blockworx/export/

pdf.rs

//! The whole document as a PDF (D21): one page per scope, the navigation
//! hierarchy as the PDF outline, and a link annotation over every block that
//! opens a scope — so the diagram navigates inside any ordinary PDF reader,
//! and review rides that reader's own annotation tools rather than anything
//! the app ships.
//!
//! Pages are drawn by the existing SVG export path
//! ([`crate::export::level::render_level`]) and placed with `krilla-svg`.
//! Nothing here knows how a block looks; a second renderer would drift from
//! the editor's, and the editor's is the one users check their drawings
//! against.

use crate::canvas::convert::IntoEgui as _;
use blockworx_doc::{document::IndexedDocument, id::BlockId};
use blockworx_geom::{Rect, Vec2, pos2};
use blockworx_paint::Luminance;
use blockworx_paint::{Color, Font};

use krilla::{
    Document as Pdf, SerializeSettings,
    annotation::{Annotation, LinkAnnotation, Target},
    color::rgb,
    destination::XyzDestination,
    geom::{PathBuilder, Point, Rect as PdfRect, Size, Transform},
    metadata::Metadata,
    num::NormalizedF32,
    outline::{Outline, OutlineNode},
    page::PageSettings,
    paint::{Fill, Stroke},
    text::{Font as PdfFont, TextDirection},
};
use krilla_svg::{SurfaceExt, SvgSettings};

use blockworx_store::projection::Provenance;

use crate::{
    path::{BlockPath, child_blocks},
    theme::Role,
    tools::title_block::Cell,
};

/// One world-unit-to-point ratio for the whole document — the CSS pt/px
/// convention — so a block is the same physical size on every page and the
/// *pages* differ instead of the scale. Fit-to-page onto one uniform sheet
/// was tried first and reversed (2026-08-30, user feedback): it blew small
/// scopes up and shrank large ones down. Mixed page sizes are ordinary PDF
/// (readers, annotators, and printers all take per-page media boxes).
const SCALE: f32 = 0.75;
/// Page margin, half an inch.
const MARGIN: f32 = 36.0;
/// The smallest sheet cut, 4×3 in: a two-block scope gets a small page,
/// not a postage stamp under a block wider than the drawing.
const MIN_PAGE: Vec2 = Vec2::new(288.0, 216.0);
/// The largest page dimension common readers accept (Acrobat's 200-inch
/// limit), in points. A scope that would overflow it is scaled down to
/// fit — the one case where the document-wide scale gives way.
const MAX_PAGE: f32 = 14_400.0;
/// The tallest the title block gets: its two-column head, then the path and
/// the provenance line beneath it. What a page reserves under its drawing.
const BLOCK_ROWS: f32 = 4.0;
/// Space between one of the block's lines and the next.
const LEADING: f32 = 4.0;
/// Breathing room between the title block's lines and the rule around them.
const BLOCK_PAD: f32 = 3.0;
/// The gutter between the head's two columns, and between a caption and
/// what it captions.
const COLUMN_GAP: f32 = 12.0;
const CAPTION_GAP: f32 = 4.0;

/// The one size the printed title block sets everything in: the canvas's own
/// block-title size at the document scale, so the block reads at the size of
/// the titles in the drawing above it.
#[derive(Clone, Copy, PartialEq, Debug)]
pub struct TextSize(f32);

impl TextSize {
    pub fn of(theme: &crate::theme::Theme) -> TextSize {
        TextSize(crate::tools::title_block::text_size(theme) * SCALE)
    }

    fn get(self) -> f32 {
        self.0
    }

    /// The pitch between the block's lines.
    fn line(self) -> f32 {
        self.0 + LEADING
    }

    /// The band a page keeps clear under its drawing for the block.
    fn footer(self) -> f32 {
        BLOCK_ROWS * self.line() + 2.0 * BLOCK_PAD
    }

