rich/

style.rs

//! Text styles.
//!
//! Port of upstream `rich/style.py` (core attributes). A [`Style`] holds an
//! optional foreground/background [`Color`] plus a set of boolean attributes
//! (bold, italic, …). Each attribute is tri-state: `Some(true)` = on,
//! `Some(false)` = explicitly off, `None` = unset — this preserves upstream's
//! `_set_attributes`/`_attributes` bitmask semantics under [`Style::combine`].

use crate::color::{Color, ColorSystem};
use crate::errors::{Result, RichError};

/// The 13 boolean attributes, in the SGR order upstream emits them.
const ATTR_COUNT: usize = 13;

/// SGR codes per attribute index (`rich.style._STYLE_MAP`).
const ATTR_SGR: [&str; ATTR_COUNT] = [
    "1", "2", "3", "4", "5", "6", "7", "8", "9", "21", "51", "52", "53",
];

/// Canonical attribute names per index.
const ATTR_NAMES: [&str; ATTR_COUNT] = [
    "bold",
    "dim",
    "italic",
    "underline",
    "blink",
    "blink2",
    "reverse",
    "conceal",
    "strike",
    "underline2",
    "frame",
    "encircle",
    "overline",
];

/// Map a style word (including upstream's short aliases) to its attribute index.
fn attribute_index(word: &str) -> Option<usize> {
    let canonical = match word {
        "b" => "bold",
        "d" => "dim",
        "i" => "italic",
        "u" => "underline",
        "r" => "reverse",
        "c" => "conceal",
        "s" => "strike",
        "uu" => "underline2",
        "o" => "overline",
        other => other,
    };
    ATTR_NAMES.iter().position(|&n| n == canonical)
}

/// A style, or the *name* of one to be looked up later. Port of upstream's
/// `StyleType = Union[str, "Style"]` (`rich/style.py`).
///
/// A [`Span`](crate::text::Span) that holds a [`Name`](StyleType::Name) is
/// resolved when it is rendered, against the theme of the console doing the
/// rendering — so the same [`Text`](crate::text::Text) printed to two differently
/// themed consoles comes out in two different colours, as it does upstream.
/// Resolving eagerly instead would freeze the colours at construction time.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum StyleType {
    /// A theme key (`"repr.number"`) or a style definition (`"bold red"`),
    /// resolved by [`Theme::get_style`](crate::theme::Theme::get_style).
    Name(String),
    /// An already-resolved style.
    Style(Style),
}

impl Default for StyleType {
    fn default() -> Self {
        StyleType::Style(Style::new())
    }
}

impl StyleType {
    /// True when this is an already-resolved style that sets nothing. A
    /// [`Name`](StyleType::Name) is never null — it may resolve to anything.
    pub fn is_null_style(&self) -> bool {
        matches!(self, StyleType::Style(style) if style.is_null())
    }
}

impl From<Style> for StyleType {
    fn from(style: Style) -> Self {
        StyleType::Style(style)
    }
}

impl From<&Style> for StyleType {
    fn from(style: &Style) -> Self {
        StyleType::Style(style.clone())
    }
}

impl From<String> for StyleType {
    fn from(name: String) -> Self {
        StyleType::Name(name)
    }
}

impl From<&str> for StyleType {
    fn from(name: &str) -> Self {
        StyleType::Name(name.to_string())
    }
}

/// One value in a style's [`Meta`]. Upstream's meta is any marshal-able
/// Python value; this port keeps the scalar subset plus lists.
///
/// Equality follows marshal's bytes: `true` is not `1`, `1` is not `1.0`, and
/// floats compare by bit pattern (so `NaN == NaN` and `0.0 != -0.0`).
#[derive(Debug, Clone)]
pub enum MetaValue {
    /// Python `None`.
    None,
    Bool(bool),
    Int(i64),
    Float(f64),
    Str(String),
    /// A list of values.
    List(Vec<MetaValue>),
    /// A tuple of values (markup handler tags produce these). Not equal to a
    /// list of the same values, as in Python.
    Tuple(Vec<MetaValue>),
}

impl MetaValue {
    /// Python's `repr()` of the value.
    pub fn repr(&self) -> String {
        let items =
            |values: &[MetaValue]| -> Vec<String> { values.iter().map(MetaValue::repr).collect() };
        match self {
            MetaValue::None => "None".to_string(),
            MetaValue::Bool(true) => "True".to_string(),
            MetaValue::Bool(false) => "False".to_string(),
            MetaValue::Int(value) => value.to_string(),
            MetaValue::Float(value) => crate::pyformat::float_repr(*value),
            MetaValue::Str(value) => crate::markup::py_repr_str(value),
            MetaValue::List(values) => format!("[{}]", items(values).join(", ")),
            MetaValue::Tuple(values) if values.len() == 1 => format!("({},)", values[0].repr()),
            MetaValue::Tuple(values) => format!("({})", items(values).join(", ")),
        }
    }
}

