rootle 0.8.4

//! Root: mode stack, action dispatch, component tree (PLAN.md §6).
//! GitHub calls run on worker threads (blocking reqwest); results return
//! over an mpsc channel as `AppEvent`s, drained once per event-loop tick.
//!
//! `App::with` constructs an **offline** app for tests: no workers are
//! spawned; backend outcomes are injected via `handle_action`.

use crate::action::Action;
use crate::components::browser::Browser;
use crate::components::clone_wizard::CloneWizard;
use crate::components::command_line::CommandLine;
use crate::components::consent_popup::ConsentPopup;
use crate::components::global_search::{GlobalSearch, SearchKind};
use crate::components::keybinds_popup::KeybindsPopup;
use crate::components::modeline::Modeline;
use crate::components::pane::EntryKind;
use crate::components::refs_popup::RefsPopup;
use crate::components::search_popup::SearchPopup;
use crate::components::settings_popup::SettingsPopup;
use crate::components::vim_input::Outcome;
use crate::config::Config;
use crate::event::{AppEvent, AppTx};
use crate::highlight::Highlighter;
use crate::keymap;
use crate::mode::Mode;
use crate::provider::{self, Provider};
use crate::state::State;
use crate::theme::{BorderShape, Theme};
use ratatui::Frame;
use ratatui::crossterm::event::KeyEvent;
use ratatui::layout::{Constraint, Direction, Layout, Rect};
use ratatui::widgets::Paragraph;
use std::sync::Arc;

mod workers;

pub struct App {
    mode: Mode,
    browser: Browser,
    popup: Option<SearchPopup>,
    /// Full-screen global search view (␣ f / ␣ g); replaces the
    /// browser while open (plans/0002-v0.2).
    search_view: Option<GlobalSearch>,
    /// Overlays (plans/0003/0004): at most one at a time.
    help: Option<KeybindsPopup>,
    command_line: Option<CommandLine>,
    settings: Option<SettingsPopup>,
    wizard: Option<CloneWizard>,
    /// Revision switcher overlay (plans/0016 M1a mock) and the
    /// revision committed when it opened — Esc reverts the crumb.
    refs_popup: Option<RefsPopup>,
    refs_baseline: Option<String>,
    /// 0019 M2: declared-but-missing provider — the consent popup
    /// owns startup until answered (y installs, n degrades honestly).
    consent: Option<ConsentPopup>,
    /// 0019 M2: sticky degradation notice (declared provider
    /// unavailable — the honest-channel surface). Transient statuses
    /// overlay it; nothing clears it for the session.
    degraded: Option<String>,
    /// 0019 polish: last-commit memo for the preview band, keyed
    /// (repo, path, ref). The band is ambient — re-selects never
    /// refetch; the first preview of a file spawns one `log(limit=1)`.
    last_commits: std::collections::HashMap<(String, String, String), crate::provider::LogEntry>,
    /// closes (history from blame, find from preview).
    history_return: Option<Mode>,
    find_return: Option<Mode>,
    /// A newer release tag when the startup check found one (0017 M3)
    /// — the modeline's `↑ vX.Y.Z` chip.
    update_tag: Option<String>,
    modeline: Modeline,
    theme: Theme,
    config: Config,
    state: State,
    tx: AppTx,
    provider: Arc<dyn Provider>,
    highlighter: Highlighter,
    /// The syntax roles the highlighter + blob cache are styled with
    /// (restyle trigger on theme switch).
    highlight_syntax: crate::theme::Syntax,
    /// Generation counter on search submissions; stale results dropped.
    search_gen: u64,
    /// Same for the global search view (find/grep workers).
    view_gen: u64,
    /// sha of the lazy hit-context fetch in flight (plans/0006 §1) —
    /// dedupes repeat selections and names the cancel target.
    pending_context_sha: Option<String>,
    /// Cursor-rest debounce generation (plans/0008 §3): bumped on
    /// every context request; a timer thread fires only if its
    /// generation is still current when the cursor rests.
    context_debounce_gen: std::sync::Arc<std::sync::atomic::AtomicU64>,
    /// One-line status shown in the modeline (searching/loading/error).
    status: Option<String>,
    /// Offline apps (tests) never spawn workers.
    offline: bool,
    pub should_quit: bool,
    /// Reserved for the editor-resume path (milestone 6): the only
    /// legitimate full `terminal.clear()` trigger (PLAN.md §9).
    pub force_redraw: bool,
    /// A prepared editor invocation; the main loop runs it while the
    /// terminal is suspended, then forces a full redraw.
    pending_editor: Option<crate::editor::EditorJob>,
    /// Queued yank (␣ y): the main loop writes it to the clipboard
    /// outside the draw path (plans/0003 §1).
    pending_clipboard: Option<String>,
}

/// Render a provider error for the status line (plans/0008 §2):
/// auth gets a recovery hint, throttling gets its advertised backoff,
/// everything else is yesterday's plain message.
pub(crate) fn provider_status(error: &crate::provider::ProviderError) -> String {
    use crate::provider::ErrorKind;
    match error.kind {
        ErrorKind::Auth => format!(
            "auth failed: {} — refresh provider credentials",
            error.message
        ),
        ErrorKind::RateLimited => match error.retry_after {
            Some(d) => format!("provider throttled — retry in {}s", d.as_secs()),
            None => format!("provider throttled: {}", error.message),
        },
        _ => error.message.clone(),
    }
}

/// Forge chip text for the modeline: `[provider] name` when set, else
/// the provider's self-reported name (`stdio:name` → `name`).
fn forge_name(config: &Config, provider: &dyn Provider) -> String {
    config
        .provider
        .name
        .clone()
        .unwrap_or_else(|| provider.name().trim_start_matches("stdio:").to_owned())
}

impl App {
    /// Fetch the open history lens' commits (v1.5): the previewed
    /// file's log at the browsed revision.
    fn open_history_fetch(&mut self) {
        let target = self
            .browser
            .repo_coords()
            .zip(self.browser.history_path().map(str::to_string));
        if let Some(((owner, name), path)) = target {
            let ref_ = self.browser.current_ref().map(str::to_string);
            self.spawn_log(format!("{owner}/{name}"), path, ref_);
        }
    }

    pub fn new(tx: AppTx, config: Config, theme: Theme) -> Self {
        let (provider, outcome) = provider::build(&config);
        let mut app = Self::build(State::load(), tx, provider, false, config, theme);
        match outcome {
            provider::BuildOutcome::Ready => {}
            provider::BuildOutcome::Warn(warning) => app.status = Some(warning),
            // 0019 M2: a declared provider is missing — ask, never
            // silently download-and-run. github carries the session
            // while the popup is up.
            provider::BuildOutcome::Missing(decl) => {
                app.consent = Some(ConsentPopup::new(decl));
            }
        }
        // 0017 M3 / 0018 M2: the 24h-cached update notice — never
        // offline, never blocking, silent on failure; CI, dumb
        // terminals, and piped stdout never check at all.
        if !app.offline && app.config.update.check && crate::update::check_allowed() {
            app.spawn_update_check();
        }
        // Warm the repos level for the initially selected org.
        if let Some(org) = app.browser.selected_org() {
            app.handle_action(Action::LoadOrgRepos(org));
        }
        app
    }

    /// Offline, state-injectable constructor for tests.
    pub fn with(state: State, tx: AppTx) -> Self {
        Self::build(
            state,
            tx,
            provider::offline(),
            true,
            Config::default(),
            Theme::catppuccin_mocha(),
        )
    }

