imprimatur 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4b065ca85ce09dca629c5a4ca92fbd0c361a8855b7226fce30e6a6e93f587cb
-  data.tar.gz: 63bbf24b4c97feb96676db2c59a2d137220799a993ea51d707977d37d3e90cf2
+  metadata.gz: 9812ca055242755ab6117d2c5eba9bb1991e02a21572682f9f36c2a0481e2139
+  data.tar.gz: 8e1d32d440ec79ea732c62dd0a830c0b13f76655df7f9b85d60d539e0d429936
 SHA512:
-  metadata.gz: 3f58a00ab92228d0cb3c1403c1111909ebda037e776e78b05a0d3830b92f46501a34a3d069303ad6092dfe0f30b5544b2638ce4b708631f60706ef04c21d09ae
-  data.tar.gz: 32f985236d5804b10812fe87d5f2e74488085d35dd1a66d648474c47f07537e1ff62a7c04f8b06c51847ac0d3d557d35804b308f7972e2b2df24a020e562630c
+  metadata.gz: 3572b1a17819ae0fa85346788343f19ef9410d19f48b7257edb95dc00544ae1234991a5d0b50284ed3d10e21f34ca991f965aa7956fecb6a03244805870cea13
+  data.tar.gz: 9399ac644f99a699a12a2a8bdcefe73977bddcec75571e8053d984d829ddc33817fd40bb6c9c79fd15ce89f56fbe472035c276e3177430b9a35ab20023b66f16

data/CHANGELOG.md

@@ -2,11 +2,35 @@
 
 ## Unreleased
 
