docs: 补齐各模块局部回归测试的输入与断言说明

Reviewed-on: #6

Cargo.toml

@@ -1,3 +1,4 @@
+# Cargo 包元数据与编译器最低版本；二进制入口默认取 src/main.rs。
 [package]
 name = "tessera"
 version = "0.1.0"
@@ -6,24 +7,39 @@ rust-version = "1.91"
 description = "Cross-platform desktop rendering client"
 license = "MIT OR Apache-2.0"
 
+# 跨平台运行依赖：语言执行、文字排版、序列化、窗口/像素表面与轻量 HTTP 服务。
+# Aster 三个 crate 使用固定在本仓库 vendor 子模块中的本地源码，不从注册表选择同名实现。
 [dependencies]
+# 应用边界的错误聚合与上下文，保留底层失败原因。
 anyhow = "1.0"
+# Aster 字节码编译器，把前端结果交给同一套 VM 执行。
 compiler = { path = "vendor/aster/crates/compiler" }
+# 系统字体发现、塑形与换行，用于测量和软件文字绘制。
 cosmic-text = "0.19"
+# Aster 托管对象、类型系统、VM 和可恢复调用；依赖包名 core 在 Rust 中重命名为 endor_core。
 endor_core = { package = "core", path = "vendor/aster/crates/core" }
+# Endor 源语法解析与原始位置诊断。
 frontend = { path = "vendor/aster/crates/frontend" }
+# 派生序列化协议，rc 特性允许发布模型中的 Arc/Rc 数据参与序列化。
 serde = { version = "1.0", features = ["derive", "rc"] }
+# HTTP 请求/响应与事件信封的 JSON 编解码。
 serde_json = "1.0"
+# 把宿主软件光栅化得到的像素缓冲呈现到原生窗口。
 softbuffer = "0.4.8"
+# 本地 Agent API 的 HTTP 监听与请求响应，不引入异步 Web 运行时。
 tiny_http = "0.12"
+# 按 Unicode 字素边界处理编辑/选择，避免把组合字符拆开。
 unicode-segmentation = "1.12"
+# 跨平台窗口、事件循环、DPI 与输入法事件。
 winit = "0.30.13"
 
+# 仅 macOS 编译原生标题栏适配，显式开启所用 AppKit/Foundation API，其他平台不引入这些依赖。
 [target.'cfg(target_os = "macos")'.dependencies]
 objc2 = "0.5.2"
 objc2-app-kit = { version = "0.2.2", default-features = false, features = ["NSApplication", "NSButton", "NSEvent", "NSView", "NSWindow"] }
 objc2-foundation = { version = "0.2.2", default-features = false, features = ["NSGeometry", "NSString", "NSUserDefaults"] }
 
+# 发布构建：thin LTO 与单代码生成单元偏重最终优化，strip 去除可执行文件符号以控制体积。
 [profile.release]
 lto = "thin"
 codegen-units = 1

docs/code-comments.md

@@ -1,6 +1,6 @@
 # Tessera 中文源码注释与阅读索引
 
-本轮只为 Tessera 主项目补充注释，Aster 子模块固定版本与内容均沿用主线。注释按模块职责、类型/函数入口、关键字段、执行阶段和失败/取消路径组织；没有改变接口、算法、常量或资源预算。
+本轮进一步细化 Tessera 自有代码的中文注释：覆盖所有 Rust 模块、运行时/API 测试、内置起始页、45 个 Endor 示例、Cargo 依赖配置及两个工具脚本。说明聚焦具体输入/输出、状态归属、计算步骤、依赖观察、取消/失败路径和资源预算；不修改接口、算法、常量或非注释程序文本。Aster 是独立维护的 vendor 子模块，其固定版本与内容沿用主线。
 
 ## 建议阅读顺序
 
@@ -24,7 +24,7 @@
 
 ## Rust 逐文件说明
 
-每行说明该文件本次新增注释解释的职责和目的。生产函数/方法均增加中文入口说明；复杂状态机另外补充阶段和不变量说明。集成测试文件增加整体阅读与检查点说明，测试程序文本和源码范围断言保持原样。
+每行说明该文件本次深化注释的职责和目的。生产函数/方法的入口说明与内部关键逻辑互相补充；VM 可调用适配器说明实际参数约定，而非仅重复 trait 名称。集成测试中的每个顶层测试/辅助函数都有具体场景和断言说明，测试程序字符串与断言保持原样。
 
 | 文件 | 注释解释的职责与目的 |
 | --- | --- |
@@ -73,7 +73,7 @@
 | [src/runtime/api/tests.rs](../src/runtime/api/tests.rs) | API 集成回归。通过实际本地 HTTP 请求检查队列、候选替换、状态码、版本和完整文档发布。 |
 | [src/runtime/api/worker.rs](../src/runtime/api/worker.rs) | 唯一串行执行 VM 的 API worker。保留活跃运行时，另建 PUT 候选，并在候选完整成功后切换发布。 |
 | [src/runtime/endor_host.rs](../src/runtime/endor_host.rs) | 把 Aster 编译/执行与 Tessera 展示生命周期连接起来。Candidate 拥有 VM 与宿主根，ReplSession 保留实际运行中的全局环境。 |
-| [src/runtime/endor_host/tests.rs](../src/runtime/endor_host/tests.rs) | 运行时集成回归与示例验收。测试经真实 Aster 前端、编译器、VM 和展示协议执行，不是手工伪造布局结果。 |
+| [src/runtime/endor_host/tests.rs](../src/runtime/endor_host/tests.rs) | 说明全部运行时测试和辅助函数的场景/断言，并解释新主线性能基准的 DPI 分组、预热、三类计时边界和统计方式。 |
 | [src/runtime/endor_script.rs](../src/runtime/endor_script.rs) | 区分完整 Module 与顶层 Script，并保留输入源码位置。 |
 | [src/runtime/event_dispatch.rs](../src/runtime/event_dispatch.rs) | 托管事件与订阅的传播实现。Connection 持有回调引用，Event 保存目标、阶段与停止传播状态。 |
 | [src/runtime/events.rs](../src/runtime/events.rs) | 原生窗口输入到执行 worker 的纯数据传输。Input 只含窗口/会话/版本/Mount 身份及有限坐标。 |
@@ -106,11 +106,68 @@
 | 文件 | 本次改动及目的 |
 | --- | --- |
 | [src/bridge/ui_bridge/start_page.endor](../src/bridge/ui_bridge/start_page.endor) | 解释卡片源测量/背景、页面工厂、纵横布局与滚动组合、共享计数和场景位置，便于从真实 Endor 页面理解宿主边界。 |
-| [scripts/build-macos-app.sh](../scripts/build-macos-app.sh) | 说明本地构建前提、锁定依赖、临时文件替换和 bundle 元数据，帮助理解每个打包步骤。 |
+| [scripts/build-macos-app.sh](../scripts/build-macos-app.sh) | 说明 macOS 构建环境前提、失败退出、锁定依赖、临时文件替换和 bundle 元数据，帮助理解每个打包步骤。 |
 | [scripts/render-uml.mjs](../scripts/render-uml.mjs) | 说明独立文档依赖、DOM/Canvas 适配、错误图检查与 SVG/PNG 产物生成，避免混淆运行依赖与文档工具。 |
-| [src/README.md](../src/README.md) | 增加本注释索引入口，便于从源码目录开始阅读。 |
-| [docs/code-comments.md](code-comments.md) | 本逐文件说明与阅读顺序，覆盖本轮提交的文件及共同边界。 |
+| [Cargo.toml](../Cargo.toml) | 解释每个依赖负责的能力、Aster 本地路径依赖、macOS 条件依赖与 release 优化配置。 |
+| [docs/code-comments.md](code-comments.md) | 更新本逐文件说明、示例索引和实际核对方式，使本次注释范围与可验证结果对应。 |
 
-## 核对方式
+## Endor 示例逐文件说明
 
-检查差异仅新增独立注释行和注释相关空白，并与主线去除注释后的文本对比；同时运行格式、完整 GUI 回归、Clippy 和包含私有项的 rustdoc。脚本使用语法检查，不执行文档渲染或应用打包。具体检查结果在 PR 中记录。
+每个示例的类、方法及关键逻辑旁增加中文说明。`page.endor` 和 `hello.endor` 被测试固定断言源码行号，因此使用行尾注释，保留原始行数；其余示例使用独立注释行，程序符号与字面量不变。
+
+| 文件 | 注释解释的场景与目的 |
+| --- | --- |
+| [examples/async-file.endor](../examples/async-file.endor) | 异步 UTF-8 文件读取：在 Console 调用 reader.read(绝对路径)，后台 provider 只交付文本，VM worker 执行业务回调。 |
+| [examples/async-network.endor](../examples/async-network.endor) | 异步 HTTP(S) 文本 GET：Console 调用 fetcher.fetch(url)，沿用 owner/key 替换、状态与成功回调协议。 |
+| [examples/await-file.endor](../examples/await-file.endor) | 把 callback-free 文件 Task 与 ui.spawn 协作函数组合：await 保存执行位置，等待完成后继续，不阻塞 VM worker。 |
+| [examples/box-layout.endor](../examples/box-layout.endor) | 盒模型组合：容器与 Page/相机独立，border-box 尺寸、padding、margin 和对齐分别参与布局。 |
+| [examples/campus-lms.endor](../examples/campus-lms.endor) | 多页面校园演示：七个普通托管 Page 共享 CampusCourse/CampusWork 业务对象，所有课程与学生数据均虚构。 |
+| [examples/classes.endor](../examples/classes.endor) | 普通源类继承示例：GUI 点击执行继承的 activate，内部 self.change 再动态分派到 DemoCounter 覆盖。 |
+| [examples/constructor-contracts.endor](../examples/constructor-contracts.endor) | 构造器分段示例：原生可选参数/可变子项与源子类新增字段分别验证。 |
+| [examples/cooperative-tasks.endor](../examples/cooperative-tasks.endor) | 协作任务示例：两个 ui.spawn 各自保留执行帧，worker 按指令量子轮转推进。 |
+| [examples/events.endor](../examples/events.endor) | 同一托管对象系统中的事件阶段：祖先 capture → 目标 onEvent → 目标监听器 → 祖先 bubble。 |
+| [examples/exit-lifecycle.endor](../examples/exit-lifecycle.endor) | 正常退出与多窗口卸载示例：同一 ExitText 出现在两窗，onUnmount 按出现位置分别调用。 |
+| [examples/field-contracts.endor](../examples/field-contracts.endor) | 字段类型契约示例：CounterText 同时有原生文本载荷和源 Number 字段。 |
+| [examples/flex-constraints.endor](../examples/flex-constraints.endor) | flexBasis/flexMin/flexMax/flexShrink 约束同一主轴分配。 |
+| [examples/flex.endor](../examples/flex.endor) | 按 flex 权重分配有限主轴空间：固定项先占自然尺寸，剩余空间按正权重划分。 |
+| [examples/fonts.endor](../examples/fonts.endor) | 字体测量示例：中英文混排、重音字符和不同字宽均走系统字体塑形与回退。 |
+| [examples/function-types.endor](../examples/function-types.endor) | Function 与 Type 的契约示例：源函数、原生函数与绑定方法都可作为函数值，类型构造器保持 Type 身份。 |
+| [examples/gc-lifecycle.endor](../examples/gc-lifecycle.endor) | 托管对象循环与等待帧回收：先记 ui.stats().objects，再调用 mountCycle，观察 phase 与 pending.value.status()。 |
+| [examples/global-dependencies.endor](../examples/global-dependencies.endor) | 全局名称依赖示例：paint 读取 color 这个具体名字，而非依赖整个 globals 字典版本。 |
+| [examples/hello.endor](../examples/hello.endor) | 解释辅助 heading、兼容 main 入口、局部业务引用和原生布局，保留源码位置夹具。 |
+| [examples/layout-cache.endor](../examples/layout-cache.endor) | 测量与绘制依赖分离：改颜色应复用尺寸缓存，改模型宽度才需要重新测量。 |
+| [examples/layout-negotiation.endor](../examples/layout-negotiation.endor) | 测量/排列协商示例：arrange 指定子宽后需重新换行测量，高度变化继续影响父容器和后继位置，直到整树稳定。 |
+| [examples/main.endor](../examples/main.endor) | 与 page.endor 等价的 main 返回根入口：用于对比顶层显式 render 和兼容模块入口的绘图结果。 |
+| [examples/managed-types.endor](../examples/managed-types.endor) | 托管名义类型入门：ui 构造器与 TextBlock/Button/Page 返回同一套 VM 托管对象。 |
+| [examples/method-contracts.endor](../examples/method-contracts.endor) | 方法覆盖遵守参数可更宽、返回可更具体的规则。 |
+| [examples/mount-lifecycle.endor](../examples/mount-lifecycle.endor) | 业务对象与出现位置生命周期分离：同一 child 在根中出现两次，每次都获得独立 Mount 和通知。 |
+| [examples/native-signatures.endor](../examples/native-signatures.endor) | 原生回调也发布 Function 签名：state.set 接收一个 Event，increment 接收零参数。 |
+| [examples/native-subclasses.endor](../examples/native-subclasses.endor) | 源类继承原生视觉类型：原生载荷负责基础绘制，新增字段和覆盖方法由源类提供。 |
+| [examples/owned-tasks.endor](../examples/owned-tasks.endor) | owner 作用域决定取消时机：Page 关闭会取消其任务，隐藏 Block 和 ui 的任务可继续。 |
+| [examples/page.endor](../examples/page.endor) | 解释顶层脚本创建文字/矩形、Page 与 render 的关系，保留四行结构树夹具。 |
+| [examples/presentable.endor](../examples/presentable.endor) | 普通业务对象显式实现 Presentable 后，ui.present 可调用其 present(window) 生成视觉对象。 |
+| [examples/property-bindings.endor](../examples/property-bindings.endor) | 通用属性绑定：业务 Model 的三个零参只读方法分别计算 rect.width、rect.color 和 label.text。 |
+| [examples/scene-viewports.endor](../examples/scene-viewports.endor) | 一个二维世界可被多个有限视口观察，Scene2D 的对象位置共享，默认 Camera2D 各自独立。 |
+| [examples/scene3d.endor](../examples/scene3d.endor) | 同一 Scene3D 在透视/正交视口中展示；相机控制独立，网格业务变换由两边共享。 |
+| [examples/scroll-axis.endor](../examples/scroll-axis.endor) | 滚动轴策略影响可滚动方向与内容测量约束：vertical 限宽并允许长高，horizontal 允许横向展开。 |
+| [examples/scroll.endor](../examples/scroll.endor) | 同一 ScrollBlock 在两个原生窗口中展示：内容业务对象共享，滚动偏移按 Mount 独立保存。 |
+| [examples/source-hit.endor](../examples/source-hit.endor) | 自定义形状命中：对象原始矩形宽 160，但 paint 只画左侧直径 80 的圆，hitTest 也只接受圆内。 |
+| [examples/source-layout.endor](../examples/source-layout.endor) | 源视觉协议的最小组合：measure 决定尺寸，arrange 决定子项位置，Metrics 是被两者读取的业务模型。 |
+| [examples/source-paint.endor](../examples/source-paint.endor) | 源 paint 产出真正进入窗口的 DisplayList；允许构造并修改本次计算的新命令，禁止改已有业务对象。 |
+| [examples/student-grades.endor](../examples/student-grades.endor) | 学生成绩中心为纯内存演示，记录均虚构，不连接学校数据库。 |
+| [examples/tab-placement.endor](../examples/tab-placement.endor) | 页面位置与子项插入的代码示例：Page 方法覆盖计数，Container.insert 在指定位置创建稳定子槽。 |
+| [examples/tabs.endor](../examples/tabs.endor) | 代码与原生侧栏都操作真实 Page 对象；activate/close/open 改变展示关系，业务对象可继续被全局引用保留。 |
+| [examples/visual-protocols.endor](../examples/visual-protocols.endor) | 原生视觉协议直接返回托管数据：Constraints/MeasureResult、Bounds/Arrangement 和 DisplayList 都可在源码中查询。 |
+| [examples/window.endor](../examples/window.endor) | 托管 Window 资源与原生窗口相连：源码排出 resize/title 命令，成功刷新后由 GUI 线程执行。 |
+| [examples/windows.endor](../examples/windows.endor) | 两个原生窗口共用一个 Aster VM 和 count 业务对象，各自拥有独立 Page 与 Mount。 |
+| [examples/workspace.endor](../examples/workspace.endor) | 静态工作台组合示例：所有指标、进度与活动记录均为演示数据，不读取任务系统或网络。 |
+| [examples/world-ui.endor](../examples/world-ui.endor) | 世界空间 UI：普通 Endor 树先在独立 UI 分辨率中布局/绘制，再作为 Panel3D 平面的纹理参与三维深度。 |
+| [examples/wrapped-text.endor](../examples/wrapped-text.endor) | 多窗口共享长段落：同一文字对象在每个 Mount 按当前宽度独立换行，后继位置跟随实际高度。 |
+
+## 核对方式与边界
+
+- 与本次分支起点及最新主线比较，逐文件核对移除注释后的文本；Rust/Endor 另做词法扫描，完整保留字符串/原始字符串内容，确认新增说明没有进入程序字面量。
+- 使用 rustfmt 的 `--emit stdout`、`skip_children=true` 逐文件做 Rust 语法解析，丢弃输出，不格式化文件、不运行 Cargo、不生成编译产物。
+- 对工具脚本使用 `node --check` 和 `sh -n`，只检查语法，不执行渲染、构建或打包；Cargo 配置另以 TOML 解析核对。
+- 检查固定行号的示例夹具、测试依赖的源码替换片段和 `git diff --check`。这些检查能证明注释外代码保持一致及语法可解析，不能替代运行时回归结果。
+- 本次未执行编译、GUI 回归、Clippy 或 rustdoc；需要构建的验证应在用户已确认的远程 runner 上运行，不能把未执行步骤写成通过。实际交付结果记录在 PR 中。

examples/async-file.endor

@@ -1,18 +1,25 @@
+// 异步 UTF-8 文件读取：在 Console 调用 reader.read(绝对路径)，后台 provider 只交付文本，VM worker 执行业务回调。
+// owner/key 相同的新读取替换旧任务；失败只记录 Task.error，不执行 apply。
+// 持有三个显示对象与当前任务；task 初值占位，第一次 read 后替换为真实 Task。
 class FileReader {
     output: TextBlock
     problem: TextBlock
     status: TextBlock
     task: Object
+    // 仅成功时调用，result 在成功回调期间已可读；写原 TextBlock 触发显示刷新。
     function apply(self: FileReader): Unit {
         self.output.text = self.task.result()
     }
+    // 以 self 为 owner、file 为 key 启动读取，清空旧输出，并把状态/错误文字绑定到当前任务。
     function read(self: FileReader, path: String): Unit {
         self.task = ui.readText(self, "file", path, self.apply)
         self.output.text = ""
+        // Task.status/error 是零参数只读方法，可直接作为绑定计算；换任务后绑定也随本次调用更新。
         self.status.bind("text", self.task.status)
         self.problem.bind("text", self.task.error)
     }
 }
+// 先建立界面对象，保持 reader 为可从 Console 操作的全局业务入口。
 output = TextBlock("尚未读取文件")
 problem = TextBlock("")
 status = TextBlock("")

examples/async-network.endor

@@ -1,21 +1,28 @@
+// 异步 HTTP(S) 文本 GET：Console 调用 fetcher.fetch(url)，沿用 owner/key 替换、状态与成功回调协议。
+// 完整响应保存为 String，界面只显示完成提示，避免把可能很大的响应放进文字控件。
+// response 是结果业务存储；output/problem/status 仅呈现任务进度与提示。
 class TextFetcher {
     output: TextBlock
     problem: TextBlock
     status: TextBlock
     task: Object
     response: String
+    // 成功后取出完整 UTF-8 结果，写 response 供 Console 查询；provider 失败不会进入此方法。
     function apply(self: TextFetcher): Unit {
         self.response = self.task.result()
         self.output.text = "请求完成；在 REPL 查看 fetcher.response"
     }
+    // 同一 self/request 身份的新请求取消旧交付，重置旧内容并把显示绑定到新任务。
     function fetch(self: TextFetcher, url: String): Unit {
         self.task = ui.fetchText(self, "request", url, self.apply)
         self.response = ""
         self.output.text = ""
+        // 绑定读取当前 Task 方法，完成和失败由 worker 的任务状态变更传播。
         self.status.bind("text", self.task.status)
         self.problem.bind("text", self.task.error)
     }
 }
+// 界面不自动访问网络，用户以 Console 明确指定 URL 后才创建任务。
 output = TextBlock("尚未请求网络")
 problem = TextBlock("")
 status = TextBlock("")

examples/await-file.endor

@@ -1,24 +1,31 @@
+// 把 callback-free 文件 Task 与 ui.spawn 协作函数组合：await 保存执行位置，等待完成后继续，不阻塞 VM worker。
+// readText 的 file 与 spawn 的 workflow 使用不同 key，分别管理读取和等待流程。
+// 保存 provider Task、协程 Task 和结果；两种任务都是托管对象，可以从 Console 独立查看。
 class AwaitReader {
     output: TextBlock
     status: TextBlock
     task: Object
     file: Object
     response: String
+    // await 在文件未完成时挂起并保留 self/操作数；恢复后只执行后半段一次，再把字符串作为 workflow.result。
     function apply(self: AwaitReader): String {
         self.response = await self.file
         self.output.text = "读取完成；在 REPL 查看 reader.response 或 reader.task.result()"
         return self.response
     }
+    // 先创建读任务，再调度普通函数 apply；spawn 而非新 async 语法提供可暂停执行上下文。
     function read(self: AwaitReader, path: String): Unit {
         self.file = ui.readText(self, "file", path)
         self.task = ui.spawn(self, "workflow", self.apply)
         self.response = ""
         self.output.text = "等待文件"
+        // 显示的是 workflow 状态，等待 provider 时它仍报告 running；结束后 result 可从 Task 或 response 读取。
         self.status.bind("text", self.task.status)
     }
 }
 output = TextBlock("在 REPL 调用 reader.read(绝对路径字符串)")
 status = TextBlock("")
+// 占位值只用于满足初始字段构造；在 read 内被真实 Task 替换，页面建立不自动读文件。
 reader = AwaitReader(output,status,ui.state(0),ui.state(0),"")
 page = Page()
 page.title = "await 文件"

examples/box-layout.endor

@@ -1,8 +1,12 @@
-// Containers compose independently of Page and of any camera.
+// 盒模型组合：容器与 Page/相机独立，border-box 尺寸、padding、margin 和对齐分别参与布局。
+// 同一文字共享内容，在左右不同有限分配中各自换行；外层 Overlay 负责叠放固定角标并裁剪溢出。
+// 内部布局基于容器自己的约束；Page 和相机只提供外部展示/投影上下文。
+// 文字 boxWidth=fill 占父分配的可用宽度，marginBottom 在文字边框盒外参与排布。
 shared = TextBlock("同一个对象可以有多个 Mount。每个位置分别测量、换行和对齐。", 2)
 shared.boxWidth = "fill"
 shared.marginBottom = 8
 
+// 左 Column 使用 fill、min/max 宽度限制和四边边框；非对称 paddingLeft 覆盖统一 padding。
 left = Column(16, 12, TextBlock("Row / Column", 2), shared, Button("继续探索"))
 left.boxWidth = "fill"
 left.minWidth = 180
@@ -15,24 +19,29 @@ left.borderColor = "#CBD5E1"
 left.paddingLeft = 24
 left.crossAlign = "center"
 
+// 右 Column 也引用同一 shared，但最大宽只有 240，因此对应 Mount 的换行高度可以不同。
 right = Column(16, 12, TextBlock("共享内容，独立排版", 2), shared)
 right.boxWidth = "fill"
 right.maxWidth = 240
 right.crossAlign = "end"
 
+// Row 分配有限 760 主轴空间，扣 padding/gap 后在两侧 fill 子项之间分配并服从上限。
 content = Row(24, 24, left, right)
 content.boxWidth = 760
 content.crossAlign = "start"
+// 角标是 Overlay 的另一子项，alignSelf 与 margin 控制它在容器交叉轴上的位置。
 badge = TextBlock("Endorphin · layout")
 badge.marginRight = 12
 badge.marginBottom = 12
 badge.alignSelf = "end"
+// 固定 800x400 的 Overlay 不按线性顺序挤开兄弟，overflow=clip 同时约束绘制和命中。
 surface = Overlay(0, 0, content, badge)
 surface.boxWidth = 800
 surface.boxHeight = 400
 surface.mainAlign = "end"
 surface.overflow = "clip"
 
+// Page 只提供展示入口，根容器自身的盒模型规则不依赖页面导航方式。
 page = Page()
 page.title = "嵌套盒模型"
 page.render(surface)

examples/campus-lms.endor

@@ -1,7 +1,9 @@
-// Endor Campus — a multi-page learning environment inspired by Canvas LMS.
-// Fictional student/course data. Paste the complete source into Console and Enter.
-// All seven tabs are ordinary managed Pages. There is no server or Canvas login.
+// 多页面校园演示：七个普通托管 Page 共享 CampusCourse/CampusWork 业务对象，所有课程与学生数据均虚构。
+// 无服务器、账号登录或真实上传；提交/评分按钮只应用预设字段值，其他页通过绑定读同一状态。
+// 作为一次完整输入提交；七页共用同一VM，会话重置后数据消失。
+// 白色圆角卡片容器，继承 Column 的排版，只覆盖自身背景绘制。
 class CampusPanel: Column {
+    // 按当前出现位置 geometry 创建一条背景命令，子项由展示遍历继续绘制。
     function paint(self: CampusPanel, mount: Mount, geometry: Bounds): DisplayList {
         fill = PaintCommand()
         fill.kind = "roundedRect"
@@ -14,18 +16,23 @@ class CampusPanel: Column {
         return DisplayList(ObjectList(fill))
     }
 }
+// 通过额外 width 字段固定表格列的期望宽，保持成绩表头和行对齐。
 class CampusCell: Column {
     width: Number
+    // 先算子内容自然高度，再改新测量结果宽度，保留真实字体引起的高度。
     function measure(self: CampusCell, mount: Mount, constraints: Constraints): MeasureResult {
         result = Column.measure(self, mount, constraints)
         result.width = self.width
         return result
     }
 }
+// 页面内容里的演示导航栏，与应用自身的原生页面侧栏是两棵不同控件树。
 class CampusSidebar: Column {
+    // 返回固定168x620期望尺寸，外层 ScrollBlock 承担超出区域的滚动。
     function measure(self: CampusSidebar, mount: Mount, constraints: Constraints): MeasureResult {
         return MeasureResult(168, 620)
     }
+    // 为导航区创建深红背景，位置/大小来自当前Mount，文字等子项保持独立命令。
     function paint(self: CampusSidebar, mount: Mount, geometry: Bounds): DisplayList {
         fill = PaintCommand()
         fill.kind = "roundedRect"
@@ -38,11 +45,14 @@ class CampusSidebar: Column {
         return DisplayList(ObjectList(fill))
     }
 }
+// Button 子类增加背景字段，固定导航按钮尺寸，并保留原生事件目标能力。
 class CampusNav: Button {
     background: String
+    // 导航按钮期望144x40，确保四个入口宽高一致。
     function measure(self: CampusNav, mount: Mount, constraints: Constraints): MeasureResult {
         return MeasureResult(144, 40)
     }
+    // 取原生按钮背景命令改色/圆角；文字由后面 replace 后的子项绘制，不在此重复生成。
     function paint(self: CampusNav, mount: Mount, geometry: Bounds): DisplayList {
         fill = Button.paint(self, mount, geometry).commands.at(0)
         fill.color = self.background
@@ -50,6 +60,7 @@ class CampusNav: Button {
         return DisplayList(ObjectList(fill))
     }
 }
+// 课程业务记录，grade/progress 被多个页面绑定读取，其余静态字段构建时直接读取。
 class CampusCourse {
     title: String
     code: String
@@ -57,6 +68,7 @@ class CampusCourse {
     grade: String
     progress: String
 }
+// 实验状态集中在一个对象，course 指向同一课程模型，评分因此能影响全站课程摘要。
 class CampusWork {
     status: String
     score: String
@@ -65,12 +77,14 @@ class CampusWork {
     todo: String
     result: String
     course: CampusCourse
+    // 模拟提交只改状态、文件名提示、待办和结果文字，不访问磁盘或网络。
     function submit(self: CampusWork, event: Event): Unit {
         self.status = "已提交 · 等待评分"
         self.submission = "lab01.endor · 已提交示例内容"
         self.todo = "已完成本次实验提交"
         self.result = "示例提交成功，可以切到作业中心查看同一条记录。"
     }
+    // 应用预设92分和反馈，并更新所属课程成绩/进度；绑定让仪表盘、课程、成绩页同步观察。
     function assess(self: CampusWork, event: Event): Unit {
         self.status = "已评分"
         self.score = "92 / 100"
@@ -81,6 +95,7 @@ class CampusWork {
         self.course.progress = "已完成 4 / 6 个学习单元"
         self.result = "已应用预设评分；仪表盘、课程主页和成绩总览同步更新。"
     }
+    // 恢复初始实验与课程状态，保留所有原对象和绑定，便于反复演示。
     function reset(self: CampusWork, event: Event): Unit {
         self.status = "未提交"
         self.score = "— / 100"
@@ -92,20 +107,25 @@ class CampusWork {
         self.result = "已恢复实验、课程成绩和学习进度的示例状态。"
     }
 }
+// 用统一包装构造表格单元格；传入的content是已有Block引用。
 function campusCell(content: Block, width: Number): Block {
     return CampusCell(0, 0, content, width)
 }
+// 显式事件适配器把click的Event与Page.open可选Window参数分开，不能直接把Event误当窗口。
 class CampusTarget {
     page: Page
-    // Consume the click Event here; Page.open's optional argument is a Window.
+    // 事件参数在适配器这一层消化，Page.open 只接收其声明的可选 Window。
+    // 消费事件但不传给Page.open；无参open表示在合适窗口打开/激活目标页。
     function open(self: CampusTarget, event: Event): Unit { self.page.open() }
 }
+// 为普通按钮创建持有目标Page的适配器，并把其绑定方法注册为click回调。
 function campusLink(label: String, target: Page): Button {
     button = Button(label)
     action = CampusTarget(target)
     button.on("click", action.open)
     return button
 }
+// 构造带指定背景的导航按钮，替换原生文字子槽为白字，然后复用事件适配器连接目标页。
 function campusNav(label: String, target: Page, background: String): Button {
     button = CampusNav(label, background)
     button.replace(0, TextBlock(label, 1, "#FFFFFF"))
@@ -113,6 +133,7 @@ function campusNav(label: String, target: Page, background: String): Button {
     button.on("click", action.open)
     return button
 }
+// 用目标Page和四个色调参数构建整块导航；不同页面复用目标资源但用不同高亮背景。
 function campusNavigation(home: Page, course: Page, assignments: Page, grades: Page, homeTone: String, courseTone: String, workTone: String, gradeTone: String): Block {
     return CampusSidebar(12, 10,
         TextBlock("Endor", 2, "#FFFFFF"),
@@ -125,6 +146,7 @@ function campusNavigation(home: Page, course: Page, assignments: Page, grades: P
         TextBlock("2026 秋季学期", 1, "#E7BAC0"),
         TextBlock("本地演示", 1, "#E7BAC0"))
 }
+// 把演示导航与标题/正文横排，外层有限ScrollBlock启用双轴，容纳固定宽度演示内容。
 function campusShell(navigation: Block, title: String, subtitle: String, body: Block): Block {
     scroll = ScrollBlock(1120, 680,
         Row(24, 28, navigation,
@@ -135,6 +157,7 @@ function campusShell(navigation: Block, title: String, subtitle: String, body: B
     scroll.axis = "both"
     return scroll
 }
+// 卡片静态显示课程代码/标题/教师，grade 用绑定随评分变化，入口按钮引用真实课程Page。
 function campusCourseCard(course: CampusCourse, page: Page, color: String): Block {
     return CampusPanel(0, 0,
         RectBlock(248, 44, 8, color),
@@ -145,6 +168,7 @@ function campusCourseCard(course: CampusCourse, page: Page, color: String): Bloc
             ui.textOf(course, "grade", 2, color),
             campusLink("进入课程", page)))
 }
+// 成绩表一行复用固定列宽单元格，当前grade为响应式文字，详情链接指向指定课程页。
 function campusGradeRow(course: CampusCourse, target: Page): Block {
     return Column(0, 12,
         Row(0, 0,
@@ -154,6 +178,7 @@ function campusGradeRow(course: CampusCourse, target: Page): Block {
             campusLink("课程详情", target)),
         RectBlock(752, 1, 0, "#EDF0F3"))
 }
+// 组合课程概况/进度和静态学习单元；上方两个链接复用作业/成绩Page，不创建新页面。
 function campusCourseBody(course: CampusCourse, intro: String, moduleOne: String, moduleTwo: String, moduleThree: String, assignments: Page, grades: Page): Block {
     return Column(0, 20,
         Row(0, 16, campusLink("作业与提交", assignments), campusLink("查看成绩", grades)),
@@ -171,11 +196,13 @@ function campusCourseBody(course: CampusCourse, intro: String, moduleOne: String
             RectBlock(752, 1, 0, "#EDF0F3"),
             TextBlock(moduleThree, 1, "#526372")))
 }
-// The shared object graph is created once; each Page projects those same objects.
+// 共享对象图只构造一次，各Page的文字绑定投影同一业务字段。
+// 只创建三份课程模型和一份实验模型，后续各页读取这些对象，避免页面间状态副本不一致。
 campusProgramming = CampusCourse("计算机程序设计", "CS 101", "陈老师 · 周二 / 周四", "86.0%", "已完成 3 / 6 个学习单元")
 campusMathematics = CampusCourse("高等数学 I", "MATH 101", "周老师 · 周一 / 周三", "91.0%", "已完成 4 / 6 个学习单元")
 campusEnglish = CampusCourse("学术英语", "ENG 102", "许老师 · 周五", "89.0%", "已完成 3 / 5 个学习单元")
 campusWork = CampusWork("未提交", "— / 100", "提交后可在此查看教师反馈。", "尚无提交内容", "1 项实验待提交", "这是一个本地提交与评分演示。", campusProgramming)
+// 先创建全部七个Page，允许导航按钮互相引用；随后逐一render建立内容。
 campusDashboard = Page()
 campusDashboard.title = "Campus · 仪表盘"
 campusProgrammingPage = Page()
@@ -190,10 +217,12 @@ campusGrades = Page()
 campusGrades.title = "Campus · 成绩总览"
 campusWorkPage = Page()
 campusWorkPage.title = "实验 01 · 提交详情"
+// 预建四种高亮导航树，课程三页共享course导航，Page切换时各自拥有独立Mount。
 campusHomeNav = campusNavigation(campusDashboard, campusProgrammingPage, campusAssignments, campusGrades, "#A64350", "#852B38", "#852B38", "#852B38")
 campusCourseNav = campusNavigation(campusDashboard, campusProgrammingPage, campusAssignments, campusGrades, "#852B38", "#A64350", "#852B38", "#852B38")
 campusAssignmentNav = campusNavigation(campusDashboard, campusProgrammingPage, campusAssignments, campusGrades, "#852B38", "#852B38", "#A64350", "#852B38")
 campusGradeNav = campusNavigation(campusDashboard, campusProgrammingPage, campusAssignments, campusGrades, "#852B38", "#852B38", "#852B38", "#A64350")
+// 仪表盘展示课程卡和当前实验摘要，status/todo均从同一campusWork绑定读取。
 campusDashboard.render(campusShell(campusHomeNav, "仪表盘", "林沐，欢迎回来。这里是你的课程与近期学习安排。",
     Column(0, 20,
         Row(0, 16,
@@ -206,6 +235,7 @@ campusDashboard.render(campusShell(campusHomeNav, "仪表盘", "林沐，欢迎
             ui.textOf(campusWork, "todo", 1, "#7C8793"),
             campusLink("打开作业详情", campusWorkPage)),
         TextBlock("虚构课程与学生数据 · Endor 本地多页面演示", 1, "#8C959F"))))
+// 程序设计课程附加实验入口；数学和英语页复用相同概况结构但读取不同课程模型。
 campusProgrammingPage.render(campusShell(campusCourseNav, "计算机程序设计", "课程 / CS 101 / 主页",
     Column(0, 16,
         campusCourseBody(campusProgramming, "通过实际编程理解对象、函数与交互。", "01   对象与字段  ·  已完成", "02   函数与方法  ·  已完成", "03   事件与可视界面  ·  进行中", campusAssignments, campusGrades),
@@ -214,6 +244,7 @@ campusMathPage.render(campusShell(campusCourseNav, "高等数学 I", "课程 / M
     campusCourseBody(campusMathematics, "学习极限、微分与积分的基本方法。", "01   函数与极限  ·  已完成", "02   导数及其应用  ·  已完成", "03   积分方法  ·  进行中", campusAssignments, campusGrades)))
 campusEnglishPage.render(campusShell(campusCourseNav, "学术英语", "课程 / ENG 102 / 主页",
     campusCourseBody(campusEnglish, "阅读学术文本，练习清晰的论证与表达。", "01   Academic reading  ·  已完成", "02   Evidence and arguments  ·  已完成", "03   Research writing  ·  进行中", campusAssignments, campusGrades)))
+// 作业中心只有程序设计实验为共享动态模型，其余两项是固定演示文字。
 campusAssignments.render(campusShell(campusAssignmentNav, "作业中心", "本学期 / 全部课程 / 作业与提交",
     Column(0, 20,
         CampusPanel(20, 12,
@@ -227,6 +258,7 @@ campusAssignments.render(campusShell(campusAssignmentNav, "作业中心", "本
         CampusPanel(20, 12,
             TextBlock("Reading response", 1, "#263444"),
             TextBlock("ENG 102 · 已评分 · 88 / 100", 1, "#7C8793")))))
+// 成绩总览复用课程grade绑定和实验score/feedback，评分无需逐页手动写UI。
 campusGrades.render(campusShell(campusGradeNav, "成绩总览", "2026 秋季学期 / 当前课程成绩",
     Column(0, 20,
         CampusPanel(20, 16,
@@ -242,12 +274,14 @@ campusGrades.render(campusShell(campusGradeNav, "成绩总览", "2026 秋季学
             Row(0, 24, TextBlock("实验 01：对象与函数"), ui.textOf(campusWork, "score", 1, "#315E86")),
             ui.textOf(campusWork, "feedback", 1, "#6D7987"),
             campusLink("打开作业与反馈", campusWorkPage)))))
+// 三个操作按钮连接同一个实验对象的submit/assess/reset，均为真实源方法回调。
 campusSubmitButton = Button("模拟提交实验")
 campusSubmitButton.on("click", campusWork.submit)
 campusAssessButton = Button("应用示例评分")
 campusAssessButton.on("click", campusWork.assess)
 campusResetButton = Button("恢复演示数据")
 campusResetButton.on("click", campusWork.reset)
+// 详情页组合要求、提交状态、操作按钮和反馈；所有输入仍只是预设本地状态转换。
 campusWorkPage.render(campusShell(campusAssignmentNav, "实验 01：对象与函数", "CS 101 / 作业 / 提交详情",
     Column(0, 20,
         Row(0, 16, campusLink("返回课程", campusProgrammingPage), campusLink("全部作业", campusAssignments), campusLink("成绩总览", campusGrades)),
@@ -265,4 +299,5 @@ campusWorkPage.render(campusShell(campusAssignmentNav, "实验 01：对象与函
             Row(0, 24, TextBlock("成绩与反馈"), ui.textOf(campusWork, "score", 2, "#315E86")),
             ui.textOf(campusWork, "feedback", 1, "#6D7987")),
         ui.textOf(campusWork, "result", 1, "#7C8793"))))
+// 逐页render会改变当前活动页，最后显式选择仪表盘作为打开后的首页。
 campusDashboard.activate()

examples/classes.endor

@@ -1,28 +1,37 @@
+// 普通源类继承示例：GUI 点击执行继承的 activate，内部 self.change 再动态分派到 DemoCounter 覆盖。
+// 两个 textOf 共享同一模型字段，修改一次业务值会更新两个展示位置。
+// 定义业务状态和公共事件入口，Number/String 字段在构造与赋值时按声明契约检查。
 class Counter {
     value: Number
     lastEvent: String
 
+    // 保存实际事件种类，再通过 self 调用可覆盖的方法；接收者保持具体子类身份。
     function activate(self: Counter, event: Event): Unit {
         self.lastEvent = event.kind
         self.change()
     }
 
+    // 基类默认行为把值置为 10，子类可复用入口并替换这部分策略。
     function change(self: Counter): Unit {
         self.value = 10
     }
 }
 
+// 继承 Counter 的字段与 activate，仅替换 change；构造参数仍按继承字段顺序传入。
 class DemoCounter: Counter {
+    // 覆盖把值设为 12，演示从继承方法内部发起的调用也会选中实际接收者的方法。
     function change(self: DemoCounter): Unit {
         self.value = 12
     }
 }
 
+// 创建唯一模型，之后所有绑定和按钮回调都指向它，无需把 GUI 状态复制到另一份存储。
 model = DemoCounter(9, "等待点击")
 first = ui.textOf(model, "value", 2)
 second = ui.textOf(model, "value", 2)
 eventName = ui.textOf(model, "lastEvent")
 button = Button("调用继承方法，再分派到覆盖方法")
+// 注册绑定方法，运行时将 click 的 Event 传给 activate；最后 Page.render 才把对象树显示出来。
 button.onClick(model.activate)
 page = Page()
 page.render(Column(24, 16, TextBlock("Endor class：继承、self 与动态方法分派", 2), Row(0, 16, first, second), button, eventName))

examples/constructor-contracts.endor

@@ -1,11 +1,20 @@
+// 构造器分段示例：原生可选参数/可变子项与源子类新增字段分别验证。
+// 省略 RectBlock 的 radius/color 不应使字符串 tag 被错当成原生颜色参数。
+// 在原生矩形后增加 tag 字段；位置构造仍保留 width/height 及可选圆角/颜色规则。
 class TaggedRect: RectBlock { tag: String }
+// 在可变数量 Block 子项之后接收源 tag，子项列表与字段不混用。
 class TaggedColumn: Column { tag: String }
+// 保留原生事件 kind，再追加业务字符串字段。
 class TaggedEvent: Event { tag: String }
+// 原生列表成员之后追加 tag，列表元素仍可保存不同托管类型。
 class TaggedList: ObjectList { tag: String }
+// 将需要更新的矩形作为强业务引用保存，按钮回调只修改它的颜色。
 class Actions {
     rect: TaggedRect
+    // 写原对象的 color，挂载显示由依赖跟踪刷新，不需要重新构造整个页面。
     function recolor(self: Actions): Unit { self.rect.color = "#237A45" }
 }
+// 这里刻意省略原生可选项，用末尾字符串初始化子类字段；后面的列表/Column 做对应可变参数演示。
 rect = TaggedRect(180, 60, "省略 radius/color 后的字段")
 event = TaggedEvent("click", "事件字段")
 items = TaggedList(rect, event, "列表成员之后的字段")

examples/cooperative-tasks.endor

@@ -1,5 +1,10 @@
+// 协作任务示例：两个 ui.spawn 各自保留执行帧，worker 按指令量子轮转推进。
+// 这里刻意重复增量语句，方便看到暂停点；取消不回滚已经发生的 steps 写入，单个原生调用仍是原子边界。
+// 每个实例有独立 steps 状态，两个任务不会把局部帧或计数存储混在一起。
 class CooperativeWork {
     steps: Object
+    // 普通零参数方法被 spawn 调度后可跨量子继续；每条 increment 更新同一实例的计数。
+    // 连续语句无需手工 yield，VM 按累计预算暂停，恢复时不会从第一条重放。
     function run(self: CooperativeWork): Unit {
         self.steps.increment()
         self.steps.increment()
@@ -67,10 +72,12 @@ class CooperativeWork {
         self.steps.increment()
     }
 }
+// 创建两个独立 owner，虽然 key 都叫 work，也不会相互替换；owner/key 组合才是任务身份。
 left = CooperativeWork(ui.state(0))
 right = CooperativeWork(ui.state(0))
 leftTask = ui.spawn(left,"work",left.run)
 rightTask = ui.spawn(right,"work",right.run)
+// 状态文字绑定到 Task.status，业务进度可在 Console 查询 left/right 的 steps.value。
 leftStatus = TextBlock("")
 rightStatus = TextBlock("")
 leftStatus.bind("text",leftTask.status)

examples/events.endor

@@ -1,3 +1,6 @@
+// 同一托管对象系统中的事件阶段：祖先 capture → 目标 onEvent → 目标监听器 → 祖先 bubble。
+// EventLog 用一个递增序列记录实际次序；改变监听器/传播标记可对比跳过与停止的语义。
+// 保存各阶段序号与最近 phase；count 是共享状态，其他字段直接写在本模型中。
 class EventLog {
     count: Object
     captureStep: Number
@@ -5,24 +8,29 @@ class EventLog {
     targetStep: Number
     bubbleStep: Number
     phase: String
+    // 祖先捕获阶段先递增序列，再保存 captureStep 和 Event.phase。
     function capture(self: EventLog, event: Event): Unit {
         self.count.increment()
         self.captureStep = self.count.value
         self.phase = event.phase
     }
+    // 目标监听器的执行点；它排在目标类型 onEvent 方法之后。
     function target(self: EventLog, event: Event): Unit {
         self.count.increment()
         self.targetStep = self.count.value
         self.phase = event.phase
     }
+    // 祖先冒泡阶段记录最后序号，未被 stopPropagation 时才到达。
     function bubble(self: EventLog, event: Event): Unit {
         self.count.increment()
         self.bubbleStep = self.count.value
         self.phase = event.phase
     }
 }
+// 覆盖目标方法，比额外 on(click,...) 监听器更早处理目标阶段事件。
 class EventButton: Button {
     model: EventLog
+    // 把模型序列递增后写 methodStep，供断言与 capture/target/bubble 比较。
     function onEvent(self: EventButton, event: Event): Unit {
         self.model.count.increment()
         self.model.methodStep = self.model.count.value
@@ -32,6 +40,8 @@ class EventButton: Button {
 model = EventLog(ui.state(0), 0, 0, 0, 0, "等待点击")
 button = EventButton("捕获 → 对象方法 → 监听器 → 冒泡", model)
 root = Column(24, 16, TextBlock("同一对象系统中的事件分派", 2), button, ui.textOf(model.count, "value"), ui.textOf(model, "phase"))
+// capture 选项显式选择捕获；不带选项的祖先监听器默认在冒泡阶段执行。
+// 返回的令牌可 disconnect，同次派发中断开尚未执行的监听器也应生效。
 capture = root.on("click", model.capture, "capture")
 target = button.on("click", model.target)
 bubble = root.on("click", model.bubble)

examples/exit-lifecycle.endor

@@ -1,17 +1,24 @@
+// 正常退出与多窗口卸载示例：同一 ExitText 出现在两窗，onUnmount 按出现位置分别调用。
+// 退出先取消任务、关闭窗口，再进行允许的卸载回调；已停止 VM 的清理不能重新进入源代码。
+// 在原生文字类型上增加共享日志，用来观察每个 Mount 的卸载通知。
 class ExitText: TextBlock {
     log: Object
+    // 每次真实卸载递增同一 log；普通重绘不调用，重复 shutdown 也不应重复调用。
     function onUnmount(self: ExitText, mount: Mount): Unit {
         self.log.increment()
     }
 }
 log = ui.state(0)
+// 文字业务对象只创建一次，Page 与另一窗都引用它，但两边有各自的 Mount 生命周期。
 watched = ExitText("关闭副窗口可观察卸载计数；退出应用也会卸载剩余位置",2,log)
 page = Page()
 page.title = "退出生命周期"
 page.render(Column(24,16,watched,ui.textOf(log,"value")))
+// 创建同 VM 内的另一原生窗口；迁移 other 后仍保留 watched 的业务身份。
 second = Window()
 second.setTitle("Exit lifecycle secondary")
 other = Page()
 other.render(watched)
 other.moveToWindow(second)
+// 应用级长定时任务用于观察退出会取消尚未完成的工作，不让退出过程等满 30 秒。
 pending = ui.sleep(ui,"pending",30000)

examples/field-contracts.endor

@@ -1,12 +1,18 @@
+// 字段类型契约示例：CounterText 同时有原生文本载荷和源 Number 字段。
+// 绑定显示读取该字段，GUI 回调与 Console 赋值受同一契约约束。
+// 增加 value:Number；构造时先传原生 text，再传源字段值。
 class CounterText: TextBlock {
     value: Number
+    // 收到 click 后把已有数值改为 10，依赖文字随之更新，不修改原生 text 内容。
     function change(self: CounterText, event: Event): Unit {
         self.value = 10
     }
 }
+// 声明 target 必须是 Block，可接收 CounterText，因为它是 TextBlock 的子类。
 class Model {
     target: Block
 }
+// 构造唯一受检对象，Model、事件回调和 textOf 均引用它。
 counter = CounterText("共享的原生子类对象", 9)
 model = Model(counter)
 button = Button("把 Number 字段改成 10")

examples/flex-constraints.endor

@@ -1,11 +1,17 @@
+// flexBasis/flexMin/flexMax/flexShrink 约束同一主轴分配。
+// 增长达到上限或收缩达到下限后，剩余空间/缺额重新分给其他尚可调整的项，固定项保持 60。
+// 给 Row 一个有限 340x60 的期望尺寸，便于精确观察分配数值。
 class Strip: Row {
+    // 源测量返回固定尺寸；后续排列仍使用原生 Row 的 padding/gap 与 flex 规则。
     function measure(self: Strip, mount: Mount, constraints: Constraints): MeasureResult {
         return MeasureResult(340, 60)
     }
 }
+// 分别持有两个可调整矩形，按钮切换增长/收缩策略，而不是手动写最终 bounds。
 class Actions {
     first: RectBlock
     second: RectBlock
+    // 两项 basis=100，按1:3分增长；首项 max=105 触顶后，多余增长转给第二项。
     function grow(self: Actions): Unit {
         self.first.flexMin = 0
         self.first.flexMax = 105
@@ -14,6 +20,7 @@ class Actions {
         self.first.flex = 1
         self.second.flex = 3
     }
+    // 两项 basis=200 造成缺额，以 flexShrink*basis 分摊；首项 min=150 后第二项继续收缩到90。
     function shrink(self: Actions): Unit {
         self.first.flexMax = 300
         self.first.flexMin = 150
@@ -25,6 +32,7 @@ class Actions {
         self.second.flexShrink = 1
     }
 }
+// 自然宽20/40与basis可不同；fixed不设置权重，保持原始60宽。
 first = RectBlock(20, 20, 4, "#A4C8F0")
 second = RectBlock(40, 20, 4, "#A6D8B2")
 fixed = RectBlock(60, 20, 4, "#E8C990")
@@ -33,6 +41,7 @@ grow = Button("增长：上限后重新分配")
 grow.onClick(actions.grow)
 shrink = Button("收缩：最小尺寸后重新分配")
 shrink.onClick(actions.shrink)
+// 先初始化增长策略再挂载，首次发布即采用105/135/60，不需等待按钮点击。
 actions.grow()
 strip = Strip(10, 10, first, second, fixed)
 page = Page()

examples/flex.endor

@@ -1,8 +1,14 @@
+// 按 flex 权重分配有限主轴空间：固定项先占自然尺寸，剩余空间按正权重划分。
+// paragraph 只有一份业务内容，但在两个 Row 的 Mount 中各自按真实分配宽度测量/换行。
+// 只持有首个 Row 的 filler，修改它的权重来间接改变同排文字分配。
 class Actions {
     filler: RectBlock
+    // 将 filler 权重恢复为 1，与 paragraph=1 近似等分可用空间。
     function balanced(self: Actions): Unit { self.filler.flex = 1 }
+    // filler 权重改为 3，paragraph 在首排获得剩余空间的四分之一，换行高度随之增加。
     function narrow(self: Actions): Unit { self.filler.flex = 3 }
 }
+// 共享文字的 flex=1 是业务布局策略，具体几何与自然尺寸缓存仍属于各 Mount。
 paragraph = TextBlock("GUI 和代码操控同一套 Aster 内存对象系统。对象只有一份，但每次挂载都有自己的约束和布局。这里用同一个 TextBlock 在两个容器中显示不同的换行。修改权重会重新测量文字高度，随后更新相邻布局。GUI 和代码操控同一套 Aster 内存对象系统。对象只有一份，但每次挂载都有自己的约束和布局。这里用同一个 TextBlock 在两个容器中显示不同的换行。修改权重会重新测量文字高度，随后更新相邻布局。")
 paragraph.flex = 1
 filler = RectBlock(20, 20)
@@ -12,6 +18,7 @@ balanced = Button("等比例分配")
 balanced.onClick(actions.balanced)
 narrow = Button("文字只占四分之一")
 narrow.onClick(actions.narrow)
+// 首排两个可伸缩子项，次排只有文字 flex 与固定 300px 兄弟，因此首排按钮不会改次排宽度。
 first = Row(10, 10, paragraph, filler)
 second = Row(10, 10, paragraph, RectBlock(300, 20))
 page = Page()

examples/fonts.endor

@@ -1,5 +1,11 @@
+// 字体测量示例：中英文混排、重音字符和不同字宽均走系统字体塑形与回退。
+// 布局使用实际字形宽度，iiii 与 WWWW 后的色块位置应不同，不能用字符数量估算宽度。
+// 字号2与独立颜色用于标题，中文是否可见取决于运行环境可用CJK字体。
 let title = ui.text("Hello Endor · 你好，Tessera", 2, "#242422")
+// 同一文字控件包含中英文和重音字符，用于观察字体回退与基线。
 let detail = ui.text("中文 English 123 — café", 1, "#606060")
+// 两组相同尺寸色块跟在窄/宽字符后，12px gap 保持一致，差异来自真实文字测量。
 let row = ui.row(0, 12, ui.text("iiii"), ui.rect(24, 20, 4, "#DCE8FF"), ui.text("WWWW"), ui.rect(24, 20, 4, "#DCE8FF"))
+// 根Column统一padding和间距，render后这些对象才有具体Mount与绘图命令。
 let page = ui.page()
 page.render(ui.column(24, 12, title, detail, row))

examples/function-types.endor

@@ -1,13 +1,22 @@
+// Function 与 Type 的契约示例：源函数、原生函数与绑定方法都可作为函数值，类型构造器保持 Type 身份。
+// 参数和返回注解在真实调用边界校验，事件注册同样使用这些签名。
+// Number 输入原样返回，用于说明参数类型在进入函数体前检查。
 function identity(value: Number): Number { return value }
+// 接受 Function 值并零参数调用，结果仍需符合本函数的 Number 返回契约。
 function callNumber(callback: Function): Number { return callback() }
+// 接受声明 Visual 能力的对象，返回 Block；调用时两侧契约都要成立。
 function visual(value: Visual): Block { return value }
+// 保留共享 state，read 作为普通绑定函数使用，click 作为接收 Event 的事件回调。
 class Actions {
     state: Object
+    // 读取模型值而不修改业务状态，保存 actions.read 时接收者已绑定。
     function read(self: Actions): Number { return self.state.value }
+    // 事件入口可忽略 Event 内容，但参数契约仍要求它是 Event，再修改同一 state。
     function click(self: Actions, event: Event): Unit { self.state.increment() }
 }
 state = ui.state(0)
 actions = Actions(state)
+// 保存绑定方法对象，之后无参调用仍使用 actions 作为 self；不是重新按字符串查找对象。
 savedFunction = actions.read
 initial = identity(callNumber(savedFunction))
 button = Button("调用带类型检查的对象方法")

examples/gc-lifecycle.endor

@@ -1,12 +1,13 @@
-// Record ui.stats().objects, call mountCycle(), then inspect phase.value and
-// pending.value.status(). Close the tab: the referenced Block still waits.
-// releaseCycle() removes both external references; the next objects query
-// should return to the same baseline before the five-minute wait finishes.
+// 托管对象循环与等待帧回收：先记 ui.stats().objects，再调用 mountCycle，观察 phase 与 pending.value.status()。
+// 关闭临时页仍可因业务引用保留等待任务；releaseCycle 清掉外部引用后，缓存不应让整个引用环常驻。
+// 比较操作前后对象数时，关闭页面只解除展示根；holder/pending 外部引用也释放后才应回到基线。
 holder = ui.state(0)
 pending = ui.state(0)
 phase = ui.state(0)
+// 通过 peer 指回包含自己的 Page，配合等待协程形成包含视觉缓存读依赖的引用环。
 class CycleRect: RectBlock {
     peer: Object
+    // sleep 归属该 rect，await 保留协程帧；先写 phase=1，只有实际恢复后才写 2 并改 Page 标题。
     function wait(self: CycleRect): Unit {
         gate = ui.sleep(self,"sleep",300000)
         phase.set(1)
@@ -14,15 +15,18 @@ class CycleRect: RectBlock {
         phase.set(2)
         self.peer.title = "等待已结束"
     }
+    // 故意读取 peer.title，让布局依赖包含循环中的 Page；缓存应借用观察，不增加长期 GC 根。
     function measure(self: CycleRect, mount: Mount, constraints: Constraints): MeasureResult {
         observed = self.peer.title
         return MeasureResult(180,40)
     }
+    // 绘制也读取 peer.title，检查绘制缓存与等待帧不会共同意外保活循环。
     function paint(self: CycleRect, mount: Mount, geometry: Bounds): DisplayList {
         observed = self.peer.title
         return RectBlock.paint(self,mount,geometry)
     }
 }
+// 创建临时 Page 和 CycleRect，相互引用后挂载，再把 Page/Task 分别放入两个外部 holder。
 function mountCycle(): Unit {
     transient = Page()
     transient.title = "临时引用环"
@@ -32,11 +36,13 @@ function mountCycle(): Unit {
     phase.set(0)
     pending.set(ui.spawn(rect,"workflow",rect.wait))
 }
+// 先关闭临时页，随后去掉两个外部引用；等待依赖无需等满五分钟，失去可达性后应整体回收。
 function releaseCycle(): Unit {
     holder.value.close()
     holder.set(0)
     pending.set(0)
 }
+// 基线页面始终存在，用它比较操作前后的托管对象数，不把临时页面当作基线。
 base = Page()
 base.title = "GC 基线"
 base.render(TextBlock("关闭临时 Page 后应回收引用环",2))

examples/global-dependencies.endor

@@ -1,11 +1,16 @@
+// 全局名称依赖示例：paint 读取 color 这个具体名字，而非依赖整个 globals 字典版本。
+// Console 求值 42 仅改变最后结果 _，不应重绘；给 color 赋新值才使绘制失效。
 color = "#ED6A5A"
+// 保持原生几何，覆盖颜色策略，使示例只观察全局读取的依赖粒度。
 class GlobalPaint: RectBlock {
+    // 调用原生基类产出新命令，读取当前 color 并写到新命令；不在只读阶段修改全局。
     function paint(self: GlobalPaint, mount: Mount, geometry: Bounds): DisplayList {
         drawing = RectBlock.paint(self,mount,geometry)
         drawing.commands.at(0).color = color
         return drawing
     }
 }
+// 显示固定大小矩形和操作提示，后续通过 Console 改同一个会话的 color。
 rect = GlobalPaint(480,120,12,"#DDEEFF")
 page = Page()
 page.title = "全局名字依赖"

examples/hello.endor

@@ -1,10 +1,10 @@
-function heading(value: Text): View {
-    return ui.text(value, 2, "#242422")
+function heading(value: Text): View { // 辅助函数把字符串包装成大字号 TextBlock；返回值仍是托管视觉引用。
+    return ui.text(value, 2, "#242422") // 这里只创建文字对象，具体宽高由实际字体和出现位置约束测量。
 }
 
-function main(): View {
-    let title = heading("Hello Endor")
-    let rectangle = ui.rect(240, 80, 12, "#DCE8FF")
-    let detail = ui.row(0, 12, ui.text("Aster VM"), ui.spacer(8), ui.text("Tessera UI"))
-    return ui.column(24, 12, title, rectangle, detail)
+function main(): View { // 兼容模块入口 main 返回视觉根，宿主负责把它显示到页面，不需要源代码显式 render。
+    let title = heading("Hello Endor") // 调用上述辅助函数，局部变量持有同一托管文字对象。
+    let rectangle = ui.rect(240, 80, 12, "#DCE8FF") // 矩形使用逻辑尺寸，圆角与颜色由原生载荷保存。
+    let detail = ui.row(0, 12, ui.text("Aster VM"), ui.spacer(8), ui.text("Tessera UI")) // Row 依次摆放文字、固定间隔和文字；共享几何仍由每次出现位置承担。
+    return ui.column(24, 12, title, rectangle, detail) // Column 的 24px 内边距和 12px 间隔决定最终命令位置；返回后发布快照拥有所需数据。
 }

examples/layout-cache.endor

@@ -1,32 +1,44 @@
+// 测量与绘制依赖分离：改颜色应复用尺寸缓存，改模型宽度才需要重新测量。
+// ViewportBand 还显式读取实际页面视口，使原生 resize 可通过依赖触发重测。
+// 只负责测量需要的宽度，和绘制颜色分成两个业务对象以便观察独立失效。
 class WidthModel {
     width: Number
+    // 点击把模型宽度置为 260；源 measure 读取过该字段，缓存因此失效。
     function expand(self: WidthModel, event: Event): Unit {
         self.width = 260
     }
 }
+// 保存 paint 使用的颜色，不参与 CachedRect 的测量。
 class Tint {
     color: String
+    // 只改颜色；正常情况下需重绘而不重新执行无关源测量。
     function blue(self: Tint, event: Event): Unit {
         self.color = "#526AC7"
     }
 }
+// 原生矩形的尺寸/颜色策略分别由源协议覆盖，业务模型通过字段持有。
 class CachedRect: RectBlock {
     dimensions: WidthModel
     tint: Tint
+    // 读取 dimensions.width 返回固定高 60；实际读观察由运行时缓存记录，不手工声明依赖表。
     function measure(self: CachedRect, mount: Mount, constraints: Constraints): MeasureResult {
         return MeasureResult(self.dimensions.width, 60)
     }
+    // 复用原生矩形命令，再改新命令的颜色；修改新结果被允许，但 paint 不能修改已有业务对象。
     function paint(self: CachedRect, mount: Mount, geometry: Bounds): DisplayList {
         drawing = RectBlock.paint(self, mount, geometry)
         drawing.commands.at(0).color = self.tint.color
         return drawing
     }
 }
+// 宽度来自 ui.viewport 的当前逻辑页面区域，显示窗口变化也能成为测量依赖。
 class ViewportBand: RectBlock {
+    // 返回可用视口宽度，最终仍服从父容器约束；外层 padding 会减少分配宽度。
     function measure(self: ViewportBand, mount: Mount, constraints: Constraints): MeasureResult {
         return MeasureResult(ui.viewport().width, 24)
     }
 }
+// 创建相互独立的宽度/颜色模型并绑定两个按钮，用相同对象观察缓存与可见结果。
 dimensions = WidthModel(200)
 tint = Tint("#ED6A5A")
 rect = CachedRect(80, 20, 0, "#ED6A5A", dimensions, tint)

examples/layout-negotiation.endor

@@ -1,24 +1,34 @@
+// 测量/排列协商示例：arrange 指定子宽后需重新换行测量，高度变化继续影响父容器和后继位置，直到整树稳定。
+// paragraph 被两个容器共享；每个 Mount 使用独立约束，不能把新宽度写回共享文字状态。
+// 保存第一个段落出现位置的分配宽度，按钮只改策略值。
 class Policy {
     width: Number
+    // 选择 280 逻辑像素宽度，段落变高，后继文字下移。
     function narrow(self: Policy, event: Event): Unit { self.width = 280 }
+    // 选择 560 逻辑像素宽度，段落变矮；另一个容器宽度不跟着改变。
     function wide(self: Policy, event: Event): Unit { self.width = 560 }
 }
+// 在原生 Column 排列基础上覆盖第一个稳定子槽的宽度。
 class ArrangedColumn: Column {
     policy: Policy
+    // 先取得包含全部子槽的 Arrangement，仅改第一子项分配；保留其他槽使排列验证完整。
     function arrange(self: ArrangedColumn, mount: Mount, geometry: Bounds): Arrangement {
         result = Column.arrange(self, mount, geometry)
         result.children.at(0).width = self.policy.width
         return result
     }
 }
+// 通过源 measure 改整个容器的期望宽度，以对比 arrange 分配路径。
 class MeasuredColumn: Column {
     width: Number
+    // 调用原生测量后修改新结果 width；这个新结果不属于已有业务对象，允许在只读计算中填写。
     function measure(self: MeasuredColumn, mount: Mount, constraints: Constraints): MeasureResult {
         result = Column.measure(self, mount, constraints)
         result.width = self.width
         return result
     }
 }
+// 两个容器使用同一个 paragraph，分别由 Policy=280 与 measure.width=360 约束。
 policy = Policy(280)
 paragraph = TextBlock("源码 arrange 改变分配宽度后，文字会按实际宽度重新测量。增加的高度继续影响容器和相邻对象，直到整棵布局稳定后才发布。这里与下面使用的是同一个 TextBlock；每个 Mount 都有自己的约束与几何。同一套内存对象不需要复制业务状态，也不通过丢弃传播来结束更新。")
 tail = TextBlock("这一行跟随上方段落。")
@@ -26,10 +36,12 @@ arranged = ArrangedColumn(0, 12, paragraph, tail, policy)
 measured = MeasuredColumn(0, 12, paragraph, TextBlock("这一段的宽度来自源码 measure。"), 360)
 narrow = Button("arrange 为 280")
 wide = Button("arrange 为 560")
+// 保留事件订阅引用，两个按钮调用同一 Policy 的不同方法。
 narrowConnection = narrow.on("click", policy.narrow)
 wideConnection = wide.on("click", policy.wide)
 page = Page()
 page.title = "约束协商"
 page.render(Column(24, 16, Row(0, 12, narrow, wide), arranged, measured))
+// 成功输入结束后宿主才消费原生窗口命令；窗口实际尺寸再回传为下一次布局约束。
 ui.window().resize(850, 700)
 ui.window().setTitle("测量与排列直到稳定")

examples/main.endor

@@ -1,5 +1,9 @@
+// 与 page.endor 等价的 main 返回根入口：用于对比顶层显式 render 和兼容模块入口的绘图结果。
+// 返回 Column 视觉对象，宿主选择/挂载页面；这里的 title 和 rectangle 只在 VM 内建立业务引用。
 function main(): View {
+    // 文字内容与矩形参数和 page 示例一致，最终绘图命令应等价。
     let heading = ui.text("Hello Endor", 2, "#242422")
     let rectangle = ui.rect(240, 80, 12, "#DCE8FF")
+    // 布局边距与间隔保持一致；不同 VM 的对象/Mount 身份独立，命令相同不表示共享对象。
     return ui.column(24, 12, heading, rectangle)
 }

examples/managed-types.endor

@@ -1,9 +1,14 @@
+// 托管名义类型入门：ui 构造器与 TextBlock/Button/Page 返回同一套 VM 托管对象。
+// 两个文字绑定读同一 counter；原生点击和 Console 都能操作该对象并传播显示变化。
+// state 提供可写 value 和 increment 方法，textOf 建立显式字段到文本的依赖。
 counter = ui.state(9)
 first = ui.textOf(counter, "value", 2)
 second = ui.textOf(counter, "value", 2)
 title = TextBlock("Endor：同一份对象，代码与 GUI 共同操作", 2)
 button = Button("增加计数")
+// 零参数源回调委托原生 state.increment；事件分发器根据签名调用，不强塞 Event 参数。
 function increment(): Unit { counter.increment() }
+// 把实际函数作为回调而非函数名文本；render 之前只创建业务对象，render 后才有出现位置。
 button.onClick(increment)
 page = Page()
 page.render(Column(24, 16, title, Row(0, 16, first, second, button)))

examples/method-contracts.endor

@@ -1,23 +1,33 @@
+// 方法覆盖遵守参数可更宽、返回可更具体的规则。
+// WideRect 复用基类原生测量后返回 Sized 子类结果；事件改变基础 width 后按同一路径重测。
+// MeasureResult 的名义子类，不增加字段，用于演示返回值协变。
 class Sized: MeasureResult {}
+// 用源方法显式委托原生测量，保留 Mount/Constraints 的基类契约。
 class BaseRect: RectBlock {
+    // 原生方法按给定出现位置与约束测量，不把几何存进共享对象。
     function measure(self: BaseRect, mount: Mount, constraints: Constraints): MeasureResult {
         return RectBlock.measure(self, mount, constraints)
     }
 }
+// 覆盖参数放宽为 Object，返回缩窄为 Sized；不能反过来缩窄参数或放宽返回。
 class WideRect: BaseRect {
+    // 调用基类后复制测量数值到新的 Sized；新结果仍满足 MeasureResult 协议。
     function measure(self: WideRect, mount: Object, constraints: Object): Sized {
         measured = BaseRect.measure(self, mount, constraints)
         return Sized(measured.width, measured.height)
     }
 }
+// 保存具体 WideRect 和计数器，使宽度修改和点击次数同时作为业务变化传播。
 class Actions {
     rect: WideRect
     count: Object
+    // 先改 width 再递增计数，新的布局刷新会使用上述动态测量覆盖。
     function widen(self: Actions): Unit {
         self.rect.width = 260
         self.count.increment()
     }
 }
+// 初始矩形宽 180；按钮事件完成后应变为 260，同时文字显示计数。
 rect = WideRect(180, 60, 8, "#ED6A5A")
 count = ui.state(0)
 actions = Actions(rect, count)

examples/mount-lifecycle.endor

@@ -1,3 +1,6 @@
+// 业务对象与出现位置生命周期分离：同一 child 在根中出现两次，每次都获得独立 Mount 和通知。
+// 普通数据变化不会重新挂载；页面关闭时子项先卸载，父项随后卸载，旧 Mount 不因重开而复活。
+// order 是统一时序，mounted/unmounted 是子项次数；latest 保存最近通知的实际 Mount。
 class LifecycleLog {
     order: Object
     mounted: Object
@@ -8,8 +11,10 @@ class LifecycleLog {
     childUnmounted: Number
     latest: Object
 }
+// 共享文字用 log 记录两个出现位置，源钩子接收的是当前具体 Mount。
 class WatchedText: TextBlock {
     log: LifecycleLog
+    // 记录顺序和次数，保存 Mount 并修改原文字；运行时在回调后重新收敛才发布。
     function onMount(self: WatchedText, mount: Mount): Unit {
         self.log.order.increment()
         self.log.mounted.increment()
@@ -17,6 +22,7 @@ class WatchedText: TextBlock {
         self.log.latest.set(mount)
         self.setText("同一个对象，两个独立挂载位置")
     }
+    // 记录已经脱离的出现位置；保留 Mount 可查询 mounted，但不能再当有效 bounds 使用。
     function onUnmount(self: WatchedText, mount: Mount): Unit {
         self.log.order.increment()
         self.log.unmounted.increment()
@@ -24,17 +30,21 @@ class WatchedText: TextBlock {
         self.log.latest.set(mount)
     }
 }
+// 父容器也记录钩子序号，便于对比挂载与子先父后的卸载顺序。
 class WatchedColumn: Column {
     log: LifecycleLog
+    // 记录父挂载顺序，不修改容器结构；子项随后各自执行通知。
     function onMount(self: WatchedColumn, mount: Mount): Unit {
         self.log.order.increment()
         self.log.parentMounted = self.log.order.value
     }
+    // 父卸载时子项卸载已完成，序列号应位于所有子项通知之后。
     function onUnmount(self: WatchedColumn, mount: Mount): Unit {
         self.log.order.increment()
         self.log.parentUnmounted = self.log.order.value
     }
 }
+// 多个 state 容器分别保存计数/最后 Mount，root 最后参数是源 log 字段，前面才是可变视觉子项。
 log = LifecycleLog(ui.state(0), ui.state(0), ui.state(0), 0, 0, 0, 0, ui.state(0))
 child = WatchedText("等待挂载", 2, log)
 root = WatchedColumn(24, 16, child, child, TextBlock("挂载次数"), ui.textOf(log.mounted, "value"), TextBlock("卸载次数"), ui.textOf(log.unmounted, "value"), log)

examples/native-signatures.endor

@@ -1,12 +1,19 @@
+// 原生回调也发布 Function 签名：state.set 接收一个 Event，increment 接收零参数。
+// 同一事件注册机制按实际签名调用；label 绑定再把事件 kind 转成可显示的字符串。
+// 保留最后一次收到的 Event 对象，初值 kind=waiting；不是只存一份格式化事件文本。
 received = ui.state(Event("waiting"))
 count = ui.state(0)
+// 只读计算提取当前事件种类，作为 label.text 绑定的依赖。
 function eventKind(): String { return received.value.kind }
 label = TextBlock("waiting")
 subscription = label.bind("text", eventKind)
 withEvent = Button("传递 Event 给原生 set")
+// received.set 是一参数原生方法，分发器传入实际 click Event。
 firstConnection = withEvent.on("click", received.set)
 withoutEvent = Button("调用零参数原生 increment")
+// count.increment 的签名为零参数，分发器调用时不传多余 Event。
 secondConnection = withoutEvent.on("click", count.increment)
+// 把已绑定状态与两种回调放到同一页面，便于对比输入效果。
 page = Page()
 page.title = "原生方法签名"
 page.render(Column(24, 16, TextBlock("源码和原生回调共用参数契约"), label, ui.textOf(count, "value"), withEvent, withoutEvent))

examples/native-subclasses.endor

@@ -1,33 +1,43 @@
+// 源类继承原生视觉类型：原生载荷负责基础绘制，新增字段和覆盖方法由源类提供。
+// label 在树中出现多次但仍是同一对象，原生方法和源字段写入共同更新各出现位置。
+// 扩展 TextBlock 的业务字段；其文本/颜色仍由原生父类存储与绘制。
 class StatusText: TextBlock {
     activeColor: String
 
+    // 用继承的 setText/setColor 改原对象；activeColor 是构造时追加的源字段。
     function activate(self: StatusText, event: Event): Unit {
         self.setText("继承的原生文本已更新")
         self.setColor(self.activeColor)
     }
 }
 
+// 继续继承源子类，添加 message 并覆盖事件入口，保留 TextBlock 的原生能力。
 class CustomStatus: StatusText {
     message: String
 
+    // 显式调用基类 setText 以示范原生未绑定方法的接收者传递，再用继承方法改颜色。
     function activate(self: CustomStatus, event: Event): Unit {
         TextBlock.setText(self, self.message)
         self.setColor(self.activeColor)
     }
 }
 
+// 按钮保存目标 Block，事件到来时把同一 Event 转交给目标的动态 activate。
 class ActionButton: Button {
     target: Block
 
+    // 不复制目标或创建新展示对象，直接调用目标业务方法，选择实际类型的覆盖实现。
     function activate(self: ActionButton, event: Event): Unit {
         self.target.activate(event)
     }
 }
 
+// Page 也可增加源字段；caption 用于构建页内标题，不替代原生窗口标题。
 class CustomPage: Page {
     caption: String
 }
 
+// 前面位置参数供原生 TextBlock 构造，后面的颜色/消息供继承字段；所有引用都保留托管类型。
 label = CustomStatus("点击按钮更新同一个自定义文本对象", 2, "#242422", "#237A45", "源码子类与原生载荷共同工作")
 button = ActionButton("调用源码子类方法", label)
 button.onClick(button.activate)

examples/owned-tasks.endor

@@ -1,15 +1,22 @@
+// owner 作用域决定取消时机：Page 关闭会取消其任务，隐藏 Block 和 ui 的任务可继续。
+// 每个 owner 下同 key 的重复点击替换旧定时器；任务生命周期不由画面是否可见推断。
+// 把 owner 与要修改的 state 分开持有，使同一个调度方法可用于三个作用域。
 class Actions {
     owner: Object
     state: Object
+    // 定时任务成功交付后修改共享计数，零参数签名符合 timer 回调要求。
     function complete(self: Actions): Unit { self.state.increment() }
+    // 每次启动 1500ms 的 load 定时器；相同 owner/key 只有最新任务继续等待。
     function schedule(self: Actions, event: Event): Unit {
         ui.after(self.owner, "load", 1500, self.complete)
     }
 }
 state = ui.state(0)
+// 该 Block 从未进入页面树，但全局引用仍持有它，因此它拥有的任务可执行。
 hidden = TextBlock("这个 Block 没有挂载，也能拥有任务")
 page = Page()
 page.title = "任务生命周期"
+// 三个 Action 共享一个 state，却分别归属 Page、Block、应用，便于比较关闭页面的取消边界。
 pageActions = Actions(page, state)
 blockActions = Actions(hidden, state)
 appActions = Actions(ui, state)
@@ -20,5 +27,6 @@ pageConnection = pageButton.on("click", pageActions.schedule)
 blockConnection = blockButton.on("click", blockActions.schedule)
 appConnection = appButton.on("click", appActions.schedule)
 page.render(Column(24, 16, TextBlock("1.5 秒后更新同一个状态对象；重复点击只保留最新任务"), ui.textOf(state, "value"), pageButton, blockButton, appButton))
+// 额外应用级任务延迟 500ms，用于展示没有点击也可按 worker 空闲轮询交付。
 initial = ui.after(ui, "initial", 500, appActions.complete)
 ui.window().setTitle("Owned Tasks")

examples/page.endor

@@ -1,4 +1,4 @@
-let heading = ui.text("Hello Endor", 2, "#242422")
-let rectangle = ui.rect(240, 80, 12, "#DCE8FF")
-let myui = ui.page()
-myui.render(ui.column(24, 12, heading, rectangle))
+let heading = ui.text("Hello Endor", 2, "#242422") // 顶层脚本不需要 main：先创建文字对象；字号 2 和十六进制颜色传给原生文字构造器。
+let rectangle = ui.rect(240, 80, 12, "#DCE8FF") // 创建固定逻辑尺寸矩形；12 为圆角半径，业务对象尚未出现在任何页面中。
+let myui = ui.page() // 创建托管 Page 资源；它负责持有展示根和页面生命周期。
+myui.render(ui.column(24, 12, heading, rectangle)) // 把文字和矩形放入 Column，padding=24、gap=12；render 选择此页并生成出现位置及发布帧。

examples/presentable.endor

@@ -1,27 +1,38 @@
+// 普通业务对象显式实现 Presentable 后，ui.present 可调用其 present(window) 生成视觉对象。
+// 生成的视图保存 source 指向业务模型，绑定和按钮继续使用原对象，展示不是业务数据副本。
+// name/color 是业务字段，零参读取方法提供只读绑定，update 提供事件修改。
 class Product {
     name: String
     color: String
+    // 返回名称并记录实际属性读取，后续 name 修改会使文本绑定重算。
     function label(self: Product): String { return self.name }
+    // 只读返回颜色，绑定到新建色块的 color。
     function shade(self: Product): String { return self.color }
+    // 点击更新原业务对象，现有绑定会同步文字和矩形，不重新调用整个 present 构造树。
     function update(self: Product, event: Event): Unit {
         self.name = "原业务对象已更新"
         self.color = "#237A45"
     }
+    // 在指定 Window 上下文创建文字、色块和按钮，连接原 self 的方法后返回组合根。
     function present(self: Product, window: Window): Block {
         title = TextBlock(self.name)
         swatch = RectBlock(180,48,8,self.color)
+        // 绑定令牌本身不承载另一份业务状态，绑定计算仍调用同一 Product。
         titleBinding = title.bind("text",self.label)
         colorBinding = swatch.bind("color",self.shade)
         button = Button("调用业务对象方法")
         connection = button.on("click",self.update)
         result = Column(24,16,title,swatch,button)
+        // 保留原始业务身份，便于代码从展示根回到来源；contextWindow 仅记录创建时的窗口编号。
         result.source = self
         result.contextWindow = window.id()
         return result
     }
 }
+// 显式声明能力并验证方法契约；只有同名 present 不会自动成为 Presentable。
 ui.implement(Product,Presentable)
 product = Product("普通对象的显式展示能力", "#526AC7")
+// 先获得视觉根，再由 ui.open 把它挂载到页面；最后设置 Page 标题。
 view = ui.present(product)
 page = ui.open(view)
 page.title = "Presentable"

examples/property-bindings.endor

@@ -1,10 +1,17 @@
+// 通用属性绑定：业务 Model 的三个零参只读方法分别计算 rect.width、rect.color 和 label.text。
+// 绑定在目标隐藏时也会更新；两个页面共享同一组 Block，不需要两份模型。
+// width/color/label 是唯一业务来源，绑定计算只读，expand 是显式事件写入入口。
 class Model {
     width: Number
     color: String
     label: String
+    // 返回 Number，目标 width 属性同时做类型/尺寸验证。
     function getWidth(self: Model): Number { return self.width }
+    // 返回颜色文本；依赖只包含实际读取的模型属性。
     function getColor(self: Model): String { return self.color }
+    // 返回当前说明文字，供 TextBlock.text 绑定使用。
     function getLabel(self: Model): String { return self.label }
+    // 一个事件同时改三个属性，随后绑定传播，布局与绘制在完整刷新后发布。
     function expand(self: Model, event: Event): Unit {
         self.width = 260
         self.color = "#237A45"
@@ -14,6 +21,7 @@ class Model {
 model = Model(120, "#526AC7", "点击更新共享对象")
 rect = RectBlock(120, 40, 8, "#526AC7")
 label = TextBlock("初始化")
+// 保存三个可断开的绑定令牌；令牌不强持有隐藏目标，目标仍需由业务对象图保留。
 widthBinding = rect.bind("width", model.getWidth)
 colorBinding = rect.bind("color", model.getColor)
 labelBinding = label.bind("text", model.getLabel)
@@ -23,6 +31,7 @@ root = Column(24, 16, label, rect, button)
 page = Page()
 page.title = "通用属性绑定"
 page.render(root)
+// 第二页面使用同一根容器，切页只更换 Mount 展示上下文；最后 activate 回第一页面。
 second = Page()
 second.title = "同一组 Block"
 second.render(root)

examples/scene-viewports.endor

@@ -1,7 +1,10 @@
-// The scene has world positions; each finite viewport has its own camera.
+// 一个二维世界可被多个有限视口观察，Scene2D 的对象位置共享，默认 Camera2D 各自独立。
+// 内层视口也可作为世界子项；HUD 在外层 Overlay 中，所以不会随世界相机变换。
+// 场景保存世界对象，视口负责有限窗口与相机变换。
 count = ui.state(0)
 increment = Button("共享计数 +1")
 increment.onClick(count.increment)
+// 业务卡片带世界 x/y 和边框，count 文字与按钮共同保留同一 state。
 card = Column(20, 12, TextBlock("世界里的 UI", 2), ui.textOf(count, "value", 3), increment)
 card.boxWidth = 220
 card.x = -60
@@ -9,17 +12,21 @@ card.y = 40
 card.borderLeft = 2
 card.borderColor = "#8CA5B8"
 
+// 有限内层视口看自己的小场景，再以世界坐标放进外层 Scene2D。
 inner = CanvasViewport(200, 100, Scene2D(RectBlock(120, 60, 8, "#D4E6D9")))
 inner.x = 260
 inner.y = 40
+// 两个外层视口引用同一 world，卡片/内层视口因此各产生两个出现位置。
 world = Scene2D(card, inner)
+// 左右视口尺寸和相机平移/缩放不同；显式赋同一 camera 才会共享导航状态。
 left = CanvasViewport(460, 320, world)
 left.camera.x = -100
 right = CanvasViewport(320, 320, world)
 right.camera.x = -80
 right.camera.zoom = 0.65
-// Set right.camera = left.camera to share a view explicitly.
+// 如需联动，在 Console 将 right.camera 赋为 left.camera；共享场景本身不会自动共享相机。
 
+// 先横排两个视图，再把固定 HUD 叠在它们之上，输入命中也使用组合后的几何。
 views = Row(0, 20, left, right)
 hud = Column(16, 8, TextBlock("一个世界，多个视角", 2), TextBlock("滚轮平移 · 空格/中键拖动 · 捏合或 Cmd/Ctrl+滚轮缩放"))
 hud.alignSelf = "end"

examples/scene3d.endor

@@ -1,19 +1,27 @@
+// 同一 Scene3D 在透视/正交视口中展示；相机控制独立，网格业务变换由两边共享。
+// 三维内容与普通 Endor 二维控件一起排版，viewport 有限尺寸不限制场景世界坐标。
+// 保存左侧视口和共享立方体；动作可改相机位置或真实网格变换。
 class SceneActions {
     view: Viewport3D
     cube: Mesh3D
+    // 把左相机放到 z=6 正面，保持相机既有 target。
     function front(self: SceneActions): Unit {
         self.view.camera.x = 0
         self.view.camera.y = 0
         self.view.camera.z = 6
     }
+    // 把同一相机移到侧上方，右侧正交相机保持原设置。
     function side(self: SceneActions): Unit {
         self.view.camera.x = 6
         self.view.camera.y = 2
         self.view.camera.z = 0
     }
+    // 修改共享 cube 的欧拉旋转，因此两个视口都看到物体变化。
     function rotate(self: SceneActions): Unit { self.cube.rotate(0, 15, 0) }
+    // 示范 Event.hit.mesh 的真实托管网格材质写入；此文件尚未把 select 注册到视口。
     function select(self: SceneActions, event: Event): Unit { event.hit.mesh.color = "#6B9B81" }
 }
+// 先构造并变换两个 Box3D，再由 Group3D 组成场景节点；几何与相机是不同对象。
 cube = Box3D(1.6, 1.6, 1.6, "#6687AB")
 cube.rotationY = 25
 cube.rotationX = 15
@@ -21,11 +29,13 @@ small = Box3D(0.7, 0.7, 0.7, "#DBA36E")
 small.x = 1.8
 small.z = -0.8
 group = Group3D(cube, small)
+// 薄盒作地面，方向光与 ambient 一起影响材质颜色，不是二维背景矩形。
 floor = Box3D(6, 0.08, 4, "#D8DEE6")
 floor.y = -1.1
 light = DirectionalLight(-1, -2, -3, "#FFFFFF", 0.9)
 scene = Scene3D(group, floor, light)
 scene.ambient = 0.35
+// 左视口使用默认透视相机，右视口显式换成 OrthographicCamera 并设置可见高度。
 perspective = Viewport3D(480, 360, scene)
 perspective.camera.z = 6
 orthographic = Viewport3D(320, 360, scene)
@@ -34,6 +44,7 @@ orthographic.camera.height = 5
 orthographic.camera.x = 4
 orthographic.camera.y = 2
 orthographic.camera.z = 5
+// 按钮绑定零参数方法；页面文字说明原生默认控制器的交互，代码可继续替换 controller。
 actions = SceneActions(perspective, cube)
 front = Button("正面")
 front.onClick(actions.front)

examples/scroll-axis.endor

@@ -1,21 +1,31 @@
+// 滚动轴策略影响可滚动方向与内容测量约束：vertical 限宽并允许长高，horizontal 允许横向展开。
+// 同一 paragraph 出现两次，文字内容共享，换行/偏移/范围在各 Mount 中独立。
+// 通过具体出现位置的 Mount 操作偏移；ScrollBlock.axis 则是对象级策略，可影响其所有出现位置。
 class Actions {
     vertical: ScrollBlock
     horizontal: ScrollBlock
+    // 只对 vertical 第一个 Mount 累加纵偏移，运行时按当前范围夹取。
     function down(self: Actions): Unit { self.vertical.mounts().at(0).scrollBy(0, 60) }
+    // 只对 horizontal 第一个 Mount 累加横偏移，禁止轴仍保持零。
     function right(self: Actions): Unit { self.horizontal.mounts().at(0).scrollBy(60, 0) }
+    // 分别把两个出现位置移回原点，不修改共享段落文字。
     function reset(self: Actions): Unit {
         self.vertical.mounts().at(0).scrollTo(0, 0)
         self.horizontal.mounts().at(0).scrollTo(0, 0)
     }
+    // 把左对象策略改为双轴，下一次求解重新计算约束和范围。
     function both(self: Actions): Unit { self.vertical.axis = "both" }
 }
 paragraph = TextBlock("这里展示的是同一个 TextBlock。左侧只允许纵向滚动，文字会按照这个 Mount 的实际视口宽度换行；右侧只允许横向滚动，文字保留横向展开。对象的文字和业务状态只有一份，每次展示的约束、几何和滚动位置分别保存。修改滚动轴也会重新测量受影响内容，并将已经不再允许的偏移夹回零。布局传播持续到受影响部分稳定，不会按固定跳数丢弃后续更新。这里展示的是同一个 TextBlock，两个视图可以拥有不同的换行结果。")
+// 纵向区域padding后内容宽为244，长文字按此有限宽换行。
 vertical = ScrollBlock(260, 140, paragraph)
 vertical.padding = 8
 vertical.axis = "vertical"
+// 横向区域沿滚动轴允许内容自然展开，所以同一文字可以比左侧更宽、更矮。
 horizontal = ScrollBlock(260, 140, paragraph)
 horizontal.padding = 8
 horizontal.axis = "horizontal"
+// 绑定四个零参数按钮回调；最终把两视图与控制区放在普通 Column/Row 中。
 actions = Actions(vertical, horizontal)
 down = Button("向下滚动")
 down.onClick(actions.down)

examples/scroll.endor

@@ -1,10 +1,16 @@
+// 同一 ScrollBlock 在两个原生窗口中展示：内容业务对象共享，滚动偏移按 Mount 独立保存。
+// 滚动只改变投影/裁剪，不复制业务计数；被裁剪内容不能通过原始矩形接受点击。
+// 保留一个源 paint 委托，检验源命令与原生命令应用相同滚动裁剪。
 class Painted: RectBlock {
+    // 使用当前 geometry 交给原生基类；外层滚动变换/clip 由展示流程统一组合。
     function paint(self: Painted, mount: Mount, geometry: Bounds): DisplayList {
         return RectBlock.paint(self,mount,geometry)
     }
 }
+// 三个按钮复用同一个 Action，任意可见按钮点击都递增同一 count。
 class Actions {
     count: Object
+    // 签名接受 Event，业务逻辑只需修改计数，不直接处理滚动位置。
     function click(self: Actions, event: Event): Unit { self.count.increment() }
 }
 count = ui.state(0)
@@ -15,12 +21,14 @@ last = Button("底部按钮")
 firstConnection = first.on("click",actions.click)
 middleConnection = middle.on("click",actions.click)
 lastConnection = last.on("click",actions.click)
+// 高内容夹有三个按钮与矩形，使固定320x180 scroller产生可观察的横纵滚动范围。
 body = Column(12,12,first,Painted(520,180,8,"#DCE8FF"),middle,RectBlock(520,180,8,"#E3EFE5"),last)
 scroller = ScrollBlock(320,180,body)
 root = Column(24,16,TextBlock("同一 Block，两处 Mount 独立滚动"),ui.textOf(count,"value"),scroller)
 page = Page()
 page.title = "滚动示例"
 page.render(root)
+// 另一窗口复用 root/scroller；它们的第二个 Mount 偏移与主窗口第一个 Mount 无关。
 other = Window()
 other.setTitle("Scroll Secondary")
 second = Page()

examples/source-hit.endor

@@ -1,23 +1,31 @@
+// 自定义形状命中：对象原始矩形宽 160，但 paint 只画左侧直径 80 的圆，hitTest 也只接受圆内。
+// 圆外部分可落到父容器监听器；按下与释放须经相同合法目标复核。
+// 扩展矩形的绘制、命中和事件方法，用同一个 hits 状态观察交互结果。
 class CircleTarget: RectBlock {
     hits: Object
+    // point 已转换到该出现位置局部坐标；使用圆心(40,40)、半径40，而不是整个 160x80 外框。
     function hitTest(self: CircleTarget, mount: Mount, point: Point): Bool {
         return point.inCircle(40, 40, 40)
     }
+    // 把原生命令宽度缩为 80、圆角半径设为 40，得到与 hitTest 对应的圆形区域。
     function paint(self: CircleTarget, mount: Mount, geometry: Bounds): DisplayList {
         drawing = RectBlock.paint(self, mount, geometry)
         drawing.commands.at(0).width = 80
         drawing.commands.at(0).radius = 40
         return drawing
     }
+    // 圆内点击递增自身计数并停止向祖先传播；父容器不会为同一次点击再递增。
     function onEvent(self: CircleTarget, event: Event): Unit {
         self.hits.increment()
         event.stopPropagation()
     }
 }
 hits = ui.state(0)
+// 父监听器单独计数；它和圆形目标显示在同页，便于比较穿过透明区的输入。
 background = ui.state(0)
 circle = CircleTarget(160, 80, 0, "#237A45", hits)
 root = Column(24, 16, circle, TextBlock("点击圆内计入圆；透明右半区域交给父容器"), TextBlock("圆内点击"), ui.textOf(hits, "value"), TextBlock("父容器点击"), ui.textOf(background, "value"))
+// 订阅在父 Column 上，圆外有效区域可回退到父目标；源命中只读检查不执行这些业务回调。
 connection = root.on("click", background.increment)
 page = Page()
 page.render(root)

examples/source-layout.endor

@@ -1,25 +1,35 @@
+// 源视觉协议的最小组合：measure 决定尺寸，arrange 决定子项位置，Metrics 是被两者读取的业务模型。
+// 运行时在只读求解中跟踪这些读取，事件修改模型后重新布局；布局方法不能直接改业务字段。
+// 保存宽度与左偏移；两字段只在事件回调中修改。
 class Metrics {
     width: Number
     left: Number
+    // 同时改变测量和排列依赖，整帧需收敛后一起发布新尺寸/位置。
     function expand(self: Metrics, event: Event): Unit {
         self.width = 260
         self.left = 68
     }
 }
+// 复用原生矩形载荷，仅覆盖尺寸策略；同一 rect 放在不同父容器可得到不同测量。
 class MeasuredRect: RectBlock {
+    // 首次测量前结构 Mount 链接已建立，因此可从 parent.block 读取当前出现位置的父策略。
+    // 此阶段还不能查询最终 bounds，返回值使用 MeasureResult 名义类型。
     function measure(self: MeasuredRect, mount: Mount, constraints: Constraints): MeasureResult {
         parent = mount.parent()
         return MeasureResult(parent.block.metrics.width, 60)
     }
 }
+// 在原生排列结果上改第一个子槽 x，其他子项仍用 Column 的堆叠规则。
 class OffsetColumn: Column {
     metrics: Metrics
+    // Arrangement 里的 x 是当前排列使用的坐标；读取 metrics.left 成为排列依赖。
     function arrange(self: OffsetColumn, mount: Mount, geometry: Bounds): Arrangement {
         positions = Column.arrange(self, mount, geometry)
         positions.children.at(0).x = self.metrics.left
         return positions
     }
 }
+// 将原生参数与源字段传给具体子类，button 事件更新模型，Page.render 建立完整展示关系。
 metrics = Metrics(200, 44)
 rect = MeasuredRect(80, 20, 0, "#526AC7")
 button = Button("更新布局")

examples/source-paint.endor

@@ -1,15 +1,22 @@
+// 源 paint 产出真正进入窗口的 DisplayList；允许构造并修改本次计算的新命令，禁止改已有业务对象。
+// 同一 rect 出现两次，两份命令随同一 tint 更新；业务身份共享，几何按 Mount 分开。
+// 原生矩形测量不变，仅将绘制颜色切换为源字段 tint。
 class TintRect: RectBlock {
     tint: String
+    // 从原生基类取得当前出现位置的矩形命令，再修改本次返回列表中的颜色并交回。
     function paint(self: TintRect, mount: Mount, geometry: Bounds): DisplayList {
         drawing = RectBlock.paint(self, mount, geometry)
         drawing.commands.at(0).color = self.tint
         return drawing
     }
 }
+// 在原生文字前增加圆角底色，背景大小使用实际分配 geometry 而不是固定猜测值。
 class Badge: TextBlock {
     background: String
+    // 先完整填写 roundedRect 命令，再取原生文字命令改成白色；列表顺序决定先画背景后画文字。
     function paint(self: Badge, mount: Mount, geometry: Bounds): DisplayList {
         fill = PaintCommand()
+        // 命令 kind 决定宿主解码所需字段，坐标/宽高来自本次 Mount，radius/color 由业务策略提供。
         fill.kind = "roundedRect"
         fill.x = geometry.x
         fill.y = geometry.y
@@ -17,17 +24,21 @@ class Badge: TextBlock {
         fill.height = geometry.height
         fill.radius = 6
         fill.color = self.background
+        // 复用原生文字塑形和换行所需参数，避免手工文字命令漏掉边界。
         text = TextBlock.paint(self, mount, geometry).commands.at(0)
         text.color = "#FFFFFF"
         return DisplayList(ObjectList(fill, text))
     }
 }
+// 保存目标 TintRect，onEvent 是托管事件目标方法覆盖，不额外创建另一份状态。
 class RecolorButton: Button {
     target: TintRect
+    // 事件阶段可修改已有业务字段；依赖跟踪检测 tint 变化后重绘两个出现位置。
     function onEvent(self: RecolorButton, event: Event): Unit {
         self.target.tint = "#526AC7"
     }
 }
+// 两次使用 rect 是同一对象，Badge 与按钮独立；根容器只组合它们，不复制业务数据。
 rect = TintRect(200, 60, 12, "#DDEEFF", "#ED6A5A")
 badge = Badge("Endor 源码正在绘制这个背景", 2, "#237A45")
 button = RecolorButton("通过对象方法改变绘制颜色", rect)

examples/student-grades.endor

@@ -1,14 +1,19 @@
-// Student grades demo. Fictional records; in-memory only.
-// Paste the entire file into Tessera Console, then press Enter.
+// 学生成绩中心为纯内存演示，记录均虚构，不连接学校数据库。
+// 按钮操作 GradeCenter/Student 原对象；成绩行与摘要用 textOf 绑定，同一学生在全部/复核视图中复用业务身份。
+// 整个文件作为一次完整源码输入提交；状态只存在本次 VM，会话重置后不保留。
+// 为 Column 增加期望宽度字段，使手工表格各列对齐，而非让文字自然宽度决定列边界。
 class GradeCell: Column {
     width: Number
+    // 先保留 Column 的自然高度，再把新测量结果宽度设为字段值，最终仍由父约束协商。
     function measure(self: GradeCell, mount: Mount, constraints: Constraints): MeasureResult {
         size = Column.measure(self, mount, constraints)
         size.width = self.width
         return size
     }
 }
+// 背景绘制由源覆盖，子项仍按普通 Column 排列与绘制。
 class GradePanel: Column {
+    // 按本次 geometry 生成白色圆角底板；不重绘或复制子项命令，后代由统一遍历处理。
     function paint(self: GradePanel, mount: Mount, geometry: Bounds): DisplayList {
         fill = PaintCommand()
         fill.kind = "roundedRect"
@@ -21,6 +26,7 @@ class GradePanel: Column {
         return DisplayList(ObjectList(fill))
     }
 }
+// 姓名/学号和各科成绩/状态是业务字段；数值修改受 Number 声明检查。
 class Student {
     name: String
     number: String
@@ -29,9 +35,11 @@ class Student {
     english: Number
     status: String
 }
+// 用统一无 padding/gap 的单格容器包装任意 Block，末尾 width 是源字段构造参数。
 function gradeCell(content: Block, width: Number): Block {
     return GradeCell(0, 0, content, width)
 }
+// 姓名/学号直接取初值，成绩和状态用响应式 textOf；行末分隔线与固定列宽保持表格结构。
 function gradeRow(student: Student): Block {
     return Column(0, 12,
         Row(0, 0,
@@ -43,6 +51,7 @@ function gradeRow(student: Student): Block {
             gradeCell(ui.textOf(student, "status", 1, "#526C83"), 160)),
         RectBlock(730, 1, 0, "#EDF0F3"))
 }
+// 保存全部/复核两棵现成子树与可替换 table，同时持有要复核的真实 Student。
 class GradeCenter {
     table: Column
     all: Column
@@ -50,20 +59,24 @@ class GradeCenter {
     student: Student
     pending: Number
     message: String
+    // 替换稳定槽0的内容为全部行，复用已有学生，不重新请求/重建数据。
     function showAll(self: GradeCenter, event: Event): Unit {
         self.table.replace(0, self.all)
         self.message = "正在查看全部 6 位学生"
     }
+    // 切换到预先构造的复核行；这是特定示例子树，不是动态过滤算法。
     function showAttention(self: GradeCenter, event: Event): Unit {
         self.table.replace(0, self.attention)
         self.message = "林沐的数学成绩有一条复核记录"
     }
+    // 写预设数学成绩68及状态，清待复核数；相关绑定在两个视图都读同一 studentLin。
     function review(self: GradeCenter, event: Event): Unit {
         self.student.math = 68
         self.student.status = "已复核"
         self.pending = 0
         self.message = "已录入复核结果：林沐 · 数学 58 → 68"
     }
+    // 恢复初始学生值/计数并显示全部列表，便于重复观察同一操作。
     function reset(self: GradeCenter, event: Event): Unit {
         self.student.math = 58
         self.student.status = "待复核"
@@ -72,6 +85,7 @@ class GradeCenter {
         self.message = "已恢复示例数据"
     }
 }
+// 下面六条数据均本地构造；allGradeRows 与 attentionGradeRows 对 studentLin 建立不同视觉行但共享其业务值。
 studentLin = Student("林沐", "2026001", 86, 58, 91, "待复核")
 studentChen = Student("陈知夏", "2026002", 94, 96, 93, "已确认")
 studentXu = Student("许星河", "2026003", 82, 88, 85, "已确认")
@@ -81,15 +95,18 @@ studentLu = Student("陆景行", "2026006", 79, 84, 87, "已确认")
 allGradeRows = Column(0, 14, gradeRow(studentLin), gradeRow(studentChen), gradeRow(studentXu), gradeRow(studentZhou), gradeRow(studentSu), gradeRow(studentLu))
 attentionGradeRows = Column(0, 14, gradeRow(studentLin))
 gradeTable = Column(0, 0, allGradeRows)
+// table 最初含一个稳定子槽，后续 replace(0,...) 正是切换这个槽。
 gradeCenter = GradeCenter(gradeTable, allGradeRows, attentionGradeRows, studentLin, 1, "正在查看全部 6 位学生")
 showAllGrades = Button("全部学生")
 showAttentionGrades = Button("查看复核记录")
 reviewGrade = Button("录入复核成绩")
 resetGrades = Button("恢复示例数据")
+// 四个回调均接受 Event，绑定到同一 GradeCenter 接收者。
 showAllGrades.on("click", gradeCenter.showAll)
 showAttentionGrades.on("click", gradeCenter.showAttention)
 reviewGrade.on("click", gradeCenter.review)
 resetGrades.on("click", gradeCenter.reset)
+// 表头复用与数据行完全相同的列宽，摘要仅 pending 响应式，6/3是固定示例统计。
 gradeHeader = Row(0, 0,
     gradeCell(TextBlock("学生", 1, "#7A8390"), 150),
     gradeCell(TextBlock("学号", 1, "#7A8390"), 120),
@@ -101,6 +118,7 @@ gradeSummary = Row(0, 40,
     Column(0, 6, TextBlock("学生人数", 1, "#7A8390"), TextBlock("6", 2)),
     Column(0, 6, TextBlock("考试科目", 1, "#7A8390"), TextBlock("3", 2)),
     Column(0, 6, TextBlock("待复核", 1, "#7A8390"), ui.textOf(gradeCenter, "pending", 2)))
+// 最终一次 render 组合摘要、控制区和表格面板；message 绑定显示最近业务操作结果。
 gradesPage = Page()
 gradesPage.title = "学生成绩管理中心"
 gradesPage.render(Column(32, 20,

examples/tab-placement.endor

@@ -1,16 +1,23 @@
+// 页面位置与子项插入的代码示例：Page 方法覆盖计数，Container.insert 在指定位置创建稳定子槽。
+// 当前侧栏提供选择/关闭，文案中的拖放场景也可经版本化事件 API 测试；不要把它理解成已实现的侧栏拖动手势。
+// 继承 Page 后观察 moveToWindow/moveTab 的真实方法调用，保留原生迁移/重排行为。
 class TrackedPage: Page {
     calls: Object
+    // 先递增 calls，再显式调用基类执行跨窗迁移；Page 身份保留，旧 Mount 上下文会替换。
     function moveToWindow(self: TrackedPage, window: Window): Page {
         self.calls.increment()
         return Page.moveToWindow(self, window)
     }
+    // position 是所属窗口内最终零基位置，重排不等于创建新的业务 Page。
     function moveTab(self: TrackedPage, position: Number): Page {
         self.calls.increment()
         return Page.moveTab(self, position)
     }
 }
+// 保存容器业务对象，按钮插入只改变其子槽顺序，已有 child 的槽与 Mount 尽量保留。
 class Actions {
     list: Column
+    // 在索引 1 前插入新 TextBlock，返回的稳定槽可供 remove 等后续操作使用。
     function insert(self: Actions, event: Event): Unit {
         self.list.insert(1, TextBlock("插入的新对象"))
     }
@@ -20,6 +27,7 @@ list = Column(0, 8, TextBlock("第一个子项"), TextBlock("最后一个子项"
 actions = Actions(list)
 button = Button("在位置 1 插入 Block")
 connection = button.on("click", actions.insert)
+// A/C/目标页共享同一根及 list；各页激活时使用独立展示上下文，业务插入结果共享。
 shared = Column(24, 16, TextBlock("拖动 Tab 重排、移入另一个窗口，或拖出独立窗口"), TextBlock("Page 方法调用次数"), ui.textOf(calls,"value"), button, list)
 first = TrackedPage(calls)
 first.title = "A · 共享内容"
@@ -30,6 +38,7 @@ second.render(Column(24, 16, TextBlock("这是 B，Page 身份随 Tab 移动保
 third = TrackedPage(calls)
 third.title = "C · 同一对象"
 third.render(shared)
+// 建立目标窗口并指定桌面位置，MoveTo 使用物理桌面坐标且可能受窗口管理器调整。
 other = Window()
 other.resize(720,520)
 other.setTitle("Tab Target")
@@ -38,6 +47,7 @@ target = TrackedPage(calls)
 target.title = "目标窗口"
 target.render(shared)
 target.open(other)
+// 恢复源窗口首个页面，最后排出 resize/title/move/focus，便于手动或 API 验证。
 first.activate()
 ui.window().resize(800,600)
 ui.window().setTitle("Tab Source")

examples/tabs.endor

@@ -1,4 +1,7 @@
-// Code and tab chrome operate the same Page objects.
+// 代码与原生侧栏都操作真实 Page 对象；activate/close/open 改变展示关系，业务对象可继续被全局引用保留。
+// 三个页面共存于同一 VM，最后 first.activate 选择初始展示页。
+// 当前宿主通过侧栏管理页面；Page 的代码接口保持同一业务身份。
+// 创建持有计数器与按钮的页面；切到其他页不等于销毁 count。
 first = Page()
 first.title = "共享计数"
 count = ui.state(0)
@@ -6,12 +9,15 @@ increment = Button("加一")
 connection = increment.on("click", count.increment)
 first.render(Column(24,16,TextBlock("切换页面后，计数对象继续存在"),ui.textOf(count,"value"),increment))
 
+// 另一页演示 Page 生命周期与快捷键；界面提示是示例文案，实际导航位于当前宿主侧栏。
 second = Page()
 second.title = "另一个页面"
 second.render(Column(24,16,TextBlock("点击上方 Tab 切换；× 关闭页面"),TextBlock("Ctrl+Tab 切换，Cmd/Ctrl+W 关闭；代码可调用 first.open() 重开")))
 
+// 独立内容页面仍用同一个运行时的原生类型和资源注册表。
 third = Page()
 third.title = "窗口与布局"
 third.render(Column(24,16,TextBlock("每个 Tab 都是同一个 VM 中的 Page 对象"),RectBlock(240,80,8,"#237A45")))
+// 重新激活第一页面，原生侧栏和源查询可观察相同 active 状态。
 first.activate()
 ui.window().setTitle("Endor Pages")

examples/visual-protocols.endor

@@ -1,3 +1,6 @@
+// 原生视觉协议直接返回托管数据：Constraints/MeasureResult、Bounds/Arrangement 和 DisplayList 都可在源码中查询。
+// onMount 作为业务阶段收集结果；实际布局/绘制计算仍受只读规则约束。
+// 把协议探测结果保存到普通业务字段，textOf 将其中一部分显示出来。
 class VisualResults {
     width: Number
     height: Number
@@ -5,8 +8,10 @@ class VisualResults {
     childY: Number
     color: String
 }
+// 继承原生矩形，在自身挂载后用该 Mount 显式调用 measure/paint。
 class ProbeRect: RectBlock {
     results: VisualResults
+    // 有限最大宽 120 约束自然宽 200；另用自定义 Bounds 查询绘制颜色，把返回结果写进共享 results。
     function onMount(self: ProbeRect, mount: Mount): Unit {
         measured = self.measure(mount, Constraints(0, 0, 120, 80))
         self.results.width = measured.width
@@ -15,14 +20,17 @@ class ProbeRect: RectBlock {
         self.results.color = drawing.commands.at(0).color
     }
 }
+// 在挂载回调中探测原生排列，复用当前结构的稳定子槽。
 class ProbeColumn: Column {
     results: VisualResults
+    // 给定绝对起点(20,30)及容器范围，原生 padding=24 使首子项位于(44,54)。
     function onMount(self: ProbeColumn, mount: Mount): Unit {
         positions = self.arrange(mount, Bounds(20, 30, 500, 300))
         self.results.childX = positions.children.at(0).x
         self.results.childY = positions.children.at(0).y
     }
 }
+// 先创建结果容器，再将它作为源子类字段共享；root 的最后一个参数是该字段，不是视觉子项。
 results = VisualResults(0, 0, 0, 0, "等待挂载")
 rect = ProbeRect(200, 60, 12, "#DDEEFF", results)
 root = ProbeColumn(24, 16, TextBlock("对象的原生视觉协议", 2), rect, TextBlock("约束测量宽度"), ui.textOf(results, "width"), TextBlock("绘制颜色"), ui.textOf(results, "color"), results)

examples/window.endor

@@ -1,17 +1,25 @@
+// 托管 Window 资源与原生窗口相连：源码排出 resize/title 命令，成功刷新后由 GUI 线程执行。
+// 实际可用视口再返回布局约束，原生窗口尺寸不是业务对象上凭空写入的一份几何副本。
+// 保存目标 Window，两个按钮对同一资源请求不同尺寸。
 class WindowActions {
     window: Window
+    // 请求 900x600 逻辑尺寸，最终大小仍由窗口管理器决定。
     function compact(self: WindowActions, event: Event): Unit {
         self.window.resize(900, 600)
     }
+    // 请求 1120x720；同次输入多次 resize 可由命令队列合并到最后值。
     function wide(self: WindowActions, event: Event): Unit {
         self.window.resize(1120, 720)
     }
 }
+// 原生矩形的测量覆盖展示父约束如何随窗口变化。
 class WindowBand: RectBlock {
+    // 取当前出现位置 maxWidth 作为期望宽度，固定高 32；不读取其他窗口的尺寸。
     function measure(self: WindowBand, mount: Mount, constraints: Constraints): MeasureResult {
         return MeasureResult(constraints.maxWidth, 32)
     }
 }
+// ui.window 返回当前主窗口托管资源；page.open 指定同一资源，后面的 title/resize 为原生命令。
 window = ui.window()
 actions = WindowActions(window)
 band = WindowBand(80, 32, 0, "#237A45")

examples/windows.endor

@@ -1,18 +1,25 @@
-// Both native windows use one Aster VM and one shared business object.
+// 两个原生窗口共用一个 Aster VM 和 count 业务对象，各自拥有独立 Page 与 Mount。
+// 任一窗口点击都修改同一计数，两个 textOf 显示随之更新。关闭窗口解除 Page 归属，持有的业务对象仍可重开。
+// 跨窗共享的是业务对象，不是某个窗口中的具体 Mount。
+// 唯一计数来源；两个按钮直接使用同一零参数原生 increment 方法。
 count = ui.state(0)
 leftButton = Button("共享计数 +1")
 leftConnection = leftButton.on("click",count.increment)
+// 先在主窗口建立页面，render 默认选择该页并挂载它的内容。
 left = Page()
 left.title = "主窗口页面"
 left.render(Column(24,16,TextBlock("两个窗口操作同一个计数对象"),ui.textOf(count,"value"),leftButton))
 
+// Window() 分配同 VM 中的独立窗口资源，不创建第二个运行时。
 other = Window()
 rightButton = Button("另一个窗口 +1")
 rightConnection = rightButton.on("click",count.increment)
 right = Page()
 right.title = "独立窗口页面"
 right.render(Column(24,16,TextBlock("关闭窗口会解除 Page 归属，保留的对象仍可重开"),ui.textOf(count,"value"),rightButton))
+// 把页面放到 other，上下文更换将重建出现位置，业务 count 仍不变。
 right.open(other)
+// 窗口命令针对各自资源编号排队；成功输入后再交 GUI，另一窗口设置自己的尺寸。
 ui.window().setTitle("Endor Main")
 other.setTitle("Endor Shared")
 other.resize(960,640)

examples/workspace.endor

@@ -1,6 +1,8 @@
-// Paste the complete file into Console in Script mode, then Run.
-// All numbers, progress values and activity entries below are demo data.
+// 静态工作台组合示例：所有指标、进度与活动记录均为演示数据，不读取任务系统或网络。
+// 辅助函数返回视觉子树，最后统一 Page.render；它们是普通 Endor 函数，不是宿主特殊组件语法。
+// 将整个文件作为完整输入提交；这里没有实时指标提供方，全部数据由下面的常量生成。
 
+// 把标签、大数值、说明和色条纵向组合，参数控制文字与强调颜色。
 function metric(label: Text, value: Text, note: Text, color: Text): View {
     return ui.column(0, 6,
         ui.text(label, 1, "#637082"),
@@ -10,11 +12,14 @@ function metric(label: Text, value: Text, note: Text, color: Text): View {
     )
 }
 
+// 生成项目标题和状态，再用两个相邻矩形表示已完成/剩余长度；filled/remaining 是逻辑像素。
 function project(name: Text, state: Text, detail: Text, filled: Number, remaining: Number, color: Text): View {
+    // 项目名和状态横排，状态颜色与进度前景相同。
     let caption = ui.row(0, 12,
         ui.text(name, 1, "#243047"),
         ui.text(state, 1, color)
     )
+    // 两块矩形间 gap=0 合成连续条，条宽由调用方传入的演示数值决定。
     let progress = ui.row(0, 0,
         ui.rect(filled, 6, 3, color),
         ui.rect(remaining, 6, 3, "#E5EAF2")
@@ -26,6 +31,7 @@ function project(name: Text, state: Text, detail: Text, filled: Number, remainin
     )
 }
 
+// 组合小圆点、时间戳、标题与说明；spacer 仅作视觉对齐，不代表真实事件时间线。
 function activity(time: Text, title: Text, detail: Text, color: Text): View {
     let dot = ui.column(0, 0, ui.spacer(7), ui.rect(6, 6, 3, color))
     let stamp = ui.row(0, 8, dot, ui.text(time, 1, "#8490A0"))
@@ -36,6 +42,7 @@ function activity(time: Text, title: Text, detail: Text, color: Text): View {
     )
 }
 
+// 头部三个文本使用字号/颜色层级，后续 statistics 复用 metric 返回三组指标。
 let heading = ui.column(0, 6,
     ui.text("ENDOR STUDIO / WORKSPACE", 1, "#5263D6"),
     ui.text("项目工作台", 2, "#243047"),
@@ -48,6 +55,7 @@ let statistics = ui.row(0, 20,
     metric("页面草稿", "08", "等待下一次灵感", "#D9A34A")
 )
 
+// 纵向复用 project，示例名称与比例是常量，不做进度计算或持久化。
 let projects = ui.column(0, 14,
     ui.text("项目进度", 1, "#243047"),
     project("Aster", "进行中", "语言解析 / 编译 / 执行", 240, 60, "#6574E8"),
@@ -55,6 +63,7 @@ let projects = ui.column(0, 14,
     project("设计文档", "草稿", "Block / Page / 对象模型", 108, 192, "#D9A34A")
 )
 
+// 三条 activity 组成静态活动区，再与项目区横排成 body。
 let timeline = ui.column(0, 14,
     ui.text("最近活动", 1, "#243047"),
     activity("10:24", "更新字体", "中英文混排预览", "#6574E8"),
@@ -64,6 +73,7 @@ let timeline = ui.column(0, 14,
 
 let body = ui.row(0, 20, projects, timeline)
 
+// 底部提示以细色块和文字组合，明确说明页面还未接业务交互。
 let note = ui.row(0, 12,
     ui.rect(4, 46, 2, "#6574E8"),
     ui.column(0, 6,
@@ -72,6 +82,7 @@ let note = ui.row(0, 12,
     )
 )
 
+// 最终根统一设置 24px padding 与20px间距；创建辅助子树本身不会提前发布页面。
 let page = ui.page()
 page.render(ui.column(24, 20,
     heading,

examples/world-ui.endor

@@ -1,8 +1,12 @@
-// A normal Endor UI tree rendered on a transformed plane in the 3D world.
+// 世界空间 UI：普通 Endor 树先在独立 UI 分辨率中布局/绘制，再作为 Panel3D 平面的纹理参与三维深度。
+// 面板内还有 CanvasViewport，输入需经外层射线、面板 UV 和内层二维相机逐层转换。
+// 面板内容仍是完整 Endor UI，可共享对象、绑定、源视觉协议与嵌套视口。
+// 分别持有外层三维视口、面板变换和面板内二维画布，避免一次动作同时驱动多层相机。
 class WorldActions {
     view: Viewport3D
     panel: Panel3D
     canvas: CanvasViewport
+    // 重置三维相机位置与观察目标，不改变面板或内层画布业务状态。
     function reset(self: WorldActions): Unit {
         self.view.camera.x = 0
         self.view.camera.y = 0.5
@@ -11,19 +15,24 @@ class WorldActions {
         self.view.camera.targetY = 0
         self.view.camera.targetZ = 0
     }
+    // 只旋转 Panel3D 平面，面板内 UI 树仍用自己的逻辑宽高。
     function turn(self: WorldActions): Unit { self.panel.rotate(0, 15, 0) }
+    // 找到画布当前 Mount，按该出现位置的有限尺寸 fitView，而非用外层三维视口大小。
     function fit(self: WorldActions): Unit { self.canvas.mounts().at(0).fitView() }
 }
 count = ui.state(0)
 increment = Button("点击：世界里的真实按钮")
 increment.onClick(count.increment)
+// 二维场景卡片使用带符号世界坐标；canvas 再提供有限可见区域和独立 camera。
 card = Column(10, 6, TextBlock("CanvasViewport", 1), RectBlock(180, 26, 6, "#9CB8A8"))
 card.boxWidth = 240
 card.x = 10
 card.y = 4
 canvas = CanvasViewport(280, 80, Scene2D(card))
+// 普通 Column、文字、按钮和二维画布组成 UI 树，按钮仍修改同一个 count。
 ui_root = Column(8, 8, TextBlock("世界空间 UI", 2), ui.textOf(count, "value", 2), increment, canvas)
 ui_root.crossAlign = "stretch"
+// 4x3 是三维世界尺寸，320x240 是 UI 布局/纹理分辨率；两者独立控制显示比例与清晰度。
 panel = Panel3D(4, 3, ui_root)
 panel.uiWidth = 320
 panel.uiHeight = 240
@@ -34,8 +43,10 @@ cube.x = 2
 cube.rotationY = 25
 floor = Box3D(10, 0.08, 5, "#D8DEE6")
 floor.y = -1.8
+// 面板与普通网格/地面共处一个深度场景，实体可遮挡面板，也阻挡被遮住的 UI 命中。
 scene = Scene3D(panel, cube, floor, DirectionalLight(-1, -2, -3, "#FFFFFF", 0.9))
 scene.ambient = 0.35
+// 外层 Viewport3D 作为二维布局里的 flex 子项；相机控制外部观察，而非 UI 内部滚动。
 view = Viewport3D(960, 520, scene)
 view.flex = 1
 view.camera.y = 0.5
@@ -47,6 +58,7 @@ turn = Button("转动 UI 面板")
 turn.onClick(actions.turn)
 fit = Button("适配面板内的画布")
 fit.onClick(actions.fit)
+// 控制按钮保持在二维页面空间，外层三维内容作为一个区域随布局伸展。
 body = Column(24, 16, TextBlock("UI → 3D 世界 → UI → Canvas", 2), view, Row(0, 12, reset, turn, fit), TextBlock("空白处左键拖动旋转 3D · 中键/空格平移 · 滚轮缩放\n面板里的按钮、文本、布局和画布都由同一份 Endor 对象驱动。"))
 body.flex = 1
 body.crossAlign = "stretch"

examples/wrapped-text.endor

@@ -1,18 +1,28 @@
+// 多窗口共享长段落：同一文字对象在每个 Mount 按当前宽度独立换行，后继位置跟随实际高度。
+// 源子类显式委托原生 measure/paint，保留系统字体塑形、组合字符和 emoji 的行为。
+// 没有独立宽度副本；约束与换行结果属于出现位置，文本内容属于共享对象。
 class Paragraph: TextBlock {
+    // 将当前 Mount 与 Constraints 交给原生文字测量，宽度变化触发重测高度。
     function measure(self: Paragraph, mount: Mount, constraints: Constraints): MeasureResult {
         return TextBlock.measure(self, mount, constraints)
     }
+    // 使用本次 geometry 画文字，和原生测量采用相同换行区域。
     function paint(self: Paragraph, mount: Mount, geometry: Bounds): DisplayList {
         return TextBlock.paint(self, mount, geometry)
     }
 }
+// 保存主窗口、共享文字和原全文，四个按钮分别改窗口尺寸或改文字内容。
 class Actions {
     window: Window
     paragraph: TextBlock
     full: String
+    // 请求主窗口变窄；真正的 viewport 由原生尺寸回传后影响换行。
     function narrow(self: Actions, event: Event): Unit { self.window.resize(800, 650) }
+    // 请求主窗口变宽，文字高度随之减小，不改另一窗口尺寸。
     function wide(self: Actions, event: Event): Unit { self.window.resize(1200, 650) }
+    // 用短文本替换同一对象内容，两个窗口的文字都重新测量。
     function short(self: Actions, event: Event): Unit { self.paragraph.setText("短文本：同一个对象、同一个 Mount。") }
+    // 恢复保存的 full 字符串，不创建新的 Paragraph。
     function restore(self: Actions, event: Event): Unit { self.paragraph.setText(self.full) }
 }
 full = "GUI 和代码操控同一套 Aster 内存对象。这个段落同时出现在两个窗口：对象内容相同，每个 Mount 根据自己的可用宽度换行。窗口变窄，段落高度增加，后面的对象向下移动；窗口变宽，段落高度减小，后面的对象向上移动。对象身份和已有 Mount 身份保持稳定。English words wrap at word boundaries; a_long_unbroken_identifier_also_wraps_when_it_cannot_fit_on_one_line. 中文、组合字符 é 与 emoji 👩‍💻 使用同一套字体整形。再次修改文字会重新计算高度，并更新两个窗口，不需要复制业务对象。"
@@ -30,6 +40,7 @@ restoreConnection = restore.on("click", actions.restore)
 page = Page()
 page.title = "约束下的文字换行"
 page.render(Column(24, 16, Row(0, 12, narrow, wide, short, restore), paragraph, tail))
+// 新窗口有独立可用宽度，但 second.render 仍用同一 paragraph，所以两个 Mount 可有不同高度。
 other = Window()
 other.resize(720, 500)
 other.setTitle("同一个段落 · 另一组宽度")
@@ -38,6 +49,7 @@ second = Page()
 second.title = "共享 Paragraph"
 second.render(Column(24, 16, paragraph))
 second.open(other)
+// 恢复主页面活动状态并设置原生窗口尺寸/标题/桌面位置，focus 命令在成功输入后交宿主执行。
 page.activate()
 ui.window().resize(800, 650)
 ui.window().setTitle("文字换行与相邻布局")

scripts/build-macos-app.sh

@@ -1,16 +1,21 @@
 #!/bin/sh
-# Native macOS build and app bundle. No Docker, mirror configuration, or tests.
+# macOS 应用打包入口：构建 release 可执行文件并组装最小 Tessera.app；脚本本身不运行测试或部署。
+# 执行会产生构建产物，应在已确认的 macOS 构建环境中调用。
+# 任一命令失败或使用未定义变量即退出，避免在失败编译后继续打包旧文件。
 set -eu
 # 此入口只能在 macOS 使用；构建授权由调用方确认，脚本不自动执行测试或部署。
 if [ "$(uname -s)" != Darwin ]; then
     echo "Build this app bundle on macOS." >&2
     exit 1
 fi
+# 以脚本所在目录的父目录作为仓库根；清空这一次 cd 的 CDPATH，防止用户 shell 配置改变目录解析。
 cd "$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
 # 锁定依赖并生成 release 可执行文件；附加参数原样交给 Cargo。
 cargo build --release --locked "$@"
+# 从 Cargo 包元数据读取首个 version 值，空值由 test 拒绝，不生成缺版本的 bundle。
 version=$(awk -F '"' '$1 ~ /^version[[:space:]]*=/ { print $2; exit }' Cargo.toml)
 test -n "$version"
+# macOS bundle 约定：Contents/MacOS 保存入口二进制，Contents/Info.plist 保存系统识别信息。
 bundle="$(pwd)/target/release/Tessera.app"
 mkdir -p "$bundle/Contents/MacOS"
 # 先写临时文件再重命名，避免复制途中将半个二进制留作 bundle 的主程序。
@@ -31,5 +36,7 @@ cat > "$bundle/Contents/Info.plist.new" <<PLIST
   <key>NSHighResolutionCapable</key><true/>
 </dict></plist>
 PLIST
+# 元数据完整写入后再替换正式文件；这只是单文件替换，不表示整个 bundle 的构建具有事务回滚。
 mv -f "$bundle/Contents/Info.plist.new" "$bundle/Contents/Info.plist"
+# 标准输出返回最终 app 路径，便于构建调用方定位产物。
 printf '%s\n' "$bundle"

scripts/render-uml.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// Documentation-only tool. Install pinned packages in a separate temporary directory;
-// UML_RENDER_TOOLS points there. No app dependencies or remote rendering service.
+// 文档 UML 批量渲染入口：读取仓库内 .puml，在 rendered 中写入 SVG/PNG。
+// 固定版本的工具包安装到独立临时目录，由 UML_RENDER_TOOLS 指定；不会修改应用依赖。
 import { createRequire } from 'node:module';
 import { readFile, readdir, mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -9,13 +9,14 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 const tools = process.env.UML_RENDER_TOOLS;
 // 工具依赖放在独立目录，避免给应用运行依赖增加文档渲染包。
 if (!tools) throw new Error('Set UML_RENDER_TOOLS to the documentation tool directory; see docs/architecture/uml/README.md');
+// 从工具目录的 package.json 创建专用 require，所有渲染依赖均从该目录解析，不依赖运行时 cwd。
 const require = createRequire(path.join(path.resolve(tools), 'package.json'));
 const { createCanvas } = require('@napi-rs/canvas');
 const { DOMImplementation, XMLSerializer, DOMParser } = require('@xmldom/xmldom');
 const sharp = require('sharp');
 
-// PlantUML's official JS engine uses DOM construction and Canvas text metrics.
-// Supply a real XML DOM and native Canvas metrics, not approximate text widths.
+// 官方 PlantUML JS 引擎依赖 DOM、Graphviz 和 Canvas 文本度量。
+// 在导入引擎前补齐全局环境，让 Node 进程可执行原本面向浏览器的布局过程。
 globalThis.PLANTUML_VIZ = require('@viz-js/viz');
 globalThis.window = globalThis;
 globalThis.XMLSerializer = XMLSerializer;
@@ -23,15 +24,17 @@ globalThis.DOMParser = DOMParser;
 const document = new DOMImplementation().createDocument(null, 'root', null);
 const element = document.createElement.bind(document);
 const elementNS = document.createElementNS.bind(document);
+// 创建只用于文本度量的 1x1 Canvas。此对象不承载最终图片像素，字体实际尺寸由原生引擎返回。
 function measurementCanvas() {
   // PlantUML 的文本布局需要真实字体宽高，统一用本机 Canvas 测量而非固定字符宽度。
   const canvas = createCanvas(1, 1);
   const context = canvas.getContext('2d');
   const measure = context.measureText.bind(context);
+  // 包装测量结果，修正 PlantUML 用于行距的 ascent/descent；保留其他真实 metrics 字段。
   context.measureText = text => {
     const metrics = measure(text);
-    // PlantUML uses this height for line spacing. Font-wide ascent/descent
-    // keeps adjacent class fields from colliding when glyphs lack descenders.
+    // 优先使用整套字体的上下界，而非当前字符串字形界；
+    // 否则不带下伸部的文字可能使相邻类字段的行距过小而重叠。
     return {
       ...metrics,
       width: metrics.width,
@@ -41,11 +44,13 @@ function measurementCanvas() {
   };
   return canvas;
 }
+// 普通标签交给 XML DOM，只有 canvas 替换为可实际 measureText 的原生对象。
 document.createElement = tag => tag === 'canvas' ? measurementCanvas() : element(tag);
 document.createElementNS = (namespace, tag) => {
   // 为无浏览器 DOM 补齐样式与 getBBox，满足官方渲染引擎的 SVG 文本布局需求。
   const node = elementNS(namespace, tag);
   node.style = {};
+  // 无浏览器布局树时只模拟当前文字节点的包围盒：字体来自 SVG 属性，y 从基线向上偏移。
   node.getBBox = () => {
     const context = measurementCanvas().getContext('2d');
     context.font = `${node.getAttribute('font-size') || 14}px ${node.getAttribute('font-family') || 'Arial'}`;
@@ -63,20 +68,23 @@ document.body = element('body');
 document.documentElement.appendChild(document.body);
 globalThis.document = document;
 const { renderToString } = await import(pathToFileURL(require.resolve('@plantuml/core')));
+// 仓库位置由脚本 URL 确定，与调用者工作目录无关；输出目录不存在时创建。
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const source = path.join(root, 'docs/architecture/uml');
 const output = path.join(source, 'rendered');
 await mkdir(output, { recursive: true });
+// 按文件名排序使处理顺序/日志稳定，只处理本目录的 .puml，不递归扫描产物目录。
 for (const filename of (await readdir(source)).filter(name => name.endsWith('.puml')).sort()) {
   // 每张图独立渲染并检查错误文本；错误图不能被当作正常产物覆盖已有预览。
   const text = await readFile(path.join(source, filename), 'utf8');
+  // 将引擎 resolve/reject 回调适配为 Promise，逐图等待；渲染失败直接终止，不覆盖该图产物。
   const rendered = await new Promise((resolve, reject) => renderToString(text.split('\n'), resolve, reject));
   const xml = new DOMParser().parseFromString(rendered, 'image/svg+xml');
   const labels = Array.from(xml.getElementsByTagName('text'), node => node.textContent).join('\n');
   if (xml.documentElement.tagName !== 'svg' || /syntax error|error line|assumed diagram type|an error has occurr/i.test(labels)) {
     throw new Error(`${filename}: renderer returned an error diagram\n${labels}`);
   }
-  // Explicit opaque paper keeps arrows/labels legible in dark Markdown viewers.
+  // 在最前方加入不透明白纸背景，保证深色 Markdown 查看器中的箭头与文字仍可辨认。
   const paper = xml.createElementNS('http://www.w3.org/2000/svg', 'rect');
   for (const [key, value] of Object.entries({ x: '0', y: '0', width: '100%', height: '100%', fill: '#FFFFFF' })) paper.setAttribute(key, value);
   xml.documentElement.insertBefore(paper, xml.documentElement.firstChild);
@@ -84,7 +92,7 @@ for (const filename of (await readdir(source)).filter(name => name.endsWith('.pu
   // 同时保存可缩放 SVG 和通用 PNG；写完读取 PNG 元数据确认生成尺寸。
   const stem = filename.slice(0, -5);
   await writeFile(path.join(output, `${stem}.svg`), svg);
-  // High-resolution PNG is the universally visible Markdown preview; SVG keeps zoomable text.
+  // 以 192 DPI 光栅化为 PNG 供通用预览；SVG 同时保留矢量文字和缩放能力。
   const png = sharp(Buffer.from(svg), { density: 192 });
   await png.png().toFile(path.join(output, `${stem}.png`));
   const metadata = await sharp(path.join(output, `${stem}.png`)).metadata();

src/bridge/mod.rs

@@ -1,4 +1,5 @@
 //! 语言桥接模块入口。集中导出 Endor 类型和宿主实现之间的适配层。
 //!
-// Module ownership follows the directory; crate-root aliases keep internal call sites stable.
+// 目录确定模块归属；main 中的 crate 根别名保持内部调用路径稳定。
+/// 注册托管类型/宿主方法，验证参数并连接业务对象、Mount、视觉协议与窗口/任务资源。
 pub(crate) mod ui_bridge;

src/bridge/ui_bridge.rs

@@ -30,6 +30,7 @@ pub const MAX_UI_NODES: usize = 4096;
 pub const MAX_PAGES: usize = 64;
 pub const MAX_DIMENSION: f64 = 1_000_000.0;
 
+// 编译器已知宿主全局类型/能力名，同时用于 install_globals；仅列名不代表绕过实际 VM 名义类型查找。
 pub const TYPE_NAMES: &[&str] = &[
     "Object",
     "Type",
@@ -102,7 +103,9 @@ struct Session {
     current: u64,
     master: ObjectRef,
     next_window: u64,
+    // 跨窗口共用 Mount 高水位，避免某窗口取消/重建后与其他窗口已暴露出现 ID 重合。
     next_mount: u64,
+    // 正常关闭副窗口后暂存尚待发布的 Close 等命令；Presentation 已移除也不能丢掉最后的原生退役请求。
     retired_commands: Vec<crate::window::Command>,
     refresh_yields: usize,
     refresh_restarts: usize,
@@ -127,6 +130,7 @@ impl std::ops::Deref for Session {
     type Target = crate::presentation::Presentation;
     /// 将包装类型的只读访问转交给内部当前上下文。
     fn deref(&self) -> &Self::Target {
+        // Session 解引用始终指向 current Presentation；调用源回调前切换窗口，结束后恢复主窗口，不能把它当全局唯一展示。
         self.presentations
             .get(&self.current)
             .expect("selected presentation")
@@ -211,9 +215,10 @@ enum Operation {
 }
 
 impl Operation {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 返回该操作显式参数数量范围；这里不计接收者、Type 首参和源子类字段。
     fn arity(self) -> endor_core::CallArity {
         use Operation::*;
+        // 此 arity 只含显式参数；TypeMethod 另加 receiver，NativeFactory 另加 Type 和子类字段外壳。
         let (minimum, maximum) = match self {
             IsInstance | IsSubtype | Bind | Implement | Implements | Supports => (2, 2),
             Stats | Viewport | Window | PageWindow | Mounts => (0, 0),
@@ -254,6 +259,7 @@ struct Function {
     operation: Operation,
     owner: Option<ObjectRef>,
     session: Shared,
+    // 原生构造的实际源子类身份；自由 ui 工厂为 None，类型构造器显式传入 Some。
     requested_type: Option<ObjectRef>,
 }
 
@@ -291,7 +297,7 @@ impl NativeCallable for TypeMethod {
     fn signature(&self) -> Option<CallSignature> {
         Some(self.signature.clone())
     }
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 在 Operation 的显式参数范围两端各加一，计入 VM 传入的隐式接收者。
     fn arity(&self) -> Option<endor_core::CallArity> {
         let arity = self.operation.arity();
         Some(endor_core::CallArity::range(
@@ -300,8 +306,9 @@ impl NativeCallable for TypeMethod {
         ))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 校验首参是预期名义类型实例，再剥离接收者，复用 Function 分派执行同一 Operation。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
+        // 名义方法统一存在类型上，VM 把 receiver 放首参；校验后剥离 receiver 再交 Function 的显式参数分派。
         let owner = object(args.first())?;
         if !cx.store().is_instance(owner, self.expected)? {
             return Err(invalid("incorrect receiver type for visual method"));
@@ -333,7 +340,7 @@ impl NativeCallable for NativeFactory {
     fn signature(&self) -> Option<CallSignature> {
         self.signature.clone()
     }
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 要求原生必填参数再加一个请求 Type；上界暂开放，子类字段与原生选项在 invoke 内分别校验。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::range(
             self.operation.arity().required + 1,
@@ -341,7 +348,7 @@ impl NativeCallable for NativeFactory {
         ))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 把请求类型的字段后缀与原生选项前缀分开验证，分配真实原生子类并初始化字段，避免非法字段先触发构造副作用。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let requested = object(args.first())?;
         let fields = cx
@@ -350,12 +357,14 @@ impl NativeCallable for NativeFactory {
             .fields()
             .to_vec();
         let values = &args[1..];
+        // 构造实参末尾是类型声明的继承/自有字段，前缀才是原生构造选项；checked_sub 防止缺字段造成下溢。
         let native_count = values
             .len()
             .checked_sub(fields.len())
             .ok_or(invalid("missing subclass field arguments"))?;
         cx.store()
             .check_class_field_arguments(requested, &values[native_count..])?;
+        // 外壳允许宽变参，但原生前缀仍按具体 Operation 完整签名检查，不能因子类存在绕过类型或 arity。
         self.options
             .as_ref()
             .ok_or(invalid("native factory is not initialized"))?
@@ -375,6 +384,7 @@ impl NativeCallable for NativeFactory {
         let NativeResult::Return(Value::Object(instance)) = result else {
             return Err(invalid("native constructor did not return an instance"));
         };
+        // 分配器必须返回精确 requested 类型，不能只返回基类实例；之后才初始化子类字段。
         if cx.store().type_of(instance)? != Some(requested) {
             return Err(invalid(
                 "native constructor returned an incorrect nominal type",
@@ -429,6 +439,7 @@ fn dimension(value: Option<&Value>) -> Result<f32, VmError> {
     let Some(Value::Number(number)) = value else {
         return Err(invalid("expected a finite nonnegative dimension"));
     };
+    // 分别支持大整数、十进制和二进制实数表示，不接受非实值；转 f64 后检查有限与范围，再降 f32。
     let value = match number.as_real() {
         Some(EndorReal::Integer(v)) => v.to_string().parse::<f64>().ok(),
         Some(EndorReal::Decimal(v)) => v.literal().parse::<f64>().ok(),
@@ -461,6 +472,7 @@ fn bind(
             session: session.clone(),
             requested_type: None,
         },
+        // 绑定方法显式捕获 owner 与 desktop，让托管 GC 识别函数的真实强边，Rust Shared 会话本身不隐式保活 VM 对象。
         vec![owner, desktop],
     ))?;
     attach_desktop_type(cx, function, "Function", desktop)?;
@@ -498,6 +510,7 @@ fn new_camera2d(
             .unwrap_or(fallback);
         cx.set_attr(camera, name, crate::native_visual::value(value))?;
     }
+    // 初始化完所有相机属性后走完整相机校验，尤其 zoom 必须处于 0.01..100，不能只通过一般坐标范围。
     crate::viewport::camera(cx.store(), camera)?;
     Ok(camera)
 }
@@ -530,6 +543,7 @@ fn new_typed_block(
         .desktop;
     let expected = desktop_type(cx.store(), type_name, desktop)?;
     let type_object = requested.unwrap_or(expected);
+    // 叶/容器原生种类对应不同类型基类，禁止用 TextBlock 分配器创建并非其子类的名义对象。
     if !cx.store().is_subtype(type_object, expected)? {
         return Err(invalid("native constructor cannot allocate this subclass"));
     }
@@ -537,6 +551,7 @@ fn new_typed_block(
     cx.attach_type(block, type_object)?;
     {
         let mut state = session.lock().map_err(|_| invalid("UI session poisoned"))?;
+        // 节点弱表受宿主预算限制；实际死亡弱项通过后续 reclaim 压缩，不能把弱索引当永不增长的免费结构。
         if state.nodes.len() >= MAX_UI_NODES {
             return Err(VmError::ExecutionLimit("4096 node budget"));
         }
@@ -572,6 +587,7 @@ fn create_window(
     if state.exiting {
         return Err(invalid("runtime is exiting; window creation is forbidden"));
     }
+    // 同一 VM 最多16窗口（含主壳）；ID 单调分配并限制到 i64 正范围，关闭后不复用旧资源身份。
     if state.presentations.len() >= 16 {
         return Err(VmError::ExecutionLimit("16 window budget"));
     }
@@ -582,6 +598,7 @@ fn create_window(
         .ok_or(invalid("window identities exhausted"))?;
     let (window, desktop, tabs) = crate::window::create(cx, state.master, id, definition)?;
     let mut presentation = crate::presentation::Presentation::new(desktop, tabs);
+    // 新窗口即使暂无内容也需发布有限空帧，让 GUI 根据投影创建 OS 窗口，而不是在 VM 中直接创建。
     presentation.force_frame = true;
     state.presentations.insert(id, presentation);
     state.next_window = id;
@@ -610,6 +627,7 @@ fn remove_page(
 ) -> Result<(), VmError> {
     let window = object(Some(&cx.store().get_attr(view.desktop, "window")?))?;
     crate::window::unregister_page(cx, window, page)?;
+    // 双层 pending 区分无请求与请求清空；移除当前/待选页时改选剩余第一页，或显式 pending=None页面。
     if view.pending.unwrap_or(view.active) == Some(page) {
         let next = crate::window::pages(cx.store(), window)?.first().copied();
         cx.set_attr(
@@ -631,6 +649,7 @@ fn show_in(
     let mut state = session.lock().map_err(|_| invalid("UI session poisoned"))?;
     let old = page_window(cx.store(), &state, page)?;
     let id = match target {
+        // 显式目标窗口既要未关闭，也要对应本会话 Presentation 的同一 desktop，拒绝其他 VM 的窗口身份。
         Some(window) => {
             let data = cx
                 .store()
@@ -648,11 +667,13 @@ fn show_in(
             }
             id
         }
+        // 不指定窗口时优先保留 Page 现有归属；未打开过的新页才进入 current，而非每次 activate 都迁移到主窗口。
         None => old.unwrap_or(state.current),
     };
     if let Some(old) = old
         && old != id
     {
+        // 跨窗口移动先撤源窗口登记与必要活动页选择，再在目标登记同一 Page，业务内容对象不复制。
         remove_page(
             cx,
             state
@@ -669,6 +690,7 @@ fn show_in(
     let window = object(Some(&cx.store().get_attr(view.desktop, "window")?))?;
     crate::window::register_page(cx, window, page)?;
     cx.set_attr(view.desktop, "pending", Value::Object(page))?;
+    // 仅记录展示请求并由 desktop.pending 强持有 Page；实际 active、Mount、布局和 published_version 留待刷新提交。
     view.pending = Some(Some(page));
     Ok(())
 }
@@ -684,17 +706,18 @@ struct PresentResult {
     session: Shared,
 }
 impl NativeCallable for PresentResult {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 接收 present 委托返回的唯一视觉对象，作为后续展示处理的输入。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(1))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 验证 present 结果为 Block；open 模式必要时包装 Page 并展示，否则只返回转换得到的视觉对象。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let [Value::Object(root)] = args else {
             return Err(invalid("Presentable.present must return a Block"));
         };
         let is_page = cx.store().payload::<block::Block>(*root, "Block")?.page;
+        // present 委托返回值必须为 Block；open=true 必要时包 Page 并展示，open=false 只返回转换结果。
         let result = if self.open {
             let page = if is_page {
                 *root
@@ -714,7 +737,7 @@ impl NativeCallable for PresentResult {
     }
 }
 
-/// 根据 Presentable 能力把任意源值转换成可展示内容，避免只允许某个原生 Block 类型。
+/// 返回已有 Block，或把其他值的可读表示包装成 TextBlock；Presentable 委托由外层调用分派负责。
 fn present_value(
     cx: &mut NativeContext<'_>,
     value: &Value,
@@ -730,6 +753,7 @@ fn present_value(
     {
         return Ok(*block);
     }
+    // 非 Block 的标量/对象转可读文字，Presentable 方法委托在 calls.rs 的更外层处理，本函数不自己调用 present。
     let value = match value {
         Value::Nil => "nil".into(),
         Value::Bool(v) => v.to_string(),
@@ -771,7 +795,9 @@ struct LayoutContext {
     full_viewport: Option<crate::layout::Size>,
     desktop: ObjectRef,
     window: u64,
+    // 布局同步返回的生命周期序列拥有根，暂留到安全提交边界执行/释放，取消时也必须清理。
     hooks: Option<ObjectRef>,
+    // 布局准备可能暂改 Mount payload 与 desktop.mounts，检查点保证失败或尺寸重定向能恢复未发布关系。
     checkpoint: crate::mount::Checkpoint,
 }
 
@@ -796,6 +822,7 @@ fn invoke_member(
     arguments: &[Value],
     instruction_budget: usize,
 ) -> Result<Value> {
+    // 使用 VM 正常绑定规则创建临时方法值；无论 call 成功/失败，先保存 result 再释放 bound 根。
     let bound = vm.bind_attr(owner, method)?;
     let result = match &bound {
         Value::Object(function) => vm
@@ -821,11 +848,13 @@ fn project_tabs(
 ) -> Result<Vec<crate::tabs::Tab>> {
     let window = object(Some(&vm.get_attr(state.desktop, "window")?))?;
     let pages = crate::window::pages(vm.object_store(), window)?;
+    // 标签选中反映待提交页面（若有请求），否则沿用 active；页面标题和顺序仍从真实窗口注册表提取。
     let active = state.pending.unwrap_or(state.active);
     let mut live = Vec::new();
     let mut tabs = Vec::new();
     for (index, page) in pages.iter().copied().enumerate() {
         let weak = vm.object_store().downgrade(page)?;
+        // 同一 Page 弱身份复用该窗口标签 ID，新增页用高水位；移出后 live 更新会移除旧映射，不靠标题匹配。
         let id = if let Some((_, id)) = state.tab_ids.iter().find(|(w, _)| *w == weak) {
             *id
         } else {
@@ -836,6 +865,7 @@ fn project_tabs(
             state.next_tab
         };
         live.push((weak, id));
+        // 标题显示过滤控制字符并限制120个 Unicode 字符，缺失/空标题用默认序号；不修改原 Page.title。
         let title = match vm.get_attr(page, "title") {
             Ok(Value::Text(title)) if !title.is_empty() => title
                 .chars()
@@ -863,6 +893,7 @@ impl UiBridge {
     /// already closed before source unmount hooks run, so they cannot remount.
     /// 按窗口和展示生命周期执行有界退出清理，允许调用方根据故障状态决定是否执行回调。
     pub fn shutdown(&self, vm: &mut Vm, callbacks: bool) -> Result<(usize, usize, usize)> {
+        // 退出先关闭新任务入口并取消旧任务，再标 session.exiting，避免卸载回调重新创建任务/窗口。
         let tasks = self.tasks.quiesce(vm)?;
         let mut drivers = Vec::new();
         let mut mounts = 0;
@@ -877,6 +908,7 @@ impl UiBridge {
                 let view = state.presentations.get_mut(id).expect("known window");
                 let desktop = view.desktop;
                 mounts += view.mounts.active.len();
+                // 正常域用空结构 synchronize 安排孩子先卸载的 hooks；故障域直接 retire，不能再次执行用户代码。
                 if callbacks {
                     if let Some(hooks) = view.mounts.synchronize(
                         vm,
@@ -892,6 +924,7 @@ impl UiBridge {
                     view.mounts.retire(vm, desktop)?;
                 }
                 let window = object(Some(&vm.get_attr(desktop, "window")?))?;
+                // 所有窗口先标 closed 并断 Page 拥有关系，然后才在下面执行用户卸载 hooks，阻止回调重新打开已关闭窗口。
                 crate::window::retire(vm, window)?;
                 vm.set_attr(desktop, "pending", Value::Nil)?;
                 vm.set_attr(desktop, "focus", Value::Nil)?;
@@ -902,6 +935,7 @@ impl UiBridge {
             Ok(ids.len())
         })();
         let mut result = prepared.map(|windows| (windows, mounts, tasks));
+        // 若之前清理/回调失败，余下 hooks 不再执行，但所有驱动根仍逐项 release，避免失败路径泄漏。
         for (id, hooks) in drivers {
             if result.is_ok() {
                 let call = (|| -> Result<()> {
@@ -951,6 +985,7 @@ impl UiBridge {
             .lock()
             .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
         let mut ids: Vec<_> = state.presentations.keys().copied().collect();
+        // 优先处理切离旧 active 页的窗口，使跨窗口迁移先退旧出现再挂新出现；同优先级按窗口 ID 稳定排序。
         ids.sort_by_key(|id| {
             let view = &state.presentations[id];
             (
@@ -1009,6 +1044,7 @@ impl UiBridge {
         vm.set_attr(desktop, "focus", Value::Nil)?;
         vm.set_attr(desktop, "focusRequested", Value::Bool(false))?;
         // Draining is not publication: failed-domain effects are discarded.
+        // 故障宿主退役的命令只丢弃不发布，防止失败域遗留 Resize/Focus 等影响当前原生状态。
         let _ = crate::window::take_commands(vm, window)?;
         let windows = object(Some(&vm.get_attr(state.master, "windows")?))?;
         vm.dict_delete(windows, &Value::Text(id.to_string()))?;
@@ -1023,6 +1059,7 @@ impl UiBridge {
             .session
             .lock()
             .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
+        // 正常 finish_closed 只移除已标 closing 的副窗口，主壳保持到 OS 退出；其最后命令转存 retired_commands 待发布。
         let ids: Vec<_> = state
             .presentations
             .iter()
@@ -1048,6 +1085,7 @@ impl UiBridge {
             .session
             .lock()
             .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
+        // 先取已移除窗口的最后命令，再合并仍活动窗口 outbox；按窗口/窗口内序号排序，不丢失正常 Close 请求。
         let mut commands = std::mem::take(&mut state.retired_commands);
         for view in state.presentations.values() {
             let window = object(Some(&vm.get_attr(view.desktop, "window")?))?;
@@ -1071,6 +1109,7 @@ impl UiBridge {
             .session
             .lock()
             .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
+        // 尺寸比较在分配新输入对象前完成，避免相同 resize 通知改变 VM 版本而触发自我失效。
         if state.layout.viewport == viewport {
             return Ok(false);
         }
@@ -1081,6 +1120,7 @@ impl UiBridge {
                 vm.set_attr(input, "height", Value::Number((size.height as f64).into()))?;
                 vm.set_attr(state.desktop, "viewport", Value::Object(input))
             })();
+            // desktop 已建立 viewport 强边后释放局部根；字段/安装失败也先释放 input，再传播保存的错误。
             vm.release(input)?;
             result?;
         } else {
@@ -1089,6 +1129,7 @@ impl UiBridge {
         state.layout.viewport = viewport;
         // A fresh Console domain can own window inputs without replacing the
         // preserved displayed page until it actually opens/renders something.
+        // 空的新 Console 域可以记录逻辑尺寸，但未展示任何 Page 时不应覆盖用户仍看到的旧域画面。
         state.force_frame |= state.active.is_some() || state.pending.flatten().is_some();
         Ok(true)
     }
@@ -1102,6 +1143,7 @@ impl UiBridge {
             Value::Text("View".into()),
             vm.get_attr(self.ui, "Block")?,
         )?;
+        // 全局名引用 ui 中同一批名义类型/函数对象，模块和 Console 不会各复制一份类型体系。
         for name in TYPE_NAMES.iter().chain(QUERY_NAMES) {
             let value = vm.get_attr(self.ui, name)?;
             vm.dict_set(globals, Value::Text((*name).into()), value)?;
@@ -1126,6 +1168,7 @@ impl UiBridge {
         let Ok(state) = self.session.lock() else {
             return false;
         };
+        // 拖放源与目标都必须匹配各自发布版本，且真实 Page 注册顺序仍对应标签弱身份表，防止用陈旧列表下标重排。
         for (id, version) in [
             (input.window, input.layout_version),
             (target.window, target.layout_version),
@@ -1173,6 +1216,7 @@ impl UiBridge {
             if state.published_version != input.layout_version {
                 bail!("event targets an obsolete presentation");
             }
+            // input.mount 在标签路径表示 Tab ID，先映回弱 Page，再确认仍在当前窗口 pages 集合，不是 Mount 几何下标。
             let weak = state
                 .tab_ids
                 .iter()
@@ -1215,12 +1259,14 @@ impl UiBridge {
                     .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
                 page_window(vm.object_store(), &state, page)?
             };
+            // 源 moveToWindow 可覆盖并拒绝/改投其他窗口；只有确认实际归属仍为预期目标才继续重排与激活。
             if destination == Some(target.window) {
                 let pages = crate::window::pages(vm.object_store(), window)?;
                 let from = pages
                     .iter()
                     .position(|candidate| *candidate == page)
                     .ok_or_else(|| anyhow::anyhow!("Page is no longer open"))?;
+                // 同窗口拖动的 index 是移除前插入缝位置，向后拖时先减一；跨窗口新加入则不用这一偏移修正。
                 let position = if input.window == target.window && from < target.index {
                     target.index - 1
                 } else {
@@ -1248,6 +1294,7 @@ impl UiBridge {
             _ => "activate",
         };
         let value = invoke_member(vm, page, method, &[], 1_000_000)?;
+        // detach 返回值可能被源覆盖成其他值，仅确为 Window 且带屏幕位置才调用 moveTo；最后统一释放原返回值。
         let placed = (|| -> Result<()> {
             if input.kind == "tab-detach"
                 && let Some([x, y]) = input.screen_position
@@ -1289,6 +1336,7 @@ impl UiBridge {
         {
             bail!("event belongs to another window");
         }
+        // 窗口关闭通过名义 close 方法，保留源覆盖语义；直接调用宿主原生退役只用于故障清理路径。
         if input.kind == "window-close" {
             let desktop = self
                 .session
@@ -1312,6 +1360,7 @@ impl UiBridge {
             vm.release_value(result?)?;
             return Ok(());
         }
+        // 内置工具打开走同一 VM 的 developerTools 能力，返回值只作临时根使用，不跨到 GUI。
         if let Some(name) = input.kind.strip_prefix("developer-open:") {
             let function = object(Some(&vm.get_attr(self.ui, "developerTools")?))?;
             let page = vm.call(function, &[Value::Text(name.into())])?;
@@ -1336,6 +1385,7 @@ impl UiBridge {
         ) {
             return self.dispatch_tab(vm, input);
         }
+        // 普通指针输入取同一锁内的版本/目标/完整出现候选快照；随后不持 session 锁执行源 hitTest 或事件回调。
         let (weak, desktop, candidates, viewport, surface) = {
             let state = self
                 .session
@@ -1365,6 +1415,7 @@ impl UiBridge {
                 let point = input
                     .point
                     .ok_or_else(|| anyhow::anyhow!("scroll has no pointer"))?;
+                // scroll 不只校验 Mount 身份，还要指针仍在页面视口和出现裁剪中；相机/面板映射后的增量才可交给 scrollBy。
                 if !data.mounted
                     || data.version != input.layout_version
                     || !surface.contains(point, viewport)
@@ -1402,6 +1453,7 @@ impl UiBridge {
             vm.release(mount)?;
             return result;
         }
+        // 坐标点击重新执行源协议选择按下和释放目标，二者同出现才分发；无坐标输入使用已捕获的弱目标。
         let mount = if let (Some(press), Some(release)) = (input.press_point, input.point) {
             if [press, release]
                 .iter()
@@ -1420,6 +1472,7 @@ impl UiBridge {
         };
         let result = (|| {
             let data = vm.payload::<crate::mount::Mount>(mount, "Mount")?.clone();
+            // 3D 视口点击先生成 RayHit3D 并附到 Event.hit，再沿视口出现传播，不能只按二维外框假定击中某网格。
             if data.geometry.scene3d_viewport
                 && input.kind == "click"
                 && let Some(point) = input.point
@@ -1451,6 +1504,7 @@ impl UiBridge {
             if !data.geometry.interactive {
                 bail!("Mount does not accept input");
             }
+            // 普通点击/焦点先登记展示焦点请求，再按 kind 调 Block.click 或 Mount.requestFocus；生效仍需后续完整刷新。
             vm.set_attr(
                 desktop,
                 "focus",
@@ -1483,6 +1537,7 @@ impl UiBridge {
     }
     /// 整理不再有效的弱索引与展示根，并配合 VM 回收，避免派生缓存延长业务对象生命周期。
     pub fn reclaim(&self, vm: &mut Vm, _roots: &mut Vec<ObjectRef>) -> Result<()> {
+        // 先回收托管环，再扫描弱节点表，只保留能升级的身份；render_cache.prune 同步清除死亡业务索引。
         vm.collect_cycles();
         let mut state = self
             .session
@@ -1511,6 +1566,7 @@ impl UiBridge {
             let window = object(Some(&vm.get_attr(presentation.desktop, "window")?))?;
             // A failed first render must not become visible on the next input
             // merely because show() already registered its Page with the Window.
+            // 第一次 render 失败时撤销尚未发布的 Page 登记，避免下一次无关输入把失败页意外显示出来。
             if presentation.active.is_none() && presentation.last_tabs.is_empty() {
                 let unpublished = crate::window::pages(vm.object_store(), window)?.to_vec();
                 for page in unpublished {
@@ -1518,6 +1574,7 @@ impl UiBridge {
                 }
             }
             let pages = crate::window::pages(vm.object_store(), window)?;
+            // 失败输入已成功执行的关闭/迁移语句不回滚；重新选择仍在真实窗口注册表中的页，修复 pending 与拥有关系。
             let next = if presentation.closing {
                 None
             } else {
@@ -1554,6 +1611,7 @@ impl UiBridge {
     }
     /// 重新评估已失效的属性绑定，并把结果计入会话统计。
     pub fn refresh_bindings(&self, vm: &mut Vm) -> Result<()> {
+        // 只在锁内快照弱节点与宿主桌面集合，实际绑定回调在锁外执行，避免回调访问 UI 时死锁。
         let (nodes, desktops) = {
             let state = self
                 .session
@@ -1571,11 +1629,13 @@ impl UiBridge {
     }
     /// 排空一次 VM 变化记录并通知各窗口，提取活动页面快照，判断本次是否需要布局与发布。
     pub fn prepare_frame(&self, vm: &mut Vm) -> Result<Option<Option<Arc<UiNode>>>> {
+        // 一次排空变更必须广播所有 Presentation，不能让先刷新的窗口吃掉其他窗口共享业务数据的失效通知。
         let changes = vm.take_changes();
         let mut state = self
             .session
             .lock()
             .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
+        // 本轮目标优先 pending，包括显式清空；快照提取返回 None 代表目标无页面，不等于无需刷新。
         let active = state.pending.unwrap_or(state.active);
         // One VM change drain feeds every presentation before selecting a root.
         // Otherwise a window refreshed first could consume another window's work.
@@ -1585,6 +1645,7 @@ impl UiBridge {
         let root = active
             .map(|v| state.render_cache.snapshot(vm.object_store(), v))
             .transpose()?;
+        // 视觉缓存用 Arc 身份快速判断根未变；即使根相同，焦点、滚动、标签或源依赖仍可能要求重绘。
         let same = match (&root, &state.last_snapshot) {
             (Some(a), Some(b)) => Arc::ptr_eq(a, b),
             (None, None) => true,
@@ -1612,6 +1673,7 @@ impl UiBridge {
             state.snapshot_visited = state.render_cache.visited;
             state.snapshot_reused = state.render_cache.reused;
         }
+        // 双层 Option 三态：外 None 无工作；Some(None) 需提交空帧；Some(Some(root)) 需布局/绘制根。
         Ok(changed.then_some(root))
     }
     /// 提交已经完成的出现几何与快照，并处理展示生命周期；不把挂起或失败的布局当成已发布帧。
@@ -1628,6 +1690,7 @@ impl UiBridge {
         let page = state.pending.unwrap_or(state.active);
         let desktop = state.desktop;
         let nodes = state.nodes.clone();
+        // 提交几何同步清除临时 layout Context，并产生挂载/卸载序列；提交桥接状态不等于已写 GUI 共享文档。
         let hooks = state
             .mounts
             .synchronize(vm, desktop, page, nodes, frame, false)?;
@@ -1645,6 +1708,7 @@ impl UiBridge {
             state.last_snapshot = snapshot;
             state.last_tabs = frame.tabs.clone();
             state.surface = frame.surface.clone();
+            // 让随后源回调看到本轮几何与版本，但真正对外原子发布要等整个刷新循环稳定，回调可能继续触发下一轮。
             state.published_version = frame.layout_version;
             // Hooks may call Page/container APIs; never hold the session mutex
             // across user code. Publish only after the refresh loop settles.
@@ -1682,6 +1746,7 @@ impl UiBridge {
                 .session
                 .lock()
                 .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
+            // 按最终帧绘制顺序查活动 Mount 弱身份，每条都必须存在；不按 HashMap 顺序调用源 paint。
             let mounts = frame
                 .mounts
                 .iter()
@@ -1721,6 +1786,7 @@ impl UiBridge {
                 .session
                 .lock()
                 .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
+            // 完成后过滤所有窗口私有 desktop 读取，再拆对象版本与名称依赖；挂起切片不覆盖上一份完成的 paint 依赖。
             let desktops = state.host_desktops();
             let reads = draft
                 .reads
@@ -1743,6 +1809,7 @@ impl UiBridge {
         window: u64,
         work: crate::source_paint::Work,
     ) -> Result<()> {
+        // 先尝试取消 VM 续体，再尝试选原窗口并强制下一帧；前一操作失败也执行必要的宿主失效准备。
         let cancelled = work.cancel(vm);
         let invalidated = self.select_window(window).and_then(|()| {
             self.session
@@ -1765,6 +1832,7 @@ impl UiBridge {
             !vm.has_suspended_call() && !vm.object_store().is_read_only(),
             "cannot prepare another frame during suspended layout"
         );
+        // 显式空页面无需源布局，清测量/布局读取并推进空帧版本，再同步退役旧 Mount；不是无工作返回。
         let Some(root) = root else {
             self.session
                 .lock()
@@ -1821,6 +1889,7 @@ impl UiBridge {
                 .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
             project_tabs(vm, &mut state)?
         };
+        // 记录真实原生页面视口供页面相机 clamp；兼容 Page.mode 只改变根约束，不永久篡改保存的窗口尺寸。
         let full_viewport = layout.viewport;
         let surface = root.surface.clone().unwrap_or_default();
         layout.page_mode = root.surface.as_ref().map(|surface| surface.mode);
@@ -1829,6 +1898,7 @@ impl UiBridge {
                 .session
                 .lock()
                 .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
+            // 按全会话高水位分配结构出现 ID，取消后也不回收已暴露过的数值身份。
             layout.reserve_identity_floor(state.next_mount);
         }
         let mut frame = layout.structure(&root)?;
@@ -1845,6 +1915,7 @@ impl UiBridge {
                 .session
                 .lock()
                 .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
+            // 在准备态 synchronize 改写 Mount 前保留旧字典与 payload；准备失败立即恢复，不能留下半套父子关系。
             let checkpoint = state.mounts.checkpoint(vm, desktop)?;
             let hooks = match state
                 .mounts
@@ -1858,6 +1929,7 @@ impl UiBridge {
             };
             (hooks, state.mounts.ordered(), checkpoint)
         };
+        // 检查点、暂存 hooks、所属窗口与根随源布局 Work 一起保留，跨量子不能只留下 VM 续体。
         let context = LayoutContext {
             surface,
             root: root.clone(),
@@ -1918,6 +1990,7 @@ impl UiBridge {
             checkpoint,
             ..
         } = context;
+        // 恢复必须在原窗口；若窗口或 session 锁已不可用，至少释放检查点拥有根，不能尝试恢复到另一个窗口。
         let selected = self.select_window(window);
         let restored = if selected.is_ok() {
             match self.session.lock() {
@@ -1934,6 +2007,7 @@ impl UiBridge {
         } else {
             checkpoint.release(vm).map_err(anyhow::Error::from)
         };
+        // 无论选择/恢复是否失败都先尝试释放延迟 hooks；保存结果后再按优先级传播错误。
         let released = hooks.map(|hooks| vm.release(hooks)).transpose();
         selected?;
         restored?;
@@ -1944,6 +2018,7 @@ impl UiBridge {
     /// 取消源布局续体并清理对应上下文，保持已发布帧可用。
     pub fn cancel_layout_frame(&self, vm: &mut Vm, pending: PendingLayout) -> Result<()> {
         let PendingLayout { work, context } = pending;
+        // 取消只读执行与恢复 Mount 是两件事，均先尝试；没有继续执行原续体时也不能漏掉检查点恢复。
         let cancelled = work.cancel(vm);
         let restored = self.discard_layout_context(vm, context);
         cancelled?;
@@ -1962,6 +2037,7 @@ impl UiBridge {
         pending: PendingLayout,
     ) -> Result<LayoutProgress> {
         let PendingLayout { work, context } = pending;
+        // 恢复时原窗口不存在则取消 owning VM 调用并清上下文，不重新建窗口或重放源布局。
         if let Err(error) = self.select_window(context.window) {
             let cancelled = work.cancel(vm);
             let restored = self.discard_layout_context(vm, context);
@@ -1981,6 +2057,7 @@ impl UiBridge {
         progress: Result<crate::source_layout::Progress>,
     ) -> Result<LayoutProgress> {
         match progress {
+            // Pending 原样捆绑 Work 与 Context；Complete 才投影、提交，Error 则撤销准备态上下文。
             Ok(crate::source_layout::Progress::Pending(work)) => {
                 Ok(LayoutProgress::Pending(Box::new(PendingLayout {
                     work,
@@ -2027,11 +2104,13 @@ impl UiBridge {
                     .session
                     .lock()
                     .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
+                // 先在布局坐标中处理滚动，再叠二维视口/面板投影；绘制与输入共享最终 Frame 几何。
                 crate::scroll::project(vm, &state.mounts, &root, &mut frame)?;
                 crate::viewport::project(&root, &mut frame)?;
             }
             // Native layout may replace the structural Frame; attach chrome only
             // after either layout path has produced the final page geometry.
+            // 小原生快速路径可能返回新的 Frame，标签/窗口与页面相机必须在最终布局之后重新附加。
             frame.tabs = tabs;
             frame.window = window;
             if let Some(root) = frame.mounts.first() {
@@ -2053,6 +2132,7 @@ impl UiBridge {
             // Shared intrinsic functions capture the primary desktop even when
             // invoked from another window. Desktop bookkeeping is private host
             // state; Window, viewport input and business dependencies remain.
+            // 源布局实际业务读取版本在生命周期 hooks 前保存，hooks 改写依赖后下一轮才能识别失效并重算。
             reads.retain(|read| !desktops.contains(&read.object()));
             cache.exclude_host_desktops(&desktops);
             let (reads, names) = crate::presentation::split_reads(reads);
@@ -2060,6 +2140,7 @@ impl UiBridge {
                 Ok(Value::Number(id)) => id.as_i64().and_then(|n| u64::try_from(n).ok()),
                 _ => None,
             };
+            // 焦点 ID 仅保留仍存在且可交互的出现，切页/树编辑移除目标后自动清掉失效焦点。
             frame.focus = frame
                 .focus
                 .filter(|id| frame.mounts.iter().any(|m| m.id == *id && m.interactive));
@@ -2074,6 +2155,7 @@ impl UiBridge {
                 state.layout_reads = reads;
                 state.layout_names = names;
             }
+            // 几何先提交到桥接状态，再执行准备阶段延后的挂载 hooks；其变化由全窗口刷新循环再收敛。
             self.commit_frame(vm, Some(root), &frame)?;
             if let Some(hooks) = hooks {
                 let value = vm
@@ -2090,6 +2172,7 @@ impl UiBridge {
             }
             Ok(frame)
         })();
+        // 收尾计算无论成功/失败，都先释放 hooks 与检查点的拥有根；只有所有必要清理通过才返回帧。
         let released_hooks = hooks.map(|hooks| vm.release(hooks)).transpose();
         let released_checkpoint = checkpoint.release(vm);
         let frame = result?;
@@ -2104,6 +2187,7 @@ impl UiBridge {
             .session
             .lock()
             .map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
+        // 此兼容提取接口只读取待展示 Page，不回退 active；持久增量路径使用 prepare_frame 的 active/pending 选择。
         state
             .pending
             .flatten()
@@ -2144,6 +2228,7 @@ pub(crate) fn desktop_type(
     name: &str,
     desktop: ObjectRef,
 ) -> Result<ObjectRef, VmError> {
+    // 查当前 desktop 的实际字典对象和精确类型条目；不是按名字创建新类型，缺条目沿 object 解码报错。
     let types = object(Some(&store.get_attr(desktop, "types")?))?;
     object(store.dict_get(types, &Value::Text(name.into()))?.as_ref())
 }

src/bridge/ui_bridge/bootstrap.rs

@@ -6,6 +6,7 @@ use super::*;
 
 /// 把本模块的类型、方法或能力注册到所属运行时上下文。
 pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
+    // 先建立 desktop/ui/tabs 并加入显式 roots，后面初始化失败时由上层运行时统一释放，避免依赖 Rust 句柄保活。
     let desktop = vm.new_object()?;
     roots.push(desktop);
     vm.set_attr(desktop, "viewport", Value::Nil)?;
@@ -14,6 +15,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
     vm.set_attr(desktop, "tabs", Value::Object(tabs))?;
     let ui = vm.new_object()?;
     roots.push(ui);
+    // 原生 Session 借用托管身份，主窗口先拥有独立 Presentation；业务对象仍全部位于传入的单一 VM。
     let session = Arc::new(Mutex::new(Session {
         nodes: Vec::new(),
         presentations: std::collections::BTreeMap::from([(
@@ -33,6 +35,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
         binding_evaluations: 0,
         exiting: false,
     }));
+    // 先分配函数占位再补签名，因为签名会引用尚未建立的名义类型；保存列表用于第二阶段替换 payload。
     let mut public_functions = Vec::new();
     let mut factories = Vec::new();
     for (name, operation) in [
@@ -75,6 +78,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
         vm.set_attr(ui, name, Value::Object(function))?;
         public_functions.push((name, function, operation));
     }
+    // Object/Type 来自 VM 类型引导，不能用普通类代替；之后所有宿主名义类型从此根体系建立。
     let root_types = vm.bootstrap_types()?;
     roots.extend([root_types.object, root_types.type_type]);
     vm.set_attr(ui, "Object", Value::Object(root_types.object))?;
@@ -83,6 +87,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
         ("Object", root_types.object),
         ("Type", root_types.type_type),
     ];
+    // 类型按基类先于子类的顺序创建。None 表示抽象能力/宿主结果类型，不开放普通源构造器。
     for (name, base_name, constructor_name) in [
         ("Trait", "Object", None),
         ("Function", "Object", None),
@@ -124,6 +129,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
     ] {
         let base = object(Some(&vm.get_attr(ui, base_name)?))?;
         let constructor = match constructor_name {
+            // ObjectList 与 Event 有特殊的“类型首参+子类字段”构造规则，单独原生适配；其他类型共用 NativeFactory。
             Some("object-list") => {
                 let factory = vm.allocate(ContextNativeFunction::new(
                     "object-list",
@@ -150,6 +156,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
                 TypeConstructor::NativeTyped(factory)
             }
             Some(constructor_name) => {
+                // 把构造标签映射到宿主 Operation；3D 族委托其元数据，未知标签立即失败，不静默创建错误类型。
                 let operation = match constructor_name {
                     "text" => Operation::Text,
                     "rect" => Operation::Rect,
@@ -186,6 +193,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
             }
             None => TypeConstructor::Abstract,
         };
+        // 记住实际工厂身份，类型构建完成后原地补签名，避免替换类型内指向的构造函数对象。
         if let (Some(tag), TypeConstructor::NativeTyped(factory)) = (constructor_name, constructor)
         {
             factories.push((tag, factory));
@@ -195,6 +203,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
         vm.set_attr(ui, name, Value::Object(definition))?;
         definitions.push((name, definition));
     }
+    // 协议值采用普通托管类：Constraints/Bounds/Point 等字段有类型注解，PaintCommand/CameraGesture 后续再初始化属性。
     for (name, fields) in [
         (
             "Constraints",
@@ -212,6 +221,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
             .into_iter()
             .map(|name| endor_core::ClassField {
                 name: name.into(),
+                // children/commands 先声明 Object 接口，后续各协议解码器再要求受控列表；几何字段统一为 Number。
                 type_name: if matches!(name, "children" | "commands") {
                     "Object"
                 } else {
@@ -232,6 +242,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
     }
     // The desktop owns the registry through ordinary traced attributes. The
     // Rust session only borrows handles and adds no hidden lifetime roots.
+    // 桌面通过普通属性拥有类型字典；后续 nominal 查询必须使用同一 desktop 中注册的精确类型身份。
     let types = vm.new_dict()?;
     roots.push(types);
     for (name, definition) in definitions {
@@ -241,8 +252,10 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
     vm.attach_type(desktop, root_types.object)?;
     vm.attach_type(ui, root_types.object)?;
     let function_type = object(Some(&vm.get_attr(ui, "Function")?))?;
+    // 让后续 VM 创建的函数使用宿主 Function 名义类型，并打开源类型检查，再安装完整本机签名。
     vm.set_function_type(function_type)?;
     vm.set_source_type_checks(true)?;
+    // 以同一函数身份补完 operation_signature，不改变先前 ui 属性引用的函数对象。
     for (name, function, operation) in public_functions {
         vm.replace_payload(
             function,
@@ -284,6 +297,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
         };
         if let Some(operation) = operation {
             let options = operation_signature(vm.object_store(), desktop, operation)?;
+            // 外层 NativeTyped 工厂接收 Type 首参和任意候选尾参，允许子类字段；NativeFactory 用 options 再核对基构造参数。
             let envelope = CallSignature {
                 arity: endor_core::CallArity::range(options.arity.required + 1, usize::MAX),
                 parameters: vec![AnnotationType::Type.into()],
@@ -292,6 +306,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
                 effect: options.effect,
             };
             let mut captures = vec![desktop];
+            // 参数和返回注解中的名义类型也是托管引用，必须纳入 captures，不能只把它们存进 Rust 签名结构。
             captures.extend(options.references());
             vm.replace_payload(
                 function,
@@ -307,6 +322,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
                 ),
             )?;
         } else {
+            // 特殊构造器保留宽变参外壳，再由对应 Constructor 按类型字段数拆实参，返回准确 Event/ObjectList 名义类型。
             let kind = if name == "event" {
                 "Event"
             } else {
@@ -377,6 +393,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
         let function = object(Some(&vm.get_attr(ui, name)?))?;
         vm.attach_type(function, function_type)?;
     }
+    // 实例方法安装到对应名义类型；继承复用基类方法，TypeMethod 会验证实际接收者及参数契约。
     for (type_name, name, operation) in [
         ("Block", "bind", Operation::Bind),
         ("OrbitController", "update", Operation::CameraControl),
@@ -429,12 +446,14 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
                 expected,
                 session: session.clone(),
             },
+            // 方法 wrapper 捕获所属类型与桌面，保证分发和签名引用在方法仍存活时有效。
             vec![expected, desktop],
         ))?;
         roots.push(method);
         vm.attach_type(method, function_type)?;
         vm.define_method(expected, name, method)?;
     }
+    // 类型与基础方法就绪后再装窗口、默认视觉、事件方法和能力契约，顺序满足各模块查类型/方法的前提。
     crate::window::install(vm, roots, desktop, tabs)?;
     let block_type = object(Some(&vm.get_attr(ui, "Block")?))?;
     crate::native_visual::install(vm, roots, desktop, block_type, function_type)?;
@@ -442,6 +461,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
     let token_type = object(Some(&vm.get_attr(ui, "Subscription")?))?;
     crate::event_dispatch::install(vm, roots, event_type, token_type, function_type)?;
     crate::protocols::install(vm, roots, desktop, ui)?;
+    // 每个桥接域配套自己的任务 Scheduler，再接工具入口及托管起始页工厂，最后返回可使用的 UiBridge。
     let tasks = crate::tasks::install(vm, roots, ui, desktop)?;
     developer_pages::install(vm, ui, &session)?;
     let bridge = UiBridge { ui, session, tasks };

src/bridge/ui_bridge/calls.rs

@@ -9,16 +9,17 @@ impl NativeCallable for Function {
     fn signature(&self) -> Option<CallSignature> {
         self.signature.clone()
     }
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 接收已经剥离 receiver 的显式参数，数量沿用 Operation 的范围。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(self.operation.arity())
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 统一校验数量与只读限制，再按 Operation 分派构造、树修改、页面、绑定、状态与能力调用，返回托管结果或 VM 续调用。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         use Operation::*;
         let arity = self.operation.arity();
         let (minimum, maximum) = (arity.required, arity.maximum);
+        // Function 接收已剥离 receiver 的显式参数；先校验数量，后面索引 args 才安全。
         if !(minimum..=maximum).contains(&args.len()) {
             return Err(invalid("incorrect UI method argument count"));
         }
@@ -26,6 +27,7 @@ impl NativeCallable for Function {
             let camera = new_camera2d(cx, &self.session, self.requested_type, args)?;
             return Ok(NativeResult::Return(Value::Object(camera)));
         }
+        // 3D 构造与普通 Block 分开，requested_type 保留源子类名义身份，否则从本 desktop 取默认类型。
         if let SceneObject(kind) = self.operation {
             let desktop = self
                 .session
@@ -58,6 +60,7 @@ impl NativeCallable for Function {
             )?;
             return Ok(NativeResult::Return(Value::Nil));
         }
+        // implement 修改显式能力关系；implements 查类型，supports 查对象实际能力，不靠同名字段鸭子类型推断。
         if matches!(self.operation, Implement | Implements | Supports) {
             let capability = object(args.get(1))?;
             let value = match self.operation {
@@ -92,6 +95,7 @@ impl NativeCallable for Function {
             };
             return Ok(NativeResult::Return(Value::Bool(value)));
         }
+        // 显式失效属于模型变更，只读阶段拒绝；paint/layout/content 精度不同，后续分别清理对应缓存。
         if matches!(self.operation, Invalidate) {
             if cx.store().is_read_only() {
                 return Err(invalid(
@@ -115,6 +119,7 @@ impl NativeCallable for Function {
                 .lock()
                 .map_err(|_| invalid("UI session poisoned"))?;
             let mut affected = std::collections::HashSet::new();
+            // 找出解析到同一底层 Data 的所有别名，失效共享数据时不能只刷新调用者包装身份。
             for weak in &session.nodes {
                 if let Some(block) = cx.upgrade(*weak)?
                     && block::resolve(cx.store(), block)?.0 == data
@@ -147,6 +152,7 @@ impl NativeCallable for Function {
                     }
                 }
             }
+            // 跨窗口 Mount 查询按窗口/出现 ID 稳定排序，不依赖 HashMap 遍历顺序；返回每个具体出现而非几何副本。
             positions.sort_unstable_by_key(|(window, id, _)| (*window, *id));
             let set = crate::mount::collection(
                 cx,
@@ -179,6 +185,7 @@ impl NativeCallable for Function {
                 .session
                 .lock()
                 .map_err(|_| invalid("UI session poisoned"))?;
+            // 关闭托管窗口后为 Presentation 排空 pending 并标 closing，后续刷新才安排 Mount 退役与空帧。
             if let Some(view) = state.presentations.get_mut(&id) {
                 cx.set_attr(view.desktop, "pending", Value::Nil)?;
                 view.pending = Some(None);
@@ -217,6 +224,7 @@ impl NativeCallable for Function {
                 )?,
             )));
         }
+        // 诊断会读对象总数与宿主变化统计，禁止在只读渲染中观察并形成反馈依赖。
         if matches!(self.operation, Stats) {
             if cx.store().is_read_only() {
                 return Err(invalid(
@@ -287,6 +295,7 @@ impl NativeCallable for Function {
             )?;
             return Ok(NativeResult::Return(Value::Object(stats)));
         }
+        // 状态是普通名义 Object，value 属性经 VM 追踪，set/increment 方法捕获同一对象，不额外建立原生状态副本。
         if matches!(self.operation, State) {
             let state = cx.new_object()?;
             attach_named_type(cx, state, "Object", &self.session)?;
@@ -303,6 +312,7 @@ impl NativeCallable for Function {
                 let Value::Number(value) = cx.store().get_attr(owner, "value")? else {
                     return Err(invalid("increment requires an integer state"));
                 };
+                // increment 要求可表示为 i64 的整数且加一不溢出，不能把任意浮点状态强转整数。
                 let next = value
                     .as_i64()
                     .and_then(|n| n.checked_add(1))
@@ -315,6 +325,7 @@ impl NativeCallable for Function {
         if matches!(self.operation, TextOf) {
             let source = object(args.first())?;
             let field = text(args.get(1))?;
+            // textOf 建立前确认字段可读取，具体字符串化与依赖记录发生在快照提取时。
             cx.store().get_attr(source, &field)?;
             let size = args
                 .get(2)
@@ -334,6 +345,7 @@ impl NativeCallable for Function {
                 0.0,
                 0.0,
             );
+            // 保留源对象强边与字段名，不在创建时复制一个静态字符串；后续属性变化会让文字快照重算。
             data.text_binding = Some((source, field));
             return Ok(NativeResult::Return(Value::Object(new_block(
                 cx,
@@ -341,6 +353,7 @@ impl NativeCallable for Function {
                 &self.session,
             )?)));
         }
+        // 普通组件先组装 Data，再统一由 new_typed_block 安装 Cell、属性和名义类型；不直接写原生窗口。
         let constructor = match self.operation {
             Scroll => Some(Data::new(
                 Kind::Scroll {
@@ -396,6 +409,7 @@ impl NativeCallable for Function {
                 } else {
                     Kind::Column
                 },
+                // 线性容器固定前两参为 padding/gap，后续都是孩子对象；组成合法性在 Block 分配前统一检查。
                 args[2..]
                     .iter()
                     .map(|v| object(Some(v)))
@@ -422,6 +436,7 @@ impl NativeCallable for Function {
                     0.0,
                     0.0,
                 );
+                // 每个新二维视口默认新建独立 Camera2D；显式属性共享相机才会联动其他视口。
                 data.camera = Some(new_camera2d(cx, &self.session, None, &[])?);
                 Some(data)
             }
@@ -451,6 +466,7 @@ impl NativeCallable for Function {
                 data.camera = Some(camera);
                 data.scene3d = Some(object(args.get(2))?);
                 let definition = desktop_type(cx.store(), "OrbitController", desktop)?;
+                // 三维视口默认独立透视相机及 OrbitController，Scene3D 引用则来自调用者，可显式共享世界。
                 data.controller = Some(crate::scene3d_model::allocate(
                     cx,
                     desktop,
@@ -460,6 +476,7 @@ impl NativeCallable for Function {
                 )?);
                 Some(data)
             }
+            // 按钮标签也是普通 TextBlock 孩子，布局和生命周期沿同一组成树，不是原生按钮硬编码文字。
             Button => {
                 let label = new_block(
                     cx,
@@ -479,6 +496,7 @@ impl NativeCallable for Function {
             }
             _ => None,
         };
+        // 统一检查文本等级和 UTF-8 字节量，再按 requested_type 生成实际对象，保留子类工厂身份。
         if let Some(data) = constructor {
             if let Kind::Text { size, value, .. } = &data.kind
                 && (!(1..=8).contains(size) || value.len() > 16_384)
@@ -502,6 +520,7 @@ impl NativeCallable for Function {
                     .map_err(|_| invalid("UI session poisoned"))?;
                 (state.master, state.desktop)
             };
+            // 非 Block 对象若显式支持 Presentable，调用其 present；已有 Block 直接进入下面的展示转换。
             let capability = desktop_type(cx.store(), "Presentable", desktop)?;
             if !cx
                 .store()
@@ -528,6 +547,7 @@ impl NativeCallable for Function {
                     },
                     vec![desktop],
                 ))?;
+                // 小驱动先调用 present(value, window)，再把结果交 PresentResult 验证/可选打开，所有委托共用当前 VM 预算。
                 let instructions = [
                     endor_core::Instruction::new(endor_core::Opcode::LoadConst, 0),
                     endor_core::Instruction::simple(endor_core::Opcode::PushNull),
@@ -560,6 +580,7 @@ impl NativeCallable for Function {
                 });
             }
         }
+        // ui.open 把普通结果转换为根组件，再在必要时包一层 Page 并展示；ui.present 仅转换，不自动打开页面。
         if matches!(self.operation, OpenValue) {
             let root = present_value(cx, &args[0], &self.session)?;
             let page = if cx.store().payload::<block::Block>(root, "Block")?.page {
@@ -581,6 +602,7 @@ impl NativeCallable for Function {
                 &self.session,
             )?)));
         }
+        // 从这里起都是需要接收者的 Block/Page 方法，未绑定 owner 时不能继续修改任意全局对象。
         let owner = self.owner.ok_or(invalid("method has no owner"))?;
         if matches!(self.operation, Bind) {
             let field = text(args.first())?;
@@ -598,6 +620,7 @@ impl NativeCallable for Function {
                 )?,
             )));
         }
+        // moveTab 重排同窗口页面索引并强制下一帧更新标签；移动的是原 Page，非新页面副本。
         if matches!(self.operation, MoveTab) {
             let position = usize::try_from(integer(args.first())?)
                 .map_err(|_| invalid("tab position out of range"))?;
@@ -615,6 +638,7 @@ impl NativeCallable for Function {
             view.force_frame = true;
             return Ok(NativeResult::Return(Value::Object(owner)));
         }
+        // 接收者可能是共享转发别名，解析到最终 Data 后修改副本，最后用一次 replace_payload 写入结构边。
         let (data_ref, data) = block::resolve(cx.store(), owner)?;
         let mut data = data.clone();
         let mut result = Value::Nil;
@@ -626,6 +650,7 @@ impl NativeCallable for Function {
                         return Err(invalid("text exceeds 16 KiB"));
                     }
                     *value = next;
+                    // 直接 setText 取代旧 textOf 推导；同时更新普通 text 属性，使快照属性读取与 payload 描述保持一致。
                     data.text_binding = None;
                     cx.set_attr(owner, "text", args[0].clone())?;
                 }
@@ -654,8 +679,10 @@ impl NativeCallable for Function {
                         (data.children.len(), args.first())
                     };
                     let child = object(argument)?;
+                    // 插入前禁止孩子图回到当前 Data，避免循环组成；position 是插入位置，返回值却是稳定 slot。
                     block::validate(cx.store(), child, Some(data_ref))?;
                     let slot = data.next_slot;
+                    // slot 单调增加且限制到 i64 正范围，不复用已删除身份；前后插入/重排不会把其他孩子 slot 改号。
                     data.next_slot = slot
                         .checked_add(1)
                         .filter(|next| *next <= i64::MAX as u64)
@@ -663,6 +690,7 @@ impl NativeCallable for Function {
                     data.children.insert(position, Child { slot, block: child });
                     result = Value::Number((slot as i64).into());
                 } else {
+                    // remove/replace/move 首参为稳定 slot 而非当前数组下标；只有 move 的第二参才是目标位置。
                     let slot = integer(args.first())?;
                     let index = data
                         .children
@@ -676,6 +704,7 @@ impl NativeCallable for Function {
                         Replace => {
                             let child = object(args.get(1))?;
                             block::validate(cx.store(), child, Some(data_ref))?;
+                            // replace 保留该组成边 slot，但换实际 Block；出现键还含 Block 身份，因此可能产生新的 Mount 上下文。
                             data.children[index].block = child;
                         }
                         Move => {
@@ -691,6 +720,7 @@ impl NativeCallable for Function {
                     }
                 }
             }
+            // children 查询返回 slot文本->Block 的托管字典，不把当前顺序假装成稳定 slot 连号数组。
             Children => {
                 let result = cx.new_dict()?;
                 for child in data.children {
@@ -709,6 +739,7 @@ impl NativeCallable for Function {
                 let root = object(args.first())?;
                 block::validate(cx.store(), root, Some(data_ref))?;
                 if matches!(self.operation, Navigate) {
+                    // 首次 navigate 把当前根纳入历史，之后新导航先截断前进分支，再追加新根，保持浏览历史语义。
                     if data.history.is_empty() {
                         if let Some(old) = data.children.first() {
                             data.history.push(old.block);
@@ -719,6 +750,7 @@ impl NativeCallable for Function {
                     data.history.push(root);
                     data.history_index = data.history.len() - 1;
                 }
+                // 页面内容统一保留根 slot0，render/navigate 改的是根对象；show 只记录待展示请求，后续刷新再布局。
                 data.children = vec![Child {
                     slot: 0,
                     block: root,
@@ -730,6 +762,7 @@ impl NativeCallable for Function {
                 if data.history.is_empty() {
                     return Ok(NativeResult::Return(Value::Nil));
                 }
+                // 后退/前进钳到历史首尾，复用已保留根对象而非重新执行旧源码。
                 let next = if matches!(self.operation, Back) {
                     data.history_index.saturating_sub(1)
                 } else {
@@ -742,6 +775,7 @@ impl NativeCallable for Function {
                 }];
                 show(cx, owner, &self.session)?;
             }
+            // 分离先创建新 Window，再把同一 Page 展示到它；跨窗口出现上下文由后续展示同步重建。
             Detach => {
                 let window = {
                     let mut state = self
@@ -780,10 +814,12 @@ impl NativeCallable for Function {
                 show_in(cx, owner, &self.session, target)?;
                 return Ok(NativeResult::Return(Value::Object(owner)));
             }
+            // unmount 清内容但不关闭 Page 标签，也不直接等同于销毁整个业务对象。
             Unmount => {
                 data.children.clear();
             }
             Close => {
+                // 关闭 Page 当场取消页面和所属 Mount 任务，即使同一输入稍后又打开它，也不能复活旧异步工作。
                 crate::tasks::cancel_owner(cx, owner)?;
                 let mut state = self
                     .session
@@ -828,6 +864,7 @@ impl NativeCallable for Function {
                 }
                 let handler = object(args.get(1))?;
                 crate::event_dispatch::validate_handler(cx.store(), handler)?;
+                // 订阅默认非捕获；可用 Bool 或 capture/bubble 文本明确阶段，其他值拒绝而不做真值转换。
                 let capture = match args.get(2) {
                     None | Some(Value::Bool(false)) => false,
                     Some(Value::Bool(true)) => true,
@@ -835,6 +872,7 @@ impl NativeCallable for Function {
                     Some(Value::Text(phase)) if phase == "bubble" => false,
                     _ => return Err(invalid("phase must be capture or bubble")),
                 };
+                // 清掉已断开连接后再计算容量，保留仍有效订阅顺序；新 Connection 拥有 handler，返回 token 仅弱引用连接。
                 let mut active = Vec::new();
                 for token in &data.subscriptions {
                     if cx
@@ -862,6 +900,7 @@ impl NativeCallable for Function {
                 data.subscriptions = active;
                 result = Value::Object(token);
             }
+            // 基类事件/挂载回调默认空实现，子类可覆盖；不在这条默认路径生成额外状态。
             OnEvent | OnMount | OnUnmount => return Ok(NativeResult::Return(Value::Nil)),
             Click | Dispatch => {
                 let desktop = self
@@ -869,6 +908,7 @@ impl NativeCallable for Function {
                     .lock()
                     .map_err(|_| invalid("UI session poisoned"))?
                     .desktop;
+                // click 新建种类为 click 的 Event，dispatch 使用调用者提供事件；两者都将可选具体 Mount 交传播模块验证。
                 let (event, mount) = if matches!(self.operation, Click) {
                     let definition = desktop_type(cx.store(), "Event", desktop)?;
                     (
@@ -883,6 +923,7 @@ impl NativeCallable for Function {
             }
             _ => return Err(invalid("unsupported Block operation")),
         }
+        // 非提前返回的结构编辑/订阅操作在末尾统一经过写屏障，触发拥有边更新和变更日志。
         cx.replace_payload(data_ref, data)?;
         Ok(NativeResult::Return(result))
     }

src/bridge/ui_bridge/developer_pages.rs

@@ -10,18 +10,20 @@ struct OpenTool {
     ui: ObjectRef,
 }
 impl NativeCallable for OpenTool {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 仅接受一个工具名称字符串，工具类型与白名单在 invoke 检查。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(1))
     }
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 把白名单工具名转换成对应托管 Page；New tab 转交预编译工厂，其余管理页复用已有实例或创建新页。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let [Value::Text(name)] = args else {
             return Err(invalid("developerTools requires a tool name"));
         };
+        // 工具名白名单包含四个管理页和特殊新标签动作，拒绝任意字符串进入工厂/工具标记路径。
         if !["Console", "Sources", "Network", "Settings", "New tab"].contains(&name.as_str()) {
             return Err(invalid("unknown developer tool"));
         }
+        // 新标签交给预编译 ui.newTab 托管工厂，经 NativeResult::Invoke 回到同一 VM 执行。
         if name == "New tab" {
             let factory = object(Some(&cx.store().get_attr(self.ui, "newTab")?))?;
             return Ok(NativeResult::Invoke {
@@ -29,6 +31,7 @@ impl NativeCallable for OpenTool {
                 arguments: vec![],
             });
         }
+        // 锁内只复制弱节点索引，之后逐个升级并查工具标记，不持 session 锁运行 show 的流程。
         let nodes = self
             .session
             .lock()
@@ -39,6 +42,7 @@ impl NativeCallable for OpenTool {
             if let Some(page) = cx.upgrade(weak)?
                 && cx.store().get_attr(page, "_tesseraTool").ok() == Some(Value::Text(name.clone()))
             {
+                // 已有同类工具页则激活并聚焦其所属原生窗口，不每次打开都创建重复 Page。
                 show(cx, page, &self.session)?;
                 let window = {
                     let state = self
@@ -56,6 +60,7 @@ impl NativeCallable for OpenTool {
                 return Ok(NativeResult::Return(Value::Object(page)));
             }
         }
+        // 没有现存工具页才创建空托管 Page，_tesseraTool 标记让宿主在该页面位置绘制对应管理工具。
         let page = new_typed_block(
             cx,
             Data::new(Kind::Page, vec![], 0.0, 0.0),
@@ -78,6 +83,7 @@ pub(super) fn install(vm: &mut Vm, ui: ObjectRef, session: &Shared) -> Result<()
         },
         vec![ui],
     ))?;
+    // 函数 captures 保活 ui；安装属性建立拥有边后释放局部分配根，避免额外常驻根。
     vm.set_attr(ui, "developerTools", Value::Object(function))?;
     vm.release(function)?;
     Ok(())
@@ -87,6 +93,7 @@ pub(super) fn install(vm: &mut Vm, ui: ObjectRef, session: &Shared) -> Result<()
 /// Its functions/classes and callbacks remain ordinary managed VM objects.
 /// 编译并安装 VM 私有的起始页工厂，供新页面动作重复调用。
 pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
+    // 源码随 binary 嵌入，每个 VM 安装时解析/编译一次；函数工厂之后重复执行不再重复编译模块。
     let source = frontend::EndorReader::from_text(
         "tessera:start-page.endor",
         include_str!("start_page.endor"),
@@ -96,6 +103,7 @@ pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
         &ast,
         &source,
         &compiler::CompileOptions {
+            // 显式声明模块可见的 ui 与宿主类型名；私有 globals 不污染用户主会话的命名空间。
             globals: std::iter::once("ui")
                 .chain(TYPE_NAMES.iter().copied())
                 .map(str::to_owned)
@@ -107,6 +115,7 @@ pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
     let result = (|| -> Result<()> {
         bridge.install_globals(vm, globals)?;
         let code = compiled.load(vm)?;
+        // 执行模块定义类和工厂，使用单次预算；这里不主动调用 newTab，不在安装时打开页面。
         let value = vm.execute_with_limits(
             code,
             globals,
@@ -117,12 +126,14 @@ pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
         );
         vm.release(code)?;
         vm.release_value(value?)?;
+        // 要求模块导出 newTab，将函数保存到 ui 上；该函数通过托管引用维持自己的私有全局环境。
         let factory = vm
             .dict_get(globals, &Value::Text("newTab".into()))?
             .ok_or_else(|| anyhow::anyhow!("start page module requires newTab"))?;
         vm.set_attr(bridge.ui, "newTab", factory)?;
         Ok(())
     })();
+    // 无论编译代码执行或导出查找成功与否，释放私有字典的局部根，再返回保存的处理结果。
     vm.release(globals)?;
     result
 }

src/bridge/ui_bridge/page_input.rs

@@ -11,6 +11,7 @@ impl UiBridge {
         vm: &mut Vm,
         input: &crate::events::Input,
     ) -> Result<()> {
+        // 锁内只读取当前发布版本与弱 Mount 身份，离开锁后才进入 VM 操作，避免持 session 锁调用用户代码。
         let (weak, desktop) = {
             let state = self
                 .session
@@ -33,6 +34,7 @@ impl UiBridge {
             .upgrade(weak)?
             .ok_or_else(|| anyhow::anyhow!("3D viewport Mount expired"))?;
         let result = (|| {
+            // 除 session 发布版本外，再检查目标自身仍挂接、版本匹配且确为 3D 视口，拒绝旧出现操作。
             let occurrence = vm.payload::<crate::mount::Mount>(mount, "Mount")?.clone();
             anyhow::ensure!(
                 occurrence.mounted
@@ -45,6 +47,7 @@ impl UiBridge {
             let camera = data
                 .camera
                 .ok_or_else(|| anyhow::anyhow!("missing 3D camera"))?;
+            // 显式配置 controller 才能接收 3D 手势；没有控制器的场景仍可显示，但不能自动修改相机。
             let controller = data
                 .controller
                 .ok_or_else(|| anyhow::anyhow!("3D controller disabled"))?;
@@ -55,6 +58,8 @@ impl UiBridge {
             let delta = input
                 .delta
                 .ok_or_else(|| anyhow::anyhow!("3D camera delta required"))?;
+            // 缩放使用倍率而非二维位移；旋转/平移通过 logical_delta 处理嵌套二维/面板投影。
+            // 不可逆映射时忽略本次连续增量，不在无效坐标上继续更新相机。
             let local_delta = if input.kind == "scene-zoom" {
                 [0., 0.]
             } else {
@@ -63,6 +68,7 @@ impl UiBridge {
                 };
                 delta
             };
+            // 可用锚点先映回所在视口空间；无法取得时使用内容左上角，传给控制器的是扣除 inset 的局部点。
             let point = input
                 .point
                 .and_then(|p| geometry.view_point(crate::geometry::Point::new(p[0], p[1]), false))
@@ -71,6 +77,7 @@ impl UiBridge {
                     geometry.x + inset.left,
                     geometry.y + inset.top,
                 ));
+            // 将输入封装为名义 CameraGesture 临时对象；不把原生 Input 或窗口指针直接交给源控制器。
             let gesture = vm.new_object()?;
             let result = (|| {
                 vm.attach_type(
@@ -81,6 +88,7 @@ impl UiBridge {
                 for (name, value) in [
                     ("dx", local_delta[0]),
                     ("dy", local_delta[1]),
+                    // factor 复用原 delta 第一项，仅缩放种类按倍率解释；dx/dy 已经转换为逻辑位移。
                     ("factor", delta[0]),
                     ("width", (geometry.width - inset.horizontal()).max(0.)),
                     ("height", (geometry.height - inset.vertical()).max(0.)),
@@ -89,6 +97,7 @@ impl UiBridge {
                 ] {
                     vm.set_attr(gesture, name, crate::native_visual::value(value))?;
                 }
+                // 绑定 controller.update 保留接收者语义，再带 camera/gesture 两个显式参数进行有界调用。
                 let function = vm.bind_attr(controller, "update")?;
                 let result = match function {
                     Value::Object(function) => vm.call_with_limits(
@@ -101,13 +110,16 @@ impl UiBridge {
                     ),
                     _ => Err(invalid("controller.update is not callable")),
                 };
+                // 先保存调用结果再释放绑定方法，错误路径同样清理；成功返回值也不保留为业务状态。
                 vm.release_value(function)?;
                 vm.release_value(result?)?;
                 Ok(())
             })();
+            // 临时手势无论控制器成功或失败均释放，然后返回先前处理结果。
             vm.release(gesture)?;
             result
         })();
+        // upgrade 得到的拥有根在闭包执行后统一释放，内部任一步失败也不会遗留该临时根。
         vm.release(mount)?;
         result
     }
@@ -118,6 +130,7 @@ impl UiBridge {
         vm: &mut Vm,
         input: &crate::events::Input,
     ) -> Result<()> {
+        // 二维视口同样先校验发布版本，再从活动表捕获原 Mount，不能因目标消失自动换成另一个视口。
         let weak = {
             let state = self
                 .session
@@ -151,6 +164,7 @@ impl UiBridge {
             let camera = data
                 .camera
                 .ok_or_else(|| anyhow::anyhow!("viewport has no camera"))?;
+            // 读取已校验的相机快照作为本次基准；共享相机用户会通过普通属性变更观察到相同更新。
             let old = crate::viewport::camera(vm.object_store(), camera)?;
             let delta = input
                 .delta
@@ -170,6 +184,7 @@ impl UiBridge {
                     .ok_or_else(|| anyhow::anyhow!("zoom anchor cannot be projected"))?;
                 let node = block::snapshot(vm.object_store(), block)?;
                 let inset = crate::layout::insets(&node);
+                // 已验证指针落在出现外框还不够；扣除 inset 后必须落入实际内容盒，禁止用边框作为缩放锚点。
                 let local = [
                     pointer.x - geometry.x - inset.left,
                     pointer.y - geometry.y - inset.top,
@@ -181,6 +196,7 @@ impl UiBridge {
                         && local[1] < geometry.height - inset.vertical(),
                     "zoom anchor is outside content viewport"
                 );
+                // 以实际钳制后的新 zoom 反求 pan，保持锚点下世界位置：old_pan + local/old_zoom = new_pan + local/new_zoom。
                 zoom = (old.zoom * delta[0]).clamp(0.01, 100.0);
                 x += local[0] / old.zoom - local[0] / zoom;
                 y += local[1] / old.zoom - local[1] / zoom;
@@ -188,9 +204,11 @@ impl UiBridge {
                 let Some(delta) = geometry.logical_delta(input.point, delta) else {
                     return Ok(());
                 };
+                // 屏幕/父层逻辑位移先撤销外层投影，再除本视口 zoom 转为相机世界偏移，不能直接加原像素增量。
                 x += delta[0] / zoom;
                 y += delta[1] / zoom;
             }
+            // 把世界偏移限制回模型坐标预算，再走 set_attr 变更追踪，不直接改原生渲染快照。
             x = x.clamp(-MAX_DIMENSION as f32, MAX_DIMENSION as f32);
             y = y.clamp(-MAX_DIMENSION as f32, MAX_DIMENSION as f32);
             vm.set_attr(camera, "x", crate::native_visual::value(x))?;
@@ -208,6 +226,7 @@ impl UiBridge {
         vm: &mut Vm,
         input: &crate::events::Input,
     ) -> Result<()> {
+        // 兼容 Page 相机不通过 Mount 定位，而是读取当前活动页面及其 Surface 副本；发布版本仍必须一致。
         let (page, mut surface, viewport) = {
             let state = self
                 .session
@@ -243,6 +262,7 @@ impl UiBridge {
                     && viewport.is_none_or(|v| pointer.x < v.width && pointer.y < v.height),
                 "zoom anchor is outside viewport"
             );
+            // 先保留旧缩放下锚点对应的世界点，再调整 zoom 并解新 pan，避免缩放时内容从光标下漂移。
             let world = surface.to_world(pointer);
             surface.zoom = (surface.zoom * delta[0]).clamp(0.1, 4.0);
             surface.pan = crate::geometry::Point::new(
@@ -253,12 +273,14 @@ impl UiBridge {
             surface.pan.x += delta[0] / surface.zoom;
             surface.pan.y += delta[1] / surface.zoom;
         }
+        // 有限页面按当前内容/视口钳制；Window 会重置导航，Canvas 则保留自由 pan/zoom。
         if let Some(viewport) = viewport {
             surface.clamp(viewport);
         }
         let limit = MAX_DIMENSION as f32;
         surface.pan.x = surface.pan.x.clamp(-limit, limit);
         surface.pan.y = surface.pan.y.clamp(-limit, limit);
+        // 最终回写活动 Page 的普通托管属性，后续刷新重新提取 Surface；此函数不直接发布原生帧。
         vm.set_attr(page, "panX", crate::native_visual::value(surface.pan.x))?;
         vm.set_attr(page, "panY", crate::native_visual::value(surface.pan.y))?;
         vm.set_attr(page, "zoom", crate::native_visual::value(surface.zoom))?;

src/bridge/ui_bridge/signatures.rs

@@ -14,6 +14,8 @@ pub(super) fn method_signature(
     use AnnotationType::{Any, Function, Nominal, Number, String as TextType, Unit};
     use Operation::*;
     let nominal = |name| desktop_type(store, name, desktop).map(Nominal);
+    // 先描述显式实参，不含隐式 receiver；后面统一在 parameters 首部补接收者。
+    // ReadOnly/Mutating/External 是 VM 调用效果契约，不是线程调度策略。
     let (arguments, returns, effect) = match operation {
         Translate3D | Rotate3D => (vec![Number, Number, Number], Unit, CallEffect::Mutating),
         CameraControl => (
@@ -21,6 +23,7 @@ pub(super) fn method_signature(
             Unit,
             CallEffect::Mutating,
         ),
+        // 绑定创建可取消 Subscription，并改写目标连接关系，因此属于 Mutating。
         Bind => (
             vec![TextType, Function],
             nominal("Subscription")?,
@@ -30,6 +33,7 @@ pub(super) fn method_signature(
         Children => (vec![], Any, CallEffect::ReadOnly),
         Invalidate => (vec![TextType], Unit, CallEffect::Mutating),
         SetText | SetColor => (vec![TextType], Unit, CallEffect::Mutating),
+        // append/insert 返回稳定 slot 数值；remove/replace/move 返回 Unit，调用方不能把它们当返回孩子对象的集合方法。
         Append => (vec![nominal("Block")?], Number, CallEffect::Mutating),
         Insert => (
             vec![Number, nominal("Block")?],
@@ -40,7 +44,9 @@ pub(super) fn method_signature(
         Replace => (vec![Number, nominal("Block")?], Unit, CallEffect::Mutating),
         Move => (vec![Number, Number], Unit, CallEffect::Mutating),
         Render | Navigate => (vec![nominal("Block")?], Unit, CallEffect::Mutating),
+        // 链式 API 返回接收者名义类型，保留子类返回契约，而不是统一降为 Block。
         OnClick => (vec![Function], Nominal(receiver), CallEffect::Mutating),
+        // 事件和生命周期方法可能执行任意用户回调，使用 External，不能冒充只读视觉查询。
         OnEvent => (vec![nominal("Event")?], Unit, CallEffect::External),
         OnMount | OnUnmount => (vec![nominal("Mount")?], Unit, CallEffect::External),
         Click => (
@@ -71,6 +77,7 @@ pub(super) fn method_signature(
         ),
         _ => return Err(invalid("unsupported native method signature")),
     };
+    // Operation 维护显式参数的必需/最大个数；方法签名整体加一，将 receiver 纳入调用约定。
     let arity = operation.arity();
     let mut parameters = vec![Nominal(receiver)];
     parameters.extend(arguments);
@@ -81,6 +88,8 @@ pub(super) fn method_signature(
         returns: returns.into(),
         effect,
     };
+    // 少数参数/返回需要联合或可空类型，先用占位 Any 建基础签名，再按下标细化。
+    // On 第三个显式选项位于 parameters[3]，可接受 Bool 或字符串。
     match operation {
         Open => signature.parameters[1] = CallType::nullable(nominal("Window")?),
         PageWindow => signature.returns = CallType::nullable(nominal("Window")?),
@@ -99,6 +108,7 @@ pub(super) fn operation_signature(
     use AnnotationType::{Any, Bool, Number, String as TextType, Trait, Type, Unit};
     use Operation::*;
     let nominal = |name| desktop_type(store, name, desktop).map(AnnotationType::Nominal);
+    // 自由 UI 操作没有隐式 receiver；同时声明固定参数、可变尾参、返回名义类型和调用效果。
     let (parameters, variadic, returns, effect) = match operation {
         IsInstance => (vec![Any, Type], None, Bool, CallEffect::ReadOnly),
         IsSubtype => (vec![Type, Type], None, Bool, CallEffect::ReadOnly),
@@ -106,6 +116,7 @@ pub(super) fn operation_signature(
         Implements => (vec![Type, Trait], None, Bool, CallEffect::ReadOnly),
         Supports => (vec![Any, Trait], None, Bool, CallEffect::ReadOnly),
         OpenValue => (vec![Any], None, nominal("Page")?, CallEffect::Mutating),
+        // present 可能转交用户展示协议，效果交由被委托调用确定，不能声明成固定 ReadOnly。
         Present => (vec![Any], None, nominal("Block")?, CallEffect::Delegated),
         State => (vec![Any], None, Any, CallEffect::ReadOnly),
         StateSet => (vec![Any], None, Unit, CallEffect::Mutating),
@@ -119,6 +130,7 @@ pub(super) fn operation_signature(
         ),
         Window => (vec![], None, nominal("Window")?, CallEffect::ReadOnly),
         NewWindow => (vec![], None, nominal("Window")?, CallEffect::Mutating),
+        // 这些构造操作返回新对象，ReadOnly 允许分配并初始化新值，但不允许因此修改已有业务对象。
         TextOf => (
             vec![Any, TextType, Number, TextType],
             None,
@@ -144,6 +156,7 @@ pub(super) fn operation_signature(
             nominal("ScrollBlock")?,
             CallEffect::ReadOnly,
         ),
+        // 布局容器前两个固定参数是 Number，其后每个尾参都必须是 Block，返回类型按具体构造器选取。
         Row | Column | Overlay => (
             vec![Number, Number],
             Some(nominal("Block")?),
@@ -169,6 +182,7 @@ pub(super) fn operation_signature(
             nominal("Viewport3D")?,
             CallEffect::ReadOnly,
         ),
+        // 3D 构造器参数来自 Kind 元数据：Number/String 映成基础注解，其余名称从本 desktop 注册表查名义类型。
         SceneObject(kind) => {
             let parameters = kind
                 .parameters()
@@ -181,6 +195,7 @@ pub(super) fn operation_signature(
                 .collect::<Result<Vec<_>, VmError>>()?;
             (
                 parameters,
+                // 3D 集合尾参使用 Object 名义约束；各具体构造操作仍需在实现中检查允许的场景对象类别。
                 if kind.variadic() {
                     Some(nominal("Object")?)
                 } else {
@@ -210,6 +225,7 @@ pub(super) fn operation_signature(
         ),
         _ => return Err(invalid("unsupported UI function signature")),
     };
+    // 最终 arity 直接沿用 Operation，参数注解与可变尾参分开保存；不在此处执行操作或分配业务对象。
     Ok(CallSignature {
         arity: operation.arity(),
         parameters: parameters.into_iter().map(CallType::from).collect(),

src/bridge/ui_bridge/start_page.endor

@@ -2,12 +2,15 @@
 // 默认页由真实 Endor 对象组成：宿主负责窗口和侧栏，卡片布局、绘制和按钮回调在源代码中定义。
 // Note 复用 Column 的内容测量，但固定卡片宽度；paint 只提供背景，孩子仍沿正常树绘制。
 class Note: Column {
+    // 卡片构造的最后一个子类字段保存背景色；前面的变参仍按 Column 的孩子参数处理。
     tint: String
     function measure(self: Note, mount: Mount, constraints: Constraints): MeasureResult {
+        // 沿用 Column 内容测量得到高度，但卡片宽固定为 224；不把背景圆角绘制误当布局尺寸。
         measured = Column.measure(self, mount, constraints)
         return MeasureResult(224, measured.height)
     }
     function paint(self: Note, mount: Mount, geometry: Bounds): DisplayList {
+        // 只生成当前卡片背景，命令使用宿主给定 Bounds 的绝对布局位置，孩子仍由各自 paint 绘制。
         fill = PaintCommand()
         fill.kind = "roundedRect"
         fill.x = geometry.x
@@ -16,15 +19,18 @@ class Note: Column {
         fill.height = geometry.height
         fill.radius = 14
         fill.color = self.tint
+        // DisplayList 中的 commands 必须是受检查 ObjectList，且成员为 PaintCommand，不能返回普通字符串。
         return DisplayList(ObjectList(fill))
     }
 }
+// 继承 Button 的事件能力与内容布局，仅覆盖自身背景 paint。
 class QuietButton: Button {
     // 返回空绘制列表保留 Button 的交互能力，同时让这个入口只显示孩子文字。
     function paint(self: QuietButton, mount: Mount, geometry: Bounds): DisplayList {
         return DisplayList(ObjectList())
     }
 }
+// 动作对象集中保存回调和 home 引用；按钮绑定方法会按托管引用关系保留动作对象。
 class StartActions {
     // 保存起始页面身份，子页面中的返回按钮激活同一 Page，而不是复制一份页面。
     home: Page
@@ -33,6 +39,7 @@ class StartActions {
         page = Page()
         page.title = "窗口页面"
         back = Button("返回画布")
+        // 绑定的是原 home 的 activate 方法；此回调恢复已有页身份，不重新构造主画布。
         back.onClick(self.home.activate)
         page.render(Column(56, 20, TextBlock("恰好一个窗口", 3), TextBlock("页面跟随可用区域调整。内容和工具栏由 Endor 自己组织。"), back))
     }
@@ -45,10 +52,12 @@ class StartActions {
         content.append(Note(24, 16, TextBlock("02 / 连接片段", 2), RectBlock(176, 130, 10, "#E6DBEF"), TextBlock("内容保留在同一条连续的页面里。"), "#F4EEF7"))
         content.append(Note(24, 16, TextBlock("03 / 慢慢展开", 2), RectBlock(176, 130, 10, "#EDDCC5"), TextBlock("追加一个子组件，内容自然延伸。"), "#FAF2E7"))
         content.append(Note(24, 16, TextBlock("04 / 留一点空白", 2), TextBlock("不必把所有想法都放在第一屏。"), "#EDF1F6"))
+        // 固定初始视口内装完整内容；下一行限制滚动轴，flex 和页面 stretch 再让视口服从窗口分配。
         view = ScrollBlock(1024, 800, content)
         view.axis = "vertical"
         view.flex = 1
         page.crossAlign = "stretch"
+        // 最后提交有限视口作为 Page 内容，触发展示请求；真正的测量、绘制与原生发布由宿主刷新流程完成。
         page.render(view)
     }
     // Row 内可继续放 Column 卡片；横向滚动不要求改变 Page 的身份或生命周期。
@@ -61,6 +70,7 @@ class StartActions {
         content.append(Note(24, 16, TextBlock("继续", 2), RectBlock(176, 230, 10, "#EFDFC7"), TextBlock("Shift + 滚轮浏览更多内容。"), "#FAF3E8"))
         content.append(Note(24, 16, TextBlock("不止一屏", 2), TextBlock("右侧仍有空间。"), "#EEF1F5"))
         view = ScrollBlock(1024, 800, content)
+        // Row 自然宽度可超出视口，只有横向滚动；卡片内部仍是 Column 的纵向排版。
         view.axis = "horizontal"
         view.flex = 1
         page.crossAlign = "stretch"
@@ -68,10 +78,12 @@ class StartActions {
     }
     // 重新调用工厂得到独立页面与相机，已有画布继续保留自己的视角。
     function canvas(self: StartActions, event: Event): Unit {
+        // 每次动作都调用工厂，得到新 Page、世界树和独立相机，不复用当前页的视角状态。
         page = newTab()
     }
     // 两个文字绑定观察同一个状态对象，示范共享业务状态与多个展示位置的区别。
     function counter(self: StartActions, event: Event): Unit {
+        // 共享的是同一个托管状态对象；textOf 两次读取该对象 value，increment 更新后两个展示一起刷新。
         count = ui.state(0)
         add = Button("增加计数")
         add.onClick(count.increment)
@@ -84,12 +96,14 @@ class StartActions {
 function newTab(): Page {
     page = Page()
     page.title = "自由画布"
+    // 先建立引用当前 Page 的动作对象，再绑定按钮；回调中的 home 指向这一轮工厂创建的页面。
     actions = StartActions(page)
     fixed = Button("窗口页面")
     vertical = Button("纵向延伸")
     horizontal = Button("横向延伸")
     canvas = Button("新的画布")
     shared = QuietButton("试试：一个对象，两个视图 ↗")
+    // 订阅绑定方法而非提前调用；事件触发后在原 VM 中创建/展示相应示例页。
     fixed.on("click", actions.blank)
     vertical.on("click", actions.vertical)
     horizontal.on("click", actions.horizontal)
@@ -99,10 +113,12 @@ function newTab(): Page {
     // x/y 属于 Scene2D 子组件的世界位置；卡片内部依旧由普通 Row/Column 排版。
     hero.x = 316
     hero.y = 254
+    // Scene2D 只规定孩子的世界位置；加入后仍可追加普通卡片，位置不受窗口宽高限制。
     world = Scene2D(hero)
     left = Note(24, 14, TextBlock("随手记下", 2), RectBlock(176, 100, 10, "#D5E4DA"), TextBlock("想法不必排成一条直线。"), "#EDF3E9")
     left.x = 36
     left.y = 92
+    // 将卡片以稳定 slot 加入场景；其 x/y 在前面单独设置，不依赖追加次序推算位置。
     world.append(left)
     top = Note(24, 14, TextBlock("四种页面，同一个世界"), TextBlock("窗口 · 纵向 · 横向 · 自由画布", 1, "#7D858C"), "#EFF1F7")
     top.x = 466

src/bridge/ui_bridge/tree.rs

@@ -16,6 +16,7 @@ pub struct UiNode {
     pub align_self: Option<crate::layout::CrossAlign>,
     pub margin: crate::layout::Insets,
     pub sizing: crate::box_model::Sizing,
+    // 单边可选覆盖值；None 表示沿用 kind 的统一 padding，不代表边距为零。
     pub padding_edges: [Option<f32>; 4],
     pub border: crate::layout::Insets,
     pub border_color: String,
@@ -25,6 +26,7 @@ pub struct UiNode {
     pub protocol_key: String,
     // slot 保持组成身份；数组次序确定当前绘制/布局顺序，二者不是同一概念。
     pub slots: Vec<u64>,
+    // 从按钮、点击连接或自定义事件等能力推导的交互资格，供命中宽阶段使用，不代表最终 hitTest 必然成功。
     pub interactive: bool,
     pub kind: UiKind,
 }
@@ -48,6 +50,7 @@ impl UiNode {
 
     /// 判断是否需要对子项执行弹性主轴分配。
     pub fn has_flex(&self) -> bool {
+        // 不仅旧 flex 数值，非默认 FlexPolicy 或任一轴 Fill 也要求父节点执行分配，不能仅按自然尺寸排布。
         self.flex > 0.0
             || self.flex_policy != crate::layout::FlexPolicy::default()
             || self.sizing.width == crate::box_model::Dimension::Fill
@@ -56,6 +59,7 @@ impl UiNode {
 
     /// 判断当前节点是否会为子项指定实际分配范围，供源布局选择安排路径。
     pub fn allocates_children(&self) -> bool {
+        // 任何孩子需要弹性或拉伸即进入分配路径；align_self 优先于父 cross_align。
         self.children().iter().any(|child| {
             child.has_flex()
                 || child.align_self.unwrap_or(self.cross_align)
@@ -65,6 +69,7 @@ impl UiNode {
 
     /// 比较节点自身配置和直接子项身份，决定能否复用旧 Arc；不是深拷贝业务图。
     pub fn shallow_eq(&self, other: &Self) -> bool {
+        // 先比较所有公共视觉/协议配置，任一变化都不能复用旧节点 Arc，即使子内容完全相同。
         if self.surface != other.surface
             || self.flex_policy != other.flex_policy
             || self.flex != other.flex
@@ -84,6 +89,7 @@ impl UiNode {
         {
             return false;
         }
+        // 直接孩子按 Arc 指针比较而不是递归深比较；依赖提取保证未变子树复用 Arc，父级只需验证其身份。
         let same_children = || {
             self.children().len() == other.children().len()
                 && self
@@ -92,6 +98,7 @@ impl UiNode {
                     .zip(other.children())
                     .all(|(a, b)| Arc::ptr_eq(a, b))
         };
+        // 同类变体再比较其专有数据和直接子项；变体不同必为 false，避免布局种类切换后误复用缓存。
         match (&self.kind, &other.kind) {
             (
                 UiKind::Viewport3D {
@@ -211,6 +218,7 @@ impl UiNode {
 #[derive(Debug, Clone, PartialEq)]
 /// 视觉内容的原生分类。叶节点保存绘制数据，容器保存子树，场景视口另外保存相机与世界投影。
 pub enum UiKind {
+    // 有限 3D 视口包含不可变场景视图和面板 UI 孩子；panels 与 children/slots 按顺序对应。
     Viewport3D {
         width: f32,
         height: f32,
@@ -219,29 +227,35 @@ pub enum UiKind {
         panels: Vec<crate::layout::Size>,
         children: Vec<Arc<UiNode>>,
     },
+    // 二维世界组成保留孩子的显式位置，不使用行列的累计偏移定位。
     Scene2D {
         positions: Vec<[f32; 2]>,
         children: Vec<Arc<UiNode>>,
     },
+    // 有限布局盒子观察独立 Scene2D，相机仅影响投影，不改变场景节点原始逻辑位置。
     CanvasViewport {
         width: f32,
         height: f32,
         camera: crate::viewport::CameraView,
         children: Vec<Arc<UiNode>>,
     },
+    // 孩子重叠布置，顺序同时决定叠放次序；普通有限布局与世界 Canvas 不同。
     Overlay {
         padding: f32,
         children: Vec<Arc<UiNode>>,
     },
+    // 旧 Page Canvas 模式的兼容投影，位置数组与孩子顺序一致，页面级 Surface 保存其相机。
     Canvas {
         positions: Vec<[f32; 2]>,
         children: Vec<Arc<UiNode>>,
     },
+    // 按钮是有子内容的容器，不把标签文本硬编码进 UiKind；交互资格另由 UiNode 标志表达。
     Button {
         padding: f32,
         gap: f32,
         children: Vec<Arc<UiNode>>,
     },
+    // 文字叶节点保留源字号等级与颜色文本；排版及最终设备比例由后续布局/显示列表转换处理。
     Text {
         value: String,
         size: u32,
@@ -263,7 +277,9 @@ pub enum UiKind {
         gap: f32,
         children: Vec<Arc<UiNode>>,
     },
+    // 无视觉内容的间隔叶节点，提供布局占用尺寸。
     Spacer(f32),
+    // 滚动盒保存有限分配尺寸、允许轴和普通内容；实际偏移按 Mount 出现分别维护，不放到共享节点里。
     Scroll {
         axis: crate::scroll::Axis,
         width: f32,

src/main.rs

@@ -10,6 +10,7 @@ mod runtime;
 mod shell;
 
 pub(crate) use bridge::ui_bridge;
+// 模型层负责从 VM 场景对象提取快照，渲染层 scene3d 负责原生计算；别名区分两者。
 pub(crate) use model::scene3d as scene3d_model;
 pub(crate) use model::{
     binding, block, document, mount, object_list, presentation, protocols, snapshot, window,
@@ -41,7 +42,9 @@ fn main() -> Result<()> {
     event_loop.set_control_flow(ControlFlow::Wait);
     // 共享最近完整发布的文档。后台 worker 拥有 VM，GUI 不借用其托管堆。
     let namespace = Arc::new(RwLock::new(NamespaceState::default()));
+    // worker 发布完整 NamespaceState，activity 供 Network 工具观察，control 用于原生窗口发运行时控制请求。
     let (activity, control) = api::start(namespace.clone(), event_loop.create_proxy())?;
+    // 两个 proxy 指向同一事件循环；后台线程通过纯数据通知唤醒 GUI，不直接操作原生窗口。
     let mut app = TesseraApp::new(namespace, activity, event_loop.create_proxy(), control)?;
     // run_app 接管线程直至退出；退出后仍需检查清理过程中记录的错误。
     event_loop.run_app(&mut app)?;

src/model/binding.rs

@@ -18,15 +18,20 @@ use crate::{block, event_dispatch::Subscription, ui_bridge::attach_desktop_type}
 #[derive(Debug, Clone)]
 /// 上次绑定计算的读取观察，用于判断是否需要重新执行源计算。
 struct Cached {
+    // 每项保存读取对象/属性的版本观察；刷新时向对象存储核对，而非复制业务值。
     reads: Vec<endor_core::ReadDependency>,
+    // 只借用上次结果的身份做相等比较；不能解引用其中可能已被回收的对象。
     output: Value,
 }
 
 #[derive(Debug, Clone)]
 /// 托管属性连接，强持有计算/目标所需引用，并保留只读计算的版本缓存。
 pub struct Binding {
+    // 目标属性名；目标 Block 通过 bindings 列表拥有本连接。
     field: String,
+    // Some 表示连接有效且拥有计算函数；取消/替换后置 None，让 trace 停止保活函数。
     pub compute: Option<ObjectRef>,
+    // payload 克隆共享同一缓存，刷新局部副本也能更新缓存；首次计算前为 None。
     reads: Arc<Mutex<Option<Cached>>>,
 }
 impl ObjectPayload for Binding {
@@ -58,12 +63,13 @@ pub fn connect(
     compute: ObjectRef,
     desktop: ObjectRef,
 ) -> Result<ObjectRef, VmError> {
+    // 在触碰连接列表前拒绝非法名称，尤其禁止绑定运行时类型属性。
     if field.is_empty() || field.len() > 128 || field == "type" {
         return Err(VmError::InvalidArgument("invalid binding property"));
     }
     let (reference, data) = block::resolve(cx.store(), target)?;
     let mut data = data.clone();
-    // Only actual fields can be bound; method names are not writable targets.
+    // 只允许属性存储里已存在的字段；方法名即使可读取，也不能作为绑定写入目标。
     let properties = data
         .properties
         .ok_or(VmError::InvalidArgument("missing property storage"))?;
@@ -73,6 +79,7 @@ pub fn connect(
             "binding compute must be a Function",
         ));
     }
+    // 刷新统一以零参数调用 compute，因此必须有参数元数据并且接受零实参。
     if !cx
         .store()
         .call_arity(compute)?
@@ -85,6 +92,8 @@ pub fn connect(
             "binding compute requires zero unbound parameters",
         ));
     }
+    // 同一字段只保留一个有效计算。其他字段连接沿用；旧同字段连接失效并清缓存，
+    // 使外部仍持有的 Subscription 不会继续驱动被替换的计算。
     let mut retained = vec![];
     for connection in &data.bindings {
         let mut binding = cx
@@ -112,11 +121,12 @@ pub fn connect(
     })?;
     retained.push(connection);
     data.bindings = retained;
-    // Generic text bindings replace the legacy textOf derivation.
+    // text 改由通用绑定负责后，清除旧 textOf 推导入口，避免两套机制竞争同一属性。
     if field == "text" {
         data.text_binding = None;
     }
     cx.replace_payload(reference, data)?;
+    // 返回的取消令牌仅弱引用连接；连接生命期由目标 Block 的 bindings 决定。
     let token = cx.allocate(Subscription {
         connection: cx.store().downgrade(connection)?,
     })?;
@@ -130,14 +140,17 @@ pub fn refresh(
     nodes: &[WeakObjectRef],
     host_desktops: &HashSet<ObjectRef>,
 ) -> Result<usize> {
+    // work 跨所有轮次累计。属性 A 的写入可能使已检查的 B 失效，所以不能只扫描一次。
     let mut work = 0;
     loop {
         let mut evaluated = false;
+        // 每轮按解析后的真实 Block 身份去重，多个包装对象共享数据时只处理一次。
         let mut seen = HashSet::new();
         for weak in nodes {
             let Some(target) = vm.upgrade(*weak)? else {
                 continue;
             };
+            // 用闭包暂存失败，让下方 release 无论处理成功与否都能释放 upgrade 的强引用。
             let result: Result<()> = (|| {
                 let (reference, data) = block::resolve(vm.object_store(), target)?;
                 if !seen.insert(reference) {
@@ -154,6 +167,8 @@ pub fn refresh(
                         .lock()
                         .map_err(|_| anyhow::anyhow!("binding cache poisoned"))?
                         .clone();
+                    // 两项都成立才能跳过：读取依赖版本未变，且目标仍等于上次输出。
+                    // 后一项让外部直接改写目标后，绑定仍能恢复其计算值。
                     if cached.as_ref().is_some_and(|cached| {
                         cached
                             .reads
@@ -165,11 +180,13 @@ pub fn refresh(
                     }) {
                         continue;
                     }
+                    // 防止相互写入的绑定持续振荡；预算跨轮累计，超限向宿主报告不稳定。
                     work += 1;
                     if work > 10_000 {
                         bail!("property bindings did not stabilize within the execution budget");
                     }
                     evaluated = true;
+                    // 计算阶段禁止写入，精确记录本次实际读取；单次调用另设帧数与指令上限。
                     let (value, reads) = vm
                         .call_read_only_precise_with_limits(
                             compute,
@@ -181,12 +198,14 @@ pub fn refresh(
                         )
                         .map_err(|error| crate::endor_host::runtime_error(vm, error))?;
                     let applied: Result<()> = (|| {
+                        // 宿主桌面对象不纳入此缓存依赖；保留业务读取，避免宿主发布状态驱动重算。
                         let reads = reads
                             .dependencies
                             .into_iter()
                             .filter(|read| !host_desktops.contains(&read.object()))
                             .collect();
                         let (_, data) = block::resolve(vm.object_store(), target)?;
+                        // 先在数据副本上验证属性类型/范围，验证通过后才写回托管属性。
                         block::apply_visual_property(&mut data.clone(), &binding.field, &value)?;
                         if vm.get_attr(target, &binding.field)? != value {
                             vm.set_attr(target, &binding.field, value.clone())?;
@@ -201,6 +220,7 @@ pub fn refresh(
                             });
                         Ok(())
                     })();
+                    // 缓存不拥有输出对象；释放调用返回值后再传播应用错误，避免失败路径漏引用。
                     vm.release_value(value)?;
                     applied?;
                 }
@@ -209,6 +229,7 @@ pub fn refresh(
             vm.release(target)?;
             result?;
         }
+        // 整轮无需计算才达到固定点；即使某次计算输出未变，也再扫描一轮确认依赖有效。
         if !evaluated {
             return Ok(work);
         }

src/model/block.rs

@@ -13,6 +13,7 @@ use crate::ui_bridge::UiNode;
 #[derive(Debug, Clone)]
 /// 稳定组成 slot 与子 Block 的配对；slot 不依赖孩子当前的屏幕位置。
 pub struct Child {
+    // slot 标识父组件中这条组成边，移动行序不改变它；同一 Block 可通过不同 slot 出现多次。
     pub slot: u64,
     pub block: ObjectRef,
 }
@@ -57,6 +58,7 @@ pub enum Kind {
 #[derive(Debug, Clone)]
 /// 对共享 Cell 的稳定包装。赋值可让所有别名一起改指向，而每次出现的 Mount 仍独立。
 pub struct Block {
+    // 共享赋值单元 Cell；其值可为最终 Data 或另一个 Block，从而保留别名身份并转发属性/类型查询。
     pub state: ObjectRef,
     pub page: bool,
     pub tasks: Option<ObjectRef>,
@@ -72,6 +74,7 @@ impl ObjectPayload for Block {
         let Value::Object(value) = store.cell_get(self.state)? else {
             return Err(VmError::InvalidArgument("Block state is not an object"));
         };
+        // 若 Cell 指向替代 Block，将属性查询继续转发；否则读取 Data.properties 的普通托管字段。
         if store.object(value)?.payload().as_any().is::<Block>() {
             Ok(Some(value))
         } else {
@@ -94,6 +97,7 @@ impl ObjectPayload for Block {
             Ok(Some(value))
         } else {
             store.payload::<Data>(value, "Block data")?;
+            // 到达最终 Data 时停止类型转发，使用当前 Block 自身名义类型；只有替换为其他 Block 才继续转发类型。
             Ok(None)
         }
     }
@@ -126,11 +130,13 @@ impl ObjectPayload for Block {
         if !store.object(source)?.payload().as_any().is::<Self>() {
             return Ok(None);
         }
+        // Page 与普通组件不能交叉共享赋值，防止把窗口/页面生命周期能力替换成普通叶组件。
         if store.payload::<Self>(source, "Block")?.page != self.page {
             return Err(VmError::InvalidArgument(
                 "Page assignment requires another Page",
             ));
         }
+        // 建立转发前检查源展开图不能回到本 Cell，禁止共享赋值在别名或组成关系中形成环。
         validate(store, source, Some(self.state))?;
         Ok(Some(self.state))
     }
@@ -150,6 +156,7 @@ pub struct Data {
     pub align_self: Option<crate::layout::CrossAlign>,
     pub margin: crate::layout::Insets,
     pub sizing: crate::box_model::Sizing,
+    // 四边覆盖顺序为上、右、下、左；None 表示回退统一 padding，不等于零。
     pub padding_edges: [Option<f32>; 4],
     pub border: crate::layout::Insets,
     pub border_color: String,
@@ -160,19 +167,23 @@ pub struct Data {
     pub scroll_axis: crate::scroll::Axis,
     pub position: [f32; 2],
     pub surface: crate::page::Surface,
+    // 下次插入的单调 slot，初始孩子按 0..len 编号，后续重排不把旧 slot 重新编号。
     pub next_slot: u64,
+    // Page 导航历史是真实托管拥有边；后退/前进可重新展示同一个对象，而非复制快照。
     pub history: Vec<ObjectRef>,
     pub history_index: usize,
     pub bindings: Vec<ObjectRef>,
     pub text_binding: Option<(ObjectRef, String)>,
     pub click: Option<ObjectRef>,
     pub subscriptions: Vec<ObjectRef>,
+    // 源可读写的视觉字段存储；Data 自身保存结构边与构造默认值，提取时再将当前属性覆盖到派生副本。
     pub properties: Option<ObjectRef>,
 }
 
 impl Data {
-    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
+    /// 建立组件业务描述，为初始孩子分配稳定 slot，并初始化无绑定、无订阅的默认布局策略。
     pub fn new(kind: Kind, children: Vec<ObjectRef>, padding: f32, gap: f32) -> Self {
+        // 先为输入孩子分配稳定 slot，next_slot 从当前长度继续，后续追加不会复用被删除条目的编号。
         let next_slot = children.len() as u64;
         Self {
             kind,
@@ -215,6 +226,7 @@ impl Data {
     }
     /// 检查原生组件种类是否承载子组成，供树修改和布局选择使用。
     pub fn is_container(&self) -> bool {
+        // 这些类别允许通过通用 Children 方法编辑；Viewport3D 的面板内容来自 Scene3D 提取，不是普通 children 列表。
         matches!(
             self.kind,
             Kind::Row
@@ -244,6 +256,7 @@ impl ObjectPayload for Data {
     }
     /// 枚举本对象真正拥有的托管强引用，供 Aster 引用追踪和循环回收使用。
     fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
+        // 所有结构字段中出现的托管强引用必须枚举：场景/相机、属性存储、孩子、历史、绑定、订阅和回调。
         if let Some(scene) = self.scene3d {
             visit(scene);
         }
@@ -280,15 +293,18 @@ impl ObjectPayload for Data {
 /// 分配 Data、共享 Cell 和 Block 包装，并让托管图拥有必要引用。
 pub fn allocate(cx: &mut NativeContext<'_>, mut data: Data) -> Result<ObjectRef, VmError> {
     let page = matches!(data.kind, Kind::Page);
+    // 分配拥有边前检查每个孩子都是有效有限 Block 图；非法组成直接失败，不截断部分 UI。
     for child in &data.children {
         validate(cx.store(), child.block, None)?;
     }
+    // 把原生默认参数显式写成普通属性，使源赋值、绑定及精确依赖跟踪观察到同一存储。
     let properties = cx.new_object()?;
     for (name, value) in native_properties(&data) {
         cx.set_attr(properties, name, value)?;
     }
     data.properties = Some(properties);
     let data = cx.allocate(data)?;
+    // 最终建立 Block -> Cell -> Data -> properties/children 拥有链，均在 VM 中参与追踪和循环回收。
     let state = cx.new_cell(Some(Value::Object(data)))?;
     cx.allocate(Block {
         state,
@@ -314,6 +330,7 @@ pub fn resolve_tracked(
     let mut seen = std::collections::HashSet::new();
     let mut dependencies = Vec::new();
     loop {
+        // 解析整条转发路径防环；依赖收集同时记录每层 Block 与 Cell，任一转发变更都会让视觉缓存失效。
         if !seen.insert(current) {
             return Err(VmError::InvalidArgument("cyclic Block reference"));
         }
@@ -322,6 +339,7 @@ pub fn resolve_tracked(
         let Value::Object(value) = store.cell_get(state)? else {
             return Err(VmError::InvalidArgument("Block state is not an object"));
         };
+        // 遇到 Data 返回最终存储身份与借用引用；否则下一轮要求该值必须是 Block，不接受任意对象。
         if store.object(value)?.payload().as_any().is::<Data>() {
             dependencies.push(value);
             return Ok((
@@ -336,7 +354,7 @@ pub fn resolve_tracked(
 
 /// Validate the entire finite expansion before establishing a new composition
 /// edge. The node count is an explicit rejected resource quota, not truncated UI.
-/// 检查当前输入或发布值的不变量，调用方据校验结果决定是否继续。
+/// 完整展开 Block/Cell/孩子图，拒绝环、禁止目标回边及超过 10000 次展开的组成。
 pub fn validate(
     store: &ObjectStore,
     root: ObjectRef,
@@ -356,11 +374,13 @@ pub fn validate(
                 path.remove(&state);
             }
             Step::Enter(block) => {
+                // 预算按实际展开次数而非不同对象数计算，共享子树重复出现也计入资源工作量。
                 visits += 1;
                 if visits > 10_000 {
                     return Err(VmError::ExecutionLimit("expanded Block graph"));
                 }
                 let state = store.payload::<Block>(block, "Block")?.state;
+                // path 只追踪当前祖先 Cell，允许其他分支共享同一组件；forbidden_state 额外阻止新边回到将被修改的目标。
                 if forbidden_state == Some(state) || !path.insert(state) {
                     return Err(VmError::InvalidArgument(
                         "Block composition would create a cycle",
@@ -375,6 +395,7 @@ pub fn validate(
                         "Block composition would create a cycle",
                     ));
                 }
+                // Data 展开孩子，非 Data 则沿共享赋值转发链继续；显式 Exit 在子树完成后清除祖先标记。
                 if let Ok(data) = store.payload::<Data>(value, "Block data") {
                     for child in data.children.iter().rev() {
                         work.push(Step::Enter(child.block));
@@ -388,8 +409,9 @@ pub fn validate(
     Ok(())
 }
 
-/// 将当前托管或可变状态提取为后续阶段使用的派生表示。
+/// 用一次性空 RenderCache 提取不可变视觉树；不跨调用保存快照缓存。
 pub fn snapshot(store: &ObjectStore, root: ObjectRef) -> Result<Arc<UiNode>, VmError> {
+    // 一次性提取使用空缓存，不保留跨调用结果；有增量复用需求的窗口应使用自己的 RenderCache。
     crate::snapshot::RenderCache::default().snapshot(store, root)
 }
 
@@ -401,6 +423,7 @@ pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
     fn number(value: f32) -> Value {
         Value::Number((value as f64).into())
     }
+    // 先枚举每种 Block 都有的定位、弹性、盒尺寸、边框与对齐属性，再按 kind 增补专有字段。
     let mut fields = vec![
         ("x", number(data.position[0])),
         ("y", number(data.position[1])),
@@ -455,6 +478,7 @@ pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
     {
         fields.push((
             name,
+            // 单边 padding 的 auto 编码成文本，不用数值哨兵，读取时才能区分“继承统一值”和显式零。
             edge.map_or_else(|| Value::Text("auto".into()), number),
         ));
     }
@@ -505,6 +529,7 @@ pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
         Kind::Spacer(size) => fields.push(("size", number(*size))),
         _ => {}
     }
+    // 容器才暴露统一 padding/gap 与主交叉轴策略；叶节点不因同名自定义字段被当成通用容器。
     if data.is_container() {
         fields.extend([
             ("padding", number(data.padding)),
@@ -518,6 +543,7 @@ pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
 
 /// 复制原生描述并用当前托管属性覆盖它；结果只用于展示，不反向修改业务对象。
 pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
+    // 只改本轮派生副本，逐个读取实际属性并验证；读取字段名集合来自 native_properties，不遍历任意用户字段。
     let mut data = data.clone();
     let properties = data
         .properties
@@ -526,6 +552,7 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
         let value = store.get_attr(properties, name)?;
         apply_visual_property(&mut data, name, &value)?;
     }
+    // 各单值合法仍可能存在跨字段矛盾，必须在全部覆盖完成后校验 min/max 关系。
     if data.flex_policy.min > data.flex_policy.max {
         return Err(VmError::InvalidArgument("flexMin exceeds flexMax"));
     }
@@ -541,6 +568,7 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
                 "CanvasViewport requires a Camera2D",
             ))?,
         )?;
+        // CanvasViewport 只容纳一个 Scene2D 根，允许其内部无限空间布局，但不接受多个普通孩子冒充场景。
         if data.children.len() != 1
             || !matches!(
                 resolve(store, data.children[0].block)?.1.kind,
@@ -558,6 +586,7 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
         let definition = store.type_of(controller)?.ok_or(VmError::InvalidArgument(
             "3D controller requires a nominal update method",
         ))?;
+        // 3D 控制器要求名义类型上的 update，接受含接收者在内三参；调用执行与预算在输入分发路径处理。
         let method = store
             .lookup_method(definition, "update")?
             .ok_or(VmError::InvalidArgument(
@@ -578,6 +607,7 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
 /// 按属性名检查和解码源值，再更新对应视觉字段；非法尺寸、枚举或颜色被拒绝。
 pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Result<(), VmError> {
     let bad = || VmError::InvalidArgument("invalid native visual property");
+    // 常规视觉长度/系数只接受非负有限值；坐标和 pan 在下面走允许负数的独立路径。
     let number = || -> Result<f32, VmError> {
         let Value::Number(value) = value else {
             return Err(bad());
@@ -588,6 +618,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
         }
         Ok(n)
     };
+    // x/y 对所有组件生效；页面 pan/zoom 只作用 Page。这里不是任意字段存在性校验，不适用种类会跳过更新。
     if matches!(name, "x" | "y" | "panX" | "panY" | "zoom") {
         let n = crate::scroll::coordinate(value)?;
         match name {
@@ -596,6 +627,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
             "panX" if matches!(data.kind, Kind::Page) => data.surface.pan.x = n,
             "panY" if matches!(data.kind, Kind::Page) => data.surface.pan.y = n,
             "zoom" if matches!(data.kind, Kind::Page) => {
+                // Page 兼容相机缩放范围不同于独立 Camera2D 的 0.01..100，保持两套源协议各自限制。
                 if !(0.1..=4.0).contains(&n) {
                     return Err(invalid_zoom());
                 }
@@ -613,6 +645,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
         return Ok(());
     }
     match name {
+        // controller 接受对象或明确的字符串 none，不能拿 Nil 隐式取消；后续 visual_data 检查其名义方法。
         "controller" if matches!(data.kind, Kind::Viewport3D { .. }) => {
             data.controller = match value {
                 Value::Object(controller) => Some(*controller),
@@ -621,6 +654,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
             };
             return Ok(());
         }
+        // camera/scene 这里仅检查 Object 并记录身份，实际 payload/结构验证由各视口快照入口继续执行。
         "camera"
             if matches!(
                 data.kind,
@@ -647,6 +681,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
                 "paddingBottom" => 2,
                 _ => 3,
             };
+            // 单边 auto 清除覆盖值；数值零保留 Some(0)，从而确实覆盖统一 padding。
             data.padding_edges[index] = if matches!(value, Value::Text(text) if text == "auto") {
                 None
             } else {
@@ -682,6 +717,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
             let Value::Text(overflow) = value else {
                 return Err(bad());
             };
+            // overflow 只切换可见/裁剪，不暗中启用滚动；需要偏移与输入消费必须使用 ScrollBlock。
             data.clip_children = match overflow.as_str() {
                 "clip" => true,
                 "visible" => false,
@@ -733,6 +769,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
             data.margin.left = number()?;
             return Ok(());
         }
+        // basis 的 Nil 与 auto 都表示内容基准；其他值使用非负长度检查。flexMin/Max 的相互关系在完整提取后验证。
         "flexBasis" => {
             data.flex_policy.basis = if matches!(value, Value::Nil)
                 || matches!(value, Value::Text(text) if text == "auto")
@@ -762,6 +799,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
         return Ok(());
     }
     let container = data.is_container();
+    // alignSelf 可由任何孩子独立声明，crossAlign 只解释容器配置；auto 恢复继承父交叉轴策略。
     if name == "alignSelf" || (container && name == "crossAlign") {
         let Value::Text(value) = value else {
             return Err(bad());
@@ -793,6 +831,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
             let Value::Text(value) = value else {
                 return Err(bad());
             };
+            // 文本属性按 UTF-8 字节设 16 KiB 上限，防止单个 Block 超过原生视觉文本预算。
             if value.len() > 16_384 {
                 return Err(bad());
             }
@@ -800,6 +839,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
         }
         (Kind::Text { size, .. }, "size") => {
             let n = number()?;
+            // Text size 是 1..8 的离散倍率，不能把任意浮点字号通过 as u32 悄悄截断。
             if !(1.0..=8.0).contains(&n) || n.fract() != 0.0 {
                 return Err(bad());
             }
@@ -809,6 +849,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
             let Value::Text(value) = value else {
                 return Err(bad());
             };
+            // 颜色赋值先验证文本格式再替换派生颜色，避免错误字符串进入软件渲染器。
             crate::document::parse_color(value).map_err(|_| bad())?;
             color.clone_from(value);
         }
@@ -824,6 +865,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
         (Kind::Rect { height, .. }, "height") => *height = number()?,
         (Kind::Rect { radius, .. }, "radius") => *radius = number()?,
         (Kind::Spacer(size), "size") => *size = number()?,
+        // 剩余 kind 专有尺寸与容器字段按各自规则覆盖；未知字段忽略，不在此处删除或修改用户自定义属性。
         (_, "padding") if container => data.padding = number()?,
         (_, "gap") if container => data.gap = number()?,
         _ => {}

src/model/document.rs

@@ -49,8 +49,9 @@ impl Default for NamespaceState {
 }
 
 impl NamespaceState {
-    /// 仅接收当前 session 的纯数据窗口命令，并按种类合并同资源的重复请求。
+    /// 在成功发布边界切换到指定 session，并按动作类别合并窗口命令；世代变化时丢弃旧命令。
     pub fn publish_window_commands(&mut self, session: u64, commands: Vec<crate::window::Command>) {
+        // 跨运行时世代先丢弃旧命令，并去除旧副窗口视口记录；主壳窗口可跨 VM 替换继续存在。
         if self.runtime_session != session {
             self.window_commands.clear();
             // The primary shell survives VM replacement. Secondary native
@@ -59,10 +60,12 @@ impl NamespaceState {
                 .retain(|id, _| *id == crate::window::MAIN_WINDOW);
         }
         self.runtime_session = session;
+        // 零表示无有效 VM 会话，清空传输请求并忽略传入命令，不能让退役结果重新控制窗口。
         if session == 0 {
             self.window_commands.clear();
             return;
         }
+        // 本方法接纳传入 session 作为当前世代，调用方负责只在成功发布边界调用；同资源同动作保留最新请求。
         for command in commands {
             self.window_commands
                 .retain(|old| !old.command.same_kind(&command));
@@ -95,13 +98,14 @@ impl NamespaceState {
         Ok(Some(revision))
     }
 
-    /// 清空本对象维护的当前内容或缓存，后续状态由调用方重新建立。
+    /// 推进提交身份和发布版本，替换为空文档并清除运行时命令，使旧提交不能覆盖清空结果。
     pub fn clear(&mut self) -> Result<u64> {
         let submission = self.next_submission()?;
         let revision = self
             .revision
             .checked_add(1)
             .context("revision counter exhausted")?;
+        // 先算好 submission 与 revision，任一溢出都不改状态；清空显示同时使旧异步发布失去提交资格。
         self.submission = submission;
         self.document = RenderDocument::default();
         self.runtime_session = 0;
@@ -117,6 +121,7 @@ pub struct RenderDocument {
     #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
     pub windows: std::collections::BTreeMap<u64, RenderDocument>,
     #[serde(skip)]
+    // 仅本机增量渲染使用，不序列化；JSON 文档仍可凭 frame.commands 绘制，不需要持有 VM 句柄。
     pub ui_root: Option<Arc<UiNode>>,
     #[serde(default)]
     pub source: String,
@@ -129,6 +134,7 @@ pub struct RenderDocument {
 impl RenderDocument {
     /// 检查当前输入或发布值的不变量，调用方据校验结果决定是否继续。
     pub fn validate(&self) -> Result<()> {
+        // 校验页面兼容相机的缩放、pan 和有限 extent；独立视口变换随后按各表与 Mount 另行检查。
         let surface = &self.frame.surface;
         if !surface.zoom.is_finite()
             || !(0.1..=4.0).contains(&surface.zoom)
@@ -144,6 +150,7 @@ impl RenderDocument {
         if self.windows.len() > 15 {
             bail!("too many window projections");
         }
+        // 副窗口只允许一层投影，键须等于其 frame.window，不能重复嵌入主窗口或再带嵌套 windows。
         for (id, document) in &self.windows {
             if *id == crate::window::MAIN_WINDOW
                 || *id != document.frame.window
@@ -164,6 +171,7 @@ impl RenderDocument {
             bail!("invalid window identity");
         }
         parse_color(&self.frame.background)?;
+        // 空平行表是兼容的“全部无 clip/view”；一旦非空就必须与 commands 等长，禁止半张索引表。
         if !self.frame.command_clips.is_empty()
             && self.frame.command_clips.len() != self.frame.commands.len()
         {
@@ -188,6 +196,7 @@ impl RenderDocument {
         if self.frame.mounts.len() > 10_000 {
             bail!("frame exceeds the 10000 mount limit");
         }
+        // 标签 ID 必须非零且唯一，最多一个活动页；标题按 UTF-8 字节限长，标签数受 MAX_PAGES 限制。
         let mut tab_ids = HashSet::new();
         if self.frame.tabs.len() > crate::ui_bridge::MAX_PAGES
             || self.frame.tabs.iter().filter(|tab| tab.active).count() > 1
@@ -199,6 +208,7 @@ impl RenderDocument {
         {
             bail!("invalid tab projection");
         }
+        // 先收集全部 Mount ID 并校验几何，再第二遍核对关系下标，允许链接指向帧中较后位置。
         let mut mount_ids = HashSet::new();
         for mount in &self.frame.mounts {
             if mount.view.is_some_and(|view| !view.valid()) {
@@ -214,6 +224,7 @@ impl RenderDocument {
             if let Some(clip) = mount.viewport_clip {
                 validate_rect(clip[0], clip[1], clip[2], clip[3], 0.0)?;
             }
+            // 滚动投影为 [x,y,maxX,maxY]，四项有限非负且实际偏移不得大于对应最大偏移。
             if let Some(scroll) = mount.scroll
                 && (!scroll.iter().all(|n| {
                     n.is_finite() && (0.0..=crate::ui_bridge::MAX_DIMENSION as f32).contains(n)
@@ -223,6 +234,7 @@ impl RenderDocument {
                 bail!("invalid scroll projection");
             }
         }
+        // 此处只保证关系目标在帧内，不做完整树环/双向一致性验证；组成与生命周期层承担更强结构不变量。
         for mount in &self.frame.mounts {
             for linked in [mount.parent, mount.first_child, mount.next_sibling]
                 .into_iter()
@@ -234,6 +246,7 @@ impl RenderDocument {
             }
         }
 
+        // 携带本机视觉根时必须与第一个根出现的业务身份一致；反序列化无 ui_root 时跳过这项。
         if let Some(root) = &self.ui_root
             && self
                 .frame
@@ -250,13 +263,15 @@ impl RenderDocument {
         Ok(())
     }
 
-    /// 校验文档后把逻辑绘制命令转换成给定设备比例的显示列表，应用变换与裁剪。
+    /// 将逻辑命令转换到设备比例并应用逐命令视图/裁剪；不自动调用 validate，发布入口须先校验。
     pub fn display_list(&self, scale: f32) -> Result<DisplayList> {
         let frame = &self.frame;
         let mut list = DisplayList::default();
         list.push(DrawCommand::Clear(parse_color(&frame.background)?));
+        // 按命令顺序取对应 clip/view；缺项按无裁剪/单位变换处理，完整文档合法性应在发布入口预先验证。
         for (index, command) in frame.commands.iter().enumerate() {
             let clip = frame.command_clips.get(index).copied().flatten();
+            // clip 已在父视图/面板对应空间，只乘设备 scale；命令本体则乘 view.zoom 再加 view 平移。
             if let Some(clip) = clip {
                 list.push(DrawCommand::PushClip(scaled_rect(
                     clip[0], clip[1], clip[2], clip[3], scale,
@@ -270,6 +285,7 @@ impl RenderDocument {
                 .unwrap_or_default();
             list.push(
                 command
+                    // 均匀缩放包含字体、半径和描边，随后平移只改原点；不能把位移再乘一次 view.zoom。
                     .to_draw_command(scale * view.zoom)?
                     .translated(Point::new(view.x * scale, view.y * scale)),
             );
@@ -277,6 +293,7 @@ impl RenderDocument {
                 list.push(DrawCommand::PopClip);
             }
         }
+        // 根层只绘制非面板的焦点框；面板内焦点已在 panel::compose 放入纹理，避免重复或脱离面板。
         if let Some(focus) = frame
             .focus
             .and_then(|id| frame.mounts.iter().find(|m| m.id == id))
@@ -311,6 +328,7 @@ impl RenderDocument {
                 list.push(DrawCommand::PopClip);
             }
         }
+        // 故障提示最后追加在页面上方，只显示错误第一行；状态是否允许输入由 Frame.hit_test 等另行限制。
         if let Some(error) = &frame.fault {
             list.push(
                 RenderCommand::RoundedRect {
@@ -361,6 +379,7 @@ pub struct CodeNode {
 impl CodeNode {
     /// 检查当前输入或发布值的不变量，调用方据校验结果决定是否继续。
     fn validate<'a>(&'a self, depth: usize, ids: &mut HashSet<&'a str>) -> Result<()> {
+        // 限制代码投影深度，避免递归查找/展示无界；同一 ids 集合跨所有分支检查全树 ID 唯一。
         if depth > 64 {
             bail!("architecture tree exceeds 64 levels");
         }
@@ -370,6 +389,7 @@ impl CodeNode {
         if !ids.insert(&self.id) {
             bail!("duplicate architecture node id: {}", self.id);
         }
+        // 零行号表示未提供来源；只有两端均非零时检查顺序，不把兼容缺失字段当非法。
         if self.start_line > 0 && self.end_line > 0 && self.start_line > self.end_line {
             bail!("invalid source range for node {}", self.id);
         }
@@ -407,12 +427,14 @@ pub struct Frame {
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub command_views: Vec<Option<crate::viewport::Transform>>,
     #[serde(skip)]
+    // 仅本机装配源覆盖/面板时使用的命令出现归属表，不进入 JSON；display_list 绘制本身不读取它。
     pub command_mounts: Vec<u64>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub mounts: Vec<MountGeometry>,
     #[serde(default)]
     pub layout_version: u64,
     #[serde(default)]
+    // 运行时世代与 layout_version 共同确定输入归属；仅布局版本相同不能跨 VM 接受事件。
     pub session: u64,
     #[serde(default)]
     pub focus: Option<u64>,
@@ -449,6 +471,7 @@ impl Default for Frame {
 /// 某次出现的几何与投影元数据。逻辑矩形不被相机直接改写，view/panel 保存通往视图空间的映射。
 pub struct MountGeometry {
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    // 可嵌套的世界 UI 映射，把页面坐标还原到此出现所在面板纹理空间。
     pub panel: Option<Arc<crate::scene3d::panel::Mapping>>,
     #[serde(default, skip_serializing_if = "std::ops::Not::not")]
     pub canvas_viewport: bool,
@@ -457,12 +480,14 @@ pub struct MountGeometry {
     #[serde(default)]
     pub camera_controls: bool,
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    // 视口内容区的额外裁剪，供相机手势锚点检查；区别于一般 Mount 的祖先 clip。
     pub viewport_clip: Option<[f32; 4]>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub view: Option<crate::viewport::Transform>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub clip: Option<[f32; 4]>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    // 当前有效滚动位置和上限，不是原始请求值；非滚动容器为 None。
     pub scroll: Option<[f32; 4]>,
     pub id: u64,
     pub block_id: String,
@@ -485,17 +510,20 @@ impl MountGeometry {
     }
     /// 把页面指针转换为该出现的布局坐标，供 hitTest 和局部事件处理使用。
     pub fn logical_point(&self, point: Point) -> Option<Point> {
+        // 先处理面板反投影及遮挡，再撤销二维 view，结果仍是布局空间绝对坐标，尚未减节点原点。
         let point = self.view_point(point, true)?;
         Some(self.view.unwrap_or_default().inverse(point))
     }
     /// 把视图位移换算成目标出现的局部位移，处理缩放与世界 UI 投影差异。
     pub fn logical_delta(&self, point: Option<[f32; 2]>, delta: [f32; 2]) -> Option<[f32; 2]> {
         let zoom = self.view.unwrap_or_default().zoom;
+        // 普通二维映射为线性，只除累计 zoom 即可；世界面板透视非线性，必须映射两个点求差。
         if self.panel.is_none() {
             return Some([delta[0] / zoom, delta[1] / zoom]);
         }
         let point = point?;
         let current = self.view_point(Point::new(point[0], point[1]), false)?;
+        // 对 point 与 point+delta 分别投影，使用 clipped=false 允许捕获拖动越出面板；投影不可逆则返回 None。
         let previous =
             self.view_point(Point::new(point[0] + delta[0], point[1] + delta[1]), false)?;
         Some([
@@ -508,6 +536,7 @@ impl MountGeometry {
         let Some(point) = self.view_point(point, true) else {
             return false;
         };
+        // 节点矩形在逻辑布局空间检查，clip 在视图/面板纹理空间检查，不能将二者坐标混用。
         let local = self.view.map_or(point, |view| view.inverse(point));
         Rect::new(self.x, self.y, self.width, self.height).contains(local)
             && self.clip.is_none_or(|c| {
@@ -524,6 +553,7 @@ impl Frame {
             .into_iter()
             .map(|index| &self.mounts[index])
             .find(|mount| {
+                // 二维视口可控制，三维视口还要求显式 camera_controls；命中外框之外，还须位于内容 viewport_clip。
                 (mount.canvas_viewport || mount.scene3d_viewport && mount.camera_controls)
                     && mount.contains(point)
                     && mount.viewport_clip.is_some_and(|clip| {
@@ -535,9 +565,11 @@ impl Frame {
     }
     /// 在无故障帧中按逆绘制顺序选中可交互的出现，空间索引只缩小候选。
     pub fn hit_test(&self, point: Point) -> Option<&MountGeometry> {
+        // 故障帧不返回可交互目标，防止用户继续向已经停止的域发送页面点击。
         if self.fault.is_some() {
             return None;
         }
+        // 索引只筛几何候选，返回最前景 interactive 出现；真正源 hitTest 协议由 worker 的 source_hit 再执行。
         self.hit_index
             .candidates(point, self.mounts.len())
             .into_iter()
@@ -636,6 +668,7 @@ impl RenderCommand {
                 color,
             } => {
                 validate_rect(*x, *y, *width, *height, *radius)?;
+                // 描边必须正且有限；具体半宽限制在软件渲染器处理，这里不要求描边小于矩形尺寸。
                 if !stroke_width.is_finite() || *stroke_width <= 0.0 {
                     bail!("stroke_width must be a positive finite number");
                 }
@@ -652,6 +685,7 @@ impl RenderCommand {
                 if !x.is_finite() || !y.is_finite() {
                     bail!("text coordinates must be finite");
                 }
+                // 有换行框时同时限制框尺寸、原点与右/下端点；无框文本在此只校验坐标有限性和文本/字号预算。
                 if let Some([width, height]) = wrap_bounds {
                     validate_rect(*x, *y, *width, *height, 0.0)?;
                     if [*x, *y, *width, *height, *x + *width, *y + *height]
@@ -719,6 +753,7 @@ impl RenderCommand {
                 size,
                 color,
                 wrap_bounds,
+            // 根据是否提供换行边界选择 WrappedText 或 Text；两者都使用同一等级字号与设备缩放。
             } => match wrap_bounds {
                 Some([width, height]) => DrawCommand::WrappedText {
                     rect: scaled_rect(*x, *y, *width, *height, scale),
@@ -752,6 +787,7 @@ fn validate_rect(x: f32, y: f32, width: f32, height: f32, radius: f32) -> Result
     if !x.is_finite() || !y.is_finite() || !width.is_finite() || !height.is_finite() {
         bail!("rectangle values must be finite");
     }
+    // 此基础检查只要求有限、非负几何与圆角，不加世界坐标绝对值上限；更严格范围由具体协议调用路径决定。
     if width < 0.0 || height < 0.0 || !radius.is_finite() || radius < 0.0 {
         bail!("rectangle dimensions and radius cannot be negative");
     }
@@ -768,6 +804,7 @@ pub fn parse_color(value: &str) -> Result<Color> {
     let hex = value
         .strip_prefix('#')
         .ok_or_else(|| anyhow::anyhow!("color must begin with #"))?;
+    // 先验证 ASCII 和精确长度，后面按字节区间切片才不会在多字节字符中间切开；不支持短色号或命名颜色。
     if !hex.is_ascii() || (hex.len() != 6 && hex.len() != 8) {
         bail!("color must use #RRGGBB or #RRGGBBAA");
     }
@@ -776,6 +813,7 @@ pub fn parse_color(value: &str) -> Result<Color> {
         parse(0..2)?,
         parse(2..4)?,
         parse(4..6)?,
+        // 顺序为 RRGGBBAA 而非 AARRGGBB，六位色号默认完全不透明。
         if hex.len() == 8 { parse(6..8)? } else { 255 },
     ))
 }
@@ -783,6 +821,7 @@ pub fn parse_color(value: &str) -> Result<Color> {
 #[cfg(test)]
 mod tests {
     #[test]
+    /// 旧文字JSON缺wrap_bounds仍走不换行命令；合法边界随DPI缩放，负宽度在发布验证中拒绝。
     fn text_wrap_bounds_validate_and_legacy_text_remains_unwrapped() {
         let mut command: RenderCommand = serde_json::from_str(
             r##"{"type":"text","x":0,"y":0,"value":"text","size":1,"color":"#000000"}"##,
@@ -808,6 +847,7 @@ mod tests {
     use super::*;
 
     #[test]
+    /// 默认空文档可通过验证且没有结构根/绘图命令，支持初始状态与清空发布。
     fn empty_document_is_valid_and_blank() {
         let document = RenderDocument::default();
         document.validate().unwrap();
@@ -816,6 +856,7 @@ mod tests {
     }
 
     #[test]
+    /// 检查六位色默认alpha255，八位色按RRGGBBAA解码，避免将末尾透明度当成首通道。
     fn parses_rgb_and_rgba_colors() {
         assert_eq!(
             parse_color("#102030").unwrap(),
@@ -832,6 +873,7 @@ mod tests {
 mod window_projection_tests {
     use super::*;
     #[test]
+    /// 同会话窗口命令可累积，新会话发布先丢旧命令；clear重置runtime_session并清空所有原生命令。
     fn replacement_and_reset_discard_old_window_projections() {
         let mut state = NamespaceState::default();
         let command = crate::window::Command {

src/model/mod.rs

@@ -1,13 +1,23 @@
 //! 模型层模块入口。包含托管业务对象、每次展示上下文、依赖缓存，以及交给窗口线程的发布值。
 //!
-// Module ownership follows the directory; crate-root aliases keep internal call sites stable.
+// 目录确定模块归属；main 中的 crate 根别名保持内部调用路径稳定。
+/// 维护托管属性绑定及其读依赖；计算结果写入目标，绑定令牌不应让隐藏目标意外常驻。
 pub(crate) mod binding;
+/// 定义托管视觉对象的业务状态、共享替换关系和容器子项；几何属于 Mount，不能写回共享 Block。
 pub(crate) mod block;
+/// 定义 GUI/HTTP 可见的完整发布文档和共享 namespace；跨线程传递拥有的数据，不传 VM 句柄。
 pub(crate) mod document;
+/// 维护对象在某个页面中的具体出现位置、稳定子槽与生命周期；同一对象可对应多个独立 Mount。
 pub(crate) mod mount;
+/// 将语言对象列表适配为宿主遍历与写入接口，保留托管身份并参与读取依赖跟踪。
 pub(crate) mod object_list;
+/// 按窗口管理页面展示上下文、Mount 准备与提交，分离业务对象寿命和一次展示的寿命。
 pub(crate) mod presentation;
+/// 提供托管视觉协议方法的解析/调用约定，让源覆盖与原生实现沿同一入口组合。
 pub(crate) mod protocols;
+/// 提取托管三维场景的节点、相机和材质；验证对象图并生成供纯数据渲染使用的场景快照。
 pub(crate) mod scene3d;
+/// 从托管对象提取展示快照与属性版本；快照是渲染输入，不承担源程序业务状态。
 pub(crate) mod snapshot;
+/// 管理 VM 内 Window/Page 资源关系、窗口命令与页面顺序，操作结果再由原生壳层执行。
 pub(crate) mod window;

src/model/mount.rs

@@ -26,7 +26,9 @@ pub struct Mount {
     // 已发布几何与每次出现的滚动位置分开保存，同一 Block 的多个位置互不覆盖。
     pub geometry: MountGeometry,
     pub scroll_offset: [f32; 2],
+    // 最后同步的布局版本，Bounds 查询会一并返回，便于调用方识别几何属于哪轮发布。
     pub version: u64,
+    // false 后禁止依赖当前几何的操作；外部即使还持有 Mount 对象也不能把它当活动出现。
     pub mounted: bool,
     // Mount 可以拥有任务；退役后任务交付还要检查 owner 是否仍有效。
     pub tasks: Option<ObjectRef>,
@@ -53,6 +55,7 @@ impl ObjectPayload for Mount {
         true
     }
     /// 枚举本对象真正拥有的托管强引用，供 Aster 引用追踪和循环回收使用。
+    // 仅 block 和 tasks 是 payload 的强拥有边；page/parent/child/sibling 是弱边，不参与 trace。
     fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
         visit(self.block);
         if let Some(tasks) = self.tasks {
@@ -86,6 +89,7 @@ enum Query {
 struct Method {
     signature: endor_core::CallSignature,
     owner: ObjectRef,
+    // 方法对象拥有 Mount，但不能经桌面反向保活整个窗口；需要桌面能力时再 upgrade。
     desktop: WeakObjectRef,
     query: Query,
 }
@@ -95,7 +99,7 @@ impl NativeCallable for Method {
     fn signature(&self) -> Option<endor_core::CallSignature> {
         Some(self.signature.clone())
     }
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 适配器已绑定 Mount；坐标测试/转换与scrollTo/By接受两个数，其余层次/几何/焦点查询零参。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(
             if matches!(
@@ -114,9 +118,10 @@ impl NativeCallable for Method {
         ))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 读取具体出现位置，先检查仍挂载与几何可用性，再执行层次、坐标、焦点、滚动或拾取操作，避免使用已退役上下文。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let mount = cx.store().payload::<Mount>(self.owner, "Mount")?.clone();
+        // 层次查询允许观察已经脱离的对象（通常得到 Nil）；几何、焦点、滚动、拾取等必须仍挂接。
         if !mount.mounted
             && matches!(
                 self.query,
@@ -135,6 +140,7 @@ impl NativeCallable for Method {
         {
             return Err(VmError::InvalidArgument("Mount is no longer attached"));
         }
+        // 除 VM 元数据检查外入口再核对实际参数数目；二维坐标/位移操作取两个 Number，其余零参。
         let arity = if matches!(
             self.query,
             Query::HitTest
@@ -153,6 +159,7 @@ impl NativeCallable for Method {
         }
         let value = match self.query {
             Query::ToView | Query::ToLocal => {
+                // 布局期间几何尚未提交，坐标转换不能把临时 bounds 与上帧投影混用。
                 if mount.layout.is_some() {
                     return Err(VmError::InvalidArgument(
                         "coordinate conversion requires committed geometry",
@@ -164,6 +171,7 @@ impl NativeCallable for Method {
                 );
                 let point =
                     if matches!(self.query, Query::ToView) {
+                        // ToView 先将局部点加节点原点，再套二维 view；若在世界面板内，还继续向外投影到页面。
                         let point = mount.geometry.view.unwrap_or_default().point(
                             crate::geometry::Point::new(
                                 point.x + mount.geometry.x,
@@ -176,6 +184,7 @@ impl NativeCallable for Method {
                             .as_ref()
                             .map_or(Some(point), |panel| panel.project_point(point))
                     } else {
+                        // ToLocal 先撤销面板和视图投影，再减节点几何原点；不可逆时返回 Nil，而非虚构坐标。
                         mount.geometry.logical_point(point).map(|point| {
                             crate::geometry::Point::new(
                                 point.x - mount.geometry.x,
@@ -183,6 +192,7 @@ impl NativeCallable for Method {
                             )
                         })
                     };
+                // 转换成功才分配名义 Point；失败返回 Nil，不把无效数值写进结果属性。
                 if let Some(point) = point {
                     let result = cx.new_object()?;
                     let desktop = cx.upgrade(self.desktop)?.ok_or(VmError::InvalidArgument(
@@ -196,6 +206,7 @@ impl NativeCallable for Method {
                     Value::Nil
                 }
             }
+            // 同一滚动入口区分绝对位置和相对增量，钳制、挂接状态与写屏障交由 scroll::set 统一执行。
             Query::ScrollTo | Query::ScrollBy => {
                 crate::scroll::set(
                     cx,
@@ -231,6 +242,7 @@ impl NativeCallable for Method {
                     ),
                 )?
             }
+            // 返回帧中已钳制的有效位置与最大偏移，不直接暴露可能尚未投影的 scroll_offset 原值。
             Query::ScrollPosition => {
                 let p = mount
                     .geometry
@@ -243,6 +255,8 @@ impl NativeCallable for Method {
                 Value::Object(result)
             }
             Query::Bounds => {
+                // 布局只读调用中可查询当前安排阶段的临时 bounds；测量时尚无 bounds，明确报错。
+                // 非布局期则读取最后提交的 MountGeometry。
                 let geometry = if let Some(layout) = &mount.layout {
                     layout
                         .lock()
@@ -260,6 +274,7 @@ impl NativeCallable for Method {
                     ]
                 };
                 let bounds = cx.new_object()?;
+                // 从本方法返回签名取得 Bounds 的名义类型，避免生成一个仅字段相似的普通对象。
                 let endor_core::CallType::Single(endor_core::AnnotationType::Nominal(definition)) =
                     &self.signature.returns
                 else {
@@ -281,6 +296,7 @@ impl NativeCallable for Method {
                 )?;
                 Value::Object(bounds)
             }
+            // 请求焦点先让出现进入可见范围，再检查可聚焦资格并写入桌面请求；后续发布负责实际生效。
             Query::Focus => {
                 crate::scroll::into_view(cx, self.owner, self.desktop)?;
                 if !mount.geometry.interactive {
@@ -297,12 +313,14 @@ impl NativeCallable for Method {
                 cx.set_attr(desktop, "focusRequested", Value::Bool(true))?;
                 Value::Nil
             }
+            // 这里是 Mount 已提交几何的 contains 查询；源 Block 的 hitTest 覆盖由 source_hit 驱动另行执行。
             Query::HitTest => {
                 if mount.layout.is_some() {
                     return Err(VmError::InvalidArgument(
                         "Mount hitTest is unavailable during layout",
                     ));
                 }
+                // 命中坐标只要求 Number 可转有限 f32；与 scroll::coordinate 不同，此处不限制绝对值至一百万。
                 let number = |value: &Value| -> Result<f32, VmError> {
                     let Value::Number(number) = value else {
                         return Err(VmError::InvalidArgument(
@@ -331,6 +349,7 @@ impl NativeCallable for Method {
                     Query::Page => mount.page,
                     _ => unreachable!(),
                 };
+                // 弱链接不存在或目标已回收都返回 Nil；升级本身失败才传播 VM 错误。
                 weak.map(|weak| cx.upgrade(weak))
                     .transpose()?
                     .flatten()
@@ -350,6 +369,7 @@ fn mount_signature(
 ) -> Result<endor_core::CallSignature, VmError> {
     use endor_core::{AnnotationType as T, CallEffect, CallSignature, CallType};
     let nominal = |name| crate::ui_bridge::desktop_type(store, name, desktop).map(T::Nominal);
+    // 层次、拾取和坐标转换可能没有结果，使用 nullable 名义类型；变更操作返回 Unit。
     let returns = match query {
         Query::Bounds => nominal("Bounds")?.into(),
         Query::Parent | Query::FirstChild | Query::NextSibling => {
@@ -362,6 +382,7 @@ fn mount_signature(
         Query::ScrollPosition => T::Any.into(),
         _ => T::Unit.into(),
     };
+    // 滚动、相机拟合和焦点会写业务/桌面属性，声明 Mutating；其余查询允许在只读协议中调用。
     let effect = if matches!(
         query,
         Query::ScrollTo | Query::ScrollBy | Query::ScrollIntoView | Query::FitView | Query::Focus
@@ -391,6 +412,7 @@ fn mount_signature(
 #[derive(Debug, Default, Clone)]
 /// 活动出现的弱索引。真实托管拥有关系在 desktop 的挂载字典中，索引不能充当隐藏 GC 根。
 pub struct MountTable {
+    // Mount ID 到托管弱身份，真实强拥有者是 desktop.mounts 字典；order 单独保存原布局顺序。
     pub active: HashMap<u64, WeakObjectRef>,
     order: Vec<u64>,
 }
@@ -404,6 +426,7 @@ struct Sync {
     old: HashMap<u64, WeakObjectRef>,
     old_order: Vec<u64>,
     frame: Frame,
+    // true 为布局准备阶段，安装临时 Context 并保留已有滚动偏移；false 为几何提交，清 Context。
     preparing: bool,
     output: Arc<Mutex<HashMap<u64, WeakObjectRef>>>,
 }
@@ -417,13 +440,14 @@ struct LifecycleCall {
     unmount: bool,
 }
 impl NativeCallable for LifecycleCall {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// Block、Mount 与用户钩子都已捕获，生命周期序列无参调用此适配器。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 卸载时先取消 Mount 所有任务，再以 Block/Mount 为实参请求 VM 执行用户 onMount/onUnmount，不在 Rust 中直接运行源体。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
+        // 用户 onUnmount 运行前先取消该出现拥有的任务，防止退役后继续交付旧工作。
         if self.unmount {
             crate::tasks::cancel_owner(cx, self.mount)?;
         }
@@ -449,6 +473,7 @@ fn lifecycle_call(
         .store()
         .lookup_method(definition, name)?
         .ok_or(VmError::InvalidArgument("Block has no lifecycle method"))?;
+    // 生命周期包装显式捕获函数、Block、Mount，使序列执行到回调前这些对象不会被回收。
     cx.allocate(ContextNativeFunction::new(
         name,
         LifecycleCall {
@@ -462,13 +487,14 @@ fn lifecycle_call(
 }
 
 impl NativeCallable for Sync {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 展示同步步骤从捕获的帧与弱节点表读取输入，无需外部实参。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 把弱业务身份升级为本轮对象映射，再同步帧中出现位置到托管 Mount，建立结构/几何与待通知生命周期。
     fn invoke(&self, cx: &mut NativeContext<'_>, _args: &[Value]) -> Result<NativeResult, VmError> {
+        // 帧只含 Block 字符串身份，先将弱节点表升级为本次同步可用的实际对象映射。
         let mut blocks = HashMap::new();
         for weak in &self.nodes {
             if let Some(block) = cx.upgrade(*weak)? {
@@ -493,6 +519,7 @@ impl NativeCallable for Sync {
                 .map(|weak| cx.upgrade(*weak))
                 .transpose()?
                 .flatten();
+            // Mount ID 相同仍不足以复用：必须仍挂接、页面相同、真实 Block 相同，防止身份误归属。
             let reusable = if let Some(old) = old {
                 let mount = cx.store().payload::<Mount>(old, "Mount")?;
                 (mount.mounted && mount.page == page && mount.block == block).then_some(old)
@@ -516,6 +543,7 @@ impl NativeCallable for Sync {
                     layout: None,
                 })?;
                 crate::ui_bridge::attach_desktop_type(cx, object, "Mount", self.desktop)?;
+                // 每个新 Mount 安装捕获自身的原生方法；captures 中只放 Mount，桌面仍保留弱身份。
                 for (name, query) in [
                     ("bounds", Query::Bounds),
                     ("scrollTo", Query::ScrollTo),
@@ -552,6 +580,7 @@ impl NativeCallable for Sync {
             };
             objects.insert(geometry.id, object);
         }
+        // 先建立全部 Mount，再第二遍补链接，保证 parent/child/sibling 无论先后都能找到目标身份。
         let root = cx.new_dict()?;
         for geometry in &self.frame.mounts {
             let object = objects[&geometry.id];
@@ -566,6 +595,7 @@ impl NativeCallable for Sync {
                 first_child: link(geometry.first_child)?,
                 next_sibling: link(geometry.next_sibling)?,
                 geometry: geometry.clone(),
+                // 准备阶段沿用用户滚动状态；提交阶段以帧中有效偏移为准，非滚动容器归零。
                 scroll_offset: if self.preparing {
                     cx.store().payload::<Mount>(object, "Mount")?.scroll_offset
                 } else {
@@ -573,6 +603,7 @@ impl NativeCallable for Sync {
                 },
                 version: self.frame.layout_version,
                 mounted: true,
+                // 临时 Context 只有原生派生数据，无托管根；提交时置 None，表示几何可供外部查询。
                 layout: if self.preparing {
                     Some(Arc::new(Mutex::new(crate::layout::Context::default())))
                 } else {
@@ -580,6 +611,7 @@ impl NativeCallable for Sync {
                 },
             };
             let old = cx.store().payload::<Mount>(object, "Mount")?;
+            // 只在上下文、几何、版本、链接或公开挂接属性确实需更新时替换 payload，减少无关变更日志。
             if self.preparing
                 || old.layout.is_some()
                 || !old.mounted
@@ -602,6 +634,7 @@ impl NativeCallable for Sync {
                     Value::Number((self.frame.layout_version as i64).into()),
                 )?;
             }
+            // 新字典逐项拥有活动 Mount；弱链接本身不负责让整棵出现树存活。
             cx.dict_set(
                 root,
                 Value::Text(geometry.id.to_string()),
@@ -611,12 +644,14 @@ impl NativeCallable for Sync {
         let mut hooks = Vec::new();
         // Layout records are preorder; reversing guarantees children unmount
         // before their parents. A Page change creates fresh Mount contexts.
+        // 旧帧按父先子后记录，逆序退役保证孩子 onUnmount 在父之前；复用对象不退役。
         for id in self.old_order.iter().rev() {
             let weak = self.old[id];
             if let Some(object) = cx.upgrade(weak)?
                 && objects.get(id) != Some(&object)
             {
                 let mut mount = cx.store().payload::<Mount>(object, "Mount")?.clone();
+                // 先撤销挂接和全部关系，再安排回调；onUnmount 不能继续使用失效几何或沿旧链操作。
                 mount.mounted = false;
                 mount.layout = None;
                 mount.parent = None;
@@ -627,9 +662,11 @@ impl NativeCallable for Sync {
                 hooks.push(lifecycle_call(cx, object, "onUnmount")?);
             }
         }
+        // 新建顺序沿帧先序，onMount 默认父先子后；全部旧退役回调排在新挂载回调之前。
         for object in created {
             hooks.push(lifecycle_call(cx, object, "onMount")?);
         }
+        // 同步只返回生命周期序列，不在此处立即执行用户回调；调用方决定在后续阶段何时运行。
         let driver = if hooks.is_empty() {
             None
         } else {
@@ -644,6 +681,7 @@ impl NativeCallable for Sync {
             .into_iter()
             .map(|(id, object)| Ok((id, cx.store().downgrade(object)?)))
             .collect::<Result<HashMap<_, _>, VmError>>()?;
+        // 先让桌面拥有新字典，再公布原生弱索引；返回的驱动保持待退役对象直到回调结束。
         cx.set_attr(self.desktop, "mounts", Value::Object(root))?;
         *self
             .output
@@ -661,6 +699,7 @@ impl NativeCallable for Sync {
 pub struct Checkpoint {
     table: MountTable,
     dictionary: Option<ObjectRef>,
+    // 保存 payload 与 mounted/layoutVersion 两项公开属性；None 表示原先没有属性，回滚要删除。
     states: Vec<(ObjectRef, Mount, Option<Value>, Option<Value>)>,
     roots: Vec<ObjectRef>,
 }
@@ -669,6 +708,7 @@ impl Checkpoint {
     /// 释放检查点为回滚临时保留的托管根，成功提交后不再需要这些引用。
     pub fn release(self, vm: &mut Vm) -> Result<(), VmError> {
         let mut result = Ok(());
+        // 逆序释放所有临时根，单项失败仍继续尝试余下根，最终返回最后一次释放错误。
         for root in self.roots.into_iter().rev() {
             if let Err(error) = vm.release(root) {
                 result = Err(error);
@@ -685,6 +725,7 @@ impl Checkpoint {
         table: &mut MountTable,
     ) -> Result<(), VmError> {
         let result = (|| {
+            // 回滚先识别本轮新增的出现并将其脱离，再恢复原有 Mount payload、公开属性和桌面拥有字典。
             let old: std::collections::HashSet<_> =
                 self.states.iter().map(|state| state.0).collect();
             for weak in table.ordered() {
@@ -702,6 +743,7 @@ impl Checkpoint {
                         }
                         Ok::<_, VmError>(())
                     })();
+                    // 保存处理结果后先释放 upgrade 根，再传播处理错误，避免失败路径遗留临时强引用。
                     vm.release(object)?;
                     result?;
                 }
@@ -709,6 +751,7 @@ impl Checkpoint {
             for (object, mount, mounted, version) in &self.states {
                 vm.replace_payload(*object, mount.clone())?;
                 for (name, value) in [("mounted", mounted), ("layoutVersion", version)] {
+                    // 原属性存在则恢复旧值，不存在则 del_attr；已缺失可忽略，其余删除错误仍要传播。
                     if let Some(value) = value {
                         vm.set_attr(*object, name, value.clone())?;
                     } else {
@@ -730,6 +773,7 @@ impl Checkpoint {
             *table = self.table.clone();
             Ok(())
         })();
+        // 恢复过程失败也要释放检查点根；先尝试两项操作，再按恢复错误优先的顺序返回。
         let released = self.release(vm);
         result?;
         released
@@ -746,6 +790,7 @@ impl MountTable {
             Err(error) => return Err(error),
         };
         let mut roots = Vec::new();
+        // 保留旧字典，避免准备阶段 desktop.mounts 换成新字典后旧出现提前回收，导致无法恢复。
         if let Some(dictionary) = dictionary {
             vm.retain(dictionary)?;
             roots.push(dictionary);
@@ -759,6 +804,7 @@ impl MountTable {
         let result = (|| {
             for weak in self.ordered() {
                 if let Some(object) = vm.upgrade(weak)? {
+                    // upgrade 已提供一个拥有根，直接记录待释放列表，不重复 retain；随后读取失败也会统一清理。
                     checkpoint.roots.push(object);
                     let mount = vm.payload::<Mount>(object, "Mount")?.clone();
                     let mut attributes = Vec::new();
@@ -768,6 +814,7 @@ impl MountTable {
                             Err(VmError::AttributeNotFound(_)) => None,
                             Err(error) => return Err(error),
                         };
+                        // 公开属性理论上可能持有对象，快照保存 Value 本身不会自动增加 VM 根，须额外 retain。
                         if let Some(Value::Object(object)) = &value {
                             vm.retain(*object)?;
                             checkpoint.roots.push(*object);
@@ -784,6 +831,7 @@ impl MountTable {
             }
             Ok::<_, VmError>(())
         })();
+        // 检查点创建到一半失败时释放已经取得的根，不返回一个不完整且可能泄漏的检查点。
         if let Err(error) = result {
             checkpoint.release(vm)?;
             return Err(error);
@@ -811,6 +859,7 @@ impl MountTable {
                 result?;
             }
         }
+        // 故障退役不执行用户回调；将 desktop.mounts 换成空字典，再清除原生索引，撤销桌面拥有关系。
         let dictionary = vm.new_dict()?;
         let result = vm.set_attr(desktop, "mounts", Value::Object(dictionary));
         vm.release(dictionary)?;
@@ -839,6 +888,7 @@ impl MountTable {
         preparing: bool,
     ) -> Result<Option<ObjectRef>, VmError> {
         let output = Arc::new(Mutex::new(HashMap::new()));
+        // 同步入口显式保活桌面与可选页面；旧表和节点表本身仍是弱索引，不增加隐式根。
         let mut captures = vec![desktop];
         captures.extend(page);
         let function = vm.allocate(ContextNativeFunction::new(
@@ -855,9 +905,11 @@ impl MountTable {
             },
             captures,
         ))?;
+        // 先保存调用结果再释放同步入口，错误时同样清理；只有成功后才替换活动索引与顺序。
         let result = vm.call(function, &[]);
         vm.release(function)?;
         let result = result?;
+        // 从共享输出移动弱表而不是克隆；生命周期驱动若存在则作为拥有结果交给调用方释放。
         self.active = std::mem::take(
             &mut *output
                 .lock()

src/model/object_list.rs

@@ -1,5 +1,5 @@
 //! 给源协议返回的对象列表提供受控封装。列表内容通过托管引用被追踪，读方法只暴露检查后的条目。
-//! 用于儿童组成、布局结果和几何输入等需要保留对象身份的场景；不是窗口线程共享的可变容器。
+//! 用于子节点组成、布局结果和几何输入等需要保留对象身份的场景；不是窗口线程共享的可变容器。
 //!
 //! Managed indexed host results; values and the at method are traced edges.
 use endor_core::{
@@ -46,16 +46,17 @@ impl NativeCallable for At {
             endor_core::CallEffect::ReadOnly,
         ))
     }
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 绑定列表接收者已捕获，只接受一个显式索引。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(1))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 要求索引可精确转为非负平台整数，检查列表范围后返回对应托管成员，不复制成员对象。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let [Value::Number(index)] = args else {
             return Err(VmError::InvalidArgument("object list at expects an index"));
         };
+        // 先要求可精确表示为 i64 的整数，再转为 usize，拒绝小数、负数及目标平台越界值。
         let index = index
             .as_i64()
             .and_then(|v| usize::try_from(v).ok())
@@ -79,7 +80,8 @@ pub fn collection(
     build(cx, mounts, desktop, None)
 }
 
-/// 根据当前输入构造本模块的派生结果，具体的验证与资源边界见函数内步骤。
+/// 建立列表 payload 和 first/count/at 属性；definition 指定子类时保留该名义类型。
+/// 最多接受 10000 个成员；空列表的 first 为 Nil，at 越界仍报错而不返回 Nil。
 fn build(
     cx: &mut NativeContext<'_>,
     mounts: Vec<ObjectRef>,
@@ -91,6 +93,7 @@ fn build(
             "object list exceeds 10000 members",
         ));
     }
+    // 在移动 Vec 之前提取元信息；成员对象的拥有边由 ObjectList::trace 声明。
     let first = mounts
         .first()
         .copied()
@@ -105,6 +108,7 @@ fn build(
     }
     cx.set_attr(set, "first", first)?;
     cx.set_attr(set, "count", Value::Number((count as i64).into()))?;
+    // at 捕获列表，列表属性又指向 at，形成托管环；显式 captures 让 GC 能追踪和回收此环。
     let at = cx.allocate(ContextNativeFunction::new("at", At(set), vec![set]))?;
     crate::ui_bridge::attach_desktop_type(cx, at, "Function", desktop)?;
     cx.set_attr(set, "at", Value::Object(at))?;
@@ -127,27 +131,30 @@ impl NativeCallable for Constructor {
     fn signature(&self) -> Option<endor_core::CallSignature> {
         self.signature.clone()
     }
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 至少包含请求 Type，之后为可变成员对象与源子类字段，具体分段在 invoke 校验。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::range(1, usize::MAX))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 按请求类型字段数切分成员/字段，禁止覆盖列表协议保留属性，验证后分配列表并初始化源字段。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let [Value::Object(definition), values @ ..] = args else {
             return Err(VmError::InvalidArgument("ObjectList type argument"));
         };
+        // 首参是要构造的名义类型，余下实参分成“成员对象前缀”和“子类字段后缀”。
         let fields = cx
             .store()
             .payload::<endor_core::EndorTypeObject>(*definition, "Type")?
             .fields()
             .to_vec();
+        // 这些名称由列表协议占用；允许子类覆盖会令 count/first/at 与底层成员不一致。
         if fields
             .iter()
             .any(|field| matches!(field.name.as_str(), "count" | "first" | "at"))
         {
             return Err(VmError::InvalidArgument("reserved ObjectList field"));
         }
+        // 字段按类型定义顺序占据最后 N 项；checked_sub 在实参不足时返回错误，避免下标下溢。
         let count = values
             .len()
             .checked_sub(fields.len())
@@ -156,6 +163,7 @@ impl NativeCallable for Constructor {
             ))?;
         cx.store()
             .check_class_field_arguments(*definition, &values[count..])?;
+        // 字段值先按声明检查；成员前缀另行要求全部是对象，禁止把标量装入宿主对象列表。
         let members = values[..count]
             .iter()
             .map(|value| {

src/model/presentation.rs

@@ -11,12 +11,15 @@ use std::sync::Arc;
 #[derive(Debug)]
 /// 一个窗口独立的展示状态：活动页面、待提交请求、Mount、布局与源读取缓存；共享 VM 的业务状态不放在这里复制。
 pub(crate) struct Presentation {
+    // 所属托管桌面身份；此结构借用身份，真正的展示根由托管桌面字典维持。
     pub desktop: ObjectRef,
     pub closing: bool,
     pub tabs: ObjectRef,
     pub active: Option<ObjectRef>,
+    // 双层 Option 区分三态：None 无请求，Some(None) 请求清空，Some(Some(page)) 请求切页。
     pub pending: Option<Option<ObjectRef>>,
     pub last_snapshot: Option<Arc<UiNode>>,
+    // 弱身份到原生稳定标签 ID 的映射；不能因为标签历史而保活已经关闭的页面。
     pub tab_ids: Vec<(WeakObjectRef, u64)>,
     pub next_tab: u64,
     pub last_tabs: Vec<crate::tabs::Tab>,
@@ -25,7 +28,9 @@ pub(crate) struct Presentation {
     pub layout: crate::layout::LayoutRuntime,
     pub mounts: crate::mount::MountTable,
     pub published_version: u64,
+    // 即使根快照身份未变也要求重新发布一帧，例如源绘制读取的数据发生变化时。
     pub force_frame: bool,
+    // 精确名称/字典种类依赖，与下面按整个对象版本记录的 reads 分开检查。
     pub paint_names: Vec<endor_core::ReadDependency>,
     pub layout_names: Vec<endor_core::ReadDependency>,
     pub paint_reads: std::collections::BTreeMap<ObjectRef, u64>,
@@ -40,6 +45,8 @@ pub(crate) struct Presentation {
 impl Presentation {
     /// 比较布局/绘制读取版本和名称依赖，标记需要刷新并通知快照缓存。
     pub fn observe_changes(&mut self, vm: &Vm, changes: &ChangeBatch) {
+        // 先检查粗粒度对象版本，layout 优先于 paint；每类只记录第一个失效项用于诊断。
+        // 对象已经释放时版本查询失败，也视作失效，而非继续使用旧缓存。
         if let Some((phase, object, version)) = self
             .layout_reads
             .iter()
@@ -62,6 +69,8 @@ impl Presentation {
                 vm.change_version(*object).ok()
             );
         }
+        // 再核对名称级依赖，避免仅凭对象版本漏掉名称解析路径上的变化。
+        // 两个检查独立执行，因此同次观察可能分别增加计数，后者诊断可覆盖前者。
         if let Some((phase, dependency)) = self
             .layout_names
             .iter()
@@ -81,6 +90,7 @@ impl Presentation {
             };
             self.last_invalid_dependency = format!("{phase} name {}:{name}", dependency.object());
         }
+        // 把同一批 VM 写入交给视觉快照缓存，源布局/绘制依赖与原生快照依赖分别维护。
         self.render_cache.invalidate(ChangeBatch {
             changes: changes.changes.clone(),
             rescan_required: changes.rescan_required,
@@ -94,16 +104,19 @@ impl Presentation {
         affected: &std::collections::HashSet<ObjectRef>,
         reason: &str,
     ) -> Result<(), VmError> {
+        // 仅绘制失效不影响测量；其余原因清除测量结果并按 Block ID 使布局缓存失效。
         if reason != "paint" {
             self.measure_cache.invalidate(affected);
             for block in affected {
                 self.layout.invalidate(&block.to_string());
             }
         }
+        // 内容变化还可能改变组成结构，因此显式失效视觉快照及其父链；其他原因不额外做此传播。
         if reason == "content" {
             self.render_cache
                 .invalidate_objects(affected.iter().copied());
         }
+        // 仅当受影响 Block 在该窗口有活动出现时强制刷新，避免无关窗口重复发帧。
         for weak in self.mounts.active.values() {
             if let Some(mount) = cx.upgrade(*weak)?
                 && affected.contains(
@@ -118,7 +131,8 @@ impl Presentation {
         Ok(())
     }
 
-    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
+    /// 用桌面与标签注册表身份初始化窗口状态，布局和视觉缓存从空状态开始。
+    // 这里只初始化窗口级缓存，不创建 VM、不复制业务对象；active/pending 留空等待窗口展示请求。
     pub fn new(desktop: ObjectRef, tabs: ObjectRef) -> Self {
         Self {
             desktop,
@@ -158,6 +172,7 @@ pub(crate) fn split_reads(
 ) {
     let mut objects = std::collections::BTreeMap::new();
     let mut names = Vec::new();
+    // 整对象依赖按身份收集到有序表，重复项以最后一次版本为准；其余精确依赖保持原记录。
     for dependency in reads {
         match dependency {
             endor_core::ReadDependency::Object { object, version } => {
@@ -174,7 +189,9 @@ mod tests {
     use super::*;
     use crate::{layout::Size, ui_bridge::UiKind};
     #[test]
+    /// 同VM中两Presentation分别布局共享树，尺寸/出现身份独立；读观察可追踪共享对象但不能增添GC根。
     fn independent_view_geometry_and_shared_vm_reads_do_not_add_roots() {
+        // 测试在同一 VM 中建立两个 Presentation，验证各自布局尺寸/出现 ID 独立，读取依赖共享业务对象。
         let mut vm = Vm::new().unwrap();
         let mut left = Presentation::new(vm.new_object().unwrap(), vm.new_dict().unwrap());
         let mut right = Presentation::new(vm.new_object().unwrap(), vm.new_dict().unwrap());
@@ -229,6 +246,7 @@ mod tests {
         left.observe_changes(&vm, &changes);
         right.observe_changes(&vm, &changes);
         assert!(left.force_frame && right.force_frame);
+        // 最后释放业务对象并回收：两份读取记录都不应成为托管根，弱引用应升级失败。
         let weak = vm.downgrade(shared).unwrap();
         vm.release(shared).unwrap();
         vm.collect_cycles();

src/model/protocols.rs

@@ -14,14 +14,18 @@ pub fn install(
     desktop: ObjectRef,
     ui: ObjectRef,
 ) -> Result<(), VmError> {
+    // 安装前要求桥接已经创建 Trait 类型与 desktop.types 注册表；缺失时立即失败，不能安装半定义能力。
     let Value::Object(trait_type) = vm.get_attr(ui, "Trait")? else {
         return Err(VmError::InvalidArgument("missing Trait type"));
     };
     let Value::Object(types) = vm.get_attr(desktop, "types")? else {
         return Err(VmError::InvalidArgument("missing type registry"));
     };
+    // 每组声明能力名、方法及显式参数数目、提供默认签名的原生类型。
+    // 签名还含接收者参数，下面会把总 arity 调整为 parameters+1。
     for (name, methods, owner) in [
         (
+            // 测量/布局/绘制/命中能力，签名取自 Block 的原生协议实现，保证效果约束与具体方法一致。
             "Visual",
             vec![("measure", 2), ("arrange", 2), ("paint", 2), ("hitTest", 2)],
             Some("Block"),
@@ -32,6 +36,7 @@ pub fn install(
             Some("Block"),
         ),
         (
+            // 组成编辑能力属于 ContainerBlock，普通叶 Block 不因此获得追加或重排孩子的方法。
             "Children",
             vec![
                 ("append", 1),
@@ -45,6 +50,7 @@ pub fn install(
         ),
         ("Presentable", vec![("present", 1)], None),
     ] {
+        // 从当前 ui 模块查名义类型身份，不靠字符串名称把另一个运行时的类型误接进来。
         let owner_definition = if let Some(owner) = owner {
             let Value::Object(definition) = vm.get_attr(ui, owner)? else {
                 return Err(VmError::InvalidArgument("missing protocol owner"));
@@ -55,6 +61,7 @@ pub fn install(
         };
         let mut requirements = Vec::new();
         for (method, parameters) in methods {
+            // 优先复用原生方法参数/返回注解和调用效果，缺少原生签名元数据时拒绝安装。
             let mut signature = if let Some(owner) = owner_definition {
                 let function = vm
                     .object_store()
@@ -66,6 +73,7 @@ pub fn install(
                         "protocol method lacks native types",
                     ))?
             } else {
+                // Presentable 没有默认 owner，手工声明 present(receiver, Window) -> Block，调用效果为 External。
                 let window = crate::ui_bridge::desktop_type(vm.object_store(), "Window", desktop)?;
                 let block = crate::ui_bridge::desktop_type(vm.object_store(), "Block", desktop)?;
                 CallSignature::exact(
@@ -75,6 +83,7 @@ pub fn install(
                 )
             };
             signature.arity = CallArity::exact(parameters + 1);
+            // 接收者类型改为 Any，使能力可由其他符合方法契约的名义类型实现，不把契约绑定死在 Block。
             signature.parameters[0] = AnnotationType::Any.into();
             requirements.push(TypedMethodRequirement {
                 name: method.into(),
@@ -82,11 +91,13 @@ pub fn install(
             });
         }
         let capability = vm.new_typed_trait(name, requirements)?;
+        // 新能力放入宿主 roots 管理生命周期，再同时暴露于 ui 属性与 desktop 类型注册表。
         roots.push(capability);
         vm.attach_type(capability, trait_type)?;
         vm.set_attr(ui, name, Value::Object(capability))?;
         vm.dict_set(types, Value::Text(name.into()), Value::Object(capability))?;
         if let Some(owner) = owner_definition {
+            // 有默认提供者时显式登记 implements 关系；Presentable 留待具体类型声明，不自动给所有 Block 安装。
             vm.implement_trait(owner, capability)?;
         }
     }

src/model/scene3d.rs

@@ -84,8 +84,9 @@ impl Constructor {
         .into_iter()
         .find(|kind| kind.function() == name)
     }
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 返回三维原生构造的显式最小/最大参数数，不含请求 Type；Group/Scene 支持最多4096子节点。
     pub fn arity(self) -> (usize, usize) {
+        // 构造器 arity 不含 NativeTyped 的类型首参，Group/Scene 允许零到 4096 个孩子，其他零参对象使用默认属性。
         match self {
             Self::Vec3 | Self::Triangle => (3, 3),
             Self::Geometry | Self::Mesh => (2, 2),
@@ -205,6 +206,7 @@ fn set_number(
 }
 /// 解析颜色值并检查其满足当前原生绘制约定。
 fn color(value: &str) -> Result<[f32; 3], VmError> {
+    // 3D 不透明材质拒绝半透明颜色，转换为 [0,1] RGB 数值；普通二维 UI 的 alpha 不受这里限制。
     let color = crate::document::parse_color(value).map_err(|_| invalid("invalid 3D color"))?;
     if color.alpha != 255 {
         return Err(invalid("3D opaque material color requires full alpha"));
@@ -224,6 +226,7 @@ pub fn allocate(
     constructor: Constructor,
     args: &[Value],
 ) -> Result<ObjectRef, VmError> {
+    // 入口假设桥接工厂已按 arity/类型检查 args；Geometry 特殊地复制缓冲并提前返回，其余创建可编辑标记节点。
     let kind = match constructor {
         Constructor::Vec3 => NodeKind::Vector,
         Constructor::Triangle => NodeKind::Triangle,
@@ -236,6 +239,7 @@ pub fn allocate(
         Constructor::Orbit => NodeKind::Orbit,
         Constructor::Panel => NodeKind::Panel,
         Constructor::Geometry => {
+            // Geometry 构造只接受受控 ObjectList，逐成员验证 Vec3 payload 并复制数值；以后改源 Vec3 不会改已建几何。
             let vertices = object_list::items(cx.store(), object_ref(&args[0])?)?
                 .iter()
                 .map(|&item| {
@@ -257,6 +261,7 @@ pub fn allocate(
                         return Err(invalid("geometry indices require Triangle3D"));
                     }
                     let mut triangle = [0; 3];
+                    // 索引先从 Number 检查非负整数，再转 u32；是否越出顶点范围在整份 geometry.valid 校验。
                     for (index, name) in ["a", "b", "c"].into_iter().enumerate() {
                         let value = number(&cx.store().get_attr(item, name)?)?;
                         if value < 0. || value.fract() != 0. {
@@ -272,6 +277,7 @@ pub fn allocate(
                 triangles,
                 uv: vec![],
             };
+            // 缓存为原生 Arc 前统一验证顶点/三角形预算与下标范围，避免渲染线程再接触源缓冲对象。
             if !geometry.valid() {
                 return Err(invalid(
                     "invalid Geometry3D buffers or geometry budget exceeded",
@@ -300,6 +306,7 @@ pub fn allocate(
         NodeKind::Mesh => {
             let (geometry, material) = if matches!(constructor, Constructor::Box) {
                 let (w, h, d) = (number(&args[0])?, number(&args[1])?, number(&args[2])?);
+                // Box 允许零尺寸产生退化面，后续光栅/拾取跳过退化三角形；负尺寸在构造入口拒绝。
                 if w < 0. || h < 0. || d < 0. {
                     return Err(invalid("Box3D dimensions must be nonnegative"));
                 }
@@ -315,6 +322,7 @@ pub fn allocate(
             cx.set_attr(instance, "geometry", Value::Object(geometry))?;
             cx.set_attr(instance, "color", Value::Text(material))?;
         }
+        // 孩子只接受 Mesh/Group/Light/Panel 标记，不允许把相机、控制器或任意 Object 放进场景组成。
         NodeKind::Group | NodeKind::Scene => {
             let children = args.iter().map(object_ref).collect::<Result<Vec<_>, _>>()?;
             for child in &children {
@@ -327,6 +335,7 @@ pub fn allocate(
                     ));
                 }
             }
+            // 托管 children 列表拥有子节点；Node payload 自身只是标记，属性拥有边由 VM 正常追踪。
             let children = object_list::collection(cx, children, desktop)?;
             cx.set_attr(instance, "children", Value::Object(children))?;
             if kind == NodeKind::Scene {
@@ -345,6 +354,7 @@ pub fn allocate(
             cx.set_attr(instance, "color", args[3].clone())?;
             set_number(cx, instance, "intensity", number(&args[4])?)?;
         }
+        // 世界宽高与 UI 像素分辨率独立：初始纹理 512×320，content 是普通 Block 图，稍后参与独立有限布局。
         NodeKind::Panel => {
             let content = object_ref(&args[2])?;
             crate::block::validate(cx.store(), content, None)?;
@@ -379,6 +389,7 @@ pub fn allocate(
             set_number(cx, instance, "panSpeed", 1.)?;
         }
     }
+    // 只有可放置节点安装 TRS；相机用 position/target/up，方向光用方向向量，不复用网格欧拉角字段。
     if matches!(kind, NodeKind::Mesh | NodeKind::Group | NodeKind::Panel) {
         for (name, value) in [
             ("x", 0.),
@@ -405,6 +416,7 @@ struct Reader<'a> {
 impl Reader<'_> {
     /// 读取字段并登记依赖，使后续字段变更能够使 3D 快照失效。
     fn value(&mut self, object: ObjectRef, name: &str) -> Result<Value, VmError> {
+        // 读取前登记精确对象/属性依赖，HashSet 去重；返回给视觉缓存后，相关字段变化才能驱动重建。
         self.reads.insert((object, name.into()));
         self.store.get_attr(object, name)
     }
@@ -422,6 +434,7 @@ impl Reader<'_> {
     }
     /// 读取并校验透视或正交摄像机字段，生成不持有 VM 引用的投影描述。
     fn camera(&mut self, object: ObjectRef) -> Result<Camera, VmError> {
+        // 先验证宿主相机种类，再按投影策略读取 fov 或 height；不把有同名字段的对象当相机。
         let projection = match self.store.payload::<Node>(object, "3D camera")?.0 {
             NodeKind::Perspective => Projection::Perspective {
                 fov: self.number(object, "fov")?,
@@ -456,6 +469,7 @@ pub struct PanelMount {
     pub content: ObjectRef,
     pub size: crate::layout::Size,
 }
+// 三部分分别是可跨线程的不可变 View、VM 内缓存用的属性依赖、仍由 VM 驱动布局的面板 Block 根。
 pub type Snapshot = (
     Arc<scene3d::View>,
     Vec<(ObjectRef, String)>,
@@ -496,6 +510,7 @@ pub fn snapshot_reusing(
         background,
         acceleration: Arc::default(),
     };
+    // 显式进入/退出栈保存节点、父世界矩阵、退出标记与路径 key；path 仅追踪祖先，因此允许共享子树多次出现。
     let mut work = vec![(scene, Matrix::default(), false, 0u64)];
     let mut panels = Vec::new();
     let mut path = HashSet::new();
@@ -508,6 +523,7 @@ pub fn snapshot_reusing(
             continue;
         }
         visits += 1;
+        // 预算按展开出现次数，重复共享同一网格也消耗实例/顶点/三角形工作，不能只数不同对象身份。
         if visits > 4096 {
             return Err(VmError::ExecutionLimit("3D scene occurrences"));
         }
@@ -517,6 +533,7 @@ pub fn snapshot_reusing(
         work.push((object, parent, true, key));
         let kind = store.payload::<Node>(object, "3D node")?.0;
         let world = if matches!(kind, NodeKind::Mesh | NodeKind::Group | NodeKind::Panel) {
+            // 局部先缩放、旋转、平移，再乘父 world；Scene/Light 不新增 TRS，方向光仍受祖先 Group 变换。
             parent.compose(Matrix::trs(
                 reader.vector(object, ["x", "y", "z"])?,
                 reader.vector(object, ["rotationX", "rotationY", "rotationZ"])?,
@@ -531,6 +548,8 @@ pub fn snapshot_reusing(
                 for (index, child) in object_list::items(store, list)?.iter().enumerate().rev() {
                     use std::hash::{Hash, Hasher};
                     let mut hasher = std::collections::hash_map::DefaultHasher::new();
+                    // 路径 key 包含父 key、当前孩子索引和托管身份，区分同一 Panel 节点在不同路径的出现。
+                    // 此 key 与普通 Block slot 不同，场景列表重排会改变路径身份。
                     key.hash(&mut hasher);
                     index.hash(&mut hasher);
                     child.hash(&mut hasher);
@@ -540,6 +559,7 @@ pub fn snapshot_reusing(
             NodeKind::Mesh => {
                 let geometry = object_ref(&reader.value(object, "geometry")?)?;
                 let geometry = store.payload::<Geometry>(geometry, "Geometry3D")?.0.clone();
+                // 每次 mesh 出现都累计完整几何，Arc 共享只节约存储，不减少本帧实例绘制工作预算。
                 triangles += geometry.triangles.len();
                 vertices += geometry.vertices.len();
                 if vertices > 262_144 {
@@ -560,10 +580,12 @@ pub fn snapshot_reusing(
             NodeKind::Panel => {
                 // Arrangement slots cross Endor's signed integer API. A raw
                 // u64 hash can turn negative when native Bounds are created.
+                // Bounds.slot 经有符号整数 API 传递，清最高位避免变负；仍显式检测碰撞，不能假设哈希必然唯一。
                 let key = key & i64::MAX as u64;
                 if panels.iter().any(|panel: &PanelMount| panel.key == key) {
                     return Err(invalid("colliding 3D UI occurrence identities"));
                 }
+                // 有限面板根数量另限 64；每个面板还有独立像素分辨率限制和递归纹理总预算。
                 if panels.len() >= 64 {
                     return Err(VmError::ExecutionLimit("3D UI panels"));
                 }
@@ -584,6 +606,7 @@ pub fn snapshot_reusing(
                 let content = object_ref(&reader.value(object, "content")?)?;
                 crate::block::resolve(store, content)?;
                 let background = color(&text(&reader.value(object, "background")?)?)?;
+                // 面板平面以中心为原点，顶点 y 向上，UV 左上为 (0,0)；两三角形共用四个角点。
                 let geometry = Arc::new(scene3d::Geometry {
                     vertices: vec![
                         Vec3::new(-width / 2., height / 2., 0.),
@@ -607,6 +630,7 @@ pub fn snapshot_reusing(
                         surface: None,
                     }),
                 });
+                // 同时把普通 UI 根交给宿主布局，scene Mesh 先只带分辨率/背景，surface 由后续 panel::compose 装配。
                 panels.push(PanelMount {
                     key,
                     content,
@@ -622,6 +646,7 @@ pub fn snapshot_reusing(
                 }
                 let direction =
                     reader.vector(object, ["directionX", "directionY", "directionZ"])?;
+                // 用两点之差撤销父矩阵平移，仅保留线性部分对方向的影响，再归一化；零方向拒绝。
                 let direction = (world.point(direction) - world.point(Vec3::default()))
                     .normalized()
                     .ok_or(invalid("light direction cannot be zero"))?;
@@ -639,6 +664,7 @@ pub fn snapshot_reusing(
             _ => return Err(invalid("invalid node in 3D scene graph")),
         }
     }
+    // 完整世界值相等时复用旧 Scene/BVH，单独换 camera 生成新 View；不相等才重建世界空间索引。
     let scene = if let Some(scene) = reuse.filter(|scene| **scene == output) {
         scene
     } else {
@@ -646,6 +672,7 @@ pub fn snapshot_reusing(
         Arc::new(output)
     };
     let view = Arc::new(scene3d::View { scene, camera });
+    // 提取各项之后仍做完整视图校验，覆盖累计世界变换、光照、面板及整体资源不变量。
     if !view.valid() {
         return Err(invalid("invalid 3D scene snapshot"));
     }
@@ -667,6 +694,7 @@ pub fn pick(
     if !matches!(data.kind, crate::block::Kind::Viewport3D { .. }) {
         return Err(invalid("pick3D requires a Viewport3D"));
     }
+    // 先做出现/面板遮挡和裁剪命中，未命中直接 Nil；即使场景射线有交点也不能点穿外层遮挡。
     if !mount.geometry.contains(point) {
         return Ok(Value::Nil);
     }
@@ -675,6 +703,7 @@ pub fn pick(
     let Some(point) = mount.geometry.logical_point(point) else {
         return Ok(Value::Nil);
     };
+    // 从布局盒扣 inset 得到实际内容视口，再把逻辑点归一化；零面积视口没有有效投影。
     let (width, height) = (
         (mount.geometry.width - inset.horizontal()).max(0.),
         (mount.geometry.height - inset.vertical()).max(0.),
@@ -695,6 +724,7 @@ pub fn pick(
     let Some(hit) = hit else {
         return Ok(Value::Nil);
     };
+    // 原生 Hit.identity 只带文本，通过本次实际读取的托管身份重新关联节点；渲染器本身从不解引用 VM 对象。
     let mesh = reads
         .iter()
         .find_map(|(object, _)| (object.to_string() == hit.identity).then_some(*object))
@@ -718,6 +748,7 @@ pub fn pick(
         "triangle",
         Value::Number((hit.triangle as i64).into()),
     )?;
+    // 交点、法线、重心权重都包装为名义 Vec3，结果对象通过普通属性强持有它们。
     for (name, vector) in [
         ("point", hit.point),
         ("normal", hit.normal),
@@ -752,7 +783,7 @@ pub struct PointerPick {
 }
 
 /// The default controller is replaceable; camera data has no dependency on it.
-/// 为指定出现解码相机手势并调用控制器；嵌套面板输入先转换到所属视口坐标。
+/// 默认 OrbitController 根据已解码的 CameraGesture 更新相机，处理轨道、平移和缩放；可由源控制器替换。
 pub fn control(
     cx: &mut NativeContext<'_>,
     controller: ObjectRef,
@@ -770,6 +801,7 @@ pub fn control(
     let dx = reader.number(gesture, "dx")?;
     let dy = reader.number(gesture, "dy")?;
     let kind = text(&reader.value(gesture, "kind")?)?;
+    // 默认轨道控制围绕 target 使用 position-target 偏移和半径；相机有效性保证观察方向不退化。
     let offset = camera.position - camera.target;
     let radius = offset.length();
     let mut position = camera.position;
@@ -784,12 +816,14 @@ pub fn control(
                 .up
                 .normalized()
                 .ok_or(invalid("camera up cannot be zero"))?;
+            // 将偏移分解为 up 方向和水平面方向，用水平旋转更新 yaw、asin(vertical) 更新 pitch。
             let vertical = (offset.dot(up) / radius).clamp(-1., 1.);
             let horizontal = (offset - up * offset.dot(up))
                 .normalized()
                 .ok_or(invalid("orbit at pole requires a different up vector"))?;
             let (sine, cosine) = (dx * speed).sin_cos();
             let horizontal = horizontal * cosine + up.cross(horizontal) * sine;
+            // 俯仰限制在两极内侧 0.01 弧度，避免绕极点时水平基退化并导致轨道跳变。
             let pitch = (vertical.asin() + dy * speed).clamp(
                 -std::f32::consts::FRAC_PI_2 + 0.01,
                 std::f32::consts::FRAC_PI_2 - 0.01,
@@ -802,6 +836,7 @@ pub fn control(
                 return Err(invalid("panSpeed expects 0 through 100"));
             }
             let height = reader.number(gesture, "height")?.max(1.);
+            // 把逻辑像素位移换成世界单位：透视按 target 距离处的可见高度，正交按固定投影高度。
             let units = match camera.projection {
                 Projection::Perspective { fov } => {
                     2. * radius * (fov.to_radians() / 2.).tan() / height
@@ -810,6 +845,7 @@ pub fn control(
             };
             let basis = camera.basis().ok_or(invalid("invalid camera basis"))?;
             let delta = basis.right * (dx * units * speed) + basis.up * (-dy * units * speed);
+            // 平移同时移动 position 和 target，保留观察方向与轨道半径；屏幕 y 向下所以 up 分量取负。
             position = position + delta;
             target = target + delta;
         }
@@ -818,6 +854,7 @@ pub fn control(
             if !(0.1..=10.0).contains(&factor) {
                 return Err(invalid("zoom factor expects 0.1 through 10"));
             }
+            // 正交缩放只改投影高度，透视缩放改变到 target 的距离；倍率大于一均表现为拉近。
             if let Projection::Orthographic { height } = camera.projection {
                 set_number(
                     cx,
@@ -833,6 +870,7 @@ pub fn control(
         }
         _ => return Err(invalid("unsupported 3D camera gesture")),
     }
+    // 写回前校验整个计算结果，拒绝超世界范围；控制器通过普通属性更新让后续快照依赖观察变化。
     if !position.valid() || !target.valid() {
         return Err(invalid("camera movement exceeds world budget"));
     }
@@ -849,7 +887,7 @@ pub fn control(
     Ok(())
 }
 
-/// 执行托管 3D 节点的原生平移/旋转操作，供尚不支持普通数值算术表达式的源程序调用。
+/// 对允许的 3D 节点累计平移或角度旋转；相机平移同时更新 target，旋转值归一到 [0,360)。
 pub fn transform(
     cx: &mut NativeContext<'_>,
     owner: ObjectRef,
@@ -869,11 +907,13 @@ pub fn transform(
     {
         return Err(invalid("unsupported 3D transform target"));
     }
+    // 旋转增量作用欧拉角，平移增量作用位置；相机不接受本接口的欧拉角旋转。
     let names = if rotate {
         ["rotationX", "rotationY", "rotationZ"]
     } else {
         ["x", "y", "z"]
     };
+    // 先收集并验证全部轴再写入，避免验证到第二/三轴才发现越界时已修改前面轴。
     let mut updates = Vec::new();
     for (index, name) in names.into_iter().enumerate() {
         let delta = number(&args[index])?;
@@ -884,11 +924,13 @@ pub fn transform(
         updates.push((
             name,
             if rotate {
+                // 角度归一到 [0,360)，支持负增量而不使用产生负余数的普通取模。
                 value.rem_euclid(360.)
             } else {
                 value
             },
         ));
+        // 相机平移同步改 target，保留朝向；不把“移动摄像机”意外变成绕固定目标转动。
         if camera {
             let name = ["targetX", "targetY", "targetZ"][index];
             let value = number(&cx.store().get_attr(owner, name)?)? + delta;
@@ -904,11 +946,11 @@ pub fn transform(
     Ok(())
 }
 impl endor_core::NativeCallable for PointerPick {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 输入 Mount 与点击点已捕获，拾取/分发准备步骤不再接受实参。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 在当前 Mount 中重新射线拾取，构造含真实 mesh 命中的 click Event，再交托管事件系统分发。
     fn invoke(
         &self,
         cx: &mut NativeContext<'_>,
@@ -921,6 +963,7 @@ impl endor_core::NativeCallable for PointerPick {
         let hit = pick(cx, self.desktop, &mount, self.point)?;
         let definition = crate::ui_bridge::desktop_type(cx.store(), "Event", self.desktop)?;
         let event = crate::event_dispatch::new_event(cx, definition, "click")?;
+        // 点击事件把精确拾取值放到 hit（未击中则 Nil），仍以 Viewport 的 Block/Mount 作为事件传播目标。
         cx.set_attr(event, "hit", hit)?;
         crate::event_dispatch::dispatch(cx, mount.block, event, Some(self.mount), self.desktop)
     }

src/model/snapshot.rs

@@ -31,10 +31,15 @@ struct Dependency {
 #[derive(Debug, Default)]
 /// 视觉快照缓存与反向依赖图。对象身份是借用索引，原生 Arc 数据不拥有 VM 根。
 pub struct RenderCache {
+    // 场景对象身份到原生不可变几何的缓存；相机改变时仍有机会复用同一场景数据。
     scenes3d: HashMap<ObjectRef, Arc<crate::scene3d::Scene>>,
+    // 每个业务 Block 的视觉结果；这里只保存原生快照，不通过 ObjectRef 增加 VM 强引用。
     entries: HashMap<ObjectRef, Cached>,
+    // 读取源 -> 读取它的 Block。属性变动从这里找到首批需要重建的快照。
     dependents: HashMap<Dependency, HashSet<ObjectRef>>,
+    // 子 Block -> 所有父 Block。共享子组件改变后，所有引用该子项的父快照都需要更新。
     parents: HashMap<ObjectRef, HashSet<ObjectRef>>,
+    // 已失效但尚未重建的 Block 集合，同时用于传播去重。
     dirty: HashSet<ObjectRef>,
     pub last_invalidation: String,
     pub visited: usize,
@@ -45,11 +50,13 @@ impl RenderCache {
     /// 把 VM 变化映射到读取过这些属性/对象的视觉节点，再沿父链向上传播脏标记。
     pub fn invalidate(&mut self, batch: ChangeBatch) {
         let mut queue = VecDeque::new();
+        // 变更日志溢出后无法知道遗漏了哪些写入，保守地将已有快照全部失效。
         if batch.rescan_required {
             self.last_invalidation = "change journal overflow".into();
             queue.extend(self.entries.keys().copied());
         } else {
             for change in batch.changes {
+                // 属性变更使用精确名称，Contents 使用整个对象键；与提取时登记的依赖粒度一致。
                 let key = Dependency {
                     object: change.object,
                     property: match change.key {
@@ -70,6 +77,7 @@ impl RenderCache {
     pub fn invalidate_objects(&mut self, objects: impl IntoIterator<Item = ObjectRef>) {
         let mut queue: VecDeque<_> = objects.into_iter().collect();
         while let Some(block) = queue.pop_front() {
+            // 只有第一次加入 dirty 才继续向父链传播，避免共享祖先被反复展开。
             if self.dirty.insert(block)
                 && let Some(parents) = self.parents.get(&block)
             {
@@ -81,6 +89,7 @@ impl RenderCache {
     /// 撤销旧缓存的反向读取边和父子边，为重新登记该节点做准备。
     fn remove(&mut self, block: ObjectRef) -> Option<Cached> {
         let old = self.entries.remove(&block)?;
+        // 旧边必须先撤销，否则节点重建后仍会被已经不再读取的对象触发失效。
         for source in &old.dependencies {
             if let Some(owners) = self.dependents.get_mut(source) {
                 owners.remove(&block);
@@ -89,6 +98,7 @@ impl RenderCache {
                 }
             }
         }
+        // 只撤销当前 Block 对孩子的父边；其他共享父节点仍保留。空集合及时删除以缩小索引。
         for child in &old.children {
             if let Some(parents) = self.parents.get_mut(child) {
                 parents.remove(&block);
@@ -104,6 +114,7 @@ impl RenderCache {
     pub fn prune(&mut self, store: &ObjectStore) {
         self.scenes3d
             .retain(|object, _| store.object(*object).is_ok());
+        // 先收集死亡身份，再修改 entries 与反向索引，避免一边借用遍历一边删除。
         let dead: Vec<_> = self
             .entries
             .keys()
@@ -112,6 +123,7 @@ impl RenderCache {
             .collect();
         for block in dead {
             self.remove(block);
+            // 只有成功建立新条目后才清脏标记；前面任何校验失败都不会把节点错误标成干净。
             self.dirty.remove(&block);
         }
     }
@@ -124,6 +136,8 @@ impl RenderCache {
     ) -> Result<Arc<UiNode>, VmError> {
         self.visited = 0;
         self.reused = 0;
+        // 使用进入/退出两阶段的显式 DFS，避免深层组成消耗 Rust 调用栈。
+        // values 是后序结果栈：每个退出节点消费刚完成的孩子快照，再压入自己。
         let mut work = vec![(root, false)];
         let mut path = HashSet::new();
         let mut values = Vec::<Arc<UiNode>>::new();
@@ -137,11 +151,13 @@ impl RenderCache {
                     values.push(cached.node.clone());
                     continue;
                 }
+                // 计数的是本次实际展开次数；共享节点可复用缓存，脏图展开仍有 10000 次上限。
                 self.visited += 1;
                 if self.visited > 10_000 {
                     return Err(VmError::ExecutionLimit("expanded Block graph"));
                 }
             }
+            // 提取前验证实例存储与类型契约；resolve_tracked 同时提供数据以及经过的代理/存储依赖。
             store.check_typed_instance_storage(block)?;
             let (data_ref, raw_data, raw_dependencies) = block::resolve_tracked(store, block)?;
             let mut data = block::visual_data(store, raw_data)?;
@@ -152,6 +168,7 @@ impl RenderCache {
                     property: None,
                 })
                 .collect();
+            // 方法名称查找也构成依赖。即使属性数值未变，协议方法被替换也必须让快照失效。
             let storage = *store
                 .attribute_path(block)?
                 .last()
@@ -162,6 +179,7 @@ impl RenderCache {
                     property: Some(name),
                 });
             }
+            // 原生视觉属性按精确字段登记，避免不参与视觉的其他属性写入触发整个节点重建。
             if let Some(properties) = data.properties {
                 for (name, _) in block::native_properties(&data) {
                     dependencies.push(Dependency {
@@ -180,6 +198,7 @@ impl RenderCache {
                     });
                 }
             }
+            // 3D 面板把托管内容映射为子 Block，同时保留尺寸与稳定 slot，供后续布局和出现身份使用。
             let mut panel_sizes = Vec::new();
             let view3d = if matches!(data.kind, Kind::Viewport3D { .. }) {
                 let scene = data
@@ -223,6 +242,7 @@ impl RenderCache {
                 continue;
             }
             path.remove(&data_ref);
+            // 协议键包含类型身份、实际方法身份及其内容版本，供布局/绘制缓存识别实现变化。
             let mut protocol_key = String::new();
             let mut custom_event = false;
             if let Some(definition) = store.type_of(block)? {
@@ -237,6 +257,7 @@ impl RenderCache {
                         });
                     }
                 }
+                // 不仅记录最终方法，还沿基类链登记类型内容依赖，使继承关系或方法表变化能触发重建。
                 let event = store.lookup_method(definition, "onEvent")?;
                 let mut current = Some(definition);
                 while let Some(definition) = current {
@@ -254,6 +275,7 @@ impl RenderCache {
                     .transpose()?
                     .unwrap_or(false);
             }
+            // 订阅连接的取消会改变 handler；记录连接内容依赖，使交互资格能随取消及时更新。
             let mut click_connection = false;
             for connection in &data.subscriptions {
                 dependencies.push(Dependency {
@@ -264,9 +286,11 @@ impl RenderCache {
                     .payload::<crate::event_dispatch::Connection>(*connection, "Connection")?;
                 click_connection |= item.kind == "click" && item.handler.is_some();
             }
+            // 逆序压入孩子确保后序结果与 data.children 原顺序一致；只取尾部的本节点孩子，保留兄弟结果。
             let children = values.split_off(values.len() - data.children.len());
             let kind = match &data.kind {
                 Kind::Text { value, size, color } => {
+                    // 旧 textOf 路径按实际源字段提取字符串。属性路径中间对象用整对象依赖，末端用字段依赖。
                     let value = if let Some((source, field)) = &data.text_binding {
                         let storage = store.attribute_path(*source)?;
                         for (index, object) in storage.iter().enumerate() {
@@ -280,6 +304,7 @@ impl RenderCache {
                             Value::Bool(v) => v.to_string(),
                             Value::Number(v) => v.to_string(),
                             Value::Text(v) => v,
+                            // 对象字符串化可能依赖其内容，所以除属性本身外还记录被引用对象的内容变化。
                             Value::Object(v) => {
                                 dependencies.push(Dependency {
                                     object: v,
@@ -335,6 +360,7 @@ impl RenderCache {
                     )?,
                     children,
                 },
+                // 二维场景保留每个孩子的世界位置；普通行列容器则由布局决定孩子坐标。
                 Kind::Scene2D => UiKind::Scene2D {
                     positions: data
                         .children
@@ -382,6 +408,7 @@ impl RenderCache {
                     children,
                 },
             };
+            // 统一外层样式与交互标志。UiKind 只表示具体内容，UiNode 保存所有类别共享的视觉元信息。
             let next = UiNode {
                 surface: matches!(data.kind, Kind::Page).then(|| {
                     let mut surface = data.surface.clone();
@@ -408,12 +435,14 @@ impl RenderCache {
                     || custom_event,
                 kind,
             };
+            // 即使本次重算结果相同，也要重新登记依赖。shallow_eq 相同时复用旧 Arc，减少下游无效重建。
             let old = self.remove(block);
             let node = if let Some(old) = old.as_ref().filter(|old| old.node.shallow_eq(&next)) {
                 old.node.clone()
             } else {
                 Arc::new(next)
             };
+            // 同一属性可能由不同提取路径重复读取，排序去重后再建立反向边。
             dependencies.sort_unstable();
             dependencies.dedup();
             let child_refs: Vec<_> = data.children.iter().map(|child| child.block).collect();

src/model/window.rs

@@ -32,6 +32,7 @@ pub struct Command {
 impl Command {
     /// 判断两条命令是否针对同一资源的同类动作，用于替换尚未执行的旧请求。
     pub fn same_kind(&self, other: &Self) -> bool {
+        // 比较动作变体而不是参数值：同窗口多次 Resize/SetTitle 可合并为最后一次，不同动作仍按序保留。
         self.window == other.window
             && std::mem::discriminant(&self.action) == std::mem::discriminant(&other.action)
     }
@@ -46,14 +47,17 @@ pub struct Envelope {
 /// 托管窗口资源状态与页面拥有关系；本对象存在不等于 OS 窗口已创建。
 pub struct ManagedWindow {
     pub id: u64,
+    // 每窗口拥有独立 desktop、tabs 与页面顺序；同 VM 的类型注册表可共享，不复制业务模型。
     pub desktop: ObjectRef,
     pub closed: bool,
     pub tasks: Option<ObjectRef>,
     tabs: ObjectRef,
+    // 页面身份的有序强拥有集合，tabs 字典同时提供托管注册入口；移动顺序只调整此 Vec。
     pages: Vec<ObjectRef>,
     sequence: u64,
     // Transport state only. Draining it must not change a language object's
     // version or create a render-dependency feedback loop.
+    // 仅保存纯数据传输队列，克隆 payload 仍共享同一 outbox；drain 不触发 VM 内容版本，避免反馈循环。
     outbox: Arc<Mutex<Vec<Command>>>,
 }
 impl ObjectPayload for ManagedWindow {
@@ -94,6 +98,7 @@ fn screen_coordinate(value: &Value) -> Result<i32, VmError> {
     let Value::Number(value) = value else {
         return Err(invalid("screen position requires integer coordinates"));
     };
+    // 屏幕位置必须为整数，允许负坐标以覆盖多显示器；范围与 i32 转换均检查，不能把小数直接截断。
     value
         .as_i64()
         .filter(|number| (-1_000_000..=1_000_000).contains(number))
@@ -137,7 +142,7 @@ impl NativeCallable for Method {
     fn signature(&self) -> Option<endor_core::CallSignature> {
         Some(self.signature.clone())
     }
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 计入 Window 接收者：resize/moveTo 共三参，setTitle 两参，其他查询/关闭/聚焦只要接收者。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(match self.operation {
             Operation::Resize | Operation::MoveTo => 3,
@@ -146,7 +151,7 @@ impl NativeCallable for Method {
         }))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 验证窗口资源与关闭状态；查询返回托管值，原生变更生成受世代保护的待执行命令，关闭走资源生命周期。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let Some(Value::Object(owner)) = args.first() else {
             return Err(invalid("Window method requires a Window"));
@@ -155,6 +160,7 @@ impl NativeCallable for Method {
             .store()
             .payload::<ManagedWindow>(*owner, "Window")?
             .clone();
+        // 已关闭窗口仍可查询稳定 ID 与页面集合，其他读取/操作拒绝，避免用旧 viewport 或重开原生资源。
         if data.closed && !matches!(self.operation, Operation::Id | Operation::Pages) {
             return Err(invalid("native window is closed"));
         }
@@ -171,6 +177,7 @@ impl NativeCallable for Method {
             Operation::Pages => {
                 Value::Object(object_list::collection(cx, data.pages, self.desktop)?)
             }
+            // 读取该 Window 自己 desktop 的逻辑视口，封装成 MeasureResult；尚未由原生侧提供尺寸时明确失败。
             Operation::Viewport => {
                 let Value::Object(input) = cx.store().get_attr(data.desktop, "viewport")? else {
                     return Err(invalid("window viewport is unavailable"));
@@ -185,6 +192,7 @@ impl NativeCallable for Method {
                 )?)
             }
             operation => {
+                // 原生命令虽暂存在内存，也属于变更，不能从只读测量/绘制回调发起窗口操作。
                 if cx.store().is_read_only() {
                     return Err(invalid(
                         "window operations are forbidden during read-only rendering",
@@ -203,6 +211,7 @@ impl NativeCallable for Method {
                         let Value::Text(title) = &args[1] else {
                             return Err(invalid("window title requires text"));
                         };
+                        // 标题限制 UTF-8 字节长度并拒绝控制字符；不会在这里执行标题文本或展开 shell 字符。
                         if title.len() > 4096 || title.chars().any(char::is_control) {
                             return Err(invalid("invalid window title"));
                         }
@@ -228,6 +237,7 @@ pub fn enqueue(
         .store()
         .payload::<ManagedWindow>(owner, "Window")?
         .clone();
+    // 命令序列单调递增且检查溢出；同类合并会产生序号空洞，但仍可按序比较先后。
     data.sequence = data
         .sequence
         .checked_add(1)
@@ -242,7 +252,9 @@ pub fn enqueue(
         .lock()
         .map_err(|_| invalid("window outbox poisoned"))?;
     // The heap barrier succeeds before any external transport state changes.
+    // 必须先成功经过 VM 写屏障，才修改不可回滚的原生 outbox；只读调用不能先留下待发命令再报错。
     cx.replace_payload(owner, data)?;
+    // 同窗口同动作只保留最后请求，其他类别保持先后；此处只入队，GUI 是否执行取决于后续成功发布。
     queue.retain(|old| !old.same_kind(&command));
     queue.push(command);
     Ok(())
@@ -266,6 +278,7 @@ pub fn register_page(
     if data.closed {
         return Err(invalid("native window is closed"));
     }
+    // 登记幂等，首次同时写 tabs 与 payload；字典键使用页面身份文本而非标题，重命名不改变登记。
     if !data.pages.contains(&page) {
         data.pages.push(page);
         cx.dict_set(
@@ -292,6 +305,7 @@ pub fn unregister_page(
         .store()
         .payload::<ManagedWindow>(window, "Window")?
         .clone();
+    // 不存在时撤销是空操作；存在时同时删有序列表与 tabs 字典边，不能只隐藏原生标签。
     if !data.pages.contains(&page) {
         return Ok(());
     }
@@ -316,7 +330,7 @@ pub fn unregister_page_host(
     Ok(())
 }
 
-/// 在窗口之间移动页面的所有权和登记顺序，保留同一业务页面身份。
+/// 在同一窗口的已登记页面集合内重排标签位置，保留 Page 身份；不负责跨窗口迁移。
 pub fn move_page(
     cx: &mut NativeContext<'_>,
     window: ObjectRef,
@@ -343,6 +357,7 @@ pub fn move_page(
             "tab ordering is forbidden during read-only rendering",
         ));
     }
+    // 只重排当前窗口中的页面，不迁移到另一窗口，也不销毁或重建 Page/Mount；跨窗口迁移由桥接层组合操作。
     if from != position {
         let page = data.pages.remove(from);
         data.pages.insert(position, page);
@@ -361,6 +376,7 @@ pub fn take_commands(vm: &Vm, window: ObjectRef) -> Result<Vec<Command>, VmError
         .outbox
         .lock()
         .map_err(|_| invalid("window outbox poisoned"))?;
+    // 一次移走全部队列，再按序号排序；仅消费传输状态，不调用 replace_payload 或改变语言依赖版本。
     let mut commands = std::mem::take(&mut *queue);
     commands.sort_by_key(|command| command.sequence);
     Ok(commands)
@@ -417,6 +433,7 @@ pub fn install(
         vm.attach_type(function, function_type)?;
         vm.define_method(definition, name, function)?;
     }
+    // 安装主窗口托管资源，原生 OS 窗口生命周期仍由 GUI 管理；页面集合初始为空。
     let window = vm.allocate(ManagedWindow {
         id: MAIN_WINDOW,
         desktop,
@@ -430,6 +447,7 @@ pub fn install(
     roots.push(window);
     vm.attach_type(window, definition)?;
     vm.set_attr(desktop, "window", Value::Object(window))?;
+    // 主 desktop 拥有统一窗口注册表，以纯数字 ID 文本索引；注册表让附加窗口在 VM 图内可达。
     let windows = vm.new_dict()?;
     vm.set_attr(desktop, "windows", Value::Object(windows))?;
     vm.dict_set(
@@ -457,6 +475,7 @@ pub fn create(
     }
     let desktop = cx.new_object()?;
     let tabs = cx.new_dict()?;
+    // 附加桌面共享主域的同一 types 字典身份，保证跨窗口对象和协议使用同一名义类型体系。
     let types = cx.store().get_attr(master, "types")?;
     cx.set_attr(desktop, "types", types)?;
     cx.set_attr(desktop, "viewport", Value::Nil)?;
@@ -477,10 +496,11 @@ pub fn create(
         return Err(invalid("window registry missing"));
     };
     cx.dict_set(windows, Value::Text(id.to_string()), Value::Object(window))?;
+    // 返回创建的三个托管身份供桥接层建立 Presentation；此函数不直接申请 OS 资源或发起布局。
     Ok((window, desktop, tabs))
 }
 
-/// 发起窗口关闭和相应生命周期清理，拒绝重复或不再有效的操作。
+/// 取消窗口/页面任务并撤销登记，标记 closed 后安排原生关闭；重复关闭直接返回。
 pub fn close(cx: &mut NativeContext<'_>, window: ObjectRef) -> Result<(), VmError> {
     if cx.store().is_read_only() {
         return Err(invalid(
@@ -494,17 +514,20 @@ pub fn close(cx: &mut NativeContext<'_>, window: ObjectRef) -> Result<(), VmErro
     if data.closed {
         return Ok(());
     }
+    // 真实关闭边界先取消窗口与所有页面 owner 的任务，再撤销页面登记，防止晚到结果继续更新已关闭资源。
     crate::tasks::cancel_owner(cx, window)?;
     for page in data.pages.clone() {
         crate::tasks::cancel_owner(cx, page)?;
         unregister_page(cx, window, page)?;
     }
+    // 循环内 unregister_page 已替换过 Window payload，必须重读最新副本，不能用最初 data 把已移除页面写回。
     data = cx
         .store()
         .payload::<ManagedWindow>(window, "Window")?
         .clone();
     data.closed = true;
     cx.replace_payload(window, data)?;
+    // 标记托管 closed 后仍可由内部 enqueue 安排原生 Close；成功输入发布前不会直接关闭系统窗口。
     enqueue(cx, window, Action::Close)
 }
 
@@ -512,6 +535,7 @@ pub fn close(cx: &mut NativeContext<'_>, window: ObjectRef) -> Result<(), VmErro
 /// 撤销已失效窗口的托管资源关系，不重新执行源关闭请求。
 pub fn retire(vm: &mut Vm, window: ObjectRef) -> Result<(), VmError> {
     let mut data = vm.payload::<ManagedWindow>(window, "Window")?.clone();
+    // 故障域的宿主退役仅断开页面拥有边并标 closed，不跑用户回调、不重新生成源关闭命令。
     vm.dict_clear(data.tabs)?;
     data.pages.clear();
     data.closed = true;

src/render/box_model.rs

@@ -75,8 +75,10 @@ impl Default for Sizing {
 
 impl Sizing {
     /// Constrain descendants using the actual finite box before wrapping text.
-    /// 根据固定/auto/fill 与 min/max 规则细化父级提供的可用约束。
+    /// 将 [最小宽, 最小高, 最大宽, 最大高] 收窄，供子内容测量和文本换行使用。
+    /// 固定尺寸限制最大可用空间；最后缩小最小约束以保持 min <= max。这里不直接计算最终盒子。
     pub fn available(self, mut constraints: [f32; 4]) -> [f32; 4] {
+        // 先套自身 max，再应用 Fixed；Auto/Fill 在测量阶段保留父级允许的空间。
         constraints[2] = constraints[2].min(self.max_width);
         constraints[3] = constraints[3].min(self.max_height);
         if let Dimension::Fixed(width) = self.width {
@@ -100,10 +102,12 @@ impl Sizing {
             max: f32,
             available: f32,
         ) -> Result<f32> {
+            // 先按策略选候选值：Auto 用内容测量值，Fixed 用指定值，Fill 用父级分配上限。
             let value = match policy {
                 Dimension::Auto => intrinsic,
                 Dimension::Fixed(value) => value,
                 Dimension::Fill => {
+                    // MAX_DIMENSION 充当无界哨兵；无界空间没有可填满的有限尺寸，必须拒绝。
                     if available >= MAX_DIMENSION as f32 {
                         return Err(VmError::InvalidArgument(
                             "fill requires a finite parent allocation on this axis",
@@ -113,6 +117,7 @@ impl Sizing {
                     available
                 }
             };
+            // 先满足自身 min/max，再服从父级上限；父级空间比 min 小时，父级上限优先。
             Ok(value.clamp(min, max).min(available))
         }
         Ok(Size {

src/render/display_list.rs

@@ -38,30 +38,38 @@ impl Color {
 #[derive(Clone, Debug)]
 /// 原生画布最终顺序执行的绘制原语，已经使用对应设备比例。
 pub enum DrawCommand {
+    // 在 rect 内绘制不可变 3D 视图；平移/缩放改变视口矩形，不改写共享场景或相机。
     Scene3D {
         rect: Rect,
         view: std::sync::Arc<crate::scene3d::View>,
     },
+    // 清除整个目标缓冲；不携带几何，因此列表平移和缩放不会改变它。
     Clear(Color),
+    // 将矩形压入裁剪栈；后续命令受裁剪约束，必须由对应 PopClip 恢复。
     PushClip(Rect),
+    // 恢复上层裁剪。合并列表保持原顺序，调用方需保证裁剪栈配对。
     PopClip,
+    // 填充圆角矩形；半径与矩形尺寸在设备缩放时使用同一比例。
     FillRoundedRect {
         rect: Rect,
         radius: f32,
         color: Color,
     },
+    // 描边圆角矩形；描边宽度也是长度，必须随几何一起缩放。
     StrokeRoundedRect {
         rect: Rect,
         radius: f32,
         width: f32,
         color: Color,
     },
+    // 在有限矩形内进行文本布局；缩放同时作用于矩形和文字样式，保持换行比例。
     WrappedText {
         rect: Rect,
         value: String,
         style: TextStyle,
         color: Color,
     },
+    // 以原点定位文本，文本布局使用 TextStyle；与 WrappedText 不同，不额外携带有限文本框。
     Text {
         origin: Point,
         value: String,
@@ -73,6 +81,7 @@ pub enum DrawCommand {
 impl DrawCommand {
     /// 返回平移后的绘制命令，并同步移动命令中的相关几何。
     pub fn translated(mut self, delta: Point) -> Self {
+        // 平移只改变位置，保留尺寸、圆角、文字样式和颜色；消费 self 后返回修改后的命令。
         match &mut self {
             Self::WrappedText { rect, .. }
             | Self::Scene3D { rect, .. }
@@ -101,7 +110,9 @@ pub struct DisplayList {
 impl DisplayList {
     /// 按设备比例缩放命令，文字、边框和矩形不能分别使用不一致比例。
     pub fn scale(&mut self, scale: f32) {
+        // 原地累计缩放：重复调用会相乘，并非设置绝对缩放值。调用方负责提供有效设备比例。
         for command in &mut self.commands {
+            // 先处理各变体独有的长度（字体、圆角、描边），再把公共矩形交给下方统一缩放。
             let rect = match command {
                 DrawCommand::WrappedText { rect, style, .. } => {
                     *style = style.scaled(scale);
@@ -131,6 +142,7 @@ impl DisplayList {
                 }
                 _ => None,
             };
+            // 矩形的原点和宽高一起缩放，保证裁剪范围、文本框与实际绘制内容对齐。
             if let Some(rect) = rect {
                 rect.x *= scale;
                 rect.y *= scale;
@@ -145,6 +157,7 @@ impl DisplayList {
     }
 
     /// 平移当前显示列表中的命令，供整块页面或管理面板放入窗口坐标。
+    // 与单条 translated 相同，但直接修改整个列表；Clear/PopClip 没有位置需要移动。
     pub fn translate(&mut self, delta: Point) {
         for command in &mut self.commands {
             match command {
@@ -171,6 +184,7 @@ impl DisplayList {
     }
 
     /// 按原顺序合并另一组绘制命令，不在这里重排层次。
+    // 消费另一个列表并移动其命令，不复制字符串或场景数据，也不在连接处补裁剪指令。
     pub fn extend(&mut self, other: DisplayList) {
         self.commands.extend(other.commands);
     }

src/render/geometry.rs

@@ -8,7 +8,7 @@ pub struct Point {
 }
 
 impl Point {
-    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
+    /// 直接保存二维坐标；不缩放、不舍入，也不检查有限性，调用方负责坐标空间和输入校验。
     pub const fn new(x: f32, y: f32) -> Self {
         Self { x, y }
     }
@@ -24,7 +24,7 @@ pub struct Rect {
 }
 
 impl Rect {
-    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
+    /// 直接保存左上角和宽高；不归一化负尺寸，布局调用方需先产生合法边界。
     pub const fn new(x: f32, y: f32, width: f32, height: f32) -> Self {
         Self {
             x,
@@ -34,7 +34,7 @@ impl Rect {
         }
     }
 
-    /// 判断给定点是否位于目标范围；需要相机转换的类型会先转换再判断。
+    /// 用闭区间比较判断点是否命中，左右上下边缘都计入；调用前需将点转换到矩形所在空间。
     pub fn contains(self, point: Point) -> bool {
         point.x >= self.x
             && point.x <= self.x + self.width
@@ -48,7 +48,9 @@ mod tests {
     use super::*;
 
     #[test]
+    /// 矩形左上/右下边界均包含，刚越过左边界的点排除，固定基础命中边界策略。
     fn rectangle_contains_edges_but_not_outside_points() {
+        // 同时验证左上和右下边界被包含，以及仅越过左边界的小偏差也会被排除。
         let rect = Rect::new(10.0, 20.0, 30.0, 40.0);
         assert!(rect.contains(Point::new(10.0, 20.0)));
         assert!(rect.contains(Point::new(40.0, 60.0)));

src/render/layout.rs

@@ -79,6 +79,7 @@ impl CrossAlign {
 
     /// 根据交叉轴对齐方式计算有限剩余空间中的偏移。
     fn offset(self, available: f32, occupied: f32) -> f32 {
+        // 溢出时剩余空间归零，Center/End 都退化为起点对齐，避免把内容前缘移出可达滚动范围。
         let spare = (available - occupied).max(0.0);
         match self {
             Self::Start | Self::Stretch => 0.0,
@@ -125,9 +126,11 @@ impl MainAlign {
 #[derive(Debug, Clone, Copy, PartialEq)]
 /// 主轴伸缩策略与限值，不能用一个宽度常量替代完整分配规则。
 pub struct FlexPolicy {
+    // Some 指定主轴首选基准，None 使用首次内容测量；grow/fill 的缺省基准在 flex_sizes 中解释为零。
     pub basis: Option<f32>,
     pub min: f32,
     pub max: f32,
+    // 收缩权重还会乘 basis；默认零表示空间不足时不主动压缩该项。
     pub shrink: f32,
 }
 impl Default for FlexPolicy {
@@ -170,7 +173,9 @@ struct Key {
 #[derive(Debug, Clone, Default)]
 /// 布局缓存、稳定出现身份与统计。构建在临时副本上完成，成功后才写回。
 pub struct LayoutRuntime {
+    // 按 Block 身份只保留最后一份 Shape/Size；共享 Block 不同约束可交替覆盖，但每次复用前仍比较完整 Shape。
     sizes: HashMap<String, (Shape, Size)>,
+    // 出现身份取父 Mount、稳定 slot 和 Block 身份三元组，区别于仅按业务组件分配一个全局 ID。
     ids: HashMap<Key, u64>,
     next_id: u64,
     pub version: u64,
@@ -209,6 +214,7 @@ fn coordinate(value: f32) -> Result<f32> {
 
 /// 从页面模式和当前视口生成根节点约束；无视口时使用明确的无界轴哨兵。
 pub fn root_constraints(viewport: Option<Size>) -> [f32; 4] {
+    // 无视口时以 MAX_DIMENSION 作为无界哨兵；它是有限数值预算，但 Fill 必须另行要求真正有限分配。
     let size = viewport.unwrap_or(Size {
         width: MAX_DIMENSION as f32,
         height: MAX_DIMENSION as f32,
@@ -218,6 +224,7 @@ pub fn root_constraints(viewport: Option<Size>) -> [f32; 4] {
 
 /// 从父级上限扣除内边距；无界哨兵保持无界，不因减法被误认为有限。
 fn content_limit(available: f32, inset: f32) -> f32 {
+    // 不能直接从哨兵减 padding，否则略小于 MAX_DIMENSION 会被误认为有限空间，从而错误允许 Fill。
     if available >= MAX_DIMENSION as f32 {
         available
     } else {
@@ -227,6 +234,7 @@ fn content_limit(available: f32, inset: f32) -> f32 {
 /// 把父盒子的可用尺寸传递给子项，扣除容器内边距并考虑主轴是否可延伸。
 pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] {
     let parent = node.sizing.available(parent);
+    // Overlay 双轴都受内容盒上限约束；不像 Row/Column 在主轴自然展开。
     if let UiKind::Overlay { .. } = node.kind {
         let padding = insets(node);
         return [
@@ -240,6 +248,7 @@ pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] {
         node.kind,
         UiKind::Canvas { .. } | UiKind::Scene2D { .. } | UiKind::CanvasViewport { .. }
     ) {
+        // 世界 Canvas/Scene2D 与其观察视口不把屏幕尺寸传入世界布局，场景孩子用无界轴约束。
         return root_constraints(None);
     }
     if let UiKind::Scroll { width, height, .. } = node.kind {
@@ -249,6 +258,7 @@ pub fn child_constraints(node: &UiNode, parent: [f32; 4]) -> [f32; 4] {
             constrained(Size { width, height }, parent),
         );
     }
+    // Row 主轴 x 无界、交叉轴 y 有限；Column/Button/Scroll 的普通方向相反，具体滚动另有上方分支。
     match container(node) {
         Some((true, padding, _)) => [
             0.0,
@@ -272,6 +282,7 @@ pub fn margin_constraints(child: &UiNode, mut constraints: [f32; 4]) -> [f32; 4]
         .into_iter()
         .enumerate()
     {
+        // 仅对真正有限轴扣 margin，保持无界哨兵；最小约束同时收窄以维持 min<=max。
         if constraints[axis + 2] < MAX_DIMENSION as f32 {
             constraints[axis + 2] = (constraints[axis + 2] - margin).max(0.0);
             constraints[axis] = constraints[axis].min(constraints[axis + 2]);
@@ -290,6 +301,7 @@ pub fn occurrence_constraints(
     offer: Size,
     child_index: usize,
 ) -> [f32; 4] {
+    // 世界面板 UI 根必须精确按纹理分辨率布局，最小与最大相同，不让外层视口世界尺寸泄入纹理空间。
     if let UiKind::Viewport3D { panels, .. } = &parent.kind {
         let size = panels[child_index];
         return [size.width, size.height, size.width, size.height];
@@ -299,6 +311,7 @@ pub fn occurrence_constraints(
         (0, child.sizing.width, offer.width, inset.horizontal()),
         (1, child.sizing.height, offer.height, inset.vertical()),
     ] {
+        // Fill 若从父容器主轴得到无界 base，但父本轮 offer 有限，则用内容可用长度测量，后面再参与权重分配。
         if dimension == crate::box_model::Dimension::Fill
             && base[axis + 2] >= MAX_DIMENSION as f32
             && available < MAX_DIMENSION as f32
@@ -333,6 +346,7 @@ pub fn initial_child_constraints(
 /// including a source parent's allocation rather than only constructor size.
 /// 根据已分配父尺寸重新细化子项约束，使实际安排能够反向影响换行等测量。
 pub fn arranged_child_constraints(node: &UiNode, available: [f32; 4], bounds: Size) -> [f32; 4] {
+    // 滚动允许轴无界以容纳内容，禁用轴使用实际已安排的视口尺寸，文字才能按最终交叉轴宽度换行。
     if let UiKind::Scroll { axis, .. } = node.kind {
         let padding = insets(node);
         return [
@@ -364,6 +378,7 @@ pub fn constrained(size: Size, constraints: [f32; 4]) -> Size {
 /// Effective content inset, including borders, in border-box coordinates.
 /// 计算布局使用的有效内边距和边框占用，兼容旧的统一 padding。
 pub fn insets(node: &UiNode) -> Insets {
+    // 单边 padding 优先，其次兼容容器的统一 padding，最后再加 border；其他叶节点无统一 padding 默认值。
     let fallback = match node.kind {
         UiKind::Row { padding, .. }
         | UiKind::Column { padding, .. }
@@ -406,6 +421,7 @@ fn measure_shape(shape: &Shape) -> Result<Size> {
         Shape::Padded(shape, padding) => padding.outer(measure_shape(shape)?),
         Shape::Text(value, size, width) => {
             let style = TextStyle::ui(*size);
+            // 自然文字宽度与受限换行高度分别测量；布局宽度不超过可用宽度，高度反映完整段落行数。
             let intrinsic = text::measure(value, style);
             let wrapped = text::measure_wrapped(value, style, *width);
             Size {
@@ -418,6 +434,7 @@ fn measure_shape(shape: &Shape) -> Result<Size> {
             height: *height,
         },
         Shape::Container(row, padding, gap, children) => {
+            // 主轴相加、交叉轴取最大，再加对应 inset 与 n-1 个 gap；saturating_sub 保证零孩子不出现负间距。
             let along = children
                 .iter()
                 .map(|s| if *row { s.width } else { s.height })
@@ -461,6 +478,7 @@ fn shape(node: &UiNode, children: Vec<Size>, constraints: [f32; 4]) -> Result<Sh
     let shape = match &node.kind {
         UiKind::Overlay { .. } => {
             let padding = insets(node);
+            // Overlay 取含各自 margin 的子盒最大宽高，不把重叠项逐个相加。
             let size = children.into_iter().zip(node.children()).fold(
                 Size::default(),
                 |size, (child, node)| {
@@ -476,11 +494,13 @@ fn shape(node: &UiNode, children: Vec<Size>, constraints: [f32; 4]) -> Result<Sh
                 size.height + padding.vertical(),
             )
         }
+        // 独立场景视口按自己的有限盒测量，不因远方世界几何或面板内容大小扩展其布局分配。
         UiKind::CanvasViewport { width, height, .. } | UiKind::Viewport3D { width, height, .. } => {
             Shape::Rect(*width, *height)
         }
         UiKind::Canvas { positions, .. } | UiKind::Scene2D { positions, .. } => {
             let mut size = Size::default();
+            // 场景尺寸仅累计孩子右下端最大值；负方向内容不向左上平移整体，导航仍由相机负责。
             for (position, child) in positions.iter().zip(children) {
                 size.width = size.width.max(position[0] + child.width);
                 size.height = size.height.max(position[1] + child.height);
@@ -511,6 +531,7 @@ fn shape(node: &UiNode, children: Vec<Size>, constraints: [f32; 4]) -> Result<Sh
             Shape::Container(row, padding, gap, children)
         }
     };
+    // 只有非默认盒尺寸策略才包 Sized 并把约束加入键；文字等自身 Shape 已包含其实际影响测量的参数。
     Ok(if node.sizing == crate::box_model::Sizing::default() {
         shape
     } else {
@@ -530,12 +551,14 @@ pub fn measure_native(node: &UiNode, children: Vec<Size>, constraints: [f32; 4])
 pub struct Context {
     pub node: Option<std::sync::Arc<UiNode>>,
     pub children: Vec<Size>,
+    // 本轮首次测量的首选尺寸，不应被上轮 flex 实际分配覆盖，否则反复测量会改变伸缩基准。
     pub preferred: Vec<Size>,
     pub bounds: Option<[f32; 4]>,
 }
 
 /// 为单个原生节点按已分配几何生成内容命令；容器背景/边框与整树遍历由外层组织。
 pub fn paint_native(node: &UiNode, x: f32, y: f32, size: Size) -> Option<RenderCommand> {
+    // 文字内容盒需要减 inset 并带 wrap_bounds；Rect/Button 背景则画完整 border-box。
     let size_for_text = size;
     let inset = insets(node);
     match &node.kind {
@@ -580,6 +603,7 @@ pub fn paint_native(node: &UiNode, x: f32, y: f32, size: Size) -> Option<RenderC
 /// 从一个节点及其分配几何生成原生绘制命令，包括背景、边框与内容。
 pub fn paint_commands(node: &UiNode, x: f32, y: f32, size: Size) -> Vec<RenderCommand> {
     let mut commands: Vec<_> = paint_native(node, x, y, size).into_iter().collect();
+    // 边框按四个零圆角条分别追加，宽厚各自钳到盒大小；不使用单一 stroke_width 混淆不等厚四边。
     let border = node.border;
     for [x, y, width, height] in [
         [x, y, size.width, border.top.min(size.height)],
@@ -639,6 +663,7 @@ fn main_limits(child: &UiNode, row: bool) -> (f32, f32) {
 
 /// 按权重分配主轴剩余空间，尊重每项 min/max；达到上限的项退出后重新分配剩余量。
 pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[Size]) -> Vec<Size> {
+    // Overlay 各孩子独立填内容盒，不共享主轴剩余量；普通线性容器才做下方加权增长/收缩。
     if matches!(node.kind, UiKind::Overlay { .. }) {
         let inset = insets(node);
         return children
@@ -668,6 +693,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
     };
     let nodes = node.children();
     let mut output = children.to_vec();
+    // 先处理交叉轴 Stretch，仅 Auto 维度可拉伸；明确 Fixed 不因父对齐策略被改写。
     for (child, size) in nodes.iter().zip(&mut output) {
         if child.align_self.unwrap_or(node.cross_align) == CrossAlign::Stretch {
             let sizing = child.sizing;
@@ -682,9 +708,11 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
             }
         }
     }
+    // 无主轴伸缩需求时也可能已完成交叉轴拉伸，直接返回这份 output，不丢弃上面调整。
     if !nodes.iter().any(|child| child.has_flex()) {
         return output;
     }
+    // 可分配主轴空间先扣父 inset、每个孩子两侧 margin 和固定 gap；使用 f64 累计减小权重分配误差。
     let space = ((if row { bounds.width } else { bounds.height }) as f64
         - if row {
             padding.horizontal()
@@ -703,6 +731,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
             .sum::<f32>() as f64
         - gap as f64 * children.len().saturating_sub(1) as f64)
         .max(0.0);
+    // 显式 basis 优先；grow/fill 默认从零参与分配，其余用 preferred，不拿已经压缩后的 children 充当自然基准。
     let bases: Vec<f64> = nodes
         .iter()
         .zip(preferred)
@@ -726,8 +755,10 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
             basis.clamp(min as f64, max as f64)
         })
         .collect();
+    // 初始 basis 先钳 min/max，剩余正数为增长，负数为收缩；非参与项仍占据其合法基准尺寸。
     let free = space - sizes.iter().sum::<f64>();
     let growing = free > 0.0;
+    // 增长按 flex，主轴 Fill 且 flex=0 用权重1；收缩按 shrink×原 basis，保持大内容承担较多缩减。
     let weights: Vec<f64> = nodes
         .iter()
         .zip(&bases)
@@ -750,6 +781,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
             if growing { max as f64 } else { min as f64 }
         })
         .collect();
+    // 只让有正权重且未到 min/max 的项参与，每轮触顶/到底的项退出，剩余空间继续分给未饱和者。
     let mut active: Vec<usize> = (0..nodes.len())
         .filter(|&i| {
             weights[i] > 0.0
@@ -767,6 +799,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
         let mut saturated = false;
         for &i in &active {
             let capacity = (limits[i] - sizes[i]).abs();
+            // 本轮按同一 remaining 比例计算，再限制到该项剩余容量；不能为单项超配后再粗暴钳制丢掉剩余量。
             let amount = (remaining * weights[i] / total).min(capacity);
             sizes[i] += if growing { amount } else { -amount };
             spent += amount;
@@ -775,6 +808,7 @@ pub fn flex_sizes(node: &UiNode, bounds: Size, children: &[Size], preferred: &[S
         remaining = (remaining - spent).max(0.0);
         // Without saturation this round distributed all available space. Do not
         // spin on floating point residue; a saturated round freezes a child.
+        // 没有项饱和说明比例分配已完成，微小浮点残差不能导致无进展死循环。
         if !saturated {
             break;
         }
@@ -804,6 +838,7 @@ pub fn arrange_native(
     bounds: Size,
     children: &[Size],
 ) -> Result<Vec<(f32, f32)>> {
+    // 3D 面板根在各自纹理空间均从 (0,0) 开始，世界摆放交由 Panel world 矩阵，不把世界坐标写入普通 UI 布局。
     if matches!(node.kind, UiKind::Viewport3D { .. }) {
         return Ok(node.children().iter().map(|_| (0., 0.)).collect());
     }
@@ -881,6 +916,7 @@ pub fn arrange_native(
         MainAlign::End => spare,
         _ => 0.0,
     };
+    // space-between 只在至少两个孩子间分配额外剩余量，原固定 gap 仍保留；单项保持 start。
     let distributed_gap = if node.main_align == MainAlign::SpaceBetween && children.len() > 1 {
         spare / (children.len() - 1) as f32
     } else {
@@ -920,6 +956,7 @@ pub fn arrange_native(
         coordinate(point.0 + child.width)?;
         coordinate(point.1 + child.height)?;
         points.push(point);
+        // 主轴游标推进当前盒尺寸、两侧 margin、固定及额外 gap；交叉轴对齐不改变主轴顺序。
         cursor += if row { child.width } else { child.height };
         cursor += if row {
             margin.horizontal()
@@ -954,6 +991,7 @@ impl LayoutRuntime {
 
     /// 清空结构出现身份表；业务对象和源状态不因此被复制。
     pub fn clear_occurrences(&mut self) {
+        // 清出现映射不重置 next_id，高水位继续增加，避免旧事件与新出现数值身份意外重合。
         self.ids.clear();
     }
     /// 在临时 LayoutRuntime 中生成完整几何，成功后才替换现有缓存和身份状态。
@@ -982,6 +1020,7 @@ impl LayoutRuntime {
         children: Vec<Size>,
         constraints: [f32; 4],
     ) -> Result<Size> {
+        // 缓存只有完整 Shape 相等才复用，纯颜色变化不在测量 Shape 中，因此无需重做尺寸求解。
         let shape = shape(node, children, constraints)?;
         if let Some((_, size)) = self
             .sizes
@@ -1003,12 +1042,14 @@ impl LayoutRuntime {
         self.settle_passes = usize::from(!structural);
         self.slices = usize::from(!structural);
         let mut items = Vec::<Item<'_>>::new();
+        // 用显式栈构建父先子后 items，根采用 slot0/无父；孩子逆序入栈保持原始布局顺序。
         let mut work = vec![(root, None::<usize>, 0, self.root_constraints())];
         let mut used = HashSet::new();
         while let Some((node, parent, slot, constraints)) = work.pop() {
             if items.len() >= MAX_LAYOUT_VISITS {
                 bail!("expanded UI layout exceeds 10000 nodes");
             }
+            // slot 与孩子必须一一对应，否则稳定出现身份不可信，不能用 zip 静默丢掉多余项。
             if node.slots.len() != node.children().len() {
                 bail!("invalid child slot table");
             }
@@ -1017,6 +1058,7 @@ impl LayoutRuntime {
                 slot,
                 block: node.block_id.clone(),
             };
+            // 结构三元组未变则复用 ID，新出现 checked_add 分配；只在成功构建副本后才提交整表。
             let id = if let Some(id) = self.ids.get(&key) {
                 *id
             } else {
@@ -1027,6 +1069,7 @@ impl LayoutRuntime {
                 self.ids.insert(key.clone(), self.next_id);
                 self.next_id
             };
+            // 同一展示出现键不得重复；共享组件在不同父或不同 slot 下使用不同 key，仍允许多次出现。
             if !used.insert(key) {
                 bail!("duplicate child slot in one presentation");
             }
@@ -1054,6 +1097,7 @@ impl LayoutRuntime {
         }
         let mut sizes = vec![Size::default(); items.len()];
         if !structural {
+            // 反向 items 自底向上测量，孩子尺寸已经求出；structural=true 完全跳过此步骤，零几何仅用于挂载准备。
             for (index, item) in items.iter().enumerate().rev() {
                 sizes[index] = constrained(
                     self.measure_node(
@@ -1069,6 +1113,7 @@ impl LayoutRuntime {
         let mut mounts = Vec::with_capacity(items.len());
         let mut commands = Vec::new();
         let mut siblings = vec![None; items.len()];
+        // 先按每个父的孩子顺序建立 next_sibling，最后一个默认 None；这与业务孩子列表身份不同。
         for item in &items {
             for pair in item.children.windows(2) {
                 siblings[pair[0]] = Some(items[pair[1]].id);
@@ -1112,6 +1157,7 @@ impl LayoutRuntime {
                 continue;
             }
             let child_sizes: Vec<_> = item.children.iter().map(|child| sizes[*child]).collect();
+            // 自顶向下用父实际尺寸更新孩子分配后再求原点；更复杂的源协议反复求解由 source_layout 驱动。
             let child_sizes = flex_sizes(item.node, size, &child_sizes, &child_sizes);
             for (child, allocated) in item.children.iter().zip(&child_sizes) {
                 sizes[*child] = *allocated;
@@ -1125,6 +1171,7 @@ impl LayoutRuntime {
                 points[*child] = point;
             }
         }
+        // 成功求解后丢弃已消失出现和不在本树的测量缓存，避免历史页面不断积累派生条目。
         self.ids.retain(|key, _| used.contains(key));
         let blocks: HashSet<_> = items
             .iter()
@@ -1132,6 +1179,7 @@ impl LayoutRuntime {
             .collect();
         self.sizes
             .retain(|block, _| blocks.contains(block.as_str()));
+        // 每次结构/完整构建成功都推进版本，禁止溢出复用；该版本用于后续 Mount/输入归属校验。
         self.version = self
             .version
             .checked_add(1)

src/render/mod.rs

@@ -1,18 +1,33 @@
 //! 渲染模块入口。排版、源视觉协议、相机投影和最终光栅化各自独立，通过不可变帧衔接。
 //!
-// Module ownership follows the directory; crate-root aliases keep internal call sites stable.
+// 目录确定模块归属；main 中的 crate 根别名保持内部调用路径稳定。
+/// 计算边框、内外边距和内容区域，并应用容器主轴/交叉轴分配规则。
 pub(crate) mod box_model;
+/// 表达与转换绘图命令，集中处理显示列表裁剪和坐标变换。
 pub(crate) mod display_list;
+/// 提供点、矩形等基础几何运算，供布局、命中和绘制共享。
 pub(crate) mod geometry;
+/// 实现原生布局求解、约束分配及可重用的尺寸/几何数据结构。
 pub(crate) mod layout;
+/// 适配原生视觉方法的测量、排列与绘制行为，供语言桥接和纯布局流程使用。
 pub(crate) mod native_visual;
+/// 描述整页表面模式、平移缩放和视口到世界坐标转换。
 pub(crate) mod page;
+/// 组合页面、侧栏和开发工具的整窗显示列表，并返回宿主输入所需布局。
 pub(crate) mod scene;
+/// 完成三维投影、射线拾取、裁剪与软件深度光栅化；子模块拆分数学、空间索引和世界 UI 面板。
 pub(crate) mod scene3d;
+/// 计算每个出现位置的滚动范围、裁剪和滚轮目标，嵌套滚动按可消费方向选择。
 pub(crate) mod scroll;
+/// 将完整显示列表写入像素缓冲；处理二维命令以及嵌套场景表面的最终合成。
 pub(crate) mod software_renderer;
+/// 在受控只读上下文调用源 hitTest，结合出现位置与可见性判断输入目标。
 pub(crate) mod source_hit;
+/// 用可恢复 VM 调用执行源 measure/arrange，追踪读依赖并迭代到几何稳定后产出草稿。
 pub(crate) mod source_layout;
+/// 分片执行源 paint 并验证/解码返回命令；未完成的绘制不能当作完整帧发布。
 pub(crate) mod source_paint;
+/// 使用系统字体塑形、换行和字形缓存，统一测量与像素绘制的文字尺寸。
 pub(crate) mod text;
+/// 处理二维场景相机、局部视口投影和空间查询，供绘制与命中使用相同变换。
 pub(crate) mod viewport;

src/render/native_visual.rs

@@ -41,6 +41,7 @@ pub(crate) fn number(
         .to_string()
         .parse::<f32>()
         .map_err(|_| invalid("invalid visual number"))?;
+    // 所有协议数值须有限且位于世界尺寸预算内；signed 区分坐标（可负）与长度/约束（非负）。
     if !value.is_finite() || value.abs() > MAX_DIMENSION as f32 || (!signed && value < 0.0) {
         return Err(invalid("visual number exceeds bounds"));
     }
@@ -48,6 +49,7 @@ pub(crate) fn number(
 }
 /// 将原生布局计算结果封装为协议需要的托管 Value。
 pub(crate) fn value(value: f32) -> Value {
+    // 原生 f32 提升到 f64 包装为 Endor Number；本函数不单独校验，调用路径必须已保证输入合法。
     Value::Number((value as f64).into())
 }
 /// 新建指定名义类型的托管记录，并逐项设置字段，作为视觉协议的结果返回。
@@ -57,6 +59,7 @@ pub(crate) fn record(
     kind: &str,
     fields: Vec<(&str, Value)>,
 ) -> Result<ObjectRef, VmError> {
+    // 先赋精确名义类型，再初始化字段；只读协议可创建结果对象，但不能借机写入旧业务图。
     let object = cx.new_object()?;
     attach_desktop_type(cx, object, kind, desktop)?;
     for (key, value) in fields {
@@ -64,8 +67,9 @@ pub(crate) fn record(
     }
     Ok(object)
 }
-/// 在约束提供的视口内执行原生布局，从根出现提取宽高，再按协议约束限制结果。
+/// 以最大宽高作视口执行原生布局并提取根尺寸；最小/最大最终钳制由 Measure 分支负责。
 fn size(node: &crate::ui_bridge::UiNode, constraints: [f32; 4]) -> Result<Size, VmError> {
+    // 无 staged 子测量结果时，使用有限最大约束运行原生布局取得根尺寸；最终 min/max 钳制在调用方 Measure 分支。
     let frame = layout::frame_with_viewport(
         node,
         Size {
@@ -106,6 +110,7 @@ pub(crate) fn is_intrinsic(
     name: &str,
     desktop: ObjectRef,
 ) -> Result<bool, VmError> {
+    // 快速路径仅认可实际 ContextNativeFunction 的 Method 实现，函数名相同或签名相似的源函数不能冒充。
     let Some(function) = store
         .object(function)?
         .payload()
@@ -118,6 +123,7 @@ pub(crate) fn is_intrinsic(
         return Ok(false);
     };
     // Per-window desktops share the same nominal registry and intrinsic bodies.
+    // 同一 VM 不同窗口 desktop 可共享 types 字典，所以以注册表身份允许复用原生方法体。
     let same_registry = method.desktop == desktop
         || matches!(
             (store.get_attr(method.desktop, "types")?, store.get_attr(desktop, "types")?),
@@ -138,24 +144,27 @@ impl NativeCallable for Method {
     fn signature(&self) -> Option<CallSignature> {
         Some(self.signature.clone())
     }
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 接收三项底层参数：Block 接收者、具体 Mount、Constraints/Bounds/Point 协议输入。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(3))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 检查 Block/Mount 归属与有效性，再按 measure/arrange/paint/hitTest 执行原生视觉协议并返回受检查的托管值。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
+        // 三个实际参数含接收者 Block、具体 Mount 和协议输入；几何属于 Mount，不能仅凭 Block 身份查询。
         let [owner, context, input] = args else {
             return Err(invalid("visual method expects a Mount and an input value"));
         };
         let owner = object(owner)?;
         let mount = cx.store().payload::<Mount>(object(context)?, "Mount")?;
+        // 默认协议也校验上下文归属，防止调用者把另一个出现的几何套到当前组件。
         if !mount.mounted || mount.block != owner {
             return Err(invalid(
                 "visual context is detached or belongs to another Block",
             ));
         }
         let geometry = mount.geometry.clone();
+        // 布局阶段从临时 Context 取当前节点、孩子实测尺寸与首选尺寸；克隆派生数据后释放锁再进行计算。
         let staged = mount
             .layout
             .as_ref()
@@ -171,6 +180,7 @@ impl NativeCallable for Method {
             })
             .transpose()?;
         let input = object(input)?;
+        // 默认 hitTest 检查局部点在已提交盒内，采用左上包含、右下排除；布局阶段几何不稳定，禁止调用。
         if matches!(self.query, Query::HitTest) {
             if staged.is_some() {
                 return Err(invalid("hitTest is unavailable during layout"));
@@ -181,11 +191,13 @@ impl NativeCallable for Method {
                 x >= 0.0 && y >= 0.0 && x < geometry.width && y < geometry.height,
             )));
         }
+        // 存在布局 Context 但尚无当前节点，说明准备顺序不完整，不能回退读取旧快照伪装成当前数据。
         if matches!(&staged, Some((None, _, _))) {
             return Err(invalid(
                 "layout context is not prepared for this occurrence",
             ));
         }
+        // 准备好则复用本轮不可变节点，非 staged 调用才从托管 Block 提取视觉快照。
         let node = if let Some((Some(node), _, _)) = &staged {
             node.clone()
         } else {
@@ -197,9 +209,11 @@ impl NativeCallable for Method {
                 let min_h = number(cx, input, "minHeight", false)?;
                 let max_w = number(cx, input, "maxWidth", false)?;
                 let max_h = number(cx, input, "maxHeight", false)?;
+                // 最小值不可超过最大值，否则后面的 clamp 会无意义甚至失败；各数值已通过非负有限检查。
                 if min_w > max_w || min_h > max_h {
                     return Err(invalid("minimum exceeds maximum constraint"));
                 }
+                // 混合源/原生布局使用已经测好的子尺寸，避免重复执行子树；独立调用则走完整原生测量。
                 let size = if let Some((_, children, _)) = &staged {
                     layout::measure_native(&node, children.clone(), [min_w, min_h, max_w, max_h])
                         .map_err(|_| invalid("native measurement exceeds layout limits"))?
@@ -211,6 +225,7 @@ impl NativeCallable for Method {
                     self.desktop,
                     "MeasureResult",
                     vec![
+                        // MeasureResult 最终明确落在传入 min/max 内，原生内容自然大小不能突破源协议约束。
                         ("width", value(size.width.clamp(min_w, max_w))),
                         ("height", value(size.height.clamp(min_h, max_h))),
                     ],
@@ -224,6 +239,7 @@ impl NativeCallable for Method {
                 if x + width > MAX_DIMENSION as f32 || y + height > MAX_DIMENSION as f32 {
                     return Err(invalid("visual bounds exceed limits"));
                 }
+                // Arrange 优先使用本轮子测量；没有 staged 时按孩子的实际分配约束逐个测量后再安排。
                 let children = if let Some((_, children, _)) = &staged {
                     children.clone()
                 } else {
@@ -248,16 +264,19 @@ impl NativeCallable for Method {
                         })
                         .collect::<Result<Vec<_>, _>>()?
                 };
+                // preferred 保留弹性分配所需首选大小，与已受约束的实测 children 区分；无 staged 时两者相同。
                 let preferred = staged
                     .as_ref()
                     .map_or(children.as_slice(), |(_, _, preferred)| {
                         preferred.as_slice()
                     });
+                // 先依据父盒分配 flex 尺寸，再由 arrange_native 求位置，避免先定位再改变孩子大小导致重叠。
                 let children =
                     layout::flex_sizes(&node, Size { width, height }, &children, preferred);
                 let points = layout::arrange_native(&node, x, y, Size { width, height }, &children)
                     .map_err(|_| invalid("native arrangement exceeds limits"))?;
                 let mut result = Vec::new();
+                // 每个返回 Bounds 附稳定 slot，与 children 当前顺序分开；调用方可按 slot 校验组成身份。
                 for ((slot, size), (x, y)) in node.slots.iter().zip(children).zip(points) {
                     let bounds = record(
                         cx,
@@ -273,6 +292,7 @@ impl NativeCallable for Method {
                     cx.set_attr(bounds, "slot", Value::Number((*slot as i64).into()))?;
                     result.push(bounds);
                 }
+                // Arrangement 返回受控 ObjectList，不返回宿主 Vec 或任意形状的源对象集合。
                 let result = crate::object_list::collection(cx, result, self.desktop)?;
                 Value::Object(record(
                     cx,
@@ -290,6 +310,7 @@ impl NativeCallable for Method {
                     return Err(invalid("visual bounds exceed limits"));
                 }
                 let mut commands = Vec::new();
+                // 将 Rust 默认绘制命令反向编码成源 PaintCommand，允许源覆盖方法调用基类 paint 后继续组合。
                 for command in layout::paint_commands(&node, x, y, Size { width, height }) {
                     let fields = match command {
                         RenderCommand::Scene3D {
@@ -299,6 +320,7 @@ impl NativeCallable for Method {
                             height,
                             view,
                         } => {
+                            // 3D 通过不可变 PaintView payload 暴露场景快照，不把运行中 VM 的场景对象交给后续绘制线程。
                             let snapshot = cx.allocate(crate::scene3d::PaintView(view))?;
                             vec![
                                 ("kind", Value::Text("scene3d".into())),
@@ -325,6 +347,7 @@ impl NativeCallable for Method {
                                 ("size", Value::Number((size as i64).into())),
                                 ("color", Value::Text(color)),
                             ];
+                            // 可选文本换行边界成对写入；缺省时两个字段都不创建，与源 paint 解码契约保持一致。
                             if let Some([width, height]) = wrap_bounds {
                                 fields.push(("wrapWidth", value(width)));
                                 fields.push(("wrapHeight", value(height)));
@@ -347,6 +370,7 @@ impl NativeCallable for Method {
                             ("radius", value(radius)),
                             ("color", Value::Text(color)),
                         ],
+                        // 当前反向编码支持明确列出的命令；新增 RenderCommand 变体时须同步此转换，不能静默丢弃。
                         _ => return Err(invalid("unsupported native paint command")),
                     };
                     let command = record(cx, self.desktop, "PaintCommand", fields)?;
@@ -378,7 +402,7 @@ impl NativeCallable for PointMethod {
     fn signature(&self) -> Option<CallSignature> {
         Some(self.signature.clone())
     }
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 圆形测试接收 Point 加圆心/半径共四项；矩形测试接收 Point 和 Bounds 共两项。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(if self.circle {
             4
@@ -387,11 +411,12 @@ impl NativeCallable for PointMethod {
         }))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 先验证 Point 名义类型与有限坐标，再分别计算圆内距离或 Bounds 包含关系，返回 Bool。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let Some(Value::Object(point)) = args.first() else {
             return Err(invalid("Point method requires a Point"));
         };
+        // Point 辅助方法验证名义接收者，不能只要有 x/y 字段就接受普通对象。
         if !cx.store().is_instance(*point, self.expected)? {
             return Err(invalid("Point method requires a Point"));
         }
@@ -407,6 +432,7 @@ impl NativeCallable for PointMethod {
             else {
                 return Err(invalid("inCircle requires center x/y and radius"));
             };
+            // 圆心和半径按 f64 解析及求平方距离，在有界数值内避免不必要的 f32 精度损失。
             let parse = |value: &endor_core::EndorNumber| -> Result<f64, VmError> {
                 let value = value
                     .to_string()
@@ -420,6 +446,7 @@ impl NativeCallable for PointMethod {
             let dx = x as f64 - parse(cx_value)?;
             let dy = y as f64 - parse(cy_value)?;
             let radius = parse(radius)?;
+            // 半径不能负；零半径只包含圆心，边界使用 <= 因此圆周也命中。
             if radius < 0.0 {
                 return Err(invalid("circle radius must be nonnegative"));
             }
@@ -432,6 +459,7 @@ impl NativeCallable for PointMethod {
             let top = number(cx, *bounds, "y", true)?;
             let width = number(cx, *bounds, "width", false)?;
             let height = number(cx, *bounds, "height", false)?;
+            // 矩形辅助同样使用半开右/下边界；这与 geometry::Rect 的闭区间 contains 不同，调用方应留意语义。
             x >= left && y >= top && x < left + width && y < top + height
         };
         Ok(NativeResult::Return(Value::Bool(inside)))
@@ -457,6 +485,7 @@ pub fn install(
     let measure = nominal("MeasureResult")?;
     let arrangement = nominal("Arrangement")?;
     let display = nominal("DisplayList")?;
+    // 把四个默认方法安装到 Block，源子类可覆盖；所有视觉协议声明 ReadOnly，允许派生结果分配而不修改模型。
     for (name, query, input, returns) in [
         ("measure", Query::Measure, constraints, measure),
         ("arrange", Query::Arrange, bounds, arrangement),
@@ -485,6 +514,7 @@ pub fn install(
         &vm.dict_get(registry, &Value::Text("Point".into()))?
             .ok_or(invalid("missing Point type"))?,
     )?;
+    // Point.inside 接收 Bounds，inCircle 接收圆心 x/y 和半径；签名都包含隐式 Point receiver。
     for (name, circle) in [("inside", false), ("inCircle", true)] {
         let function = vm.allocate(ContextNativeFunction::new(
             name,

src/render/page.rs

@@ -12,9 +12,13 @@ use serde::{Deserialize, Serialize};
 /// 旧 Page 的有限或自由空间模式，新场景视口不依赖它表达布局方向。
 pub enum Mode {
     #[default]
+    // 双轴被原生视口限制；兼容相机固定在原点且比例为 1。
     Window,
+    // 宽度固定，高度允许展开到布局上限，只沿 y 方向导航。
     Vertical,
+    // 高度固定，宽度允许展开到布局上限，只沿 x 方向导航。
     Horizontal,
+    // 双轴自由布局并允许平移缩放；相机不按内容边缘钳制。
     Canvas,
 }
 
@@ -44,10 +48,12 @@ impl Mode {
 
     /// 为旧页面模式生成有限轴和可延伸轴的根约束。
     pub fn constraints(self, viewport: Option<Size>) -> [f32; 4] {
+        // 未收到原生视口尺寸时采用布局默认根约束；不能凭空建立固定宽高。
         let Some(size) = viewport else {
             return crate::layout::root_constraints(None);
         };
         let limit = crate::ui_bridge::MAX_DIMENSION as f32;
+        // 数组采用 [最小宽, 最小高, 最大宽, 最大高]；竖/横页面仍至少占满当前视口。
         match self {
             Self::Window => [size.width, size.height, size.width, size.height],
             Self::Vertical => [size.width, size.height, size.width, limit],
@@ -61,10 +67,13 @@ impl Mode {
 /// 页面级兼容相机状态和有限内容范围，支持绘制与命中正逆变换。
 pub struct Surface {
     pub mode: Mode,
+    // 发布给原生侧的页面身份文本，不是托管强引用。
     pub page: String,
+    // 视图左上角对应的世界坐标；绘制时先减 pan 再乘 zoom。
     pub pan: Point,
     #[serde(default = "unit")]
     pub zoom: f32,
+    // 布局产出的内容宽高，用于有限模式钳制；不决定 Canvas 的导航边界。
     pub extent: Size,
 }
 
@@ -87,7 +96,7 @@ impl Default for Surface {
 }
 
 impl Surface {
-    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
+    /// 指定页面模式并显式使用单位缩放，其他字段采用空页面默认值；无需分配 VM 或原生窗口资源。
     pub fn new(mode: Mode) -> Self {
         Self {
             mode,
@@ -97,6 +106,7 @@ impl Surface {
     }
 
     /// 把页面视图坐标反算为旧 Page 相机下的世界坐标。
+    // 输入在视图空间，先除缩放再加世界偏移；调用方需保证 zoom 有限且大于零。
     pub fn to_world(&self, point: Point) -> Point {
         Point::new(
             point.x / self.zoom + self.pan.x,
@@ -105,6 +115,7 @@ impl Surface {
     }
 
     /// 把旧页面世界坐标变换到可见视图坐标。
+    // 输入在世界空间，先减相机偏移再缩放，恰与 to_world 互逆。
     pub fn to_view(&self, point: Point) -> Point {
         Point::new(
             (point.x - self.pan.x) * self.zoom,
@@ -114,6 +125,8 @@ impl Surface {
 
     /// 判断给定点是否位于目标范围；需要相机转换的类型会先转换再判断。
     pub fn contains(&self, point: [f32; 2], viewport: Option<Size>) -> bool {
+        // 传入的数组是世界坐标。转换后使用左/上包含、右/下排除的视口边界；
+        // 未知视口时仍排除负坐标，但不限制右/下界。
         let point = self.to_view(Point::new(point[0], point[1]));
         point.x >= 0.0
             && point.y >= 0.0
@@ -122,6 +135,8 @@ impl Surface {
 
     /// 只对有限页面按实际内容范围钳制偏移；自由画布不按内容边缘停止导航。
     pub fn clamp(&mut self, viewport: Size) {
+        // Window 重置所有导航；单轴模式清除另一轴并恢复单位缩放。
+        // 内容小于视口时 max(0) 令可滚动范围归零，避免 clamp 出现反向上下限。
         match self.mode {
             Mode::Window => {
                 self.pan = Point::default();
@@ -153,7 +168,9 @@ mod tests {
     use super::*;
 
     #[test]
+    /// 检查页面相机的往返变换，缩放时反求 pan 使指针下世界点固定，并按视口验证世界点可见性。
     fn camera_inverse_and_cursor_anchored_zoom_preserve_world_position() {
+        // 先验证相机正逆变换，再改变 zoom 并反求 pan，保证指针下的世界点不发生漂移。
         let mut view = Surface::new(Mode::Canvas);
         view.pan = Point::new(-240.0, 120.0);
         view.zoom = 0.75;
@@ -183,7 +200,9 @@ mod tests {
     }
 
     #[test]
+    /// 纵向页面将过大偏移夹到内容减视口范围；内容缩短到视口以内后偏移必须归零，横向偏移也禁用。
     fn finite_pages_clamp_after_content_shrinks() {
+        // 先将 900 的旧偏移钳到 800-600=200，再缩短内容至视口以内，确认偏移回零。
         let mut view = Surface::new(Mode::Vertical);
         view.pan = Point::new(25.0, 900.0);
         view.extent = Size {

src/render/scene.rs

@@ -25,6 +25,7 @@ pub fn build_scene(
     activity: &Activity,
     sidebar: &mut crate::sidebar::State,
 ) -> DisplayScene {
+    // 活动标签的 developer_tool 标记决定管理页类型，不靠当前窗口标题猜测；同步工具状态后再合成。
     let tool = document
         .frame
         .tabs
@@ -35,23 +36,28 @@ pub fn build_scene(
     developer_tools_state.document_updated(document);
     let left = sidebar.left();
     let surface = &document.frame.surface;
+    // width/height 为设备像素，sidebar.left 为逻辑单位，先乘 scale 得到页面可用裁剪区域。
     let content = Rect::new(
         left * scale,
         0.0,
         (width as f32 - left * scale).max(0.0),
         height as f32,
     );
+    // 管理页使用单位页面缩放，避免业务 Page 相机改变宿主工具字号；普通页叠加旧 Surface zoom。
     let zoom = if tool.is_some() { 1.0 } else { surface.zoom };
+    // 显示列表转换失败时降级为空默认文档；这只保护原生绘制，不把无效命令伪装成成功执行。
     let mut page = document.display_list(scale * zoom).unwrap_or_else(|_| {
         RenderDocument::default()
             .display_list(scale)
             .expect("default document is valid")
     });
+    // 页面显示列表先已乘设备比例/zoom，再加入侧栏偏移和世界 pan 的设备像素平移，保持缩放顺序一致。
     page.translate(Point::new(
         (left - surface.pan.x * zoom) * scale,
         -surface.pan.y * zoom * scale,
     ));
     let mut display_list = DisplayList::default();
+    // 全窗只做一次 Clear，后续跳过页面列表自身 Clear，防止其覆盖侧栏或突破页面裁剪。
     display_list.push(DrawCommand::Clear(
         crate::document::parse_color(&document.frame.background)
             .unwrap_or(crate::system_ui::theme::BG),
@@ -71,9 +77,11 @@ pub fn build_scene(
         developer_tools_state,
         activity,
     );
+    // 工具命令在设备空间平移，交互布局在逻辑空间平移，两者比例不同但实际对齐同一页面起点。
     developer_list.translate(Point::new(left * scale, 0.0));
     developer_layout.translate(left, 0.0);
     display_list.extend(developer_list);
+    // 侧栏最后覆盖合成，内部按逻辑尺寸绘制后统一设备缩放，不受页面相机影响。
     let mut chrome = sidebar.draw(
         &document.frame.tabs,
         height as f32 / scale,

src/render/scene3d.rs

@@ -23,8 +23,10 @@ pub struct Geometry {
     pub uv: Vec<[f32; 2]>,
 }
 impl Geometry {
-    /// 检查数值、几何和资源条件是否满足本类型约束，供上层拒绝非法输入。
+    /// 检查顶点与三角数量、索引范围、坐标有效性及逐顶点 UV；允许缺省 UV，不在此限制 UV 到单位区间。
     pub fn valid(&self) -> bool {
+        // 检查顶点/三角形资源量和所有索引范围；UV 可省略，否则必须逐顶点对应且每个分量有限。
+        // 不在这里强制 UV 位于 [0,1]，纹理采样阶段再钳制。
         self.vertices.len() <= MAX_VERTICES
             && (self.uv.is_empty()
                 || self.uv.len() == self.vertices.len()
@@ -39,6 +41,7 @@ impl Geometry {
     }
     /// 生成以原点为中心的盒体顶点和三角形索引；位置和旋转由网格世界矩阵另行描述。
     pub fn cuboid(width: f32, height: f32, depth: f32) -> Self {
+        // 八个角点共享位置，每个面拆两个三角形；尺寸有效性由构造调用边界检查，cuboid 本身只生成数值。
         let (x, y, z) = (width / 2., height / 2., depth / 2.);
         Self {
             uv: vec![],
@@ -72,6 +75,7 @@ impl Geometry {
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 /// 一次场景实例：几何、世界矩阵、颜色与可选 UI 面板，身份用于拾取回关联。
 pub struct Mesh {
+    // 纯文本业务关联身份，用于拾取返回；不作为渲染线程可操作的托管引用。
     pub identity: String,
     pub geometry: Arc<Geometry>,
     pub world: Matrix,
@@ -110,6 +114,7 @@ pub struct Scene {
     pub ambient: f32,
     pub background: [f32; 3],
     #[serde(skip)]
+    // 序列化忽略的世界 BVH，反序列化后可按场景网格重建；相机改变不要求重建世界空间索引。
     pub acceleration: Arc<spatial::Index>,
 }
 impl PartialEq for Scene {
@@ -153,13 +158,13 @@ pub struct Hit {
 }
 
 impl View {
-    /// 检查数值、几何和资源条件是否满足本类型约束，供上层拒绝非法输入。
+    /// 递归验证相机、材质、灯光、网格/面板表面及全场景资源预算；世界 UI 嵌套最多八层。
     pub fn valid(&self) -> bool {
         thread_local! { static DEPTH:std::cell::Cell<usize>=const { std::cell::Cell::new(0) }; }
         // 验证可能递归进入面板内的 3D；作用域结束时归还深度，错误返回也不泄漏计数。
         struct Guard;
         impl Drop for Guard {
-            /// 在 Rust 所有者离开作用域时执行本类型的配套清理；不能用它代替需要报告错误的显式关闭。
+            /// 退出当前嵌套校验层时递减线程局部深度；短路失败与正常返回都恢复同一计数。
             fn drop(&mut self) {
                 DEPTH.with(|depth| depth.set(depth.get() - 1));
             }
@@ -174,12 +179,14 @@ impl View {
         }) {
             return false;
         }
+        // 深度检查通过才建立 Guard，之后任一短路校验失败都会恢复计数；上限覆盖嵌套面板中的 3D 命令。
         let _guard = Guard;
         let color_valid = |color: [f32; 3]| {
             color
                 .iter()
                 .all(|value| value.is_finite() && (0.0..=1.0).contains(value))
         };
+        // 同时限制实例数、灯光数、累计顶点数和三角形数，单个 Geometry 合法不代表整个 Scene 未超预算。
         self.camera.valid()
             && self.scene.ambient.is_finite()
             && (0.0..=1.0).contains(&self.scene.ambient)
@@ -201,6 +208,7 @@ impl View {
                 .sum::<usize>()
                 <= MAX_TRIANGLES
             && self.scene.meshes.iter().all(|mesh| {
+                // 矩阵系数有限之外还验证每个变换后顶点范围，避免局部几何合法但累计世界变换产生无限坐标。
                 mesh.geometry.valid()
                     && mesh.world.0.iter().all(|v| v.is_finite())
                     && color_valid(mesh.color)
@@ -209,6 +217,7 @@ impl View {
                         .vertices
                         .iter()
                         .all(|point| mesh.world.point(*point).valid())
+                    // 面板纹理限制在 1..2048 每轴，内部命令/视图/裁剪表等长并递归校验绘制；多一个命令额度留给装配焦点框。
                     && mesh.panel.as_ref().is_none_or(|panel| {
                         panel.width > 0
                             && panel.height > 0
@@ -235,6 +244,7 @@ impl View {
             && self.scene.lights.iter().all(|light| {
                 color_valid(light.color)
                     && light.direction.valid()
+                    // 方向光必须近似单位向量，确保点积仅反映夹角而非把方向模长重复乘入光照强度。
                     && (light.direction.length() - 1.).abs() < 0.0001
                     && light.intensity.is_finite()
                     && (0.0..=32.0).contains(&light.intensity)
@@ -242,6 +252,7 @@ impl View {
     }
     /// 按包围盒候选发射射线，再检查三角形；距离相同时保留与绘制顺序一致的实例。
     pub fn pick(&self, u: f32, v: f32, aspect: f32) -> Option<Hit> {
+        // 拾取只接受有效相机、视口内归一化点及正有限宽高比；不在此完整重验几何，调用方应先验证 View。
         if !self.camera.valid()
             || !(0.0..=1.0).contains(&u)
             || !(0.0..=1.0).contains(&v)
@@ -254,6 +265,7 @@ impl View {
         let basis = self.camera.basis()?;
         let mut hit: Option<Hit> = None;
         let temporary;
+        // 无缓存或网格数失配时本次临时重建；数量相同的内容变更须由快照层生成新索引，不靠 matches 检测。
         let index = if self.scene.acceleration.matches(self.scene.meshes.len()) {
             &*self.scene.acceleration
         } else {
@@ -261,6 +273,7 @@ impl View {
             &temporary
         };
         for (entry, instance) in index.ray(ray) {
+            // BVH 候选按包围盒进入距离排序；后续盒子起点已比最近真实交点远时，可安全停止查询。
             if hit.as_ref().is_some_and(|hit| entry > hit.distance) {
                 break;
             }
@@ -272,6 +285,7 @@ impl View {
                     continue;
                 };
                 let point = ray.origin + ray.direction * distance;
+                // near/far 限制相机前向深度，而不是到相机的欧氏距离；离轴射线同样按视锥范围筛选。
                 let depth = self.camera.view(basis, point).z;
                 if depth < self.camera.near
                     || depth > self.camera.far
@@ -282,9 +296,11 @@ impl View {
                 {
                     continue;
                 }
+                // 使用变换后的世界顶点计算面法线，支持非均匀缩放；退化三角形没有可靠法线，不作为命中。
                 let Some(normal) = (b - a).cross(c - a).normalized() else {
                     continue;
                 };
+                // 同距离时保留较早实例，与绘制严格小于深度比较一致；同实例后续同距三角形也不会覆盖前者。
                 hit = Some(Hit {
                     instance,
                     identity: mesh.identity.clone(),
@@ -331,6 +347,7 @@ pub fn surface(
     height: u32,
     aspect: f32,
 ) -> Result<Arc<[u32]>, &'static str> {
+    // 全局缓存以 View Arc 身份+输出尺寸+aspect 为键；值相等但不同 Arc 的视图不会自动命中。
     static CACHE: std::sync::OnceLock<std::sync::Mutex<SurfaceCache>> = std::sync::OnceLock::new();
     let cache = CACHE.get_or_init(Default::default);
     {
@@ -348,6 +365,7 @@ pub fn surface(
     // 3D viewport and recurse through the compositor.
     let pixels: Arc<[u32]> = render_aspect(view, width, height, aspect)?.into();
     let mut cache = cache.lock().map_err(|_| "3D surface cache poisoned")?;
+    // 按插入顺序从队首淘汰，不在命中时搬到队尾；最多 8 项、累计 8388608 像素，渲染单表面另有限额。
     while cache.entries.len() >= 8 || cache.pixels + pixels.len() > 8_388_608 {
         let Some(entry) = cache.entries.pop_front() else {
             break;
@@ -387,6 +405,7 @@ impl Vertex {
 }
 /// 生成相机空间六个视锥平面，供三角形裁剪与 BVH 可见性查询共用。
 fn frustum_planes(camera: Camera, aspect: f32) -> [[f32; 4]; 6] {
+    // 平面内侧满足 ax+by+cz+d>=0。透视侧平面随 z 展开，正交侧平面是固定 x/y 边界。
     let (x, y, slope) = match camera.projection {
         Projection::Perspective { fov } => {
             let y = (fov.to_radians() / 2.).tan();
@@ -414,10 +433,12 @@ fn clip(mut polygon: Vec<Vertex>, camera: Camera, aspect: f32) -> Vec<Vertex> {
             a * p.x + b * p.y + c * p.z + d
         };
         let mut output = Vec::new();
+        // 从闭多边形最后一点连到第一点开始，逐边做 Sutherland–Hodgman 裁剪，不遗漏首尾边。
         let mut previous = *polygon.last().unwrap();
         let mut before = distance(previous);
         for current in polygon {
             let after = distance(current);
+            // 边跨平面时按带符号距离求交点比例，同步插值相机位置和 UV；内侧端点另行保留。
             if (before >= 0.) != (after >= 0.) {
                 output.push(previous.lerp(current, before / (before - after)));
             }
@@ -445,6 +466,7 @@ fn render_aspect(
     aspect: f32,
 ) -> Result<Vec<u32>, &'static str> {
     let _scope = crate::software_renderer::RenderScope::enter()?;
+    // 颜色与深度各占一份面积，既有每表面硬上限，也在下方计入递归累计像素预算。
     let area = width as usize * height as usize;
     // Offscreen targets have a hard per-surface resource bound.
     if area > 4_194_304
@@ -456,12 +478,14 @@ fn render_aspect(
     {
         return Err("invalid 3D surface or resource budget exceeded");
     }
+    // 先申请两份工作量再分配缓冲，深度初始化正无穷，首个有效面可写入。
     crate::software_renderer::reserve_pixels(area.saturating_mul(2))?;
     let mut pixels = vec![rgb(view.scene.background); area];
     let mut depths = vec![f32::INFINITY; area];
     let camera = view.camera;
     let basis = camera.basis().unwrap();
     let perspective = matches!(camera.projection, Projection::Perspective { .. });
+    // 点已经经过视锥裁剪，才做透视除法；屏幕 y 向下，保留相机 z 用于后续深度/UV 校正。
     let project = |point: Vec3| {
         let half = match camera.projection {
             Projection::Perspective { fov } => point.z * (fov.to_radians() / 2.).tan(),
@@ -484,12 +508,14 @@ fn render_aspect(
     // 宽阶段只筛选候选：离屏网格不进入后续纹理分配和逐三角形处理。
     for instance in index.visible(camera, aspect) {
         let mesh = &view.scene.meshes[instance];
+        // 只为宽阶段可见的面板生成普通 UI 纹理；同一 mesh 的所有三角形复用本次纹理。
         let texture = mesh.panel.as_ref().map(panel::texture).transpose()?;
         for indices in &mesh.geometry.triangles {
             let [a, b, c] = indices.map(|i| mesh.world.point(mesh.geometry.vertices[i as usize]));
             let Some(normal) = (b - a).cross(c - a).normalized() else {
                 continue;
             };
+            // 每三角形使用平面法线做 Lambert 漫反射，环境光为基础，方向光逐 RGB 累加；背光点积钳零。
             let mut light = [view.scene.ambient; 3];
             for source in &view.scene.lights {
                 let intensity = normal.dot(source.direction * -1.).max(0.) * source.intensity;
@@ -497,6 +523,7 @@ fn render_aspect(
                     *channel += intensity * color;
                 }
             }
+            // 材质色乘累计光照后转 RGB，通道最终钳制；UI 面板纹理分支直接采纹理，不再乘这份网格光照。
             let color = rgb(std::array::from_fn(|i| mesh.color[i] * light[i]));
             // 在透视除法之前裁剪，并插入具有正确 UV 的交点；不能先投影再裁剪近面。
             let polygon = clip(
@@ -506,6 +533,7 @@ fn render_aspect(
                             basis,
                             mesh.world.point(mesh.geometry.vertices[index as usize]),
                         ),
+                        // 没有 UV 的顶点用 [0,0]；普通无纹理网格不依赖它，带纹理面板由构造器提供四角 UV。
                         uv: mesh
                             .geometry
                             .uv
@@ -528,6 +556,7 @@ fn render_aspect(
                 let max_x = a.x.max(b.x).max(c.x).ceil().min(width as f32) as u32;
                 let min_y = a.y.min(b.y).min(c.y).floor().max(0.) as u32;
                 let max_y = a.y.max(b.y).max(c.y).ceil().min(height as f32) as u32;
+                // 按屏幕包围矩形面积计工作，而非仅成功写像素数；大量重叠/细长三角形也不能绕过循环预算。
                 work += max_x.saturating_sub(min_x) as usize * max_y.saturating_sub(min_y) as usize;
                 if work > 32_000_000 {
                     return Err("3D raster work budget exceeded");
@@ -535,6 +564,7 @@ fn render_aspect(
                 let edge = |a: Vec3, b: Vec3, x: f32, y: f32| {
                     (x - a.x) * (b.y - a.y) - (y - a.y) * (b.x - a.x)
                 };
+                // 有向面积允许任意顶点绕序，除相同 area 得到一致重心权重；近零面积跳过，不做背面剔除。
                 let area = edge(a, b, c.x, c.y);
                 if area.abs() < 1e-6 {
                     continue;
@@ -543,6 +573,7 @@ fn render_aspect(
                     for x in min_x..max_x {
                         let px = x as f32 + 0.5;
                         let py = y as f32 + 0.5;
+                        // 在像素中心求三个屏幕重心权重，负值容忍 1e-5 舍入误差，明显在外则不做深度和纹理计算。
                         let weights = [
                             edge(b, c, px, py) / area,
                             edge(c, a, px, py) / area,
@@ -576,6 +607,7 @@ fn render_aspect(
                                                 + weights[2] * vertices[2].uv[axis]
                                         }
                                     };
+                                    // 透视校正 UV 后做最近邻采样，钳到 [0,1] 并限制到最后一个像素，避免 UV=1 恰好越界。
                                     let u = (interpolated(0).clamp(0., 1.) * panel.width as f32)
                                         .min((panel.width - 1) as f32)
                                         as usize;
@@ -599,6 +631,7 @@ fn render_aspect(
 mod tests {
     use super::*;
     #[test]
+    /// 构造99个远离视锥的网格，宽阶段只保留正中实例；有/无预存BVH的精确拾取身份与距离必须一致。
     fn spatial_index_culls_offscreen_meshes_and_preserves_ray_pick() {
         let mut view = view(Geometry::cuboid(1., 1., 1.));
         let scene = Arc::make_mut(&mut view.scene);
@@ -614,6 +647,7 @@ mod tests {
             scene.meshes.push(far);
         }
         scene.acceleration = Arc::new(spatial::Index::build(&scene.meshes));
+        // 远处实例应被宽阶段剔除；随后比较带缓存与临时重建索引的精确拾取身份/距离，防止加速改变结果。
         assert_eq!(scene.acceleration.visible(view.camera, 1.), vec![0]);
         let ray = view.camera.ray(0.5, 0.5, 1.).unwrap();
         assert_eq!(scene.acceleration.ray(ray).len(), 1);
@@ -624,6 +658,7 @@ mod tests {
         assert_eq!(indexed.identity, fallback.identity);
         assert_eq!(indexed.distance, fallback.distance);
     }
+    /// 构造测试最小视图：默认相机、原点红网格、纯环境光与白背景，不依赖业务VM或外部光源。
     fn view(geometry: Geometry) -> View {
         View {
             camera: Camera::default(),
@@ -643,6 +678,7 @@ mod tests {
         }
     }
     #[test]
+    /// 跨越近裁剪面的三角形仍应产生像素，射线命中受同一 near/far 约束；缩短远面后命中消失。
     fn triangles_crossing_near_plane_are_clipped_and_pick_uses_the_same_range() {
         let mut view = view(Geometry {
             uv: vec![],
@@ -658,6 +694,7 @@ mod tests {
         view.camera.near = 1.;
         view.camera.far = 10.;
         view.camera.projection = Projection::Perspective { fov: 90. };
+        // 三角形跨近面仍应产生可见红像素，拾取也必须尊重相同 near/far；缩短 far 后命中消失。
         let pixels = render(&view, 64, 64).unwrap();
         assert!(pixels.contains(&0xFF0000));
         let hit = view.pick(0.5, 0.5, 1.).unwrap();
@@ -666,6 +703,7 @@ mod tests {
         assert!(view.pick(0.5, 0.5, 1.).is_none());
     }
     #[test]
+    /// 验证局部TRS先于父变换作用于点；正交投影不同水平采样的射线方向相同但原点按可见宽度平移。
     fn group_transform_order_and_orthographic_rays_are_consistent() {
         let local = Matrix::trs(
             Vec3::new(1., 0., 0.),
@@ -689,10 +727,12 @@ mod tests {
         assert_eq!(right.origin.x - left.origin.x, 2.);
     }
     #[test]
+    /// 同一不可变视图/尺寸/aspect复用像素Arc；改变aspect重绘，超像素预算或退化相机必须拒绝。
     fn surface_cache_reuses_immutable_frames_and_rejects_invalid_resources() {
         let view = Arc::new(view(Geometry::cuboid(1., 1., 1.)));
         let first = surface(&view, 64, 64, 1.).unwrap();
         let second = surface(&view, 64, 64, 1.).unwrap();
+        // 同一不可变视图/尺寸/aspect 返回同像素 Arc；仅改变 aspect 即使像素尺寸不变也必须重绘。
         assert!(Arc::ptr_eq(&first, &second));
         let wide = surface(&view, 64, 64, 2.).unwrap();
         assert!(!Arc::ptr_eq(&first, &wide));

src/render/scene3d/math.rs

@@ -5,14 +5,14 @@ use serde::{Deserialize, Serialize};
 use std::ops::{Add, Mul, Sub};
 
 #[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
-/// 三个有限浮点分量的数学向量，不是托管 Vec3 对象。
+/// 三维数学向量；构造不校验分量，需在输入边界显式调用 valid，不是托管 Vec3 对象。
 pub struct Vec3 {
     pub x: f32,
     pub y: f32,
     pub z: f32,
 }
 impl Vec3 {
-    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
+    /// 直接保存三个分量，不隐式归一化或拒绝非有限值。
     pub const fn new(x: f32, y: f32, z: f32) -> Self {
         Self { x, y, z }
     }
@@ -34,11 +34,13 @@ impl Vec3 {
     }
     /// 仅在长度有效且不退化时返回单位向量，避免除零产生非有限结果。
     pub fn normalized(self) -> Option<Self> {
+        // 先求模长，拒绝非有限值和长度不大于 1e-6 的向量；返回 None 让相机/法线调用方停止退化计算。
         let length = self.length();
         (length.is_finite() && length > 1e-6).then(|| self * (1.0 / length))
     }
-    /// 检查数值、几何和资源条件是否满足本类型约束，供上层拒绝非法输入。
+    /// 要求三维向量各分量有限、绝对值不超过一百万；构造和算术运算不会自动调用此检查。
     pub fn valid(self) -> bool {
+        // 构造函数与算术运算不会自动验证；此入口显式要求每个分量有限且绝对值至多一百万。
         [self.x, self.y, self.z]
             .iter()
             .all(|v| v.is_finite() && v.abs() <= 1_000_000.0)
@@ -80,12 +82,15 @@ impl Default for Matrix {
 impl Matrix {
     /// 求仿射世界矩阵的逆；退化或不可逆时返回空值。
     pub fn inverse(self) -> Option<Self> {
+        // 这里按仿射矩阵处理：最后一行假设为 [0,0,0,1]，只逆左上 3×3，不实现一般透视矩阵求逆。
         let m = self.0;
         let determinant = m[0] * (m[5] * m[10] - m[6] * m[9]) - m[1] * (m[4] * m[10] - m[6] * m[8])
             + m[2] * (m[4] * m[9] - m[5] * m[8]);
+        // 接近零行列式意味着某方向被压扁或数值不稳定；不能继续除以 determinant。
         if !determinant.is_finite() || determinant.abs() < 1e-9 {
             return None;
         }
+        // 用伴随矩阵除行列式得到线性部分逆矩阵；先把逆平移留为零。
         let d = 1. / determinant;
         let mut out = Self([
             (m[5] * m[10] - m[6] * m[9]) * d,
@@ -105,6 +110,7 @@ impl Matrix {
             0.,
             1.,
         ]);
+        // 仿射逆平移为 -A⁻¹t。此时 out 平移为零，所以 point 只应用刚求得的线性逆变换。
         let translation = out.point(Vec3::new(m[3], m[7], m[11])) * -1.;
         out.0[3] = translation.x;
         out.0[7] = translation.y;
@@ -113,6 +119,7 @@ impl Matrix {
     }
     /// 组合父子仿射变换，调用顺序决定局部坐标最终落在哪个世界位置。
     pub fn compose(self, local: Self) -> Self {
+        // 行主序存储，点视作列向量；self.compose(local) = self × local，即先应用 local 再应用 self。
         let mut out = [0.; 16];
         for row in 0..4 {
             for col in 0..4 {
@@ -133,6 +140,7 @@ impl Matrix {
     }
     /// 由平移、角度旋转和缩放构造局部仿射矩阵。
     pub fn trs(position: Vec3, rotation: Vec3, scale: Vec3) -> Self {
+        // 输入欧拉角单位为度，先转换为弧度。组合为 T × Rz × Ry × Rx × S，列分别乘对应缩放轴。
         let (sx, cx) = rotation.x.to_radians().sin_cos();
         let (sy, cy) = rotation.y.to_radians().sin_cos();
         let (sz, cz) = rotation.z.to_radians().sin_cos();
@@ -161,7 +169,9 @@ impl Matrix {
 #[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
 /// 投影策略：透视视场角或正交可见高度。
 pub enum Projection {
+    // fov 表示垂直视场角（度），水平范围再乘视口宽高比。
     Perspective { fov: f32 },
+    // height 是相机空间可见总高度，与深度无关；宽度为 height × aspect。
     Orthographic { height: f32 },
 }
 
@@ -198,13 +208,16 @@ pub struct Basis {
 impl Camera {
     /// 从观察位置、目标和上方向建立正交相机基；方向退化时拒绝。
     pub fn basis(self) -> Option<Basis> {
+        // forward 指向观察目标；up 输入只提供大致上方向，叉积后重新正交化。
+        // 位置等于目标、up 为零或与前向平行时，normalized 返回 None。
         let forward = (self.target - self.position).normalized()?;
         let right = forward.cross(self.up).normalized()?;
         let up = right.cross(forward).normalized()?;
         Some(Basis { right, up, forward })
     }
-    /// 检查数值、几何和资源条件是否满足本类型约束，供上层拒绝非法输入。
+    /// 验证相机向量/观察基、裁剪面次序和投影参数；退化方向、非法视场角或正交高度均返回 false。
     pub fn valid(self) -> bool {
+        // 除了向量范围，还要求有效观察基、0 < near < far，以及合法视场角或正交高度。
         self.position.valid()
             && self.target.valid()
             && self.up.valid()
@@ -223,15 +236,19 @@ impl Camera {
     }
     /// 把世界点投影到相机的右/上/前基向量坐标。
     pub fn view(self, basis: Basis, p: Vec3) -> Vec3 {
+        // 先把世界点相对化，再点乘正交基；这里前方 z 为正，与某些图形 API 的负 z 约定不同。
         let p = p - self.position;
         Vec3::new(p.dot(basis.right), p.dot(basis.up), p.dot(basis.forward))
     }
     /// 从视口归一化坐标生成透视或正交射线；宽高比由具体视口提供。
     pub fn ray(self, u: f32, v: f32, aspect: f32) -> Option<Ray> {
         let basis = self.basis()?;
+        // u/v 通常是视口内 [0,1]，映射到 [-1,1] 并翻转屏幕 y。
+        // 此函数不钳制输入，捕获拖动可以从视口外继续生成射线；aspect 由调用方保证有效。
         let (x, y) = (u * 2. - 1., 1. - v * 2.);
         match self.projection {
             Projection::Perspective { fov } => {
+                // 透视射线共用相机原点，方向沿前向加上视平面偏移，最后归一化。
                 let half = (fov.to_radians() / 2.).tan();
                 Some(Ray {
                     origin: self.position,
@@ -241,6 +258,7 @@ impl Camera {
                         .normalized()?,
                 })
             }
+            // 正交射线方向都为 forward，只改变起点在相机右/上平面中的位置。
             Projection::Orthographic { height } => Some(Ray {
                 origin: self.position
                     + basis.right * (x * height * aspect / 2.)
@@ -259,15 +277,18 @@ pub struct Ray {
 impl Ray {
     /// 求射线与三角形相交距离和重心坐标，拒绝退化三角形及射线起点后方的交点。
     pub fn triangle(self, a: Vec3, b: Vec3, c: Vec3) -> Option<(f32, [f32; 3])> {
+        // Möller–Trumbore 求交：使用两条三角形边与叉积解重心系数，不先构造平面方程。
         let ab = b - a;
         let ac = c - a;
         let p = self.direction.cross(ac);
         let determinant = ab.dot(p);
+        // 近零表示射线与面平行或三角形退化；保留正负行列式，因此不做背面剔除。
         if determinant.abs() < 1e-7 {
             return None;
         }
         let inverse = 1.0 / determinant;
         let t = self.origin - a;
+        // u 是顶点 b 的重心权重，必须位于 [0,1]；v 是 c 的权重，a 的权重由 1-u-v 得到。
         let u = t.dot(p) * inverse;
         if !(0.0..=1.0).contains(&u) {
             return None;
@@ -277,6 +298,7 @@ impl Ray {
         if v < 0. || u + v > 1. {
             return None;
         }
+        // 返回的是射线参数 t，方向为单位向量时才等于世界距离；负值在射线起点后方，被拒绝。
         let distance = ac.dot(q) * inverse;
         (distance >= 0.).then_some((distance, [1. - u - v, u, v]))
     }

src/render/scene3d/panel.rs

@@ -17,17 +17,22 @@ use std::sync::Arc;
 #[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
 /// 一次面板出现的正逆投影信息，可以链接父面板形成嵌套映射。
 pub struct Mapping {
+    // 包含本面板的 3D 视口 Mount ID，与 key 一起区分同一业务场景的多次出现。
     pub owner: u64,
+    // 面板在场景中的稳定标识，不能仅凭 Block 身份选择某个具体面板出现。
     pub key: u64,
     pub view: Arc<View>,
     pub rect: [f32; 4],
+    // 外层二维相机变换；逆映射先处理它，再进入 3D 摄像机射线计算。
     pub outer: Transform,
     pub clip: Option<[f32; 4]>,
+    // 嵌套面板的外层链；反投影从父到子，正投影从子到父。
     pub parent: Option<Arc<Mapping>>,
 }
 impl Mapping {
     /// 沿父面板逆投影到当前平面的 UI 像素；要求可见时使用最近射线命中拒绝被遮挡的目标。
     pub fn texture_point(&self, point: Point, clipped: bool) -> Option<Point> {
+        // 先把最外层窗口坐标逐层反投影为父面板像素，再检查当前面板所属空间的裁剪。
         let point = if let Some(parent) = &self.parent {
             parent.texture_point(point, clipped)?
         } else {
@@ -45,6 +50,7 @@ impl Mapping {
         if width <= 0. || height <= 0. {
             return None;
         }
+        // rect 是 3D 视口在当前二维空间的位置，归一化坐标传给该视口相机；不是面板纹理坐标。
         let (u, v) = ((point.x - x) / width, (point.y - y) / height);
         let mesh = self.view.scene.meshes.iter().find(|mesh| {
             mesh.panel
@@ -68,18 +74,22 @@ impl Mapping {
         let center = mesh.world.point(Vec3::default());
         let normal = (mesh.world.point(Vec3::new(1., 0., 0.)) - center)
             .cross(mesh.world.point(Vec3::new(0., 1., 0.)) - center);
+        // 用世界变换后的局部 x/y 轴叉积求平面法线，支持旋转和非均匀缩放；平行射线无交点。
         let denominator = normal.dot(ray.direction);
         if denominator.abs() < 1e-7 {
             return None;
         }
+        // 解射线与无限平面交点，拒绝非有限及相机后方结果；clipped=false 时允许点落在面板边界外。
         let distance = (center - ray.origin).dot(normal) / denominator;
         if !distance.is_finite() || distance <= 0. {
             return None;
         }
+        // 把世界交点乘逆 world 回到面板局部坐标，逆矩阵退化时拒绝。
         let local = mesh
             .world
             .inverse()?
             .point(ray.origin + ray.direction * distance);
+        // 面板网格约定以局部原点为中心；x 向右、y 向上，转换为纹理左上原点、y 向下。
         let world_width = mesh.geometry.vertices[1].x - mesh.geometry.vertices[0].x;
         let world_height = mesh.geometry.vertices[0].y - mesh.geometry.vertices[2].y;
         let point = Point::new(
@@ -99,6 +109,7 @@ impl Mapping {
         let panel = mesh.panel.as_ref()?;
         let width = mesh.geometry.vertices[1].x - mesh.geometry.vertices[0].x;
         let height = mesh.geometry.vertices[0].y - mesh.geometry.vertices[2].y;
+        // 正向路径与 texture_point 对称：纹理像素先转局部平面点，再进入世界空间。
         let world = mesh.world.point(Vec3::new(
             (point.x / panel.width as f32 - 0.5) * width,
             (0.5 - point.y / panel.height as f32) * height,
@@ -106,10 +117,12 @@ impl Mapping {
         ));
         let camera = self.view.camera;
         let local = camera.view(camera.basis()?, world);
+        // 点在近远面之外时无可用投影；此方法仅算位置，不检查前方遮挡或二维 clip。
         if local.z <= camera.near || local.z >= camera.far {
             return None;
         }
         let [x, y, w, h] = self.rect;
+        // 透视半高随相机深度增长，正交半高恒定；横向除数还包含视口宽高比。
         let half = match camera.projection {
             Projection::Perspective { fov } => local.z * (fov.to_radians() / 2.).tan(),
             Projection::Orthographic { height } => height / 2.,
@@ -118,6 +131,7 @@ impl Mapping {
             x + (local.x / (half * w / h) + 1.) * w / 2.,
             y + (1. - local.y / half) * h / 2.,
         ));
+        // 当前投影得到的是父面板纹理空间；继续向外层正投影，直到窗口页面坐标。
         if let Some(parent) = &self.parent {
             parent.project_point(point)
         } else {
@@ -142,6 +156,7 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
     use crate::document::RenderCommand;
     use std::collections::{HashMap, HashSet};
     let mounts: HashMap<_, _> = frame.mounts.iter().map(|mount| (mount.id, mount)).collect();
+    // 分组键包含视口 owner 和面板 key，防止同一场景在两个视口出现时互相混入绘制命令。
     let mut groups = HashMap::<(u64, u64), Vec<Entry>>::new();
     let mut roots = Vec::new();
     // 每条命令都有出现归属；据此分流为窗口根命令或某个世界面板的内部命令。
@@ -163,6 +178,7 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
             roots.push(entry);
         }
     }
+    // 面板内焦点框也必须作为纹理内容绘制，不能留在窗口根层，否则会脱离世界面板位置。
     if let Some(mount) = frame.focus.and_then(|id| mounts.get(&id))
         && let Some(panel) = &mount.panel
     {
@@ -195,6 +211,7 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
         if let RenderCommand::Scene3D { view, .. } = &mut entry.command
             && view.scene.meshes.iter().any(|mesh| mesh.panel.is_some())
         {
+            // 只有含面板的 Scene3D 命令才递归装配；path 跟踪当前祖先出现，限制深度小于 8 并拒绝环。
             anyhow::ensure!(
                 depth < 8 && path.insert(entry.owner),
                 "3D UI paint nesting cycle or depth budget exceeded"
@@ -208,6 +225,7 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
                         clips: Vec::new(),
                         views: Vec::new(),
                     };
+                    // 按照原命令顺序递归装配面板内容；嵌套 3D 子命令先完成，父面板才取得完整表面。
                     for child in groups.get(&(entry.owner, panel.key)).into_iter().flatten() {
                         let child = assemble(child.clone(), groups, path, depth + 1)?;
                         surface.commands.push(child.command);
@@ -221,11 +239,13 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
                 scene: Arc::new(scene),
                 camera: view.camera,
             });
+            // 退出当前分支时撤销祖先标记，允许同一身份在其他独立分支中出现而不误判成环。
             path.remove(&entry.owner);
         }
         Ok(entry)
     }
     let mut path = HashSet::new();
+    // 面板内部命令已经移入 UiSurface，根帧只保留外层命令；四张平行元数据表同步重建。
     frame.commands.clear();
     frame.command_clips.clear();
     frame.command_views.clear();
@@ -242,10 +262,12 @@ pub fn compose(frame: &mut crate::document::Frame) -> anyhow::Result<()> {
 
 /// 为一个面板分配有限像素表面，并调用普通 UI 软件渲染；当前实现不会按面板内容独立缓存纹理。
 pub fn texture(panel: &super::Panel) -> Result<Vec<u32>, &'static str> {
+    // 先向统一像素预算申请有限纹理面积，再分配背景缓冲；嵌套面板同样受该预算约束。
     crate::software_renderer::reserve_pixels(panel.width as usize * panel.height as usize)?;
     let mut pixels =
         vec![super::rgb(panel.background); panel.width as usize * panel.height as usize];
     if let Some(surface) = &panel.surface {
+        // 将普通 UI 表面包装为临时文档复用现有显示列表和软件渲染路径；比例 1 对应纹理像素。
         let document = crate::document::RenderDocument {
             frame: crate::document::Frame {
                 background: format!("#{:06X}", super::rgb(panel.background)),

src/render/scene3d/spatial.rs

@@ -21,6 +21,7 @@ impl Bounds {
             .vertices
             .iter()
             .map(|point| mesh.world.point(*point));
+        // 空网格没有包围盒，返回 None 后不会进入树；首顶点初始化上下界，避免把原点误算进边界。
         let first = points.next()?;
         Some(points.fold(
             Self {
@@ -64,6 +65,7 @@ impl Bounds {
     }
     /// 用包围盒筛出射线候选；索引查询按进入距离排序，精确三角形求交在调用方完成。
     fn ray(self, ray: Ray) -> Option<f32> {
+        // slab 算法逐轴交区间；near 从零开始，只保留射线前方，起点在盒内时返回零。
         let mut near = 0f32;
         let mut far = f32::INFINITY;
         for (origin, direction, min, max) in [
@@ -71,6 +73,7 @@ impl Bounds {
             (ray.origin.y, ray.direction.y, self.min.y, self.max.y),
             (ray.origin.z, ray.direction.z, self.min.z, self.max.z),
         ] {
+            // 近乎平行该轴时不做除法；起点在 slab 外即可拒绝，在 slab 内则该轴不收窄距离。
             if direction.abs() < 1e-12 {
                 if origin < min || origin > max {
                     return None;
@@ -79,6 +82,7 @@ impl Bounds {
             }
             let a = (min - origin) / direction;
             let b = (max - origin) / direction;
+            // 方向可为负，先排序该轴进入/退出距离，再与之前各轴区间求交。
             near = near.max(a.min(b));
             far = far.min(a.max(b));
             if far < near {
@@ -87,8 +91,9 @@ impl Bounds {
         }
         Some(near)
     }
-    /// 用相机六平面保守判断包围盒可见性，返回保持原场景顺序的候选。
+    /// 检查八角是否全落在任一视锥平面外侧；返回保守可见性，不代表真实三角形可见。
     fn visible(self, camera: Camera, basis: Basis, planes: &[[f32; 4]; 6]) -> bool {
+        // 用三位索引枚举 AABB 八角，再转到相机空间，使角点与视锥平面处于同一坐标系。
         let corners: [Vec3; 8] = std::array::from_fn(|index| {
             camera.view(
                 basis,
@@ -111,6 +116,7 @@ impl Bounds {
                 ),
             )
         });
+        // 只有某个平面外侧包含全部八角时才剔除；盒与视锥可能无真实相交也会保守保留。
         !planes.iter().any(|[a, b, c, d]| {
             corners
                 .iter()
@@ -148,8 +154,9 @@ pub struct Index {
     root: Option<usize>,
 }
 impl Index {
-    /// 根据当前输入构造本模块的派生结果，具体的验证与资源边界见函数内步骤。
+    /// 用变换后的网格顶点建立世界 AABB 与 BVH；忽略空网格，树内仅保存原生几何下标。
     pub fn build(meshes: &[Mesh]) -> Self {
+        // 保留与原网格下标等长的包围盒数组；items 仅收集非空网格，最终候选仍指向原场景下标。
         let bounds: Vec<_> = meshes.iter().map(Bounds::mesh).collect();
         let mut items: Vec<_> = bounds
             .iter()
@@ -173,11 +180,13 @@ impl Index {
             .map(|&index| self.bounds[index].unwrap())
             .reduce(Bounds::union)
             .unwrap();
+        // 先占位父节点，递归子树会扩展 nodes；返回后按稳定下标替换父占位，不保留可失效的引用。
         let index = self.nodes.len();
         self.nodes.push(Node::Leaf {
             bounds,
             items: Vec::new(),
         });
+        // 至多四项成为叶；更大集合沿包围盒最长轴排序后二等分，控制树深而非按三角形拆分。
         if items.len() <= 4 {
             self.nodes[index] = Node::Leaf {
                 bounds,
@@ -198,6 +207,7 @@ impl Index {
                     .center(axis)
                     .total_cmp(&self.bounds[b].unwrap().center(axis))
             });
+            // 两半均非空，即使所有中心重合也能递减集合规模，保证递归终止。
             let mid = items.len() / 2;
             let (left, right) = items.split_at_mut(mid);
             let left = self.split(left);
@@ -211,11 +221,13 @@ impl Index {
         index
     }
     /// 检查索引覆盖的网格数量是否与场景相符；缺失缓存时允许重建。
+    // 这里只校验数量，不验证顶点或 world 变换；调用方必须在几何改变后重建索引。
     pub fn matches(&self, meshes: usize) -> bool {
         self.bounds.len() == meshes
     }
     /// 用包围盒筛出射线候选；索引查询按进入距离排序，精确三角形求交在调用方完成。
     pub fn ray(&self, ray: Ray) -> Vec<(f32, usize)> {
+        // 空树的栈为空；显式栈避免查询递归，先测分支包围盒，未命中时整棵子树跳过。
         let mut stack: Vec<_> = self.root.into_iter().collect();
         let mut output = Vec::new();
         while let Some(index) = stack.pop() {
@@ -236,11 +248,13 @@ impl Index {
                 }
             }
         }
+        // 距离是盒进入距离而非三角形命中距离；同距按场景下标排序，精确拾取仍由调用方完成。
         output.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1)));
         output
     }
     /// 用相机六平面保守判断包围盒可见性，返回保持原场景顺序的候选。
     pub fn visible(&self, camera: Camera, aspect: f32) -> Vec<usize> {
+        // 相机无法建立有效正交基时没有可靠视锥，返回空候选，不继续使用无效投影。
         let Some(basis) = camera.basis() else {
             return Vec::new();
         };
@@ -264,6 +278,7 @@ impl Index {
                 }
             }
         }
+        // BVH 遍历顺序与场景顺序不同；恢复原下标顺序以保持后续绘制及同深度处理稳定。
         output.sort_unstable();
         output
     }

src/render/scroll.rs

@@ -54,6 +54,8 @@ impl Axis {
 
 /// 求两个裁剪矩形的交集，空区域仍保持合法非负尺寸。
 fn intersection(a: [f32; 4], b: [f32; 4]) -> [f32; 4] {
+    // 输入采用 [左, 上, 宽, 高]。交集左上取较大值，右下取较小值；
+    // 右/下边界再钳到左/上边界，保证完全错开时输出零面积而非负尺寸。
     let x = a[0].max(b[0]);
     let y = a[1].max(b[1]);
     [
@@ -65,6 +67,8 @@ fn intersection(a: [f32; 4], b: [f32; 4]) -> [f32; 4] {
 }
 /// 沿出现树累计滚动偏移和裁剪；遇到独立场景视口时按其有限边界重新建立投影范围。
 pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame) -> Result<()> {
+    // 第一阶段只建立查找表，不改坐标：Block ID 查语义节点，Mount ID 查帧中的出现。
+    // 同一个 Block 可以多次出现；滚动偏移后面按 Mount 读取，不能存入这个 Block 表。
     let mut nodes = HashMap::new();
     let mut work = vec![root];
     while let Some(node) = work.pop() {
@@ -82,6 +86,8 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
         .iter()
         .map(|m| matches!(nodes[m.block_id.as_str()].kind, UiKind::Scroll { .. }))
         .collect();
+    // extent 保存尚未滚动的内容右下边界。滚动容器先扣除自身右/下 inset，
+    // 后续传播子内容后再加回 padding，避免把空容器的内边距算成可滚动溢出。
     let mut extent: Vec<_> = frame
         .mounts
         .iter()
@@ -95,6 +101,7 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
             (m.x + m.width - inset.right, m.y + m.height - inset.bottom)
         })
         .collect();
+    // Mount 按父先子后排列，反向扫描才能先汇总子树，再将边界向父级传播。
     for i in (0..frame.mounts.len()).rev() {
         let m = &frame.mounts[i];
         if let Some(parent) = m.parent {
@@ -103,8 +110,10 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
                 nodes[frame.mounts[parent].block_id.as_str()].kind,
                 UiKind::CanvasViewport { .. } | UiKind::Viewport3D { .. }
             ) {
+                // 场景世界内部的坐标范围不扩大外部有限布局盒子的滚动范围。
                 continue;
             }
+            // 子滚动容器向外只贡献自己的视口；它内部的溢出由自己的偏移处理。
             let e = if scrolling[i] {
                 (m.x + m.width, m.y + m.height)
             } else {
@@ -114,6 +123,8 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
             extent[parent].1 = extent[parent].1.max(e.1);
         }
     }
+    // 第二阶段从父到子投影。上下文保存祖先累计位移和裁剪，而非当前节点本身的偏移。
+    // 重建绘制命令及其平行元数据，保证显示、命中与裁剪使用同一套投影坐标。
     let mut contexts = HashMap::<u64, (f32, f32, Option<[f32; 4]>)>::new();
     frame.commands.clear();
     frame.command_clips.clear();
@@ -130,6 +141,7 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
             UiKind::Scroll { axis, .. } => axis,
             _ => Axis::Both,
         };
+        // limits 在未改写的布局坐标里计算；禁用轴直接设零，内容比视口小时也为零。
         let limits = [
             if axis.horizontal() {
                 (extent[i].0 + padding.right - m.x - m.width).max(0.0)
@@ -142,10 +154,12 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
                 0.0
             },
         ];
+        // 当前容器跟随祖先滚动；它自己的 scroll_offset 只影响子节点，容器边框保持原位。
         m.x -= dx;
         m.y -= dy;
         m.clip = clip;
         let mut child = (dx, dy, clip);
+        // 普通裁剪使用边框内侧矩形，并与祖先裁剪求交，不能扩大祖先允许的区域。
         if node.clip_children {
             let border = node.border;
             let viewport = [
@@ -167,11 +181,14 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
             let owner = vm
                 .upgrade(*weak)?
                 .ok_or_else(|| anyhow::anyhow!("expired scroll Mount"))?;
+            // weak upgrade 临时保活 Mount。先保存 payload 读取结果再 release，
+            // 这样读取失败也会先释放强引用，然后由下方 offset? 传播错误。
             let offset = vm
                 .payload::<Mount>(owner, "Mount")
                 .map(|mount| mount.scroll_offset);
             vm.release(owner)?;
             let offset = offset?;
+            // 内容缩短时旧偏移可能超界；此处只钳制帧投影，不改写托管 Mount 的原偏移。
             let x = offset[0].clamp(0.0, limits[0]);
             let y = offset[1].clamp(0.0, limits[1]);
             m.scroll = Some([x, y, limits[0], limits[1]]);
@@ -187,6 +204,7 @@ pub fn project(vm: &mut Vm, table: &MountTable, root: &UiNode, frame: &mut Frame
                 ),
             );
         }
+        // 3D 子场景有独立投影空间，不能继续叠加外层二维滚动坐标和裁剪。
         if matches!(node.kind, UiKind::Viewport3D { .. }) {
             child = (0., 0., None);
         }
@@ -218,6 +236,7 @@ pub fn coordinate(value: &Value) -> Result<f32, VmError> {
             "scroll coordinates must be numbers",
         ));
     };
+    // 通过 Number 文本表示转为 f32，再检查有限性及绝对值上限；允许负数以表达相对滚动。
     let n = value
         .to_string()
         .parse::<f32>()
@@ -235,6 +254,7 @@ pub fn set(
     point: [f32; 2],
     relative: bool,
 ) -> Result<(), VmError> {
+    // 只允许已提交且仍挂接的出现接受滚动；布局过程中的临时 Mount 不具备稳定滚动边界。
     let mut mount = cx.store().payload::<Mount>(owner, "Mount")?.clone();
     if !mount.mounted || mount.layout.is_some() {
         return Err(VmError::InvalidArgument(
@@ -257,7 +277,8 @@ pub fn set(
     let desktop = cx
         .upgrade(desktop)?
         .ok_or(VmError::InvalidArgument("Mount window expired"))?;
-    // Check the normal mutation barrier even when the clamped result is equal.
+    // 即使钳制后数值未变，也走正常写屏障，使只读调用不能借助无效滚动绕过变更限制。
+    // scrollRequested 通知后续刷新重做投影，而不是在这里直接重建布局或绘制。
     cx.replace_payload(owner, mount)?;
     cx.set_attr(desktop, "scrollRequested", Value::Bool(true))
 }
@@ -273,6 +294,7 @@ pub fn into_view(
             "scrollIntoView requires committed attached Mount",
         ));
     }
+    // rect 随祖先滚动调整，表示目标在当前投影中的可见需求；从最近父容器逐层向外处理。
     let mut rect = [
         mount.geometry.x,
         mount.geometry.y,
@@ -286,6 +308,7 @@ pub fn into_view(
         };
         let mount = cx.store().payload::<Mount>(owner, "Mount")?.clone();
         parent = mount.parent;
+        // 跨越独立场景边界时，外层只能滚动整个场景视口，不能使用内部世界坐标定位目标。
         if mount.geometry.canvas_viewport || mount.geometry.scene3d_viewport {
             rect = [
                 mount.geometry.x,
@@ -295,6 +318,7 @@ pub fn into_view(
             ];
         }
         if let Some(offset) = mount.geometry.scroll {
+            // 目标起点在视口前则向前对齐；否则只补足末端溢出，已完全可见时返回零。
             let delta = |start: f32, length: f32, viewport: f32, size: f32| {
                 if start < viewport {
                     start - viewport
@@ -306,6 +330,7 @@ pub fn into_view(
             let dy = delta(rect[1], rect[3], mount.geometry.y, mount.geometry.height);
             let x = (offset[0] + dx).clamp(0.0, offset[2]);
             let y = (offset[1] + dy).clamp(0.0, offset[3]);
+            // 下一层祖先看到的目标位置必须扣掉本层实际移动量，不能扣未钳制的请求量。
             rect[0] -= x - offset[0];
             rect[1] -= y - offset[1];
             if x != offset[0] || y != offset[1] {
@@ -318,12 +343,15 @@ pub fn into_view(
 /// 按逆出现顺序选择指针处可处理当前滚动方向的最内层容器。
 pub fn wheel_target(frame: &Frame, point: Point, delta: [f32; 2]) -> Option<u64> {
     let indices: HashMap<_, _> = frame.mounts.iter().map(|mount| (mount.id, mount)).collect();
+    // 逆序先取最上层命中的出现，再沿其祖先寻找能消费位移的滚动容器。
+    // 不搜索被覆盖的兄弟容器，内层到边界后才交给外层滚动。
     let mut current = frame
         .mounts
         .iter()
         .rev()
         .find(|mount| mount.contains(point));
     while let Some(mount) = current {
+        // 只有至少一轴钳制后真正改变偏移才接收此次输入；没有任何容器可移动则返回 None。
         if mount.scroll.is_some_and(|s| {
             (s[0] + delta[0]).clamp(0.0, s[2]) != s[0] || (s[1] + delta[1]).clamp(0.0, s[3]) != s[1]
         }) {

src/render/software_renderer.rs

@@ -10,6 +10,7 @@ use crate::{
 /// 显示列表的 CPU 执行入口，错误在原生 present 前向上传递。
 pub struct SoftwareRenderer;
 
+// 预算按渲染线程维护，递归 3D/面板渲染共用同一组计数；不同线程之间不共享额度。
 thread_local! {
     static RENDER_DEPTH:std::cell::Cell<usize>=const { std::cell::Cell::new(0) };
     static PIXEL_UNITS:std::cell::Cell<usize>=const { std::cell::Cell::new(0) };
@@ -21,9 +22,11 @@ impl RenderScope {
     pub fn enter() -> Result<Self, &'static str> {
         RENDER_DEPTH.with(|depth| {
             let current = depth.get();
+            // 拒绝第 19 层进入，不先增加深度；成功返回的 RenderScope 析构时才对应减一。
             if current >= 18 {
                 return Err("render nesting budget exceeded");
             }
+            // 只有最外层渲染开始才清累计像素数；递归进入不能借此重置预算。
             if current == 0 {
                 PIXEL_UNITS.with(|pixels| pixels.set(0));
             }
@@ -33,7 +36,7 @@ impl RenderScope {
     }
 }
 impl Drop for RenderScope {
-    /// 在 Rust 所有者离开作用域时执行本类型的配套清理；不能用它代替需要报告错误的显式关闭。
+    /// 退出一次像素渲染作用域时归还嵌套深度；像素工作量仍按本帧累计，不因退出内层而返还。
     fn drop(&mut self) {
         RENDER_DEPTH.with(|depth| depth.set(depth.get() - 1));
     }
@@ -41,6 +44,7 @@ impl Drop for RenderScope {
 /// 累加本帧中间表面工作量，超过预算立即返回错误。
 pub(crate) fn reserve_pixels(units: usize) -> Result<(), &'static str> {
     PIXEL_UNITS.with(|pixels| {
+        // 累计申请工作量而非当前存活像素；释放一个中间表面不会返还额度，饱和加法避免溢出绕过限制。
         let next = pixels.get().saturating_add(units);
         if next > 16_777_216 {
             return Err("nested render pixel budget exceeded");
@@ -58,6 +62,7 @@ impl SoftwareRenderer {
         width: u32,
         height: u32,
     ) -> Result<(), &'static str> {
+        // RAII 保护让成功、提前返回和错误传播都恢复深度；target 长度须由调用方保证至少 width×height。
         let _scope = RenderScope::enter()?;
         let mut canvas = Canvas {
             pixels: target,
@@ -70,6 +75,7 @@ impl SoftwareRenderer {
         for command in list.commands() {
             match command {
                 DrawCommand::Scene3D { rect, view } => {
+                    // 先将 3D 矩形与当前裁剪和目标尺寸相交；完全不可见时连中间表面都不生成。
                     let left = rect.x.max(canvas.clip.x).max(0.).floor() as u32;
                     let top = rect.y.max(canvas.clip.y).max(0.).floor() as u32;
                     let right = (rect.x + rect.width)
@@ -85,24 +91,28 @@ impl SoftwareRenderer {
                     if left >= right || top >= bottom || rect.width <= 0. || rect.height <= 0. {
                         continue;
                     }
+                    // 3D 中间表面的最长边限制到约 2048 像素，再采样到请求尺寸；相机宽高比仍用原 rect，避免改变透视比例。
                     let lod = (2048. / rect.width.max(rect.height)).min(1.);
                     let w = (rect.width * lod).ceil().max(1.) as u32;
                     let h = (rect.height * lod).ceil().max(1.) as u32;
                     let surface = crate::scene3d::surface(view, w, h, rect.width / rect.height)?;
                     for y in top..bottom {
                         for x in left..right {
+                            // 按目标像素中心反算纹理坐标并钳到有效表面边界；只复制可见区域，不循环整个放大矩形。
                             let u = (((x as f32 + 0.5 - rect.x) / rect.width) * w as f32)
                                 .clamp(0., (w - 1) as f32)
                                 as u32;
                             let v = (((y as f32 + 0.5 - rect.y) / rect.height) * h as f32)
                                 .clamp(0., (h - 1) as f32)
                                 as u32;
+                            // 3D 表面是最终 RGB 像素，直接覆盖目标；不走二维 source alpha 混合。
                             canvas.pixels[y as usize * width as usize + x as usize] =
                                 surface[v as usize * w as usize + u as usize];
                         }
                     }
                 }
                 DrawCommand::PushClip(rect) => {
+                    // 先保存旧裁剪，再求交；嵌套 PushClip 只能收窄，矩形分离时宽高归零。
                     clips.push(canvas.clip);
                     let x = canvas.clip.x.max(rect.x);
                     let y = canvas.clip.y.max(rect.y);
@@ -120,6 +130,7 @@ impl SoftwareRenderer {
                     );
                 }
                 DrawCommand::PopClip => {
+                    // 多余 PopClip 在当前实现中被忽略；合法列表仍应由生成层保证配对。
                     if let Some(clip) = clips.pop() {
                         canvas.clip = clip;
                     }
@@ -154,7 +165,7 @@ impl SoftwareRenderer {
     }
 }
 
-/// 借用目标像素切片并维护当前裁剪，所有像素写入都受该上下文限制。
+/// 借用目标像素切片并维护当前裁剪；图形/文字受裁剪，Clear 明确填满整个目标。
 struct Canvas<'a> {
     pixels: &'a mut [u32],
     width: u32,
@@ -163,14 +174,16 @@ struct Canvas<'a> {
 }
 
 impl Canvas<'_> {
-    /// 清空本对象维护的当前内容或缓存，后续状态由调用方重新建立。
+    /// 用不透明 RGB 填满目标切片；此命令忽略当前裁剪和输入颜色 alpha。
     fn clear(&mut self, color: Color) {
+        // Clear 填整个提供的目标切片，不受当前 clip 约束；pack 忽略 alpha，清屏色作为不透明 RGB。
         self.pixels.fill(pack(color));
     }
 
     /// 只遍历裁剪后的矩形像素，按圆角覆盖决定填充区域。
     fn fill_rounded_rect(&mut self, rect: Rect, radius: f32, color: Color) {
         let bounds = self.clamped_bounds(rect);
+        // 半径钳到非负且不超过半宽/半高；后续用像素中心判定圆角内外，不做边缘面积覆盖积分。
         let radius = radius.max(0.0).min(rect.width / 2.0).min(rect.height / 2.0);
         for y in bounds.1..bounds.3 {
             for x in bounds.0..bounds.2 {
@@ -184,6 +197,7 @@ impl Canvas<'_> {
     /// 用外轮廓与内轮廓的差绘制边框，避免把边框当成整个矩形填充。
     fn stroke_rounded_rect(&mut self, rect: Rect, radius: f32, width: f32, color: Color) {
         let bounds = self.clamped_bounds(rect);
+        // 描边请求先至少一单位再限制为半宽/半高；inner 从四边缩入，最终绘制外轮廓减内轮廓。
         let width = width.max(1.0).min(rect.width / 2.0).min(rect.height / 2.0);
         let outer_radius = radius.max(0.0).min(rect.width / 2.0).min(rect.height / 2.0);
         let inner = Rect::new(
@@ -209,6 +223,7 @@ impl Canvas<'_> {
 
     /// 把文字原点转换为局部裁剪区域，交给有界字形绘制，再混合到目标缓冲。
     fn draw_text(&mut self, origin: Point, value: &str, style: TextStyle, color: Color) {
+        // 将文字原点对齐整数像素；转换 clip 到字形局部空间，回调再加原点写回目标。
         let x = origin.x.round() as i32;
         let y = origin.y.round() as i32;
         let clip = Rect::new(
@@ -227,6 +242,7 @@ impl Canvas<'_> {
         if rect.width <= 0.0 || rect.height <= 0.0 {
             return;
         }
+        // 段落文本临时收窄 clip 到文本框；下方调用完成后恢复 old，后续命令不能继承段落私有裁剪。
         let old = self.clip;
         let x = old.x.max(rect.x);
         let y = old.y.max(rect.y);
@@ -248,6 +264,7 @@ impl Canvas<'_> {
             value,
             style,
             color,
+            // 换行按完整段落宽度排版，而不是按被祖先裁剪后剩余的可见宽度重新排版。
             Some(rect.width),
             clip,
             |dx, dy, pixel| self.blend_pixel(left + dx, top + dy, pixel),
@@ -257,6 +274,7 @@ impl Canvas<'_> {
 
     /// 把连续矩形转换成目标缓冲内的整数像素范围，避免在不可见区域进行光栅循环。
     fn clamped_bounds(&self, rect: Rect) -> (i32, i32, i32, i32) {
+        // 左/上 floor，右/下 ceil 形成保守循环范围；blend_pixel 还会按当前 clip 检查实际整数像素。
         (
             rect.x.max(self.clip.x).max(0.0).floor() as i32,
             rect.y.max(self.clip.y).max(0.0).floor() as i32,
@@ -273,6 +291,7 @@ impl Canvas<'_> {
 
     /// 在画布与当前裁剪范围内进行透明度混合，防止文字/图形写出目标缓冲。
     fn blend_pixel(&mut self, x: i32, y: i32, source: Color) {
+        // 拒绝画布外、裁剪外与全透明像素；只有通过后才计算线性下标，避免负坐标转 usize。
         if x < 0
             || y < 0
             || x >= self.width as i32
@@ -287,6 +306,7 @@ impl Canvas<'_> {
         }
 
         let index = y as usize * self.width as usize + x as usize;
+        // 全不透明像素可直接打包覆盖，省去目的通道解码与乘除法。
         if source.alpha == 255 {
             self.pixels[index] = pack(source);
             return;
@@ -296,6 +316,7 @@ impl Canvas<'_> {
         let dst_red = (destination >> 16) & 0xff;
         let dst_green = (destination >> 8) & 0xff;
         let dst_blue = destination & 0xff;
+        // 非预乘源颜色按 source*alpha + destination*(1-alpha) 合成，目标不存 alpha，逐通道整除 255。
         let alpha = source.alpha as u32;
         let inverse = 255 - alpha;
         let red = (source.red as u32 * alpha + dst_red * inverse) / 255;
@@ -317,6 +338,8 @@ fn rounded_rect_contains(rect: Rect, radius: f32, x: f32, y: f32) -> bool {
     // Clamp in local coordinates: adding a large origin to a shrinking tab's
     // half-width can otherwise round the lower bound above the upper bound.
     let radius = radius.min(rect.width / 2.0).min(rect.height / 2.0);
+    // 在局部坐标钳到圆角中心可达矩形，距离向量对应最近角圆心；中心带距离为零。
+    // 先减大原点可降低浮点舍入导致 clamp 上下界反转的风险。
     let local_x = x - rect.x;
     let local_y = y - rect.y;
     let dx = local_x - local_x.clamp(radius, rect.width - radius);
@@ -326,6 +349,7 @@ fn rounded_rect_contains(rect: Rect, radius: f32, x: f32, y: f32) -> bool {
 
 /// 将颜色通道打包成目标缓冲的整数像素表示。
 fn pack(color: Color) -> u32 {
+    // 像素格式为 0x00RRGGBB，高字节不存透明度；透明度已在混合阶段折算进 RGB。
     (color.red as u32) << 16 | (color.green as u32) << 8 | color.blue as u32
 }
 
@@ -334,6 +358,7 @@ mod tests {
     use super::*;
 
     #[test]
+    /// 画长文字进入嵌套裁剪，逐像素检查多行与裁剪交集；PopClip后的蓝矩形验证后续命令不沿用旧clip。
     fn wrapped_text_uses_multiple_lines_respects_nested_clips_and_restores_the_clip() {
         let mut list = DisplayList::default();
         list.push(DrawCommand::Clear(Color::rgb(255, 255, 255)));
@@ -358,6 +383,7 @@ mod tests {
         });
         let mut pixels = vec![0; 80 * 60];
         SoftwareRenderer::render(&list, &mut pixels, 80, 60).unwrap();
+        // 确认文字确实换成多行且每个非背景文字像素都落在嵌套裁剪交集内，蓝色矩形验证裁剪已恢复。
         let mut second_line = false;
         for y in 0..60 {
             for x in 0..80 {
@@ -373,6 +399,7 @@ mod tests {
     }
 
     #[test]
+    /// 在黑底4x4缓冲画2x2红矩形，核对内部像素变红、外部仍黑，覆盖最小坐标/打包路径。
     fn renderer_changes_pixels_inside_a_rectangle() {
         let mut list = DisplayList::default();
         list.push(DrawCommand::Clear(Color::rgb(0, 0, 0)));
@@ -388,6 +415,7 @@ mod tests {
     }
 
     #[test]
+    /// 半透明白字叠黑底必须含中间抗锯齿值且通道不超128；alpha=0的文字完全不改像素。
     fn text_edges_are_antialiased_and_respect_opacity() {
         let mut list = DisplayList::default();
         list.push(DrawCommand::Clear(Color::rgb(0, 0, 0)));
@@ -400,6 +428,7 @@ mod tests {
         let mut pixels = vec![0; 256 * 48];
         SoftwareRenderer::render(&list, &mut pixels, 256, 48).unwrap();
         assert!(pixels.iter().any(|pixel| *pixel > 0));
+        // 白字 alpha=128 叠黑底，任何通道都不应超过 128；中间覆盖值证明字形边缘仍有抗锯齿。
         assert!(pixels.iter().all(|pixel| (pixel & 255) <= 128));
         assert!(pixels.iter().any(|pixel| (1..128).contains(&(pixel & 255))));
 

src/render/source_hit.rs

@@ -13,13 +13,14 @@ use endor_core::{
 /// 验证 hitTest 返回的是 Bool，避免把任意真值隐式当成命中。
 struct Boolean;
 impl NativeCallable for Boolean {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 接收 hitTest 返回的唯一值，交给 invoke 严格检查 Bool。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(1))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 只接受真正的 Bool 并原样返回；数字或对象不能以宿主真值规则替代源协议契约。
     fn invoke(&self, _: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
+        // 协议要求明确 Bool；拒绝数字、对象等“真值”，使用户实现错误立即暴露。
         let [Value::Bool(value)] = args else {
             return Err(VmError::InvalidArgument("hitTest must return Bool"));
         };
@@ -30,13 +31,14 @@ impl NativeCallable for Boolean {
 /// 比较按下与释放的选择结果，只有同一目标才能继续点击分发。
 struct SameTarget;
 impl NativeCallable for SameTarget {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 接收按下与释放两次命中选择的结果。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(2))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 仅当两结果为同一 Mount 对象才返回目标，否则返回 Nil；共享 Block 的不同出现位置也不能合成点击。
     fn invoke(&self, _: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
+        // 比较的是实际出现 Mount 的身份；即使共享同一个 Block，不同出现之间拖动也不构成点击。
         let value = match args {
             [Value::Object(first), Value::Object(second)] if first == second => {
                 Value::Object(*first)
@@ -53,6 +55,7 @@ fn code(
     constants: Vec<Value>,
     layout: CodeLayout,
 ) -> Result<ObjectRef, VmError> {
+    // 校验并编码指令，同时设置诊断位置；独立空 globals 避免驱动依赖业务全局命名空间。
     let code = EndorCode::from_instructions(&instructions, constants, layout)?.with_location(
         "<pointer hitTest>",
         "<tessera>",
@@ -76,11 +79,13 @@ fn selector(
     ))?;
     let mut instructions = Vec::new();
     let mut constants = vec![Value::Object(validate)];
+    // 候选按绘制顺序提供，逆序使最上层先参与测试；弱引用失效视为过期输入错误。
     for weak in candidates.iter().rev() {
         let mount = cx
             .upgrade(*weak)?
             .ok_or(VmError::InvalidArgument("pointer Mount expired"))?;
         let target = cx.store().payload::<Mount>(mount, "Mount")?.clone();
+        // 先排除已卸载、非交互和几何不命中的出现，避免为明显无效候选构造源调用。
         if !target.mounted
             || !target.geometry.interactive
             || !target
@@ -91,14 +96,17 @@ fn selector(
         }
         let geometry = &target.geometry;
         let point = crate::geometry::Point::new(point[0], point[1]);
+        // 把投影坐标反算到节点逻辑空间；不可逆/无效投影没有可用于 hitTest 的局部坐标。
         let Some(point) = geometry.logical_point(point) else {
             continue;
         };
+        // 源 Point 以节点左上为原点；这里再次验证范围，避免变换后的点落到节点盒子之外。
         let x = point.x - geometry.x;
         let y = point.y - geometry.y;
         if x < 0.0 || y < 0.0 || x > geometry.width || y > geometry.height {
             continue;
         }
+        // 依据真实 Block 的名义类型解析 hitTest，不用原生矩形命中替代源协议。
         let definition = cx
             .store()
             .type_of(target.block)?
@@ -111,6 +119,7 @@ fn selector(
         attach_desktop_type(cx, local, "Point", desktop)?;
         cx.set_attr(local, "x", Value::Number((x as f64).into()))?;
         cx.set_attr(local, "y", Value::Number((y as f64).into()))?;
+        // 每个候选占四个常量：协议函数、Block、Mount、局部 Point；索引供下面字节码复用。
         let start = constants.len() as u32;
         constants.extend([
             Value::Object(function),
@@ -118,12 +127,16 @@ fn selector(
             Value::Object(mount),
             Value::Object(local),
         ]);
+        // false 分支只跳过“加载本 Mount 并返回”两条指令。按编码宽度计算，
+        // 常量索引大到需要扩展操作数时仍能跳到下一候选。
         let skip = (Instruction::encode_all(&[
             Instruction::new(Opcode::LoadConst, start + 2),
             Instruction::simple(Opcode::ReturnValue),
         ])?
         .len()
             / 2) as u32;
+        // 先调用 hitTest(block, mount, local)，再把结果传给 validate。
+        // true 立即返回本 Mount；false 继续下一个候选，实现透明区域向下穿透。
         instructions.extend([
             Instruction::new(Opcode::LoadConst, 0),
             Instruction::simple(Opcode::PushNull),
@@ -139,6 +152,7 @@ fn selector(
             Instruction::simple(Opcode::ReturnValue),
         ]);
     }
+    // 所有候选均未命中时显式返回 Nil；不会把最后一个 false 当作选择结果。
     let end = constants.len() as u32;
     constants.push(Value::Nil);
     instructions.extend([
@@ -156,13 +170,14 @@ struct Prepare {
     desktop: ObjectRef,
 }
 impl NativeCallable for Prepare {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 候选、按下点和释放点已保存于适配器，无需外部实参。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 为按下/释放各建立只读选择器，把两次结果放入同一 VM 调用序列，再交 SameTarget 比较实际出现身份。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
+        // 按下和释放分别构造选择器，但都在本次只读执行内调用，使用同一预算域。
         let down = selector(cx, &self.candidates, self.press, self.desktop)?;
         let up = selector(cx, &self.candidates, self.release, self.desktop)?;
         let compare = cx.allocate(ContextNativeFunction::new(
@@ -170,6 +185,7 @@ impl NativeCallable for Prepare {
             SameTarget,
             vec![],
         ))?;
+        // 两次选择结果先存入局部槽，再作为两个实参交给 SameTarget；局部槽也保留中间结果生命周期。
         let instructions = vec![
             Instruction::new(Opcode::LoadConst, 0),
             Instruction::simple(Opcode::PushNull),
@@ -199,6 +215,7 @@ impl NativeCallable for Prepare {
                 ..CodeLayout::default()
             },
         )?;
+        // 把执行权交回 VM 运行驱动，不在宿主里递归开启另一次 VM 调用。
         Ok(NativeResult::Invoke {
             function: driver,
             arguments: vec![],
@@ -206,7 +223,7 @@ impl NativeCallable for Prepare {
     }
 }
 /// Returned Mount owns one root. No-hit and mismatched targets return None.
-/// 解析输入所指向的实际目标，避免把包装身份与底层数据混淆。
+/// 在一次有界只读调用中分别选择按下与释放目标；仅二者为同一 Mount 时返回其拥有根。
 pub fn resolve(
     vm: &mut Vm,
     desktop: ObjectRef,
@@ -214,6 +231,7 @@ pub fn resolve(
     press: [f32; 2],
     release: [f32; 2],
 ) -> anyhow::Result<Option<ObjectRef>> {
+    // 显式 captures 保活 desktop；候选列表仍是弱引用，不因等待选择而保活全部旧 Mount。
     let prepare = vm.allocate(ContextNativeFunction::new(
         "prepare pointer hitTest",
         Prepare {
@@ -232,9 +250,11 @@ pub fn resolve(
             max_instructions: 1_000_000,
         },
     );
+    // 先保存调用结果再释放入口根，因此 VM 返回错误时也能完成入口清理。
     vm.release(prepare)?;
     let (value, _) = result.map_err(|error| crate::endor_host::runtime_error(vm, error))?;
     match value {
+        // 成功返回的 Mount 仍拥有一次根引用，交由调用方使用并释放；None 不转移任何对象根。
         Value::Object(mount) => Ok(Some(mount)),
         Value::Nil => Ok(None),
         value => {

src/render/source_layout.rs

@@ -40,6 +40,7 @@ fn desktop_type_registry(cx: &NativeContext<'_>, desktop: ObjectRef) -> Result<O
 #[derive(Debug, Clone)]
 /// 一次源测量的缓存输入、输出和真实读取依赖；不同约束或依赖版本不能复用。
 struct Measurement {
+    // 缓存记录借用的业务身份及方法身份，与子测量、约束和依赖版本共同决定复用资格，不增加托管根。
     owner: ObjectRef,
     method: ObjectRef,
     children: Vec<Size>,
@@ -79,6 +80,7 @@ impl Cache {
 #[derive(Debug)]
 /// 一个等待源测量返回的收集项，记录本次方法、约束和子项输入。
 struct Pending {
+    // 只读子调用的精确读取跟踪区间 token，由 Step 开始、Collect 在结果解码后结束。
     token: usize,
     owner: ObjectRef,
     method: ObjectRef,
@@ -102,6 +104,7 @@ struct Plan {
     pending: Vec<Option<Pending>>,
     constraints: Vec<[f32; 4]>,
     // Source-arranged dimensions remain exact for this solve, not business state.
+    // 每个出现两个轴的显式分配，Some 形成精确 min=max 约束；不是可写业务尺寸属性。
     allocations: Vec<[Option<f32>; 2]>,
     custom_arrange: Vec<bool>,
     native_arrange: Vec<bool>,
@@ -137,12 +140,12 @@ struct Step {
     desktop: ObjectRef,
 }
 impl NativeCallable for Step {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 单个布局步骤所需 Mount、阶段和计划已保存，实际调用无参。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 解析当前实际 measure/arrange 实现，决定原生快速路径或源调用，准备本节点输入及依赖收集，避免跳过源覆盖。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
         let mount = cx.store().payload::<Mount>(self.mount, "Mount")?.clone();
         let definition = cx
@@ -153,6 +156,7 @@ impl NativeCallable for Step {
             .store()
             .lookup_method(definition, self.phase.method())?
             .ok_or(invalid("missing layout method"))?;
+        // 判断真实宿主实现而非方法名；源覆盖即使调用基类也不能整体绕过其用户逻辑。
         let intrinsic = crate::native_visual::is_intrinsic(
             cx.store(),
             method,
@@ -169,6 +173,7 @@ impl NativeCallable for Step {
                 .iter()
                 .map(|child| plan.sizes[*child])
                 .collect::<Vec<_>>();
+            // preferred 优先取本轮最初测量值，不能将上一轮 flex 分配当作新的自然基准，造成累计漂移。
             let preferred = plan.children[self.index]
                 .iter()
                 .map(|child| plan.preferred[*child].unwrap_or(plan.sizes[*child]))
@@ -181,6 +186,7 @@ impl NativeCallable for Step {
             if matches!(self.phase, Phase::Measure) {
                 plan.custom_measure[self.index] = !intrinsic;
             }
+            // 原生 measure 直接计算避免源 VM 调用；源 measure 尝试按 Mount、owner、方法、子尺寸、约束和读取版本复用。
             let native_size = if matches!(self.phase, Phase::Measure) && intrinsic {
                 let constraints = plan.constraints[self.index];
                 Some(
@@ -213,6 +219,7 @@ impl NativeCallable for Step {
                                     })
                             })
                             .map(|entry| entry.size);
+                    // 命中无需再打开读取跟踪；未命中保存 Pending 元信息，等待真正源调用结果返回才建立缓存。
                     if let Some(size) = cached {
                         plan.cache.hits += 1;
                         Some(size)
@@ -236,10 +243,12 @@ impl NativeCallable for Step {
             if matches!(self.phase, Phase::Arrange) {
                 plan.runtime.arranged += 1;
                 plan.native_arrange[self.index] = intrinsic;
+                // 原生 arrange 若需要分配 flex/stretch 也视作需显式记录子分配，参与后面的约束收敛。
                 plan.custom_arrange[self.index] = !intrinsic || node.allocates_children();
             }
             (node, children, preferred, bounds, native_size)
         };
+        // 先安装本轮节点、子测量和临时 bounds，让源代码调用基类或 Mount.bounds 时观察当前阶段数据。
         let context = mount.layout.ok_or(invalid("missing pre-layout context"))?;
         {
             let mut context = context
@@ -250,6 +259,7 @@ impl NativeCallable for Step {
             context.preferred = preferred;
             context.bounds = bounds;
         }
+        // 原生结果或缓存命中都包装为同一名义 MeasureResult，后续 Collect 无需区分来源。
         if let Some(size) = native_size {
             return Ok(NativeResult::Return(Value::Object(record(
                 cx,
@@ -294,6 +304,7 @@ impl NativeCallable for Step {
             }
         };
         if matches!(self.phase, Phase::Measure) {
+            // 输入记录初始化完成后再开始子调用跟踪；Collect 解码返回值也在区间内，覆盖复用旧结果对象的字段读取。
             let token = cx.store().begin_read_tracking()?;
             self.plan
                 .lock()
@@ -322,13 +333,14 @@ struct Collect {
     desktop: ObjectRef,
 }
 impl NativeCallable for Collect {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 接收一次 measure/arrange 返回的托管结果，按当前 phase 解码。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(1))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 结束当前测量读跟踪并解码结果，验证尺寸或完整子槽安排，再更新计划与可复用测量依赖。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
+        // 取走本节点待收集状态，确保每个跟踪区间只结束一次；arrange 不建立测量缓存项。
         let pending = if matches!(self.phase, Phase::Measure) {
             self.plan
                 .lock()
@@ -345,6 +357,7 @@ impl NativeCallable for Collect {
             Phase::Measure => "MeasureResult",
             Phase::Arrange => "Arrangement",
         };
+        // 先验证 MeasureResult/Arrangement 名义类型，再解码字段，拒绝只有同名字段的普通对象。
         if !cx
             .store()
             .is_instance(*result, desktop_type(cx.store(), expected, self.desktop)?)?
@@ -357,6 +370,7 @@ impl NativeCallable for Collect {
             .map_err(|_| invalid("layout plan poisoned"))?;
         match self.phase {
             Phase::Measure => {
+                // 源返回宽高先检查非负有限，再钳制到本出现约束，不允许结果绕过父级分配。
                 let size = layout::constrained(
                     Size {
                         width: number(cx, *result, "width", false)?,
@@ -367,6 +381,7 @@ impl NativeCallable for Collect {
                 // Native shrink-to-content containers keep their existing input
                 // policy. Only a source measurement that differs from the native
                 // result supplies an additional content constraint.
+                // 源容器测量若不同于默认原生结果，将相应轴记成额外内容上限；后续碰巧相等也不撤销本轮已选限制。
                 if plan.custom_measure[self.index] && !plan.children[self.index].is_empty() {
                     let children = plan.children[self.index]
                         .iter()
@@ -398,6 +413,7 @@ impl NativeCallable for Collect {
                     })
                     .transpose()?;
                 if let Some((pending, reads)) = tracked {
+                    // 若观察了 Mount 内容/几何等不稳定宿主状态，无法证明跨轮可复用，保守地删除该测量缓存。
                     let mut volatile = false;
                     let registry = desktop_type_registry(cx, self.desktop)?;
                     for read in &reads.accesses {
@@ -429,6 +445,7 @@ impl NativeCallable for Collect {
                                     .into_iter()
                                     .filter(|dependency| {
                                         let object = dependency.object();
+                                        // 缓存只保留仍存在的业务依赖，去除 desktop、注册表与 Mount；避免宿主提交几何自己反过来使缓存失效。
                                         object != self.desktop
                                             && object != registry
                                             && cx.store().object(object).is_ok_and(|value| {
@@ -440,6 +457,7 @@ impl NativeCallable for Collect {
                         );
                     }
                 }
+                // 仅首次填写 preferred；sizes 每轮更新，根测量直接给本轮根 bounds，安排才能从根向下展开。
                 plan.preferred[self.index].get_or_insert(size);
                 plan.sizes[self.index] = size;
                 if self.index == 0 {
@@ -452,11 +470,13 @@ impl NativeCallable for Collect {
                 };
                 let items = object_list::items(cx.store(), list)?;
                 let children = plan.children[self.index].clone();
+                // 安排结果必须覆盖全部孩子，不能省略零尺寸项；结合下面 slot 唯一检查保证逐一对应。
                 if items.len() != children.len() {
                     return Err(invalid(
                         "Arrangement must assign every child slot exactly once",
                     ));
                 }
+                // 按稳定 slot 找实际孩子下标，不要求源返回列表与孩子原顺序一致；外来或重复 slot 都拒绝。
                 let slots: HashMap<_, _> = plan.nodes[self.index]
                     .slots
                     .iter()
@@ -496,6 +516,7 @@ impl NativeCallable for Collect {
                         return Err(invalid("arrangement bounds exceed limits"));
                     }
                     let child = children[position];
+                    // 源安排或原生弹性分配的差异保留为显式轴分配，下一轮测量使用精确尺寸，确保文字按实际宽度重排。
                     if plan.custom_arrange[self.index] {
                         if plan.native_arrange[self.index]
                             && let Some(main) = layout::main_axis(&plan.nodes[self.index])
@@ -526,11 +547,11 @@ struct Settle {
     mounts: Arc<[WeakObjectRef]>,
 }
 impl NativeCallable for Settle {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 一轮测量/排列完成后无参进入收敛检查。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 由新 bounds 推导下一轮约束与自然尺寸，比较完整布局状态；稳定则结束，循环状态报错，否则继续同帧求解。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
         let repeat = {
             let mut plan = self
@@ -538,6 +559,7 @@ impl NativeCallable for Settle {
                 .lock()
                 .map_err(|_| invalid("layout plan poisoned"))?;
             plan.runtime.settle_passes += 1;
+            // 安排完成后按最终 bounds 从父到子推导下一轮约束，测量限制和源分配可反向影响换行高度。
             let mut next = plan.constraints.clone();
             for index in 0..plan.nodes.len() {
                 let children = plan.children[index].clone();
@@ -570,6 +592,7 @@ impl NativeCallable for Settle {
                         child_index,
                     );
                     let mut constraints = natural;
+                    // 显式轴分配同时设置最小与最大，区别于仅给孩子一个可自由缩小的最大可用宽度。
                     if let Some(width) = plan.allocations[child][0] {
                         constraints[0] = width;
                         constraints[2] = width;
@@ -580,6 +603,7 @@ impl NativeCallable for Settle {
                     }
                     if let Some(main) = layout::main_axis(&plan.nodes[index]) {
                         let cross = 1 - main;
+                        // 交叉轴变化可能改变换行及主轴自然高度，清 preferred 让其重新测量；原生派生主轴分配也需暂时撤销。
                         if constraints[cross] != plan.constraints[child][cross]
                             || constraints[cross + 2] != plan.constraints[child][cross + 2]
                         {
@@ -600,6 +624,7 @@ impl NativeCallable for Settle {
                 }
             }
             let mut state = Vec::with_capacity(plan.nodes.len() * 14);
+            // 把约束、实测、bounds、分配和首选值编码成几何状态，统一 +0/-0，避免仅符号位差异造成假不收敛。
             let bits = |value: f32| if value == 0.0 { 0 } else { value.to_bits() };
             for (index, constraints) in next.iter().enumerate() {
                 state.extend(constraints.iter().copied().map(bits));
@@ -624,6 +649,7 @@ impl NativeCallable for Settle {
                     state.extend([0, 0]);
                 }
             }
+            // 相邻两轮状态和约束均相同才停止；非相邻重复则是振荡环，不能把循环误当作稳定布局。
             if plan.previous.as_ref() == Some(&state) && plan.constraints == next {
                 false
             } else {
@@ -632,6 +658,7 @@ impl NativeCallable for Settle {
                 }
                 plan.previous = Some(state);
                 plan.constraints = next;
+                // 需要重算时清全部 bounds；下一轮测量不能访问上轮安排产生的陈旧几何。
                 plan.bounds.fill(None);
                 true
             }
@@ -660,11 +687,11 @@ struct Prepare {
     desktop: ObjectRef,
 }
 impl NativeCallable for Prepare {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 布局驱动的零参入口，Mount 列表/desktop/计划已由调用方捕获。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 建立按出现位置推进的 Advance 和固定字节码循环，保持同一 VM 预算，避免首次让出前创建整树临时调用对象。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
         let advance = cx.allocate(ContextNativeFunction::new(
             "next layout occurrence",
@@ -693,13 +720,14 @@ struct Advance {
     next: Mutex<usize>,
 }
 impl NativeCallable for Advance {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 由共享布局循环无参调用，游标表示本轮测量/排列的位置。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 按游标安排自底向上 measure 与自顶向下 arrange，短锁结束后才创建/执行当前节点调用，末尾进入收敛检查。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
         let count = self.mounts.len();
+        // 游标取值/递增只在短锁内完成，不能持锁执行源协议，否则源调用基类会再次访问同一 Plan。
         let position = {
             let mut next = self
                 .next
@@ -711,6 +739,7 @@ impl NativeCallable for Advance {
             }
             position
         };
+        // 每轮恰有 N 个逆序 measure 和 N 个正序 arrange，之后调用 Settle；需要重算时游标归零。
         if position == count * 2 {
             let settled = Settle {
                 plan: self.plan.clone(),
@@ -728,6 +757,7 @@ impl NativeCallable for Advance {
             }
             return Ok(NativeResult::Return(Value::Bool(repeat)));
         }
+        // nodes 是先序，逆序测量保证孩子先完成，正序安排保证父 bounds 已经分配到孩子。
         let (phase, index) = if position < count {
             (Phase::Measure, count - position - 1)
         } else {
@@ -736,6 +766,7 @@ impl NativeCallable for Advance {
         let mount = cx
             .upgrade(self.mounts[index])?
             .ok_or(invalid("layout Mount expired"))?;
+        // 只为当前出现建立 Step 与 collector，显式 captures 保活本次 Mount/desktop，避免一次分配整棵调用树。
         let step = cx.allocate(ContextNativeFunction::new(
             "layout step",
             Step {
@@ -757,6 +788,7 @@ impl NativeCallable for Advance {
             },
             vec![self.desktop],
         ))?;
+        // 执行一步并立即收集，再给外层 repeat_call 返回 true；各轮迭代共享原 VM 帧和预算。
         let function = crate::vm_sequence::collect_and_continue(
             cx,
             collector,
@@ -810,6 +842,7 @@ impl Work {
 
     /// 显式结束布局续体和只读域，释放本次尚未提交的临时根。
     pub fn cancel(self, vm: &mut Vm) -> Result<()> {
+        // 取消与释放入口根均先尝试，再依次传播错误；普通 Rust drop 无法替代 VM 只读域清理。
         let cancelled = vm.cancel_read_only_call();
         let released = vm.release(self.prepare);
         cancelled?;
@@ -864,9 +897,11 @@ pub fn start(
     cache.hits = 0;
     cache.misses = 0;
     let live: HashSet<_> = mounts.iter().copied().collect();
+    // 先删除不再出现在此结构中的测量项，防止已移除的弱 Mount 身份无限积累。
     cache.entries.retain(|mount, _| live.contains(mount));
     // Preserve the existing native measurement cache and avoid VM/result
     // allocation for small trees without custom layout methods. Contexts already exist.
+    // 扫描每个出现的实际 measure/arrange，实现全部为原生还不够，下面 flex/拉伸也会要求收敛驱动。
     let mut custom = false;
     for weak in &mounts {
         let mount = vm
@@ -900,16 +935,19 @@ pub fn start(
     }
     // Flex allocation can change text wrapping and ancestor measurements even
     // when every protocol method is native. Use the same settling driver.
+    // 仅小于等于64节点且无自定义/弹性分配的树走直接路径；大原生树仍经同一驱动以便分片让出。
     if !custom && nodes.len() <= NATIVE_FAST_PATH_MAX_NODES {
         cache.clear();
         let mut native = runtime.frame(&root)?;
         // Only the structural pass consumes a published version.
+        // 结构准备已经分配本次发布版本，快速完整测量不能再多消耗一个可见布局版本。
         native.layout_version = frame.layout_version;
         runtime.version = frame.layout_version;
         *frame = native;
         state.reads.clear();
         return Ok(Progress::Complete(state));
     }
+    // 帧结构、弱 Mount 和视觉节点必须同序同数量，否则按出现下标执行协议会把上下文接错。
     anyhow::ensure!(
         nodes.len() == mounts.len() && nodes.len() == frame.mounts.len(),
         "layout structure does not match Mount contexts"
@@ -926,6 +964,7 @@ pub fn start(
             children[indices[&parent]].push(index);
         }
     }
+    // 从根向下初始化约束，之后每轮由 Settle 结合真实父分配细化；初始值不是最终精确几何。
     let mut constraints = vec![runtime.root_constraints(); nodes.len()];
     for index in 0..nodes.len() {
         for (child_index, child) in children[index].iter().enumerate() {
@@ -938,6 +977,7 @@ pub fn start(
         }
     }
     let count = nodes.len();
+    // 把运行时/缓存克隆进未发布 Plan，失败或取消时上层可以丢弃派生求解结果而不提交半帧。
     let plan = Arc::new(Mutex::new(Plan {
         sizes: vec![Size::default(); nodes.len()],
         preferred: vec![None; nodes.len()],
@@ -973,6 +1013,7 @@ pub fn start(
         desktop,
         slices: 1,
     };
+    // 一次有界只读调用跨所有节点与收敛轮次；slice 只控制让出量，总指令预算仍共享一百万。
     let progress = vm.start_read_only_call(
         prepare,
         &[],
@@ -992,6 +1033,7 @@ fn finish(
     value: Value,
     reads: Vec<endor_core::ReadDependency>,
 ) -> Result<Progress> {
+    // 驱动返回值仅为控制流结果，先释放；真正结果保存在原生 Plan，而非返回值中的第二份业务图。
     vm.release_value(value)?;
     let mut plan = work
         .plan
@@ -999,6 +1041,7 @@ fn finish(
         .map_err(|_| anyhow::anyhow!("layout plan poisoned"))?;
     plan.runtime.slices = work.slices;
     let frame = &mut work.state.frame;
+    // 用最终收敛 bounds 更新 frame 的各出现；这里只生成默认内容命令，后续投影/源 paint 还会重建完整绘制表。
     frame.commands.clear();
     for (index, mount) in frame.mounts.iter_mut().enumerate() {
         let [x, y, width, height] =
@@ -1016,6 +1059,7 @@ fn finish(
     }
     work.state.runtime = plan.runtime.clone();
     work.state.cache = plan.cache.clone();
+    // 大原生树可能使用分片驱动但没有真正源读取，因此无需把宿主驱动读取当业务布局依赖发布。
     if !plan.custom {
         work.state.reads.clear();
         return Ok(Progress::Complete(work.state));

src/render/source_paint.rs

@@ -33,7 +33,7 @@ fn object(value: Value) -> Result<ObjectRef, VmError> {
         Err(invalid("paint must return managed objects"))
     }
 }
-/// 把当前源值或文本选择解码成此调用需要的文本表示。
+/// 读取指定命令字段并要求其值为 Text；不隐式字符串化其他类型。
 fn text(store: &ObjectStore, object: ObjectRef, name: &str) -> Result<String, VmError> {
     if let Value::Text(value) = store.get_attr(object, name)? {
         Ok(value)
@@ -46,6 +46,7 @@ fn number(store: &ObjectStore, object: ObjectRef, name: &str) -> Result<f32, VmE
     let Value::Number(value) = store.get_attr(object, name)? else {
         return Err(invalid("paint field must be a Number"));
     };
+    // x/y 允许负数以表达相对原点的绘制；其余长度必须非负。所有数值都必须有限且在尺寸预算内。
     let value = value
         .to_string()
         .parse::<f32>()
@@ -73,12 +74,14 @@ fn decode(
     command: ObjectRef,
     expected: ObjectRef,
 ) -> Result<RenderCommand, VmError> {
+    // 使用当前 desktop 注册的 PaintCommand 名义类型；字段形状相似的普通对象也不能冒充命令。
     if !store.is_instance(command, expected)? {
         return Err(invalid("paint commands must be PaintCommand instances"));
     }
     let x = number(store, command, "x")?;
     let y = number(store, command, "y")?;
     let kind = text(store, command, "kind")?;
+    // 3D 命令使用不可变场景视图，不读取颜色文本；其他命令的颜色由最终 validate 统一校验。
     let color = if kind == "scene3d" {
         String::new()
     } else {
@@ -86,6 +89,7 @@ fn decode(
     };
     let result = match kind.as_str() {
         "scene3d" => {
+            // 这里仅接受宿主生成的 PaintView payload，克隆原生 Arc，不把活动的 VM 场景图传到绘制线程。
             let snapshot = object(store.get_attr(command, "scene")?)?;
             RenderCommand::Scene3D {
                 x,
@@ -102,6 +106,7 @@ fn decode(
             let width = number(store, command, "width")?;
             let height = number(store, command, "height")?;
             let radius = number(store, command, "radius")?;
+            // 单项数值合法还不足以保证右/下边界合法；额外检查原点与尺寸相加后的范围。
             if x + width > MAX_DIMENSION as f32 || y + height > MAX_DIMENSION as f32 {
                 return Err(invalid("paint rectangle exceeds bounds"));
             }
@@ -128,9 +133,11 @@ fn decode(
         }
         "text" => {
             let size = number(store, command, "size")?;
+            // size 是离散文字等级而非任意像素字号，只接受 1 到 8 的整数。
             if size.fract() != 0.0 || !(1.0..=8.0).contains(&size) {
                 return Err(invalid("paint text size must be an integer from 1 to 8"));
             }
+            // 两个换行边界必须同时出现或同时缺失；只缺一个时传播属性错误，防止半定义文本框。
             let wrap_bounds = match (
                 store.get_attr(command, "wrapWidth"),
                 store.get_attr(command, "wrapHeight"),
@@ -153,6 +160,7 @@ fn decode(
         }
         _ => return Err(invalid("unsupported paint command kind")),
     };
+    // 变体字段解码后仍走统一命令校验，覆盖颜色格式、文本以及组合几何合法性。
     result
         .validate()
         .map_err(|_| invalid("invalid paint command geometry, text or color"))?;
@@ -162,7 +170,9 @@ fn decode(
 #[derive(Debug, Default)]
 /// 按出现 ID 收集已检查的源绘制覆盖，随后与原生默认命令合并。
 struct PaintOutput {
+    // 按出现 ID 收集覆盖；同一个业务 Block 在多个 Mount 中可产生不同绘制结果。
     commands: BTreeMap<u64, Vec<RenderCommand>>,
+    // 全轮源命令累计数，不能靠拆分多个源 DisplayList 绕过 10000 条总预算。
     count: usize,
 }
 type Output = Arc<Mutex<PaintOutput>>;
@@ -174,12 +184,12 @@ struct Collect {
     output: Output,
 }
 impl NativeCallable for Collect {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 接收当前出现位置 paint 的唯一 DisplayList 结果。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(1))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 验证返回名义类型并完整解码所有 PaintCommand，检查全轮命令预算后才把该出现位置结果写入输出表。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let [Value::Object(result)] = args else {
             return Err(invalid("paint must return a DisplayList"));
@@ -190,12 +200,14 @@ impl NativeCallable for Collect {
         )? {
             return Err(invalid("paint must return a DisplayList"));
         }
+        // 先验证外层 DisplayList，再取其受控 ObjectList；所有成员解码成功后才写入 output。
         let commands = object(cx.store().get_attr(*result, "commands")?)?;
         let expected = named_type(cx.store(), self.desktop, "PaintCommand")?;
         let commands = object_list::items(cx.store(), commands)?
             .iter()
             .map(|command| decode(cx.store(), *command, expected))
             .collect::<Result<Vec<_>, _>>()?;
+        // 仅收集结果时持锁，不在调用源 paint 期间持有结果锁；失败不会插入半个命令列表。
         let mut output = self
             .output
             .lock()
@@ -216,13 +228,14 @@ struct Prepare {
     output: Output,
 }
 impl NativeCallable for Prepare {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 零参数驱动入口，待绘制 Mount 和输出容器已保存在适配器。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 建立共享游标与固定外层字节码循环，让 VM 每轮只准备一个出现位置的 paint 调用。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
+        // 构造一个共享游标驱动；每轮只准备当前出现，避免一次保留所有出现的临时实参。
         let advance = cx.allocate(ContextNativeFunction::new(
             "next paint occurrence",
             Advance {
@@ -250,12 +263,13 @@ struct Advance {
     output: Output,
 }
 impl NativeCallable for Advance {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 由外层循环无参调用，下一出现位置由内部游标决定。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 短锁内取并推进游标，随后验证/准备当前 Mount 的方法与几何；用临时调用链收集结果，完成后才进入下一位置。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
+        // 锁只保护取游标与递增；离开此块后释放锁，再做 VM 分配和源调用。
         let occurrence = {
             let mut next = self
                 .next
@@ -265,6 +279,7 @@ impl NativeCallable for Advance {
             *next += usize::from(occurrence.is_some());
             occurrence
         };
+        // false 是 repeat_call 的停止信号；有出现时即使跳过原生方法也返回 true 继续遍历。
         let Some((id, weak)) = occurrence else {
             return Ok(NativeResult::Return(Value::Bool(false)));
         };
@@ -283,9 +298,11 @@ impl NativeCallable for Advance {
             .store()
             .lookup_method(definition, "paint")?
             .ok_or(invalid("missing paint method"))?;
+        // 原生默认 paint 留给 finish 生成；仅执行实际覆盖的源方法，避免重复绘制同一出现。
         if crate::native_visual::is_intrinsic(cx.store(), function, "paint", self.desktop)? {
             return Ok(NativeResult::Return(Value::Bool(true)));
         }
+        // 把已提交 Mount 几何封装为本轮临时 Bounds；新分配参数可初始化，业务模型仍处于只读域。
         let bounds = cx.new_object()?;
         attach_desktop_type(cx, bounds, "Bounds", self.desktop)?;
         for (name, value) in [
@@ -296,6 +313,7 @@ impl NativeCallable for Advance {
         ] {
             cx.set_attr(bounds, name, Value::Number((value as f64).into()))?;
         }
+        // 收集器只捕获桌面根和当前出现 ID；输出是原生共享容器，不增加业务图的强引用。
         let collector = cx.allocate(ContextNativeFunction::new(
             "collect source paint",
             Collect {
@@ -305,6 +323,7 @@ impl NativeCallable for Advance {
             },
             vec![self.desktop],
         ))?;
+        // 辅助帧先执行 paint(block, mount, bounds)，收集其结果，再返回 true 推进外层游标。
         let function = crate::vm_sequence::collect_and_continue(
             cx,
             collector,
@@ -326,7 +345,9 @@ impl NativeCallable for Advance {
 
 /// 已经完成本阶段、但尚未由桥接层发布的派生结果，包含帧/缓存或真实读取依赖。
 pub struct Draft {
+    // 已经合并命令的原生帧；Draft 仍需桥接层提交，完成计算不等于发布成功。
     pub frame: Frame,
+    // 保留源绘制的业务读取依赖，供下次写入后判定是否必须重绘。
     pub reads: Vec<endor_core::ReadDependency>,
     pub slices: usize,
 }
@@ -342,6 +363,7 @@ pub enum Progress {
 /// 拥有未完成源调用及临时根的工作句柄；丢弃 Rust 值不能替代 VM 内的取消。
 pub struct Work {
     desktop: ObjectRef,
+    // 跨切片保留的入口根；完成或取消都必须在所属 VM 中显式释放。
     prepare: ObjectRef,
     output: Output,
     root: Option<Arc<UiNode>>,
@@ -352,6 +374,7 @@ pub struct Work {
 impl Work {
     /// 继续当前绘制续体，保留其先前收集的命令和所属窗口上下文。
     pub fn resume(mut self, vm: &mut Vm, slice: usize) -> Result<Progress> {
+        // 恢复保留原执行预算，slice 只决定本次让出的指令配额，不能重置整个绘制上限。
         self.slices += 1;
         let progress = vm.resume_read_only_call(slice);
         self.accept(vm, progress)
@@ -359,6 +382,7 @@ impl Work {
 
     /// 关闭未完成绘制续体并释放其临时根，不发布半完成命令列表。
     pub fn cancel(self, vm: &mut Vm) -> Result<()> {
+        // 先执行取消和 release 两个操作，再依次传播错误；取消失败也仍尝试释放入口根。
         let cancelled = vm.cancel_read_only_call();
         let released = vm.release(self.prepare);
         cancelled?;
@@ -373,6 +397,7 @@ impl Work {
         progress: Result<endor_core::ExecutionProgress, VmError>,
     ) -> Result<Progress> {
         match progress {
+            // 挂起时工作句柄继续持有 frame/output/prepare，不能发布部分输出。
             Ok(endor_core::ExecutionProgress::Pending { .. }) => {
                 Ok(Progress::Pending(Box::new(self)))
             }
@@ -381,11 +406,13 @@ impl Work {
                 dependencies,
                 ..
             }) => {
+                // VM 完成后先释放入口与驱动返回值，再读取纯原生收集结果；返回值本身不作为绘制命令。
                 vm.release(self.prepare)?;
                 vm.release_value(value)?;
                 finish(vm, self, dependencies)
             }
             Err(error) => {
+                // 趁 VM 诊断信息仍可用先生成错误，再取消只读执行并清理临时根。
                 let diagnostic = crate::endor_host::runtime_error(vm, error);
                 self.cancel(vm)?;
                 Err(diagnostic)
@@ -403,6 +430,7 @@ pub fn start(
     frame: Frame,
     slice: usize,
 ) -> Result<Progress> {
+    // 禁止零切片和嵌套只读/挂起调用；同一 VM 同时只能由一个续体驱动。
     anyhow::ensure!(slice > 0, "paint slice must be positive");
     anyhow::ensure!(
         !vm.has_suspended_call() && !vm.object_store().is_read_only(),
@@ -444,7 +472,9 @@ fn finish(vm: &mut Vm, mut work: Work, reads: Vec<endor_core::ReadDependency>) -
         .output
         .lock()
         .map_err(|_| anyhow::anyhow!("paint output poisoned"))?;
+    // 是否有源覆盖以 map 是否为空判断；源方法返回空命令列表也算覆盖，会抑制该出现的默认绘制。
     let native_only = output.commands.is_empty();
+    // 没有根时没有节点投影可合并，直接交回已有帧并清空绘制读取，不展开默认命令。
     if work.root.is_none() {
         return Ok(Progress::Complete(Box::new(Draft {
             frame: work.frame,
@@ -455,6 +485,7 @@ fn finish(vm: &mut Vm, mut work: Work, reads: Vec<endor_core::ReadDependency>) -
     let root = work.root.as_deref();
     let desktop = work.desktop;
     let frame = &mut work.frame;
+    // 建立 Block ID 到不可变节点的索引；最终合并顺序仍以 frame.mounts 为准，不能按 map 排序。
     let mut nodes = HashMap::new();
     let mut pending: Vec<_> = root.into_iter().collect();
     while let Some(node) = pending.pop() {
@@ -466,7 +497,9 @@ fn finish(vm: &mut Vm, mut work: Work, reads: Vec<endor_core::ReadDependency>) -
     let mut views = Vec::new();
     let mut owners = Vec::new();
     for mount in &frame.mounts {
+        // 记录本出现追加前的长度，用差值为新增命令同步扩展 clip/view/owner 三张平行表。
         let before = commands.len();
+        // 有源覆盖则使用其整个结果（包括空列表）；否则用节点和 Mount 几何生成原生默认命令。
         if let Some(custom) = output.commands.get(&mount.id) {
             commands.extend(custom.iter().cloned());
         } else {
@@ -486,6 +519,7 @@ fn finish(vm: &mut Vm, mut work: Work, reads: Vec<endor_core::ReadDependency>) -
         clips.extend(std::iter::repeat_n(mount.clip, commands.len() - before));
         views.extend(std::iter::repeat_n(mount.view, commands.len() - before));
         owners.extend(std::iter::repeat_n(mount.id, commands.len() - before));
+        // 混合原生与源命令后再检查总预算，前面的源输出预算不能覆盖这里新增的默认命令。
         if commands.len() > 10_000 {
             bail!("paint command budget exceeded");
         }
@@ -494,8 +528,11 @@ fn finish(vm: &mut Vm, mut work: Work, reads: Vec<endor_core::ReadDependency>) -
     frame.command_clips = clips;
     frame.command_views = views;
     frame.command_mounts = owners;
+    // 统一命令和投影元数据就绪后，再把世界 UI 面板装配进对应 3D 场景。
     crate::scene3d::panel::compose(frame)?;
     let registry = object(vm.get_attr(desktop, "types")?)?;
+    // 排除宿主桌面、类型注册表、Mount 以及已经死亡的临时身份，只保留业务读取。
+    // 纯原生帧不需要保留这次驱动的读取记录。
     let reads = reads
         .into_iter()
         .filter(|dependency| {

src/render/text.rs

@@ -67,9 +67,11 @@ pub struct TextSize {
 /// 文字整形缓存键，包含文本、样式和可选换行宽度。
 struct TextKey {
     value: String,
+    // 用浮点原始位模式做键，精确区分整形参数；不是把字号取整为 u32。
     font_size: u32,
     line_height: u32,
     family: TextFamily,
+    // None 表示不换行，Some 保存宽度的浮点位模式；同一文本不同宽度必须分开缓存。
     wrap_width: Option<u32>,
 }
 
@@ -85,15 +87,17 @@ struct TextEngine {
     code_family: Option<String>,
     swash: SwashCache,
     buffers: HashMap<TextKey, PreparedText>,
+    // 累计缓存文本的 UTF-8 字节数，只衡量源文本预算，并非 Buffer/字形的总内存。
     source_bytes: usize,
 }
 
 impl TextEngine {
-    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
+    /// 扫描系统字体，选择可用的界面/等宽字体偏好，并建立空整形和栅格缓存。
     fn new() -> Self {
         let mut fonts = FontSystem::new();
         // Select installed, readable families rather than assuming an OS font
         // name exists. COSMIC Text handles per-glyph fallback (including CJK).
+        // 按偏好顺序查询实际安装字体，找到第一个匹配名；找不到则由字体系统默认族处理。
         let choose = |choices: &[&str]| {
             choices.iter().find_map(|choice| {
                 fonts
@@ -135,6 +139,7 @@ impl TextEngine {
 
     /// 为文本、字体样式和可选换行宽度建立整形缓存，超过缓存预算先清理旧结果。
     fn prepare_width(&mut self, value: &str, style: TextStyle, wrap_width: Option<f32>) -> TextKey {
+        // 键包含全部排版输入；命中后测量与绘制都复用同一 Buffer，避免两套排版产生偏差。
         let key = TextKey {
             value: value.to_owned(),
             font_size: style.font_size.to_bits(),
@@ -146,6 +151,8 @@ impl TextEngine {
             return key;
         }
         // Cache recent shaped strings, without retaining every submitted source.
+        // 采用整批清空而非 LRU；新增前达到条数或文本字节阈值时释放旧整形结果。
+        // 单个超大文本仍会被整形，source_bytes 不是对单次输入长度的硬拒绝。
         if self.buffers.len() >= 256 || self.source_bytes + value.len() > 524_288 {
             self.buffers.clear();
             self.source_bytes = 0;
@@ -163,11 +170,13 @@ impl TextEngine {
             &mut self.fonts,
             Metrics::new(style.font_size, style.line_height),
         );
+        // 有限宽度使用按词优先、字形兜底的换行策略，兼容中文和无空格长标识符；无宽度则不换行。
         buffer.set_wrap(if wrap_width.is_some() {
             Wrap::WordOrGlyph
         } else {
             Wrap::None
         });
+        // 高度不设上限，让测量能得到所有换行后的完整内容高度，而非当前裁剪区域高度。
         buffer.set_size(wrap_width, None);
         buffer.set_text(
             value,
@@ -175,7 +184,9 @@ impl TextEngine {
             Shaping::Advanced,
             Some(Align::Left),
         );
+        // 整形采用高级脚本处理和左对齐；实际字形及回退由同一 FontSystem 决定。
         buffer.shape_until_scroll(&mut self.fonts, false);
+        // 即使空文本没有布局 run 也保留一行高度；宽度取各行最大值，高度取最下方行底。
         let mut size = TextSize {
             width: 0.0,
             height: style.line_height,
@@ -193,6 +204,7 @@ impl TextEngine {
 
 /// 取得全局受锁保护的字体/整形引擎；共享缓存不等于可以并行修改字体状态。
 fn engine() -> &'static Mutex<TextEngine> {
+    // 惰性创建全进程引擎；Mutex 同时保护字体库、整形缓存与栅格缓存，测量和绘制不能并发修改它。
     static ENGINE: OnceLock<Mutex<TextEngine>> = OnceLock::new();
     ENGINE.get_or_init(|| Mutex::new(TextEngine::new()))
 }
@@ -206,6 +218,7 @@ pub fn measure(value: &str, style: TextStyle) -> TextSize {
 
 /// 按可用宽度整形并测量多行高度，供布局与实际段落绘制共用。
 pub fn measure_wrapped(value: &str, style: TextStyle, width: f32) -> TextSize {
+    // 零或负可用宽度直接返回零宽与一行高，避免给整形器无效换行宽度。
     if width <= 0.0 {
         return TextSize {
             width: 0.0,
@@ -236,9 +249,12 @@ pub fn draw_clipped(
     {
         return;
     }
+    // 超大字号按比例降到最高 512 再栅格化；普通字号保持 1。
+    // 字体、行高和换行宽度一起缩小，后续用 1/lod 恢复目标几何比例。
     let lod = (512. / style.font_size).min(1.);
     let mut engine = engine().lock().expect("text engine lock");
     let key = engine.prepare_width(value, style.scaled(lod), width.map(|width| width * lod));
+    // 拆借可变字段以便在保留 Buffer 借用时访问字体和 Swash 缓存，不复制整形结果。
     let TextEngine {
         fonts,
         swash,
@@ -246,6 +262,7 @@ pub fn draw_clipped(
         ..
     } = &mut *engine;
     let buffer = &buffers[&key].buffer;
+    // 从已有 image_cache 统计位图字节；不包含整形 Buffer，也不含字体数据库本身。
     let mut cache_bytes: usize = swash
         .image_cache
         .values()
@@ -257,6 +274,7 @@ pub fn draw_clipped(
             let physical = glyph.physical((0., run.line_y), 1.);
             // Conservative font-sized guard includes bearings/overhangs. The
             // exact bitmap bounds below determine the actual visible pixels.
+            // 先用保守包围范围排除完全不可见字形，尽量避免生成裁剪区外的位图；精确边界由实际位图决定。
             let guard = glyph.font_size * 4. / lod;
             let gx = physical.x as f32 / lod;
             let gy = physical.y as f32 / lod;
@@ -267,10 +285,12 @@ pub fn draw_clipped(
             {
                 continue;
             }
+            // 达到条数或约 32 MiB 时替换整个 SwashCache，再生成当前可见字形；预算不因缩放无限增长。
             if swash.image_cache.len() >= 4096 || cache_bytes >= 33_554_432 {
                 *swash = SwashCache::new();
                 cache_bytes = 0;
             }
+            // 只对新生成的图像增加字节统计；缓存中的生成失败项由 None 跳过，不参与绘制。
             let cached = swash.image_cache.contains_key(&physical.cache_key);
             let Some(image) = swash.get_image(fonts, physical.cache_key) else {
                 continue;
@@ -278,22 +298,28 @@ pub fn draw_clipped(
             if !cached {
                 cache_bytes += image.data.len();
             }
+            // 位图 placement 包含字形 bearing。顶部使用基线减 top，再除 lod 转回目标绘制空间。
             let left = (physical.x + image.placement.left) as f32 / lod;
             let top = (physical.y - image.placement.top) as f32 / lod;
             let right = left + image.placement.width as f32 / lod;
             let bottom = top + image.placement.height as f32 / lod;
+            // 可选字形颜色覆盖 RGB，但透明度始终采用调用方的整体 alpha。彩色位图分支会使用位图自己的 RGB。
             let base = glyph.color_opt.map_or(color, |value| {
                 Color::rgba(value.r(), value.g(), value.b(), color.alpha)
             });
+            // 循环范围取位图与 clip 交集，只遍历最终可见像素；ceil 与半像素采样共同决定整数像素覆盖。
             for y in top.max(clip.y).ceil() as i32..bottom.min(clip.y + clip.height).ceil() as i32 {
                 for x in
                     left.max(clip.x).ceil() as i32..right.min(clip.x + clip.width).ceil() as i32
                 {
+                    // 把目标像素中心反映射到低分辨率位图，再钳制到最后一个有效像素，避免边缘采样越界。
                     let u = (((x as f32 + 0.5 - left) * lod) as u32)
                         .min(image.placement.width.saturating_sub(1));
                     let v = (((y as f32 + 0.5 - top) * lod) as u32)
                         .min(image.placement.height.saturating_sub(1));
                     let index = (v * image.placement.width + u) as usize;
+                    // 灰度 Mask 把覆盖率乘整体 alpha；Color 保留位图 RGB 并乘其 alpha。
+                    // SubpixelMask 不适用此软件合成路径，直接跳过。
                     let sample = match image.content {
                         cosmic_text::SwashContent::Mask => Color::rgba(
                             base.red,
@@ -312,6 +338,7 @@ pub fn draw_clipped(
                         }
                         cosmic_text::SwashContent::SubpixelMask => continue,
                     };
+                    // 只输出采样颜色，最终混合由调用方 pixel 完成；回调在引擎锁持有期间执行，不应重入文字引擎。
                     pixel(x, y, sample);
                 }
             }
@@ -326,6 +353,7 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
 
     // A source line may include a very large comment. Only shape a bounded
     // preview for the sidebar; the stored source and its AST spans stay intact.
+    // 仅预览截断至约 8 KiB 字素边界，不改保存的源码。单个超长字素也不能被拆开。
     let truncated = value.len() > 8192;
     let value = if truncated {
         let end = value
@@ -338,6 +366,7 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
     } else {
         value
     };
+    // 原文本未受预览截断且已能放下时原样返回；受截断文本即使较短也要追加省略号提示。
     if !truncated && measure(value, style).width <= width {
         return value.to_owned();
     }
@@ -345,15 +374,18 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
     if width <= 0.0 || measure(ellipsis, style).width > width {
         return String::new();
     }
+    // 保存每个完整字素簇的结束字节位置，后续切片不会拆开组合音标或连字 emoji。
     let ends: Vec<_> = value
         .grapheme_indices(true)
         .map(|(start, part)| start + part.len())
         .collect();
     let mut low = 0;
     let mut high = ends.len();
+    // 二分搜索可容纳的最长字素前缀；取上中位数使成功分支能推进 low，避免相邻边界时死循环。
     while low < high {
         let count = (low + high).div_ceil(2);
         let end = ends[count - 1];
+        // 省略号也参与真实整形测量，不能简单从总宽度减去字符数估算。
         let candidate = format!("{}{ellipsis}", &value[..end]);
         if measure(&candidate, style).width <= width {
             low = count;
@@ -361,6 +393,7 @@ pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
             high = count - 1;
         }
     }
+    // 没有任何字素能放下时只返回省略号；更早已经检查省略号本身可容纳。
     let end = low.checked_sub(1).map_or(0, |index| ends[index]);
     format!("{}{ellipsis}", &value[..end])
 }
@@ -371,7 +404,9 @@ mod tests {
     use unicode_segmentation::UnicodeSegmentation;
 
     #[test]
+    /// 用一万倍缩放检验绘制回调被限制在32x32裁剪内，同时检查字形缓存字号不超过512以控制中间资源。
     fn extreme_zoom_rasterizes_only_the_clip_with_bounded_glyph_sizes() {
+        // 极端缩放测试限制实际回调在 32×32 裁剪区，同时检查缓存字号不超过 512。
         let mut count = 0;
         draw_clipped(
             "M",
@@ -397,8 +432,10 @@ mod tests {
     }
 
     #[test]
+    /// 混合中文、单词、长标识符、组合字符和emoji，检查窄宽约束分别换行/缓存，且不污染无约束自然测量。
     fn width_sensitive_shaping_wraps_words_and_clusters_without_changing_intrinsic_metrics() {
         let style = TextStyle::ui(1);
+        // 混合中文、长英文词、组合字符和 emoji，验证窄/宽换行缓存隔离且不改变无换行测量结果。
         let text = "中文段落 with words and long_unbroken_identifier é 👩‍💻 中文段落";
         let intrinsic = measure(text, style);
         let narrow = measure_wrapped(text, style, 70.0);
@@ -416,7 +453,9 @@ mod tests {
     }
 
     #[test]
+    /// 比较比例字体宽窄字母、等宽字体、多行高度与缩放比例，证明尺寸来自字体整形而非按字符数估计。
     fn proportional_metrics_monospace_and_multiline_height_come_from_the_fonts() {
+        // 用宽窄拉丁字母验证比例字体差异、等宽字体一致性、多行行高和同比例缩放。
         let ui = TextStyle::ui(1);
         assert!(measure("WWWW", ui).width > measure("iiii", ui).width * 2.0);
         let mono = TextStyle::code();
@@ -427,8 +466,10 @@ mod tests {
     }
 
     #[test]
+    /// 普通和代码字体都需为四个中文字符产生非零glyph_id；依赖测试环境安装可用CJK回退字体。
     fn system_fallback_shapes_chinese_without_missing_glyphs() {
         let mut engine = engine().lock().unwrap();
+        // 两种字体风格都要求四个中文字符生成非零 glyph_id，确保系统回退实际找到了字形。
         for style in [TextStyle::ui(1), TextStyle::code()] {
             let key = engine.prepare("中文字体", style);
             let glyphs: Vec<_> = engine.buffers[&key]
@@ -443,6 +484,7 @@ mod tests {
     }
 
     #[test]
+    /// 按实际测量宽度截断带组合字符的文本，结果需是原文字素边界前缀加省略号，且整体不超宽。
     fn ellipsis_fits_actual_width_and_preserves_graphemes() {
         let style = TextStyle::code();
         let short_source = "let s = ui.text(\"中文字体\")";
@@ -450,6 +492,7 @@ mod tests {
         let value = "e\u{301}e\u{301}中文字体e\u{301}e\u{301}";
         let width = measure("e\u{301}e\u{301}中…", style).width + 0.01;
         let fitted = fit(value, width, style);
+        // 检查结果前缀确实来自原文且结束于字素边界，而不仅是合法 UTF-8 字节边界。
         let prefix = fitted.strip_suffix('…').unwrap();
         assert!(value.starts_with(prefix));
         assert!(

src/render/viewport.rs

@@ -39,10 +39,12 @@ pub struct CameraView {
 
 /// 读取并校验托管 Camera2D 的位置和缩放，生成原生投影描述。
 pub fn camera(store: &ObjectStore, object: ObjectRef) -> Result<CameraView, VmError> {
+    // 先验证实际宿主 payload，避免只有 x/y/zoom 同名字段的普通对象冒充相机。
     store.payload::<Camera2D>(object, "Camera2D")?;
     let x = crate::scroll::coordinate(&store.get_attr(object, "x")?)?;
     let y = crate::scroll::coordinate(&store.get_attr(object, "y")?)?;
     let zoom = crate::scroll::coordinate(&store.get_attr(object, "zoom")?)?;
+    // coordinate 已检查有限性与绝对范围；zoom 还要严格为正并位于专门相机范围，保证可逆变换。
     if !(0.01..=100.0).contains(&zoom) {
         return Err(VmError::InvalidArgument(
             "Camera2D.zoom expects 0.01 through 100",
@@ -63,6 +65,7 @@ pub fn fit(
     cx: &mut endor_core::NativeContext<'_>,
     mount: &crate::mount::Mount,
 ) -> Result<(), VmError> {
+    // 只接受已提交的 CanvasViewport，布局期间的临时几何不能作为 fitView 分配尺寸依据。
     if !mount.geometry.canvas_viewport || mount.layout.is_some() {
         return Err(VmError::InvalidArgument(
             "fitView requires a committed CanvasViewport Mount",
@@ -83,6 +86,7 @@ pub fn fit(
         .store()
         .payload::<crate::mount::Mount>(root, "Mount")?
         .clone();
+    // 只汇总场景直接子出现的有限边界，沿 sibling 链扫描；不把无限世界或整棵后代图作为布局盒。
     let mut next = scene.first_child;
     let mut bounds: Option<[f32; 4]> = None;
     let mut count = 0;
@@ -95,12 +99,14 @@ pub fn fit(
             .upgrade(weak)?
             .ok_or(VmError::InvalidArgument("expired scene child"))?;
         let child = cx.store().payload::<crate::mount::Mount>(object, "Mount")?;
+        // 先扣 scene 原点，把孩子绝对布局坐标转为场景相对坐标；此数组存左上/右下，而非宽高。
         let rect = [
             child.geometry.x - scene.geometry.x,
             child.geometry.y - scene.geometry.y,
             child.geometry.x - scene.geometry.x + child.geometry.width,
             child.geometry.y - scene.geometry.y + child.geometry.height,
         ];
+        // 逐个扩展共同包围框，空场景保持 None 并在后面回到单位相机。
         bounds = Some(bounds.map_or(rect, |b| {
             [
                 b[0].min(rect[0]),
@@ -113,13 +119,16 @@ pub fn fit(
     }
     let node = crate::block::snapshot(cx.store(), mount.block)?;
     let inset = crate::layout::insets(&node);
+    // 扣除布局 inset 后才是相机可用的内容区域；负值归零，避免用边框占用部分计算缩放。
     let width = (mount.geometry.width - inset.horizontal()).max(0.0);
     let height = (mount.geometry.height - inset.vertical()).max(0.0);
     let (x, y, zoom) = if let Some(bounds) = bounds {
+        // 两个轴分别计算可容纳倍率再取较小者；内容跨度增加 48 世界单位形成留白，最终钳到相机范围。
         let zoom = (width / (bounds[2] - bounds[0] + 48.0))
             .min(height / (bounds[3] - bounds[1] + 48.0))
             .clamp(0.01, 100.0);
         (
+            // 让内容中心落在视口中心：相机位置 = 内容中心 - 半个视口的世界尺寸。
             (bounds[0] + bounds[2]) / 2.0 - width / (2.0 * zoom),
             (bounds[1] + bounds[3]) / 2.0 - height / (2.0 * zoom),
             zoom,
@@ -127,6 +136,7 @@ pub fn fit(
     } else {
         (0.0, 0.0, 1.0)
     };
+    // 最终通过普通属性写入走 VM 变更追踪/绑定机制；共享该相机的其他视口也会观察到更新。
     for (name, value) in [("x", x), ("y", y), ("zoom", zoom)] {
         cx.set_attr(
             camera,
@@ -160,6 +170,7 @@ impl Transform {
         Point::new(point.x * self.zoom + self.x, point.y * self.zoom + self.y)
     }
     /// 将视图点反算回逻辑坐标，供命中和手势锚点计算使用。
+    // 不在这里额外校验 zoom，调用方必须先保证 valid；零缩放无法反算。
     pub fn inverse(self, point: Point) -> Point {
         Point::new(
             (point.x - self.x) / self.zoom,
@@ -177,6 +188,7 @@ impl Transform {
         )
     }
     /// 将当前变换再放入外层变换，保持绘制与逆向命中的组合顺序一致。
+    // 组合为 outer(self(point))：内层平移也要乘外层缩放，不能只把两次平移相加。
     pub fn then(self, outer: Self) -> Self {
         Self {
             zoom: self.zoom * outer.zoom,
@@ -184,8 +196,9 @@ impl Transform {
             y: self.y * outer.zoom + outer.y,
         }
     }
-    /// 检查数值、几何和资源条件是否满足本类型约束，供上层拒绝非法输入。
+    /// 验证累计二维变换：zoom 有限且在 (0,1000000]，平移有限且绝对值不超过一万亿。
     pub fn valid(self) -> bool {
+        // 允许累计平移远大于单个世界坐标范围，因为相机偏移还会乘缩放；同时限制嵌套累计放大。
         self.zoom.is_finite()
             && self.zoom > 0.0
             && self.zoom <= 1_000_000.0
@@ -198,6 +211,7 @@ impl Transform {
 
 /// 计算视口与祖先裁剪的共同可见矩形。
 fn intersect(a: [f32; 4], b: [f32; 4]) -> [f32; 4] {
+    // clip 用 [x,y,width,height]，分离的矩形返回零面积，不产生负宽高。
     let x = a[0].max(b[0]);
     let y = a[1].max(b[1]);
     [
@@ -222,12 +236,14 @@ pub fn project(
         nodes.insert(node.block_id.as_str(), node);
         work.extend(node.children().iter().map(|node| node.as_ref()));
     }
+    // 每个出现向孩子传递累计二维变换、当前空间的裁剪和嵌套面板映射；业务布局坐标不被改写。
     type Scope = (
         Transform,
         Option<[f32; 4]>,
         Option<Arc<crate::scene3d::panel::Mapping>>,
     );
     let mut contexts = HashMap::<u64, Scope>::new();
+    // 保留 next_sibling 查找表，遍历可变 Mount 时仍可按稳定子出现顺序为面板根建立映射。
     let next: HashMap<_, _> = frame
         .mounts
         .iter()
@@ -237,6 +253,7 @@ pub fn project(
         HashMap::<u64, (Arc<crate::scene3d::panel::Mapping>, crate::layout::Size)>::new();
     for mount in &mut frame.mounts {
         let node = nodes[mount.block_id.as_str()];
+        // 面板根进入独立纹理像素空间，二维变换重置为单位，裁剪重置为面板尺寸；普通节点沿用父上下文。
         let (view, clip, panel) = if let Some((panel, size)) = panels.get(&mount.id) {
             (
                 Transform::default(),
@@ -253,6 +270,7 @@ pub fn project(
             view.valid(),
             "nested viewport transform exceeds numeric budget"
         );
+        // 单位变换省略存储，其余保持为显式 Transform；每轮先清理旧 viewport_clip，避免残留上帧状态。
         mount.view = (view != Transform::default()).then_some(view);
         mount.panel = panel.clone();
         mount.clip = clip;
@@ -263,6 +281,7 @@ pub fn project(
         let viewport = if let UiKind::CanvasViewport { camera, .. } = &node.kind {
             let x = mount.x + inset.left;
             let y = mount.y + inset.top;
+            // 围绕视口内容原点建立相机变换：原点保持锚定，世界内容先减相机位置再缩放，最后套父变换。
             child_view = Transform {
                 zoom: camera.zoom,
                 x: x * (1.0 - camera.zoom) - camera.x * camera.zoom,
@@ -282,6 +301,7 @@ pub fn project(
                 (mount.width - inset.horizontal()).max(0.),
                 (mount.height - inset.vertical()).max(0.),
             ))
+        // 普通节点的 clip_children 裁到边框内侧，独立视口裁内容盒，Scroll 默认裁整个滚动盒。
         } else if node.clip_children {
             let border = node.border;
             Some(Rect::new(
@@ -296,6 +316,7 @@ pub fn project(
             None
         };
         if let Some(rect) = viewport {
+            // 本视口边界按父变换投影，不能套当前相机的 child_view，否则相机会连自己的视口框一起移动。
             let rect = view.rect(rect);
             let rect = [rect.x, rect.y, rect.width, rect.height];
             child_clip = Some(clip.map_or(rect, |clip| intersect(clip, rect)));
@@ -309,6 +330,7 @@ pub fn project(
             ..
         } = &node.kind
         {
+            // 沿面板映射链限制嵌套深度，防止递归纹理装配和输入逆投影无限展开。
             let mut depth = 0;
             let mut ancestor = panel.clone();
             while let Some(mapping) = ancestor {
@@ -317,6 +339,7 @@ pub fn project(
             }
             anyhow::ensure!(depth < 8, "3D UI viewport nesting exceeds 8 surfaces");
             let mut child = mount.first_child;
+            // slots、面板尺寸和直接子出现按同序配对；缺少预期子出现时立即报错，不能把内容映射到错误面板。
             for (key, size) in node.slots.iter().zip(sizes) {
                 let id = child.ok_or_else(|| anyhow::anyhow!("missing 3D UI root occurrence"))?;
                 let mapping = Arc::new(crate::scene3d::panel::Mapping {
@@ -333,6 +356,7 @@ pub fn project(
                     clip: mount.viewport_clip,
                     parent: panel.clone(),
                 });
+                // 记录待遍历面板根的新上下文；之后走到该孩子时切换纹理空间，不把外层 clip 误当纹理像素。
                 panels.insert(id, (mapping, *size));
                 child = next[&id];
             }
@@ -340,6 +364,7 @@ pub fn project(
         contexts.insert(mount.id, (child_view, child_clip, panel));
     }
     let mounts: HashMap<_, _> = frame.mounts.iter().map(|mount| (mount.id, mount)).collect();
+    // 按每条命令的 Mount 归属重建 view/clip，确保源绘制、默认绘制和输入都使用这一轮最终投影。
     frame.command_views.clear();
     frame.command_clips.clear();
     anyhow::ensure!(
@@ -353,6 +378,7 @@ pub fn project(
         frame.command_views.push(mount.view);
         frame.command_clips.push(mount.clip);
     }
+    // 几何、裁剪和视图信息全部就绪后才建立屏幕宽阶段索引，避免查询旧投影候选。
     frame.hit_index = std::sync::Arc::new(spatial::Index::build(&frame.mounts));
     Ok(())
 }
@@ -360,9 +386,9 @@ pub fn project(
 mod tests {
     use super::*;
     #[test]
+    /// 以实际两次点变换核对嵌套组合顺序、逆变换和矩形尺寸，并允许大相机投影平移而非套用较小世界坐标限额。
     fn nested_views_compose_and_invert_without_changing_layout_coordinates() {
-        // Camera coordinates may be +/-1e6 at zoom 100. Their projected
-        // translation must not inherit the smaller world-coordinate limit.
+        // 相机坐标可达正负一百万，缩放100后投影平移可达一亿；不能继续使用较小的世界坐标限制。
         assert!(
             Transform {
                 zoom: 100.,
@@ -382,6 +408,7 @@ mod tests {
             y: 20.0,
         };
         let point = Point::new(-5.0, 100.0);
+        // 以两次实际点变换验证组合顺序，再检查逆变换和矩形尺寸，避免只验证某一种公式写法。
         let composed = inner.then(outer);
         assert_eq!(composed.point(point), outer.point(inner.point(point)));
         assert_eq!(composed.inverse(composed.point(point)), point);

src/render/viewport/spatial.rs

@@ -9,12 +9,15 @@ use std::collections::HashMap;
 #[derive(Debug, Default)]
 /// 有限屏幕格子和后备集合。候选筛选允许保守多取，但不能因索引预算漏掉有效命中。
 pub struct Index {
+    // 建立索引时的 Mount 总数，用来发现明显过期的索引；数量相同不代表几何未改变。
     count: usize,
+    // 格子坐标映射到原 mounts 切片下标，保留原始绘制顺序信息，不持有托管对象。
     cells: HashMap<(i32, i32), Vec<usize>>,
+    // 不能安全装入网格的候选，每次查询都参与；由后续精确 contains 排除误命中。
     fallback: Vec<usize>,
 }
 impl Index {
-    /// 根据当前输入构造本模块的派生结果，具体的验证与资源边界见函数内步骤。
+    /// 从帧几何构建 128 单位屏幕网格；大对象、投影面板和超预算项进入保守后备集合。
     pub fn build(mounts: &[MountGeometry]) -> Self {
         let mut result = Self {
             count: mounts.len(),
@@ -22,6 +25,7 @@ impl Index {
         };
         let mut entries = 0;
         for (index, mount) in mounts.iter().enumerate() {
+            // 只有可交互项、场景视口或滚动容器需要参与输入目标宽阶段，其余外观节点跳过。
             if !mount.interactive
                 && !mount.canvas_viewport
                 && !mount.scene3d_viewport
@@ -29,16 +33,19 @@ impl Index {
             {
                 continue;
             }
+            // 3D 面板使用射线投影，不能把局部矩形当成屏幕 AABB 安全近似，统一交给精确阶段。
             if mount.panel.is_some() {
                 result.fallback.push(index);
                 continue;
             }
+            // 普通二维节点取两对角点并应用视图变换，再排序上下界，兼容坐标方向变化。
             let a = Point::new(mount.x, mount.y);
             let b = Point::new(mount.x + mount.width, mount.y + mount.height);
             let a = mount.view.map_or(a, |view| view.point(a));
             let b = mount.view.map_or(b, |view| view.point(b));
             let (mut x0, mut y0, mut x1, mut y1) =
                 (a.x.min(b.x), a.y.min(b.y), a.x.max(b.x), a.y.max(b.y));
+            // 先与有效裁剪求交，缩小入网范围；完全不可见的矩形不需要成为候选。
             if let Some([x, y, w, h]) = mount.clip {
                 x0 = x0.max(x);
                 y0 = y0.max(y);
@@ -48,6 +55,7 @@ impl Index {
             if x1 < x0 || y1 < y0 {
                 continue;
             }
+            // 极端或非有限坐标不做网格展开，转后备集合；不能因转换溢出而漏掉待精确检查的目标。
             if ![x0, y0, x1, y1]
                 .iter()
                 .all(|value| value.is_finite() && value.abs() < 1e12)
@@ -56,8 +64,10 @@ impl Index {
                 continue;
             }
             let (left, top, right, bottom) = (cell(x0), cell(y0), cell(x1), cell(y1));
+            // 用 i64 计算格子跨度和饱和乘积，避免极大矩形在预算检查前发生算术溢出。
             let cells = (i64::from(right) - i64::from(left) + 1)
                 .saturating_mul(i64::from(bottom) - i64::from(top) + 1);
+            // 单项最多展开 256 格，全索引最多 65536 项格子引用；超预算只降级，不丢弃目标。
             if cells > 256 || entries + cells > 65_536 {
                 result.fallback.push(index);
                 continue;
@@ -73,6 +83,7 @@ impl Index {
     }
     /// 返回当前网格格子与后备集合中的候选，去重并恢复逆绘制顺序。
     pub fn candidates(&self, point: Point, count: usize) -> Vec<usize> {
+        // 索引总数与当前帧不一致时，下标集合不再可靠；直接返回整帧逆序候选。
         if self.count != count {
             return (0..count).rev().collect();
         }
@@ -80,6 +91,7 @@ impl Index {
         if let Some(items) = self.cells.get(&(cell(point.x), cell(point.y))) {
             output.extend(items);
         }
+        // 按下标降序还原从前景到背景的绘制顺序；去重确保同一出现不会重复执行 hitTest。
         output.sort_unstable_by(|a, b| b.cmp(a));
         output.dedup();
         output
@@ -87,6 +99,7 @@ impl Index {
 }
 /// 把屏幕坐标映射到有界整数网格坐标，处理负方向与极端数值。
 fn cell(value: f32) -> i32 {
+    // 每格 128 个屏幕单位；floor 让 -1 属于负格而不是零格，再限制到整数表示范围。
     (value / 128.)
         .floor()
         .clamp(i32::MIN as f32, i32::MAX as f32) as i32
@@ -96,6 +109,7 @@ fn cell(value: f32) -> i32 {
 mod tests {
     use super::*;
     #[test]
+    /// 200个分散节点只返回局部网格候选；覆盖海量格的巨大前景节点进入后备集合后仍按前景顺序参与精确命中。
     fn screen_grid_limits_candidates_and_keeps_huge_rectangles_hittable() {
         let (_, document) = crate::endor_host::ReplSession::load(
             "page=Page()\npage.render(Button(\"hit\"))",
@@ -123,6 +137,7 @@ mod tests {
         }
         let index = Index::build(&mounts);
         assert_eq!(index.candidates(Point::new(5., 5.), mounts.len()), vec![0]);
+        // 把最前景节点扩大到覆盖海量格子，验证其进入后备集合后仍排在普通候选之前且可精确命中。
         mounts[199].x = -1_000_000.;
         mounts[199].width = 2_000_000.;
         let index = Index::build(&mounts);

src/runtime/api.rs

@@ -34,6 +34,7 @@ use crate::{
     endor_host,
 };
 
+// 只监听 IPv4 回环固定端口，接口用于本进程原生输入和本机 agent，不是对外网络服务器。
 pub const API_ADDRESS: &str = "127.0.0.1:4737";
 const MAX_CODE_SIZE: u64 = endor_host::MAX_SOURCE_BYTES as u64;
 type Notify = Arc<dyn Fn() + Send + Sync>;
@@ -55,12 +56,14 @@ pub struct RuntimeControl {
 impl RuntimeControl {
     /// 只发出一次退出请求，唤醒 worker 执行清理，并通过完成句柄通知原生循环。
     pub fn request_shutdown(&self) -> bool {
+        // 原子标志合并重复退出请求；已请求直接返回 true，不在 GUI 线程重复排队清理。
         if self.requested.swap(true, Ordering::AcqRel) {
             return true;
         }
         if self.sender.try_send(()).is_ok() {
             true
         } else {
+            // 控制队列不可用时回滚请求标志，允许调用方识别失败并再次尝试，而非永远卡在假退出状态。
             self.requested.store(false, Ordering::Release);
             false
         }
@@ -74,6 +77,7 @@ impl RuntimeControl {
         let (lock, ready) = &*self.completion;
         let result = lock.lock().ok()?;
         let (result, _) = ready
+            // 条件变量处理虚假唤醒，直到完成槽非空或超时；返回 None 也可能来自锁中毒，不能当作清理成功。
             .wait_timeout_while(result, timeout, |result| result.is_none())
             .ok()?;
         result.clone()
@@ -105,11 +109,12 @@ struct BuildRequest {
     submission: u64,
 }
 
-/// 建立本模块的执行/服务上下文，并把后续推进交给返回的句柄或驱动。
+/// 绑定回环 API，启动请求接收与单 VM worker，返回活动日志及一次性退出控制句柄。
 pub fn start(
     namespace: Arc<RwLock<NamespaceState>>,
     proxy: EventLoopProxy<AppEvent>,
 ) -> Result<(Activity, RuntimeControl)> {
+    // 退出控制仅需一个消息槽，正常执行请求另走容量8队列，避免工作排满后无法通知关闭。
     let (sender, receiver) = sync_channel(1);
     let control = RuntimeControl {
         sender,
@@ -121,6 +126,7 @@ pub fn start(
         control: control.clone(),
         proxy: proxy.clone(),
     };
+    // 绑定失败在启动阶段反馈，不能假装本机 API 可用；后台通知仅发送 GUI 事件，不直接画窗口。
     let server = Server::http(API_ADDRESS)
         .map_err(|error| anyhow::anyhow!(error))
         .with_context(|| format!("bind Tessera API to {API_ADDRESS}"))?;
@@ -165,6 +171,7 @@ fn start_server_observed(
     observer_notify: Notify,
     shutdown: Option<Shutdown>,
 ) -> Result<thread::JoinHandle<()>> {
+    // HTTP 接收与 VM 执行分离，最多8个排队请求；源代码只在单个 endor-worker 中操作 VM。
     let (sender, receiver) = sync_channel::<BuildRequest>(8);
     let worker_namespace = namespace.clone();
     let worker_notify = notify.clone();
@@ -175,11 +182,13 @@ fn start_server_observed(
         .name("tessera-endor-worker".into())
         .spawn(move || {
             let mut worker = Worker::default();
+            // 分片请求跨循环保留原 HTTP 请求和继续句柄；同一时刻只推进一个有未完成 VM 执行的输入。
             let mut pending: Option<(BuildRequest, PendingRequest)> = None;
             loop {
                 if let Some(shutdown) = &shutdown
                     && shutdown.receiver.try_recv().is_ok()
                 {
+                    // 退出优先于下一量子：先撤去待响应请求，再由 shutdown_runtime 清理 VM 续体与生命周期资源。
                     if let Some((job, input)) = pending.take() {
                         drop(input);
                         let _ = job
@@ -187,12 +196,14 @@ fn start_server_observed(
                             .respond(error_response(StatusCode(503), "application is exiting"));
                     }
                     let outcome = worker.shutdown_runtime();
+                    // 排队请求全部明确回应503，不能留着客户端无期限等待已经停止的执行线程。
                     while let Ok(job) = receiver.try_recv() {
                         let _ = job
                             .request
                             .respond(error_response(StatusCode(503), "application is exiting"));
                     }
                     if let Ok(mut current) = worker_namespace.write() {
+                        // 撤销所有帧的会话/焦点与原生命令，让 GUI 不再把旧资源当成仍可执行的活域。
                         current.runtime_session = 0;
                         current.window_commands.clear();
                         current.document.frame.session = 0;
@@ -206,6 +217,7 @@ fn start_server_observed(
                     let (lock, ready) = &*shutdown.control.completion;
                     if let Ok(mut result) = lock.lock() {
                         *result = Some(outcome.clone());
+                        // 先在锁内保存清理结果再唤醒等待者，同时用 AppEvent 通知原生事件循环退出，两条路径复用同一 outcome。
                         ready.notify_all();
                     }
                     let _ = shutdown.proxy.send_event(AppEvent::ShutdownComplete {
@@ -213,6 +225,7 @@ fn start_server_observed(
                     });
                     break;
                 }
+                // 分片只让出线程，不并行执行后续输入；当前请求完成才回应并处理下一队列项。
                 if let Some((job, input)) = pending.take() {
                     match worker.resume_request(&job, input, &worker_namespace, &worker_notify) {
                         RequestProgress::Pending(input) => {
@@ -228,6 +241,7 @@ fn start_server_observed(
                     }
                     continue;
                 }
+                // 空闲输入边界先推进视口刷新与任务，待执行刷新/协作任务时零等待，否则最多100ms检查一次。
                 worker.refresh_viewport(&worker_namespace, &worker_notify);
                 let wait = if worker.repl.as_ref().is_some_and(|(_, runtime)| {
                     runtime.has_pending_refresh() || runtime.has_cooperative_tasks()
@@ -261,6 +275,7 @@ fn start_server_observed(
                                     && current.runtime_session != runtime.id
                             })
                         }) {
+                            // 当前持久域同时失去 submission 和 runtime_session 归属时退役；不能仅因源码请求排队就误删仍权威的旧域。
                             worker.repl = None;
                         }
                         if wait.is_zero() {
@@ -278,6 +293,7 @@ fn start_server_observed(
                 if exiting
                     .as_ref()
                     .is_some_and(|flag| flag.load(Ordering::Acquire))
+                    // 退出后拒绝写入/执行路由，GET 与 OPTIONS 仍可读取最近发布值或探测接口。
                     && !matches!(request.method(), Method::Get | Method::Options)
                 {
                     let _ =
@@ -306,8 +322,9 @@ struct ObservedRequest {
     notify: Notify,
 }
 impl ObservedRequest {
-    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
+    /// 从请求提取允许观察的头部与显示来源，创建活动记录并通知工具界面。
     fn new(inner: Request, activity: Activity, notify: Notify) -> Self {
+        // 活动观察只保留 Content-Type/Length；X-Tessera-Origin 仅判来源标签，不把任意认证头复制进工具日志。
         let headers = inner
             .headers()
             .iter()
@@ -315,6 +332,7 @@ impl ObservedRequest {
             .map(ToString::to_string)
             .collect::<Vec<_>>()
             .join("\n");
+        // console 标记只是显示来源，不提供权限，也不改变 VM 执行语义。
         let origin = if inner
             .headers()
             .iter()
@@ -349,7 +367,9 @@ impl ObservedRequest {
         let status = response.status_code();
         let headers = response.headers().to_vec();
         let length = response.data_length();
+        // 响应正文本已在内存 Cursor，记录预览后用原 status/headers/reader/length 重建响应，不消费正文内容。
         let reader = response.into_reader();
+        // 记录的是已构造响应，即使后面 socket 发送失败也已结束活动记录，不能据此声称客户端成功接收。
         self.activity.lock().unwrap().finish(
             self.id,
             status.0,
@@ -390,6 +410,7 @@ fn handle(
 ) {
     let request = ObservedRequest::new(request, activity.clone(), observer_notify.clone());
     let method = request.method().clone();
+    // 路由匹配去掉查询串，namespace 从固定路径提取；不把 query 当作命名空间或源代码。
     let path = request
         .url()
         .split('?')
@@ -400,6 +421,7 @@ fn handle(
     let evaluation = namespace_from_route(&path, "/evaluate");
     let repl = namespace_from_route(&path, "/repl");
     let event = namespace_from_route(&path, "/events");
+    // PUT/code 完整替换，POST 在 events/repl/evaluate 中分类，DELETE/repl 是持久会话重置；其他交给资源读取/清空路径。
     let route = if method == Method::Put {
         namespace_from_path(&path).map(|name| (name, RequestKind::Code))
     } else if method == Method::Post {
@@ -452,6 +474,7 @@ fn code_request(
         );
     }
 
+    // GET 返回最近成功发布的 source 而非正在排队的输入，并通过头部暴露 revision/session/window/layout 及逻辑视口。
     if method == Method::Get {
         let mut response = text(
             StatusCode(200),
@@ -506,6 +529,7 @@ fn code_request(
         );
         return response;
     }
+    // 释放读锁后才申请写锁，避免同一线程持读锁升级为写锁死锁；修改结束也先解锁再发送 GUI 通知。
     drop(current);
 
     match method {
@@ -548,6 +572,7 @@ fn submit(
             return;
         }
     };
+    // 读取成功后才保存受限活动正文预览；超长或非法 UTF-8 请求不会进入执行队列。
     request.record_body(&source);
     let Ok(mut current) = namespace.write() else {
         let _ = request.respond(error_response(
@@ -560,6 +585,7 @@ fn submit(
         let _ = request.respond(error_response(StatusCode(404), "namespace is not active"));
         return;
     }
+    // 仅完整 Code 请求分配新 submission，事件/REPL/表达式继承当前身份，保留共享域输入顺序。
     let submission = match if kind == RequestKind::Code {
         current.next_submission()
     } else {
@@ -578,6 +604,7 @@ fn submit(
         namespace: addressed.into(),
         submission,
     };
+    // 持 namespace 写锁完成入队和接受身份更新；worker 提交使用同一锁，保证接受与发布之间没有竞态窗口。
     match sender.try_send(job) {
         // A rejected queue entry never invalidates accepted work. The worker
         // uses this same lock when committing, so publication is atomic.
@@ -586,6 +613,7 @@ fn submit(
                 current.submission = submission;
             }
         }
+        // 队列拒绝时不推进 submission，所以已经接受的旧工作不会因为本次失败请求而失去发布资格。
         Err(TrySendError::Full(job)) => {
             let _ = job
                 .request
@@ -611,6 +639,7 @@ fn superseded(submission: u64) -> Response<std::io::Cursor<Vec<u8>>> {
 
 /// 从固定路由格式提取命名空间，避免把不匹配的路径当作代码资源。
 fn namespace_from_route<'a>(path: &'a str, suffix: &str) -> Option<&'a str> {
+    // 同时检查前后缀且命名空间非空、无额外斜杠；不做模糊路径前缀匹配。
     path.strip_prefix("/v1/namespaces/")?
         .strip_suffix(suffix)
         .filter(|namespace| !namespace.is_empty() && !namespace.contains('/'))
@@ -628,6 +657,8 @@ fn read_code(request: &mut Request) -> Result<String> {
     {
         anyhow::bail!("code exceeds the 1 MiB limit");
     }
+    // 已知 Content-Length 先预拒绝，再在流上最多读上限+1；防止缺失/不实长度绕过容量限制。
+    // read_to_string 要求 UTF-8，不用有损替换改变用户源码。
     let mut code = String::new();
     request
         .as_reader()
@@ -644,6 +675,7 @@ fn read_code(request: &mut Request) -> Result<String> {
 fn compile_error(error: anyhow::Error) -> Response<std::io::Cursor<Vec<u8>>> {
     let mut diagnostic =
         serde_json::json!({ "severity": "error", "message": format!("{error:#}") });
+    // 有 SourceDiagnostic 才附行/列和半开字节范围；其他运行时错误仍保留完整错误链消息，不编造源码位置。
     if let Some(source) = error.downcast_ref::<frontend::SourceDiagnostic>() {
         diagnostic["line"] = source.location.line.into();
         diagnostic["column"] = source.location.column.into();
@@ -683,6 +715,7 @@ fn markdown(status: StatusCode, value: String) -> Response<std::io::Cursor<Vec<u
 
 /// 以明确的内容类型和状态码构造响应，并应用本机 API 的公共响应头。
 fn text(status: StatusCode, value: &str, content_type: &str) -> Response<std::io::Cursor<Vec<u8>>> {
+    // 公共响应头只允许固定本机 Origin/方法/头名，非通配任意来源；这些头不替代回环绑定与路由校验。
     let mut response = Response::from_string(value).with_status_code(status);
     add_header(&mut response, "Content-Type", content_type);
     add_header(
@@ -705,6 +738,7 @@ fn text(status: StatusCode, value: &str, content_type: &str) -> Response<std::io
 
 /// 向响应追加经过 HTTP 库检查的头字段，不直接拼接未验证的原始报文。
 fn add_header(response: &mut Response<std::io::Cursor<Vec<u8>>>, name: &str, value: &str) {
+    // 由 HTTP 库验证字段格式，非法头被忽略，不把未校验字符拼进原始响应报文。
     if let Ok(header) = Header::from_bytes(name, value) {
         response.add_header(header);
     }

src/runtime/api/guide.rs

@@ -1,9 +1,11 @@
 //! 从当前命名空间生成 /agent 使用指南。返回的示例、地址和版本描述来自运行时上下文；这里生成文档，不执行用户源码。
 //!
-//! Live agent-facing guide generated from the current namespace.
+//! 指南正文是返回给客户端的静态 Markdown 模板，只有命名空间、版本、地址和内置示例按参数填充。
 use super::*;
 
-/// 用当前命名空间、地址和版本填充在线指南，示例来自项目内置 Endor 源码。
+/// 为 /agent 生成可提交代码与查询接口的 Markdown 说明。
+/// format! 使用具名插值注入 namespace.name/revision 与监听地址；示例在编译时嵌入，
+/// 因而请求不会访问示例文件、执行示例或改变会话。正文中的 JSON/Endor 是文档内容。
 pub(super) fn agent_guide(namespace: &NamespaceState) -> String {
     format!(
         r##"# Tessera Agent API

src/runtime/api/tests.rs

@@ -10,6 +10,8 @@ use std::{
 };
 
 #[test]
+/// 模拟 reset 后旧画面仍含编号 2 的窗口，而新 Console VM 恰好再次分配编号 2。
+/// 关闭 session=0 的旧投影只能移除画面，不能按相同数字误关新 VM 的真实资源。
 fn preserved_picture_close_does_not_retire_same_number_in_fresh_console_vm() {
     let (_, mut picture) = endor_host::ReplSession::load(
         include_str!("../../../examples/windows.endor"),
@@ -18,6 +20,7 @@ fn preserved_picture_close_does_not_retire_same_number_in_fresh_console_vm() {
         150,
     )
     .unwrap();
+    // 把旧文档标成无活动 VM 的保留投影；编号相同也不能据此识别当前资源。
     picture.frame.session = 0;
     for view in picture.windows.values_mut() {
         view.frame.session = 0;
@@ -80,6 +83,7 @@ fn preserved_picture_close_does_not_retire_same_number_in_fresh_console_vm() {
     );
 }
 
+/// 一次测试独占的临时 HTTP 服务；端口由系统分配，持有线程句柄以便结束时解除阻塞并回收。
 struct TestServer {
     server: Arc<Server>,
     address: SocketAddr,
@@ -87,6 +91,8 @@ struct TestServer {
 }
 
 impl TestServer {
+    /// 发送带明确 Content-Length 的 UTF-8 文本请求，使用 Connection: close 读至响应结束。
+    /// 返回状态码、原始头和正文；10 秒超时使服务端死锁表现为测试失败而非无限等待。
     fn request(&self, method: &str, path: &str, body: &str) -> (u16, String, String) {
         let mut stream = TcpStream::connect(self.address).unwrap();
         stream
@@ -105,6 +111,7 @@ impl TestServer {
 }
 
 impl Drop for TestServer {
+    /// 解除服务端 accept 等待并等待线程结束，避免测试之间遗留监听线程。
     fn drop(&mut self) {
         self.server.unblock();
         if let Some(api) = self.api.take() {
@@ -114,6 +121,8 @@ impl Drop for TestServer {
 }
 
 #[test]
+/// 通过 HTTP 提交覆盖 moveTab 的 Page 子类，再发送带帧身份的 tab-drop。
+/// 检查源覆盖恰好调用一次、页面顺序改变，以及重放旧事件返回 409 而不损坏运行时。
 fn native_tab_drop_route_reorders_live_pages_and_rejects_reused_frames() {
     let server = Arc::new(Server::http("127.0.0.1:0").unwrap());
     let namespace = Arc::new(RwLock::new(NamespaceState::default()));
@@ -157,6 +166,7 @@ fn native_tab_drop_route_reorders_live_pages_and_rejects_reused_frames() {
             }),
         }
     };
+    // 保留同一事件正文用于重放测试，不能重新读取新 layout_version，否则就不是过期输入。
     let body = serde_json::to_string(&input).unwrap();
     let response = client.request("POST", "/v1/namespaces/app.main/events", &body);
     assert_eq!(response.0, 200, "{}", response.2);
@@ -177,6 +187,8 @@ fn native_tab_drop_route_reorders_live_pages_and_rejects_reused_frames() {
 }
 
 #[test]
+/// 零延时任务触发非法窗口尺寸，使后台回调先产生运行时故障。
+/// 之后多次 REPL 请求都应被拒绝，同时保留原始 stop/window size 诊断，而非用后续错误覆盖。
 fn background_failure_preserves_its_cause_after_rejected_console_input() {
     let server = Arc::new(Server::http("127.0.0.1:0").unwrap());
     let namespace = Arc::new(RwLock::new(NamespaceState::default()));
@@ -215,6 +227,8 @@ fn background_failure_preserves_its_cause_after_rejected_console_input() {
 }
 
 #[test]
+/// 依次创建未挂载对象、读取共享值、挂载、reset，再用完整 PUT 替换会话。
+/// 验证未挂载输入不增 revision，reset 清绑定但保留画面，成功 PUT 才切换到新 VM。
 fn console_keeps_memory_until_reset_or_complete_put_without_erasing_the_page() {
     let server = Arc::new(Server::http("127.0.0.1:0").unwrap());
     let namespace = Arc::new(RwLock::new(NamespaceState::default()));
@@ -226,6 +240,7 @@ fn console_keeps_memory_until_reset_or_complete_put_without_erasing_the_page() {
     };
     let repl = "/v1/namespaces/app.main/repl";
     let code = "/v1/namespaces/app.main/code";
+    // 先创建对象但不 render；返回值可以跨 REPL 请求复用，发布 revision 此时仍为 0。
     let created = client.request("POST", repl, "title = ui.text(\"中文\")");
     assert_eq!(created.0, 200, "{}", created.2);
     let created: serde_json::Value = serde_json::from_str(&created.2).unwrap();
@@ -262,6 +277,8 @@ fn console_keeps_memory_until_reset_or_complete_put_without_erasing_the_page() {
 }
 
 #[test]
+/// 经真实 HTTP 完成指南读取、PUT/GET、失败候选、再次 PUT 和 DELETE。
+/// 同时检查诊断位置、源文本/版本头、空文档、错误 namespace 与通知次数，确保仅成功发布改变版本。
 fn http_executes_real_endor_preserves_failed_updates_and_supports_delete() {
     let server = Arc::new(Server::http("127.0.0.1:0").unwrap());
     let namespace = Arc::new(RwLock::new(NamespaceState::default()));
@@ -317,6 +334,8 @@ fn http_executes_real_endor_preserves_failed_updates_and_supports_delete() {
 }
 
 #[test]
+/// 直接推进 worker 的 submission，模拟新候选已接受但尚未成功替换的时刻。
+/// 旧 VM 的 retained 仍可读；clear 撤销 namespace 后再刷新，才释放 live owner。
 fn queued_candidate_keeps_live_owner_until_delete_revokes_it() {
     let (runtime, document) = endor_host::ReplSession::load(
         "retained = ui.state(9)\npage = Page()\npage.render(ui.textOf(retained,\"value\"))",
@@ -361,6 +380,8 @@ fn queued_candidate_keeps_live_owner_until_delete_revokes_it() {
 }
 
 #[test]
+/// 用通知回调中的通道阻塞第一轮 worker，再使第二个 PUT 排队。
+/// 此时 GET/DELETE 仍应可用；释放 worker 后第一请求成功、被 DELETE 超越的候选返回 409，文档保持清空。
 fn http_delete_remains_available_and_invalidates_queued_put() {
     use std::{
         sync::{Mutex, mpsc},
@@ -370,6 +391,7 @@ fn http_delete_remains_available_and_invalidates_queued_put() {
     let namespace = Arc::new(RwLock::new(NamespaceState::default()));
     let (entered_tx, entered_rx) = mpsc::channel();
     let (release_tx, release_rx) = mpsc::channel();
+    // 通知是共享闭包；用 Mutex 包装接收端使其满足线程共享约束，只阻塞第一次通知。
     let release_rx = Mutex::new(release_rx);
     let calls = AtomicUsize::new(0);
     let notify: Notify = Arc::new(move || {
@@ -384,9 +406,11 @@ fn http_delete_remains_available_and_invalidates_queued_put() {
         server,
         api: Some(api),
     };
-    // Unblock even if a test assertion fails, before scoped threads join.
+    // 析构守卫在 scoped 线程 join 前释放阻塞通知；即使断言 panic 也不能让 worker 永久等通道。
+    // 持有释放信号的发送端；离开作用域即通知 worker 继续，包括异常展开路径。
     struct Release(mpsc::Sender<()>);
     impl Drop for Release {
+        // send 失败意味着接收端已结束，此时无需再阻塞测试清理。
         fn drop(&mut self) {
             let _ = self.0.send(());
         }
@@ -406,6 +430,7 @@ fn http_delete_remains_available_and_invalidates_queued_put() {
         }
         assert_eq!(client.request("GET", route, "").2, example);
         assert_eq!(client.request("DELETE", route, "").0, 200);
+        // DELETE 已同步清空文档并提升提交身份，现在解除第一请求通知阻塞，让排队候选观察到失效。
         drop(release);
         assert_eq!(first.join().unwrap().0, 200);
         assert_eq!(pending.join().unwrap().0, 409);
@@ -415,6 +440,7 @@ fn http_delete_remains_available_and_invalidates_queued_put() {
 }
 
 #[test]
+/// 检查 code 路径解析只接受完整的单段 namespace；缺少后缀和嵌套斜线均返回 None。
 fn extracts_namespace_only_from_code_routes() {
     assert_eq!(
         namespace_from_path("/v1/namespaces/app.main/code"),
@@ -425,6 +451,7 @@ fn extracts_namespace_only_from_code_routes() {
 }
 
 #[test]
+/// 对生成的指南做契约回归：保留代码 CRUD、可运行示例和当前地址，移除旧 export scene/display_list 暴露。
 fn guide_contains_only_code_crud_routes() {
     let guide = agent_guide(&NamespaceState::default());
     assert!(guide.contains("Code CRUD"));
@@ -435,6 +462,8 @@ fn guide_contains_only_code_crud_routes() {
 }
 
 #[test]
+/// 创建已经就绪的定时任务，先按前台模式刷新再读取计数，确保输入前不抢跑回调。
+/// 随后允许空闲刷新并推进待完成工作，计数应从 0 变为 1。
 fn foreground_refresh_does_not_deliver_new_callbacks_ahead_of_input() {
     let source = r#"
 class Action {
@@ -459,6 +488,7 @@ page.render(TextBlock("input priority"))
         next_session: 801,
     };
     let notify: Notify = Arc::new(|| {});
+    // 前台模式仅处理输入前必须收敛的刷新，不引入新的任务交付。
     worker.refresh_viewport_mode(&namespace, &notify, true);
     let value = worker
         .repl
@@ -484,6 +514,8 @@ page.render(TextBlock("input priority"))
 }
 
 #[test]
+/// 在负世界坐标放置按钮，通过 HTTP 平移/锚定缩放，再发送世界坐标 click。
+/// 检查相机数值、旧帧重放 409、按钮计数，以及零倍率 400 不导致 VM fault。
 fn canvas_camera_crosses_real_http_route_and_preserves_negative_world_clicks() {
     let server = Arc::new(Server::http("127.0.0.1:0").unwrap());
     let namespace = Arc::new(RwLock::new(NamespaceState {
@@ -586,6 +618,8 @@ page.render(button)
 }
 
 #[test]
+/// 给局部 CanvasViewport 添加父内边距和自身左边框，检验页面坐标到内容相机锚点的转换。
+/// 成功平移/缩放后核对相机状态；边框、边界与视口外锚点均须返回 400，保留健康运行时。
 fn explicit_viewport_camera_crosses_http_and_rejects_bad_anchors_without_faulting() {
     let server = Arc::new(Server::http("127.0.0.1:0").unwrap());
     let namespace = Arc::new(RwLock::new(NamespaceState {
@@ -658,6 +692,7 @@ fn explicit_viewport_camera_crosses_http_and_rejects_bad_anchors_without_faultin
             expected
         );
     }
+    // 分别覆盖左边框、右侧边界及远离视口的锚点，避免只校验整个窗口范围。
     for point in [[25.0, 30.0], [220.0, 30.0], [700.0, 700.0]] {
         let response = client.request(
             "POST",
@@ -670,6 +705,8 @@ fn explicit_viewport_camera_crosses_http_and_rejects_bad_anchors_without_faultin
 }
 
 #[test]
+/// 通过真实 HTTP 检查透视缩放/orbit、正交缩放，再替换为源实现 PanOnly。
+/// 比较相机数值与自定义控制器结果，并验证视口外锚点和禁用控制器的拒绝状态不会停掉 VM。
 fn scene3d_controllers_cross_http_and_can_be_replaced_by_endor_code() {
     let server = Arc::new(Server::http("127.0.0.1:0").unwrap());
     let namespace = Arc::new(RwLock::new(NamespaceState {
@@ -761,6 +798,8 @@ fn scene3d_controllers_cross_http_and_can_be_replaced_by_endor_code() {
 }
 
 #[test]
+/// 在旋转的 Panel3D 上嵌入二维 CanvasViewport，经射线/UV 映射解释相机事件。
+/// 缺失指针必须拒绝；带指针的平移/缩放只改变面板内相机，外层三维相机保持原值。
 fn canvas_in_world_ui_uses_ray_uv_coordinates_for_real_http_camera_events() {
     let server = Arc::new(Server::http("127.0.0.1:0").unwrap());
     let namespace = Arc::new(RwLock::new(NamespaceState {
@@ -833,6 +872,7 @@ fn canvas_in_world_ui_uses_ray_uv_coordinates_for_real_http_camera_events() {
             .unwrap()
     };
     let pan = value("canvas.camera.x");
+    // 面板倾斜后的投影位移不等于 UI 内部位移，不能把屏幕 delta 直接写入局部相机。
     assert!(pan > 10.);
     assert_eq!(value("view.camera.x"), 0.);
     let response = client.request(

src/runtime/api/worker.rs

@@ -6,6 +6,7 @@
 use super::*;
 
 type HttpResponse = Response<std::io::Cursor<Vec<u8>>>;
+// 外层 thread::Result 区分 Rust panic，内层 Result 区分可诊断编译/运行错误；正常结果另带待发布窗口命令。
 type InputOutcome =
     std::thread::Result<Result<(endor_host::ReplResult, Vec<crate::window::Command>)>>;
 
@@ -19,6 +20,7 @@ type CandidateOutcome = std::thread::Result<
 
 /// 已执行业务部分但仍在等待展示刷新的输入元数据，避免恢复时重放回调。
 pub(super) struct PendingInput {
+    // 输入开始时所属 submission，与 id（VM 会话）分开；新 PUT 接受时可保留正在执行的原 VM 至输入收敛。
     epoch: u64,
     id: u64,
     event: bool,
@@ -27,6 +29,7 @@ pub(super) struct PendingInput {
 
 /// 挂起 HTTP 请求的阶段：等旧刷新、继续输入或继续隔离候选。
 pub(super) enum PendingRequest {
+    // 仅等待旧只读刷新结束，业务输入尚未执行；恢复时可重新走入口，而 Input 阶段不能重放业务副作用。
     BeforeInput,
     Input(Box<PendingInput>),
     Candidate(Box<endor_host::ReplSession>),
@@ -56,6 +59,7 @@ fn current_viewports(
         })
         .map(|(id, size)| (*id, *size))
         .collect();
+    // 主窗口逻辑视口优先覆盖 map 同名值，主壳可以跨会话沿用；副窗口必须仍属于当前发布世代。
     if let Some(viewport) = current.viewport {
         viewports.insert(crate::window::MAIN_WINDOW, viewport);
     }
@@ -77,6 +81,7 @@ impl Worker {
                 error: None,
             };
         };
+        // 正常域允许有界关闭回调，故障域只做宿主清理；catch_unwind 防止清理 panic 跳过原生退出通知。
         let callbacks = !runtime.is_faulted();
         let result = catch_unwind(AssertUnwindSafe(|| runtime.shutdown()));
         match result {
@@ -108,6 +113,7 @@ impl Worker {
         namespace: &Arc<RwLock<NamespaceState>>,
         notify: &Notify,
     ) -> Response<std::io::Cursor<Vec<u8>>> {
+        // 故障/失活资源的专用关闭只处理副窗口，主壳由 OS 关闭控制走全应用退出流程。
         if input.window == crate::window::MAIN_WINDOW {
             return error_response(
                 StatusCode(409),
@@ -126,6 +132,7 @@ impl Worker {
                     .1
                     .retire_window(input.window)
             }));
+            // 退役失败不能继续借用半清理 VM，放弃整个活域并在下方清其他帧的会话与命令资格。
             if !matches!(result, Ok(Ok(()))) {
                 // Never keep a half-cleaned VM live or borrow another generation.
                 self.repl = None;
@@ -141,6 +148,7 @@ impl Worker {
         let Some(view) = current.document.windows.get(&input.window) else {
             return error_response(StatusCode(409), "window is no longer active");
         };
+        // 即便副窗口数值 ID 相同，也不能让旧会话的关闭请求删除新会话投影。
         if view.frame.session != input.session {
             return error_response(
                 StatusCode(409),
@@ -200,6 +208,7 @@ impl Worker {
         let Some((owner, runtime)) = &mut self.repl else {
             return;
         };
+        // submission 变化先尝试保留仍权威的活域所有者，不立即拿旧 epoch 继续发布后台结果。
         if *owner != epoch {
             if let Ok(current) = namespace.read() {
                 self.preserve_live_owner(&current);
@@ -218,11 +227,13 @@ impl Worker {
             }
             // An accepted foreground input waits only for the existing
             // refresh; do not keep placing new callbacks ahead of it.
+            // 已有前台请求只等当前刷新，不不断把新任务回调插到它前面，避免忙后台工作饿死用户输入。
             let completed = if before_input {
                 None
             } else {
                 runtime.poll_tasks_incremental(&viewports)?
             };
+            // 任务后续刷新未收敛时可以发布较早已完整的 resize 文档，但暂扣任务产生的命令，防止半完成副作用外泄。
             if runtime.has_pending_refresh() {
                 // A complete earlier resize may publish; task effects and their
                 // native commands wait until the task's refresh has settled.
@@ -235,6 +246,7 @@ impl Worker {
             Ok(current) => current,
             Err(_) => return,
         };
+        // 耗时 VM 工作期间 HTTP 线程可能接受 PUT/DELETE，发布写锁内再核对 submission 与 session 双身份。
         if current.submission != epoch || current.runtime_session != id {
             return;
         }
@@ -243,6 +255,7 @@ impl Worker {
                 if let Some(document) = document {
                     (document, Some(commands))
                 } else {
+                    // 无新文档也可能有标题/焦点等原生命令；只在实际有投影变化时唤醒 GUI，避免空闲无效重绘。
                     let projected = !commands.is_empty();
                     current.publish_window_commands(id, commands);
                     drop(current);
@@ -259,6 +272,7 @@ impl Worker {
                         .chars()
                         .take(1024)
                         .collect(),
+                    // 内部 panic 与普通背景错误不同，必须丢弃 VM 并撤销所有原生命令，不能继续运行损坏的域。
                     _ => {
                         self.repl = None;
                         current.runtime_session = 0;
@@ -289,6 +303,7 @@ impl Worker {
         namespace: &Arc<RwLock<NamespaceState>>,
         notify: &Notify,
     ) -> RequestProgress {
+        // 完整 PUT 独立候选，表达式隔离求值；只有 REPL/事件会进入当前持久域并等待已有刷新。
         if job.kind == RequestKind::Code {
             return self.begin_program_request(job, namespace, notify);
         }
@@ -311,6 +326,7 @@ impl Worker {
         if epoch != job.submission {
             return RequestProgress::Complete(superseded(job.submission));
         }
+        // 重置丢弃内存会话但保留显示文档，清帧 session/focus 使旧画面不再接受旧对象事件。
         if job.kind == RequestKind::ResetRepl {
             self.repl = None;
             if let Ok(mut current) = namespace.write() {
@@ -336,6 +352,7 @@ impl Worker {
         {
             return RequestProgress::Pending(PendingRequest::BeforeInput);
         }
+        // 事件先做 JSON 结构、kind 白名单和 Input 字段校验，再用权威发布帧核对具体资源能力。
         let event = if job.kind == RequestKind::Event {
             let input: crate::events::Input = match serde_json::from_str(&job.source) {
                 Ok(input) => input,
@@ -394,6 +411,7 @@ impl Worker {
                 };
                 &document.frame
             };
+            // 窗口关闭允许处理已失活/故障副窗口，不像点击一样要求可运行 VM；由专用宿主退役路径处理。
             if input.kind == "window-close"
                 && frame.window == input.window
                 && frame.session == input.session
@@ -414,6 +432,7 @@ impl Worker {
                     );
                 }
             }
+            // 标签拖放同时验证目标窗口的会话、版本、无故障及插入位置，源窗口校验不能替代目标校验。
             if let Some(target) = &input.tab_drop {
                 let target_frame = if target.window == crate::window::MAIN_WINDOW {
                     Some(&current.document.frame)
@@ -441,6 +460,7 @@ impl Worker {
                     ));
                 }
             }
+            // 统一事件归属门：窗口/session/版本及操作对应资源必须都合法；window-close 特别允许旧布局版本。
             if frame.window != input.window
                 || frame.session != input.session
                 || (input.kind != "window-close" && frame.layout_version != input.layout_version)
@@ -454,6 +474,7 @@ impl Worker {
                     input.kind.as_str(),
                     "tab-activate" | "tab-close" | "tab-detach" | "tab-drop"
                 ) {
+                    // 标签操作的 mount 字段承载 Tab ID，而普通输入承载 Mount ID；两套身份不能混着查询。
                     !frame.tabs.iter().any(|tab| tab.id == input.mount)
                 } else {
                     !frame.mounts.iter().any(|mount| {
@@ -461,6 +482,7 @@ impl Worker {
                             && if input.kind.starts_with("viewport-") {
                                 mount.canvas_viewport
                             } else if input.kind.starts_with("scene-") {
+                                // 3D 手势还要求显式控制器能力，scroll 要有滚动投影，点击/焦点则要求 interactive。
                                 mount.scene3d_viewport && mount.camera_controls
                             } else if input.kind == "scroll" {
                                 mount.scroll.is_some()
@@ -480,6 +502,7 @@ impl Worker {
                     "event targets an obsolete or inactive frame",
                 ));
             }
+            // 兼容页面仅 Canvas 可缩放，Window 模式不接受 pan；结构合法不等于当前页面模式支持操作。
             if input.kind == "page-zoom" && frame.surface.mode != crate::page::Mode::Canvas
                 || input.kind == "page-pan" && frame.surface.mode == crate::page::Mode::Window
             {
@@ -488,6 +511,7 @@ impl Worker {
                     "camera input is unavailable in this Page mode",
                 ));
             }
+            // 缩放锚点须经过面板反投影与内容 clip 检查，不能落在视口边框或被遮挡面板上仍缩放。
             if matches!(input.kind.as_str(), "viewport-zoom" | "scene-zoom")
                 && !frame.mounts.iter().any(|mount| {
                     mount.id == input.mount
@@ -510,6 +534,7 @@ impl Worker {
                     "zoom anchor is outside content viewport",
                 ));
             }
+            // 世界 UI 的非线性位移变换需要位置锚点；普通二维视口的线性位移可以省略 point。
             if (input.kind.starts_with("viewport-") || input.kind.starts_with("scene-"))
                 && input.point.is_none()
                 && frame
@@ -531,6 +556,7 @@ impl Worker {
             .as_ref()
             .is_none_or(|(current, _)| *current != epoch)
         {
+            // 没有当前 epoch 会话时惰性建立空 REPL，每次分配新会话 ID 并检查溢出，禁止复用旧输入身份。
             self.next_session = match self.next_session.checked_add(1) {
                 Some(id) => id,
                 None => {
@@ -575,6 +601,7 @@ impl Worker {
             } else {
                 session.execute_incremental(&job.source, &job.namespace, &viewports)?
             };
+            // 业务执行可能已改 VM，但展示未完成时暂不取窗口命令；PendingInput 保存结果并只恢复展示阶段。
             let commands = if session.has_pending_refresh() {
                 Vec::new()
             } else {
@@ -592,6 +619,7 @@ impl Worker {
                     result,
                 })));
             }
+            // 启动失败且残留挂起刷新时直接丢弃域，不能保留一个无法安全推进的 HTTP 请求。
             // A failed start must never leave a request waiting on a broken VM.
             self.repl = None;
         }
@@ -633,6 +661,7 @@ impl Worker {
         notify: &Notify,
     ) -> RequestProgress {
         let viewports = match namespace.read() {
+            // 正在执行输入只要仍属当前提交或仍拥有权威 VM 就可收敛；两项皆失效才彻底废弃。
             Ok(current)
                 if current.submission == input.epoch || current.runtime_session == input.id =>
             {
@@ -660,6 +689,7 @@ impl Worker {
             return RequestProgress::Complete(superseded(job.submission));
         }
         let resumed = catch_unwind(AssertUnwindSafe(|| -> Result<_> {
+            // 这里只恢复 pending 展示/尺寸工作，不再调用 execute/dispatch，所以前一个量子的源副作用不会重放。
             let document = session.resize_windows_incremental(&viewports, false)?;
             if session.has_pending_refresh() {
                 return Ok(None);
@@ -704,6 +734,7 @@ impl Worker {
         let Ok(mut current) = namespace.write() else {
             return error_response(StatusCode(500), "namespace lock is poisoned");
         };
+        // 接受新 PUT 会使排队旧输入失效，但已执行的活域输入需先收敛，才能在候选失败时留下内部一致的旧程序。
         let epoch = if current.submission != epoch {
             if current.runtime_session != id {
                 drop(current);
@@ -725,6 +756,7 @@ impl Worker {
         match result {
             Ok(Ok((result, commands))) => {
                 let projected = !commands.is_empty();
+                // rendered 只表示此次交付带新文档，成功执行但页面未变仍可返回 value/session；不因此虚增 revision。
                 let rendered = result.document.is_some();
                 if let Some(document) = result.document {
                     match current.commit(epoch, document) {
@@ -750,6 +782,7 @@ impl Worker {
                     // Preserve the first failure of this VM; subsequent
                     // rejected Console input must not hide the callback cause.
                     // A preserved picture from another generation is unrelated.
+                    // 同 VM 保留最初故障原因，后续“域已停止”错误不能覆盖真正回调故障；其他世代旧图不沿用故障。
                     let fault = (document.frame.session == id)
                         .then(|| document.frame.fault.clone())
                         .flatten()
@@ -771,6 +804,7 @@ impl Worker {
                 for view in document.windows.values_mut() {
                     view.frame.fault = document.frame.fault.clone();
                 }
+                // 输入 panic 保留最近画面但撤销运行时/命令并发布故障条，再将 self.repl 丢弃。
                 current.runtime_session = 0;
                 current.window_commands.clear();
                 let _ = current.commit(epoch, document);
@@ -828,6 +862,7 @@ impl Worker {
             }
         };
         let id = self.next_session;
+        // 候选装载运行在独立 ReplSession，未成功前不修改 self.repl，旧程序仍是权威展示来源。
         let started = catch_unwind(AssertUnwindSafe(|| {
             endor_host::ReplSession::load_incremental(
                 &job.source,
@@ -838,6 +873,7 @@ impl Worker {
             )
         }));
         let result = match started {
+            // 候选业务装载成功但布局未完成，整个候选移进 PendingRequest；不能把 None 当成空文档提交。
             Ok(Ok((runtime, None))) => {
                 return RequestProgress::Pending(PendingRequest::Candidate(Box::new(runtime)));
             }
@@ -863,6 +899,7 @@ impl Worker {
             Ok(current) if current.submission == job.submission => {
                 // Secondary native resources still belong to the old VM. Only
                 // the primary shell's current viewport applies to a candidate.
+                // 候选不沿用旧副窗口的视口；副窗口资源归旧 VM，只有主壳当前尺寸可作为新候选分配条件。
                 current
                     .viewport
                     .map(|size| (crate::window::MAIN_WINDOW, size))
@@ -886,6 +923,7 @@ impl Worker {
             if runtime.has_pending_refresh() {
                 return Ok(None);
             }
+            // 所有刷新结束仍没有 Page 文档时明确失败，不用旧显示值冒充候选自己的输出。
             let document =
                 document.ok_or_else(|| anyhow::anyhow!("program did not publish a Page"))?;
             Ok(Some((document, runtime.take_window_commands()?)))
@@ -918,6 +956,7 @@ impl Worker {
         match result {
             Ok(Ok((runtime, document, commands))) => match current.commit(job.submission, document)
             {
+                // 写锁内先原子提交文档，再切换命令世代与活域；解锁后唤醒 GUI，新 VM 至此才取代旧 VM。
                 Ok(Some(revision)) => {
                     current.publish_window_commands(id, commands);
                     self.repl = Some((job.submission, runtime));
@@ -934,6 +973,7 @@ impl Worker {
             failed => {
                 // The candidate never mutated the displayed program's heap.
                 // Restore that program's event epoch when a replacement fails.
+                // 候选失败只更新旧活域 epoch，保留其堆与页面；不存在旧域时也不会借用其他会话伪造成功。
                 self.preserve_live_owner(&current);
                 drop(current);
                 match failed {
@@ -954,6 +994,7 @@ fn build(
     namespace: &Arc<RwLock<NamespaceState>>,
     notify: &Notify,
 ) -> Response<std::io::Cursor<Vec<u8>>> {
+    // 隔离表达式不读写持久 REPL 堆，也不发布文档，响应明确 persistent=false。
     if job.kind == RequestKind::Expression {
         return match catch_unwind(AssertUnwindSafe(|| endor_host::evaluate(&job.source))) {
             Ok(Ok(value)) => json(
@@ -971,6 +1012,7 @@ fn build(
     }
     // Only an independent native snapshot crosses into the published state.
     // A fresh VM is discarded on success, error and unwind alike.
+    // 一次性构建同样用独立 VM，计算锁外执行，返回后再次核对 submission 才能发布原生快照。
     let result = catch_unwind(AssertUnwindSafe(|| {
         endor_host::compile(&job.source, &job.namespace, job.submission)
     }));

src/runtime/endor_host.rs

@@ -33,6 +33,7 @@ pub fn compile(source: &str, namespace: &str, submission: u64) -> Result<RenderD
     }
     let source = EndorReader::from_text(format!("{namespace} [submission {submission}]"), source);
     let plan = endor_script::parse(&source)?;
+    // 各 Script 根共享 AST 计数预算，不能通过拆成很多交互片段绕过整份源码节点上限。
     let mut budget = AstBudget::default();
     for ast in plan.roots() {
         budget.visit_ast_root(ast)?;
@@ -46,6 +47,7 @@ pub fn compile(source: &str, namespace: &str, submission: u64) -> Result<RenderD
         candidate.roots.push(globals);
         let bridge = ui_bridge::install(&mut candidate.vm, &mut candidate.roots)?;
         bridge.install_globals(&mut candidate.vm, globals)?;
+        // Script 多段分别执行，指令总额按片段数均分；Module 作为整体获得完整预算，避免每段都重获一百万。
         let limits = match &plan {
             SourcePlan::Module(_) => LIMITS,
             SourcePlan::Script(_) => ExecutionLimits {
@@ -67,6 +69,7 @@ pub fn compile(source: &str, namespace: &str, submission: u64) -> Result<RenderD
             SourcePlan::Script(_) => bridge
                 .rendered(&candidate.vm)?
                 .ok_or_else(|| anyhow::anyhow!("script must call ui.page().render(root)"))?,
+            // 模块先执行定义再调用 main；若 main 未显式 render，可将其返回值转换成展示根。
             SourcePlan::Module(_) => {
                 let entry = candidate
                     .vm
@@ -88,6 +91,7 @@ pub fn compile(source: &str, namespace: &str, submission: u64) -> Result<RenderD
                         Some(root) => Ok(root),
                         None => ui_bridge::snapshot(&candidate.vm, &value),
                     });
+                // 提取快照结果先暂存，成功或失败都释放 main 返回值的拥有根，再传播快照错误。
                 candidate.vm.release_value(value)?;
                 snapshot?
             }
@@ -102,6 +106,7 @@ pub fn compile(source: &str, namespace: &str, submission: u64) -> Result<RenderD
         document.validate()?;
         Ok(document)
     })();
+    // 独立构建在成功与错误路径都显式释放宿主根/回收堆；返回成功文档也要求 cleanup 成功。
     let cleanup = candidate.close();
     match (result, cleanup) {
         (Ok(document), Ok(())) => Ok(document),
@@ -117,6 +122,7 @@ pub fn evaluate(source: &str) -> Result<String> {
         bail!("expression exceeds the 1 MiB limit");
     }
     let source = EndorReader::from_text("console expression", source);
+    // 隔离 evaluate 只接受一个表达式，默认编译选项不安装 ui 桥接，也不读已发布程序的 globals。
     let ast = frontend::parse_source_ast(&source, frontend::ParseMode::Expression)?;
     AstBudget::default().visit_ast_root(&ast)?;
     let compiled = compiler::compile_ast(&ast, &source, &compiler::CompileOptions::default())
@@ -132,6 +138,7 @@ pub fn evaluate(source: &str) -> Result<String> {
             .vm
             .execute_with_limits(code, globals, LIMITS)
             .map_err(|error| runtime_error(&candidate.vm, error))?;
+        // 只把标量或对象 repr 字符串交回 API，真实 Value 随一次性 VM 清理，不跨线程交付托管引用。
         let rendered = match &value {
             Value::Nil => "nil".to_owned(),
             Value::Bool(v) => v.to_string(),
@@ -171,6 +178,7 @@ fn compile_plan_with_globals(
     // Match Aster module behavior for function forward references. Bindings are
     // added in source order; every executable statement still uses Aster's own
     // single-input Interactive compiler and the candidate's shared globals.
+    // 先收集全部函数/类声明名以支持前向引用；普通绑定仍按源码执行次序逐段加入已知全局名。
     for root in plan.roots() {
         if let AstRoot::Interactive(input) = root {
             for statement in &input.statements {
@@ -193,6 +201,7 @@ fn compile_plan_with_globals(
             compiler::compile_ast(root, source, &options)
                 .map_err(|error| source.annotate(error))?,
         );
+        // 每段编译成功才把绑定/赋值名字加入下一段编译上下文，语法与代码生成都继续委托 Aster。
         if let AstRoot::Interactive(input) = root {
             for statement in &input.statements {
                 if let StmtKind::Binding(binding) = &statement.kind {
@@ -218,6 +227,7 @@ struct PendingPaint {
 /// 跨 worker 轮次的全窗口刷新状态，保存已完成草稿和当前布局/绘制，直到稳定再发布。
 struct RefreshWork {
     // 已完成窗口的草稿先留在本轮；所有窗口收敛后才合成一次完整发布。
+    // RefreshWork 先克隆最近完整文档作为草稿基线，各窗口更新暂存于此；全轮稳定前不写共享 NamespaceState。
     documents: std::collections::BTreeMap<u64, RenderDocument>,
     windows: std::collections::VecDeque<u64>,
     current: Option<u64>,
@@ -249,6 +259,7 @@ pub struct ReplSession {
     ast_nodes: usize,
     source: String,
     nodes: Vec<CodeNode>,
+    // 回调/渲染失败后置位，拒绝继续普通业务输入；保留画面不表示堆还能安全执行。
     faulted: bool,
     program_root: Option<CodeNode>,
     documents: std::collections::BTreeMap<u64, RenderDocument>,
@@ -308,6 +319,7 @@ impl ReplSession {
             .into_iter()
             .collect();
         let document = runtime.refresh_after_mutation(Some(&viewports))?;
+        // 初始刷新若已完成必须确实有 Page 文档才可接受候选；仍挂起则把整个运行时交 worker 下一量子继续。
         if !runtime.has_pending_refresh() {
             anyhow::ensure!(document.is_some(), "program did not publish a Page");
             runtime
@@ -339,6 +351,7 @@ impl ReplSession {
         runtime
             .bridge
             .set_viewport(&mut runtime.candidate.vm, viewport)?;
+        // 完整程序代码在候选自己的真实 globals 中执行，之后保留该堆用于事件与 Console，不通过重放历史恢复状态。
         let globals = runtime.candidate.globals.expect("program globals");
         let limits = if matches!(plan, SourcePlan::Script(_)) {
             ExecutionLimits {
@@ -372,6 +385,7 @@ impl ReplSession {
                 .vm
                 .call_with_limits(main, &[], LIMITS)
                 .map_err(|error| runtime_error(&runtime.candidate.vm, error))?;
+            // main 已主动打开 Page 时尊重其选择；否则把返回值经展示协议打开，不能重复创建第二个默认页面。
             let opened = if runtime.bridge.has_page()? {
                 Ok(())
             } else {
@@ -385,6 +399,7 @@ impl ReplSession {
         }
         runtime.source = source.into();
         runtime.ast_nodes = budget.nodes;
+        // 保存完整程序的 Sources 投影，后续 Console 追加时可移入交互记录树；不把 AST 投影当可执行堆对象。
         runtime.program_root = Some(architecture(&unit, &plan, namespace, submission));
         Ok(runtime)
     }
@@ -398,7 +413,7 @@ impl ReplSession {
         Ok(runtime)
     }
 
-    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
+    /// 建立真实持久 VM、全局字典与 UI 桥接根，尚未执行用户输入或产生窗口帧。
     pub fn new(id: u64) -> Result<Self> {
         let mut candidate = Candidate::new()?;
         let globals = candidate.vm.new_dict()?;
@@ -452,6 +467,7 @@ impl ReplSession {
         if source.len() > MAX_SOURCE_BYTES {
             bail!("input exceeds 1 MiB");
         }
+        // 持久 Console 限制累计输入次数、源码文本和稍后的 AST 总节点数，用户需显式重置才能重新获得预算。
         if self.inputs >= 256 || self.source.len() + source.len() + 80 > MAX_SOURCE_BYTES {
             bail!("console session exceeds 256 inputs or 1 MiB; reset the session to continue");
         }
@@ -468,6 +484,7 @@ impl ReplSession {
             bail!("console session exceeds 10000 AST nodes; reset the session to continue");
         }
         let globals = self.candidate.globals.expect("live console globals");
+        // 从实际 globals 枚举已有名称供增量编译，支持前次输入创建的真实对象，而非靠解析历史猜名称。
         let names = self
             .candidate
             .vm
@@ -487,6 +504,7 @@ impl ReplSession {
         self.bridge.discard_pending(&mut self.candidate.vm)?;
         self.bridge
             .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)?;
+        // 解析/编译全部成功后才记本轮输入与源码；之后运行失败仍可能保留此前语句副作用，不做事务回滚。
         self.inputs += 1;
         self.ast_nodes += budget.nodes;
         if let Some(root) = self.program_root.take() {
@@ -495,6 +513,7 @@ impl ReplSession {
         if !self.source.is_empty() && !self.source.ends_with('\n') {
             self.source.push('\n');
         }
+        // 交互源码前加 Console input 注释分隔，投影节点行号再整体平移到累计 transcript 中。
         let offset = line_starts(&self.source).len();
         self.source
             .push_str(&format!("// Console input {}\n", self.inputs));
@@ -527,6 +546,7 @@ impl ReplSession {
                 self.candidate.vm.release(code)?;
                 let value = executed?;
                 // Keep the actual last result accessible as `_`, including unnamed UI objects.
+                // 绑定/赋值语句展示其新变量实际值，普通表达式展示返回值；不是仅显示该语句执行的 Unit。
                 let display = if let AstRoot::Interactive(input) = ast {
                     match &input.statements[0].kind {
                         StmtKind::Binding(binding) => self
@@ -544,6 +564,7 @@ impl ReplSession {
                 } else {
                     value.clone()
                 };
+                // 先算 repr 并把实际最后值写入全局 _，保留未命名 UI 对象；随后释放 execute 返回根，错误也逐项传播。
                 let repr = value_repr(&self.candidate.vm, &display);
                 let retained =
                     self.candidate
@@ -566,6 +587,7 @@ impl ReplSession {
                 input: self.inputs,
             })
         })();
+        // 失败丢弃未发布展示请求和原生命令，保留已执行业务写入，并在代码投影上明确标记非事务语义。
         if result.is_err() {
             self.take_window_commands()?;
             self.bridge.discard_pending(&mut self.candidate.vm)?;
@@ -574,6 +596,7 @@ impl ReplSession {
                     .push_str(" (error; earlier statements may remain live)");
             }
         }
+        // 未完成只读续体仍持有临时结果，不在中途执行完整 reclaim；等刷新结束后再回收不可达宿主根。
         if !self.has_pending_refresh() {
             self.bridge
                 .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)?;
@@ -605,6 +628,7 @@ impl ReplSession {
         &mut self,
         viewports: Option<&std::collections::BTreeMap<u64, crate::layout::Size>>,
     ) -> Result<Option<RenderDocument>> {
+        // 无增量视口参数的测试/同步入口排空状态机；worker 提供目标视口时只推进一次并记录重定向依据。
         let Some(viewports) = viewports else {
             return self.refresh_document();
         };
@@ -632,6 +656,7 @@ impl ReplSession {
 
     /// 推进一次刷新状态机，保存挂起的 Work；只有全窗口收敛时才生成可发布文档。
     fn poll_refresh(&mut self, record_yield: bool) -> Result<RefreshProgress> {
+        // 从 self 取出工作以便可变推进，挂起时放回；首次从已发布各窗口文档克隆初始草稿。
         let mut work = self.refresh.take().unwrap_or_else(|| RefreshWork {
             documents: self.documents.clone(),
             windows: Default::default(),
@@ -659,6 +684,7 @@ impl ReplSession {
                 self.refresh = Some(work);
                 Ok(RefreshProgress::Pending)
             }
+            // 收敛后统一组合文档，再恢复主窗口选择；收尾失败也标故障，不把失败草稿当已发布帧。
             Ok(true) => {
                 let result = self.finish_refresh(work);
                 self.bridge.select_window(crate::window::MAIN_WINDOW)?;
@@ -669,6 +695,8 @@ impl ReplSession {
             }
             Err(error) => {
                 self.faulted = true;
+                // 错误时必须显式取消 paint/layout 的 owning VM 续体并恢复检查点，不能仅丢弃 Rust 工作结构。
+                // 进入 paint 后只恢复其原续体和配对文档，不重复布局，也不重跑输入业务语句。
                 if let Some(paint) = work.paint.take() {
                     self.bridge.cancel_paint_frame(
                         &mut self.candidate.vm,
@@ -689,6 +717,7 @@ impl ReplSession {
     /// 执行一个刷新步骤：刷新绑定、选择窗口、准备快照、推进布局或绘制，并决定是否需要下一轮。
     fn step_refresh(&mut self, work: &mut RefreshWork) -> Result<bool> {
         // 阶段一：新一轮先刷新绑定，再取得稳定窗口遍历顺序。
+        // 每轮先使属性绑定达到固定点，再取窗口顺序；生命周期或绑定可能改变窗口/页面结构，因此需要多轮确认。
         if work.pass_start {
             self.bridge.refresh_bindings(&mut self.candidate.vm)?;
             work.windows = self.bridge.window_ids()?.into();
@@ -703,6 +732,7 @@ impl ReplSession {
                 work.current = Some(id);
                 return Ok(false);
             }
+            // 任何窗口本轮生成新帧，就再扫描一轮检查依赖和挂载回调是否又引起变化，直到整轮无变化。
             if work.pass_changed {
                 work.pass_start = true;
                 return Ok(false);
@@ -758,6 +788,7 @@ impl ReplSession {
         };
         document.frame.session = self.id;
         document.validate()?;
+        // 跨所有窗口和稳定轮次累计布局工作，空帧也计一，防止持续无几何变化请求绕过收敛预算。
         work.work += document.frame.mounts.len().max(1);
         if work.work > 200_000 {
             bail!("layout dependencies did not stabilize within the rendering work budget");
@@ -788,6 +819,7 @@ impl ReplSession {
             crate::source_paint::Progress::Complete(draft) => {
                 document.frame = draft.frame;
                 document.validate()?;
+                // 只有整个绘制 Complete 且验证通过才替换当前窗口草稿；Pending 保留配对文档和 Work，不对 GUI 可见。
                 work.documents.insert(id, document);
                 work.pass_changed = true;
                 work.changed = true;
@@ -798,6 +830,7 @@ impl ReplSession {
 
     /// 收敛后组合所有窗口文档，保留本轮完整结果；没有变化时不额外制造发布。
     fn finish_refresh(&mut self, mut work: RefreshWork) -> Result<Option<RenderDocument>> {
+        // 收敛后完成已关闭窗口退役并删其旧文档；没有实际变化时不制造额外 revision。
         self.bridge.finish_closed(&mut self.candidate.vm)?;
         let ids = self.bridge.window_ids()?;
         work.documents.retain(|id, _| ids.contains(id));
@@ -818,12 +851,14 @@ impl ReplSession {
                 ..Default::default()
             });
         main.source = self.source.clone();
+        // 优先采用源码与当前 transcript 相同的窗口代码投影，避免主窗口未重绘时 Sources 仍展示旧输入树。
         main.root = work
             .documents
             .values()
             .find(|document| document.source == self.source)
             .and_then(|document| document.root.clone())
             .or(main.root);
+        // 副窗口统一挂到主文档 windows 一层，子文档自身不再嵌套副窗口，最终 validate 检查完整跨线程值。
         main.windows = work
             .documents
             .iter()
@@ -852,6 +887,7 @@ impl ReplSession {
         let Some(mut work) = self.refresh.take() else {
             return Ok(());
         };
+        // 记录实际取消了哪类续体用于诊断；已完成窗口草稿和已发生业务副作用不会因此回滚。
         let cancelled = work.pending.is_some();
         let cancelled_paint = work.paint.is_some();
         if let Some(paint) = work.paint.take()
@@ -877,6 +913,7 @@ impl ReplSession {
         // Keep completed window drafts and callback effects. Only the pending
         // window's speculative Mount state was restored. A new external target
         // begins a fresh convergence budget, not a continuation of a bad cycle.
+        // 重新从全窗口稳定轮开始，清当前选择/旧根并重置此次外部尺寸目标的收敛工作预算；草稿 documents 保留。
         work.windows.clear();
         work.current = None;
         work.root = None;
@@ -897,6 +934,7 @@ impl ReplSession {
         if self.faulted {
             bail!("runtime stopped after a callback or rendering failure");
         }
+        // 仅目标视口集合确实不同才取消重定向；同一目标的下一 worker 轮继续原续体，不重复从头布局。
         let retarget = self
             .refresh
             .as_ref()
@@ -905,6 +943,7 @@ impl ReplSession {
         if retarget {
             self.retarget_refresh(viewports)?;
         }
+        // 同目标 drain=true 同步排空旧刷新并保存完整结果；drain=false 只推进一量子，不能先执行新的尺寸变更。
         let previous = if self.has_pending_refresh() && !retarget {
             if drain {
                 let result = self.refresh_document();
@@ -917,6 +956,7 @@ impl ReplSession {
         };
         let ids = self.bridge.window_ids()?;
         let mut changed = false;
+        // 仅更新桥接仍注册的窗口；旧 GUI 尺寸记录不应在新域里隐式创建窗口资源。
         for (id, viewport) in viewports {
             if ids.contains(id) {
                 self.bridge.select_window(*id)?;
@@ -926,6 +966,7 @@ impl ReplSession {
             }
         }
         self.bridge.select_window(crate::window::MAIN_WINDOW)?;
+        // 尺寸没变且无挂起工作则直接返回先前已完成文档，避免制造无意义新帧。
         if !changed && !self.has_pending_refresh() {
             return Ok(previous);
         }
@@ -989,10 +1030,12 @@ impl ReplSession {
         &mut self,
         viewports: Option<&std::collections::BTreeMap<u64, crate::layout::Size>>,
     ) -> Result<Option<RenderDocument>> {
+        // 异步回调不能插入只读布局/绘制续体中，即使后台邮箱已有结果也等刷新空闲边界。
         if self.has_pending_refresh() {
             return Ok(None);
         }
         if self.faulted {
+            // 故障域不执行任何新用户任务，仅取消已有任务并在确实移除工作后回收引用。
             if self.bridge.cancel_tasks(&mut self.candidate.vm)? > 0 {
                 self.bridge
                     .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)?;
@@ -1001,6 +1044,7 @@ impl ReplSession {
         }
         let mut completed = false;
         let result = (|| {
+            // worker 增量轮至多启动一个任务推进，给前台输入和窗口刷新公平机会；同步路径单轮允许64项。
             let limit = if viewports.is_some() { 1 } else { 64 };
             if self.bridge.poll_tasks(&mut self.candidate.vm, limit)? == 0 {
                 return Ok(None);
@@ -1014,6 +1058,7 @@ impl ReplSession {
             self.take_window_commands()?;
             self.bridge.discard_pending(&mut self.candidate.vm)?;
         }
+        // 任务推进或失败后才需回收，并且不能在仍有只读续体时清理其临时根。
         if (completed || result.is_err()) && !self.has_pending_refresh() {
             self.bridge
                 .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)?;
@@ -1070,6 +1115,7 @@ impl ReplSession {
 
     /// 有界关闭任务、挂载和窗口，释放运行时根，并报告清理结果。
     pub fn shutdown(&mut self) -> Result<(usize, usize, usize)> {
+        // 先取消视觉续体恢复挂载检查点，再判断原域是否允许正常关闭回调，随后标故障禁止后续普通执行。
         self.cancel_pending_refresh()?;
         let callbacks = !self.faulted;
         self.faulted = true;
@@ -1082,6 +1128,7 @@ impl ReplSession {
         // This path is exclusively host cleanup after the domain has stopped.
         // No language functions, layout, paint or lifecycle hooks may run here.
         self.faulted = true;
+        // 专用退役只清宿主资源，不调源生命周期；删除已缓存文档和窗口命令，避免后续重发该副窗口。
         self.bridge.retire_window(&mut self.candidate.vm, id)?;
         self.documents.remove(&id);
         let _ = self.take_window_commands()?;
@@ -1129,12 +1176,14 @@ impl ReplSession {
         if self.faulted {
             bail!("runtime stopped after a callback or rendering failure");
         }
+        // 即使绕过 HTTP 入口直接调用，也再校验会话身份；共享窗口数值 ID 不提供跨 VM 权限。
         if input.session != self.id {
             bail!("event belongs to another runtime session");
         }
         if !self.accepts_tab_drop(input) {
             bail!("drop targets an obsolete presentation");
         }
+        // 将 ui.window/viewport 等隐式上下文切到事件所属窗口，分发后统一恢复主窗口。
         self.bridge.select_window(input.window)?;
         let result = (|| {
             self.bridge.dispatch(&mut self.candidate.vm, input)?;
@@ -1154,6 +1203,7 @@ impl ReplSession {
         self.bridge.select_window(crate::window::MAIN_WINDOW)?;
         if result.is_err() {
             self.take_window_commands()?;
+            // 回调失败属于共享 VM 故障，不只关闭单个按钮；丢弃未发布命令与 pending 请求，但不重放已执行写入。
             self.faulted = true;
             self.bridge.discard_pending(&mut self.candidate.vm)?;
         }
@@ -1166,8 +1216,9 @@ impl ReplSession {
 }
 
 impl Drop for ReplSession {
-    /// 在 Rust 所有者离开作用域时执行本类型的配套清理；不能用它代替需要报告错误的显式关闭。
+    /// 析构兜底取消会话中未完成的布局/绘制续体；需要观察清理错误或运行退出钩子的路径仍须显式 shutdown。
     fn drop(&mut self) {
+        // Drop 最后兜底取消未完成视觉工作，错误无法从析构返回；需要报告清理错误的路径必须显式 shutdown。
         let _ = self.cancel_pending_refresh();
     }
 }
@@ -1210,9 +1261,11 @@ impl Candidate {
 
     /// 释放候选拥有的宿主根并清理 VM；通过显式关闭保证错误也能被报告。
     fn close(&mut self) -> Result<()> {
+        // 清全局字典先断业务对象可达根，再逆序释放宿主分配根；最后执行循环回收并验证对象计数归零。
         if let Some(globals) = self.globals.take() {
             self.vm.dict_clear(globals)?;
         }
+        // pop 逐项移出确保再次 close 不重复释放已成功处理的根；错误仍交显式关闭调用方报告。
         while let Some(root) = self.roots.pop() {
             self.vm.release(root)?;
         }
@@ -1225,16 +1278,16 @@ impl Candidate {
 }
 
 impl Drop for Candidate {
-    /// 在 Rust 所有者离开作用域时执行本类型的配套清理；不能用它代替需要报告错误的显式关闭。
+    /// 析构调用 Candidate.close 释放候选根和 VM，覆盖提前返回/异常展开；析构不能向调用者报告清理错误。
     fn drop(&mut self) {
-        // Explicit close reports accounting errors; dropping the fresh VM is
-        // also the final cleanup boundary on every early return or unwind.
+        // 显式 close 可以报告引用计数/清理错误；Drop 则保证提前返回和异常展开仍经过最终清理边界。
         let _ = self.close();
     }
 }
 
 /// 把 VM 错误与当前源位置/调用栈组合成用户可读的诊断。
 pub(crate) fn runtime_error(vm: &Vm, error: VmError) -> anyhow::Error {
+    // 错误发生后立即读取 VM traceback，保留函数、源文件与指令偏移；无栈信息时直接保留原 VmError。
     let locations = vm
         .last_traceback()
         .iter()
@@ -1264,6 +1317,7 @@ impl Visitor for AstBudget {
     type Error = anyhow::Error;
     /// 更新源结构遍历的深度/数量预算，拒绝超出允许范围的语法树。
     fn enter_node(&mut self, _span: Span) -> Result<()> {
+        // 每次进入节点累计总数和当前深度；leave 只归还深度，整份输入总量不会因退出子树重置。
         self.depth += 1;
         self.nodes += 1;
         if self.depth > MAX_AST_DEPTH || self.nodes > MAX_AST_NODES {
@@ -1284,6 +1338,7 @@ fn architecture(
     namespace: &str,
     submission: u64,
 ) -> CodeNode {
+    // CodeNode ID 由 namespace/submission 和本次递增序号构成，只是 Sources 投影身份，不是托管对象地址。
     let mut tree = Architecture {
         line_starts: line_starts(source.text()),
         next_id: 0,
@@ -1305,6 +1360,7 @@ fn architecture(
         }
     }
     let roots = plan.roots();
+    // 整体范围取首根起点至末根终点，Script 的多个交互片段在原始文本中的 span 已恢复偏移。
     let span = Span::new(
         roots.first().map_or(0, |root| root.span().start),
         roots.last().map_or(0, |root| root.span().end),
@@ -1320,6 +1376,7 @@ fn architecture(
 /// 建立源文本每行起点表，供字节 span 转换为行列位置。
 fn line_starts(source: &str) -> Vec<usize> {
     let bytes = source.as_bytes();
+    // 按字节扫描行终止符，CRLF 仅在 LF 记一次，孤立 CR 也换行；空文本仍保留第1行起点0。
     let mut starts = vec![0];
     for (offset, byte) in bytes.iter().enumerate() {
         if *byte == b'\n' || (*byte == b'\r' && bytes.get(offset + 1) != Some(&b'\n')) {
@@ -1337,10 +1394,11 @@ struct Architecture {
 }
 
 impl Architecture {
-    /// 将相应语法结构投影为带源码范围的 CodeNode，供 Sources 展示和定位。
+    /// 分配本投影内节点 ID，并将半开字节 span 映射为1基起止行，组装 CodeNode。
     fn node(&mut self, name: String, kind: &str, span: Span, children: Vec<CodeNode>) -> CodeNode {
         let id = self.next_id;
         self.next_id += 1;
+        // partition_point 返回不大于 offset 的行首数量，天然得到1基行号；span.end 是半开端，先减1找最后实际字符行。
         let line = |offset| self.line_starts.partition_point(|start| *start <= offset);
         CodeNode {
             id: format!("{}:ast-{id}", self.identity),
@@ -1352,11 +1410,12 @@ impl Architecture {
         }
     }
 
-    /// 将相应语法结构投影为带源码范围的 CodeNode，供 Sources 展示和定位。
+    /// 区分函数与类声明；类下先投影字段，再投影方法。
     fn declaration(&mut self, declaration: &Decl) -> CodeNode {
         match &declaration.kind {
             DeclKind::Function(function) => self.function(function),
             DeclKind::Class(class) => {
+                // 类投影先列字段再列方法；只复制显示名称和范围，不把声明 AST 当可执行对象保存。
                 let mut children: Vec<_> = class
                     .fields
                     .iter()
@@ -1368,8 +1427,9 @@ impl Architecture {
         }
     }
 
-    /// 将相应语法结构投影为带源码范围的 CodeNode，供 Sources 展示和定位。
+    /// 将函数声明及其体内语句投影为一个带源码范围的 function 节点。
     fn function(&mut self, function: &frontend::ast::Function) -> CodeNode {
+        // 函数投影按函数体语句顺序递归展开，不单独生成参数节点；展示范围仍覆盖完整函数声明。
         let children = function
             .body
             .statements
@@ -1384,9 +1444,10 @@ impl Architecture {
         )
     }
 
-    /// 将相应语法结构投影为带源码范围的 CodeNode，供 Sources 展示和定位。
+    /// 按赋值、返回、表达式和声明种类构建 Sources 层次，保留真实子表达式关系。
     fn statement(&mut self, statement: &Stmt) -> CodeNode {
         match &statement.kind {
+            // 成员赋值投影两个子表达式：目标对象和右值，成员名作为本节点显示名称。
             StmtKind::MemberAssignment(assignment) => {
                 let object = self.expression(&assignment.object);
                 let value = self.expression(&assignment.value);
@@ -1428,13 +1489,15 @@ impl Architecture {
         }
     }
 
-    /// 将相应语法结构投影为带源码范围的 CodeNode，供 Sources 展示和定位。
+    /// 递归投影表达式层次，用简短文本作显示名，并保留完整原始 span。
     fn expression(&mut self, expr: &Expr) -> CodeNode {
         let (name, kind, children) = match &expr.kind {
             ExprKind::Name(name) => (name.clone(), "name", vec![]),
             ExprKind::Number(value) => (value.clone(), "number", vec![]),
+            // 字符串展示名最多40个 Unicode 字符，但 span 保留整段字面量，截断标签不影响源码选择范围。
             ExprKind::String(value) => (value.chars().take(40).collect(), "string", vec![]),
             ExprKind::Symbol(name) => (name.text.clone(), "symbol", vec![]),
+            // 当前代码投影把 Unary 和 Await 共用 unary/negate 显示标签；这是展示简化，不表示 await 执行成取负。
             ExprKind::Unary { operand, .. } | ExprKind::Await(operand) => {
                 ("negate".into(), "unary", vec![self.expression(operand)])
             }
@@ -1447,6 +1510,7 @@ impl Architecture {
                 (name.text.clone(), "member", vec![self.expression(object)])
             }
             ExprKind::Call { callee, arguments } => {
+                // 调用目标作为首个孩子，随后按原顺序列实参，Sources 可以区分调用表达式和参数层次。
                 let mut children = vec![self.expression(callee)];
                 children.extend(arguments.iter().map(|expr| self.expression(expr)));
                 ("call".into(), "call", children)

src/runtime/endor_script.rs

@@ -26,22 +26,26 @@ impl SourcePlan {
     }
 }
 
-/// 把外部源码或属性表示转换为内部枚举/结构，并反馈不支持的输入。
+/// 优先解析完整模块，否则按可完成的交互输入分段为 Script，并将 AST/诊断位置映回原文。
 pub fn parse(source: &SourceUnit) -> Result<SourcePlan> {
+    // 完整模块优先；只有模块解析失败才退回连续交互输入模式，宿主不自行实现 Endor 语法。
     if let Ok(module) = frontend::parse_source_ast(source, ParseMode::Module) {
         return Ok(SourcePlan::Module(module));
     }
+    // 一次词法分析获得原始字节 span，候选分段依赖 token 之间的实际换行而非直接按行切字符串。
     let tokens = frontend::lex_source(source)?;
     let mut roots = Vec::new();
     let mut start = 0;
     let mut depth = 0_i64;
     for (index, token) in tokens.iter().enumerate() {
+        // 追踪圆/花括号嵌套，括号内换行不能直接结束输入；最终语法是否合法仍交给 Aster。
         match token.kind {
             TokenKind::LeftParen | TokenKind::LeftBrace => depth += 1,
             TokenKind::RightParen | TokenKind::RightBrace => depth -= 1,
             _ => {}
         }
         let end = token.span.end;
+        // 末尾 token 总是尝试解析；非末尾要求顶层换行，且下一 token 不像成员访问、调用或算术续接。
         let boundary = tokens.get(index + 1).is_none_or(|next| {
             depth == 0
                 && source.text()[end..next.span.start].contains(['\r', '\n'])
@@ -58,25 +62,30 @@ pub fn parse(source: &SourceUnit) -> Result<SourcePlan> {
         if !boundary {
             continue;
         }
+        // 当前片段从上一次成功边界 start 开始，保留期间的空白与注释；解析器看到的是片段局部字节位置。
         match frontend::parse_ast(&source.text()[start..end], ParseMode::Interactive) {
             Ok(mut root) => {
                 let AstRoot::Interactive(input) = &mut root else {
                     unreachable!("interactive mode");
                 };
+                // 成功后递归加回 start，把整个 AST 的局部 span 转成原文件位置，再推进下一段起点。
                 shift_input(input, start);
                 roots.push(root);
                 start = end;
             }
             // An incomplete interactive input can continue on the next line.
             // Only Aster decides whether its combined syntax is valid.
+            // 错误恰在片段末尾且还有 token 时，视为可能未完成的交互输入，保持 start 不动继续拼接。
             Err(diagnostic) if index + 1 < tokens.len() && diagnostic.span.start == end - start => {
             }
             Err(mut diagnostic) => {
+                // 其他语法错误立即恢复原始偏移，再用 SourceUnit 添加原文件来源与行列诊断。
                 shift_span(&mut diagnostic.span, start);
                 return Err(source.annotate(diagnostic).into());
             }
         }
     }
+    // 空输入不能静默产生空计划；再次委托交互入口给出解析器自己的空输入诊断与来源。
     if roots.is_empty() {
         // Produce Aster's original empty-input diagnostic and provenance.
         frontend::parse_source_ast(source, ParseMode::Interactive)?;
@@ -84,8 +93,9 @@ pub fn parse(source: &SourceUnit) -> Result<SourcePlan> {
     Ok(SourcePlan::Script(roots))
 }
 
-/// 递归调整对应语法节点的源码范围，保持片段解析后的错误位置仍指向原输入。
+/// 为单个半开字节范围加回片段起始偏移，不处理其所属节点的子节点。
 fn shift_span(span: &mut Span, offset: usize) {
+    // span 采用原文本字节偏移，start/end 同增 offset 保持长度；不是按字符数或行数偏移。
     span.start += offset;
     span.end += offset;
 }
@@ -93,6 +103,7 @@ fn shift_span(span: &mut Span, offset: usize) {
 /// 递归调整对应语法节点的源码范围，保持片段解析后的错误位置仍指向原输入。
 fn shift_input(input: &mut InteractiveInput, offset: usize) {
     shift_span(&mut input.span, offset);
+    // 根范围之外，逐条语句递归处理所有内层节点，避免错误只在顶层位置正确。
     for statement in &mut input.statements {
         shift_statement(statement, offset);
     }
@@ -112,6 +123,7 @@ fn shift_statement(statement: &mut Stmt, offset: usize) {
             shift_span(&mut assignment.name.span, offset);
             shift_expression(&mut assignment.value, offset);
         }
+        // 成员赋值同时包含目标对象表达式、成员名和右值，三部分都要恢复原始位置。
         StmtKind::MemberAssignment(assignment) => {
             shift_span(&mut assignment.span, offset);
             shift_span(&mut assignment.name.span, offset);
@@ -134,6 +146,7 @@ fn shift_declaration(declaration: &mut Decl, offset: usize) {
     shift_span(&mut declaration.span, offset);
     match &mut declaration.kind {
         DeclKind::Function(function) => shift_function(function, offset),
+        // 类的名称、基类、字段类型和方法均保存独立 span，不能仅移动声明外层范围。
         DeclKind::Class(class) => {
             shift_span(&mut class.span, offset);
             shift_span(&mut class.name.span, offset);
@@ -157,6 +170,7 @@ fn shift_function(function: &mut frontend::ast::Function, offset: usize) {
     shift_span(&mut function.span, offset);
     shift_span(&mut function.name.span, offset);
     shift_span(&mut function.return_type.span, offset);
+    // 参数自身、名称、类型各有范围；函数返回类型和函数体范围也独立移动。
     for parameter in &mut function.parameters {
         shift_span(&mut parameter.span, offset);
         shift_span(&mut parameter.name.span, offset);
@@ -172,6 +186,7 @@ fn shift_function(function: &mut frontend::ast::Function, offset: usize) {
 fn shift_expression(expression: &mut Expr, offset: usize) {
     shift_span(&mut expression.span, offset);
     match &mut expression.kind {
+        // 这些叶节点只用表达式外层 span；Symbol/Member 的名称还保存额外 span，需继续调整。
         ExprKind::Name(_) | ExprKind::Number(_) | ExprKind::String(_) => {}
         ExprKind::Symbol(name) => shift_span(&mut name.span, offset),
         ExprKind::Unary { operand, .. } | ExprKind::Await(operand) => {
@@ -185,6 +200,7 @@ fn shift_expression(expression: &mut Expr, offset: usize) {
             shift_expression(object, offset);
             shift_span(&mut name.span, offset);
         }
+        // 调用目标可继续是成员/调用等复合表达式；逐个递归实参而非只改整个 Call 的范围。
         ExprKind::Call { callee, arguments } => {
             shift_expression(callee, offset);
             for argument in arguments {

src/runtime/event_dispatch.rs

@@ -1,5 +1,5 @@
 //! 托管事件与订阅的传播实现。Connection 持有回调引用，Event 保存目标、阶段与停止传播状态。
-//! 分发沿出现关系执行 capture → target → bubble，并处理默认行为；只有同一 VM 中的回调可以接触托管对象。
+//! 分发沿出现关系执行 capture → target → bubble，记录默认行为阻止状态；只有同一 VM 中的回调可以接触托管对象。
 //!
 //! Managed subscriptions and occurrence-specific propagation. A validated VM
 //! function sequences calls, so all handlers share one execution budget.
@@ -9,6 +9,7 @@ use endor_core::{
     Value, Vm, VmError, WeakObjectRef,
 };
 
+// 一次分发最多安排 10000 个处理器，另由共享 VM 驱动约束全部回调的总执行预算。
 const MAX_DELIVERIES: usize = 10_000;
 /// 统一构造本模块的参数错误，让调用方停止处理无效输入。
 fn invalid(message: &'static str) -> VmError {
@@ -26,6 +27,7 @@ pub fn validate_handler(
     let arity = store
         .call_arity(function)?
         .ok_or(invalid("event handler requires positional metadata"))?;
+    // 允许无参便捷回调或单 Event 回调；实际递送时优先传 Event（若接受一参），否则零参调用。
     if !arity.accepts(0) && !arity.accepts(1) {
         return Err(invalid(
             "event handler must accept zero arguments or one Event",
@@ -37,10 +39,15 @@ pub fn validate_handler(
 #[derive(Debug, Clone, Default)]
 /// 本次传播的托管事件状态，包含目标、当前阶段和阻止默认/停止传播控制。
 pub struct Event {
+    // 弱引用本轮 guard，检测同一 Event 是否正在分发；驱动释放后 guard 消失，事件可再次使用。
     dispatch: Option<WeakObjectRef>,
+    // 当前传播组，一般对应路径中的一个出现/阶段；目标捕获与目标非捕获共用一组。
     group: usize,
+    // stopPropagation 记下当前组，只阻止后续其他组；同组余下处理器仍执行。
     stopped_at: Option<usize>,
+    // stopImmediatePropagation 全局跳过后续 Delivery，连当前组剩余处理器也停止。
     immediate: bool,
+    // preventDefault 仅记录默认行为是否被阻止；本模块不在这里实现具体的系统默认动作。
     prevented: bool,
 }
 impl ObjectPayload for Event {
@@ -122,12 +129,12 @@ enum Method {
     Connected,
 }
 impl NativeCallable for Method {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 事件与订阅查询/控制方法无显式参数，只接受隐式 Event 或 Subscription 接收者。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(1))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 按操作读取或修改连接/传播状态；断开清除真实 handler/compute，停止标志写回同一 Event。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let [Value::Object(owner)] = args else {
             return Err(invalid("event method receiver"));
@@ -139,6 +146,7 @@ impl NativeCallable for Method {
                     .payload::<Subscription>(*owner, "Subscription")?
                     .connection;
                 let connection = cx.upgrade(weak)?;
+                // Subscription 同时包装事件 Connection 和属性 Binding；按 payload 类型清 handler 或 compute。
                 let connected = if let Some(connection) = connection {
                     if cx
                         .store()
@@ -152,6 +160,7 @@ impl NativeCallable for Method {
                             .payload::<crate::binding::Binding>(connection, "Binding")?
                             .clone();
                         let connected = data.compute.is_some();
+                        // 取消切断真实强拥有边，外部仍可保留 token，但 token 弱引用本身不保活回调或目标。
                         if matches!(self, Self::Disconnect) {
                             data.compute = None;
                             cx.replace_payload(connection, data)?;
@@ -210,16 +219,17 @@ impl NativeCallable for Constructor {
     fn signature(&self) -> Option<endor_core::CallSignature> {
         self.signature.clone()
     }
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 至少接收隐式请求 Type 和事件 kind，额外参数留给源子类声明字段。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::range(2, usize::MAX))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 先验证事件子类字段数量与注解，再创建原生 Event 并填充声明字段，错误不得留下部分实例。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let [Value::Object(definition), Value::Text(kind), values @ ..] = args else {
             return Err(invalid("Event requires an event kind"));
         };
+        // 事件子类构造先验证额外字段参数数量与注解，再创建默认事件并逐字段初始化。
         let fields = cx
             .store()
             .payload::<endor_core::EndorTypeObject>(*definition, "Type")?
@@ -250,6 +260,7 @@ pub fn new_event(
     let event = cx.allocate(Event::default())?;
     cx.attach_type(event, definition)?;
     cx.set_attr(event, "kind", Value::Text(kind.into()))?;
+    // 新事件尚未递送，目标、出现与 hit 都为空；kind 保留输入种类，phase 初始 none。
     for name in ["target", "mount", "currentTarget", "currentMount", "hit"] {
         cx.set_attr(event, name, Value::Nil)?;
     }
@@ -268,7 +279,7 @@ impl NativeCallable for TypedMethod {
     fn signature(&self) -> Option<endor_core::CallSignature> {
         Some(self.signature.clone())
     }
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 把已声明签名的调用交给内部 Method，复用事件/订阅控制实现，不创建第二套状态。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         self.method.invoke(cx, args)
     }
@@ -294,6 +305,7 @@ pub fn install(
         (token_type, "disconnect", Method::Disconnect),
         (token_type, "isConnected", Method::Connected),
     ] {
+        // isDefaultPrevented/isConnected 返回 Bool 且只读；控制传播和取消方法返回 Unit 并声明 Mutating。
         let query = matches!(method, Method::Prevented | Method::Connected);
         let function = vm.allocate(ContextNativeFunction::new(
             name,
@@ -340,18 +352,20 @@ struct Delivery {
     handler: Handler,
 }
 impl NativeCallable for Delivery {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 单次递送步骤的 Event/handler/阶段已保存在适配器中，执行时不再接收参数。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 轮到该处理器时重查传播状态和连接是否仍有效，更新当前阶段/目标，再按真实回调 arity 发出 VM 调用。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
         let mut event = cx.store().payload::<Event>(self.event, "Event")?.clone();
+        // 真正轮到处理器时重新读取传播状态，之前回调的 stop 操作立即影响后续项，无需重建序列。
         if event.immediate || event.stopped_at.is_some_and(|group| group != self.group) {
             return Ok(NativeResult::Return(Value::Nil));
         }
         let (function, mut arguments) = match self.handler {
+            // 序列只捕获 Connection，不快照 handler；前面处理器取消它后，这里看到 None 并跳过。
             Handler::Token(token) => {
                 let Some(handler) = cx
                     .store()
@@ -363,6 +377,7 @@ impl NativeCallable for Delivery {
                 (handler, vec![])
             }
             Handler::Legacy(function) => (function, vec![]),
+            // 对象协议在执行到该项时解析实际类型的 onEvent；显式 receiver 先放入实参向量。
             Handler::ObjectMethod => {
                 let Some(definition) = cx.store().type_of(self.owner)? else {
                     return Err(invalid("untyped event target"));
@@ -374,6 +389,7 @@ impl NativeCallable for Delivery {
                 (function, vec![Value::Object(self.owner)])
             }
         };
+        // 调用前更新 currentTarget/currentMount/phase，处理器观察到的是当前路径项，不会误用最终目标。
         event.group = self.group;
         cx.replace_payload(self.event, event)?;
         cx.set_attr(self.event, "phase", Value::Text(self.phase.into()))?;
@@ -383,6 +399,7 @@ impl NativeCallable for Delivery {
             "currentMount",
             self.mount.map(Value::Object).unwrap_or(Value::Nil),
         )?;
+        // 对象方法总是携带 Event；显式订阅/旧式回调按 arity 决定是否传 Event。
         if matches!(self.handler, Handler::ObjectMethod)
             || cx
                 .store()
@@ -398,17 +415,18 @@ impl NativeCallable for Delivery {
     }
 }
 #[derive(Debug)]
-/// 传播结束后的默认行为收尾步骤。
+/// 正常传播结束后清理当前目标、阶段和 guard 标记，返回仍保留最终控制状态的 Event。
 struct Finish(ObjectRef);
 impl NativeCallable for Finish {
-    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
+    /// 派发结束步骤已持有 Event 引用，无需显式输入。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
 
-    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
+    /// 正常序列结束时清除活跃派发守卫与当前上下文，保留 target/prevented 并返回实际 Event，允许后续重用。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
         let mut event = cx.store().payload::<Event>(self.0, "Event")?.clone();
+        // 正常序列结束清递送标记与当前上下文，保留原始 target/mount 和 prevented 供调用方读取。
         event.dispatch = None;
         cx.replace_payload(self.0, event)?;
         cx.set_attr(self.0, "phase", Value::Text("none".into()))?;
@@ -421,7 +439,7 @@ impl NativeCallable for Finish {
 /// Snapshot the selected occurrence's route and listener order. Disconnection
 /// before a listener's turn skips it; newly registered listeners wait for the
 /// next dispatch. A code event without a Mount visits only its target object.
-/// 按 Mount 祖先路径执行捕获、目标与冒泡阶段，再处理对应默认行为。
+/// 快照 Mount 路径和订阅顺序，构造共享预算的 capture/target/bubble 驱动并返回 VM 续调。
 pub fn dispatch(
     cx: &mut NativeContext<'_>,
     owner: ObjectRef,
@@ -430,6 +448,7 @@ pub fn dispatch(
     desktop: ObjectRef,
 ) -> Result<NativeResult, VmError> {
     let mut event = cx.store().payload::<Event>(event_ref, "Event")?.clone();
+    // 只有 guard 仍存活才禁止重入；此前分发失败但 guard 已释放时，不让旧弱身份永久锁住 Event。
     if let Some(weak) = event.dispatch
         && cx.upgrade(weak)?.is_some()
     {
@@ -441,13 +460,16 @@ pub fn dispatch(
     if kind.is_empty() || kind.len() > 128 {
         return Err(invalid("invalid event kind"));
     }
+    // 路线由目标向外保存。无 Mount 的代码事件只访问目标对象，不猜测共享 Block 属于哪个出现。
     let mut route = vec![(owner, mount)];
     if let Some(mount) = mount {
         let target = cx.store().payload::<Mount>(mount, "Mount")?.clone();
+        // 传入 Mount 必须仍挂接且确实展示 owner；同一 Block 的另一个出现不能替代该上下文。
         if !target.mounted || target.block != owner {
             return Err(invalid("event context does not belong to this Block"));
         }
         let mut parent = target.parent;
+        // 沿弱 parent 链构建本轮路径快照，检查死亡祖先、脱离与环；不通过 Block 业务孩子关系反推祖先。
         let mut seen = std::collections::HashSet::from([mount]);
         while let Some(weak) = parent {
             let ancestor = cx
@@ -463,15 +485,18 @@ pub fn dispatch(
             route.push((data.block, Some(ancestor)));
             parent = data.parent;
         }
+        // 出现祖先之外再加入 Page 上下文，页面本身无 currentMount；弱页已失效则拒绝该旧路线。
         if let Some(weak) = target.page {
             let page = cx.upgrade(weak)?.ok_or(invalid("event Page has expired"))?;
             route.push((page, None));
         }
     }
+    // 所有递送和 Finish 显式捕获 guard，Event 只弱引用它；驱动完成/失败释放后 guard 自动结束本轮资格。
     let guard = cx.new_object()?;
     let mut calls = Vec::new();
     let mut group = 0;
     // Each occurrence is its own propagation group, even for shared Blocks.
+    // 先从最外层向目标递送捕获，再从目标向外递送非捕获；目标两次遍历都标记 phase=target。
     let traversal = route
         .iter()
         .enumerate()
@@ -486,6 +511,7 @@ pub fn dispatch(
     for (index, &(block, current_mount), capture) in traversal {
         let (_, data) = block::resolve(cx.store(), block)?;
         let mut handlers = Vec::new();
+        // 本轮先快照符合事件 kind 与 capture 的订阅顺序；回调期间新注册的连接不进入当前分发。
         for token in &data.subscriptions {
             let token_data = cx.store().payload::<Connection>(*token, "Connection")?;
             if token_data.handler.is_some()
@@ -496,6 +522,7 @@ pub fn dispatch(
             }
         }
         if !capture {
+            // 非捕获阶段 onEvent 先执行，再按订阅顺序，最后兼容旧 click 回调。
             handlers.insert(0, Handler::ObjectMethod);
             if kind == "click"
                 && let Some(handler) = data.click
@@ -507,6 +534,7 @@ pub fn dispatch(
             if calls.len() >= MAX_DELIVERIES {
                 return Err(invalid("event delivery budget exceeded"));
             }
+            // 每一项显式保活本轮 Event、guard、目标和可选 Mount/连接；不能仅靠 Rust ObjectRef 值当 GC 根。
             let mut captures = vec![event_ref, guard, block];
             if let Some(mount) = current_mount {
                 captures.push(mount);
@@ -538,6 +566,7 @@ pub fn dispatch(
         }
         // Capture and bubble at the target are one group: stopPropagation at
         // target capture still permits other target listeners.
+        // 目标捕获后不递增 group，使 stopPropagation 仍允许目标非捕获处理器；其他路径/阶段则隔离为新组。
         if index != 0 || !capture {
             group += 1;
         }
@@ -547,10 +576,12 @@ pub fn dispatch(
         Finish(event_ref),
         vec![event_ref, guard],
     ))?;
+    // 无论传播是否被停止，Finish 都作为序列最后一项执行，它不受 Delivery 的 stopped 判定影响。
     calls.push(finish);
     let driver = crate::vm_sequence::build(cx, calls, "<event dispatch>", desktop)?;
     event.dispatch = Some(cx.store().downgrade(guard)?);
     event.group = 0;
+    // 再次使用 Event 时清上一轮停止和默认阻止标志；目标与 Mount 属性也被本轮参数覆盖。
     event.stopped_at = None;
     event.immediate = false;
     event.prevented = false;

src/runtime/events.rs

@@ -21,6 +21,7 @@ use winit::event_loop::EventLoopProxy;
 /// 拖放目标窗口、目标布局版本和插入位置，源标签身份由外层 Input 保存。
 pub struct TabDrop {
     pub window: u64,
+    // 事件所依据的已发布布局版本，由执行端校验过期帧；原生连续手势有单独刷新逻辑。
     pub layout_version: u64,
     pub index: usize,
 }
@@ -31,15 +32,19 @@ pub struct TabDrop {
 pub struct Input {
     #[serde(default = "default_window")]
     pub window: u64,
+    // 产生事件的运行时会话；重载后即使窗口或 Mount 数值相同也不能沿用旧事件。
     pub session: u64,
     pub layout_version: u64,
+    // 捕获的具体出现身份；页面级相机事件使用零，独立视口相机事件要求非零。
     pub mount: u64,
     pub kind: String,
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    // 事件位置或缩放锚点；click 与 press_point 配对，具体坐标语义由事件 kind 决定。
     pub point: Option<[f32; 2]>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub press_point: Option<[f32; 2]>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    // 平移/滚动增量，或缩放的 [倍率,0]；不能无差别接受任意事件携带该字段。
     pub delta: Option<[f32; 2]>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub tab_drop: Option<TabDrop>,
@@ -53,11 +58,12 @@ fn default_window() -> u64 {
 }
 
 impl Input {
-    /// 检查当前输入或发布值的不变量，调用方据校验结果决定是否继续。
+    /// 按事件种类核对可携带字段、坐标范围和 Mount 是否为零；不替代执行端的会话/能力校验。
     pub fn validate(&self) -> Result<(), &'static str> {
         if self.window == 0 {
             return Err("window identity must be nonzero");
         }
+        // 标签跨窗口放置仅接受目标元信息；禁止同时夹带指针/滚动/屏幕位置，避免混用两套操作。
         if self.kind == "tab-drop" {
             let Some(target) = &self.tab_drop else {
                 return Err("tab-drop requires target metadata");
@@ -73,9 +79,11 @@ impl Input {
             }
             return Ok(());
         }
+        // 非 tab-drop 不得携带目标窗口信息，即使其他字段恰好合法也拒绝。
         if self.tab_drop.is_some() {
             return Err("tab_drop is only accepted for tab-drop");
         }
+        // 屏幕位置只服务 tab-detach 的新窗口定位，允许负数以支持左侧/上方显示器，但限制绝对范围。
         if let Some(position) = self.screen_position
             && (self.kind != "tab-detach"
                 || !position
@@ -94,7 +102,9 @@ impl Input {
                 | "scene-pan"
                 | "scene-zoom"
         ) {
+            // 独立视口输入可包含负的局部位置（例如捕获拖动移出视口）；页面级锚点要求非负。
             let viewport = self.kind.starts_with("viewport-") || self.kind.starts_with("scene-");
+            // 所有相机操作必须带有限、有界的增量；point 在非缩放操作可省略。
             let valid_delta = self.delta.is_some_and(|delta| {
                 delta
                     .iter()
@@ -117,6 +127,7 @@ impl Input {
             {
                 return Err("invalid page camera input");
             }
+            // 缩放必须给锚点并使用正倍率 0.1..=10；第二分量必须为零，不把缩放与二维平移混合编码。
             if self.kind.ends_with("-zoom")
                 && (self.point.is_none()
                     || self
@@ -127,6 +138,7 @@ impl Input {
             }
             return Ok(());
         }
+        // 滚动需要当前点与二维有限增量，不接受按下点；Mount 能力与身份由执行端进一步核对。
         if self.kind == "scroll" {
             return match (self.point, self.press_point, self.delta) {
                 (Some(point), None, Some(delta))
@@ -145,6 +157,8 @@ impl Input {
         if self.delta.is_some() {
             return Err("delta is only accepted for scroll input");
         }
+        // 无指针坐标的离散事件可通过此结构校验；若有指针信息，必须是 click 的按下/释放成对坐标。
+        // 这里不做完整 kind 白名单授权，具体操作仍由后续分发层检查。
         match (self.point, self.press_point) {
             (None, None) => Ok(()),
             (Some(point), Some(press))
@@ -165,15 +179,17 @@ impl Input {
 /// 原生输入的有界发送端，后台线程串行发往本地 API；所有窗口共享权威发布状态。
 pub struct Client(SyncSender<Input>);
 impl Client {
-    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
+    /// 建立容量 64 的发送队列和单个后台 HTTP 线程；线程创建失败则返回错误。
     pub fn new(
         proxy: EventLoopProxy<crate::app::AppEvent>,
         namespace: Arc<RwLock<crate::document::NamespaceState>>,
     ) -> anyhow::Result<Self> {
+        // 队列最多容纳 64 项；原生发送端使用 try_send，不阻塞 GUI 事件线程，也不保证满队列时无损。
         let (sender, receiver) = sync_channel::<Input>(64);
         thread::Builder::new()
             .name("tessera-native-events".into())
             .spawn(move || {
+                // 后台线程按队列顺序逐个发送 HTTP 请求；命名空间锁只覆盖检查，不跨越网络等待。
                 for mut input in receiver {
                     if let Ok(current) = namespace.read() {
                         if !refresh_continuous_input(&mut input, &current) {
@@ -182,6 +198,7 @@ impl Client {
                     } else {
                         continue;
                     }
+                    // 传输/服务错误通过事件代理回 GUI；代理已关闭时忽略通知失败，接收端退出后线程自然结束。
                     if let Err(error) = send(&input) {
                         let _ = proxy.send_event(crate::app::AppEvent::RuntimeFailed {
                             message: error.to_string(),
@@ -191,8 +208,9 @@ impl Client {
             })?;
         Ok(Self(sender))
     }
-    /// 通过有界原生输入客户端或本地 HTTP 发送纯数据事件；过期版本按既定协议处理。
+    /// 非阻塞尝试入队；成功仅代表队列接收，满队列或后台线程关闭返回 false。
     pub fn send(&self, input: Input) -> bool {
+        // 只反馈是否成功入队；队列满或接收端关闭都返回 false，不代表 worker 已接受或执行事件。
         self.0.try_send(input).is_ok()
     }
 }
@@ -208,6 +226,7 @@ fn refresh_continuous_input(input: &mut Input, current: &crate::document::Namesp
     ) {
         return true;
     }
+    // 选取事件原窗口的权威帧；窗口已经消失时丢弃，不能把手势改投主窗口。
     let frame = if input.window == crate::window::MAIN_WINDOW {
         Some(&current.document.frame)
     } else {
@@ -220,6 +239,7 @@ fn refresh_continuous_input(input: &mut Input, current: &crate::document::Namesp
     let Some(frame) = frame else {
         return false;
     };
+    // 必须仍属同一运行时会话、帧无故障且原捕获 Mount 具备对应能力，才可更新布局版本。
     if current.runtime_session != input.session
         || frame.session != input.session
         || frame.fault.is_some()
@@ -236,12 +256,14 @@ fn refresh_continuous_input(input: &mut Input, current: &crate::document::Namesp
     {
         return false;
     }
+    // 只追随新版本，不改 session/window/mount，不重选目标；每条排队增量仍独立发送。
     input.layout_version = frame.layout_version;
     true
 }
 
 /// 通过有界原生输入客户端或本地 HTTP 发送纯数据事件；过期版本按既定协议处理。
 fn send(input: &Input) -> anyhow::Result<()> {
+    // 固定回环 API 的轻量客户端，使用 Content-Length 和 Connection: close 定界；不连接外部地址。
     let body = serde_json::to_string(input)?;
     let mut stream =
         TcpStream::connect_timeout(&crate::api::API_ADDRESS.parse()?, Duration::from_secs(2))?;
@@ -254,9 +276,11 @@ fn send(input: &Input) -> anyhow::Result<()> {
         body
     )?;
     let mut response = String::new();
+    // 响应读取最多 32 KiB，避免错误正文无限增长；状态从 HTTP 状态行提取，不实现通用 HTTP 客户端。
     stream.take(32768).read_to_string(&mut response)?;
     let status = response.split_whitespace().nth(1).unwrap_or("");
     // An old frame's event is deliberately discarded, with no automatic retry.
+    // 409 代表过期帧冲突，按输入协议静默丢弃，不重试离散动作，避免重复点击或跨版本误操作。
     if status == "409" {
         return Ok(());
     }
@@ -277,6 +301,7 @@ fn send(input: &Input) -> anyhow::Result<()> {
 mod tests {
     use super::*;
     #[test]
+    /// 重复消费旧帧捕获的连续 pan，允许刷新到当前版本且保留每条 delta；离散 click 不改版本，会话/目标替换拒绝手势。
     fn queued_native_pan_keeps_each_delta_and_rejects_replaced_targets() {
         let (mut session, document) = crate::endor_host::ReplSession::load(
             "view=CanvasViewport(200,100,Scene2D(RectBlock(20,20,0)))\npage=Page()\npage.render(view)",
@@ -306,6 +331,7 @@ mod tests {
             document,
             ..Default::default()
         };
+        // 反复从旧帧原始手势克隆输入，验证每条增量都被刷新版本并累计，12×3 应得到 36。
         for _ in 0..12 {
             let mut queued = original.clone();
             assert!(refresh_continuous_input(&mut queued, &current));
@@ -315,6 +341,7 @@ mod tests {
             session.execute("view.camera.x", "app.main").unwrap().value,
             "36"
         );
+        // 离散点击不得自动刷新版本；随后验证会话替换和目标移除都会拒绝连续手势。
         let mut click = original.clone();
         click.kind = "click".into();
         assert!(refresh_continuous_input(&mut click, &current));
@@ -326,6 +353,7 @@ mod tests {
         assert!(!refresh_continuous_input(&mut original.clone(), &current));
     }
     #[test]
+    /// 对 tab-drop 元数据、位置上限与 tab-detach 桌面坐标逐项改坏，检查辅助字段只在对应事件类型和预算内合法。
     fn drop_metadata_is_scoped_to_its_event_kind_and_bounded() {
         let mut input:Input=serde_json::from_str(r#"{"window":1,"session":1,"layout_version":2,"mount":3,"kind":"tab-drop","tab_drop":{"window":2,"layout_version":4,"index":1}}"#).unwrap();
         assert!(input.validate().is_ok());
@@ -343,6 +371,7 @@ mod tests {
     }
 
     #[test]
+    /// 旧 JSON 未带 window 时默认主窗口以保持兼容；显式 window=0 仍是非法资源，不能当成默认值。
     fn legacy_event_window_defaults_but_zero_is_never_a_resource() {
         let mut input: Input =
             serde_json::from_str(r#"{"session":1,"layout_version":2,"mount":3,"kind":"focus"}"#)