mbr_core/

flashcards.rs

//! Flashcard review history: the pure half of `POST /.mbr/flashcard-review`.
//!
//! A note with `type: flashcard` turns its definition lists into a deck — each
//! term is a card's front, its definitions the back. Spaced-repetition results
//! are kept *in the note itself*, as one more definition of the term:
//!
//! ```markdown
//! What is the capital of France?
//! : Paris.
//! : ___Review History___
//!   * 2026-10-06 13:45 - Again
//!   * 2026-10-09 18:02 - Good
//! ```
//!
//! This module appends one entry to that list (creating the definition when the
//! term has none yet). Like [`crate::tasks::patch_task_line`] it knows nothing
//! about the filesystem or HTTP: the handler reads the file, passes the text and
//! the reviewer's time in, and writes back [`ReviewPatch::source`].
//!
//! # Whose clock
//!
//! The entry has no offset (the format is the user's, and it has to read well
//! as plain text), and the deck replays it as the *browser's* local time. So
//! the time must be the reviewer's wall clock, not the server's: stamped by a
//! server in another time zone, a review would land hours away from where the
//! deck expects it and FSRS's 1-minute/10-minute learning steps would come due
//! at the wrong moment or not at all. The client therefore sends its local time
//! and [`parse_review_time`] checks it — the exact entry format, and within
//! [`REVIEW_TIME_WINDOW_HOURS`] of the server's UTC clock.
//!
//! # Why a real parse, not a line scan
//!
//! Where a term's definitions end is a markdown question, not a textual one: a
//! `: not a definition` line inside a fenced code block, a lazy continuation, a
//! nested list in an answer and a loose list's blank lines all defeat a regex.
//! pulldown-cmark's offset iterator answers it with the same options the
//! renderer uses ([`markdown_options`]), so the writer and the page cannot
//! disagree about which `<dd>`s belong to which `<dt>`.
//!
//! # Scope: top-level definition lists only
//!
//! A definition list nested in a block quote or list item would need every
//! inserted line to repeat the container's `> ` / indentation prefix. The deck
//! (`components/src/flashcards/dom.ts`) collects top-level lists only, and this
//! module refuses anything else with [`FlashcardPatchError::NotATerm`], so the
//! two agree on what a card is.

use std::ops::Range;

use chrono::NaiveDateTime;
use pulldown_cmark::{Event, Parser, Tag, TagEnd};
use serde::{Deserialize, Serialize};

use crate::errors::{FlashcardPatchError, ReviewTimeError};
use crate::markdown::{LineIndex, markdown_options, strip_bom};
use crate::tasks::{line_span, split_line_terminator};

/// The label written when a term gets its first review.
///
/// `___x___` renders as `<em><strong>x</strong></em>`. Any emphasis wrapping the
/// words "Review History" (case-insensitive) is *recognised* — see
/// [`is_history_label`] — but this is the one spelling mbr writes.
pub const HISTORY_LABEL: &str = "___Review History___";

/// The label's words, compared case-insensitively once emphasis is stripped.
const HISTORY_TEXT: &str = "review history";

/// `YYYY-MM-DD HH:MM`, the reviewer's local wall-clock time without an offset
/// — the same shape as a task's `@done(...)` stamp.
const ENTRY_TIME_FORMAT: &str = "%Y-%m-%d %H:%M";

/// How far a reviewer's wall clock may sit from the server's UTC clock.
///
/// Real offsets run from UTC−12 to UTC+14, so every reviewer is within 14
/// hours; 26 leaves room for a badly-set clock on either side while still
/// refusing a stray epoch, a far-future date or a client that sent something
/// other than "now".
pub const REVIEW_TIME_WINDOW_HOURS: i64 = 26;

/// Validates the reviewer's local time as sent by the deck (`at`).
///
/// Strictly `YYYY-MM-DD HH:MM` — ASCII digits, zero-padded, no seconds, no
/// offset, nothing around it — because the string is written into the note
/// verbatim and has to read back as an entry. Chrono's own parser would accept
/// `2026-1-6 9:05` and a leading `+`, so the shape is checked byte by byte
/// first and chrono only judges the calendar (month 13, February 29th of a
/// common year, `24:00`, minute 60 — there is no minute-precision spelling of a
/// leap second).
///
/// `now_utc` is the server's clock as a naive UTC time, a parameter so the
/// window is testable without mocking it.
///
/// # Errors
///
/// [`ReviewTimeError::Malformed`] for anything that is not a real date and
/// time in the entry format; [`ReviewTimeError::OutOfRange`] for one more than
/// [`REVIEW_TIME_WINDOW_HOURS`] away from `now_utc`.
pub fn parse_review_time(
    at: &str,
    now_utc: NaiveDateTime,
) -> Result<NaiveDateTime, ReviewTimeError> {
    const SHAPE: &[u8; 16] = b"0000-00-00 00:00";
    let shaped = at.len() == SHAPE.len()
        && at.bytes().zip(SHAPE).all(|(byte, &want)| match want {
            b'0' => byte.is_ascii_digit(),
            separator => byte == separator,
        });
    if !shaped {
        return Err(ReviewTimeError::Malformed);
    }
    let time = NaiveDateTime::parse_from_str(at, ENTRY_TIME_FORMAT)
        .map_err(|_| ReviewTimeError::Malformed)?;
    let window = chrono::TimeDelta::hours(REVIEW_TIME_WINDOW_HOURS);
    if (time - now_utc).abs() > window {
        return Err(ReviewTimeError::OutOfRange);
    }
    Ok(time)
}

/// One self-rating, in Anki's four-button vocabulary.
///
/// Readers also accept `Fail` as a synonym for [`Rating::Again`] (that is the
/// frontend's job — it parses the history), but mbr only ever *writes* `Again`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum Rating {
    Again,
    Hard,
    Good,
    Easy,
}

impl Rating {
    /// How the rating is spelled in a history entry.
    pub fn label(self) -> &'static str {
        match self {
            Self::Again => "Again",
            Self::Hard => "Hard",
            Self::Good => "Good",
            Self::Easy => "Easy",
        }
    }
}

/// The text of one history entry: `2026-10-06 13:45 - Good`.
pub fn format_entry(reviewed_at: NaiveDateTime, rating: Rating) -> String {
    format!(
        "{} - {}",
        reviewed_at.format(ENTRY_TIME_FORMAT),
        rating.label()
    )
}

/// A markdown source with one review appended by [`append_review`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReviewPatch {
    /// The whole file, ready to be written back.
    pub source: String,
    /// The entry text, as written (without the bullet).
    pub entry: String,
    /// 1-based line number of the first inserted line.
    pub inserted_at: u32,
    /// The inserted lines, without terminators: the bullet alone, or the
    /// history label followed by the bullet when the term had no history yet —
    /// either one followed by a blank line when the next card's term was glued
    /// to the insert point (see [`append_review`]).
    ///
    /// Returned so a client holding the file's lines can splice them in rather
    /// than re-read the file, and shift every later line number it holds.
    pub inserted: Vec<String>,
}

impl ReviewPatch {
    /// 1-based line number of the new bullet: the last non-blank inserted line.
    pub fn entry_line(&self) -> u32 {
        let index = self
            .inserted
            .iter()
            .rposition(|line| !line.is_empty())
            .unwrap_or(0);
        self.inserted_at
            .saturating_add(u32::try_from(index).unwrap_or(0))
    }
}

/// Appends one review entry to the history of the term on `term_line`.
///
/// `reviewed_at` is the reviewer's local wall-clock time (see [`parse_review_time`]),
/// written as the entry's timestamp.
///
/// `term_line` is 1-based — the `data-mbr-line` the renderer puts on the
/// `<dt>`. `expected` is the line's text as the client last saw it, compared
/// modulo its terminator exactly like `POST /.mbr/task`'s, so an edit to the
/// term since the page was loaded is a conflict rather than a review recorded
/// against the wrong card.
///
/// Where the entry goes:
///
/// * the term has a history definition with a list — a new item right after
///   the list's last item, copying that item's indentation, marker and
///   spacing (so `-` lists stay `-` lists);
/// * a history definition with no list yet — a `* ` item at the definition's
///   content indentation, right after it;
/// * no history definition — `: ___Review History___` plus the item, right
///   after the term's last definition, copying that definition's `: ` prefix
///   (see [`definition_prefix`] for when it is not copied verbatim).
///
/// Every other byte is untouched: inserted lines use the terminator of the
/// line they follow (so CRLF files stay CRLF), and a file without a trailing
/// newline still has none.
///
/// # A term glued to the insert point
///
/// A term needs no blank line before it when the definition above ends in a
/// block that cannot be lazily continued — a closed code fence:
///
/// ~~~markdown
/// Q1
/// : A1
///
///   ```
///   code
///   ```
/// Q2
/// : A2
/// ~~~
///
/// Here `Q2` is a card, and so it is indented by up to three spaces. A history
/// bullet inserted above it would give it a paragraph to continue, and the
/// card would silently merge into `Q1`'s history. So when the line after the
/// insert point is non-blank and not a `:` definition, a blank line follows
/// the entry, whatever its indentation. (The common shape, `Q2` straight after
/// a one-line answer, needs nothing: that `Q2` was a lazy continuation of the
/// answer before the write, never a card.)
///
/// # Verified, not predicted
///
/// That rule is a prediction of how the parser will read the result, so the
/// result is re-parsed: every term must still be a term on its (shifted) line,
/// and the new entry must be the last item of the target's history. A patch
/// that fails is retried with the separating blank line; if that fails too the
/// review is refused rather than written.
///
/// # Errors
///
/// [`FlashcardPatchError`]. [`FlashcardPatchError::UnsafeInsert`] when no
/// insertion passes the check above; every other variant means the client is
/// looking at a stale copy of the file.
///
/// # Examples
///
/// ```
/// use chrono::NaiveDate;
/// use mbr_core::flashcards::{Rating, append_review};
///
/// let reviewed_at = NaiveDate::from_ymd_opt(2026, 10, 6)
///     .and_then(|d| d.and_hms_opt(13, 45, 0))
///     .unwrap();
/// let source = "Capital of France?\n: Paris.\n";
/// let patch = append_review(source, 1, "Capital of France?", Rating::Good, reviewed_at).unwrap();
/// assert_eq!(
///     patch.source,
///     "Capital of France?\n: Paris.\n: ___Review History___\n  * 2026-10-06 13:45 - Good\n"
/// );
/// assert_eq!(patch.inserted_at, 3);
/// assert_eq!(patch.entry_line(), 4);
/// ```
pub fn append_review(
    source: &str,
    term_line: u32,
    expected: &str,
    rating: Rating,
    reviewed_at: NaiveDateTime,
) -> Result<ReviewPatch, FlashcardPatchError> {
    let span = line_span(source, term_line)
        .ok_or(FlashcardPatchError::LineOutOfRange { line: term_line })?;
    let (content, term_terminator) = split_line_terminator(&source[span]);
    if content != split_line_terminator(expected).0 {
        return Err(FlashcardPatchError::Mismatch { line: term_line });
    }

    let not_a_term = FlashcardPatchError::NotATerm { line: term_line };
    let terms = scan_terms(source);
    let term = terms
        .iter()
        .find(|term| term.line == term_line)
        .ok_or(not_a_term)?;

    let lines = LineIndex::build(source);
    let entry = format_entry(reviewed_at, rating);
    let (after_line, inserted) = match term.definitions.iter().find(|d| d.history) {
        Some(Definition {
            last_item: Some(item),
            ..
        }) => (
            last_line_of(source, &lines, item),
            vec![bullet_after(source, item.start, &entry)],
        ),
        Some(history) => {
            let indent = content_indent(&definition_prefix(source, history.range.start));
            (
                last_line_of(source, &lines, &history.range),
                vec![format!("{indent}* {entry}")],
            )
        }
        None => {
            // A title is only ever emitted with at least one definition, so
            // this cannot fail on a list pulldown-cmark produced.
            let last = term.definitions.last().ok_or(not_a_term)?;
            let prefix = definition_prefix(source, last.range.start);
            (
                last_line_of(source, &lines, &last.range),
                vec![
                    format!("{prefix}{HISTORY_LABEL}"),
                    format!("{}* {entry}", content_indent(&prefix)),
                ],
            )
        }
    };

    let glued = line_span(source, after_line.saturating_add(1))
        .map(|span| split_line_terminator(&source[span]).0)
        .is_some_and(could_be_absorbed);
    let fallback_terminator = if term_terminator.is_empty() {
        "\n"
    } else {
        term_terminator
    };
    let build = |separate: bool| {
        let inserted: Vec<String> = inserted
            .iter()
            .cloned()
            .chain(separate.then(String::new))
            .collect();
        ReviewPatch {
            source: insert_lines_after(source, after_line, &inserted, fallback_terminator),
            entry: entry.clone(),
            inserted_at: after_line.saturating_add(1),
            inserted,
        }
    };

    // Defence in depth: the shape rules above are a prediction of how the
    // parser will read the result. Check it with the parser itself, and fall
    // back to the separating blank line before refusing outright.
    let term_lines: Vec<u32> = terms.iter().map(|term| term.line).collect();
    std::iter::once(glued)
        .chain((!glued).then_some(true))
        .map(build)
        .find(|patch| keeps_every_card(patch, &term_lines, term_line))
        .ok_or(FlashcardPatchError::UnsafeInsert { line: term_line })
}