-- Add native PDF metadata, bounded page reads with explicit failure states,
-  and optional pure-Rust full-page PNG rendering.
-- Keep scanned and blank page structure available without a text layer.
-- Render PDFs through a bundled Rust worker with time, memory and output limits;
-  cancellation kills and reaps it. macOS uses an RSS watchdog, not a hard cap.
+- Isolate PDF metadata and text reads in the bundled resource-limited Rust
+  worker, as rendering already is; all three accept `memory_bytes:`.
+- On Linux/FreeBSD, re-exec the worker under its address-space limit before
+  reading the PDF, including tiny metadata-only reads.
+- Preserve completed pages on worker termination and recover healthy neighbors
+  after page-local stream limits without renewing the overall deadline.
+- Allow a bounded exit grace when macOS cannot inspect an exiting worker;
+  persistent monitor failures still terminate and reap a live worker.
+
+## [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)
+
+
+### Bug Fixes
+
+* **pdf:** isolate bounded reads and preserve page recovery ([fbfbbc5](https://github.com/seuros/imprimatur/commit/fbfbbc5e7e44768efae293b37be255b8b797f831))
 
 ## [0.6.0](https://github.com/seuros/imprimatur/compare/v0.5.0...v0.6.0) (2026-10-25)
 

data/Cargo.lock

@@ -513,7 +513,7 @@ dependencies = [
 
 [[package]]
 name = "imprimatur"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "aes",
  "crc32fast",
@@ -526,6 +526,7 @@ dependencies = [
  "nix",
  "qrcode",
  "read-fonts 0.45.1",
+ "serde",
  "serde_json",
  "sha2",
  "tempfile",
@@ -535,7 +536,7 @@ dependencies = [
 
 [[package]]
 name = "imprimatur-cli"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "imprimatur",
  "regex",
@@ -547,7 +548,7 @@ dependencies = [
 
 [[package]]
 name = "imprimatur_native"
-version = "0.6.0"
+version = "0.7.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.0" }
+imprimatur = { path = "ext/imprimatur_native/core", version = "0.7.0" }
 libproc = "0.14.11"
 magnus = { version = "0.9.2", default-features = false }
 md-5 = "0.11.0"
@@ -27,6 +27,7 @@ read-fonts = "0.45.1"
 # rb-sys, features and all.
 rb-sys = { version = "0.9.130", default-features = false, features = ["stable-api"] }
 regex = "1.13.1"
+serde = { version = "1.0.229", features = ["derive"] }
 serde_json = "1.0.154"
 sha2 = "0.11.1"
 tempfile = "3"

data/README.md

@@ -362,20 +362,31 @@ before allocation (`max_pixels:`, 4 million) and encoded output
 (`max_output_bytes:`, 8 MiB). Preflight rejects pages drawing more than 40 million
 source-image pixels. Renderer warnings fail instead of silently dropping content.
 The crate exposes `read::pdf::{info, pages, render_page}` (`render` feature) and
-`read::pdf::isolation::render_page_isolated` (`isolation` feature). The latter
-takes an absolute path to the trusted `imprimatur-render-worker` executable.
-The gem bundles that worker and always uses isolated rendering; it never falls
-back to an in-process render or searches PATH.
+`read::pdf::isolation::{info_isolated, pages_isolated, render_page_isolated}`
+(`isolation` feature). These take an absolute path to the trusted
+`imprimatur-render-worker` executable. The gem bundles that worker and always
+isolates all three PDF operations; it never falls back to in-process parsing
+or searches PATH.
 
-All three accept the normal read limits. Rendering also accepts `memory_bytes:`
+All three accept the normal read limits and `memory_bytes:`
 (1 GiB by default): Linux/FreeBSD enforce an address-space cap; macOS uses a
 sampled RSS watchdog, which can briefly overshoot. A worker is killed and reaped
-on timeout, cancellation or supervisor failure. Rendering has a mandatory
+on timeout, cancellation or supervisor failure. Each operation has a mandatory
 60-second process ceiling even with `timeout: nil`; a shorter `timeout:` still
 applies. CPU time, output files and core dumps are also limited.
 
+The page worker flushes completed records as it goes. An exhausted stream
+budget triggers individual-page recovery inside that worker: each attempt has
+its own `max_inflated` allowance, while the original overall deadline, process
+memory limit and aggregate text cap remain in force. An oversized page is
+`failed`, not blank, without discarding healthy neighbors. A worker terminated
+after metadata was read preserves completed pages and explicitly marks the
+unreached pages; an expired overall deadline marks them `skipped`. Cancellation
+still raises rather than returning a partial successful call.
+
 This is resource containment, **not a filesystem/network security sandbox**.
-The raw crate `render_page` remains in-process and cannot interrupt Hayro.
+The raw crate `info`, `pages` and `render_page` APIs remain in-process;
+`render_page` cannot interrupt Hayro.
 `max_inflated` bounds our preflight, not Hayro's internal decoders.
 
 ```ruby

data/ext/imprimatur_native/cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "imprimatur-cli"
-version = "0.6.0"
+version = "0.7.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,11 @@ 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 footer 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 +31,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 +44,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 +56,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 +70,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.0"
+version = "0.7.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"]
@@ -33,6 +33,7 @@ md-5.workspace = true
 miniz_oxide.workspace = true
 qrcode.workspace = true
 read-fonts = { workspace = true, optional = true }
+serde = { workspace = true, optional = true }
 serde_json = { workspace = true, optional = true }
 sha2.workspace = true
 thiserror.workspace = true
@@ -51,7 +52,7 @@ archive = ["dep:zip"]
 fonts = ["dep:read-fonts"]
 # Pure-Rust full-page PDF rasterization; readers and writers remain independent.
 render = ["dep:hayro"]
-isolation = ["render", "dep:tempfile", "dep:nix", "dep:libproc"]
+isolation = ["render", "json", "dep:serde", "dep:tempfile", "dep:nix", "dep:libproc"]
 
 [target.'cfg(unix)'.dependencies]
 nix = { workspace = true, optional = true }

data/ext/imprimatur_native/core/README.md

@@ -11,10 +11,15 @@ states and UTF-8-safe text limits. `read::pdf::render_page`, under the optional
 `render` feature, rasterizes a full page through Hayro (pure Rust).
 That raw API is not preemptible. For untrusted documents, enable `isolation`,
 build the `imprimatur-render-worker` binary and pass its absolute path to
-`read::pdf::isolation::render_page_isolated`. Rust supervises finite wall/CPU,
+`read::pdf::isolation::{info_isolated, pages_isolated, render_page_isolated}`.
+Rust supervises finite wall/CPU,
 memory and file-output limits, killing and reaping failed/cancelled workers.
 Linux/FreeBSD enforce address-space limits; macOS samples RSS and can briefly
 overshoot. This is resource containment, not a filesystem/network sandbox.
+Isolated page reads flush completed records, retain them on worker termination,
+and recover healthy neighbors after page-local decompression failures. Recovery
+attempts renew only the individual decompression allowance, never the overall
+deadline, process-memory limit or aggregate text cap.
 
 ```rust
 use imprimatur::xlsx::{Cell, Color, DateTime, Format, Workbook};

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

@@ -48,7 +48,14 @@ fn pdf(out: &mut String, pages: &[Page]) {
         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/bounded.rs

@@ -11,6 +11,7 @@ use crate::{Error, Result};
 
 /// Metadata read without interpreting page content.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[cfg_attr(feature = "isolation", derive(serde::Serialize, serde::Deserialize))]
 pub struct Info {
     pub page_count: u32,
     /// Opened with the empty password: permissions, not a locked document.
@@ -40,7 +41,7 @@ impl Default for ReadOptions {
 }
 
 impl ReadOptions {
-    const fn validate(&self) -> Result<()> {
+    pub(super) const fn validate(&self) -> Result<()> {
         if self.first_page == 0 || self.last_page < self.first_page {
             return Err(Error::InvalidPdfOption("pages must be an ascending one-based range"));
         }
@@ -53,6 +54,7 @@ impl ReadOptions {
 
 /// What is known about a page; failure is never reported as empty.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[cfg_attr(feature = "isolation", derive(serde::Serialize, serde::Deserialize))]
 pub enum Status {
     Text,
     Empty,
@@ -73,6 +75,7 @@ impl Status {
 }
 
 #[derive(Debug)]
+#[cfg_attr(feature = "isolation", derive(serde::Serialize, serde::Deserialize))]
 pub struct PageResult {
     pub number: u32,
     pub status: Status,
@@ -106,6 +109,24 @@ pub fn info(data: &[u8], limits: &Limits) -> Result<Info> {
 /// # Errors
 /// As [`info`], and invalid options.
 pub fn pages(data: &[u8], options: &ReadOptions, limits: &Limits) -> Result<Pages> {
+    let mut pages = Vec::new();
+    let info = visit_pages(data, options, limits, false, |page| {
+        pages.push(page);
+        Ok(())
+    })?;
+    Ok(Pages { info, pages })
+}
+
+/// The worker flushes each completed page. After an exhausted stream budget,
+/// single-page attempts get fresh decompression budgets, as individual reads
+/// would; the supervisor still enforces one wall-clock and process limit.
+pub(super) fn visit_pages(
+    data: &[u8],
+    options: &ReadOptions,
+    limits: &Limits,
+    recover: bool,
+    mut emit: impl FnMut(PageResult) -> Result<()>,
+) -> Result<Info> {
     options.validate()?;
     let budget = Budget::new(limits, data.len())?;
     let document = open(data, &budget)?;
@@ -114,52 +135,89 @@ pub fn pages(data: &[u8], options: &ReadOptions, limits: &Limits) -> Result<Page
     let mut fonts = Fonts::new();
     let mut text = PageText { strict: true, ..PageText::default() };
     let mut remaining = options.max_output_bytes;
-    let mut results = Vec::with_capacity(selected.pages.len());
+    let mut individual = false;
     for (number, page) in selected.pages {
         budget.check()?;
         if remaining == 0 {
-            results.push(unread(
-                number,
-                Status::Skipped,
-                "the text output limit was reached".into(),
-            ));
+            emit(unread(number, Status::Skipped, "the text output limit was reached".into()))?;
             continue;
         }
         text.max_bytes = Some(options.max_page_bytes.min(remaining));
-        let read = page.and_then(|page| page_text(&document, &page, &mut fonts, &mut text));
-        match read {
-            Ok(()) => {
-                let lines = layout::lines(&text);
-                let mut output = String::new();
-                for line in &lines.lines {
-                    if !output.is_empty() {
-                        output.push('\n');
-                    }
-                    output.push_str(lines.text(line));
+        let read = if individual {
+            single_page(data, number, options, remaining, limits)
+        } else {
+            page.and_then(|page| page_text(&document, &page, &mut fonts, &mut text))
+                .map(|()| text_result(number, &text, text.max_bytes.unwrap_or(remaining)))
+        };
+        let read = match read {
+            Err(error @ Error::LimitExceeded(_)) if recover => {
+                // Never renew an expired time budget or swallow cancellation.
+                budget.check()?;
+                if individual {
+                    Err(error)
+                } else {
+                    individual = true;
+                    single_page(data, number, options, remaining, limits)
                 }
-                let limit = options.max_page_bytes.min(remaining);
-                let truncated = text.truncated || output.len() > limit;
-                truncate(&mut output, limit);
-                remaining -= output.len();
-                results.push(PageResult {
-                    number,
-                    status: if output.trim().is_empty() { Status::Empty } else { Status::Text },
-                    text: output,
-                    images: Some(u32::try_from(text.images).unwrap_or(u32::MAX)),
-                    truncated,
-                    reason: truncated.then(|| "the page text limit was reached".into()),
-                });
+            }
+            other => other,
+        };
+        let result = match read {
+            Ok(page) => page,
+            Err(error @ Error::LimitExceeded(_)) if recover => {
+                budget.check()?;
+                unread(number, Status::Failed, error.to_string())
             }
             Err(error) if xref::is_limit(&error) || matches!(error, Error::PasswordRequired) => {
                 return Err(error);
             }
-            Err(error) => results.push(unread(number, Status::Failed, error.to_string())),
+            Err(error) => unread(number, Status::Failed, error.to_string()),
+        };
+        remaining -= result.text.len();
+        emit(result)?;
+    }
+    Ok(Info { page_count: selected.count, encrypted: document.encrypted() })
+}
+
+fn single_page(
+    data: &[u8],
+    number: u32,
+    options: &ReadOptions,
+    remaining: usize,
+    limits: &Limits,
+) -> Result<PageResult> {
+    let options = ReadOptions {
+        first_page: number,
+        last_page: number,
+        max_pages: 1,
+        max_output_bytes: remaining,
+        ..options.clone()
+    };
+    pages(data, &options, limits)?
+        .pages
+        .pop()
+        .ok_or_else(|| Error::malformed("PDF", "the selected page disappeared"))
+}
+
+fn text_result(number: u32, text: &PageText, limit: usize) -> PageResult {
+    let lines = layout::lines(text);
+    let mut output = String::new();
+    for line in &lines.lines {
+        if !output.is_empty() {
+            output.push('\n');
         }
+        output.push_str(lines.text(line));
+    }
+    let truncated = text.truncated || output.len() > limit;
+    truncate(&mut output, limit);
+    PageResult {
+        number,
+        status: if output.trim().is_empty() { Status::Empty } else { Status::Text },
+        text: output,
+        images: Some(u32::try_from(text.images).unwrap_or(u32::MAX)),
+        truncated,
+        reason: truncated.then(|| "the page text limit was reached".into()),
     }
-    Ok(Pages {
-        info: Info { page_count: selected.count, encrypted: document.encrypted() },
-        pages: results,
-    })
 }
 
 pub(super) fn open<'a>(data: &'a [u8], budget: &'a Budget<'a>) -> Result<Document<'a>> {
@@ -170,7 +228,8 @@ pub(super) fn open<'a>(data: &'a [u8], budget: &'a Budget<'a>) -> Result<Documen
     Document::open(data, budget).map(Document::strict)
 }
 
-const fn unread(number: u32, status: Status, reason: String) -> PageResult {
+pub(super) fn unread(number: u32, status: Status, mut reason: String) -> PageResult {
+    truncate(&mut reason, 4096);
     PageResult {
         number,
         status,