mnml-rs 0.2.14

//! The terminal frontend: raw-mode / alt-screen / mouse-capture setup, the
//! crossterm event loop, and the shared key/mouse dispatchers (`dispatch_key` /
//! `dispatch_mouse`) that the headless+IPC loop also calls — so headless behavior
//! matches the real UI.

pub mod chord;
pub mod handlers;
pub mod mouse;
pub use chord::{CHORD_CHAIN_TIMEOUT_MS, dispatch_chord_chain, tick_chord_chain};
use handlers::overlay::{
    handle_git_section_commit_key, handle_glyph_builder_key, handle_help_overlay_key,
    handle_integration_edit_key, handle_picker_key, handle_prompt_key, handle_search_section_key,
    handle_settings_overlay_key,
};
use handlers::pane::{handle_pane_key, handle_tree_key};
pub(crate) use mouse::coalesce_scroll;
pub use mouse::dispatch_mouse;

use std::io::{self, Stdout};
use std::time::{Duration, Instant};

use ratatui::Terminal;
use ratatui::backend::CrosstermBackend;
use ratatui::crossterm::cursor::SetCursorStyle;
use ratatui::crossterm::event::{
    self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEvent, KeyEventKind,
    KeyModifiers, KeyboardEnhancementFlags, PopKeyboardEnhancementFlags,
    PushKeyboardEnhancementFlags,
};
use ratatui::crossterm::execute;
use ratatui::crossterm::terminal::{
    EnterAlternateScreen, LeaveAlternateScreen, SetTitle, disable_raw_mode, enable_raw_mode,
    supports_keyboard_enhancement,
};

use crate::app::App;
use crate::focus::Focus;
use crate::ipc::{self, Ipc};
use crate::pane::Pane;
use crate::ui;

/// Drain queued OS notifications from `app.pending_os_notifications`
/// and emit each as an OSC 9 + OSC 777 escape sequence (with an
/// optional BEL for sound). Ghostty / iTerm2 / kitty / WezTerm
/// route these to native OS notification banners; other
/// terminals silently consume the sequence.
fn emit_pending_os_notifications(
    app: &mut App,
    backend: &mut CrosstermBackend<Stdout>,
) -> io::Result<()> {
    use ratatui::crossterm::style::Print;
    for (title, body, sound) in app.take_pending_os_notifications() {
        // OSC 9 — the de facto standard used by iTerm2 (and now
        // Ghostty, WezTerm, kitty, Windows Terminal). Body-only.
        let osc9 = format!("\x1b]9;{title}: {body}\x07");
        // OSC 777 — xterm / gnome-terminal / older kitty format.
        // Takes title + body separately.
        let osc777 = format!("\x1b]777;notify;{title};{body}\x07");
        let bel = if sound { "\x07" } else { "" };
        let _ = execute!(backend, Print(osc9), Print(osc777), Print(bel));
    }
    Ok(())
}

/// Run the terminal UI. `Ok(true)` ⇒ exit for a rebuild+relaunch (the `run.sh`
/// wrapper watches for that); `Ok(false)` ⇒ normal quit.
pub fn run(mut app: App) -> Result<bool, String> {
    // Workspace basename for the terminal-window title — picks up the
    // current project name so multiple mnml tabs are distinguishable
    // ("mnml — mnml", "mnml — work", …).
    let title = match app.workspace.file_name().and_then(|s| s.to_str()) {
        Some(name) if !name.is_empty() => format!("mnml — {name}"),
        _ => "mnml".to_string(),
    };
    let blink = app.config.editor.cursor_blink;
    let mut term =
        setup_terminal(&title, blink).map_err(|e| format!("terminal setup failed: {e}"))?;
    let result = run_loop(&mut term, &mut app);
    let _ = restore_terminal(&mut term);
    result
        .map(|()| app.restart_requested)
        .map_err(|e| format!("{e}"))
}

fn setup_terminal(
    title: &str,
    cursor_blink: bool,
) -> io::Result<Terminal<CrosstermBackend<Stdout>>> {
    enable_raw_mode()?;
    let mut out = io::stdout();
    // mouse-round-9 SEV-3 2026-07-11 — was hardcoded SteadyBar.
    let cursor_style = if cursor_blink {
        SetCursorStyle::BlinkingBar
    } else {
        SetCursorStyle::SteadyBar
    };
    if let Err(e) = execute!(
        out,
        EnterAlternateScreen,
        EnableMouseCapture,
        // Enable all-motion mouse events (?1003h) so hover-without-button
        // generates `MouseEventKind::Moved`. crossterm's `EnableMouseCapture`
        // only turns on button + drag tracking by default. Needed for the
        // statusline chip tooltips.
        ratatui::crossterm::style::Print("\x1b[?1003h"),
        // Enable bracketed paste (?2004h) so external file drops arrive
        // as `Event::Paste(text)` instead of typed-through characters.
        // Powers external drag-and-drop (#7).
        ratatui::crossterm::event::EnableBracketedPaste,
        cursor_style,
        // OSC 0/2 — sets the terminal window/tab title.
        SetTitle(title),
    ) {
        let _ = disable_raw_mode();
        return Err(e);
    }
    // Ask for the kitty keyboard protocol so chords the legacy encoding can't
    // express — `Ctrl+Shift+P`, `Ctrl+I` vs `Tab`, etc. — come through distinctly.
    // No-op on terminals that don't support it.
    if supports_keyboard_enhancement().unwrap_or(false) {
        let _ = execute!(
            out,
            PushKeyboardEnhancementFlags(KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES)
        );
    }
    Terminal::new(CrosstermBackend::new(out)).inspect_err(|_| {
        let _ = disable_raw_mode();
    })
}

fn restore_terminal(term: &mut Terminal<CrosstermBackend<Stdout>>) -> io::Result<()> {
    if supports_keyboard_enhancement().unwrap_or(false) {
        let _ = execute!(term.backend_mut(), PopKeyboardEnhancementFlags);
    }
    disable_raw_mode()?;
    execute!(
        term.backend_mut(),
        LeaveAlternateScreen,
        // Pair with the ?1003h we set in setup_terminal so the host terminal
        // returns to standard tracking.
        ratatui::crossterm::style::Print("\x1b[?1003l"),
        DisableMouseCapture,
        // Pair with the EnableBracketedPaste we sent — otherwise the host
        // shell keeps receiving \e[200~/\e[201~ markers around every paste,
        // breaking clipboard paste after mnml exits.
        ratatui::crossterm::event::DisableBracketedPaste,
        SetCursorStyle::DefaultUserShape
    )?;
    term.show_cursor()?;
    Ok(())
}

fn run_loop(term: &mut Terminal<CrosstermBackend<Stdout>>, app: &mut App) -> io::Result<()> {
    // The interactive loop also speaks the file-IPC channel (so `./run.sh restart`,
    // E2E driving, and "agent inspects the live UI" work against the real terminal,
    // not just headless). Best-effort: if the workspace fs is read-only, skip it.
    let mut ipc = Ipc::init(&app.workspace).ok();
    if let Some(ipc) = ipc.as_mut() {
        let (w, h) = term.size().map(|s| (s.width, s.height)).unwrap_or((0, 0));
        ipc.append_event(&format!(
            "{{\"event\":\"start\",\"mode\":\"tui\",\"cols\":{w},\"rows\":{h}}}"
        ));
    }

    app.run_startup_tasks();
    // Background now-playing poller for the statusline miniplayer —
    // real terminal loop only (headless / e2e skip it).
    app.start_now_playing_poller();

    // 2026-07-29 — IPC dump throttle bookkeeping. See the block
    // near the dump call for rationale.
    let mut last_ipc_dump: Option<Instant> = None;

    loop {
        let frame_start = std::time::Instant::now();
        app.tick();
        // Chord-chain timeout — fires the pending fallback (if any)
        // when the user pauses past `CHORD_CHAIN_TIMEOUT_MS`. Must run
        // every frame regardless of redraw so a dangling prefix
        // doesn't sit forever after the user gives up.
        tick_chord_chain(app);
        if app.redraw_requested {
            app.redraw_requested = false;
            // Force a fresh paint over a cleared buffer (an external process
            // can leave the terminal in any state).
            term.clear()?;
        }
        term.draw(|f| ui::draw(f, app))?;
        // 2026-07-19 — record frame duration RIGHT after the draw
        // completes. The previous recording point was at the bottom
        // of the loop AFTER `event::poll(120ms)`, which included
        // the idle poll wait as "frame time" — the stress meter
        // was pinned red on any idle session (user report). Now
        // it measures the actual tick+draw work.
        app.record_frame_duration(frame_start.elapsed().as_millis());
        emit_pending_os_notifications(app, term.backend_mut())?;
        crate::app::dispatch::emit_image_placements(app);
        if let Some(ipc) = ipc.as_mut() {
            // 2026-07-29 — throttle the IPC screen/status/rects
            // dump to ~10 Hz. Previously ran on every tick — at 40ms
            // (Pty-open cadence) that's 75 sync disk writes/sec just
            // for IPC introspection. On a macOS system with any I/O
            // pressure this added noticeable typing lag. IPC
            // consumers (headless test drivers, click-audit scripts)
            // don't need more than ~10 fps of ground truth.
            // COMMAND draining still runs every tick so keystrokes /
            // IPC commands stay instant — only the DUMPS are throttled.
            const IPC_DUMP_MIN_MS: u128 = 100;
            if last_ipc_dump
                .map(|t: Instant| t.elapsed().as_millis() >= IPC_DUMP_MIN_MS)
                .unwrap_or(true)
            {
                ipc::dump_screen_status(ipc, term.current_buffer_mut(), app);
                last_ipc_dump = Some(Instant::now());
            }
            ipc::drain_commands(ipc, app);
            ipc::drain_plugin_events(ipc, app);
        }
        if app.should_quit {
            app.save_session_on_quit();
            break;
        }
        // Poll faster while a pty is open so streaming output stays smooth.
        // DAP sessions also need fast polling so stopped/output events
        // surface promptly.
        let timeout = Duration::from_millis(
            if app.has_pty_pane() || app.has_pending_ai() || app.dap.is_some() {
                40
            } else {
                120
            },
        );
        if event::poll(timeout)? {
            match event::read()? {
                Event::Key(k) if k.kind != KeyEventKind::Release => dispatch_key(app, k),
                Event::Mouse(m) => {
                    // Wheel coalescing: when the read event is a
                    // ScrollUp/ScrollDown, drain every other
                    // immediately-available scroll event of the
                    // same direction from crossterm's queue, sum
                    // them, dispatch ONE batched scroll. Fixes
                    // post-release over-scroll — macOS produces
                    // 30+ events per spin; without this they queue
                    // and keep applying for ~2s after release.
                    if let Some(batched) = coalesce_scroll(&m)? {
                        dispatch_mouse(app, batched);
                    } else {
                        dispatch_mouse(app, m);
                    }
                    // code-reviewer W-2 2026-06-28: coalesce_scroll
                    // may have read a non-scroll event from the
                    // queue while looking for more wheel events.
                    // Drain the stash so the click/key isn't lost.
                    if let Some(leftover) = mouse::take_coalesce_leftover() {
                        match leftover {
                            Event::Key(k) if k.kind != KeyEventKind::Release => {
                                dispatch_key(app, k)
                            }
                            Event::Mouse(m) => dispatch_mouse(app, m),
                            _ => {}
                        }
                    }
                }
                Event::Resize(_, _) => {}
                Event::Paste(text) => {
                    // Priority 0 — modal overlay open: paste routes
                    // to the overlay's focused text field. Covers
                    // Ctrl+V AND drag-drop from Finder (terminals
                    // translate a drop into a bracketed-paste of the
                    // dropped path). 2026-07-11 user request.
                    if app.glyph_builder.is_some() {
                        let cleaned = text
                            .trim()
                            .trim_matches(|c| c == '\'' || c == '"')
                            .to_string();
                        if let Some(s) = app.glyph_builder.as_mut() {
                            s.insert_str(&cleaned);
                        }
                        continue;
                    }
                    if app.integration_edit.is_some() {
                        // integration_edit_paste reads the clipboard
                        // rather than the event's text — synthesize by
                        // setting the clipboard and calling it. Trim
                        // there too.
                        app.clipboard.set(text.trim().to_string(), false);
                        app.integration_edit_paste();
                        continue;
                    }
                    // Prompt overlay — Cmd+V / Ctrl+V on ANY prompt
                    // (single-line text input) inserts the pasted
                    // text at the caret. Every overlay text field
                    // must ship with paste per user 2026-07-15
                    // "overlay-text-field-affordances" — no more
                    // append-only prompts.
                    if let Some(p) = app.prompt.as_mut() {
                        p.insert_str(text.trim_end_matches('\n'));
                        continue;
                    }
                    // 2026-08-08 — `:` cmdline capture. Cmd+V arrives
                    // as a bracketed-paste; without this branch the
                    // paste silently dropped (user report). Same
                    // filter as the typed-char path — strip control
                    // chars and newlines so multi-line paste stays
                    // single-line.
                    if app.no_pane_cmdline.is_some() {
                        for c in text.chars() {
                            if c != '\n' && c != '\r' && (c as u32) >= 0x20 {
                                app.no_pane_cmdline_push_char(c);
                            }
                        }
                        continue;
                    }
                    // Picker (Ctrl+P / Ctrl+Shift+P / etc.) — user
                    // report 2026-08-05: paste into the Open File
                    // picker dropped silently. Same treatment as
                    // prompt: insert at end of query, skip newlines.
                    if let Some(p) = app.picker.as_mut() {
                        p.insert_str(text.trim_end_matches('\n'));
                        continue;
                    }
                    // Workspace picker filter — same class as the
                    // main picker, different backing store.
                    if app.workspace_picker_open {
                        for c in text.chars() {
                            if c != '\n' && c != '\r' && (c as u32) >= 0x20 {
                                app.workspace_picker_filter.push(c);
                            }
                        }
                        continue;
                    }
                    // Grep-panel filter — same pattern.
                    if app.git_palette_filter_focused {
                        for c in text.chars() {
                            if c != '\n' && c != '\r' && (c as u32) >= 0x20 {
                                app.git_palette_filter.push(c);
                            }
                        }
                        continue;
                    }
                    // Tree filter (when filter_mode is active).
                    if app.tree.filter_mode {
                        for c in text.chars() {
                            if c != '\n' && c != '\r' && (c as u32) >= 0x20 {
                                app.tree.filter_push(c);
                            }
                        }
                        continue;
                    }
                    // Pane-scoped inputs (Cheatsheet, Browser
                    // filters, WebSocket send input). Only handle if
                    // the active pane matches AND its input mode is
                    // on.
                    if let Some(active) = app.active
                        && let Some(pane) = app.panes.get_mut(active)
                    {
                        match pane {
                            crate::pane::Pane::Cheatsheet(c) if c.filter_mode => {
                                for ch in text.chars() {
                                    if ch != '\n' && ch != '\r' && (ch as u32) >= 0x20 {
                                        c.query.push(ch);
                                    }
                                }
                                continue;
                            }
                            crate::pane::Pane::Browser(b) => {
                                let target: Option<&mut String> = if b.net_filter_mode {
                                    Some(&mut b.net_filter)
                                } else if b.dom_filter_mode {
                                    Some(&mut b.dom_filter)
                                } else if b.cookies_filter_mode {
                                    Some(&mut b.cookies_filter)
                                } else if b.storage_filter_mode {
                                    Some(&mut b.storage_filter)
                                } else {
                                    None
                                };
                                if let Some(dst) = target {
                                    for ch in text.chars() {
                                        if ch != '\n' && ch != '\r' && (ch as u32) >= 0x20 {
                                            dst.push(ch);
                                        }
                                    }
                                    continue;
                                }
                            }
                            crate::pane::Pane::Websocket(w) => {
                                // WS send-input is a multi-line
                                // buffer (paste JSON payload etc.),
                                // so we preserve newlines here.
                                for ch in text.chars() {
                                    if ch == '\r' {
                                        continue;
                                    }
                                    w.input.push(ch);
                                }
                                continue;
                            }
                            _ => {}
                        }
                    }
                    // Priority 1 — drag-and-drop of external files
                    // (#7): terminals emit a bracketed-paste with a
                    // filesystem path when the user drops a file.
                    if try_open_dragged_path(app, &text) {
                        continue;
                    }
                    // Priority 2 — pasting a curl / http-verb URL
                    // shape into a Request pane populates the form
                    // (matches Postman / Bruno "copy as cURL from
                    // DevTools, paste here" workflow). Guarded on
                    // the active pane being a Request AND the paste
                    // content matching a lightweight curl-shape check
                    // so a normal text paste into a text field isn't
                    // hijacked.
                    let request_active = app
                        .active
                        .and_then(|i| app.panes.get(i))
                        .map(|p| matches!(p, crate::pane::Pane::Request(_)))
                        .unwrap_or(false);
                    if request_active && crate::app::App::text_looks_like_curl(&text) {
                        app.http_paste_curl_from_text(&text);
                        continue;
                    }
                    // 2026-08-08 (nvchad-user R5 SEV-2) — vim `:` cmdline
                    // paste. The `no_pane_cmdline` branch above only fires
                    // when there's no focused editor; when vim owns the
                    // cmdline (the common case — editor pane focused,
                    // user types `:e <path>` and pastes) the paste event
                    // fell through silently. Route into the InputHandler's
                    // cmdline API so the pasted text lands at the caret.
                    if let Some(editor) = app.active_editor_mut()
                        && let Some(mut cur) = editor.input.cmdline_get()
                    {
                        let caret = editor
                            .input
                            .cmdline_caret()
                            .unwrap_or(cur.len())
                            .min(cur.len());
                        let clean: String = text
                            .chars()
                            .filter(|c| *c != '\n' && *c != '\r' && (*c as u32) >= 0x20)
                            .collect();
                        cur.insert_str(caret, &clean);
                        let new_caret = caret + clean.len();
                        editor.input.cmdline_set(Some(cur));
                        editor.input.set_cmdline_caret(new_caret);
                        continue;
                    }
                    // 2026-08-08 (nvchad-user R5 SEV-2) — insert-mode
                    // paste in the editor (both vim insert mode and
                    // Standard mode). Route via `EditOp::InsertStr`
                    // through `Editor::apply` so vim's undo group stays
                    // intact and the standard mode's history is
                    // recorded consistently. In Normal / Visual the
                    // buffer isn't accepting text input, so falls
                    // through to the silent-drop below.
                    let insert_mode = app.editing_mode() == crate::input::EditingMode::Insert;
                    if insert_mode && app.active_editor_mut().is_some() {
                        let clean: String = text.replace('\r', "");
                        // Split-borrow: pull clipboard out first, then
                        // reborrow the editor. Both live on `app`.
                        let mut clip = std::mem::replace(
                            &mut app.clipboard,
                            crate::clipboard::Clipboard::detached(),
                        );
                        if let Some(editor) = app.active_editor_mut() {
                            let _ = editor.editor.apply(
                                crate::edit_op::EditOp::InsertStr(clean),
                                24,
                                &mut clip,
                            );
                        }
                        app.clipboard = clip;
                        continue;
                    }
                    // Nothing else routes Paste events today; drop
                    // silently as before.
                }
                _ => {}
            }
        }
        // (Frame-duration sample moved earlier — right after
        // term.draw — so idle poll wait doesn't count as stress.)
    }

    if let Some(ipc) = ipc.as_mut() {
        term.draw(|f| ui::draw(f, app))?;
        ipc::dump_screen_status(ipc, term.current_buffer_mut(), app);
        ipc.append_event(if app.restart_requested {
            "{\"event\":\"exit\",\"restart\":true}"
        } else {
            "{\"event\":\"exit\"}"
        });
    }
    Ok(())
}

