//! 把 Aster 编译/执行与 Tessera 展示生命周期连接起来。Candidate 拥有 VM 与宿主根，ReplSession 保留实际运行中的全局环境。
//! 完整源码 PUT 使用隔离候选；Console 输入则在已有 VM 上执行，先前发生的写入不等于可以回放或事务回滚。
//! 刷新状态机遍历窗口并逐步推进布局/绘制。完成所有必要轮次才形成文档；取消会释放挂起调用并恢复未提交的 Mount。
//!
//! api::worker 为完整 PUT 创建 ReplSession 候选，为 Console/事件/resize 调用已有会话；只有该 worker 拥有 VM。
//! UI 类型与刷新由 bridge 适配；此模块负责源码预算、真实会话、执行结果和挂起刷新的生命周期。
//! compile/evaluate 是一次性入口，关闭 Candidate 后只返回纯数据；生产持久路径使用增量入口并保存续体。
//! 本模块仍直接依赖 UI Frame/桥接，不是已经可以独立搬走的通用 Nexus runtime，迁移需先抽出宿主接口。
//!
//! 增量刷新有两层“继续”：ReplSession 保存全窗口 RefreshWork，bridge 保存当前窗口的布局或绘制续体。
//! API worker 下一量子恢复前者，step_refresh 再选择同一窗口恢复后者；两层都不重放已经执行的 Console/事件副作用。
//! 尺寸目标确实变化才由 retarget_refresh 取消当前视觉续体并重启稳定轮；取消派生几何不会撤销已发生的业务写入。
use anyhow::{Result, bail};
use endor_core::{ExecutionLimits, ObjectRef, Value, Vm, VmError};
use frontend::{
    EndorReader, SourceUnit, Span,
    ast::{AstRoot, Decl, DeclKind, Expr, ExprKind, Spanned, Stmt, StmtKind, visitor::Visitor},
};
use std::collections::BTreeSet;

use crate::{
    document::{CodeNode, RenderDocument},
    endor_script::{self, SourcePlan},
    layout, ui_bridge,
};

/// API、完整加载、Console 与 evaluate 共用的原始输入字节预算；不是字符数或 AST 节点数量。
pub const MAX_SOURCE_BYTES: usize = 1_048_576;
// 每次源执行的硬上限；脚本多片段会分摊指令额度，不能每段重新获得完整额度。
const LIMITS: ExecutionLimits = ExecutionLimits {
    max_frames: 128,
    max_instructions: 1_000_000,
};
// AstBudget 访问者的结构预算，在加载代码前拒绝过大或过深语法树。
const MAX_AST_NODES: usize = 10_000;
const MAX_AST_DEPTH: usize = 64;

/// 一次性编译/现有 API 检查路径调用，在临时 VM 执行并提取文档，不返回持久可响应事件的 ReplSession。
pub fn compile(source: &str, namespace: &str, submission: u64) -> Result<RenderDocument> {
    if source.len() > MAX_SOURCE_BYTES {
        // 先限制输入再进行词法/AST 分配，避免仅靠执行预算保护不了源码解析开销。
        bail!("source exceeds the 1 MiB limit");
    }
    // 把请求来源和提交编号放入诊断 SourceUnit，后续注解错误可显示真实源行列。
    let source = EndorReader::from_text(format!("{namespace} [submission {submission}]"), source);
    // Module/Script 组织由宿主确定，语法解析和位置映射继续委托 endor_script/Aster。
    let plan = endor_script::parse(&source)?;
    // 各 Script 根共享 AST 计数预算，不能通过拆成很多交互片段绕过整份源码节点上限。
    let mut budget = AstBudget::default();
    for ast in plan.roots() {
        // 同一个 budget 累加每段，不因片段边界重置节点/深度检查。
        budget.visit_ast_root(ast)?;
    }
    // 编译得到可加载模板，此时还没有把业务语句在任何 VM 中运行。
    let compiled = compile_plan(&source, &plan)?;
    // 纯数据代码树供 Sources 浏览，和下面实际可执行代码/托管图不是同一结构。
    let root = architecture(&source, &plan, namespace, submission);
    // Candidate 是此一次性域的 VM 与根拥有者，所有出口都在下面 close 收尾。
    let mut candidate = Candidate::new()?;
    // 保存整个执行结果，不能让内部 ? 跳过 Candidate::close。
    let result: Result<RenderDocument> = (|| {
        // 同一程序的所有段共享一个 globals，真实引用由 candidate.roots 持有。
        let globals = candidate.vm.new_dict()?;
        candidate.globals = Some(globals);
        candidate.roots.push(globals);
        // 类型安装在执行前完成，全局别名引用同一批名义对象，不在每片脚本重建 UI 类型。
        let bridge = ui_bridge::install(&mut candidate.vm, &mut candidate.roots)?;
        bridge.install_globals(&mut candidate.vm, globals)?;
        // Script 多段分别执行，指令总额按片段数均分；Module 作为整体获得完整预算，避免每段都重获一百万。
        let limits = match &plan {
            SourcePlan::Module(_) => LIMITS,
            SourcePlan::Script(_) => ExecutionLimits {
                max_instructions: LIMITS.max_instructions / compiled.len().max(1),
                ..LIMITS
            },
        };
        for template in &compiled {
            // 每段加载后有一个代码拥有根，统一登记供候选失败/完成时释放。
            let code = template.load(&mut candidate.vm)?;
            candidate.roots.push(code);
            // 顶层语句返回值此处不作为默认展示根，脚本应显式 render；返回拥有值需立即释放。
            let value = candidate
                .vm
                .execute_with_limits(code, globals, limits)
                .map_err(|error| runtime_error(&candidate.vm, error))?;
            candidate.vm.release_value(value)?;
        }
        bridge.refresh_bindings(&mut candidate.vm)?;
        // 源业务执行后刷新绑定，再依据脚本显式页面或模块 main 返回结果选视觉树。
        let ui_root = match &plan {
            // 脚本没有约定 main 返回值，必须有源 API 安排的页面。
            SourcePlan::Script(_) => bridge
                .rendered(&candidate.vm)?
                .ok_or_else(|| anyhow::anyhow!("script must call ui.page().render(root)"))?,
            // 模块先执行定义再调用 main；若 main 未显式 render，可将其返回值转换成展示根。
            SourcePlan::Module(_) => {
                // 从真实全局字典找 main，不能通过 AST 名字存在就假定运行结果也是 callable。
                let entry = candidate
                    .vm
                    .dict_get(globals, &Value::Text("main".into()))?
                    .ok_or_else(|| {
                        anyhow::anyhow!("declare main or render a page from a top-level script")
                    })?;
                // 对象身份是可调用检查的第一步，VM.call 仍继续验证具体 callable 契约。
                let Value::Object(entry) = entry else {
                    bail!("main must be a callable function");
                };
                // main 返回值有局部拥有根，快照成功/失败都须经过下面 release_value。
                let value = candidate
                    .vm
                    .call_with_limits(entry, &[], LIMITS)
                    .map_err(|error| runtime_error(&candidate.vm, error))?;
                bridge.refresh_bindings(&mut candidate.vm)?;
                // 尊重 main 已主动展示的页面，否则用返回 Block 直接提取兼容快照。
                let snapshot = bridge
                    .rendered(&candidate.vm)
                    .and_then(|rendered| match rendered {
                        Some(root) => Ok(root),
                        None => ui_bridge::snapshot(&candidate.vm, &value),
                    });
                // 提取快照结果先暂存，成功或失败都释放 main 返回值的拥有根，再传播快照错误。
                candidate.vm.release_value(value)?;
                snapshot?
            }
        };
        // 输出文档只持源码/代码树/不可变视觉与几何，没有 ObjectRef 或可执行 VM 指针。
        let document = RenderDocument {
            windows: std::collections::BTreeMap::new(),
            source: source.text().to_owned(),
            root: Some(root),
            frame: layout::frame(&ui_root)?,
            ui_root: Some(ui_root),
        };
        document.validate()?;
        Ok(document)
    })();
    // 独立构建在成功与错误路径都显式释放宿主根/回收堆；返回成功文档也要求 cleanup 成功。
    let cleanup = candidate.close();
    match (result, cleanup) {
        (Ok(document), Ok(())) => Ok(document),
        (Err(error), Ok(())) | (Ok(_), Err(error)) => Err(error),
        (Err(error), Err(cleanup)) => Err(error.context(format!("candidate cleanup: {cleanup}"))),
    }
}

/// api::worker 的 evaluate 请求调用，在一次性无 UI 全局的隔离 VM 求单表达式，返回可显示字符串。
pub fn evaluate(source: &str) -> Result<String> {
    if source.len() > MAX_SOURCE_BYTES {
        bail!("expression exceeds the 1 MiB limit");
    }
    // 独立来源名明确区别于持久 Console transcript，不读取其历史或对象堆。
    let source = EndorReader::from_text("console expression", source);
    // 隔离 evaluate 只接受一个表达式，默认编译选项不安装 ui 桥接，也不读已发布程序的 globals。
    let ast = frontend::parse_source_ast(&source, frontend::ParseMode::Expression)?;
    AstBudget::default().visit_ast_root(&ast)?;
    // 默认全局只有语言内置，不为 evaluate 暗中安装 ui 或活程序用户全局。
    let compiled = compiler::compile_ast(&ast, &source, &compiler::CompileOptions::default())
        .map_err(|error| source.annotate(error))?;
    // 独立候选统一持有执行根，表达式失败也由 close 释放整个域。
    let mut candidate = Candidate::new()?;
    // 暂存执行/格式化错误，保证外层 close 不因这里的 ? 被跳过。
    let result = (|| {
        // 表达式全局环境为空的新字典，不能用运行时 namespace 文档代替真实 globals。
        let globals = candidate.vm.new_dict()?;
        candidate.globals = Some(globals);
        candidate.roots.push(globals);
        // 模板加载到此 VM 后才有真实代码对象，拥有根记入 Candidate。
        let code = compiled.load(&mut candidate.vm)?;
        candidate.roots.push(code);
        // 一次有界执行产生拥有返回值，字符串化后显式释放。
        let value = candidate
            .vm
            .execute_with_limits(code, globals, LIMITS)
            .map_err(|error| runtime_error(&candidate.vm, error))?;
        // 只把标量或对象 repr 字符串交回 API，真实 Value 随一次性 VM 清理，不跨线程交付托管引用。
        let rendered = match &value {
            Value::Nil => "nil".to_owned(),
            Value::Bool(v) => v.to_string(),
            Value::Text(v) => format!("{v:?}"),
            Value::Number(v) => v.to_string(),
            Value::Object(v) => candidate.vm.repr(*v)?,
        };
        candidate.vm.release_value(value)?;
        Ok(rendered)
    })();
    // 先尝试关闭候选，再合并执行和清理结果，不能只因表达式已有字符串结果就跳过清理。
    let cleanup = candidate.close();
    match (result, cleanup) {
        (Ok(value), Ok(())) => Ok(value),
        (Err(e), _) | (_, Err(e)) => Err(e),
    }
}

