//! 托管 Window 的页面所有权、原生命令与关闭生命周期。
//! 源码 resize/focus/setTitle 先产生纯数据命令；只有所属输入成功发布后，GUI 线程才应用它们。
//! 窗口 ID 和运行时 session 共同限定资源归属；切换 VM 或关闭窗口时不能让旧命令作用到新资源。
//!
//! 调用路径：bootstrap 调用 install 建立主窗口；桥接新窗口/页面 API 调用 create、登记、重排与 close。
//! ReplSession 收集 take_commands 后，由 API worker 为成功发布的命令附 session，GUI 再执行对应 OS 操作。
//! 生命周期退役使用 retire/unregister_page_host 的宿主入口，不借已停止 VM 重跑源回调。
//!
//! Managed window resources and versioned, coalesced native projections.
//! The VM owns Page roots; only scalar commands cross to the GUI thread.
use crate::{native_visual, object_list, ui_bridge::desktop_type};
use endor_core::{
    ContextNativeFunction, NativeCallable, NativeContext, NativeResult, ObjectPayload, ObjectRef,
    ObjectStore, Value, Vm, VmError,
};
use std::sync::{Arc, Mutex};

// 主窗口的资源 ID 固定为 1，壳可在 VM 替换后继续存在；真正命令归属还要检查 session。
pub const MAIN_WINDOW: u64 = 1;
// 源 resize 的每轴逻辑尺寸上限，独立于世界场景坐标和软件渲染像素预算。
pub const MAX_WINDOW_DIMENSION: f64 = 4096.0;
#[derive(Debug, Clone, PartialEq)]
/// 可投影到原生窗口的动作类别，如尺寸、标题、焦点与关闭。
pub enum Action {
    // 纯数据逻辑宽高请求，不会从 VM 线程直接调用 OS resize。
    Resize { width: f64, height: f64 },
    // 完整新标题文本，同类请求合并时取最后一次。
    SetTitle(String),
    // 屏幕整数坐标，允许负数支持多显示器布局。
    MoveTo { x: i32, y: i32 },
    // 请求操作系统聚焦窗口，区别于某个 Mount 的页面焦点。
    Focus,
    // 源关闭流程完成后的原生退役请求，旧 session 不得关闭新资源。
    Close,
}
#[derive(Debug, Clone, PartialEq)]
/// 成功发布后由 GUI 执行的一条原生窗口请求，含资源身份和动作顺序。
pub struct Command {
    // 目标原生资源 ID，与外层 Envelope.session 一起确定归属。
    pub window: u64,
    // 单窗口动作先后序号，合并可产生空洞但不得反向执行。
    pub sequence: u64,
    // 请求内容只含可离开 VM 的数值/文本，不含 ObjectRef。
    pub action: Action,
}
impl Command {
    /// 判断两条命令是否针对同一资源的同类动作，用于替换尚未执行的旧请求。
    pub fn same_kind(&self, other: &Self) -> bool {
        // 比较动作变体而不是参数值：同窗口多次 Resize/SetTitle 可合并为最后一次，不同动作仍按序保留。
        self.window == other.window
            && std::mem::discriminant(&self.action) == std::mem::discriminant(&other.action)
    }
}
#[derive(Debug, Clone)]
/// 附带运行时 session 的命令，阻止旧域请求在新 VM 上生效。
pub struct Envelope {
    // 产生该命令的运行时世代，API 发布状态切换 VM 时丢弃旧世代请求。
    pub session: u64,
    // 已合并排序的窗口动作，GUI 先核对世代再作用到 OS 窗口。
    pub command: Command,
}
#[derive(Debug, Clone)]
/// 托管窗口资源状态与页面拥有关系；本对象存在不等于 OS 窗口已创建。
pub struct ManagedWindow {
    // VM 内窗口资源 ID，创建托管对象不代表同 ID OS 窗口已经完成创建。
    pub id: u64,
    // 每窗口拥有独立 desktop、tabs 与页面顺序；同 VM 的类型注册表可共享，不复制业务模型。
    pub desktop: ObjectRef,
    // 逻辑关闭标志，阻止继续操作/登记页面；id/pages 查询仍允许。
    pub closed: bool,
    // 窗口 owner 的任务作用域强引用，真实关闭时先取消再退役页面。
    pub tasks: Option<ObjectRef>,
    // 托管页面字典拥有关系，与 pages 顺序 Vec 一起维护；字典键为 Page 身份文本。
    tabs: ObjectRef,
    // 页面身份的有序强拥有集合，tabs 字典同时提供托管注册入口；移动顺序只调整此 Vec。
    pages: Vec<ObjectRef>,
    // 最近已入队动作的单调序号，enqueue 先检查溢出再替换 payload。
    sequence: u64,
    // Transport state only. Draining it must not change a language object's
    // version or create a render-dependency feedback loop.
    // 仅保存纯数据传输队列，克隆 payload 仍共享同一 outbox；drain 不触发 VM 内容版本，避免反馈循环。
    outbox: Arc<Mutex<Vec<Command>>>,
}
impl ObjectPayload for ManagedWindow {
    /// 提供受检查的 Any 下转型入口，让宿主按具体 payload 类型读取数据。
    fn as_any(&self) -> &dyn std::any::Any {
        self
    }
    /// 返回运行时诊断/类型检查使用的稳定 payload 名称。
    fn kind_name(&self) -> &'static str {
        "tessera-window"
    }
    /// 声明此 payload 是否允许使用托管属性存储，具体字段仍由类型与调用检查约束。
    fn allows_attributes(&self) -> bool {
        true
    }
    /// 声明此 payload 的赋值遵循引用身份语义，避免把内部宿主状态当作可复制值。
    fn reference_assignment_only(&self) -> bool {
        true
    }
    /// 枚举本对象真正拥有的托管强引用，供 Aster 引用追踪和循环回收使用。
    fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
        // GC 追踪独立桌面，保证挂载字典与待展示状态属于可见托管拥有图。
        visit(self.desktop);
        // 只追踪存在的任务作用域，任务自己的图再由任务 payload 暴露。
        if let Some(tasks) = self.tasks {
            visit(tasks);
        }
        // tabs 字典与 pages 都是真实拥有边，不能仅在宿主 Vec 保存句柄而漏掉引用追踪。
        visit(self.tabs);
        // 依序强持有全部登记 Page，不只保留当前活动页；重排不改变这些对象身份。
        for page in &self.pages {
            visit(*page);
        }
    }
}
/// 统一构造本模块的参数错误，让调用方停止处理无效输入。
fn invalid(message: &'static str) -> VmError {
    VmError::InvalidArgument(message)
}
/// 把源数值转换为有限屏幕坐标，拒绝越界或不可表示的值。
fn screen_coordinate(value: &Value) -> Result<i32, VmError> {
    // moveTo 参数要求整数 Number，不把文本屏幕位置或小数隐式截断。
    let Value::Number(value) = value else {
        return Err(invalid("screen position requires integer coordinates"));
    };
    // 屏幕位置必须为整数，允许负坐标以覆盖多显示器；范围与 i32 转换均检查，不能把小数直接截断。
    value
        .as_i64()
        .filter(|number| (-1_000_000..=1_000_000).contains(number))
        .and_then(|number| i32::try_from(number).ok())
        .ok_or(invalid("screen position exceeds limits"))
}
/// 从源 Value 取得窗口操作需要的数值，保留错误类型诊断。
fn scalar(value: &Value) -> Result<f64, VmError> {
    // resize 每轴要求 Number，错误类型在进入原生命令队列前拒绝。
    let Value::Number(value) = value else {
        return Err(invalid("window size requires numbers"));
    };
    // 先转 f64 再检查有限性和逻辑窗口尺寸范围，超界不会在 OS 侧被静默钳制。
    let number = value
        .to_string()
        .parse::<f64>()
        .map_err(|_| invalid("invalid window size"))?;
    // 每轴至少为 1、最多 4096，NaN/无穷同样非法。
    if !number.is_finite() || !(1.0..=MAX_WINDOW_DIMENSION).contains(&number) {
        return Err(invalid("window size exceeds limits"));
    }
    Ok(number)
}
#[derive(Debug, Clone, Copy)]
/// 当前宿主 API 的操作分类，分派代码负责参数校验与状态更新。
enum Operation {
    // 返回稳定资源数值身份，窗口已关闭后仍可查询。
    Id,
    // 读取此窗口 desktop 的当前逻辑视口，未提供尺寸时失败。
    Viewport,
    // 返回按登记顺序的新对象列表，成员仍为原 Page 引用。
    Pages,
    // 排队修改原生逻辑尺寸，读协议期间禁止。
    Resize,
    // 排队移动 OS 窗口到带符号整数屏幕位置。
    MoveTo,
    // 排队更新标题，按字节限长并拒绝控制字符。
    SetTitle,
    // 排队原生聚焦；不会直接选择某个页面 Mount。
    Focus,
}
#[derive(Debug)]
/// 保存 owner、签名或操作枚举的原生方法适配器，统一由 VM 调用。
struct Method {
    // 安装时从当前桌面类型构造的未绑定方法契约，首个参数是 Window receiver。
    signature: endor_core::CallSignature,
    // 统一适配器的行为分派，同时决定 arity 和结果/效果类型。
    operation: Operation,
    // 类型注册所在主桌面，由 native captures 保活；读取 viewport 时使用 receiver 自己的 desktop。
    desktop: ObjectRef,
}
impl NativeCallable for Method {
    /// 给出参数与返回值的托管类型契约；实际操作在 invoke 中执行。
    fn signature(&self) -> Option<endor_core::CallSignature> {
        Some(self.signature.clone())
    }
    /// 计入 Window 接收者：resize/moveTo 共三参，setTitle 两参，其他查询/聚焦只要接收者。
    fn arity(&self) -> Option<endor_core::CallArity> {
        Some(endor_core::CallArity::exact(match self.operation {
            Operation::Resize | Operation::MoveTo => 3,
            Operation::SetTitle => 2,
            _ => 1,
        }))
    }

