markdown/

edit.rs

//! Editing a [`Doc`].
//!
//! This is the half of a block editor that has nothing to do with gpui: text
//! goes in and out of a [`Text`], marks move with it, and blocks split, merge
//! and indent. Keeping it pure is what makes it testable — the guarantee below
//! is checked over generated edit sequences, not over the handful of cases
//! anyone thinks to write down.
//!
//! **The guarantee is [`crate::serialize`]'s, preserved.** Call
//! [`Doc::normalize`] and the document round-trips: serialize, parse, and
//! nothing moves. An editor that can reach a state its own serializer cannot
//! express is an editor that corrupts the file on save, and no amount of UI
//! polish recovers from that.
//!
//! Normalizing is a *save* step rather than a keystroke step, and deliberately.
//! Markdown cannot hold a space at the end of a line, but stripping one the
//! moment it is typed takes it away mid-word — so the model carries it and
//! sheds it on the way out, which is what every editor that writes markdown
//! does.
//!
//! Marks are **left-sticky**: text typed at the end of a bold run is bold, text
//! typed at its start is not. The caret inherits formatting from the character
//! before it, which is what every editor does and what nobody notices until it
//! is wrong.

use std::ops::Range;

mod shortcut;
mod text;

pub use shortcut::*;

use crate::{
    doc::{
        Block, BlockKind, Doc, Mark, MarkSpan, Part, QuoteKind, Quoted, Run, Runs, Text, quote_runs,
    },
    select::{Cursor, Selection},
};

/// What a [`Doc::replace`] did, for anything holding a position it moved.
///
/// The caret is [`Doc::replace`]'s own answer and every caller wants it. The
/// other two are for a caller keeping a position of its own — a comment anchor,
/// a bookmark into the document — which has no other way to learn that the text
/// under it shifted.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Splice {
    /// What the call covered, clamped and in document order.
    pub removed: Selection,
    /// Where the caret landed: the end of what went in.
    pub caret: Cursor,
    /// The change in block count, which every block after [`Self::removed`]
    /// moves by.
    pub blocks: isize,
}

impl Doc {
    /// Split block `ix` at byte offset `at`, returning the new block's index.
    ///
    /// The tail keeps the block's kind where a continued Enter means "another of
    /// these" — a list item, for example; anything else continues as body
    /// text. Both halves keep the block's indent and quote. At the start of a
    /// block holding text the block moves down whole, under an empty one of the
    /// same list kind or an empty paragraph, and the returned index is the
    /// block.
    pub fn split(&mut self, ix: usize, at: usize) -> usize {
        if ix >= self.blocks.len() {
            return ix;
        }
        let (indent, quote) = (self.blocks[ix].indent, self.blocks[ix].quote);
        if at == 0
            && self.blocks[ix]
                .text_at(Part::Body)
                .is_some_and(|text| !text.text.is_empty())
        {
            let above = match &self.blocks[ix].kind {
                BlockKind::Bullet(_) => BlockKind::Bullet(Text::default()),
                BlockKind::Ordered { .. } => BlockKind::Ordered {
                    number: 1,
                    text: Text::default(),
                },
                BlockKind::Task { .. } => BlockKind::Task {
                    checked: false,
                    text: Text::default(),
                },
                _ => BlockKind::Paragraph(Text::default()),
            };
            self.blocks.insert(
                ix,
                Block {
                    quote,
                    ..Block::at(above, indent)
                },
            );
            self.repair();
            return ix + 1;
        }
        // Nothing to cut for a block with no body — Enter after an atomic
        // block opens a paragraph.
        let tail = self.blocks[ix]
            .text_at_mut(Part::Body)
            .map(|text| text.split_off(at))
            .unwrap_or_default();
        let kind = match &self.blocks[ix].kind {
            BlockKind::Bullet(_) => BlockKind::Bullet(tail),
            BlockKind::Ordered { .. } => BlockKind::Ordered {
                number: 1,
                text: tail,
            },
            BlockKind::Task { .. } => BlockKind::Task {
                checked: false,
                text: tail,
            },
            _ => BlockKind::Paragraph(tail),
        };
        self.blocks.insert(
            ix + 1,
            Block {
                quote,
                ..Block::at(kind, indent)
            },
        );
        self.repair();
        ix + 1
    }

    /// Take one layer off block `ix`, outermost first: the syntax around its
    /// text, then its quote, then a level of indent. `false` when the block
    /// has none of them left.
    ///
    /// Backspace at the start of a block, and Enter in an empty one.
    pub fn peel(&mut self, ix: usize) -> bool {
        let Some(block) = self.blocks.get(ix) else {
            return false;
        };
        // Every prefix [`shortcut`] reads is chrome around text; the first
        // backspace takes the chrome and leaves the text where it was, so what
        // can be typed in can be typed out.
        let unwrapped = match &block.kind {
            kind if is_marker(kind) => block.text_at(Part::Body).cloned(),
            BlockKind::Heading { text, .. } => Some(text.clone()),
            BlockKind::Code { code, .. } => Some(code.clone()),
            _ => None,
        };
        if let Some(text) = unwrapped {
            self.blocks[ix].kind = BlockKind::Paragraph(text);
        } else if block.quote.is_some() {
            self.blocks[ix].quote = None;
        } else if block.indent > 0 {
            self.shift_subtree(ix, -1);
        } else {
            return false;
        }
        self.repair();
        true
    }