    fn font(self) -> Font {
        Font::canvas(self.0)
    }
}
/// The rule's corner radius and weight.
const BLOCK_RADIUS: f32 = 3.0;
const BLOCK_BORDER: f32 = 0.6;

/// What a PDF export is taken from.
pub struct Scene<'a> {
    pub document: IndexedDocument<'a>,
    /// The session's theme. Its role→base table is kept and only the palette
    /// is swapped, so a user's role edits survive into print.
    pub theme: &'a crate::theme::Theme,
    /// The palette family to print in, at [`Luminance::Light`].
    pub scheme: blockworx_paint::Scheme,
    pub font: blockworx_paint::FontChoice,
    /// What every page's title block states — the same statement, from the
    /// same definition, that the editor's block draws.
    pub block: crate::tools::title_block::TitleBlock,
    /// This export's own stamp, for the PDF's document information. Not the
    /// block's `from`, which says where the *document* came from.
    pub provenance: Option<Provenance>,
}

/// How a scope's world-space `frame` is placed on its page: at a given
/// scale, centred in the content box. Page coordinates are krilla's —
/// points, y down from the page's top-left corner.
#[derive(Clone, Copy, PartialEq, Debug)]
pub struct Fit {
    scale: f32,
    /// Page-point translation applied after scaling.
    offset: Vec2,
}

impl Fit {
    /// `frame` placed in `content` at `scale`, centred. The scale is the
    /// document's, not the page's, so nothing here can stretch or shrink a
    /// drawing to its sheet.
    pub fn at(frame: Rect, content: Rect, scale: f32) -> Fit {
        let centring = (content.size() - frame.size() * scale) / 2.0;
        Fit {
            scale,
            offset: content.min.to_vec2() + centring - frame.min.to_vec2() * scale,
        }
    }

    /// Where a world-space rect lands on the page.
    pub fn place(self, world: Rect) -> Rect {
        Rect::from_min_max(
            (world.min.to_vec2() * self.scale + self.offset).to_pos2(),
            (world.max.to_vec2() * self.scale + self.offset).to_pos2(),
        )
    }
}

/// One scope's sheet: cut to the drawing it holds — the scope's extent at
/// the document scale, plus margins and the title block's band, floored and
/// capped — and the placement of that drawing on it.
pub struct Sheet {
    pub size: Vec2,
    pub fit: Fit,
    footer: f32,
}

impl Sheet {
    /// The sheet cut for a scope whose drawing spans `frame`, under a title
    /// block set at `text`.
    pub fn for_frame(frame: Rect, text: TextSize) -> Sheet {
        // An empty scope renders to no rect at all; it gets the floor sheet.
        let frame = if frame.is_finite() && frame.is_positive() {
            frame
        } else {
            Rect::ZERO
        };
        let footer = text.footer();
        let chrome = Vec2::new(2.0 * MARGIN, 2.0 * MARGIN + footer);
        let scale = [
            (MAX_PAGE - chrome.x) / frame.width(),
            (MAX_PAGE - chrome.y) / frame.height(),
        ]
        .into_iter()
        .filter(|s| s.is_finite() && *s > 0.0)
        .fold(SCALE, f32::min);
        let size = (frame.size() * scale + chrome).max(MIN_PAGE);
        Sheet {
            size,
            fit: Fit::at(frame, content_box(size, footer), scale),
            footer,
        }
    }

    /// The band the drawing is placed in: the sheet less its margins and the
    /// title block below.
    #[cfg_attr(not(test), allow(dead_code))]
    fn content_box(&self) -> Rect {
        content_box(self.size, self.footer)
    }
}

/// The band a sheet of `size` places its drawing in.
fn content_box(size: Vec2, footer: f32) -> Rect {
    Rect::from_min_max(
        pos2(MARGIN, MARGIN),
        pos2(size.x - MARGIN, size.y - MARGIN - footer),
    )
}