/// True when `line`, directly after the insert point, could be swallowed by
/// the new entry: anything non-blank that is not a `:` definition (which
/// continues the definition list as it should).
///
/// Indentation does not matter. A line below the entry's content column is a
/// lazy continuation of its paragraph; one at or past it is an ordinary
/// continuation. Either way the next card's term — which may be indented up to
/// three spaces — would stop being a term.
fn could_be_absorbed(line: &str) -> bool {
    let content = line.trim_start_matches([' ', '\t']);
    !content.is_empty() && !content.starts_with(':')
}

/// Whether `patch` re-parses as the same deck plus one entry: every term is
/// still a term (on its old line, shifted past the insert), and the new entry
/// is the last item of `term_line`'s history definition — the one the next
/// review will append to.
fn keeps_every_card(patch: &ReviewPatch, term_lines: &[u32], term_line: u32) -> bool {
    let shift = u32::try_from(patch.inserted.len()).unwrap_or(u32::MAX);
    let after = scan_terms(&patch.source);
    let moved = term_lines.iter().map(|&line| {
        if line >= patch.inserted_at {
            line.saturating_add(shift)
        } else {
            line
        }
    });
    if !after.iter().map(|term| term.line).eq(moved) {
        return false;
    }
    let Some(span) = line_span(&patch.source, patch.entry_line()) else {
        return false;
    };
    // The entry's last character, which only its own list item can contain.
    let text = split_line_terminator(&patch.source[span.clone()])
        .0
        .trim_end();
    let Some(entry_end) = (span.start + text.len()).checked_sub(1) else {
        return false;
    };
    after
        .iter()
        .find(|term| term.line == term_line)
        .and_then(|term| term.definitions.iter().find(|d| d.history))
        .and_then(|history| history.last_item.as_ref())
        .is_some_and(|item| item.contains(&entry_end))
}

/// True when inline `text` — the words inside the emphasis that opens a
/// definition — names the review-history definition.
pub fn is_history_label(text: &str) -> bool {
    text.trim().eq_ignore_ascii_case(HISTORY_TEXT)
}

// ============================================================================
// Scanning
// ============================================================================

/// One top-level definition-list term and its definitions.
#[derive(Debug, Clone, PartialEq, Eq)]
struct Term {
    /// 1-based line the term starts on.
    line: u32,
    definitions: Vec<Definition>,
}

/// One `<dd>`, as byte ranges into the source.
#[derive(Debug, Clone, PartialEq, Eq)]
struct Definition {
    range: Range<usize>,
    /// Whether this is the review-history definition.
    history: bool,
    /// The last item of the definition's first directly-nested list.
    last_item: Option<Range<usize>>,
}

/// Whether a definition's leading content names it the history definition.
#[derive(Debug)]
enum Label {
    /// Nothing but block wrappers seen yet.
    Pending,
    /// Inside the leading emphasis opened at `depth`, collecting its text.
    Capturing {
        depth: usize,
        text: String,
    },
    Decided(bool),
}

/// Depth of a definition's own content: `DefinitionList` (0) →
/// `DefinitionListDefinition` (1) → content (2).
const CONTENT_DEPTH: usize = 2;

/// A definition being walked.
#[derive(Debug)]
struct DefinitionScan {
    range: Range<usize>,
    label: Label,
    /// Depth of the first list that is a direct child of the definition.
    list_depth: Option<usize>,
    list_closed: bool,
    last_item: Option<Range<usize>>,
}

impl DefinitionScan {
    fn new(range: Range<usize>) -> Self {
        Self {
            range,
            label: Label::Pending,
            list_depth: None,
            list_closed: false,
            last_item: None,
        }
    }

    /// A `Start` at `depth` (the depth *outside* the tag being opened).
    fn start(&mut self, tag: &Tag<'_>, depth: usize, range: &Range<usize>) {
        if matches!(self.label, Label::Pending) {
            self.label = match tag {
                // A loose definition wraps its content in a paragraph.
                Tag::Paragraph if depth == CONTENT_DEPTH => Label::Pending,
                Tag::Emphasis | Tag::Strong => Label::Capturing {
                    depth,
                    text: String::new(),
                },
                _ => Label::Decided(false),
            };
        }
        match tag {
            Tag::List(_) if depth == CONTENT_DEPTH && self.list_depth.is_none() => {
                self.list_depth = Some(depth);
            }
            Tag::Item if !self.list_closed && self.list_depth.is_some_and(|d| d + 1 == depth) => {
                self.last_item = Some(range.clone());
            }
            _ => {}
        }
    }

    /// An `End` that closes a tag opened at `depth`.
    fn end(&mut self, tag: &TagEnd, depth: usize) {
        if let Label::Capturing {
            depth: opened,
            text,
        } = &self.label
            && *opened == depth
        {
            self.label = Label::Decided(is_history_label(text));
        }
        if matches!(tag, TagEnd::List(_)) && self.list_depth == Some(depth) {
            self.list_closed = true;
        }
    }

    /// Any non-tag event inside the definition.
    fn inline(&mut self, event: &Event<'_>) {
        match &mut self.label {
            Label::Capturing { text, .. } => {
                if let Event::Text(t) | Event::Code(t) = event {
                    text.push_str(t);
                }
            }
            // Leading text before any emphasis: an ordinary answer.
            Label::Pending => self.label = Label::Decided(false),
            Label::Decided(_) => {}
        }
    }

    fn finish(self) -> Definition {
        Definition {
            range: self.range,
            history: matches!(self.label, Label::Decided(true)),
            last_item: self.last_item,
        }
    }
}

/// Every top-level definition-list term in `source`, in document order.
fn scan_terms(source: &str) -> Vec<Term> {
    let body = strip_bom(source);
    let shift = source.len() - body.len();
    let lines = LineIndex::build(source);

    let mut terms = Vec::new();
    let mut depth = 0usize;
    let mut in_top_list = false;
    let mut term: Option<Term> = None;
    let mut definition: Option<DefinitionScan> = None;

    for (event, range) in Parser::new_ext(body, markdown_options()).into_offset_iter() {
        let range = range.start + shift..range.end + shift;
        match event {
            Event::Start(tag) => {
                match (&tag, depth) {
                    (Tag::DefinitionList, 0) => in_top_list = true,
                    (Tag::DefinitionListTitle, 1) if in_top_list => {
                        let next = Term {
                            line: lines.line_of(range.start),
                            definitions: Vec::new(),
                        };
                        terms.extend(term.replace(next));
                    }
                    (Tag::DefinitionListDefinition, 1) if in_top_list => {
                        definition = Some(DefinitionScan::new(range));
                    }
                    _ => {
                        if let Some(scan) = definition.as_mut() {
                            scan.start(&tag, depth, &range);
                        }
                    }
                }
                depth += 1;
            }
            Event::End(tag) => {
                depth = depth.saturating_sub(1);
                match (&tag, depth) {
                    (TagEnd::DefinitionListDefinition, 1) if in_top_list => {
                        if let (Some(scan), Some(open)) = (definition.take(), term.as_mut()) {
                            open.definitions.push(scan.finish());
                        }
                    }
                    (TagEnd::DefinitionList, 0) if in_top_list => {
                        in_top_list = false;
                        terms.extend(term.take());
                    }
                    _ => {
                        if let Some(scan) = definition.as_mut() {
                            scan.end(&tag, depth);
                        }
                    }
                }
            }
            other => {
                if let Some(scan) = definition.as_mut() {
                    scan.inline(&other);
                }
            }
        }
    }
    terms.extend(term);
    terms
}

// ============================================================================
// Source surgery
// ============================================================================

/// Byte offset of the start of the line containing `offset`.
fn line_start(source: &str, offset: usize) -> usize {
    source[..offset]
        .rfind('\n')
        .map_or(0, |newline| newline + 1)
}

/// The text of the line containing `offset`, without its terminator.
fn line_containing(source: &str, offset: usize) -> &str {
    let start = line_start(source, offset);
    let end = source[start..]
        .find('\n')
        .map_or(source.len(), |newline| start + newline);
    source[start..end].trim_end_matches('\r')
}

/// The last line holding anything but whitespace within `range`. A loose
/// block's range can run on over trailing blank lines, and inserting after
/// those would detach the new line from the block it belongs to.
fn last_line_of(source: &str, lines: &LineIndex, range: &Range<usize>) -> u32 {
    let text = &source[range.clone()];
    let content = text.trim_end();
    if content.is_empty() {
        lines.line_of(range.start)
    } else {
        lines.line_of(range.start + content.len() - 1)
    }
}

