mdbook-lini 0.5.2

//! Compiling one lini block into the figure that replaces it.

use std::path::Path;

use lini::{Diagnostic, Level, Options};

/// The wrapper a figure and its listing share. It must stay outside Lini's own
/// `.lini-<type>` namespace — every node in a diagram wears `.lini-box`,
/// `.lini-block` and the like, so a wrapper named for a type would restyle the
/// insides of every SVG on the page. `our_classes_are_ours_alone` guards it.
const BLOCK: &str = "lini-figure-block";

/// Open a drawn icon of `width` — the two marks below share everything but
/// their strokes, and neither may carry a newline.
const ICON_HEAD: &str = concat!(
    r#"<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" "#,
    r#"stroke-width="2.1" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">"#,
);

/// "Show the source": a pair of chevrons with air between them. A slash in the
/// middle only crowds it at this size.
const ICON_SOURCE: &str =
    r#"<path d="M9 6.5 3.5 12 9 17.5"/><path d="M15 6.5 20.5 12 15 17.5"/></svg>"#;

/// "Show the figure": a framed picture. Deliberately not a play triangle —
/// nothing runs here, the figure is already drawn and merely hidden, and a play
/// glyph would promise otherwise. Two linked nodes would say `lini` more
/// loudly, but at 18px the boxes collapse into a pair of dots.
const ICON_FIGURE: &str = concat!(
    r#"<rect x="3" y="4.75" width="18" height="14.5" rx="2.5"/>"#,
    r#"<circle cx="8.75" cy="10" r="1.5"/>"#,
    r#"<path d="M20.5 17.5 14.25 11.25 5 19.25"/></svg>"#,
);

/// What a block shows: which view leads, and what follows it.
///
/// A block has two views — the figure, and the source that drew it — and the
/// fence names them in the order they appear: `figure-code` is the figure and
/// then its source. A single word names the lead and leaves the other folded
/// behind the toggle, which is the default arrangement; `-only` says nothing
/// follows at all.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
struct Mode {
    lead: View,
    second: Second,
}

/// One of the two things a block can show. The fence spells [`View::Source`]
/// `code`, which is what a reader calls it.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum View {
    Figure,
    Source,
}

/// What follows the leading view.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Second {
    /// The default: folded behind the toggle button, one view on the page at
    /// a time.
    Folded,
    /// Named second in the fence — `figure-code`, `code-figure` — so it is on
    /// the page under the lead, with no toggle at all. For the block whose
    /// source *is* the lesson: a reader meeting the language for the first
    /// time should not have to discover a button to see what drew the picture.
    Shown,
    /// `-only`: there is no second view.
    None,
}

impl Mode {
    /// Whether the block needs the compiler.
    ///
    /// The source leading with nothing after it is the one arrangement that
    /// never puts a figure on the page, so `code-only` is also the fence that
    /// never compiles: a fragment, or a deliberate counter-example, stays a
    /// listing to read instead of becoming an error box — a consequence of
    /// the grammar rather than a word of its own.
    fn draws(self) -> bool {
        !(self.lead == View::Source && self.second == Second::None)
    }
}