    /// Quote block `ix`, or take it out of its quote with `None`.
    pub fn set_quote(&mut self, ix: usize, quote: Option<Quoted>) {
        let Some(block) = self.blocks.get_mut(ix) else {
            return;
        };
        block.quote = quote;
        self.repair();
    }

    /// What picking a quote does to block `ix`: one it is already in with this
    /// alert takes it out, a quote with another alert takes this one across
    /// the whole blockquote, and a block outside a quote goes in.
    pub fn toggle_quote(&mut self, ix: usize, alert: Option<QuoteKind>) {
        match self.blocks.get(ix).and_then(|block| block.quote) {
            Some(quote) if quote.alert == alert => self.set_quote(ix, None),
            Some(_) => self.set_alert(ix, alert),
            None => self.set_quote(ix, Some(Quoted { alert })),
        }
    }

    /// Give the whole blockquote block `ix` sits in the alert `alert`. Nothing
    /// for a block outside a quote.
    pub fn set_alert(&mut self, ix: usize, alert: Option<QuoteKind>) {
        let runs = quote_runs(self.blocks.iter().map(|block| (block.quote, block.indent)));
        let Some(Some(_)) = runs.get(ix) else {
            return;
        };
        let start = (0..=ix)
            .rev()
            .find(|&at| runs[at].is_some_and(|run| run.first))
            .unwrap_or(ix);
        let end = (ix + 1..runs.len())
            .find(|&at| runs[at].is_none_or(|run| run.first))
            .unwrap_or(runs.len());
        for block in &mut self.blocks[start..end] {
            block.quote = Some(Quoted { alert });
        }
        self.repair();
    }

    /// Backspace at the start of a block.
    ///
    /// Notion's chain, in order: the block [`Doc::peel`]s, an image with
    /// nothing written under it goes, and only a plain block at the left
    /// margin merges into the one above it. When that one holds no body there
    /// is nothing to merge into, so the caret steps into a fence or a table,
    /// and a rule — which no caret can enter, and so no other key can remove —
    /// goes. Returns where the caret landed, and `None` when nothing moved.
    ///
    /// A table cell is not a position that can swallow its neighbour, so
    /// backspace at the start of one does nothing rather than eating the table.
    pub fn merge_back(&mut self, at: Cursor) -> Option<Cursor> {
        if matches!(at.part, Part::Cell { .. }) {
            return None;
        }
        if self.peel(at.block) {
            let parts = self.blocks[at.block].parts();
            let part = if parts.contains(&at.part) {
                at.part
            } else {
                Part::Body
            };
            return Some(Cursor::new(at.block, part, 0));
        }
        let block = self.blocks.get(at.block)?;
        // A caption is the only handle a caret has on an image, so with the
        // caption empty there is nothing left to take but the picture.
        if at.part == Part::Caption && block.text_at(Part::Caption)?.is_empty() {
            let previous = at.block.checked_sub(1);
            self.blocks.remove(at.block);
            self.repair();
            let Some(previous) = previous else {
                return Some(Cursor::default().clamp(self));
            };
            let part = self.blocks[previous]
                .parts()
                .last()
                .copied()
                .unwrap_or_default();
            return Some(Cursor::new(previous, part, 0).end(self));
        }
        if at.block == 0 {
            return None;
        }
        let tail = self.blocks[at.block].text_at(Part::Body)?.clone();
        let previous = at.block - 1;
        match self.blocks[previous].parts().last().copied() {
            // Only two blocks that both hold a body can become one.
            Some(Part::Body) => {
                let head = self.blocks[previous].text_at_mut(Part::Body)?;
                let caret = head.text.len();
                head.append(tail);
                self.blocks.remove(at.block);
                self.repair();
                Some(Cursor::new(previous, Part::Body, caret))
            }
            Some(part) => {
                let end = self.blocks[previous]
                    .text_at(part)
                    .map_or(0, |text| text.text.len());
                // Stepping into a fence, a caption or a cell leaves this block
                // where it is, which is right while it still holds something
                // and a trap once it does not: nothing above it merges, so a
                // block left empty here is one backspace can never reach again.
                if tail.is_empty() {
                    self.blocks.remove(at.block);
                    self.repair();
                }
                Some(Cursor::new(previous, part, end))
            }
            None => {
                self.blocks.remove(previous);
                self.repair();
                Some(Cursor::new(previous, at.part, at.offset))
            }
        }
    }

