opencrabs 0.5.11

//! Telegram-side rendering for the OPTIONAL `suggest_options` tool (#597).
//!
//! Non-blocking: the agent surfaces
//! `ProgressEvent::SuggestedOptions`, and we post an inline keyboard under the
//! finished response with one button per suggestion. Tapping a button injects
//! that suggestion as the user's next message (a fresh turn) — see the
//! `followup:` arm in the callback dispatcher. Typing your own message is always
//! available and just starts a normal turn; there is no oneshot and no timeout.

use std::sync::Arc;
use std::time::Duration;

use teloxide::payloads::{EditMessageTextSetters, SendMessageSetters};
use teloxide::types::{
    ChatId, InlineKeyboardButton, InlineKeyboardMarkup, MessageId, ParseMode, ThreadId,
};
use uuid::Uuid;

use super::TelegramState;

/// Callback-data prefix for a tapped follow-up suggestion: `followup:<session>:<idx>`.
pub(crate) const FOLLOWUP_PREFIX: &str = "followup:";

/// Body for the standalone fallback bubble (#1226 item 4). Prose mode keeps
/// just the folded list (it has no buttons, nothing can expire); button
/// modes carry the bare lamp plus an expiry marker — this fallback fires
/// when the merge lost a rate-limit race, so the bubble is subject to the
/// stale-shell lifecycle and operators kept reading dead fallbacks as
/// fresh, answerable questions (msgs 30997 / 31010: one was tapped 32
/// minutes after its choices were consumed).
pub(crate) fn standalone_fallback_body(layout: &SuggestLayout, options: &[String]) -> String {
    if *layout == SuggestLayout::NumberedProse {
        // #119 fold tier: the Go lines carry the questions; nothing else
        // needed — no lamp, no list.
        go_tier_lines_rich(options)
    } else {
        String::from("\u{1f4a1} <i>(choices may have expired)</i>")
    }
}

/// What the suggestion block becomes once one of its options is tapped.
///
/// Replaces the prompt and its keyboard in place. The Bot API has no
/// send-as-user, so posting the choice as a new message renders a
/// user-chosen continuation under the bot's name, avatar and badge. A `>`
/// quote does not change that: the bubble is still labelled as the bot
/// (#844). Editing the block reads as a selected control instead.
pub(crate) fn picked_block(text: &str, chooser: Option<&str>) -> String {
    match chooser {
        // Name the member who chose it (#893). Without this the record reads as
        // an anonymous line from the bot, which in a group says nothing about
        // who acted. The Bot API cannot post AS a user, but the callback query
        // carries the tapper's identity and it was simply discarded.
        Some(name) if !name.trim().is_empty() => {
            format!("\u{25b6}\u{fe0f} {} \u{2014} {text}", name.trim())
        }
        _ => format!("\u{25b6}\u{fe0f} {text}"),
    }
}

/// Last-resort record when the suggestion block cannot be edited, because it
/// is too old or no longer accessible. Worse attribution than editing, but
/// losing the record of what was chosen is worse still.
pub(crate) fn echo_fallback(text: &str, chooser: Option<&str>) -> String {
    match chooser {
        Some(name) if !name.trim().is_empty() => {
            format!("> \u{25b6}\u{fe0f} {} \u{2014} {text}", name.trim())
        }
        _ => format!("> \u{25b6}\u{fe0f} {text}"),
    }
}

/// What a tapped suggestion block is rewritten into (#39).
///
/// The pick record is baked into the body BEFORE any transport arm runs,
/// so no arm can drop it: a merged host — rich or classic — keeps its
/// answer HTML and gains the pick record; a standalone block becomes the
/// pick record. Before this shape the append lived inside the rich arm
/// only, and the classic merged host silently lost the choice (owner
/// report 2026-08-29 23:51Z).
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) enum PickRewrite {
    /// Rich merged host: body rides `edit_rich_html`, empty markup strips
    /// the dead buttons.
    RichHost(String),
    /// Markdown-plane merged host (#79 piece 4): body rides
    /// `edit_rich_markdown` — the server render keeps tables intact
    /// (#679); empty markup strips the dead buttons.
    RichMarkdownHost(String),
    /// Classic merged host: body rides `edit_message_text` + empty markup
    /// to strip the dead buttons.
    ClassicHost(String),
    /// Standalone suggestion block: body rides plain `edit_message_text`.
    Standalone(String),
}

/// The single construction site for a post-tap body (#39).
///
/// `host` is `(html, rich)` of the merged host bubble when the tapped
/// message IS it; merged host → answer HTML + pick record, standalone →
/// pick record alone.
pub(crate) fn pick_rewrite(
    host: Option<(&str, bool, Option<&str>)>,
    picked_html: &str,
    picked_md: &str,
    picked_idx: usize,
) -> PickRewrite {
    match host {
        Some((full, rich, markdown)) => {
            if rich {
                // #67 tap-redraw: the rows must not survive as live
                // controls — they are rewritten to the picked state
                // (success+✓+disabled / disabled) instead of stripped, so
                // the bubble keeps showing what was chosen. `mark_picked_button`
                // is a byte-level `<tg-button` scan, plane-agnostic — the
                // same rewrite serves the html and markdown planes.
                //
                // #96: each plane must redraw in ITS OWN plane. The md-plane
                // host's `markdown` column carries the `<tg-button>` rows as
                // raw widget markup (the only html the rich-markdown renderer
                // accepts); rewriting the `full` HTML strip-source instead
                // posts `<p>`/`<b>` tags into the markdown field — Telegram
                // renders them literally (tag soup). Markdown hosts get
                // `mark_picked_button(markdown)` + the pick line as plain
                // markdown; html hosts keep the html rewrite.
                if let Some(md) = markdown {
                    PickRewrite::RichMarkdownHost(format!(
                        "{}\n\n{picked_md}",
                        mark_picked_button(md, picked_idx)
                    ))
                } else {
                    PickRewrite::RichHost(format!(
                        "{}\n\n{picked_html}",
                        mark_picked_button(full, picked_idx)
                    ))
                }
            } else {
                // Classic hosts keep their buttons as reply markup (not in
                // the body) — the empty-markup arm strips those; nothing to
                // rewrite here.
                PickRewrite::ClassicHost(format!("{full}\n\n{picked_html}"))
            }
        }
        None => PickRewrite::Standalone(picked_html.to_string()),
    }
}

