rich_cli/

lib.rs

//! `rich` — a Rust port of the `rich-cli` terminal toolbox.
//!
//! The command line lives in this library target so the Python wheel can run
//! it in-process ([`run`] and [`run_embedded`] are its only public items);
//! `main.rs` is the `rich` binary and only calls [`run`].
//!
//! This binary mirrors the upstream `rich-cli` command-line tool and is built on
//! the [`rich`] library crate. It implements the rendering modes `--print`,
//! `--markdown`, `--rst`, `--json`, `--syntax`, `--csv`, `--ipynb`, and `--rule`, plus
//! width/justify, HTML/SVG export to a file (`--export-html PATH` / `-o PATH`,
//! `--export-svg PATH`, which may be combined, and our `--export-png PATH`), the
//! `--panel`/`--padding` decorators (with `--title`/`--caption`/`--style`), a
//! plain-file printer (with extension auto-detection), **URL fetch** (`rich <url>`,
//! behind the default `fetch` feature), **paging** (`--pager`), and a capability
//! demo — i.e. the whole common rich-cli surface.
//!
//! On top of that it has documented binary-boundary conveniences that upstream
//! lacks (see `docs/PORTING.md`): Org, AsciiDoc and man pages (`--org`,
//! `--asciidoc`, `--man`, detected by extension and content), JSONL/log
//! streaming, images and GIFs (behind
//! the default `art` feature), `--watch`, `--batch`, config profiles and
//! `--theme-file`, and the tool commands `inspect`, `diff` (images, text and
//! patches), `view`, `hex`, `unicode`, `env`, `capture`, `ansi explain`,
//! `doctor`, `bench compare`, `completions`, `docs`, `config` and `plugins`;
//! the diagram sources `mermaid`, `dot`, `deps` and `schema`, `chart` and
//! `profile`;
//! the interactive commands (`choose`, `filter`, `input`, `confirm`, `pager`,
//! `write`, `file`, `color`, `asset`, `explore`, `date`); `micro`; `record`;
//! and `serve` (behind the off-by-default `serve` feature). Each composes
//! public `rich` / `rich-ext` / `rich-art` / `rich-diagram` / `rich-mermaid`
//! / `rich-interact` / `rich-micro` / `rich-record` / `rich-web` APIs.

// A builder method that returns `Self` is `#[must_use]`: dropping its
// result drops the value (CONTRIBUTING.md, "API conventions").
#![warn(clippy::return_self_not_must_use)]

use std::io::{BufRead, IsTerminal, Read, Write};
use std::path::{Path, PathBuf};
use std::process::ExitCode;

mod animation;
#[cfg(feature = "interact")]
mod approve_jump;
mod authoring;
#[cfg(feature = "art")]
mod banner;
mod batch;
#[cfg_attr(target_os = "wasi", path = "batch_output_wasi.rs")]
mod batch_output;
mod batch_paths;
#[cfg(test)]
mod batch_races;
mod chart;
mod cli_spec;
mod config;
mod console;
mod controls;
mod demo;
mod doctor;
mod documents;
mod host;
mod inspect;
#[cfg(feature = "interact")]
mod interactive;
mod logs;
mod marketplace;
#[cfg(feature = "art")]
mod micro;
mod plugins;
mod profile;
#[cfg(feature = "record")]
mod record;
mod redact_preview;
mod render_target;
#[cfg(feature = "serve")]
mod serve;
mod shell;
mod sources;
mod spin;
mod structured_log;
mod style_rules;
mod tools;
mod viewers;
mod watch;
use batch::run_batch;
use config::{ConfigRoots, config_args};
use marketplace::spec as marketplace_spec;

use rich::r#box::{Box as BoxSet, DOUBLE, HEAVY_HEAD, SQUARE};
use rich::cells::cell_len;
use rich::markdown::Markdown;
use rich::measure::Measurement;
use rich::protocol::{LineRenderable, OwnedTableRows};
use rich::text::Text;
use rich::{
    Align, AnsiDecoder, Bar, ColorSystem, Columns, Console, ConsoleOptions, Constrain, Control,
    DEFAULT_TERMINAL_THEME, Highlighter, HorizontalAlign, ISO8601Highlighter, Json, Justify,
    Layout, Live, LiveRender, LogLevel, LogRender, Padding, Panel, Pretty, Progress, ProgressBar,
    ProgressColumn, Renderable, Rule, Segment, Spinner, Status, Style, Styled, Syntax, Table,
    Traceback, Tree, filesize,
};
use rich_data::csv::{Dialect, has_header, read_rows, sniff};
use rich_data::infer::{InferredType, Inferrer};
use rich_ext::ConsoleExt;
use rich_ext::cli::CliExtensions;
use rich_ext::encoding::{Encoding, has_utf16_bom};
use rich_ext::sanitize_terminal_controls;

/// Boxed `Text` helper to cut down on `Box::new(Text::new(...))` noise.
fn text(content: &str) -> Box<dyn Renderable> {
    Box::new(Text::new(content))
}

/// The builder every console the `rich` binary prints through starts from.
///
/// The core reads `FORCE_COLOR` and `TTY_COMPATIBLE` as rich 15.0.0 does.
/// The binary keeps its documented contract instead (`FORCE_COLOR` is not
/// supported and redirected stdout stays plain), so it decides whether it
/// writes to a terminal from standard output alone. A caller may still
/// override that with `force_terminal`.
///
/// The core also exits with status 1 when the reader closes the pipe, as
/// upstream does. For the binary a closed pipe is success (`rich … | head`):
/// the console goes quiet and the command ends normally.
pub(crate) fn console_builder() -> rich::console::ConsoleBuilder {
    Console::builder()
        .force_terminal(std::io::stdout().is_terminal())
        .on_broken_pipe(|console| console.set_quiet(true))
}

const VERSION: &str = env!("CARGO_PKG_VERSION");

/// How to render the resource. Mirrors the mutually-exclusive rich-cli flags.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Mode {
    /// No explicit flag: auto-detect by file extension, else print plain.
    Auto,
    /// `-p/--print`: interpret the resource as console markup.
    Print,
    /// `-m/--markdown`: render the resource as Markdown.
    Markdown,
    /// `-j/--json`: pretty-print the resource as JSON.
    Json,
    /// `-x/--syntax`: syntax-highlight the resource (language from extension).
    Syntax,
    /// `--csv`: render a CSV/TSV resource as a table.
    Csv,
    /// `.ipynb`: render a Jupyter notebook (markdown + code cells + outputs).
    Ipynb,
    /// `--rst`: render reStructuredText, as upstream's `rich-rst` does.
    Rst,
    /// `--org`: render an Org document (not upstream; see `documents.rs`).
    Org,
    /// `--asciidoc`: render AsciiDoc (not upstream; see `documents.rs`).
    AsciiDoc,
    /// `--man`: render a man page from its roff source (not upstream; see
    /// `documents.rs`).
    Man,
    /// `--gif`: animate one or more GIFs in place.
    Gif,
    /// `--diff`: perceptually compare two images (takes exactly two resources).
    Diff,
    /// `--image`: render a single still image as ASCII art, half-blocks, or Sixel.
    Image,
    /// `--rule`: draw a horizontal rule (the resource, if any, is its title).
    Rule,
    /// `--jsonl`: stream JSON Lines / NDJSON records.
    JsonLines,
    /// `--log`: stream common structured-log JSONL records.
    Log,
    /// `--inspect`: explore structured data (not upstream; see `inspect.rs`).
    Inspect,
    /// `ansi explain` / `--ansi-explain`: decode escape sequences (`tools.rs`).
    AnsiExplain,
    /// `view`: detect the format, then show it paged, numbered and searchable
    /// (not upstream; see `viewers.rs`).
    View,
    /// `hex`: a hex dump with an ASCII panel (`viewers.rs`).
    Hex,
    /// `unicode`: graphemes, code points, widths and invalid UTF-8.
    Unicode,
    /// `env`: environment variables, redacted, or one PATH-like variable.
    Env,
    /// `capture -- CMD…`: run a command and show or export its output.
    Capture,
    /// `mermaid`: draw a Mermaid diagram (not upstream; see `rs-rich-mermaid`).
    Mermaid,
    /// `dot`: draw a DOT (Graphviz) graph natively (`sources.rs`).
    Dot,
    /// `deps`: a Cargo dependency tree from `cargo metadata` (`sources.rs`).
    Deps,
    /// `schema`: a JSON Schema, SQL DDL or Arrow schema as a tree, two
    /// compared, or an ER diagram (`sources.rs`).
    Schema,
    /// `chart`: a chart from CSV, JSON or stdin (`chart.rs`).
    Chart,
    /// `profile`: a profile of CSV, TSV or JSON Lines (`profile.rs`).
    Profile,
}

impl Mode {
    fn streams_records(self) -> bool {
        matches!(self, Self::JsonLines | Self::Log)
    }

    fn draws_directly(self) -> bool {
        matches!(self, Self::Gif | Self::Diff | Self::Image) || self.streams_records()
    }

    fn allows_extensions(self) -> bool {
        !matches!(self, Self::Gif | Self::Diff | Self::Image | Self::Rule)
            && !self.streams_records()
    }

    fn accepts_multiple_resources(self) -> bool {
        matches!(
            self,
            Self::Gif | Self::Diff | Self::Env | Self::Capture | Self::Schema
        )
    }
}

struct ModeSpec {
    mode: Mode,
    primary: &'static str,
    aliases: &'static [&'static str],
}

const MODE_SPECS: &[ModeSpec] = &[
    ModeSpec {
        mode: Mode::Auto,
        primary: "auto",
        aliases: &[],
    },
    ModeSpec {
        mode: Mode::Print,
        primary: "print",
        aliases: &["print"],
    },
    ModeSpec {
        mode: Mode::Markdown,
        primary: "markdown",
        aliases: &["markdown", "md"],
    },
    ModeSpec {
        mode: Mode::Json,
        primary: "json",
        aliases: &["json"],
    },
    ModeSpec {
        mode: Mode::Syntax,
        primary: "syntax",
        aliases: &["syntax", "code"],
    },
    ModeSpec {
        mode: Mode::Csv,
        primary: "csv",
        aliases: &["csv", "tsv"],
    },
    ModeSpec {
        mode: Mode::Ipynb,
        primary: "ipynb",
        aliases: &["ipynb", "notebook"],
    },
    ModeSpec {
        mode: Mode::Rst,
        primary: "rst",
        aliases: &["rst"],
    },
    ModeSpec {
        mode: Mode::Org,
        primary: "org",
        aliases: &["org"],
    },
    ModeSpec {
        mode: Mode::AsciiDoc,
        primary: "asciidoc",
        aliases: &["asciidoc", "adoc"],
    },
    ModeSpec {
        mode: Mode::Man,
        primary: "man",
        aliases: &["man", "roff"],
    },
    ModeSpec {
        mode: Mode::Gif,
        primary: "gif",
        aliases: &["gif"],
    },
    ModeSpec {
        mode: Mode::Diff,
        primary: "diff",
        aliases: &["diff"],
    },
    ModeSpec {
        mode: Mode::Image,
        primary: "image",
        aliases: &["image"],
    },
    ModeSpec {
        mode: Mode::Rule,
        primary: "rule",
        aliases: &["rule"],
    },
    ModeSpec {
        mode: Mode::JsonLines,
        primary: "jsonl",
        aliases: &["jsonl", "ndjson"],
    },
    ModeSpec {
        mode: Mode::Log,
        primary: "log",
        aliases: &["log", "logs"],
    },
    ModeSpec {
        mode: Mode::Inspect,
        primary: "inspect",
        aliases: &["inspect"],
    },
    ModeSpec {
        mode: Mode::AnsiExplain,
        primary: "ansi",
        aliases: &["ansi", "ansi-explain"],
    },
    ModeSpec {
        mode: Mode::View,
        primary: "view",
        aliases: &["view"],
    },
    ModeSpec {
        mode: Mode::Hex,
        primary: "hex",
        aliases: &["hex", "hexdump"],
    },
    ModeSpec {
        mode: Mode::Unicode,
        primary: "unicode",
        aliases: &["unicode"],
    },
    ModeSpec {
        mode: Mode::Env,
        primary: "env",
        aliases: &["env"],
    },
    ModeSpec {
        mode: Mode::Capture,
        primary: "capture",
        aliases: &["capture"],
    },
    ModeSpec {
        mode: Mode::Mermaid,
        primary: "mermaid",
        aliases: &["mermaid", "mmd"],
    },
    ModeSpec {
        mode: Mode::Dot,
        primary: "dot",
        aliases: &["dot", "graphviz"],
    },
    ModeSpec {
        mode: Mode::Deps,
        primary: "deps",
        aliases: &["deps"],
    },
    ModeSpec {
        mode: Mode::Schema,
        primary: "schema",
        aliases: &["schema"],
    },
    ModeSpec {
        mode: Mode::Chart,
        primary: "chart",
        aliases: &["chart"],
    },
    ModeSpec {
        mode: Mode::Profile,
        primary: "profile",
        aliases: &["profile"],
    },
];

const RENDER_MODE_FLAGS: &str = "--print/--markdown/--rst/--org/--asciidoc/--man/--json/--syntax/--csv/--ipynb/--rule/--gif/--diff/--image/--jsonl/--log/--inspect/--ansi-explain";

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ReportFormat {
    Human,
    Json,
}

impl ReportFormat {
    fn apply_option(&mut self, option: &str, value: Option<&str>) -> Result<(), String> {
        match option {
            "--report" => {
                *self = match value.ok_or("--report requires one of: human, json")? {
                    "human" => Self::Human,
                    "json" => Self::Json,
                    other => return Err(format!("unknown report format {other:?} (human, json)")),
                };
            }
            "--machine-json" => *self = Self::Json,
            _ => {}
        }
        Ok(())
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ExitClass {
    Success,
    Usage,
    Input,
    Data,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    Gate,
}

impl ExitClass {
    fn code(self) -> u8 {
        match self {
            Self::Success => 0,
            Self::Usage => 2,
            Self::Input => 3,
            Self::Data => 4,
            Self::Gate => 5,
        }
    }

    fn name(self) -> &'static str {
        match self {
            Self::Success => "success",
            Self::Usage => "usage",
            Self::Input => "input",
            Self::Data => "data",
            Self::Gate => "gate",
        }
    }

    fn exit_code(self) -> ExitCode {
        ExitCode::from(self.code())
    }
}

/// How `--diff` draws the image part of its report.
///
/// Detection of terminal graphics support is a heuristic and will be wrong
/// somewhere (there is no reliable probe that works when output is piped), so
/// this is exposed rather than inferred: when the guess is wrong the user
/// picks.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum ImageMode {
    /// Sixel where it looks supported, else half-blocks, else ASCII.
    Auto,
    /// Real pixels via the Sixel graphics protocol.
    Sixel,
    /// Half-block characters — works in any truecolour terminal.
    Blocks,
    /// Unicode Braille cells.
    Braille,
    /// Unicode quadrant blocks: 2×2 pixels, two colours per cell.
    Quadrants,
    /// A character ramp, the jp2a-style rendering. No colour required.
    Ascii,
    /// Skip the picture; print only the numbers.
    None,
}

impl std::str::FromStr for ImageMode {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value.to_ascii_lowercase().as_str() {
            "auto" => Ok(Self::Auto),
            "sixel" => Ok(Self::Sixel),
            "blocks" | "block" | "half-block" | "half-blocks" => Ok(Self::Blocks),
            "braille" => Ok(Self::Braille),
            "quadrants" | "quadrant" => Ok(Self::Quadrants),
            "ascii" | "art" => Ok(Self::Ascii),
            "none" | "off" => Ok(Self::None),
            other => Err(format!(
                "unknown image mode {other:?} (auto, sixel, blocks, quadrants, braille, ascii, none)"
            )),
        }
    }
}

/// Upstream's options for source files: `Syntax` for `--syntax` (and
/// automatic mode, which upstream renders as syntax), and the code cells of
/// `--ipynb`; `--head`/`--tail` also cut `--csv` rows.
#[derive(Clone, Debug, Default, PartialEq)]
struct SourceOptions {
    /// `--head/-h LINES`, `--tail/-t LINES` (at least 1).
    head: Option<usize>,
    tail: Option<usize>,
    /// `-n/--line-numbers`.
    line_numbers: bool,
    /// `-g/--guides`: indentation guides.
    guides: bool,
    /// `--lexer LEXER`: the language to highlight as.
    lexer: Option<String>,
    /// `--no-wrap`: crop long source lines, and don't wrap `--print` text.
    no_wrap: bool,
    /// `--infer`: a `--csv` table's column types, inferred from its cells
    /// (`rich_data::infer`), under each heading and aligning the numbers.
    /// Not upstream; without it the table is rich-cli 1.8.1's.
    infer: bool,
}

impl SourceOptions {
    /// Whether any option asks for a `Syntax` view.
    fn wants_syntax(&self) -> bool {
        self.head.is_some()
            || self.tail.is_some()
            || self.line_numbers
            || self.guides
            || self.lexer.is_some()
            || self.no_wrap
    }

    /// Upstream's `_line_range(head, tail, num_lines)`, for `Syntax`'s
    /// `line_range`. `--tail N` keeps upstream's arithmetic,
    /// `(num_lines - tail + 2, num_lines + 1)`, which shows the last `N - 1`
    /// lines: `rich-cli --tail 3` prints two.
    fn line_range(&self, code: &str) -> Result<Option<(i64, i64)>, String> {
        let lines = python_line_count(code) as i64;
        match (self.head, self.tail) {
            (Some(_), Some(_)) => Err("cannot specify both head and tail".into()),
            (Some(head), None) => Ok(Some((1, head as i64))),
            (None, Some(tail)) => Ok(Some((lines - tail as i64 + 2, lines + 1))),
            (None, None) => Ok(None),
        }
    }

    /// `Syntax` as upstream's CLI builds it.
    fn syntax(&self, code: &str, language: &str) -> Result<Syntax, String> {
        let mut syntax = Syntax::new(code, self.lexer.as_deref().unwrap_or(language))
            .line_numbers(self.line_numbers)
            .indent_guides(self.guides)
            .word_wrap(!self.no_wrap);
        if let Some((start, end)) = self.line_range(code)? {
            syntax = syntax.line_range(Some(start), Some(end));
        }
        Ok(syntax)
    }
}

/// `len(text.splitlines())`, which upstream's `num_lines` is: Python also
/// ends a line at `\r`, `\v`, `\f`, `\x1c`–`\x1e`, `\x85`, U+2028 and
/// U+2029, where `str::lines` ends one only at `\n`.
fn python_line_count(text: &str) -> usize {
    let mut count = 0;
    let mut chars = text.chars().peekable();
    let mut open = false;
    while let Some(c) = chars.next() {
        match c {
            '\r' => {
                if chars.peek() == Some(&'\n') {
                    chars.next();
                }
                count += 1;
                open = false;
            }
            '\n' | '\u{b}' | '\u{c}' | '\u{1c}' | '\u{1d}' | '\u{1e}' | '\u{85}' | '\u{2028}'
            | '\u{2029}' => {
                count += 1;
                open = false;
            }
            _ => open = true,
        }
    }
    count + usize::from(open)
}

/// Parsed command line.
#[derive(Clone)]
struct Cli {
    mode: Mode,
    resource: Option<String>,
    /// Every positional argument. Only `--gif` accepts more than one (so
    /// several animations can share the screen); other modes reject extras.
    /// Read only by the GIF player, hence unused without the `art` feature.
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    resources: Vec<String>,
    /// `--loop N`: how many times `--gif` repeats (0 = forever).
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    loops: Option<usize>,
    /// `--speed`, `--fps`, `--max-frames`, `--max-duration`: `--gif` playback.
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    animation: animation::AnimationControls,
    /// `--threshold PCT`: with `--diff`, exit non-zero when the changed
    /// percentage of the canvas exceeds this. Makes the tool a CI gate.
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    diff_threshold: Option<f32>,
    /// `--image-mode`: how `--diff`/`--image` draws its picture.
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_mode: ImageMode,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_fit: Option<String>,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_anchor: Option<String>,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_background: Option<ImageBackdrop>,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_color: Option<String>,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_dither: Option<String>,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_color_distance: Option<String>,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_rotate: Option<u16>,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_flip_horizontal: bool,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_flip_vertical: bool,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_grayscale: bool,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_max_width: Option<usize>,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_max_height: Option<usize>,
    /// `--image-brightness`, `--image-contrast`, `--image-gamma` (1.0 = unchanged).
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_brightness: Option<f32>,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_contrast: Option<f32>,
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    image_gamma: Option<f32>,
    log_presentation: String,
    /// `--mermaid-backend`: how Mermaid diagrams are drawn; `None` when not
    /// given (see [`MermaidBackend`]).
    mermaid_backend: Option<MermaidBackend>,
    /// `--dot-backend`: how DOT graphs are drawn and exported; `None` when
    /// not given (see [`sources::DotBackend`]).
    dot_backend: Option<sources::DotBackend>,
    /// `rich deps` options: `--metadata`, `--why`, `--graph`, `--depth`, …
    graph_sources: sources::GraphSourceOptions,
    /// `rich chart` options: `--kind`, `--x`, `--y`.
    chart: chart::ChartOptions,
    /// `rich schema` options: `--er`.
    schema: sources::SchemaOptions,
    /// `rich profile` options: `--sample`, `--columns`, `--top`.
    profile: profile::ProfileOptions,
    /// `--style-rule` and `--rules` (and a config's `[[rules]]`): conditional
    /// styles for `--csv`, `rich profile` and `rich inspect --table`.
    rules: style_rules::RuleOptions,
    /// `--highlighter NAME`: the console-wide code highlighter.
    highlighter: Option<String>,
    /// `--code-theme NAME`: a theme of the chosen code highlighter.
    code_theme: Option<String>,
    /// `--plugin PATH` (and a trusted config's `plugins`): runtime plugins to
    /// load, in order.
    plugins: Vec<String>,
    /// `--micro-project` (and a trusted config's `micro_project`): load the
    /// project's `.rich/micro/` micro assets.
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    micro_project: bool,
    theme_styles: std::collections::BTreeMap<String, Style>,
    /// `--theme-file PATH`: styles from an upstream `[styles]` theme file,
    /// layered under config themes and `--theme-style`.
    theme_file_styles: std::collections::BTreeMap<String, Style>,
    /// `--height N`: with `--image`, render this many rows instead of the
    /// backend's default.
    #[cfg_attr(not(feature = "art"), allow(dead_code))]
    height: Option<usize>,
    extensions: CliExtensions,
    width: Option<usize>,
    justify: Option<Justify>,
    /// `-L`/`-R`/`-C`/`-F` (`--text-left`, …): the justify of `--print` and
    /// `--rule` text, as distinct from `--left`/`--right`/`--center`, which
    /// align the whole output.
    text_justify: Option<Justify>,
    /// `--emoji`/`-j`… upstream's `-j`: replace `:emoji:` codes. Upstream's
    /// console has `emoji=False` unless given.
    emoji: bool,
    /// `--soft`: print with `soft_wrap=True`.
    soft: bool,
    /// `-W/--max-width`: `console.print(width=…)`.
    max_width: Option<usize>,
    /// `--rule-style`, `--rule-char`: the `--rule` line.
    rule_style: Option<Style>,
    rule_char: Option<String>,
    /// `--force-terminal`: `Console(force_terminal=True)`.
    force_terminal: bool,
    /// `--head`/`--tail`, `-n`, `-g`, `--lexer`, `--no-wrap`.
    source: SourceOptions,
    no_color: bool,
    /// `--export-html PATH` (`-o PATH`): also write a self-contained HTML
    /// document to PATH. The resource is still rendered to the terminal.
    export_html: Option<String>,
    /// `--export-svg PATH`: also write a self-contained SVG document to PATH.
    export_svg: Option<String>,
    /// `--export-png PATH`: also write a PNG image of the output to PATH
    /// (rs-rich-record's rasteriser, the `png` feature; #723).
    export_png: Option<String>,
    /// `--panel BOX`: wrap the output in a [`Panel`] with the named box.
    /// `--panel none` is upstream's default and means *no panel at all*, so it
    /// parses to `None` rather than to `box.NONE`.
    panel: Option<BoxSet>,
    /// `--padding T[,R[,B,L]]`: wrap the output in [`Padding`].
    padding: Option<(usize, usize, usize, usize)>,
    /// `--title`: the panel title, and the CSV table's title.
    title: Option<String>,
    /// `--caption`: the panel subtitle, and the CSV table's caption.
    caption: Option<String>,
    /// `-S/--panel-style`: the panel *border* style.
    panel_style: Option<Style>,
    /// `-s/--style`: a style laid under the whole renderable (upstream's
    /// `Styled`), applied outside the panel.
    style: Option<Style>,
    /// `-e/--expand`: make `--panel`/`--padding` fill the available width
    /// instead of shrinking to their content. Implied by `--width`.
    expand: bool,
    /// `--pager`: page the output through the system pager.
    pager: bool,
    auto_pager: bool,
    /// `-y/--hyperlinks`: render a Markdown link as an OSC 8 hyperlink.
    /// Upstream's flag, and upstream's default of **false** — see
    /// [`build_markdown`], which is where it is consumed.
    hyperlinks: bool,
    /// `--sanitize`: visibly neutralize terminal controls from input and labels.
    sanitize: bool,
    /// `--report json`: emit a stable result/error envelope to stderr while
    /// leaving stdout for rendered content.
    report_format: ReportFormat,
    /// Re-render a changing local file or URL while stdout is a terminal.
    watch: bool,
    /// Polling interval for `--watch`, in seconds.
    watch_interval: f64,
    /// Avoid emitting unchanged URL responses.
    watch_cache: bool,
    /// Quiet period, in seconds, that collapses a burst of file events into
    /// one re-render (`--watch-debounce`).
    watch_debounce: f64,
    /// `--watch-poll`: skip file events and poll local files at the interval.
    watch_poll: bool,
    /// `--watch-exit-on-error`: end the watch non-zero when a render fails.
    watch_exit_on_error: bool,
    batch: bool,
    progress: bool,
    continue_on_error: bool,
    jobs: usize,
    dry_run: bool,
    batch_paths: batch_paths::BatchPathOptions,
    worker_args: Vec<String>,
    overwrite: bool,
    collision: CollisionPolicy,
    data: inspect::DataOptions,
    tools: tools::ToolOptions,
    viewers: viewers::ViewerOptions,
    /// `rich log`'s filters, follow mode, groups and live view.
    logs: logs::LogOptions,
}

/// `--mermaid-backend`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum MermaidBackend {
    /// Flowcharts, sequence and ER diagrams as text; other diagrams as
    /// source. The default for fences.
    Text,
    /// Mermaid's own CLI first (the `mmdc` feature). The default for
    /// `rich mermaid` in a build that has it.
    Mmdc,
    /// Markdown fences stay code blocks, as upstream renders them.
    Off,
}

impl MermaidBackend {
    fn parse(value: &str) -> Result<Self, String> {
        match value {
            "text" => Ok(Self::Text),
            "off" => Ok(Self::Off),
            "mmdc" if cfg!(feature = "mmdc") => Ok(Self::Mmdc),
            "mmdc" => Err(
                "--mermaid-backend mmdc needs a build with the mmdc feature \
                 (cargo install rs-rich-cli --features mmdc)"
                    .into(),
            ),
            other => Err(format!(
                "unknown Mermaid backend {other:?} (text, mmdc, off)"
            )),
        }
    }
}

/// Mermaid options for a backend.
#[cfg(feature = "mermaid")]
fn mermaid_options(backend: MermaidBackend) -> rich_mermaid::MermaidOptions {
    rich_mermaid::MermaidOptions {
        backend: match backend {
            MermaidBackend::Mmdc => rich_mermaid::Backend::Mmdc,
            MermaidBackend::Text | MermaidBackend::Off => rich_mermaid::Backend::Text,
        },
        ..rich_mermaid::MermaidOptions::default()
    }
}

/// The CLI's plugin registry: [`builtin_registry`], then the linked plugins
/// and the runtime plugins `--plugin` loaded (see [`plugins`]).
fn plugin_registry(mermaid: MermaidBackend) -> rich_ext::ExtensionRegistry {
    plugin_registry_with(mermaid, true)
}

/// [`plugin_registry`], leaving out the DOT plugin when `dot` is false
/// (`--dot-backend off`).
fn plugin_registry_with(mermaid: MermaidBackend, dot: bool) -> rich_ext::ExtensionRegistry {
    let mut registry = builtin_registry(mermaid, dot);
    plugins::add_to(&mut registry);
    registry
}

/// The built-in plugins: rich-ext's, DOT, and Mermaid and lumis where
/// compiled in.
fn builtin_registry(mermaid: MermaidBackend, dot: bool) -> rich_ext::ExtensionRegistry {
    let mut registry = rich_ext::ExtensionRegistry::with_defaults();
    if dot {
        registry
            .add_plugin(&rich_diagram::plugin::DotPlugin::default())
            .expect("the DOT plugin registers cleanly");
    }
    #[cfg(feature = "mermaid")]
    if mermaid != MermaidBackend::Off {
        registry
            .add_plugin(&rich_mermaid::MermaidPlugin::new(mermaid_options(mermaid)))
            .expect("the Mermaid plugin registers cleanly");
    }
    #[cfg(not(feature = "mermaid"))]
    let _ = mermaid;
    #[cfg(feature = "lumis")]
    registry
        .add_plugin(&rich_lumis::LumisPlugin)
        .expect("the lumis plugin registers cleanly");
    registry
}

/// The console-wide code highlighting `--highlighter` and `--code-theme`
/// choose; `None` when neither is given, which leaves every console on the
/// default syntect highlighter and its default theme.
fn code_highlighting(
    highlighter: Option<&str>,
    theme: Option<&str>,
) -> Result<Option<rich::CodeHighlighting>, String> {
    if highlighter.is_none() && theme.is_none() {
        return Ok(None);
    }
    let mut registry = plugin_registry(MermaidBackend::Off);
    let name = highlighter.unwrap_or("syntect");
    if let Err(error) = registry.set_default_code_highlighter(name, theme) {
        return Err(match error {
            rich_ext::HighlighterChoiceError::UnknownHighlighter { .. }
                if name == "lumis" && !cfg!(feature = "lumis") =>
            {
                format!(
                    "{error} (lumis needs a build with the lumis feature: cargo install \
                     rs-rich-cli --features lumis)"
                )
            }
            rich_ext::HighlighterChoiceError::UnknownTheme { .. } => {
                let themes = registry
                    .code_highlighter(name)
                    .map(|engine| engine.themes())
                    .unwrap_or_default();
                if themes.len() <= 40 {
                    format!("{error}; its themes: {}", themes.join(", "))
                } else {
                    format!(
                        "{error}; it has {} themes, such as {}; `rich doctor --report json` \
                         lists them all",
                        themes.len(),
                        themes[..12].join(", ")
                    )
                }
            }
            other => other.to_string(),
        });
    }
    Ok(registry.code_highlighting())
}

/// rich-ext's default code highlighting (syntect) for a console that renders
/// a resource, without rich-ext's example number highlighter.
///
/// Upstream rich-cli highlights with rich's `ReprHighlighter` alone. The
/// number highlighter painted every run of digits a fixed bold cyan over it,
/// so digits upstream leaves plain (`abc123`) came out cyan, and a theme's
/// `repr.number` could not take the colour away: `--theme-style
/// repr.number=bold` kept the digits cyan, where upstream's theme replaces
/// the style and they render bold alone.
fn install_render_defaults(console: &mut Console) {
    use rich::ConsoleCodeHighlighting;
    if let Some(highlighting) = rich_ext::ExtensionRegistry::with_defaults().code_highlighting() {
        console.set_code_highlighting(Some(highlighting));
    }
}

