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
+2 -1
View File
@@ -1,6 +1,7 @@
//! 语言桥接模块入口。集中导出 Endor 类型和宿主实现之间的适配层。
//!
// Module ownership follows the directory; crate-root aliases keep internal call sites stable.
// 目录确定模块归属;main 中的 crate 根别名保持内部调用路径稳定。
/// 注册托管类型/宿主方法,验证参数并连接业务对象、Mount、视觉协议与窗口/任务资源。
pub(crate) mod ui_bridge;
pub(crate) mod graphics;
+93 -8
View File
@@ -30,6 +30,7 @@ pub const MAX_UI_NODES: usize = 4096;
pub const MAX_PAGES: usize = 64;
pub const MAX_DIMENSION: f64 = 1_000_000.0;
// 编译器已知宿主全局类型/能力名,同时用于 install_globals;仅列名不代表绕过实际 VM 名义类型查找。
pub const TYPE_NAMES: &[&str] = &[
"Object",
"Type",
@@ -102,7 +103,9 @@ struct Session {
current: u64,
master: ObjectRef,
next_window: u64,
// 跨窗口共用 Mount 高水位,避免某窗口取消/重建后与其他窗口已暴露出现 ID 重合。
next_mount: u64,
// 正常关闭副窗口后暂存尚待发布的 Close 等命令;Presentation 已移除也不能丢掉最后的原生退役请求。
retired_commands: Vec<crate::window::Command>,
refresh_yields: usize,
refresh_restarts: usize,
@@ -127,6 +130,7 @@ impl std::ops::Deref for Session {
type Target = crate::presentation::Presentation;
/// 将包装类型的只读访问转交给内部当前上下文。
fn deref(&self) -> &Self::Target {
// Session 解引用始终指向 current Presentation;调用源回调前切换窗口,结束后恢复主窗口,不能把它当全局唯一展示。
self.presentations
.get(&self.current)
.expect("selected presentation")
@@ -211,9 +215,10 @@ enum Operation {
}
impl Operation {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 返回该操作显式参数数量范围;这里不计接收者、Type 首参和源子类字段。
fn arity(self) -> endor_core::CallArity {
use Operation::*;
// 此 arity 只含显式参数;TypeMethod 另加 receiver,NativeFactory 另加 Type 和子类字段外壳。
let (minimum, maximum) = match self {
IsInstance | IsSubtype | Bind | Implement | Implements | Supports => (2, 2),
Stats | Viewport | Window | PageWindow | Mounts => (0, 0),
@@ -254,6 +259,7 @@ struct Function {
operation: Operation,
owner: Option<ObjectRef>,
session: Shared,
// 原生构造的实际源子类身份;自由 ui 工厂为 None,类型构造器显式传入 Some。
requested_type: Option<ObjectRef>,
}
@@ -291,7 +297,7 @@ impl NativeCallable for TypeMethod {
fn signature(&self) -> Option<CallSignature> {
Some(self.signature.clone())
}
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 在 Operation 的显式参数范围两端各加一,计入 VM 传入的隐式接收者。
fn arity(&self) -> Option<endor_core::CallArity> {
let arity = self.operation.arity();
Some(endor_core::CallArity::range(
@@ -300,8 +306,9 @@ impl NativeCallable for TypeMethod {
))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 校验首参是预期名义类型实例,再剥离接收者,复用 Function 分派执行同一 Operation。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
// 名义方法统一存在类型上,VM 把 receiver 放首参;校验后剥离 receiver 再交 Function 的显式参数分派。
let owner = object(args.first())?;
if !cx.store().is_instance(owner, self.expected)? {
return Err(invalid("incorrect receiver type for visual method"));
@@ -333,7 +340,7 @@ impl NativeCallable for NativeFactory {
fn signature(&self) -> Option<CallSignature> {
self.signature.clone()
}
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 要求原生必填参数再加一个请求 Type;上界暂开放,子类字段与原生选项在 invoke 内分别校验。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::range(
self.operation.arity().required + 1,
@@ -341,7 +348,7 @@ impl NativeCallable for NativeFactory {
))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 把请求类型的字段后缀与原生选项前缀分开验证,分配真实原生子类并初始化字段,避免非法字段先触发构造副作用。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
let requested = object(args.first())?;
let fields = cx
@@ -350,12 +357,14 @@ impl NativeCallable for NativeFactory {
.fields()
.to_vec();
let values = &args[1..];
// 构造实参末尾是类型声明的继承/自有字段,前缀才是原生构造选项;checked_sub 防止缺字段造成下溢。
let native_count = values
.len()
.checked_sub(fields.len())
.ok_or(invalid("missing subclass field arguments"))?;
cx.store()
.check_class_field_arguments(requested, &values[native_count..])?;
// 外壳允许宽变参,但原生前缀仍按具体 Operation 完整签名检查,不能因子类存在绕过类型或 arity。
self.options
.as_ref()
.ok_or(invalid("native factory is not initialized"))?
@@ -375,6 +384,7 @@ impl NativeCallable for NativeFactory {
let NativeResult::Return(Value::Object(instance)) = result else {
return Err(invalid("native constructor did not return an instance"));
};
// 分配器必须返回精确 requested 类型,不能只返回基类实例;之后才初始化子类字段。
if cx.store().type_of(instance)? != Some(requested) {
return Err(invalid(
"native constructor returned an incorrect nominal type",
@@ -429,6 +439,7 @@ fn dimension(value: Option<&Value>) -> Result<f32, VmError> {
let Some(Value::Number(number)) = value else {
return Err(invalid("expected a finite nonnegative dimension"));
};
// 分别支持大整数、十进制和二进制实数表示,不接受非实值;转 f64 后检查有限与范围,再降 f32。
let value = match number.as_real() {
Some(EndorReal::Integer(v)) => v.to_string().parse::<f64>().ok(),
Some(EndorReal::Decimal(v)) => v.literal().parse::<f64>().ok(),
@@ -461,6 +472,7 @@ fn bind(
session: session.clone(),
requested_type: None,
},
// 绑定方法显式捕获 owner 与 desktop,让托管 GC 识别函数的真实强边,Rust Shared 会话本身不隐式保活 VM 对象。
vec![owner, desktop],
))?;
attach_desktop_type(cx, function, "Function", desktop)?;
@@ -498,6 +510,7 @@ fn new_camera2d(
.unwrap_or(fallback);
cx.set_attr(camera, name, crate::native_visual::value(value))?;
}
// 初始化完所有相机属性后走完整相机校验,尤其 zoom 必须处于 0.01..100,不能只通过一般坐标范围。
crate::viewport::camera(cx.store(), camera)?;
Ok(camera)
}
@@ -530,6 +543,7 @@ fn new_typed_block(
.desktop;
let expected = desktop_type(cx.store(), type_name, desktop)?;
let type_object = requested.unwrap_or(expected);
// 叶/容器原生种类对应不同类型基类,禁止用 TextBlock 分配器创建并非其子类的名义对象。
if !cx.store().is_subtype(type_object, expected)? {
return Err(invalid("native constructor cannot allocate this subclass"));
}
@@ -537,6 +551,7 @@ fn new_typed_block(
cx.attach_type(block, type_object)?;
{
let mut state = session.lock().map_err(|_| invalid("UI session poisoned"))?;
// 节点弱表受宿主预算限制;实际死亡弱项通过后续 reclaim 压缩,不能把弱索引当永不增长的免费结构。
if state.nodes.len() >= MAX_UI_NODES {
return Err(VmError::ExecutionLimit("4096 node budget"));
}
@@ -572,6 +587,7 @@ fn create_window(
if state.exiting {
return Err(invalid("runtime is exiting; window creation is forbidden"));
}
// 同一 VM 最多16窗口(含主壳);ID 单调分配并限制到 i64 正范围,关闭后不复用旧资源身份。
if state.presentations.len() >= 16 {
return Err(VmError::ExecutionLimit("16 window budget"));
}
@@ -582,6 +598,7 @@ fn create_window(
.ok_or(invalid("window identities exhausted"))?;
let (window, desktop, tabs) = crate::window::create(cx, state.master, id, definition)?;
let mut presentation = crate::presentation::Presentation::new(desktop, tabs);
// 新窗口即使暂无内容也需发布有限空帧,让 GUI 根据投影创建 OS 窗口,而不是在 VM 中直接创建。
presentation.force_frame = true;
state.presentations.insert(id, presentation);
state.next_window = id;
@@ -610,6 +627,7 @@ fn remove_page(
) -> Result<(), VmError> {
let window = object(Some(&cx.store().get_attr(view.desktop, "window")?))?;
crate::window::unregister_page(cx, window, page)?;
// 双层 pending 区分无请求与请求清空;移除当前/待选页时改选剩余第一页,或显式 pending=None页面。
if view.pending.unwrap_or(view.active) == Some(page) {
let next = crate::window::pages(cx.store(), window)?.first().copied();
cx.set_attr(
@@ -631,6 +649,7 @@ fn show_in(
let mut state = session.lock().map_err(|_| invalid("UI session poisoned"))?;
let old = page_window(cx.store(), &state, page)?;
let id = match target {
// 显式目标窗口既要未关闭,也要对应本会话 Presentation 的同一 desktop,拒绝其他 VM 的窗口身份。
Some(window) => {
let data = cx
.store()
@@ -648,11 +667,13 @@ fn show_in(
}
id
}
// 不指定窗口时优先保留 Page 现有归属;未打开过的新页才进入 current,而非每次 activate 都迁移到主窗口。
None => old.unwrap_or(state.current),
};
if let Some(old) = old
&& old != id
{
// 跨窗口移动先撤源窗口登记与必要活动页选择,再在目标登记同一 Page,业务内容对象不复制。
remove_page(
cx,
state
@@ -669,6 +690,7 @@ fn show_in(
let window = object(Some(&cx.store().get_attr(view.desktop, "window")?))?;
crate::window::register_page(cx, window, page)?;
cx.set_attr(view.desktop, "pending", Value::Object(page))?;
// 仅记录展示请求并由 desktop.pending 强持有 Page;实际 active、Mount、布局和 published_version 留待刷新提交。
view.pending = Some(Some(page));
Ok(())
}
@@ -684,17 +706,18 @@ struct PresentResult {
session: Shared,
}
impl NativeCallable for PresentResult {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 接收 present 委托返回的唯一视觉对象,作为后续展示处理的输入。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(1))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 验证 present 结果为 Block;open 模式必要时包装 Page 并展示,否则只返回转换得到的视觉对象。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
let [Value::Object(root)] = args else {
return Err(invalid("Presentable.present must return a Block"));
};
let is_page = cx.store().payload::<block::Block>(*root, "Block")?.page;
// present 委托返回值必须为 Block;open=true 必要时包 Page 并展示,open=false 只返回转换结果。
let result = if self.open {
let page = if is_page {
*root
@@ -714,7 +737,7 @@ impl NativeCallable for PresentResult {
}
}
/// 根据 Presentable 能力把任意源值转换成可展示内容,避免只允许某个原生 Block 类型。
/// 返回已有 Block,或把其他值的可读表示包装成 TextBlock;Presentable 委托由外层调用分派负责。
fn present_value(
cx: &mut NativeContext<'_>,
value: &Value,
@@ -730,6 +753,7 @@ fn present_value(
{
return Ok(*block);
}
// 非 Block 的标量/对象转可读文字,Presentable 方法委托在 calls.rs 的更外层处理,本函数不自己调用 present。
let value = match value {
Value::Nil => "nil".into(),
Value::Bool(v) => v.to_string(),
@@ -771,7 +795,9 @@ struct LayoutContext {
full_viewport: Option<crate::layout::Size>,
desktop: ObjectRef,
window: u64,
// 布局同步返回的生命周期序列拥有根,暂留到安全提交边界执行/释放,取消时也必须清理。
hooks: Option<ObjectRef>,
// 布局准备可能暂改 Mount payload 与 desktop.mounts,检查点保证失败或尺寸重定向能恢复未发布关系。
checkpoint: crate::mount::Checkpoint,
}
@@ -796,6 +822,7 @@ fn invoke_member(
arguments: &[Value],
instruction_budget: usize,
) -> Result<Value> {
// 使用 VM 正常绑定规则创建临时方法值;无论 call 成功/失败,先保存 result 再释放 bound 根。
let bound = vm.bind_attr(owner, method)?;
let result = match &bound {
Value::Object(function) => vm
@@ -821,11 +848,13 @@ fn project_tabs(
) -> Result<Vec<crate::tabs::Tab>> {
let window = object(Some(&vm.get_attr(state.desktop, "window")?))?;
let pages = crate::window::pages(vm.object_store(), window)?;
// 标签选中反映待提交页面(若有请求),否则沿用 active;页面标题和顺序仍从真实窗口注册表提取。
let active = state.pending.unwrap_or(state.active);
let mut live = Vec::new();
let mut tabs = Vec::new();
for (index, page) in pages.iter().copied().enumerate() {
let weak = vm.object_store().downgrade(page)?;
// 同一 Page 弱身份复用该窗口标签 ID,新增页用高水位;移出后 live 更新会移除旧映射,不靠标题匹配。
let id = if let Some((_, id)) = state.tab_ids.iter().find(|(w, _)| *w == weak) {
*id
} else {
@@ -836,6 +865,7 @@ fn project_tabs(
state.next_tab
};
live.push((weak, id));
// 标题显示过滤控制字符并限制120个 Unicode 字符,缺失/空标题用默认序号;不修改原 Page.title。
let title = match vm.get_attr(page, "title") {
Ok(Value::Text(title)) if !title.is_empty() => title
.chars()
@@ -863,6 +893,7 @@ impl UiBridge {
/// already closed before source unmount hooks run, so they cannot remount.
/// 按窗口和展示生命周期执行有界退出清理,允许调用方根据故障状态决定是否执行回调。
pub fn shutdown(&self, vm: &mut Vm, callbacks: bool) -> Result<(usize, usize, usize)> {
// 退出先关闭新任务入口并取消旧任务,再标 session.exiting,避免卸载回调重新创建任务/窗口。
let tasks = self.tasks.quiesce(vm)?;
let mut drivers = Vec::new();
let mut mounts = 0;
@@ -877,6 +908,7 @@ impl UiBridge {
let view = state.presentations.get_mut(id).expect("known window");
let desktop = view.desktop;
mounts += view.mounts.active.len();
// 正常域用空结构 synchronize 安排孩子先卸载的 hooks;故障域直接 retire,不能再次执行用户代码。
if callbacks {
if let Some(hooks) = view.mounts.synchronize(
vm,
@@ -892,6 +924,7 @@ impl UiBridge {
view.mounts.retire(vm, desktop)?;
}
let window = object(Some(&vm.get_attr(desktop, "window")?))?;
// 所有窗口先标 closed 并断 Page 拥有关系,然后才在下面执行用户卸载 hooks,阻止回调重新打开已关闭窗口。
crate::window::retire(vm, window)?;
vm.set_attr(desktop, "pending", Value::Nil)?;
vm.set_attr(desktop, "focus", Value::Nil)?;
@@ -902,6 +935,7 @@ impl UiBridge {
Ok(ids.len())
})();
let mut result = prepared.map(|windows| (windows, mounts, tasks));
// 若之前清理/回调失败,余下 hooks 不再执行,但所有驱动根仍逐项 release,避免失败路径泄漏。
for (id, hooks) in drivers {
if result.is_ok() {
let call = (|| -> Result<()> {
@@ -951,6 +985,7 @@ impl UiBridge {
.lock()
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
let mut ids: Vec<_> = state.presentations.keys().copied().collect();
// 优先处理切离旧 active 页的窗口,使跨窗口迁移先退旧出现再挂新出现;同优先级按窗口 ID 稳定排序。
ids.sort_by_key(|id| {
let view = &state.presentations[id];
(
@@ -1009,6 +1044,7 @@ impl UiBridge {
vm.set_attr(desktop, "focus", Value::Nil)?;
vm.set_attr(desktop, "focusRequested", Value::Bool(false))?;
// Draining is not publication: failed-domain effects are discarded.
// 故障宿主退役的命令只丢弃不发布,防止失败域遗留 Resize/Focus 等影响当前原生状态。
let _ = crate::window::take_commands(vm, window)?;
let windows = object(Some(&vm.get_attr(state.master, "windows")?))?;
vm.dict_delete(windows, &Value::Text(id.to_string()))?;
@@ -1023,6 +1059,7 @@ impl UiBridge {
.session
.lock()
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
// 正常 finish_closed 只移除已标 closing 的副窗口,主壳保持到 OS 退出;其最后命令转存 retired_commands 待发布。
let ids: Vec<_> = state
.presentations
.iter()
@@ -1048,6 +1085,7 @@ impl UiBridge {
.session
.lock()
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
// 先取已移除窗口的最后命令,再合并仍活动窗口 outbox;按窗口/窗口内序号排序,不丢失正常 Close 请求。
let mut commands = std::mem::take(&mut state.retired_commands);
for view in state.presentations.values() {
let window = object(Some(&vm.get_attr(view.desktop, "window")?))?;
@@ -1071,6 +1109,7 @@ impl UiBridge {
.session
.lock()
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
// 尺寸比较在分配新输入对象前完成,避免相同 resize 通知改变 VM 版本而触发自我失效。
if state.layout.viewport == viewport {
return Ok(false);
}
@@ -1081,6 +1120,7 @@ impl UiBridge {
vm.set_attr(input, "height", Value::Number((size.height as f64).into()))?;
vm.set_attr(state.desktop, "viewport", Value::Object(input))
})();
// desktop 已建立 viewport 强边后释放局部根;字段/安装失败也先释放 input,再传播保存的错误。
vm.release(input)?;
result?;
} else {
@@ -1089,6 +1129,7 @@ impl UiBridge {
state.layout.viewport = viewport;
// A fresh Console domain can own window inputs without replacing the
// preserved displayed page until it actually opens/renders something.
// 空的新 Console 域可以记录逻辑尺寸,但未展示任何 Page 时不应覆盖用户仍看到的旧域画面。
state.force_frame |= state.active.is_some() || state.pending.flatten().is_some();
Ok(true)
}
@@ -1102,6 +1143,7 @@ impl UiBridge {
Value::Text("View".into()),
vm.get_attr(self.ui, "Block")?,
)?;
// 全局名引用 ui 中同一批名义类型/函数对象,模块和 Console 不会各复制一份类型体系。
for name in TYPE_NAMES.iter().chain(QUERY_NAMES) {
let value = vm.get_attr(self.ui, name)?;
vm.dict_set(globals, Value::Text((*name).into()), value)?;
@@ -1126,6 +1168,7 @@ impl UiBridge {
let Ok(state) = self.session.lock() else {
return false;
};
// 拖放源与目标都必须匹配各自发布版本,且真实 Page 注册顺序仍对应标签弱身份表,防止用陈旧列表下标重排。
for (id, version) in [
(input.window, input.layout_version),
(target.window, target.layout_version),
@@ -1173,6 +1216,7 @@ impl UiBridge {
if state.published_version != input.layout_version {
bail!("event targets an obsolete presentation");
}
// input.mount 在标签路径表示 Tab ID,先映回弱 Page,再确认仍在当前窗口 pages 集合,不是 Mount 几何下标。
let weak = state
.tab_ids
.iter()
@@ -1215,12 +1259,14 @@ impl UiBridge {
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
page_window(vm.object_store(), &state, page)?
};
// 源 moveToWindow 可覆盖并拒绝/改投其他窗口;只有确认实际归属仍为预期目标才继续重排与激活。
if destination == Some(target.window) {
let pages = crate::window::pages(vm.object_store(), window)?;
let from = pages
.iter()
.position(|candidate| *candidate == page)
.ok_or_else(|| anyhow::anyhow!("Page is no longer open"))?;
// 同窗口拖动的 index 是移除前插入缝位置,向后拖时先减一;跨窗口新加入则不用这一偏移修正。
let position = if input.window == target.window && from < target.index {
target.index - 1
} else {
@@ -1248,6 +1294,7 @@ impl UiBridge {
_ => "activate",
};
let value = invoke_member(vm, page, method, &[], 1_000_000)?;
// detach 返回值可能被源覆盖成其他值,仅确为 Window 且带屏幕位置才调用 moveTo;最后统一释放原返回值。
let placed = (|| -> Result<()> {
if input.kind == "tab-detach"
&& let Some([x, y]) = input.screen_position
@@ -1289,6 +1336,7 @@ impl UiBridge {
{
bail!("event belongs to another window");
}
// 窗口关闭通过名义 close 方法,保留源覆盖语义;直接调用宿主原生退役只用于故障清理路径。
if input.kind == "window-close" {
let desktop = self
.session
@@ -1312,6 +1360,7 @@ impl UiBridge {
vm.release_value(result?)?;
return Ok(());
}
// 内置工具打开走同一 VM 的 developerTools 能力,返回值只作临时根使用,不跨到 GUI。
if let Some(name) = input.kind.strip_prefix("developer-open:") {
let function = object(Some(&vm.get_attr(self.ui, "developerTools")?))?;
let page = vm.call(function, &[Value::Text(name.into())])?;
@@ -1336,6 +1385,7 @@ impl UiBridge {
) {
return self.dispatch_tab(vm, input);
}
// 普通指针输入取同一锁内的版本/目标/完整出现候选快照;随后不持 session 锁执行源 hitTest 或事件回调。
let (weak, desktop, candidates, viewport, surface) = {
let state = self
.session
@@ -1365,6 +1415,7 @@ impl UiBridge {
let point = input
.point
.ok_or_else(|| anyhow::anyhow!("scroll has no pointer"))?;
// scroll 不只校验 Mount 身份,还要指针仍在页面视口和出现裁剪中;相机/面板映射后的增量才可交给 scrollBy。
if !data.mounted
|| data.version != input.layout_version
|| !surface.contains(point, viewport)
@@ -1402,6 +1453,7 @@ impl UiBridge {
vm.release(mount)?;
return result;
}
// 坐标点击重新执行源协议选择按下和释放目标,二者同出现才分发;无坐标输入使用已捕获的弱目标。
let mount = if let (Some(press), Some(release)) = (input.press_point, input.point) {
if [press, release]
.iter()
@@ -1420,6 +1472,7 @@ impl UiBridge {
};
let result = (|| {
let data = vm.payload::<crate::mount::Mount>(mount, "Mount")?.clone();
// 3D 视口点击先生成 RayHit3D 并附到 Event.hit,再沿视口出现传播,不能只按二维外框假定击中某网格。
if data.geometry.scene3d_viewport
&& input.kind == "click"
&& let Some(point) = input.point
@@ -1478,6 +1531,7 @@ impl UiBridge {
vm.release_value(result?)?;
return Ok(());
}
// 普通点击/焦点先登记展示焦点请求,再按 kind 调 Block.click 或 Mount.requestFocus;生效仍需后续完整刷新。
vm.set_attr(
desktop,
"focus",
@@ -1510,6 +1564,7 @@ impl UiBridge {
}
/// 整理不再有效的弱索引与展示根,并配合 VM 回收,避免派生缓存延长业务对象生命周期。
pub fn reclaim(&self, vm: &mut Vm, _roots: &mut Vec<ObjectRef>) -> Result<()> {
// 先回收托管环,再扫描弱节点表,只保留能升级的身份;render_cache.prune 同步清除死亡业务索引。
vm.collect_cycles();
let mut state = self
.session
@@ -1538,6 +1593,7 @@ impl UiBridge {
let window = object(Some(&vm.get_attr(presentation.desktop, "window")?))?;
// A failed first render must not become visible on the next input
// merely because show() already registered its Page with the Window.
// 第一次 render 失败时撤销尚未发布的 Page 登记,避免下一次无关输入把失败页意外显示出来。
if presentation.active.is_none() && presentation.last_tabs.is_empty() {
let unpublished = crate::window::pages(vm.object_store(), window)?.to_vec();
for page in unpublished {
@@ -1545,6 +1601,7 @@ impl UiBridge {
}
}
let pages = crate::window::pages(vm.object_store(), window)?;
// 失败输入已成功执行的关闭/迁移语句不回滚;重新选择仍在真实窗口注册表中的页,修复 pending 与拥有关系。
let next = if presentation.closing {
None
} else {
@@ -1581,6 +1638,7 @@ impl UiBridge {
}
/// 重新评估已失效的属性绑定,并把结果计入会话统计。
pub fn refresh_bindings(&self, vm: &mut Vm) -> Result<()> {
// 只在锁内快照弱节点与宿主桌面集合,实际绑定回调在锁外执行,避免回调访问 UI 时死锁。
let (nodes, desktops) = {
let state = self
.session
@@ -1598,11 +1656,13 @@ impl UiBridge {
}
/// 排空一次 VM 变化记录并通知各窗口,提取活动页面快照,判断本次是否需要布局与发布。
pub fn prepare_frame(&self, vm: &mut Vm) -> Result<Option<Option<Arc<UiNode>>>> {
// 一次排空变更必须广播所有 Presentation,不能让先刷新的窗口吃掉其他窗口共享业务数据的失效通知。
let changes = vm.take_changes();
let mut state = self
.session
.lock()
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
// 本轮目标优先 pending,包括显式清空;快照提取返回 None 代表目标无页面,不等于无需刷新。
let active = state.pending.unwrap_or(state.active);
// One VM change drain feeds every presentation before selecting a root.
// Otherwise a window refreshed first could consume another window's work.
@@ -1612,6 +1672,7 @@ impl UiBridge {
let root = active
.map(|v| state.render_cache.snapshot(vm.object_store(), v))
.transpose()?;
// 视觉缓存用 Arc 身份快速判断根未变;即使根相同,焦点、滚动、标签或源依赖仍可能要求重绘。
let same = match (&root, &state.last_snapshot) {
(Some(a), Some(b)) => Arc::ptr_eq(a, b),
(None, None) => true,
@@ -1639,6 +1700,7 @@ impl UiBridge {
state.snapshot_visited = state.render_cache.visited;
state.snapshot_reused = state.render_cache.reused;
}
// 双层 Option 三态:外 None 无工作;Some(None) 需提交空帧;Some(Some(root)) 需布局/绘制根。
Ok(changed.then_some(root))
}
/// 提交已经完成的出现几何与快照,并处理展示生命周期;不把挂起或失败的布局当成已发布帧。
@@ -1655,6 +1717,7 @@ impl UiBridge {
let page = state.pending.unwrap_or(state.active);
let desktop = state.desktop;
let nodes = state.nodes.clone();
// 提交几何同步清除临时 layout Context,并产生挂载/卸载序列;提交桥接状态不等于已写 GUI 共享文档。
let hooks = state
.mounts
.synchronize(vm, desktop, page, nodes, frame, false)?;
@@ -1672,6 +1735,7 @@ impl UiBridge {
state.last_snapshot = snapshot;
state.last_tabs = frame.tabs.clone();
state.surface = frame.surface.clone();
// 让随后源回调看到本轮几何与版本,但真正对外原子发布要等整个刷新循环稳定,回调可能继续触发下一轮。
state.published_version = frame.layout_version;
// Hooks may call Page/container APIs; never hold the session mutex
// across user code. Publish only after the refresh loop settles.
@@ -1709,6 +1773,7 @@ impl UiBridge {
.session
.lock()
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
// 按最终帧绘制顺序查活动 Mount 弱身份,每条都必须存在;不按 HashMap 顺序调用源 paint。
let mounts = frame
.mounts
.iter()
@@ -1748,6 +1813,7 @@ impl UiBridge {
.session
.lock()
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
// 完成后过滤所有窗口私有 desktop 读取,再拆对象版本与名称依赖;挂起切片不覆盖上一份完成的 paint 依赖。
let desktops = state.host_desktops();
let reads = draft
.reads
@@ -1770,6 +1836,7 @@ impl UiBridge {
window: u64,
work: crate::source_paint::Work,
) -> Result<()> {
// 先尝试取消 VM 续体,再尝试选原窗口并强制下一帧;前一操作失败也执行必要的宿主失效准备。
let cancelled = work.cancel(vm);
let invalidated = self.select_window(window).and_then(|()| {
self.session
@@ -1792,6 +1859,7 @@ impl UiBridge {
!vm.has_suspended_call() && !vm.object_store().is_read_only(),
"cannot prepare another frame during suspended layout"
);
// 显式空页面无需源布局,清测量/布局读取并推进空帧版本,再同步退役旧 Mount;不是无工作返回。
let Some(root) = root else {
self.session
.lock()
@@ -1848,6 +1916,7 @@ impl UiBridge {
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
project_tabs(vm, &mut state)?
};
// 记录真实原生页面视口供页面相机 clamp;兼容 Page.mode 只改变根约束,不永久篡改保存的窗口尺寸。
let full_viewport = layout.viewport;
let surface = root.surface.clone().unwrap_or_default();
layout.page_mode = root.surface.as_ref().map(|surface| surface.mode);
@@ -1856,6 +1925,7 @@ impl UiBridge {
.session
.lock()
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
// 按全会话高水位分配结构出现 ID,取消后也不回收已暴露过的数值身份。
layout.reserve_identity_floor(state.next_mount);
}
let mut frame = layout.structure(&root)?;
@@ -1872,6 +1942,7 @@ impl UiBridge {
.session
.lock()
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
// 在准备态 synchronize 改写 Mount 前保留旧字典与 payload;准备失败立即恢复,不能留下半套父子关系。
let checkpoint = state.mounts.checkpoint(vm, desktop)?;
let hooks = match state
.mounts
@@ -1885,6 +1956,7 @@ impl UiBridge {
};
(hooks, state.mounts.ordered(), checkpoint)
};
// 检查点、暂存 hooks、所属窗口与根随源布局 Work 一起保留,跨量子不能只留下 VM 续体。
let context = LayoutContext {
surface,
root: root.clone(),
@@ -1945,6 +2017,7 @@ impl UiBridge {
checkpoint,
..
} = context;
// 恢复必须在原窗口;若窗口或 session 锁已不可用,至少释放检查点拥有根,不能尝试恢复到另一个窗口。
let selected = self.select_window(window);
let restored = if selected.is_ok() {
match self.session.lock() {
@@ -1961,6 +2034,7 @@ impl UiBridge {
} else {
checkpoint.release(vm).map_err(anyhow::Error::from)
};
// 无论选择/恢复是否失败都先尝试释放延迟 hooks;保存结果后再按优先级传播错误。
let released = hooks.map(|hooks| vm.release(hooks)).transpose();
selected?;
restored?;
@@ -1971,6 +2045,7 @@ impl UiBridge {
/// 取消源布局续体并清理对应上下文,保持已发布帧可用。
pub fn cancel_layout_frame(&self, vm: &mut Vm, pending: PendingLayout) -> Result<()> {
let PendingLayout { work, context } = pending;
// 取消只读执行与恢复 Mount 是两件事,均先尝试;没有继续执行原续体时也不能漏掉检查点恢复。
let cancelled = work.cancel(vm);
let restored = self.discard_layout_context(vm, context);
cancelled?;
@@ -1989,6 +2064,7 @@ impl UiBridge {
pending: PendingLayout,
) -> Result<LayoutProgress> {
let PendingLayout { work, context } = pending;
// 恢复时原窗口不存在则取消 owning VM 调用并清上下文,不重新建窗口或重放源布局。
if let Err(error) = self.select_window(context.window) {
let cancelled = work.cancel(vm);
let restored = self.discard_layout_context(vm, context);
@@ -2008,6 +2084,7 @@ impl UiBridge {
progress: Result<crate::source_layout::Progress>,
) -> Result<LayoutProgress> {
match progress {
// Pending 原样捆绑 Work 与 Context;Complete 才投影、提交,Error 则撤销准备态上下文。
Ok(crate::source_layout::Progress::Pending(work)) => {
Ok(LayoutProgress::Pending(Box::new(PendingLayout {
work,
@@ -2054,11 +2131,13 @@ impl UiBridge {
.session
.lock()
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
// 先在布局坐标中处理滚动,再叠二维视口/面板投影;绘制与输入共享最终 Frame 几何。
crate::scroll::project(vm, &state.mounts, &root, &mut frame)?;
crate::viewport::project(&root, &mut frame)?;
}
// Native layout may replace the structural Frame; attach chrome only
// after either layout path has produced the final page geometry.
// 小原生快速路径可能返回新的 Frame,标签/窗口与页面相机必须在最终布局之后重新附加。
frame.tabs = tabs;
frame.window = window;
if let Some(root) = frame.mounts.first() {
@@ -2080,6 +2159,7 @@ impl UiBridge {
// Shared intrinsic functions capture the primary desktop even when
// invoked from another window. Desktop bookkeeping is private host
// state; Window, viewport input and business dependencies remain.
// 源布局实际业务读取版本在生命周期 hooks 前保存,hooks 改写依赖后下一轮才能识别失效并重算。
reads.retain(|read| !desktops.contains(&read.object()));
cache.exclude_host_desktops(&desktops);
let (reads, names) = crate::presentation::split_reads(reads);
@@ -2087,6 +2167,7 @@ impl UiBridge {
Ok(Value::Number(id)) => id.as_i64().and_then(|n| u64::try_from(n).ok()),
_ => None,
};
// 焦点 ID 仅保留仍存在且可交互的出现,切页/树编辑移除目标后自动清掉失效焦点。
frame.focus = frame
.focus
.filter(|id| frame.mounts.iter().any(|m| m.id == *id && m.interactive));
@@ -2101,6 +2182,7 @@ impl UiBridge {
state.layout_reads = reads;
state.layout_names = names;
}
// 几何先提交到桥接状态,再执行准备阶段延后的挂载 hooks;其变化由全窗口刷新循环再收敛。
self.commit_frame(vm, Some(root), &frame)?;
if let Some(hooks) = hooks {
let value = vm
@@ -2117,6 +2199,7 @@ impl UiBridge {
}
Ok(frame)
})();
// 收尾计算无论成功/失败,都先释放 hooks 与检查点的拥有根;只有所有必要清理通过才返回帧。
let released_hooks = hooks.map(|hooks| vm.release(hooks)).transpose();
let released_checkpoint = checkpoint.release(vm);
let frame = result?;
@@ -2131,6 +2214,7 @@ impl UiBridge {
.session
.lock()
.map_err(|_| anyhow::anyhow!("UI session poisoned"))?;
// 此兼容提取接口只读取待展示 Page,不回退 active;持久增量路径使用 prepare_frame 的 active/pending 选择。
state
.pending
.flatten()
@@ -2171,6 +2255,7 @@ pub(crate) fn desktop_type(
name: &str,
desktop: ObjectRef,
) -> Result<ObjectRef, VmError> {
// 查当前 desktop 的实际字典对象和精确类型条目;不是按名字创建新类型,缺条目沿 object 解码报错。
let types = object(Some(&store.get_attr(desktop, "types")?))?;
object(store.dict_get(types, &Value::Text(name.into()))?.as_ref())
}
+20
View File
@@ -6,6 +6,7 @@ use super::*;
/// 把本模块的类型、方法或能力注册到所属运行时上下文。
pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
// 先建立 desktop/ui/tabs 并加入显式 roots,后面初始化失败时由上层运行时统一释放,避免依赖 Rust 句柄保活。
let desktop = vm.new_object()?;
roots.push(desktop);
vm.set_attr(desktop, "viewport", Value::Nil)?;
@@ -14,6 +15,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
vm.set_attr(desktop, "tabs", Value::Object(tabs))?;
let ui = vm.new_object()?;
roots.push(ui);
// 原生 Session 借用托管身份,主窗口先拥有独立 Presentation;业务对象仍全部位于传入的单一 VM。
let session = Arc::new(Mutex::new(Session {
nodes: Vec::new(),
presentations: std::collections::BTreeMap::from([(
@@ -33,6 +35,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
binding_evaluations: 0,
exiting: false,
}));
// 先分配函数占位再补签名,因为签名会引用尚未建立的名义类型;保存列表用于第二阶段替换 payload。
let mut public_functions = Vec::new();
let mut factories = Vec::new();
for (name, operation) in [
@@ -75,6 +78,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
vm.set_attr(ui, name, Value::Object(function))?;
public_functions.push((name, function, operation));
}
// Object/Type 来自 VM 类型引导,不能用普通类代替;之后所有宿主名义类型从此根体系建立。
let root_types = vm.bootstrap_types()?;
roots.extend([root_types.object, root_types.type_type]);
vm.set_attr(ui, "Object", Value::Object(root_types.object))?;
@@ -83,6 +87,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
("Object", root_types.object),
("Type", root_types.type_type),
];
// 类型按基类先于子类的顺序创建。None 表示抽象能力/宿主结果类型,不开放普通源构造器。
for (name, base_name, constructor_name) in [
("Trait", "Object", None),
("Function", "Object", None),
@@ -124,6 +129,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
] {
let base = object(Some(&vm.get_attr(ui, base_name)?))?;
let constructor = match constructor_name {
// ObjectList 与 Event 有特殊的“类型首参+子类字段”构造规则,单独原生适配;其他类型共用 NativeFactory。
Some("object-list") => {
let factory = vm.allocate(ContextNativeFunction::new(
"object-list",
@@ -150,6 +156,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
TypeConstructor::NativeTyped(factory)
}
Some(constructor_name) => {
// 把构造标签映射到宿主 Operation;3D 族委托其元数据,未知标签立即失败,不静默创建错误类型。
let operation = match constructor_name {
"text" => Operation::Text,
"rect" => Operation::Rect,
@@ -186,6 +193,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
}
None => TypeConstructor::Abstract,
};
// 记住实际工厂身份,类型构建完成后原地补签名,避免替换类型内指向的构造函数对象。
if let (Some(tag), TypeConstructor::NativeTyped(factory)) = (constructor_name, constructor)
{
factories.push((tag, factory));
@@ -195,6 +203,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
vm.set_attr(ui, name, Value::Object(definition))?;
definitions.push((name, definition));
}
// 协议值采用普通托管类:Constraints/Bounds/Point 等字段有类型注解,PaintCommand/CameraGesture 后续再初始化属性。
for (name, fields) in [
(
"Constraints",
@@ -212,6 +221,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
.into_iter()
.map(|name| endor_core::ClassField {
name: name.into(),
// children/commands 先声明 Object 接口,后续各协议解码器再要求受控列表;几何字段统一为 Number。
type_name: if matches!(name, "children" | "commands") {
"Object"
} else {
@@ -232,6 +242,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
}
// The desktop owns the registry through ordinary traced attributes. The
// Rust session only borrows handles and adds no hidden lifetime roots.
// 桌面通过普通属性拥有类型字典;后续 nominal 查询必须使用同一 desktop 中注册的精确类型身份。
let types = vm.new_dict()?;
roots.push(types);
for (name, definition) in definitions {
@@ -241,8 +252,10 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
vm.attach_type(desktop, root_types.object)?;
vm.attach_type(ui, root_types.object)?;
let function_type = object(Some(&vm.get_attr(ui, "Function")?))?;
// 让后续 VM 创建的函数使用宿主 Function 名义类型,并打开源类型检查,再安装完整本机签名。
vm.set_function_type(function_type)?;
vm.set_source_type_checks(true)?;
// 以同一函数身份补完 operation_signature,不改变先前 ui 属性引用的函数对象。
for (name, function, operation) in public_functions {
vm.replace_payload(
function,
@@ -284,6 +297,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
};
if let Some(operation) = operation {
let options = operation_signature(vm.object_store(), desktop, operation)?;
// 外层 NativeTyped 工厂接收 Type 首参和任意候选尾参,允许子类字段;NativeFactory 用 options 再核对基构造参数。
let envelope = CallSignature {
arity: endor_core::CallArity::range(options.arity.required + 1, usize::MAX),
parameters: vec![AnnotationType::Type.into()],
@@ -292,6 +306,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
effect: options.effect,
};
let mut captures = vec![desktop];
// 参数和返回注解中的名义类型也是托管引用,必须纳入 captures,不能只把它们存进 Rust 签名结构。
captures.extend(options.references());
vm.replace_payload(
function,
@@ -307,6 +322,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
),
)?;
} else {
// 特殊构造器保留宽变参外壳,再由对应 Constructor 按类型字段数拆实参,返回准确 Event/ObjectList 名义类型。
let kind = if name == "event" {
"Event"
} else {
@@ -377,6 +393,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
let function = object(Some(&vm.get_attr(ui, name)?))?;
vm.attach_type(function, function_type)?;
}
// 实例方法安装到对应名义类型;继承复用基类方法,TypeMethod 会验证实际接收者及参数契约。
for (type_name, name, operation) in [
("Block", "bind", Operation::Bind),
("OrbitController", "update", Operation::CameraControl),
@@ -429,12 +446,14 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
expected,
session: session.clone(),
},
// 方法 wrapper 捕获所属类型与桌面,保证分发和签名引用在方法仍存活时有效。
vec![expected, desktop],
))?;
roots.push(method);
vm.attach_type(method, function_type)?;
vm.define_method(expected, name, method)?;
}
// 类型与基础方法就绪后再装窗口、默认视觉、事件方法和能力契约,顺序满足各模块查类型/方法的前提。
crate::window::install(vm, roots, desktop, tabs)?;
let block_type = object(Some(&vm.get_attr(ui, "Block")?))?;
crate::native_visual::install(vm, roots, desktop, block_type, function_type)?;
@@ -442,6 +461,7 @@ pub fn install(vm: &mut Vm, roots: &mut Vec<ObjectRef>) -> Result<UiBridge> {
let token_type = object(Some(&vm.get_attr(ui, "Subscription")?))?;
crate::event_dispatch::install(vm, roots, event_type, token_type, function_type)?;
crate::protocols::install(vm, roots, desktop, ui)?;
// 每个桥接域配套自己的任务 Scheduler,再接工具入口及托管起始页工厂,最后返回可使用的 UiBridge。
let tasks = crate::tasks::install(vm, roots, ui, desktop)?;
crate::bridge::graphics::install(vm, roots, ui, desktop)?;
developer_pages::install(vm, ui, &session)?;
+43 -2
View File
@@ -9,16 +9,17 @@ impl NativeCallable for Function {
fn signature(&self) -> Option<CallSignature> {
self.signature.clone()
}
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 接收已经剥离 receiver 的显式参数,数量沿用 Operation 的范围。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(self.operation.arity())
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 统一校验数量与只读限制,再按 Operation 分派构造、树修改、页面、绑定、状态与能力调用,返回托管结果或 VM 续调用。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
use Operation::*;
let arity = self.operation.arity();
let (minimum, maximum) = (arity.required, arity.maximum);
// Function 接收已剥离 receiver 的显式参数;先校验数量,后面索引 args 才安全。
if !(minimum..=maximum).contains(&args.len()) {
return Err(invalid("incorrect UI method argument count"));
}
@@ -26,6 +27,7 @@ impl NativeCallable for Function {
let camera = new_camera2d(cx, &self.session, self.requested_type, args)?;
return Ok(NativeResult::Return(Value::Object(camera)));
}
// 3D 构造与普通 Block 分开,requested_type 保留源子类名义身份,否则从本 desktop 取默认类型。
if let SceneObject(kind) = self.operation {
let desktop = self
.session
@@ -58,6 +60,7 @@ impl NativeCallable for Function {
)?;
return Ok(NativeResult::Return(Value::Nil));
}
// implement 修改显式能力关系;implements 查类型,supports 查对象实际能力,不靠同名字段鸭子类型推断。
if matches!(self.operation, Implement | Implements | Supports) {
let capability = object(args.get(1))?;
let value = match self.operation {
@@ -92,6 +95,7 @@ impl NativeCallable for Function {
};
return Ok(NativeResult::Return(Value::Bool(value)));
}
// 显式失效属于模型变更,只读阶段拒绝;paint/layout/content 精度不同,后续分别清理对应缓存。
if matches!(self.operation, Invalidate) {
if cx.store().is_read_only() {
return Err(invalid(
@@ -115,6 +119,7 @@ impl NativeCallable for Function {
.lock()
.map_err(|_| invalid("UI session poisoned"))?;
let mut affected = std::collections::HashSet::new();
// 找出解析到同一底层 Data 的所有别名,失效共享数据时不能只刷新调用者包装身份。
for weak in &session.nodes {
if let Some(block) = cx.upgrade(*weak)?
&& block::resolve(cx.store(), block)?.0 == data
@@ -147,6 +152,7 @@ impl NativeCallable for Function {
}
}
}
// 跨窗口 Mount 查询按窗口/出现 ID 稳定排序,不依赖 HashMap 遍历顺序;返回每个具体出现而非几何副本。
positions.sort_unstable_by_key(|(window, id, _)| (*window, *id));
let set = crate::mount::collection(
cx,
@@ -179,6 +185,7 @@ impl NativeCallable for Function {
.session
.lock()
.map_err(|_| invalid("UI session poisoned"))?;
// 关闭托管窗口后为 Presentation 排空 pending 并标 closing,后续刷新才安排 Mount 退役与空帧。
if let Some(view) = state.presentations.get_mut(&id) {
cx.set_attr(view.desktop, "pending", Value::Nil)?;
view.pending = Some(None);
@@ -217,6 +224,7 @@ impl NativeCallable for Function {
)?,
)));
}
// 诊断会读对象总数与宿主变化统计,禁止在只读渲染中观察并形成反馈依赖。
if matches!(self.operation, Stats) {
if cx.store().is_read_only() {
return Err(invalid(
@@ -287,6 +295,7 @@ impl NativeCallable for Function {
)?;
return Ok(NativeResult::Return(Value::Object(stats)));
}
// 状态是普通名义 Object,value 属性经 VM 追踪,set/increment 方法捕获同一对象,不额外建立原生状态副本。
if matches!(self.operation, State) {
let state = cx.new_object()?;
attach_named_type(cx, state, "Object", &self.session)?;
@@ -303,6 +312,7 @@ impl NativeCallable for Function {
let Value::Number(value) = cx.store().get_attr(owner, "value")? else {
return Err(invalid("increment requires an integer state"));
};
// increment 要求可表示为 i64 的整数且加一不溢出,不能把任意浮点状态强转整数。
let next = value
.as_i64()
.and_then(|n| n.checked_add(1))
@@ -315,6 +325,7 @@ impl NativeCallable for Function {
if matches!(self.operation, TextOf) {
let source = object(args.first())?;
let field = text(args.get(1))?;
// textOf 建立前确认字段可读取,具体字符串化与依赖记录发生在快照提取时。
cx.store().get_attr(source, &field)?;
let size = args
.get(2)
@@ -334,6 +345,7 @@ impl NativeCallable for Function {
0.0,
0.0,
);
// 保留源对象强边与字段名,不在创建时复制一个静态字符串;后续属性变化会让文字快照重算。
data.text_binding = Some((source, field));
return Ok(NativeResult::Return(Value::Object(new_block(
cx,
@@ -341,6 +353,7 @@ impl NativeCallable for Function {
&self.session,
)?)));
}
// 普通组件先组装 Data,再统一由 new_typed_block 安装 Cell、属性和名义类型;不直接写原生窗口。
let constructor = match self.operation {
Scroll => Some(Data::new(
Kind::Scroll {
@@ -396,6 +409,7 @@ impl NativeCallable for Function {
} else {
Kind::Column
},
// 线性容器固定前两参为 padding/gap,后续都是孩子对象;组成合法性在 Block 分配前统一检查。
args[2..]
.iter()
.map(|v| object(Some(v)))
@@ -422,6 +436,7 @@ impl NativeCallable for Function {
0.0,
0.0,
);
// 每个新二维视口默认新建独立 Camera2D;显式属性共享相机才会联动其他视口。
data.camera = Some(new_camera2d(cx, &self.session, None, &[])?);
Some(data)
}
@@ -451,6 +466,7 @@ impl NativeCallable for Function {
data.camera = Some(camera);
data.scene3d = Some(object(args.get(2))?);
let definition = desktop_type(cx.store(), "OrbitController", desktop)?;
// 三维视口默认独立透视相机及 OrbitController,Scene3D 引用则来自调用者,可显式共享世界。
data.controller = Some(crate::scene3d_model::allocate(
cx,
desktop,
@@ -460,6 +476,7 @@ impl NativeCallable for Function {
)?);
Some(data)
}
// 按钮标签也是普通 TextBlock 孩子,布局和生命周期沿同一组成树,不是原生按钮硬编码文字。
Button => {
let label = new_block(
cx,
@@ -479,6 +496,7 @@ impl NativeCallable for Function {
}
_ => None,
};
// 统一检查文本等级和 UTF-8 字节量,再按 requested_type 生成实际对象,保留子类工厂身份。
if let Some(data) = constructor {
if let Kind::Text { size, value, .. } = &data.kind
&& (!(1..=8).contains(size) || value.len() > 16_384)
@@ -502,6 +520,7 @@ impl NativeCallable for Function {
.map_err(|_| invalid("UI session poisoned"))?;
(state.master, state.desktop)
};
// 非 Block 对象若显式支持 Presentable,调用其 present;已有 Block 直接进入下面的展示转换。
let capability = desktop_type(cx.store(), "Presentable", desktop)?;
if !cx
.store()
@@ -528,6 +547,7 @@ impl NativeCallable for Function {
},
vec![desktop],
))?;
// 小驱动先调用 present(value, window),再把结果交 PresentResult 验证/可选打开,所有委托共用当前 VM 预算。
let instructions = [
endor_core::Instruction::new(endor_core::Opcode::LoadConst, 0),
endor_core::Instruction::simple(endor_core::Opcode::PushNull),
@@ -560,6 +580,7 @@ impl NativeCallable for Function {
});
}
}
// ui.open 把普通结果转换为根组件,再在必要时包一层 Page 并展示;ui.present 仅转换,不自动打开页面。
if matches!(self.operation, OpenValue) {
let root = present_value(cx, &args[0], &self.session)?;
let page = if cx.store().payload::<block::Block>(root, "Block")?.page {
@@ -581,6 +602,7 @@ impl NativeCallable for Function {
&self.session,
)?)));
}
// 从这里起都是需要接收者的 Block/Page 方法,未绑定 owner 时不能继续修改任意全局对象。
let owner = self.owner.ok_or(invalid("method has no owner"))?;
if matches!(self.operation, Bind) {
let field = text(args.first())?;
@@ -598,6 +620,7 @@ impl NativeCallable for Function {
)?,
)));
}
// moveTab 重排同窗口页面索引并强制下一帧更新标签;移动的是原 Page,非新页面副本。
if matches!(self.operation, MoveTab) {
let position = usize::try_from(integer(args.first())?)
.map_err(|_| invalid("tab position out of range"))?;
@@ -615,6 +638,7 @@ impl NativeCallable for Function {
view.force_frame = true;
return Ok(NativeResult::Return(Value::Object(owner)));
}
// 接收者可能是共享转发别名,解析到最终 Data 后修改副本,最后用一次 replace_payload 写入结构边。
let (data_ref, data) = block::resolve(cx.store(), owner)?;
let mut data = data.clone();
let mut result = Value::Nil;
@@ -626,6 +650,7 @@ impl NativeCallable for Function {
return Err(invalid("text exceeds 16 KiB"));
}
*value = next;
// 直接 setText 取代旧 textOf 推导;同时更新普通 text 属性,使快照属性读取与 payload 描述保持一致。
data.text_binding = None;
cx.set_attr(owner, "text", args[0].clone())?;
}
@@ -654,8 +679,10 @@ impl NativeCallable for Function {
(data.children.len(), args.first())
};
let child = object(argument)?;
// 插入前禁止孩子图回到当前 Data,避免循环组成;position 是插入位置,返回值却是稳定 slot。
block::validate(cx.store(), child, Some(data_ref))?;
let slot = data.next_slot;
// slot 单调增加且限制到 i64 正范围,不复用已删除身份;前后插入/重排不会把其他孩子 slot 改号。
data.next_slot = slot
.checked_add(1)
.filter(|next| *next <= i64::MAX as u64)
@@ -663,6 +690,7 @@ impl NativeCallable for Function {
data.children.insert(position, Child { slot, block: child });
result = Value::Number((slot as i64).into());
} else {
// remove/replace/move 首参为稳定 slot 而非当前数组下标;只有 move 的第二参才是目标位置。
let slot = integer(args.first())?;
let index = data
.children
@@ -676,6 +704,7 @@ impl NativeCallable for Function {
Replace => {
let child = object(args.get(1))?;
block::validate(cx.store(), child, Some(data_ref))?;
// replace 保留该组成边 slot,但换实际 Block;出现键还含 Block 身份,因此可能产生新的 Mount 上下文。
data.children[index].block = child;
}
Move => {
@@ -691,6 +720,7 @@ impl NativeCallable for Function {
}
}
}
// children 查询返回 slot文本->Block 的托管字典,不把当前顺序假装成稳定 slot 连号数组。
Children => {
let result = cx.new_dict()?;
for child in data.children {
@@ -709,6 +739,7 @@ impl NativeCallable for Function {
let root = object(args.first())?;
block::validate(cx.store(), root, Some(data_ref))?;
if matches!(self.operation, Navigate) {
// 首次 navigate 把当前根纳入历史,之后新导航先截断前进分支,再追加新根,保持浏览历史语义。
if data.history.is_empty() {
if let Some(old) = data.children.first() {
data.history.push(old.block);
@@ -719,6 +750,7 @@ impl NativeCallable for Function {
data.history.push(root);
data.history_index = data.history.len() - 1;
}
// 页面内容统一保留根 slot0,render/navigate 改的是根对象;show 只记录待展示请求,后续刷新再布局。
data.children = vec![Child {
slot: 0,
block: root,
@@ -730,6 +762,7 @@ impl NativeCallable for Function {
if data.history.is_empty() {
return Ok(NativeResult::Return(Value::Nil));
}
// 后退/前进钳到历史首尾,复用已保留根对象而非重新执行旧源码。
let next = if matches!(self.operation, Back) {
data.history_index.saturating_sub(1)
} else {
@@ -742,6 +775,7 @@ impl NativeCallable for Function {
}];
show(cx, owner, &self.session)?;
}
// 分离先创建新 Window,再把同一 Page 展示到它;跨窗口出现上下文由后续展示同步重建。
Detach => {
let window = {
let mut state = self
@@ -780,10 +814,12 @@ impl NativeCallable for Function {
show_in(cx, owner, &self.session, target)?;
return Ok(NativeResult::Return(Value::Object(owner)));
}
// unmount 清内容但不关闭 Page 标签,也不直接等同于销毁整个业务对象。
Unmount => {
data.children.clear();
}
Close => {
// 关闭 Page 当场取消页面和所属 Mount 任务,即使同一输入稍后又打开它,也不能复活旧异步工作。
crate::tasks::cancel_owner(cx, owner)?;
let mut state = self
.session
@@ -828,6 +864,7 @@ impl NativeCallable for Function {
}
let handler = object(args.get(1))?;
crate::event_dispatch::validate_handler(cx.store(), handler)?;
// 订阅默认非捕获;可用 Bool 或 capture/bubble 文本明确阶段,其他值拒绝而不做真值转换。
let capture = match args.get(2) {
None | Some(Value::Bool(false)) => false,
Some(Value::Bool(true)) => true,
@@ -835,6 +872,7 @@ impl NativeCallable for Function {
Some(Value::Text(phase)) if phase == "bubble" => false,
_ => return Err(invalid("phase must be capture or bubble")),
};
// 清掉已断开连接后再计算容量,保留仍有效订阅顺序;新 Connection 拥有 handler,返回 token 仅弱引用连接。
let mut active = Vec::new();
for token in &data.subscriptions {
if cx
@@ -862,6 +900,7 @@ impl NativeCallable for Function {
data.subscriptions = active;
result = Value::Object(token);
}
// 基类事件/挂载回调默认空实现,子类可覆盖;不在这条默认路径生成额外状态。
OnEvent | OnMount | OnUnmount => return Ok(NativeResult::Return(Value::Nil)),
Click | Dispatch => {
let desktop = self
@@ -869,6 +908,7 @@ impl NativeCallable for Function {
.lock()
.map_err(|_| invalid("UI session poisoned"))?
.desktop;
// click 新建种类为 click 的 Event,dispatch 使用调用者提供事件;两者都将可选具体 Mount 交传播模块验证。
let (event, mount) = if matches!(self.operation, Click) {
let definition = desktop_type(cx.store(), "Event", desktop)?;
(
@@ -883,6 +923,7 @@ impl NativeCallable for Function {
}
_ => return Err(invalid("unsupported Block operation")),
}
// 非提前返回的结构编辑/订阅操作在末尾统一经过写屏障,触发拥有边更新和变更日志。
cx.replace_payload(data_ref, data)?;
Ok(NativeResult::Return(result))
}
+13 -2
View File
@@ -10,18 +10,20 @@ struct OpenTool {
ui: ObjectRef,
}
impl NativeCallable for OpenTool {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 仅接受一个工具名称字符串,工具类型与白名单在 invoke 检查。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(1))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 把白名单工具名转换成对应托管 Page;New tab 转交预编译工厂,其余管理页复用已有实例或创建新页。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
let [Value::Text(name)] = args else {
return Err(invalid("developerTools requires a tool name"));
};
// 工具名白名单包含四个管理页和特殊新标签动作,拒绝任意字符串进入工厂/工具标记路径。
if !["Console", "Sources", "Network", "Settings", "New tab"].contains(&name.as_str()) {
return Err(invalid("unknown developer tool"));
}
// 新标签交给预编译 ui.newTab 托管工厂,经 NativeResult::Invoke 回到同一 VM 执行。
if name == "New tab" {
let factory = object(Some(&cx.store().get_attr(self.ui, "newTab")?))?;
return Ok(NativeResult::Invoke {
@@ -29,6 +31,7 @@ impl NativeCallable for OpenTool {
arguments: vec![],
});
}
// 锁内只复制弱节点索引,之后逐个升级并查工具标记,不持 session 锁运行 show 的流程。
let nodes = self
.session
.lock()
@@ -39,6 +42,7 @@ impl NativeCallable for OpenTool {
if let Some(page) = cx.upgrade(weak)?
&& cx.store().get_attr(page, "_tesseraTool").ok() == Some(Value::Text(name.clone()))
{
// 已有同类工具页则激活并聚焦其所属原生窗口,不每次打开都创建重复 Page。
show(cx, page, &self.session)?;
let window = {
let state = self
@@ -56,6 +60,7 @@ impl NativeCallable for OpenTool {
return Ok(NativeResult::Return(Value::Object(page)));
}
}
// 没有现存工具页才创建空托管 Page,_tesseraTool 标记让宿主在该页面位置绘制对应管理工具。
let page = new_typed_block(
cx,
Data::new(Kind::Page, vec![], 0.0, 0.0),
@@ -78,6 +83,7 @@ pub(super) fn install(vm: &mut Vm, ui: ObjectRef, session: &Shared) -> Result<()
},
vec![ui],
))?;
// 函数 captures 保活 ui;安装属性建立拥有边后释放局部分配根,避免额外常驻根。
vm.set_attr(ui, "developerTools", Value::Object(function))?;
vm.release(function)?;
Ok(())
@@ -87,6 +93,7 @@ pub(super) fn install(vm: &mut Vm, ui: ObjectRef, session: &Shared) -> Result<()
/// Its functions/classes and callbacks remain ordinary managed VM objects.
/// 编译并安装 VM 私有的起始页工厂,供新页面动作重复调用。
pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
// 源码随 binary 嵌入,每个 VM 安装时解析/编译一次;函数工厂之后重复执行不再重复编译模块。
let source = frontend::EndorReader::from_text(
"tessera:start-page.endor",
include_str!("start_page.endor"),
@@ -96,6 +103,7 @@ pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
&ast,
&source,
&compiler::CompileOptions {
// 显式声明模块可见的 ui 与宿主类型名;私有 globals 不污染用户主会话的命名空间。
globals: std::iter::once("ui")
.chain(TYPE_NAMES.iter().copied())
.map(str::to_owned)
@@ -107,6 +115,7 @@ pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
let result = (|| -> Result<()> {
bridge.install_globals(vm, globals)?;
let code = compiled.load(vm)?;
// 执行模块定义类和工厂,使用单次预算;这里不主动调用 newTab,不在安装时打开页面。
let value = vm.execute_with_limits(
code,
globals,
@@ -117,12 +126,14 @@ pub(super) fn install_start_page(vm: &mut Vm, bridge: &UiBridge) -> Result<()> {
);
vm.release(code)?;
vm.release_value(value?)?;
// 要求模块导出 newTab,将函数保存到 ui 上;该函数通过托管引用维持自己的私有全局环境。
let factory = vm
.dict_get(globals, &Value::Text("newTab".into()))?
.ok_or_else(|| anyhow::anyhow!("start page module requires newTab"))?;
vm.set_attr(bridge.ui, "newTab", factory)?;
Ok(())
})();
// 无论编译代码执行或导出查找成功与否,释放私有字典的局部根,再返回保存的处理结果。
vm.release(globals)?;
result
}
+22
View File
@@ -11,6 +11,7 @@ impl UiBridge {
vm: &mut Vm,
input: &crate::events::Input,
) -> Result<()> {
// 锁内只读取当前发布版本与弱 Mount 身份,离开锁后才进入 VM 操作,避免持 session 锁调用用户代码。
let (weak, desktop) = {
let state = self
.session
@@ -33,6 +34,7 @@ impl UiBridge {
.upgrade(weak)?
.ok_or_else(|| anyhow::anyhow!("3D viewport Mount expired"))?;
let result = (|| {
// 除 session 发布版本外,再检查目标自身仍挂接、版本匹配且确为 3D 视口,拒绝旧出现操作。
let occurrence = vm.payload::<crate::mount::Mount>(mount, "Mount")?.clone();
anyhow::ensure!(
occurrence.mounted
@@ -45,6 +47,7 @@ impl UiBridge {
let camera = data
.camera
.ok_or_else(|| anyhow::anyhow!("missing 3D camera"))?;
// 显式配置 controller 才能接收 3D 手势;没有控制器的场景仍可显示,但不能自动修改相机。
let controller = data
.controller
.ok_or_else(|| anyhow::anyhow!("3D controller disabled"))?;
@@ -55,6 +58,8 @@ impl UiBridge {
let delta = input
.delta
.ok_or_else(|| anyhow::anyhow!("3D camera delta required"))?;
// 缩放使用倍率而非二维位移;旋转/平移通过 logical_delta 处理嵌套二维/面板投影。
// 不可逆映射时忽略本次连续增量,不在无效坐标上继续更新相机。
let local_delta = if input.kind == "scene-zoom" {
[0., 0.]
} else {
@@ -63,6 +68,7 @@ impl UiBridge {
};
delta
};
// 可用锚点先映回所在视口空间;无法取得时使用内容左上角,传给控制器的是扣除 inset 的局部点。
let point = input
.point
.and_then(|p| geometry.view_point(crate::geometry::Point::new(p[0], p[1]), false))
@@ -71,6 +77,7 @@ impl UiBridge {
geometry.x + inset.left,
geometry.y + inset.top,
));
// 将输入封装为名义 CameraGesture 临时对象;不把原生 Input 或窗口指针直接交给源控制器。
let gesture = vm.new_object()?;
let result = (|| {
vm.attach_type(
@@ -81,6 +88,7 @@ impl UiBridge {
for (name, value) in [
("dx", local_delta[0]),
("dy", local_delta[1]),
// factor 复用原 delta 第一项,仅缩放种类按倍率解释;dx/dy 已经转换为逻辑位移。
("factor", delta[0]),
("width", (geometry.width - inset.horizontal()).max(0.)),
("height", (geometry.height - inset.vertical()).max(0.)),
@@ -89,6 +97,7 @@ impl UiBridge {
] {
vm.set_attr(gesture, name, crate::native_visual::value(value))?;
}
// 绑定 controller.update 保留接收者语义,再带 camera/gesture 两个显式参数进行有界调用。
let function = vm.bind_attr(controller, "update")?;
let result = match function {
Value::Object(function) => vm.call_with_limits(
@@ -101,13 +110,16 @@ impl UiBridge {
),
_ => Err(invalid("controller.update is not callable")),
};
// 先保存调用结果再释放绑定方法,错误路径同样清理;成功返回值也不保留为业务状态。
vm.release_value(function)?;
vm.release_value(result?)?;
Ok(())
})();
// 临时手势无论控制器成功或失败均释放,然后返回先前处理结果。
vm.release(gesture)?;
result
})();
// upgrade 得到的拥有根在闭包执行后统一释放,内部任一步失败也不会遗留该临时根。
vm.release(mount)?;
result
}
@@ -118,6 +130,7 @@ impl UiBridge {
vm: &mut Vm,
input: &crate::events::Input,
) -> Result<()> {
// 二维视口同样先校验发布版本,再从活动表捕获原 Mount,不能因目标消失自动换成另一个视口。
let weak = {
let state = self
.session
@@ -151,6 +164,7 @@ impl UiBridge {
let camera = data
.camera
.ok_or_else(|| anyhow::anyhow!("viewport has no camera"))?;
// 读取已校验的相机快照作为本次基准;共享相机用户会通过普通属性变更观察到相同更新。
let old = crate::viewport::camera(vm.object_store(), camera)?;
let delta = input
.delta
@@ -170,6 +184,7 @@ impl UiBridge {
.ok_or_else(|| anyhow::anyhow!("zoom anchor cannot be projected"))?;
let node = block::snapshot(vm.object_store(), block)?;
let inset = crate::layout::insets(&node);
// 已验证指针落在出现外框还不够;扣除 inset 后必须落入实际内容盒,禁止用边框作为缩放锚点。
let local = [
pointer.x - geometry.x - inset.left,
pointer.y - geometry.y - inset.top,
@@ -181,6 +196,7 @@ impl UiBridge {
&& local[1] < geometry.height - inset.vertical(),
"zoom anchor is outside content viewport"
);
// 以实际钳制后的新 zoom 反求 pan,保持锚点下世界位置:old_pan + local/old_zoom = new_pan + local/new_zoom。
zoom = (old.zoom * delta[0]).clamp(0.01, 100.0);
x += local[0] / old.zoom - local[0] / zoom;
y += local[1] / old.zoom - local[1] / zoom;
@@ -188,9 +204,11 @@ impl UiBridge {
let Some(delta) = geometry.logical_delta(input.point, delta) else {
return Ok(());
};
// 屏幕/父层逻辑位移先撤销外层投影,再除本视口 zoom 转为相机世界偏移,不能直接加原像素增量。
x += delta[0] / zoom;
y += delta[1] / zoom;
}
// 把世界偏移限制回模型坐标预算,再走 set_attr 变更追踪,不直接改原生渲染快照。
x = x.clamp(-MAX_DIMENSION as f32, MAX_DIMENSION as f32);
y = y.clamp(-MAX_DIMENSION as f32, MAX_DIMENSION as f32);
vm.set_attr(camera, "x", crate::native_visual::value(x))?;
@@ -208,6 +226,7 @@ impl UiBridge {
vm: &mut Vm,
input: &crate::events::Input,
) -> Result<()> {
// 兼容 Page 相机不通过 Mount 定位,而是读取当前活动页面及其 Surface 副本;发布版本仍必须一致。
let (page, mut surface, viewport) = {
let state = self
.session
@@ -243,6 +262,7 @@ impl UiBridge {
&& viewport.is_none_or(|v| pointer.x < v.width && pointer.y < v.height),
"zoom anchor is outside viewport"
);
// 先保留旧缩放下锚点对应的世界点,再调整 zoom 并解新 pan,避免缩放时内容从光标下漂移。
let world = surface.to_world(pointer);
surface.zoom = (surface.zoom * delta[0]).clamp(0.1, 4.0);
surface.pan = crate::geometry::Point::new(
@@ -253,12 +273,14 @@ impl UiBridge {
surface.pan.x += delta[0] / surface.zoom;
surface.pan.y += delta[1] / surface.zoom;
}
// 有限页面按当前内容/视口钳制;Window 会重置导航,Canvas 则保留自由 pan/zoom。
if let Some(viewport) = viewport {
surface.clamp(viewport);
}
let limit = MAX_DIMENSION as f32;
surface.pan.x = surface.pan.x.clamp(-limit, limit);
surface.pan.y = surface.pan.y.clamp(-limit, limit);
// 最终回写活动 Page 的普通托管属性,后续刷新重新提取 Surface;此函数不直接发布原生帧。
vm.set_attr(page, "panX", crate::native_visual::value(surface.pan.x))?;
vm.set_attr(page, "panY", crate::native_visual::value(surface.pan.y))?;
vm.set_attr(page, "zoom", crate::native_visual::value(surface.zoom))?;
+16
View File
@@ -14,6 +14,8 @@ pub(super) fn method_signature(
use AnnotationType::{Any, Function, Nominal, Number, String as TextType, Unit};
use Operation::*;
let nominal = |name| desktop_type(store, name, desktop).map(Nominal);
// 先描述显式实参,不含隐式 receiver;后面统一在 parameters 首部补接收者。
// ReadOnly/Mutating/External 是 VM 调用效果契约,不是线程调度策略。
let (arguments, returns, effect) = match operation {
Translate3D | Rotate3D => (vec![Number, Number, Number], Unit, CallEffect::Mutating),
CameraControl => (
@@ -21,6 +23,7 @@ pub(super) fn method_signature(
Unit,
CallEffect::Mutating,
),
// 绑定创建可取消 Subscription,并改写目标连接关系,因此属于 Mutating。
Bind => (
vec![TextType, Function],
nominal("Subscription")?,
@@ -30,6 +33,7 @@ pub(super) fn method_signature(
Children => (vec![], Any, CallEffect::ReadOnly),
Invalidate => (vec![TextType], Unit, CallEffect::Mutating),
SetText | SetColor => (vec![TextType], Unit, CallEffect::Mutating),
// append/insert 返回稳定 slot 数值;remove/replace/move 返回 Unit,调用方不能把它们当返回孩子对象的集合方法。
Append => (vec![nominal("Block")?], Number, CallEffect::Mutating),
Insert => (
vec![Number, nominal("Block")?],
@@ -40,7 +44,9 @@ pub(super) fn method_signature(
Replace => (vec![Number, nominal("Block")?], Unit, CallEffect::Mutating),
Move => (vec![Number, Number], Unit, CallEffect::Mutating),
Render | Navigate => (vec![nominal("Block")?], Unit, CallEffect::Mutating),
// 链式 API 返回接收者名义类型,保留子类返回契约,而不是统一降为 Block。
OnClick => (vec![Function], Nominal(receiver), CallEffect::Mutating),
// 事件和生命周期方法可能执行任意用户回调,使用 External,不能冒充只读视觉查询。
OnEvent => (vec![nominal("Event")?], Unit, CallEffect::External),
OnMount | OnUnmount => (vec![nominal("Mount")?], Unit, CallEffect::External),
Click => (
@@ -71,6 +77,7 @@ pub(super) fn method_signature(
),
_ => return Err(invalid("unsupported native method signature")),
};
// Operation 维护显式参数的必需/最大个数;方法签名整体加一,将 receiver 纳入调用约定。
let arity = operation.arity();
let mut parameters = vec![Nominal(receiver)];
parameters.extend(arguments);
@@ -81,6 +88,8 @@ pub(super) fn method_signature(
returns: returns.into(),
effect,
};
// 少数参数/返回需要联合或可空类型,先用占位 Any 建基础签名,再按下标细化。
// On 第三个显式选项位于 parameters[3],可接受 Bool 或字符串。
match operation {
Open => signature.parameters[1] = CallType::nullable(nominal("Window")?),
PageWindow => signature.returns = CallType::nullable(nominal("Window")?),
@@ -99,6 +108,7 @@ pub(super) fn operation_signature(
use AnnotationType::{Any, Bool, Number, String as TextType, Trait, Type, Unit};
use Operation::*;
let nominal = |name| desktop_type(store, name, desktop).map(AnnotationType::Nominal);
// 自由 UI 操作没有隐式 receiver;同时声明固定参数、可变尾参、返回名义类型和调用效果。
let (parameters, variadic, returns, effect) = match operation {
IsInstance => (vec![Any, Type], None, Bool, CallEffect::ReadOnly),
IsSubtype => (vec![Type, Type], None, Bool, CallEffect::ReadOnly),
@@ -106,6 +116,7 @@ pub(super) fn operation_signature(
Implements => (vec![Type, Trait], None, Bool, CallEffect::ReadOnly),
Supports => (vec![Any, Trait], None, Bool, CallEffect::ReadOnly),
OpenValue => (vec![Any], None, nominal("Page")?, CallEffect::Mutating),
// present 可能转交用户展示协议,效果交由被委托调用确定,不能声明成固定 ReadOnly。
Present => (vec![Any], None, nominal("Block")?, CallEffect::Delegated),
State => (vec![Any], None, Any, CallEffect::ReadOnly),
StateSet => (vec![Any], None, Unit, CallEffect::Mutating),
@@ -119,6 +130,7 @@ pub(super) fn operation_signature(
),
Window => (vec![], None, nominal("Window")?, CallEffect::ReadOnly),
NewWindow => (vec![], None, nominal("Window")?, CallEffect::Mutating),
// 这些构造操作返回新对象,ReadOnly 允许分配并初始化新值,但不允许因此修改已有业务对象。
TextOf => (
vec![Any, TextType, Number, TextType],
None,
@@ -144,6 +156,7 @@ pub(super) fn operation_signature(
nominal("ScrollBlock")?,
CallEffect::ReadOnly,
),
// 布局容器前两个固定参数是 Number,其后每个尾参都必须是 Block,返回类型按具体构造器选取。
Row | Column | Overlay => (
vec![Number, Number],
Some(nominal("Block")?),
@@ -169,6 +182,7 @@ pub(super) fn operation_signature(
nominal("Viewport3D")?,
CallEffect::ReadOnly,
),
// 3D 构造器参数来自 Kind 元数据:Number/String 映成基础注解,其余名称从本 desktop 注册表查名义类型。
SceneObject(kind) => {
let parameters = kind
.parameters()
@@ -181,6 +195,7 @@ pub(super) fn operation_signature(
.collect::<Result<Vec<_>, VmError>>()?;
(
parameters,
// 3D 集合尾参使用 Object 名义约束;各具体构造操作仍需在实现中检查允许的场景对象类别。
if kind.variadic() {
Some(nominal("Object")?)
} else {
@@ -210,6 +225,7 @@ pub(super) fn operation_signature(
),
_ => return Err(invalid("unsupported UI function signature")),
};
// 最终 arity 直接沿用 Operation,参数注解与可变尾参分开保存;不在此处执行操作或分配业务对象。
Ok(CallSignature {
arity: operation.arity(),
parameters: parameters.into_iter().map(CallType::from).collect(),
+16
View File
@@ -2,12 +2,15 @@
// 默认页由真实 Endor 对象组成:宿主负责窗口和侧栏,卡片布局、绘制和按钮回调在源代码中定义。
// Note 复用 Column 的内容测量,但固定卡片宽度;paint 只提供背景,孩子仍沿正常树绘制。
class Note: Column {
// 卡片构造的最后一个子类字段保存背景色;前面的变参仍按 Column 的孩子参数处理。
tint: String
function measure(self: Note, mount: Mount, constraints: Constraints): MeasureResult {
// 沿用 Column 内容测量得到高度,但卡片宽固定为 224;不把背景圆角绘制误当布局尺寸。
measured = Column.measure(self, mount, constraints)
return MeasureResult(224, measured.height)
}
function paint(self: Note, mount: Mount, geometry: Bounds): DisplayList {
// 只生成当前卡片背景,命令使用宿主给定 Bounds 的绝对布局位置,孩子仍由各自 paint 绘制。
fill = PaintCommand()
fill.kind = "roundedRect"
fill.x = geometry.x
@@ -16,15 +19,18 @@ class Note: Column {
fill.height = geometry.height
fill.radius = 14
fill.color = self.tint
// DisplayList 中的 commands 必须是受检查 ObjectList,且成员为 PaintCommand,不能返回普通字符串。
return DisplayList(ObjectList(fill))
}
}
// 继承 Button 的事件能力与内容布局,仅覆盖自身背景 paint。
class QuietButton: Button {
// 返回空绘制列表保留 Button 的交互能力,同时让这个入口只显示孩子文字。
function paint(self: QuietButton, mount: Mount, geometry: Bounds): DisplayList {
return DisplayList(ObjectList())
}
}
// 动作对象集中保存回调和 home 引用;按钮绑定方法会按托管引用关系保留动作对象。
class StartActions {
// 保存起始页面身份,子页面中的返回按钮激活同一 Page,而不是复制一份页面。
home: Page
@@ -33,6 +39,7 @@ class StartActions {
page = Page()
page.title = "窗口页面"
back = Button("返回画布")
// 绑定的是原 home 的 activate 方法;此回调恢复已有页身份,不重新构造主画布。
back.onClick(self.home.activate)
page.render(Column(56, 20, TextBlock("恰好一个窗口", 3), TextBlock("页面跟随可用区域调整。内容和工具栏由 Endor 自己组织。"), back))
}
@@ -45,10 +52,12 @@ class StartActions {
content.append(Note(24, 16, TextBlock("02 / 连接片段", 2), RectBlock(176, 130, 10, "#E6DBEF"), TextBlock("内容保留在同一条连续的页面里。"), "#F4EEF7"))
content.append(Note(24, 16, TextBlock("03 / 慢慢展开", 2), RectBlock(176, 130, 10, "#EDDCC5"), TextBlock("追加一个子组件,内容自然延伸。"), "#FAF2E7"))
content.append(Note(24, 16, TextBlock("04 / 留一点空白", 2), TextBlock("不必把所有想法都放在第一屏。"), "#EDF1F6"))
// 固定初始视口内装完整内容;下一行限制滚动轴,flex 和页面 stretch 再让视口服从窗口分配。
view = ScrollBlock(1024, 800, content)
view.axis = "vertical"
view.flex = 1
page.crossAlign = "stretch"
// 最后提交有限视口作为 Page 内容,触发展示请求;真正的测量、绘制与原生发布由宿主刷新流程完成。
page.render(view)
}
// Row 内可继续放 Column 卡片;横向滚动不要求改变 Page 的身份或生命周期。
@@ -61,6 +70,7 @@ class StartActions {
content.append(Note(24, 16, TextBlock("继续", 2), RectBlock(176, 230, 10, "#EFDFC7"), TextBlock("Shift + 滚轮浏览更多内容。"), "#FAF3E8"))
content.append(Note(24, 16, TextBlock("不止一屏", 2), TextBlock("右侧仍有空间。"), "#EEF1F5"))
view = ScrollBlock(1024, 800, content)
// Row 自然宽度可超出视口,只有横向滚动;卡片内部仍是 Column 的纵向排版。
view.axis = "horizontal"
view.flex = 1
page.crossAlign = "stretch"
@@ -68,10 +78,12 @@ class StartActions {
}
// 重新调用工厂得到独立页面与相机,已有画布继续保留自己的视角。
function canvas(self: StartActions, event: Event): Unit {
// 每次动作都调用工厂,得到新 Page、世界树和独立相机,不复用当前页的视角状态。
page = newTab()
}
// 两个文字绑定观察同一个状态对象,示范共享业务状态与多个展示位置的区别。
function counter(self: StartActions, event: Event): Unit {
// 共享的是同一个托管状态对象;textOf 两次读取该对象 value,increment 更新后两个展示一起刷新。
count = ui.state(0)
add = Button("增加计数")
add.onClick(count.increment)
@@ -84,12 +96,14 @@ class StartActions {
function newTab(): Page {
page = Page()
page.title = "自由画布"
// 先建立引用当前 Page 的动作对象,再绑定按钮;回调中的 home 指向这一轮工厂创建的页面。
actions = StartActions(page)
fixed = Button("窗口页面")
vertical = Button("纵向延伸")
horizontal = Button("横向延伸")
canvas = Button("新的画布")
shared = QuietButton("试试:一个对象,两个视图 ↗")
// 订阅绑定方法而非提前调用;事件触发后在原 VM 中创建/展示相应示例页。
fixed.on("click", actions.blank)
vertical.on("click", actions.vertical)
horizontal.on("click", actions.horizontal)
@@ -99,10 +113,12 @@ function newTab(): Page {
// x/y 属于 Scene2D 子组件的世界位置;卡片内部依旧由普通 Row/Column 排版。
hero.x = 316
hero.y = 254
// Scene2D 只规定孩子的世界位置;加入后仍可追加普通卡片,位置不受窗口宽高限制。
world = Scene2D(hero)
left = Note(24, 14, TextBlock("随手记下", 2), RectBlock(176, 100, 10, "#D5E4DA"), TextBlock("想法不必排成一条直线。"), "#EDF3E9")
left.x = 36
left.y = 92
// 将卡片以稳定 slot 加入场景;其 x/y 在前面单独设置,不依赖追加次序推算位置。
world.append(left)
top = Note(24, 14, TextBlock("四种页面,同一个世界"), TextBlock("窗口 · 纵向 · 横向 · 自由画布", 1, "#7D858C"), "#EFF1F7")
top.x = 466
+16
View File
@@ -16,6 +16,7 @@ pub struct UiNode {
pub align_self: Option<crate::layout::CrossAlign>,
pub margin: crate::layout::Insets,
pub sizing: crate::box_model::Sizing,
// 单边可选覆盖值;None 表示沿用 kind 的统一 padding,不代表边距为零。
pub padding_edges: [Option<f32>; 4],
pub border: crate::layout::Insets,
pub border_color: String,
@@ -25,6 +26,7 @@ pub struct UiNode {
pub protocol_key: String,
// slot 保持组成身份;数组次序确定当前绘制/布局顺序,二者不是同一概念。
pub slots: Vec<u64>,
// 从按钮、点击连接或自定义事件等能力推导的交互资格,供命中宽阶段使用,不代表最终 hitTest 必然成功。
pub interactive: bool,
pub pointer_events: bool,
pub kind: UiKind,
@@ -49,6 +51,7 @@ impl UiNode {
/// 判断是否需要对子项执行弹性主轴分配。
pub fn has_flex(&self) -> bool {
// 不仅旧 flex 数值,非默认 FlexPolicy 或任一轴 Fill 也要求父节点执行分配,不能仅按自然尺寸排布。
self.flex > 0.0
|| self.flex_policy != crate::layout::FlexPolicy::default()
|| self.sizing.width == crate::box_model::Dimension::Fill
@@ -57,6 +60,7 @@ impl UiNode {
/// 判断当前节点是否会为子项指定实际分配范围,供源布局选择安排路径。
pub fn allocates_children(&self) -> bool {
// 任何孩子需要弹性或拉伸即进入分配路径;align_self 优先于父 cross_align。
self.children().iter().any(|child| {
child.has_flex()
|| child.align_self.unwrap_or(self.cross_align)
@@ -66,6 +70,7 @@ impl UiNode {
/// 比较节点自身配置和直接子项身份,决定能否复用旧 Arc;不是深拷贝业务图。
pub fn shallow_eq(&self, other: &Self) -> bool {
// 先比较所有公共视觉/协议配置,任一变化都不能复用旧节点 Arc,即使子内容完全相同。
if self.surface != other.surface
|| self.flex_policy != other.flex_policy
|| self.flex != other.flex
@@ -86,6 +91,7 @@ impl UiNode {
{
return false;
}
// 直接孩子按 Arc 指针比较而不是递归深比较;依赖提取保证未变子树复用 Arc,父级只需验证其身份。
let same_children = || {
self.children().len() == other.children().len()
&& self
@@ -94,6 +100,7 @@ impl UiNode {
.zip(other.children())
.all(|(a, b)| Arc::ptr_eq(a, b))
};
// 同类变体再比较其专有数据和直接子项;变体不同必为 false,避免布局种类切换后误复用缓存。
match (&self.kind, &other.kind) {
(
UiKind::Viewport3D {
@@ -213,6 +220,7 @@ impl UiNode {
#[derive(Debug, Clone, PartialEq)]
/// 视觉内容的原生分类。叶节点保存绘制数据,容器保存子树,场景视口另外保存相机与世界投影。
pub enum UiKind {
// 有限 3D 视口包含不可变场景视图和面板 UI 孩子;panels 与 children/slots 按顺序对应。
Viewport3D {
width: f32,
height: f32,
@@ -221,29 +229,35 @@ pub enum UiKind {
panels: Vec<crate::layout::Size>,
children: Vec<Arc<UiNode>>,
},
// 二维世界组成保留孩子的显式位置,不使用行列的累计偏移定位。
Scene2D {
positions: Vec<[f32; 2]>,
children: Vec<Arc<UiNode>>,
},
// 有限布局盒子观察独立 Scene2D,相机仅影响投影,不改变场景节点原始逻辑位置。
CanvasViewport {
width: f32,
height: f32,
camera: crate::viewport::CameraView,
children: Vec<Arc<UiNode>>,
},
// 孩子重叠布置,顺序同时决定叠放次序;普通有限布局与世界 Canvas 不同。
Overlay {
padding: f32,
children: Vec<Arc<UiNode>>,
},
// 旧 Page Canvas 模式的兼容投影,位置数组与孩子顺序一致,页面级 Surface 保存其相机。
Canvas {
positions: Vec<[f32; 2]>,
children: Vec<Arc<UiNode>>,
},
// 按钮是有子内容的容器,不把标签文本硬编码进 UiKind;交互资格另由 UiNode 标志表达。
Button {
padding: f32,
gap: f32,
children: Vec<Arc<UiNode>>,
},
// 文字叶节点保留源字号等级与颜色文本;排版及最终设备比例由后续布局/显示列表转换处理。
Text {
value: String,
size: u32,
@@ -265,7 +279,9 @@ pub enum UiKind {
gap: f32,
children: Vec<Arc<UiNode>>,
},
// 无视觉内容的间隔叶节点,提供布局占用尺寸。
Spacer(f32),
// 滚动盒保存有限分配尺寸、允许轴和普通内容;实际偏移按 Mount 出现分别维护,不放到共享节点里。
Scroll {
axis: crate::scroll::Axis,
width: f32,