/// #67 tap-redraw: rewrite the follow-up button rows of a rich merged host
/// to the post-tap state. The tapped button flips to success style, gains a
/// ✓ and `disabled`; every sibling follow-up button loses its style (bare
/// `disabled` is the only reliably grayed form — #71) and gains `disabled`.
/// Non-follow-up markup passes through byte-identical.
pub(crate) fn mark_picked_button(html: &str, picked_idx: usize) -> String {
    let mut out = String::with_capacity(html.len() + 64);
    let mut rest = html;
    while let Some(tag_start) = rest.find("<tg-button") {
        let after_open = &rest[tag_start + "<tg-button".len()..];
        // `<tg-button-row>` and any other `<tg-button…` lookalike that is
        // not the button tag itself passes through untouched.
        if !after_open.starts_with('>') && !after_open.starts_with(' ') {
            out.push_str(&rest[..tag_start + "<tg-button".len()]);
            rest = after_open;
            continue;
        }
        let Some(attrs_rel) = after_open.find('>') else {
            // Unterminated tag: emit the remainder verbatim.
            out.push_str(rest);
            return out;
        };
        let tag_open_len = "<tg-button".len();
        let attrs = &after_open[..attrs_rel];
        let after_attrs = &after_open[attrs_rel + 1..];
        let body_rel = attrs_rel + 1;
        let Some(label_rel) = after_attrs.find("</tg-button>") else {
            // Unterminated label: emit through the tag opener verbatim.
            out.push_str(&rest[..tag_start + tag_open_len + body_rel]);
            rest = after_attrs;
            continue;
        };
        let label = &after_attrs[..label_rel];
        let tail = &after_attrs[label_rel + "</tg-button>".len()..];
        let idx = attrs
            .split("data=\"followup:")
            .nth(1)
            .and_then(|v| v.split('"').next())
            .and_then(|v| v.rsplit(':').next())
            .and_then(|v| v.parse::<usize>().ok());
        let picked = idx == Some(picked_idx);
        if picked || idx.is_some() {
            let mut new_attrs = attrs.to_string();
            if picked {
                // The picked button flips to success regardless of its
                // original style.
                if let Some(s) = new_attrs.find("style=\"")
                    && let Some(e) = new_attrs[s + "style=\"".len()..].find('"')
                {
                    let style_end = s + "style=\"".len() + e;
                    new_attrs.replace_range(s + "style=\"".len()..style_end, "success");
                } else {
                    new_attrs.push_str(" style=\"success\"");
                }
            } else {
                // #71: a styled button still renders enabled-looking even
                // with `disabled` (owner A/B: `style="primary" disabled`
                // stays blue), so siblings drop their style attribute —
                // bare `disabled` is the only form that renders grayed.
                if let Some(s) = new_attrs.find(" style=\"")
                    && let Some(e) = new_attrs[s + " style=\"".len()..].find('"')
                {
                    let style_end = s + " style=\"".len() + e + 1;
                    new_attrs.replace_range(s..style_end, "");
                }
            }
            // Bot API 10.3 spec: disabled button requires type="disabled",
            // not the boolean attribute `disabled`!
            // Strip data="..." payload and replace type="..." with type="disabled".
            if let Some(s) = new_attrs.find("data=\"")
                && let Some(e) = new_attrs[s + "data=\"".len()..].find('"')
            {
                let data_end = s + "data=\"".len() + e + 1;
                // If there's a leading space, include it
                let strip_start = if s > 0 && new_attrs.as_bytes()[s - 1] == b' ' {
                    s - 1
                } else {
                    s
                };
                new_attrs.replace_range(strip_start..data_end, "");
            }
            if let Some(s) = new_attrs.find("type=\"")
                && let Some(e) = new_attrs[s + "type=\"".len()..].find('"')
            {
                let type_end = s + "type=\"".len() + e;
                new_attrs.replace_range(s + "type=\"".len()..type_end, "disabled");
            } else {
                new_attrs.push_str(" type=\"disabled\"");
            }
            // Backward compatibility for any parser expecting `disabled` token
            if !new_attrs.contains("disabled") {
                new_attrs.push_str(" disabled");
            }
            out.push_str(&rest[..tag_start]);
            out.push_str("<tg-button");
            out.push_str(&new_attrs);
            out.push('>');
            if picked {
                out.push_str("\u{2713} ");
            }
            out.push_str(label);
            out.push_str("</tg-button>");
        } else {
            // Not a follow-up button: emit the whole span verbatim.
            out.push_str(&rest[..tag_start + tag_open_len + body_rel + label_rel]);
            out.push_str("</tg-button>");
        }
        rest = tail;
    }
    out.push_str(rest);
    out
}

/// Button-width calibration, measured 2026-08-25 on Alexey's client
/// Fold threshold: a label wider than this never rides a button — the
/// whole set folds to [`SuggestLayout::NumberedProse`]. Recalibrated
/// 2026-09-04 (fork issue #79 owner smokes): the old 50-char gate shipped
/// clipped Cyrillic — measured cuts at 40-44 chars rich-plane, 32
/// wide-glyph native-plane, and a byte-identical label flipped clean/cut
/// across reads, so no char-count cap is provably safe at any precision.
/// The constant is conservative by design: 20 sits below every cut
/// datapoint observed on any plane. Units are worst-case (wide-glyph)
/// display width; plain `chars().count()` overcounts slim-glyph labels,
/// which errs safe.
pub(crate) const BUTTON_LABEL_MAX_UNITS: usize = 20;
/// Full-width clip point for a SINGLE-option button (#119). One button on
/// its own row carries more than a shared-row label — the old pre-#79
/// 50-char budget rode this shape — but not unlimited: cuts were measured
/// at 32 (wide-glyph native) and 40-44 (rich-plane), so 30 keeps a margin
/// under every datapoint while clearing the 27-char live-smoke label the
/// 20-unit shared-row gate wrongly folded. One label is also the only
/// place the owner reads the full text against a single control — the
/// fold tier's cramming premise never applies at n=1.
pub(crate) const SINGLE_BUTTON_MAX_UNITS: usize = 30;
/// Total width one row of buttons may carry before the set folds (issue
/// #79: 3x12=36 shared-row cut, 4x12=43 cut; only a 24 slim-tail pair
/// held — same conservative-by-design rule as [`BUTTON_LABEL_MAX_UNITS`]).
pub(crate) const SHARED_ROW_TOTAL_UNITS: usize = 20;
/// Longest label allowed to share one row with its siblings. Recalibrated
/// 2026-08-31 (live probes, fork issue #49): the real constraint is
/// ROW-TOTAL width (~32 chars shared equally across the row, before the
/// body-width-dependent truncation Alexey observed), not per-label chars —
/// 4×8=32 held, 15+18=33 clipped ~2 symbols, and bubble width varies with
/// the message body, so 12 keeps a safety margin under the worst bubble
/// while doubling information per row vs the old 8.
pub(crate) const SHARED_ROW_MAX_CHARS: usize = 12;
/// Tap ergonomics (Alexey, 2026-08-25): #119 Go! buttons never pack more
/// than 4 per row, so every target stays big enough for a finger.
pub(crate) const MAX_NUMBERS_PER_ROW: usize = 4;

/// Which shape the suggestion controls take for a given option list.
/// Tiers are measured, not guessed — see [`BUTTON_LABEL_MAX_UNITS`].
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub(crate) enum SuggestLayout {
    /// Every label short AND few options: all buttons share ONE row.
    SharedRow,
    /// Every label fits a full-width button: one button per row.
    Column,
    /// Some label too long even full-width (#119 owner design): the fold
    /// tier splits by set size (owner order 2026-09-09): n=1 = one bold
    /// `Go: <label>?` body line + one `Go!` button; n>=2 = the plain
    /// numbered list `1. <label>` body + buttons labelled `N. <FirstWord>`
    /// (owner order 2026-09-14), packed [`MAX_NUMBERS_PER_ROW`] per row.
    /// Both planes build those button labels through [`go_button_label`],
    /// so the emitter and the [`enforce_button_fit`] fold agree on the tier.
    NumberedProse,
}