/// Compile one block's source into its figure, and — unless the fence says
/// `figure-only` — the listing of the source with it.
///
/// A block that fails to compile becomes a visible error box and the message
/// goes to stderr — the build still finishes, so one bad diagram never costs
/// you the rest of the book.
pub fn render(
    source: &str,
    chapter: &str,
    first_line: usize,
    base_dir: Option<&Path>,
    words: &[&str],
) -> String {
    let mode = mode(words, chapter, first_line);

    // A block showing no figure never reaches the compiler, which is the whole
    // point of `code-only`: a fragment, a counter-example, or a deliberate
    // syntax error is a listing to read, not a figure that failed to draw.
    if !mode.draws() {
        return listing(source, "");
    }

    // Lini counts lines from the top of what it is handed, so pad the source
    // with the markdown standing above it. Diagnostics then read
    // `chapter.md:LINE:COL` against the real file.
    let padded = "\n".repeat(first_line - 1) + source;
    let options = Options { base_dir: base_dir.map(Path::to_path_buf), ..Options::default() };

    // Validation first: an unknown property or a malformed value costs us the
    // figure, exactly as it would on the command line.
    if let Some(fatal) = report(lini::lint_str(&padded).unwrap_or_default(), &padded, chapter) {
        return error_box(&fatal);
    }
    match lini::compile_str_checked(&padded, &options) {
        // Routing relaxations are warnings — the figure still draws.
        Ok((svg, routing)) => {
            report(routing, &padded, chapter);
            let id = toggle_id(chapter, first_line);
            match (mode.second, mode.lead) {
                // `figure-only`: the figure alone, and no wrapper — there is
                // no second view to position against it.
                (Second::None, _) => wrap(&svg),

                // Figure first: the control floats over the figure, which has
                // no button row of its own to join.
                (Second::Folded, View::Figure) => format!(
                    "<div class=\"{BLOCK}\">{figure}{toggle}{button}\
                     <div class=\"lini-alt-view\">{alt}</div></div>",
                    figure = wrap(&svg),
                    toggle = checkbox("source", &id),
                    button = button(ICON_SOURCE, "source", &id),
                    alt = listing(source, ""),
                ),
                // Source first: the control joins mdbook's own button row
                // inside the `<pre>` — see `listing`.
                (Second::Folded, View::Source) => format!(
                    "<div class=\"{BLOCK}\">{toggle}{code}\
                     <div class=\"lini-alt-view\">{alt}</div></div>",
                    toggle = checkbox("figure", &id),
                    code = listing(
                        source,
                        &format!(
                            "<span class=\"buttons\">{}</span>",
                            button(ICON_FIGURE, "figure", &id)
                        ),
                    ),
                    alt = wrap(&svg),
                ),

                // Both named: the two views stacked in the fence's order, with
                // no checkbox and no button. The second keeps the class the
                // toggled one wears — it is the same box in the same place —
                // and the rule that hides it is written against the checkbox,
                // so a block that emits none has nothing to hide it. The
                // wrapper says `lini-open` so a theme can tell the two
                // arrangements apart.
                (Second::Shown, lead) => {
                    let (first, second) = match lead {
                        View::Figure => (wrap(&svg), listing(source, "")),
                        View::Source => (listing(source, ""), wrap(&svg)),
                    };
                    format!(
                        "<div class=\"{BLOCK} lini-open\">{first}\
                         <div class=\"lini-alt-view\">{second}</div></div>"
                    )
                }
            }
        }
        Err(e) => {
            let text = e.display_with_source(&padded, chapter).to_string();
            eprintln!("mdbook-lini: {text}");
            error_box(&text)
        }
    }
}

/// Read the mode off the fence's word.
///
/// Six spellings of one grammar — the views a block shows, in the order it
/// shows them. Each names a whole arrangement, so they are alternatives and
/// the last one written wins. A word we don't know is reported and ignored,
/// not fatal — the same bargain the rest of this module strikes: a typo in an
/// info string costs a line of build output, never the figure.
fn mode(words: &[&str], chapter: &str, line: usize) -> Mode {
    let mut mode = Mode { lead: View::Figure, second: Second::Folded };
    for word in words {
        match arrangement(word) {
            Some(named) => mode = named,
            Option::None => eprintln!(
                "mdbook-lini: {chapter}:{line}: unknown word `{word}` on a lini fence — ignoring"
            ),
        }
    }
    mode
}

/// The arrangement one fence word names, or `None` if it names nothing.
///
/// The vocabulary lives here alone, so a test can ask whether a word is one of
/// ours without keeping a second copy of the list to drift against the first.
fn arrangement(word: &str) -> Option<Mode> {
    use Second::{Folded, None, Shown};
    use View::{Figure, Source};

    Some(match word {
        "figure" => Mode { lead: Figure, second: Folded },
        "code" => Mode { lead: Source, second: Folded },
        "figure-code" => Mode { lead: Figure, second: Shown },
        "code-figure" => Mode { lead: Source, second: Shown },
        "figure-only" => Mode { lead: Figure, second: None },
        "code-only" => Mode { lead: Source, second: None },
        _ => return Option::None,
    })
}

