mirador 1.22.0

//! The chronometer: one large local clock, with secondary zones beneath it.
//!
//! The hierarchy is the point. A dashboard answers "what time is it" dozens of
//! times a day and "what time is it in Tokyo" rarely, so the local time is set
//! in block numerals and everything else is a labelled list. Reading the local
//! time should not require focusing on the panel at all.

use jiff::tz::TimeZone;
use ratatui::Frame;
use ratatui::crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
use ratatui::layout::Rect;
use ratatui::style::{Modifier, Style};
use ratatui::text::Span;
use ratatui::widgets::Paragraph;

use crate::config::ClocksConfig;
use crate::frame::{Binding, FRAME_HEIGHT, FRAME_WIDTH};
use crate::glyphs::{self, BigText};
use crate::grid::{Column, Grid, cell_width};
use crate::keymap::{KeysConfig, Meta, PanelKeymap};
use crate::panel::{KeyOutcome, Panel, RenderContext};

/// What the clock panel's keys do. The dialog `a` and `e` open keeps its own
/// keys: it takes typing, and a key moved there could never be typed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ClocksAction {
    Seconds,
    Add,
    Edit,
    MoveUp,
    MoveDown,
    TwelveHour,
    Remove,
    Up,
    Down,
    ShowPath,
}

/// Every key the panel responds to, under `[clocks.keys]`. The border hint, the
/// status bar and the help overlay are derived from it, so a key the panel
/// reads is a key it advertises.
///
/// **The order of the primaries decides which survive a narrow panel**, because
/// [`crate::frame::hint_line`] fills the border in order and stops at the first
/// that will not fit. The clock's border holds about four.
///
/// `Shift+↑↓` is a primary and sits above `d`, which is a deliberate swap made
/// after #109 shipped. Reordering is the thing that issue was filed for — "no
/// way to change order of TZ list via kbd" — and as an `extra` it appeared only
/// in the help overlay, so the border advertised `e edit` and said nothing about
/// the headline capability. The owner went looking for it in a released build
/// and concluded it had not been implemented. A key nobody can find is a key
/// that does not exist.
///
/// `a add` rather than `a add zone` for the same reason: the four together need
/// 42 cells against a budget of `width - 8`, which is 43 on the default layout.
/// The panel is a list of zones and the word buys nothing.
///
/// `d remove` is the one that drops at that width, and it is the right one to
/// lose: `d` deletes in the task, notes and watchlist panels too, so a reader who
/// has used any of them already knows it. `s` and the move keys are idiosyncratic
/// to this panel and guessable from nothing. A wider clock shows all six.
///
/// `h` is the same kind of key as `s`, and it shipped in 1.13.0 as an `extra` —
/// the #109 mistake again, one release later: in `?` and nowhere else, so a wide
/// clock with room to spare still never offered it. It sits above `d` for the
/// reason `Shift+↑↓` does, and `12/24h` rather than `12 / 24-hour` because the
/// border pays for every cell: at the default width the first four still fit
/// exactly and both of these drop, `h` appears from a 55-cell budget, and `d`
/// joins it at 66.
pub const ACTIONS: &[Meta<ClocksAction>] = &[
    Meta {
        action: ClocksAction::Seconds,
        name: "seconds",
        defaults: &[(KeyCode::Char('s'), KeyModifiers::NONE)],
        label: "seconds",
        primary: true,
        joins: false,
        about: "show or hide seconds",
    },
    Meta {
        action: ClocksAction::Add,
        name: "add",
        defaults: &[(KeyCode::Char('a'), KeyModifiers::NONE)],
        label: "add",
        primary: true,
        joins: false,
        about: "add a clock",
    },
    Meta {
        action: ClocksAction::Edit,
        name: "edit",
        defaults: &[(KeyCode::Char('e'), KeyModifiers::NONE)],
        label: "edit",
        primary: true,
        joins: false,
        about: "edit the selected clock",
    },
    Meta {
        action: ClocksAction::MoveUp,
        name: "move_up",
        defaults: &[
            (KeyCode::Up, KeyModifiers::SHIFT),
            (KeyCode::Char('K'), KeyModifiers::NONE),
        ],
        label: "move",
        primary: true,
        joins: false,
        about: "move the selected clock up",
    },
    Meta {
        action: ClocksAction::MoveDown,
        name: "move_down",
        defaults: &[
            (KeyCode::Down, KeyModifiers::SHIFT),
            (KeyCode::Char('J'), KeyModifiers::NONE),
        ],
        label: "move",
        primary: true,
        joins: true,
        about: "move the selected clock down",
    },
    Meta {
        action: ClocksAction::TwelveHour,
        name: "twelve_hour",
        defaults: &[(KeyCode::Char('h'), KeyModifiers::NONE)],
        label: "12/24h",
        primary: true,
        joins: false,
        about: "switch between the 24- and 12-hour clock",
    },
    Meta {
        action: ClocksAction::Remove,
        name: "remove",
        defaults: &[(KeyCode::Char('d'), KeyModifiers::NONE)],
        label: "remove",
        primary: true,
        joins: false,
        about: "remove the selected clock",
    },
    Meta {
        action: ClocksAction::Up,
        name: "up",
        defaults: &[
            (KeyCode::Up, KeyModifiers::NONE),
            (KeyCode::Char('k'), KeyModifiers::NONE),
        ],
        label: "select a clock",
        primary: false,
        joins: false,
        about: "select the clock above",
    },
    Meta {
        action: ClocksAction::Down,
        name: "down",
        defaults: &[
            (KeyCode::Down, KeyModifiers::NONE),
            (KeyCode::Char('j'), KeyModifiers::NONE),
        ],
        label: "select a clock",
        primary: false,
        joins: true,
        about: "select the clock below",
    },
    Meta {
        action: ClocksAction::ShowPath,
        name: "show_path",
        defaults: &[(KeyCode::Char('o'), KeyModifiers::NONE)],
        label: "show file path",
        primary: false,
        joins: false,
        about: "show where the clocks are saved",
    },
];

/// `[clocks.keys]` laid over [`ACTIONS`], or why it cannot be.
pub fn keymap(keys: &KeysConfig) -> Result<PanelKeymap<ClocksAction>, String> {
    PanelKeymap::new("clocks", ACTIONS, keys)
}

/// The keys the panel starts with, until `build` hands it the config's
/// through [`Panel::set_keys`].
fn default_keys() -> PanelKeymap<ClocksAction> {
    PanelKeymap::defaults("clocks", ACTIONS)
}

/// The largest scale the numerals are ever drawn at. Past this a clock stops
/// being readable-from-across-the-room and starts being a poster.
const MAX_CLOCK_SCALE: u16 = 3;

/// Rows a glyph occupies at scale 1.
const GLYPH_ROWS: u16 = 5;

/// Rows the numerals occupy at the largest scale.
const BIG_CLOCK_ROWS: u16 = GLYPH_ROWS * MAX_CLOCK_SCALE;

/// Columns of the secondary zone list.
///
/// `time` holds the formatted time *and* the day marker, so it has to be wide
/// enough for both: `HH:MM:SS +1d` is twelve cells. It was nine, which fits the
/// time and truncates the marker away — and the marker is the half that carries
/// the warning, so the column silently dropped the only part of the row a reader
/// could get wrong. See the note on `day_marker` below.
pub(crate) const COLUMNS: &[Column] = &[
    Column::flex("zone", 1),
    Column::fixed("time", 12),
    Column::fixed("vs local", 9).right().drops_below(30),
];

/// The zone list when its times carry AM or PM.
///
/// `00:00:00 AM +1d` is fifteen cells, and at twelve the marker was cut to `…`
/// — #107 again, reached by the very `time_format` the README suggests. Chosen
/// by what the table's format holds rather than by `twelve_hour`, so someone
/// who wrote `%I:%M:%S %p` themselves gets the room too. `vs local` drops three
/// cells later, which leaves the zone label exactly the room it has in 24-hour.
pub(crate) const COLUMNS_MERIDIEM: &[Column] = &[
    Column::flex("zone", 1),
    Column::fixed("time", 15),
    Column::fixed("vs local", 9).right().drops_below(33),
];

/// A resolved clock: either a working timezone or the error from resolving it.
#[derive(Debug)]
struct Clock {
    label: String,
    zone: Result<TimeZone, String>,
}

/// The world clocks panel.
#[derive(Debug)]
pub struct ClocksPanel {
    /// `[clocks.keys]` over the defaults.
    keys: PanelKeymap<ClocksAction>,
    config: ClocksConfig,
    /// The clock rendered large. Always the first configured zone.
    primary: Clock,
    /// Everything else, rendered as a labelled list.
    secondary: Vec<Clock>,
    show_seconds: bool,
    /// `h`, seeded from `[clocks].twelve_hour`.
    twelve_hour: bool,
    /// The live list, which the panel edits. `[clocks].zones` seeds it once.
    zones: crate::zones::Zones,
    /// Which secondary clock is selected, for `d`. The primary is index 0 and
    /// cannot be selected, because it cannot be removed.
    selected: usize,
    /// The first secondary clock the table shows, when it has more clocks than
    /// rows. Moved by `render` to keep `selected` on screen, as the theme
    /// picker moves its own, because only `render` knows how many rows fit.
    zone_offset: usize,
    /// The `a` or `e` dialog, while it is open.
    asking: Option<crate::prompt::Prompt>,
    /// Which entry `e` opened the dialog on, when it was `e` rather than `a`.
    ///
    /// The two dialogs are the same prompt, and this is what tells them apart
    /// on submit — an add appends, an edit replaces. `None` means `a`.
    editing: Option<usize>,
    status: Option<String>,
    /// The instant the last frame showed, in whichever unit is on screen.
    ///
    /// This panel is why the whole dashboard used to repaint four times a
    /// second: it asked for a 250ms tick and had no `tick` at all, so every one
    /// of them counted as a change. With `show_seconds = false` the visible
    /// content moves once a minute and idle CPU was identical either way.
    last_shown: Option<i64>,
}

impl ClocksPanel {
    /// Resolve every zone once, at construction.
    pub fn new(config: ClocksConfig, path: std::path::PathBuf) -> anyhow::Result<Self> {
        let mut zones = crate::zones::Zones::load(path, &config.zones)?;
        // Persist the seed on a first run, as the watchlist does, so there is
        // a file to edit by hand and `[clocks].zones` is not read again. The
        // load marks a seed to be written and nothing used to write it until
        // a clock was changed from the panel: the config was re-read at every
        // launch until then, and ignored without a word after. A failure is
        // reported the way a failed edit is, and the panel builds regardless.
        zones.save_reporting();
        let mut clocks: Vec<Clock> = zones
            .zones()
            .iter()
            .map(|zone| Clock {
                label: if zone.label.is_empty() {
                    zone.timezone.clone()
                } else {
                    zone.label.clone()
                },
                zone: resolve_zone(&zone.timezone),
            })
            .collect();

        // A panel with no configured zones still shows local time rather than
        // an empty box: the clock is the one thing that should never be blank.
        let primary = if clocks.is_empty() {
            Clock {
                label: "Local".into(),
                zone: Ok(TimeZone::system()),
            }
        } else {
            clocks.remove(0)
        };

        let show_seconds = config.show_seconds;
        let twelve_hour = config.twelve_hour;
        Ok(Self {
            keys: default_keys(),
            config,
            primary,
            secondary: clocks,
            show_seconds,
            twelve_hour,
            zones,
            selected: 1,
            zone_offset: 0,
            asking: None,
            editing: None,
            status: None,
            last_shown: None,
        })
    }

    /// Rebuild the clocks from the zone list after it changes.
    fn reload(&mut self) {
        let mut clocks: Vec<Clock> = self
            .zones
            .zones()
            .iter()
            .map(|zone| Clock {
                label: if zone.label.is_empty() {
                    zone.timezone.clone()
                } else {
                    zone.label.clone()
                },
                zone: resolve_zone(&zone.timezone),
            })
            .collect();
        if !clocks.is_empty() {
            self.primary = clocks.remove(0);
        }
        self.secondary = clocks;
        // The cursor indexes the zone list, whose first entry is the big clock
        // and is not selectable — so the range is `1..=secondary.len()`, and
        // clamping against the *zone* count instead leaves it one past the end
        // after a removal, where `d` silently does nothing.
        self.selected = self.selected.clamp(1, self.secondary.len().max(1));
        // The zone list is what is on screen now, so a failure to write it has
        // to be visible: the clock would silently be gone next launch.
        self.zones.save_reporting();
        // Forces a redraw even when the minute has not changed.
        self.last_shown = None;
    }