/// THE budget verdict — sole authority on whether one button row ships
/// byte-identical or folds (#119 refactor, option A). Both consumers call
/// THIS: `pick_layout` at the emitter and `enforce_button_fit` at the
/// rich/api.rs funnel. Before this function, the two sites carried
/// divergent copies of the budgets — the funnel re-folded full-width
/// single-button rows the emitter had just approved, which is exactly
/// the live #119 regression. One verdict = the divergence class is
/// structurally impossible.
///
/// Row shapes:
/// - ONE button renders FULL-WIDTH, so it gets the solo budget
///   [`SINGLE_BUTTON_MAX_UNITS`] (30) — sized below every measured cut
///   datapoint (32 wide-glyph native, 40-44 rich-plane — see #79) while
///   clearing confirm-style labels (27 units) that the 20-unit shared
///   gate wrongly folded.
/// - Multi-button rows share keyboard width, so every label must fit
///   [`SHARED_ROW_MAX_CHARS`] and the row total [`SHARED_ROW_TOTAL_UNITS`].
///
/// Width is the character count of the label's DISPLAY text: callers decode
/// entities first, so the emitter and the funnel measure the same unit.
/// Measuring the escaped form instead overcounts by up to 4 units per `&`
/// — and that is NOT "safe": it rejected a row the emitter had already
/// approved, folding a 30-unit label that read as 34 (#396).
pub(crate) fn row_fits(labels: &[&str]) -> bool {
    if labels.len() == 1 {
        labels[0].chars().count() <= SINGLE_BUTTON_MAX_UNITS
    } else {
        let total: usize = labels.iter().map(|l| l.chars().count()).sum();
        labels
            .iter()
            .all(|l| l.chars().count() <= SHARED_ROW_MAX_CHARS)
            && total <= SHARED_ROW_TOTAL_UNITS
    }
}

pub(crate) fn pick_layout(options: &[String]) -> SuggestLayout {
    let width = |o: &String| o.chars().count();
    let refs: Vec<&str> = options.iter().map(|o| o.as_str()).collect();
    if options.len() > 1 && options.len() <= MAX_NUMBERS_PER_ROW && row_fits(&refs) {
        SuggestLayout::SharedRow
    } else if options.iter().all(|o| width(o) <= BUTTON_LABEL_MAX_UNITS)
        || (options.len() == 1 && width(&options[0]) <= SINGLE_BUTTON_MAX_UNITS)
    {
        // n=1 with a label past the shared 20-unit cap still rides
        // full-width up to the solo budget (#119) — row_fits's solo arm.
        SuggestLayout::Column
    } else {
        SuggestLayout::NumberedProse
    }
}

/// The folded option list as rich HTML (#119 fold tier). Set-size split
/// (owner order 2026-09-09, "back to the way the numbered lists were
/// before the Go button introduction"):
/// n=1 keeps the confirmed Go! tier — one bold `Go: <label>?` line through
/// the canonical inline primitives (`escape_html` → `format_inline`);
/// n>=2 reverts to the ORIGINAL plain numbered list (`1. <label>` — no
/// `Go:` prefix, no `?` mutation, no bold), byte-identical semantics to
/// the pre-`c92873b1` `folded_list_html`. Options are independent ONE-line
/// texts, so they deliberately skip document-level interpretation (a
/// stray `|` must not turn the line into a table). No "Suggested next"
/// header — the lines ride directly under the answer text in the same
/// bubble (#tg-suggest-merge).
pub(crate) fn go_tier_lines_rich(options: &[String]) -> String {
    if options.len() == 1 {
        return options
            .iter()
            .map(|opt| {
                super::markdown::format_inline(&super::markdown::escape_html(&go_tier_line(opt)))
            })
            .collect::<Vec<_>>()
            .join("\n");
    }
    options
        .iter()
        .enumerate()
        .map(|(i, opt)| {
            format!(
                "{}. {}",
                i + 1,
                super::markdown::format_inline(&super::markdown::escape_html(opt))
            )
        })
        .collect::<Vec<_>>()
        .join("\n")
}

/// The fold-tier button label for one option — set-size split (owner
/// order 2026-09-09, updated 2026-09-14): n>=2 = `N. <FirstWord>` (e.g. `1. Deploy`, `2. Skip`),
/// pairing with the restored `1. <label>` body lines while giving each button immediate context;
/// n=1 = the single `Go!` button of the confirmed Go! tier. `number` is 1-based.
pub(crate) fn go_button_label(number: usize, label: &str, is_single: bool) -> String {
    if is_single {
        String::from("Go!")
    } else {
        let first_word = label.split_whitespace().next().unwrap_or_default();
        if first_word.is_empty() {
            number.to_string()
        } else {
            format!("{number}. {first_word}")
        }
    }
}

/// The verb the #119 fold tier names options with — the word the numbered
/// `N. Go: <label>?` body line prefixes the label with.
const GO_TIER_VERB: &str = "Go";

/// One #119 single-option fold-tier body line (n=1 ONLY — owner design
/// 06:42Z + verb-repeat amendment 06:46Z, render corrections 2026-09-09):
/// `Go: <label>?` — label verbatim + `?` unless it already ends one
/// (`Go — implement #98…?`), `Go: <label>?` otherwise (`Go: Smoke OK —
/// ack both units?`). The label is NOT re-wrapped in markup here: the
/// rich plane escapes+formats via `go_tier_lines_rich`; the markdown
/// plane takes the raw line. For n>=2 the fold is the plain numbered
/// list (owner order 2026-09-09) — this Go! line never fires there.
pub(crate) fn go_tier_line(label: &str) -> String {
    // Verb match is whole-first-word, not a character prefix: "go fast"
    // qualifies, "Gossip about it" does not (CI r2, E-test 139).
    let first_word = label.split_whitespace().next().unwrap_or_default();
    let starts_with_verb = first_word.eq_ignore_ascii_case(GO_TIER_VERB);
    // Owner render correction 2026-09-09: a label that already ends with a
    // question mark must not get a second one; the whole line renders bold
    // (`**` survives escape_html, format_inline/native md both turn it <b>).
    let terminator = if label.ends_with('?') { "" } else { "?" };
    if starts_with_verb {
        format!("**{label}{terminator}**")
    } else {
        format!("**{GO_TIER_VERB}: {label}{terminator}**")
    }
}

/// The #119 fold-tier body block. Set-size split (owner order 2026-09-09,
/// "back to the way the numbered lists were before the Go button
/// introduction"): n=1 = one bold `go_tier_line`; n>=2 = the ORIGINAL
/// plain numbered list `1. <label>` (markdown plane) — byte-identical to
/// the pre-`c92873b1` `folded_list_markdown`. The n>=2 buttons carry
/// `N. <FirstWord>` labels ([`go_button_label`], owner order 2026-09-14)
/// whose numbers pair with these lines.
pub(crate) fn go_tier_lines(options: &[String]) -> String {
    if options.len() == 1 {
        return go_tier_line(&options[0]);
    }
    options
        .iter()
        .enumerate()
        .map(|(i, o)| format!("{}. {}", i + 1, o))
        .collect::<Vec<_>>()
        .join("\n")
}

/// host-aware stale-shell strip: the #597 clear killed the stash, but the
/// buttons keep rendering inside the body until the body is rewritten clean.
pub(crate) fn strip_button_rows(html: &str) -> String {
    let mut out = String::with_capacity(html.len());
    let mut rest = html;
    while let Some(start) = rest.find("<tg-button-row>") {
        match rest[start..].find("</tg-button-row>") {
            Some(rel) => {
                let end = start + rel + "</tg-button-row>".len();
                out.push_str(&rest[..start]);
                rest = &rest[end..];
            }
            None => break, // unterminated span: leave the remainder untouched
        }
    }
    out.push_str(rest);
    out.trim_end().to_string()
}

