imprimatur 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b79ecca5f76986eb4049090056dcee55fe7b8d2aafa1115de48ea2f45b0e12ef
-  data.tar.gz: 925d5c93f99da882db19b562c749ba41c1ae17a5fd01d17b66bd9be93a9dc15a
+  metadata.gz: 7c343d074a7ed5e2ba382910345401adaaa92269eb915c901db443d97ed6f68a
+  data.tar.gz: 00cfe2c403d09f50708469c6228813f8ab9361775b848ac23457389008e643ab
 SHA512:
-  metadata.gz: e28f3c9640d20df215ed94a94195fcea8a28336f1ddc1d5a923355e09fdc68142517b92147c3b76dc089b68294c8aa4b4edde1a832fc613fb44612d92e4773ba
-  data.tar.gz: c7f0d6f08c5f9349574e03c3ec025c82f737afdeb5e4e8c6994bf7afe0c5a7fa7091e418495691346f43b987a7abd7451d6eeca207b87dd911a523508039ac3a
+  metadata.gz: e003c94d4f867c4d957a7921a8ef50eb36f0393196535064bfab45cfead076f881a39dbbc7d2e73aa15487e57046a18ea3df1483f8b493f926a8d6e362e6ee7c
+  data.tar.gz: ac5657121fd5b657880fee907b3a4508087aff20a15ad057b1d43254796d767e908eec39952ac44a0aa65f814a55d36db8c9b56119effe647d8ea018bcb2e6b4

data/CHANGELOG.md

@@ -11,6 +11,32 @@
 - Allow a bounded exit grace when macOS cannot inspect an exiting worker;
   persistent monitor failures still terminate and reap a live worker.
 