/// The `: ` prefix (leading blanks, colon, following blanks) of the definition
/// starting at `offset`, for a new definition placed after it.
///
/// The leading blanks are copied, and so is a gap of one to four spaces after
/// the colon. A wider gap, or one holding a tab, is *not*: five or more columns
/// after the marker make the definition's content an indented code block, so
/// a label written with that prefix would be code, never recognised as the
/// history, and every review would add another one. Those get `": "`.
fn definition_prefix(source: &str, offset: usize) -> String {
    /// The widest gap after `:` that still starts ordinary content.
    const MAX_GAP: usize = 4;
    let line = line_containing(source, offset);
    let lead = line.len() - line.trim_start_matches([' ', '\t']).len();
    let gap = line[lead..]
        .strip_prefix(':')
        .map_or(0, |rest| rest.len() - rest.trim_start_matches(' ').len());
    let gap = if (1..=MAX_GAP).contains(&gap) { gap } else { 1 };
    let lead = if line[lead..].starts_with(':') {
        &line[..lead]
    } else {
        ""
    };
    format!("{lead}:{}", " ".repeat(gap))
}

/// Indentation that puts a line inside a definition whose first line starts
/// with `prefix` — the prefix with its colon blanked out.
fn content_indent(prefix: &str) -> String {
    prefix.replace(':', " ")
}

/// A list item for `entry` shaped like the item starting at `item_start`: same
/// indentation, marker and gap.
fn bullet_after(source: &str, item_start: usize, entry: &str) -> String {
    let start = line_start(source, item_start);
    // Only whitespace is expected in front of a top-level definition's list
    // item; blank anything else so the column survives regardless.
    let indent: String = source[start..item_start]
        .chars()
        .map(|c| if c == '\t' { '\t' } else { ' ' })
        .collect();
    let rest = line_containing(source, item_start);
    let rest = &rest[item_start - start..];
    let marker_len = rest.find(|c: char| c.is_whitespace()).unwrap_or(rest.len());
    let marker = &rest[..marker_len];
    let after = &rest[marker_len..];
    let gap = &after[..after.len() - after.trim_start_matches([' ', '\t']).len()];
    let (marker, gap) = if marker.is_empty() {
        ("*", " ")
    } else if gap.is_empty() {
        (marker, " ")
    } else {
        (marker, gap)
    };
    format!("{indent}{marker}{gap}{entry}")
}

/// `source` with `inserted` placed after its 1-based `after_line`.
///
/// Each inserted line takes the terminator of the line it follows. When that
/// line is the last one and has none, the file gains a terminator *before* the
/// insert (`fallback`), and the insert itself ends unterminated, so the file
/// still does not end in a newline.
fn insert_lines_after(
    source: &str,
    after_line: u32,
    inserted: &[String],
    fallback: &str,
) -> String {
    let added: usize = inserted.iter().map(|line| line.len() + 2).sum();
    let mut out = String::with_capacity(source.len() + added);
    let Some(span) = line_span(source, after_line) else {
        // Unreachable for a line found by scanning `source`; append instead of
        // losing the entry.
        out.push_str(source);
        for line in inserted {
            out.push_str(fallback);
            out.push_str(line);
        }
        return out;
    };
    let (_, terminator) = split_line_terminator(&source[span.clone()]);
    if terminator.is_empty() {
        out.push_str(source);
        for line in inserted {
            out.push_str(fallback);
            out.push_str(line);
        }
    } else {
        out.push_str(&source[..span.end]);
        for line in inserted {
            out.push_str(line);
            out.push_str(terminator);
        }
        out.push_str(&source[span.end..]);
    }
    out
}

#[cfg(test)]
mod tests {
    use super::*;
    use chrono::NaiveDate;
    use proptest::prelude::*;

    fn at(h: u32, m: u32) -> NaiveDateTime {
        NaiveDate::from_ymd_opt(2026, 10, 6)
            .and_then(|d| d.and_hms_opt(h, m, 0))
            .expect("valid test time")
    }

    /// Appends a `Good` at 13:45 to the term on `line`, reading `expected`
    /// straight from the source.
    fn append(source: &str, line: u32) -> Result<ReviewPatch, FlashcardPatchError> {
        let expected = source
            .split('\n')
            .nth(line as usize - 1)
            .unwrap_or_default()
            .trim_end_matches('\r');
        append_review(source, line, expected, Rating::Good, at(13, 45))
    }

    fn appended(source: &str, line: u32) -> String {
        append(source, line).expect("append succeeds").source
    }

    // ---- format -------------------------------------------------------------

    #[test]
    fn entry_format_is_minutes_and_capitalised_rating() {
        assert_eq!(
            format_entry(at(9, 5), Rating::Again),
            "2026-10-06 09:05 - Again"
        );
        assert_eq!(
            format_entry(at(23, 59), Rating::Easy),
            "2026-10-06 23:59 - Easy"
        );
    }

    // ---- the reviewer's clock ----------------------------------------------

    /// The server's UTC "now" for the window tests.
    fn utc_now() -> NaiveDateTime {
        at(12, 0)
    }

    #[test]
    fn review_time_accepts_any_real_time_zone() {
        // UTC-12 (Baker Island) to UTC+14 (Kiribati), and UTC itself.
        for at in ["2026-10-06 00:00", "2026-10-06 12:00", "2026-10-07 02:00"] {
            assert_eq!(
                parse_review_time(at, utc_now()).map(|t| format_entry(t, Rating::Good)),
                Ok(format!("{at} - Good")),
                "{at}"
            );
        }
        // The window's edges are inclusive.
        assert!(parse_review_time("2026-10-05 10:00", utc_now()).is_ok());
        assert!(parse_review_time("2026-10-07 14:00", utc_now()).is_ok());
    }

    #[test]
    fn review_time_refuses_times_no_time_zone_can_explain() {
        for at in [
            "2026-10-05 09:59", // 26h01m behind
            "2026-10-07 14:01", // 26h01m ahead
            "1970-01-01 00:00",
            "9999-12-31 23:59",
        ] {
            assert_eq!(
                parse_review_time(at, utc_now()),
                Err(ReviewTimeError::OutOfRange),
                "{at}"
            );
        }
    }

    #[test]
    fn review_time_is_strictly_the_entry_format() {
        for at in [
            "",
            "now",
            "2026-10-06",
            "2026-10-06 12:00:00", // seconds are not stored
            "2026-10-06T12:00",
            "2026-10-06 12:00Z",
            "2026-10-06 12:00 ",
            " 2026-10-06 12:00",
            "2026-10-6 12:00",
            "2026-10-06 2:00",
            "+2026-10-06 12:00",
            "2026-1０-06 12:00", // a full-width digit
            "2026-10-06 12:00 - Good",
        ] {
            assert_eq!(
                parse_review_time(at, utc_now()),
                Err(ReviewTimeError::Malformed),
                "{at:?}"
            );
        }
    }

    #[test]
    fn review_time_refuses_impossible_calendar_values() {
        for at in [
            "2026-13-01 12:00",
            "2026-00-10 12:00",
            "2026-02-29 12:00", // not a leap year
            "2026-10-32 12:00",
            "2026-10-06 24:00",
            "2026-10-06 12:60",
            // A leap second has no minute-precision spelling: 23:59:60 is
            // malformed (no seconds) and 23:60 is not a minute.
            "2016-12-31 23:60",
            "2016-12-31 23:59:60",
        ] {
            assert_eq!(
                parse_review_time(at, utc_now()),
                Err(ReviewTimeError::Malformed),
                "{at}"
            );
        }
    }

    proptest! {
        /// Never panics, and anything it accepts round-trips through the entry
        /// format unchanged — which is what the server writes.
        #[test]
        fn review_time_never_panics_and_round_trips(at in "\\PC{0,24}") {
            if let Ok(time) = parse_review_time(&at, utc_now()) {
                prop_assert_eq!(time.format(ENTRY_TIME_FORMAT).to_string(), at);
            }
        }
    }

    #[test]
    fn rating_deserialises_lowercase_only() {
        let good: Rating = serde_json::from_str("\"good\"").unwrap();
        assert_eq!(good, Rating::Good);
        assert!(serde_json::from_str::<Rating>("\"Good\"").is_err());
        assert!(serde_json::from_str::<Rating>("\"fail\"").is_err());
    }

    #[test]
    fn history_label_matching() {
        assert!(is_history_label("Review History"));
        assert!(is_history_label("  review history "));
        assert!(is_history_label("REVIEW HISTORY"));
        assert!(!is_history_label("Review"));
        assert!(!is_history_label("Review History of Rome"));
    }

    // ---- creating a history -------------------------------------------------

    #[test]
    fn first_review_creates_the_history_definition() {
        let source = "Q?\n: A.\n\nNext?\n: B.\n";
        let patch = append(source, 1).unwrap();
        assert_eq!(
            patch.source,
            "Q?\n: A.\n: ___Review History___\n  * 2026-10-06 13:45 - Good\n\nNext?\n: B.\n"
        );
        assert_eq!(patch.entry, "2026-10-06 13:45 - Good");
        assert_eq!(patch.inserted_at, 3);
        assert_eq!(
            patch.inserted,
            vec![": ___Review History___", "  * 2026-10-06 13:45 - Good"]
        );
        assert_eq!(patch.entry_line(), 4);
    }

    #[test]
    fn history_goes_after_the_last_of_several_answers() {
        let source = "Q?\n: one\n: two\n";
        assert_eq!(
            appended(source, 1),
            "Q?\n: one\n: two\n: ___Review History___\n  * 2026-10-06 13:45 - Good\n"
        );
    }

    #[test]
    fn history_copies_a_wider_definition_prefix() {
        let source = "Q?\n:   A wide answer\n";
        assert_eq!(
            appended(source, 1),
            "Q?\n:   A wide answer\n:   ___Review History___\n    * 2026-10-06 13:45 - Good\n"
        );
    }

    #[test]
    fn loose_definitions_get_the_history_after_the_last_content_line() {
        let source = "Q?\n\n: A.\n\n: B.\n\nNext?\n\n: C.\n";
        assert_eq!(
            appended(source, 1),
            "Q?\n\n: A.\n\n: B.\n: ___Review History___\n  * 2026-10-06 13:45 - Good\n\nNext?\n\n: C.\n"
        );
    }

    #[test]
    fn multi_line_answer_with_nested_list_and_code() {
        let source = concat!(
            "Q?\n",
            ": Steps:\n",
            "  * first\n",
            "  * second\n",
            "\n",
            "  ```\n",
            "  : not a definition\n",
            "  ```\n",
            "\n",
            "Next?\n",
            ": B.\n",
        );
        let patched = appended(source, 1);
        assert_eq!(
            patched,
            concat!(
                "Q?\n",
                ": Steps:\n",
                "  * first\n",
                "  * second\n",
                "\n",
                "  ```\n",
                "  : not a definition\n",
                "  ```\n",
                ": ___Review History___\n",
                "  * 2026-10-06 13:45 - Good\n",
                "\n",
                "Next?\n",
                ": B.\n",
            )
        );
        // And the nested list did not get mistaken for the history.
        let terms = scan_terms(&patched);
        assert_eq!(terms[0].definitions.len(), 2);
        assert!(!terms[0].definitions[0].history);
        assert!(terms[0].definitions[1].history);
    }