/// #59 (DRY): the empty reply-markup used to strip dead keyboards — one
/// construction site instead of one per strip arm.
pub(crate) fn empty_keyboard() -> teloxide::types::InlineKeyboardMarkup {
    teloxide::types::InlineKeyboardMarkup::new(
        Vec::<Vec<teloxide::types::InlineKeyboardButton>>::new(),
    )
}

/// #79 chokepoint: EVERY rich body that may carry `<tg-button-row>`
/// controls passes through here on send and edit (the `rich/api.rs`
/// funnel), so hand-authored button rows from any lane get the same
/// measured fit rule the suggestion cards enforce at their own emitter —
/// the n8n-card cut class. Row verdicts go through [`row_fits`] — the
/// single budget authority (#119 option A): one-button rows ride the
/// solo budget, shared rows the per-label + row-total caps. If every
/// row fits, the body ships byte-identical. Otherwise the whole set
/// folds to the NumberedProse shape (proven cut-free twice in #79):
/// buttons keep their attributes — callback data and URL routing are
/// untouched — but render their fold-tier label, and the original labels
/// move into an `<ol>` after the last row. Idempotent: a folded body's
/// tier labels never re-trigger the fold.
/// Enforces button width budgets across an HTML body.
///
/// Hand-authored multi-button rows exceeding the shared row budget (total >20 or
/// per-label >12 units) are re-shaped to `Column` layout (one button per row, keeping
/// original labels intact) when all labels in the contiguous button set fit the solo
/// budget (`SINGLE_BUTTON_MAX_UNITS` = 30).
///
/// If any button label in the set exceeds 30 units, the set falls back to the
/// `NumberedProse` shape (proven cut-free twice in #79): buttons keep their attributes
/// — callback data and URL routing are untouched — but render their fold-tier label,
/// and the original labels move into an `<ol>` after the last row of that set.
///
/// The fold tier is the owner's 2026-09-14 shape (#396): `N. <FirstWord>` for n>=2,
/// `Go!` for a single-button set — the same tier the emitter's NumberedProse arm
/// writes, so the two arms agree. The pre-#396 fold wrote a bare index, which told
/// the owner nothing about what the button did. The tier label is derived from the
/// DECODED first word and re-escaped for the HTML context; when it cannot fit the
/// solo budget on its own (a first word of 28+ units), the button falls back to the
/// bare index, which always fits — without that guard a folded body would re-trigger
/// the fold on the next pass.
///
/// Every verdict below measures the label's DISPLAY width, not its escaped form —
/// see [`row_fits`] for why the escaped form is the wrong unit (#396).
///
/// Contiguous runs of `<tg-button-row>` blocks (separated only by whitespace) form
/// a single logical set; intervening non-whitespace text delineates independent sets.
///
/// Idempotent: a re-shaped or folded body never re-triggers transformation.
pub(crate) fn enforce_button_fit(html: &str) -> String {
    const ROW_OPEN: &str = "<tg-button-row>";
    const ROW_CLOSE: &str = "</tg-button-row>";
    const BTN_OPEN: &str = "<tg-button";
    const BTN_CLOSE: &str = "</tg-button>";

    struct EnforcerButton<'a> {
        open_tag: &'a str,
        label: &'a str,
    }

    struct EnforcerRow<'a> {
        row_start: usize,
        row_end: usize,
        buttons: Vec<EnforcerButton<'a>>,
    }

    struct EnforcerSet<'a> {
        rows: Vec<EnforcerRow<'a>>,
        set_start: usize,
        set_end: usize,
    }

    // Pass 1 — collect row spans and parsed buttons.
    let mut rows: Vec<EnforcerRow<'_>> = Vec::new();
    let mut scan_from = 0usize;
    while let Some(rel) = html[scan_from..].find(ROW_OPEN) {
        let row_start = scan_from + rel;
        let Some(crel) = html[row_start..].find(ROW_CLOSE) else {
            break; // unterminated row: leave the remainder untouched
        };
        let row_end = row_start + crel + ROW_CLOSE.len();
        let block = &html[row_start + ROW_OPEN.len()..row_end - ROW_CLOSE.len()];
        let mut buttons: Vec<EnforcerButton<'_>> = Vec::new();
        let mut bscan = 0usize;
        while let Some(brel) = block[bscan..].find(BTN_OPEN) {
            let bstart = bscan + brel;
            // Skip a prefix hit like `<tg-button-row>` itself.
            let after = &block[bstart + BTN_OPEN.len()..];
            if !after.starts_with(' ') && !after.starts_with('>') {
                bscan = bstart + BTN_OPEN.len();
                continue;
            }
            let Some(orel) = after.find('>') else {
                break;
            };
            let open_tag = &block[bstart..bstart + BTN_OPEN.len() + orel];
            let label_start = bstart + BTN_OPEN.len() + orel + 1;
            let Some(lrel) = block[label_start..].find(BTN_CLOSE) else {
                break;
            };
            let label = &block[label_start..label_start + lrel];
            buttons.push(EnforcerButton { open_tag, label });
            bscan = label_start + lrel + BTN_CLOSE.len();
        }
        rows.push(EnforcerRow {
            row_start,
            row_end,
            buttons,
        });
        scan_from = row_end;
    }

    if rows.is_empty() {
        return html.to_string();
    }

    // Pass 2 — partition rows into contiguous sets.
    // Runs of `<tg-button-row>` blocks with only whitespace between them form one set.
    // Intervening non-whitespace text delineates independent sets.
    let mut sets: Vec<EnforcerSet<'_>> = Vec::new();
    for row in rows {
        if let Some(current_set) = sets.last_mut() {
            let inter = &html[current_set.set_end..row.row_start];
            if inter.trim().is_empty() {
                current_set.set_end = row.row_end;
                current_set.rows.push(row);
                continue;
            }
        }
        sets.push(EnforcerSet {
            set_start: row.row_start,
            set_end: row.row_end,
            rows: vec![row],
        });
    }

    // Every verdict below must measure DISPLAY width — the same unit
    // `pick_layout` measured when it approved the layout. Labels are sliced
    // raw out of the HTML, so they still carry the entities `escape_html`
    // wrote, and one `&` alone inflates a label by 4 characters (`&amp;`).
    // Measuring the escaped form therefore rejects rows that fit their
    // budget: #396 folded an approved 30-unit label because it read as 34.
    // One helper keeps all three feeders in lockstep.
    let display_fits = |buttons: &[EnforcerButton<'_>]| -> bool {
        let decoded: Vec<String> = buttons
            .iter()
            .map(|b| super::markdown::unescape_html(b.label))
            .collect();
        let refs: Vec<&str> = decoded.iter().map(|s| s.as_str()).collect();
        row_fits(&refs)
    };

    // Quick check: if every row in every set satisfies row_fits as-authored, return untouched.
    let all_as_authored_fit = sets
        .iter()
        .all(|s| s.rows.iter().all(|r| display_fits(&r.buttons)));
    if all_as_authored_fit {
        return html.to_string();
    }

    // Pass 3 — assemble transformed output per set.
    let mut out = String::with_capacity(html.len() + 64);
    let mut pos = 0usize;

    for set in &sets {
        // Append text preceding this set
        out.push_str(&html[pos..set.set_start]);

        let set_fits_as_authored = set.rows.iter().all(|r| display_fits(&r.buttons));

        if set_fits_as_authored {
            out.push_str(&html[set.set_start..set.set_end]);
        } else {
            // Check if all buttons individually fit the solo Column budget (<= 30 units).
            // row_fits is THE single authority (#119 Option A, #137):
            let can_reshape_to_column = set
                .rows
                .iter()
                .flat_map(|r| &r.buttons)
                .all(|b| display_fits(std::slice::from_ref(b)));

            if can_reshape_to_column {
                // Re-shape into Column layout: one button per row, preserving original labels.
                let mut first = true;
                for row in &set.rows {
                    for btn in &row.buttons {
                        if !first {
                            out.push('\n');
                        }
                        first = false;
                        out.push_str(ROW_OPEN);
                        out.push_str(btn.open_tag);
                        out.push('>');
                        out.push_str(btn.label);
                        out.push_str(BTN_CLOSE);
                        out.push_str(ROW_CLOSE);
                    }
                }
            } else {
                // Fall back to NumberedProse fold, scoped to this set.
                // The fold button carries the SAME tier the emitter's
                // NumberedProse arm writes (owner order 2026-09-14):
                // `N. <FirstWord>` for n>=2, `Go!` for n=1. Writing a bare
                // index here left every folded button reading `1`, `2`, …
                // with no hint of what it did — the emitter had already
                // chosen the right tier and the enforcer threw it away.
                let total_buttons: usize = set.rows.iter().map(|r| r.buttons.len()).sum();
                let is_single = total_buttons == 1;
                let mut index = 0usize;
                let mut set_labels: Vec<&str> = Vec::new();
                for row in &set.rows {
                    out.push_str(ROW_OPEN);
                    for btn in &row.buttons {
                        index += 1;
                        set_labels.push(btn.label);
                        out.push_str(btn.open_tag);
                        out.push('>');
                        // The tier label derives from the DECODED text, so
                        // it must be re-escaped for the HTML context. The
                        // `<ol>` below keeps the raw (already-escaped)
                        // label — the two planes are built from different
                        // sources on purpose.
                        let decoded = super::markdown::unescape_html(btn.label);
                        let folded = super::markdown::escape_html(&go_button_label(
                            index, &decoded, is_single,
                        ));
                        // Idempotency guard: a fold label that does not fit
                        // its own budget would re-trigger the fold on the
                        // next pass, growing without bound. Only an
                        // over-long first word can reach here — 28 units at
                        // a single-digit index, 27 once the index reaches
                        // two digits (the `N. ` prefix costs digits + 2
                        // against the 30-unit solo budget). Fall to the
                        // no-first-word tier (`N. ` → bare index), which
                        // always fits.
                        if row_fits(&[folded.as_str()]) {
                            out.push_str(&folded);
                        } else {
                            out.push_str(&go_button_label(index, "", is_single));
                        }
                        out.push_str(BTN_CLOSE);
                    }
                    out.push_str(ROW_CLOSE);
                }
                out.push_str("\n<ol>");
                for label in set_labels {
                    out.push_str("<li>");
                    out.push_str(label);
                    out.push_str("</li>");
                }
                out.push_str("</ol>");
            }
        }
        pos = set.set_end;
    }
    out.push_str(&html[pos..]);
    out
}

