mos_pdf/

lib.rs

//! PDF backend for Mosaic (manifest §21.1).
//!
//! Emits a fixed-A4 PDF declaring all 14 standard PDF base fonts
//! (Helvetica/Times/Courier × 4 + Symbol + `ZapfDingbats`). No font
//! data ships; every glyph outline is supplied by the PDF reader's
//! built-in Core 14 implementations.
//!
//! For each Latin Core 14 face actually used, the backend plans a
//! per-document `/Encoding` dict that layers a `/Differences` array
//! on top of `WinAnsiEncoding` to reach the 99 extended glyphs each
//! AFM carries beyond `WinAnsi` (`Ł`, `ł`, `Ě`, `ě`, `Ő`, `ő`, the
//! Romanian comma-below set, math operators `−≤≥≠√∂∑∆◊`, `fi`/`fl`).
//! A matching `/ToUnicode` `CMap` is emitted so the bytes we mint
//! decode back to real Unicode in copy/paste and search.
//!
//! See the private `encoding` module for the planner. PDF/A, tagged
//! PDF, hyperlinks, bookmarks, and full font embedding (issue #9)
//! are deferred.

#![doc(
    html_logo_url = "https://mosaiclang.dev/assets/A4.svg",
    html_favicon_url = "https://mosaiclang.dev/assets/A4.svg"
)]

#[doc(hidden)]
pub mod content;
mod debug;
#[doc(hidden)]
pub mod embedded;
#[doc(hidden)]
pub mod encoding;
#[doc(hidden)]
pub mod images;

use std::collections::HashMap;
use std::path::Path;

use mos_core::{CoreError, Diagnostic, Result, codes};
use mos_fonts::EmbeddedFontId;
use mos_layout::{Base14Font, Font, PageGraph, TextRun};
use pdf_writer::types::{SystemInfo, UnicodeCmap};
use pdf_writer::writers::Encoding;
use pdf_writer::{Finish, Name, Pdf, Rect, Ref, Str, TextStr};

use crate::embedded::{EmbeddedFontPlan, EmbeddedRefs};
use crate::encoding::{DocEncoding, EncodingPlanner};

/// Identifies Mosaic as the PDF's producing application, written to the
/// Info dictionary `/Producer` and `/Creator` so a built PDF traces back
/// to the compiler that bred it (the way ffmpeg/Word/Adobe stamp theirs).
/// A compile-time constant, so output stays byte-for-byte deterministic:
/// no wall-clock, host, path, or user data leaks in. The version tracks
/// the workspace `CARGO_PKG_VERSION` automatically.
///
/// Follow-up (intentionally deferred to keep this stamp deterministic):
/// - `/CreationDate` + `/ModDate` driven by a `SOURCE_DATE_EPOCH`-style
///   deterministic input (UTC, stable `D:YYYYMMDDHHmmSS'+00'00'` format).
/// - An XMP metadata packet (catalog `/Metadata`) for PDF/A / Adobe tooling,
///   kept in sync with this Info dict.
const PRODUCER: &str = concat!("Mosaic ", env!("CARGO_PKG_VERSION"));

/// Document-level metadata written to the PDF Info dictionary.
///
/// Populated by the lowerer from `#set document(...)`. `language` is captured
/// but not yet emitted; it belongs in the catalog `/Lang` entry.
///
/// # Examples
///
/// ```
/// use mos_pdf::PdfMetadata;
///
/// let metadata = PdfMetadata {
///     title: Some("Demo".to_owned()),
///     author: Some("Mosaic".to_owned()),
///     language: Some("en".to_owned()),
/// };
///
/// assert_eq!(metadata.title.as_deref(), Some("Demo"));
/// ```
#[derive(Debug, Clone, Default)]
pub struct PdfMetadata {
    pub title: Option<String>,
    pub author: Option<String>,
    pub language: Option<String>,
}

/// Emit `graph` as a PDF file at `out`. Creates `out`'s parent
/// directory if it doesn't already exist.
///
/// Returns any diagnostics raised during PDF emission; currently
/// only `MOS0032` (per-font extended-glyph budget exhausted). Layout
/// diagnostics flow through [`mos_layout::LayoutResult::diagnostics`]
/// separately; callers (the CLI) typically render both.
///
/// # Errors
///
/// Returns a wrapped [`Diagnostic`] if writing the file (or creating
/// its parent directory) fails.
///
/// # Examples
///
/// ```no_run
/// use std::path::Path;
///
/// use mos_layout::PageGraph;
/// use mos_pdf::PdfMetadata;
///
/// let graph = PageGraph::default();
/// let metadata = PdfMetadata::default();
/// let diagnostics = mos_pdf::emit(&graph, &metadata, Path::new("build/main.pdf"))?;
///
/// assert!(diagnostics.is_empty());
/// # Ok::<(), mos_core::CoreError>(())
/// ```
pub fn emit(graph: &PageGraph, metadata: &PdfMetadata, out: &Path) -> Result<Vec<Diagnostic>> {
    let (bytes, diagnostics) = build_pdf(graph, metadata)?;
    write_pdf(&bytes, out)?;
    Ok(diagnostics)
}

/// Emit a PDF with visible layout geometry from the graph's matching report.
///
/// Each page retains its original content and coordinates. A 36-point strip
/// above the original page holds the legend, outside the document's bounds.
/// The debug canvas is at least 420 points wide to keep the legend legible.
/// Use the graph and report from the same `LayoutEngine::layout_with_debug`
/// result. The ordinary [`emit`] output is unaffected.
///
/// # Errors
///
/// Returns `MOS0051` for mismatched page geometry, or the same font and I/O
/// errors as [`emit`].
pub fn emit_debug(
    graph: &PageGraph,
    report: &mos_layout::debug::Report,
    metadata: &PdfMetadata,
    out: &Path,
) -> Result<Vec<Diagnostic>> {
    debug::validate(graph, report)?;
    let (bytes, diagnostics) = build_pdf_impl(graph, metadata, Some(report))?;
    write_pdf(&bytes, out)?;
    Ok(diagnostics)
}

fn write_pdf(bytes: &[u8], out: &Path) -> Result<()> {
    if let Some(parent) = out.parent()
        && !parent.as_os_str().is_empty()
    {
        std::fs::create_dir_all(parent).map_err(|err| {
            io_diagnostic(format!(
                "could not create output directory `{}`: {err}",
                mos_core::display_path(parent)
            ))
        })?;
    }
    std::fs::write(out, bytes).map_err(|err| {
        io_diagnostic(format!(
            "could not write PDF to `{}`: {err}",
            mos_core::display_path(out)
        ))
    })?;
    Ok(())
}

fn io_diagnostic(message: String) -> CoreError {
    CoreError::Diagnostic(Box::new(Diagnostic::simple(&codes::MOS0014, None, message)))
}