impl PartialEq for MetaValue {
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (MetaValue::None, MetaValue::None) => true,
            (MetaValue::Bool(a), MetaValue::Bool(b)) => a == b,
            (MetaValue::Int(a), MetaValue::Int(b)) => a == b,
            (MetaValue::Float(a), MetaValue::Float(b)) => a.to_bits() == b.to_bits(),
            (MetaValue::Str(a), MetaValue::Str(b)) => a == b,
            (MetaValue::List(a), MetaValue::List(b)) => a == b,
            (MetaValue::Tuple(a), MetaValue::Tuple(b)) => a == b,
            _ => false,
        }
    }
}

impl Eq for MetaValue {}

impl std::hash::Hash for MetaValue {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        std::mem::discriminant(self).hash(state);
        match self {
            MetaValue::None => {}
            MetaValue::Bool(value) => value.hash(state),
            MetaValue::Int(value) => value.hash(state),
            MetaValue::Float(value) => value.to_bits().hash(state),
            MetaValue::Str(value) => value.hash(state),
            MetaValue::List(values) | MetaValue::Tuple(values) => values.hash(state),
        }
    }
}

/// A style's metadata: upstream's `Style.meta` dict. Upstream stores it
/// marshal-encoded; this port keeps the entries themselves, **in insertion
/// order**, because marshal's bytes (and so style equality) depend on it.
/// Assigning an existing key replaces its value in place, as a `dict` does.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
pub struct Meta {
    entries: Vec<(String, MetaValue)>,
}

impl Meta {
    /// Python's `repr()` of the dict.
    pub fn repr(&self) -> String {
        let entries: Vec<String> = self
            .entries
            .iter()
            .map(|(key, value)| format!("{}: {}", crate::markup::py_repr_str(key), value.repr()))
            .collect();
        format!("{{{}}}", entries.join(", "))
    }

    /// An empty map.
    pub fn new() -> Self {
        Meta::default()
    }

    /// Set `key` (`meta[key] = value`).
    pub fn insert(&mut self, key: impl Into<String>, value: MetaValue) {
        let key = key.into();
        match self
            .entries
            .iter_mut()
            .find(|(existing, _)| *existing == key)
        {
            Some((_, slot)) => *slot = value,
            None => self.entries.push((key, value)),
        }
    }

    /// The value for `key`.
    pub fn get(&self, key: &str) -> Option<&MetaValue> {
        self.entries
            .iter()
            .find(|(existing, _)| existing == key)
            .map(|(_, value)| value)
    }

    /// Merge `other` in (`dict.update`): its values win.
    pub fn update(&mut self, other: &Meta) {
        for (key, value) in &other.entries {
            self.insert(key.clone(), value.clone());
        }
    }

    /// The entries in insertion order.
    pub fn iter(&self) -> impl Iterator<Item = (&str, &MetaValue)> {
        self.entries
            .iter()
            .map(|(key, value)| (key.as_str(), value))
    }

    pub fn len(&self) -> usize {
        self.entries.len()
    }

    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }
}

impl<K: Into<String>> FromIterator<(K, MetaValue)> for Meta {
    fn from_iter<I: IntoIterator<Item = (K, MetaValue)>>(iter: I) -> Self {
        let mut meta = Meta::new();
        for (key, value) in iter {
            meta.insert(key, value);
        }
        meta
    }
}

/// FNV-1a, for caches keyed by short strings such as tag names, which
/// SipHash's setup would cost more to hash than the strings themselves.
pub(crate) struct ShortKeyHasher(u64);

impl Default for ShortKeyHasher {
    fn default() -> Self {
        ShortKeyHasher(0xcbf2_9ce4_8422_2325)
    }
}

impl std::hash::Hasher for ShortKeyHasher {
    fn finish(&self) -> u64 {
        self.0
    }

    fn write(&mut self, bytes: &[u8]) {
        for &byte in bytes {
            self.0 = (self.0 ^ u64::from(byte)).wrapping_mul(0x0100_0000_01b3);
        }
    }
}

/// A terminal text style. Mirrors `rich.style.Style`.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Style {
    color: Option<Color>,
    bgcolor: Option<Color>,
    attrs: [Option<bool>; ATTR_COUNT],
    /// An OSC 8 hyperlink target, if any.
    link: Option<String>,
    /// Upstream's `_meta`: metadata that never renders but takes part in
    /// equality and combination (`None` is upstream's `_meta = None`).
    meta: Option<Meta>,
}

impl Style {
    /// The empty (null) style — sets nothing.
    pub fn new() -> Self {
        Style::default()
    }

    /// A style carrying only a foreground and/or background color.
    /// Port of `Style.from_color`.
    pub fn from_color(color: Option<Color>, bgcolor: Option<Color>) -> Self {
        Style {
            color,
            bgcolor,
            attrs: [None; ATTR_COUNT],
            link: None,
            meta: None,
        }
    }

