25 KiB
25 KiB
Tessera 中文源码注释与阅读索引
本轮进一步细化 Tessera 自有代码的中文注释：覆盖所有 Rust 模块、运行时/API 测试、内置起始页、45 个 Endor 示例、Cargo 依赖配置及两个工具脚本。说明聚焦具体输入/输出、状态归属、计算步骤、依赖观察、取消/失败路径和资源预算；不修改接口、算法、常量或非注释程序文本。Aster 是独立维护的 vendor 子模块，其固定版本与内容沿用主线。
建议阅读顺序
- main：创建原生循环、共享文档与执行 worker。
- 原生应用：理解窗口生命周期、可用视口、输入边界和最终 present。
- API worker 与 运行时：理解候选/活跃 VM、输入串行化、分片刷新和发布。
- 桥接层、Block 与 Mount：区分共享业务对象、每次出现和展示事务。
- 快照、源布局 和 源绘制：理解依赖缓存、只读执行及挂起工作。
- 二维视口、3D 和 面板映射：理解布局/世界/视图的边界。
- 任务、provider 和 事件传播：理解异步交付资格与生命周期。
阅读时需要保留的边界
- Block/Data 属于共享业务组成；Mount 属于一个展示位置，不能把一次出现的尺寸写回共享对象来代替排版。
- ObjectRef/WeakObjectRef 的含义由真实托管拥有关系决定；派生缓存中的身份索引不能成为隐藏根。
- 窗口线程消费完整发布值；VM、源回调和托管堆操作只在执行 worker 内推进。
- submission 防止旧请求覆盖新输入；session 防止跨 VM 资源误用；layout_version 防止旧几何上的离散操作误触。
- Pending Work 同时拥有续体与上下文；取消必须关闭原 VM 的只读执行并恢复未提交 Mount，不能只丢弃 Rust 值。
- 场景世界不是无限尺寸的排版盒子；有限视口参加布局，摄像机负责投影，命中沿相同链逆变换。
- 现有 CPU 绘制、缓存范围与输入队列限制仍按当前代码执行；说明性注释不代表性能优化已实现。
Rust 逐文件说明
每行说明该文件本次深化注释的职责和目的。生产函数/方法的入口说明与内部关键逻辑互相补充；VM 可调用适配器说明实际参数约定，而非仅重复 trait 名称。集成测试中的每个顶层测试/辅助函数都有具体场景和断言说明，测试程序字符串与断言保持原样。
| 文件 | 注释解释的职责与目的 |
|---|---|
| src/bridge/mod.rs | 语言桥接模块入口。集中导出 Endor 类型和宿主实现之间的适配层。 |
| src/bridge/ui_bridge.rs | Endor 与 Tessera 的展示事务协调层：维护每个窗口的 Page、Mount、布局缓存和发布版本。 |
| src/bridge/ui_bridge/bootstrap.rs | 安装一次 VM 域需要的宿主类型、对象和方法。类型注册表是源代码调用原生能力的入口。 |
| src/bridge/ui_bridge/calls.rs | 把 Endor 方法调用分派到对应宿主操作。这里处理构造、树修改、绑定、状态与页面能力。 |
| src/bridge/ui_bridge/developer_pages.rs | 把内置开发工具和起始页接入托管 Page。工厂在所属 VM 中编译和执行，而不是在窗口线程另建业务状态。 |
| src/bridge/ui_bridge/page_input.rs | 把页面、2D 视口和 3D 视口的相机输入转换成托管对象更新。 |
| src/bridge/ui_bridge/signatures.rs | 声明宿主方法在 Endor 类型系统中的参数和返回契约。 |
| src/bridge/ui_bridge/tree.rs | 定义从托管对象提取的不可变视觉树。共享业务对象可以有多次展示，树节点与 Mount 出现的身份不是同一概念。 |
| src/main.rs | 应用组合入口。先创建原生事件循环和共享发布状态，再启动 API/VM worker，最后把窗口事件交给 TesseraApp。 |
| src/model/binding.rs | 属性绑定：在只读计算中收集依赖，将结果写回绑定目标。 |
| src/model/block.rs | Block 的共享赋值、底层 Data 与视觉属性实现。Block 通过 Cell 间接指向 Data，使别名能观察到同一次替换。 |
| src/model/document.rs | 运行时与窗口线程之间的发布数据契约。NamespaceState 管理提交序号、版本和当前完整文档。 |
| src/model/mod.rs | 模型层模块入口。包含托管业务对象、每次展示上下文、依赖缓存，以及交给窗口线程的发布值。 |
| src/model/mount.rs | 每次展示的托管上下文：同一个 Block 出现在两个位置时，有两个独立 Mount。 |
| src/model/object_list.rs | 给源协议返回的对象列表提供受控封装。列表内容通过托管引用被追踪，读方法只暴露检查后的条目。 |
| src/model/presentation.rs | 一个原生窗口对应一份 Presentation：独立视口、Mount、测量缓存、焦点与依赖记录。 |
| src/model/protocols.rs | 安装 Visual、EventTarget、Children 和 Presentable 等能力契约。 |
| src/model/scene3d.rs | 将 Endor 托管场景对象转换成可供渲染线程读取的 3D 数据。 |
| src/model/snapshot.rs | 从可变托管对象图提取不可变 UiNode，并维护反向依赖与父子失效传播。 |
| src/model/window.rs | 托管 Window 的页面所有权、原生命令与关闭生命周期。 |
| src/render/box_model.rs | 有限布局盒子的尺寸策略。区分 auto、固定值和 fill，并处理 min/max 对约束与最终尺寸的限制。 |
| src/render/display_list.rs | 面向设备像素的绘制指令集合。它承载矩形、文字、裁剪与 3D 表面等原语，不直接操作 VM。 |
| src/render/geometry.rs | 共享的二维点和矩形值。命中判断在调用方完成坐标系转换后使用，矩形本身不隐式处理相机。 |
| src/render/layout.rs | 原生布局求解器：自底向上测量期望尺寸，再自顶向下分配位置和实际尺寸。 |
| src/render/mod.rs | 渲染模块入口。排版、源视觉协议、相机投影和最终光栅化各自独立，通过不可变帧衔接。 |
| src/render/native_visual.rs | 让原生组件也通过 Endor 的 measure/arrange/paint 协议被调用。 |
| src/render/page.rs | 旧 Page.mode 的兼容空间策略，以及页面级的正逆相机变换。 |
| src/render/scene.rs | 合成整个原生窗口的显示列表：页面画面、宿主侧栏和开发工具绘制。 |
| src/render/scene3d.rs | 有界 CPU 3D 渲染器。使用相同摄像机与世界变换进行视锥裁剪、深度测试、纹理采样和射线拾取。 |
| src/render/scene3d/math.rs | 3D 数学基础：向量、仿射矩阵、摄像机基向量、投影射线和三角形相交。 |
| src/render/scene3d/panel.rs | 连接 3D 平面与普通 UI 的坐标和绘制桥梁。 |
| src/render/scene3d/spatial.rs | 不可变世界空间 BVH。用网格变换后的包围盒快速筛选视锥与射线候选。 |
| src/render/scroll.rs | 逐 Mount 的滚动状态、裁剪和输入目标选择。 |
| src/render/software_renderer.rs | 把 DisplayList 写入 CPU 像素缓冲。裁剪栈限定矩形、文字和 3D 表面的实际写入区域。 |
| src/render/source_hit.rs | 通过真正的源/原生 hitTest 协议确定指针目标。 |
| src/render/source_layout.rs | 源 measure/arrange 协议的分片布局驱动器。自底向上的测量与自顶向下的安排共享一个只读 VM 调用域。 |
| src/render/source_paint.rs | 执行源 paint 覆盖并解码受检查的 PaintCommand。 |
| src/render/text.rs | 统一字体发现、文字整形、测量与抗锯齿字形绘制。 |
| src/render/viewport.rs | 独立 2D 相机与可逆投影。视口尺寸属于布局；平移、缩放属于视图，不改变世界对象的逻辑位置。 |
| src/render/viewport/spatial.rs | 有界屏幕网格，用来减少普通二维命中和相机目标查询的候选。 |
| src/runtime/api.rs | 本机 HTTP API 入口：路由请求、限制输入大小、观察活动，并将执行工作送入串行 worker。 |
| src/runtime/api/guide.rs | 从当前命名空间生成 /agent 使用指南。返回的示例、地址和版本描述来自运行时上下文；这里生成文档，不执行用户源码。 |
| src/runtime/api/tests.rs | API 集成回归。通过实际本地 HTTP 请求检查队列、候选替换、状态码、版本和完整文档发布。 |
| src/runtime/api/worker.rs | 唯一串行执行 VM 的 API worker。保留活跃运行时，另建 PUT 候选，并在候选完整成功后切换发布。 |
| src/runtime/endor_host.rs | 把 Aster 编译/执行与 Tessera 展示生命周期连接起来。Candidate 拥有 VM 与宿主根，ReplSession 保留实际运行中的全局环境。 |
| src/runtime/endor_host/tests.rs | 说明全部运行时测试和辅助函数的场景/断言，并解释新主线性能基准的 DPI 分组、预热、三类计时边界和统计方式。 |
| src/runtime/endor_script.rs | 区分完整 Module 与顶层 Script，并保留输入源码位置。 |
| src/runtime/event_dispatch.rs | 托管事件与订阅的传播实现。Connection 持有回调引用，Event 保存目标、阶段与停止传播状态。 |
| src/runtime/events.rs | 原生窗口输入到执行 worker 的纯数据传输。Input 只含窗口/会话/版本/Mount 身份及有限坐标。 |
| src/runtime/io_tasks.rs | 后台文件/网络 provider。线程池只携带纯数据、取消控制与弱 Task 身份，不持有 VM。 |
| src/runtime/mod.rs | 运行时模块入口。VM 生命周期、API、源程序组织、事件与异步任务在这里组合。 |
| src/runtime/tasks.rs | owner/key 管理的异步任务与协作式源函数调度。弱索引用于查找，回调、等待对象和协程帧是托管图中的真实边。 |
| src/runtime/vm_sequence.rs | 构造共享 VM 调用序列与同帧循环驱动的字节码。 |
| src/shell/activity.rs | 有界 HTTP 活动记录。保存请求/响应的可显示预览供 Network 工具读取，不负责执行请求。 |
| src/shell/app.rs | winit 原生应用生命周期和窗口事件入口。这里创建窗口、发布逻辑视口、转发输入，并把不可变文档画到原生表面。 |
| src/shell/clipboard.rs | 把 UTF-8 文本读写适配到当前平台的系统剪贴板命令。 |
| src/shell/developer_tools.rs | Console/Sources/Network/Settings 的宿主交互协调与绘制状态。 |
| src/shell/developer_tools/console.rs | 绘制 Console 输入、结果历史和对应命中区域。 |
| src/shell/developer_tools/network.rs | 绘制已观察到的 HTTP 活动、请求列表与详情。 |
| src/shell/developer_tools/painter.rs | 开发工具画面的绘制辅助：文字行、按钮、分隔线和滚动条。 |
| src/shell/developer_tools/selection.rs | 多行文本选择和光标导航。选择端点映射到合法字符边界，避免把 UTF-8 字节中间当成一个字符。 |
| src/shell/developer_tools/settings.rs | 绘制宿主设置页面和主题选择区域。 |
| src/shell/developer_tools/sources.rs | 绘制 AST、当前源码快照和云文件视图。 |
| src/shell/mod.rs | 原生宿主模块入口。窗口、管理控件、系统适配和开发工具状态与用户业务界面分开维护。 |
| src/shell/native_chrome.rs | macOS 原生标题栏适配。定位系统窗口按钮并沿用用户的标题栏双击设置。 |
| src/shell/sidebar.rs | 宿主管理工具和页面列表的唯一侧栏。展开时占据页面左侧空间，折叠后只保留展开按钮区域。 |
| src/shell/sources.rs | 云文件浏览的 provider 抽象与工作区状态。默认 provider 未连接，不假装已有外部文件。 |
| src/shell/system_ui/interaction.rs | 即时绘制控件的跨帧交互状态：稳定 WidgetId、悬停、按下捕获、键盘焦点和释放激活。 |
| src/shell/system_ui/mod.rs | 宿主管理控件的共享组件入口。主题、绘制原语和跨帧交互状态分离，用户 Endor 页面不依赖这里的控件树。 |
| src/shell/system_ui/theme.rs | 宿主控件的颜色与状态调色。根据背景、强调色和交互状态生成可读颜色，不改变业务状态。 |
| src/shell/system_ui/widgets.rs | 用统一主题绘制宿主管理控件，并同步注册交互目标。 |
| src/shell/tabs.rs | 发布页面标签的数据结构。保留稳定页面身份、标题、选中状态和开发工具类别；页面的托管所有权由模型层管理。 |
其他文件
| 文件 | 本次改动及目的 |
|---|---|
| src/bridge/ui_bridge/start_page.endor | 解释卡片源测量/背景、页面工厂、纵横布局与滚动组合、共享计数和场景位置，便于从真实 Endor 页面理解宿主边界。 |
| scripts/build-macos-app.sh | 说明 macOS 构建环境前提、失败退出、锁定依赖、临时文件替换和 bundle 元数据，帮助理解每个打包步骤。 |
| scripts/render-uml.mjs | 说明独立文档依赖、DOM/Canvas 适配、错误图检查与 SVG/PNG 产物生成，避免混淆运行依赖与文档工具。 |
| Cargo.toml | 解释每个依赖负责的能力、Aster 本地路径依赖、macOS 条件依赖与 release 优化配置。 |
| docs/code-comments.md | 更新本逐文件说明、示例索引和实际核对方式，使本次注释范围与可验证结果对应。 |
Endor 示例逐文件说明
每个示例的类、方法及关键逻辑旁增加中文说明。page.endor 和 hello.endor 被测试固定断言源码行号，因此使用行尾注释，保留原始行数；其余示例使用独立注释行，程序符号与字面量不变。
| 文件 | 注释解释的场景与目的 |
|---|---|
| examples/async-file.endor | 异步 UTF-8 文件读取：在 Console 调用 reader.read(绝对路径)，后台 provider 只交付文本，VM worker 执行业务回调。 |
| examples/async-network.endor | 异步 HTTP(S) 文本 GET：Console 调用 fetcher.fetch(url)，沿用 owner/key 替换、状态与成功回调协议。 |
| examples/await-file.endor | 把 callback-free 文件 Task 与 ui.spawn 协作函数组合：await 保存执行位置，等待完成后继续，不阻塞 VM worker。 |
| examples/box-layout.endor | 盒模型组合：容器与 Page/相机独立，border-box 尺寸、padding、margin 和对齐分别参与布局。 |
| examples/campus-lms.endor | 多页面校园演示：七个普通托管 Page 共享 CampusCourse/CampusWork 业务对象，所有课程与学生数据均虚构。 |
| examples/classes.endor | 普通源类继承示例：GUI 点击执行继承的 activate，内部 self.change 再动态分派到 DemoCounter 覆盖。 |
| examples/constructor-contracts.endor | 构造器分段示例：原生可选参数/可变子项与源子类新增字段分别验证。 |
| examples/cooperative-tasks.endor | 协作任务示例：两个 ui.spawn 各自保留执行帧，worker 按指令量子轮转推进。 |
| examples/events.endor | 同一托管对象系统中的事件阶段：祖先 capture → 目标 onEvent → 目标监听器 → 祖先 bubble。 |
| examples/exit-lifecycle.endor | 正常退出与多窗口卸载示例：同一 ExitText 出现在两窗，onUnmount 按出现位置分别调用。 |
| examples/field-contracts.endor | 字段类型契约示例：CounterText 同时有原生文本载荷和源 Number 字段。 |
| examples/flex-constraints.endor | flexBasis/flexMin/flexMax/flexShrink 约束同一主轴分配。 |
| examples/flex.endor | 按 flex 权重分配有限主轴空间：固定项先占自然尺寸，剩余空间按正权重划分。 |
| examples/fonts.endor | 字体测量示例：中英文混排、重音字符和不同字宽均走系统字体塑形与回退。 |
| examples/function-types.endor | Function 与 Type 的契约示例：源函数、原生函数与绑定方法都可作为函数值，类型构造器保持 Type 身份。 |
| examples/gc-lifecycle.endor | 托管对象循环与等待帧回收：先记 ui.stats().objects，再调用 mountCycle，观察 phase 与 pending.value.status()。 |
| examples/global-dependencies.endor | 全局名称依赖示例：paint 读取 color 这个具体名字，而非依赖整个 globals 字典版本。 |
| examples/hello.endor | 解释辅助 heading、兼容 main 入口、局部业务引用和原生布局，保留源码位置夹具。 |
| examples/layout-cache.endor | 测量与绘制依赖分离：改颜色应复用尺寸缓存，改模型宽度才需要重新测量。 |
| examples/layout-negotiation.endor | 测量/排列协商示例：arrange 指定子宽后需重新换行测量，高度变化继续影响父容器和后继位置，直到整树稳定。 |
| examples/main.endor | 与 page.endor 等价的 main 返回根入口：用于对比顶层显式 render 和兼容模块入口的绘图结果。 |
| examples/managed-types.endor | 托管名义类型入门：ui 构造器与 TextBlock/Button/Page 返回同一套 VM 托管对象。 |
| examples/method-contracts.endor | 方法覆盖遵守参数可更宽、返回可更具体的规则。 |
| examples/mount-lifecycle.endor | 业务对象与出现位置生命周期分离：同一 child 在根中出现两次，每次都获得独立 Mount 和通知。 |
| examples/native-signatures.endor | 原生回调也发布 Function 签名：state.set 接收一个 Event，increment 接收零参数。 |
| examples/native-subclasses.endor | 源类继承原生视觉类型：原生载荷负责基础绘制，新增字段和覆盖方法由源类提供。 |
| examples/owned-tasks.endor | owner 作用域决定取消时机：Page 关闭会取消其任务，隐藏 Block 和 ui 的任务可继续。 |
| examples/page.endor | 解释顶层脚本创建文字/矩形、Page 与 render 的关系，保留四行结构树夹具。 |
| examples/presentable.endor | 普通业务对象显式实现 Presentable 后，ui.present 可调用其 present(window) 生成视觉对象。 |
| examples/property-bindings.endor | 通用属性绑定：业务 Model 的三个零参只读方法分别计算 rect.width、rect.color 和 label.text。 |
| examples/scene-viewports.endor | 一个二维世界可被多个有限视口观察，Scene2D 的对象位置共享，默认 Camera2D 各自独立。 |
| examples/scene3d.endor | 同一 Scene3D 在透视/正交视口中展示；相机控制独立，网格业务变换由两边共享。 |
| examples/scroll-axis.endor | 滚动轴策略影响可滚动方向与内容测量约束：vertical 限宽并允许长高，horizontal 允许横向展开。 |
| examples/scroll.endor | 同一 ScrollBlock 在两个原生窗口中展示：内容业务对象共享，滚动偏移按 Mount 独立保存。 |
| examples/source-hit.endor | 自定义形状命中：对象原始矩形宽 160，但 paint 只画左侧直径 80 的圆，hitTest 也只接受圆内。 |
| examples/source-layout.endor | 源视觉协议的最小组合：measure 决定尺寸，arrange 决定子项位置，Metrics 是被两者读取的业务模型。 |
| examples/source-paint.endor | 源 paint 产出真正进入窗口的 DisplayList；允许构造并修改本次计算的新命令，禁止改已有业务对象。 |
| examples/student-grades.endor | 学生成绩中心为纯内存演示，记录均虚构，不连接学校数据库。 |
| examples/tab-placement.endor | 页面位置与子项插入的代码示例：Page 方法覆盖计数，Container.insert 在指定位置创建稳定子槽。 |
| examples/tabs.endor | 代码与原生侧栏都操作真实 Page 对象；activate/close/open 改变展示关系，业务对象可继续被全局引用保留。 |
| examples/visual-protocols.endor | 原生视觉协议直接返回托管数据：Constraints/MeasureResult、Bounds/Arrangement 和 DisplayList 都可在源码中查询。 |
| examples/window.endor | 托管 Window 资源与原生窗口相连：源码排出 resize/title 命令，成功刷新后由 GUI 线程执行。 |
| examples/windows.endor | 两个原生窗口共用一个 Aster VM 和 count 业务对象，各自拥有独立 Page 与 Mount。 |
| examples/workspace.endor | 静态工作台组合示例：所有指标、进度与活动记录均为演示数据，不读取任务系统或网络。 |
| examples/world-ui.endor | 世界空间 UI：普通 Endor 树先在独立 UI 分辨率中布局/绘制，再作为 Panel3D 平面的纹理参与三维深度。 |
| 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 中。