docs: clarify host test observations and task wait limits

src/runtime/endor_host/tests.rs

@@ -15,6 +15,7 @@ const PAGE: &str = include_str!("../../../examples/page.endor");
 /// 可选性能基准：分别测世界 UI 和普通三维场景在 1x/2x DPI 下的相机交互更新、变更绘制和同列表缓存绘制。
 /// 默认 ignore，需在已确认的构建环境中以 release 单测试线程运行，避免其他测试干扰；下面命令仅为运行说明。
 /// cargo test --release --locked scene_interaction_performance -- --ignored --nocapture --test-threads=1
+/// 该基准只打印耗时与计数，没有性能阈值或像素正确性断言；静态复审不等于已执行基准。
 #[test]
 #[ignore]
 fn scene_interaction_performance() {
@@ -419,7 +420,7 @@ page.render(Column(0,8,Column(0,8,paragraph,tail),Column(50,8,paragraph)))
             })
             .collect();
         assert_eq!(widths, [400.0, 300.0]);
-        // 同字串加宽后的实际绘制行高和原来比较，排除仅命令宽字段被改、字形仍按旧行排的情况。
+        // 比较发布 Text 命令的 wrap_bounds 高度，验证测量/投影随宽度更新；本测试此处没有光栅化像素。
         let heights: Vec<_> = resized
             .frame
             .commands
@@ -650,6 +651,7 @@ page.render(block)
         session.execute("block.value", "app.main").unwrap().value,
         r#""updated""#
     );
+    // ui.viewport 返回对象，与 Textual.value 的 String 契约不符；此处仅断言绑定失败，没有检查失败后的订阅数量。
     assert!(
         session
             .execute("alias.bind(\"value\", ui.viewport)", "app.main")
@@ -985,15 +987,16 @@ fn file_task_state(session: &mut ReplSession) -> String {
     status
 }
 /// 最多轮询 1000 次，每轮推进任务并检查其是否离开 pending。
-/// 短暂休眠让后台文件线程获得执行机会；取消/失败也算终态，超时则明确使测试失败。
+/// 短暂休眠给后台线程执行机会；只要状态不是 pending 就返回，完成/取消/失败的具体期望由调用测试检查。
+/// 1000 是轮数上限，每轮 poll 的耗时另计；这里没有承诺总墙钟时间不超过一秒。
 fn complete_file_task(session: &mut ReplSession) {
     // 测试调用方依赖此有界等待推进后台文件结果；达到上限必须失败，不能无限挂住测试进程。
     for _ in 0..1000 {
         // 后台只填 mailbox，必须显式让 owning VM poll 才能执行回调或完成无回调 Task。
         session.poll_tasks().unwrap();
-        // 只要状态离开 pending 就交还调用方，让其按当前测试目的区分成功、取消或失败。
+        // 按非 pending 条件交还调用方，不是通用的 Task 终态判定（running 也满足此条件）。
         if file_task_state(session) != "pending" {
-            // 不只 Completed，Cancelled/Failed 也结束等待，具体预期由各调用测试单独断言。
+            // 当前文件测试随后显式断言 completed/cancelled/failed，不能仅凭本助手返回认定成功。
             return;
         }
         std::thread::sleep(std::time::Duration::from_millis(1));
@@ -1270,6 +1273,7 @@ fn orphan_task_scope_is_collectable_and_callback_failure_stops_remaining_work()
         page.render(TextBlock("preserve"))
         token=orphan()"#;
     // 加载后的回收边界应剪掉不可达 owner/作用域环，token 本身不反向强持有 owner。
+    // orphan 回调绑定主窗口而不是临时 owner，避免回调自身又强持有 owner，使本例无法观察其回收。
     let (mut session, _) = ReplSession::load(source, "app.main", 1, 192).unwrap();
     assert_eq!(
         session.execute("token.active()", "app.main").unwrap().value,