// T-2: coalesce_scroll + SCROLL_BATCH_COUNT + take_scroll_batch_count
// moved to src/tui/mouse.rs (re-exported above).

/// External drag-and-drop (#7). Terminals that emit a bracketed
/// paste of a filesystem path should route as an open, not as a
/// text-insert. Detects:
/// - A single line (or newline-separated batch) whose trimmed value
///   is an existing file path (or `file://` URL).
/// - Multi-file drops: one open per line.
/// Returns true when at least one path opened.
fn try_open_dragged_path(app: &mut App, text: &str) -> bool {
    let mut opened_any = false;
    for raw in text.lines().map(str::trim).filter(|s| !s.is_empty()) {
        // Strip `file://` prefix + a common wrapping quote/escape pair.
        let stripped = raw
            .strip_prefix("file://")
            .unwrap_or(raw)
            .trim_matches(&['"', '\''] as &[_]);
        // Percent-decode `%20` etc — macOS Finder + several terminals
        // emit percent-encoded URIs for paths with spaces.
        let decoded = percent_decode(stripped);
        let path = std::path::PathBuf::from(decoded);
        if path.is_file() {
            app.open_path(&path);
            opened_any = true;
        }
    }
    opened_any
}

/// Minimal `%XX` decoder — covers the URL-encoded drag-and-drop
/// case without pulling in a URL crate. Accumulates the decoded
/// BYTE stream and converts to UTF-8 at the end so multibyte
/// sequences like `%C3%A9` reassemble as `é` instead of two Latin-1
/// scalars (`é`). Malformed UTF-8 falls through via `from_utf8_lossy`
/// rather than erroring.
fn percent_decode(s: &str) -> String {
    let bytes = s.as_bytes();
    let mut out: Vec<u8> = Vec::with_capacity(bytes.len());
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] == b'%'
            && i + 2 < bytes.len()
            && bytes[i + 1].is_ascii_hexdigit()
            && bytes[i + 2].is_ascii_hexdigit()
            && let Ok(v) = u8::from_str_radix(
                std::str::from_utf8(&bytes[i + 1..=i + 2]).unwrap_or("00"),
                16,
            )
        {
            out.push(v);
            i += 3;
            continue;
        }
        out.push(bytes[i]);
        i += 1;
    }
    String::from_utf8_lossy(&out).into_owned()
}

// ─── key dispatch (shared with headless/IPC) ────────────────────────

/// Translate a startup-picker selection into the corresponding command
/// or App method. Called from `dispatch_key` after the user commits.
fn fire_startup_action(action: crate::app::StartupPickerAction, app: &mut App) {
    use crate::app::StartupPickerAction::*;
    match action {
        NewFile => {
            crate::command::run("file.new", app);
        }
        OpenFile => {
            crate::command::run("view.discovery", app);
        }
        OpenFolder => {
            // Opens the AddWorkspace path prompt (`~/` is supported);
            // accepting it canonicalizes the path + adds it as an
            // extra workspace via `App::add_workspace_runtime`.
            crate::command::run("view.add_workspace", app);
        }
        SwitchWorkspace(idx) => {
            app.switch_workspace(idx);
        }
        OpenProject(path) => {
            // Same path as `view.add_workspace` once it has the
            // resolved path — registers the folder as an extra
            // workspace + switches focus to it.
            app.add_workspace_runtime(path, None);
        }
    }
}

/// Try to summon a menu via Alt+<letter> or F10. Returns true when a
/// menu was opened (caller should stop further key dispatch). Called
/// from `dispatch_key` only when no menu is currently open and the
/// `[ui] menu_bar` mode isn't `"hidden"`.
fn try_open_menu_from_key(app: &mut App, key: KeyEvent) -> bool {
    // R6 nvchad SEV-2 2026-08-09 — Alt+letter used to open the menu
    // dropdown ON TOP OF any already-open overlay (Ctrl+P picker,
    // Settings, workspace picker, prompt, vim `:` cmdline, no-pane
    // cmdline). Result: a three-layer overlay stack eating keys
    // across two input contexts. Bail before the accelerator handler
    // when any modal overlay owns focus.
    if app.picker.is_some()
        || app.prompt.is_some()
        || app.settings_overlay.is_some()
        || app.workspace_picker_open
        || app.no_pane_cmdline.is_some()
    {
        return false;
    }
    // Vim `:` cmdline lives inside the active editor pane's input
    // handler — check via `cmdline_get()`, which returns None on
    // handlers that don't own a cmdline (standard mode).
    if let Some(idx) = app.active
        && let Some(crate::pane::Pane::Editor(b)) = app.panes.get(idx)
        && b.input.cmdline_get().is_some()
    {
        return false;
    }
    let menus = crate::menu_bar::bar(app);
    // R6 keyboard/mouse/nvchad triple-corroborated 2026-08-09 — the
    // menu-bar paint clips menus that don't fit before the centred
    // workspace-chip cluster (at 120 cols only File/Edit/Selection
    // render). The prior visibility gate on Alt+letter/F10 (added in
    // keyboard-round-10 F1 to prevent firing an invisible first
    // Action on Enter) locked six of the ten menus out of the
    // keyboard path — Alt+V / G / R / T / W / H silently no-op'd at
    // any real-world width and arrow-nav wrapped through only the
    // three drawn menus.
    //
    // The stale rationale: "invisible menu + Enter = fires the
    // wrong Action". That risk lives in `handle_menu_key`'s Enter
    // handler, which fires whichever item is *highlighted*; the
    // dropdown itself always paints (it renders over the workspace
    // chip cluster), so once open the user sees exactly what they'd
    // fire. Enter-safety comes from the dropdown paint, not the
    // parent chip's visibility.
    //
    // Drop the visibility gate on both accelerators — Alt+V now
    // opens the View dropdown even when the "View" word isn't drawn,
    // and arrow-nav cycles through ALL menus.
    // F10 — open the first menu whose label is alphabetic
    // (skip the brand menu, whose label starts with a Nerd Font
    // glyph). Falls back to index 0 if no alphabetic menu exists.
    //
    // R6 R2 vscode-keyboard SEV-2 F3 2026-08-09 — DAP-gate. When
    // a debug session is active, F10 belongs to dap.next
    // (VS Code + IntelliJ convention). Prior behavior unconditionally
    // summoned the File menu, blocking step-over for the entire
    // debug session. Skip the menu-summon when app.dap is Some;
    // dispatch_chord_chain then reaches the F10 → dap.next binding
    // in the normal way. Users who still want the menu bar during
    // a debug session have Alt+F / Alt+E / etc.
    if key.code == KeyCode::F(10)
        && key.modifiers.is_empty()
        && !menus.is_empty()
        && app.dap.is_none()
    {
        let target = menus
            .iter()
            .position(|m| {
                m.label
                    .chars()
                    .next()
                    .is_some_and(|c| c.is_ascii_alphabetic())
            })
            .unwrap_or(0);
        app.menu_open = Some(crate::menu_bar::MenuOpenState::new_keyboard(target));
        return true;
    }
    // Alt+<letter> — open the menu whose FIRST ALPHABETIC char
    // matches. For the brand menu (`>  mnml`), that's `m`; for
    // `File`, `f`; etc. Matching the first alpha char (instead of
    // strictly the first char) lets the brand menu have an Alt
    // shortcut too, despite leading with a non-alpha prompt mark.
    //
    // input-handler-reviewer 2026-06-29 SEV-2: must NOT match
    // Ctrl+Alt+<letter> — those are global chords (Ctrl+Alt+W
    // closes right-panel tab, etc.) that the chord layer claims.
    // `modifiers.contains(ALT)` is a subset check, so without the
    // explicit `!contains(CONTROL)` exclusion, Ctrl+Alt+W was
    // being consumed by the menu-bar accelerator (matching 'W' →
    // Window menu) before reaching dispatch_chord_chain.
    if key.modifiers.contains(KeyModifiers::ALT)
        && !key.modifiers.contains(KeyModifiers::CONTROL)
        && let KeyCode::Char(ch) = key.code
    {
        let ch_lower = ch.to_ascii_lowercase();
        if let Some((i, _)) = menus.iter().enumerate().find(|(_, m)| {
            m.label
                .chars()
                .find(|c| c.is_ascii_alphabetic())
                .is_some_and(|c| c.to_ascii_lowercase() == ch_lower)
        }) {
            app.menu_open = Some(crate::menu_bar::MenuOpenState::new_keyboard(i));
            return true;
        }
    }
    false
}

