mirador 1.22.0

//! The application shell: layout, focus, the event loop and global bindings.
//!
//! The shell knows nothing about what any panel displays. It owns the grid, the
//! focus ring, the frames and the tick schedule, and forwards everything else
//! through the [`Panel`] trait.

use std::path::PathBuf;
use std::time::{Duration, Instant};

use anyhow::{Context, Result};
use ratatui::DefaultTerminal;
use ratatui::crossterm::event::{
    self, Event, KeyCode, KeyEvent, KeyEventKind, KeyModifiers, MouseEvent, MouseEventKind,
};
use ratatui::layout::{Constraint, Layout, Position, Rect};
use ratatui::style::{Modifier, Style};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, BorderType, Borders, Clear, Padding, Paragraph};

use crate::config::Config;
use crate::frame::{Binding, FrameSpec};
use crate::keymap::Action;
use crate::panel::{KeyOutcome, Panel, RenderContext};
use crate::state::UiState;
use crate::theme::Gradients;

/// The gap between two hints on the status bar and the arrange legend.
///
/// Three spaces once, which is what a hint list wants when it is not competing
/// for the row — but this row is the one place on the dashboard where width is
/// always short, and six of them were being spent to separate seven hints. Two
/// is still twice the single space inside a hint, so `q quit` still reads as
/// one thing rather than two.
///
/// Named rather than repeated, because the test that proves the bar never
/// draws half a hint rebuilds the bar from this same table and would otherwise
/// hold its own private copy of the gap.
const HINT_GAP: &str = "  ";

/// How long a run of resize keystrokes must be quiet before the layout is
/// written back.
///
/// Long enough to sit out key auto-repeat, short enough that closing the window
/// a moment later still keeps the change.
const RESIZE_SETTLE: Duration = Duration::from_millis(750);

/// Smallest weight a panel or row may be squeezed to.
const MIN_WEIGHT: u16 = 1;

/// Split `total` cells across `weights`, giving no slot more than its maximum
/// and handing what it declines to the slots that can still use it.
///
/// `maxima` pairs with `weights` index for index, so the two must be the same
/// length; both callers build them from the same rows, or from the same row's
/// entries, so they always match.
///
/// A clock cannot use a hundred columns; a calendar cannot use more than its
/// months need. Pure proportional layout gives them the space anyway and they
/// sit in it, while the task list next door runs out of room. So a panel may
/// declare the point past which more space does nothing for it, and the surplus
/// moves sideways to a neighbour that will actually fill it.
///
/// When *every* slot is bounded there is nobody left who can use the surplus,
/// and it is spread back across the whole row rather than left unallocated:
/// panels draw their own frames, so a gap would show as a hole in the middle of
/// the dashboard. Better every panel slightly over its maximum than a seam.
///
/// The emphasis on *spread* is the fix for a real bug. The surplus used to be
/// handed to the slots that could still grow without re-capping them, so on the
/// next pass they were over their own maxima, nobody could absorb it, and the
/// loop broke leaving the whole overshoot on one panel. On the shipped default
/// layout at 400 columns that gave the clock 302 of them — and the clock's
/// numerals stop growing at 158, so about 145 columns were literally blank
/// while the weather panel beside it sat at 51 and the task list below ran out
/// of room. It only appeared once the terminal was wider than the row's maxima
/// summed, which is why nothing caught it until someone opened a 4K terminal.
fn distribute(total: u16, weights: &[u16], maxima: &[Option<u16>]) -> Vec<u16> {
    debug_assert_eq!(weights.len(), maxima.len(), "one maximum per weight");
    let count = weights.len();
    if count == 0 || total == 0 {
        return vec![0; count];
    }

    let mut sizes = proportional(total, weights);

    // Each pass caps whoever is over and re-splits what they gave up. Bounded
    // by the slot count: every pass either caps at least one more slot or ends,
    // because a slot only receives surplus while it is still under its maximum.
    for _ in 0..count {
        let mut surplus: u32 = 0;
        for i in 0..count {
            if let Some(max) = maxima[i]
                && sizes[i] > max
            {
                surplus += u32::from(sizes[i] - max);
                sizes[i] = max;
            }
        }
        if surplus == 0 {
            break;
        }
        // `surplus` was summed out of `sizes`, which sums to `total`.
        let surplus = u16::try_from(surplus).unwrap_or(u16::MAX);

        let takers: Vec<usize> = (0..count)
            .filter(|&i| maxima[i].is_none_or(|max| sizes[i] < max))
            .collect();

        if takers.is_empty() {
            // Every slot is at its declared maximum and there are still cells
            // to place. Spread them across the row in proportion, so the
            // overshoot is shared rather than landing entirely on whichever
            // slot happened to be uncapped last.
            for (i, extra) in proportional(surplus, weights).into_iter().enumerate() {
                sizes[i] = sizes[i].saturating_add(extra);
            }
            break;
        }

        let taker_weights: Vec<u16> = takers.iter().map(|&i| weights[i].max(1)).collect();
        for (slot, extra) in takers.iter().zip(proportional(surplus, &taker_weights)) {
            sizes[*slot] = sizes[*slot].saturating_add(extra);
        }
        // A taker may now be over its own maximum; the next pass caps it.
    }

    sizes
}

/// Split `total` in proportion to `weights`, losing no cells to rounding.
///
/// Largest-remainder rather than plain division: dividing and truncating leaves
/// up to one cell per slot unallocated, which shows up as a ragged right edge.
fn proportional(total: u16, weights: &[u16]) -> Vec<u16> {
    let count = weights.len();
    if count == 0 {
        return Vec::new();
    }
    let sum: u32 = weights.iter().map(|w| u32::from((*w).max(1))).sum();
    if sum == 0 {
        return vec![0; count];
    }

    let mut sizes = Vec::with_capacity(count);
    let mut remainders: Vec<(u32, usize)> = Vec::with_capacity(count);
    let mut used: u32 = 0;

    for (index, weight) in weights.iter().enumerate() {
        let exact = u32::from(total) * u32::from((*weight).max(1));
        let whole = exact / sum;
        remainders.push((exact % sum, index));
        used += whole;
        sizes.push(u16::try_from(whole).unwrap_or(u16::MAX));
    }

    // Hand the leftover cells to the largest remainders, ties by position so
    // the result is stable frame to frame.
    remainders.sort_by(|a, b| b.0.cmp(&a.0).then(a.1.cmp(&b.1)));
    let mut leftover = u32::from(total).saturating_sub(used);
    for (_, index) in remainders {
        if leftover == 0 {
            break;
        }
        sizes[index] = sizes[index].saturating_add(1);
        leftover -= 1;
    }

    sizes
}

/// The index to trade space with: the next one along, or the previous one when
/// `index` is last. `None` when there is nobody to trade with.
fn neighbour_of(index: usize, len: usize) -> Option<usize> {
    if len < 2 {
        return None;
    }
    if index + 1 < len {
        Some(index + 1)
    } else {
        index.checked_sub(1)
    }
}

/// What leads an alert on the status bar.
const ALERT_MARKER: &str = " ⚠ ";

/// The status bar's alert, fitted to a bar `width` cells wide.
///
/// One part for [`crate::grid::assemble`], marker and text together, so the
/// whole thing is measured in cells and abridged as one value. The text used
/// to be cut to the room left beside the marker, counted in characters: right
/// for `⚠`, a cell over for a wide sign such as `🚨`, which the terminal would
/// have taken off the alert's end with no `…`. And a bar narrower than the
/// marker drew the marker over nothing, where now it ends in `…` like any
/// other cut.
fn alert_line(text: &str, width: u16, theme: &crate::theme::Theme) -> Line<'static> {
    crate::grid::assemble(
        vec![vec![
            Span::styled(
                ALERT_MARKER,
                Style::default()
                    .fg(theme.error)
                    .add_modifier(Modifier::BOLD),
            ),
            Span::styled(text.to_string(), Style::default().fg(theme.error)),
        ]],
        width,
    )
}

/// The keys of the shell's four modes, read from the config together, each
/// named for the `[<mode>.keys]` table it comes from.
///
/// Both ways in — the start and a reload or reset from the key map — take
/// their keys from [`ModeKeys::read`] and unpack every field by name, so a
/// fifth mode added here does not compile until both have been told about
/// it. They used to be written out twice, once through the named
/// constructors and once by spelling each scope's name, action table and
/// config field again by hand.
struct ModeKeys {
    arrange: crate::keymap::PanelKeymap<crate::keymap::ArrangeAction>,
    panel_picker: crate::keymap::PanelKeymap<crate::picker::PickerAction>,
    theme_picker: crate::keymap::PanelKeymap<crate::theme_picker::ThemePickerAction>,
    help_overlay: crate::keymap::PanelKeymap<crate::keymap::HelpAction>,
}

impl ModeKeys {
    /// Each mode's `[<mode>.keys]` laid over its defaults, or why one of
    /// them cannot be.
    fn read(config: &Config) -> std::result::Result<Self, String> {
        Ok(Self {
            arrange: crate::keymap::arrange_keymap(&config.arrange.keys)?,
            panel_picker: crate::picker::keymap(&config.panel_picker.keys)?,
            theme_picker: crate::theme_picker::keymap(&config.theme_picker.keys)?,
            help_overlay: crate::keymap::help_keymap(&config.help_overlay.keys)?,
        })
    }
}

/// A panel plus its tick bookkeeping.
struct Slot {
    /// Which widget this is, so a layout change can carry the panel across
    /// rather than rebuilding it. Kept on the slot because the config's
    /// `[layout]` has already been mutated by the time a rebuild runs, so it
    /// no longer says what the *current* panels are.
    widget: String,
    panel: Box<dyn Panel>,
    /// `(row, column)` in `config.layout` of the entry this panel was built
    /// for, so a resize knows which weights the focused panel is made of and
    /// `geometry` which box it draws in. Kept on the slot rather than in a
    /// list beside `slots`, which every builder had to push in step: a widget
    /// that builds nothing leaves a hole in the layout, and an index into one
    /// list read against the other then names some other panel.
    position: (usize, usize),
    /// When this panel last ticked. `None` until it has, which is what makes
    /// the first tick fire immediately.
    ///
    /// Deliberately not "now minus a day": `Instant` on Windows is a duration
    /// since boot, so `checked_sub` there returns `None` on a machine up for
    /// less than that and the `unwrap` was a hard panic before the terminal
    /// was even initialised. `network.rs` already solved the same "the first
    /// sample is not meaningful" problem this way.
    last_tick: Option<Instant>,
    /// Interior rectangle the panel was last drawn into, used to route mouse
    /// events. `None` until the first draw, and while the panel is too small
    /// to render at all — in both cases there is nothing to click.
    area: Option<Rect>,
}

/// The running dashboard.
///
/// The flags are genuinely independent — an overlay being open says nothing
/// about whether the layout needs writing — so grouping them into a struct to
/// satisfy the lint would add a name without adding a meaning.
#[allow(clippy::struct_excessive_bools)]
pub struct App {
    config: Config,
    /// The shell's keys: the defaults with the config's `[keys]` over them.
    keymap: crate::keymap::Keymap,
    /// Arrange mode's keys, from `[arrange.keys]`.
    arrange_keys: crate::keymap::PanelKeymap<crate::keymap::ArrangeAction>,
    /// The `w` picker's keys, from `[panel_picker.keys]`, handed to it as it
    /// opens.
    panel_picker_keys: crate::keymap::PanelKeymap<crate::picker::PickerAction>,
    /// The `t` picker's keys, from `[theme_picker.keys]`.
    theme_picker_keys: crate::keymap::PanelKeymap<crate::theme_picker::ThemePickerAction>,
    /// The help overlay's scroll keys, from `[help_overlay.keys]`.
    help_keys: crate::keymap::PanelKeymap<crate::keymap::HelpAction>,
    gradients: Gradients,
    slots: Vec<Slot>,
    focus: usize,
    show_help: bool,
    /// First visible line of the help overlay.
    help_scroll: u16,
    /// How far the help overlay can scroll, and how tall its viewport is — both
    /// measured during the render that laid it out, because both depend on the
    /// terminal width the text wrapped at. Zero overflow is also what tells the
    /// key handler to leave the arrow keys alone and close on anything.
    help_overflow: u16,
    help_viewport: u16,
    should_quit: bool,
    /// A newer version, if the opt-in check found one. Empty otherwise, and
    /// empty always when the check is off — `App` never starts it, so no test
    /// and no `--print-config` run can reach the network.
    update: crate::update::Found,
    /// Whether the update notice is still on screen. Retired by the first key,
    /// paste or click: a dashboard you leave open all day must not nag, and a
    /// notice that will not go away is a nag.
    show_update_hint: bool,
    /// What has happened since mirador started.
    ///
    /// Lives here rather than in the watch log panel because the panel may not
    /// be placed, may be toggled off and on, and is rebuilt whenever the layout
    /// changes. Events would be lost every time, and a log that forgets when
    /// you rearrange the dashboard is not a log.
    watch: crate::watch::WatchLog,
    /// The day the watch log last saw.
    ///
    /// Held here rather than in a panel because the day turning is not any
    /// panel's business — the todo panel happens to notice it too, but a
    /// dashboard whose day-divider disappears when you switch off the task
    /// list would be a strange thing.
    today: jiff::civil::Date,
    /// The panel picker, while it is open.
    picker: Option<crate::picker::Picker>,
    /// The theme picker, while it is open, and the theme to put back if it is
    /// cancelled. Previewing means the live theme is not the committed one, so
    /// the dialog cannot be closed without knowing what it replaced.
    theme_picker: Option<(crate::theme_picker::ThemePicker, crate::theme::Theme)>,
    /// The key map, opened by pressing the help key while help is open.
    keymap_dialog: Option<crate::keymap_dialog::KeymapDialog>,
    /// The layout as it stood when arrange mode opened, kept so that `Esc` can
    /// put it back. Moving panels is a bigger, more spatial change than
    /// toggling one on, and being able to try an arrangement and back out of it
    /// is most of what makes it safe to try at all.
    arranging: Option<Arrangement>,
    /// The config file, so layout changes can be written back to it. `None` in
    /// tests, which is what keeps them off a real user's config.
    config_path: Option<PathBuf>,
    /// When the last `Ctrl+arrow` landed, if one is still unwritten.
    last_resize: Option<Instant>,
    /// Whether the layout has been changed since it was last written.
    layout_dirty: bool,
    /// Why the last layout write failed, if it did. Shown in the picker and
    /// on the bar: a change you made that silently did not persist is the
    /// worst outcome here. Set by [`App::write_layout`] and by nothing else,
    /// so the alert that reads it is true whenever it is lit.
    layout_error: Option<String>,
    /// Why the last layout change was refused, if it was — the last panel,
    /// or a layout the panels would not build from, already put back.
    /// Nothing changed and nothing is unsaved, so it is said in the picker
    /// and not on the bar, and it goes when the picker closes. It used to
    /// share `layout_error`, which put "The layout could not be saved" on
    /// the bar for a save nobody attempted, until some later layout change
    /// happened to succeed.
    layout_notice: Option<String>,
    /// Where to write remembered preferences, once someone asks for that.
    /// `None` in tests, which is what keeps them off a real user's file.
    state_path: Option<PathBuf>,
    /// The last state written, so a keypress that changed nothing writes
    /// nothing.
    saved_state: UiState,
    /// What the config file itself says. Preferences are recorded as the
    /// difference from this, which is what lets one be un-set.
    baseline: UiState,
}

/// What arrange mode has to put back if the user changes their mind.
struct Arrangement {
    layout: crate::config::Layout,
    /// Whether the layout was already unwritten when the mode opened — a resize
    /// a moment earlier, say. Cancelling restores the layout, and must not also
    /// throw away a change that was never part of this arrangement.
    was_dirty: bool,
}

impl std::fmt::Debug for App {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("App")
            .field("panels", &self.slots.len())
            .field("focus", &self.focus)
            .finish_non_exhaustive()
    }
}

impl App {
    /// Build every panel named in the layout, in row-major order.
    pub fn new(config: Config) -> Result<Self> {
        let slots = Self::build_slots(&config)?;
        Self::around(config, slots)
    }

    /// The shell around panels already built: key tables, gradients and a
    /// dashboard in its opening state.
    fn around(config: Config, slots: Vec<Slot>) -> Result<Self> {
        let (keymap, _) = crate::keymap::KeyTables::from_config(&config)
            .check()
            .map_err(anyhow::Error::msg)?;
        // Checked with the rest just above, so this cannot fail.
        let ModeKeys {
            arrange: arrange_keys,
            panel_picker: panel_picker_keys,
            theme_picker: theme_picker_keys,
            help_overlay: help_keys,
        } = ModeKeys::read(&config).map_err(anyhow::Error::msg)?;

        let gradients = config.theme.gradients();
        Ok(Self {
            config,
            keymap,
            arrange_keys,
            panel_picker_keys,
            theme_picker_keys,
            help_keys,
            gradients,
            slots,
            focus: 0,
            show_help: false,
            help_scroll: 0,
            help_overflow: 0,
            help_viewport: 0,
            should_quit: false,
            update: crate::update::Found::default(),
            show_update_hint: true,
            watch: crate::watch::WatchLog::default(),
            today: jiff::Zoned::now().date(),
            picker: None,
            theme_picker: None,
            keymap_dialog: None,
            arranging: None,
            config_path: None,
            last_resize: None,
            layout_dirty: false,
            layout_error: None,
            layout_notice: None,
            state_path: None,
            saved_state: UiState::default(),
            baseline: UiState::default(),
        })
    }

    /// Build one panel per entry in the layout, in row-major order.
    fn build_slots(config: &Config) -> Result<Vec<Slot>> {
        let mut slots = Vec::new();
        for (row_index, row) in config.layout.rows.iter().enumerate() {
            for (column_index, entry) in row.panels.iter().enumerate() {
                let panel = crate::widgets::build(&entry.widget, config)
                    .with_context(|| format!("building the `{}` panel", entry.widget))?;
                if let Some(panel) = panel {
                    slots.push(Slot {
                        widget: entry.widget.clone(),
                        panel,
                        position: (row_index, column_index),
                        last_tick: None,
                        area: None,
                    });
                }
            }
        }

        anyhow::ensure!(
            !slots.is_empty(),
            "no panels were built; check the `[layout]` table in your config"
        );
        Ok(slots)
    }

    /// Reconcile the panels with a changed layout, carrying across every panel
    /// that is still placed.
    ///
    /// This used to throw every panel away and remake them all, on the grounds
    /// that a beat of re-fetching reads as the dashboard responding. That was
    /// wrong, and the demo recording is what showed it: **start the pomodoro,
    /// toggle an unrelated panel, and the timer resets to 25:00.** A running
    /// timer is not a cache that can be refilled — it is the user's state, and
    /// nothing about switching the network panel off says to discard it. The
    /// weather and stocks panels lost their readings the same way and spent a
    /// fetch cycle showing "loading" after any toggle.
    ///
    /// A panel is matched to a layout entry by widget name. Nothing stops a
    /// hand-written config placing the same widget twice — `validate` checks
    /// that names are *known*, not that they are unique — so the surviving
    /// panels are consumed from a pool rather than looked up, and a second
    /// `clocks` entry gets a second panel rather than the same one twice.
    ///
    /// Two orderings matter here:
    ///
    /// 1. Every genuinely new panel is built **before** any existing one is
    ///    disturbed, so a layout that will not build leaves the running
    ///    dashboard exactly as it was. That was already true and is preserved.
    /// 2. Panels are shut down only once the new arrangement is settled, and
    ///    only the ones actually leaving. Dropping them without `shutdown`
    ///    discards the task store's save-on-shutdown and leaks the fetch
    ///    threads.
    ///
    /// This is only ever called after a `[layout]` edit, so no panel's *own*
    /// config can have changed underneath it. A caller that changes, say,
    /// `[weather].units` cannot use this — the carried-over panel would keep
    /// the old setting.
    fn rebuild_panels(&mut self) -> Result<()> {
        use std::collections::{HashMap, VecDeque};

        let desired: Vec<(usize, usize, String)> = self
            .config
            .layout
            .rows
            .iter()
            .enumerate()
            .flat_map(|(row, entry)| {
                entry
                    .panels
                    .iter()
                    .enumerate()
                    .map(move |(column, panel)| (row, column, panel.widget.clone()))
            })
            .collect();

        // What the live panels can supply, by name.
        let mut spare: HashMap<&str, usize> = HashMap::new();
        for slot in &self.slots {
            *spare.entry(slot.widget.as_str()).or_default() += 1;
        }

        // Build only what cannot be carried across. Any failure returns here,
        // with `self` untouched.
        let mut fresh: HashMap<String, VecDeque<Box<dyn Panel>>> = HashMap::new();
        let mut placed = 0usize;
        for (_, _, widget) in &desired {
            if let Some(count) = spare.get_mut(widget.as_str())
                && *count > 0
            {
                *count -= 1;
                placed += 1;
                continue;
            }
            let panel = crate::widgets::build(widget, &self.config)
                .with_context(|| format!("building the `{widget}` panel"))?;
            if let Some(panel) = panel {
                fresh.entry(widget.clone()).or_default().push_back(panel);
                placed += 1;
            }
        }

        // Checked before anything is taken apart, so a layout that would leave
        // nothing on screen is refused rather than applied.
        anyhow::ensure!(
            placed > 0,
            "no panels were built; check the `[layout]` table in your config"
        );

        let focused = self.slots.get(self.focus).map(|slot| slot.widget.clone());

        let mut pool: HashMap<String, VecDeque<Slot>> = HashMap::new();
        for slot in std::mem::take(&mut self.slots) {
            pool.entry(slot.widget.clone()).or_default().push_back(slot);
        }

        let mut slots = Vec::with_capacity(placed);
        for (row, column, widget) in desired {
            let carried = pool.get_mut(&widget).and_then(VecDeque::pop_front);
            let slot = carried.or_else(|| {
                fresh
                    .get_mut(&widget)
                    .and_then(VecDeque::pop_front)
                    .map(|panel| Slot {
                        widget: widget.clone(),
                        panel,
                        position: (row, column),
                        last_tick: None,
                        area: None,
                    })
            });
            if let Some(mut slot) = slot {
                // A carried panel is almost certainly somewhere else in the
                // layout now, and on screen. Its place is the entry it was
                // just matched to; its `area`, which mouse events are matched
                // against, is cleared rather than trusted until the next draw
                // sets it.
                slot.position = (row, column);
                slot.area = None;
                slots.push(slot);
            }
        }

        // Whatever is left was removed from the layout.
        for (_, leaving) in pool {
            for mut slot in leaving {
                slot.panel.shutdown();
            }
        }

        // Follow the focused panel to wherever it ended up, rather than leaving
        // the highlight on whatever now occupies its old index.
        self.focus = focused
            .and_then(|widget| slots.iter().position(|slot| slot.widget == widget))
            .unwrap_or_else(|| self.focus.min(slots.len().saturating_sub(1)));
        self.slots = slots;
        Ok(())
    }

    /// Run until the user quits.
    pub fn run(&mut self, terminal: &mut DefaultTerminal) -> Result<()> {
        let tick_rate = Duration::from_millis(self.config.general.tick_rate_ms.clamp(16, 5_000));

        // Redraw only when something actually changed. Mouse reporting makes
        // this matter: the terminal sends an event for every cell the pointer
        // crosses, and drawing on each one would have a dashboard left open all
        // day burning CPU whenever the mouse passes over it.
        let mut dirty = true;

        while !self.should_quit {
            if dirty {
                terminal.draw(|frame| self.render(frame))?;
                dirty = false;
            }

            if event::poll(self.poll_wait(tick_rate))? {
                match event::read()? {
                    // Only react to presses; on Windows every key also emits a
                    // release event, which would otherwise double every action.
                    Event::Key(key) if key.kind == KeyEventKind::Press => {
                        self.handle_key(key);
                        // Only keys can move a preference, and only after one
                        // has been handled can it have moved. Cheap because it
                        // compares before writing: an arrow key costs a struct
                        // comparison, not a file.
                        self.persist_preferences();
                        dirty = true;
                    }
                    Event::Paste(text) => dirty |= self.handle_paste(&text),
                    Event::Mouse(mouse) => dirty |= self.handle_mouse(mouse),
                    // Resize re-runs layout against the new frame size, which
                    // is the next draw's job — but that draw has to happen.
                    Event::Resize(_, _) => dirty = true,
                    // The closest thing to "the reader is looking" that a
                    // terminal will tell us. Not every terminal sends it and
                    // tmux forwards it only with `focus-events on`, so it is
                    // an improvement where available rather than the mechanism
                    // — the keypress below carries it everywhere else.
                    //
                    // **Losing focus only.** This used to mark on both, on the
                    // reasoning that gaining focus means they are here now and
                    // losing it means they were here until this moment — each
                    // true in isolation, and together they made the rule line
                    // impossible to see. Returning to the dashboard set "last
                    // looked" to *now*, so everything that arrived while the
                    // reader was away landed on the old side of the line and the
                    // line vanished in the instant they came back to read it.
                    // A terminal that reported focus *correctly* therefore made
                    // the feature less visible than one that did not (#132).
                    //
                    // Leaving is the half that can be recorded without
                    // destroying what it describes: they were present with those
                    // entries on screen, so marking them seen is honest. Coming
                    // back is precisely when the line has to still be there.
                    Event::FocusLost => self.watch.mark_seen(),
                    _ => {}
                }
            }

            dirty |= self.tick_panels();
            dirty |= self.collect_events();
            self.write_settled_resize();
        }

        self.finish();
        Ok(())
    }

