//! 运行时与窗口线程之间的发布数据契约。NamespaceState 管理提交序号、版本和当前完整文档。
//! RenderDocument/Frame 包含绘制命令、Mount 几何、页面标签和相机投影。发布前统一检查数量、坐标、颜色及索引一致性。
//! 屏幕命中、逻辑坐标和世界 UI 的射线映射必须与绘制采用同一变换；这里的 ID 是数据身份，不是窗口线程可操作的托管引用。
//! 调用路径：API worker 用 NamespaceState 提交/清空候选；桥接发布前调用 validate。
//! 窗口壳用 Frame 命中结果构造输入，worker 再复核；软件渲染入口用 display_list 转为设备坐标命令。
//! 所有发布值拥有绘制所需原生数据，不能要求窗口线程通过 ID 解引用 VM。
//!
use std::collections::HashSet;
use std::sync::Arc;

use anyhow::{Context as _, Result, bail};
use serde::{Deserialize, Serialize};

use crate::{
    display_list::{Color, DisplayList, DrawCommand},
    geometry::{Point, Rect},
    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>,
}

impl Default for NamespaceState {
    /// 建立类型约定的初始值，供尚未发布或尚未交互的状态使用。
    fn default() -> Self {
        Self {
            name: DEFAULT_NAMESPACE.to_owned(),
            revision: 0,
            submission: 0,
            document: RenderDocument::default(),
            viewport: None,
            window_viewports: std::collections::BTreeMap::new(),
            runtime_session: 0,
            window_commands: Vec::new(),
        }
    }
}

impl NamespaceState {
    /// 在成功发布边界切换到指定 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
            // resources belong to their originating runtime generation.
            self.window_viewports
                .retain(|id, _| *id == crate::window::MAIN_WINDOW);
        }
        self.runtime_session = session;
        // 零表示无有效 VM 会话，清空传输请求并忽略传入命令，不能让退役结果重新控制窗口。
        if session == 0 {
            self.window_commands.clear();
            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);
    }

    /// 计算下一个完整源码提交身份；计数溢出时返回错误而不是复用旧身份。
    pub fn next_submission(&self) -> Result<u64> {
        self.submission
            .checked_add(1)
            .context("submission counter exhausted")
    }

    /// 仅当提交身份仍是最新时替换完整文档并递增版本；已被取代的结果不发布。
    pub fn commit(&mut self, submission: u64, document: RenderDocument) -> Result<Option<u64>> {
        // 先核对归属，再计算新版本；失败或过时的结果不会替换已显示文档。
        if submission != self.submission {
            return Ok(None);
        }
        // 先计算可用新版本，溢出时整个提交失败且旧文档仍在。
        let revision = self
            .revision
            .checked_add(1)
            .context("revision counter exhausted")?;
        self.document = document;
        self.revision = revision;
        Ok(Some(revision))
    }

    /// 推进提交身份和发布版本，替换为空文档并清除运行时命令，使旧提交不能覆盖清空结果。
    pub fn clear(&mut self) -> Result<u64> {
        // clear 也创建新提交身份，让先前在途的合法候选失去发布资格。
        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;
        self.window_commands.clear();
        self.revision = revision;
        Ok(revision)
    }
}