/// #108: button rows and the trailer must start a FRESH markdown block —
/// a single leading newline lets the server parser fuse the preceding
/// paragraph into the controls block, rendering it indented. Guarantees a
/// blank-line separator regardless of whether the body already ends in
/// a newline.
fn push_blank_line(md: &mut String) {
    if !md.ends_with('\n') {
        md.push('\n');
    }
    md.push('\n');
}

/// Shared markdown-plane tail construction (#79 piece 4 + #31 + #108):
/// folded list (prose mode) + blank-line-separated in-body button rows +
/// trailer. One helper so the merge arm and the cross-turn glue arm stay
/// byte-identical in construction — and so the block-boundary property is
/// unit-testable (rows and trailer must start a FRESH markdown block; a
/// single newline fuses the preceding paragraph into the controls block and
/// the server renders it indented).
pub(crate) fn append_rows_and_trailer_md(
    md: &mut String,
    options: &[crate::brain::tools::suggest_options::SuggestionItem],
    token: &str,
    prose: bool,
    trailer: Option<&str>,
) {
    if prose {
        // Markdown plane, #119 fold tier (set-size split, owner order
        // 2026-09-09): n=1 = one bold `Go: <label>?` line; n>=2 = the
        // original plain numbered list. Raw lines: the markdown plane
        // renders them plainly, no html primitives needed. Blank line
        // before the block: owner correction 2026-09-09 — a single \n
        // glued the fold block to the body's last line (Telegram rich
        // renderer needs a paragraph break there).
        // #207 fold-list counter isolation: a preceding markdown ordered list
        // (e.g. 1..3 in prose) fuses with this fold block if separated by only
        // a blank line, causing Telegram to continue numbering (4..6) while
        // buttons show 1..3. A horizontal rule (---) breaks the list container.
        let raw_labels: Vec<String> = options.iter().map(|o| o.label.clone()).collect();
        push_blank_line(md);
        md.push_str("---\n\n");
        md.push_str(&go_tier_lines(&raw_labels));
    }
    push_blank_line(md);
    md.push_str(&suggestion_rows_rich_html(options, token));
    if let Some(t) = trailer {
        push_blank_line(md);
        md.push_str(t);
    }
}

/// The suggestion controls as native rich-button rows (Bot API 10.3
/// `<tg-button-row>`), laid out per the measured ladder. Primary style
/// throughout — picked over app-default after Alexey compared both live.
/// Callback payloads stay `followup:<session>:<idx>`, so taps route through
/// the existing callback dispatcher unchanged regardless of surface.
pub(crate) fn suggestion_rows_rich_html(
    options: &[crate::brain::tools::suggest_options::SuggestionItem],
    token: &str,
) -> String {
    use crate::brain::tools::suggest_options::SuggestionStyle;
    let btn = |i: usize, label: &str, style: SuggestionStyle| {
        let style_attr = match style {
            SuggestionStyle::Primary => " style=\"primary\"",
            SuggestionStyle::Danger => " style=\"danger\"",
            SuggestionStyle::Default => "",
        };
        format!(
            "<tg-button type=\"callback_data\" data=\"{FOLLOWUP_PREFIX}{token}:{i}\"{style_attr}>{}</tg-button>",
            super::markdown::escape_html(label)
        )
    };
    let labels: Vec<String> = options.iter().map(|o| o.label.clone()).collect();
    match pick_layout(&labels) {
        SuggestLayout::SharedRow => format!(
            "<tg-button-row>{}</tg-button-row>",
            options
                .iter()
                .enumerate()
                .map(|(i, opt)| btn(i, &opt.label, opt.style))
                .collect::<String>()
        ),
        SuggestLayout::Column => options
            .iter()
            .enumerate()
            .map(|(i, opt)| {
                format!(
                    "<tg-button-row>{}</tg-button-row>",
                    btn(i, &opt.label, opt.style)
                )
            })
            .collect::<Vec<_>>()
            .join("\n"),
        SuggestLayout::NumberedProse => (0..options.len())
            .map(|i| {
                btn(
                    i,
                    &go_button_label(i + 1, &options[i].label, options.len() == 1),
                    options[i].style,
                )
            })
            .collect::<Vec<_>>()
            .chunks(MAX_NUMBERS_PER_ROW)
            .map(|c| format!("<tg-button-row>{}</tg-button-row>", c.concat()))
            .collect::<Vec<_>>()
            .join("\n"),
    }
}