    /// 验证窗口资源与关闭状态；查询返回托管值，原生变更生成待执行命令；世代封装与关闭生命周期由外层入口处理。
    fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
        // 未绑定原生方法从首参取得真正 receiver，再验证 ManagedWindow payload。
        let Some(Value::Object(owner)) = args.first() else {
            return Err(invalid("Window method requires a Window"));
        };
        // 复制当前资源状态，后续分配查询返回值时不持有 payload 借用。
        let data = cx
            .store()
            .payload::<ManagedWindow>(*owner, "Window")?
            .clone();
        // 已关闭窗口仍可查询稳定 ID 与页面集合，其他读取/操作拒绝，避免用旧 viewport 或重开原生资源。
        if data.closed && !matches!(self.operation, Operation::Id | Operation::Pages) {
            return Err(invalid("native window is closed"));
        }
        // 即使签名元数据已声明 arity，入口仍检查实际实参数，避免直接 native 调用越界。
        let expected = match self.operation {
            Operation::Resize | Operation::MoveTo => 3,
            Operation::SetTitle => 2,
            _ => 1,
        };
        // 形状不符立即拒绝，不能读取缺少的宽高/标题实参。
        if args.len() != expected {
            return Err(invalid("incorrect Window method argument count"));
        }
        // 查询构造托管返回值；变更分支只排队命令，最终统一交 VM 返回协议处理。
        let result = match self.operation {
            // 关闭对象仍能返回原 ID，不能借查询 ID 来重开资源。
            Operation::Id => Value::Number((data.id as i64).into()),
            // 复制成员列表到新 ObjectList，成员身份和原登记顺序保持，原窗口集合不被修改。
            Operation::Pages => {
                Value::Object(object_list::collection(cx, data.pages, self.desktop)?)
            }
            // 读取该 Window 自己 desktop 的逻辑视口，封装成 MeasureResult；尚未由原生侧提供尺寸时明确失败。
            Operation::Viewport => {
                // receiver 的逻辑 viewport 尚未由宿主提供时不构造假定默认尺寸。
                let Value::Object(input) = cx.store().get_attr(data.desktop, "viewport")? else {
                    return Err(invalid("window viewport is unavailable"));
                };
                // 逐项读取此窗口现有视口记录，MeasureResult 只包装已知尺寸。
                let width = cx.store().get_attr(input, "width")?;
                // 高度与宽度都来自 receiver.desktop，而非安装方法的主 desktop。
                let height = cx.store().get_attr(input, "height")?;
                Value::Object(native_visual::record(
                    cx,
                    self.desktop,
                    "MeasureResult",
                    vec![("width", width), ("height", height)],
                )?)
            }
            // 余下为原生资源变更，先检查当前只读范围再解码动作参数。
            operation => {
                // 原生命令虽暂存在内存，也属于变更，不能从只读测量/绘制回调发起窗口操作。
                if cx.store().is_read_only() {
                    return Err(invalid(
                        "window operations are forbidden during read-only rendering",
                    ));
                }
                // 参数全部解码成功后才 enqueue，非法标题或尺寸不会产生半个窗口动作。
                let action = match operation {
                    // 两轴独立转受限屏幕整数，可负但不可有小数。
                    Operation::MoveTo => Action::MoveTo {
                        x: screen_coordinate(&args[1])?,
                        y: screen_coordinate(&args[2])?,
                    },
                    // 两轴独立验证有限逻辑尺寸，不把业务世界坐标范围用于 OS 窗口大小。
                    Operation::Resize => Action::Resize {
                        width: scalar(&args[1])?,
                        height: scalar(&args[2])?,
                    },
                    Operation::SetTitle => {
                        // 标题必须是源文本，不能使用对象 str 等隐式转换触发额外源行为。
                        let Value::Text(title) = &args[1] else {
                            return Err(invalid("window title requires text"));
                        };
                        // 标题限制 UTF-8 字节长度并拒绝控制字符；不会在这里执行标题文本或展开 shell 字符。
                        if title.len() > 4096 || title.chars().any(char::is_control) {
                            return Err(invalid("invalid window title"));
                        }
                        Action::SetTitle(title.clone())
                    }
                    Operation::Focus => Action::Focus,
                    _ => unreachable!(),
                };
                // 所有正常方法请求经同一排队屏障，调用成功仍不代表 GUI 已执行。
                enqueue(cx, *owner, action)?;
                Value::Nil
            }
        };
        Ok(NativeResult::Return(result))
    }
}
/// 把合法窗口操作追加到所属窗口的待发布命令，不能直接在 VM 线程操作 OS。
pub fn enqueue(
    cx: &mut NativeContext<'_>,
    owner: ObjectRef,
    action: Action,
) -> Result<(), VmError> {
    // 内部关闭也可经此入口入队 Close；此函数不重复做公开方法的 closed 检查。
    let mut data = cx
        .store()
        .payload::<ManagedWindow>(owner, "Window")?
        .clone();
    // 命令序列单调递增且检查溢出；同类合并会产生序号空洞，但仍可按序比较先后。
    data.sequence = data
        .sequence
        .checked_add(1)
        .ok_or(invalid("window command sequence exhausted"))?;
    // 把已验证动作与资源 ID/新序号组合为独立传输值。
    let command = Command {
        window: data.id,
        sequence: data.sequence,
        action,
    };
    // 克隆 Arc 使 outbox 借用与即将 move 的 payload 分离；transport 不含托管根。
    let queue = data.outbox.clone();
    // 队列锁毒化时报错，不继续修改 VM 版本或丢失原请求。
    let mut queue = queue
        .lock()
        .map_err(|_| invalid("window outbox poisoned"))?;
    // The heap barrier succeeds before any external transport state changes.
    // 必须先成功经过 VM 写屏障，才修改不可回滚的原生 outbox；只读调用不能先留下待发命令再报错。
    cx.replace_payload(owner, data)?;
    // 同窗口同动作只保留最后请求，其他类别保持先后；此处只入队，GUI 是否执行取决于后续成功发布。
    queue.retain(|old| !old.same_kind(&command));
    queue.push(command);
    Ok(())
}