/// compile/prepare_program 调用，建立 UI 宿主全局名集合，再复用增量编译助手生成模板序列。
fn compile_plan(source: &SourceUnit, plan: &SourcePlan) -> Result<Vec<compiler::CompiledCode>> {
    compile_plan_with_globals(
        source,
        plan,
        std::iter::once("ui")
            .chain(ui_bridge::TYPE_NAMES.iter().copied())
            .chain(ui_bridge::QUERY_NAMES.iter().copied())
            .map(str::to_owned)
            .collect(),
    )
}

/// compile_plan 与 execute_mode 调用，按源序编译 Script 各段，同时支持完整模块和声明前向引用。
fn compile_plan_with_globals(
    source: &SourceUnit,
    plan: &SourcePlan,
    mut globals: BTreeSet<String>,
) -> Result<Vec<compiler::CompiledCode>> {
    // 先收集全部函数/类声明名以支持前向引用；普通绑定仍按源码执行次序逐段加入已知全局名。
    for root in plan.roots() {
        if let AstRoot::Interactive(input) = root {
            // 完整模块的声明可见性由 Aster 自己处理；只有拆成多个交互根时宿主需预收集声明名。
            for statement in &input.statements {
                if let StmtKind::Declaration(decl) = &statement.kind {
                    // 只预声明函数/类，不提前把任意赋值名当作已存在业务值。
                    let name = match &decl.kind {
                        DeclKind::Function(function) => &function.name,
                        DeclKind::Class(class) => &class.name,
                    };
                    globals.insert(name.text.clone());
                }
            }
        }
    }
    // 每个根保留一个模板，执行顺序必须与原根切片一一对应，不能按名字排序。
    let mut compiled = Vec::with_capacity(plan.roots().len());
    /// 本函数在每段成功编译后调用，递归收集后续段可能引用的绑定名，不执行或预测条件真值。
    fn assigned(statement: &Stmt, globals: &mut BTreeSet<String>) {
        match &statement.kind {
            StmtKind::Binding(b) => {
                // 绑定给后续片段的静态名称解析提供名字；字典中的真实值仍在执行时建立。
                globals.insert(b.name.text.clone());
            }
            StmtKind::Assignment(a) => {
                // 顶层赋值也可能引入名字，按 Aster 交互语义让后续段可以编译引用。
                globals.insert(a.name.text.clone());
            }
            StmtKind::If(b) => {
                // 两个分支都收集“可能声明”名字，不在编译阶段决定哪条路径会执行。
                for s in &b.body.statements {
                    assigned(s, globals);
                }
                if let Some(other) = &b.otherwise {
                    // else 中的潜在绑定也要让后续片段可编译引用，但这里不预先在 globals 字典创建实际值。
                    for s in &other.statements {
                        assigned(s, globals);
                    }
                }
            }
            StmtKind::While(b) => {
                // 循环体可能写入全局；是否真正执行一次由 VM 决定，宿主不展开循环。
                for s in &b.body.statements {
                    assigned(s, globals);
                }
            }
            // 表达式、return、成员赋值等不引入新的普通全局名；函数内部作用域由语言编译器处理。
            _ => {}
        }
    }
    for root in plan.roots() {
        // 每段得到当前已知全局集合快照，先编译再把本段绑定加入下一段上下文。
        let options = compiler::CompileOptions {
            globals: globals.iter().cloned().collect(),
        };
        compiled.push(
            compiler::compile_ast(root, source, &options)
                .map_err(|error| source.annotate(error))?,
        );
        // 每段编译成功才把绑定/赋值名字加入下一段编译上下文，语法与代码生成都继续委托 Aster。
        if let AstRoot::Interactive(input) = root {
            for statement in &input.statements {
                assigned(statement, &mut globals);
            }
        }
    }
    Ok(compiled)
}

/// refresh_step 挂起 paint 时创建、下一轮恢复/取消时消费，文档草稿与所属窗口续体必须成对保留。
struct PendingPaint {
    // 原窗口 ID，恢复/取消前显式 select_window，不能依赖稍后变化的 current。
    window: u64,
    // 对应本次完成布局的源码/视觉/几何草稿，paint 结束前不得对外发布。
    document: RenderDocument,
    // owning VM 中未完成的 source_paint Work，取消时显式关闭，Rust drop 本身不替代 VM 清理。
    work: Box<crate::source_paint::Work>,
}

/// 跨 worker 轮次的全窗口刷新状态，保存已完成草稿和当前布局/绘制，直到稳定再发布。
struct RefreshWork {
    // 已完成窗口的草稿先留在本轮；所有窗口收敛后才合成一次完整发布。
    // RefreshWork 先克隆最近完整文档作为草稿基线，各窗口更新暂存于此；全轮稳定前不写共享 NamespaceState。
    documents: std::collections::BTreeMap<u64, RenderDocument>,
    // 当前稳定性遍历轮剩余窗口，按 bridge 的退旧优先次序排队。
    windows: std::collections::VecDeque<u64>,
    // 本片正在推进窗口，pending/paint 的上下文必须与其一致。
    current: Option<u64>,
    // 当前帧不可变根草稿，布局完成再绘制仍使用这一轮同一份快照。
    root: Option<std::sync::Arc<crate::ui_bridge::UiNode>>,
    // 续体必须保留其 owning VM；取消时显式关闭，不能靠丢弃 Rust 值。
    pending: Option<Box<crate::ui_bridge::PendingLayout>>,
    // 与 pending 布局阶段互斥的未完成绘制，完成后才把当前窗口文档写进 documents。
    paint: Option<Box<PendingPaint>>,
    // pass_changed 要求再跑一轮确认稳定，changed 记录整次刷新是否有可发布变化。
    pass_start: bool,
    // 一轮是否有变化，决定下一轮还需确认稳定；不等于最终对外是否已有变化。
    pass_changed: bool,
    // 整次刷新累计变化，用于稳定后决定返回文档还是 None。
    changed: bool,
    // 整次刷新工作量预算，跨多个 worker 量子累计，不能让每片各得一份完整收敛额度。
    work: usize,
    // 记录本轮尺寸目标，下一次 worker 轮次据此判断是否需要重定向。
    viewports: Option<std::collections::BTreeMap<u64, crate::layout::Size>>,
}

/// 刷新仍在进行或已完成；完成也可能没有新文档需要发布。
enum RefreshProgress {
    // worker 保留整个 ReplSession，下次继续已有布局/绘制续体，不接新业务写入。
    Pending,
    // 已稳定；None 为没有新文档，Some 才有可以让 worker 校验/发布的完整值。
    Complete(Option<Box<RenderDocument>>),
}

/// 持久源运行时与其桥接会话，保存实际全局对象、代码投影、全窗口文档和挂起刷新。
pub struct ReplSession {
    // 真正 VM、全局拥有根和清理状态，和 HTTP/UI 读取的文档快照分离。
    candidate: Candidate,
    // 同 VM 的 Tessera 扩展能力，实际窗口/布局/绘制规则留在 bridge/model/render。
    bridge: ui_bridge::UiBridge,
    // worker 分配的运行时代际 ID，输入即使数值窗口/Mount 相同也不能跨代沿用。
    pub id: u64,
    // 已接受 Console 输入数量与累计 AST 节点数，完整源加载和后续输入都受各自预算控制。
    inputs: usize,
    ast_nodes: usize,
    // 完整程序或累加后的 Console transcript，供发布和 Sources 使用，不通过回放恢复执行状态。
    source: String,
    // 交互记录的纯数据代码树，与 Candidate 的真实 globals/函数引用不是同一存储。
    nodes: Vec<CodeNode>,
    // 回调/渲染失败后置位，拒绝继续普通业务输入；保留画面不表示堆还能安全执行。
    faulted: bool,
    // 完整程序的 Sources 根，首次 Console 追加时移入 nodes 保留原程序浏览记录。
    program_root: Option<CodeNode>,
    // 最近完成的逐窗基线文档；未稳定刷新只改 RefreshWork 草稿，不提前替换共享发布状态。
    documents: std::collections::BTreeMap<u64, RenderDocument>,
    // 同一个 VM 上至多一份跨片刷新，所有业务写入口先 require_idle_refresh。
    refresh: Option<RefreshWork>,
}
/// 一次 Console/事件操作的标量显示结果与可选完整文档，避免直接跨线程暴露托管返回值。
pub struct ReplResult {
    // 用于 Console/API 的字符串结果，不跨线程暴露拥有根 Value。
    pub value: String,
    // 只有本轮已经稳定完成刷新才返回完整文档，挂起或无变化时为 None。
    pub document: Option<RenderDocument>,
    // 当前 globals 条目数的显示统计，具体计算按 execute_mode 的接口约定处理。
    pub bindings: usize,
    // 已接受输入编号，供 API/Console 对应 transcript 与代码树记录。
    pub input: usize,
}
impl ReplSession {
    /// Compile once into an isolated candidate, then keep its actual heap and
    /// callback environments alive after the first successful publication.
    #[cfg(test)]
    /// 测试用同步装载入口：建立完整候选并排空初始刷新，返回真实运行时与完成文档。
    pub fn load(
        source: &str,
        namespace: &str,
        submission: u64,
        id: u64,
    ) -> Result<(Self, RenderDocument)> {
        Self::load_with_viewport(source, namespace, submission, id, None)
    }

