konoma 0.19.0

//! Application state: the `App` struct and its methods — mode (Tree/Preview), the tree,
//! tabs, and the current preview target. Git view methods live in the `git_view` submodule.

use std::collections::BTreeSet;
use std::path::{Path, PathBuf};
use std::sync::Arc;

use anyhow::Result;
use ratatui::layout::Rect;
use ratatui::text::{Line, Span};
use ratatui_image::errors::Errors;
use ratatui_image::picker::Picker;
use ratatui_image::protocol::Protocol;
use ratatui_image::thread::{ResizeRequest, ResizeResponse, ThreadProtocol};
use ratatui_image::{FilterType, Resize};
use tokio::sync::mpsc::UnboundedSender;

use crate::config::Config;
use crate::i18n::tr;
use crate::preview::PreviewKind;

mod bookmark_actions;
mod copy_actions;
mod dialog_actions;
mod file_actions;
mod follow;
mod git_view;
mod md_items;
mod md_media;
mod md_render;
mod md_tasks;
mod md_text;
mod media_load;
mod outline;
mod paste_jump;
mod preview_visual;
mod search;
mod session_actions;
mod tab_lifecycle;
mod table_actions;

use md_text::*;
// Only referenced by tests (`crate::app::PreviewSelection`) — `preview_visual` itself uses the
// type unqualified since it's defined there, so this re-export would be unused_imports outside cfg(test).
#[cfg(test)]
pub use preview_visual::PreviewSelection;
use preview_visual::*;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Mode {
    #[default]
    Tree,
    Preview,
}

/// Display mode (outer): what is currently shown full-screen. The **outer chip** in the status bar (colors assigned by `ui`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DisplayMode {
    Tree,
    Preview,
    Image,
    /// CSV/TSV table preview (aligned grid + cell cursor).
    Table,
}

/// Internal mode (inner): what is currently being operated. Shows the **inner chip** only while active and switches the footer keys too.
/// Priority: dialog > each footer mode (filter/search/sort/bookmarks) > visual.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum InternalMode {
    Visual,
    /// Windowed-preview line selection (`v` in a code/text preview).
    PreviewVisual,
    Filter,
    /// Changed-files-only tree view (`C`; Agent Watch).
    ChangedFilter,
    Search,
    Sort,
    Mark,
    Bookmarks,
    Tabs,
    Outline,
    Info,
    Create,
    Rename,
    BatchRename,
    RenamePreview,
    DeleteConfirm,
    DropConfirm,
    QuitConfirm,
    BookmarkConfirm,
    GitChanges,
    GitDiff,
    Commit,
    GitLog,
    GitDetail,
    GitBranch,
    GitGraph,
    GitGraphPicker,
}

/// Preview paging key style. Specified via the `ui.keys` setting (default vim).
/// Diffs use only the page/half-page keys. j/k line movement, arrows, and PageUp/Down are common to both styles.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum KeyScheme {
    /// vim style: Ctrl-f/Ctrl-b=page, Ctrl-d/Ctrl-u=half.
    Vim,
    /// less style: Space/b=page, d/u=half.
    Less,
}

impl KeyScheme {
    pub fn parse(s: &str) -> Self {
        match s {
            "less" => Self::Less,
            _ => Self::Vim,
        }
    }
}

/// diff layout (config `git.diff`; cycle at runtime with `s`). Auto picks vertical/horizontal automatically from the terminal width.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DiffLayout {
    /// Vertical (unified).
    Unified,
    /// Side-by-side.
    Split,
    /// Horizontal if wide, vertical if narrow.
    Auto,
}

impl DiffLayout {
    /// Parse a config value. "split"/"horizontal"/"side-by-side"=horizontal / "auto"=auto / otherwise=vertical.
    pub fn parse(s: &str) -> Self {
        let n: String = s
            .chars()
            .filter(|c| !matches!(c, ' ' | '-' | '_'))
            .flat_map(|c| c.to_lowercase())
            .collect();
        match n.as_str() {
            "split" | "horizontal" | "sidebyside" | "side" => Self::Split,
            "auto" => Self::Auto,
            _ => Self::Unified, // "unified" / "vertical" / 不明
        }
    }
    /// Resolve whether to lay out side-by-side at the actual display width `width`. Auto decides by a threshold.
    pub fn is_split(self, width: u16) -> bool {
        match self {
            DiffLayout::Unified => false,
            DiffLayout::Split => true,
            DiffLayout::Auto => width >= DIFF_AUTO_MIN_WIDTH,
        }
    }
    /// Cycle to the next layout (vertical→horizontal→Auto→vertical). For `s`.
    #[cfg_attr(not(feature = "git"), allow(dead_code))]
    pub fn next(self) -> Self {
        match self {
            DiffLayout::Unified => DiffLayout::Split,
            DiffLayout::Split => DiffLayout::Auto,
            DiffLayout::Auto => DiffLayout::Unified,
        }
    }
}

/// Minimum inner width for side-by-side under Auto (below this, vertical). A guideline so two-column code is not cramped.
const DIFF_AUTO_MIN_WIDTH: u16 = 90;

/// Layout of the status chrome (config `ui.statusbar`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StatusbarLayout {
    /// Context (mode/path/zoom) on top (right of the tab row), key hints at the bottom (default).
    Split,
    /// Combine both context and key hints into a single bottom line.
    Bottom,
}

impl StatusbarLayout {
    pub fn parse(s: &str) -> Self {
        match s {
            "bottom" => Self::Bottom,
            _ => Self::Split,
        }
    }
}

/// Path display style. Used for the title (tree/preview). Cycle with the `p` key.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PathStyle {
    /// Relative to the launch directory name (e.g. konoma/src/main.rs). Default.
    Relative,
    /// Relative to HOME (e.g. ~/work/konoma).
    Home,
    /// Full path (e.g. /Users/me/work/konoma).
    Full,
}

impl PathStyle {
    pub fn parse(s: &str) -> Self {
        match s {
            "home" => Self::Home,
            "full" => Self::Full,
            _ => Self::Relative,
        }
    }
    pub fn next(self) -> Self {
        match self {
            Self::Relative => Self::Home,
            Self::Home => Self::Full,
            Self::Full => Self::Relative,
        }
    }
}

/// A single entry shown in the tree.
#[derive(Debug, Clone)]
pub struct Entry {
    pub path: PathBuf,
    pub is_dir: bool,
    pub depth: usize,
    pub expanded: bool,
}

/// Tree sort key (FR / M7 auxiliary). Switch via the footer menu (`s`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SortKey {
    Name,
    Size,
    Modified,
    Ext,
}

/// Sort settings. `reverse`=flip ascending/descending, `dirs_first`=group directories at the top.
/// Default is "name, ascending, directories first" (matches the previous behavior). Global (not per-tab).
#[derive(Clone, Copy)]
pub struct Sort {
    pub key: SortKey,
    pub reverse: bool,
    pub dirs_first: bool,
}

impl Default for Sort {
    fn default() -> Self {
        Self {
            key: SortKey::Name,
            reverse: false,
            dirs_first: true,
        }
    }
}

impl SortKey {
    /// Parse a config string (case-insensitive). Unknown/empty falls back to Name.
    pub fn parse(s: &str) -> Self {
        match s.trim().to_lowercase().as_str() {
            "size" => SortKey::Size,
            "modified" | "mtime" | "mod" => SortKey::Modified,
            "ext" | "extension" | "type" => SortKey::Ext,
            _ => SortKey::Name,
        }
    }
}

impl Sort {
    /// Build the startup sort order from the `[ui.sort]` config.
    pub fn from_config(c: &crate::config::SortConfig) -> Self {
        Self {
            key: SortKey::parse(&c.key),
            reverse: c.reverse,
            dirs_first: c.dirs_first,
        }
    }
}

/// Destructive/creation operations confirmed through a modal dialog (M7 Phase B, safety first).
// git 専用バリアント(GitDiscard/GitDeleteBranch)は非 git ビルドでは構築経路が無い(その構築元は
// git ディスパッチ専用)。バリアント自体は match の網羅性のため残し、非 git のみ dead_code を許す。
#[cfg_attr(not(feature = "git"), allow(dead_code))]
#[derive(Clone)]
enum PendingOp {
    /// Create with the entered name. A trailing `/` means a folder. `dir` is the destination (based on the cursor).
    Create { dir: PathBuf },
    /// Rename the target to the entered name within the same parent.
    Rename { target: PathBuf },
    /// Send the target to the trash (recoverable).
    Delete { targets: Vec<PathBuf> },
    /// Template-input stage of batch rename (`targets`=targets in display order). On confirm, builds a plan and moves to preview.
    BatchRenameInput { targets: Vec<PathBuf> },
    /// Preview→apply stage of batch rename (`plan`=(old, new) pairs).
    BatchRenameApply { plan: Vec<(PathBuf, PathBuf)> },
    /// In the Git view, `x`=discard a file's changes (via a confirmation dialog). On confirm, git::discard.
    GitDiscard { path: PathBuf },
    /// In the Git view, `c`=enter a commit message. On confirm, git::commit (uses the staged index).
    GitCommit,
    /// In the branch list, `n`=enter a new branch name. On confirm, git::create_branch (create and switch).
    GitCreateBranch,
    /// In the branch list, `d`=delete confirmation. `y`=safe (-d) / `!`=force (-D).
    GitDeleteBranch { name: String },
    /// A transfer received via file drag & drop (through a terminal paste). `c`=copy / `m`=move / Esc=cancel.
    /// `sources`=the dropped existing paths, `dir`=the drop destination (directory based on the cursor).
    DropTransfer { sources: Vec<PathBuf>, dir: PathBuf },
    /// Quit the whole app. A confirmation is requested before exiting (see `ui.confirm_quit`).
    Quit,
    /// Overwrite an existing bookmark under `key` with `target` (confirmation via `ui.confirm_bookmark_overwrite`).
    BookmarkOverwrite { key: char, target: PathBuf },
}

/// A confirmation (yes/no) or text-input modal. On confirm, calls fileops according to `op`.
struct Dialog {
    op: PendingOp,
    kind: DialogKind,
}

/// Dialog kind. Confirm=y/n for a destructive op (delete) / Input=name entry for create/rename.
/// `allow_permanent`=whether the delete confirmation also offers `!`=permanent delete (unrecoverable) (true=delete confirmation only).
enum DialogKind {
    Confirm {
        message: String,
        allow_permanent: bool,
    },
    Input {
        title: String,
        buffer: String,
        /// Insertion position (**character** index within buffer, 0..=char count). Move with ←→/Home/End.
        cursor: usize,
    },
    /// Confirmation preview for batch rename. `lines`=the "old → new" list, `scroll`=the top visible line.
    Preview {
        title: String,
        lines: Vec<String>,
        scroll: usize,
    },
}

/// File clipboard operation kind. Copy=duplicate / Cut=move (consumed on paste).
#[derive(Clone, Copy, PartialEq, Eq)]
enum ClipOp {
    Copy,
    Cut,
}

/// Copy/cut targets pushed with `Y`/`X`. Apply them with `P` to the cursor-based directory.
#[derive(Clone)]
struct Clipboard {
    op: ClipOp,
    paths: Vec<PathBuf>,
}

/// Size of `App` in bytes — a memory guard reads this to catch a struct that suddenly balloons.
#[cfg(test)]
pub fn sizeof_app() -> usize {
    std::mem::size_of::<App>()
}

/// Size of one `PerTab` in bytes. `PerTab` is cloned per tab (snapshot / restore), so a regression
/// that inlines a large buffer into it multiplies memory by the tab count — this guards against that.
#[cfg(test)]
pub fn sizeof_pertab() -> usize {
    std::mem::size_of::<PerTab>()
}

/// The media payload loaded on a separate thread (sent back to the UI thread).
pub enum MediaPayload {
    /// A still image (single-frame GIF / video thumb / PDF page) → goes to image_src.
    Static(image::DynamicImage),
    /// All GIF frames (composited RGBA + delay) → goes to gif_frames.
    Gif(Vec<(image::DynamicImage, std::time::Duration)>),
    /// A raster of a vector source (SVG file / mermaid diagram). The SVG is retained so zooming
    /// re-rasterizes at the needed density (sharp zoom) instead of blowing up pixels.
    Vector {
        img: image::DynamicImage,
        svg: std::sync::Arc<Vec<u8>>,
    },
}

/// Result of media loading from another thread. Matched by generation via `gen`; results made stale by navigation are discarded.
pub struct MediaResult {
    gen: u64,
    /// None = decode/rasterize failure (the render side shows a fallback).
    payload: Option<MediaPayload>,
}

/// The geometry a kitty image targets: `(crop rect (x,y,w,h) in source px, display cols, rows)`.
type KittyGeom = ((u32, u32, u32, u32), u16, u16);

/// Result of an async kitty image build (resize + `o=z` compress) from a worker thread. Matched by
/// `gen` (latest-wins): a build superseded by a newer zoom/pan is discarded. None = build failed.
pub struct KittyResult {
    gen: u64,
    image: Option<crate::preview::kitty::KittyImage>,
}

/// Heavy media loading to run on a separate thread (pure work that does not reference App).
enum MediaJob {
    /// Rasterize an SVG (path, max-edge px). Vector-backed: keeps the source for sharp zoom.
    Svg(PathBuf, u32),
    /// Expand all GIF frames. Falls back to still-image decode for single-frame/non-animated GIFs.
    Gif(PathBuf),
    /// Extract one representative frame from a video (delegated to ffmpegthumbnailer/ffmpeg). Thumbnail only; no playback.
    Video(PathBuf),
    /// Rasterize page N (1-based) of a PDF (delegated to pdftocairo/pdftoppm/qlmanage/sips). Loaded one page at a time.
    Pdf(PathBuf, u32),
    /// Render a standalone mermaid file to SVG (pure Rust) and rasterize it (max-edge px, theme).
    /// None (unsupported diagram / parse failure) → the caller's text-diagram fallback shows.
    Mermaid(PathBuf, u32, String),
    /// Render mermaid source text (a ```mermaid fence opened full-screen) and rasterize it.
    MermaidSrc(String, u32, String),
    /// Re-rasterize the retained SVG source at a new max-edge px (sharp zoom). The path is only
    /// the base for relative resources inside the SVG (mermaid output has none).
    SvgReraster(std::sync::Arc<Vec<u8>>, PathBuf, u32),
}

impl MediaJob {
    /// Load the actual data (called on a separate thread or via the synchronous fallback). None on failure.
    fn run(self) -> Option<MediaPayload> {
        match self {
            MediaJob::Svg(p, max_px) => {
                let data = std::fs::read(&p).ok()?;
                let img = crate::preview::svg::rasterize_bytes(&data, &p, max_px)?;
                Some(MediaPayload::Vector {
                    img,
                    svg: std::sync::Arc::new(data),
                })
            }
            MediaJob::Gif(p) => match crate::preview::image::decode_gif(&p) {
                Some(frames) => Some(MediaPayload::Gif(frames)),
                // 単一フレーム/アニメでない GIF → 静止画として表示。
                None => crate::preview::image::decode_static(&p).map(MediaPayload::Static),
            },
            MediaJob::Video(p) => crate::preview::video::thumbnail(&p).map(MediaPayload::Static),
            MediaJob::Pdf(p, page) => {
                crate::preview::pdf::render_page(&p, page).map(MediaPayload::Static)
            }
            MediaJob::Mermaid(p, max_px, theme) => {
                let code = std::fs::read_to_string(&p).ok()?;
                MediaJob::MermaidSrc(code, max_px, theme).run()
            }
            MediaJob::MermaidSrc(code, max_px, theme) => {
                let svg = crate::preview::markdown::mermaid_to_svg(&code, &theme)?;
                let data = svg.into_bytes();
                let img =
                    crate::preview::svg::rasterize_bytes(&data, Path::new("mermaid.svg"), max_px)?;
                Some(MediaPayload::Vector {
                    img,
                    svg: std::sync::Arc::new(data),
                })
            }
            MediaJob::SvgReraster(svg, p, max_px) => {
                let img = crate::preview::svg::rasterize_bytes(&svg, &p, max_px)?;
                Some(MediaPayload::Vector { img, svg })
            }
        }
    }
}

/// Result of the **heavy ignored set (`git::ignored`)** computed on a separate thread. Staleness is judged by `gen`, and
/// only the latest generation is applied (results from after moving to another repo while computing are discarded). `workdir` is the
/// repo workdir being computed; on apply it is put into `git_ignored_for` to serve as the Phase G cache key.
pub struct IgnoredResult {
    gen: u64,
    workdir: PathBuf,
    set: std::collections::HashSet<PathBuf>,
}

/// One decoded media payload kept across a tab switch (see `App::media_cache`).
struct MediaCache {
    path: PathBuf,
    mtime: Option<std::time::SystemTime>,
    /// File size alongside the mtime. Archive extraction and `cp -p` / `rsync -a` **preserve the mtime**,
    /// so mtime alone would keep serving the old picture; the size catches the common case of those.
    len: Option<u64>,
    /// PDF page the image belongs to (1 for every other kind), so paging is not confused with a hit.
    page: u32,
    /// Which mermaid fence inside the document this render belongs to. A full-screen fence keeps
    /// `preview_path` pointing at the **Markdown file**, so without this two fences of the same document
    /// look identical to the cache and switching tabs would show the other diagram.
    fence_ord: Option<usize>,
    src: std::sync::Arc<image::DynamicImage>,
    logical: Option<(u32, u32)>,
    vector_svg: Option<std::sync::Arc<Vec<u8>>>,
}

/// Result of `git status` + branch computed on a separate thread. Staleness is judged by `gen` exactly like
/// [`IgnoredResult`], so a scan that finishes after the user has already moved on is discarded.
///
/// `git status` is a **whole-worktree scan**: even on a tiny repository it costs ~5ms (process spawn +
/// repo discovery), and it grows with the working tree. Running it on the UI thread made every tab switch
/// pay that cost synchronously, which is why it is offloaded here (design principle #4 "never block the UI").
pub struct StatusResult {
    gen: u64,
    workdir: Option<PathBuf>,
    statuses: std::collections::HashMap<PathBuf, crate::git::FileStatus>,
    branch: Option<String>,
}

pub struct App {
    /// The directory opened at startup (immutable). The reset target for `A` ResetAnchor. Kept separately because open_dir moves with `a`.
    launch_dir: PathBuf,
    pub path_style: PathStyle,
    pub key_scheme: KeyScheme,
    pub lang: crate::i18n::Lang,
    pub cfg: Config,

    /// Tree sort settings (FR / M7 auxiliary). Global (not per-tab). Changed via the `s` menu.
    pub sort: Sort,
    /// Whether the `s` sort-selection menu is showing (while true, main intercepts keys).
    sort_menu: bool,
    /// Bookmarks (M7 auxiliary). Lowercase a-z=local (per launch dir) / uppercase A-Z=global.
    pub bookmarks: crate::bookmarks::Bookmarks,
    /// Tab-session persistence (`[ui] restore_tabs`). Attached by main like the loader senders;
    /// `None` (tests) = tab operations never write session files.
    session_store: Option<crate::session::SessionStore>,
    /// True only while `restore_session` is rebuilding the saved tabs. Suppresses the per-op
    /// `save_session` calls that `tab_new`/`tab_goto` would otherwise fire, so a crash mid-restore
    /// cannot overwrite the on-disk session with a partial set; one complete write happens at the end.
    session_restoring: bool,
    /// State of waiting for a letter after `m`/`'` (Set=register / Jump=jump).
    /// Waiting for the letter key after `m` (bookmark set). (`'` opens the list directly.)
    mark_set_pending: bool,
    /// Whether the bookmark-list overlay is showing.
    bookmark_list: bool,
    /// Selection position in the list (a flat index over local on top and global below, concatenated).
    bookmark_list_sel: usize,
    /// Confirmation/input dialog (create `a` / rename `R` / delete `D`). While showing, main intercepts keys.
    dialog: Option<Dialog>,
    /// File clipboard (M7 Phase B). Push with `Y`=copy/`X`=cut, apply with `P`=paste.
    clipboard: Option<Clipboard>,

    /// Follow mode (`F`, global): while true, an external file change (e.g. an AI agent writing) jumps the
    /// tree selection to that file and opens its preview. Any other keypress turns it off (Zed-style).
    follow_mode: bool,
    /// Files changed during the current follow session (since `F` was last turned ON; first-change order,
    /// deduped). Powers the session-scoped `n`/`N` review in follow-opened diffs — "what just changed",
    /// not the whole dirty worktree. Kept after follow turns off (review continues); reset by the next ON.
    follow_session: Vec<PathBuf>,
    /// Whether the current GitDiff preview was opened by follow mode. While true, `n`/`N` and the title's
    /// position indicator use `follow_session` instead of the full git change set.
    diff_follow_scope: bool,
    /// In a follow-opened diff, show the FULL git diff (vs HEAD/index) instead of the diff since
    /// follow-start. Toggled per-session by the diff-scope key; reset to false (baseline) each `F`-on.
    follow_diff_full: bool,
    /// Snapshot captured at follow-start (`F` on), so follow diffs show only changes SINCE that point —
    /// pre-existing uncommitted changes are folded into the baseline and stay invisible. Held in memory,
    /// bounded to the files that were dirty at follow-start (clean files use the pinned HEAD blob on
    /// demand). Captured on each `F`-on and KEPT afterwards (through `follow_break`/off, so the session's
    /// diffs stay reviewable via `n`/`N`/`f`) until the next `F`-on recaptures it; only ever consulted
    /// under `diff_follow_scope`. See `docs/FEATURE-FOLLOW-BASELINE-2026-07.md`.
    #[cfg(feature = "git")]
    follow_baseline: Option<FollowBaseline>,

    /// Total wrapped display rows of the current decorated Markdown at the last render (what
    /// `preview_scroll` is clamped against). Set by the preview renderer; used with `MdCache::src_lines`
    /// to map the scroll position back to an approximate source line when opening the editor (`e`).
    pub md_view_rows: usize,

    /// less-style windowed reading for Code/Text (does not read the whole file). Always Some during a Code/Text preview.
    /// While Some, scrolling uses `tab.preview_byte_top` (the line-head byte) instead of preview_scroll.
    preview_win: Option<crate::preview::window::FileWindow>,
    /// Cache of the total line count (computed once with count_lines when line numbers are ON).
    preview_total_lines: Option<usize>,
    /// Cache of the highlighted window (avoids re-highlighting on every render).
    win_cache: Option<WinCache>,

    /// Whether the current Code preview is a "heavy first time" (waiting for grammar compilation of a cold language).
    /// While true, the render shows a loading display (indicator) or plain text (progressive).
    /// Judged with `code::is_ext_warm` at preview start; if already warm, false from the start (immediate coloring).
    hl_pending: bool,
    /// Whether a background-thread warm is in progress (prevents double-launch). Common to indicator/progressive.
    hl_warming: bool,
    /// Frame index of the central spinner (advanced by the run loop while waiting on the indicator = animation).
    spinner_frame: usize,

