16 KiB
16 KiB
Tessera 中文源码注释与阅读索引
本轮只为 Tessera 主项目补充注释，Aster 子模块固定版本与内容均沿用主线。注释按模块职责、类型/函数入口、关键字段、执行阶段和失败/取消路径组织；没有改变接口、算法、常量或资源预算。
建议阅读顺序
- 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 逐文件说明
每行说明该文件本次新增注释解释的职责和目的。生产函数/方法均增加中文入口说明；复杂状态机另外补充阶段和不变量说明。集成测试文件增加整体阅读与检查点说明，测试程序文本和源码范围断言保持原样。
| 文件 | 注释解释的职责与目的 |
|---|---|
| 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 | 运行时集成回归与示例验收。测试经真实 Aster 前端、编译器、VM 和展示协议执行，不是手工伪造布局结果。 |
| 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 | 说明本地构建前提、锁定依赖、临时文件替换和 bundle 元数据，帮助理解每个打包步骤。 |
| scripts/render-uml.mjs | 说明独立文档依赖、DOM/Canvas 适配、错误图检查与 SVG/PNG 产物生成，避免混淆运行依赖与文档工具。 |
| src/README.md | 增加本注释索引入口，便于从源码目录开始阅读。 |
| docs/code-comments.md | 本逐文件说明与阅读顺序，覆盖本轮提交的文件及共同边界。 |
核对方式
检查差异仅新增独立注释行和注释相关空白，并与主线去除注释后的文本对比；同时运行格式、完整 GUI 回归、Clippy 和包含私有项的 rustdoc。脚本使用语法检查，不执行文档渲染或应用打包。具体检查结果在 PR 中记录。