diff --git a/docs/architecture/01-modules.md b/docs/architecture/01-modules.md index 91a84bb..297b9df 100644 --- a/docs/architecture/01-modules.md +++ b/docs/architecture/01-modules.md @@ -26,22 +26,9 @@ Tessera/ 箭头表示主要运行时调用/数据流,不宣称是无环的 Rust import 图。 -```mermaid -flowchart LR - Agent[本机客户端 / Console] --> API[runtime: HTTP API] - API --> Worker[runtime: 串行 VM worker] - Worker --> Aster[Aster frontend / compiler / core] - Worker --> Bridge[bridge: UI 类型和行为] - Bridge <--> Model[model: 对象与展示状态] - Bridge --> Render[render: 布局与画面提取] - Worker --> Published[NamespaceState / RenderDocument] - Published --> Shell[shell: 原生工作区] - Shell --> Scene[render: 场景合成与光栅化] - Scene --> OS[winit / softbuffer / 操作系统] - Shell -->|序列化输入| API - Worker --> IO[runtime: 有界 I/O provider] - IO -->|纯数据完成消息| Worker -``` +![组件与主要数据流](uml/rendered/components.png) + +[放大 SVG](uml/rendered/components.svg) · [编辑 UML 源码](uml/components.puml) 标准 UML 组件表示见 [components.puml](uml/components.puml)。`System UI` 只依赖低层几何、文本和画图,不导入 Endor VM 或 guest bridge;开发工具的执行逻辑由外层提供。 @@ -56,24 +43,9 @@ flowchart LR | 按需 I/O 池 | 文件/HTTP 工作及取消控制 | 不持有托管根;通过 mailbox 回传文本/错误 | | 系统 curl 子进程 | `fetchText` 的实际 HTTP 传输 | 有超时、大小和协议限制;不是业务服务 | -```mermaid -flowchart TB - subgraph Desktop[Tessera 单个桌面进程] - GUI[GUI 主线程] - HTTP[本机 API 接收线程] - VM[唯一执行 worker] - IO[I/O 池] - State[(Arc / RwLock NamespaceState)] - HTTP -->|有界队列| VM - VM -->|原子发布| State - State -->|只读快照| GUI - GUI -->|输入客户端| HTTP - VM <--> IO - end - External[本机 agent] -->|127.0.0.1:4737| HTTP - IO --> Curl[系统 curl 子进程] - GUI --> Native[原生窗口 / 软件像素缓冲] -``` +![进程与线程部署](uml/rendered/deployment.png) + +[放大 SVG](uml/rendered/deployment.svg) · [编辑 UML 源码](uml/deployment.puml) 可编辑部署图:[deployment.puml](uml/deployment.puml)。Aster 作为 Cargo path dependency 编译到同一应用,不是额外 VM 服务;Lyra 和 Hestia 不在应用依赖链中。 diff --git a/docs/architecture/02-object-model.md b/docs/architecture/02-object-model.md index d0f7080..962c9ad 100644 --- a/docs/architecture/02-object-model.md +++ b/docs/architecture/02-object-model.md @@ -6,81 +6,9 @@ 下面是简化 UML 类图;实线关联表示有强引用/直接持有,虚线标明弱引用或派生关系。它省略类型表、回调捕获边和桌面的内部字典,不能当成完整 GC 根枚举。 -```mermaid -classDiagram - class ReplSession { - id: u64 - candidate: Candidate - bridge: UiBridge - documents: Map - faulted: bool - } - class Candidate { - vm: Vm - roots: ObjectRef[] - globals: ObjectRef - } - class ManagedWindow { - id: u64 - pages: ObjectRef[] - closed: bool - } - class Block { - state: ObjectRef - page: bool - } - class Cell - class Data { - kind: Kind - children: Child[] - properties: ObjectRef - bindings: ObjectRef[] - } - class Child { - slot: u64 - block: ObjectRef - } - class Mount { - block: ObjectRef - page: WeakObjectRef - parent: WeakObjectRef - geometry: MountGeometry - mounted: bool - } - class Presentation { - desktop: ObjectRef - active: ObjectRef - mounts: MountTable - render_cache: RenderCache - } - class UiNode { - block_id: String - slots: u64[] - kind: UiKind - } - class RenderDocument { - source: String - ui_root: Arc - frame: Frame - windows: Map - } - ReplSession *-- Candidate - ReplSession *-- UiBridge - UiBridge *-- Presentation : Session 中逐窗口保存 - ManagedWindow --> Block : pages / tabs 保留 Page - Block --> Cell : state - Cell --> Data : 普通内容 - Cell --> Block : 共享赋值转发时 - Data *-- Child - Child --> Block - Mount --> Block - Mount ..> Mount : parent / siblings 弱引用 - Presentation *-- MountTable - Presentation ..> UiNode : 缓存派生树 - RenderDocument o-- UiNode : 不可变原生值 - RenderDocument *-- Frame - RenderDocument *-- RenderDocument : 次级窗口 -``` +![对象模型与引用关系](uml/rendered/domain.png) + +[放大 SVG](uml/rendered/domain.svg) · [编辑 UML 源码](uml/domain.puml) 可编辑来源:[domain.puml](uml/domain.puml)。`Page` 是具有 Page 行为的托管 Block,不是另一棵浏览器 DOM;`ManagedWindow` 是 VM 中的窗口语义,和 winit 的原生 Window 有对应关系,但不是同一对象。 diff --git a/docs/architecture/03-runtime.md b/docs/architecture/03-runtime.md index 2b383ea..eb45b65 100644 --- a/docs/architecture/03-runtime.md +++ b/docs/architecture/03-runtime.md @@ -2,37 +2,9 @@ ## 完整程序提交的时序 -```mermaid -sequenceDiagram - actor Client as 本机客户端 - participant API as api.rs - participant Queue as 有界队列 - participant Worker as api/worker.rs - participant Aster as Reader/Parser/Compiler/VM - participant Bridge as UiBridge - participant State as NamespaceState - participant GUI as TesseraApp - Client->>API: PUT /v1/namespaces/app.main/code - API->>API: 校验命名空间/大小/入队资格 - API->>Queue: BuildRequest + submission - Queue->>Worker: 串行接收 - Worker->>Aster: 在新候选中解析、编译和执行 - Aster->>Bridge: 构建对象、Page 和回调 - loop 可恢复的刷新切片 - Worker->>Bridge: 绑定、快照、布局、绘制、挂载同步 - Bridge-->>Worker: Pending / 完成的原生文档 - end - Worker->>State: 核对提交代际 - alt 仍有效且构建成功 - Worker->>State: 提交 RenderDocument / 窗口命令 - Worker->>Worker: 候选成为活跃 ReplSession - Worker-->>GUI: DocumentUpdated - Worker-->>Client: 成功响应与修订信息 - else 已过期或错误 - Worker->>Worker: 丢弃候选,保留已有有效程序 - Worker-->>Client: 409 / 422 / 500 等错误 - end -``` +![完整程序执行与发布时序](uml/rendered/publication.png) + +[放大 SVG](uml/rendered/publication.svg) · [编辑 UML 源码](uml/publication.puml) 图简化了 HTTP Response 的持有:原始请求在入队后由 worker 完成响应,不是 GUI 执行 HTTP 请求。可编辑来源:[publication.puml](uml/publication.puml)。 @@ -55,22 +27,9 @@ Console 的编译错误发生在执行前;运行期错误则可能保留此前 ## 代际与失败边界 -```mermaid -stateDiagram-v2 - [*] --> Candidate: 接受完整 PUT - Candidate --> Refreshing: 编译执行成功 - Candidate --> Rejected: 编译/执行错误 - Refreshing --> Refreshing: 让出并继续刷新 - Refreshing --> Active: 文档有效且 submission 匹配 - Refreshing --> Superseded: 更新的写入或删除 - Active --> Active: Console / 输入 / 任务完成 - Active --> Faulted: 活跃回调或刷新故障 - Active --> Retired: 成功替换 / reset / delete / shutdown - Faulted --> Retired: 清理或替换 - Rejected --> [*] - Superseded --> [*] - Retired --> [*] -``` +![候选与活跃运行时状态](uml/rendered/runtime.png) + +[放大 SVG](uml/rendered/runtime.svg) · [编辑 UML 源码](uml/runtime.puml) 这是候选和活跃运行时的概念状态图,并非源码中一个同名 enum。刷新具体由 `RefreshWork`、`PendingLayout`、paint Work 与 worker 的 PendingRequest 协作,不能在挂起时换一个 VM 恢复。 @@ -78,20 +37,9 @@ stateDiagram-v2 `ui.after`、`ui.readText`、`ui.fetchText` 和协作任务由托管 Task 表示。回调及 scope 是 VM 强边,调度索引保留弱身份。I/O 池只接收路径/URL等原生数据、取消控制及完成消息,不拿着 ObjectRef 在其他线程调用 VM。 -```mermaid -stateDiagram-v2 - [*] --> Pending - Pending --> Running: 到期 / 可以执行 - Pending --> Completed: provider 完成且无需回调 - Pending --> Failed: provider 返回错误 - Pending --> Cancelled: owner 失效 / key 替换 / 主动取消 - Running --> Completed: 成功交付 - Running --> Failed: 传输或执行错误 - Running --> Cancelled: 取消及生命周期清理 - Completed --> [*] - Failed --> [*] - Cancelled --> [*] -``` +![异步任务状态](uml/rendered/tasks.png) + +[放大 SVG](uml/rendered/tasks.svg) · [编辑 UML 源码](uml/tasks.puml) 源码的 Task 状态为 pending、running、completed、cancelled、failed;具体 provider 可能在 Pending 期间已开展后台 I/O,图中的 Running 不表示后台 I/O 一定此时才启动。见 [tasks.puml](uml/tasks.puml)。 diff --git a/docs/architecture/04-rendering.md b/docs/architecture/04-rendering.md index 1b50b1d..5c3fa4e 100644 --- a/docs/architecture/04-rendering.md +++ b/docs/architecture/04-rendering.md @@ -19,27 +19,9 @@ GUI 在 redraw 时组合已发布的画面和宿主 chrome,并按实际屏幕 ## 点击如何回到对象 -```mermaid -sequenceDiagram - actor User as 用户 - participant GUI as TesseraApp - participant Client as events::Client - participant API as API / worker - participant VM as ReplSession - participant Dispatch as event_dispatch - participant Publish as 刷新并发布 - User->>GUI: 鼠标按下 / 松开 - GUI->>GUI: 已发布几何命中,检查 press/release 目标 - GUI->>Client: Input(window, session, layout_version, mount) - Client->>API: POST /events - API->>API: 拒绝过期会话、窗口和拖放目标 - API->>VM: dispatch_incremental - VM->>Dispatch: 解析当前 Mount 和 Block - Dispatch->>Dispatch: capture → target → bubble - Dispatch->>VM: 受预算的 handler / onEvent / onClick - VM->>Publish: 刷新共享对象的相关展示 - Publish-->>GUI: 新 Frame / DocumentUpdated -``` +![原生输入与事件分发时序](uml/rendered/input.png) + +[放大 SVG](uml/rendered/input.svg) · [编辑 UML 源码](uml/input.puml) 可编辑来源:[input.puml](uml/input.puml)。没有 Mount 的代码主动 dispatch 只访问目标;有 Mount 的事件沿该次出现的父路径传播。事件监听器连接由 Block 保留,Subscription token 是弱控制句柄。 diff --git a/docs/architecture/05-workspace.md b/docs/architecture/05-workspace.md index 02df236..9e0ea9d 100644 --- a/docs/architecture/05-workspace.md +++ b/docs/architecture/05-workspace.md @@ -8,17 +8,9 @@ | 已发布 Tab / Frame / Window Envelope | 传输不透明 ID、标题、活动状态、窗口命令和版本 | 保留 VM 堆对象 | | TesseraApp / tabs::Motion / winit Window | 绘制、命中、拖动、滚动、原生资源及即时交互 | 执行业务回调、复制业务对象图 | -```mermaid -stateDiagram-v2 - [*] --> Open: Page 打开并被 registry 保留 - Open --> Selected: activate / 点击标签 - Selected --> Open: 选择别页 - Open --> Closed: close 释放 registry 边 - Selected --> Closed: 关闭活动页 - Closed --> Open: 脚本仍引用 Page 时重新打开 - Closed --> Collected: 不再有托管强边且 GC 回收 - Collected --> [*] -``` +![页面展示与可达性状态](uml/rendered/windows.png) + +[放大 SVG](uml/rendered/windows.svg) · [编辑 UML 源码](uml/windows.puml) 该图是**可达性与展示状态的说明**,不是一个源码 enum。关闭原生窗口、移除 Page 展示和回收对象不是同一动作。跨窗口拖放携带来源/目标窗口、布局版本、插入位置等元数据,worker 拒绝过期目标,再更新托管 registry;GUI 不直接移动堆对象。可编辑来源:[windows.puml](uml/windows.puml)。 diff --git a/docs/architecture/06-progress.md b/docs/architecture/06-progress.md index 4c52f5f..c963474 100644 --- a/docs/architecture/06-progress.md +++ b/docs/architecture/06-progress.md @@ -30,7 +30,7 @@ 本轮是整理,不扩展业务功能。沿用工作约定:格式、`cargo clippy --all-targets --offline -- -D warnings`、原生 release 打包、真实窗口和少量人工 API 操作;不执行 cargo test、自动 smoke 脚本或 Docker。Clippy 会编译检查已有测试代码,但不代表测试已经执行。 -最终实际执行结果见 [整理清单的验收记录](file-map.md#验收记录)。没有在本机安装 PlantUML/Graphviz 或额外测试依赖;Mermaid/PlantUML 图是可编辑文档源码,未宣称完成图形渲染器验收。 +最终实际执行结果见 [整理清单的验收记录](file-map.md#验收记录)。架构图已用官方 PlantUML JavaScript 引擎在本地生成 SVG 和 PNG,并检查实际图片。渲染工具临时安装在仓库外,不需要 Java、原生 Graphviz 或在线服务;详见 [UML 图册的重建步骤](uml/README.md#重新生成)。 ## 后续建议顺序 diff --git a/docs/architecture/07-decisions.md b/docs/architecture/07-decisions.md index 011667e..2938d1e 100644 --- a/docs/architecture/07-decisions.md +++ b/docs/architecture/07-decisions.md @@ -21,10 +21,10 @@ - 不更改 Endor 示例、API 路由、语法、运行时预算、窗口视觉参数和交互效果。 - 不更新 Aster 子模块,不改变 vendor 历史。 - 不移动构建产物、已有示例与媒体目录,不修改用户未提交的示例工作。 -- 不引入新的产品依赖、UML 渲染服务或构建工具。 +- 不引入新的产品依赖或在线 UML 渲染服务。文档图片由仓库外的临时 Node 工具生成,应用构建不依赖它。 ## 文档的可信度 -本套 UML 以实际 Rust 类型、线程名、队列、方法和引用语义为依据。概念状态机、主要调用流及省略字段都在图旁标明;它们不是自动从源码生成的完整模型。进展矩阵区分代码已有、此前人工验证、本轮验证及未完成项。 +本套 UML 以实际 Rust 类型、线程名、队列、方法和引用语义为依据。`.puml` 是图的唯一可编辑来源,PNG/SVG 由 `scripts/render-uml.mjs` 生成;文档直接引用生成图像。概念状态机、主要调用流及省略字段都在图旁标明;它们不是自动从源码生成的完整模型。进展矩阵区分代码已有、此前人工验证、本轮验证及未完成项。 更改执行/生命周期语义后应同步更新 `02/03/04` 与对应 `.puml`;更改 shell 交互后更新 `05`;发布阶段结果更新 `06` 和本轮验收记录。逐文件清单是本次迁移快照,不要求以后每次新增模块都伪装成同一轮迁移。 diff --git a/docs/architecture/README.md b/docs/architecture/README.md index faced32..f083503 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -17,7 +17,11 @@ Tessera 目前是**运行 Endor 对象程序的原生桌面宿主**。Endor 程 | [07 设计决策](07-decisions.md) | 为什么使用这些边界?整理还没有解决什么? | | [逐文件整理清单](file-map.md) | 每个文件迁移到哪里、负责什么,本次拆出了什么? | -UML 图直接嵌在上述 Markdown 中,支持 Mermaid 的阅读器可直接显示。另提供七份可编辑的 [PlantUML 源文件](uml/README.md),包括组件、部署、类、两条时序和两类状态机。两种表示都由当前代码人工核对,尚未接入自动生成或同步检查。 +UML 已渲染为普通 PNG 图片,直接嵌入各篇说明,不依赖 Mermaid 或 PlantUML 插件。需要放大可打开 SVG;八张图的图片、SVG 和可编辑源码集中在 [UML 图册](uml/README.md)。图像由本地脚本从 `.puml` 生成,不使用在线渲染服务。 + +![组件与主要数据流](uml/rendered/components.png) + +[放大组件图 SVG](uml/rendered/components.svg) ## 先抓住四个概念 diff --git a/docs/architecture/file-map.md b/docs/architecture/file-map.md index 4d26e09..a08633e 100644 --- a/docs/architecture/file-map.md +++ b/docs/architecture/file-map.md @@ -128,4 +128,17 @@ - 在线指南完整 GET 返回 HTTP 200;新增架构文档、源码导航和项目入口的本地文件链接检查通过。 - 原有 API/宿主测试随模块迁移并通过编译检查;未执行 cargo test、自动 smoke 或 Docker。 - Aster 子模块仍为 `f3e1670`。用户已有的示例变更保留且不提交。 -- 未安装 UML 渲染器或调用在线渲染服务;PlantUML/Mermaid 图没有完成渲染器/版面验收,图中省略范围均有说明。 +- 初轮仅提供 UML 源码;后续已补齐八图的本地 SVG/PNG 渲染、普通 Markdown 图片引用和实际图像检查,见下节。 + + +## UML 渲染补齐 + +- `scripts/render-uml.mjs`:新增本地官方 PlantUML 引擎的导出入口,使用 XML DOM、原生 Canvas 字体测量和 Viz 布局;检测错误图,生成不透明白底 SVG 与高分辨率 PNG。 +- `scripts/README.md`:增加文档渲染入口;不改变原生打包/检查流程。 +- `uml/components.puml`、`deployment.puml`、`domain.puml`、`publication.puml`、`input.puml`、`tasks.puml`、`windows.puml`:修正标签换行,统一字体和画布设置,调整组件图方向并修正部署图中不兼容的注释位置。 +- `uml/runtime.puml`:补充文档原有的候选/活跃运行时状态图源码。 +- `uml/rendered/{components,deployment,domain,publication,runtime,input,tasks,windows}.{svg,png}`:新增对应八张图的 SVG 和 PNG,共 16 个生成文件。 +- `01-modules.md`、`02-object-model.md`、`03-runtime.md`、`04-rendering.md`、`05-workspace.md`:把所有未渲染的 Mermaid 图块替换为普通图片,附 SVG 和源码链接。 +- `README.md`、`06-progress.md`、`07-decisions.md`、`uml/README.md` 和本清单:更新查看入口、图册、生成方式与实际验证状态。 + +八份源码均通过本地导出并检查实际图片;文档图片/本地链接、Node 语法和 Git 空白检查通过。本轮没有修改 Rust 应用代码,因此不重复运行应用构建或 cargo test。 diff --git a/docs/architecture/uml/README.md b/docs/architecture/uml/README.md index a7ea488..f993cc2 100644 --- a/docs/architecture/uml/README.md +++ b/docs/architecture/uml/README.md @@ -1,15 +1,67 @@ -# 可编辑 UML 源文件 +# UML 图册 -| 文件 | UML 类型与内容 | 对应说明 | -| --- | --- | --- | -| [components.puml](components.puml) | 组件图:主要调用与数据流;不冒充完整 import 图 | [01](../01-modules.md) | -| [deployment.puml](deployment.puml) | 部署图:线程、共享状态、原生窗口与 curl 子进程 | [01](../01-modules.md) | -| [domain.puml](domain.puml) | 类图:托管对象、弱边、Mount、不可变快照 | [02](../02-object-model.md) | -| [publication.puml](publication.puml) | 时序图:完整 PUT 的候选执行与代际发布 | [03](../03-runtime.md) | -| [input.puml](input.puml) | 时序图:原生输入回到活跃 VM 与刷新 | [04](../04-rendering.md) | -| [tasks.puml](tasks.puml) | 状态图:Task 完成、失败与取消 | [03](../03-runtime.md) | -| [windows.puml](windows.puml) | 状态图:Page 打开、关闭、重开与回收 | [05](../05-workspace.md) | +下面直接显示已渲染的 PNG,不需要安装 Markdown 插件。打开 SVG 可以放大阅读;`.puml` 保留可编辑源码。画布为不透明白底,避免深色查看器把黑色文字和连线淹没。 -这些 `.puml` 是可编辑的标准 UML 源码;Markdown 中另有 Mermaid 阅读版本。它们均为人工维护,当前没有自动同步生成步骤。概念图已标注其简化范围。 +## 组件与主要数据流 -本轮没有安装 PlantUML/Graphviz 或调用在线渲染服务,因此未验证具体渲染器的版面输出。已有本地 PlantUML 环境时,可从项目根目录执行 `plantuml docs/architecture/uml/*.puml` 导出 SVG/PNG;不要为查看架构而上传整个仓库或私有对象数据。 +![组件与主要数据流](rendered/components.png) + +[放大 SVG](rendered/components.svg) · [编辑源码](components.puml) + +## 进程与线程部署 + +![进程与线程部署](rendered/deployment.png) + +[放大 SVG](rendered/deployment.svg) · [编辑源码](deployment.puml) + +## 对象模型与引用关系 + +![对象模型与引用关系](rendered/domain.png) + +[放大 SVG](rendered/domain.svg) · [编辑源码](domain.puml) + +## 完整程序执行与发布时序 + +![完整程序执行与发布时序](rendered/publication.png) + +[放大 SVG](rendered/publication.svg) · [编辑源码](publication.puml) + +## 候选与活跃运行时状态 + +![候选与活跃运行时状态](rendered/runtime.png) + +[放大 SVG](rendered/runtime.svg) · [编辑源码](runtime.puml) + +## 原生输入与事件分发时序 + +![原生输入与事件分发时序](rendered/input.png) + +[放大 SVG](rendered/input.svg) · [编辑源码](input.puml) + +## 异步任务状态 + +![异步任务状态](rendered/tasks.png) + +[放大 SVG](rendered/tasks.svg) · [编辑源码](tasks.puml) + +## 页面展示与可达性状态 + +![页面展示与可达性状态](rendered/windows.png) + +[放大 SVG](rendered/windows.svg) · [编辑源码](windows.puml) + +## 重新生成 + +从项目根目录运行下面的文档工具。依赖只安装到临时目录,固定版本;不写入 Cargo、应用依赖或全局环境。渲染时不上传图的源码。 + +```sh +export UML_RENDER_TOOLS="$(mktemp -d /private/tmp/tessera-uml.XXXXXX)" +npm install --prefix "$UML_RENDER_TOOLS" --ignore-scripts --no-audit --no-fund \ + @plantuml/core@1.2026.9 @viz-js/viz@3.17.0 \ + @napi-rs/canvas@0.1.80 @xmldom/xmldom@0.9.12 sharp@0.34.5 +node scripts/render-uml.mjs +``` + +使用官方 `@plantuml/core` JavaScript 引擎、Viz 布局、XML DOM 和本机 Canvas 字体测量,不需要 Java 或原生 Graphviz。PNG 由同一份 SVG 导出。脚本对渲染错误图做检查,失败则停止;修改源码后应重新生成并查看图片。 + +字体取自本机,跨机器重建可能有微小的排版差异。源图中的概念状态与省略字段范围以各篇架构说明为准;渲染不会把概念图变成自动提取的完整代码模型。 diff --git a/docs/architecture/uml/components.puml b/docs/architecture/uml/components.puml index 3b7661c..de8dff8 100644 --- a/docs/architecture/uml/components.puml +++ b/docs/architecture/uml/components.puml @@ -1,24 +1,19 @@ @startuml -left to right direction +skinparam backgroundColor #FFFFFF +skinparam defaultFontName Arial +skinparam defaultFontSize 14 +skinparam shadowing false +top to bottom direction title Tessera — implemented components (principal runtime flows) -component "shell -windows / tabs / developer tools" as Shell -component "runtime/api -HTTP + queue" as API -component "runtime/api/worker -serial VM ownership" as Worker -component "bridge/ui_bridge -types / native calls / refresh" as Bridge -component "model -objects / mounts / bindings" as Model -component "render -layout / paint / hit / raster" as Render -component "Aster -frontend / compiler / core" as Aster -component "runtime/io_tasks -plain-data completion" as IO -database "NamespaceState -owned document + frame values" as State +component "shell\nwindows / tabs / developer tools" as Shell +component "runtime/api\nHTTP + queue" as API +component "runtime/api/worker\nserial VM ownership" as Worker +component "bridge/ui_bridge\ntypes / native calls / refresh" as Bridge +component "model\nobjects / mounts / bindings" as Model +component "render\nlayout / paint / hit / raster" as Render +component "Aster\nfrontend / compiler / core" as Aster +component "runtime/io_tasks\nplain-data completion" as IO +database "NamespaceState\nowned document + frame values" as State Shell --> API : serialized input / Console API --> Worker : bounded BuildRequest queue Worker --> Aster : compile / execute diff --git a/docs/architecture/uml/deployment.puml b/docs/architecture/uml/deployment.puml index 9c5d417..9753578 100644 --- a/docs/architecture/uml/deployment.puml +++ b/docs/architecture/uml/deployment.puml @@ -1,18 +1,18 @@ @startuml +skinparam backgroundColor #FFFFFF +skinparam defaultFontName Arial +skinparam defaultFontSize 14 +skinparam shadowing false title Tessera — local process and thread deployment node "User computer" { artifact "Local agent client" as Agent node "Tessera desktop process" { - node "GUI main thread -winit + softbuffer" as GUI - node "tessera-agent-api -HTTP receiver" as API - node "tessera-endor-worker -ReplSession / Candidate / Aster heap" as Worker + node "GUI main thread\nwinit + softbuffer" as GUI + node "tessera-agent-api\nHTTP receiver" as API + node "tessera-endor-worker\nReplSession / Candidate / Aster heap" as Worker node "Input sender thread" as Input node "Lazy bounded I/O pool" as IO - database "Arc> -no VM handles in published frames" as State + database "Arc>\nno VM handles in published frames" as State API --> Worker : bounded queue (8 pending) Worker --> State : commit document State --> GUI : native snapshots @@ -26,7 +26,4 @@ no VM handles in published frames" as State GUI --> Window IO --> Curl : fetchText transport } -note bottom of Worker -Aster libraries are linked into Tessera. -No Lyra/Hestia process is required. @enduml diff --git a/docs/architecture/uml/domain.puml b/docs/architecture/uml/domain.puml index dc1779c..cf9582b 100644 --- a/docs/architecture/uml/domain.puml +++ b/docs/architecture/uml/domain.puml @@ -1,4 +1,8 @@ @startuml +skinparam backgroundColor #FFFFFF +skinparam defaultFontName Arial +skinparam defaultFontSize 14 +skinparam shadowing false title Tessera — managed identity versus published values hide empty methods class ReplSession { @@ -44,18 +48,18 @@ class Mount { class MountTable { active: Map } -class UiNode <> { +class UiNode { block_id: String slots: u64[] kind: UiKind } -class Frame <> { +class Frame { session: u64 layout_version: u64 commands: RenderCommand[] tabs: Tab[] } -class RenderDocument <> { +class RenderDocument { source: String ui_root: Arc windows: Map diff --git a/docs/architecture/uml/input.puml b/docs/architecture/uml/input.puml index 749862d..c0e84f7 100644 --- a/docs/architecture/uml/input.puml +++ b/docs/architecture/uml/input.puml @@ -1,4 +1,8 @@ @startuml +skinparam backgroundColor #FFFFFF +skinparam defaultFontName Arial +skinparam defaultFontSize 14 +skinparam shadowing false title Native input — one VM and one event dispatcher actor User participant TesseraApp as GUI diff --git a/docs/architecture/uml/publication.puml b/docs/architecture/uml/publication.puml index 88d6b2f..e128893 100644 --- a/docs/architecture/uml/publication.puml +++ b/docs/architecture/uml/publication.puml @@ -1,4 +1,8 @@ @startuml +skinparam backgroundColor #FFFFFF +skinparam defaultFontName Arial +skinparam defaultFontSize 14 +skinparam shadowing false title Complete PUT — isolated execution and epoch-checked publication actor Client participant "api.rs" as API diff --git a/docs/architecture/uml/rendered/components.png b/docs/architecture/uml/rendered/components.png new file mode 100644 index 0000000..4f4f047 Binary files /dev/null and b/docs/architecture/uml/rendered/components.png differ diff --git a/docs/architecture/uml/rendered/components.svg b/docs/architecture/uml/rendered/components.svg new file mode 100644 index 0000000..0e428f7 --- /dev/null +++ b/docs/architecture/uml/rendered/components.svg @@ -0,0 +1 @@ +Tessera — implemented components (principal runtime flows)shellwindows / tabs / developer toolsruntime/apiHTTP + queueruntime/api/workerserial VM ownershipbridge/ui_bridgetypes / native calls / refreshmodelobjects / mounts / bindingsrenderlayout / paint / hit / rasterAsterfrontend / compiler / coreruntime/io_tasksplain-data completionNamespaceStateowned document + frame valuesDirectory groups are not separate crates.Imports still cross groups; this is notan exhaustive or acyclic import graph.serialized input / Consolebounded BuildRequest queuecompile / executeinstall / refresh / dispatchmanaged graph + dependenciesderive framevalidate epoch + publishimmutable snapshotcompose chrome + rasterizerequest / completion \ No newline at end of file diff --git a/docs/architecture/uml/rendered/deployment.png b/docs/architecture/uml/rendered/deployment.png new file mode 100644 index 0000000..c1e55c5 Binary files /dev/null and b/docs/architecture/uml/rendered/deployment.png differ diff --git a/docs/architecture/uml/rendered/deployment.svg b/docs/architecture/uml/rendered/deployment.svg new file mode 100644 index 0000000..641a4e8 --- /dev/null +++ b/docs/architecture/uml/rendered/deployment.svg @@ -0,0 +1 @@ +Tessera — local process and thread deploymentUser computerTessera desktop processLocal agent clientSystem curl subprocessOS window + pixel bufferGUI main threadwinit + softbuffertessera-agent-apiHTTP receivertessera-endor-workerReplSession / Candidate / Aster heapInput sender threadLazy bounded I/O poolArc<RwLock<NamespaceState>>no VM handles in published framesbounded queue (8 pending)commit documentnative snapshotsInput valuesloopback HTTPmailbox / cancellation127.0.0.1:4737fetchText transport \ No newline at end of file diff --git a/docs/architecture/uml/rendered/domain.png b/docs/architecture/uml/rendered/domain.png new file mode 100644 index 0000000..e5c590f Binary files /dev/null and b/docs/architecture/uml/rendered/domain.png differ diff --git a/docs/architecture/uml/rendered/domain.svg b/docs/architecture/uml/rendered/domain.svg new file mode 100644 index 0000000..648dcde --- /dev/null +++ b/docs/architecture/uml/rendered/domain.svg @@ -0,0 +1 @@ +Tessera — managed identity versus published valuesCReplSessionid: u64faulted: boolCCandidatevm: Vmroots: ObjectRef[]globals: ObjectRefCUiBridgeCPresentationdesktop: ObjectRefactive: ObjectRefrender_cache: RenderCacheCManagedWindowid: u64pages: ObjectRef[]closed: boolCBlockstate: ObjectRefpage: boolCCellCDatakind: Kindchildren: Child[]bindings: ObjectRef[]CChildslot: u64block: ObjectRefCMountblock: ObjectRefpage: WeakObjectRefparent: WeakObjectRefgeometry: MountGeometryCMountTableactive: Map<u64, WeakObjectRef>CUiNodeblock_id: Stringslots: u64[]kind: UiKindCFramesession: u64layout_version: u64commands: RenderCommand[]tabs: Tab[]CRenderDocumentsource: Stringui_root: Arc<UiNode>windows: MapPage is a managed Block kind/nominal type.This omits type tables, service dictionaries,captured roots and many fields: not a full GC graph.shared Sessionopen Pages retainedstateshared assignment forwardingordinary contentstrongweak reverse/sibling linksweak indexcached derivationsecondary windows \ No newline at end of file diff --git a/docs/architecture/uml/rendered/input.png b/docs/architecture/uml/rendered/input.png new file mode 100644 index 0000000..469782b Binary files /dev/null and b/docs/architecture/uml/rendered/input.png differ diff --git a/docs/architecture/uml/rendered/input.svg b/docs/architecture/uml/rendered/input.svg new file mode 100644 index 0000000..d189555 --- /dev/null +++ b/docs/architecture/uml/rendered/input.svg @@ -0,0 +1 @@ +Native input — one VM and one event dispatcherUserTesseraAppevents..ClientAPI . workerReplSessionevent_dispatchrefresh . publicationUserTesseraAppevents::ClientAPI / workerReplSessionevent_dispatchrefresh / publicationUserTesseraAppevents::ClientAPI / workerReplSessionevent_dispatchrefresh / publicationpointer press / releasepublished geometry; matching targetInput(window, session, layout_version, mount)POST /eventsreject stale source/destination identitiesdispatch_incrementaltarget Block + optional Mountcapture -> target -> bubblebudgeted handler / onEvent / onClickupdate related presentationsFrame / DocumentUpdatedWithout a Mount, dispatch visits only the target.With a Mount, traversal follows that occurrence. \ No newline at end of file diff --git a/docs/architecture/uml/rendered/publication.png b/docs/architecture/uml/rendered/publication.png new file mode 100644 index 0000000..26f294f Binary files /dev/null and b/docs/architecture/uml/rendered/publication.png differ diff --git a/docs/architecture/uml/rendered/publication.svg b/docs/architecture/uml/rendered/publication.svg new file mode 100644 index 0000000..1b620ea --- /dev/null +++ b/docs/architecture/uml/rendered/publication.svg @@ -0,0 +1 @@ +Complete PUT — isolated execution and epoch-checked publicationClientapi.rsBuildRequest queueapi.worker.rsAster candidate VMUiBridgeNamespaceStateTesseraAppClientapi.rsBuildRequest queueapi/worker.rsAster candidate VMUiBridgeNamespaceStateTesseraAppClientapi.rsBuildRequest queueapi/worker.rsAster candidate VMUiBridgeNamespaceStateTesseraAppPUT /v1/namespaces/app.main/codevalidate / assign accepted submissionbounded enqueuereceive requestparse / compile / execute in fresh candidateallocate objects / Pagesloop[incremental refresh slices]bindings / layout / paint / mountsPending or native documentverify submission epochalt[valid and successful]commit document + window commandscandidate becomes active ReplSessionDocumentUpdatedresponse + committed revision[superseded / failed]discard candidate; keep valid live owner409 / 422 / 500 as applicableWorker retains the observed request and responds.GUI does not execute the HTTP request or VM. \ No newline at end of file diff --git a/docs/architecture/uml/rendered/runtime.png b/docs/architecture/uml/rendered/runtime.png new file mode 100644 index 0000000..6c3add5 Binary files /dev/null and b/docs/architecture/uml/rendered/runtime.png differ diff --git a/docs/architecture/uml/rendered/runtime.svg b/docs/architecture/uml/rendered/runtime.svg new file mode 100644 index 0000000..af206f0 --- /dev/null +++ b/docs/architecture/uml/rendered/runtime.svg @@ -0,0 +1 @@ +Candidate and active runtime (conceptual states)CandidateRefreshingRejectedActiveSupersededFaultedRetiredaccepted complete PUTcompilation / execution succeedscompilation / execution erroryield / continue refreshvalid document + matching submissionnewer write / deleteConsole / input / task completioncallback or refresh faultreplace / reset / delete / shutdowncleanup or replace \ No newline at end of file diff --git a/docs/architecture/uml/rendered/tasks.png b/docs/architecture/uml/rendered/tasks.png new file mode 100644 index 0000000..6ca865e Binary files /dev/null and b/docs/architecture/uml/rendered/tasks.png differ diff --git a/docs/architecture/uml/rendered/tasks.svg b/docs/architecture/uml/rendered/tasks.svg new file mode 100644 index 0000000..71bb868 --- /dev/null +++ b/docs/architecture/uml/rendered/tasks.svg @@ -0,0 +1 @@ +Managed Task — lifecycle states from tasks.rsPendingRunningCompletedFailedCancelledProvider I/O may already run while the Taskis Pending. Running does not necessarilymean the I/O starts at that instant.Scheduler index is weak; callbacks/scopesare traced managed edges.due / delivery eligibleprovider done; no callbackprovider errorowner invalid / key replacement / cancelsuccessful deliverytransport or execution errorcancel / lifecycle cleanup \ No newline at end of file diff --git a/docs/architecture/uml/rendered/windows.png b/docs/architecture/uml/rendered/windows.png new file mode 100644 index 0000000..87f2a10 Binary files /dev/null and b/docs/architecture/uml/rendered/windows.png differ diff --git a/docs/architecture/uml/rendered/windows.svg b/docs/architecture/uml/rendered/windows.svg new file mode 100644 index 0000000..4c4ae41 --- /dev/null +++ b/docs/architecture/uml/rendered/windows.svg @@ -0,0 +1 @@ +Page visibility and reachability (conceptual states)OpenSelectedClosedCollectedClosing a tab is not destroying an object.Cross-window moves update managed registriesonly after session/layout/drop validation.Page registeredactivate / click tabselect another Pageclose / release registry edgestill referenced; reopenclose active Pageno strong managed path; GC \ No newline at end of file diff --git a/docs/architecture/uml/runtime.puml b/docs/architecture/uml/runtime.puml new file mode 100644 index 0000000..ad2d0d8 --- /dev/null +++ b/docs/architecture/uml/runtime.puml @@ -0,0 +1,20 @@ +@startuml +skinparam backgroundColor #FFFFFF +skinparam defaultFontName Arial +skinparam defaultFontSize 14 +skinparam shadowing false +title Candidate and active runtime (conceptual states) +[*] --> Candidate : accepted complete PUT +Candidate --> Refreshing : compilation / execution succeeds +Candidate --> Rejected : compilation / execution error +Refreshing --> Refreshing : yield / continue refresh +Refreshing --> Active : valid document + matching submission +Refreshing --> Superseded : newer write / delete +Active --> Active : Console / input / task completion +Active --> Faulted : callback or refresh fault +Active --> Retired : replace / reset / delete / shutdown +Faulted --> Retired : cleanup or replace +Rejected --> [*] +Superseded --> [*] +Retired --> [*] +@enduml diff --git a/docs/architecture/uml/tasks.puml b/docs/architecture/uml/tasks.puml index 5e2e2a9..67ab98b 100644 --- a/docs/architecture/uml/tasks.puml +++ b/docs/architecture/uml/tasks.puml @@ -1,4 +1,8 @@ @startuml +skinparam backgroundColor #FFFFFF +skinparam defaultFontName Arial +skinparam defaultFontSize 14 +skinparam shadowing false title Managed Task — lifecycle states from tasks.rs [*] --> Pending Pending --> Running : due / delivery eligible diff --git a/docs/architecture/uml/windows.puml b/docs/architecture/uml/windows.puml index 5f215ee..d1e8e2c 100644 --- a/docs/architecture/uml/windows.puml +++ b/docs/architecture/uml/windows.puml @@ -1,4 +1,8 @@ @startuml +skinparam backgroundColor #FFFFFF +skinparam defaultFontName Arial +skinparam defaultFontSize 14 +skinparam shadowing false title Page visibility and reachability (conceptual states) [*] --> Open : Page registered Open --> Selected : activate / click tab diff --git a/scripts/README.md b/scripts/README.md index 6f5dd13..b2224aa 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -22,3 +22,11 @@ read-only and retains Cargo downloads/build output in project-specific Docker volumes. CI_CACHE_SCOPE selects main/manual or a PR cache namespace. It acquires a host lock and removes its own container on interruption; cached volumes survive. See [workflow details](../.gitea/workflows/README.md) for invalidation and triggers. + + +## UML 文档渲染 + +`render-uml.mjs` 从 `docs/architecture/uml/*.puml` 在本地生成 SVG 和 PNG,输出到 +`docs/architecture/uml/rendered/`。固定工具版本与运行步骤见 +[UML 图册](../docs/architecture/uml/README.md#重新生成)。这些 Node 工具独立于应用依赖, +不需要 Java、原生 Graphviz 或远程渲染服务。 diff --git a/scripts/render-uml.mjs b/scripts/render-uml.mjs new file mode 100644 index 0000000..72cdfc9 --- /dev/null +++ b/scripts/render-uml.mjs @@ -0,0 +1,87 @@ +#!/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. +import { createRequire } from 'node:module'; +import { readFile, readdir, mkdir, writeFile } from 'node:fs/promises'; +import path from 'node:path'; +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'); +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. +globalThis.PLANTUML_VIZ = require('@viz-js/viz'); +globalThis.window = globalThis; +globalThis.XMLSerializer = XMLSerializer; +globalThis.DOMParser = DOMParser; +const document = new DOMImplementation().createDocument(null, 'root', null); +const element = document.createElement.bind(document); +const elementNS = document.createElementNS.bind(document); +function measurementCanvas() { + const canvas = createCanvas(1, 1); + const context = canvas.getContext('2d'); + const measure = context.measureText.bind(context); + 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, + actualBoundingBoxAscent: metrics.fontBoundingBoxAscent || metrics.actualBoundingBoxAscent, + actualBoundingBoxDescent: metrics.fontBoundingBoxDescent || metrics.actualBoundingBoxDescent, + }; + }; + return canvas; +} +document.createElement = tag => tag === 'canvas' ? measurementCanvas() : element(tag); +document.createElementNS = (namespace, tag) => { + const node = elementNS(namespace, tag); + node.style = {}; + node.getBBox = () => { + const context = measurementCanvas().getContext('2d'); + context.font = `${node.getAttribute('font-size') || 14}px ${node.getAttribute('font-family') || 'Arial'}`; + const metrics = context.measureText(node.textContent || ''); + return { + width: metrics.width, + height: metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent, + x: 0, + y: -metrics.actualBoundingBoxAscent, + }; + }; + return node; +}; +document.body = element('body'); +document.documentElement.appendChild(document.body); +globalThis.document = document; +const { renderToString } = await import(pathToFileURL(require.resolve('@plantuml/core'))); +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 }); +for (const filename of (await readdir(source)).filter(name => name.endsWith('.puml')).sort()) { + const text = await readFile(path.join(source, filename), 'utf8'); + 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. + 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); + const svg = new XMLSerializer().serializeToString(xml); + 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. + 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(); + console.log(`${filename} -> SVG + PNG (${metadata.width}×${metadata.height})`); +}