edamame 0.1.5

use std::cell::{OnceCell, RefCell};
use std::collections::HashMap;
use std::ops::Range;

use ratatui::text::Line;

use crate::config::Theme;
use crate::diagram::DiagramSource;
use crate::document::visual_cache::VisualRowCache;
use crate::document::SourceMap;
use crate::markdown::{
    annotate_list_blanks, inlines_to_plain, parse_raw_with_ranges, promote_diagram_code_blocks,
    promote_display_math_paragraphs, promote_html_comments, promote_image_paragraphs,
    reconstruct_broken_display_math, split_display_math_paragraphs, Block, ImageRowOverride,
    InlineColMap, RenderCache, Renderer,
};

/// Setext heading style detected from raw block source.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SetextKind {
    H1,
    H2,
}

/// The setext variant for `source`: a non-blank line not starting with `#`, followed by
/// one consisting entirely of `=` (H1) or `-` (H2).  Trailing spaces on the underline are
/// allowed per CommonMark.
pub fn detect_setext(source: &str) -> Option<SetextKind> {
    let mut lines = source.lines();
    let first = lines.next()?;
    let second = lines.next()?;
    if first.trim().is_empty() {
        return None;
    }
    if first.trim_start().starts_with('#') {
        return None;
    }
    let second = second.trim_end();
    if second.is_empty() {
        return None;
    }
    if second.chars().all(|c| c == '=') {
        return Some(SetextKind::H1);
    }
    if second.chars().all(|c| c == '-') {
        return Some(SetextKind::H2);
    }
    None
}

/// Metadata for one `Block::ImageBlock`, for the image loader and placeholder.
#[derive(Debug, Clone)]
pub struct ImageBlockInfo {
    /// Index in the `SourceMap`'s virtual-block space — feed it to
    /// `source_map.rendered_lines_for_block` for the rows this image reserves.
    pub block_idx: usize,
    pub alt: String,
    pub url: String,
    /// `Some` when promoted from a fenced diagram code block.  The App decode worker
    /// branches on it to pick between `crate::image::resolve` and
    /// `crate::diagram::resolve_mermaid`; both funnel to the same `ImageReady` path.
    pub source: Option<DiagramSource>,
}

/// The parsed and rendered state of the document: rendered lines, the cursor ↔
/// rendered-line [`SourceMap`], and the block AST.  Rebuilt from scratch after every edit.
#[derive(Debug, Clone)]
pub struct ParsedDoc {
    /// Rendered styled lines.
    pub lines: Vec<Line<'static>>,
    /// The text this parse was built from — the coordinate space of every byte range in
    /// [`source_map`](Self::source_map) and [`real_ranges`](Self::real_ranges).
    ///
    /// The live `Buffer` is *not* that space: a deferred in-line edit advances the buffer
    /// without rebuilding the parse, so slicing the buffer with a parse-time range reads
    /// text shifted by the edit's length — and a shift crossing a line boundary silently
    /// changes how many lines the slice appears to have.  Resolve parse-time ranges here
    /// (see [`byte_to_line`](Self::byte_to_line)); touch the buffer only with a *live*
    /// offset.
    source: Box<str>,
    /// Source map linking rendered lines to source byte ranges.
    pub source_map: SourceMap,
    /// Post-processed block AST, 1:1 with `real_ranges`.  Reflects every post-parse pass
    /// and any live table-width override, so callers see exactly what the renderer
    /// rendered — and per-frame consumers need not re-run pulldown-cmark on every draw.
    pub blocks: Vec<crate::markdown::Block>,
    /// Byte ranges of the real (non-blank) source blocks, 1:1 with `blocks`.  The
    /// blank-line virtual blocks are NOT here — look those up via `source_map`.
    pub real_ranges: Vec<Range<usize>>,
    /// Rendered lines produced by block `i` *itself*, before `preserve_blank_lines`
    /// inserts inter-block gap lines.  `RenderedView` uses it to keep gap lines out of the
    /// cursor block's raw replacement region.
    per_block_own: Vec<usize>,
    /// Every `Block::ImageBlock`, in document order, so the decode-dispatch scan and the
    /// paint pass don't each walk the block list.
    pub image_blocks: Vec<ImageBlockInfo>,
    /// GFM-slug → rendered-line index for every heading; `LinkTarget::Anchor` dispatches
    /// against it.  Slugs are lowercased, stripped to `[a-z0-9 -]`, whitespace runs
    /// become `-`, and collisions take a `-N` suffix.
    pub heading_anchors: HashMap<String, usize>,
    /// Label → rendered-line index for every footnote definition, the footnote analogue of
    /// [`heading_anchors`](Self::heading_anchors).  The key is the raw label as written,
    /// not the rendered number.
    pub footnote_anchors: HashMap<String, usize>,
    /// Width-keyed lazy cache of `visual_rows_for_line`, so the snapshot builders and the
    /// scroll arithmetic don't re-walk and re-allocate per call.
    ///
    /// A small LRU rather than one slot because each frame queries two widths in lockstep:
    /// total rows at the full doc-area width to decide whether a scrollbar gutter is
    /// needed, then again at the post-gutter width for the scrollbar's metrics.  One slot
    /// rebuilds twice per frame on long documents — visible as scroll lag.
    pub(super) visual_rows: RefCell<Vec<VisualRowCache>>,
    /// Lazy rendered-line → source-line table for the gutter, filled by
    /// `editor::state_source_lines`.
    ///
    /// Here rather than on `EditorState` so its lifetime is exactly this parse's: a
    /// deferred in-line edit bumps `parsed_version` without rebuilding the parse and keeps
    /// painting *these* rows, so it must keep this table too — and a reparse drops it by
    /// construction.
    source_lines: OnceCell<Vec<Option<usize>>>,
    /// Lazy per-buffer-line raw ↔ rendered column maps, for the selection painter and the
    /// cursor-indicator overlay.
    inline_maps: Vec<OnceCell<InlineColMap>>,
    /// Whether this parse rendered prose paragraphs with reflow on (soft breaks → spaces,
    /// wrapped as one flow).  Consumers that map a rendered row to a source line
    /// (`state_source_lines`, `mouse_ops::coord`, the overlay painter) branch on it, because a
    /// reflowed paragraph's rendered row spans several source lines rather than one.
    pub reflow_paragraphs: bool,
    /// `(block_idx, band_rows)` for a `$$...$$` block currently revealed with the live math
    /// preview, or `None`.  When set, that block's rendered rows split into a top preview band of
    /// `band_rows` (the rendered formula) followed by the editable raw-source rows, so the formula
    /// keeps the block's top edge.  Every rendered-row ⇄ source-line mapping shifts the source rows
    /// down by `band_rows` through [`latex_source_offset`](Self::latex_source_offset).  Set by
    /// `EditorState::refresh_parsed`; a mermaid or preview-off reveal leaves it `None`.
    pub(crate) math_source_offset: Option<(usize, usize)>,
}

impl ParsedDoc {
    /// Parse `source` and render it using `theme`.
    ///
    /// `preserve_blank_lines` reflects consecutive source blank lines in the output
    /// instead of collapsing them the way Markdown does.  `image_max_height` is the
    /// rendered-row ceiling for each `Block::ImageBlock`.
    pub fn build(
        source: &str,
        theme: &Theme,
        preserve_blank_lines: bool,
        image_max_height: usize,
    ) -> Self {
        Self::build_with_overrides(
            source,
            theme,
            preserve_blank_lines,
            image_max_height,
            None,
            None,
            false,
            80,
            false,
            false,
            true,
            false,
            None,
        )
    }