/// Handle a key while a menu dropdown is open. Returns true when the
/// key was consumed by the menu (caller should stop dispatch).
fn handle_menu_key(app: &mut App, key: KeyEvent) -> bool {
    let menus = crate::menu_bar::bar(app);
    let Some(open) = app.menu_open.as_ref().cloned() else {
        return false;
    };
    let Some(menu) = menus.get(open.menu_idx) else {
        return false;
    };
    // R6 R2 vscode-keyboard F8 (2026-08-09) — a top-level global
    // chord fired while a menu is open should close the menu and
    // let the chord dispatcher take the key. VS Code convention.
    // Previously Ctrl+P/Ctrl+Shift+P/F1/etc. silently no-oped:
    // this fn returned `false` because Ctrl+letter didn't match a
    // mnemonic, but `try_open_menu_from_key` also bailed because
    // `menu_open.is_some()`, so nothing ever ran. Close the menu,
    // return false so `dispatch_chord_chain` gets the key.
    let is_ctrl_letter = key.modifiers.contains(KeyModifiers::CONTROL)
        && matches!(key.code, KeyCode::Char(c) if c.is_ascii_alphabetic());
    let is_fkey = matches!(
        key.code,
        KeyCode::F(1)
            | KeyCode::F(2)
            | KeyCode::F(3)
            | KeyCode::F(4)
            | KeyCode::F(5)
            | KeyCode::F(6)
            | KeyCode::F(7)
            | KeyCode::F(8)
            | KeyCode::F(9)
            | KeyCode::F(10)
            | KeyCode::F(11)
            | KeyCode::F(12)
    );
    if is_ctrl_letter || is_fkey {
        app.menu_open = None;
        return false;
    }
    // #1097 (2026-08-20) — `/` toggles filter mode. In filter mode,
    // printable chars append to `filter`, Backspace shortens, Esc
    // clears (first) then closes menu (second). Non-filter mode keeps
    // the existing mnemonic-cycle behavior so muscle memory holds.
    if matches!(key.code, KeyCode::Char('/'))
        && !key.modifiers.contains(KeyModifiers::CONTROL)
        && !key.modifiers.contains(KeyModifiers::ALT)
        && let Some(s) = app.menu_open.as_mut()
    {
        s.filter_focused = !s.filter_focused;
        if !s.filter_focused {
            s.filter.clear();
        }
        s.last_mnemonic = None;
        s.item_idx = 0;
        return true;
    }
    // Filter-mode key routing — intercept BEFORE the standard arrow /
    // Enter / mnemonic paths so typing narrows without triggering
    // mnemonic cycling. Arrows + Enter still fall through so the user
    // can nav filtered results and fire the highlighted match.
    if open.filter_focused {
        match key.code {
            KeyCode::Backspace => {
                if let Some(s) = app.menu_open.as_mut() {
                    if s.filter.pop().is_none() {
                        // Empty filter + Backspace → drop filter mode.
                        s.filter_focused = false;
                    }
                    s.item_idx = 0;
                }
                return true;
            }
            KeyCode::Esc => {
                if let Some(s) = app.menu_open.as_mut() {
                    if s.filter.is_empty() {
                        // Second Esc closes the menu.
                        app.menu_open = None;
                    } else {
                        // First Esc clears the filter, stays in menu.
                        s.filter.clear();
                        s.filter_focused = false;
                        s.item_idx = 0;
                    }
                }
                return true;
            }
            KeyCode::Char(c)
                if !key.modifiers.contains(KeyModifiers::CONTROL)
                    && !key.modifiers.contains(KeyModifiers::ALT)
                    && !c.is_control() =>
            {
                if let Some(s) = app.menu_open.as_mut() {
                    s.filter.push(c);
                    // Snap highlight to first visible match so the
                    // narrowed set is immediately actionable.
                    if let Some(&first) = s.visible_indexes(&menu.items).first() {
                        s.item_idx = first;
                    }
                }
                return true;
            }
            _ => {} // Arrows / Enter fall through to standard nav.
        }
    }
    // keyboard-round-14 SEV-3 #11 2026-07-17 — Alt+letter that
    // matches the currently-open menu's first-alpha closes it
    // (VS Code convention: Alt+V opens View → Alt+V again closes).
    // Was: silent no-op — user needed Esc or Alt+different-letter
    // to close. Only matches the SAME menu; Alt+other-letter still
    // switches menus (existing behavior below).
    if key.modifiers.contains(KeyModifiers::ALT)
        && !key.modifiers.contains(KeyModifiers::CONTROL)
        && let KeyCode::Char(ch) = key.code
    {
        let ch_lower = ch.to_ascii_lowercase();
        let same_first_alpha = menu
            .label
            .chars()
            .find(|c| c.is_ascii_alphabetic())
            .is_some_and(|c| c.to_ascii_lowercase() == ch_lower);
        if same_first_alpha {
            app.menu_open = None;
            return true;
        }
    }
    // Submenu keyboard handling. If a submenu is open (`sub_item_idx
    // is Some`), nav is routed into IT instead of the parent menu.
    // Left closes the submenu (back to parent). Esc closes both.
    if let Some(sub_idx) = open.sub_item_idx
        && let Some(crate::menu_bar::MenuItem::Submenu { items, .. }) =
            menu.items.get(open.item_idx)
    {
        match key.code {
            KeyCode::Esc => {
                app.menu_open = None;
                return true;
            }
            KeyCode::Left => {
                // Close just the submenu, stay on the parent row.
                if let Some(s) = app.menu_open.as_mut() {
                    s.sub_item_idx = None;
                }
                return true;
            }
            KeyCode::Up => {
                let n = items.len();
                if n > 0 {
                    let start = (sub_idx + n - 1) % n;
                    let new_idx = walk_to_action(items, start, false);
                    if let Some(s) = app.menu_open.as_mut() {
                        s.sub_item_idx = Some(new_idx);
                    }
                }
                return true;
            }
            KeyCode::Down => {
                let n = items.len();
                if n > 0 {
                    let start = (sub_idx + 1) % n;
                    let new_idx = walk_to_action(items, start, true);
                    if let Some(s) = app.menu_open.as_mut() {
                        s.sub_item_idx = Some(new_idx);
                    }
                }
                return true;
            }
            KeyCode::Enter | KeyCode::Right => {
                if let Some(crate::menu_bar::MenuItem::Action { command_id, .. }) =
                    items.get(sub_idx)
                {
                    let id = command_id.clone();
                    app.menu_open = None;
                    crate::command::run(&id, app);
                }
                return true;
            }
            _ => {}
        }
    }
    match key.code {
        KeyCode::Esc => {
            app.menu_open = None;
            true
        }
        KeyCode::Left => {
            // R6 keyboard/mouse/nvchad 2026-08-09 — arrow-nav cycles
            // through ALL menus, not just the ones currently painted.
            // Same rationale as `try_open_menu_from_key`: dropdown
            // Enter-safety comes from the dropdown paint itself, not
            // the parent chip's visibility. Prior gate locked six of
            // ten menus out of ←→ nav at typical widths.
            let all: Vec<usize> = (0..menus.len()).collect();
            if let Some(prev) = prev_visible_menu(open.menu_idx, &all, menus.len()) {
                app.menu_open = Some(crate::menu_bar::MenuOpenState::new_keyboard(prev));
            }
            true
        }
        KeyCode::Right => {
            // Submenu open-on-right when the highlighted parent row
            // IS a Submenu. Otherwise fall through to next-menu nav.
            if let Some(crate::menu_bar::MenuItem::Submenu { .. }) = menu.items.get(open.item_idx) {
                if let Some(s) = app.menu_open.as_mut() {
                    s.sub_item_idx = Some(0);
                }
                return true;
            }
            let all: Vec<usize> = (0..menus.len()).collect();
            if let Some(next) = next_visible_menu(open.menu_idx, &all, menus.len()) {
                app.menu_open = Some(crate::menu_bar::MenuOpenState::new_keyboard(next));
            }
            true
        }
        KeyCode::Up => {
            // #1097 — when filter is active, nav the FILTERED index
            // list; otherwise walk_to_action on the full items list
            // (existing behavior).
            if !open.filter.is_empty() {
                let vis = open.visible_indexes(&menu.items);
                if !vis.is_empty()
                    && let Some(s) = app.menu_open.as_mut()
                {
                    let cur = vis.iter().position(|&i| i == s.item_idx).unwrap_or(0);
                    let n = vis.len();
                    s.item_idx = vis[(cur + n - 1) % n];
                    s.keyboard_opened = true;
                }
                return true;
            }
            let n = menu.items.len();
            if n > 0 {
                // Skip past Separators by walking until we hit an
                // Action. `usize::MAX` (fresh-mouse-open) wraps to last.
                let start = if open.item_idx == usize::MAX {
                    n - 1
                } else {
                    (open.item_idx + n - 1) % n
                };
                let new_idx = walk_to_action(&menu.items, start, false);
                if let Some(s) = app.menu_open.as_mut() {
                    s.item_idx = new_idx;
                    s.keyboard_opened = true;
                    s.last_mnemonic = None;
                }
            }
            true
        }
        KeyCode::Down => {
            if !open.filter.is_empty() {
                let vis = open.visible_indexes(&menu.items);
                if !vis.is_empty()
                    && let Some(s) = app.menu_open.as_mut()
                {
                    let cur = vis.iter().position(|&i| i == s.item_idx).unwrap_or(0);
                    s.item_idx = vis[(cur + 1) % vis.len()];
                    s.keyboard_opened = true;
                }
                return true;
            }
            let n = menu.items.len();
            if n > 0 {
                let start = if open.item_idx == usize::MAX {
                    0
                } else {
                    (open.item_idx + 1) % n
                };
                let new_idx = walk_to_action(&menu.items, start, true);
                if let Some(s) = app.menu_open.as_mut() {
                    s.item_idx = new_idx;
                    s.keyboard_opened = true;
                    s.last_mnemonic = None;
                }
            }
            true
        }
        KeyCode::Enter => {
            // keyboard-round-9 SEV-2 F1 2026-07-14 — walk to the
            // nearest Action if item_idx points somewhere invalid
            // (usize::MAX after a mouse open, or a Separator). Prior
            // impl silently swallowed Enter in those cases; users
            // expected first-item activation. Enter on a Submenu row
            // OPENS the submenu instead of firing.
            if let Some(crate::menu_bar::MenuItem::Submenu { .. }) = menu.items.get(open.item_idx) {
                if let Some(s) = app.menu_open.as_mut() {
                    s.sub_item_idx = Some(0);
                }
                return true;
            }
            let target = match menu.items.get(open.item_idx) {
                Some(crate::menu_bar::MenuItem::Action { .. }) => open.item_idx,
                _ => walk_to_action(&menu.items, 0, true),
            };
            if let Some(crate::menu_bar::MenuItem::Action { command_id, .. }) =
                menu.items.get(target)
            {
                let id = command_id.clone();
                app.menu_open = None;
                crate::command::run(&id, app);
            }
            true
        }
        // keyboard-round-9 SEV-2 F1 2026-07-14 — printable-char
        // mnemonic (first-letter match) highlights the matching
        // Action; a second press of the SAME letter cycles to the
        // next match; Enter commits. design-round-4 issue 1
        // 2026-07-14 — was single-shot "fire the first match", so
        // View's 7 "Toggle*" items all collapsed onto "Toggle file
        // tree" and the other 6 were unreachable. Any OTHER
        // printable char is still swallowed so it can't leak into
        // the editor while the menu is open.
        KeyCode::Char(c) if !key.modifiers.contains(KeyModifiers::CONTROL) => {
            let lower = c.to_ascii_lowercase();
            let matches: Vec<usize> = menu
                .items
                .iter()
                .enumerate()
                .filter_map(|(i, it)| match it {
                    crate::menu_bar::MenuItem::Action { label, .. } => label
                        .chars()
                        .find(|ch| ch.is_ascii_alphabetic())
                        .and_then(|first| (first.to_ascii_lowercase() == lower).then_some(i)),
                    _ => None,
                })
                .collect();
            if let Some(&first) = matches.first() {
                // nvchad-user + vscode-user-keyboard 2026-07-30 both
                // flagged: pressing `s` for Save only highlighted the
                // row (Enter still required). Every OS menu bar fires
                // on the mnemonic directly. Compromise: single match
                // → fire immediately; multiple matches → cycle-then-
                // Enter so the 7-item `View → Toggle*` case still
                // works (repeat-tap `t` cycles between them).
                if matches.len() == 1
                    && let Some(crate::menu_bar::MenuItem::Action { command_id, .. }) =
                        menu.items.get(first)
                {
                    let id = command_id.to_string();
                    app.menu_open = None;
                    crate::command::run(&id, app);
                    return true;
                }
                // Repeat press of same letter → advance to next match
                // (wraps). Different letter → land on first match.
                let target = if open.last_mnemonic == Some(lower) && matches.len() > 1 {
                    matches
                        .iter()
                        .find(|&&idx| idx > open.item_idx)
                        .copied()
                        .unwrap_or(first)
                } else {
                    first
                };
                if let Some(s) = app.menu_open.as_mut() {
                    s.item_idx = target;
                    s.keyboard_opened = true;
                    s.last_mnemonic = Some(lower);
                }
            }
            // Swallow the char either way — no bleed into the editor.
            true
        }
        _ => false,
    }
}