/// Give `console` the code highlighting `cli` chose (parsing checked it).
fn apply_code_highlighting(console: &mut Console, cli: &Cli) {
    use rich::ConsoleCodeHighlighting;
    if let Ok(Some(highlighting)) =
        code_highlighting(cli.highlighter.as_deref(), cli.code_theme.as_deref())
    {
        console.set_code_highlighting(Some(highlighting));
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum CollisionPolicy {
    Error,
    Overwrite,
    Suffix,
}

/// Build the `-m/--markdown` renderable, honouring `-y/--hyperlinks`.
///
/// Upstream is `Markdown(markdown_data, code_theme=theme, hyperlinks=hyperlinks)`
/// with `@click.option("--hyperlinks", "-y", is_flag=True)`, so the default is
/// **false**: `rich -m` renders `[text](url)` as `text (url)`, with the URL
/// visible, and only `-y` turns it into an OSC 8 hyperlink whose target the
/// reader cannot see.
///
/// Without this, `rich -m` emitted the OSC 8 rendering unconditionally and the
/// destination appeared nowhere in the byte stream — so every URL in a document
/// was unrecoverable as soon as the output was piped or `NO_COLOR` was set.
fn build_markdown(source: &str, hyperlinks: bool) -> Markdown {
    Markdown::new(source).hyperlinks(hyperlinks)
}

/// Run the `rich` command line with `args` (the arguments after the program
/// name) and return its exit status. The `rich` binary's `main` is only this.
///
/// This library target exists for the Python wheel (`crates/rich-py`), which
/// runs the CLI in-process through [`run_embedded`]; it is not a supported
/// Rust API, and everything else in it is private. Output goes to the
/// process's real stdout and stderr and input comes from its stdin; some modes
/// (`--batch`, `--watch`, the demo) install a process-wide Ctrl-C handler, and
/// a few error paths end the process.
///
/// Arguments that are not valid Unicode are parsed by their escaped
/// spelling (see [`path_arg`]), and a file named by one is opened by its
/// original bytes (see [`fs_path`]), as upstream's click does through
/// `surrogateescape`; text such as `--print`'s shows lossily ([`text_arg`]).
pub fn run(args: Vec<std::ffi::OsString>) -> ExitCode {
    dispatch(remember_raw_args(args))
}

/// Paths and arguments that were not valid Unicode, by their escaped
/// spelling ([`escaped_path`]); `None` when two different ones share one
/// spelling (which then cannot say which it was).
static RAW_ARGS: std::sync::Mutex<Vec<(String, Option<std::ffi::OsString>)>> =
    std::sync::Mutex::new(Vec::new());

/// The arguments as `String`s for the parser, keeping the originals of any
/// that are not valid Unicode for [`fs_path`].
///
/// Such an argument is spelled as [`path_arg`] spells a path, after a NUL
/// that no argument can contain, never by its lossy spelling: `\xff.txt`
/// and a real `\u{fffd}.txt` share that one, so `rich $'\xff.txt'
/// --export-html \u{fffd}.txt` resolved the export to the input and
/// overwrote it.
fn remember_raw_args(args: Vec<std::ffi::OsString>) -> Vec<String> {
    let mut raw: Vec<(String, Option<std::ffi::OsString>)> = Vec::new();
    let args = args
        .into_iter()
        .map(|arg| match arg.into_string() {
            Ok(arg) => arg,
            Err(arg) => {
                let spelling = escaped_path(&arg);
                match raw.iter_mut().find(|(known, _)| *known == spelling) {
                    Some((_, original)) if original.as_ref() != Some(&arg) => *original = None,
                    Some(_) => {}
                    None => raw.push((spelling.clone(), Some(arg))),
                }
                spelling
            }
        })
        .collect();
    if let Ok(mut slot) = RAW_ARGS.lock() {
        *slot = raw;
    }
    args
}

/// The file system path an argument names: the original bytes when it was
/// not valid Unicode (so `rich $'\xff.txt'` opens that file, not
/// `\u{fffd}.txt`), else the argument itself.
pub(crate) fn fs_path(arg: &str) -> std::path::PathBuf {
    RAW_ARGS
        .lock()
        .ok()
        .and_then(|raw| {
            raw.iter()
                .find(|(spelling, _)| spelling == arg)
                .and_then(|(_, original)| original.clone())
        })
        .map_or_else(|| std::path::PathBuf::from(arg), std::path::PathBuf::from)
}

/// An argument used as text rather than a path (`--print`'s text, a
/// `--title`): an escaped spelling of one that was not valid Unicode shows
/// lossily, as the text it was meant to be.
pub(crate) fn text_arg(arg: &str) -> String {
    if !arg.starts_with('\0') {
        return arg.to_string();
    }
    RAW_ARGS
        .lock()
        .ok()
        .and_then(|raw| {
            raw.iter()
                .find(|(spelling, _)| spelling == arg)
                .and_then(|(_, original)| original.clone())
        })
        .map_or_else(
            || arg.to_string(),
            |original| original.to_string_lossy().into_owned(),
        )
}

/// A path as the `String` the rest of the CLI passes around. A path that is
/// not valid Unicode (a file found by a batch glob, a planned output named
/// after one) is spelled with each invalid byte as `\xNN` (and each `\` as
/// `\x5C`, so no two such paths share a spelling), after a NUL, which no
/// path or argument can contain, so the spelling never names another file.
/// It is remembered, so [`fs_path`] gives the original back wherever the
/// spelling reaches the file system.
pub(crate) fn path_arg(path: &Path) -> String {
    if let Some(text) = path.to_str() {
        return text.to_string();
    }
    let spelling = escaped_path(path.as_os_str());
    if let Ok(mut raw) = RAW_ARGS.lock() {
        let original = path.as_os_str().to_owned();
        match raw.iter_mut().find(|(known, _)| *known == spelling) {
            Some((_, known)) if known.as_ref() != Some(&original) => *known = None,
            Some(_) => {}
            None => raw.push((spelling.clone(), Some(original))),
        }
    }
    spelling
}

/// A NUL, then the Unicode parts of `path` with `\` as `\x5C`, and each
/// other byte as `\xNN`.
#[cfg(unix)]
fn escaped_path(path: &std::ffi::OsStr) -> String {
    use std::os::unix::ffi::OsStrExt;
    let mut out = String::from('\0');
    for chunk in path.as_bytes().utf8_chunks() {
        out.push_str(&chunk.valid().replace('\\', "\\x5C"));
        for byte in chunk.invalid() {
            out.push_str(&format!("\\x{byte:02X}"));
        }
    }
    out
}

#[cfg(not(unix))]
fn escaped_path(path: &std::ffi::OsStr) -> String {
    format!("\0{}", path.to_string_lossy())
}

/// [`run`] for a host process that is not the `rich` executable: `program` is
/// the command that starts this CLI again (for the Python wheel,
/// `[sys.executable, "-m", "rs_rich"]`), used for `--batch` workers and the
/// demo's child `--watch`, where the binary runs its own executable. An empty
/// `program` means the current executable, as in [`run`].
///
/// A host may call this from several threads at once (the wheel releases the
/// GIL), but a run's plugins, program and colour settings are process-wide:
/// runs take turns, each whole, so one never clears another's plugins.
pub fn run_embedded(program: Vec<std::ffi::OsString>, args: Vec<std::ffi::OsString>) -> ExitCode {
    // A run that panicked left nothing half-set that the next run does not
    // reset first, so a poisoned lock is still usable.
    let _turn = EMBEDDED_RUN.lock().unwrap_or_else(|e| e.into_inner());
    if let Ok(mut slot) = SELF_PROGRAM.lock() {
        *slot = program;
    }
    IN_HOST.store(true, std::sync::atomic::Ordering::SeqCst);
    let code = run(args);
    IN_HOST.store(false, std::sync::atomic::Ordering::SeqCst);
    code
}

/// Held for the whole of one [`run_embedded`] call.
static EMBEDDED_RUN: std::sync::Mutex<()> = std::sync::Mutex::new(());

/// Set while [`run_embedded`] runs a command line in a host process.
static IN_HOST: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

/// Whether this run is inside a host process ([`run_embedded`]), whose
/// process-wide state (its Ctrl+C handling) a command must leave alone.
pub(crate) fn in_host() -> bool {
    IN_HOST.load(std::sync::atomic::Ordering::SeqCst)
}

/// The command [`run_embedded`] was given; empty for the binary.
static SELF_PROGRAM: std::sync::Mutex<Vec<std::ffi::OsString>> = std::sync::Mutex::new(Vec::new());

fn dispatch(args: Vec<String>) -> ExitCode {
    // An in-process host (`run_embedded`, the Python wheel) runs many
    // command lines: a run's plugins are only the ones it names.
    plugins::install(Vec::new());
    if demo::requested(&args) {
        return demo::dispatch(&args);
    }
    if doctor::requested(&args) {
        return doctor::dispatch(&args);
    }
    if plugins::requested(&args) {
        return plugins::dispatch(&args);
    }
    if marketplace::requested(&args) {
        return marketplace::dispatch(&args);
    }
    #[cfg(feature = "art")]
    if banner::requested(&args) {
        return banner::dispatch(&args);
    }
    if shell::requested(&args) {
        return shell::dispatch(&args);
    }
    if spin::requested(&args) {
        return spin::dispatch(&args);
    }
    if console::requested(&args) {
        return console::dispatch(&args);
    }
    #[cfg(feature = "art")]
    if micro::requested(&args) {
        return micro::dispatch(&args);
    }
    #[cfg(feature = "interact")]
    if let Some(command) = interactive::requested(&args) {
        return interactive::dispatch(command, &args);
    }
    #[cfg(feature = "interact")]
    if let Some(command) = approve_jump::requested(&args) {
        return approve_jump::dispatch(command, &args);
    }
    #[cfg(feature = "record")]
    if record::requested(&args) {
        return record::dispatch(&args);
    }
    #[cfg(feature = "serve")]
    if serve::requested(&args) {
        return serve::dispatch(&args);
    }
    match parse(&args) {
        Ok(None) => ExitCode::SUCCESS, // help/version already printed
        Ok(Some(cli)) => {
            if let Err(message) = plugins::check_linked() {
                return fail(&cli, ExitClass::Usage, message);
            }
            // `--plugin` paths, then the installed plugins (`rich plugin`).
            if !cli.plugins.is_empty() || marketplace::has_installed() {
                match plugins::load(&cli.plugins) {
                    Ok(loaded) => plugins::install(loaded),
                    Err((class, message)) => return fail(&cli, class, message),
                }
            }
            // `--transform` names are known once plugins are loaded.
            if let Some(message) = cli
                .data
                .unknown_transform(&plugin_registry(MermaidBackend::Text))
            {
                return fail(&cli, ExitClass::Usage, message);
            }
            if cli.batch && cfg!(target_os = "wasi") {
                return fail(&cli, ExitClass::Usage, host::unavailable("--batch"));
            }
            if cli.batch
                && let Err(error) = batch::install_interrupt_handler()
            {
                return fail(
                    &cli,
                    ExitClass::Input,
                    format!("cannot install batch interruption handler: {error}"),
                );
            }
            run_cli(cli)
        }
        Err(message) => emit_error(
            wants_json_report(&args),
            ExitClass::Usage,
            &format!("{message} (try --help)"),
        ),
    }
}

/// A command that runs this CLI again: a `--batch` worker, or the demo's
/// child `--watch`. In the `rich` binary that is the current executable; under
/// [`run_embedded`] it is the host's command.
fn self_command() -> std::io::Result<std::process::Command> {
    let program = SELF_PROGRAM
        .lock()
        .map(|program| program.clone())
        .unwrap_or_default();
    Ok(match program.split_first() {
        Some((executable, rest)) => {
            let mut command = std::process::Command::new(executable);
            command.args(rest);
            command
        }
        None => std::process::Command::new(std::env::current_exe()?),
    })
}

/// Options that consume the following argument as their value. Needed to tell a
/// positional subcommand from an option's value when scanning raw arguments.
const VALUE_OPTIONS: &[&str] = &[
    "--batch-input-root",
    "--batch-name-template",
    "--log-presentation",
    "--level",
    "--where",
    "--parser",
    "--time",
    "--output",
    "--mermaid-backend",
    "--dot-backend",
    "--metadata",
    "--why",
    "--package",
    "--timings",
    "--audit",
    "--build-profile",
    "--baseline",
    "--save",
    "--policy",
    "--sbom",
    "--depth",
    "--kind",
    "--x",
    "--y",
    "--sample",
    "--columns",
    "--top",
    "--max-paths",
    "--style-rule",
    "--rules",
    "--highlighter",
    "--code-theme",
    "--plugin",
    "-w",
    "--width",
    "-o",
    "--export-html",
    "--export-svg",
    "--export-png",
    "-a",
    "--panel",
    "-d",
    "--padding",
    "-h",
    "--head",
    "-t",
    "--tail",
    "--lexer",
    "-W",
    "--max-width",
    "--rule-style",
    "--rule-char",
    "--title",
    "--caption",
    "-s",
    "--style",
    "-S",
    "--panel-style",
    "--report",
    "--image-mode",
    "--image-fit",
    "--image-anchor",
    "--image-background",
    "--height",
    "--theme",
    "--theme-style",
    "--theme-file",
    "--image-color",
    "--image-dither",
    "--image-color-distance",
    "--image-rotate",
    "--image-max-width",
    "--image-max-height",
    "--image-brightness",
    "--image-contrast",
    "--image-gamma",
    "--demo-section",
    "--demo-delay",
    "--watch-interval",
    "--interval",
    "--watch-debounce",
    "--gif-mode",
    "--encoding",
    "--threshold",
    "--loop",
    "--speed",
    "--fps",
    "--max-frames",
    "--max-duration",
    "--jobs",
    "--collision",
    "--format",
    "--select",
    "--filter",
    "--highlight",
    "--transform",
    "--find",
    "--max-depth",
    "--max-length",
    "--compare",
    "--context",
    "--language",
    "--search",
    "--offset",
    "--length",
    "--bytes-per-line",
    "--group",
    "--limit",
    "--cast",
    "--redact-pattern",
    "--config",
    "--profile",
];

/// Whether the command line already picks a render mode, by flag *or* by the
/// positional subcommand form. Config must not inject a `mode` default over
/// `rich json file.json`, which selects JSON without ever naming `--json`.
fn selects_mode_explicitly(args: &[String]) -> bool {
    explicit_mode(args).is_some()
}

/// The render mode the command line picks by flag or subcommand, if any.
fn explicit_mode(args: &[String]) -> Option<Mode> {
    let mut iter = args.iter();
    let mut seen_positional = false;
    while let Some(arg) = iter.next() {
        if arg == "--" {
            break;
        }
        if VALUE_OPTIONS.contains(&arg.as_str()) {
            iter.next();
            continue;
        }
        if arg.starts_with('-') && arg.len() > 1 {
            if let Some(flag) = mode_flag_alias(arg) {
                return command_mode(&flag[2..]);
            }
            continue;
        }
        if !seen_positional {
            seen_positional = true;
            if let Some(mode) = command_mode(arg) {
                return Some(mode);
            }
        }
    }
    None
}

/// The command word (`hex`, `view`, …) the command line starts with, if its
/// first positional is one.
fn command_word(args: &[String]) -> Option<&str> {
    let mut iter = args.iter();
    while let Some(arg) = iter.next() {
        if arg == "--" {
            return None;
        }
        if VALUE_OPTIONS.contains(&arg.as_str()) {
            iter.next();
        } else if !arg.starts_with('-') || arg == "-" {
            return command_mode(arg).map(|_| arg.as_str());
        }
    }
    None
}

/// The first positional word, when it can name a subcommand (`plugins`,
/// `doctor`, `record`, `choose`, `bench`, …): never after `--`, and never
/// once a render-mode flag came before it, which makes the word a resource
/// (`rich -p plugins` prints "plugins"). Every subcommand scanner uses this,
/// so they agree with each other and with [`parse`].
pub(crate) fn subcommand_word(args: &[String]) -> Option<&str> {
    let mut iter = args.iter();
    while let Some(arg) = iter.next() {
        if arg == "--" || mode_flag_alias(arg).is_some() {
            return None;
        }
        if VALUE_OPTIONS.contains(&arg.as_str()) {
            iter.next();
        } else if !arg.starts_with('-') || arg == "-" {
            return Some(arg);
        }
    }
    None
}

/// The canonical long flag for a render-mode option, or `None` for anything else.
fn mode_flag_alias(arg: &str) -> Option<&'static str> {
    Some(match arg {
        "--print" | "-p" => "--print",
        "--markdown" | "-m" => "--markdown",
        "--json" | "-j" | "-J" => "--json",
        "--syntax" | "-x" => "--syntax",
        "--csv" => "--csv",
        "--ipynb" => "--ipynb",
        "--rst" => "--rst",
        "--org" => "--org",
        "--asciidoc" | "--adoc" => "--asciidoc",
        "--man" | "--roff" => "--man",
        "--jsonl" | "--ndjson" => "--jsonl",
        "--log" => "--log",
        "--rule" | "-u" => "--rule",
        "--image" => "--image",
        "--gif" => "--gif",
        "--diff" => "--diff",
        "--inspect" => "--inspect",
        "--ansi-explain" => "--ansi-explain",
        _ => return None,
    })
}

fn emit_error(json: bool, class: ExitClass, message: &str) -> ExitCode {
    // Messages quote paths and other input, which may carry terminal controls
    // (a file named `x\e]0;title\a.txt`): show them, never execute them.
    let message = &controls::shown(message);
    if json {
        eprintln!(
            "{}",
            serde_json::json!({
                "ok": false,
                "code": class.name(),
                "exit_code": class.code(),
                "message": message,
                "error": {
                    "message": message,
                },
            })
        );
    } else {
        eprintln!("rich: {message}");
    }
    class.exit_code()
}

fn emit_success_report(format: ReportFormat) {
    if format == ReportFormat::Json {
        eprintln!(
            "{}",
            serde_json::json!({
                "ok": true,
                "code": ExitClass::Success.name(),
                "exit_code": ExitClass::Success.code(),
                "result": {},
            })
        );
    }
}

fn fail(cli: &Cli, class: ExitClass, message: impl AsRef<str>) -> ExitCode {
    let message = controls::shown(message.as_ref());
    // A watched resource's live region shows its own error.
    if watch::capture_error(&message) {
        return class.exit_code();
    }
    emit_error(cli.report_format == ReportFormat::Json, class, &message)
}

fn success(cli: &Cli) -> ExitCode {
    if !watch::capturing() {
        emit_success_report(cli.report_format);
    }
    ExitClass::Success.exit_code()
}

/// Match `text` against a simple glob supporting `*` (any run of characters)
/// and `?` (exactly one). Both apply within a single path segment.
///
/// Substring containment is not a glob: `*.md` used that way also matched
/// `notes.md.bak`, and a `?` pattern matched nothing at all because the literal
/// `?` was still being searched for.
#[cfg(test)]
fn glob_match(pattern: &str, text: &str) -> bool {
    let pattern: Vec<GlobUnit> = pattern.chars().map(GlobUnit::Char).collect();
    let text: Vec<GlobUnit> = text.chars().map(GlobUnit::Char).collect();
    glob_match_units(&pattern, &text)
}

/// One unit a glob matches: a character, or a byte of a name that is not
/// valid Unicode, which `?` matches alone and nothing else stands for.
#[derive(Clone, Copy, PartialEq, Eq)]
enum GlobUnit {
    Char(char),
    // Only Unix names are bytes; elsewhere (Windows, WASI) they are text.
    #[cfg_attr(not(unix), allow(dead_code))]
    Byte(u8),
}

/// A file name's units, from its bytes where it is not valid Unicode:
/// matching its lossy spelling let `a\xff*` match `a\xfe.txt`.
fn glob_units(name: &std::ffi::OsStr) -> Vec<GlobUnit> {
    #[cfg(unix)]
    {
        use std::os::unix::ffi::OsStrExt;
        let mut units = Vec::new();
        for chunk in name.as_bytes().utf8_chunks() {
            units.extend(chunk.valid().chars().map(GlobUnit::Char));
            units.extend(chunk.invalid().iter().map(|&byte| GlobUnit::Byte(byte)));
        }
        units
    }
    #[cfg(not(unix))]
    {
        name.to_string_lossy().chars().map(GlobUnit::Char).collect()
    }
}

fn glob_match_units(pattern: &[GlobUnit], text: &[GlobUnit]) -> bool {
    const ANY: GlobUnit = GlobUnit::Char('?');
    const STAR: GlobUnit = GlobUnit::Char('*');
    let (mut p, mut t) = (0usize, 0usize);
    let (mut star, mut retry) = (None, 0usize);
    while t < text.len() {
        if p < pattern.len() && (pattern[p] == ANY || pattern[p] == text[t]) {
            p += 1;
            t += 1;
        } else if p < pattern.len() && pattern[p] == STAR {
            star = Some(p);
            retry = t;
            p += 1;
        } else if let Some(open) = star {
            p = open + 1;
            retry += 1;
            t = retry;
        } else {
            return false;
        }
    }
    while p < pattern.len() && pattern[p] == STAR {
        p += 1;
    }
    p == pattern.len()
}

fn has_glob_meta(value: &str) -> bool {
    value.contains('*') || value.contains('?')
}

/// Split `dir/sub/*.md` into its literal directory and its name pattern.
fn split_glob(resource: &str) -> (PathBuf, String) {
    let meta = resource.find(['*', '?']).unwrap_or(0);
    match resource[..meta].rfind(['/', '\\']) {
        Some(cut) => (
            PathBuf::from(&resource[..cut]),
            resource[cut + 1..].to_string(),
        ),
        None => (PathBuf::from("."), resource.to_string()),
    }
}

/// Collect every file under `dir`, skipping symlinks.
///
/// `Path::is_dir` follows links, so a directory containing a link to itself or
/// to an ancestor pushed that directory back onto the stack forever, building
/// ever longer paths until the process ran out of memory. Not following links
/// at all keeps the walk finite without having to track device/inode identity,
/// which is not portable.
fn collect_files(dir: &Path, out: &mut Vec<String>) -> Result<(), String> {
    let mut stack = vec![dir.to_path_buf()];
    while let Some(current) = stack.pop() {
        batch::check_interrupted()?;
        let entries = std::fs::read_dir(&current)
            .map_err(|error| format!("cannot scan {}: {error}", current.display()))?;
        for entry in entries {
            batch::check_interrupted()?;
            let entry = entry.map_err(|error| format!("cannot scan {}: {error}", dir.display()))?;
            let path = entry.path();
            let kind = std::fs::symlink_metadata(&path)
                .map_err(|error| format!("cannot read {}: {error}", path.display()))?
                .file_type();
            if kind.is_symlink() {
                continue;
            }
            if kind.is_dir() {
                stack.push(path);
            } else if kind.is_file() {
                out.push(path_arg(&path));
            }
        }
    }
    Ok(())
}

fn expand_batch_resources(resources: &[String]) -> Result<Vec<String>, String> {
    let mut out = Vec::new();
    for resource in resources {
        batch::check_interrupted()?;
        if resource == "-" || is_url(resource) {
            return Err("batch resources must be local files or directories".into());
        }
        if has_glob_meta(resource) {
            // A glob that was not valid Unicode is split and matched on its
            // own bytes: only the whole argument's are remembered, and its
            // escaped spelling spells each such byte with a `\`.
            let raw = fs_path(resource);
            let escaped = raw.as_os_str() != std::ffi::OsStr::new(resource);
            let (dir, pattern) = if escaped {
                let parent = raw.parent().unwrap_or(Path::new(""));
                if has_glob_meta(&parent.to_string_lossy()) {
                    return Err(format!(
                        "batch glob {} may only use * and ? in the final path segment",
                        controls::shown(resource)
                    ));
                }
                let dir = if parent.as_os_str().is_empty() {
                    PathBuf::from(".")
                } else {
                    parent.to_path_buf()
                };
                (dir, glob_units(raw.file_name().unwrap_or_default()))
            } else {
                let (dir, pattern) = split_glob(resource);
                if pattern.contains('/') || pattern.contains('\\') {
                    return Err(format!(
                        "batch glob {resource:?} may only use * and ? in the final path segment"
                    ));
                }
                (dir, pattern.chars().map(GlobUnit::Char).collect())
            };
            let entries = std::fs::read_dir(&dir)
                .map_err(|error| format!("cannot scan {}: {error}", dir.display()))?;
            for entry in entries {
                batch::check_interrupted()?;
                let entry =
                    entry.map_err(|error| format!("cannot scan {}: {error}", dir.display()))?;
                let path = entry.path();
                if !path.is_file() {
                    continue;
                }
                if glob_match_units(&pattern, &glob_units(&entry.file_name())) {
                    out.push(path_arg(&path));
                }
            }
            continue;
        }
        let path = fs_path(resource);
        if path.is_file() {
            out.push(resource.clone());
        } else if path.is_dir() {
            collect_files(&path, &mut out)?;
        } else {
            return Err(format!("batch resource does not exist: {resource}"));
        }
    }
    batch::check_interrupted()?;
    out.sort();
    out.dedup();
    batch::check_interrupted()?;
    if out.is_empty() {
        return Err("batch plan contains no files".into());
    }
    Ok(out)
}

/// Where one batch item's exports are written.
///
/// The kind of each export is carried explicitly. Recovering it by sniffing the
/// path extension silently dropped exports whose name did not end in `.html` or
/// `.svg`, so `--export-html result.out` planned a path and then wrote nothing.
#[derive(Default, Clone)]
struct BatchOutputs {
    html: Option<String>,
    svg: Option<String>,
}

fn batch_export_path(
    path: Option<&str>,
    input: &str,
    index: usize,
    total: usize,
) -> Option<String> {
    let path = path?;
    if total == 1 {
        return Some(path.into());
    }
    let p = fs_path(path);
    // The input's stem as its bytes: a non-Unicode name keeps them.
    let input = fs_path(input);
    let stem = input
        .file_stem()
        .unwrap_or_else(|| std::ffi::OsStr::new("output"));
    let mut name = stem.to_owned();
    match p.extension() {
        Some(ext) if !ext.is_empty() => {
            name.push(".");
            name.push(ext);
        }
        _ => name.push(format!("-{index}")),
    }
    Some(path_arg(&if p.is_dir() {
        p.join(name)
    } else {
        p.with_file_name(name)
    }))
}

/// `out.html` -> `out-2.html`, keeping an extension-less name intact.
fn suffixed_path(path: &Path, suffix: usize) -> String {
    let mut name = path
        .file_stem()
        .unwrap_or_else(|| std::ffi::OsStr::new("output"))
        .to_owned();
    name.push(format!("-{suffix}"));
    if let Some(ext) = path.extension() {
        name.push(".");
        name.push(ext);
    }
    path_arg(&path.with_file_name(name))
}

/// Settle one planned output against the rest of the plan and against the disk.
///
/// `suffix` has to consider existing files too, not just in-plan duplicates:
/// a policy whose whole purpose is to avoid clobbering must not quietly
/// overwrite a file that was already there.
fn resolve_destination(
    cli: &Cli,
    candidate: String,
    taken: &mut std::collections::BTreeSet<String>,
) -> Result<String, (ExitClass, String)> {
    let occupied = |path: &str, taken: &std::collections::BTreeSet<String>| {
        taken.contains(path) || (!cli.overwrite && fs_path(path).exists())
    };
    match cli.collision {
        CollisionPolicy::Overwrite => {
            taken.insert(candidate.clone());
            Ok(candidate)
        }
        CollisionPolicy::Suffix => {
            let mut chosen = candidate.clone();
            let mut suffix = 2;
            while occupied(&chosen, taken) {
                batch::check_interrupted().map_err(|message| (ExitClass::Input, message))?;
                chosen = suffixed_path(&fs_path(&candidate), suffix);
                suffix += 1;
            }
            taken.insert(chosen.clone());
            Ok(chosen)
        }
        CollisionPolicy::Error => {
            if taken.contains(&candidate) {
                return Err((
                    ExitClass::Usage,
                    format!("batch output collision: {candidate}"),
                ));
            }
            if !cli.overwrite && fs_path(&candidate).exists() {
                return Err((
                    ExitClass::Input,
                    format!("refusing to overwrite existing output: {candidate} (use --overwrite)"),
                ));
            }
            taken.insert(candidate.clone());
            Ok(candidate)
        }
    }
}

/// Run one batch item with its diagnostics captured, yielding its failure class.
/// Reuse resolved rendering flags without re-reading config in batch workers.
fn worker_args(args: &[String]) -> Vec<String> {
    let mut result = vec!["--no-config".into()];
    let mut iter = args.iter();
    let mut seen_resource = false;
    let mut selected_mode = false;
    while let Some(arg) = iter.next() {
        if arg == "--" {
            break;
        }
        if VALUE_OPTIONS.contains(&arg.as_str()) {
            let value = iter.next();
            if !matches!(
                arg.as_str(),
                "--jobs"
                    | "--batch-input-root"
                    | "--batch-name-template"
                    | "--collision"
                    | "--report"
                    | "-o"
                    | "--export-html"
                    | "--export-svg"
                    | "--config"
                    | "--profile"
            ) {
                result.push(arg.clone());
                if let Some(value) = value {
                    result.push(value.clone());
                }
            }
        } else if arg.starts_with('-') && arg != "-" {
            selected_mode |= mode_flag_alias(arg).is_some();
            if !matches!(
                arg.as_str(),
                "--batch"
                    | "--batch-preserve-dirs"
                    | "--no-batch-preserve-dirs"
                    | "--no-batch"
                    | "--dry-run"
                    | "--progress"
                    | "--no-progress"
                    | "--continue-on-error"
                    | "--no-continue-on-error"
                    | "--overwrite"
                    | "--no-overwrite"
                    | "--machine-json"
            ) {
                result.push(arg.clone());
            }
        } else if !seen_resource {
            if let Some(mode) = command_mode(arg).filter(|_| !selected_mode) {
                selected_mode = true;
                result.push(format!("--{}", mode_name(mode)));
            } else {
                seen_resource = true;
            }
        }
    }
    result
}

fn wants_json_report(args: &[String]) -> bool {
    let mut format = ReportFormat::Human;
    let mut iter = args.iter();
    while let Some(arg) = iter.next() {
        match arg.as_str() {
            "--report" => {
                if let Some(value) = iter.next() {
                    let _ = format.apply_option("--report", Some(value));
                }
            }
            "--machine-json" => {
                let _ = format.apply_option("--machine-json", None);
            }
            "--" => break,
            _ => {}
        }
    }
    format == ReportFormat::Json
}

/// Map a `--panel` box name to a box set (port of rich-cli's `BOXES` +
/// `getattr(box, name.upper())`).
///
/// `none` is upstream's *default* for `--panel`, and upstream guards the whole
/// panel step with `if panel != "none"` — so it means "no panel", not "a panel
/// drawn with `box.NONE`". Drawing box.NONE put an invisible one-cell frame and
/// a blank line around the output, which reads as the tool having mangled the
/// file for no reason.
///
/// rich-cli offers six names; this binary takes every box in rich's `box`
/// module (the names `rich asset --kind box` offers), the six first.
fn parse_box(name: &str) -> Result<Option<BoxSet>, String> {
    let name = name.to_ascii_lowercase();
    if name == "none" {
        return Ok(None);
    }
    PANEL_BOXES
        .iter()
        .find(|(known, _)| *known == name)
        .map(|(_, set)| Some(*set))
        .ok_or_else(|| {
            let names: Vec<&str> = PANEL_BOXES.iter().map(|(known, _)| *known).collect();
            format!(
                "unknown panel box {name:?} (use none or {})",
                names.join(", ")
            )
        })
}

/// `--panel` names: rich-cli's six, then the rest of rich's `box` module.
pub(crate) const PANEL_BOXES: &[(&str, BoxSet)] = {
    use rich::r#box as b;
    &[
        ("ascii", b::ASCII),
        ("ascii2", b::ASCII2),
        ("square", b::SQUARE),
        ("rounded", b::ROUNDED),
        ("heavy", b::HEAVY),
        ("double", b::DOUBLE),
        ("ascii_double_head", b::ASCII_DOUBLE_HEAD),
        ("square_double_head", b::SQUARE_DOUBLE_HEAD),
        ("minimal", b::MINIMAL),
        ("minimal_heavy_head", b::MINIMAL_HEAVY_HEAD),
        ("minimal_double_head", b::MINIMAL_DOUBLE_HEAD),
        ("simple", b::SIMPLE),
        ("simple_head", b::SIMPLE_HEAD),
        ("simple_heavy", b::SIMPLE_HEAVY),
        ("horizontals", b::HORIZONTALS),
        ("heavy_edge", b::HEAVY_EDGE),
        ("heavy_head", b::HEAVY_HEAD),
        ("double_edge", b::DOUBLE_EDGE),
        ("markdown", b::MARKDOWN),
    ]
};

/// Parse a `--padding` value: 1, 2, or 4 comma-separated integers, unpacked into
/// `(top, right, bottom, left)`. Port of rich-cli's padding parsing + upstream's
/// `Padding.unpack`.
fn parse_padding(value: &str) -> Result<(usize, usize, usize, usize), String> {
    let error = || "padding should be 1, 2, or 4 integers separated by commas".to_string();
    let parts: Result<Vec<usize>, _> = value
        .split(',')
        .map(|p| p.trim().parse::<usize>())
        .collect();
    let parts = parts.map_err(|_| error())?;
    match parts.as_slice() {
        [p] => Ok((*p, *p, *p, *p)),
        [v, h] => Ok((*v, *h, *v, *h)),
        [t, r, b, l] => Ok((*t, *r, *b, *l)),
        _ => Err(error()),
    }
}

/// Set the render mode, rejecting a second, conflicting mode flag.
fn mode_name(mode: Mode) -> &'static str {
    MODE_SPECS
        .iter()
        .find_map(|spec| (spec.mode == mode).then_some(spec.primary))
        .unwrap_or("unknown")
}

fn command_mode(command: &str) -> Option<Mode> {
    MODE_SPECS
        .iter()
        .find_map(|spec| spec.aliases.contains(&command).then_some(spec.mode))
}

/// `--head`/`--tail`'s LINES: upstream's `click.IntRange(min=1)`.
fn parse_lines(flag: &str, value: Option<&String>) -> Result<usize, String> {
    let flag = match flag {
        "-h" | "--head" => "--head",
        _ => "--tail",
    };
    let value = value.ok_or_else(|| format!("{flag} requires a number of LINES"))?;
    match value.parse::<i64>() {
        Ok(lines) if lines >= 1 => Ok(lines as usize),
        Ok(lines) => Err(format!("{flag}: {lines} is not in the range x>=1")),
        Err(_) => Err(format!("{flag}: {value:?} is not a valid integer")),
    }
}

fn set_mode(current: &mut Mode, mode: Mode) -> Result<(), String> {
    if *current != Mode::Auto && *current != mode {
        return Err(format!(
            "only one render mode ({RENDER_MODE_FLAGS}) may be given"
        ));
    }
    *current = mode;
    Ok(())
}

/// Parse args into a [`Cli`], or `Ok(None)` when `--help`/`--version` handled it.
fn parse(args: &[String]) -> Result<Option<Cli>, String> {
    let roots = ConfigRoots::default();
    if authoring::dispatch(args)? {
        return Ok(None);
    }
    if tools::bench_dispatch(args)? {
        return Ok(None);
    }
    if let Some(output) = config::inspect(args, &roots)? {
        authoring::out(&format!("{output}\n"));
        return Ok(None);
    }
    let merged = config_args(args, &roots)?;
    parse_inner(&merged)
}

