# Tessera 源码导航

整体设计和当前进展从 [架构导览](../docs/architecture/README.md) 开始；本轮每个文件的迁移对应见 [逐文件清单](../docs/architecture/file-map.md)。

`main.rs` 只负责组合启动，并保留 crate 私有模块路径别名。五组目录仍在同一个 binary crate 中，不是严格单向分层。

| 目录 | 责任 |
| --- | --- |
| `shell/` | 原生工作区、窗口输入、标签、开发工具和独立宿主管理控件 |
| `runtime/` | 本机 API、串行 VM 执行、事件和异步任务 |
| `model/` | 托管对象、绑定、Mount、窗口语义、依赖与发布值 |
| `render/` | 几何、布局、source/native 视觉协议、绘制、命中、字体和软件渲染 |
| `bridge/` | Endor 类型/方法与宿主能力及展示刷新之间的连接 |

## shell

| 模块 | 职责 |
| --- | --- |
| [activity](shell/activity.rs) | 有界 HTTP 活动记录与允许的头部预览 |
| [app](shell/app.rs) | GUI 事件循环、窗口/viewport、输入与 chrome 调度 |
| [clipboard](shell/clipboard.rs) | 原生 UTF-8 剪贴板适配 |
| [developer_tools](shell/developer_tools.rs) | 四个工具 Page 的状态、焦点与管理交互协调 |
| [native_chrome](shell/native_chrome.rs) | macOS 原生按钮对齐和工具栏双击系统动作 |
| [sources](shell/sources.rs) | 默认断开的云文件 provider 接口及工作区 |
| [system_ui](shell/system_ui/mod.rs) | 独立宿主管理控件、交互和主题 |
| [tabs](shell/tabs.rs) | 共享标签绘制/命中、密集布局、滚动、拖放及动画 |

## runtime

| 模块 | 职责 |
| --- | --- |
| [api](runtime/api.rs) | HTTP 请求路由、队列、请求观察和响应；worker/指南拆为子模块 |
| [endor_host](runtime/endor_host.rs) | 候选/活跃 VM、编译执行、增量刷新、清理和诊断 |
| [endor_script](runtime/endor_script.rs) | 组织 Aster Script/Module 输入及原始源码范围 |
| [events](runtime/events.rs) | 原生输入的有界 loopback 传输 |
| [event_dispatch](runtime/event_dispatch.rs) | 托管事件、订阅和 capture/target/bubble 分发 |
| [io_tasks](runtime/io_tasks.rs) | 有界文件/HTTP provider、纯数据完成消息和取消 |
| [tasks](runtime/tasks.rs) | 托管 Task、owner/key 取消和协作任务调度 |
| [vm_sequence](runtime/vm_sequence.rs) | 共享 VM 调用序列及同帧迭代驱动 |

## model

| 模块 | 职责 |
| --- | --- |
| [binding](model/binding.rs) | 属性依赖、只读计算与托管绑定 |
| [block](model/block.rs) | Block/Cell/Data 语义、稳定子 slot 和共享赋值 |
| [document](model/document.rs) | NamespaceState、RenderDocument、Frame、发布校验与原生命令 |
| [mount](model/mount.rs) | 每次展示出现的托管上下文、生命周期及弱索引 |
| [object_list](model/object_list.rs) | 托管结果集合的类型封装与只读访问 |
| [presentation](model/presentation.rs) | 逐窗口布局、Mount、缓存、读依赖和失效状态 |
| [protocols](model/protocols.rs) | Visual/EventTarget/Children/Presentable 能力契约安装 |
| [snapshot](model/snapshot.rs) | 变化依赖和不可变视觉提取缓存 |
| [window](model/window.rs) | 托管 Window、Page registry、命令及生命周期 |

## render

| 模块 | 职责 |
| --- | --- |
| [display_list](render/display_list.rs) | 原生绘制原语和颜色 |
| [geometry](render/geometry.rs) | 点和矩形值 |
| [layout](render/layout.rs) | 原生测量、排列、出现几何及预算 |
| [native_visual](render/native_visual.rs) | 托管原生视觉协议、值转换和签名检查 |
| [scene](render/scene.rs) | 页面、标签、插入标记和开发工具画面合成 |
| [scroll](render/scroll.rs) | 逐 Mount 偏移、嵌套滚动和剪裁投影 |
| [software_renderer](render/software_renderer.rs) | 软件光栅化、抗锯齿覆盖和嵌套剪裁 |
| [source_hit](render/source_hit.rs) | 源/原生命中协议与匹配目标 |
| [source_layout](render/source_layout.rs) | 源 measure/arrange、约束、挂起工作和测量缓存 |
| [source_paint](render/source_paint.rs) | 源 paint 调用、受限命令转换和依赖 |
| [text](render/text.rs) | 系统字体、shaping、字形和测量缓存 |

## bridge

| 模块 | 职责 |
| --- | --- |
| [ui_bridge](bridge/ui_bridge.rs) | Endor 宿主类型、窗口展示会话、布局/绘制发布协调 |

## 主要入口和运行约束

- HTTP 路由：`runtime/api.rs`；worker：`runtime/api/worker.rs`；在线指南：`runtime/api/guide.rs`。
- Bridge 安装：`bridge/ui_bridge/bootstrap.rs`；Block 调用：`calls.rs`；签名：`signatures.rs`；不可变树：`tree.rs`。
- 默认页：`bridge/ui_bridge/start_page.endor`；Console/Sources/Network/Settings：`shell/developer_tools/`。
- 现有 API 和宿主测试：`runtime/api/tests.rs`、`runtime/endor_host/tests.rs`；其他模块中也保留原单元测试。

VM 和托管根只由执行 worker 操作。原生窗口收到已发布值，不收到 ObjectRef。完整 PUT 成功才接替活跃程序；Console 保留实际 VM；失败和清理语义见架构文档。

当前开发与验证在本机使用原生 Rust 工具链完成：格式、现有测试、Clippy、原生构建和人工运行检查。CI/CD 工作流与 Docker 检查入口已移除；具体命令见 [项目验证说明](../README.md#validation)。历史验收记录只代表当时实际执行的检查。