#[derive(Clone, Debug, Default, Serialize, Deserialize)]
/// 可以离开 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,
}

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]
                .iter()
                .all(|v| v.is_finite() && v.abs() <= 1_000_000.0)
            || ![surface.extent.width, surface.extent.height]
                .iter()
                .all(|v| v.is_finite() && (0.0..=1_000_000.0).contains(v))
        {
            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()
            {
                bail!("invalid secondary window projection");
            }
            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");
        }
        parse_color(&self.frame.background)?;
        // 空平行表是兼容的“全部无 clip/view”；一旦非空就必须与 commands 等长，禁止半张索引表。
        if !self.frame.command_clips.is_empty()
            && self.frame.command_clips.len() != self.frame.commands.len()
        {
            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
                .frame
                .tabs
                .iter()
                .any(|tab| tab.id == 0 || !tab_ids.insert(tab.id) || tab.title.len() > 1024)
        {
            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)?;
            }
            // 滚动投影为 [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)
                }) || scroll[0] > scroll[2]
                    || scroll[1] > scroll[3])
            {
                bail!("invalid scroll projection");
            }
        }
        // 此处只保证关系目标在帧内，不做完整树环/双向一致性验证；组成与生命周期层承担更强结构不变量。
        // 第二轮使用完整 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");
                }
            }
        }

        // 携带本机视觉根时必须与第一个根出现的业务身份一致；反序列化无 ui_root 时跳过这项。
        if let Some(root) = &self.ui_root
            && self
                .frame
                .mounts
                .first()
                .is_none_or(|mount| mount.block_id != root.block_id)
        {
            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)?;
        }
        Ok(())
    }

    /// 将逻辑命令转换到设备比例并应用逐命令视图/裁剪；不自动调用 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 {
                list.push(DrawCommand::PushClip(scaled_rect(
                    clip[0], clip[1], clip[2], clip[3], scale,
                )));
            }
            // 没有逐命令 view 时使用单位变换；实际缩放由设备 scale×view.zoom 组成。
            let view = frame
                .command_views
                .get(index)
                .copied()
                .flatten()
                .unwrap_or_default();
            list.push(
                command
                    // 均匀缩放包含字体、半径和描边，随后平移只改原点；不能把位移再乘一次 view.zoom。
                    .to_draw_command(scale * view.zoom)?
                    .translated(Point::new(view.x * scale, view.y * scale)),
            );
            // 本命令已经绘制，配对弹出先前压入的 clip，维持列表栈平衡。
            if clip.is_some() {
                list.push(DrawCommand::PopClip);
            }
        }
        // 根层只绘制非面板的焦点框；面板内焦点已在 panel::compose 放入纹理，避免重复或脱离面板。
        if let Some(focus) = frame
            .focus
            .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,
                )));
            }
            list.push(
                RenderCommand::StrokeRoundedRect {
                    x: focus
                        .view
                        .unwrap_or_default()
                        .rect(Rect::new(focus.x, focus.y, focus.width, focus.height))
                        .x,
                    y: focus
                        .view
                        .unwrap_or_default()
                        .rect(Rect::new(focus.x, focus.y, focus.width, focus.height))
                        .y,
                    width: focus.width * focus.view.unwrap_or_default().zoom,
                    height: focus.height * focus.view.unwrap_or_default().zoom,
                    radius: 7.0,
                    stroke_width: 2.0,
                    color: "#4F6FDB".into(),
                }
                .to_draw_command(scale)?,
            );
            // 焦点框单独配对弹出 clip，避免把之后的故障提示也裁掉。
            if focus.clip.is_some() {
                list.push(DrawCommand::PopClip);
            }
        }
        // 故障提示最后追加在页面上方，只显示错误第一行；状态是否允许输入由 Frame.hit_test 等另行限制。
        if let Some(error) = &frame.fault {
            list.push(
                RenderCommand::RoundedRect {
                    x: 0.0,
                    y: 0.0,
                    width: 10000.0,
                    height: 36.0,
                    radius: 0.0,
                    color: "#FFF1EF".into(),
                }
                .to_draw_command(scale)?,
            );
            list.push(
                RenderCommand::Text {
                    x: 12.0,
                    y: 8.0,
                    value: format!("运行已停止：{}", error.lines().next().unwrap_or_default()),
                    size: 1,
                    color: "#A32D25".into(),
                    wrap_bounds: None,
                }
                .to_draw_command(scale)?,
            );
        }
        Ok(list)
    }

    /// 从源码投影根按 ID 查找节点，供 Sources 查看与定位使用。
    pub fn node(&self, id: &str) -> Option<&CodeNode> {
        self.root.as_ref()?.find(id)
    }
}

#[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>,
}

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");
        }
        // 空源码节点 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);
        }
        // 零行号表示未提供来源；只有两端均非零时检查顺序，不把兼容缺失字段当非法。
        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)?;
        }
        Ok(())
    }

    /// 按请求的代码节点身份或路径查找对应的源码投影。
    fn find(&self, id: &str) -> Option<&CodeNode> {
        // node(id) 先匹配当前节点，未命中再按孩子顺序递归返回首个匹配。
        if self.id == id {
            return Some(self);
        }
        self.children.iter().find_map(|child| child.find(id))
    }
}