/// Build the PDF bytes from `graph`. Pulled out of [`emit`] so tests
/// can round-trip without touching the filesystem. Returns the bytes
/// plus any encoding diagnostics (currently `MOS0032` for Base14
/// `/Differences` overflow). Kept `pub(crate)`; the public surface
/// includes [`emit`] and [`emit_debug`].
///
/// # Errors
///
/// Returns an error if font subsetting fails for any embedded face
/// (only with corrupted font data; the bundled cuts have been
/// verified).
pub(crate) fn build_pdf(
    graph: &PageGraph,
    metadata: &PdfMetadata,
) -> Result<(Vec<u8>, Vec<Diagnostic>)> {
    build_pdf_impl(graph, metadata, None)
}

fn build_pdf_impl(
    graph: &PageGraph,
    metadata: &PdfMetadata,
    debug: Option<&mos_layout::debug::Report>,
) -> Result<(Vec<u8>, Vec<Diagnostic>)> {
    // Phase 1a: scan every run and plan per-face Base14 /Differences
    // encodings (embedded-font runs are skipped: they take the Type 0
    // CID path below).
    let mut diagnostics: Vec<Diagnostic> = Vec::new();
    let encodings = plan_base14_encodings(graph, &mut diagnostics);

    // Phase 1b: subset every embedded face actually used. One plan
    // per face referenced; absent if the face never appears in `runs`.
    // Only embedded-font runs need cloning into the flat slice the
    // planner consumes: Base14 runs would be filtered out by
    // `plan_embedded` anyway, so cloning them up front is pure waste
    // for documents where Base14 dominates.
    let embedded_runs: Vec<TextRun> = graph
        .pages
        .iter()
        .flat_map(|p| p.runs.iter())
        .filter(|r| matches!(r.font, Font::Embedded(_)))
        .cloned()
        .collect();
    let embedded_plans: Vec<EmbeddedFontPlan> = embedded::plan_embedded(&embedded_runs)?;
    let embedded_by_id: HashMap<EmbeddedFontId, &EmbeddedFontPlan> =
        embedded_plans.iter().map(|p| (p.id, p)).collect();

    // Phase 2: emit. Refs allocated up front so the page tree, font
    // dicts, encoding dicts, FontFile2 streams, and ToUnicode streams
    // can cross-reference.
    let mut pdf = Pdf::new();
    let mut next_id: i32 = 1;
    let mut alloc = || {
        let id = Ref::new(next_id);
        next_id += 1;
        id
    };

    let catalog_id = alloc();
    let page_tree_id = alloc();
    let info_id = alloc();

    // One indirect ref per Base14 face, in the order published by
    // `Font::ALL_BASE14`. Always all 14 entries so every page's
    // resource dictionary is identical for Base14: preserves byte
    // stability for Base14-only documents.
    let base14_refs: Vec<(Font, Ref)> = Font::ALL_BASE14.iter().map(|f| (*f, alloc())).collect();

    // For each Latin face that needs a `/Differences` map, pre-allocate
    // the indirect refs for the custom encoding dict and the
    // `/ToUnicode` CMap stream. Symbol/Dingbats and unused faces get
    // no extra refs. Iterate `Font::ALL_BASE14` (not `&encodings`) so the
    // `alloc()` order, and therefore the byte layout of the produced
    // PDF is deterministic across runs.
    let mut encoding_refs: HashMap<Font, (Ref, Ref)> = HashMap::new();
    for font in Font::ALL_BASE14 {
        if let Some(enc) = encodings.get(&font)
            && enc.has_differences()
        {
            let enc_ref = alloc();
            let cmap_ref = alloc();
            encoding_refs.insert(font, (enc_ref, cmap_ref));
        }
    }

    // One set of 5 refs per embedded face actually referenced.
    let embedded_refs: HashMap<EmbeddedFontId, EmbeddedRefs> = embedded_plans
        .iter()
        .map(|plan| {
            (
                plan.id,
                EmbeddedRefs {
                    font: alloc(),
                    cid_font: alloc(),
                    descriptor: alloc(),
                    font_file: alloc(),
                    to_unicode: alloc(),
                },
            )
        })
        .collect();

    // Allocate one indirect ref per unique image. Compression itself
    // happens at emit time (see the loop below) so we don't hold every
    // compressed stream in memory simultaneously: `graph.images` is
    // already the deduped set, and an image-heavy document can blow
    // peak RAM if we buffer all compressed copies before writing them.
    let image_refs: Vec<Ref> = graph.images.iter().map(|_| alloc()).collect();

    let page_refs: Vec<(Ref, Ref)> = graph.pages.iter().map(|_| (alloc(), alloc())).collect();

    // Outline (bookmark) refs follow the document's page/font/image
    // objects, so a heading-free document — where `outline` is empty and
    // this is `None` — produces byte-identical output to before outlines
    // existed. Allocation walks `graph.outline` in document order, so the
    // root and per-entry ids are deterministic across runs.
    let outline_refs: Option<(Ref, Vec<Ref>)> = (!graph.outline.is_empty()).then(|| {
        let root = alloc();
        let items: Vec<Ref> = graph.outline.iter().map(|_| alloc()).collect();
        (root, items)
    });
    // Independent WinAnsi font: document /Differences may reuse ASCII slots
    // that the legend needs. Allocate only for debug output.
    let debug_font_ref = debug.map(|_| alloc());
    if let Some(font_ref) = debug_font_ref {
        pdf.type1_font(font_ref)
            .base_font(Name(b"Helvetica"))
            .encoding_predefined(Name(b"WinAnsiEncoding"));
    }

    {
        let mut catalog = pdf.catalog(catalog_id);
        catalog.pages(page_tree_id);
        if let Some((root, _)) = &outline_refs {
            catalog.outlines(*root);
        }
    }

    let page_count = i32::try_from(page_refs.len()).unwrap_or(i32::MAX);
    pdf.pages(page_tree_id)
        .kids(page_refs.iter().map(|(p, _)| *p))
        .count(page_count);

    emit_pages(
        &mut pdf,
        graph,
        &PageEmitContext {
            page_tree_id,
            page_refs: &page_refs,
            base14_refs: &base14_refs,
            embedded_refs: &embedded_refs,
            image_refs: &image_refs,
            encodings: &encodings,
            embedded_by_id: &embedded_by_id,
            debug,
            debug_font_ref,
        },
    )?;

    // Emit each Image XObject. Order matches `graph.images` (and
    // therefore the `alloc()` order above), keeping byte output
    // deterministic. Each image is compressed in this loop and the
    // compressed buffer dropped at the end of the iteration, so peak
    // memory holds at most one compressed image at a time on top of
    // the (Arc-shared) decoded pixel buffer the handle already owns.
    emit_images(&mut pdf, graph, &image_refs);

    emit_base14_fonts(&mut pdf, &base14_refs, &encoding_refs);

    // Emit each embedded face's 5-object cluster (Type 0 + CIDFont +
    // descriptor + FontFile2 stream + ToUnicode CMap).
    for plan in &embedded_plans {
        let refs = embedded_refs[&plan.id];
        embedded::emit_embedded(&mut pdf, plan, refs);
    }

    // Emit the custom /Encoding dicts and /ToUnicode CMap streams.
    // Same `Font::ALL_BASE14` walk as the allocation pass above keeps
    // emit order deterministic.
    for font in Font::ALL_BASE14 {
        let Some(enc) = encodings.get(&font) else {
            continue;
        };
        let Some(&(enc_ref, cmap_ref)) = encoding_refs.get(&font) else {
            continue;
        };
        emit_encoding_dict(&mut pdf, enc_ref, enc);
        emit_to_unicode_cmap(&mut pdf, cmap_ref, enc);
    }

    {
        let mut info = pdf.document_info(info_id);
        if let Some(title) = metadata.title.as_deref() {
            info.title(TextStr(title));
        }
        if let Some(author) = metadata.author.as_deref() {
            info.author(TextStr(author));
        }
        // Provenance stamp: mark Mosaic as the producing application. Both
        // keys carry the same constant string, so this adds no wall-clock
        // or environment data and the output stays deterministic.
        info.producer(TextStr(PRODUCER));
        info.creator(TextStr(PRODUCER));
        info.finish();
    }

    if let Some((root, items)) = &outline_refs {
        emit_outline(&mut pdf, graph, *root, items, &page_refs);
    }

    Ok((pdf.finish(), diagnostics))
}

