Zayden-Jung/endorphin-tessera-gui
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: explain document publication and visual snapshot invalidation

Browse Source
This commit is contained in:
Codex Bot
2026-11-12 18:13:48 +08:00
parent dbf0bb5800
commit 38e8bbc1e6
2 changed files with 222 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/model/document.rs
+128
View File
@@ -1,6 +1,9 @@
//! 运行时与窗口线程之间的发布数据契约。NamespaceState 管理提交序号、版本和当前完整文档。
//! RenderDocument/Frame 包含绘制命令、Mount 几何、页面标签和相机投影。发布前统一检查数量、坐标、颜色及索引一致性。
//! 屏幕命中、逻辑坐标和世界 UI 的射线映射必须与绘制采用同一变换；这里的 ID 是数据身份，不是窗口线程可操作的托管引用。
//! 调用路径：API worker 用 NamespaceState 提交/清空候选；桥接发布前调用 validate。
//! 窗口壳用 Frame 命中结果构造输入，worker 再复核；软件渲染入口用 display_list 转为设备坐标命令。
//! 所有发布值拥有绘制所需原生数据，不能要求窗口线程通过 ID 解引用 VM。
//!
use std::collections::HashSet;
use std::sync::Arc;
@@ -14,21 +17,26 @@ use crate::{
ui_bridge::UiNode,
};
// HTTP/Console 未指定名字时的默认命名空间，初始化状态和源入口应使用同一值。
pub const DEFAULT_NAMESPACE: &str = "app.main";
#[derive(Clone, Debug)]
/// HTTP/GUI 共享的最近完整发布状态；submission 决定结果归属，revision 表示实际发布次数。
pub struct NamespaceState {
// 命名空间显示/API 身份，区别于每次输入的 submission 与 VM session。
pub name: String,
// 成功替换或 clear 才推进的发布版本，用于调用方识别可见文档更新。
pub revision: u64,
// 较新完整 PUT/DELETE 会改变提交身份；旧输入即使晚完成也不得覆盖新结果。
pub submission: u64,
// 最近成功的完整文档；编译/执行失败或过期候选不替换它。
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,
// 待窗口壳消费的世代化原生命令，按动作合并并保留全局请求顺序。
pub window_commands: Vec<crate::window::Envelope>,
}
@@ -66,12 +74,14 @@ impl NamespaceState {
return;
}
// 本方法接纳传入 session 作为当前世代，调用方负责只在成功发布边界调用；同资源同动作保留最新请求。
// 同一资源的同类动作保留最新请求，Focus/Resize 等不同动作仍分别排队。
for command in commands {
self.window_commands
.retain(|old| !old.command.same_kind(&command));
self.window_commands
.push(crate::window::Envelope { session, command });
}
// 合并后按 VM 原始 sequence 恢复执行顺序，避免 retain/push 使不同资源动作乱序。
self.window_commands
.sort_by_key(|command| command.command.sequence);
}
@@ -89,6 +99,7 @@ impl NamespaceState {
if submission != self.submission {
return Ok(None);
}
// 先计算可用新版本，溢出时整个提交失败且旧文档仍在。
let revision = self
.revision
.checked_add(1)
@@ -100,7 +111,9 @@ impl NamespaceState {
/// 推进提交身份和发布版本，替换为空文档并清除运行时命令，使旧提交不能覆盖清空结果。
pub fn clear(&mut self) -> Result<u64> {
// clear 也创建新提交身份，让先前在途的合法候选失去发布资格。
let submission = self.next_submission()?;
// 发布版本与提交令牌都先检查溢出，状态更新集中在全部检查成功之后。
let revision = self
.revision
.checked_add(1)
@@ -119,15 +132,19 @@ impl NamespaceState {
/// 可以离开 VM 线程的完整展示值，包含源码投影、根帧和其他窗口的文档。
pub struct RenderDocument {
#[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
// 主文档携带的副窗口投影，最多一层，不是可任意递归的窗口树。
pub windows: std::collections::BTreeMap<u64, RenderDocument>,
#[serde(skip)]
// 仅本机增量渲染使用，不序列化；JSON 文档仍可凭 frame.commands 绘制，不需要持有 VM 句柄。
pub ui_root: Option<Arc<UiNode>>,
#[serde(default)]
// 完整输入源码或 Console 历史，Sources 使用原文与结构树范围定位。
pub source: String,
#[serde(default)]
// 可选源码投影根；空文档可无根，和视觉 ui_root 是不同的数据。
pub root: Option<CodeNode>,
#[serde(default)]
// 当前窗口完整视觉帧，副窗口文档也各有自己的 frame.window。
pub frame: Frame,
}
@@ -136,6 +153,7 @@ impl RenderDocument {
pub fn validate(&self) -> Result<()> {
// 校验页面兼容相机的缩放、pan 和有限 extent；独立视口变换随后按各表与 Mount 另行检查。
let surface = &self.frame.surface;
// 所有页面兼容相机分量先检查范围，之后窗口绘制与输入可使用同一有限变换。
if !surface.zoom.is_finite()
|| !(0.1..=4.0).contains(&surface.zoom)
|| ![surface.pan.x, surface.pan.y]
@@ -147,11 +165,14 @@ impl RenderDocument {
{
bail!("invalid page camera or extent");
}
// 主窗口之外最多十五个副窗口，与完整桌面窗口预算一致。
if self.windows.len() > 15 {
bail!("too many window projections");
}
// 副窗口只允许一层投影，键须等于其 frame.window，不能重复嵌入主窗口或再带嵌套 windows。
// 按每个副窗口独立校验帧，不允许借嵌套 map 绕开窗口计数。
for (id, document) in &self.windows {
// 副窗口不能冒用主窗口 ID，键/帧身份须相等，且不得再次嵌套 windows。
if *id == crate::window::MAIN_WINDOW
|| *id != document.frame.window
|| !document.windows.is_empty()
@@ -160,13 +181,16 @@ impl RenderDocument {
}
document.validate()?;
}
// 源码预算按 UTF-8 字节计，不以字符数绕过 1 MiB 输入限制。
if self.source.len() > 1_048_576 {
bail!("source exceeds the 1 MiB limit");
}
// 绘制命令预算独立于 Mount 数量，防止单个源 paint 产生无界命令。
if self.frame.commands.len() > 10_000 {
bail!("frame exceeds the 10,000 command limit");
}
// 零窗口 ID 无效，不作为默认主窗口的别名接纳。
if self.frame.window == 0 {
bail!("invalid window identity");
}
@@ -177,27 +201,35 @@ impl RenderDocument {
{
bail!("invalid command clip table");
}
// 只校验存在的裁剪矩形；None 表示该命令不加这层裁剪。
for clip in self.frame.command_clips.iter().flatten() {
validate_rect(clip[0], clip[1], clip[2], clip[3], 0.0)?;
}
// 视图表与裁剪表同样是平行索引，非空半表会使绘制参数错配。
if !self.frame.command_views.is_empty()
&& self.frame.command_views.len() != self.frame.commands.len()
{
bail!("invalid command view table");
}
// 各二维变换先检查缩放/平移合法性，后面的绘制转换可据此使用。
for view in self.frame.command_views.iter().flatten() {
// 拒绝不可逆或超界视图变换，避免绘制与命中给出互相矛盾的坐标。
if !view.valid() {
bail!("invalid command view transform");
}
}
// 逐条分派到命令自己的几何/文本/材质检查，不能只检查命令总数。
for command in &self.frame.commands {
command.validate()?;
}
// 出现位置也设独立上限，防止少量命令背后展开过多可命中节点。
if self.frame.mounts.len() > 10_000 {
bail!("frame exceeds the 10000 mount limit");
}
// 标签 ID 必须非零且唯一，最多一个活动页；标题按 UTF-8 字节限长，标签数受 MAX_PAGES 限制。
// 记录全部标签身份，集合同时用于检测重复；active 数量另外限制为至多一个。
let mut tab_ids = HashSet::new();
// 同时检查标签数量、活动项数和每项身份/标题预算，不能只验证某个当前活动页。
if self.frame.tabs.len() > crate::ui_bridge::MAX_PAGES
|| self.frame.tabs.iter().filter(|tab| tab.active).count() > 1
|| self
@@ -209,18 +241,24 @@ impl RenderDocument {
bail!("invalid tab projection");
}
// 先收集全部 Mount ID 并校验几何，再第二遍核对关系下标，允许链接指向帧中较后位置。
// 先建整帧身份集合，第二轮才能允许关系链接指向后面才出现的节点。
let mut mount_ids = HashSet::new();
// 首轮逐项检查变换、身份与几何，收集关系检查所需的完整 ID 集合。
for mount in &self.frame.mounts {
// Mount 的二维变换与绘制表独立检查，不能因为命令合法就信任输入几何。
if mount.view.is_some_and(|view| !view.valid()) {
bail!("invalid Mount view transform");
}
// 业务 block_id 可因共享重复，但每个出现的 Mount ID 必须非零且帧内唯一。
if mount.id == 0 || mount.block_id.is_empty() || !mount_ids.insert(mount.id) {
bail!("invalid or duplicate mount identity");
}
validate_rect(mount.x, mount.y, mount.width, mount.height, 0.0)?;
// 祖先 clip 与节点原几何分别校验，裁剪不能包含 NaN 或负尺寸。
if let Some(clip) = mount.clip {
validate_rect(clip[0], clip[1], clip[2], clip[3], 0.0)?;
}
// 相机手势额外内容区裁剪也须合法，避免手势使用未验证矩形。
if let Some(clip) = mount.viewport_clip {
validate_rect(clip[0], clip[1], clip[2], clip[3], 0.0)?;
}
@@ -235,11 +273,14 @@ impl RenderDocument {
}
}
// 此处只保证关系目标在帧内，不做完整树环/双向一致性验证；组成与生命周期层承担更强结构不变量。
// 第二轮使用完整 ID 集合检查关系归属；这里不证明双向一致性或无环。
for mount in &self.frame.mounts {
// 只枚举实际存在的关系 ID，None 是合法边界，不补造关系。
for linked in [mount.parent, mount.first_child, mount.next_sibling]
.into_iter()
.flatten()
{
// 任何父/子/兄弟关系都必须落在本窗口帧内。
if !mount_ids.contains(&linked) {
bail!("mount links outside this frame");
}
@@ -256,7 +297,9 @@ impl RenderDocument {
{
bail!("frame root does not match its visual projection");
}
// 源码树单独检查节点 ID 唯一，不能和视觉 Mount ID 集合混用。
let mut ids = HashSet::new();
// 无源码树是合法空发布；有根则递归检查深度、范围和身份。
if let Some(root) = &self.root {
root.validate(0, &mut ids)?;
}
@@ -265,11 +308,14 @@ impl RenderDocument {
/// 将逻辑命令转换到设备比例并应用逐命令视图/裁剪；不自动调用 validate，发布入口须先校验。
pub fn display_list(&self, scale: f32) -> Result<DisplayList> {
// 窗口渲染调用此转换，借用已发布完整帧，不访问候选 VM 或业务对象。
let frame = &self.frame;
// 新建拥有数据的设备显示列表，先清背景再按逻辑绘制顺序追加。
let mut list = DisplayList::default();
list.push(DrawCommand::Clear(parse_color(&frame.background)?));
// 按命令顺序取对应 clip/view；缺项按无裁剪/单位变换处理，完整文档合法性应在发布入口预先验证。
for (index, command) in frame.commands.iter().enumerate() {
// 表可整体缺省；存在裁剪时为单条命令压入/弹出，防止影响后续无关命令。
let clip = frame.command_clips.get(index).copied().flatten();
// clip 已在父视图/面板对应空间，只乘设备 scale；命令本体则乘 view.zoom 再加 view 平移。
if let Some(clip) = clip {
@@ -277,6 +323,7 @@ impl RenderDocument {
clip[0], clip[1], clip[2], clip[3], scale,
)));
}
// 没有逐命令 view 时使用单位变换；实际缩放由设备 scale×view.zoom 组成。
let view = frame
.command_views
.get(index)
@@ -289,6 +336,7 @@ impl RenderDocument {
.to_draw_command(scale * view.zoom)?
.translated(Point::new(view.x * scale, view.y * scale)),
);
// 本命令已经绘制，配对弹出先前压入的 clip，维持列表栈平衡。
if clip.is_some() {
list.push(DrawCommand::PopClip);
}
@@ -299,6 +347,7 @@ impl RenderDocument {
.and_then(|id| frame.mounts.iter().find(|m| m.id == id))
.filter(|mount| mount.panel.is_none())
{
// 焦点框使用与目标同一祖先裁剪，不能穿出滚动容器或有限面板。
if let Some(c) = focus.clip {
list.push(DrawCommand::PushClip(scaled_rect(
c[0], c[1], c[2], c[3], scale,
@@ -324,6 +373,7 @@ impl RenderDocument {
}
.to_draw_command(scale)?,
);
// 焦点框单独配对弹出 clip，避免把之后的故障提示也裁掉。
if focus.clip.is_some() {
list.push(DrawCommand::PopClip);
}
@@ -365,14 +415,20 @@ impl RenderDocument {
#[derive(Clone, Debug, Serialize, Deserialize)]
/// Sources 使用的源码层次节点；ID、名称、种类和行列范围都属于代码投影而不是运行时对象句柄。
pub struct CodeNode {
// 源码节点稳定选择键，带命名空间/提交来源；与视觉 block_id 字符串用途不同。
pub id: String,
// 源声明或语句的显示名称，Sources 用于树列表标题，不作为全局唯一键。
pub name: String,
// 源码结构类别（如 script/module/function），不等于运行时视觉组件种类。
pub kind: String,
#[serde(default)]
// 原源码起始行，零表示缺少来源，不能默认当作第一行。
pub start_line: usize,
#[serde(default)]
// 原源码结束行；两端都已知时必须不早于 start_line。
pub end_line: usize,
#[serde(default)]
// 源码语法投影的有序孩子，验证 ID 唯一性时共享整树集合。
pub children: Vec<CodeNode>,
}
@@ -383,9 +439,11 @@ impl CodeNode {
if depth > 64 {
bail!("architecture tree exceeds 64 levels");
}
// 空源码节点 ID 无法供 Sources 稳定选中或查找，发布时拒绝。
if self.id.is_empty() {
bail!("architecture node id cannot be empty");
}
// 集合覆盖整棵树，两个不同分支也不能重用同一节点 ID。
if !ids.insert(&self.id) {
bail!("duplicate architecture node id: {}", self.id);
}
@@ -393,6 +451,7 @@ impl CodeNode {
if self.start_line > 0 && self.end_line > 0 && self.start_line > self.end_line {
bail!("invalid source range for node {}", self.id);
}
// 递归共享全局身份集合并增加深度，不能每个子树重新计数而绕过约束。
for child in &self.children {
child.validate(depth + 1, ids)?;
}
@@ -401,6 +460,7 @@ impl CodeNode {
/// 按请求的代码节点身份或路径查找对应的源码投影。
fn find(&self, id: &str) -> Option<&CodeNode> {
// node(id) 先匹配当前节点，未命中再按孩子顺序递归返回首个匹配。
if self.id == id {
return Some(self);
}
@@ -415,32 +475,43 @@ pub struct Frame {
#[serde(skip)]
pub hit_index: Arc<crate::viewport::spatial::Index>,
#[serde(default)]
// 页面级兼容 pan/zoom 与内容范围；独立相机另由 command_views/Mount.view 表达。
pub surface: crate::page::Surface,
#[serde(default = "default_window")]
// 非零原生窗口身份，副窗口 map 的键必须与它相同。
pub window: u64,
#[serde(default = "default_background")]
// 页面清屏颜色文本，每帧显示列表先生成一条 Clear。
pub background: String,
#[serde(default)]
// 按最终绘制顺序保存逻辑命令，后项覆盖前项；不包含显示列表追加的焦点/故障层。
pub commands: Vec<RenderCommand>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
// 逐命令有效裁剪 [x,y,width,height]；可整体为空，否则必须与 commands 等长。
pub command_clips: Vec<Option<[f32; 4]>>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
// 逐命令二维投影，缺省单位变换；clip 已在投影后的对应视图空间。
pub command_views: Vec<Option<crate::viewport::Transform>>,
#[serde(skip)]
// 仅本机装配源覆盖/面板时使用的命令出现归属表，不进入 JSON；display_list 绘制本身不读取它。
pub command_mounts: Vec<u64>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
// 本窗口所有出现位置的平面索引，业务身份可重复，Mount ID 必须唯一。
pub mounts: Vec<MountGeometry>,
#[serde(default)]
// 本次布局发布版本，与 session/window 一起判断原生输入是否过期。
pub layout_version: u64,
#[serde(default)]
// 运行时世代与 layout_version 共同确定输入归属；仅布局版本相同不能跨 VM 接受事件。
pub session: u64,
#[serde(default)]
// 焦点 Mount ID，普通根焦点在 display_list 追加，面板焦点已组合进纹理。
pub focus: Option<u64>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
// 当前窗口标签投影，ID 唯一且最多一个 active。
pub tabs: Vec<crate::tabs::Tab>,
#[serde(default)]
// 停止域诊断，显示列表追加提示且 hit_test 拒绝继续选择交互目标。
pub fault: Option<String>,
}
@@ -474,32 +545,48 @@ pub struct MountGeometry {
// 可嵌套的世界 UI 映射，把页面坐标还原到此出现所在面板纹理空间。
pub panel: Option<Arc<crate::scene3d::panel::Mapping>>,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
// 是否二维相机视口，供窗口手势定位选择。
pub canvas_viewport: bool,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
// 是否三维视口，原生拾取/相机事件据此进入对应协议。
pub scene3d_viewport: bool,
#[serde(default)]
// 三维视口是否具备相机控制器，camera_at 不只凭 scene3d_viewport 接受手势。
pub camera_controls: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
// 视口内容区的额外裁剪，供相机手势锚点检查；区别于一般 Mount 的祖先 clip。
pub viewport_clip: Option<[f32; 4]>,
#[serde(default, skip_serializing_if = "Option::is_none")]
// 布局空间到当前视图/面板纹理空间的二维变换，None 为单位变换。
pub view: Option<crate::viewport::Transform>,
#[serde(default, skip_serializing_if = "Option::is_none")]
// 祖先合成后的可见裁剪，与投影后的点比较，不能当作布局空间矩形。
pub clip: Option<[f32; 4]>,
#[serde(default, skip_serializing_if = "Option::is_none")]
// 当前有效滚动位置和上限，不是原始请求值；非滚动容器为 None。
pub scroll: Option<[f32; 4]>,
// 本帧内出现身份，重建/换页可变化，不是托管 ObjectRef。
pub id: u64,
// 业务对象身份文本，共享对象的多个 Mount 可拥有同一 block_id。
pub block_id: String,
// 父出现 ID；关系目标必须在本帧中，不允许跨窗口链接。
pub parent: Option<u64>,
// 首个子出现 ID，通过 next_sibling 遍历同级。
pub first_child: Option<u64>,
// 下一个同级出现 ID，保留组成展开次序。
pub next_sibling: Option<u64>,
// 出现的布局空间绝对横坐标，投影通过 view/panel 另算。
pub x: f32,
// 出现的布局空间绝对纵坐标，不随相机直接改写。
pub y: f32,
// 本次布局分配宽度，可不同于共享业务对象的自然 width。
pub width: f32,
// 本次布局分配高度，不和其他出现位置共用几何存储。
pub height: f32,
// 原生粗命中资格，真正源 hitTest/事件监听状态仍由 worker 复核。
pub interactive: bool,
#[serde(default)]
// 是否存在 pointer 系列处理需求，供窗口指针输入路由使用。
pub pointer_events: bool,
}
@@ -518,12 +605,15 @@ impl MountGeometry {
}
/// 把视图位移换算成目标出现的局部位移，处理缩放与世界 UI 投影差异。
pub fn logical_delta(&self, point: Option<[f32; 2]>, delta: [f32; 2]) -> Option<[f32; 2]> {
// 累计二维缩放用于把最终视图差值还原到布局位移；透视面板还需先投影两个端点。
let zoom = self.view.unwrap_or_default().zoom;
// 普通二维映射为线性，只除累计 zoom 即可；世界面板透视非线性，必须映射两个点求差。
if self.panel.is_none() {
return Some([delta[0] / zoom, delta[1] / zoom]);
}
// 面板投影非线性，缺少当前位置就无法正确换算 delta，明确返回 None。
let point = point?;
// 先反投影手势基点；clipped=false 允许捕获拖动移出面板，投影失败则停止处理。
let current = self.view_point(Point::new(point[0], point[1]), false)?;
// 对 point 与 point+delta 分别投影，使用 clipped=false 允许捕获拖动越出面板；投影不可逆则返回 None。
let previous =
@@ -535,6 +625,7 @@ impl MountGeometry {
}
/// 判断给定点是否位于目标范围；需要相机转换的类型会先转换再判断。
pub fn contains(&self, point: Point) -> bool {
// 先完成世界面板反投影和遮挡检查，失败直接视为未命中。
let Some(point) = self.view_point(point, true) else {
return false;
};
@@ -550,6 +641,7 @@ impl MountGeometry {
impl Frame {
/// 从顶层绘制顺序向后查找可控制的视口，命中与裁剪均成立才接收相机手势。
pub fn camera_at(&self, point: Point) -> Option<&MountGeometry> {
// 窗口手势目标选择使用空间索引候选次序，但仍须逐个通过视口种类、外框和内容裁剪。
self.hit_index
.candidates(point, self.mounts.len())
.into_iter()
@@ -595,6 +687,7 @@ fn default_background() -> String {
/// 可校验、可序列化的逻辑绘制命令；转换到设备像素在 display_list 阶段完成。
pub enum RenderCommand {
#[serde(skip_deserializing)]
// 仅本机可构造的不可变图像资源命令，禁止从外部 JSON 反序列化任意图像资源。
Image {
x: f32,
y: f32,
@@ -607,6 +700,7 @@ pub enum RenderCommand {
tint: Option<Color>,
image: Arc<crate::render::image::Image>,
},
// 屏幕矩形中的三维 View 快照，世界几何和相机数据由原生 Arc 独立拥有。
Scene3D {
x: f32,
y: f32,
@@ -614,6 +708,7 @@ pub enum RenderCommand {
height: f32,
view: Arc<crate::scene3d::View>,
},
// 逻辑坐标填充矩形，颜色保存文本，设备缩放和通道解码在显示列表转换时完成。
RoundedRect {
x: f32,
y: f32,
@@ -623,6 +718,7 @@ pub enum RenderCommand {
radius: f32,
color: String,
},
// 逻辑坐标描边矩形，stroke_width 与半径都参与设备同比缩放。
StrokeRoundedRect {
x: f32,
y: f32,
@@ -634,6 +730,7 @@ pub enum RenderCommand {
stroke_width: f32,
color: String,
},
// 逻辑文字和离散字号，可选 wrap_bounds 明确是否换行；旧数据缺省为不换行。
Text {
x: f32,
y: f32,
@@ -649,7 +746,9 @@ pub enum RenderCommand {
impl RenderCommand {
/// 检查当前输入或发布值的不变量，调用方据校验结果决定是否继续。
pub(crate) fn validate(&self) -> Result<()> {
// RenderDocument.validate 逐条调用，按命令种类检查自身数据；不在这里尝试光栅化。
match self {
// 本机图片命令除了外框还包含偏移、角度和透明度，资源像素尺寸必须非零。
Self::Image {
x,
y,
@@ -663,6 +762,7 @@ impl RenderCommand {
..
} => {
validate_rect(*x, *y, *width, *height, 0.)?;
// 所有变换参数有限且 opacity 在 [0,1]，防止无效混合或图像采样。
if ![offset_x, offset_y, angle, opacity]
.iter()
.all(|v| v.is_finite())
@@ -673,6 +773,7 @@ impl RenderCommand {
bail!("invalid image command");
}
}
// 三维视口外框与 view 快照各自验证，场景数据不能仅因外框合法就直接绘制。
Self::Scene3D {
x,
y,
@@ -681,10 +782,12 @@ impl RenderCommand {
view,
} => {
validate_rect(*x, *y, *width, *height, 0.0)?;
// View 的投影/场景不变量失败时拒绝发布，不让无效射线/深度计算进入渲染。
if !view.valid() {
bail!("invalid 3D view");
}
}
// 填充矩形检查有限非负尺寸/圆角，再解码颜色格式。
Self::RoundedRect {
x,
y,
@@ -696,6 +799,7 @@ impl RenderCommand {
validate_rect(*x, *y, *width, *height, *radius)?;
parse_color(color)?;
}
// 描边矩形除公共几何外还必须具有正且有限的描边宽度。
Self::StrokeRoundedRect {
x,
y,
@@ -712,6 +816,7 @@ impl RenderCommand {
}
parse_color(color)?;
}
// 文字无框时只要求坐标有限；有 wrap 框时还校验框和端点的协议范围。
Self::Text {
x,
y,
@@ -720,12 +825,14 @@ impl RenderCommand {
color,
wrap_bounds,
} => {
// 首先拒绝文字原点 NaN/无穷，后续测量与绘制不能处理这类坐标。
if !x.is_finite() || !y.is_finite() {
bail!("text coordinates must be finite");
}
// 有换行框时同时限制框尺寸、原点与右/下端点；无框文本在此只校验坐标有限性和文本/字号预算。
if let Some([width, height]) = wrap_bounds {
validate_rect(*x, *y, *width, *height, 0.0)?;
// 换行框本身及其远端坐标都不得超过视觉长度预算，避免原点与宽高相加后越界。
if [*x, *y, *width, *height, *x + *width, *y + *height]
.iter()
.any(|value| value.abs() > crate::ui_bridge::MAX_DIMENSION as f32)
@@ -733,9 +840,11 @@ impl RenderCommand {
bail!("text wrap bounds exceed limits");
}
}
// 单条文字按 UTF-8 字节限长 16 KiB，不按字符数估算资源用量。
if value.len() > 16_384 {
bail!("text command exceeds 16 KiB");
}
// size 是 1..8 的样式等级，不是任意像素字号。
if !(1..=8).contains(size) {
bail!("text size must be between 1 and 8");
}
@@ -747,7 +856,9 @@ impl RenderCommand {
/// 把一条已验证的发布命令变成原生绘制原语，缩放几何和文字样式。
fn to_draw_command(&self, scale: f32) -> Result<DrawCommand> {
// display_list 调用这里把逻辑命令同比缩放为设备原语；二维平移由调用方随后统一追加。
Ok(match self {
// 图像保留不可变资源 Arc，原点/局部矩形按比例缩放，角度、透明度和 tint 保持其含义。
Self::Image {
x,
y,
@@ -767,6 +878,7 @@ impl RenderCommand {
opacity: *opacity,
tint: *tint,
},
// 只缩放三维视口屏幕矩形，内部相机与世界场景仍由 View 快照解释。
Self::Scene3D {
x,
y,
@@ -777,6 +889,7 @@ impl RenderCommand {
rect: scaled_rect(*x, *y, *width, *height, scale),
view: view.clone(),
},
// 填充矩形位置/尺寸/圆角同比缩放，颜色转为渲染器通道值。
Self::RoundedRect {
x,
y,
@@ -789,6 +902,7 @@ impl RenderCommand {
radius: radius * scale,
color: parse_color(color)?,
},
// 描边宽度也乘设备比例，保持与矩形外观一致的视觉厚度。
Self::StrokeRoundedRect {
x,
y,
@@ -812,12 +926,14 @@ impl RenderCommand {
wrap_bounds,
// 根据是否提供换行边界选择 WrappedText 或 Text；两者都使用同一等级字号与设备缩放。
} => match wrap_bounds {
// 有 wrap 框时产生 WrappedText，排字区域和样式同时缩放，保持换行语义。
Some([width, height]) => DrawCommand::WrappedText {
rect: scaled_rect(*x, *y, *width, *height, scale),
value: value.clone(),
style: crate::text::TextStyle::ui(*size).scaled(scale),
color: parse_color(color)?,
},
// 旧 JSON 未提供 wrap_bounds 时保留不换行 Text 行为，不凭测量结果补造裁剪。
None => DrawCommand::Text {
origin: Point::new(x * scale, y * scale),
value: value.clone(),
@@ -841,6 +957,7 @@ fn default_text_size() -> u32 {
/// 统一检查有限矩形坐标、尺寸与可选圆角，阻止异常值进入光栅循环。
fn validate_rect(x: f32, y: f32, width: f32, height: f32, radius: f32) -> Result<()> {
// 各命令/clip 共用基础几何检查；世界坐标可负，但四个分量必须有限。
if !x.is_finite() || !y.is_finite() || !width.is_finite() || !height.is_finite() {
bail!("rectangle values must be finite");
}
@@ -858,6 +975,7 @@ fn scaled_rect(x: f32, y: f32, width: f32, height: f32, scale: f32) -> Rect {
/// 解析支持的十六进制 RGB/RGBA 文本，拒绝错误长度或非法字符。
pub fn parse_color(value: &str) -> Result<Color> {
// 属性解码、文档验证和显示列表转换共用颜色入口，必须带显式 # 前缀。
let hex = value
.strip_prefix('#')
.ok_or_else(|| anyhow::anyhow!("color must begin with #"))?;
@@ -865,6 +983,7 @@ pub fn parse_color(value: &str) -> Result<Color> {
if !hex.is_ascii() || (hex.len() != 6 && hex.len() != 8) {
bail!("color must use #RRGGBB or #RRGGBBAA");
}
// 已确认 ASCII 和长度后，可安全按字节成对解析 R/G/B/A，非法十六进制仍返回错误。
let parse = |range| u8::from_str_radix(&hex[range], 16);
Ok(Color::rgba(
parse(0..2)?,
@@ -880,6 +999,7 @@ mod tests {
#[test]
/// 旧文字JSON缺wrap_bounds仍走不换行命令；合法边界随DPI缩放，负宽度在发布验证中拒绝。
fn text_wrap_bounds_validate_and_legacy_text_remains_unwrapped() {
// 从缺省 wrap_bounds 的旧 JSON 反序列化，验证兼容默认值而非手工构造近似命令。
let mut command: RenderCommand = serde_json::from_str(
r##"{"type":"text","x":0,"y":0,"value":"text","size":1,"color":"#000000"}"##,
)
@@ -888,6 +1008,7 @@ mod tests {
command.to_draw_command(1.0).unwrap(),
DrawCommand::Text { .. }
));
// 添加合法 40×20 框，后面以 1.25 DPI 核对实际绘制原语尺寸。
if let RenderCommand::Text { wrap_bounds, .. } = &mut command {
*wrap_bounds = Some([40.0, 20.0]);
}
@@ -895,6 +1016,7 @@ mod tests {
assert!(
matches!(command.to_draw_command(1.25).unwrap(),DrawCommand::WrappedText{rect,..}if rect.width==50.0 && rect.height==25.0)
);
// 再破坏为负宽，要求发布验证拒绝，而不是把尺寸夹到零继续显示。
if let RenderCommand::Text { wrap_bounds, .. } = &mut command {
*wrap_bounds = Some([-1.0, 20.0]);
}
@@ -906,6 +1028,7 @@ mod tests {
#[test]
/// 默认空文档可通过验证且没有结构根/绘图命令，支持初始状态与清空发布。
fn empty_document_is_valid_and_blank() {
// 默认值代表初始化/清空后的合法空状态，既不需要源码树也不需要业务命令。
let document = RenderDocument::default();
document.validate().unwrap();
assert!(document.root.is_none());
@@ -915,6 +1038,7 @@ mod tests {
#[test]
/// 检查六位色默认alpha255，八位色按RRGGBBAA解码，避免将末尾透明度当成首通道。
fn parses_rgb_and_rgba_colors() {
// 六位色默认不透明，八位色最后两位为 alpha，分别核对通道顺序。
assert_eq!(
parse_color("#102030").unwrap(),
Color::rgba(16, 32, 48, 255)
@@ -932,13 +1056,16 @@ mod window_projection_tests {
#[test]
/// 同会话窗口命令可累积，新会话发布先丢旧命令；clear重置runtime_session并清空所有原生命令。
fn replacement_and_reset_discard_old_window_projections() {
// 模拟 API 发布状态，先在同一 VM session 累积不同动作，再更换世代。
let mut state = NamespaceState::default();
// 第一动作 Focus 与随后 Resize 类型不同，同世代合并不应互相覆盖。
let command = crate::window::Command {
window: 1,
sequence: 1,
action: crate::window::Action::Focus,
};
state.publish_window_commands(1, vec![command.clone()]);
// 第二动作使用更大 sequence，检验同世代累积及换世代清旧命令。
let resize = crate::window::Command {
window: 1,
sequence: 2,
@@ -952,6 +1079,7 @@ mod window_projection_tests {
state.publish_window_commands(2, vec![resize]);
assert_eq!(state.window_commands.len(), 1);
assert_eq!(state.window_commands[0].session, 2);
// clear 应清除当前 runtime_session 和待传输命令，旧 VM 请求不能在重置后落到新窗口。
state.clear().unwrap();
assert_eq!(state.runtime_session, 0);
assert!(state.window_commands.is_empty());
src/model/snapshot.rs
+94 -1
View File
@@ -2,6 +2,10 @@
//! 缓存只借用可检查的对象身份，不增加托管根。对象释放后必须清理缓存索引；快照仍可持有独立的原生数值数据。
//! 干净子树直接复用 Arc；脏节点重新检查属性、方法、绑定和子项，循环与展开数量在发布前拒绝。
//!
//! 调用路径：UiBridge 的 prepare/刷新入口消费 VM ChangeBatch，调用 invalidate/prune 后按页面根 snapshot。
//! block::snapshot 也可用临时空缓存一次性提取；持久窗口缓存只保留原生 UiNode Arc，不 retain 托管身份。
//! 协议方法/属性改变会使业务快照失效，但相机、布局和绘制各自还有后续阶段的缓存边界。
//!
//! Object-to-visual dependencies. Cached results never own VM references.
use crate::{
block::{self, Kind},
@@ -16,15 +20,20 @@ use std::{
#[derive(Debug)]
/// 某个业务组件的视觉快照，以及使它失效的读取依赖和子项身份。
struct Cached {
// 已提取的原生不可变视觉树，窗口/布局可复用 Arc，不能由其中的身份文本操作 VM。
node: Arc<UiNode>,
// 重建时实际登记的反向读取键，remove 必须逐一撤销，避免旧读取持续误失效。
dependencies: Vec<Dependency>,
// 当前组成孩子的借用身份，仅维护父链反向索引，不形成新的托管强边。
children: Vec<ObjectRef>,
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
/// 反向依赖键：区分整个对象内容和精确属性名称，减少无关字段变化引起的失效。
struct Dependency {
// 读取源的借用身份，对象可能已被回收，使用前需由 prune/store 查询处理失效。
object: ObjectRef,
// Some 表示精确字段；None 表示对象内容/方法表等整体依赖，与 ChangeKey 粒度对应。
property: Option<String>,
}
@@ -41,29 +50,38 @@ pub struct RenderCache {
parents: HashMap<ObjectRef, HashSet<ObjectRef>>,
// 已失效但尚未重建的 Block 集合，同时用于传播去重。
dirty: HashSet<ObjectRef>,
// 最近一次失效原因诊断，供开发工具/统计展示，不决定缓存正确性。
pub last_invalidation: String,
// 本次 snapshot 实际重建的进入次数，按调用重置并用于展开预算。
pub visited: usize,
// 本次直接命中干净缓存的节点数，不等于整个复用子树的展开节点数。
pub reused: usize,
}
impl RenderCache {
/// 把 VM 变化映射到读取过这些属性/对象的视觉节点，再沿父链向上传播脏标记。
pub fn invalidate(&mut self, batch: ChangeBatch) {
// 收集首批受变化影响的业务 Block，随后统一交给父链失效传播。
let mut queue = VecDeque::new();
// 变更日志溢出后无法知道遗漏了哪些写入，保守地将已有快照全部失效。
if batch.rescan_required {
self.last_invalidation = "change journal overflow".into();
queue.extend(self.entries.keys().copied());
} else {
// 非溢出批次逐项按读取粒度匹配，不把无关字段变化扩大为整图失效。
for change in batch.changes {
// 属性变更使用精确名称，Contents 使用整个对象键；与提取时登记的依赖粒度一致。
// 变化键与提取时记录的 Dependency 完全同构，保证属性名与 Contents 不混用。
let key = Dependency {
object: change.object,
property: match change.key {
// 字段写入只匹配该名字的精确读取者。
ChangeKey::Attribute(name) => Some(name),
// 对象 payload/方法内容变化匹配整个对象的依赖。
ChangeKey::Contents => None,
},
};
// 同一个源可被多个业务快照读取，全部加入队列；去重与父链传播在下一入口处理。
if let Some(owners) = self.dependents.get(&key) {
self.last_invalidation = format!("{} {:?}", key.object, key.property);
queue.extend(owners);
@@ -75,7 +93,9 @@ impl RenderCache {
/// 迭代传播显式失效，使用集合避免共享父链重复遍历或循环入队。
pub fn invalidate_objects(&mut self, objects: impl IntoIterator<Item = ObjectRef>) {
// 显式失效入口也复用同一队列算法，调用方可传多个共享节点。
let mut queue: VecDeque<_> = objects.into_iter().collect();
// 广度推进向上的父链，不递归进入 Rust 栈；dirty 同时作为传播去重集合。
while let Some(block) = queue.pop_front() {
// 只有第一次加入 dirty 才继续向父链传播，避免共享祖先被反复展开。
if self.dirty.insert(block)
@@ -88,20 +108,27 @@ impl RenderCache {
/// 撤销旧缓存的反向读取边和父子边，为重新登记该节点做准备。
fn remove(&mut self, block: ObjectRef) -> Option<Cached> {
// 先移除本体，若根本没缓存则无需撤边；返回旧 Arc 供调用方比较是否可复用。
let old = self.entries.remove(&block)?;
// 旧边必须先撤销，否则节点重建后仍会被已经不再读取的对象触发失效。
// 撤销旧快照的每个读取反向边，新建依赖可能已不再读取这些对象/属性。
for source in &old.dependencies {
// 只移除当前 Block，不能让其他仍读取该源的快照失去失效通知。
if let Some(owners) = self.dependents.get_mut(source) {
owners.remove(&block);
// 没有读取者时清空索引项，避免死亡/过时依赖键持续积累。
if owners.is_empty() {
self.dependents.remove(source);
}
}
}
// 只撤销当前 Block 对孩子的父边；其他共享父节点仍保留。空集合及时删除以缩小索引。
// 撤销当前父对孩子的索引边，共享孩子仍可能保留其他父。
for child in &old.children {
// 找到孩子所有父集合，仅删除本 Block 的组成关系。
if let Some(parents) = self.parents.get_mut(child) {
parents.remove(&block);
// 孩子已无缓存父时删除反向项，避免无用身份长期占缓存内存。
if parents.is_empty() {
self.parents.remove(child);
}
@@ -112,6 +139,7 @@ impl RenderCache {
/// 删除托管堆中已不存在的身份，缓存本身不负责保持业务对象存活。
pub fn prune(&mut self, store: &ObjectStore) {
// 桥接回收/准备入口调用 prune，先丢弃托管场景根已经不存在的原生场景缓存。
self.scenes3d
.retain(|object, _| store.object(*object).is_ok());
// 先收集死亡身份，再修改 entries 与反向索引，避免一边借用遍历一边删除。
@@ -121,9 +149,10 @@ impl RenderCache {
.filter(|v| store.object(**v).is_err())
.copied()
.collect();
// 每个死亡 Block 都需 remove 撤销依赖和父边，不只删除 entries 本体。
for block in dead {
self.remove(block);
// 只有成功建立新条目后才清脏标记；前面任何校验失败都不会把节点错误标成干净。
// 此处身份已死亡，不会再重建；清除其遗留脏标记，避免弱索引变成长期墓碑。
self.dirty.remove(&block);
}
}
@@ -134,16 +163,22 @@ impl RenderCache {
store: &ObjectStore,
root: ObjectRef,
) -> Result<Arc<UiNode>, VmError> {
// 按本次提取重置工作统计，缓存内容与 dirty 则跨调用保留。
self.visited = 0;
self.reused = 0;
// 使用进入/退出两阶段的显式 DFS，避免深层组成消耗 Rust 调用栈。
// values 是后序结果栈：每个退出节点消费刚完成的孩子快照，再压入自己。
// 每项为业务 Block 与后序完成标记；false 先展开孩子，true 再消费孩子结果组装父。
let mut work = vec![(root, false)];
// 当前祖先 Data 集合防止组合环，不是整棵图的全局去重，合法共享孩子仍可多次出现。
let mut path = HashSet::new();
// 原生子树后序结果栈，保留兄弟已有结果，父完成时只取尾部本节点孩子。
let mut values = Vec::<Arc<UiNode>>::new();
// 显式 DFS 驱动全部提取，发生错误就拒绝这次快照，不返回半棵树。
while let Some((block, finish)) = work.pop() {
// 入栈时先尝试复用；退出标记表示孩子已形成快照，可以组装父节点。
if !finish {
// 干净且存在条目才能复用；仅不在 dirty 中并不能证明已缓存。
if !self.dirty.contains(&block)
&& let Some(cached) = self.entries.get(&block)
{
@@ -153,14 +188,18 @@ impl RenderCache {
}
// 计数的是本次实际展开次数；共享节点可复用缓存，脏图展开仍有 10000 次上限。
self.visited += 1;
// 超过实际重建展开预算明确报错，不能按固定节点数截断显示。
if self.visited > 10_000 {
return Err(VmError::ExecutionLimit("expanded Block graph"));
}
}
// 提取前验证实例存储与类型契约；resolve_tracked 同时提供数据以及经过的代理/存储依赖。
store.check_typed_instance_storage(block)?;
// 取得共享转发后的真实 Data 及 Block/Cell 路径，让替换身份和中间单元变化也触发重建。
let (data_ref, raw_data, raw_dependencies) = block::resolve_tracked(store, block)?;
// 托管属性只覆盖本轮副本，提取不改业务对象；后面的三维面板展开也只修改此副本。
let mut data = block::visual_data(store, raw_data)?;
// 把转发链各对象登记为 Contents 依赖，随后再添加精确字段和协议方法键。
let mut dependencies: Vec<_> = raw_dependencies
.into_iter()
.map(|object| Dependency {
@@ -169,10 +208,12 @@ impl RenderCache {
})
.collect();
// 方法名称查找也构成依赖。即使属性数值未变，协议方法被替换也必须让快照失效。
// 方法可被实例存储阴影，记录末端属性存储中所有受契约约束的方法名。
let storage = *store
.attribute_path(block)?
.last()
.expect("nonempty attribute path");
// 类型方法名也需对实例字段写入失效，以便重建时报告非法阴影而非复用旧合法快照。
for name in store.typed_method_names(block)? {
dependencies.push(Dependency {
object: storage,
@@ -180,7 +221,9 @@ impl RenderCache {
});
}
// 原生视觉属性按精确字段登记，避免不参与视觉的其他属性写入触发整个节点重建。
// 原生字段存储独立于 Data 结构 payload，按每个公开视觉字段建立精确依赖。
if let Some(properties) = data.properties {
// 只登记该原生 kind 实际解释的字段，不遍历所有业务自定义属性。
for (name, _) in block::native_properties(&data) {
dependencies.push(Dependency {
object: properties,
@@ -188,9 +231,11 @@ impl RenderCache {
});
}
}
// 二维相机字段进入视口快照依赖，只有 camera 本身的业务变化影响对应视口。
if matches!(data.kind, Kind::CanvasViewport { .. })
&& let Some(camera) = data.camera
{
// 记录三项相机参数的精确读依赖，源控制器等无关字段不使二维视图重建。
for name in ["x", "y", "zoom"] {
dependencies.push(Dependency {
object: camera,
@@ -199,11 +244,15 @@ impl RenderCache {
}
}
// 3D 面板把托管内容映射为子 Block，同时保留尺寸与稳定 slot，供后续布局和出现身份使用。
// 三维提取返回的每块面板 UI 分辨率，顺序必须和替换后的 children 相同。
let mut panel_sizes = Vec::new();
// 只有 Viewport3D 提取三维 View；普通种类不能凭同名 scene 字段触发场景遍历。
let view3d = if matches!(data.kind, Kind::Viewport3D { .. }) {
// 三维视口必须有 Scene3D 业务根；缺失即拒绝本次快照。
let scene = data
.scene3d
.ok_or(VmError::InvalidArgument("missing Scene3D"))?;
// 传入同场景旧原生 Arc 以便只改相机时复用场景；同时收集真实字段读取及面板组成。
let (view, reads, panels) = crate::scene3d_model::snapshot_reusing(
store,
scene,
@@ -218,6 +267,7 @@ impl RenderCache {
}));
data.children = panels
.into_iter()
// 每块面板内容作为 UI 孩子，panel.key 成为稳定 slot；另并行保存 UI 尺寸供布局使用。
.map(|panel| {
panel_sizes.push(panel.size);
crate::block::Child {
@@ -231,29 +281,39 @@ impl RenderCache {
None
};
// path 只追踪当前祖先链，因此允许同一业务组件在不同分支多次出现。
// 首次进入登记祖先与展开孩子；finish=true 表示孩子结果已齐，下一步可以组装本节点。
if !finish {
// 同一 Data 在当前祖先链再次出现才是环；与兄弟分支共享区分。
if !path.insert(data_ref) {
return Err(VmError::InvalidArgument("cyclic Block composition"));
}
work.push((block, true));
// 逆序压栈使孩子实际完成顺序仍与组成顺序一致，退出标记排在全部孩子之后。
for child in data.children.iter().rev() {
work.push((child.block, false));
}
continue;
}
path.remove(&data_ref);
// 只有仍有 handler 且 kind 以 pointer 开头的连接提供 pointer_events，断开令牌不再算交互需求。
let pointer_connection = data.subscriptions.iter().any(|&o| {
store
.payload::<crate::event_dispatch::Connection>(o, "Subscription")
.is_ok_and(|s| s.handler.is_some() && s.kind.starts_with("pointer"))
});
// 协议键包含类型身份、实际方法身份及其内容版本，供布局/绘制缓存识别实现变化。
// 协议指纹供后续布局/绘制缓存比较；不能仅凭业务 Block ID 认定实现没变。
let mut protocol_key = String::new();
// 无类型或无 onEvent 时默认没有自定义事件能力，随后按名义方法识别。
let mut custom_event = false;
// 名义类型与其方法表决定实际协议，不从任意同名实例值推断视觉实现。
if let Some(definition) = store.type_of(block)? {
protocol_key.push_str(&definition.to_string());
// 五种视觉/事件协议方法都记录句柄及内容版本，payload 保持句柄不变也会改变指纹。
for name in ["measure", "arrange", "paint", "hitTest", "onEvent"] {
// 仅已解析到的实际方法加入依赖；类型链另登记，负责将来新增/替换方法的失效。
if let Some(method) = store.lookup_method(definition, name)? {
// 使用对象内容版本识别同函数身份下的实现替换，不只把方法名拼入字符串。
let version = store.change_version(method)?;
protocol_key.push_str(&format!("/{method}:{version}"));
dependencies.push(Dependency {
@@ -263,13 +323,17 @@ impl RenderCache {
}
}
// 不仅记录最终方法，还沿基类链登记类型内容依赖，使继承关系或方法表变化能触发重建。
// 保存当前解析到的 onEvent，再遍历基类链登记方法表依赖。
let event = store.lookup_method(definition, "onEvent")?;
// 从动态类型向基类推进，每层都属于方法查找的读取来源。
let mut current = Some(definition);
// 继承关系/任一基类表变化都能影响查找结果，不能只观察最终方法函数。
while let Some(definition) = current {
dependencies.push(Dependency {
object: definition,
property: None,
});
// 名义类型 payload 提供 base 链，错误类型不能被当成链尾默默接受。
let item = store.payload::<endor_core::EndorTypeObject>(definition, "Type")?;
current = item.base();
}
@@ -281,29 +345,38 @@ impl RenderCache {
.unwrap_or(false);
}
// 订阅连接的取消会改变 handler；记录连接内容依赖，使交互资格能随取消及时更新。
// 另累计 click 监听资格，与 pointer 系列、内建 Button 和源 onEvent 合并。
let mut click_connection = false;
// 所有事件连接的 handler 取消都会写 payload，Contents 依赖让交互标记及时重算。
for connection in &data.subscriptions {
dependencies.push(Dependency {
object: *connection,
property: None,
});
// 从真实 Connection payload 判断事件种类与有效 handler，不能凭连接句柄存在就当作活跃。
let item = store
.payload::<crate::event_dispatch::Connection>(*connection, "Connection")?;
click_connection |= item.kind == "click" && item.handler.is_some();
}
// 逆序压入孩子确保后序结果与 data.children 原顺序一致；只取尾部的本节点孩子，保留兄弟结果。
// 每个孩子在后序栈恰有一个结果；按数量拆尾部，其他兄弟结果留给祖先。
let children = values.split_off(values.len() - data.children.len());
// 将业务描述转为不依赖 VM 存活的原生 UiKind，孩子 Arc 按种类移入一次。
let kind = match &data.kind {
Kind::Text { value, size, color } => {
// 旧 textOf 路径按实际源字段提取字符串。属性路径中间对象用整对象依赖，末端用字段依赖。
// text_binding 兼容路径动态读取其源值，普通文字则采用已解码的 text 字段副本。
let value = if let Some((source, field)) = &data.text_binding {
// 源属性可能经过共享转发链，各中间身份变化都可能改变最后读取的值。
let storage = store.attribute_path(*source)?;
// 中间节点登记 Contents，只有末端属性存储用精确字段名，兼顾转发变更与精确失效。
for (index, object) in storage.iter().enumerate() {
dependencies.push(Dependency {
object: *object,
property: (index + 1 == storage.len()).then(|| field.clone()),
});
}
// 按源 Value 类型转换显示文本，对象 str 还需登记该对象内容依赖。
match store.get_attr(*source, field)? {
Value::Nil => "nil".into(),
Value::Bool(v) => v.to_string(),
@@ -327,6 +400,7 @@ impl RenderCache {
color: color.clone(),
}
}
// 矩形只复制自然视觉数据，实际出现宽高由后续布局决定。
Kind::Rect {
width,
height,
@@ -338,6 +412,7 @@ impl RenderCache {
radius: *radius,
color: color.clone(),
},
// 滚动视口快照保存尺寸/轴与原生孩子，不保存每个 Mount 的偏移。
Kind::Scroll { width, height } => UiKind::Scroll {
axis: data.scroll_axis,
width: *width,
@@ -346,7 +421,9 @@ impl RenderCache {
gap: data.gap,
children,
},
// 间距叶节点无需组成快照，保留自然尺寸供布局使用。
Kind::Spacer(size) => UiKind::Spacer(*size),
// 三维 View 和面板尺寸与内容孩子一同发布，缺失 View 必须报错。
Kind::Viewport3D { width, height } => UiKind::Viewport3D {
width: *width,
height: *height,
@@ -355,6 +432,7 @@ impl RenderCache {
panels: panel_sizes,
children,
},
// 二维有限视口保存已解码 Camera2D 值与 Scene2D 孩子，后续投影不再查询 VM。
Kind::CanvasViewport { width, height } => UiKind::CanvasViewport {
width: *width,
height: *height,
@@ -371,42 +449,50 @@ impl RenderCache {
.children
.iter()
.map(|child| {
// Scene2D 的每个孩子可能是别名，先解析当前 Data 再读取经过属性覆盖的位置。
let (_, child) = block::resolve(store, child.block)?;
Ok(block::visual_data(store, child)?.position)
})
.collect::<Result<Vec<_>, VmError>>()?,
children,
},
// Overlay 各孩子叠放在相同内容区域，不携带 Row/Column 线性 gap 策略。
Kind::Overlay => UiKind::Overlay {
padding: data.padding,
children,
},
// 普通 Row 保留 padding/gap 与有序孩子，位置由布局计算。
Kind::Row => UiKind::Row {
padding: data.padding,
gap: data.gap,
children,
},
// 兼容 canvas Page 与 Scene2D 一样提取业务位置，表面 pan/zoom 另在 UiNode 上保存。
Kind::Page if data.surface.mode == crate::page::Mode::Canvas => UiKind::Canvas {
positions: data
.children
.iter()
.map(|child| {
// 旧 Page canvas 同样取每个出现对应业务子的当前 x/y，不把父排列结果当作世界位置。
let (_, data) = block::resolve(store, child.block)?;
Ok(block::visual_data(store, data)?.position)
})
.collect::<Result<Vec<_>, VmError>>()?,
children,
},
// 旧横向页面模式复用 Row 内容布局，页面表面元信息仍独立保留。
Kind::Page if data.surface.mode == crate::page::Mode::Horizontal => UiKind::Row {
padding: data.padding,
gap: data.gap,
children,
},
// Column 和其余旧页面模式使用纵向内容排列。
Kind::Column | Kind::Page => UiKind::Column {
padding: data.padding,
gap: data.gap,
children,
},
// 按钮作为带默认视觉/事件语义的容器保留孩子与内边距。
Kind::Button => UiKind::Button {
padding: data.padding,
gap: data.gap,
@@ -416,6 +502,7 @@ impl RenderCache {
// 统一外层样式与交互标志。UiKind 只表示具体内容，UiNode 保存所有类别共享的视觉元信息。
let next = UiNode {
surface: matches!(data.kind, Kind::Page).then(|| {
// 仅 Page 附带表面快照，补入公开页面身份文本而非持有 VM 引用。
let mut surface = data.surface.clone();
surface.page = block.to_string();
surface
@@ -443,7 +530,9 @@ impl RenderCache {
kind,
};
// 即使本次重算结果相同，也要重新登记依赖。shallow_eq 相同时复用旧 Arc，减少下游无效重建。
// 撤销旧依赖/父边，即使浅层视觉结果相等也必须按本轮读取重新登记。
let old = self.remove(block);
// 结果浅相等才复用旧 Arc，减少下游无效工作；变化结果建立新不可变节点。
let node = if let Some(old) = old.as_ref().filter(|old| old.node.shallow_eq(&next)) {
old.node.clone()
} else {
@@ -452,16 +541,20 @@ impl RenderCache {
// 同一属性可能由不同提取路径重复读取，排序去重后再建立反向边。
dependencies.sort_unstable();
dependencies.dedup();
// 保留孩子业务身份用于父链反向索引，与 UiKind 内的原生 Arc 拥有关系分开。
let child_refs: Vec<_> = data.children.iter().map(|child| child.block).collect();
// 为每个去重读取键登记当前 Block，供下个 VM ChangeBatch 找到首批失效者。
for source in &dependencies {
self.dependents
.entry(source.clone())
.or_default()
.insert(block);
}
// 每个共享孩子可有多个父，子项失效时需要沿所有父边传播脏标记。
for child in &child_refs {
self.parents.entry(*child).or_default().insert(block);
}
// 节点和全部反向边建立后才安装新条目，最后清 dirty 并把结果交回后序栈。
self.entries.insert(
block,
Cached {