docs: clarify protocol and document publication contracts

This commit is contained in:
2026-11-12 20:38:06 +08:00
parent ab3cd0c7cf
commit 0c4bd06231
3 changed files with 22 additions and 5 deletions
+15 -4
View File
@@ -29,14 +29,14 @@ pub struct NamespaceState {
pub revision: u64,
// 较新完整 PUT/DELETE 会改变提交身份;旧输入即使晚完成也不得覆盖新结果。
pub submission: u64,
// 最近成功的完整文档;编译/执行失败或过期候选不替换它。
// 最近完整发布的文档;失败候选不替换其几何,但 worker 可在旧完整画面上追加 fault 诊断后重新提交。
pub document: RenderDocument,
// viewport 是主窗口逻辑页面区域;window_viewports 同时记录仍存活的副窗口。
pub viewport: Option<crate::layout::Size>,
pub window_viewports: std::collections::BTreeMap<u64, crate::layout::Size>,
// 原生命令与运行时世代一起发布,防止窗口 ID 在跨 VM 时被误用。
pub runtime_session: u64,
// 待窗口壳消费的世代化原生命令,按动作合并并保留全局请求顺序。
// 待窗口壳消费的世代化原生命令,按同窗动作合并;sequence 只在各窗口内单调,不承诺跨窗口的全局发生顺序。
pub window_commands: Vec<crate::window::Envelope>,
}
@@ -81,7 +81,7 @@ impl NamespaceState {
self.window_commands
.push(crate::window::Envelope { session, command });
}
// 合并后按 VM 原始 sequence 恢复执行顺序,避免 retain/push 使不同资源动作乱序。
// 按各命令原 sequence 排序,恢复同窗保留动作的先后;不同窗口的序号可以相同,不能由此推导跨窗时间顺序。
self.window_commands
.sort_by_key(|command| command.command.sequence);
}
@@ -94,6 +94,7 @@ impl NamespaceState {
}
/// 仅当提交身份仍是最新时替换完整文档并递增版本;已被取代的结果不发布。
/// 发布调用方须先完成文档验证与适用的世代检查;这里不自动 validate,也不设置 runtime_session 或发布窗口命令。
pub fn commit(&mut self, submission: u64, document: RenderDocument) -> Result<Option<u64>> {
// 先核对归属,再计算新版本;失败或过时的结果不会替换已显示文档。
if submission != self.submission {
@@ -469,7 +470,8 @@ impl CodeNode {
}
#[derive(Clone, Debug, Serialize, Deserialize)]
/// 一个窗口的一次完整视觉发布:有序命令及其裁剪/变换、出现几何、焦点和版本。平行索引表必须和命令数量一致。
/// 一个窗口的视觉帧数据:有序命令及其裁剪/变换、出现几何、焦点和版本。布局/绘制也用此结构保存未发布草稿。
/// 是否完整可见由运行时的验证与稳定发布边界决定;仅持有 Frame 或 layout_version 不能证明它已发布。
pub struct Frame {
// 命中索引是可重建的本地优化,不作为序列化协议的一部分保存。
#[serde(skip)]
@@ -605,6 +607,7 @@ impl MountGeometry {
}
/// 把视图位移换算成目标出现的局部位移,处理缩放与世界 UI 投影差异。
pub fn logical_delta(&self, point: Option<[f32; 2]>, delta: [f32; 2]) -> Option<[f32; 2]> {
// page_input 的相机手势和 UiBridge 的 scroll 输入共用;返回的是本出现布局单位,视口相机自身的 zoom 由各调用方再解释。
// 累计二维缩放用于把最终视图差值还原到布局位移;透视面板还需先投影两个端点。
let zoom = self.view.unwrap_or_default().zoom;
// 普通二维映射为线性,只除累计 zoom 即可;世界面板透视非线性,必须映射两个点求差。
@@ -641,6 +644,7 @@ impl MountGeometry {
impl Frame {
/// 从顶层绘制顺序向后查找可控制的视口,命中与裁剪均成立才接收相机手势。
pub fn camera_at(&self, point: Point) -> Option<&MountGeometry> {
// 本方法不检查 frame.fault 或 session;shell 接纳输入的外层流程仍须验证运行域和发布身份。
// 窗口手势目标选择使用空间索引候选次序,但仍须逐个通过视口种类、外框和内容裁剪。
self.hit_index
.candidates(point, self.mounts.len())
@@ -689,15 +693,22 @@ pub enum RenderCommand {
#[serde(skip_deserializing)]
// 仅本机可构造的不可变图像资源命令,禁止从外部 JSON 反序列化任意图像资源。
Image {
// 旋转/缩放围绕的逻辑原点;与下面局部图像矩形偏移分开保存。
x: f32,
y: f32,
// 显示矩形的逻辑尺寸,可与原始像素宽高不同;设备比例在 to_draw_command 中应用。
width: f32,
height: f32,
// 相对 origin 的局部矩形起点,Sprite 锚点通过负偏移表示,不移动资源本身的像素。
offset_x: f32,
offset_y: f32,
// 弧度旋转角,设备同比缩放不改变角度。
angle: f32,
// 整体混合透明度,发布验证要求位于 [0,1]。
opacity: f32,
// 可选颜色调制;None 使用图像本来的颜色,区别于全透明调制色。
tint: Option<Color>,
// 原生像素由 Arc 独立保活;GUI 绘制无需用源对象 ID 查 VM 堆。
image: Arc<crate::render::image::Image>,
},
// 屏幕矩形中的三维 View 快照,世界几何和相机数据由原生 Arc 独立拥有。