docs: clarify shell input window and host widget lifecycles

src/shell/native_chrome.rs

@@ -2,6 +2,8 @@
 //! 仅在 macOS 编译；Objective-C 交互局限在原生窗口层，不参与 Endor 布局与事件分发。
 //!
 //! Keep AppKit's real window buttons aligned with the custom tab strip.
+//! app::create_native/redraw 负责在事件循环线程调用对齐，app::window_event 的标题空白区按下路径调用双击处理。
+//! 两个入口都只临时借用 winit 持有的 NSView/NSWindow；本模块不保存原生指针，也不向 VM 发送伪造标题栏事件。
 use objc2_app_kit::{NSApplication, NSView, NSWindowButton, NSWindowStyleMask};
 use objc2_foundation::{MainThreadMarker, NSPoint, NSString, NSUserDefaults};
 use winit::{
@@ -19,9 +21,11 @@ pub fn titlebar_double_click(window: &Window) -> bool {
         return false;
     };
     let Ok(handle) = window.window_handle() else {
+        // 借用句柄失败表示当前无法可靠访问原生视图，不把它当成一次已处理的双击吞掉。
         return false;
     };
     let RawWindowHandle::AppKit(handle) = handle.as_raw() else {
+        // 只允许 AppKit 句柄进入下面 NSView 转型，其他平台句柄不具有这些 Objective-C 对象前提。
         return false;
     };
     // SAFETY: called on the event-loop thread during a left-button press, with
@@ -74,12 +78,15 @@ pub fn align_controls(window: &Window) {
     // SAFETY: winit owns this NSView for the lifetime of the borrowed Window.
     // All AppKit access is on the event-loop thread; no native pointers escape.
     unsafe {
+        // 安全前提由调用方保证：事件循环主线程、仍活着的 Window 借用，以及 winit 提供的有效 NSView；这里只短期访问。
         let view = &*handle.ns_view.as_ptr().cast::<NSView>();
         let Some(native) = view.window() else {
+            // 原生视图尚未关联窗口时无需移动控制按钮，不创建替代 NSWindow 来补齐。
             return;
         };
         // Fullscreen traffic lights belong to AppKit's separate floating toolbar.
         if native.styleMask().contains(NSWindowStyleMask::FullScreen) {
+            // 全屏按钮由 AppKit 独立工具栏管理，内容视图坐标不适合作为它们的位置来源。
             return;
         }
         // 读取内容视图边界，用与侧栏相同的 HEADER 高度确定标题行中心。