    /// Apply an edit to the text at `at`, then put the block back in order.
    ///
    /// The editor should reach text through here rather than mutating a block
    /// directly: a heading or a table cell that acquires a newline has no
    /// spelling, and nothing else is positioned to notice.
    pub fn edit_at(&mut self, at: Cursor, edit: impl FnOnce(&mut Text)) {
        let Some(block) = self.blocks.get_mut(at.block) else {
            return;
        };
        let one_line = matches!(block.kind, BlockKind::Heading { .. })
            || matches!(at.part, Part::Cell { .. } | Part::Caption);
        let Some(text) = block.text_at_mut(at.part) else {
            return;
        };
        edit(text);
        if one_line {
            crate::parse::collapse_to_one_line(text);
        }
    }

    /// The blocks nested under `ix`, `ix` included — what a move, a duplicate
    /// or a drag carries with it.
    ///
    /// A flat list makes this a scan for the next block that is not deeper,
    /// which is the whole argument for the flat list.
    pub fn subtree(&self, ix: usize) -> Range<usize> {
        let Some(base) = self.blocks.get(ix).map(|block| block.indent) else {
            return ix..ix;
        };
        let mut end = ix + 1;
        while self
            .blocks
            .get(end)
            .is_some_and(|block| block.indent > base)
        {
            end += 1;
        }
        ix..end
    }

    /// Move a block and its children to sit before or after their neighbour.
    ///
    /// `delta` counts *siblings*, not rows: moving down past a bullet with
    /// three children clears all four, or a block would land inside the run it
    /// was trying to step over.
    pub fn move_block(&mut self, ix: usize, delta: isize) -> Option<usize> {
        let span = self.subtree(ix);
        if span.is_empty() {
            return None;
        }
        let to = match delta {
            ..0 => {
                // The start of whichever subtree ends where this one begins.
                (0..span.start)
                    .rev()
                    .find(|&above| self.subtree(above).end == span.start)?
            }
            0.. => {
                let next = self.subtree(span.end);
                if next.is_empty() {
                    return None;
                }
                // Landing after the neighbour means landing where it ends,
                // less the hole this subtree leaves behind.
                next.end - span.len()
            }
        };
        let moved: Vec<Block> = self.blocks.drain(span.clone()).collect();
        self.blocks.splice(to..to, moved);
        self.repair();
        Some(to)
    }

    /// Copy a block and its children in below themselves.
    pub fn duplicate(&mut self, ix: usize) -> Option<usize> {
        let span = self.subtree(ix);
        if span.is_empty() {
            return None;
        }
        let copy: Vec<Block> = self.blocks[span.clone()].to_vec();
        self.blocks.splice(span.end..span.end, copy);
        self.repair();
        Some(span.end)
    }

    /// Delete a block and its children.
    pub fn remove_block(&mut self, ix: usize) {
        let span = self.subtree(ix);
        if span.is_empty() {
            return;
        }
        self.blocks.drain(span);
        self.repair();
    }

    /// Turn block `ix` into `kind`, carrying its text across and keeping its
    /// indent.
    ///
    /// The one operation a typed prefix, the slash menu and the block menu all
    /// perform, so none of them reaches into a block's kind on its own.
    pub fn set_kind(&mut self, ix: usize, kind: BlockKind) {
        let Some(block) = self.blocks.get_mut(ix) else {
            return;
        };
        let text = match &block.kind {
            // A bookmark's text is the link it shows, so turning one back into
            // prose hands the URL over instead of an empty block.
            BlockKind::Bookmark { url, .. } => Text::link(url),
            BlockKind::Image { alt, .. } => alt.clone(),
            _ => block.text_at(Part::Body).cloned().unwrap_or_default(),
        };
        block.kind = kind;
        match block.text_at_mut(Part::Body) {
            Some(body) => *body = text,
            // The two kinds whose text is not a body. Code is also the one the
            // marks cannot come with.
            None => match &mut block.kind {
                BlockKind::Code { code, .. } => *code = Text::plain(text.text),
                BlockKind::Image { alt, .. } => *alt = text,
                _ => {}
            },
        }
        self.repair();
    }

    /// The tag on a fenced block — what the label shows, what the highlighter
    /// reads, and what the info string carries. Not [`Doc::set_kind`]'s job:
    /// that carries a *body* across, and a fence has none to give back.
    /// Put an empty row in table `ix` before `row`, numbered as
    /// [`Part::Cell`] numbers rows (1 is the first body row), as wide as the
    /// widest row. `false` when `ix` is not a table.
    pub fn insert_row(&mut self, ix: usize, row: usize) -> bool {
        let Some(BlockKind::Table { header, rows, .. }) =
            self.blocks.get_mut(ix).map(|block| &mut block.kind)
        else {
            return false;
        };
        let width = rows
            .iter()
            .map(Vec::len)
            .chain([header.len(), 1])
            .max()
            .unwrap_or(1);
        let at = row.saturating_sub(1).min(rows.len());
        rows.insert(at, vec![Text::default(); width]);
        true
    }