    pub fn with_color(mut self, color: Color) -> Self {
        self.color = Some(color);
        self
    }

    /// Attach an OSC 8 hyperlink target. Port of `Style(link=…)`.
    pub fn with_link(mut self, url: impl Into<String>) -> Self {
        self.link = Some(url.into());
        self
    }

    /// The hyperlink target, if set.
    pub fn link(&self) -> Option<&str> {
        self.link.as_deref()
    }

    /// Return a copy with the hyperlink target set (`Some`) or cleared (`None`),
    /// leaving every other attribute unchanged. Port of `Style.update_link`.
    pub fn update_link(&self, link: Option<String>) -> Style {
        let mut style = self.clone();
        style.link = link;
        style
    }

    pub fn with_bgcolor(mut self, color: Color) -> Self {
        self.bgcolor = Some(color);
        self
    }

    pub fn color(&self) -> Option<&Color> {
        self.color.as_ref()
    }

    pub fn bgcolor(&self) -> Option<&Color> {
        self.bgcolor.as_ref()
    }

    /// A copy with the foreground and background colours removed; attributes
    /// and link survive. Port of `Style.without_color`.
    pub fn without_color(&self) -> Style {
        // Upstream's `without_color` builds a new style with `_meta = None`,
        // and a null style comes back as the null style.
        if self.is_null() {
            return Style::new();
        }
        Style {
            color: None,
            bgcolor: None,
            attrs: self.attrs,
            link: self.link.clone(),
            meta: None,
        }
    }

    /// The tri-state value of attribute `index` (see the internal `attrs` order:
    /// 0=bold, 1=dim, 2=italic, 3=underline, 6=reverse, 8=strike, …).
    pub fn attr(&self, index: usize) -> Option<bool> {
        self.attrs.get(index).copied().flatten()
    }

    /// True when nothing at all is set (renders as a no-op). Non-empty
    /// metadata counts, as upstream's `_null` includes `meta`.
    pub fn is_null(&self) -> bool {
        self.color.is_none()
            && self.bgcolor.is_none()
            && self.link.is_none()
            && self.meta.as_ref().is_none_or(Meta::is_empty)
            && self.attrs.iter().all(Option::is_none)
    }

    /// Attach metadata. Port of `Style(meta=…)`. An empty map leaves the style
    /// null, but it still differs from one with no metadata at all (upstream
    /// hashes the marshal-encoded `{}`).
    pub fn with_meta(mut self, meta: Meta) -> Self {
        self.meta = Some(meta);
        self
    }

    /// The metadata, empty when none is set. Port of the `Style.meta`
    /// property.
    pub fn meta(&self) -> Meta {
        self.meta.clone().unwrap_or_default()
    }

    /// The metadata as stored: `None` when the style carries none.
    pub fn meta_ref(&self) -> Option<&Meta> {
        self.meta.as_ref()
    }

    /// A style carrying only `meta`. Port of `Style.from_meta` (null when
    /// `meta` is empty). Upstream also gives it a random `link_id`, which
    /// this port does not model (see DIVERGENCES #20).
    pub fn from_meta(meta: Meta) -> Style {
        Style::new().with_meta(meta)
    }

    /// A style with event-handler metadata. Port of `Style.on`: each handler
    /// is stored as `"@name"` over `meta` (default empty).
    pub fn on(meta: Option<Meta>, handlers: &[(&str, MetaValue)]) -> Style {
        let mut meta = meta.unwrap_or_default();
        for (name, value) in handlers {
            meta.insert(format!("@{name}"), value.clone());
        }
        Style::from_meta(meta)
    }

    /// A copy without metadata or link. Port of `Style.clear_meta_and_links`.
    pub fn clear_meta_and_links(&self) -> Style {
        let mut style = self.clone();
        style.link = None;
        style.meta = None;
        style
    }

    /// The `bold` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.bold`.
    pub fn bold(&self) -> Option<bool> {
        self.attrs[0]
    }

    /// The `dim` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.dim`.
    pub fn dim(&self) -> Option<bool> {
        self.attrs[1]
    }

    /// The `italic` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.italic`.
    pub fn italic(&self) -> Option<bool> {
        self.attrs[2]
    }

    /// The `underline` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.underline`.
    pub fn underline(&self) -> Option<bool> {
        self.attrs[3]
    }

    /// The `blink` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.blink`.
    pub fn blink(&self) -> Option<bool> {
        self.attrs[4]
    }

    /// The `blink2` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.blink2`.
    pub fn blink2(&self) -> Option<bool> {
        self.attrs[5]
    }

    /// The `reverse` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.reverse`.
    pub fn reverse(&self) -> Option<bool> {
        self.attrs[6]
    }

    /// The `conceal` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.conceal`.
    pub fn conceal(&self) -> Option<bool> {
        self.attrs[7]
    }

    /// The `strike` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.strike`.
    pub fn strike(&self) -> Option<bool> {
        self.attrs[8]
    }

