imprimatur 0.1.0 → 0.3.0

data/ext/imprimatur_native/core/src/archive.rs

@@ -0,0 +1,279 @@
+//! Zip archives of any files, for what is not a document.
+//!
+//! Entries are written from disk (streamed) or from memory, with their
+//! modification times and comments, ZIP64 when an entry is large; they are
+//! read one by one, each within a size limit. Behind the `archive` feature,
+//! which brings in the `zip` crate; documents' own zips (XLSX, DOCX) never
+//! need it.
+//!
+//! ```
+//! use std::io::Cursor;
+//! use imprimatur::archive::{Archive, Writer};
+//!
+//! let mut writer = Writer::new(Cursor::new(Vec::new()));
+//! writer.add("notes/readme.txt", b"hello", Some("first"))?;
+//! let bytes = writer.finish()?.into_inner();
+//!
+//! let mut archive = Archive::new(Cursor::new(bytes))?;
+//! assert_eq!(archive.names(), ["notes/readme.txt"]);
+//! assert_eq!(archive.read("notes/readme.txt", 1024)?.as_deref(), Some(&b"hello"[..]));
+//! # Ok::<(), imprimatur::Error>(())
+//! ```
+
+#[cfg(test)]
+mod tests;
+
+use std::fs::File;
+use std::io::{self, Read, Seek, Write};
+use std::path::Path;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use ::zip::result::ZipError;
+use ::zip::write::FullFileOptions;
+use ::zip::{CompressionMethod, DateTime, ZipArchive, ZipWriter};
+
+use crate::xlsx::civil_from_days;
+use crate::{Error, Result};
+
+/// An archive being written; [`finish`](Self::finish) writes its directory.
+pub struct Writer<W: Write + Seek> {
+    zip: ZipWriter<W>,
+}
+
+impl Writer<File> {
+    /// A new archive at `path`, replacing any file there.
+    ///
+    /// # Errors
+    /// [`Error::Io`] when the file cannot be created.
+    pub fn create(path: impl AsRef<Path>) -> Result<Self> {
+        Ok(Self::new(File::create(path)?))
+    }
+}
+
+impl<W: Write + Seek> Writer<W> {
+    pub fn new(sink: W) -> Self {
+        Self { zip: ZipWriter::new(sink) }
+    }
+
+    /// Adds the file at `source` as `name`, streamed from disk, with its
+    /// modification time.
+    ///
+    /// # Errors
+    /// [`Error::Io`] when the file cannot be read or the archive written.
+    pub fn add_file(
+        &mut self,
+        name: &str,
+        source: impl AsRef<Path>,
+        comment: Option<&str>,
+    ) -> Result<()> {
+        let mut file = File::open(source)?;
+        let metadata = file.metadata()?;
+        self.zip
+            .start_file(name, options(metadata.modified().ok(), metadata.len(), comment))
+            .map_err(error)?;
+        io::copy(&mut file, &mut self.zip)?;
+        Ok(())
+    }
+
+    /// Adds `data` as `name`, dated now.
+    ///
+    /// # Errors
+    /// [`Error::Io`] when the archive cannot be written.
+    pub fn add(&mut self, name: &str, data: &[u8], comment: Option<&str>) -> Result<()> {
+        let size = u64::try_from(data.len()).unwrap_or(u64::MAX);
+        self.zip
+            .start_file(name, options(Some(SystemTime::now()), size, comment))
+            .map_err(error)?;
+        self.zip.write_all(data)?;
+        Ok(())
+    }
+
+    /// The archive's own comment, shown by most zip tools.
+    ///
+    /// # Errors
+    /// [`Error::Malformed`] for a comment over 65,535 bytes.
+    pub fn set_comment(&mut self, comment: &str) -> Result<()> {
+        self.zip.set_comment(comment).map_err(error)
+    }
+
+    /// Writes the central directory and gives the sink back.
+    ///
+    /// # Errors
+    /// [`Error::Io`] when it cannot be written.
+    pub fn finish(self) -> Result<W> {
+        self.zip.finish().map_err(error)
+    }
+}
+
+/// How an entry is written: deflated, dated, ZIP64 when it needs to be.
+fn options(
+    modified: Option<SystemTime>,
+    size: u64,
+    comment: Option<&str>,
+) -> FullFileOptions<'static, 'static> {
+    let options = FullFileOptions::default()
+        .compression_method(CompressionMethod::Deflated)
+        .last_modified_time(dos_time(modified))
+        .large_file(size >= u64::from(u32::MAX));
+    match comment {
+        Some(comment) => options.with_file_comment(comment),
+        None => options,
+    }
+}
+
+/// A time as a zip entry's (UTC, two-second steps, 1980 to 2107); the
+/// format's epoch outside that range.
+fn dos_time(time: Option<SystemTime>) -> DateTime {
+    let Some(seconds) =
+        time.and_then(|time| time.duration_since(UNIX_EPOCH).ok()).map(|since| since.as_secs())
+    else {
+        return DateTime::default();
+    };
+    let days = i64::try_from(seconds / 86_400).unwrap_or(i64::MAX);
+    let (year, month, day) = civil_from_days(days);
+    let clock = seconds % 86_400;
+    let part = |value: u64| u8::try_from(value).unwrap_or(0);
+    let (month, day) = (u8::try_from(month).unwrap_or(1), u8::try_from(day).unwrap_or(1));
+    u16::try_from(year)
+        .ok()
+        .and_then(|year| {
+            DateTime::from_date_and_time(
+                year,
+                month,
+                day,
+                part(clock / 3600),
+                part(clock / 60 % 60),
+                part(clock % 60),
+            )
+            .ok()
+        })
+        .unwrap_or_default()
+}
+
+/// What the archive's directory says of an entry.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Entry {
+    pub name: String,
+    /// Its size once decompressed, as the directory states it.
+    pub size: u64,
+    pub compressed_size: u64,
+    pub crc32: u32,
+    pub comment: String,
+}
+
+/// An archive being read.
+pub struct Archive<R: Read + Seek> {
+    zip: ZipArchive<R>,
+}
+
+impl Archive<File> {
+    /// The archive at `path`.
+    ///
+    /// # Errors
+    /// [`Error::Io`] when it cannot be opened, [`Error::Malformed`] when it
+    /// is no zip.
+    pub fn open(path: impl AsRef<Path>) -> Result<Self> {
+        Self::new(File::open(path)?)
+    }
+}
+
+impl<R: Read + Seek> Archive<R> {
+    /// # Errors
+    /// [`Error::Malformed`] when `source` is no zip.
+    pub fn new(source: R) -> Result<Self> {
+        Ok(Self { zip: ZipArchive::new(source).map_err(error)? })
+    }
+
+    /// The entries' names, in the archive's order.
+    #[must_use]
+    pub fn names(&self) -> Vec<String> {
+        self.zip
+            .file_names()
+            .filter_map(std::result::Result::ok)
+            .map(std::borrow::Cow::into_owned)
+            .collect()
+    }
+
+    /// Every entry's name, sizes, checksum and comment, in the archive's
+    /// order, without decompressing anything.
+    ///
+    /// # Errors
+    /// [`Error::Malformed`] for a damaged directory.
+    pub fn entries(&mut self) -> Result<Vec<Entry>> {
+        (0..self.zip.len())
+            .map(|index| {
+                let entry = self.zip.by_index_raw(index).map_err(error)?;
+                Ok(Entry {
+                    name: entry.name().map_err(error)?.into_owned(),
+                    size: entry.size(),
+                    compressed_size: entry.compressed_size(),
+                    crc32: entry.crc32(),
+                    comment: entry.comment().to_owned(),
+                })
+            })
+            .collect()
+    }
+
+    /// The entry `name`'s bytes, `None` when there is none.
+    ///
+    /// # Errors
+    /// [`Error::LimitExceeded`] past `limit` bytes, [`Error::PasswordRequired`]
+    /// for an encrypted entry, [`Error::Malformed`] for a damaged one.
+    pub fn read(&mut self, name: &str, limit: u64) -> Result<Option<Vec<u8>>> {
+        let mut out = Vec::new();
+        self.copy(name, &mut out, limit).map(|found| found.then_some(out))
+    }
+
+    /// Writes the entry `name` to the file at `path`; whether there was one.
+    ///
+    /// # Errors
+    /// As [`read`](Self::read), and [`Error::Io`] for the file.
+    pub fn extract(&mut self, name: &str, path: impl AsRef<Path>, limit: u64) -> Result<bool> {
+        if !self.names().iter().any(|entry| entry == name) {
+            return Ok(false);
+        }
+        let mut file = File::create(path)?;
+        self.copy(name, &mut file, limit)
+    }
+
+    /// Copies an entry's bytes to `out`, at most `limit` of them.
+    fn copy(&mut self, name: &str, out: &mut impl Write, limit: u64) -> Result<bool> {
+        let entry = match self.zip.by_name(name) {
+            Ok(entry) => entry,
+            Err(ZipError::FileNotFound) => return Ok(false),
+            Err(other) => return Err(error(other)),
+        };
+        // One byte past the limit tells a full entry from a cut one.
+        let copied = io::copy(&mut entry.take(limit.saturating_add(1)), out)?;
+        if copied > limit {
+            return Err(Error::LimitExceeded("decompressed size"));
+        }
+        Ok(true)
+    }
+}
+
+impl<W: Write + Seek> std::fmt::Debug for Writer<W> {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.debug_struct("Writer").finish_non_exhaustive()
+    }
+}
+
+impl<R: Read + Seek> std::fmt::Debug for Archive<R> {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.debug_struct("Archive").field("entries", &self.zip.len()).finish()
+    }
+}
+
+fn error(error: ZipError) -> Error {
+    match error {
+        ZipError::Io(error) => Error::Io(error),
+        ZipError::InvalidPassword => Error::PasswordRequired,
+        ZipError::UnsupportedArchive(reason) if reason.contains("assword") => {
+            Error::PasswordRequired
+        }
+        ZipError::UnsupportedArchive(reason) => {
+            Error::UnsupportedDocument(format!("a zip entry: {reason}"))
+        }
+        other => Error::malformed("zip", other.to_string()),
+    }
+}