/// Emit the `/Outlines` tree from `graph.outline` (flat, document order,
/// each entry carrying a heading `level` 1..=3). Nesting is reconstructed
/// in a single pass over a level stack of entry indices, then the root
/// dict and one `/Outline` item per entry are wired with
/// parent/prev/next/first/last links and page destinations.
///
/// `items[i]` is the indirect ref for `graph.outline[i]`; `root` is the
/// `/Outlines` dict ref. Called only when `graph.outline` is non-empty,
/// so `items` is non-empty and `roots` always has at least one member.
fn emit_outline(
    pdf: &mut Pdf,
    graph: &PageGraph,
    root: Ref,
    items: &[Ref],
    page_refs: &[(Ref, Ref)],
) {
    let entries = &graph.outline;
    let n = entries.len();

    // Pass 1: reconstruct parent / children / top-level roots from a
    // level stack. Popping every entry whose level is >= the current
    // one makes a skipped level (H1→H3) attach under the nearest
    // shallower ancestor, and a later shallower heading re-parent
    // correctly. Document order is preserved, so child and sibling
    // order match the source.
    let mut parent: Vec<Option<usize>> = vec![None; n];
    let mut children: Vec<Vec<usize>> = vec![Vec::new(); n];
    let mut roots: Vec<usize> = Vec::new();
    let mut stack: Vec<usize> = Vec::new();
    for (i, entry) in entries.iter().enumerate() {
        while stack
            .last()
            .is_some_and(|&top| entries[top].level >= entry.level)
        {
            stack.pop();
        }
        match stack.last() {
            Some(&p) => {
                parent[i] = Some(p);
                children[p].push(i);
            }
            None => roots.push(i),
        }
        stack.push(i);
    }

    // Pass 2: subtree sizes (descendants excluding self) for /Count. A
    // child always has a higher index than its parent (document order +
    // the stack discipline), so a reverse walk visits every child before
    // its parent.
    let mut descendants: Vec<usize> = vec![0; n];
    for i in (0..n).rev() {
        if let Some(p) = parent[i] {
            descendants[p] += descendants[i] + 1;
        }
    }

    // Root /Outlines dict: first/last top-level items plus the full
    // entry total (positive → every item open, since none are collapsed).
    {
        let mut outline = pdf.outline(root);
        if let (Some(&first), Some(&last)) = (roots.first(), roots.last()) {
            outline.first(items[first]);
            outline.last(items[last]);
        }
        outline.count(i32::try_from(n).unwrap_or(i32::MAX));
    }

    for (i, entry) in entries.iter().enumerate() {
        let mut item = pdf.outline_item(items[i]);
        item.title(TextStr(&entry.title));
        item.parent(match parent[i] {
            Some(p) => items[p],
            None => root,
        });

        // Prev/next siblings within the parent's child list (or the root
        // list for top-level entries).
        let siblings: &[usize] = match parent[i] {
            Some(p) => &children[p],
            None => &roots,
        };
        if let Some(pos) = siblings.iter().position(|&s| s == i) {
            if pos > 0 {
                item.prev(items[siblings[pos - 1]]);
            }
            if pos + 1 < siblings.len() {
                item.next(items[siblings[pos + 1]]);
            }
        }

        // Children first/last + subtree count (positive → open).
        if let (Some(&first), Some(&last)) = (children[i].first(), children[i].last()) {
            item.first(items[first]);
            item.last(items[last]);
            item.count(i32::try_from(descendants[i]).unwrap_or(i32::MAX));
        }

        // Destination: land on the heading's page with the top coord
        // flipped to bottom-origin (same convention as text runs). Bounds
        // are guaranteed by construction; the `.get` guards skip a
        // malformed index rather than panicking.
        if let Some((page_ref, _)) = page_refs.get(entry.page_index)
            && let Some(page) = graph.pages.get(entry.page_index)
        {
            let top = page.height_pt - entry.top_from_top_pt;
            item.dest().page(*page_ref).xyz(0.0, top, None);
        }
    }
}

struct PageEmitContext<'a> {
    page_tree_id: Ref,
    page_refs: &'a [(Ref, Ref)],
    base14_refs: &'a [(Font, Ref)],
    embedded_refs: &'a HashMap<EmbeddedFontId, EmbeddedRefs>,
    image_refs: &'a [Ref],
    encodings: &'a HashMap<Font, DocEncoding>,
    embedded_by_id: &'a HashMap<EmbeddedFontId, &'a EmbeddedFontPlan>,
    debug: Option<&'a mos_layout::debug::Report>,
    debug_font_ref: Option<Ref>,
}

fn plan_base14_encodings(
    graph: &PageGraph,
    diagnostics: &mut Vec<Diagnostic>,
) -> HashMap<Font, DocEncoding> {
    let mut planner = EncodingPlanner::new();
    for page in &graph.pages {
        planner.observe_runs(&page.runs);
    }
    planner.finalize(diagnostics)
}