/// 将页面登记到其窗口，维护托管所有权与页面顺序。
pub fn register_page(
    cx: &mut NativeContext<'_>,
    window: ObjectRef,
    page: ObjectRef,
) -> Result<(), VmError> {
    // 登记会改变 Page 拥有关系，不允许从只读布局/绘制回调产生可见资源副作用。
    if cx.store().is_read_only() {
        return Err(invalid(
            "opening a Page is forbidden during read-only rendering",
        ));
    }
    // 读取当前窗口页集合副本，后面以 payload 替换让 VM 正确更新拥有边。
    let mut data = cx
        .store()
        .payload::<ManagedWindow>(window, "Window")?
        .clone();
    // 关闭资源不能重新登记页面，避免旧窗口被页面 open 隐式复活。
    if data.closed {
        return Err(invalid("native window is closed"));
    }
    // 登记幂等，首次同时写 tabs 与 payload；字典键使用页面身份文本而非标题，重命名不改变登记。
    if !data.pages.contains(&page) {
        data.pages.push(page);
        cx.dict_set(
            data.tabs,
            Value::Text(page.to_string()),
            Value::Object(page),
        )?;
        cx.replace_payload(window, data)?;
    }
    Ok(())
}
/// 从窗口的页面集合撤销指定页面，保持后续展示索引一致。
pub fn unregister_page(
    cx: &mut NativeContext<'_>,
    window: ObjectRef,
    page: ObjectRef,
) -> Result<(), VmError> {
    // 撤销登记同样是业务图写入，只读协议中必须在删字典/列表前拒绝。
    if cx.store().is_read_only() {
        return Err(invalid(
            "closing a Page is forbidden during read-only rendering",
        ));
    }
    // 复制现有有序页集合，下面先检查目标确实在该窗口登记。
    let mut data = cx
        .store()
        .payload::<ManagedWindow>(window, "Window")?
        .clone();
    // 不存在时撤销是空操作；存在时同时删有序列表与 tabs 字典边，不能只隐藏原生标签。
    if !data.pages.contains(&page) {
        return Ok(());
    }
    data.pages.retain(|value| *value != page);
    cx.dict_delete(data.tabs, &Value::Text(page.to_string()))?;
    cx.replace_payload(window, data)?;
    Ok(())
}
/// Discard an unpublished Page registration without invoking guest callbacks.
/// 宿主收尾路径撤销页面登记，用于已经由外层决定的关闭/退役流程。
pub fn unregister_page_host(
    vm: &mut Vm,
    window: ObjectRef,
    page: ObjectRef,
) -> Result<(), VmError> {
    // 宿主已确定收尾时直接使用 VM 写屏障，不创建源调用或执行关闭回调。
    let mut data = vm.payload::<ManagedWindow>(window, "Window")?.clone();
    // 存在才同时移除顺序拥有边和 tabs 字典边，缺失则幂等返回。
    if data.pages.contains(&page) {
        data.pages.retain(|value| *value != page);
        vm.dict_delete(data.tabs, &Value::Text(page.to_string()))?;
        vm.replace_payload(window, data)?;
    }
    Ok(())
}