fn parse_inner(args: &[String]) -> Result<Option<Cli>, String> {
    let mut mode = Mode::Auto;
    let mut resources: Vec<String> = Vec::new();
    let mut loops = None;
    let mut animation = animation::AnimationControls::default();
    let mut diff_threshold = None;
    let mut image_mode = ImageMode::Auto;
    let mut image_fit = None;
    let mut image_anchor = None;
    let mut image_background = None;
    let mut image_color = None;
    let mut image_dither = None;
    let mut image_color_distance = None;
    let mut image_rotate = None;
    let mut image_flip_horizontal = false;
    let mut image_flip_vertical = false;
    let mut image_grayscale = false;
    let mut image_max_width = None;
    let mut image_max_height = None;
    let mut image_brightness = None;
    let mut image_contrast = None;
    let mut image_gamma = None;
    let mut log_presentation = String::from("plain");
    let mut mermaid_backend = None;
    let mut dot_backend = None;
    let mut graph_sources = sources::GraphSourceOptions::default();
    let mut chart = chart::ChartOptions::default();
    let mut schema_options = sources::SchemaOptions::default();
    let mut profile_options = profile::ProfileOptions::default();
    let mut rule_options = style_rules::RuleOptions::default();
    let mut highlighter: Option<String> = None;
    let mut plugins: Vec<String> = Vec::new();
    let mut code_theme: Option<String> = None;
    let mut theme_styles = std::collections::BTreeMap::new();
    let mut theme_file_styles = std::collections::BTreeMap::new();
    let mut height = None;
    let mut extensions = CliExtensions::default();
    let mut data = inspect::DataOptions::default();
    let mut tool_options = tools::ToolOptions::default();
    let mut viewer_options = viewers::ViewerOptions::default();
    let mut log_options = logs::LogOptions::default();
    // Whether any paging flag was given: `view` pages automatically otherwise.
    let mut paging_explicit = false;
    // `rich ansi explain FILE`: the second word belongs to the command.
    let mut ansi_word = false;
    let mut width = None;
    let mut justify = None;
    let mut no_color = std::env::var_os("NO_COLOR").is_some_and(|value| !value.is_empty());
    let mut export_html: Option<String> = None;
    let mut export_svg: Option<String> = None;
    let mut export_png: Option<String> = None;
    let mut panel = None;
    let mut padding = None;
    let mut title = None;
    let mut caption = None;
    let mut panel_style = None;
    let mut style = None;
    let mut expand = false;
    let mut pager = false;
    let mut auto_pager = false;
    let mut hyperlinks = false;
    let mut source = SourceOptions::default();
    // Upstream's `if text_left … elif text_right … elif text_center … elif
    // text_full`: the first of these in that order wins, wherever it was given.
    let mut text_flags = [false; 4];
    let mut emoji = false;
    let mut soft = false;
    let mut max_width = None;
    let mut rule_style = None;
    let mut rule_char = None;
    let mut force_terminal = false;
    // Unset means each command's default: off for the upstream modes, on
    // for `view` and text `diff` (see `run_once_with_fetch`).
    let mut sanitize = None;
    let mut report_format = ReportFormat::Human;
    let mut watch = false;
    let mut watch_interval = 1.0;
    let mut watch_cache = false;
    let mut watch_debounce: Option<f64> = None;
    let mut watch_poll = false;
    let mut watch_exit_on_error = false;
    let mut batch = false;
    let mut progress = true;
    let mut micro_project = false;
    let mut continue_on_error = false;
    let mut jobs = 1usize;
    let mut dry_run = false;
    let mut batch_paths = batch_paths::BatchPathOptions::default();
    let mut overwrite = false;
    let mut collision = CollisionPolicy::Error;
    // Set by `--`: everything after it is a positional argument, however much it
    // looks like a flag. Without this nothing beginning with `-` could be
    // printed or opened at all — `rich -p -- "-5 degrees"` and `rich -- -weird.md`
    // both died with "unknown option".
    let mut end_of_options = false;
    // `--format NAME` for a document format (`org`, `man`, …): the mode it
    // names. Data formats stay with `data`; the last `--format` wins.
    let mut document_format: Option<(String, Mode)> = None;

    // `rich deps` takes `--top` and `--threshold` from `rich profile` and
    // `--diff`, which share their names.
    let deps_mode = explicit_mode(args) == Some(Mode::Deps);
    let mut iter = args.iter();
    while let Some(arg) = iter.next() {
        if end_of_options {
            resources.push(arg.to_string());
            continue;
        }
        if extensions.parse_option(arg, &mut iter)? {
            continue;
        }
        if arg == "--format" {
            let named = iter
                .clone()
                .next()
                .and_then(|value| documents::format_mode(value).map(|mode| (value.clone(), mode)));
            if let Some(named) = named {
                iter.next();
                document_format = Some(named);
                data.format = None;
                continue;
            }
            document_format = None;
        }
        if data
            .parse_option(arg, &mut iter)
            .map_err(|err| match arg.as_str() {
                "--format" => documents::FORMAT_USAGE.to_string(),
                _ => err,
            })?
        {
            continue;
        }
        if tool_options.parse_option(arg, &mut iter)? {
            continue;
        }
        // Before the viewer options: `--group trace` is `rich log`'s, and
        // `--group 4` is left for `rich hex`.
        if log_options.parse_option(arg, &mut iter)? {
            continue;
        }
        if viewer_options.parse_option(arg, &mut iter)? {
            continue;
        }
        if graph_sources.parse_option(arg, &mut iter, deps_mode)? {
            continue;
        }
        if chart.parse_option(arg, &mut iter)? {
            continue;
        }
        if schema_options.parse_option(arg) {
            continue;
        }
        if profile_options.parse_option(arg, &mut iter)? {
            continue;
        }
        if rule_options.parse_option(arg, &mut iter)? {
            continue;
        }
        if matches!(
            arg.as_str(),
            "--pager" | "--auto-pager" | "--no-pager" | "--no-auto-pager"
        ) {
            paging_explicit = true;
        }
        match arg.as_str() {
            "--" => end_of_options = true,
            // `-h` is upstream's `--head`: help is `--help` only.
            "--help" => {
                let no_color = no_color || cli_spec::no_color_requested(args);
                // `rich hex --help` shows the command, not the whole CLI.
                let help = command_word(args)
                    .and_then(|command| cli_spec::subcommand_help(&[command], no_color));
                match help {
                    Some(help) => authoring::out(&format!("{help}\n")),
                    None => print_help(no_color),
                }
                return Ok(None);
            }
            "-V" | "-v" | "--version" => {
                println!("rich (rs-rich-cli) {VERSION}");
                return Ok(None);
            }
            "-p" | "--print" => set_mode(&mut mode, Mode::Print)?,
            "-m" | "--markdown" => set_mode(&mut mode, Mode::Markdown)?,
            // Upstream's JSON is `-J`; this port's `-j` (upstream's `--emoji`)
            // predates the rest of the short aliases. See DIVERGENCES.
            "-j" | "-J" | "--json" => set_mode(&mut mode, Mode::Json)?,
            "-x" | "--syntax" => set_mode(&mut mode, Mode::Syntax)?,
            "--csv" => set_mode(&mut mode, Mode::Csv)?,
            "--ipynb" => set_mode(&mut mode, Mode::Ipynb)?,
            "--rst" => set_mode(&mut mode, Mode::Rst)?,
            "--org" => set_mode(&mut mode, Mode::Org)?,
            "--asciidoc" | "--adoc" => set_mode(&mut mode, Mode::AsciiDoc)?,
            "--man" | "--roff" => set_mode(&mut mode, Mode::Man)?,
            "--gif" => set_mode(&mut mode, Mode::Gif)?,
            "--diff" => set_mode(&mut mode, Mode::Diff)?,
            "--image" => set_mode(&mut mode, Mode::Image)?,
            "--jsonl" | "--ndjson" => set_mode(&mut mode, Mode::JsonLines)?,
            "--log" => set_mode(&mut mode, Mode::Log)?,
            "--inspect" => set_mode(&mut mode, Mode::Inspect)?,
            "--ansi-explain" => set_mode(&mut mode, Mode::AnsiExplain)?,
            "--highlighter" => {
                let value = iter
                    .next()
                    .ok_or("--highlighter requires a code highlighter's name")?;
                highlighter = Some(value.clone());
            }
            "--code-theme" => {
                let value = iter.next().ok_or("--code-theme requires a theme name")?;
                code_theme = Some(value.clone());
            }
            "--plugin" => {
                let path = iter.next().ok_or("--plugin requires PATH")?;
                plugins.push(path.clone());
            }
            "--mermaid-backend" => {
                let value = iter
                    .next()
                    .ok_or("--mermaid-backend requires text, mmdc or off")?;
                mermaid_backend = Some(MermaidBackend::parse(value)?);
            }
            "--dot-backend" => {
                let value = iter
                    .next()
                    .ok_or("--dot-backend requires text, graphviz or off")?;
                dot_backend = Some(sources::DotBackend::parse(value)?);
            }
            "--log-presentation" => {
                let value = iter
                    .next()
                    .ok_or("--log-presentation requires plain or rich")?;
                if !matches!(value.as_str(), "plain" | "rich") {
                    return Err("--log-presentation requires plain or rich".into());
                }
                log_presentation = value.clone();
            }
            "--report" => {
                let value = iter.next().map(String::as_str);
                report_format.apply_option("--report", value)?;
            }
            "--machine-json" => {
                report_format.apply_option("--machine-json", None)?;
            }
            "--progress" => progress = true,
            "--no-progress" => progress = false,
            "--micro-project" => micro_project = true,
            "--no-micro-project" => micro_project = false,
            "--theme-style" => {
                let binding = iter.next().ok_or("--theme-style requires NAME=STYLE")?;
                let (name, value) = binding
                    .split_once('=')
                    .ok_or("--theme-style requires NAME=STYLE")?;
                config::validate_theme_binding(name, value)?;
                let style = Style::parse(value)
                    .map_err(|error| format!("invalid theme style {name}: {error}"))?;
                theme_styles.insert(name.to_owned(), style);
            }
            "--theme-file" => {
                let path = iter.next().ok_or("--theme-file requires PATH")?;
                theme_file_styles = read_theme_file(path, &format!("--theme-file {path}"))?;
            }
            "--image-color" => {
                const USAGE: &str =
                    "--image-color requires truecolor, ansi256, ansi16 or grayscale";
                let value = iter.next().ok_or(USAGE)?;
                if !matches!(
                    value.as_str(),
                    "truecolor" | "ansi256" | "ansi16" | "grayscale"
                ) {
                    return Err(USAGE.into());
                }
                image_color = Some(value.clone());
            }
            flag @ ("--image-max-width" | "--image-max-height") => {
                let usage = format!("{flag} requires a positive integer");
                let value = iter
                    .next()
                    .and_then(|v| v.parse::<usize>().ok())
                    .filter(|v| *v > 0)
                    .ok_or(usage)?;
                if flag == "--image-max-width" {
                    image_max_width = Some(value);
                } else {
                    image_max_height = Some(value);
                }
            }
            flag @ ("--image-brightness" | "--image-contrast" | "--image-gamma") => {
                let gamma = flag == "--image-gamma";
                let usage = if gamma {
                    format!("{flag} requires a finite number greater than 0 (1.0 = unchanged)")
                } else {
                    format!("{flag} requires a finite number of at least 0 (1.0 = unchanged)")
                };
                let value = iter
                    .next()
                    .and_then(|v| v.parse::<f32>().ok())
                    .filter(|v| v.is_finite() && (*v > 0.0 || (!gamma && *v == 0.0)))
                    .ok_or(usage)?;
                match flag {
                    "--image-brightness" => image_brightness = Some(value),
                    "--image-contrast" => image_contrast = Some(value),
                    _ => image_gamma = Some(value),
                }
            }
            "--image-flip-horizontal" => image_flip_horizontal = true,
            "--no-image-flip-horizontal" => image_flip_horizontal = false,
            "--image-flip-vertical" => image_flip_vertical = true,
            "--no-image-flip-vertical" => image_flip_vertical = false,
            "--image-grayscale" => image_grayscale = true,
            "--no-image-grayscale" => image_grayscale = false,
            "--image-rotate" => {
                let value = iter
                    .next()
                    .ok_or("--image-rotate requires 0, 90, 180 or 270")?;
                image_rotate = Some(match value.as_str() {
                    "0" => 0,
                    "90" => 90,
                    "180" => 180,
                    "270" => 270,
                    _ => return Err("--image-rotate requires 0, 90, 180 or 270".into()),
                });
            }
            "--image-dither" => {
                const USAGE: &str =
                    "--image-dither requires none, floyd-steinberg, bayer4x4 or atkinson";
                let value = iter.next().ok_or(USAGE)?;
                if !matches!(
                    value.as_str(),
                    "none" | "floyd-steinberg" | "bayer4x4" | "atkinson"
                ) {
                    return Err(USAGE.into());
                }
                image_dither = Some(value.clone());
            }
            "--image-color-distance" => {
                const USAGE: &str = "--image-color-distance requires rgb or oklab";
                let value = iter.next().ok_or(USAGE)?;
                if !matches!(value.as_str(), "rgb" | "oklab") {
                    return Err(USAGE.into());
                }
                image_color_distance = Some(value.clone());
            }
            "--image-mode" => {
                let value = iter.next().ok_or(
                    "--image-mode requires one of: auto, sixel, blocks, quadrants, braille, ascii, none",
                )?;
                image_mode = value.parse()?;
            }
            "--image-fit" => {
                let value = iter
                    .next()
                    .ok_or("--image-fit requires contain, cover, stretch or native")?;
                if !matches!(value.as_str(), "contain" | "cover" | "stretch" | "native") {
                    return Err("--image-fit requires contain, cover, stretch or native".into());
                }
                image_fit = Some(value.clone());
            }
            "--image-anchor" => {
                let value = iter.next().ok_or("--image-anchor requires a position")?;
                if !matches!(
                    value.as_str(),
                    "center"
                        | "top"
                        | "bottom"
                        | "left"
                        | "right"
                        | "top-left"
                        | "top-right"
                        | "bottom-left"
                        | "bottom-right"
                ) {
                    return Err("--image-anchor requires center/top/bottom/left/right/top-left/top-right/bottom-left/bottom-right".into());
                }
                image_anchor = Some(value.clone());
            }
            "--image-background" => {
                const USAGE: &str = "--image-background requires #RRGGBB, default or checkerboard";
                let value = iter.next().ok_or(USAGE)?;
                image_background = Some(ImageBackdrop::parse(value).ok_or(USAGE)?);
            }
            "--height" => {
                let value = iter.next().ok_or("--height requires a number")?;
                let rows: usize = value
                    .parse()
                    .map_err(|_| format!("invalid height '{value}'"))?;
                if rows == 0 {
                    return Err("--height must be at least 1".into());
                }
                height = Some(rows);
            }
            "--threshold" => {
                let value = iter
                    .next()
                    .ok_or("--threshold requires a percentage, e.g. --threshold 2")?;
                let percent: f32 = value
                    .parse()
                    .map_err(|_| format!("invalid threshold '{value}'"))?;
                // `"NaN"` and `"inf"` both parse as f32, and every comparison
                // against NaN is false — so an empty template variable or a bad
                // substitution would turn the gate off and report a pass. A gate
                // that can be silently disabled is worse than no gate.
                if !percent.is_finite() || !(0.0..=100.0).contains(&percent) {
                    return Err(format!(
                        "threshold must be a percentage between 0 and 100, got '{value}'"
                    ));
                }
                diff_threshold = Some(percent);
            }
            "--loop" => {
                let value = iter.next().ok_or("--loop requires a count (0 = forever)")?;
                loops = Some(
                    value
                        .parse()
                        .map_err(|_| format!("invalid loop count {value:?}"))?,
                );
            }
            "--speed" | "--fps" | "--max-frames" | "--max-duration" => {
                let value = iter
                    .next()
                    .ok_or_else(|| format!("{arg} requires a value"))?;
                animation.set(arg, value)?;
            }
            "-u" | "--rule" => set_mode(&mut mode, Mode::Rule)?,
            "-l" | "--left" => justify = Some(Justify::Left),
            "-r" | "--right" if justify != Some(Justify::Left) => justify = Some(Justify::Right),
            "-r" | "--right" => {}
            "-c" | "--center" if justify.is_none() => justify = Some(Justify::Center),
            "-c" | "--center" => {}
            "-L" | "--text-left" => text_flags[0] = true,
            "-R" | "--text-right" => text_flags[1] = true,
            "-C" | "--text-center" => text_flags[2] = true,
            "-F" | "--text-full" => text_flags[3] = true,
            "-h" | "--head" => source.head = Some(parse_lines(arg, iter.next())?),
            "-t" | "--tail" => source.tail = Some(parse_lines(arg, iter.next())?),
            "-n" | "--line-numbers" => source.line_numbers = true,
            "-g" | "--guides" => source.guides = true,
            "--lexer" => {
                source.lexer = Some(iter.next().ok_or("--lexer requires a LEXER")?.clone());
            }
            "--no-wrap" => source.no_wrap = true,
            "--infer" => source.infer = true,
            "--emoji" => emoji = true,
            "--soft" => soft = true,
            "-W" | "--max-width" => {
                let value = iter.next().ok_or("--max-width requires a SIZE")?;
                // Upstream's default is -1, and a size of 0 or less means none.
                let size: i64 = value
                    .parse()
                    .map_err(|_| format!("invalid --max-width '{value}'"))?;
                max_width = usize::try_from(size).ok().filter(|size| *size > 0);
            }
            "--rule-style" => {
                let value = iter.next().ok_or("--rule-style requires a STYLE")?;
                rule_style = Some(
                    Style::parse(value).map_err(|e| format!("unable to parse rule style: {e}"))?,
                );
            }
            "--rule-char" => {
                rule_char = Some(
                    iter.next()
                        .ok_or("--rule-char requires a CHARACTER")?
                        .clone(),
                );
            }
            "--force-terminal" => force_terminal = true,
            "--no-color" => no_color = true,
            "--pager" => {
                pager = true;
                auto_pager = false;
            }
            "--auto-pager" => {
                auto_pager = true;
                pager = false;
            }
            "--no-pager" => {
                pager = false;
                auto_pager = false;
            }
            "--no-auto-pager" => auto_pager = false,
            "--color" => no_color = false,
            "--no-watch" => watch = false,
            "--no-watch-cache" => watch_cache = false,
            "--no-watch-poll" => watch_poll = false,
            "--no-watch-exit-on-error" => watch_exit_on_error = false,
            "--no-batch" => batch = false,
            "--no-continue-on-error" => continue_on_error = false,
            "--no-overwrite" => {
                overwrite = false;
                collision = CollisionPolicy::Error;
            }
            "--no-sanitize" => sanitize = Some(false),
            "--dry-run" => dry_run = true,
            "--batch-preserve-dirs" => batch_paths.preserve_dirs = true,
            "--no-batch-preserve-dirs" => batch_paths.preserve_dirs = false,
            "--batch-input-root" => {
                batch_paths.input_root = Some(fs_path(
                    iter.next().ok_or("--batch-input-root requires a path")?,
                ))
            }
            "--batch-name-template" => {
                batch_paths.template = Some(
                    batch_paths::FilenameTemplate::parse(
                        iter.next()
                            .ok_or("--batch-name-template requires a template")?,
                    )
                    .map_err(|e| e.to_string())?,
                )
            }
            "--watch" => watch = true,
            "--watch-cache" => watch_cache = true,
            "--watch-poll" => watch_poll = true,
            "--watch-exit-on-error" => watch_exit_on_error = true,
            "--watch-debounce" => {
                let value = iter
                    .next()
                    .ok_or("--watch-debounce requires seconds (0 or more)")?;
                let seconds = value
                    .parse::<f64>()
                    .map_err(|_| format!("invalid watch debounce {value:?}"))?;
                if !seconds.is_finite() || !(0.0..=3600.0).contains(&seconds) {
                    return Err("--watch-debounce must be between 0 and 3600 seconds".into());
                }
                watch_debounce = Some(seconds);
            }
            "--watch-interval" | "--interval" => {
                let value = iter
                    .next()
                    .ok_or("--watch-interval requires seconds greater than zero")?;
                watch_interval = value
                    .parse::<f64>()
                    .map_err(|_| format!("invalid watch interval {value:?}"))?;
                if !watch_interval.is_finite() || watch_interval <= 0.0 || watch_interval > 86400.0
                {
                    return Err(
                        "--watch-interval must be greater than zero and at most 86400 seconds"
                            .into(),
                    );
                }
            }
            "--batch" => batch = true,
            "--continue-on-error" => continue_on_error = true,
            "--overwrite" => {
                overwrite = true;
                collision = CollisionPolicy::Overwrite;
            }
            "--collision" => {
                collision = match iter
                    .next()
                    .ok_or("--collision requires error, overwrite, or suffix")?
                    .as_str()
                {
                    "error" => CollisionPolicy::Error,
                    "overwrite" => CollisionPolicy::Overwrite,
                    "suffix" => CollisionPolicy::Suffix,
                    other => return Err(format!("unknown collision policy {other:?}")),
                };
                overwrite = collision == CollisionPolicy::Overwrite;
            }
            "--jobs" => {
                jobs = iter
                    .next()
                    .ok_or("--jobs requires a positive number")?
                    .parse()
                    .map_err(|_| "--jobs requires a positive number".to_string())?;
                if jobs == 0 {
                    return Err("--jobs must be at least 1".into());
                }
            }
            "--sanitize" => sanitize = Some(true),
            // Upstream's `@click.option("--hyperlinks", "-y", is_flag=True,
            // help="Render hyperlinks in markdown.")`. Accepted in every mode,
            // as click accepts it — it is read only where markdown is rendered.
            "-y" | "--hyperlinks" => hyperlinks = true,
            // Both take a PATH and both may be given at once, matching
            // upstream: the resource still renders to the terminal and the
            // files are written alongside it.
            "--export-html" | "-o" => {
                export_html = Some(iter.next().ok_or("--export-html requires a PATH")?.clone());
            }
            "--export-svg" => {
                export_svg = Some(iter.next().ok_or("--export-svg requires a PATH")?.clone());
            }
            "--export-png" => {
                export_png = Some(iter.next().ok_or("--export-png requires a PATH")?.clone());
            }
            "-a" | "--panel" => {
                let value = iter.next().ok_or("--panel requires a box name")?;
                panel = parse_box(value)?;
            }
            "-d" | "--padding" => {
                let value = iter.next().ok_or("--padding requires a value")?;
                padding = Some(parse_padding(value)?);
            }
            "-e" | "--expand" => expand = true,
            "--title" => {
                title = Some(iter.next().ok_or("--title requires a value")?.clone());
            }
            "--caption" => {
                caption = Some(iter.next().ok_or("--caption requires a value")?.clone());
            }
            // `-s/--style` is the style of the *renderable* (upstream wraps it in
            // `Styled`); `-S/--panel-style` is the border. They were fused into
            // one flag that set the border, so there was no way to style the
            // content at all and `--style` aborted without `--panel`.
            "-s" | "--style" => {
                let value = iter.next().ok_or("--style requires a value")?;
                style = Some(Style::parse(value).map_err(|e| format!("invalid --style: {e}"))?);
            }
            "-S" | "--panel-style" => {
                let value = iter.next().ok_or("--panel-style requires a value")?;
                panel_style =
                    Some(Style::parse(value).map_err(|e| format!("invalid --panel-style: {e}"))?);
            }
            "-w" | "--width" => {
                let value = iter.next().ok_or("--width requires a number")?;
                let columns: usize = value.parse().map_err(|_| {
                    // The common cause is a missing value, in which case this
                    // has just eaten the filename — say so rather than quoting
                    // the path back with debug escaping.
                    if std::path::Path::new(value).exists() {
                        format!("--width needs a number, but got the file '{value}' — a value is missing")
                    } else {
                        format!("invalid width '{value}'")
                    }
                })?;
                if columns == 0 {
                    return Err("--width must be at least 1".into());
                }
                width = Some(columns);
            }
            other if other.starts_with('-') && other != "-" => {
                return Err(format!("unknown option {other:?}"));
            }
            other
                if mode == Mode::Auto && resources.is_empty() && command_mode(other).is_some() =>
            {
                ansi_word = other == "ansi";
                set_mode(&mut mode, command_mode(other).expect("checked above"))?;
            }
            "explain" if ansi_word && resources.is_empty() => ansi_word = false,
            other => resources.push(other.to_string()),
        }
    }

    // A document `--format` is that document's mode flag: it may not be
    // combined with another mode, and like any input mode it reads stdin when
    // there is no RESOURCE.
    if let Some((name, document)) = document_format {
        if mode != Mode::Auto && mode != document {
            return Err(format!(
                "--format {name} cannot be combined with --{}",
                mode_name(mode)
            ));
        }
        mode = document;
    }
    // `--format` makes automatic mode an input mode: with no RESOURCE it reads
    // stdin, as `--json` does, instead of showing the demo.
    if data.format.is_some() {
        if !matches!(mode, Mode::Auto | Mode::Inspect) {
            return Err(format!(
                "--format cannot be combined with --{}",
                mode_name(mode)
            ));
        }
        if mode == Mode::Auto && resources.is_empty() && !batch {
            resources.push("-".into());
        }
    }
    if let Some(flag) = data
        .inspect_only_option(matches!(mode, Mode::Capture | Mode::Log))
        .filter(|_| mode != Mode::Inspect)
    {
        if flag == "--redact" {
            return Err(
                "--redact only has an effect with --inspect, `rich capture` or `rich log`".into(),
            );
        }
        return Err(format!("{flag} only has an effect with --inspect"));
    }
    if let Some(flag) = data.transform_option() {
        if !transforms_apply(mode) {
            return Err(format!(
                "{flag} only has an effect on {}",
                transform_modes(flag)
            ));
        }
        data.check_transforms(mode == Mode::Inspect)?;
    }
    if let Some(flag) = tool_options.diff_option().filter(|_| mode != Mode::Diff) {
        return Err(format!("{flag} only has an effect with --diff"));
    }
    if let Some(flag) = tool_options
        .ansi_option()
        .filter(|_| mode != Mode::AnsiExplain)
    {
        return Err(format!("{flag} only has an effect with --ansi-explain"));
    }
    if mode == Mode::Log {
        // `--group 4` went to `rich hex`'s options: say what `rich log` takes.
        if viewer_options
            .given()
            .iter()
            .any(|(flag, _)| *flag == "--group")
        {
            return Err("--group requires trace, span or correlation with `rich log`".into());
        }
        log_options.validate(resources.first().map(String::as_str))?;
        if log_options.follows() && (watch || batch) {
            return Err("--follow cannot be combined with --watch or --batch".into());
        }
    }
    // `--depth` is `rich deps`'s flag and `rich profile`'s too: deps' options
    // parse it, and hand it over here.
    if mode == Mode::Profile
        && let Some(depth) = graph_sources.take_depth()
    {
        profile_options.set_depth(depth)?;
    }
    for (flag, commands) in viewer_options
        .given()
        .into_iter()
        .chain(graph_sources.given())
        .chain(chart.given())
        .chain(schema_options.given())
        .chain(profile_options.given())
        .chain(log_options.given())
    {
        if !commands.contains(&mode_name(mode)) {
            return Err(format!(
                "{flag} only has an effect with `rich {}`",
                commands.join("` or `rich ")
            ));
        }
    }
    if mode == Mode::Capture && resources.is_empty() {
        return Err("capture needs a command: rich capture [OPTIONS] -- COMMAND [ARGS...]".into());
    }
    if mode == Mode::View && !paging_explicit {
        auto_pager = true;
    }
    data.validate()?;

    if watch && (batch || pager || auto_pager) {
        return Err("--watch cannot be combined with --batch or paging".into());
    }

    // `--gif`/`--diff` consume their whole resource list as one unit (a diff is
    // a pair), but a batch rewrites each item to a single resource — `run_diff`
    // would then index `resources[1]` and panic. Reject the combination.
    if batch {
        if mode.accepts_multiple_resources() {
            return Err(format!(
                "--batch cannot be combined with {}",
                if mode == Mode::Diff {
                    "--diff"
                } else {
                    "--gif"
                }
            ));
        }
        if resources.is_empty() {
            return Err("--batch needs at least one file, directory or glob".into());
        }
        // One pager per item would be N interactive pagers over one plan.
        if pager || auto_pager {
            return Err("--pager cannot be combined with --batch".into());
        }
    }

    // Only `--gif` animates several resources at once; every other mode renders
    // exactly one.
    if mode == Mode::Diff && !(1..=2).contains(&resources.len()) {
        return Err(
            "--diff needs two images or files to compare, or one patch: --diff before after".into(),
        );
    }
    // `--conflicts` reads the merge conflicts left in one file; there is no
    // percentage of it to gate on.
    if mode == Mode::Diff && tool_options.conflicts() {
        if resources.len() != 1 {
            return Err("--conflicts needs exactly one file: rich diff --conflicts FILE".into());
        }
        if diff_threshold.is_some() {
            return Err("--threshold cannot be combined with --conflicts".into());
        }
    }
    if mode == Mode::Image {
        if resources.is_empty() {
            return Err(
                "--image requires an image file: rich --image photo.png (or `-` for stdin)".into(),
            );
        }
        if image_mode == ImageMode::None {
            return Err(
                "--image-mode none has no effect with --image; use auto, ascii, blocks, or sixel"
                    .into(),
            );
        }
    }
    let quantized = matches!(
        image_color.as_deref(),
        Some("ansi256" | "ansi16" | "grayscale")
    );
    if quantized && image_mode == ImageMode::Braille {
        return Err(format!(
            "--image-color {} has no effect with --image-mode braille, which is monochrome",
            image_color.as_deref().unwrap()
        ));
    }
    for (flag, value, neutral) in [
        ("--image-dither", image_dither.as_deref(), "none"),
        (
            "--image-color-distance",
            image_color_distance.as_deref(),
            "rgb",
        ),
    ] {
        if let Some(value) = value.filter(|v| *v != neutral && !quantized) {
            return Err(format!(
                "{flag} {value} requires --image-color ansi256, ansi16 or grayscale"
            ));
        }
    }
    if image_anchor.is_some() && image_fit.as_deref() != Some("cover") {
        return Err("--image-anchor requires --image-fit cover".into());
    }
    if (batch_paths.preserve_dirs
        || batch_paths.template.is_some()
        || batch_paths.input_root.is_some())
        && !batch
    {
        return Err("batch path options require --batch".into());
    }
    if batch_paths.preserve_dirs && batch_paths.input_root.is_none() {
        return Err("--batch-preserve-dirs requires --batch-input-root".into());
    }
    if dry_run && !batch {
        return Err("--dry-run requires --batch".into());
    }
    if jobs > 1 && (!batch || (export_html.is_none() && export_svg.is_none())) {
        return Err("--jobs greater than 1 requires --batch with a file export".into());
    }
    // `native` sizes to the image itself; the others fill a rectangle.
    if image_fit.as_deref().is_some_and(|fit| fit != "native") && height.is_none() {
        return Err("--image-fit requires --height to define the target rectangle".into());
    }
    // `--gif` animates in place and the demo writes its own console, so neither
    // goes through the export path: both accepted -o/--export-svg, wrote no
    // file, and exited 0. Everywhere else a bad export path is a hard error, so
    // silence here reads as success.
    let effective_mode = if mode == Mode::Auto {
        detect_mode(resources.first().map(String::as_str))
    } else {
        mode
    };
    extensions.validate(
        effective_mode == Mode::Gif,
        effective_mode.allows_extensions()
            && !(mode == Mode::Auto && resources.is_empty())
            && !(mode == Mode::Print && resources.first().is_some_and(|r| r != "-" && !is_url(r))),
    )?;
    if export_png.is_some() && !cfg!(feature = "png") {
        return Err("--export-png needs a build with the png feature".into());
    }
    if export_png.is_some() && batch {
        return Err("--export-png cannot be combined with --batch".into());
    }
    let exporting = export_html.is_some() || export_svg.is_some() || export_png.is_some();
    if exporting {
        let unsupported = if effective_mode == Mode::Gif {
            Some("--gif")
        } else if mode == Mode::Auto && resources.is_empty() {
            Some("the capability demo")
        } else {
            None
        };
        if let Some(what) = unsupported {
            return Err(format!(
                "--export-html/--export-svg/--export-png cannot capture {what}"
            ));
        }
    }

    // A flag whose mode is absent is almost always a mistake, and silence is the
    // dangerous response: `--threshold` without `--diff` used to render the file
    // and exit 0, so a CI job that lost its `--diff` — a typo, a refactor, an
    // argument reordered — became a permanently green gate. That is the same
    // failure the NaN check closed, reached from the other side.
    let text_justify = [
        Justify::Left,
        Justify::Right,
        Justify::Center,
        Justify::Full,
    ]
    .into_iter()
    .zip(text_flags)
    .find_map(|(justify, given)| given.then_some(justify));
    // Automatic mode renders source as syntax, as upstream's does, so the
    // source options apply to it.
    let source_mode = matches!(effective_mode, Mode::Syntax | Mode::Ipynb | Mode::Auto);
    let print_mode = matches!(effective_mode, Mode::Print | Mode::Rule);
    let orphans = [
        (
            "--head/--tail",
            source.head.is_some() || source.tail.is_some(),
            "--syntax, --csv or --ipynb",
            source_mode || effective_mode == Mode::Csv,
        ),
        (
            "--infer",
            source.infer,
            "--csv",
            effective_mode == Mode::Csv,
        ),
        (
            "--line-numbers",
            source.line_numbers,
            "--syntax or --ipynb",
            source_mode,
        ),
        (
            "--guides",
            source.guides,
            "--syntax or --ipynb",
            source_mode,
        ),
        (
            "--lexer",
            source.lexer.is_some(),
            "--syntax, --ipynb, --rst, --org, --asciidoc or --man",
            source_mode
                || matches!(
                    effective_mode,
                    Mode::Rst | Mode::Org | Mode::AsciiDoc | Mode::Man
                ),
        ),
        (
            "--no-wrap",
            source.no_wrap,
            "--syntax, --ipynb, --print or --rule",
            source_mode || print_mode,
        ),
        (
            "--text-left/--text-right/--text-center/--text-full",
            text_justify.is_some(),
            "--print or --rule",
            print_mode,
        ),
        (
            "--rule-style",
            rule_style.is_some(),
            "--rule",
            effective_mode == Mode::Rule,
        ),
        (
            "--rule-char",
            rule_char.is_some(),
            "--rule",
            effective_mode == Mode::Rule,
        ),
        // The streaming modes write each record as it arrives, not through
        // the final print these shape.
        (
            "--soft",
            soft,
            "a mode other than --jsonl or --log",
            !matches!(effective_mode, Mode::JsonLines | Mode::Log),
        ),
        (
            "--max-width",
            max_width.is_some(),
            "a mode other than --jsonl or --log",
            !matches!(effective_mode, Mode::JsonLines | Mode::Log),
        ),
        (
            "--threshold",
            diff_threshold.is_some(),
            "--diff",
            mode == Mode::Diff,
        ),
        (
            "--image-mode",
            image_mode != ImageMode::Auto,
            "--diff/--image",
            mode == Mode::Diff || mode == Mode::Image,
        ),
        ("--height", height.is_some(), "--image", mode == Mode::Image),
        (
            "--image-rotate",
            image_rotate.is_some(),
            "--image",
            mode == Mode::Image,
        ),
        (
            "--image-flip-horizontal",
            image_flip_horizontal,
            "--image",
            mode == Mode::Image,
        ),
        (
            "--image-flip-vertical",
            image_flip_vertical,
            "--image",
            mode == Mode::Image,
        ),
        (
            "--image-grayscale",
            image_grayscale,
            "--image",
            mode == Mode::Image,
        ),
        (
            "--image-color",
            image_color.is_some(),
            "--image or --gif",
            mode == Mode::Image || effective_mode == Mode::Gif,
        ),
        (
            "--image-max-width",
            image_max_width.is_some(),
            "--image",
            mode == Mode::Image,
        ),
        (
            "--image-max-height",
            image_max_height.is_some(),
            "--image",
            mode == Mode::Image,
        ),
        (
            "--image-brightness",
            image_brightness.is_some(),
            "--image",
            mode == Mode::Image,
        ),
        (
            "--image-contrast",
            image_contrast.is_some(),
            "--image",
            mode == Mode::Image,
        ),
        (
            "--image-gamma",
            image_gamma.is_some(),
            "--image",
            mode == Mode::Image,
        ),
        (
            "--image-dither",
            image_dither.is_some(),
            "--image or --gif",
            mode == Mode::Image || effective_mode == Mode::Gif,
        ),
        (
            "--image-color-distance",
            image_color_distance.is_some(),
            "--image or --gif",
            mode == Mode::Image || effective_mode == Mode::Gif,
        ),
        (
            "--image-fit",
            image_fit.is_some(),
            "--image",
            mode == Mode::Image,
        ),
        (
            "--image-background",
            image_background.is_some(),
            "--image",
            mode == Mode::Image,
        ),
        (
            "--loop",
            loops.is_some(),
            "--gif",
            effective_mode == Mode::Gif,
        ),
        (
            "--speed",
            animation.speed.is_some(),
            "--gif",
            effective_mode == Mode::Gif,
        ),
        (
            "--fps",
            animation.fps.is_some(),
            "--gif",
            effective_mode == Mode::Gif,
        ),
        (
            "--max-frames",
            animation.max_frames.is_some(),
            "--gif",
            effective_mode == Mode::Gif,
        ),
        (
            "--max-duration",
            animation.max_duration.is_some(),
            "--gif",
            effective_mode == Mode::Gif,
        ),
        // `--title`/`--caption` are deliberately NOT here: upstream feeds them to
        // the CSV table as well as to the panel, so requiring `--panel` made
        // `rich --csv sales.csv --title Sales` — a documented upstream use —
        // impossible. `-S`/`-e` really do nothing without a panel.
        (
            "--panel-style",
            panel_style.is_some(),
            "--panel",
            panel.is_some(),
        ),
        (
            "--expand",
            expand,
            "--panel/--padding",
            panel.is_some() || padding.is_some(),
        ),
        ("--watch-interval", watch_interval != 1.0, "--watch", watch),
        ("--watch-cache", watch_cache, "--watch", watch),
        (
            "--watch-debounce",
            watch_debounce.is_some(),
            "--watch",
            watch,
        ),
        ("--watch-poll", watch_poll, "--watch", watch),
        (
            "--watch-exit-on-error",
            watch_exit_on_error,
            "--watch",
            watch,
        ),
    ];
    if let Some((flag, _, needs, _)) = orphans
        .iter()
        .find(|(_, given, _, mode_present)| *given && !*mode_present)
    {
        return Err(format!("{flag} only has an effect with {needs}"));
    }

    // These decorate a single rendered resource; --diff composes its own report
    // and quietly dropped them, which reads as the flag having no effect.
    let demo = mode == Mode::Auto && resources.is_empty();
    if effective_mode.draws_directly() || demo {
        let mode_name = if effective_mode == Mode::Gif {
            "--gif"
        } else if effective_mode == Mode::Image {
            "--image"
        } else if effective_mode.streams_records() {
            mode_name(effective_mode)
        } else if demo {
            "the capability demo"
        } else {
            "--diff"
        };
        let unsupported = [
            (
                "--pager",
                (pager || auto_pager)
                    && (effective_mode == Mode::Gif || effective_mode.streams_records() || demo),
            ),
            (
                "--export-html/--export-svg/--export-png",
                (export_html.is_some() || export_svg.is_some() || export_png.is_some())
                    && effective_mode.streams_records(),
            ),
            ("--width", demo && width.is_some()),
            ("--theme-style", demo && !theme_styles.is_empty()),
            ("--theme-file", demo && !theme_file_styles.is_empty()),
            (
                "--hyperlinks",
                hyperlinks && (effective_mode.streams_records() || demo),
            ),
            ("--panel", panel.is_some()),
            ("--padding", padding.is_some()),
            ("--title", title.is_some()),
            ("--caption", caption.is_some()),
            ("--style", style.is_some()),
            ("--panel-style", panel_style.is_some()),
            ("--expand", expand),
            ("--left/--center/--right", justify.is_some()),
        ];
        if let Some((flag, _)) = unsupported.iter().find(|(_, given)| *given) {
            return Err(format!("{flag} cannot be combined with {mode_name}"));
        }
    }
    // `--watch` may follow several local files, one live region each; the
    // watcher itself checks that every one of them is a watchable file.
    if !mode.accepts_multiple_resources() && resources.len() > 1 && !batch && !watch {
        return Err("only one resource may be given (except with --gif or --watch)".into());
    }
    // `view`, `schema`, `log` and the text diff are new here, with no
    // upstream output to keep: like `less`, they show terminal controls in
    // what they display instead of letting them act, unless `--no-sanitize`
    // says otherwise. A log is untrusted input. So is anything fetched from
    // a URL, in every mode: a server's escapes (a title, an OSC 52
    // clipboard write, a hidden OSC 8 link) are shown, not obeyed. That is
    // a divergence from upstream rich-cli (docs/DIVERGENCES.md).
    let sanitize = sanitize.unwrap_or_else(|| {
        resources.iter().any(|r| is_url(r))
            || mode == Mode::View
            || mode == Mode::Schema
            || mode == Mode::Log
            || (mode == Mode::Diff
                && !(resources.len() == 2 && resources.iter().all(|r| looks_like_image(r))))
    });
    // `--print` and `--rule` show their resource as text.
    let resource = resources.first().map(|resource| {
        if print_mode {
            text_arg(resource)
        } else {
            resource.clone()
        }
    });
    let title = title.map(|title| text_arg(&title));
    let caption = caption.map(|caption| text_arg(&caption));
    let rule_char = rule_char.map(|characters| text_arg(&characters));

    // An unknown highlighter or theme is a usage error, listing the choices.
    code_highlighting(highlighter.as_deref(), code_theme.as_deref())?;
    Ok(Some(Cli {
        mode,
        resource,
        resources,
        loops,
        animation,
        diff_threshold,
        image_mode,
        image_fit,
        image_anchor,
        image_background,
        image_color,
        image_dither,
        image_color_distance,
        image_rotate,
        image_flip_horizontal,
        image_flip_vertical,
        image_grayscale,
        image_max_width,
        image_max_height,
        image_brightness,
        image_contrast,
        image_gamma,
        log_presentation,
        mermaid_backend,
        dot_backend,
        graph_sources,
        chart,
        schema: schema_options,
        profile: profile_options,
        rules: rule_options,
        highlighter,
        code_theme,
        plugins,
        micro_project,
        theme_styles,
        theme_file_styles,
        height,
        extensions,
        width,
        justify,
        text_justify,
        emoji,
        soft,
        max_width,
        rule_style,
        rule_char,
        force_terminal,
        source,
        no_color,
        export_html,
        export_svg,
        export_png,
        panel,
        padding,
        title,
        caption,
        panel_style,
        style,
        expand,
        pager,
        auto_pager,
        hyperlinks,
        sanitize,
        report_format,
        watch,
        watch_interval,
        watch_cache,
        watch_debounce: watch_debounce.unwrap_or(watch::DEFAULT_DEBOUNCE_SECONDS),
        watch_poll,
        watch_exit_on_error,
        batch,
        progress,
        continue_on_error,
        jobs,
        dry_run,
        batch_paths,
        worker_args: worker_args(args),
        overwrite,
        collision,
        data,
        tools: tool_options,
        viewers: viewer_options,
        logs: log_options,
    }))
}