    /// The file requested for external-editor launch via `e`, plus the 1-based line to open at (matching
    /// the on-screen preview position; None = open at the top). The run loop takes it, suspends the TUI, and
    /// launches (because entering/leaving the terminal must happen on the render thread, here we only raise the "request").
    pending_edit: Option<(PathBuf, Option<usize>)>,

    /// Flag requesting launch of an external git tool (lazygit, etc.) via `O`. The run loop takes it, suspends the TUI, and launches.
    pending_git_tool: bool,

    /// Cache of decorated preview content (Markdown/Mermaid).
    /// Avoids re-parsing (pulldown-cmark/syntect/mermaid layout) on every scroll.
    /// It depends on width (to fit mermaid to the display width), so the key is (path, width).
    md_cache: Option<MdCache>,

    /// Cache of raw diff lines for the GitDiff preview (per path). Avoids recomputing `git diff` every frame.
    diff_cache: Option<DiffCache>,
    gutter_cache: Option<GutterCache>,

    /// Interactive items in the Markdown preview (links + task checkboxes, collected on each render).
    /// Focus with Tab/⇧Tab; Enter opens a link / toggles a checkbox, Space toggles a checkbox.
    md_items: Vec<MdItem>,
    /// Per-`<details>`-block open override (ordinal → open), set by `Space`/`Enter` on the summary.
    /// Absent = the default (from the `open` attribute + `ui.md_details`). Reset on file/tab change.
    details_open: std::collections::HashMap<usize, bool>,

    /// The matching table cells as a set, for O(1) lookup while rendering (mirrors `tab.search_matches`).
    /// Kept separate so a large result set does not turn cell drawing into a linear scan.
    table_search_hits: std::collections::HashSet<(usize, usize)>,

    /// Image backend (M2). None if the terminal is unsupported or uninitialized, in which case images fall back to text.
    /// For rendering, ui::preview passes `image` by &mut to StatefulImage. Resize/encode is
    /// offloaded to a separate thread via `img_tx`, and the result is applied in apply_image_resize.
    picker: Option<Picker>,
    img_tx: Option<UnboundedSender<ResizeRequest>>,
    pub image: Option<ThreadProtocol>,
    /// On a kitty-graphics terminal, still images take konoma's own transmit path instead of
    /// ratatui-image's `image`/`ThreadProtocol`: the pixels are **zlib-compressed** (`o=z`), which
    /// shrinks the terminal transfer 2×–50× (the real latency; see docs/PERF-IMAGE-TRANSFER-2026-07).
    /// `use_kitty` is set from the picker's protocol type; on other terminals (sixel/iterm2/
    /// halfblocks) `kitty_image` stays None and the `image` path is used unchanged.
    use_kitty: bool,
    kitty_is_tmux: bool,
    /// The prepared compressed image for the current crop (None until built / on non-kitty terminals).
    kitty_image: Option<crate::preview::kitty::KittyImage>,
    /// Offloads the kitty resize+compress (~30–50 ms) to a worker thread so rapid zoom/pan does not
    /// hitch the UI. The **first** build after opening a file stays synchronous (so the image appears
    /// without a blank frame); subsequent rebuilds (zoom/pan/resize) go async and the previous image
    /// keeps showing until the new one arrives. None in tests → everything runs synchronously.
    kitty_tx: Option<std::sync::mpsc::Sender<KittyResult>>,
    /// Latest-wins generation for async kitty builds: only the newest spawn's result is applied.
    kitty_gen: u64,
    /// The (crop, cols, rows) the current kitty image (or in-flight build) targets. Prevents
    /// re-spawning the same build every frame while the geometry is unchanged.
    kitty_want: Option<KittyGeom>,
    /// The geometry the **currently shown** kitty image was actually built for. A build is in flight
    /// exactly when this differs from `kitty_want` (covers pan, where the cell size is unchanged).
    kitty_shown: Option<KittyGeom>,
    /// The source image (decoded). Zoom/pan crops this at render time and rebuilds the protocol
    /// (because ratatui-image has no offset pan). Held in an `Arc` so the async kitty-build worker
    /// can share it without copying the (potentially large) pixels.
    image_src: Option<std::sync::Arc<image::DynamicImage>>,
    /// The most recently built crop rectangle (source-image px: x,y,w,h). The protocol is rebuilt only when it changes.
    image_crop: Option<(u32, u32, u32, u32)>,
    /// The most recent visible fraction (0..1, w/h). Less than 1 = the image overflows the viewport and is clipped = pan is possible.
    image_vis_frac: (f64, f64),
    /// SVG source of the current image preview when it is vector-backed (SVG file / mermaid diagram).
    /// Zooming past the raster's density re-rasterizes this at the needed scale on a worker thread
    /// ("sharp zoom"); raster images leave it None (pixel zoom only).
    vector_svg: Option<std::sync::Arc<Vec<u8>>>,
    /// Logical (layout) pixel size of a vector-backed image = the dimensions of its **first** raster.
    /// `image_layout` sizes/zooms against this identity, so swapping in a sharper raster changes only
    /// pixel density, never the on-screen geometry (HiDPI-style backing store).
    image_logical: Option<(u32, u32)>,
    /// A full-screen sharp-zoom re-raster is in flight (at most one — key-repeat `+` must not spawn
    /// the same job a dozen times; the inline-fence analog is `MdImgEntry::reraster_inflight`).
    /// Cleared when a media result arrives (`apply_media`) and by `clear_image` (generation bump).
    vector_reraster_inflight: bool,
    /// Signature of the inline-image overlay drawn last frame (urls + screen rects). When it
    /// changes (scroll/focus moved a diagram, or the document was left), the run loop clears the
    /// terminal once to sweep orphaned kitty unicode-placeholder rows (they are printed into the
    /// terminal grid and a blank-over-blank diff never repaints them).
    md_overlay_last: Option<u64>,
    /// Overlay signature seen during the current frame (None until the overlay draws).
    md_overlay_seen: Option<u64>,
    /// The overlay moved/vanished since the previous frame → the run loop full-redraws once.
    md_overlay_moved: bool,

    /// mtime of the previewed media file at load time. Media (image/svg/gif/video/pdf) is reloaded on an
    /// FS event only when this changes (avoids re-decoding / re-running external tools on unrelated edits).
    preview_media_mtime: Option<std::time::SystemTime>,
    /// The decoded media of the tab we most recently switched **away from**, so switching back does not
    /// redo the work that produced it. That work is not just an image decode: SVG/mermaid are
    /// rasterized and PDF/video shell out to `pdftocairo` / `ffmpeg`, which costs hundreds of
    /// milliseconds. Exactly **one** slot, holding an `Arc` clone of the source image that was already
    /// in memory, so the extra footprint is bounded to a single image. Animated GIFs are never cached
    /// (their frames are separate state). Reuse requires an exact `(path, mtime, page)` match, so an
    /// externally edited file is always re-read.
    media_cache: Option<MediaCache>,

    /// Parsed CSV/TSV table (Some while a table preview is active and parsing succeeded).
    /// None while not a table, or when parsing failed (then the preview degrades to raw text).
    table_data: Option<crate::preview::table::TableData>,
    /// Per-tab bundle — see `PerTab` (root/mode/preview target/scroll, table cursor/scroll, git-view
    /// overlay, windowed-preview scroll/caret, image/PDF pan-page, Markdown raw/focus/fence-zoom,
    /// selection/filter/search). `pub(crate)` because ui/main read the 13 fields that used to be
    /// flat `pub` on `App` (root/open_dir/entries/selected/show_hidden/tree_viewport/mode/
    /// preview_path/preview_kind/preview_scroll/preview_hscroll/preview_viewport/image_zoom) directly
    /// as `app.tab.<field>`.
    pub(crate) tab: PerTab,
    /// Visible data-row count at the last render (the page size for PageUp/Down). Set by the renderer.
    table_viewport_rows: u16,

    /// Visual-selection anchor `(line, col)`. Some = selecting. Charwise (`v`) uses both; linewise (`V`) uses the line.
    preview_visual_anchor: Option<(usize, usize)>,
    /// Whether the active selection is linewise (`V`, whole lines) rather than charwise (`v`, exact character range).
    preview_visual_linewise: bool,

    /// GIF animation (M6). All frames (composited RGBA) + each display duration. Empty means no animation (still image).
    /// A separate path from the still-image asynchronous ThreadProtocol: to avoid the "render an unencoded
    /// new protocol → nothing shows" churn in an animation whose frame changes each time, the current frame is **synchronously encoded**
    /// and atomically swapped into `gif_protocol` (see below). Zoom/pan share image_zoom/image_center.
    gif_frames: Vec<(image::DynamicImage, std::time::Duration)>,
    /// Index of the currently displayed GIF frame.
    gif_idx: usize,
    /// The time the current frame began showing (the start point for the next-frame deadline). None=before the first tick.
    gif_shown_at: Option<std::time::Instant>,
    /// The render protocol (kitty, etc.) of the current frame synchronously encoded to the display size. Drawn with the Image widget.
    gif_protocol: Option<Protocol>,
    /// The (frame index, crop rectangle) gif_protocol was built from. Re-encoded only when it changes (avoids wasteful re-encode).
    gif_proto_key: Option<(usize, (u32, u32, u32, u32))>,

    /// Sending end that offloads heavy media loading (SVG rasterize / GIF full-frame decode) to a separate thread.
    /// The result is received by main's poll loop and applied in apply_media. None=synchronous fallback (tests, etc.).
    media_tx: Option<std::sync::mpsc::Sender<MediaResult>>,
    /// Decoded/encoded cache for inline Markdown images, keyed by resolved absolute path.
    md_image_cache: std::collections::HashMap<PathBuf, MdImgEntry>,
    /// Render cache for the tree's detail columns (`ui.details`): path → formatted cells.
    /// Filled lazily for visible rows (render pre-pass) and dropped on every tree rebuild, so the
    /// per-row stat (and the `items` column's read_dir) runs once per tree generation instead of
    /// on every keypress.
    detail_cells_cache: std::collections::HashMap<PathBuf, Vec<String>>,
    /// Sender that offloads inline-image decoding to a background thread.
    md_img_tx: Option<std::sync::mpsc::Sender<MdImageResult>>,
    /// Remote inline-image URLs whose background download is in flight (deduplicates fetches).
    md_remote_inflight: std::collections::HashSet<String>,
    /// Remote inline-image URLs whose download failed — do not retry; they show a text placeholder.
    md_remote_failed: std::collections::HashSet<String>,
    /// Sender that reports the completion of a background remote-image download to the run loop.
    md_remote_tx: Option<std::sync::mpsc::Sender<RemoteFetch>>,
    /// Sender that offloads inline-image encoding (resize + protocol) to the encode worker thread.
    md_enc_tx: Option<std::sync::mpsc::Sender<MdEncodeRequest>>,
    /// Media-load generation. Incremented in enter_preview/clear to make old thread results stale.
    media_gen: u64,
    /// Whether waiting on another thread's media load (used by the render side to show "Loading…").
    media_loading: bool,

    /// Run2 keymap (Surface × key → Action). Built from the config at startup.
    pub keymaps: crate::keymap::KeyMap,
    /// which-key leader-pending state (`Space`=file management / `y`=path copy). After the press, a
    /// which-key menu is shown in the footer and the next keystroke confirms/cancels (a generalization of the old two-key pending_chord).
    pub pending_leader: Option<crate::keymap::LeaderId>,

    /// A transient message (copy result, etc.). Cleared on the next key input. Shown in the status line.
    pub flash: Option<String>,

    /// Visibility state and scroll position of the `?` help (full key list) overlay.
    pub show_help: bool,
    pub help_scroll: u16,
    /// Visibility state of the `i` file-info popup.
    pub show_info: bool,

    /// Tabs (FR-5). Each tab is a tree context. The active tab's working state is held in the fields above as the source of truth.
    tabs: Vec<PerTab>,
    active_tab: usize,
    /// Tab-list overlay (`T`). App-global (not per-tab).
    tab_list: bool,
    tab_list_sel: usize,
    /// Heading-outline overlay (`o` in a Markdown preview): jump to any heading.
    outline_open: bool,
    outline_sel: usize,

    /// git status (FR-7). Absolute path → kind. Cached per root and re-fetched when root changes.
    git_status: std::collections::HashMap<PathBuf, crate::git::FileStatus>,
    /// The set of top-level gitignore-excluded entries (`git::ignored`). Used to decide which tree entries are dimmed.
    /// Since it is a heavy computation, it is cached **per repo (workdir)** (`git_ignored_for`), so moving root to a
    /// subdirectory within the same repository does not rebuild it.
    git_ignored: std::collections::HashSet<PathBuf>,
    /// The root at which `git_status`/`git_branch` were computed. If it differs from the current root, a re-fetch is *considered* (but see `git_status_workdir`).
    git_status_for: Option<PathBuf>,
    /// The **repo workdir** `git_status`/`git_branch` cover. `git status` is run from the workdir, so its
    /// result is identical anywhere within the same repo — moving root with `l`/`h` reuses it instead of
    /// re-running a full worktree scan (slow on large repos). Same idea as `git_ignored_for` for the ignore set.
    git_status_workdir: Option<PathBuf>,
    /// The cached `git_status` may be stale (a file changed, a commit/checkout happened, ignore rules
    /// changed): force a recompute on the next `refresh_git_if_needed` even if the workdir is unchanged.
    git_status_dirty: bool,
    /// The root for which `git status` is being computed on a separate thread (guard against duplicate
    /// dispatch). None = not computing. Keyed by **root** (never None while in flight), so the
    /// `pending == target` comparison can't be satisfied by two `None`s the way `git_ignored_pending` can.
    git_status_pending: Option<PathBuf>,
    /// Generation of the `statuses` computation. Incremented on dispatch; a result is applied only if it
    /// still matches (discards scans superseded by a newer root/tab change).
    git_status_gen: u64,
    /// Sender returning results from the worker computing `statuses`+`branch` in the background.
    /// If not attached (tests), `spawn_or_sync_statuses` falls back to computing synchronously.
    status_tx: Option<std::sync::mpsc::Sender<StatusResult>>,
    /// The **repo workdir** at which `git_ignored` (heavy) was computed. If it is the same, root moves within the same repository
    /// do not rebuild it (avoids the 410ms recomputation when descending into a subdirectory with `l`).
    git_ignored_for: Option<PathBuf>,
    /// The workdir for which `ignored` is being computed on a separate thread (a guard against duplicate dispatch). None=not computing.
    git_ignored_pending: Option<PathBuf>,
    /// Generation of the `ignored` computation. Incremented by +1 on dispatch; a result is applied only if it matches this generation
    /// (discards stale results from after moving to another repo while computing).
    git_ignored_gen: u64,
    /// Flag to **rebuild even for the same repo** because the ignore rules (`.gitignore`/`.git/info/exclude`) changed.
    /// Comes from FS events. Set when a recompute is wanted even if workdir is the same (the old set is kept until the result is applied).
    git_ignored_dirty: bool,
    /// Sender that returns results to the worker computing `ignored` in the background. If not attached (tests, etc.), a synchronous fallback is used.
    ignored_tx: Option<std::sync::mpsc::Sender<IgnoredResult>>,
    /// git diff layout (vertical/horizontal/Auto). Initialized from the `git.diff` setting and cycled with `s`. Used by both the GitDiff preview
    /// and the commit/working-tree detail.
    diff_layout: DiffLayout,
    /// The current branch name (fetched at the same time as git status). None if not a repo.
    git_branch: Option<String>,

    /// Whether the branch-visibility panel (`b`) is open. Modal/transient — not per-tab (reset, not
    /// restored, on tab switch; see `PerTab` for the per-tab git-view overlay state).
    git_graph_picker: bool,
    /// Cursor position in the panel (row = branch).
    git_graph_picker_sel: usize,
    /// Tentative selection while editing the panel (committed to `git_graph_visible` with Enter / discarded with q).
    git_graph_picker_set: std::collections::HashSet<String>,
    /// Whether `J`/`K` reordering was done in the panel (so the base is re-derived to the top branch on Enter confirm).
    git_graph_reordered: bool,
}

/// Path-copy kind (FR-6). Chosen by the key after `c`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CopyKind {
    /// File name only (`cn`).
    Name,
    /// Full path (`cp`).
    Full,
    /// Path relative to where it was opened (`cr`).
    Relative,
    /// Full path of the parent directory (`cd`).
    Parent,
    /// `@relative/path` reference for AI agents (`y@`). Claude Code reads `@path` as file context, so
    /// the path is strictly relative to `open_dir` (the launch/anchor dir where the agent usually runs),
    /// **without** the leading directory name that `Relative` prepends for display.
    AtRef,
}

/// Commit-info copy kind (chosen after `y` in git log/graph/detail).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(not(feature = "git"), allow(dead_code))]
pub enum GitCopyKind {
    /// Short hash (7 digits).
    ShortHash,
    /// Full hash (40 digits).
    FullHash,
    /// Subject (the first line of the message).
    Subject,
    /// Full message (subject + body, multi-line).
    Message,
    /// Author name.
    Author,
    /// Date.
    Date,
}

/// What the in-preview search (`/`) searches, which decides how matches are found and how `n`/`N`
/// move. Each preview kind addresses positions differently, so the search plumbing routes on this
/// instead of testing preview fields in several places.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum SearchTarget {
    /// Code/Text and raw (`R`) Markdown: byte offsets into the file, moved via the read window.
    Windowed,
    /// CSV/TSV: (data row, column) cell coordinates, moved via the cell cursor.
    Table,
    /// Decorated Markdown/Mermaid: indices into the **decorated** lines, moved by scrolling.
    Markdown,
    /// Media and diffs — no search model (`/` flashes a hint).
    Unsupported,
}

/// CSV/TSV table copy kind (chosen after `y` in the table preview).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TableCopyKind {
    /// The current cell's value.
    Cell,
    /// The current row's cells joined by the delimiter (`,` / tab).
    Row,
    /// The current column's header plus every cell value, one per line.
    Column,
}

/// Cache of decorated preview content. The key is (path, display width).
/// Everything derivable once per (path, width) lives here so a frame only clones the visible
/// slice (`md_slice`) instead of re-cloning / re-flowing the whole document on every keypress.
struct MdCache {
    path: PathBuf,
    width: u16,
    /// Decorated lines with links already collapsed (label-only; URLs recovered into `items`) —
    /// exactly what the renderer draws, minus the per-frame focus inversion.
    lines: Vec<Line<'static>>,
    /// Tab-cycle items (links / task checkboxes / code-block headers) in document order,
    /// built once from `lines`. Mirrored into `App::md_items` when the cache is (re)built.
    items: Vec<MdItem>,
    /// Block-level inline images reserved within `lines` (Markdown only; empty otherwise).
    images: Vec<crate::preview::markdown::ImagePlacement>,
    /// Number of source lines in the file. Used with the on-screen wrapped-row count to map the scroll
    /// position back to an approximate source line, so `e` opens the editor near the top of the view.
    src_lines: usize,
    /// Widest line in display cells (horizontal-scroll clamp for wrap=off).
    max_line_cols: usize,
    /// wrap=on: visual (post-wrap) start row of each line via ratatui's own per-line reflow;
    /// `len = lines.len() + 1`, last element = total display rows. Empty when wrap=off or width=0.
    row_prefix: Vec<usize>,
    /// Effective mermaid target rows the cache was built with (fit-to-view). A viewport change
    /// only invalidates documents that actually contain fence diagrams.
    fence_rows: u16,
    /// In-page anchor map (GitHub slug → decorated logical-line index) for `[x](#slug)` jumps.
    anchors: Vec<(String, usize)>,
    /// Effective open/closed state of each `<details>` block (document order) as rendered — the base
    /// a `Space`/`Enter` toggle flips.
    details_states: Vec<bool>,
}

/// Cache of raw diff lines for the GitDiff preview. `file_diff` (the git call) does not depend on display width
/// (side-by-side/coloring is done separately at render time), so the key is the path only. This avoids re-invoking git on every
/// scroll/horizontal scroll/resize (aligned with log/graph: load once on open).
/// Since the diff changes when the working tree changes, it is invalidated by `refresh()` (FS events / manual refresh).
struct DiffCache {
    path: PathBuf,
    lines: Vec<crate::git::DiffLine>,
}

/// Per-file cap for a follow baseline snapshot: a dirty file larger than this is not snapshotted
/// (recorded as `None`), and its follow diff falls back to the full git diff (honest degradation).
#[cfg(feature = "git")]
const FOLLOW_BASELINE_FILE_CAP: usize = 5 * 1024 * 1024;
/// Total cap across all snapshotted baseline files: once exceeded, remaining dirty files are recorded
/// as `None` (full-diff fallback) so pressing `F` on a fully-dirty tree never balloons memory.
#[cfg(feature = "git")]
const FOLLOW_BASELINE_TOTAL_CAP: usize = 64 * 1024 * 1024;

/// The follow-start snapshot. `dirty` holds the content of files that were already modified/untracked
/// at follow-start (keyed by canonicalized path): `Some(bytes)` = snapshotted, `None` = skipped for
/// size (falls back to full diff). Files NOT in `dirty` were clean at follow-start, so their baseline
/// is the blob at `head`.
#[cfg(feature = "git")]
struct FollowBaseline {
    dirty: std::collections::HashMap<PathBuf, Option<Vec<u8>>>,
    head: Option<String>,
}

/// Cache of the editor-style git gutter marks (per new-file line) for the currently-previewed code/text
/// file. Keyed by path; a working-tree change (`refresh`) drops it so external edits re-derive. Avoids
/// re-invoking `file_diff` (a git call) on every scroll/keypress while previewing.
struct GutterCache {
    path: PathBuf,
    marks: std::collections::HashMap<u32, GutterMark>,
}

/// One interactive item within a rendered Markdown preview: a link or a task-list checkbox.
/// `line`=index of the decorated line (for scrolling). Both are collected straight from the render
/// result (links = underlined blue spans + collapsed targets, checkboxes = `task_marker_style` spans),
/// so no source re-parsing is needed.
#[derive(Clone)]
struct MdItem {
    line: usize,
    kind: MdItemKind,
}

#[derive(Clone)]
enum MdItemKind {
    /// A link; `target`=URL/relative path.
    Link { target: String },
    /// A task checkbox; `state`=its current state char (` `/`x`/custom) as shown.
    Task { state: char },
    /// A fenced code block (its header line is the focus target; `Enter` copies its raw source).
    CodeBlock,
    /// An inline mermaid diagram (image mode); `ordinal`=fence index in document order.
    /// `Enter` opens it full screen with zoom/pan.
    MermaidFence { ordinal: usize },
    /// A `<details>` summary line; `ordinal`=details-block index in document order.
    /// `Enter`/`Space` toggle it collapsed ⇄ expanded.
    Details { ordinal: usize },
}