    /// Like [`Self::build`], but with two live overrides.
    ///
    /// `live_table_widths` splices `user_widths` onto the table starting at its `.0` byte,
    /// so a column-resize drag can preview widths without writing the `tui-columns`
    /// comment to the buffer on every mouse-move.
    ///
    /// `image_row_override` is a `(URL, image-block ordinal)` → row-count callback that
    /// reserves exactly the rows each decoded image will occupy and collapses the one block
    /// whose raw source the cursor revealed.  The ordinal indexes [`Self::image_blocks`],
    /// built from the same document-order walk the renderer counts in.  `None` from (or
    /// for) the callback falls back to `image_max_height`.
    #[allow(clippy::too_many_arguments)]
    pub fn build_with_overrides(
        source: &str,
        theme: &Theme,
        preserve_blank_lines: bool,
        image_max_height: usize,
        live_table_widths: Option<&(usize, Vec<Option<usize>>)>,
        image_row_override: Option<ImageRowOverride>,
        row_striping: bool,
        viewport_width: usize,
        big_h1: bool,
        // When false, code-block bodies are the single-span lines they were before
        // highlighting existed.
        syntax_highlighting: bool,
        // When false, fenced diagram blocks stay ordinary code blocks and their source
        // shows verbatim — what a user who declined the diagrams prompt should see.
        promote_diagrams: bool,
        // When true, prose paragraphs reflow (soft breaks become spaces, the paragraph
        // wraps to the viewport as one flow) instead of rendering one row per source line.
        reflow_paragraphs: bool,
        // Block-level render memoization, so unchanged blocks reuse their rendered lines.
        // `None` (tests, one-shot builds) renders everything from scratch.
        render_cache: Option<&mut RenderCache>,
    ) -> Self {
        // Blocks and their byte ranges from one pulldown-cmark pass, 1:1 until the
        // `tui-columns` merge below.  That merge MUST run before the live-widths override:
        // it checks for `user_widths: None`, so overriding first would leave the comment
        // unabsorbed and flashing into the rendered view between drag events.
        let (mut blocks, mut real_ranges) = parse_raw_with_ranges(source);
        let total_bytes = source.len();
        // Loose-list items carry their preceding blank-line count so the renderer can
        // space them while the list stays one `Block::List`.
        annotate_list_blanks(&mut blocks, &real_ranges, source);
        // FIRST: the merge below looks for a `Block::HtmlComment` next to a
        // `Block::Table`, so it must run against the promoted variant.  Order and count
        // are preserved, so `real_ranges` stays 1:1.
        promote_html_comments(&mut blocks);
        merge_trailing_tui_columns_comments(&mut blocks, &mut real_ranges);
        // Image-only paragraphs become `Block::ImageBlock` so the renderer reserves
        // multi-row space for the graphics overlay.  In place, so alignment stays 1:1.
        promote_image_paragraphs(&mut blocks, Some(&mut real_ranges));
        // Rescue a `$$...$$` block whose interior LaTeX pulldown refused to close (an unbalanced
        // brace mid-typing): rebuild the display-math inline so it promotes like any other formula
        // instead of collapsing to prose and losing its reserved rows.  Runs in both branches so
        // the figures-off `math` code-block rendering stays consistent too.  Ranges and block
        // count are untouched, so the 1:1 alignment holds.
        reconstruct_broken_display_math(&mut blocks, &real_ranges, source);
        // Fenced diagram blocks and `$$...$$`-only paragraphs take the same path.  Each returns a
        // `url → DiagramSource` map, merged and attached to `ImageBlockInfo.source` below so the
        // decode worker finds the source text without re-walking `blocks`.  Both are gated on
        // `promote_diagrams`: mermaid and display math share one consent switch, so a user who
        // declined keeps seeing the original source rather than a placeholder they can't render.
        let diagram_sources = if promote_diagrams {
            let mut sources = promote_diagram_code_blocks(&mut blocks);
            sources.extend(promote_display_math_paragraphs(
                &mut blocks,
                &mut real_ranges,
                source,
            ));
            sources
        } else {
            // Figures off: mermaid fences already ARE code blocks, but two
            // `$$...$$` formulas stacked with no blank line between them are
            // one paragraph (pulldown folds them).  Split that paragraph so
            // each formula becomes its own block and renders as a separate
            // fenced-style `math` code block — matching how the figures-on
            // path promotes them to one image block per formula.
            split_display_math_paragraphs(&mut blocks, &mut real_ranges, source);
            HashMap::new()
        };
        if let Some((override_start, widths)) = live_table_widths {
            apply_live_table_widths(&mut blocks, &real_ranges, *override_start, widths);
        }

        // The viewport width feeds the table-column min-max distribution, so wide tables
        // wrap proportionally rather than overflow.
        let mut renderer = Renderer::new(theme)
            .with_viewport_width(viewport_width.max(1))
            .with_image_max_height(image_max_height)
            .with_row_striping(row_striping)
            .with_big_h1(big_h1)
            .with_syntax_highlighting(syntax_highlighting)
            .with_reflow_paragraphs(reflow_paragraphs);
        if let Some(override_fn) = image_row_override {
            renderer = renderer.with_image_row_override(override_fn);
        }
        let (rendered_lines, real_per_block_counts) = match render_cache {
            Some(cache) => renderer.render_with_counts_cached(&blocks, cache),
            None => renderer.render_with_counts(&blocks),
        };

        // Each source blank line becomes its own virtual block owning a single `\n`, so
        // cursor navigation stays 1:1 with buffer lines and never jumps a blank line.
        //
        // pulldown-cmark's ranges absorb a variable number of trailing newlines, so each
        // real block backs up past them (`content_end_of_block`) and then counts forward:
        // the first `\n` ends the block, each additional one is a blank line.
        let src_bytes = source.as_bytes();
        let mut lines: Vec<Line<'static>> = Vec::with_capacity(rendered_lines.len());
        let mut rendered_to_block: Vec<usize> = Vec::with_capacity(rendered_lines.len());
        let mut all_original: Vec<Range<usize>> = Vec::new();
        let mut all_per_block_own: Vec<usize> = Vec::new();

        let push_blank = |lines: &mut Vec<Line<'static>>,
                          r2b: &mut Vec<usize>,
                          origs: &mut Vec<Range<usize>>,
                          owns: &mut Vec<usize>,
                          original: Range<usize>,
                          emit: bool| {
            let idx = origs.len();
            origs.push(original);
            owns.push(if emit { 1 } else { 0 });
            if emit {
                lines.push(Line::raw(""));
                r2b.push(idx);
            }
        };

        // Leading blank lines — the whole document when there are no real blocks.
        let leading_end = real_ranges
            .first()
            .map(|r| r.start.min(total_bytes))
            .unwrap_or(total_bytes);
        let mut bp = 0usize;
        while bp < leading_end {
            if src_bytes[bp] == b'\n' {
                push_blank(
                    &mut lines,
                    &mut rendered_to_block,
                    &mut all_original,
                    &mut all_per_block_own,
                    bp..bp + 1,
                    preserve_blank_lines,
                );
            }
            bp += 1;
        }

        // Real blocks, each followed by the blank lines in the gap after it.
        // `rendered_lines` is consumed by move: cloning each `Line<'static>` deep-copies
        // every span's Cow, which is measurable on large documents.
        let mut rendered_iter = rendered_lines.into_iter();
        let mut image_blocks = Vec::new();
        let mut heading_anchors: HashMap<String, usize> = HashMap::new();
        let mut footnote_anchors: HashMap<String, usize> = HashMap::new();
        let mut anchor_counts: HashMap<String, usize> = HashMap::new();
        for (i, &count) in real_per_block_counts.iter().enumerate() {
            let idx = all_original.len();
            all_original.push(real_ranges[i].clone());
            all_per_block_own.push(count);
            if let Block::ImageBlock { alt, url } = &blocks[i] {
                let source = diagram_sources.get(url).cloned();
                image_blocks.push(ImageBlockInfo {
                    block_idx: idx,
                    alt: alt.clone(),
                    url: url.clone(),
                    source,
                });
            }
            if let Block::Heading { inlines, .. } = &blocks[i] {
                let plain = inlines_to_plain(inlines);
                let base_slug = gfm_slug(&plain);
                let slug = uniquify_slug(&base_slug, &mut anchor_counts);
                // `lines.len()` is where this heading's first line will land, since the
                // block's own lines are pushed below.
                heading_anchors.insert(slug, lines.len());
            }
            if let Block::FootnoteDefinition { label, .. } = &blocks[i] {
                footnote_anchors.insert(label.clone(), lines.len());
            }
            for _ in 0..count {
                if let Some(line) = rendered_iter.next() {
                    lines.push(line);
                    rendered_to_block.push(idx);
                }
            }

            // A setext H2 has two raw lines but renders as one, so append a rule to keep
            // `RenderedView`'s reveal 1:1 with the source — what setext H1 already does in
            // `Renderer::render_heading`.
            let block_source = &source[real_ranges[i].start..real_ranges[i].end.min(total_bytes)];
            if count == 1 && matches!(detect_setext(block_source), Some(SetextKind::H2)) {
                lines.push(Line::styled("─".repeat(viewport_width.max(1)), theme.rule));
                rendered_to_block.push(idx);
                if let Some(n) = all_per_block_own.last_mut() {
                    *n += 1;
                }
            }

            let content_end = content_end_of_block(source, &real_ranges[i]);
            let gap_end = if i + 1 < real_ranges.len() {
                real_ranges[i + 1].start.min(total_bytes)
            } else {
                total_bytes
            };

            let mut newline_count = 0usize;
            let mut emitted_in_gap = 0usize;
            let mut gp = content_end;
            while gp < gap_end {
                if src_bytes[gp] == b'\n' {
                    newline_count += 1;
                    if newline_count > 1 {
                        let emit = preserve_blank_lines || emitted_in_gap == 0;
                        push_blank(
                            &mut lines,
                            &mut rendered_to_block,
                            &mut all_original,
                            &mut all_per_block_own,
                            gp..gp + 1,
                            emit,
                        );
                        if emit {
                            emitted_in_gap += 1;
                        }
                    }
                }
                gp += 1;
            }
        }

        // Defensive: stray rendered lines go to the most recently pushed block.
        for line in rendered_iter {
            lines.push(line);
            let last = all_original.len().saturating_sub(1);
            rendered_to_block.push(last);
        }

        // Phantom final line: a source ending in '\n' has one more buffer line than the
        // loops produce blocks for, since ropey puts the cursor on an empty line *after*
        // the last '\n'.  Without its own block, `block_for_byte`'s end-of-source fallback
        // attributes that cursor to the last real block and `RenderedView` swallows the
        // block's text under an empty raw reveal.
        //
        // An *empty* document takes the same branch and must: ropey reports one line for
        // `""` but the loops produce no blocks, so the rendered / preview painters (which
        // iterate rendered lines) would paint nothing at all, cursor included.
        if total_bytes == 0 || src_bytes[total_bytes - 1] == b'\n' {
            push_blank(
                &mut lines,
                &mut rendered_to_block,
                &mut all_original,
                &mut all_per_block_own,
                total_bytes..total_bytes,
                true,
            );
        }

        let extended_ranges = build_extended_ranges(&all_original, total_bytes);

        let source_map = SourceMap::new(
            rendered_to_block,
            extended_ranges,
            all_original,
            total_bytes,
        );

        let line_count = source.split('\n').count();
        Self {
            lines,
            source: source.into(),
            source_map,
            blocks,
            real_ranges,
            per_block_own: all_per_block_own,
            image_blocks,
            heading_anchors,
            footnote_anchors,
            visual_rows: RefCell::new(Vec::new()),
            source_lines: OnceCell::new(),
            inline_maps: (0..line_count).map(|_| OnceCell::new()).collect(),
            reflow_paragraphs,
            // Set by `EditorState::refresh_parsed` once the live reveal is known; a fresh parse
            // starts with no preview split.
            math_source_offset: None,
        }
    }