    // ---- appending to a history ---------------------------------------------

    #[test]
    fn appends_after_the_last_history_bullet() {
        let source = concat!(
            "Q?\n",
            ": A.\n",
            ": ___Review History___\n",
            "  * 2026-10-01 08:00 - Again\n",
            "  * 2026-10-02 09:00 - Good\n",
            "\n",
            "Next?\n",
            ": B.\n",
        );
        let patch = append(source, 1).unwrap();
        assert_eq!(patch.inserted, vec!["  * 2026-10-06 13:45 - Good"]);
        assert_eq!(patch.inserted_at, 6);
        assert_eq!(patch.entry_line(), 6);
        assert_eq!(
            patch.source,
            concat!(
                "Q?\n",
                ": A.\n",
                ": ___Review History___\n",
                "  * 2026-10-01 08:00 - Again\n",
                "  * 2026-10-02 09:00 - Good\n",
                "  * 2026-10-06 13:45 - Good\n",
                "\n",
                "Next?\n",
                ": B.\n",
            )
        );
    }

    #[test]
    fn keeps_dash_markers_and_wide_gaps() {
        let source = "Q?\n: A.\n: **Review History**\n  -   2026-10-01 08:00 - Hard\n";
        assert_eq!(
            appended(source, 1),
            "Q?\n: A.\n: **Review History**\n  -   2026-10-01 08:00 - Hard\n  -   2026-10-06 13:45 - Good\n"
        );
    }

    #[test]
    fn recognises_single_emphasis_and_any_case() {
        let source = "Q?\n: A.\n: *review history*\n  * 2026-10-01 08:00 - Fail\n";
        let patch = append(source, 1).unwrap();
        assert_eq!(patch.inserted, vec!["  * 2026-10-06 13:45 - Good"]);
    }

    #[test]
    fn plain_text_review_history_is_an_answer_not_a_history() {
        // Without emphasis it is just an answer that happens to say that.
        let source = "Q?\n: Review History\n";
        let patch = append(source, 1).unwrap();
        assert_eq!(patch.inserted.len(), 2, "a real history is created");
    }

    #[test]
    fn label_only_history_gets_its_first_bullet() {
        let source = "Q?\n: A.\n: ___Review History___\n\nNext?\n: B.\n";
        assert_eq!(
            appended(source, 1),
            "Q?\n: A.\n: ___Review History___\n  * 2026-10-06 13:45 - Good\n\nNext?\n: B.\n"
        );
    }

    #[test]
    fn loose_history_list_appends_after_last_item() {
        let source = concat!(
            "Q?\n\n",
            ": A.\n\n",
            ": ___Review History___\n\n",
            "  * 2026-10-01 08:00 - Good\n\n",
            "  * 2026-10-02 08:00 - Easy\n\n",
            "Next?\n\n",
            ": B.\n",
        );
        let patched = appended(source, 1);
        assert!(
            patched.contains("  * 2026-10-02 08:00 - Easy\n  * 2026-10-06 13:45 - Good\n\nNext?"),
            "{patched}"
        );
    }

    #[test]
    fn unparseable_history_lines_are_left_alone() {
        let source = "Q?\n: A.\n: ___Review History___\n  * yesterday, sort of\n";
        assert_eq!(
            appended(source, 1),
            "Q?\n: A.\n: ___Review History___\n  * yesterday, sort of\n  * 2026-10-06 13:45 - Good\n"
        );
    }

    // ---- addressing -------------------------------------------------------

    #[test]
    fn second_term_in_the_same_list_and_terms_in_other_lists() {
        let source = concat!(
            "# Deck\n",       // 1
            "\n",             // 2
            "One?\n",         // 3
            ": 1\n",          // 4
            "\n",             // 5
            "Two?\n",         // 6
            ": 2\n",          // 7
            "\n",             // 8
            "A paragraph.\n", // 9
            "\n",             // 10
            "Three?\n",       // 11
            ": 3\n",          // 12
        );
        assert!(appended(source, 6).contains("Two?\n: 2\n: ___Review History___\n  * "));
        assert!(
            appended(source, 11)
                .ends_with("Three?\n: 3\n: ___Review History___\n  * 2026-10-06 13:45 - Good\n")
        );
        let one = appended(source, 3);
        assert!(
            one.starts_with("# Deck\n\nOne?\n: 1\n: ___Review History___\n"),
            "{one}"
        );
    }

    #[test]
    fn frontmatter_counts_toward_line_numbers() {
        let source = "---\ntype: flashcard\n---\n\nQ?\n: A.\n";
        assert!(
            appended(source, 5)
                .ends_with(": A.\n: ___Review History___\n  * 2026-10-06 13:45 - Good\n")
        );
        // The frontmatter's `type: flashcard` is not a term.
        assert_eq!(
            append(source, 2),
            Err(FlashcardPatchError::NotATerm { line: 2 })
        );
    }

    #[test]
    fn bom_does_not_shift_anything() {
        let source = "\u{feff}---\ntype: flashcard\n---\nQ?\n: A.\n";
        let patched = appended(source, 4);
        assert!(patched.starts_with('\u{feff}'));
        assert!(patched.ends_with(": A.\n: ___Review History___\n  * 2026-10-06 13:45 - Good\n"));
    }

    #[test]
    fn colon_lines_in_code_fences_are_not_terms() {
        let source = "```\nFake?\n: not a definition\n```\n\nReal?\n: yes\n";
        assert_eq!(
            append(source, 2),
            Err(FlashcardPatchError::NotATerm { line: 2 })
        );
        assert!(
            appended(source, 6)
                .ends_with(": yes\n: ___Review History___\n  * 2026-10-06 13:45 - Good\n")
        );
    }

    /// A term inside a ```` ```chat ```` body renders as a real `<dt>` with a
    /// `data-mbr-line`, but in the source it is code-fence text. The writer must
    /// refuse it, which is why the deck treats `.mbr-chat` as nesting.
    #[test]
    fn terms_inside_chat_blocks_are_not_terms() {
        let source = "```chat\n{{Alice|Chat term\n: chat answer\n|}}\n```\n\nReal?\n: yes\n";
        assert_eq!(
            append(source, 2),
            Err(FlashcardPatchError::NotATerm { line: 2 })
        );
        assert!(
            appended(source, 7)
                .ends_with(": yes\n: ___Review History___\n  * 2026-10-06 13:45 - Good\n")
        );
    }

    #[test]
    fn definition_lines_and_prose_are_not_terms() {
        let source = "Prose.\n\nQ?\n: A.\n";
        assert_eq!(
            append(source, 1),
            Err(FlashcardPatchError::NotATerm { line: 1 })
        );
        assert_eq!(
            append(source, 4),
            Err(FlashcardPatchError::NotATerm { line: 4 })
        );
    }

    #[test]
    fn nested_definition_lists_are_refused() {
        let source = "> Q?\n> : A.\n\n- Q2?\n  : A2.\n";
        assert_eq!(
            append(source, 1),
            Err(FlashcardPatchError::NotATerm { line: 1 })
        );
        assert_eq!(
            append(source, 4),
            Err(FlashcardPatchError::NotATerm { line: 4 })
        );
    }

    #[test]
    fn mismatch_and_out_of_range() {
        let source = "Q?\n: A.\n";
        assert_eq!(
            append_review(source, 1, "Q? (edited)", Rating::Good, at(1, 2)),
            Err(FlashcardPatchError::Mismatch { line: 1 })
        );
        assert_eq!(
            append_review(source, 9, "Q?", Rating::Good, at(1, 2)),
            Err(FlashcardPatchError::LineOutOfRange { line: 9 })
        );
        assert_eq!(
            append_review(source, 0, "Q?", Rating::Good, at(1, 2)),
            Err(FlashcardPatchError::LineOutOfRange { line: 0 })
        );
    }

    #[test]
    fn expected_is_compared_modulo_terminator() {
        let source = "Q?\r\n: A.\r\n";
        assert!(append_review(source, 1, "Q?\r\n", Rating::Hard, at(1, 2)).is_ok());
        assert!(append_review(source, 1, "Q?", Rating::Hard, at(1, 2)).is_ok());
    }

    // ---- terminators --------------------------------------------------------

    #[test]
    fn crlf_is_preserved() {
        let source = "Q?\r\n: A.\r\n: ___Review History___\r\n  * 2026-10-01 08:00 - Good\r\n";
        assert_eq!(
            appended(source, 1),
            "Q?\r\n: A.\r\n: ___Review History___\r\n  * 2026-10-01 08:00 - Good\r\n  * 2026-10-06 13:45 - Good\r\n"
        );
        let fresh = "Q?\r\n: A.\r\n";
        assert_eq!(
            appended(fresh, 1),
            "Q?\r\n: A.\r\n: ___Review History___\r\n  * 2026-10-06 13:45 - Good\r\n"
        );
    }

    #[test]
    fn missing_trailing_newline_stays_missing() {
        assert_eq!(
            appended("Q?\n: A.", 1),
            "Q?\n: A.\n: ___Review History___\n  * 2026-10-06 13:45 - Good"
        );
        assert_eq!(
            appended("Q?\r\n: A.", 1),
            "Q?\r\n: A.\r\n: ___Review History___\r\n  * 2026-10-06 13:45 - Good"
        );
        assert_eq!(
            appended(
                "Q?\n: A.\n: ___Review History___\n  * 2026-10-01 08:00 - Good",
                1
            ),
            "Q?\n: A.\n: ___Review History___\n  * 2026-10-01 08:00 - Good\n  * 2026-10-06 13:45 - Good"
        );
    }

    #[test]
    fn repeated_reviews_accumulate() {
        let mut source = "Q?\n: A.\n\nNext?\n: B.\n".to_string();
        for (i, rating) in [Rating::Again, Rating::Hard, Rating::Good, Rating::Easy]
            .into_iter()
            .enumerate()
        {
            source = append_review(&source, 1, "Q?", rating, at(10, i as u32))
                .unwrap()
                .source;
        }
        assert_eq!(
            source,
            concat!(
                "Q?\n",
                ": A.\n",
                ": ___Review History___\n",
                "  * 2026-10-06 10:00 - Again\n",
                "  * 2026-10-06 10:01 - Hard\n",
                "  * 2026-10-06 10:02 - Good\n",
                "  * 2026-10-06 10:03 - Easy\n",
                "\n",
                "Next?\n",
                ": B.\n",
            )
        );
    }

    // ---- terms with no blank line before them --------------------------------

