merge: resolve manuscript conflicts with latest main comments

This commit is contained in:
2026-11-12 11:11:00 +08:00
123 changed files with 2699 additions and 253 deletions
+23 -2
View File
@@ -18,15 +18,20 @@ use crate::{block, event_dispatch::Subscription, ui_bridge::attach_desktop_type}
#[derive(Debug, Clone)]
/// 上次绑定计算的读取观察,用于判断是否需要重新执行源计算。
struct Cached {
// 每项保存读取对象/属性的版本观察;刷新时向对象存储核对,而非复制业务值。
reads: Vec<endor_core::ReadDependency>,
// 只借用上次结果的身份做相等比较;不能解引用其中可能已被回收的对象。
output: Value,
}
#[derive(Debug, Clone)]
/// 托管属性连接,强持有计算/目标所需引用,并保留只读计算的版本缓存。
pub struct Binding {
// 目标属性名;目标 Block 通过 bindings 列表拥有本连接。
field: String,
// Some 表示连接有效且拥有计算函数;取消/替换后置 None,让 trace 停止保活函数。
pub compute: Option<ObjectRef>,
// payload 克隆共享同一缓存,刷新局部副本也能更新缓存;首次计算前为 None。
reads: Arc<Mutex<Option<Cached>>>,
}
impl ObjectPayload for Binding {
@@ -58,12 +63,13 @@ pub fn connect(
compute: ObjectRef,
desktop: ObjectRef,
) -> Result<ObjectRef, VmError> {
// 在触碰连接列表前拒绝非法名称,尤其禁止绑定运行时类型属性。
if field.is_empty() || field.len() > 128 || field == "type" {
return Err(VmError::InvalidArgument("invalid binding property"));
}
let (reference, data) = block::resolve(cx.store(), target)?;
let mut data = data.clone();
// Only actual fields can be bound; method names are not writable targets.
// 只允许属性存储里已存在的字段;方法名即使可读取,也不能作为绑定写入目标。
let properties = data
.properties
.ok_or(VmError::InvalidArgument("missing property storage"))?;
@@ -73,6 +79,7 @@ pub fn connect(
"binding compute must be a Function",
));
}
// 刷新统一以零参数调用 compute,因此必须有参数元数据并且接受零实参。
if !cx
.store()
.call_arity(compute)?
@@ -85,6 +92,8 @@ pub fn connect(
"binding compute requires zero unbound parameters",
));
}
// 同一字段只保留一个有效计算。其他字段连接沿用;旧同字段连接失效并清缓存,
// 使外部仍持有的 Subscription 不会继续驱动被替换的计算。
let mut retained = vec![];
for connection in &data.bindings {
let mut binding = cx
@@ -112,11 +121,12 @@ pub fn connect(
})?;
retained.push(connection);
data.bindings = retained;
// Generic text bindings replace the legacy textOf derivation.
// text 改由通用绑定负责后,清除旧 textOf 推导入口,避免两套机制竞争同一属性。
if field == "text" {
data.text_binding = None;
}
cx.replace_payload(reference, data)?;
// 返回的取消令牌仅弱引用连接;连接生命期由目标 Block 的 bindings 决定。
let token = cx.allocate(Subscription {
connection: cx.store().downgrade(connection)?,
})?;
@@ -130,14 +140,17 @@ pub fn refresh(
nodes: &[WeakObjectRef],
host_desktops: &HashSet<ObjectRef>,
) -> Result<usize> {
// work 跨所有轮次累计。属性 A 的写入可能使已检查的 B 失效,所以不能只扫描一次。
let mut work = 0;
loop {
let mut evaluated = false;
// 每轮按解析后的真实 Block 身份去重,多个包装对象共享数据时只处理一次。
let mut seen = HashSet::new();
for weak in nodes {
let Some(target) = vm.upgrade(*weak)? else {
continue;
};
// 用闭包暂存失败,让下方 release 无论处理成功与否都能释放 upgrade 的强引用。
let result: Result<()> = (|| {
let (reference, data) = block::resolve(vm.object_store(), target)?;
if !seen.insert(reference) {
@@ -154,6 +167,8 @@ pub fn refresh(
.lock()
.map_err(|_| anyhow::anyhow!("binding cache poisoned"))?
.clone();
// 两项都成立才能跳过:读取依赖版本未变,且目标仍等于上次输出。
// 后一项让外部直接改写目标后,绑定仍能恢复其计算值。
if cached.as_ref().is_some_and(|cached| {
cached
.reads
@@ -165,11 +180,13 @@ pub fn refresh(
}) {
continue;
}
// 防止相互写入的绑定持续振荡;预算跨轮累计,超限向宿主报告不稳定。
work += 1;
if work > 10_000 {
bail!("property bindings did not stabilize within the execution budget");
}
evaluated = true;
// 计算阶段禁止写入,精确记录本次实际读取;单次调用另设帧数与指令上限。
let (value, reads) = vm
.call_read_only_precise_with_limits(
compute,
@@ -181,12 +198,14 @@ pub fn refresh(
)
.map_err(|error| crate::endor_host::runtime_error(vm, error))?;
let applied: Result<()> = (|| {
// 宿主桌面对象不纳入此缓存依赖;保留业务读取,避免宿主发布状态驱动重算。
let reads = reads
.dependencies
.into_iter()
.filter(|read| !host_desktops.contains(&read.object()))
.collect();
let (_, data) = block::resolve(vm.object_store(), target)?;
// 先在数据副本上验证属性类型/范围,验证通过后才写回托管属性。
block::apply_visual_property(&mut data.clone(), &binding.field, &value)?;
if vm.get_attr(target, &binding.field)? != value {
vm.set_attr(target, &binding.field, value.clone())?;
@@ -201,6 +220,7 @@ pub fn refresh(
});
Ok(())
})();
// 缓存不拥有输出对象;释放调用返回值后再传播应用错误,避免失败路径漏引用。
vm.release_value(value)?;
applied?;
}
@@ -209,6 +229,7 @@ pub fn refresh(
vm.release(target)?;
result?;
}
// 整轮无需计算才达到固定点;即使某次计算输出未变,也再扫描一轮确认依赖有效。
if !evaluated {
return Ok(work);
}
+45 -3
View File
@@ -13,6 +13,7 @@ use crate::ui_bridge::UiNode;
#[derive(Debug, Clone)]
/// 稳定组成 slot 与子 Block 的配对;slot 不依赖孩子当前的屏幕位置。
pub struct Child {
// slot 标识父组件中这条组成边,移动行序不改变它;同一 Block 可通过不同 slot 出现多次。
pub slot: u64,
pub block: ObjectRef,
}
@@ -57,6 +58,7 @@ pub enum Kind {
#[derive(Debug, Clone)]
/// 对共享 Cell 的稳定包装。赋值可让所有别名一起改指向,而每次出现的 Mount 仍独立。
pub struct Block {
// 共享赋值单元 Cell;其值可为最终 Data 或另一个 Block,从而保留别名身份并转发属性/类型查询。
pub state: ObjectRef,
pub page: bool,
pub tasks: Option<ObjectRef>,
@@ -72,6 +74,7 @@ impl ObjectPayload for Block {
let Value::Object(value) = store.cell_get(self.state)? else {
return Err(VmError::InvalidArgument("Block state is not an object"));
};
// 若 Cell 指向替代 Block,将属性查询继续转发;否则读取 Data.properties 的普通托管字段。
if store.object(value)?.payload().as_any().is::<Block>() {
Ok(Some(value))
} else {
@@ -94,6 +97,7 @@ impl ObjectPayload for Block {
Ok(Some(value))
} else {
store.payload::<Data>(value, "Block data")?;
// 到达最终 Data 时停止类型转发,使用当前 Block 自身名义类型;只有替换为其他 Block 才继续转发类型。
Ok(None)
}
}
@@ -126,11 +130,13 @@ impl ObjectPayload for Block {
if !store.object(source)?.payload().as_any().is::<Self>() {
return Ok(None);
}
// Page 与普通组件不能交叉共享赋值,防止把窗口/页面生命周期能力替换成普通叶组件。
if store.payload::<Self>(source, "Block")?.page != self.page {
return Err(VmError::InvalidArgument(
"Page assignment requires another Page",
));
}
// 建立转发前检查源展开图不能回到本 Cell,禁止共享赋值在别名或组成关系中形成环。
validate(store, source, Some(self.state))?;
Ok(Some(self.state))
}
@@ -150,6 +156,7 @@ pub struct Data {
pub align_self: Option<crate::layout::CrossAlign>,
pub margin: crate::layout::Insets,
pub sizing: crate::box_model::Sizing,
// 四边覆盖顺序为上、右、下、左;None 表示回退统一 padding,不等于零。
pub padding_edges: [Option<f32>; 4],
pub border: crate::layout::Insets,
pub border_color: String,
@@ -160,19 +167,23 @@ pub struct Data {
pub scroll_axis: crate::scroll::Axis,
pub position: [f32; 2],
pub surface: crate::page::Surface,
// 下次插入的单调 slot,初始孩子按 0..len 编号,后续重排不把旧 slot 重新编号。
pub next_slot: u64,
// Page 导航历史是真实托管拥有边;后退/前进可重新展示同一个对象,而非复制快照。
pub history: Vec<ObjectRef>,
pub history_index: usize,
pub bindings: Vec<ObjectRef>,
pub text_binding: Option<(ObjectRef, String)>,
pub click: Option<ObjectRef>,
pub subscriptions: Vec<ObjectRef>,
// 源可读写的视觉字段存储;Data 自身保存结构边与构造默认值,提取时再将当前属性覆盖到派生副本。
pub properties: Option<ObjectRef>,
}
impl Data {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 建立组件业务描述,为初始孩子分配稳定 slot,并初始化无绑定、无订阅的默认布局策略。
pub fn new(kind: Kind, children: Vec<ObjectRef>, padding: f32, gap: f32) -> Self {
// 先为输入孩子分配稳定 slot,next_slot 从当前长度继续,后续追加不会复用被删除条目的编号。
let next_slot = children.len() as u64;
Self {
kind,
@@ -215,6 +226,7 @@ impl Data {
}
/// 检查原生组件种类是否承载子组成,供树修改和布局选择使用。
pub fn is_container(&self) -> bool {
// 这些类别允许通过通用 Children 方法编辑;Viewport3D 的面板内容来自 Scene3D 提取,不是普通 children 列表。
matches!(
self.kind,
Kind::Row
@@ -244,6 +256,7 @@ impl ObjectPayload for Data {
}
/// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。
fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
// 所有结构字段中出现的托管强引用必须枚举:场景/相机、属性存储、孩子、历史、绑定、订阅和回调。
if let Some(scene) = self.scene3d {
visit(scene);
}
@@ -280,15 +293,18 @@ impl ObjectPayload for Data {
/// 分配 Data、共享 Cell 和 Block 包装,并让托管图拥有必要引用。
pub fn allocate(cx: &mut NativeContext<'_>, mut data: Data) -> Result<ObjectRef, VmError> {
let page = matches!(data.kind, Kind::Page);
// 分配拥有边前检查每个孩子都是有效有限 Block 图;非法组成直接失败,不截断部分 UI。
for child in &data.children {
validate(cx.store(), child.block, None)?;
}
// 把原生默认参数显式写成普通属性,使源赋值、绑定及精确依赖跟踪观察到同一存储。
let properties = cx.new_object()?;
for (name, value) in native_properties(&data) {
cx.set_attr(properties, name, value)?;
}
data.properties = Some(properties);
let data = cx.allocate(data)?;
// 最终建立 Block -> Cell -> Data -> properties/children 拥有链,均在 VM 中参与追踪和循环回收。
let state = cx.new_cell(Some(Value::Object(data)))?;
cx.allocate(Block {
state,
@@ -314,6 +330,7 @@ pub fn resolve_tracked(
let mut seen = std::collections::HashSet::new();
let mut dependencies = Vec::new();
loop {
// 解析整条转发路径防环;依赖收集同时记录每层 Block 与 Cell,任一转发变更都会让视觉缓存失效。
if !seen.insert(current) {
return Err(VmError::InvalidArgument("cyclic Block reference"));
}
@@ -322,6 +339,7 @@ pub fn resolve_tracked(
let Value::Object(value) = store.cell_get(state)? else {
return Err(VmError::InvalidArgument("Block state is not an object"));
};
// 遇到 Data 返回最终存储身份与借用引用;否则下一轮要求该值必须是 Block,不接受任意对象。
if store.object(value)?.payload().as_any().is::<Data>() {
dependencies.push(value);
return Ok((
@@ -336,7 +354,7 @@ pub fn resolve_tracked(
/// Validate the entire finite expansion before establishing a new composition
/// edge. The node count is an explicit rejected resource quota, not truncated UI.
/// 检查当前输入或发布值的不变量,调用方据校验结果决定是否继续。
/// 完整展开 Block/Cell/孩子图,拒绝环、禁止目标回边及超过 10000 次展开的组成。
pub fn validate(
store: &ObjectStore,
root: ObjectRef,
@@ -356,11 +374,13 @@ pub fn validate(
path.remove(&state);
}
Step::Enter(block) => {
// 预算按实际展开次数而非不同对象数计算,共享子树重复出现也计入资源工作量。
visits += 1;
if visits > 10_000 {
return Err(VmError::ExecutionLimit("expanded Block graph"));
}
let state = store.payload::<Block>(block, "Block")?.state;
// path 只追踪当前祖先 Cell,允许其他分支共享同一组件;forbidden_state 额外阻止新边回到将被修改的目标。
if forbidden_state == Some(state) || !path.insert(state) {
return Err(VmError::InvalidArgument(
"Block composition would create a cycle",
@@ -375,6 +395,7 @@ pub fn validate(
"Block composition would create a cycle",
));
}
// Data 展开孩子,非 Data 则沿共享赋值转发链继续;显式 Exit 在子树完成后清除祖先标记。
if let Ok(data) = store.payload::<Data>(value, "Block data") {
for child in data.children.iter().rev() {
work.push(Step::Enter(child.block));
@@ -388,8 +409,9 @@ pub fn validate(
Ok(())
}
/// 将当前托管或可变状态提取为后续阶段使用的派生表示。
/// 用一次性空 RenderCache 提取不可变视觉树;不跨调用保存快照缓存。
pub fn snapshot(store: &ObjectStore, root: ObjectRef) -> Result<Arc<UiNode>, VmError> {
// 一次性提取使用空缓存,不保留跨调用结果;有增量复用需求的窗口应使用自己的 RenderCache。
crate::snapshot::RenderCache::default().snapshot(store, root)
}
@@ -401,6 +423,7 @@ pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
fn number(value: f32) -> Value {
Value::Number((value as f64).into())
}
// 先枚举每种 Block 都有的定位、弹性、盒尺寸、边框与对齐属性,再按 kind 增补专有字段。
let mut fields = vec![
("x", number(data.position[0])),
("y", number(data.position[1])),
@@ -455,6 +478,7 @@ pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
{
fields.push((
name,
// 单边 padding 的 auto 编码成文本,不用数值哨兵,读取时才能区分“继承统一值”和显式零。
edge.map_or_else(|| Value::Text("auto".into()), number),
));
}
@@ -505,6 +529,7 @@ pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
Kind::Spacer(size) => fields.push(("size", number(*size))),
_ => {}
}
// 容器才暴露统一 padding/gap 与主交叉轴策略;叶节点不因同名自定义字段被当成通用容器。
if data.is_container() {
fields.extend([
("padding", number(data.padding)),
@@ -518,6 +543,7 @@ pub fn native_properties(data: &Data) -> Vec<(&'static str, Value)> {
/// 复制原生描述并用当前托管属性覆盖它;结果只用于展示,不反向修改业务对象。
pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
// 只改本轮派生副本,逐个读取实际属性并验证;读取字段名集合来自 native_properties,不遍历任意用户字段。
let mut data = data.clone();
let properties = data
.properties
@@ -526,6 +552,7 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
let value = store.get_attr(properties, name)?;
apply_visual_property(&mut data, name, &value)?;
}
// 各单值合法仍可能存在跨字段矛盾,必须在全部覆盖完成后校验 min/max 关系。
if data.flex_policy.min > data.flex_policy.max {
return Err(VmError::InvalidArgument("flexMin exceeds flexMax"));
}
@@ -541,6 +568,7 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
"CanvasViewport requires a Camera2D",
))?,
)?;
// CanvasViewport 只容纳一个 Scene2D 根,允许其内部无限空间布局,但不接受多个普通孩子冒充场景。
if data.children.len() != 1
|| !matches!(
resolve(store, data.children[0].block)?.1.kind,
@@ -558,6 +586,7 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
let definition = store.type_of(controller)?.ok_or(VmError::InvalidArgument(
"3D controller requires a nominal update method",
))?;
// 3D 控制器要求名义类型上的 update,接受含接收者在内三参;调用执行与预算在输入分发路径处理。
let method = store
.lookup_method(definition, "update")?
.ok_or(VmError::InvalidArgument(
@@ -578,6 +607,7 @@ pub fn visual_data(store: &ObjectStore, data: &Data) -> Result<Data, VmError> {
/// 按属性名检查和解码源值,再更新对应视觉字段;非法尺寸、枚举或颜色被拒绝。
pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Result<(), VmError> {
let bad = || VmError::InvalidArgument("invalid native visual property");
// 常规视觉长度/系数只接受非负有限值;坐标和 pan 在下面走允许负数的独立路径。
let number = || -> Result<f32, VmError> {
let Value::Number(value) = value else {
return Err(bad());
@@ -588,6 +618,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
}
Ok(n)
};
// x/y 对所有组件生效;页面 pan/zoom 只作用 Page。这里不是任意字段存在性校验,不适用种类会跳过更新。
if matches!(name, "x" | "y" | "panX" | "panY" | "zoom") {
let n = crate::scroll::coordinate(value)?;
match name {
@@ -596,6 +627,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
"panX" if matches!(data.kind, Kind::Page) => data.surface.pan.x = n,
"panY" if matches!(data.kind, Kind::Page) => data.surface.pan.y = n,
"zoom" if matches!(data.kind, Kind::Page) => {
// Page 兼容相机缩放范围不同于独立 Camera2D 的 0.01..100,保持两套源协议各自限制。
if !(0.1..=4.0).contains(&n) {
return Err(invalid_zoom());
}
@@ -613,6 +645,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
return Ok(());
}
match name {
// controller 接受对象或明确的字符串 none,不能拿 Nil 隐式取消;后续 visual_data 检查其名义方法。
"controller" if matches!(data.kind, Kind::Viewport3D { .. }) => {
data.controller = match value {
Value::Object(controller) => Some(*controller),
@@ -621,6 +654,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
};
return Ok(());
}
// camera/scene 这里仅检查 Object 并记录身份,实际 payload/结构验证由各视口快照入口继续执行。
"camera"
if matches!(
data.kind,
@@ -647,6 +681,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
"paddingBottom" => 2,
_ => 3,
};
// 单边 auto 清除覆盖值;数值零保留 Some(0),从而确实覆盖统一 padding。
data.padding_edges[index] = if matches!(value, Value::Text(text) if text == "auto") {
None
} else {
@@ -682,6 +717,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
let Value::Text(overflow) = value else {
return Err(bad());
};
// overflow 只切换可见/裁剪,不暗中启用滚动;需要偏移与输入消费必须使用 ScrollBlock。
data.clip_children = match overflow.as_str() {
"clip" => true,
"visible" => false,
@@ -733,6 +769,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
data.margin.left = number()?;
return Ok(());
}
// basis 的 Nil 与 auto 都表示内容基准;其他值使用非负长度检查。flexMin/Max 的相互关系在完整提取后验证。
"flexBasis" => {
data.flex_policy.basis = if matches!(value, Value::Nil)
|| matches!(value, Value::Text(text) if text == "auto")
@@ -762,6 +799,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
return Ok(());
}
let container = data.is_container();
// alignSelf 可由任何孩子独立声明,crossAlign 只解释容器配置;auto 恢复继承父交叉轴策略。
if name == "alignSelf" || (container && name == "crossAlign") {
let Value::Text(value) = value else {
return Err(bad());
@@ -793,6 +831,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
let Value::Text(value) = value else {
return Err(bad());
};
// 文本属性按 UTF-8 字节设 16 KiB 上限,防止单个 Block 超过原生视觉文本预算。
if value.len() > 16_384 {
return Err(bad());
}
@@ -800,6 +839,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
}
(Kind::Text { size, .. }, "size") => {
let n = number()?;
// Text size 是 1..8 的离散倍率,不能把任意浮点字号通过 as u32 悄悄截断。
if !(1.0..=8.0).contains(&n) || n.fract() != 0.0 {
return Err(bad());
}
@@ -809,6 +849,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
let Value::Text(value) = value else {
return Err(bad());
};
// 颜色赋值先验证文本格式再替换派生颜色,避免错误字符串进入软件渲染器。
crate::document::parse_color(value).map_err(|_| bad())?;
color.clone_from(value);
}
@@ -824,6 +865,7 @@ pub fn apply_visual_property(data: &mut Data, name: &str, value: &Value) -> Resu
(Kind::Rect { height, .. }, "height") => *height = number()?,
(Kind::Rect { radius, .. }, "radius") => *radius = number()?,
(Kind::Spacer(size), "size") => *size = number()?,
// 剩余 kind 专有尺寸与容器字段按各自规则覆盖;未知字段忽略,不在此处删除或修改用户自定义属性。
(_, "padding") if container => data.padding = number()?,
(_, "gap") if container => data.gap = number()?,
_ => {}
+45 -3
View File
@@ -49,8 +49,9 @@ impl Default for NamespaceState {
}
impl NamespaceState {
/// 仅接收当前 session 的纯数据窗口命令,并按种类合并同资源的重复请求。
/// 在成功发布边界切换到指定 session,并按动作类别合并窗口命令;世代变化时丢弃旧命令。
pub fn publish_window_commands(&mut self, session: u64, commands: Vec<crate::window::Command>) {
// 跨运行时世代先丢弃旧命令,并去除旧副窗口视口记录;主壳窗口可跨 VM 替换继续存在。
if self.runtime_session != session {
self.window_commands.clear();
// The primary shell survives VM replacement. Secondary native
@@ -59,10 +60,12 @@ impl NamespaceState {
.retain(|id, _| *id == crate::window::MAIN_WINDOW);
}
self.runtime_session = session;
// 零表示无有效 VM 会话,清空传输请求并忽略传入命令,不能让退役结果重新控制窗口。
if session == 0 {
self.window_commands.clear();
return;
}
// 本方法接纳传入 session 作为当前世代,调用方负责只在成功发布边界调用;同资源同动作保留最新请求。
for command in commands {
self.window_commands
.retain(|old| !old.command.same_kind(&command));
@@ -95,13 +98,14 @@ impl NamespaceState {
Ok(Some(revision))
}
/// 清空本对象维护的当前内容或缓存,后续状态由调用方重新建立。
/// 推进提交身份和发布版本,替换为空文档并清除运行时命令,使旧提交不能覆盖清空结果。
pub fn clear(&mut self) -> Result<u64> {
let submission = self.next_submission()?;
let revision = self
.revision
.checked_add(1)
.context("revision counter exhausted")?;
// 先算好 submission 与 revision,任一溢出都不改状态;清空显示同时使旧异步发布失去提交资格。
self.submission = submission;
self.document = RenderDocument::default();
self.runtime_session = 0;
@@ -117,6 +121,7 @@ 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)]
pub source: String,
@@ -129,6 +134,7 @@ pub struct RenderDocument {
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)
@@ -144,6 +150,7 @@ impl RenderDocument {
if self.windows.len() > 15 {
bail!("too many window projections");
}
// 副窗口只允许一层投影,键须等于其 frame.window,不能重复嵌入主窗口或再带嵌套 windows。
for (id, document) in &self.windows {
if *id == crate::window::MAIN_WINDOW
|| *id != document.frame.window
@@ -164,6 +171,7 @@ impl RenderDocument {
bail!("invalid window identity");
}
parse_color(&self.frame.background)?;
// 空平行表是兼容的“全部无 clip/view”;一旦非空就必须与 commands 等长,禁止半张索引表。
if !self.frame.command_clips.is_empty()
&& self.frame.command_clips.len() != self.frame.commands.len()
{
@@ -188,6 +196,7 @@ impl RenderDocument {
if self.frame.mounts.len() > 10_000 {
bail!("frame exceeds the 10000 mount limit");
}
// 标签 ID 必须非零且唯一,最多一个活动页;标题按 UTF-8 字节限长,标签数受 MAX_PAGES 限制。
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
@@ -199,6 +208,7 @@ impl RenderDocument {
{
bail!("invalid tab projection");
}
// 先收集全部 Mount ID 并校验几何,再第二遍核对关系下标,允许链接指向帧中较后位置。
let mut mount_ids = HashSet::new();
for mount in &self.frame.mounts {
if mount.view.is_some_and(|view| !view.valid()) {
@@ -214,6 +224,7 @@ impl RenderDocument {
if let Some(clip) = mount.viewport_clip {
validate_rect(clip[0], clip[1], clip[2], clip[3], 0.0)?;
}
// 滚动投影为 [x,y,maxX,maxY],四项有限非负且实际偏移不得大于对应最大偏移。
if let Some(scroll) = mount.scroll
&& (!scroll.iter().all(|n| {
n.is_finite() && (0.0..=crate::ui_bridge::MAX_DIMENSION as f32).contains(n)
@@ -223,6 +234,7 @@ impl RenderDocument {
bail!("invalid scroll projection");
}
}
// 此处只保证关系目标在帧内,不做完整树环/双向一致性验证;组成与生命周期层承担更强结构不变量。
for mount in &self.frame.mounts {
for linked in [mount.parent, mount.first_child, mount.next_sibling]
.into_iter()
@@ -234,6 +246,7 @@ impl RenderDocument {
}
}
// 携带本机视觉根时必须与第一个根出现的业务身份一致;反序列化无 ui_root 时跳过这项。
if let Some(root) = &self.ui_root
&& self
.frame
@@ -250,13 +263,15 @@ impl RenderDocument {
Ok(())
}
/// 校验文档后把逻辑绘制命令转换成给定设备比例的显示列表,应用变换与裁剪。
/// 将逻辑命令转换到设备比例并应用逐命令视图/裁剪;不自动调用 validate,发布入口须先校验。
pub fn display_list(&self, scale: f32) -> Result<DisplayList> {
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 {
list.push(DrawCommand::PushClip(scaled_rect(
clip[0], clip[1], clip[2], clip[3], scale,
@@ -270,6 +285,7 @@ impl RenderDocument {
.unwrap_or_default();
list.push(
command
// 均匀缩放包含字体、半径和描边,随后平移只改原点;不能把位移再乘一次 view.zoom。
.to_draw_command(scale * view.zoom)?
.translated(Point::new(view.x * scale, view.y * scale)),
);
@@ -277,6 +293,7 @@ impl RenderDocument {
list.push(DrawCommand::PopClip);
}
}
// 根层只绘制非面板的焦点框;面板内焦点已在 panel::compose 放入纹理,避免重复或脱离面板。
if let Some(focus) = frame
.focus
.and_then(|id| frame.mounts.iter().find(|m| m.id == id))
@@ -311,6 +328,7 @@ impl RenderDocument {
list.push(DrawCommand::PopClip);
}
}
// 故障提示最后追加在页面上方,只显示错误第一行;状态是否允许输入由 Frame.hit_test 等另行限制。
if let Some(error) = &frame.fault {
list.push(
RenderCommand::RoundedRect {
@@ -361,6 +379,7 @@ pub struct CodeNode {
impl CodeNode {
/// 检查当前输入或发布值的不变量,调用方据校验结果决定是否继续。
fn validate<'a>(&'a self, depth: usize, ids: &mut HashSet<&'a str>) -> Result<()> {
// 限制代码投影深度,避免递归查找/展示无界;同一 ids 集合跨所有分支检查全树 ID 唯一。
if depth > 64 {
bail!("architecture tree exceeds 64 levels");
}
@@ -370,6 +389,7 @@ impl CodeNode {
if !ids.insert(&self.id) {
bail!("duplicate architecture node id: {}", self.id);
}
// 零行号表示未提供来源;只有两端均非零时检查顺序,不把兼容缺失字段当非法。
if self.start_line > 0 && self.end_line > 0 && self.start_line > self.end_line {
bail!("invalid source range for node {}", self.id);
}
@@ -407,12 +427,14 @@ pub struct Frame {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
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")]
pub mounts: Vec<MountGeometry>,
#[serde(default)]
pub layout_version: u64,
#[serde(default)]
// 运行时世代与 layout_version 共同确定输入归属;仅布局版本相同不能跨 VM 接受事件。
pub session: u64,
#[serde(default)]
pub focus: Option<u64>,
@@ -449,6 +471,7 @@ impl Default for Frame {
/// 某次出现的几何与投影元数据。逻辑矩形不被相机直接改写,view/panel 保存通往视图空间的映射。
pub struct MountGeometry {
#[serde(default, skip_serializing_if = "Option::is_none")]
// 可嵌套的世界 UI 映射,把页面坐标还原到此出现所在面板纹理空间。
pub panel: Option<Arc<crate::scene3d::panel::Mapping>>,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub canvas_viewport: bool,
@@ -457,12 +480,14 @@ pub struct MountGeometry {
#[serde(default)]
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")]
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]>,
pub id: u64,
pub block_id: String,
@@ -487,17 +512,20 @@ impl MountGeometry {
}
/// 把页面指针转换为该出现的布局坐标,供 hitTest 和局部事件处理使用。
pub fn logical_point(&self, point: Point) -> Option<Point> {
// 先处理面板反投影及遮挡,再撤销二维 view,结果仍是布局空间绝对坐标,尚未减节点原点。
let point = self.view_point(point, true)?;
Some(self.view.unwrap_or_default().inverse(point))
}
/// 把视图位移换算成目标出现的局部位移,处理缩放与世界 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]);
}
let point = point?;
let current = self.view_point(Point::new(point[0], point[1]), false)?;
// 对 point 与 point+delta 分别投影,使用 clipped=false 允许捕获拖动越出面板;投影不可逆则返回 None。
let previous =
self.view_point(Point::new(point[0] + delta[0], point[1] + delta[1]), false)?;
Some([
@@ -510,6 +538,7 @@ impl MountGeometry {
let Some(point) = self.view_point(point, true) else {
return false;
};
// 节点矩形在逻辑布局空间检查,clip 在视图/面板纹理空间检查,不能将二者坐标混用。
let local = self.view.map_or(point, |view| view.inverse(point));
Rect::new(self.x, self.y, self.width, self.height).contains(local)
&& self.clip.is_none_or(|c| {
@@ -526,6 +555,7 @@ impl Frame {
.into_iter()
.map(|index| &self.mounts[index])
.find(|mount| {
// 二维视口可控制,三维视口还要求显式 camera_controls;命中外框之外,还须位于内容 viewport_clip。
(mount.canvas_viewport || mount.scene3d_viewport && mount.camera_controls)
&& mount.contains(point)
&& mount.viewport_clip.is_some_and(|clip| {
@@ -537,9 +567,11 @@ impl Frame {
}
/// 在无故障帧中按逆绘制顺序选中可交互的出现,空间索引只缩小候选。
pub fn hit_test(&self, point: Point) -> Option<&MountGeometry> {
// 故障帧不返回可交互目标,防止用户继续向已经停止的域发送页面点击。
if self.fault.is_some() {
return None;
}
// 索引只筛几何候选,返回最前景 interactive 出现;真正源 hitTest 协议由 worker 的 source_hit 再执行。
self.hit_index
.candidates(point, self.mounts.len())
.into_iter()
@@ -674,6 +706,7 @@ impl RenderCommand {
color,
} => {
validate_rect(*x, *y, *width, *height, *radius)?;
// 描边必须正且有限;具体半宽限制在软件渲染器处理,这里不要求描边小于矩形尺寸。
if !stroke_width.is_finite() || *stroke_width <= 0.0 {
bail!("stroke_width must be a positive finite number");
}
@@ -690,6 +723,7 @@ impl RenderCommand {
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]
@@ -776,6 +810,7 @@ impl RenderCommand {
size,
color,
wrap_bounds,
// 根据是否提供换行边界选择 WrappedText 或 Text;两者都使用同一等级字号与设备缩放。
} => match wrap_bounds {
Some([width, height]) => DrawCommand::WrappedText {
rect: scaled_rect(*x, *y, *width, *height, scale),
@@ -809,6 +844,7 @@ fn validate_rect(x: f32, y: f32, width: f32, height: f32, radius: f32) -> Result
if !x.is_finite() || !y.is_finite() || !width.is_finite() || !height.is_finite() {
bail!("rectangle values must be finite");
}
// 此基础检查只要求有限、非负几何与圆角,不加世界坐标绝对值上限;更严格范围由具体协议调用路径决定。
if width < 0.0 || height < 0.0 || !radius.is_finite() || radius < 0.0 {
bail!("rectangle dimensions and radius cannot be negative");
}
@@ -825,6 +861,7 @@ pub fn parse_color(value: &str) -> Result<Color> {
let hex = value
.strip_prefix('#')
.ok_or_else(|| anyhow::anyhow!("color must begin with #"))?;
// 先验证 ASCII 和精确长度,后面按字节区间切片才不会在多字节字符中间切开;不支持短色号或命名颜色。
if !hex.is_ascii() || (hex.len() != 6 && hex.len() != 8) {
bail!("color must use #RRGGBB or #RRGGBBAA");
}
@@ -833,6 +870,7 @@ pub fn parse_color(value: &str) -> Result<Color> {
parse(0..2)?,
parse(2..4)?,
parse(4..6)?,
// 顺序为 RRGGBBAA 而非 AARRGGBB,六位色号默认完全不透明。
if hex.len() == 8 { parse(6..8)? } else { 255 },
))
}
@@ -840,6 +878,7 @@ pub fn parse_color(value: &str) -> Result<Color> {
#[cfg(test)]
mod tests {
#[test]
/// 旧文字JSON缺wrap_bounds仍走不换行命令;合法边界随DPI缩放,负宽度在发布验证中拒绝。
fn text_wrap_bounds_validate_and_legacy_text_remains_unwrapped() {
let mut command: RenderCommand = serde_json::from_str(
r##"{"type":"text","x":0,"y":0,"value":"text","size":1,"color":"#000000"}"##,
@@ -865,6 +904,7 @@ mod tests {
use super::*;
#[test]
/// 默认空文档可通过验证且没有结构根/绘图命令,支持初始状态与清空发布。
fn empty_document_is_valid_and_blank() {
let document = RenderDocument::default();
document.validate().unwrap();
@@ -873,6 +913,7 @@ mod tests {
}
#[test]
/// 检查六位色默认alpha255,八位色按RRGGBBAA解码,避免将末尾透明度当成首通道。
fn parses_rgb_and_rgba_colors() {
assert_eq!(
parse_color("#102030").unwrap(),
@@ -889,6 +930,7 @@ mod tests {
mod window_projection_tests {
use super::*;
#[test]
/// 同会话窗口命令可累积,新会话发布先丢旧命令;clear重置runtime_session并清空所有原生命令。
fn replacement_and_reset_discard_old_window_projections() {
let mut state = NamespaceState::default();
let command = crate::window::Command {
+11 -1
View File
@@ -1,13 +1,23 @@
//! 模型层模块入口。包含托管业务对象、每次展示上下文、依赖缓存,以及交给窗口线程的发布值。
//!
// Module ownership follows the directory; crate-root aliases keep internal call sites stable.
// 目录确定模块归属;main 中的 crate 根别名保持内部调用路径稳定。
/// 维护托管属性绑定及其读依赖;计算结果写入目标,绑定令牌不应让隐藏目标意外常驻。
pub(crate) mod binding;
/// 定义托管视觉对象的业务状态、共享替换关系和容器子项;几何属于 Mount,不能写回共享 Block。
pub(crate) mod block;
/// 定义 GUI/HTTP 可见的完整发布文档和共享 namespace;跨线程传递拥有的数据,不传 VM 句柄。
pub(crate) mod document;
/// 维护对象在某个页面中的具体出现位置、稳定子槽与生命周期;同一对象可对应多个独立 Mount。
pub(crate) mod mount;
/// 将语言对象列表适配为宿主遍历与写入接口,保留托管身份并参与读取依赖跟踪。
pub(crate) mod object_list;
/// 按窗口管理页面展示上下文、Mount 准备与提交,分离业务对象寿命和一次展示的寿命。
pub(crate) mod presentation;
/// 提供托管视觉协议方法的解析/调用约定,让源覆盖与原生实现沿同一入口组合。
pub(crate) mod protocols;
/// 提取托管三维场景的节点、相机和材质;验证对象图并生成供纯数据渲染使用的场景快照。
pub(crate) mod scene3d;
/// 从托管对象提取展示快照与属性版本;快照是渲染输入,不承担源程序业务状态。
pub(crate) mod snapshot;
/// 管理 VM 内 Window/Page 资源关系、窗口命令与页面顺序,操作结果再由原生壳层执行。
pub(crate) mod window;
+58 -6
View File
@@ -26,7 +26,9 @@ pub struct Mount {
// 已发布几何与每次出现的滚动位置分开保存,同一 Block 的多个位置互不覆盖。
pub geometry: MountGeometry,
pub scroll_offset: [f32; 2],
// 最后同步的布局版本,Bounds 查询会一并返回,便于调用方识别几何属于哪轮发布。
pub version: u64,
// false 后禁止依赖当前几何的操作;外部即使还持有 Mount 对象也不能把它当活动出现。
pub mounted: bool,
// Mount 可以拥有任务;退役后任务交付还要检查 owner 是否仍有效。
pub tasks: Option<ObjectRef>,
@@ -53,6 +55,7 @@ impl ObjectPayload for Mount {
true
}
/// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。
// 仅 block 和 tasks 是 payload 的强拥有边;page/parent/child/sibling 是弱边,不参与 trace。
fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
visit(self.block);
if let Some(tasks) = self.tasks {
@@ -86,6 +89,7 @@ enum Query {
struct Method {
signature: endor_core::CallSignature,
owner: ObjectRef,
// 方法对象拥有 Mount,但不能经桌面反向保活整个窗口;需要桌面能力时再 upgrade。
desktop: WeakObjectRef,
query: Query,
}
@@ -95,7 +99,7 @@ impl NativeCallable for Method {
fn signature(&self) -> Option<endor_core::CallSignature> {
Some(self.signature.clone())
}
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 适配器已绑定 Mount;坐标测试/转换与scrollTo/By接受两个数,其余层次/几何/焦点查询零参。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(
if matches!(
@@ -114,9 +118,10 @@ impl NativeCallable for Method {
))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 读取具体出现位置,先检查仍挂载与几何可用性,再执行层次、坐标、焦点、滚动或拾取操作,避免使用已退役上下文。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
let mount = cx.store().payload::<Mount>(self.owner, "Mount")?.clone();
// 层次查询允许观察已经脱离的对象(通常得到 Nil);几何、焦点、滚动、拾取等必须仍挂接。
if !mount.mounted
&& matches!(
self.query,
@@ -135,6 +140,7 @@ impl NativeCallable for Method {
{
return Err(VmError::InvalidArgument("Mount is no longer attached"));
}
// 除 VM 元数据检查外入口再核对实际参数数目;二维坐标/位移操作取两个 Number,其余零参。
let arity = if matches!(
self.query,
Query::HitTest
@@ -153,6 +159,7 @@ impl NativeCallable for Method {
}
let value = match self.query {
Query::ToView | Query::ToLocal => {
// 布局期间几何尚未提交,坐标转换不能把临时 bounds 与上帧投影混用。
if mount.layout.is_some() {
return Err(VmError::InvalidArgument(
"coordinate conversion requires committed geometry",
@@ -164,6 +171,7 @@ impl NativeCallable for Method {
);
let point =
if matches!(self.query, Query::ToView) {
// ToView 先将局部点加节点原点,再套二维 view;若在世界面板内,还继续向外投影到页面。
let point = mount.geometry.view.unwrap_or_default().point(
crate::geometry::Point::new(
point.x + mount.geometry.x,
@@ -176,6 +184,7 @@ impl NativeCallable for Method {
.as_ref()
.map_or(Some(point), |panel| panel.project_point(point))
} else {
// ToLocal 先撤销面板和视图投影,再减节点几何原点;不可逆时返回 Nil,而非虚构坐标。
mount.geometry.logical_point(point).map(|point| {
crate::geometry::Point::new(
point.x - mount.geometry.x,
@@ -183,6 +192,7 @@ impl NativeCallable for Method {
)
})
};
// 转换成功才分配名义 Point;失败返回 Nil,不把无效数值写进结果属性。
if let Some(point) = point {
let result = cx.new_object()?;
let desktop = cx.upgrade(self.desktop)?.ok_or(VmError::InvalidArgument(
@@ -196,6 +206,7 @@ impl NativeCallable for Method {
Value::Nil
}
}
// 同一滚动入口区分绝对位置和相对增量,钳制、挂接状态与写屏障交由 scroll::set 统一执行。
Query::ScrollTo | Query::ScrollBy => {
crate::scroll::set(
cx,
@@ -231,6 +242,7 @@ impl NativeCallable for Method {
),
)?
}
// 返回帧中已钳制的有效位置与最大偏移,不直接暴露可能尚未投影的 scroll_offset 原值。
Query::ScrollPosition => {
let p = mount
.geometry
@@ -243,6 +255,8 @@ impl NativeCallable for Method {
Value::Object(result)
}
Query::Bounds => {
// 布局只读调用中可查询当前安排阶段的临时 bounds;测量时尚无 bounds,明确报错。
// 非布局期则读取最后提交的 MountGeometry。
let geometry = if let Some(layout) = &mount.layout {
layout
.lock()
@@ -260,6 +274,7 @@ impl NativeCallable for Method {
]
};
let bounds = cx.new_object()?;
// 从本方法返回签名取得 Bounds 的名义类型,避免生成一个仅字段相似的普通对象。
let endor_core::CallType::Single(endor_core::AnnotationType::Nominal(definition)) =
&self.signature.returns
else {
@@ -281,6 +296,7 @@ impl NativeCallable for Method {
)?;
Value::Object(bounds)
}
// 请求焦点先让出现进入可见范围,再检查可聚焦资格并写入桌面请求;后续发布负责实际生效。
Query::Focus => {
crate::scroll::into_view(cx, self.owner, self.desktop)?;
if !mount.geometry.interactive {
@@ -297,12 +313,14 @@ impl NativeCallable for Method {
cx.set_attr(desktop, "focusRequested", Value::Bool(true))?;
Value::Nil
}
// 这里是 Mount 已提交几何的 contains 查询;源 Block 的 hitTest 覆盖由 source_hit 驱动另行执行。
Query::HitTest => {
if mount.layout.is_some() {
return Err(VmError::InvalidArgument(
"Mount hitTest is unavailable during layout",
));
}
// 命中坐标只要求 Number 可转有限 f32;与 scroll::coordinate 不同,此处不限制绝对值至一百万。
let number = |value: &Value| -> Result<f32, VmError> {
let Value::Number(number) = value else {
return Err(VmError::InvalidArgument(
@@ -331,6 +349,7 @@ impl NativeCallable for Method {
Query::Page => mount.page,
_ => unreachable!(),
};
// 弱链接不存在或目标已回收都返回 Nil;升级本身失败才传播 VM 错误。
weak.map(|weak| cx.upgrade(weak))
.transpose()?
.flatten()
@@ -350,6 +369,7 @@ fn mount_signature(
) -> Result<endor_core::CallSignature, VmError> {
use endor_core::{AnnotationType as T, CallEffect, CallSignature, CallType};
let nominal = |name| crate::ui_bridge::desktop_type(store, name, desktop).map(T::Nominal);
// 层次、拾取和坐标转换可能没有结果,使用 nullable 名义类型;变更操作返回 Unit。
let returns = match query {
Query::Bounds => nominal("Bounds")?.into(),
Query::Parent | Query::FirstChild | Query::NextSibling => {
@@ -362,6 +382,7 @@ fn mount_signature(
Query::ScrollPosition => T::Any.into(),
_ => T::Unit.into(),
};
// 滚动、相机拟合和焦点会写业务/桌面属性,声明 Mutating;其余查询允许在只读协议中调用。
let effect = if matches!(
query,
Query::ScrollTo | Query::ScrollBy | Query::ScrollIntoView | Query::FitView | Query::Focus
@@ -391,6 +412,7 @@ fn mount_signature(
#[derive(Debug, Default, Clone)]
/// 活动出现的弱索引。真实托管拥有关系在 desktop 的挂载字典中,索引不能充当隐藏 GC 根。
pub struct MountTable {
// Mount ID 到托管弱身份,真实强拥有者是 desktop.mounts 字典;order 单独保存原布局顺序。
pub active: HashMap<u64, WeakObjectRef>,
order: Vec<u64>,
}
@@ -404,6 +426,7 @@ struct Sync {
old: HashMap<u64, WeakObjectRef>,
old_order: Vec<u64>,
frame: Frame,
// true 为布局准备阶段,安装临时 Context 并保留已有滚动偏移;false 为几何提交,清 Context。
preparing: bool,
output: Arc<Mutex<HashMap<u64, WeakObjectRef>>>,
}
@@ -417,13 +440,14 @@ struct LifecycleCall {
unmount: bool,
}
impl NativeCallable for LifecycleCall {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// Block、Mount 与用户钩子都已捕获,生命周期序列无参调用此适配器。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 卸载时先取消 Mount 所有任务,再以 Block/Mount 为实参请求 VM 执行用户 onMount/onUnmount,不在 Rust 中直接运行源体。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
// 用户 onUnmount 运行前先取消该出现拥有的任务,防止退役后继续交付旧工作。
if self.unmount {
crate::tasks::cancel_owner(cx, self.mount)?;
}
@@ -449,6 +473,7 @@ fn lifecycle_call(
.store()
.lookup_method(definition, name)?
.ok_or(VmError::InvalidArgument("Block has no lifecycle method"))?;
// 生命周期包装显式捕获函数、Block、Mount,使序列执行到回调前这些对象不会被回收。
cx.allocate(ContextNativeFunction::new(
name,
LifecycleCall {
@@ -462,13 +487,14 @@ fn lifecycle_call(
}
impl NativeCallable for Sync {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 展示同步步骤从捕获的帧与弱节点表读取输入,无需外部实参。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 把弱业务身份升级为本轮对象映射,再同步帧中出现位置到托管 Mount,建立结构/几何与待通知生命周期。
fn invoke(&self, cx: &mut NativeContext<'_>, _args: &[Value]) -> Result<NativeResult, VmError> {
// 帧只含 Block 字符串身份,先将弱节点表升级为本次同步可用的实际对象映射。
let mut blocks = HashMap::new();
for weak in &self.nodes {
if let Some(block) = cx.upgrade(*weak)? {
@@ -493,6 +519,7 @@ impl NativeCallable for Sync {
.map(|weak| cx.upgrade(*weak))
.transpose()?
.flatten();
// Mount ID 相同仍不足以复用:必须仍挂接、页面相同、真实 Block 相同,防止身份误归属。
let reusable = if let Some(old) = old {
let mount = cx.store().payload::<Mount>(old, "Mount")?;
(mount.mounted && mount.page == page && mount.block == block).then_some(old)
@@ -516,6 +543,7 @@ impl NativeCallable for Sync {
layout: None,
})?;
crate::ui_bridge::attach_desktop_type(cx, object, "Mount", self.desktop)?;
// 每个新 Mount 安装捕获自身的原生方法;captures 中只放 Mount,桌面仍保留弱身份。
for (name, query) in [
("bounds", Query::Bounds),
("scrollTo", Query::ScrollTo),
@@ -552,6 +580,7 @@ impl NativeCallable for Sync {
};
objects.insert(geometry.id, object);
}
// 先建立全部 Mount,再第二遍补链接,保证 parent/child/sibling 无论先后都能找到目标身份。
let root = cx.new_dict()?;
for geometry in &self.frame.mounts {
let object = objects[&geometry.id];
@@ -566,6 +595,7 @@ impl NativeCallable for Sync {
first_child: link(geometry.first_child)?,
next_sibling: link(geometry.next_sibling)?,
geometry: geometry.clone(),
// 准备阶段沿用用户滚动状态;提交阶段以帧中有效偏移为准,非滚动容器归零。
scroll_offset: if self.preparing {
cx.store().payload::<Mount>(object, "Mount")?.scroll_offset
} else {
@@ -573,6 +603,7 @@ impl NativeCallable for Sync {
},
version: self.frame.layout_version,
mounted: true,
// 临时 Context 只有原生派生数据,无托管根;提交时置 None,表示几何可供外部查询。
layout: if self.preparing {
Some(Arc::new(Mutex::new(crate::layout::Context::default())))
} else {
@@ -580,6 +611,7 @@ impl NativeCallable for Sync {
},
};
let old = cx.store().payload::<Mount>(object, "Mount")?;
// 只在上下文、几何、版本、链接或公开挂接属性确实需更新时替换 payload,减少无关变更日志。
if self.preparing
|| old.layout.is_some()
|| !old.mounted
@@ -602,6 +634,7 @@ impl NativeCallable for Sync {
Value::Number((self.frame.layout_version as i64).into()),
)?;
}
// 新字典逐项拥有活动 Mount;弱链接本身不负责让整棵出现树存活。
cx.dict_set(
root,
Value::Text(geometry.id.to_string()),
@@ -611,12 +644,14 @@ impl NativeCallable for Sync {
let mut hooks = Vec::new();
// Layout records are preorder; reversing guarantees children unmount
// before their parents. A Page change creates fresh Mount contexts.
// 旧帧按父先子后记录,逆序退役保证孩子 onUnmount 在父之前;复用对象不退役。
for id in self.old_order.iter().rev() {
let weak = self.old[id];
if let Some(object) = cx.upgrade(weak)?
&& objects.get(id) != Some(&object)
{
let mut mount = cx.store().payload::<Mount>(object, "Mount")?.clone();
// 先撤销挂接和全部关系,再安排回调;onUnmount 不能继续使用失效几何或沿旧链操作。
mount.mounted = false;
mount.layout = None;
mount.parent = None;
@@ -627,9 +662,11 @@ impl NativeCallable for Sync {
hooks.push(lifecycle_call(cx, object, "onUnmount")?);
}
}
// 新建顺序沿帧先序,onMount 默认父先子后;全部旧退役回调排在新挂载回调之前。
for object in created {
hooks.push(lifecycle_call(cx, object, "onMount")?);
}
// 同步只返回生命周期序列,不在此处立即执行用户回调;调用方决定在后续阶段何时运行。
let driver = if hooks.is_empty() {
None
} else {
@@ -644,6 +681,7 @@ impl NativeCallable for Sync {
.into_iter()
.map(|(id, object)| Ok((id, cx.store().downgrade(object)?)))
.collect::<Result<HashMap<_, _>, VmError>>()?;
// 先让桌面拥有新字典,再公布原生弱索引;返回的驱动保持待退役对象直到回调结束。
cx.set_attr(self.desktop, "mounts", Value::Object(root))?;
*self
.output
@@ -661,6 +699,7 @@ impl NativeCallable for Sync {
pub struct Checkpoint {
table: MountTable,
dictionary: Option<ObjectRef>,
// 保存 payload 与 mounted/layoutVersion 两项公开属性;None 表示原先没有属性,回滚要删除。
states: Vec<(ObjectRef, Mount, Option<Value>, Option<Value>)>,
roots: Vec<ObjectRef>,
}
@@ -669,6 +708,7 @@ impl Checkpoint {
/// 释放检查点为回滚临时保留的托管根,成功提交后不再需要这些引用。
pub fn release(self, vm: &mut Vm) -> Result<(), VmError> {
let mut result = Ok(());
// 逆序释放所有临时根,单项失败仍继续尝试余下根,最终返回最后一次释放错误。
for root in self.roots.into_iter().rev() {
if let Err(error) = vm.release(root) {
result = Err(error);
@@ -685,6 +725,7 @@ impl Checkpoint {
table: &mut MountTable,
) -> Result<(), VmError> {
let result = (|| {
// 回滚先识别本轮新增的出现并将其脱离,再恢复原有 Mount payload、公开属性和桌面拥有字典。
let old: std::collections::HashSet<_> =
self.states.iter().map(|state| state.0).collect();
for weak in table.ordered() {
@@ -702,6 +743,7 @@ impl Checkpoint {
}
Ok::<_, VmError>(())
})();
// 保存处理结果后先释放 upgrade 根,再传播处理错误,避免失败路径遗留临时强引用。
vm.release(object)?;
result?;
}
@@ -709,6 +751,7 @@ impl Checkpoint {
for (object, mount, mounted, version) in &self.states {
vm.replace_payload(*object, mount.clone())?;
for (name, value) in [("mounted", mounted), ("layoutVersion", version)] {
// 原属性存在则恢复旧值,不存在则 del_attr;已缺失可忽略,其余删除错误仍要传播。
if let Some(value) = value {
vm.set_attr(*object, name, value.clone())?;
} else {
@@ -730,6 +773,7 @@ impl Checkpoint {
*table = self.table.clone();
Ok(())
})();
// 恢复过程失败也要释放检查点根;先尝试两项操作,再按恢复错误优先的顺序返回。
let released = self.release(vm);
result?;
released
@@ -746,6 +790,7 @@ impl MountTable {
Err(error) => return Err(error),
};
let mut roots = Vec::new();
// 保留旧字典,避免准备阶段 desktop.mounts 换成新字典后旧出现提前回收,导致无法恢复。
if let Some(dictionary) = dictionary {
vm.retain(dictionary)?;
roots.push(dictionary);
@@ -759,6 +804,7 @@ impl MountTable {
let result = (|| {
for weak in self.ordered() {
if let Some(object) = vm.upgrade(weak)? {
// upgrade 已提供一个拥有根,直接记录待释放列表,不重复 retain;随后读取失败也会统一清理。
checkpoint.roots.push(object);
let mount = vm.payload::<Mount>(object, "Mount")?.clone();
let mut attributes = Vec::new();
@@ -768,6 +814,7 @@ impl MountTable {
Err(VmError::AttributeNotFound(_)) => None,
Err(error) => return Err(error),
};
// 公开属性理论上可能持有对象,快照保存 Value 本身不会自动增加 VM 根,须额外 retain。
if let Some(Value::Object(object)) = &value {
vm.retain(*object)?;
checkpoint.roots.push(*object);
@@ -784,6 +831,7 @@ impl MountTable {
}
Ok::<_, VmError>(())
})();
// 检查点创建到一半失败时释放已经取得的根,不返回一个不完整且可能泄漏的检查点。
if let Err(error) = result {
checkpoint.release(vm)?;
return Err(error);
@@ -811,6 +859,7 @@ impl MountTable {
result?;
}
}
// 故障退役不执行用户回调;将 desktop.mounts 换成空字典,再清除原生索引,撤销桌面拥有关系。
let dictionary = vm.new_dict()?;
let result = vm.set_attr(desktop, "mounts", Value::Object(dictionary));
vm.release(dictionary)?;
@@ -839,6 +888,7 @@ impl MountTable {
preparing: bool,
) -> Result<Option<ObjectRef>, VmError> {
let output = Arc::new(Mutex::new(HashMap::new()));
// 同步入口显式保活桌面与可选页面;旧表和节点表本身仍是弱索引,不增加隐式根。
let mut captures = vec![desktop];
captures.extend(page);
let function = vm.allocate(ContextNativeFunction::new(
@@ -855,9 +905,11 @@ impl MountTable {
},
captures,
))?;
// 先保存调用结果再释放同步入口,错误时同样清理;只有成功后才替换活动索引与顺序。
let result = vm.call(function, &[]);
vm.release(function)?;
let result = result?;
// 从共享输出移动弱表而不是克隆;生命周期驱动若存在则作为拥有结果交给调用方释放。
self.active = std::mem::take(
&mut *output
.lock()
+14 -6
View File
@@ -1,5 +1,5 @@
//! 给源协议返回的对象列表提供受控封装。列表内容通过托管引用被追踪,读方法只暴露检查后的条目。
//! 用于儿童组成、布局结果和几何输入等需要保留对象身份的场景;不是窗口线程共享的可变容器。
//! 用于子节点组成、布局结果和几何输入等需要保留对象身份的场景;不是窗口线程共享的可变容器。
//!
//! Managed indexed host results; values and the at method are traced edges.
use endor_core::{
@@ -46,16 +46,17 @@ impl NativeCallable for At {
endor_core::CallEffect::ReadOnly,
))
}
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 绑定列表接收者已捕获,只接受一个显式索引。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(1))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 要求索引可精确转为非负平台整数,检查列表范围后返回对应托管成员,不复制成员对象。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
let [Value::Number(index)] = args else {
return Err(VmError::InvalidArgument("object list at expects an index"));
};
// 先要求可精确表示为 i64 的整数,再转为 usize,拒绝小数、负数及目标平台越界值。
let index = index
.as_i64()
.and_then(|v| usize::try_from(v).ok())
@@ -145,7 +146,8 @@ pub fn collection(
build(cx, mounts, desktop, None)
}
/// 根据当前输入构造本模块的派生结果,具体的验证与资源边界见函数内步骤。
/// 建立列表 payload 和 first/count/at 属性;definition 指定子类时保留该名义类型。
/// 最多接受 10000 个成员;空列表的 first 为 Nil,at 越界仍报错而不返回 Nil。
fn build(
cx: &mut NativeContext<'_>,
mounts: Vec<ObjectRef>,
@@ -157,6 +159,7 @@ fn build(
"object list exceeds 10000 members",
));
}
// 在移动 Vec 之前提取元信息;成员对象的拥有边由 ObjectList::trace 声明。
let first = mounts
.first()
.copied()
@@ -171,6 +174,7 @@ fn build(
}
cx.set_attr(set, "first", first)?;
cx.set_attr(set, "count", Value::Number((count as i64).into()))?;
// at 捕获列表,列表属性又指向 at,形成托管环;显式 captures 让 GC 能追踪和回收此环。
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))?;
@@ -213,21 +217,23 @@ impl NativeCallable for Constructor {
fn signature(&self) -> Option<endor_core::CallSignature> {
self.signature.clone()
}
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 至少包含请求 Type,之后为可变成员对象与源子类字段,具体分段在 invoke 校验。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::range(1, usize::MAX))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 按请求类型字段数切分成员/字段,禁止覆盖列表协议保留属性,验证后分配列表并初始化源字段。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
let [Value::Object(definition), values @ ..] = args else {
return Err(VmError::InvalidArgument("ObjectList type argument"));
};
// 首参是要构造的名义类型,余下实参分成“成员对象前缀”和“子类字段后缀”。
let fields = cx
.store()
.payload::<endor_core::EndorTypeObject>(*definition, "Type")?
.fields()
.to_vec();
// 列表查询和修改方法均由原生协议保留,子类字段不得覆盖这些名称。
if fields.iter().any(|field| {
matches!(
field.name.as_str(),
@@ -236,6 +242,7 @@ impl NativeCallable for Constructor {
}) {
return Err(VmError::InvalidArgument("reserved ObjectList field"));
}
// 字段按类型定义顺序占据最后 N 项;checked_sub 在实参不足时返回错误,避免下标下溢。
let count = values
.len()
.checked_sub(fields.len())
@@ -244,6 +251,7 @@ impl NativeCallable for Constructor {
))?;
cx.store()
.check_class_field_arguments(*definition, &values[count..])?;
// 字段值先按声明检查;成员前缀另行要求全部是对象,禁止把标量装入宿主对象列表。
let members = values[..count]
.iter()
.map(|value| {
+19 -1
View File
@@ -11,12 +11,15 @@ use std::sync::Arc;
#[derive(Debug)]
/// 一个窗口独立的展示状态:活动页面、待提交请求、Mount、布局与源读取缓存;共享 VM 的业务状态不放在这里复制。
pub(crate) struct Presentation {
// 所属托管桌面身份;此结构借用身份,真正的展示根由托管桌面字典维持。
pub desktop: ObjectRef,
pub closing: bool,
pub tabs: ObjectRef,
pub active: Option<ObjectRef>,
// 双层 Option 区分三态:None 无请求,Some(None) 请求清空,Some(Some(page)) 请求切页。
pub pending: Option<Option<ObjectRef>>,
pub last_snapshot: Option<Arc<UiNode>>,
// 弱身份到原生稳定标签 ID 的映射;不能因为标签历史而保活已经关闭的页面。
pub tab_ids: Vec<(WeakObjectRef, u64)>,
pub next_tab: u64,
pub last_tabs: Vec<crate::tabs::Tab>,
@@ -25,7 +28,9 @@ pub(crate) struct Presentation {
pub layout: crate::layout::LayoutRuntime,
pub mounts: crate::mount::MountTable,
pub published_version: u64,
// 即使根快照身份未变也要求重新发布一帧,例如源绘制读取的数据发生变化时。
pub force_frame: bool,
// 精确名称/字典种类依赖,与下面按整个对象版本记录的 reads 分开检查。
pub paint_names: Vec<endor_core::ReadDependency>,
pub layout_names: Vec<endor_core::ReadDependency>,
pub paint_reads: std::collections::BTreeMap<ObjectRef, u64>,
@@ -40,6 +45,8 @@ pub(crate) struct Presentation {
impl Presentation {
/// 比较布局/绘制读取版本和名称依赖,标记需要刷新并通知快照缓存。
pub fn observe_changes(&mut self, vm: &Vm, changes: &ChangeBatch) {
// 先检查粗粒度对象版本,layout 优先于 paint;每类只记录第一个失效项用于诊断。
// 对象已经释放时版本查询失败,也视作失效,而非继续使用旧缓存。
if let Some((phase, object, version)) = self
.layout_reads
.iter()
@@ -62,6 +69,8 @@ impl Presentation {
vm.change_version(*object).ok()
);
}
// 再核对名称级依赖,避免仅凭对象版本漏掉名称解析路径上的变化。
// 两个检查独立执行,因此同次观察可能分别增加计数,后者诊断可覆盖前者。
if let Some((phase, dependency)) = self
.layout_names
.iter()
@@ -81,6 +90,7 @@ impl Presentation {
};
self.last_invalid_dependency = format!("{phase} name {}:{name}", dependency.object());
}
// 把同一批 VM 写入交给视觉快照缓存,源布局/绘制依赖与原生快照依赖分别维护。
self.render_cache.invalidate(ChangeBatch {
changes: changes.changes.clone(),
rescan_required: changes.rescan_required,
@@ -94,16 +104,19 @@ impl Presentation {
affected: &std::collections::HashSet<ObjectRef>,
reason: &str,
) -> Result<(), VmError> {
// 仅绘制失效不影响测量;其余原因清除测量结果并按 Block ID 使布局缓存失效。
if reason != "paint" {
self.measure_cache.invalidate(affected);
for block in affected {
self.layout.invalidate(&block.to_string());
}
}
// 内容变化还可能改变组成结构,因此显式失效视觉快照及其父链;其他原因不额外做此传播。
if reason == "content" {
self.render_cache
.invalidate_objects(affected.iter().copied());
}
// 仅当受影响 Block 在该窗口有活动出现时强制刷新,避免无关窗口重复发帧。
for weak in self.mounts.active.values() {
if let Some(mount) = cx.upgrade(*weak)?
&& affected.contains(
@@ -118,7 +131,8 @@ impl Presentation {
Ok(())
}
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 用桌面与标签注册表身份初始化窗口状态,布局和视觉缓存从空状态开始。
// 这里只初始化窗口级缓存,不创建 VM、不复制业务对象;active/pending 留空等待窗口展示请求。
pub fn new(desktop: ObjectRef, tabs: ObjectRef) -> Self {
Self {
desktop,
@@ -158,6 +172,7 @@ pub(crate) fn split_reads(
) {
let mut objects = std::collections::BTreeMap::new();
let mut names = Vec::new();
// 整对象依赖按身份收集到有序表,重复项以最后一次版本为准;其余精确依赖保持原记录。
for dependency in reads {
match dependency {
endor_core::ReadDependency::Object { object, version } => {
@@ -174,7 +189,9 @@ mod tests {
use super::*;
use crate::{layout::Size, ui_bridge::UiKind};
#[test]
/// 同VM中两Presentation分别布局共享树,尺寸/出现身份独立;读观察可追踪共享对象但不能增添GC根。
fn independent_view_geometry_and_shared_vm_reads_do_not_add_roots() {
// 测试在同一 VM 中建立两个 Presentation,验证各自布局尺寸/出现 ID 独立,读取依赖共享业务对象。
let mut vm = Vm::new().unwrap();
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());
@@ -230,6 +247,7 @@ mod tests {
left.observe_changes(&vm, &changes);
right.observe_changes(&vm, &changes);
assert!(left.force_frame && right.force_frame);
// 最后释放业务对象并回收:两份读取记录都不应成为托管根,弱引用应升级失败。
let weak = vm.downgrade(shared).unwrap();
vm.release(shared).unwrap();
vm.collect_cycles();
+11
View File
@@ -14,14 +14,18 @@ pub fn install(
desktop: ObjectRef,
ui: ObjectRef,
) -> Result<(), VmError> {
// 安装前要求桥接已经创建 Trait 类型与 desktop.types 注册表;缺失时立即失败,不能安装半定义能力。
let Value::Object(trait_type) = vm.get_attr(ui, "Trait")? else {
return Err(VmError::InvalidArgument("missing Trait type"));
};
let Value::Object(types) = vm.get_attr(desktop, "types")? else {
return Err(VmError::InvalidArgument("missing type registry"));
};
// 每组声明能力名、方法及显式参数数目、提供默认签名的原生类型。
// 签名还含接收者参数,下面会把总 arity 调整为 parameters+1。
for (name, methods, owner) in [
(
// 测量/布局/绘制/命中能力,签名取自 Block 的原生协议实现,保证效果约束与具体方法一致。
"Visual",
vec![("measure", 2), ("arrange", 2), ("paint", 2), ("hitTest", 2)],
Some("Block"),
@@ -32,6 +36,7 @@ pub fn install(
Some("Block"),
),
(
// 组成编辑能力属于 ContainerBlock,普通叶 Block 不因此获得追加或重排孩子的方法。
"Children",
vec![
("append", 1),
@@ -45,6 +50,7 @@ pub fn install(
),
("Presentable", vec![("present", 1)], None),
] {
// 从当前 ui 模块查名义类型身份,不靠字符串名称把另一个运行时的类型误接进来。
let owner_definition = if let Some(owner) = owner {
let Value::Object(definition) = vm.get_attr(ui, owner)? else {
return Err(VmError::InvalidArgument("missing protocol owner"));
@@ -55,6 +61,7 @@ pub fn install(
};
let mut requirements = Vec::new();
for (method, parameters) in methods {
// 优先复用原生方法参数/返回注解和调用效果,缺少原生签名元数据时拒绝安装。
let mut signature = if let Some(owner) = owner_definition {
let function = vm
.object_store()
@@ -66,6 +73,7 @@ pub fn install(
"protocol method lacks native types",
))?
} else {
// Presentable 没有默认 owner,手工声明 present(receiver, Window) -> Block,调用效果为 External。
let window = crate::ui_bridge::desktop_type(vm.object_store(), "Window", desktop)?;
let block = crate::ui_bridge::desktop_type(vm.object_store(), "Block", desktop)?;
CallSignature::exact(
@@ -75,6 +83,7 @@ pub fn install(
)
};
signature.arity = CallArity::exact(parameters + 1);
// 接收者类型改为 Any,使能力可由其他符合方法契约的名义类型实现,不把契约绑定死在 Block。
signature.parameters[0] = AnnotationType::Any.into();
requirements.push(TypedMethodRequirement {
name: method.into(),
@@ -82,11 +91,13 @@ pub fn install(
});
}
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))?;
if let Some(owner) = owner_definition {
// 有默认提供者时显式登记 implements 关系;Presentable 留待具体类型声明,不自动给所有 Block 安装。
vm.implement_trait(owner, capability)?;
}
}
+48 -5
View File
@@ -84,8 +84,9 @@ impl Constructor {
.into_iter()
.find(|kind| kind.function() == name)
}
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 返回三维原生构造的显式最小/最大参数数,不含请求 Type;Group/Scene 支持最多4096子节点。
pub fn arity(self) -> (usize, usize) {
// 构造器 arity 不含 NativeTyped 的类型首参,Group/Scene 允许零到 4096 个孩子,其他零参对象使用默认属性。
match self {
Self::Vec3 | Self::Triangle => (3, 3),
Self::Geometry | Self::Mesh => (2, 2),
@@ -205,6 +206,7 @@ fn set_number(
}
/// 解析颜色值并检查其满足当前原生绘制约定。
fn color(value: &str) -> Result<[f32; 3], VmError> {
// 3D 不透明材质拒绝半透明颜色,转换为 [0,1] RGB 数值;普通二维 UI 的 alpha 不受这里限制。
let color = crate::document::parse_color(value).map_err(|_| invalid("invalid 3D color"))?;
if color.alpha != 255 {
return Err(invalid("3D opaque material color requires full alpha"));
@@ -224,6 +226,7 @@ pub fn allocate(
constructor: Constructor,
args: &[Value],
) -> Result<ObjectRef, VmError> {
// 入口假设桥接工厂已按 arity/类型检查 args;Geometry 特殊地复制缓冲并提前返回,其余创建可编辑标记节点。
let kind = match constructor {
Constructor::Vec3 => NodeKind::Vector,
Constructor::Triangle => NodeKind::Triangle,
@@ -236,6 +239,7 @@ pub fn allocate(
Constructor::Orbit => NodeKind::Orbit,
Constructor::Panel => NodeKind::Panel,
Constructor::Geometry => {
// Geometry 构造只接受受控 ObjectList,逐成员验证 Vec3 payload 并复制数值;以后改源 Vec3 不会改已建几何。
let vertices = object_list::items(cx.store(), object_ref(&args[0])?)?
.iter()
.map(|&item| {
@@ -257,6 +261,7 @@ pub fn allocate(
return Err(invalid("geometry indices require Triangle3D"));
}
let mut triangle = [0; 3];
// 索引先从 Number 检查非负整数,再转 u32;是否越出顶点范围在整份 geometry.valid 校验。
for (index, name) in ["a", "b", "c"].into_iter().enumerate() {
let value = number(&cx.store().get_attr(item, name)?)?;
if value < 0. || value.fract() != 0. {
@@ -272,6 +277,7 @@ pub fn allocate(
triangles,
uv: vec![],
};
// 缓存为原生 Arc 前统一验证顶点/三角形预算与下标范围,避免渲染线程再接触源缓冲对象。
if !geometry.valid() {
return Err(invalid(
"invalid Geometry3D buffers or geometry budget exceeded",
@@ -300,6 +306,7 @@ pub fn allocate(
NodeKind::Mesh => {
let (geometry, material) = if matches!(constructor, Constructor::Box) {
let (w, h, d) = (number(&args[0])?, number(&args[1])?, number(&args[2])?);
// Box 允许零尺寸产生退化面,后续光栅/拾取跳过退化三角形;负尺寸在构造入口拒绝。
if w < 0. || h < 0. || d < 0. {
return Err(invalid("Box3D dimensions must be nonnegative"));
}
@@ -315,6 +322,7 @@ pub fn allocate(
cx.set_attr(instance, "geometry", Value::Object(geometry))?;
cx.set_attr(instance, "color", Value::Text(material))?;
}
// 孩子只接受 Mesh/Group/Light/Panel 标记,不允许把相机、控制器或任意 Object 放进场景组成。
NodeKind::Group | NodeKind::Scene => {
let children = args.iter().map(object_ref).collect::<Result<Vec<_>, _>>()?;
for child in &children {
@@ -327,6 +335,7 @@ pub fn allocate(
));
}
}
// 托管 children 列表拥有子节点;Node payload 自身只是标记,属性拥有边由 VM 正常追踪。
let children = object_list::collection(cx, children, desktop)?;
cx.set_attr(instance, "children", Value::Object(children))?;
if kind == NodeKind::Scene {
@@ -345,6 +354,7 @@ pub fn allocate(
cx.set_attr(instance, "color", args[3].clone())?;
set_number(cx, instance, "intensity", number(&args[4])?)?;
}
// 世界宽高与 UI 像素分辨率独立:初始纹理 512×320,content 是普通 Block 图,稍后参与独立有限布局。
NodeKind::Panel => {
let content = object_ref(&args[2])?;
crate::block::validate(cx.store(), content, None)?;
@@ -379,6 +389,7 @@ pub fn allocate(
set_number(cx, instance, "panSpeed", 1.)?;
}
}
// 只有可放置节点安装 TRS;相机用 position/target/up,方向光用方向向量,不复用网格欧拉角字段。
if matches!(kind, NodeKind::Mesh | NodeKind::Group | NodeKind::Panel) {
for (name, value) in [
("x", 0.),
@@ -405,6 +416,7 @@ struct Reader<'a> {
impl Reader<'_> {
/// 读取字段并登记依赖,使后续字段变更能够使 3D 快照失效。
fn value(&mut self, object: ObjectRef, name: &str) -> Result<Value, VmError> {
// 读取前登记精确对象/属性依赖,HashSet 去重;返回给视觉缓存后,相关字段变化才能驱动重建。
self.reads.insert((object, name.into()));
self.store.get_attr(object, name)
}
@@ -422,6 +434,7 @@ impl Reader<'_> {
}
/// 读取并校验透视或正交摄像机字段,生成不持有 VM 引用的投影描述。
fn camera(&mut self, object: ObjectRef) -> Result<Camera, VmError> {
// 先验证宿主相机种类,再按投影策略读取 fov 或 height;不把有同名字段的对象当相机。
let projection = match self.store.payload::<Node>(object, "3D camera")?.0 {
NodeKind::Perspective => Projection::Perspective {
fov: self.number(object, "fov")?,
@@ -456,6 +469,7 @@ pub struct PanelMount {
pub content: ObjectRef,
pub size: crate::layout::Size,
}
// 三部分分别是可跨线程的不可变 View、VM 内缓存用的属性依赖、仍由 VM 驱动布局的面板 Block 根。
pub type Snapshot = (
Arc<scene3d::View>,
Vec<(ObjectRef, String)>,
@@ -496,6 +510,7 @@ pub fn snapshot_reusing(
background,
acceleration: Arc::default(),
};
// 显式进入/退出栈保存节点、父世界矩阵、退出标记与路径 key;path 仅追踪祖先,因此允许共享子树多次出现。
let mut work = vec![(scene, Matrix::default(), false, 0u64)];
let mut panels = Vec::new();
let mut path = HashSet::new();
@@ -508,6 +523,7 @@ pub fn snapshot_reusing(
continue;
}
visits += 1;
// 预算按展开出现次数,重复共享同一网格也消耗实例/顶点/三角形工作,不能只数不同对象身份。
if visits > 4096 {
return Err(VmError::ExecutionLimit("3D scene occurrences"));
}
@@ -517,6 +533,7 @@ pub fn snapshot_reusing(
work.push((object, parent, true, key));
let kind = store.payload::<Node>(object, "3D node")?.0;
let world = if matches!(kind, NodeKind::Mesh | NodeKind::Group | NodeKind::Panel) {
// 局部先缩放、旋转、平移,再乘父 world;Scene/Light 不新增 TRS,方向光仍受祖先 Group 变换。
parent.compose(Matrix::trs(
reader.vector(object, ["x", "y", "z"])?,
reader.vector(object, ["rotationX", "rotationY", "rotationZ"])?,
@@ -531,6 +548,8 @@ pub fn snapshot_reusing(
for (index, child) in object_list::items(store, list)?.iter().enumerate().rev() {
use std::hash::{Hash, Hasher};
let mut hasher = std::collections::hash_map::DefaultHasher::new();
// 路径 key 包含父 key、当前孩子索引和托管身份,区分同一 Panel 节点在不同路径的出现。
// 此 key 与普通 Block slot 不同,场景列表重排会改变路径身份。
key.hash(&mut hasher);
index.hash(&mut hasher);
child.hash(&mut hasher);
@@ -540,6 +559,7 @@ pub fn snapshot_reusing(
NodeKind::Mesh => {
let geometry = object_ref(&reader.value(object, "geometry")?)?;
let geometry = store.payload::<Geometry>(geometry, "Geometry3D")?.0.clone();
// 每次 mesh 出现都累计完整几何,Arc 共享只节约存储,不减少本帧实例绘制工作预算。
triangles += geometry.triangles.len();
vertices += geometry.vertices.len();
if vertices > 262_144 {
@@ -560,10 +580,12 @@ pub fn snapshot_reusing(
NodeKind::Panel => {
// Arrangement slots cross Endor's signed integer API. A raw
// u64 hash can turn negative when native Bounds are created.
// Bounds.slot 经有符号整数 API 传递,清最高位避免变负;仍显式检测碰撞,不能假设哈希必然唯一。
let key = key & i64::MAX as u64;
if panels.iter().any(|panel: &PanelMount| panel.key == key) {
return Err(invalid("colliding 3D UI occurrence identities"));
}
// 有限面板根数量另限 64;每个面板还有独立像素分辨率限制和递归纹理总预算。
if panels.len() >= 64 {
return Err(VmError::ExecutionLimit("3D UI panels"));
}
@@ -584,6 +606,7 @@ pub fn snapshot_reusing(
let content = object_ref(&reader.value(object, "content")?)?;
crate::block::resolve(store, content)?;
let background = color(&text(&reader.value(object, "background")?)?)?;
// 面板平面以中心为原点,顶点 y 向上,UV 左上为 (0,0);两三角形共用四个角点。
let geometry = Arc::new(scene3d::Geometry {
vertices: vec![
Vec3::new(-width / 2., height / 2., 0.),
@@ -607,6 +630,7 @@ pub fn snapshot_reusing(
surface: None,
}),
});
// 同时把普通 UI 根交给宿主布局,scene Mesh 先只带分辨率/背景,surface 由后续 panel::compose 装配。
panels.push(PanelMount {
key,
content,
@@ -622,6 +646,7 @@ pub fn snapshot_reusing(
}
let direction =
reader.vector(object, ["directionX", "directionY", "directionZ"])?;
// 用两点之差撤销父矩阵平移,仅保留线性部分对方向的影响,再归一化;零方向拒绝。
let direction = (world.point(direction) - world.point(Vec3::default()))
.normalized()
.ok_or(invalid("light direction cannot be zero"))?;
@@ -639,6 +664,7 @@ pub fn snapshot_reusing(
_ => return Err(invalid("invalid node in 3D scene graph")),
}
}
// 完整世界值相等时复用旧 Scene/BVH,单独换 camera 生成新 View;不相等才重建世界空间索引。
let scene = if let Some(scene) = reuse.filter(|scene| **scene == output) {
scene
} else {
@@ -646,6 +672,7 @@ pub fn snapshot_reusing(
Arc::new(output)
};
let view = Arc::new(scene3d::View { scene, camera });
// 提取各项之后仍做完整视图校验,覆盖累计世界变换、光照、面板及整体资源不变量。
if !view.valid() {
return Err(invalid("invalid 3D scene snapshot"));
}
@@ -667,6 +694,7 @@ pub fn pick(
if !matches!(data.kind, crate::block::Kind::Viewport3D { .. }) {
return Err(invalid("pick3D requires a Viewport3D"));
}
// 先做出现/面板遮挡和裁剪命中,未命中直接 Nil;即使场景射线有交点也不能点穿外层遮挡。
if !mount.geometry.contains(point) {
return Ok(Value::Nil);
}
@@ -675,6 +703,7 @@ pub fn pick(
let Some(point) = mount.geometry.logical_point(point) else {
return Ok(Value::Nil);
};
// 从布局盒扣 inset 得到实际内容视口,再把逻辑点归一化;零面积视口没有有效投影。
let (width, height) = (
(mount.geometry.width - inset.horizontal()).max(0.),
(mount.geometry.height - inset.vertical()).max(0.),
@@ -695,6 +724,7 @@ pub fn pick(
let Some(hit) = hit else {
return Ok(Value::Nil);
};
// 原生 Hit.identity 只带文本,通过本次实际读取的托管身份重新关联节点;渲染器本身从不解引用 VM 对象。
let mesh = reads
.iter()
.find_map(|(object, _)| (object.to_string() == hit.identity).then_some(*object))
@@ -718,6 +748,7 @@ pub fn pick(
"triangle",
Value::Number((hit.triangle as i64).into()),
)?;
// 交点、法线、重心权重都包装为名义 Vec3,结果对象通过普通属性强持有它们。
for (name, vector) in [
("point", hit.point),
("normal", hit.normal),
@@ -752,7 +783,7 @@ pub struct PointerPick {
}
/// The default controller is replaceable; camera data has no dependency on it.
/// 为指定出现解码相机手势并调用控制器;嵌套面板输入先转换到所属视口坐标。
/// 默认 OrbitController 根据已解码的 CameraGesture 更新相机,处理轨道、平移和缩放;可由源控制器替换。
pub fn control(
cx: &mut NativeContext<'_>,
controller: ObjectRef,
@@ -770,6 +801,7 @@ pub fn control(
let dx = reader.number(gesture, "dx")?;
let dy = reader.number(gesture, "dy")?;
let kind = text(&reader.value(gesture, "kind")?)?;
// 默认轨道控制围绕 target 使用 position-target 偏移和半径;相机有效性保证观察方向不退化。
let offset = camera.position - camera.target;
let radius = offset.length();
let mut position = camera.position;
@@ -784,12 +816,14 @@ pub fn control(
.up
.normalized()
.ok_or(invalid("camera up cannot be zero"))?;
// 将偏移分解为 up 方向和水平面方向,用水平旋转更新 yaw、asin(vertical) 更新 pitch。
let vertical = (offset.dot(up) / radius).clamp(-1., 1.);
let horizontal = (offset - up * offset.dot(up))
.normalized()
.ok_or(invalid("orbit at pole requires a different up vector"))?;
let (sine, cosine) = (dx * speed).sin_cos();
let horizontal = horizontal * cosine + up.cross(horizontal) * sine;
// 俯仰限制在两极内侧 0.01 弧度,避免绕极点时水平基退化并导致轨道跳变。
let pitch = (vertical.asin() + dy * speed).clamp(
-std::f32::consts::FRAC_PI_2 + 0.01,
std::f32::consts::FRAC_PI_2 - 0.01,
@@ -802,6 +836,7 @@ pub fn control(
return Err(invalid("panSpeed expects 0 through 100"));
}
let height = reader.number(gesture, "height")?.max(1.);
// 把逻辑像素位移换成世界单位:透视按 target 距离处的可见高度,正交按固定投影高度。
let units = match camera.projection {
Projection::Perspective { fov } => {
2. * radius * (fov.to_radians() / 2.).tan() / height
@@ -810,6 +845,7 @@ pub fn control(
};
let basis = camera.basis().ok_or(invalid("invalid camera basis"))?;
let delta = basis.right * (dx * units * speed) + basis.up * (-dy * units * speed);
// 平移同时移动 position 和 target,保留观察方向与轨道半径;屏幕 y 向下所以 up 分量取负。
position = position + delta;
target = target + delta;
}
@@ -818,6 +854,7 @@ pub fn control(
if !(0.1..=10.0).contains(&factor) {
return Err(invalid("zoom factor expects 0.1 through 10"));
}
// 正交缩放只改投影高度,透视缩放改变到 target 的距离;倍率大于一均表现为拉近。
if let Projection::Orthographic { height } = camera.projection {
set_number(
cx,
@@ -833,6 +870,7 @@ pub fn control(
}
_ => return Err(invalid("unsupported 3D camera gesture")),
}
// 写回前校验整个计算结果,拒绝超世界范围;控制器通过普通属性更新让后续快照依赖观察变化。
if !position.valid() || !target.valid() {
return Err(invalid("camera movement exceeds world budget"));
}
@@ -849,7 +887,7 @@ pub fn control(
Ok(())
}
/// 执行托管 3D 节点的原生平移/旋转操作,供尚不支持普通数值算术表达式的源程序调用。
/// 对允许的 3D 节点累计平移或角度旋转;相机平移同时更新 target,旋转值归一到 [0,360)。
pub fn transform(
cx: &mut NativeContext<'_>,
owner: ObjectRef,
@@ -869,11 +907,13 @@ pub fn transform(
{
return Err(invalid("unsupported 3D transform target"));
}
// 旋转增量作用欧拉角,平移增量作用位置;相机不接受本接口的欧拉角旋转。
let names = if rotate {
["rotationX", "rotationY", "rotationZ"]
} else {
["x", "y", "z"]
};
// 先收集并验证全部轴再写入,避免验证到第二/三轴才发现越界时已修改前面轴。
let mut updates = Vec::new();
for (index, name) in names.into_iter().enumerate() {
let delta = number(&args[index])?;
@@ -884,11 +924,13 @@ pub fn transform(
updates.push((
name,
if rotate {
// 角度归一到 [0,360),支持负增量而不使用产生负余数的普通取模。
value.rem_euclid(360.)
} else {
value
},
));
// 相机平移同步改 target,保留朝向;不把“移动摄像机”意外变成绕固定目标转动。
if camera {
let name = ["targetX", "targetY", "targetZ"][index];
let value = number(&cx.store().get_attr(owner, name)?)? + delta;
@@ -904,11 +946,11 @@ pub fn transform(
Ok(())
}
impl endor_core::NativeCallable for PointerPick {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 输入 Mount 与点击点已捕获,拾取/分发准备步骤不再接受实参。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 在当前 Mount 中重新射线拾取,构造含真实 mesh 命中的 click Event,再交托管事件系统分发。
fn invoke(
&self,
cx: &mut NativeContext<'_>,
@@ -921,6 +963,7 @@ impl endor_core::NativeCallable for PointerPick {
let hit = pick(cx, self.desktop, &mount, self.point)?;
let definition = crate::ui_bridge::desktop_type(cx.store(), "Event", self.desktop)?;
let event = crate::event_dispatch::new_event(cx, definition, "click")?;
// 点击事件把精确拾取值放到 hit(未击中则 Nil),仍以 Viewport 的 Block/Mount 作为事件传播目标。
cx.set_attr(event, "hit", hit)?;
crate::event_dispatch::dispatch(cx, mount.block, event, Some(self.mount), self.desktop)
}
+29
View File
@@ -31,10 +31,15 @@ struct Dependency {
#[derive(Debug, Default)]
/// 视觉快照缓存与反向依赖图。对象身份是借用索引,原生 Arc 数据不拥有 VM 根。
pub struct RenderCache {
// 场景对象身份到原生不可变几何的缓存;相机改变时仍有机会复用同一场景数据。
scenes3d: HashMap<ObjectRef, Arc<crate::scene3d::Scene>>,
// 每个业务 Block 的视觉结果;这里只保存原生快照,不通过 ObjectRef 增加 VM 强引用。
entries: HashMap<ObjectRef, Cached>,
// 读取源 -> 读取它的 Block。属性变动从这里找到首批需要重建的快照。
dependents: HashMap<Dependency, HashSet<ObjectRef>>,
// 子 Block -> 所有父 Block。共享子组件改变后,所有引用该子项的父快照都需要更新。
parents: HashMap<ObjectRef, HashSet<ObjectRef>>,
// 已失效但尚未重建的 Block 集合,同时用于传播去重。
dirty: HashSet<ObjectRef>,
pub last_invalidation: String,
pub visited: usize,
@@ -45,11 +50,13 @@ impl RenderCache {
/// 把 VM 变化映射到读取过这些属性/对象的视觉节点,再沿父链向上传播脏标记。
pub fn invalidate(&mut self, batch: ChangeBatch) {
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 使用整个对象键;与提取时登记的依赖粒度一致。
let key = Dependency {
object: change.object,
property: match change.key {
@@ -70,6 +77,7 @@ impl RenderCache {
pub fn invalidate_objects(&mut self, objects: impl IntoIterator<Item = ObjectRef>) {
let mut queue: VecDeque<_> = objects.into_iter().collect();
while let Some(block) = queue.pop_front() {
// 只有第一次加入 dirty 才继续向父链传播,避免共享祖先被反复展开。
if self.dirty.insert(block)
&& let Some(parents) = self.parents.get(&block)
{
@@ -81,6 +89,7 @@ impl RenderCache {
/// 撤销旧缓存的反向读取边和父子边,为重新登记该节点做准备。
fn remove(&mut self, block: ObjectRef) -> Option<Cached> {
let old = self.entries.remove(&block)?;
// 旧边必须先撤销,否则节点重建后仍会被已经不再读取的对象触发失效。
for source in &old.dependencies {
if let Some(owners) = self.dependents.get_mut(source) {
owners.remove(&block);
@@ -89,6 +98,7 @@ impl RenderCache {
}
}
}
// 只撤销当前 Block 对孩子的父边;其他共享父节点仍保留。空集合及时删除以缩小索引。
for child in &old.children {
if let Some(parents) = self.parents.get_mut(child) {
parents.remove(&block);
@@ -104,6 +114,7 @@ impl RenderCache {
pub fn prune(&mut self, store: &ObjectStore) {
self.scenes3d
.retain(|object, _| store.object(*object).is_ok());
// 先收集死亡身份,再修改 entries 与反向索引,避免一边借用遍历一边删除。
let dead: Vec<_> = self
.entries
.keys()
@@ -112,6 +123,7 @@ impl RenderCache {
.collect();
for block in dead {
self.remove(block);
// 只有成功建立新条目后才清脏标记;前面任何校验失败都不会把节点错误标成干净。
self.dirty.remove(&block);
}
}
@@ -124,6 +136,8 @@ impl RenderCache {
) -> Result<Arc<UiNode>, VmError> {
self.visited = 0;
self.reused = 0;
// 使用进入/退出两阶段的显式 DFS,避免深层组成消耗 Rust 调用栈。
// values 是后序结果栈:每个退出节点消费刚完成的孩子快照,再压入自己。
let mut work = vec![(root, false)];
let mut path = HashSet::new();
let mut values = Vec::<Arc<UiNode>>::new();
@@ -137,11 +151,13 @@ impl RenderCache {
values.push(cached.node.clone());
continue;
}
// 计数的是本次实际展开次数;共享节点可复用缓存,脏图展开仍有 10000 次上限。
self.visited += 1;
if self.visited > 10_000 {
return Err(VmError::ExecutionLimit("expanded Block graph"));
}
}
// 提取前验证实例存储与类型契约;resolve_tracked 同时提供数据以及经过的代理/存储依赖。
store.check_typed_instance_storage(block)?;
let (data_ref, raw_data, raw_dependencies) = block::resolve_tracked(store, block)?;
let mut data = block::visual_data(store, raw_data)?;
@@ -152,6 +168,7 @@ impl RenderCache {
property: None,
})
.collect();
// 方法名称查找也构成依赖。即使属性数值未变,协议方法被替换也必须让快照失效。
let storage = *store
.attribute_path(block)?
.last()
@@ -162,6 +179,7 @@ impl RenderCache {
property: Some(name),
});
}
// 原生视觉属性按精确字段登记,避免不参与视觉的其他属性写入触发整个节点重建。
if let Some(properties) = data.properties {
for (name, _) in block::native_properties(&data) {
dependencies.push(Dependency {
@@ -180,6 +198,7 @@ impl RenderCache {
});
}
}
// 3D 面板把托管内容映射为子 Block,同时保留尺寸与稳定 slot,供后续布局和出现身份使用。
let mut panel_sizes = Vec::new();
let view3d = if matches!(data.kind, Kind::Viewport3D { .. }) {
let scene = data
@@ -228,6 +247,7 @@ impl RenderCache {
.payload::<crate::event_dispatch::Connection>(o, "Subscription")
.is_ok_and(|s| s.handler.is_some() && s.kind.starts_with("pointer"))
});
// 协议键包含类型身份、实际方法身份及其内容版本,供布局/绘制缓存识别实现变化。
let mut protocol_key = String::new();
let mut custom_event = false;
if let Some(definition) = store.type_of(block)? {
@@ -242,6 +262,7 @@ impl RenderCache {
});
}
}
// 不仅记录最终方法,还沿基类链登记类型内容依赖,使继承关系或方法表变化能触发重建。
let event = store.lookup_method(definition, "onEvent")?;
let mut current = Some(definition);
while let Some(definition) = current {
@@ -259,6 +280,7 @@ impl RenderCache {
.transpose()?
.unwrap_or(false);
}
// 订阅连接的取消会改变 handler;记录连接内容依赖,使交互资格能随取消及时更新。
let mut click_connection = false;
for connection in &data.subscriptions {
dependencies.push(Dependency {
@@ -269,9 +291,11 @@ impl RenderCache {
.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());
let kind = match &data.kind {
Kind::Text { value, size, color } => {
// 旧 textOf 路径按实际源字段提取字符串。属性路径中间对象用整对象依赖,末端用字段依赖。
let value = if let Some((source, field)) = &data.text_binding {
let storage = store.attribute_path(*source)?;
for (index, object) in storage.iter().enumerate() {
@@ -285,6 +309,7 @@ impl RenderCache {
Value::Bool(v) => v.to_string(),
Value::Number(v) => v.to_string(),
Value::Text(v) => v,
// 对象字符串化可能依赖其内容,所以除属性本身外还记录被引用对象的内容变化。
Value::Object(v) => {
dependencies.push(Dependency {
object: v,
@@ -340,6 +365,7 @@ impl RenderCache {
)?,
children,
},
// 二维场景保留每个孩子的世界位置;普通行列容器则由布局决定孩子坐标。
Kind::Scene2D => UiKind::Scene2D {
positions: data
.children
@@ -387,6 +413,7 @@ impl RenderCache {
children,
},
};
// 统一外层样式与交互标志。UiKind 只表示具体内容,UiNode 保存所有类别共享的视觉元信息。
let next = UiNode {
surface: matches!(data.kind, Kind::Page).then(|| {
let mut surface = data.surface.clone();
@@ -415,12 +442,14 @@ impl RenderCache {
|| custom_event,
kind,
};
// 即使本次重算结果相同,也要重新登记依赖。shallow_eq 相同时复用旧 Arc,减少下游无效重建。
let old = self.remove(block);
let node = if let Some(old) = old.as_ref().filter(|old| old.node.shallow_eq(&next)) {
old.node.clone()
} else {
Arc::new(next)
};
// 同一属性可能由不同提取路径重复读取,排序去重后再建立反向边。
dependencies.sort_unstable();
dependencies.dedup();
let child_refs: Vec<_> = data.children.iter().map(|child| child.block).collect();
+28 -4
View File
@@ -32,6 +32,7 @@ pub struct Command {
impl Command {
/// 判断两条命令是否针对同一资源的同类动作,用于替换尚未执行的旧请求。
pub fn same_kind(&self, other: &Self) -> bool {
// 比较动作变体而不是参数值:同窗口多次 Resize/SetTitle 可合并为最后一次,不同动作仍按序保留。
self.window == other.window
&& std::mem::discriminant(&self.action) == std::mem::discriminant(&other.action)
}
@@ -46,14 +47,17 @@ pub struct Envelope {
/// 托管窗口资源状态与页面拥有关系;本对象存在不等于 OS 窗口已创建。
pub struct ManagedWindow {
pub id: u64,
// 每窗口拥有独立 desktop、tabs 与页面顺序;同 VM 的类型注册表可共享,不复制业务模型。
pub desktop: ObjectRef,
pub closed: bool,
pub tasks: Option<ObjectRef>,
tabs: ObjectRef,
// 页面身份的有序强拥有集合,tabs 字典同时提供托管注册入口;移动顺序只调整此 Vec。
pages: Vec<ObjectRef>,
sequence: u64,
// Transport state only. Draining it must not change a language object's
// version or create a render-dependency feedback loop.
// 仅保存纯数据传输队列,克隆 payload 仍共享同一 outbox;drain 不触发 VM 内容版本,避免反馈循环。
outbox: Arc<Mutex<Vec<Command>>>,
}
impl ObjectPayload for ManagedWindow {
@@ -94,6 +98,7 @@ fn screen_coordinate(value: &Value) -> Result<i32, VmError> {
let Value::Number(value) = value else {
return Err(invalid("screen position requires integer coordinates"));
};
// 屏幕位置必须为整数,允许负坐标以覆盖多显示器;范围与 i32 转换均检查,不能把小数直接截断。
value
.as_i64()
.filter(|number| (-1_000_000..=1_000_000).contains(number))
@@ -137,7 +142,7 @@ impl NativeCallable for Method {
fn signature(&self) -> Option<endor_core::CallSignature> {
Some(self.signature.clone())
}
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 计入 Window 接收者:resize/moveTo 共三参,setTitle 两参,其他查询/关闭/聚焦只要接收者。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(match self.operation {
Operation::Resize | Operation::MoveTo => 3,
@@ -146,7 +151,7 @@ impl NativeCallable for Method {
}))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 验证窗口资源与关闭状态;查询返回托管值,原生变更生成受世代保护的待执行命令,关闭走资源生命周期。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
let Some(Value::Object(owner)) = args.first() else {
return Err(invalid("Window method requires a Window"));
@@ -155,6 +160,7 @@ impl NativeCallable for Method {
.store()
.payload::<ManagedWindow>(*owner, "Window")?
.clone();
// 已关闭窗口仍可查询稳定 ID 与页面集合,其他读取/操作拒绝,避免用旧 viewport 或重开原生资源。
if data.closed && !matches!(self.operation, Operation::Id | Operation::Pages) {
return Err(invalid("native window is closed"));
}
@@ -171,6 +177,7 @@ impl NativeCallable for Method {
Operation::Pages => {
Value::Object(object_list::collection(cx, data.pages, self.desktop)?)
}
// 读取该 Window 自己 desktop 的逻辑视口,封装成 MeasureResult;尚未由原生侧提供尺寸时明确失败。
Operation::Viewport => {
let Value::Object(input) = cx.store().get_attr(data.desktop, "viewport")? else {
return Err(invalid("window viewport is unavailable"));
@@ -185,6 +192,7 @@ impl NativeCallable for Method {
)?)
}
operation => {
// 原生命令虽暂存在内存,也属于变更,不能从只读测量/绘制回调发起窗口操作。
if cx.store().is_read_only() {
return Err(invalid(
"window operations are forbidden during read-only rendering",
@@ -203,6 +211,7 @@ impl NativeCallable for Method {
let Value::Text(title) = &args[1] else {
return Err(invalid("window title requires text"));
};
// 标题限制 UTF-8 字节长度并拒绝控制字符;不会在这里执行标题文本或展开 shell 字符。
if title.len() > 4096 || title.chars().any(char::is_control) {
return Err(invalid("invalid window title"));
}
@@ -228,6 +237,7 @@ pub fn enqueue(
.store()
.payload::<ManagedWindow>(owner, "Window")?
.clone();
// 命令序列单调递增且检查溢出;同类合并会产生序号空洞,但仍可按序比较先后。
data.sequence = data
.sequence
.checked_add(1)
@@ -242,7 +252,9 @@ pub fn enqueue(
.lock()
.map_err(|_| invalid("window outbox poisoned"))?;
// The heap barrier succeeds before any external transport state changes.
// 必须先成功经过 VM 写屏障,才修改不可回滚的原生 outbox;只读调用不能先留下待发命令再报错。
cx.replace_payload(owner, data)?;
// 同窗口同动作只保留最后请求,其他类别保持先后;此处只入队,GUI 是否执行取决于后续成功发布。
queue.retain(|old| !old.same_kind(&command));
queue.push(command);
Ok(())
@@ -266,6 +278,7 @@ pub fn register_page(
if data.closed {
return Err(invalid("native window is closed"));
}
// 登记幂等,首次同时写 tabs 与 payload;字典键使用页面身份文本而非标题,重命名不改变登记。
if !data.pages.contains(&page) {
data.pages.push(page);
cx.dict_set(
@@ -292,6 +305,7 @@ pub fn unregister_page(
.store()
.payload::<ManagedWindow>(window, "Window")?
.clone();
// 不存在时撤销是空操作;存在时同时删有序列表与 tabs 字典边,不能只隐藏原生标签。
if !data.pages.contains(&page) {
return Ok(());
}
@@ -316,7 +330,7 @@ pub fn unregister_page_host(
Ok(())
}
/// 在窗口之间移动页面的所有权和登记顺序,保留同一业务页面身份。
/// 在同一窗口的已登记页面集合内重排标签位置,保留 Page 身份;不负责跨窗口迁移。
pub fn move_page(
cx: &mut NativeContext<'_>,
window: ObjectRef,
@@ -343,6 +357,7 @@ pub fn move_page(
"tab ordering is forbidden during read-only rendering",
));
}
// 只重排当前窗口中的页面,不迁移到另一窗口,也不销毁或重建 Page/Mount;跨窗口迁移由桥接层组合操作。
if from != position {
let page = data.pages.remove(from);
data.pages.insert(position, page);
@@ -361,6 +376,7 @@ pub fn take_commands(vm: &Vm, window: ObjectRef) -> Result<Vec<Command>, VmError
.outbox
.lock()
.map_err(|_| invalid("window outbox poisoned"))?;
// 一次移走全部队列,再按序号排序;仅消费传输状态,不调用 replace_payload 或改变语言依赖版本。
let mut commands = std::mem::take(&mut *queue);
commands.sort_by_key(|command| command.sequence);
Ok(commands)
@@ -417,6 +433,7 @@ pub fn install(
vm.attach_type(function, function_type)?;
vm.define_method(definition, name, function)?;
}
// 安装主窗口托管资源,原生 OS 窗口生命周期仍由 GUI 管理;页面集合初始为空。
let window = vm.allocate(ManagedWindow {
id: MAIN_WINDOW,
desktop,
@@ -430,6 +447,7 @@ pub fn install(
roots.push(window);
vm.attach_type(window, definition)?;
vm.set_attr(desktop, "window", Value::Object(window))?;
// 主 desktop 拥有统一窗口注册表,以纯数字 ID 文本索引;注册表让附加窗口在 VM 图内可达。
let windows = vm.new_dict()?;
vm.set_attr(desktop, "windows", Value::Object(windows))?;
vm.dict_set(
@@ -457,6 +475,7 @@ pub fn create(
}
let desktop = cx.new_object()?;
let tabs = cx.new_dict()?;
// 附加桌面共享主域的同一 types 字典身份,保证跨窗口对象和协议使用同一名义类型体系。
let types = cx.store().get_attr(master, "types")?;
cx.set_attr(desktop, "types", types)?;
cx.set_attr(desktop, "viewport", Value::Nil)?;
@@ -477,10 +496,11 @@ pub fn create(
return Err(invalid("window registry missing"));
};
cx.dict_set(windows, Value::Text(id.to_string()), Value::Object(window))?;
// 返回创建的三个托管身份供桥接层建立 Presentation;此函数不直接申请 OS 资源或发起布局。
Ok((window, desktop, tabs))
}
/// 发起窗口关闭和相应生命周期清理,拒绝重复或不再有效的操作。
/// 取消窗口/页面任务并撤销登记,标记 closed 后安排原生关闭;重复关闭直接返回。
pub fn close(cx: &mut NativeContext<'_>, window: ObjectRef) -> Result<(), VmError> {
if cx.store().is_read_only() {
return Err(invalid(
@@ -494,17 +514,20 @@ pub fn close(cx: &mut NativeContext<'_>, window: ObjectRef) -> Result<(), VmErro
if data.closed {
return Ok(());
}
// 真实关闭边界先取消窗口与所有页面 owner 的任务,再撤销页面登记,防止晚到结果继续更新已关闭资源。
crate::tasks::cancel_owner(cx, window)?;
for page in data.pages.clone() {
crate::tasks::cancel_owner(cx, page)?;
unregister_page(cx, window, page)?;
}
// 循环内 unregister_page 已替换过 Window payload,必须重读最新副本,不能用最初 data 把已移除页面写回。
data = cx
.store()
.payload::<ManagedWindow>(window, "Window")?
.clone();
data.closed = true;
cx.replace_payload(window, data)?;
// 标记托管 closed 后仍可由内部 enqueue 安排原生 Close;成功输入发布前不会直接关闭系统窗口。
enqueue(cx, window, Action::Close)
}
@@ -512,6 +535,7 @@ pub fn close(cx: &mut NativeContext<'_>, window: ObjectRef) -> Result<(), VmErro
/// 撤销已失效窗口的托管资源关系,不重新执行源关闭请求。
pub fn retire(vm: &mut Vm, window: ObjectRef) -> Result<(), VmError> {
let mut data = vm.payload::<ManagedWindow>(window, "Window")?.clone();
// 故障域的宿主退役仅断开页面拥有边并标 closed,不跑用户回调、不重新生成源关闭命令。
vm.dict_clear(data.tabs)?;
data.pages.clear();
data.closed = true;