    #[cfg(test)]
    /// 测试用同步装载入口：建立完整候选并排空初始刷新，返回真实运行时与完成文档。
    pub fn load_with_viewport(
        source: &str,
        namespace: &str,
        submission: u64,
        id: u64,
        viewport: Option<crate::layout::Size>,
    ) -> Result<(Self, RenderDocument)> {
        // 测试只接受主窗口尺寸，先建立真实 VM，再同步排空初始刷新便于直接断言帧内容。
        let mut runtime = Self::prepare_program(source, namespace, submission, id, viewport)?;
        // 成功执行但没发布页面不算完整 GUI 程序，避免返回一个表面“成功”的空候选。
        let document = runtime
            .refresh_document()?
            .ok_or_else(|| anyhow::anyhow!("program did not publish a Page"))?;
        runtime
            .bridge
            .reclaim(&mut runtime.candidate.vm, &mut runtime.candidate.roots)?;
        Ok((runtime, document))
    }

    /// api::worker 的 PUT 完整源码路径调用，建立候选并只推进有限刷新，未稳定时保留 runtime 等后续量子。
    pub fn load_incremental(
        source: &str,
        namespace: &str,
        submission: u64,
        id: u64,
        viewport: Option<crate::layout::Size>,
    ) -> Result<(Self, Option<RenderDocument>)> {
        // 源程序执行在隔离 Candidate，旧活跃程序和 GUI 发布文档尚未替换。
        let mut runtime = Self::prepare_program(source, namespace, submission, id, viewport)?;
        // 首轮只提供主窗口已知尺寸，源程序新建的其他窗口由后续 resize 通知补充。
        let viewports = viewport
            .map(|size| (crate::window::MAIN_WINDOW, size))
            .into_iter()
            .collect();
        // Option 文档为 None 既可能挂起也可能无变化，必须再看 has_pending_refresh 区分。
        let document = runtime.refresh_after_mutation(Some(&viewports))?;
        // 初始刷新若已完成必须确实有 Page 文档才可接受候选；仍挂起则把整个运行时交 worker 下一量子继续。
        if !runtime.has_pending_refresh() {
            anyhow::ensure!(document.is_some(), "program did not publish a Page");
            runtime
                .bridge
                .reclaim(&mut runtime.candidate.vm, &mut runtime.candidate.roots)?;
        }
        Ok((runtime, document))
    }

    /// load/load_incremental 的共同准备入口，在新 VM 执行完整源码，验证已安排页面；布局/发布留给外层。
    fn prepare_program(
        source: &str,
        namespace: &str,
        submission: u64,
        id: u64,
        viewport: Option<crate::layout::Size>,
    ) -> Result<Self> {
        if source.len() > MAX_SOURCE_BYTES {
            // 完整 PUT 候选在创建 VM 前限制原始 UTF-8 字节数，解析/代码生成尚未开始。
            bail!("source exceeds the 1 MiB limit");
        }
        // 来源标注把 API namespace/提交号接入 Aster 错误来源，不改变用户原文。
        let unit = EndorReader::from_text(format!("{namespace} [submission {submission}]"), source);
        // 按 Module/Script 路径编译，脚本片段仍共享同一个 globals。
        let plan = endor_script::parse(&unit)?;
        // 一份输入的所有根累计使用同一结构预算，过大 AST 在业务执行前失败。
        let mut budget = AstBudget::default();
        for ast in plan.roots() {
            budget.visit_ast_root(ast)?;
        }
        // 全部编译成功后才创建并执行新运行时，解析/编译失败不改变任何活程序对象。
        let compiled = compile_plan(&unit, &plan)?;
        // new 安装类型和 globals，但不主动打开页面；源程序决定要展示的内容。
        let mut runtime = Self::new(id)?;
        runtime
            .bridge
            .set_viewport(&mut runtime.candidate.vm, viewport)?;
        // 完整程序代码在候选自己的真实 globals 中执行，之后保留该堆用于事件与 Console，不通过重放历史恢复状态。
        let globals = runtime.candidate.globals.expect("program globals");
        // 根据已编译根数确定脚本每段硬额度；完整模块仍使用一份 LIMITS 执行模块定义。
        let limits = if matches!(plan, SourcePlan::Script(_)) {
            // 指令硬额度在脚本段间均分，不因一个输入拆成更多交互段而放大执行总量。
            ExecutionLimits {
                max_instructions: LIMITS.max_instructions / compiled.len().max(1),
                ..LIMITS
            }
        } else {
            // 模块作为一个编译单元执行定义，之后 main 有单独一次有界调用。
            LIMITS
        };
        for template in &compiled {
            // 代码只需此段执行期间持有，执行结果暂存，代码根释放后再传播调用错误。
            let code = template.load(&mut runtime.candidate.vm)?;
            // 保存 Result 以保证失败执行也经过 vm.release(code)。
            let result = runtime
                .candidate
                .vm
                .execute_with_limits(code, globals, limits)
                .map_err(|error| runtime_error(&runtime.candidate.vm, error));
            runtime.candidate.vm.release(code)?;
            runtime.candidate.vm.release_value(result?)?;
        }
        if matches!(plan, SourcePlan::Module(_)) {
            // 模块顶层只安装定义，main 从实际 globals 查找，而非只依据 AST 声明列表。
            let main = runtime
                .candidate
                .vm
                .dict_get(globals, &Value::Text("main".into()))?
                .ok_or_else(|| anyhow::anyhow!("declare a main function"))?;
            // 同名全局可能被赋为标量，先解码对象，再由 VM 完整检查可调用契约。
            let Value::Object(main) = main else {
                bail!("main must be callable");
            };
            // 返回值保留到 has_page/open_value 决策之后；无论打开成功与否都须显式释放。
            let value = runtime
                .candidate
                .vm
                .call_with_limits(main, &[], LIMITS)
                .map_err(|error| runtime_error(&runtime.candidate.vm, error))?;
            // main 已主动打开 Page 时尊重其选择；否则把返回值经展示协议打开，不能重复创建第二个默认页面。
            let opened = if runtime.bridge.has_page()? {
                Ok(())
            } else {
                // 返回对象按 Presentable/普通值规则进入桥接，不要求所有模块都手写 page.render。
                runtime.bridge.open_value(&mut runtime.candidate.vm, &value)
            };
            runtime.candidate.vm.release_value(value)?;
            opened?;
        }
        if !runtime.bridge.has_page()? {
            // UI 程序必须有实际安排页面，单独计算出一个未打开 Block 不算可发布程序。
            bail!("script must call page.render(root) or ui.open(value)");
        }
        runtime.source = source.into();
        runtime.ast_nodes = budget.nodes;
        // 保存完整程序的 Sources 投影，后续 Console 追加时可移入交互记录树；不把 AST 投影当可执行堆对象。
        runtime.program_root = Some(architecture(&unit, &plan, namespace, submission));
        Ok(runtime)
    }

    /// api::worker 新建 Console 域时调用，在未打开页面的空会话中记录原生主窗口尺寸。
    pub fn new_with_viewport(id: u64, viewport: Option<crate::layout::Size>) -> Result<Self> {
        // 新 Console 不回放旧源码，不复制先前程序的可变对象堆；显示的旧文档仍由 worker 决策保留。
        let mut runtime = Self::new(id)?;
        runtime
            .bridge
            .set_viewport(&mut runtime.candidate.vm, viewport)?;
        Ok(runtime)
    }

    /// prepare_program/new_with_viewport 调用，分配持久 Candidate、globals 和 UiBridge，不执行用户代码。
    pub fn new(id: u64) -> Result<Self> {
        // Candidate 的 Drop 负责异常返回时的最终清理，不让 bootstrap 半途失败泄漏 VM 根。
        let mut candidate = Candidate::new()?;
        // globals 的拥有根留在 Candidate，实际用户绑定在以后输入中原地更新这个字典。
        let globals = candidate.vm.new_dict()?;
        candidate.globals = Some(globals);
        candidate.roots.push(globals);
        // 每个会话安装一份类型域，后续输入继续复用，不按 Console 行重复建立名义类型。
        let bridge = ui_bridge::install(&mut candidate.vm, &mut candidate.roots)?;
        bridge.install_globals(&mut candidate.vm, globals)?;
        Ok(Self {
            candidate,
            bridge,
            id,
            inputs: 0,
            ast_nodes: 0,
            source: String::new(),
            nodes: Vec::new(),
            faulted: false,
            program_root: None,
            documents: std::collections::BTreeMap::new(),
            refresh: None,
        })
    }
    #[cfg(test)]
    /// 同步执行一个 Console 输入并排空刷新，返回标量结果及可选新文档。
    pub fn execute(&mut self, source: &str, namespace: &str) -> Result<ReplResult> {
        self.execute_mode(source, namespace, None)
    }

    /// api::worker 的 Console 输入请求调用，执行真实 globals 上的语句，展示部分允许跨片挂起。
    pub fn execute_incremental(
        &mut self,
        source: &str,
        namespace: &str,
        viewports: &std::collections::BTreeMap<u64, crate::layout::Size>,
    ) -> Result<ReplResult> {
        self.execute_mode(source, namespace, Some(viewports))
    }