/// Cache of highlighted lines for windowed reading.
/// The key is (path, top byte, height). Rebuilt only when scroll/vertical resize changes it.
/// (Line content does not depend on display width, so width is not part of the key.)
struct WinCache {
    path: PathBuf,
    byte_top: u64,
    height: u16,
    /// Whether `lines` carry syntax colors. Plain text is cached too (same key space); the flag
    /// keeps a colored window from being mistaken for a plain one when the highlight state flips.
    styled: bool,
    lines: Vec<Line<'static>>,
}

/// A decoded inline Markdown image plus its background-encoded render protocol(s).
#[derive(Default)]
struct MdImgEntry {
    /// The decoded source image (None while the background decode is in flight). Shared with the encode
    /// worker via `Arc` (cheap clone) so cropping/encoding happens off the UI thread.
    decoded: Option<Arc<image::DynamicImage>>,
    /// The graphics protocol for the fully-visible image, encoded for `proto_size`.
    protocol: Option<Protocol>,
    /// The (cols, rows) `protocol` was encoded for.
    proto_size: Option<(u16, u16)>,
    /// The graphics protocol for a partially-scrolled image: only the visible vertical band, cropped and
    /// encoded so the image renders clipped instead of being hidden. Re-encoded when the band changes.
    clip_protocol: Option<Protocol>,
    /// The (cols, full_rows, row_off, vis_rows) band `clip_protocol` was encoded for.
    clip_key: Option<(u16, u16, u16, u16)>,
    /// An encode request is in flight on the worker thread (at most one per image, so scrolling does not
    /// queue a backlog — when it returns, the next render requests the then-current band).
    enc_inflight: bool,
    /// Decode or encode failed — do not retry; the placeholder/text fallback stays visible.
    failed: bool,
    /// In-place zoom protocol for a **focused inline mermaid diagram** (`+`/`-` while focused):
    /// a crop of the source encoded into the same (cols, rows) cell area (the layout never moves).
    zoom_protocol: Option<Protocol>,
    /// The (cols, rows, crop px rect) `zoom_protocol` was encoded for.
    zoom_key: Option<(u16, u16, PxRect)>,
    /// SVG source of a rendered mermaid fence — kept so in-place zoom can re-rasterize at a higher
    /// density (sharp zoom, same mechanism as the full-screen vector zoom).
    svg: Option<std::sync::Arc<Vec<u8>>>,
    /// Layout size = the **first** raster's dimensions. The markdown layout (cells) is computed from
    /// this, so a sharper re-raster never changes the reserved area (the user-visible size is fixed).
    layout_px: Option<(u32, u32)>,
    /// A sharpening re-raster is in flight (at most one per diagram).
    reraster_inflight: bool,
}

/// Outcome of a fence-sharpen check (the sync variant lets tests re-run with the new raster).
#[derive(PartialEq)]
enum FenceSharpen {
    NotNeeded,
    Spawned,
    AppliedSync,
}

/// Which protocol a background encode produces (so the result is stored in the right slot).
#[derive(Clone, Copy, PartialEq, Debug)]
enum MdEncodeKey {
    /// The whole image at (cols, rows) cells.
    Full { cols: u16, rows: u16 },
    /// A cropped vertical band, keyed by (cols, full_rows, row_off, vis_rows).
    Clip {
        cols: u16,
        full_rows: u16,
        row_off: u16,
        vis_rows: u16,
    },
    /// An in-place zoom crop of a focused inline mermaid diagram, encoded into the same
    /// (cols, rows) area. Keyed by the pixel crop so pan/zoom/re-raster all re-encode naturally.
    Zoom { cols: u16, rows: u16, crop: PxRect },
}

/// A request to encode an inline image (or a cropped band of it) off the UI thread (principle #4).
pub struct MdEncodeRequest {
    path: PathBuf,
    key: MdEncodeKey,
    image: Arc<image::DynamicImage>,
    /// Pixel band to crop before encoding; None encodes the whole image.
    crop: Option<PxRect>,
    cols: u16,
    rows: u16,
}

/// Result of a background inline-image encode, delivered to the run loop.
pub struct MdEncodeResult {
    path: PathBuf,
    key: MdEncodeKey,
    /// None = the encode failed. The worker **always** sends a result: swallowing failures left
    /// `enc_inflight` latched on, freezing all re-encodes of that image and keeping
    /// `md_images_loading()` true forever (busy spinner + 16ms polling — idle CPU 0% broken).
    protocol: Option<Protocol>,
}

/// Background worker that encodes inline-image protocols (the whole image or a cropped band) with a
/// cloned Picker, so the UI thread never blocks on the resize/encode (principle #4). Exits when the
/// request sender is dropped (App teardown).
pub fn md_encode_worker(
    picker: Picker,
    rx: std::sync::mpsc::Receiver<MdEncodeRequest>,
    tx: std::sync::mpsc::Sender<MdEncodeResult>,
) {
    while let Ok(req) = rx.recv() {
        let (path, key) = (req.path.clone(), req.key);
        let picker = &picker; // 借用: move クロージャがループ跨ぎで picker を消費しないように
                              // リクエスト処理全体を panic 捕捉で包む: 1件の new_protocol/crop が panic しても
                              // ワーカースレッドを殺さない(殺すと以後の全エンコードが止まり enc_inflight が恒久 latch)。
        let protocol = crate::preview::markdown::catch_silent(move || {
            let img = match req.crop {
                Some((x, y, w, h)) => req.image.crop_imm(x, y, w, h),
                None => (*req.image).clone(),
            };
            let size = ratatui::layout::Size::new(req.cols, req.rows);
            // フェンス図(ベクタ由来)は予約グリッドまで**拡大も**する(Scale): ラスタが小さくても
            // 左上詰めの余白バンドを作らず領域を満たす=シャープさは密度追従の再ラスタが担う。
            // 写真は従来どおり Fit(自然サイズ超に拡大しない=ぼやけさせない)。
            let resize =
                if crate::preview::markdown::is_mermaid_fence_url(&req.path.to_string_lossy()) {
                    Resize::Scale(Some(FilterType::Lanczos3))
                } else {
                    Resize::Fit(Some(FilterType::Lanczos3))
                };
            // 失敗(Err)でも必ず結果を送り返す: 握り潰すと enc_inflight が立ちっぱなしになる。
            picker.new_protocol(img, size, resize).ok()
        })
        .flatten();
        if tx
            .send(MdEncodeResult {
                path,
                key,
                protocol,
            })
            .is_err()
        {
            break;
        }
    }
}

/// Result of a background inline-image decode, delivered to the run loop.
pub struct MdImageResult {
    path: PathBuf,
    image: Result<image::DynamicImage, String>,
    /// SVG source alongside a rendered mermaid fence (kept for in-place sharp zoom). None otherwise.
    svg: Option<std::sync::Arc<Vec<u8>>>,
    /// True when this is a sharpening re-raster of an already-shown diagram: only the pixels are
    /// replaced — the layout size and the decoration cache stay untouched.
    reraster: bool,
}

/// Result of a background remote-image download (curl → local cache file), delivered to the run loop.
/// It carries no bytes: on success the file is already in the cache, so the run loop just invalidates
/// the decoration cache to re-lay the image out; on failure the URL is remembered so it is not retried.
pub struct RemoteFetch {
    url: String,
    ok: bool,
}

/// Result of `build_decorated`: the rendered lines plus everything needed to finish setting up the
/// Markdown cache (inline images, follow-up fetches/renders to kick off, source line count).
struct DecoratedMarkdown {
    lines: Vec<Line<'static>>,
    images: Vec<crate::preview::markdown::ImagePlacement>,
    remote_urls: Vec<String>,
    mermaid_fences: Vec<String>,
    math_exprs: Vec<(String, bool)>,
    src_lines: usize,
}

/// Per-tab state bundle. Migrated concern-by-concern out of the flat App fields so tab save/load
/// is one clone and adding a per-tab field touches one place (see docs/REFACTOR-2026-07.md).
/// `App.tabs` is `Vec<PerTab>` (one entry per tab, snapshot/restore on switch); the active tab's
/// working state is held in `App.tab` as the source of truth. Currently: Table preview cursor + scroll, the git-view overlay
/// (changes hub / log / graph / branches / commit detail) state, windowed-preview scroll/caret
/// internals (byte/line top, 2D cursor), image/PDF pan-and-page position, Markdown raw-mode/Tab-focus/
/// inline-fence zoom state, and the tab-scoped selection/filter/search state.
///
/// `Default` is implemented manually (not derived): a few fields have a non-zero "fresh tab" value
/// (`image_center`/`fence_center` start centered, `fence_zoom` starts at 1.0=fit, `pdf_page` starts
/// at 1), matching what `App::new` used to initialize them to before this migration.
#[derive(Clone)]
pub(crate) struct PerTab {
    // --- ツリー/root ナビゲーション状態 ---
    pub(crate) root: PathBuf,
    /// The directory opened at startup. The base for relative-path display (kept separately because root moves up with h).
    pub(crate) open_dir: PathBuf,
    /// The tree flattened into display order. For M0 it is fine to simply rebuild it every time.
    pub(crate) entries: Vec<Entry>,
    pub(crate) selected: usize,
    pub(crate) show_hidden: bool,
    /// Height (in rows) of the tree display area at the last render. Used as the page size for paging.
    pub(crate) tree_viewport: u16,
    pub(crate) mode: Mode,
    /// The target, kind, and scroll position (vertical/horizontal) while in Preview mode.
    /// Horizontal scroll is used to view long lines when not wrapping (ui.wrap=false).
    /// To avoid scrolling past the end, the actual clamp is done at render time (when content and screen size are known).
    pub(crate) preview_path: Option<PathBuf>,
    pub(crate) preview_kind: Option<PreviewKind>,
    pub(crate) preview_scroll: u16,
    pub(crate) preview_hscroll: u16,
    /// Height (in rows) of the text display area at the last render. Used as the page size for paging.
    pub(crate) preview_viewport: u16,
    table_cur_row: usize,
    table_cur_col: usize,
    table_top_row: usize,
    table_left_col: usize,
    // git オーバーレイもタブごとに保持する(別タブでドキュメントを見て戻っても git モードのまま)。
    git_view: bool,
    git_view_sel: usize,
    git_view_entries: Vec<crate::git::ChangeEntry>,
    came_from_git_view: bool,
    git_log: Option<Vec<crate::git::CommitInfo>>,
    git_log_sel: usize,
    git_detail: Option<Vec<crate::git::DiffLine>>,
    git_detail_meta: Option<crate::git::CommitMeta>,
    git_detail_title: Option<String>,
    git_detail_scroll: u16,
    git_detail_hscroll: u16,
    git_detail_viewport: u16,
    git_detail_total: usize,
    git_branches: Option<Vec<crate::git::BranchInfo>>,
    git_branch_sel: usize,
    git_branch_filter: String,
    git_branch_filtering: bool,
    git_graph: Option<Vec<crate::git::GraphRow>>,
    git_graph_sel: usize,
    // グラフ本体(git_graph)を保存する以上、それを装飾する派生状態(基準ピン・凡例・表示ブランチ・
    // 優先順)も同じタブに保存しないと、別タブで基準/表示を変えて戻ったとき凡例や `base:` タイトルが
    // 他タブのまま残る(load_active はグラフを再構築しない)。git_detail_meta/title を git_detail と
    // 一緒に保存するのと同じ扱い。ピッカー(モーダル)の一時状態は保存せず復元時にリセットする。
    git_graph_base: Option<String>,
    git_graph_base_label: Option<String>,
    git_graph_visible: std::collections::HashSet<String>,
    git_graph_legend: Vec<crate::git::LegendEntry>,
    git_graph_hidden: usize,
    git_graph_order: Vec<String>,
    // --- windowed(Code/Text/raw md)プレビューのスクロール内部状態 ---
    preview_byte_top: u64,
    preview_top_line: usize,
    // --- windowed プレビューの 2D キャレット位置(選択 anchor は持ち越さない) ---
    preview_cursor_line: usize,
    preview_cursor_col: usize,
    // --- 画像/PDF のパン・ページ位置 ---
    /// Zoom factor. 1.0=the whole image fits, >1.0 zooms in (overflowing the viewport clips and enables pan).
    pub(crate) image_zoom: f64,
    image_center: (f64, f64),
    pdf_page: u32,
    pdf_pages: Option<u32>,
    // --- Markdown/Mermaid raw ソース表示(`R`)・Tab フォーカス・インライン図のその場ズーム/全画面復帰 ---
    md_raw: bool,
    focused_item: Option<usize>,
    fence_zoom: f64,
    fence_center: (f64, f64),
    fence_return: Option<(u16, Option<usize>)>,
    // --- タブ毎の選択 / 絞り込み / プレビュー検索 ---
    selection: BTreeSet<PathBuf>,
    visual_anchor: Option<usize>,
    tree_filter: Option<String>,
    filter_input: Option<String>,
    filter_pool: Vec<Entry>,
    changed_filter: bool,
    preview_search: Option<String>,
    search_input: Option<String>,
    search_matches: Vec<(u64, usize, usize)>,
    search_idx: usize,
}

impl Default for PerTab {
    fn default() -> Self {
        Self {
            // root/open_dir has no meaningful default — App::new overrides both right after
            // `PerTab::default()`, and `rebuild_tree` fills `entries`.
            root: PathBuf::new(),
            open_dir: PathBuf::new(),
            entries: Vec::new(),
            selected: 0,
            show_hidden: false,
            tree_viewport: 0,
            // App::new starts in Tree, not whatever `Mode::default()` would be.
            mode: Mode::Tree,
            preview_path: None,
            preview_kind: None,
            preview_scroll: 0,
            preview_hscroll: 0,
            preview_viewport: 0,
            table_cur_row: 0,
            table_cur_col: 0,
            table_top_row: 0,
            table_left_col: 0,
            git_view: false,
            git_view_sel: 0,
            git_view_entries: Vec::new(),
            came_from_git_view: false,
            git_log: None,
            git_log_sel: 0,
            git_detail: None,
            git_detail_meta: None,
            git_detail_title: None,
            git_detail_scroll: 0,
            git_detail_hscroll: 0,
            git_detail_viewport: 0,
            git_detail_total: 0,
            git_branches: None,
            git_branch_sel: 0,
            git_branch_filter: String::new(),
            git_branch_filtering: false,
            git_graph: None,
            git_graph_sel: 0,
            git_graph_base: None,
            git_graph_base_label: None,
            git_graph_visible: std::collections::HashSet::new(),
            git_graph_legend: Vec::new(),
            git_graph_hidden: 0,
            git_graph_order: Vec::new(),
            preview_byte_top: 0,
            preview_top_line: 0,
            preview_cursor_line: 0,
            preview_cursor_col: 0,
            // App::new used to initialize image_zoom to 1.0 (whole image fits), not 0.0.
            image_zoom: 1.0,
            // 画像/フェンスの中心は「中央」が初期値(App::new が (0.5, 0.5) にしていたのと同じ)。
            image_center: (0.5, 0.5),
            // PDF ページは 1 始まり(App::new が 1 にしていたのと同じ)。
            pdf_page: 1,
            pdf_pages: None,
            md_raw: false,
            focused_item: None,
            // フェンスのその場ズームは 1.0=フィットが初期値(App::new が 1.0 にしていたのと同じ)。
            fence_zoom: 1.0,
            fence_center: (0.5, 0.5),
            fence_return: None,
            selection: BTreeSet::new(),
            visual_anchor: None,
            tree_filter: None,
            filter_input: None,
            filter_pool: Vec::new(),
            changed_filter: false,
            preview_search: None,
            search_input: None,
            search_matches: Vec::new(),
            search_idx: 0,
        }
    }
}

impl App {
    pub fn new(root: PathBuf, cfg: Config) -> Result<Self> {
        let path_style = PathStyle::parse(&cfg.ui.path_style);
        let key_scheme = KeyScheme::parse(&cfg.ui.keys);
        let lang = crate::i18n::Lang::resolve(&cfg.ui.lang);
        let sort = Sort::from_config(&cfg.ui.sort);
        // diff の並び初期値 (設定 git.diff)。実行時 `s` で 縦→横→Auto を巡回。
        let diff_layout = DiffLayout::parse(&cfg.git.diff);
        // Run2 キーマップ: 既定 + 設定 (`[keys.<surface>]` + 旧 copy_* alias) をマージし衝突を検証する。
        // page/half プロファイルは ui.keys (vim/less) に従う。Stage 2 は構築のみ (ディスパッチ未接続)。
        let keymaps = crate::keymap::KeyMap::from_config(
            crate::keymap::scheme_from_str(&cfg.ui.keys),
            &cfg.keys.to_keymap_config(),
        );
        let mut app = Self {
            launch_dir: root.clone(),
            path_style,
            key_scheme,
            lang,
            cfg,
            sort,
            sort_menu: false,
            bookmarks: crate::bookmarks::Bookmarks::load(&root),
            session_store: None,
            session_restoring: false,
            mark_set_pending: false,
            bookmark_list: false,
            bookmark_list_sel: 0,
            dialog: None,
            clipboard: None,
            follow_mode: false,
            follow_session: Vec::new(),
            diff_follow_scope: false,
            follow_diff_full: false,
            #[cfg(feature = "git")]
            follow_baseline: None,
            md_view_rows: 0,
            preview_win: None,
            preview_total_lines: None,
            win_cache: None,
            hl_pending: false,
            hl_warming: false,
            spinner_frame: 0,
            pending_edit: None,
            pending_git_tool: false,
            md_cache: None,
            diff_cache: None,
            gutter_cache: None,
            md_items: Vec::new(),
            details_open: std::collections::HashMap::new(),
            table_search_hits: std::collections::HashSet::new(),
            picker: None,
            img_tx: None,
            image: None,
            use_kitty: false,
            kitty_is_tmux: false,
            kitty_image: None,
            kitty_tx: None,
            kitty_gen: 0,
            kitty_want: None,
            kitty_shown: None,
            image_src: None,
            image_crop: None,
            image_vis_frac: (1.0, 1.0),
            vector_svg: None,
            image_logical: None,
            vector_reraster_inflight: false,
            md_overlay_last: None,
            md_overlay_seen: None,
            md_overlay_moved: false,
            preview_media_mtime: None,
            media_cache: None,
            table_data: None,
            tab: PerTab {
                root: root.clone(),
                open_dir: root.clone(),
                ..PerTab::default()
            },
            table_viewport_rows: 0,
            preview_visual_anchor: None,
            preview_visual_linewise: false,
            gif_frames: Vec::new(),
            gif_idx: 0,
            gif_shown_at: None,
            gif_protocol: None,
            gif_proto_key: None,
            media_tx: None,
            md_image_cache: std::collections::HashMap::new(),
            detail_cells_cache: std::collections::HashMap::new(),
            md_img_tx: None,
            md_remote_inflight: std::collections::HashSet::new(),
            md_remote_failed: std::collections::HashSet::new(),
            md_remote_tx: None,
            md_enc_tx: None,
            media_gen: 0,
            media_loading: false,
            keymaps,
            pending_leader: None,
            flash: None,
            show_help: false,
            show_info: false,
            help_scroll: 0,
            tabs: Vec::new(),
            active_tab: 0,
            tab_list: false,
            tab_list_sel: 0,
            outline_open: false,
            outline_sel: 0,
            git_status: std::collections::HashMap::new(),
            git_ignored: std::collections::HashSet::new(),
            git_status_for: None,
            git_status_workdir: None,
            git_status_dirty: false,
            git_status_pending: None,
            git_status_gen: 0,
            status_tx: None,
            git_ignored_for: None,
            git_ignored_pending: None,
            git_ignored_gen: 0,
            git_ignored_dirty: false,
            ignored_tx: None,
            diff_layout,
            git_branch: None,
            git_graph_picker: false,
            git_graph_picker_sel: 0,
            git_graph_picker_set: std::collections::HashSet::new(),
            git_graph_reordered: false,
        };
        app.rebuild_tree()?;
        // 最初のタブとして現在の状態を登録する。
        app.tabs.push(app.snapshot_tab());
        Ok(app)
    }

    /// Attach the per-project session store (`[ui] restore_tabs`). Called by main only, like the
    /// loader senders — tests that need persistence attach a temp-based store explicitly, so plain
    /// `App::new` (unit/e2e tests) never touches the real `~/.config`.
    pub fn attach_session_store(&mut self, store: crate::session::SessionStore) {
        self.session_store = Some(store);
    }

    /// Summarize startup keymap conflicts / ignored settings into one line (for the startup flash; i18n).
    /// Conflicts have already safely fallen back to defaults (#17/FR-8). None if there is nothing.
    pub fn keymap_report(&self) -> Option<String> {
        let nc = self.keymaps.conflicts.len();
        let nw = self.keymaps.warnings.len();
        if nc == 0 && nw == 0 {
            return None;
        }
        let mut parts: Vec<String> = Vec::new();
        if nc > 0 {
            parts.push(match self.lang {
                crate::i18n::Lang::Jp => format!("キー衝突{nc}件(既定で継続)"),
                crate::i18n::Lang::En => format!("{nc} key conflict(s) (using defaults)"),
            });
        }
        if nw > 0 {
            parts.push(match self.lang {
                crate::i18n::Lang::Jp => format!("無効な設定{nw}件を無視"),
                crate::i18n::Lang::En => format!("{nw} invalid key setting(s) ignored"),
            });
        }
        let head = tr(self.lang, crate::i18n::Msg::Keymap);
        Some(format!("{head}: {}", parts.join(" / ")))
    }

    /// Starting from directly under root, recursively expand the expanded directories and flatten them.
    /// A naive implementation for M0. Support for large directories will later be replaced with lazy loading.
    pub fn rebuild_tree(&mut self) -> Result<()> {
        let mut out = Vec::new();
        // HashSet: build_dir checks membership once per child (a Vec scan is E×N comparisons).
        let expanded_dirs: std::collections::HashSet<PathBuf> = self
            .tab
            .entries
            .iter()
            .filter(|e| e.is_dir && e.expanded)
            .map(|e| e.path.clone())
            .collect();

        build_dir(
            &self.tab.root,
            0,
            &expanded_dirs,
            self.tab.show_hidden,
            self.sort,
            &mut out,
        )?;
        self.tab.entries = out;
        if self.tab.selected >= self.tab.entries.len() {
            self.tab.selected = self.tab.entries.len().saturating_sub(1);
        }
        // entries を作り直したら visual_anchor(entries 添字)は stale。必ず無効化する。
        self.tab.visual_anchor = None;
        // 詳細セルのキャッシュも世代交代(fs が変わった可能性がある節目=ここで必ず破棄)。
        self.detail_cells_cache.clear();
        Ok(())
    }

    /// Fill the detail-column cell cache for the given visible rows (tree render pre-pass).
    /// A path already cached is skipped; the whole cache is dropped by `rebuild_tree` (the choke
    /// point every fs change goes through), so cells are computed once per tree generation.
    pub fn ensure_detail_cells(&mut self, rows: &[(PathBuf, bool)], cols: &[String]) {
        for (path, is_dir) in rows {
            if self.detail_cells_cache.contains_key(path) {
                continue;
            }
            let meta = crate::fileops::quick_meta(path).unwrap_or(crate::fileops::RowMeta {
                is_dir: *is_dir,
                is_symlink: false,
                size: 0,
                mtime: None,
                mode: 0,
            });
            let cells: Vec<String> = cols
                .iter()
                .map(|id| crate::fileops::detail_cell(id, path, &meta).unwrap_or_default())
                .collect();
            self.detail_cells_cache.insert(path.clone(), cells);
        }
    }

