fleuron/

pdf.rs

//! PDF export: display structure in, PDF bytes out.
//!
//! The painter for print. Everything it needs already exists on the
//! page — glyph ids, absolute positions, page trim — so this stage
//! places what layout decided and decides nothing itself.
//!
//! Glyphs are shown at their own x, not at the font's: kerning and
//! justification put them where they are, and a PDF that re-derived
//! positions from advances would disagree with the preview. The text
//! each run was shaped from travels with it, so the writer can build
//! the glyph-to-character map that makes the text selectable.
//!
//! Links and the outline are layout's too: each link arrives on its
//! page with the areas it covers and the place it goes, and each outline entry with
//! the place of its heading.

use krilla::action::LinkAction;
use krilla::annotation::{Annotation, LinkAnnotation, Target};
use krilla::color::rgb;
use krilla::destination::XyzDestination;
use krilla::geom::{PathBuilder, Point, Rect, Size, Transform};
use krilla::image::Image;
use krilla::metadata::{DateTime, Metadata as PdfMetadata};
use krilla::num::NormalizedF32;
use krilla::outline::{Outline, OutlineNode};
use krilla::page::PageSettings;
use krilla::paint::{Fill, FillRule};
use krilla::surface::Surface;
use krilla::text::{Font, GlyphId, KrillaGlyph, Tag};
use krilla::{Document, SerializeSettings};

use crate::LayoutOutput;
use crate::content::Metadata;
use crate::fonts::FontRegistry;
use crate::images::Assets;
use crate::pages::{Corners, DrawItem, Glyph, LinkTo, OutlineEntry, Page, PageBox};
use crate::style::Color;

/// What can go wrong turning the display structure into a PDF.
#[derive(Debug, thiserror::Error)]
pub enum PdfError {
    /// The face named could not be embedded.
    #[error("font {0} could not be embedded")]
    Font(String),
    /// The image named is in no format the writer can embed.
    #[error("image {0} could not be embedded")]
    Image(String),
    /// A draw item falls outside what PDF can express.
    #[error("page {number} draws {kind} outside what PDF can express")]
    Geometry {
        /// The folio the offending item is on.
        number: u32,
        /// What kind of item it was.
        kind: &'static str,
    },
    /// The writer refused the document.
    #[error("PDF serialization failed: {0}")]
    Serialize(String),
}

/// Writes one laid-out book as PDF bytes.
///
/// Fonts resolve through the registry that shaped the run and images
/// through the table that sized them: the display structure names
/// indexes, the tables own the files, and so the embedded subset has
/// the outlines the shaper measured and the embedded image is the
/// file the header was read from.
///
/// A book with no images passes [`Assets::none`].
pub fn write(
    output: &LayoutOutput,
    registry: &FontRegistry,
    assets: &Assets,
    metadata: &Metadata,
) -> Result<Vec<u8>, PdfError> {
    write_with(
        output,
        registry,
        assets,
        metadata,
        SerializeSettings::default(),
    )
}

fn write_with(
    output: &LayoutOutput,
    registry: &FontRegistry,
    assets: &Assets,
    metadata: &Metadata,
    settings: SerializeSettings,
) -> Result<Vec<u8>, PdfError> {
    let fonts = embed_fonts(registry)?;
    let images = embed_images(assets)?;
    let mut document = Document::new_with(settings);
    document.set_metadata(document_metadata(metadata));
    for page in &output.pages {
        let mut pdf_page = document.start_page_with(PageSettings::new(page.width, page.height));
        let mut surface = pdf_page.surface();
        for item in &page.items {
            paint(&mut surface, item, page, &fonts, &images, registry)?;
        }
        surface.finish();
        for link in &page.links {
            for area in &link.areas {
                if let Some(annotation) = annotation(area, &link.to) {
                    pdf_page.add_annotation(annotation);
                }
            }
        }
        pdf_page.finish();
    }
    if !output.navigation.outline.is_empty() {
        let mut outline = Outline::new();
        for entry in &output.navigation.outline {
            outline.push_child(outline_node(entry));
        }
        document.set_outline(outline);
    }
    document
        .finish()
        .map_err(|e| PdfError::Serialize(format!("{e:?}")))
}

/// One line of a link as the annotation a viewer follows. An empty
/// area is none.
fn annotation(area: &PageBox, to: &LinkTo) -> Option<Annotation> {
    let rect = Rect::from_xywh(area.x, area.y, area.width, area.height)?;
    let target = match to {
        LinkTo::Place { place, .. } => Target::Destination(destination(place).into()),
        LinkTo::Uri(uri) => Target::Action(LinkAction::new(uri.clone()).into()),
    };
    Some(LinkAnnotation::new(rect, target).into())
}

/// The top left corner of a box, on its page.
fn destination(place: &PageBox) -> XyzDestination {
    XyzDestination::new(place.page as usize, Point::from_xy(place.x, place.y))
}

/// One heading of the outline, and the headings under it.
fn outline_node(entry: &OutlineEntry) -> OutlineNode {
    let mut node = OutlineNode::new(entry.title.clone(), destination(&entry.place));
    for child in &entry.children {
        node.push_child(outline_node(child));
    }
    node
}

/// Every asset as a krilla image, indexed as the display structure
/// indexes them.
///
/// The format is read off the bytes rather than off the url, since a
/// url never has to name one: `/asset/8412` is a perfectly good
/// one. PDF's `DCTDecode` is the JPEG stream
/// itself, so a JPEG travels into the file as it arrived; the raster
/// formats are decoded once, alpha channel and all.
fn embed_images(assets: &Assets) -> Result<Vec<Image>, PdfError> {
    assets
        .assets()
        .iter()
        .enumerate()
        .map(|(index, asset)| {
            let bytes = assets
                .bytes(index as u32)
                .ok_or_else(|| PdfError::Image(asset.url.clone()))?
                .to_vec();
            embed_image(bytes).ok_or_else(|| PdfError::Image(asset.url.clone()))
        })
        .collect()
}

/// One image, in whichever format its own header says it is.
///
/// Interpolation is off, because an image placed at the size its own
/// header asked for is already at the resolution it was made for.
fn embed_image(bytes: Vec<u8>) -> Option<Image> {
    let data = krilla::Data::from(bytes);
    match () {
        _ if data.as_ref().starts_with(b"\x89PNG\r\n\x1a\n") => Image::from_png(data, false),
        _ if data.as_ref().starts_with(&[0xFF, 0xD8]) => Image::from_jpeg(data, false),
        _ if data.as_ref().starts_with(b"GIF8") => Image::from_gif(data, false),
        _ if data.as_ref().starts_with(b"RIFF") => Image::from_webp(data, false),
        _ => None,
    }
}

/// Every registered face as a krilla font, indexed by `font_id`.
/// krilla subsets on write, so a face nothing draws with costs
/// nothing.
///
/// A face off its family's default location embeds as that instance:
/// the outlines a reader gets are the ones the shaper measured, not
/// the whole axis.
fn embed_fonts(registry: &FontRegistry) -> Result<Vec<Font>, PdfError> {
    (0..registry.len() as u16)
        .map(|id| {
            let name = || {
                registry
                    .font_ref(id)
                    .map(|f| f.name.clone())
                    .unwrap_or_else(|| id.to_string())
            };
            let bytes = registry.bytes(id).ok_or_else(|| PdfError::Font(name()))?;
            let variations: Vec<(Tag, f32)> = registry
                .variations(id)
                .unwrap_or_default()
                .iter()
                .map(|axis| (Tag::new(&axis.tag), axis.value))
                .collect();
            Font::new_variable(bytes.into(), 0, &variations).ok_or_else(|| PdfError::Font(name()))
        })
        .collect()
}