    /// execute/execute_incremental 共用入口，先完整编译再执行；解析错误不写业务堆，运行错误不回滚此前成功语句。
    fn execute_mode(
        &mut self,
        source: &str,
        namespace: &str,
        viewports: Option<&std::collections::BTreeMap<u64, crate::layout::Size>>,
    ) -> Result<ReplResult> {
        self.require_idle_refresh()?;
        if self.faulted {
            // 故障后保留可见画面不代表 VM 安全可继续变更，必须重置会话或替换完整程序。
            bail!(
                "runtime stopped after a callback or rendering failure; reset the session or replace its program"
            );
        }
        if source.len() > MAX_SOURCE_BYTES {
            // 单次 Console 输入也受原始字节预算约束，不能仅靠下面累计 transcript 预算替代。
            bail!("input exceeds 1 MiB");
        }
        // 持久 Console 限制累计输入次数、源码文本和稍后的 AST 总节点数，用户需显式重置才能重新获得预算。
        if self.inputs >= 256 || self.source.len() + source.len() + 80 > MAX_SOURCE_BYTES {
            bail!("console session exceeds 256 inputs or 1 MiB; reset the session to continue");
        }
        // 对每次输入保留会话号/输入号作为来源，累计 transcript 的行号稍后再为 Sources 投影偏移。
        let source = EndorReader::from_text(
            format!("console session {} input {}", self.id, self.inputs + 1),
            source,
        );
        // 输入可以是一段或多段交互语句，语法仍由 Aster 的 parser 决定。
        let plan = endor_script::parse(&source)?;
        // 新输入的结构量先算出，再与会话累计量合并，不为每次输入重新放宽全会话上限。
        let mut budget = AstBudget::default();
        for ast in plan.roots() {
            budget.visit_ast_root(ast)?;
        }
        if self.ast_nodes + budget.nodes > MAX_AST_NODES {
            // 此处限制整个持久会话累计结构量；超限发生在记输入号、追加源码和执行用户语句之前。
            bail!("console session exceeds 10000 AST nodes; reset the session to continue");
        }
        // new 已建立的字典继续原地使用，保存对象身份和闭包，不能通过历史源码重放重建它。
        let globals = self.candidate.globals.expect("live console globals");
        // 从实际 globals 枚举已有名称供增量编译，支持前次输入创建的真实对象，而非靠解析历史猜名称。
        let names = self
            .candidate
            .vm
            .dict_items(globals)?
            .iter()
            .filter_map(|(key, _)| {
                // 只把字符串键变成静态编译全局名，不向编译器传 VM Value 或托管引用。
                if let Value::Text(name) = key {
                    Some(name.clone())
                } else {
                    None
                }
            })
            .collect();
        // 所有根先编译完，任何语法/类型编译错误都不会执行输入前半部分。
        let compiled = compile_plan_with_globals(&source, &plan, names)?;
        self.bridge.discard_pending(&mut self.candidate.vm)?;
        self.bridge
            .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)?;
        // 解析/编译全部成功后才记本轮输入与源码；之后运行失败仍可能保留此前语句副作用，不做事务回滚。
        self.inputs += 1;
        self.ast_nodes += budget.nodes;
        if let Some(root) = self.program_root.take() {
            // 第一次 Console 输入把原完整程序浏览树移入 transcript 节点，不丢原程序的 Sources 内容。
            self.nodes.push(root);
        }
        if !self.source.is_empty() && !self.source.ends_with('\n') {
            // 分隔行不改变 VM 代码语义，只保证后续 Sources 行号和注释不粘到上一行末尾。
            self.source.push('\n');
        }
        // 交互源码前加 Console input 注释分隔，投影节点行号再整体平移到累计 transcript 中。
        let offset = line_starts(&self.source).len();
        self.source
            .push_str(&format!("// Console input {}\n", self.inputs));
        self.source.push_str(source.text());
        if !self.source.ends_with('\n') {
            // transcript 的尾部补换行只服务下一条输入的浏览行号，当前执行仍使用独立 SourceUnit 原文。
            self.source.push('\n');
        }
        // 本轮输入的代码树先使用局部行号，再用 offset 平移到累计源码中的对应位置。
        let mut node = architecture(
            &source,
            &plan,
            &format!("{namespace}:console-{}", self.id),
            self.inputs as u64,
        );
        node.name = format!("Input {}", self.inputs);
        shift_node_lines(&mut node, offset);
        self.nodes.push(node);
        // 保存执行/刷新失败供下面丢弃未发布请求并给 Sources 标注，已完成赋值不做事务回滚。
        let result: Result<ReplResult> = (|| {
            // 多根均分本次硬预算，不让后续片段每个都获得完整一百万条指令。
            let limits = ExecutionLimits {
                max_instructions: LIMITS.max_instructions / compiled.len().max(1),
                ..LIMITS
            };
            // 依次覆盖为最后一个片段的可显示值；本局部只保存字符串，不延长任意返回对象寿命。
            let mut rendered_value = "nil".to_owned();
            for (ast, template) in plan.roots().iter().zip(&compiled) {
                // 代码根只跨一次 execute，先暂存 Result 再 release(code)，失败也有清理。
                let code = template.load(&mut self.candidate.vm)?;
                // VM 执行真实 globals，不把本轮 AST 当快照去覆盖旧业务状态。
                let executed = self
                    .candidate
                    .vm
                    .execute_with_limits(code, globals, limits)
                    .map_err(|error| runtime_error(&self.candidate.vm, error));
                self.candidate.vm.release(code)?;
                // execute 返回拥有根，后面 repr/全局 _ 更新是否成功都必须释放这份根。
                let value = executed?;
                // 绑定/赋值语句展示其新变量实际值，普通表达式展示返回值；不是仅显示该语句执行的 Unit。
                let display = if let AstRoot::Interactive(input) = ast {
                    match &input.statements[0].kind {
                        StmtKind::Binding(binding) => self
                            .candidate
                            .vm
                            .dict_get(globals, &Value::Text(binding.name.text.clone()))?
                            .unwrap_or_else(|| value.clone()),
                        StmtKind::Assignment(assignment) => self
                            .candidate
                            .vm
                            .dict_get(globals, &Value::Text(assignment.name.text.clone()))?
                            .unwrap_or_else(|| value.clone()),
                        _ => value.clone(),
                    }
                } else {
                    value.clone()
                };
                // 先算 repr 并把实际最后值写入全局 _，保留未命名 UI 对象；随后释放 execute 返回根，错误也逐项传播。
                let repr = value_repr(&self.candidate.vm, &display);
                // _ 的字典强边独立保留最后值，避免匿名 Block 在 Console 显示后马上丢失身份。
                let retained =
                    self.candidate
                        .vm
                        .dict_set(globals, Value::Text("_".into()), display);
                self.candidate.vm.release_value(value)?;
                retained?;
                rendered_value = repr?;
            }
            // 有业务变更后才推进 UI 稳定循环，可能返回挂起时的 None，worker 继续保留该会话。
            let document = self.refresh_after_mutation(viewports)?;
            Ok(ReplResult {
                value: rendered_value,
                document,
                bindings: self
                    .candidate
                    .vm
                    .dict_items(globals)?
                    .len()
                    .saturating_sub(1),
                input: self.inputs,
            })
        })();
        // 失败丢弃未发布展示请求和原生命令，保留已执行业务写入，并在代码投影上明确标记非事务语义。
        if result.is_err() {
            // 只丢待发布展示与原生命令，不假装撤销此前已完成的用户赋值或资源关闭。
            self.take_window_commands()?;
            self.bridge.discard_pending(&mut self.candidate.vm)?;
            if let Some(node) = self.nodes.last_mut() {
                // 标记本次已记录的输入节点，保留先前 Sources 记录，不把运行失败误记为从未执行。
                node.name
                    .push_str(" (error; earlier statements may remain live)");
            }
        }
        // 未完成只读续体仍持有临时结果，不在中途执行完整 reclaim；等刷新结束后再回收不可达宿主根。
        if !self.has_pending_refresh() {
            self.bridge
                .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)?;
        }
        result
    }

    /// api::worker 选择空闲等待策略时查询，区分可运行协程与仅等待定时/I/O 的任务，不执行用户代码。
    pub fn has_cooperative_tasks(&self) -> bool {
        self.bridge.has_cooperative_tasks()
    }

    /// worker 和本模块写入口查询，刷新未结束时必须继续原续体，不能插入 Console/任务回调写入。
    pub fn has_pending_refresh(&self) -> bool {
        self.refresh.is_some()
    }

    /// execute/dispatch/命令提取等入口的共同前置检查，禁止在原只读视觉调用未结束时重入变更。
    fn require_idle_refresh(&self) -> Result<()> {
        anyhow::ensure!(
            !self.has_pending_refresh(),
            "finish pending refresh before mutating this runtime"
        );
        Ok(())
    }

    /// prepare_program 后的加载、Console/事件/任务回调后调用，按调用模式同步排空或只推进一个刷新步骤。
    fn refresh_after_mutation(
        &mut self,
        viewports: Option<&std::collections::BTreeMap<u64, crate::layout::Size>>,
    ) -> Result<Option<RenderDocument>> {
        // 无增量视口参数的测试/同步入口排空状态机；worker 提供目标视口时只推进一次并记录重定向依据。
        let Some(viewports) = viewports else {
            return self.refresh_document();
        };
        // 传入视口表示 worker 增量模式，只前进一步；目标尺寸副本保存供后续重定向比较。
        let progress = self.poll_refresh(true)?;
        if let Some(work) = &mut self.refresh {
            work.viewports = Some(viewports.clone());
        }
        Ok(match progress {
            RefreshProgress::Pending => None,
            RefreshProgress::Complete(document) => document.map(|document| *document),
        })
    }

    /// 测试同步入口与 drain=true resize 调用，循环推进同一刷新直到稳定，不重执行用户业务语句。
    fn refresh_document(&mut self) -> Result<Option<RenderDocument>> {
        loop {
            match self.poll_refresh(false)? {
                // Pending 仍是活动 Work，只让出 OS 调度机会，不重建 VM 或重新开始源布局。
                RefreshProgress::Pending => std::thread::yield_now(),
                RefreshProgress::Complete(document) => {
                    return Ok(document.map(|document| *document));
                }
            }
        }
    }

    /// refresh_after_mutation/advance_idle_refresh/同步循环共用，消费或保存 RefreshWork 并统一处理故障清理。
    fn poll_refresh(&mut self, record_yield: bool) -> Result<RefreshProgress> {
        // 从 self 取出工作以便可变推进，挂起时放回；首次从已发布各窗口文档克隆初始草稿。
        let mut work = self.refresh.take().unwrap_or_else(|| RefreshWork {
            documents: self.documents.clone(),
            windows: Default::default(),
            current: None,
            root: None,
            pending: None,
            paint: None,
            pass_start: true,
            pass_changed: false,
            changed: false,
            work: 0,
            viewports: None,
        });
        // 暂存 step 错误以便仍能显式取消 Work 内的续体；不能在这里直接 ? 丢掉 work。
        let result = (|| {
            if self.step_refresh(&mut work)? {
                return Ok(true);
            }
            if record_yield {
                // 只记录真正把控制权交回 worker 的增量步，同步排空循环不累计这种诊断次数。
                self.bridge.note_refresh_yield()?;
            }
            Ok(false)
        })();
        match result {
            Ok(false) => {
                // 原样保存根/检查点/窗口队列和续体，下次 poll_refresh 从同一拥有域恢复。
                self.refresh = Some(work);
                Ok(RefreshProgress::Pending)
            }
            // 收敛后统一组合文档，再恢复主窗口选择；收尾失败也标故障，不把失败草稿当已发布帧。
            Ok(true) => {
                // finish_refresh 验证整份多窗口文档后才更新本会话完成基线，仍由 worker 决定共享发布。
                let result = self.finish_refresh(work);
                self.bridge.select_window(crate::window::MAIN_WINDOW)?;
                if result.is_err() {
                    self.faulted = true;
                }
                result.map(|document| RefreshProgress::Complete(document.map(Box::new)))
            }
            Err(error) => {
                self.faulted = true;
                // 错误时必须显式取消 paint/layout 的 owning VM 续体并恢复检查点，不能仅丢弃 Rust 工作结构。
                // 这里是失败收尾，取消已有 paint 并丢弃配对草稿；只有正常下一量子的 step_refresh 才会恢复 paint。
                if let Some(paint) = work.paint.take() {
                    self.bridge.cancel_paint_frame(
                        &mut self.candidate.vm,
                        paint.window,
                        *paint.work,
                    )?;
                }
                if let Some(pending) = work.pending.take() {
                    // 若失败发生在布局阶段，取消这份原窗口检查点配套的 Work；不会恢复执行源语句或发布其草稿。
                    self.bridge
                        .abort_layout_frame(&mut self.candidate.vm, *pending)?;
                }
                self.bridge.select_window(crate::window::MAIN_WINDOW)?;
                Err(error)
            }
        }
    }

    /// poll_refresh 每量子调用一次，推进稳定循环、一个窗口或一片布局/绘制；true 只表示全轮无新增变化。
    fn step_refresh(&mut self, work: &mut RefreshWork) -> Result<bool> {
        // 阶段一：新一轮先刷新绑定，再取得稳定窗口遍历顺序。
        // 每轮先使属性绑定达到固定点，再取窗口顺序；绑定结果应用与生命周期写入可能令依赖再次失效，因此需要多轮确认。
        if work.pass_start {
            // 生命周期可能改窗口登记，绑定结果可能改视觉属性；新的稳定轮必须重新刷新绑定并获取窗口顺序。
            self.bridge.refresh_bindings(&mut self.candidate.vm)?;
            work.windows = self.bridge.window_ids()?.into();
            work.current = None;
            work.pass_changed = false;
            work.pass_start = false;
            return Ok(false);
        }
        // 阶段二：逐个选择窗口；一轮发生变化时再扫描一轮，直到依赖不再引起新帧。
        let Some(id) = work.current else {
            // 没有当前窗口时先取队列下一项，本次只做状态推进，下次才进入其 VM 布局/绘制。
            if let Some(id) = work.windows.pop_front() {
                work.current = Some(id);
                return Ok(false);
            }
            // 任何窗口本轮生成新帧，就再扫描一轮检查依赖和挂载回调是否又引起变化，直到整轮无变化。
            if work.pass_changed {
                // 有帧变化就再完整扫一轮，才能发现 hooks/依赖引起的二次变化；不能第一轮结束就发布。
                work.pass_start = true;
                return Ok(false);
            }
            return Ok(true);
        };
        self.bridge.select_window(id)?;
        // 已进入 paint 的窗口直接恢复原绘制续体，不重放业务回调或布局。
        if let Some(paint) = work.paint.take() {
            // 取回配对文档与源 paint Work，不重新 measure/arrange，也不把原业务输入再执行一遍。
            let PendingPaint {
                window,
                document,
                work: paint_work,
            } = *paint;
            // 同一 owning VM 上恢复固定预算的一片绘制，Complete/Pending 由共同接收器处理。
            let progress = self
                .bridge
                .resume_paint_frame(&mut self.candidate.vm, *paint_work)?;
            return Self::accept_window_paint(work, window, document, progress);
        }
        // 阶段三：恢复旧布局，或在快照/依赖确实变化时建立新布局。
        let progress = if let Some(pending) = work.pending.take() {
            // 原布局仍挂起时恢复，不能重新提取另一份根让当前续体读写不同展示上下文。
            self.bridge
                .resume_layout_frame(&mut self.candidate.vm, *pending)?
        } else if let Some(root) = self.bridge.prepare_frame(&mut self.candidate.vm)? {
            // 双层 Option 内层 None 也代表有空帧工作；保存准确根供布局完成后 paint 复用。
            work.root = root.clone();
            self.bridge
                .begin_layout_frame(&mut self.candidate.vm, root)?
        } else {
            // 没有任何本窗变化才切下一窗，不能把“需发布空帧”误归为这一无工作分支。
            work.current = None;
            return Ok(false);
        };
        // 未完成布局没有可用完整几何，必须保留 Work；Complete 才可以组装后续待绘制文档。
        let frame = match progress {
            crate::ui_bridge::LayoutProgress::Pending(pending) => {
                // current 和 root 保留不动，下次量子仍为此窗口续体继续执行。
                work.pending = Some(pending);
                return Ok(false);
            }
            crate::ui_bridge::LayoutProgress::Complete(frame) => *frame,
        };
        // 阶段四：几何完成后建立候选文档，再运行 paint；这里尚未向 GUI 发布。
        let mut document = RenderDocument {
            windows: Default::default(),
            source: self.source.clone(),
            root: Some(self.program_root.clone().unwrap_or_else(|| CodeNode {
                id: format!("console-session-{}", self.id),
                name: format!("Console session {}", self.id),
                kind: "repl-session".into(),
                start_line: 1,
                end_line: self.source.lines().count(),
                children: self.nodes.clone(),
            })),
            frame,
            ui_root: work.root.take(),
        };
        document.frame.session = self.id;
        document.validate()?;
        // 跨所有窗口和稳定轮次累计布局工作，空帧也计一，防止持续无几何变化请求绕过收敛预算。
        work.work += document.frame.mounts.len().max(1);
        if work.work > 200_000 {
            // 即使每次单帧都有限，失效反馈也可能永不收敛，这个累计预算禁止无限循环刷新。
            bail!("layout dependencies did not stabilize within the rendering work budget");
        }
        // Frame 转移给 source_paint，document 暂留其他元数据；PendingPaint 会把两者重新配对保存。
        let progress = self.bridge.begin_paint_frame(
            &mut self.candidate.vm,
            document.ui_root.clone(),
            std::mem::take(&mut document.frame),
        )?;
        Self::accept_window_paint(work, id, document, progress)
    }

    /// step_refresh 启动/恢复 paint 后调用，挂起就保留配对状态，完成就写逐窗草稿并标记需要稳定性复扫。
    fn accept_window_paint(
        work: &mut RefreshWork,
        id: u64,
        mut document: RenderDocument,
        progress: crate::source_paint::Progress,
    ) -> Result<bool> {
        match progress {
            crate::source_paint::Progress::Pending(paint) => {
                // 没完整 DisplayList 时绝不替换 documents，原完整画面仍可供 GUI 使用。
                work.paint = Some(Box::new(PendingPaint {
                    window: id,
                    document,
                    work: paint,
                }));
            }
            crate::source_paint::Progress::Complete(draft) => {
                // 绘制完成的 frame 含实际显示列表，验证通过再进入本轮草稿基线。
                document.frame = draft.frame;
                document.validate()?;
                // 只有整个绘制 Complete 且验证通过才替换当前窗口草稿；Pending 保留配对文档和 Work，不对 GUI 可见。
                work.documents.insert(id, document);
                work.pass_changed = true;
                work.changed = true;
            }
        }
        Ok(false)
    }

    /// poll_refresh 收到全轮稳定后调用，完成关闭资源清理并生成一次多窗口发布值；不会直接写 NamespaceState。
    fn finish_refresh(&mut self, mut work: RefreshWork) -> Result<Option<RenderDocument>> {
        // 收敛后完成已关闭窗口退役并删其旧文档；没有实际变化时不制造额外 revision。
        self.bridge.finish_closed(&mut self.candidate.vm)?;
        // 以桥接真实仍登记窗口为准删去旧文档，不让已关闭副窗口在下轮凭缓存“复活”。
        let ids = self.bridge.window_ids()?;
        work.documents.retain(|id, _| ids.contains(id));
        if !work.changed {
            // 无新展示变化仍保存清理后的基线，但返回 None 避免增加无意义外部 revision。
            self.documents = work.documents;
            return Ok(None);
        }
        // 主窗可能尚无自己的已画文档，构造带 session 的空基线以容纳新副窗口和源码投影。
        let mut main = work
            .documents
            .get(&crate::window::MAIN_WINDOW)
            .cloned()
            .unwrap_or_else(|| RenderDocument {
                source: self.source.clone(),
                frame: crate::document::Frame {
                    session: self.id,
                    ..Default::default()
                },
                ..Default::default()
            });
        main.source = self.source.clone();
        // 优先采用源码与当前 transcript 相同的窗口代码投影，避免主窗口未重绘时 Sources 仍展示旧输入树。
        main.root = work
            .documents
            .values()
            .find(|document| document.source == self.source)
            .and_then(|document| document.root.clone())
            .or(main.root);
        // 副窗口统一挂到主文档 windows 一层，子文档自身不再嵌套副窗口，最终 validate 检查完整跨线程值。
        main.windows = work
            .documents
            .iter()
            .filter(|(id, _)| **id != crate::window::MAIN_WINDOW)
            .map(|(id, document)| (*id, document.clone()))
            .collect();
        main.validate()?;
        self.documents = work.documents;
        Ok(Some(main))
    }

    #[cfg(test)]
    /// 同步更新多个窗口尺寸，复用同一运行时并完成必要刷新。
    pub fn resize_windows(
        &mut self,
        viewports: &std::collections::BTreeMap<u64, crate::layout::Size>,
    ) -> Result<Option<RenderDocument>> {
        self.resize_windows_incremental(viewports, true)
    }

    /// resize_windows_incremental 检测目标尺寸集合变化时调用，取消当前续体并重建稳定轮，不回滚业务写入。
    fn retarget_refresh(
        &mut self,
        viewports: &std::collections::BTreeMap<u64, crate::layout::Size>,
    ) -> Result<()> {
        // 没有挂起刷新就无需重定向，外层随后直接把新尺寸送入正常 set_viewport 路径。
        let Some(mut work) = self.refresh.take() else {
            return Ok(());
        };
        // 记录实际取消了哪类续体用于诊断；已完成窗口草稿和已发生业务副作用不会因此回滚。
        let cancelled = work.pending.is_some();
        // 两个独立诊断位记录实际取消阶段，不能把所有重启都记成布局取消。
        let cancelled_paint = work.paint.is_some();
        if let Some(paint) = work.paint.take()
            && let Err(error) =
                self.bridge
                    .cancel_paint_frame(&mut self.candidate.vm, paint.window, *paint.work)
        {
            // 取消 paint 失败后域不再继续正常执行，不把残留续体草稿交给新一轮目标使用。
            self.faulted = true;
            return Err(error);
        }
        if let Some(pending) = work.pending.take()
            && let Err(error) = self
                .bridge
                .cancel_layout_frame(&mut self.candidate.vm, *pending)
        {
            // layout 取消还要恢复 Mount 检查点，失败同样停域，不能仅删 Pending Rust 值。
            self.faulted = true;
            return Err(error);
        }
        if let Err(error) = self.bridge.note_refresh_restart(cancelled, cancelled_paint) {
            // 统计写入失败也表示桥接状态不可可靠访问，不能保留看似可续跑的刷新并继续执行源程序。
            self.faulted = true;
            return Err(error);
        }
        // 重新从全窗口稳定轮开始，清当前选择/旧根并重置此次外部尺寸目标的收敛工作预算；草稿 documents 保留。
        work.windows.clear();
        work.current = None;
        work.root = None;
        work.pass_start = true;
        work.pass_changed = false;
        work.work = 0;
        work.viewports = Some(viewports.clone());
        self.refresh = Some(work);
        Ok(())
    }

    /// api::worker 的窗口 resize 和挂起刷新推进调用；同目标继续原 Work，新目标才显式取消并重定向。
    pub fn resize_windows_incremental(
        &mut self,
        viewports: &std::collections::BTreeMap<u64, crate::layout::Size>,
        drain: bool,
    ) -> Result<Option<RenderDocument>> {
        if self.faulted {
            bail!("runtime stopped after a callback or rendering failure");
        }
        // 仅目标视口集合确实不同才取消重定向；同一目标的下一 worker 轮继续原续体，不重复从头布局。
        let retarget = self
            .refresh
            .as_ref()
            .and_then(|work| work.viewports.as_ref())
            .is_some_and(|previous| previous != viewports);
        if retarget {
            // 外部目标确实改变才重启，避免每次 worker 轮询都把慢布局从头做一遍。
            self.retarget_refresh(viewports)?;
        }
        // 同目标 drain=true 同步排空旧刷新并保存完整结果；drain=false 只推进一量子，不能先执行新的尺寸变更。
        let previous = if self.has_pending_refresh() && !retarget {
            if drain {
                // 同步调用者要求先完成原目标的完整结果，再处理本次输入的尺寸变更。
                let result = self.refresh_document();
                self.finish_refresh_update(result)?
            } else {
                // 增量轮本次只继续原视觉调用，不能在其只读挂起中插入 set_viewport 写入。
                return self.advance_idle_refresh();
            }
        } else {
            None
        };
        // 过滤仍属于此会话的窗口，GUI 可能还保留旧运行时窗口尺寸记录，不能自动创建同 ID 新资源。
        let ids = self.bridge.window_ids()?;
        // 聚合真正改变尺寸的窗口，重复通知不应引起重新布局或派生版本反馈。
        let mut changed = false;
        // 仅更新桥接仍注册的窗口；旧 GUI 尺寸记录不应在新域里隐式创建窗口资源。
        for (id, viewport) in viewports {
            // viewports 来自宿主尺寸记录，只有桥接当前仍注册的 ID 才有权改输入；其余记录不会分配新窗口。
            if ids.contains(id) {
                // 每次选明确窗口，使 ui.viewport 等隐式上下文读到对应窗口的尺寸输入。
                self.bridge.select_window(*id)?;
                changed |= self
                    .bridge
                    .set_viewport(&mut self.candidate.vm, Some(*viewport))?;
            }
        }
        self.bridge.select_window(crate::window::MAIN_WINDOW)?;
        // 尺寸没变且无挂起工作则直接返回先前已完成文档，避免制造无意义新帧。
        if !changed && !self.has_pending_refresh() {
            return Ok(previous);
        }
        if drain {
            // 新刷新没变化时仍返回上面已排空的 previous，不让同步路径丢失完整已就绪结果。
            let result = self
                .refresh_document()
                .map(|document| document.or(previous));
            self.finish_refresh_update(result)
        } else {
            // 只推进一次，目标集合随 Work 保存，下轮据此辨别“续跑”还是“真正新 resize”。
            let result = self.advance_idle_refresh();
            if let Some(work) = &mut self.refresh {
                work.viewports = Some(viewports.clone());
            }
            result
        }
    }

    /// resize 增量路径调用，推进一片并将 Pending 映成 None；仍需 has_pending_refresh 判断是否已空闲。
    fn advance_idle_refresh(&mut self) -> Result<Option<RenderDocument>> {
        // 先保存错误/完成值供 finish_refresh_update 清理，不能因 poll 报错跳过未发布请求撤销。
        let result = self.poll_refresh(true).map(|progress| match progress {
            RefreshProgress::Pending => None,
            RefreshProgress::Complete(document) => document.map(|document| *document),
        });
        self.finish_refresh_update(result)
    }

    /// resize/advance_idle_refresh 共用收尾，错误时丢未发布命令，空闲后再回收不可达托管根。
    fn finish_refresh_update(
        &mut self,
        result: Result<Option<RenderDocument>>,
    ) -> Result<Option<RenderDocument>> {
        if result.is_err() {
            // GUI 继续使用旧完整文档，失败草稿的副作用命令不能外泄为 Resize/Focus 等原生动作。
            self.take_window_commands()?;
            self.bridge.discard_pending(&mut self.candidate.vm)?;
        }
        if !self.has_pending_refresh() {
            // 仍挂起时临时对象属于原视觉调用，不能在其中完整回收；只在续体结束边界 reclaim。
            self.bridge
                .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)?;
        }
        result
    }

    /// 同步调用方/测试使用，在 owning VM 推进就绪任务并排空展示；不允许 GUI 或 provider 线程调用 VM。
    pub fn poll_tasks(&mut self) -> Result<Option<RenderDocument>> {
        self.poll_tasks_mode(None)
    }

    /// api::worker 空闲轮调用，每轮至多推进一个任务，然后允许其布局/绘制挂起，给前台输入公平机会。
    pub fn poll_tasks_incremental(
        &mut self,
        viewports: &std::collections::BTreeMap<u64, crate::layout::Size>,
    ) -> Result<Option<RenderDocument>> {
        self.poll_tasks_mode(Some(viewports))
    }

    /// poll_tasks/poll_tasks_incremental 共同执行路径，任务错误停用同一故障域，成功变更走正常刷新状态机。
    fn poll_tasks_mode(
        &mut self,
        viewports: Option<&std::collections::BTreeMap<u64, crate::layout::Size>>,
    ) -> Result<Option<RenderDocument>> {
        // 异步回调不能插入只读布局/绘制续体中，即使后台邮箱已有结果也等刷新空闲边界。
        if self.has_pending_refresh() {
            // 只读视觉续体尚未结束时不取邮箱/回调写业务属性，先让 worker 继续原刷新。
            return Ok(None);
        }
        if self.faulted {
            // 故障域不执行任何新用户任务，仅取消已有任务并在确实移除工作后回收引用。
            if self.bridge.cancel_tasks(&mut self.candidate.vm)? > 0 {
                self.bridge
                    .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)?;
            }
            return Ok(None);
        }
        // 表示确有任务推进/清理，不等于某个协程已经 Completed；用于决定是否需要 reclaim。
        let mut completed = false;
        // 保留调度/刷新错误供下方统一停域、取消任务、丢弃未发布命令，避免中途直接返回。
        let result = (|| {
            // worker 增量轮至多启动一个任务推进，给前台输入和窗口刷新公平机会；同步路径单轮允许64项。
            let limit = if viewports.is_some() { 1 } else { 64 };
            if self.bridge.poll_tasks(&mut self.candidate.vm, limit)? == 0 {
                // 无实际推进就不启动视觉刷新，等待 I/O/计时器不会凭轮询本身制造新帧。
                return Ok(None);
            }
            completed = true;
            self.refresh_after_mutation(viewports)
        })();
        if result.is_err() {
            // 任一共享 VM 任务回调故障会停整个域，不只把当前 Task 标失败后继续执行其他不安全回调。
            self.faulted = true;
            self.bridge.cancel_tasks(&mut self.candidate.vm)?;
            self.take_window_commands()?;
            self.bridge.discard_pending(&mut self.candidate.vm)?;
        }
        // 任务推进或失败后才需回收，并且不能在仍有只读续体时清理其临时根。
        if (completed || result.is_err()) && !self.has_pending_refresh() {
            self.bridge
                .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)?;
        }
        result
    }

    /// api::worker 准备一次发布/错误丢弃时调用，空闲边界才可排空命令，避免从未稳定草稿提前执行 OS 动作。
    pub fn take_window_commands(&self) -> Result<Vec<crate::window::Command>> {
        self.require_idle_refresh()?;
        self.bridge.take_window_commands(&self.candidate.vm)
    }

    #[cfg(test)]
    /// 测试用单窗口尺寸更新入口，遵循与原生尺寸发布相同的校验和刷新规则。
    pub fn resize(
        &mut self,
        viewport: Option<crate::layout::Size>,
    ) -> Result<Option<RenderDocument>> {
        self.require_idle_refresh()?;
        if self.faulted {
            bail!("runtime stopped after a callback or rendering failure");
        }
        if !self.bridge.set_viewport(&mut self.candidate.vm, viewport)? {
            return Ok(None);
        }
        // 同步测试 resize 保存刷新错误，随后同样丢弃失败请求并回收引用，不让 ? 跳过清理。
        let result = self.refresh_document();
        if result.is_err() {
            self.take_window_commands()?;
            self.bridge.discard_pending(&mut self.candidate.vm)?;
        }
        self.bridge
            .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)?;
        result
    }

    /// shutdown 和 ReplSession::drop 调用，显式取消 owning VM 上挂起的 paint/layout，不回放源程序。
    fn cancel_pending_refresh(&mut self) -> Result<()> {
        if let Some(mut work) = self.refresh.take() {
            // 从会话移走 Work 后逐项清理，检查点/临时 VM 根不能仅靠 Rust 值析构替代。
            if let Some(paint) = work.paint.take() {
                self.bridge.cancel_paint_frame(
                    &mut self.candidate.vm,
                    paint.window,
                    *paint.work,
                )?;
            }
            if let Some(pending) = work.pending.take() {
                // 与 paint 清理互斥的布局续体还带 Mount 检查点，交桥接层完整取消而非直接丢弃 Rust 句柄。
                self.bridge
                    .cancel_layout_frame(&mut self.candidate.vm, *pending)?;
            }
        }
        Ok(())
    }

    /// api::worker 退役运行时调用，取消视觉续体并关闭任务/挂载/窗口；Candidate 的根仍由其 close/Drop 释放。
    pub fn shutdown(&mut self) -> Result<(usize, usize, usize)> {
        // 先取消视觉续体恢复挂载检查点，再判断原域是否允许正常关闭回调，随后标故障禁止后续普通执行。
        self.cancel_pending_refresh()?;
        // 正常域允许卸载钩子，已经故障的域只做宿主清理，不能再次执行不可靠的源回调。
        let callbacks = !self.faulted;
        self.faulted = true;
        self.bridge.shutdown(&mut self.candidate.vm, callbacks)
    }

    /// worker 在故障域处理原生关闭时调用，只退役指定副窗口与缓存，不允许再执行源生命周期钩子。
    pub fn retire_window(&mut self, id: u64) -> Result<()> {
        self.require_idle_refresh()?;
        // 只用于域已停止后的宿主清理，不能将此路径当作正常 Window.close 源方法的替代。
        self.faulted = true;
        // 专用退役只清宿主资源，不调源生命周期；删除已缓存文档和窗口命令，避免后续重发该副窗口。
        self.bridge.retire_window(&mut self.candidate.vm, id)?;
        self.documents.remove(&id);
        // 故障退役只排空命令并丢弃，不能把失败域旧 Focus/Resize 发布到当前原生资源。
        let _ = self.take_window_commands()?;
        self.bridge
            .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)
    }

    /// api::worker 接受 tab-drop 前调用，验证两端发布版本/页面顺序，普通非拖放信封由 bridge 返回 true。
    pub fn accepts_tab_drop(&self, input: &crate::events::Input) -> bool {
        self.bridge.accepts_tab_drop(&self.candidate.vm, input)
    }

    /// api::worker 接纳窗口输入前调用，只查询资源是否仍登记且未 closing，后面仍需 session/Mount 校验。
    pub fn accepts_window(&self, id: u64) -> bool {
        self.bridge.accepts_window(id)
    }

    /// 报告该运行时是否已经停止正常业务执行，供 worker 选择故障清理路径。
    pub fn is_faulted(&self) -> bool {
        self.faulted
    }

    #[cfg(test)]
    /// 同步分发一次已校验输入并完成展示刷新。
    pub fn dispatch(&mut self, input: &crate::events::Input) -> Result<ReplResult> {
        self.dispatch_mode(input, None)
    }

    /// api::worker 的原生/HTTP 输入任务调用，在同一会话执行一次回调，然后分片推进其视觉变化。
    pub fn dispatch_incremental(
        &mut self,
        input: &crate::events::Input,
        viewports: &std::collections::BTreeMap<u64, crate::layout::Size>,
    ) -> Result<ReplResult> {
        self.dispatch_mode(input, Some(viewports))
    }

    /// dispatch/dispatch_incremental 共用入口，核对运行时代际/拖放目标，再选窗分派并恢复主窗口上下文。
    fn dispatch_mode(
        &mut self,
        input: &crate::events::Input,
        viewports: Option<&std::collections::BTreeMap<u64, crate::layout::Size>>,
    ) -> Result<ReplResult> {
        self.require_idle_refresh()?;
        if self.faulted {
            bail!("runtime stopped after a callback or rendering failure");
        }
        // 即使绕过 HTTP 入口直接调用，也再校验会话身份；共享窗口数值 ID 不提供跨 VM 权限。
        if input.session != self.id {
            bail!("event belongs to another runtime session");
        }
        if !self.accepts_tab_drop(input) {
            // 拖放还需验证目标端最新页面序列，身份不符时不先执行源 moveToWindow 再尝试修复位置。
            bail!("drop targets an obsolete presentation");
        }
        // 将 ui.window/viewport 等隐式上下文切到事件所属窗口，分发后统一恢复主窗口。
        self.bridge.select_window(input.window)?;
        // 暂存回调/刷新错误，外层始终尝试恢复主窗口选择、丢弃未发布结果并回收空闲根。
        let result = (|| {
            self.bridge.dispatch(&mut self.candidate.vm, input)?;
            // 输入已执行一次，后续只续跑视觉刷新，不能为多片 layout 再调用同一 click 回调。
            let document = self.refresh_after_mutation(viewports)?;
            Ok(ReplResult {
                value: "nil".into(),
                document,
                bindings: self
                    .candidate
                    .vm
                    .dict_items(self.candidate.globals.expect("live globals"))?
                    .len()
                    .saturating_sub(1),
                input: self.inputs,
            })
        })();
        self.bridge.select_window(crate::window::MAIN_WINDOW)?;
        if result.is_err() {
            self.take_window_commands()?;
            // 回调失败属于共享 VM 故障，不只关闭单个按钮；丢弃未发布命令与 pending 请求，但不重放已执行写入。
            self.faulted = true;
            self.bridge.discard_pending(&mut self.candidate.vm)?;
        }
        if !self.has_pending_refresh() {
            // 分派后的只读刷新若仍挂起，临时根归原调用持有；只有空闲边界才回收，不干扰下一量子恢复。
            self.bridge
                .reclaim(&mut self.candidate.vm, &mut self.candidate.roots)?;
        }
        result
    }
}