/// A scope and the scopes it holds: the navigator's hierarchy, with a page
/// number attached to each node.
struct Scoped {
    path: BlockPath,
    title: String,
    page: usize,
    /// Child scopes, in [`child_blocks`] order — the navigator's order.
    children: Vec<Scoped>,
}

impl Scoped {
    /// Pre-order, which is the order pages were numbered in, so the nth
    /// element is the nth page.
    fn flatten<'a>(&'a self, out: &mut Vec<&'a Scoped>) {
        out.push(self);
        for child in &self.children {
            child.flatten(out);
        }
    }

    fn outline_node(&self) -> OutlineNode {
        let mut node = OutlineNode::new(self.title.clone(), destination(self.page)).with_open(true);
        for child in &self.children {
            node.push_child(child.outline_node());
        }
        node
    }
}

/// The top of a page, which is where a jump to a scope should land.
fn destination(page: usize) -> XyzDestination {
    XyzDestination::new(page, Point::from_xy(0.0, 0.0))
}

/// A scope's heading: the block's title, or `untitled block` where it has
/// none.
fn scope_title(document: &IndexedDocument<'_>, id: BlockId) -> String {
    let name = document
        .doc
        .block(&id)
        .map(|block| block.title.name.clone());
    crate::edit::describe::bare("block", name)
}

/// Walk the navigation hierarchy from the document's designated top,
/// numbering pages depth-first as the navigator lists them.
fn plan(document: &IndexedDocument<'_>, name: String) -> Scoped {
    fn descend(
        document: &IndexedDocument<'_>,
        path: BlockPath,
        title: String,
        next: &mut usize,
    ) -> Scoped {
        let page = *next;
        *next += 1;
        let children = child_blocks(document, path.scope())
            .into_iter()
            .filter(|&id| crate::path::structure(document, id).opens_a_scope())
            .map(|id| {
                let mut child = path.clone();
                child.push(id);
                descend(document, child, scope_title(document, id), next)
            })
            .collect();
        Scoped {
            path,
            title,
            page,
            children,
        }
    }
    descend(document, BlockPath::opening(document.doc), name, &mut 0)
}

/// Every scope this export cuts a page for, in page order — the plan's own
/// answer, for the test that holds the PDF's pages, the navigator's branches
/// and the canvas's double borders to one predicate.
#[cfg(test)]
pub(crate) fn page_scopes(document: &IndexedDocument<'_>) -> Vec<crate::path::Scope> {
    let planned = plan(document, "drawing".to_owned());
    let mut order = Vec::new();
    planned.flatten(&mut order);
    order.iter().map(|scoped| scoped.path.scope()).collect()
}

/// Render `scene` to PDF bytes: one page per scope, outlined and cross-linked.
pub fn export(scene: Scene<'_>) -> anyhow::Result<Vec<u8>> {
    let Scene {
        document,
        theme,
        scheme,
        font,
        block,
        provenance,
    } = scene;

    let mut theme = theme.clone();
    theme.set_palette(scheme.palette(Luminance::Light));
    let sheet_font = PdfFont::new(font.bytes().into(), 0);
    let text = TextSize::of(&theme);

    let root = plan(&document, block.name.clone());
    let mut order = Vec::new();
    root.flatten(&mut order);

    // epaint measures what krilla draws — in the same family, so the widths
    // the block is laid out from are the widths the glyphs take. The
    // toolkit's own layout is the one source of text extents (CLAUDE.md —
    // consume it, don't approximate it).
    let mut fonts = egui::epaint::text::Fonts::new(
        egui::epaint::text::TextOptions::default(),
        crate::canvas::build_fonts(font),
    );
    let mut pdf = Pdf::new_with(SerializeSettings::default());
    for (index, scope) in order.iter().enumerate() {
        draw_page(
            &mut pdf,
            &Page {
                document: &document,
                theme: &theme,
                font,
                sheet_font: sheet_font.as_ref(),
                text,
                scope,
                block: &block,
                ancestors: ancestors_of(&order, index),
            },
            &mut fonts,
        )?;
    }

    let mut outline = Outline::new();
    outline.push_child(root.outline_node());
    pdf.set_outline(outline);
    pdf.set_metadata(metadata(&block.name, provenance.as_ref()));

    Ok(pdf.finish()?)
}