+## [0.8.0](https://github.com/seuros/imprimatur/compare/v0.7.0...v0.8.0) (2026-10-27)
+
+
+### Features
+
+* **reader:** accept drop_repeated in the Ruby API ([4e537d6](https://github.com/seuros/imprimatur/commit/4e537d641bafd8d3cdb8b1c20d16f4cb766ad073))
+
+
+### Bug Fixes
+
+* **pdf:** read printed page numbers from headers too, not just footers ([c036434](https://github.com/seuros/imprimatur/commit/c0364341ee8fc36be2c97d25fd06da0aa76a4ad6))
+
+## [0.7.0](https://github.com/seuros/imprimatur/compare/v0.6.1...v0.7.0) (2026-10-26)
+
+
+### Features
+
+* **pdf:** add --drop-repeated to remove watermarks anywhere on the page ([8ea82c9](https://github.com/seuros/imprimatur/commit/8ea82c98f6b507ff7ffd296f8e0ec8f30aed529f))
+* **pdf:** emit printed page labels from /PageLabels or footer text ([f761555](https://github.com/seuros/imprimatur/commit/f76155578acfc8514465b93b5b019df100d54de7))
+* **pdf:** recognize numbered sections as headings in markdown output ([341f651](https://github.com/seuros/imprimatur/commit/341f651631b74ff93879f9eba71d0874ae261fd1))
+
+
+### Bug Fixes
+
+* **pdf:** keep ordinal superscripts attached to their base text ([21fbb51](https://github.com/seuros/imprimatur/commit/21fbb510f90ab7c029d22e4e396b887fa66e16c6))
+
 ## [0.6.1](https://github.com/seuros/imprimatur/compare/v0.6.0...v0.6.1) (2026-10-25)
 
 

data/Cargo.lock

@@ -513,7 +513,7 @@ dependencies = [
 
 [[package]]
 name = "imprimatur"
-version = "0.6.1"
+version = "0.8.0"
 dependencies = [
  "aes",
  "crc32fast",
@@ -536,7 +536,7 @@ dependencies = [
 
 [[package]]
 name = "imprimatur-cli"
-version = "0.6.1"
+version = "0.8.0"
 dependencies = [
  "imprimatur",
  "regex",
@@ -548,7 +548,7 @@ dependencies = [
 
 [[package]]
 name = "imprimatur_native"
-version = "0.6.1"
+version = "0.8.0"
 dependencies = [
  "imprimatur",
  "magnus",

data/Cargo.toml

@@ -15,7 +15,7 @@ crc32fast = "1.5.2"
 datamatrix = "0.3.3"
 font-test-data = "0.10.0"
 hayro = { version = "0.8.0", default-features = false, features = ["embed-fonts", "embed-cmaps"] }
-imprimatur = { path = "ext/imprimatur_native/core", version = "0.6.1" }
+imprimatur = { path = "ext/imprimatur_native/core", version = "0.8.0" }
 libproc = "0.14.11"
 magnus = { version = "0.9.2", default-features = false }
 md-5 = "0.11.0"

data/README.md

@@ -32,7 +32,7 @@ end
 gem "imprimatur"
 ```
 
-Precompiled gems ship for Linux (x86_64 and aarch64, glibc 2.34+ and musl),
+Precompiled gems ship for Linux (x86_64 and aarch64, glibc 2.34+),
 macOS 13+ (arm64, x86_64) and FreeBSD 15.1 (amd64): nothing to compile.
 Anywhere else, the source gem compiles the extension on install, with the
 toolchain from [rustup.rs](https://rustup.rs) (1.99+).

data/ext/imprimatur_native/cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "imprimatur-cli"
-version = "0.6.1"
+version = "0.8.0"
 description = "Read PDF, XLSX, XLS, ODS and DOCX documents as Markdown or JSON, search them, extract their images."
 keywords = ["pdf", "xlsx", "docx", "markdown", "cli"]
 categories = ["command-line-utilities", "text-processing"]

data/ext/imprimatur_native/cli/src/cli/markdown.rs

@@ -15,9 +15,12 @@ use crate::app::{self, App, Out, Status};
 ///
 /// PDF: the text layer, placed glyph by glyph, with headings by font size,
 /// running headers and footers left out, and pages after the first marked
-/// `<!-- page N -->`. Encrypted PDFs open when their user password is
-/// empty. XLSX, XLS and ODS: each sheet as a table, values as shown, then
-/// its comments. DOCX: headings, lists, emphasis, links and tables.
+/// `<!-- page N -->` (or `<!-- page N (label L) -->` with its printed page
+/// label, from `/PageLabels` or a header or footer line that looks like
+/// one). Encrypted
+/// PDFs open when their user password is empty. XLSX, XLS and ODS: each
+/// sheet as a table, values as shown, then its comments. DOCX: headings,
+/// lists, emphasis, links and tables.
 ///
 /// With several documents, each is introduced by `<!-- file: PATH -->`. A
 /// document that fails is reported on standard error and the others are
@@ -29,6 +32,10 @@ use crate::app::{self, App, Out, Status};
 /// (number, date, bool, text, error, formula) and comments; a Word
 /// document's blocks (heading, paragraph, list item, table) with the byte
 /// ranges of their bold, italic and linked text.
+///
+/// With `--drop-repeated` on a PDF, text that sits at the same spot on most
+/// pages is dropped wherever it falls, not only in the top and bottom
+/// margins: diagonal or rotated watermark stamps included. Off by default.
 #[derive(Args, Debug)]
 #[usage(
     effect = "read",
@@ -38,7 +45,8 @@ use crate::app::{self, App, Out, Status};
     example("imprimatur markdown audit.pdf", help = "Print a PDF's text"),
     example("imprimatur md -o notes/ *.docx", help = "Write notes/NAME.md for each"),
     example("curl -s $URL | imprimatur md -", help = "Read standard input"),
-    example("imprimatur --json md sales.xlsx", help = "Typed cells, as JSON")
+    example("imprimatur --json md sales.xlsx", help = "Typed cells, as JSON"),
+    example("imprimatur md --drop-repeated stamped.pdf", help = "Drop a repeated watermark")
 )]
 pub struct Markdown {
     /// Documents to read; `-` reads standard input
@@ -49,6 +57,11 @@ pub struct Markdown {
     #[usage(short = 'o', long, value_name = "DIR", value_hint = usage_rs::ValueHint::DirPath)]
     pub output: Option<PathBuf>,
 
+    /// PDF: drop text repeated at the same spot on most pages, anywhere on
+    /// the page (watermarks); off by default
+    #[usage(long)]
+    pub drop_repeated: bool,
+
     #[usage(flatten)]
     pub limits: LimitFlags,
 }
@@ -58,7 +71,7 @@ impl RunWith<&App> for Markdown {
 
     fn run_with(self, app: &App) -> ExitCode {
         let limits = match self.limits.checked() {
-            Ok(limits) => limits,
+            Ok(limits) => limits.drop_repeated(self.drop_repeated),
             Err(status) => return status,
         };
         if let Some(directory) = &self.output

data/ext/imprimatur_native/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "imprimatur"
-version = "0.6.1"
+version = "0.8.0"
 description = "XLSX, PDF and DOCX authoring, and PDF, XLSX, XLS, ODS and DOCX reading, with its own XML, zip and PDF code."
 keywords = ["xlsx", "excel", "pdf", "docx", "spreadsheet"]
 categories = ["encoding", "text-processing"]

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

@@ -28,6 +28,7 @@ pub struct Limits {
     pub(crate) max_depth: usize,
     pub(crate) timeout: Option<Duration>,
     pub(crate) cancel: Option<Arc<AtomicBool>>,
+    pub(crate) drop_repeated: bool,
 }
 
 impl Default for Limits {
@@ -38,6 +39,7 @@ impl Default for Limits {
             max_depth: 256,
             timeout: Some(Duration::from_mins(1)),
             cancel: None,
+            drop_repeated: false,
         }
     }
 }
@@ -79,6 +81,15 @@ impl Limits {
         self.cancel = Some(flag);
         self
     }
+
+    /// For a PDF: drop text that repeats at the same spot on most pages
+    /// anywhere on the page, not only in the top and bottom margins. Off by
+    /// default.
+    #[must_use]
+    pub const fn drop_repeated(mut self, drop: bool) -> Self {
+        self.drop_repeated = drop;
+        self
+    }
 }
 
 /// One read's consumption. Single-threaded: a read runs on one thread.
@@ -100,6 +111,10 @@ impl<'a> Budget<'a> {
         self.limits.max_depth
     }
 
+    pub const fn drop_repeated(&self) -> bool {
+        self.limits.drop_repeated
+    }
+
     /// Decompressed bytes still allowed.
     pub fn inflatable(&self) -> usize {
         let left = self.limits.max_inflated.saturating_sub(self.inflated.get());

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

@@ -72,6 +72,7 @@ pub struct Page {
     pub number: u32,
     pub blocks: Vec<Placed>,
     pub images: u32,
+    pub label: Option<String>,
 }
 
 /// A block and where it lies on its page.

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

@@ -55,7 +55,7 @@ fn page(page: &Page) -> Json {
             object
         })
         .collect();
-    json!({ "page": page.number, "images": page.images, "blocks": blocks })
+    json!({ "page": page.number, "label": page.label, "images": page.images, "blocks": blocks })
 }
 
 /// An image's description, its data left out: `format`, `width`, `height`,

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

@@ -44,11 +44,21 @@ pub enum Mode {
 }
 
 fn pdf(out: &mut String, pages: &[Page]) {
-    for page in pages.iter().filter(|page| !page.blocks.is_empty()) {
+    // Every page past the first gets its marker, blocks or none: an empty
+    // page (left bare by `--drop-repeated`, or genuinely blank) still needs
+    // one, so the markers stay a reliable page count and index.
+    for page in pages {
         if page.number > 1 {
             end_block(out);
             // Writing to a String cannot fail.
-            let _ = writeln!(out, "<!-- page {} -->", page.number);
+            match &page.label {
+                Some(label) => {
+                    let _ = writeln!(out, "<!-- page {} (label {label}) -->", page.number);
+                }
+                None => {
+                    let _ = writeln!(out, "<!-- page {} -->", page.number);
+                }
+            }
         }
         write_blocks(out, page.blocks.iter().map(|placed| &placed.block), Mode::Body);
     }

data/ext/imprimatur_native/core/src/read/pdf/document/labels.rs

@@ -0,0 +1,152 @@
+use std::collections::HashSet;
+
+use super::{Dict, Document, Object, Result};
+
+struct LabelRange {
+    start: u32,
+    style: Option<u8>,
+    prefix: Option<String>,
+    first: i64,
+}
+
+const ROMAN: &[(i64, &str)] = &[
+    (1000, "M"),
+    (900, "CM"),
+    (500, "D"),
+    (400, "CD"),
+    (100, "C"),
+    (90, "XC"),
+    (50, "L"),
+    (40, "XL"),
+    (10, "X"),
+    (9, "IX"),
+    (5, "V"),
+    (4, "IV"),
+    (1, "I"),
+];
+
+impl Document<'_> {
+    pub fn page_labels(&self, count: usize) -> Result<Option<Vec<Option<String>>>> {
+        let Some(ranges) = self.label_ranges()? else { return Ok(None) };
+        Ok(Some(
+            (0..count)
+                .map(|index| label_for(&ranges, u32::try_from(index).unwrap_or(u32::MAX)))
+                .collect(),
+        ))
+    }
+
+    fn label_ranges(&self) -> Result<Option<Vec<LabelRange>>> {
+        let Some(root) = self.trailer().get(b"Root") else { return Ok(None) };
+        let root = self.resolve(root)?;
+        let Some(catalog) = root.as_dict() else { return Ok(None) };
+        let Some(tree) = catalog.get(b"PageLabels") else { return Ok(None) };
+        let mut ranges = Vec::new();
+        self.walk_labels(tree, 0, &mut HashSet::new(), &mut ranges)?;
+        ranges.sort_by_key(|range| range.start);
+        ranges.dedup_by_key(|range| range.start);
+        Ok(Some(ranges))
+    }
+
+    fn walk_labels(
+        &self,
+        node: &Object,
+        depth: usize,
+        visited: &mut HashSet<u32>,
+        out: &mut Vec<LabelRange>,
+    ) -> Result<()> {
+        self.budget.check()?;
+        self.budget.nest(depth)?;
+        if let Some((number, _)) = node.as_reference()
+            && !visited.insert(number)
+        {
+            return Ok(());
+        }
+        let node = self.resolve(node)?;
+        let Some(dict) = node.as_dict() else { return Ok(()) };
+        if let Some(Object::Array(nums)) = self.entry(dict, b"Nums")?.as_deref() {
+            let mut nums = nums.iter();
+            while let (Some(start), Some(value)) = (nums.next(), nums.next()) {
+                let Some(start) =
+                    self.resolve(start)?.as_integer().and_then(|start| u32::try_from(start).ok())
+                else {
+                    continue;
+                };
+                let value = self.resolve(value)?;
+                if let Some(label) = value.as_dict() {
+                    out.push(self.label_range(start, label)?);
+                }
+            }
+        }
+        if let Some(Object::Array(kids)) = self.entry(dict, b"Kids")?.as_deref() {
+            for kid in kids {
+                self.walk_labels(kid, depth + 1, visited, out)?;
+            }
+        }
+        Ok(())
+    }
+
+    fn label_range(&self, start: u32, dict: &Dict) -> Result<LabelRange> {
+        let style = self
+            .entry(dict, b"S")?
+            .as_deref()
+            .and_then(Object::as_name)
+            .and_then(|name| name.first().copied());
+        let prefix = self
+            .entry(dict, b"P")?
+            .as_deref()
+            .and_then(Object::as_bytes)
+            .map(|bytes| String::from_utf8_lossy(bytes).into_owned());
+        let first = self.entry(dict, b"St")?.as_deref().and_then(Object::as_integer).unwrap_or(1);
+        Ok(LabelRange { start, style, prefix, first })
+    }
+}
+
+fn label_for(ranges: &[LabelRange], index: u32) -> Option<String> {
+    let range = ranges.iter().rev().find(|range| range.start <= index)?;
+    let offset = i64::from(index - range.start);
+    let number = range.first.checked_add(offset)?;
+    let mut label = range.prefix.clone().unwrap_or_default();
+    if let Some(style) = range.style {
+        label.push_str(&numeral(style, number));
+    }
+    Some(label)
+}
+
+fn numeral(style: u8, number: i64) -> String {
+    match style {
+        b'R' => roman(number, true),
+        b'r' => roman(number, false),
+        b'A' => alpha(number, true),
+        b'a' => alpha(number, false),
+        _ => number.to_string(),
+    }
+}
+
+fn roman(number: i64, upper: bool) -> String {
+    if number < 1 {
+        return number.to_string();
+    }
+    let mut remaining = number;
+    let mut out = String::new();
+    for &(value, symbol) in ROMAN {
+        while remaining >= value {
+            out.push_str(symbol);
+            remaining -= value;
+        }
+    }
+    if upper { out } else { out.to_ascii_lowercase() }
+}
+
+fn alpha(number: i64, upper: bool) -> String {
+    if number < 1 {
+        return String::new();
+    }
+    let zero_based = number - 1;
+    let letter = u8::try_from(zero_based % 26).unwrap_or(0);
+    let repeat = usize::try_from(zero_based / 26 + 1).unwrap_or(1);
+    let letter = if upper { b'A' + letter } else { b'a' + letter };
+    std::iter::repeat_n(char::from(letter), repeat).collect()
+}
+
+#[cfg(test)]
+mod tests;

data/ext/imprimatur_native/core/src/read/pdf/document.rs

@@ -1,6 +1,7 @@
 //! A PDF file's objects on demand: loaded once and shared, decrypted, and
 //! their streams decoded; then the pages, with what they inherit.
 
+mod labels;
 mod pages;
 
 use std::borrow::Cow;

data/ext/imprimatur_native/core/src/read/pdf/layout.rs

@@ -20,6 +20,7 @@ use crate::script::Counts;
 const EDGE: f64 = 0.09;
 /// A gap wider than this share of the font size separates words.
 const WORD_GAP: f64 = 0.18;
+const POSITION_BUCKET: f64 = 3.0;
 
 /// A line of a page, its text a span of the page's buffer.
 #[derive(Debug, Clone)]
@@ -36,6 +37,9 @@ pub struct Line {
     /// In the top or bottom margin of an upright page: a hash of the text,
     /// digits aside, to spot running headers and footers. 0 elsewhere.
     pub margin: u64,
+    /// A hash of the text and its bucketed position and direction, to spot
+    /// anything else that repeats at the same spot on most pages.
+    pub repeat: u64,
 }
 
 /// A page's lines and their text (one buffer for all of them), its height
@@ -82,14 +86,9 @@ pub fn lines(page: &PageText) -> PageLines {
         glyphs.sort_by(|a, b| b.1.total_cmp(&a.1).then(a.0.total_cmp(&b.0)));
         let mut start = 0;
         while start < glyphs.len() {
-            let (_, baseline, first) = glyphs[start];
-            let mut end = start + 1;
-            while end < glyphs.len() {
-                let (_, y, glyph) = glyphs[end];
-                if (baseline - y).abs() > 0.45 * first.size.max(glyph.size) {
-                    break;
-                }
-                end += 1;
+            let mut end = row_end(&glyphs, start);
+            if let Some(merged) = attach_superscript(&glyphs, start, end) {
+                end = merged;
             }
             let row = &mut glyphs[start..end];
             row.sort_by(|a, b| a.0.total_cmp(&b.0));
@@ -108,6 +107,54 @@ pub fn lines(page: &PageText) -> PageLines {
     out
 }
 
+fn row_end(glyphs: &[(f64, f64, &Glyph)], start: usize) -> usize {
+    let (_, baseline, first) = glyphs[start];
+    let mut end = start + 1;
+    while end < glyphs.len() {
+        let (_, y, glyph) = glyphs[end];
+        if (baseline - y).abs() > 0.45 * first.size.max(glyph.size) {
+            break;
+        }
+        end += 1;
+    }
+    end
+}
+
+const SUPERSCRIPT_GLYPHS: usize = 3;
+const SUPERSCRIPT_SIZE_RATIO: f64 = 0.85;
+
+fn attach_superscript(glyphs: &[(f64, f64, &Glyph)], start: usize, end: usize) -> Option<usize> {
+    if end - start > SUPERSCRIPT_GLYPHS || end >= glyphs.len() {
+        return None;
+    }
+    let row = &glyphs[start..end];
+    let (_, baseline, _) = glyphs[start];
+    let (next_x, next_y, next) = glyphs[end];
+    let base_size = next.size;
+    let candidate_size = row.iter().map(|&(_, _, glyph)| glyph.size).fold(0.0, f64::max);
+    let raised = baseline - next_y;
+    if raised <= 0.0 || raised > base_size.max(candidate_size) {
+        return None;
+    }
+    if row.iter().any(|&(_, _, glyph)| glyph.size > SUPERSCRIPT_SIZE_RATIO * base_size) {
+        return None;
+    }
+    let row_left = row.iter().map(|&(x, _, _)| x).fold(f64::MAX, f64::min);
+    let row_right = row.iter().map(|&(x, _, glyph)| x + glyph.width).fold(f64::MIN, f64::max);
+    let next_right = next_x + next.width;
+    let gap = if row_left >= next_right {
+        row_left - next_right
+    } else if next_x >= row_right {
+        next_x - row_right
+    } else {
+        return None;
+    };
+    if gap > WORD_GAP * base_size.max(1.0) {
+        return None;
+    }
+    Some(row_end(glyphs, end))
+}
+
 /// Whether a page reads right to left: more of its letters, those in the
 /// top and bottom margins of upright text aside, are right to left.
 fn right_to_left(page: &PageText) -> bool {
@@ -179,7 +226,9 @@ fn line<'p>(
     let (left, y, _) = row[0];
     let span = span::end(&out.text[..start])..span::end(&out.text);
     let bold = bold * 2 > count;
-    out.lines.push(Line { span, y, left, right, size, bold, turns, margin: 0 });
+    let text = span::slice(&out.text, &span);
+    let repeat = repeat_key(text, left, y, turns);
+    out.lines.push(Line { span, y, left, right, size, bold, turns, margin: 0, repeat });
 }
 
 /// A hash of a line's text with digits as `#` and ASCII letters lowercased
@@ -192,18 +241,39 @@ fn margin_key(text: &str) -> u64 {
     hash.max(1)
 }
 
+#[expect(clippy::cast_possible_truncation, reason = "page coordinates fit in i64")]
+fn repeat_key(text: &str, left: f64, y: f64, turns: u8) -> u64 {
+    let bucket = |value: f64| (value / POSITION_BUCKET).round() as i64;
+    let mut hash = margin_key(text);
+    for part in [u64::from(turns), bucket(left).cast_unsigned(), bucket(y).cast_unsigned()] {
+        hash = (hash ^ part).wrapping_mul(0x0100_0000_01b3);
+    }
+    hash.max(1)
+}
+
 /// The document's pages, from their lines: blocks of the lines that are
-/// not running headers or footers.
-pub fn pages(pages: &[PageLines]) -> Vec<Page> {
-    let boilerplate = running_lines(pages);
-    let kept = |line: &&Line| line.margin == 0 || boilerplate.binary_search(&line.margin).is_err();
-    let body = body_size(pages, &kept);
-    let levels = heading_sizes(pages, &kept, body);
+/// not running headers or footers, and, with `drop_repeated_anywhere`, not
+/// text repeated at the same spot on most pages anywhere on the page.
+pub fn pages(
+    pages: &[PageLines],
+    labels: Option<&[Option<String>]>,
+    drop_repeated_anywhere: bool,
+) -> Vec<Page> {
+    let boilerplate = repeated_keys(pages, |line| line.margin);
+    let margin_kept =
+        |line: &&Line| line.margin == 0 || boilerplate.binary_search(&line.margin).is_err();
+    let repeated =
+        if drop_repeated_anywhere { repeated_keys(pages, |line| line.repeat) } else { Vec::new() };
+    let kept = |line: &&Line| {
+        margin_kept(line) && (repeated.is_empty() || repeated.binary_search(&line.repeat).is_err())
+    };
+    let body = body_size(pages, &margin_kept);
+    let levels = heading_sizes(pages, &margin_kept, body);
     let mut out = Vec::with_capacity(pages.len());
     let mut paragraph: Vec<&Line> = Vec::new();
     // Each page's blocks, collected here, then moved out at their size.
     let mut blocks = Vec::new();
-    for (number, page) in (1..).zip(pages) {
+    for (index, (number, page)) in (1..).zip(pages).enumerate() {
         paragraph.clear();
         for line in page.lines.iter().filter(kept) {
             if let Some(last) = paragraph.last()
@@ -223,11 +293,53 @@ pub fn pages(pages: &[PageLines]) -> Vec<Page> {
             reason = "`blocks` keeps its buffer for the next page"
         )]
         let blocks = blocks.drain(..).collect();
-        out.push(Page { number, blocks, images: page.images });
+        let label = labels
+            .map_or_else(|| printed_label(page), |labels| labels.get(index).cloned().flatten());
+        out.push(Page { number, blocks, images: page.images, label });
     }
     out
 }
 
+/// The page's own printed label, from a single header or footer line that
+/// looks like one: a bare page number or roman numeral ("`-i-`", "`7`"), or
+/// the same after a short label word ("`Page 70`" -> "`70`"). Unlike the
+/// boilerplate this document's other margin lines are checked against, a
+/// running "`Page 70`", "`Page 71`", ... header is not noise here: each
+/// instance *is* that page's label, not a repeated line to drop.
+fn printed_label(page: &PageLines) -> Option<String> {
+    let mut candidates =
+        page.lines.iter().filter(|line: &&Line| line.margin != 0).filter_map(|line| {
+            let text = page.text(line).trim();
+            page_number_label(text)
+        });
+    let label = candidates.next()?;
+    candidates.next().is_none().then_some(label)
+}
+
+/// `text` as a page label, if it looks like one, stripped of a leading
+/// label word such as "Page" when there is one.
+fn page_number_label(text: &str) -> Option<String> {
+    if looks_like_page_number(text) {
+        return Some(text.to_owned());
+    }
+    let word_end = text.find(|ch: char| !ch.is_ascii_alphabetic())?;
+    if word_end == 0 {
+        return None;
+    }
+    let rest = text[word_end..].trim_start_matches(|ch: char| !ch.is_alphanumeric());
+    looks_like_page_number(rest).then(|| rest.to_owned())
+}
+
+fn looks_like_page_number(text: &str) -> bool {
+    let core = text.trim_matches(|ch: char| !ch.is_alphanumeric());
+    !core.is_empty()
+        && core.len() <= 8
+        && (core.chars().all(|ch| ch.is_ascii_digit())
+            || core.chars().all(|ch| {
+                matches!(ch.to_ascii_lowercase(), 'i' | 'v' | 'x' | 'l' | 'c' | 'd' | 'm')
+            }))
+}
+
 /// Whether `next` carries on the paragraph `last` is in: same direction,
 /// similar size, and no more than a line and a half below it.
 fn continues(last: &Line, next: &Line) -> bool {
@@ -245,41 +357,79 @@ fn continues(last: &Line, next: &Line) -> bool {
 fn block(page: &PageLines, lines: &[&Line], body: f64, levels: &[f64]) -> Placed {
     let first = lines[0];
     let length: usize = lines.iter().map(|line| line.span.len()).sum();
-    let level = if lines.len() <= 3 && length <= 200 {
-        levels.iter().position(|&size| first.size >= size - 0.25)
-    } else {
-        None
+    let short = lines.len() <= 3 && length <= 200;
+    let text = paragraph_text(page, lines);
+    let level =
+        if short { levels.iter().position(|&size| first.size >= size - 0.25) } else { None };
+    let sized = level
+        .filter(|_| first.size >= body * 1.15)
+        .map(|level| u8::try_from(level.min(2) + 1).unwrap_or(3));
+    let numbered = (short && first.bold && first.size >= body - 0.25)
+        .then(|| numbered_heading_level(&text))
+        .flatten();
+    let block = match sized.or(numbered) {
+        Some(level) => Block::Heading { level, text: Text::plain(text) },
+        None => Block::Paragraph { text: Text::plain(text) },
     };
+    Placed { block, bounds: bounds(page, lines) }
+}
+
+fn paragraph_text(page: &PageLines, lines: &[&Line]) -> String {
+    let length: usize = lines.iter().map(|line| line.span.len()).sum();
     let mut text = String::with_capacity(length + lines.len());
-    let block = if let Some(level) = level.filter(|_| first.size >= body * 1.15) {
-        for (index, line) in lines.iter().enumerate() {
-            if index > 0 {
-                text.push(' ');
+    for (index, line) in lines.iter().enumerate() {
+        let line = page.text(line);
+        if index > 0 {
+            let joined = text.ends_with('-') && {
+                let mut before = text.chars().rev().skip(1);
+                before.next().is_some_and(char::is_lowercase)
+                    && line.chars().next().is_some_and(char::is_lowercase)
+            };
+            if joined {
+                text.pop();
+            } else {
+                text.push('\n');
             }
-            text.push_str(page.text(line));
         }
-        let level = u8::try_from(level.min(2) + 1).unwrap_or(3);
-        Block::Heading { level, text: Text::plain(text) }
-    } else {
-        for (index, line) in lines.iter().enumerate() {
-            let line = page.text(line);
-            if index > 0 {
-                let joined = text.ends_with('-') && {
-                    let mut before = text.chars().rev().skip(1);
-                    before.next().is_some_and(char::is_lowercase)
-                        && line.chars().next().is_some_and(char::is_lowercase)
-                };
-                if joined {
-                    text.pop();
-                } else {
-                    text.push('\n');
-                }
-            }
-            text.push_str(line);
+        text.push_str(line);
+    }
+    text
+}
+
+fn numbered_heading_level(text: &str) -> Option<u8> {
+    let (depth, rest) = numbered_prefix(text)?;
+    if depth < 2 || !(rest.is_empty() || rest.starts_with(' ')) {
+        return None;
+    }
+    let title = rest.trim_start();
+    if title.contains("....") || title.starts_with(|ch: char| !ch.is_alphanumeric()) {
+        return None;
+    }
+    Some(u8::try_from(depth).unwrap_or(6).min(6))
+}
+
+fn numbered_prefix(text: &str) -> Option<(usize, &str)> {
+    let bytes = text.as_bytes();
+    let mut groups = 0_usize;
+    let mut pos = 0_usize;
+    loop {
+        let start = pos;
+        while bytes.get(pos).is_some_and(u8::is_ascii_digit) {
+            pos += 1;
         }
-        Block::Paragraph { text: Text::plain(text) }
-    };
-    Placed { block, bounds: bounds(page, lines) }
+        if pos == start {
+            break;
+        }
+        groups += 1;
+        if groups >= 4
+            || bytes.get(pos) != Some(&b'.')
+            || !bytes.get(pos + 1).is_some_and(u8::is_ascii_digit)
+        {
+            break;
+        }
+        pos += 1;
+    }
+    (groups > 0).then(|| (groups, &text[pos..]))
 }
 
 /// Where upright lines lie on the page, from its top-left corner: from the
@@ -296,9 +446,9 @@ fn bounds(page: &PageLines, lines: &[&Line]) -> Option<Bounds> {
     Some(Bounds { left, top, right, bottom })
 }
 
-/// Text that repeats in the margins of many pages (page numbers, running
-/// titles), digits aside: their margin keys, sorted.
-fn running_lines(pages: &[PageLines]) -> Vec<u64> {
+/// The keys `key` returns for lines that repeat on enough pages to be
+/// boilerplate rather than coincidence, sorted.
+fn repeated_keys(pages: &[PageLines], key: impl Fn(&Line) -> u64) -> Vec<u64> {
     if pages.len() < 3 {
         return Vec::new();
     }
@@ -306,7 +456,7 @@ fn running_lines(pages: &[PageLines]) -> Vec<u64> {
     let mut seen: Vec<u64> = Vec::new();
     for page in pages {
         seen.clear();
-        seen.extend(page.lines.iter().map(|line| line.margin).filter(|&key| key != 0));
+        seen.extend(page.lines.iter().map(&key).filter(|&key| key != 0));
         seen.sort_unstable();
         seen.dedup();
         for &key in &seen {
@@ -314,10 +464,10 @@ fn running_lines(pages: &[PageLines]) -> Vec<u64> {
         }
     }
     let threshold = (pages.len() * 2 / 5).max(3);
-    let mut running: Vec<u64> =
+    let mut repeated: Vec<u64> =
         counts.into_iter().filter(|&(_, count)| count >= threshold).map(|(key, _)| key).collect();
-    running.sort_unstable();
-    running
+    repeated.sort_unstable();
+    repeated
 }
 
 /// Every page's lines that `kept` keeps.

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

@@ -57,5 +57,6 @@ pub(super) fn content(data: &[u8], budget: &Budget<'_>) -> Result<Vec<Page>> {
             Err(_) => lines.push(layout::PageLines::default()),
         }
     }
-    Ok(layout::pages(&lines))
+    let labels = document.page_labels(lines.len())?;
+    Ok(layout::pages(&lines, labels.as_deref(), budget.drop_repeated()))
 }

data/ext/imprimatur_native/ffi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "imprimatur_native"
-version = "0.6.1"
+version = "0.8.0"
 description = "Ruby bindings for the imprimatur crate"
 publish = false
 edition.workspace = true

data/ext/imprimatur_native/ffi/src/lib.rs

@@ -323,13 +323,13 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     barcode::define(ruby, imprimatur)?;
 
     let native = imprimatur.define_module("Native")?;
-    native.define_singleton_method("markdown", function!(read::markdown_native, 4))?;
-    native.define_singleton_method("content", function!(read::content_native, 5))?;
-    native.define_singleton_method("images", function!(read::images_native, 4))?;
+    native.define_singleton_method("markdown", function!(read::markdown_native, 5))?;
+    native.define_singleton_method("content", function!(read::content_native, 6))?;
+    native.define_singleton_method("images", function!(read::images_native, 5))?;
     native.define_singleton_method("pdf_info", function!(pdf::info, 4))?;
     native.define_singleton_method("pdf_pages", function!(pdf::pages, 5))?;
     native.define_singleton_method("render_pdf_page", function!(pdf::render, 5))?;
-    native.define_singleton_method("sheets", function!(sheets::sheets_native, 5))?;
+    native.define_singleton_method("sheets", function!(sheets::sheets_native, 6))?;
     let zip_writer = native.define_class("ZipWriter", ruby.class_object())?;
     zip_writer.define_singleton_method("new", function!(archive::ZipWriter::new, 1))?;
     zip_writer.define_method("add_file", method!(archive::ZipWriter::add_file, 3))?;

data/ext/imprimatur_native/ffi/src/pdf.rs

@@ -7,7 +7,7 @@ use std::path::PathBuf;
 
 use crate::read::without_gvl;
 
-type Keywords = (Option<usize>, Option<u64>, Option<f64>);
+type Keywords = (Option<usize>, Option<u64>, Option<f64>, bool);
 
 pub fn info(
     ruby: &Ruby,

data/ext/imprimatur_native/ffi/src/read.rs

@@ -25,15 +25,19 @@ struct Read<T, F> {
 }
 
 /// Called by `Imprimatur.markdown`, which owns the keyword interface.
-/// `timeout` is in seconds; `nil` limits keep their defaults.
+/// `timeout` is in seconds; `nil` limits keep their defaults. `drop_repeated`
+/// drops PDF text repeated at the same spot on most pages, anywhere on the
+/// page (watermarks); off by default.
 pub fn markdown_native(
     ruby: &Ruby,
     document: RString,
     max_input: Option<usize>,
     max_inflated: Option<u64>,
     timeout: Option<f64>,
+    drop_repeated: bool,
 ) -> Result<RString, Error> {
-    let text = without_gvl(ruby, document, (max_input, max_inflated, timeout), markdown)?;
+    let text =
+        without_gvl(ruby, document, (max_input, max_inflated, timeout, drop_repeated), markdown)?;
     Ok(ruby.str_new(&text))
 }
 
@@ -45,9 +49,11 @@ pub fn content_native(
     max_input: Option<usize>,
     max_inflated: Option<u64>,
     timeout: Option<f64>,
+    drop_repeated: bool,
     styles: bool,
 ) -> Result<RString, Error> {
-    let read = without_gvl(ruby, document, (max_input, max_inflated, timeout), content)?;
+    let read =
+        without_gvl(ruby, document, (max_input, max_inflated, timeout, drop_repeated), content)?;
     let options = json::Options { styles };
     Ok(ruby.str_new(&Json::Object(json::content_with(&read, options)).to_string()))
 }
@@ -60,9 +66,13 @@ pub fn images_native(
     max_input: Option<usize>,
     max_inflated: Option<u64>,
     timeout: Option<f64>,
+    drop_repeated: bool,
 ) -> Result<RArray, Error> {
-    let found =
-        without_gvl(ruby, document, (max_input, max_inflated, timeout), |bytes, limits| {
+    let found = without_gvl(
+        ruby,
+        document,
+        (max_input, max_inflated, timeout, drop_repeated),
+        |bytes, limits| {
             let mut found = Vec::new();
             images(bytes, limits, |image| {
                 let description = Json::Object(json::image(&image)).to_string();
@@ -70,7 +80,8 @@ pub fn images_native(
                 Ok(())
             })?;
             Ok(found)
-        })?;
+        },
+    )?;
     let pairs = ruby.ary_new_capa(found.len());
     for (data, description) in found {
         let pair = [
@@ -86,9 +97,14 @@ pub fn images_native(
 fn limits(
     ruby: &Ruby,
     cancel: &Arc<AtomicBool>,
-    (max_input, max_inflated, timeout): (Option<usize>, Option<u64>, Option<f64>),
+    (max_input, max_inflated, timeout, drop_repeated): (
+        Option<usize>,
+        Option<u64>,
+        Option<f64>,
+        bool,
+    ),
 ) -> Result<Limits, Error> {
-    let mut limits = Limits::default().cancel_on(Arc::clone(cancel));
+    let mut limits = Limits::default().cancel_on(Arc::clone(cancel)).drop_repeated(drop_repeated);
     if let Some(bytes) = max_input {
         limits = limits.max_input(bytes);
     }
@@ -107,7 +123,7 @@ fn limits(
 pub fn without_gvl<T, F>(
     ruby: &Ruby,
     document: RString,
-    keywords: (Option<usize>, Option<u64>, Option<f64>),
+    keywords: (Option<usize>, Option<u64>, Option<f64>, bool),
     job: F,
 ) -> Result<T, Error>
 where

data/ext/imprimatur_native/ffi/src/sheets.rs

@@ -23,9 +23,11 @@ pub fn sheets_native(
     max_input: Option<usize>,
     max_inflated: Option<u64>,
     timeout: Option<f64>,
+    drop_repeated: bool,
     styles: bool,
 ) -> Result<RArray, Error> {
-    let read = without_gvl(ruby, document, (max_input, max_inflated, timeout), content)?;
+    let read =
+        without_gvl(ruby, document, (max_input, max_inflated, timeout, drop_repeated), content)?;
     let Some(sheets) = read.sheets() else {
         let kind = if matches!(read, Content::Pdf(_)) { "a PDF" } else { "a Word document" };
         let error = imprimatur::Error::UnsupportedDocument(format!("{kind} is no spreadsheet"));

data/lib/imprimatur/reader.rb

@@ -41,8 +41,8 @@ module Imprimatur
     end
 
     # @api private
-    def self.limits(timeout: 60, max_bytes: nil, max_inflated: nil)
-      [max_bytes, max_inflated, timeout && Float(timeout)]
+    def self.limits(timeout: 60, max_bytes: nil, max_inflated: nil, drop_repeated: false)
+      [max_bytes, max_inflated, timeout && Float(timeout), drop_repeated ? true : false]
     end
 
     # A path or an IO is read no further than +max_bytes+ (one byte past it

data/lib/imprimatur/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imprimatur
-  VERSION = '0.6.1'
+  VERSION = '0.8.0'
 end

data/lib/imprimatur.rb

@@ -72,6 +72,8 @@ module Imprimatur
     # @param timeout [Numeric, nil] seconds the read may take (60), +nil+ for none
     # @param max_bytes [Integer, nil] the largest document accepted (512 MiB)
     # @param max_inflated [Integer, nil] decompressed bytes allowed in all (1 GiB)
+    # @param drop_repeated [Boolean] PDF only: drop text repeated at the same
+    #   spot on most pages, anywhere on the page (watermarks); off by default
     # @return [String] Markdown, UTF-8
     # @raise [NoTextLayer] a PDF of scanned pages: run OCR instead
     # @raise [PasswordRequired] a PDF that needs a password to open

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imprimatur
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -106,6 +106,7 @@ files:
 - ext/imprimatur_native/core/src/read/pdf/content/state.rs
 - ext/imprimatur_native/core/src/read/pdf/crypt.rs
 - ext/imprimatur_native/core/src/read/pdf/document.rs
+- ext/imprimatur_native/core/src/read/pdf/document/labels.rs
 - ext/imprimatur_native/core/src/read/pdf/document/pages.rs
 - ext/imprimatur_native/core/src/read/pdf/filter.rs
 - ext/imprimatur_native/core/src/read/pdf/font.rs