    /// Whether the block covering `byte` is a paragraph rendered with reflow on *and* collapsed
    /// to a single rendered logical line.  The single gate the reflow-aware consumers (gutter,
    /// mouse, overlay, `EffectiveRows`) share so they agree on which blocks lost the 1:1
    /// source-line ↔ rendered-row correspondence.  Resolved through
    /// [`real_block_for_byte`](Self::real_block_for_byte), never a raw `blocks` index (whose
    /// space counts blank-line virtual blocks).
    ///
    /// A paragraph with a hard break does not reflow (`render_paragraph`), so it renders as
    /// several logical lines and the single-line check excludes it — those consumers keep the
    /// per-source-line path.  A soft-break-only paragraph stays one logical line even when it
    /// wraps to several *visual* rows, so wrapping is unaffected.
    pub fn is_reflowed_paragraph_at(&self, byte: usize) -> bool {
        self.reflow_paragraphs
            && matches!(
                self.real_block_for_byte(byte),
                Some(crate::markdown::Block::Paragraph { .. })
            )
            && {
                let r = self.source_map.rendered_lines_for_byte(byte);
                r.end.saturating_sub(r.start) == 1
            }
    }

    /// Number of rendered lines.
    pub fn line_count(&self) -> usize {
        self.lines.len()
    }

    /// The text this parse was built from.  See [`source`](Self::source) for why a
    /// parse-time range must be resolved here and never against the live `Buffer`.
    pub fn source(&self) -> &str {
        &self.source
    }

    /// 0-based source line containing `byte`, counted in *this parse's* text — the
    /// correct answer when a deferred in-line edit has left the buffer disagreeing.
    ///
    /// Past-the-end answers the last line.  O(byte), so a caller walking every block in
    /// order should keep a running count instead.
    pub fn byte_to_line(&self, byte: usize) -> usize {
        let upto = byte.min(self.source.len());
        self.source.as_bytes()[..upto]
            .iter()
            .filter(|&&b| b == b'\n')
            .count()
    }

    /// See [`per_block_own`](Self::per_block_own).
    pub fn block_own_line_count(&self, block_idx: usize) -> usize {
        self.per_block_own.get(block_idx).copied().unwrap_or(0)
    }

    /// The post-processed [`Block`] whose *real* range contains `byte`; `None` on a blank
    /// line.  Searches `real_ranges`, not the source map's space — the two diverge by one
    /// per preceding blank line, so a source-map index must never index `blocks`.
    pub fn real_block_for_byte(&self, byte: usize) -> Option<&Block> {
        let idx = self.real_ranges.partition_point(|r| r.end <= byte);
        let range = self.real_ranges.get(idx)?;
        if byte >= range.start && byte < range.end {
            self.blocks.get(idx)
        } else {
            None
        }
    }

    /// True for a synthetic `Block::ImageBlock` promoted from a mermaid fence.  These
    /// share the fenced-code "reveal the entire raw source on cursor entry" affordance,
    /// which several call sites special-case; the rule lives here.
    pub fn is_mermaid_block(&self, block_idx: usize) -> bool {
        self.image_blocks.iter().any(|info| {
            info.block_idx == block_idx && matches!(info.source, Some(DiagramSource::Mermaid(_)))
        })
    }