/// 在同一窗口的已登记页面集合内重排标签位置，保留 Page 身份；不负责跨窗口迁移。
pub fn move_page(
    cx: &mut NativeContext<'_>,
    window: ObjectRef,
    page: ObjectRef,
    position: usize,
) -> Result<(), VmError> {
    // 只读取同窗口已登记 Page 集合，本函数不创建/迁移页面或安排新生命周期。
    let mut data = cx
        .store()
        .payload::<ManagedWindow>(window, "Window")?
        .clone();
    // 已关闭窗口不能再重排其旧标签上下文。
    if data.closed {
        return Err(invalid("native window is closed"));
    }
    // 按原 Page 身份定位当前位置，名字/标题可能重复，不能据此识别页面。
    let from = data
        .pages
        .iter()
        .position(|candidate| *candidate == page)
        .ok_or(invalid("Page is not open in this window"))?;
    // position 是最终数组索引，不是允许等于 len 的插入缝。
    if position >= data.pages.len() {
        return Err(invalid("tab position out of range"));
    }
    // 验证来源/位置后，实际写入前仍要拦截只读范围。
    if cx.store().is_read_only() {
        return Err(invalid(
            "tab ordering is forbidden during read-only rendering",
        ));
    }
    // 只重排当前窗口中的页面，不迁移到另一窗口，也不销毁或重建 Page/Mount；跨窗口迁移由桥接层组合操作。
    if from != position {
        // 先从原位置移除同一引用，再插入最终位置；不分配 Page 副本或改 tabs 字典身份。
        let page = data.pages.remove(from);
        data.pages.insert(position, page);
        cx.replace_payload(window, data)?;
    }
    Ok(())
}
/// 借用一个有效托管窗口的已登记页面集合。
pub fn pages(store: &ObjectStore, window: ObjectRef) -> Result<&[ObjectRef], VmError> {
    // 借用真实 payload 页顺序，调用方不能把返回切片跨 VM 修改保存。
    Ok(&store.payload::<ManagedWindow>(window, "Window")?.pages)
}
/// 取走当前窗口累积的命令，后续由成功发布结果携带到 GUI。
pub fn take_commands(vm: &Vm, window: ObjectRef) -> Result<Vec<Command>, VmError> {
    // 读取 payload 只取得共享 transport outbox；drain 不应制造业务依赖写入。
    let data = vm.payload::<ManagedWindow>(window, "Window")?;
    // 锁内移出本轮全部动作，若毒化则保留错误，不假装没有窗口命令。
    let mut queue = data
        .outbox
        .lock()
        .map_err(|_| invalid("window outbox poisoned"))?;
    // 一次移走全部队列，再按序号排序；仅消费传输状态，不调用 replace_payload 或改变语言依赖版本。
    let mut commands = std::mem::take(&mut *queue);
    commands.sort_by_key(|command| command.sequence);
    Ok(commands)
}
/// 把本模块的类型、方法或能力注册到所属运行时上下文。
pub fn install(
    vm: &mut Vm,
    roots: &mut Vec<ObjectRef>,
    desktop: ObjectRef,
    tabs: ObjectRef,
) -> Result<ObjectRef, VmError> {
    // bootstrap 已建立名义 Window 类型，安装此类型的方法与主窗口实例。
    let definition = desktop_type(vm.object_store(), "Window", desktop)?;
    // 所有原生方法也附本域 Function 类型，使源回调/反射查询识别一致。
    let function_type = desktop_type(vm.object_store(), "Function", desktop)?;
    // 显式列出此适配器提供的方法；close 由桥接资源生命周期入口单独处理。
    for (name, operation) in [
        ("id", Operation::Id),
        ("viewport", Operation::Viewport),
        ("pages", Operation::Pages),
        ("resize", Operation::Resize),
        ("moveTo", Operation::MoveTo),
        ("setTitle", Operation::SetTitle),
        ("focus", Operation::Focus),
    ] {
        use endor_core::{AnnotationType as T, CallEffect, CallSignature};
        // 按操作声明参数、返回和效果，读查询可用于只读协议，资源变更均为 Mutating。
        let (parameters, returns, effect) = match operation {
            Operation::Id => (vec![], T::Number, CallEffect::ReadOnly),
            // pages 返回默认 ObjectList，其成员是同一 VM 的真实 Page。
            Operation::Pages => (
                vec![],
                T::Nominal(desktop_type(vm.object_store(), "ObjectList", desktop)?),
                CallEffect::ReadOnly,
            ),
            // viewport 返回名义 MeasureResult，不能只声明 Any 让错误记录蒙混通过。
            Operation::Viewport => (
                vec![],
                T::Nominal(desktop_type(vm.object_store(), "MeasureResult", desktop)?),
                CallEffect::ReadOnly,
            ),
            // 两数变更返回 Unit，显式标 Mutating 防止只读调用绕过入口检查。
            Operation::Resize | Operation::MoveTo => {
                (vec![T::Number, T::Number], T::Unit, CallEffect::Mutating)
            }
            Operation::SetTitle => (vec![T::String], T::Unit, CallEffect::Mutating),
            Operation::Focus => (vec![], T::Unit, CallEffect::Mutating),
        };
        // 未绑定方法签名先放 Window receiver，再追加显式参数，与 Method.arity 一致。
        let mut arguments = vec![T::Nominal(definition)];
        arguments.extend(parameters);
        // native 捕获桌面类型环境，真正 receiver 仍由调用实参提供，可服务同 VM 的副窗口。
        let function = vm.allocate(ContextNativeFunction::new(
            name,
            Method {
                operation,
                desktop,
                signature: CallSignature::exact(arguments, returns, effect),
            },
            vec![desktop],
        ))?;
        roots.push(function);
        vm.attach_type(function, function_type)?;
        vm.define_method(definition, name, function)?;
    }
    // 安装主窗口托管资源，原生 OS 窗口生命周期仍由 GUI 管理；页面集合初始为空。
    let window = vm.allocate(ManagedWindow {
        id: MAIN_WINDOW,
        desktop,
        closed: false,
        tasks: None,
        tabs,
        pages: Vec::new(),
        sequence: 0,
        outbox: Arc::new(Mutex::new(Vec::new())),
    })?;
    roots.push(window);
    vm.attach_type(window, definition)?;
    vm.set_attr(desktop, "window", Value::Object(window))?;
    // 主 desktop 拥有统一窗口注册表，以纯数字 ID 文本索引；注册表让附加窗口在 VM 图内可达。
    // 主桌面强持有统一窗口字典，副窗口建立后也在这里保持可达。
    let windows = vm.new_dict()?;
    vm.set_attr(desktop, "windows", Value::Object(windows))?;
    vm.dict_set(
        windows,
        Value::Text(MAIN_WINDOW.to_string()),
        Value::Object(window),
    )?;
    vm.release(windows)?;
    Ok(window)
}