/// The page of every scope `order[index]` hangs from, outermost first — one
/// per ancestor segment of its path, which is what the title block's Path row
/// links each of its own segments to. Pre-order puts every ancestor before
/// its descendants, so the search only ever looks backwards.
fn ancestors_of(order: &[&Scoped], index: usize) -> Vec<usize> {
    let path = order[index].path.segments();
    (1..path.len())
        .filter_map(|depth| {
            order[..index]
                .iter()
                .rev()
                .find(|scope| scope.path.segments() == &path[..depth])
                .map(|scope| scope.page)
        })
        .collect()
}

/// Everything one page is drawn from.
struct Page<'a> {
    document: &'a IndexedDocument<'a>,
    theme: &'a crate::theme::Theme,
    font: blockworx_paint::FontChoice,
    /// The typeface the sheet's own text is set in — the drawing's, so the
    /// title block matches the titles above it.
    sheet_font: Option<&'a PdfFont>,
    text: TextSize,
    scope: &'a Scoped,
    /// What every page's title block states.
    block: &'a crate::tools::title_block::TitleBlock,
    /// The page each ancestor segment of this scope's path opens, outermost
    /// first. The last segment is this page itself and gets no link.
    ancestors: Vec<usize>,
}

fn draw_page(
    pdf: &mut Pdf,
    page: &Page<'_>,
    fonts: &mut egui::epaint::text::Fonts,
) -> anyhow::Result<()> {
    let mut presentation = crate::presentation::Presentation::default();
    let level = crate::export::level::render_level(
        page.theme,
        page.font,
        *page.document,
        &page.scope.path,
        &mut presentation,
    );
    let tree = usvg::Tree::from_str(&level.svg, &usvg::Options::default())?;
    let sheet = Sheet::for_frame(level.frame, page.text);
    let fit = sheet.fit;

    let size = Size::from_wh(sheet.size.x, sheet.size.y)
        .ok_or_else(|| anyhow::anyhow!("the page size is degenerate"))?;
    let mut pdf_page = pdf.start_page_with(PageSettings::new(size));
    let mut printed = None;
    {
        let mut surface = pdf_page.surface();

        let mut ground = PathBuilder::new();
        if let Some(rect) = PdfRect::from_xywh(0.0, 0.0, sheet.size.x, sheet.size.y) {
            ground.push_rect(rect);
        }
        if let Some(path) = ground.finish() {
            surface.set_fill(Some(fill(page.theme, Role::CanvasBackground)));
            surface.draw_path(&path);
        }

        if let Some(font) = page.sheet_font {
            printed = draw_title_block(&mut surface, fonts, page, &sheet, font);
        }

        let origin = fit.place(level.frame).min;
        surface.push_transform(&Transform::from_row(
            fit.scale, 0.0, 0.0, fit.scale, origin.x, origin.y,
        ));
        let svg_size = Size::from_wh(tree.size().width(), tree.size().height())
            .ok_or_else(|| anyhow::anyhow!("the rendered scope has no extent"))?;
        surface.draw_svg(&tree, svg_size, SvgSettings::default());
        surface.pop();
        surface.finish();
    }

    for child in &page.scope.children {
        let Some(id) = child.path.scope().block() else {
            continue;
        };
        let Some(world) = level
            .blocks
            .iter()
            .find(|&&(block, _)| block == id)
            .map(|&(_, rect)| rect)
        else {
            continue;
        };
        if let Some(link) = link(fit.place(world), child.page, &child.title) {
            pdf_page.add_annotation(link);
        }
    }
    // Every scope this page hangs from is reachable from the Path row it is
    // named in — better than one strip back to the parent, which could only
    // ever offer the step above.
    for (rect, target, name) in printed.into_iter().flat_map(|p| p.links) {
        if let Some(link) = link(rect, target, &name) {
            pdf_page.add_annotation(link);
        }
    }
    pdf_page.finish();
    Ok(())
}