    /// Cached detail cells for one row (filled by `ensure_detail_cells`).
    pub fn detail_cells_get(&self, path: &Path) -> Option<&Vec<String>> {
        self.detail_cells_cache.get(path)
    }

    /// Calls `rebuild_tree`, and on failure does not swallow it but reports via flash. Returns `true` on success.
    /// Used on paths that cannot bail out with `?` (bookmark jump, clearing the filter, rebuilding after a git discard).
    /// The return value lets the caller decide whether to show a subsequent success flash (=false means don't).
    fn rebuild_tree_notify(&mut self) -> bool {
        if let Err(e) = self.rebuild_tree() {
            self.flash = Some(format!(
                "{}{e}",
                crate::i18n::tr(self.lang, crate::i18n::Msg::OperationFailed)
            ));
            false
        } else {
            true
        }
    }

    // --- ソート (FR・M7 補助) -------------------------------------------------
    /// Whether the `s` sort-selection menu is showing.
    pub fn is_sort_menu(&self) -> bool {
        self.sort_menu
    }
    /// Open the sort menu with `s`. main routes the next key here.
    pub fn open_sort_menu(&mut self) {
        self.sort_menu = true;
    }
    /// Close the sort menu (Esc or an out-of-scope key).
    pub fn close_sort_menu(&mut self) {
        self.sort_menu = false;
    }
    /// Key handling for the sort menu. n/s/m/e=select the key (closes after selecting), r=flip asc/desc, .=directories first
    /// (toggles keep it open). Out-of-scope keys close it. If the order changes, rebuild (while filtering, applied after clearing).
    pub fn sort_menu_key(&mut self, c: char) -> Result<()> {
        let keep_open = match c {
            'n' => {
                self.sort.key = SortKey::Name;
                false
            }
            's' => {
                self.sort.key = SortKey::Size;
                false
            }
            'm' => {
                self.sort.key = SortKey::Modified;
                false
            }
            'e' => {
                self.sort.key = SortKey::Ext;
                false
            }
            'r' => {
                self.sort.reverse = !self.sort.reverse;
                true
            }
            '.' => {
                self.sort.dirs_first = !self.sort.dirs_first;
                true
            }
            _ => {
                self.sort_menu = false;
                return Ok(());
            }
        };
        // 絞り込み中は結果順を変えない(クリア後にツリー再構築で反映)。
        if self.tab.tree_filter.is_none() {
            self.rebuild_tree()?;
        }
        self.sort_menu = keep_open;
        Ok(())
    }
    /// Current sort display for the top context bar (e.g. `sort: mod ↑`).
    pub fn sort_label(&self) -> String {
        let k = match self.sort.key {
            SortKey::Name => "name",
            SortKey::Size => "size",
            SortKey::Modified => "mod",
            SortKey::Ext => "ext",
        };
        let arrow = if self.sort.reverse { "↓" } else { "↑" };
        format!("sort: {k} {arrow}")
    }

    // --- モード表示 (2軸: 表示モード × 内部モード) ----------------------------
    /// Display mode (for the outer chip). Preview becomes Image if it is an image.
    pub fn display_mode(&self) -> DisplayMode {
        match self.tab.mode {
            Mode::Tree => DisplayMode::Tree,
            Mode::Preview => {
                if self.is_image_preview() {
                    DisplayMode::Image
                } else if self.is_table_preview() {
                    DisplayMode::Table
                } else {
                    DisplayMode::Preview
                }
            }
        }
    }
    /// Internal mode (for the inner chip and footer switching). None if nothing is being operated.
    /// Priority: dialog > filter/search/sort/mark/bookmarks > visual.
    pub fn internal_mode(&self) -> Option<InternalMode> {
        if let Some(d) = &self.dialog {
            return Some(match &d.kind {
                // アプリ終了確認は非破壊。削除/ドロップとは別チップ/フッターにする。
                DialogKind::Confirm { .. } if self.confirm_is_quit() => InternalMode::QuitConfirm,
                // ブックマーク上書き確認も非破壊=別チップ/フッター。
                DialogKind::Confirm { .. } if self.confirm_is_bookmark() => {
                    InternalMode::BookmarkConfirm
                }
                // D&D 転送は破壊的でないので削除確認とは別チップ/フッターにする。
                DialogKind::Confirm { .. } if self.confirm_is_drop() => InternalMode::DropConfirm,
                DialogKind::Confirm { .. } => InternalMode::DeleteConfirm,
                DialogKind::Preview { .. } => InternalMode::RenamePreview,
                DialogKind::Input { .. } => match &d.op {
                    PendingOp::Create { .. } => InternalMode::Create,
                    PendingOp::BatchRenameInput { .. } => InternalMode::BatchRename,
                    PendingOp::GitCommit => InternalMode::Commit,
                    PendingOp::GitCreateBranch => InternalMode::GitBranch,
                    _ => InternalMode::Rename,
                },
            });
        }
        // コミット詳細は log の上に被さるので先に判定する。
        if self.is_git_detail() {
            return Some(InternalMode::GitDetail);
        }
        if self.is_git_log() {
            return Some(InternalMode::GitLog);
        }
        // パネルはグラフの上に被さる(is_git_graph も true なので先に判定)。
        if self.is_git_graph_picker() {
            return Some(InternalMode::GitGraphPicker);
        }
        if self.is_git_graph() {
            return Some(InternalMode::GitGraph);
        }
        if self.is_git_branches() {
            return Some(InternalMode::GitBranch);
        }
        if self.is_git_view() {
            return Some(InternalMode::GitChanges);
        }
        if self.is_git_diff_preview() {
            return Some(InternalMode::GitDiff);
        }
        if self.is_filtering() {
            return Some(InternalMode::Filter);
        }
        if self.is_searching() {
            return Some(InternalMode::Search);
        }
        if self.is_sort_menu() {
            return Some(InternalMode::Sort);
        }
        if self.is_marking() {
            return Some(InternalMode::Mark);
        }
        if self.is_bookmark_list() {
            return Some(InternalMode::Bookmarks);
        }
        if self.is_tab_list() {
            return Some(InternalMode::Tabs);
        }
        if self.is_outline() {
            return Some(InternalMode::Outline);
        }
        if self.is_info() {
            return Some(InternalMode::Info);
        }
        if self.is_visual() {
            return Some(InternalMode::Visual);
        }
        if self.is_preview_visual() {
            return Some(InternalMode::PreviewVisual);
        }
        if self.tab.changed_filter && matches!(self.tab.mode, Mode::Tree) {
            return Some(InternalMode::ChangedFilter);
        }
        None
    }

    /// The **frontmost surface** that currently receives keys (the single source of truth for Run2 keymap dispatch).
    /// Strictly follows the same priority as internal_mode, while also including the base full screens (Tree/Preview) and overlays (§4).
    /// Off the render path; references only existing bool predicates (same cost as now).
    pub fn surface(&self) -> crate::keymap::Surface {
        use crate::keymap::Surface as S;
        // ダイアログ最優先 (種別で細分: 入力 / 削除確認 / ドロップ確認 / リネームプレビュー)。
        if self.is_dialog() {
            if self.dialog_is_preview() {
                return S::DialogRenamePreview;
            }
            if self.dialog_is_confirm() {
                if self.confirm_is_quit() {
                    return S::DialogConfirmQuit;
                }
                if self.confirm_is_bookmark() {
                    return S::DialogConfirmBookmark;
                }
                if self.confirm_is_drop() {
                    return S::DialogConfirmDrop;
                }
                return S::DialogConfirmDelete;
            }
            return S::DialogInput;
        }
        // ヘルプ (全要素の上)。
        if self.show_help {
            return S::Help;
        }
        // Git オーバーレイ (詳細 > log > graph > branches > 変更ハブ > diff)。feature 無効時は到達しない。
        #[cfg(feature = "git")]
        {
            if self.is_git_detail() {
                return S::GitDetail;
            }
            if self.is_git_log() {
                return S::GitLog;
            }
            // パネルはグラフの上に被さる(is_git_graph も true なので先に判定)。
            if self.is_git_graph_picker() {
                return S::GitGraphPicker;
            }
            if self.is_git_graph() {
                return S::GitGraph;
            }
            if self.is_git_branches() {
                return if self.git_branch_filtering() {
                    S::BranchFilter
                } else {
                    S::GitBranches
                };
            }
            if self.is_git_view() {
                return S::GitChanges;
            }
            if self.is_git_diff_preview() {
                return S::PreviewGitDiff;
            }
        }
        // 入力系 / メニュー / 一覧 / 情報 / ビジュアル。
        if self.is_filtering() {
            return S::Filter;
        }
        if self.is_searching() {
            return S::Search;
        }
        if self.is_sort_menu() {
            return S::Sort;
        }
        if self.is_marking() {
            return S::Mark;
        }
        if self.is_bookmark_list() {
            return S::Bookmarks;
        }
        if self.is_tab_list() {
            return S::Tabs;
        }
        if self.is_outline() {
            return S::Outline;
        }
        if self.is_info() {
            return S::Info;
        }
        if self.is_visual() {
            return S::Visual;
        }
        // 基本全画面 (Preview は画像/テキストで分岐)。
        match self.tab.mode {
            Mode::Preview => {
                if self.is_image_preview() {
                    S::PreviewImage
                } else if self.is_table_preview() {
                    S::PreviewTable
                } else if self.is_preview_visual() {
                    S::PreviewTextVisual
                } else {
                    S::PreviewText
                }
            }
            Mode::Tree => S::Tree,
        }
    }

    // --- コピー/カット&ペースト (M7 Phase B・既定キー Y/X/P・keymap で変更可) ---
    /// Label for the context display: "copy 3" / "cut 3". None if the clipboard is empty.
    pub fn clipboard_label(&self) -> Option<String> {
        self.clipboard.as_ref().map(|c| {
            let verb = match c.op {
                ClipOp::Copy => crate::i18n::tr(self.lang, crate::i18n::Msg::CopyHint),
                ClipOp::Cut => crate::i18n::tr(self.lang, crate::i18n::Msg::CutHint),
            };
            format!("{verb} {}", c.paths.len())
        })
    }
    /// `Y`=copy: push the selection (or the cursor if none) to the clipboard (for duplication). The selection is cleared.
    pub fn copy_selection(&mut self) {
        let targets = self.op_targets();
        if targets.is_empty() {
            self.flash = Some(crate::i18n::tr(self.lang, crate::i18n::Msg::NoTarget).into());
            return;
        }
        let n = targets.len();
        self.clipboard = Some(Clipboard {
            op: ClipOp::Copy,
            paths: targets,
        });
        self.clear_selection();
        self.flash = Some(format!(
            "{} ({n})",
            crate::i18n::tr(self.lang, crate::i18n::Msg::Copied)
        ));
    }
    /// `X`=cut: push the selection (or the cursor if none) to the clipboard (for moving). The selection is cleared.
    pub fn cut_selection(&mut self) {
        let targets = self.op_targets();
        if targets.is_empty() {
            self.flash = Some(crate::i18n::tr(self.lang, crate::i18n::Msg::NoTarget).into());
            return;
        }
        let n = targets.len();
        self.clipboard = Some(Clipboard {
            op: ClipOp::Cut,
            paths: targets,
        });
        self.clear_selection();
        self.flash = Some(format!(
            "{} ({n})",
            crate::i18n::tr(self.lang, crate::i18n::Msg::CutDone)
        ));
    }
    /// `P`=paste: apply to the cursor-based directory. Copy duplicates, cut moves (consumed). **Never overwrites.**
    pub fn paste(&mut self) -> Result<()> {
        let Some(clip) = self.clipboard.clone() else {
            self.flash = Some(crate::i18n::tr(self.lang, crate::i18n::Msg::ClipboardEmpty).into());
            return Ok(());
        };
        let dir = self.op_base_dir();
        let (mut ok, mut last, mut err) = (0usize, None, None);
        for src in &clip.paths {
            // 自分自身(やその中)への貼り付けは無限コピーになるので弾く。
            if dir.starts_with(src) {
                err = Some(
                    crate::i18n::tr(self.lang, crate::i18n::Msg::CannotPasteIntoSelf).to_string(),
                );
                continue;
            }
            let res = match clip.op {
                ClipOp::Copy => crate::fileops::copy_into(&dir, src),
                ClipOp::Cut => crate::fileops::move_into(&dir, src),
            };
            match res {
                Ok(p) => {
                    ok += 1;
                    last = Some(p);
                }
                Err(e) => err = Some(e.to_string()),
            }
        }
        if matches!(clip.op, ClipOp::Cut) {
            self.clipboard = None; // カットは消費(元が移動済み)
        }
        self.refresh()?;
        if let Some(p) = &last {
            self.reveal_and_select(p)?;
        }
        self.flash = Some(match err {
            Some(e) => format!(
                "{} {ok} / {}: {e}",
                crate::i18n::tr(self.lang, crate::i18n::Msg::Pasted),
                crate::i18n::tr(self.lang, crate::i18n::Msg::Failed),
            ),
            None => format!(
                "{} ({ok})",
                crate::i18n::tr(self.lang, crate::i18n::Msg::Pasted)
            ),
        });
        Ok(())
    }

    /// `Space→D`=duplicate: copy each target **in place** (into its own parent directory) with a
    /// collision-free name (`note copy.md`, then `note copy 2.md`). Operates on the selection, or the
    /// cursor entry when none. Directories are duplicated recursively (as a sibling `dir copy`), and
    /// symlinks are copied as links — both via `copy_into`. Never overwrites. The last new item is
    /// revealed and selected so the result is visible.
    pub fn duplicate_selection(&mut self) -> Result<()> {
        let targets = self.op_targets();
        if targets.is_empty() {
            self.flash = Some(crate::i18n::tr(self.lang, crate::i18n::Msg::NoTarget).into());
            return Ok(());
        }
        let (mut ok, mut last, mut err) = (0usize, None, None);
        for src in &targets {
            // 親ディレクトリ = 複製先(その場に複製)。ルート等で親が無ければ失敗扱い(クラッシュしない)。
            let Some(dir) = src.parent() else {
                err =
                    Some(crate::i18n::tr(self.lang, crate::i18n::Msg::OperationFailed).to_string());
                continue;
            };
            match crate::fileops::copy_into(dir, src) {
                Ok(p) => {
                    ok += 1;
                    last = Some(p);
                }
                Err(e) => err = Some(e.to_string()),
            }
        }
        self.clear_selection();
        self.refresh()?;
        if let Some(p) = &last {
            self.reveal_and_select(p)?;
        }
        self.flash = Some(match err {
            Some(e) => format!(
                "{} {ok} / {}: {e}",
                crate::i18n::tr(self.lang, crate::i18n::Msg::Duplicated),
                crate::i18n::tr(self.lang, crate::i18n::Msg::Failed)
            ),
            None => format!(
                "{} ({ok})",
                crate::i18n::tr(self.lang, crate::i18n::Msg::Duplicated)
            ),
        });
        Ok(())
    }

    /// The selection listed in the **current sort order (tree display order)**. Used as the numbering order for sequential rename.
    /// Selections not present in entries (collapsed, etc.) are appended at the end in path order.
    fn selection_in_display_order(&self) -> Vec<PathBuf> {
        let mut v: Vec<PathBuf> = self
            .tab
            .entries
            .iter()
            .filter(|e| self.tab.selection.contains(&e.path))
            .map(|e| e.path.clone())
            .collect();
        for p in &self.tab.selection {
            if !v.contains(p) {
                v.push(p.clone());
            }
        }
        v
    }
    /// Heading for the batch-rename input dialog (the count + a placeholder legend).
    fn batch_rename_title(&self, count: usize) -> String {
        format!(
            "{} {} {}  {{n}} {{n:0W}} {{name}} {{ext}}",
            crate::i18n::tr(self.lang, crate::i18n::Msg::BatchRename),
            count,
            crate::i18n::tr(self.lang, crate::i18n::Msg::Items),
        )
    }
    /// `R` (with a selection)=batch rename. Opens template input that numbers the selection sequentially in display order.
    pub fn start_batch_rename(&mut self) {
        let targets = self.selection_in_display_order();
        if targets.is_empty() {
            self.flash = Some(crate::i18n::tr(self.lang, crate::i18n::Msg::NoTarget).into());
            return;
        }
        let title = self.batch_rename_title(targets.len());
        self.dialog = Some(Dialog {
            op: PendingOp::BatchRenameInput { targets },
            kind: DialogKind::Input {
                title,
                buffer: String::new(),
                cursor: 0,
            },
        });
    }

    /// `a`=create. Opens an input dialog to create with the entered name in the cursor-based directory (a trailing `/` makes a folder).
    pub fn start_create(&mut self) {
        let dir = self.op_base_dir();
        let where_ = self.format_path(&dir);
        self.dialog = Some(Dialog {
            op: PendingOp::Create { dir },
            kind: DialogKind::Input {
                title: format!(
                    "{} in {where_}  ({})",
                    crate::i18n::tr(self.lang, crate::i18n::Msg::Create),
                    crate::i18n::tr(self.lang, crate::i18n::Msg::TrailingSlashFolder),
                ),
                buffer: String::new(),
                cursor: 0,
            },
        });
    }

    /// `R`=rename. An input dialog to change the cursor's file/directory name (prefilled with the current name).
    pub fn start_rename(&mut self) {
        let Some(target) = self
            .tab
            .entries
            .get(self.tab.selected)
            .map(|e| e.path.clone())
        else {
            self.flash = Some(crate::i18n::tr(self.lang, crate::i18n::Msg::NoTarget).into());
            return;
        };
        let name = target
            .file_name()
            .and_then(|n| n.to_str())
            .unwrap_or("")
            .to_string();
        let cursor = name.chars().count(); // 末尾にカーソルを置く。
        self.dialog = Some(Dialog {
            op: PendingOp::Rename { target },
            kind: DialogKind::Input {
                title: crate::i18n::tr(self.lang, crate::i18n::Msg::Rename).into(),
                buffer: name,
                cursor,
            },
        });
    }

    /// `D`=delete (with confirmation). Opens a confirmation dialog targeting **all selected items if there is a selection**, or the cursor item otherwise.
    /// `y`=send to trash (recoverable) / `!`=permanent delete (unrecoverable) / `n`,Esc=cancel.
    pub fn start_delete(&mut self) {
        let targets = self.op_targets();
        if targets.is_empty() {
            self.flash = Some(crate::i18n::tr(self.lang, crate::i18n::Msg::NoTarget).into());
            return;
        }
        // メッセージ: 1件は名前、複数件は「N 件 (先頭名 他)」。
        let label = if targets.len() == 1 {
            targets[0]
                .file_name()
                .and_then(|n| n.to_str())
                .unwrap_or("?")
                .to_string()
        } else {
            let first = targets[0]
                .file_name()
                .and_then(|n| n.to_str())
                .unwrap_or("?");
            format!(
                "{} {} ({first} {})",
                targets.len(),
                crate::i18n::tr(self.lang, crate::i18n::Msg::Items),
                crate::i18n::tr(self.lang, crate::i18n::Msg::Etc),
            )
        };
        self.dialog = Some(Dialog {
            op: PendingOp::Delete { targets },
            kind: DialogKind::Confirm {
                message: format!(
                    "{}: {label}",
                    crate::i18n::tr(self.lang, crate::i18n::Msg::DeleteTarget),
                ),
                allow_permanent: true,
            },
        });
    }

    pub fn tree_next(&mut self) {
        if self.tab.selected + 1 < self.tab.entries.len() {
            self.tab.selected += 1;
        }
    }

    pub fn tree_prev(&mut self) {
        self.tab.selected = self.tab.selected.saturating_sub(1);
    }

    /// To the top of the tree.
    pub fn tree_first(&mut self) {
        self.tab.selected = 0;
    }

    /// To the bottom of the tree.
    pub fn tree_last(&mut self) {
        self.tab.selected = self.tab.entries.len().saturating_sub(1);
    }

    /// Page the tree by one (dir: +1=next / -1=previous). Overlaps one row to keep context.
    pub fn tree_page(&mut self, dir: i32) {
        let page = self.tab.tree_viewport.saturating_sub(1).max(1) as i32;
        self.tree_move(dir * page);
    }

    /// Half-page the tree (vim: Ctrl-d/Ctrl-u, less: d/u).
    pub fn tree_half_page(&mut self, dir: i32) {
        let half = (self.tab.tree_viewport / 2).max(1) as i32;
        self.tree_move(dir * half);
    }

    /// Move the selection by delta rows and clamp it to [0, end].
    fn tree_move(&mut self, delta: i32) {
        self.tab.selected = clamp_cursor(self.tab.selected, delta, self.tab.entries.len());
    }

    /// If a directory, toggle expansion; if a file, transition to Preview.
    /// While filtering (a flat result list), expand-toggle is meaningless, so behave the same as `tree_descend`.
    pub fn tree_activate(&mut self) -> Result<()> {
        if self.tab.tree_filter.is_some() || self.tab.changed_filter {
            return self.tree_descend();
        }
        let Some(entry) = self.tab.entries.get(self.tab.selected).cloned() else {
            return Ok(());
        };
        if entry.is_dir {
            // expanded をトグルして再構築
            if let Some(e) = self.tab.entries.get_mut(self.tab.selected) {
                e.expanded = !e.expanded;
            }
            self.rebuild_tree()?;
        } else {
            self.enter_preview(&entry.path);
        }
        Ok(())
    }

    /// Before switching root, discard state that points to items of the old root.
    /// `selection` is held by path, so under a different root it stays invisible yet becomes a target for mis-operations (a footgun), and
    /// `visual_anchor` is an entries index, so it goes stale under a different root. The filter and preview search are also
    /// for the old root, so they are cleared together (rebuild_tree also invalidates visual_anchor, but we do it explicitly).
    fn clear_for_root_change(&mut self) {
        self.tab.selection.clear();
        self.tab.visual_anchor = None;
        self.clear_filter_state();
        self.search_clear();
    }

    /// Move to the parent directory (raise the root). For `h`. While filtering, first clear the filter (the normal tree of the current root).
    pub fn tree_leave(&mut self) -> Result<()> {
        if self.tab.tree_filter.is_some() {
            self.filter_clear();
            return Ok(());
        }
        if self.tab.changed_filter {
            self.toggle_changed_filter(); // OFF に戻す(通常ツリーへ)
            return Ok(());
        }
        if let Some(parent) = self.tab.root.parent().map(Path::to_path_buf) {
            self.clear_for_root_change();
            self.tab.root = parent;
            self.tab.entries.clear();
            self.tab.selected = 0;
            self.rebuild_tree()?;
        }
        Ok(())
    }

