From 13ef34685d94100a372775fda0f8bcdc46bc4daa Mon Sep 17 00:00:00 2001
From: l0ng-ai <24760907+l0ng-ai@users.noreply.github.com>
Date: Sun, 16 Aug 2026 08:11:52 +0800
Subject: [PATCH] docs(app): restore why Linux zooms the window a different way
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

    if cfg!(target_os = "linux") { window.zoom_window() }
    else { window.titlebar_double_click() }

reads like a stylistic split and is a bug fix. gpui implements
`titlebar_double_click` on macOS only — everywhere else the trait method
is an empty default, so on Linux this row swallowed the double-click and
nothing zoomed. `zoom_window` is the maximise toggle there, and what
gpui-component's own `TitleBar` calls for the same reason. Windows needs
neither: the row maps to HTCAPTION and the OS has already acted.

Nothing in the code said any of that, so the obvious tidy — collapse the
branch to the one gpui documents — silently breaks Linux again. The
branch is byte-for-byte what it was when that was written.

Also `WindowMoveArm`, whose point is *where* the flag lives rather than
what it holds, and `last_focused`, which is why switching tabs returns
to the pane you left instead of the first one.

Checked `last_focused`'s reference to `remember_active_pane` before
restoring it, on the assumption it had rotted — it has not, the function
is still there and still called from two places, and `focus_target`
still falls back to `first_leaf()` exactly as described. My first grep
said otherwise because I had truncated it.

Measured function length across the tree while here: the only
production function over 400 lines is `Tty7App::render` at 578, which is
a gpui element tree — long, linear, and not something to split while
its behaviour cannot be verified visually.
---
 src/ui/app.rs | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/ui/app.rs b/src/ui/app.rs
index 484503a6..a0bce39c 100644
--- a/src/ui/app.rs
+++ b/src/ui/app.rs
@@ -269,6 +269,14 @@ pub(crate) fn title_bar_drag(
     cx: &mut gpui::App,
 ) -> gpui::Stateful<gpui::Div> {
     window_move_gesture(row, key, window, cx).on_double_click(|_, window, _| {
+        // gpui only implements `titlebar_double_click` on macOS — the trait
+        // method is an empty default everywhere else, so on Linux this row
+        // swallowed the double-click and nothing zoomed. `zoom_window` is the
+        // maximise toggle there (x11 `_NET_WM_STATE_MAXIMIZED_*`, wayland
+        // `set_maximized`), and what gpui-component's own `TitleBar` calls on
+        // Linux for exactly this reason. Windows needs neither: the row is a
+        // drag area, which maps to HTCAPTION, and the OS has already restored
+        // or maximised the window before this could run.
         if cfg!(target_os = "linux") {
             window.zoom_window();
         } else {
@@ -277,6 +285,8 @@ pub(crate) fn title_bar_drag(
     })
 }
 
+/// The armed flag behind [`window_move_gesture`]. A single bool, but *where* it
+/// lives is the whole point — see there.
 pub(crate) struct WindowMoveArm {
     should_move: bool,
 }
@@ -341,6 +351,11 @@ pub(crate) fn window_mark() -> Option<impl IntoElement> {
 pub struct Tab {
     pub pane: Pane,
     pub name: Option<String>,
+    /// Entity id of the pane that last held focus in this tab. Recorded when we
+    /// leave the tab (see [`Tty7App::remember_active_pane`]) and restored on
+    /// return, so switching away and back keeps the active pane instead of
+    /// jumping to the first leaf. `None` for a tab never left, or after its
+    /// focused pane closed — both fall back to `first_leaf()`.
     last_focused: Option<gpui::EntityId>,
     /// The pane zoomed in this tab, stashed here by `activate` while another
     /// tab is on screen — zoom is a tab's view state, not the window's, so