/// At most `max` of the resource's bytes from `offset` on, unconverted, and
/// whether more follow: a URL is fetched as text, stdin and files are read
/// raw so binary input survives. With `--encoding` the text is decoded first,
/// as every other mode does (reading at most
/// [`controls::INSPECT_LIMIT`] bytes).
///
/// A file is read from `offset` (seeking where it can) and no further than
/// the window needs, so `rich hex /dev/urandom --length 16` ends and a sparse
/// gigabyte costs only the bytes shown.
fn read_window(cli: &Cli, offset: u64, max: u64) -> Result<(Vec<u8>, bool), String> {
    use std::io::{Seek, SeekFrom};
    let resource = cli.resource.as_deref();
    let name = resource.unwrap_or("<stdin>");
    let window = |bytes: Vec<u8>| {
        let start = usize::try_from(offset)
            .unwrap_or(usize::MAX)
            .min(bytes.len());
        let mut rest = bytes[start..].to_vec();
        let more = rest.len() as u64 > max;
        rest.truncate(usize::try_from(max).unwrap_or(usize::MAX));
        (rest, more)
    };
    if let Some(url) = resource.filter(|r| is_url(r)) {
        return fetch_url(url, cli.extensions.encoding).map(|(text, _)| window(text.into_bytes()));
    }
    if cli.extensions.encoding.is_some() {
        return read_resource_limited(
            resource,
            cli.extensions.encoding,
            Some(controls::INSPECT_LIMIT),
        )
        .map(|text| window(text.into_bytes()))
        .map_err(|err| format!("cannot read {name}: {err}"));
    }
    let error = |err: std::io::Error| format!("cannot read {name}: {err}");
    // One byte past the window says whether more follow.
    let take = max.saturating_add(1);
    let mut bytes = Vec::new();
    match resource.filter(|r| *r != "-") {
        Some(path) if fs_path(path).is_dir() => {
            return Err(format!("cannot read {path}: it is a directory"));
        }
        Some(path) => {
            let mut file = std::fs::File::open(fs_path(path)).map_err(error)?;
            // A pipe or FIFO cannot seek: skip by reading instead.
            if offset > 0 && file.seek(SeekFrom::Start(offset)).is_err() {
                std::io::copy(&mut (&mut file).take(offset), &mut std::io::sink())
                    .map_err(error)?;
            }
            file.take(take).read_to_end(&mut bytes).map_err(error)?;
        }
        None => {
            let mut stdin = std::io::stdin().lock();
            std::io::copy(&mut (&mut stdin).take(offset), &mut std::io::sink()).map_err(error)?;
            stdin.take(take).read_to_end(&mut bytes).map_err(error)?;
        }
    }
    let more = bytes.len() as u64 > max;
    bytes.truncate(usize::try_from(max).unwrap_or(usize::MAX));
    Ok((bytes, more))
}

/// Read up to `limit` bytes (all of them for `None`); more is an error.
fn read_limited(reader: impl Read, limit: Option<u64>) -> std::io::Result<Vec<u8>> {
    let mut bytes = Vec::new();
    match limit {
        None => {
            let mut reader = reader;
            reader.read_to_end(&mut bytes)?;
        }
        Some(limit) => {
            reader
                .take(limit.saturating_add(1))
                .read_to_end(&mut bytes)?;
            if bytes.len() as u64 > limit {
                return Err(std::io::Error::other(format!(
                    "larger than {}, the most this command reads",
                    controls::size(limit)
                )));
            }
        }
    }
    Ok(bytes)
}

/// Read a resource: `-` (or `None`) means stdin, otherwise a file path.
///
/// A **file** is decoded with replacement, not rejected: upstream opens it as
/// `open(path, "rt", encoding="utf8", errors="replace")`, so a cp1252 export —
/// what Excel writes on a Windows box by default — renders with `�` where the
/// odd byte was. We refused the whole file with exit 1, which is the one
/// outcome that makes the tool useless for exactly the files people reach for
/// it with.
///
/// **Stdin stays strict.** Upstream reads it with `sys.stdin.read()`, whose
/// decode error escapes into rich-cli's `except Exception` and exits non-zero;
/// there is no `errors="replace"` on that path.
fn read_resource(resource: Option<&str>, encoding: Option<Encoding>) -> std::io::Result<String> {
    read_resource_limited(resource, encoding, None)
}

/// [`read_resource`], reading at most `limit` bytes (all of them for `None`):
/// more is an error. The upstream modes read without a limit, as upstream
/// does.
fn read_resource_limited(
    resource: Option<&str>,
    encoding: Option<Encoding>,
    limit: Option<u64>,
) -> std::io::Result<String> {
    let content = match resource {
        Some(path) if path != "-" => {
            let file = &fs_path(path);
            // A directory reaches the reader as "Access is denied" on Windows,
            // which sends the reader hunting for a permissions problem.
            if file.is_dir() {
                return Err(std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    "is a directory, not a file",
                ));
            }
            let bytes = match limit {
                None => std::fs::read(file)?,
                Some(_) => read_limited(std::fs::File::open(file)?, limit)?,
            };
            if let Some(encoding) = encoding {
                return encoding.decode(&bytes).map(normalize_newlines);
            }
            if has_utf16_bom(&bytes) {
                eprintln!(
                    "rich: {} has a UTF-16 BOM; use --encoding utf-16 to decode it (default remains UTF-8 replacement)",
                    controls::shown(path)
                );
            }
            match String::from_utf8(bytes) {
                Ok(text) => text,
                // An image is not text in any encoding, and lossily decoding one
                // fills the terminal with thousands of replacement characters
                // and no clue. Keep the diagnostic for those; decode everything
                // else, which is what `errors="replace"` is actually for.
                Err(_) if looks_like_image(path) => {
                    return Err(std::io::Error::new(
                        std::io::ErrorKind::InvalidData,
                        "looks like an image; use `rich --image <path>` to view it, or \
                         `rich --diff <before> <after>` to compare two images",
                    ));
                }
                Err(err) => String::from_utf8_lossy(err.as_bytes()).into_owned(),
            }
        }
        _ => {
            if std::io::stdin().is_terminal() {
                let eof = if cfg!(windows) {
                    "Ctrl-Z then Enter"
                } else {
                    "Ctrl-D"
                };
                eprintln!("rich: reading stdin; finish input with {eof}");
            }
            let buffer = read_limited(std::io::stdin(), limit)?;
            decode_strict(buffer, encoding)?
        }
    };
    Ok(normalize_newlines(if encoding.is_some() {
        content
    } else {
        strip_bom(content)
    }))
}

fn sanitize_json_value(value: &mut serde_json::Value) {
    match value {
        serde_json::Value::String(text) => *text = sanitize_terminal_controls(text),
        serde_json::Value::Array(values) => values.iter_mut().for_each(sanitize_json_value),
        serde_json::Value::Object(values) => values.values_mut().for_each(sanitize_json_value),
        _ => {}
    }
}

fn sanitize_json_source(content: &str) -> Result<String, serde_json::Error> {
    let mut value = serde_json::from_str::<serde_json::Value>(content)?;
    sanitize_json_value(&mut value);
    serde_json::to_string(&value)
}

/// Strict stdin/URL input; the default file path separately retains replacement.
fn decode_strict(bytes: Vec<u8>, encoding: Option<Encoding>) -> std::io::Result<String> {
    if let Some(encoding) = encoding {
        return encoding.decode(&bytes);
    }
    String::from_utf8(bytes).map_err(|err| std::io::Error::new(
        std::io::ErrorKind::InvalidData,
        if has_utf16_bom(err.as_bytes()) {
            "input has a UTF-16 BOM; use --encoding utf-16"
        } else {
            "input is not valid UTF-8 text; for known headerless UTF-16 select --encoding utf-16le or utf-16be"
        },
    ))
}

/// Translate CRLF and lone CR to LF, as Python's universal newlines do.
///
/// Upstream reads text files in universal-newline mode, so it **never sees a
/// CR**; `std::fs::read_to_string` hands them straight through. That gap made
/// `--syntax` on a CRLF file render as a blank rectangle: each line was emitted
/// as `code` + CR + padding, so the CR returned the cursor to column 0 and the
/// padding overwrote the code. Exit 0, nothing visible, and piping hid it
/// because the bytes were all present — only a terminal acts on the CR.
fn normalize_newlines(text: String) -> String {
    const CR: char = '\r';
    const LF: char = '\n';
    if !text.contains(CR) {
        return text;
    }
    let mut out = String::with_capacity(text.len());
    let mut chars = text.chars().peekable();
    while let Some(c) = chars.next() {
        if c == CR {
            // CRLF and a lone CR both collapse to a single LF, matching
            // Python's universal-newline translation.
            if chars.peek() == Some(&LF) {
                chars.next();
            }
            out.push(LF);
        } else {
            out.push(c);
        }
    }
    out
}

/// Drop a leading UTF-8 byte-order mark.
///
/// Windows editors write one by default and it is invisible: it made valid JSON
/// fail to parse at "column 1", and Markdown render its first heading as
/// literal text at exit 0 — in both cases with nothing pointing at the cause.
/// Whether a path's extension names an image format `--diff`/`--image` could
/// read.
///
/// Used only to improve an error message, so a false negative costs nothing.
fn looks_like_image(path: &str) -> bool {
    std::path::Path::new(path)
        .extension()
        .and_then(|e| e.to_str())
        .map(|e| e.to_ascii_lowercase())
        .is_some_and(|e| {
            matches!(
                e.as_str(),
                "png" | "jpg" | "jpeg" | "gif" | "bmp" | "webp" | "tif" | "tiff" | "ico" | "avif"
            )
        })
}

fn strip_bom(text: String) -> String {
    match text.strip_prefix('\u{feff}') {
        Some(rest) => rest.to_string(),
        None => text,
    }
}

/// Whether `resource` is an `http(s)` URL (rich-cli's `rich <url>`). The scheme
/// is matched case-insensitively, as RFC 3986 specifies.
fn is_url(resource: &str) -> bool {
    let head: String = resource.chars().take(8).collect::<String>().to_lowercase();
    head.starts_with("http://") || head.starts_with("https://")
}

/// The lowercased file extension of a resource, taken from its basename (the
/// last path segment) with any `?query`/`#fragment` stripped — so it works for
/// URLs (`…/main.rs?raw=1` → `rs`) as well as plain paths.
fn resource_ext(resource: &str) -> Option<String> {
    let basename = resource.rsplit(['/', '\\']).next().unwrap_or(resource);
    let basename = basename.split(['?', '#']).next().unwrap_or(basename);
    basename
        .rsplit_once('.')
        .map(|(_, ext)| ext.to_ascii_lowercase())
        .filter(|ext| !ext.is_empty())
}

/// The maximum *decoded* response body we will hold in memory, in bytes.
/// Exceeding it is a hard error (we never render a truncated resource).
#[cfg(feature = "fetch")]
const MAX_BODY_BYTES: u64 = 16 * 1024 * 1024;

/// Fetch a URL over HTTP(S), returning `(body, content_type)`. Port of
/// rich-cli's `requests.get`, with two deliberate safety bounds upstream lacks:
/// a 30-second global timeout and [`MAX_BODY_BYTES`].
///
/// Like `requests.get`, a non-2xx status is **not** an error — the body is
/// returned so an error page still renders. TLS verification is on (rustls,
/// trusting the system's certificate store, and the bundled webpki roots only
/// when that store cannot be used: `rich_marketplace::tls`).
#[cfg(feature = "fetch")]
fn fetch_url(url: &str, encoding: Option<Encoding>) -> Result<(String, Option<String>), String> {
    use std::time::Duration;
    // Redirects (ten, as `requests` and ureq allow) are followed one request
    // at a time: `rich_marketplace::redirect` says why. Once a hop is
    // `https://`, a redirect to `http://` is refused before it is requested
    // (`requests` follows it): what was asked for over TLS is not fetched in
    // the clear. An `http://` URL given as such is still fetched.
    let budget = Duration::from_secs(30);
    let mut secure = false;
    let mut response =
        rich_marketplace::redirect::get_following(url, 10, false, budget, |hop, deadline| {
            let https = is_https(hop);
            if secure && !https {
                return Err(FetchFailure::Downgrade(hop.to_string()));
            }
            secure |= https;
            rich_marketplace::tls::with_fallback(|trust| {
                ureq::get(hop)
                    .config()
                    // One 30-second budget for the whole chain and its body.
                    .timeout_global(Some(deadline.remaining()?))
                    // Match `requests.get`: don't turn 4xx/5xx into an error, so the
                    // response body (often a useful error page) is rendered instead.
                    .http_status_as_error(false)
                    .max_redirects(0)
                    .tls_config(trust.tls_config())
                    .build()
                    .call()
            })
            .map_err(FetchFailure::Trust)
        })
        .map_err(|err| match err {
            FetchFailure::Trust(err) => format!("cannot fetch {url}: {err}"),
            FetchFailure::Downgrade(to) => format!(
                "cannot fetch {url}: refused its redirect from https:// to {to}, which is not \
                 encrypted (fetch the http:// address itself if that is intended)"
            ),
        })?;
    let content_type = response
        .headers()
        .get("content-type")
        .and_then(|value| value.to_str().ok())
        .map(str::to_string);

    // Bound the *decoded* body: `.reader()` yields post-decompression bytes, so
    // capping it here (rather than via ureq's `limit()`, whose LimitReader sits
    // *under* the gzip decoder and would only bound compressed bytes) also
    // defuses a `Content-Encoding: gzip` bomb. Read one byte past the limit so
    // an oversized body is detectable rather than silently truncated.
    let mut buffer = Vec::new();
    response
        .body_mut()
        .with_config()
        .reader()
        .take(MAX_BODY_BYTES + 1)
        .read_to_end(&mut buffer)
        .map_err(|err| format!("cannot read {url}: {err}"))?;
    if buffer.len() as u64 > MAX_BODY_BYTES {
        return Err(format!(
            "{url} exceeds the {} MiB limit",
            MAX_BODY_BYTES / (1024 * 1024)
        ));
    }
    let body =
        decode_strict(buffer, encoding).map_err(|err| format!("cannot decode {url}: {err}"))?;
    Ok((body, content_type))
}

/// Why [`fetch_url`]'s redirect chain stopped.
#[cfg(feature = "fetch")]
enum FetchFailure {
    /// A request failed (with the system's roots, and the bundled ones when
    /// the system store could not be used).
    Trust(rich_marketplace::tls::TrustError),
    /// A redirect from `https://` to this `http://` URL.
    Downgrade(String),
}

#[cfg(feature = "fetch")]
impl From<ureq::Error> for FetchFailure {
    fn from(error: ureq::Error) -> Self {
        FetchFailure::Trust(error.into())
    }
}

/// Whether `url`'s scheme is `https`, in any case.
#[cfg(feature = "fetch")]
fn is_https(url: &str) -> bool {
    url.get(..8)
        .is_some_and(|s| s.eq_ignore_ascii_case("https://"))
}

/// Stub used when the crate is built without the `fetch` feature.
#[cfg(not(feature = "fetch"))]
fn fetch_url(url: &str, _encoding: Option<Encoding>) -> Result<(String, Option<String>), String> {
    Err(format!(
        "cannot fetch {url}: this build has no URL support (rebuild with the `fetch` feature)"
    ))
}

/// The high-level render mode implied by a response `Content-Type` (the MIME
/// type, ignoring any `; charset=…`). Used only when neither a flag nor the URL
/// extension already picked a mode.
fn content_type_mode(content_type: &str) -> Option<Mode> {
    let mime = mime_of(content_type);
    match mime.as_str() {
        "text/markdown" | "text/x-markdown" => Some(Mode::Markdown),
        "text/x-rst" | "text/prs.fallenstein.rst" => Some(Mode::Rst),
        "text/org" | "text/x-org" => Some(Mode::Org),
        "text/asciidoc" | "text/x-asciidoc" => Some(Mode::AsciiDoc),
        "text/troff" | "application/x-troff" | "application/x-troff-man" | "text/x-troff-man" => {
            Some(Mode::Man)
        }
        "application/json" | "text/json" => Some(Mode::Json),
        "text/csv" => Some(Mode::Csv),
        _ => None,
    }
}

/// A syntect lexer name for a response `Content-Type`, for syntax-highlighting a
/// fetched resource that has no informative extension. A small common subset of
/// upstream's Pygments MIME table.
fn content_type_lexer(content_type: &str) -> Option<&'static str> {
    let mime = mime_of(content_type);
    Some(match mime.as_str() {
        "text/html" | "application/xhtml+xml" => "html",
        "text/css" => "css",
        "application/javascript" | "text/javascript" => "javascript",
        "application/xml" | "text/xml" => "xml",
        "text/x-python" | "application/x-python" | "text/x-python3" => "python",
        "text/x-rust" => "rust",
        "text/x-c" | "text/x-csrc" => "c",
        "application/x-sh" | "text/x-shellscript" => "bash",
        "application/x-yaml" | "text/yaml" | "text/x-yaml" => "yaml",
        "application/toml" | "text/x-toml" => "toml",
        _ => return None,
    })
}

/// Whether an extension names no particular language, so a `Content-Type` that
/// does should win when picking a syntax lexer.
fn is_uninformative_ext(ext: &str) -> bool {
    matches!(ext, "txt" | "text" | "log" | "dat" | "out")
}

/// The bare MIME type from a `Content-Type` header (lowercased, `; charset=…`
/// and surrounding whitespace stripped).
fn mime_of(content_type: &str) -> String {
    content_type
        .split(';')
        .next()
        .unwrap_or("")
        .trim()
        .to_ascii_lowercase()
}

/// Resolve `Mode::Auto` to a concrete mode from the resource's file extension.
/// Whether `--filter` and `--highlight` apply in `mode`: plain text,
/// `--print`, `--syntax` and `--inspect`.
fn transforms_apply(mode: Mode) -> bool {
    matches!(
        mode,
        Mode::Auto | Mode::Print | Mode::Syntax | Mode::Inspect
    )
}

/// The usage error for a transform option `mode` does not take: any of them
/// outside [`transforms_apply`], and `--transform` (text only) with
/// `--inspect`.
fn transform_misplaced_in(cli: &Cli, mode: Mode) -> Option<String> {
    if let Some(flag) = cli
        .data
        .transform_option()
        .filter(|_| !transforms_apply(mode))
    {
        return Some(transforms_misplaced(flag, mode));
    }
    (mode == Mode::Inspect && !cli.data.transforms().is_empty())
        .then(|| cli.data.check_transforms(true).unwrap_err())
}

fn transforms_misplaced(flag: &str, mode: Mode) -> String {
    format!(
        "{flag} only has an effect on {}, not {}",
        transform_modes(flag),
        mode_name(mode)
    )
}

/// Where a transform option applies: `--transform` rewrites text only.
fn transform_modes(flag: &str) -> &'static str {
    if flag == "--transform" {
        "text, --print or --syntax"
    } else {
        "text, --print, --syntax or --inspect"
    }
}

fn detect_mode(resource: Option<&str>) -> Mode {
    match resource.and_then(resource_ext).as_deref() {
        Some("md") | Some("markdown") => Mode::Markdown,
        Some("json") => Mode::Json,
        Some("csv") | Some("tsv") => Mode::Csv,
        Some("ipynb") => Mode::Ipynb,
        Some("rst") => Mode::Rst,
        // Not upstream (documents.rs). A URL with no path has no extension:
        // `https://example.org` is a web page, not an Org file.
        Some("org") if !resource.is_some_and(documents::bare_host) => Mode::Org,
        Some("adoc" | "asciidoc") => Mode::AsciiDoc,
        Some("man" | "roff" | "mdoc") => Mode::Man,
        Some("gif") => Mode::Gif,
        Some("mmd") | Some("mermaid") if cfg!(feature = "mermaid") => Mode::Mermaid,
        Some("dot") | Some("gv") => Mode::Dot,
        // Anything the table above does not divert is source code, and upstream
        // highlights it: `rich main.rs` is syntax-highlighted with no flag at
        // all. We printed it raw instead, so `rich hello.py` produced no
        // highlighting and no styling in an export — while `docs/cli.md` line 12
        // advertised the upstream behaviour and `--help` documented ours. The
        // two contradicted each other; this resolves them the way the docs (and
        // upstream) say.
        Some(_) => Mode::Syntax,
        // No extension to go on (including stdin): stay in Auto and let the
        // caller decide, rather than guessing a lexer for something that may not
        // be source at all.
        None => Mode::Auto,
    }
}

/// Force a renderable to a fixed width, wherever on the screen it lands. Port
/// of rich-cli's `ForceWidth`.
///
/// `--width N` used to shrink the *console* to N, which also moved every
/// alignment inside N columns: `rich -w 20 --center` centred within 20 rather
/// than within the terminal, and an `--export-svg` frame came out N wide.
/// Upstream leaves the console alone and narrows only the renderable.
struct ForceWidth {
    child: Box<dyn Renderable>,
    width: usize,
}

impl Renderable for ForceWidth {
    fn rich_render(&self, console: &Console, options: &ConsoleOptions) -> Vec<Segment> {
        self.child
            .rich_render(console, &options.update_width(self.width))
    }

    fn measure(&self, _console: &Console, _options: &ConsoleOptions) -> Measurement {
        Measurement::new(self.width, self.width)
    }
}

/// Position a renderable within the available width. Port of the horizontal
/// axis of `rich.align.Align`, which is what `console.print(justify=…)` wraps
/// every renderable in.
///
/// The core crate's [`Align`] follows upstream: it constrains the child to its
/// measured width, `set_shape`s the block, then pads it. But in this port
/// `Table`, `Json` and friends measure as the whole console (see
/// `measure_rendered`), so core `Align` would not move them. This wrapper takes
/// the width to constrain to from the caller instead.
struct Aligned {
    child: Box<dyn Renderable>,
    /// The width to render the child *within* — what upstream's `Align` reads
    /// out of `console.measure(renderable)` and hands to `Constrain`. The block
    /// it then pads is measured from the output, not from this: a `--csv` table
    /// given `-w 40` still renders at its own 23 columns, and it is 23 that gets
    /// centred.
    width: usize,
    justify: Justify,
}

impl Renderable for Aligned {
    fn rich_render(&self, console: &Console, options: &ConsoleOptions) -> Vec<Segment> {
        let width = self.width.clamp(1, options.max_width);
        // The child renders with the console's own justify, not this alignment.
        // Upstream puts `print(justify=…)` into the render options, but rich-cli
        // builds its `--print`/`--rule` text with an explicit `justify="default"`
        // — a truthy string in Python — which blocks the inheritance, so
        // `-w 9 --center -p mid` centres a three-cell block within the terminal
        // rather than centring "mid" inside nine columns first. Every other
        // renderable this CLI builds (`Table`, `Json`, `Syntax`, `Markdown`)
        // ignores `options.justify` in this port, so there is nothing else for
        // the inheritance to reach.
        let lines = console.render_lines(self.child.as_ref(), &options.update_width(width), false);
        let widths: Vec<usize> = lines
            .iter()
            .map(|line| line.iter().map(Segment::cell_length).sum())
            .collect();
        // `Segment.get_shape` then `Segment.set_shape`: square the block off at
        // the widest line it actually produced, so a multi-line child moves as
        // one block instead of each line drifting to its own width.
        let shape = widths.iter().copied().max().unwrap_or(0);

        let excess = options.max_width.saturating_sub(shape);
        let (left, right) = match self.justify {
            Justify::Right => (excess, 0),
            Justify::Center => (excess / 2, excess - excess / 2),
            _ => (0, excess),
        };
        let blank = |count: usize| Segment::new(" ".repeat(count), Some(Style::new()));

        let mut segments = Vec::new();
        let last = lines.len().saturating_sub(1);
        for (index, (line, line_width)) in lines.into_iter().zip(widths).enumerate() {
            if left > 0 {
                segments.push(blank(left));
            }
            segments.extend(line);
            let pad = shape - line_width + right;
            if pad > 0 {
                segments.push(blank(pad));
            }
            if index != last {
                segments.push(Segment::line());
            }
        }
        segments
    }
}

/// The width a renderable actually occupies, found by rendering it.
///
/// `Table`, `Json` and friends inherit `(max_width, max_width)` from the
/// `Renderable` default in the core crate, so asking them to measure themselves
/// always answers "the whole console" and a fitted panel would not shrink at
/// all. Neither pads its output to the space it is given, though, so the widest
/// rendered line *is* upstream's `Measurement.get(…).maximum`, clamped to the
/// console — which is what a fitted `Panel` needs.
///
/// Not usable for `Syntax`, whose lines *are* padded out to the full width by
/// its background: that one is measured from the source instead.
fn measure_rendered(console: &Console, renderable: &dyn Renderable) -> usize {
    console
        .render_lines(renderable, &console.options(), false)
        .iter()
        .map(|line| line.iter().map(Segment::cell_length).sum::<usize>())
        .max()
        .unwrap_or(0)
}

/// Only labels consumed by a panel or CSV table should be parsed. Other modes
/// ignore these options upstream, including malformed unused markup.
/// Whether something in this run expanded `:micro:` tokens whose
/// placeholders are still to be drawn.
fn micro_pending() -> bool {
    #[cfg(feature = "art")]
    return micro::drawing_pending();
    #[cfg(not(feature = "art"))]
    false
}

fn validate_labels(cli: &Cli) -> Result<(), String> {
    for label in cli.title.iter().chain(cli.caption.iter()) {
        Text::from_markup(label).map_err(|err| err.to_string())?;
    }
    Ok(())
}

/// Apply upstream's decorator chain — padding, panel, style, fixed width,
/// alignment — and print the result. Port of the tail of rich-cli's `main`.
///
/// `fit` is the width the renderable measures at; `None` means "fills whatever
/// it is given", which is what a `Markdown` reports, so nothing shrinks to it.
fn decorate_and_emit(
    cli: &Cli,
    console: &Console,
    export: &Export,
    renderable: Box<dyn Renderable>,
    fit: Option<usize>,
) -> ExitCode {
    decorate_and_emit_with(cli, console, export, renderable, fit, emit_exit_code)
}

/// [`decorate_and_emit`], with `finish` turning the print and export result
/// into the exit code (and its report).
fn decorate_and_emit_with(
    cli: &Cli,
    console: &Console,
    export: &Export,
    renderable: Box<dyn Renderable>,
    fit: Option<usize>,
    finish: impl FnOnce(&Cli, Result<(), String>) -> ExitCode,
) -> ExitCode {
    if cli.panel.is_some()
        && let Err(err) = validate_labels(cli)
    {
        return fail(cli, ExitClass::Data, err);
    }
    let max_width = console.width();
    // `if width > 0: expand = True` — a fixed width is a width to fill.
    let expand = cli.expand || cli.width.is_some();
    let mut renderable = renderable;
    let mut fit = fit;

    // This port's `Padding` and `Panel` always fill the width they are given, so
    // a *fitted* box is a `Constrain` around one. Upstream instead passes
    // `expand=False` and lets the box measure its own child — the same width,
    // reached from the outside, which is the only way that works while the core
    // crate's `Table`/`Syntax`/`Json` still inherit the default measurement.
    if let Some((top, right, bottom, left)) = cli.padding {
        let padded: Box<dyn Renderable> =
            Box::new(Padding::new(renderable, (top, right, bottom, left)));
        // `Padding.__rich_measure__`: the child plus the horizontal padding,
        // capped at the available width.
        fit = fit.map(|width| (width + left + right).min(max_width));
        renderable = if expand {
            padded
        } else {
            Box::new(Constrain::new(padded, fit))
        };
    }

    if let Some(box_set) = cli.panel {
        let mut panel = Panel::new(renderable).box_set(box_set);
        // `:micro:name:` in a label expands where its `:emoji:` codes do:
        // always, as `Text.from_markup` replaces them.
        #[cfg(feature = "art")]
        let micro_label = |label: &Option<String>| {
            label
                .as_deref()
                .and_then(|label| micro::panel_label(console, label, cli.micro_project))
        };
        #[cfg(not(feature = "art"))]
        let micro_label = |_: &Option<String>| None::<Text>;
        let micro_title = micro_label(&cli.title);
        if let Some(title) = micro_title.clone() {
            panel = panel.title_as_text(title);
        } else if let Some(title) = cli.title.clone() {
            panel = panel.title(title);
        }
        if let Some(caption) = micro_label(&cli.caption) {
            panel = panel.subtitle_as_text(caption);
        } else if let Some(caption) = cli.caption.clone() {
            panel = panel.subtitle(caption);
        }
        if let Some(style) = cli.panel_style.clone() {
            panel = panel.border_style(style);
        }
        // `Panel.__rich_measure__`: the wider of the child (measured in
        // `max_width - 4`) and the title, plus a border and a pad on each side.
        // The *subtitle* is deliberately absent — upstream does not measure it,
        // so a long `--caption` is truncated by the border rather than widening
        // the panel.
        //
        // Panel parses markup, normalizes newlines/tabs, and pads the label by
        // one cell on either side. Measure visible text with the same rules.
        let inner = max_width.saturating_sub(4);
        let child = fit.unwrap_or(inner).min(inner);
        let title_width = cli
            .title
            .as_deref()
            .map(|title| {
                // `Text.from_markup(title)` replaces emoji codes whatever the
                // console's `emoji`, so the title draws (and measures) them.
                let mut title = match &micro_title {
                    Some(title) => {
                        let mut flat = title.blank_copy();
                        flat.append(&title.plain().replace('\n', " "), None);
                        flat
                    }
                    None => {
                        let title = rich::emoji::replace(title);
                        Text::from_markup(&title.replace('\n', " "))
                            .expect("title markup validated before rendering")
                    }
                };
                title.expand_tabs(8);
                cell_len(title.plain()) + 2
            })
            .unwrap_or(0);
        fit = Some(child.max(title_width) + 4);
        let panel: Box<dyn Renderable> = Box::new(panel);
        renderable = if expand {
            panel
        } else {
            Box::new(Constrain::new(panel, fit))
        };
    }

    // `-s/--style` lays a style under everything, outside the panel — upstream's
    // `Styled(renderable, text_style)`. It does not change any width.
    if let Some(style) = cli.style.clone() {
        renderable = Box::new(Styled::new(renderable, style));
    }

    // `if width > 0 and not pager` — the pager lays out at its own width.
    if let Some(width) = cli.width.filter(|_| !cli.pager) {
        renderable = Box::new(ForceWidth {
            child: renderable,
            width,
        });
        fit = Some(width);
    }

    if let Some(justify) = cli.justify {
        renderable = Box::new(Aligned {
            child: renderable,
            width: fit.unwrap_or(max_width),
            justify,
        });
    }

    // Micro assets are drawn only when the output goes to the terminal alone:
    // an export, the pager or a watch would record (or repaint over) Kitty's
    // placeholder cells or the blank cells under an image, so they (and the
    // terminal with them) keep the fallback.
    #[cfg(feature = "art")]
    if let Some(registry) =
        micro::take_drawing().filter(|_| export.terminal_only() && !watch::watching())
    {
        renderable = micro::drawn(console, registry, renderable);
    }

    // Upstream's final `console.print(renderable, width=max_width or None,
    // soft_wrap=soft)`.
    let mut options = console.options();
    if let Some(max_width) = cli.max_width {
        options.max_width = max_width.min(options.max_width);
    }
    let shown = if cli.soft {
        let mut segments = soft_wrap_segments(console, renderable.as_ref(), &options);
        if !segments.is_empty() {
            segments.push(Segment::line());
        }
        emit_segments(console, export, segments)
    } else {
        emit(console, export, |c| {
            c.print_with(renderable.as_ref(), &options)
        })
    };
    finish(cli, shown)
}

/// What `console.print(renderable, soft_wrap=True)` writes: nothing wraps
/// (`no_wrap`, `overflow="ignore"`) and, with `crop=False`, no line is cut at
/// the console width, so the terminal wraps it. Core's print always crops,
/// so this follows its print path (a printed text is joined, a renderable
/// that asks is fitted to its measurement) and stops short of the crop.
fn soft_wrap_segments(
    console: &Console,
    renderable: &dyn Renderable,
    options: &ConsoleOptions,
) -> Vec<Segment> {
    let mut options = options.clone();
    options.no_wrap.get_or_insert(true);
    options
        .overflow
        .get_or_insert(rich::console::Overflow::Ignore);
    let joined = renderable.printed_text();
    let renderable: &dyn Renderable = match &joined {
        Some(text) => text,
        None => renderable,
    };
    if renderable.fit_to_measurement() {
        let measurement = renderable.measure(console, &options);
        options.max_width = measurement.maximum.min(options.max_width).max(1);
    }
    console.render(renderable, Some(&options))
}

