docs: explain Tessera modules and execution flows in Chinese

src/render/source_paint.rs

@@ -1,3 +1,7 @@
+//! 执行源 paint 覆盖并解码受检查的 PaintCommand。
+//! 所有绘制回调位于只读域；临时返回对象可分配，但已有模型不可写。命令数量、类型、坐标和颜色在合入帧前检查。
+//! 源命令与原生命令按 Mount 绘制顺序合并，随后装配世界 UI 面板。挂起绘制同样需要显式恢复或取消。
+//!
 //! Source paint dispatch produces checked immutable commands. One read-only VM
 //! resumable call sequences all overrides, sharing one instruction/frame budget.
 use crate::{
@@ -17,9 +21,11 @@ use std::{
     sync::{Arc, Mutex},
 };
 
+/// 统一构造本模块的参数错误，让调用方停止处理无效输入。
 fn invalid(message: &'static str) -> VmError {
     VmError::InvalidArgument(message)
 }
+/// 从源值中提取并检查托管对象身份，错误类型沿 VM 错误返回。
 fn object(value: Value) -> Result<ObjectRef, VmError> {
     if let Value::Object(object) = value {
         Ok(object)
@@ -27,6 +33,7 @@ fn object(value: Value) -> Result<ObjectRef, VmError> {
         Err(invalid("paint must return managed objects"))
     }
 }
+/// 把当前源值或文本选择解码成此调用需要的文本表示。
 fn text(store: &ObjectStore, object: ObjectRef, name: &str) -> Result<String, VmError> {
     if let Value::Text(value) = store.get_attr(object, name)? {
         Ok(value)
@@ -34,6 +41,7 @@ fn text(store: &ObjectStore, object: ObjectRef, name: &str) -> Result<String, Vm
         Err(invalid("paint field must be text"))
     }
 }
+/// 在源 Value 与所需数值表示之间转换，并沿用本调用的有限值/范围检查。
 fn number(store: &ObjectStore, object: ObjectRef, name: &str) -> Result<f32, VmError> {
     let Value::Number(value) = store.get_attr(object, name)? else {
         return Err(invalid("paint field must be a Number"));
@@ -50,6 +58,7 @@ fn number(store: &ObjectStore, object: ObjectRef, name: &str) -> Result<f32, VmE
     }
     Ok(value)
 }
+/// 从当前 desktop 的类型注册表取得绘制结果必须符合的托管类型。
 fn named_type(store: &ObjectStore, desktop: ObjectRef, name: &str) -> Result<ObjectRef, VmError> {
     let registry = object(store.get_attr(desktop, "types")?)?;
     object(
@@ -58,6 +67,7 @@ fn named_type(store: &ObjectStore, desktop: ObjectRef, name: &str) -> Result<Obj
             .ok_or(invalid("missing paint type"))?,
     )
 }
+/// 把源方法返回的托管绘制值解码成受限 Rust 命令，检查名义类型、字段和绘制预算。
 fn decode(
     store: &ObjectStore,
     command: ObjectRef,
@@ -150,22 +160,26 @@ fn decode(
 }
 
 #[derive(Debug, Default)]
+/// 按出现 ID 收集已检查的源绘制覆盖，随后与原生默认命令合并。
 struct PaintOutput {
     commands: BTreeMap<u64, Vec<RenderCommand>>,
     count: usize,
 }
 type Output = Arc<Mutex<PaintOutput>>;
 #[derive(Debug)]
+/// 检查源 paint 返回列表并将命令保存到当前出现的绘制结果。
 struct Collect {
     desktop: ObjectRef,
     mount: u64,
     output: Output,
 }
 impl NativeCallable for Collect {
+    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(1))
     }
 
+    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let [Value::Object(result)] = args else {
             return Err(invalid("paint must return a DisplayList"));
@@ -195,16 +209,19 @@ impl NativeCallable for Collect {
     }
 }
 #[derive(Debug)]
+/// 为当前出现准备 paint 方法、几何和类型检查上下文。
 struct Prepare {
     desktop: ObjectRef,
     mounts: Vec<(u64, WeakObjectRef)>,
     output: Output,
 }
 impl NativeCallable for Prepare {
+    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
 
+    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
         let advance = cx.allocate(ContextNativeFunction::new(
             "next paint occurrence",
@@ -225,6 +242,7 @@ impl NativeCallable for Prepare {
 }
 
 #[derive(Debug)]
+/// 安排下一个出现的绘制调用，保持原始绘制顺序和共享 VM 预算。
 struct Advance {
     desktop: ObjectRef,
     mounts: Arc<[(u64, WeakObjectRef)]>,
@@ -232,9 +250,11 @@ struct Advance {
     output: Output,
 }
 impl NativeCallable for Advance {
+    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(0))
     }
+    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
     fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
         let occurrence = {
             let mut next = self
@@ -304,6 +324,7 @@ impl NativeCallable for Advance {
     }
 }
 
+/// 已经完成本阶段、但尚未由桥接层发布的派生结果，包含帧/缓存或真实读取依赖。
 pub struct Draft {
     pub frame: Frame,
     pub reads: Vec<endor_core::ReadDependency>,
@@ -311,12 +332,14 @@ pub struct Draft {
 }
 
 #[must_use = "pending paint must be resumed or cancelled on its owning VM"]
+/// 本次推进处于挂起还是完成；挂起工作必须继续恢复或显式取消。
 pub enum Progress {
     Pending(Box<Work>),
     Complete(Box<Draft>),
 }
 
 /// Only unpublished native commands and an owning prepare root cross a pause.
+/// 拥有未完成源调用及临时根的工作句柄；丢弃 Rust 值不能替代 VM 内的取消。
 pub struct Work {
     desktop: ObjectRef,
     prepare: ObjectRef,
@@ -327,12 +350,14 @@ pub struct Work {
 }
 
 impl Work {
+    /// 继续当前绘制续体，保留其先前收集的命令和所属窗口上下文。
     pub fn resume(mut self, vm: &mut Vm, slice: usize) -> Result<Progress> {
         self.slices += 1;
         let progress = vm.resume_read_only_call(slice);
         self.accept(vm, progress)
     }
 
+    /// 关闭未完成绘制续体并释放其临时根，不发布半完成命令列表。
     pub fn cancel(self, vm: &mut Vm) -> Result<()> {
         let cancelled = vm.cancel_read_only_call();
         let released = vm.release(self.prepare);
@@ -341,6 +366,7 @@ impl Work {
         Ok(())
     }
 
+    /// 区分源绘制续体是挂起还是完成，保留工作或结束只读域并生成 Draft。
     fn accept(
         self,
         vm: &mut Vm,
@@ -368,6 +394,7 @@ impl Work {
     }
 }
 
+/// 建立本轮只读绘制驱动和结果收集器；源覆盖与原生默认绘制最终保持同一出现顺序。
 pub fn start(
     vm: &mut Vm,
     desktop: ObjectRef,
@@ -411,6 +438,7 @@ pub fn start(
     work.accept(vm, result)
 }
 
+/// 按 Mount 合并源覆盖和原生命令，补齐投影/裁剪表，再递归装配世界 UI 面板。
 fn finish(vm: &mut Vm, mut work: Work, reads: Vec<endor_core::ReadDependency>) -> Result<Progress> {
     let output = work
         .output