data/ext/imprimatur_native/core/src/doc/paragraph.rs

@@ -46,8 +46,9 @@ impl Run {
     }
 }
 
-/// Runs of text laid out together. Left aligned unless told otherwise, or
-/// right aligned when right to left.
+/// Runs of text laid out together, in the direction set or else that of
+/// their first letter. Left aligned unless told otherwise, or right aligned
+/// when right to left.
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct Paragraph {
     pub(crate) runs: Vec<Run>,
@@ -102,9 +103,15 @@ impl Paragraph {
         &self.runs
     }
 
+    /// The direction the paragraph reads in: as set, or else that of its
+    /// first letter.
+    pub(crate) fn effective_direction(&self) -> Option<TextDirection> {
+        self.direction.or_else(|| self.runs.iter().find_map(|run| TextDirection::of(&run.text)))
+    }
+
     /// The alignment the paragraph is laid out with.
     pub(crate) fn effective_align(&self) -> Align {
-        self.align.unwrap_or(match self.direction {
+        self.align.unwrap_or_else(|| match self.effective_direction() {
             Some(TextDirection::RightToLeft) => Align::Right,
             _ => Align::Left,
         })

data/ext/imprimatur_native/core/src/doc/picture.rs

@@ -0,0 +1,192 @@
+//! Pictures: PNG or JPEG files, read once for what PDF and DOCX need.
+
+use std::sync::Arc;
+
+use crate::style::Align;
+use crate::{Error, Result};
+
+/// Pixels per point at 96 pixels an inch: a picture's size when none is set.
+const POINTS_PER_PIXEL: f64 = 0.75;
+/// The largest side, in points, a picture may be set to: PDF's page limit.
+const MAX_POINTS: f64 = 14_400.0;
+/// The largest side, in pixels, a picture may have.
+const MAX_PIXELS: u32 = 1 << 16;
+
+/// A PNG or JPEG drawn in the document's flow.
+///
+/// It is drawn at the width or height set (in points, the other following
+/// its proportions), or else at 96 pixels an inch, never larger than the
+/// page leaves room for.
+///
+/// ```no_run
+/// use imprimatur::doc::{Document, Picture};
+/// use imprimatur::style::Align;
+///
+/// let mut doc = Document::new();
+/// doc.picture(Picture::new(std::fs::read("logo.png")?)?.width(144.0)?.align(Align::Center));
+/// # Ok::<(), imprimatur::Error>(())
+/// ```
+#[derive(Debug, Clone, PartialEq)]
+pub struct Picture {
+    pub(crate) data: Arc<[u8]>,
+    pub(crate) kind: Kind,
+    pub(crate) pixels: (u32, u32),
+    width: Option<f64>,
+    height: Option<f64>,
+    pub(crate) align: Option<Align>,
+}
+
+/// The format, and what writing it takes.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Kind {
+    Png(Png),
+    /// Gray (1), RGB (3) or CMYK (4) components; Adobe's CMYK is inverted.
+    Jpeg {
+        components: u8,
+        inverted: bool,
+    },
+}
+
+/// A PNG's pixel layout and its compressed pixels (its `IDAT` chunks).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Png {
+    pub depth: u8,
+    /// 0 gray, 2 RGB, 3 palette, 4 gray and alpha, 6 RGB and alpha.
+    pub color: u8,
+    pub palette: Vec<u8>,
+    /// The `tRNS` chunk: a palette's alphas, or the transparent color.
+    pub transparency: Vec<u8>,
+    pub compressed: Vec<u8>,
+}
+
+impl Picture {
+    /// # Errors
+    /// [`Error::InvalidImage`] for data that is no PNG or JPEG, a damaged
+    /// one, an interlaced PNG, a JPEG other than 8 bits a sample, or one
+    /// larger than 65 536 pixels a side.
+    pub fn new(data: impl Into<Vec<u8>>) -> Result<Self> {
+        let data: Arc<[u8]> = data.into().into();
+        let (kind, pixels) = if data.starts_with(b"\x89PNG\r\n\x1a\n") {
+            png(&data)?
+        } else if data.starts_with(&[0xFF, 0xD8, 0xFF]) {
+            jpeg(&data)?
+        } else {
+            return Err(Error::InvalidImage("not a PNG or JPEG image"));
+        };
+        let valid = (1..=MAX_PIXELS).contains(&pixels.0) && (1..=MAX_PIXELS).contains(&pixels.1);
+        valid.ok_or(Error::InvalidImage("a picture of 1 to 65 536 pixels a side"))?;
+        Ok(Self { data, kind, pixels, width: None, height: None, align: None })
+    }
+
+    /// Its width in points; the height follows unless set too.
+    ///
+    /// # Errors
+    /// [`Error::InvalidImage`] outside 1 to 14 400 points.
+    pub fn width(mut self, points: f64) -> Result<Self> {
+        self.width = Some(points_in_range(points)?);
+        Ok(self)
+    }
+
+    /// Its height in points; the width follows unless set too.
+    ///
+    /// # Errors
+    /// [`Error::InvalidImage`] outside 1 to 14 400 points.
+    pub fn height(mut self, points: f64) -> Result<Self> {
+        self.height = Some(points_in_range(points)?);
+        Ok(self)
+    }
+
+    #[must_use]
+    pub const fn align(mut self, align: Align) -> Self {
+        self.align = Some(align);
+        self
+    }
+
+    /// The size it is drawn at, in points, fitted into `room` (the width
+    /// and height between the margins).
+    pub(crate) fn size(&self, room: (f64, f64)) -> (f64, f64) {
+        let (pixels_wide, pixels_high) = (f64::from(self.pixels.0), f64::from(self.pixels.1));
+        let (width, height) = match (self.width, self.height) {
+            (Some(width), Some(height)) => (width, height),
+            (Some(width), None) => (width, width * pixels_high / pixels_wide),
+            (None, Some(height)) => (height * pixels_wide / pixels_high, height),
+            (None, None) => (pixels_wide * POINTS_PER_PIXEL, pixels_high * POINTS_PER_PIXEL),
+        };
+        let scale = (room.0 / width).min(room.1 / height).min(1.0);
+        (width * scale, height * scale)
+    }
+}
+
+fn points_in_range(points: f64) -> Result<f64> {
+    (1.0..=MAX_POINTS)
+        .contains(&points)
+        .then_some(points)
+        .ok_or(Error::InvalidImage("a picture of 1 to 14 400 points a side"))
+}
+
+/// A PNG's chunks; interlaced ones are refused.
+fn png(data: &[u8]) -> Result<(Kind, (u32, u32))> {
+    let damaged = || Error::InvalidImage("a damaged PNG");
+    let mut png = Png {
+        depth: 0,
+        color: 0,
+        palette: Vec::new(),
+        transparency: Vec::new(),
+        compressed: Vec::new(),
+    };
+    let (mut pixels, mut at) = (None, 8);
+    while let Some(head) = data.get(at..at + 8) {
+        let length = u32::from_be_bytes([head[0], head[1], head[2], head[3]]) as usize;
+        let body = data.get(at + 8..at + 8 + length).ok_or_else(damaged)?;
+        match &head[4..8] {
+            b"IHDR" if body.len() == 13 => {
+                let side = |at: usize| {
+                    u32::from_be_bytes([body[at], body[at + 1], body[at + 2], body[at + 3]])
+                };
+                pixels = Some((side(0), side(4)));
+                (png.depth, png.color) = (body[8], body[9]);
+                (body[12] == 0).ok_or(Error::InvalidImage("an interlaced PNG"))?;
+            }
+            b"PLTE" => png.palette = body.to_vec(),
+            b"tRNS" => png.transparency = body.to_vec(),
+            b"IDAT" => png.compressed.extend_from_slice(body),
+            b"IEND" => break,
+            _ => {}
+        }
+        at += 12 + length;
+    }
+    let layout = matches!(
+        (png.color, png.depth),
+        (0, 1 | 2 | 4 | 8 | 16) | (3, 1 | 2 | 4 | 8) | (2 | 4 | 6, 8 | 16)
+    );
+    let palette = png.color != 3 || !png.palette.is_empty();
+    let pixels = pixels.filter(|_| layout && palette && !png.compressed.is_empty());
+    Ok((Kind::Png(png), pixels.ok_or_else(damaged)?))
+}
+
+/// A JPEG's frame header (`SOF`), and Adobe's mark, which inverts CMYK.
+fn jpeg(data: &[u8]) -> Result<(Kind, (u32, u32))> {
+    let damaged = || Error::InvalidImage("a damaged JPEG");
+    let (mut at, mut inverted) = (2, false);
+    loop {
+        let &[0xFF, marker, high, low] = data.get(at..at + 4).ok_or_else(damaged)? else {
+            return Err(damaged());
+        };
+        let length = usize::from(u16::from_be_bytes([high, low]));
+        if marker == 0xEE && data.get(at + 4..at + 9) == Some(b"Adobe") {
+            inverted = true;
+        }
+        // SOF0 to SOF15, but DHT, JPG and DAC share the range.
+        if (0xC0..=0xCF).contains(&marker) && !matches!(marker, 0xC4 | 0xC8 | 0xCC) {
+            let frame = data.get(at + 4..at + 10).ok_or_else(damaged)?;
+            (frame[0] == 8).ok_or(Error::InvalidImage("a JPEG of 8 bits a sample"))?;
+            let height = u32::from(u16::from_be_bytes([frame[1], frame[2]]));
+            let width = u32::from(u16::from_be_bytes([frame[3], frame[4]]));
+            let components = frame[5];
+            matches!(components, 1 | 3 | 4).ok_or_else(damaged)?;
+            let kind = Kind::Jpeg { components, inverted: inverted && components == 4 };
+            return Ok((kind, (width, height)));
+        }
+        at += 2 + length;
+    }
+}

data/ext/imprimatur_native/core/src/doc/table.rs

@@ -1,5 +1,12 @@
+use crate::script::Counts;
+use crate::style::TextDirection;
+
 /// A grid of text cells; columns share the page width equally. Short rows
 /// are padded with empty cells.
+///
+/// Each cell reads in the direction of its first letter, a cell of figures
+/// in the table's; a table mostly right to left has its first column on the
+/// right.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Table {
     pub(crate) rows: Vec<Vec<String>>,
@@ -38,4 +45,18 @@ impl Table {
     pub(crate) const fn has_header(&self) -> bool {
         self.header
     }
+
+    /// The direction most of the table's letters read in; `None` without a
+    /// letter.
+    pub(crate) fn direction(&self) -> Option<TextDirection> {
+        let mut counts = Counts::default();
+        self.count(&mut counts);
+        counts.direction()
+    }
+
+    pub(crate) fn count(&self, counts: &mut Counts) {
+        for cell in self.rows.iter().flatten() {
+            counts.add(cell);
+        }
+    }
 }

data/ext/imprimatur_native/core/src/doc.rs

@@ -22,6 +22,7 @@
 //! ```
 
 mod paragraph;
+pub(crate) mod picture;
 mod table;
 #[cfg(test)]
 mod tests;
@@ -31,24 +32,49 @@ use std::io::{BufWriter, Write};
 use std::path::Path;
 
 pub use paragraph::{Paragraph, Run};
+pub use picture::Picture;
 pub use table::Table;
 
+use crate::script::Counts;
 use crate::{Error, Result};
 
-/// Paper size; pages are portrait.
+/// Paper size; A4 and Letter pages are portrait.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub enum PageSize {
     #[default]
     A4,
     Letter,
+    /// Width and height in hundredths of a point; see [`PageSize::custom`].
+    Custom(u32, u32),
 }
 
 impl PageSize {
+    /// A page of this width and height, in points (1/72 inch): 36 to 1584
+    /// (half an inch to 22 inches), as both PDF and Word take them.
+    ///
+    /// # Errors
+    /// [`Error::InvalidPageSize`] outside that range.
+    pub fn custom(width: f64, height: f64) -> Result<Self> {
+        let side = |points: f64| {
+            #[expect(
+                clippy::cast_possible_truncation,
+                clippy::cast_sign_loss,
+                reason = "36 to 1584"
+            )]
+            (36.0..=1584.0).contains(&points).then(|| (points * 100.0).round() as u32)
+        };
+        side(width)
+            .zip(side(height))
+            .map(|(width, height)| Self::Custom(width, height))
+            .ok_or(Error::InvalidPageSize(width, height))
+    }
+
     /// Width and height in PDF points (1/72 inch).