impl Drop for ReplSession {
    /// 析构兜底取消会话中未完成的布局/绘制续体；需要观察清理错误或运行退出钩子的路径仍须显式 shutdown。
    fn drop(&mut self) {
        // Drop 最后兜底取消未完成视觉工作，错误无法从析构返回；需要报告清理错误的路径必须显式 shutdown。
        let _ = self.cancel_pending_refresh();
    }
}

/// execute_mode 为本轮 Sources 根调用，递归把局部一基行号平移到累计 Console transcript，不改变执行源码。
fn shift_node_lines(node: &mut CodeNode, offset: usize) {
    node.start_line += offset;
    node.end_line += offset;
    for child in &mut node.children {
        // 所有后代都保存独立行号，父节点平移不会隐式修正内部函数/表达式的选择范围。
        shift_node_lines(child, offset);
    }
}
/// execute_mode 在保存全局 _ 前调用，把真实返回值/新绑定值转成显示字符串；返回根仍由调用者释放。
fn value_repr(vm: &Vm, value: &Value) -> Result<String> {
    Ok(match value {
        Value::Nil => "nil".into(),
        Value::Bool(v) => v.to_string(),
        Value::Text(v) => format!("{v:?}"),
        Value::Number(v) => v.to_string(),
        Value::Object(v) => vm.repr(*v)?,
    })
}