#[allow(clippy::too_many_arguments)] // #31: trailer rides the existing arg set
pub(crate) async fn render_suggestions(
    bot: &teloxide::Bot,
    state: &Arc<TelegramState>,
    session_id: Uuid,
    chat_id: ChatId,
    thread_id: Option<ThreadId>,
    options: Vec<crate::brain::tools::suggest_options::SuggestionItem>,
    // Merge candidate captured by deliver_final_response: the bubble the final
    // response landed in, whatever surface sent it (classic HTML, or table-free
    // rich markdown). Some = attach the controls to THAT bubble — one message
    // instead of two, no "Suggested next" header. None or failed edit =
    // standalone fallback below.
    merge_host: Option<super::state::MergeBubble>,
    // #31: the post-halt sign-off run reclaimed from the flow (after the
    // suggest_options Tool entry). Rich merge: embedded as a paragraph AFTER
    // the in-body button rows (one message, never removed). Every other
    // shape: its own bubble after placement — content, not chrome, so it
    // ships even when the buttons die.
    trailer: Option<String>,
) {
    if options.is_empty() {
        // Stash cleared between delivery and render (mid-turn tap, newer
        // turn) — the trailer still ships (#31); there is nothing to
        // register and no keyboard to place.
        if let Some(t) = &trailer {
            send_trailer_bubble(bot, chat_id, thread_id, t).await;
        }
        return;
    }

    let raw_options: Vec<String> = options.iter().map(|o| o.label.clone()).collect();
    // Per-keyboard identity (#1217): register BEFORE building buttons so the
    // callback token exists before the keyboard goes to the wire. Opaque
    // token rides in every callback payload; taps resolve against this exact
    // set even when a newer turn registers its own keyboard meanwhile.
    let token = state
        .register_pending_followups(session_id, raw_options.clone())
        .await;
    // Layout tiers are measured, not guessed (see BUTTON_LABEL_MAX_UNITS
    // and SINGLE_BUTTON_MAX_UNITS): short labels share one row, medium
    // labels get a full-width row each, a lone option rides one
    // full-width button up to its own clip point (#119), and anything
    // longer folds into the body (set-size split, owner order 2026-09-09):
    // n=1 = bold `Go: <label>?` + a Go! button; n>=2 = the plain
    // numbered list with `N. <FirstWord>` buttons (<=4 per row, owner
    // order 2026-09-14). The absolute index
    // is encoded in the
    // callback data; the option text itself can exceed Telegram's 64-byte
    // callback-data limit, so we never put it there.
    let layout = pick_layout(&raw_options);
    let text_btn = |i: usize, opt: &str| {
        InlineKeyboardButton::callback(opt.to_string(), format!("{FOLLOWUP_PREFIX}{token}:{i}"))
    };
    let rows: Vec<Vec<InlineKeyboardButton>> = match layout {
        SuggestLayout::SharedRow => vec![
            raw_options
                .iter()
                .enumerate()
                .map(|(i, opt)| text_btn(i, opt))
                .collect(),
        ],
        SuggestLayout::Column => raw_options
            .iter()
            .enumerate()
            .map(|(i, opt)| vec![text_btn(i, opt)])
            .collect(),
        SuggestLayout::NumberedProse => {
            let all: Vec<InlineKeyboardButton> = (0..raw_options.len())
                .map(|i| {
                    InlineKeyboardButton::callback(
                        go_button_label(i + 1, &raw_options[i], raw_options.len() == 1),
                        format!("{FOLLOWUP_PREFIX}{token}:{i}"),
                    )
                })
                .collect();
            all.chunks(MAX_NUMBERS_PER_ROW)
                .map(|c| c.to_vec())
                .collect()
        }
    };

    let keyboard = InlineKeyboardMarkup::new(rows);

    // Primary path: MERGE onto the answer bubble (#tg-suggest-merge). Prose
    // mode appends the `Go: <label>?` lines under the answer text (#119
    // fold tier); button modes add
    // nothing on the classic surface (the buttons carry everything). Rich
    // bubbles additionally get native <tg-button-row> controls INSIDE the
    // message body. Both placement payloads are built ONCE — before the first
    // attempt — so a Retry-After deferral (#30) re-sends byte-identical
    // content instead of re-deriving it.
    let merge_payload: Option<MergePayload> = merge_host.map(|host| {
        let mid = host.message_id;
        // Base body + plane: classic bubbles keep their exact delivered
        // HTML; markdown-plane hosts (#79 piece 4) keep the raw markdown —
        // including tables, which the markdown plane renders intact
        // server-side (C1 probe) where rich HTML input flattens them
        // (#679). The html conversion of the merged payload is kept only
        // as the host record's strip source.
        let (mut new_html, rich, new_markdown) = match host.body {
            super::state::BubbleBody::Html(html) => {
                let mut body = html;
                if layout == SuggestLayout::NumberedProse {
                    // Classic hosts preserve the raw newline join via
                    // go_tier_lines_rich (#119 fold tier: n=1 = bold
                    // `Go: <label>?`; n>=2 = the original plain numbered
                    // list — owner order 2026-09-09). Paragraph break
                    // before the block — owner correction 2026-09-09: a
                    // single \n glued the fold block to the body's last
                    // line.
                    if !body.ends_with('\n') {
                        body.push('\n');
                    }
                    body.push('\n');
                    body.push_str("<hr/>\n");
                    body.push_str(&go_tier_lines_rich(&raw_options));
                }
                (body, false, None)
            }
            super::state::BubbleBody::Markdown(md) => {
                let mut new_md = md;
                append_rows_and_trailer_md(
                    &mut new_md,
                    &options,
                    &token,
                    layout == SuggestLayout::NumberedProse,
                    trailer.as_deref(),
                );
                let strip_source = super::rich::markdown_to_html_p(&new_md);
                (strip_source, true, Some(new_md))
            }
        };
        if rich && new_markdown.is_none() {
            // Legacy html-plane rich host: the rows ride the html dialect
            // as before (#1226 newline handling applies).
            new_html.push('\n');
            new_html.push_str(&suggestion_rows_rich_html(&options, &token));
            if let Some(t) = &trailer {
                new_html.push('\n');
                new_html.push_str(&super::rich::markdown_to_html_p(t));
            }
        }
        MergePayload {
            message_id: mid,
            new_html,
            rich,
            new_markdown,
        }
    });

    let placement_payload = merge_payload;

    // Standalone fallback (no merge candidate, or the edit
    // lost a race / grew too old): the header sentence is still gone per
    // #tg-suggest-merge — prose mode shows just the `Go: <label>?` lines
    // (#119 fold tier; they ARE the questions), button
    // modes need SOME text for the Bot API to accept the message, so they
    // degrade to the bare 💡.
    let standalone_body = standalone_fallback_body(&layout, &raw_options);

    let option_count = options.len();
    match place_once(
        bot,
        state,
        chat_id,
        thread_id,
        &token,
        option_count,
        &keyboard,
        placement_payload.as_ref(),
        &standalone_body,
    )
    .await
    {
        Ok(()) => {
            // #31: send the trailer bubble only if it wasn't already embedded
            // in a rich merge. The followup host is attached only on merge
            // success, so peek_followup_host tells us if the merge landed.
            // If it did and was rich, the trailer is already in the HTML.
            let embedded = state
                .peek_followup_host(&token)
                .await
                .map(|h| h.rich && trailer.is_some())
                .unwrap_or(false);
            if !embedded && let Some(t) = &trailer {
                send_trailer_bubble(bot, chat_id, thread_id, t).await;
            }
        }
        Err(PlaceErr::Fatal(e)) => {
            tracing::warn!("Telegram suggest_options: send failed: {e}");
            // The buttons never landed — drop the stash so a stale entry can't
            // swallow an unrelated future tap.
            state.drop_pending_followup(&token).await;
        }
        Err(PlaceErr::RetryAfter(wait)) => {
            // #30: a 429 here used to drop the stash at once — but BOTH arms
            // die inside the same flood window (the standalone send followed
            // the merge edit by 22ms into the same 41s ban), and the buttons
            // were lost forever. Keep the stash instead and re-place after
            // the TRUE Retry-After, budget-capped.
            tracing::warn!(
                "Telegram suggest_options: placement hit Retry-After {}s (token {token}) — \
                 stash kept, deferring",
                wait.as_secs()
            );
            let bot = bot.clone();
            let state = state.clone();
            let token = token.clone();
            let keyboard = keyboard.clone();
            let trailer = trailer.clone();
            tokio::spawn(async move {
                let mut wait = wait;
                for attempt in 1..=MAX_DEFERRED_PLACEMENT_ATTEMPTS {
                    use rand::Rng;
                    // Jitter so several placements deferred by the same ban
                    // don't all re-hit Telegram on the same second.
                    let jitter = Duration::from_millis(rand::rng().random_range(0..=2000));
                    tokio::time::sleep(wait + jitter).await;
                    match place_once(
                        &bot,
                        &state,
                        chat_id,
                        thread_id,
                        &token,
                        option_count,
                        &keyboard,
                        placement_payload.as_ref(),
                        &standalone_body,
                    )
                    .await
                    {
                        Ok(()) => {
                            tracing::info!(
                                "Telegram suggest_options: deferred placement {attempt}/\
                                 {MAX_DEFERRED_PLACEMENT_ATTEMPTS} landed (token {token})"
                            );
                            // #31: send the trailer bubble only if it wasn't
                            // already embedded in a rich merge.
                            let embedded = state
                                .peek_followup_host(&token)
                                .await
                                .map(|h| h.rich && trailer.is_some())
                                .unwrap_or(false);
                            if !embedded && let Some(t) = &trailer {
                                send_trailer_bubble(&bot, chat_id, thread_id, t).await;
                            }
                            return;
                        }
                        Err(PlaceErr::Fatal(e)) => {
                            tracing::warn!(
                                "Telegram suggest_options: deferred placement {attempt} \
                                 failed permanently: {e}"
                            );
                            state.drop_pending_followup(&token).await;
                            return;
                        }
                        Err(PlaceErr::RetryAfter(w)) => {
                            tracing::warn!(
                                "Telegram suggest_options: deferred placement {attempt} hit \
                                 Retry-After {}s again (token {token})",
                                w.as_secs()
                            );
                            wait = w;
                        }
                    }
                }
                tracing::warn!(
                    "Telegram suggest_options: placement budget spent after \
                     {MAX_DEFERRED_PLACEMENT_ATTEMPTS} deferred attempts (token {token}) — dropping"
                );
                state.drop_pending_followup(&token).await;
            });
        }
    }
}