/// Create a managed native-window resource. The GUI creates the OS resource only
/// after the owning candidate/input publishes its immutable projection.
/// 建立托管窗口、desktop 与页面容器；原生窗口通过命令发布后出现。
pub fn create(
    cx: &mut NativeContext<'_>,
    master: ObjectRef,
    id: u64,
    definition: ObjectRef,
) -> Result<(ObjectRef, ObjectRef, ObjectRef), VmError> {
    // 源 Window 构造也是资源变更，必须在分配新 desktop/tabs 前阻止只读协议调用。
    if cx.store().is_read_only() {
        return Err(invalid(
            "window creation is forbidden during read-only rendering",
        ));
    }
    // 每窗口独立桌面保存 viewport、mounts、请求等展示状态，业务名义类型仍与主域共享。
    let desktop = cx.new_object()?;
    // 副窗口页面字典从空集合开始，不复制主窗口的登记页面。
    let tabs = cx.new_dict()?;
    // 附加桌面共享主域的同一 types 字典身份，保证跨窗口对象和协议使用同一名义类型体系。
    // 复制的是 Value::Object 身份，不克隆另一份类型体系，跨窗页面/回调仍使用同一名义类型。
    let types = cx.store().get_attr(master, "types")?;
    cx.set_attr(desktop, "types", types)?;
    cx.set_attr(desktop, "viewport", Value::Nil)?;
    cx.set_attr(desktop, "tabs", Value::Object(tabs))?;
    // 建立逻辑资源并附请求 Window 名义类型；此处只安排 VM 内可达图。
    let window = cx.allocate(ManagedWindow {
        id,
        desktop,
        closed: false,
        tasks: None,
        tabs,
        pages: Vec::new(),
        sequence: 0,
        outbox: Arc::new(Mutex::new(Vec::new())),
    })?;
    cx.attach_type(window, definition)?;
    cx.set_attr(desktop, "window", Value::Object(window))?;
    // 统一注册表必须由 master 提供，缺失说明运行时安装不完整，不能私自创建孤立窗口集合。
    let Value::Object(windows) = cx.store().get_attr(master, "windows")? else {
        return Err(invalid("window registry missing"));
    };
    cx.dict_set(windows, Value::Text(id.to_string()), Value::Object(window))?;
    // 返回创建的三个托管身份供桥接层建立 Presentation；此函数不直接申请 OS 资源或发起布局。
    Ok((window, desktop, tabs))
}

