imprimatur 0.1.0

data/ext/imprimatur_native/core/src/read/image.rs

@@ -0,0 +1,233 @@
+//! Images found in documents, as files: what PDFs store as pixels becomes
+//! PNG (or TIFF, for fax-compressed scans); JPEG and JPEG 2000 are kept as
+//! they are; Office documents' media are copied.
+
+mod dimensions;
+#[cfg(test)]
+mod tests;
+
+use super::content::Bounds;
+
+/// An image, encoded as a file of its format.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Image {
+    pub data: Vec<u8>,
+    pub format: ImageFormat,
+    pub width: Option<u32>,
+    pub height: Option<u32>,
+    pub location: ImageLocation,
+}
+
+/// Where an image was found.
+#[derive(Debug, Clone, PartialEq)]
+#[non_exhaustive]
+pub enum ImageLocation {
+    /// On a PDF page (the first that draws it), placed at `bounds`.
+    Page { number: u32, bounds: Option<Bounds> },
+    /// A part of a Word or Excel package, and for a workbook the sheet that
+    /// shows it.
+    Part { name: String, sheet: Option<String> },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[non_exhaustive]
+pub enum ImageFormat {
+    Png,
+    Jpeg,
+    Jpeg2000,
+    Tiff,
+    Gif,
+    Bmp,
+    Webp,
+    Svg,
+    Emf,
+    Wmf,
+    /// A PDF's JBIG2 stream, globals first: viewers do not open it, a JBIG2
+    /// decoder in embedded mode does.
+    Jbig2,
+    Other,
+}
+
+impl ImageFormat {
+    #[must_use]
+    pub const fn extension(self) -> &'static str {
+        match self {
+            Self::Png => "png",
+            Self::Jpeg => "jpg",
+            Self::Jpeg2000 => "jp2",
+            Self::Tiff => "tif",
+            Self::Gif => "gif",
+            Self::Bmp => "bmp",
+            Self::Webp => "webp",
+            Self::Svg => "svg",
+            Self::Emf => "emf",
+            Self::Wmf => "wmf",
+            Self::Jbig2 => "jb2",
+            Self::Other => "bin",
+        }
+    }
+
+    /// The format of a file, by its first bytes, or by its name's
+    /// extension when they say nothing.
+    pub(crate) fn sniff(data: &[u8], name: &str) -> Self {
+        match data {
+            [0x89, b'P', b'N', b'G', ..] => Self::Png,
+            [0xFF, 0xD8, ..] => Self::Jpeg,
+            [b'G', b'I', b'F', b'8', ..] => Self::Gif,
+            [b'B', b'M', ..] => Self::Bmp,
+            [b'I', b'I', 42, 0, ..] | [b'M', b'M', 0, 42, ..] => Self::Tiff,
+            [b'R', b'I', b'F', b'F', _, _, _, _, b'W', b'E', b'B', b'P', ..] => Self::Webp,
+            [0xD7, 0xCD, 0xC6, 0x9A, ..] => Self::Wmf,
+            [0, 0, 0, 0x0C, b'j', b'P', ..] | [0xFF, 0x4F, 0xFF, 0x51, ..] => Self::Jpeg2000,
+            _ if data.get(40..44) == Some(b" EMF") => Self::Emf,
+            _ if is_svg(data) => Self::Svg,
+            _ => name.rsplit_once('.').map_or(Self::Other, |(_, extension)| {
+                match extension.to_ascii_lowercase().as_str() {
+                    "svg" => Self::Svg,
+                    "emf" => Self::Emf,
+                    "wmf" => Self::Wmf,
+                    _ => Self::Other,
+                }
+            }),
+        }
+    }
+
+    /// Width and height, read from the file's header where the format puts
+    /// them up front.
+    pub(crate) fn dimensions(self, data: &[u8]) -> Option<(u32, u32)> {
+        dimensions::dimensions(self, data)
+    }
+}
+
+/// Whether a file is SVG markup: an `<svg` element among its first bytes,
+/// after an XML declaration, comments or a doctype at most.
+fn is_svg(data: &[u8]) -> bool {
+    let head = &data[..data.len().min(1024)];
+    let head = head.strip_prefix(b"\xEF\xBB\xBF").unwrap_or(head).trim_ascii_start();
+    head.starts_with(b"<")
+        && !head.starts_with(b"<html")
+        && head.windows(4).any(|window| window == b"<svg")
+}
+
+/// PNG color types (ISO/IEC 15948, 11.2.2).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PngColor {
+    Gray = 0,
+    Rgb = 2,
+    Palette = 3,
+    GrayAlpha = 4,
+    Rgba = 6,
+}
+
+/// A PNG of `rows` packed pixels, `bits` per sample, each row starting on a
+/// byte. `palette` is RGB triples, for [`PngColor::Palette`].
+pub fn png(
+    width: u32,
+    height: u32,
+    color: PngColor,
+    bits: u8,
+    palette: Option<&[u8]>,
+    rows: &[u8],
+) -> Vec<u8> {
+    let channels: usize = match color {
+        PngColor::Gray | PngColor::Palette => 1,
+        PngColor::GrayAlpha => 2,
+        PngColor::Rgb => 3,
+        PngColor::Rgba => 4,
+    };
+    let stride = (width as usize * channels * usize::from(bits)).div_ceil(8);
+    let mut filtered = Vec::with_capacity((stride + 1) * height as usize);
+    // Short data, as damaged files have, is padded with zero rows.
+    for row in 0..height as usize {
+        filtered.push(0);
+        let line = rows.get(row * stride..).unwrap_or_default();
+        let line = &line[..line.len().min(stride)];
+        filtered.extend_from_slice(line);
+        filtered.resize(filtered.len() + stride - line.len(), 0);
+    }
+    let compressed = miniz_oxide::deflate::compress_to_vec_zlib(&filtered, 6);
+    let mut out = Vec::with_capacity(compressed.len() + 128);
+    out.extend_from_slice(b"\x89PNG\r\n\x1a\n");
+    let mut header = [0_u8; 13];
+    header[..4].copy_from_slice(&width.to_be_bytes());
+    header[4..8].copy_from_slice(&height.to_be_bytes());
+    header[8] = bits;
+    header[9] = color as u8;
+    chunk(&mut out, *b"IHDR", &header);
+    if let Some(palette) = palette {
+        chunk(&mut out, *b"PLTE", palette);
+    }
+    chunk(&mut out, *b"IDAT", &compressed);
+    chunk(&mut out, *b"IEND", &[]);
+    out
+}
+
+fn chunk(out: &mut Vec<u8>, kind: [u8; 4], data: &[u8]) {
+    out.extend_from_slice(&u32::try_from(data.len()).unwrap_or(u32::MAX).to_be_bytes());
+    let start = out.len();
+    out.extend_from_slice(&kind);
+    out.extend_from_slice(data);
+    let crc = crc32fast::hash(&out[start..]);
+    out.extend_from_slice(&crc.to_be_bytes());
+}
+
+/// How a fax-compressed image is coded (`CCITTFaxDecode`'s `K`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Fax {
+    Group3OneDimensional,
+    Group3TwoDimensional,
+    Group4,
+}
+
+/// A one-strip TIFF around CCITT fax data, as PDFs store scans.
+/// `black_is_one` is whether 1 bits are black (`BlackIs1`, after `Decode`).
+pub fn tiff(
+    width: u32,
+    height: u32,
+    fax: Fax,
+    black_is_one: bool,
+    byte_aligned: bool,
+    data: &[u8],
+) -> Vec<u8> {
+    let (compression, options_tag, options) = match fax {
+        Fax::Group3OneDimensional => (3, 292, u32::from(byte_aligned) << 2),
+        Fax::Group3TwoDimensional => (3, 292, 1 | u32::from(byte_aligned) << 2),
+        Fax::Group4 => (4, 293, 0),
+    };
+    // TIFF photometric: 0 is WhiteIsZero, 1 is BlackIsZero.
+    let photometric = u32::from(!black_is_one);
+    let entries: [(u16, u16, u32); 10] = [
+        (256, 4, width),
+        (257, 4, height),
+        (258, 3, 1),
+        (259, 3, compression),
+        (262, 3, photometric),
+        (273, 4, 0), // strip offset, set below
+        (277, 3, 1),
+        (278, 4, height),
+        (279, 4, u32::try_from(data.len()).unwrap_or(u32::MAX)),
+        (options_tag, 4, options),
+    ];
+    let directory = 8;
+    let strip = directory + 2 + entries.len() * 12 + 4;
+    let mut out = Vec::with_capacity(strip + data.len());
+    out.extend_from_slice(b"II*\0");
+    out.extend_from_slice(&u32::try_from(directory).unwrap_or(0).to_le_bytes());
+    out.extend_from_slice(&u16::try_from(entries.len()).unwrap_or(0).to_le_bytes());
+    for (tag, kind, value) in entries {
+        let value = if tag == 273 { u32::try_from(strip).unwrap_or(0) } else { value };
+        out.extend_from_slice(&tag.to_le_bytes());
+        out.extend_from_slice(&kind.to_le_bytes());
+        out.extend_from_slice(&1_u32.to_le_bytes());
+        // A SHORT sits in the first two bytes of the value field.
+        if kind == 3 {
+            out.extend_from_slice(&u16::try_from(value).unwrap_or(0).to_le_bytes());
+            out.extend_from_slice(&[0, 0]);
+        } else {
+            out.extend_from_slice(&value.to_le_bytes());
+        }
+    }
+    out.extend_from_slice(&0_u32.to_le_bytes());
+    out.extend_from_slice(data);
+    out
+}