/// Pre-built merge-edit payload (#30): computed ONCE per suggestion block so
/// a deferred re-placement after a Retry-After re-sends byte-identical
/// content. `rich` picks the wire: rich bubbles edit via the rich API with
/// in-body button rows, classic bubbles via editMessageText + reply_markup.
#[derive(Clone)]
struct MergePayload {
    message_id: MessageId,
    new_html: String,
    rich: bool,
    /// Markdown-plane payload (#79 piece 4): when set, the merge edit and
    /// every later redraw ride `edit_rich_markdown`; `new_html` then only
    /// feeds the host record's strip source.
    new_markdown: Option<String>,
}

/// Placement error class (#30): decides whether the stash survives the
/// failure.
enum PlaceErr {
    /// Telegram answered 429 with a Retry-After — the placement may succeed
    /// once the window passes, so the stash MUST survive the wait.
    RetryAfter(Duration),
    /// Anything else: retrying cannot fix it; the stash drops as before.
    Fatal(String),
}

/// Deferred placement attempts after a Retry-After, on top of the inline
/// first pass (#30). Two deferrals cap the chase at roughly two flood
/// windows while comfortably covering the 31–42s windows observed in the
/// #30 ledger.
const MAX_DEFERRED_PLACEMENT_ATTEMPTS: u32 = 2;

/// Wait used when only the rich arm's stringified "(429)" survives — see
/// [`classify_rich_err`].
const RICH_429_FALLBACK_WAIT_SECS: u64 = 30;

fn classify_request_err(e: teloxide::RequestError) -> PlaceErr {
    match e {
        teloxide::RequestError::RetryAfter(secs) => PlaceErr::RetryAfter(secs.duration()),
        other => PlaceErr::Fatal(other.to_string()),
    }
}

/// The rich arm buries Telegram's exact retry_after inside its own internal
/// retry loop (`post_rich`) and surfaces only an anyhow string, so
/// classification keys off the status marker. The wait is a middle-of-the-
/// road default: the rich path already slept out the true value
/// RICH_MAX_RETRIES times before bailing, and the observed flood windows
/// run 31–42s (#30 ledger).
fn classify_rich_err(e: &str) -> PlaceErr {
    if e.contains("(429)") {
        PlaceErr::RetryAfter(Duration::from_secs(RICH_429_FALLBACK_WAIT_SECS))
    } else {
        PlaceErr::Fatal(e.to_string())
    }
}