fn emit_pages(pdf: &mut Pdf, graph: &PageGraph, ctx: &PageEmitContext<'_>) -> Result<()> {
    for (index, (page, (page_id, content_id))) in
        graph.pages.iter().zip(ctx.page_refs.iter()).enumerate()
    {
        let debug_page = ctx.debug.map(|report| &report.pages[index]);
        let extra_height = if debug_page.is_some() {
            debug::LEGEND_HEIGHT_PT
        } else {
            0.0
        };
        let width = if debug_page.is_some() {
            debug::canvas_width(page.width_pt)
        } else {
            page.width_pt
        };
        let mut page_obj = pdf.page(*page_id);
        page_obj.media_box(Rect::new(0.0, 0.0, width, page.height_pt + extra_height));
        page_obj.parent(ctx.page_tree_id);
        page_obj.contents(*content_id);
        {
            let mut resources = page_obj.resources();
            {
                let mut fonts = resources.fonts();
                for (face, font_id) in ctx.base14_refs {
                    fonts.pair(Name(face.pdf_resource_name()), *font_id);
                }
                if let Some(font_ref) = ctx.debug_font_ref {
                    fonts.pair(debug::FONT_NAME, font_ref);
                }
                for id in EmbeddedFontId::ALL {
                    if let Some(refs) = ctx.embedded_refs.get(&id) {
                        fonts.pair(Name(id.pdf_resource_name()), refs.font);
                    }
                }
            }
            if !graph.images.is_empty() {
                let mut x_objects = resources.x_objects();
                for (handle, image_id) in graph.images.iter().zip(ctx.image_refs.iter()) {
                    let name = images::resource_name(handle);
                    x_objects.pair(Name(name.as_bytes()), *image_id);
                }
            }
        }
        page_obj.finish();

        let mut stream_bytes =
            content::build_content_stream(page.height_pt, page, ctx.encodings, ctx.embedded_by_id)?;
        if let Some(debug_page) = debug_page {
            // Isolate both streams: text state (e.g. character spacing) and
            // drawing state from the document must not affect the legend.
            stream_bytes.splice(..0, b"q\n".iter().copied());
            stream_bytes.extend_from_slice(b"\nQ\n");
            stream_bytes.extend_from_slice(&debug::overlay(debug_page));
        }
        pdf.stream(*content_id, &stream_bytes);
    }
    Ok(())
}

fn emit_base14_fonts(
    pdf: &mut Pdf,
    base14_refs: &[(Font, Ref)],
    encoding_refs: &HashMap<Font, (Ref, Ref)>,
) {
    for (face, font_id) in base14_refs {
        let Some(base14) = face.base14() else {
            continue;
        };
        let mut font_dict = pdf.type1_font(*font_id);
        font_dict.base_font(Name(face.pdf_base_name().as_bytes()));
        if matches!(base14, Base14Font::Symbol | Base14Font::ZapfDingbats) {
            continue;
        }
        match encoding_refs.get(face) {
            Some(&(enc_ref, cmap_ref)) => {
                font_dict.pair(Name(b"Encoding"), enc_ref);
                font_dict.to_unicode(cmap_ref);
            }
            None => {
                font_dict.encoding_predefined(Name(b"WinAnsiEncoding"));
            }
        }
    }
}

fn emit_images(pdf: &mut Pdf, graph: &PageGraph, image_refs: &[Ref]) {
    for (handle, id) in graph.images.iter().zip(image_refs.iter()) {
        let compressed = images::flate_compress(&handle.rgb8);
        images::emit_image_xobject(pdf, *id, handle, &compressed);
    }
}

/// Emits one PDF indirect object: a custom `/Encoding` dict with
/// `/BaseEncoding /WinAnsiEncoding` and a `/Differences` array.
/// `pdf-writer`'s `Differences::consecutive(start, names)` emits the
/// run-length form `[ start /n1 /n2 /n3 ]`. We use one group per
/// contiguous run for compactness; isolated slots get their own
/// single-element group.
fn emit_encoding_dict(pdf: &mut Pdf, id: Ref, enc: &DocEncoding) {
    let mut enc_dict: Encoding<'_> = pdf.indirect(id).start();
    enc_dict.base_encoding(Name(b"WinAnsiEncoding"));
    {
        let mut diffs = enc_dict.differences();
        let mut i = 0;
        while i < enc.differences.len() {
            let (start, _) = enc.differences[i];
            // Find the end of this contiguous run (slot[j] == slot[j-1] + 1).
            let mut j = i + 1;
            while j < enc.differences.len() && enc.differences[j].0 == enc.differences[j - 1].0 + 1
            {
                j += 1;
            }
            let names = enc.differences[i..j]
                .iter()
                .map(|(_, n)| Name(n.as_bytes()));
            diffs.consecutive(start, names);
            i = j;
        }
    }
    enc_dict.finish();
}

/// Emits a `/ToUnicode` `CMap` stream that round-trips every byte
/// used by `enc` back to its original Unicode codepoint, so
/// copy-paste and full-text search work for both `WinAnsi` natives
/// and `/Differences`-remapped slots.
fn emit_to_unicode_cmap(pdf: &mut Pdf, id: Ref, enc: &DocEncoding) {
    // The `SystemInfo` here is embedded inside the PostScript-y CMap
    // stream content (the `%%BeginResource: CMap …` header that
    // `UnicodeCmap::new` writes). The `/CMapName` and `/CIDSystemInfo`
    // entries set further down go on the stream dictionary itself.
    // both are required by PDF 1.7 §9.7.5.4 / §9.10.3 (pdf-writer
    // documents `.name()` and `.system_info()` as "Required"), even
    // though readers we've tested tolerate their absence because the
    // PS content carries the same info.
    let system_info = SystemInfo {
        registry: Str(b"Adobe"),
        ordering: Str(b"UCS"),
        supplement: 0,
    };
    let mut cmap: UnicodeCmap<u8> = UnicodeCmap::new(Name(b"Adobe-Identity-UCS"), system_info);
    for &(byte, ch) in &enc.to_unicode_entries {
        cmap.pair(byte, ch);
    }
    let cmap_bytes = cmap.finish();
    let mut cmap_writer = pdf.cmap(id, &cmap_bytes);
    cmap_writer.name(Name(b"Adobe-Identity-UCS"));
    cmap_writer.system_info(system_info);
}

#[cfg(test)]
mod tests {
    // No `#![allow]` here. The two filesystem-touching tests
    // (`emit_writes_file`, `emit_fails_with_mos0014_when_target_is_a_directory`)
    // return `TestResult` and surface failures via `?` / `ensure!`
    // instead of `unwrap`/`expect`/`panic!`. The rest return `()`
    // and use plain `assert!`, which is not covered by
    // `clippy::panic`.
    use std::error::Error;

    use lopdf::{Document as LopdfDocument, Object};
    use mos_layout::{Base14Font, Font, OutlineEntry, Page, PageGraph, TextRun};

    use super::*;

    // Explicit `std::result::Result` because the parent module
    // imports `mos_core::Result` which only takes one type
    // parameter.
    type TestResult = std::result::Result<(), Box<dyn Error>>;

    /// `assert!`-shaped helper that returns `Err` instead of
    /// panicking, so `-> TestResult` bodies stay clippy-clean under
    /// `clippy::panic_in_result_fn`. Mirrors the precedent in
    /// `pdf-base14-metrics/tests/winansi_vendor.rs` and the
    /// integration test at `tests/extended_latin_roundtrip.rs`.
    macro_rules! ensure {
        ($cond:expr, $($arg:tt)*) => {
            if !$cond {
                return Err(format!($($arg)*).into());
            }
        };
    }

    fn count_bytes(haystack: &[u8], needle: &[u8]) -> usize {
        haystack
            .windows(needle.len())
            .filter(|w| *w == needle)
            .count()
    }