    fn build(
        state: State,
        tx: AppTx,
        provider: Arc<dyn Provider>,
        offline: bool,
        config: Config,
        theme: Theme,
    ) -> Self {
        // Launch flow: the repo search popup opens automatically only
        // for a fresh install (no repos in state yet). With recents,
        // the browser opens directly; ␣ s still offers resume via the
        // prefilled last repo.
        let forge = forge_name(&config, provider.as_ref());
        let icon = config.provider.icon.clone().or_else(|| provider.icon());
        let popup = if state.recent_repos.is_empty()
            && state.recent_orgs.is_empty()
            && state.last_repo.is_none()
        {
            let mut p = SearchPopup::with_prefill(state.last_repo.as_deref());
            p.forge = forge.clone();
            Some(p)
        } else {
            None
        };
        App {
            mode: Mode::Browse,
            browser: Browser::new(&state.recent_orgs, &provider.default_orgs()),
            popup, // opens on launch only for a fresh state
            search_view: None,
            help: None,
            command_line: None,
            settings: None,
            wizard: None,
            refs_popup: None,
            refs_baseline: None,
            // 0019 M2: declared-but-missing provider — the consent
            consent: None,
            degraded: None,
            last_commits: std::collections::HashMap::new(),
            history_return: None,
            find_return: None,
            update_tag: None,
            modeline: Modeline {
                forge,
                icon,
                context: String::new(),
                status: None,
                update_tag: None,
            },
            theme,
            config,
            state,
            tx,
            provider,
            highlighter: Highlighter::new(&theme),
            // The syntax roles the highlighter + blob cache are styled
            // with; compared against the effective theme to trigger
            // restyle (settings live preview / commit).
            highlight_syntax: theme.syntax,
            search_gen: 0,
            view_gen: 0,
            pending_context_sha: None,
            context_debounce_gen: std::sync::Arc::new(std::sync::atomic::AtomicU64::new(0)),
            status: None,
            offline,
            should_quit: false,
            force_redraw: false,
            pending_editor: None,
            pending_clipboard: None,
        }
    }

    fn effective_mode(&self) -> Mode {
        if self.command_line.is_some() {
            return Mode::Insert;
        }
        if let Some(settings) = &self.settings {
            return settings.effective_mode();
        }
        if self.help.is_some() || self.wizard.is_some() {
            return Mode::Browse;
        }
        if let Some(view) = &self.search_view {
            // The leader layer can be raised over the view (␣ from the
            // results) — it owns the keys and the modeline while up.
            if self.mode == Mode::Leader {
                return Mode::Leader;
            }
            return view.effective_mode();
        }
        match &self.popup {
            Some(popup) => popup.effective_mode(),
            None => self.mode,
        }
    }

    pub fn handle_key(&mut self, key: KeyEvent) {
        let action = self.dispatch(key);
        self.handle_action(action);
    }

