docs: explain Tessera modules and execution flows in Chinese

src/render/source_hit.rs

@@ -1,3 +1,6 @@
+//! 通过真正的源/原生 hitTest 协议确定指针目标。
+//! 按逆绘制顺序筛选候选，并在同一只读 VM 调用与预算中比较按下、释放目标；透明或未命中的子项可以继续回退。
+//!
 //! Resolve pointer targets in paint order through source/native hitTest methods.
 //! Both press and release selectors share one read-only VM call and budget.
 use crate::{mount::Mount, ui_bridge::attach_desktop_type};
@@ -7,12 +10,15 @@ use endor_core::{
 };
 
 #[derive(Debug)]
+/// 验证 hitTest 返回的是 Bool，避免把任意真值隐式当成命中。
 struct Boolean;
 impl NativeCallable for Boolean {
+    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(1))
     }
 
+    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
     fn invoke(&self, _: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let [Value::Bool(value)] = args else {
             return Err(VmError::InvalidArgument("hitTest must return Bool"));
@@ -21,12 +27,15 @@ impl NativeCallable for Boolean {
     }
 }
 #[derive(Debug)]
+/// 比较按下与释放的选择结果，只有同一目标才能继续点击分发。
 struct SameTarget;
 impl NativeCallable for SameTarget {
+    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(2))
     }
 
+    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
     fn invoke(&self, _: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let value = match args {
             [Value::Object(first), Value::Object(second)] if first == second => {
@@ -37,6 +46,7 @@ impl NativeCallable for SameTarget {
         Ok(NativeResult::Return(value))
     }
 }
+/// 构造只读命中选择驱动所需的托管代码与函数对象。
 fn code(
     cx: &mut NativeContext<'_>,
     instructions: Vec<Instruction>,
@@ -52,6 +62,7 @@ fn code(
     let globals = cx.new_dict()?;
     cx.new_function("pointer hitTest", code, globals)
 }
+/// 按逆绘制顺序构造候选 hitTest 调用，先进行几何与局部坐标筛选。
 fn selector(
     cx: &mut NativeContext<'_>,
     candidates: &[WeakObjectRef],
@@ -137,6 +148,7 @@ fn selector(
     code(cx, instructions, constants, CodeLayout::default())
 }
 #[derive(Debug)]
+/// 在一个只读调用中准备两次指针选择所需的候选与局部坐标。
 struct Prepare {
     candidates: Vec<WeakObjectRef>,
     press: [f32; 2],
@@ -144,10 +156,12 @@ struct Prepare {
     desktop: ObjectRef,
 }
 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 down = selector(cx, &self.candidates, self.press, self.desktop)?;
         let up = selector(cx, &self.candidates, self.release, self.desktop)?;
@@ -192,6 +206,7 @@ impl NativeCallable for Prepare {
     }
 }
 /// Returned Mount owns one root. No-hit and mismatched targets return None.
+/// 解析输入所指向的实际目标，避免把包装身份与底层数据混淆。
 pub fn resolve(
     vm: &mut Vm,
     desktop: ObjectRef,