    /// The `underline2` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.underline2`.
    pub fn underline2(&self) -> Option<bool> {
        self.attrs[9]
    }

    /// The `frame` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.frame`.
    pub fn frame(&self) -> Option<bool> {
        self.attrs[10]
    }

    /// The `encircle` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.encircle`.
    pub fn encircle(&self) -> Option<bool> {
        self.attrs[11]
    }

    /// The `overline` attribute: `Some(true)` on, `Some(false)` off, `None` unset.
    /// Upstream's `Style.overline`.
    pub fn overline(&self) -> Option<bool> {
        self.attrs[12]
    }

    /// The null style, which sets nothing. Port of `Style.null`.
    pub fn null() -> Style {
        Style::new()
    }

    /// A copy. Port of `Style.copy`.
    pub fn copy(&self) -> Style {
        self.clone()
    }

    /// Whether the background is unset or the terminal default. Port of the
    /// `Style.transparent_background` property.
    pub fn transparent_background(&self) -> bool {
        self.bgcolor.as_ref().is_none_or(Color::is_default)
    }

    /// A style with only this one's background color. Port of the
    /// `Style.background_style` property.
    pub fn background_style(&self) -> Style {
        Style::from_color(None, self.bgcolor.clone())
    }

    /// Combine `styles` in order, later ones winning. Port of
    /// `Style.combine` (and `Style.chain`); upstream raises on no styles,
    /// this returns `None`.
    pub fn combine_all<'a>(styles: impl IntoIterator<Item = &'a Style>) -> Option<Style> {
        let mut styles = styles.into_iter();
        let first = styles.next()?.clone();
        Some(styles.fold(first, |combined, style| combined.combine(style)))
    }

    /// The first style that is set. Port of `Style.pick_first`; upstream
    /// raises `ValueError` when all are `None`, this returns `None`.
    pub fn pick_first<T: Clone>(values: &[Option<T>]) -> Option<T> {
        values.iter().flatten().next().cloned()
    }

    /// A copy with attribute `index` set to `value` (`None` unsets it). The
    /// index follows upstream's bit order (0 = bold … 12 = overline).
    pub fn with_attr(mut self, index: usize, value: Option<bool>) -> Style {
        if let Some(slot) = self.attrs.get_mut(index) {
            *slot = value;
        }
        self
    }

    /// Write `text` (this style's definition when `None`) to stdout in this
    /// style, for testing. Port of `Style.test`.
    pub fn test(&self, text: Option<&str>) {
        let definition = self.definition();
        let text = text.filter(|text| !text.is_empty()).unwrap_or(&definition);
        println!("{}", self.render(text, Some(ColorSystem::Truecolor)));
    }

    ///
    /// Attributes come first in their canonical order, then the foreground
    /// colour, then `on <bgcolour>`, then `link <url>`. A style that sets nothing
    /// is `"none"` — never the empty string, which upstream reserves for "no
    /// style at all".
    pub fn definition(&self) -> String {
        let mut parts: Vec<String> = Vec::new();
        for (index, name) in ATTR_NAMES.iter().enumerate() {
            match self.attrs[index] {
                Some(true) => parts.push((*name).to_string()),
                Some(false) => parts.push(format!("not {name}")),
                None => {}
            }
        }
        if let Some(color) = &self.color {
            parts.push(color.name.to_string());
        }
        if let Some(bgcolor) = &self.bgcolor {
            parts.push("on".to_string());
            parts.push(bgcolor.name.to_string());
        }
        if let Some(link) = self.link.as_ref().filter(|link| !link.is_empty()) {
            parts.push("link".to_string());
            parts.push(link.clone());
        }
        if parts.is_empty() {
            "none".to_string()
        } else {
            parts.join(" ")
        }
    }

    /// Canonicalise a style definition so that definitions with the same effect
    /// have the same string. Port of `Style.normalize`.
    ///
    /// A definition that parses round-trips through [`definition`](Self::definition),
    /// so `"b"` and `"BOLD"` both become `"bold"`. One that does not parse is
    /// merely trimmed and lowercased — that is the path a *theme name* like
    /// `"repr.number"` takes, and it is why theme lookups are effectively
    /// case-insensitive on the markup side while [`Theme::get_style`] itself is
    /// case-sensitive.
    ///
    /// [`Theme::get_style`]: crate::theme::Theme::get_style
    pub fn normalize(definition: &str) -> String {
        // Upstream memoises this with `@lru_cache(maxsize=1024)`; markup
        // normalises every tag it opens or closes, so the cache keeps a
        // frame of markup from parsing the same few names again
        // (docs/PORTING.md, "Performance notes").
        type Cache = std::collections::HashMap<
            String,
            String,
            std::hash::BuildHasherDefault<crate::style::ShortKeyHasher>,
        >;
        thread_local! {
            static CACHE: std::cell::RefCell<Cache> = std::cell::RefCell::new(Cache::default());
        }
        if let Some(hit) = CACHE.with(|cache| cache.borrow().get(definition).cloned()) {
            return hit;
        }
        let normalized = Style::normalize_uncached(definition);
        CACHE.with(|cache| {
            let mut cache = cache.borrow_mut();
            if cache.len() >= 1024 {
                cache.clear();
            }
            cache.insert(definition.to_string(), normalized.clone());
        });
        normalized
    }

    /// [`normalize`](Self::normalize) without the cache: the port of the
    /// function upstream's cache wraps.
    fn normalize_uncached(definition: &str) -> String {
        match Style::parse(definition) {
            Ok(style) => style.definition(),
            Err(_) => definition.trim().to_lowercase(),
        }
    }

    /// Parse a style definition such as `"bold red on blue"`.
    ///
    /// Port of `Style.parse` covering attributes, `not <attr>`, `link <url>`, and
    /// `<color> on <color>`. (`meta` is deferred — see DIVERGENCES.)
    pub fn parse(definition: &str) -> Result<Self> {
        // Port of upstream's leading guard:
        //     if style_definition.strip() == "none" or not style_definition
        // `none` is only valid as the WHOLE definition — upstream raises on
        // `"bold none"`, because inside the word loop `none` is treated as a
        // colour name and fails to parse. Many `DEFAULT_STYLES` entries are
        // exactly `"none"`, so without this they would all be dropped.
        if definition.is_empty() || definition.trim() == "none" {
            return Ok(Style::new());
        }
        let mut style = Style::new();
        let mut words = definition.split_whitespace();
        while let Some(raw) = words.next() {
            let word = raw.to_lowercase();
            match word.as_str() {
                "on" => {
                    let color_word = words.next().ok_or_else(|| {
                        RichError::StyleSyntax("color expected after 'on'".to_string())
                    })?;
                    style.bgcolor = Some(Color::parse(color_word).map_err(|error| {
                        RichError::StyleSyntax(format!(
                            "unable to parse {} as background color; {}",
                            crate::markup::py_repr_str(color_word),
                            error.message()
                        ))
                    })?);
                }
                "not" => {
                    let attr_word = words.next().unwrap_or("");
                    // Deliberately NOT lowercased: upstream folds case only on
                    // the loop word, and looks the `not` operand up verbatim —
                    // so `"not BOLD"` is a syntax error there, and must be here.
                    let idx = attribute_index(attr_word).ok_or_else(|| {
                        RichError::StyleSyntax(format!(
                            "expected style attribute after 'not', found {}",
                            crate::markup::py_repr_str(attr_word)
                        ))
                    })?;
                    style.attrs[idx] = Some(false);
                }
                "link" => {
                    // A bare `link` is a syntax error upstream, not an empty
                    // link — accepting it would emit a hyperlink to nowhere.
                    let url = words.next().filter(|url| !url.is_empty()).ok_or_else(|| {
                        RichError::StyleSyntax("URL expected after 'link'".to_string())
                    })?;
                    style.link = Some(url.to_string());
                }
                _ => {
                    if let Some(idx) = attribute_index(&word) {
                        style.attrs[idx] = Some(true);
                    } else {
                        style.color = Some(Color::parse(&word).map_err(|error| {
                            RichError::StyleSyntax(format!(
                                "unable to parse {} as color; {}",
                                crate::markup::py_repr_str(&word),
                                error.message()
                            ))
                        })?);
                    }
                }
            }
        }
        Ok(style)
    }

    /// Combine two styles, `other` winning wherever it sets a value.
    ///
    /// Port of `Style.__add__`.
    pub fn combine(&self, other: &Style) -> Style {
        // `_add`: a null style on either side leaves the other as it is.
        if other.is_null() {
            return self.clone();
        }
        if self.is_null() {
            return other.clone();
        }
        let mut attrs = self.attrs;
        for (slot, over) in attrs.iter_mut().zip(other.attrs.iter()) {
            if over.is_some() {
                *slot = *over;
            }
        }
        Style {
            color: other.color.clone().or_else(|| self.color.clone()),
            bgcolor: other.bgcolor.clone().or_else(|| self.bgcolor.clone()),
            attrs,
            // `style._link or self._link`: an empty link does not win.
            link: other
                .link
                .clone()
                .filter(|link| !link.is_empty())
                .or_else(|| self.link.clone()),
            // `if self._meta and style._meta: {**self.meta, **style.meta}`,
            // else `style._meta or self._meta`.
            meta: match (&self.meta, &other.meta) {
                (Some(mine), Some(theirs)) => {
                    let mut merged = mine.clone();
                    merged.update(theirs);
                    Some(merged)
                }
                (mine, theirs) => theirs.clone().or_else(|| mine.clone()),
            },
        }
    }

    /// The SGR parameter list (e.g. `"1;31;44"`) for a given color system.
    ///
    /// Port of `Style._make_ansi_codes`.
    pub fn ansi_codes(&self, system: ColorSystem) -> String {
        let mut sgr: Vec<String> = Vec::new();
        for (idx, attr) in self.attrs.iter().enumerate() {
            if *attr == Some(true) {
                sgr.push(ATTR_SGR[idx].to_string());
            }
        }
        if let Some(color) = &self.color {
            sgr.extend(color.downgrade(system).ansi_codes(true));
        }
        if let Some(bgcolor) = &self.bgcolor {
            sgr.extend(bgcolor.downgrade(system).ansi_codes(false));
        }
        sgr.join(";")
    }

    /// The CSS declarations for this style under `theme` (for HTML export).
    /// Port of `Style.get_html_style`.
    pub fn get_html_style(&self, theme: &crate::terminal_theme::TerminalTheme) -> String {
        use crate::terminal_theme::blend_rgb;
        let mut css: Vec<String> = Vec::new();

        let mut color = self.color.clone();
        let mut bgcolor = self.bgcolor.clone();
        // reverse (attr index 6): swap fore/background.
        if self.attrs[6] == Some(true) {
            std::mem::swap(&mut color, &mut bgcolor);
        }
        // dim (attr index 1): blend the foreground halfway to the background.
        if self.attrs[1] == Some(true) {
            let fg = match &color {
                Some(c) => theme.resolve(c, true),
                None => theme.foreground,
            };
            let blended = blend_rgb(fg, theme.background, 0.5);
            color = Some(Color::from_rgb(blended.red, blended.green, blended.blue));
        }

        if let Some(c) = &color {
            let hex = theme.resolve(c, true).hex();
            css.push(format!("color: {hex}"));
            css.push(format!("text-decoration-color: {hex}"));
        }
        if let Some(c) = &bgcolor {
            let hex = theme.resolve(c, false).hex();
            css.push(format!("background-color: {hex}"));
        }
        if self.attrs[0] == Some(true) {
            css.push("font-weight: bold".to_string());
        }
        if self.attrs[2] == Some(true) {
            css.push("font-style: italic".to_string());
        }
        if self.attrs[3] == Some(true) {
            css.push("text-decoration: underline".to_string());
        }
        if self.attrs[8] == Some(true) {
            css.push("text-decoration: line-through".to_string());
        }
        if self.attrs[12] == Some(true) {
            css.push("text-decoration: overline".to_string());
        }
        css.join("; ")
    }

    /// The SVG `<text>` CSS declarations for this style under `theme`. Port of
    /// the `get_svg_style` closure in `Console.export_svg`. Unlike
    /// [`get_html_style`](Self::get_html_style), the colour is always resolved to
    /// a concrete triplet (the theme fore/background stands in for a missing or
    /// default colour), `dim` blends 40% toward the background (not 50%), and the
    /// rules are joined with a bare `;`.
    pub fn get_svg_style(&self, theme: &crate::terminal_theme::TerminalTheme) -> String {
        use crate::terminal_theme::blend_rgb;
        // Resolve fore/background to concrete triplets (theme defaults fill in for
        // a None/default colour, exactly as `theme.resolve` does for `Default`).
        let mut color = self
            .color
            .as_ref()
            .map_or(theme.foreground, |c| theme.resolve(c, true));
        let mut bgcolor = self
            .bgcolor
            .as_ref()
            .map_or(theme.background, |c| theme.resolve(c, false));
        if self.attrs[6] == Some(true) {
            std::mem::swap(&mut color, &mut bgcolor);
        }
        if self.attrs[1] == Some(true) {
            color = blend_rgb(color, bgcolor, 0.4);
        }
        let mut rules = vec![format!("fill: {}", color.hex())];
        if self.attrs[0] == Some(true) {
            rules.push("font-weight: bold".to_string());
        }
        if self.attrs[2] == Some(true) {
            rules.push("font-style: italic;".to_string());
        }
        if self.attrs[3] == Some(true) {
            rules.push("text-decoration: underline;".to_string());
        }
        if self.attrs[8] == Some(true) {
            rules.push("text-decoration: line-through;".to_string());
        }
        rules.join(";")
    }

    /// Wrap `text` in this style's escape sequence for `system`.
    ///
    /// With `system == None` (no color) or a null style, `text` is returned
    /// unchanged. A [`link`](Self::with_link) additionally wraps the result in an
    /// OSC 8 hyperlink. Port of `Style.render`.
    ///
    /// **Divergence:** upstream tags each hyperlink with a random `id=` field (to
    /// group multi-segment links for hover); we omit it so output is
    /// deterministic. See docs/DIVERGENCES.md.
    pub fn render(&self, text: &str, system: Option<ColorSystem>) -> String {
        let Some(system) = system else {
            return text.to_string();
        };
        if text.is_empty() {
            return text.to_string();
        }
        let codes = self.ansi_codes(system);
        let rendered = if codes.is_empty() {
            text.to_string()
        } else {
            format!("\x1b[{codes}m{text}\x1b[0m")
        };
        match &self.link {
            Some(url) => format!("\x1b]8;;{url}\x1b\\{rendered}\x1b]8;;\x1b\\"),
            None => rendered,
        }
    }
}