    /// Worker outcomes from the event channel.
    pub fn handle_app_event(&mut self, event: AppEvent) {
        match event {
            AppEvent::SearchResults { gen_id, items } => {
                if gen_id != self.search_gen {
                    return; // stale submission
                }
                self.status = None;
                if let Some(popup) = &mut self.popup {
                    popup.update(&Action::SearchResults { items });
                }
            }
            AppEvent::SearchFailed { gen_id, error } => {
                if gen_id != self.search_gen {
                    return;
                }
                self.status = None;
                if let Some(popup) = &mut self.popup {
                    popup.update(&Action::SearchFailed { error });
                }
            }
            AppEvent::OrgReposLoaded { org, repos } => {
                self.status = None;
                self.browser.org_repos_loaded(&org, repos);
            }
            AppEvent::OrgReposFailed { org, error } => {
                self.status = Some(format!("{org}: {}", provider_status(&error)));
            }
            AppEvent::TreeLoaded {
                owner,
                name,
                entries,
                truncated,
                branch,
            } => {
                self.handle_action(Action::TreeLoaded {
                    owner,
                    name,
                    entries,
                    truncated,
                    branch,
                });
            }
            AppEvent::BlobLoaded { sha, name, bytes } => {
                self.handle_action(Action::BlobLoaded { sha, name, bytes });
            }
            AppEvent::BlobFailed { sha, error } => {
                self.handle_action(Action::BlobFailed { sha, error });
            }
            AppEvent::TreeFailed { owner, name, error } => {
                self.handle_action(Action::TreeFailed { owner, name, error });
            }
            AppEvent::GlobalSearchDelta { gen_id, hits } => {
                if gen_id != self.view_gen {
                    return; // stale batch — a newer submission owns the view
                }
                let Some(view) = &self.search_view else {
                    return;
                };
                let (kind, query) = (view.kind(), view.query.value());
                let hits = hits
                    .into_iter()
                    .map(crate::components::global_search::SearchHit::from_raw)
                    .collect();
                let hits = self.finish_hits(hits, kind, &query);
                if let Some(view) = &mut self.search_view {
                    view.update(&Action::GlobalSearchDelta { hits });
                }
                // Live count while the stream runs.
                if let Some(view) = &self.search_view {
                    self.status = Some(format!(
                        "searching {}… {} hits",
                        self.modeline.forge,
                        view.hit_count()
                    ));
                }
            }
            AppEvent::GlobalSearchResults {
                gen_id,
                hits,
                clipped,
                index,
                client_filtered,
                unfiltered,
            } => {
                if gen_id != self.view_gen {
                    return; // stale submission
                }
                self.status = None;
                let Some(view) = &self.search_view else {
                    return;
                };
                let (kind, query) = (view.kind(), view.query.value());
                let hits = hits
                    .into_iter()
                    .map(crate::components::global_search::SearchHit::from_raw)
                    .collect();
                let hits = self.finish_hits(hits, kind, &query);
                if let Some(view) = &mut self.search_view {
                    view.update(&Action::GlobalSearchResults {
                        hits,
                        clipped,
                        index,
                        client_filtered,
                        unfiltered,
                    });
                }
                // Bare selected hit (beyond the eager preview cap): ask
                // for its context lazily (plans/0006 §1).
                let request = self
                    .search_view
                    .as_ref()
                    .and_then(|view| view.context_request());
                if let Some(action) = request {
                    self.handle_action(action);
                }
            }
            AppEvent::GlobalSearchFailed { gen_id, error } => {
                if gen_id != self.view_gen {
                    return;
                }
                self.status = None;
                if let Some(view) = &mut self.search_view {
                    view.update(&Action::GlobalSearchFailed { error });
                }
            }
            AppEvent::HitContextDebounceFired {
                timer_gen,
                hit,
                query,
            } => {
                self.handle_action(Action::HitContextDebounceFired {
                    timer_gen,
                    hit,
                    query,
                });
            }
            AppEvent::HitContextMissing { gen_id, sha } => {
                if gen_id != self.view_gen {
                    return; // view moved on
                }
                self.handle_action(Action::HitContextMissing { sha });
            }
            AppEvent::HitContextFailed { gen_id, sha, error } => {
                if gen_id != self.view_gen {
                    return;
                }
                self.handle_action(Action::HitContextFailed { sha, error });
            }
            AppEvent::HitContextLoaded {
                gen_id,
                repo,
                path,
                sha,
                line,
                preview,
                match_count,
                query,
            } => {
                if gen_id != self.view_gen {
                    return; // view moved on
                }
                if self.pending_context_sha.as_deref() == Some(sha.as_str()) {
                    self.pending_context_sha = None;
                }
                let Some(view) = &self.search_view else {
                    return;
                };
                let kind = view.kind();
                let mut hits = vec![crate::components::global_search::SearchHit::plain(
                    &repo,
                    &path,
                    line,
                    preview,
                    match_count,
                    String::new(),
                )];
                hits = self.finish_hits(hits, kind, &query);
                let styled = hits.pop().expect("one hit");
                let action = Action::HitContextLoaded {
                    repo,
                    path,
                    sha,
                    line,
                    preview: styled.preview,
                    match_count,
                };
                if let Some(view) = &mut self.search_view {
                    view.update(&action);
                }
            }
            AppEvent::HitFileLoaded {
                gen_id,
                repo,
                path,
                sha,
                bytes,
            } => {
                if gen_id != self.view_gen {
                    return; // view moved on — drop the stale blob
                }
                // 0019 polish: the expanded pane's band rides the same
                // last-commit memo as the miller preview.
                let band_ctx = {
                    let branch = self
                        .search_view
                        .as_ref()
                        .and_then(|v| v.expanded_branch())
                        .unwrap_or_default();
                    self.last_commits
                        .get(&(repo.clone(), path.clone(), branch))
                        .map(|e| crate::components::preview::BandContext {
                            sha: e.sha.clone(),
                            subject: e.subject.clone(),
                            author: e.author.clone(),
                            date: e.date.clone(),
                        })
                };
                // Sanitize + highlight at the boundary, on the UI
                // thread (PLAN.md §9) — same rule as every blob.
                let action = if crate::sanitize::is_binary(&bytes) {
                    Action::HitFileFailed {
                        error: crate::provider::ProviderError::other("binary file"),
                        sha,
                    }
                } else {
                    let text = crate::sanitize::sanitize(&bytes);
                    let mut lines = self.highlighter.highlight(&path, &text);
                    let lang = self.highlighter.language(&path);
                    // 0019: the expanded pane wears the same match chips
                    // as the results list — a boundary-aware chip so a
                    // match straddling syntax spans (half in a comment)
                    // still shows.
                    if let Some(view) = &self.search_view
                        && view.is_grep()
                    {
                        let needle = view.query_text().to_lowercase();
                        if !needle.is_empty() {
                            let (bg, fg) =
                                (self.theme.semantic.search_match, self.theme.semantic.crust);
                            for line in &mut lines {
                                crate::components::global_search::chip_line(line, &needle, bg, fg);
                            }
                        }
                    }
                    Action::HitFileLoaded {
                        repo: repo.clone(),
                        path: path.clone(),
                        sha,
                        lang,
                        lines,
                    }
                };
                // Memo miss on the expanded hit: spawn the one-shot
                // fetch (log-capable providers only; ambient).
                if band_ctx.is_none()
                    && !self.offline
                    && let Some(view) = &self.search_view
                    && let Some(branch) = view.expanded_branch()
                {
                    self.spawn_last_commit(repo.clone(), path.clone(), Some(branch.clone()));
                }
                if let Some(view) = &mut self.search_view {
                    view.expanded_set_band(&path, band_ctx);
                    view.update(&action);
                }
            }
            AppEvent::HitFileFailed { gen_id, sha, error } => {
                if gen_id != self.view_gen {
                    return;
                }
                // Auth/throttle surface a status line; other kinds
                // stay quiet — the pane itself shows the error
                // (same rule as the lazy context, plans/0008 §2).
                use crate::provider::ErrorKind;
                if matches!(error.kind, ErrorKind::Auth | ErrorKind::RateLimited) {
                    self.status = Some(provider_status(&error));
                }
                if let Some(view) = &mut self.search_view {
                    view.update(&Action::HitFileFailed { sha, error });
                }
            }
            AppEvent::CloneExpanded { repos, errors } => {
                if repos.is_empty() {
                    self.status = Some(if errors.is_empty() {
                        "nothing to clone".into()
                    } else {
                        format!("no repos: {}", errors.join("; "))
                    });
                } else {
                    if !errors.is_empty() {
                        self.status = Some(format!("some orgs failed: {}", errors.join("; ")));
                    }
                    let cwd = std::env::current_dir().unwrap_or_default();
                    self.wizard = Some(CloneWizard::new(repos, cwd));
                }
            }
            AppEvent::CloneDone { ok, failed } => {
                let mut status = format!(
                    "cloned {} repo{}",
                    ok.len(),
                    if ok.len() == 1 { "" } else { "s" }
                );
                if !failed.is_empty() {
                    status.push_str(&format!(
                        ", {} failed ({} …)",
                        failed.len(),
                        failed[0].1.chars().take(40).collect::<String>()
                    ));
                }
                self.status = Some(status);
            }
            // v1.5 revision lenses (plans/0016 M1).
            AppEvent::RefsLoaded { repo: _, refs } => {
                if let Some(popup) = &mut self.refs_popup {
                    popup.set_refs(refs);
                }
            }
            AppEvent::RefsFailed { repo: _, error } => {
                self.status = Some(provider_status(&error));
            }
            AppEvent::LogLoaded {
                path,
                entries,
                truncated,
            } => {
                if self.browser.history_path() == Some(path.as_str()) {
                    self.browser.history_loaded(entries, truncated);
                }
            }
            AppEvent::LogFailed { path: _, error } => {
                self.status = Some(provider_status(&error));
            }
            AppEvent::BlameLoaded { path, ranges } => {
                if let Some(view) = &mut self.search_view
                    && view.blame_loading_for(&path)
                {
                    view.blame_store(path, ranges);
                } else {
                    self.browser.blame_store(path, ranges);
                }
            }
            AppEvent::LastCommitLoaded { repo, path, entry } => {
                if let Some(entry) = entry {
                    // Compact at the boundary: 7-char sha, date-only
                    // — the band is a header, not a ledger.
                    let ctx = crate::components::preview::BandContext {
                        sha: entry.sha.chars().take(7).collect(),
                        subject: entry.subject.clone(),
                        author: entry.author.clone(),
                        date: entry
                            .date
                            .split('T')
                            .next()
                            .unwrap_or(&entry.date)
                            .to_string(),
                    };
                    let ref_ = self
                        .browser
                        .current_ref()
                        .map(str::to_string)
                        .unwrap_or_default();
                    self.last_commits
                        .insert((repo.clone(), path.clone(), ref_), entry);
                    // Dress whichever surface is showing this file now:
                    // the miller preview (not at-commit) and/or the
                    // search pane's expanded hit.
                    if !self.browser.at_commit_view()
                        && self.browser.selected_file().is_some_and(|(p, _)| p == path)
                    {
                        self.browser
                            .preview
                            .set_band(Some(path.clone()), Some(ctx.clone()));
                    }
                    if let Some(view) = &mut self.search_view {
                        view.expanded_set_band(&path, Some(ctx));
                    }
                }
            }
            AppEvent::BlameFailed { path, error } => {
                if let Some(view) = &mut self.search_view
                    && view.blame_loading_for(&path)
                {
                    view.blame_clear();
                }
                self.status = Some(provider_status(&error));
            }
            AppEvent::BlobAtLoaded {
                path,
                ref_,
                sha,
                bytes,
                subject,
                author,
                date,
            } => {
                // Open-at-commit: style like every blob, but show it
                // directly — the tree cursor still names the
                // present-day blob, so refresh_preview would revert it.
                if crate::sanitize::is_binary(&bytes) {
                    self.status = Some("binary file at that commit".into());
                    return;
                }
                let text = crate::sanitize::sanitize(&bytes);
                let short: String = ref_.chars().take(7).collect();
                // The title carries the commit marker; highlighting and
                // language detection read the real path — "main.rs @
                // 42ec959" has no known extension (the demo caught the
                // unhighlighted frame).
                let name = format!("{path} @ {short}");
                let lines = self.highlighter.highlight(&path, &text);
                let lang = self.highlighter.language(&path);
                let band = crate::components::preview::BandContext {
                    sha: short,
                    subject,
                    author,
                    date,
                };
                self.browser
                    .show_at_commit(&sha, &name, &lang, text, lines, Some(band));
                // The lens' work is done — the commit's content is up.
                self.browser.close_history();
                self.history_return = Some(Mode::Preview);
                self.mode = Mode::Preview;
                self.status = None;
            }
            AppEvent::BlobAtFailed { path: _, error } => {
                self.status = Some(provider_status(&error));
            }
            AppEvent::UpdateAvailable { tag, toast } => {
                self.update_tag = Some(tag.clone());
                // 0018 M2: the toast nags once a day and never steals
                // the status line from real work — the chip is the
                // persistent channel.
                if toast && self.status.is_none() {
                    self.status = Some(format!("rootle {tag} is out — run `rootle update`"));
                }
            }
            // 0019 M2: the consent install landed — hot-swap the
            // provider, drop the popup, say so.
            AppEvent::DeclarationInstalled { name } => {
                self.consent = None;
                self.degraded = None;
                match provider::spawn_installed(&self.config, &name) {
                    Ok(p) => {
                        self.provider = p;
                        self.status = Some(format!("{name} ready"));
                    }
                    Err(e) => {
                        let note = format!("{name} unavailable: {e} — browsing github");
                        self.degraded = Some(note.clone());
                        self.status = Some(note);
                    }
                }
            }
            AppEvent::DeclarationFailed { name, error } => {
                // Honest degraded mode — the popup shows the error
                // until dismissed, then the notice goes sticky.
                let note = format!("{name} unavailable: {error} — browsing github");
                self.degraded = Some(note.clone());
                if let Some(popup) = &mut self.consent {
                    popup.set_state(crate::action::DeclarationState::Failed(error));
                } else {
                    self.status = Some(note);
                }
            }
        }
    }

