feat: add pane navigation controls

refs #421

refs #330

related discussions:

https://github.com/ogulcancelik/herdr/discussions/422

https://github.com/ogulcancelik/herdr/discussions/438

https://github.com/ogulcancelik/herdr/discussions/442

9 files changed, 1456 insertions, 51 deletions

diff --git a/src/app/actions.rs b/src/app/actions.rs
index 9bce43ed..8124be93 100644
--- a/src/app/actions.rs
+++ b/src/app/actions.rs
@@ -1371,6 +1371,41 @@ impl AppState {
         }
     }
 
+    pub fn swap_pane(&mut self, direction: NavDirection) -> bool {
+        let Some(ws_idx) = self.active else {
+            return false;
+        };
+        let Some(tab) = self.workspaces.get(ws_idx).and_then(|ws| ws.active_tab()) else {
+            return false;
+        };
+        let panes = if tab.zoomed {
+            tab.layout.panes(self.view.terminal_area)
+        } else {
+            self.view.pane_infos.clone()
+        };
+
+        let Some(focused) = panes.iter().find(|p| p.is_focused) else {
+            return false;
+        };
+        let Some(target) = find_in_direction(focused, direction, &panes) else {
+            return false;
+        };
+        let source = focused.id;
+        let Some(tab) = self
+            .workspaces
+            .get_mut(ws_idx)
+            .and_then(|ws| ws.active_tab_mut())
+        else {
+            return false;
+        };
+        if tab.layout.swap_panes(source, target) {
+            self.mark_session_dirty();
+            true
+        } else {
+            false
+        }
+    }
+
     pub fn resize_pane(&mut self, direction: NavDirection) {
         if let Some(first) = self.view.pane_infos.first() {
             let area = self
@@ -4093,6 +4128,91 @@ mod tests {
     }
 
     #[test]
+    fn swap_pane_direction_preserves_focus_and_swaps_layout_cells() {
+        let mut state = app_with_workspaces(&["test"]);
+        let root = state.workspaces[0].tabs[0].root_pane;
+        let right = state.workspaces[0].test_split(Direction::Horizontal);
+        state.workspaces[0].layout.focus_pane(root);
+        crate::ui::compute_view(&mut state, ratatui::layout::Rect::new(0, 0, 100, 20));
+        let before_root_rect = state
+            .view
+            .pane_infos
+            .iter()
+            .find(|info| info.id == root)
+            .unwrap()
+            .rect;
+        let before_right_rect = state
+            .view
+            .pane_infos
+            .iter()
+            .find(|info| info.id == right)
+            .unwrap()
+            .rect;
+
+        assert!(state.swap_pane(NavDirection::Right));
+        crate::ui::compute_view(&mut state, ratatui::layout::Rect::new(0, 0, 100, 20));
+
+        assert_eq!(state.workspaces[0].focused_pane_id(), Some(root));
+        assert_eq!(
+            state
+                .view
+                .pane_infos
+                .iter()
+                .find(|info| info.id == root)
+                .unwrap()
+                .rect,
+            before_right_rect
+        );
+        assert_eq!(
+            state
+                .view
+                .pane_infos
+                .iter()
+                .find(|info| info.id == right)
+                .unwrap()
+                .rect,
+            before_root_rect
+        );
+    }
+
+    #[test]
+    fn swap_pane_direction_stays_zoomed_and_mutates_hidden_layout() {
+        let mut state = app_with_workspaces(&["test"]);
+        let root = state.workspaces[0].tabs[0].root_pane;
+        let right = state.workspaces[0].test_split(Direction::Horizontal);
+        state.workspaces[0].layout.focus_pane(root);
+        state.workspaces[0].zoomed = true;
+        crate::ui::compute_view(&mut state, ratatui::layout::Rect::new(0, 0, 100, 20));
+
+        assert!(state.swap_pane(NavDirection::Right));
+        crate::ui::compute_view(&mut state, ratatui::layout::Rect::new(0, 0, 100, 20));
+
+        assert!(state.workspaces[0].zoomed);
+        assert_eq!(state.workspaces[0].focused_pane_id(), Some(root));
+        assert_eq!(state.view.pane_infos.len(), 1);
+        assert_eq!(state.view.pane_infos[0].id, root);
+
+        state.workspaces[0].zoomed = false;
+        crate::ui::compute_view(&mut state, ratatui::layout::Rect::new(0, 0, 100, 20));
+        let root_rect = state
+            .view
+            .pane_infos
+            .iter()
+            .find(|info| info.id == root)
+            .unwrap()
+            .rect;
+        let right_rect = state
+            .view
+            .pane_infos
+            .iter()
+            .find(|info| info.id == right)
+            .unwrap()
+            .rect;
+
+        assert!(root_rect.x > right_rect.x);
+    }
+
+    #[test]
     fn close_pane_removes_from_workspace() {
         let mut state = app_with_workspaces(&["test"]);
         state.workspaces[0].test_split(Direction::Horizontal);
diff --git a/src/app/api.rs b/src/app/api.rs
index 733fb8b8..35994bff 100644
--- a/src/app/api.rs
+++ b/src/app/api.rs
@@ -555,6 +555,14 @@ impl App {
             Method::AgentRead(params) => return self.handle_agent_read(request.id, params),
             Method::AgentSend(params) => return self.handle_agent_send(request.id, params),
             Method::PaneSplit(params) => return self.handle_pane_split(request.id, params),
+            Method::PaneSwap(params) => return self.handle_pane_swap(request.id, params),
+            Method::PaneLayout(params) => return self.handle_pane_layout(request.id, params),
+            Method::PaneNeighbor(params) => return self.handle_pane_neighbor(request.id, params),
+            Method::PaneEdges(params) => return self.handle_pane_edges(request.id, params),
+            Method::PaneFocusDirection(params) => {
+                return self.handle_pane_focus_direction(request.id, params);
+            }
+            Method::PaneResize(params) => return self.handle_pane_resize(request.id, params),
             Method::PaneList(params) => return self.handle_pane_list(request.id, params),
             Method::PaneGet(target) => return self.handle_pane_get(request.id, target),
             Method::PaneRename(params) => return self.handle_pane_rename(request.id, params),
diff --git a/src/app/api/panes.rs b/src/app/api/panes.rs
index d027f732..23272ffd 100644
--- a/src/app/api/panes.rs
+++ b/src/app/api/panes.rs
@@ -1,13 +1,18 @@
 use bytes::Bytes;
 
 use crate::api::schema::{
-    EventData, EventEnvelope, EventKind, PaneClearAgentAuthorityParams, PaneListParams,
-    PaneReadParams, PaneReadResult, PaneReleaseAgentParams, PaneRenameParams,
-    PaneReportAgentParams, PaneReportAgentSessionParams, PaneReportMetadataParams,
-    PaneSendInputParams, PaneSendKeysParams, PaneSendTextParams, PaneSplitParams, PaneTarget,
-    ReadFormat, ReadSource, ResponseResult,
+    EventData, EventEnvelope, EventKind, PaneClearAgentAuthorityParams, PaneDirection,
+    PaneEdgesParams, PaneEdgesResult, PaneFocusDirectionParams, PaneFocusDirectionReason,
+    PaneFocusDirectionResult, PaneLayoutPane, PaneLayoutParams, PaneLayoutRect, PaneLayoutSnapshot,
+    PaneLayoutSplit, PaneListParams, PaneNeighborParams, PaneNeighborResult, PaneReadParams,
+    PaneReadResult, PaneReleaseAgentParams, PaneRenameParams, PaneReportAgentParams,
+    PaneReportAgentSessionParams, PaneReportMetadataParams, PaneResizeParams, PaneResizeReason,
+    PaneResizeResult, PaneSendInputParams, PaneSendKeysParams, PaneSendTextParams, PaneSplitParams,
+    PaneSwapParams, PaneSwapReason, PaneSwapResult, PaneTarget, ReadFormat, ReadSource,
+    ResponseResult,
 };
 use crate::app::{App, Mode};
+use crate::layout::{find_in_direction, NavDirection, PaneId};
 
 use super::super::api_helpers::{
     detect_state_from_api, encode_api_keys, encode_api_text, normalize_custom_status,
@@ -17,8 +22,21 @@ use super::responses::{encode_error, encode_success};
 
 impl App {
     pub(super) fn handle_pane_split(&mut self, id: String, params: PaneSplitParams) -> String {
-        let Some((ws_idx, target_pane_id)) = self.parse_pane_id(&params.target_pane_id) else {
-            return pane_not_found(id, &params.target_pane_id);
+        let target = if let Some(target_pane_id) = params.target_pane_id.as_deref() {
+            self.parse_pane_id(target_pane_id)
+        } else if let Some(workspace_id) = params.workspace_id.as_deref() {
+            self.parse_workspace_id(workspace_id).and_then(|ws_idx| {
+                let pane_id = self.state.workspaces.get(ws_idx)?.focused_pane_id()?;
+                Some((ws_idx, pane_id))
+            })
+        } else {
+            self.state.active.and_then(|ws_idx| {
+                let pane_id = self.state.workspaces.get(ws_idx)?.focused_pane_id()?;
+                Some((ws_idx, pane_id))
+            })
+        };
+        let Some((ws_idx, target_pane_id)) = target else {
+            return encode_error(id, "pane_not_found", "pane not found");
         };
         let (rows, cols) = self.state.estimate_pane_size();
         let split_cwd = params.cwd.map(std::path::PathBuf::from).or_else(|| {
@@ -37,26 +55,42 @@ impl App {
         let host_terminal_theme = self.state.host_terminal_theme;
         let previous_focus = self.state.current_pane_focus_target();
         let Some(ws) = self.state.workspaces.get_mut(ws_idx) else {
-            return pane_not_found(id, &params.target_pane_id);
+            return encode_error(id, "pane_not_found", "pane not found");
         };
         let direction = match params.direction {
             crate::api::schema::SplitDirection::Right => ratatui::layout::Direction::Horizontal,
             crate::api::schema::SplitDirection::Down => ratatui::layout::Direction::Vertical,
         };
-        let (target_tab_idx, new_pane) = match ws.split_pane(
-            target_pane_id,
-            direction,
-            rows,
-            cols,
-            split_cwd,
-            scrollback_limit_bytes,
-            host_terminal_theme,
-            crate::pane::PaneShellConfig::new(&default_shell, self.state.shell_mode),
-            params.focus,
-        ) {
+        let shell_config = crate::pane::PaneShellConfig::new(&default_shell, self.state.shell_mode);
+        let split_result = match params.ratio {
+            Some(ratio) => ws.split_pane_with_ratio(
+                target_pane_id,
+                direction,
+                ratio,
+                rows,
+                cols,
+                split_cwd,
+                scrollback_limit_bytes,
+                host_terminal_theme,
+                shell_config,
+                params.focus,
+            ),
+            None => ws.split_pane(
+                target_pane_id,
+                direction,
+                rows,
+                cols,
+                split_cwd,
+                scrollback_limit_bytes,
+                host_terminal_theme,
+                shell_config,
+                params.focus,
+            ),
+        };
+        let (target_tab_idx, new_pane) = match split_result {
             Some(Ok(result)) => result,
             Some(Err(err)) => return encode_error(id, "pane_split_failed", err.to_string()),
-            None => return pane_not_found(id, &params.target_pane_id),
+            None => return encode_error(id, "pane_not_found", "pane not found"),
         };
         if params.focus {
             self.state.switch_workspace_tab(ws_idx, target_tab_idx);
@@ -99,6 +133,390 @@ impl App {
         encode_success(id, ResponseResult::PaneInfo { pane })
     }
 
+    pub(super) fn handle_pane_layout(&mut self, id: String, params: PaneLayoutParams) -> String {
+        let Some((ws_idx, pane_id)) = self.resolve_optional_pane(params.pane_id.as_deref()) else {
+            return encode_error(id, "pane_not_found", "pane not found");
+        };
+        let Some(tab_idx) = self.state.workspaces[ws_idx].find_tab_index_for_pane(pane_id) else {
+            return pane_not_found(
+                id,
+                &self.public_pane_id(ws_idx, pane_id).unwrap_or_default(),
+            );
+        };
+        let Some(layout) = self.pane_layout_snapshot(ws_idx, tab_idx) else {
+            return encode_error(id, "pane_layout_unavailable", "pane layout unavailable");
+        };
+
+        encode_success(id, ResponseResult::PaneLayout { layout })
+    }
+
+    pub(super) fn handle_pane_neighbor(
+        &mut self,
+        id: String,
+        params: PaneNeighborParams,
+    ) -> String {
+        let Some((ws_idx, pane_id)) = self.resolve_optional_pane(params.pane_id.as_deref()) else {
+            return encode_error(id, "pane_not_found", "pane not found");
+        };
+        let Some(tab_idx) = self.state.workspaces[ws_idx].find_tab_index_for_pane(pane_id) else {
+            return pane_not_found(
+                id,
+                &self.public_pane_id(ws_idx, pane_id).unwrap_or_default(),
+            );
+        };
+        let Some(source_public_id) = self.public_pane_id(ws_idx, pane_id) else {
+            return encode_error(id, "pane_not_found", "pane not found");
+        };
+        let neighbor_pane_id = self
+            .directional_pane_target(ws_idx, tab_idx, pane_id, params.direction)
+            .and_then(|pane_id| self.public_pane_id(ws_idx, pane_id));
+        let Some(layout) = self.pane_layout_snapshot(ws_idx, tab_idx) else {
+            return encode_error(id, "pane_layout_unavailable", "pane layout unavailable");
+        };
+
+        encode_success(
+            id,
+            ResponseResult::PaneNeighbor {
+                neighbor: PaneNeighborResult {
+                    pane_id: source_public_id,
+                    direction: params.direction,
+                    neighbor_pane_id,
+                    layout,
+                },
+            },
+        )
+    }
+
+    pub(super) fn handle_pane_edges(&mut self, id: String, params: PaneEdgesParams) -> String {
+        let Some((ws_idx, pane_id)) = self.resolve_optional_pane(params.pane_id.as_deref()) else {
+            return encode_error(id, "pane_not_found", "pane not found");
+        };
+        let Some(tab_idx) = self.state.workspaces[ws_idx].find_tab_index_for_pane(pane_id) else {
+            return pane_not_found(
+                id,
+                &self.public_pane_id(ws_idx, pane_id).unwrap_or_default(),
+            );
+        };
+        let Some(tab) = self
+            .state
+            .workspaces
+            .get(ws_idx)
+            .and_then(|ws| ws.tabs.get(tab_idx))
+        else {
+            return encode_error(id, "pane_layout_unavailable", "pane layout unavailable");
+        };
+        let area = self.state.view.terminal_area;
+        let Some(info) = tab
+            .layout
+            .panes(area)
+            .into_iter()
+            .find(|info| info.id == pane_id)
+        else {
+            return pane_not_found(
+                id,
+                &self.public_pane_id(ws_idx, pane_id).unwrap_or_default(),
+            );
+        };
+        let Some(pane_public_id) = self.public_pane_id(ws_idx, pane_id) else {
+            return encode_error(id, "pane_not_found", "pane not found");
+        };
+        let Some(layout) = self.pane_layout_snapshot(ws_idx, tab_idx) else {
+            return encode_error(id, "pane_layout_unavailable", "pane layout unavailable");
+        };
+
+        encode_success(
+            id,
+            ResponseResult::PaneEdges {
+                edges: PaneEdgesResult {
+                    pane_id: pane_public_id,
+                    left: info.rect.x <= area.x,
+                    right: info.rect.x + info.rect.width >= area.x + area.width,
+                    up: info.rect.y <= area.y,
+                    down: info.rect.y + info.rect.height >= area.y + area.height,
+                    layout,
+                },
+            },
+        )
+    }
+
+    pub(super) fn handle_pane_focus_direction(
+        &mut self,
+        id: String,
+        params: PaneFocusDirectionParams,
+    ) -> String {
+        let Some((ws_idx, source_pane_id)) = self.resolve_optional_pane(params.pane_id.as_deref())
+        else {
+            return encode_error(id, "pane_not_found", "pane not found");
+        };
+        let Some(tab_idx) = self.state.workspaces[ws_idx].find_tab_index_for_pane(source_pane_id)
+        else {
+            return pane_not_found(
+                id,
+                &self
+                    .public_pane_id(ws_idx, source_pane_id)
+                    .unwrap_or_default(),
+            );
+        };
+        let Some(source_public_id) = self.public_pane_id(ws_idx, source_pane_id) else {
+            return encode_error(id, "pane_not_found", "pane not found");
+        };
+        let target =
+            self.directional_pane_target(ws_idx, tab_idx, source_pane_id, params.direction);
+        let reason = target
+            .is_none()
+            .then_some(PaneFocusDirectionReason::NoNeighbor);
+
+        if let Some(target_pane_id) = target {
+            self.state.focus_pane_in_workspace(ws_idx, target_pane_id);
+            self.state.switch_workspace_tab(ws_idx, tab_idx);
+            self.state.mode = Mode::Terminal;
+        }
+        let focused_pane_id = self
+            .state
+            .workspaces
+            .get(ws_idx)
+            .and_then(|ws| ws.tabs.get(tab_idx))
+            .map(|tab| tab.layout.focused())
+            .and_then(|pane_id| self.public_pane_id(ws_idx, pane_id));
+        let Some(layout) = self.pane_layout_snapshot(ws_idx, tab_idx) else {
+            return encode_error(id, "pane_layout_unavailable", "pane layout unavailable");
+        };
+
+        encode_success(
+            id,
+            ResponseResult::PaneFocusDirection {
+                focus: PaneFocusDirectionResult {
+                    changed: target.is_some(),
+                    reason,
+                    source_pane_id: source_public_id,
+                    focused_pane_id,
+                    layout,
+                },
+            },
+        )
+    }
+
+    pub(super) fn handle_pane_resize(&mut self, id: String, params: PaneResizeParams) -> String {
+        let Some((ws_idx, pane_id)) = self.resolve_optional_pane(params.pane_id.as_deref()) else {
+            return encode_error(id, "pane_not_found", "pane not found");
+        };
+        let Some(tab_idx) = self.state.workspaces[ws_idx].find_tab_index_for_pane(pane_id) else {
+            return pane_not_found(
+                id,
+                &self.public_pane_id(ws_idx, pane_id).unwrap_or_default(),
+            );
+        };
+        let Some(pane_public_id) = self.public_pane_id(ws_idx, pane_id) else {
+            return encode_error(id, "pane_not_found", "pane not found");
+        };
+
+        let amount = params
+            .amount
+            .filter(|amount| amount.is_finite())
+            .unwrap_or(0.05)
+            .abs()
+            .min(0.5);
+        let direction: NavDirection = params.direction.into();
+        let area = self.state.view.terminal_area;
+        let changed = self
+            .state
+            .workspaces
+            .get_mut(ws_idx)
+            .and_then(|ws| ws.tabs.get_mut(tab_idx))
+            .is_some_and(|tab| tab.layout.resize_pane(pane_id, direction, amount, area));
+        if changed {
+            self.schedule_session_save();
+        }
+
+        let Some(layout) = self.pane_layout_snapshot(ws_idx, tab_idx) else {
+            return encode_error(id, "pane_layout_unavailable", "pane layout unavailable");
+        };
+        let focused_pane_id = layout.focused_pane_id.clone();
+
+        encode_success(
+            id,
+            ResponseResult::PaneResize {
+                resize: PaneResizeResult {
+                    changed,
+                    reason: (!changed).then_some(PaneResizeReason::Unchanged),
+                    pane_id: pane_public_id,
+                    focused_pane_id,
+                    layout,
+                },
+            },
+        )
+    }
+
+    pub(super) fn handle_pane_swap(&mut self, id: String, params: PaneSwapParams) -> String {
+        let directional = params.direction.is_some();
+        let explicit = params.source_pane_id.is_some() || params.target_pane_id.is_some();
+        if directional == explicit {
+            return encode_error(
+                id,
+                "invalid_pane_swap",
+                "provide either direction with optional pane_id, or source_pane_id and target_pane_id",
+            );
+        }
+
+        let (ws_idx, tab_idx, source_pane_id, target_pane_id, reason) = if let Some(direction) =
+            params.direction
+        {
+            let Some((ws_idx, source_pane_id)) =
+                self.resolve_swap_source(params.pane_id.as_deref())
+            else {
+                return encode_error(id, "pane_not_found", "source pane not found");
+            };
+            let Some(tab_idx) =
+                self.state.workspaces[ws_idx].find_tab_index_for_pane(source_pane_id)
+            else {
+                return pane_not_found(
+                    id,
+                    &self
+                        .public_pane_id(ws_idx, source_pane_id)
+                        .unwrap_or_default(),
+                );
+            };
+            let target = self.directional_pane_target(ws_idx, tab_idx, source_pane_id, direction);
+            match target {
+                Some(target_pane_id) => {
+                    (ws_idx, tab_idx, source_pane_id, Some(target_pane_id), None)
+                }
+                None => (
+                    ws_idx,
+                    tab_idx,
+                    source_pane_id,
+                    None,
+                    Some(PaneSwapReason::NoNeighbor),
+                ),
+            }
+        } else {
+            let Some(source_raw) = params.source_pane_id.as_deref() else {
+                return encode_error(id, "invalid_pane_swap", "missing source_pane_id");
+            };
+            let Some(target_raw) = params.target_pane_id.as_deref() else {
+                return encode_error(id, "invalid_pane_swap", "missing target_pane_id");
+            };
+            let source = self
+                .parse_pane_id(source_raw)
+                .and_then(|(ws_idx, pane_id)| {
+                    let tab_idx = self.state.workspaces[ws_idx].find_tab_index_for_pane(pane_id)?;
+                    Some((ws_idx, tab_idx, pane_id))
+                });
+            let target = self
+                .parse_pane_id(target_raw)
+                .and_then(|(ws_idx, pane_id)| {
+                    let tab_idx = self.state.workspaces[ws_idx].find_tab_index_for_pane(pane_id)?;
+                    Some((ws_idx, tab_idx, pane_id))
+                });
+            let response_context = source
+                .map(|(ws_idx, tab_idx, _)| (ws_idx, tab_idx))
+                .or_else(|| target.map(|(ws_idx, tab_idx, _)| (ws_idx, tab_idx)))
+                .or_else(|| {
+                    let ws_idx = self.state.active?;
+                    let tab_idx = self.state.workspaces.get(ws_idx)?.active_tab_index();
+                    Some((ws_idx, tab_idx))
+                });
+            let Some((ws_idx, tab_idx)) = response_context else {
+                return encode_error(id, "pane_layout_unavailable", "pane layout unavailable");
+            };
+            let source_pane_id = source
+                .map(|(_, _, pane_id)| pane_id)
+                .or_else(|| {
+                    self.state
+                        .workspaces
+                        .get(ws_idx)?
+                        .tabs
+                        .get(tab_idx)
+                        .map(|tab| tab.layout.focused())
+                })
+                .unwrap_or(PaneId::from_raw(0));
+            let target_pane_id = target.map(|(_, _, pane_id)| pane_id);
+            let reason = match (source, target) {
+                (None, _) | (_, None) => Some(PaneSwapReason::NotFound),
+                (Some((_, _, source)), Some((_, _, target))) if source == target => {
+                    Some(PaneSwapReason::SamePane)
+                }
+                (Some((source_ws, source_tab, _)), Some((target_ws, target_tab, _)))
+                    if source_ws != target_ws || source_tab != target_tab =>
+                {
+                    Some(PaneSwapReason::CrossTab)
+                }
+                _ => None,
+            };
+            (ws_idx, tab_idx, source_pane_id, target_pane_id, reason)
+        };
+
+        let mut changed = false;
+        if reason.is_none() {
+            if let Some(target_pane_id) = target_pane_id {
+                let previous_focus = self.state.current_pane_focus_target();
+                if let Some(tab) = self
+                    .state
+                    .workspaces
+                    .get_mut(ws_idx)
+                    .and_then(|ws| ws.tabs.get_mut(tab_idx))
+                {
+                    changed = tab.layout.swap_panes(source_pane_id, target_pane_id);
+                    tab.layout.focus_pane(source_pane_id);
+                    if changed {
+                        self.state.switch_workspace_tab(ws_idx, tab_idx);
+                        self.state
+                            .record_pane_focus_change(previous_focus, ws_idx, source_pane_id);
+                        self.state.mark_session_dirty();
+                        self.schedule_session_save();
+                    }
+                }
+            }
+        }
+
+        let source_public_id = match params.source_pane_id {
+            Some(raw) => self
+                .parse_pane_id(&raw)
+                .and_then(|(idx, pane_id)| {
+                    self.state
+                        .workspaces
+                        .get(idx)?
+                        .find_tab_index_for_pane(pane_id)?;
+                    self.public_pane_id(idx, pane_id)
+                })
+                .unwrap_or(raw),
+            None => self
+                .public_pane_id(ws_idx, source_pane_id)
+                .unwrap_or_default(),
+        };
+        let target_public_id = match params.target_pane_id {
+            Some(raw) => self
+                .parse_pane_id(&raw)
+                .and_then(|(idx, pane_id)| {
+                    self.state
+                        .workspaces
+                        .get(idx)?
+                        .find_tab_index_for_pane(pane_id)?;
+                    self.public_pane_id(idx, pane_id)
+                })
+                .or(Some(raw)),
+            None => target_pane_id.and_then(|pane_id| self.public_pane_id(ws_idx, pane_id)),
+        };
+        let Some(layout) = self.pane_layout_snapshot(ws_idx, tab_idx) else {
+            return encode_error(id, "pane_layout_unavailable", "pane layout unavailable");
+        };
+        let focused_pane_id = layout.focused_pane_id.clone();
+
+        encode_success(
+            id,
+            ResponseResult::PaneSwap {
+                swap: PaneSwapResult {
+                    changed,
+                    reason,
+                    source_pane_id: source_public_id,
+                    target_pane_id: target_public_id,
+                    focused_pane_id,
+                    layout,
+                },
+            },
+        )
+    }
+
     pub(super) fn handle_pane_rename(&mut self, id: String, params: PaneRenameParams) -> String {
         let Some((ws_idx, pane_id)) = self.parse_pane_id(&params.pane_id) else {
             return pane_not_found(id, &params.pane_id);
@@ -526,6 +944,118 @@ fn pane_not_found(id: String, pane_id: &str) -> String {
     encode_error(id, "pane_not_found", format!("pane {pane_id} not found"))
 }
 
+impl App {
+    fn resolve_optional_pane(&self, pane_id: Option<&str>) -> Option<(usize, PaneId)> {
+        match pane_id {
+            Some(pane_id) => self.parse_pane_id(pane_id),
+            None => {
+                let ws_idx = self.state.active?;
+                let pane_id = self.state.workspaces.get(ws_idx)?.focused_pane_id()?;
+                Some((ws_idx, pane_id))
+            }
+        }
+    }
+
+    fn resolve_swap_source(&self, pane_id: Option<&str>) -> Option<(usize, PaneId)> {
+        self.resolve_optional_pane(pane_id)
+    }
+
+    fn directional_pane_target(
+        &self,
+        ws_idx: usize,
+        tab_idx: usize,
+        source_pane_id: PaneId,
+        direction: PaneDirection,
+    ) -> Option<PaneId> {
+        let tab = self.state.workspaces.get(ws_idx)?.tabs.get(tab_idx)?;
+        let panes = tab.layout.panes(self.state.view.terminal_area);
+        let source = panes.iter().find(|pane| pane.id == source_pane_id)?;
+        find_in_direction(source, direction.into(), &panes)
+    }
+
+    fn pane_layout_snapshot(&self, ws_idx: usize, tab_idx: usize) -> Option<PaneLayoutSnapshot> {
+        let ws = self.state.workspaces.get(ws_idx)?;
+        let tab = ws.tabs.get(tab_idx)?;
+        let area = self.state.view.terminal_area;
+        let focused_pane_id = self.public_pane_id(ws_idx, tab.layout.focused())?;
+        let panes = tab
+            .layout
+            .panes(area)
+            .into_iter()
+            .filter_map(|pane| {
+                Some(PaneLayoutPane {
+                    pane_id: self.public_pane_id(ws_idx, pane.id)?,
+                    focused: pane.is_focused,
+                    rect: pane.rect.into(),
+                })
+            })
+            .collect();
+        let splits = tab
+            .layout
+            .splits(area)
+            .into_iter()
+            .enumerate()
+            .map(|(idx, split)| PaneLayoutSplit {
+                id: split_path_id(idx, &split.path),
+                direction: match split.direction {
+                    ratatui::layout::Direction::Horizontal => {
+                        crate::api::schema::SplitDirection::Right
+                    }
+                    ratatui::layout::Direction::Vertical => {
+                        crate::api::schema::SplitDirection::Down
+                    }
+                },
+                ratio: split.ratio,
+                rect: split.area.into(),
+            })
+            .collect();
+
+        Some(PaneLayoutSnapshot {
+            workspace_id: self.public_workspace_id(ws_idx),
+            tab_id: self.public_tab_id(ws_idx, tab_idx)?,
+            zoomed: tab.zoomed,
+            area: area.into(),
+            focused_pane_id,
+            panes,
+            splits,
+        })
+    }
+}
+
+impl From<PaneDirection> for NavDirection {
+    fn from(direction: PaneDirection) -> Self {
+        match direction {
+            PaneDirection::Left => NavDirection::Left,
+            PaneDirection::Right => NavDirection::Right,
+            PaneDirection::Up => NavDirection::Up,
+            PaneDirection::Down => NavDirection::Down,
+        }
+    }
+}
+
+impl From<ratatui::layout::Rect> for PaneLayoutRect {
+    fn from(rect: ratatui::layout::Rect) -> Self {
+        Self {
+            x: rect.x,
+            y: rect.y,
+            width: rect.width,
+            height: rect.height,
+        }
+    }
+}
+
+fn split_path_id(idx: usize, path: &[bool]) -> String {
+    if path.is_empty() {
+        return format!("split_{idx}_root");
+    }
+    let path = path
+        .iter()
+        .map(|right| if *right { "1" } else { "0" })
+        .collect::<Vec<_>>()
+        .join("");
+    format!("split_{idx}_{path}")
+}
+
 fn invalid_agent(id: String) -> String {
     encode_error(id, "invalid_agent", "agent label must not be empty")
 }
@@ -573,4 +1103,354 @@ mod tests {
         assert_eq!(app.state.request_remove_linked_worktree, None);
         assert!(app.state.workspaces.is_empty());
     }
+
+    #[test]
+    fn api_pane_swap_explicit_source_and_target_preserves_focus_and_returns_layout() {
+        let mut app = app_with_linked_worktree();
+        let source = app.state.workspaces[0].tabs[0].root_pane;
+        let target = app.state.workspaces[0].test_split(ratatui::layout::Direction::Horizontal);
+        app.state.workspaces[0].tabs[0].layout.focus_pane(source);
+        crate::ui::compute_view(&mut app.state, ratatui::layout::Rect::new(0, 0, 100, 20));
+        let source_public = app.public_pane_id(0, source).unwrap();
+        let target_public = app.public_pane_id(0, target).unwrap();
+
+        let response = app.handle_pane_swap(
+            "req".into(),
+            PaneSwapParams {
+                source_pane_id: Some(source_public.clone()),
+                target_pane_id: Some(target_public.clone()),
+                ..PaneSwapParams::default()
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneSwap { swap } = success.result else {
+            panic!("expected pane swap response");
+        };
+        assert!(swap.changed);
+        assert_eq!(swap.reason, None);
+        assert_eq!(swap.source_pane_id, source_public);
+        assert_eq!(swap.target_pane_id, Some(target_public));
+        assert_eq!(swap.focused_pane_id, swap.source_pane_id);
+        assert_eq!(swap.layout.focused_pane_id, swap.source_pane_id);
+        assert_eq!(swap.layout.panes.len(), 2);
+        assert_eq!(app.state.workspaces[0].focused_pane_id(), Some(source));
+    }
+
+    #[test]
+    fn api_pane_swap_unfocused_source_updates_last_pane_history() {
+        let mut app = app_with_linked_worktree();
+        let source = app.state.workspaces[0].tabs[0].root_pane;
+        let focused = app.state.workspaces[0].test_split(ratatui::layout::Direction::Horizontal);
+        let target = app.state.workspaces[0].test_split(ratatui::layout::Direction::Vertical);
+        app.state.active = Some(0);
+        app.state.selected = 0;
+        app.state.workspaces[0].tabs[0].layout.focus_pane(focused);
+        crate::ui::compute_view(&mut app.state, ratatui::layout::Rect::new(0, 0, 100, 20));
+        let source_public = app.public_pane_id(0, source).unwrap();
+        let target_public = app.public_pane_id(0, target).unwrap();
+
+        let response = app.handle_pane_swap(
+            "req".into(),
+            PaneSwapParams {
+                source_pane_id: Some(source_public),
+                target_pane_id: Some(target_public),
+                ..PaneSwapParams::default()
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneSwap { swap } = success.result else {
+            panic!("expected pane swap response");
+        };
+        assert!(swap.changed);
+        assert_eq!(app.state.workspaces[0].focused_pane_id(), Some(source));
+
+        app.state.last_pane();
+
+        assert_eq!(app.state.workspaces[0].focused_pane_id(), Some(focused));
+    }
+
+    #[test]
+    fn api_pane_swap_direction_no_neighbor_returns_unchanged_layout() {
+        let mut app = app_with_linked_worktree();
+        let source = app.state.workspaces[0].tabs[0].root_pane;
+        app.state.workspaces[0].tabs[0].layout.focus_pane(source);
+        crate::ui::compute_view(&mut app.state, ratatui::layout::Rect::new(0, 0, 100, 20));
+        let source_public = app.public_pane_id(0, source).unwrap();
+
+        let response = app.handle_pane_swap(
+            "req".into(),
+            PaneSwapParams {
+                pane_id: Some(source_public.clone()),
+                direction: Some(PaneDirection::Left),
+                ..PaneSwapParams::default()
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneSwap { swap } = success.result else {
+            panic!("expected pane swap response");
+        };
+        assert!(!swap.changed);
+        assert_eq!(swap.reason, Some(PaneSwapReason::NoNeighbor));
+        assert_eq!(swap.source_pane_id, source_public);
+        assert_eq!(swap.target_pane_id, None);
+        assert_eq!(swap.layout.panes.len(), 1);
+    }
+
+    #[test]
+    fn api_pane_swap_explicit_missing_target_returns_not_found_noop() {
+        let mut app = app_with_linked_worktree();
+        let source = app.state.workspaces[0].tabs[0].root_pane;
+        let source_public = app.public_pane_id(0, source).unwrap();
+
+        let response = app.handle_pane_swap(
+            "req".into(),
+            PaneSwapParams {
+                source_pane_id: Some(source_public.clone()),
+                target_pane_id: Some("missing-pane".into()),
+                ..PaneSwapParams::default()
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneSwap { swap } = success.result else {
+            panic!("expected pane swap response");
+        };
+        assert!(!swap.changed);
+        assert_eq!(swap.reason, Some(PaneSwapReason::NotFound));
+        assert_eq!(swap.source_pane_id, source_public);
+        assert_eq!(swap.target_pane_id, Some("missing-pane".into()));
+        assert_eq!(swap.layout.panes.len(), 1);
+    }
+
+    #[test]
+    fn api_pane_swap_explicit_missing_source_returns_not_found_noop() {
+        let mut app = app_with_linked_worktree();
+        let target = app.state.workspaces[0].tabs[0].root_pane;
+        let target_public = app.public_pane_id(0, target).unwrap();
+
+        let response = app.handle_pane_swap(
+            "req".into(),
+            PaneSwapParams {
+                source_pane_id: Some("missing-pane".into()),
+                target_pane_id: Some(target_public.clone()),
+                ..PaneSwapParams::default()
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneSwap { swap } = success.result else {
+            panic!("expected pane swap response");
+        };
+        assert!(!swap.changed);
+        assert_eq!(swap.reason, Some(PaneSwapReason::NotFound));
+        assert_eq!(swap.source_pane_id, "missing-pane");
+        assert_eq!(swap.target_pane_id, Some(target_public));
+        assert_eq!(swap.layout.panes.len(), 1);
+    }
+
+    #[test]
+    fn api_pane_swap_explicit_cross_workspace_preserves_target_id() {
+        let mut app = app_with_linked_worktree();
+        app.state.workspaces.push(Workspace::test_new("other"));
+        let source = app.state.workspaces[0].tabs[0].root_pane;
+        let target = app.state.workspaces[1].tabs[0].root_pane;
+        let source_public = app.public_pane_id(0, source).unwrap();
+        let target_public = app.public_pane_id(1, target).unwrap();
+
+        let response = app.handle_pane_swap(
+            "req".into(),
+            PaneSwapParams {
+                source_pane_id: Some(source_public.clone()),
+                target_pane_id: Some(target_public.clone()),
+                ..PaneSwapParams::default()
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneSwap { swap } = success.result else {
+            panic!("expected pane swap response");
+        };
+        assert!(!swap.changed);
+        assert_eq!(swap.reason, Some(PaneSwapReason::CrossTab));
+        assert_eq!(swap.source_pane_id, source_public);
+        assert_eq!(swap.target_pane_id, Some(target_public));
+        assert_eq!(swap.layout.workspace_id, app.public_workspace_id(0));
+    }
+
+    #[test]
+    fn api_pane_layout_returns_public_ids_rects_and_splits() {
+        let mut app = app_with_linked_worktree();
+        let root = app.state.workspaces[0].tabs[0].root_pane;
+        let right = app.state.workspaces[0].test_split(ratatui::layout::Direction::Horizontal);
+        app.state.workspaces[0].tabs[0].layout.focus_pane(root);
+        crate::ui::compute_view(&mut app.state, ratatui::layout::Rect::new(0, 0, 100, 20));
+        let root_public = app.public_pane_id(0, root).unwrap();
+        let right_public = app.public_pane_id(0, right).unwrap();
+
+        let response = app.handle_pane_layout(
+            "req".into(),
+            crate::api::schema::PaneLayoutParams {
+                pane_id: Some(root_public.clone()),
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneLayout { layout } = success.result else {
+            panic!("expected pane layout response");
+        };
+        assert_eq!(layout.focused_pane_id, root_public);
+        assert!(layout.panes.iter().any(|pane| pane.pane_id == root_public));
+        assert!(layout.panes.iter().any(|pane| pane.pane_id == right_public));
+        assert_eq!(layout.splits.len(), 1);
+        assert_eq!(
+            layout.splits[0].direction,
+            crate::api::schema::SplitDirection::Right
+        );
+    }
+
+    #[test]
+    fn api_pane_neighbor_returns_directional_neighbor_public_id() {
+        let mut app = app_with_linked_worktree();
+        let root = app.state.workspaces[0].tabs[0].root_pane;
+        let right = app.state.workspaces[0].test_split(ratatui::layout::Direction::Horizontal);
+        app.state.workspaces[0].tabs[0].layout.focus_pane(root);
+        crate::ui::compute_view(&mut app.state, ratatui::layout::Rect::new(0, 0, 100, 20));
+        let root_public = app.public_pane_id(0, root).unwrap();
+        let right_public = app.public_pane_id(0, right).unwrap();
+
+        let response = app.handle_pane_neighbor(
+            "req".into(),
+            crate::api::schema::PaneNeighborParams {
+                pane_id: Some(root_public.clone()),
+                direction: PaneDirection::Right,
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneNeighbor { neighbor } = success.result else {
+            panic!("expected pane neighbor response");
+        };
+        assert_eq!(neighbor.pane_id, root_public);
+        assert_eq!(neighbor.direction, PaneDirection::Right);
+        assert_eq!(neighbor.neighbor_pane_id, Some(right_public));
+    }
+
+    #[test]
+    fn api_pane_edges_reports_physical_layout_edges() {
+        let mut app = app_with_linked_worktree();
+        let root = app.state.workspaces[0].tabs[0].root_pane;
+        let right = app.state.workspaces[0].test_split(ratatui::layout::Direction::Horizontal);
+        app.state.workspaces[0].tabs[0].layout.focus_pane(root);
+        crate::ui::compute_view(&mut app.state, ratatui::layout::Rect::new(0, 0, 100, 20));
+        let right_public = app.public_pane_id(0, right).unwrap();
+
+        let response = app.handle_pane_edges(
+            "req".into(),
+            crate::api::schema::PaneEdgesParams {
+                pane_id: Some(right_public.clone()),
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneEdges { edges } = success.result else {
+            panic!("expected pane edges response");
+        };
+        assert_eq!(edges.pane_id, right_public);
+        assert!(!edges.left);
+        assert!(edges.right);
+        assert!(edges.up);
+        assert!(edges.down);
+    }
+
+    #[test]
+    fn api_pane_resize_changes_target_ratio_without_changing_focus() {
+        let mut app = app_with_linked_worktree();
+        let root = app.state.workspaces[0].tabs[0].root_pane;
+        let right = app.state.workspaces[0].test_split(ratatui::layout::Direction::Horizontal);
+        app.state.workspaces[0].tabs[0].layout.focus_pane(right);
+        crate::ui::compute_view(&mut app.state, ratatui::layout::Rect::new(0, 0, 100, 20));
+        let root_public = app.public_pane_id(0, root).unwrap();
+        let right_public = app.public_pane_id(0, right).unwrap();
+
+        let response = app.handle_pane_resize(
+            "req".into(),
+            crate::api::schema::PaneResizeParams {
+                pane_id: Some(root_public.clone()),
+                direction: PaneDirection::Right,
+                amount: Some(0.1),
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneResize { resize } = success.result else {
+            panic!("expected pane resize response");
+        };
+        assert!(resize.changed);
+        assert_eq!(resize.reason, None);
+        assert_eq!(resize.pane_id, root_public);
+        assert_eq!(resize.focused_pane_id, right_public);
+        assert_eq!(resize.layout.focused_pane_id, right_public);
+        assert!((resize.layout.splits[0].ratio - 0.6).abs() < f32::EPSILON);
+        assert_eq!(app.state.workspaces[0].focused_pane_id(), Some(right));
+    }
+
+    #[test]
+    fn api_pane_focus_direction_focuses_neighbor() {
+        let mut app = app_with_linked_worktree();
+        let root = app.state.workspaces[0].tabs[0].root_pane;
+        let right = app.state.workspaces[0].test_split(ratatui::layout::Direction::Horizontal);
+        app.state.workspaces[0].tabs[0].layout.focus_pane(root);
+        crate::ui::compute_view(&mut app.state, ratatui::layout::Rect::new(0, 0, 100, 20));
+        let root_public = app.public_pane_id(0, root).unwrap();
+        let right_public = app.public_pane_id(0, right).unwrap();
+
+        let response = app.handle_pane_focus_direction(
+            "req".into(),
+            crate::api::schema::PaneFocusDirectionParams {
+                pane_id: Some(root_public.clone()),
+                direction: PaneDirection::Right,
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneFocusDirection { focus } = success.result else {
+            panic!("expected pane focus direction response");
+        };
+        assert!(focus.changed);
+        assert_eq!(focus.reason, None);
+        assert_eq!(focus.source_pane_id, root_public);
+        assert_eq!(focus.focused_pane_id, Some(right_public.clone()));
+        assert_eq!(focus.layout.focused_pane_id, right_public);
+        assert_eq!(app.state.workspaces[0].focused_pane_id(), Some(right));
+    }
+
+    #[test]
+    fn api_pane_focus_direction_no_neighbor_is_noop() {
+        let mut app = app_with_linked_worktree();
+        let root = app.state.workspaces[0].tabs[0].root_pane;
+        app.state.workspaces[0].tabs[0].layout.focus_pane(root);
+        crate::ui::compute_view(&mut app.state, ratatui::layout::Rect::new(0, 0, 100, 20));
+        let root_public = app.public_pane_id(0, root).unwrap();
+
+        let response = app.handle_pane_focus_direction(
+            "req".into(),
+            crate::api::schema::PaneFocusDirectionParams {
+                pane_id: Some(root_public.clone()),
+                direction: PaneDirection::Left,
+            },
+        );
+
+        let success: SuccessResponse = serde_json::from_str(&response).unwrap();
+        let ResponseResult::PaneFocusDirection { focus } = success.result else {
+            panic!("expected pane focus direction response");
+        };
+        assert!(!focus.changed);
+        assert_eq!(focus.reason, Some(PaneFocusDirectionReason::NoNeighbor));
+        assert_eq!(focus.source_pane_id, root_public.clone());
+        assert_eq!(focus.focused_pane_id, Some(root_public));
+        assert_eq!(app.state.workspaces[0].focused_pane_id(), Some(root));
+    }
 }
diff --git a/src/app/input/modal.rs b/src/app/input/modal.rs
index 334b008e..5b179e9b 100644
--- a/src/app/input/modal.rs
+++ b/src/app/input/modal.rs
@@ -722,33 +722,111 @@ pub(super) fn apply_context_menu_action(
         (ContextMenuKind::Pane { pane_id, .. }, Some("Rename pane")) => {
             open_rename_pane(state, pane_id);
         }
-        (ContextMenuKind::Pane { pane_id, .. }, Some("Clear pane name")) => {
-            if let Some(ws_idx) = state.active {
-                if let Some(ws) = state.workspaces.get(ws_idx) {
-                    if let Some(pane) = ws.pane_state(pane_id) {
-                        let terminal_id = pane.attached_terminal_id.clone();
-                        if let Some(terminal) = state.terminals.get_mut(&terminal_id) {
-                            terminal.clear_manual_label();
-                            state.mark_session_dirty();
-                        }
+        (
+            ContextMenuKind::Pane {
+                ws_idx, pane_id, ..
+            },
+            Some("Clear pane name"),
+        ) => {
+            if let Some(ws) = state.workspaces.get(ws_idx) {
+                if let Some(pane) = ws.pane_state(pane_id) {
+                    let terminal_id = pane.attached_terminal_id.clone();
+                    if let Some(terminal) = state.terminals.get_mut(&terminal_id) {
+                        terminal.clear_manual_label();
+                        state.mark_session_dirty();
                     }
                 }
             }
             state.mode = Mode::Terminal;
         }
-        (ContextMenuKind::Pane { .. }, Some("Split vertical")) => {
+        (
+            ContextMenuKind::Pane {
+                ws_idx,
+                tab_idx,
+                pane_id,
+                source_pane_id,
+                ..
+            },
+            Some("Swap with focused pane"),
+        ) => {
+            if let Some(source_pane_id) = source_pane_id {
+                state.selected = ws_idx;
+                state.active = Some(ws_idx);
+                state.switch_tab(tab_idx);
+                if let Some(tab) = state
+                    .workspaces
+                    .get_mut(ws_idx)
+                    .and_then(|ws| ws.tabs.get_mut(tab_idx))
+                {
+                    if tab.layout.swap_panes(source_pane_id, pane_id) {
+                        tab.layout.focus_pane(source_pane_id);
+                        state.mark_session_dirty();
+                    }
+                }
+            }
+            state.mode = Mode::Terminal;
+        }
+        (
+            ContextMenuKind::Pane {
+                ws_idx,
+                tab_idx,
+                pane_id,
+                ..
+            },
+            Some("Split right"),
+        ) => {
+            state.selected = ws_idx;
+            state.active = Some(ws_idx);
+            state.switch_tab(tab_idx);
+            state.focus_pane_in_workspace(ws_idx, pane_id);
             state.split_pane(terminal_runtimes, Direction::Horizontal);
             state.mode = Mode::Terminal;
         }
-        (ContextMenuKind::Pane { .. }, Some("Split horizontal")) => {
+        (
+            ContextMenuKind::Pane {
+                ws_idx,
+                tab_idx,
+                pane_id,
+                ..
+            },
+            Some("Split down"),
+        ) => {
+            state.selected = ws_idx;
+            state.active = Some(ws_idx);
+            state.switch_tab(tab_idx);
+            state.focus_pane_in_workspace(ws_idx, pane_id);
             state.split_pane(terminal_runtimes, Direction::Vertical);
             state.mode = Mode::Terminal;
         }
-        (ContextMenuKind::Pane { .. }, Some("Zoom")) => {
+        (
+            ContextMenuKind::Pane {
+                ws_idx,
+                tab_idx,
+                pane_id,
+                ..
+            },
+            Some("Zoom"),
+        ) => {
+            state.selected = ws_idx;
+            state.active = Some(ws_idx);
+            state.switch_tab(tab_idx);
+            state.focus_pane_in_workspace(ws_idx, pane_id);
             state.toggle_zoom();
             state.mode = Mode::Terminal;
         }
-        (ContextMenuKind::Pane { .. }, Some("Close pane")) => {
+        (
+            ContextMenuKind::Pane {
+                ws_idx,
+                tab_idx,
+                pane_id,
+                ..
+            },
+            Some("Close pane"),
+        ) => {
+            state.selected = ws_idx;
+            state.active = Some(ws_idx);
+            state.switch_tab(tab_idx);
+            state.focus_pane_in_workspace(ws_idx, pane_id);
             if !state.close_pane() {
                 state.mode = if state.active.is_some() {
                     Mode::Terminal
@@ -1301,7 +1379,10 @@ mod tests {
         let pane_id = state.workspaces[0].tabs[0].root_pane;
         let menu = ContextMenuState {
             kind: ContextMenuKind::Pane {
+                ws_idx: 0,
+                tab_idx: 0,
                 pane_id,
+                source_pane_id: None,
                 has_manual_label: false,
             },
             x: 0,
diff --git a/src/app/input/mouse.rs b/src/app/input/mouse.rs
index 51a9763e..9272c279 100644
--- a/src/app/input/mouse.rs
+++ b/src/app/input/mouse.rs
@@ -950,7 +950,6 @@ impl AppState {
                 if let (Some(ws_idx), Some(tab_idx)) =
                     (self.active, self.tab_at(mouse.column, mouse.row))
                 {
-                    self.switch_tab(tab_idx);
                     self.context_menu = Some(ContextMenuState {
                         kind: ContextMenuKind::Tab { ws_idx, tab_idx },
                         x: mouse.column,
@@ -963,17 +962,30 @@ impl AppState {
 
             MouseEventKind::Down(MouseButton::Right) if !in_sidebar => {
                 if let Some(info) = self.pane_mouse_target(mouse.column, mouse.row).cloned() {
-                    self.focus_pane(info.id);
+                    let ws_idx = self.active?;
+                    let tab_idx = self
+                        .workspaces
+                        .get(ws_idx)
+                        .map(|ws| ws.active_tab_index())?;
+                    let previous_focused_pane_id = self
+                        .workspaces
+                        .get(ws_idx)
+                        .and_then(|ws| ws.focused_pane_id());
+                    let source_pane_id =
+                        previous_focused_pane_id.filter(|pane_id| *pane_id != info.id);
                     let has_manual_label = self
-                        .active
-                        .and_then(|ws_idx| self.workspaces.get(ws_idx))
+                        .workspaces
+                        .get(ws_idx)
                         .and_then(|ws| ws.pane_state(info.id))
                         .and_then(|pane| self.terminals.get(&pane.attached_terminal_id))
                         .and_then(|terminal| terminal.manual_label.as_ref())
                         .is_some();
                     self.context_menu = Some(ContextMenuState {
                         kind: ContextMenuKind::Pane {
+                            ws_idx,
+                            tab_idx,
                             pane_id: info.id,
+                            source_pane_id,
                             has_manual_label,
                         },
                         x: mouse.column,
@@ -1997,6 +2009,90 @@ mod tests {
     }
 
     #[tokio::test]
+    async fn pane_right_click_keeps_focus_and_swap_menu_swaps_with_focused_pane() {
+        let mut app = app_for_mouse_test();
+        let mut ws = Workspace::test_new("test");
+        let source = ws.tabs[0].root_pane;
+        let target = ws.test_split(Direction::Horizontal);
+        ws.tabs[0].layout.focus_pane(source);
+        app.state.workspaces = vec![ws];
+        app.state.active = Some(0);
+        app.state.selected = 0;
+        app.state.mode = Mode::Terminal;
+        crate::ui::compute_view(&mut app.state, Rect::new(0, 0, 100, 20));
+        let target_info = app
+            .state
+            .view
+            .pane_infos
+            .iter()
+            .find(|info| info.id == target)
+            .expect("target pane info")
+            .clone();
+        let source_rect_before = app
+            .state
+            .view
+            .pane_infos
+            .iter()
+            .find(|info| info.id == source)
+            .expect("source pane info")
+            .rect;
+        let target_rect_before = target_info.rect;
+
+        app.handle_mouse(mouse(
+            MouseEventKind::Down(MouseButton::Right),
+            target_info.inner_rect.x,
+            target_info.inner_rect.y,
+        ));
+
+        assert_eq!(app.state.workspaces[0].focused_pane_id(), Some(source));
+        let menu = app.state.context_menu.as_mut().expect("pane context menu");
+        assert!(matches!(
+            menu.kind,
+            ContextMenuKind::Pane {
+                pane_id,
+                source_pane_id: Some(source_pane_id),
+                ..
+            } if pane_id == target && source_pane_id == source
+        ));
+        let swap_idx = menu
+            .items()
+            .iter()
+            .position(|item| *item == "Swap with focused pane")
+            .expect("swap item");
+        menu.list.highlighted = swap_idx;
+
+        handle_context_menu_key(
+            &mut app.state,
+            &mut app.terminal_runtimes,
+            KeyEvent::new(KeyCode::Enter, KeyModifiers::empty()),
+        );
+        crate::ui::compute_view(&mut app.state, Rect::new(0, 0, 100, 20));
+
+        assert_eq!(app.state.mode, Mode::Terminal);
+        assert_eq!(app.state.workspaces[0].focused_pane_id(), Some(source));
+        assert_eq!(
+            app.state
+                .view
+                .pane_infos
+                .iter()
+                .find(|info| info.id == source)
+                .unwrap()
+                .rect,
+            target_rect_before
+        );
+        assert_eq!(
+            app.state
+                .view
+                .pane_infos
+                .iter()
+                .find(|info| info.id == target)
+                .unwrap()
+                .rect,
+            source_rect_before
+        );
+    }
+
+    #[tokio::test]
     async fn right_click_passthrough_requires_exact_modifier_match() {
         let mut app = app_for_mouse_test();
         let mut ws = Workspace::test_new("test");
@@ -2446,7 +2542,10 @@ mod tests {
         let runtime_count = app.terminal_runtimes.len();
         app.state.context_menu = Some(ContextMenuState {
             kind: ContextMenuKind::Pane {
+                ws_idx: 0,
+                tab_idx: 0,
                 pane_id,
+                source_pane_id: None,
                 has_manual_label: false,
             },
             x: 2,
@@ -2796,6 +2895,37 @@ mod tests {
     }
 
     #[test]
+    fn right_click_inactive_tab_opens_menu_without_switching_tabs() {
+        let mut app = app_for_mouse_test();
+        let mut ws = Workspace::test_new("one");
+        ws.test_add_tab(Some("two"));
+        app.state.workspaces = vec![ws];
+        app.state.active = Some(0);
+        app.state.selected = 0;
+        app.state.mode = Mode::Terminal;
+
+        crate::ui::compute_view(&mut app.state, Rect::new(0, 0, 106, 20));
+        let second_tab = app.state.view.tab_hit_areas[1];
+
+        app.handle_mouse(mouse(
+            MouseEventKind::Down(MouseButton::Right),
+            second_tab.x + 1,
+            second_tab.y,
+        ));
+
+        assert_eq!(app.state.workspaces[0].active_tab, 0);
+        let menu = app.state.context_menu.as_ref().expect("tab context menu");
+        assert_eq!(
+            menu.kind,
+            ContextMenuKind::Tab {
+                ws_idx: 0,
+                tab_idx: 1
+            }
+        );
+        assert_eq!(app.state.mode, Mode::ContextMenu);
+    }
+
+    #[test]
     fn wheel_over_overflowing_tab_bar_switches_tabs() {
         let mut app = app_for_mouse_test();
         let mut ws = Workspace::test_new("one");
diff --git a/src/app/input/navigate.rs b/src/app/input/navigate.rs
index 2ac86aeb..7f803825 100644
--- a/src/app/input/navigate.rs
+++ b/src/app/input/navigate.rs
@@ -499,6 +499,10 @@ pub(crate) enum NavigateAction {
     FocusPaneDown,
     FocusPaneUp,
     FocusPaneRight,
+    SwapPaneLeft,
+    SwapPaneDown,
+    SwapPaneUp,
+    SwapPaneRight,
     SplitVertical,
     SplitHorizontal,
     ClosePane,
@@ -601,6 +605,10 @@ fn action_for_key(
         (&kb.focus_pane_down, NavigateAction::FocusPaneDown),
         (&kb.focus_pane_up, NavigateAction::FocusPaneUp),
         (&kb.focus_pane_right, NavigateAction::FocusPaneRight),
+        (&kb.swap_pane_left, NavigateAction::SwapPaneLeft),
+        (&kb.swap_pane_down, NavigateAction::SwapPaneDown),
+        (&kb.swap_pane_up, NavigateAction::SwapPaneUp),
+        (&kb.swap_pane_right, NavigateAction::SwapPaneRight),
         (&kb.last_pane, NavigateAction::LastPane),
         (&kb.cycle_pane_next, NavigateAction::CyclePaneNext),
         (&kb.cycle_pane_previous, NavigateAction::CyclePanePrevious),
@@ -778,6 +786,22 @@ pub(super) fn execute_navigate_action_in_context(
         NavigateAction::FocusPaneDown => state.navigate_pane(NavDirection::Down),
         NavigateAction::FocusPaneUp => state.navigate_pane(NavDirection::Up),
         NavigateAction::FocusPaneRight => state.navigate_pane(NavDirection::Right),
+        NavigateAction::SwapPaneLeft => {
+            state.swap_pane(NavDirection::Left);
+            leave_navigate_mode(state);
+        }
+        NavigateAction::SwapPaneDown => {
+            state.swap_pane(NavDirection::Down);
+            leave_navigate_mode(state);
+        }
+        NavigateAction::SwapPaneUp => {
+            state.swap_pane(NavDirection::Up);
+            leave_navigate_mode(state);
+        }
+        NavigateAction::SwapPaneRight => {
+            state.swap_pane(NavDirection::Right);
+            leave_navigate_mode(state);
+        }
         NavigateAction::SplitVertical => {
             state.split_pane(terminal_runtimes, Direction::Horizontal);
             leave_navigate_mode(state);
@@ -1501,6 +1525,19 @@ navigate_pane_right = "ctrl+l"
     }
 
     #[test]
+    fn terminal_direct_swap_pane_shortcut_maps_to_navigation_action() {
+        let mut state = state_with_workspaces(&["test"]);
+        state.keybinds.swap_pane_right = crate::config::ActionKeybinds::direct("alt+shift+l");
+
+        let action = terminal_direct_navigation_action(
+            &state,
+            TerminalKey::new(KeyCode::Char('l'), KeyModifiers::ALT | KeyModifiers::SHIFT),
+        );
+
+        assert_eq!(action, Some(NavigateAction::SwapPaneRight));
+    }
+
+    #[test]
     fn terminal_direct_last_pane_shortcut_maps_to_navigation_action() {
         let mut state = state_with_workspaces(&["test"]);
         state.keybinds.last_pane = crate::config::ActionKeybinds::direct("alt+l");
@@ -1788,11 +1825,11 @@ last_pane = "prefix+tab"
     #[test]
     fn modified_navigate_local_key_can_be_bound_as_prefix_rhs() {
         let mut state = state_with_workspaces(&["test"]);
-        state.keybinds.toggle_sidebar = crate::config::ActionKeybinds::prefix("shift+h");
+        state.keybinds.toggle_sidebar = crate::config::ActionKeybinds::prefix("shift+u");
 
         handle_navigate_key(
             &mut state,
-            KeyEvent::new(KeyCode::Char('H'), KeyModifiers::SHIFT),
+            KeyEvent::new(KeyCode::Char('U'), KeyModifiers::SHIFT),
         );
 
         assert!(state.sidebar_collapsed);
diff --git a/src/app/input/terminal.rs b/src/app/input/terminal.rs
index 99ae3bf1..c60a9f48 100644
--- a/src/app/input/terminal.rs
+++ b/src/app/input/terminal.rs
@@ -652,7 +652,7 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn clicking_unfocused_pane_with_mouse_reporting_focuses_it_via_right_button() {
+    async fn right_clicking_unfocused_mouse_reporting_pane_keeps_focus_for_context_menu() {
         let mut app = app_for_mouse_test();
         let mut ws = Workspace::test_new("test");
         let first_pane = ws.tabs[0].root_pane;
@@ -702,12 +702,10 @@ mod tests {
             second_info.inner_rect.y + 2,
         ));
 
-        assert_eq!(
-            app.state.workspaces[0].tabs[0].layout.focused(),
-            second_pane
-        );
+        assert_eq!(app.state.workspaces[0].tabs[0].layout.focused(), first_pane);
         assert_eq!(app.state.mode, Mode::ContextMenu);
-        assert!(app.state.context_menu.is_some());
+        let menu = app.state.context_menu.as_ref().expect("pane context menu");
+        assert!(menu.items().contains(&"Swap with focused pane"));
     }
 
     #[tokio::test]
diff --git a/src/app/mod.rs b/src/app/mod.rs
index 1914c895..a9408736 100644
--- a/src/app/mod.rs
+++ b/src/app/mod.rs
@@ -2590,12 +2590,40 @@ mod tests {
                 crate::api::schema::WorktreeCreateParams::default(),
             ),
         };
+        let pane_swap = crate::api::schema::Request {
+            id: "req_6".into(),
+            method: crate::api::schema::Method::PaneSwap(crate::api::schema::PaneSwapParams {
+                pane_id: Some("w_1-1".into()),
+                direction: Some(crate::api::schema::PaneDirection::Right),
+                ..crate::api::schema::PaneSwapParams::default()
+            }),
+        };
+        let pane_focus_direction = crate::api::schema::Request {
+            id: "req_7".into(),
+            method: crate::api::schema::Method::PaneFocusDirection(
+                crate::api::schema::PaneFocusDirectionParams {
+                    pane_id: Some("w_1-1".into()),
+                    direction: crate::api::schema::PaneDirection::Right,
+                },
+            ),
+        };
+        let pane_resize = crate::api::schema::Request {
+            id: "req_8".into(),
+            method: crate::api::schema::Method::PaneResize(crate::api::schema::PaneResizeParams {
+                pane_id: Some("w_1-1".into()),
+                direction: crate::api::schema::PaneDirection::Right,
+                amount: Some(0.05),
+            }),
+        };
 
         assert!(!crate::api::request_changes_ui(&read_only));
         assert!(!crate::api::request_changes_ui(&worktree_list));
         assert!(crate::api::request_changes_ui(&mutating));
         assert!(crate::api::request_changes_ui(&pane_rename));
         assert!(crate::api::request_changes_ui(&worktree_create));
+        assert!(crate::api::request_changes_ui(&pane_swap));
+        assert!(crate::api::request_changes_ui(&pane_focus_direction));
+        assert!(crate::api::request_changes_ui(&pane_resize));
     }
 
     #[test]
@@ -2936,8 +2964,9 @@ mod tests {
             id: "req_pane_split_background_tab".into(),
             method: crate::api::schema::Method::PaneSplit(crate::api::schema::PaneSplitParams {
                 workspace_id: None,
-                target_pane_id,
+                target_pane_id: Some(target_pane_id),
                 direction: crate::api::schema::SplitDirection::Right,
+                ratio: None,
                 cwd: None,
                 focus: false,
             }),
@@ -3014,8 +3043,9 @@ mod tests {
             id: "req_pane_split_focus_background_tab".into(),
             method: crate::api::schema::Method::PaneSplit(crate::api::schema::PaneSplitParams {
                 workspace_id: None,
-                target_pane_id,
+                target_pane_id: Some(target_pane_id),
                 direction: crate::api::schema::SplitDirection::Right,
+                ratio: None,
                 cwd: None,
                 focus: true,
             }),
@@ -3039,6 +3069,97 @@ mod tests {
     }
 
     #[tokio::test]
+    async fn pane_split_request_applies_ratio() {
+        let _guard = config_env_lock().lock().unwrap();
+        let original_shell = std::env::var_os("SHELL");
+        std::env::set_var("SHELL", "/usr/bin/true");
+
+        let mut app = test_app();
+        let workspace = Workspace::test_new("api-pane-split-ratio");
+        let target_pane = workspace.tabs[0].root_pane;
+        app.state.workspaces = vec![workspace];
+        app.state.ensure_test_terminals();
+        app.state.active = Some(0);
+        app.state.selected = 0;
+
+        let target_pane_id = app.pane_info(0, target_pane).unwrap().pane_id;
+
+        let response = app.handle_api_request(crate::api::schema::Request {
+            id: "req_pane_split_ratio".into(),
+            method: crate::api::schema::Method::PaneSplit(crate::api::schema::PaneSplitParams {
+                workspace_id: None,
+                target_pane_id: Some(target_pane_id),
+                direction: crate::api::schema::SplitDirection::Right,
+                ratio: Some(0.333),
+                cwd: None,
+                focus: false,
+            }),
+        });
+        let response: serde_json::Value = serde_json::from_str(&response).unwrap();
+
+        assert_eq!(response["result"]["type"], "pane_info");
+        let splits = app.state.workspaces[0].tabs[0]
+            .layout
+            .splits(ratatui::layout::Rect::new(0, 0, 100, 20));
+        assert_eq!(splits.len(), 1);
+        assert!((splits[0].ratio - 0.333).abs() < f32::EPSILON);
+
+        let runtimes: Vec<_> = app.terminal_runtimes.drain().collect();
+        for (_terminal_id, runtime) in runtimes {
+            runtime.shutdown();
+        }
+        match original_shell {
+            Some(value) => std::env::set_var("SHELL", value),
+            None => std::env::remove_var("SHELL"),
+        }
+    }
+
+    #[tokio::test]
+    async fn pane_split_request_uses_active_focused_pane_when_target_is_omitted() {
+        let _guard = config_env_lock().lock().unwrap();
+        let original_shell = std::env::var_os("SHELL");
+        std::env::set_var("SHELL", "/usr/bin/true");
+
+        let mut app = test_app();
+        let workspace = Workspace::test_new("api-pane-split-current");
+        let target_pane = workspace.tabs[0].root_pane;
+        app.state.workspaces = vec![workspace];
+        app.state.ensure_test_terminals();
+        app.state.active = Some(0);
+        app.state.selected = 0;
+        app.state.focus_pane_in_workspace(0, target_pane);
+
+        let response = app.handle_api_request(crate::api::schema::Request {
+            id: "req_pane_split_current".into(),
+            method: crate::api::schema::Method::PaneSplit(crate::api::schema::PaneSplitParams {
+                workspace_id: None,
+                target_pane_id: None,
+                direction: crate::api::schema::SplitDirection::Right,
+                ratio: None,
+                cwd: None,
+                focus: false,
+            }),
+        });
+        let response: serde_json::Value = serde_json::from_str(&response).unwrap();
+
+        assert_eq!(response["result"]["type"], "pane_info");
+        assert_eq!(app.state.workspaces[0].tabs[0].layout.pane_count(), 2);
+        assert_eq!(
+            app.state.workspaces[0].tabs[0].layout.focused(),
+            target_pane
+        );
+
+        let runtimes: Vec<_> = app.terminal_runtimes.drain().collect();
+        for (_terminal_id, runtime) in runtimes {
+            runtime.shutdown();
+        }
+        match original_shell {
+            Some(value) => std::env::set_var("SHELL", value),
+            None => std::env::remove_var("SHELL"),
+        }
+    }
+
+    #[tokio::test]
     async fn focused_agent_start_records_previous_pane() {
         let mut app = test_app();
         let workspace = Workspace::test_new("agent-start-focus");
diff --git a/src/app/state.rs b/src/app/state.rs
index a25c7c5e..e06fb3f5 100644
--- a/src/app/state.rs
+++ b/src/app/state.rs
@@ -1052,7 +1052,10 @@ pub enum ContextMenuKind {
         tab_idx: usize,
     },
     Pane {
+        ws_idx: usize,
+        tab_idx: usize,
         pane_id: PaneId,
+        source_pane_id: Option<PaneId>,
         has_manual_label: bool,
     },
 }
@@ -1105,22 +1108,49 @@ impl ContextMenuState {
             ContextMenuKind::Tab { .. } => &["New tab", "Rename", "Close"],
             ContextMenuKind::Pane {
                 has_manual_label: true,
+                source_pane_id: Some(_),
+                ..
+            } => &[
+                "Rename pane",
+                "Clear pane name",
+                "Swap with focused pane",
+                "Split right",
+                "Split down",
+                "Zoom",
+                "Close pane",
+            ],
+            ContextMenuKind::Pane {
+                has_manual_label: false,
+                source_pane_id: Some(_),
+                ..
+            } => &[
+                "Rename pane",
+                "Swap with focused pane",
+                "Split right",
+                "Split down",
+                "Zoom",
+                "Close pane",
+            ],
+            ContextMenuKind::Pane {
+                has_manual_label: true,
+                source_pane_id: None,
                 ..
             } => &[
                 "Rename pane",
                 "Clear pane name",
-                "Split vertical",
-                "Split horizontal",
+                "Split right",
+                "Split down",
                 "Zoom",
                 "Close pane",
             ],
             ContextMenuKind::Pane {
                 has_manual_label: false,
+                source_pane_id: None,
                 ..
             } => &[
                 "Rename pane",
-                "Split vertical",
-                "Split horizontal",
+                "Split right",
+                "Split down",
                 "Zoom",
                 "Close pane",
             ],