fn run_cli(cli: Cli) -> ExitCode {
    if cli.watch {
        return run_watch(cli);
    }
    run_once(cli)
}

fn run_watch(mut cli: Cli) -> ExitCode {
    let Some(resource) = cli.resource.clone() else {
        return fail(
            &cli,
            ExitClass::Usage,
            "--watch requires a file path or URL",
        );
    };
    let several = cli.resources.len() > 1;
    for resource in &cli.resources {
        if resource == "-" || (cli.mode == Mode::Print && !is_url(resource)) {
            return fail(
                &cli,
                ExitClass::Usage,
                "--watch requires a local file or URL, not stdin or literal markup",
            );
        }
        if several && is_url(resource) {
            return fail(
                &cli,
                ExitClass::Usage,
                "--watch with several resources requires local files; watch a URL on its own",
            );
        }
        let effective_mode = if cli.mode == Mode::Auto {
            detect_mode(Some(resource))
        } else {
            cli.mode
        };
        if effective_mode.draws_directly() || effective_mode == Mode::Rule {
            return fail(
                &cli,
                ExitClass::Usage,
                "--watch requires a resource-backed render mode",
            );
        }
    }
    if several
        && (cli.export_html.is_some() || cli.export_svg.is_some() || cli.export_png.is_some())
    {
        return fail(
            &cli,
            ExitClass::Usage,
            "--export-html/--export-svg/--export-png cannot be combined with watching several \
             files",
        );
    }
    // Redirected output must be a finite, deterministic command. This also
    // keeps `rich --watch file > snapshot.txt` from hanging in a pipeline.
    // Several files render once each, in order, exactly as separate runs.
    if !std::io::stdout().is_terminal() {
        cli.watch = false;
        if !several {
            return run_once(cli);
        }
        let mut first_failure = None;
        for resource in cli.resources.clone() {
            let mut single = cli.clone();
            single.resource = Some(resource.clone());
            single.resources = vec![resource];
            let status = run_once(single);
            if status != ExitClass::Success.exit_code() && first_failure.is_none() {
                first_failure = Some(status);
            }
        }
        return first_failure.unwrap_or_else(|| ExitClass::Success.exit_code());
    }
    // From here on the output repaints: micro assets keep their fallback.
    if cfg!(target_os = "wasi") {
        return fail(&cli, ExitClass::Usage, host::unavailable("--watch"));
    }
    watch::start_watching();
    let resource = resource.as_str();
    if !is_url(resource) {
        return watch::watch_files(cli);
    }
    // Only URLs remain: they keep the polling-only loop below.
    if is_url(resource) {
        #[cfg(not(feature = "fetch"))]
        {
            cli.watch = false;
            return run_once(cli);
        }
    }

    let interval = std::time::Duration::from_secs_f64(cli.watch_interval);
    let mut previous = None;
    loop {
        #[cfg(feature = "fetch")]
        let cached = if is_url(resource) && cli.watch_cache {
            Some(fetch_url(resource, cli.extensions.encoding))
        } else {
            None
        };
        #[cfg(not(feature = "fetch"))]
        let cached: Option<Result<(String, Option<String>), String>> = None;
        let fingerprint = match cached.as_ref() {
            Some(Ok((body, content_type))) => {
                use std::hash::{Hash, Hasher};
                let mut hasher = std::collections::hash_map::DefaultHasher::new();
                body.hash(&mut hasher);
                content_type.hash(&mut hasher);
                format!("url:{:x}", hasher.finish())
            }
            Some(Err(error)) => format!("url-error:{error}"),
            None => watch_fingerprint(resource, false, cli.extensions.encoding),
        };
        let changed = previous.as_ref() != Some(&fingerprint);
        if changed || (is_url(resource) && !cli.watch_cache) {
            previous = Some(fingerprint);
            // Each watch frame owns the viewport; clear stale rows when a
            // replacement is shorter, then start the new frame at the top.
            let console = crate::console_builder().build();
            console.clear();
            console.control(&Control::home());
            let _ = std::io::stdout().flush();
            let mut iteration = cli.clone();
            iteration.watch = false;
            let status = run_once_with_fetch(iteration, cached.and_then(Result::ok));
            if status != ExitClass::Success.exit_code() {
                // A temporary disappearance or parse failure is a frame error,
                // not a reason to abandon a watch that may recover.
                eprintln!("rich: watch will retry after the next change");
            }
        }
        std::thread::sleep(interval);
    }
}

fn watch_fingerprint(resource: &str, cache_url: bool, encoding: Option<Encoding>) -> String {
    if is_url(resource) {
        #[cfg(feature = "fetch")]
        if cache_url {
            return match fetch_url(resource, encoding) {
                Ok((body, content_type)) => {
                    use std::hash::{Hash, Hasher};
                    let mut hasher = std::collections::hash_map::DefaultHasher::new();
                    body.hash(&mut hasher);
                    content_type.hash(&mut hasher);
                    format!("url:{:x}", hasher.finish())
                }
                Err(error) => format!("url-error:{error}"),
            };
        }
        #[cfg(not(feature = "fetch"))]
        let _ = (cache_url, encoding);
        return "url".to_string();
    }
    match std::fs::metadata(fs_path(resource)) {
        Ok(metadata) if metadata.is_file() => {
            use std::hash::Hasher;
            // Atomic saves and in-place writes may preserve both size and
            // mtime. Read regular files each poll using a fixed-size buffer,
            // so detection is portable and memory does not grow with input.
            let mut file = match std::fs::File::open(fs_path(resource)) {
                Ok(file) => file,
                Err(error) => return format!("file-error:{error}"),
            };
            let mut hasher = std::collections::hash_map::DefaultHasher::new();
            let mut buffer = [0u8; 64 * 1024];
            loop {
                match file.read(&mut buffer) {
                    Ok(0) => break,
                    Ok(count) => hasher.write(&buffer[..count]),
                    Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue,
                    Err(error) => return format!("file-error:{error}"),
                }
            }
            format!("file:{:x}", hasher.finish())
        }
        Ok(_) => "not-file".to_string(),
        Err(_) => "missing".to_string(),
    }
}

fn run_once(cli: Cli) -> ExitCode {
    run_once_with_fetch(cli, None)
}

/// The console theme: the default theme, then `--theme-file`, then config
/// themes and `--theme-style` bindings, each overriding the one before.
fn cli_theme(cli: &Cli) -> rich::Theme {
    let mut theme = rich::Theme::default_theme();
    for (name, style) in cli.theme_file_styles.iter().chain(&cli.theme_styles) {
        theme.insert(name.clone(), style.clone());
    }
    theme
}

impl Cli {
    /// Whether any option changes the console theme.
    fn themed(&self) -> bool {
        !self.theme_styles.is_empty() || !self.theme_file_styles.is_empty()
    }
}

/// Read an upstream theme file (`Theme.read`: a `[styles]` section of
/// `name = style` lines). Errors name the file and, where the file has one,
/// the offending line, after `label` (`--theme-file PATH`, or the config
/// setting that named it).
///
/// Only a regular file of at most [`controls::THEME_FILE_LIMIT`] is read: a
/// FIFO would block every run and `/dev/zero` would never end.
fn read_theme_file(
    path: &str,
    label: &str,
) -> Result<std::collections::BTreeMap<String, Style>, String> {
    let limit = controls::THEME_FILE_LIMIT;
    // A path that is not valid Unicode is read by its own bytes.
    let path = &fs_path(path);
    // Checked before opening: opening a FIFO blocks until a writer appears.
    let metadata = std::fs::metadata(path).map_err(|err| format!("{label}: {err}"))?;
    if !metadata.is_file() {
        return Err(format!("{label}: not a regular file"));
    }
    let too_large = || {
        format!(
            "{label}: larger than {}, the most read from a theme file",
            controls::size(limit)
        )
    };
    if metadata.len() > limit {
        return Err(too_large());
    }
    let file = std::fs::File::open(path).map_err(|err| format!("{label}: {err}"))?;
    let mut bytes = Vec::new();
    file.take(limit + 1)
        .read_to_end(&mut bytes)
        .map_err(|err| format!("{label}: {err}"))?;
    if bytes.len() as u64 > limit {
        return Err(too_large());
    }
    let text = String::from_utf8(bytes).map_err(|err| format!("{label}: {err}"))?;
    let theme = rich::Theme::from_file(&text, false).map_err(|err| match &err {
        // Structural errors already say which line.
        rich::errors::RichError::ThemeConfig(_) => format!("{label}: {err}"),
        _ => match bad_style_line(&text) {
            Some(line) => format!("{label}: line {line}: {err}"),
            None => format!("{label}: {err}"),
        },
    })?;
    Ok(theme
        .names()
        .filter_map(|name| Some((name.to_owned(), theme.get(name)?.clone())))
        .collect())
}

/// The 1-based line of the first `name = style` in `[styles]` whose style
/// does not parse, for pointing at a style error.
fn bad_style_line(text: &str) -> Option<usize> {
    let mut in_styles = false;
    for (index, line) in text.lines().enumerate() {
        let trimmed = line.trim();
        if trimmed.starts_with('[') {
            in_styles = trimmed.eq_ignore_ascii_case("[styles]");
            continue;
        }
        if !in_styles || trimmed.starts_with(['#', ';']) || line.starts_with([' ', '\t']) {
            continue;
        }
        let Some((_, value)) = trimmed.split_once(['=', ':']) else {
            continue;
        };
        if Style::parse(value.trim()).is_err() {
            return Some(index + 1);
        }
    }
    None
}

fn run_once_with_fetch(mut cli: Cli, prefetched: Option<(String, Option<String>)>) -> ExitCode {
    if cli.sanitize {
        cli.title = cli
            .title
            .take()
            .map(|title| sanitize_terminal_controls(&title));
        cli.caption = cli
            .caption
            .take()
            .map(|caption| sanitize_terminal_controls(&caption));
    }

    if cli.batch {
        return run_batch(&cli);
    }

    // With no flags and no resource, show the capability demo.
    if cli.mode == Mode::Auto && cli.resource.is_none() {
        run_demo(cli.no_color, std::time::Duration::ZERO);
        return success(&cli);
    }

    let mut mode = match cli.mode {
        Mode::Auto => detect_mode(cli.resource.as_deref()),
        other => other,
    };
    if let Some(message) = transform_misplaced_in(&cli, mode) {
        return fail(&cli, ExitClass::Usage, message);
    }
    // A compressed man page (`ls.1.gz`) would print as binary noise.
    if matches!(cli.mode, Mode::Auto | Mode::Man)
        && let Some(message) = cli
            .resource
            .as_deref()
            .and_then(documents::compressed_man_page)
    {
        return fail(&cli, ExitClass::Input, message);
    }

    // `view` decides what to show from the resource itself: an existing
    // renderer, a numbered source view, or a hex dump of binary input. The
    // resource is read once, here, so stdin is not read twice.
    let mut prefetched = prefetched;
    let mut view_as = None;
    let mut view_bytes = Vec::new();
    if mode == Mode::View {
        let ext = cli
            .resource
            .as_deref()
            .filter(|r| *r != "-")
            .and_then(resource_ext);
        // Images and logs are read by their own renderers; anything else is
        // read here, up to a limit, and sniffed.
        let by_name = viewers::detect(ext.as_deref(), cli.resource.as_deref(), b"");
        if !matches!(
            by_name,
            viewers::ViewAs::Image | viewers::ViewAs::Gif | viewers::ViewAs::Log
        ) {
            // A notebook is one JSON document, often large with its outputs:
            // cutting it short would only make it invalid.
            let limit = if by_name == viewers::ViewAs::Notebook {
                controls::INSPECT_LIMIT
            } else {
                controls::VIEW_LIMIT
            };
            let more;
            (view_bytes, more) = match read_window(&cli, 0, limit) {
                Ok(read) => read,
                Err(err) => return fail(&cli, ExitClass::Input, err),
            };
            let name = cli.resource.as_deref().unwrap_or("<stdin>");
            let kind = viewers::detect(ext.as_deref(), cli.resource.as_deref(), &view_bytes);
            if kind == viewers::ViewAs::Binary {
                if more || view_bytes.len() as u64 > controls::BYTES_LIMIT {
                    view_bytes.truncate(controls::BYTES_LIMIT as usize);
                    viewers::notice(
                        name,
                        &controls::size(controls::BYTES_LIMIT),
                        "use rich hex with --offset and --length for the rest",
                    );
                }
            } else if let Some(end) = viewers::line_end(&view_bytes, controls::LINE_LIMIT)
                .filter(|_| matches!(kind, viewers::ViewAs::Source(_) | viewers::ViewAs::Patch))
            {
                // Numbered source and patches render line by line.
                view_bytes.truncate(end);
                viewers::notice(
                    name,
                    &format!("{} lines", controls::LINE_LIMIT),
                    "use a pager or rich --syntax for the whole file",
                );
            } else if more {
                viewers::notice(
                    name,
                    &controls::size(limit),
                    "use a pager or rich --syntax for the whole file",
                );
            }
        }
        let mut kind = viewers::detect(ext.as_deref(), cli.resource.as_deref(), &view_bytes);
        // An animated WebP plays, as a GIF does; a still one is an image.
        if kind == viewers::ViewAs::Image
            && ext.as_deref() == Some("webp")
            && cli
                .resource
                .as_deref()
                .is_some_and(|r| !is_url(r) && viewers::animated_webp(&fs_path(r)))
        {
            kind = viewers::ViewAs::Gif;
        }
        mode = match kind {
            viewers::ViewAs::Markdown => Mode::Markdown,
            viewers::ViewAs::Csv => Mode::Csv,
            viewers::ViewAs::Notebook => Mode::Ipynb,
            viewers::ViewAs::Image => Mode::Image,
            viewers::ViewAs::Gif => Mode::Gif,
            viewers::ViewAs::Log => Mode::Log,
            _ => Mode::View,
        };
        let text = String::from_utf8_lossy(&view_bytes).into_owned();
        prefetched = Some((text, None));
        view_as = Some(kind);
    }

    // Modes that render incrementally write directly to the console instead of
    // composing one renderable, so no `ForceWidth` wrapper can reach them.
    // Upstream's `Console(emoji=emoji, force_terminal=…)`: emoji codes stay
    // as typed unless `--emoji` is given.
    let mut builder = crate::console_builder()
        .no_color(cli.no_color)
        .emoji(cli.emoji);
    if cli.themed() {
        builder = builder.theme(cli_theme(&cli));
    }
    // Parallel workers spool output, but render for the parent's destination.
    // Pager policy still checks the real stdout handle before starting a pager.
    if let Ok(terminal) = std::env::var("RS_RICH_BATCH_TERMINAL") {
        builder = builder.force_terminal(terminal == "1");
    }
    if cli.force_terminal {
        builder = builder.force_terminal(true);
    }
    if let Some(width) = cli.width.filter(|_| mode.draws_directly()) {
        builder = builder.width(width);
    }
    // A watched resource renders into a live region, one column narrower than
    // the terminal (the Live display keeps the last column free).
    if let Some(width) = watch::capture_width() {
        builder = builder.width(width);
    }
    let mut console = builder.build();
    render_target::attach(&mut console);
    install_render_defaults(&mut console);
    plugins::install_highlighters(&mut console);
    apply_code_highlighting(&mut console, &cli);

    if mode == Mode::Rule
        && let Some(title) = &cli.resource
        && let Err(err) = Text::from_markup(title)
    {
        return fail(&cli, ExitClass::Data, err.to_string());
    }

    // SVG export needs a title (the resource's basename, else "rich") and a
    // stable id. Upstream's auto id hashes Python reprs, so we use a fixed one
    // (see the rich crate's svg module / DIVERGENCES #15). A literal resource
    // (print-mode markup, a rule's title) is not a path, so splitting it on
    // `/` or `\` would title `[b]Hi[/] there` as `] there`: it gets "rich".
    let literal = mode == Mode::Rule
        || (mode == Mode::Print && cli.resource.as_deref().is_some_and(|r| !is_url(r)));
    let mut svg_title = cli
        .resource
        .as_deref()
        .filter(|r| *r != "-" && !literal)
        .map(|r| r.rsplit(['/', '\\']).next().unwrap_or(r).to_string())
        .unwrap_or_else(|| "rich".to_string());
    if cli.sanitize {
        svg_title = sanitize_terminal_controls(&svg_title);
    }
    #[allow(unused_mut)]
    let mut export = Export {
        html_path: cli.export_html.as_deref(),
        svg_path: cli.export_svg.as_deref(),
        png_path: cli.export_png.as_deref(),
        svg_title: &svg_title,
        pager: cli.pager,
        auto_pager: cli.auto_pager,
    };

    // GIF playback consumes the resource list itself (it can take several) and
    // animates rather than rendering once.
    if mode == Mode::Gif {
        return play_gifs(&cli, &console);
    }

    // `--diff` consumes both resources and reports rather than rendering one:
    // perceptually for two images, as a text, source or patch diff otherwise.
    if mode == Mode::Diff {
        let images = cli.resources.len() == 2 && cli.resources.iter().all(|r| looks_like_image(r));
        if !images {
            return run_text_diff(&cli, &console, &export);
        }
        if let Some(flag) = cli.tools.diff_option() {
            return fail(
                &cli,
                ExitClass::Usage,
                format!("{flag} applies to text diffs, not images"),
            );
        }
        #[cfg(feature = "art")]
        return run_diff(&cli, &console, &export);
        #[cfg(not(feature = "art"))]
        return fail(
            &cli,
            ExitClass::Usage,
            "this build has no image support (rebuild with the `art` feature)",
        );
    }

    // `--image` renders a single still image directly through rich-art's
    // `ImageArt` facade rather than composing a decorated renderable.
    #[cfg(feature = "art")]
    if mode == Mode::Image {
        return run_image(&cli, &console, &export);
    }
    #[cfg(not(feature = "art"))]
    if mode == Mode::Image {
        return fail(
            &cli,
            ExitClass::Usage,
            "this build has no image support (rebuild with the `art` feature)",
        );
    }

    if mode.streams_records() {
        return run_json_lines(&cli, &console, mode == Mode::Log);
    }

    // A rule takes its optional title from the resource string directly (no
    // fetch/read) — but it still goes through the decorators, because upstream
    // wraps it like anything else, so `--rule --panel` really does draw a panel.
    if mode == Mode::Rule {
        let mut rule = match cli.resource.as_deref() {
            Some(title) if title != "-" && cli.sanitize => {
                Rule::new(sanitize_terminal_controls(title))
            }
            Some(title) if title != "-" => Rule::new(title),
            _ => Rule::line(),
        };
        // `Rule(resource, style=rule_style, characters=rule_char or "─",
        // align="center" if justify in ("full", "default") else justify)`.
        // Upstream's default is an explicit `bright_green`, not the theme's
        // `rule.line`, so a theme cannot restyle a plain `--rule`.
        let style = cli
            .rule_style
            .clone()
            .unwrap_or_else(|| Style::parse("bright_green").expect("a valid style"));
        rule = rule.style(style);
        if let Some(characters) = cli.rule_char.as_deref().filter(|c| !c.is_empty()) {
            // The line repeats its characters across the terminal, so a
            // control in them acts once per cell unless shown.
            if cli.sanitize {
                rule = rule.characters(sanitize_terminal_controls(characters));
            } else {
                rule = rule.characters(characters);
            }
        }
        match cli.text_justify {
            Some(Justify::Left) => rule = rule.align(rich::align::HorizontalAlign::Left),
            Some(Justify::Right) => rule = rule.align(rich::align::HorizontalAlign::Right),
            _ => {}
        }
        // `Rule.__rich_measure__` is `Measurement(1, 1)`: a rule claims no width
        // of its own, so a fitted panel around one is 5 cells wide.
        return decorate_and_emit(&cli, &console, &export, Box::new(rule), Some(1));
    }

    // The viewer commands that need no text content.
    if mode == Mode::Capture {
        let redactor = match viewers::capture_redactor(&cli.viewers, cli.data.redact()) {
            Ok(redactor) => redactor,
            Err(err) => return fail(&cli, ExitClass::Usage, err),
        };
        let preview = viewers::redact_preview(&cli.viewers);
        if preview && redactor.is_none() {
            return fail(
                &cli,
                ExitClass::Usage,
                "--redact-preview needs --redact or --redact-pattern",
            );
        }
        // The command draws inside the panel: its width, less the two
        // borders and their padding.
        let width = cli
            .width
            .unwrap_or_else(|| console.width())
            .saturating_sub(4)
            .max(1);
        // A recording that cannot be written is found out before the
        // command runs, not after. A preview writes nothing.
        let cast = match viewers::cast_path(&cli.viewers).filter(|_| !preview) {
            Some(path) => match std::fs::File::create(path) {
                Ok(file) => Some((path, file)),
                Err(err) => {
                    return fail(
                        &cli,
                        ExitClass::Input,
                        format!("cannot write {path}: {err}"),
                    );
                }
            },
            None => None,
        };
        let mut captured = match viewers::capture(&cli.resources, width) {
            Ok(captured) => captured,
            Err(err) => return fail(&cli, ExitClass::Input, err),
        };
        if let Some(notice) = &captured.notice {
            eprintln!("rich: capture: {notice}");
        }
        if let (true, Some(redactor)) = (preview, &redactor) {
            let would_write: Vec<String> = [
                viewers::cast_path(&cli.viewers),
                export.html_path,
                export.svg_path,
                export.png_path,
            ]
            .into_iter()
            .flatten()
            .map(str::to_string)
            .collect();
            let previews = redact_preview::capture(&captured, redactor);
            return redact_preview::emit(&cli, &console, previews, &would_write);
        }
        // Before the panel, the exports and the cast see any of it.
        if let Some(redactor) = &redactor {
            captured.redact(redactor);
        }
        if cli.sanitize {
            captured.sanitize();
        }
        if let Some((path, mut file)) = cast {
            let cast = viewers::asciicast(&captured, width, console.height());
            if let Err(err) = file.write_all(cast.as_bytes()) {
                return fail(
                    &cli,
                    ExitClass::Input,
                    format!("cannot write {path}: {err}"),
                );
            }
        }
        let view = viewers::capture_view(&captured);
        let fit = view.measure(&console, &console.options()).maximum;
        // Like `time` or `env`, exit with the command's status once its
        // output is shown and exported, so scripts and CI see a failure.
        let code = captured.exit_code();
        return decorate_and_emit_with(&cli, &console, &export, view, Some(fit), |cli, shown| {
            if code == 0 || shown.is_err() {
                return emit_exit_code(cli, shown);
            }
            // A failed command's report replaces the success envelope.
            if cli.report_format == ReportFormat::Json {
                eprintln!("{}", viewers::capture_report(&captured));
            }
            ExitCode::from(code)
        });
    }
    if mode == Mode::Mermaid && !cfg!(feature = "mermaid") {
        return fail(
            &cli,
            ExitClass::Usage,
            "this build has no Mermaid support (the mermaid feature)",
        );
    }
    if mode == Mode::Env {
        let view = viewers::env(&cli.viewers, &cli.resources);
        let fit = view.measure(&console, &console.options()).maximum;
        return decorate_and_emit(&cli, &console, &export, view, Some(fit));
    }
    if mode == Mode::Profile {
        let profile = match profile::profile(&cli) {
            Ok(profile) => profile,
            Err((class, err)) => return fail(&cli, class, err),
        };
        // As `doctor --report json`: the profile is the stdout document.
        if cli.report_format == ReportFormat::Json {
            let json = serde_json::to_string_pretty(&profile.to_json()).unwrap_or_default();
            authoring::out(&format!("{json}\n"));
            return ExitClass::Success.exit_code();
        }
        let view: Box<dyn Renderable> = Box::new(profile);
        let fit = view.measure(&console, &console.options()).maximum;
        return decorate_and_emit(&cli, &console, &export, view, Some(fit));
    }
    if matches!(mode, Mode::Deps | Mode::Schema | Mode::Chart) {
        let view = match mode {
            Mode::Deps => sources::deps(&cli).map(|deps| (deps.view, deps.gate)),
            Mode::Schema => sources::schema(&cli).map(|view| (view, None)),
            _ => chart::chart(&cli).map(|view| (view, None)),
        };
        let (view, gate) = match view {
            Ok(view) => view,
            Err((class, err)) => return fail(&cli, class, err),
        };
        let fit = view.measure(&console, &console.options()).maximum;
        // A failed gate (`rich deps --audit` with a vulnerability) exits 5
        // once the report is shown, with one report envelope.
        return decorate_and_emit_with(&cli, &console, &export, view, Some(fit), |cli, shown| {
            match gate {
                Some(message) if shown.is_ok() => fail(cli, ExitClass::Gate, message),
                _ => emit_exit_code(cli, shown),
            }
        });
    }
    if matches!(mode, Mode::Hex | Mode::Unicode) {
        // Only the bytes shown are read: an explicit `--length`, else up to
        // the limit, with a notice when more follow.
        let hex = mode == Mode::Hex;
        let offset = cli.viewers.offset().filter(|_| hex).unwrap_or(0);
        let length = cli.viewers.length().filter(|_| hex);
        let max = length.map_or(controls::BYTES_LIMIT, |n| n as u64);
        let (bytes, more) = match read_window(&cli, offset, max) {
            Ok(read) => read,
            Err(err) => return fail(&cli, ExitClass::Input, err),
        };
        if more && length.is_none() {
            let hint = if hex {
                "use --offset and --length for the rest"
            } else {
                "pass a shorter input"
            };
            viewers::notice(
                cli.resource.as_deref().unwrap_or("<stdin>"),
                &controls::size(controls::BYTES_LIMIT),
                hint,
            );
        }
        let view = if hex {
            viewers::hex(&cli.viewers, bytes, offset)
        } else {
            viewers::unicode(&cli.viewers, &bytes)
        };
        let view = match view {
            Ok(view) => view,
            Err(err) => return fail(&cli, ExitClass::Usage, err),
        };
        let fit = view.measure(&console, &console.options()).maximum;
        return decorate_and_emit(&cli, &console, &export, view, Some(fit));
    }

    // Obtain the content: fetch it over HTTP(S) when the resource is a URL,
    // treat it as a literal markup string under `--print`, else read the
    // file/stdin. A URL also yields a `Content-Type` used below.
    let resource_is_url = matches!(cli.resource.as_deref(), Some(r) if is_url(r));
    let (mut content, content_type) = if let Some(fetched) = prefetched {
        fetched
    } else if resource_is_url {
        match fetch_url(cli.resource.as_deref().unwrap(), cli.extensions.encoding) {
            Ok(fetched) => fetched,
            Err(err) => {
                return fail(&cli, ExitClass::Input, err);
            }
        }
    } else if mode == Mode::Print && matches!(cli.resource.as_deref(), Some(r) if r != "-") {
        (cli.resource.clone().unwrap(), None)
    } else {
        // `inspect` is ours: it parses at most a documented limit.
        let limit = (mode == Mode::Inspect).then_some(controls::INSPECT_LIMIT);
        match read_resource_limited(cli.resource.as_deref(), cli.extensions.encoding, limit) {
            Ok(content) => (content, None),
            Err(err) => {
                let name = cli.resource.as_deref().unwrap_or("<stdin>");
                return fail(&cli, ExitClass::Input, format!("cannot read {name}: {err}"));
            }
        }
    };
    // `ansi explain` shows escapes visibly; neutralising them first would
    // leave nothing to explain.
    if cli.sanitize && mode != Mode::AnsiExplain {
        content = sanitize_terminal_controls(&content);
    }

    // `--format` routes input automatic mode would print as text (stdin, no
    // extension) — or, with a named format, any input — to a renderer.
    let mut routed_language = None;
    let mut routed = false;
    if let Some(format) = cli.data.format.filter(|_| cli.mode == Mode::Auto)
        && (mode == Mode::Auto || matches!(format, inspect::InputFormat::Named(_)))
    {
        routed = true;
        mode = match inspect::route(format, &content, cli.resource.as_deref()) {
            inspect::Route::Json => Mode::Json,
            inspect::Route::Syntax(lexer) => {
                routed_language = Some(lexer);
                Mode::Syntax
            }
            inspect::Route::Text => Mode::Auto,
        };
    }

    // Documents by content (documents.rs): a man page named for its section
    // (`ls.1`), an extensionless file that is unmistakably Org, AsciiDoc or
    // roff, and, with `--format auto`, piped input that is likely one. Never
    // when a flag chose the mode, nor when a source option asks for syntax.
    if cli.mode == Mode::Auto
        && !cli.source.wants_syntax()
        && (mode == Mode::Auto || (mode == Mode::Syntax && !routed))
    {
        let auto = cli.data.format == Some(inspect::InputFormat::Auto);
        if let Some(document) = documents::by_content(cli.resource.as_deref(), &content, auto) {
            mode = document;
        }
    }

    // For a URL that neither a flag nor a telltale extension resolved: upstream
    // renders fetched content as syntax-highlighted source by default, unless the
    // Content-Type marks it markdown / json / csv.
    if resource_is_url && mode == Mode::Auto && !routed {
        mode = content_type
            .as_deref()
            .and_then(content_type_mode)
            .unwrap_or(Mode::Syntax);
    }

    // Upstream renders anything it does not recognise as syntax. This port
    // prints plain text instead, until a source option asks for more.
    if mode == Mode::Auto && cli.source.wants_syntax() {
        mode = Mode::Syntax;
    }

    // Pre-parse JSON so a parse error surfaces before any (HTML) rendering.
    let json_content = if mode == Mode::Json && cli.sanitize {
        match sanitize_json_source(content.trim()) {
            Ok(content) => Some(content),
            Err(err) => {
                return fail(&cli, ExitClass::Data, format!("invalid JSON: {err}"));
            }
        }
    } else {
        None
    };

    let json = if mode == Mode::Json {
        let source = json_content.as_deref().unwrap_or_else(|| content.trim());
        match Json::new(source) {
            Ok(json) => Some(json),
            Err(err) => {
                return fail(&cli, ExitClass::Data, format!("invalid JSON: {err}"));
            }
        }
    } else {
        None
    };

    // Same treatment for a notebook. Without this the parse failure was printed
    // from inside the render closure, which cannot influence the exit code — so
    // a broken notebook reported an error and exited 0, while a broken .json
    // exited 1. A malformed input must not look like success to a script.
    if mode == Mode::Ipynb {
        let notebook = match serde_json::from_str::<serde_json::Value>(&content) {
            Ok(mut value) if value.get("cells").and_then(|c| c.as_array()).is_some() => {
                if cli.sanitize {
                    sanitize_json_value(&mut value);
                }
                value
            }
            Ok(_) => {
                return fail(&cli, ExitClass::Data, "not a notebook: no `cells` array");
            }
            Err(err) => {
                return fail(
                    &cli,
                    ExitClass::Data,
                    format!("invalid notebook JSON: {err}"),
                );
            }
        };
        let renderable = match build_ipynb(&notebook, cli.hyperlinks, cli.justify, &cli.source) {
            Ok(renderable) => renderable,
            Err(err) => return fail(&cli, ExitClass::Usage, err),
        };
        let fit = renderable.measure(&console, &console.options()).maximum;
        return decorate_and_emit(&cli, &console, &export, Box::new(renderable), Some(fit));
    }

    // Markup comes from the user in Print mode, so a mistake in it should be
    // reported rather than printed literally (upstream raises `MarkupError`).
    // Checked up front because the render closure below cannot fail.
    if mode == Mode::Print
        && let Err(err) = console.try_build_text(&content)
    {
        return fail(&cli, ExitClass::Data, err.to_string());
    }

    // The highlighting language comes from the resource extension, falling back
    // (for a URL) to a lexer guessed from its Content-Type. An *uninformative*
    // extension (.txt/.log/…) doesn't shadow a Content-Type that names a real
    // language, so `snippet.txt` served as `text/x-python` still highlights.
    let extension = resource_ext(cli.resource.as_deref().unwrap_or_default())
        .filter(|ext| !is_uninformative_ext(ext));
    let language = routed_language
        .map(str::to_string)
        .or(extension)
        .or_else(|| {
            content_type
                .as_deref()
                .and_then(content_type_lexer)
                .map(str::to_string)
        })
        .unwrap_or_default();

    // `--format` or a URL's Content-Type can still route away from text.
    if let Some(message) = transform_misplaced_in(&cli, mode) {
        return fail(&cli, ExitClass::Usage, message);
    }

    // Build the renderable, and the width a non-expanding `Panel`/`Padding`
    // would shrink around it — upstream's `Measurement.get(…).maximum`.
    let (renderable, fit): (Box<dyn Renderable>, Option<usize>) = match mode {
        // `Markdown` defines no `__rich_measure__`, so upstream measures it as
        // the whole available width and a panel around it never shrinks.
        Mode::Markdown => {
            // `:micro:name:` outside code draws as its asset.
            #[cfg(feature = "art")]
            let micro = micro::markdown(&console, &content, cli.micro_project);
            #[cfg(feature = "art")]
            let source = micro.as_ref().map_or(content.as_str(), |m| m.source());
            #[cfg(not(feature = "art"))]
            let source = content.as_str();
            let mut markdown = build_markdown(source, cli.hyperlinks);
            // ```mermaid and ```dot fences draw as diagrams unless
            // `--mermaid-backend off` / `--dot-backend off`.
            if let Some(fences) = plugin_registry_with(
                cli.mermaid_backend.unwrap_or(MermaidBackend::Text),
                cli.dot_backend != Some(sources::DotBackend::Off),
            )
            .fences()
            {
                markdown = markdown.fence_renderer(fences);
            }
            #[cfg(feature = "art")]
            let view: Box<dyn Renderable> = match micro {
                Some(micro) => Box::new(micro.view(markdown)),
                None => Box::new(markdown),
            };
            #[cfg(not(feature = "art"))]
            let view: Box<dyn Renderable> = Box::new(markdown);
            (view, None)
        }
        // Upstream is `RestructuredText(data, code_theme=theme,
        // default_lexer=lexer or "python", show_errors=False)`; the theme
        // reaches its code blocks through the console's code highlighting.
        Mode::Rst => {
            let lexer = cli.source.lexer.as_deref().unwrap_or("python");
            let document = rich_ext::rst::RestructuredText::new(&content).default_lexer(lexer);
            (Box::new(document), None)
        }
        // Not upstream (documents.rs); like `Markdown`, measured as the whole
        // width. Mermaid and DOT source blocks draw as diagrams, as fences do.
        Mode::Org | Mode::AsciiDoc | Mode::Man => {
            let fences = plugin_registry_with(
                cli.mermaid_backend.unwrap_or(MermaidBackend::Text),
                cli.dot_backend != Some(sources::DotBackend::Off),
            )
            .fences();
            (documents::render(mode, &content, &cli, fences), None)
        }
        #[cfg(feature = "mermaid")]
        Mode::Mermaid => {
            // The command itself asks for a diagram, so it may use mmdc.
            let default = if cfg!(feature = "mmdc") {
                MermaidBackend::Mmdc
            } else {
                MermaidBackend::Text
            };
            let backend = match cli.mermaid_backend.unwrap_or(default) {
                MermaidBackend::Off => MermaidBackend::Text,
                chosen => chosen,
            };
            let diagram =
                rich_mermaid::Mermaid::new(content.clone()).options(mermaid_options(backend));
            (Box::new(diagram), None)
        }
        Mode::Dot => {
            // `--dot-backend graphviz` gives `--export-svg` Graphviz's own
            // SVG; the terminal still shows the native drawing.
            let graphviz = cli.dot_backend == Some(sources::DotBackend::Graphviz);
            let mut svg_done = false;
            if let (true, Some(path)) = (graphviz, export.svg_path) {
                svg_done = sources::graphviz_svg(&content, path);
                if svg_done {
                    export.svg_path = None;
                }
            }
            match sources::dot(&content, cli.resource.as_deref()) {
                Ok(diagram) => (diagram, None),
                // Graphviz drew what the native parser refuses: say so, and
                // keep its SVG.
                Err((_, err)) if svg_done => {
                    eprintln!("rich: warning: {err}; only Graphviz's SVG was written");
                    return success(&cli);
                }
                Err((class, err)) => return fail(&cli, class, err),
            }
        }
        Mode::Json => {
            // `rich.json.JSON` sets `text.no_wrap = True`, and every decorator
            // upstream can wrap the document in — `Padding`, `Panel`, `Styled`,
            // `ForceWidth` — is a `ConsoleRenderable`, so the `Text` reaches
            // `Text.__rich_console__` with the flag intact and each line is
            // CROPPED at the width. A *bare* document is a `Text`, which
            // `_collect_renderables` re-joins through `Text(sep).join(...)`;
            // `Text.join` copies its metadata from the separator, so the flag
            // is lost and the default fold wrap applies instead.
            //
            // `--left/--center/--right` is not on the list: `align_append`
            // wraps whatever `check_text` produced, so the join — and the loss
            // — has already happened by the time `Align` sees it.
            //
            // `--pager` skips `ForceWidth`, but pages through
            // `console.render_lines(renderable, …)`, which renders the `Text`
            // directly and keeps the flag.
            let nested = cli.padding.is_some()
                || cli.panel.is_some()
                || cli.style.is_some()
                || cli.width.is_some()
                || cli.pager
                || cli.auto_pager;
            let json = json.expect("json parsed above").no_wrap(nested);
            #[cfg(feature = "json-escape-safe")]
            let json = json.escape_safe(true);
            let fit = measure_rendered(&console, &json);
            (Box::new(json), Some(fit))
        }
        Mode::Csv => {
            if let Err(err) = validate_labels(&cli) {
                return fail(&cli, ExitClass::Data, err);
            }
            // `.tsv` only picks the fallback dialect; the sniffer reads the file
            // itself, so a comma-separated `.tsv` still renders as a table.
            let fallback = csv_fallback_delimiter(cli.resource.as_deref());
            let rules = cli.rules.rules();
            let table = match build_csv_table_with(
                &content,
                fallback,
                cli.title.as_deref(),
                cli.caption.as_deref(),
                (cli.source.head, cli.source.tail),
                cli.source.infer,
                (!rules.is_empty()).then_some((&console, rules)),
            ) {
                Some(table) => table,
                // Upstream's `on_error(str(error))`. The message is CPython's,
                // verbatim, because it is the one a script would grep for.
                None => {
                    return fail(&cli, ExitClass::Data, "Could not determine delimiter");
                }
            };
            // `:micro:name:` in the title and caption, where `:emoji:` codes
            // expand (with `--emoji`).
            #[cfg(feature = "art")]
            let table = {
                let mut table = table;
                let label = |label: &Option<String>, style| {
                    label.as_deref().and_then(|label| {
                        micro::table_label(&console, label, style, cli.micro_project)
                    })
                };
                if let Some(title) = label(&cli.title, "table.title") {
                    table = table.title_text(title);
                }
                if let Some(caption) = label(&cli.caption, "table.caption") {
                    table = table.caption_text(caption);
                }
                table
            };
            // Stream undecorated CSV rows: measuring or collecting the complete
            // styled table first multiplies memory by hundreds on tall inputs.
            // Containers, alignment, paging and exports still need the full view.
            if cli.panel.is_none()
                && cli.padding.is_none()
                && cli.style.is_none()
                && cli.justify.is_none()
                && cli.max_width.is_none()
                && !cli.soft
                && !cli.pager
                && !cli.auto_pager
                && cli.export_html.is_none()
                && cli.export_svg.is_none()
                && cli.export_png.is_none()
                && !watch::capturing()
                && !micro_pending()
            {
                let mut options = console.options();
                options.max_width = cli.width.unwrap_or_else(|| {
                    table
                        .measure(&console, &options)
                        .maximum
                        .min(options.max_width)
                        .max(1)
                });
                let stdout = std::io::stdout();
                let mut output = std::io::BufWriter::new(stdout.lock());
                let result = table
                    .try_for_each_line(&console, &options, |line| {
                        let line = Segment::crop_lines(&line, console.width());
                        writeln!(output, "{}", console.segments_to_string(&line))
                    })
                    .and_then(|()| output.flush());
                if let Err(error) = result {
                    // A consumer such as `head` may finish before this table.
                    // Match the other stdout paths: a closed pipe is success.
                    if error.kind() == std::io::ErrorKind::BrokenPipe {
                        return success(&cli);
                    }
                    return fail(
                        &cli,
                        ExitClass::Input,
                        format!("could not write CSV output: {error}"),
                    );
                }
                return success(&cli);
            }
            let fit = measure_rendered(&console, &table);
            (Box::new(table), Some(fit))
        }
        // `--filter`, `--transform` and `--highlight` work on the highlighted
        // text.
        Mode::Syntax if cli.data.transform_option().is_some() => {
            let language = cli.source.lexer.as_deref().unwrap_or(&language);
            // `--head`/`--tail` pick the lines first, as `Syntax`'s
            // `line_range` does on the other path.
            let code = match cli.source.line_range(&content) {
                Ok(Some((start, end))) => {
                    let start = start.max(1) as usize - 1;
                    let end = end.max(0) as usize;
                    let lines: Vec<&str> = content.lines().collect();
                    lines
                        .get(start.min(lines.len())..end.min(lines.len()))
                        .unwrap_or_default()
                        .join("\n")
                }
                Ok(None) => content.clone(),
                Err(err) => return fail(&cli, ExitClass::Usage, err),
            };
            let text = Syntax::new(code.as_str(), language).highlight_for(&console);
            let text = match cli
                .data
                .text_pipeline(&plugin_registry(MermaidBackend::Text))
                .and_then(|pipeline| pipeline.apply(text).map_err(inspect::transform_failed))
            {
                Ok(text) => text,
                Err(err) => return fail(&cli, ExitClass::Data, err),
            };
            let fit = text.measurement().1;
            // Keep `Syntax`'s layout: every row filled to the width in the
            // code background, so a transform changes only what it matches.
            let background = match text.base_style() {
                rich::style::StyleType::Style(style) => style.clone(),
                rich::style::StyleType::Name(_) => rich::Style::new(),
            };
            // The text's own final empty line (after a trailing newline) is
            // drawn by `Padding`, as `Syntax` draws it.
            let padded =
                rich::padding::Padding::new(Box::new(text), (0, 0, 0, 0)).style(background);
            (Box::new(padded), Some(fit))
        }
        Mode::Syntax => {
            let syntax = match cli.source.syntax(&content, &language) {
                Ok(syntax) => syntax,
                Err(err) => return fail(&cli, ExitClass::Usage, err),
            };
            // `Syntax.__rich_measure__`: the widest source line, plus the
            // line-number column when there is one.
            let fit = syntax.measure(&console, &console.options()).maximum;
            (Box::new(syntax), Some(fit))
        }
        Mode::View => {
            let view: Box<dyn Renderable> = match view_as {
                Some(viewers::ViewAs::Patch) => {
                    let name = cli.resource.clone().unwrap_or_else(|| "<stdin>".into());
                    match tools::text_diff(&cli.tools, &[name], &[content.clone()], None, false) {
                        Ok(outcome) => outcome.renderable,
                        Err(err) => return fail(&cli, ExitClass::Data, err),
                    }
                }
                Some(viewers::ViewAs::Binary) => {
                    match viewers::hex(&cli.viewers, std::mem::take(&mut view_bytes), 0) {
                        Ok(view) => view,
                        Err(err) => return fail(&cli, ExitClass::Usage, err),
                    }
                }
                Some(viewers::ViewAs::Source(ref lexer)) => {
                    if let Some(summary) = viewers::search_summary(&cli.viewers, &content) {
                        eprintln!("{summary}");
                    }
                    viewers::source(&cli.viewers, &content, lexer)
                }
                _ => viewers::source(&cli.viewers, &content, "txt"),
            };
            let fit = view.measure(&console, &console.options()).maximum;
            (view, Some(fit))
        }
        Mode::AnsiExplain => {
            let view = tools::ansi_explain(&cli.tools, &content);
            let fit = view.measure(&console, &console.options()).maximum;
            (view, Some(fit))
        }
        Mode::Inspect => {
            let encoding = cli.extensions.encoding;
            let read = |path: &str| {
                read_resource_limited(Some(path), encoding, Some(controls::INSPECT_LIMIT))
                    .map_err(|err| format!("cannot read {path}: {err}"))
            };
            let rules = cli.rules.rules();
            let view = match inspect::build_with(
                &cli.data,
                &content,
                cli.resource.as_deref(),
                read,
                rules,
            ) {
                Ok(view) => view,
                Err(err) => return fail(&cli, ExitClass::Data, err),
            };
            let fit = view.measure(&console, &console.options()).maximum;
            (view, Some(fit))
        }
        // Print + auto: parse markup (Print) or take plain text (auto), then
        // `--filter` and `--highlight`.
        _ => {
            // `:micro:name:` goes where `:emoji:` codes go: in --print
            // markup with --emoji.
            #[cfg(feature = "art")]
            let micro = (mode == Mode::Print && cli.emoji)
                .then(|| micro::print_markup(&console, &content, cli.micro_project))
                .flatten();
            #[cfg(feature = "art")]
            let mut text = match micro {
                Some(text) => text,
                None if mode == Mode::Print => console.build_text(&content),
                None => Text::new(content.as_str()),
            };
            #[cfg(not(feature = "art"))]
            let mut text = if mode == Mode::Print {
                console.build_text(&content)
            } else {
                Text::new(content.as_str())
            };
            // `Text.from_markup(…, justify=justify)` and `renderable.no_wrap =
            // no_wrap`. A bare text loses both to `print`'s `Text.join`, as
            // upstream's does; `--width`, `--panel` and the rest keep them.
            if let Some(justify) = cli.text_justify {
                text.set_justify(justify);
            }
            if cli.source.no_wrap {
                text.set_no_wrap(Some(true));
            }
            let text = match cli
                .data
                .text_pipeline(&plugin_registry(MermaidBackend::Text))
                .and_then(|pipeline| pipeline.apply(text).map_err(inspect::transform_failed))
            {
                Ok(text) => text,
                Err(err) => return fail(&cli, ExitClass::Data, err),
            };
            let fit = text.measurement().1;
            // A two-row micro asset reserves the row below its line (#711).
            #[cfg(feature = "art")]
            let renderable = micro::rows(text);
            #[cfg(not(feature = "art"))]
            let renderable: Box<dyn Renderable> = Box::new(text);
            (renderable, Some(fit))
        }
    };
    decorate_and_emit(&cli, &console, &export, renderable, fit)
}