    fn dispatch(&mut self, key: KeyEvent) -> Action {
        // Overlays capture keys, topmost first — the consent popup is
        // the very top: a pending trust decision outranks everything.
        if let Some(consent) = &mut self.consent {
            return consent.handle_key(key);
        }
        if let Some(wizard) = &mut self.wizard {
            return wizard.handle_key(key);
        }
        if let Some(settings) = &mut self.settings {
            return settings.handle_key(key);
        }
        if let Some(help) = &mut self.help {
            return help.handle_key(key);
        }
        if let Some(refs) = &mut self.refs_popup {
            return refs.handle_key(key);
        }
        if let Some(command_line) = &mut self.command_line {
            return command_line.handle_key(key);
        }
        if let Some(view) = &mut self.search_view {
            // While the leader layer is up, it owns the keys — the
            // view regains them on the action that follows.
            if self.mode == Mode::Leader {
                return keymap::leader(key.code);
            }
            return view.handle_key(key);
        }
        if let Some(popup) = &mut self.popup {
            return popup.handle_key(key);
        }
        match self.mode {
            Mode::Browse => keymap::browsing(key.code),
            Mode::Visual => keymap::visual(key.code),
            Mode::Search => match self.browser.filter_input.handle_key(key) {
                Outcome::Changed => Action::Noop, // filter applied below
                Outcome::Submitted => Action::CommitFilter,
                Outcome::Cancelled => Action::ClearFilter,
                Outcome::Noop => Action::Noop,
            },
            Mode::Find => match self.browser.find_input.handle_key(key) {
                Outcome::Changed => Action::UpdateFind,
                Outcome::Submitted => Action::CommitFind,
                Outcome::Cancelled => Action::CancelFind,
                Outcome::Noop => Action::Noop,
            },
            Mode::Leader => keymap::leader(key.code),
            Mode::History => {
                // An active `/` session owns the keys until commit.
                if self.browser.history_filtering() {
                    self.browser.history_filter_key(key);
                    Action::Noop
                } else {
                    keymap::history(key.code)
                }
            }
            Mode::Preview => self.browser.preview_key(key),
            _ => Action::Noop,
        }
    }