/// Book metadata as document metadata. `fleuron` is both creator and
/// producer: the engine laid the pages out and wrote the file.
///
/// The creation date is the book's own `date`, because the engine
/// reads no clock: a run that stamped the hour would write different
/// bytes every time it ran, and two runs over one book are meant to
/// be one file.
fn document_metadata(metadata: &Metadata) -> PdfMetadata {
    let mut pdf = PdfMetadata::new()
        .creator("fleuron".to_string())
        .producer("fleuron".to_string());
    if let Some(title) = &metadata.title {
        pdf = pdf.title(title.clone());
    }
    if let Some(author) = &metadata.author {
        pdf = pdf.authors(vec![author.clone()]);
    }
    if let Some(language) = metadata.language() {
        pdf = pdf.language(language.to_string());
    }
    if let Some(date) = metadata.extra.get("date").and_then(|date| written(date)) {
        pdf = pdf.creation_date(date);
    }
    pdf
}

/// A date as a book writes one: `2026-08-27`, and as much of
/// `T14:30:00` after it as the book bothered with. Anything else is
/// no date and no creation date.
fn written(date: &str) -> Option<DateTime> {
    let number = |field: Option<&str>, digits: usize| -> Option<u16> {
        let field = field?;
        (field.len() == digits && field.bytes().all(|b| b.is_ascii_digit()))
            .then(|| field.parse().ok())?
    };
    let (day, clock) = match date.split_once(['T', ' ']) {
        Some((day, clock)) => (day, Some(clock)),
        None => (date, None),
    };
    let mut fields = day.split('-');
    let mut stamp = DateTime::new(number(fields.next(), 4)?);
    if let Some(month) = number(fields.next(), 2) {
        stamp = stamp.month(month as u8);
        if let Some(day) = number(fields.next(), 2) {
            stamp = stamp.day(day as u8);
        }
    }
    let mut fields = clock.unwrap_or_default().split(':');
    if let Some(hour) = number(fields.next(), 2) {
        stamp = stamp.hour(hour as u8);
        if let Some(minute) = number(fields.next(), 2) {
            stamp = stamp.minute(minute as u8);
            if let Some(second) = number(fields.next(), 2) {
                stamp = stamp.second(second as u8);
            }
        }
    }
    Some(stamp)
}

fn paint(
    surface: &mut Surface,
    item: &DrawItem,
    page: &Page,
    fonts: &[Font],
    images: &[Image],
    registry: &FontRegistry,
) -> Result<(), PdfError> {
    match item {
        DrawItem::Text {
            x,
            y,
            font_id,
            size,
            text,
            source,
            source_map,
            // The glyphs are here; the features that chose them are
            // for a painter that has to choose its own. Where the run
            // was written is for a preview that follows a cursor; a
            // page of a PDF does not move.
            features: _,
            origin: _,
            pseudo_element: _,
            // Each glyph carries its own x.
            width: _,
            // The page's items arrived in paint order, so the layer
            // that put them in it is spent.
            layer: _,
            color,
            glyphs,
        } => {
            ink(surface, *color);
            let font = fonts
                .get(*font_id as usize)
                .ok_or_else(|| PdfError::Font(font_id.to_string()))?;
            // What a reader selects and what a search matches is the
            // manuscript, so a run that was transformed hands over
            // what the author wrote rather than what was drawn.
            let extracted = extracted(text, source, source_map, glyphs);
            let placed = place(glyphs, &extracted, *x, *size, *font_id, registry);
            surface.draw_glyphs(
                Point::from_xy(*x, *y),
                &placed,
                font.clone(),
                extracted.text,
                *size,
                false,
            );
        }
        DrawItem::Rect {
            x,
            y,
            w,
            h,
            color,
            layer: _,
        } => {
            ink(surface, *color);
            let rect = Rect::from_xywh(*x, *y, *w, *h).ok_or(PdfError::Geometry {
                number: page.number,
                kind: "a rectangle",
            })?;
            let mut builder = PathBuilder::new();
            builder.push_rect(rect);
            let path = builder.finish().ok_or(PdfError::Geometry {
                number: page.number,
                kind: "a rectangle",
            })?;
            surface.draw_path(&path);
        }
        // The transform is layout's decision, not the writer's: an
        // image krilla draws into a unit square is translated to the
        // corner layout put it at and scaled to the box layout sized
        // for it.
        DrawItem::Image {
            x,
            y,
            w,
            h,
            asset,
            alpha,
            layer: _,
        } => {
            let image = images
                .get(*asset as usize)
                .ok_or_else(|| PdfError::Image(asset.to_string()))?;
            let size = Size::from_wh(*w, *h).ok_or(PdfError::Geometry {
                number: page.number,
                kind: "an image",
            })?;
            faded(surface, *alpha, |surface| {
                surface.push_transform(&Transform::from_translate(*x, *y));
                surface.draw_image(image.clone(), size);
                surface.pop();
            });
        }
        // The box clips and the tile is drawn inside it, once or as
        // many times as it takes to cover the box. Layout placed the
        // first tile; the rest are that tile stepped by its own size.
        DrawItem::Background {
            x,
            y,
            w,
            h,
            radii,
            tile_x,
            tile_y,
            tile_w,
            tile_h,
            repeat,
            asset,
            alpha,
            layer: _,
        } => {
            let image = images
                .get(*asset as usize)
                .ok_or_else(|| PdfError::Image(asset.to_string()))?;
            let size = Size::from_wh(*tile_w, *tile_h).ok_or(PdfError::Geometry {
                number: page.number,
                kind: "a background image",
            })?;
            let clip = Rect::from_xywh(*x, *y, *w, *h).ok_or(PdfError::Geometry {
                number: page.number,
                kind: "a background box",
            })?;
            let mut builder = PathBuilder::new();
            if radii.is_square() {
                builder.push_rect(clip);
            } else {
                outline(&mut builder, [*x, *y, *w, *h], *radii);
            }
            let path = builder.finish().ok_or(PdfError::Geometry {
                number: page.number,
                kind: "a background box",
            })?;
            faded(surface, *alpha, |surface| {
                surface.push_clip_path(&path, &FillRule::NonZero);
                for (left, top) in tiles(
                    [*x, *y, *w, *h],
                    [*tile_x, *tile_y, *tile_w, *tile_h],
                    *repeat,
                ) {
                    surface.push_transform(&Transform::from_translate(left, top));
                    surface.draw_image(image.clone(), size);
                    surface.pop();
                }
                surface.pop();
            });
        }
        // The even-odd rule is what leaves the inside of a ring empty.
        DrawItem::Rounded {
            x,
            y,
            w,
            h,
            radii,
            ring,
            color,
            layer: _,
        } => {
            surface.set_fill(Some(Fill {
                paint: rgb::Color::new(color.r, color.g, color.b).into(),
                opacity: opacity(color.a),
                rule: FillRule::EvenOdd,
            }));
            let mut builder = PathBuilder::new();
            outline(&mut builder, [*x, *y, *w, *h], *radii);
            let inner = [
                x + ring.left,
                y + ring.top,
                w - ring.left - ring.right,
                h - ring.top - ring.bottom,
            ];
            let hollow = ring.top > 0.0 || ring.right > 0.0 || ring.bottom > 0.0 || ring.left > 0.0;
            if hollow && inner[2] > 0.0 && inner[3] > 0.0 {
                outline(&mut builder, inner, radii.inside(*ring));
            }
            let path = builder.finish().ok_or(PdfError::Geometry {
                number: page.number,
                kind: "a rounded box",
            })?;
            surface.draw_path(&path);
        }
    }
    Ok(())
}