    /// True when `block_idx` is a synthetic image block promoted from a `$$...$$` display-math
    /// paragraph (see `promote_display_math_paragraphs`).
    pub fn is_latex_block(&self, block_idx: usize) -> bool {
        self.image_blocks.iter().any(|info| {
            info.block_idx == block_idx && matches!(info.source, Some(DiagramSource::Latex(_)))
        })
    }

    /// Rows of the live math-preview band above the revealed raw source for `block_idx`, or `0`
    /// when the block has no such band (not the revealed math block, mermaid, or preview off).
    /// Every rendered-row ⇄ source-line mapping shifts the source down by this amount.  See
    /// [`math_source_offset`](Self::math_source_offset).
    pub(crate) fn latex_source_offset(&self, block_idx: usize) -> usize {
        match self.math_source_offset {
            Some((idx, band)) if idx == block_idx => band,
            _ => 0,
        }
    }

    /// True for a *diagram-derived* image block — a mermaid fence or a `$$...$$` math formula,
    /// however many source lines it spans.  Such blocks reveal as a single unit (every reserved
    /// row swaps to its raw-source line 1:1), so the raw-reveal bookkeeping (timer, drag
    /// suppression, click/row mapping) treats them alike.  Ordinary images stay on the generic path.
    pub fn is_diagram_reveal_block(&self, block_idx: usize) -> bool {
        self.image_blocks.iter().any(|info| {
            info.block_idx == block_idx
                && matches!(
                    info.source,
                    Some(DiagramSource::Mermaid(_)) | Some(DiagramSource::Latex(_))
                )
        })
    }

    /// True for a `Block::ImageBlock` (real image or promoted diagram).  Such a block has one
    /// source line but reserves *many* rendered rows, so a caller translating a rendered sub-row
    /// back to a raw line must not use the sub-row index directly: the byte range can absorb a
    /// trailing blank line, and a naive `sub_idx` then addresses the wrong buffer line.
    /// `mouse_ops::coord` pins every reserved row to raw line 0; `rendered_view::paint` skips them
    /// via its `raw_line_idx` bounds check.
    pub fn is_image_block(&self, block_idx: usize) -> bool {
        self.image_blocks
            .iter()
            .any(|info| info.block_idx == block_idx)
    }

    // ── Inline column map cache ────────────────────────────────────────────

    /// Lazily-built bidirectional char-column map for `buffer_line_idx`, built from
    /// `raw_line` on the first call for that index.
    ///
    /// **Contract:** `raw_line` must be the canonical content for `buffer_line_idx` in the
    /// *current* generation.  The cache is keyed only by index, so non-canonical text
    /// returns a stale map silently — and initializing an entry with it poisons that entry
    /// for every later, correct caller.
    ///
    /// A caller deriving `(buffer_line_idx, raw_line)` from block byte ranges cannot
    /// guarantee canonicality (ranges starting mid-line, sub-rows past a block's raw line
    /// count), and must go through `EditorState::inline_map_for`, which verifies the pair
    /// against the live buffer and serves an uncached map on mismatch.
    pub fn inline_map(&self, buffer_line_idx: usize, raw_line: &str) -> &InlineColMap {
        debug_assert!(
            buffer_line_idx < self.inline_maps.len(),
            "InlineColMap: buffer_line_idx {buffer_line_idx} out of bounds ({})",
            self.inline_maps.len()
        );
        let cell = &self.inline_maps[buffer_line_idx];
        let map = cell.get_or_init(|| InlineColMap::build(raw_line));
        debug_assert_eq!(
            raw_line.chars().count(),
            map.raw_len(),
            "InlineColMap: raw_line char count mismatch for buffer line {buffer_line_idx}"
        );
        map
    }

    // ── Visual-row cache (rendered) ───────────────────────────────────────
    //
    // Thin lazy wrappers over `VisualRowCache`, populated on first query at a given width.

    /// Visual rows for rendered line `idx`.  O(1) once warm; O(lines) on the first call
    /// at a given width.
    pub fn visual_rows_for_line_at(&self, idx: usize, width: usize) -> usize {
        self.with_visual_rows(width, |c| c.for_line(idx))
    }

    /// Sum of visual rows occupied by rendered lines `[0..idx)` at `width`.
    pub fn visual_rows_before(&self, idx: usize, width: usize) -> usize {
        self.with_visual_rows(width, |c| c.before(idx))
    }

    /// Sum of visual rows over `[first..=last]`.  Used by tests in this crate.
    #[allow(dead_code)]
    pub fn visual_rows_between(&self, first: usize, last: usize, width: usize) -> usize {
        self.with_visual_rows(width, |c| c.between(first, last))
    }

    /// Total visual rows occupied by the rendered document at `width`.
    pub fn total_visual_rows(&self, width: usize) -> usize {
        self.with_visual_rows(width, |c| c.total())
    }

    /// Rendered-line → source-line table, built with `init` on first call.  See
    /// [`source_lines`](Self::source_lines) for why it is cached per parse.
    pub fn source_lines_or_init(
        &self,
        init: impl FnOnce() -> Vec<Option<usize>>,
    ) -> &[Option<usize>] {
        self.source_lines.get_or_init(init)
    }

    /// `(rendered_line_idx, sub_row)` for a document-level visual row.
    pub fn line_at_visual_row(&self, visual_row: usize, width: usize) -> (usize, usize) {
        self.with_visual_rows(width, |c| c.find_visual_row(visual_row))
    }

    /// Run `f` against the visual-row cache for `width`, warming it first if needed.
    fn with_visual_rows<R>(&self, width: usize, f: impl FnOnce(&VisualRowCache) -> R) -> R {
        self.ensure_visual_rows(width);
        let borrow = self.visual_rows.borrow();
        let cache = borrow
            .iter()
            .find(|c| c.width() == width)
            .expect("visual-row cache populated above");
        f(cache)
    }

    /// Promote an already-warm entry for `width` to the front, or build one and evict
    /// past the LRU capacity.  The immutable check releases before the `borrow_mut` so the
    /// `RefCell` is never aliased.
    fn ensure_visual_rows(&self, width: usize) {
        /// At least 2, to absorb the editor view's per-frame two-width query pattern.
        const LRU_CAP: usize = 2;
        {
            let borrow = self.visual_rows.borrow();
            if borrow.first().map(|c| c.width()) == Some(width) {
                return;
            }
        }
        let warm_pos = self
            .visual_rows
            .borrow()
            .iter()
            .position(|c| c.width() == width);
        if let Some(pos) = warm_pos {
            let mut entries = self.visual_rows.borrow_mut();
            let entry = entries.remove(pos);
            entries.insert(0, entry);
            return;
        }
        let cache = VisualRowCache::build(self.lines.len(), width, |i| {
            crate::ui::line_render::visual_rows_for_line(&self.lines[i], width)
        });
        let mut entries = self.visual_rows.borrow_mut();
        entries.insert(0, cache);
        entries.truncate(LRU_CAP);
    }
}

/// GitHub Flavored Markdown slug: lowercase, drop anything outside `[a-z0-9 -]`, collapse
/// whitespace runs to a single `-`.  Leading / trailing dashes are preserved (as GFM
/// does), and an empty slug is returned as-is for the caller to handle.
pub fn gfm_slug(text: &str) -> String {
    let mut out = String::with_capacity(text.len());
    let mut prev_ws = false;
    for ch in text.chars().flat_map(|c| c.to_lowercase()) {
        if ch.is_whitespace() {
            if !prev_ws {
                out.push('-');
            }
            prev_ws = true;
            continue;
        }
        prev_ws = false;
        if ch.is_ascii_alphanumeric() || ch == '-' {
            out.push(ch);
        }
    }
    out
}

