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
+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 {