/// How far along its tangent each control point of a cubic curve sits,
/// as a fraction of the radius, for the curve to follow a quarter
/// ellipse.
const KAPPA: f32 = 0.552_284_8;

/// A box `[left, top, width, height]` with rounded corners, clockwise
/// from the top left. Each corner is one cubic curve.
fn outline(builder: &mut PathBuilder, box_: [f32; 4], radii: Corners) {
    let [x, y, w, h] = box_;
    let Corners {
        top_left: tl,
        top_right: tr,
        bottom_right: br,
        bottom_left: bl,
    } = radii;
    let near = 1.0 - KAPPA;
    builder.move_to(x + tl.x, y);
    builder.line_to(x + w - tr.x, y);
    builder.cubic_to(
        x + w - tr.x * near,
        y,
        x + w,
        y + tr.y * near,
        x + w,
        y + tr.y,
    );
    builder.line_to(x + w, y + h - br.y);
    builder.cubic_to(
        x + w,
        y + h - br.y * near,
        x + w - br.x * near,
        y + h,
        x + w - br.x,
        y + h,
    );
    builder.line_to(x + bl.x, y + h);
    builder.cubic_to(
        x + bl.x * near,
        y + h,
        x,
        y + h - bl.y * near,
        x,
        y + h - bl.y,
    );
    builder.line_to(x, y + tl.y);
    builder.cubic_to(x, y + tl.y * near, x + tl.x * near, y, x + tl.x, y);
    builder.close();
}

/// Draws what `draw` draws at an eight-bit alpha, and writes nothing
/// around it where the alpha is opaque.
fn faded(surface: &mut Surface, alpha: u8, draw: impl FnOnce(&mut Surface)) {
    if alpha == 255 {
        draw(surface);
        return;
    }
    surface.push_opacity(opacity(alpha));
    draw(surface);
    surface.pop();
}

/// How many tiles one background is drawn as, whatever the arithmetic
/// asks for. A tile a fraction of a point wide over a whole page
/// would otherwise be drawn a million times, and nobody sees past the
/// first few thousand.
const TILES: usize = 4096;

/// Where each copy of a repeated image is drawn, in paint order. One
/// copy where the sheet asked for no repeat. Both boxes are
/// `[left, top, width, height]`.
fn tiles(box_: [f32; 4], tile: [f32; 4], repeat: bool) -> Vec<(f32, f32)> {
    let [x, y, w, h] = box_;
    let [tile_x, tile_y, tile_w, tile_h] = tile;
    if !repeat {
        return vec![(tile_x, tile_y)];
    }
    // How far back the tiling starts, and how many copies it takes to
    // reach the far edge from there.
    let steps = |start: f32, edge: f32, extent: f32, step: f32| {
        let before = ((start - edge) / step).ceil().max(0.0) as usize;
        let after = ((edge + extent - start) / step).ceil().max(1.0) as usize;
        (start - before as f32 * step, (before + after).min(TILES))
    };
    let (first_x, across) = steps(tile_x, x, w, tile_w);
    let (first_y, down) = steps(tile_y, y, h, tile_h);
    let mut placed = Vec::with_capacity((across * down).min(TILES));
    for row in 0..down {
        for column in 0..across {
            if placed.len() == TILES {
                return placed;
            }
            placed.push((
                first_x + column as f32 * tile_w,
                first_y + row as f32 * tile_h,
            ));
        }
    }
    placed
}

/// What the next item is filled with. A page starts out filling in
/// opaque black, so a run in opaque black writes no colour at all.
fn ink(surface: &mut Surface, color: Color) {
    surface.set_fill((color != Color::BLACK).then(|| Fill {
        paint: rgb::Color::new(color.r, color.g, color.b).into(),
        opacity: opacity(color.a),
        ..Fill::default()
    }));
}

/// An eight-bit alpha as the opacity krilla takes.
fn opacity(alpha: u8) -> NormalizedF32 {
    NormalizedF32::new(alpha as f32 / 255.0).unwrap_or(NormalizedF32::ONE)
}

/// Display-structure glyphs as krilla glyphs.
///
/// krilla walks a run by advances from its origin, so an absolute x
/// becomes the gap to the glyph after it. The last glyph has no
/// successor and takes the advance its font gives it — anything else
/// would leave a spurious adjustment at the end of every run.
/// Advances are in ems, hence the division by size.
fn place(
    glyphs: &[Glyph],
    extracted: &Extracted<'_>,
    origin: f32,
    size: f32,
    font_id: u16,
    registry: &FontRegistry,
) -> Vec<KrillaGlyph> {
    let upem = registry
        .metrics(font_id)
        .map(|m| m.units_per_em as f32)
        .unwrap_or(1000.0);
    // The run's origin need not be its first glyph's x; the gap
    // shifts every glyph, since krilla measures the cursor from the
    // origin.
    let offset = glyphs.first().map(|g| g.x - origin).unwrap_or(0.0);
    glyphs
        .iter()
        .enumerate()
        .map(|(i, glyph)| {
            let advance = match glyphs.get(i + 1) {
                Some(next) => (next.x - glyph.x) / size,
                None => registry.advance_width(font_id, glyph.id).unwrap_or(0) as f32 / upem,
            };
            KrillaGlyph {
                glyph_id: GlyphId::new(glyph.id),
                text_range: extracted.ranges[i].clone(),
                x_advance: advance,
                x_offset: offset / size,
                y_offset: 0.0,
                y_advance: 0.0,
                location: None,
            }
        })
        .collect()
}

/// What a run's glyphs are read back as: one string, and the stretch
/// of it each glyph stands for.
struct Extracted<'a> {
    text: &'a str,
    ranges: Vec<std::ops::Range<usize>>,
}

/// The run as a reader gets it back. A run nothing transformed is
/// read back as it was shaped; one that was has what the author
/// wrote, and every glyph's range is taken through the run's map
/// into it.
fn extracted<'a>(
    text: &'a str,
    source: &'a str,
    source_map: &[u32],
    glyphs: &[Glyph],
) -> Extracted<'a> {
    let transformed = !source_map.is_empty();
    let read = if transformed { source } else { text };
    let through = |at: u32| match source_map.get(at as usize) {
        Some(offset) => *offset,
        None => read.len() as u32,
    };
    let ranges = glyphs
        .iter()
        .map(|glyph| {
            let range = if transformed {
                through(glyph.range.start)..through(glyph.range.end)
            } else {
                glyph.range.start..glyph.range.end
            };
            clamp_range(range, read)
        })
        .collect();
    Extracted { text: read, ranges }
}