    /// Write a resize once the key has stopped repeating.
    ///
    /// Resizes are batched rather than written per keystroke — `Ctrl+arrow`
    /// auto-repeats, and rewriting the config on every repeat would be absurd
    /// — but they are not batched all the way to exit any more. Closing the
    /// terminal window is a normal way to stop a dashboard you leave open all
    /// day, and it never reaches [`App::finish`]: the process is signalled and
    /// the pending resize is gone. This settles once the repeats stop, which
    /// is the earliest moment the write is not wasted.
    ///
    /// Deliberately not a signal handler. The only thing at risk is this one
    /// write, `SIGKILL` cannot be caught anyway, and the terminal does not
    /// need restoring when the terminal is what went away.
    ///
    /// Not while arrange mode is open. A resize made inside the mode is part
    /// of the arrangement, which Keep (or Ctrl+C, see `finish`) writes and Esc
    /// puts back. Settling it
    /// anyway wrote the file behind the mode's back, so Esc restored the
    /// screen and left the config resized for the next launch. A resize made
    /// before the mode opened is still dirty after Esc and settles here once
    /// the mode has closed.
    fn write_settled_resize(&mut self) {
        if self.arranging.is_none()
            && self.layout_dirty
            && self
                .last_resize
                .is_some_and(|at| at.elapsed() >= RESIZE_SETTLE)
        {
            self.write_layout();
            self.last_resize = None;
        }
    }

    /// Shut the panels down and write whatever is still unwritten.
    ///
    /// That includes an arrangement still open in arrange mode: Ctrl+C keeps
    /// it, as Keep would, and only Esc discards one. Decided by the owner on
    /// 2026-10-07 — Ctrl+C is the way out that always works, and leaving
    /// should not throw away work that is on screen.
    fn finish(&mut self) {
        for slot in &mut self.slots {
            slot.panel.shutdown();
        }
        // Once more on the way out, in case the last thing changed was not a
        // key — and because Ctrl+C reaches here too.
        self.persist_preferences();
        self.write_layout();
    }

    /// Remember preferences to `path` from now on.
    ///
    /// Separate from [`App::new`] so that tests, which build apps constantly,
    /// cannot write to a real user's state file by forgetting to opt out. An
    /// app with no path set simply never persists.
    ///
    /// `loaded` is what was read from that file, so startup does not rewrite a
    /// file it has just read. `baseline` is what the *config* says, taken before
    /// the loaded values were folded in — every write is the difference between
    /// the panels and that.
    pub fn remember_preferences_at(&mut self, path: PathBuf, loaded: UiState, baseline: UiState) {
        self.saved_state = loaded;
        self.baseline = baseline;
        self.state_path = Some(path);
    }

    /// The preferences that differ from the config, which is all that is worth
    /// recording.
    ///
    /// Panels report their current values unconditionally; the comparison is
    /// here, once, so a value set back to what the config says drops out of the
    /// file instead of leaving the earlier change asserted for ever.
    fn collect_preferences(&self) -> UiState {
        let mut current = UiState::default();
        for slot in &self.slots {
            slot.panel.remember(&mut current);
        }
        // The theme is the shell's, not any panel's, so it is reported here —
        // but reported the same way, unconditionally, so invariant 17 holds for
        // it too and picking your config's own theme back retracts the entry.
        //
        // While the theme picker is open the live theme is only a preview, so
        // the one reported is the theme it opened on. Otherwise every arrow
        // key wrote the file, and a dashboard closed mid-browse came back in
        // a theme nobody chose.
        let committed = self
            .theme_picker
            .as_ref()
            .map_or(&self.config.theme, |(_, original)| original);
        current.theme.clone_from(&committed.name);
        current.only_changes_from(&self.baseline)
    }

    /// Write preferences if any of them moved.
    ///
    /// A failed write is deliberately not surfaced. There is no panel that owns
    /// this to show an error in, and the failure costs a sort order that one
    /// keystroke restores — putting a warning on a dashboard designed to be
    /// left open, over that, would be the wrong trade. Task and note saves,
    /// which can lose something you cannot retype, do surface theirs.
    fn persist_preferences(&mut self) {
        let Some(path) = self.state_path.clone() else {
            return;
        };
        let current = self.collect_preferences();
        if current == self.saved_state {
            return;
        }
        if current.save(&path).is_ok() {
            self.saved_state = current;
        }
    }

    /// Drain what the panels have noticed into the log.
    ///
    /// Returns whether anything was recorded, so the dashboard redraws: a new
    /// entry is a visible change if the watch log is on screen, and cheaper to
    /// report unconditionally than to ask whether it is placed.
    fn collect_events(&mut self) -> bool {
        let mut recorded = false;

        // The day turning is the one thing in here that always happens, which
        // matters more than it sounds: with a calendar unconfigured and no task
        // falling due, every other source can go quiet for days and leave the
        // panel looking broken. It is also the most useful divider a log of
        // "what changed while I was away" can have.
        let today = jiff::Zoned::now().date();
        if today != self.today {
            self.today = today;
            self.watch.push(crate::watch::Event::new(
                "clock",
                format!("{} began", today.strftime("%A %-d %B")),
            ));
            recorded = true;
        }

        for slot in &mut self.slots {
            for event in slot.panel.events() {
                self.watch.push(event);
                recorded = true;
            }
        }
        recorded
    }

    /// Tick every panel whose interval has elapsed, and report whether any of
    /// them said something a viewer could see had changed.
    ///
    /// The distinction is the whole point, and getting it wrong is invisible in
    /// a screenshot and enormous in a profile. This used to return "some
    /// panel's timer fired", which the run loop OR'd straight into `dirty`.
    /// Measured on the shipped nine-panel default at 400x100: **243 redraws a
    /// minute**, and the same 243 whether `show_seconds` was on or off — so
    /// with seconds off the dashboard repainted 243 times to show content that
    /// changed once.
    fn tick_panels(&mut self) -> bool {
        let now = Instant::now();
        let mut changed = false;
        for slot in &mut self.slots {
            let due = slot
                .last_tick
                .is_none_or(|last| now.duration_since(last) >= slot.panel.refresh_interval());
            if due {
                // Not `changed = changed || slot.panel.tick()`: `||`
                // short-circuits once the accumulator is true, and a panel that
                // stops being ticked stops updating. The call goes on the left
                // so the order is visibly load-bearing; `|=` on a `bool` is
                // eager and would be as safe, which is what `run` relies on.
                changed = slot.panel.tick() || changed;
                slot.last_tick = Some(now);
            }
        }
        changed
    }

    /// True when the focused panel is in a text-entry or modal state and global
    /// bindings must not fire.
    fn focus_captures_input(&self) -> bool {
        self.slots
            .get(self.focus)
            .is_some_and(|slot| slot.panel.captures_input())
    }

    /// Let a focused interactive panel request responsive asynchronous echo
    /// without changing the dashboard-wide polling budget. The floor prevents
    /// an external process from turning the shell into a busy loop.
    fn poll_wait(&self, configured: Duration) -> Duration {
        self.slots
            .get(self.focus)
            .filter(|slot| slot.panel.captures_input())
            .map_or(configured, |slot| {
                configured.min(slot.panel.refresh_interval().max(Duration::from_millis(16)))
            })
    }

    fn handle_key(&mut self, key: KeyEvent) {
        // Any key at all retires the update notice. It has been read or it has
        // been ignored; either way it has had its turn.
        self.show_update_hint = false;
        // A keypress is weaker evidence than a focus event — the moments this
        // most wants to be right are the glances that touch nothing — but it is
        // the only evidence available on a terminal that does not report focus.
        self.watch.mark_seen();

        let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);

        // Editors get first refusal only for a real selection. No modal panel,
        // child process or external protocol can veto the escape hatch: after
        // the selection collapses, Ctrl+C exits from every state.
        if ctrl && matches!(key.code, KeyCode::Char('c')) {
            let consumed = self.slots.get_mut(self.focus).is_some_and(|slot| {
                slot.panel.copy_selection() == crate::panel::KeyOutcome::Consumed
            });
            if consumed {
                return;
            }
            self.should_quit = true;
            return;
        }

        // The help overlay swallows the next key, whatever it is — except the
        // ones that scroll it, because on an 80x24 terminal the focused panel's
        // own bindings do not fit and a key that cannot be reached is a key
        // that does not exist. Scrolling only binds when there is something
        // below the fold, so on a tall terminal any key still closes it.
        if self.show_help {
            // The help key a second time goes one level deeper, to the full
            // key map. Reached through help rather than on a key of its own:
            // every free letter is some panel's already, and the overlay is
            // where someone wondering about keys has just arrived.
            if self.keymap.action(key) == Some(Action::Help) {
                self.show_help = false;
                self.keymap_dialog = Some(crate::keymap_dialog::KeymapDialog::new());
                return;
            }
            // The scroll keys are `[help_overlay.keys]`, and bind only when
            // there is something below the fold; every other key closes.
            if self.help_overflow > 0 {
                use crate::keymap::HelpAction;
                let page = self.help_viewport.max(1);
                let moved = self.help_keys.action(key).map(|action| match action {
                    HelpAction::Down => self.help_scroll.saturating_add(1),
                    HelpAction::Up => self.help_scroll.saturating_sub(1),
                    HelpAction::PageDown => self.help_scroll.saturating_add(page),
                    HelpAction::PageUp => self.help_scroll.saturating_sub(page),
                    HelpAction::First => 0,
                    HelpAction::Last => self.help_overflow,
                });
                if let Some(to) = moved {
                    self.help_scroll = to.min(self.help_overflow);
                    return;
                }
            }
            self.show_help = false;
            return;
        }

        if let Some(dialog) = self.keymap_dialog.as_mut() {
            match dialog.handle_key(key) {
                crate::keymap_dialog::Request::None => {}
                crate::keymap_dialog::Request::Close => self.keymap_dialog = None,
                crate::keymap_dialog::Request::Reload => self.reload_keys(),
                crate::keymap_dialog::Request::Reset => self.reset_keys(),
            }
            return;
        }

        // The picker is a real dialog rather than a notice, so it reads keys
        // instead of dismissing on any of them.
        if self.theme_picker.is_some() {
            self.handle_theme_picker_key(key);
            return;
        }
        if self.picker.is_some() {
            self.handle_picker_key(key);
            return;
        }

        let resize = self.keymap.action(key).filter(|action| action.is_resize());

        // Arrange mode claims the bare arrows, which is the whole point of it
        // being a mode: no modifier to discover, and no terminal that declines
        // to deliver the chord. The resize keys fall through wherever they
        // have been moved to, so resizing keeps working while you are
        // rearranging — which is when you are most likely to want it — and a
        // key in `[arrange.keys]` that is also a resize key is refused at load
        // for that reason. Any other Ctrl key falls through too, unless
        // `[arrange.keys]` binds it.
        if self.arranging.is_some()
            && resize.is_none()
            && (!ctrl || self.arrange_keys.action(key).is_some())
        {
            self.handle_arrange_key(key);
            return;
        }

        // Resizing is a shell-level concern, the way it is in tmux, so it is
        // claimed before panels get a look. It has to be: the calendar binds
        // the bare arrow keys and does not inspect modifiers, so offering the
        // key onward first would have Ctrl+Left scroll the month instead.
        //
        // A panel in a text-entry state still vetoes it, under the same rule
        // that stops `q` quitting mid-form.
        if let Some(action) = resize
            && !self.focus_captures_input()
        {
            let resized = match action {
                Action::ResizeWider => self.resize_width(true),
                Action::ResizeNarrower => self.resize_width(false),
                Action::ResizeTaller => self.resize_height(true),
                _ => self.resize_height(false),
            };
            // Only a resize that actually moved something needs writing. Held
            // against a minimum, the key repeats without changing anything, and
            // marking those dirty would write the config on shutdown after a
            // session that changed nothing.
            self.layout_dirty |= resized;
            if resized {
                self.last_resize = Some(Instant::now());
            }
            // Swallowed either way: a resize that hit the minimum is still a
            // resize key, and must not fall through to a panel binding.
            return;
        }