/// 拥有 VM、全局字典与宿主保留根；关闭时按顺序释放，失败也必须收尾。
struct Candidate {
    // 实际解释器/托管堆，仅执行 worker 线程操作，不放入共享 NamespaceState。
    vm: Vm,
    // 宿主安装期间保留的拥有根，close 逆序 pop；ObjectRef Rust 数值本身没有自动 release 行为。
    roots: Vec<ObjectRef>,
    // 主全局字典也在 roots 中，先清字典断业务根，再统一释放根，避免闭包环残留。
    globals: Option<ObjectRef>,
}

impl Candidate {
    /// 创建独立 VM，先不保留任何宿主根或全局字典；后续安装失败也由该候选负责清理。
    fn new() -> Result<Self> {
        Ok(Self {
            vm: Vm::new()?,
            roots: Vec::new(),
            globals: None,
        })
    }

    /// compile/evaluate 显式调用，Candidate::drop 兜底调用；按拥有顺序拆根并验证堆没有遗留对象。
    fn close(&mut self) -> Result<()> {
        // 清全局字典先断业务对象可达根，再逆序释放宿主分配根；最后执行循环回收并验证对象计数归零。
        if let Some(globals) = self.globals.take() {
            // take 使重复 close 不重复清同一身份；先断用户全局再释放类型/函数等宿主根。
            self.vm.dict_clear(globals)?;
        }
        // pop 逐项移出确保再次 close 不重复释放已成功处理的根；错误仍交显式关闭调用方报告。
        while let Some(root) = self.roots.pop() {
            self.vm.release(root)?;
        }
        self.vm.collect_cycles();
        if self.vm.object_count() != 0 {
            // 源程序返回了纯数据也不掩盖资源泄漏，显式 close 会把这个错误报告给调用者。
            bail!("candidate VM retained objects after cleanup");
        }
        Ok(())
    }
}