/// A glyph's range, kept inside the string it indexes and on
/// character boundaries: krilla slices the text with it to build the
/// ToUnicode map, and a bad range there is a panic, not a wrong
/// glyph.
fn clamp_range(range: std::ops::Range<u32>, text: &str) -> std::ops::Range<usize> {
    let floor = |at: u32| {
        let mut at = (at as usize).min(text.len());
        while !text.is_char_boundary(at) {
            at -= 1;
        }
        at
    };
    let start = floor(range.start);
    start..floor(range.end).max(start)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::content::{Attributes, Block, Book, HeadingLevel, Inline, Section};
    use crate::fonts::{BUNDLED_FONT, Features, bundled_registry};
    use crate::pages::{Glyph, Side};

    /// The fixture map: a JPEG whose JFIF density is not 96dpi, so
    /// its intrinsic size is not its pixel count.
    const MAP: &[u8] = include_bytes!("../../../fixtures/images/plate.jpg");

    /// The fixture ornament: a PNG whose ground is transparent, and
    /// the same image as lossless WebP.
    const ORNAMENT: &[u8] = include_bytes!("../../../fixtures/images/fleuron.png");
    const ORNAMENT_WEBP: &[u8] = include_bytes!("../../../fixtures/images/fleuron.webp");

    fn registry() -> &'static FontRegistry {
        static REGISTRY: std::sync::OnceLock<FontRegistry> = std::sync::OnceLock::new();
        REGISTRY.get_or_init(|| bundled_registry().expect("bundled font parses"))
    }

    /// A book of one paragraph, with title metadata.
    fn book(text: &str) -> Book {
        let mut book = Book {
            metadata: Metadata {
                title: Some("Gulliver\'s Travels".into()),
                author: Some("Jonathan Swift".into()),
                extra: [("date".to_string(), "1726-10-28".to_string())]
                    .into_iter()
                    .collect(),
            },
            sections: vec![Section {
                attributes: Default::default(),
                blocks: vec![Block::Paragraph {
                    id: Default::default(),
                    inlines: vec![Inline::Text {
                        id: Default::default(),
                        value: text.into(),
                        attributes: Attributes::default(),
                        position: None,
                        span: None,
                    }],
                    attributes: Attributes::default(),
                    position: None,
                    span: None,
                }],
                ..Default::default()
            }],
        };
        book.assign_node_ids();
        book
    }

    /// A book that opens with a heading, for a sheet to colour.
    fn chapter() -> Book {
        let mut book = Book {
            metadata: Metadata::default(),
            sections: vec![Section {
                attributes: Default::default(),
                blocks: vec![
                    Block::Heading {
                        id: Default::default(),
                        level: HeadingLevel::H1,
                        inlines: vec![Inline::Text {
                            id: Default::default(),
                            value: "Chapter One".into(),
                            attributes: Attributes::default(),
                            position: None,
                            span: None,
                        }],
                        attributes: Attributes::default(),
                        position: None,
                        span: None,
                    },
                    Block::Paragraph {
                        id: Default::default(),
                        inlines: vec![Inline::Text {
                            id: Default::default(),
                            value: "The wind came off the water.".into(),
                            attributes: Attributes::default(),
                            position: None,
                            span: None,
                        }],
                        attributes: Attributes::default(),
                        position: None,
                        span: None,
                    },
                ],
                ..Default::default()
            }],
        };
        book.assign_node_ids();
        book
    }

    /// One hand-built page: the display structure a painter sees, without
    /// going through layout.
    fn page_of(items: Vec<DrawItem>, width: f32, height: f32) -> LayoutOutput {
        LayoutOutput {
            pages: vec![Page {
                number: 1,
                side: Side::Recto,
                width,
                height,
                sections: Vec::new(),
                items,
                links: Vec::new(),
            }],
            fonts: registry().font_ref(0).cloned().into_iter().collect(),
            assets: Vec::new(),
            warnings: Vec::new(),
            navigation: Default::default(),
        }
    }

    /// An asset table over files a host handed over by name.
    fn assets(files: &[(&str, &[u8])]) -> Assets {
        let mut assets = Assets::none();
        for (url, bytes) in files {
            assets.add(url, bytes.to_vec());
        }
        assets
    }

    /// PDF bytes as inspectable text: content streams uncompressed,
    /// bytes read as latin-1 so offsets survive.
    fn readable(output: &LayoutOutput, metadata: &Metadata) -> String {
        with_images(output, &Assets::none(), metadata)
    }

    /// The same, over images the host supplied.
    fn with_images(output: &LayoutOutput, assets: &Assets, metadata: &Metadata) -> String {
        latin1(&bytes_of(output, assets, metadata))
    }

    fn bytes_of(output: &LayoutOutput, assets: &Assets, metadata: &Metadata) -> Vec<u8> {
        write_with(
            output,
            registry(),
            assets,
            metadata,
            SerializeSettings {
                compress_content_streams: false,
                ..Default::default()
            },
        )
        .expect("the bundled face embeds")
    }

    fn latin1(bytes: &[u8]) -> String {
        bytes.iter().map(|b| *b as char).collect()
    }

    fn laid_out(book: &Book) -> LayoutOutput {
        let styles = crate::style::defaults(book, registry());
        crate::layout::layout_book(book, &styles, registry(), &Assets::none())
    }

    /// The page content streams, joined: where the operators are.
    /// The rest of a PDF is font and image bytes, and a byte pair
    /// inside a subset is not an operator.
    fn content(pdf: &str) -> String {
        // The split is on `\nstream\n` rather than `stream\n`, which
        // also matches the tail of `endstream` and takes the
        // terminator with it.
        let streams: Vec<&str> = pdf
            .split("\nstream\n")
            .skip(1)
            .filter_map(|rest| rest.split_once("\nendstream"))
            .map(|(body, _)| body)
            .filter(|body| body.is_ascii() && body.contains(" cm\n"))
            .collect();
        assert!(!streams.is_empty(), "no page content stream in:\n{pdf}");
        streams.join("\n")
    }

    /// The one glyph-positioning offset inside a showing op, in
    /// 1000ths of an em: `[(…) 100 (…)] TJ`.
    fn showing_offset(pdf: &str) -> Option<f32> {
        let show = &pdf[pdf.find("[(")?..pdf.find("] TJ")?];
        show.rsplit_once(") ")?.1.split_once(" (")?.0.parse().ok()
    }

    /// The page's trim size is the media box: krilla is told the size
    /// the display structure gives, not a default.
    #[test]
    fn page_trim_becomes_the_media_box() {
        let pdf = readable(&page_of(Vec::new(), 432.0, 648.0), &Metadata::default());
        assert!(
            pdf.contains("/MediaBox [0 0 432 648]"),
            "media box missing from:\n{pdf}"
        );
    }

    /// Glyphs show where layout put them. A run whose second glyph
    /// sits a hair off its font advance must come out as one showing
    /// op with that offset in it — 1000ths of an em, positive leftwards
    /// — not as two runs and not as font-advance spacing.
    #[test]
    fn glyphs_show_at_the_positions_layout_gave_them() {
        let d = registry().char_glyph(0, 'd').unwrap();
        let advance = registry().advance_width(0, d).unwrap() as f32 / 1000.0 * 10.0;
        let items = vec![DrawItem::Text {
            x: 0.0,
            y: 20.0,
            font_id: 0,
            size: 10.0,
            width: advance * 2.0 - 1.0,
            text: "dd".into(),
            source: String::new(),
            source_map: Vec::new(),
            origin: None,
            pseudo_element: None,
            features: Features::NONE,
            color: Color::BLACK,
            layer: 0,
            glyphs: vec![
                Glyph {
                    id: d,
                    x: 0.0,
                    range: 0..1,
                },
                Glyph {
                    id: d,
                    x: advance - 1.0,
                    range: 1..2,
                },
            ],
        }];
        let pdf = readable(&page_of(items, 200.0, 200.0), &Metadata::default());
        // 1pt tighter than the font advance, at 10pt: 100/1000 em,
        // positive because PDF offsets pull the next glyph leftwards.
        let offset = showing_offset(&pdf).expect("no showing offset in:\n{pdf}");
        assert!(
            (offset - 100.0).abs() < 0.01,
            "pair shows {offset}/1000 em tight, layout asked for 100"
        );
    }

    /// Acceptance: the writer paints a layered page in the order the
    /// list is in, which is the order the layers put it in. The
    /// preview painter walks the same list the same way, so the two
    /// agree on what covers what.
    #[test]
    fn a_layered_page_paints_in_the_order_the_list_is_in() {
        let under = Color::rgb(0, 51, 102);
        let over = Color::rgb(180, 30, 30);
        // What a lowered block and a raised one come out as: the
        // sort put the lower one first, and the writer keeps it
        // there.
        let items = vec![
            DrawItem::Rect {
                x: 0.0,
                y: 0.0,
                w: 100.0,
                h: 100.0,
                color: under,
                layer: -1,
            },
            DrawItem::Rect {
                x: 20.0,
                y: 20.0,
                w: 60.0,
                h: 60.0,
                color: over,
                layer: 10,
            },
        ];
        let painted = content(&readable(
            &page_of(items, 200.0, 200.0),
            &Metadata::default(),
        ));
        let lower = painted
            .find("0 0.2 0.4 rg")
            .expect("the lowered block filled with its own colour");
        let raised = painted
            .find("0.7058824 0.11764706 0.11764706 rg")
            .expect("the raised block filled with its own colour");
        assert!(
            lower < raised,
            "the writer painted the raised block first:\n{painted}"
        );
    }

    /// Rules paint as filled paths at the coordinates layout gave them.
    #[test]
    fn rect_items_paint_as_filled_paths() {
        let items = vec![DrawItem::Rect {
            x: 54.0,
            y: 100.0,
            w: 324.0,
            h: 0.5,
            color: Color::BLACK,
            layer: 0,
        }];
        let pdf = readable(&page_of(items, 432.0, 648.0), &Metadata::default());
        assert!(
            pdf.contains("54 100 m") && pdf.contains("378 100 l") && pdf.contains("\nf\n"),
            "rect did not paint as a filled path:\n{pdf}"
        );
    }

    /// Acceptance: the preview and the export agree about a rule
    /// across a run. Both painters read the rects the display
    /// structure holds and neither derives one of its own, so the
    /// test is that the export paints a filled path at the
    /// coordinates layout wrote.
    #[test]
    fn a_rule_across_a_run_paints_where_layout_put_it() {
        let book = chapter();
        let styles = crate::style::Stylesheets::parse(&[crate::style::Source::author(
            "decoration.css",
            "h1 { text-decoration: underline }",
        )])
        .compile(&book, registry());
        let output = crate::layout::layout_book(&book, &styles, registry(), &Assets::none());
        let rules: Vec<(f32, f32, f32, f32)> = output.pages[0]
            .items
            .iter()
            .filter_map(|item| match item {
                DrawItem::Rect { x, y, w, h, .. } => Some((*x, *y, *w, *h)),
                _ => None,
            })
            .collect();
        assert_eq!(rules.len(), 1, "the heading did not take one rule");
        let (x, y, w, h) = rules[0];
        let painted = content(&readable(&output, &Metadata::default()));
        let corners = [
            format!("{x} {y} m"),
            format!("{} {y} l", x + w),
            format!("{} {} l", x + w, y + h),
        ];
        for corner in &corners {
            assert!(
                painted.contains(corner),
                "the export did not paint `{corner}`:\n{painted}",
            );
        }
    }

    /// Colour reaches the page: a heading the sheet coloured fills
    /// with the colour its run carries, a rule fills with its own,
    /// and a page in black writes no colour at all.
    #[test]
    fn items_fill_with_the_colour_they_carry() {
        let book = chapter();
        let styles = crate::style::Stylesheets::parse(&[crate::style::Source::author(
            "colour.css",
            "h1 { color: #b41e1e }",
        )])
        .compile(&book, registry());
        let output = crate::layout::layout_book(&book, &styles, registry(), &Assets::none());
        let heading = output.pages[0]
            .items
            .iter()
            .find_map(|item| match item {
                DrawItem::Text { text, color, .. } if text.starts_with("Chapter") => Some(*color),
                _ => None,
            })
            .expect("the heading opens the first page");
        assert_eq!(heading, Color::rgb(180, 30, 30));
        let painted = content(&readable(&output, &Metadata::default()));
        // The channels the PDF writes, each over 255.
        let red = painted
            .find("0.7058824 0.11764706 0.11764706 rg")
            .unwrap_or_else(|| {
                panic!("the heading did not fill with the colour its run carries:\n{painted}")
            });
        // The fill is surface state, so the prose under the heading
        // has to set it back rather than inherit the red.
        assert!(
            painted[red..].contains("\n0 g\n"),
            "the heading's colour ran on into the prose under it:\n{painted}"
        );

        let rule = page_of(
            vec![DrawItem::Rect {
                x: 10.0,
                y: 40.0,
                w: 100.0,
                h: 0.5,
                color: Color::rgb(0, 51, 102),
                layer: 0,
            }],
            200.0,
            200.0,
        );
        let painted = content(&readable(&rule, &Metadata::default()));
        assert!(
            painted.contains("0 0.2 0.4 rg"),
            "the rule did not fill with the colour it carries:\n{painted}"
        );

        let black = content(&readable(&laid_out(&book), &Metadata::default()));
        assert!(
            !black.contains(" rg"),
            "a page in black wrote a colour of its own:\n{black}"
        );
    }

    /// Acceptance: text set in a colour with alpha paints at that
    /// alpha. The fill carries the colour, and a graphics state carries
    /// the alpha as its fill opacity.
    #[test]
    fn a_run_in_a_colour_with_alpha_fills_at_that_alpha() {
        let book = chapter();
        let styles = crate::style::Stylesheets::parse(&[crate::style::Source::author(
            "alpha.css",
            "h1 { color: rgba(180, 30, 30, 0.25) }",
        )])
        .compile(&book, registry());
        let output = crate::layout::layout_book(&book, &styles, registry(), &Assets::none());
        let pdf = readable(&output, &Metadata::default());
        assert!(
            pdf.contains("/ca 0.2509804"),
            "no fill opacity of a quarter in:\n{pdf}"
        );
        let painted = content(&pdf);
        let red = painted
            .find("0.7058824 0.11764706 0.11764706 rg")
            .unwrap_or_else(|| panic!("the heading lost its colour:\n{painted}"));
        assert!(
            painted[..red].contains(" gs\n") || painted[red..].contains(" gs\n"),
            "the fill opacity is never set on the page:\n{painted}"
        );
    }

    /// The face embeds as a subset: a tagged BaseFont, a FontFile2,
    /// and a stream far smaller than the face it came from.
    #[test]
    fn the_face_embeds_as_a_subset() {
        let pdf = readable(&laid_out(&book("difficult offices")), &Metadata::default());
        let tag = pdf
            .find("+EBGaramond-Regular")
            .expect("no subset-tagged BaseFont");
        assert!(
            pdf[tag - 6..tag].chars().all(|c| c.is_ascii_uppercase()),
            "BaseFont has no six-letter subset tag"
        );
        assert!(pdf.contains("/FontFile2"), "no embedded font program");
        assert!(
            pdf.len() < BUNDLED_FONT.len(),
            "the whole PDF ({} bytes) is no smaller than the full face ({} bytes)",
            pdf.len(),
            BUNDLED_FONT.len()
        );
    }

    /// A JPEG is embedded as it arrived: PDF's `DCTDecode` is the
    /// JPEG stream itself, so re-encoding one would cost quality for
    /// nothing.
    #[test]
    fn a_jpeg_embeds_the_bytes_it_arrived_as() {
        let items = vec![DrawItem::Image {
            x: 40.0,
            y: 60.0,
            w: 115.2,
            h: 76.8,
            asset: 0,
            alpha: 255,
            layer: 0,
        }];
        let table = assets(&[("plate.jpg", MAP)]);
        let bytes = bytes_of(&page_of(items, 432.0, 648.0), &table, &Metadata::default());
        let pdf = latin1(&bytes);
        assert!(pdf.contains("/DCTDecode"), "the map was re-encoded");
        assert!(
            bytes.windows(MAP.len()).any(|window| window == MAP),
            "the embedded stream is not the file that went in",
        );
    }

    /// The raster formats decode, and an alpha channel becomes the
    /// image's soft mask, which is what lets the paper, or a rule
    /// under it, show through.
    #[test]
    fn a_raster_image_with_alpha_embeds_a_soft_mask() {
        for (url, bytes) in [("fleuron.png", ORNAMENT), ("fleuron.webp", ORNAMENT_WEBP)] {
            let items = vec![
                DrawItem::Rect {
                    x: 0.0,
                    y: 0.0,
                    w: 432.0,
                    h: 648.0,
                    color: Color::BLACK,
                    layer: 0,
                },
                DrawItem::Image {
                    x: 200.0,
                    y: 300.0,
                    w: 30.72,
                    h: 30.72,
                    asset: 0,
                    alpha: 255,
                    layer: 0,
                },
            ];
            let table = assets(&[(url, bytes)]);
            let pdf = with_images(&page_of(items, 432.0, 648.0), &table, &Metadata::default());
            assert!(
                pdf.contains("/SMask"),
                "{url}: the ornament's transparency was flattened away",
            );
            assert!(
                pdf.contains("/ColorSpace /DeviceGray"),
                "{url}: no grayscale mask stream",
            );
            assert!(
                !pdf.contains("/DCTDecode"),
                "{url}: a raster image went in as a JPEG stream",
            );
        }
    }

    /// Four corners of one radius.
    fn round(radius: f32) -> Corners {
        let radius = crate::pages::Radius {
            x: radius,
            y: radius,
        };
        Corners {
            top_left: radius,
            top_right: radius,
            bottom_right: radius,
            bottom_left: radius,
        }
    }

    /// A rounded tint fills a path whose corners are curves, and a ring
    /// fills the band between two outlines by the even-odd rule.
    #[test]
    fn a_rounded_box_fills_a_curved_path() {
        let items = vec![
            DrawItem::Rounded {
                x: 20.0,
                y: 20.0,
                w: 100.0,
                h: 40.0,
                radii: round(3.0),
                ring: crate::style::Edges::all(0.0),
                color: Color::rgb(0xf4, 0xf1, 0xea),
                layer: 0,
            },
            DrawItem::Rounded {
                x: 20.0,
                y: 80.0,
                w: 100.0,
                h: 40.0,
                radii: round(6.0),
                ring: crate::style::Edges::all(2.0),
                color: Color::rgb(0, 51, 102),
                layer: 0,
            },
        ];
        let painted = content(&readable(
            &page_of(items, 200.0, 200.0),
            &Metadata::default(),
        ));
        let curves = painted.matches(" c\n").count();
        assert_eq!(
            curves, 12,
            "one curve per corner of three outlines:\n{painted}"
        );
        assert!(
            painted.contains("\nf*\n"),
            "the ring is not filled by the even-odd rule:\n{painted}"
        );
    }

    /// Acceptance: a rounded chip on a run draws its corners in the
    /// export, the way a rounded block does. The chip reaches the
    /// painter as one rounded box, so the curves come out of the same
    /// path builder the preview reads the same box through.
    #[test]
    fn a_rounded_chip_draws_its_corners() {
        let mut book = book("roll for the modifier");
        let Some(Block::Paragraph { inlines, .. }) = book.sections[0].blocks.first_mut() else {
            panic!("the fixture opens with a paragraph");
        };
        inlines.push(Inline::Code {
            id: Default::default(),
            value: "2d6".into(),
            attributes: Attributes::default(),
            position: None,
            span: None,
        });
        book.assign_node_ids();
        let styles = crate::style::Stylesheets::parse(&[crate::style::Source::author(
            "chip.css",
            "code { background-color: #858585; padding: 2pt 4pt; border-radius: 3pt }",
        )])
        .compile(&book, registry());
        let output = crate::layout::layout_book(&book, &styles, registry(), &Assets::none());
        let chip = output.pages[0]
            .items
            .iter()
            .filter(|item| matches!(item, DrawItem::Rounded { .. }))
            .count();
        assert_eq!(chip, 1, "the chip is not one rounded box");
        let painted = content(&readable(&output, &Metadata::default()));
        assert_eq!(
            painted.matches(" c\n").count(),
            4,
            "one curve per corner of the chip:\n{painted}",
        );
    }

    /// Acceptance: a rounded background image is clipped to the same
    /// curve as the tint under it.
    #[test]
    fn a_rounded_background_clips_to_a_curved_path() {
        let items = vec![DrawItem::Background {
            x: 40.0,
            y: 60.0,
            w: 120.0,
            h: 80.0,
            radii: round(3.0),
            tile_x: 40.0,
            tile_y: 60.0,
            tile_w: 120.0,
            tile_h: 80.0,
            repeat: false,
            asset: 0,
            alpha: 255,
            layer: 0,
        }];
        let table = assets(&[("plate.jpg", MAP)]);
        let painted = content(&with_images(
            &page_of(items, 432.0, 648.0),
            &table,
            &Metadata::default(),
        ));
        let clip = painted
            .find("\nW\n")
            .unwrap_or_else(|| panic!("the image is not clipped:\n{painted}"));
        assert_eq!(
            painted[..clip].matches(" c\n").count(),
            4,
            "the clip does not follow four curved corners:\n{painted}"
        );
    }

    /// Acceptance: a tint with an alpha over the image behind a page
    /// leaves the image showing through. The image is drawn first, and
    /// the tint over it fills at a quarter of full opacity.
    #[test]
    fn a_translucent_tint_over_a_page_image_fills_at_its_alpha() {
        let items = vec![
            DrawItem::Background {
                x: 0.0,
                y: 0.0,
                w: 432.0,
                h: 648.0,
                radii: Corners::SQUARE,
                tile_x: 0.0,
                tile_y: 0.0,
                tile_w: 432.0,
                tile_h: 648.0,
                repeat: false,
                asset: 0,
                alpha: 255,
                layer: DrawItem::PAGE_BACKGROUND,
            },
            DrawItem::Rect {
                x: 54.0,
                y: 100.0,
                w: 324.0,
                h: 120.0,
                color: Color::rgba(0, 0, 0, 64),
                layer: 0,
            },
        ];
        let table = assets(&[("plate.jpg", MAP)]);
        let pdf = with_images(&page_of(items, 432.0, 648.0), &table, &Metadata::default());
        assert!(
            pdf.contains("/ca 0.2509804"),
            "the tint fills opaque:\n{pdf}"
        );
        let painted = content(&pdf);
        let image = painted
            .find(" Do\n")
            .unwrap_or_else(|| panic!("the page image is not drawn:\n{painted}"));
        let tint = painted
            .find("0 0 0 rg")
            .unwrap_or_else(|| panic!("the tint is not filled:\n{painted}"));
        assert!(image < tint, "the tint is under the image:\n{painted}");
    }

    /// An image with an alpha draws under a graphics state that
    /// carries the alpha as its opacity, and an opaque one sets none.
    #[test]
    fn an_image_with_alpha_draws_at_that_alpha() {
        let image = |alpha| {
            vec![DrawItem::Image {
                x: 54.0,
                y: 90.0,
                w: 72.0,
                h: 48.0,
                asset: 0,
                alpha,
                layer: 0,
            }]
        };
        let table = assets(&[("plate.jpg", MAP)]);
        let faded = with_images(
            &page_of(image(128), 432.0, 648.0),
            &table,
            &Metadata::default(),
        );
        assert!(
            faded.contains("/ca 0.5019608") && faded.contains("/CA 0.5019608"),
            "no opacity of a half in:\n{faded}"
        );
        let opaque = with_images(
            &page_of(image(255), 432.0, 648.0),
            &table,
            &Metadata::default(),
        );
        assert!(!opaque.contains("/ca "), "an opaque image set an opacity");
    }

    /// Painters scale; they do not re-derive. An image layout sized
    /// down draws at the size layout gave it, not at the one its
    /// header declares.
    #[test]
    fn an_image_draws_at_the_size_layout_gave_it() {
        let items = vec![DrawItem::Image {
            x: 54.0,
            y: 90.0,
            w: 72.0,
            h: 48.0,
            asset: 0,
            alpha: 255,
            layer: 0,
        }];
        let table = assets(&[("plate.jpg", MAP)]);
        let (width, height) = table
            .lookup("plate.jpg")
            .expect("the map is an asset")
            .1
            .size();
        assert!(
            (width - 180.0).abs() < 0.01 && (height - 306.72).abs() < 0.01,
            "the header sizes the map at {width}x{height}pt",
        );
        let pdf = with_images(&page_of(items, 432.0, 648.0), &table, &Metadata::default());
        // krilla draws an image into the unit square, so the box is
        // the transform: the size layout asked for, and the corner it
        // asked for, measured up from the foot of the page.
        assert!(
            pdf.contains("72 0 0 48 54 510 cm"),
            "the image is not placed at 72x48pt at (54, 90):\n{pdf}",
        );
    }

    /// Acceptance: the preview and the export of a wrapped page
    /// agree.
    ///
    /// Both painters read the same display structure. The question is
    /// whether the export puts each item where that structure says.
    /// The image lands at the box its item carries. The line beside
    /// it starts at the x and the baseline its own item carries.
    #[test]
    fn a_wrapped_page_exports_where_the_display_structure_put_it() {
        let mut book = book(
            "My father had a small estate in Nottinghamshire, and I was the third of \
             five sons. He sent me to Emanuel College in Cambridge at fourteen years \
             old, where I resided three years and applied myself close to my studies.",
        );
        book.sections[0].blocks.insert(
            0,
            Block::Image {
                id: Default::default(),
                url: "plate.jpg".into(),
                alt: "a map of Lilliput".into(),
                attributes: Attributes::default(),
                position: None,
                span: None,
            },
        );
        book.assign_node_ids();
        let styles = crate::style::Stylesheets::parse(&[crate::style::Source::author(
            "anchored.css",
            "img { position: absolute; top: 0; left: 0; margin-right: 12pt; wrap-flow: end }",
        )])
        .compile(&book, registry());
        let table = assets(&[("plate.jpg", MAP)]);
        let output = crate::layout::layout_book(&book, &styles, registry(), &table);
        let page = &output.pages[0];

        let image = page
            .items
            .iter()
            .find_map(|item| match item {
                DrawItem::Image { x, y, w, h, .. } => Some((*x, *y, *w, *h)),
                _ => None,
            })
            .expect("the image is on the page");
        let (x, baseline) = page
            .items
            .iter()
            .find_map(|item| match item {
                DrawItem::Text { x, y, .. } if *x > image.0 + image.2 => Some((*x, *y)),
                _ => None,
            })
            .expect("a line is set beside the image");
        assert!(
            baseline > image.1 && baseline < image.1 + image.3,
            "the line at {baseline} is not beside the image at {image:?}",
        );

        let pdf = content(&with_images(&output, &table, &Metadata::default()));
        // krilla draws an image into the unit square, so the box is
        // the transform. It carries the size and the corner of the
        // item, measured up from the foot of the page.
        let box_ = format!(
            "{} 0 0 {} {} {} cm",
            image.2,
            image.3,
            image.0,
            page.height - image.1 - image.3,
        );
        assert!(
            pdf.contains(&box_),
            "the image is not placed at {box_}:\n{pdf}",
        );
        // krilla writes text under a flip, so the line sits at the x
        // and the baseline the item carries.
        let text = format!("1 0 0 -1 {x} {baseline} Tm");
        assert!(
            pdf.contains(&text),
            "the line beside the image is not set at {text}:\n{pdf}",
        );
    }

    /// Acceptance: the preview and the export of a page with a
    /// relative block and an absolute block on it agree.
    ///
    /// Both painters read the same display structure. The export must
    /// put the lines of both blocks at the x and the baseline that
    /// their items carry.
    #[test]
    fn a_page_of_positioned_blocks_exports_where_the_display_structure_put_them() {
        let text = |value: &str| Inline::Text {
            id: Default::default(),
            value: value.into(),
            attributes: Attributes::default(),
            position: None,
            span: None,
        };
        let mut book = book(
            "My father had a small estate in Nottinghamshire, and I was the third of \
             five sons. He sent me to Emanuel College in Cambridge at fourteen years old.",
        );
        let blocks = &mut book.sections[0].blocks;
        blocks.insert(
            0,
            Block::Heading {
                id: Default::default(),
                level: HeadingLevel::H1,
                inlines: vec![text("Raised")],
                attributes: Attributes::default(),
                position: None,
                span: None,
            },
        );
        blocks.push(Block::Blockquote {
            id: Default::default(),
            blocks: vec![Block::Paragraph {
                id: Default::default(),
                inlines: vec![text("Lifted against the page")],
                attributes: Attributes::default(),
                position: None,
                span: None,
            }],
            attributes: Attributes::default(),
            position: None,
            span: None,
        });
        book.assign_node_ids();
        let styles = crate::style::Stylesheets::parse(&[crate::style::Source::author(
            "positioned.css",
            "h1 { position: relative; top: -12pt } \
             blockquote { position: absolute; bottom: 1in; left: 0.5in; margin: 0 }",
        )])
        .compile(&book, registry());
        let output = crate::layout::layout_book(&book, &styles, registry(), &Assets::none());
        let page = &output.pages[0];

        let pdf = content(&readable(&output, &Metadata::default()));
        for word in ["Raised", "Lifted"] {
            let (x, baseline) = page
                .items
                .iter()
                .find_map(|item| match item {
                    DrawItem::Text { x, y, text, .. } if text.contains(word) => Some((*x, *y)),
                    _ => None,
                })
                .unwrap_or_else(|| panic!("no run of {word} on the page"));
            // krilla writes text under a flip, so the line sits at the
            // x and the baseline the item carries.
            let placed = format!("1 0 0 -1 {x} {baseline} Tm");
            assert!(
                pdf.contains(&placed),
                "{word} is not set at {placed}:\n{pdf}",
            );
        }
    }

    /// An image nothing supplied is no draw item, and one warning
    /// names the url.
    #[test]
    fn an_image_no_host_supplied_is_reported_and_skipped() {
        let mut book = Book {
            sections: vec![Section {
                attributes: Default::default(),
                blocks: vec![Block::Image {
                    id: Default::default(),
                    url: "missing.png".into(),
                    alt: "a map".into(),
                    attributes: Attributes::default(),
                    position: None,
                    span: None,
                }],
                ..Default::default()
            }],
            ..Default::default()
        };
        book.assign_node_ids();
        let output = laid_out(&book);
        assert!(
            !output.pages.iter().any(|page| page
                .items
                .iter()
                .any(|item| matches!(item, DrawItem::Image { .. }))),
            "an image with no bytes was placed anyway",
        );
        assert_eq!(output.warnings.len(), 1, "{:?}", output.warnings);
        assert!(output.warnings[0].message.contains("missing.png"));
    }

    /// Book metadata reaches the document information dictionary.
    #[test]
    fn metadata_carries_the_book_title() {
        let book = book("Some prose.");
        let pdf = readable(&laid_out(&book), &book.metadata);
        assert!(pdf.contains("/Title (Gulliver's Travels)"), "no title");
        assert!(pdf.contains("/Author (Jonathan Swift)"), "no author");
        assert!(pdf.contains("/Producer (fleuron)"), "no producer");
        assert!(
            pdf.contains("/CreationDate (D:17261028"),
            "the book's own date is not the creation date:\n{pdf}",
        );
    }

    /// A date the book does not write is no creation date, rather
    /// than the hour the run happened to start: the engine reads no
    /// clock, and two runs over one book are one file.
    #[test]
    fn a_book_with_no_date_is_stamped_with_none() {
        let mut book = book("Some prose.");
        book.metadata.extra.remove("date");
        let pdf = readable(&laid_out(&book), &book.metadata);
        assert!(!pdf.contains("/CreationDate"), "a clock was read");
    }

    /// Text is selectable because every glyph maps back to the
    /// characters it was shaped from: the ffi ligature is one glyph
    /// and three code points in the ToUnicode map.
    #[test]
    fn glyphs_map_back_to_their_characters() {
        let pdf = readable(&laid_out(&book("difficult offices")), &Metadata::default());
        assert!(pdf.contains("/ToUnicode"), "no ToUnicode map");
        assert!(
            pdf.contains("<006600660069>"),
            "the ffi ligature does not map back to f, f, i:\n{pdf}"
        );
    }

    /// A transformed run is drawn in the letters the transform asked
    /// for and read back in the ones the author wrote: the glyphs are
    /// the capitals, and the ToUnicode map sends them to the source.
    #[test]
    fn a_transformed_run_extracts_as_it_was_written() {
        let book = book("Some prose.");
        let styles = crate::style::Stylesheets::parse(&[crate::style::Source::author(
            "author.css",
            "p { text-transform: uppercase }",
        )])
        .compile(&book, registry());
        let output = crate::layout::layout_book(&book, &styles, registry(), &Assets::none());
        let (text, source) = output
            .pages
            .iter()
            .flat_map(|page| &page.items)
            .find_map(|item| match item {
                DrawItem::Text { text, source, .. } => Some((text.clone(), source.clone())),
                _ => None,
            })
            .expect("the book set a line");
        assert_eq!(
            (text.as_str(), source.as_str()),
            ("SOME PROSE.", "Some prose.")
        );

        let pdf = readable(&output, &Metadata::default());
        // The drawn capitals map back to what was written: an `O`
        // that stands for an `o` is the whole of the difference.
        assert!(
            pdf.contains("<006F>"),
            "the ToUnicode map does not send the capitals to the source:\n{pdf}",
        );
    }

    /// A first line transformed is drawn in the letters the transform
    /// asked for and read back in the ones the author wrote, and the
    /// rest of the paragraph is untouched.
    #[test]
    fn a_transformed_first_line_extracts_as_it_was_written() {
        let book = book(&"my father had a small estate in nottinghamshire ".repeat(6));
        let styles = crate::style::Stylesheets::parse(&[crate::style::Source::author(
            "author.css",
            "p::first-line { text-transform: uppercase }",
        )])
        .compile(&book, registry());
        let output = crate::layout::layout_book(&book, &styles, registry(), &Assets::none());
        let drawn: Vec<(String, String)> = output
            .pages
            .iter()
            .flat_map(|page| &page.items)
            .filter_map(|item| match item {
                DrawItem::Text { text, source, .. } => Some((text.clone(), source.clone())),
                _ => None,
            })
            .collect();
        let (opening, written) = drawn.first().expect("the book set a line");
        assert_eq!(opening, &opening.to_uppercase());
        assert_eq!(written, &written.to_lowercase());
        assert_eq!(opening, &written.to_uppercase());
        assert!(
            drawn[1..]
                .iter()
                .all(|(text, source)| text == &text.to_lowercase() && source.is_empty()),
            "the transform ran past the first line",
        );

        let pdf = readable(&output, &Metadata::default());
        assert!(
            pdf.contains("<006D>"),
            "the ToUnicode map does not send the capitals to the source:\n{pdf}",
        );
    }

    /// The file is structurally whole — header, page tree, cross
    /// reference, trailer — which is what `qpdf --check` reads.
    #[test]
    fn the_document_is_structurally_whole() {
        let book = book("Some prose.");
        let output = laid_out(&book);
        let pdf = readable(&output, &book.metadata);
        assert!(pdf.starts_with("%PDF-1.7"), "no PDF header");
        assert!(
            pdf.contains(&format!("/Type /Pages\n  /Count {}", output.pages.len())),
            "page tree does not count the display structure's pages"
        );
        assert!(pdf.contains("startxref"), "no cross-reference offset");
        assert!(pdf.trim_end().ends_with("%%EOF"), "no trailer");
    }

    /// Two runs over one book produce byte-identical PDFs: nothing in
    /// the writer reads a clock or a hash of an address.
    #[test]
    fn writing_is_deterministic() {
        let book = book("Some prose, twice over.");
        let output = laid_out(&book);
        let table = assets(&[("plate.jpg", MAP)]);
        let first = write(&output, registry(), &table, &book.metadata).unwrap();
        let second = write(&output, registry(), &table, &book.metadata).unwrap();
        assert_eq!(first, second);
    }
}