    pub fn handle_action(&mut self, action: Action) {
        match action {
            Action::Quit | Action::LeaderQuit => {
                self.state.last_path = Some(self.browser.dir_path());
                self.state.save();
                self.should_quit = true;
            }
            Action::ClosePopup => {
                trace("ClosePopup");
                // Topmost overlay first; the search popup last.
                if self.wizard.take().is_some()
                    || self.settings.take().is_some()
                    || self.help.take().is_some()
                    || self.command_line.take().is_some()
                {
                    return;
                }
                if self.refs_popup.take().is_some() {
                    // Revisions switcher cancelled: the live preview
                    // reverts to the committed revision.
                    let baseline = self.refs_baseline.clone();
                    self.browser.set_current_ref(baseline);
                    return;
                }
                self.popup = None;
                self.mode = Mode::Browse;
            }
            Action::SearchSubmitted(_) => {
                self.search_gen += 1;
                self.provider.advise_cancel(); // superseded in-flight work
                self.status = Some(format!("searching {}…", self.modeline.forge));
                if let Some(popup) = &mut self.popup {
                    popup.update(&action);
                }
                if !self.offline {
                    self.spawn_search(self.search_gen);
                }
            }
            Action::SearchResults { .. } | Action::SearchFailed { .. } => {
                // Injected (tests) or misrouted worker outcomes.
                if let Some(popup) = &mut self.popup {
                    popup.update(&action);
                }
                self.status = None;
            }
            Action::RepoSelected { owner, name } => {
                trace(&format!("RepoSelected {owner}/{name}"));
                self.state.record_repo(&owner, &name);
                self.state.save();
                self.browser.set_repo(&owner, &name);
                self.popup = None;
                self.mode = Mode::Browse;
                self.handle_action(Action::LoadRepoTree { owner, name });
            }
            Action::OrgSelected(org) => {
                trace(&format!("OrgSelected {org}"));
                self.state.record_org(&org);
                self.state.save();
                self.browser.select_org(&org);
                self.popup = None;
                self.mode = Mode::Browse;
                self.handle_action(Action::LoadOrgRepos(org));
            }
            Action::LoadOrgRepos(org) => {
                self.status = Some(format!("loading {org}…"));
                if !self.offline {
                    self.spawn_org_repos(org);
                }
            }
            Action::OrgReposLoaded { org, repos } => {
                self.status = None;
                self.browser.org_repos_loaded(&org, repos);
            }
            Action::OrgReposFailed { org, error } => {
                self.status = Some(format!("{org}: {}", provider_status(&error)));
            }
            Action::LoadRepoTree { owner, name } => {
                self.status = Some(format!("loading {owner}/{name} tree…"));
                if !self.offline {
                    self.spawn_tree(owner, name);
                }
            }
            Action::TreeLoaded {
                owner,
                name,
                entries,
                truncated,
                branch,
            } => {
                self.status = None;
                self.browser
                    .tree_loaded(&owner, &name, entries, truncated, branch);
            }
            Action::TreeFailed { owner, name, error } => {
                self.status = Some(format!("{owner}/{name}: {}", provider_status(&error)));
            }
            Action::LoadBlob { sha, name } => {
                if !self.offline {
                    self.spawn_blob(sha, name);
                }
            }
            Action::BlobLoaded { sha, name, bytes } => {
                // Sanitize at the boundary, highlight once, cache in
                // the browser (PLAN.md §9).
                if crate::sanitize::is_binary(&bytes) {
                    self.browser.blob_failed(&sha, "binary file");
                    return;
                }
                let text = crate::sanitize::sanitize(&bytes);
                let lines = self.highlighter.highlight(&name, &text);
                let lang = self.highlighter.language(&name);
                self.browser.blob_loaded(&sha, &name, &lang, text, lines);
                self.band_apply_or_fetch();
            }
            Action::BlobFailed { sha, error } => {
                self.status = Some(provider_status(&error));
                self.browser.blob_failed(&sha, &error.message);
            }
            Action::HitContextFailed { sha: _, error } => {
                // Auth/throttle surface; anything else stays quiet —
                // the bare path remains and revisit retries (§2).
                use crate::provider::ErrorKind;
                if matches!(error.kind, ErrorKind::Auth | ErrorKind::RateLimited) {
                    self.status = Some(provider_status(&error));
                }
            }
            Action::Leader => self.mode = Mode::Leader,
            Action::KeybindsPopup => self.help = Some(KeybindsPopup::new()),
            Action::CommandLine => self.command_line = Some(CommandLine::new()),
            Action::RunCommand(name) => {
                self.command_line = None;
                match name.as_str() {
                    "settings" => {
                        let themes = Theme::available_names();
                        self.settings = Some(SettingsPopup::new(&self.config, themes));
                    }
                    "clone" => {
                        let (repos, orgs) = self.clone_candidates();
                        if orgs.is_empty() {
                            let cwd = std::env::current_dir().unwrap_or_default();
                            // Direct selections carry no listing
                            // metadata (v1.4): bare names.
                            let repos = repos
                                .into_iter()
                                .map(crate::provider::RepoInfo::bare)
                                .collect();
                            self.wizard = Some(CloneWizard::new(repos, cwd));
                        } else {
                            self.status = Some(format!("expanding {} org(s)…", orgs.len()));
                            if !self.offline {
                                self.spawn_expand_clone(repos, orgs);
                            }
                        }
                    }
                    other => {
                        // `:42` jumps to line 42 in a file view — the
                        // zoomed preview submode or a search hit's
                        // expanded file pane (plans/0016 M1).
                        match other.parse::<u32>() {
                            Ok(line) if line > 0 => {
                                let jumped = if let Some(view) = &mut self.search_view {
                                    view.expanded_goto_line(line)
                                } else if self.browser.preview.text_line_count() > 0 {
                                    self.browser.preview.set_cursor_line(line);
                                    true
                                } else {
                                    false
                                };
                                if !jumped {
                                    self.status = Some(format!(":{other}: not in a file view"));
                                }
                            }
                            _ => self.status = Some(format!("unknown command: {other}")),
                        }
                    }
                }
            }
            Action::Visual => {
                self.mode = Mode::Visual;
                self.browser.enter_visual();
            }
            Action::ExitVisual => {
                self.mode = Mode::Browse;
                self.browser.exit_visual();
            }
            Action::ToggleSelect => self.browser.toggle_selected(),
            Action::LeaderReload => {
                self.mode = Mode::Browse;
                if let Some((owner, name)) = self.browser.repo_coords() {
                    // Conditional refetch: cheap when the ref ETag is
                    // still fresh (304), fresh tree when it moved.
                    self.handle_action(Action::LoadRepoTree { owner, name });
                    self.status = Some("reloading tree…".into());
                } else if let Some(org) = self.browser.selected_org() {
                    self.handle_action(Action::LoadOrgRepos(org));
                    self.status = Some("reloading org repos…".into());
                } else {
                    self.status = Some("nothing to reload".into());
                }
            }
            Action::DeleteMarked => {
                self.mode = Mode::Browse;
                let deleted = self.browser.delete_marked_orgs();
                if deleted.is_empty() {
                    self.status = Some("no marked orgs (mark orgs in VISUAL, ␣d)".into());
                } else {
                    // Keep persisted recents in sync.
                    self.state.recent_orgs.retain(|o| !deleted.contains(o));
                    if self
                        .state
                        .last_org
                        .as_deref()
                        .is_some_and(|o| deleted.iter().any(|d| d == o))
                    {
                        self.state.last_org = None;
                    }
                    self.state.save();
                    self.status = Some(format!("deleted {} org(s)", deleted.len()));
                }
            }
            Action::ClearMarks => {
                self.mode = Mode::Browse;
                self.browser.clear_marks();
                self.status = Some("marks cleared".into());
            }
            Action::LeaderRefs => {
                self.mode = Mode::Browse;
                if !self.provider.capabilities().refs {
                    self.status = Some("provider has no revision listing".into());
                } else if let Some((owner, name)) = self.browser.repo_coords() {
                    let current = self
                        .browser
                        .current_ref()
                        .or_else(|| self.browser.branch())
                        .unwrap_or("main")
                        .to_string();
                    self.refs_baseline = self.browser.current_ref().map(str::to_string);
                    self.refs_popup = Some(RefsPopup::new(&current));
                    self.spawn_refs(format!("{owner}/{name}"));
                } else {
                    self.status = Some("open a repo to switch revisions".into());
                }
            }
            Action::RefsPreview(name) => {
                // Live preview: the crumb follows the cursor (no fetch
                // until commit).
                self.browser.set_current_ref(Some(name));
            }
            Action::RefsCommit(name) => {
                self.refs_popup = None;
                self.refs_baseline = Some(name.clone());
                self.browser.set_current_ref(Some(name.clone()));
                self.status = Some(format!("switched to {name}"));
                // The ref is read at spawn — refetch the tree now.
                if let Some((owner, name)) = self.browser.repo_coords() {
                    self.handle_action(Action::LoadRepoTree { owner, name });
                }
            }
            Action::LeaderPreview => {
                self.mode = Mode::Browse;
                if self.browser.repo_coords().is_none() {
                    self.status = Some("open a repo first".into());
                } else {
                    self.mode = Mode::Preview;
                }
            }
            Action::PreviewCopy => {
                // GitHub's copy button: the visual selection, else the
                // cursor line — from whichever file pane is up.
                let target = if let Some(view) = &mut self.search_view {
                    view.expanded_copy_target()
                } else {
                    self.browser.preview.copy_target()
                };
                match target {
                    Some((text, n)) => {
                        self.pending_clipboard = Some(text);
                        self.status =
                            Some(format!("copied {n} line{}", if n == 1 { "" } else { "s" }));
                    }
                    None => self.status = Some("nothing to copy".into()),
                }
            }
            Action::ExitPreview => {
                // The commit-view ladder: Esc restores the present-day
                // blob first, exits the submode second.
                if self.browser.at_commit_view() {
                    self.browser.commit_view_close();
                } else {
                    self.mode = Mode::Browse;
                }
            }
            Action::BlameToggle => {
                // 0019 parity: the search view's expanded pane runs the
                // same lens at the hit's default branch.
                if let Some(view) = &mut self.search_view {
                    if view.blame_active() {
                        view.blame_clear();
                    } else if !self.provider.capabilities().blame {
                        self.status = Some("provider has no blame".into());
                    } else if !view.blame_toggle_on() {
                        self.status = Some("blame: preview is not a text file".into());
                    } else if let Some((repo, path, branch)) = view.blame_needed() {
                        view.blame_mark_loading(path.clone());
                        let ref_ = if branch.is_empty() {
                            None
                        } else {
                            Some(branch)
                        };
                        self.spawn_blame(repo, path, ref_);
                        self.status = Some("blame…".into());
                    }
                } else if self.browser.preview.blaming() {
                    self.browser.clear_blame();
                } else if !self.provider.capabilities().blame {
                    // Honest absence (Bitbucket has no blame API).
                    self.status = Some("provider has no blame".into());
                } else if !self.browser.blame_toggle_on() {
                    self.status = Some("blame: preview is not a text file".into());
                } else if let Some(path) = self.browser.blame_needed_for()
                    && let Some((owner, name)) = self.browser.repo_coords()
                {
                    self.browser.blame_mark_loading(path.clone());
                    let ref_ = self.browser.current_ref().map(str::to_string);
                    self.spawn_blame(format!("{owner}/{name}"), path, ref_);
                    self.status = Some("blame…".into());
                }
            }
            Action::PreviewEnter => {
                // Blaming: Enter opens the line's commit in the history
                // lens; otherwise Enter is the editor handoff.
                match self.browser.blame_line_sha() {
                    Some(sha) if self.provider.capabilities().log => {
                        if self.browser.open_history(Some(sha)) {
                            self.open_history_fetch();
                            self.history_return = Some(Mode::Preview);
                            self.mode = Mode::History;
                        }
                    }
                    _ => self.handle_action(Action::OpenSelected),
                }
            }
            Action::LeaderHistory => {
                let back = self.mode;
                self.mode = Mode::Browse;
                if !self.provider.capabilities().log {
                    self.status = Some("provider has no commit log".into());
                } else if self.browser.open_history(None) {
                    self.history_return = Some(if back == Mode::Preview {
                        Mode::Preview
                    } else {
                        Mode::Browse
                    });
                    self.open_history_fetch();
                    self.mode = Mode::History;
                } else {
                    self.status = Some("preview a file for its history".into());
                }
            }
            Action::HistoryFilterBegin => self.browser.history_begin_filter(),
            Action::HistoryYank => {
                // The permalink that never rots: the URL carries the
                // commit sha as its ref.
                let target = self.browser.repo_coords().zip(self.browser.history_pick());
                if let Some(((owner, name), (path, sha))) = target {
                    match self.provider.web_url(
                        &format!("{owner}/{name}"),
                        &path,
                        &sha,
                        None,
                        None,
                        true,
                    ) {
                        Ok(u) => {
                            self.pending_clipboard = Some(u.clone());
                            self.status = Some(format!("yanked {u}"));
                        }
                        Err(e) => self.status = Some(provider_status(&e)),
                    }
                }
            }
            Action::HistoryUp => self.browser.history_move(-1),
            Action::HistoryDown => self.browser.history_move(1),
            Action::HistoryOpen => {
                // Open the file at the picked commit — bytes land via
                // BlobAtLoaded; the restore point is noted there.
                let target = self.browser.repo_coords().zip(self.browser.history_pick());
                let entry = self.browser.history_pick_entry();
                if let (Some(((owner, name), (path, sha))), Some(entry)) = (target, entry) {
                    self.spawn_blob_at(
                        format!("{owner}/{name}"),
                        path,
                        sha,
                        entry.subject,
                        entry.author,
                        entry.date,
                    );
                    self.status = Some("opening at commit".into());
                }
            }
            Action::HistoryClose => {
                // The wizard ladder: a committed filter clears first,
                // the next Esc closes.
                if self.browser.history_esc() {
                    self.mode = self.history_return.take().unwrap_or(Mode::Browse);
                }
            }
            Action::LeaderYank => {
                // Mock stage (plans/0003 §1): toast the URL that would
                // be yanked; clipboard (OSC 52) wires up later.
                // From the leader layer it drops back to Browse; from
                // the preview submode (␣ p y) the pane stays focused.
                if self.mode == Mode::Leader {
                    self.mode = Mode::Browse;
                }
                // URLs come from the provider — no GitHub grammar
                // outside the GitHub impl (plans/0005).
                let url = if let Some(view) = &self.search_view {
                    view.yank_target().and_then(|t| {
                        self.provider
                            .web_url(&t.repo, &t.path, &t.branch, t.line, t.end, true)
                            .ok()
                    })
                } else if let Some((owner, repo)) = self.browser.repo_coords() {
                    // File under the cursor yanks the FILE (blob URL);
                    // otherwise the current directory (tree URL).
                    let (path, is_file) = match self.browser.selected_file() {
                        Some((file, _sha)) => (file, true),
                        None => (self.browser.dir_path(), false),
                    };
                    let branch = self.browser.branch().unwrap_or("");
                    // File yank anchors to the preview line cursor —
                    // or the visual range as `#L3-L7` (v1.5); dirs/orgs
                    // stay line-less.
                    let (line, end) = if is_file {
                        self.browser.yank_anchor()
                    } else {
                        (None, None)
                    };
                    self.provider
                        .web_url(
                            &format!("{owner}/{repo}"),
                            &path,
                            branch,
                            line,
                            end,
                            is_file,
                        )
                        .ok()
                } else {
                    self.browser
                        .selected_org()
                        .and_then(|org| self.provider.org_url(&org).ok())
                };
                match url {
                    Some(u) => {
                        self.pending_clipboard = Some(u.clone());
                        self.status = Some(format!("yanked {u}"));
                    }
                    None => self.status = Some("nothing to yank".into()),
                }
            }
            Action::LeaderSearch => {
                // Resume: prefill with the last repo — one Enter
                // re-runs the query back to where the user was.
                let mut popup = SearchPopup::with_prefill(self.state.last_repo.as_deref());
                popup.forge = self.modeline.forge.clone();
                self.popup = Some(popup);
                self.mode = Mode::Browse;
            }
            Action::LeaderFileFind | Action::LeaderGrep => {
                let kind = if action == Action::LeaderFileFind {
                    SearchKind::FileFind
                } else {
                    SearchKind::Grep
                };
                let repo = self
                    .browser
                    .repo_coords()
                    .map(|(owner, name)| format!("{owner}/{name}"));
                let org = self.browser.selected_org();
                let persisted_scope = self
                    .state
                    .search_scope
                    .as_deref()
                    .and_then(crate::components::global_search::Scope::from_stored);
                let mut view = GlobalSearch::new(
                    kind,
                    repo,
                    org,
                    persisted_scope,
                    self.state.search_extension.clone(),
                );
                // plans/0016 M1a: off the default branch, index-backed
                // search (GitHub) can't follow — the title says so.
                if let (Some(r), Some(b)) = (self.browser.current_ref(), self.browser.branch())
                    && r != b
                {
                    view.search_ref_note = Some(format!("search: {b} only"));
                }
                self.search_view = Some(view);
                self.mode = Mode::Browse;
            }
            Action::CloseSearchView => {
                self.search_view = None;
                self.mode = Mode::Browse;
            }
            Action::GlobalSearchSubmitted {
                ref kind,
                ref query,
                ref scope,
                ref extension,
            } => {
                // Persist last-used scope/extension (plans/0002 §6.4).
                if let Some(view) = &self.search_view {
                    self.state.search_scope = Some(view.scope().stored().to_string());
                    self.state.search_extension = Some(view.extension_value());
                    self.state.save();
                }
                self.view_gen += 1;
                self.provider.advise_cancel(); // superseded in-flight work
                self.pending_context_sha = None;
                if let Some(view) = &mut self.search_view {
                    view.update(&action);
                }
                if self.offline {
                    // Tests: inject the mock producer, same Action flow.
                    let hits =
                        crate::components::global_search::mock::hits(*kind, query, extension);
                    let hits = self.finish_hits(hits, *kind, query);
                    if let Some(view) = &mut self.search_view {
                        view.update(&Action::GlobalSearchResults {
                            hits,
                            clipped: false,
                            index: None,
                            client_filtered: 0,
                            unfiltered: vec![],
                        });
                    }
                    self.status = None;
                    // Bare selected hit (beyond the eager preview cap):
                    // ask for its context lazily (plans/0006 §1).
                    let request = self
                        .search_view
                        .as_ref()
                        .and_then(|view| view.context_request());
                    if let Some(action) = request {
                        self.handle_action(action);
                    }
                } else {
                    self.status = Some("searching code…".into());
                    self.spawn_view_search(
                        self.view_gen,
                        *kind,
                        query.clone(),
                        scope.clone(),
                        extension.clone(),
                    );
                }
            }
            Action::GlobalSearchResults { .. }
            | Action::GlobalSearchDelta { .. }
            | Action::GlobalSearchFailed { .. } => {
                if let Some(view) = &mut self.search_view {
                    view.update(&action);
                }
                self.status = None;
            }
            Action::LoadHitContext { hit, query } => {
                // Dedupe repeat selections of an in-flight fetch.
                if self.pending_context_sha.as_deref() == Some(hit.sha.as_str()) {
                    return;
                }
                if self.offline {
                    return; // tests inject context via Action directly
                }
                // Cursor-rest debounce (plans/0008 §3): 200ms rearmed
                // per selection change. Holding j through N hits costs
                // one provider call — the resting one — instead of N
                // requests plus N-1 advisory cancels.
                let timer_gen = self
                    .context_debounce_gen
                    .fetch_add(1, std::sync::atomic::Ordering::SeqCst)
                    + 1;
                let shared = self.context_debounce_gen.clone();
                let tx = self.tx.clone();
                let hit = *hit;
                std::thread::spawn(move || {
                    std::thread::sleep(std::time::Duration::from_millis(200));
                    if shared.load(std::sync::atomic::Ordering::SeqCst) == timer_gen {
                        let _ = tx.send(AppEvent::HitContextDebounceFired {
                            timer_gen,
                            hit,
                            query,
                        });
                    }
                });
            }
            Action::HitContextDebounceFired {
                timer_gen,
                hit,
                query,
            } => {
                // The timer thread already generation-checked; re-check
                // here — another request may have landed while the
                // event queued.
                if timer_gen
                    != self
                        .context_debounce_gen
                        .load(std::sync::atomic::Ordering::SeqCst)
                {
                    return;
                }
                if self.pending_context_sha.as_deref() == Some(hit.sha.as_str()) {
                    return;
                }
                // A different pending fetch is superseded — tell the
                // provider it can stop (v1.1).
                if self.pending_context_sha.is_some() {
                    self.provider.advise_cancel();
                }
                self.pending_context_sha = Some(hit.sha.clone());
                let gen_id = self.view_gen;
                self.spawn_hit_context(gen_id, hit, query);
            }
            Action::HitContextLoaded { .. } | Action::HitContextMissing { .. } => {
                if let Some(view) = &mut self.search_view {
                    view.update(&action);
                }
            }
            // Expanded file pane (plans/0012 M2): fetch the hit's
            // whole blob on a worker; the view shows a loading
            // placeholder until the styled lines land.
            Action::LoadHitFile { hit } => {
                if !self.offline {
                    let gen_id = self.view_gen;
                    self.spawn_hit_file(gen_id, *hit);
                }
            }
            Action::HitFileLoaded { .. } | Action::HitFileFailed { .. } => {
                if let Some(view) = &mut self.search_view {
                    view.update(&action);
                }
            }
            Action::OpenSearchHit(hit) => {
                if !hit.sha.is_empty() {
                    // Real hit: materialize the blob like the browser
                    // does (cache-first; the UI is about to suspend).
                    if hit.repo.contains('/') {
                        match crate::editor::prepare(
                            &self.config,
                            self.provider.as_ref(),
                            &hit.repo,
                            &hit.path,
                            &hit.sha,
                        ) {
                            Ok(job) => self.pending_editor = Some(job),
                            Err(message) => {
                                self.status = Some(format!("editor: {message}"));
                            }
                        }
                    }
                } else {
                    // Mock hits: materialize the stand-in body.
                    let slug = self
                        .search_view
                        .as_ref()
                        .map(|v| v.kind().slug())
                        .unwrap_or("hit");
                    match crate::editor::resolve_program(&self.config) {
                        Some(program) => {
                            // Content-address the mock body like a real blob.
                            use sha2::{Digest, Sha256};
                            // digest 0.11 dropped `LowerHex` on its output —
                            // render the hex by hand.
                            use std::fmt::Write as _;
                            let digest = Sha256::digest(hit.body.as_bytes());
                            let mut sha = String::with_capacity(digest.len() * 2);
                            for byte in digest {
                                let _ = write!(sha, "{byte:02x}");
                            }
                            match crate::editor::materialize(
                                "mock",
                                slug,
                                &sha,
                                &hit.path,
                                hit.body.as_bytes(),
                            ) {
                                Ok(file) => {
                                    let mut args =
                                        crate::editor::build_args(&program, &self.config);
                                    args.push(file.to_string_lossy().into_owned());
                                    self.pending_editor =
                                        Some(crate::editor::EditorJob { program, args });
                                }
                                Err(e) => self.status = Some(format!("editor: {e}")),
                            }
                        }
                        None => {
                            self.status =
                                Some("no editor found — set [editor].program or $EDITOR".into());
                        }
                    }
                }
            }
            Action::RunClone { repos, dest } => {
                if repos.is_empty() {
                    self.status = Some("nothing selected to clone".into());
                    self.wizard = None;
                } else {
                    let count = repos.len();
                    self.status = Some(format!("cloning {count} repos…"));
                    self.wizard = None;
                    if !self.offline {
                        self.spawn_clones(repos, dest);
                    }
                }
            }
            Action::ApplySettings(config) => {
                self.settings = None; // close the popup
                let theme_changed = config.theme != self.config.theme;
                let provider_changed = config.provider != self.config.provider;
                let ui_changed = config.ui != self.config.ui;
                self.config = config;
                // Hot reload: rebuild the palette (and chrome prefs);
                // every component reads Theme per render, so the
                // repaint is automatic.
                if theme_changed || ui_changed {
                    let name = self.config.theme.name.clone();
                    let border = BorderShape::parse(&self.config.ui.border).unwrap_or_default();
                    self.theme = Theme::load(&name)
                        .with_border(border)
                        .with_nerd_font(self.config.ui.nerd_font)
                        .with_separator(&self.config.ui.separator);
                }
                match self.config.save() {
                    Ok(()) => {
                        self.status = Some(if provider_changed {
                            "settings saved — provider applies after restart".into()
                        } else {
                            "settings saved".into()
                        })
                    }
                    Err(e) => self.status = Some(format!("settings: {e} (applied live)")),
                }
            }
            Action::EnterSearch => {
                self.browser.filter_input.submode = crate::components::vim_input::SubMode::Insert;
                self.mode = Mode::Search;
            }
            Action::CommitFilter => self.mode = Mode::Browse,
            Action::ClearFilter => {
                // BROWSE Esc precedence (plans/0007 §3): a committed
                // find clears first (:nohlsearch), then the list filter.
                // In SEARCH mode Esc keeps its cancel-the-session role.
                if self.mode == Mode::Browse && self.browser.preview.find_active() {
                    self.browser.preview.clear_find();
                } else {
                    self.browser.clear_filter();
                }
                self.mode = Mode::Browse;
            }
            Action::LeaderFindInFile => {
                // Reachable from the leader layer (Browse underneath)
                // and from the preview submode — FIND returns to
                // whichever raised it.
                let back = self.mode;
                self.find_return = Some(if back == Mode::Preview {
                    Mode::Preview
                } else {
                    Mode::Browse
                });
                self.mode = Mode::Browse; // leader layer down either way
                if self.browser.preview.findable() {
                    self.browser.find_input.clear();
                    self.browser.find_input.submode = crate::components::vim_input::SubMode::Insert;
                    self.browser.preview.begin_find();
                    self.mode = Mode::Find;
                } else {
                    self.mode = self.find_return.take().unwrap_or(Mode::Browse);
                    self.status = Some("find: preview is not a text file".into());
                }
            }
            Action::UpdateFind => {
                let query = self.browser.find_input.value();
                self.browser.preview.update_find(query);
            }
            Action::CommitFind => {
                self.mode = self.find_return.take().unwrap_or(Mode::Browse);
            }
            Action::CancelFind => {
                self.browser.preview.cancel_find();
                self.browser.find_input.clear();
                self.mode = self.find_return.take().unwrap_or(Mode::Browse);
            }
            Action::FindNext => {
                self.browser.preview.find_step(1);
            }
            Action::FindPrev => {
                self.browser.preview.find_step(-1);
            }
            Action::MoveUp
            | Action::MoveDown
            | Action::DrillIn
            | Action::DrillOut
            | Action::PreviewLineUp
            | Action::PreviewLineDown => {
                let follow = self.browser.update(&action);
                self.handle_action(follow);
            }
            Action::OpenSelected => {
                match self.browser.selected_kind() {
                    Some(EntryKind::File) => {
                        // Enter on a file → open in the editor (read-only,
                        // PLAN.md §12). The blocking blob fetch is fine:
                        // the UI is about to suspend anyway.
                        if let (Some((path, sha)), Some((owner, repo))) =
                            (self.browser.selected_file(), self.browser.repo_coords())
                        {
                            match crate::editor::prepare(
                                &self.config,
                                self.provider.as_ref(),
                                &format!("{owner}/{repo}"),
                                &path,
                                &sha,
                            ) {
                                Ok(job) => self.pending_editor = Some(job),
                                Err(message) => self.status = Some(format!("editor: {message}")),
                            }
                        }
                    }
                    Some(EntryKind::Dir | EntryKind::Repo | EntryKind::Org) => {
                        let follow = self.browser.update(&Action::DrillIn);
                        self.handle_action(follow);
                    }
                    None => {}
                }
            }

            // 0019 M2: the consent popup's answers.
            Action::DeclarationAccept => {
                if let Some(consent) = &mut self.consent {
                    let decl = consent.declaration().clone();
                    consent.set_state(crate::action::DeclarationState::Installing);
                    self.status = Some(format!("installing {}…", decl.name));
                    self.spawn_declared_install(decl);
                }
            }
            Action::DeclarationDecline => {
                if let Some(consent) = self.consent.take() {
                    let name = consent.declaration().name.clone();
                    // Honest degraded mode: the fallback is named, the
                    // declaration stays in the config, the retry is a
                    // command away — and the notice is sticky.
                    let note = format!(
                        "{name} not installed — browsing github (retry: rootle provider install {name})"
                    );
                    self.degraded = Some(note.clone());
                    self.status = Some(note);
                }
            }
            Action::DeclarationState(state) => {
                if let Some(consent) = &mut self.consent {
                    consent.set_state(state);
                }
            }
            Action::Noop => {}
        }

        // Incremental filter: re-apply on every SEARCH keystroke.
        if self.mode == Mode::Search {
            self.browser.apply_filter();
        }

        // Theme switches (settings live preview, then commit) restyle
        // the code the same frame the chrome recolors.
        self.sync_highlight_theme();

        // Any state change can leave a file under the cursor without its
        // blob (navigation, filter commit/clear, tree loads) — drain it
        // uniformly at the end of every route.
        self.maybe_load_blob();

        // Provider notices (a stdio child's successful restart) ride
        // the status line once (plans/0008 §5).
        if let Some(note) = self.provider.take_notice() {
            self.status = Some(note);
        }
    }