data/ext/imprimatur_native/core/src/read/inflate.rs

@@ -0,0 +1,44 @@
+//! Deflate, for zip entries and PDF streams alike: into one buffer sized
+//! up front (exactly, when the size is known), grown only past a guess,
+//! never past the budget. What a damaged stream yields before the damage is
+//! kept; the caller decides whether that is enough.
+
+use miniz_oxide::inflate::TINFLStatus;
+use miniz_oxide::inflate::core::{DecompressorOxide, decompress, inflate_flags};
+
+use crate::{Error, Result};
+
+/// Inflates `data`, zlib-wrapped or raw, starting with room for `expected`
+/// bytes and growing to `limit` at most. Returns the output and whether the
+/// stream ended properly. Checksums are not verified: PDF writers get them
+/// wrong, and zip entries have their CRC checked by the caller.
+pub fn inflate(data: &[u8], zlib: bool, expected: usize, limit: usize) -> Result<(Vec<u8>, bool)> {
+    let flags = inflate_flags::TINFL_FLAG_USING_NON_WRAPPING_OUTPUT_BUF
+        | inflate_flags::TINFL_FLAG_IGNORE_ADLER32
+        | if zlib { inflate_flags::TINFL_FLAG_PARSE_ZLIB_HEADER } else { 0 };
+    let mut decompressor = Box::<DecompressorOxide>::default();
+    let mut out = vec![0_u8; expected.clamp(1, limit.max(1))];
+    let (mut read, mut written) = (0, 0);
+    loop {
+        let (status, consumed, produced) =
+            decompress(&mut decompressor, &data[read..], &mut out, written, flags);
+        read += consumed;
+        written += produced;
+        match status {
+            TINFLStatus::Done => {
+                out.truncate(written);
+                return Ok((out, true));
+            }
+            TINFLStatus::HasMoreOutput => {
+                if out.len() >= limit {
+                    return Err(Error::LimitExceeded("decompressed size"));
+                }
+                out.resize(out.len().saturating_mul(2).min(limit), 0);
+            }
+            _ => {
+                out.truncate(written);
+                return Ok((out, false));
+            }
+        }
+    }
+}