/// Turn an "everything written successfully" flag into a process exit code.
/// A failed `--export-html`/`--export-svg` write must not report success.
#[allow(dead_code)]
fn exit_code(ok: bool) -> ExitCode {
    if ok {
        ExitCode::SUCCESS
    } else {
        ExitCode::FAILURE
    }
}

fn emit_exit_code(cli: &Cli, result: Result<(), String>) -> ExitCode {
    match result {
        Ok(()) => success(cli),
        Err(message) => fail(cli, ExitClass::Input, message),
    }
}

fn write_rendered_stdout(console: &Console, renderable: &dyn Renderable) -> std::io::Result<()> {
    let output = console.render_export(renderable);
    let stdout = std::io::stdout();
    let mut lock = stdout.lock();
    lock.write_all(output.as_bytes())
}

fn run_json_lines(cli: &Cli, console: &Console, log_mode: bool) -> ExitCode {
    if cli.extensions.encoding.is_some() {
        return fail(
            cli,
            ExitClass::Usage,
            "--encoding is not supported with streaming JSONL/log mode",
        );
    }
    if matches!(cli.resource.as_deref(), Some(resource) if is_url(resource)) {
        return fail(
            cli,
            ExitClass::Usage,
            "streaming JSONL/log mode reads files or stdin, not URLs",
        );
    }
    if log_mode {
        return logs::run(cli, console);
    }

    let mut input: Box<dyn BufRead> = match cli.resource.as_deref() {
        Some(path) if path != "-" => {
            let file = &fs_path(path);
            if file.is_dir() {
                return fail(
                    cli,
                    ExitClass::Input,
                    format!("cannot read {path}: is a directory, not a file"),
                );
            }
            match std::fs::File::open(file) {
                Ok(file) => Box::new(std::io::BufReader::new(file)),
                Err(err) => {
                    return fail(cli, ExitClass::Input, format!("cannot read {path}: {err}"));
                }
            }
        }
        _ => {
            if std::io::stdin().is_terminal() {
                let eof = if cfg!(windows) {
                    "Ctrl-Z then Enter"
                } else {
                    "Ctrl-D"
                };
                eprintln!("rich: reading stdin; finish input with {eof}");
            }
            Box::new(std::io::BufReader::new(std::io::stdin()))
        }
    };

    let mut line = String::new();
    let mut line_number = 0usize;
    loop {
        line.clear();
        let read = match input.read_line(&mut line) {
            Ok(read) => read,
            Err(err) => {
                return fail(
                    cli,
                    ExitClass::Input,
                    format!("cannot read JSONL stream: {err}"),
                );
            }
        };
        if read == 0 {
            break;
        }
        line_number += 1;
        let record = line.trim_end_matches(['\r', '\n']);
        let mut value = match serde_json::from_str::<serde_json::Value>(record) {
            Ok(value) => value,
            Err(err) => {
                return fail(
                    cli,
                    ExitClass::Data,
                    format!("invalid JSONL at line {line_number}: {err}"),
                );
            }
        };
        if cli.sanitize {
            sanitize_json_value(&mut value);
        }
        let source = serde_json::to_string(&value).expect("JSON value serializes");
        let json = Json::new(&source).expect("serialized JSON parses");
        let wrote = write_rendered_stdout(console, &json);
        if let Err(error) = wrote {
            if error.kind() == std::io::ErrorKind::BrokenPipe {
                return success(cli);
            }
            return fail(
                cli,
                ExitClass::Input,
                format!("could not write JSONL output: {error}"),
            );
        }
    }
    success(cli)
}

/// Whether `value` matches rich-cli's `is_number`, i.e. Python's
/// `re.fullmatch(r"\-?[0-9]*?\.?[0-9]*?", value)`.
///
/// Note how loose that is: `-`, `.`, `-.` and the empty string all pass, and a
/// leading space does not. The caller only asks about non-empty cells.
fn is_number(value: &str) -> bool {
    let body = value.strip_prefix('-').unwrap_or(value);
    let (integer, fraction) = match body.split_once('.') {
        Some((integer, fraction)) => (integer, Some(fraction)),
        None => (body, None),
    };
    let digits = |part: &str| part.bytes().all(|b| b.is_ascii_digit());
    digits(integer) && fraction.is_none_or(digits)
}

/// Build the CSV table for `content`, sniffing the dialect and the header the
/// way upstream's `render_csv` does.
///
/// `fallback_delimiter` is the dialect to use when `csv.Sniffer` raises, and
/// `None` means upstream has none to offer: its `except csv.Error` arm falls
/// back to `csv.get_dialect("excel")` for a resource whose name ends `.csv`
/// and to `"excel-tab"` for one ending `.tsv`, and for **everything else** —
/// any other extension, a bare name, a URL, stdin — calls
/// `on_error(str(error))`, which prints the message and exits non-zero.
///
/// So `None` here is a failure, and the caller must report it. Rendering a
/// fabricated one-column table at exit 0 instead is the worst possible
/// outcome: `rich --csv "$f" && publish` proceeds on a file nothing could
/// parse, with empty stderr to say so.
///
/// `infer` (`--infer`, not upstream) types each column with
/// `rich_data::infer` after `--head`/`--tail` cut the rows; see
/// [`render_csv`].
fn build_csv_table(
    content: &str,
    fallback_delimiter: Option<char>,
    title: Option<&str>,
    caption: Option<&str>,
    window: (Option<usize>, Option<usize>),
    infer: bool,
) -> Option<Table> {
    build_csv_table_with(
        content,
        fallback_delimiter,
        title,
        caption,
        window,
        infer,
        None,
    )
}

/// [`build_csv_table`] with `--style-rule`/`--rules` (not upstream): the
/// rules, and the console that renders a styled cell's markup.
fn build_csv_table_with(
    content: &str,
    fallback_delimiter: Option<char>,
    title: Option<&str>,
    caption: Option<&str>,
    window: (Option<usize>, Option<usize>),
    infer: bool,
    rules: Option<(&Console, &rich_ext::table::StyleRules)>,
) -> Option<Table> {
    // The sniffer sees only the first 1024 *characters* — upstream's
    // `csv_data[:1024]` — however long the file is.
    let sample: String = content.chars().take(1024).collect();
    let sniffed = sniff(&sample, Some(&[',', '\t', '|', ';'])).zip(has_header(&sample));
    let (dialect, header) = match sniffed {
        Some(sniffed) => sniffed,
        None => (Dialect::excel(fallback_delimiter?), true),
    };
    let mut rows = read_rows(content, &dialect);
    // `table_rows[:head]` or `table_rows[-tail:]` (head wins), counted over
    // the non-blank data rows, before the numeric columns are chosen.
    if window.0.is_some() || window.1.is_some() {
        let header_row = if header && !rows.is_empty() {
            Some(rows.remove(0))
        } else {
            None
        };
        let mut data: Vec<Vec<String>> = rows.into_iter().filter(|row| !row.is_empty()).collect();
        match window {
            (Some(head), _) => data.truncate(head),
            (None, Some(tail)) => {
                data.drain(..data.len().saturating_sub(tail));
            }
            (None, None) => {}
        }
        rows = header_row.into_iter().chain(data).collect();
    }
    let types = infer.then(|| infer_csv_types(&rows, header));
    Some(render_csv(rows, header, title, caption, types, rules))
}

/// Each column's inferred type, for `--infer`: the data rows (blank lines
/// skipped, as the table skips them) read by `rich_data::infer`, a missing
/// cell in a short row counting as null.
fn infer_csv_types(rows: &[Vec<String>], has_header: bool) -> Vec<InferredType> {
    let width = rows.iter().map(Vec::len).max().unwrap_or(0);
    let mut data = rich_data::Rows::new((0..width).map(|index| index.to_string()));
    for row in rows
        .iter()
        .skip(usize::from(has_header))
        .filter(|row| !row.is_empty())
    {
        data.push(
            (0..width)
                .map(|index| rich_data::Value::from(row.get(index).map_or("", String::as_str))),
        );
    }
    Inferrer::new()
        .infer(&data)
        .columns()
        .iter()
        .map(|column| column.data_type())
        .collect()
}

/// The dialect upstream falls back to when `csv.Sniffer` cannot read
/// `resource`, or `None` when it has none — a failure, not a default.
///
/// Upstream tests the **resource string**, not the detected language:
/// `resource.lower().endswith(".csv")` then `.endswith(".tsv")`. So a URL
/// ending `.tsv` gets the tab dialect, and `-` (stdin) gets nothing.
fn csv_fallback_delimiter(resource: Option<&str>) -> Option<char> {
    let name = resource.unwrap_or_default().to_lowercase();
    if name.ends_with(".csv") {
        Some(',')
    } else if name.ends_with(".tsv") {
        Some('\t')
    } else {
        None
    }
}

/// Build a table from parsed CSV `rows`, mirroring rich-cli's `render_csv`: a
/// blue border, `HEAVY_HEAD` when the sniffer found a header and `SQUARE` when
/// it did not, and any all-numeric column right-justified with bold-green body
/// and header cells.
///
/// With `types` (`--infer`), a column is numeric when its inferred type is
/// an integer or a float, so null tokens (`NA`, `null`, …) no longer make a
/// number column text, and each heading shows its type on a second, dim
/// line; a table without a header row then shows a heading of types alone.
///
/// With `rules` (`--style-rule`, `--rules`; not upstream), the rules style
/// the data rows by header (or `#N`), each cell compared as its text; a
/// styled cell is its markup rendered by the console, then styled.
fn render_csv(
    rows: Vec<Vec<String>>,
    has_header: bool,
    title: Option<&str>,
    caption: Option<&str>,
    types: Option<Vec<InferredType>>,
    rules: Option<(&Console, &rich_ext::table::StyleRules)>,
) -> Table {
    let mut table = Table::new()
        .border_style(Style::parse("blue").expect("valid style"))
        .show_header(has_header || types.is_some())
        .box_set(if has_header { HEAVY_HEAD } else { SQUARE });
    if let Some(title) = title {
        table = table.title(title);
    }
    if let Some(caption) = caption {
        table = table.caption(caption);
    }

    let empty: Vec<String> = Vec::new();
    let (header, body) = if has_header {
        match rows.split_first() {
            Some((header, body)) => (header, body),
            None => return table,
        }
    } else {
        (&empty, rows.as_slice())
    };
    // `[row for row in rows if row]`: a blank line is not a table row.
    let data: Vec<&Vec<String>> = body.iter().filter(|row| !row.is_empty()).collect();

    // A row may carry more fields than the header names, and upstream's
    // `table.add_row(*row)` grows the table to hold them. Columns came from the
    // header alone, so those fields had nowhere to go and were dropped -- a
    // silent data loss in a tool whose job is showing you the file.
    let widest = data.iter().map(|row| row.len()).max().unwrap_or(0);
    let columns = header.len().max(widest);

    for index in 0..columns {
        // A column is numeric when no data cell is a non-empty non-number. A
        // row too SHORT to reach the column disqualifies it (upstream's
        // `except Exception: break`), while an empty cell does not; and an
        // empty data set counts as numeric, as upstream's `for … else` does.
        let inferred = types
            .as_ref()
            .map(|types| types.get(index).copied().unwrap_or(InferredType::Null));
        let numeric = match inferred {
            Some(inferred) => matches!(inferred, InferredType::Integer | InferredType::Float),
            None => data.iter().all(|row| match row.get(index) {
                Some(value) => value.is_empty() || is_number(value),
                None => false,
            }),
        };
        let name = header.get(index).map(String::as_str).unwrap_or("");
        if let Some(inferred) = inferred {
            let mut heading = Text::new(name);
            if !name.is_empty() {
                heading.append("\n", None);
            }
            heading.append(
                inferred.name(),
                Some(Style::parse("dim").expect("valid style").into()),
            );
            let justify = if numeric {
                Justify::Right
            } else {
                Justify::Left
            };
            table.add_column_text(heading, justify);
        } else if numeric {
            table.add_column_justify(name, Justify::Right);
        } else {
            table.add_column(name);
        }
        if numeric {
            table.column_style(Style::parse("bold green").expect("valid style"));
            table.column_header_fill(Style::parse("bold green").expect("valid style"));
        }
    }
    // Measurement/style inference is complete. Move the parsed cells into the
    // table rather than retaining and cloning the complete input row set.
    drop(data);
    let headers: Vec<String> = match rules {
        Some(_) => (0..columns)
            .map(|index| header.get(index).cloned().unwrap_or_default())
            .collect(),
        None => Vec::new(),
    };
    let body = rows
        .into_iter()
        .skip(usize::from(has_header))
        .filter(|row| !row.is_empty());
    match rules.filter(|(_, rules)| !rules.is_empty()) {
        None => {
            table.extend_owned_rows(body.collect());
        }
        Some((console, rules)) => {
            add_styled_csv_rows(&mut table, console, rules, &headers, body.collect())
        }
    }
    table
}

/// Add CSV `rows` to `table` styled by `rules`, matched against `headers`;
/// each cell is compared as its text (`Value::Str`, so a number in text
/// compares as a number). An unstyled cell stays markup, as upstream's.
fn add_styled_csv_rows(
    table: &mut Table,
    console: &Console,
    rules: &rich_ext::table::StyleRules,
    headers: &[String],
    rows: Vec<Vec<String>>,
) {
    use rich_ext::table::{Target, Value};
    let headers: Vec<&str> = headers.iter().map(String::as_str).collect();
    let values = |row: &[String]| -> Vec<Value> { row.iter().cloned().map(Value::Str).collect() };
    // Only a column rule needs every row before the first is drawn.
    let resolved = if rules
        .rules()
        .iter()
        .any(|r| r.target_kind() == Target::Column)
    {
        rules.resolve(&headers, rows.iter().map(|row| values(row)))
    } else {
        rules.resolve(&headers, std::iter::empty::<Vec<Value>>())
    };
    style_rules::warn_unresolved(&resolved, &headers);
    for row in rows {
        let cells: Vec<Value> = row.into_iter().map(Value::Str).collect();
        let row_style = resolved.row_style(&cells);
        let styles: Vec<Option<Style>> = (0..cells.len())
            .map(|index| resolved.cell_style(&cells, index))
            .collect();
        let cells = cells
            .into_iter()
            .zip(styles)
            .map(|(cell, style)| {
                let markup = match cell {
                    Value::Str(text) => text,
                    other => other.plain(),
                };
                match style {
                    None => rich::Cell::Markup(markup),
                    Some(style) => {
                        let mut text = console.render_str(&markup, Some(false));
                        let len = text.plain().len();
                        text.stylize(style, 0, len);
                        rich::Cell::Text(text)
                    }
                }
            })
            .collect();
        table.add_row_with(cells, row_style.map(Into::into), false);
    }
}

/// Join a notebook cell/output `source` field (a JSON string, or an array of
/// line strings that already include their trailing newlines).
fn join_source(value: &serde_json::Value) -> String {
    match value {
        serde_json::Value::String(s) => s.clone(),
        serde_json::Value::Array(a) => a.iter().filter_map(|v| v.as_str()).collect(),
        _ => String::new(),
    }
}

/// Join a notebook `traceback`, whose elements are lines WITHOUT trailing
/// newlines (unlike `source`/`text`, which carry their own). Using
/// [`join_source`] here fused a whole stack trace onto one line.
fn join_traceback(value: &serde_json::Value) -> String {
    match value {
        serde_json::Value::String(s) => s.clone(),
        serde_json::Value::Array(a) => a
            .iter()
            .filter_map(|v| v.as_str())
            .collect::<Vec<_>>()
            .join(
                "
",
            ),
        _ => String::new(),
    }
}

/// Build an `In [n]:` / `Out[n]:` execution-count label. Port of rich-cli's
/// `[green]In [[#66ff00]{count}[/#66ff00]]:[/green]` markup (built as spans to
/// avoid markup-escaping the literal brackets).
fn io_label(word: &str, count: Option<i64>, base: &str, number: &str) -> Text {
    let base_style = Style::parse(base).ok();
    let number_style = Style::parse(number).ok();
    let n = count.map_or_else(|| " ".to_string(), |c| c.to_string());
    let mut text = Text::new("");
    text.append(&format!("{word}["), base_style.clone().map(Into::into));
    text.append(&n, number_style.map(Into::into));
    text.append("]:", base_style.map(Into::into));
    text
}

/// Port of the Group returned by rich-cli's `render_ipynb`. Keeping the cells
/// composable lets the common padding/panel/style/width/alignment chain apply.
struct Notebook {
    items: Vec<Box<dyn Renderable>>,
    // Console.print(justify=...) also reaches the group's Text children in
    // upstream. Their individual lines align within the group's measured width.
    justify: Option<Justify>,
}

impl Renderable for Notebook {
    fn rich_render(&self, console: &Console, options: &ConsoleOptions) -> Vec<Segment> {
        let mut options = options.clone();
        if let Some(justify) = self.justify {
            options.justify = justify;
        }
        let mut segments = Vec::new();
        for item in &self.items {
            let rendered = item.rich_render(console, &options);
            if !rendered.is_empty() {
                segments.extend(rendered);
                segments.push(Segment::line());
            }
        }
        // Console supplies the final newline. Empty groups produce no output.
        if !segments.is_empty() {
            segments.pop();
        }
        segments
    }

    fn measure(&self, console: &Console, options: &ConsoleOptions) -> Measurement {
        self.items
            .iter()
            .map(|item| item.measure(console, options))
            .fold(Measurement::new(0, 0), |width, item| {
                Measurement::new(
                    width.minimum.max(item.minimum),
                    width.maximum.max(item.maximum),
                )
            })
    }
}

/// Text.from_ansi joins decoded lines, preserving their style spans.
fn notebook_ansi(source: &str) -> Text {
    let mut result = Text::new("");
    // rich-cli 1.8.1 runs on rich 12, whose `AnsiDecoder.decode` split with
    // `splitlines`: no final empty line, and `\r\n` ends a line.
    let mut decoder = AnsiDecoder::new();
    let lines: Vec<Text> = source
        .lines()
        .map(|line| decoder.decode_line(line))
        .collect();
    for (index, line) in lines.iter().enumerate() {
        if index > 0 {
            result.append("\n", None);
        }
        result = result.append_text(line);
    }
    result
}

/// Port of rich-cli 1.8.1's notebook cell/output grouping. Parse once, then use
/// the same renderable for terminal output, paging and recorded exports.
fn build_ipynb(
    notebook: &serde_json::Value,
    hyperlinks: bool,
    justify: Option<Justify>,
    source_options: &SourceOptions,
) -> Result<Notebook, String> {
    let language = notebook["metadata"]["kernelspec"]["language"]
        .as_str()
        .or_else(|| notebook["metadata"]["language_info"]["name"].as_str())
        .unwrap_or("python");
    let empty = Vec::new();
    let mut items: Vec<Box<dyn Renderable>> = Vec::new();
    let mut new_line = true;
    for cell in notebook["cells"].as_array().unwrap_or(&empty) {
        if new_line {
            items.push(text(""));
        }
        if cell.get("execution_count").is_some() {
            items.push(Box::new(io_label(
                "In ",
                cell["execution_count"].as_i64().filter(|n| *n != 0),
                "green",
                "#66ff00",
            )));
        }
        let source = join_source(&cell["source"]);
        items.push(match cell["cell_type"].as_str().unwrap_or("") {
            "markdown" => Box::new(build_markdown(&source, hyperlinks)),
            // Upstream's `Syntax(source, lexer, line_numbers=…, indent_guides=…,
            // word_wrap=not no_wrap, line_range=…)`, per cell.
            "code" => Box::new(
                Panel::new(Box::new(source_options.syntax(&source, language)?))
                    .border_style(Style::parse("dim").expect("valid style")),
            ),
            _ => text(&source),
        });
        new_line = true;
        for output in cell["outputs"].as_array().unwrap_or(&empty) {
            let rendered = match output["output_type"].as_str().unwrap_or("") {
                "stream" => {
                    new_line = false;
                    notebook_ansi(&join_source(&output["text"]))
                }
                "error" => {
                    new_line = true;
                    notebook_ansi(join_traceback(&output["traceback"]).trim_end())
                }
                "execute_result" => {
                    new_line = true;
                    let mut label = io_label(
                        "Out",
                        output["execution_count"].as_i64().filter(|n| *n != 0),
                        "red",
                        "#ee4b2b",
                    );
                    label.append("\n", None);
                    label.append_text(&notebook_ansi(&join_source(&output["data"]["text/plain"])))
                }
                _ => continue,
            };
            items.push(Box::new(rendered));
        }
    }
    Ok(Notebook { items, justify })
}

fn diff_threshold_exceeded(changed: f32, limit: f32) -> bool {
    // Use the formatter's rounding for BOTH displayed operands, including
    // ties. f32::round uses a different tie rule from the report's formatting.
    let displayed = |value: f32| {
        format!("{value:.1}")
            .parse::<f32>()
            .expect("formatted percentage is a number")
    };
    displayed(changed) > displayed(limit)
}

/// `rich diff` for anything but an image pair: text, ANSI captures and
/// source side by side or unified, or one patch (`git diff | rich diff -`).
fn run_text_diff(cli: &Cli, console: &Console, export: &Export) -> ExitCode {
    let mut contents = Vec::with_capacity(cli.resources.len());
    for resource in &cli.resources {
        let content = if is_url(resource) {
            fetch_url(resource, cli.extensions.encoding).map(|(content, _)| content)
        } else {
            read_resource(Some(resource), cli.extensions.encoding)
                .map_err(|err| format!("cannot read {resource}: {err}"))
        };
        match content {
            Ok(content) => contents.push(content),
            Err(err) => return fail(cli, ExitClass::Input, err),
        }
    }
    let names: Vec<String> = cli
        .resources
        .iter()
        .map(|r| {
            if r == "-" {
                "<stdin>".to_string()
            } else {
                r.clone()
            }
        })
        .collect();
    let outcome = match tools::text_diff(
        &cli.tools,
        &names,
        &contents,
        cli.diff_threshold,
        cli.sanitize,
    ) {
        Ok(outcome) => outcome,
        Err(err) => return fail(cli, ExitClass::Data, err),
    };
    let fit = outcome
        .renderable
        .measure(console, &console.options())
        .maximum;
    let code = decorate_and_emit(cli, console, export, outcome.renderable, Some(fit));
    if code != ExitCode::SUCCESS || !outcome.failed {
        return code;
    }
    fail(cli, ExitClass::Gate, "diff threshold exceeded")
}

/// Compare two images perceptually and report where they differ.
///
/// Prints a heat map of the ΔE field plus a ranked table of changed regions.
/// The table is the point: it is text, so it survives a pipe, a log, and a CI
/// transcript, which a picture does not.
///
/// With `--threshold`, exits non-zero when the changed percentage exceeds it,
/// which is what makes this usable as a visual-regression gate.
/// Open an image file, translating a few common failure modes (a directory
/// instead of a file, an unrecognized extension) into one actionable message.
/// Shared by `--diff` (which loads two images) and `--image` (which loads
/// one) so neither reimplements the other's error handling.
///
/// The directory check reached the plain read path but not this one, so
/// `rich --diff a.png somedir` still reported "Access is denied".
#[cfg(feature = "art")]
fn open_image_path(path: &str) -> Result<rich_art::image::DynamicImage, String> {
    if fs_path(path).is_dir() {
        return Err(format!("cannot read {path}: is a directory, not a file"));
    }
    match rich_art::image::open(fs_path(path)) {
        Ok(image) => Ok(image),
        Err(err) => {
            use rich_art::image::error::{ImageFormatHint, UnsupportedErrorKind};
            let hint = match &err {
                rich_art::image::ImageError::Unsupported(error) => match error.kind() {
                    UnsupportedErrorKind::Format(ImageFormatHint::PathExtension(ext)) => {
                        Some(format!(
                            "unsupported image extension {}; use a supported image format such as PNG, JPEG, GIF or WebP",
                            ext.display()
                        ))
                    }
                    _ => None,
                },
                _ => None,
            };
            Err(format!(
                "cannot read {path}: {}",
                hint.unwrap_or_else(|| err.to_string())
            ))
        }
    }
}

/// Map the CLI's own `ImageMode` (which also carries `None`, meaning "print no
/// picture at all") onto `rich_art`'s `ImageMode` (which has no such variant ?
/// a facade that always draws something has no notion of "nothing"). Argument
/// parsing rejects `--image-mode none` together with `--image` before this can
/// ever see it.
#[cfg(feature = "art")]
fn to_art_image_mode(mode: ImageMode) -> rich_art::ImageMode {
    match mode {
        ImageMode::Auto => rich_art::ImageMode::Auto,
        ImageMode::Sixel => rich_art::ImageMode::Sixel,
        ImageMode::Blocks => rich_art::ImageMode::Blocks,
        ImageMode::Braille => rich_art::ImageMode::Braille,
        ImageMode::Quadrants => rich_art::ImageMode::Quadrants,
        ImageMode::Ascii => rich_art::ImageMode::Ascii,
        ImageMode::None => unreachable!("--image-mode none is rejected during argument parsing"),
    }
}

