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
+42 -5
View File
@@ -38,40 +38,49 @@ pub enum AppEvent {
/// 一个原生窗口的宿主状态;主窗口还协调子窗口资源,共用同一运行时与输入通道。
pub struct TesseraApp {
// 运行时窗口资源编号与 winit WindowId 分属不同命名空间,输入携带前者,OS 事件匹配后者。
resource: u64,
control: crate::api::RuntimeControl,
exit_requested: bool,
// 记录当前原生窗口所对应的运行时世代,避免重启后继续显示已失效的子窗口。
native_session: u64,
startup_page_requested: bool,
native_error: Option<String>,
// 只有主窗口维护此表;子窗口有独立文档/绘制状态,但复用运行时控制与输入队列。
children: std::collections::BTreeMap<u64, TesseraApp>,
proxy: EventLoopProxy<AppEvent>,
// 窗口、softbuffer 上下文与表面延迟创建;Arc 让表面持有有效的原生窗口句柄。
window: Option<Arc<Window>>,
context: Option<Context<Arc<Window>>>,
surface: Option<Surface<Arc<Window>, Arc<Window>>>,
namespace: Arc<RwLock<NamespaceState>>,
developer_tools: DeveloperToolsState,
// 最近一次绘制生成的宿主控件几何,用于下一次输入命中、光标和 IME 定位。
layout: SceneLayout,
pointer: Point,
sidebar: crate::sidebar::State,
sidebar_keyboard: bool,
panning: bool,
// 拖动开始时捕获视口,None 也可能表示拖动整张 Canvas,而非手势未开始。
pan_viewport: Option<u64>,
orbiting: bool,
space_down: bool,
modifiers: ModifiersState,
activity: Activity,
event_client: crate::events::Client,
// 保存按下时的版本与位置;释放时需确认仍处在同一会话与布局,防止旧画面误点击。
guest_pressed: Option<crate::events::Input>,
pointer_hover: Option<crate::events::Input>,
pointer_capture: Option<crate::events::Input>,
guest_focus: Option<crate::events::Input>,
// Enter/Space 的按下捕获;只在对应按键释放时发出一次 click,忽略系统连发。
guest_key: Option<(NamedKey, crate::events::Input)>,
guest_keyboard: bool,
}
impl TesseraApp {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 先建立连接权威 namespace 的有界事件客户端,再初始化主窗口状态。
/// 客户端创建失败向调用方返回错误;原生窗口和像素表面延迟到 resumed 创建。
pub fn new(
namespace: Arc<RwLock<NamespaceState>>,
activity: Activity,
@@ -142,11 +151,12 @@ impl TesseraApp {
let session = namespace.runtime_session;
let revision = namespace.revision;
let submission = namespace.submission;
// 先复制已发布的子窗口投影并释放读锁,再创建/销毁 OS 资源;原生调用不会占着发布锁。
let documents = namespace.document.windows.clone();
drop(namespace);
if session != self.native_session {
// Console reset preserves the old projection with input disabled.
// A real replacement changes frame sessions and drops old OS views.
// 控制台 reset 可以保留旧投影但禁用输入;真正替换运行时后,
// 新文档带新 session,此时销毁旧原生视图,防止跨世代复用。
let replaces = documents
.values()
.any(|document| document.frame.session == session && session != 0);
@@ -203,6 +213,7 @@ impl TesseraApp {
return;
};
let session = namespace.runtime_session;
// 取走整批命令即表示消费;随后释放写锁,执行窗口 API 时不阻塞 worker 的文档发布。
let commands = std::mem::take(&mut namespace.window_commands);
drop(namespace);
for envelope in commands {
@@ -275,6 +286,7 @@ impl TesseraApp {
namespace.window_viewports.insert(self.resource, size);
if self.resource == crate::window::MAIN_WINDOW {
let session = namespace.runtime_session;
// 主窗口维护 worker 可见的视口总表:先移除旧世代/已关闭子窗口,再复制当前有效子窗口的逻辑尺寸。
namespace.window_viewports.retain(|id, _| {
*id == crate::window::MAIN_WINDOW
|| self
@@ -333,6 +345,7 @@ impl TesseraApp {
/// 接收完整文档更新,协调子窗口和原生命令,再更新输入焦点并请求重绘。
fn document_updated(&mut self, event_loop: &ActiveEventLoop) {
// 先使原生资源对应新文档,再执行其窗口命令;随后重建焦点令牌,避免沿用旧布局身份。
self.reconcile_windows(event_loop);
self.apply_window_commands();
if let Ok(namespace) = self.namespace.read() {
@@ -364,6 +377,7 @@ impl TesseraApp {
/// 先处理宿主管理输入、选择与快捷键,再按焦点决定是否交给页面。
fn handle_keyboard(&mut self, event: &winit::event::KeyEvent) {
// 宿主快捷键优先级最高;后续依次交给侧栏、页面交互、开发工具按钮及文本编辑。
let command = self.modifiers.super_key() || self.modifiers.control_key();
if command
&& event.state == ElementState::Pressed
@@ -391,6 +405,7 @@ impl TesseraApp {
}
return;
}
// 侧栏获得键盘路由后,Tab 在宿主目标间移动,Enter/Space 采用按下捕获、释放触发。
if self.sidebar_keyboard {
if event.logical_key == Key::Named(NamedKey::Tab)
&& event.state == ElementState::Pressed
@@ -434,6 +449,7 @@ impl TesseraApp {
return;
}
}
// 页面交互成功消费按键才提前返回;未处理的按键还可交给开发工具,保持明确的路由顺序。
if self.guest_keyboard && self.handle_guest_key(event) {
self.request_redraw();
return;
@@ -463,6 +479,7 @@ impl TesseraApp {
}
return;
}
// 只有展开且有编辑焦点的工具接受文本;剪切先成功写系统剪贴板,再删除选中内容。
if !self.developer_tools.open || self.developer_tools.focus.is_none() {
return;
}
@@ -490,6 +507,7 @@ impl TesseraApp {
}
_ => {}
}
// 输入法预编辑期间不再把原始按键转换为编辑动作;最终文本通过 Ime::Commit 插入。
} else if let Key::Named(key) = &event.logical_key {
if !self.developer_tools.preedit.is_empty() {
return;
@@ -548,6 +566,7 @@ impl TesseraApp {
if frame.session == 0 {
return None;
}
// 命中的是当前发布帧,事件同时携带 session/layout_version;worker 可拒绝排队期间已过期的输入。
let mount = frame.hit_test(point)?;
Some(crate::events::Input {
window: self.resource,
@@ -684,6 +703,7 @@ impl TesseraApp {
tab_drop: None,
screen_position: None,
});
// 滚轮优先交给可滚动挂载;未命中则尝试 3D 缩放或整页平移,最后更新开发工具自身滚动。
if let Some(input) = input {
self.send_guest(input);
}
@@ -726,6 +746,7 @@ impl TesseraApp {
return None;
}
let world = frame.surface.to_world(point);
// 拖动沿用捕获 ID,滚轮/缩放则按当前点命中;被捕获的视口若已消失,取消此次输入而不切换目标。
let viewport = if self.panning {
self.pan_viewport.and_then(|id| {
frame.mounts.iter().find(|mount| {
@@ -740,6 +761,7 @@ impl TesseraApp {
if self.panning && self.pan_viewport.is_some() && viewport.is_none() {
return None;
}
// 局部 2D/3D 视口使用不同动作名。平移除去页面 zoom 以还原世界位移,缩放倍率本身不按 zoom 缩放。
if let Some(viewport) = viewport {
return Some(crate::events::Input {
window: self.resource,
@@ -775,6 +797,7 @@ impl TesseraApp {
screen_position: None,
});
}
// 没有局部相机时才考虑整页变换:普通 Window 不平移,只有 Canvas 接受整页缩放。
if frame.surface.mode == crate::page::Mode::Window
|| kind == "page-zoom" && frame.surface.mode != crate::page::Mode::Canvas
{
@@ -819,6 +842,7 @@ impl TesseraApp {
if frame.session == 0 || frame.fault.is_some() {
return None;
}
// 按发布帧中的挂载顺序遍历可交互目标;Shift+Tab 逆向环绕,尚无焦点时从首/末项进入。
let targets: Vec<_> = frame
.mounts
.iter()
@@ -866,6 +890,7 @@ impl TesseraApp {
if !event.repeat {
self.guest_key = self.guest_focus.clone().map(|focus| (*key, focus));
}
// 释放会取走捕获,保证不会重复激活;仅与原来按下的 Enter/Space 相同才转换成 click。
} else if let Some((pressed, mut input)) = self.guest_key.take()
&& pressed == *key
{
@@ -907,6 +932,7 @@ impl TesseraApp {
.with_titlebar_transparent(true)
.with_fullsize_content_view(true)
};
// 先创建平台窗口,再建立软件绘图上下文/表面;任何一步失败都向外返回,由 resumed 记录并处理。
let window = Arc::new(event_loop.create_window(attributes)?);
#[cfg(target_os = "macos")]
crate::native_chrome::align_controls(&window);
@@ -932,6 +958,7 @@ impl TesseraApp {
}
self.guest_pressed = None;
self.guest_key = None;
// 正常关闭先请求 VM 清理,等待 ShutdownComplete 再退出 OS 循环;发送失败时自行投递结束通知并保留错误。
if self.control.request_shutdown() {
self.exit_requested = true;
} else {
@@ -993,6 +1020,7 @@ impl TesseraApp {
let Ok(namespace) = self.namespace.read() else {
return Ok(());
};
// 读锁保护一次完整文档取样与场景生成;生成后释放锁,像素写入和 present 不再占用 namespace。
let scene = scene::build_scene(
size.width,
size.height,
@@ -1022,6 +1050,7 @@ impl TesseraApp {
LogicalSize::new(1.0, 19.0),
);
// 根据真实物理尺寸调整像素表面;逻辑坐标到物理像素的转换已由场景构造中的 scale_factor 负责。
surface
.resize(width, height)
.map_err(|error| anyhow::anyhow!("{error}"))?;
@@ -1040,8 +1069,8 @@ impl TesseraApp {
impl ApplicationHandler<AppEvent> for TesseraApp {
/// 处理 OS 直接结束事件循环的收尾,尝试在明确时限内等待运行时清理。
fn exiting(&mut self, _: &ActiveEventLoop) {
// OS termination can bypass CloseRequested. The loop is already ending;
// use a bounded fallback rather than silently dropping every callback.
// OS 终止可能跳过 CloseRequested;此时循环已在退出,无法再等事件通知。
// 最多阻塞 5 秒等待运行时完成清理,超时保留退出错误而不无限等待。
if !self.control.request_shutdown() {
self.native_error = Some("VM worker unavailable during shutdown".into());
return;
@@ -1128,6 +1157,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
let Some(window) = self.window.as_ref().cloned() else {
return;
};
// 主处理器先按 OS WindowId 转发子窗口事件;转发后汇总视口,供同一运行时布局所有窗口。
if window.id() != window_id {
if let Some(child) = self.children.values_mut().find(|child| {
child
@@ -1142,6 +1172,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
}
match event {
// 主窗口关闭触发应用退出;子窗口关闭先发 window-close,由源程序生命周期逻辑决定资源清理。
WindowEvent::CloseRequested => {
if self.resource == crate::window::MAIN_WINDOW {
self.request_exit();
@@ -1176,6 +1207,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
..
} => {
let scale = window.scale_factor() as f32;
// OS 指针是物理像素,先除 DPI 得逻辑坐标;后续侧栏命中和页面世界坐标转换都从该坐标出发。
let next = Point::new(x as f32 / scale, y as f32 / scale);
let delta = Point::new(next.x - self.pointer.x, next.y - self.pointer.y);
self.pointer = next;
@@ -1194,6 +1226,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
&& mount.camera_controls
})
});
// 3D 相机拖动超过世界坐标下的 3 单位阈值后转为 orbit,并清除 click 捕获,避免释放时误激活。
if is_3d && (point.x - start[0]).hypot(point.y - start[1]) > 3. {
self.orbiting = true;
self.panning = self.begin_pan();
@@ -1301,6 +1334,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
);
}
} else {
// 拖动结束仅结束手势,不把同一次释放再当成点击;普通点击需保持按下与释放的帧身份一致。
if self.panning {
self.panning = false;
self.guest_pressed = None;
@@ -1314,6 +1348,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
&& released.session == pressed.session
&& released.layout_version == pressed.layout_version
{
// 保留起点用于运行时判断点击/拖动语义;目标来自释放位置,具体可接受性仍由 worker 校验。
released.press_point = pressed.point;
self.send_guest(released);
}
@@ -1330,6 +1365,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
window.request_redraw();
}
WindowEvent::MouseWheel { delta, .. } => {
// 行滚动按每行 38 逻辑像素换算,像素滚动除去 DPI;Shift 在几乎没有横向分量时将纵向量转横向。
let (mut dx, mut dy) = match delta {
MouseScrollDelta::LineDelta(x, y) => (x * 38.0, y * 38.0),
MouseScrollDelta::PixelDelta(p) => (
@@ -1418,6 +1454,7 @@ impl ApplicationHandler<AppEvent> for TesseraApp {
}
window.request_redraw();
}
// 失焦可能导致收不到对应释放事件,因此清空按键/鼠标捕获、平移状态及修饰键,避免恢复焦点后卡住。
WindowEvent::Focused(false) => {
self.cancel_pointer();
self.guest_pressed = None;