impl Drop for Candidate {
    /// 析构调用 Candidate.close 释放候选根和 VM，覆盖提前返回/异常展开；析构不能向调用者报告清理错误。
    fn drop(&mut self) {
        // 显式 close 可以报告引用计数/清理错误；Drop 则保证提前返回和异常展开仍经过最终清理边界。
        let _ = self.close();
    }
}

/// 本模块和 bridge/tasks 的 VM 错误映射调用，立即取 last_traceback 拼成纯文本，避免后续调用覆盖故障栈。
pub(crate) fn runtime_error(vm: &Vm, error: VmError) -> anyhow::Error {
    // 错误发生后立即读取 VM traceback，保留函数、源文件与指令偏移；无栈信息时直接保留原 VmError。
    let locations = vm
        .last_traceback()
        .iter()
        .map(|frame| {
            // 每帧保留来源文件、函数名和指令位置，不把托管异常对象直接跨线程交付。
            format!(
                "{}:{} in {} (instruction {})",
                frame.filename, frame.first_line, frame.function, frame.instruction_offset
            )
        })
        .collect::<Vec<_>>()
        .join("\n");
    if locations.is_empty() {
        // 无 VM 栈时保留原始 VmError，不能凭当前源码猜一个错误行号。
        error.into()
    } else {
        // 含栈则附加每帧可读位置，Console/API 不需读取 VM 就能展示错误。
        anyhow::anyhow!("{error}\n{locations}")
    }
}

#[derive(Default)]
/// 编译前的语法节点数量/嵌套预算，限制输入结构复杂度。
struct AstBudget {
    // 当前递归路径深度，leave_node 归还；不能与累计节点数共用一个计数。
    depth: usize,
    // 已访问节点总量，多个 Script 根共享累计，leave_node 不减少。
    nodes: usize,
}

