mnml-rs 0.2.14

//! Hover-tooltip overlay — a small floating label rendered above (or below) the
//! currently-hovered clickable chip, ~500ms after the mouse settles on it. Closes
//! the discoverability loop: lets users learn what each chip does without trial-
//! and-error or memorizing the README.
//!
//! `App.hover_chip` carries `(HoverChip, Instant)`; `tui::dispatch_mouse` updates
//! it on every `MouseEventKind::Moved`. This module reads it and paints if the
//! delay has elapsed.

use ratatui::Frame;
use ratatui::layout::Rect;
use ratatui::style::{Modifier, Style};
use ratatui::text::Line;
use ratatui::widgets::{Clear, Paragraph};

use crate::HoverChip;
use crate::app::{App, HOVER_TOOLTIP_DELAY_MS};
use crate::ui::theme;

/// Render the tooltip overlay if a chip has been stably hovered for at least
/// `HOVER_TOOLTIP_DELAY_MS`. Called after every other UI layer so the popup
/// sits on top.
pub fn draw(frame: &mut Frame, app: &App, screen: Rect) {
    // User opt-out (`[ui] hover_tooltip = false` /
    // `view.toggle_hover_tooltip`). The bottom-left hover-help panel
    // covers the same targets in more detail, so users who dislike
    // the popup-near-cursor affordance can turn it off entirely and
    // rely on the panel. Default stays `true` for back-compat.
    if !app.config.ui.hover_tooltip {
        return;
    }
    let Some((chip, since)) = app.hover_chip else {
        return;
    };
    if since.elapsed().as_millis() < HOVER_TOOLTIP_DELAY_MS as u128 {
        return;
    }
    let Some((anchor, label, sublabel)) = describe(chip, app) else {
        return;
    };
    // Tooltip uses the shared menu chrome (square border, default fg,
    // bg2 fill). Sublabel may be multi-line — split on '\n' so
    // rich tooltips (Sessions panel) can show a block of lines.
    let prim_w = label.chars().count();
    let sub_lines: Vec<String> = sublabel
        .as_deref()
        .map(|s| s.split('\n').map(|l| l.to_string()).collect())
        .unwrap_or_default();
    let sub_max_w = sub_lines
        .iter()
        .map(|l| l.chars().count())
        .max()
        .unwrap_or(0);
    // Cap width at ~72 cols so a very long grid line doesn't blow
    // out the tooltip; each line is truncated below.
    let inner_w = prim_w.max(sub_max_w).min(72) as u16;
    let w = inner_w + 4; // 2 padding + 2 borders
    // Height: 1 primary + N sublabel lines + 2 borders.
    let h: u16 = if sub_lines.is_empty() {
        3
    } else {
        (2 + 1 + sub_lines.len() as u16).min(screen.height)
    };
    // Anchor: place above the chip when there's room; else below.
    let want_y = anchor.y.saturating_sub(h);
    let y = if anchor.y >= h {
        want_y
    } else {
        (anchor.y + 1).min(screen.height.saturating_sub(h))
    };
    let x = anchor.x.min(screen.width.saturating_sub(w)).max(screen.x);
    let area = Rect {
        x,
        y: y.max(screen.y),
        width: w.min(screen.width),
        height: h.min(screen.height),
    };
    let t = theme::cur();
    frame.render_widget(Clear, area);
    let mut lines: Vec<Line<'static>> = Vec::new();
    lines.push(Line::styled(
        format!(" {label} "),
        Style::default()
            .fg(t.fg)
            .bg(t.bg2)
            .add_modifier(Modifier::BOLD),
    ));
    let cap = inner_w as usize;
    for s in sub_lines {
        // Truncate any line longer than the tooltip inner width.
        let text: String = if s.chars().count() > cap {
            let take = cap.saturating_sub(1);
            let mut out: String = s.chars().take(take).collect();
            out.push('…');
            out
        } else {
            s
        };
        // Blank sub-line separator (`""`) → paint as a blank row
        // in the tooltip bg (nice visual break between sections).
        if text.is_empty() {
            lines.push(Line::styled(" ", Style::default().bg(t.bg2)));
        } else {
            lines.push(Line::styled(
                format!(" {text} "),
                Style::default().fg(t.comment).bg(t.bg2),
            ));
        }
    }
    let block = crate::ui::design_tokens::popup_menu("");
    frame.render_widget(Paragraph::new(lines).block(block), area);
}

/// Public wrapper that drops the anchor rect — used by the
/// hover-help footer (`ui/hover_help.rs`), which paints a fixed
/// row at the bottom of the screen and only needs the text.
pub fn describe_text(chip: HoverChip, app: &App) -> Option<(String, Option<String>)> {
    describe(chip, app).map(|(_rect, primary, secondary)| (primary, secondary))
}

