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
+25 -3
View File
@@ -16,6 +16,7 @@ use winit::event_loop::EventLoopProxy;
/// 拖放目标窗口、目标布局版本和插入位置,源标签身份由外层 Input 保存。
pub struct TabDrop {
pub window: u64,
// 事件所依据的已发布布局版本,由执行端校验过期帧;原生连续手势有单独刷新逻辑。
pub layout_version: u64,
pub index: usize,
}
@@ -26,15 +27,19 @@ pub struct TabDrop {
pub struct Input {
#[serde(default = "default_window")]
pub window: u64,
// 产生事件的运行时会话;重载后即使窗口或 Mount 数值相同也不能沿用旧事件。
pub session: u64,
pub layout_version: u64,
// 捕获的具体出现身份;页面级相机事件使用零,独立视口相机事件要求非零。
pub mount: u64,
pub kind: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
// 事件位置或缩放锚点;click 与 press_point 配对,具体坐标语义由事件 kind 决定。
pub point: Option<[f32; 2]>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub press_point: Option<[f32; 2]>,
#[serde(default, skip_serializing_if = "Option::is_none")]
// 平移/滚动增量,或缩放的 [倍率,0];不能无差别接受任意事件携带该字段。
pub delta: Option<[f32; 2]>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tab_drop: Option<TabDrop>,
@@ -48,11 +53,12 @@ fn default_window() -> u64 {
}
impl Input {
/// 检查当前输入或发布值的不变量,调用方据校验结果决定是否继续。
/// 按事件种类核对可携带字段、坐标范围和 Mount 是否为零;不替代执行端的会话/能力校验。
pub fn validate(&self) -> Result<(), &'static str> {
if self.window == 0 {
return Err("window identity must be nonzero");
}
// 标签跨窗口放置仅接受目标元信息;禁止同时夹带指针/滚动/屏幕位置,避免混用两套操作。
if self.kind == "tab-drop" {
let Some(target) = &self.tab_drop else {
return Err("tab-drop requires target metadata");
@@ -68,9 +74,11 @@ impl Input {
}
return Ok(());
}
// 非 tab-drop 不得携带目标窗口信息,即使其他字段恰好合法也拒绝。
if self.tab_drop.is_some() {
return Err("tab_drop is only accepted for tab-drop");
}
// 屏幕位置只服务 tab-detach 的新窗口定位,允许负数以支持左侧/上方显示器,但限制绝对范围。
if let Some(position) = self.screen_position
&& (self.kind != "tab-detach"
|| !position
@@ -89,7 +97,9 @@ impl Input {
| "scene-pan"
| "scene-zoom"
) {
// 独立视口输入可包含负的局部位置(例如捕获拖动移出视口);页面级锚点要求非负。
let viewport = self.kind.starts_with("viewport-") || self.kind.starts_with("scene-");
// 所有相机操作必须带有限、有界的增量;point 在非缩放操作可省略。
let valid_delta = self.delta.is_some_and(|delta| {
delta
.iter()
@@ -112,6 +122,7 @@ impl Input {
{
return Err("invalid page camera input");
}
// 缩放必须给锚点并使用正倍率 0.1..=10;第二分量必须为零,不把缩放与二维平移混合编码。
if self.kind.ends_with("-zoom")
&& (self.point.is_none()
|| self
@@ -122,6 +133,7 @@ impl Input {
}
return Ok(());
}
// 滚动需要当前点与二维有限增量,不接受按下点;Mount 能力与身份由执行端进一步核对。
if self.kind == "scroll" {
return match (self.point, self.press_point, self.delta) {
(Some(point), None, Some(delta))
@@ -157,6 +169,8 @@ impl Input {
if self.delta.is_some() {
return Err("delta is only accepted for scroll input");
}
// 无指针坐标的离散事件可通过此结构校验;若有指针信息,必须是 click 的按下/释放成对坐标。
// 这里不做完整 kind 白名单授权,具体操作仍由后续分发层检查。
match (self.point, self.press_point) {
(None, None) => Ok(()),
(Some(point), Some(press))
@@ -228,7 +242,7 @@ impl Inbox {
}
}
impl Client {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 建立容量 64 的发送队列和单个后台中继线程,事件交给原生 VM worker;线程创建失败则返回错误。
pub fn new(
proxy: EventLoopProxy<crate::app::AppEvent>,
namespace: Arc<RwLock<crate::document::NamespaceState>>,
@@ -263,7 +277,7 @@ impl Client {
})?;
Ok(Self(inbox))
}
/// 通过有界原生输入客户端或本地 HTTP 发送纯数据事件;过期版本按既定协议处理。
/// 非阻塞尝试入队;成功仅代表队列接收,满队列或后台线程关闭返回 false。
pub fn send(&self, input: Input) -> bool {
let Ok(mut q) = self.0.queue.lock() else {
return false;
@@ -303,6 +317,7 @@ pub(crate) fn refresh_continuous_input(
) {
return true;
}
// 选取事件原窗口的权威帧;窗口已经消失时丢弃,不能把手势改投主窗口。
let frame = if input.window == crate::window::MAIN_WINDOW {
Some(&current.document.frame)
} else {
@@ -315,6 +330,7 @@ pub(crate) fn refresh_continuous_input(
let Some(frame) = frame else {
return false;
};
// 必须仍属同一运行时会话、帧无故障且原捕获 Mount 具备对应能力,才可更新布局版本。
if current.runtime_session != input.session
|| frame.session != input.session
|| frame.fault.is_some()
@@ -333,6 +349,7 @@ pub(crate) fn refresh_continuous_input(
{
return false;
}
// 只追随新版本,不改 session/window/mount,不重选目标;每条排队增量仍独立发送。
input.layout_version = frame.layout_version;
true
}
@@ -341,6 +358,7 @@ pub(crate) fn refresh_continuous_input(
mod tests {
use super::*;
#[test]
/// 重复消费旧帧捕获的连续 pan,允许刷新到当前版本且保留每条 delta;离散 click 不改版本,会话/目标替换拒绝手势。
fn queued_native_pan_keeps_each_delta_and_rejects_replaced_targets() {
let (mut session, document) = crate::endor_host::ReplSession::load(
"view=CanvasViewport(200,100,Scene2D(RectBlock(20,20,0)))\npage=Page()\npage.render(view)",
@@ -370,6 +388,7 @@ mod tests {
document,
..Default::default()
};
// 反复从旧帧原始手势克隆输入,验证每条增量都被刷新版本并累计,12×3 应得到 36。
for _ in 0..12 {
let mut queued = original.clone();
assert!(refresh_continuous_input(&mut queued, &current));
@@ -379,6 +398,7 @@ mod tests {
session.execute("view.camera.x", "app.main").unwrap().value,
"36"
);
// 离散点击不得自动刷新版本;随后验证会话替换和目标移除都会拒绝连续手势。
let mut click = original.clone();
click.kind = "click".into();
assert!(refresh_continuous_input(&mut click, &current));
@@ -390,6 +410,7 @@ mod tests {
assert!(!refresh_continuous_input(&mut original.clone(), &current));
}
#[test]
/// 对 tab-drop 元数据、位置上限与 tab-detach 桌面坐标逐项改坏,检查辅助字段只在对应事件类型和预算内合法。
fn drop_metadata_is_scoped_to_its_event_kind_and_bounded() {
let mut input:Input=serde_json::from_str(r#"{"window":1,"session":1,"layout_version":2,"mount":3,"kind":"tab-drop","tab_drop":{"window":2,"layout_version":4,"index":1}}"#).unwrap();
assert!(input.validate().is_ok());
@@ -407,6 +428,7 @@ mod tests {
}
#[test]
/// 旧 JSON 未带 window 时默认主窗口以保持兼容;显式 window=0 仍是非法资源,不能当成默认值。
fn legacy_event_window_defaults_but_zero_is_never_a_resource() {
let mut input: Input =
serde_json::from_str(r#"{"session":1,"layout_version":2,"mount":3,"kind":"focus"}"#)