/// Sort + dedup the visible-menu indexes and return the next one after
/// `cur` (wraps). Returns None when `visible` is empty (menu bar hasn't
/// rendered yet) or has one element (nothing to advance to).
/// keyboard-round-10 SEV-2 F1.
fn next_visible_menu(cur: usize, visible: &[usize], _total: usize) -> Option<usize> {
    let mut vis: Vec<usize> = visible.to_vec();
    vis.sort_unstable();
    vis.dedup();
    if vis.len() < 2 {
        return None;
    }
    // First visible > cur, else wrap to smallest.
    Some(
        vis.iter()
            .copied()
            .find(|&i| i > cur)
            .unwrap_or_else(|| vis[0]),
    )
}

fn prev_visible_menu(cur: usize, visible: &[usize], _total: usize) -> Option<usize> {
    let mut vis: Vec<usize> = visible.to_vec();
    vis.sort_unstable();
    vis.dedup();
    if vis.len() < 2 {
        return None;
    }
    // Last visible < cur, else wrap to largest.
    Some(
        vis.iter()
            .copied()
            .rev()
            .find(|&i| i < cur)
            .unwrap_or_else(|| vis[vis.len() - 1]),
    )
}

/// Walk through `items` starting at `start`, in the given direction
/// (`true` = forward, `false` = backward), returning the index of the
/// first Action found. Returns `start` if no Action exists.
fn walk_to_action(items: &[crate::menu_bar::MenuItem], start: usize, forward: bool) -> usize {
    let n = items.len();
    let mut idx = start;
    for _ in 0..n {
        // nvchad-user r2 2026-08-05 — added `Submenu` to the match.
        // Was: `Action` only, so Down/Up arrow silently skipped
        // over `Open recent file ▸` and the submenu was
        // keyboard-unreachable. Submenu is a selectable row too —
        // the parent's Right/Enter handler opens the child when
        // it's highlighted.
        if matches!(
            items.get(idx),
            Some(
                crate::menu_bar::MenuItem::Action { .. }
                    | crate::menu_bar::MenuItem::Submenu { .. }
            )
        ) {
            return idx;
        }
        idx = if forward {
            (idx + 1) % n
        } else {
            (idx + n - 1) % n
        };
    }
    start
}