    /// Descend into the selected directory (make that directory the new root). For `l`.
    /// Symmetric to `h` (to the parent). If a file, transition to Preview.
    /// Works on filter results too: directory → move there and clear the filter / file → preview.
    pub fn tree_descend(&mut self) -> Result<()> {
        let Some(entry) = self.tab.entries.get(self.tab.selected).cloned() else {
            return Ok(());
        };
        let was_filtering = self.tab.tree_filter.is_some();
        if entry.is_dir {
            // root を変えるので旧 root の選択/ビジュアル/絞り込み/検索を破棄する(持ち越さない)。
            self.clear_for_root_change();
            self.tab.root = entry.path;
            self.tab.entries.clear();
            self.tab.selected = 0;
            self.rebuild_tree()?;
        } else {
            // ファイルは絞り込みを保ったままプレビュー(戻ると結果一覧に復帰)。
            let _ = was_filtering;
            self.enter_preview(&entry.path);
        }
        Ok(())
    }

    pub fn toggle_hidden(&mut self) -> Result<()> {
        self.tab.show_hidden = !self.tab.show_hidden;
        self.rebuild_tree()
    }

    /// The diff lines for a GitDiff preview of `path`. `follow` = this is a follow-opened diff, so
    /// (unless toggled to full) show the diff since follow-start; otherwise the full git diff. The
    /// single decision point shared by `follow_jump` (initial open) and `git_diff_lines` (recompute
    /// on scroll/FS-refresh/`n`/`N`), so every path stays consistent.
    pub(super) fn compute_gitdiff_lines(
        &self,
        path: &Path,
        follow: bool,
    ) -> Vec<crate::git::DiffLine> {
        #[cfg(feature = "git")]
        if follow && !self.follow_diff_full {
            if let Some(lines) = self.follow_baseline_diff(path) {
                return lines;
            }
        }
        let _ = follow;
        crate::git::file_diff(&self.tab.root, path)
    }

    fn enter_preview(&mut self, path: &Path) {
        // 同一ファイルへの再入(全画面フェンスからの `q` 復帰)か。この場合はインライン画像
        // キャッシュを温存する: キーはフェンス=内容ハッシュ/画像=パスなので stale にならず、
        // 捨てると全フェンスが Loading からやり直し=縮退レイアウトの 1 描画で復元スクロール/
        // フォーカスがクランプされ「元の位置に戻る」約束が破れていた。
        let same_file = self.tab.preview_path.as_deref() == Some(path);
        self.tab.preview_path = Some(path.to_path_buf());
        // 設定駆動でプレビュー種別を解決。未対応は CanNotPreview。
        let kind = self.cfg.resolve_preview(path);
        self.tab.preview_scroll = 0;
        self.tab.preview_hscroll = 0;
        self.tab.preview_byte_top = 0;
        self.tab.preview_top_line = 0;
        // 画像状態は毎回リセット。SVG/GIF は別スレッドで読み込み開始(UI を塞がない)。
        self.clear_image();
        // PDF はページ数を先に求める(pdfinfo・~数 ms)。None なら単ページ扱い=ページ移動なし。
        if matches!(kind, PreviewKind::Pdf(_)) {
            self.tab.pdf_pages = crate::preview::pdf::page_count(path);
        }
        self.start_media_load(&kind, path);
        self.tab.preview_kind = Some(kind);
        self.tab.fence_return = None; // 通常のプレビュー遷移でフェンス復帰情報は用済み
        self.tab.fence_zoom = 1.0;
        self.tab.fence_center = (0.5, 0.5);
        self.tab.md_raw = false; // 新規ファイルは装飾表示から(Markdown/Mermaid)。`R` で raw へ。
        self.md_cache = None; // 別ファイルに切替: 装飾キャッシュを無効化
        self.md_items.clear();
        if !same_file {
            self.md_image_cache.clear(); // 別ファイル: インライン画像キャッシュも破棄
        }
        self.tab.focused_item = None;
        self.outline_open = false; // 新規プレビューでアウトラインオーバーレイは閉じる
        self.details_open.clear(); // <details> の開閉状態は文書ごと=別ファイルでリセット
        self.tab.preview_search = None;
        self.tab.search_input = None;
        self.tab.search_matches.clear();
        self.table_search_hits.clear();
        self.tab.search_idx = 0;
        self.setup_windowed(); // 大きい Code/Text なら less 風ウィンドウ読みに切替
                               // windowed プレビューの 2D キャレット/選択を先頭へリセット。
        self.tab.preview_cursor_line = 0;
        self.tab.preview_cursor_col = 0;
        self.preview_visual_anchor = None;
        self.preview_visual_linewise = false;
        // CSV/TSV はテーブルへパース。カーソル/スクロールを先頭へ戻してから読み込む。
        self.tab.table_cur_row = 0;
        self.tab.table_cur_col = 0;
        self.tab.table_top_row = 0;
        self.tab.table_left_col = 0;
        self.load_table();
        self.tab.mode = Mode::Preview;
    }

    /// Code/Text previews use less-style windowed reading **regardless of size**.
    /// This avoids whole-file highlighting (1.3s/debug for 1600 lines) and reads/colors only the visible window (tens of lines), so
    /// opening is instant even for small files and behavior is symmetric with huge files. Images/md/mermaid are excluded
    /// (md/mermaid need their whole structure understood and are usually small).
    fn setup_windowed(&mut self) {
        self.preview_win = None;
        self.win_cache = None;
        self.preview_total_lines = None;
        // 重いハイライト待ち状態を判定: Code かつ ハイライト有効 かつ 文法が未コンパイル(cold)なら
        // 初回だけローディング表示/段階表示が要る。温まっていれば最初から即時着色。
        self.hl_pending = self.cfg.ui.syntax_highlight
            && matches!(self.tab.preview_kind, Some(PreviewKind::Code(_)))
            && !crate::preview::code::is_ext_warm(self.current_preview_ext());
        self.hl_warming = false;
        // Code/Text は常に windowed。Markdown/Mermaid は raw 表示(`R`)のときだけ windowed 化＝
        // 素のソースを行/桁一致で読み、2D キャレット選択をそのまま乗せる。
        let windowed_kind = matches!(
            self.tab.preview_kind,
            Some(PreviewKind::Code(_)) | Some(PreviewKind::Text(_))
        ) || self.is_raw_source();
        if !windowed_kind {
            return;
        }
        let Some(path) = self.tab.preview_path.clone() else {
            return;
        };
        if let Ok(w) = crate::preview::window::FileWindow::open(&path) {
            self.preview_win = Some(w);
        }
    }

    /// Extension of the current preview target file (empty string if none). Used for the highlight-warm check, etc.
    pub fn current_preview_ext(&self) -> &str {
        self.tab
            .preview_path
            .as_deref()
            .and_then(|p| p.extension())
            .and_then(|e| e.to_str())
            .unwrap_or("")
    }

    /// Whether waiting on heavy code highlighting (whether the render shows a loading/progressive display).
    pub fn is_highlight_pending(&self) -> bool {
        self.hl_pending
    }

    /// Whether the loading display is the "central spinner" style (false=progressive=immediate plain text).
    pub fn loading_is_indicator(&self) -> bool {
        self.cfg.ui.preview_loading != "progressive"
    }

    /// Clear the loading state on warm completion (swap in the colored version). Common to indicator/progressive.
    pub fn clear_highlight_pending(&mut self) {
        self.hl_pending = false;
        self.hl_warming = false;
    }

    /// If the background warm has not started yet, return the launch target (the caller runs `code::warm_file` on a separate thread).
    /// Both indicator and progressive **compile on a background thread** so the UI is not stalled (the spinner keeps spinning).
    /// Launch only when the return value is Some((ext, path)) (= prevents double-launch).
    pub fn take_warm_job(&mut self) -> Option<(String, PathBuf)> {
        if self.hl_pending && !self.hl_warming {
            if let Some(path) = self.tab.preview_path.clone() {
                self.hl_warming = true;
                return Some((self.current_preview_ext().to_string(), path));
            }
        }
        None
    }

    /// Background jobs currently in flight, as i18n labels (drives the top-right busy indicator).
    /// **Derived** from the existing per-job state (no separate begin/end pairing that could leak
    /// a stuck spinner): git-ignored scan / media decode / syntax-highlight warm-up / inline images.
    pub fn busy_jobs(&self) -> Vec<crate::i18n::Msg> {
        let mut v = Vec::new();
        // 無視セットと status はどちらも「git のスキャン中」= 同じラベルで表す(片方でも走っていれば出す)。
        if self.git_ignored_pending.is_some() || self.git_status_pending.is_some() {
            v.push(crate::i18n::Msg::BusyGitScan);
        }
        if self.media_loading {
            v.push(crate::i18n::Msg::BusyMedia);
        }
        if self.hl_pending || self.hl_warming {
            v.push(crate::i18n::Msg::BusyHighlight);
        }
        if self.md_images_loading() {
            v.push(crate::i18n::Msg::BusyImages);
        }
        v
    }

    /// Whether the top-right busy indicator should be shown/animated right now
    /// (config on + at least one background job in flight). The run loop only schedules
    /// animation ticks while this is true, so idle CPU stays at zero.
    pub fn busy_indicator_active(&self) -> bool {
        self.cfg.ui.busy_indicator && !self.busy_jobs().is_empty()
    }

    /// Advance the spinner by one frame (the run loop calls this periodically while waiting = keeps it spinning).
    pub fn tick_spinner(&mut self) {
        self.spinner_frame = self.spinner_frame.wrapping_add(1);
    }