/// Render one still image through rich-art's [`rich_art::ImageArt`] facade.
///
/// This function only opens the file and maps CLI flags onto the facade's
/// builder; picking a backend, sizing and colour handling all stay inside
/// [`rich_art::ImageArt`]; nothing here reimplements that logic (see
/// AGENTS.md's mirror/ext boundary).
#[cfg(feature = "art")]
fn run_image(cli: &Cli, console: &Console, export: &Export) -> ExitCode {
    use rich_art::ImageArt;

    let Some(resource) = cli.resource.as_deref() else {
        return fail(
            cli,
            ExitClass::Usage,
            "--image requires an image file: rich --image photo.png (or `-` for stdin)",
        );
    };

    let image = if resource == "-" {
        let mut buffer = Vec::new();
        if let Err(err) = std::io::stdin().read_to_end(&mut buffer) {
            return fail(cli, ExitClass::Input, format!("cannot read stdin: {err}"));
        }
        match rich_art::image::load_from_memory(&buffer) {
            Ok(image) => image,
            Err(err) => {
                return fail(
                    cli,
                    ExitClass::Input,
                    format!("cannot decode image from stdin: {err}"),
                );
            }
        }
    } else {
        match open_image_path(resource) {
            Ok(image) => image,
            Err(message) => return fail(cli, ExitClass::Input, message),
        }
    };

    let width = cli.width.unwrap_or_else(|| console.width());
    let mut art = ImageArt::new(image)
        .transforms(rich_art::ImageTransforms {
            rotation: match cli.image_rotate {
                Some(90) => rich_art::Rotation::Clockwise90,
                Some(180) => rich_art::Rotation::Clockwise180,
                Some(270) => rich_art::Rotation::Clockwise270,
                _ => rich_art::Rotation::None,
            },
            flip_horizontal: cli.image_flip_horizontal,
            flip_vertical: cli.image_flip_vertical,
            grayscale: cli.image_grayscale,
            brightness: cli.image_brightness.unwrap_or(1.0),
            contrast: cli.image_contrast.unwrap_or(1.0),
            gamma: cli.image_gamma.unwrap_or(1.0),
        })
        .mode(to_art_image_mode(cli.image_mode))
        .width(width)
        .color(!cli.no_color);
    if let Some(height) = cli.height {
        art = art.height(height);
    }
    if let Some(columns) = cli.image_max_width {
        art = art.max_width(columns);
    }
    if let Some(rows) = cli.image_max_height {
        art = art.max_height(rows);
    }

    if let Some(fit) = cli.image_fit.as_deref() {
        art = art.fit(match fit {
            "cover" => rich_art::ImageFit::Cover,
            "stretch" => rich_art::ImageFit::Stretch,
            "native" => rich_art::ImageFit::Native,
            _ => rich_art::ImageFit::Contain,
        });
    }
    if let Some(anchor) = cli.image_anchor.as_deref() {
        use rich_art::ImageAnchor;
        art = art.anchor(match anchor {
            "top" => ImageAnchor::Top,
            "bottom" => ImageAnchor::Bottom,
            "left" => ImageAnchor::Left,
            "right" => ImageAnchor::Right,
            "top-left" => ImageAnchor::TopLeft,
            "top-right" => ImageAnchor::TopRight,
            "bottom-left" => ImageAnchor::BottomLeft,
            "bottom-right" => ImageAnchor::BottomRight,
            _ => ImageAnchor::Center,
        });
    }
    match cli.image_background {
        Some(ImageBackdrop::Color(rgb)) => art = art.background(rgb),
        Some(ImageBackdrop::Terminal) => {
            art = art.background_mode(rich_art::ImageBackground::TerminalDefault)
        }
        Some(ImageBackdrop::Checkerboard) => {
            art = art.background_mode(rich_art::ImageBackground::Checkerboard)
        }
        None => {}
    }
    let (color_mode, dither, distance) = image_color_processing(cli);
    art = art
        .color_mode(color_mode)
        .dither(dither)
        .color_distance(distance);

    // Validate up front: `Renderable::rich_render` cannot fail and would
    // silently fall back to ASCII, which is the wrong answer for a CLI that
    // promised a clear error (e.g. `--image-mode sixel` on a build without
    // the `sixel` feature, or an image Sixel cannot encode).
    let options = console.options();
    if let Err(err) = art.render(console, &options) {
        // rich-art reports an unrecognised terminal as `SixelNotSupported`;
        // this covers a console that is a terminal where the art render
        // target decided it was not (e.g. a forced width on a pipe).
        let message = match err {
            rich_art::ImageArtError::NonTerminalDestination if console.is_terminal() => format!(
                "this terminal (TERM={}) is not known to support Sixel graphics; set \
                 RICH_SIXEL=1 or RICH_GRAPHICS=sixel to use Sixel anyway, or choose \
                 --image-mode blocks, braille or ascii",
                std::env::var("TERM").unwrap_or_default()
            ),
            err => err.to_string(),
        };
        return fail(cli, ExitClass::Input, message);
    }

    let terminal_only = Export {
        html_path: None,
        svg_path: None,
        png_path: None,
        ..*export
    };
    if let Err(message) = emit(console, &terminal_only, |c| c.print(&art)) {
        return fail(cli, ExitClass::Input, message);
    }
    if export.any_file() {
        use rich::protocol::RenderEnvironment;
        use rich_ext::target::{RenderTarget, TargetKind, TargetOverrides};
        let mut caps = render_target::observe(console, TargetOverrides::default()).capabilities;
        caps.color_system = if cli.no_color {
            None
        } else {
            Some(ColorSystem::Truecolor)
        };
        let target = RenderTarget::new(TargetKind::Html, caps, console.theme().clone());
        let export_console = target.console();
        if let Err(err) =
            art.render_with_environment(&export_console, &export_console.options(), &target)
        {
            return fail(cli, ExitClass::Input, err.to_string());
        }
        let segments = target.segments(&art);
        debug_assert!(!target.capabilities().interactive);
        if let Err(message) = save_exports(&export_console, export, &segments) {
            return fail(cli, ExitClass::Input, message);
        }
    }
    success(cli)
}

#[cfg(feature = "art")]
fn run_diff(cli: &Cli, console: &Console, export: &Export) -> ExitCode {
    use rich::Table;
    use rich_art::imagediff::{DiffSettings, diff};
    use rich_art::{AsciiArt, BlockArt, BrailleArt, SixelArt};

    let (before_path, after_path) = (&cli.resources[0], &cli.resources[1]);
    let before = match open_image_path(before_path) {
        Ok(image) => image,
        Err(message) => return fail(cli, ExitClass::Input, message),
    };
    let after = match open_image_path(after_path) {
        Ok(image) => image,
        Err(message) => return fail(cli, ExitClass::Input, message),
    };

    let report = match diff(&before, &after, &DiffSettings::default()) {
        Ok(report) => report,
        Err(err) => return fail(cli, ExitClass::Data, err.to_string()),
    };

    let width = cli.width.unwrap_or_else(|| console.width());
    let changed = report.changed_fraction * 100.0;
    let naive = report.naive_changed_fraction * 100.0;

    // Decided before rendering so the verdict can be part of the output (and
    // therefore part of an --export-svg capture), while the exit code is
    // settled outside the closure.
    // Compare the number that is PRINTED, not the one behind it. Comparing full
    // precision against a one-decimal display produced "FAIL 5.4% changed, limit
    // 5.4%" -- a verdict that contradicts itself and cannot be explained from
    // the output, which is what anyone tuning a threshold to the reported figure
    // runs straight into.
    let failed = cli
        .diff_threshold
        .is_some_and(|limit| diff_threshold_exceeded(changed, limit));

    let render_report = |c: &Console, for_export: bool| {
        // Leave room for the summary, the table and the prompt, so the top of
        // the picture is not scrolled off before the reader sees it.
        let rows_cap = console.height().saturating_sub(14).clamp(6, 30);

        // Resolve `auto` from what this console can ACTUALLY do, not from the
        // --no-color flag alone. Redirected output has no colour, and a
        // half-block render without colour is a solid rectangle of identical
        // characters -- 30 rows carrying no information. Sixel is a control
        // sequence, so it is dropped entirely when the destination is not a
        // terminal.
        let has_color = c.color_system().is_some() && !cli.no_color;
        let is_terminal = c.is_terminal();
        let mut mode = cli.image_mode;
        if mode == ImageMode::Auto {
            if !has_color && !for_export && cli.report_format == ReportFormat::Human {
                eprintln!(
                    "rich: auto image mode has no terminal colour, drawing the diff as ASCII instead"
                );
            }
            mode = if !has_color {
                ImageMode::Ascii
            } else if is_terminal && rich_art::sixel::is_probably_supported() {
                ImageMode::Sixel
            } else {
                ImageMode::Blocks
            };
        }

        // An explicit choice still has to produce something. Downgrade rather
        // than emit a rectangle of identical blocks or nothing at all, and say
        // why on stderr so the change is visible rather than mysterious.
        if matches!(mode, ImageMode::Blocks | ImageMode::Quadrants) && !has_color {
            if !for_export && cli.report_format == ReportFormat::Human {
                eprintln!("rich: no colour available, drawing the diff as ASCII art");
            }
            mode = ImageMode::Ascii;
        }
        if mode == ImageMode::Sixel && !is_terminal {
            if cli.image_mode != ImageMode::Sixel
                && !for_export
                && cli.report_format == ReportFormat::Human
            {
                eprintln!(
                    "rich: Sixel graphics need a terminal, drawing the diff as {} instead",
                    if has_color { "blocks" } else { "ASCII art" }
                );
            }
            mode = if has_color {
                ImageMode::Blocks
            } else {
                ImageMode::Ascii
            };
        }

        match mode {
            ImageMode::None => {}
            ImageMode::Ascii => c.print(
                &AsciiArt::new(report.heatmap())
                    .width(width)
                    .color(has_color),
            ),
            ImageMode::Blocks => c.print(
                &BlockArt::new(report.heatmap())
                    .width(width)
                    .height(rows_cap),
            ),
            ImageMode::Quadrants => c.print(
                &rich_art::QuadrantArt::new(report.heatmap())
                    .width(width)
                    .height(rows_cap),
            ),
            ImageMode::Braille => c.print(
                &BrailleArt::new(report.heatmap())
                    .width(width)
                    .height(rows_cap),
            ),
            ImageMode::Sixel => {
                let art = SixelArt::new(report.heatmap())
                    .width(width)
                    .height(rows_cap);
                // Encoding can still fail on a terminal; the report must stay
                // useful, so fall back rather than leaving an empty gap.
                if art.encode(width).is_some() {
                    c.print(&art);
                } else {
                    if cli.report_format == ReportFormat::Human {
                        eprintln!("rich: could not encode Sixel, drawing the diff as blocks");
                    }
                    c.print(
                        &BlockArt::new(report.heatmap())
                            .width(width)
                            .height(rows_cap),
                    );
                }
            }
            ImageMode::Auto => unreachable!("resolved above"),
        }
        // The blank line separates the picture from the summary, so it belongs
        // to the picture — with --image-mode none it was just a stray first
        // line in every report and every redirected file.
        if mode != ImageMode::None {
            c.print_str("");
        }
        c.print_str(&format!(
            "[bold]{changed:.1}%[/] of the canvas changed perceptibly \
             [dim](a plain pixel diff would say {naive:.1}%)[/]"
        ));

        if report.regions.is_empty() {
            c.print_str("[dim]No region large enough to report.[/]");
        } else {
            let mut table = Table::new().title("Where it changed");
            table.add_column("#");
            table.add_column_justify("Share", rich::Justify::Right);
            table.add_column_justify("Mean ΔE", rich::Justify::Right);
            table.add_column_justify("Area px", rich::Justify::Right);
            table.add_column("Box (x,y w×h)");
            for (rank, r) in report.regions.iter().enumerate() {
                table.add_row(&[
                    &format!("{}", rank + 1),
                    &format!("{:.0}%", r.share_of_change * 100.0),
                    &format!("{:.1}", r.mean_delta_e),
                    &format!("{}", r.area_px),
                    &format!("{},{} {}×{}", r.x, r.y, r.width, r.height),
                ]);
            }
            c.print(&table);
        }

        // The gate is compared against the perceptual figure, never the naive
        // one — gating on a pixel diff is what makes visual regression testing
        // useless in the first place.
        if let Some(limit) = cli.diff_threshold {
            if failed {
                c.print_str(&format!(
                    "[bold red]FAIL[/] {changed:.1}% changed, limit {limit:.1}%"
                ));
            } else {
                c.print_str(&format!(
                    "[bold green]OK[/] {changed:.1}% changed, within {limit:.1}%"
                ));
            }
        }
    };

    let terminal_only = Export {
        html_path: None,
        svg_path: None,
        png_path: None,
        ..*export
    };
    let mut wrote = emit(console, &terminal_only, |c| render_report(c, false));
    if export.any_file() {
        // HTML/SVG support truecolor independently of stdout. Render the already
        // loaded report for that destination; never reread images or recompute
        // the comparison. A nonterminal console prevents Sixel control data.
        let mut export_console = crate::console_builder()
            .force_terminal(false)
            .color_system(Some(ColorSystem::Truecolor))
            .no_color(cli.no_color)
            .width(console.width())
            .height(console.height())
            .theme(console.theme().clone())
            .build();
        install_render_defaults(&mut export_console);
        let segments = export_console.record_output(|c| render_report(c, true));
        wrote = wrote.and_then(|()| save_exports(&export_console, export, &segments));
    }

    if let Err(message) = wrote {
        return fail(cli, ExitClass::Input, message);
    }
    if failed {
        return fail(cli, ExitClass::Gate, "diff threshold exceeded");
    }
    success(cli)
}

/// Animate every `--gif` resource at once, sharing the console width.
/// `--image-background`: what transparent pixels become.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[cfg_attr(not(feature = "art"), allow(dead_code))]
enum ImageBackdrop {
    /// `#RRGGBB`: composite onto this colour.
    Color([u8; 3]),
    /// `default`: leave transparent cells to the terminal's background.
    Terminal,
    /// `checkerboard`: composite onto a gray checkerboard.
    Checkerboard,
}

impl ImageBackdrop {
    fn parse(value: &str) -> Option<Self> {
        match value {
            "default" => return Some(ImageBackdrop::Terminal),
            "checkerboard" => return Some(ImageBackdrop::Checkerboard),
            _ => {}
        }
        let hex = value.strip_prefix('#')?;
        if hex.len() != 6 || !hex.bytes().all(|b| b.is_ascii_hexdigit()) {
            return None;
        }
        let channel = |i: usize| u8::from_str_radix(&hex[i * 2..i * 2 + 2], 16).ok();
        Some(ImageBackdrop::Color([
            channel(0)?,
            channel(1)?,
            channel(2)?,
        ]))
    }
}

/// `--image-color`, `--image-dither` and `--image-color-distance`, shared by
/// still images and GIF frames. Unset options are the library defaults.
#[cfg(feature = "art")]
fn image_color_processing(
    cli: &Cli,
) -> (
    rich_art::ImageColorMode,
    rich_art::Dither,
    rich_art::ColorDistance,
) {
    use rich_art::{ColorDistance, Dither, ImageColorMode};
    let mode = match cli.image_color.as_deref() {
        Some("ansi256") => ImageColorMode::Ansi256,
        Some("ansi16") => ImageColorMode::Ansi16,
        Some("grayscale") => ImageColorMode::Grayscale,
        _ => ImageColorMode::TrueColor,
    };
    let dither = match cli.image_dither.as_deref() {
        Some("floyd-steinberg") => Dither::FloydSteinberg,
        Some("bayer4x4") => Dither::Bayer4x4,
        Some("atkinson") => Dither::Atkinson,
        _ => Dither::None,
    };
    let distance = match cli.image_color_distance.as_deref() {
        Some("oklab") => ColorDistance::Oklab,
        _ => ColorDistance::Rgb,
    };
    (mode, dither, distance)
}

#[cfg(feature = "art")]
fn play_gifs(cli: &Cli, console: &Console) -> ExitCode {
    use rich_art::{AnimatedArt, Repeat, Stage, Until};

    if cli.resources.is_empty() {
        return fail(cli, ExitClass::Usage, "--gif needs at least one GIF path");
    }
    let count = cli.resources.len();
    const GAP: usize = 2;

    // Share the width between the animations, leaving room for the gaps.
    let total = cli.width.unwrap_or_else(|| console.width());
    let per_gif = total
        .saturating_sub(GAP * count.saturating_sub(1))
        .checked_div(count)
        .unwrap_or(total)
        .max(8);

    let repeat = match cli.loops {
        Some(0) => Repeat::Forever,
        Some(n) => Repeat::Times(n),
        None => Repeat::Times(1),
    };

    let mut arts = Vec::with_capacity(count);
    for path in &cli.resources {
        match AnimatedArt::from_path(path) {
            Ok(art) => {
                let (color_mode, dither, distance) = image_color_processing(cli);
                arts.push(
                    art.width(per_gif)
                        .blocks(cli.extensions.gif_blocks())
                        .color(!cli.no_color)
                        .color_mode(color_mode)
                        .dither(dither)
                        .color_distance(distance)
                        .repeat(repeat),
                );
            }
            Err(err) => {
                return fail(cli, ExitClass::Input, format!("cannot read {path}: {err}"));
            }
        }
    }

    if !console.is_terminal() && cli.report_format == ReportFormat::Human {
        eprintln!("rich: GIF animation needs a terminal; rendering the first frame only");
    }

    // `play` needs its own console (it moves into the Live display).
    let mut builder = crate::console_builder().no_color(cli.no_color);
    if cli.themed() {
        builder = builder.theme(cli_theme(cli));
    }
    // Parallel workers spool output, but render for the parent's destination.
    // Pager policy still checks the real stdout handle before starting a pager.
    if let Ok(terminal) = std::env::var("RS_RICH_BATCH_TERMINAL") {
        builder = builder.force_terminal(terminal == "1");
    }
    if let Some(width) = cli.width {
        builder = builder.width(width);
    }
    let console = builder.build();
    let played = if cli.animation.needs_player() && console.is_terminal() {
        // `--speed` and `--max-frames` need the CLI's own clock.
        let passes = match repeat {
            Repeat::Forever => None,
            Repeat::Times(n) => Some(n),
            Repeat::Once => Some(1),
        };
        animation::play(arts, GAP, passes, &cli.animation, console)
    } else {
        // Colour art is byte-heavy; `--fps` (default 30) keeps it comfortable.
        let fps = cli.animation.fps();
        let mut stage = Stage::new().gap(GAP);
        for art in arts {
            stage = stage.with(art.max_fps(fps));
        }
        if let Some(limit) = cli.animation.max_duration {
            stage = stage.until(Until::Elapsed(limit));
        }
        stage.play_stdout(console)
    };
    match played {
        Ok(()) => success(cli),
        Err(err) => fail(cli, ExitClass::Input, format!("playback failed: {err}")),
    }
}

/// Without the `art` feature there is no GIF support.
#[cfg(not(feature = "art"))]
fn play_gifs(_cli: &Cli, _console: &Console) -> ExitCode {
    fail(
        _cli,
        ExitClass::Usage,
        "this build has no GIF support (rebuild with the `art` feature)",
    )
}

/// Where a render action's output goes: straight to the terminal, or captured
/// into a self-contained HTML or SVG document.
struct Export<'a> {
    /// `--export-html PATH`, if given.
    html_path: Option<&'a str>,
    /// `--export-svg PATH`, if given.
    svg_path: Option<&'a str>,
    /// `--export-png PATH`, if given.
    png_path: Option<&'a str>,
    /// Document title for the SVG and PNG frames (the resource's file name).
    svg_title: &'a str,
    /// `--pager`: page the terminal output instead of writing it straight out.
    pager: bool,
    auto_pager: bool,
}

impl Export<'_> {
    /// Whether the output goes straight to the terminal and nowhere else: no
    /// export, no pager, no watch capture.
    fn terminal_only(&self) -> bool {
        !watch::capturing() && !self.any_file() && !self.pager && !self.auto_pager
    }

    /// Whether any file export (`--export-html`, `--export-svg`,
    /// `--export-png`) was asked for.
    fn any_file(&self) -> bool {
        self.html_path.is_some() || self.svg_path.is_some() || self.png_path.is_some()
    }
}

/// Render once and deliver it everywhere it was asked for.
///
/// The exports do **not** replace the terminal output — upstream prints the
/// resource *and* saves the files, and both `--export-html` and `--export-svg`
/// may be given together. So when either is set the render is recorded once and
/// the same segments are turned into terminal bytes, HTML and SVG. Diff reports
/// use separate destination capabilities after loading/comparing the images;
/// ordinary input renderables are recorded once here.
///
/// Returns false if a file could not be written, so the caller can exit non-zero.
fn should_page(
    explicit: bool,
    automatic: bool,
    terminal: bool,
    lines: usize,
    height: usize,
) -> bool {
    terminal && (explicit || (automatic && lines > height.saturating_sub(1)))
}

fn emit(console: &Console, export: &Export, render: impl FnOnce(&Console)) -> Result<(), String> {
    if export.terminal_only() {
        render(console);
        return Ok(());
    }
    emit_segments(console, export, console.record_output(render))
}

/// [`emit`] for output already rendered, as `print` would have written it
/// (with its final newline).
fn emit_segments(console: &Console, export: &Export, segments: Vec<Segment>) -> Result<(), String> {
    if watch::capturing() {
        // A live watch region repaints these segments itself.
        watch::capture_segments(segments);
        return Ok(());
    }
    let mut first_error = None;

    // The terminal still gets the output, exports or not.
    let terminal = console.segments_to_string(&segments);
    if should_page(
        export.pager,
        export.auto_pager,
        std::io::stdout().is_terminal(),
        terminal.lines().count(),
        console.height(),
    ) {
        // The text is already rendered, so hand it straight to the pager
        // rather than re-rendering through `Console::page`.
        if let Err(err) = rich::pager::Pager::show(&rich::pager::SystemPager, &terminal) {
            first_error = Some(format!("cannot page output: {err}"));
        }
    } else {
        let stdout = std::io::stdout();
        let mut lock = stdout.lock();
        if let Err(err) = lock.write_all(terminal.as_bytes()) {
            first_error = Some(format!("could not write output: {err}"));
        }
    }

    save_exports(console, export, &segments).and(first_error.map_or(Ok(()), Err))
}

fn save_exports(console: &Console, export: &Export, segments: &[Segment]) -> Result<(), String> {
    let filtered: Vec<Segment> = segments.iter().filter(|s| !s.control).cloned().collect();
    let segments = filtered.as_slice();
    let mut first_error = None;
    if let Some(path) = export.html_path {
        // CSS-class stylesheet form, as upstream's `save_html` default.
        let html = rich::export::export_html_classes(segments, &DEFAULT_TERMINAL_THEME);
        if let Err(err) = std::fs::write(fs_path(path), html) {
            first_error = Some(format!("failed to save HTML: {err}"));
        }
    }
    if let Some(path) = export.svg_path {
        let svg = rich::svg::export_svg(
            segments,
            &rich::SVG_EXPORT_THEME,
            export.svg_title,
            // Upstream derives this id by hashing Python reprs; a fixed one keeps
            // our output deterministic (DIVERGENCES #15).
            "rich-cli",
            console.width(),
        );
        if let Err(err) = std::fs::write(fs_path(path), svg) {
            first_error.get_or_insert_with(|| format!("failed to save SVG: {err}"));
        }
    }
    if let Some(path) = export.png_path
        && let Err(message) = save_png(path, segments, export.svg_title, console.width())
    {
        first_error.get_or_insert(message);
    }
    first_error.map_or(Ok(()), Err)
}

/// `--export-png PATH`: the segments drawn by rs-rich-record's rasteriser,
/// in rich's SVG export theme, in a window titled like the SVG's, as wide
/// as the console (#723).
#[cfg(feature = "png")]
fn save_png(path: &str, segments: &[Segment], title: &str, width: usize) -> Result<(), String> {
    use rich_record::render::png::{PngOptions, segments_png};
    let options = PngOptions {
        title,
        columns: Some(width),
        ..PngOptions::default()
    };
    let fonts = rich_record::render::raster::Fonts::embedded();
    let png = segments_png(segments, &fonts, &options)
        .map_err(|err| format!("failed to save PNG: {err}"))?;
    std::fs::write(fs_path(path), png).map_err(|err| format!("failed to save PNG: {err}"))
}

/// Without the `png` feature the parser refuses `--export-png`.
#[cfg(not(feature = "png"))]
fn save_png(_: &str, _: &[Segment], _: &str, _: usize) -> Result<(), String> {
    Err("--export-png needs a build with the png feature".into())
}

/// `--help`: the [`cli_spec`] help, through a stdout console.
fn print_help(no_color: bool) {
    cli_spec::print_help(no_color);
}

fn build_demo_console(no_color: bool) -> Console {
    let mut console = demo_console_builder(no_color).build();
    console.install_extensions();
    console
}

/// [`build_demo_console`]'s settings, before it is built.
fn demo_console_builder(no_color: bool) -> rich::console::ConsoleBuilder {
    // Force truecolor so the demo looks the same regardless of TERM — but only
    // when it is actually going to a terminal. Forcing it unconditionally wrote
    // escape sequences into a pipe, and made `--no-color` a no-op on this path
    // alone while every other mode honoured it.
    let to_terminal = std::io::stdout().is_terminal() && !no_color;
    crate::console_builder()
        .force_terminal(to_terminal)
        .no_color(no_color)
        .color_system(if to_terminal {
            Some(ColorSystem::Truecolor)
        } else {
            None
        })
        // `[error]`/`[warning]`/`[info]` are rich-ext's additions, not upstream
        // styles — the core theme is a faithful 154-entry port.
        .theme(rich_ext::extended_theme())
}