    /// The theme everything renders with: the settings popup's live
    /// preview while it's browsing palettes, the committed theme
    /// otherwise.
    fn effective_theme(&self) -> Theme {
        self.settings
            .as_ref()
            .and_then(SettingsPopup::preview_theme)
            .unwrap_or(self.theme)
    }

    /// Re-highlight cached blobs when the effective theme's syntax
    /// roles change. Cheap no-op per keystroke otherwise (SyntaxSet is
    /// loaded once; only the color table rebuilds).
    fn sync_highlight_theme(&mut self) {
        let theme = self.effective_theme();
        if theme.syntax == self.highlight_syntax {
            return;
        }
        self.highlighter.set_theme(&theme);
        self.browser.restyle_blobs(&self.highlighter);
        self.highlight_syntax = theme.syntax;
    }

    /// If the selected file's blob isn't loaded, fetch it.
    fn maybe_load_blob(&mut self) {
        if let Some((sha, name)) = self.browser.take_blob_request() {
            self.handle_action(Action::LoadBlob { sha, name });
        }
    }

    /// Hand the prepared editor job to the main loop (which owns the
    /// terminal and performs the suspend/resume dance).
    pub fn take_editor_job(&mut self) -> Option<crate::editor::EditorJob> {
        self.pending_editor.take()
    }