    /// The `<dt>` texts of `source` rendered exactly as a page is — the same
    /// parser and [`markdown_options`] — so these tests do not rely on
    /// [`scan_terms`] agreeing with itself.
    fn rendered_terms(source: &str) -> Vec<String> {
        let mut html = String::new();
        pulldown_cmark::html::push_html(&mut html, Parser::new_ext(source, markdown_options()));
        html.split("<dt>")
            .skip(1)
            .map(|rest| rest[..rest.find("</dt>").expect("closed dt")].to_string())
            .collect()
    }

    /// Rates the term on `line` and checks the write kept every card — by the
    /// renderer's parse and by [`outline`] — while adding one history entry.
    fn assert_rating_keeps_cards(source: &str, line: u32) -> String {
        let terms = rendered_terms(source);
        let before = outline(source);
        let patched = appended(source, line);
        assert_eq!(rendered_terms(&patched), terms, "{patched}");
        let after = outline(&patched);
        assert_eq!(after.len(), before.len(), "{patched}");
        for (i, (b, a)) in before.iter().zip(&after).enumerate() {
            assert_eq!((&b.0, &b.1), (&a.0, &a.1), "card {i}: {patched}");
            let target = b.0 == line_containing(source, line_span(source, line).unwrap().start);
            let grown = if target {
                b.2.unwrap_or(0) + 1
            } else {
                b.2.unwrap_or(0)
            };
            assert_eq!(a.2.unwrap_or(0), grown, "card {i}: {patched}");
        }
        patched
    }

    /// `Q2` straight after an answer is not a second term at all: it is a lazy
    /// continuation of `A1`'s paragraph, before any write, so the deck never
    /// offered it as a card. A pulldown-cmark definition list needs a blank
    /// line (or a non-paragraph block) before the next term.
    #[test]
    fn a_term_glued_to_an_answer_is_a_lazy_continuation() {
        let source = "Q1\n: A1\nQ2\n: A2\n";
        assert_eq!(rendered_terms(source), ["Q1"]);
        assert_eq!(
            append(source, 3),
            Err(FlashcardPatchError::NotATerm { line: 3 })
        );
        let patched = assert_rating_keeps_cards(source, 1);
        assert_eq!(
            patched,
            "Q1\n: A1\nQ2\n: A2\n: ___Review History___\n  * 2026-10-06 13:45 - Good\n"
        );
    }

    /// The same inside an existing history: `Q2` continues the last bullet.
    #[test]
    fn a_term_glued_to_a_history_bullet_is_a_lazy_continuation() {
        let source = "Q1\n: A1\n: ___Review History___\n  * 2026-10-01 08:00 - Good\nQ2\n: A2\n";
        assert_eq!(rendered_terms(source), ["Q1"]);
        assert_rating_keeps_cards(source, 1);
    }

    #[test]
    fn a_term_glued_to_a_loose_answer_is_a_lazy_continuation() {
        let source = "Q1\n\n: A1\nQ2\n\n: A2\n";
        assert_eq!(rendered_terms(source), ["Q1"]);
        assert_rating_keeps_cards(source, 1);
    }

    /// A definition ending in a fenced block leaves no paragraph to continue,
    /// so here the glued `Q2` *is* a term — and a history written straight
    /// above it would hand it a bullet to lazily continue, silently merging
    /// the card into the previous one.
    #[test]
    fn a_term_glued_to_a_closed_fence_stays_a_term() {
        let source = "Q1\n: A1\n\n  ```\n  code\n  ```\nQ2\n: A2\n";
        assert_eq!(rendered_terms(source), ["Q1", "Q2"]);
        let patched = assert_rating_keeps_cards(source, 1);
        assert_eq!(
            patched,
            concat!(
                "Q1\n: A1\n\n  ```\n  code\n  ```\n",
                ": ___Review History___\n",
                "  * 2026-10-06 13:45 - Good\n",
                "\n",
                "Q2\n: A2\n",
            )
        );
        // The separating blank line is reported, so a client shifting its line
        // numbers by `inserted.len()` stays right, but the entry's own line
        // skips it.
        let patch = append(source, 1).unwrap();
        assert_eq!(patch.inserted.last().map(String::as_str), Some(""));
        assert_eq!((patch.inserted_at, patch.entry_line()), (7, 8));
        // `Q2`'s card renders exactly as it did before the write.
        let q2_card = |source: &str| {
            let mut html = String::new();
            pulldown_cmark::html::push_html(&mut html, Parser::new_ext(source, markdown_options()));
            html[html.find("<dt>Q2</dt>").expect("Q2 is a term")..].to_string()
        };
        assert_eq!(q2_card(&patched), q2_card(source));
        // …and the next rating appends to the history, above the blank line.
        let again = assert_rating_keeps_cards(&patched, 1);
        assert!(
            again.contains("13:45 - Good\n  * 2026-10-06 13:45 - Good\n\nQ2\n"),
            "{again}"
        );
    }

    /// A term may be indented up to three spaces. One space after a closed
    /// fence keeps `Q2` outside the definition (whose content column is two),
    /// so it is a card — and must stay one.
    #[test]
    fn an_indented_term_glued_to_a_closed_fence_stays_a_term() {
        let source = "Q1\n: A1\n\n  ```\n  code\n  ```\n Q2\n: A2\n";
        assert_eq!(rendered_terms(source), ["Q1", "Q2"]);
        let patched = assert_rating_keeps_cards(source, 1);
        assert_eq!(
            patched,
            concat!(
                "Q1\n: A1\n\n  ```\n  code\n  ```\n",
                ": ___Review History___\n",
                "  * 2026-10-06 13:45 - Good\n",
                "\n",
                " Q2\n: A2\n",
            )
        );
        // Rating the indented card itself works too.
        assert_rating_keeps_cards(source, 7);
        // Two or three spaces put the line inside `Q1`'s definition instead
        // (a paragraph after the fence): not a card, before or after.
        for indent in ["  ", "   "] {
            let inside = source.replace("\n Q2", &format!("\n{indent}Q2"));
            assert_eq!(rendered_terms(&inside), ["Q1"], "{inside:?}");
            assert_rating_keeps_cards(&inside, 1);
        }
    }

    /// The same trap one level down: the history's last bullet ends in a
    /// fence, and the next card's term is glued to it.
    #[test]
    fn a_term_glued_to_a_history_bullet_ending_in_a_fence_stays_a_term() {
        for indent in ["", " "] {
            let source = format!(
                concat!(
                    "Q1\n",
                    ": A1\n",
                    ": ___Review History___\n",
                    "  * 2026-10-01 08:00 - Good\n",
                    "\n",
                    "    ```\n",
                    "    x\n",
                    "    ```\n",
                    "{}Q2\n",
                    ": A2\n",
                ),
                indent
            );
            assert_eq!(rendered_terms(&source), ["Q1", "Q2"], "{source:?}");
            let patch = append(&source, 1).unwrap();
            assert_eq!(
                patch.inserted,
                vec!["  * 2026-10-06 13:45 - Good", ""],
                "{source:?}"
            );
            assert_eq!((patch.inserted_at, patch.entry_line()), (9, 9));
            let again = assert_rating_keeps_cards(&assert_rating_keeps_cards(&source, 1), 1);
            assert_eq!(rendered_terms(&again), ["Q1", "Q2"]);
        }
    }

    /// The re-parse refuses a patch that would swallow the next card, which is
    /// what the glued-line rule exists to avoid.
    #[test]
    fn verification_rejects_a_patch_that_swallows_a_card() {
        let source = "Q1\n: A1\n\n  ```\n  code\n  ```\n Q2\n: A2\n";
        let inserted = vec![
            ": ___Review History___".to_string(),
            "  * 2026-10-06 13:45 - Good".to_string(),
        ];
        let bad = ReviewPatch {
            source: insert_lines_after(source, 6, &inserted, "\n"),
            entry: "2026-10-06 13:45 - Good".to_string(),
            inserted_at: 7,
            inserted,
        };
        assert_eq!(rendered_terms(&bad.source), ["Q1"], "the patch is bad");
        let term_lines: Vec<u32> = scan_terms(source).iter().map(|t| t.line).collect();
        assert_eq!(term_lines, [1, 7]);
        assert!(!keeps_every_card(&bad, &term_lines, 1));
        assert!(keeps_every_card(
            &append(source, 1).unwrap(),
            &term_lines,
            1
        ));
    }

    /// Five or more columns after `:` make the answer an indented code block.
    /// Copying that prefix onto the history label would make it code too:
    /// never recognised, so every review would add another history.
    #[test]
    fn a_wide_or_tabbed_answer_gap_is_not_copied_onto_the_history() {
        for source in [
            "Q?\n:     A\n",
            "Q?\n:\t\tA\n",
            "Q?\n: \tA\n",
            "Q?\n:      A\n",
        ] {
            let mut patched = source.to_string();
            for minute in 0..3 {
                patched = append_review(&patched, 1, "Q?", Rating::Good, at(10, minute))
                    .unwrap()
                    .source;
            }
            assert_eq!(
                patched,
                format!(
                    "{source}: ___Review History___\n  * 2026-10-06 10:00 - Good\n  * 2026-10-06 10:01 - Good\n  * 2026-10-06 10:02 - Good\n"
                ),
                "{source:?}"
            );
            let terms = scan_terms(&patched);
            assert_eq!(terms.len(), 1);
            assert_eq!(
                terms[0].definitions.iter().filter(|d| d.history).count(),
                1,
                "{patched:?}"
            );
        }
        // Up to four spaces is ordinary content, and is copied with its indent.
        assert_eq!(
            appended("Q?\n:    A\n", 1),
            "Q?\n:    A\n:    ___Review History___\n     * 2026-10-06 13:45 - Good\n"
        );
        assert_eq!(
            appended("Q?\n : A\n", 1),
            "Q?\n : A\n : ___Review History___\n   * 2026-10-06 13:45 - Good\n"
        );
    }

    // ---- a real deck: multi-line terms, quoted and bulleted answers ---------

    /// One card exactly as a user's deck writes it: a bold question paragraph,
    /// a blank line, the four choices as the (multi-line) term, then answers
    /// including a blockquote and a `Memory aids:` answer with an indented
    /// `  * ` bullet. `{n}` names the card; `{history}` is the tail after
    /// `: Memory aids:`'s bullet (empty for a card never reviewed).
    fn ham_card(n: u32, history: &str) -> String {
        format!(
            concat!(
                "**T1-A{n:02}: Who selects a Frequency Coordinator?**\n",
                "\n",
                "A. The FCC Office of Spectrum Management and Coordination Policy\n",
                "B. The local chapter of the Office of National Council of Independent Frequency Coordinators\n",
                "C. Amateur operators in a local or regional area whose stations are eligible to be repeater or auxiliary stations\n",
                "D. The FCC Regional Field Office\n",
                ": **C.** Amateur operators in a local or regional area whose stations are eligible to be repeater or auxiliary stations\n",
                ": **47 CFR 97.3(a)(22):**\n",
                ": > **Frequency coordinator.** An entity, ***recognized in a local or regional area by amateur operators whose stations are eligible to be auxiliary or repeater stations,*** that recommends transmit/receive channels and associated operating and technical parameters for such stations in order to avoid or minimize potential interference.\n",
                ": Frequency coordinators are amateur radio operators who are recognized by other local or regional amateurs (particularly those who operate repeaters or auxiliary stations). They recommend which transmit/receive channels and what operating and technical parameters should be used so repeaters don't interfere with one another. This local recognition means the coordinators are chosen by the amateur community in the area rather than by an FCC office.\n",
                ": Coordination is important because if an operator ignores the locally established band plan or the coordinator's recommendations, they might transmit on or near a repeater input and cause harmful interference to others.\n",
                ": Memory aids:\n",
                "  * Remember: \"Frequency coordinator\" = someone recognized by local/regional amateur operators (not an FCC office).\n",
                "{history}",
            ),
            n = n,
            history = history,
        )
    }

