From 723e7f1fbdf10fcc1af1fb8b4780045a794c5f5d Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 12 Nov 2026 20:30:28 +0800 Subject: [PATCH] docs: clarify UI registration signatures and visual snapshot fields --- src/bridge/ui_bridge/bootstrap.rs | 8 +++++++- src/bridge/ui_bridge/page_input.rs | 5 ++++- src/bridge/ui_bridge/signatures.rs | 2 ++ src/bridge/ui_bridge/tree.rs | 21 +++++++++++++++++++++ 4 files changed, 34 insertions(+), 2 deletions(-) diff --git a/src/bridge/ui_bridge/bootstrap.rs b/src/bridge/ui_bridge/bootstrap.rs index 7b11576..3a494ee 100644 --- a/src/bridge/ui_bridge/bootstrap.rs +++ b/src/bridge/ui_bridge/bootstrap.rs @@ -5,6 +5,8 @@ //! 随后调用本模块的 `install`;运行时再通过 install_globals 注入源程序使用的 UI 值。 //! 本文件只建立宿主环境。源程序稍后调用构造器或实例方法时,才会进入 `calls::Function::invoke`。 //! 安装返回的 UiBridge 由运行时保存;传入的 roots 由候选运行时持有,并在失败或退役时统一释放。 +//! 安装顺序还承载 GC 关系:desktop.types 拥有类型,类型拥有工厂/方法,callable 再追踪签名和显式 captures。 +//! 两阶段补签名保留原对象身份,因此 ui 属性和 TypeConstructor 不需要重新指向另一批函数。 use super::*; /// 为一次候选程序/REPL 会话安装 Tessera 宿主环境,供运行时后续注入全局值和执行源程序。 @@ -351,7 +353,8 @@ pub fn install(vm: &mut Vm, roots: &mut Vec) -> Result { }; // 初始强边是注册表;随后追加签名引用的类型,供 ContextNativeFunction::trace 使用。 let mut captures = vec![desktop]; - // 参数和返回注解中的名义类型也是托管引用,必须纳入 captures,不能只把它们存进 Rust 签名结构。 + // ContextNativeFunction 自动追踪外壳 signature,但内部 options 不对它暴露;窄参数中的名义类型要额外加入 captures。 + // 即使 desktop.types 当前也能保活它们,仍显式枚举 options 真正使用的引用,不把内部签名藏在不可见的 Rust 拥有图中。 captures.extend(options.references()); vm.replace_payload( function, @@ -370,6 +373,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec) -> Result { // 特殊构造器保留宽变参外壳,再由对应 Constructor 按类型字段数拆实参,返回准确 Event/ObjectList 名义类型。 // 为返回值选取专用名义类型,避免宽变参外壳同时放宽了返回值检查。 let kind = if name == "event" { + // 前面已穷举通用工厂,此分支只剩 Event 和 ObjectList;这里的名字决定返回契约而不是业务实例类型。 "Event" } else { "ObjectList" @@ -383,8 +387,10 @@ pub fn install(vm: &mut Vm, roots: &mut Vec) -> Result { ), // 固定前缀与 required 数量保持一致,额外实参由 variadic 和字段验证共同约束。 parameters: if name == "event" { + // Event 的事件名在外壳阶段就要求 String;随后专用构造器再拆出其余子类字段。 vec![AnnotationType::Type.into(), AnnotationType::String.into()] } else { + // ObjectList 元素和子类字段都在开放尾参中,由构造器按 requested Type 的字段声明分界。 vec![AnnotationType::Type.into()] }, variadic: Some(AnnotationType::Any.into()), diff --git a/src/bridge/ui_bridge/page_input.rs b/src/bridge/ui_bridge/page_input.rs index a8c9e7d..fbca725 100644 --- a/src/bridge/ui_bridge/page_input.rs +++ b/src/bridge/ui_bridge/page_input.rs @@ -3,7 +3,8 @@ //! //! UiBridge::dispatch 按输入 kind 分流到下面三个方法:整页、局部二维视口和局部三维场景分别处理。 //! 它们只在所属 VM worker 上修改托管相机属性或调用 controller.update,不直接改 GUI 已发布帧。 -//! 姿态变化随后由正常依赖/快照刷新观察;任何新帧仍需走 layout/paint/commit 的完整发布路径。 +//! 姿态变化随后由正常依赖/快照刷新观察;任何新帧仍需完成布局、桥接挂载提交、绘制和稳定发布。 +//! 这三个入口由 dispatch 在信封校验与选窗检查之后调用;内部仍分别验证发布版本和该手势所需的目标/坐标字段。 use super::*; impl UiBridge { @@ -61,6 +62,7 @@ impl UiBridge { .ok_or_else(|| anyhow::anyhow!("3D controller disabled"))?; // 同一视觉对象的边框/内边距由快照解析,手势锚点与可用尺寸都应扣除这部分。 let node = block::snapshot(vm.object_store(), occurrence.block)?; + // 此处的一次性快照只用于读取盒模型,不替换 Presentation 的视觉缓存,也不提交新的布局或画面。 // inset 将外框换算成视口内容盒,避免控制器把边框尺寸算成场景宽高。 let inset = crate::layout::insets(&node); // 几何来自具体 Mount,两个窗口中共享同一场景仍可能有不同视图投影。 @@ -198,6 +200,7 @@ impl UiBridge { .delta .ok_or_else(|| anyhow::anyhow!("viewport input has no delta"))?; // 基于旧快照计算三个新值,完成验证后才依次回写托管属性。 + // x/y 是世界偏移而非屏幕位移;几何先撤外层投影,除以本相机 zoom 后才属于可累加到 x/y 的单位。 let (mut x, mut y, mut zoom) = (old.x, old.y, old.zoom); if input.kind == "viewport-zoom" { // 缩放必须有锚点,不能让缺失指针导致隐式绕视口原点缩放。 diff --git a/src/bridge/ui_bridge/signatures.rs b/src/bridge/ui_bridge/signatures.rs index 6a95e08..162d48b 100644 --- a/src/bridge/ui_bridge/signatures.rs +++ b/src/bridge/ui_bridge/signatures.rs @@ -5,6 +5,8 @@ //! ui_bridge::bind 也会为状态对象的绑定函数调用 operation_signature。 //! VM 随后在调用边界读取这些签名,验证数量、类型及调用效果;业务实现位于 calls/scene3d 等模块。 //! 参数注解并不决定是否必填:Operation::arity 给出实参数量,注解表则检查实际出现的每一个参数。 +//! 例如 Text 的注解列出 text/size/color 三项,但 arity 为 1..3,所以省略后两项合法,显式 nil 仍不满足 Number/String。 +//! ReadOnly 构造可初始化本次新分配对象;Delegated 只允许进入委托入口,后续被调用函数仍要接受各自的效果检查。 use super::*; /// bootstrap 安装实例方法时调用,构造包含 receiver 的 VM 方法契约。 diff --git a/src/bridge/ui_bridge/tree.rs b/src/bridge/ui_bridge/tree.rs index 3ece657..bca0141 100644 --- a/src/bridge/ui_bridge/tree.rs +++ b/src/bridge/ui_bridge/tree.rs @@ -27,6 +27,7 @@ pub struct UiNode { pub sizing: crate::box_model::Sizing, // 单边可选覆盖值;None 表示沿用 kind 的统一 padding,不代表边距为零。 pub padding_edges: [Option; 4], + // 四边边框厚度;layout::insets 将其与有效 padding 相加,内容盒、相机锚点及绘制共用该内缩量。 pub border: crate::layout::Insets, // 留原始颜色字符串供显示列表解码;颜色变更也必须使 shallow_eq 为 false。 pub border_color: String, @@ -86,6 +87,7 @@ impl UiNode { } /// model::snapshot 缓存重建节点后调用,判断可否保留旧 Arc;返回 true 不会修改任何节点或 VM 对象。 + /// 缓存调用方仍会用本轮读取重建依赖/父边;这里只证明视觉值可复用,不能证明依赖来源没有变化。 pub fn shallow_eq(&self, other: &Self) -> bool { // 先比较所有公共视觉/协议配置,任一变化都不能复用旧节点 Arc,即使子内容完全相同。 if self.surface != other.surface @@ -286,13 +288,18 @@ pub enum UiKind { }, // 旧 Page Canvas 模式的兼容投影,位置数组与孩子顺序一致,页面级 Surface 保存其相机。 Canvas { + // 页面根中每个孩子的业务位置,保持与 children 同长度同顺序;Surface 再统一变换到页面视图。 positions: Vec<[f32; 2]>, + // 业务组成提取的不可变子树;数组顺序决定遍历/绘制顺序,不按 x/y 自动排序。 children: Vec>, }, // 按钮是有子内容的容器,不把标签文本硬编码进 UiKind;交互资格另由 UiNode 标志表达。 Button { + // 内容与边框之间的统一内边距;单边覆盖仍优先使用 UiNode.padding_edges。 padding: f32, + // 多个内容孩子的主轴间距,不含父节点外 margin 或按钮边框厚度。 gap: f32, + // 标签只是其中一个普通 Text 子树,按钮没有独立的硬编码文字字段。 children: Vec>, }, // 文字叶节点保留源字号等级与颜色文本;排版及最终设备比例由后续布局/显示列表转换处理。 @@ -306,20 +313,30 @@ pub enum UiKind { }, // 纯绘制叶节点;几何尺寸与圆角供布局/显示列表共用,不含托管对象句柄。 Rect { + // 自然宽高用于测量;父安排与盒尺寸策略仍可给实际出现分配其他尺寸。 width: f32, height: f32, + // 圆角半径影响显示列表的矩形命令,不给孩子增加布局空间。 radius: f32, + // 已校验格式的填充色字符串,与 UiNode.border_color 分别控制填充和边框。 color: String, }, // Column 沿纵轴累加孩子位置,Row 沿横轴;二者都保存统一内边距和孩子间距。 Column { + // 容器默认内边距,最终内容内缩还包括单边覆盖与边框厚度。 padding: f32, + // 相邻孩子间沿纵向增加的空隙,首尾不额外增加一份 gap。 gap: f32, + // 当前组成顺序;节点可共享 Arc,但每次出现的 Mount 和几何另行建立。 children: Vec>, }, + // 横排容器与 Column 使用相同盒模型,但 gap 和弹性分配沿水平主轴计算。 Row { + // 统一内边距,由 layout::insets 与单边覆盖/边框合成有效值。 padding: f32, + // 横向相邻孩子间距,不是孩子自身宽度或两边 margin 的替代值。 gap: f32, + // 源组成的逻辑顺序,不因视觉位置变化而重排 slot。 children: Vec>, }, // 无视觉内容的间隔叶节点,提供布局占用尺寸。 @@ -328,10 +345,14 @@ pub enum UiKind { Scroll { // axis 指定允许消费的滚动方向;实际可消费距离还取决于具体 Mount 的内容/视口范围。 axis: crate::scroll::Axis, + // 有限视口的自然尺寸;内容可能大于视口,溢出范围和偏移由布局与 Mount 派生。 width: f32, height: f32, + // 内容布局的统一内边距,与视口外 margin 分开。 padding: f32, + // 内容子项的纵向间隔,保持与原生滚动容器布局规则一致。 gap: f32, + // 当前内容树;滚动仅改变出现投影,不把移动后的坐标写入共享 UiNode。 children: Vec>, }, }