data/ext/imprimatur_native/core/src/read/json.rs

@@ -0,0 +1,172 @@
+//! Content and images as JSON.
+//!
+//! One schema for every caller: the command line's `--json` and the Ruby
+//! binding. Offsets are byte offsets into the UTF-8 text they belong to;
+//! positions are in points from a page's top-left corner.
+
+#[cfg(test)]
+mod tests;
+
+use serde_json::{Map, Value as Json, json};
+
+use super::{Block, Bounds, Cell, Content, Grid, Image, ImageLocation, Mark, Page, Sheet, Value};
+
+/// The document's content, by format: `pages`, `sheets` or `blocks`.
+#[must_use]
+pub fn content(content: &Content) -> Map<String, Json> {
+    let mut object = Map::new();
+    object.insert("format".into(), content.format().as_str().into());
+    match content {
+        Content::Pdf(pages) => object.insert("pages".into(), pages.iter().map(page).collect()),
+        Content::Xlsx(sheets) => object.insert("sheets".into(), sheets.iter().map(sheet).collect()),
+        Content::Docx(blocks) => object.insert("blocks".into(), blocks.iter().map(block).collect()),
+    };
+    object
+}
+
+fn page(page: &Page) -> Json {
+    let blocks: Vec<Json> = page
+        .blocks
+        .iter()
+        .map(|placed| {
+            let mut object = block(&placed.block);
+            if let (Some(bounds), Json::Object(fields)) = (placed.bounds, &mut object) {
+                fields.insert("bounds".into(), self::bounds(bounds));
+            }
+            object
+        })
+        .collect();
+    json!({ "page": page.number, "images": page.images, "blocks": blocks })
+}
+
+/// An image's description, its data left out: `format`, `width`, `height`,
+/// `bytes`, and where it is: `page` and `bounds`, or `part` and `sheet`.
+#[must_use]
+pub fn image(image: &Image) -> Map<String, Json> {
+    let mut object = Map::new();
+    object.insert("format".into(), image.format.extension().into());
+    object.insert("width".into(), image.width.into());
+    object.insert("height".into(), image.height.into());
+    object.insert("bytes".into(), image.data.len().into());
+    match &image.location {
+        ImageLocation::Page { number, bounds } => {
+            object.insert("page".into(), (*number).into());
+            if let Some(bounds) = bounds {
+                object.insert("bounds".into(), self::bounds(*bounds));
+            }
+        }
+        ImageLocation::Part { name, sheet } => {
+            object.insert("part".into(), name.as_str().into());
+            if let Some(sheet) = sheet {
+                object.insert("sheet".into(), sheet.as_str().into());
+            }
+        }
+    }
+    object
+}
+
+/// A rectangle, rounded to hundredths of a point.
+#[must_use]
+pub fn bounds(bounds: Bounds) -> Json {
+    let round = |value: f64| (value * 100.0).round() / 100.0;
+    json!({
+        "left": round(bounds.left),
+        "top": round(bounds.top),
+        "right": round(bounds.right),
+        "bottom": round(bounds.bottom),
+    })
+}
+
+fn block(block: &Block) -> Json {
+    match block {
+        Block::Heading { level, text } => {
+            json!({ "type": "heading", "level": level, "text": text.text })
+        }
+        Block::Paragraph { text } => {
+            with_marks(json!({ "type": "paragraph", "text": text.text }), &text.marks)
+        }
+        Block::ListItem { level, ordered, text } => with_marks(
+            json!({ "type": "list_item", "level": level, "ordered": ordered, "text": text.text }),
+            &text.marks,
+        ),
+        Block::Table(grid) => json!({ "type": "table", "rows": rows(grid, false) }),
+    }
+}
+
+fn with_marks(mut object: Json, marks: &[Mark]) -> Json {
+    if !marks.is_empty()
+        && let Json::Object(fields) = &mut object
+    {
+        let marks = marks
+            .iter()
+            .map(|mark| {
+                json!({
+                    "start": mark.range.start,
+                    "end": mark.range.end,
+                    "bold": mark.bold,
+                    "italic": mark.italic,
+                    "link": mark.link,
+                })
+            })
+            .collect();
+        fields.insert("marks".into(), marks);
+    }
+    object
+}
+
+fn sheet(sheet: &Sheet) -> Json {
+    let comments: Vec<Json> = sheet
+        .comments
+        .iter()
+        .map(|note| {
+            let author = note.author.as_deref();
+            json!({ "cell": note.reference(), "author": author, "text": note.text })
+        })
+        .collect();
+    json!({
+        "name": sheet.name,
+        "hidden": sheet.hidden,
+        "rows": rows(&sheet.cells, true),
+        "comments": comments,
+    })
+}
+
+/// Rows of cells, numbered from 1 in a sheet (where cells are named `B2`)
+/// and from 0 in a Word table (where they are numbered by column).
+fn rows(grid: &Grid, sheet: bool) -> Json {
+    grid.rows()
+        .map(|cells| {
+            let row = cells.first().map_or(0, |cell| cell.row);
+            let cells: Vec<Json> = cells.iter().map(|cell| self::cell(grid, cell, sheet)).collect();
+            if sheet {
+                json!({ "row": row + 1, "cells": cells })
+            } else {
+                json!({ "row": row, "cells": cells })
+            }
+        })
+        .collect()
+}
+
+fn cell(grid: &Grid, cell: &Cell, sheet: bool) -> Json {
+    let text = grid.text(cell);
+    let (kind, value) = match cell.value {
+        Value::Number(number) => ("number", json!(number)),
+        Value::Bool(on) => ("bool", json!(on)),
+        Value::Date(date) => ("date", json!(date.to_string().replace(' ', "T"))),
+        Value::Error => ("error", json!(text)),
+        Value::Formula => ("formula", json!(text)),
+        _ => ("text", json!(text)),
+    };
+    let mut object = Map::new();
+    if sheet {
+        object.insert("cell".into(), cell.reference().into());
+    } else {
+        object.insert("column".into(), cell.column.into());
+    }
+    object.insert("type".into(), kind.into());
+    object.insert("value".into(), value);
+    if !matches!(kind, "text" | "error" | "formula") {
+        object.insert("text".into(), text.into());
+    }
+    Json::Object(object)
+}