/// `(anchor_rect, primary_line, secondary_line)`. None ⇒ chip's rect isn't
/// registered this frame (chip is hidden, terminal too narrow, etc.) — bail.
fn describe(chip: HoverChip, app: &App) -> Option<(Rect, String, Option<String>)> {
    match chip {
        HoverChip::StatuslineMode => {
            // code-reviewer S1-1 — variant-match moved to the
            // enum's tooltip_label() method so the UI layer doesn't
            // branch on input mode (spine rule). Tree-focus is a
            // focus state, not a mode — checked via the focus side.
            let mode_desc = if matches!(app.focus, crate::focus::Focus::Tree)
                && app.editing_mode().label().is_none()
            {
                "blue = TREE focus"
            } else {
                app.editing_mode().tooltip_label()
            };
            Some((
                app.rects.statusline_mode_chip?,
                format!("click: toggle vim ⇄ standard · {mode_desc}"),
                Some("right-click: input-style menu".into()),
            ))
        }
        HoverChip::StatuslineBranch => {
            // Branch chip carries the git counts; explain the glyphs.
            let g = app.git.snapshot();
            let mut extra: Vec<&'static str> = Vec::new();
            if g.added > 0 {
                extra.push("+ added");
            }
            if g.changed > 0 {
                extra.push("● changed");
            }
            if g.removed > 0 {
                extra.push("- removed");
            }
            if g.conflicts > 0 {
                extra.push("⚠ conflicts");
            }
            if g.ahead > 0 {
                extra.push("⇡ ahead");
            }
            if g.behind > 0 {
                extra.push("⇣ behind");
            }
            let label = if extra.is_empty() {
                "click: open commit graph".to_string()
            } else {
                format!("click: graph · {}", extra.join(" "))
            };
            Some((
                app.rects.statusline_branch_chip?,
                label,
                Some("right-click: git ops menu".into()),
            ))
        }
        HoverChip::StatuslineWorkspace => {
            let primary = if app.repos.len() > 1 {
                "click: switch repo"
            } else {
                "click: repo / worktree menu"
            };
            Some((
                app.rects.statusline_workspace_chip?,
                primary.into(),
                Some("right-click: workspace menu".into()),
            ))
        }
        HoverChip::StatuslineClock => Some((
            app.rects.statusline_clock_chip?,
            "click: local ⇄ UTC".into(),
            Some("right-click: clock menu".into()),
        )),
        HoverChip::StatuslineLsp => Some((
            app.rects.statusline_lsp_chip?,
            "click: :LspStatus (running servers)".into(),
            None,
        )),
        HoverChip::StatuslineWrap => Some((
            app.rects.statusline_wrap_chip?,
            // R12 vscode-mouse SEV-3 — tooltip used to say "toggle
            // word wrap" while the menu + palette + InfoView all
            // agreed on "line wrap". Aligned to the menu/palette
            // wording so search + muscle memory hit the same term.
            "click: toggle line wrap".into(),
            None,
        )),
        HoverChip::StatuslineAiClaude => Some((
            app.rects.statusline_ai_claude_chip?,
            // 2026-08-16 — was a full hover-overlay; retired in
            // favor of `Pane::ClaudeUsage`, so the chip now just
            // hints the click target like every other chip.
            "click: open Claude usage pane".into(),
            None,
        )),
        HoverChip::StatuslineAiCodex => Some((
            app.rects.statusline_ai_codex_chip?,
            // 2026-08-16 — was a toast-only chip; now opens the
            // dedicated `Pane::CodexUsage` after the AiUsage split.
            "click: open Codex usage pane".into(),
            None,
        )),
        HoverChip::StatuslineAutosave => Some((
            app.rects.statusline_autosave_chip?,
            "click: show autosave config".into(),
            None,
        )),
        HoverChip::StatuslineFilesize => Some((
            app.rects.statusline_filesize_chip?,
            "click: :Stat (file metadata)".into(),
            None,
        )),
        HoverChip::StatuslineLnCol => Some((
            app.rects.statusline_lncol_chip?,
            "click: goto line".into(),
            None,
        )),
        // 2026-08-01 (P2) — HoverChip::LauncherIcon match deleted.
        HoverChip::IntegrationIcon(idx) => {
            let icon = app.config.ui.integration_icons.get(idx)?;
            let &(rect, _) = app
                .rects
                .integration_icon_rects
                .iter()
                .find(|(_, i)| *i == idx)?;
            let label = icon
                .label
                .clone()
                .unwrap_or_else(|| format!("click: {}", icon.command));
            Some((rect, label, None))
        }
        HoverChip::WorkspaceHeader => {
            let rect = app.rects.tree_toggle?;
            Some((rect, app.workspace.display().to_string(), None))
        }
        HoverChip::ExtraWorkspaceHeader(idx) => {
            let rect = app
                .rects
                .extra_workspace_toggles
                .iter()
                .find(|(_, i)| *i == idx)
                .map(|(r, _)| *r)?;
            let path = app.extra_workspaces.get(idx)?.root.display().to_string();
            Some((rect, path, None))
        }
        HoverChip::TreeIcon(cmd_id) => {
            let &(rect, _) = app
                .rects
                .tree_icon_buttons
                .iter()
                .find(|(_, id)| *id == cmd_id)?;
            let label: std::borrow::Cow<'static, str> = match cmd_id {
                "view.add_workspace" => "add workspace folder".into(),
                "file.new" => "new file".into(),
                "file.new_folder" => "new folder".into(),
                "tree.refresh" => "refresh tree".into(),
                "tree.collapse_all" => "collapse all".into(),
                "tree.toggle_collapse_all" => {
                    if app.tree.is_fully_collapsed() {
                        "expand all".into()
                    } else {
                        "collapse all".into()
                    }
                }
                "picker.files" => "search files".into(),
                "integrations.add" => "add integration".into(),
                other => other.into(),
            };
            Some((rect, label.into_owned(), None))
        }
        HoverChip::ActivityBarIcon(section) => {
            let &(rect, _) = app
                .rects
                .activity_bar_icons
                .iter()
                .find(|(_, s)| *s == section)?;
            // #polish 2026-07-06 — enrich the single-word label
            // with a click hint + description of what the section
            // shows. Users hover to LEARN, not just to confirm
            // the name — the extra context closes the loop.
            use crate::app::ActivitySection;
            let (primary, secondary): (&str, Option<&str>) = match section {
                ActivitySection::Explorer => (
                    "click: Files rail",
                    Some("workspace file tree · new file / folder"),
                ),
                ActivitySection::Search => {
                    ("click: Search rail", Some("ripgrep across the workspace"))
                }
                ActivitySection::Git => (
                    "click: Git graph",
                    Some("commits · branches · worktrees · stash"),
                ),
                ActivitySection::Debug => (
                    "click: Debug rail",
                    Some("breakpoints · watches · call stack"),
                ),
                ActivitySection::Integrations => (
                    "click: Integrations rail",
                    Some("browser / mixr / integration tools · + to add"),
                ),
                ActivitySection::Sessions => (
                    "click: Sessions rail",
                    Some("Claude / Codex / shell sessions"),
                ),
                ActivitySection::Agents => (
                    "click: Agents rail",
                    Some("running Claude Code + Codex sessions"),
                ),
                ActivitySection::CloudAgents => (
                    "click: Cloud Agents rail",
                    Some("ECS runner + Anthropic managed sessions"),
                ),
                ActivitySection::Http => (
                    "click: HTTP rail",
                    Some("requests · recent · captured · envs · collections"),
                ),
                ActivitySection::Notes => (
                    "click: Notes rail",
                    Some(".mnml/notes/*.md persistent scratch"),
                ),
                ActivitySection::Todos => (
                    "click: TODOs rail",
                    Some("TODO / FIXME / XXX / HACK / REVIEW hits"),
                ),
                ActivitySection::Findings => (
                    "click: Findings rail",
                    Some(".mnml/findings/*.md tester / review reports"),
                ),
                ActivitySection::Mount(_) => {
                    let (_, _, label, _) = section.meta();
                    return Some((rect, label.to_string(), None));
                }
                ActivitySection::LauncherIcon(idx) => {
                    // Show the pinned integration's tooltip.
                    let label = app
                        .config
                        .ui
                        .activity_bar_pinned_integrations
                        .get(idx as usize)
                        .and_then(|id| app.config.ui.integration_icons.iter().find(|i| &i.id == id))
                        .and_then(|i| i.label.clone())
                        .unwrap_or_else(|| "Pinned integration".to_string());
                    return Some((rect, label, Some("click: launch".to_string())));
                }
            };
            Some((rect, primary.to_string(), secondary.map(String::from)))
        }
        HoverChip::GitGraphCommitMsg {
            pane_id,
            commit_idx,
        } => {
            let rect = app
                .rects
                .git_graph_subject_cells
                .iter()
                .find(|(_, pid, ci)| *pid == pane_id && *ci == commit_idx)
                .map(|(r, _, _)| *r)?;
            let g = match app.panes.get(pane_id) {
                Some(crate::pane::Pane::GitGraph(g)) => g,
                _ => return None,
            };
            let c = g.commits.get(commit_idx)?;
            let subj = c.subject.clone();
            // Wrap long subjects at ~80 chars for readability.
            let display = if subj.chars().count() > 80 {
                subj.chars().take(80).collect::<String>() + "…"
            } else {
                subj
            };
            let hint = format!("{} · {}", c.author, c.short);
            Some((rect, display, Some(hint)))
        }
        HoverChip::GitGraphLane {
            pane_id,
            commit_idx,
            lane_idx,
        } => {
            // qa-feature 2026-06-30 — walk newer commits (lower
            // commit_idx) in the same lane until we find one with
            // a branch ref, then use that ref name as the lane
            // label. Falls back to a subject preview if nothing
            // named is found. `rect` is the specific lane cell.
            let rect = app
                .rects
                .git_graph_lane_cells
                .iter()
                .find(|(_, pid, ci, li)| *pid == pane_id && *ci == commit_idx && *li == lane_idx)
                .map(|(r, _, _, _)| *r)?;
            let g = match app.panes.get(pane_id) {
                Some(crate::pane::Pane::GitGraph(g)) => g,
                _ => return None,
            };
            // Walk from `commit_idx` upward (i.e. toward index 0
            // = newest) inside the same lane. Include the anchor
            // commit itself first.
            let mut label = None;
            let mut idx = commit_idx;
            while idx < g.commits.len() {
                let c = &g.commits[idx];
                let in_lane = c.graph.get(lane_idx).is_some_and(|cell| cell.ch != ' ');
                if !in_lane {
                    break;
                }
                if let Some(r) = c.refs.iter().find(|r| {
                    matches!(
                        r.kind,
                        crate::git::log::RefKind::LocalBranch
                            | crate::git::log::RefKind::RemoteBranch
                            | crate::git::log::RefKind::Head
                    )
                }) {
                    label = Some(r.name.clone());
                    break;
                }
                if idx == 0 {
                    break;
                }
                idx -= 1;
            }
            let main = label.unwrap_or_else(|| {
                g.commits
                    .get(commit_idx)
                    .map(|c| {
                        let subj = c.subject.chars().take(60).collect::<String>();
                        format!("no branch name · {subj}")
                    })
                    .unwrap_or_else(|| "lane".to_string())
            });
            let hint = g
                .commits
                .get(commit_idx)
                .map(|c| format!("commit: {} · {}", c.short, c.author));
            Some((rect, main, hint))
        }
        HoverChip::StatuslineNowPlaying => {
            let rect = app.rects.statusline_mixr_chip?;
            // qa-6th mouse SEV-3 2026-06-29: was returning None
            // when nothing is playing, so the chip had no tooltip
            // and felt undiscoverable. Fall back to a generic
            // affordance string.
            let main = match app.now_playing.as_ref() {
                Some(np) => {
                    let track = if np.track.is_empty() {
                        "(no track)".to_string()
                    } else {
                        np.track.clone()
                    };
                    let source = if np.source.is_empty() {
                        "now playing".to_string()
                    } else {
                        np.source.clone()
                    };
                    format!("{source}: {track}")
                }
                None => "mixr".to_string(),
            };
            Some((
                rect,
                main,
                Some("click: open mixr · right-click: menu".into()),
            ))
        }
        HoverChip::PaletteSidebarButton => {
            let rect = app.rects.palette_sidebar_button?;
            let state = if app.tree_visible { "open" } else { "off" };
            Some((
                rect,
                format!("file tree: {state}"),
                Some("click: toggle file tree (Ctrl+B)".into()),
            ))
        }
        HoverChip::PaletteRightPanelButton => {
            let rect = app.rects.palette_right_panel_button?;
            let state = if app.right_panel_visible {
                "open"
            } else {
                "off"
            };
            Some((
                rect,
                format!("right panel: {state}"),
                Some("click: toggle right side panel (Ctrl+Shift+B)".into()),
            ))
        }
        HoverChip::StatuslineStress | HoverChip::PaletteStress => {
            let rect = if matches!(chip, HoverChip::StatuslineStress) {
                app.rects.statusline_stress_chip?
            } else {
                app.rects.palette_stress_chip?
            };
            let score = app.stress_score();
            let mut sorted: Vec<u16> = app.frame_times_ms.iter().copied().collect();
            sorted.sort_unstable();
            let p50 = if sorted.is_empty() {
                0
            } else {
                sorted[sorted.len() / 2]
            };
            let p95 = if sorted.is_empty() {
                0
            } else {
                sorted[(sorted.len() * 95) / 100]
            };
            let max = sorted.last().copied().unwrap_or(0);
            Some((
                rect,
                format!("stress: {score}/100 · p50 {p50}ms · p95 {p95}ms · max {max}ms"),
                Some(format!(
                    "{} samples · right-click for actions",
                    app.frame_times_ms.len()
                )),
            ))
        }
        HoverChip::SplitDivider => {
            let idx = app.hover_divider_idx?;
            let d = app.rects.split_dividers.get(idx)?;
            let dir_label = match d.dir {
                crate::layout::SplitDir::Horizontal => "horizontal split",
                crate::layout::SplitDir::Vertical => "vertical split",
            };
            Some((
                d.rect,
                format!("{dir_label} divider"),
                Some("drag to resize · double-click to equalize".into()),
            ))
        }
        HoverChip::PaletteBackButton => {
            let rect = app.rects.palette_back_button?;
            let n = app.panes.len();
            // #polish 2026-07-06 — hint at what "back" cycles through
            // (previous open buffer in MRU order) + note when there's
            // nothing to cycle to.
            // mouse-round-9 SEV-3 2026-07-11 — add `click:` / `right-click:`
            // prefixes so the tooltip reads as affordances, not
            // status text.
            // mouse-round-7 SEV-3 2026-07-12 — was pure status text
            // when n<=1; now leads with the click hint and adds a
            // disabled-state subtitle so users see the intent even
            // when nothing to cycle to.
            let primary = if n <= 1 {
                "back to previous buffer (Ctrl+[)".to_string()
            } else {
                format!("click: prev buffer (MRU) · {n} open")
            };
            let subtitle = if n <= 1 {
                "disabled — no other buffers · right-click: nav history menu".to_string()
            } else {
                "right-click: nav history menu".to_string()
            };
            Some((rect, primary, Some(subtitle)))
        }
        HoverChip::PaletteForwardButton => {
            let rect = app.rects.palette_forward_button?;
            let n = app.panes.len();
            // mouse-round-7 SEV-3 2026-07-12 — mirror of back button.
            let primary = if n <= 1 {
                "forward to next buffer (Ctrl+])".to_string()
            } else {
                format!("click: next buffer (MRU) · {n} open")
            };
            let subtitle = if n <= 1 {
                "disabled — no other buffers · right-click: nav history menu".to_string()
            } else {
                "right-click: nav history menu".to_string()
            };
            Some((rect, primary, Some(subtitle)))
        }
        HoverChip::PaletteSearchChip => {
            let rect = app.rects.palette_search_chip?;
            // mouse-round-7 SEV-3 2026-07-12 — was `Cmd+P` (macOS-
            // only leak from the copy). mnml's primary modifier is
            // Ctrl everywhere.
            Some((
                rect,
                "command palette".to_string(),
                Some("click: open files, commands, recent (Ctrl+P)".into()),
            ))
        }
        HoverChip::PaletteDropdownButton => {
            let rect = app.rects.palette_dropdown_button?;
            // mouse-round-7 SEV-3 2026-07-12 — was bare "recent
            // files"; now a full click hint + right-click subtitle.
            Some((
                rect,
                "recent files".to_string(),
                Some("click: open recent · right-click: open menu".into()),
            ))
        }
        HoverChip::PaletteAddIntegration => {
            let rect = app.rects.palette_add_integration_button?;
            Some((
                rect,
                "add integration".into(),
                Some("click: discovery overlay (integrations + custom)".into()),
            ))
        }
        HoverChip::RightPanelTab(pid) => {
            // Find this tab's rect by walking right_panel_tabs and
            // matching the pane id.
            let idx = app.right_panel_panes.iter().position(|&p| p == pid)?;
            let rect = app
                .rects
                .right_panel_tabs
                .iter()
                .find(|(_, i)| *i == idx)
                .map(|(r, _)| *r)?;
            use crate::pane::Pane;
            let main = app.panes.get(pid).map(Pane::title).unwrap_or_default();
            // design-critic end-of-day #3 — inactive tab's "×: close
            // active tab" implied "click × to close THIS tab" which
            // is wrong. Give each tab its own helper line.
            let hint = if idx == app.right_panel_active_idx {
                "click: switch · ×: close · right-click: menu"
            } else {
                "click: switch tab · right-click: switch/close"
            };
            Some((rect, main, Some(hint.into())))
        }
        HoverChip::RightPanelClose => {
            let rect = app.rects.right_panel_close?;
            Some((
                rect,
                "close active tab".to_string(),
                Some("left-click: close · right-click: menu · Ctrl+Alt+W".into()),
            ))
        }
        HoverChip::SplitTabChip(pid) => {
            let rect = app
                .rects
                .split_tab_chips
                .iter()
                .find(|(_, _, p)| *p == pid)
                .map(|(r, _, _)| *r)?;
            use crate::pane::Pane;
            let title = app.panes.get(pid).map(Pane::title).unwrap_or_default();
            let path = if let Some(Pane::Editor(b)) = app.panes.get(pid) {
                b.path.as_ref().map(|p| p.display().to_string())
            } else {
                None
            };
            let main = path.unwrap_or(title);
            Some((
                rect,
                main,
                Some("click: switch · middle: close · right: menu".into()),
            ))
        }
        HoverChip::SplitTabPlus(leaf_active) => {
            let rect = app
                .rects
                .split_tab_plus_buttons
                .iter()
                .find(|(_, p)| *p == leaf_active)
                .map(|(r, _)| *r)?;
            Some((
                rect,
                "add to this leaf".into(),
                Some("click: Create… menu (new scratch buffer, terminal, split)".into()),
            ))
        }
        HoverChip::SplitTabClose(pid) => {
            let rect = app
                .rects
                .split_tab_close
                .iter()
                .find(|(_, _, p)| *p == pid)
                .map(|(r, _, _)| *r)?;
            use crate::pane::Pane;
            let dirty = matches!(app.panes.get(pid), Some(Pane::Editor(b)) if b.dirty);
            let label = if dirty {
                "close (unsaved — will prompt)"
            } else {
                "close tab"
            };
            Some((rect, label.into(), None))
        }
        HoverChip::AgentsPanelChip(kind) => {
            let rect = match kind {
                crate::AgentsPanelChipKind::NewSession => app.rects.agents_panel_new_chip,
                crate::AgentsPanelChipKind::FromPr => app.rects.agents_panel_pr_chip,
                crate::AgentsPanelChipKind::ViewToggle => app.rects.agents_panel_view_chip,
            }?;
            let (main, sub) = match kind {
                crate::AgentsPanelChipKind::NewSession => (
                    "new agent session",
                    Some("click: spawn fresh Claude Code session in workspace"),
                ),
                crate::AgentsPanelChipKind::FromPr => (
                    "new agent from PR",
                    Some("click: open wizard — pick PRs + action, fire one session per PR"),
                ),
                crate::AgentsPanelChipKind::ViewToggle => (
                    "view mode",
                    Some("click: cycle workspace ↔ status grouping"),
                ),
            };
            Some((rect, main.into(), sub.map(Into::into)))
        }
        HoverChip::CloudAgentsNewRunButton => {
            let rect = app.rects.cloud_agents_new_run_button?;
            Some((
                rect,
                "new cloud run".into(),
                Some("click: open wizard (Managed Agents · ECS runner)".into()),
            ))
        }
        HoverChip::CloudRunAutoRefresh => {
            // Find the rect in cloud_agent_run_hits.
            let rect = app
                .rects
                .cloud_agent_run_hits
                .iter()
                .find(|(_, _, h)| {
                    matches!(
                        h,
                        crate::ui::cloud_agent_run_view::CloudAgentRunHit::CycleAutoRefresh
                    )
                })
                .map(|(r, _, _)| *r)?;
            Some((
                rect,
                "auto-refresh".into(),
                Some("click: cycle off → 10s → 30s → 60s → 5m".into()),
            ))
        }
        HoverChip::CloudRunRefresh => {
            let rect = app
                .rects
                .cloud_agent_run_hits
                .iter()
                .find(|(_, _, h)| {
                    matches!(
                        h,
                        crate::ui::cloud_agent_run_view::CloudAgentRunHit::Refresh
                    )
                })
                .map(|(r, _, _)| *r)?;
            Some((
                rect,
                "refresh".into(),
                Some("click: re-fetch logs + artifacts (or restart SSE stream)".into()),
            ))
        }
        HoverChip::ActivityBarGear => {
            let rect = app.rects.activity_bar_gear?;
            Some((
                rect,
                "settings".into(),
                Some("click: themes · about · prefs".into()),
            ))
        }
        HoverChip::DockKebab => {
            let rect = app.rects.dock_widget_kebabs.first().map(|(r, _)| *r)?;
            Some((rect, "widget options".into(), None))
        }
        HoverChip::DockEmptyChip => {
            let rect = app.rects.dock_empty_chip?;
            Some((
                rect,
                "create first dock widget".into(),
                Some("click: choose widget kind".into()),
            ))
        }
        HoverChip::StatuslineMixrPlay => {
            let rect = app.rects.statusline_mixr_play_chip?;
            Some((rect, "play / pause".into(), None))
        }
        HoverChip::StatuslineMixrFfwd => {
            let rect = app.rects.statusline_mixr_ffwd_chip?;
            Some((rect, "skip track".into(), None))
        }
        HoverChip::StatuslineTestChip => {
            let rect = app.rects.statusline_test_chip?;
            Some((
                rect,
                "test status".into(),
                Some("click: focus test output pane".into()),
            ))
        }
        HoverChip::SplitStripTermButton => {
            let rect = app
                .rects
                .split_strip_term_buttons
                .iter()
                .map(|(r, _)| *r)
                .next()?;
            Some((rect, "open shell in split".to_string(), None))
        }
        HoverChip::SplitStripButton(dir) => {
            let rect = app
                .rects
                .split_strip_buttons
                .iter()
                .find(|(_, _, d)| *d == dir)
                .map(|(r, _, _)| *r)?;
            let label = match dir {
                crate::layout::SplitDir::Horizontal => "split right",
                crate::layout::SplitDir::Vertical => "split down",
            };
            Some((rect, label.into(), None))
        }
        HoverChip::RailHeaderChip(action) => {
            let rect = app
                .rects
                .rail_git_header_buttons
                .iter()
                .find(|(_, a)| *a == action)
                .map(|(r, _)| *r)?;
            let label = match action {
                crate::GitRailHeaderAction::Fetch => "fetch",
                crate::GitRailHeaderAction::Pull => "pull",
                crate::GitRailHeaderAction::Push => "push",
                crate::GitRailHeaderAction::StageAll => "stage all changes",
                crate::GitRailHeaderAction::Commit => "commit…",
                crate::GitRailHeaderAction::Graph => "open commit graph",
            };
            Some((rect, label.into(), None))
        }
        HoverChip::GitToolbarChip(action) => {
            let rect = app
                .rects
                .git_toolbar_buttons
                .iter()
                .find(|(_, _, a)| std::mem::discriminant(a) == std::mem::discriminant(&action))
                .map(|(r, _, _)| *r)?;
            Some((rect, action.tooltip_label().into(), None))
        }
        HoverChip::BufferlineNewTab => {
            let rect = app.rects.bufferline_new_tab_button?;
            // vscode-user-mouse 2026-07-30 SEV-3 #4: was "new scratch
            // buffer" which read like VS-Code's "add a tab to this
            // group". This `+` opens a fresh TAB PAGE (a vim-style
            // desktop workspace with its own layout tree) — an empty
            // canvas independent of whatever's open now. The Alt+1..9
            // hint helps mouse-only users discover the switch chords.
            Some((
                rect,
                "new tab page".into(),
                Some("click: open a new empty tab page (workspace) · Alt+1..9 to switch".into()),
            ))
        }
        HoverChip::BufferlineTabsLabel => {
            let rect = app.rects.bufferline_tabs_label?;
            let n = app.layouts.len();
            let dirty = app.dirty_buffer_names().len();
            let primary = if n <= 1 {
                "single tab page".to_string()
            } else {
                format!("{n} tab pages")
            };
            let secondary = if dirty > 0 {
                format!("click: switch tab page · ● = {dirty} dirty buffer(s)")
            } else {
                "click: switch tab page · right-click: menu".to_string()
            };
            Some((rect, primary, Some(secondary)))
        }
        HoverChip::BufferlineThemeToggle => {
            let rect = app.rects.bufferline_theme_toggle?;
            let cur = app.config.ui.theme.as_str();
            Some((
                rect,
                format!("theme: {cur}"),
                Some("click: toggle between configured themes".into()),
            ))
        }
        HoverChip::BufferlineWindowClose => {
            let rect = app.rects.bufferline_window_close?;
            // Stale "click: app.quit" surfaced an internal command
            // id; user-facing sublabel reads better.
            Some((rect, "quit mnml".into(), Some("click: quit".into())))
        }
        // Task #875 (R5 SEV-3 F6) — tab-page pips.
        HoverChip::BufferlineTabPage(idx) => {
            let &(rect, _) = app
                .rects
                .bufferline_tab_page_chips
                .iter()
                .find(|(_, i)| *i == idx)?;
            let total = app.layouts.len().max(1);
            let is_active = idx == app.active_layout;
            let primary = if is_active {
                format!("Tab page {} of {} (active)", idx + 1, total)
            } else {
                format!("Tab page {} of {}", idx + 1, total)
            };
            let alt_hint = if idx < 9 {
                format!(" · Alt+{}", idx + 1)
            } else {
                String::new()
            };
            Some((
                rect,
                primary,
                Some(format!("click: switch{alt_hint} · right-click: menu")),
            ))
        }
        HoverChip::BufferlineTabPageClose(idx) => {
            let &(rect, _) = app
                .rects
                .bufferline_tab_page_close
                .iter()
                .find(|(_, i)| *i == idx)?;
            Some((
                rect,
                format!("close tab page {}", idx + 1),
                Some("click: close".into()),
            ))
        }
        // Task #875 (R5 SEV-3 F7) — Integrations panel tab-strip chips.
        HoverChip::IntegrationsTabInstalled => {
            let rect = app.rects.integrations_tab_installed?;
            Some((
                rect,
                "Installed integrations".into(),
                Some("click: switch to installed list".into()),
            ))
        }
        HoverChip::IntegrationsTabMarketplace => {
            let rect = app.rects.integrations_tab_marketplace?;
            Some((
                rect,
                "Marketplace — browse & install".into(),
                Some("click: switch to marketplace".into()),
            ))
        }
        HoverChip::IntegrationsTabRefresh => {
            let rect = app.rects.integrations_tab_refresh?;
            Some((
                rect,
                "refresh integrations".into(),
                Some("click: re-scan .mnml/integrations/ + user config".into()),
            ))
        }
        HoverChip::IntegrationsTabSort => {
            let rect = app.rects.integrations_tab_sort?;
            Some((
                rect,
                "sort order".into(),
                Some("click: cycle A-Z / recent / manual".into()),
            ))
        }
        // Task #875 (R5 SEV-3 F8) — statusline coverage chip.
        HoverChip::StatuslineCoverage => {
            let rect = app.rects.statusline_coverage_chip?;
            Some((
                rect,
                "test coverage".into(),
                Some("click: open coverage overlay · right-click: menu".into()),
            ))
        }
        HoverChip::SplitStripAiButton => {
            // Anchor on the first AI-button rect (any of them work —
            // the tooltip just needs a position to attach to). The
            // config decides what the label reads.
            let rect = app
                .rects
                .split_strip_ai_buttons
                .iter()
                .map(|(r, _, _)| *r)
                .next()?;
            let (primary, secondary) = match app.config.ui.tab_bar_ai_icon.as_str() {
                "codex" => (
                    "open Codex in this split".to_string(),
                    "click: spawn Codex".into(),
                ),
                "both" => (
                    "open Claude / Codex in this split".to_string(),
                    "click a chip to spawn · right-click: menu".into(),
                ),
                _ => (
                    "open new Claude Code session".to_string(),
                    "click: spawn new session · right-click: menu".into(),
                ),
            };
            Some((rect, primary, Some(secondary)))
        }
        HoverChip::BufferlineTabClose(pid) => {
            let rect = app
                .rects
                .bufferline_tab_close
                .iter()
                .find(|(_, p)| *p == pid)
                .map(|(r, _)| *r)?;
            // Dirty editors show `●` instead of `×`. Mention what a
            // click would actually do — the close behavior is the
            // same in both cases today (dirty triggers an unsaved-
            // changes confirmation), so the tooltip is informational
            // either way.
            use crate::pane::Pane;
            let is_dirty = matches!(app.panes.get(pid), Some(Pane::Editor(b)) if b.dirty);
            let label = if is_dirty {
                "unsaved changes"
            } else {
                "close tab"
            };
            Some((
                rect,
                label.into(),
                Some(
                    "click: close (prompts on unsaved) · use the tab right-click menu to Save"
                        .into(),
                ),
            ))
        }
        HoverChip::SessionsTab(pid) => {
            let rect = app
                .rects
                .session_tabs
                .iter()
                .find(|(_, p)| *p == pid)
                .map(|(r, _)| *r)?;
            use crate::pane::Pane;
            let (title, sub) = match app.panes.get(pid) {
                Some(Pane::Pty(s)) => {
                    // Title: same auto-detected name the sessions
                    // card + tab show (Jira prefixes → OSC → label).
                    let title = s.tab_label_with_prefixes(&app.config.ui.ticket_prefixes);
                    // Sub: multi-line block with branch, cwd, and
                    // up to 6 grid lines of what the pty is doing.
                    // Rendered as one-line-per-`\n` by `draw` below.
                    let cwd = s.profile.cwd.as_ref();
                    let branch = cwd.and_then(|p| {
                        std::process::Command::new("git")
                            .args(["symbolic-ref", "--short", "-q", "HEAD"])
                            .current_dir(p)
                            .output()
                            .ok()
                            .and_then(|out| {
                                let b = String::from_utf8_lossy(&out.stdout).trim().to_string();
                                (!b.is_empty()).then_some(b)
                            })
                    });
                    let cwd_str = cwd
                        .and_then(|p| p.to_str().map(|s| s.to_string()))
                        .unwrap_or_default();
                    let mut lines: Vec<String> = Vec::new();
                    if let Some(b) = branch {
                        lines.push(format!("⎇ {b}"));
                    }
                    if !cwd_str.is_empty() {
                        lines.push(format!("⌂ {cwd_str}"));
                    }
                    // Prefer the JSONL transcript at rest — a real
                    // `you: … / claude: …` exchange reads better
                    // than the tail of the grid. When Claude's
                    // thinking (spinner up), stay on the grid so
                    // the tooltip mirrors what's live on the pane.
                    let thinking = s.current_spinner_glyph().is_some() || s.is_codex_thinking();
                    let content: Vec<String> = if !thinking
                        && let Some(sid) = s.profile.session_id.as_deref()
                        && {
                            let lines =
                                crate::claude_agents::transcript_summary_lines(sid, &app.workspace);
                            !lines.is_empty()
                        } {
                        crate::claude_agents::transcript_summary_lines(
                            s.profile.session_id.as_deref().unwrap(),
                            &app.workspace,
                        )
                    } else {
                        // Grid: bottom-up scan → reverse for reading order.
                        s.session_summary_lines(6).into_iter().rev().collect()
                    };
                    if !content.is_empty() {
                        if !lines.is_empty() {
                            lines.push(String::new());
                        }
                        for l in content {
                            lines.push(l);
                        }
                    }
                    let block = if lines.is_empty() {
                        "click: focus session".to_string()
                    } else {
                        lines.join("\n")
                    };
                    (title, Some(block))
                }
                Some(p) => (p.title(), Some("click: focus session".into())),
                None => ("session".into(), None),
            };
            Some((rect, title, sub))
        }
        HoverChip::BufferlineTab(pid) => {
            let rect = app
                .rects
                .bufferline_tabs
                .iter()
                .find(|(_, p)| *p == pid)
                .map(|(r, _)| *r)?;
            // For editor panes, prefer the workspace-relative path so the
            // tooltip is the full file location. Fall back to the pane's
            // generic title for non-editor panes (Git status / Browser / …).
            use crate::pane::Pane;
            let label = match app.panes.get(pid) {
                Some(Pane::Editor(b)) => match &b.path {
                    Some(p) => {
                        let rel = p
                            .strip_prefix(&app.workspace)
                            .unwrap_or(p)
                            .to_string_lossy()
                            .into_owned();
                        if b.dirty { format!("{rel}  ●") } else { rel }
                    }
                    None => b.display_name().to_string(),
                },
                Some(p) => p.title(),
                None => "tab".into(),
            };
            Some((
                rect,
                label,
                Some("click: focus · middle: close · right: menu".into()),
            ))
        }
        HoverChip::DiffToolbar(action) => {
            let rect = app
                .rects
                .diff_toolbar_buttons
                .iter()
                .find(|(_, _, a)| *a == action)
                .map(|(r, _, _)| *r)?;
            let label = match action {
                crate::DiffToolbarAction::ViewInline => "view: inline (whole file)",
                crate::DiffToolbarAction::ViewHunk => "view: hunks (focused)",
                crate::DiffToolbarAction::ViewSplit => "view: split (side-by-side)",
                crate::DiffToolbarAction::ToggleWrap => "toggle line wrap",
                crate::DiffToolbarAction::Close => "close diff",
            };
            Some((rect, label.into(), None))
        }
        HoverChip::FoldChip => {
            // Tooltip anchors above the first fold chip the cursor is over.
            // Mouse is over a fold chip so at least one is hovered — find
            // the first rect that matches.
            let rect = app.rects.fold_chips.first().map(|(r, _, _)| *r)?;
            Some((rect, "click: unfold this block".into(), None))
        }
        HoverChip::CodeLensChip => {
            let rect = app.rects.code_lens_chips.first().map(|(r, _, _)| *r)?;
            Some((rect, "click: run code lens".into(), None))
        }
        HoverChip::ClaudeAgentsTopbarChip(kind) => {
            let rect = app
                .rects
                .claude_agents_topbar_chips
                .iter()
                .find(|(_, _, k)| *k == kind)
                .map(|(r, _, _)| *r)?;
            let label = match kind {
                crate::ui::TopbarChipKind::View => {
                    "click: cycle drill view (Summary → Todos → Files → Bash → Subagents) · key: v"
                }
                crate::ui::TopbarChipKind::Sort => {
                    "click: cycle sort key (state → tokens↓ → cost↓ → recent → …) · key: s"
                }
                crate::ui::TopbarChipKind::Group => {
                    "click: cycle grouping (by source ↔ by workspace) · key: Ctrl+G"
                }
                crate::ui::TopbarChipKind::Source => {
                    "click: cycle source filter (all → ✦ claude → ◈ codex → all) · key: >"
                }
                crate::ui::TopbarChipKind::Workspace => {
                    "click: toggle workspace-only filter · key: W"
                }
            };
            Some((rect, label.into(), None))
        }
        HoverChip::RequestTopBarChip(kind) => {
            use crate::RequestTopBarChip;
            let (rect, primary, secondary) = match kind {
                RequestTopBarChip::Method => (
                    app.rects.request_method_button?,
                    "click: pick HTTP verb (GET / POST / …)",
                    None,
                ),
                RequestTopBarChip::Env => (
                    app.rects.request_env_button?,
                    "click: switch active .env",
                    Some("right-click: switch / edit / clear override"),
                ),
                RequestTopBarChip::Send => (
                    app.rects.request_send_button?,
                    "click: send request (or abort while in-flight)",
                    Some("right-click: send / abort / diff last two"),
                ),
                RequestTopBarChip::Save => (
                    app.rects.request_save_button?,
                    "click: save request (Save-As if new)",
                    Some("right-click: save / save mock / save response"),
                ),
                RequestTopBarChip::Clear => (
                    app.rects.request_clear_button?,
                    "click: clear the request fields",
                    None,
                ),
                RequestTopBarChip::Code => (
                    app.rects.request_code_button?,
                    "click: generate code snippet (curl / py / js / …)",
                    Some("right-click: copy curl / open picker"),
                ),
            };
            Some((rect, primary.into(), secondary.map(|s| s.into())))
        }
        HoverChip::RequestResponseCopy => Some((
            app.rects.request_response_copy_chip?,
            "click: copy response body to clipboard".into(),
            None,
        )),
        HoverChip::RequestResponseWrap => Some((
            app.rects.request_response_wrap_chip?,
            "click: toggle body line wrap".into(),
            None,
        )),
        HoverChip::RequestResponseAiPrompt => Some((
            app.rects.request_response_ai_prompt_chip?,
            "click: copy AI-ready \"debug this failure\" prompt".into(),
            Some("headers redact secrets before copy".into()),
        )),
        HoverChip::RequestResponseFormat => Some((
            app.rects.request_format_button?,
            "click: prettify JSON body".into(),
            Some("dim when the body isn't JSON".into()),
        )),
        HoverChip::BufferlineNewRequest => Some((
            app.rects.bufferline_new_request_button?,
            "click: open a new HTTP request".into(),
            None,
        )),
        HoverChip::ScrollbarThumb => {
            // Anchor: any scrollbar rect will do — pick the one
            // the cursor actually sits on. Falls back to None
            // when no scrollbar rendered this frame (rare race).
            let rect = app.rects.scrollbars.first().map(|h| h.area)?;
            Some((rect, "click: jump to that row · drag: scroll".into(), None))
        }
        HoverChip::RightPanelGrip => {
            let rect = app.rects.right_panel_edge?;
            Some((
                rect,
                "drag: resize · double-click: reset width".into(),
                None,
            ))
        }
        HoverChip::TreeRailGrip => {
            let rect = app.rects.tree_edge?;
            Some((
                rect,
                "drag: resize · double-click: reset width".into(),
                None,
            ))
        }
        HoverChip::MenuBarWord(idx) => {
            // mouse-round-8 SEV-3 2026-07-12 — suppress the hover
            // tooltip while any menu-bar menu is already open. The
            // open dropdown paints below the bar row and the tooltip
            // would render on top, covering the first item of the
            // open menu. Hover-switch already handles moving between
            // menus (round-10 SEV-2 fix).
            if app.menu_open.is_some() {
                return None;
            }
            let &(rect, _) = app.rects.menu_bar_words.iter().find(|(_, i)| *i == idx)?;
            let menus = crate::menu_bar::bar(app);
            let menu = menus.get(idx)?;
            let label_trim = menu.label.trim();
            // Alt accelerator letter (first ASCII alpha character).
            let accel = label_trim
                .chars()
                .find(|c| c.is_ascii_alphabetic())
                .map(|c| c.to_ascii_uppercase());
            let secondary = accel.map(|c| format!("Alt+{c}"));
            Some((rect, "click: open menu".into(), secondary))
        }
        HoverChip::PendingUndoChip => {
            let rect = app.rects.pending_undo_chip?;
            let action_hint = app
                .pending_undo
                .as_ref()
                .map(|u| format!("undoes: {}", u.label))
                .unwrap_or_default();
            Some((
                rect,
                "click to undo the last destructive action · `u` in vim mode".into(),
                if action_hint.is_empty() {
                    None
                } else {
                    Some(action_hint)
                },
            ))
        }
        HoverChip::RequestVarToken(idx) => {
            let (rect, name) = app.rects.request_var_click_rects.get(idx)?.clone();
            // api-round-12 SEV-2 2026-07-14 — was 2-tier
            // `EnvSet::select` which returned empty on `.mnml`-only
            // workspaces, making every resolved var render as "not
            // defined in active env" in the hover tooltip.
            let envset = app.active_envset();
            // Same resolution shape as tokenize_vars — `$foo` hits
            // dynamic_var, otherwise env lookup.
            let value = match name.strip_prefix('$') {
                Some(dyn_name) => crate::http::template::dynamic_var(dyn_name),
                None => envset.lookup(&name),
            };
            let head = format!("{{{{{name}}}}}");
            let sub = match value {
                Some(v) => {
                    // Truncate long values so the tooltip stays a
                    // one-liner. 100 chars is generous — env values
                    // are usually short.
                    let clipped: String = v.chars().take(100).collect();
                    let more = if v.chars().count() > 100 { "…" } else { "" };
                    format!("= {clipped}{more} · click to jump to env")
                }
                None => "not defined in active env · click to open env file".to_string(),
            };
            Some((rect, head, Some(sub)))
        }
        HoverChip::HttpSectionChip(idx) => {
            let (rect, section, kind) = *app.rects.http_panel_section_chips.get(idx)?;
            let section_name = match section {
                1 => "RECENT",
                2 => "CAPTURED",
                4 => "CHAINS",
                5 => "MOCKS",
                6 => "COLLECTIONS",
                _ => "section",
            };
            let (line, sub) = match kind {
                crate::app::HttpChipKind::Filter => (
                    format!("Filter {section_name}"),
                    "focus the `/` filter (matches / narrows across all sections)".to_string(),
                ),
                crate::app::HttpChipKind::Refresh => (
                    // #polish 2026-07-07 (design-critic #2) — retitled
                    // from "Refresh {section_name}" because clicking
                    // fires `http.refresh` which rescans EVERY section
                    // + toasts panel-wide. The old scope-implying title
                    // was actively misleading.
                    "Refresh HTTP panel".to_string(),
                    "re-scan collections / files / envs / captured log".to_string(),
                ),
                crate::app::HttpChipKind::Capture => (
                    "Start capturing".to_string(),
                    "open a browser pane (or dump the current log if one is already open)"
                        .to_string(),
                ),
                crate::app::HttpChipKind::Clear => match section {
                    1 => (
                        "Clear RECENT".to_string(),
                        "truncate the request history log".to_string(),
                    ),
                    2 => (
                        "Clear CAPTURED".to_string(),
                        "truncate the captured-request log".to_string(),
                    ),
                    _ => (
                        "Clear filter".to_string(),
                        format!("reset the / filter on {section_name}"),
                    ),
                },
                crate::app::HttpChipKind::New => match section {
                    3 => (
                        "New env…".to_string(),
                        "prompt for a name and create an empty env file".to_string(),
                    ),
                    6 => (
                        "New collection…".to_string(),
                        "prompt for a name and create an empty collection".to_string(),
                    ),
                    _ => (format!("New {section_name} item"), String::new()),
                },
            };
            Some((rect, line, Some(sub)))
        }
        HoverChip::TreeUpRow => {
            let rect = app.rects.tree_up_row?;
            // mouse-round-7 SEV-3 2026-07-12 — used to render the
            // full absolute path (108 chars in a tempdir), stretching
            // the tooltip box to the terminal width. Show just the
            // last segment (or short-form middle-ellipsis) so the
            // user sees "which parent" without the 100-char noise.
            let parent = app.workspace.parent();
            let display: String = match parent {
                Some(p) => {
                    let last = p.file_name().and_then(|n| n.to_str()).map(str::to_string);
                    let full = p.display().to_string();
                    match last {
                        Some(name) if !name.is_empty() && full.chars().count() > 40 => {
                            format!("…/{name}")
                        }
                        _ => full,
                    }
                }
                None => "/".to_string(),
            };
            Some((
                rect,
                "Open parent as workspace".into(),
                Some(format!("click: {display}")),
            ))
        }
        HoverChip::HttpToolbarChip(idx) => {
            let (rect, cmd_id) = *app.rects.http_panel_icon_buttons.get(idx)?;
            let title = crate::command::registry()
                .get(cmd_id)
                .map(|c| c.title.to_string())
                .unwrap_or_else(|| cmd_id.to_string());
            Some((rect, title, None))
        }
        HoverChip::HttpCollectionAddRequestChip(idx) => {
            let (rect, root) = app
                .rects
                .http_panel_collection_new_request_chips
                .get(idx)?
                .clone();
            let name = root
                .file_name()
                .and_then(|n| n.to_str())
                .unwrap_or("")
                .to_string();
            Some((
                rect,
                format!("New request in {name}"),
                Some("prompt for a name and create req-N.http".into()),
            ))
        }
        HoverChip::RequestEditSplitDivider => {
            let rect = app.rects.request_edit_split_divider?;
            Some((
                rect,
                "click: cycle split ratio (30% / 50% / 70%)".into(),
                Some("live drag-resize is a v2 follow-up".into()),
            ))
        }
        HoverChip::RequestEditSplitChip => {
            let rect = app.rects.request_edit_split_chip?;
            let open = matches!(
                app.active.and_then(|i| app.panes.get(i)),
                Some(crate::pane::Pane::Request(rp)) if rp.edit_tab_split.is_some()
            );
            let (line, sub) = if open {
                (
                    "click: close side-by-side edit split",
                    "click a right-side tab to change what it shows",
                )
            } else {
                (
                    "click: split the edit area side-by-side",
                    "e.g. Body on the left, Vars on the right",
                )
            };
            Some((rect, line.into(), Some(sub.into())))
        }
        HoverChip::RequestSplitToggle => {
            let rect = app.rects.request_split_toggle?;
            let orient_desc = match app.active.and_then(|i| app.panes.get(i)) {
                Some(crate::pane::Pane::Request(rp)) => match rp.split_orientation {
                    crate::request_pane::SplitOrientation::Auto => {
                        "current: A auto (picks by width)"
                    }
                    crate::request_pane::SplitOrientation::Vertical => {
                        "current: ▥ stacked (request above response)"
                    }
                    crate::request_pane::SplitOrientation::Horizontal => "current: ▤ side-by-side",
                },
                _ => "cycle auto / stacked / side-by-side",
            };
            Some((
                rect,
                "click: cycle split orientation (auto → ▥ → ▤)".into(),
                Some(orient_desc.into()),
            ))
        }
        HoverChip::StatuslineFile => {
            let rect = app.rects.statusline_file_chip?;
            let b = app.active_editor()?;
            let path = b
                .path
                .as_ref()
                .map(|p| p.display().to_string())
                .unwrap_or_else(|| b.display_name().to_string());
            // mouse-round-8 SEV-3 2026-07-12 — long absolute paths
            // stretched the tooltip box to the full terminal width.
            // Prefer the workspace-relative path when the file is
            // inside the workspace (short, unambiguous); fall back
            // to the absolute path abbreviated with a middle
            // ellipsis when the absolute is >64 chars.
            let ws = app.workspace.display().to_string();
            let display_path: String = if let Some(rest) = path.strip_prefix(&ws) {
                let rest = rest.trim_start_matches('/');
                if rest.is_empty() {
                    path.clone()
                } else {
                    rest.to_string()
                }
            } else if path.chars().count() > 64 {
                let chars: Vec<char> = path.chars().collect();
                let head: String = chars.iter().take(24).collect();
                let tail: String = chars
                    .iter()
                    .rev()
                    .take(32)
                    .collect::<Vec<_>>()
                    .into_iter()
                    .rev()
                    .collect();
                format!("{head}…{tail}")
            } else {
                path.clone()
            };
            let dirty = if b.dirty { " · unsaved" } else { "" };
            Some((
                rect,
                format!("{display_path}{dirty}"),
                Some("click: reveal in tree · right-click: buffer menu".into()),
            ))
        }
        HoverChip::StatuslineDiagnostics => {
            let rect = app.rects.statusline_diagnostics_chip?;
            let b = app.active_editor()?;
            let (errs, warns) =
                b.all_diagnostics()
                    .fold((0u32, 0u32), |(e, w), d| match d.severity {
                        crate::lsp::Severity::Error => (e + 1, w),
                        crate::lsp::Severity::Warning => (e, w + 1),
                        _ => (e, w),
                    });
            let mut parts: Vec<String> = Vec::new();
            if errs > 0 {
                parts.push(format!("{errs} error{}", if errs == 1 { "" } else { "s" }));
            }
            if warns > 0 {
                parts.push(format!(
                    "{warns} warning{}",
                    if warns == 1 { "" } else { "s" }
                ));
            }
            let primary = if parts.is_empty() {
                "no diagnostics".to_string()
            } else {
                parts.join(" · ")
            };
            Some((rect, primary, Some("click: open diagnostics panel".into())))
        }
        HoverChip::StatuslineSymbol => {
            let rect = app.rects.statusline_symbol_chip?;
            let b = app.active_editor()?;
            let symbol = b
                .language_ext
                .as_deref()
                .and_then(|ext| {
                    let symbols = crate::regex_outline::extract_symbols(b.editor.text(), ext);
                    let row = b.editor.row_col().0 as u32;
                    symbols
                        .iter()
                        .rev()
                        .find(|s| s.line <= row)
                        .map(|s| s.name.clone())
                })
                .unwrap_or_default();
            Some((
                rect,
                if symbol.is_empty() {
                    "current symbol".to_string()
                } else {
                    format!("symbol: {symbol}")
                },
                Some("click: open outline".into()),
            ))
        }
        HoverChip::StatuslinePr => {
            let rect = app.rects.statusline_pr_chip?;
            let pr = app.git_rail.pulls.iter().find(|p| p.is_current_branch)?;
            let title: String = pr.title.chars().take(60).collect();
            let elided = if pr.title.chars().count() > 60 {
                "…"
            } else {
                ""
            };
            Some((
                rect,
                format!("{}{} — {title}{elided}", pr.host_tag, pr.number_label),
                Some("click: open PR in browser".into()),
            ))
        }
        HoverChip::StatuslineMacroRec => {
            let rect = app.rects.statusline_macro_chip?;
            let reg = match &app.macro_state {
                crate::app::MacroState::Recording { register, .. } => *register,
                _ => return None,
            };
            Some((
                rect,
                format!("recording macro @{reg}"),
                Some("click: stop recording (q)".into()),
            ))
        }
        HoverChip::StatuslineFind => {
            let rect = app.rects.statusline_find_chip?;
            let b = app.active_editor()?;
            let f = b.find.as_ref()?;
            let cur = f.current.map(|i| i + 1).unwrap_or(0);
            let m = f.matches.len();
            Some((
                rect,
                format!("find: {}  ({}/{})", f.query, cur, m),
                Some("click: reopen find prompt · n/N: next/prev".into()),
            ))
        }
        HoverChip::StatuslineSel => {
            let rect = app.rects.statusline_sel_chip?;
            let b = app.active_editor()?;
            let text = b.editor.selected_text();
            let chars = text.chars().count();
            let bytes = text.len();
            let lines = text.matches('\n').count() + 1;
            Some((
                rect,
                format!("{chars} chars · {bytes} bytes · {lines} lines"),
                None,
            ))
        }
        HoverChip::StatuslineProgress => {
            let rect = app.rects.statusline_progress_chip?;
            let title = app
                .lsp_progress
                .values()
                .next()
                .cloned()
                .unwrap_or_default();
            Some((
                rect,
                if title.is_empty() {
                    "LSP task".to_string()
                } else {
                    format!("LSP: {title}")
                },
                Some("$/progress notification".into()),
            ))
        }
        HoverChip::StatuslineBgTasks => {
            let rect = app.rects.statusline_bg_tasks_chip?;
            let n = app.background_task_count();
            Some((rect, format!("{n} background tasks running"), None))
        }
        HoverChip::StatuslineAi => {
            let rect = app.rects.statusline_ai_chip?;
            Some((
                rect,
                "waiting for AI completion".to_string(),
                Some("inline suggestion in flight".into()),
            ))
        }
        HoverChip::StatuslineLanguage => {
            let rect = app.rects.statusline_language_chip?;
            let lang = app
                .active_editor()
                .and_then(|b| b.language_ext.clone())
                .unwrap_or_else(|| "—".to_string());
            Some((
                rect,
                if lang == "—" {
                    "no language".to_string()
                } else {
                    format!("language: {lang}")
                },
                Some("click for details · detected from file extension".into()),
            ))
        }
        HoverChip::GutterMark {
            pane_id,
            line_no,
            kind,
        } => {
            let &(rect, _, _, _) = app
                .rects
                .gutter_marks
                .iter()
                .find(|(_, pid, ln, k)| *pid == pane_id && *ln == line_no && *k == kind)?;
            let (primary, secondary) = match kind {
                crate::GutterMarkKind::DapArrow => (
                    format!("▶ debugger paused at line {}", line_no + 1),
                    Some("continue / step to advance".into()),
                ),
                crate::GutterMarkKind::ConditionalBreakpoint => (
                    format!("◆ conditional breakpoint (line {})", line_no + 1),
                    Some("click gutter: toggle · right-click: edit condition".into()),
                ),
                crate::GutterMarkKind::Breakpoint => (
                    format!("● breakpoint (line {})", line_no + 1),
                    Some("click gutter to toggle".into()),
                ),
                crate::GutterMarkKind::Diagnostic(sev) => {
                    // Aggregate every diagnostic touching this line so the
                    // tooltip shows the actual message, not just the color.
                    // (Multiple diagnostics on one line get joined.)
                    let msgs: Vec<String> = app
                        .panes
                        .get(pane_id)
                        .and_then(|p| match p {
                            crate::pane::Pane::Editor(b) => Some(b),
                            _ => None,
                        })
                        .map(|b| {
                            b.all_diagnostics()
                                .filter(|d| {
                                    (d.range.start.line as usize) <= line_no
                                        && line_no <= (d.range.end.line as usize)
                                })
                                .map(|d| d.message.lines().next().unwrap_or("").to_string())
                                .filter(|s| !s.is_empty())
                                .collect()
                        })
                        .unwrap_or_default();
                    let sev_word = match sev {
                        crate::lsp::Severity::Error => "error",
                        crate::lsp::Severity::Warning => "warning",
                        crate::lsp::Severity::Info => "info",
                        crate::lsp::Severity::Hint => "hint",
                    };
                    let primary = if let Some(first) = msgs.first() {
                        // Truncate long messages so the tooltip stays compact.
                        let clipped: String = first.chars().take(80).collect();
                        let elided = if first.chars().count() > 80 {
                            "…"
                        } else {
                            ""
                        };
                        format!("● {sev_word}: {clipped}{elided}")
                    } else {
                        format!("● {sev_word} on line {}", line_no + 1)
                    };
                    let secondary = if msgs.len() > 1 {
                        Some(format!("+{} more on this line", msgs.len() - 1))
                    } else {
                        None
                    };
                    (primary, secondary)
                }
                crate::GutterMarkKind::GitChange(kind) => {
                    let (glyph, word) = match kind {
                        crate::git::diff::SignKind::Added => ("▎", "added"),
                        crate::git::diff::SignKind::Modified => ("▎", "modified"),
                        crate::git::diff::SignKind::Removed => ("▎", "removed nearby"),
                    };
                    (
                        format!("{glyph} git: {word} (line {})", line_no + 1),
                        Some("] c / [ c jumps hunks".into()),
                    )
                }
            };
            Some((rect, primary, secondary))
        }
        HoverChip::ToastBox(idx) => {
            let rect = *app.rects.toast_stack_rects.get(idx)?;
            let text = app
                .toast_stack
                .get(idx)
                .map(|e| e.text.clone())
                .unwrap_or_default();
            // Truncate for the tooltip primary but keep the full text
            // available via the secondary line.
            let primary = if text.chars().count() > 40 {
                let short: String = text.chars().take(40).collect();
                format!("{short}…")
            } else {
                text.clone()
            };
            Some((
                rect,
                primary,
                Some("click to dismiss · right-click for menu · hover pauses TTL".into()),
            ))
        }
        // Task #929 — dropdown-row tooltips are suppressed to avoid
        // painting a floating popup on top of the open menu (same
        // rationale as `MenuBarWord` while a menu is open, see the
        // `menu_open.is_some()` guard above). The info-panel path
        // still fires — `HoverChip::MenuBarItem` routes through
        // `info_view_copy::resolve_menu_bar_item_copy` and lands in
        // the bottom-left panel.
        HoverChip::MenuBarItem { .. } => None,
        HoverChip::StatuslineSegment(idx) => {
            let (rect, seg_id) = app.rects.statusline_segment_hits.get(idx)?.clone();
            // Task #965 reviewer follow-up 2026-08-17: prefer the
            // DYNAMIC segment's tooltip first — that's where the
            // manifest-driven pipeline stores the combined base +
            // runtime state ("waiting for first poll" / "last error:
            // <msg>"). Fall back to the manifest's static tooltip
            // (in case DynamicSegment.tooltip is None, e.g. an
            // IPC-set segment that didn't declare one), then to a
            // click-command hint, then the raw id as last resort.
            let dyn_tooltip = app
                .dynamic_segments
                .iter()
                .find(|d| d.id == seg_id)
                .and_then(|d| d.tooltip.clone());
            let manifest_tooltip = app.integration_manifests.iter().find_map(|m| {
                m.statusline_segments
                    .iter()
                    .find(|s| s.id == seg_id)
                    .and_then(|s| s.tooltip.clone())
            });
            let click_hint = app
                .dynamic_segments
                .iter()
                .find(|d| d.id == seg_id)
                .and_then(|d| d.click_command.clone())
                .map(|cmd| format!("click: {cmd}"));
            let primary = dyn_tooltip
                .clone()
                .or_else(|| manifest_tooltip.clone())
                .or_else(|| click_hint.clone())
                .unwrap_or_else(|| seg_id.clone());
            let secondary = if primary != click_hint.clone().unwrap_or_default() {
                click_hint
            } else {
                None
            };
            Some((rect, primary, secondary))
        }
    }
}