    /// Move the selected clock one row up, keeping the cursor on it.
    ///
    /// The cursor follows the clock rather than staying put, because the reader
    /// is moving a *thing*: holding the key should walk one entry up the table,
    /// not shuffle a different entry on every press.
    fn move_selected_up(&mut self) {
        if self.zones.move_up(self.selected) {
            self.selected -= 1;
            self.reload();
        } else {
            // The only way to fail from a valid selection is trying to displace
            // the primary, so this says the same thing `d` does.
            self.status = Some("the big clock stays".into());
        }
    }

    /// Move the selected clock one row down, keeping the cursor on it.
    ///
    /// Silent at the bottom, unlike [`Self::move_selected_up`]: running out of
    /// list is obvious from the screen, where the rule protecting the big clock
    /// is not.
    fn move_selected_down(&mut self) {
        if self.zones.move_down(self.selected) {
            self.selected += 1;
            self.reload();
        }
    }

    /// Deal with a keypress while the add-or-edit prompt is open.
    fn handle_prompt_key(&mut self, key: KeyEvent) {
        let Some(prompt) = self.asking.as_mut() else {
            return;
        };
        match prompt.handle_key(key) {
            crate::prompt::Outcome::Editing => {}
            crate::prompt::Outcome::Cancelled => {
                self.asking = None;
                self.editing = None;
            }
            // Picked from the list: the city the reader recognised becomes
            // the clock's label, which is the whole reason the outcome carries
            // both. Nothing needs validating — the list only holds zones that
            // resolve, and a test holds it to that.
            crate::prompt::Outcome::Chose { label, value } => {
                let applied = match self.editing {
                    Some(index) => self.zones.edit(index, label, value),
                    None => self.zones.add(label, value),
                };
                match applied {
                    Ok(()) => {
                        self.asking = None;
                        self.editing = None;
                        self.reload();
                    }
                    Err(refused) => {
                        if let Some(prompt) = self.asking.as_mut() {
                            prompt.reject(refused.why());
                        }
                    }
                }
            }
            crate::prompt::Outcome::Submitted(answer) => {
                // `Label = Zone` if you want to name it, otherwise just the
                // zone and the city out of it becomes the label.
                let (label, timezone) = match answer.split_once('=') {
                    Some((label, zone)) => (label.trim(), zone.trim()),
                    None => ("", answer.trim()),
                };
                if resolve_zone(timezone).is_err() {
                    prompt.reject(format!("unknown timezone `{timezone}`"));
                    return;
                }
                let applied = match self.editing {
                    Some(index) => self.zones.edit(index, label, timezone),
                    None => self.zones.add(label, timezone),
                };
                if let Err(refused) = applied {
                    prompt.reject(refused.why());
                    return;
                }
                self.asking = None;
                self.editing = None;
                self.reload();
            }
        }
    }
}

/// `format` with its seconds removed, for when `s` has hidden them.
///
/// `s` is bound to "seconds", not "seconds on the big clock", and the panel is
/// one panel — a clock with no seconds sitting above a table that still has
/// them reads as the key not having worked.
///
/// The awkwardness is that `[clocks].time_format` is the user's, and can be
/// anything. Switching to a fixed seconds-less format would silently discard
/// their choice — someone who set `%I:%M:%S %p` would find `s` turning their
/// clock to 24-hour. So the seconds specifier is removed from *their* format,
/// along with the separator immediately before it, and everything else is left
/// alone.
///
/// The format is read through [`specifiers`], the way `strftime` reads it,
/// not searched for the text `%S`: a flag or a width is still the
/// seconds (`%-S`, `%02S`, `%:S`), and `%%S` is a percent sign and a letter.
/// The three whole times that carry seconds become their seconds-less
/// selves as jiff draws them — `%T` and `%X` are `%H:%M:%S` whatever their
/// flags say, so they become `%H:%M` with the hour padded as it was, and
/// `%r` is `%-I:%M:%S %p`. A fraction of a second goes with them — `%f`,
/// `%N` and `%.3f`, and a `.` or `,` written before one — since a fraction
/// left behind draws `09:05.123`, a minute with a decimal fraction of one.
/// `%c` is left alone: it is a whole date, and taking it apart would be
/// guessing at a layout that is jiff's to choose.
///
/// A format with no seconds in it is returned unchanged, which is the right
/// answer rather than a special case: there is nothing for `s` to hide, and the
/// table simply looks the same either way.
fn without_seconds(format: &str) -> String {
    let mut out = String::with_capacity(format.len());
    let mut copied = 0;
    for (range, _, conversion) in specifiers(format) {
        let (replacement, separators): (&str, &[char]) = match conversion {
            'S' => ("", &[':', '.', '-']),
            // A fraction of a second, with or without its own dot.
            'f' | 'N' => ("", &['.', ',']),
            'T' | 'X' => ("%H:%M", &[]),
            'r' => ("%-I:%M %p", &[]),
            _ => continue,
        };
        let mut text = &format[copied..range.start];
        // Take the separator with it, so `%H:%M:%S` does not leave `%H:%M:`.
        // Only from the text between specifiers: the character before a
        // specifier may be the end of another one.
        if let Some(before) = text.chars().next_back()
            && separators.contains(&before)
        {
            text = &text[..text.len() - before.len_utf8()];
        }
        out.push_str(text);
        out.push_str(replacement);
        copied = range.end;
    }
    out.push_str(&format[copied..]);
    out
}

/// One conversion specifier in a `strftime` format: its byte range, what
/// stands between the `%` and the conversion, and the conversion character.
/// `%%` comes back as a specifier whose conversion is `%`, so a literal
/// percent is never mistaken for the start of the next one.
///
/// What stands between is read as jiff reads it — flags, then a width, then
/// colons — so `%-S`, `%02S` and `%:S` are all the seconds. Flags only, as
/// this once read, made `%:S` a conversion called `:` followed by the text
/// `S`, which jiff does not agree with. Likewise `%.3f`, jiff's fraction with
/// a leading dot, is one specifier: an `f` with `.3` between.
fn specifiers(format: &str) -> impl Iterator<Item = (std::ops::Range<usize>, &str, char)> {
    let mut from = 0;
    std::iter::from_fn(move || {
        let at = from + format[from..].find('%')?;
        let spec = &format[at + 1..];
        let flags = spec
            .find(|c: char| !matches!(c, '-' | '_' | '0' | '^' | '#'))
            .unwrap_or(spec.len());
        let width = flags
            + spec[flags..]
                .find(|c: char| !c.is_ascii_digit())
                .unwrap_or(spec.len() - flags);
        let colons = width
            + spec[width..]
                .find(|c: char| c != ':')
                .unwrap_or(spec.len() - width);
        // `%.3f` is one directive in jiff — a dot, a precision, then `f` —
        // and comes back as an `f` with `.3` standing between. A dot not
        // followed by digits and `f` is not, and jiff draws it as text.
        let dotted = spec[colons..].strip_prefix('.').and_then(|rest| {
            let digits = rest
                .find(|c: char| !c.is_ascii_digit())
                .unwrap_or(rest.len());
            rest[digits..]
                .starts_with('f')
                .then_some(colons + 1 + digits)
        });
        let (between, conversion) = match dotted {
            Some(between) => (between, Some('f')),
            None => (colons, spec[colons..].chars().next()),
        };
        let end = at + 1 + between + conversion.map_or(0, char::len_utf8);
        from = end;
        Some((at..end, &spec[..between], conversion.unwrap_or('%')))
    })
}

/// Whether a format prints AM or PM, which is what decides the table's columns.
fn has_meridiem(format: &str) -> bool {
    specifiers(format).any(|(_, _, conversion)| matches!(conversion, 'p' | 'P' | 'r'))
}

/// `format` as a 12-hour format, for when `[clocks].twelve_hour` or `h` has
/// asked for one (#265).
///
/// The same shape as [`without_seconds`], for the same reason: the panel is one
/// panel, so a 12-hour clock above a 24-hour table reads as the setting half
/// working — and `time_format` is the reader's, so it is converted rather than
/// replaced. Each 24-hour hour becomes its 12-hour twin with the reader's
/// padding kept (`%H` to `%I`, `%k` to `%l`, `%T` and `%R` spelled out), and
/// ` %p` goes straight after the last time specifier, so `%H:%M (%Z)` becomes
/// `%I:%M %p (%Z)` rather than ending in the meridiem.
///
/// There is deliberately no conversion the other way. With the setting off the
/// hours are used as written, which is what it did before the setting existed
/// — so a config that asked for `%I:%M:%S %p` keeps the table it asked for.
///
/// Left alone: a format that is already 12-hour, one with no hour in it, and
/// one that already says AM or PM somewhere.
fn twelve_hour_format(format: &str) -> String {
    let mut out = String::with_capacity(format.len() + 3);
    let mut converted = false;
    let mut after_time = None;
    let mut copied = 0;
    for (range, flags, conversion) in specifiers(format) {
        out.push_str(&format[copied..range.start]);
        copied = range.end;
        let twin = match conversion {
            'H' => "I",
            'k' => "l",
            'T' => "I:%M:%S",
            'R' => "I:%M",
            _ => "",
        };
        if twin.is_empty() {
            out.push_str(&format[range]);
        } else {
            out.push('%');
            out.push_str(flags);
            out.push_str(twin);
        }
        converted |= matches!(conversion, 'H' | 'k' | 'T' | 'R');
        if matches!(conversion, 'H' | 'k' | 'T' | 'R' | 'I' | 'l' | 'M' | 'S') {
            after_time = Some(out.len());
        }
    }
    out.push_str(&format[copied..]);
    if converted
        && !has_meridiem(format)
        && let Some(at) = after_time
    {
        out.insert_str(at, " %p");
    }
    out
}

/// Look up an IANA zone, treating `local` as the system zone.
fn resolve_zone(name: &str) -> Result<TimeZone, String> {
    if name.eq_ignore_ascii_case("local") || name.is_empty() {
        return Ok(TimeZone::system());
    }
    TimeZone::get(name).map_err(|_| format!("unknown timezone `{name}`"))
}

/// The offset of `other` relative to the primary zone, as `+9h` or `+5h30`.
///
/// Relative offsets answer the question people actually have about a foreign
/// clock — are they ahead or behind me, and by how much — which a raw UTC
/// offset makes you compute yourself.
fn relative_offset(primary: jiff::tz::Offset, other: jiff::tz::Offset) -> String {
    let delta = i64::from(other.seconds()) - i64::from(primary.seconds());
    if delta == 0 {
        return "same".to_string();
    }
    let sign = if delta < 0 { '-' } else { '+' };
    let abs = delta.abs();
    let (hours, minutes) = (abs / 3600, (abs % 3600) / 60);
    if minutes == 0 {
        format!("{sign}{hours}h")
    } else {
        format!("{sign}{hours}h{minutes:02}")
    }
}