/// What printing the title block leaves behind for the page to place: the
/// rule around it, and a link over each ancestor segment of its Path row.
struct Printed {
    #[cfg_attr(not(test), allow(dead_code))]
    frame: Rect,
    links: Vec<(Rect, usize, String)>,
}

/// The title block, in the corner an ECAD sheet keeps it, from the one
/// definition the editor's block is also drawn from
/// ([`crate::tools::title_block::Grid`]): a two-column head over the path and
/// whatever else runs wide, anchored to the lower-right margin from epaint's
/// measured widths and ruled like a sheet's block.
///
/// The path's ancestor segments carry link annotations to their own pages, so
/// every scope this one hangs from is one click away from the row that names
/// it — which is what retired the heading strip that used to offer the step
/// above and nothing else.
fn draw_title_block(
    surface: &mut krilla::surface::Surface<'_>,
    fonts: &mut egui::epaint::text::Fonts,
    page: &Page<'_>,
    sheet: &Sheet,
    font: &PdfFont,
) -> Option<Printed> {
    let mut text = Measured {
        fonts,
        font: page.text.font(),
    };
    let segments = crate::tools::content_path::segments(page.document, &page.scope.path);
    let grid = page.block.grid(&segments);

    // What the sheet leaves the block, and how that is shared out: a head
    // column gets half of it where there are two, and a wide line all of it.
    let inner = sheet.size.x - 2.0 * (MARGIN + BLOCK_PAD);
    let share = if grid.right.is_empty() {
        inner
    } else {
        (inner - COLUMN_GAP) / 2.0
    };
    let left = Column::lay_out(&mut text, &grid.left, share, Fitting::ByCharacter);
    let right = Column::lay_out(&mut text, &grid.right, share, Fitting::ByCharacter);
    let wide = Column::lay_out(&mut text, &grid.wide, inner, Fitting::BySegment);

    let head_width = if right.cells.is_empty() {
        left.width
    } else {
        left.width + COLUMN_GAP + right.width
    };
    let width = head_width.max(wide.width);
    let rows = grid.head_rows() + grid.wide.len();
    let line = page.text.line();
    let (ascent, line_box) = (text.ascent(), text.height());
    let height = (rows.saturating_sub(1) as f32) * line + line_box;

    let block = Rect::from_min_max(
        pos2(
            sheet.size.x - MARGIN - BLOCK_PAD - width,
            sheet.size.y - MARGIN - BLOCK_PAD - height,
        ),
        pos2(
            sheet.size.x - MARGIN - BLOCK_PAD,
            sheet.size.y - MARGIN - BLOCK_PAD,
        ),
    );
    let baseline = |row: usize| block.min.y + row as f32 * line + ascent;

    let mut links = Vec::new();
    for (row, cell) in left.cells.iter().enumerate() {
        cell.draw(
            surface,
            page,
            font,
            At {
                x: block.min.x,
                baseline: baseline(row),
                captions: left.captions,
            },
        );
    }
    for (row, cell) in right.cells.iter().enumerate() {
        cell.draw(
            surface,
            page,
            font,
            At {
                x: block.min.x + left.width + COLUMN_GAP,
                baseline: baseline(row),
                captions: right.captions,
            },
        );
    }
    for (row, cell) in wide.cells.iter().enumerate() {
        let baseline = baseline(grid.head_rows() + row);
        let value_x = cell.draw(
            surface,
            page,
            font,
            At {
                x: block.min.x,
                baseline,
                captions: wide.captions,
            },
        );
        links.extend(ancestor_links(
            &mut text,
            page,
            cell,
            Placed {
                x: value_x,
                top: baseline - ascent,
                height: line_box,
            },
        ));
    }

    surface.set_fill(None);
    // Ruled from the block that was actually laid out, so the frame holds it
    // rather than the band it was assumed to fill.
    let frame = block.expand(BLOCK_PAD);
    let path = rounded_rect(frame, BLOCK_RADIUS)?;
    surface.set_stroke(Some(Stroke {
        paint: paint(page.theme, Role::TitleBlockBorder),
        width: BLOCK_BORDER,
        ..Stroke::default()
    }));
    surface.draw_path(&path);
    surface.set_stroke(None);
    Some(Printed { frame, links })
}