/// 取消窗口/页面任务并撤销登记，标记 closed 后安排原生关闭；重复关闭直接返回。
pub fn close(cx: &mut NativeContext<'_>, window: ObjectRef) -> Result<(), VmError> {
    // 关闭会取消任务并撤销 Page 强拥有边，必须先拒绝只读协议中的资源副作用。
    if cx.store().is_read_only() {
        return Err(invalid(
            "window close is forbidden during read-only rendering",
        ));
    }
    // 读取当前页集合做取消/撤销；循环内 payload 会多次更新，后面必须重读。
    let mut data = cx
        .store()
        .payload::<ManagedWindow>(window, "Window")?
        .clone();
    // 重复 close 幂等，不再次取消/撤销或生成重复原生 Close。
    if data.closed {
        return Ok(());
    }
    // 真实关闭边界先取消窗口与所有页面 owner 的任务，再撤销页面登记，防止晚到结果继续更新已关闭资源。
    crate::tasks::cancel_owner(cx, window)?;
    // 遍历旧页顺序副本，unregister_page 可以安全更新真实集合；每页 owner 任务先取消。
    for page in data.pages.clone() {
        crate::tasks::cancel_owner(cx, page)?;
        unregister_page(cx, window, page)?;
    }
    // 循环内 unregister_page 已替换过 Window payload，必须重读最新副本，不能用最初 data 把已移除页面写回。
    data = cx
        .store()
        .payload::<ManagedWindow>(window, "Window")?
        .clone();
    data.closed = true;
    cx.replace_payload(window, data)?;
    // 标记托管 closed 后仍可由内部 enqueue 安排原生 Close；成功输入发布前不会直接关闭系统窗口。
    enqueue(cx, window, Action::Close)
}

/// Host teardown for a stopped VM: no binding, dispatch or source execution.
/// 撤销已失效窗口的托管资源关系，不重新执行源关闭请求。
pub fn retire(vm: &mut Vm, window: ObjectRef) -> Result<(), VmError> {
    // 已停止域的宿主路径只解除托管页面拥有边并标记 closed，任务/OS 清理由外层退役流程负责。
    let mut data = vm.payload::<ManagedWindow>(window, "Window")?.clone();
    // 故障域的宿主退役仅断开页面拥有边并标 closed，不跑用户回调、不重新生成源关闭命令。
    vm.dict_clear(data.tabs)?;
    data.pages.clear();
    data.closed = true;
    vm.replace_payload(window, data)
}