/// Which face the clock wears at this size: the text drawn in numerals, the
/// small seconds beside them if any, and the scale — `None` meaning plain text.
///
/// The ladder is full numerals, then short numerals with small seconds, then
/// plain text. The middle rung fits the short form against what is left after
/// the suffix's cells, not against the whole width; and when that fails the
/// ladder goes to plain text *with* the seconds rather than to numerals
/// without them, because `s` is on and a clock that dropped its seconds by
/// itself reads as the key not having worked.
///
/// A 12-hour clock's `AM` or `PM` sits in the same column as the small seconds,
/// at the top of the numerals where they sit at the foot (#265), so every rung
/// leaves it a space and its cells. Over the seconds it costs nothing more:
/// two letters over two digits.
fn choose_face(
    show_seconds: bool,
    full: &str,
    short: &str,
    seconds: &str,
    meridiem: Option<&str>,
    width: u16,
    rows: u16,
) -> (String, Option<String>, Option<u16>) {
    let fits =
        |text: &str, columns: u16| glyphs::fitting_scale(text, columns, rows, MAX_CLOCK_SCALE);
    let meridiem_cells = meridiem.map_or(0, |m| cell_width(m).saturating_add(1));
    if !show_seconds {
        return (
            short.to_string(),
            None,
            fits(short, width.saturating_sub(meridiem_cells)),
        );
    }
    if let Some(scale) = fits(full, width.saturating_sub(meridiem_cells)) {
        return (full.to_string(), None, Some(scale));
    }
    let suffix_cells = cell_width(seconds).max(meridiem.map_or(0, cell_width)) + 1;
    if let Some(scale) = fits(short, width.saturating_sub(suffix_cells)) {
        return (short.to_string(), Some(seconds.to_string()), Some(scale));
    }
    (full.to_string(), None, None)
}

impl Panel for ClocksPanel {
    fn title(&self) -> String {
        "Clock".to_string()
    }

    fn counter(&self) -> Option<String> {
        let zone = self.primary.zone.as_ref().ok()?;
        Some(
            jiff::Timestamp::now()
                .to_zoned(zone.clone())
                .strftime("%Z")
                .to_string(),
        )
    }

    fn bindings(&self) -> &[Binding] {
        self.keys.bindings()
    }

    fn set_keys(&mut self, config: &crate::config::Config) {
        self.keys = PanelKeymap::or_defaults("clocks", ACTIONS, &config.clocks.keys);
    }

    fn max_width(&self) -> Option<u16> {
        // The numerals stop growing at scale 3, so past the width that
        // `HH:MM:SS` needs there the clock is the same size with more blank
        // around it. Wide enough to matter, though: below this the panel falls
        // back to plain text, which is the one thing this panel exists not to
        // do. It is a taker of surplus far longer than most panels.
        // A 12-hour clock's `AM` beside them is a space and two cells more.
        let meridiem = if self.twelve_hour { 3 } else { 0 };
        Some(glyphs::width_of("00:00:00", MAX_CLOCK_SCALE) + meridiem + FRAME_WIDTH)
    }

    fn max_height(&self) -> Option<u16> {
        // Numerals at their largest, the date beneath, then the zone table:
        // a blank separator, a header, and a row per zone. Past this the panel
        // is centred numerals with a growing void underneath them.
        let date = u16::from(!self.config.date_format.is_empty());
        let zones = if self.secondary.is_empty() {
            0
        } else {
            u16::try_from(self.secondary.len()).unwrap_or(0) + 2
        };
        Some(BIG_CLOCK_ROWS + date + zones + FRAME_HEIGHT)
    }

    fn refresh_interval(&self) -> std::time::Duration {
        // Often enough to land on the boundary promptly, and no more often than
        // the smallest unit on screen needs.
        if self.show_seconds {
            std::time::Duration::from_millis(250)
        } else {
            std::time::Duration::from_secs(1)
        }
    }

    fn tick(&mut self) -> bool {
        // Every zone's minute turns on the same instant — UTC offsets are whole
        // minutes, including the 30- and 45-minute ones — so one comparison
        // covers the big clock, the zone list and the date line together.
        let second = jiff::Timestamp::now().as_second();
        let unit = if self.show_seconds {
            second
        } else {
            second / 60
        };
        let moved = self.last_shown != Some(unit);
        self.last_shown = Some(unit);
        moved
    }

    fn overlay(&self) -> Option<&crate::prompt::Prompt> {
        self.asking.as_ref()
    }

    fn alert(&self) -> Option<crate::panel::Alert> {
        self.zones.last_error.as_ref().map(|why| {
            crate::panel::Alert::failing(format!("The world clocks could not be saved — {why}"))
        })
    }

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

    fn handle_key(&mut self, key: KeyEvent) -> KeyOutcome {
        if self.asking.is_some() {
            self.handle_prompt_key(key);
            return KeyOutcome::Consumed;
        }

        self.status = None;
        // The primary clock is index 0 and is not selectable, so the cursor
        // lives in 1..=secondary.len().
        let last = self.secondary.len();
        let Some(action) = self.keys.action(key) else {
            return KeyOutcome::Ignored;
        };
        match action {
            ClocksAction::Seconds => self.show_seconds = !self.show_seconds,
            ClocksAction::TwelveHour => {
                self.twelve_hour = !self.twelve_hour;
                // The instant on screen has not moved, so `tick` would not
                // see a change until it does — a minute, with seconds hidden.
                self.last_shown = None;
            }
            ClocksAction::Add => {
                self.editing = None;
                self.asking = Some(crate::prompt::Prompt::new(
                    "ADD A CLOCK",
                    "↑↓ choose · Enter adds · Esc cancels",
                    "",
                    crate::prompt::Completion::Places(crate::zones::PLACES),
                ));
            }
            ClocksAction::Edit => {
                // Pre-filled with what the entry already says, in the same
                // `Label = Zone` the add dialog accepts. Relabelling is the
                // common case, so the text you want to change is already there
                // rather than something you retype from scratch.
                if let Some(zone) = self.zones.zones().get(self.selected) {
                    self.editing = Some(self.selected);
                    self.asking = Some(crate::prompt::Prompt::new(
                        "EDIT THIS CLOCK",
                        "`Label = Zone` · Enter saves · Esc cancels",
                        &format!("{} = {}", zone.label, zone.timezone),
                        crate::prompt::Completion::Places(crate::zones::PLACES),
                    ));
                }
            }
            ClocksAction::ShowPath => {
                self.status = Some(self.zones.path().display().to_string());
            }
            // Shift moves the clock rather than the cursor, which is the same
            // shape as `Ctrl+←→↑↓` resizing a panel rather than moving focus.
            // `J`/`K` do it too, because this panel already offers arrows and
            // `j`/`k` as equals for the selection and it would be strange for
            // only one of the pair to gain the modifier.
            ClocksAction::MoveUp => self.move_selected_up(),
            ClocksAction::MoveDown => self.move_selected_down(),
            ClocksAction::Remove => {
                if self.zones.remove(self.selected) {
                    self.reload();
                } else {
                    self.status = Some("the big clock stays".into());
                }
            }
            ClocksAction::Down => {
                self.selected = self.selected.saturating_add(1).min(last.max(1));
            }
            ClocksAction::Up => {
                self.selected = self.selected.saturating_sub(1).max(1);
            }
        }
        KeyOutcome::Consumed
    }

    fn remember(&self, state: &mut crate::state::UiState) {
        state.clocks_show_seconds = Some(self.show_seconds);
        state.clocks_twelve_hour = Some(self.twelve_hour);
    }