data/ext/imprimatur_native/core/src/read/markdown.rs

@@ -0,0 +1,254 @@
+//! Content as Markdown. Escaping is minimal on purpose: the text feeds
+//! search indexes and language models, where `snake\_case` would be noise.
+//! Only what would break the structure is escaped: pipes and line breaks
+//! inside table cells, and a paragraph that would read as a heading or a
+//! quote.
+
+#[cfg(test)]
+mod tests;
+
+use std::fmt::Write as _;
+
+use super::content::{Block, Cell, Content, Grid, Page, Sheet, Text, push_reference};
+
+/// The deepest Markdown heading.
+const MAX_HEADING: u8 = 6;
+
+impl Content {
+    /// The content as Markdown: a PDF's pages (from the second, marked
+    /// `<!-- page N -->`), each sheet of a workbook under its name, a Word
+    /// document's blocks.
+    #[must_use]
+    pub fn to_markdown(&self) -> String {
+        let mut out = String::new();
+        match self {
+            Self::Pdf(pages) => pdf(&mut out, pages),
+            Self::Xlsx(sheets) => {
+                for sheet in sheets {
+                    write_sheet(&mut out, sheet);
+                }
+            }
+            Self::Docx(blocks) => write_blocks(&mut out, blocks.iter(), Mode::Body),
+        }
+        out
+    }
+}
+
+/// How a block's text is written.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Mode {
+    /// Emphasis and links.
+    Body,
+    /// Links only: emphasis in a table cell is mostly a bold header row.
+    Cell,
+}
+
+fn pdf(out: &mut String, pages: &[Page]) {
+    for page in pages.iter().filter(|page| !page.blocks.is_empty()) {
+        if page.number > 1 {
+            end_block(out);
+            // Writing to a String cannot fail.
+            let _ = writeln!(out, "<!-- page {} -->", page.number);
+        }
+        write_blocks(out, page.blocks.iter().map(|placed| &placed.block), Mode::Body);
+    }
+}
+
+fn write_sheet(out: &mut String, sheet: &Sheet) {
+    end_block(out);
+    out.push_str("## ");
+    out.push_str(&sheet.name);
+    if sheet.hidden {
+        out.push_str(" (hidden)");
+    }
+    out.push_str("\n\n");
+    if sheet.cells.is_empty() {
+        out.push_str("_Empty._\n");
+    } else {
+        write_table(out, &sheet.cells);
+    }
+    for (index, note) in sheet.comments.iter().enumerate() {
+        if index == 0 {
+            end_block(out);
+            out.push_str("Comments:\n\n");
+        }
+        out.push_str("- ");
+        push_reference(out, note.row, note.column);
+        if let Some(author) = &note.author {
+            out.push_str(" (");
+            out.push_str(author);
+            out.push(')');
+        }
+        out.push_str(": ");
+        for (index, line) in note.text.lines().enumerate() {
+            if index > 0 {
+                out.push_str("\n  ");
+            }
+            out.push_str(line.trim_end());
+        }
+        out.push('\n');
+    }
+}
+
+/// Blocks in order: consecutive list items form one list; everything else
+/// is a block of its own.
+pub fn write_blocks<'b>(out: &mut String, blocks: impl Iterator<Item = &'b Block>, mode: Mode) {
+    let mut in_list = false;
+    for block in blocks {
+        match block {
+            Block::Heading { level, text } => {
+                end_block(out);
+                for _ in 0..(*level).clamp(1, MAX_HEADING) {
+                    out.push('#');
+                }
+                out.push(' ');
+                out.extend(text.text.chars().map(|ch| if ch == '\n' { ' ' } else { ch }));
+                out.push('\n');
+            }
+            Block::Paragraph { text } => {
+                end_block(out);
+                if text.text.starts_with(['#', '>']) {
+                    out.push('\\');
+                }
+                write_text(out, text, mode, "");
+                out.push('\n');
+            }
+            Block::ListItem { level, ordered, text } => {
+                if !in_list {
+                    end_block(out);
+                }
+                let indent = "  ".repeat(usize::from(*level));
+                let marker = if *ordered { "1. " } else { "- " };
+                out.push_str(&indent);
+                out.push_str(marker);
+                let continuation = format!("{indent}{}", " ".repeat(marker.len()));
+                write_text(out, text, mode, &continuation);
+                out.push('\n');
+            }
+            Block::Table(grid) => {
+                end_block(out);
+                write_table(out, grid);
+            }
+        }
+        in_list = matches!(block, Block::ListItem { .. });
+    }
+}
+
+/// A cell's blocks as one cell of a table: links kept, emphasis left out,
+/// each line on its own, blank lines dropped.
+pub fn cell_text(blocks: &[Block], out: &mut String) {
+    let mut rendered = String::new();
+    write_blocks(&mut rendered, blocks.iter(), Mode::Cell);
+    for line in rendered.lines().filter(|line| !line.trim().is_empty()) {
+        if !out.is_empty() {
+            out.push('\n');
+        }
+        out.push_str(line);
+    }
+}
+
+/// Text with its marks; line breaks continue at `indent`, as a list item's
+/// must. Whitespace at the edges of a marked stretch stays outside it.
+fn write_text(out: &mut String, text: &Text, mode: Mode, indent: &str) {
+    let mut at = 0;
+    for mark in &text.marks {
+        push_lines(out, &text.text[at..mark.range.start], indent);
+        let stretch = &text.text[mark.range.clone()];
+        at = mark.range.end;
+        let core = stretch.trim();
+        if core.is_empty() {
+            push_lines(out, stretch, indent);
+            continue;
+        }
+        push_lines(out, &stretch[..stretch.len() - stretch.trim_start().len()], indent);
+        let emphasis = mode == Mode::Body;
+        let marker = match (mark.bold && emphasis, mark.italic && emphasis) {
+            (true, true) => "***",
+            (true, false) => "**",
+            (false, true) => "*",
+            (false, false) => "",
+        };
+        if mark.link.is_some() {
+            out.push('[');
+        }
+        out.push_str(marker);
+        push_lines(out, core, indent);
+        out.push_str(marker);
+        if let Some(url) = &mark.link {
+            out.push_str("](");
+            out.push_str(url);
+            out.push(')');
+        }
+        push_lines(out, &stretch[stretch.trim_end().len()..], indent);
+    }
+    push_lines(out, &text.text[at..], indent);
+}
+
+fn push_lines(out: &mut String, text: &str, indent: &str) {
+    for (index, line) in text.split('\n').enumerate() {
+        if index > 0 {
+            out.push('\n');
+            out.push_str(indent);
+        }
+        out.push_str(line);
+    }
+}
+
+/// A grid as a table: its first row as the header, rows without cells and
+/// columns without any left out.
+pub fn write_table(out: &mut String, grid: &Grid) {
+    let Some(last) = grid.cells().iter().map(|cell| cell.column).max() else { return };
+    let mut used = vec![false; last as usize + 1];
+    for cell in grid.cells() {
+        used[cell.column as usize] = true;
+    }
+    let columns: Vec<u32> = (0..=last).filter(|&column| used[column as usize]).collect();
+    let mut rows = grid.rows();
+    let Some(header) = rows.next() else { return };
+    write_row(out, grid, header, &columns);
+    out.push('|');
+    for _ in &columns {
+        out.push_str(" --- |");
+    }
+    out.push('\n');
+    for row in rows {
+        write_row(out, grid, row, &columns);
+    }
+}
+
+fn write_row(out: &mut String, grid: &Grid, cells: &[Cell], columns: &[u32]) {
+    out.push('|');
+    let mut cells = cells.iter().peekable();
+    for &column in columns {
+        out.push(' ');
+        if let Some(cell) = cells.next_if(|cell| cell.column == column) {
+            push_cell(out, grid.text(cell));
+        }
+        out.push_str(" |");
+    }
+    out.push('\n');
+}
+
+/// Cell text on one line: pipes escaped, line breaks as `<br>`.
+pub fn push_cell(out: &mut String, text: &str) {
+    for (index, line) in text.trim().lines().enumerate() {
+        if index > 0 {
+            out.push_str("<br>");
+        }
+        for ch in line.trim_end_matches('\r').chars() {
+            if ch == '|' {
+                out.push('\\');
+            }
+            out.push(ch);
+        }
+    }
+}
+
+/// Ends the current block with a blank line, unless the output is empty
+/// or already ends with one.
+pub fn end_block(out: &mut String) {
+    if out.is_empty() || out.ends_with("\n\n") {
+        return;
+    }
+    out.push_str(if out.ends_with('\n') { "\n" } else { "\n\n" });
+}