docs: clarify scene and protocol cache regression scope

src/runtime/endor_host/tests.rs

@@ -5635,7 +5635,7 @@ fn scene_viewport_example_and_scroll_view_alias_run_as_real_source() {
             "app.main",
         )
         .unwrap();
-    // 新实例仍应满足 ScrollBlock 名义类型，保证兼容原有滚动 API。
+    // 新实例满足 ScrollBlock 名义类型；本例只检查类型关系，没有挂载 testScroll 或实际调用其滚动方法。
     assert_eq!(
         session
             .execute("ui.isInstance(testScroll, ScrollBlock)", "app.main")
@@ -5908,6 +5908,7 @@ fn scene3d_example_custom_geometry_and_cycle_diagnostics_use_real_source() {
         "40"
     );
     // 在原会话替换为三个顶点、一个三角面的自定义 Geometry3D，要求产生有效新文档。
+    // 此处重设 scene.children 属性，不是在原 ObjectList 上 append/remove，不能覆盖列表内容依赖的原地编辑路径。
     session.execute(r##"
         geometry=Geometry3D(ObjectList(Vec3(-1,-1,0),Vec3(1,-1,0),Vec3(0,1,0)),ObjectList(Triangle3D(0,1,2)))
         custom=Mesh3D(geometry,"#112233")
@@ -6017,7 +6018,8 @@ fn world_ui_panel_renders_live_endor_and_ray_hits_respect_mesh_occlusion() {
             .value,
         "100"
     );
-    // 从源 Mount.toLocal 反投影屏幕中心，数值解析后应近似恢复纹理坐标 50，与 toView 互相校验。
+    // 此处 toView/toLocal 仅比较 x 分量，没有独立断言两个源 API 的 y；完整中心点另由上方原生投影检查。
+    // 从源 Mount.toLocal 反投影屏幕中心，数值解析后 x 应近似恢复纹理坐标 50。
     let local = session
         .execute("button.mounts().at(0).toLocal(100,100).x", "app.main")
         .unwrap()
@@ -6099,7 +6101,8 @@ fn world_ui_panel_renders_live_endor_and_ray_hits_respect_mesh_occlusion() {
         .iter()
         .find(|mount| mount.panel.is_some() && mount.interactive)
         .unwrap();
-    // 面板 UI 的 contains 应因遮挡失败；整帧命中回落到外层三维视口，不能穿透到按钮。
+    // 面板 UI 的 contains 应因遮挡失败；整帧命中回落到外层三维视口。
+    // 此处只查询命中与随后像素，没有再派发被遮挡 click，也没有以 count 断言该次回调被拒绝。
     assert!(!button.contains(point));
     assert!(blocked.frame.hit_test(point).unwrap().scene3d_viewport);
     // 最终像素也必须显示前景蓝盒，与命中采用同一场景深度关系。
@@ -6617,6 +6620,7 @@ fn nested_scroll_into_view_and_source_paint_share_clipped_geometry() {
     // 至少一条绘制命令带裁剪，说明嵌套滚动上下文已进入文档。
     assert!(result.frame.command_clips.iter().any(Option::is_some));
     // 对最深 last 的 Mount 请求 scrollIntoView，需要联动内、外两个祖先而非只滚最近一层。
+    // 初始帧只检查存在裁剪项；滚动后断言两层偏移和 Mount.hitTest，没有逐命令比较新 clip 或采样像素。
     session
         .execute("last.mounts().at(0).scrollIntoView()", "app.main")
         .unwrap();
@@ -6694,7 +6698,7 @@ returned = button.dispatch(dispatched)"#,
 struct VisualRedirect {
     // 下方方法替换测试指定的源实现；ContextNativeFunction 的 roots 另负责保活。
     target: ObjectRef,
-    // 对外沿用原签名，使本用例只改变实现，不借参数契约变化制造缓存失效。
+    // 保存调用方提供的契约副本；paint 替换测试沿用原签名，onEvent 测试还会显式改 effect。
     signature: endor_core::CallSignature,
 }
 impl endor_core::NativeCallable for VisualRedirect {
@@ -6718,10 +6722,10 @@ impl endor_core::NativeCallable for VisualRedirect {
 }
 
 #[test]
-/// 从同一 desktop 的第二窗口查到 Block.measure，检查原生快速路径认的是方法与注册表组合。
+/// 从同一 VM 的第二窗口 desktop 查到 Block.measure，检查原生快速路径认的是方法与注册表组合。
 /// 同函数换成 paint 名称或外来 types 表都不能被认作 intrinsic，避免只凭对象形状或方法名跳过源执行。
 fn native_visual_identity_accepts_shared_window_registries_only() {
-    // 建立同一 desktop 下的会话和第二窗口，验证窗口共享类型注册表可以使用相同原生快速路径。
+    // 第二窗口有独立 desktop，但共享同一 types 字典；验证这种共享注册身份仍可使用原生快速路径。
     let mut session = ReplSession::new(238).unwrap();
     // 真实 Window 构造注册第二窗口，不手工拼造一个看似相同的 desktop。
     session.execute("second = Window()", "app.main").unwrap();
@@ -6872,7 +6876,8 @@ fn replacing_base_visual_methods_changes_layout_and_same_identity_paint() {
 }
 
 #[test]
-/// 保持 Block.onEvent 的函数句柄不变，替换为有副作用的转发 payload。
+/// 保持 Block.onEvent 的函数句柄不变，替换转发 payload 并把签名 effect 改为 Mutating。
+/// Hooks.onEvent 本体为空且本例不派发事件，检查的是协议能力/缓存变化，不是业务副作用执行。
 /// 通过 VM changes 使 RenderCache 失效后 rect 从不交互变为交互，protocol_key 也应变化，证明缓存追踪实现版本。
 fn same_identity_event_payload_changes_invalidate_interactivity_cache() {
     // 独立会话仅构造未挂载 rect 和 Hooks，用 RenderCache 直接观察交互协议快照。