fn run_demo(no_color: bool, delay: std::time::Duration) -> Console {
    let to_terminal = std::io::stdout().is_terminal() && !no_color;
    let console = build_demo_console(no_color);

    demo::section(&console, delay, "rs-rich-cli");
    console.print_str("[bold magenta]rs-rich-cli[/] — a Rust port of [italic]rich[/]");
    console.print_str(
        "Core renderables track Python rich 15.0.0; Rust extensions add more workflows.",
    );

    // Markup, color, theme, and the rich-ext highlighter.
    demo::section(&console, delay, "markup · color · theme · extension");
    console.print_str(
        "Styles:   [bold]bold[/] [dim]dim[/] [italic]italic[/] [underline]underline[/] [reverse]reverse[/]",
    );
    console.print_str(
        "Color:    [red]red[/] [green]green[/] [blue]blue[/] [#ff8800]#ff8800[/] [white on blue]on blue[/]",
    );
    console.print_str("Theme:    [error]error[/], [warning]warning[/], [info]info[/]");
    // Upstream's theme stack: a pushed theme applies until its guard drops.
    let mut themed = build_demo_console(no_color);
    let release =
        rich::Theme::from_styles([("release", "bold magenta")], true).expect("valid demo theme");
    themed.use_theme(release).print_str(
        "Stack:    [release]release[/] from a pushed theme, popped when its guard drops",
    );
    console.print_str("Extension: numbers like 3.14 and 2026 are auto-highlighted");
    // Built-in ReprHighlighter (highlight=true): auto-colors numbers, bools,
    // strings, paths, calls, etc.
    // A second console, so it needs the same terminal/colour decision as the
    // main one — building it with force_terminal(true) unconditionally was what
    // leaked escape sequences into a pipe after the demo itself stopped.
    let hl = crate::console_builder()
        .force_terminal(to_terminal)
        .no_color(no_color)
        .color_system(if to_terminal {
            Some(ColorSystem::Truecolor)
        } else {
            None
        })
        .highlight(true)
        .build();
    hl.print_str("Highlight:  result = func(42, True, None, '/usr/bin')");
    // ISO8601Highlighter — colors date/time/timezone fields.
    let mut stamp = Text::new("2023-06-15T13:45:30+02:00");
    ISO8601Highlighter::new().highlight(&mut stamp);
    console.print(&Text::new("ISO 8601:   ").append_text(&stamp));
    console.print_str("Emoji:     :rocket: :fire: :sparkles: :thumbs_up: :snake: :coffee:");

    // Rule variants (title alignment).
    demo::section(&console, delay, "rule");
    console.print(&Rule::line());
    demo::section(&console, delay, "centered");
    console.print(&Rule::new("left").align(HorizontalAlign::Left));
    console.print(&Rule::new("right").align(HorizontalAlign::Right));

    // Panels with different boxes.
    demo::section(&console, delay, "panel");
    console.print(&Panel::new(text("rounded box (default)")).title("rounded"));
    console.print(
        &Panel::new(text("square box"))
            .box_set(SQUARE)
            .title("square"),
    );
    console.print(
        &Panel::new(text("double box"))
            .box_set(DOUBLE)
            .title("double"),
    );
    console.print(
        &Panel::new(text("title + subtitle"))
            .title("top")
            .subtitle("bottom"),
    );
    // Legacy-Windows box substitution: a ROUNDED panel falls back to SQUARE.
    let legacy = crate::console_builder()
        .force_terminal(to_terminal)
        .no_color(no_color)
        .color_system(if to_terminal {
            Some(ColorSystem::Truecolor)
        } else {
            None
        })
        .width(console.width())
        .legacy_windows(true)
        .build();
    legacy.print(&Panel::new(text("rounded → square on legacy Windows")).title("legacy"));

    // Padding (shown inside a panel so the blank space is visible).
    demo::section(&console, delay, "padding");
    console.print(
        &Panel::new(Box::new(Padding::new(text("padded (1, 4)"), (1, 4, 1, 4)))).title("padding"),
    );

    // Styled — lay one style under an entire renderable.
    demo::section(&console, delay, "styled");
    console.print(&Styled::new(
        Box::new(Panel::new(text("green under the whole panel")).title("styled")),
        Style::parse("green").unwrap(),
    ));

    // Horizontal alignment (fills the console width).
    demo::section(&console, delay, "align");
    console.print(&Align::left(text("← left")));
    console.print(&Align::center(text("center")));
    console.print(&Align::right(text("right →")));

    // Text justify (via print(justify=…)).
    demo::section(&console, delay, "justify");
    console.print_justified("left justified", Justify::Left);
    console.print_justified("centered", Justify::Center);
    console.print_justified("right justified", Justify::Right);

    // Constrain — same panel, capped to 24 cells.
    demo::section(&console, delay, "constrain (width 24)");
    console.print(&Constrain::new(
        Box::new(Panel::new(text("constrained")).title("≤24")),
        Some(24),
    ));

    // Table.
    demo::section(&console, delay, "table");
    let mut table = Table::new().title("ported renderables");
    // A styled column and a fixed-width column (content wraps with ellipsis).
    table
        .add_column("Renderable")
        .column_style(Style::parse("cyan").unwrap());
    table.add_column("Module").column_width(12);
    table.add_column_justify("Parity", Justify::Center);
    for (renderable, module, parity) in [
        ("Text / markup", "text, markup", "✓"),
        ("Rule", "rule", "✓"),
        ("Panel", "panel", "✓"),
        ("Padding", "padding", "✓"),
        ("Align", "align", "✓"),
        ("Constrain", "constrain", "✓"),
        ("Columns", "columns", "✓"),
        ("Table", "table", "✓"),
        ("Tree", "tree", "✓"),
        ("ProgressBar", "progress_bar", "✓"),
    ] {
        table.add_row(&[renderable, module, parity]);
    }
    console.print(&table);

    // Columns — packs items into as many columns as fit the width.
    demo::section(&console, delay, "columns");
    let months = [
        "January",
        "February",
        "March",
        "April",
        "May",
        "June",
        "July",
        "August",
        "September",
        "October",
        "November",
        "December",
    ];
    console.print(&Columns::new(
        months.iter().map(|m| m.to_string()).collect(),
    ));

    // Tree.
    demo::section(&console, delay, "tree");
    let mut tree = Tree::new("rs-rich-cli");
    let core = tree.add("crates/rich (core, mirrors rich 15.0.0)");
    core.add("color · style · text · console");
    core.add("box · rule · panel · padding · align");
    core.add("table · tree · wrap · filesize");
    tree.add("crates/rich-ext (our extensions)");
    tree.add("crates/rich-cli (this binary)");
    console.print(&tree);

    // Progress bars at a few completion levels (0 → 100%).
    demo::section(&console, delay, "progress bar");
    for pct in [0.0, 33.0, 66.0, 100.0] {
        console.print(&ProgressBar::new(100.0, pct).width(48));
    }

    // Progress display with upstream's default columns (description, bar,
    // percentage, time remaining), driven by a simulated clock so the frame is
    // deterministic: speeds and ETAs come from real task samples.
    demo::section(&console, delay, "progress");
    let clock = std::sync::Arc::new(std::sync::atomic::AtomicU64::new(0f64.to_bits()));
    let set_time =
        |seconds: f64| clock.store(seconds.to_bits(), std::sync::atomic::Ordering::SeqCst);
    let reader = clock.clone();
    let now = move || f64::from_bits(reader.load(std::sync::atomic::Ordering::SeqCst));
    let mut progress = Progress::new().clock(now.clone());
    let downloading = progress.add_task("Downloading", 100.0, 0.0);
    let processing = progress.add_task("Processing", 100.0, 0.0);
    progress.add_task("Waiting", 100.0, 0.0);
    set_time(4.0);
    progress.advance(downloading, 20.0);
    progress.advance(processing, 60.0);
    set_time(8.0);
    progress.advance(downloading, 30.0);
    progress.advance(processing, 40.0);
    console.print(&progress);

    // Time, rate and spinner columns on a simulated transfer.
    let mut transfer = Progress::new().clock(now).columns(vec![
        ProgressColumn::spinner(),
        ProgressColumn::Description,
        ProgressColumn::Bar,
        ProgressColumn::Download,
        ProgressColumn::TransferSpeed,
        ProgressColumn::TimeElapsed,
        ProgressColumn::time_remaining(),
    ]);
    let iso = transfer.add_task("ubuntu.iso", 4_700_000_000.0, 0.0);
    let notes = transfer.add_task("notes.txt", 42_000.0, 0.0);
    set_time(12.0);
    transfer.advance(iso, 1_200_000_000.0);
    transfer.advance(notes, 20_000.0);
    set_time(20.0);
    transfer.advance(iso, 900_000_000.0);
    transfer.advance(notes, 22_000.0);
    console.print(&transfer);

    // Progress with custom columns — description + bar + M-of-N counter.
    let mut mofn = Progress::new().columns(vec![
        ProgressColumn::Description,
        ProgressColumn::Bar,
        ProgressColumn::MofN,
    ]);
    mofn.add_task("Files", 8.0, 3.0);
    mofn.add_task("Chunks", 128.0, 128.0);
    console.print(&mofn);

    // Progress with a download column — completed/total in shared byte units.
    let mut download = Progress::new().columns(vec![
        ProgressColumn::Description,
        ProgressColumn::Bar,
        ProgressColumn::Download,
    ]);
    download.add_task("archive.tar", 10_000_000.0, 4_200_000.0);
    console.print(&download);

    // JSON — pretty-printed and highlighted.
    demo::section(&console, delay, "json");
    if let Ok(json) = Json::new(
        r#"{"port": "rich", "version": "15.0.0", "parity": true, "widgets": ["panel", "table", "tree"]}"#,
    ) {
        console.print(&json);
    }

    // Pretty — colorize a Rust value's Debug output (Rust-native rich.pretty).
    demo::section(&console, delay, "pretty");
    let value = vec![("panel", 1u32), ("table", 2), ("tree", 3)];
    console.print(&Pretty::new(&value));

    // Log records — upstream's LogRender grid: a repeated time is blanked.
    demo::section(&console, delay, "log");
    let log = LogRender::new().show_level(true);
    for (level, message) in [
        (LogLevel::Info, "server started on port 8080"),
        (LogLevel::Debug, "cache warm: 128 entries"),
        (LogLevel::Warn, "disk usage at 85%"),
        (LogLevel::Error, "connection reset by peer"),
    ] {
        console.print(&log.render(
            &console,
            Text::new(message),
            Some(Text::new("[12:00:00]")),
            level.text(),
            Some("main.rs"),
            Some(42),
            None,
        ));
    }
    // Console.log fills the same grid in: the time, the message and the
    // caller. A fixed clock and a pseudo-file (`<demo>`, which links
    // nowhere) keep the tour the same on every run.
    let logging = || {
        let mut logger = demo_console_builder(no_color)
            .get_datetime(|| std::time::UNIX_EPOCH + std::time::Duration::from_secs(12 * 3600))
            .build();
        logger.install_extensions();
        logger
    };
    let logger = logging();
    for (line, message) in [
        (
            7,
            "[bold]console.log[/]: the time, the message and the caller",
        ),
        (8, "a log in the same second leaves the time blank"),
    ] {
        let _ = logger.log_at(
            &[rich::LogObject::Str(message)],
            &rich::LogOptions::default(),
            "<demo>",
            line,
        );
    }
    // Progress.log: logs land above a running progress display.
    let live = Progress::new()
        .clock(|| 0.0)
        .columns(vec![
            ProgressColumn::Description,
            ProgressColumn::Bar,
            ProgressColumn::MofN,
        ])
        .start(logging(), std::io::stdout(), 10.0);
    let deploy = live.add_task("Deploying", 3.0, 0.0);
    for (line, step) in [(12, "built"), (13, "tested"), (14, "shipped")] {
        if !delay.is_zero() {
            std::thread::sleep(delay / 3);
        }
        let message = format!("progress.log: [green]{step}[/]");
        let _ = live.log_at(
            &[rich::LogObject::Str(&message)],
            &rich::LogOptions::default(),
            "<demo>",
            line,
        );
        live.advance(deploy, 1.0);
    }
    let _ = live.stop();

    // Traceback — render an error + its source chain (Rust-native rich.traceback).
    demo::section(&console, delay, "traceback");
    let cause = std::io::Error::new(std::io::ErrorKind::NotFound, "no such file: config.toml");
    let err = std::io::Error::other(cause);
    console.print(&Traceback::new(&err));

    // Bar — a filled span within a range (eighth-block resolution).
    demo::section(&console, delay, "bar (range)");
    for (begin, end) in [(0.0, 100.0), (0.0, 62.0), (20.0, 80.0), (55.0, 100.0)] {
        console.print(&Bar::new(100.0, begin, end).width(48));
    }

    // Markdown — headings, inline styles, lists, block quotes, tables, and rules.
    demo::section(&console, delay, "markdown");
    console.print(&Markdown::new(
        "# Heading\n\nA paragraph with **bold**, *italic*, `code`, ~~struck~~ text, and a [link](https://example.com).\nTilde runs pair as upstream pairs them: a ~~~x~~~ b.\n\n- bullet item\n- another\n\n1. first\n2. second\n\n> a block quote\n\n| Name | Age |\n| :--- | ---: |\n| Alice | 30 |\n| Bob | 7 |\n\n```rust\nfn main() {\n    println!(\"hi\");\n}\n```\n\n---",
    ));

    // Syntax highlighting (via syntect — functional, not byte-parity with rich).
    demo::section(&console, delay, "syntax");
    console.print(&Syntax::new(
        "fn main() {\n    let msg = \"hello, rich\";\n    println!(\"{msg}\");\n}",
        "rust",
    ));

    // Control codes — cursor/screen sequences (shown escaped, not executed).
    demo::section(&console, delay, "control codes");
    let show_escape = |label: &str, control: &Control| {
        // Escaped so the sequence is visible (and its `[` isn't read as markup).
        let escaped = control
            .as_str()
            .replace('\x1b', "\\x1b")
            .replace('\x07', "\\a")
            .replace('\r', "\\r");
        console.print(&Text::new(format!("  {label:>14}: {escaped}")));
    };
    show_escape("clear screen", &Control::clear());
    show_escape("home", &Control::home());
    show_escape("move (2,-1)", &Control::move_(2, -1));
    show_escape("move_to (3,4)", &Control::move_to(3, 4));
    show_escape("hide cursor", &Control::show_cursor(false));
    show_escape("bell", &Control::bell());
    // LiveRender — the in-place redraw sequence for a 3-line render.
    let live_render = LiveRender::new(text("a\nb\nc"));
    let _ = console.render_to_string(&live_render); // render once to record the shape
    show_escape("live refresh", &live_render.position_cursor());
    // Live — the full control stream for a two-frame in-place update (captured
    // to a buffer so the demo stays static instead of animating).
    let live_console = crate::console_builder()
        .force_terminal(true)
        .color_system(Some(ColorSystem::Truecolor))
        .width(20)
        .build();
    let mut live = Live::new(text("frame one"), live_console, Vec::<u8>::new());
    live.start();
    live.update(text("frame two"));
    live.stop();
    let stream = String::from_utf8_lossy(live.writer())
        .replace('\x1b', "\\x1b")
        .replace('\r', "\\r")
        .replace('\n', "\\n");
    console.print(&Text::new(format!("  {:>14}: {stream}", "live stream")));

    // ANSI decoder — parse a raw SGR string back into styled Text, then re-render.
    demo::section(&console, delay, "ansi decoder");
    let raw =
        "\x1b[1;31mred bold\x1b[0m \x1b[38;5;214morange\x1b[0m \x1b[3;4mitalic underline\x1b[0m";
    console.print(&Text::new(format!(
        "  input:  {}",
        raw.replace('\x1b', "\\x1b")
    )));
    let mut decoder = rich::AnsiDecoder::new();
    for line in raw.lines().map(|line| decoder.decode_line(line)) {
        console.print(&Text::new("  output: ").append_text(&line));
    }

    // Capture / export — record a rendering to a buffer, then strip its styles.
    demo::section(&console, delay, "capture · export_text");
    let plain = console.export_text(|c| {
        c.print(&Panel::new(text("captured panel")).box_set(SQUARE));
    });
    console.print(&Text::new("  export_text (styles stripped):"));
    for line in plain.lines() {
        console.print(&Text::new(format!("    {line}")));
    }
    // export_html — the inline CSS a style compiles to (via `--export-html`).
    let html_rule = Style::parse("bold red")
        .unwrap()
        .get_html_style(&DEFAULT_TERMINAL_THEME);
    console.print(&Text::new(format!(
        "  export_html: [bold red] → <span style=\"{html_rule}\">"
    )));
    // record=True keeps everything printed, for the recorded exports.
    let recorder = demo_console_builder(no_color)
        .record(true)
        .width(40)
        .build();
    recorder.print_str("[bold magenta]recorded[/] by a [green]record=True[/] console");
    let plain = recorder
        .export_text_recorded(false, false)
        .unwrap_or_default();
    let html = recorder
        .export_html_recorded(&rich::ExportHtmlOptions {
            clear: false,
            inline_styles: true,
            ..Default::default()
        })
        .unwrap_or_default();
    let svg = recorder
        .export_svg_recorded(&rich::ExportSvgOptions {
            title: "demo",
            ..Default::default()
        })
        .unwrap_or_default();
    console.print(&Text::new(format!(
        "  export_text_recorded: {:?}",
        plain.trim_end()
    )));
    // The first styled span, or the size when nothing was styled.
    let span = html
        .lines()
        .find_map(|line| line.find("<span").map(|at| &line[at..]))
        .and_then(|span| span.split("</span>").next())
        .map_or_else(
            || format!("{} bytes of HTML", html.len()),
            |span| format!("{span}</span>"),
        );
    console.print(&Text::new(format!("  export_html_recorded: {span}")));
    console.print(&Text::new(format!(
        "  export_svg_recorded:  {} bytes of SVG",
        svg.len()
    )));

    // Layout — split a region into ratioed rows/columns; Panel leaves expand
    // to fill their region (rendered here at a fixed size).
    demo::section(&console, delay, "layout");
    let panel_leaf = |title: &str, body: &str| {
        Layout::with_renderable(Box::new(
            Panel::new(text(body))
                .box_set(SQUARE)
                .title(title.to_string()),
        ))
    };
    let mut header = Layout::new();
    header.split_row(vec![
        panel_leaf("left", "pane A"),
        panel_leaf("right", "pane B"),
    ]);
    let mut root = Layout::new();
    root.split_column(vec![
        header,
        Layout::with_renderable(text("footer (fixed size 3)")).size(3),
    ]);
    let grid = crate::console_builder()
        .force_terminal(true)
        .color_system(Some(ColorSystem::Truecolor))
        .width(48)
        .height(7)
        .build();
    for line in grid.export_text(|c| c.print(&root)).lines() {
        console.print(&Text::new(line));
    }

    // Spinners — a few frames of each built-in (animation needs a Live loop).
    demo::section(&console, delay, "spinner (frames)");
    for name in ["dots", "line", "arrow", "simpleDots"] {
        let spinner = Spinner::new(name);
        let frames: String = (0..6)
            .map(|i| console.render_to_string(&spinner.render(i as f64 * 0.15)))
            .collect::<Vec<_>>()
            .join(" ");
        console.print_str(&format!("  {name:>11}: {frames}"));
    }
    // Status — a spinner + message (green frame; animation needs a Live loop).
    let status = Status::new("Loading…").renderable().render(0.0);
    console.print(&Text::new("       status: ").append_text(&status));
    // Console.status runs that loop: a transient display, so only a
    // terminal sees it, and only while the work runs.
    if to_terminal && !delay.is_zero() {
        let _ = std::io::stdout().flush();
        let running = console.status(Status::new("console.status: working…"));
        std::thread::sleep(delay);
        running.stop();
    }
    console.print_str("  console.status: a spinner on a live display while work runs");

    // CSV rendered as a table (blue border, numeric columns bold-green + right).
    demo::section(&console, delay, "csv");
    let csv = "Product,Qty,Price\nWidget,3,9.99\nGadget,12,19.50\nGizmo,1,4.25";
    if let Some(table) = build_csv_table(csv, Some(','), None, None, (None, None), false) {
        console.print(&table);
    }

    // filesize.
    demo::section(&console, delay, "filesize");
    for bytes in [1u64, 999, 1_000, 1_500, 1_000_000, 1_500_000_000] {
        console.print_str(&format!("  {bytes:>13} → {}", filesize::decimal(bytes)));
    }
    console.print(&Rule::line());
    console
}

#[cfg(test)]
mod tests {
    use super::*;
    use rich::ColorSystem;

    /// Every render-mode spelling [`mode_flag_alias`] knows, long and short.
    const MODE_FLAGS: &[&str] = &[
        "--print",
        "-p",
        "--markdown",
        "-m",
        "--json",
        "-j",
        "-J",
        "--syntax",
        "-x",
        "--csv",
        "--ipynb",
        "--rst",
        "--jsonl",
        "--ndjson",
        "--log",
        "--rule",
        "-u",
        "--image",
        "--gif",
        "--diff",
        "--inspect",
        "--ansi-explain",
    ];

    /// A render-mode flag before a subcommand's word makes the word a
    /// resource, for every subcommand scanner: `rich -p plugins` prints it.
    #[test]
    fn a_mode_flag_before_a_subcommand_word_makes_it_a_resource() {
        for flag in MODE_FLAGS {
            assert!(mode_flag_alias(flag).is_some(), "{flag}");
        }
        let claimed = |args: &[String]| {
            let mut words = Vec::new();
            if plugins::requested(args) {
                words.push("plugins");
            }
            if doctor::requested(args) {
                words.push("doctor");
            }
            if spin::requested(args) {
                words.push("spin");
            }
            if console::requested(args) {
                words.push("console");
            }
            #[cfg(feature = "art")]
            if micro::requested(args) {
                words.push("micro");
            }
            #[cfg(feature = "record")]
            if record::requested(args) {
                words.push("record");
            }
            #[cfg(feature = "serve")]
            if serve::requested(args) {
                words.push("serve");
            }
            #[cfg(feature = "interact")]
            words.extend(interactive::requested(args));
            #[cfg(feature = "interact")]
            words.extend(approve_jump::requested(args));
            if tools::bench_dispatch(args).unwrap_or(true) {
                words.push("bench");
            }
            let roots = ConfigRoots {
                home: None,
                cwd: std::env::temp_dir(),
                no_color_env: false,
            };
            if !matches!(config::inspect(args, &roots), Ok(None)) {
                words.push("config");
            }
            words
        };
        let words = [
            "plugins", "doctor", "record", "serve", "choose", "filter", "input", "confirm",
            "pager", "date", "bench", "config", "spin", "console",
        ];
        for word in words {
            // Without a mode flag the word is the subcommand (where built).
            let plain = claimed(&[word.to_string(), "--no-color".into()]);
            assert!(plain.is_empty() || plain == [word], "{word}: {plain:?}");
            for flag in MODE_FLAGS {
                let args = [flag.to_string(), word.to_string()];
                assert_eq!(claimed(&args), Vec::<&str>::new(), "{flag} {word}");
                let args = ["--no-color".to_string(), flag.to_string(), word.to_string()];
                assert_eq!(claimed(&args), Vec::<&str>::new(), "{args:?}");
            }
        }
        assert!(plugins::requested(&["--no-color".into(), "plugins".into()]));
        assert!(doctor::requested(&["doctor".into()]));
    }

    #[cfg(feature = "art")]
    #[test]
    fn diff_threshold_uses_the_reports_tie_rounding() {
        // The report prints 0.2 against 0.2, then 0.8 against 0.7.
        assert!(!diff_threshold_exceeded(0.25, 0.24));
        assert!(diff_threshold_exceeded(0.75, 0.74));
        assert!(!diff_threshold_exceeded(0.75, 0.76));
    }

    #[test]
    fn detects_urls() {
        assert!(is_url("http://example.com"));
        assert!(is_url("https://example.com/x"));
        // RFC 3986: the scheme is case-insensitive.
        assert!(is_url("HTTPS://example.com"));
        assert!(is_url("Http://example.com"));
        assert!(!is_url("example.com"));
        assert!(!is_url("./file.md"));
        assert!(!is_url("-"));
        assert!(!is_url("")); // must not panic on a short/empty resource
        assert!(!is_url("ht"));
        assert!(!is_url("ftp://example.com"));
    }

    #[test]
    fn uninformative_extensions_defer_to_content_type() {
        assert!(is_uninformative_ext("txt"));
        assert!(is_uninformative_ext("log"));
        assert!(!is_uninformative_ext("py"));
        assert!(!is_uninformative_ext("rs"));
    }

    #[test]
    fn resource_ext_uses_basename_without_query() {
        assert_eq!(resource_ext("a.md").as_deref(), Some("md"));
        assert_eq!(resource_ext("path/to/b.RS").as_deref(), Some("rs"));
        assert_eq!(
            resource_ext("https://x.com/c.py?raw=1").as_deref(),
            Some("py")
        );
        // Dots in the host must not be mistaken for an extension.
        assert_eq!(resource_ext("https://api.example.com/data"), None);
        assert_eq!(resource_ext("https://x.com/"), None);
        assert_eq!(resource_ext("noext"), None);
    }

    #[test]
    fn content_type_maps_mode_and_lexer() {
        assert_eq!(mime_of("text/html; charset=utf-8"), "text/html");
        assert_eq!(content_type_mode("text/markdown"), Some(Mode::Markdown));
        assert_eq!(
            content_type_mode("application/json; charset=utf-8"),
            Some(Mode::Json)
        );
        assert_eq!(content_type_mode("text/csv"), Some(Mode::Csv));
        assert_eq!(content_type_mode("text/html"), None); // -> syntax, not a mode
        assert_eq!(content_type_lexer("text/html"), Some("html"));
        assert_eq!(content_type_lexer("text/x-python"), Some("python"));
        assert_eq!(content_type_lexer("text/plain"), None);
    }

    #[test]
    fn join_source_handles_string_and_array() {
        use serde_json::json;
        assert_eq!(join_source(&json!("a\nb")), "a\nb");
        // Array elements already carry their trailing newlines; they concat.
        assert_eq!(join_source(&json!(["a\n", "b"])), "a\nb");
        assert_eq!(join_source(&json!(null)), "");
    }

    #[test]
    fn ipynb_extension_auto_detects() {
        assert_eq!(detect_mode(Some("notebook.ipynb")), Mode::Ipynb);
    }

    #[test]
    fn io_label_builds_execution_count() {
        // "In [1]:" — the plain text (styles aside) should read back exactly.
        assert_eq!(
            io_label("In ", Some(1), "green", "#66ff00").plain(),
            "In [1]:"
        );
        assert_eq!(io_label("Out", None, "red", "#ee4b2b").plain(), "Out[ ]:");
    }

    #[test]
    fn parse_padding_unpacks_like_upstream() {
        assert_eq!(parse_padding("2"), Ok((2, 2, 2, 2)));
        assert_eq!(parse_padding("1,2"), Ok((1, 2, 1, 2)));
        assert_eq!(parse_padding("1,2,3,4"), Ok((1, 2, 3, 4)));
        assert_eq!(parse_padding(" 1 , 2 "), Ok((1, 2, 1, 2)));
        assert!(parse_padding("1,2,3").is_err()); // 3 values not allowed
        assert!(parse_padding("x").is_err());
    }

    #[test]
    fn parse_box_maps_names() {
        assert!(matches!(parse_box("rounded"), Ok(Some(_))));
        assert!(matches!(parse_box("HEAVY"), Ok(Some(_))));
        // `none` is upstream's default and means NO panel, not `box.NONE`.
        assert!(matches!(parse_box("none"), Ok(None)));
        assert!(parse_box("bogus").is_err());
    }

    #[test]
    fn paging_policy_respects_viewport_and_redirection() {
        assert!(!should_page(true, true, false, 100, 24));
        assert!(!should_page(false, true, true, 23, 24));
        assert!(should_page(false, true, true, 24, 24));
        assert!(should_page(true, false, true, 1, 24));
        assert!(!should_page(false, false, true, 100, 24));
    }

    #[test]
    fn worker_arguments_preserve_resources_named_like_commands() {
        for source in [["--markdown", "json", "b.md"], ["markdown", "json", "b.md"]] {
            let args: Vec<String> = source.into_iter().map(str::to_string).collect();
            assert_eq!(worker_args(&args), ["--no-config", "--markdown"]);
        }
    }

    #[test]
    fn worker_arguments_keep_option_values_and_remove_batch_operands() {
        let args: Vec<String> = [
            "--batch",
            "--title",
            "--batch",
            "--jobs",
            "2",
            "json",
            "--export-html",
            "out.html",
            "--",
            "--pager",
        ]
        .into_iter()
        .map(str::to_string)
        .collect();
        assert_eq!(
            worker_args(&args),
            ["--no-config", "--title", "--batch", "--json"]
        );
    }

    /// Batch workers render with the parent's code highlighter and theme.
    #[test]
    fn worker_arguments_keep_the_code_highlighter() {
        let args: Vec<String> = [
            "--batch",
            "--highlighter",
            "syntect",
            "--code-theme",
            "ansi_dark",
            "a.py",
        ]
        .into_iter()
        .map(str::to_string)
        .collect();
        assert_eq!(
            worker_args(&args),
            [
                "--no-config",
                "--highlighter",
                "syntect",
                "--code-theme",
                "ansi_dark"
            ]
        );
    }

    #[test]
    fn parses_pager_flag() {
        let s = |v: &str| v.to_string();
        assert!(parse(&[s("--pager"), s("x")]).unwrap().unwrap().pager);
        assert!(!parse(&[s("x")]).unwrap().unwrap().pager);
    }

    #[test]
    fn parses_watch_options_and_rejects_orphans() {
        let s = |v: &str| v.to_string();
        let cli = parse(&[
            s("--watch"),
            s("--watch-interval"),
            s("0.25"),
            s("--watch-cache"),
            s("file.md"),
        ])
        .unwrap()
        .unwrap();
        assert!(cli.watch);
        assert_eq!(cli.watch_interval, 0.25);
        assert!(cli.watch_cache);
        assert!(parse(&[s("--watch-cache"), s("file.md")]).is_err());
        assert!(parse(&[s("--watch-interval"), s("2"), s("file.md")]).is_err());
    }

    #[test]
    fn parses_multi_file_watch_options() {
        let s = |v: &str| v.to_string();
        let parse = parse_inner;
        let cli = parse(&[
            s("--watch"),
            s("--watch-debounce"),
            s("0.3"),
            s("--watch-poll"),
            s("--watch-exit-on-error"),
            s("a.md"),
            s("b.json"),
        ])
        .unwrap()
        .unwrap();
        assert_eq!(cli.resources, ["a.md", "b.json"]);
        assert_eq!(cli.watch_debounce, 0.3);
        assert!(cli.watch_poll && cli.watch_exit_on_error);
        let default = parse(&[s("--watch"), s("a.md")]).unwrap().unwrap();
        assert_eq!(default.watch_debounce, watch::DEFAULT_DEBOUNCE_SECONDS);
        assert!(!default.watch_poll && !default.watch_exit_on_error);
        for orphan in [
            vec![s("--watch-debounce"), s("0.2"), s("a.md")],
            vec![s("--watch-poll"), s("a.md")],
            vec![s("--watch-exit-on-error"), s("a.md")],
        ] {
            assert!(
                parse(&orphan)
                    .err()
                    .unwrap()
                    .contains("only has an effect with --watch")
            );
        }
        for bad in ["-0.1", "nan", "inf", "soon", "3601"] {
            assert!(parse(&[s("--watch"), s("--watch-debounce"), s(bad), s("a.md")]).is_err());
        }
        // Several resources remain an error without --watch (or --gif/--batch).
        assert!(parse(&[s("a.md"), s("b.md")]).is_err());
    }

    #[test]
    fn watch_fingerprint_distinguishes_missing_and_replaced_files() {
        let path = std::env::temp_dir().join(format!("rs-rich-watch-{}.txt", std::process::id(),));
        let _ = std::fs::remove_file(&path);
        let missing = watch_fingerprint(path.to_str().unwrap(), false, None);
        std::fs::write(&path, "first").unwrap();
        let first = watch_fingerprint(path.to_str().unwrap(), false, None);
        std::fs::write(&path, "second content").unwrap();
        let second = watch_fingerprint(path.to_str().unwrap(), false, None);
        let _ = std::fs::remove_file(&path);
        assert_eq!(missing, "missing");
        assert_ne!(first, missing);
        assert_ne!(first, second);
    }

    #[test]
    fn parses_batch_controls_and_cli_values_override_config_defaults() {
        let s = |v: &str| v.to_string();
        let cli = parse(&[
            s("--no-config"),
            s("--batch"),
            s("--jobs"),
            s("3"),
            s("-o"),
            s("out.html"),
            s("--continue-on-error"),
            s("--collision"),
            s("suffix"),
            s("input"),
        ])
        .unwrap()
        .unwrap();
        assert!(cli.batch);
        assert_eq!(cli.jobs, 3);
        assert!(cli.continue_on_error);
        assert_eq!(cli.collision, CollisionPolicy::Suffix);
    }

    #[test]
    fn batch_expansion_is_recursive_sorted_and_deduplicated() {
        let root = std::env::temp_dir().join(format!("rich-batch-test-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&root);
        let nested = root.join("nested");
        std::fs::create_dir_all(&nested).unwrap();
        std::fs::write(root.join("richbatchonly.md"), "# b").unwrap();
        std::fs::write(nested.join("richbatchnested.md"), "# a").unwrap();

        let root_arg = root.to_string_lossy().into_owned();
        let glob_arg = root
            .join("*richbatchonly.md")
            .to_string_lossy()
            .into_owned();
        let inputs = expand_batch_resources(&[root_arg, glob_arg]).unwrap();
        assert_eq!(inputs.len(), 2);
        assert!(inputs[0].ends_with("richbatchnested.md"));
        assert!(inputs[1].ends_with("richbatchonly.md"));

        std::fs::remove_dir_all(root).unwrap();
    }

    #[test]
    fn batch_output_suffixes_are_deterministic_for_collisions() {
        let inputs = ["one.md", "two.md"];
        let first = batch_export_path(Some("out.html"), inputs[0], 0, 2).unwrap();
        let second = batch_export_path(Some("out.html"), inputs[1], 1, 2).unwrap();
        assert_eq!(first, "one.html");
        assert_eq!(second, "two.html");
        assert_eq!(
            Path::new("one.html")
                .with_file_name("one-2.html")
                .to_string_lossy(),
            "one-2.html"
        );
    }

    #[test]
    fn config_profiles_support_profiles_section_and_source_errors() {
        let root = std::env::temp_dir().join(format!("rich-config-test-{}", std::process::id()));
        std::fs::create_dir_all(&root).unwrap();
        let config = root.join("config.toml");
        std::fs::write(&config, "[profiles.ci]\nmode = \"json\"\njobs = 4\n").unwrap();
        let args = vec![
            "--config".to_string(),
            config.to_string_lossy().into_owned(),
            "--profile".to_string(),
            "ci".to_string(),
        ];
        let merged = config_args(
            &args,
            &ConfigRoots {
                home: None,
                cwd: root.clone(),
                no_color_env: false,
            },
        )
        .unwrap();
        assert!(merged.windows(1).any(|arg| arg[0] == "--json"));
        assert!(
            merged
                .windows(2)
                .any(|pair| pair[0] == "--jobs" && pair[1] == "4")
        );

        let bad = root.join("bad.toml");
        std::fs::write(&bad, "[defaults]\nnot-a-setting = true\n").unwrap();
        let error = config_args(
            &["--config".to_string(), bad.to_string_lossy().into_owned()],
            &ConfigRoots {
                home: None,
                cwd: root.clone(),
                no_color_env: false,
            },
        )
        .unwrap_err();
        assert!(error.contains("config "));
        assert!(error.contains("unknown key"));
        std::fs::remove_dir_all(root).unwrap();
    }

    #[test]
    fn batch_rejects_modes_that_consume_their_whole_resource_list() {
        let s = |v: &str| v.to_string();
        let error = parse(&[s("--no-config"), s("--batch"), s("--diff"), s("a"), s("b")])
            .err()
            .unwrap();
        assert!(error.contains("--batch cannot be combined with --diff"));
        let error = parse(&[s("--no-config"), s("--batch"), s("--gif"), s("a")])
            .err()
            .unwrap();
        assert!(error.contains("--batch cannot be combined with --gif"));
        // One pager per item would open N interactive pagers over one plan.
        let error = parse(&[s("--no-config"), s("--batch"), s("--pager"), s("a")])
            .err()
            .unwrap();
        assert!(error.contains("--pager cannot be combined with --batch"));
    }

    #[test]
    fn line_counts_follow_python_splitlines() {
        assert_eq!(python_line_count(""), 0);
        assert_eq!(python_line_count("a"), 1);
        assert_eq!(python_line_count("a\n"), 1);
        assert_eq!(python_line_count("a\n\n"), 2);
        assert_eq!(python_line_count("a\r\nb"), 2);
        assert_eq!(
            python_line_count("a\rb\x0bc\x0cd\x1ce\u{85}f\u{2028}g\u{2029}h"),
            8
        );
    }

    #[test]
    fn glob_matches_metacharacters_rather_than_substrings() {
        assert!(glob_match("*.md", "notes.md"));
        // `.md` appears in the name, but the pattern anchors at the end.
        assert!(!glob_match("*.md", "notes.md.bak"));
        assert!(glob_match("a?c.md", "abc.md"));
        assert!(!glob_match("a?c.md", "ac.md"));
        assert!(glob_match("*", "anything"));
        assert!(glob_match("a*b*c", "axxbyyc"));
        assert!(!glob_match("a*b*c", "axxbyy"));
    }

    #[test]
    fn batch_expansion_skips_symlinked_directories() {
        let root = std::env::temp_dir().join(format!("rich-batch-link-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&root);
        std::fs::create_dir_all(&root).unwrap();
        std::fs::write(root.join("a.md"), "# a").unwrap();
        // A link back to the containing directory used to be walked forever.
        #[cfg(unix)]
        let linked = std::os::unix::fs::symlink(&root, root.join("loop")).is_ok();
        #[cfg(windows)]
        let linked = std::os::windows::fs::symlink_dir(&root, root.join("loop")).is_ok();
        let inputs = expand_batch_resources(&[root.to_string_lossy().into_owned()]).unwrap();
        if linked {
            assert_eq!(inputs.len(), 1, "symlinked directory must not be followed");
        }
        assert!(inputs[0].ends_with("a.md"));
        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn subcommand_mode_wins_over_config_mode_default() {
        let s = |v: &str| v.to_string();
        assert!(selects_mode_explicitly(&[s("json"), s("file.json")]));
        assert!(selects_mode_explicitly(&[s("--markdown"), s("file.md")]));
        // A value that happens to look like a subcommand is not a subcommand.
        assert!(!selects_mode_explicitly(&[
            s("--title"),
            s("json"),
            s("file")
        ]));
        assert!(!selects_mode_explicitly(&[s("file.md")]));

        let root = std::env::temp_dir().join(format!("rich-config-mode-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&root);
        std::fs::create_dir_all(&root).unwrap();
        let config = root.join("config.toml");
        std::fs::write(&config, "[defaults]\nmode = \"markdown\"\n").unwrap();
        let merged = config_args(
            &[
                "--config".to_string(),
                config.to_string_lossy().into_owned(),
                "json".to_string(),
                "file.json".to_string(),
            ],
            &ConfigRoots {
                home: None,
                cwd: root.clone(),
                no_color_env: false,
            },
        )
        .unwrap();
        assert!(
            !merged.iter().any(|arg| arg == "--markdown"),
            "config mode must not override an explicit subcommand: {merged:?}"
        );
        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn suffix_collisions_step_past_files_already_on_disk() {
        let root = std::env::temp_dir().join(format!("rich-batch-suffix-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&root);
        std::fs::create_dir_all(&root).unwrap();
        let target = root.join("out.html");
        std::fs::write(&target, "existing").unwrap();
        let target = target.to_string_lossy().into_owned();

        let cli = parse(&[
            "--no-config".to_string(),
            "--batch".to_string(),
            "--collision".to_string(),
            "suffix".to_string(),
            "x".to_string(),
        ])
        .unwrap()
        .unwrap();
        let mut taken = std::collections::BTreeSet::new();
        let first = resolve_destination(&cli, target.clone(), &mut taken).unwrap();
        assert!(
            first.ends_with("out-2.html"),
            "existing file must be kept: {first}"
        );
        let second = resolve_destination(&cli, target.clone(), &mut taken).unwrap();
        assert!(second.ends_with("out-3.html"));

        // `error` refuses rather than clobbering, and says how to proceed.
        let mut cli_error = cli.clone();
        cli_error.collision = CollisionPolicy::Error;
        let mut taken = std::collections::BTreeSet::new();
        let (class, message) =
            resolve_destination(&cli_error, target.clone(), &mut taken).unwrap_err();
        assert_eq!(class, ExitClass::Input);
        assert!(message.contains("--overwrite"));

        // `--overwrite` opts in explicitly.
        let mut cli_overwrite = cli.clone();
        cli_overwrite.overwrite = true;
        let mut taken = std::collections::BTreeSet::new();
        assert_eq!(
            resolve_destination(&cli_overwrite, target.clone(), &mut taken).unwrap(),
            target
        );
        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn batch_outputs_keep_their_export_kind() {
        // The planned path need not end in `.html`; the kind is carried, not sniffed.
        let outputs = BatchOutputs {
            html: batch_export_path(Some("result.out"), "a.md", 0, 1),
            ..BatchOutputs::default()
        };
        assert_eq!(outputs.html.as_deref(), Some("result.out"));
        assert!(outputs.svg.is_none());
    }

    #[test]
    fn parses_export_flags() {
        let s = |v: &str| v.to_string();
        // Both take a PATH, and the resource is a separate positional.
        let cli = parse(&[s("--export-svg"), s("out.svg"), s("x")])
            .unwrap()
            .unwrap();
        assert_eq!(cli.export_svg.as_deref(), Some("out.svg"));
        assert!(cli.export_html.is_none());
        assert_eq!(cli.resource.as_deref(), Some("x"));

        let cli = parse(&[s("-o"), s("out.html"), s("x")]).unwrap().unwrap();
        assert_eq!(cli.export_html.as_deref(), Some("out.html"));

        // Both together is allowed — upstream writes both files.
        let cli = parse(&[
            s("--export-html"),
            s("a.html"),
            s("--export-svg"),
            s("b.svg"),
            s("x"),
        ])
        .unwrap()
        .unwrap();
        assert_eq!(cli.export_html.as_deref(), Some("a.html"));
        assert_eq!(cli.export_svg.as_deref(), Some("b.svg"));

        // A missing PATH is an error rather than swallowing the next argument.
        assert!(parse(&[s("--export-html")]).is_err());
        // The two export formats are mutually exclusive.
    }

    #[test]
    fn is_number_matches_pattern() {
        // Every case checked against Python's own
        // `re.compile(r"\-?[0-9]*?\.?[0-9]*?").fullmatch`. The loose ones are
        // not oversights: that pattern really does accept a lone `-`, a lone
        // `.` and the empty string, and really does reject a padded `" 12 "`.
        for ok in [
            "0", "42", "-7", "3.14", "-0.5", "", "-", ".", "-.", "5.", ".5",
        ] {
            assert!(is_number(ok), "{ok:?} should be numeric");
        }
        for no in [" 12 ", "1.2.3", "1e5", "abc", "5%"] {
            assert!(!is_number(no), "{no:?} should not be numeric");
        }
    }

    #[test]
    fn render_csv_matches_upstream() {
        // Byte-parity with the Table real rich-cli's render_csv builds for this
        // CSV (captured from rich 15.0.0): HEAVY_HEAD box, blue border, the
        // numeric Age column right-justified with bold-green body + header cells.
        let table = build_csv_table(
            "Name,Age,City\nAlice,30,NYC\nBob,25,LA\n",
            Some(','),
            None,
            None,
            (None, None),
            false,
        )
        .expect("the sniffer reads this one");
        let out = Console::builder()
            .force_terminal(true)
            .color_system(Some(ColorSystem::Truecolor))
            .width(40)
            .no_color(false)
            .build()
            .render_to_string(&table);
        let expected = concat!(
            "\x1b[34m┏━━━━━━━┳━━━━━┳━━━━━━┓\x1b[0m\n",
            "\x1b[34m┃\x1b[0m\x1b[1m \x1b[0m\x1b[1mName \x1b[0m\x1b[1m \x1b[0m\x1b[34m┃\x1b[0m",
            "\x1b[1;32m \x1b[0m\x1b[1;32mAge\x1b[0m\x1b[1;32m \x1b[0m\x1b[34m┃\x1b[0m",
            "\x1b[1m \x1b[0m\x1b[1mCity\x1b[0m\x1b[1m \x1b[0m\x1b[34m┃\x1b[0m\n",
            "\x1b[34m┡━━━━━━━╇━━━━━╇━━━━━━┩\x1b[0m\n",
            "\x1b[34m│\x1b[0m Alice \x1b[34m│\x1b[0m\x1b[1;32m \x1b[0m\x1b[1;32m 30\x1b[0m",
            "\x1b[1;32m \x1b[0m\x1b[34m│\x1b[0m NYC  \x1b[34m│\x1b[0m\n",
            "\x1b[34m│\x1b[0m Bob   \x1b[34m│\x1b[0m\x1b[1;32m \x1b[0m\x1b[1;32m 25\x1b[0m",
            "\x1b[1;32m \x1b[0m\x1b[34m│\x1b[0m LA   \x1b[34m│\x1b[0m\n",
            "\x1b[34m└───────┴─────┴──────┘\x1b[0m",
        );
        assert_eq!(out, expected);
    }
}