/// Fence-safe markdown-plane edit (#98): every redraw that re-sends a
/// rich-md host body must preserve a delivered mermaid diagram. When the
/// body carries a mermaid fence, resolve it to markdown+media — the send
/// path's own mechanism (#1044) — and edit via the media-capable rich edit,
/// so the image re-renders instead of degrading to raw fence text.
///
/// - No fence → byte-identical plain `edit_rich_markdown` (no resolve call).
/// - Fence but empty media (every fence degraded to a failure block) →
///   plain edit of the resolved body; the failure block is the legible form.
/// - Media edit rejected with 429 → propagate WITHOUT fallback: retries must
///   re-send the same body (#30 byte-identity), a fallback body would flip
///   the plane mid-retry.
/// - Media edit rejected otherwise → warn + plain edit of the ORIGINAL body,
///   so the keyboard always lands (diagram degrades to pre-#98 fence text,
///   never worse than today).
#[allow(clippy::too_many_arguments)]
pub(crate) async fn edit_rich_md_fencesafe(
    api_url: &str,
    token: &str,
    chat_id: i64,
    message_id: i32,
    markdown: &str,
    reply_markup: Option<&serde_json::Value>,
    origin: &str,
    origin_detail: &str,
) -> Result<(), String> {
    if !super::rich::mermaid::has_mermaid_fence(markdown) {
        return super::rich::api::edit_rich_markdown(
            api_url,
            token,
            chat_id,
            message_id,
            markdown,
            reply_markup,
            origin,
            origin_detail,
        )
        .await
        .map_err(|e| e.to_string());
    }
    let (resolved, media) = super::rich::mermaid::resolve_markdown_media(markdown).await;
    if media.is_empty() {
        return super::rich::api::edit_rich_markdown(
            api_url,
            token,
            chat_id,
            message_id,
            &resolved,
            reply_markup,
            origin,
            origin_detail,
        )
        .await
        .map_err(|e| e.to_string());
    }
    match super::rich::api::edit_rich_markdown_media(
        api_url,
        token,
        chat_id,
        message_id,
        &resolved,
        &media,
        reply_markup,
        origin,
        origin_detail,
    )
    .await
    {
        Ok(()) => Ok(()),
        Err(e) => {
            let s = e.to_string();
            if s.contains("(429)") {
                return Err(s);
            }
            tracing::warn!(
                "Telegram rich edit: media edit rejected ({s}) — plain markdown fallback \
                 (keyboard lands; fence degrades to text)"
            );
            super::rich::api::edit_rich_markdown(
                api_url,
                token,
                chat_id,
                message_id,
                markdown,
                reply_markup,
                origin,
                origin_detail,
            )
            .await
            .map_err(|e| e.to_string())
        }
    }
}

/// One placement pass (#30): merge onto the answer bubble when a payload
/// exists, standalone otherwise. RetryAfter-class errors bubble up so the
/// caller can defer with the stash intact; anything else is Fatal.
#[allow(clippy::too_many_arguments)]
async fn place_once(
    bot: &teloxide::Bot,
    state: &Arc<TelegramState>,
    chat_id: ChatId,
    thread_id: Option<ThreadId>,
    token: &str,
    option_count: usize,
    keyboard: &InlineKeyboardMarkup,
    merge: Option<&MergePayload>,
    standalone_body: &str,
) -> Result<(), PlaceErr> {
    use teloxide::prelude::Requester;

    if let Some(mp) = merge {
        let mid = mp.message_id;
        let outcome: Result<(), PlaceErr> = if let Some(md) = &mp.new_markdown {
            // Markdown-plane host (#79 piece 4): raw markdown + embedded
            // button rows — the server render keeps tables intact (#679).
            // Fence-safe (#98): a delivered mermaid diagram re-renders
            // instead of degrading to raw fence text.
            edit_rich_md_fencesafe(
                bot.api_url().as_str(),
                bot.token(),
                chat_id.0,
                mid.0,
                md,
                None,
                "turn",
                "-",
            )
            .await
            .map_err(|e| classify_rich_err(&e))
        } else if mp.rich {
            super::rich::api::edit_rich_html(
                bot.api_url().as_str(),
                bot.token(),
                chat_id.0,
                mid.0,
                &mp.new_html,
                None,
                "turn",
                "-",
            )
            .await
            .map_err(|e| classify_rich_err(&e.to_string()))
        } else {
            bot.edit_message_text(chat_id, mid, &mp.new_html)
                .parse_mode(ParseMode::Html)
                .reply_markup(keyboard.clone())
                .await
                .map(|_| ())
                .map_err(classify_request_err)
        };
        match outcome {
            Ok(()) => {
                tracing::info!(
                    "Telegram suggest_options: keyboard merged onto msg {mid} \
                     ({} host, token {token}, {option_count} options)",
                    if mp.new_markdown.is_some() {
                        "rich-md"
                    } else if mp.rich {
                        "rich"
                    } else {
                        "classic"
                    }
                );
                state
                    .attach_followup_host(
                        token,
                        super::state::MergedHost {
                            message_id: mid,
                            html: mp.new_html.clone(),
                            rich: mp.rich,
                            markdown: mp.new_markdown.clone(),
                        },
                    )
                    .await;
                return Ok(());
            }
            Err(PlaceErr::RetryAfter(wait)) => return Err(PlaceErr::RetryAfter(wait)),
            Err(PlaceErr::Fatal(e)) => {
                tracing::warn!(
                    "Telegram suggest_options: merge onto msg {mid} failed ({e}) — standalone fallback"
                );
            }
        }
    }

    let mut req = bot
        .send_message(chat_id, standalone_body)
        .reply_markup(keyboard.clone());
    req = req.parse_mode(ParseMode::Html);
    if let Some(tid) = thread_id {
        req = req.message_thread_id(tid);
    }
    match req.await {
        Ok(msg) => {
            tracing::info!(
                "Telegram suggest_options: standalone block msg {} \
                 (token {token}, {option_count} options)",
                msg.id
            );
            Ok(())
        }
        Err(e) => Err(classify_request_err(e)),
    }
}

/// The #31 sign-off trailer as its own bubble: Markdown rendered with the
/// same HTML wire as every other telegram bubble, thread-routed, with a
/// plain-text retry when the parse-mode send is rejected — a malformed
/// markdown construct must degrade the sign-off, never discard it
/// (keep-never-discard is the whole point of #31).
async fn send_trailer_bubble(
    bot: &teloxide::Bot,
    chat_id: ChatId,
    thread_id: Option<ThreadId>,
    trailer: &str,
) {
    use teloxide::prelude::Requester;

    // #583 (residual of #93/#58): a fence-bearing trailer renders its diagrams
    // via the hooked rich send (media assembly + HTML-dialect fallback
    // inside). Keep-never-discard (#31) is preserved by the fall-through: any
    // rich-path failure drops to the legacy HTML send + plain retry below.
    if super::rich::mermaid::should_render_mermaid(trailer) {
        match super::rich::send_rich_with_mermaid(
            bot.api_url().as_str(),
            bot.token(),
            chat_id.0,
            thread_id,
            trailer,
            "turn",
            "#583-trailer",
        )
        .await
        {
            Ok(()) => {
                tracing::info!("Telegram: #31 trailer bubble delivered rich (#583) with mermaid");
                return;
            }
            Err(e) => {
                tracing::warn!(
                    "Telegram: #31 trailer rich send failed ({e}) — falling back to legacy HTML path"
                );
            }
        }
    }

    let html = super::markdown::markdown_to_telegram_html(trailer);
    let mut req = bot.send_message(chat_id, html).parse_mode(ParseMode::Html);
    if let Some(tid) = thread_id {
        req = req.message_thread_id(tid);
    }
    match req.await {
        Ok(msg) => {
            tracing::info!("Telegram: #31 trailer bubble delivered as msg {}", msg.id);
        }
        Err(e) => {
            tracing::warn!("Telegram: #31 trailer bubble HTML send failed ({e}) — retrying plain");
            let mut plain = bot.send_message(chat_id, trailer);
            if let Some(tid) = thread_id {
                plain = plain.message_thread_id(tid);
            }
            match plain.await {
                Ok(msg) => {
                    tracing::info!(
                        "Telegram: #31 trailer bubble delivered plain as msg {}",
                        msg.id
                    );
                }
                Err(e2) => {
                    tracing::warn!("Telegram: #31 trailer bubble dropped after plain retry: {e2}");
                }
            }
        }
    }
}