#[derive(Clone, Debug, Serialize, Deserialize)]
/// 一个窗口的一次完整视觉发布：有序命令及其裁剪/变换、出现几何、焦点和版本。平行索引表必须和命令数量一致。
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>,
}

impl Default for Frame {
    /// 建立类型约定的初始值，供尚未发布或尚未交互的状态使用。
    fn default() -> Self {
        Self {
            hit_index: Arc::default(),
            surface: crate::page::Surface::default(),
            window: crate::window::MAIN_WINDOW,
            background: default_background(),
            commands: Vec::new(),
            command_clips: Vec::new(),
            command_views: Vec::new(),
            command_mounts: Vec::new(),
            mounts: Vec::new(),
            layout_version: 0,
            session: 0,
            focus: None,
            tabs: Vec::new(),
            fault: None,
        }
    }
}

/// A position in a published frame. Identifiers are opaque data, never VM handles.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
/// 某次出现的几何与投影元数据。逻辑矩形不被相机直接改写，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,
    #[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,
}

impl MountGeometry {
    /// 先沿世界 UI 面板逆投影指针，按需要执行可见性和裁剪检查。
    pub fn view_point(&self, point: Point, clipped: bool) -> Option<Point> {
        self.panel
            .as_ref()
            .map_or(Some(point), |panel| panel.texture_point(point, clipped))
    }
    /// 把页面指针转换为该出现的布局坐标，供 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]);
        }
        // 面板投影非线性，缺少当前位置就无法正确换算 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 =
            self.view_point(Point::new(point[0] + delta[0], point[1] + delta[1]), false)?;
        Some([
            ((previous.x - current.x) / zoom).clamp(-1_000_000., 1_000_000.),
            ((previous.y - current.y) / zoom).clamp(-1_000_000., 1_000_000.),
        ])
    }
    /// 判断给定点是否位于目标范围；需要相机转换的类型会先转换再判断。
    pub fn contains(&self, point: Point) -> bool {
        // 先完成世界面板反投影和遮挡检查，失败直接视为未命中。
        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| {
                c[2] > 0.0 && c[3] > 0.0 && Rect::new(c[0], c[1], c[2], c[3]).contains(point)
            })
    }
}

impl Frame {
    /// 从顶层绘制顺序向后查找可控制的视口，命中与裁剪均成立才接收相机手势。
    pub fn camera_at(&self, point: Point) -> Option<&MountGeometry> {
        // 窗口手势目标选择使用空间索引候选次序，但仍须逐个通过视口种类、外框和内容裁剪。
        self.hit_index
            .candidates(point, self.mounts.len())
            .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| {
                        mount.view_point(point, true).is_some_and(|point| {
                            Rect::new(clip[0], clip[1], clip[2], clip[3]).contains(point)
                        })
                    })
            })
    }
    /// 在无故障帧中按逆绘制顺序选中可交互的出现，空间索引只缩小候选。
    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()
            .map(|index| &self.mounts[index])
            .find(|mount| mount.interactive && mount.contains(point))
    }
}

/// 返回默认主窗口身份，供省略窗口字段的兼容输入使用。
fn default_window() -> u64 {
    crate::window::MAIN_WINDOW
}

/// 提供空帧或未指定背景时的默认页面底色。
fn default_background() -> String {
    "#F7F7F5".to_owned()
}

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
/// 可校验、可序列化的逻辑绘制命令；转换到设备像素在 display_list 阶段完成。
pub enum RenderCommand {
    #[serde(skip_deserializing)]
    // 仅本机可构造的不可变图像资源命令，禁止从外部 JSON 反序列化任意图像资源。
    Image {
        x: f32,
        y: f32,
        width: f32,
        height: f32,
        offset_x: f32,
        offset_y: f32,
        angle: f32,
        opacity: f32,
        tint: Option<Color>,
        image: Arc<crate::render::image::Image>,
    },
    // 屏幕矩形中的三维 View 快照，世界几何和相机数据由原生 Arc 独立拥有。
    Scene3D {
        x: f32,
        y: f32,
        width: f32,
        height: f32,
        view: Arc<crate::scene3d::View>,
    },
    // 逻辑坐标填充矩形，颜色保存文本，设备缩放和通道解码在显示列表转换时完成。
    RoundedRect {
        x: f32,
        y: f32,
        width: f32,
        height: f32,
        #[serde(default)]
        radius: f32,
        color: String,
    },
    // 逻辑坐标描边矩形，stroke_width 与半径都参与设备同比缩放。
    StrokeRoundedRect {
        x: f32,
        y: f32,
        width: f32,
        height: f32,
        #[serde(default)]
        radius: f32,
        #[serde(default = "default_stroke_width")]
        stroke_width: f32,
        color: String,
    },
    // 逻辑文字和离散字号，可选 wrap_bounds 明确是否换行；旧数据缺省为不换行。
    Text {
        x: f32,
        y: f32,
        value: String,
        #[serde(default = "default_text_size")]
        size: u32,
        color: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        wrap_bounds: Option<[f32; 2]>,
    },
}