    fn sample_graph() -> PageGraph {
        PageGraph {
            pages: vec![Page {
                number: 1,
                width_pt: 595.276_f32,
                height_pt: 841.89_f32,
                runs: vec![
                    TextRun {
                        x_pt: 68.0,
                        baseline_from_top_pt: 100.0,
                        size_pt: 20.0,
                        font: Font::Base14(Base14Font::HelveticaBold),
                        text: "Title".to_owned(),
                        actual_text: None,
                        glyphs: Vec::new(),
                    },
                    TextRun {
                        x_pt: 68.0,
                        baseline_from_top_pt: 130.0,
                        size_pt: 11.0,
                        font: Font::Base14(Base14Font::Helvetica),
                        text: "Body".to_owned(),
                        actual_text: None,
                        glyphs: Vec::new(),
                    },
                ],
                images: Vec::new(),
            }],
            images: Vec::new(),
            outline: Vec::new(),
        }
    }

    fn info_string<'info>(
        info: &'info lopdf::Dictionary,
        key: &[u8],
    ) -> std::result::Result<&'info str, Box<dyn Error>> {
        let Object::String(bytes, _) = info.get(key)? else {
            return Err(format!(
                "expected Info key /{} to be a string",
                String::from_utf8_lossy(key)
            )
            .into());
        };
        Ok(std::str::from_utf8(bytes)?)
    }

    #[test]
    fn build_pdf_starts_with_pdf_header_and_ends_with_eof() {
        let (bytes, diags) = build_pdf(&sample_graph(), &PdfMetadata::default()).unwrap();
        assert!(bytes.starts_with(b"%PDF-"), "missing PDF header");
        assert!(
            bytes.windows(5).any(|w| w == b"%%EOF"),
            "missing %%EOF marker"
        );
        assert!(diags.is_empty(), "unexpected diagnostics: {diags:?}");
    }

    #[test]
    fn build_pdf_embeds_text_runs_as_visible_strings() {
        let (bytes, _) = build_pdf(&sample_graph(), &PdfMetadata::default()).unwrap();
        // The Str writer emits ASCII inside `(...)` so we can grep
        // the raw bytes for the visible payload.
        assert!(
            bytes.windows(b"(Title)".len()).any(|w| w == b"(Title)"),
            "Title not found in stream"
        );
        assert!(
            bytes.windows(b"(Body)".len()).any(|w| w == b"(Body)"),
            "Body not found in stream"
        );
    }

    #[test]
    fn empty_graph_still_produces_valid_pdf() {
        let (bytes, _) = build_pdf(&PageGraph::default(), &PdfMetadata::default()).unwrap();
        assert!(bytes.starts_with(b"%PDF-"));
    }

    #[test]
    fn metadata_and_provenance_appear_in_info_dictionary() -> TestResult {
        let metadata = PdfMetadata {
            title: Some("My Doc".to_owned()),
            author: Some("A. Person".to_owned()),
            language: None,
        };
        let (bytes, _) = build_pdf(&sample_graph(), &metadata).unwrap();
        let doc = LopdfDocument::load_mem(&bytes)?;
        let Object::Reference(info_id) = doc.trailer.get(b"Info")? else {
            return Err("expected trailer /Info reference".into());
        };
        let info = doc.get_dictionary(*info_id)?;

        ensure!(info_string(info, b"Title")? == "My Doc", "wrong /Title");
        ensure!(
            info_string(info, b"Author")? == "A. Person",
            "wrong /Author"
        );
        ensure!(
            info_string(info, b"Producer")? == PRODUCER,
            "wrong /Producer"
        );
        ensure!(info_string(info, b"Creator")? == PRODUCER, "wrong /Creator");
        Ok(())
    }

    #[test]
    fn actual_text_is_emitted_for_replacement_runs() {
        let graph = PageGraph {
            pages: vec![Page {
                number: 1,
                width_pt: 595.276_f32,
                height_pt: 841.89_f32,
                runs: vec![TextRun {
                    x_pt: 68.0,
                    baseline_from_top_pt: 100.0,
                    size_pt: 12.0,
                    font: Font::Base14(Base14Font::Courier),
                    text: "    println".to_owned(),
                    actual_text: Some("\tprintln".to_owned()),
                    glyphs: Vec::new(),
                }],
                images: Vec::new(),
            }],
            images: Vec::new(),
            outline: Vec::new(),
        };

        let (bytes, diags) = build_pdf(&graph, &PdfMetadata::default()).unwrap();

        assert!(diags.is_empty(), "unexpected diagnostics: {diags:?}");
        assert!(
            bytes
                .windows(b"/ActualText".len())
                .any(|w| w == b"/ActualText"),
            "missing /ActualText"
        );
        assert!(
            bytes.windows(b"println".len()).any(|w| w == b"println"),
            "actual text payload missing"
        );
    }

    #[test]
    fn actual_text_wraps_adjacent_fragments_once() {
        let graph = PageGraph {
            pages: vec![Page {
                number: 1,
                width_pt: 595.276_f32,
                height_pt: 841.89_f32,
                runs: vec![
                    TextRun {
                        x_pt: 68.0,
                        baseline_from_top_pt: 100.0,
                        size_pt: 12.0,
                        font: Font::Base14(Base14Font::Courier),
                        text: "    ".to_owned(),
                        actual_text: Some("\tprintln".to_owned()),
                        glyphs: Vec::new(),
                    },
                    TextRun {
                        x_pt: 92.0,
                        baseline_from_top_pt: 100.0,
                        size_pt: 12.0,
                        font: Font::Base14(Base14Font::CourierBold),
                        text: "println".to_owned(),
                        actual_text: Some("\tprintln".to_owned()),
                        glyphs: Vec::new(),
                    },
                ],
                images: Vec::new(),
            }],
            images: Vec::new(),
            outline: Vec::new(),
        };

        let (bytes, diags) = build_pdf(&graph, &PdfMetadata::default()).unwrap();

        assert!(diags.is_empty(), "unexpected diagnostics: {diags:?}");
        assert_eq!(count_bytes(&bytes, b"/ActualText"), 1);
        assert_eq!(count_bytes(&bytes, b"println"), 1);
    }

    /// A graph containing Polish + Czech text: exercises the
    /// `/Differences` and `/ToUnicode` emit paths end to end.
    fn extended_latin_graph() -> PageGraph {
        PageGraph {
            pages: vec![Page {
                number: 1,
                width_pt: 595.276_f32,
                height_pt: 841.89_f32,
                runs: vec![TextRun {
                    x_pt: 68.0,
                    baseline_from_top_pt: 100.0,
                    size_pt: 12.0,
                    font: Font::Base14(Base14Font::Helvetica),
                    text: "Łódź Příliš ě".to_owned(),
                    actual_text: None,
                    glyphs: Vec::new(),
                }],
                images: Vec::new(),
            }],
            images: Vec::new(),
            outline: Vec::new(),
        }
    }

    #[test]
    fn extended_latin_emits_differences_and_to_unicode() {
        let (bytes, diags) = build_pdf(&extended_latin_graph(), &PdfMetadata::default()).unwrap();
        assert!(diags.is_empty(), "unexpected diagnostics: {diags:?}");
        // The /Encoding dict carries /BaseEncoding /WinAnsiEncoding.
        assert!(
            bytes
                .windows(b"/BaseEncoding /WinAnsiEncoding".len())
                .any(|w| w == b"/BaseEncoding /WinAnsiEncoding"),
            "missing /BaseEncoding"
        );
        // The /Differences array contains the AFM glyph names for the
        // non-WinAnsi codepoints in the sample: Ł→Lslash, ř→rcaron,
        // ě→ecaron, ź→zacute. (ó/d/í/l/i/š are WinAnsi natives, so
        // they don't show up in /Differences.)
        for name in [b"/Lslash" as &[u8], b"/rcaron", b"/ecaron", b"/zacute"] {
            assert!(
                bytes.windows(name.len()).any(|w| w == name),
                "missing {:?} in /Differences",
                std::str::from_utf8(name).unwrap_or("?")
            );
        }
        // A /ToUnicode CMap was emitted.
        assert!(
            bytes
                .windows(b"/ToUnicode".len())
                .any(|w| w == b"/ToUnicode"),
            "missing /ToUnicode reference"
        );
        assert!(
            bytes
                .windows(b"beginbfchar".len())
                .any(|w| w == b"beginbfchar"),
            "missing beginbfchar in CMap"
        );
    }

    #[test]
    fn pure_ascii_graph_keeps_predefined_winansi_shortcut() {
        // Existing sample_graph() is pure ASCII; no /Differences
        // should be emitted, the predefined WinAnsi shortcut path is
        // exercised. This guards against accidental "always emit a
        // custom encoding" regressions that would balloon every PDF.
        let (bytes, _) = build_pdf(&sample_graph(), &PdfMetadata::default()).unwrap();
        assert!(
            bytes
                .windows(b"/Encoding /WinAnsiEncoding".len())
                .any(|w| w == b"/Encoding /WinAnsiEncoding"),
            "expected predefined WinAnsi shortcut on ASCII-only doc"
        );
        assert!(
            !bytes
                .windows(b"/BaseEncoding".len())
                .any(|w| w == b"/BaseEncoding"),
            "no custom /Encoding dict expected for ASCII-only doc"
        );
    }

    #[test]
    fn extended_latin_content_stream_uses_remapped_bytes() {
        // Polish "Ł" lands in the first gap slot (0x7F) by the
        // allocator's deterministic order. The run also contains
        // Latin-1 bytes ≥ 0x80 (`ó`, `í`, …) so pdf-writer switches
        // the string from literal `(...)` to hex `<...>` form;
        // 0x7F therefore appears in the document as the ASCII pair
        // `7F`. This is a smoke check that the encoder routed Ł to
        // a remapped slot rather than substituting `?` (0x3F).
        //
        // Both assertions operate on the page content stream slice
        // only: scanning the whole PDF would let the `/ToUnicode`
        // CMap (`<7F> <0141>`) satisfy the `7F` needle even if the
        // content stream had silently substituted to `?`. Surgical
        // slicing keeps the smoke test honest.
        let (bytes, _) = build_pdf(&extended_latin_graph(), &PdfMetadata::default()).unwrap();
        let content_stream = first_content_stream(&bytes).expect("content stream not found");
        let needle = b"7F";
        assert!(
            content_stream.windows(needle.len()).any(|w| w == needle),
            "content stream should reference remapped slot 0x7F"
        );
        let qmark_count = content_stream.split(|&b| b == b'?').count() - 1;
        assert!(
            qmark_count < 5,
            "too many `?` in PDF ({qmark_count}); did Ł/ř/ě/ź get substituted?"
        );
    }

    #[test]
    fn build_pdf_is_byte_for_byte_deterministic() {
        // Regression guard for the HashMap-iteration-order bug that
        // shuffled indirect IDs between builds. Two `build_pdf` calls
        // on the same graph must produce identical bytes; otherwise
        // golden tests and reproducible CI artifacts break.
        let (a, _) = build_pdf(&extended_latin_graph(), &PdfMetadata::default()).unwrap();
        let (b, _) = build_pdf(&extended_latin_graph(), &PdfMetadata::default()).unwrap();
        assert_eq!(
            a,
            b,
            "build_pdf is non-deterministic: byte lengths {} vs {}",
            a.len(),
            b.len()
        );
    }

    /// Locate the first `stream` ... `endstream` body in a PDF byte
    /// blob and return the bytes between them. `build_pdf` emits the
    /// page content stream before any `/ToUnicode` `CMap` stream
    /// (see the object-order comment in [`build_pdf`]), so the first
    /// match is always the page content. Markers anchor on the
    /// surrounding `\n` so the substring inside `endstream` doesn't
    /// false-match the opener.
    fn first_content_stream(bytes: &[u8]) -> Option<&[u8]> {
        let open = b"\nstream\n";
        let close = b"\nendstream";
        let open_at = bytes.windows(open.len()).position(|w| w == open)?;
        let body = &bytes[open_at + open.len()..];
        let close_at = body.windows(close.len()).position(|w| w == close)?;
        Some(&body[..close_at])
    }

    fn unique_temp_path(label: &str) -> std::path::PathBuf {
        std::env::temp_dir().join(format!(
            "mos-pdf-test-{label}-{}",
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map_or(0, |d| d.as_nanos())
        ))
    }

    #[test]
    fn emit_writes_file() -> TestResult {
        let dir = unique_temp_path("write");
        let out = dir.join("out.pdf");
        let diags = emit(&sample_graph(), &PdfMetadata::default(), &out)
            .map_err(|e| format!("emit: {e:?}"))?;
        ensure!(diags.is_empty(), "unexpected diagnostics: {diags:?}");
        let bytes = std::fs::read(&out)?;
        ensure!(bytes.starts_with(b"%PDF-"), "missing PDF header");
        std::fs::remove_dir_all(&dir).ok();
        Ok(())
    }

    /// Build a graph with one image: a 4×2 red-and-blue checker
    /// flattened to RGB8, sized at 40×20 pt. Reused across multiple
    /// emit tests below.
    fn image_graph() -> PageGraph {
        use mos_layout::{ImageHandle, ImagePlacement};
        use std::sync::Arc;
        // 4 columns × 2 rows; alternating red/blue cells.
        let mut rgb8 = Vec::with_capacity(4 * 2 * 3);
        for y in 0..2 {
            for x in 0..4 {
                if (x + y) % 2 == 0 {
                    rgb8.extend_from_slice(&[255, 0, 0]);
                } else {
                    rgb8.extend_from_slice(&[0, 0, 255]);
                }
            }
        }
        let handle = ImageHandle {
            id: 0,
            resolved_path: "/tmp/checker.png".to_owned(),
            pixel_width: 4,
            pixel_height: 2,
            rgb8: Arc::from(rgb8),
        };
        PageGraph {
            pages: vec![Page {
                number: 1,
                width_pt: 595.276_f32,
                height_pt: 841.89_f32,
                runs: Vec::new(),
                images: vec![ImagePlacement {
                    handle: handle.clone(),
                    x_pt: 68.0,
                    top_from_top_pt: 100.0,
                    width_pt: 40.0,
                    height_pt: 20.0,
                }],
            }],
            images: vec![handle],
            outline: Vec::new(),
        }
    }

    #[test]
    fn image_xobject_carries_width_height_and_devicergb() {
        let (bytes, diags) = build_pdf(&image_graph(), &PdfMetadata::default()).unwrap();
        assert!(diags.is_empty(), "unexpected diagnostics: {diags:?}");
        // The Image XObject must declare /Subtype /Image, /Width 4,
        // /Height 2, /ColorSpace /DeviceRGB, /BitsPerComponent 8, and
        // /Filter /FlateDecode.
        for needle in [
            b"/Subtype /Image" as &[u8],
            b"/Width 4",
            b"/Height 2",
            b"/ColorSpace /DeviceRGB",
            b"/BitsPerComponent 8",
            b"/Filter /FlateDecode",
        ] {
            assert!(
                bytes.windows(needle.len()).any(|w| w == needle),
                "missing {:?} in PDF",
                std::str::from_utf8(needle).unwrap_or("?")
            );
        }
    }

    #[test]
    fn image_placement_emits_do_operator_referencing_xobject() {
        let (bytes, _) = build_pdf(&image_graph(), &PdfMetadata::default()).unwrap();
        // The page's resource dict must list /Im0; the content stream
        // must reference /Im0 via the Do operator.
        assert!(
            bytes.windows(b"/Im0 ".len()).any(|w| w == b"/Im0 "),
            "/Im0 resource name not found"
        );
        assert!(
            bytes.windows(b"/Im0 Do".len()).any(|w| w == b"/Im0 Do"),
            "/Im0 Do operator not found in content stream"
        );
    }

    #[test]
    fn duplicate_image_emits_one_xobject() {
        // Two placements of the same image should still produce one
        // shared XObject; the layout pass already dedup'd them, so the
        // PDF backend never sees two ImageHandle entries.
        use mos_layout::{ImageHandle, ImagePlacement};
        use std::sync::Arc;
        let handle = ImageHandle {
            id: 0,
            resolved_path: "/tmp/shared.png".to_owned(),
            pixel_width: 1,
            pixel_height: 1,
            rgb8: Arc::from(vec![10_u8, 20, 30]),
        };
        let graph = PageGraph {
            pages: vec![Page {
                number: 1,
                width_pt: 595.276_f32,
                height_pt: 841.89_f32,
                runs: Vec::new(),
                images: vec![
                    ImagePlacement {
                        handle: handle.clone(),
                        x_pt: 10.0,
                        top_from_top_pt: 50.0,
                        width_pt: 5.0,
                        height_pt: 5.0,
                    },
                    ImagePlacement {
                        handle: handle.clone(),
                        x_pt: 100.0,
                        top_from_top_pt: 50.0,
                        width_pt: 5.0,
                        height_pt: 5.0,
                    },
                ],
            }],
            images: vec![handle],
            outline: Vec::new(),
        };
        let (bytes, _) = build_pdf(&graph, &PdfMetadata::default()).unwrap();
        let xobject_marker = b"/Subtype /Image";
        let count = bytes
            .windows(xobject_marker.len())
            .filter(|w| *w == xobject_marker)
            .count();
        assert_eq!(count, 1, "expected exactly one Image XObject, got {count}");
        // Both placements show up as /Im0 Do.
        let do_count = bytes
            .windows(b"/Im0 Do".len())
            .filter(|w| *w == b"/Im0 Do")
            .count();
        assert_eq!(
            do_count, 2,
            "expected two /Im0 Do operators, got {do_count}"
        );
    }

    #[test]
    fn image_only_pdf_remains_byte_deterministic() {
        let (a, _) = build_pdf(&image_graph(), &PdfMetadata::default()).unwrap();
        let (b, _) = build_pdf(&image_graph(), &PdfMetadata::default()).unwrap();
        assert_eq!(a, b, "image emit must be byte-stable across runs");
    }

    #[test]
    fn emit_fails_with_mos0014_when_target_is_a_directory() -> TestResult {
        // Writing a file whose path collides with an existing
        // directory must surface as an `MOS0014` diagnostic, not a
        // panic or an `Unimplemented` error.
        let dir = unique_temp_path("conflict");
        std::fs::create_dir_all(&dir)?;
        // `dir` itself is the bogus output target; `fs::write` will
        // refuse to overwrite a directory.
        let result = emit(&sample_graph(), &PdfMetadata::default(), &dir);
        std::fs::remove_dir_all(&dir).ok();
        let Err(err) = result else {
            return Err("expected emit to fail when target is a directory".into());
        };
        let CoreError::Diagnostic(d) = err else {
            return Err("expected Diagnostic, got Unimplemented".into());
        };
        ensure!(
            d.def().code() == codes::MOS0014.code(),
            "wrong code: {:?}",
            d.def().code()
        );
        ensure!(
            d.message().contains("could not write PDF"),
            "message={:?}",
            d.message()
        );
        Ok(())
    }

    /// A single-page graph carrying the given outline entries. Every
    /// entry lands on page 0; the page is A4 so `top_from_top_pt` flips
    /// against `841.89`.
    fn outline_graph(entries: Vec<OutlineEntry>) -> PageGraph {
        PageGraph {
            pages: vec![Page {
                number: 1,
                width_pt: 595.276_f32,
                height_pt: 841.89_f32,
                runs: Vec::new(),
                images: Vec::new(),
            }],
            images: Vec::new(),
            outline: entries,
        }
    }

    fn entry(level: u8, title: &str, top_from_top_pt: f32) -> OutlineEntry {
        OutlineEntry {
            level,
            title: title.to_owned(),
            page_index: 0,
            top_from_top_pt,
        }
    }

    /// Read `key` from `dict` as an indirect-reference object id.
    fn ref_id(
        dict: &lopdf::Dictionary,
        key: &[u8],
    ) -> std::result::Result<(u32, u16), Box<dyn Error>> {
        match dict.get(key)? {
            Object::Reference(id) => Ok(*id),
            other => Err(format!(
                "expected /{} to be a reference, got {other:?}",
                String::from_utf8_lossy(key)
            )
            .into()),
        }
    }

    /// Follow catalog → /Outlines and return the root outline dictionary.
    fn load_outlines(
        doc: &LopdfDocument,
    ) -> std::result::Result<&lopdf::Dictionary, Box<dyn Error>> {
        let root_id = ref_id(&doc.trailer, b"Root")?;
        let catalog = doc.get_dictionary(root_id)?;
        let outlines_id = ref_id(catalog, b"Outlines")?;
        Ok(doc.get_dictionary(outlines_id)?)
    }

    #[test]
    fn outline_emitted_when_headings_present() -> TestResult {
        let graph = outline_graph(vec![entry(1, "One", 100.0), entry(2, "Two", 200.0)]);
        let (bytes, diags) = build_pdf(&graph, &PdfMetadata::default()).unwrap();
        ensure!(diags.is_empty(), "unexpected diagnostics: {diags:?}");
        ensure!(
            count_bytes(&bytes, b"/Type /Outlines") >= 1,
            "missing /Type /Outlines"
        );

        let doc = LopdfDocument::load_mem(&bytes)?;
        let outlines = load_outlines(&doc)?;
        // Root /Count is the full entry total (every item open).
        let Object::Integer(count) = outlines.get(b"Count")? else {
            return Err("missing /Count on root /Outlines".into());
        };
        ensure!(*count == 2, "wrong root /Count: {count}");
        // The single top-level H1 is both first and last root child.
        ensure!(
            ref_id(outlines, b"First")? == ref_id(outlines, b"Last")?,
            "single top-level entry must be both /First and /Last"
        );
        Ok(())
    }

    #[test]
    fn no_outline_dict_for_heading_free_doc() -> TestResult {
        // sample_graph() has an empty outline: no /Outlines objects, and
        // the catalog carries no /Outlines key. Guards the byte-identical
        // heading-free path.
        let (bytes, _) = build_pdf(&sample_graph(), &PdfMetadata::default()).unwrap();
        ensure!(
            count_bytes(&bytes, b"/Outlines") == 0,
            "heading-free doc must emit no /Outlines"
        );
        let doc = LopdfDocument::load_mem(&bytes)?;
        let root_id = ref_id(&doc.trailer, b"Root")?;
        let catalog = doc.get_dictionary(root_id)?;
        ensure!(
            catalog.get(b"Outlines").is_err(),
            "catalog must not carry an /Outlines key when there are no headings"
        );
        Ok(())
    }

    #[test]
    fn outline_nesting_wires_parent_first_last() -> TestResult {
        // H1 with two H2 children.
        let graph = outline_graph(vec![
            entry(1, "Chapter", 100.0),
            entry(2, "First", 200.0),
            entry(2, "Second", 300.0),
        ]);
        let (bytes, _) = build_pdf(&graph, &PdfMetadata::default()).unwrap();
        let doc = LopdfDocument::load_mem(&bytes)?;
        let outlines = load_outlines(&doc)?;

        // The lone H1 is the single root child.
        let h1_id = ref_id(outlines, b"First")?;
        ensure!(h1_id == ref_id(outlines, b"Last")?, "H1 must be sole root");
        let h1 = doc.get_dictionary(h1_id)?;

        let first_h2_id = ref_id(h1, b"First")?;
        let last_h2_id = ref_id(h1, b"Last")?;
        ensure!(first_h2_id != last_h2_id, "the two H2 items must differ");

        let first_h2 = doc.get_dictionary(first_h2_id)?;
        let last_h2 = doc.get_dictionary(last_h2_id)?;
        // Both H2 parents point back at the H1.
        ensure!(
            ref_id(first_h2, b"Parent")? == h1_id,
            "first H2 /Parent wrong"
        );
        ensure!(
            ref_id(last_h2, b"Parent")? == h1_id,
            "last H2 /Parent wrong"
        );
        // The two H2s are prev/next linked in document order.
        ensure!(ref_id(first_h2, b"Next")? == last_h2_id, "H2 /Next wrong");
        ensure!(ref_id(last_h2, b"Prev")? == first_h2_id, "H2 /Prev wrong");
        Ok(())
    }

    #[test]
    fn outline_skipped_level_attaches_to_nearest_ancestor() -> TestResult {
        // H1 then H3 (no intervening H2): the H3 must parent under the H1.
        let graph = outline_graph(vec![entry(1, "Top", 100.0), entry(3, "Deep", 200.0)]);
        let (bytes, _) = build_pdf(&graph, &PdfMetadata::default()).unwrap();
        let doc = LopdfDocument::load_mem(&bytes)?;
        let outlines = load_outlines(&doc)?;

        let h1_id = ref_id(outlines, b"First")?;
        let h1 = doc.get_dictionary(h1_id)?;
        let h3_id = ref_id(h1, b"First")?;
        let h3 = doc.get_dictionary(h3_id)?;
        ensure!(
            ref_id(h3, b"Parent")? == h1_id,
            "skipped-level H3 must attach to the nearest shallower ancestor (H1)"
        );
        Ok(())
    }

    #[test]
    fn outline_dest_uses_flipped_top_coordinate() -> TestResult {
        let top_from_top = 120.0_f32;
        let graph = outline_graph(vec![entry(1, "Heading", top_from_top)]);
        let (bytes, _) = build_pdf(&graph, &PdfMetadata::default()).unwrap();
        let doc = LopdfDocument::load_mem(&bytes)?;
        let outlines = load_outlines(&doc)?;

        let item = doc.get_dictionary(ref_id(outlines, b"First")?)?;
        let Object::Array(dest) = item.get(b"Dest")? else {
            return Err("missing /Dest array on outline item".into());
        };
        // Dest is [pageRef /XYZ left top zoom]; top sits at index 3 and
        // must be page_height - top_from_top_pt (bottom-origin flip).
        let Some(Object::Real(top)) = dest.get(3) else {
            return Err(format!("dest top not a real: {dest:?}").into());
        };
        let expected = 841.89_f32 - top_from_top;
        let within_tolerance = (*top - expected).abs() < 0.01;
        ensure!(
            within_tolerance,
            "wrong dest top: {top} vs expected {expected}"
        );
        Ok(())
    }

    #[test]
    fn outline_pdf_is_byte_for_byte_deterministic() {
        // The outline emit path must not introduce HashMap-iteration
        // nondeterminism: two builds of an outline-bearing graph match.
        let graph = outline_graph(vec![
            entry(1, "Chapter", 100.0),
            entry(2, "First", 200.0),
            entry(2, "Second", 300.0),
        ]);
        let (a, _) = build_pdf(&graph, &PdfMetadata::default()).unwrap();
        let (b, _) = build_pdf(&graph, &PdfMetadata::default()).unwrap();
        assert_eq!(a, b, "outline emit must be byte-stable across runs");
    }

    #[test]
    fn outline_after_populated_encoding_map_is_byte_deterministic() {
        // `outline_graph` is base14-ASCII, so its encoding/embedded HashMaps
        // are empty — its determinism test can't prove outline refs stay
        // stable when allocated AFTER a HashMap-populated, variable object
        // count. `extended_latin_graph` populates `encoding_refs`; stacking
        // an outline on it exercises "outline allocated last, after a
        // reseeded HashMap" across two builds.
        let mut graph = extended_latin_graph();
        graph.outline = vec![entry(1, "Chapter", 100.0), entry(2, "Section", 200.0)];
        let (a, _) = build_pdf(&graph, &PdfMetadata::default()).unwrap();
        let (b, _) = build_pdf(&graph, &PdfMetadata::default()).unwrap();
        assert_eq!(a, b, "outline + custom encoding build must be byte-stable");
    }
}