/// Append a `-N` suffix on collision, matching GitHub: first use is `base`, then `base-1`,
/// `base-2`.  `counts` carries the per-base tally across calls.
pub(crate) fn uniquify_slug(base: &str, counts: &mut HashMap<String, usize>) -> String {
    let entry = counts.entry(base.to_owned()).or_insert(0);
    let slug = if *entry == 0 {
        base.to_owned()
    } else {
        format!("{base}-{}", *entry)
    };
    *entry += 1;
    slug
}

/// Splice a `user_widths` override onto the `Block::Table` whose range starts at
/// `override_start`, for the column-resize drag's preview.
fn apply_live_table_widths(
    blocks: &mut [crate::markdown::ast::Block],
    real_ranges: &[Range<usize>],
    override_start: usize,
    widths: &[Option<usize>],
) {
    use crate::markdown::ast::Block;
    // Blocks and ranges are emitted in the same order, so they pair by index before the
    // trailing-comment merge runs.
    let mut block_i = 0usize;
    while block_i < blocks.len() && block_i < real_ranges.len() {
        if real_ranges[block_i].start == override_start {
            if let Block::Table { user_widths, .. } = &mut blocks[block_i] {
                *user_widths = Some(widths.to_vec());
            }
        }
        block_i += 1;
    }
}

/// Merge trailing `<!-- tui-columns: [..] -->` blocks into their preceding tables,
/// rewriting `real_ranges` so the (block, range) pairing stays 1:1.  Mirrors
/// `markdown::parser::attach_trailing_tui_columns_comments`, which does not.
fn merge_trailing_tui_columns_comments(
    blocks: &mut Vec<crate::markdown::ast::Block>,
    real_ranges: &mut Vec<Range<usize>>,
) {
    use crate::markdown::ast::Block;
    let mut i = 0;
    while i + 1 < blocks.len() {
        let is_pair = matches!(
            (&blocks[i], &blocks[i + 1]),
            (Block::Table { user_widths: None, .. }, Block::HtmlComment(body))
                if crate::markdown::table_layout::parse_column_widths_comment(body).is_some()
        );
        if is_pair {
            let body = match &blocks[i + 1] {
                Block::HtmlComment(s) => s.clone(),
                _ => unreachable!(),
            };
            let widths = crate::markdown::table_layout::parse_column_widths_comment(&body).unwrap();
            if let Block::Table { user_widths, .. } = &mut blocks[i] {
                *user_widths = Some(widths);
            }
            blocks.remove(i + 1);
            // The table's extended range already ends at the next block's start, so
            // dropping the comment's range lets the covering-ranges pass fill the gap.
            if i + 1 < real_ranges.len() {
                let absorbed_end = real_ranges[i + 1].end;
                real_ranges[i] = real_ranges[i].start..absorbed_end;
                real_ranges.remove(i + 1);
            }
            continue;
        }
        i += 1;
    }
}

/// The byte just after the block's last non-newline character.  `block.end` may include
/// zero, one, or two trailing `\n`s depending on how pulldown-cmark reported the range.
fn content_end_of_block(source: &str, block: &Range<usize>) -> usize {
    let bytes = source.as_bytes();
    let mut end = block.end.min(bytes.len());
    while end > block.start && bytes[end - 1] == b'\n' {
        end -= 1;
    }
    end
}