/// A figure and the collapsed listing of the source that drew it.
///
/// A checkbox and its label are the whole mechanism — no script, so the toggle
/// works with scripts off and takes keyboard focus, which is the promise the
/// figures themselves make.
///
/// It is deliberately **not** a `<details>`. That element carries a disclosure
/// marker, and a book's own stylesheet is unlayered — so it outranks ours and
/// can put the caret back however we suppress it. It also gives a theme a
/// second element to frame, which is how a listing ends up in a box inside a
/// box. A label has no marker, and the `<pre>` is left as the one thing a theme
/// will style: one frame, like every other code block on the page.
fn checkbox(names: &str, id: &str) -> String {
    format!(
        "<input class=\"lini-view-toggle\" type=\"checkbox\" id=\"{id}\" aria-label=\"Show {names}\">"
    )
}

fn button(icon: &str, names: &str, id: &str) -> String {
    format!(
        "<label class=\"lini-view-button\" for=\"{id}\" title=\"Show {names}\">{ICON_HEAD}{icon}</label>"
    )
}

/// The source, highlighted, in the panel the token palette is keyed on.
///
/// The `<pre>` inside is left bare so it is the one element a book's own
/// stylesheet frames — one box, like every other code block on the page.
/// `nohighlight` makes mdbook's highlight.js bail before it re-tokenizes our
/// spans, while its script still adds `.hljs` for the theme's code chrome and
/// still hangs its copy button on `pre > code`.
/// `buttons` is mdbook's own control row, emitted by us when the listing is
/// the primary view. mdbook's script adopts any `.buttons` it finds inside a
/// `<pre>` and inserts its copy button there rather than building its own — so
/// mdbook positions both controls, they cannot drift out of alignment, and the
/// pointer never leaves the `<pre>` on its way to ours, which is what kept the
/// copy button from vanishing under the hand-placed version.
fn listing(source: &str, buttons: &str) -> String {
    format!(
        "<div class=\"lini-source\"><pre>{buttons}<code class=\"nohighlight\">{}</code></pre></div>",
        one_line(&lini::highlight_html(source)),
    )
}

/// A DOM id for one block's toggle, unique within the chapter — which is the
/// page. Anything that is not a letter or digit folds to `-`, so a nested
/// chapter path still yields a legal id and the label can point at it.
fn toggle_id(chapter: &str, line: usize) -> String {
    let mut slug = String::with_capacity(chapter.len());
    for c in chapter.chars() {
        match c {
            c if c.is_ascii_alphanumeric() => slug.push(c.to_ascii_lowercase()),
            _ if !slug.ends_with('-') => slug.push('-'),
            _ => {}
        }
    }
    format!("lini-src-{}-{line}", slug.trim_matches('-'))
}

/// Fold every newline into the entity that renders as one.
///
/// A blank line **ends an HTML block** in CommonMark: the rest of the chapter
/// would be parsed as Markdown and spill out of the figure, orphaning the
/// closing tags at the foot of the page. Idiomatic Lini has blank lines — a
/// stylesheet, a gap, then the drawn statements — so the listing cannot carry
/// them literally. Inside `<pre>` the entity renders identically, and it can
/// end nothing.
fn one_line(html: &str) -> String {
    html.replace('\n', "&#10;")
}

/// Print every diagnostic; return the first error-level one, which is fatal.
fn report(diags: Vec<Diagnostic>, source: &str, chapter: &str) -> Option<String> {
    let mut fatal = None;
    for d in diags {
        let text = d.display_with_source(source, chapter).to_string();
        eprintln!("mdbook-lini: {text}");
        if d.level == Level::Error && fatal.is_none() {
            fatal = Some(text);
        }
    }
    fatal
}

/// Wrap a compiled SVG in the figure div the stylesheet targets.
///
/// The wrapper carries `--lini-w`, the diagram's natural pixel width — the one
/// hook the stylesheet needs to floor how far a wide figure may scale down
/// before the wrapper scrolls instead.
fn wrap(svg: &str) -> String {
    match natural_width(svg) {
        Some(w) => format!("<div class=\"lini-figure\" style=\"--lini-w: {w}px\">{svg}</div>"),
        None => format!("<div class=\"lini-figure\">{svg}</div>"),
    }
}