    /// Put an empty, left-aligned column in table `ix` before `column`, in the
    /// header and every row. `false` when `ix` is not a table.
    pub fn insert_column(&mut self, ix: usize, column: usize) -> bool {
        let Some(BlockKind::Table {
            align,
            header,
            rows,
        }) = self.blocks.get_mut(ix).map(|block| &mut block.kind)
        else {
            return false;
        };
        for cells in std::iter::once(&mut *header)
            .filter(|header| !header.is_empty())
            .chain(rows.iter_mut())
        {
            cells.insert(column.min(cells.len()), Text::default());
        }
        align.insert(column.min(align.len()), crate::Align::Left);
        true
    }

    /// Take body row `row` ([`Part::Cell`] numbering) out of table `ix`.
    /// `false` for the header row, a row that is not there, or a block that
    /// is not a table.
    pub fn remove_row(&mut self, ix: usize, row: usize) -> bool {
        let Some(BlockKind::Table { rows, .. }) =
            self.blocks.get_mut(ix).map(|block| &mut block.kind)
        else {
            return false;
        };
        if row == 0 || row > rows.len() {
            return false;
        }
        rows.remove(row - 1);
        true
    }

    /// Take `column` out of table `ix`, from the header and every row.
    /// `false` for the last column left, or a block that is not a table.
    pub fn remove_column(&mut self, ix: usize, column: usize) -> bool {
        let Some(BlockKind::Table {
            align,
            header,
            rows,
        }) = self.blocks.get_mut(ix).map(|block| &mut block.kind)
        else {
            return false;
        };
        let width = rows
            .iter()
            .map(Vec::len)
            .chain([header.len()])
            .max()
            .unwrap_or(0);
        if width < 2 || column >= width {
            return false;
        }
        for cells in std::iter::once(&mut *header).chain(rows.iter_mut()) {
            if column < cells.len() {
                cells.remove(column);
            }
        }
        if column < align.len() {
            align.remove(column);
        }
        true
    }

    /// Move a body row to its final row index. The header stays at row zero.
    pub fn move_row(&mut self, ix: usize, from: usize, to: usize) -> bool {
        let Some(BlockKind::Table { rows, .. }) =
            self.blocks.get_mut(ix).map(|block| &mut block.kind)
        else {
            return false;
        };
        if from == to || from == 0 || to == 0 || from > rows.len() || to > rows.len() {
            return false;
        }
        let row = rows.remove(from - 1);
        rows.insert(to - 1, row);
        true
    }

    /// Move a column, including its header, alignment, and every body cell.
    pub fn move_column(&mut self, ix: usize, from: usize, to: usize) -> bool {
        let Some(BlockKind::Table {
            align,
            header,
            rows,
        }) = self.blocks.get_mut(ix).map(|block| &mut block.kind)
        else {
            return false;
        };
        let width = rows
            .iter()
            .map(Vec::len)
            .chain([header.len()])
            .max()
            .unwrap_or(0);
        if from == to || from >= width || to >= width {
            return false;
        }
        for cells in std::iter::once(&mut *header)
            .filter(|cells| !cells.is_empty())
            .chain(rows.iter_mut())
        {
            cells.resize(width, Text::default());
            let cell = cells.remove(from);
            cells.insert(to, cell);
        }
        align.resize(width, crate::Align::Left);
        let alignment = align.remove(from);
        align.insert(to, alignment);
        true
    }

    pub fn set_language(&mut self, ix: usize, language: Option<String>) {
        if let Some(BlockKind::Code { language: tag, .. }) =
            self.blocks.get_mut(ix).map(|block| &mut block.kind)
        {
            *tag = language;
        }
    }

    /// Replace a fenced block's code. Anything but a fence is left alone.
    pub fn set_code(&mut self, ix: usize, code: String) {
        if let Some(BlockKind::Code { code: held, .. }) =
            self.blocks.get_mut(ix).map(|block| &mut block.kind)
        {
            *held = Text::plain(code);
        }
    }

    /// Turn what a selection covers into one code block, leaving whatever it
    /// did not cover as blocks of its own.
    ///
    /// The fence is what markdown has for code over more than one line. An
    /// inline span is not: no CommonMark spelling puts a line break inside
    /// backticks, so one written that way comes back as a space.
    ///
    /// Marks are dropped on the way in, the way [`Doc::set_kind`] drops them
    /// when it turns a block into a fence — code is literal to its closing
    /// fence, and nothing in it is markup.
    pub fn fence(&mut self, selection: Selection) -> Cursor {
        let lines: Vec<String> = self
            .spans(selection)
            .iter()
            .filter(|(at, _)| at.part == Part::Body)
            .filter_map(|(at, range)| {
                let text = self.blocks[at.block].text_at(at.part)?;
                text.text.get(range.clone()).map(str::to_string)
            })
            .collect();
        if lines.is_empty() {
            return selection.head.clamp(self);
        }
        let code = Text::plain(lines.join("\n"));

        // Cutting the selection leaves the head and the tail it did not cover
        // joined in one block, with the caret at the seam between them — which
        // is where the fence goes.
        let at = self.replace(selection, Text::default()).caret;
        let tail = self.split(at.block, at.offset);
        let (indent, quote) = (self.blocks[at.block].indent, self.blocks[at.block].quote);
        self.blocks.insert(
            tail,
            Block {
                quote,
                ..Block::at(
                    BlockKind::Code {
                        language: None,
                        code,
                        height: None,
                    },
                    indent,
                )
            },
        );
        // A selection that covered whole blocks leaves nothing on either side,
        // and an empty paragraph is not what "turn this into code" asked for.
        let empty = |block: &Block| {
            block
                .text_at(Part::Body)
                .is_some_and(|text| text.text.is_empty())
        };
        if self.blocks.get(tail + 1).is_some_and(empty) {
            self.blocks.remove(tail + 1);
        }
        let mut fence = tail;
        if empty(&self.blocks[at.block]) {
            self.blocks.remove(at.block);
            fence -= 1;
        }
        self.repair();
        Cursor::new(fence, Part::Code, 0).clamp(self)
    }