    /// The current spinner glyph (no emoji; the classic braille-pattern spinner = single-width and color-free in the terminal).
    pub fn spinner_glyph(&self) -> &'static str {
        const FRAMES: [&str; 10] = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
        FRAMES[self.spinner_frame % FRAMES.len()]
    }

    /// `e`: decide the target to open in the external editor and raise the request. Tree=the selected file / Preview=the file being shown.
    /// For a directory or no target, notify via flash and do nothing (only files can be edited).
    /// In Preview the editor is asked to open at the on-screen position (see `preview_edit_line`).
    pub fn request_edit(&mut self) {
        let target = match self.tab.mode {
            Mode::Tree => match self.tab.entries.get(self.tab.selected) {
                Some(e) if e.is_dir => {
                    self.flash = Some(tr(self.lang, crate::i18n::Msg::CannotEditDirectory).into());
                    return;
                }
                Some(e) => Some(e.path.clone()),
                None => None,
            },
            Mode::Preview => self.tab.preview_path.clone(),
        };
        match target {
            Some(p) => self.pending_edit = Some((p, self.preview_edit_line())),
            None => self.flash = Some(tr(self.lang, crate::i18n::Msg::NoFileToEdit).into()),
        }
    }

    /// The 1-based file line to open the external editor at, matching the on-screen position.
    /// - Windowed preview (plain text / code / raw-Markdown via `R`): the exact caret line.
    /// - Rendered Markdown: an **approximate** source line for the top of the current view. Reflow means
    ///   there is no exact scroll-row → source-line mapping, so the top-of-view fraction through the wrapped
    ///   output (`preview_scroll / md_view_rows`) is mapped to that fraction of the source. This lands the
    ///   editor near where you were reading rather than at the top (block-structured docs land on the
    ///   section being read; see `preview_edit_line` verification).
    /// - Otherwise (tree edits, Mermaid, images): None (open at the top).
    fn preview_edit_line(&self) -> Option<usize> {
        if self.tab.mode != Mode::Preview {
            return None;
        }
        if self.is_windowed() {
            return Some(self.tab.preview_cursor_line + 1);
        }
        // Rendered Markdown: reflow means there is no exact scroll-row → source-line mapping. Anchor on a
        // logical line (a Tab-focused item if one is visible, else the top of the view), estimate its
        // source line proportionally, then refine by content (see md_content_anchor_line).
        if matches!(self.tab.preview_kind, Some(PreviewKind::Markdown(_))) {
            if let Some(c) = &self.md_cache {
                let same = self.tab.preview_path.as_ref().is_some_and(|p| *p == c.path);
                if same && c.src_lines > 0 && self.md_view_rows > 0 {
                    // Prefer the on-screen Tab focus (the visible "cursor"); otherwise the top of view.
                    let (logical, row) = match self.md_focused_visible_line() {
                        Some(hit) => hit,
                        None => (
                            self.md_top_logical_line().unwrap_or(0),
                            self.tab.preview_scroll as usize,
                        ),
                    };
                    let est = (row * c.src_lines / self.md_view_rows).min(c.src_lines - 1);
                    return Some(self.md_content_anchor_line(logical, est).unwrap_or(est) + 1);
                }
            }
        }
        None
    }

    /// The (decorated logical line, top display row) of the Tab-focused Markdown item, but only when it
    /// is currently on screen — so `e` opens where the visible cursor is. None if nothing is focused or
    /// the focus has been scrolled out of view (then `e` falls back to the top of the view).
    fn md_focused_visible_line(&self) -> Option<(usize, usize)> {
        let item = self.tab.focused_item.and_then(|i| self.md_items.get(i))?;
        let (row, h) = self.md_visual_span(item.line);
        let scroll = self.tab.preview_scroll as usize;
        let vh = self.tab.preview_viewport.max(1) as usize;
        (row < scroll + vh && row + h > scroll).then_some((item.line, row))
    }

    /// The 0-based decorated (logical) line at the top of the current Markdown view, resolving wrapping
    /// so it matches what the renderer draws (`preview_scroll` is in post-wrap display rows).
    fn md_top_logical_line(&self) -> Option<usize> {
        let c = self.md_cache.as_ref()?;
        if c.lines.is_empty() {
            return None;
        }
        let scroll = self.tab.preview_scroll as usize;
        if !self.cfg.ui.wrap || c.width == 0 || c.row_prefix.len() != c.lines.len() + 1 {
            return Some(scroll.min(c.lines.len() - 1));
        }
        // prefix は各行の開始表示行(単調増加)。scroll を含む行 = pp(p <= scroll) - 1。
        let i = c
            .row_prefix
            .partition_point(|&p| p <= scroll)
            .saturating_sub(1);
        Some(i.min(c.lines.len() - 1))
    }

    /// Refine the proportional editor-open estimate for rendered Markdown by content: take the longest
    /// visible span of decorated logical line `logical` (a single span carries no Markdown markers, so its
    /// text is a verbatim substring of the source) and find the source line containing it, closest to
    /// `est`. Returns a 0-based source line, or None to fall back to `est`. Re-reads the file so it
    /// matches what the editor will open (an agent may have edited it since the preview was built).
    fn md_content_anchor_line(&self, logical: usize, est: usize) -> Option<usize> {
        use ratatui::style::Modifier;
        let c = self.md_cache.as_ref()?;
        let line = c.lines.get(logical)?;
        // Longest non-hidden, non-blank span (hidden spans carry link/URL targets, not on-screen text).
        let key = line
            .spans
            .iter()
            .filter(|s| !s.style.add_modifier.contains(Modifier::HIDDEN))
            .map(|s| s.content.trim())
            .filter(|t| !t.is_empty())
            .max_by_key(|t| t.chars().count())?;
        if key.chars().count() < 4 {
            return None;
        }
        let content = crate::preview::text::load(c.path.as_path()).ok()?;
        let mut best: Option<usize> = None;
        let mut best_d = usize::MAX;
        for (i, sl) in content.lines.iter().enumerate() {
            if sl.contains(key) {
                let d = i.abs_diff(est);
                if d < best_d {
                    best_d = d;
                    best = Some(i);
                }
            }
        }
        best
    }

    /// Taken by the run loop: if set, return the editor-launch target path (+ line) and clear it.
    pub fn take_pending_edit(&mut self) -> Option<(PathBuf, Option<usize>)> {
        self.pending_edit.take()
    }

    /// `O`: request launching an external git tool (lazygit, etc.) (the run loop picks it up, suspends, then launches).
    #[cfg_attr(not(feature = "git"), allow(dead_code))]
    pub fn launch_git_tool(&mut self) {
        self.pending_git_tool = true;
    }

    /// Taken by the run loop: if a git-tool launch request is set, return true and clear it.
    pub fn take_launch_git_tool(&mut self) -> bool {
        std::mem::take(&mut self.pending_git_tool)
    }

    /// Reopen the preview after the external editor exits (reflect the edited content). Caches are also discarded.
    /// Even if the editor replaces the file (temp→rename), the FileWindow is reopened so the latest is read.
    pub fn reload_preview(&mut self) {
        self.md_cache = None;
        self.win_cache = None;
        if matches!(self.tab.mode, Mode::Preview) {
            self.setup_windowed();
            self.reload_media_if_changed();
            // CSV/TSV は外部編集で内容が変わり得る。再パースしてカーソルを範囲内へクランプ(位置は保つ)。
            if matches!(self.tab.preview_kind, Some(PreviewKind::Table { .. })) {
                self.load_table();
                self.clamp_table_cursor();
            }
        }
    }

    /// On an FS-driven reload, re-load media (image/svg/gif/video/pdf) **only when the previewed file
    /// actually changed** (mtime guard). Without this, an image preview stays stale after an external
    /// edit: text/markdown follows via the md_cache clear, but images go through a separate path and were
    /// missed — so when a file is edited externally (e.g. an editor on the right), the konoma preview on the left did not refresh.
    /// The mtime guard avoids re-decoding / re-running external tools (pdftocairo/ffmpeg) on unrelated FS
    /// events. Zoom / pan / page are preserved across the reload.
    fn reload_media_if_changed(&mut self) {
        let is_media = match &self.tab.preview_kind {
            Some(kind) => self.kind_loads_media(kind),
            None => false,
        };
        if !is_media {
            return;
        }
        let Some(path) = self.tab.preview_path.clone() else {
            return;
        };
        let Some(kind) = self.tab.preview_kind.clone() else {
            return;
        };
        if file_mtime(&path) == self.preview_media_mtime {
            return; // 対象ファイルは未変更 → 無駄な再デコード/外部ツール実行を避ける
        }
        // 表示状態(ズーム/中心/ページ)を保持して再ロード。
        let (zoom, center, page) = (
            self.tab.image_zoom,
            self.tab.image_center,
            self.tab.pdf_page,
        );
        self.clear_image(); // ズーム/中心/ページ/メディア世代をリセット
        if matches!(kind, PreviewKind::Pdf(_)) {
            self.tab.pdf_pages = crate::preview::pdf::page_count(&path);
            self.tab.pdf_page = page.clamp(1, self.tab.pdf_pages.unwrap_or(1).max(1));
        }
        self.start_media_load(&kind, &path); // preview_media_mtime も更新される
        self.tab.image_zoom = zoom;
        self.tab.image_center = center;
    }

    /// The directory to watch **in addition** to the tree root so external (agent) edits to the
    /// currently shown file are still detected. Returns the shown file's parent directory **only when
    /// that file lives outside the watched root**: a global-bookmark target, or the repo-wide git view
    /// when the root is a repo subdirectory. Files under the root are already covered by the recursive
    /// root watch (so this returns `None` for them, and whenever no file is shown / not in Preview).
    ///
    /// This closes the gap where the FSEvents watcher only covers `app.tab.root`: an out-of-root preview
    /// or diff never received change events, so an AI/external edit left it stale (the user's own `e`
    /// edit still reloaded via the editor-return path — hence "my edits show, the AI's don't").
    /// Consumed by the run loop in `main.rs`, which adds a non-recursive watch on this directory.
    pub fn out_of_root_watch_dir(&self) -> Option<PathBuf> {
        if !matches!(self.tab.mode, Mode::Preview) {
            return None;
        }
        let p = self.tab.preview_path.as_ref()?;
        if p.starts_with(&self.tab.root) {
            return None; // already covered by the recursive root watch
        }
        p.parent().map(|d| d.to_path_buf())
    }

    /// The repo's `.git` directory to watch **non-recursively** when the tree root is a *subdirectory*
    /// of the repo (so the parent `.git` sits above `root` and is not covered by the recursive root
    /// watch). Without this, an external git op that touches only `.git` (a commit of already-staged
    /// files, an external checkout) fires no event under the subdir, so the cached `git status` /
    /// branch would linger stale — the per-workdir status cache no longer re-verifies on `h`/`l`.
    /// `.git/index` and `.git/HEAD` are direct children, so a non-recursive watch catches the signals
    /// that change status/branch. Returns None when root *is* the repo root (`.git` already watched)
    /// or outside any repo. konoma's own reads are lock-free (`--no-optional-locks`), so this does not
    /// create a self-feedback loop.
    pub fn git_dir_watch(&self) -> Option<PathBuf> {
        let wd = crate::git::workdir(&self.tab.root)?;
        if self.tab.root == wd {
            return None; // root is the repo root → `.git` is already under the recursive watch
        }
        let git = wd.join(".git");
        git.is_dir().then_some(git)
    }

    /// Whether in windowed (large file) mode. Used for the render and scroll branching.
    pub fn is_windowed(&self) -> bool {
        self.preview_win.is_some()
    }

    /// Index of the focused Markdown item (link/checkbox), if any. Read-only query used by the
    /// E2E simulation tests to assert Tab/⇧Tab focus movement.
    #[cfg(test)]
    pub fn focused_item(&self) -> Option<usize> {
        self.tab.focused_item
    }

    /// The link targets in the current Markdown preview's `md_items`, in document order (E2E: assert
    /// exactly which URLs became focusable links — e.g. that a URL inside code did NOT).
    #[cfg(test)]
    pub fn md_link_targets(&self) -> Vec<String> {
        self.md_items
            .iter()
            .filter_map(|it| match &it.kind {
                MdItemKind::Link { target } => Some(target.clone()),
                _ => None,
            })
            .collect()
    }

    /// Whether the current preview is a Markdown/Mermaid file shown as its raw source (`R` toggled on).
    /// Such a preview is windowed like a code file, so the 2D caret selection/copy applies.
    pub fn is_raw_source(&self) -> bool {
        self.tab.md_raw
            && matches!(
                self.tab.preview_kind,
                Some(PreviewKind::Markdown(_)) | Some(PreviewKind::Mermaid(_))
            )
    }

    /// Whether the current preview is Markdown/Mermaid (has a decorated render, so `R` can toggle raw source).
    pub fn is_decorated_kind(&self) -> bool {
        matches!(
            self.tab.preview_kind,
            Some(PreviewKind::Markdown(_)) | Some(PreviewKind::Mermaid(_))
        )
    }

    /// Whether raw source view is currently on (for the footer/title indicator).
    pub fn is_md_raw(&self) -> bool {
        self.tab.md_raw
    }

    /// `R`: toggle a Markdown/Mermaid preview between its decorated render and raw source. No-op for other kinds.
    /// Rebuilds the windowed reader and resets the caret/scroll/selection so the new view starts at the top.
    pub fn toggle_md_raw(&mut self) {
        if !self.is_decorated_kind() {
            return;
        }
        self.tab.md_raw = !self.tab.md_raw;
        // 表示切替＝先頭から。窓読み(raw)/装飾(rendered)を張り直す。
        self.tab.preview_byte_top = 0;
        self.tab.preview_top_line = 0;
        self.tab.preview_scroll = 0;
        self.tab.preview_hscroll = 0;
        self.tab.preview_cursor_line = 0;
        self.tab.preview_cursor_col = 0;
        self.preview_visual_anchor = None;
        self.preview_visual_linewise = false;
        self.md_cache = None;
        self.setup_windowed();
    }

    /// Page the preview to the next/previous **file** in tree display order (`dir`=+1/-1, wraps
    /// at the ends). Directories are skipped; the tree cursor follows the shown file, so leaving
    /// the preview lands where you are. The anchor is the previewed file's tree position, falling
    /// back to the cursor when the previewed file is not in the tree (e.g. a global-bookmark
    /// target outside the root). With no other file to go to, this is a no-op.
    pub fn preview_jump_file(&mut self, dir: i32) {
        if self.tab.mode != Mode::Preview || self.tab.entries.is_empty() {
            return;
        }
        let anchor = self
            .tab
            .preview_path
            .as_ref()
            .and_then(|p| self.tab.entries.iter().position(|e| e.path == *p))
            .unwrap_or_else(|| self.tab.selected.min(self.tab.entries.len() - 1));
        let n = self.tab.entries.len() as i64;
        let mut i = anchor as i64;
        for _ in 0..n {
            i = (i + dir as i64).rem_euclid(n);
            if i as usize == anchor {
                break; // 一周した=他にファイルが無い
            }
            if !self.tab.entries[i as usize].is_dir {
                self.tab.selected = i as usize;
                let path = self.tab.entries[i as usize].path.clone();
                self.enter_preview(&path);
                return;
            }
        }
    }

    pub fn back_to_tree(&mut self) {
        // 全画面フェンス表示からの `q` は「ツリーへ」ではなく「元の Markdown ビューへ」戻る
        // (git diff の came_from_git_view と同じ、来た場所へ帰る流儀)。スクロール/フォーカスも復元。
        if matches!(self.tab.preview_kind, Some(PreviewKind::MermaidFence(_))) {
            if let Some(md) = self.tab.preview_path.clone() {
                let ret = self.tab.fence_return.take();
                self.enter_preview(&md);
                if let Some((scroll, focus)) = ret {
                    self.tab.preview_scroll = scroll;
                    self.tab.focused_item = focus;
                }
                return;
            }
        }
        self.tab.mode = Mode::Tree;
        // Re-verify git status when the tree becomes visible again. FSEvents is inherently lossy
        // (bursts get coalesced, and an external commit can arrive as `.git/*.lock`-only churn), so
        // an external git op during Preview may have left `git_status` stale. Invalidating here makes
        // the next render's `refresh_git_if_needed` refetch the cheap statuses+branch (the heavy
        // `ignored` set is kept, since the repo is unchanged) — so returning to the tree always shows
        // fresh markers, instead of a stale change marker until you navigate across a directory (`h`/`l`).
        // Mark dirty too, so the per-workdir status cache (reused across `h`/`l` in the same repo) is
        // bypassed for this deliberate re-verify — otherwise the stale markers would linger.
        self.git_status_for = None;
        self.git_status_dirty = true;
        // Same seam re-verification for the detail columns: their cells are cached per tree
        // generation (Phase G) and a missed fs event would otherwise pin stale size/mtime until
        // the next rebuild. Dropping here keeps them as robust as the git markers.
        self.detail_cells_cache.clear();
        self.tab.preview_path = None;
        self.tab.preview_kind = None;
        self.clear_image(); // graphics 状態を解放
        self.md_cache = None;
        self.tab.md_raw = false;
        self.preview_win = None;
        self.win_cache = None;
        self.preview_total_lines = None;
        self.hl_pending = false;
        self.hl_warming = false;
        self.tab.preview_byte_top = 0;
        self.tab.preview_top_line = 0;
        self.md_items.clear();
        self.tab.focused_item = None;
        self.tab.preview_search = None;
        self.tab.search_input = None;
        self.tab.search_matches.clear();
        self.table_search_hits.clear();
        self.tab.search_idx = 0;
        self.tab.came_from_git_view = false;
        self.table_data = None;
        self.tab.table_cur_row = 0;
        self.tab.table_cur_col = 0;
        self.tab.table_top_row = 0;
        self.tab.table_left_col = 0;
        self.tab.preview_cursor_line = 0;
        self.tab.preview_cursor_col = 0;
        self.preview_visual_anchor = None;
        self.preview_visual_linewise = false;
    }

    /// Whether this preview kind displays through the media (image) pipeline — and therefore needs
    /// a `start_media_load` whenever its display state was dropped (tab restore / fs reload).
    /// Mermaid kinds count only in image mode; in text mode they draw via the decorated path.
    /// Remember the media currently on screen before a tab switch discards it, so switching back can
    /// reuse it. Skips animated GIFs (frames live in separate state) and anything without a source image.
    fn stash_media_cache(&mut self) {
        if !self.gif_frames.is_empty() {
            return;
        }
        let (Some(path), Some(src)) = (self.tab.preview_path.clone(), self.image_src.clone())
        else {
            return;
        };
        // 1枠とはいえ「見た画像を1枚ずっと抱える」ので、病的に大きいものは諦めて捨てる
        // (再デコードの方が、数百 MB を常駐させ続けるより安い)。**実バイト数**で見る:
        // 画素数だけだと 16bit PNG(8B/px)や HDR/EXR(12B/px)が上限をすり抜けて数百 MiB 常駐する。
        const MAX_CACHED_BYTES: usize = 128 * 1024 * 1024;
        if src.as_bytes().len() > MAX_CACHED_BYTES {
            self.media_cache = None; // 旧エントリも道連れにしない
            return;
        }
        let meta = std::fs::metadata(&path).ok();
        self.media_cache = Some(MediaCache {
            path,
            mtime: self.preview_media_mtime,
            len: meta.map(|m| m.len()),
            page: self.tab.pdf_page.max(1),
            fence_ord: self.preview_fence_ord(),
            src,
            logical: self.image_logical,
            vector_svg: self.vector_svg.clone(),
        });
    }

    /// Release the one-slot media cache if it belongs to the preview currently on screen (the tab that
    /// is about to be closed). Without this, closing the only media tab leaves its image resident with
    /// nothing able to reuse it.
    fn drop_media_cache_for_active(&mut self) {
        let cur = self.tab.preview_path.as_deref();
        if matches!((&self.media_cache, cur), (Some(c), Some(p)) if c.path == p) {
            self.media_cache = None;
        }
        // 表示中のメディアそのものも、このタブが閉じられるので退避対象にしない。
        if self.image_src.is_some() && cur.is_some() {
            self.media_cache = match self.media_cache.take() {
                Some(c) if Some(c.path.as_path()) != cur => Some(c),
                _ => None,
            };
        }
    }

    /// The mermaid-fence ordinal of the current preview, if it is a full-screen fence.
    fn preview_fence_ord(&self) -> Option<usize> {
        match &self.tab.preview_kind {
            Some(PreviewKind::MermaidFence(ord)) => Some(*ord),
            _ => None,
        }
    }

    /// Restore the stashed media for `path` if it is an exact match and the file has not changed since.
    /// Returns true when the caller can skip re-loading the media entirely.
    fn restore_media_cache(&mut self, path: &Path, page: u32) -> bool {
        let len = std::fs::metadata(path).ok().map(|m| m.len());
        let fence = self.preview_fence_ord();
        let hit = matches!(&self.media_cache, Some(c)
            if c.path == path
                && c.page == page
                && c.fence_ord == fence
                && c.mtime == file_mtime(path)
                && c.mtime.is_some()
                && c.len == len);
        if !hit {
            return false;
        }
        let c = self.media_cache.as_ref().expect("checked above");
        self.image_logical = c.logical;
        self.vector_svg = c.vector_svg.clone();
        self.preview_media_mtime = c.mtime;
        // Arc の中身は共有なので画像は複製しない。protocol は直前の `clear_image` が落としており、
        // `image_crop = None` が次の描画での作り直しの合図になる(kitty 側の残像掃除も clear_image が担当)。
        self.image_src = Some(c.src.clone());
        self.image_crop = None;
        true
    }

    fn kind_loads_media(&self, kind: &PreviewKind) -> bool {
        matches!(
            kind,
            PreviewKind::Image(_)
                | PreviewKind::Svg(_)
                | PreviewKind::Video(_)
                | PreviewKind::Pdf(_)
        ) || (matches!(kind, PreviewKind::Mermaid(_) | PreviewKind::MermaidFence(_))
            && self.mermaid_image_mode())
    }

    /// Release and reset the image display state (protocol, source image, zoom/pan).
    fn clear_image(&mut self) {
        self.image = None;
        self.kitty_image = None;
        // Discard any in-flight kitty build from the file we are leaving (gen bump) and clear the
        // wanted geometry so the next image triggers a fresh (synchronous first) build.
        self.kitty_gen = self.kitty_gen.wrapping_add(1);
        self.kitty_want = None;
        self.kitty_shown = None;
        self.image_src = None;
        self.tab.image_zoom = 1.0;
        self.tab.image_center = (0.5, 0.5);
        self.image_crop = None;
        self.image_vis_frac = (1.0, 1.0);
        self.vector_svg = None;
        self.image_logical = None;
        self.gif_frames = Vec::new();
        self.gif_idx = 0;
        self.gif_shown_at = None;
        self.gif_protocol = None;
        self.gif_proto_key = None;
        self.tab.pdf_page = 1;
        self.tab.pdf_pages = None;
        // 世代を進めて、別ファイルの読み込み中に届く前ファイルのメディア結果を陳腐化させる。
        self.media_gen = self.media_gen.wrapping_add(1);
        self.media_loading = false;
        self.vector_reraster_inflight = false;
        // 画像状態を捨てたら mtime の主張も捨てる(不変条件)。残すと「表示は無いのに mtime は
        // 最新」の地雷になり、reload_media_if_changed が未変更と誤判定して再ロードを塞ぐ
        // (タブ復帰で mermaid がテキスト図に劣化していた真因の一つ)。
        self.preview_media_mtime = None;
    }

    /// Page the text preview by one page (dir: +1=next page / -1=previous page).
    /// Overlaps one row to keep context. The upper bound is clamped at render time.
    pub fn preview_page(&mut self, dir: i32) {
        let page = self.tab.preview_viewport.saturating_sub(1).max(1) as i32;
        self.preview_scroll(dir * page);
    }

    /// Half-page the text preview (vim: Ctrl-d/Ctrl-u, less: d/u).
    pub fn preview_half_page(&mut self, dir: i32) {
        let half = (self.tab.preview_viewport / 2).max(1) as i32;
        self.preview_scroll(dir * half);
    }

    /// To the top of the preview.
    pub fn preview_to_top(&mut self) {
        if self.is_windowed() {
            self.tab.preview_cursor_line = 0;
            self.tab.preview_byte_top = 0;
            self.tab.preview_top_line = 0;
        } else {
            self.tab.preview_scroll = 0;
        }
    }

    /// To the bottom of the preview. The actual maximum is clamped at render time, when content and screen size are known.
    /// When windowed, moves to the line-head byte of the last page (found by a backward seek, without scanning the whole file).
    /// If line numbers are ON, the bottom line number is also corrected from the total line count.
    pub fn preview_to_bottom(&mut self) {
        if !self.is_windowed() {
            self.tab.preview_scroll = u16::MAX;
            return;
        }
        let vh = self.tab.preview_viewport.max(1) as usize;
        // 行カーソルの末尾クランプに総行数が要るので常に求める(キャッシュされる)。
        let total = self.win_total();
        let cur = self.tab.preview_top_line;
        if let Some(b) = self
            .preview_win
            .as_mut()
            .map(|w| w.last_page_top(vh).unwrap_or(0))
        {
            self.tab.preview_byte_top = b;
            self.tab.preview_top_line = total.map(|t| t.saturating_sub(vh)).unwrap_or(cur);
        }
        if let Some(t) = total {
            self.tab.preview_cursor_line = t.saturating_sub(1);
        }
    }

    /// Total line count (computed and cached only when line numbers are ON). Scans the whole file, so call it minimally.
    fn win_total(&mut self) -> Option<usize> {
        if let Some(t) = self.preview_total_lines {
            return Some(t);
        }
        let t = self.preview_win.as_mut()?.count_lines().ok()?;
        self.preview_total_lines = Some(t);
        Some(t)
    }

    /// Apply a re-encode result from the worker to the current image state. Returns true if applied.
    pub fn apply_image_resize(&mut self, resp: Result<ResizeResponse, Errors>) -> bool {
        let Ok(resp) = resp else {
            return false; // エンコード失敗は無視(クラッシュさせない)
        };
        match self.image.as_mut() {
            Some(state) => state.update_resized_protocol(resp),
            None => false,
        }
    }

    pub fn preview_scroll(&mut self, delta: i32) {
        if self.is_windowed() {
            // windowed(Code/Text)は行カーソルを動かし、窓を追従させる(常時カーソルモデル)。
            self.preview_cursor_move(delta);
            return;
        }
        let next = self.tab.preview_scroll as i32 + delta;
        // 下限のみここで。上限 (末尾) は内容・画面サイズが判る描画時にクランプする。
        self.tab.preview_scroll = next.max(0) as u16;
    }

    /// Move the windowed line cursor by `delta` (clamped to the file), then scroll the window to keep it visible.
    /// In visual mode the anchor stays fixed, so moving the cursor extends the selection.
    fn preview_cursor_move(&mut self, delta: i32) {
        let total = self.win_total().unwrap_or(usize::MAX);
        let maxl = total.saturating_sub(1) as i64;
        let next =
            (self.tab.preview_cursor_line as i64 + delta as i64).clamp(0, maxl.max(0)) as usize;
        self.tab.preview_cursor_line = next;
        self.follow_cursor();
    }

    /// Scroll the window (byte-based) just enough that the line cursor is on screen.
    fn follow_cursor(&mut self) {
        let vh = self.tab.preview_viewport.max(1) as usize;
        let top = self.tab.preview_top_line;
        let cur = self.tab.preview_cursor_line;
        if cur < top {
            self.win_scroll_lines(-((top - cur) as i32));
        } else if cur >= top + vh {
            self.win_scroll_lines((cur + 1 - (top + vh)) as i32);
        }
    }

    /// Windowed scroll (delta lines). Computes the surrounding line-head bytes each time to move preview_byte_top, and
    /// updates preview_top_line (the line number) by the actual number of moved lines. Downward is clamped so as not to pass the last page.
    /// On end-clamp, the line number is corrected from the total line count when line numbers are ON.
    fn win_scroll_lines(&mut self, delta: i32) {
        let vh = self.tab.preview_viewport.max(1) as usize;
        let top = self.tab.preview_byte_top;
        let line = self.tab.preview_top_line;
        // 行番号 ON、または(行カーソルのため)総行数が既にキャッシュされていれば末尾クランプに使う。
        let total = if self.cfg.ui.line_numbers || self.preview_total_lines.is_some() {
            self.win_total()
        } else {
            None
        };
        let result = self.preview_win.as_mut().map(|w| {
            if delta > 0 {
                let (adv, moved) = w.advance(top, delta as usize).unwrap_or((top, 0));
                let maxt = w.last_page_top(vh).unwrap_or(top);
                if adv >= maxt {
                    // 末尾ページ到達: 行番号は総行数から(無ければ素朴に加算)。
                    let bl = total.map(|t| t.saturating_sub(vh)).unwrap_or(line + moved);
                    (maxt, bl)
                } else {
                    (adv, line + moved)
                }
            } else if delta < 0 {
                let (ret, moved) = w.retreat(top, (-delta) as usize).unwrap_or((0, 0));
                (ret, line.saturating_sub(moved))
            } else {
                (top, line)
            }
        });
        if let Some((nt, nl)) = result {
            self.tab.preview_byte_top = nt;
            self.tab.preview_top_line = nl;
        }
    }

    /// For windowed display, read the current window (from the top byte for the height), highlight Code with syntect
    /// / leave Text plain, and return it as a list of ratatui Lines. Cached by (path, top byte, height),
    /// re-read only on scroll/resize. If the top exceeds the last page, it is clamped.
    pub fn windowed_lines(&mut self, height: u16, width: u16) -> Vec<Line<'static>> {
        let _ = width; // 行内容は幅に依存しない(折返しは描画側)。将来用に受けておく。
        let h = height.max(1) as usize;
        // リサイズ等で末尾を超えていたらクランプ(行番号も総行数から補正)。
        let top0 = self.tab.preview_byte_top;
        let maxt = self
            .preview_win
            .as_mut()
            .and_then(|w| w.last_page_top(h).ok());
        if let Some(maxt) = maxt {
            if top0 > maxt {
                self.tab.preview_byte_top = maxt;
                // 行番号ガター OFF でも検索の現在一致(橙)が abs=preview_top_line+i で
                // 参照するため、末尾ページへのクランプ時は line_numbers の有無に関わらず
                // 常に preview_top_line を総行数から補正する(#5)。
                if let Some(t) = self.win_total() {
                    self.tab.preview_top_line = t.saturating_sub(h);
                }
            }
        }
        let top = self.tab.preview_byte_top;
        let path = self.tab.preview_path.clone().unwrap_or_default();
        // syntax を着けるか: ハイライト無効(off-switch) / progressive で待ち中(hl_pending)なら素。
        // Code は常に対象。Text は「拡張子/ファイル名から実在の文法が解決できる時だけ」対象にする＝
        // .bashrc/Makefile/Dockerfile 等の設定ファイルを着色しつつ、本当に素のテキストは無色のまま保つ。
        // progressive 待ち中だけは「差し替え前の素テキスト」なのでキャッシュしない(後で着色版に替わる)。
        let syntax_kind = match &self.tab.preview_kind {
            Some(PreviewKind::Code(_)) => true,
            Some(PreviewKind::Text(p)) => crate::preview::code::has_named_syntax(p),
            // raw ソース表示(`R`)の Markdown/Mermaid はファイルの文法(.md→Markdown 等)で着色する。
            Some(PreviewKind::Markdown(p)) | Some(PreviewKind::Mermaid(p)) if self.tab.md_raw => {
                crate::preview::code::has_named_syntax(p)
            }
            _ => false,
        };
        let want_syntax = self.cfg.ui.syntax_highlight
            && syntax_kind
            && (!self.hl_pending || self.loading_is_indicator());
        // progressive 待ち中の素テキストだけはキャッシュしない(後で着色版に差し替わるため)。
        // それ以外は素テキストでも (path, top, height) でキャッシュする=毎フレームのファイル
        // 読み直しをしない。`styled` をキーに含め、着色版と素版を取り違えない。
        let cacheable = want_syntax || !(self.cfg.ui.syntax_highlight && syntax_kind);
        let mut content: Vec<Line<'static>> = if cacheable {
            let hit = matches!(
                &self.win_cache,
                Some(c) if c.path == path && c.byte_top == top && c.height == height
                    && c.styled == want_syntax
            );
            if !hit {
                let raw = self
                    .preview_win
                    .as_mut()
                    .and_then(|w| w.read_lines(top, h).ok())
                    .unwrap_or_default();
                let lines = if want_syntax {
                    let src = raw.join("\n");
                    crate::preview::code::highlight(&src, &path, &self.cfg.ui.theme.code_theme)
                } else {
                    raw.into_iter().map(Line::from).collect()
                };
                self.win_cache = Some(WinCache {
                    path,
                    byte_top: top,
                    height,
                    styled: want_syntax,
                    lines,
                });
            }
            self.win_cache
                .as_ref()
                .map(|c| c.lines.clone())
                .unwrap_or_default()
        } else {
            // progressive 待ち中の素テキスト(キャッシュしない=着色完了で差し替わる)。
            let raw = self
                .preview_win
                .as_mut()
                .and_then(|w| w.read_lines(top, h).ok())
                .unwrap_or_default();
            raw.into_iter().map(Line::from).collect()
        };
        // タブを可視マーカー(→)＋タブストップ空白へ展開する(端末はタブを桁揃えしないため)。
        // 行番号ガター/検索強調の前に行う＝桁追跡が本文の先頭(0桁)基準になる。窓の可視行のみ=軽い。
        content = crate::preview::code::expand_tabs(content, self.cfg.ui.tab_width);
        // 検索中は一致箇所(クエリ)を強調する(ガターより先=本文だけ強調)。
        // 現在の出現(search_idx)1箇所だけオレンジ、他は黄色。表示行 i の絶対行 = preview_top_line + i。
        // その行が現在の出現の行なら、その列(col)の出現だけオレンジにする(同一行に複数あっても1つ)。
        if let Some(q) = self.tab.preview_search.clone() {
            // 現在一致(search_idx)の行と、その「行内での出現順位」(0始まり)を求める。
            // タブ展開でバイト列がずれるため、列(バイト位置)ではなく出現順位で
            // 現在一致を同定する(#14)。同一行の一致は search_matches 内で連続・列昇順。
            let (cur_line, cur_rank) =
                match self.tab.search_matches.get(self.tab.search_idx).copied() {
                    Some((_, line, _)) => {
                        let rank = self.tab.search_matches[..self.tab.search_idx]
                            .iter()
                            .filter(|(_, l, _)| *l == line)
                            .count();
                        (Some(line), Some(rank))
                    }
                    None => (None, None),
                };
            let top_line = self.tab.preview_top_line;
            content = content
                .into_iter()
                .enumerate()
                .map(|(i, l)| {
                    let abs = top_line + i;
                    let rank = if cur_line == Some(abs) {
                        cur_rank
                    } else {
                        None
                    };
                    highlight_query_in_line(l, &q, rank)
                })
                .collect();
        }
        let top_line = self.tab.preview_top_line;
        // 2D キャレット列を可視のカーソル行の実長さにクランプし、書き戻す(`l`/`$` の行き過ぎ補正)。
        // キャレット行はビューポート追従で常に可視なので、ここで content から実長を取得できる。
        if self.tab.preview_cursor_line >= top_line
            && self.tab.preview_cursor_line < top_line + content.len()
        {
            let ln = &content[self.tab.preview_cursor_line - top_line];
            let len: usize = ln.spans.iter().map(|s| s.content.chars().count()).sum();
            // 読み取り専用キャレットは常に実在の文字の上に置く(空行は 0)。$ は最後の文字へ。
            self.tab.preview_cursor_col = self.tab.preview_cursor_col.min(len.saturating_sub(1));
        }
        // 行カーソル/選択範囲のハイライト(ガター前＝列インデックスが本文先頭 0 基準に揃う)。
        let content = apply_preview_caret(
            content,
            top_line,
            self.tab.preview_cursor_line,
            self.tab.preview_cursor_col,
            self.preview_selection(),
        );
        // 行番号ガター(設定 ON のときだけ)。先頭行番号 = preview_top_line。
        let content = if self.cfg.ui.line_numbers {
            with_line_numbers(content, top_line)
        } else {
            content
        };
        // git 変更ガター(設定 ON・変更のあるファイルのみ)。行番号の左に 1 セルのマーカーを前置する。
        let marks = self.git_gutter_marks();
        with_git_gutter(content, top_line, &marks)
    }

    /// Git gutter marks (per 1-based new-file line) for the current code/text preview, cached per path.
    /// Empty when the gutter is disabled, outside a repo, or the file is unchanged (→ no gutter column).
    /// Called from `windowed_lines`, which only runs for code/text previews, so no kind check is needed.
    fn git_gutter_marks(&mut self) -> std::collections::HashMap<u32, GutterMark> {
        if !self.cfg.ui.git_gutter {
            return std::collections::HashMap::new();
        }
        let Some(path) = self.tab.preview_path.clone() else {
            return std::collections::HashMap::new();
        };
        let hit = matches!(&self.gutter_cache, Some(c) if c.path == path);
        if !hit {
            let diff = crate::git::file_diff(&self.tab.root, &path);
            let marks = gutter_marks(&diff);
            self.gutter_cache = Some(GutterCache {
                path: path.clone(),
                marks,
            });
        }
        self.gutter_cache
            .as_ref()
            .map(|c| c.marks.clone())
            .unwrap_or_default()
    }

    /// Windowed scroll progress (0..=100 %). For the title display. None if not windowed.
    pub fn window_progress(&self) -> Option<u16> {
        let w = self.preview_win.as_ref()?;
        let len = w.len();
        if len == 0 {
            return Some(0);
        }
        Some((self.tab.preview_byte_top.min(len) * 100 / len) as u16)
    }

    pub fn preview_hscroll(&mut self, delta: i32) {
        let next = self.tab.preview_hscroll as i32 + delta;
        self.tab.preview_hscroll = next.max(0) as u16;
    }
    /// Reset horizontal scroll to the line start (left edge) in one step. `0`. When wrapping, it is already 0, so no effect.
    pub fn preview_hscroll_home(&mut self) {
        self.tab.preview_hscroll = 0;
    }
    /// Send horizontal scroll to the line end (right edge) in one step. `$`. The actual maximum is clamped to the longest line width at render time
    /// (here we set the upper bound, and the render side's `.min(max_h)` settles it at the correct right edge).
    pub fn preview_hscroll_end(&mut self) {
        self.tab.preview_hscroll = u16::MAX;
    }

    pub fn cycle_path_style(&mut self) {
        self.path_style = self.path_style.next();
    }

    /// Toggle the `?` help. When opening, reset scroll to the top.
    pub fn toggle_help(&mut self) {
        self.show_help = !self.show_help;
        self.help_scroll = 0;
    }

    /// Toggle the `i` file-info popup. Does not open if there is no target.
    pub fn toggle_info(&mut self) {
        if self.show_info {
            self.show_info = false;
        } else if self.info_target().is_some() {
            self.show_info = true;
        } else {
            self.flash = Some(crate::i18n::tr(self.lang, crate::i18n::Msg::NoTarget).into());
        }
    }
    /// Whether the file-info popup is showing.
    pub fn is_info(&self) -> bool {
        self.show_info
    }
    /// The target path for the info display: Tree=the cursor item / Preview=the file being previewed.
    pub fn info_target(&self) -> Option<PathBuf> {
        match self.tab.mode {
            Mode::Tree => self
                .tab
                .entries
                .get(self.tab.selected)
                .map(|e| e.path.clone()),
            Mode::Preview => self.tab.preview_path.clone(),
        }
    }

    /// Scroll within the help. The upper bound is clamped at render time (since content and screen size are then known).
    pub fn help_scroll_by(&mut self, delta: i32) {
        self.help_scroll = (self.help_scroll as i32 + delta).max(0) as u16;
    }

    /// Format a path into a display string using the current path_style (shared by the tree/preview title).
    pub fn format_path(&self, path: &Path) -> String {
        match self.path_style {
            PathStyle::Full => path.display().to_string(),
            PathStyle::Home => home_relative(path),
            PathStyle::Relative => rel_to_open(&self.tab.open_dir, path),
        }
    }
}

