diff --git a/src/bridge/ui_bridge/developer_pages.rs b/src/bridge/ui_bridge/developer_pages.rs index 08c590b..0b3b210 100644 --- a/src/bridge/ui_bridge/developer_pages.rs +++ b/src/bridge/ui_bridge/developer_pages.rs @@ -40,6 +40,7 @@ impl NativeCallable for OpenTool { }); } // 锁内只复制弱节点索引,之后逐个升级并查工具标记,不持 session 锁运行 show 的流程。 + // 搜索范围是会话全部节点而非 current 的标签;已关闭但仍被源引用的工具页也可复用,死亡弱项则跳过。 let nodes = self .session .lock() @@ -73,6 +74,7 @@ impl NativeCallable for OpenTool { } } // 没有现存工具页才创建空托管 Page,_tesseraTool 标记让宿主在该页面位置绘制对应管理工具。 + // 工具原生内容不需要伪造 Block 子树;空 Page 仍沿正常窗口注册、标签投影及生命周期刷新路径展示。 let page = new_typed_block( cx, Data::new(Kind::Page, vec![], 0.0, 0.0), @@ -107,6 +109,7 @@ pub(super) fn install(vm: &mut Vm, ui: ObjectRef, session: &Shared) -> Result<() /// 每个 VM 仅安装一次,后续新标签操作重复调用工厂;源类/闭包仍由正常 VM 对象系统管理。 pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> { // 源码随 binary 嵌入,每个 VM 安装时解析/编译一次;函数工厂之后重复执行不再重复编译模块。 + // 模板之后必须 load 到传入的所属 VM;不同会话的类、闭包和私有 globals 不能复用另一 VM 的托管对象身份。 let source = frontend::EndorReader::from_text( "tessera:start-page.endor", include_str!("start_page.endor"), diff --git a/src/model/presentation.rs b/src/model/presentation.rs index 3b8cd56..7c20be0 100644 --- a/src/model/presentation.rs +++ b/src/model/presentation.rs @@ -31,7 +31,7 @@ pub(crate) struct Presentation { pub tab_ids: Vec<(WeakObjectRef, u64)>, // 分配新原生标签 ID 的单调计数,与可被回收的 Page 弱身份分开。 pub next_tab: u64, - // 最近发布的标签值列表,用于检测标题/活动项/顺序变化。 + // 最近一次桥接 commit_frame 保存的标签草稿,用于检测标题/活动项/顺序变化;不保证 GUI 已收到该帧。 pub last_tabs: Vec, // 当前页面兼容表面相机和模式,随本窗口展示更新。 pub surface: crate::page::Surface, @@ -41,7 +41,8 @@ pub(crate) struct Presentation { pub layout: crate::layout::LayoutRuntime, // 本窗口活动 Mount 的弱索引与发布顺序,托管字典负责强拥有。 pub mounts: crate::mount::MountTable, - // 最后完整发布的布局版本,未提交的分片结果不能直接覆盖此边界。 + // commit_frame 已同步 Mount 的布局版本,输入检查据此拒绝旧几何;后续 paint/稳定发布仍可能尚未完成。 + // 字段名沿用 published_version,但不代表此值已经写入 GUI 共享文档,也不是整个源输入的成功标记。 pub published_version: u64, // 即使根快照身份未变也要求重新发布一帧,例如源绘制读取的数据发生变化时。 pub force_frame: bool, @@ -67,8 +68,9 @@ pub(crate) struct Presentation { impl Presentation { /// 比较布局/绘制读取版本和名称依赖,标记需要刷新并通知快照缓存。 + /// UiBridge::prepare_frame 将同一 ChangeBatch 广播所有窗口;这里只设置失效状态,实际提取/布局由各窗随后推进。 pub fn observe_changes(&mut self, vm: &Vm, changes: &ChangeBatch) { - // 先检查粗粒度对象版本,layout 优先于 paint;每类只记录第一个失效项用于诊断。 + // 先检查粗粒度对象版本,layout 优先于 paint;合并后的两阶段读取序列只记录第一个失效项用于诊断。 // 对象已经释放时版本查询失败,也视作失效,而非继续使用旧缓存。 if let Some((phase, object, version)) = self .layout_reads @@ -93,7 +95,7 @@ impl Presentation { vm.change_version(*object).ok() ); } - // 再核对名称级依赖,避免仅凭对象版本漏掉名称解析路径上的变化。 + // 再核对精确依赖,既包括对象属性名,也包括命名空间查找和字典种类,保留 VM 记录的原粒度。 // 两个检查独立执行,因此同次观察可能分别增加计数,后者诊断可覆盖前者。 if let Some((phase, dependency)) = self .layout_names @@ -125,6 +127,7 @@ impl Presentation { } /// 按尺寸、内容或绘制失效原因清理对应缓存,避免把所有变化都当成相同重建。 + /// calls::Invalidate 已校验 reason,并按最终共享 Data 收集 affected 中的全部 Block 别名;这里不再自行扫描其他窗口。 pub fn invalidate( &mut self, cx: &mut NativeContext<'_>, @@ -206,6 +209,7 @@ pub(crate) fn split_reads( // 其他精确依赖保持原枚举与顺序,不能降级为对象版本而丢掉名字解析语义。 let mut names = Vec::new(); // 整对象依赖按身份收集到有序表,重复项以最后一次版本为准;其余精确依赖保持原记录。 + // 调用方先排除各窗口 desktop 记账读取;本函数不负责过滤宿主身份,也不替调用方取得新的版本。 for dependency in reads { // 按 ReadDependency 种类拆分;不会 retain 借用身份或执行源函数。 match dependency { diff --git a/src/model/window.rs b/src/model/window.rs index d9a4952..1751051 100644 --- a/src/model/window.rs +++ b/src/model/window.rs @@ -283,6 +283,8 @@ impl NativeCallable for Method { } } /// 把合法窗口操作追加到所属窗口的待发布命令,不能直接在 VM 线程操作 OS。 +/// Method::invoke 先检查尺寸/标题/只读规则;工具激活和 close 也直接调用本入口,因此 closed 与动作参数并不在这里重验。 +/// 返回成功只表示 outbox 已排队;worker 成功发布并封装 session 后,shell::app 才可能执行动作。 pub fn enqueue( cx: &mut NativeContext<'_>, owner: ObjectRef, @@ -314,12 +316,14 @@ pub fn enqueue( // 必须先成功经过 VM 写屏障,才修改不可回滚的原生 outbox;只读调用不能先留下待发命令再报错。 cx.replace_payload(owner, data)?; // 同窗口同动作只保留最后请求,其他类别保持先后;此处只入队,GUI 是否执行取决于后续成功发布。 + // 例如 Resize(seq1)、Focus(seq2)、Resize(seq3) 会留下 Focus(seq2)、Resize(seq3),不能保留首次 Resize 的旧序号。 queue.retain(|old| !old.same_kind(&command)); queue.push(command); Ok(()) } /// 将页面登记到其窗口,维护托管所有权与页面顺序。 +/// UiBridge::show_in 在调用前处理跨窗撤登记;本入口只保证该窗口内不重复,不负责查找或迁移其他窗口的同一 Page。 pub fn register_page( cx: &mut NativeContext<'_>, window: ObjectRef, @@ -443,6 +447,7 @@ pub fn pages(store: &ObjectStore, window: ObjectRef) -> Result<&[ObjectRef], VmE Ok(&store.payload::(window, "Window")?.pages) } /// 取走当前窗口累积的命令,后续由成功发布结果携带到 GUI。 +/// 正常发布路径会封装返回值;故障清理路径也调用本函数但直接丢弃结果,所以 drain 本身不能视为发布成功。 pub fn take_commands(vm: &Vm, window: ObjectRef) -> Result, VmError> { // 读取 payload 只取得共享 transport outbox;drain 不应制造业务依赖写入。 let data = vm.payload::(window, "Window")?; @@ -546,7 +551,8 @@ pub fn install( /// Create a managed native-window resource. The GUI creates the OS resource only /// after the owning candidate/input publishes its immutable projection. -/// 建立托管窗口、desktop 与页面容器;原生窗口通过命令发布后出现。 +/// 建立托管窗口、desktop 与页面容器;桥接强制生成该窗口的首帧,GUI 根据成功发布的窗口投影创建 OS 资源。 +/// Action 没有 Create 变体;这里返回的三元组由 ui_bridge::create_window 用于建立独立 Presentation。 pub fn create( cx: &mut NativeContext<'_>, master: ObjectRef, @@ -609,6 +615,7 @@ pub fn close(cx: &mut NativeContext<'_>, window: ObjectRef) -> Result<(), VmErro return Ok(()); } // 真实关闭边界先取消窗口与所有页面 owner 的任务,再撤销页面登记,防止晚到结果继续更新已关闭资源。 + // cancel_owner 只取消传入 owner 的作用域;具体 Mount 的任务随后在桥接刷新卸载出现时清理,不在此遍历 Mount 表。 crate::tasks::cancel_owner(cx, window)?; // 遍历旧页顺序副本,unregister_page 可以安全更新真实集合;每页 owner 任务先取消。 for page in data.pages.clone() { @@ -628,6 +635,7 @@ pub fn close(cx: &mut NativeContext<'_>, window: ObjectRef) -> Result<(), VmErro /// Host teardown for a stopped VM: no binding, dispatch or source execution. /// 撤销已失效窗口的托管资源关系,不重新执行源关闭请求。 +/// UiBridge::shutdown/retire_window 先处理任务或 Mount,再调用这里断 Page 拥有边;不等同于源 close 的排队关闭流程。 pub fn retire(vm: &mut Vm, window: ObjectRef) -> Result<(), VmError> { // 已停止域的宿主路径只解除托管页面拥有边并标记 closed,任务/OS 清理由外层退役流程负责。 let mut data = vm.payload::(window, "Window")?.clone();