docs: render UML diagrams and embed portable previews
Verify Tessera GUI / verify (push) Failing after 1m30s

This commit is contained in:
2026-10-25 22:09:47 +08:00
parent 18376793b0
commit 21439d4c4d
36 changed files with 278 additions and 252 deletions
+6 -34
View File
@@ -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 不在应用依赖链中。
+3 -75
View File
@@ -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 有对应关系,但不是同一对象。
+9 -61
View File
@@ -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)。
+3 -21
View File
@@ -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 是弱控制句柄。
+3 -11
View File
@@ -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)。
+1 -1
View File
@@ -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#重新生成)。
## 后续建议顺序
+2 -2
View File
@@ -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` 和本轮验收记录。逐文件清单是本次迁移快照,不要求以后每次新增模块都伪装成同一轮迁移。
+5 -1
View File
@@ -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)
## 先抓住四个概念
+14 -1
View File
@@ -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。
+64 -12
View File
@@ -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 导出。脚本对渲染错误图做检查,失败则停止;修改源码后应重新生成并查看图片。
字体取自本机,跨机器重建可能有微小的排版差异。源图中的概念状态与省略字段范围以各篇架构说明为准;渲染不会把概念图变成自动提取的完整代码模型。
+14 -19
View File
@@ -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
+8 -11
View File
@@ -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<RwLock<NamespaceState>>
no VM handles in published frames" as State
database "Arc<RwLock<NamespaceState>>\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
+7 -3
View File
@@ -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<u64, WeakObjectRef>
}
class UiNode <<immutable native value>> {
class UiNode {
block_id: String
slots: u64[]
kind: UiKind
}
class Frame <<published native value>> {
class Frame {
session: u64
layout_version: u64
commands: RenderCommand[]
tabs: Tab[]
}
class RenderDocument <<published native value>> {
class RenderDocument {
source: String
ui_root: Arc<UiNode>
windows: Map
+4
View File
@@ -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
+4
View File
@@ -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
Binary file not shown.

After

Width:  |  Height:  |  Size: 317 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 264 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 469 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 251 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 17 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 376 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 23 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 227 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 226 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 169 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 8.4 KiB

+20
View File
@@ -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
+4
View File
@@ -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
+4
View File
@@ -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
+8
View File
@@ -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 或远程渲染服务。
+87
View File
@@ -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})`);
}