    #[allow(clippy::too_many_lines)] // One panel, drawn top to bottom; the
    // sub-steps share so much local state that splitting them would mean
    // threading half a dozen parameters through private helpers.
    fn render(&mut self, frame: &mut Frame, area: Rect, ctx: RenderContext<'_>) {
        let theme = ctx.theme;
        if area.width == 0 || area.height == 0 {
            return;
        }

        let now = jiff::Timestamp::now();
        let primary_zone = match &self.primary.zone {
            Ok(zone) => zone.clone(),
            Err(message) => {
                frame.render_widget(
                    Paragraph::new(Span::styled(
                        message.clone(),
                        Style::default().fg(theme.error),
                    )),
                    area,
                );
                return;
            }
        };
        let local = now.to_zoned(primary_zone);

        // Seconds are wanted, but "HH:MM:SS" at block size needs about 62
        // columns and the clock panel rarely has that. So: try the full string
        // large, and if it will not fit, set HH:MM large with the seconds
        // riding small at the baseline. The hour and minute stay readable from
        // across the room either way, which is the whole point of the panel.
        //
        // A 12-hour hour is space-padded, the way one is read, and the blank
        // still takes a cell — an unknown glyph draws nothing and keeps its
        // width — so the numerals do not step sideways when 9:59 turns 10:00.
        let hour = if self.twelve_hour { "%l" } else { "%H" };
        let full = local.strftime(&format!("{hour}:%M:%S")).to_string();
        let short = local.strftime(&format!("{hour}:%M")).to_string();
        let seconds = local.strftime("%S").to_string();
        let meridiem = self.twelve_hour.then(|| local.strftime("%p").to_string());

        // Budget the panel before sizing the clock. The zone table is the
        // reason this panel exists beyond telling the time, so it gets its
        // rows first and the numerals take what is left. Sizing the clock
        // first is what pushed the zones off the bottom.
        let date_rows = u16::from(!self.config.date_format.is_empty());
        let zone_rows = if self.secondary.is_empty() {
            0
        } else {
            // One header, one row per zone, one blank line to separate them
            // from the numerals.
            u16::try_from(self.secondary.len()).unwrap_or(0) + 2
        };
        let clock_budget = area.height.saturating_sub(date_rows + zone_rows).max(1);
        let face = |rows: u16| {
            choose_face(
                self.show_seconds,
                &full,
                &short,
                &seconds,
                meridiem.as_deref(),
                area.width,
                rows,
            )
        };
        // Width and height together, inside `choose_face`: filtering a
        // width-only answer by height rejects instead of stepping down a scale,
        // and a *shorter* string earns a bigger one. That is how hiding the
        // seconds used to make the clock smaller rather than larger.
        // Small seconds ride beside the numerals and take cells of their own —
        // a space and two digits — so the short form is fitted against what is
        // left *after* them. It used to be fitted alone, and the pair was then
        // centred as a unit: at 40 columns the numerals fitted, the suffix did
        // not, and the terminal cut `26` down to `2`, a fragment of a value.
        // Found by the silent-clip sweep in `widgets`, the day it was written.
        // When even the pair does not fit, the ladder steps straight down to
        // plain text with the seconds intact rather than to numerals without
        // them: `s` is on, and a clock that dropped its seconds on its own
        // would read as the key not having worked (#106, the other way round).
        let (mut time_text, mut small_seconds, mut scale) = face(clock_budget);

        // A notice — `o`'s path, `the big clock stays`, a failed save — has
        // the last row to itself. It used to be painted over whatever had
        // been drawn there: with no table that was the date, and the end of
        // the date showed through beside it.
        //
        // The row comes from slack: the blank line above the table, which
        // goes first when room is short, or rows the numerals leave unused.
        // Only when there is neither does the clock give it up. Taking it
        // from the clock's budget every time cost the numerals a whole scale
        // step for a one-line message — fifteen rows to ten at the panel's own
        // largest size, until the next key, or for good after a failed save.
        //
        // A failed write to the zone file has to be seen: the clock is on
        // screen now and would silently be gone at the next launch.
        let notice = self
            .status
            .as_ref()
            .or(self.zones.last_error.as_ref())
            .filter(|_| area.height >= 2)
            .cloned();
        if notice.is_some() {
            let face_rows = scale.map_or(1, |scale| GLYPH_ROWS * scale);
            let table_rows = zone_rows.saturating_sub(1);
            if face_rows
                .saturating_add(date_rows)
                .saturating_add(table_rows)
                >= area.height
            {
                (time_text, small_seconds, scale) = face(clock_budget.saturating_sub(1).max(1));
            }
        }
        let bottom = area.y + area.height - u16::from(notice.is_some());
        let mut cursor = area.y;

        if let Some(scale) = scale {
            let big = BigText::new(&time_text, scale);
            // Reserve room for the small seconds and the meridiem, which share
            // a column, so the whole stays centred as a unit rather than the
            // big block jumping when seconds appear.
            let suffix = small_seconds
                .iter()
                .chain(&meridiem)
                .map(|text| cell_width(text))
                .max()
                .map_or(0, |cells| cells.saturating_add(1));
            let total = big.width + suffix;
            let x = area.x + (area.width.saturating_sub(total)) / 2;

            for (index, row) in big.rows.iter().enumerate() {
                let y = area.y + u16::try_from(index).unwrap_or(0);
                if y >= bottom {
                    break;
                }
                frame.render_widget(
                    Paragraph::new(Span::styled(row.clone(), Style::default().fg(theme.accent))),
                    Rect::new(x, y, big.width.min(area.width), 1),
                );
            }

            if let Some(seconds) = &small_seconds {
                // Sat on the baseline of the big digits, dimmer, so it reads as
                // a subscript rather than as another number.
                let y = area.y + big.height.saturating_sub(1);
                let sx = x + big.width + 1;
                // The fit above guarantees the room; the clamp is what makes a
                // future mistake there show as missing seconds rather than as
                // a cut one, which is the failure a reader cannot see.
                let room = (area.x + area.width).saturating_sub(sx);
                if room >= suffix.saturating_sub(1) && y < bottom {
                    frame.render_widget(
                        Paragraph::new(Span::styled(
                            seconds.clone(),
                            Style::default().fg(theme.muted),
                        )),
                        Rect::new(sx, y, suffix.saturating_sub(1).min(room), 1),
                    );
                }
            }

            if let Some(meridiem) = &meridiem {
                // At the top of the numerals where the seconds sit at the foot,
                // as #265 asked, so the two read as notes on one time. The
                // utility face's weight, the seconds' dimness, and the same
                // clamp as theirs: whole or not at all.
                let sx = x + big.width + 1;
                let room = (area.x + area.width).saturating_sub(sx);
                let cells = suffix.saturating_sub(1);
                if room >= cells {
                    frame.render_widget(
                        Paragraph::new(Span::styled(
                            meridiem.clone(),
                            Style::default()
                                .fg(theme.muted)
                                .add_modifier(Modifier::BOLD),
                        )),
                        Rect::new(sx, area.y, cells, 1),
                    );
                }
            }
            cursor += big.height;
        } else {
            // Too small for block digits at any scale: fall back to plain text
            // rather than clipping — and truncate the plain text too, since a
            // rect the width of the panel cuts `15:54:33` to `15:54:3` at seven
            // columns, which is a different time.
            let time = if self.show_seconds { full } else { short };
            let text = match &meridiem {
                Some(meridiem) => format!("{} {meridiem}", time.trim_start()),
                None => time,
            };
            let text = crate::grid::truncate(&text, usize::from(area.width));
            frame.render_widget(
                Paragraph::new(Span::styled(
                    text,
                    Style::default()
                        .fg(theme.accent)
                        .add_modifier(Modifier::BOLD),
                )),
                Rect::new(area.x, cursor, area.width, 1),
            );
            cursor += 1;
        }

        // The date sits directly under the numerals in the utility face, so
        // the two read as one object rather than as two separate facts.
        //
        // Truncated here rather than left to the rect, and measured in cells
        // rather than in `chars()`. Both halves were wrong and the pair of them
        // produced the one silent cut on the dashboard: a `Paragraph` in a rect
        // narrower than its text is clipped by the terminal, which cannot tell
        // a value from a fragment, so `WEDNESDAY 09 SEPTEMBER` came out at 80
        // columns as `WEDNESDAY 09 SEPT` — a complete-looking abbreviated month
        // that is not what the day is called. Every other cut on the same
        // screen says `…`; this one did not. `date_format` is the reader's, so
        // it can hold any text at all, which is why `chars()` was the second
        // fault rather than a theoretical one.
        if cursor < bottom && !self.config.date_format.is_empty() {
            let date = glyphs::utility(&local.strftime(&self.config.date_format).to_string());
            let date = crate::grid::truncate(&date, usize::from(area.width));
            // Not `cell_width`, which saturates: `truncate` counts a control
            // character as no cells and `display_width` as one, so a format
            // padded with enough of them measures past a `u16` even here, and
            // a width saturated to the maximum would draw it flush left. One
            // that does not fit a `u16` is drawn nowhere, as it always was.
            let width = u16::try_from(crate::grid::display_width(&date)).unwrap_or(0);
            let x = area.x + (area.width.saturating_sub(width)) / 2;
            frame.render_widget(
                Paragraph::new(Span::styled(
                    date,
                    Style::default()
                        .fg(theme.label)
                        .add_modifier(Modifier::BOLD),
                )),
                Rect::new(x, cursor, width.min(area.width), 1),
            );
            cursor += 1;
        }

        // The notice's row, cleared first: the table ends above it, and it was
        // once painted over the last clock in the table, and with no table
        // never reached at all — `d` on the big clock said why in a field
        // nobody could see.
        if let Some(message) = &notice {
            let row = Rect::new(area.x, bottom, area.width, 1);
            frame.render_widget(ratatui::widgets::Clear, row);
            frame.render_widget(
                Paragraph::new(Span::styled(
                    crate::grid::truncate(message, usize::from(area.width)),
                    Style::default().fg(theme.error),
                )),
                row,
            );
        }

        if self.secondary.is_empty() || cursor >= bottom {
            return;
        }

        // A blank line separates the numerals from the table, but only when
        // there is room for the whole table underneath it.
        let needed = u16::try_from(self.secondary.len()).unwrap_or(u16::MAX);
        if bottom.saturating_sub(cursor) > needed.saturating_add(1) {
            cursor += 1;
        }
        let remaining = bottom.saturating_sub(cursor);
        // A header needs a clock under it to say anything.
        if remaining < 2 {
            return;
        }

        // More clocks than rows: the table shows a window of them that follows
        // the cursor, so the clock `d` would remove is always one on screen.
        // Every clock used to go into the paragraph and the terminal dropped
        // the ones past the bottom, with the cursor walking on through them.
        let rows = usize::from(remaining - 1);
        let at = self.selected.saturating_sub(1);
        if at < self.zone_offset {
            self.zone_offset = at;
        } else if at >= self.zone_offset + rows {
            self.zone_offset = at + 1 - rows;
        }
        self.zone_offset = self
            .zone_offset
            .min(self.secondary.len().saturating_sub(rows));

        // Once per draw rather than once per row: `s` and `h` govern the whole
        // panel, not just the numerals above this table. Hours first, since
        // `%T` spelled out is what lets `without_seconds` find the seconds.
        let time_format = if self.twelve_hour {
            twelve_hour_format(&self.config.time_format)
        } else {
            self.config.time_format.clone()
        };
        let time_format = if self.show_seconds {
            time_format
        } else {
            without_seconds(&time_format)
        };
        let columns = if has_meridiem(&time_format) {
            COLUMNS_MERIDIEM
        } else {
            COLUMNS
        };
        let grid = Grid::new(columns, area.width);
        let mut lines = vec![grid.header(theme)];

        for (index, clock) in self
            .secondary
            .iter()
            .enumerate()
            .skip(self.zone_offset)
            .take(rows)
        {
            // The cursor is over the zone list, whose first entry is zone 1.
            let here = ctx.focused && index + 1 == self.selected;
            // Marked by reversing the label rather than by a gutter arrow: the
            // table has three columns and no room to spare, and reversing is
            // what the picker already uses for the same idea.
            let label = if here {
                Style::default()
                    .fg(theme.text)
                    .add_modifier(Modifier::REVERSED)
            } else {
                Style::default().fg(theme.text)
            };
            match &clock.zone {
                Ok(zone) => {
                    let zoned = now.to_zoned(zone.clone());
                    // A foreign clock on a different calendar day is the thing
                    // people actually get wrong, so it is called out.
                    let day_marker = match zoned.date().cmp(&local.date()) {
                        std::cmp::Ordering::Greater => " +1d",
                        std::cmp::Ordering::Less => " -1d",
                        std::cmp::Ordering::Equal => "",
                    };
                    let offset = if self.config.show_offset {
                        relative_offset(local.offset(), zoned.offset())
                    } else {
                        String::new()
                    };

                    lines.push(grid.row(&[
                        Span::styled(clock.label.clone(), label),
                        Span::styled(
                            format!("{}{day_marker}", zoned.strftime(&time_format)),
                            Style::default().fg(if day_marker.is_empty() {
                                theme.text
                            } else {
                                theme.warning
                            }),
                        ),
                        Span::styled(offset, Style::default().fg(theme.muted)),
                    ]));
                }
                Err(message) => lines.push(grid.row(&[
                    Span::styled(clock.label.clone(), label),
                    Span::styled(message.clone(), Style::default().fg(theme.error)),
                ])),
            }
        }

        frame.render_widget(
            Paragraph::new(lines),
            Rect::new(area.x, cursor, area.width, remaining),
        );
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::store::testing::TempDir;

    /// Every key in the map works and is advertised; see
    /// [`crate::keymap::assert_every_key_works`].
    #[test]
    fn every_key_in_the_map_works_and_is_advertised() {
        crate::keymap::assert_every_key_works(&default_keys(), |event| {
            let (mut p, _g) = panel_from_named("keymap", ClocksConfig::default());
            p.handle_key(event)
        });
    }
    use crate::config::ClockZone;
    use jiff::tz::Offset;

    /// Reported as #103: pressing `s` to hide the seconds made the time render
    /// in small text instead of block numerals.
    ///
    /// The cause was in `glyphs::fitting_scale`, which took only a width; the
    /// caller then *filtered* that answer by height, which rejects instead of
    /// stepping down a scale. `HH:MM` is narrower than `HH:MM:SS`, so it earned
    /// a bigger scale — and a bigger scale is `CELL_H` rows taller, so at some
    /// panel sizes it no longer fit the rows and fell all the way back to plain
    /// text. Hiding a character made the clock smaller.
    ///
    /// Swept rather than pinned at one size, because the original was found at
    /// 68x11 and nothing would have led anyone to try that size on purpose.
    #[test]
    fn hiding_the_seconds_never_shrinks_the_clock() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let config = crate::config::Config::default();
        let gradients = config.theme.gradients();

        let draws_block_numerals = |panel: &mut ClocksPanel, w: u16, h: u16| -> bool {
            let mut terminal = Terminal::new(TestBackend::new(w, h)).unwrap();
            terminal
                .draw(|frame| {
                    panel.render(
                        frame,
                        frame.area(),
                        RenderContext {
                            theme: &config.theme,
                            gradients: &gradients,
                            focused: true,
                            watch: &crate::watch::WatchLog::default(),
                        },
                    );
                })
                .unwrap();
            let buffer = terminal.backend().buffer().clone();
            (0..h).any(|y| {
                (0..w).any(|x| {
                    buffer
                        .cell((x, y))
                        .is_some_and(|cell| cell.symbol() == "\u{2588}")
                })
            })
        };

        // Built once and drawn at every size. Building a panel saves its
        // seeded zone list, and three thousand saves to disk made this one test
        // take fifteen seconds.
        let (mut with, _a) = panel_from_named("secs-on", ClocksConfig::default());
        with.show_seconds = true;
        let (mut without, _b) = panel_from_named("secs-off", ClocksConfig::default());
        without.show_seconds = false;

        let mut shrank = Vec::new();
        for width in 20..104u16 {
            for height in 6..24u16 {
                if draws_block_numerals(&mut with, width, height)
                    && !draws_block_numerals(&mut without, width, height)
                {
                    shrank.push((width, height));
                }
            }
        }

        assert!(
            shrank.is_empty(),
            "at {} panel sizes, hiding the seconds dropped the clock to plain \
             text; first few: {:?}",
            shrank.len(),
            &shrank[..shrank.len().min(6)]
        );
    }

    /// #106: `s` is bound to "seconds", and the panel is one panel — a clock
    /// with no seconds above a table that still has them reads as the key not
    /// having worked. The user's own `time_format` has to survive it, so the
    /// seconds specifier is removed from *their* format rather than swapped for
    /// a fixed one.
    #[test]
    fn hiding_the_seconds_takes_them_out_of_the_zone_table_too() {
        assert_eq!(without_seconds("%H:%M:%S"), "%H:%M");
        // A 12-hour format keeps being a 12-hour format.
        assert_eq!(without_seconds("%I:%M:%S %p"), "%I:%M %p");
        // `%T` is a whole time, so it becomes the seconds-less whole time.
        assert_eq!(without_seconds("%T"), "%H:%M");
        // Nothing to remove is not a special case.
        assert_eq!(without_seconds("%H:%M"), "%H:%M");
        assert_eq!(without_seconds(""), "");
        // The separator goes with it, rather than leaving a trailing colon.
        assert!(!without_seconds("%H:%M:%S").ends_with(':'));
        assert!(!without_seconds("%H.%M.%S").ends_with('.'));
    }