    /// The term line of a [`ham_card`] — line 3 of the card: the `<dt>` is the
    /// `A.`–`D.` paragraph, not the bold question, which is a `<p>` before the
    /// `<dl>`.
    const HAM_TERM: &str = "A. The FCC Office of Spectrum Management and Coordination Policy";
    const HAM_TERM_OFFSET: u32 = 2;
    const HAM_REMEMBER: &str = "  * Remember: \"Frequency coordinator\"";
    const HAM_HISTORY: &str = ": ___Review History___\n  * 2026-10-07 14:53 - Good\n";

    /// `source` rendered by the real page pipeline ([`crate::markdown::render_str`]
    /// with `data-mbr-line` on, as the server renders a deck).
    fn render_page(source: &str) -> String {
        use crate::link_transform::LinkTransformConfig;
        use crate::markdown::{RenderOptions, ReviewLines, render_str};
        let root = std::path::Path::new("/nonexistent-root");
        let opts = RenderOptions {
            root_path: root,
            oembed_timeout_ms: 0,
            link_transform_config: LinkTransformConfig {
                markdown_extensions: vec!["md".to_string()],
                index_file: "index.md".to_string(),
                is_index_file: false,
                url_depth: None,
                current_page_url: String::new(),
                markdown_page_probe: None,
            },
            oembed_cache: None,
            server_mode: true,
            transcode_enabled: false,
            valid_tag_sources: Default::default(),
            review: ReviewLines::Emit,
            mark_incomplete: false,
            incomplete_markers: &[],
            wikilink_index: None,
        };
        render_str(source, std::path::Path::new("deck.md"), opts)
            .expect("renders")
            .html
    }

    /// Every `data-mbr-line` on a rendered `<dt>` — what the deck sends as
    /// `line`.
    fn page_term_lines(html: &str) -> Vec<u32> {
        html.match_indices("<dt data-mbr-line=\"")
            .map(|(at, prefix)| {
                let rest = &html[at + prefix.len()..];
                rest[..rest.find('"').expect("closing quote")]
                    .parse()
                    .expect("numeric line")
            })
            .collect()
    }

    /// Asserts every list item of the page sits inside a `<dd>` of a `<dl>`:
    /// the `Memory aids` bullet and each history entry, never a stray `<ul>`
    /// after the list. Returns the number of `<dl>`s.
    fn assert_bullets_inside_definitions(html: &str, entries: &[&str]) -> usize {
        let mut outside = html.to_string();
        let mut lists = 0;
        while let Some(open) = outside.find("<dl>") {
            let close = open + outside[open..].find("</dl>").expect("closed dl") + "</dl>".len();
            let list = outside[open..close].to_string();
            assert!(list.contains("<li"), "a <dl> without its bullets: {html}");
            outside.replace_range(open..close, "");
            lists += 1;
        }
        assert!(!outside.contains("<li"), "a bullet left the <dl>: {html}");
        assert!(!outside.contains("<ul"), "a list left the <dl>: {html}");
        for entry in entries {
            assert!(html.contains(entry), "{entry:?} missing: {html}");
        }
        // Each card's `Memory aids` answer still owns its bullet.
        let answers = html.matches("Memory aids:").count();
        assert!(answers > 0, "{html}");
        assert_eq!(
            html.matches("Memory aids:\n<ul>\n<li").count(),
            answers,
            "{html}"
        );
        lists
    }

    /// Asserts `patch` is `before` with `patch.inserted` spliced in at
    /// `patch.inserted_at` and not one other byte changed.
    fn assert_pure_insert(before: &str, patch: &ReviewPatch) {
        let terminator = if before.contains("\r\n") {
            "\r\n"
        } else {
            "\n"
        };
        let mut lines: Vec<&str> = before.split(terminator).collect();
        let at = patch.inserted_at as usize - 1;
        // A file with no trailing newline gains the terminator before the
        // insert, not after it.
        let unterminated_tail = !before.ends_with('\n') && at == lines.len();
        for (i, line) in patch.inserted.iter().enumerate() {
            lines.insert(at + i, line);
        }
        let rebuilt = lines.join(terminator);
        assert_eq!(patch.source, rebuilt, "inserted {:?}", patch.inserted);
        if unterminated_tail {
            assert!(!patch.source.ends_with('\n'));
        }
    }

    fn ham_append(source: &str, line: u32, rating: Rating, minute: u32) -> ReviewPatch {
        let patch = append_review(source, line, HAM_TERM, rating, at(13, minute))
            .unwrap_or_else(|e| panic!("append at {line}: {e:?}\n{source}"));
        assert_pure_insert(source, &patch);
        patch
    }

    /// The reported corruption — a blank line, then the bullets at column 0 —
    /// takes them out of the `<dl>`. Pins that the checks above can see it, so
    /// their passing means the writer does not produce it.
    #[test]
    fn ham_deck_reported_corruption_moves_bullets_out_of_the_list() {
        let good = ham_card(9, HAM_HISTORY);
        let broken = good
            .replace("\n  * Remember", "\n\n* Remember")
            .replace("\n  * 2026", "\n\n* 2026");
        let html = render_page(&broken);
        let remember = html.find("Remember: ").expect("rendered");
        let dl_end = html.find("</dl>").expect("a <dl>");
        assert!(dl_end < remember, "{html}");
        assert!(
            std::panic::catch_unwind(|| assert_bullets_inside_definitions(&html, &[])).is_err()
        );
        assert!(
            std::panic::catch_unwind(|| {
                assert_bullets_inside_definitions(&render_page(&good), &[])
            })
            .is_ok()
        );
    }

    #[test]
    fn ham_deck_term_is_the_choices_paragraph() {
        let source = ham_card(9, HAM_HISTORY);
        let html = render_page(&source);
        assert_eq!(page_term_lines(&html), vec![3], "{html}");
        assert_eq!(
            scan_terms(&source)
                .iter()
                .map(|t| t.line)
                .collect::<Vec<_>>(),
            vec![3]
        );
        assert!(
            html.contains("<p data-mbr-line=\"1\"><strong>T1-A09"),
            "{html}"
        );
        assert_bullets_inside_definitions(&html, &["2026-10-07 14:53 - Good"]);
        // The bold question is not the term, so it is not a valid `expected`.
        let question = "**T1-A09: Who selects a Frequency Coordinator?**";
        assert_eq!(
            append_review(&source, 1, question, Rating::Good, at(13, 45)),
            Err(FlashcardPatchError::NotATerm { line: 1 })
        );
    }

    #[test]
    fn ham_deck_appends_one_bullet_after_the_history() {
        let source = ham_card(9, HAM_HISTORY);
        let patch = ham_append(&source, 3, Rating::Good, 45);
        assert_eq!(
            patch.source,
            format!("{source}  * 2026-10-06 13:45 - Good\n"),
            "only the new bullet, after the last one"
        );
        assert_eq!(patch.inserted, vec!["  * 2026-10-06 13:45 - Good"]);
        assert_eq!(patch.inserted_at, 16);
        assert_eq!(patch.entry_line(), 16);
        assert!(patch.source.contains(&format!("\n{HAM_REMEMBER}")));
        assert!(
            !patch.source.contains("\n\n  *"),
            "no blank before a bullet"
        );
        let html = render_page(&patch.source);
        assert_eq!(page_term_lines(&html), vec![3]);
        assert_bullets_inside_definitions(
            &html,
            &["2026-10-07 14:53 - Good", "2026-10-06 13:45 - Good"],
        );
    }

    #[test]
    fn ham_deck_first_review_creates_history_after_memory_aids_bullet() {
        let source = ham_card(9, "");
        let patch = ham_append(&source, 3, Rating::Hard, 45);
        assert_eq!(
            patch.source,
            format!("{source}: ___Review History___\n  * 2026-10-06 13:45 - Hard\n")
        );
        assert_eq!(patch.inserted_at, 14, "right after the Remember bullet");
        let html = render_page(&patch.source);
        assert_bullets_inside_definitions(&html, &["2026-10-06 13:45 - Hard"]);
        assert!(
            html.contains(
                "<dd data-mbr-line=\"14\"><em><strong>Review History</strong></em>\n<ul>"
            ),
            "{html}"
        );
    }

    #[test]
    fn ham_deck_with_several_history_entries() {
        let history = concat!(
            ": ___Review History___\n",
            "  * 2026-10-01 08:00 - Again\n",
            "  * 2026-10-03 09:10 - Hard\n",
            "  * 2026-10-07 14:53 - Good\n",
        );
        let source = ham_card(9, history);
        let patch = ham_append(&source, 3, Rating::Easy, 45);
        assert_eq!(
            patch.source,
            format!("{source}  * 2026-10-06 13:45 - Easy\n")
        );
        assert_eq!(patch.inserted_at, 18);
        assert_bullets_inside_definitions(&render_page(&patch.source), &["13:45 - Easy"]);
    }

    /// Five sequential reviews of the user's card: each one only appends,
    /// the `Memory aids` bullet never moves, and the page keeps one `<dl>`.
    #[test]
    fn ham_deck_is_stable_over_repeated_reviews() {
        for start in ["", HAM_HISTORY] {
            let original = ham_card(9, start);
            let mut source = original.clone();
            let mut expected_tail = if start.is_empty() {
                ": ___Review History___\n".to_string()
            } else {
                start.to_string()
            };
            let ratings = [
                Rating::Again,
                Rating::Hard,
                Rating::Good,
                Rating::Easy,
                Rating::Good,
            ];
            for (minute, rating) in (0u32..).zip(ratings) {
                let patch = ham_append(&source, 3, rating, minute);
                source = patch.source;
                expected_tail.push_str(&format!(
                    "  * 2026-10-06 13:{minute:02} - {}\n",
                    rating.label()
                ));
                assert_eq!(source, format!("{}{expected_tail}", ham_card(9, "")));
                let html = render_page(&source);
                assert_eq!(page_term_lines(&html), vec![3]);
                assert_eq!(assert_bullets_inside_definitions(&html, &[]), 1);
                assert_eq!(
                    html.matches("Review History").count(),
                    1,
                    "one history: {html}"
                );
            }
            assert!(source.starts_with(&original[..original.len() - start.len()]));
        }
    }