/// Common helper that moves a list cursor by delta and returns it clamped to `[0, len-1]`.
/// Even if the caller (`g`/`G`/Home/End) passes `delta=i32::MIN/MAX`, the computation is done in i64, so it
/// does not panic on overflow (the plain `as i32 + delta` addition used to crash in debug).
/// `len==0` returns 0. The behavior is unchanged from the previous `(cur as i32 + delta).clamp(0, len-1)`.
fn clamp_cursor(cur: usize, delta: i32, len: usize) -> usize {
    if len == 0 {
        return 0;
    }
    let last = len.saturating_sub(1) as i64;
    (cur as i64).saturating_add(delta as i64).clamp(0, last) as usize
}

/// Within line `line` (multiple colored spans), highlight the parts matching `query` (substring, case-insensitive)
/// in a highlighter style (background color + black text + bold). Even for matches crossing span boundaries, each span is split at the
/// match boundaries and the background is applied (the original fg/bold/italic are kept). If the byte length changes when lowercasing
/// (multibyte), it does nothing to avoid mis-slicing.
/// When `current_occurrence`=Some(occurrence rank within the line, 0-based), **only that one occurrence is orange**, and
/// the others are yellow (vim's CurSearch/Search style; `n`/`N` change the color of only the selected occurrence). None means all yellow.
/// Since occurrences are identified by rank rather than column (byte position), the current match stays stable even if the byte sequence shifts from tab expansion (#14).
fn highlight_query_in_line(
    line: Line<'static>,
    query: &str,
    current_occurrence: Option<usize>,
) -> Line<'static> {
    use ratatui::style::{Color, Modifier};
    if query.is_empty() {
        return line;
    }
    let full: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
    let lower = full.to_lowercase();
    let q = query.to_lowercase();
    if lower.len() != full.len() {
        return line; // 非 ASCII でバイト長が変わる場合は安全側で強調なし
    }
    // 一致バイト範囲を収集。
    let mut ranges: Vec<(usize, usize)> = Vec::new();
    let mut i = 0;
    while let Some(rel) = lower[i..].find(&q) {
        let s = i + rel;
        let e = s + q.len();
        ranges.push((s, e));
        i = e;
    }
    if ranges.is_empty() {
        return line;
    }
    let style = line.style;
    let mut out: Vec<Span<'static>> = Vec::new();
    let mut pos = 0usize; // full 内のバイト位置
    for span in line.spans {
        let text = span.content.into_owned();
        let span_start = pos;
        let span_end = pos + text.len();
        // この span 内の分割点(span 端＋一致境界)。
        let mut points = vec![span_start, span_end];
        for (s, e) in &ranges {
            if *s > span_start && *s < span_end {
                points.push(*s);
            }
            if *e > span_start && *e < span_end {
                points.push(*e);
            }
        }
        points.sort_unstable();
        points.dedup();
        for w in points.windows(2) {
            let (a, b) = (w[0], w[1]);
            if let Some(seg) = text.get(a - span_start..b - span_start) {
                if seg.is_empty() {
                    continue;
                }
                // この区間が属する一致範囲の出現順位(あれば)。その順位が current_occurrence
                // なら現在の出現=オレンジ、他の一致は黄色。範囲外は素のまま。
                let hit = ranges.iter().position(|(s, e)| a >= *s && b <= *e);
                let st = if let Some(idx) = hit {
                    let bg = if current_occurrence == Some(idx) {
                        Color::Rgb(0xff, 0x8c, 0x00) // 現在の出現
                    } else {
                        Color::Yellow // 他の出現
                    };
                    span.style
                        .bg(bg)
                        .fg(Color::Black)
                        .add_modifier(Modifier::BOLD)
                } else {
                    span.style
                };
                out.push(Span::styled(seg.to_string(), st));
            }
        }
        pos = span_end;
    }
    Line::from(out).style(style)
}

/// Editor-style git change status of one line in the previewed (working-tree) file, for the left gutter.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum GutterMark {
    /// Newly inserted line (no matching removal): green bar.
    Added,
    /// Line replaced/edited (part of a hunk that also removed lines): blue bar.
    Modified,
    /// One or more lines were removed just above this line: red boundary marker.
    Deleted,
}

// Gutter marker colors, matching Zed: green added, amber modified, red deleted.
const GUTTER_ADDED: ratatui::style::Color = ratatui::style::Color::Rgb(87, 171, 90);
const GUTTER_MODIFIED: ratatui::style::Color = ratatui::style::Color::Rgb(216, 166, 74);
const GUTTER_DELETED: ratatui::style::Color = ratatui::style::Color::Rgb(199, 84, 80);

/// Derive a per-new-line git gutter map from a file's working-tree diff. Keyed by 1-based new-file line
/// number. A change block is a maximal run of Added/Removed lines (Context breaks it): with additions it
/// marks each added line Modified (if the block also removed lines) or Added (pure insertion); a
/// pure-deletion block marks the following line Deleted (or the preceding line if the deletion is at EOF).
fn gutter_marks(diff: &[crate::git::DiffLine]) -> std::collections::HashMap<u32, GutterMark> {
    use crate::git::DiffLineKind;
    let mut marks = std::collections::HashMap::new();
    let mut i = 0;
    while i < diff.len() {
        if diff[i].kind == DiffLineKind::Context {
            i += 1;
            continue;
        }
        let start = i;
        let mut removed = 0usize;
        let mut added: Vec<u32> = Vec::new();
        while i < diff.len() && diff[i].kind != DiffLineKind::Context {
            match diff[i].kind {
                DiffLineKind::Removed => removed += 1,
                DiffLineKind::Added => {
                    if let Some(n) = diff[i].new_no {
                        added.push(n);
                    }
                }
                DiffLineKind::Context => {}
            }
            i += 1;
        }
        if !added.is_empty() {
            let mark = if removed > 0 {
                GutterMark::Modified
            } else {
                GutterMark::Added
            };
            for n in added {
                marks.insert(n, mark);
            }
        } else if removed > 0 {
            // Pure deletion: anchor the marker to the line just below the removed block; if the block is
            // at EOF, anchor to the last real line above it (deletion below).
            let anchor = diff
                .get(i)
                .and_then(|d| d.new_no)
                .or_else(|| diff[..start].iter().rev().find_map(|d| d.new_no));
            if let Some(a) = anchor {
                marks.entry(a).or_insert(GutterMark::Deleted);
            }
        }
    }
    marks
}

/// Prepend a one-cell git change marker to each line (before the line-number gutter, Zed-style). Only
/// applied when the file has changes (`marks` non-empty) — unchanged files / non-repos keep their layout.
/// The displayed line `i` maps to 1-based file line `top_line + i + 1`; unchanged lines get a blank cell.
fn with_git_gutter(
    lines: Vec<Line<'static>>,
    top_line: usize,
    marks: &std::collections::HashMap<u32, GutterMark>,
) -> Vec<Line<'static>> {
    use ratatui::style::{Color, Style};
    if marks.is_empty() {
        return lines;
    }
    lines
        .into_iter()
        .enumerate()
        .map(|(i, line)| {
            let n = (top_line + i + 1) as u32;
            let (glyph, color) = match marks.get(&n) {
                Some(GutterMark::Added) => ("▌", GUTTER_ADDED),
                Some(GutterMark::Modified) => ("▌", GUTTER_MODIFIED),
                // Thin bar hugging the TOP edge of the line below a deletion, so it
                // sits on the seam between the two lines instead of looking like the
                // line itself was removed. (A terminal cell can't draw in the inter-row
                // gap, so the top edge is the closest we can get without adding a row.)
                Some(GutterMark::Deleted) => ("▔", GUTTER_DELETED),
                None => (" ", Color::Reset),
            };
            let style = line.style;
            let mut spans = Vec::with_capacity(line.spans.len() + 1);
            spans.push(Span::styled(glyph, Style::new().fg(color)));
            spans.extend(line.spans);
            Line::from(spans).style(style)
        })
        .collect()
}