        self.dispatch_key(key);
    }

    /// Route a terminal bracketed paste to the focused editor.
    ///
    /// A panel can consume the whole block so a multiline editor preserves
    /// hard lines and literal tabs. Older form fields still receive the same
    /// printable key stream they did before bracketed paste was enabled; it is
    /// dispatched straight to the capturing panel so pasted `q` cannot become
    /// a global quit command.
    ///
    /// The veto is asked again before every key, and the paste ends when it
    /// lapses. A newline is Enter, and Enter commits a one-line form: what
    /// follows it would otherwise reach the panel as commands, which in the
    /// task list means a second line beginning `a` opens another task and
    /// one beginning `dy` deletes the first. The rest is dropped instead.
    ///
    /// A delete confirmation captures input too, and nothing here can tell
    /// it from a form, so the panels that ask one claim a paste themselves
    /// and drop it: typed in, a paste beginning with `y` was the answer.
    fn handle_paste(&mut self, text: &str) -> bool {
        // A paste is the reader acting, as a key is: it retires the update
        // notice and marks the watch log seen. Both change what is on screen,
        // and `run` redraws after a paste only when asked — so every way out
        // of here asks when either did, as `handle_mouse` does with the
        // notice. Without it a paste no panel took left both standing.
        let had_hint = std::mem::take(&mut self.show_update_hint);
        let line_before = self.watch.unseen();
        self.watch.mark_seen();
        let retired = had_hint || self.watch.unseen() != line_before;

        if self.show_help {
            self.show_help = false;
            return true;
        }
        if self.theme_picker.is_some()
            || self.picker.is_some()
            || self.arranging.is_some()
            || self.keymap_dialog.is_some()
        {
            return retired;
        }

        let Some(slot) = self.slots.get_mut(self.focus) else {
            return retired;
        };
        if slot.panel.handle_paste(text) == crate::panel::KeyOutcome::Consumed {
            return true;
        }
        let text = text.replace("\r\n", "\n").replace('\r', "\n");
        let mut used = false;
        for character in text.chars() {
            if !slot.panel.captures_input() {
                break;
            }
            let code = match character {
                '\n' => KeyCode::Enter,
                '\t' => KeyCode::Tab,
                c if !c.is_control() => KeyCode::Char(c),
                _ => continue,
            };
            used = slot
                .panel
                .handle_key(KeyEvent::new(code, KeyModifiers::NONE))
                == crate::panel::KeyOutcome::Consumed
                || used;
        }
        used || retired
    }

    /// Read every key table from the config again, for the key map's `r`.
    ///
    /// A keymap that does not check out is reported and not applied: the keys
    /// in force stay in force, so a half-finished edit cannot take away the
    /// key the reader would use to fix it.
    fn reload_keys(&mut self) {
        let result = match self.config_path.as_deref() {
            Some(path) => crate::keymap::read_keys(path),
            None => Err("there is no config file to read keys from".into()),
        };
        let outcome = match result {
            Ok((tables, keymap)) => {
                tables.apply(&mut self.config);
                self.keymap = keymap;
                self.rebind_panels();
                Ok(match self.keys_changed() {
                    0 => "Loaded. Every key is its default.".to_string(),
                    1 => "Loaded. One key differs from its default.".to_string(),
                    n => format!("Loaded. {n} keys differ from their defaults."),
                })
            }
            Err(error) => Err(format!("Kept the keys you had. {error}")),
        };
        self.report_to_key_map(outcome);
    }

    /// Say in the key map how a reload or a reset went: what it did, or why
    /// it did nothing, shown as a failure.
    fn report_to_key_map(&mut self, outcome: std::result::Result<String, String>) {
        let (text, failed) = match outcome {
            Ok(text) => (text, false),
            Err(text) => (text, true),
        };
        if let Some(dialog) = self.keymap_dialog.as_mut() {
            dialog.report(text, failed);
        }
    }

    /// How many actions, the shell's and every panel's, are not on their
    /// default keys.
    fn keys_changed(&self) -> usize {
        let shell = Action::LISTED
            .iter()
            .filter(|action| !self.keymap.is_default(**action))
            .count();
        let panels = self
            .panel_keys()
            .iter()
            .flat_map(|(_, listing)| listing)
            .filter(|listed| !listed.is_default())
            .count();
        shell + panels
    }

    /// Every panel scope's keys as the key map lists them.
    fn panel_keys(&self) -> crate::keymap::PanelListing {
        crate::keymap::KeyTables::from_config(&self.config)
            .check()
            .map(|(_, panels)| panels)
            .unwrap_or_default()
    }

    /// Hand the shell's modes and every live panel their keys from the
    /// config again.
    ///
    /// Both callers apply tables that have just been checked — a reload's,
    /// or the defaults — so the modes' keys always build. Were one somehow
    /// not to, the keys in force stay in force, which is what a reload that
    /// does not check out does too.
    fn rebind_panels(&mut self) {
        if let Ok(ModeKeys {
            arrange,
            panel_picker,
            theme_picker,
            help_overlay,
        }) = ModeKeys::read(&self.config)
        {
            self.arrange_keys = arrange;
            self.panel_picker_keys = panel_picker;
            self.theme_picker_keys = theme_picker;
            self.help_keys = help_overlay;
        }
        for slot in &mut self.slots {
            slot.panel.set_keys(&self.config);
        }
    }

    /// Comment out every key table in the config and go back to the
    /// defaults, for the key map's `d` once the reader has said yes.
    fn reset_keys(&mut self) {
        let result = match self.config_path.as_deref() {
            Some(path) => crate::keymap::reset_file(path),
            None => Err("there is no config file to reset".into()),
        };
        let outcome = match result {
            Ok(edited) => {
                self.keymap = crate::keymap::Keymap::default();
                crate::keymap::KeyTables::default().apply(&mut self.config);
                self.rebind_panels();
                let text = if edited {
                    "Every key is back to its default. Your old key lines are \
                     still in the config, commented out."
                } else {
                    "The config sets no keys, so every key is its default."
                };
                Ok(text.to_string())
            }
            Err(error) => Err(format!("Nothing was changed. {error}")),
        };
        self.report_to_key_map(outcome);
    }

    /// Open arrange mode, remembering what to go back to.
    fn enter_arrange(&mut self) {
        self.arranging = Some(Arrangement {
            layout: self.config.layout.clone(),
            was_dirty: self.layout_dirty,
        });
    }

    /// Move the focused panel, or leave the mode.
    fn handle_arrange_key(&mut self, key: KeyEvent) {
        use crate::arrange::Direction;
        use crate::keymap::ArrangeAction;

        // Esc backs out of it, which is what Esc means everywhere else in
        // mirador, and so it is in no table. The picker commits on Esc instead,
        // and that is defensible there because each of its changes is one
        // keystroke to undo; an arrangement is not.
        if key.code == KeyCode::Esc {
            if let Some(before) = self.arranging.take() {
                self.config.layout = before.layout;
                // Rebuilding from a layout that was live a moment ago
                // cannot fail, and if it somehow did there is nothing
                // better to fall back to.
                let _ = self.rebuild_panels();
                self.layout_dirty = before.was_dirty;
            }
            return;
        }
        // The digits pick a panel here as they do outside the mode, and are
        // in no table for the same reason.
        if self.jump_to_slot(key) {
            return;
        }

        let Some(action) = self.arrange_keys.action(key) else {
            return;
        };
        match action {
            // The shifted keys move the whole row rather than the panel,
            // which is the same escalation the clock panel uses: the bare key
            // moves the small thing, the shifted key the thing it sits in.
            //
            // Not `Ctrl+←→↑↓`, which #100 proposed: those resize inside this
            // mode, advertised in the legend and pinned by
            // `ctrl_arrows_still_resize_inside_arrange_mode`.
            ArrangeAction::RowUp => self.move_focused_row(false),
            ArrangeAction::RowDown => self.move_focused_row(true),
            ArrangeAction::MoveLeft => self.move_focused(Direction::Left),
            ArrangeAction::MoveRight => self.move_focused(Direction::Right),
            ArrangeAction::MoveUp => self.move_focused(Direction::Up),
            ArrangeAction::MoveDown => self.move_focused(Direction::Down),
            // Pick a different panel to move without leaving the mode.
            // Rearranging a dashboard means moving several things, and having
            // to commit and re-enter between each one would make a two-panel
            // swap a six-keystroke job.
            ArrangeAction::FocusNext => self.cycle_focus(true),
            ArrangeAction::FocusPrevious => self.cycle_focus(false),
            // Keeping it is the ordinary way out, so it gets the ordinary keys.
            // Written here rather than on every arrow: trying four arrangements
            // should cost one write, and the mode is a natural commit point —
            // the same reasoning as the picker.
            ArrangeAction::Keep => {
                self.arranging = None;
                self.write_layout();
            }
        }
    }

    /// Move the focused panel one step, putting the layout back if the result
    /// will not build.
    fn move_focused(&mut self, direction: crate::arrange::Direction) {
        let Some((row, column)) = self.focused_position() else {
            return;
        };
        let before = self.config.layout.clone();
        if crate::arrange::move_panel(&mut self.config.layout, row, column, direction).is_none() {
            return;
        }

        // Focus follows the panel by name, so the moved panel keeps the
        // highlight wherever it lands and nothing here has to chase it.
        // A move builds no new panel, and only building one can fail, so a
        // refusal is a guard rather than a path, and arrange mode, which
        // draws no picker, has nowhere to say more.
        let _ = self.commit_layout(before);
    }

    /// Move the row the focused panel sits in, up or down, putting the layout
    /// back if the result will not build — silently, for the reason a panel
    /// move gives.
    fn move_focused_row(&mut self, down: bool) {
        let Some((row, _)) = self.focused_position() else {
            return;
        };
        let before = self.config.layout.clone();
        if crate::arrange::move_row(&mut self.config.layout, row, down).is_none() {
            return;
        }

        // Focus follows the panel by name, as it does for a panel move, so the
        // highlight stays on whatever the reader was moving even though every
        // panel in the row changed its flat index.
        let _ = self.commit_layout(before);
    }

    /// Rebuild the panels around the layout now in the config, or put
    /// `before` back and say why not.
    ///
    /// Every change to which panels there are, or where they sit, comes
    /// through here — a panel moved, a row moved, a panel switched on or off.
    /// Two layout changes go around it. A resize only moves weights, which the
    /// next draw reads from the config with no panel rebuilt. Esc in arrange
    /// mode rebuilds the panels itself, from a layout that was live a moment
    /// ago, so there is nothing to undo, and it puts back whether that layout
    /// was already waiting to be written rather than marking it.
    ///
    /// A layout the panels cannot be built from is undone rather than left
    /// half-applied, so the dashboard is always one the config can describe,
    /// and only a change that took is marked as needing to be written. What to
    /// say about a refusal is the caller's: the picker shows it, arrange mode
    /// has nowhere to.
    fn commit_layout(&mut self, before: crate::config::Layout) -> Result<()> {
        if let Err(error) = self.rebuild_panels() {
            // Rebuilding from a layout that was live a moment ago cannot
            // fail, and if it somehow did there is nothing better to fall
            // back to.
            self.config.layout = before;
            let _ = self.rebuild_panels();
            return Err(error);
        }
        self.layout_dirty = true;
        Ok(())
    }

    /// Act on whatever the picker made of a keypress.
    fn handle_picker_key(&mut self, key: KeyEvent) {
        let Some(picker) = self.picker.as_mut() else {
            return;
        };
        match picker.handle_key(key) {
            crate::picker::Action::None => {}
            crate::picker::Action::Toggle(name) => self.toggle_widget(&name),
            crate::picker::Action::Close => {
                self.picker = None;
                self.layout_notice = None;
                // Written on close rather than on every toggle: someone trying
                // three arrangements should cost one write, not three, and the
                // dialog is a natural commit point.
                self.write_layout();
            }
        }
    }

    /// Open the theme picker, remembering the theme to put back on `Esc`.
    ///
    /// The themes directory sits beside the config, so a `--config` somewhere
    /// unusual looks for themes beside *it*. With no config path — which is
    /// only ever the tests — the bundled set is the whole list.
    fn open_theme_picker(&mut self) {
        let dir = self
            .config_path
            .as_deref()
            .and_then(crate::themes::user_dir);
        let picker = crate::theme_picker::ThemePicker::new(
            self.config.theme.name.as_deref(),
            dir.as_deref(),
        )
        .with_keys(self.theme_picker_keys.clone());
        self.theme_picker = Some((picker, self.config.theme.clone()));
    }

    /// Act on whatever the theme picker made of a keypress.
    fn handle_theme_picker_key(&mut self, key: KeyEvent) {
        let Some((picker, original)) = self.theme_picker.as_mut() else {
            return;
        };
        match picker.handle_key(key) {
            crate::theme_picker::Action::None => {}
            crate::theme_picker::Action::Preview(name) => {
                let dir = self
                    .config_path
                    .as_deref()
                    .and_then(crate::themes::user_dir);
                // A theme that will not load is left as a dead row rather than
                // reported: the file is the user's own, they have just watched
                // every other name repaint the screen, and the one that does
                // nothing is legible enough. Anything louder would put an error
                // dialog on top of a colour picker.
                if let Ok(theme) = crate::themes::resolve(&name, dir.as_deref()) {
                    self.apply_theme(theme);
                }
            }
            crate::theme_picker::Action::Accept => {
                self.theme_picker = None;
                // The live theme is already the chosen one, so there is nothing
                // to apply — only to record. Written here rather than on every
                // cursor move, so browsing the list costs no writes: while the
                // dialog is open, `collect_preferences` reports the theme it
                // opened on, and closing it is what lets this one through.
                self.persist_preferences();
            }
            crate::theme_picker::Action::Cancel => {
                let restore = original.clone();
                self.theme_picker = None;
                self.apply_theme(restore);
            }
        }
    }

    /// Swap the live theme, including the colours derived from it.
    ///
    /// `gradients` is the one thing that does not read `config.theme` at draw
    /// time — it is a baked 101-entry ramp, computed once. Forgetting it here
    /// would leave the cpu and network graphs painted in the previous theme
    /// while everything around them changed, which looks like a rendering bug
    /// rather than a missing line.
    fn apply_theme(&mut self, theme: crate::theme::Theme) {
        self.config.theme = theme;
        self.gradients = self.config.theme.gradients();
    }

    /// Turn a widget on or off, rebuilding the dashboard around it.
    fn toggle_widget(&mut self, widget: &str) {
        let before = self.config.layout.clone();

        if self.config.layout.places(widget) {
            if !self.config.layout.remove_widget(widget) {
                // The last panel. An empty layout is rejected at startup, so
                // allowing this would write a config that cannot be opened.
                self.layout_notice = Some("at least one panel has to stay".into());
                return;
            }
        } else {
            self.config.layout.add_widget(widget);
        }

        // A layout that will not build is a reason to refuse the toggle, not
        // to leave the dashboard in pieces, and the picker says why.
        self.layout_notice = self.commit_layout(before).err().map(|e| format!("{e:#}"));
    }

    /// Write the layout back into the config file, if it changed.
    ///
    /// Textual, so comments and formatting survive; see [`crate::layout_edit`].
    /// A failure is kept and shown rather than swallowed — a panel you switched
    /// on that quietly fails to persist is worse than one that never appeared,
    /// because you will not find out until the next start.
    fn write_layout(&mut self) {
        if !self.layout_dirty {
            return;
        }
        let Some(path) = self.config_path.clone() else {
            return;
        };

        // Atomic, like every other file mirador writes. This used to be a bare
        // `fs::write`, which is the one place it mattered most: the target is
        // the user's own config, complete with the comments they may have edited
        // and the ones mirador wrote to explain itself, and a crash or a full
        // disk part-way through a plain overwrite leaves them a truncated file
        // and nothing to recover from.
        let result = std::fs::read_to_string(&path)
            .map_err(anyhow::Error::from)
            .and_then(|source| crate::layout_edit::apply(&source, &self.config.layout))
            .and_then(|updated| crate::store::write_atomic(&path, &updated));

        match result {
            Ok(()) => {
                self.layout_dirty = false;
                self.layout_error = None;
            }
            Err(e) => self.layout_error = Some(format!("{e:#}")),
        }
    }

    /// Why the layout could not be written, if the last attempt failed.
    ///
    /// For `main`, after [`App::run`] has returned and the terminal is back.
    /// The write on the way out is the last chance to keep a resize made a
    /// moment before quitting, and when it fails there is no status bar left
    /// to say so. Dropping it there was the one place [`App::write_layout`]'s
    /// promise not to swallow a failure did not hold.
    pub fn unsaved_layout(&self) -> Option<&str> {
        self.layout_error.as_deref()
    }

    /// The line `main` prints after restoring the terminal, if a layout change
    /// was lost on the way out. Built here so its wording is tested; `main`
    /// only prints it.
    pub fn exit_report(&self) -> Option<String> {
        self.unsaved_layout()
            .map(|why| format!("mirador: the layout could not be saved — {why}"))
    }

    /// Write layout changes to `path` from now on.
    ///
    /// Separate from [`App::new`] for the same reason the state path is: tests
    /// build apps constantly and must not be able to touch a real config.
    pub fn write_layout_to(&mut self, path: PathBuf) {
        self.config_path = Some(path);
    }

    /// Offer a key to the focused panel, then to the global bindings.
    fn dispatch_key(&mut self, key: KeyEvent) {
        // Offer the key to the focused panel first.
        if let Some(slot) = self.slots.get_mut(self.focus)
            && slot.panel.handle_key(key) == KeyOutcome::Consumed
        {
            return;
        }

        // A panel in a modal state gets an absolute veto on global bindings, so
        // typing "q" into a task title cannot quit the dashboard.
        if self.focus_captures_input() {
            return;
        }

        match self.keymap.action(key) {
            // The configured quit key and Ctrl+C only. Esc used to quit here,
            // undocumented — while the task panel prints "Nothing matches this
            // filter. Esc to clear." A panel consumes Esc only while its filter
            // is non-empty, so the same key in the same panel one keystroke
            // apart either cleared the filter or killed the dashboard, and
            // nothing on screen said which. Esc means "back out of something"
            // everywhere else, which is why the keymap will not take it.
            Some(Action::Quit) => self.should_quit = true,
            Some(Action::FocusNext) => self.cycle_focus(true),
            Some(Action::FocusPrevious) => self.cycle_focus(false),
            Some(Action::Help) => {
                self.show_help = true;
                // Opening it always starts at the top; the bindings for the
                // panel you just focused are the reason you pressed `?`.
                self.help_scroll = 0;
            }
            Some(Action::Panels) => {
                self.picker = Some(
                    crate::picker::Picker::new(self.config.widget_names())
                        .with_keys(self.panel_picker_keys.clone()),
                );
            }
            Some(Action::Theme) => self.open_theme_picker(),
            Some(Action::Arrange) => self.enter_arrange(),
            // Reached only while a panel captures input, which vetoes resizing
            // along with every other global key; see `handle_key`.
            Some(
                Action::ResizeWider
                | Action::ResizeNarrower
                | Action::ResizeTaller
                | Action::ResizeShorter,
            )
            | None => {
                self.jump_to_slot(key);
            }
        }
    }

    /// Focus the panel a digit names, `1` for the first, and say whether the
    /// key was a digit at all.
    ///
    /// A digit with no panel behind it is still a digit: it moves nothing,
    /// and it is not offered anywhere else. One place for both the dashboard
    /// and arrange mode, because `1`–`9` are the keys no table may take and
    /// the two must not come to disagree about what they do.
    fn jump_to_slot(&mut self, key: KeyEvent) -> bool {
        let KeyCode::Char(c @ '1'..='9') = key.code else {
            return false;
        };
        let index = c as usize - '1' as usize;
        if index < self.slots.len() {
            self.focus = index;
        }
        true
    }

    /// Move `step` weight from `donor` to `taker` within a set of weights,
    /// leaving the total untouched.
    ///
    /// Keeping the total fixed is what makes this feel like tmux: widening one
    /// panel narrows its neighbour and nothing else on screen moves. Scaling a
    /// single weight instead would silently reflow every other panel in the row.
    fn transfer(weights: &mut [u16], taker: usize, donor: usize) -> bool {
        let total: u32 = weights.iter().map(|w| u32::from(*w)).sum();
        // Step with the scale of the config rather than a fixed number of
        // units: weights are relative, so `width = 60` and `width = 3` are both
        // legitimate ways to write the same layout.
        let step = u16::try_from(total / 50).unwrap_or(1).max(1);

        let (Some(&grows), Some(&shrinks)) = (weights.get(taker), weights.get(donor)) else {
            return false;
        };
        // Never squeeze a panel out of existence — a panel that vanished could
        // not be focused, and so could not be given its space back.
        let step = step.min(shrinks.saturating_sub(MIN_WEIGHT));
        if step == 0 {
            return false;
        }
        weights[taker] = grows.saturating_add(step);
        weights[donor] = shrinks - step;
        true
    }

    /// Widen or narrow the focused panel against its neighbour in the row.
    fn resize_width(&mut self, grow: bool) -> bool {
        let Some((row, column)) = self.focused_position() else {
            return false;
        };
        let Some(entry) = self.config.layout.rows.get_mut(row) else {
            return false;
        };
        // Borrow from the panel to the right, or from the left when the focused
        // panel is last in its row.
        let Some(neighbour) = neighbour_of(column, entry.panels.len()) else {
            return false;
        };

        let mut weights: Vec<u16> = entry.panels.iter().map(|p| p.width).collect();
        let (taker, donor) = if grow {
            (column, neighbour)
        } else {
            (neighbour, column)
        };
        if !Self::transfer(&mut weights, taker, donor) {
            return false;
        }
        for (panel, weight) in entry.panels.iter_mut().zip(weights) {
            panel.width = weight;
        }
        true
    }

    /// Grow or shrink the focused panel's row against the neighbouring row.
    fn resize_height(&mut self, grow: bool) -> bool {
        let Some((row, _)) = self.focused_position() else {
            return false;
        };
        let rows = &mut self.config.layout.rows;
        let Some(neighbour) = neighbour_of(row, rows.len()) else {
            return false;
        };

        let mut weights: Vec<u16> = rows.iter().map(|r| r.height).collect();
        let (taker, donor) = if grow {
            (row, neighbour)
        } else {
            (neighbour, row)
        };
        if !Self::transfer(&mut weights, taker, donor) {
            return false;
        }
        for (entry, weight) in rows.iter_mut().zip(weights) {
            entry.height = weight;
        }
        true
    }

    /// The panel whose interior contains this point, if any.
    fn panel_at(&self, column: u16, row: u16) -> Option<usize> {
        self.slots.iter().position(|slot| {
            slot.area
                .is_some_and(|area| area.contains(Position::new(column, row)))
        })
    }

    /// Route a mouse event, returning whether the screen needs redrawing.
    ///
    /// Click focuses the panel under the pointer and is then offered to it;
    /// scroll is offered to the panel under the pointer *without* moving focus,
    /// so running the wheel over a list does not yank the keyboard away from
    /// whatever the user was working in.
    fn handle_mouse(&mut self, event: MouseEvent) -> bool {
        let interesting = matches!(
            event.kind,
            MouseEventKind::Down(_) | MouseEventKind::ScrollUp | MouseEventKind::ScrollDown
        );
        if !interesting {
            // Motion and button-release arrive constantly and mean nothing
            // here. Returning false is what keeps the redraw loop quiet.
            return false;
        }

        // A deliberate click or scroll retires the update notice, as a key
        // does. Pointer motion deliberately does not: the mouse crossing the
        // window on its way somewhere else is not the user reading anything.
        let had_hint = std::mem::take(&mut self.show_update_hint);

        // The help overlay swallows the next input, whatever it is — the same
        // rule keys follow.
        if self.show_help {
            self.show_help = false;
            return true;
        }

        // A shell dialog owns the keyboard while it is open, and the mouse
        // with it. None of them reads the pointer, so the event goes nowhere:
        // offered to the panels it fell through the dialog, and a click moved
        // focus to a panel beneath and selected a row nobody could see.
        if self.picker.is_some() || self.theme_picker.is_some() || self.keymap_dialog.is_some() {
            return had_hint;
        }

        // A panel in a text-entry or modal state gets the same absolute veto
        // over the mouse that it has over global keys: a stray click must not
        // pull focus out of a half-typed task and strand the form.
        if self.focus_captures_input() {
            let focus = self.focus;
            let Some(area) = self.slots.get(focus).and_then(|slot| slot.area) else {
                return had_hint;
            };
            if !area.contains(Position::new(event.column, event.row)) {
                return had_hint;
            }
            let consumed = self
                .slots
                .get_mut(focus)
                .is_some_and(|slot| slot.panel.handle_mouse(event, area) == KeyOutcome::Consumed);
            return consumed || had_hint;
        }

        let Some(index) = self.panel_at(event.column, event.row) else {
            return had_hint;
        };

        let focus_moved = if matches!(event.kind, MouseEventKind::Down(_)) {
            let moved = self.focus != index;
            self.focus = index;
            moved
        } else {
            false
        };

        let Some(slot) = self.slots.get_mut(index) else {
            return focus_moved || had_hint;
        };
        let Some(area) = slot.area else {
            return focus_moved || had_hint;
        };
        let consumed = slot.panel.handle_mouse(event, area) == KeyOutcome::Consumed;
        consumed || focus_moved || had_hint
    }

    /// Move focus one panel forward or backward, wrapping at both ends.
    fn cycle_focus(&mut self, forward: bool) {
        let len = self.slots.len();
        if len == 0 {
            return;
        }
        self.focus = if forward {
            (self.focus + 1) % len
        } else {
            (self.focus + len - 1) % len
        };
    }

    /// Where the focused panel sits in `config.layout`, as `(row, column)`.
    fn focused_position(&self) -> Option<(usize, usize)> {
        self.slots.get(self.focus).map(|slot| slot.position)
    }

    /// Compute one rectangle per panel, in the same row-major order as
    /// `self.slots`.
    ///
    /// Two passes of [`distribute`]: heights down the rows, then widths across
    /// each row. Both honour the panels' declared maxima, so a panel that
    /// cannot use more space passes it to one that can.
    fn geometry(&self, area: Rect) -> Vec<Rect> {
        let rows = &self.config.layout.rows;

        // The slot each layout entry built, from one walk of the slots. An
        // entry that built no panel stays `None`: a hole, which the rows and
        // columns below leave empty rather than closing up.
        let mut built: Vec<Vec<Option<usize>>> = rows
            .iter()
            .map(|row| vec![None; row.panels.len()])
            .collect();
        for (index, slot) in self.slots.iter().enumerate() {
            let (row, column) = slot.position;
            if let Some(entry) = built.get_mut(row).and_then(|row| row.get_mut(column)) {
                *entry = Some(index);
            }
        }

        let row_weights: Vec<u16> = rows.iter().map(|row| row.height.max(1)).collect();
        // A row is only bounded when every panel in it is: they share the
        // height, so one unbounded panel keeps the whole row unbounded.
        let row_maxima: Vec<Option<u16>> = built
            .iter()
            .map(|row| {
                let mut tallest = 0u16;
                for slot in row {
                    let max = slot.and_then(|slot| self.slots[slot].panel.max_height())?;
                    tallest = tallest.max(max);
                }
                (tallest > 0).then_some(tallest)
            })
            .collect();

        let heights = distribute(area.height, &row_weights, &row_maxima);

        // Indexed by slot, not by layout column. Pushing one rect per column
        // assumes every layout entry produced a panel; a single entry that did
        // not shifts every later slot onto the previous entry's rectangle,
        // which is what `slot.area` hit-tests, so clicks land on the wrong
        // panel. A slot that gets no rectangle keeps the zero one and is
        // skipped by the caller's size check.
        let mut rects = vec![Rect::default(); self.slots.len()];
        let mut y = area.y;
        for (row_index, (row, slots)) in rows.iter().zip(&built).enumerate() {
            let height = heights.get(row_index).copied().unwrap_or(0);

            let widths: Vec<u16> = row.panels.iter().map(|p| p.width.max(1)).collect();
            let maxima: Vec<Option<u16>> = slots
                .iter()
                .map(|slot| slot.and_then(|slot| self.slots[slot].panel.max_width()))
                .collect();
            let columns = distribute(area.width, &widths, &maxima);

            let mut x = area.x;
            for (slot, width) in slots.iter().zip(columns) {
                if let Some(slot) = *slot {
                    rects[slot] = Rect::new(x, y, width, height);
                }
                x = x.saturating_add(width);
            }
            y = y.saturating_add(height);
        }
        rects
    }

    /// Which row the open picker is on, for tests that drive it by keystroke.
    #[cfg(test)]
    fn picker_row(&self) -> Option<usize> {
        self.picker.as_ref().map(crate::picker::Picker::selected)
    }

    /// The dashboard `config` lays out, from panels already built rather than
    /// through `widgets::build` — which, under test, refuses the weather,
    /// markets and news panels, because each starts a fetch thread that goes
    /// straight to the network. A test wanting the whole default dashboard
    /// hands over the offline panels instead.
    ///
    /// Each layout entry takes the first unused panel of its widget, in the
    /// row-major order `new` builds in. An entry with none to take is an
    /// error, as a panel that will not build is to `new`, and panels nothing
    /// in the layout takes are dropped.
    #[cfg(test)]
    pub fn with_panels(config: Config, mut panels: Vec<(&str, Box<dyn Panel>)>) -> Result<Self> {
        let mut slots = Vec::new();
        for (row_index, row) in config.layout.rows.iter().enumerate() {
            for (column_index, entry) in row.panels.iter().enumerate() {
                let index = panels
                    .iter()
                    .position(|(widget, _)| *widget == entry.widget)
                    .with_context(|| format!("no `{}` panel was supplied", entry.widget))?;
                let (_, panel) = panels.remove(index);
                slots.push(Slot {
                    widget: entry.widget.clone(),
                    panel,
                    position: (row_index, column_index),
                    last_tick: None,
                    area: None,
                });
            }
        }
        Self::around(config, slots)
    }

    /// Test-only access to the private render pass.
    #[cfg(test)]
    pub fn render_for_test(&mut self, frame: &mut ratatui::Frame) {
        self.render(frame);
    }

    fn render(&mut self, frame: &mut ratatui::Frame) {
        let area = frame.area();

        let body = if self.config.general.show_status_bar && area.height > 1 {
            let parts = Layout::vertical([Constraint::Min(1), Constraint::Length(1)]).split(area);
            self.render_status_bar(frame, parts[1]);
            parts[0]
        } else {
            area
        };

        let rects = self.geometry(body);
        let theme = &self.config.theme;
        let focus = self.focus;

        for (index, slot) in self.slots.iter_mut().enumerate() {
            // Cleared first so a panel that fails to draw this pass cannot keep
            // catching clicks at the place it used to be.
            slot.area = None;

            let Some(rect) = rects.get(index).copied() else {
                continue;
            };
            if rect.width == 0 || rect.height == 0 {
                continue;
            }

            let focused = index == focus;
            let title = slot.panel.title();
            let spec = FrameSpec {
                title: &title,
                counter: slot.panel.counter(),
                focused,
                bindings: slot.panel.bindings(),
                index: index + 1,
            };
            let inner = crate::frame::draw(frame, rect, theme, &spec);

            if inner.width == 0 || inner.height == 0 {
                continue;
            }
            slot.area = Some(inner);

            slot.panel.render(
                frame,
                inner,
                RenderContext {
                    theme,
                    gradients: &self.gradients,
                    focused,
                    watch: &self.watch,
                },
            );
        }

        // Panel dialogs, before the shell's own overlays and after every
        // panel: drawn any earlier and the panels following the one that owns
        // the dialog paint straight over it.
        for slot in &self.slots {
            if let Some(prompt) = slot.panel.overlay() {
                prompt.render(frame, area, &self.config.theme);
            }
        }

        if self.show_help {
            self.render_help(frame, area);
        }
        // Listed only while the key map is open; the draw pays for nothing
        // otherwise.
        let panel_keys = if self.keymap_dialog.is_some() {
            self.panel_keys()
        } else {
            Vec::new()
        };
        if let Some(dialog) = self.keymap_dialog.as_mut() {
            dialog.render(
                frame,
                area,
                &self.keymap,
                &panel_keys,
                self.config_path.as_deref(),
                &self.config.theme,
            );
        }
        if let Some((picker, _)) = &self.theme_picker {
            picker.render(frame, area, &self.config.theme);
        }
        if let Some(picker) = &self.picker {
            picker.render(
                frame,
                area,
                &self.config.theme,
                |name| self.config.layout.places(name),
                // What was just refused, or else why the last write failed.
                self.layout_notice
                    .as_deref()
                    .or(self.layout_error.as_deref()),
            );
        }
    }

    /// The status bar carries *global* bindings only.
    ///
    /// Panel bindings live in the focused panel's own border, which keeps the
    /// two scopes visually separate. A flat list of both teaches users to press
    /// panel keys while the wrong panel is focused.
    fn render_status_bar(&self, frame: &mut ratatui::Frame, area: Rect) {
        let theme = &self.config.theme;
        let key_style = Style::default().fg(theme.key).add_modifier(Modifier::BOLD);
        let muted = Style::default().fg(theme.muted);

        // In arrange mode the bar belongs to the mode. The global keys are not
        // reachable anyway — the arrows have been claimed — so listing them
        // would be listing keys that do nothing.
        //
        // This also hides an alert for as long as the mode is open, which is a
        // decision rather than an oversight. Arrange mode is a gesture measured
        // in seconds and the legend is what makes it usable; an alert that
        // waits until `Enter` or `Esc` has lost nothing, because the thing it
        // names has already happened either way.
        if self.arranging.is_some() {
            let spans = vec![Span::styled(
                " ARRANGE",
                Style::default()
                    .fg(theme.accent)
                    .add_modifier(Modifier::BOLD),
            )];
            // Which arrow moves along the row and which moves between rows is
            // self-evident the moment you press one, because the panels move.
            // What is *not* evident is that there is a row past the last one,
            // so the width saved by collapsing the first two entries into
            // "move" is spent saying so. Someone had to ask.
            //
            // Ordered so that the two that matter most survive a narrow
            // terminal: knowing how to get out of a mode beats knowing every
            // trick inside it.
            let mut parts = vec![spans];
            // Both vertical hints were shortened when `Shift+↑↓` was added in
            // #100: a sixth entry does not fit beside the old wording at an
            // ordinary 110 columns, and dropping one was not an option —
            // the help overlay carries only the *global* keys, so this legend
            // is the only place any of these are documented. A key that ships
            // undiscoverable is the mistake the resize keys already made once.
            //
            // Derived from `[arrange.keys]` and the shell's resize keys, so a
            // key moved in either is shown where it went.
            let legend =
                crate::keymap::arrange_legend(&self.arrange_keys, self.keymap.resize_bindings());
            for binding in legend {
                // Dropped whole rather than clipped: half a hint reads as a
                // rendering fault, where a missing one just reads as a narrow
                // terminal. The gap leads the hint it introduces, so a dropped
                // hint takes its gap with it.
                parts.push(vec![
                    Span::styled(HINT_GAP, muted),
                    Span::styled(binding.key, key_style),
                    Span::styled(format!(" {}", binding.action), muted),
                ]);
            }
            frame.render_widget(
                Paragraph::new(crate::grid::assemble(parts, area.width)),
                area,
            );
            return;
        }

        let spans = vec![Span::styled(
            " mirador",
            Style::default()
                .fg(theme.accent)
                .add_modifier(Modifier::BOLD),
        )];

        // Dropped whole rather than clipped, exactly as the arrange legend
        // above does it: half a hint reads as a rendering fault, a missing one
        // reads as a narrow terminal. This bar had no such guard and did not
        // need one while every primary was a single character — `t theme` was
        // the widest thing in it. Promoting the resize keys made it need one:
        // at 80 columns the bar ended `Ctrl+←`.
        let mut parts = vec![spans];
        for binding in self.keymap.bindings().iter().filter(|b| b.primary) {
            parts.push(vec![
                Span::styled(HINT_GAP, muted),
                Span::styled(binding.key.clone(), key_style),
                Span::styled(format!(" {}", binding.action), muted),
            ]);
        }

        // An alert takes the whole bar rather than sharing it. It outranks the
        // update notice, which does not get worse while you read the alert,
        // and it outranks the key list too, because the *reason* is the
        // actionable part and squeezing it in beside `Tab focus` truncated it
        // to "read-only file syste…". The keys are behind `?`, and an alert is
        // gone as soon as the thing it names is.
        if let Some(alert) = self.alert() {
            frame.render_widget(
                Paragraph::new(alert_line(&alert.text, area.width, theme)),
                area,
            );
            return;
        }

        // The hint rides on the right of the bar it shares with the global
        // keys, and gives way to them when the terminal is too narrow: knowing
        // how to quit matters more than knowing what you are not using.
        let mut line = crate::grid::assemble(parts, area.width);
        if let Some(hint) = self.update_hint() {
            let used: usize = line
                .spans
                .iter()
                .map(|s| crate::grid::display_width(&s.content))
                .sum();
            let hint_width = crate::grid::display_width(&hint);
            let total = usize::from(area.width);
            // One space of breathing room on each side of the gap.
            if used + hint_width + 3 <= total {
                line.spans.push(Span::styled(
                    " ".repeat(total - used - hint_width - 1),
                    muted,
                ));
                line.spans
                    .push(Span::styled(hint, Style::default().fg(theme.label)));
            }
        }

        frame.render_widget(Paragraph::new(line), area);
    }

    /// The single most pressing thing, if anything is pressing.
    ///
    /// Absent almost always, which is the point — see [`crate::panel::Alert`].
    /// There is no all-clear: an indicator that says everything is fine is a
    /// light you have to read in order to learn nothing, and reading it is work
    /// a dashboard should not ask for.
    fn alert(&self) -> Option<crate::panel::Alert> {
        // The layout write is the one genuine silent failure in the program.
        // It is reported inside the `w` picker and nowhere else, so a
        // rearrangement that fails to persist says nothing at all once the
        // picker closes — and the change is gone at the next launch.
        let own = self.layout_error.as_ref().map(|why| {
            crate::panel::Alert::failing(format!("The layout could not be saved — {why}"))
        });

        self.slots
            .iter()
            .filter_map(|slot| slot.panel.alert())
            .chain(own)
            // Most severe wins, and the newest of equals — with two levels and
            // both near-never, which one shows barely matters; that it is only
            // ever *one* does.
            .max_by_key(|alert| alert.severity)
    }

    /// Watch `found` for a newer version from now on.
    ///
    /// Separate from [`App::new`] for the same reason the state path is: tests
    /// build apps constantly, and none of them should be able to start a
    /// network request by accident.
    pub fn watch_for_updates(&mut self, found: crate::update::Found) {
        self.update = found;
    }

    /// The update notice, if there is one and it has not been dismissed.
    ///
    /// Rare, actionable now, and it stops being true the moment you act on it —
    /// which is what earned it a place on the bar when the unused-widget hint,
    /// the same every launch until you changed your layout, lost its own.
    fn update_hint(&self) -> Option<String> {
        if !self.show_update_hint {
            return None;
        }
        let latest = self
            .update
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .clone()?;
        Some(format!("mirador {latest} is out   mirador --update "))
    }

    /// The overlay's text: the global keys, then the focused panel's own.
    ///
    /// Split out from `render_help` because that function reached clippy's
    /// hundred-line limit — the same wall `run()` hit when #177 and #182 landed
    /// together. The seam is a real one either way: this half decides what the
    /// overlay *says*, the other half where it sits.
    fn help_lines(
        global: &[Binding],
        panel: Option<(&str, &[Binding])>,
        theme: &crate::theme::Theme,
    ) -> Vec<Line<'static>> {
        let key_style = Style::default().fg(theme.key).add_modifier(Modifier::BOLD);
        let muted = Style::default().fg(theme.muted);

        let section = |title: &str| {
            Line::from(Span::styled(
                crate::glyphs::utility(title),
                Style::default()
                    .fg(theme.label)
                    .add_modifier(Modifier::BOLD),
            ))
        };

        let panel_keys: &[Binding] = panel.map_or(&[], |(_, keys)| keys);
        // Sized to the widest key on show rather than to a constant. The
        // constant was 12, the width of the longest key the program has, so
        // `q` was followed by eleven spaces in every overlay ever drawn and the
        // actions began a third of the way across a 46-cell popup. Still capped
        // at 12: a plugin names its own keys, and one long enough to push the
        // actions off the edge would be a plugin deciding how this dialog is
        // laid out.
        let key_column = global
            .iter()
            .chain(panel_keys)
            .map(|binding| crate::grid::display_width(&binding.key).min(12))
            .max()
            .unwrap_or(1);
        let entry = |binding: &Binding| {
            let key = crate::grid::truncate(&binding.key, key_column);
            let padding = " ".repeat(key_column.saturating_sub(crate::grid::display_width(&key)));
            Line::from(vec![
                Span::styled(format!("  {key}{padding}  "), key_style),
                Span::styled(binding.action.to_string(), muted),
            ])
        };

        let mut lines = vec![section("global")];
        lines.extend(global.iter().map(entry));

        // Bindings are grouped by the panel they belong to, so it is always
        // clear which panel a key acts on.
        if let Some((title, keys)) = panel.filter(|(_, keys)| !keys.is_empty()) {
            lines.push(Line::from(""));
            lines.push(section(title));
            lines.extend(keys.iter().map(entry));
        }
        lines
    }

    fn render_help(&mut self, frame: &mut ratatui::Frame, area: Rect) {
        let theme = &self.config.theme;

        let panel_title = self.slots.get(self.focus).map(|slot| slot.panel.title());
        let lines = Self::help_lines(
            self.keymap.bindings(),
            self.slots
                .get(self.focus)
                .zip(panel_title.as_deref())
                .map(|(slot, title)| (title, slot.panel.bindings())),
            theme,
        );

        // The footer is rendered separately and pinned to the last row, rather
        // than being the last line of the scrolling text. A hint saying how to
        // close the overlay is no use once it has scrolled out of the overlay.
        //
        // The overlay is 46 cells wide, frame included. The key column's
        // comment in `help_lines` and the doc of the test that sizes it both
        // quote that figure, so they move with it.
        let width = 46.min(area.width);
        let text_width = width.saturating_sub(crate::frame::FRAME_WIDTH).max(1);
        // Pre-wrap with Mirador's cell-aware rules. The focused panel may be an
        // external process, so handing its binding text to ratatui's wrapper
        // would give plugin-controlled emoji and combining marks a known panic
        // path in the host renderer.
        let lines: Vec<Line<'static>> = lines
            .iter()
            .flat_map(|line| crate::grid::wrap_line(line, text_width))
            .collect();
        let text_height = u16::try_from(lines.len()).unwrap_or(u16::MAX);
        let body = Paragraph::new(lines);

        // Borders, the blank line, and the footer.
        let chrome = 4;
        let height = text_height.saturating_add(chrome).min(area.height);
        let popup = crate::frame::centred(area, width, height);

        frame.render_widget(Clear, popup);
        let block = Block::default()
            .borders(Borders::ALL)
            .border_type(BorderType::Rounded)
            .border_style(Style::default().fg(theme.border_focused))
            .padding(Padding::horizontal(1))
            .title_top(Line::from(vec![
                Span::styled("┤", Style::default().fg(theme.border_focused)),
                Span::styled(
                    "Keys",
                    Style::default()
                        .fg(theme.title)
                        .add_modifier(Modifier::BOLD),
                ),
                Span::styled("├", Style::default().fg(theme.border_focused)),
            ]))
            // Right-aligned in the border, the way every panel shows its
            // counter — `?` is where someone goes to find out what the thing
            // does, so it is also where they will look for what version it is,
            // and the border costs no rows to say so.
            .title_top(
                Line::from(vec![
                    Span::styled("┤", Style::default().fg(theme.border_focused)),
                    Span::styled(
                        concat!("v", env!("CARGO_PKG_VERSION")),
                        Style::default().fg(theme.muted),
                    ),
                    Span::styled("├", Style::default().fg(theme.border_focused)),
                ])
                .right_aligned(),
            );
        let inner = block.inner(popup);
        frame.render_widget(block, popup);

        if inner.height == 0 {
            self.help_overflow = 0;
            self.help_viewport = 0;
            return;
        }

        // Give the footer the last row and the blank line the one above it,
        // but never at the cost of showing no text at all.
        let footer_rows = 2.min(inner.height.saturating_sub(1));
        let viewport = Rect {
            height: inner.height - footer_rows,
            ..inner
        };

        self.help_viewport = viewport.height;
        self.help_overflow = text_height.saturating_sub(viewport.height);
        // The terminal may have shrunk since the last frame, or the focused
        // panel changed to one with fewer bindings.
        self.help_scroll = self.help_scroll.min(self.help_overflow);

        frame.render_widget(body.scroll((self.help_scroll, 0)), viewport);

        if footer_rows > 0 {
            let footer = Rect {
                y: inner.y + inner.height - 1,
                height: 1,
                ..inner
            };
            frame.render_widget(
                Paragraph::new(self.help_footer(theme, footer.width)),
                footer,
            );
        }
    }

    /// The pinned last row of the help overlay.
    ///
    /// It says how to close the overlay, and when there is more text than fits,
    /// that scrolling is possible and where in the list you are. Without the
    /// position there is no way to tell a full list from a truncated one — so
    /// when there is a position it comes first, ahead of the way to the key
    /// map, and the close hint is short enough that all three fit the
    /// overlay's fixed width, three-digit counts included.
    ///
    /// Each separator leads the part it introduces, so a part dropped for
    /// want of width takes its `·` with it. The first version put the
    /// separator after `? key map`, and was two cells too wide besides: an
    /// overlay that scrolled showed `? key map ·` and nothing else, the
    /// position and the way out both gone.
    /// `the_help_footer_keeps_its_position_and_ends_on_no_separator` pins it.
    fn help_footer(&self, theme: &crate::theme::Theme, width: u16) -> Line<'static> {
        let italic = Style::default()
            .fg(theme.muted)
            .add_modifier(Modifier::ITALIC);
        let key_style = Style::default().fg(theme.key).add_modifier(Modifier::BOLD);

        let mut parts: Vec<Vec<Span<'static>>> = Vec::new();
        let mut push = |mut part: Vec<Span<'static>>| {
            if !parts.is_empty() {
                part.insert(0, Span::styled(" · ", italic));
            }
            parts.push(part);
        };

        if self.help_overflow > 0 {
            let more_above = self.help_scroll > 0;
            let more_below = self.help_scroll < self.help_overflow;
            // The keys that scroll, from `[help_overlay.keys]`: `↑↓` at the
            // defaults, and whatever the reader moved them to otherwise.
            let arrows = crate::keymap::help_scroll_hint(&self.help_keys, more_above, more_below);
            // The count is spaced from the keys, and needs no space when
            // there are none to be spaced from.
            let gap = if arrows.is_some() { " " } else { "" };
            push(vec![
                Span::styled(arrows.unwrap_or_default(), key_style),
                Span::styled(
                    format!(
                        "{gap}{}/{}",
                        self.help_scroll + self.help_viewport,
                        self.help_overflow + self.help_viewport,
                    ),
                    italic,
                ),
            ]);
        }
        // The way to the key map, and the only place it is advertised.
        if let Some(help) = self.keymap.keys(Action::Help).first() {
            push(vec![
                Span::styled(help.to_string(), key_style),
                Span::styled(" key map", italic),
            ]);
        }
        push(vec![Span::styled(
            if self.help_overflow > 0 {
                "other keys close"
            } else {
                "any key to close"
            },
            italic,
        )]);
        crate::grid::assemble(parts, width)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::{Layout as LayoutConfig, LayoutPanel, LayoutRow};
    use crate::store::testing::TempDir;

    /// A config whose layout is only panels that need no I/O.
    fn config_with(widgets: &[&str]) -> Config {
        Config {
            layout: LayoutConfig {
                rows: vec![LayoutRow {
                    height: 1,
                    panels: widgets
                        .iter()
                        .map(|w| LayoutPanel {
                            widget: (*w).to_string(),
                            width: 1,
                        })
                        .collect(),
                }],
            },
            ..Config::default()
        }
    }

    /// A two-row layout with two panels in the first row, all on a 100 scale.
    fn resizable() -> Config {
        Config {
            layout: LayoutConfig {
                rows: vec![
                    LayoutRow {
                        height: 50,
                        panels: vec![
                            LayoutPanel {
                                widget: "clocks".into(),
                                width: 50,
                            },
                            LayoutPanel {
                                widget: "calendar".into(),
                                width: 50,
                            },
                        ],
                    },
                    LayoutRow {
                        height: 50,
                        panels: vec![LayoutPanel {
                            widget: "cpu".into(),
                            width: 100,
                        }],
                    },
                ],
            },
            ..Config::default()
        }
    }

    /// The status bar as drawn at `width`, with styling dropped.
    fn status_bar_at(app: &mut App, width: u16) -> String {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let mut terminal = Terminal::new(TestBackend::new(width, 1)).expect("backend");
        terminal
            .draw(|frame| app.render_status_bar(frame, Rect::new(0, 0, width, 1)))
            .expect("draws");
        crate::widgets::testing::rows(terminal.backend().buffer()).concat()
    }

    fn widths(app: &App) -> Vec<u16> {
        app.config.layout.rows[0]
            .panels
            .iter()
            .map(|p| p.width)
            .collect()
    }

    fn heights(app: &App) -> Vec<u16> {
        app.config.layout.rows.iter().map(|r| r.height).collect()
    }

    /// The whole grid as widget names, which is what a move is supposed to
    /// change and what a cancelled one is supposed to restore.
    fn widgets_by_row(app: &App) -> Vec<Vec<String>> {
        app.config
            .layout
            .rows
            .iter()
            .map(|row| row.panels.iter().map(|p| p.widget.clone()).collect())
            .collect()
    }

    #[test]
    fn widening_a_panel_narrows_its_neighbour_and_holds_the_total() {
        let mut app = App::new(resizable()).unwrap();
        let before: u16 = widths(&app).iter().sum();

        assert!(app.resize_width(true));
        let after = widths(&app);
        assert!(after[0] > 50, "focused panel must grow: {after:?}");
        assert!(after[1] < 50, "its neighbour must give the space up");
        assert_eq!(
            after.iter().sum::<u16>(),
            before,
            "the row total must not drift, or every panel reflows"
        );
    }

    #[test]
    fn narrowing_is_the_exact_inverse_of_widening() {
        let mut app = App::new(resizable()).unwrap();
        let before = widths(&app);
        assert!(app.resize_width(true));
        assert!(app.resize_width(false));
        assert_eq!(widths(&app), before);
    }

    #[test]
    fn the_last_panel_in_a_row_borrows_from_the_one_before_it() {
        let mut app = App::new(resizable()).unwrap();
        app.focus = 1;
        assert!(app.resize_width(true));
        let after = widths(&app);
        assert!(after[1] > 50, "the last panel must still be able to grow");
        assert!(after[0] < 50);
    }

    #[test]
    fn a_panel_alone_in_its_row_cannot_be_resized_horizontally() {
        let mut app = App::new(resizable()).unwrap();
        // The cpu panel is the only one in row 1; there is nobody to take
        // space from, and stretching it alone would mean nothing.
        app.focus = 2;
        assert!(!app.resize_width(true));
        assert!(!app.resize_width(false));
    }

    #[test]
    fn resizing_height_trades_between_rows() {
        let mut app = App::new(resizable()).unwrap();
        let before: u16 = heights(&app).iter().sum();
        assert!(app.resize_height(true));
        let after = heights(&app);
        assert!(after[0] > 50 && after[1] < 50, "{after:?}");
        assert_eq!(after.iter().sum::<u16>(), before);
    }

    #[test]
    fn a_panel_can_never_be_squeezed_out_of_existence() {
        let mut app = App::new(resizable()).unwrap();
        // Far more presses than it takes to consume the neighbour entirely.
        for _ in 0..500 {
            app.resize_width(true);
        }
        let after = widths(&app);
        assert!(
            after[1] >= MIN_WEIGHT,
            "a panel squeezed to nothing can never be focused to get its space back: {after:?}"
        );
        assert_eq!(after.iter().sum::<u16>(), 100, "total still holds");
    }

    /// The mode has to say that there is a row past the last one. Someone read
    /// `↑↓ move rows`, took it to mean "move between the rows that exist", and
    /// asked how to make a new one — which the mode had done all along.
    #[test]
    fn the_arrange_legend_says_a_row_can_be_opened() {
        let mut app = App::new(resizable()).expect("builds");
        app.handle_key(KeyEvent::from(KeyCode::Char('m')));

        let bar = status_bar_at(&mut app, 110);
        assert!(bar.contains("ARRANGE"), "the mode names itself: {bar}");
        assert!(
            bar.contains("new row"),
            "and says rows can be opened: {bar}"
        );
        // #100 added `Shift+↑↓`, and this legend is the only place the mode's
        // keys are written down — the help overlay carries global keys only. So
        // an ordinary terminal has to show every one of them, which is what
        // forced both vertical hints to be shortened rather than one dropped.
        assert!(
            bar.contains("move row"),
            "and says a row can be moved: {bar}"
        );
    }

    /// The resize keys shipped as `extra` and so appeared only behind `?`.
    /// The owner went looking for them in the status bar, did not find them,
    /// and concluded the feature did not exist — which is the whole argument
    /// for `primary`, and the same failure #109 and #117 already made.
    #[test]
    fn the_resize_keys_are_advertised_on_the_status_bar() {
        let mut app = App::new(resizable()).expect("builds");
        let bar = status_bar_at(&mut app, 120);
        assert!(
            bar.contains("Ctrl+←→↑↓ resize"),
            "resize must be advertised where someone looking for it will look: {bar}"
        );
    }

    /// The bar is built from one table, so a hint cannot be worded differently
    /// in two places — but it *can* be worded differently from the legend and
    /// `--help`, which are separate strings. All three say `Ctrl+←→↑↓`.
    #[test]
    fn the_resize_hint_is_worded_the_way_arrange_mode_words_it() {
        let mut app = App::new(resizable()).expect("builds");
        let plain = status_bar_at(&mut app, 120);
        app.handle_key(KeyEvent::from(KeyCode::Char('m')));
        let legend = status_bar_at(&mut app, 120);
        assert!(
            plain.contains("Ctrl+←→↑↓ resize") && legend.contains("Ctrl+←→↑↓ resize"),
            "the same key must read the same in both bars:\n  {plain}\n  {legend}"
        );
    }

    /// Every width must show whole hints or none — never a fragment. This is
    /// the property the arrange legend has always had and this bar did not:
    /// while every primary was one character the shortfall never showed, and
    /// promoting the resize hint made it show at 80 columns as `Ctrl+←`.
    /// Now that the hint is itself four arrows, a fragment of it would read as
    /// a plausible narrower binding, which is the same fault wearing a
    /// better disguise.
    ///
    /// Asserted by construction rather than by looking for a fragment: the
    /// drawn bar has to be one of the prefixes that end on a hint boundary,
    /// which no partial hint can be.
    #[test]
    fn the_status_bar_never_draws_half_a_hint() {
        let mut app = App::new(resizable()).expect("builds");

        let mut whole = Vec::new();
        let mut acc = String::from(" mirador");
        whole.push(acc.clone());
        for binding in app.keymap.bindings().iter().filter(|b| b.primary) {
            acc.push_str(HINT_GAP);
            acc.push_str(&binding.key);
            acc.push(' ');
            acc.push_str(&binding.action);
            whole.push(acc.clone());
        }

        for width in 8..200u16 {
            let bar = status_bar_at(&mut app, width);
            let drawn = bar.trim_end().to_string();
            assert!(
                whole.contains(&drawn),
                "the bar was cut mid-hint at {width}: {drawn:?}"
            );
            assert!(
                crate::grid::display_width(&drawn) <= usize::from(width),
                "the bar overflowed at {width}: {drawn:?}"
            );
        }
    }

    /// A terminal too narrow for every hint keeps the ones that get you out.
    /// Half a hint reads as a rendering fault; a missing one reads as a narrow
    /// terminal, which is what it is.
    #[test]
    fn a_narrow_arrange_legend_drops_whole_hints_and_keeps_the_way_out() {
        let mut app = App::new(resizable()).expect("builds");
        app.handle_key(KeyEvent::from(KeyCode::Char('m')));

        for width in 40..110u16 {
            let bar = status_bar_at(&mut app, width);
            assert!(
                crate::grid::display_width(bar.trim_end()) <= usize::from(width),
                "the bar overflowed at {width}: {bar}"
            );
            if width >= 46 {
                assert!(bar.contains("Esc cancel"), "no way out at {width}: {bar}");
            }
        }
    }

    /// The day turning is the one source that always fires, which is what
    /// stops the watch log looking broken on a dashboard with no calendar and
    /// nothing falling due. It lives in the shell rather than a panel so that
    /// switching off the task list cannot take it away.
    #[test]
    fn the_day_turning_is_recorded_whatever_panels_are_placed() {
        // Only a clock: neither of the panels that report events is here.
        let mut app = App::new(config_with(&["clocks"])).expect("builds");
        assert!(app.watch.entries().next().is_none(), "nothing yet");

        // Wind the remembered day back, which is what a night does.
        app.today = app.today.yesterday().expect("a day before today exists");
        assert!(app.collect_events(), "the rollover is worth a redraw");

        let entry = app.watch.entries().next().expect("an entry was recorded");
        assert!(
            entry.text.ends_with("began"),
            "reads as a day divider: {}",
            entry.text
        );

        // And only once — a second pass on the same day adds nothing.
        assert!(!app.collect_events(), "the same day is not news twice");
        assert_eq!(app.watch.entries().count(), 1);
    }

    /// The layout write is the one thing in the program that could fail
    /// silently: it was reported inside the `w` picker and nowhere else, so a
    /// rearrangement that did not persist said nothing once the picker closed,
    /// and the change was gone at the next launch.
    #[test]
    fn a_layout_that_would_not_save_reaches_the_status_bar() {
        let mut app = App::new(resizable()).expect("builds");
        assert!(app.alert().is_none(), "nothing is wrong yet");

        app.layout_error = Some("read-only file system (os error 30)".into());
        let alert = app.alert().expect("an alert");
        assert_eq!(alert.severity, crate::panel::Severity::Failing);
        assert!(alert.text.contains("layout"), "names it: {}", alert.text);

        let bar = status_bar_at(&mut app, 120);
        assert!(bar.contains('⚠'), "and it is on the bar: {bar}");
        assert!(bar.contains("os error 30"), "with the reason: {bar}");
    }

    /// There is no all-clear. An indicator saying everything is fine is a light
    /// you have to read to learn nothing, and reading it is work.
    #[test]
    fn a_quiet_dashboard_says_nothing_at_all() {
        let mut app = App::new(resizable()).expect("builds");
        let bar = status_bar_at(&mut app, 120);
        assert!(!bar.contains('⚠'), "no marker: {bar}");
        assert!(
            !bar.to_lowercase().contains("ok") && !bar.to_lowercase().contains("clear"),
            "and no reassurance: {bar}"
        );
    }

    /// The alert is measured where it is built, because a rendered bar only
    /// holds what the terminal kept. At every width it fits the bar, and it is
    /// either the marker and the whole alert or ends in `…` — and a bar too
    /// narrow for the marker still says it was cut, rather than drawing
    /// ` ⚠ ` over an alert that is not there.
    #[test]
    fn the_alert_line_never_outgrows_the_bar() {
        let theme = crate::theme::Theme::default();
        for text in [
            "The layout could not be saved — read-only file system",
            "設定を保存できませんでした 🌞 ディスクがいっぱいです",
        ] {
            let whole = format!("{ALERT_MARKER}{text}");
            let mut cut = false;
            for width in 1..=80u16 {
                let line: String = alert_line(text, width, &theme)
                    .spans
                    .iter()
                    .map(|span| span.content.as_ref())
                    .collect();
                assert!(
                    crate::grid::display_width(&line) <= usize::from(width),
                    "{line:?} is wider than {width}"
                );
                if let Some(head) = line.strip_suffix('…') {
                    assert!(whole.starts_with(head), "{width}: {line:?}");
                    cut = true;
                } else {
                    assert_eq!(line, whole, "cut with nothing to say so at {width}");
                }
            }
            assert!(cut, "a sweep that never cut {text:?} tests nothing");
        }
    }

    /// An alert outranks the update notice. That notice is not going to get
    /// worse while you read the alert; the alert might.
    #[test]
    fn an_alert_displaces_the_hints_rather_than_queueing_behind_them() {
        let mut app = App::new(config_with(&["clocks"])).expect("builds");
        app.watch_for_updates(std::sync::Arc::new(std::sync::Mutex::new(Some(
            "9.9.9".to_string(),
        ))));
        let before = status_bar_at(&mut app, 200);
        assert!(before.contains("9.9.9"), "the notice is there to displace");

        app.layout_error = Some("disk full".into());
        let after = status_bar_at(&mut app, 200);
        assert!(after.contains("disk full"), "the alert shows: {after}");
        assert!(
            !after.contains("9.9.9"),
            "and the notice gives way: {after}"
        );
    }

    /// The mode has to claim the bare arrows before panels do, for the same
    /// reason the resize keys are claimed: the calendar binds plain arrows and
    /// does not inspect modifiers, so a left arrow meant to move a panel would
    /// scroll a month instead.
    #[test]
    fn arrange_claims_the_arrows_the_focused_panel_would_otherwise_take() {
        let mut app = App::new(resizable()).expect("builds");
        app.handle_key(KeyEvent::from(KeyCode::Char('m')));
        assert!(app.arranging.is_some(), "m opened the mode");

        let before = widgets_by_row(&app);
        app.handle_key(KeyEvent::from(KeyCode::Right));
        assert_ne!(
            widgets_by_row(&app),
            before,
            "the arrow moved a panel rather than reaching the calendar"
        );
    }

    /// Esc means "back out of this" everywhere else in mirador, and an
    /// arrangement is exactly the kind of change worth being able to abandon.
    #[test]
    fn esc_puts_the_layout_back_exactly_as_it_was() {
        let mut app = App::new(resizable()).expect("builds");
        let before = widgets_by_row(&app);

        app.handle_key(KeyEvent::from(KeyCode::Char('m')));
        for code in [KeyCode::Right, KeyCode::Down, KeyCode::Up] {
            app.handle_key(KeyEvent::from(code));
        }
        assert_ne!(widgets_by_row(&app), before, "something actually moved");

        app.handle_key(KeyEvent::from(KeyCode::Esc));
        assert!(app.arranging.is_none(), "the mode closed");
        assert_eq!(widgets_by_row(&app), before, "and the layout came back");
        assert!(
            !app.layout_dirty,
            "a cancelled arrangement leaves nothing to write"
        );
    }

    /// A resize made before the mode opened is not part of the arrangement, so
    /// cancelling must not swallow it. Restoring the layout and clearing the
    /// flag unconditionally would lose a change the user had already made.
    #[test]
    fn cancelling_does_not_discard_a_change_made_before_the_mode_opened() {
        let mut app = App::new(resizable()).expect("builds");
        app.handle_key(KeyEvent::new(KeyCode::Right, KeyModifiers::CONTROL));
        assert!(app.layout_dirty, "the resize is waiting to be written");

        app.handle_key(KeyEvent::from(KeyCode::Char('m')));
        app.handle_key(KeyEvent::from(KeyCode::Down));
        app.handle_key(KeyEvent::from(KeyCode::Esc));

        assert!(
            app.layout_dirty,
            "the earlier resize still needs writing after the cancel"
        );
    }

    /// Focus follows the widget rather than the slot index, so the panel you
    /// are moving stays the one under the highlight. Without this you would
    /// move a panel once and then start moving whatever slid into its place.
    #[test]
    fn the_moved_panel_keeps_the_focus() {
        let mut app = App::new(resizable()).expect("builds");
        app.focus = 0;
        let moving = app.slots[0].widget.clone();

        app.handle_key(KeyEvent::from(KeyCode::Char('m')));
        app.handle_key(KeyEvent::from(KeyCode::Right));

        assert_eq!(
            app.slots[app.focus].widget, moving,
            "the highlight went with the panel"
        );
    }

    /// #100, tested through the shell rather than through `arrange::move_row`.
    ///
    /// The arithmetic having its own tests is not enough — #106 shipped a
    /// correct helper that was simply never called, and two unit tests passed
    /// throughout. This presses the key.
    #[test]
    fn shift_arrows_move_the_whole_row_in_arrange_mode() {
        let mut app = App::new(resizable()).expect("builds");
        // `resizable` is [clocks, calendar] over [cpu]. Focus the lone panel in
        // the second row — before #100 it could only ever merge upward.
        app.focus = 2;
        let moving = app.slots[2].widget.clone();
        assert_eq!(moving, "cpu", "fixture changed under this test");

        app.handle_key(KeyEvent::from(KeyCode::Char('m')));
        app.handle_key(KeyEvent::new(KeyCode::Up, KeyModifiers::SHIFT));

        assert_eq!(
            app.config.layout.rows.len(),
            2,
            "moving a row must not merge it away"
        );
        assert_eq!(
            app.config.layout.rows[0].panels[0].widget, "cpu",
            "the cpu row should now be first"
        );
        assert_eq!(
            app.slots[app.focus].widget, moving,
            "the highlight went with the panel"
        );
        assert!(app.arranging.is_some(), "and the mode stayed open");
    }

    /// `J`/`K` are the same gesture without a modifier, matching the clock
    /// panel. Bare `j`/`k` must still move the *panel*, or the shifted pair
    /// would have quietly replaced the plain one.
    #[test]
    fn capital_and_plain_movement_keys_do_different_things() {
        let mut app = App::new(resizable()).expect("builds");
        app.focus = 2;
        app.handle_key(KeyEvent::from(KeyCode::Char('m')));
        app.handle_key(KeyEvent::from(KeyCode::Char('K')));
        assert_eq!(
            app.config.layout.rows[0].panels[0].widget, "cpu",
            "K should have moved the row"
        );

        // And the plain key still merges, which is the behaviour #100 was
        // careful not to take away.
        let mut app = App::new(resizable()).expect("builds");
        app.focus = 2;
        app.handle_key(KeyEvent::from(KeyCode::Char('m')));
        app.handle_key(KeyEvent::from(KeyCode::Char('k')));
        assert_eq!(
            app.config.layout.rows.len(),
            1,
            "plain k should still merge the panel into the row above"
        );
    }

    /// The arrows are the mode's, but Ctrl+arrow still has to reach the resize
    /// path — rearranging is exactly when you want to adjust proportions.
    #[test]
    fn ctrl_arrows_still_resize_inside_arrange_mode() {
        let mut app = App::new(resizable()).expect("builds");
        app.handle_key(KeyEvent::from(KeyCode::Char('m')));

        let before = widths(&app);
        app.handle_key(KeyEvent::new(KeyCode::Right, KeyModifiers::CONTROL));
        assert_ne!(widths(&app), before, "Ctrl+Right resized rather than moved");
        assert!(app.arranging.is_some(), "and did not close the mode");
    }

    #[test]
    fn resize_keys_are_claimed_before_the_focused_panel_sees_them() {
        // The calendar binds bare Left/Right and ignores modifiers, so if the
        // shell offered the key onward first, Ctrl+Left would scroll the month
        // instead of resizing. Focus it and check the width actually moved.
        let mut app = App::new(resizable()).unwrap();
        app.focus = 1;
        let before = widths(&app);
        app.handle_key(KeyEvent::new(KeyCode::Left, KeyModifiers::CONTROL));
        assert_ne!(widths(&app), before, "Ctrl+Left was swallowed by the panel");
    }

    #[test]
    fn toggling_one_panel_leaves_the_others_untouched() {
        // The bug the demo recording caught: `rebuild_panels` remade every
        // panel, so switching the network panel off reset a running pomodoro to
        // 25:00 and sent the weather and stocks panels back to "loading".
        //
        // Panels are compared by pointer identity — the same allocation before
        // and after is the only thing that actually proves state survived,
        // where comparing a rendered figure would pass for a panel that had
        // been rebuilt and happened to look the same.
        let mut app = App::new(config_with(&["clocks", "todo", "pomodoro"])).unwrap();
        let before: Vec<*const u8> = app
            .slots
            .iter()
            .map(|slot| std::ptr::from_ref(&*slot.panel).cast::<u8>())
            .collect();

        app.toggle_widget("pomodoro");
        assert!(!app.config.layout.places("pomodoro"), "it went");

        let after: Vec<*const u8> = app
            .slots
            .iter()
            .map(|slot| std::ptr::from_ref(&*slot.panel).cast::<u8>())
            .collect();
        assert_eq!(after, before[..2], "the surviving panels were rebuilt");

        // And back again: the two that never left are still the same panels.
        app.toggle_widget("pomodoro");
        assert!(app.config.layout.places("pomodoro"));
        let again: Vec<*const u8> = app
            .slots
            .iter()
            .take(2)
            .map(|slot| std::ptr::from_ref(&*slot.panel).cast::<u8>())
            .collect();
        assert_eq!(again, before[..2], "re-adding a panel rebuilt the others");
    }

    #[test]
    fn focus_follows_the_panel_rather_than_the_index() {
        // Removing a panel to the left of the focused one shifts every later
        // index down. Leaving `focus` where it was moves the highlight to a
        // different panel, which gets noticed only when the next keypress goes
        // somewhere unexpected.
        //
        // The indices are chosen so that clamping cannot pass by accident: with
        // four panels and focus on the second, removing the first leaves the
        // old `min(focus, len - 1)` pointing at the *third* widget.
        let mut app = App::new(config_with(&["clocks", "todo", "pomodoro", "notes"])).unwrap();
        app.focus = 1;
        assert_eq!(app.slots[app.focus].widget, "todo");

        app.toggle_widget("clocks");
        assert_eq!(
            app.slots[app.focus].widget, "todo",
            "focus jumped to another panel"
        );
    }

    /// A panel that will not build refuses the toggle: the layout and the
    /// panels on screen are the ones from before, nothing is left to write,
    /// and the picker is told why. Under test `weather` is such a panel — it
    /// would start a fetch thread — and a toggle that does build afterwards
    /// clears the reason again.
    #[test]
    fn a_panel_that_will_not_build_is_refused_and_the_layout_put_back() {
        let mut app = App::new(config_with(&["clocks", "todo"])).unwrap();
        let layout = widgets_by_row(&app);
        let panels: Vec<*const u8> = app
            .slots
            .iter()
            .map(|slot| std::ptr::from_ref(&*slot.panel).cast::<u8>())
            .collect();

        app.toggle_widget("weather");
        assert_eq!(widgets_by_row(&app), layout, "the layout came back");
        let after: Vec<*const u8> = app
            .slots
            .iter()
            .map(|slot| std::ptr::from_ref(&*slot.panel).cast::<u8>())
            .collect();
        assert_eq!(after, panels, "and so did the very same panels");
        assert!(!app.layout_dirty, "a refusal leaves nothing to write");
        let notice = app.layout_notice.clone().unwrap_or_default();
        assert!(
            notice.contains("`weather`"),
            "the picker says why: {notice:?}"
        );

        app.toggle_widget("notes");
        assert!(app.config.layout.places("notes"));
        assert!(
            app.layout_dirty,
            "a toggle that took is waiting to be written"
        );
        assert_eq!(app.layout_notice, None, "and the old reason is gone");
    }

    #[test]
    fn a_widget_placed_twice_gets_two_panels() {
        // `Config::validate` checks that widget names are *known*, not that
        // they are unique, so a hand-written config can place one twice.
        // Matching panels to entries by name has to consume from a pool — a
        // lookup would hand the same panel to both entries.
        let mut config = config_with(&["clocks", "clocks", "todo"]);
        config.layout.rows[0].panels[0].width = 30;
        config.layout.rows[0].panels[1].width = 30;
        config.layout.rows[0].panels[2].width = 40;

        let mut app = App::new(config).unwrap();
        assert_eq!(app.slots.len(), 3);

        let distinct: std::collections::HashSet<*const u8> = app
            .slots
            .iter()
            .map(|slot| std::ptr::from_ref(&*slot.panel).cast::<u8>())
            .collect();
        assert_eq!(distinct.len(), 3, "two entries share one panel");

        // A rebuild must keep them distinct too.
        app.toggle_widget("notes");
        let distinct: std::collections::HashSet<*const u8> = app
            .slots
            .iter()
            .map(|slot| std::ptr::from_ref(&*slot.panel).cast::<u8>())
            .collect();
        assert_eq!(distinct.len(), app.slots.len(), "a panel was reused twice");
    }

    #[test]
    fn no_update_notice_until_something_finds_a_version() {
        // `App` never starts a check itself. A dashboard built in a test — or
        // by `--print-config` — must not be able to reach the network.
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        assert_eq!(app.update_hint(), None);

        app.watch_for_updates(std::sync::Arc::new(std::sync::Mutex::new(Some(
            "9.9.9".to_string(),
        ))));
        let hint = app.update_hint().expect("a found version should show");
        assert!(hint.contains("9.9.9"), "got `{hint}`");
        assert!(
            hint.contains("mirador --update"),
            "the notice must say what to do about it: `{hint}`"
        );
    }

    #[test]
    fn the_update_notice_retires_on_the_first_keypress() {
        // A dashboard left open all day must not keep telling you something
        // you have already read.
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.watch_for_updates(std::sync::Arc::new(std::sync::Mutex::new(Some(
            "9.9.9".to_string(),
        ))));
        assert!(app.update_hint().is_some());

        app.handle_key(key(KeyCode::Tab));
        assert_eq!(app.update_hint(), None, "the notice outlived a keypress");
    }

    #[test]
    fn the_update_notice_has_the_end_of_the_status_bar_to_itself() {
        // It used to share the row with a hint listing the widgets your layout
        // left out. That hint is gone — see
        // `a_layout_missing_widgets_is_not_advertised_anywhere` — so the update
        // notice is the only thing that can appear here.
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.watch_for_updates(std::sync::Arc::new(std::sync::Mutex::new(Some(
            "9.9.9".to_string(),
        ))));
        let shown = app.update_hint().expect("an update is waiting");
        assert!(shown.contains("9.9.9"), "got `{shown}`");
    }

    /// A layout that leaves widgets out is a decision, not an oversight.
    ///
    /// mirador used to say so — once in the status bar at startup, and for ever
    /// in the help overlay. The status bar line retired on the first keypress;
    /// the overlay section did not, so someone who had deliberately switched
    /// four panels off was told about them every time they pressed `?`. That is
    /// the nagging this dashboard exists not to do, arrived at from the
    /// direction of helpfulness rather than of notifications.
    ///
    /// `w` is still a primary binding, so the way to switch a panel on is on
    /// the status bar and in the help. What is gone is being told you *should*.
    #[test]
    fn a_layout_missing_widgets_is_not_advertised_anywhere() {
        // One panel out of fourteen, so thirteen are unused — the loudest possible
        // case for the hint that used to be here.
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        let screen = |app: &mut App, help: bool| -> String {
            if help {
                app.handle_key(KeyEvent::from(KeyCode::Char('?')));
            }
            drawn(app, 200, 40).join("\n")
        };

        let dashboard = screen(&mut app, false);
        assert!(
            !dashboard.contains("unused"),
            "the dashboard advertises what you chose not to run"
        );

        let help = screen(&mut app, true);
        assert!(app.show_help, "the overlay is open");
        for banned in ["unused", "not in your layout", "switch them on"] {
            assert!(
                !help.contains(banned),
                "the help overlay still nags about unused widgets: found `{banned}`"
            );
        }
    }

    /// The key column was a hardcoded 12 — the width of the longest key the
    /// program has — so every overlay ever drawn put eleven spaces after `q`
    /// and began its actions a third of the way across a 46-cell popup.
    ///
    /// Asserted against the widest key actually on show, not against a number:
    /// a test that pinned 9 would have to be edited by whoever next renames a
    /// binding, and would pass just as happily if the column went back to being
    /// a constant that happened to equal 9.
    #[test]
    fn the_help_overlay_sizes_its_key_column_to_the_keys_it_shows() {
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.handle_key(KeyEvent::from(KeyCode::Char('?')));
        let rows = drawn(&mut app, 120, 40);

        let widest = app
            .keymap
            .bindings()
            .iter()
            .chain(app.slots[app.focus].panel.bindings())
            .map(|binding| crate::grid::display_width(&binding.key))
            .max()
            .expect("there are bindings");
        assert!(
            widest < 12,
            "no key is 12 cells wide any more, so a column of 12 is padding: {widest}"
        );

        // `q quit` is the shortest key in the overlay and so the one the old
        // constant punished hardest. Its action must start where every other
        // action starts.
        let row = rows
            .iter()
            .find(|row| row.contains(" q ") && row.contains("quit"))
            .expect("the overlay lists `q quit`");
        let key_at = row.find('q').expect("the key is on the row");
        let action_at = row.find("quit").expect("the action is on the row");
        assert_eq!(
            action_at - key_at,
            widest + 2,
            "the action starts one column past the widest key plus its gap: {row:?}"
        );
    }

    /// Two list panels with their files in a scratch directory, so nothing a
    /// test does can reach the user's own tasks or notes.
    fn two_lists(name: &str) -> (Config, TempDir) {
        let dir = TempDir::new(&format!("app-{name}"));
        let mut config = config_with(&["notes", "todo"]);
        config.notes.file = Some(dir.join("notes.toml"));
        config.todo.file = Some(dir.join("todos.toml"));
        (config, dir)
    }

    /// The rows of the dashboard as drawn, so a test can read where things are.
    fn drawn(app: &mut App, width: u16, height: u16) -> Vec<String> {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;
        let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap();
        terminal.draw(|frame| app.render_for_test(frame)).unwrap();
        crate::widgets::testing::rows(terminal.backend().buffer())
    }

    /// The screen row carrying the selection marker inside `area`, if any.
    fn marker_row(rows: &[String], area: Rect) -> Option<u16> {
        (area.y..area.y + area.height).find(|&y| {
            let row = &rows[usize::from(y)];
            row.chars()
                .skip(usize::from(area.x))
                .take(usize::from(area.width))
                .any(|c| c == '▸')
        })
    }

    fn at(kind: MouseEventKind, column: u16, row: u16) -> MouseEvent {
        MouseEvent {
            kind,
            column,
            row,
            modifiers: KeyModifiers::NONE,
        }
    }

    /// `handle_mouse` goes to the panel under the *pointer*, and a scroll must
    /// move the list it is aimed at without yanking the keyboard away from
    /// what the user was typing in. Nothing exercised that seam: every mouse
    /// path in the panels was unexecuted by the suite.
    ///
    /// Observed from the outside, since the panel's selection is its own: the
    /// tasks panel draws its marker only while focused, so focus is moved
    /// there *afterwards* with Tab and the marker is read from the second row,
    /// where the scroll left it — against a control that never scrolled and
    /// finds it on the first.
    #[test]
    fn a_scroll_acts_on_the_panel_under_the_pointer_and_leaves_focus_where_it_was() {
        let (config, _dir) = two_lists("scroll");
        let mut app = App::new(config.clone()).unwrap();
        let rows = drawn(&mut app, 120, 30);
        let todo = app.slots[1].area.expect("the tasks panel was drawn");
        assert_eq!(app.focus, 0, "notes start focused");
        assert!(
            marker_row(&rows, todo).is_none(),
            "unfocused, the tasks panel draws no marker"
        );

        let redraw = app.handle_mouse(at(MouseEventKind::ScrollDown, todo.x + 3, todo.y + 3));
        assert!(redraw, "the wheel over a list is consumed by it");
        assert_eq!(app.focus, 0, "and focus did not move");

        app.handle_key(KeyEvent::from(KeyCode::Tab));
        let after = drawn(&mut app, 120, 30);
        let scrolled = marker_row(&after, todo).expect("focused, the marker shows");

        let mut control = App::new(config).unwrap();
        drawn(&mut control, 120, 30);
        control.handle_key(KeyEvent::from(KeyCode::Tab));
        let untouched = marker_row(&drawn(&mut control, 120, 30), todo).unwrap();
        assert_eq!(
            scrolled,
            untouched + 1,
            "the scroll moved the selection one row while the panel was not focused"
        );
    }

    /// A click focuses the panel it lands in and selects the row it hit.
    #[test]
    fn a_click_focuses_the_panel_under_the_pointer_and_selects_the_row_it_hit() {
        let (config, _dir) = two_lists("click");
        let mut app = App::new(config).unwrap();
        let rows = drawn(&mut app, 120, 30);
        let todo = app.slots[1].area.unwrap();
        // The third task row: header line, column headings, then tasks.
        // Columns, not bytes: the frame's `│` is three bytes wide and one
        // cell, which is invariant 9 reaching into a test.
        let target = (todo.y..todo.y + todo.height)
            .filter(|&y| {
                rows[usize::from(y)]
                    .chars()
                    .skip(usize::from(todo.x))
                    .collect::<String>()
                    .contains("[ ]")
            })
            .nth(2)
            .expect("three task rows on screen");

        app.handle_mouse(at(
            MouseEventKind::Down(ratatui::crossterm::event::MouseButton::Left),
            todo.x + 6,
            target,
        ));
        assert_eq!(app.focus, 1, "the click moved focus to the tasks panel");
        let after = drawn(&mut app, 120, 30);
        assert_eq!(
            marker_row(&after, todo),
            Some(target),
            "and selected the row it hit"
        );
    }

    /// A panel in a text-entry state has the same absolute veto over the mouse
    /// that it has over global keys: a stray click must not pull focus out of
    /// a half-typed task and strand the form.
    #[test]
    fn an_open_form_vetoes_a_click_landing_in_another_panel() {
        let (config, _dir) = two_lists("veto");
        let mut app = App::new(config).unwrap();
        drawn(&mut app, 120, 30);
        let notes = app.slots[0].area.unwrap();

        app.handle_key(KeyEvent::from(KeyCode::Tab));
        assert_eq!(app.focus, 1);
        app.handle_key(KeyEvent::from(KeyCode::Char('a')));
        assert!(app.focus_captures_input(), "the task form is open");

        app.handle_mouse(at(
            MouseEventKind::Down(ratatui::crossterm::event::MouseButton::Left),
            notes.x + 2,
            notes.y + 2,
        ));
        assert_eq!(app.focus, 1, "focus stayed with the form");
        assert!(app.focus_captures_input(), "and the form is still open");
    }

    /// Invariant 17, at the seam that shipped wrong twice: the *App* gathers
    /// what every panel reports, compares it against the config once, and
    /// writes only the difference — so a preference toggled back to what the
    /// config says leaves the file rather than asserting itself for ever.
    /// `UiState` has unit tests for the comparison; nothing had ever driven
    /// the plumbing that calls it.
    #[test]
    fn a_preference_moved_off_the_config_is_written_and_moved_back_is_retracted() {
        let dir = TempDir::new("prefs");
        let path = dir.join("state.toml");
        let config = config_with(&["clocks"]);
        let baseline = crate::state::UiState::from_config(&config);
        let mut app = App::new(config).unwrap();
        app.remember_preferences_at(path.clone(), crate::state::UiState::default(), baseline);

        app.handle_key(KeyEvent::from(KeyCode::Char('s')));
        app.persist_preferences();
        let written = std::fs::read_to_string(&path).expect("a change was written");
        assert!(
            written.contains("clocks_show_seconds = false"),
            "the toggle is recorded as a difference from the config: {written}"
        );

        app.handle_key(KeyEvent::from(KeyCode::Char('s')));
        app.persist_preferences();
        let written = std::fs::read_to_string(&path).unwrap();
        assert!(
            !written.contains("clocks_show_seconds"),
            "toggled back to the config's value, the entry is gone: {written:?}"
        );
    }

    /// The picker's edit reaches the config file as a textual edit that keeps
    /// the comments, and a file the editor cannot work on is refused and
    /// reported rather than rewritten. Both halves through the keys, not by
    /// calling `layout_edit` directly.
    #[test]
    fn a_picker_change_is_written_to_the_config_and_an_uneditable_file_is_reported() {
        let dir = TempDir::new("layout");

        // One panel per line, the way the shipped config is written: the
        // editor rebuilds a row from captured panel *lines*, and a comment
        // above a panel travels with it.
        let editable = "[layout]\nrows = [\n  { height = 1, panels = [\n    # keep me\n    { widget = \"clocks\",   width = 1 },\n    { widget = \"calendar\", width = 1 },\n  ] },\n]\n";
        let path = dir.join("config.toml");
        std::fs::write(&path, editable).unwrap();
        let config: Config = toml::from_str(editable).expect("a minimal config parses");

        let mut app = App::new(config.clone()).unwrap();
        app.write_layout_to(path.clone());
        app.handle_key(KeyEvent::from(KeyCode::Char('w')));
        assert!(app.picker.is_some(), "`w` opens the picker");
        // Down to `calendar` — sixth in `widget_names` — and switch it off.
        for _ in 0..5 {
            app.handle_key(KeyEvent::from(KeyCode::Down));
        }
        assert_eq!(
            app.picker.as_ref().map(crate::picker::Picker::selected),
            Some(5)
        );
        app.handle_key(KeyEvent::from(KeyCode::Char(' ')));
        app.handle_key(KeyEvent::from(KeyCode::Esc));

        assert_eq!(app.layout_error, None, "the edit was accepted");
        let after = std::fs::read_to_string(&path).unwrap();
        assert!(
            !after.contains("calendar"),
            "calendar left the layout: {after}"
        );
        assert!(after.contains("# keep me"), "the comment survived: {after}");
        assert!(after.contains("\"clocks\""), "clocks stayed: {after}");

        // The other spelling loads but cannot be edited; the file is left
        // exactly as it was and the failure is on the bar, not swallowed.
        let sections = "# keep me\n[[layout.rows]]\nheight = 1\n[[layout.rows.panels]]\nwidget = \"clocks\"\nwidth = 1\n[[layout.rows.panels]]\nwidget = \"calendar\"\nwidth = 1\n";
        let other = dir.join("sections.toml");
        std::fs::write(&other, sections).unwrap();
        let mut app = App::new(config).unwrap();
        app.write_layout_to(other.clone());
        app.handle_key(KeyEvent::from(KeyCode::Char('w')));
        for _ in 0..5 {
            app.handle_key(KeyEvent::from(KeyCode::Down));
        }
        app.handle_key(KeyEvent::from(KeyCode::Char(' ')));
        app.handle_key(KeyEvent::from(KeyCode::Esc));
        assert!(
            app.layout_error.is_some(),
            "a file it cannot edit is reported"
        );
        assert_eq!(
            std::fs::read_to_string(&other).unwrap(),
            sections,
            "and left untouched"
        );
    }

    #[test]
    fn a_click_retires_the_hint_but_the_pointer_merely_passing_over_does_not() {
        use ratatui::crossterm::event::MouseButton;

        let mouse = |kind| MouseEvent {
            kind,
            column: 0,
            row: 0,
            modifiers: KeyModifiers::NONE,
        };

        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.watch_for_updates(std::sync::Arc::new(std::sync::Mutex::new(Some(
            "9.9.9".to_string(),
        ))));
        app.handle_mouse(mouse(MouseEventKind::Moved));
        assert!(
            app.update_hint().is_some(),
            "the mouse crossing the window is not the user reading anything"
        );

        app.handle_mouse(mouse(MouseEventKind::Down(MouseButton::Left)));
        assert!(app.update_hint().is_none(), "a deliberate click retires it");
    }

    #[test]
    fn retiring_the_hint_forces_a_redraw_so_it_actually_disappears() {
        use ratatui::crossterm::event::MouseButton;

        // A click landing on no panel at all still has to repaint, or the
        // retired hint stays on screen until something else happens to redraw.
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        let dirty = app.handle_mouse(MouseEvent {
            kind: MouseEventKind::Down(MouseButton::Left),
            column: 9_000,
            row: 9_000,
            modifiers: KeyModifiers::NONE,
        });
        assert!(dirty, "the hint was cleared, so the screen is out of date");
    }

    /// The paste half of the test above. A paste retires the notice and marks
    /// the watch log seen, as a key does — but where `run` redraws after every
    /// key, it redraws after a paste only when `handle_paste` asks, and a
    /// paste the focused panel does not take asked for nothing. The notice
    /// then stayed on screen until something else happened to redraw, and so
    /// did a rule line the paste had just made untrue.
    #[test]
    fn retiring_the_hint_by_paste_forces_a_redraw_too() {
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.watch_for_updates(std::sync::Arc::new(std::sync::Mutex::new(Some(
            "9.9.9".to_string(),
        ))));
        assert!(app.update_hint().is_some());
        let dirty = app.handle_paste("hello");
        assert!(app.update_hint().is_none(), "a paste retires the notice");
        assert!(
            dirty,
            "the notice was retired, so the screen is out of date"
        );

        // The rule line alone, with the notice already gone: one entry from
        // before the reader was last here and one from after, which is the one
        // state that draws a line. Spinning until the clock moves keeps the
        // second strictly after that moment and before the paste's own.
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.show_update_hint = false;
        let an_hour_ago = jiff::Zoned::now()
            .checked_sub(jiff::Span::new().hours(1))
            .unwrap();
        app.watch.push(crate::watch::Event {
            at: an_hour_ago,
            source: "test".into(),
            text: "before".into(),
        });
        app.watch.mark_seen();
        let seen = jiff::Zoned::now();
        while jiff::Zoned::now() <= seen {
            std::hint::spin_loop();
        }
        app.watch.push(crate::watch::Event::new("test", "after"));
        assert_eq!(app.watch.unseen(), Some(1), "the line is on screen");
        let dirty = app.handle_paste("hello");
        assert_eq!(app.watch.unseen(), None, "the paste marked it seen");
        assert!(dirty, "the line moved, so the screen is out of date");
    }

    #[test]
    fn the_help_overlay_renders_at_any_size() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        // The overlay clips silently rather than erroring, so a size that
        // cannot fit its text must still draw something rather than panic on
        // the arithmetic. It once carried an unused-widget section that made
        // it taller still; the section is gone and the sizes stay.
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.handle_key(KeyEvent::from(KeyCode::Char('?')));
        assert!(app.show_help);

        for (width, height) in [(1, 1), (4, 3), (30, 8), (80, 24), (200, 60)] {
            let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap();
            terminal
                .draw(|frame| app.render_for_test(frame))
                .unwrap_or_else(|e| panic!("help failed to draw at {width}x{height}: {e}"));
        }
    }

    #[test]
    fn every_binding_of_the_focused_panel_is_reachable_on_an_80x24_terminal() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        // The tasks panel declares 17 bindings; with the global block, the
        // section headings and the footer that is well past the 22 rows an
        // 80x24 terminal leaves inside the overlay. It used to clip there
        // silently, so about a third of the keys did not exist as far as
        // anyone reading `?` could tell.
        let mut app = App::new(config_with(&["todo"])).unwrap();
        let bindings = app.slots[0].panel.bindings().len();
        assert!(bindings > 4, "this test needs a panel with many bindings");

        let mut terminal = Terminal::new(TestBackend::new(80, 24)).unwrap();
        app.handle_key(KeyEvent::from(KeyCode::Char('?')));
        terminal.draw(|frame| app.render_for_test(frame)).unwrap();

        assert!(
            app.help_overflow > 0,
            "the overlay fits at 80x24, so this test no longer proves anything"
        );

        // Scroll to the bottom one key at a time, redrawing as a user would.
        let mut guard = 0;
        while app.help_scroll < app.help_overflow {
            app.handle_key(KeyEvent::from(KeyCode::Down));
            terminal.draw(|frame| app.render_for_test(frame)).unwrap();
            assert!(app.show_help, "scrolling must not dismiss the overlay");
            guard += 1;
            assert!(guard < 200, "scrolling made no progress");
        }

        // The last row of text is on screen, and `End` and `Home` agree.
        app.handle_key(KeyEvent::from(KeyCode::Home));
        assert_eq!(app.help_scroll, 0);
        app.handle_key(KeyEvent::from(KeyCode::End));
        assert_eq!(app.help_scroll, app.help_overflow);

        // Anything that is not a scroll key still closes it.
        app.handle_key(KeyEvent::from(KeyCode::Char('x')));
        assert!(
            !app.show_help,
            "a non-scroll key must still close the overlay"
        );
    }

    #[test]
    fn the_overlay_closes_on_any_key_when_it_all_fits() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        // Scrolling only binds the arrow keys when there is something below the
        // fold. On a terminal with room to spare, `?` then Down must close,
        // because that is what "any key to close" promises.
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        let mut terminal = Terminal::new(TestBackend::new(120, 60)).unwrap();
        app.handle_key(KeyEvent::from(KeyCode::Char('?')));
        terminal.draw(|frame| app.render_for_test(frame)).unwrap();

        assert_eq!(
            app.help_overflow, 0,
            "120x60 has room for the whole overlay"
        );
        app.handle_key(KeyEvent::from(KeyCode::Down));
        assert!(!app.show_help);
    }

    #[test]
    fn the_hint_gives_way_to_the_global_keys_on_a_narrow_terminal() {
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.watch_for_updates(std::sync::Arc::new(std::sync::Mutex::new(Some(
            "9.9.9".to_string(),
        ))));
        let row_text = |app: &mut App, width: u16| -> String { drawn(app, width, 6)[5].clone() };

        // Wide enough for the global keys *and* the notice.
        let wide = row_text(&mut app, 200);
        assert!(wide.contains("9.9.9"), "wide enough for both: `{wide}`");

        let narrow = row_text(&mut app, 44);
        assert!(
            !narrow.contains("9.9.9"),
            "knowing how to quit outranks the notice: `{narrow}`"
        );
        assert!(
            narrow.contains("quit"),
            "the global keys survive: `{narrow}`"
        );
    }

    #[test]
    fn space_is_split_by_weight_when_nobody_declares_a_limit() {
        assert_eq!(distribute(100, &[50, 50], &[None, None]), vec![50, 50]);
        assert_eq!(distribute(100, &[25, 75], &[None, None]), vec![25, 75]);
    }

    /// A maximum with no weight beside it was ignored in silence, and a weight
    /// with no maximum panicked on an index; both are a caller pairing the
    /// wrong slices, and the assertion says so by name. A debug assertion, so
    /// the test is a debug build's only.
    #[test]
    #[cfg(debug_assertions)]
    #[should_panic(expected = "one maximum per weight")]
    fn distribute_refuses_maxima_that_do_not_pair_with_the_weights() {
        distribute(100, &[50, 50], &[None, None, Some(10)]);
    }

    #[test]
    fn every_cell_is_allocated_however_the_weights_divide() {
        // Truncating division would leave a ragged edge where the frames stop
        // short of the terminal.
        for total in [1u16, 7, 23, 80, 81, 199, 200] {
            for weights in [vec![1, 1, 1], vec![34, 33, 33], vec![1, 2, 7]] {
                let maxima = vec![None; weights.len()];
                let sizes = distribute(total, &weights, &maxima);
                assert_eq!(
                    sizes.iter().sum::<u16>(),
                    total,
                    "{total} across {weights:?} gave {sizes:?}"
                );
            }
        }
    }

    #[test]
    fn a_panel_that_cannot_use_more_space_hands_it_to_one_that_can() {
        // The calendar case: bounded neighbour, unbounded list.
        let sizes = distribute(100, &[50, 50], &[Some(30), None]);
        assert_eq!(sizes, vec![30, 70], "the surplus must move sideways");
        assert_eq!(sizes.iter().sum::<u16>(), 100);
    }

    #[test]
    fn surplus_from_several_bounded_panels_lands_on_the_one_that_can_grow() {
        let sizes = distribute(120, &[40, 40, 40], &[Some(20), Some(20), None]);
        assert_eq!(sizes, vec![20, 20, 80]);
    }

    #[test]
    fn surplus_is_shared_between_takers_in_proportion_to_their_weights() {
        // Two unbounded panels, one twice the weight of the other.
        let sizes = distribute(120, &[60, 20, 40], &[Some(30), None, None]);
        assert_eq!(sizes.iter().sum::<u16>(), 120);
        assert_eq!(sizes[0], 30, "the bounded one is capped");
        assert!(
            sizes[2] > sizes[1],
            "the heavier taker gets more of it: {sizes:?}"
        );
    }

    #[test]
    fn a_row_of_entirely_bounded_panels_still_covers_its_full_width() {
        // Nobody to hand the surplus to. Panels draw their own frames, so
        // leaving cells unallocated would show as a hole in the dashboard —
        // an over-wide panel is the lesser evil.
        //
        // Note this case is capped *before* redistribution, so it never reaches
        // the path that was broken. `no_slot_exceeds_its_maximum_while_another`
        // is the one that does; this one alone could not fail.
        let sizes = distribute(200, &[50, 50], &[Some(30), Some(30)]);
        assert_eq!(
            sizes.iter().sum::<u16>(),
            200,
            "no gap may be left: {sizes:?}"
        );
        assert_eq!(sizes, vec![100, 100], "and the overshoot is shared");
    }

    #[test]
    fn a_row_too_wide_for_its_maxima_shares_the_overshoot() {
        // The invariant that actually distinguishes the fix from the bug.
        //
        // "Nobody exceeds their maximum while somebody is under theirs" is not
        // enough: the buggy output [302, 47, 51] satisfies it, because 47 and
        // 51 are exactly at their maxima rather than under. What it violates is
        // that the *excess* be shared — [140, 0, 0] against weights
        // [26, 34, 40] is not a proportional split of anything.
        //
        // The real default top row: clocks / calendar / weather, at every width
        // from too-narrow to a 4K terminal.
        let weights = [26u16, 34, 40];
        let maxima = [Some(162u16), Some(47), Some(51)];
        let ceiling: u16 = maxima.iter().map(|m| m.unwrap()).sum();

        for total in (20u16..=1000).step_by(7) {
            let sizes = distribute(total, &weights, &maxima);

            assert_eq!(
                sizes.iter().map(|s| u32::from(*s)).sum::<u32>(),
                u32::from(total),
                "the row must cover its width exactly at {total}: {sizes:?}"
            );

            if total <= ceiling {
                // There is room to honour every maximum, so nobody may exceed.
                for i in 0..3 {
                    assert!(
                        sizes[i] <= maxima[i].unwrap(),
                        "at {total}: slot {i} exceeded its maximum with room to \
                         spare — {sizes:?} against {maxima:?}"
                    );
                }
                continue;
            }

            // Past the ceiling everybody has to go over. The excess must track
            // the weights, not land on one panel.
            let excess: Vec<u16> = (0..3).map(|i| sizes[i] - maxima[i].unwrap()).collect();
            let want = proportional(total - ceiling, &weights);
            assert_eq!(
                excess, want,
                "at {total}: the overshoot is not shared — {sizes:?}, excess \
                 {excess:?}, expected {want:?}"
            );
        }
    }

    #[test]
    fn a_wide_terminal_does_not_park_the_surplus_on_one_panel() {
        // The specific regression, with the numbers from the bug report.
        let sizes = distribute(400, &[26, 34, 40], &[Some(162), Some(47), Some(51)]);
        assert_eq!(sizes.iter().sum::<u16>(), 400);
        assert!(
            sizes[0] < 250,
            "the clock took the whole surplus again: {sizes:?}"
        );
        assert!(
            sizes[2] > 51,
            "the panel that could have used the space got none of it: {sizes:?}"
        );
    }

    #[test]
    fn a_limit_larger_than_the_space_available_changes_nothing() {
        let sizes = distribute(40, &[50, 50], &[Some(500), None]);
        assert_eq!(sizes, vec![20, 20], "a limit nobody reaches is inert");
    }

    #[test]
    fn degenerate_distributions_do_not_panic() {
        assert_eq!(distribute(0, &[1, 1], &[None, None]), vec![0, 0]);
        let shares = distribute(10, &[], &[]);
        assert!(shares.is_empty(), "{shares:?}");
        assert_eq!(
            distribute(10, &[0, 0], &[None, None]).iter().sum::<u16>(),
            10
        );
        assert_eq!(distribute(1, &[1, 1, 1], &[None; 3]).iter().sum::<u16>(), 1);
    }

    #[test]
    fn a_bounded_row_gives_its_leftover_height_to_the_row_below() {
        // The clock is bounded on height — numerals, date, zone table, and
        // nothing that grows past that. The CPU graph is not. The whole point
        // of the mechanism: reclaim the void under the clock and give it to
        // something that fills it.
        //
        // The calendar is deliberately *not* used here: it stacks another row
        // of months when given height, so it is bounded on width only.
        let config = Config {
            layout: LayoutConfig {
                rows: vec![
                    LayoutRow {
                        height: 50,
                        panels: vec![LayoutPanel {
                            widget: "clocks".into(),
                            width: 100,
                        }],
                    },
                    LayoutRow {
                        height: 50,
                        panels: vec![LayoutPanel {
                            widget: "cpu".into(),
                            width: 100,
                        }],
                    },
                ],
            },
            ..Config::default()
        };

        let app = App::new(config).unwrap();
        let bound = app.slots[0]
            .panel
            .max_height()
            .expect("the clock is bounded");
        let rects = app.geometry(Rect::new(0, 0, 120, bound * 3));
        assert_eq!(rects.len(), 2);
        assert_eq!(rects[0].height, bound, "the clock takes only what it uses");
        assert_eq!(
            rects[0].height + rects[1].height,
            bound * 3,
            "and the height it gave up must be used, not lost"
        );
        assert_eq!(rects[1].y, rects[0].height, "the rows stay flush");
    }

    #[test]
    fn a_calendar_keeps_its_height_because_it_stacks_more_months_into_it() {
        let config = Config {
            layout: LayoutConfig {
                rows: vec![
                    LayoutRow {
                        height: 50,
                        panels: vec![LayoutPanel {
                            widget: "calendar".into(),
                            width: 100,
                        }],
                    },
                    LayoutRow {
                        height: 50,
                        panels: vec![LayoutPanel {
                            widget: "cpu".into(),
                            width: 100,
                        }],
                    },
                ],
            },
            ..Config::default()
        };

        let app = App::new(config).unwrap();
        let rects = app.geometry(Rect::new(0, 0, 120, 60));
        assert_eq!(
            rects[0].height, 30,
            "extra height becomes another row of months, so none is handed back"
        );
    }

    #[test]
    fn a_bounded_panel_gives_its_leftover_width_to_its_neighbour() {
        let config = Config {
            layout: LayoutConfig {
                rows: vec![LayoutRow {
                    height: 100,
                    panels: vec![
                        LayoutPanel {
                            widget: "calendar".into(),
                            width: 50,
                        },
                        LayoutPanel {
                            widget: "cpu".into(),
                            width: 50,
                        },
                    ],
                }],
            },
            ..Config::default()
        };

        let app = App::new(config).unwrap();
        let rects = app.geometry(Rect::new(0, 0, 200, 40));
        assert!(
            rects[0].width < 100,
            "the calendar is bounded: {:?}",
            rects[0]
        );
        assert_eq!(
            rects[0].width + rects[1].width,
            200,
            "and the columns still cover the terminal"
        );
        assert_eq!(rects[1].x, rects[0].width, "the panels stay flush");
    }

    #[test]
    fn focus_wraps_in_both_directions() {
        let mut app = App::new(config_with(&["clocks", "cpu", "network"])).unwrap();
        assert_eq!(app.focus, 0);

        app.cycle_focus(true);
        assert_eq!(app.focus, 1);
        app.cycle_focus(true);
        app.cycle_focus(true);
        assert_eq!(app.focus, 0, "forward focus must wrap");

        app.cycle_focus(false);
        assert_eq!(app.focus, 2, "backward focus must wrap");
    }

    #[test]
    fn geometry_returns_one_rect_per_panel_and_fills_the_area() {
        let config = Config {
            layout: LayoutConfig {
                rows: vec![
                    LayoutRow {
                        height: 50,
                        panels: vec![
                            LayoutPanel {
                                widget: "clocks".into(),
                                width: 50,
                            },
                            LayoutPanel {
                                widget: "cpu".into(),
                                width: 50,
                            },
                        ],
                    },
                    LayoutRow {
                        height: 50,
                        panels: vec![LayoutPanel {
                            widget: "network".into(),
                            width: 100,
                        }],
                    },
                ],
            },
            ..Config::default()
        };
        let app = App::new(config).unwrap();
        let area = Rect::new(0, 0, 80, 24);
        let rects = app.geometry(area);

        assert_eq!(rects.len(), 3);
        assert_eq!(rects[2].width, 80);
        assert_eq!(rects[0].width + rects[1].width, 80);
        assert_eq!(rects[0].x, 0);
        assert_eq!(rects[1].x, rects[0].width);
        for rect in &rects {
            assert!(rect.x + rect.width <= area.x + area.width);
            assert!(rect.y + rect.height <= area.y + area.height);
        }
    }

    #[test]
    fn a_layout_entry_that_builds_no_panel_does_not_shift_the_rest() {
        // `geometry` used to push one rect per layout column and `render` read
        // it back by slot index. Any entry that produced no panel made the two
        // disagree, so every later slot drew — and hit-tested clicks — in the
        // previous entry's box.
        //
        // `Config::validate` rejects an unknown widget name, but `App::new`
        // does not re-validate and neither does `rebuild_panels`, so this is
        // one `config.layout` mutation away from being reachable.
        let mut config = config_with(&["nope", "clocks", "cpu"]);
        config.layout.rows[0].panels[0].width = 25;
        config.layout.rows[0].panels[1].width = 25;
        config.layout.rows[0].panels[2].width = 50;

        let app = App::new(config).unwrap();
        assert_eq!(app.slots.len(), 2, "the unknown widget builds no panel");
        assert_eq!(slot_positions(&app), vec![(0, 1), (0, 2)]);

        let rects = app.geometry(Rect::new(0, 0, 80, 24));
        assert_eq!(rects.len(), 2, "one rect per slot, not per layout column");

        // Column 0 is 20 cells wide and belongs to nothing. The clock is the
        // first *slot* but the second *column*, so it starts at x = 20.
        assert_eq!(
            rects[0].x, 20,
            "the clock took the missing panel's rectangle"
        );
        assert_eq!(rects[1].x, rects[0].x + rects[0].width);
        assert_eq!(rects[0].width + rects[1].width, 60);
    }

    /// Where each slot says it sits in `config.layout`, in slot order.
    fn slot_positions(app: &App) -> Vec<(usize, usize)> {
        app.slots.iter().map(|slot| slot.position).collect()
    }

    /// Every slot's `(row, column)` names the layout entry it was built for,
    /// through every kind of rebuild: a panel moved along its row and into
    /// the next, a whole row moved, and a panel toggled off and back on in
    /// the picker. A resize, a move and `geometry` all find a panel's place
    /// from it, so a slot left holding the place it had before a rebuild
    /// resizes the wrong weights and draws in another panel's box.
    #[test]
    fn every_slot_knows_where_it_sits_after_a_rebuild() {
        let check = |app: &App, after: &str| {
            for (slot, (row, column)) in app.slots.iter().zip(slot_positions(app)) {
                let entry = app
                    .config
                    .layout
                    .rows
                    .get(row)
                    .and_then(|r| r.panels.get(column))
                    .map(|entry| entry.widget.as_str());
                assert_eq!(
                    entry,
                    Some(slot.widget.as_str()),
                    "after {after}, the `{}` slot says it sits at ({row}, {column})",
                    slot.widget
                );
            }
        };
        let mut app = App::new(resizable()).expect("builds");
        check(&app, "building");
        let before = widgets_by_row(&app);

        app.focus = 0;
        app.handle_key(key(KeyCode::Char('m')));
        app.handle_key(key(KeyCode::Right));
        check(&app, "a move along the row");
        app.handle_key(key(KeyCode::Down));
        check(&app, "a move into the next row");
        app.handle_key(KeyEvent::new(KeyCode::Up, KeyModifiers::SHIFT));
        check(&app, "a row move");
        app.handle_key(key(KeyCode::Enter));
        assert_ne!(widgets_by_row(&app), before, "the moves moved nothing");

        app.handle_key(key(KeyCode::Char('w')));
        app.handle_key(key(KeyCode::Char(' ')));
        check(&app, "a toggle off");
        app.handle_key(key(KeyCode::Char(' ')));
        check(&app, "a toggle back on");
    }

    #[test]
    fn a_settled_dashboard_stops_asking_to_be_redrawn() {
        // The property this whole change exists for: with nothing moving,
        // ticking must eventually report no change. Before, every panel whose
        // timer fired counted as one, so the dashboard never went quiet and
        // repainted at the fastest panel's cadence for ever.
        //
        // Panels that legitimately change on a timer are left out: the clock
        // (its second or minute turns), pomodoro while running, and cpu and
        // network (a fresh sample is a new number). What is left must settle.
        let mut app = App::new(config_with(&["todo", "notes", "calendar"])).unwrap();

        // The first tick may report a change; nothing has been drawn yet.
        app.tick_panels();

        for round in 0..5 {
            // Force every panel due, so this cannot pass by ticking nothing.
            for slot in &mut app.slots {
                slot.last_tick = None;
            }
            assert!(
                !app.tick_panels(),
                "round {round}: a dashboard with nothing moving asked for a repaint"
            );
        }
    }

    #[test]
    fn a_due_panel_is_ticked_even_when_an_earlier_one_already_reported_a_change() {
        // `changed = changed || panel.tick()` would short-circuit and skip the
        // call, and a panel that stops being ticked stops updating — a bug
        // that would show up only when some *other* panel happened to change
        // first.
        //
        // The calls are counted by the panels themselves. This test used to
        // check `last_tick`, which `tick_panels` sets on the next line whether
        // or not `tick()` ran, so it passed with the short-circuit put back.
        struct TickingPanel {
            ticks: std::rc::Rc<std::cell::Cell<usize>>,
        }

        impl crate::panel::Panel for TickingPanel {
            fn title(&self) -> String {
                "ticking test".into()
            }

            fn tick(&mut self) -> bool {
                self.ticks.set(self.ticks.get() + 1);
                true
            }

            fn render(
                &mut self,
                _frame: &mut ratatui::Frame,
                _area: Rect,
                _ctx: crate::panel::RenderContext<'_>,
            ) {
            }
        }

        let first = std::rc::Rc::new(std::cell::Cell::new(0));
        let second = std::rc::Rc::new(std::cell::Cell::new(0));
        let panels: Vec<(&str, Box<dyn Panel>)> = vec![
            (
                "clocks",
                Box::new(TickingPanel {
                    ticks: first.clone(),
                }),
            ),
            (
                "todo",
                Box::new(TickingPanel {
                    ticks: second.clone(),
                }),
            ),
        ];
        let mut app = App::with_panels(config_with(&["clocks", "todo"]), panels).unwrap();
        for slot in &mut app.slots {
            slot.last_tick = None;
        }
        assert!(app.tick_panels(), "both panels reported a change");
        assert_eq!(
            (first.get(), second.get()),
            (1, 1),
            "each due panel is ticked once, the second even after the first changed"
        );
    }

    #[test]
    fn geometry_survives_a_terminal_too_small_to_draw() {
        let app = App::new(config_with(&["clocks", "cpu"])).unwrap();
        for (w, h) in [(0, 0), (1, 1), (3, 2)] {
            let rects = app.geometry(Rect::new(0, 0, w, h));
            assert_eq!(rects.len(), 2, "must still return one rect per panel");
        }
    }

    #[test]
    fn zero_weights_are_treated_as_one_rather_than_dividing_by_zero() {
        let config = Config {
            layout: LayoutConfig {
                rows: vec![LayoutRow {
                    height: 0,
                    panels: vec![LayoutPanel {
                        widget: "cpu".into(),
                        width: 0,
                    }],
                }],
            },
            ..Config::default()
        };
        let app = App::new(config).unwrap();
        let rects = app.geometry(Rect::new(0, 0, 80, 24));
        assert_eq!(rects.len(), 1);
        assert!(rects[0].width > 0);
    }

    #[test]
    fn quit_keys_set_the_quit_flag() {
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        assert!(!app.should_quit);
        app.handle_key(KeyEvent::new(KeyCode::Char('q'), KeyModifiers::NONE));
        assert!(app.should_quit);

        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.handle_key(KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL));
        assert!(app.should_quit);

        // Esc must not. The task panel tells you to press it to clear a filter,
        // and a panel only consumes it while the filter is non-empty — so when
        // Esc also quit, the same key in the same panel one keystroke apart
        // either cleared the filter or killed the dashboard.
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.handle_key(KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE));
        assert!(
            !app.should_quit,
            "Esc means back out of something, not quit"
        );
    }

    /// `config` with `[keys]` set from `toml_text`.
    fn with_keys(config: Config, toml_text: &str) -> Config {
        Config {
            keys: crate::keymap::keys_config(toml_text),
            ..config
        }
    }

    /// A rebound quit key replaces `q` rather than joining it, and Ctrl+C is
    /// untouched by any of it — invariant 2's way out does not depend on the
    /// reader's config being sensible.
    #[test]
    fn a_rebound_quit_key_replaces_q_and_ctrl_c_still_quits() {
        let config = || with_keys(config_with(&["clocks"]), "[keys]\nquit = \"x\"");

        let mut app = App::new(config()).unwrap();
        app.handle_key(KeyEvent::from(KeyCode::Char('q')));
        assert!(!app.should_quit, "q is no longer the quit key");
        app.handle_key(KeyEvent::from(KeyCode::Char('x')));
        assert!(app.should_quit, "x is");

        let mut app = App::new(config()).unwrap();
        app.handle_key(KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL));
        assert!(app.should_quit, "and Ctrl+C always is");
    }

    /// #284, end to end: Ctrl+arrows switch desktops on a Mac, so resize moves
    /// to Alt. Alt resizes, Ctrl no longer does, arrange mode lets Alt through
    /// the way it let Ctrl through, and both bars say where the keys went.
    #[test]
    fn resize_rebound_to_alt_works_everywhere_ctrl_did() {
        let config = with_keys(
            resizable(),
            r#"
            [keys]
            resize_wider = "alt+right"
            resize_narrower = "alt+left"
            resize_taller = "alt+down"
            resize_shorter = "alt+up"
            "#,
        );
        let widths = |app: &App| -> Vec<u16> {
            app.config.layout.rows[0]
                .panels
                .iter()
                .map(|p| p.width)
                .collect()
        };
        let mut app = App::new(config).expect("builds");
        app.focus = 0;
        let before = widths(&app);

        app.handle_key(KeyEvent::new(KeyCode::Right, KeyModifiers::CONTROL));
        assert_eq!(widths(&app), before, "Ctrl+→ is not a resize key any more");

        app.handle_key(KeyEvent::new(KeyCode::Right, KeyModifiers::ALT));
        let widened = widths(&app);
        assert!(widened[0] > before[0], "Alt+→ widened the panel");

        app.handle_key(KeyEvent::from(KeyCode::Char('m')));
        let arrangement = widgets_by_row(&app);
        app.handle_key(KeyEvent::new(KeyCode::Right, KeyModifiers::ALT));
        assert_eq!(
            widgets_by_row(&app),
            arrangement,
            "inside arrange mode Alt+→ resized rather than moving the panel"
        );
        assert!(widths(&app)[0] > widened[0], "and it did resize");

        let legend = status_bar_at(&mut app, 120);
        app.handle_key(KeyEvent::from(KeyCode::Enter));
        let plain = status_bar_at(&mut app, 120);
        for bar in [&plain, &legend] {
            assert!(bar.contains("Alt+←→↑↓ resize"), "{bar}");
            assert!(!bar.contains("Ctrl+←"), "{bar}");
        }
    }

    /// A config file of its own, removed when the test ends.
    struct KeysFile {
        path: std::path::PathBuf,
        _dir: TempDir,
    }

    impl KeysFile {
        fn new(name: &str, text: &str) -> Self {
            let dir = TempDir::new(&format!("keymap-{name}"));
            let path = dir.join("config.toml");
            std::fs::write(&path, text).expect("write");
            Self { path, _dir: dir }
        }

        fn text(&self) -> String {
            std::fs::read_to_string(&self.path).expect("read")
        }
    }

    fn open_key_map(app: &mut App) {
        app.handle_key(KeyEvent::from(KeyCode::Char('?')));
        assert!(app.show_help, "the first press opens help");
        app.handle_key(KeyEvent::from(KeyCode::Char('?')));
        assert!(
            !app.show_help && app.keymap_dialog.is_some(),
            "the second, the key map"
        );
    }

    /// The only place the key map is advertised is the help overlay's footer,
    /// so the footer has to say it — in the help key's own name.
    #[test]
    fn help_says_how_to_reach_the_key_map_and_the_key_map_opens() {
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.handle_key(KeyEvent::from(KeyCode::Char('?')));
        let backend = ratatui::backend::TestBackend::new(100, 40);
        let mut terminal = ratatui::Terminal::new(backend).expect("terminal");
        terminal.draw(|frame| app.render(frame)).expect("draw");
        let screen: String = terminal
            .backend()
            .buffer()
            .content()
            .iter()
            .map(ratatui::buffer::Cell::symbol)
            .collect();
        assert!(screen.contains("? key map"), "the footer names the way in");

        app.handle_key(KeyEvent::from(KeyCode::Char('?')));
        assert!(app.keymap_dialog.is_some());
        app.handle_key(KeyEvent::from(KeyCode::Esc));
        assert!(app.keymap_dialog.is_none(), "Esc closes it");
        assert!(!app.should_quit);
    }

    /// Invariant 2 holds inside the dialog too: it reads keys, and Ctrl+C is
    /// taken before it can.
    #[test]
    fn ctrl_c_quits_from_inside_the_key_map_even_mid_question() {
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        open_key_map(&mut app);
        app.handle_key(KeyEvent::from(KeyCode::Char('d')));
        app.handle_key(KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL));
        assert!(app.should_quit);
    }

    /// Edit the config, press `r`, and the new keys are live — no restart.
    /// A bad edit is reported and the keys in force stay in force.
    #[test]
    fn reload_applies_a_good_edit_and_refuses_a_bad_one() {
        let file = KeysFile::new("reload", "[keys]\nquit = \"x\"\n");
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.write_layout_to(file.path.clone());
        open_key_map(&mut app);

        app.handle_key(KeyEvent::from(KeyCode::Char('r')));
        assert_eq!(
            app.keymap.action(KeyEvent::from(KeyCode::Char('x'))),
            Some(Action::Quit),
            "the edit is live"
        );

        std::fs::write(&file.path, "[keys]\ntheme = \"q\"\n").expect("write");
        app.handle_key(KeyEvent::from(KeyCode::Char('r')));
        assert_eq!(
            app.keymap.action(KeyEvent::from(KeyCode::Char('x'))),
            Some(Action::Quit),
            "a clash is refused and x still quits"
        );
    }

    /// A panel's keys reload and reset with the shell's, and the panel that
    /// is already on screen takes them at once — it is carried across, not
    /// rebuilt, so nothing but [`Panel::set_keys`] would ever tell it.
    #[test]
    fn a_live_panel_takes_its_keys_from_a_reload_and_gives_them_back_on_reset() {
        use crate::panel::KeyOutcome;
        let file = KeysFile::new(
            "panel",
            "[cpu]\nhistory = 5\n\n[cpu.keys]\nper_core = \"p\"\n",
        );
        let mut app = App::new(config_with(&["cpu"])).unwrap();
        app.write_layout_to(file.path.clone());
        let press = |app: &mut App, c| {
            app.slots[0]
                .panel
                .handle_key(KeyEvent::from(KeyCode::Char(c)))
        };
        let hinted =
            |app: &App, key: &str| app.slots[0].panel.bindings().iter().any(|b| b.key == key);
        assert!(hinted(&app, "c"));

        open_key_map(&mut app);
        app.handle_key(KeyEvent::from(KeyCode::Char('r')));
        assert_eq!(
            press(&mut app, 'p'),
            KeyOutcome::Consumed,
            "the new key is live"
        );
        assert_eq!(
            press(&mut app, 'c'),
            KeyOutcome::Ignored,
            "the old one is gone"
        );
        assert!(
            hinted(&app, "p") && !hinted(&app, "c"),
            "and the hint follows"
        );

        app.handle_key(KeyEvent::from(KeyCode::Char('d')));
        app.handle_key(KeyEvent::from(KeyCode::Char('y')));
        let text = file.text();
        assert!(text.contains("\n# per_core = \"p\""), "{text}");
        assert!(text.starts_with("[cpu]\nhistory = 5\n"), "{text}");
        assert_eq!(
            press(&mut app, 'c'),
            KeyOutcome::Consumed,
            "the default is back"
        );
        assert!(hinted(&app, "c"));
    }

    #[test]
    fn a_panel_keymap_that_does_not_check_out_does_not_start() {
        let mut config = config_with(&["cpu"]);
        config.cpu.keys = toml::from_str("per_core = \"1\"").expect("a table");
        let Err(error) = App::new(config) else {
            panic!("a panel key on a jump key was accepted");
        };
        assert!(error.to_string().contains("[cpu.keys]"), "{error}");
    }

    /// `d`, then `y`: the file's `[keys]` lines are commented out and the
    /// defaults are live at once. Anything else leaves both alone.
    #[test]
    fn defaults_resets_the_file_and_the_live_keys_only_on_yes() {
        let file = KeysFile::new("reset", "[general]\nmouse = true\n\n[keys]\nquit = \"x\"\n");
        let config = with_keys(config_with(&["clocks"]), "[keys]\nquit = \"x\"");
        let mut app = App::new(config).unwrap();
        app.write_layout_to(file.path.clone());
        open_key_map(&mut app);

        app.handle_key(KeyEvent::from(KeyCode::Char('d')));
        app.handle_key(KeyEvent::from(KeyCode::Char('n')));
        assert!(
            file.text().contains("\nquit = \"x\""),
            "a no changed nothing"
        );
        assert!(!app.keymap.is_default(Action::Quit));

        app.handle_key(KeyEvent::from(KeyCode::Char('d')));
        app.handle_key(KeyEvent::from(KeyCode::Char('y')));
        assert!(file.text().contains("\n# quit = \"x\""), "{}", file.text());
        assert!(file.text().starts_with("[general]\nmouse = true\n"));
        assert!(app.keymap.is_default(Action::Quit), "the defaults are live");
        assert!(
            app.keymap_dialog.is_some(),
            "and the dialog stays to say so"
        );
    }

    /// What the key map last reported, and whether it said so as a failure.
    fn key_map_notice(app: &App) -> (String, bool) {
        let (text, failed) = app
            .keymap_dialog
            .as_ref()
            .and_then(crate::keymap_dialog::KeymapDialog::notice)
            .expect("the key map reported something");
        (text.to_string(), failed)
    }

    /// A reload that does not check out is reported in the failure colour,
    /// and says the keys in force were kept. Nothing read either half of the
    /// report back, so a flag flipped on this branch would have shown a
    /// refused keymap as though it had loaded.
    #[test]
    fn a_key_reload_that_does_not_check_out_is_reported_as_a_failure() {
        let file = KeysFile::new("reload-refused", "[keys]\nquit = \"no such key\"\n");
        let mut app = App::new(config_with(&["clocks"])).expect("builds");
        app.write_layout_to(file.path.clone());
        open_key_map(&mut app);
        app.handle_key(key(KeyCode::Char('r')));

        let (text, failed) = key_map_notice(&app);
        assert!(failed, "reported as a success: {text}");
        assert!(text.starts_with("Kept the keys you had. "), "{text}");
        assert!(app.keymap.is_default(Action::Quit), "and nothing changed");
    }

    /// The other half: a reload that checks out says what it loaded, and not
    /// in the failure colour.
    #[test]
    fn a_key_reload_that_checks_out_is_reported_as_a_success() {
        let file = KeysFile::new("reload-taken", "[keys]\nquit = \"x\"\n");
        let mut app = App::new(config_with(&["clocks"])).expect("builds");
        app.write_layout_to(file.path.clone());
        open_key_map(&mut app);
        app.handle_key(key(KeyCode::Char('r')));

        let (text, failed) = key_map_notice(&app);
        assert!(!failed, "reported as a failure: {text}");
        assert_eq!(text, "Loaded. One key differs from its default.");
    }

    /// A reset with no config file to rewrite says nothing was changed, as a
    /// failure; one that lands says the keys are back, as a success. The
    /// same report as a reload's, and as unread until these.
    #[test]
    fn a_key_reset_says_whether_it_took() {
        let mut app = App::new(config_with(&["clocks"])).expect("builds");
        open_key_map(&mut app);
        app.handle_key(key(KeyCode::Char('d')));
        app.handle_key(key(KeyCode::Char('y')));
        let (text, failed) = key_map_notice(&app);
        assert!(failed, "reported as a success: {text}");
        assert!(text.starts_with("Nothing was changed. "), "{text}");

        let file = KeysFile::new("reset-taken", "[keys]\nquit = \"x\"\n");
        app.write_layout_to(file.path.clone());
        app.handle_key(key(KeyCode::Char('d')));
        app.handle_key(key(KeyCode::Char('y')));
        let (text, failed) = key_map_notice(&app);
        assert!(!failed, "reported as a failure: {text}");
        assert!(
            text.starts_with("Every key is back to its default."),
            "{text}"
        );
    }

    /// `config` with `[arrange.keys]` set from `toml_text`.
    fn with_arrange_keys(config: Config, toml_text: &str) -> Config {
        let mut config = config;
        config.arrange.keys = toml::from_str(toml_text).expect("a table");
        config
    }

    /// A moved arrange key moves the panel and the old one does nothing —
    /// and a Ctrl key, which the mode used to hand straight on, is the mode's
    /// once `[arrange.keys]` binds it.
    #[test]
    fn a_moved_arrange_key_works_even_with_ctrl_and_the_old_key_is_free() {
        let config = with_arrange_keys(resizable(), "move_right = \"ctrl+l\"");
        let mut app = App::new(config).expect("builds");
        app.focus = 0;
        app.handle_key(KeyEvent::from(KeyCode::Char('m')));
        let before = widgets_by_row(&app);

        app.handle_key(KeyEvent::from(KeyCode::Right));
        app.handle_key(KeyEvent::from(KeyCode::Char('l')));
        assert_eq!(
            widgets_by_row(&app),
            before,
            "neither old key moves anything"
        );

        app.handle_key(KeyEvent::new(KeyCode::Char('l'), KeyModifiers::CONTROL));
        assert_ne!(widgets_by_row(&app), before, "Ctrl+L moved the panel");
        assert!(app.arranging.is_some(), "and the mode is still open");

        let legend = status_bar_at(&mut app, 200);
        assert!(legend.contains("Ctrl+l move right"), "{legend}");
    }

    /// Reload reaches a mode that is already open: the keys change under the
    /// reader's hands, as the panels' do.
    #[test]
    fn reload_gives_arrange_mode_its_new_keys() {
        let file = KeysFile::new("arrange", "[arrange.keys]\nkeep = \"space\"\n");
        let mut app = App::new(resizable()).expect("builds");
        app.write_layout_to(file.path.clone());
        open_key_map(&mut app);
        app.handle_key(KeyEvent::from(KeyCode::Char('r')));
        app.handle_key(KeyEvent::from(KeyCode::Esc));

        app.handle_key(KeyEvent::from(KeyCode::Char('m')));
        app.handle_key(KeyEvent::from(KeyCode::Enter));
        assert!(app.arranging.is_some(), "Enter no longer keeps");
        app.handle_key(KeyEvent::from(KeyCode::Char(' ')));
        assert!(app.arranging.is_none(), "space does");
    }

    /// Reload reaches both pickers: a picker opened after it reads the new
    /// keys, the same way arrange mode and the panels do.
    #[test]
    fn reload_gives_the_pickers_their_new_keys() {
        let file = KeysFile::new(
            "pickers",
            "[panel_picker.keys]\nclose = \"x\"\n\n[theme_picker.keys]\nput_back = \"x\"\n\n\
             [help_overlay.keys]\ndown = \"s\"\n",
        );
        let mut app = App::new(config_with(&["clocks"])).expect("builds");
        app.write_layout_to(file.path.clone());
        open_key_map(&mut app);
        app.handle_key(KeyEvent::from(KeyCode::Char('r')));
        app.handle_key(KeyEvent::from(KeyCode::Esc));

        app.handle_key(KeyEvent::from(KeyCode::Char('w')));
        app.handle_key(KeyEvent::from(KeyCode::Char('q')));
        assert!(app.picker.is_some(), "q no longer closes the panel picker");
        app.handle_key(KeyEvent::from(KeyCode::Char('x')));
        assert!(app.picker.is_none(), "x does");

        app.handle_key(KeyEvent::from(KeyCode::Char('t')));
        app.handle_key(KeyEvent::from(KeyCode::Char('t')));
        assert!(
            app.theme_picker.is_some(),
            "t no longer puts the theme back"
        );
        app.handle_key(KeyEvent::from(KeyCode::Char('x')));
        assert!(app.theme_picker.is_none(), "x does");
        assert_eq!(
            app.help_keys.action(KeyEvent::from(KeyCode::Char('s'))),
            Some(crate::keymap::HelpAction::Down),
            "and the help overlay's"
        );
    }

    /// The keys the shell holds live for the mode `[<mode>.keys]` configures,
    /// as the key map would list them. A mode with no arm here is one whose
    /// table nothing reads, and says so.
    fn live_mode_keys(app: &App, mode: &str) -> Vec<(&'static str, Vec<crate::keymap::Key>)> {
        let listing = match mode {
            "arrange" => app.arrange_keys.listing(),
            "panel_picker" => app.panel_picker_keys.listing(),
            "theme_picker" => app.theme_picker_keys.listing(),
            "help_overlay" => app.help_keys.listing(),
            other => panic!("[{other}.keys] is a mode the shell holds no live keys for"),
        };
        listing
            .into_iter()
            .map(|listed| (listed.name, listed.keys))
            .collect()
    }

    /// Every table in `MODE_SCOPES` reaches a field the shell reads keys
    /// from. The tests above each name the modes they knew of; this one asks
    /// the list, so a mode added to it whose reload lands nowhere — checked,
    /// listed in the key map, reset, and never in force — fails here.
    #[test]
    fn every_mode_table_reloads_into_the_keys_the_shell_reads() {
        for scope in crate::keymap::MODE_SCOPES {
            let defaults = (scope.listing)(&crate::keymap::KeysConfig::default()).expect("valid");
            let moved = defaults.first().expect("a mode has keys").name;
            let table = format!("{moved} = \"f9\"\n");
            let file = KeysFile::new(
                &format!("mode-{}", scope.widget),
                &format!("[{}.keys]\n{table}", scope.widget),
            );
            let mut app = App::new(config_with(&["clocks"])).expect("builds");
            app.write_layout_to(file.path.clone());
            assert_ne!(
                live_mode_keys(&app, scope.widget)[0].1,
                vec!["f9".parse::<crate::keymap::Key>().expect("a key")],
                "{}: f9 is not already the default",
                scope.widget
            );

            app.reload_keys();

            let written: crate::keymap::KeysConfig = toml::from_str(&table).expect("a table");
            let expected: Vec<_> = (scope.listing)(&written)
                .expect("valid")
                .into_iter()
                .map(|listed| (listed.name, listed.keys))
                .collect();
            assert_eq!(
                live_mode_keys(&app, scope.widget),
                expected,
                "[{}.keys] reloaded into nothing the shell reads",
                scope.widget
            );
        }
    }

    /// An open picker is offered every key before resizing is, so a picker
    /// key may be a resize key — it is the picker's while the picker is open,
    /// and a resize again once it closes. Arrange mode reads after resize,
    /// and there the same key is refused.
    #[test]
    fn a_picker_key_may_be_a_resize_key_but_an_arrange_key_may_not() {
        let mut config = resizable();
        config.panel_picker.keys = toml::from_str("down = \"ctrl+down\"").expect("a table");
        let mut app = App::new(config).expect("a picker may use a resize key");
        app.handle_key(KeyEvent::from(KeyCode::Char('w')));
        let before = app.picker.as_ref().expect("open").selected();
        app.handle_key(KeyEvent::new(KeyCode::Down, KeyModifiers::CONTROL));
        assert_eq!(
            app.picker.as_ref().expect("still open").selected(),
            before + 1,
            "Ctrl+↓ moved the cursor in the picker"
        );
        assert!(!app.layout_dirty, "and resized nothing");

        let mut config = resizable();
        config.arrange.keys = toml::from_str("move_down = \"ctrl+down\"").expect("a table");
        let Err(error) = App::new(config) else {
            panic!("an arrange key on a resize key was accepted");
        };
        assert!(error.to_string().contains("[arrange.keys]"), "{error}");
    }

    /// The help footer an 80x24 terminal actually shows, scrolled to the top,
    /// the middle and the bottom: the position, the way to the key map and
    /// the way out, all three, and never a line ending on a separator. It
    /// shipped in 1.17.0 reading `? key map ·` and nothing else.
    #[test]
    fn the_help_footer_keeps_its_position_and_ends_on_no_separator() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;
        let mut app = App::new(config_with(&["todo"])).expect("builds");
        let mut terminal = Terminal::new(TestBackend::new(80, 24)).unwrap();
        app.handle_key(KeyEvent::from(KeyCode::Char('?')));
        terminal.draw(|frame| app.render_for_test(frame)).unwrap();
        assert!(
            app.help_overflow > 0,
            "the test needs an overlay that scrolls"
        );

        for key in [KeyCode::Home, KeyCode::Down, KeyCode::End] {
            app.handle_key(KeyEvent::from(key));
            terminal.draw(|frame| app.render_for_test(frame)).unwrap();
            let footer = crate::widgets::testing::rows(terminal.backend().buffer())
                .into_iter()
                .find(|row| row.contains("key map"))
                .expect("the footer row");
            let text = footer.split('│').nth(1).expect("inside the overlay").trim();
            assert!(
                text.contains('/') && text.contains("? key map") && text.contains("close"),
                "{key:?}: {text}"
            );
            assert!(!text.ends_with('·'), "{key:?}: {text}");
        }

        // Every width the footer could be squeezed to ends on a whole part.
        for width in 1..60 {
            let line = app.help_footer(&crate::theme::Theme::default(), width);
            let text: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
            assert!(!text.trim_end().ends_with('·'), "{width}: {text}");
        }
    }

    /// A moved scroll key scrolls the overlay, the old one closes it like any
    /// other key, and the footer names the new one.
    #[test]
    fn a_moved_help_scroll_key_scrolls_and_the_old_one_closes() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;
        let mut config = config_with(&["todo"]);
        config.help_overlay.keys = toml::from_str("down = \"s\"").expect("a table");
        let mut app = App::new(config).expect("builds");
        let mut terminal = Terminal::new(TestBackend::new(80, 24)).unwrap();
        app.handle_key(KeyEvent::from(KeyCode::Char('?')));
        terminal.draw(|frame| app.render_for_test(frame)).unwrap();
        assert!(
            app.help_overflow > 0,
            "the test needs an overlay that scrolls"
        );

        let footer = crate::widgets::testing::rows(terminal.backend().buffer())
            .into_iter()
            .find(|row| row.contains("key map"))
            .expect("the footer row");
        let text = footer.split('│').nth(1).expect("inside the overlay").trim();
        assert!(
            text.starts_with("s "),
            "the footer names the new key: {text}"
        );

        app.handle_key(KeyEvent::from(KeyCode::Char('s')));
        assert_eq!(app.help_scroll, 1, "s scrolled");
        assert!(app.show_help);
        app.handle_key(KeyEvent::from(KeyCode::Down));
        assert!(!app.show_help, "the old key closes it like any other");
    }

    #[test]
    fn a_keymap_that_does_two_things_with_one_key_does_not_start() {
        let config = with_keys(config_with(&["clocks"]), "[keys]\ntheme = \"q\"");
        let Err(error) = App::new(config) else {
            panic!("a clashing keymap was accepted");
        };
        let error = error.to_string();
        assert!(error.contains("bound to both"), "{error}");
    }

    #[test]
    fn only_a_focused_capturing_panel_can_shorten_the_event_wait() {
        struct ResponsivePanel {
            capturing: bool,
        }

        impl crate::panel::Panel for ResponsivePanel {
            fn title(&self) -> String {
                "responsive test".into()
            }

            fn refresh_interval(&self) -> Duration {
                Duration::from_millis(8)
            }

            fn captures_input(&self) -> bool {
                self.capturing
            }

            fn render(
                &mut self,
                _frame: &mut ratatui::Frame,
                _area: Rect,
                _ctx: crate::panel::RenderContext<'_>,
            ) {
            }
        }

        let configured = Duration::from_millis(250);
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.slots[0].panel = Box::new(ResponsivePanel { capturing: false });
        assert_eq!(app.poll_wait(configured), configured);

        app.slots[0].panel = Box::new(ResponsivePanel { capturing: true });
        assert_eq!(app.poll_wait(configured), Duration::from_millis(16));
        assert_eq!(
            app.poll_wait(Duration::from_millis(10)),
            Duration::from_millis(10),
            "a panel may ask for responsiveness but never slow the configured loop"
        );

        app.handle_key(KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL));
        assert!(
            app.should_quit,
            "even a capturing panel cannot intercept Ctrl+C"
        );
    }

    #[test]
    fn clipboard_inputs_reach_the_editor_before_global_keys() {
        struct CopyPanel {
            selected: bool,
            pasted: std::rc::Rc<std::cell::RefCell<String>>,
        }

        impl crate::panel::Panel for CopyPanel {
            fn title(&self) -> String {
                "copy test".to_string()
            }

            fn render(
                &mut self,
                _frame: &mut ratatui::Frame,
                _area: Rect,
                _ctx: crate::panel::RenderContext<'_>,
            ) {
            }

            fn copy_selection(&mut self) -> crate::panel::KeyOutcome {
                if std::mem::take(&mut self.selected) {
                    crate::panel::KeyOutcome::Consumed
                } else {
                    crate::panel::KeyOutcome::Ignored
                }
            }

            fn handle_paste(&mut self, text: &str) -> crate::panel::KeyOutcome {
                self.pasted.borrow_mut().push_str(text);
                crate::panel::KeyOutcome::Consumed
            }
        }

        let mut app = App::new(config_with(&["clocks"])).unwrap();
        let pasted = std::rc::Rc::new(std::cell::RefCell::new(String::new()));
        app.slots[0].panel = Box::new(CopyPanel {
            selected: true,
            pasted: pasted.clone(),
        });
        let ctrl_c = KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL);

        app.handle_key(ctrl_c);
        assert!(!app.should_quit, "the selection gets Ctrl+C first");
        assert!(app.handle_paste("one\n\ttwo"));
        assert_eq!(&*pasted.borrow(), "one\n\ttwo", "paste stays one block");
        app.handle_key(ctrl_c);
        assert!(app.should_quit, "without a selection Ctrl+C still quits");
    }

    #[test]
    fn number_keys_jump_to_a_panel_and_ignore_out_of_range_indices() {
        let mut app = App::new(config_with(&["clocks", "cpu"])).unwrap();
        app.handle_key(KeyEvent::new(KeyCode::Char('2'), KeyModifiers::NONE));
        assert_eq!(app.focus, 1);
        app.handle_key(KeyEvent::new(KeyCode::Char('9'), KeyModifiers::NONE));
        assert_eq!(app.focus, 1, "an out-of-range index must not move focus");
    }

    /// The digits pick the panel to move inside arrange mode as they pick
    /// one outside it. The mode is the second of the two places that read
    /// them, and until this test nothing had pressed a digit there.
    #[test]
    fn number_keys_pick_the_panel_to_move_inside_arrange_mode_too() {
        let mut app = App::new(resizable()).expect("builds");
        app.focus = 0;
        let before = widgets_by_row(&app);
        app.handle_key(KeyEvent::from(KeyCode::Char('m')));

        app.handle_key(KeyEvent::from(KeyCode::Char('3')));
        assert_eq!(app.slots[app.focus].widget, "cpu", "3 picked the third");
        app.handle_key(KeyEvent::from(KeyCode::Char('9')));
        assert_eq!(app.focus, 2, "an out-of-range index moves nothing");
        assert!(app.arranging.is_some(), "and the mode is still open");
        assert_eq!(widgets_by_row(&app), before, "with nothing moved");
    }

    #[test]
    fn help_opens_and_the_next_key_closes_it() {
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.handle_key(KeyEvent::new(KeyCode::Char('?'), KeyModifiers::NONE));
        assert!(app.show_help);
        app.handle_key(KeyEvent::new(KeyCode::Char('x'), KeyModifiers::NONE));
        assert!(!app.show_help);
        assert!(!app.should_quit, "closing help must not also quit");
    }

    fn key(code: KeyCode) -> KeyEvent {
        KeyEvent::new(code, KeyModifiers::NONE)
    }

    /// Walk the theme picker down to a named theme and report what it landed on.
    fn preview_a_theme(app: &mut App) -> String {
        app.handle_key(key(KeyCode::Char('t')));
        // Down until the accent actually moves. The list is alphabetical and
        // starts on `ansi`, whose accent is an ANSI index rather than an RGB
        // triple, so the first row that differs is a real repaint.
        let start = app.config.theme.accent;
        for _ in 0..20 {
            app.handle_key(key(KeyCode::Down));
            if app.config.theme.accent != start {
                break;
            }
        }
        app.config
            .theme
            .name
            .clone()
            .expect("a previewed theme is a named one")
    }

    #[test]
    fn moving_in_the_theme_picker_repaints_before_anything_is_committed() {
        let mut app = App::new(config_with(&["clocks", "cpu"])).unwrap();
        let before = app.config.theme.accent;
        let name = preview_a_theme(&mut app);
        assert_ne!(
            app.config.theme.accent, before,
            "`{name}` was selected but the live theme did not change"
        );
        assert!(
            app.theme_picker.is_some(),
            "moving must not close the dialog"
        );
    }

    /// The graphs read a baked ramp rather than the theme, so a swap that
    /// forgets it leaves cpu and network painted in the previous palette.
    #[test]
    fn a_theme_swap_rebakes_the_gradients_the_graphs_draw_from() {
        let mut app = App::new(config_with(&["cpu"])).unwrap();
        let before = app.gradients.clone();
        preview_a_theme(&mut app);
        assert_ne!(
            app.gradients, before,
            "the graph ramp still holds the previous theme's colours"
        );
    }

    #[test]
    fn esc_puts_back_the_theme_the_picker_opened_on() {
        let mut app = App::new(config_with(&["clocks", "cpu"])).unwrap();
        let theme = app.config.theme.clone();
        let gradients = app.gradients.clone();

        preview_a_theme(&mut app);
        app.handle_key(key(KeyCode::Esc));

        assert!(app.theme_picker.is_none(), "Esc must close the dialog");
        assert_eq!(app.config.theme.accent, theme.accent, "theme not restored");
        assert_eq!(app.gradients, gradients, "gradients not restored");
    }

    #[test]
    fn enter_keeps_the_previewed_theme() {
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        let name = preview_a_theme(&mut app);
        app.handle_key(key(KeyCode::Enter));

        assert!(app.theme_picker.is_none());
        assert_eq!(
            app.config.theme.name.as_deref(),
            Some(name.as_str()),
            "Enter must keep what was on screen"
        );
    }

    /// The dialog owns the keyboard while it is open. Otherwise `q` under the
    /// cursor quits the dashboard mid-browse, which is invariant 2's rule
    /// applied to a shell dialog rather than a panel.
    #[test]
    fn the_theme_picker_takes_the_keyboard_while_it_is_open() {
        let mut app = App::new(config_with(&["clocks", "todo"])).unwrap();
        app.handle_key(key(KeyCode::Char('t')));
        let focus = app.focus;

        app.handle_key(key(KeyCode::Tab));
        assert_eq!(app.focus, focus, "Tab reached the focus ring");
        app.handle_key(key(KeyCode::Char('w')));
        assert!(
            app.picker.is_none(),
            "`w` opened the panel picker underneath"
        );

        app.handle_key(key(KeyCode::Char('q')));
        assert!(
            !app.should_quit,
            "`q` quit the dashboard from inside a dialog"
        );
        assert!(app.theme_picker.is_none(), "`q` should close the dialog");
    }

    #[test]
    fn the_picker_opens_and_toggles_a_panel_on_and_off() {
        let mut app = App::new(config_with(&["clocks", "todo"])).unwrap();
        let before = app.slots.len();

        app.handle_key(key(KeyCode::Char('w')));
        assert!(app.picker.is_some(), "w opens the dialog");

        // WIDGET_NAMES starts with clocks, which this layout already places.
        app.handle_key(key(KeyCode::Char(' ')));
        assert!(!app.config.layout.places("clocks"), "space turned it off");
        assert_eq!(app.slots.len(), before - 1, "and the panel actually went");
        assert!(app.layout_dirty);

        app.handle_key(key(KeyCode::Char(' ')));
        assert!(
            app.config.layout.places("clocks"),
            "space turned it back on"
        );
        assert_eq!(app.slots.len(), before);
    }

    #[test]
    fn the_picker_moves_and_closes_without_quitting() {
        let mut app = App::new(config_with(&["clocks", "todo"])).unwrap();
        app.handle_key(key(KeyCode::Char('w')));

        // Cursor movement itself is `picker`'s; what matters here is that the
        // keys reach it rather than the panels or the global bindings.
        app.handle_key(key(KeyCode::Down));
        assert_eq!(app.picker_row(), Some(1));
        app.handle_key(key(KeyCode::Up));
        assert_eq!(app.picker_row(), Some(0));

        app.handle_key(key(KeyCode::Esc));
        assert!(app.picker.is_none());
        assert!(
            !app.should_quit,
            "Esc closes the dialog rather than falling through to quit"
        );
    }

    #[test]
    fn rebuilding_shuts_the_outgoing_panels_down() {
        // The picker rebuilds every panel on each toggle. Dropping the old ones
        // without shutdown() discarded the task store's save and left each
        // panel's fetch thread running — so toggling stocks five times left
        // five pollers hitting the same endpoint, defeating the per-thread
        // rate limit the module documents as enforced in code.
        let mut app = App::new(config_with(&["clocks", "todo"])).unwrap();
        let before = std::thread::available_parallelism().is_ok();
        assert!(before, "sanity: threads are available");

        app.handle_key(key(KeyCode::Char('w')));
        for _ in 0..5 {
            app.handle_key(key(KeyCode::Char(' ')));
        }
        // Whatever the toggles did, the dashboard is still coherent and every
        // slot still has a panel behind it.
        assert!(!app.slots.is_empty());
    }

    #[test]
    fn a_panel_ticks_immediately_rather_than_one_interval_late() {
        // Previously arranged by back-dating an Instant by 24 hours, which is
        // None on Windows below that uptime and panicked on the unwrap.
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        assert!(
            app.slots.iter().all(|s| s.last_tick.is_none()),
            "a fresh panel has never ticked"
        );
        assert!(app.tick_panels(), "and is due immediately");
        assert!(app.slots.iter().all(|s| s.last_tick.is_some()));
    }

    #[test]
    fn the_last_panel_cannot_be_switched_off() {
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        app.handle_key(key(KeyCode::Char('w')));
        app.handle_key(key(KeyCode::Char(' ')));

        assert!(
            app.config.layout.places("clocks"),
            "an empty layout is rejected at startup, so this would write a \
             config that cannot be opened again"
        );
        assert_eq!(app.slots.len(), 1);
        let rows = drawn(&mut app, 120, 30).join("\n");
        assert!(
            rows.contains("at least one panel has to stay"),
            "and the picker says why:\n{rows}"
        );

        // A refusal changes nothing and leaves nothing unsaved, so it belongs
        // to the dialog and goes with it. On the bar it read "The layout could
        // not be saved", which was false, and stayed lit until some later
        // layout change happened to succeed.
        app.handle_key(key(KeyCode::Esc));
        assert!(app.picker.is_none());
        assert!(
            app.alert().is_none(),
            "a refusal is not a failed save: {:?}",
            app.alert().map(|alert| alert.text)
        );
        let bar = status_bar_at(&mut app, 120);
        assert!(!bar.contains('⚠'), "and the bar is calm: {bar}");
    }

    /// A paste into a one-line form arrives as keys, and the first newline
    /// commits the form. Whatever follows it is no longer typing: it used to
    /// reach the task list as commands, so a second line beginning with `a`
    /// opened a new task, a space marked one done and `dy` deleted it.
    #[test]
    fn a_paste_stops_at_the_newline_that_closes_a_one_line_form() {
        let dir = TempDir::new("paste");
        let file = dir.join("todos.toml");
        // Empty rather than absent, so the store does not seed examples.
        std::fs::write(&file, "").unwrap();
        let mut config = config_with(&["todo"]);
        config.todo.file = Some(file.clone());
        let mut app = App::new(config).unwrap();

        app.handle_key(key(KeyCode::Char('a')));
        assert!(app.focus_captures_input(), "the task form is open");
        assert!(app.handle_paste("Buy milk\nand eggs\n"));

        let titles: Vec<String> = crate::task::TaskStore::load(&file)
            .unwrap()
            .tasks()
            .iter()
            .map(|task| task.title.clone())
            .collect();
        assert_eq!(
            titles,
            ["Buy milk"],
            "the first line is the task; the rest is not a command"
        );
        assert!(
            !app.focus_captures_input(),
            "and the list is back, not a second form"
        );
    }

    /// A paste is text, and a delete confirmation takes no text. The shell
    /// types a paste no panel claims into a capturing one key by key, so a
    /// paste beginning with `y` answered the question it landed on: `d` on a
    /// task, then a paste of "yesterday's notes", and the task was gone —
    /// the one action in these panels with no undo. Each of the three that
    /// ask now claims the paste and does nothing with it.
    #[test]
    fn a_paste_never_answers_a_delete_confirmation() {
        /// Ask to delete the one item, paste `y`, and check it is still there
        /// and the question is still waiting for a key.
        fn ask_then_paste(app: &mut App, which: &str, items: &dyn Fn() -> usize) {
            assert_eq!(items(), 1, "{which}: one item to begin with");
            app.handle_key(key(KeyCode::Char('d')));
            assert!(app.focus_captures_input(), "{which}: the question is open");
            app.handle_paste("y");
            assert_eq!(items(), 1, "{which}: a pasted `y` deleted the item");
            assert!(
                app.focus_captures_input(),
                "{which}: and the question is still waiting for a key"
            );
            app.handle_key(key(KeyCode::Char('n')));
            assert!(!app.focus_captures_input(), "{which}: `n` still answers it");
            assert_eq!(items(), 1, "{which}: and keeps the item");
        }
        fn type_in(app: &mut App, text: &str) {
            app.handle_key(key(KeyCode::Char('a')));
            for c in text.chars() {
                app.handle_key(key(KeyCode::Char(c)));
            }
            app.handle_key(key(KeyCode::Enter));
        }

        let dir = TempDir::new("confirm");

        // Empty rather than absent, so neither store seeds its examples.
        let tasks = dir.join("todos.toml");
        let notes = dir.join("notes.toml");
        std::fs::write(&tasks, "").unwrap();
        std::fs::write(&notes, "").unwrap();
        let mut config = config_with(&["todo"]);
        config.todo.file = Some(tasks.clone());
        let mut app = App::new(config).unwrap();
        type_in(&mut app, "Doomed");
        ask_then_paste(&mut app, "tasks", &|| {
            crate::task::TaskStore::load(&tasks).unwrap().tasks().len()
        });

        let mut config = config_with(&["notes"]);
        config.notes.file = Some(notes.clone());
        let mut app = App::new(config).unwrap();
        type_in(&mut app, "Doomed");
        ask_then_paste(&mut app, "notes", &|| {
            crate::note::NoteStore::load(&notes).unwrap().notes().len()
        });

        // `build` would reach Yahoo, so the stocks panel goes in by hand, on
        // a canned source, over a calculator that reads nothing.
        let watchlist = dir.join("watchlist.toml");
        std::fs::write(&watchlist, "symbols = [\"AAPL\"]\n").unwrap();
        let mut app = App::new(config_with(&["calculator"])).unwrap();
        app.slots[0].panel = Box::new(
            crate::widgets::stocks::StocksPanel::offline(
                crate::config::StocksConfig {
                    refresh_secs: 86_400,
                    ..crate::config::StocksConfig::default()
                },
                watchlist.clone(),
            )
            .unwrap(),
        );
        ask_then_paste(&mut app, "stocks", &|| {
            crate::quote::Watchlist::load(&watchlist, &[])
                .unwrap()
                .symbols()
                .len()
        });
    }

    /// Previewing is not choosing. Every arrow key in the theme picker used to
    /// write `state.toml`, so the comment on Accept was untrue and a dashboard
    /// killed mid-browse came back in a theme nobody picked.
    #[test]
    fn browsing_themes_writes_nothing_until_one_is_chosen() {
        let dir = TempDir::new("browse");
        let path = dir.join("state.toml");
        let config = config_with(&["clocks"]);
        let baseline = crate::state::UiState::from_config(&config);
        let mut app = App::new(config).unwrap();
        app.remember_preferences_at(path.clone(), crate::state::UiState::default(), baseline);

        app.handle_key(key(KeyCode::Char('t')));
        let mut previewed = Vec::new();
        for _ in 0..2 {
            app.handle_key(key(KeyCode::Down));
            // What the run loop does after every key.
            app.persist_preferences();
            previewed.push(app.config.theme.name.clone());
        }
        assert!(
            previewed.iter().all(Option::is_some) && previewed[0] != previewed[1],
            "two different themes were on screen: {previewed:?}"
        );
        assert!(
            !path.exists(),
            "browsing wrote {:?}",
            std::fs::read_to_string(&path).unwrap_or_default()
        );

        app.handle_key(key(KeyCode::Enter));
        app.persist_preferences();
        let chosen = previewed[1].clone().unwrap();
        let written = std::fs::read_to_string(&path).expect("Enter records the choice");
        assert!(
            written.contains(&chosen),
            "the theme chosen is the one written: {written}"
        );
    }

    /// Arrange mode is a commit point: Keep writes and Esc puts everything
    /// back. A resize inside it used to start the settle timer anyway, so a
    /// pause before Esc left the file holding widths the screen had undone.
    #[test]
    fn a_resize_inside_arrange_mode_waits_for_the_mode_to_close() {
        let dir = TempDir::new("settle");
        let text = "[layout]\nrows = [\n  { height = 1, panels = [\n    { widget = \"clocks\",   width = 50 },\n    { widget = \"calendar\", width = 50 },\n  ] },\n]\n";
        let path = dir.join("config.toml");
        std::fs::write(&path, text).unwrap();
        let mut app = App::new(toml::from_str(text).unwrap()).unwrap();
        app.write_layout_to(path.clone());
        let settled = || Instant::now().checked_sub(RESIZE_SETTLE * 2);

        app.handle_key(key(KeyCode::Char('m')));
        app.handle_key(KeyEvent::new(KeyCode::Right, KeyModifiers::CONTROL));
        assert_ne!(widths(&app), [50, 50], "the resize happened");
        app.last_resize = settled();
        app.write_settled_resize();
        assert_eq!(
            std::fs::read_to_string(&path).unwrap(),
            text,
            "a resize inside the mode is part of the arrangement"
        );

        app.handle_key(key(KeyCode::Esc));
        app.write_settled_resize();
        assert_eq!(widths(&app), [50, 50], "Esc put the widths back");
        assert_eq!(
            std::fs::read_to_string(&path).unwrap(),
            text,
            "and the file never left them"
        );

        // The control: outside the mode the same resize settles to the file,
        // so the silence above is the guard and not a timer that never fires.
        app.handle_key(KeyEvent::new(KeyCode::Right, KeyModifiers::CONTROL));
        app.last_resize = settled();
        app.write_settled_resize();
        assert_ne!(
            std::fs::read_to_string(&path).unwrap(),
            text,
            "outside the mode a settled resize is written"
        );
    }

    /// Ctrl+C in arrange mode keeps the arrangement, as Keep would; only Esc
    /// discards one. The owner's decision of 2026-10-07, pinned so a change to
    /// the exit path cannot quietly reverse it.
    #[test]
    fn ctrl_c_in_arrange_mode_keeps_the_arrangement() {
        let dir = TempDir::new("ctrlc");
        let text = "[layout]\nrows = [\n  { height = 1, panels = [\n    { widget = \"clocks\",   width = 50 },\n    { widget = \"calendar\", width = 50 },\n  ] },\n]\n";
        let path = dir.join("config.toml");
        std::fs::write(&path, text).unwrap();
        let mut app = App::new(toml::from_str(text).unwrap()).unwrap();
        app.write_layout_to(path.clone());

        app.handle_key(key(KeyCode::Char('m')));
        app.handle_key(KeyEvent::new(KeyCode::Right, KeyModifiers::CONTROL));
        let arranged = widths(&app);
        assert_ne!(arranged, [50, 50], "the resize happened");
        app.handle_key(KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL));
        app.finish();

        let written: crate::config::Config =
            toml::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
        let saved: Vec<u16> = written.layout.rows[0]
            .panels
            .iter()
            .map(|p| p.width)
            .collect();
        assert_eq!(
            saved, arranged,
            "the arrangement on screen is the one written"
        );
    }

    /// The write on the way out is the last chance to keep a resize made just
    /// before `q`. When it fails there is no bar left to show it on, so it is
    /// handed back for `main` to print once the terminal is restored.
    #[test]
    fn a_layout_that_cannot_be_written_on_the_way_out_is_handed_back() {
        let dir = TempDir::new("exit");
        // Loads, but `layout_edit` only rewrites the `rows = [ … ]` form.
        let sections = "[[layout.rows]]\nheight = 1\n[[layout.rows.panels]]\nwidget = \"clocks\"\nwidth = 50\n[[layout.rows.panels]]\nwidget = \"calendar\"\nwidth = 50\n";
        let path = dir.join("config.toml");
        std::fs::write(&path, sections).unwrap();
        let mut app = App::new(toml::from_str(sections).unwrap()).unwrap();
        app.write_layout_to(path.clone());

        assert_eq!(app.unsaved_layout(), None, "nothing to report yet");
        app.handle_key(KeyEvent::new(KeyCode::Right, KeyModifiers::CONTROL));
        app.finish();

        let report = app
            .exit_report()
            .expect("the failed write on the way out is not dropped");
        assert!(
            report.starts_with("mirador: the layout could not be saved — ")
                && report.contains("rows = ["),
            "it says what was lost and why: {report}"
        );
        assert_eq!(std::fs::read_to_string(&path).unwrap(), sections);
    }

    /// Keys go to an open shell dialog and nowhere else, and so does the
    /// mouse now. A click under the panel picker used to move focus to the
    /// panel beneath and select a row nobody could see, and the wheel
    /// scrolled lists behind the key map.
    #[test]
    fn an_open_dialog_keeps_the_mouse_from_the_panels_beneath_it() {
        use ratatui::crossterm::event::MouseButton;
        // Its name, how to open it, and how to tell it is still open.
        type Dialog = (&'static str, fn(&mut App), fn(&App) -> bool);

        let (config, _dir) = two_lists("dialog");
        let mut app = App::new(config).unwrap();
        drawn(&mut app, 120, 30);
        let todo = app.slots[1].area.expect("the tasks panel was drawn");
        let click = at(
            MouseEventKind::Down(MouseButton::Left),
            todo.x + 6,
            todo.y + 4,
        );
        let wheel = at(MouseEventKind::ScrollDown, todo.x + 6, todo.y + 4);

        let dialogs: [Dialog; 3] = [
            (
                "panel picker",
                |app| app.handle_key(key(KeyCode::Char('w'))),
                |app| app.picker.is_some(),
            ),
            (
                "theme picker",
                |app| app.handle_key(key(KeyCode::Char('t'))),
                |app| app.theme_picker.is_some(),
            ),
            ("key map", open_key_map, |app| app.keymap_dialog.is_some()),
        ];
        for (name, open, is_open) in dialogs {
            open(&mut app);
            assert!(is_open(&app), "the {name} opened");
            assert!(
                !app.handle_mouse(wheel),
                "the wheel reached the list under the {name}"
            );
            app.handle_mouse(click);
            assert_eq!(app.focus, 0, "a click under the {name} moved focus");
            assert!(is_open(&app), "and the {name} is still open");
            app.handle_key(key(KeyCode::Esc));
            assert!(!is_open(&app), "Esc closed the {name}");
        }

        // The control: with nothing open, the same click lands.
        app.handle_mouse(click);
        assert_eq!(app.focus, 1, "without a dialog the click focuses the list");
    }

    #[test]
    fn nothing_is_written_when_no_config_path_was_given() {
        // The guard that keeps the whole test suite off a real user's config.
        let mut app = App::new(config_with(&["clocks", "todo"])).unwrap();
        app.handle_key(key(KeyCode::Char('w')));
        app.handle_key(key(KeyCode::Char(' ')));
        assert!(app.layout_dirty);
        app.handle_key(key(KeyCode::Esc));
        assert!(
            app.layout_dirty,
            "still pending, because there was nowhere to write it"
        );
        assert_eq!(app.layout_error, None, "and that is not an error");
    }

    #[test]
    fn a_resize_that_changed_nothing_does_not_mark_the_layout_dirty() {
        let mut app = App::new(config_with(&["clocks"])).unwrap();
        // One panel in its row: there is no neighbour to trade with, so the
        // key does nothing and must not queue a config write.
        app.handle_key(KeyEvent::new(KeyCode::Right, KeyModifiers::CONTROL));
        assert!(!app.layout_dirty);
    }

    #[test]
    fn an_empty_layout_is_rejected_at_construction() {
        let config = Config {
            layout: LayoutConfig { rows: Vec::new() },
            ..Config::default()
        };
        assert!(App::new(config).is_err());
    }

    #[test]
    fn every_global_binding_has_a_key_and_an_action() {
        let keymap = crate::keymap::Keymap::default();
        for binding in keymap.bindings() {
            assert!(!binding.key.is_empty());
            assert!(!binding.action.is_empty());
        }
        assert!(
            keymap.bindings().iter().any(|b| b.key == "?" && b.primary),
            "help must always be advertised"
        );
    }

    /// And the event loop itself must offer only `FocusLost` to `mark_seen`.
    /// The two tests above exercise `WatchLog`; this one is about the wiring,
    /// which is where #132 actually lived — the log was always correct.
    #[test]
    fn only_losing_focus_marks_the_log_seen() {
        let source = std::fs::read_to_string(file!()).expect("this file is readable");
        let wiring = source
            .lines()
            .find(|line| line.contains("=> self.watch.mark_seen()"))
            .expect("the focus arm still exists");
        assert!(
            wiring.contains("FocusLost") && !wiring.contains("FocusGained"),
            "gaining focus must not mark the log seen: {wiring:?}"
        );
    }
}