/// A stack of styles, each combined with the one below it. Port of
/// `rich.style.StyleStack`.
#[derive(Debug, Clone)]
pub struct StyleStack {
    stack: Vec<Style>,
}

impl StyleStack {
    /// A stack holding `default_style`.
    pub fn new(default_style: Style) -> Self {
        StyleStack {
            stack: vec![default_style],
        }
    }

    /// The style at the top of the stack. Port of `StyleStack.current`.
    pub fn current(&self) -> &Style {
        self.stack
            .last()
            .expect("the stack keeps its default style")
    }

    /// Push `style` combined with the current one. Port of `StyleStack.push`.
    pub fn push(&mut self, style: &Style) {
        let combined = self.current().combine(style);
        self.stack.push(combined);
    }

    /// Pop the top style and return the new current one. Port of
    /// `StyleStack.pop`; popping the default style is an error (upstream
    /// raises `IndexError` on the next access).
    pub fn pop(&mut self) -> Result<&Style> {
        if self.stack.len() == 1 {
            return Err(RichError::StyleStack(
                "pop from empty style stack".to_string(),
            ));
        }
        self.stack.pop();
        Ok(self.current())
    }
}

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

    /// The cached `normalize` answers what the uncached one does, on a miss
    /// and on a hit, for definitions that parse and ones that do not.
    #[test]
    fn normalize_cache_is_transparent() {
        let definitions = [
            "b",
            "BOLD",
            " bold red on blue ",
            "repr.number",
            "Repr.Number ",
            "not bold",
            "not BOLD",
            "link https://x.io",
            "#ff0000",
            "rgb(1,2,3)",
            "",
            "none",
            "bold none",
            "on",
            "color(300)",
            "@click",
            "b i u",
            "u2",
        ];
        for _ in 0..2 {
            for definition in definitions {
                assert_eq!(
                    Style::normalize(definition),
                    Style::normalize_uncached(definition),
                    "{definition:?}"
                );
            }
        }
        // Past the cache's size it starts again, still answering the same.
        for n in 0..1100 {
            let definition = format!("tag{n}");
            assert_eq!(Style::normalize(&definition), definition);
        }
        assert_eq!(Style::normalize("B"), "bold");
    }

    /// Expectations captured from real rich 15.0.0.
    #[test]
    fn meta_matches_upstream() {
        let meta = |entries: &[(&str, MetaValue)]| -> Meta { entries.iter().cloned().collect() };
        let a = Style::parse("bold")
            .unwrap()
            .with_meta(meta(&[("x", MetaValue::Int(1)), ("y", MetaValue::Int(2))]));
        let b = Style::new().with_meta(meta(&[("y", MetaValue::Int(3)), ("z", MetaValue::Int(4))]));
        // `{'x': 1, 'y': 3, 'z': 4}`
        assert_eq!(
            a.combine(&b).meta(),
            meta(&[
                ("x", MetaValue::Int(1)),
                ("y", MetaValue::Int(3)),
                ("z", MetaValue::Int(4))
            ])
        );
        assert!(Style::new().with_meta(Meta::new()).is_null());
        assert!(Style::from_meta(Meta::new()).is_null());
        let ab = meta(&[("a", MetaValue::Int(1)), ("b", MetaValue::Int(2))]);
        let ba = meta(&[("b", MetaValue::Int(2)), ("a", MetaValue::Int(1))]);
        assert_ne!(Style::new().with_meta(ab), Style::new().with_meta(ba));
        assert_ne!(
            Style::new().with_meta(meta(&[("a", MetaValue::Bool(true))])),
            Style::new().with_meta(meta(&[("a", MetaValue::Int(1))]))
        );
        assert_eq!(
            Style::on(
                Some(meta(&[("k", MetaValue::Int(1))])),
                &[("click", MetaValue::Str("go".into()))]
            )
            .meta(),
            meta(&[
                ("k", MetaValue::Int(1)),
                ("@click", MetaValue::Str("go".into()))
            ])
        );
        let rich = Style::parse("bold link x")
            .unwrap()
            .with_meta(meta(&[("a", MetaValue::Int(1))]));
        assert_eq!(rich.definition(), "bold link x");
        assert_eq!(rich.clear_meta_and_links(), Style::parse("bold").unwrap());
        // Meta never renders.
        assert_eq!(
            rich.ansi_codes(ColorSystem::Truecolor),
            Style::parse("bold")
                .unwrap()
                .ansi_codes(ColorSystem::Truecolor)
        );
    }

    /// `normalize` round-trips a parseable definition through `definition()` and
    /// merely trims+lowercases one that isn't. Every expectation here was taken
    /// from real rich 15.0.0's `Style.normalize`.
    #[test]
    fn normalize_matches_upstream() {
        for (input, expected) in [
            ("b", "bold"),
            ("bold", "bold"),
            ("BOLD", "bold"),
            ("  Bold  ", "bold"),
            ("dim i", "dim italic"),
            ("not bold", "not bold"),
            ("bold red", "bold red"),
            ("red on blue", "red on blue"),
            ("link https://x", "link https://x"),
            // Not a style definition, so it falls through to trim+lowercase —
            // this is the path every theme name takes.
            ("nope", "nope"),
            ("REPR.Number", "repr.number"),
            // `not` is case-sensitive upstream, so this fails to parse and takes
            // the fallback, which happens to produce the same string.
            ("not BOLD", "not bold"),
        ] {
            assert_eq!(Style::normalize(input), expected, "normalize({input:?})");
        }
    }

    /// A style that sets nothing renders as `"none"`, never as an empty string.
    #[test]
    fn definition_of_null_style_is_none() {
        assert_eq!(Style::new().definition(), "none");
        assert_eq!(Style::parse("none").unwrap().definition(), "none");
    }

    /// `not <attr>` is case-sensitive, matching upstream, which looks the operand
    /// up without folding and raises when it misses. Accepting `not BOLD` would
    /// silently *cancel* an enclosing bold instead of being ignored.
    #[test]
    fn not_operand_is_case_sensitive() {
        assert!(Style::parse("not bold").is_ok());
        assert!(Style::parse("not BOLD").is_err());
    }

    /// `link <url>` is a style keyword, not a colour name. Without it the whole
    /// definition failed to parse and the hyperlink was silently dropped.
    #[test]
    fn parse_understands_link() {
        let style = Style::parse("link https://example.com").expect("link parses");
        assert_eq!(style.link.as_deref(), Some("https://example.com"));
        assert_eq!(style.definition(), "link https://example.com");
        // A bare `link` is a syntax error, exactly as upstream — accepting it
        // would emit a hyperlink to nowhere.
        assert!(Style::parse("link").is_err());
    }

    #[test]
    fn parse_bold_red() {
        let style = Style::parse("bold red").unwrap();
        assert_eq!(style.ansi_codes(ColorSystem::Truecolor), "1;31");
        assert_eq!(
            style.render("hello", Some(ColorSystem::Truecolor)),
            "\x1b[1;31mhello\x1b[0m"
        );
    }

    #[test]
    fn svg_style_matches_upstream() {
        // Captured from real rich 15.0.0 `export_svg`'s `get_svg_style` under
        // `SVG_EXPORT_THEME`. Note: bgcolor is excluded from the fill style,
        // `reverse` swaps to the background, and dim blends 40% toward it.
        use crate::terminal_theme::SVG_EXPORT_THEME as theme;
        let svg = |spec: &str| Style::parse(spec).unwrap().get_svg_style(&theme);
        assert_eq!(Style::new().get_svg_style(&theme), "fill: #c5c8c6");
        assert_eq!(svg("bold red"), "fill: #cc555a;font-weight: bold");
        assert_eq!(svg("italic green"), "fill: #98a84b;font-style: italic;");
        assert_eq!(svg("dim"), "fill: #868887");
        assert_eq!(
            svg("underline blue on yellow"),
            "fill: #608ab1;text-decoration: underline;"
        );
        assert_eq!(svg("reverse"), "fill: #292929");
    }

    #[test]
    fn link_wraps_in_osc8() {
        let style = Style::parse("underline blue")
            .unwrap()
            .with_link("https://example.com");
        assert_eq!(
            style.render("click", Some(ColorSystem::Truecolor)),
            "\x1b]8;;https://example.com\x1b\\\x1b[4;34mclick\x1b[0m\x1b]8;;\x1b\\"
        );
        // A link-only style still wraps (no SGR inside).
        let bare = Style::new().with_link("https://x.com");
        assert_eq!(
            bare.render("y", Some(ColorSystem::Truecolor)),
            "\x1b]8;;https://x.com\x1b\\y\x1b]8;;\x1b\\"
        );
        assert!(!bare.is_null());
    }

    #[test]
    fn parse_fg_on_bg() {
        let style = Style::parse("white on blue").unwrap();
        assert_eq!(style.ansi_codes(ColorSystem::Truecolor), "37;44");
    }

    #[test]
    fn combine_overrides() {
        let base = Style::parse("bold red").unwrap();
        let over = Style::parse("blue").unwrap();
        let combined = base.combine(&over);
        // bold retained from base, color replaced by blue (34)
        assert_eq!(combined.ansi_codes(ColorSystem::Truecolor), "1;34");
    }

    #[test]
    fn no_color_system_is_plaintext() {
        let style = Style::parse("bold red").unwrap();
        assert_eq!(style.render("hello", None), "hello");
    }

    #[test]
    fn null_style_does_not_wrap() {
        let style = Style::new();
        assert_eq!(style.render("hello", Some(ColorSystem::Truecolor)), "hello");
    }
}