    /// Queued yank text, drained by the main loop once per iteration.
    pub fn take_clipboard(&mut self) -> Option<String> {
        self.pending_clipboard.take()
    }

    /// 0019 polish: the band's last-commit context for the file under
    /// preview — memo hit dresses immediately, a miss spawns the
    /// one-shot fetch (ambient; errors stay silent).
    fn band_apply_or_fetch(&mut self) {
        if !self.provider.capabilities().log || self.browser.at_commit_view() {
            return;
        }
        let Some((owner, name)) = self.browser.repo_coords() else {
            return;
        };
        let Some((path, _)) = self.browser.selected_file() else {
            return;
        };
        let ref_ = self
            .browser
            .current_ref()
            .map(str::to_string)
            .unwrap_or_default();
        let key = (format!("{owner}/{name}"), path.clone(), ref_.clone());
        match self.last_commits.get(&key) {
            Some(entry) => {
                self.browser.preview.set_band(
                    Some(path),
                    Some(crate::components::preview::BandContext {
                        sha: entry.sha.clone(),
                        subject: entry.subject.clone(),
                        author: entry.author.clone(),
                        date: entry.date.clone(),
                    }),
                );
            }
            None => {
                self.spawn_last_commit(format!("{owner}/{name}"), path, Some(ref_));
            }
        }
    }