/// Where one of the block's lines goes: the left edge of its caption, the
/// baseline it sits on, and the width of the caption column beside it.
#[derive(Clone, Copy)]
struct At {
    x: f32,
    baseline: f32,
    captions: f32,
}

/// Where a line's value was set: its left edge and the line box it fills.
#[derive(Clone, Copy)]
struct Placed {
    x: f32,
    top: f32,
    height: f32,
}

/// A link over each ancestor segment of `cell`'s path, aimed at that
/// ancestor's page. The last segment names this page and gets none; a segment
/// the line had no room for was dropped, and its link with it.
fn ancestor_links(
    text: &mut Measured<'_>,
    page: &Page<'_>,
    cell: &Laid,
    at: Placed,
) -> Vec<(Rect, usize, String)> {
    let Some(kept) = cell.kept.as_ref() else {
        return Vec::new();
    };
    let Placed { top, height, .. } = at;
    let mut links = Vec::new();
    // `kept.first` is where the drawn segments start in the whole path, and
    // `kept.elided` the ellipsis standing in for what came before them.
    let mut x = at.x + text.width(kept.elided);
    for (offset, segment) in kept.segments.iter().enumerate() {
        let width = text.width(segment);
        let index = kept.first + offset;
        if let Some(&target) = page.ancestors.get(index) {
            links.push((
                Rect::from_min_max(pos2(x, top), pos2(x + width, top + height)),
                target,
                segment.clone(),
            ));
        }
        x += width + text.width(crate::tools::content_path::SEPARATOR_STR);
    }
    links
}

/// A link annotation over `rect` jumping to the top of `page`.
fn link(rect: Rect, page: usize, alt: &str) -> Option<Annotation> {
    let rect = PdfRect::from_ltrb(rect.min.x, rect.min.y, rect.max.x, rect.max.y)?;
    Some(Annotation::new_link(
        LinkAnnotation::new(rect, Target::Destination(destination(page).into())),
        Some(alt.to_owned()),
    ))
}

/// epaint's text extents in the family and size the block is set in — the
/// toolkit's own layout, which is what krilla then draws.
struct Measured<'a> {
    fonts: &'a mut egui::epaint::text::Fonts,
    font: Font,
}

impl Measured<'_> {
    fn galley(&mut self, text: &str) -> std::sync::Arc<egui::Galley> {
        // Measured, never painted: the PDF writer sets its own ink, so this
        // is egui's "recolor me" sentinel rather than a color.
        self.fonts.with_pixels_per_point(1.0).layout_no_wrap(
            text.to_owned(),
            (&self.font).egui(),
            Color::PLACEHOLDER.egui(),
        )
    }

    fn width(&mut self, text: &str) -> f32 {
        self.galley(text).size().x
    }

    /// The line box one run of this text occupies.
    fn height(&mut self) -> f32 {
        self.galley(MEASURING_RUN).size().y
    }

    /// Where a line's baseline sits below its top edge.
    fn ascent(&mut self) -> f32 {
        let galley = self.galley(MEASURING_RUN);
        galley
            .rows
            .iter()
            .flat_map(|row| row.glyphs.iter())
            .next()
            .map_or_else(|| galley.size().y, |glyph| glyph.font_ascent)
    }
}

