Zayden-Jung/endorphin-tessera-gui
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: explain document publication and visual snapshot invalidation

Browse Source
This commit is contained in:
Codex Bot
2026-11-12 18:13:48 +08:00
parent dbf0bb5800
commit 38e8bbc1e6
2 changed files with 222 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/model/document.rs
+128
View File
@@ -1,6 +1,9 @@
//! 运行时与窗口线程之间的发布数据契约。NamespaceState 管理提交序号、版本和当前完整文档。
//! RenderDocument/Frame 包含绘制命令、Mount 几何、页面标签和相机投影。发布前统一检查数量、坐标、颜色及索引一致性。
//! 屏幕命中、逻辑坐标和世界 UI 的射线映射必须与绘制采用同一变换；这里的 ID 是数据身份，不是窗口线程可操作的托管引用。
//! 调用路径：API worker 用 NamespaceState 提交/清空候选；桥接发布前调用 validate。
//! 窗口壳用 Frame 命中结果构造输入，worker 再复核；软件渲染入口用 display_list 转为设备坐标命令。
//! 所有发布值拥有绘制所需原生数据，不能要求窗口线程通过 ID 解引用 VM。
//!
use std::collections::HashSet;
use std::sync::Arc;
@@ -14,21 +17,26 @@ use crate::{
ui_bridge::UiNode,
};
// HTTP/Console 未指定名字时的默认命名空间，初始化状态和源入口应使用同一值。
pub const DEFAULT_NAMESPACE: &str = "app.main";
#[derive(Clone, Debug)]
/// HTTP/GUI 共享的最近完整发布状态；submission 决定结果归属，revision 表示实际发布次数。
pub struct NamespaceState {
// 命名空间显示/API 身份，区别于每次输入的 submission 与 VM session。
pub name: String,
// 成功替换或 clear 才推进的发布版本，用于调用方识别可见文档更新。
pub revision: u64,
// 较新完整 PUT/DELETE 会改变提交身份；旧输入即使晚完成也不得覆盖新结果。
pub submission: u64,
// 最近成功的完整文档；编译/执行失败或过期候选不替换它。
pub document: RenderDocument,
// viewport 是主窗口逻辑页面区域；window_viewports 同时记录仍存活的副窗口。
pub viewport: Option<crate::layout::Size>,
pub window_viewports: std::collections::BTreeMap<u64, crate::layout::Size>,
// 原生命令与运行时世代一起发布，防止窗口 ID 在跨 VM 时被误用。
pub runtime_session: u64,
// 待窗口壳消费的世代化原生命令，按动作合并并保留全局请求顺序。
pub window_commands: Vec<crate::window::Envelope>,
}
@@ -66,12 +74,14 @@ impl NamespaceState {
return;
}
// 本方法接纳传入 session 作为当前世代，调用方负责只在成功发布边界调用；同资源同动作保留最新请求。
// 同一资源的同类动作保留最新请求，Focus/Resize 等不同动作仍分别排队。
for command in commands {
self.window_commands
.retain(|old| !old.command.same_kind(&command));
self.window_commands
.push(crate::window::Envelope { session, command });
}
// 合并后按 VM 原始 sequence 恢复执行顺序，避免 retain/push 使不同资源动作乱序。
self.window_commands
.sort_by_key(|command| command.command.sequence);
}
@@ -89,6 +99,7 @@ impl NamespaceState {
if submission != self.submission {
return Ok(None);
}
// 先计算可用新版本，溢出时整个提交失败且旧文档仍在。
let revision = self
.revision
.checked_add(1)
@@ -100,7 +111,9 @@ impl NamespaceState {
/// 推进提交身份和发布版本，替换为空文档并清除运行时命令，使旧提交不能覆盖清空结果。
pub fn clear(&mut self) -> Result<u64> {
// clear 也创建新提交身份，让先前在途的合法候选失去发布资格。
let submission = self.next_submission()?;
// 发布版本与提交令牌都先检查溢出，状态更新集中在全部检查成功之后。
let revision = self
.revision
.checked_add(1)
@@ -119,15 +132,19 @@ impl NamespaceState {
/// 可以离开 VM 线程的完整展示值，包含源码投影、根帧和其他窗口的文档。
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)]
// 完整输入源码或 Console 历史，Sources 使用原文与结构树范围定位。
pub source: String,
#[serde(default)]
// 可选源码投影根；空文档可无根，和视觉 ui_root 是不同的数据。
pub root: Option<CodeNode>,
#[serde(default)]
// 当前窗口完整视觉帧，副窗口文档也各有自己的 frame.window。
pub frame: Frame,
}
@@ -136,6 +153,7 @@ 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)
|| ![surface.pan.x, surface.pan.y]
@@ -147,11 +165,14 @@ impl RenderDocument {
{
bail!("invalid page camera or extent");
}
// 主窗口之外最多十五个副窗口，与完整桌面窗口预算一致。
if self.windows.len() > 15 {
bail!("too many window projections");
}
// 副窗口只允许一层投影，键须等于其 frame.window，不能重复嵌入主窗口或再带嵌套 windows。
// 按每个副窗口独立校验帧，不允许借嵌套 map 绕开窗口计数。
for (id, document) in &self.windows {
// 副窗口不能冒用主窗口 ID，键/帧身份须相等，且不得再次嵌套 windows。
if *id == crate::window::MAIN_WINDOW
|| *id != document.frame.window
|| !document.windows.is_empty()
@@ -160,13 +181,16 @@ impl RenderDocument {
}
document.validate()?;
}
// 源码预算按 UTF-8 字节计，不以字符数绕过 1 MiB 输入限制。
if self.source.len() > 1_048_576 {
bail!("source exceeds the 1 MiB limit");
}
// 绘制命令预算独立于 Mount 数量，防止单个源 paint 产生无界命令。
if self.frame.commands.len() > 10_000 {
bail!("frame exceeds the 10,000 command limit");
}
// 零窗口 ID 无效，不作为默认主窗口的别名接纳。
if self.frame.window == 0 {
bail!("invalid window identity");
}
@@ -177,27 +201,35 @@ impl RenderDocument {
{
bail!("invalid command clip table");
}
// 只校验存在的裁剪矩形；None 表示该命令不加这层裁剪。
for clip in self.frame.command_clips.iter().flatten() {
validate_rect(clip[0], clip[1], clip[2], clip[3], 0.0)?;
}
// 视图表与裁剪表同样是平行索引，非空半表会使绘制参数错配。
if !self.frame.command_views.is_empty()
&& self.frame.command_views.len() != self.frame.commands.len()
{
bail!("invalid command view table");
}
// 各二维变换先检查缩放/平移合法性，后面的绘制转换可据此使用。
for view in self.frame.command_views.iter().flatten() {
// 拒绝不可逆或超界视图变换，避免绘制与命中给出互相矛盾的坐标。
if !view.valid() {
bail!("invalid command view transform");
}
}
// 逐条分派到命令自己的几何/文本/材质检查，不能只检查命令总数。
for command in &self.frame.commands {
command.validate()?;
}
// 出现位置也设独立上限，防止少量命令背后展开过多可命中节点。
if self.frame.mounts.len() > 10_000 {
bail!("frame exceeds the 10000 mount limit");
}
// 标签 ID 必须非零且唯一，最多一个活动页；标题按 UTF-8 字节限长，标签数受 MAX_PAGES 限制。
// 记录全部标签身份，集合同时用于检测重复；active 数量另外限制为至多一个。
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
|| self
@@ -209,18 +241,24 @@ impl RenderDocument {
bail!("invalid tab projection");
}
// 先收集全部 Mount ID 并校验几何，再第二遍核对关系下标，允许链接指向帧中较后位置。
// 先建整帧身份集合，第二轮才能允许关系链接指向后面才出现的节点。
let mut mount_ids = HashSet::new();
// 首轮逐项检查变换、身份与几何，收集关系检查所需的完整 ID 集合。
for mount in &self.frame.mounts {
// Mount 的二维变换与绘制表独立检查，不能因为命令合法就信任输入几何。
if mount.view.is_some_and(|view| !view.valid()) {
bail!("invalid Mount view transform");
}
// 业务 block_id 可因共享重复，但每个出现的 Mount ID 必须非零且帧内唯一。
if mount.id == 0 || mount.block_id.is_empty() || !mount_ids.insert(mount.id) {
bail!("invalid or duplicate mount identity");
}
validate_rect(mount.x, mount.y, mount.width, mount.height, 0.0)?;
// 祖先 clip 与节点原几何分别校验，裁剪不能包含 NaN 或负尺寸。
if let Some(clip) = mount.clip {
validate_rect(clip[0], clip[1], clip[2], clip[3], 0.0)?;
}
// 相机手势额外内容区裁剪也须合法，避免手势使用未验证矩形。
if let Some(clip) = mount.viewport_clip {
validate_rect(clip[0], clip[1], clip[2], clip[3], 0.0)?;
}
@@ -235,11 +273,14 @@ impl RenderDocument {
}
}
// 此处只保证关系目标在帧内，不做完整树环/双向一致性验证；组成与生命周期层承担更强结构不变量。
// 第二轮使用完整 ID 集合检查关系归属；这里不证明双向一致性或无环。
for mount in &self.frame.mounts {
// 只枚举实际存在的关系 ID，None 是合法边界，不补造关系。
for linked in [mount.parent, mount.first_child, mount.next_sibling]
.into_iter()
.flatten()
{
// 任何父/子/兄弟关系都必须落在本窗口帧内。
if !mount_ids.contains(&linked) {
bail!("mount links outside this frame");
}
@@ -256,7 +297,9 @@ impl RenderDocument {
{
bail!("frame root does not match its visual projection");
}
// 源码树单独检查节点 ID 唯一，不能和视觉 Mount ID 集合混用。
let mut ids = HashSet::new();
// 无源码树是合法空发布；有根则递归检查深度、范围和身份。
if let Some(root) = &self.root {
root.validate(0, &mut ids)?;
}
@@ -265,11 +308,14 @@ impl RenderDocument {
/// 将逻辑命令转换到设备比例并应用逐命令视图/裁剪；不自动调用 validate，发布入口须先校验。
pub fn display_list(&self, scale: f32) -> Result<DisplayList> {
// 窗口渲染调用此转换，借用已发布完整帧，不访问候选 VM 或业务对象。
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 {
@@ -277,6 +323,7 @@ impl RenderDocument {
clip[0], clip[1], clip[2], clip[3], scale,
)));
}
// 没有逐命令 view 时使用单位变换；实际缩放由设备 scale×view.zoom 组成。
let view = frame
.command_views
.get(index)
@@ -289,6 +336,7 @@ impl RenderDocument {
.to_draw_command(scale * view.zoom)?
.translated(Point::new(view.x * scale, view.y * scale)),
);
// 本命令已经绘制，配对弹出先前压入的 clip，维持列表栈平衡。
if clip.is_some() {
list.push(DrawCommand::PopClip);
}
@@ -299,6 +347,7 @@ impl RenderDocument {
.and_then(|id| frame.mounts.iter().find(|m| m.id == id))
.filter(|mount| mount.panel.is_none())
{
// 焦点框使用与目标同一祖先裁剪，不能穿出滚动容器或有限面板。
if let Some(c) = focus.clip {
list.push(DrawCommand::PushClip(scaled_rect(
c[0], c[1], c[2], c[3], scale,
@@ -324,6 +373,7 @@ impl RenderDocument {
}
.to_draw_command(scale)?,
);
// 焦点框单独配对弹出 clip，避免把之后的故障提示也裁掉。
if focus.clip.is_some() {
list.push(DrawCommand::PopClip);
}
@@ -365,14 +415,20 @@ impl RenderDocument {
#[derive(Clone, Debug, Serialize, Deserialize)]
/// Sources 使用的源码层次节点；ID、名称、种类和行列范围都属于代码投影而不是运行时对象句柄。
pub struct CodeNode {
// 源码节点稳定选择键，带命名空间/提交来源；与视觉 block_id 字符串用途不同。
pub id: String,
// 源声明或语句的显示名称，Sources 用于树列表标题，不作为全局唯一键。
pub name: String,
// 源码结构类别（如 script/module/function），不等于运行时视觉组件种类。
pub kind: String,
#[serde(default)]
// 原源码起始行，零表示缺少来源，不能默认当作第一行。
pub start_line: usize,
#[serde(default)]
// 原源码结束行；两端都已知时必须不早于 start_line。
pub end_line: usize,
#[serde(default)]
// 源码语法投影的有序孩子，验证 ID 唯一性时共享整树集合。
pub children: Vec<CodeNode>,
}
@@ -383,9 +439,11 @@ impl CodeNode {
if depth > 64 {
bail!("architecture tree exceeds 64 levels");
}
// 空源码节点 ID 无法供 Sources 稳定选中或查找，发布时拒绝。
if self.id.is_empty() {
bail!("architecture node id cannot be empty");
}
// 集合覆盖整棵树，两个不同分支也不能重用同一节点 ID。
if !ids.insert(&self.id) {
bail!("duplicate architecture node id: {}", self.id);
}
@@ -393,6 +451,7 @@ impl CodeNode {
if self.start_line > 0 && self.end_line > 0 && self.start_line > self.end_line {
bail!("invalid source range for node {}", self.id);
}
// 递归共享全局身份集合并增加深度，不能每个子树重新计数而绕过约束。
for child in &self.children {
child.validate(depth + 1, ids)?;
}
@@ -401,6 +460,7 @@ impl CodeNode {
/// 按请求的代码节点身份或路径查找对应的源码投影。
fn find(&self, id: &str) -> Option<&CodeNode> {
// node(id) 先匹配当前节点，未命中再按孩子顺序递归返回首个匹配。
if self.id == id {
return Some(self);
}
@@ -415,32 +475,43 @@ pub struct Frame {
#[serde(skip)]
pub hit_index: Arc<crate::viewport::spatial::Index>,
#[serde(default)]
// 页面级兼容 pan/zoom 与内容范围；独立相机另由 command_views/Mount.view 表达。
pub surface: crate::page::Surface,
#[serde(default = "default_window")]
// 非零原生窗口身份，副窗口 map 的键必须与它相同。
pub window: u64,
#[serde(default = "default_background")]
// 页面清屏颜色文本，每帧显示列表先生成一条 Clear。
pub background: String,
#[serde(default)]
// 按最终绘制顺序保存逻辑命令，后项覆盖前项；不包含显示列表追加的焦点/故障层。
pub commands: Vec<RenderCommand>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
// 逐命令有效裁剪 [x,y,width,height]；可整体为空，否则必须与 commands 等长。
pub command_clips: Vec<Option<[f32; 4]>>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
// 逐命令二维投影，缺省单位变换；clip 已在投影后的对应视图空间。
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")]
// 本窗口所有出现位置的平面索引，业务身份可重复，Mount ID 必须唯一。
pub mounts: Vec<MountGeometry>,
#[serde(default)]
// 本次布局发布版本，与 session/window 一起判断原生输入是否过期。
pub layout_version: u64,
#[serde(default)]
// 运行时世代与 layout_version 共同确定输入归属；仅布局版本相同不能跨 VM 接受事件。
pub session: u64,
#[serde(default)]
// 焦点 Mount ID，普通根焦点在 display_list 追加，面板焦点已组合进纹理。
pub focus: Option<u64>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
// 当前窗口标签投影，ID 唯一且最多一个 active。
pub tabs: Vec<crate::tabs::Tab>,
#[serde(default)]
// 停止域诊断，显示列表追加提示且 hit_test 拒绝继续选择交互目标。
pub fault: Option<String>,
}
@@ -474,32 +545,48 @@ pub struct MountGeometry {
// 可嵌套的世界 UI 映射，把页面坐标还原到此出现所在面板纹理空间。
pub panel: Option<Arc<crate::scene3d::panel::Mapping>>,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
// 是否二维相机视口，供窗口手势定位选择。
pub canvas_viewport: bool,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
// 是否三维视口，原生拾取/相机事件据此进入对应协议。
pub scene3d_viewport: bool,
#[serde(default)]
// 三维视口是否具备相机控制器，camera_at 不只凭 scene3d_viewport 接受手势。
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")]
// 布局空间到当前视图/面板纹理空间的二维变换，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]>,
// 本帧内出现身份，重建/换页可变化，不是托管 ObjectRef。
pub id: u64,
// 业务对象身份文本，共享对象的多个 Mount 可拥有同一 block_id。
pub block_id: String,
// 父出现 ID；关系目标必须在本帧中，不允许跨窗口链接。
pub parent: Option<u64>,
// 首个子出现 ID，通过 next_sibling 遍历同级。
pub first_child: Option<u64>,
// 下一个同级出现 ID，保留组成展开次序。
pub next_sibling: Option<u64>,
// 出现的布局空间绝对横坐标，投影通过 view/panel 另算。
pub x: f32,
// 出现的布局空间绝对纵坐标，不随相机直接改写。
pub y: f32,
// 本次布局分配宽度，可不同于共享业务对象的自然 width。
pub width: f32,
// 本次布局分配高度，不和其他出现位置共用几何存储。
pub height: f32,
// 原生粗命中资格，真正源 hitTest/事件监听状态仍由 worker 复核。
pub interactive: bool,
#[serde(default)]
// 是否存在 pointer 系列处理需求，供窗口指针输入路由使用。
pub pointer_events: bool,
}
@@ -518,12 +605,15 @@ impl MountGeometry {
}
/// 把视图位移换算成目标出现的局部位移，处理缩放与世界 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]);
}
// 面板投影非线性，缺少当前位置就无法正确换算 delta，明确返回 None。
let point = point?;
// 先反投影手势基点；clipped=false 允许捕获拖动移出面板，投影失败则停止处理。
let current = self.view_point(Point::new(point[0], point[1]), false)?;
// 对 point 与 point+delta 分别投影，使用 clipped=false 允许捕获拖动越出面板；投影不可逆则返回 None。
let previous =
@@ -535,6 +625,7 @@ impl MountGeometry {
}
/// 判断给定点是否位于目标范围；需要相机转换的类型会先转换再判断。
pub fn contains(&self, point: Point) -> bool {
// 先完成世界面板反投影和遮挡检查，失败直接视为未命中。
let Some(point) = self.view_point(point, true) else {
return false;
};
@@ -550,6 +641,7 @@ impl MountGeometry {
impl Frame {
/// 从顶层绘制顺序向后查找可控制的视口，命中与裁剪均成立才接收相机手势。
pub fn camera_at(&self, point: Point) -> Option<&MountGeometry> {
// 窗口手势目标选择使用空间索引候选次序，但仍须逐个通过视口种类、外框和内容裁剪。
self.hit_index
.candidates(point, self.mounts.len())
.into_iter()
@@ -595,6 +687,7 @@ fn default_background() -> String {
/// 可校验、可序列化的逻辑绘制命令；转换到设备像素在 display_list 阶段完成。
pub enum RenderCommand {
#[serde(skip_deserializing)]
// 仅本机可构造的不可变图像资源命令，禁止从外部 JSON 反序列化任意图像资源。
Image {
x: f32,
y: f32,
@@ -607,6 +700,7 @@ pub enum RenderCommand {
tint: Option<Color>,
image: Arc<crate::render::image::Image>,
},
// 屏幕矩形中的三维 View 快照，世界几何和相机数据由原生 Arc 独立拥有。
Scene3D {
x: f32,
y: f32,
@@ -614,6 +708,7 @@ pub enum RenderCommand {
height: f32,
view: Arc<crate::scene3d::View>,
},
// 逻辑坐标填充矩形，颜色保存文本，设备缩放和通道解码在显示列表转换时完成。
RoundedRect {
x: f32,
y: f32,
@@ -623,6 +718,7 @@ pub enum RenderCommand {
radius: f32,
color: String,
},
// 逻辑坐标描边矩形，stroke_width 与半径都参与设备同比缩放。
StrokeRoundedRect {
x: f32,
y: f32,
@@ -634,6 +730,7 @@ pub enum RenderCommand {
stroke_width: f32,
color: String,
},
// 逻辑文字和离散字号，可选 wrap_bounds 明确是否换行；旧数据缺省为不换行。
Text {
x: f32,
y: f32,
@@ -649,7 +746,9 @@ pub enum RenderCommand {
impl RenderCommand {
/// 检查当前输入或发布值的不变量，调用方据校验结果决定是否继续。
pub(crate) fn validate(&self) -> Result<()> {
// RenderDocument.validate 逐条调用，按命令种类检查自身数据；不在这里尝试光栅化。
match self {
// 本机图片命令除了外框还包含偏移、角度和透明度，资源像素尺寸必须非零。
Self::Image {
x,
y,
@@ -663,6 +762,7 @@ impl RenderCommand {
..
} => {
validate_rect(*x, *y, *width, *height, 0.)?;
// 所有变换参数有限且 opacity 在 [0,1]，防止无效混合或图像采样。
if ![offset_x, offset_y, angle, opacity]
.iter()
.all(|v| v.is_finite())
@@ -673,6 +773,7 @@ impl RenderCommand {
bail!("invalid image command");
}
}
// 三维视口外框与 view 快照各自验证，场景数据不能仅因外框合法就直接绘制。
Self::Scene3D {
x,
y,
@@ -681,10 +782,12 @@ impl RenderCommand {
view,
} => {
validate_rect(*x, *y, *width, *height, 0.0)?;
// View 的投影/场景不变量失败时拒绝发布，不让无效射线/深度计算进入渲染。
if !view.valid() {
bail!("invalid 3D view");
}
}
// 填充矩形检查有限非负尺寸/圆角，再解码颜色格式。
Self::RoundedRect {
x,
y,
@@ -696,6 +799,7 @@ impl RenderCommand {
validate_rect(*x, *y, *width, *height, *radius)?;
parse_color(color)?;
}
// 描边矩形除公共几何外还必须具有正且有限的描边宽度。
Self::StrokeRoundedRect {
x,
y,
@@ -712,6 +816,7 @@ impl RenderCommand {
}
parse_color(color)?;
}
// 文字无框时只要求坐标有限；有 wrap 框时还校验框和端点的协议范围。
Self::Text {
x,
y,
@@ -720,12 +825,14 @@ impl RenderCommand {
color,
wrap_bounds,
} => {
// 首先拒绝文字原点 NaN/无穷，后续测量与绘制不能处理这类坐标。
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]
.iter()
.any(|value| value.abs() > crate::ui_bridge::MAX_DIMENSION as f32)
@@ -733,9 +840,11 @@ impl RenderCommand {
bail!("text wrap bounds exceed limits");
}
}
// 单条文字按 UTF-8 字节限长 16 KiB，不按字符数估算资源用量。
if value.len() > 16_384 {
bail!("text command exceeds 16 KiB");
}
// size 是 1..8 的样式等级，不是任意像素字号。
if !(1..=8).contains(size) {
bail!("text size must be between 1 and 8");
}
@@ -747,7 +856,9 @@ impl RenderCommand {
/// 把一条已验证的发布命令变成原生绘制原语，缩放几何和文字样式。
fn to_draw_command(&self, scale: f32) -> Result<DrawCommand> {
// display_list 调用这里把逻辑命令同比缩放为设备原语；二维平移由调用方随后统一追加。
Ok(match self {
// 图像保留不可变资源 Arc，原点/局部矩形按比例缩放，角度、透明度和 tint 保持其含义。
Self::Image {
x,
y,
@@ -767,6 +878,7 @@ impl RenderCommand {
opacity: *opacity,
tint: *tint,
},
// 只缩放三维视口屏幕矩形，内部相机与世界场景仍由 View 快照解释。
Self::Scene3D {
x,
y,
@@ -777,6 +889,7 @@ impl RenderCommand {
rect: scaled_rect(*x, *y, *width, *height, scale),
view: view.clone(),
},
// 填充矩形位置/尺寸/圆角同比缩放，颜色转为渲染器通道值。
Self::RoundedRect {
x,
y,
@@ -789,6 +902,7 @@ impl RenderCommand {
radius: radius * scale,
color: parse_color(color)?,
},
// 描边宽度也乘设备比例，保持与矩形外观一致的视觉厚度。
Self::StrokeRoundedRect {
x,
y,
@@ -812,12 +926,14 @@ impl RenderCommand {
wrap_bounds,
// 根据是否提供换行边界选择 WrappedText 或 Text；两者都使用同一等级字号与设备缩放。
} => match wrap_bounds {
// 有 wrap 框时产生 WrappedText，排字区域和样式同时缩放，保持换行语义。
Some([width, height]) => DrawCommand::WrappedText {
rect: scaled_rect(*x, *y, *width, *height, scale),
value: value.clone(),
style: crate::text::TextStyle::ui(*size).scaled(scale),
color: parse_color(color)?,
},
// 旧 JSON 未提供 wrap_bounds 时保留不换行 Text 行为，不凭测量结果补造裁剪。
None => DrawCommand::Text {
origin: Point::new(x * scale, y * scale),
value: value.clone(),
@@ -841,6 +957,7 @@ fn default_text_size() -> u32 {
/// 统一检查有限矩形坐标、尺寸与可选圆角，阻止异常值进入光栅循环。
fn validate_rect(x: f32, y: f32, width: f32, height: f32, radius: f32) -> Result<()> {
// 各命令/clip 共用基础几何检查；世界坐标可负，但四个分量必须有限。
if !x.is_finite() || !y.is_finite() || !width.is_finite() || !height.is_finite() {
bail!("rectangle values must be finite");
}
@@ -858,6 +975,7 @@ fn scaled_rect(x: f32, y: f32, width: f32, height: f32, scale: f32) -> Rect {
/// 解析支持的十六进制 RGB/RGBA 文本，拒绝错误长度或非法字符。
pub fn parse_color(value: &str) -> Result<Color> {
// 属性解码、文档验证和显示列表转换共用颜色入口，必须带显式 # 前缀。
let hex = value
.strip_prefix('#')
.ok_or_else(|| anyhow::anyhow!("color must begin with #"))?;
@@ -865,6 +983,7 @@ pub fn parse_color(value: &str) -> Result<Color> {
if !hex.is_ascii() || (hex.len() != 6 && hex.len() != 8) {
bail!("color must use #RRGGBB or #RRGGBBAA");
}
// 已确认 ASCII 和长度后，可安全按字节成对解析 R/G/B/A，非法十六进制仍返回错误。
let parse = |range| u8::from_str_radix(&hex[range], 16);
Ok(Color::rgba(
parse(0..2)?,
@@ -880,6 +999,7 @@ mod tests {
#[test]
/// 旧文字JSON缺wrap_bounds仍走不换行命令；合法边界随DPI缩放，负宽度在发布验证中拒绝。
fn text_wrap_bounds_validate_and_legacy_text_remains_unwrapped() {
// 从缺省 wrap_bounds 的旧 JSON 反序列化，验证兼容默认值而非手工构造近似命令。
let mut command: RenderCommand = serde_json::from_str(
r##"{"type":"text","x":0,"y":0,"value":"text","size":1,"color":"#000000"}"##,
)
@@ -888,6 +1008,7 @@ mod tests {
command.to_draw_command(1.0).unwrap(),
DrawCommand::Text { .. }
));
// 添加合法 40×20 框，后面以 1.25 DPI 核对实际绘制原语尺寸。
if let RenderCommand::Text { wrap_bounds, .. } = &mut command {
*wrap_bounds = Some([40.0, 20.0]);
}
@@ -895,6 +1016,7 @@ mod tests {
assert!(
matches!(command.to_draw_command(1.25).unwrap(),DrawCommand::WrappedText{rect,..}if rect.width==50.0 && rect.height==25.0)
);
// 再破坏为负宽，要求发布验证拒绝，而不是把尺寸夹到零继续显示。
if let RenderCommand::Text { wrap_bounds, .. } = &mut command {
*wrap_bounds = Some([-1.0, 20.0]);
}
@@ -906,6 +1028,7 @@ mod tests {
#[test]
/// 默认空文档可通过验证且没有结构根/绘图命令，支持初始状态与清空发布。
fn empty_document_is_valid_and_blank() {
// 默认值代表初始化/清空后的合法空状态，既不需要源码树也不需要业务命令。
let document = RenderDocument::default();
document.validate().unwrap();
assert!(document.root.is_none());
@@ -915,6 +1038,7 @@ mod tests {
#[test]
/// 检查六位色默认alpha255，八位色按RRGGBBAA解码，避免将末尾透明度当成首通道。
fn parses_rgb_and_rgba_colors() {
// 六位色默认不透明，八位色最后两位为 alpha，分别核对通道顺序。
assert_eq!(
parse_color("#102030").unwrap(),
Color::rgba(16, 32, 48, 255)
@@ -932,13 +1056,16 @@ mod window_projection_tests {
#[test]
/// 同会话窗口命令可累积，新会话发布先丢旧命令；clear重置runtime_session并清空所有原生命令。
fn replacement_and_reset_discard_old_window_projections() {
// 模拟 API 发布状态，先在同一 VM session 累积不同动作，再更换世代。
let mut state = NamespaceState::default();
// 第一动作 Focus 与随后 Resize 类型不同，同世代合并不应互相覆盖。
let command = crate::window::Command {
window: 1,
sequence: 1,
action: crate::window::Action::Focus,
};
state.publish_window_commands(1, vec![command.clone()]);
// 第二动作使用更大 sequence，检验同世代累积及换世代清旧命令。
let resize = crate::window::Command {
window: 1,
sequence: 2,
@@ -952,6 +1079,7 @@ mod window_projection_tests {
state.publish_window_commands(2, vec![resize]);
assert_eq!(state.window_commands.len(), 1);
assert_eq!(state.window_commands[0].session, 2);
// clear 应清除当前 runtime_session 和待传输命令，旧 VM 请求不能在重置后落到新窗口。
state.clear().unwrap();
assert_eq!(state.runtime_session, 0);
assert!(state.window_commands.is_empty());