impl RenderCommand {
    /// 检查当前输入或发布值的不变量，调用方据校验结果决定是否继续。
    pub(crate) fn validate(&self) -> Result<()> {
        // RenderDocument.validate 逐条调用，按命令种类检查自身数据；不在这里尝试光栅化。
        match self {
            // 本机图片命令除了外框还包含偏移、角度和透明度，资源像素尺寸必须非零。
            Self::Image {
                x,
                y,
                width,
                height,
                offset_x,
                offset_y,
                angle,
                opacity,
                image,
                ..
            } => {
                validate_rect(*x, *y, *width, *height, 0.)?;
                // 所有变换参数有限且 opacity 在 [0,1]，防止无效混合或图像采样。
                if ![offset_x, offset_y, angle, opacity]
                    .iter()
                    .all(|v| v.is_finite())
                    || !(0. ..=1.).contains(opacity)
                    || image.width == 0
                    || image.height == 0
                {
                    bail!("invalid image command");
                }
            }
            // 三维视口外框与 view 快照各自验证，场景数据不能仅因外框合法就直接绘制。
            Self::Scene3D {
                x,
                y,
                width,
                height,
                view,
            } => {
                validate_rect(*x, *y, *width, *height, 0.0)?;
                // View 的投影/场景不变量失败时拒绝发布，不让无效射线/深度计算进入渲染。
                if !view.valid() {
                    bail!("invalid 3D view");
                }
            }
            // 填充矩形检查有限非负尺寸/圆角，再解码颜色格式。
            Self::RoundedRect {
                x,
                y,
                width,
                height,
                radius,
                color,
            } => {
                validate_rect(*x, *y, *width, *height, *radius)?;
                parse_color(color)?;
            }
            // 描边矩形除公共几何外还必须具有正且有限的描边宽度。
            Self::StrokeRoundedRect {
                x,
                y,
                width,
                height,
                radius,
                stroke_width,
                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");
                }
                parse_color(color)?;
            }
            // 文字无框时只要求坐标有限；有 wrap 框时还校验框和端点的协议范围。
            Self::Text {
                x,
                y,
                value,
                size,
                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)
                    {
                        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");
                }
                parse_color(color)?;
            }
        }
        Ok(())
    }

    /// 把一条已验证的发布命令变成原生绘制原语，缩放几何和文字样式。
    fn to_draw_command(&self, scale: f32) -> Result<DrawCommand> {
        // display_list 调用这里把逻辑命令同比缩放为设备原语；二维平移由调用方随后统一追加。
        Ok(match self {
            // 图像保留不可变资源 Arc，原点/局部矩形按比例缩放，角度、透明度和 tint 保持其含义。
            Self::Image {
                x,
                y,
                width,
                height,
                offset_x,
                offset_y,
                angle,
                opacity,
                tint,
                image,
            } => DrawCommand::Image {
                image: image.clone(),
                origin: Point::new(x * scale, y * scale),
                rect: scaled_rect(*offset_x, *offset_y, *width, *height, scale),
                angle: *angle,
                opacity: *opacity,
                tint: *tint,
            },
            // 只缩放三维视口屏幕矩形，内部相机与世界场景仍由 View 快照解释。
            Self::Scene3D {
                x,
                y,
                width,
                height,
                view,
            } => DrawCommand::Scene3D {
                rect: scaled_rect(*x, *y, *width, *height, scale),
                view: view.clone(),
            },
            // 填充矩形位置/尺寸/圆角同比缩放，颜色转为渲染器通道值。
            Self::RoundedRect {
                x,
                y,
                width,
                height,
                radius,
                color,
            } => DrawCommand::FillRoundedRect {
                rect: scaled_rect(*x, *y, *width, *height, scale),
                radius: radius * scale,
                color: parse_color(color)?,
            },
            // 描边宽度也乘设备比例，保持与矩形外观一致的视觉厚度。
            Self::StrokeRoundedRect {
                x,
                y,
                width,
                height,
                radius,
                stroke_width,
                color,
            } => DrawCommand::StrokeRoundedRect {
                rect: scaled_rect(*x, *y, *width, *height, scale),
                radius: radius * scale,
                width: stroke_width * scale,
                color: parse_color(color)?,
            },
            Self::Text {
                x,
                y,
                value,
                size,
                color,
                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(),
                    style: crate::text::TextStyle::ui(*size).scaled(scale),
                    color: parse_color(color)?,
                },
            },
        })
    }
}