/// A run with an ascender and a descender, so the line box measured off it is
/// the one every line of the block gets.
const MEASURING_RUN: &str = "Ag";

/// How a value too wide for its column gives way.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Fitting {
    /// Character by character from the front, an ellipsis standing in for
    /// what went.
    ByCharacter,
    /// Whole path segments from the front — a half-eaten name links to
    /// nothing and reads as nothing, so a segment is kept or dropped.
    BySegment,
}

/// Which of a path's segments a line had room for.
struct Kept {
    /// Index of the first surviving segment in the whole path.
    first: usize,
    segments: Vec<String>,
    /// What stands in front of them for the ones that were dropped.
    elided: &'static str,
}

/// One cell placed on its line: what it draws, and — for a path — which of
/// its segments survived the fit.
struct Laid {
    caption: &'static str,
    value: String,
    emphasis: crate::tools::title_block::Emphasis,
    kept: Option<Kept>,
}

impl Laid {
    /// Draw the cell at `x` on `baseline`, its value set clear of a caption
    /// column `captions` wide. Returns where the value starts.
    fn draw(
        &self,
        surface: &mut krilla::surface::Surface<'_>,
        page: &Page<'_>,
        font: &PdfFont,
        at: At,
    ) -> f32 {
        use crate::tools::title_block::Emphasis;
        let mut set = |text: &str, x: f32, role: Role| {
            if text.is_empty() {
                return;
            }
            surface.set_fill(Some(fill(page.theme, role)));
            surface.draw_text(
                Point::from_xy(x, at.baseline),
                font.clone(),
                page.text.get(),
                text,
                false,
                TextDirection::Auto,
            );
        };
        set(self.caption, at.x, Role::ShapeType);
        let value_x = at.x + at.captions + CAPTION_GAP;
        set(
            &self.value,
            value_x,
            match self.emphasis {
                Emphasis::Title => Role::ShapeTitle,
                Emphasis::Body => Role::ShapeType,
            },
        );
        value_x
    }
}

/// One column of the block, measured: its cells as they will be drawn, how
/// wide its captions are, and how wide the column ends up.
struct Column {
    cells: Vec<Laid>,
    captions: f32,
    width: f32,
}

impl Column {
    fn lay_out(text: &mut Measured<'_>, cells: &[Cell], share: f32, fitting: Fitting) -> Column {
        use crate::tools::title_block::Value;
        let captions = cells
            .iter()
            .map(|cell| text.width(cell.caption))
            .fold(0.0, f32::max);
        let room = (share - captions - CAPTION_GAP).max(0.0);
        let laid: Vec<Laid> = cells
            .iter()
            .map(|cell| match (&cell.value, fitting) {
                (Value::Path(segments), Fitting::BySegment) => {
                    let kept = fit_segments(text, segments, room);
                    Laid {
                        caption: cell.caption,
                        value: format!(
                            "{}{}",
                            kept.elided,
                            crate::tools::content_path::join(&kept.segments)
                        ),
                        emphasis: cell.emphasis,
                        kept: Some(kept),
                    }
                }
                (value, _) => Laid {
                    caption: cell.caption,
                    value: shortened(text, value.text(), room),
                    emphasis: cell.emphasis,
                    kept: None,
                },
            })
            .collect();
        let values = laid
            .iter()
            .map(|cell| text.width(&cell.value))
            .fold(0.0, f32::max);
        Column {
            width: if laid.is_empty() {
                0.0
            } else {
                captions + CAPTION_GAP + values
            },
            cells: laid,
            captions,
        }
    }
}