    /// The seconds were found by searching the format for the text
    /// `%S`, which is not how `strftime` reads it. A flag or a width between
    /// the `%` and the `S` hid the seconds from the search, so `%H:%M:%-S`
    /// kept them with `s` off — `16:47:9` under a clock without them, #106
    /// again — and a literal `%%S` was taken for one, leaving a dangling
    /// `%` that drew as `16:47 %`. Every case here is checked against what
    /// jiff actually draws, not only against the format text.
    #[test]
    fn hiding_the_seconds_reads_the_format_the_way_strftime_does() {
        // A flag or a width is still the seconds.
        assert_eq!(without_seconds("%H:%M:%-S"), "%H:%M");
        assert_eq!(without_seconds("%H:%M:%_S"), "%H:%M");
        assert_eq!(without_seconds("%H:%M:%02S"), "%H:%M");
        // A literal percent is text, and `%%S` is not the seconds.
        assert_eq!(without_seconds("%H:%M %%S"), "%H:%M %%S");

        let at = jiff::civil::date(2026, 10, 8)
            .at(9, 5, 7, 123_456_789)
            .to_zoned(TimeZone::UTC)
            .expect("a real instant");
        let drawn = |format: &str| at.strftime(format).to_string();
        // jiff reads colons before any conversion, so `%:S` is the seconds
        // and has to stay on the list the search used to carry.
        assert_eq!(drawn("%H:%M:%:S"), "09:05:07");
        // And it reads `%.3f` as one directive — the dot, a precision, the
        // `f` — not as a conversion called `.` followed by the text `3f`.
        assert_eq!(drawn("%H:%M:%S%.3f"), "09:05:07.123");
        let one: Vec<_> = specifiers("%.3f").collect();
        assert_eq!(one, [(0..4, ".3", 'f')], "{one:?}");
        for (format, expected) in [
            ("%H:%M:%S", "09:05"),
            ("%H:%M:%-S", "09:05"),
            ("%H:%M:%:S", "09:05"),
            // `%T` is drawn padded whatever its flags say — `%-T` reads
            // `09:05:07` — so the hour it gives way to stays padded.
            ("%-T", "09:05"),
            // The two composites that carry seconds: `%X` is jiff's
            // `%H:%M:%S` and `%r` its `%-I:%M:%S %p`.
            ("%X", "09:05"),
            ("%r", "9:05 AM"),
            ("%I:%M:%S %p", "09:05 AM"),
            ("%H:%M %%S", "09:05 %S"),
            // A fraction of a second is the seconds too. Left behind, it
            // drew `09:05.123` — a minute and a decimal fraction of one,
            // under a big clock that had dropped its seconds.
            ("%H:%M:%S%.3f", "09:05"),
            ("%H:%M:%S.%N", "09:05"),
            ("%H:%M:%S,%3f", "09:05"),
            ("%T%.f", "09:05"),
        ] {
            assert_eq!(drawn(&without_seconds(format)), expected, "{format}");
        }
        // `%r` says AM or PM, so its table is the meridiem one with `s` on
        // as well as off. Uncounted, it took the 12-cell time column with
        // the seconds — `12:05:07 PM +1d` is fifteen, #107's cut — and
        // switched column sets when `s` turned them off.
        assert!(has_meridiem("%r"));
        assert!(has_meridiem(&without_seconds("%r")));
    }

    /// The same fix wired in, checked the way the #106 test checks it: a panel
    /// whose `time_format` carries a flagged seconds specifier, drawn with
    /// `s` on and off.
    #[test]
    fn a_flagged_seconds_specifier_leaves_the_zone_table_with_s() {
        let config = ClocksConfig {
            time_format: "%H:%M:%-S".into(),
            ..ClocksConfig::default()
        };
        let (mut panel, _guard) = panel_from_named("flagged-seconds", config);
        assert!(!panel.secondary.is_empty(), "a zone table to look at");
        let zone_rows_with_seconds = |panel: &mut ClocksPanel| -> Vec<String> {
            let buffer = crate::widgets::testing::render_in(
                panel,
                60,
                20,
                &crate::theme::Theme::default(),
                true,
            );
            crate::widgets::testing::rows(&buffer)
                .into_iter()
                .filter(|row| row.matches(':').count() >= 2 && !row.contains('\u{2588}'))
                .collect()
        };

        panel.show_seconds = true;
        assert!(
            !zone_rows_with_seconds(&mut panel).is_empty(),
            "with seconds on, the zone rows carry them"
        );
        panel.show_seconds = false;
        let still = zone_rows_with_seconds(&mut panel);
        assert!(still.is_empty(), "{still:#?}");
    }

    /// The wiring, not just the helper. Breaking the call site while leaving
    /// `without_seconds` correct passed every other test here — the helper can
    /// be right and simply not be called.
    #[test]
    fn the_rendered_zone_table_loses_its_seconds_when_s_does() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let config = crate::config::Config::default();
        let gradients = config.theme.gradients();

        let screen = |panel: &mut ClocksPanel| -> String {
            let mut terminal = Terminal::new(TestBackend::new(60, 20)).unwrap();
            terminal
                .draw(|frame| {
                    panel.render(
                        frame,
                        frame.area(),
                        RenderContext {
                            theme: &config.theme,
                            gradients: &gradients,
                            focused: true,
                            watch: &crate::watch::WatchLog::default(),
                        },
                    );
                })
                .unwrap();
            let buffer = terminal.backend().buffer().clone();
            (0..20)
                .map(|y| {
                    (0..60)
                        .filter_map(|x| buffer.cell((x, y)).map(|c| c.symbol().to_string()))
                        .collect::<String>()
                })
                .collect::<Vec<_>>()
                .join("\n")
        };

        // A zone table needs at least one secondary clock to exist at all.
        let (mut panel, _guard) = panel_from_named("seconds-wiring", ClocksConfig::default());
        assert!(
            !panel.secondary.is_empty(),
            "the default config seeds secondary zones"
        );

        // `HH:MM:SS` in the table: two colons on a zone row.
        panel.show_seconds = true;
        let with = screen(&mut panel);
        let rows_with_two_colons = with
            .lines()
            .filter(|line| line.matches(':').count() >= 2)
            .count();
        assert!(
            rows_with_two_colons > 0,
            "with seconds on, some zone row shows HH:MM:SS\n{with}"
        );