    /// The way back out of a fence: every line becomes a paragraph. `None` when
    /// the selection is not all code, which is what makes this the other half
    /// of a toggle rather than an operation of its own.
    pub fn unfence(&mut self, selection: Selection) -> Option<Cursor> {
        let (start, end) = selection.clamp(self).ordered();
        let blocks = start.block..=end.block;
        if !blocks
            .clone()
            .all(|ix| matches!(self.blocks[ix].kind, BlockKind::Code { .. }))
        {
            return None;
        }
        for ix in blocks.rev() {
            let BlockKind::Code { code, .. } = &self.blocks[ix].kind else {
                continue;
            };
            let (indent, quote) = (self.blocks[ix].indent, self.blocks[ix].quote);
            let paragraphs: Vec<Block> = code
                .text
                .split('\n')
                .map(|line| Block {
                    quote,
                    ..Block::at(BlockKind::Paragraph(Text::plain(line)), indent)
                })
                .collect();
            self.blocks.splice(ix..=ix, paragraphs);
        }
        self.repair();
        Some(Cursor::new(start.block, Part::Body, 0).clamp(self))
    }

    /// Every text a selection touches, with the slice of it covered.
    ///
    /// One selection can reach across paragraphs and table cells, and a mark
    /// applies to each of them separately — marks live inside a [`Text`] and
    /// have no way to span two.
    pub fn spans(&self, selection: Selection) -> Vec<(Cursor, Range<usize>)> {
        let (start, end) = selection.clamp(self).ordered();
        let (first, last) = (
            Cursor::new(start.block, start.part, 0),
            Cursor::new(end.block, end.part, 0),
        );
        let mut out = Vec::new();
        for block in start.block..=end.block.min(self.blocks.len().saturating_sub(1)) {
            for part in self.blocks[block].parts() {
                let here = Cursor::new(block, part, 0);
                if here < first || here > last {
                    continue;
                }
                let len = here.len_in(self).unwrap_or(0);
                let from = if here == first { start.offset } else { 0 };
                let to = if here == last { end.offset } else { len };
                if from < to.min(len) {
                    out.push((here, from..to.min(len)));
                }
            }
        }
        out
    }

    /// Add `mark` over a selection, or take it away if every part of the
    /// selection already carries it.
    ///
    /// The decision is made across the whole selection before anything moves:
    /// dragging over a bold word and a plain one and pressing cmd-B should bold
    /// the rest rather than unbolding the half that was already there.
    pub fn toggle_mark(&mut self, selection: Selection, mark: Mark) {
        let spans = self.spans(selection);
        let remove = self.covered_by(selection, &mark);

        for (at, range) in spans {
            // Code is literal to its closing fence and a caption has no room
            // for markup between its brackets; nothing in either is markup.
            if matches!(at.part, Part::Code | Part::Caption) {
                continue;
            }
            if remove == self.carries(&at, &range, &mark) {
                let mark = mark.clone();
                self.edit_at(at, |text| text.toggle(range, mark));
            }
        }
    }

    /// The marks a selection carries throughout — what a toolbar paints as lit.
    ///
    /// Collapsed, it answers with the marks the next character typed here would
    /// join, which is the **left-sticky** rule [`Text::insert`] already
    /// follows: the run ending at the caret, never the one starting there.
    pub fn marks(&self, selection: Selection) -> Vec<Mark> {
        let mut marks: Vec<Mark> = Vec::new();
        if selection.is_collapsed() {
            let at = selection.head.clamp(self);
            let Some(text) = self.blocks.get(at.block).and_then(|b| b.text_at(at.part)) else {
                return marks;
            };
            for span in &text.marks {
                if span.range.start < at.offset && at.offset <= span.range.end {
                    marks.push(span.mark.clone());
                }
            }
            marks.dedup();
            return marks;
        }
        for (at, range) in self.spans(selection) {
            let Some(text) = self.blocks[at.block].text_at(at.part) else {
                continue;
            };
            for span in &text.marks {
                if span.range.start < range.end
                    && span.range.end > range.start
                    && !marks.contains(&span.mark)
                {
                    marks.push(span.mark.clone());
                }
            }
        }
        marks.retain(|mark| self.covered_by(selection, mark));
        marks
    }