/// The `width` lini bakes onto the root `<svg>` tag, in pixels.
fn natural_width(svg: &str) -> Option<&str> {
    let tag = &svg[..svg.find('>')?];
    let (_, after) = tag.split_once(" width=\"")?;
    after.split_once('"').map(|(width, _)| width)
}

/// A diagnostic, on the page as well as on stderr. It is many lines and may
/// carry an empty one, so it goes through [`one_line`] like the listing does.
fn error_box(message: &str) -> String {
    format!("<pre class=\"lini-error\">{}</pre>", one_line(&escape(message)))
}

fn escape(s: &str) -> String {
    s.replace('&', "&amp;").replace('<', "&lt;").replace('>', "&gt;")
}

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

    /// The width hook rides the figure div in either mode — the listing is
    /// beside the figure, never between it and its own sizing.
    #[test]
    fn wraps_a_diagram_with_its_natural_width() {
        for words in [&[][..], &["figure-only"][..]] {
            let html = render("a -> b", "demo.md", 1, None, words);
            assert!(
                html.contains("<div class=\"lini-figure\" style=\"--lini-w: "),
                "{words:?}: {html}"
            );
            assert!(html.contains("<svg") && html.ends_with("</div>"), "{words:?}: {html}");
        }
    }

    #[test]
    fn a_broken_block_becomes_an_error_box() {
        let html = render("|box", "demo.md", 1, None, &[]);
        assert!(html.starts_with("<pre class=\"lini-error\">"), "{html}");
    }

    #[test]
    fn an_error_points_at_the_chapter_line_not_the_block_line() {
        let html = render("a -> b\n|box", "demo.md", 41, None, &[]);
        assert!(html.contains("demo.md:42:"), "{html}");
    }

    #[test]
    fn reads_the_width_off_the_root_tag() {
        assert_eq!(natural_width(r#"<svg viewBox="0 0 8 4" width="8" height="4">"#), Some("8"));
        assert_eq!(natural_width("<svg>"), None);
    }

    /// A source that exercises the hazard: a blank line between the stylesheet
    /// and the drawn statements, which is how idiomatic lini is laid out.
    const SPACED: &str = "{ layout: flow; }\n\n|box#a| \"A\"\n\na -> b \"go\"\n";

    /// The tags this module emits, undone — enough to read back the listing.
    fn listing(html: &str) -> String {
        let open = html.find("<code").expect("a code element");
        let start = html[open..].find('>').expect("its end") + open + 1;
        let end = html[start..].find("</code>").expect("its close") + start;
        let mut out = String::new();
        let mut rest = &html[start..end];
        while let Some(lt) = rest.find('<') {
            out.push_str(&rest[..lt]);
            let gt = rest[lt..].find('>').expect("well-formed tag") + lt;
            rest = &rest[gt + 1..];
        }
        out.push_str(rest);
        out.replace("&#10;", "\n")
            .replace("&lt;", "<")
            .replace("&gt;", ">")
            .replace("&quot;", "\"")
            .replace("&amp;", "&")
    }

    /// A blank line ends an HTML block in CommonMark, spilling the rest of the
    /// chapter out of the figure — so nothing we emit may contain one.
    fn blank_line(html: &str) -> Option<usize> {
        html.split('\n').position(|line| line.trim().is_empty())
    }

    #[test]
    fn a_figure_carries_a_source_toggle_by_default() {
        let html = render("a -> b", "demo.md", 1, None, &[]);
        assert!(html.starts_with("<div class=\"lini-figure-block\">"), "{html}");
        assert!(html.contains("<input class=\"lini-view-toggle\""), "{html}");
        assert!(html.contains("<label class=\"lini-view-button\""), "{html}");
        assert!(html.contains("lini-source"), "{html}");
        assert!(html.contains("<div class=\"lini-figure\""), "{html}");
    }

    /// A `<details>` brings a disclosure marker that a host stylesheet can
    /// re-assert from outside our layer — the caret that turned up on
    /// lini.rs. A label has no marker to suppress in the first place.
    #[test]
    fn the_control_is_a_label_with_no_disclosure_marker() {
        let html = render("a -> b", "demo.md", 1, None, &[]);
        assert!(!html.contains("<details"), "{html}");
        assert!(!html.contains("<summary"), "{html}");
    }

    /// The listing sits in a plain `<div>`, so the `<pre>` inside it is the
    /// only element a host theme boxes — one frame, like every other code
    /// block on the page, rather than a box inside a box.
    #[test]
    fn only_the_pre_is_boxable() {
        let html = render("a -> b", "demo.md", 1, None, &[]);
        let panel = html.split("<div class=\"lini-source").nth(1).expect("a panel");
        let panel = &panel[panel.find('>').unwrap() + 1..];
        assert!(panel.starts_with("<pre><code"), "{panel}");
    }

    /// Two figures share a page, so their toggles cannot share an id — and the
    /// label has to point at its own.
    #[test]
    fn each_toggle_owns_its_id() {
        let first = render("a -> b", "guide/figures.md", 4, None, &[]);
        let second = render("a -> b", "guide/figures.md", 40, None, &[]);
        // Anchored on the toggle: a diagram's own nodes carry `data-id=` too.
        let id_of = |html: &str| {
            let mark = "<input class=\"lini-view-toggle\" type=\"checkbox\" id=\"";
            let at = html.find(mark).expect("a toggle") + mark.len();
            html[at..][..html[at..].find('"').unwrap()].to_owned()
        };
        let (a, b) = (id_of(&first), id_of(&second));
        assert_ne!(a, b, "two blocks in one chapter share an id");
        assert!(first.contains(&format!("for=\"{a}\"")), "label points elsewhere: {first}");
        assert!(a.chars().all(|c| c.is_ascii_alphanumeric() || c == '-'), "illegal id: {a}");
    }

    /// hljs re-tokenizes every `<code>` it finds and would wipe our spans; it
    /// bails early on this class alone (`noHighlightRe`), while mdbook still
    /// adds `.hljs` for the theme's code chrome and still attaches its copy
    /// button to `pre code`.
    #[test]
    fn the_listing_opts_out_of_mdbooks_highlighter() {
        let html = render("a -> b", "demo.md", 1, None, &[]);
        assert!(html.contains("<pre><code class=\"nohighlight\">"), "{html}");
    }

    #[test]
    fn the_figure_only_word_emits_the_bare_figure() {
        let html = render("a -> b", "demo.md", 1, None, &["figure-only"]);
        assert!(html.starts_with("<div class=\"lini-figure\" style=\"--lini-w: "), "{html}");
        assert!(!html.contains("lini-source"), "{html}");
        assert!(!html.contains("lini-figure-block"), "{html}");
        assert!(html.ends_with("</div>"));
    }

    #[test]
    fn an_unrecognised_word_still_renders_the_default() {
        let html = render("a -> b", "demo.md", 1, None, &["wat"]);
        assert!(html.contains("lini-source"), "{html}");
    }

    #[test]
    fn the_listing_is_the_authors_own_text_verbatim() {
        let html = render(SPACED, "demo.md", 1, None, &[]);
        assert_eq!(listing(&html), SPACED);
    }

    #[test]
    fn a_source_with_blank_lines_emits_no_blank_line() {
        let html = render(SPACED, "demo.md", 1, None, &[]);
        assert_eq!(blank_line(&html), None, "line {:?} is blank in {html}", blank_line(&html));
    }

    #[test]
    fn a_bare_figure_emits_no_blank_line() {
        let html = render(SPACED, "demo.md", 1, None, &["figure-only"]);
        assert_eq!(blank_line(&html), None, "{html}");
    }

    /// A diagnostic is many lines and may carry an empty one; it lands in the
    /// page as raw HTML like everything else, so it is under the same law.
    #[test]
    fn an_error_box_emits_no_blank_line() {
        let html = render("|box| { fill: ", "demo.md", 1, None, &[]);
        assert!(html.starts_with("<pre class=\"lini-error\">"), "{html}");
        assert_eq!(blank_line(&html), None, "{html}");
    }

    #[test]
    fn the_code_word_puts_the_source_first() {
        let html = render("a -> b", "demo.md", 1, None, &["code"]);
        let source_at = html.find("lini-source").expect("a listing");
        let figure_at = html.find("lini-figure\"").expect("a figure");
        assert!(source_at < figure_at, "the figure still comes first: {html}");
        assert!(html.contains("Show figure"), "{html}");
        assert!(html.contains("lini-alt-view"), "{html}");
    }

    /// The hidden half is whichever one the mode did not put first, so one
    /// rule hides either — the alt marker rides the figure in `code` mode.
    #[test]
    fn code_mode_hides_the_figure_not_the_listing() {
        let html = render("a -> b", "demo.md", 1, None, &["code"]);
        let alt = html.split("lini-alt-view").nth(1).expect("an alt panel");
        assert!(alt[..80].contains("lini-figure"), "the alt panel is not the figure: {alt}");
    }

    /// The control lives in mdbook's own row, so mdbook lays both out. A
    /// hand-placed button over the `<pre>` drifts out of alignment and, worse,
    /// steals the pointer off the `<pre>` so mdbook hides its copy button the
    /// moment you reach for ours.
    #[test]
    fn the_code_mode_button_joins_mdbooks_button_row() {
        let html = render("a -> b", "demo.md", 1, None, &["code"]);
        assert!(
            html.contains("<pre><span class=\"buttons\"><label class=\"lini-view-button\""),
            "{html}"
        );
    }

    /// Figure-first has no `<pre>` on top to join, so its control floats over
    /// the figure and must not carry a row that mdbook would style.
    #[test]
    fn the_default_mode_button_stands_alone() {
        let html = render("a -> b", "demo.md", 1, None, &[]);
        assert!(!html.contains("class=\"buttons\""), "{html}");
        assert!(html.contains("<label class=\"lini-view-button\""), "{html}");
    }

    /// Naming both views is for the teaching figure, where the source is the
    /// lesson rather than a detail: a reader should not have to find a button
    /// to see what drew the picture.
    #[test]
    fn figure_code_shows_the_figure_and_the_source_at_once() {
        let html = render("a -> b", "demo.md", 1, None, &["figure-code"]);
        let figure_at = html.find("lini-figure\"").expect("a figure");
        let source_at = html.find("lini-source").expect("a listing");
        assert!(figure_at < source_at, "the source leads: {html}");
        assert!(!html.contains("lini-view-toggle"), "a shown pair carries a toggle: {html}");
        assert!(!html.contains("lini-view-button"), "a shown pair carries a button: {html}");
    }

    /// The rule that hides the second view is written against the checkbox, so
    /// a block that emits none has nothing to hide it — that, and not a second
    /// mechanism, is what puts both views on the page.
    #[test]
    fn a_shown_second_view_wears_the_class_the_hidden_one_wears() {
        let html = render("a -> b", "demo.md", 1, None, &["figure-code"]);
        assert!(html.starts_with("<div class=\"lini-figure-block lini-open\">"), "{html}");
        assert!(html.contains("<div class=\"lini-alt-view\">"), "{html}");
    }

    /// The compound reads in the order it is written, so the same two views
    /// swap places when the fence names them the other way round.
    #[test]
    fn code_figure_leads_with_the_source() {
        let html = render("a -> b", "demo.md", 1, None, &["code-figure"]);
        let source_at = html.find("lini-source").expect("a listing");
        let figure_at = html.find("lini-figure\"").expect("a figure");
        assert!(source_at < figure_at, "the figure leads: {html}");
        assert!(!html.contains("lini-view-toggle"), "{html}");
    }

    /// A single word names the lead and folds the other away — so `figure`
    /// spells the default out loud, and `code` is its mirror.
    #[test]
    fn a_single_word_folds_the_other_view_behind_the_toggle() {
        assert_eq!(
            render("a -> b", "demo.md", 1, None, &["figure"]),
            render("a -> b", "demo.md", 1, None, &[]),
        );
        for (word, first) in [("figure", "lini-figure\""), ("code", "lini-source")] {
            let html = render("a -> b", "demo.md", 1, None, &[word]);
            let lead = html.find(first).expect("the lead view");
            let alt = html.find("lini-alt-view").expect("a folded view");
            assert!(lead < alt, "`{word}` does not lead with {first}: {html}");
            assert!(html.contains("lini-view-toggle"), "`{word}` has no toggle: {html}");
        }
    }

    /// With no toggle there is no button, so nothing needs mdbook's row —
    /// mdbook builds its own for the copy button, as it does on any `<pre>`.
    #[test]
    fn a_shown_pair_leaves_mdbooks_button_row_to_mdbook() {
        let html = render("a -> b", "demo.md", 1, None, &["code-figure"]);
        assert!(!html.contains("class=\"buttons\""), "{html}");
    }

    #[test]
    fn a_shown_pair_emits_no_blank_line() {
        for words in [&["figure-code"][..], &["code-figure"][..]] {
            let html = render(SPACED, "demo.md", 1, None, words);
            assert_eq!(blank_line(&html), None, "{words:?}: {html}");
        }
    }

    #[test]
    fn code_only_emits_a_listing_and_nothing_else() {
        let html = render("a -> b", "demo.md", 1, None, &["code-only"]);
        assert!(html.contains("lini-source"), "{html}");
        assert!(!html.contains("<svg"), "code-only drew a figure: {html}");
        assert!(!html.contains("lini-view-toggle"), "code-only carries a toggle: {html}");
        assert!(!html.contains("lini-figure"), "{html}");
    }

    /// The point of `code-only`: a fragment or a deliberate counter-example is
    /// a listing, not an error box. Nothing compiles it, so nothing can fail —
    /// and that falls out of the grammar rather than being a rule of its own.
    #[test]
    fn a_code_only_block_is_never_compiled() {
        let html = render("|box| { fill:", "demo.md", 1, None, &["code-only"]);
        assert!(!html.contains("lini-error"), "code-only reported a compile error: {html}");
        assert!(html.contains("lini-tok-"), "code-only lost its highlighting: {html}");
    }

    #[test]
    fn a_code_only_listing_emits_no_blank_line() {
        let html = render(SPACED, "demo.md", 1, None, &["code-only"]);
        assert_eq!(blank_line(&html), None, "{html}");
    }

    /// The book under `tests/book/` is built by CI, not by `cargo test`, so a
    /// fence word that stops being one goes unnoticed here — which is exactly
    /// what happened when `raw` was retired and `figure` changed meaning: the
    /// fixture kept both and the `book` job failed for three releases while
    /// this suite stayed green. Reading the fixture from here closes that gap
    /// without needing mdbook.
    #[test]
    fn the_book_fixture_only_uses_words_we_know() {
        let md = include_str!("../tests/book/src/chapter_1.md");
        let mut fences = 0;
        for line in md.lines().filter(|l| l.trim_start().starts_with("```lini")) {
            fences += 1;
            let info = line.trim_start().trim_start_matches('`');
            for word in info.split([' ', '\t', ',']).skip(1).filter(|w| !w.is_empty()) {
                assert!(
                    arrangement(word).is_some(),
                    "tests/book/src/chapter_1.md says `{word}`, which is not a fence word"
                );
            }
        }
        assert!(fences >= 6, "the fixture lost its fences: found {fences}");
    }

    /// Lini dresses every node in `.lini-<type>`, so a class of ours that
    /// happened to be spelled like a type would restyle the insides of every
    /// diagram on the page. This is the standing guard — it is what turns a
    /// future Lini release adding, say, a `figure` type from a silent visual
    /// bug into a failing build here.
    #[test]
    fn our_classes_are_ours_alone() {
        // One of each family, so the sweep sees the classes each one emits.
        let src = "{ layout: flow; }\n|box#a| \"A\"\n|cyl#b| \"B\"\n|note#c| \"C\"\na -> b";
        let svg = lini::compile_str(src).expect("the probe compiles");
        for ours in [
            BLOCK,
            "lini-figure",
            "lini-source",
            "lini-error",
            "lini-view-toggle",
            "lini-view-button",
            "lini-alt-view",
            "lini-open",
        ] {
            assert!(
                !svg.contains(ours),
                "Lini now emits `{ours}` itself — rename ours before it restyles diagrams"
            );
        }
    }
}