-    pub(crate) const fn points(self) -> (f64, f64) {
+    pub(crate) fn points(self) -> (f64, f64) {
         match self {
             Self::A4 => (595.276, 841.89),
             Self::Letter => (612.0, 792.0),
+            Self::Custom(width, height) => (f64::from(width) / 100.0, f64::from(height) / 100.0),
         }
     }
 
@@ -57,6 +83,7 @@ impl PageSize {
         match self {
             Self::A4 => (11_906, 16_838),
             Self::Letter => (12_240, 15_840),
+            Self::Custom(width, height) => (width / 5, height / 5),
         }
     }
 }
@@ -68,6 +95,7 @@ pub enum Block {
     Heading { level: u8, text: String },
     Paragraph(Paragraph),
     Table(Table),
+    Picture(Picture),
     PageBreak,
 }
 
@@ -78,6 +106,8 @@ pub struct Document {
     blocks: Vec<Block>,
     page_size: PageSize,
     page_numbers: bool,
+    /// Hundredths of a point; one inch when unset.
+    margin: Option<u32>,
 }
 
 impl Document {
@@ -91,6 +121,43 @@ impl Document {
         self
     }
 
+    /// The margin on every side, in points: one inch (72) unless set.
+    ///
+    /// # Errors
+    /// [`Error::InvalidMargin`] outside 0 to 144 points.
+    pub fn set_margin(&mut self, points: f64) -> Result<&mut Self> {
+        #[expect(clippy::cast_possible_truncation, clippy::cast_sign_loss, reason = "0 to 144")]
+        let margin = (0.0..=144.0)
+            .contains(&points)
+            .then(|| (points * 100.0).round() as u32)
+            .ok_or(Error::InvalidMargin(points))?;
+        self.margin = Some(margin);
+        Ok(self)
+    }
+
+    /// The margin on every side, in points.
+    #[must_use]
+    pub fn margin(&self) -> f64 {
+        self.margin.map_or(72.0, |margin| f64::from(margin) / 100.0)
+    }
+
+    /// The width and height between the margins, in points.
+    ///
+    /// # Errors
+    /// [`Error::InvalidMargin`] when the margins leave no room.
+    pub(crate) fn room(&self) -> Result<(f64, f64)> {
+        let (width, height) = self.page_size.points();
+        let margin = self.margin();
+        let room = (2.0f64.mul_add(-margin, width), 2.0f64.mul_add(-margin, height));
+        (room.0 >= 1.0 && room.1 >= 1.0).then_some(room).ok_or(Error::InvalidMargin(margin))
+    }
+
+    /// A picture, in the flow of the text.
+    pub fn picture(&mut self, picture: Picture) -> &mut Self {
+        self.blocks.push(Block::Picture(picture));
+        self
+    }
+
     /// Numbers pages `1 / 3` at the bottom of each one.
     pub const fn set_page_numbers(&mut self, enabled: bool) -> &mut Self {
         self.page_numbers = enabled;
@@ -144,6 +211,23 @@ impl Document {
         self
     }
 
+    /// Whether most of the document's letters are right to left: its pages
+    /// are then laid out right to left.
+    pub(crate) fn reads_right_to_left(&self) -> bool {
+        let mut counts = Counts::default();
+        for block in &self.blocks {
+            match block {
+                Block::Heading { text, .. } => counts.add(text),
+                Block::Paragraph(paragraph) => {
+                    paragraph.runs.iter().for_each(|run| counts.add(&run.text));
+                }
+                Block::Table(table) => table.count(&mut counts),
+                Block::Picture(_) | Block::PageBreak => {}
+            }
+        }
+        counts.right_to_left()
+    }
+
     #[must_use]
     pub fn blocks(&self) -> &[Block] {
         &self.blocks