    /// Whether every part of a selection already carries `mark` — what decides
    /// between adding it and taking it away, and what a toolbar button reads to
    /// know whether it is lit.
    pub fn covered_by(&self, selection: Selection, mark: &Mark) -> bool {
        let spans = self.spans(selection);
        !spans.is_empty()
            && spans.iter().all(|(at, range)| {
                matches!(at.part, Part::Code | Part::Caption) || self.carries(at, range, mark)
            })
    }

    fn carries(&self, at: &Cursor, range: &Range<usize>, mark: &Mark) -> bool {
        self.blocks[at.block]
            .text_at(at.part)
            .is_some_and(|text| text.covered_by(range, mark))
    }

    /// The sub-document a selection covers — what a copy puts on the clipboard.
    ///
    /// A table is atomic here for the same reason it is in [`Doc::replace`]:
    /// half a table has no shape worth keeping, so a selection reaching into
    /// one takes it whole.
    pub fn slice(&self, selection: Selection) -> Doc {
        let (start, end) = selection.clamp(self).ordered();
        let mut out = Doc {
            blocks: self.blocks[start.block..=end.block].to_vec(),
        };
        let last = end.block - start.block;
        // Tail first: trimming the head would move the offsets the tail is in.
        if !matches!(end.part, Part::Cell { .. })
            && let Some(text) = out.blocks[last].text_at_mut(end.part)
        {
            text.split_off(end.offset);
        }
        if !matches!(start.part, Part::Cell { .. })
            && let Some(text) = out.blocks[0].text_at_mut(start.part)
        {
            *text = text.split_off(start.offset);
        }
        // The slice starts at the left margin whatever depth it was cut from.
        out.repair();
        out
    }

    /// Replace a selection with a whole document — the paste path.
    ///
    /// A lone paragraph goes in as inline text, marks and all: pasting a
    /// sentence into a sentence must not make a new block. Anything else
    /// arrives as blocks, and the remainder of the caret's block follows them.
    pub fn splice(&mut self, selection: Selection, other: Doc) -> Cursor {
        let blocks = other.blocks;
        let inline = match blocks.as_slice() {
            [] => Some(Text::default()),
            [block] => match &block.kind {
                BlockKind::Paragraph(text) => Some(text.clone()),
                _ => None,
            },
            _ => None,
        };
        if let Some(text) = inline {
            return self.replace(selection, text).caret;
        }

        let caret = self.replace(selection, Text::default()).caret;
        let (base, quote) = (
            self.blocks[caret.block].indent,
            self.blocks[caret.block].quote,
        );
        // Split so what followed the caret follows the paste too. An empty
        // remainder is the blank block a paste at the end would leave behind.
        let tail = self.split(caret.block, caret.offset);
        let empty_tail = self.blocks[tail]
            .text_at(Part::Body)
            .is_some_and(Text::is_empty);

        let mut at = caret.block;
        for block in blocks {
            at += 1;
            self.blocks.insert(
                at,
                Block {
                    kind: block.kind,
                    indent: base.saturating_add(block.indent),
                    quote: block.quote.or(quote),
                },
            );
        }
        if empty_tail {
            self.blocks.remove(at + 1);
        }
        // And the block the caret opened in, if the paste displaced all of it.
        let head_empty = self.blocks[caret.block]
            .text_at(Part::Body)
            .is_some_and(Text::is_empty);
        if head_empty && matches!(self.blocks[caret.block].kind, BlockKind::Paragraph(_)) {
            self.blocks.remove(caret.block);
            at -= 1;
        }
        self.repair();
        Cursor::new(at, Part::Body, 0).end(self).clamp(self)
    }