/// Prepend a line-number gutter (right-aligned + a space) to each line. The first line's number is `top_line+1` (1-based).
/// A dim color (DarkGray) distinguishes it from the body. The original line style (background, etc.) is kept.
fn with_line_numbers(lines: Vec<Line<'static>>, top_line: usize) -> Vec<Line<'static>> {
    use ratatui::style::{Color, Style};
    let last = top_line + lines.len().max(1);
    let width = last.to_string().len().max(3); // 最低 3 桁ぶんの幅を確保
    lines
        .into_iter()
        .enumerate()
        .map(|(i, line)| {
            let n = top_line + i + 1;
            let gutter = Span::styled(format!("{n:>width$} "), Style::new().fg(Color::DarkGray));
            let style = line.style;
            let mut spans = Vec::with_capacity(line.spans.len() + 1);
            spans.push(gutter);
            spans.extend(line.spans);
            Line::from(spans).style(style)
        })
        .collect()
}

/// The rectangle that centers an image of size `cells` (natural size) within `inner` while preserving the aspect ratio.
/// With `allow_upscale=false`, downscale only (scale<=1=fit behavior); with `true`, it may upscale to fill the area.
fn centered_rect(cells: (u16, u16), inner: Rect, allow_upscale: bool) -> Rect {
    let (cw, ch) = cells;
    if cw == 0 || ch == 0 || inner.width == 0 || inner.height == 0 {
        return inner;
    }
    let mut scale = (inner.width as f64 / cw as f64).min(inner.height as f64 / ch as f64);
    if !allow_upscale {
        scale = scale.min(1.0);
    }
    let w = ((cw as f64 * scale).round() as u16).clamp(1, inner.width);
    let h = ((ch as f64 * scale).round() as u16).clamp(1, inner.height);
    let x = inner.x + (inner.width - w) / 2;
    let y = inner.y + (inner.height - h) / 2;
    Rect {
        x,
        y,
        width: w,
        height: h,
    }
}

/// Max reserved rows for one inline Markdown image; a taller image is scaled down (keeping aspect) so it never dominates the viewport.
const MD_IMAGE_MAX_ROWS: u16 = 24;

/// Resolve a Markdown image URL to a local file path. A remote (`http(s)://`) URL resolves to its
/// download-cache path, but only once it has been fetched (so callers treat a cached remote image
/// exactly like a local one). `data:` URLs return None. Relative paths are resolved against the
/// Markdown file's directory. Returns the path only if the file exists.
fn resolve_md_image_path(url: &str, base: Option<&Path>) -> Option<PathBuf> {
    let u = url.trim();
    if u.is_empty() {
        return None;
    }
    if crate::preview::markdown::is_remote_image_url(u) {
        let p = md_remote_cache_path(u)?;
        return p.is_file().then_some(p);
    }
    let lower = u.to_ascii_lowercase();
    if lower.starts_with("data:") {
        return None;
    }
    let u = u.strip_prefix("file://").unwrap_or(u);
    let p = PathBuf::from(u);
    let p = if p.is_absolute() {
        p
    } else if let Some(b) = base {
        b.join(p)
    } else {
        p
    };
    p.is_file().then_some(p)
}

/// Pixel dimensions of a cached inline-image file, accepting both raster formats and SVG (parsed cheaply
/// via usvg, without rasterizing). None if the file is neither a known raster image nor an SVG.
fn md_image_dims(path: &Path) -> Option<(u32, u32)> {
    crate::preview::image::dimensions(path).or_else(|| crate::preview::svg::intrinsic_size(path))
}

/// Decode a cached inline-image file to an image, rasterizing SVG (at `svg_max_px`) when the raster
/// decoders reject it (GitHub READMEs are full of SVG badges/logos). None if it is not a decodable image.
fn md_decode_image(path: &Path, svg_max_px: u32) -> Option<image::DynamicImage> {
    crate::preview::image::decode_static(path)
        .or_else(|| crate::preview::svg::rasterize(path, svg_max_px))
}

/// The source-pixel band `(y0, height)` of an image `dh` pixels tall that corresponds to the visible
/// cell rows `[row_off, row_off + vis_rows)` out of `full_rows` total. The result is always within
/// `[0, dh]` (so `crop_imm(0, y0, _, height)` never exceeds the image and never panics), and the height
/// is at least 1.
fn md_band_pixels(full_rows: u16, row_off: u16, vis_rows: u16, dh: u32) -> (u32, u32) {
    let fr = full_rows.max(1) as u32;
    let y0 = (row_off as u32 * dh) / fr;
    let y1 = ((row_off as u32 + vis_rows as u32).min(fr) * dh) / fr;
    (y0, y1.saturating_sub(y0).max(1))
}

/// Root of konoma's on-disk cache (`$XDG_CACHE_HOME` or `~/.cache`). None if neither is available.
fn cache_root() -> Option<PathBuf> {
    if let Some(x) = std::env::var_os("XDG_CACHE_HOME") {
        if !x.is_empty() {
            return Some(PathBuf::from(x));
        }
    }
    let home = std::env::var_os("HOME")?;
    if home.is_empty() {
        return None;
    }
    Some(PathBuf::from(home).join(".cache"))
}

/// Deterministic cache path for a remote image URL: `<cache>/konoma/remote-images/<hash>`. The file is
/// stored without an extension (the content type is unknown until fetched) and read via content sniffing.
fn md_remote_cache_path(url: &str) -> Option<PathBuf> {
    use std::hash::{Hash, Hasher};
    let root = cache_root()?;
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    url.trim().hash(&mut hasher);
    Some(
        root.join("konoma")
            .join("remote-images")
            .join(format!("{:016x}", hasher.finish())),
    )
}

/// Maximum bytes to download for one remote image (guards against huge / hostile responses).
const MD_REMOTE_MAX_BYTES: u64 = 25 * 1024 * 1024;

/// Download a remote image with `curl` into `dest` (atomically, via a temp file), validating that the
/// bytes decode as an image before committing. Returns whether a valid image now exists at `dest`.
/// Runs on a background thread. Uses the system `curl` (always present on macOS) to avoid adding a
/// TLS/HTTP dependency — consistent with konoma's external-tool delegation model (PRD §5).
fn fetch_remote_image(url: &str, dest: &Path) -> bool {
    use std::process::{Command, Stdio};
    let Some(parent) = dest.parent() else {
        return false;
    };
    if std::fs::create_dir_all(parent).is_err() {
        return false;
    }
    let tmp = dest.with_extension("part");
    let status = Command::new("curl")
        .args([
            "-sSL", // silent, show errors, follow redirects (GitHub proxies images via camo)
            "--fail",
            "--max-time",
            "20",
            "--max-filesize",
            &MD_REMOTE_MAX_BYTES.to_string(),
            "-A",
            "konoma image preview",
            "-o",
        ])
        .arg(&tmp)
        .arg(url)
        .stdin(Stdio::null())
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .status();
    let downloaded = matches!(status, Ok(s) if s.success());
    if !downloaded {
        let _ = std::fs::remove_file(&tmp);
        return false;
    }
    // Reject non-images (e.g. an HTML error page served with 200) before caching them (accepts SVG).
    if md_image_dims(&tmp).is_none() {
        let _ = std::fs::remove_file(&tmp);
        return false;
    }
    let ok = std::fs::rename(&tmp, dest).is_ok();
    if ok {
        prune_remote_cache(parent, MD_REMOTE_CACHE_MAX);
    }
    ok
}

/// Keep at most `keep` files in the remote-image cache directory, deleting the oldest (by mtime).
/// The cache is content-addressed (one file per distinct URL) with no cleanup, so without this it
/// grows unbounded over a machine's lifetime. Runs only after a **new** download (rare), so the
/// directory scan is cheap. Best-effort: any IO error just leaves the cache as-is.
fn prune_remote_cache(dir: &Path, keep: usize) {
    let Ok(rd) = std::fs::read_dir(dir) else {
        return;
    };
    let mut files: Vec<(std::time::SystemTime, PathBuf)> = rd
        .flatten()
        .filter(|e| e.file_type().map(|t| t.is_file()).unwrap_or(false))
        .filter_map(|e| {
            let p = e.path();
            // 進行中の一時ファイル(.part)は対象外。
            if p.extension().is_some_and(|x| x == "part") {
                return None;
            }
            let mtime = e.metadata().and_then(|m| m.modified()).ok()?;
            Some((mtime, p))
        })
        .collect();
    if files.len() <= keep {
        return;
    }
    files.sort_by_key(|(t, _)| *t); // oldest first
    for (_, p) in files.iter().take(files.len() - keep) {
        let _ = std::fs::remove_file(p);
    }
}

/// Max files kept in the remote-image disk cache (`~/.cache/konoma/remote-images`).
const MD_REMOTE_CACHE_MAX: usize = 256;

/// Compute the display size in terminal cells for an image of `pw`x`ph` pixels, given the terminal
/// font cell size (`fw`x`fh` px). The image is fit to `avail_cols` (never upscaled beyond its natural
/// cell size) and then capped to `max_rows`, preserving aspect ratio in both steps.
fn md_image_cells(
    pw: u32,
    ph: u32,
    fw: u16,
    fh: u16,
    avail_cols: u16,
    max_rows: u16,
) -> (u16, u16) {
    let fw = (fw.max(1)) as f64;
    let fh = (fh.max(1)) as f64;
    let nat_cols = (pw as f64 / fw).ceil().max(1.0);
    let nat_rows = (ph as f64 / fh).ceil().max(1.0);
    let avail = avail_cols.max(1) as f64;
    let (mut cols, mut rows) = if nat_cols <= avail {
        (nat_cols, nat_rows)
    } else {
        let s = avail / nat_cols;
        (avail, (nat_rows * s).round().max(1.0))
    };
    let maxr = max_rows.max(1) as f64;
    if rows > maxr {
        let s = maxr / rows;
        rows = maxr;
        cols = (cols * s).round().max(1.0);
    }
    (cols as u16, rows as u16)
}

/// Cell box for an inline mermaid diagram: **fill to `target_rows`** (up- or downscale, keeping
/// the aspect from the layout pixels), clamped by the available width. Unlike raster images
/// (`md_image_cells`, never upscaled), diagrams are vector-backed — the raster follows the
/// display size via sharpening re-rasters, so growing beyond the natural size stays crisp.
fn mermaid_cells(pw: u32, ph: u32, fw: u16, fh: u16, avail: u16, target_rows: u16) -> (u16, u16) {
    let (fw, fh) = (fw.max(1) as f64, fh.max(1) as f64);
    let ar = (pw.max(1) as f64) / (ph.max(1) as f64); // px アスペクト
    let mut rows = target_rows.max(1) as f64;
    let mut cols = (rows * fh * ar / fw).round().max(1.0);
    let avail = avail.max(1) as f64;
    if cols > avail {
        cols = avail;
        rows = (cols * fw / ar / fh).round().max(1.0);
    }
    (cols as u16, rows as u16)
}

/// Cell box for an inline math image, sized proportionally from the SVG's intrinsic **em** units
/// (RaTeX renders at 40 units/em) so equations sit at roughly text scale: em-height → rows, intrinsic
/// aspect → cols. Display math gets a touch more height than inline. Clamped to the available width
/// (aspect preserved) and a sane row cap. Vector-backed, so the once-rendered raster is fit crisply.
fn math_cells(uw: u32, uh: u32, fw: u16, fh: u16, avail: u16, display: bool) -> (u16, u16) {
    let (fw, fh) = (fw.max(1) as f64, fh.max(1) as f64);
    let em_h = (uh.max(1) as f64) / 40.0;
    let rows_per_em = if display { 1.5 } else { 1.3 };
    let mut rows = (em_h * rows_per_em).round().max(1.0);
    let ar = (uw.max(1) as f64) / (uh.max(1) as f64);
    let mut cols = (rows * fh * ar / fw).round().max(1.0);
    let avail = avail.max(1) as f64;
    if cols > avail {
        cols = avail;
        rows = (cols * fw / ar / fh).round().max(1.0);
    }
    // 極端に高い式(行列など)が画面を埋め尽くさないための上限。
    let maxr = 24.0;
    if rows > maxr {
        let s = maxr / rows;
        rows = maxr;
        cols = (cols * s).round().max(1.0);
    }
    (cols as u16, rows as u16)
}

/// Source-pixel crop rectangle (x, y, w, h).
type PxRect = (u32, u32, u32, u32);

/// Crop window for the in-place zoom of an inline diagram. `f` is the visible fraction, i.e.
/// 1/zoom, of the source; `center` is clamped so the window stays inside the image. Returns the
/// crop px rect plus the clamped center. Fractions are scale-free, so the same zoom and center
/// map onto a sharper re-raster unchanged.
fn fence_crop(dims: (u32, u32), f: f64, center: (f64, f64)) -> (PxRect, (f64, f64)) {
    let (sw, sh) = dims;
    let f = f.clamp(0.0, 1.0);
    let cx = center.0.clamp(f / 2.0, 1.0 - f / 2.0);
    let cy = center.1.clamp(f / 2.0, 1.0 - f / 2.0);
    let cw = ((sw as f64 * f).round() as u32).clamp(1, sw);
    let ch = ((sh as f64 * f).round() as u32).clamp(1, sh);
    let x0 = ((cx * sw as f64) as i64 - cw as i64 / 2).clamp(0, (sw - cw) as i64) as u32;
    let y0 = ((cy * sh as f64) as i64 - ch as i64 / 2).clamp(0, (sh - ch) as i64) as u32;
    ((x0, y0, cw, ch), (cx, cy))
}

/// Result of [`image_layout`]. `center` and `frac` are both `(f64, f64)` pairs with different
/// meanings (image-space center vs. per-axis visible fraction), so this struct keeps them from
/// being swapped at the call site.
///
/// - `target`  : the render-target rectangle (centered; z=1=fit, grows when zooming, clips when exceeding the viewport)
/// - `crop_rect`: the source-image window of the visible portion (px: x,y,w,h)
/// - `center`  : the center clamped to where the visible window fits within the image [0,1]
/// - `frac`    : the visible fraction per axis (<1=clipped=pan possible)
#[derive(Clone, Copy)]
struct ImageLayout {
    target: Rect,
    crop_rect: PxRect,
    center: (f64, f64),
    frac: (f64, f64),
}

/// Compute the display layout for an image/GIF frame (a pure function shared by prepare_image / prepare_gif).
/// From (source image src, font_size, zoom, center[0,1], display area inner, render_scale), returns
/// an [`ImageLayout`] (None if size 0).
fn image_layout(
    src: &image::DynamicImage,
    font_size: ratatui_image::FontSize,
    zoom: f64,
    center: (f64, f64),
    inner: Rect,
    render_scale: f64,
    logical: Option<(u32, u32)>,
) -> Option<ImageLayout> {
    use image::GenericImageView;
    let (sw, sh) = src.dimensions();
    if sw == 0 || sh == 0 || inner.width == 0 || inner.height == 0 {
        return None;
    }
    // z=1 のフィット表示サイズ(セル, 拡大しない)。ベクタ由来のプレビューは **論理サイズ**
    // (初回ラスタの寸法) で計るので、シャープなラスタへ差し替えても画面上の大きさ・切り出し窓は
    // 一切動かない(HiDPI のバッキングストア方式。切り出し自体は比率で実ピクセルに写像される)。
    let (nw, nh) = match logical {
        Some((lw, lh)) if lw > 0 && lh > 0 => (
            (lw as u16).div_ceil(font_size.width.max(1)),
            (lh as u16).div_ceil(font_size.height.max(1)),
        ),
        _ => {
            let n = Resize::natural_size(src, font_size);
            (n.width, n.height)
        }
    };
    let base = centered_rect((nw, nh), inner, false);
    // ズーム後の論理表示サイズ。
    let disp_w = (base.width as f64 * zoom).max(1.0);
    let disp_h = (base.height as f64 * zoom).max(1.0);
    // 画面に出る大きさ = min(表示サイズ, 表示領域)。
    let tw = (disp_w.min(inner.width as f64).round() as u16).max(1);
    let th = (disp_h.min(inner.height as f64).round() as u16).max(1);
    // 各軸の可視率(<1 なら見切れ＝パン可能)。
    let fw = (tw as f64 / disp_w).min(1.0);
    let fh = (th as f64 / disp_h).min(1.0);
    // 中心を可視窓が画像内に収まる範囲へクランプ。
    let cx = center.0.clamp(fw / 2.0, 1.0 - fw / 2.0);
    let cy = center.1.clamp(fh / 2.0, 1.0 - fh / 2.0);
    // 元画像から見える窓を切り出す(px)。
    let cw = ((sw as f64 * fw).round() as u32).clamp(1, sw);
    let ch = ((sh as f64 * fh).round() as u32).clamp(1, sh);
    let x0 = ((cx * sw as f64) as i64 - cw as i64 / 2).clamp(0, (sw - cw) as i64) as u32;
    let y0 = ((cy * sh as f64) as i64 - ch as i64 / 2).clamp(0, (sh - ch) as i64) as u32;
    let crop_rect = (x0, y0, cw, ch);
    // 表示矩形(中央寄せ)。任意で render_scale により縮小(転送量=描画待ち削減)。
    let scale = render_scale.clamp(0.1, 1.0);
    let (tw, th) = if scale >= 0.999 {
        (tw, th)
    } else {
        (
            ((tw as f64 * scale).round() as u16).max(1),
            ((th as f64 * scale).round() as u16).max(1),
        )
    };
    let target = Rect {
        x: inner.x + (inner.width - tw.min(inner.width)) / 2,
        y: inner.y + (inner.height - th.min(inner.height)) / 2,
        width: tw.min(inner.width),
        height: th.min(inner.height),
    };
    Some(ImageLayout {
        target,
        crop_rect,
        center: (cx, cy),
        frac: (fw, fh),
    })
}

/// The modification time of `path`, or None if it cannot be read. Used by the FS-driven media auto-reload guard.
fn file_mtime(path: &Path) -> Option<std::time::SystemTime> {
    std::fs::metadata(path).and_then(|m| m.modified()).ok()
}

/// Assemble the copy string (a pure function; does not touch the clipboard).
/// `open_dir` is the base for relative paths (the launch directory).
fn copy_text(path: &Path, open_dir: &Path, kind: CopyKind) -> String {
    match kind {
        CopyKind::Name => path
            .file_name()
            .map(|n| n.to_string_lossy().into_owned())
            .unwrap_or_default(),
        CopyKind::Full => path.display().to_string(),
        CopyKind::Parent => path
            .parent()
            .map(|p| p.display().to_string())
            .unwrap_or_default(),
        // 左上のタイトル表示 (format_path の Relative) と完全に同じ基準にする。
        CopyKind::Relative => rel_to_open(open_dir, path),
        CopyKind::AtRef => at_ref_text(open_dir, path),
    }
}

/// `@path` reference for AI agents (Claude Code's `@file` context syntax). Under `open_dir` the path is
/// strictly relative to it (`src/app.rs` — no leading dir name, unlike `rel_to_open`); outside it is
/// `..`-relative; if neither works, absolute. Prefixed with `@`.
fn at_ref_text(open_dir: &Path, path: &Path) -> String {
    let rel = match path.strip_prefix(open_dir) {
        Ok(r) if !r.as_os_str().is_empty() => r.display().to_string(),
        _ => match rel_from(open_dir, path) {
            Some(r) if !r.as_os_str().is_empty() => r.display().to_string(),
            _ => path.display().to_string(),
        },
    };
    format!("@{rel}")
}

/// A relative display string based on `open_dir` (the launch directory). For paths underneath, it puts the launch directory name first (e.g. `A/sub/x`),
/// and for things outside open_dir (siblings/ancestors) it relativizes with `..` (e.g. `../B/aaa.md`, `..`). If it cannot be relativized, `~/...`.
/// A shared function to guarantee the **same base** for the top-left path display (`format_path`'s Relative) and path copy (`cr`/`yr`).
fn rel_to_open(open_dir: &Path, path: &Path) -> String {
    if path.starts_with(open_dir) {
        // open_dir 配下: 起動ディレクトリ名を先頭に出すため、その親を基準に相対化 (例: A/sub/x)。
        let base = open_dir.parent().unwrap_or(open_dir);
        match path.strip_prefix(base) {
            Ok(rel) if !rel.as_os_str().is_empty() => rel.display().to_string(),
            _ => home_relative(path),
        }
    } else {
        // open_dir の外(兄弟/上位など): open_dir 基準の相対パスを `..` 込みで表示 (例: ../B/aaa.md)。
        // これが無いと兄弟 B のファイルが `B/aaa.md` のように見え、配下にあるかのように誤解される。
        match rel_from(open_dir, path) {
            Some(rel) if !rel.as_os_str().is_empty() => rel.display().to_string(),
            _ => home_relative(path),
        }
    }
}

/// Write to the clipboard. Returns Err on environments where arboard is unavailable (the caller shows a flash).
fn set_clipboard(text: &str) -> Result<()> {
    #[cfg(target_os = "linux")]
    {
        // On Linux the clipboard content is owned by the process holding the X11/Wayland
        // selection: dropping the Clipboard releases it and the copied text is lost unless a
        // clipboard manager grabbed it. Probe on the main thread first so the caller still gets
        // an Err (and shows its flash) on headless/unavailable environments, then hold the
        // selection in a detached thread via SetExtLinux::wait() so paste works. wait() returns
        // (and the thread exits) as soon as another app — or the next copy — takes ownership, so
        // at most one holder thread is alive at a time. Not unit-tested (requires an X11/Wayland
        // display); verified in a Linux VM.
        use arboard::SetExtLinux;
        let _ = arboard::Clipboard::new()?;
        let owned = text.to_string();
        std::thread::spawn(move || {
            if let Ok(mut cb) = arboard::Clipboard::new() {
                let _ = cb.set().wait().text(owned);
            }
        });
        Ok(())
    }
    #[cfg(not(target_os = "linux"))]
    {
        let mut cb = arboard::Clipboard::new()?;
        cb.set_text(text.to_string())?;
        Ok(())
    }
}

/// `~/...` if under HOME, otherwise the full path.
pub(crate) fn home_relative(path: &Path) -> String {
    if let Some(home) = std::env::var_os("HOME") {
        let home = PathBuf::from(home);
        if let Ok(rel) = path.strip_prefix(&home) {
            if rel.as_os_str().is_empty() {
                return "~".to_string();
            }
            return format!("~/{}", rel.display());
        }
    }
    path.display().to_string()
}

/// Resolve a dropped (=pasted) string into a list of **existing paths**. Terminals (Ghostty, etc.) pass a drop
/// as shell-escaped text (spaces as `\ `; multiple files separated by unescaped spaces).
/// Undo the backslash escapes, split on unescaped whitespace/newlines, and return only the tokens that **exist on disk**
/// (= safely excludes plain text pastes, junk, and control-character mixes).
fn parse_dropped_paths(text: &str) -> Vec<PathBuf> {
    let mut tokens: Vec<String> = Vec::new();
    let mut cur = String::new();
    let mut escaped = false;
    for c in text.chars() {
        if escaped {
            cur.push(c); // 直前が `\` ＝ この文字はリテラル(空白入りパス名等)
            escaped = false;
        } else if c == '\\' {
            escaped = true;
        } else if c.is_whitespace() {
            if !cur.is_empty() {
                tokens.push(std::mem::take(&mut cur));
            }
        } else {
            cur.push(c);
        }
    }
    if !cur.is_empty() {
        tokens.push(cur);
    }
    tokens
        .into_iter()
        .map(PathBuf::from)
        .filter(|p| p.exists()) // 実在パスのみ採用(テキストペースト/不正入力を弾く安全網)
        .collect()
}

/// Build a plan for sequential rename. Number `targets` **in display order** as `{n}`=1,2,…,
/// expand the template, and create each (old, new) path. If the template has no extension, the original extension is kept automatically.
/// **Pre-validates** collisions: an empty name / a `/` mixed in / duplicate final names / a collision with an existing file (not vacated within the batch) is an Err.
fn build_rename_plan(targets: &[PathBuf], template: &str) -> Result<Vec<(PathBuf, PathBuf)>> {
    let mut plan: Vec<(PathBuf, PathBuf)> = Vec::with_capacity(targets.len());
    for (idx, src) in targets.iter().enumerate() {
        let n = idx + 1;
        let stem = src.file_stem().and_then(|s| s.to_str()).unwrap_or("");
        let ext = src.extension().and_then(|s| s.to_str()).unwrap_or("");
        let rendered = crate::fileops::render_rename_template(template, n, stem, ext);
        let rendered = rendered.trim().to_string();
        if rendered.is_empty() {
            anyhow::bail!("空の名前になります (n={n})");
        }
        if rendered.contains('/') {
            anyhow::bail!("名前に / は使えません: {rendered}");
        }
        // 拡張子: テンプレ結果に拡張子が無ければ元拡張子を自動付与(ユーザ決定)。
        let has_ext = Path::new(&rendered)
            .extension()
            .filter(|e| !e.is_empty())
            .is_some();
        let new_name = if !has_ext && !ext.is_empty() {
            format!("{rendered}.{ext}")
        } else {
            rendered
        };
        let dst = src
            .parent()
            .unwrap_or_else(|| Path::new("."))
            .join(&new_name);
        plan.push((src.clone(), dst));
    }
    // 最終名の重複検証。
    let mut seen = BTreeSet::new();
    for (_, dst) in &plan {
        if !seen.insert(dst.clone()) {
            anyhow::bail!("リネーム先が重複: {}", dst.display());
        }
    }
    // 既存ファイルとの衝突検証(バッチ内で「移動して空く」元パスは除外)。
    let vacated: BTreeSet<PathBuf> = plan
        .iter()
        .filter(|(s, d)| s != d)
        .map(|(s, _)| s.clone())
        .collect();
    for (src, dst) in &plan {
        // 名前据え置き(src == dst)は自分自身の存在を衝突と誤検出しないよう除外する(#11)。
        // 真の衝突=別ファイルと被る場合のみ、最終名重複検証(上)で弾く。
        if src == dst {
            continue;
        }
        if dst.exists() && !vacated.contains(dst) {
            anyhow::bail!("既に存在します: {}", dst.display());
        }
    }
    Ok(plan)
}

/// Return the byte position in `s` corresponding to character index `char_idx` (past the end gives `s.len()`).
/// A conversion to safely compute insertion/deletion positions even for multibyte text (e.g. Japanese file names).
fn char_byte(s: &str, char_idx: usize) -> usize {
    s.char_indices()
        .nth(char_idx)
        .map(|(b, _)| b)
        .unwrap_or(s.len())
}

/// Compute the relative path from `base` to `target`, including `..` (equivalent to pathdiff). It removes the common leading components and
/// pushes one `..` for each remaining level on the base side. None if the root kinds (absolute/drive) disagree and it cannot be relativized.
fn rel_from(base: &Path, target: &Path) -> Option<PathBuf> {
    use std::path::Component;
    let bc: Vec<Component> = base.components().collect();
    let tc: Vec<Component> = target.components().collect();
    let mut i = 0;
    while i < bc.len() && i < tc.len() && bc[i] == tc[i] {
        i += 1;
    }
    // 共通成分が無く、かつ一方がルート(絶対/Prefix)で始まる=相対化不能。
    if i == 0 {
        let is_root = |c: Option<&Component>| {
            matches!(c, Some(Component::Prefix(_)) | Some(Component::RootDir))
        };
        if is_root(bc.first()) || is_root(tc.first()) {
            return None;
        }
    }
    let mut rel = PathBuf::new();
    for _ in i..bc.len() {
        rel.push("..");
    }
    for c in &tc[i..] {
        rel.push(c.as_os_str());
    }
    Some(rel)
}

/// Append one directory's worth of entries to out. Recurse into expanded subdirectories.
/// Bundles the decision info for one entry for sorting. Lowercased sort keys are precomputed
/// once per entry (sort_by runs O(n log n) comparisons — lowercasing inside the comparator
/// allocated two Strings per comparison). The stat is taken only when the sort key needs
/// size/mtime, or when the entry is a symlink (is_dir must follow the link like fs::metadata).
struct ChildMeta {
    path: PathBuf,
    /// Lowercased file name (also the stable tiebreak for every sort key).
    name_lower: String,
    /// Lowercased extension; filled only when sorting by extension.
    ext_lower: String,
    is_dir: bool,
    size: u64,
    mtime: Option<std::time::SystemTime>,
}

fn child_meta(path: PathBuf, ft: Option<std::fs::FileType>, sort: Sort) -> ChildMeta {
    let need_stat = matches!(sort.key, SortKey::Size | SortKey::Modified);
    let is_symlink = ft.map(|t| t.is_symlink()).unwrap_or(true);
    let (is_dir, size, mtime) = if need_stat || is_symlink {
        // fs::metadata follows symlinks, so a symlink to a directory stays expandable.
        let md = std::fs::metadata(&path).ok();
        (
            md.as_ref().map(|m| m.is_dir()).unwrap_or(false),
            md.as_ref().map(|m| m.len()).unwrap_or(0),
            md.as_ref().and_then(|m| m.modified().ok()),
        )
    } else {
        // DirEntry::file_type is free on macOS (readdir d_type) — no extra syscall.
        (ft.map(|t| t.is_dir()).unwrap_or(false), 0, None)
    };
    let name_lower = path
        .file_name()
        .map(|s| s.to_string_lossy().to_lowercase())
        .unwrap_or_default();
    let ext_lower = if matches!(sort.key, SortKey::Ext) {
        path.extension()
            .and_then(|e| e.to_str())
            .unwrap_or("")
            .to_lowercase()
    } else {
        String::new()
    };
    ChildMeta {
        path,
        name_lower,
        ext_lower,
        is_dir,
        size,
        mtime,
    }
}

/// Compare two entries according to the settings. dirs_first → key → reverse, finally stabilized by name.
fn sort_cmp(a: &ChildMeta, b: &ChildMeta, sort: Sort) -> std::cmp::Ordering {
    use std::cmp::Ordering;
    if sort.dirs_first {
        let d = b.is_dir.cmp(&a.is_dir); // ディレクトリ(true)を先頭に
        if d != Ordering::Equal {
            return d;
        }
    }
    let mut ord = match sort.key {
        SortKey::Name => a.name_lower.cmp(&b.name_lower),
        SortKey::Size => a.size.cmp(&b.size),
        SortKey::Modified => a.mtime.cmp(&b.mtime),
        SortKey::Ext => a.ext_lower.cmp(&b.ext_lower),
    };
    if sort.reverse {
        ord = ord.reverse();
    }
    // 同値は名前(昇順)で安定化して並びがブレないようにする。
    ord.then_with(|| a.name_lower.cmp(&b.name_lower))
}

/// Take the title label for the graph base from refs (`%D`). From `(HEAD -> main, origin/main)`, etc.,
/// pick one branch name (strip the HEAD-> and skip tag:). If there is no branch ref, the short hash.
#[cfg_attr(not(feature = "git"), allow(dead_code))]
fn base_label_from(refs: &str, short: &str) -> String {
    for part in refs.split(',').map(str::trim) {
        let p = part.strip_prefix("HEAD -> ").unwrap_or(part);
        if p.is_empty() || p.starts_with("tag:") {
            continue;
        }
        return p.to_string();
    }
    short.to_string()
}

fn build_dir(
    dir: &Path,
    depth: usize,
    expanded_dirs: &std::collections::HashSet<PathBuf>,
    show_hidden: bool,
    sort: Sort,
    out: &mut Vec<Entry>,
) -> Result<()> {
    let mut children: Vec<ChildMeta> = std::fs::read_dir(dir)?
        .filter_map(|r| r.ok())
        .map(|e| {
            let ft = e.file_type().ok();
            (e.path(), ft)
        })
        .filter(|(p, _)| {
            if show_hidden {
                return true;
            }
            !p.file_name()
                .and_then(|n| n.to_str())
                .map(|n| n.starts_with('.'))
                .unwrap_or(false)
        })
        .map(|(p, ft)| child_meta(p, ft, sort))
        .collect();

    children.sort_by(|a, b| sort_cmp(a, b, sort));

    for c in children {
        let expanded = c.is_dir && expanded_dirs.contains(&c.path);
        out.push(Entry {
            path: c.path.clone(),
            is_dir: c.is_dir,
            depth,
            expanded,
        });
        if expanded {
            build_dir(&c.path, depth + 1, expanded_dirs, show_hidden, sort, out)?;
        }
    }
    Ok(())
}

/// Recursively collect files/directories under `root` (the population for filtering). Hidden ones are excluded via `show_hidden`,
/// and symlink directories are not descended into (to prevent loops). The scan count is capped as a cost limit.
/// The return value is in ascending path order (grouped per directory). Each Entry is flat with depth=0 and expanded=false.
fn collect_all(root: &Path, show_hidden: bool) -> Vec<Entry> {
    const CAP: usize = 50_000;
    let mut out = Vec::new();
    let mut stack = vec![root.to_path_buf()];
    while let Some(dir) = stack.pop() {
        if out.len() >= CAP {
            break;
        }
        let Ok(rd) = std::fs::read_dir(&dir) else {
            continue;
        };
        for path in rd.filter_map(|r| r.ok()).map(|e| e.path()) {
            if out.len() >= CAP {
                break;
            }
            let hidden = path
                .file_name()
                .and_then(|n| n.to_str())
                .map(|n| n.starts_with('.'))
                .unwrap_or(false);
            if hidden && !show_hidden {
                continue;
            }
            // シンボリックリンクの dir には潜らない(循環回避)。is_dir はリンク先を辿るので別途判定。
            let is_symlink = std::fs::symlink_metadata(&path)
                .map(|m| m.file_type().is_symlink())
                .unwrap_or(false);
            let is_dir = path.is_dir();
            out.push(Entry {
                path: path.clone(),
                is_dir,
                depth: 0,
                expanded: false,
            });
            if is_dir && !is_symlink {
                stack.push(path);
            }
        }
    }
    out.sort_by(|a, b| a.path.cmp(&b.path));
    out
}

#[cfg(test)]
mod tests;