/// Extend the block ranges so they non-overlappingly cover `0..total_bytes`: each starts
/// at its original start (the first at 0, absorbing anything the block walk missed) and
/// ends at the next block's start.
fn build_extended_ranges(original: &[Range<usize>], total_bytes: usize) -> Vec<Range<usize>> {
    if original.is_empty() {
        if total_bytes > 0 {
            #[allow(clippy::single_range_in_vec_init)]
            return vec![0..total_bytes];
        }
        return Vec::new();
    }
    let n = original.len();
    let mut out = Vec::with_capacity(n);
    for i in 0..n {
        let start = if i == 0 { 0 } else { original[i].start };
        let end = if i + 1 < n {
            original[i + 1].start
        } else {
            total_bytes.max(original[i].end)
        };
        let start = start.min(end);
        out.push(start..end);
    }
    out
}

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

    fn theme() -> &'static Theme {
        Box::leak(Box::new(Theme::default()))
    }

    #[test]
    fn build_single_paragraph() {
        let doc = ParsedDoc::build("Hello world\n", theme(), false, 24);
        assert!(!doc.lines.is_empty());
        assert!(doc.source_map.block_count() >= 1);
    }

    #[test]
    fn build_heading_and_paragraph() {
        let src = "# Heading\n\nParagraph text\n";
        let doc = ParsedDoc::build(src, theme(), false, 24);
        assert!(doc.line_count() >= 2);
        let heading_range = doc.source_map.rendered_lines_for_byte(2);
        assert!(!heading_range.is_empty());
        let para_range = doc.source_map.rendered_lines_for_byte(src.len() - 3);
        assert!(!para_range.is_empty());
    }

    #[test]
    fn every_byte_maps_to_some_line() {
        let src = "# Hello\n\nWorld\n\n---\n";
        let doc = ParsedDoc::build(src, theme(), false, 24);
        for b in 0..src.len() {
            let range = doc.source_map.rendered_lines_for_byte(b);
            assert!(
                !range.is_empty(),
                "byte {} ('{:?}') did not map to any rendered line",
                b,
                src.as_bytes().get(b)
            );
        }
    }

    /// One blank line matches the count ropey reports for `""`.  With zero lines the
    /// rendered views painted nothing and the cursor was invisible outside raw mode.
    #[test]
    fn empty_doc_owns_one_blank_line_for_the_cursor() {
        let doc = ParsedDoc::build("", theme(), false, 24);
        assert_eq!(doc.line_count(), 1);
        assert_eq!(doc.source_map.block_for_byte(0), Some(0));
        assert!(!doc.source_map.rendered_lines_for_byte(0).is_empty());
    }

    #[test]
    fn detect_setext_recognises_h1_and_h2() {
        assert_eq!(detect_setext("Title\n=====\n"), Some(SetextKind::H1));
        assert_eq!(detect_setext("Title\n-----\n"), Some(SetextKind::H2));
    }

    #[test]
    fn detect_setext_rejects_atx() {
        assert_eq!(detect_setext("# Title\n"), None);
        assert_eq!(detect_setext("## Title\n"), None);
    }

    #[test]
    fn detect_setext_requires_underline() {
        assert_eq!(detect_setext("Only one line"), None);
        assert_eq!(detect_setext("Title\nbody\n"), None);
    }

    /// An image-only paragraph promotes to a `Block::ImageBlock` reserving
    /// `image_max_height` rows, so visual motion traverses it like any multi-line block.
    #[test]
    fn image_paragraph_promotes_and_reserves_rows() {
        let src = "Above.\n\n![cat](local.png)\n\nBelow.\n";
        let doc = ParsedDoc::build(src, theme(), true, 10);
        let image_byte = src.find('!').expect("image exists");
        let image_block = doc.source_map.block_for_byte(image_byte).unwrap();
        assert_eq!(doc.block_own_line_count(image_block), 10);
    }

    /// A paragraph holding only `$$...$$` display math must be promoted to
    /// an image block (phase 1 block-math design), so the renderer can
    /// reserve multi-row space for the rasterized formula exactly like a
    /// diagram or image block.
    #[test]
    fn display_math_paragraph_promotes_to_image_block() {
        let src = "Above.\n\n$$\nx^2 + y^2 = z^2\n$$\n\nBelow.\n";
        let doc = ParsedDoc::build(src, theme(), true, 10);
        let math_byte = src.find("$$").expect("math exists");
        let math_block = doc
            .source_map
            .block_for_byte(math_byte)
            .expect("math block exists in source map");
        assert!(
            doc.is_image_block(math_block),
            "a $$...$$-only paragraph must promote to an image block (block {}); blocks: {:?}",
            math_block,
            doc.blocks
        );
    }

    /// The promotion must carry the LaTeX source through to
    /// `ImageBlockInfo` (via the diagram-sources map) so the decode worker
    /// can render the formula — same contract mermaid blocks rely on.
    #[test]
    fn promoted_math_block_carries_latex_source() {
        let src = "$$\nE = mc^2\n$$\n";
        let doc = ParsedDoc::build(src, theme(), true, 10);
        let math_blocks: Vec<_> = doc
            .image_blocks
            .iter()
            .filter(|info| matches!(info.source, Some(crate::diagram::DiagramSource::Latex(_))))
            .collect();
        assert_eq!(math_blocks.len(), 1, "image_blocks: {:?}", doc.image_blocks);
        assert!(
            matches!(&math_blocks[0].source, Some(crate::diagram::DiagramSource::Latex(s)) if s.trim() == "E = mc^2"),
            "latex source must be preserved: {:?}",
            math_blocks[0].source
        );
        assert!(
            math_blocks[0].url.starts_with("diagram-math-"),
            "synthetic math url expected: {}",
            math_blocks[0].url
        );
    }

    /// Regression: pulldown-cmark refuses to close a `$$...$$` span whose body has an unbalanced
    /// `{`, so a half-typed `x^{123` degrades to plain text and the block loses its reserved rows
    /// mid-typing.  `reconstruct_broken_display_math` rescues it: the block must still promote to a
    /// Latex image block (whose render then fails cleanly), so the figure stays reserved while the
    /// braces are open.
    #[test]
    fn broken_brace_math_still_promotes_to_a_reserved_image_block() {
        for src in ["$$\nx^2 = z^{123\n$$\n", "$$x^2 = z^{123$$\n"] {
            let doc = ParsedDoc::build(src, theme(), true, 10);
            let math_blocks: Vec<_> = doc
                .image_blocks
                .iter()
                .filter(|info| matches!(info.source, Some(crate::diagram::DiagramSource::Latex(_))))
                .collect();
            assert_eq!(
                math_blocks.len(),
                1,
                "an unbalanced-brace formula must still reserve an image block for {src:?}; blocks: {:?}",
                doc.blocks
            );
            assert!(
                matches!(&math_blocks[0].source, Some(crate::diagram::DiagramSource::Latex(s)) if s.contains("z^{123")),
                "the raw (invalid) latex must be carried through for {src:?}: {:?}",
                math_blocks[0].source
            );
        }
    }

    /// A paragraph that merely mentions dollar signs — not a lone `$$...$$` block — must NOT be
    /// dragged into display math by the brace-repair pass.
    #[test]
    fn brace_repair_leaves_ordinary_prose_alone() {
        for src in [
            "It cost $$5 and change.\n",            // no closing pair shape
            "$$a$$ then prose then $$b{$$\n",       // interior `$$`: multiple / mixed
            "Prose then $$x^{1$$ trailing words\n", // not delimited end to end
        ] {
            let doc = ParsedDoc::build(src, theme(), true, 10);
            let math_blocks = doc
                .image_blocks
                .iter()
                .filter(|info| matches!(info.source, Some(crate::diagram::DiagramSource::Latex(_))))
                .count();
            assert_eq!(
                math_blocks, 0,
                "prose wrongly promoted for {src:?}: {:?}",
                doc.blocks
            );
        }
    }

    /// Display math is gated on the same consent switch as diagrams. With
    /// `promote_diagrams = false` (the user declined the figures prompt, or
    /// set `[figures].enabled = "never"`) a `$$...$$` paragraph is NOT
    /// promoted to an image block — it stays a paragraph and renders as its
    /// literal source, the way a declined mermaid fence stays a code block.
    /// Regression for the promotion that used to ignore the setting.
    #[test]
    fn display_math_is_not_promoted_when_figures_disabled() {
        let src = "$$\nE = mc^2\n$$\n";
        let doc = ParsedDoc::build_with_overrides(
            src,
            theme(),
            true,
            10,
            None,
            None,
            false,
            80,
            false,
            false,
            /* promote_diagrams */ false,
            /* reflow_paragraphs */ false,
            None,
        );
        assert!(
            doc.image_blocks.is_empty(),
            "no image block should be promoted with figures disabled: {:?}",
            doc.blocks
        );
        // With figures off the `$$...$$` paragraph renders as a
        // fenced-style ` math ` code block (not inline code, not an image):
        // a ` math ` header, the formula body, and a blank closing row.
        // The `$$` delimiters are hidden here and reveal only under the
        // cursor.
        let rendered: String = doc
            .lines
            .iter()
            .flat_map(|l| l.spans.iter().map(|s| s.content.as_ref()))
            .collect();
        assert!(
            rendered.contains("E = mc^2"),
            "the formula body must stay visible when figures are disabled: {rendered:?}"
        );
        assert!(
            rendered.contains("math"),
            "the block must carry a ` math ` header: {rendered:?}"
        );
        assert!(
            !rendered.contains("$$"),
            "the styled block hides the `$$` delimiters (they reveal on cursor): {rendered:?}"
        );
    }

    #[test]
    fn setext_h2_has_two_rendered_lines() {
        let src = "Heading\n-------\n";
        let doc = ParsedDoc::build(src, theme(), false, 24);
        let block = doc.source_map.block_for_byte(0).unwrap();
        assert_eq!(doc.block_own_line_count(block), 2);
    }

    /// The reveal classification: mermaid and `$$...$$` math blocks are
    /// both multi-line diagram images whose raw source must paint 1:1
    /// over the reserved rows on cursor reveal — ordinary `![alt](url)`
    /// images are single-line and stay on the generic image path.
    #[test]
    fn diagram_reveal_classification_covers_latex_and_mermaid_only() {
        let src = "![logo](logo.png)\n\n\
                   ```mermaid\ngraph TD\nA-->B\n```\n\n\
                   $$\nE = mc^2\n$$\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);
        let latex = doc
            .image_blocks
            .iter()
            .find(|i| matches!(i.source, Some(crate::diagram::DiagramSource::Latex(_))))
            .expect("latex block")
            .block_idx;
        let mermaid = doc
            .image_blocks
            .iter()
            .find(|i| matches!(i.source, Some(crate::diagram::DiagramSource::Mermaid(_))))
            .expect("mermaid block")
            .block_idx;
        let plain = doc
            .image_blocks
            .iter()
            .find(|i| i.source.is_none())
            .expect("plain image block")
            .block_idx;

        assert!(doc.is_latex_block(latex));
        assert!(doc.is_diagram_reveal_block(latex));
        assert!(!doc.is_mermaid_block(latex));

        assert!(doc.is_mermaid_block(mermaid));
        assert!(doc.is_diagram_reveal_block(mermaid));
        assert!(!doc.is_latex_block(mermaid));

        assert!(!doc.is_latex_block(plain));
        assert!(!doc.is_mermaid_block(plain));
        assert!(!doc.is_diagram_reveal_block(plain));
    }

    /// Two `$$...$$` blocks stacked with no blank line between them (the
    /// common pattern in math documents) must each promote to their own
    /// image block.  pulldown-cmark may fold them into one paragraph with
    /// two DisplayMath events plus a soft break — the promotion must
    /// handle that shape, not only a paragraph holding a single math.
    #[test]
    fn adjacent_display_math_paragraphs_each_promote() {
        let src = "$$\nX = \\begin{bmatrix} 1 & 2 \\end{bmatrix}\n$$\n\
                   $$\nA = \\begin{bmatrix} 1 & 2 & 3 & 4 \\end{bmatrix}\n$$\n";
        let doc = ParsedDoc::build(src, theme(), true, 10);
        let math_blocks: Vec<_> = doc
            .image_blocks
            .iter()
            .filter(|info| matches!(info.source, Some(crate::diagram::DiagramSource::Latex(_))))
            .collect();
        assert_eq!(
            math_blocks.len(),
            2,
            "each stacked $$...$$ block must promote; blocks: {:?}",
            doc.blocks
        );
        // Sources preserved in document order.
        let sources: Vec<&str> = math_blocks
            .iter()
            .map(|info| match &info.source {
                Some(crate::diagram::DiagramSource::Latex(s)) => s.trim(),
                _ => "",
            })
            .collect();
        assert!(sources[0].contains("X ="), "first source: {sources:?}");
        assert!(sources[1].contains("A ="), "second source: {sources:?}");
    }

    /// With figures OFF the same stacked pair (folded by pulldown into one
    /// paragraph) must still split into two separate blocks, each rendering
    /// as its own fenced-style ` math ` code block — not one merged block,
    /// and not inline code.
    #[test]
    fn adjacent_display_math_paragraphs_split_when_figures_off() {
        let src = "$$\nX = 1\n$$\n$$\nA = 2\n$$\n";
        let doc = ParsedDoc::build_with_overrides(
            src,
            theme(),
            true,
            10,
            None,
            None,
            false,
            80,
            false,
            false,
            /* promote_diagrams */ false,
            /* reflow_paragraphs */ false,
            None,
        );
        // Nothing is promoted to an image with figures off.
        assert!(doc.image_blocks.is_empty(), "blocks: {:?}", doc.blocks);
        // Two separate `math` code blocks: two ` math ` header rows, both
        // formula bodies present, and no literal `$$` in the rendered lines
        // (delimiters reveal only under the cursor).
        let rendered: String = doc
            .lines
            .iter()
            .map(|l| {
                l.spans
                    .iter()
                    .map(|s| s.content.as_ref())
                    .collect::<String>()
            })
            .collect::<Vec<_>>()
            .join("\n");
        assert_eq!(
            rendered.matches("math").count(),
            2,
            "expected two ` math ` headers: {rendered:?}"
        );
        assert!(
            rendered.contains("X = 1") && rendered.contains("A = 2"),
            "{rendered:?}"
        );
        assert!(
            !rendered.contains("$$"),
            "delimiters must be hidden: {rendered:?}"
        );
    }

    #[test]
    fn setext_h1_has_two_rendered_lines() {
        let src = "Heading\n=======\n";
        let doc = ParsedDoc::build(src, theme(), false, 24);
        let block = doc.source_map.block_for_byte(0).unwrap();
        assert_eq!(doc.block_own_line_count(block), 2);
    }

    /// A blank line needs its own virtual block or the cursor cannot land on it.
    #[test]
    fn blank_line_is_its_own_block() {
        let src = "First\n\nSecond\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);

        let first_block = doc.source_map.block_for_byte(2); // inside "First"
        let blank_block = doc.source_map.block_for_byte(6); // the blank line
        let second_block = doc.source_map.block_for_byte(9); // inside "Second"

        assert!(first_block.is_some() && blank_block.is_some() && second_block.is_some());
        assert_ne!(
            first_block, blank_block,
            "blank line must not share a block with preceding paragraph"
        );
        assert_ne!(
            blank_block, second_block,
            "blank line must not share a block with following paragraph"
        );
    }

    /// Navigating consecutive blank lines must land on each in turn.
    #[test]
    fn multiple_blank_lines_each_own_block() {
        let src = "A\n\n\n\nB\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);

        // The blank-line newlines are at bytes 2, 3, 4.
        let b2 = doc.source_map.block_for_byte(2).unwrap();
        let b3 = doc.source_map.block_for_byte(3).unwrap();
        let b4 = doc.source_map.block_for_byte(4).unwrap();
        assert_ne!(b2, b3);
        assert_ne!(b3, b4);
    }

    /// See the phantom-final-line note in `build_with_overrides`.
    #[test]
    fn phantom_final_line_owns_its_own_block() {
        let src = "Alpha\n\nBeta\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);
        let beta_block = doc.source_map.block_for_byte(src.find("Beta").unwrap());
        let phantom_block = doc.source_map.block_for_byte(src.len());
        assert!(beta_block.is_some() && phantom_block.is_some());
        assert_ne!(
            beta_block, phantom_block,
            "cursor at end of source must not share the last real block"
        );
        let range = doc
            .source_map
            .rendered_lines_for_block(phantom_block.unwrap());
        assert_eq!(range, doc.line_count() - 1..doc.line_count());
        let text: String = doc.lines[range.start]
            .spans
            .iter()
            .map(|s| s.content.as_ref())
            .collect();
        assert!(
            text.is_empty(),
            "phantom line must render blank, got {text:?}"
        );
    }

    /// No phantom block without a trailing newline.
    #[test]
    fn no_phantom_block_without_trailing_newline() {
        let src = "Alpha\n\nBeta";
        let doc = ParsedDoc::build(src, theme(), true, 24);
        let beta_block = doc.source_map.block_for_byte(src.find("Beta").unwrap());
        let end_block = doc.source_map.block_for_byte(src.len());
        assert_eq!(
            beta_block, end_block,
            "cursor at end of an unterminated line stays in that line's block"
        );
    }

    /// Regression: the merge pass must run before the live-widths override, or the
    /// `tui-columns` comment flashes into the rendered view on every drag event.
    #[test]
    fn live_widths_preview_still_hides_trailing_tui_columns_comment() {
        let src = "| a | b |\n|---|---|\n| 1 | 2 |\n<!-- tui-columns: [5, 6] -->\n";
        let live = (0usize, vec![Some(7), None]);
        let doc = ParsedDoc::build_with_overrides(
            src,
            theme(),
            true,
            24,
            Some(&live),
            None,
            false,
            80,
            false,
            false,
            true,
            false,
            None,
        );
        for line in &doc.lines {
            let text: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
            assert!(
                !text.contains("tui-columns"),
                "comment leaked into rendered output: {text:?}"
            );
        }
    }

    #[test]
    fn gfm_slug_basic_cases() {
        assert_eq!(gfm_slug("Hello, World!"), "hello-world");
        assert_eq!(gfm_slug("Foo"), "foo");
        assert_eq!(gfm_slug("  spaces   here  "), "-spaces-here-");
        // The three letters are stripped, leaving two whitespace runs and so two dashes.
        assert_eq!(gfm_slug("α β γ"), "--");
        assert_eq!(gfm_slug("API v2 — Release Notes"), "api-v2--release-notes");
        assert_eq!(gfm_slug("Hello World"), "hello-world");
    }

    #[test]
    fn uniquify_slug_appends_suffix_on_collision() {
        let mut counts = HashMap::new();
        assert_eq!(uniquify_slug("foo", &mut counts), "foo");
        assert_eq!(uniquify_slug("foo", &mut counts), "foo-1");
        assert_eq!(uniquify_slug("foo", &mut counts), "foo-2");
        assert_eq!(uniquify_slug("bar", &mut counts), "bar");
    }

    #[test]
    fn heading_anchors_has_one_entry_per_heading() {
        let src = "# First\n\nPara.\n\n## Second Heading\n\nMore.\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);
        assert!(doc.heading_anchors.contains_key("first"));
        assert!(doc.heading_anchors.contains_key("second-heading"));
        let doc2 = ParsedDoc::build(src, theme(), true, 24);
        assert_eq!(doc.heading_anchors, doc2.heading_anchors);
    }

    #[test]
    fn heading_anchors_uniquify_on_collision() {
        let src = "# Foo\n\n## Foo\n\n### Foo\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);
        assert!(doc.heading_anchors.contains_key("foo"));
        assert!(doc.heading_anchors.contains_key("foo-1"));
        assert!(doc.heading_anchors.contains_key("foo-2"));
    }

    #[test]
    fn footnote_anchors_map_label_to_definition_line() {
        let src = "Intro.[^1]\n\nMiddle.\n\n[^1]: The note.\n";
        let doc = ParsedDoc::build(src, theme(), true, 40);
        let &line = doc
            .footnote_anchors
            .get("1")
            .expect("footnote_anchors should contain label '1'");
        let rendered = doc.lines[line]
            .spans
            .iter()
            .map(|s| s.content.as_ref())
            .collect::<String>();
        assert!(
            rendered.contains("The note."),
            "anchor line should be the definition, got: {rendered:?}"
        );
    }

    #[test]
    fn heading_anchor_indexes_point_to_rendered_heading_line() {
        let src = "Intro paragraph.\n\n# Target\n\nBody.\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);
        let &idx = doc
            .heading_anchors
            .get("target")
            .expect("heading anchor present");
        let target_byte = src.find("Target").unwrap();
        let heading_lines = doc.source_map.rendered_lines_for_byte(target_byte);
        assert!(
            heading_lines.contains(&idx),
            "anchor {} points to line {} but heading spans {:?}",
            "target",
            idx,
            heading_lines
        );
    }

    // ── Visual-row cache ────────────────────────────────────────────────

    /// The cache must agree with `line_render::visual_rows_for_line` on every line.
    #[test]
    fn visual_rows_cache_matches_line_render() {
        let long = "x".repeat(120);
        let src = format!("# Title\n\nshort\n\n{long}\n\nfinal\n");
        let doc = ParsedDoc::build(&src, theme(), true, 24);
        let width = 40;
        for (i, line) in doc.lines.iter().enumerate() {
            let canonical = crate::ui::line_render::visual_rows_for_line(line, width).max(1);
            assert_eq!(
                doc.visual_rows_for_line_at(i, width),
                canonical,
                "cache mismatch at line {i}",
            );
        }
    }

    /// The prefix-sum invariant the snapshot builders rely on.
    #[test]
    fn visual_rows_before_is_prefix_sum() {
        let src = "Para one.\n\n```\ncode\nblock\n```\n\n| a | b |\n|---|---|\n| 1 | 2 |\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);
        let width = 30;
        for i in 0..doc.lines.len() {
            assert_eq!(
                doc.visual_rows_before(i + 1, width),
                doc.visual_rows_before(i, width) + doc.visual_rows_for_line_at(i, width),
                "prefix-sum invariant broken at line {i}",
            );
        }
    }

    /// A → B → A must answer correctly each time: the width-mismatch rebuild path.
    #[test]
    fn visual_rows_cache_invalidates_on_width_change() {
        let long = "y".repeat(80);
        let src = format!("Hello\n\n{long}\n");
        let doc = ParsedDoc::build(&src, theme(), true, 24);
        let expect = |w: usize| -> Vec<usize> {
            doc.lines
                .iter()
                .map(|l| crate::ui::line_render::visual_rows_for_line(l, w).max(1))
                .collect()
        };
        let at_40 = expect(40);
        let at_60 = expect(60);
        for (i, want) in at_40.iter().enumerate() {
            assert_eq!(doc.visual_rows_for_line_at(i, 40), *want);
        }
        for (i, want) in at_60.iter().enumerate() {
            assert_eq!(doc.visual_rows_for_line_at(i, 60), *want);
        }
        for (i, want) in at_40.iter().enumerate() {
            assert_eq!(doc.visual_rows_for_line_at(i, 40), *want);
        }
    }

    #[test]
    fn visual_rows_between_matches_manual_sum() {
        let src = "alpha\n\nbeta\n\ngamma\n\ndelta\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);
        let width = 50;
        let n = doc.lines.len();
        for first in 0..n {
            for last in first..n {
                let expected: usize = (first..=last)
                    .map(|i| doc.visual_rows_for_line_at(i, width))
                    .sum();
                assert_eq!(
                    doc.visual_rows_between(first, last, width),
                    expected,
                    "between({first}, {last}) mismatch",
                );
            }
        }
    }

    // ── HTML-comment hiding ──────────────────────────────────────────────

    /// A comment block's `per_block_own` must be 0, so navigation can detect it as hidden
    /// without inspecting the AST variant.
    #[test]
    fn html_comment_block_owns_zero_rendered_lines() {
        let src = "Alpha.\n\n<!-- hidden -->\n\nBeta.\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);
        assert!(
            doc.blocks
                .iter()
                .any(|b| matches!(b, Block::HtmlComment(_))),
            "blocks: {:?}",
            doc.blocks
        );
        let comment_byte = src.find("<!--").unwrap();
        let block_idx = doc
            .source_map
            .block_for_byte(comment_byte)
            .expect("comment bytes must map to a block");
        assert_eq!(doc.block_own_line_count(block_idx), 0);
        for line in &doc.lines {
            let text: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
            assert!(
                !text.contains("<!--"),
                "comment leaked into rendered output: {text:?}"
            );
        }
    }

    /// Regression guard: a parser refactor once changed the variant the merge looks for.
    #[test]
    fn tui_columns_still_absorbed_through_parsed_doc() {
        let src = "| a | b |\n|---|---|\n| 1 | 2 |\n<!-- tui-columns: [10, 20] -->\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);
        assert!(matches!(
            doc.blocks.first(),
            Some(Block::Table {
                user_widths: Some(_),
                ..
            })
        ));
        assert!(
            !doc.blocks
                .iter()
                .any(|b| matches!(b, Block::HtmlComment(_))),
            "comment should have been absorbed: {:?}",
            doc.blocks
        );
    }

    /// A blank line's rendered range must be that line, not the preceding block's last.
    #[test]
    fn blank_line_rendered_range_is_blank_line() {
        let src = "First\n\nSecond\n";
        let doc = ParsedDoc::build(src, theme(), true, 24);

        let first_range = doc.source_map.rendered_lines_for_byte(2);
        let blank_range = doc.source_map.rendered_lines_for_byte(6);
        let second_range = doc.source_map.rendered_lines_for_byte(9);

        assert!(!first_range.is_empty());
        assert!(!blank_range.is_empty());
        assert!(!second_range.is_empty());
        assert!(first_range.end <= blank_range.start);
        assert!(blank_range.end <= second_range.start);
        for idx in blank_range.clone() {
            let line = &doc.lines[idx];
            let text: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
            assert!(
                text.is_empty(),
                "expected blank rendered line at index {idx}, got {text:?}"
            );
        }
    }
}