    /// Three cards separated by blank lines, the first and last with
    /// history, the middle one without: each review lands under its own card,
    /// addressed by the `<dt>` line the page renders after the previous write.
    #[test]
    fn ham_deck_several_cards_in_a_row() {
        let cards = [
            ham_card(1, HAM_HISTORY),
            ham_card(2, ""),
            ham_card(3, HAM_HISTORY),
        ];
        let mut source = cards.join("\n");
        let mut cards = cards.to_vec();
        // Review middle, last, first, middle again.
        for (minute, card) in [1usize, 2, 0, 1].into_iter().enumerate() {
            let lines = page_term_lines(&render_page(&source));
            assert_eq!(lines.len(), 3, "{source}");
            assert_eq!(
                lines,
                scan_terms(&source)
                    .iter()
                    .map(|t| t.line)
                    .collect::<Vec<_>>()
            );
            let minute = u32::try_from(minute).unwrap();
            let patch = ham_append(&source, lines[card], Rating::Good, minute);
            let bullet = format!("  * 2026-10-06 13:{minute:02} - Good\n");
            if !cards[card].contains("Review History") {
                cards[card].push_str(": ___Review History___\n");
            }
            cards[card].push_str(&bullet);
            source = patch.source;
            assert_eq!(source, cards.join("\n"));
            let html = render_page(&source);
            assert_eq!(assert_bullets_inside_definitions(&html, &[]), 3, "{html}");
        }
        // Every card's term moved only by the lines inserted above it.
        let first_len = u32::try_from(cards[0].lines().count()).unwrap();
        let second_len = u32::try_from(cards[1].lines().count()).unwrap();
        assert_eq!(
            page_term_lines(&render_page(&source)),
            vec![
                1 + HAM_TERM_OFFSET,
                first_len + 2 + HAM_TERM_OFFSET,
                first_len + second_len + 3 + HAM_TERM_OFFSET,
            ]
        );
    }

    #[test]
    fn ham_deck_crlf() {
        let source = ham_card(9, HAM_HISTORY).replace('\n', "\r\n");
        let patch = ham_append(&source, 3, Rating::Good, 45);
        assert_eq!(
            patch.source,
            format!("{source}  * 2026-10-06 13:45 - Good\r\n")
        );
        let fresh = ham_card(9, "").replace('\n', "\r\n");
        let patch = ham_append(&fresh, 3, Rating::Good, 45);
        assert_eq!(
            patch.source,
            format!("{fresh}: ___Review History___\r\n  * 2026-10-06 13:45 - Good\r\n")
        );
        assert_bullets_inside_definitions(&render_page(&patch.source), &["13:45 - Good"]);
    }

    #[test]
    fn ham_deck_without_trailing_newline() {
        let with = ham_card(9, HAM_HISTORY);
        let source = with.trim_end_matches('\n');
        let patch = ham_append(source, 3, Rating::Good, 45);
        assert_eq!(
            patch.source,
            format!("{source}\n  * 2026-10-06 13:45 - Good")
        );
        let fresh = ham_card(9, "");
        let fresh = fresh.trim_end_matches('\n');
        let patch = ham_append(fresh, 3, Rating::Good, 45);
        assert_eq!(
            patch.source,
            format!("{fresh}\n: ___Review History___\n  * 2026-10-06 13:45 - Good")
        );
        assert_bullets_inside_definitions(&render_page(&patch.source), &["13:45 - Good"]);
    }

    /// The next card's question glued to the history bullet (no blank line)
    /// is, before any write, a lazy continuation of that bullet — the page
    /// shows it inside the history, and both cards share one `<dl>`. The write
    /// must not change what the page shows beyond adding the entry: the second
    /// card's term stays a term, and nothing is outdented or separated.
    #[test]
    fn ham_deck_second_card_glued_after_the_history() {
        for first in [HAM_HISTORY, ""] {
            let source = format!("{}{}", ham_card(1, first), ham_card(2, HAM_HISTORY));
            let html = render_page(&source);
            let lines = page_term_lines(&html);
            assert_eq!(lines.len(), 2, "{html}");
            // Already one `<dl>`: the glued question continues the bullet.
            let lists = assert_bullets_inside_definitions(&html, &[]);
            assert_eq!(lists, 1, "{html}");
            for &line in &lines {
                let patch = ham_append(&source, line, Rating::Good, 45);
                let after = render_page(&patch.source);
                assert_eq!(
                    page_term_lines(&after).len(),
                    2,
                    "a card was lost: {}",
                    patch.source
                );
                assert!(after.contains("2026-10-06 13:45 - Good"), "{after}");
                assert_eq!(
                    patch.source.matches(HAM_REMEMBER).count(),
                    2,
                    "{}",
                    patch.source
                );
                assert_eq!(
                    assert_bullets_inside_definitions(&after, &[]),
                    lists,
                    "{after}"
                );
            }
        }
    }

    // ---- T1-B11: the second damaged card ------------------------------------

    /// T1-B11 as it presumably was before it was damaged: two indented
    /// `Memory aids` bullets, then `{history}`.
    fn b11_card(history: &str) -> String {
        format!(
            concat!(
                "**T1-B11: What is the maximum peak envelope power output for Technician class operators in their HF band segments?**\n",
                "\n",
                "A. 200 watts\n",
                "B. 100 watts\n",
                "C. 50 watts\n",
                "D. 10 watts\n",
                ": **A.** 200 watts\n",
                ": Technician-class operators are limited to 200 watts PEP (Peak Envelope Power) on any portion of an HF band that they are authorized to use. This is an FCC regulation that must be memorized for the exam.\n",
                ": Also remember that FCC rule 97.313 requires stations to use the minimum transmitter power necessary to carry out the desired communications, even though the maximum allowed for Technician HF segments is 200 W PEP.\n",
                ": Memory aids:\n",
                "  * \"HF\" has 2 letters → 2-hundred watts (200 W)\n",
                "  * The word \"maximum\" corresponds to the largest numeric choice\n",
                "{history}",
            ),
            history = history,
        )
    }

    /// The card exactly as found on disk.
    const B11_DAMAGED: &str = concat!(
        "**T1-B11: What is the maximum peak envelope power output for Technician class operators in their HF band segments?**\n",
        "\n",
        "A. 200 watts\n",
        "B. 100 watts\n",
        "C. 50 watts\n",
        "D. 10 watts\n",
        ": **A.** 200 watts\n",
        ": Technician-class operators are limited to 200 watts PEP (Peak Envelope Power) on any portion of an HF band that they are authorized to use. This is an FCC regulation that must be memorized for the exam.\n",
        ": Also remember that FCC rule 97.313 requires stations to use the minimum transmitter power necessary to carry out the desired communications, even though the maximum allowed for Technician HF segments is 200 W PEP.\n",
        ": Memory aids:\n",
        "\n",
        "* \"HF\" has 2 letters → 2-hundred watts (200 W)\n",
        "* The word \"maximum\" corresponds to the largest numeric choice\n",
        "  : ___Review History___\n",
        "* 2026-10-07 14:54 - Again\n",
    );
    const B11_TERM: &str = "A. 200 watts";

    fn b11_append(source: &str, minute: u32) -> ReviewPatch {
        let patch = append_review(source, 3, B11_TERM, Rating::Again, at(14, minute))
            .unwrap_or_else(|e| panic!("{e:?}\n{source}"));
        assert_pure_insert(source, &patch);
        patch
    }

    /// The writer's own first review of a card whose last answer ends in an
    /// indented bullet: the label takes the answer's *first* line's `: `
    /// prefix (column 0), never the bullet's indent, and the entry is indented
    /// under it — not `  : ___Review History___` and `* …` at column 0, which
    /// is the damage found on disk.
    #[test]
    fn b11_first_review_labels_at_column_zero_after_the_bullets() {
        let source = b11_card("");
        let patch = b11_append(&source, 54);
        assert_eq!(
            patch.inserted,
            vec![": ___Review History___", "  * 2026-10-06 14:54 - Again"]
        );
        assert_eq!(patch.inserted_at, 13, "after the second Memory aids bullet");
        assert_eq!(
            patch.source,
            format!("{source}: ___Review History___\n  * 2026-10-06 14:54 - Again\n")
        );
        let html = render_page(&patch.source);
        assert_bullets_inside_definitions(
            &html,
            &["2 letters", "largest numeric", "14:54 - Again"],
        );
        assert!(!patch.source.contains("\n  : "), "{}", patch.source);
        assert!(!patch.source.contains("\n* "), "{}", patch.source);
        assert!(!patch.source.contains(":\n\n"), "{}", patch.source);
    }

    /// From either original form — no history yet, or one with entries — no
    /// number of reviews produces the damaged shape.
    #[test]
    fn b11_repeated_reviews_never_produce_the_damage() {
        for history in ["", ": ___Review History___\n  * 2026-10-05 09:00 - Good\n"] {
            let mut source = b11_card(history);
            for minute in 0..5 {
                source = b11_append(&source, minute).source;
                assert!(!source.contains("\n  : "), "{source}");
                assert!(!source.contains("\n* "), "{source}");
                assert!(!source.contains(":\n\n"), "{source}");
                let html = render_page(&source);
                assert_eq!(page_term_lines(&html), vec![3]);
                assert_eq!(assert_bullets_inside_definitions(&html, &[]), 1, "{html}");
                assert_eq!(html.matches("Review History").count(), 1, "{html}");
            }
            let entries = (0..5)
                .map(|m| format!("  * 2026-10-06 14:{m:02} - Again\n"))
                .collect::<String>();
            let label = if history.is_empty() {
                ": ___Review History___\n"
            } else {
                ""
            };
            assert_eq!(source, format!("{}{label}{entries}", b11_card(history)));
        }
    }