impl Visitor for AstBudget {
    type Error = anyhow::Error;
    /// Aster Visitor 在进入任意语法节点时调用，compile/evaluate/加载/Console 共用这个结构预算。
    fn enter_node(&mut self, _span: Span) -> Result<()> {
        // 每次进入节点累计总数和当前深度；leave 只归还深度，整份输入总量不会因退出子树重置。
        self.depth += 1;
        self.nodes += 1;
        if self.depth > MAX_AST_DEPTH || self.nodes > MAX_AST_NODES {
            // 在加载/执行代码前停止，防止巨大源码结构绕过仅约束运行指令的 LIMITS。
            bail!("Aster AST exceeds the 64-level or 10000-node host budget");
        }
        Ok(())
    }
    /// 离开当前语法节点时归还嵌套深度；累计节点数保留，不能通过退出子树绕过总量预算。
    fn leave_node(&mut self) {
        self.depth -= 1;
    }
}

/// compile/prepare_program/execute_mode 调用，将已解析 AST 投影为 Sources 浏览树，不保存可执行托管引用。
fn architecture(
    source: &SourceUnit,
    plan: &SourcePlan,
    namespace: &str,
    submission: u64,
) -> CodeNode {
    // CodeNode ID 由 namespace/submission 和本次递增序号构成，只是 Sources 投影身份，不是托管对象地址。
    let mut tree = Architecture {
        line_starts: line_starts(source.text()),
        next_id: 0,
        identity: format!("{namespace}@{submission}"),
    };
    // 把各根按源顺序拼入一个显示根，后续 CodeNode ID 在这一次 tree 构造中递增。
    let mut children = Vec::new();
    for root in plan.roots() {
        match root {
            // 模块展示声明树，脚本展示每段语句树，表达式模式保留单表达式层次。
            AstRoot::Module(program) => children.extend(
                program
                    .declarations
                    .iter()
                    .map(|decl| tree.declaration(decl)),
            ),
            AstRoot::Interactive(input) => {
                children.extend(input.statements.iter().map(|stmt| tree.statement(stmt)))
            }
            AstRoot::Expression(expression) => children.push(tree.expression(expression)),
        }
    }
    // 只借根列表取首尾跨度，不克隆整棵 AST；Script 的 span 已由 endor_script 映回原文件。
    let roots = plan.roots();
    // 整体范围取首根起点至末根终点，Script 的多个交互片段在原始文本中的 span 已恢复偏移。
    let span = Span::new(
        roots.first().map_or(0, |root| root.span().start),
        roots.last().map_or(0, |root| root.span().end),
    );
    // 代码根种类是 Sources 显示分类，不参与 VM 模块/脚本执行方式的选择。
    let kind = if matches!(plan, SourcePlan::Module(_)) {
        "module"
    } else {
        "script"
    };
    tree.node(namespace.to_owned(), kind, span, children)
}

/// architecture/execute_mode 调用，建立字节偏移→行号的搜索索引，兼容 CRLF、LF 和孤立 CR。
fn line_starts(source: &str) -> Vec<usize> {
    // Span 使用 UTF-8 字节单位，所以不用 chars().enumerate() 的字符索引匹配它。
    let bytes = source.as_bytes();
    // 按字节扫描行终止符，CRLF 仅在 LF 记一次，孤立 CR 也换行；空文本仍保留第1行起点0。
    let mut starts = vec![0];
    for (offset, byte) in bytes.iter().enumerate() {
        if *byte == b'\n' || (*byte == b'\r' && bytes.get(offset + 1) != Some(&b'\n')) {
            // 记录换行符之后的下一行首，CRLF 只在 LF 分支记录一次，空末行也有可定位起点。
            starts.push(offset + 1);
        }
    }
    starts
}

/// 构造 Sources 语法投影所需的源码与定位辅助状态。
struct Architecture {
    // 排好序的字节行首，node 通过 partition_point 得到一基行号。
    line_starts: Vec<usize>,
    // 单次代码投影中的序号，高水位只用于 UI ID，不是 VM 对象身份。
    next_id: usize,
    // namespace@submission 前缀，区分不同提交/Console 输入产生的 AST 节点。
    identity: String,
}

impl Architecture {
    /// declaration/function/statement/expression 共用的纯数据分配助手，统一 ID 与半开 span→一基行号转换。
    fn node(&mut self, name: String, kind: &str, span: Span, children: Vec<CodeNode>) -> CodeNode {
        // 先取当前序号再递增，父子节点构建顺序可不同但同投影内身份唯一。
        let id = self.next_id;
        self.next_id += 1;
        // partition_point 返回不大于 offset 的行首数量，天然得到1基行号；span.end 是半开端，先减1找最后实际字符行。
        let line = |offset| self.line_starts.partition_point(|start| *start <= offset);
        CodeNode {
            id: format!("{}:ast-{id}", self.identity),
            name,
            kind: kind.into(),
            start_line: line(span.start),
            end_line: line(span.end.saturating_sub(1).max(span.start)),
            children,
        }
    }

    /// architecture 的模块声明和 statement 的声明分支调用，区分普通函数与含字段/方法的类。
    fn declaration(&mut self, declaration: &Decl) -> CodeNode {
        match &declaration.kind {
            DeclKind::Function(function) => self.function(function),
            DeclKind::Class(class) => {
                // 类投影先列字段再列方法；只复制显示名称和范围，不把声明 AST 当可执行对象保存。
                let mut children: Vec<_> = class
                    .fields
                    .iter()
                    .map(|field| self.node(field.name.text.clone(), "field", field.span, vec![]))
                    .collect();
                children.extend(class.methods.iter().map(|method| self.function(method)));
                self.node(class.name.text.clone(), "class", class.span, children)
            }
        }
    }

    /// declaration 的函数和类方法分支调用，逐条投影函数体；参数包含在源码范围中但不另建显示节点。
    fn function(&mut self, function: &frontend::ast::Function) -> CodeNode {
        // 函数投影按函数体语句顺序递归展开，不单独生成参数节点；展示范围仍覆盖完整函数声明。
        let children = function
            .body
            .statements
            .iter()
            .map(|stmt| self.statement(stmt))
            .collect();
        self.node(
            function.name.text.clone(),
            "function",
            function.span,
            children,
        )
    }

    /// architecture/function/分支体递归调用，生成语句浏览节点，不执行条件、不改变 AST 或业务对象。
    fn statement(&mut self, statement: &Stmt) -> CodeNode {
        match &statement.kind {
            StmtKind::If(branch) => {
                // 条件是第一个孩子，随后 then/else 依源顺序展开；树不预测运行时会走哪支。
                let mut children = vec![self.expression(&branch.condition)];
                children.extend(branch.body.statements.iter().map(|s| self.statement(s)));
                if let Some(body) = &branch.otherwise {
                    // 没有 else 就不造空显示分支，保持 Sources 仅浏览实际存在的源码。
                    children.extend(body.statements.iter().map(|s| self.statement(s)));
                }
                self.node("if".into(), "if", statement.span, children)
            }
            StmtKind::While(loop_) => {
                // 只展开一次静态循环体，不能按运行次数复制显示节点或重演循环。
                let mut children = vec![self.expression(&loop_.condition)];
                children.extend(loop_.body.statements.iter().map(|s| self.statement(s)));
                self.node("while".into(), "while", statement.span, children)
            }
            // 成员赋值投影两个子表达式：目标对象和右值，成员名作为本节点显示名称。
            StmtKind::MemberAssignment(assignment) => {
                // 成员访问目标也可能是复合调用，独立投影才能浏览到其中的对象表达式。
                let object = self.expression(&assignment.object);
                // 右值另建子树，不把赋值目标名字混进计算表达式的显示类型。
                let value = self.expression(&assignment.value);
                self.node(
                    assignment.name.text.clone(),
                    "member-assign",
                    statement.span,
                    vec![object, value],
                )
            }
            StmtKind::Binding(binding) => {
                // 显示绑定名字，孩子保留初始值表达式及其完整范围。
                let child = self.expression(&binding.value);
                self.node(
                    binding.name.text.clone(),
                    "let",
                    statement.span,
                    vec![child],
                )
            }
            StmtKind::Assignment(assignment) => {
                // 和 let 显示类型区分，Sources 可分清声明与之后更新同一名字的语句。
                let child = self.expression(&assignment.value);
                self.node(
                    assignment.name.text.clone(),
                    "assign",
                    statement.span,
                    vec![child],
                )
            }
            StmtKind::Return(returned) => {
                // Option::iter 保持无值 return 的孩子列表为空，不凭空补一个 nil AST 节点。
                let children = returned
                    .value
                    .iter()
                    .map(|expr| self.expression(expr))
                    .collect();
                self.node("return".into(), "return", statement.span, children)
            }
            StmtKind::Expression(expr) => self.expression(expr),
            StmtKind::Declaration(decl) => self.declaration(decl),
        }
    }

    /// statement 和 expression 自递归调用，保留运算/成员/调用层次，显示标签可截短但源范围不截短。
    fn expression(&mut self, expr: &Expr) -> CodeNode {
        // 三元组统一提供 UI 名称、种类和孩子，最后仍用同一个 node 助手分配 ID/行号。
        let (name, kind, children) = match &expr.kind {
            ExprKind::Name(name) => (name.clone(), "name", vec![]),
            ExprKind::Number(value) => (value.clone(), "number", vec![]),
            // 字符串展示名最多40个 Unicode 字符，但 span 保留整段字面量，截断标签不影响源码选择范围。
            ExprKind::String(value) => (value.chars().take(40).collect(), "string", vec![]),
            ExprKind::Symbol(name) => (name.text.clone(), "symbol", vec![]),
            // 当前代码投影把 Unary 和 Await 共用 unary/negate 显示标签；这是展示简化，不表示 await 执行成取负。
            ExprKind::Unary { operand, .. } | ExprKind::Await(operand) => {
                ("negate".into(), "unary", vec![self.expression(operand)])
            }
            ExprKind::Binary { left, right, .. } => (
                "binary".into(),
                "binary",
                vec![self.expression(left), self.expression(right)],
            ),
            ExprKind::Member { object, name } => {
                // 成员名作显示标签，对象表达式保留为孩子，类型/属性读取语义不在此求值。
                (name.text.clone(), "member", vec![self.expression(object)])
            }
            ExprKind::Call { callee, arguments } => {
                // 调用目标作为首个孩子，随后按原顺序列实参，Sources 可以区分调用表达式和参数层次。
                let mut children = vec![self.expression(callee)];
                children.extend(arguments.iter().map(|expr| self.expression(expr)));
                ("call".into(), "call", children)
            }
        };
        self.node(name, kind, expr.span, children)
    }
}

#[cfg(test)]
mod tests;

#[cfg(test)]
mod manuscript_tests;