From f0a55e0f7aca1176744e42ee30f8da46f1f6e023 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 12 Nov 2026 18:17:20 +0800 Subject: [PATCH] docs: explain object lists, presentation state and capability installation --- src/model/mod.rs | 3 +++ src/model/object_list.rs | 43 +++++++++++++++++++++++++++++++++ src/model/presentation.rs | 50 +++++++++++++++++++++++++++++++++++++++ src/model/protocols.rs | 14 +++++++++++ 4 files changed, 110 insertions(+) diff --git a/src/model/mod.rs b/src/model/mod.rs index fe72df8..82e1253 100644 --- a/src/model/mod.rs +++ b/src/model/mod.rs @@ -1,4 +1,7 @@ //! 模型层模块入口。包含托管业务对象、每次展示上下文、依赖缓存,以及交给窗口线程的发布值。 +//! main.rs 通过 crate 根重导出这些模块,旧的 crate::block 等调用路径仍落在本目录。 +//! 依赖方向:bridge/runtime 操作这些托管模型;窗口壳只消费发布值,不能直接修改 VM 中的对象图。 +//! 新读者可先看 block(业务身份)→ presentation/mount(每窗口出现)→ snapshot/document(发布数据)。 //! // 目录确定模块归属;main 中的 crate 根别名保持内部调用路径稳定。 /// 维护托管属性绑定及其读依赖;计算结果写入目标,绑定令牌不应让隐藏目标意外常驻。 diff --git a/src/model/object_list.rs b/src/model/object_list.rs index c012848..251700c 100644 --- a/src/model/object_list.rs +++ b/src/model/object_list.rs @@ -1,6 +1,10 @@ //! 给源协议返回的对象列表提供受控封装。列表内容通过托管引用被追踪,读方法只暴露检查后的条目。 //! 用于子节点组成、布局结果和几何输入等需要保留对象身份的场景;不是窗口线程共享的可变容器。 //! +//! 调用路径:桥接 bootstrap 注册 Constructor;Mount/视觉协议/绘图入口调用 collection 生成返回列表。 +//! source-layout/graphics/三维等消费者用 items 借用成员;源代码通过 at/append/remove/extend/added 操作。 +//! 列表只允许对象成员;子类普通字段另按名义类型检查,不能把标量字段值混进成员前缀。 +//! //! Managed indexed host results; values and the at method are traced edges. use endor_core::{ ContextNativeFunction, NativeCallable, NativeContext, NativeResult, ObjectPayload, ObjectRef, @@ -28,6 +32,7 @@ impl ObjectPayload for ObjectList { } /// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。 fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) { + // Aster 引用追踪逐条遍历成员拥有边;变量名 mount 沿用最初用途,但列表也可持有其他对象。 for mount in &self.0 { visit(*mount); } @@ -53,6 +58,7 @@ impl NativeCallable for At { /// 要求索引可精确转为非负平台整数,检查列表范围后返回对应托管成员,不复制成员对象。 fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result { + // VM 调用已绑定 at 时仍检查实参数形状,不能依赖调用方一定执行签名预检查。 let [Value::Number(index)] = args else { return Err(VmError::InvalidArgument("object list at expects an index")); }; @@ -61,35 +67,50 @@ impl NativeCallable for At { .as_i64() .and_then(|v| usize::try_from(v).ok()) .ok_or(VmError::InvalidArgument("invalid list index"))?; + // 根据已验证平台索引借用真实成员句柄;越界返回错误,不像 first 空列表那样返回 Nil。 let mount = *cx .store() .payload::(self.0, "Object list")? .0 .get(index) .ok_or(VmError::InvalidArgument("list index out of range"))?; + // Return 交回原托管身份,由 VM 的 native 返回协议处理结果拥有关系,不复制成员对象。 Ok(NativeResult::Return(Value::Object(mount))) } } #[derive(Debug)] +// append/remove/extend/added 共用的绑定适配器,操作差异由三个标志决定。 struct Edit { + // 当前列表接收者,方法 captures 强持有它,列表属性再指回方法形成可追踪托管环。 owner: ObjectRef, + // 新列表/函数的名义类型从该桌面解析,不误接到其他 VM 的类型注册表。 desktop: ObjectRef, + // true 时把唯一实参解释为删除索引;否则是追加成员(extend 优先)。 remove: bool, + // added 返回新列表而不改原接收者;原地操作则更新 payload/count/first。 persistent: bool, + // true 时唯一实参须为另一 ObjectList,将其成员按顺序追加。 extend: bool, } impl NativeCallable for Edit { + // 绑定接收者已经捕获,四种编辑操作都只接收一个显式参数。 fn arity(&self) -> Option { Some(endor_core::CallArity::exact(1)) } + // 由 VM 调用绑定编辑方法;先在 Vec 副本中验证/编辑,成功后才更新原列表或分配返回列表。 fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result { + // 复制借用成员句柄以结束原列表借用;改副本本身不会修改 VM 拥有边。 let mut members = items(cx.store(), self.owner)?.to_vec(); + // extend 接收对象列表,不把整个列表作为一个成员追加;先检查合并后的总预算。 if self.extend { + // 要求实参为对象,再由 items 验证确为宿主 ObjectList payload。 let [Value::Object(other)] = args else { return Err(VmError::InvalidArgument("extend expects ObjectList")); }; + // 借用另一列表当前成员;owner==other 时复制副本已建好,仍可安全按原序列扩展。 let incoming = items(cx.store(), *other)?; + // 合并后不能超过 10000,即使每个输入列表单独都合法也须重新检查。 if members.len() + incoming.len() > 10_000 { return Err(VmError::InvalidArgument( "object list exceeds 10000 members", @@ -97,9 +118,12 @@ impl NativeCallable for Edit { } members.extend_from_slice(incoming); } else if self.remove { + // 删除路径只修改指定索引,不按业务身份去重或删除所有相同成员。 + // 索引类型必须为 Number,后面再拒绝小数、负数和越界值。 let [Value::Number(index)] = args else { return Err(VmError::InvalidArgument("remove expects index")); }; + // 先精确转 i64/usize,再比较现有长度;无效索引不改变原 payload。 let index = index .as_i64() .and_then(|v| usize::try_from(v).ok()) @@ -107,9 +131,11 @@ impl NativeCallable for Edit { .ok_or(VmError::InvalidArgument("list index out of range"))?; members.remove(index); } else { + // 单项追加只接受对象句柄,不能装入 Nil、字符串或数字作为宿主成员。 let [Value::Object(item)] = args else { return Err(VmError::InvalidArgument("append expects object")); }; + // 追加前已有 10000 项时拒绝,不能先写原列表再报预算错误。 if members.len() >= 10_000 { return Err(VmError::InvalidArgument( "object list exceeds 10000 members", @@ -117,6 +143,7 @@ impl NativeCallable for Edit { } members.push(*item); } + // added 的持久式结果使用默认 ObjectList 类型,原列表(含其子类字段)保持不变。 if self.persistent { return Ok(NativeResult::Return(Value::Object(collection( cx, @@ -124,12 +151,15 @@ impl NativeCallable for Edit { self.desktop, )?))); } + // 原地路径重新计算元信息,payload 替换与 count/first 属性写入都经过 VM 写屏障。 let count = members.len(); + // 空列表 first=Nil;非空保存第一个原成员身份,不构造副本。 let first = members .first() .copied() .map(Value::Object) .unwrap_or(Value::Nil); + // 替换 payload 让 VM 更新成员引用追踪并产生 Contents 变化,依赖消费者可观察编辑。 cx.replace_payload(self.owner, ObjectList(members))?; cx.set_attr(self.owner, "count", Value::Number((count as i64).into()))?; cx.set_attr(self.owner, "first", first)?; @@ -143,6 +173,7 @@ pub fn collection( mounts: Vec, desktop: ObjectRef, ) -> Result { + // 宿主返回的集合不带源子类字段,统一使用桌面的默认 ObjectList 名义类型。 build(cx, mounts, desktop, None) } @@ -154,6 +185,7 @@ fn build( desktop: ObjectRef, definition: Option, ) -> Result { + // 构造入口也检查预算,不能只在编辑入口检查而让宿主一次生成超大列表。 if mounts.len() > 10_000 { return Err(VmError::InvalidArgument( "object list exceeds 10000 members", @@ -165,8 +197,11 @@ fn build( .copied() .map(Value::Object) .unwrap_or(Value::Nil); + // 在成员 Vec 移入 payload 之前保存数量,供普通 count 属性使用。 let count = mounts.len(); + // ObjectList payload 声明全部成员强拥有边,VM 分配负责登记引用。 let set = cx.allocate(ObjectList(mounts))?; + // 源子类构造保留请求的名义类型;普通 collection 返回值才用默认类型。 if let Some(definition) = definition { cx.attach_type(set, definition)?; } else { @@ -178,12 +213,14 @@ fn build( let at = cx.allocate(ContextNativeFunction::new("at", At(set), vec![set]))?; crate::ui_bridge::attach_desktop_type(cx, at, "Function", desktop)?; cx.set_attr(set, "at", Value::Object(at))?; + // 逐个安装四种绑定操作,标志表是方法语义的唯一分派来源。 for (name, remove, persistent, extend) in [ ("append", false, false, false), ("remove", true, false, false), ("added", false, true, false), ("extend", false, false, true), ] { + // 显式 captures=[set,desktop] 保活接收者与类型环境,循环可由 Aster GC 看到。 let method = cx.allocate(ContextNativeFunction::new( name, Edit { @@ -209,7 +246,9 @@ pub fn items(store: &endor_core::ObjectStore, list: ObjectRef) -> Result<&[Objec #[derive(Debug)] /// ObjectList 原生类型的可调用构造器,负责检查传入子对象。 pub struct Constructor { + // bootstrap 提供的可选构造契约,子类构造仍在 invoke 按字段后缀切分参数。 pub signature: Option, + // 构造列表与绑定方法的所属桌面,captures 由注册构造器的 bootstrap 负责保活。 pub desktop: ObjectRef, } impl NativeCallable for Constructor { @@ -224,6 +263,7 @@ impl NativeCallable for Constructor { /// 按请求类型字段数切分成员/字段,禁止覆盖列表协议保留属性,验证后分配列表并初始化源字段。 fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result { + // VM 类型调用传入请求 Type 为首参,允许构造 ObjectList 名义子类。 let [Value::Object(definition), values @ ..] = args else { return Err(VmError::InvalidArgument("ObjectList type argument")); }; @@ -255,6 +295,7 @@ impl NativeCallable for Constructor { let members = values[..count] .iter() .map(|value| { + // 只检查成员前缀的每项是对象;源子类标量字段已经从后缀单独校验。 if let Value::Object(object) = value { Ok(*object) } else { @@ -264,7 +305,9 @@ impl NativeCallable for Constructor { } }) .collect::, _>>()?; + // 所有字段/成员验证完成后才分配,避免坏字段参数先产生原生列表副作用。 let list = build(cx, members, self.desktop, Some(*definition))?; + // 按声明顺序初始化子类字段,保留契约检查后的原 Value 身份。 for (field, value) in fields.iter().zip(&values[count..]) { cx.set_attr(list, &field.name, value.clone())?; } diff --git a/src/model/presentation.rs b/src/model/presentation.rs index 91dd9de..3b8cd56 100644 --- a/src/model/presentation.rs +++ b/src/model/presentation.rs @@ -1,6 +1,10 @@ //! 一个原生窗口对应一份 Presentation:独立视口、Mount、测量缓存、焦点与依赖记录。 //! 多个窗口仍使用同一个 VM 和共享业务对象。读取版本失效时只标记相关展示需要刷新,不能因此复制一份业务状态。 //! +//! 调用路径:bootstrap/新窗口入口创建 Presentation;UiBridge 收集 VM changes 后对每窗口调用 observe_changes。 +//! Block.invalidate 的桥接路径调用 invalidate,源布局/绘制完成后用 split_reads 保存本窗口实际读取。 +//! 本结构是 VM 线程内宿主状态,不能把其借用 ObjectRef 或弱表直接交给窗口线程操作。 +//! //! Per-window rendering state. Business objects and code remain in one VM. //! Registries and caches borrow checked identities; the managed desktop owns //! presentation roots through its pending/mount dictionaries. @@ -13,32 +17,51 @@ use std::sync::Arc; pub(crate) struct Presentation { // 所属托管桌面身份;此结构借用身份,真正的展示根由托管桌面字典维持。 pub desktop: ObjectRef, + // 窗口正在退役的标记,阻止常规新展示请求在关闭阶段复活旧上下文。 pub closing: bool, + // 当前窗口标签字典的借用身份,真正拥有边由托管 desktop 保持。 pub tabs: ObjectRef, + // 当前已生效 Page 的借用身份;页面生命期仍由托管展示根维持。 pub active: Option, // 双层 Option 区分三态:None 无请求,Some(None) 请求清空,Some(Some(page)) 请求切页。 pub pending: Option>, + // 最近原生根快照,比较 Arc/内容以决定是否需要新的布局,不强持有 VM 业务对象。 pub last_snapshot: Option>, // 弱身份到原生稳定标签 ID 的映射;不能因为标签历史而保活已经关闭的页面。 pub tab_ids: Vec<(WeakObjectRef, u64)>, + // 分配新原生标签 ID 的单调计数,与可被回收的 Page 弱身份分开。 pub next_tab: u64, + // 最近发布的标签值列表,用于检测标题/活动项/顺序变化。 pub last_tabs: Vec, + // 当前页面兼容表面相机和模式,随本窗口展示更新。 pub surface: crate::page::Surface, + // 托管业务图到原生视觉树的缓存及反向依赖,不能替代源测量缓存。 pub render_cache: crate::snapshot::RenderCache, + // 本窗口几何求解、出现身份与布局缓存,多个窗口共享业务树但不共享此状态。 pub layout: crate::layout::LayoutRuntime, + // 本窗口活动 Mount 的弱索引与发布顺序,托管字典负责强拥有。 pub mounts: crate::mount::MountTable, + // 最后完整发布的布局版本,未提交的分片结果不能直接覆盖此边界。 pub published_version: u64, // 即使根快照身份未变也要求重新发布一帧,例如源绘制读取的数据发生变化时。 pub force_frame: bool, // 精确名称/字典种类依赖,与下面按整个对象版本记录的 reads 分开检查。 pub paint_names: Vec, + // 源布局精确名字/字典类别读取,与 layout_reads 的整对象版本分别检查。 pub layout_names: Vec, + // 源 paint 的对象内容版本观察,仅借用身份,不 retain 对象。 pub paint_reads: std::collections::BTreeMap, + // 观察到读取失效的累计次数,饱和累加用于诊断,不作为实际刷新次数。 pub dependency_invalidations: usize, + // 最近失效的阶段/对象或名字诊断;同次两类检查都命中时后者覆盖前者。 pub last_invalid_dependency: String, + // 源 measure/arrange 实际读取的整对象版本,更新后按该版本观察决定刷新。 pub layout_reads: std::collections::BTreeMap, + // 源测量的参数/依赖缓存,paint-only 显式失效不清除此缓存。 pub measure_cache: crate::source_layout::Cache, + // 最近快照提取实际重建节点统计,供开发工具解释刷新成本。 pub snapshot_visited: usize, + // 最近快照提取直接复用条目统计,与 visited 分开展示。 pub snapshot_reused: usize, } @@ -60,6 +83,7 @@ impl Presentation { { self.force_frame = true; self.dependency_invalidations = self.dependency_invalidations.saturating_add(1); + // 失效诊断尽量附 payload 种类;对象已释放时用 released,而不是解引用过期句柄。 let kind = vm .object(*object) .map(|value| value.payload().kind_name()) @@ -84,8 +108,11 @@ impl Presentation { { self.force_frame = true; self.dependency_invalidations = self.dependency_invalidations.saturating_add(1); + // Name 依赖显示具体名字,其他精确记录显示字典类别变化,不假装都有属性名。 let name = match dependency { + // 名字解析路径中的具体名称用于调试哪些全局/属性访问使布局或绘制失效。 endor_core::ReadDependency::Name { name, .. } => name.as_str(), + // 非 Name 分支表示字典种类观察,仍需保留其失效事实。 _ => "", }; self.last_invalid_dependency = format!("{phase} name {}:{name}", dependency.object()); @@ -107,6 +134,7 @@ impl Presentation { // 仅绘制失效不影响测量;其余原因清除测量结果并按 Block ID 使布局缓存失效。 if reason != "paint" { self.measure_cache.invalidate(affected); + // 源测量缓存按业务身份失效,布局缓存则使用其身份文本;同一窗口所有受影响对象都处理。 for block in affected { self.layout.invalidate(&block.to_string()); } @@ -117,7 +145,9 @@ impl Presentation { .invalidate_objects(affected.iter().copied()); } // 仅当受影响 Block 在该窗口有活动出现时强制刷新,避免无关窗口重复发帧。 + // 逐个弱升级本窗口活动出现,只在此窗口确有受影响 Block 时 force_frame。 for weak in self.mounts.active.values() { + // 已消失的 Mount 不触发刷新;升级成功后检查它的业务 Block 是否属于 affected。 if let Some(mount) = cx.upgrade(*weak)? && affected.contains( &cx.store() @@ -134,6 +164,7 @@ impl Presentation { /// 用桌面与标签注册表身份初始化窗口状态,布局和视觉缓存从空状态开始。 // 这里只初始化窗口级缓存,不创建 VM、不复制业务对象;active/pending 留空等待窗口展示请求。 pub fn new(desktop: ObjectRef, tabs: ObjectRef) -> Self { + // 这里只初始化本窗口宿主状态;不分配新的 VM 或业务对象,尚无页面、根快照和读观察。 Self { desktop, closing: false, @@ -170,14 +201,19 @@ pub(crate) fn split_reads( std::collections::BTreeMap, Vec, ) { + // 整体对象观察按身份归并到有序表,后续 observe_changes 比较该对象的当前版本。 let mut objects = std::collections::BTreeMap::new(); + // 其他精确依赖保持原枚举与顺序,不能降级为对象版本而丢掉名字解析语义。 let mut names = Vec::new(); // 整对象依赖按身份收集到有序表,重复项以最后一次版本为准;其余精确依赖保持原记录。 for dependency in reads { + // 按 ReadDependency 种类拆分;不会 retain 借用身份或执行源函数。 match dependency { + // 同对象重复观察以最后出现的版本覆盖先前版本,与本轮实际观察结束状态一致。 endor_core::ReadDependency::Object { object, version } => { objects.insert(object, version); } + // Name/字典类别等精确记录完整保留,交给 ObjectStore 的有效性检查器解释。 dependency => names.push(dependency), } } @@ -193,8 +229,11 @@ mod tests { fn independent_view_geometry_and_shared_vm_reads_do_not_add_roots() { // 测试在同一 VM 中建立两个 Presentation,验证各自布局尺寸/出现 ID 独立,读取依赖共享业务对象。 let mut vm = Vm::new().unwrap(); + // 第一窗口以独立 desktop/tabs 与独立 LayoutRuntime 初始化,但仍属于同一个 VM。 let mut left = Presentation::new(vm.new_object().unwrap(), vm.new_dict().unwrap()); + // 第二窗口使用另一套展示状态,随后给它不同有限视口,不能靠复制业务树隔离几何。 let mut right = Presentation::new(vm.new_object().unwrap(), vm.new_dict().unwrap()); + // 左窗口设 100×80,右窗口设 200×160,同一自然 500×500 根会被各自约束。 left.layout.viewport = Some(Size { width: 100.0, height: 80.0, @@ -203,6 +242,7 @@ mod tests { width: 200.0, height: 160.0, }); + // 手工不可变原生矩形快照以同一 block_id 供两窗口布局,专门隔离展示几何状态。 let root = UiNode { surface: None, flex: 0.0, @@ -228,26 +268,36 @@ mod tests { color: "#237A45".into(), }, }; + // 分别执行真实布局,验证共享快照在左右窗口产生不同分配宽度。 let left_frame = left.layout.frame(&root).unwrap(); + // 右窗口也读取同一 root,但不应沿用左侧出现身份或约束结果。 let right_frame = right.layout.frame(&root).unwrap(); assert_eq!(left_frame.mounts[0].width, 100.0); assert_eq!(right_frame.mounts[0].width, 200.0); + // 只清左窗口出现,下一帧应分配新左 ID,而右窗口不受影响。 left.layout.clear_occurrences(); + // 新左帧应更换出现 ID,验证 clear_occurrences 的实际效果。 let new_left = left.layout.frame(&root).unwrap(); + // 未清理的右窗口保留原 ID,说明身份序列/缓存没有跨 Presentation 串用。 let same_right = right.layout.frame(&root).unwrap(); assert_ne!(new_left.mounts[0].id, left_frame.mounts[0].id); assert_eq!(same_right.mounts[0].id, right_frame.mounts[0].id); + // 在 VM 中创建共享业务读取源,让两窗口记录不同阶段对同一对象的依赖。 let shared = vm.new_object().unwrap(); + // 保存写入前的版本;left.paint_reads 与 right.layout_reads 都只借用该身份。 let version = vm.change_version(shared).unwrap(); left.paint_reads.insert(shared, version); right.layout_reads.insert(shared, version); + // 实际写入使对象版本改变;两类读取观察都应设置各自 force_frame。 vm.set_attr(shared, "value", endor_core::Value::Bool(true)) .unwrap(); + // 同一 VM 变化批次送给两窗口,记录克隆不能制造业务对象副本或新的 GC 根。 let changes = vm.take_changes(); left.observe_changes(&vm, &changes); right.observe_changes(&vm, &changes); assert!(left.force_frame && right.force_frame); // 最后释放业务对象并回收:两份读取记录都不应成为托管根,弱引用应升级失败。 + // 只保留弱句柄再释放业务根,最后 collect_cycles 后应无法升级,证明 reads 不保活源对象。 let weak = vm.downgrade(shared).unwrap(); vm.release(shared).unwrap(); vm.collect_cycles(); diff --git a/src/model/protocols.rs b/src/model/protocols.rs index 9379c83..97f1873 100644 --- a/src/model/protocols.rs +++ b/src/model/protocols.rs @@ -1,6 +1,9 @@ //! 安装 Visual、EventTarget、Children 和 Presentable 等能力契约。 //! 契约描述对象能响应什么源方法;具体测量、绘制、事件执行仍在各自协议驱动器中完成。 //! +//! 调用路径:ui_bridge::bootstrap 先创建名义类型/原生方法,再调用 install,把能力同时公开到 ui 和 desktop.types。 +//! Aster 在 implement 注册、覆写和调用边界使用 TypedMethodRequirement 检查契约;安装期间不执行用户方法体。 +//! //! Host capability definitions over Aster's explicit managed trait relations. use endor_core::{ AnnotationType, CallArity, CallEffect, CallSignature, ObjectRef, TypedMethodRequirement, Value, @@ -18,6 +21,7 @@ pub fn install( let Value::Object(trait_type) = vm.get_attr(ui, "Trait")? else { return Err(VmError::InvalidArgument("missing Trait type")); }; + // 使用当前桌面的真实类型字典,能力与其 Window/Block 注解必须来自同一运行时。 let Value::Object(types) = vm.get_attr(desktop, "types")? else { return Err(VmError::InvalidArgument("missing type registry")); }; @@ -31,6 +35,7 @@ pub fn install( Some("Block"), ), ( + // 事件能力同时约束订阅、源码派发和目标默认方法,原生签名来自 Block。 "EventTarget", vec![("on", 3), ("dispatch", 2), ("onEvent", 1)], Some("Block"), @@ -48,10 +53,12 @@ pub fn install( ], Some("ContainerBlock"), ), + // Presentable 显式声明展示能力,不能仅因对象有同名 present 就隐式启用。 ("Presentable", vec![("present", 1)], None), ] { // 从当前 ui 模块查名义类型身份,不靠字符串名称把另一个运行时的类型误接进来。 let owner_definition = if let Some(owner) = owner { + // 有默认提供者时要求 ui 上的名义类型存在,避免装入缺少方法基线的能力。 let Value::Object(definition) = vm.get_attr(ui, owner)? else { return Err(VmError::InvalidArgument("missing protocol owner")); }; @@ -59,10 +66,13 @@ pub fn install( } else { None }; + // 本能力的每项方法要求在此收集,全部契约可构造后才分配 trait 对象。 let mut requirements = Vec::new(); + // 逐方法复用原生参数/返回/效果,再统一将 receiver 放宽为 Any。 for (method, parameters) in methods { // 优先复用原生方法参数/返回注解和调用效果,缺少原生签名元数据时拒绝安装。 let mut signature = if let Some(owner) = owner_definition { + // 按名义 owner 的方法表查真实函数,不从实例字段借用一个碰巧同名的 callable。 let function = vm .object_store() .lookup_method(owner, method)? @@ -74,7 +84,9 @@ pub fn install( ))? } else { // Presentable 没有默认 owner,手工声明 present(receiver, Window) -> Block,调用效果为 External。 + // Presentable 的窗口参数绑定当前桌面 Window 名义类型,不使用宽泛 Object 替代要求。 let window = crate::ui_bridge::desktop_type(vm.object_store(), "Window", desktop)?; + // 返回必须满足当前桌面 Block 契约,具体实现可返回更具体的视觉子类。 let block = crate::ui_bridge::desktop_type(vm.object_store(), "Block", desktop)?; CallSignature::exact( vec![AnnotationType::Any, AnnotationType::Nominal(window)], @@ -90,12 +102,14 @@ pub fn install( signature, }); } + // VM 创建受类型约束的 trait;后面保活、附 Trait 名义类型并公开两个查询入口。 let capability = vm.new_typed_trait(name, requirements)?; // 新能力放入宿主 roots 管理生命周期,再同时暴露于 ui 属性与 desktop 类型注册表。 roots.push(capability); vm.attach_type(capability, trait_type)?; vm.set_attr(ui, name, Value::Object(capability))?; vm.dict_set(types, Value::Text(name.into()), Value::Object(capability))?; + // 默认 owner 显式 implement;没有 owner 的 Presentable 不能自动授予全部类型。 if let Some(owner) = owner_definition { // 有默认提供者时显式登记 implements 关系;Presentable 留待具体类型声明,不自动给所有 Block 安装。 vm.implement_trait(owner, capability)?;