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 独立拥有。
+3
View File
@@ -94,6 +94,8 @@ pub fn install(
CallEffect::External,
)
};
// Aster typed trait 要求固定的规范调用形状;例如 on 以 receiver+事件名+回调+阶段四参描述。
// 这只修改 trait 的签名副本,不收紧原生 on/dispatch 方法本身允许省略尾参的 arity。
signature.arity = CallArity::exact(parameters + 1);
// 接收者类型改为 Any,使能力可由其他符合方法契约的名义类型实现,不把契约绑定死在 Block。
signature.parameters[0] = AnnotationType::Any.into();
@@ -103,6 +105,7 @@ pub fn install(
});
}
// VM 创建受类型约束的 trait;后面保活、附 Trait 名义类型并公开两个查询入口。
// EndorTraitObject.trace 会追踪签名中的名义类型,requirements 不是只供显示的无拥有关系文本。
let capability = vm.new_typed_trait(name, requirements)?;
// 新能力放入宿主 roots 管理生命周期,再同时暴露于 ui 属性与 desktop 类型注册表。
roots.push(capability);
+4 -1
View File
@@ -546,6 +546,7 @@ pub fn snapshot(
snapshot_reusing(store, scene, camera, None)
}
/// 遍历场景并记录字段依赖;如果世界数据未变则复用不可变场景和 BVH,只替换摄像机视图。
/// RenderCache 传入同一 Scene3D 的旧场景;仍完整读取当前场景并比较数值,复用并不意味着跳过遍历或沿用旧依赖。
pub fn snapshot_reusing(
store: &ObjectStore,
scene: ObjectRef,
@@ -625,6 +626,7 @@ pub fn snapshot_reusing(
match kind {
NodeKind::Scene | NodeKind::Group => {
// 通过 Reader 记录 children 属性引用,items 再验证它确为 ObjectList。
// 此处记录的是 owner.children 属性键;items 借用列表 payload,不会给 reader.reads 自动添加列表内容依赖。
let list = object_ref(&reader.value(object, "children")?)?;
// 逆序压栈保留列表原始遍历次序,每个子出现都继承当前 world。
for (index, child) in object_list::items(store, list)?.iter().enumerate().rev() {
@@ -891,7 +893,7 @@ pub fn pick(
}
#[derive(Debug)]
/// 指针拾取的中间结果,保留交点与所属实例信息供 Event/RayHit3D 使用。
/// UiBridge 为三维点击分配的零参原生适配器;invoke 才执行拾取并将 RayHit3D/Nil 放进 Event.hit。
pub struct PointerPick {
// 原生指针目标的托管 Mount,由调用方包装的 captures 保活。
pub mount: ObjectRef,
@@ -1023,6 +1025,7 @@ pub fn control(
return Err(invalid("camera movement exceeds world budget"));
}
// 位置与 target 逐轴经 NativeContext 写回,变化日志让下一视觉快照观察到更新。
// 正交 zoom 分支还会单独写 height;这些是普通属性写入,不构成多字段事务回滚,失败处理由外层 VM 调用路径负责。
for (name, value) in [
("x", position.x),
("y", position.y),