    /// 0018 M3: the quit-time restart trace — only when this session
    /// knew about an update (the `↑` chip), compare the on-disk
    /// binary once. The caller prints it after terminal restore.
    pub fn update_exit_note(&self) -> Option<String> {
        self.update_tag.as_ref()?;
        crate::update::disk_newer_note()
    }

    /// Desired terminal cursor shape, if any text input is focused.
    pub fn cursor_style(&self) -> Option<ratatui::crossterm::cursor::SetCursorStyle> {
        if let Some(cl) = &self.command_line {
            return cl.cursor_style();
        }
        if let Some(settings) = &self.settings {
            return settings.cursor_style();
        }
        if let Some(view) = &self.search_view {
            return view.cursor_style();
        }
        self.popup.as_ref().and_then(|p| p.cursor_style())
    }

    pub fn render(&mut self, frame: &mut Frame, area: Rect) {
        let theme = self.effective_theme();
        let mode = self.effective_mode();
        // State vs keys, one hint surface per context: a view or
        // overlay that draws its own border hint row (search view,
        // popups, wizard) wins; the glued strip serves what has no
        // border — the leader layer (always) and the browser's
        // transient modes; the modeline is state-only either way.
        let overlay_up = self.popup.is_some()
            || self.wizard.is_some()
            || self.settings.is_some()
            || self.help.is_some()
            || self.command_line.is_some()
            || self.refs_popup.is_some()
            || self.search_view.is_some();
        let strip = mode == Mode::Leader || (!overlay_up && mode != Mode::Browse);
        let rows = Layout::default()
            .direction(Direction::Vertical)
            .constraints(if strip {
                vec![
                    Constraint::Min(1),
                    Constraint::Length(1),
                    Constraint::Length(1),
                ]
            } else {
                vec![Constraint::Min(1), Constraint::Length(1)]
            })
            .split(area);

        if let Some(view) = &mut self.search_view {
            view.render(frame, rows[0], &theme);
            self.modeline.context = view.context();
        } else {
            // The preview submode (␣ p) and its lenses zoom the pane to
            // the full row; FIND raised from it keeps the zoom.
            let zoomed = matches!(self.mode, Mode::Preview | Mode::History)
                || (self.mode == Mode::Find && self.find_return == Some(Mode::Preview));
            self.browser.preview.focused = zoomed;
            self.browser.render(frame, rows[0], &theme, zoomed);
            self.modeline.context = self.browser.context();
        }
        if strip {
            frame.render_widget(
                Paragraph::new(crate::components::modeline::hint_strip_line(
                    mode,
                    rows[1].width as usize,
                    &theme,
                )),
                rows[1],
            );
        }
        self.modeline.status = self.status.clone().or_else(|| self.degraded.clone());
        let modeline_row = rows[rows.len() - 1];
        self.modeline.update_tag = self.update_tag.clone();
        self.modeline.render(frame, modeline_row, mode, &theme);

        if let Some(popup) = &mut self.popup {
            popup.render(frame, rows[0], &theme);
        }
        // v0.3/v0.4 overlays, above the base view.
        if let Some(help) = &mut self.help {
            help.render(frame, rows[0], &theme);
        }
        if let Some(settings) = &mut self.settings {
            settings.render(frame, rows[0], &theme);
        }
        if let Some(wizard) = &mut self.wizard {
            wizard.render(frame, rows[0], &theme);
        }
        if let Some(refs) = &mut self.refs_popup {
            refs.render(frame, rows[0], &theme);
        }
        // 0019 M2: the consent popup is the topmost surface — a
        // pending trust decision renders above everything.
        if let Some(consent) = &mut self.consent {
            consent.render(frame, rows[0], &theme);
        }
        // Command strip sits on the modeline's doorstep, last.
        if let Some(command_line) = &mut self.command_line {
            command_line.render(frame, rows[0], &theme);
        }
    }
}
/// Worker debug tracing: enabled via ROOTLE_TRACE=/path/log (kept minimal,
/// no logging dependency; remove when the backend stabilizes).
pub fn trace(msg: &str) {
    if let Ok(path) = std::env::var("ROOTLE_TRACE") {
        use std::io::Write;
        if let Ok(mut f) = std::fs::OpenOptions::new()
            .create(true)
            .append(true)
            .open(path)
        {
            let _ = writeln!(f, "{:?} {msg}", std::time::SystemTime::now());
        }
    }
}

#[cfg(test)]
mod tests {
    use crate::provider::{ErrorKind, ProviderError};
    use std::time::Duration;

    #[test]
    fn provider_status_renders_per_kind() {
        let auth = ProviderError::new(ErrorKind::Auth, "bad credentials");
        let rendered = super::provider_status(&auth);
        assert!(rendered.contains("bad credentials"));
        assert!(rendered.contains("refresh provider credentials"));

        let throttled = ProviderError::new(ErrorKind::RateLimited, "slow down")
            .with_retry_after(Duration::from_secs(37));
        assert_eq!(
            super::provider_status(&throttled),
            "provider throttled — retry in 37s"
        );

        let plain = ProviderError::other("something broke");
        assert_eq!(super::provider_status(&plain), "something broke");
    }
}