    /// Replace everything a selection covers with `text`, and say where the
    /// caret lands.
    ///
    /// **The one mutation.** Typing, backspace, delete, cut and paste are all
    /// this call with a different argument, which is why none of them needs to
    /// know whether a selection was empty, spanned two paragraphs, or swallowed
    /// a table on the way past.
    pub fn replace(&mut self, selection: Selection, text: Text) -> Splice {
        // An empty document has no block to put anything in; editing one opens
        // the paragraph every other path then assumes exists.
        if self.blocks.is_empty() {
            self.blocks
                .push(Block::new(BlockKind::Paragraph(Text::default())));
        }
        // Counted after that, so the block a nothing-document opens with is not
        // a shift anything downstream has to hear about.
        let before = self.blocks.len();
        let (start, end) = selection.clamp(self).ordered();
        let removed = Selection::new(start, end);

        // Code is literal and a caption is written between brackets, so marks
        // arriving from a paste have nowhere to go in either.
        let text = if matches!(start.part, Part::Code | Part::Caption) {
            Text::plain(text.text)
        } else {
            text
        };

        if start.block == end.block && start.part == end.part {
            let at = start.offset + text.text.len();
            self.edit_at(start, |body| {
                body.remove(start.offset..end.offset);
                body.insert(start.offset, &text.text);
                for span in &text.marks {
                    body.marks.push(MarkSpan {
                        range: start.offset + span.range.start..start.offset + span.range.end,
                        mark: span.mark.clone(),
                    });
                }
                body.normalize_marks();
            });
            return Splice {
                removed,
                caret: Cursor {
                    offset: at,
                    ..start
                }
                .clamp(self),
                blocks: 0,
            };
        }

        // Across cells of one table the table itself survives: the covered
        // cells are emptied and the shape stays, which is what a spreadsheet
        // selection does and what keeps the columns from collapsing.
        if start.block == end.block {
            for part in self.blocks[start.block].parts() {
                if part < start.part || part > end.part {
                    continue;
                }
                // `remove` clamps, so the open end needs no length.
                let (from, to) = (
                    if part == start.part { start.offset } else { 0 },
                    if part == end.part {
                        end.offset
                    } else {
                        usize::MAX
                    },
                );
                self.edit_at(Cursor::new(start.block, part, 0), |body| {
                    body.remove(from..to)
                });
            }
            // The recursion is the insert alone, so what it covered is not what
            // this call covered — only the caret comes back out of it.
            let caret = self.replace(Selection::at(start), text).caret;
            return Splice {
                removed,
                caret,
                blocks: self.blocks.len() as isize - before as isize,
            };
        }

        // Across blocks the head keeps its kind and takes the tail's
        // remainder, and everything between them goes.
        //
        // A **table is atomic** to a selection that leaves it. Half a table has
        // no shape worth keeping, so an end landing in one takes the whole
        // block rather than splicing a lone cell into a paragraph.
        let head_keeps = !matches!(start.part, Part::Cell { .. })
            && self.blocks[start.block].text_at(start.part).is_some();
        let tail = match end.part {
            Part::Cell { .. } => Text::default(),
            part => self.blocks[end.block]
                .text_at_mut(part)
                .map(|body| body.split_off(end.offset))
                .unwrap_or_default(),
        };

        let (indent, quote) = (
            self.blocks[start.block].indent,
            self.blocks[start.block].quote,
        );
        let first = if head_keeps {
            start.block + 1
        } else {
            start.block
        };
        self.blocks.drain(first..=end.block);

        let caret = if head_keeps {
            self.edit_at(start, |body| body.remove(start.offset..usize::MAX));
            self.edit_at(start, |body| body.append(tail));
            start
        } else {
            // Everything the selection touched is gone, so the tail arrives as
            // a paragraph in its place.
            self.blocks.insert(
                start.block,
                Block {
                    quote,
                    ..Block::at(BlockKind::Paragraph(tail), indent)
                },
            );
            Cursor::new(start.block, Part::Body, 0)
        };
        self.repair();
        let caret = caret.clamp(self);
        let caret = self.replace(Selection::at(caret), text).caret;
        Splice {
            removed,
            caret,
            blocks: self.blocks.len() as isize - before as isize,
        }
    }

    /// Put the document into the form markdown can hold — the save step.
    ///
    /// Drops the whitespace markdown discards anyway (leading and trailing on
    /// every line, blank lines at a block's edges), flattens the blocks whose
    /// output is one line, and renumbers ordered runs. After this,
    /// `parse(serialize(doc)) == doc`.
    pub fn normalize(&mut self) {
        self.normalize_with(&crate::Marks::default());
    }

    /// [`Doc::normalize`] with the app's own marks — see [`crate::Marks`].
    pub fn normalize_with(&mut self, marks: &crate::Marks) {
        for block in &mut self.blocks {
            block.normalize_text();
        }
        // An empty heading or list item stays: `# ` and `- ` are both real.
        self.blocks.retain(|block| !block.blank());
        self.repair();

        // The rules above keep every ordinary edit lossless. They cannot be
        // complete, and no serializer fix would make them so: whether a mark
        // boundary can be written depends on CommonMark's flanking rules, and
        // some marks have no spelling at all. Bold ending on a `~` with a letter
        // after it is one — a closing delimiter preceded by punctuation and
        // followed by a letter is not right-flanking, so `Tit**l\~\~**e` does
        // not close. That is a limit of the format, not a bug in the writer.
        //
        // So the last word goes to markdown: adopt the document it can hold.
        //
        // This is exact rather than approximate. Anything [`crate::parse`]
        // returns is a fixed point of the round trip — that is the guarantee the
        // parser is tested for — so writing this document out and reading it
        // back yields one by construction. Marks with no spelling are dropped
        // here, in front of the reader, rather than silently at save time.
        //
        // The cheaper rules above still earn their place: they are what keeps
        // the ordinary edit lossless, so this step has nothing left to take.
        *self = crate::parse_with(&crate::serialize_with(self, marks), marks);
    }

    /// Tab. A block can go one level deeper than the one above it, and its
    /// children come with it.
    pub fn indent(&mut self, ix: usize) -> bool {
        let Some(block) = self.blocks.get(ix) else {
            return false;
        };
        if block.indent >= self.ceiling(ix) {
            return false;
        }
        self.shift_subtree(ix, 1);
        // A run that has just been nested has nothing above it to carry on
        // from, so it starts over. `renumber` cannot decide this on its own: a
        // list written `5.` keeps its 5, and from the numbers alone the two
        // cases look the same.
        if self.begins_run(ix)
            && let BlockKind::Ordered { number, .. } = &mut self.blocks[ix].kind
        {
            *number = 1;
        }
        self.repair();
        true
    }

