update docs

Author: skywind3000

docs/window.md

@@ -58,7 +58,7 @@ Border content is generated by `quickui#utils#make_border()` as text lines, writ
 | `mode` | Number | 0 | Lifecycle state (0=not created/closed, 1=created) |
 | `opts` | Dict | {} | Deep copy of creation options |
 | `info` | Dict | {} | Internal environment data computed during initialization |
-| `quit` | Number | 0 | Whether closed by close button (Vim only, set via callback) |
+| `quit` | Number | 0 | Whether closed by close button (Vim: set via popup callback; Neovim: set by `mouse_click()` when click lands on border window's close button) |
 
 ### `info` Dictionary Internal Fields
 
@@ -117,11 +117,13 @@ Creates and displays a window. If the window is already open, it first calls `cl
 Closes the window and releases all resources.
 
 **Behavior**:
-- Vim: Calls `popup_close()`
-- Neovim: Calls `nvim_win_close()` for both content and border windows
+- Vim: Calls `popup_close()` (wrapped in `try/catch` for safety)
+- Neovim: Calls `nvim_win_close()` for both content and border windows (each wrapped in `try/catch`)
 - Releases content buffer and border buffer (`quickui#core#buffer_free()`)
 - Resets `winid=-1`, `bid=-1`, `mode=0`, `hide=0`
 
+All window-close calls are protected by `try/catch`, so calling `close()` on an already-closed window or a window closed externally (by user action or autocmd) is safe and will not throw errors. Resource cleanup (buffer release, state reset) is always performed regardless of whether the close call succeeds.
+
 #### `win.show(show)`
 
 Controls window visibility.
@@ -215,7 +217,7 @@ Executes Ex commands in the window context.
 - If the window is open (`winid >= 0`), executes immediately via `quickui#core#win_execute()`
 - If the window is not yet shown, commands are appended to `info.pending_cmd` and automatically executed when the window is displayed
 
-This deferred execution mechanism ensures that commands set before window creation are not lost.
+Commands cached via `execute()` before `open()` are preserved across the `open()` call — they will be consumed (executed and cleared) when the window is first shown. Multiple `execute()` calls accumulate commands in order.
 
 ### Syntax Highlighting Methods
 
@@ -258,10 +260,12 @@ call win.syntax_end()
 
 Handles a mouse click event, returning the click position relative to the window content area.
 
-**Returns**: Dict `{'x': col, 'y': row}`, coordinates are 0-based. Returns `{'x': -1, 'y': -1}` if the click is not within this window.
+**Returns**: Dict `{'x': col, 'y': row}`, coordinates are 0-based. Returns `{'x': -1, 'y': -1}` if the click is not within the content window.
 
 Automatically subtracts the border offset when borders are present.
 
+**Neovim close button detection**: On Neovim, if the click lands on the border window's close button position (top-right corner) and `opts.button` is enabled, `self.quit` is set to `1`. This unifies the close button behavior across both platforms — consumers can check `win.quit` without writing platform-specific code.
+
 ### Other Methods
 
 #### `win.refresh()`
@@ -365,5 +369,7 @@ call win.syntax_end()
 2. **Coordinate system**: `x`/`y` use 0-based coordinates, but Vim's popup API uses 1-based coordinates — window.vim handles the +1 conversion internally.
 3. **Border dimensions**: `tw`/`th` is the total size including border + padding, `w`/`h` is the pure content area size. `move()`'s boundary clamping is based on `tw`/`th`.
 4. **Buffer management**: window uses `quickui#core#buffer_alloc/free` for buffer pool management. Do not manipulate buffers directly, and do not use `bid` after `close()`.
-5. **quit property**: Only effective on Vim — set to 1 via the `popup_exit` callback when the user clicks the close button. Neovim has no such mechanism.
+5. **quit property**: On Vim, set to 1 via the `popup_exit` callback when the user clicks the close button. On Neovim, set to 1 by `mouse_click()` when the click lands on the border window's close button (requires `opts.button` enabled). Consumers can check `win.quit` uniformly on both platforms.
 6. **mode property**: `0` means the window is not created or has been closed, `1` means created. Most methods return early when `mode==0`.
+7. **close() is safe to call multiple times**: All window-close operations are wrapped in `try/catch`. Calling `close()` on an already-closed window, or a window destroyed externally, will not throw — resource cleanup always runs.
+8. **Deferred execute() across open()**: Commands cached via `execute()` before `open()` survive the `open()` call and are consumed when the window is first shown.