pub fn dispatch_key(app: &mut App, key: KeyEvent) {
    // Any keystroke cancels a pending hover tooltip / divider highlight —
    // the user moved on to typing, the hover-cue is no longer relevant.
    app.hover_chip = None;
    app.hover_divider_idx = None;
    app.hover_tree_edge = false;
    app.hover_right_panel_edge = false;
    // #20 v5 — Ctrl+Shift+Z as a global keyboard shortcut for the
    // pending-undo chip. Consumed before overlay routing so it
    // works even when a picker / prompt is open (undo of the last
    // destructive action shouldn't require dismissing the overlay
    // above it first). Only fires when there IS a pending_undo,
    // so this key stays free for other flows otherwise.
    if key.code == KeyCode::Char('Z')
        && key
            .modifiers
            .contains(KeyModifiers::CONTROL | KeyModifiers::SHIFT)
        && app.pending_undo.is_some()
    {
        app.commit_pending_undo();
        return;
    }
    // F2 focus routing: `lsp.rename` claims F2 in the static keymap
    // (VS Code: rename symbol under cursor), but VS Code ALSO uses
    // F2 to rename the selected file when the tree is focused. When
    // no overlay is claiming keys and Focus == Tree, redirect F2 to
    // `file.rename`. This lives here (not in the keymap) so the
    // static registry can bind F2 to `lsp.rename` alone — dropping
    // the previous keymap-collision warning. 2026-07-08.
    if key.code == KeyCode::F(2)
        && key.modifiers.is_empty()
        && app.picker.is_none()
        && app.prompt.is_none()
        && app.whichkey.is_none()
        && app.context_menu.is_none()
        && app.menu_open.is_none()
        && app.focus == crate::focus::Focus::Tree
        && app.tree.selected_file().is_some()
    {
        let _ = crate::command::run("file.rename", app);
        return;
    }
    // Same idiom for Ctrl+D → `file.duplicate` when Focus == Tree.
    // The `editor.add_cursor_at_next_word` command owns `ctrl+d` in
    // the standard keymap and gets dispatched by the chord chain
    // BEFORE `handle_tree_key` runs — so its own Ctrl+D branch (which
    // routes to `file.duplicate`) never fired. This special-case
    // routes the key to the tree action first when tree is focused
    // and no overlay is claiming input. vscode-user-keyboard
    // 2026-07-10 SEV-2 fix.
    if key.code == KeyCode::Char('d')
        && key.modifiers == KeyModifiers::CONTROL
        && app.picker.is_none()
        && app.prompt.is_none()
        && app.whichkey.is_none()
        && app.context_menu.is_none()
        && app.menu_open.is_none()
        && app.focus == crate::focus::Focus::Tree
        && app.tree.selected_file().is_some()
    {
        let _ = crate::command::run("file.duplicate", app);
        return;
    }
    // Full-screen escape hatch: when full-screen is on and no
    // overlay is claiming Esc, treat Esc as "exit full-screen" so
    // the user is never trapped. Overlays (picker / prompt /
    // which-key) get first dibs by returning before this check below.
    if app.fullscreen_mode
        && key.code == KeyCode::Esc
        && app.picker.is_none()
        && app.prompt.is_none()
        && app.whichkey.is_none()
        && app.context_menu.is_none()
        && app.menu_open.is_none()
    {
        app.toggle_fullscreen_mode();
        return;
    }
    // Workspace-picker dropdown — when open, intercept keys so they
    // navigate the picker (not the editor below).
    if app.workspace_picker_open {
        match key.code {
            KeyCode::Esc => {
                app.workspace_picker_open = false;
                app.workspace_picker_filter.clear();
                return;
            }
            KeyCode::Char(c)
                if !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                app.workspace_picker_filter.push(c);
                return;
            }
            _ => {
                // 2026-08-08 — Backspace / Ctrl+U / Ctrl+W / Ctrl+V.
                let r = crate::ui::text_input::handle_filter_shortcut(
                    key,
                    &mut app.workspace_picker_filter,
                    Some(&mut app.clipboard),
                );
                if r == crate::ui::text_input::TextKeyResult::Handled {
                    return;
                }
            }
        }
    }
    // Workspaces editor overlay — intercept keyboard so arrows
    // navigate, Enter edits, n adds, d deletes, Esc closes.
    if app.workspaces_editor_open && app.prompt.is_none() && app.context_menu.is_none() {
        let total = app.config.workspaces.len() + 1; // +1 for the "Add" action row
        match key.code {
            KeyCode::Esc => {
                app.close_workspaces_editor();
                return;
            }
            // Reorder (Shift+↑/↓ and `K`/`J`) MUST be matched
            // before the bare Up/Down arms below — otherwise the
            // unguarded ↑/↓ arms swallow the Shift variant.
            KeyCode::Up if key.modifiers.contains(KeyModifiers::SHIFT) => {
                let sel = app.workspaces_editor_selected;
                if sel < app.config.workspaces.len() {
                    app.workspaces_editor_move_up(sel);
                }
                return;
            }
            KeyCode::Down if key.modifiers.contains(KeyModifiers::SHIFT) => {
                let sel = app.workspaces_editor_selected;
                if sel < app.config.workspaces.len() {
                    app.workspaces_editor_move_down(sel);
                }
                return;
            }
            KeyCode::Char('K') => {
                let sel = app.workspaces_editor_selected;
                if sel < app.config.workspaces.len() {
                    app.workspaces_editor_move_up(sel);
                }
                return;
            }
            KeyCode::Char('J') => {
                let sel = app.workspaces_editor_selected;
                if sel < app.config.workspaces.len() {
                    app.workspaces_editor_move_down(sel);
                }
                return;
            }
            KeyCode::Up | KeyCode::Char('k') => {
                if app.workspaces_editor_selected > 0 {
                    app.workspaces_editor_selected -= 1;
                } else {
                    app.workspaces_editor_selected = total.saturating_sub(1);
                }
                return;
            }
            KeyCode::Down | KeyCode::Char('j') => {
                app.workspaces_editor_selected =
                    (app.workspaces_editor_selected + 1) % total.max(1);
                return;
            }
            KeyCode::Enter => {
                let sel = app.workspaces_editor_selected;
                if sel < app.config.workspaces.len() {
                    app.workspaces_editor_open_rename(sel);
                } else {
                    // + Add row.
                    crate::command::run("view.add_workspace", app);
                }
                return;
            }
            KeyCode::Char('n') => {
                crate::command::run("view.add_workspace", app);
                return;
            }
            KeyCode::Char('d') => {
                let sel = app.workspaces_editor_selected;
                if sel < app.config.workspaces.len() {
                    app.workspaces_editor_delete(sel);
                }
                return;
            }
            _ => {}
        }
    }
    // Dock widget kebab menu — when open, intercept keys so they
    // navigate the menu rather than falling through to editor /
    // tree handlers.
    if app.dock_kebab_menu.is_some() {
        let menu = app.dock_kebab_menu.as_ref().unwrap();
        let items_len = menu.items.len();
        match key.code {
            KeyCode::Esc => {
                app.dock_kebab_menu = None;
                return;
            }
            KeyCode::Down | KeyCode::Tab => {
                if let Some(m) = app.dock_kebab_menu.as_mut() {
                    let mut i = m.selected;
                    for _ in 0..items_len {
                        i = (i + 1) % items_len;
                        if matches!(
                            m.items[i],
                            crate::dock::KebabMenuItem::Header(_)
                                | crate::dock::KebabMenuItem::Separator
                        ) {
                            continue;
                        }
                        break;
                    }
                    m.selected = i;
                }
                return;
            }
            KeyCode::Up | KeyCode::BackTab => {
                if let Some(m) = app.dock_kebab_menu.as_mut() {
                    let mut i = m.selected;
                    for _ in 0..items_len {
                        i = if i == 0 { items_len - 1 } else { i - 1 };
                        if matches!(
                            m.items[i],
                            crate::dock::KebabMenuItem::Header(_)
                                | crate::dock::KebabMenuItem::Separator
                        ) {
                            continue;
                        }
                        break;
                    }
                    m.selected = i;
                }
                return;
            }
            KeyCode::Enter => {
                let (wid, item) = {
                    let m = app.dock_kebab_menu.as_ref().unwrap();
                    (m.widget_id, m.items.get(m.selected).copied())
                };
                if let Some(item) = item {
                    crate::dock::apply_kebab_choice(app, wid, item);
                }
                return;
            }
            _ => {}
        }
    }
    // Integrations rail filter — explicit focus (was auto-focused,
    // but that stole `:` / palette shortcuts / any global char while
    // the section was open; kept accreting gates for every collision
    // until 2026-07-04 flipped it to explicit). Focus is set by
    // pressing `/` in the panel or clicking the filter chip.
    // code-reviewer 2026-07-09: add `prompt.is_none()` +
    // `no_pane_cmdline.is_none()` guards for parity with the
    // other panels' hoisted absorb; the prior version could still
    // eat keys while a confirm dialog was open or the no-pane
    // cmdline was capturing.
    if app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Integrations
        && app.picker.is_none()
        && app.integration_edit.is_none()
        && app.prompt.is_none()
        && app.no_pane_cmdline.is_none()
    {
        // Not-yet-focused: `/` enters filter mode (matches vim /
        // less search idiom). All other chars flow through so
        // global shortcuts still fire from the panel.
        if !app.integrations_panel_filter_focused {
            if let KeyCode::Char('/') = key.code
                && !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT)
            {
                app.integrations_panel_filter_focused = true;
                return;
            }
        } else {
            // Focused: chars append, Backspace pops, Esc clears +
            // unfocuses, Enter commits + unfocuses.
            match key.code {
                KeyCode::Esc => {
                    app.integrations_panel_filter.clear();
                    app.integrations_panel_filter_focused = false;
                    return;
                }
                KeyCode::Enter => {
                    app.integrations_panel_filter_focused = false;
                    return;
                }
                KeyCode::Char(c)
                    if !key
                        .modifiers
                        .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
                {
                    app.integrations_panel_filter.push(c);
                    return;
                }
                _ => {
                    // 2026-08-08 — Backspace / Ctrl+U / Ctrl+W /
                    // Ctrl+V via the shared filter helper.
                    let r = crate::ui::text_input::handle_filter_shortcut(
                        key,
                        &mut app.integrations_panel_filter,
                        Some(&mut app.clipboard),
                    );
                    if r == crate::ui::text_input::TextKeyResult::Handled {
                        return;
                    }
                }
            }
        }
    }
    // HTTP rail filter — same `/` → focus, then char/backspace/Esc/Enter.
    if !app.http_panel_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Http
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && let KeyCode::Char('/') = key.code
        && !key
            .modifiers
            .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT)
    {
        app.http_panel_filter_focused = true;
        return;
    }
    // Absorb block must re-check the same guards as the entry —
    // the `_filter_focused` flag alone would trap keys after
    // focus moves to a pane / a picker opens / a prompt fires.
    // nvchad-user + vscode-user-mouse + vscode-user-keyboard all
    // hit variants of that on 2026-07-09. Same guard-hoist
    // pattern for all four filter panels below.
    if app.http_panel_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Http
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && app.prompt.is_none()
    {
        match key.code {
            KeyCode::Esc => {
                app.http_panel_filter.clear();
                app.http_panel_filter_focused = false;
                app.http_panel_cursor_reset();
                return;
            }
            KeyCode::Enter => {
                app.http_panel_filter_focused = false;
                // Filter accepted — snap cursor to first visible
                // row so `j`/`k`/Enter operate on the narrowed set.
                app.http_panel_cursor_reset();
                return;
            }
            KeyCode::Char(c)
                if !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                app.http_panel_filter.push(c);
                app.http_panel_cursor_reset();
                return;
            }
            _ => {
                // 2026-08-08 — Backspace / Ctrl+U / Ctrl+W / Ctrl+V
                // via the shared filter helper. cursor_reset() runs
                // if the filter actually changed.
                let before = app.http_panel_filter.len();
                let r = crate::ui::text_input::handle_filter_shortcut(
                    key,
                    &mut app.http_panel_filter,
                    Some(&mut app.clipboard),
                );
                if r == crate::ui::text_input::TextKeyResult::Handled {
                    if app.http_panel_filter.len() != before {
                        app.http_panel_cursor_reset();
                    }
                    return;
                }
            }
        }
    }
    // HTTP panel row navigation — j/k / arrows / Enter when the
    // panel has focus and no filter's active. Keyboard-user SEV-2 #4
    // fix (2026-07-07).
    if app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Http
        && !app.http_panel_filter_focused
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && !key
            .modifiers
            .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT)
    {
        match key.code {
            KeyCode::Down | KeyCode::Char('j') => {
                app.http_panel_cursor_down();
                return;
            }
            KeyCode::Up | KeyCode::Char('k') => {
                app.http_panel_cursor_up();
                return;
            }
            KeyCode::Enter => {
                app.http_panel_cursor_activate();
                return;
            }
            _ => {}
        }
    }
    // TODOs / Notes rail filter — same `/` idiom as HTTP + Agents.
    // Focus on `/`, then intercept typing / backspace / Esc / Enter.
    if !app.todos_panel_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Todos
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && let KeyCode::Char('/') = key.code
        && !key
            .modifiers
            .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT)
    {
        app.todos_panel_filter_focused = true;
        return;
    }
    if app.todos_panel_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Todos
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && app.prompt.is_none()
    {
        match key.code {
            KeyCode::Esc => {
                app.todos_panel_filter.clear();
                app.todos_panel_filter_focused = false;
                return;
            }
            KeyCode::Enter => {
                app.todos_panel_filter_focused = false;
                return;
            }
            KeyCode::Char(c)
                if !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                app.todos_panel_filter.push(c);
                return;
            }
            _ => {
                // 2026-08-08 — Backspace / Ctrl+U / Ctrl+W / Ctrl+V.
                let r = crate::ui::text_input::handle_filter_shortcut(
                    key,
                    &mut app.todos_panel_filter,
                    Some(&mut app.clipboard),
                );
                if r == crate::ui::text_input::TextKeyResult::Handled {
                    return;
                }
            }
        }
    }
    // Row nav on TODOs / Notes / Sessions when the panel has
    // focus and the filter isn't focused. Mirrors the HTTP
    // panel's j/k/arrow/Enter handling. vscode-user-keyboard
    // SEV-2 fix 2026-07-09.
    if app.focus == crate::focus::Focus::Tree
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && app.prompt.is_none()
        && !key
            .modifiers
            .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT)
    {
        match (app.active_section, key.code) {
            (crate::app::ActivitySection::Todos, KeyCode::Down | KeyCode::Char('j'))
                if !app.todos_panel_filter_focused =>
            {
                app.todos_panel_cursor_down();
                return;
            }
            (crate::app::ActivitySection::Todos, KeyCode::Up | KeyCode::Char('k'))
                if !app.todos_panel_filter_focused =>
            {
                app.todos_panel_cursor_up();
                return;
            }
            (crate::app::ActivitySection::Todos, KeyCode::Enter)
                if !app.todos_panel_filter_focused =>
            {
                app.todos_panel_activate();
                return;
            }
            (crate::app::ActivitySection::Notes, KeyCode::Down | KeyCode::Char('j'))
                if !app.notes_panel_filter_focused =>
            {
                app.notes_panel_cursor_down();
                return;
            }
            (crate::app::ActivitySection::Notes, KeyCode::Up | KeyCode::Char('k'))
                if !app.notes_panel_filter_focused =>
            {
                app.notes_panel_cursor_up();
                return;
            }
            (crate::app::ActivitySection::Notes, KeyCode::Enter)
                if !app.notes_panel_filter_focused =>
            {
                app.notes_panel_activate();
                return;
            }
            (crate::app::ActivitySection::Sessions, KeyCode::Down | KeyCode::Char('j'))
                if !app.sessions_panel_filter_focused =>
            {
                app.sessions_panel_cursor_down();
                return;
            }
            (crate::app::ActivitySection::Sessions, KeyCode::Up | KeyCode::Char('k'))
                if !app.sessions_panel_filter_focused =>
            {
                app.sessions_panel_cursor_up();
                return;
            }
            (crate::app::ActivitySection::Sessions, KeyCode::Enter)
                if !app.sessions_panel_filter_focused =>
            {
                app.sessions_panel_activate();
                return;
            }
            _ => {}
        }
    }
    if !app.sessions_panel_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Sessions
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && let KeyCode::Char('/') = key.code
        && !key
            .modifiers
            .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT)
    {
        app.sessions_panel_filter_focused = true;
        return;
    }
    if app.sessions_panel_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Sessions
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && app.prompt.is_none()
    {
        match key.code {
            KeyCode::Esc => {
                app.sessions_panel_filter.clear();
                app.sessions_panel_filter_focused = false;
                return;
            }
            KeyCode::Enter => {
                app.sessions_panel_filter_focused = false;
                return;
            }
            KeyCode::Char(c)
                if !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                app.sessions_panel_filter.push(c);
                return;
            }
            _ => {
                // 2026-08-08 — Backspace / Ctrl+U / Ctrl+W / Ctrl+V.
                let r = crate::ui::text_input::handle_filter_shortcut(
                    key,
                    &mut app.sessions_panel_filter,
                    Some(&mut app.clipboard),
                );
                if r == crate::ui::text_input::TextKeyResult::Handled {
                    return;
                }
            }
        }
    }
    if !app.notes_panel_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Notes
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && let KeyCode::Char('/') = key.code
        && !key
            .modifiers
            .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT)
    {
        app.notes_panel_filter_focused = true;
        return;
    }
    if app.notes_panel_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Notes
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && app.prompt.is_none()
    {
        match key.code {
            KeyCode::Esc => {
                app.notes_panel_filter.clear();
                app.notes_panel_filter_focused = false;
                return;
            }
            KeyCode::Enter => {
                app.notes_panel_filter_focused = false;
                return;
            }
            KeyCode::Char(c)
                if !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                app.notes_panel_filter.push(c);
                return;
            }
            _ => {
                // 2026-08-08 — Backspace / Ctrl+U / Ctrl+W / Ctrl+V.
                let r = crate::ui::text_input::handle_filter_shortcut(
                    key,
                    &mut app.notes_panel_filter,
                    Some(&mut app.clipboard),
                );
                if r == crate::ui::text_input::TextKeyResult::Handled {
                    return;
                }
            }
        }
    }
    // Agents rail filter — `/` in the panel focuses filter (matches
    // vim / less search idiom, mirrors the Integrations panel behavior).
    // Once focused, intercept typing / backspace / Esc / Enter.
    if !app.agents_panel_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Agents
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && let KeyCode::Char('/') = key.code
        && !key
            .modifiers
            .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT)
    {
        app.agents_panel_filter_focused = true;
        return;
    }
    // code-reviewer 2026-07-09: agents' absorb also needed the
    // guard-hoist — same class as the four filter panels fixed
    // in the parent commit.
    if app.agents_panel_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Agents
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && app.prompt.is_none()
    {
        match key.code {
            KeyCode::Esc => {
                app.agents_panel_filter.clear();
                app.agents_panel_filter_focused = false;
                return;
            }
            KeyCode::Enter => {
                app.agents_panel_filter_focused = false;
                return;
            }
            KeyCode::Char(c)
                if !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                app.agents_panel_filter.push(c);
                return;
            }
            _ => {
                // 2026-08-08 — Backspace / Ctrl+U / Ctrl+W / Ctrl+V.
                let r = crate::ui::text_input::handle_filter_shortcut(
                    key,
                    &mut app.agents_panel_filter,
                    Some(&mut app.clipboard),
                );
                if r == crate::ui::text_input::TextKeyResult::Handled {
                    return;
                }
            }
        }
    }
    // Cloud Agents quick-fire prompt — `/` to focus (matches the
    // Integrations / Agents / Settings idiom), then chars append,
    // Enter submits, Esc clears + unfocuses.
    if !app.cloud_run_prompt_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::CloudAgents
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && let KeyCode::Char('/') = key.code
        && !key
            .modifiers
            .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT)
    {
        app.cloud_run_prompt_focused = true;
        return;
    }
    // Cloud Agents quick-fire prompt input (hybrid UX — daily-driver
    // path that uses the saved [cloud_run.defaults]). Absorb guard-
    // hoisted 2026-07-10 to match the other panels — was capturing
    // keys across section changes and picker opens (SEV-2 class).
    if app.cloud_run_prompt_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::CloudAgents
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && app.prompt.is_none()
    {
        match key.code {
            KeyCode::Esc => {
                app.cloud_run_prompt_input.clear();
                app.cloud_run_prompt_focused = false;
                return;
            }
            KeyCode::Enter => {
                app.cloud_run_quick_send();
                return;
            }
            KeyCode::Char(c)
                if !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                app.cloud_run_prompt_input.push(c);
                return;
            }
            _ => {
                // 2026-08-08 — Backspace / Ctrl+U / Ctrl+W / Ctrl+V.
                let r = crate::ui::text_input::handle_filter_shortcut(
                    key,
                    &mut app.cloud_run_prompt_input,
                    Some(&mut app.clipboard),
                );
                if r == crate::ui::text_input::TextKeyResult::Handled {
                    return;
                }
            }
        }
    }
    // Same idiom for the Cloud Agents panel filter.
    if app.cloud_agents_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::CloudAgents
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && app.prompt.is_none()
    {
        match key.code {
            KeyCode::Esc => {
                app.cloud_agents_filter.clear();
                app.cloud_agents_filter_focused = false;
                return;
            }
            KeyCode::Enter => {
                app.cloud_agents_filter_focused = false;
                return;
            }
            KeyCode::Char(c)
                if !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                app.cloud_agents_filter.push(c);
                return;
            }
            _ => {
                // 2026-08-08 — Backspace / Ctrl+U / Ctrl+W / Ctrl+V.
                let r = crate::ui::text_input::handle_filter_shortcut(
                    key,
                    &mut app.cloud_agents_filter,
                    Some(&mut app.clipboard),
                );
                if r == crate::ui::text_input::TextKeyResult::Handled {
                    return;
                }
            }
        }
    }
    // NewCloudRunWizard (Cloud Agents version) keys.
    if app
        .active
        .and_then(|i| app.panes.get(i))
        .map(|p| matches!(p, crate::pane::Pane::NewCloudRunWizard(_)))
        .unwrap_or(false)
    {
        match key.code {
            KeyCode::Esc => {
                app.new_cloud_run_wizard_close();
                return;
            }
            KeyCode::Up | KeyCode::Char('k') => {
                app.new_cloud_run_wizard_move(-1);
                return;
            }
            KeyCode::Down | KeyCode::Char('j') => {
                app.new_cloud_run_wizard_move(1);
                return;
            }
            KeyCode::Backspace => {
                app.new_cloud_run_wizard_backspace();
                return;
            }
            KeyCode::Tab | KeyCode::Enter => {
                app.new_cloud_run_wizard_next();
                return;
            }
            KeyCode::Char(ch)
                if !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                app.new_cloud_run_wizard_type(ch);
                return;
            }
            _ => {}
        }
    }
    // NewCloudAgentWizard pane — when active, intercept arrows,
    // Tab, Enter, Esc, and typing so the keys don't fall through
    // to the editor underneath.
    if app
        .active
        .and_then(|i| app.panes.get(i))
        .map(|p| matches!(p, crate::pane::Pane::NewCloudAgentWizard(_)))
        .unwrap_or(false)
    {
        match key.code {
            KeyCode::Esc => {
                app.new_cloud_agent_wizard_close();
                return;
            }
            KeyCode::Up | KeyCode::Char('k') => {
                app.new_cloud_agent_wizard_move(-1);
                return;
            }
            KeyCode::Down | KeyCode::Char('j') => {
                app.new_cloud_agent_wizard_move(1);
                return;
            }
            KeyCode::Backspace => {
                app.new_cloud_agent_wizard_backspace();
                return;
            }
            KeyCode::Tab => {
                app.new_cloud_agent_wizard_next();
                return;
            }
            KeyCode::Enter => {
                app.new_cloud_agent_wizard_next();
                return;
            }
            KeyCode::Char(' ') => {
                app.new_cloud_agent_wizard_toggle();
                return;
            }
            KeyCode::Char('a') => {
                app.new_cloud_agent_wizard_select_all();
                return;
            }
            KeyCode::Char(ch)
                if !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                app.new_cloud_agent_wizard_type(ch);
                return;
            }
            _ => {}
        }
    }
    // Git-palette filter input — when focused, intercept typing /
    // backspace / Esc here so the keys don't fall through to the
    // editor. 2026-07-10 audit: guard-hoisted to match the other
    // panel filters (same absorb-block class as the SEV-2 fixes).
    if app.git_palette_filter_focused
        && app.focus == crate::focus::Focus::Tree
        && app.active_section == crate::app::ActivitySection::Git
        && app.picker.is_none()
        && app.no_pane_cmdline.is_none()
        && app.prompt.is_none()
    {
        match key.code {
            KeyCode::Esc => {
                app.git_palette_filter.clear();
                app.git_palette_filter_focused = false;
                return;
            }
            KeyCode::Enter => {
                app.git_palette_filter_focused = false;
                return;
            }
            KeyCode::Char(c)
                if !key
                    .modifiers
                    .intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                app.git_palette_filter.push(c);
                return;
            }
            _ => {
                // 2026-08-08 — Backspace / Ctrl+U / Ctrl+W / Ctrl+V.
                let r = crate::ui::text_input::handle_filter_shortcut(
                    key,
                    &mut app.git_palette_filter,
                    Some(&mut app.clipboard),
                );
                if r == crate::ui::text_input::TextKeyResult::Handled {
                    return;
                }
            }
        }
    }
    // Menu-bar dropdown — intercept keys before anything else so
    // Esc / arrows / Enter target the menu instead of the editor.
    if app.menu_open.is_some() && handle_menu_key(app, key) {
        return;
    }
    // Menu summon — Alt+letter opens the corresponding menu,
    // F10 opens the first menu. Gated by menu_bar mode != "hidden".
    if app.menu_open.is_none()
        && app.config.ui.menu_bar != "hidden"
        && try_open_menu_from_key(app, key)
    {
        return;
    }
    // 2026-06-22 — Esc during an in-flight tree-file drag aborts
    // the drag: clears tree_drag + the drop-zone overlay. User
    // can release the mouse anywhere safely after that without
    // triggering drag-to-split. Matches the VS Code / macOS
    // convention of Esc-cancels-drag.
    if key.code == KeyCode::Esc && app.tree_drag.is_some() {
        app.tree_drag = None;
        app.rects.tab_drop_target = None;
        return;
    }
    // Same idiom for the hover-help drag-resize handle. If the terminal
    // ever fails to deliver the mouse-up (focus loss mid-drag, SGR glitch,
    // mouse leaves the window), the drag stays armed and would silently
    // intercept the next unrelated left-drag anywhere. Esc gives the user
    // a bailout.
    if key.code == KeyCode::Esc && app.hover_help_drag.is_some() {
        app.hover_help_drag = None;
        return;
    }
    // AI ghost-text: while a suggestion is showing, bare `Tab` accepts
    // all of it, `Ctrl+Right` accepts the next word, `Ctrl+Down` the
    // next line (both leave the remainder as a ghost); any other key
    // dismisses it (and then does its normal thing).
    //
    // 2026-08-19 (#1070) — accepting a ghost also dismisses any open
    // LSP completion popup. The two UIs commonly overlap: the user
    // types "reset(" which auto-triggers `textDocument/completion`
    // AND fires the ghost debounce; the ghost lands first, but the
    // completion popup stays visible underneath. Bare Tab hits this
    // early-return before the popup's own Tab-accept branch below
    // (line ~2335), so without this the popup lingers indefinitely.
    // Confirmed via hero-tape review: the popup stuck around for
    // ~15s across the hover-help + settings beats.
    if app.has_ghost_suggestion() {
        if key.code == KeyCode::Tab && key.modifiers.is_empty() {
            app.accept_ghost_suggestion();
            app.completion = None;
            return;
        }
        if key.code == KeyCode::Right && key.modifiers == KeyModifiers::CONTROL {
            app.accept_ghost_word();
            app.completion = None;
            return;
        }
        if key.code == KeyCode::Down && key.modifiers == KeyModifiers::CONTROL {
            app.accept_ghost_line();
            app.completion = None;
            return;
        }
        app.clear_ghost_suggestion();
    }
    // 2026-06-08 vscode hunt SEV-2: `Ctrl+S` (Save) is a global
    // muscle-memory reflex — VS Code fires it from any focus. mnml
    // used to swallow it inside every overlay (palette, prompts,
    // settings) which led to silent data loss: "find something,
    // hit Ctrl+S to checkpoint, keep going" left the file dirty
    // with no toast, no error. Intercept here before any
    // overlay-consuming branch runs. Overlay state is untouched —
    // save fires, the user keeps doing whatever they were doing.
    // Skip when a pty pane has the focus (the shell legitimately
    // wants `Ctrl+S` for XOFF flow control); the keymap below
    // handles the not-in-overlay case the same way it did before.
    if key.code == KeyCode::Char('s')
        && key.modifiers == KeyModifiers::CONTROL
        && !matches!(
            app.active.and_then(|i| app.panes.get(i)),
            Some(Pane::Pty(_))
        )
        // R10 keyboard SEV-1 (2026-08-11) — the Integration Configure
        // overlay owns Ctrl+S itself (`save_integration_settings`).
        // The interceptor used to fire global `save_active` first,
        // and the pane's handler at overlay.rs:41 never ran. Footer
        // said `[Ctrl+S] save` and did nothing. Skip the interceptor
        // so the overlay handler sees the chord.
        && app.integration_settings.is_none()
    {
        // Anything in flight that would have consumed the chord
        // (palette / prompt / settings) is still alive afterwards;
        // we just don't let it eat the save.
        app.save_active();
        return;
    }
    // Scratch terminal — when focused, route keystrokes to the pty
    // (with Esc as the way out). The chord that toggles it (`term.
    // scratch_toggle`) still works as the close gesture because the
    // command resolver runs against the keymap below — but only when
    // the scratch term isn't focused.
    if let Some(scratch) = app.scratch_term.as_mut()
        && scratch.focused
    {
        // keyboard-round-12 SEV-2 2026-07-14 — Ctrl+` must escape
        // the pty-forwarding branch so it can reach the toggle
        // command and CLOSE the scratch term. Was: every non-Esc
        // key (including the toggle chord itself) got forwarded
        // to the child, which just typed a backtick into the
        // shell — the close half of the toggle was unreachable
        // from the keyboard. Also handle Ctrl+~ / Ctrl+Shift+` in
        // case a terminal delivers Shift with the tilde form.
        let is_close_chord = matches!(key.code, KeyCode::Char('`') | KeyCode::Char('~'))
            && key.modifiers.contains(KeyModifiers::CONTROL);
        if is_close_chord {
            app.toggle_scratch_term();
            return;
        }
        if key.code == KeyCode::Esc {
            scratch.focused = false;
            return;
        }
        let bytes = crate::app::dispatch::pty_key_bytes(key);
        if !bytes.is_empty() {
            scratch.session.write_bytes(&bytes);
        }
        return;
    }
    // Native mixr panel — when focused, route *every* key (incl. Esc,
    // which mixr uses for back-navigation) to mixr over the wire.
    // Startup picker intercept — when the launch-time chooser is up,
    // it owns the keyboard. Esc / q dismisses; arrows + digits move /
    // commit; everything else is swallowed so it doesn't leak through
    // to the underlying editor.
    if app.startup_picker.is_some() {
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') => {
                app.dismiss_startup_picker();
            }
            KeyCode::Up | KeyCode::Char('k') => {
                app.startup_picker_move(-1);
            }
            KeyCode::Down | KeyCode::Char('j') => {
                app.startup_picker_move(1);
            }
            KeyCode::Enter => {
                if let Some(action) = app.startup_picker_commit() {
                    fire_startup_action(action, app);
                }
            }
            KeyCode::Char(c) if c.is_ascii_digit() && c != '0' => {
                if let Some(action) = app.startup_picker_press_digit(c) {
                    fire_startup_action(action, app);
                }
            }
            _ => {}
        }
        return;
    }
    // Macro recording — capture every keystroke that flows through here.
    // Replaying explicitly skips this so it doesn't re-record into a new
    // macro mid-replay.
    if let crate::app::MacroState::Recording { keys, .. } = &mut app.macro_state {
        keys.push(key);
    }
    // Esc dismisses any visible toast (visual fluff the user explicitly
    // said "go away" to). Doesn't return — other Esc handlers further
    // down still fire (e.g. exit overlays, leave visual mode).
    if key.code == KeyCode::Esc {
        app.toast = None;
        app.toast_stack.clear();
        // F1 discovery overlay closes on Esc too — same dismiss gesture as
        // tooltips/toasts.
        app.show_discovery_overlay = false;
        // Welcome overlay also dismisses on Esc (and persists the marker
        // so it doesn't auto-reopen next launch).
        if app.show_welcome {
            app.dismiss_welcome();
        }
        app.show_about = false;
    }
    // The AI usage overlay was retired 2026-08-16 in favor of a
    // proper `Pane::AiUsage` — no key-steal shim needed anymore.
    // Flash intercept: when label overlay is up, Esc cancels; a printable
    // char matching a label commits the jump; an unmatched key cancels
    // and falls through to normal dispatch.
    if app.flash_state.is_some() {
        if key.code == KeyCode::Esc {
            app.flash_cancel();
            return;
        }
        if let KeyCode::Char(c) = key.code
            && app.flash_consume_char(c)
        {
            return;
        }
        // No match — drop state and re-dispatch the keystroke normally.
        app.flash_cancel();
    }
    // The settings overlay steals all keys until it's saved (Enter) or
    // cancelled (Esc). Keyboard-only — see CLAUDE.md's "Family settings
    // UI convention".
    if app.settings_overlay.is_some() {
        handle_settings_overlay_key(app, key);
        return;
    }
    // First-launch wizard — steals all keys until Finish (Enter) or
    // Ask-me-later (Esc). Sits ABOVE the settings-overlay branch
    // because we want the wizard to win when both are somehow open
    // (shouldn't happen; belt-and-braces).
    if app.first_launch.is_some() {
        crate::tui::handlers::overlay::handle_first_launch_key(app, key);
        return;
    }
    // Per-integration Settings pane — same modal-precedence idea.
    if app.integration_settings.is_some() {
        crate::tui::handlers::overlay::handle_integration_settings_key(app, key);
        return;
    }
    // #20 Pattern B — a pending confirm modal wins over everything
    // else. Blocks all input until dismissed (Esc / N) or fired
    // (Enter / Y).
    if app.pending_confirm.is_some() {
        crate::tui::handlers::overlay::handle_confirm_modal_key(app, key);
        return;
    }
    // An open picker / palette overlay steals all keys until it's
    // dismissed. Checked BEFORE the integration-edit panel so Ctrl+G
    // from inside the edit panel (which opens the glyph picker on
    // top) routes subsequent keys to the picker's filter input,
    // not back into the Glyph field char-by-char.
    if app.picker.is_some() {
        handle_picker_key(app, key);
        return;
    }
    // Integration edit panel — all-keys-stolen while open; Enter
    // saves, Esc cancels, Tab cycles fields, ←→ cycles color, other
    // chars type into the focused text field.
    // Glyph builder is checked BEFORE integration_edit because when
    // both are open (edit panel → glyph action menu → builder), the
    // builder is the visual front layer. Reverse order made Esc
    // close the edit panel first (behind) then the builder — user
    // saw two Escs to close what they expected to be one.
    if app.glyph_builder.is_some() {
        handle_glyph_builder_key(app, key);
        return;
    }
    if app.integration_edit.is_some() {
        handle_integration_edit_key(app, key);
        return;
    }
    // Search activity-bar section: input focused → printable keys
    // append to the query, Backspace deletes, Enter runs the grep,
    // ↑↓ navigates results, Esc blurs.
    if app.search_input_focused {
        handle_search_section_key(app, key);
        return;
    }
    // Git activity-bar section: commit textarea focused → printables
    // append to the buffer, Backspace deletes, Ctrl+Enter commits,
    // Esc blurs.
    if app.git_section_commit_focused {
        handle_git_section_commit_key(app, key);
        return;
    }
    // Help overlay — scroll + dismiss. No editing.
    if app.help_overlay.is_some() {
        handle_help_overlay_key(app, key);
        return;
    }
    // The LSP signature-help popup: Esc dismisses; Up / Down cycle through
    // overload signatures (only when there's more than one — otherwise the
    // arrow keys still navigate the editor). Any other key falls through (we
    // want typing to continue updating the popup, not dismiss it). Cursor
    // jumps via commands clear the popup separately.
    if let Some(sig) = app.signature.as_mut() {
        match key.code {
            KeyCode::Esc => {
                app.signature = None;
                return;
            }
            KeyCode::Down if sig.signatures.len() > 1 => {
                sig.cycle();
                return;
            }
            KeyCode::Up if sig.signatures.len() > 1 => {
                sig.cycle_prev();
                return;
            }
            _ => {}
        }
    }
    // Peek-definition overlay — Esc closes; arrows / j / k / PgUp /
    // PgDn scroll within the box; anything else closes + falls
    // through to normal handling.
    if app.peek_overlay.is_some() {
        match key.code {
            KeyCode::Esc => {
                app.peek_overlay = None;
                return;
            }
            KeyCode::Up | KeyCode::Char('k') => {
                if let Some(po) = &mut app.peek_overlay {
                    po.scroll_up();
                }
                return;
            }
            KeyCode::Down | KeyCode::Char('j') => {
                if let Some(po) = &mut app.peek_overlay {
                    po.scroll_down();
                }
                return;
            }
            KeyCode::PageUp => {
                if let Some(po) = &mut app.peek_overlay {
                    for _ in 0..5 {
                        po.scroll_up();
                    }
                }
                return;
            }
            KeyCode::PageDown => {
                if let Some(po) = &mut app.peek_overlay {
                    for _ in 0..5 {
                        po.scroll_down();
                    }
                }
                return;
            }
            _ => {
                // 2026-06-21 lsp-cheat-test SEV-2: was falling
                // through to the editor, so in vim mode pressing
                // `x` to dismiss the overlay also deleted the
                // char under cursor. Now: close + EAT the
                // keystroke. User can re-issue if they actually
                // wanted to do something with it.
                app.peek_overlay = None;
                return;
            }
        }
    }
    // An LSP hover popup is up: arrows / j / k / PgUp / PgDn scroll it; Esc
    // closes it; anything else closes it and is then handled normally.
    if app.hover.is_some() {
        match key.code {
            KeyCode::Esc => {
                app.hover = None;
                return;
            }
            KeyCode::Up | KeyCode::Char('k') => {
                if let Some(h) = &mut app.hover {
                    h.scroll_by(-1);
                }
                return;
            }
            KeyCode::Down | KeyCode::Char('j') => {
                if let Some(h) = &mut app.hover {
                    h.scroll_by(1);
                }
                return;
            }
            KeyCode::PageUp => {
                if let Some(h) = &mut app.hover {
                    h.scroll_by(-6);
                }
                return;
            }
            KeyCode::PageDown => {
                if let Some(h) = &mut app.hover {
                    h.scroll_by(6);
                }
                return;
            }
            _ => app.hover = None, // fall through to normal handling
        }
    }
    // An as-you-type LSP completion popup is up: arrows / Ctrl+N·P move the
    // selection, Tab / Enter accept, Esc dismisses it; identifier keys (and `.`,
    // `:`, Backspace) fall through to the editor — the resulting edit re-filters
    // it (`App::completion_on_edit`); anything else dismisses it and is handled
    // normally.
    if app.completion.is_some() {
        let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);
        match key.code {
            KeyCode::Esc => {
                app.completion = None;
                return;
            }
            KeyCode::Tab | KeyCode::Enter => {
                // While a snippet placeholder cycle is active, Tab / Shift+Tab
                // navigate placeholders (dismissing this popup) instead of
                // accepting a completion — otherwise an as-you-type popup that
                // happened to be open races with the snippet's Tab and steals
                // it (the flaky-on-CI snippet failures). Enter still accepts.
                // SHIFT modifier honoured so Shift+Tab retreats rather than
                // inadvertently advancing forward (latent bug surfaced by the
                // 2026-06-26 review of the flake).
                if key.code == KeyCode::Tab && app.snippet_session.is_some() {
                    app.completion = None;
                    if key.modifiers.contains(KeyModifiers::SHIFT) {
                        app.snippet_prev_placeholder();
                    } else {
                        app.snippet_next_placeholder();
                    }
                } else {
                    app.completion_accept();
                }
                return;
            }
            KeyCode::Up => {
                app.completion_move(-1);
                return;
            }
            KeyCode::Down => {
                app.completion_move(1);
                return;
            }
            KeyCode::Char('p') if ctrl => {
                app.completion_move(-1);
                return;
            }
            KeyCode::Char('n') if ctrl => {
                app.completion_move(1);
                return;
            }
            // Ctrl+K / Ctrl+J — vim-style alternates for Up / Down.
            KeyCode::Char('k') if ctrl => {
                app.completion_move(-1);
                return;
            }
            KeyCode::Char('j') if ctrl => {
                app.completion_move(1);
                return;
            }
            KeyCode::PageUp => {
                app.completion_move(-8);
                return;
            }
            KeyCode::PageDown => {
                app.completion_move(8);
                return;
            }
            KeyCode::Char(c)
                if !ctrl && (c.is_alphanumeric() || c == '_' || c == '.' || c == ':') => {}
            KeyCode::Backspace => {}
            _ => app.completion = None, // fall through, handled normally
        }
    }
    // A snippet placeholder cycle is active: Tab jumps forward to the next
    // `$N` / `$0` stop; Shift-Tab walks back to the previous stop; Esc
    // dismisses. Anything else falls through (typing, arrows, etc. all work
    // normally — the session just tracks length deltas so the next Tab
    // targets the right spot).
    if app.snippet_session.is_some() {
        match key.code {
            // Shift+Tab (some terminals only synthesize BackTab; kitty etc.
            // send Tab+Shift) → previous placeholder.
            KeyCode::Tab if key.modifiers.contains(KeyModifiers::SHIFT) => {
                app.snippet_prev_placeholder();
                return;
            }
            KeyCode::Tab => {
                app.snippet_next_placeholder();
                return;
            }
            KeyCode::BackTab => {
                app.snippet_prev_placeholder();
                return;
            }
            KeyCode::Esc => {
                app.snippet_session = None;
                return;
            }
            _ => {} // fall through, handled normally
        }
    }
    // The right-click context menu steals keys: ↑↓/jk move, Enter runs, Esc closes.
    if app.context_menu.is_some() {
        match key.code {
            KeyCode::Up | KeyCode::Char('k') => app.context_menu_move(-1),
            KeyCode::Down | KeyCode::Char('j') => app.context_menu_move(1),
            KeyCode::Enter => app.context_menu_accept(),
            KeyCode::Esc => app.context_menu_cancel(),
            _ => {} // keep the menu up
        }
        return;
    }
    // The interactive replace overlay (`:%s/.../.../c`) steals keys:
    // y = replace this, n = skip, a = replace all remaining, q/Esc = quit.
    // Per-match cursor jump is handled by App; we just route the key.
    if app.replace_confirm.is_some() {
        match key.code {
            KeyCode::Char('y' | 'Y') => app.replace_confirm_yes(),
            KeyCode::Char('n' | 'N') => app.replace_confirm_no(),
            KeyCode::Char('a' | 'A') => app.replace_confirm_all(),
            KeyCode::Char('q' | 'Q') | KeyCode::Esc => app.replace_confirm_quit(),
            _ => {}
        }
        return;
    }
    // The "unsaved changes" confirm overlay steals keys: s/Enter = Save, d = Discard, c/Esc = Cancel.
    if app.close_prompt.is_some() {
        match key.code {
            KeyCode::Char('s' | 'S') | KeyCode::Enter => app.close_prompt_resolve(0),
            KeyCode::Char('d' | 'D') => app.close_prompt_resolve(1),
            KeyCode::Char('c' | 'C') | KeyCode::Esc => app.close_prompt_resolve(2),
            _ => {}
        }
        return;
    }
    // The single-line text-input overlay (commit message, …) steals keys.
    if app.prompt.is_some() {
        // R10 vscode-keyboard SEV-2 (2026-08-11) — Ctrl+Shift+P
        // from within a prompt should dismiss the prompt and open
        // the palette, matching VS Code + the earlier fix in
        // `open_command_palette`. Without this guard the prompt
        // handler ate the chord before palette-open ran, and Esc
        // then leaked stray keys into the underneath prompt.
        if key.code == KeyCode::Char('P')
            && key
                .modifiers
                .contains(KeyModifiers::CONTROL | KeyModifiers::SHIFT)
        {
            app.open_command_palette();
            return;
        }
        handle_prompt_key(app, key);
        return;
    }
    // A leader sequence in flight: walk the which-key trie until a leaf / dead end / Esc.
    if app.whichkey.is_some() {
        match key.code {
            KeyCode::Esc => app.whichkey_cancel(),
            KeyCode::Backspace => app.whichkey_cancel(),
            KeyCode::Char(c) => app.whichkey_feed(c),
            _ => {} // other keys: keep the popup up
        }
        return;
    }

    // Esc aborts an in-flight chord-chain pending WITHOUT firing the
    // inner fallback. Vim's convention — without this, `ctrl+k` then
    // Esc would still commit to `whichkey.leader` via the timeout
    // fallback, defeating the purpose of an abort.
    if matches!(key.code, KeyCode::Esc) && !app.pending_chord_seq.is_empty() {
        app.pending_chord_seq.clear();
        app.pending_chord_deadline = None;
        app.pending_chord_fallback = None;
        return;
    }

    // 2026-06-20 — Esc on bare focus with in-flight HTTP work
    // aborts. Runs AFTER overlay/cmdline gates so it doesn't
    // steal Esc from picker / prompt / cmdline cancellation,
    // but BEFORE the pane-focused handlers so users don't lose
    // the chord to a deeper handler. Idempotent — also fine if
    // no work is in flight.
    if matches!(key.code, KeyCode::Esc)
        && app.picker.is_none()
        && app.prompt.is_none()
        && app.context_menu.is_none()
        && app.no_pane_cmdline.is_none()
        && (app.http_bench_rx.is_some()
            || app.http_sync_rx.is_some()
            || app.lookup_fire_rx.is_some())
    {
        app.http_abort_all();
        return;
    }

    // App-level chords (any focus) resolve through the one keymap table — registry
    // defaults overlaid with `[keys.*]` config. These win over the focused pane;
    // all built-in defaults are modified/F-keys the editor doesn't want anyway.
    //
    // Chord-chain aware: feeds the key into the pending sequence and dispatches
    // based on the resolve_seq result. See `dispatch_chord_chain` for the full
    // state machine. Returns true if the key was consumed (no fall-through);
    // false if it wasn't (fall through to the focused handler).
    // Ctrl+; → open the ex-cmdline regardless of focus, input mode,
    // or any pending chord-chain state. Sits ABOVE dispatch_chord_chain
    // because a half-typed leader sequence in editor focus would
    // otherwise push this key onto pending_chord_seq and either fire
    // a multi-key chord or leave the cmdline open silently swallowed.
    // User-reported 2026-06-18 that Ctrl+; worked in tree focus but
    // failed in pane focus — symptom of a leader chord left dangling
    // in the pane's interaction.
    if key.code == KeyCode::Char(';') && key.modifiers.contains(KeyModifiers::CONTROL) {
        // Clear any in-flight chord chain — fresh chord, fresh state.
        app.pending_chord_seq.clear();
        app.pending_chord_deadline = None;
        app.pending_chord_fallback = None;
        if app.no_pane_cmdline.is_none() {
            app.open_ex_command_prompt();
        }
        return;
    }

    // 2026-06-19 — Ctrl+] / Ctrl+[ in a Request pane's Edit view
    // cycle the tab strip (Body/Headers/Params/Vars/Source). In
    // standard input mode, the global chord chain binds these to
    // editor.indent_line / outdent_line, which would otherwise
    // swallow them. Intercept first when we're on a Request pane
    // in Edit view so tab cycling works in both input modes.
    // api-workflow third hunt SEV-2.
    if matches!(key.code, KeyCode::Char(']') | KeyCode::Char('['))
        && key.modifiers.contains(KeyModifiers::CONTROL)
        && matches!(app.focus, Focus::Pane)
        && let Some(cur) = app.active
        && let Some(Pane::Request(rp)) = app.panes.get_mut(cur)
        && rp.view == crate::request_pane::ViewMode::Edit
    {
        rp.edit_tab = if key.code == KeyCode::Char(']') {
            rp.edit_tab.next()
        } else {
            rp.edit_tab.prev()
        };
        // When jumping to the Source tab, focus the Source field
        // so the user can immediately type. When leaving Source,
        // restore URL focus (the natural default for the other
        // tabs).
        if rp.edit_tab == crate::request_pane::EditTab::Source {
            rp.focus = crate::request_pane::EditField::Source;
        } else if rp.focus == crate::request_pane::EditField::Source {
            rp.focus = crate::request_pane::EditField::Url;
        }
        return;
    }
    // 2026-06-19 — keyboard hunt SEV-2: Ctrl+1..5 jumps directly
    // to the matching Edit-view tab. Same Request-pane-only gate as
    // Ctrl+]/Ctrl+[. Same standard-mode chord-chain bypass needed
    // for the same reason.
    if key.modifiers.contains(KeyModifiers::CONTROL)
        && matches!(
            key.code,
            KeyCode::Char('1')
                | KeyCode::Char('2')
                | KeyCode::Char('3')
                | KeyCode::Char('4')
                | KeyCode::Char('5')
                | KeyCode::Char('6')
        )
        && matches!(app.focus, Focus::Pane)
        && let Some(cur) = app.active
        && let Some(Pane::Request(rp)) = app.panes.get_mut(cur)
        && rp.view == crate::request_pane::ViewMode::Edit
    {
        use crate::request_pane::EditTab;
        rp.edit_tab = match key.code {
            KeyCode::Char('1') => EditTab::Body,
            KeyCode::Char('2') => EditTab::Headers,
            KeyCode::Char('3') => EditTab::Params,
            KeyCode::Char('4') => EditTab::Auth,
            KeyCode::Char('5') => EditTab::Vars,
            KeyCode::Char('6') => EditTab::Source,
            _ => rp.edit_tab,
        };
        if rp.edit_tab == EditTab::Source {
            rp.focus = crate::request_pane::EditField::Source;
        } else if rp.focus == crate::request_pane::EditField::Source {
            rp.focus = crate::request_pane::EditField::Url;
        }
        return;
    }

    // nvchad-round-15 SEV-2 F2 2026-07-15 — Ctrl+B in vim Normal /
    // Visual mode is canonical PageUp (since 1976 vi). The global
    // keymap binds it to `view.toggle_tree` — correct in standard
    // mode, but in vim Normal mode the vim.rs handler at :2839
    // owns Ctrl+B. Without this bypass, `dispatch_chord_chain`
    // below would fire the global toggle first and the vim.rs
    // branch is dead code. Skip chord_chain when the current key
    // is a vim-reserved Normal-mode chord so it falls through to
    // the focused input handler naturally. Matches the same
    // reasoning as the existing round-10 Ctrl+F fix (vim.rs side).
    let vim_reserves_key = {
        let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);
        let vim_normal_or_visual = matches!(
            app.editing_mode(),
            crate::input::EditingMode::Normal
                | crate::input::EditingMode::Visual
                | crate::input::EditingMode::VisualLine
                | crate::input::EditingMode::VisualBlock
        );
        vim_normal_or_visual
            && ctrl
            && !key.modifiers.contains(KeyModifiers::ALT)
            // R7 nvchad SEV-2 2026-08-09 — extended from `b`/`B`
            // (page-back) to also include `o`/`O`/`i`. Vim owns:
            //   Ctrl+B / Ctrl+F — page back/forward
            //   Ctrl+O / Ctrl+I — jumplist back/forward
            // Without this bypass, the global keymap fires
            // `picker.files` (Ctrl+O bound in command.rs:2550) and
            // Ctrl+I is a no-op even though vim.rs at :2717 returns
            // `AppCommand::RunCommand("nav.back")` for Ctrl+O — dead
            // code because chord_chain got there first.
            && matches!(
                key.code,
                KeyCode::Char('b')
                    | KeyCode::Char('B')
                    | KeyCode::Char('o')
                    | KeyCode::Char('O')
                    | KeyCode::Char('i')
                    | KeyCode::Char('I')
                    // R10 nvchad SEV-3 — Ctrl+W is vim's window-
                    // prefix chord (Ctrl+W h/j/k/l/w/q ...).
                    // Standard mode's `Ctrl+W = buffer.close` used
                    // to win globally; now vim keeps ownership of
                    // Ctrl+W so the chord chain reaches
                    // handle_normal's Ctrl+W arm.
                    | KeyCode::Char('w')
                    | KeyCode::Char('W')
            )
    };

    // keyboard-round-14 SEV-2 2026-07-16 — when a Pty pane is
    // focused, forward the shell-critical ctrl chords straight to
    // the child instead of letting the global keymap eat them.
    // Was: Ctrl+D fired `editor.add_cursor_at_next_word` even from
    // a focused shell (breaking exit); Ctrl+K fired the whichkey
    // leader (breaking kill-line); Ctrl+R fired `find.find`
    // (breaking reverse-history-search); Ctrl+N/P fired autocomplete
    // move (breaking readline history); Ctrl+F fired
    // `find.find` (breaking readline forward-char). These are the
    // 6 chords a shell user hits within seconds of dropping into an
    // integration. Sits above dispatch_chord_chain so the key falls
    // through to the focused-Pty handler naturally.
    //
    // Exceptions:
    //  * Ctrl+F in a claude-code pane keeps its filename-inject
    //    (handled in pane.rs before the pty write path).
    //  * Ctrl+` still toggles the scratch terminal (kb-round-12).
    //  * Ctrl+C / Ctrl+U / Ctrl+A already fell through correctly.
    let pty_reserves_key = {
        let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);
        let active_is_pty = app.focus == crate::focus::Focus::Pane
            && app
                .active
                .and_then(|i| app.panes.get(i))
                .is_some_and(|p| matches!(p, crate::pane::Pane::Pty(_)));
        active_is_pty
            && ctrl
            && !key.modifiers.contains(KeyModifiers::ALT)
            && !key.modifiers.contains(KeyModifiers::SHIFT)
            && matches!(
                key.code,
                KeyCode::Char('d')
                    | KeyCode::Char('D')
                    | KeyCode::Char('k')
                    | KeyCode::Char('K')
                    | KeyCode::Char('n')
                    | KeyCode::Char('N')
                    | KeyCode::Char('p')
                    | KeyCode::Char('P')
                    | KeyCode::Char('r')
                    | KeyCode::Char('R')
                    | KeyCode::Char('f')
                    | KeyCode::Char('F')
            )
    };

    // vscode-user-keyboard SEV-2: when the chord chain bottoms out
    // and fires its fallback (typically `whichkey.leader`), the
    // current key was being dropped instead of fed into the just-
    // opened whichkey overlay — making `<leader>tr` need three
    // keys (`Ctrl+K t t r`) instead of two. Now: if whichkey was
    // NOT open before chord-dispatch but IS open after, re-route
    // the current key to the overlay's char-feed.
    let whichkey_was_open = app.whichkey.is_some();
    // 2026-07-22 fix: bare `Delete` was bound globally to
    // `file.delete` (with no Focus::Tree gate), so pressing Delete
    // in the Request pane or the code editor teleported to the
    // tree's file-delete-confirm dialog instead of forward-
    // deleting a char at the caret. Skip the chord-chain machinery
    // for lone Delete when focus is NOT on the tree AND no chord
    // is pending — pane handlers own the key in that case.
    let delete_owns_focus = matches!(key.code, KeyCode::Delete)
        && key.modifiers.is_empty()
        && !matches!(app.focus, crate::focus::Focus::Tree)
        && app.pending_chord_seq.is_empty();
    // R10 nvchad SEV-2 2026-08-10 — when vim's `:` cmdline is open,
    // ALL keys belong to the cmdline. Was: space in `:set nowrap`
    // got eaten by dispatch_chord_chain as a leader chord, and the
    // cmdline saw `:setnowrap`. Every other char (`s`, `e`, `t`,
    // `n`, ...) was fine because the chord-chain fell through for
    // non-bound keys — but leader = space, so space specifically
    // got trapped.
    let vim_cmdline_open = app
        .active
        .and_then(|i| app.panes.get(i))
        .and_then(|p| p.as_editor())
        .map(|b| b.input.is_cmdline_open())
        .unwrap_or(false);
    // R11 claude-agents SEV-2 + 2026-08-10 e2e-fix — bare `space` is
    // the leader chord, but leader dispatch must NOT fire when the
    // focused surface is a text-input context: (1) an editor in
    // Insert / Replace mode or modeless (Standard) — typing " " in
    // a buffer used to get eaten and `HELLO fn main` became
    // `HELLOfn main`; (2) the Claude Agents dashboard, which uses
    // bare space as its multi-select toggle; (3) any non-editor
    // pane whose handler will treat bare space as text (DAP REPL,
    // HTTP request body, settings picker filter, …). The safe
    // gate is: bare space only reaches chord chain when vim is in
    // a modal state (Normal / Visual*) — that's the ONLY context
    // where `<space>ff` should route to the leader. Everywhere
    // else, bare space is text input.
    let vim_op_pending = app
        .active
        .and_then(|i| app.panes.get(i))
        .and_then(|p| p.as_editor())
        .map(|b| b.input.is_op_pending())
        .unwrap_or(false);
    let pane_wants_bare_space = matches!(key.code, KeyCode::Char(' '))
        && key.modifiers.is_empty()
        && (
            // 2026-08-18 (#968 reviewer follow-up) — Tree focus was
            // previously EXCLUDED from the bypass so `<space>ff`
            // leader chord could work from the tree, but that meant
            // pane.rs::handle_tree_key's Space arm (documented as
            // "activate row") was unreachable. Now Tree focus bypasses
            // the chord chain: Space activates the focused row, and
            // leader chords are reached via Ctrl+K (which also opens
            // whichkey) or by first focusing a pane.
            matches!(app.focus, crate::focus::Focus::Tree)
                || vim_op_pending
                || !matches!(
                    app.editing_mode(),
                    crate::input::EditingMode::Normal
                        | crate::input::EditingMode::Visual
                        | crate::input::EditingMode::VisualLine
                        | crate::input::EditingMode::VisualBlock
                )
        );
    if !vim_reserves_key
        && !pty_reserves_key
        && !delete_owns_focus
        && !vim_cmdline_open
        && !pane_wants_bare_space
        && dispatch_chord_chain(app, key)
    {
        return;
    }
    if !whichkey_was_open
        && app.whichkey.is_some()
        && let KeyCode::Char(c) = key.code
    {
        app.whichkey_feed(c);
        return;
    }

    // When the no-pane cmdline is open, it owns every keystroke
    // regardless of which side of the focus boundary the user
    // started typing from. Without this gate a pane-focused user
    // who hit Ctrl+; would land in the cmdline visually but their
    // typing would still go to the editor.
    if app.no_pane_cmdline.is_some() {
        let shift = key.modifiers.contains(KeyModifiers::SHIFT);
        match key.code {
            KeyCode::Esc => app.no_pane_cmdline_cancel(),
            // Enter runs whatever is currently in the cmdline.
            // 2026-06-19 — earlier impl auto-substituted the
            // popup match, but that breaks legitimate vim
            // abbreviations (`:reg`, `:wq`, …). Users wanting
            // the popup match use Tab/click first to put it
            // into the line.
            KeyCode::Enter => {
                // 2026-06-24 — if the user has navigated the popup
                // with ↑/↓/Tab (selected index != 0), accept the
                // highlighted match before committing. Index 0 is
                // the auto-selected first match — leaving it
                // unaccepted preserves the vim convention where
                // `:reg<Enter>` fires the literal `:reg` instead
                // of whatever `:registers`/etc. matched first.
                if app.cmdline_popup_is_showing() && app.cmdline_popup_selected > 0 {
                    app.cmdline_popup_accept_current();
                }
                app.no_pane_cmdline_commit();
            }
            // 2026-06-19 — popup nav. Tab / Down advance the
            // highlighted match; Shift+Tab / Up retreat. Rewrites
            // the cmdline to the new selection so Enter fires
            // whatever's highlighted. No-op when popup isn't
            // showing (compute returns <2 matches).
            KeyCode::Tab if shift => app.cmdline_popup_move(-1),
            KeyCode::Tab => app.cmdline_popup_move(1),
            KeyCode::Down => app.cmdline_popup_move(1),
            KeyCode::Up => app.cmdline_popup_move(-1),
            KeyCode::PageDown => app.cmdline_popup_move(8),
            KeyCode::PageUp => app.cmdline_popup_move(-8),
            KeyCode::Home => app.cmdline_popup_move_to(0),
            KeyCode::End => app.cmdline_popup_move_to(usize::MAX),
            _ => {
                // 2026-08-08 — common Ctrl+U / Ctrl+W / Ctrl+V /
                // Backspace shortcuts on the `:` cmdline. Uses the
                // shared filter helper so the routing matches
                // every other append-only surface.
                if let Some(buf) = app.no_pane_cmdline.as_mut() {
                    let r = crate::ui::text_input::handle_filter_shortcut(
                        key,
                        buf,
                        Some(&mut app.clipboard),
                    );
                    if r == crate::ui::text_input::TextKeyResult::Handled {
                        return;
                    }
                }
                if let KeyCode::Char(c) = key.code
                    && !key.modifiers.contains(KeyModifiers::CONTROL)
                {
                    app.no_pane_cmdline_push_char(c);
                }
            }
        }
        return;
    }

    // Snapshot cursor position BEFORE dispatch so we can record a
    // vim-jumplist entry after any key that produced a "big jump"
    // (>= JUMP_ROW_THRESHOLD rows away from the previous position,
    // OR a file switch). Fix 2026-07-07 — was: only `open_path`
    // pushed nav_back, so within-file jumps like `G`/`gg`/`{N}G`/
    // `/pattern` never made Ctrl+O go anywhere.
    let before = app.current_nav_point();
    // #1076 (2026-08-19) — global Ctrl+W (buffer.close) intercept for
    // Standard mode. Prior #1037 fix routed Ctrl+W through
    // `handle_pane_key`'s view-only branch, but many pane-openers
    // (`open_claude_usage_pane`, `open_codex_usage_pane`,
    // `open_spend_report_pane`, `open_integration_detail_pane`, …)
    // call `reveal_pane` without also shifting focus to
    // `Focus::Pane`. If the user opens Claude Usage from the palette
    // while focused on the tree, Ctrl+W goes to `handle_tree_key`
    // which has no close branch → key gets eaten silently.
    //
    // In standard/VS Code mode Ctrl+W is unambiguously "close the
    // active pane" no matter where focus is (the palette + menu-bar
    // both bind it to `buffer.close`). Route it directly here so it
    // stops depending on where the user happened to click last.
    //
    // Vim mode preserved: Ctrl+W in vim is the window-navigation
    // prefix, handled downstream — leave it to the pane router.
    if key.code == KeyCode::Char('w')
        && key.modifiers == KeyModifiers::CONTROL
        && !app.ctrl_w_is_window_nav()
        && app.active.is_some()
    {
        app.close_active_pane();
        return;
    }
    match app.focus {
        Focus::Tree => handle_tree_key(app, key),
        Focus::Pane => handle_pane_key(app, key),
        // Right panel behaves like a pane for key routing — the
        // pane handler already reads `app.right_panel_focus_active`
        // when dispatching outline/diag/grep keys.
        Focus::RightPanel => handle_pane_key(app, key),
        Focus::BottomPanel => handle_pane_key(app, key),
    }
    if let Some(before) = before
        && let Some(after) = app.current_nav_point()
    {
        const JUMP_ROW_THRESHOLD: usize = 3;
        let big_row_move =
            before.path == after.path && before.row.abs_diff(after.row) >= JUMP_ROW_THRESHOLD;
        let file_switched = before.path != after.path;
        if big_row_move || file_switched {
            app.record_within_file_jump(before);
        }
    }
    // Reset AFTER the recorder runs. `record_within_file_jump`
    // consults this flag to decide whether to clear nav_forward;
    // leaving it stale would suppress the clear on the NEXT key's
    // fresh jump. nvchad SEV-2 2026-07-10.
    app.nav_jump_in_progress = false;
}