/// The trailing run of `segments` that measures inside `width` — a path's
/// tail is the part that names where you are — with an ellipsis for the rest.
/// At least one segment is always kept: a path that says nothing at all is
/// worse than one that overruns its column.
fn fit_segments(text: &mut Measured<'_>, segments: &[String], width: f32) -> Kept {
    for first in 0..segments.len().saturating_sub(1) {
        let elided = if first == 0 { "" } else { ELIDED };
        let candidate = format!(
            "{elided}{}",
            crate::tools::content_path::join(&segments[first..])
        );
        if text.width(&candidate) <= width {
            return Kept {
                first,
                segments: segments[first..].to_vec(),
                elided,
            };
        }
    }
    let first = segments.len().saturating_sub(1);
    Kept {
        first,
        segments: segments[first..].to_vec(),
        elided: if first == 0 { "" } else { ELIDED },
    }
}

/// What stands in for the head of a path a line had no room for.
const ELIDED: &str = "\u{2026}/";

/// `text` trimmed from the *front* until it measures inside `width`.
fn shortened(fonts: &mut Measured<'_>, text: String, width: f32) -> String {
    if fonts.width(&text) <= width {
        return text;
    }
    let mut chars = text.chars();
    loop {
        if chars.next().is_none() {
            return String::from("\u{2026}");
        }
        let candidate = format!("\u{2026}{}", chars.as_str());
        if fonts.width(&candidate) <= width {
            return candidate;
        }
    }
}

/// The circular-arc control-point ratio: a quarter circle drawn as one cubic
/// puts its handles this fraction of the radius from the corner.
const KAPPA: f32 = 0.552_284_8;

/// A rounded rectangle, cornered with cubics — krilla's path builder speaks
/// segments, not primitives with radii.
fn rounded_rect(rect: Rect, radius: f32) -> Option<krilla::geom::Path> {
    let radius = radius.min(rect.width() / 2.0).min(rect.height() / 2.0);
    if !rect.is_positive() || !radius.is_finite() || radius <= 0.0 {
        return None;
    }
    let handle = radius * KAPPA;
    let (l, t, r, b) = (rect.left(), rect.top(), rect.right(), rect.bottom());
    let mut path = PathBuilder::new();
    path.move_to(l + radius, t);
    path.line_to(r - radius, t);
    path.cubic_to(
        r - radius + handle,
        t,
        r,
        t + radius - handle,
        r,
        t + radius,
    );
    path.line_to(r, b - radius);
    path.cubic_to(
        r,
        b - radius + handle,
        r - radius + handle,
        b,
        r - radius,
        b,
    );
    path.line_to(l + radius, b);
    path.cubic_to(
        l + radius - handle,
        b,
        l,
        b - radius + handle,
        l,
        b - radius,
    );
    path.line_to(l, t + radius);
    path.cubic_to(
        l,
        t + radius - handle,
        l + radius - handle,
        t,
        l + radius,
        t,
    );
    path.close();
    path.finish()
}

fn paint(theme: &crate::theme::Theme, role: Role) -> krilla::paint::Paint {
    let color = theme.resolve(role);
    rgb::Color::new(color.r(), color.g(), color.b()).into()
}

fn fill(theme: &crate::theme::Theme, role: Role) -> Fill {
    Fill {
        paint: paint(theme, role),
        opacity: NormalizedF32::ONE,
        rule: krilla::paint::FillRule::default(),
    }
}

/// The document information a reader shows. No creation date is written: the
/// only clock available would make two exports of one document differ, and a
/// byte-identical export is what the golden pins.
fn metadata(name: &str, provenance: Option<&Provenance>) -> Metadata {
    let metadata = Metadata::new()
        .title(name.to_owned())
        .creator(env!("CARGO_PKG_NAME").to_owned())
        .document_id(name.to_owned());
    match provenance {
        None => metadata,
        Some(from) => metadata
            .authors(vec![from.author.clone()])
            .description(format!("{} \u{2014} {}", from.line(), from.detail())),
    }
}

#[cfg(test)]
mod tests;