        panel.show_seconds = false;
        let without = screen(&mut panel);
        let still_two = without
            .lines()
            .filter(|line| {
                // Ignore the big numerals, which are block glyphs, and the
                // footer; a zone row is one with a zone label on it.
                line.matches(':').count() >= 2 && !line.contains('\u{2588}')
            })
            .count();
        assert_eq!(
            still_two, 0,
            "with seconds off, no zone row should still carry them\n{without}"
        );
    }

    /// #107: the column holds the time *and* the day marker, and the marker is
    /// the half that carries the warning. At nine cells `02:43:48 +1d` was
    /// truncated to `02:43:48…`, so the one part a reader could get wrong was
    /// the part that never showed.
    #[test]
    fn the_day_marker_fits_beside_the_time_it_belongs_to() {
        let time = COLUMNS
            .iter()
            .find(|column| column.label == "time")
            .expect("there is a time column");
        let crate::grid::Width::Fixed(width) = time.width else {
            panic!("the time column is fixed width");
        };
        let meridiem = COLUMNS_MERIDIEM
            .iter()
            .find(|column| column.label == "time")
            .expect("there is a time column");
        let crate::grid::Width::Fixed(meridiem_width) = meridiem.width else {
            panic!("the time column is fixed width");
        };
        for (time, width) in [("00:00:00", width), ("00:00:00 AM", meridiem_width)] {
            for marker in ["", " +1d", " -1d"] {
                let widest = format!("{time}{marker}");
                assert!(
                    crate::grid::display_width(&widest) <= usize::from(width),
                    "`{widest}` needs {} cells and the column is {width}",
                    crate::grid::display_width(&widest)
                );
            }
        }
    }

    /// The date line was the one thing on the dashboard that was cut without
    /// saying so. It was handed to a `Paragraph` in a rect narrower than the
    /// text, so the *terminal* did the cutting, and a terminal cannot tell a
    /// value from a fragment: `WEDNESDAY 09 SEPTEMBER` arrived at 80 columns as
    /// `WEDNESDAY 09 SEPT`, which reads as a whole abbreviated month.
    ///
    /// Two properties, because the old code got two things wrong. Anything cut
    /// has to say `…`, and nothing may be drawn wider than the space it was
    /// given — which the old `chars().count()` could not know, since
    /// `date_format` is the reader's and may hold any text at all.
    #[test]
    fn the_date_line_says_when_it_has_been_cut() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let config = crate::config::Config::default();
        let gradients = config.theme.gradients();

        // Literal text passes through `strftime` untouched, so the whole line
        // is known without depending on what today happens to be. The second
        // is double-width throughout: eight cells to six `chars()`, which is
        // the gap the old measurement fell into.
        for format in [
            "MIDWEEK LONG DATE LINE",
            "\u{6c34}\u{66dc}\u{65e5} \u{4e5d}\u{6708}",
        ] {
            let full = crate::glyphs::utility(format);
            let mut ever_cut = false;

            for width in 4..48u16 {
                let (mut panel, _guard) = panel_from_named(
                    "date-cut",
                    ClocksConfig {
                        date_format: format.to_string(),
                        ..ClocksConfig::default()
                    },
                );
                let mut terminal = Terminal::new(TestBackend::new(width, 20)).unwrap();
                terminal
                    .draw(|frame| {
                        panel.render(
                            frame,
                            frame.area(),
                            RenderContext {
                                theme: &config.theme,
                                gradients: &gradients,
                                focused: true,
                                watch: &crate::watch::WatchLog::default(),
                            },
                        );
                    })
                    .unwrap();
                // Read the buffer rather than `TestBackend`'s `Display`, which
                // wraps every row in quotation marks — two cells that are not
                // on anybody's screen, and enough to fail a width assertion
                // that is doing its job.
                let buffer = terminal.backend().buffer().clone();
                let rows: Vec<String> = (0..buffer.area.height)
                    .map(|y| {
                        // Walk by each glyph's measured width, the way
                        // `link::linkify` has to: the cell a double-width glyph
                        // covers holds a space, indistinguishable from a real
                        // one, so reading every cell turns `水曜` into `水 曜 `
                        // and inflates the row by a cell per wide glyph.
                        let mut row = String::new();
                        let mut x = 0u16;
                        while x < buffer.area.width {
                            let Some(cell) = buffer.cell((x, y)) else {
                                break;
                            };
                            let symbol = cell.symbol();
                            row.push_str(symbol);
                            x += cell_width(symbol).max(1);
                        }
                        row
                    })
                    .collect();

                // The date row is the one carrying the *first* character of the
                // format — one character, not two, because a cut short enough
                // to lose the second is exactly the case being tested and a
                // two-character head would quietly skip it. The zone rows are
                // excluded by their colons, and the numerals above are block
                // glyphs. A width too narrow to hold even the first character
                // draws no date at all, which is a row not drawn rather than a
                // row drawn wrong.
                let head: String = full.chars().take(1).collect();
                let Some(row) = rows
                    .iter()
                    .find(|line| line.contains(&head) && !line.contains(':'))
                else {
                    continue;
                };
                let drawn = row.trim();

                assert!(
                    crate::grid::display_width(drawn) <= usize::from(width),
                    "the date overflowed {width} cells: {drawn:?}"
                );
                if drawn == full {
                    continue;
                }
                ever_cut = true;
                assert!(
                    drawn.ends_with('\u{2026}'),
                    "the date was cut at {width} without saying so: {drawn:?}"
                );
            }

            assert!(
                ever_cut,
                "no width in the sweep actually cut `{full}`, so this proves nothing"
            );
        }
    }

    /// A date that measures wider than a `u16` is not drawn, as it was not
    /// before `cell_width` took over the measuring. It can still get there
    /// after `truncate`, because the two measure differently: `truncate`
    /// counts a control character as no cells and `display_width` as one, so
    /// a `date_format` padded with seventy thousand of them comes back whole.
    /// Saturating that to `u16::MAX` drew the date flush left in a panel that
    /// centres it; the width it was measured at is not one to place it by.
    #[test]
    fn a_date_measured_wider_than_a_u16_is_not_drawn() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let config = crate::config::Config::default();
        let gradients = config.theme.gradients();
        let format = format!("MIDWEEK{}", "\u{1}".repeat(70_000));
        assert!(
            crate::grid::display_width(&crate::grid::truncate(&format, 40)) > 65_535,
            "the format no longer survives `truncate` too wide for a u16, so this proves nothing"
        );

        let (mut panel, _guard) = panel_from_named(
            "date-u16",
            ClocksConfig {
                date_format: format,
                ..ClocksConfig::default()
            },
        );
        let mut terminal = Terminal::new(TestBackend::new(40, 20)).unwrap();
        terminal
            .draw(|frame| {
                panel.render(
                    frame,
                    frame.area(),
                    RenderContext {
                        theme: &config.theme,
                        gradients: &gradients,
                        focused: true,
                        watch: &crate::watch::WatchLog::default(),
                    },
                );
            })
            .unwrap();
        let buffer = terminal.backend().buffer().clone();
        let rows: Vec<String> = (0..buffer.area.height)
            .map(|y| {
                (0..buffer.area.width)
                    .filter_map(|x| buffer.cell((x, y)).map(ratatui::buffer::Cell::symbol))
                    .collect()
            })
            .collect();
        assert!(rows.iter().all(|row| !row.contains("MIDWEEK")), "{rows:#?}");
    }

    /// The small seconds beside the numerals are a value: `26`, not `2`. At
    /// 40 columns the numerals fitted and the suffix did not, and the terminal
    /// cut it — the fit was measured without the three cells the seconds take.
    ///
    /// Swept across widths and heights rather than pinned at 40, because 40 is
    /// only where it was noticed. Whatever follows the last block glyph on the
    /// numerals' baseline row is either nothing or both digits.
    #[test]
    fn the_small_seconds_are_drawn_whole_or_not_at_all() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let config = crate::config::Config::default();
        let gradients = config.theme.gradients();
        let mut seen_small_seconds = false;
        // One panel, drawn at every size; see the meridiem test.
        let (mut panel, _guard) = panel_from_named("small-secs", ClocksConfig::default());
        panel.show_seconds = true;

        for width in 8..=100u16 {
            for height in 6..=14u16 {
                let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap();
                terminal
                    .draw(|frame| {
                        panel.render(
                            frame,
                            frame.area(),
                            RenderContext {
                                theme: &config.theme,
                                gradients: &gradients,
                                focused: true,
                                watch: &crate::watch::WatchLog::default(),
                            },
                        );
                    })
                    .unwrap();
                let rows = crate::widgets::testing::rows(terminal.backend().buffer());
                // The baseline is the last row that holds a block glyph.
                let Some(baseline) = rows.iter().rev().find(|r| r.contains('\u{2588}')) else {
                    continue;
                };
                let after = baseline.rsplit('\u{2588}').next().unwrap_or("").trim();
                if after.is_empty() {
                    continue;
                }
                seen_small_seconds = true;
                assert!(
                    after.len() == 2 && after.bytes().all(|b| b.is_ascii_digit()),
                    "at {width}x{height} the seconds beside the numerals read {after:?}: {baseline:?}"
                );
            }
        }
        assert!(
            seen_small_seconds,
            "no size in the sweep drew small seconds, so the property was never exercised"
        );
    }

    /// The middle rung of the face ladder is measured with the seconds' cells
    /// taken out. It used to fit the short form alone and then centre the pair,
    /// so at a width that held the numerals but not the suffix the seconds were
    /// cut by the terminal. The alternative — numerals without seconds while `s`
    /// is on — is refused too: the ladder goes to plain text with them intact.
    #[test]
    fn the_short_face_is_only_chosen_when_its_seconds_fit_beside_it() {
        let (full, short, seconds) = ("15:44:26", "15:44", "26");
        let rows = 6;
        let short_width = glyphs::width_of(short, 1);
        let suffix = 3; // a space and two digits

        // Room for the numerals and the seconds: the pair, at scale 1.
        let (text, small, scale) =
            choose_face(true, full, short, seconds, None, short_width + suffix, rows);
        assert_eq!(
            (text.as_str(), small.as_deref(), scale),
            (short, Some(seconds), Some(1))
        );

        // Room for the numerals alone: not numerals alone. Plain text keeps
        // every digit the reader asked for.
        let (text, small, scale) = choose_face(
            true,
            full,
            short,
            seconds,
            None,
            short_width + suffix - 1,
            rows,
        );
        assert_eq!(
            (text.as_str(), small.as_deref(), scale),
            (full, None, None),
            "numerals that would cut or drop the seconds must give way to plain text"
        );

        // Seconds off: the short form fits the whole width, no suffix reserved.
        let (text, small, scale) =
            choose_face(false, full, short, seconds, None, short_width, rows);
        assert_eq!(
            (text.as_str(), small.as_deref(), scale),
            (short, None, Some(1))
        );

        // A meridiem shares the seconds' column: two letters over two digits
        // cost nothing more than the digits did.
        let (text, small, scale) = choose_face(
            true,
            full,
            short,
            seconds,
            Some("PM"),
            short_width + suffix,
            rows,
        );
        assert_eq!(
            (text.as_str(), small.as_deref(), scale),
            (short, Some(seconds), Some(1))
        );

        // With the seconds hidden it still needs its own space and two cells.
        let (_, _, scale) = choose_face(false, full, short, seconds, Some("PM"), short_width, rows);
        assert_eq!(
            scale, None,
            "the numerals fit only by leaving AM/PM no room"
        );
        let (_, _, scale) = choose_face(
            false,
            full,
            short,
            seconds,
            Some("PM"),
            short_width + 3,
            rows,
        );
        assert_eq!(scale, Some(1));
    }

    /// #265: a 12-hour clock converts the reader's own `time_format`, keeping
    /// their padding and putting AM/PM beside the time rather than at the end
    /// of whatever follows it.
    #[test]
    fn a_twelve_hour_clock_converts_the_table_format_it_is_given() {
        assert_eq!(twelve_hour_format("%H:%M:%S"), "%I:%M:%S %p");
        // Padding is the reader's.
        assert_eq!(twelve_hour_format("%k:%M"), "%l:%M %p");
        assert_eq!(twelve_hour_format("%-H:%M"), "%-I:%M %p");
        // Whole-time shorthands are spelled out, so `s` can find the seconds.
        assert_eq!(twelve_hour_format("%T"), "%I:%M:%S %p");
        assert_eq!(without_seconds(&twelve_hour_format("%T")), "%I:%M %p");
        assert_eq!(twelve_hour_format("%R"), "%I:%M %p");
        // AM/PM goes beside the time, not after whatever follows it.
        assert_eq!(twelve_hour_format("%H:%M (%Z)"), "%I:%M %p (%Z)");
        // Nothing to convert is left exactly alone.
        assert_eq!(twelve_hour_format("%I:%M:%S %p"), "%I:%M:%S %p");
        assert_eq!(twelve_hour_format("%-I:%M%P"), "%-I:%M%P");
        assert_eq!(twelve_hour_format("%H:%M %p"), "%I:%M %p");
        assert_eq!(twelve_hour_format("%M past"), "%M past");
        assert_eq!(twelve_hour_format(""), "");
        // A literal percent is not a specifier.
        assert_eq!(twelve_hour_format("100%% %H"), "100%% %I %p");
        assert_eq!(twelve_hour_format("%%H:%M"), "%%H:%M");
        // A trailing lone `%` neither panics nor vanishes.
        assert_eq!(twelve_hour_format("%H %"), "%I %p %");
    }

    #[test]
    fn h_switches_the_clock_between_twelve_and_twenty_four_hours() {
        let (mut panel, _guard) = panel_from_named("h-key", ClocksConfig::default());
        assert!(!panel.twelve_hour);
        assert_eq!(
            panel.handle_key(KeyEvent::from(KeyCode::Char('h'))),
            KeyOutcome::Consumed
        );
        assert!(panel.twelve_hour);
        let mut state = crate::state::UiState::default();
        panel.remember(&mut state);
        assert_eq!(state.clocks_twelve_hour, Some(true));
        press(&mut panel, KeyCode::Char('h'));
        assert!(!panel.twelve_hour);
    }

    /// The rows of `panel` drawn at `width` x `height`, one string per row.
    fn drawn(panel: &mut ClocksPanel, width: u16, height: u16) -> Vec<String> {
        crate::widgets::testing::rows(&crate::widgets::testing::rendered(panel, width, height))
    }

    /// AM/PM is a value like the small seconds: `PM`, never `P`. Swept over
    /// sizes with the seconds on and off, because the two take different
    /// rungs of the ladder and each reserves the meridiem's room separately.
    /// The plain-text fallback carries it too, or says `…`.
    #[test]
    fn the_meridiem_is_drawn_whole_or_not_at_all() {
        let (mut seen_beside, mut seen_plain) = (false, false);
        // One panel, drawn at every size: building one saves its seeded zone
        // list, and a save per size made this test take seconds.
        let (mut panel, _guard) = panel_from_named("meridiem", ClocksConfig::default());
        panel.twelve_hour = true;
        for show_seconds in [true, false] {
            panel.show_seconds = show_seconds;
            for width in 6..=100u16 {
                for height in 6..=14u16 {
                    let rows = drawn(&mut panel, width, height);
                    let top = &rows[0];
                    if top.contains('\u{2588}') {
                        let after = top.rsplit('\u{2588}').next().unwrap_or("").trim();
                        assert!(
                            after == "AM" || after == "PM",
                            "at {width}x{height} the numerals' top row ends {after:?}: {top:?}"
                        );
                        seen_beside = true;
                    } else {
                        let text = top.trim();
                        assert!(
                            text.ends_with("AM")
                                || text.ends_with("PM")
                                || text.ends_with('\u{2026}'),
                            "at {width}x{height} the plain clock lost its meridiem silently: {text:?}"
                        );
                        seen_plain = true;
                    }
                }
            }
        }
        assert!(
            seen_beside && seen_plain,
            "the sweep must reach both faces, or it proves half of this"
        );
    }

    /// A 12-hour zone row is fifteen cells with its day marker, and at the
    /// 24-hour table's twelve the marker was the part cut. Kiritimati is
    /// UTC+14 and the primary UTC−12, so it is tomorrow there at every instant
    /// this test could run — the marker is certain, not a matter of the hour.
    #[test]
    fn a_twelve_hour_zone_row_keeps_its_day_marker() {
        let (mut panel, _guard) = panel_from_named(
            "meridiem-marker",
            ClocksConfig {
                zones: vec![
                    zone("Here", "Etc/GMT+12"),
                    zone("Kiritimati", "Pacific/Kiritimati"),
                ],
                twelve_hour: true,
                ..ClocksConfig::default()
            },
        );
        let rows = drawn(&mut panel, 40, 20);
        let row = rows
            .iter()
            .find(|row| row.contains("Kiritimati"))
            .expect("the zone row is drawn");
        assert!(
            row.contains("M +1d"),
            "a 12-hour row keeps AM/PM and its marker: {row:?}"
        );
    }

    /// A panel seeded from `config`, with a zone file of its very own.
    ///
    /// It has to be its own: `write_atomic` creates the parent directory it is
    /// given, so a shared path is a shared *file*, and these tests all edit the
    /// zone list. A single `/nonexistent/zones.toml` looked fine on macOS and
    /// Linux — nothing can create `/nonexistent` without root, so every save
    /// failed harmlessly and every panel got the seed — and on Windows the
    /// runner happily made `C:\nonexistent`, after which each test loaded
    /// whatever the last one had written and three of them failed with a
    /// timezone none of them had asked for.
    fn panel_from_named(name: &str, config: ClocksConfig) -> (ClocksPanel, TempDir) {
        let dir = TempDir::new(&format!("zones-{name}"));
        let panel = ClocksPanel::new(config, dir.join("zones.toml")).expect("builds from a seed");
        (panel, dir)
    }

    fn zone(label: &str, tz: &str) -> ClockZone {
        ClockZone {
            label: label.into(),
            timezone: tz.into(),
        }
    }

    fn press(panel: &mut ClocksPanel, code: KeyCode) {
        panel.handle_key(KeyEvent::from(code));
    }

    fn labels(panel: &ClocksPanel) -> Vec<String> {
        panel.secondary.iter().map(|c| c.label.clone()).collect()
    }

    /// Removing the last clock in the list used to leave the cursor one past
    /// the end, where `d` did nothing at all and the panel looked wedged.
    #[test]
    fn the_cursor_stays_on_a_real_clock_after_a_removal() {
        let (mut panel, _guard) = panel_from_named(
            "the_cursor_stays_on_a_real_c",
            ClocksConfig {
                zones: vec![
                    zone("Home", "local"),
                    zone("UTC", "UTC"),
                    zone("Tokyo", "Asia/Tokyo"),
                ],
                ..ClocksConfig::default()
            },
        );

        // Move to the last secondary clock and remove it.
        press(&mut panel, KeyCode::Down);
        assert_eq!(panel.selected, 2);
        press(&mut panel, KeyCode::Char('d'));
        assert_eq!(labels(&panel), ["UTC"], "Tokyo is gone");

        // The cursor must now be on UTC, not past it, so `d` works again.
        assert_eq!(panel.selected, 1);
        press(&mut panel, KeyCode::Char('d'));
        assert!(labels(&panel).is_empty(), "and UTC goes too");
    }

    /// The primary is index 0 and never selectable, so the last `d` on an
    /// empty list has to say why nothing happened rather than look broken.
    ///
    /// Read off the screen as well as the field: with no table to draw, the
    /// panel returned before it reached the notice, so the field said why and
    /// the screen said nothing.
    #[test]
    fn the_big_clock_survives_and_says_so() {
        let (mut panel, _guard) = panel_from_named(
            "the_big_clock_survives_and_s",
            ClocksConfig {
                zones: vec![zone("Home", "local")],
                ..ClocksConfig::default()
            },
        );
        press(&mut panel, KeyCode::Char('d'));
        assert_eq!(panel.primary.label, "Home", "still there");
        assert!(panel.status.is_some(), "and the panel says why");
        let rows = drawn(&mut panel, 40, 12);
        assert!(
            rows.iter().any(|row| row.contains("the big clock stays")),
            "on screen, too: {rows:#?}"
        );
    }

    /// A first run writes the seeded list out, so `zones.toml` is there to be
    /// edited by hand, as the shipped config says, and `[clocks].zones` is not
    /// read again. It was marked to be written and never was: the file
    /// appeared only once a clock was changed from the panel, and until then
    /// the config was re-read every launch — after which, with nothing to say
    /// so, it stopped being.
    #[test]
    fn a_first_run_writes_the_seeded_zone_file() {
        let seed = vec![zone("Home", "UTC"), zone("Tokyo", "Asia/Tokyo")];
        let (panel, _guard) = panel_from_named(
            "first_run_writes",
            ClocksConfig {
                zones: seed.clone(),
                ..ClocksConfig::default()
            },
        );
        assert!(
            panel.zones.path().exists(),
            "the seed is on disk to be edited"
        );
        assert_eq!(panel.zones.last_error, None);
        let written = crate::zones::Zones::load(panel.zones.path(), &[]).expect("reads back");
        let names = |zones: &[ClockZone]| -> Vec<(String, String)> {
            zones
                .iter()
                .map(|z| (z.label.clone(), z.timezone.clone()))
                .collect()
        };
        assert_eq!(names(written.zones()), names(&seed));
    }

    /// The other side: a config with no clocks has nothing to seed, and writes
    /// nothing, so a list added to the config later is still read.
    #[test]
    fn an_empty_seed_writes_no_zone_file() {
        let (panel, _guard) = panel_from_named(
            "empty_seed_writes_nothing",
            ClocksConfig {
                zones: Vec::new(),
                ..ClocksConfig::default()
            },
        );
        assert!(!panel.zones.path().exists());
    }

    /// A seed that cannot be written is reported the way a failed edit is,
    /// and the panel still builds: the clocks are on screen either way.
    #[test]
    fn a_seed_that_cannot_be_written_is_reported_not_fatal() {
        let (_, guard) = panel_from_named("unwritable_seed", ClocksConfig::default());
        let blocker = guard.join("blocker");
        std::fs::write(&blocker, "a file where a directory has to be").unwrap();
        let panel = ClocksPanel::new(ClocksConfig::default(), blocker.join("zones.toml"))
            .expect("a failed save does not stop the panel");
        assert!(panel.zones.last_error.is_some(), "it is reported");
        assert!(panel.alert().is_some(), "where the status bar sees it");
    }

    /// More clocks than rows: the table shows a window of them that follows
    /// the cursor, so the clock `d` would remove is always one you can see.
    /// Every zone went into one paragraph and the terminal dropped the ones
    /// past the bottom, while the cursor walked on through rows nobody could
    /// see.
    #[test]
    fn the_selected_clock_is_always_on_screen() {
        let names = [
            "Alpha", "Bravo", "Charlie", "Delta", "Echo", "Foxtrot", "Golf", "Hotel",
        ];
        let zones = [
            "UTC",
            "Asia/Tokyo",
            "Europe/Paris",
            "America/New_York",
            "Australia/Sydney",
            "Asia/Kolkata",
            "America/Chicago",
            "Africa/Cairo",
        ];
        let mut seed = vec![zone("Home", "local")];
        seed.extend(names.iter().zip(zones).map(|(n, z)| zone(n, z)));
        let (mut panel, _guard) = panel_from_named(
            "window",
            ClocksConfig {
                zones: seed,
                ..ClocksConfig::default()
            },
        );

        let first = drawn(&mut panel, 40, 8);
        assert!(
            !first.iter().any(|row| row.contains("Hotel")),
            "the table has to be too tall for the panel, or this proves nothing: {first:#?}"
        );
        let on_screen = |panel: &mut ClocksPanel, name: &str| {
            assert_eq!(names[panel.selected - 1], name);
            let rows = drawn(panel, 40, 8);
            let shown = rows.iter().filter(|row| row.contains(name)).count();
            assert_eq!(shown, 1, "{name} is selected: {rows:#?}");
        };
        let (last, rest) = names.split_last().expect("names");
        for name in rest {
            on_screen(&mut panel, name);
            press(&mut panel, KeyCode::Down);
        }
        on_screen(&mut panel, last);
        for name in rest.iter().rev() {
            press(&mut panel, KeyCode::Up);
            on_screen(&mut panel, name);
        }
    }

    /// With no table, the notice's row is budgeted like the date: the clock
    /// and the date fit above it, and nothing drawn there before shows
    /// through beside it. It was painted over the date, and the end of the
    /// date showed through after the message at the heights where the two
    /// met.
    #[test]
    fn a_notice_on_a_lone_clock_has_its_row_to_itself() {
        for height in 2..=14u16 {
            let (mut panel, _guard) = panel_from_named(
                "lone-notice",
                ClocksConfig {
                    zones: Vec::new(),
                    ..ClocksConfig::default()
                },
            );
            panel.status = Some("the big clock stays".into());
            let rows = drawn(&mut panel, 40, height);
            let last = rows.last().expect("a row").trim_end().to_string();
            assert_eq!(last, "the big clock stays", "height {height}: {rows:#?}");
        }
    }

    /// A notice takes a row of its own under the table. It was painted over
    /// the last row, so `o` on the last clock hid the clock it was pressed on.
    #[test]
    fn a_notice_never_covers_a_clock() {
        let (mut panel, _guard) = panel_from_named(
            "notice_row",
            ClocksConfig {
                zones: vec![
                    zone("Home", "local"),
                    zone("Alpha", "UTC"),
                    zone("Bravo", "Asia/Tokyo"),
                    zone("Charlie", "Europe/Paris"),
                ],
                ..ClocksConfig::default()
            },
        );
        press(&mut panel, KeyCode::Down);
        press(&mut panel, KeyCode::Down);
        let calm = drawn(&mut panel, 40, 7);
        assert!(
            calm[6].contains("Charlie"),
            "the table ends on the panel's last row: {calm:#?}"
        );
        press(&mut panel, KeyCode::Char('o'));
        let rows = drawn(&mut panel, 40, 7);
        assert!(
            rows.iter().any(|row| row.contains("Charlie")),
            "the selected clock is still drawn: {rows:#?}"
        );
        let path = panel.zones.path().display().to_string();
        let head: String = path.chars().take(10).collect();
        assert!(rows[6].contains(&head), "and the path under it: {rows:#?}");
    }

    /// A notice is one row for a moment, and the numerals are the panel's
    /// face: a key that shrinks them until the next key is the footprint
    /// change the visual system refuses. The row comes from slack — the blank
    /// line above the table, or rows the numerals leave unused — and from
    /// the clock only when there is none. It was taken from the clock's
    /// budget every time, so at the panel's own largest size `o` dropped the
    /// numerals from fifteen rows to ten, and a failed save kept them there.
    ///
    /// Asserted at the size the panel asks for, where it sits in a tall row,
    /// and then at every height: with a table there is always a separator to
    /// give, and a lone clock gives from its own last row whenever it is
    /// blank. Where it is not, the clock steps down rather than lose its
    /// last row of numerals under the notice — every digit fills every row
    /// of its glyph, so a whole face is a multiple of five rows.
    #[test]
    fn a_notice_does_not_cost_the_numerals_a_scale_step() {
        let numerals = |rows: &[String]| rows.iter().filter(|row| row.contains('\u{2588}')).count();
        let notice = "the big clock stays";
        let (mut table, _a) = panel_from_named("notice-table", ClocksConfig::default());
        let (mut lone, _b) = panel_from_named(
            "notice-lone",
            ClocksConfig {
                zones: vec![zone("Home", "local")],
                ..ClocksConfig::default()
            },
        );
        let (mut undated, _c) = panel_from_named(
            "notice-undated",
            ClocksConfig {
                zones: vec![zone("Home", "local")],
                date_format: String::new(),
                ..ClocksConfig::default()
            },
        );

        let width = table.max_width().expect("a widest") - FRAME_WIDTH;
        let tallest = table.max_height().expect("a tallest") - FRAME_HEIGHT;
        table.status = None;
        let calm = drawn(&mut table, width, tallest);
        assert_eq!(
            numerals(&calm),
            usize::from(BIG_CLOCK_ROWS),
            "the numerals are at their largest, or this proves nothing: {calm:#?}"
        );
        table.status = Some(notice.into());
        let noted = drawn(&mut table, width, tallest);
        assert_eq!(numerals(&noted), numerals(&calm), "{noted:#?}");
        assert!(noted.last().is_some_and(|row| row.contains(notice)));
        for name in ["UTC", "London", "Tokyo"] {
            assert!(
                noted.iter().any(|row| row.contains(name)),
                "{name} is still drawn: {noted:#?}"
            );
        }

        for (panel, has_table, dated) in [
            (&mut table, true, true),
            (&mut lone, false, true),
            (&mut undated, false, false),
        ] {
            for height in 2..=tallest + 3 {
                panel.status = None;
                let calm = drawn(panel, width, height);
                panel.status = Some(notice.into());
                let noted = drawn(panel, width, height);
                assert!(
                    noted.last().is_some_and(|row| row.contains(notice)),
                    "height {height}: {noted:#?}"
                );
                assert_eq!(
                    numerals(&noted) % usize::from(GLYPH_ROWS),
                    0,
                    "height {height}, numerals cut under the notice: {noted:#?}"
                );
                // Nor does the date give way while the numerals have a row to
                // give: it is not slack, and dropping it is the clock losing
                // half of itself to a passing message.
                let face = numerals(&calm);
                if dated && face > 0 {
                    let date = calm[face].trim();
                    assert!(!date.is_empty(), "the date is under the numerals");
                    assert!(
                        noted.iter().any(|row| row.trim() == date),
                        "height {height}, the date gave way: {noted:#?}"
                    );
                }
                let spare = has_table || calm.last().is_some_and(|row| row.trim().is_empty());
                if spare {
                    assert_eq!(
                        numerals(&noted),
                        numerals(&calm),
                        "height {height}, a row to spare: {calm:#?} {noted:#?}"
                    );
                }
            }
        }
    }

    #[test]
    fn a_zone_that_does_not_resolve_is_refused_with_the_prompt_left_open() {
        let (mut panel, _guard) =
            panel_from_named("a_zone_that_does_not_resolve", ClocksConfig::default());
        press(&mut panel, KeyCode::Char('a'));
        for c in "Mars/Olympus".chars() {
            panel.handle_key(KeyEvent::from(KeyCode::Char(c)));
        }
        let before = labels(&panel);
        press(&mut panel, KeyCode::Enter);

        assert!(panel.asking.is_some(), "the prompt stays open to be fixed");
        assert_eq!(labels(&panel), before, "and nothing was added");
    }

    /// `Label = Zone` with nothing after the `=` names no zone, and the panel
    /// said "that clock is already on the panel": `Zones` refused a blank
    /// zone and a repeated one with the same `false`, and the prompt could
    /// only phrase it one way. Both dialogs, because both took the answer.
    #[test]
    fn a_label_with_no_zone_is_refused_for_that_and_not_as_a_duplicate() {
        let (mut panel, _guard) = panel_from_named(
            "a_label_with_no_zone_is_refu",
            ClocksConfig {
                zones: vec![zone("Home", "local"), zone("UTC", "UTC")],
                ..ClocksConfig::default()
            },
        );
        let complaint = |panel: &ClocksPanel| {
            use ratatui::Terminal;
            use ratatui::backend::TestBackend;
            let theme = crate::config::Config::default().theme;
            let prompt = panel.asking.as_ref().expect("the prompt stays open");
            let mut terminal = Terminal::new(TestBackend::new(80, 20)).unwrap();
            terminal
                .draw(|frame| prompt.render(frame, frame.area(), &theme))
                .unwrap();
            let buffer = terminal.backend().buffer().clone();
            buffer
                .content()
                .iter()
                .map(ratatui::buffer::Cell::symbol)
                .collect::<String>()
        };

        press(&mut panel, KeyCode::Char('a'));
        for c in "Somewhere =".chars() {
            press(&mut panel, KeyCode::Char(c));
        }
        let before = labels(&panel);
        press(&mut panel, KeyCode::Enter);
        let screen = complaint(&panel);
        assert!(screen.contains("name a zone"), "add: {screen}");
        assert!(!screen.contains("already"), "add: {screen}");
        assert_eq!(labels(&panel), before, "and nothing was added");

        press(&mut panel, KeyCode::Esc);
        press(&mut panel, KeyCode::Char('e'));
        // Whatever the selected clock pre-filled, replaced by a bare label.
        for _ in 0..40 {
            press(&mut panel, KeyCode::Backspace);
        }
        for c in "Elsewhere =".chars() {
            press(&mut panel, KeyCode::Char(c));
        }
        press(&mut panel, KeyCode::Enter);
        let screen = complaint(&panel);
        assert!(screen.contains("name a zone"), "edit: {screen}");
        assert!(!screen.contains("already"), "edit: {screen}");
    }

    /// Picking from the list names the clock after the city you recognised,
    /// and the `Label = Zone` form still works for anyone typing a zone the
    /// list does not carry.
    #[test]
    fn a_clock_can_be_added_with_or_without_a_label() {
        let (mut panel, _guard) = panel_from_named(
            "a_clock_can_be_added_with_or",
            ClocksConfig {
                zones: vec![zone("Home", "local")],
                ..ClocksConfig::default()
            },
        );

        press(&mut panel, KeyCode::Char('a'));
        for c in "Bengaluru".chars() {
            panel.handle_key(KeyEvent::from(KeyCode::Char(c)));
        }
        press(&mut panel, KeyCode::Enter);
        assert_eq!(
            labels(&panel),
            ["Bengaluru"],
            "the city you picked, not the one in the identifier"
        );

        press(&mut panel, KeyCode::Char('a'));
        for c in "HQ = Europe/Berlin".chars() {
            panel.handle_key(KeyEvent::from(KeyCode::Char(c)));
        }
        press(&mut panel, KeyCode::Enter);
        assert_eq!(labels(&panel), ["Bengaluru", "HQ"], "or named by you");
    }

    #[test]
    fn local_and_utc_always_resolve() {
        assert!(resolve_zone("local").is_ok());
        assert!(resolve_zone("LOCAL").is_ok());
        assert!(resolve_zone("").is_ok());
        assert!(resolve_zone("UTC").is_ok());
    }

    #[test]
    fn unknown_zones_report_the_name_instead_of_panicking() {
        let err = resolve_zone("Mars/Olympus").expect_err("must fail");
        assert!(err.contains("Mars/Olympus"), "got: {err}");
    }

    #[test]
    fn relative_offsets_are_expressed_against_the_primary_clock() {
        let utc = Offset::from_seconds(0).unwrap();
        let tokyo = Offset::from_seconds(9 * 3600).unwrap();
        let new_york = Offset::from_seconds(-4 * 3600).unwrap();
        let kolkata = Offset::from_seconds(5 * 3600 + 1800).unwrap();

        assert_eq!(relative_offset(utc, tokyo), "+9h");
        assert_eq!(relative_offset(utc, new_york), "-4h");
        assert_eq!(relative_offset(utc, utc), "same");
        assert_eq!(relative_offset(utc, kolkata), "+5h30");
        // Relative to New York rather than to UTC.
        assert_eq!(relative_offset(new_york, tokyo), "+13h");
    }

    #[test]
    fn the_first_zone_becomes_the_large_clock() {
        let (panel, _guard) = panel_from_named(
            "the_first_zone_becomes_the_l",
            ClocksConfig {
                zones: vec![zone("Home", "UTC"), zone("Tokyo", "Asia/Tokyo")],
                ..Default::default()
            },
        );
        assert_eq!(panel.primary.label, "Home");
        assert_eq!(panel.secondary.len(), 1);
        assert_eq!(panel.secondary[0].label, "Tokyo");
    }

    #[test]
    fn an_empty_zone_list_still_shows_local_time() {
        let (panel, _guard) = panel_from_named(
            "an_empty_zone_list_still_sho",
            ClocksConfig {
                zones: Vec::new(),
                ..Default::default()
            },
        );
        assert!(panel.primary.zone.is_ok());
        assert!(panel.secondary.is_empty());
    }

    #[test]
    fn a_label_falls_back_to_the_zone_name() {
        let (panel, _guard) = panel_from_named(
            "a_label_falls_back_to_the_zo",
            ClocksConfig {
                zones: vec![zone("", "UTC"), zone("", "Asia/Tokyo")],
                ..Default::default()
            },
        );
        assert_eq!(panel.primary.label, "UTC");
        assert_eq!(panel.secondary[0].label, "Asia/Tokyo");
    }

    #[test]
    fn s_toggles_seconds_and_is_consumed() {
        let (mut panel, _guard) =
            panel_from_named("s_toggles_seconds_and_is_con", ClocksConfig::default());
        let before = panel.show_seconds;
        let outcome = panel.handle_key(KeyEvent::new(
            KeyCode::Char('s'),
            ratatui::crossterm::event::KeyModifiers::NONE,
        ));
        assert_eq!(outcome, KeyOutcome::Consumed);
        assert_ne!(panel.show_seconds, before);
    }

    #[test]
    fn other_keys_fall_through_to_the_application() {
        let (mut panel, _guard) =
            panel_from_named("other_keys_fall_through_to_t", ClocksConfig::default());
        let outcome = panel.handle_key(KeyEvent::new(
            KeyCode::Tab,
            ratatui::crossterm::event::KeyModifiers::NONE,
        ));
        assert_eq!(outcome, KeyOutcome::Ignored);
    }

    /// The move keys have to reach the *border*, not just the help overlay.
    ///
    /// They shipped in 0.17.0 as `extra` bindings, which put them in `?` and
    /// nowhere else — so the border advertised `e edit` and said nothing about
    /// reordering, which is the thing #109 was filed for. The owner went looking
    /// for the feature in a released build and concluded it had not been
    /// implemented. A key nobody can find is a key that does not exist.
    ///
    /// Asserted against the width the default layout actually gives this panel,
    /// because `hint_line` fills the border in order and stops at the first
    /// binding that will not fit: this passes or fails on the *order* and the
    /// *wording* of `default_keys().bindings()`, not merely on the primary flag. Lengthening any
    /// label above `move` pushes it off, which is how it was invisible before.
    #[test]
    fn the_move_keys_reach_the_border_at_the_default_width() {
        // The clock's frame measures 52 cells at 150x42 — checked by rendering
        // it — and `render_frame` spends `width - 8` of that on hints.
        const BUDGET: u16 = 52 - 8;
        let theme = crate::theme::Theme::default();
        let hint = crate::frame::hint_line(default_keys().bindings(), &theme, BUDGET)
            .expect("the clock has primaries");
        let drawn: String = hint.spans.iter().map(|s| s.content.as_ref()).collect();

        // The move key, not a substring of another hint. The first version of
        // this test asked whether the border contained "move" — and `remove`
        // contains `move`, so it passed with the binding demoted back to an
        // extra. Match the key itself.
        assert!(
            drawn.contains("Shift+↑↓"),
            "reordering is invisible on the border: {drawn:?}"
        );
        assert!(
            drawn.contains("a add") && drawn.contains("e edit"),
            "adding and editing must survive alongside it: {drawn:?}"
        );
    }

    /// `h` shipped in 1.13.0 as an `extra`, so the border never offered it at any
    /// width — reported by the owner on a clock with room to spare. Asserted at
    /// both ends of its range: absent where the default width already fits
    /// exactly four hints, present from the first budget that has room for it,
    /// and reached before `d`, which the other list panels already teach.
    #[test]
    fn the_twelve_hour_key_reaches_the_border_once_there_is_room() {
        let theme = crate::theme::Theme::default();
        let drawn = |budget: u16| -> String {
            crate::frame::hint_line(default_keys().bindings(), &theme, budget)
                .expect("the clock has primaries")
                .spans
                .iter()
                .map(|s| s.content.as_ref())
                .collect()
        };

        // Default width: the four that fit are untouched, and `h` waits.
        let default = drawn(52 - 8);
        assert!(
            default.contains("Shift+↑↓") && !default.contains("12/24h"),
            "at the default width the move key still fits and `h` drops: {default:?}"
        );

        // The first budget with room for it.
        let roomy = drawn(55);
        assert!(
            roomy.contains("h 12/24h"),
            "a clock with room for `h` must show it: {roomy:?}"
        );
        assert!(
            !roomy.contains("d remove"),
            "`h` is offered before `d`, so at 55 cells it is `h` that fits: {roomy:?}"
        );

        // Wide enough for everything: all six, `h` before `d`.
        let wide = drawn(200);
        let (h, d) = (wide.find("h 12/24h"), wide.find("d remove"));
        assert!(
            matches!((h, d), (Some(h), Some(d)) if h < d),
            "a wide clock shows `h` and then `d`: {wide:?}"
        );
    }

    /// And the order is the thing that decides it, independently of any width.
    /// `move` must be reached before `remove`, or a narrow panel spends its last
    /// slot on the key every other list panel already teaches.
    #[test]
    fn move_is_offered_to_the_border_before_remove() {
        let keys = default_keys();
        let primaries: Vec<&str> = keys
            .bindings()
            .iter()
            .filter(|b| b.primary)
            .map(|b| b.action.as_ref())
            .collect();
        // `expect`, not a bare comparison. `position` returns `Option`, and
        // `None < Some(_)` is true — so comparing them directly passed when the
        // binding was not a primary at all, which is the exact regression this
        // is here to catch.
        let move_at = primaries
            .iter()
            .position(|a| *a == "move")
            .expect("`move` must be a primary, or it never reaches the border");
        let remove_at = primaries
            .iter()
            .position(|a| *a == "remove")
            .expect("`remove` is still a primary");
        assert!(
            move_at < remove_at,
            "move must come first; got {primaries:?}"
        );
    }
}