// T-1: chord-chain dispatch + tick + timeout const moved to src/tui/chord.rs.
// Re-exported above (`pub use chord::*`) so existing call sites work.

// T-3: overlay key handlers moved to src/tui/handlers/overlay.rs.
// Imported above so existing dispatch_key call sites work.

// T-4: handle_tree_key, handle_pane_key, handle_md_preview_key,
// handle_diff_key, handle_request_key, is_view_only_pane moved to
// src/tui/handlers/pane.rs (imported above).

/// Shell out `mixr --command <verb>` for the statusline transport
/// chip. Detached + non-blocking so a slow mixr-side handler can't
/// stutter the render loop; failures are logged and otherwise
/// swallowed so an absent / not-on-PATH mixr doesn't surface as a
/// scary toast for users who don't have mixr installed at all.
/// The `mixr --command` path writes to `~/.mixr/command` (an atomic
/// file write) which a running mixr polls — nothing else is needed.
pub(crate) fn send_mixr_command(verb: &str) {
    let result = std::process::Command::new("mixr")
        .args(["--command", verb])
        .spawn();
    if let Err(e) = result {
        eprintln!("mnml: send_mixr_command({verb:?}) failed: {e}");
    }
}

/// Drive Apple Music / Spotify via AppleScript for the statusline
/// transport chips. `app_name` is the source string mnml reads from
/// `now_playing` (`"Music"` / `"Spotify"`), `verb` is an AppleScript
/// transport command — `"playpause"`, `"next track"`, etc.
///
/// Detached + non-blocking; failures log and are swallowed so a user
/// without the named app installed doesn't get a scary toast.
pub(crate) fn send_macos_player(app_name: &str, verb: &str) {
    // Whitelist the source names we recognize so a malformed
    // `np.source` can't be coerced into arbitrary AppleScript.
    let app = match app_name {
        s if s.eq_ignore_ascii_case("Music") => "Music",
        s if s.eq_ignore_ascii_case("Spotify") => "Spotify",
        _ => return,
    };
    let script = format!("tell application \"{app}\" to {verb}");
    let result = std::process::Command::new("osascript")
        .args(["-e", &script])
        .spawn();
    if let Err(e) = result {
        eprintln!("mnml: send_macos_player({app_name:?}, {verb:?}) failed: {e}");
    }
}