    /// On the damaged file the card has no history the parser can see: the
    /// blank line ends the `<dl>` after `: Memory aids:`, and the bullets, the
    /// indented label (a lazy continuation of the second bullet) and the old
    /// entry are an ordinary list after it. The writer therefore treats the
    /// card as never reviewed and creates a fresh history *inside* the `<dl>`
    /// right after `: Memory aids:` — a pure insert, so it neither moves nor
    /// repairs the stray list, and the old entry stays outside (unread by
    /// the deck, which reads history from the `<dd>`).
    ///
    /// The indented label also makes the second stray bullet a *nested*
    /// definition list (term `The word "maximum" …`, line 13). Nested lists
    /// are not cards on either side — `scan_terms` and the deck's `dom.ts`
    /// both take top-level lists only — so a review addressed there is
    /// `NotATerm`.
    #[test]
    fn b11_damaged_file_gets_a_fresh_history_inside_the_list() {
        let html = render_page(B11_DAMAGED);
        assert_eq!(page_term_lines(&html), vec![3, 13], "{html}");
        assert_eq!(
            scan_terms(B11_DAMAGED)
                .iter()
                .map(|t| t.line)
                .collect::<Vec<_>>(),
            vec![3]
        );
        let nested = B11_DAMAGED.lines().nth(12).unwrap();
        assert_eq!(
            append_review(B11_DAMAGED, 13, nested, Rating::Good, at(14, 54)),
            Err(FlashcardPatchError::NotATerm { line: 13 })
        );
        let dl_end = html.find("</dl>").expect("a <dl>");
        assert!(dl_end < html.find("2 letters").unwrap(), "{html}");
        assert!(!html[..dl_end].contains("Review History"), "{html}");

        let patch = b11_append(B11_DAMAGED, 54);
        assert_eq!(patch.inserted_at, 11, "right after `: Memory aids:`");
        assert_eq!(
            patch.inserted,
            vec![": ___Review History___", "  * 2026-10-06 14:54 - Again"]
        );
        let html = render_page(&patch.source);
        let dl_end = html.find("</dl>").expect("a <dl>");
        assert!(html[..dl_end].contains("<em><strong>Review History</strong></em>\n<ul>"));
        assert!(html[..dl_end].contains("14:54 - Again"), "{html}");
        // The old, damaged block is untouched and still outside.
        assert!(
            html[dl_end..].contains("2026-10-07 14:54 - Again"),
            "{html}"
        );
        // A second review lands in the new history, not the stray list.
        let second = b11_append(&patch.source, 55);
        assert_eq!(second.inserted, vec!["  * 2026-10-06 14:55 - Again"]);
        assert_eq!(second.inserted_at, 13);
    }

    // ---- properties ---------------------------------------------------------

    /// One generated card: its term, its answers and an optional history.
    #[derive(Debug, Clone)]
    struct GenCard {
        loose: bool,
        /// No blank line between this card's term and the previous card.
        glued: bool,
        /// Spaces in front of a glued term (0–3; a term may be indented).
        indent: usize,
        answers: Vec<u8>,
        history: Option<(char, Vec<u8>)>,
    }

    impl GenCard {
        /// Whether a term glued straight after this card is a term of its
        /// own. Only when the card's last definition ends in a closed fence
        /// (answer kind 3, no history): anything ending in a paragraph — a
        /// one-line answer, a list item, a history label or bullet — takes
        /// the glued line as a lazy continuation instead.
        fn ends_in_a_fence(&self) -> bool {
            self.history.is_none() && self.answers.last().is_some_and(|kind| kind % 5 == 3)
        }
    }

    /// Answer shapes, by index — single line, multi-line continuation, nested
    /// list, code fence holding a fake definition, and an inline-code answer.
    fn answer_text(kind: u8, n: usize) -> String {
        match kind % 5 {
            0 => format!(": answer {n}"),
            1 => format!(": answer {n} line one\n  and line two"),
            2 => format!(": list {n}:\n  * a{n}\n  * b{n}"),
            3 => format!(": code {n}\n\n  ```\n  : fake {n}\n  Fake term?\n  ```"),
            _ => format!(": `code {n}` answer"),
        }
    }

    fn history_text(marker: char, entries: &[u8]) -> String {
        let mut text = String::from(": ___Review History___");
        for (i, kind) in entries.iter().enumerate() {
            let rating = ["Again", "Fail", "Hard", "Good", "Easy", "garbage"][*kind as usize % 6];
            text.push_str(&format!(
                "\n  {marker} 2026-09-{:02} 10:00 - {rating}",
                i + 1
            ));
        }
        text
    }

    fn gen_card() -> impl Strategy<Value = GenCard> {
        (
            any::<bool>(),
            any::<bool>(),
            0usize..4,
            prop::collection::vec(0u8..5, 1..4),
            prop::option::of((
                prop::sample::select(vec!['*', '-']),
                prop::collection::vec(0u8..6, 0..4),
            )),
        )
            .prop_map(|(loose, glued, indent, answers, history)| GenCard {
                loose,
                glued,
                indent,
                answers,
                history,
            })
    }

    /// A document: optional frontmatter, then deflists (separated by a
    /// paragraph or a fenced block of fake cards), with chosen line endings.
    fn gen_document() -> impl Strategy<Value = (String, Vec<u32>)> {
        (
            any::<bool>(),
            prop::collection::vec(prop::collection::vec(gen_card(), 1..4), 1..4),
            any::<bool>(),
            any::<bool>(),
        )
            .prop_map(|(frontmatter, lists, crlf, trailing_newline)| {
                let mut blocks: Vec<String> = Vec::new();
                if frontmatter {
                    blocks.push("---\ntype: flashcard\n---".to_string());
                }
                let mut term_index = 0usize;
                for (list_index, cards) in lists.iter().enumerate() {
                    if list_index > 0 {
                        blocks.push(if list_index % 2 == 0 {
                            "Some prose between lists.".to_string()
                        } else {
                            "```\nFake?\n: fake\n```".to_string()
                        });
                    }
                    for (card_index, card) in cards.iter().enumerate() {
                        term_index += 1;
                        let separator = if card.loose { "\n\n" } else { "\n" };
                        let mut definitions: Vec<String> = card
                            .answers
                            .iter()
                            .map(|kind| answer_text(*kind, term_index))
                            .collect();
                        if let Some((marker, entries)) = &card.history {
                            definitions.push(history_text(*marker, entries));
                        }
                        let previous = card_index.checked_sub(1).map(|i| &cards[i]);
                        let glued = card.glued && previous.is_some();
                        // A glued line that the parser will read as a lazy
                        // continuation is not a term, so it must not be named
                        // like one: `terms` below is the generator's own
                        // prediction, checked against the scanner. After a
                        // fence, two or more spaces reach the definition's
                        // content column (2), making the line a paragraph
                        // inside it rather than a term.
                        let indent = if glued { card.indent } else { 0 };
                        let is_term = !glued
                            || (previous.is_some_and(GenCard::ends_in_a_fence) && indent < 2);
                        let name = if is_term { "Term" } else { "Glued" };
                        let card_text = format!(
                            "{}{name} {term_index}?{separator}{}",
                            " ".repeat(indent),
                            definitions.join(separator)
                        );
                        match blocks.last_mut() {
                            Some(last) if glued => {
                                last.push('\n');
                                last.push_str(&card_text);
                            }
                            _ => blocks.push(card_text),
                        }
                    }
                }
                let mut text = blocks.join("\n\n");
                if trailing_newline {
                    text.push('\n');
                }
                let terms: Vec<u32> = text
                    .split('\n')
                    .enumerate()
                    .filter(|(_, line)| line.trim_start().starts_with("Term "))
                    .map(|(i, _)| i as u32 + 1)
                    .collect();
                if crlf {
                    text = text.replace('\n', "\r\n");
                }
                (text, terms)
            })
    }

    /// What a card means, independent of where its bytes are: the term line's
    /// text, each answer's trimmed source, and the history item count.
    fn outline(source: &str) -> Vec<(String, Vec<String>, Option<usize>)> {
        scan_terms(source)
            .iter()
            .map(|term| {
                let term_text =
                    line_containing(source, line_span(source, term.line).unwrap().start);
                let answers = term
                    .definitions
                    .iter()
                    .filter(|d| !d.history)
                    .map(|d| source[d.range.clone()].trim_end().to_string())
                    .collect();
                let history = term.definitions.iter().find(|d| d.history).map(|d| {
                    let text = &source[d.range.clone()];
                    text.lines()
                        .filter(|line| line.trim_start().starts_with(['*', '-']))
                        .count()
                });
                (term_text.to_string(), answers, history)
            })
            .collect()
    }

    proptest! {
        /// Appending to one card changes nothing but that card's history,
        /// which gains exactly one entry — and the new entry is findable.
        #[test]
        fn append_adds_exactly_one_history_entry(
            (source, terms) in gen_document(),
            pick in any::<prop::sample::Index>(),
            rating in prop::sample::select(vec![Rating::Again, Rating::Hard, Rating::Good, Rating::Easy]),
        ) {
            let before = outline(&source);
            prop_assert_eq!(before.len(), terms.len(), "generator and scanner agree: {:?}", source);

            let target = pick.index(terms.len());
            let line = terms[target];
            let expected = line_containing(&source, line_span(&source, line).unwrap().start).to_string();
            let patch = append_review(&source, line, &expected, rating, at(13, 45)).unwrap();
            let after = outline(&patch.source);

            prop_assert_eq!(after.len(), before.len());
            for (i, (b, a)) in before.iter().zip(&after).enumerate() {
                prop_assert_eq!(&b.0, &a.0, "term text");
                prop_assert_eq!(&b.1, &a.1, "answers of term {}", i);
                if i == target {
                    prop_assert_eq!(a.2, Some(b.2.unwrap_or(0) + 1), "{}", patch.source);
                } else {
                    prop_assert_eq!(b.2, a.2);
                }
            }

            // The inserted lines are where the patch says they are.
            let lines: Vec<&str> = patch.source.split('\n').map(|l| l.trim_end_matches('\r')).collect();
            for (offset, inserted) in patch.inserted.iter().enumerate() {
                prop_assert_eq!(lines[patch.inserted_at as usize - 1 + offset], inserted.as_str());
            }
            prop_assert!(lines[patch.entry_line() as usize - 1].ends_with(&patch.entry));

            // Terminator style and trailing-newline presence are preserved.
            let crlf = source.contains("\r\n");
            prop_assert_eq!(crlf, patch.source.contains("\r\n"));
            if crlf {
                prop_assert_eq!(
                    patch.source.matches('\n').count(),
                    patch.source.matches("\r\n").count(),
                    "no bare LF in a CRLF file"
                );
            }
            prop_assert_eq!(source.ends_with('\n'), patch.source.ends_with('\n'));
            prop_assert_eq!(
                patch.source.split('\n').count(),
                source.split('\n').count() + patch.inserted.len()
            );
        }

        /// Arbitrary input never panics.
        #[test]
        fn append_never_panics(source in "(?s).{0,200}", line in 0u32..20, expected in ".{0,20}") {
            let _ = append_review(&source, line, &expected, Rating::Good, at(1, 2));
        }

        /// Arbitrary input made of markdown-ish pieces never panics either, and
        /// any success re-parses with the term still in place.
        #[test]
        fn append_on_markdownish_input_never_panics(
            pieces in prop::collection::vec(
                prop::sample::select(vec![
                    "Q?", ": a", ": ___Review History___", "  * x", "  - 2026-01-01 00:00 - Good",
                    "", "```", "> q", "- item", "  ```", ":", "  : nested", "\t* tab", "**Review History**",
                ]),
                0..24,
            ),
            line in 1u32..24,
        ) {
            let source = pieces.join("\n");
            let expected = source.split('\n').nth(line as usize - 1).unwrap_or_default().to_string();
            if let Ok(patch) = append_review(&source, line, &expected, Rating::Easy, at(1, 2)) {
                prop_assert!(scan_terms(&patch.source).iter().any(|t| t.line == line));
            }
        }
    }
}