    /// Whether the block at `ix` starts a run of ordered items rather than
    /// carrying one on: the nearest block at its own indent, before the list
    /// it sits in ends, is not an ordered item.
    fn begins_run(&self, ix: usize) -> bool {
        let indent = self.blocks[ix].indent;
        self.blocks[..ix]
            .iter()
            .rev()
            .take_while(|block| block.indent >= indent)
            .find(|block| block.indent == indent)
            .is_none_or(|block| !matches!(block.kind, BlockKind::Ordered { .. }))
    }

    /// How deep block `ix` is allowed to sit.
    ///
    /// Markdown expresses nesting through list items and nothing else, so a
    /// block may only go deeper than the one above it when that one is a
    /// marker. Indenting a paragraph under a *heading* would serialize to four
    /// leading spaces, which reads back as an indented code block.
    ///
    /// A block that does not carry on the blockquote above it sits no deeper
    /// than that blockquote's `>`.
    pub fn ceiling(&self, ix: usize) -> u8 {
        let runs = quote_runs(
            self.blocks[..ix]
                .iter()
                .map(|block| (block.quote, block.indent)),
        );
        self.ceiling_after(ix, ix.checked_sub(1).and_then(|previous| runs[previous]))
    }

    /// [`Doc::ceiling`], given the blockquote place of the block above.
    fn ceiling_after(&self, ix: usize, above: Option<Run>) -> u8 {
        let Some(previous) = ix.checked_sub(1).map(|previous| &self.blocks[previous]) else {
            return 0;
        };
        let ceiling = if is_marker(&previous.kind) {
            previous.indent + 1
        } else {
            previous.indent
        };
        match above {
            Some(run) if self.blocks.get(ix).map(|block| block.quote) != Some(previous.quote) => {
                ceiling.min(run.level)
            }
            _ => ceiling,
        }
    }

    /// Clamp every indent to what the document can actually express, then make
    /// ordered runs consecutive. Cheap, total, and called after anything
    /// structural — a local rule is not enough, because outdenting one block
    /// can leave the block *after* it stranded a level too deep.
    ///
    /// Public because an editor that changes a block's *kind* has to restore
    /// the invariant too, and only this knows what it is.
    pub fn repair(&mut self) {
        let mut runs = Runs::default();
        let mut above = None;
        for ix in 0..self.blocks.len() {
            let ceiling = self.ceiling_after(ix, above);
            let block = &mut self.blocks[ix];
            block.indent = block.indent.min(ceiling);
            above = runs.next(block.quote, block.indent);
        }
        self.renumber();
    }

    /// Shift-Tab, children included.
    pub fn outdent(&mut self, ix: usize) -> bool {
        if self.blocks.get(ix).is_none_or(|block| block.indent == 0) {
            return false;
        }
        self.shift_subtree(ix, -1);
        self.repair();
        true
    }

    /// Move a block and everything nested under it. Children have to travel
    /// with the parent or the document invariant breaks the moment a level
    /// disappears from under them.
    fn shift_subtree(&mut self, ix: usize, by: i8) {
        let span = self.subtree(ix);
        for block in &mut self.blocks[span] {
            block.indent = block.indent.saturating_add_signed(by);
        }
    }
}

fn is_marker(kind: &BlockKind) -> bool {
    matches!(
        kind,
        BlockKind::Bullet(_) | BlockKind::Ordered { .. } | BlockKind::Task { .. }
    )
}

impl Block {
    /// Shed what markdown cannot hold from each of the block's texts: the
    /// whitespace at the ends of its lines and of the whole, and a line break
    /// where the block has no spelling for one. Marks move with the text.
    pub(crate) fn normalize_text(&mut self) {
        let one_line = matches!(self.kind, BlockKind::Heading { .. });
        match &mut self.kind {
            BlockKind::Paragraph(text)
            | BlockKind::Heading { text, .. }
            | BlockKind::Bullet(text)
            | BlockKind::Ordered { text, .. }
            | BlockKind::Task { text, .. } => {
                *text = crate::parse::normalize(&text.text, &text.marks);
                text.normalize_marks();
                if one_line {
                    crate::parse::collapse_to_one_line(text);
                }
            }
            BlockKind::Table { header, rows, .. } => {
                for cell in header.iter_mut().chain(rows.iter_mut().flatten()) {
                    *cell = crate::parse::normalize(&cell.text, &cell.marks);
                    cell.normalize_marks();
                    crate::parse::collapse_to_one_line(cell);
                }
            }
            // A caption lives between brackets, where a line break has no
            // spelling at all.
            BlockKind::Image { alt, .. } => crate::parse::collapse_to_one_line(alt),
            BlockKind::Code { .. } | BlockKind::Bookmark { .. } | BlockKind::Rule => {}
        }
    }
}