/// 提供未指定描边宽度时的兼容默认值。
fn default_stroke_width() -> f32 {
    1.0
}

/// 提供未指定字号时的协议默认值。
fn default_text_size() -> u32 {
    1
}

/// 统一检查有限矩形坐标、尺寸与可选圆角，阻止异常值进入光栅循环。
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");
    }
    // 此基础检查只要求有限、非负几何与圆角，不加世界坐标绝对值上限；更严格范围由具体协议调用路径决定。
    if width < 0.0 || height < 0.0 || !radius.is_finite() || radius < 0.0 {
        bail!("rectangle dimensions and radius cannot be negative");
    }
    Ok(())
}

/// 将逻辑矩形转换为设备比例下的矩形，保持位置与尺寸同比缩放。
fn scaled_rect(x: f32, y: f32, width: f32, height: f32, scale: f32) -> Rect {
    Rect::new(x * scale, y * scale, width * scale, height * scale)
}

/// 解析支持的十六进制 RGB/RGBA 文本，拒绝错误长度或非法字符。
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");
    }
    // 已确认 ASCII 和长度后，可安全按字节成对解析 R/G/B/A，非法十六进制仍返回错误。
    let parse = |range| u8::from_str_radix(&hex[range], 16);
    Ok(Color::rgba(
        parse(0..2)?,
        parse(2..4)?,
        parse(4..6)?,
        // 顺序为 RRGGBBAA 而非 AARRGGBB，六位色号默认完全不透明。
        if hex.len() == 8 { parse(6..8)? } else { 255 },
    ))
}

#[cfg(test)]
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"}"##,
        )
        .unwrap();
        assert!(matches!(
            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]);
        }
        command.validate().unwrap();
        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]);
        }
        assert!(command.validate().is_err());
    }

    use super::*;

    #[test]
    /// 默认空文档可通过验证且没有结构根/绘图命令，支持初始状态与清空发布。
    fn empty_document_is_valid_and_blank() {
        // 默认值代表初始化/清空后的合法空状态，既不需要源码树也不需要业务命令。
        let document = RenderDocument::default();
        document.validate().unwrap();
        assert!(document.root.is_none());
        assert!(document.frame.commands.is_empty());
    }

    #[test]
    /// 检查六位色默认alpha255，八位色按RRGGBBAA解码，避免将末尾透明度当成首通道。
    fn parses_rgb_and_rgba_colors() {
        // 六位色默认不透明，八位色最后两位为 alpha，分别核对通道顺序。
        assert_eq!(
            parse_color("#102030").unwrap(),
            Color::rgba(16, 32, 48, 255)
        );
        assert_eq!(
            parse_color("#10203080").unwrap(),
            Color::rgba(16, 32, 48, 128)
        );
    }
}

#[cfg(test)]
mod window_projection_tests {
    use super::*;
    #[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,
            action: crate::window::Action::Resize {
                width: 900.0,
                height: 600.0,
            },
        };
        state.publish_window_commands(1, vec![resize.clone()]);
        assert_eq!(state.window_commands.len(), 2);
        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());
    }
}