From d4da4b94bb3de846c0047877a7b0fc3b4cb79bae Mon Sep 17 00:00:00 2001 From: amoisttowe1 Date: Wed, 18 Nov 2026 01:29:46 -0800 Subject: [PATCH] M5.1: structural round-trip, property and never-crash tests for crates/annot (tests only) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What this adds Structural round-trip, property and never-crash evidence for `crates/annot`, which had no `tests/` directory — every prior test checked an in-memory object and never crossed the writer. 50 new tests take the crate from 42 to **92 passing / 0 failed**, with nothing ignored and no existing test weakened: - `tests/round_trip.rs` (25) — annotations survive save and reopen across all three writer paths: geometry, contents text, flag bits, opacity, identifying names, pop-up back-references, link targets/URIs/dash structure, per-page order and ownership. - `tests/properties.rs` (10) — proptest invariants over generated geometry, opacity and flags. - `tests/malformed.rs` (15) — damaged input must never panic; each case documents the *measured* behaviour as defined degradation, not endorsed output. - `tests/support/{bytes.rs,fixture.rs}` — a raw-byte reader and PDF skeletons, so claims can be made about the saved file rather than only about parsed objects. `proptest = { workspace = true }` as a dev-dependency (same declaration as `cos`; style differs from the dotted form in crypt/filters). proptest 1.11.0 is already locked in the workspace, so `Cargo.lock` gains one edge and no new package. **No product code is changed.** This pins current behaviour, including three questionable behaviours it surfaced (below), and leaves every fix to a follow-up. ## Appearance is deliberately out of scope Nothing here asserts what an appearance stream draws, so this stays clear of #2345, #2137, #2066, #1775 and #1513 (all open, all rewriting appearance generation). Structural fidelity — where a mark sits, what it says, which rules apply — is behaviour none of them intends to alter. ## Evidence quality: mutation-tested, with credit split honestly Ten single-site guard/arithmetic/key-rename mutants were run against `crates/annot/src/lib.rs` by two independent reviewers plus the author. All ten were caught, and they split **five and five**: - Killed by pre-existing inline tests in `crates/annot/src/tests.rs` as well: `lib.rs:857` inverted, `:1030` inverted (six inline tests), `:1930` inverted, `:2161` tie-break swapped, `:1241` `/Parent` renamed. - Killed **only** by tests added here: `:1030` clamp deleted, `:857` clamp deleted, opacity clamp removed at `:1024`, colour clamp in `rgb()` removed at `:824`, and a clamp introduced on the read path at `:2238`. `lib.rs:857` and `:1030` appear on both sides deliberately — inverting either trips inline tests, deleting them trips nothing outside this branch. Confusing those two mutation families is easy enough to produce a false refutation, so the distinction is recorded in `round_trip.rs` rather than left to whoever re-runs them. A build failure was never counted as a kill in any pass. The mutants were run at `crates/annot/src/lib.rs` as of base `99941daa`. Main has since split that file into modules (`5ce4d244`); the anchor statements are byte-identical at their new homes (the `/Parent` site apart, locals renamed), but main also grew the inline suite from 42 to 74 tests — so the five-and-five split describes the base tree, and the battery was not re-run at the merge head `3122ebad`. ## Three defects found while writing this — reported, not fixed 1. **Large finite numbers are written unvalidated and become unreadable downstream.** The only style guard on the create path (`lib.rs:1018`) is `!finite(&style.color) || !style.opacity.is_finite() || !style.width.is_finite()`; the `abs() < 1e7` cap inside `finite()` (`:827-829`) applies to **colour alone**, so `width` carries no magnitude limit at all. Measured: `width = 1e9` and `1e299` are accepted and written verbatim to `/BS /W`. qpdf (`pikepdf.Job(["--check", …])`, pikepdf 9.11 / libqpdf 12.2) exits **3** — its *warning* status, printed with "operation succeeded with warnings" (0 = clean and silent here) — reporting `overflow/underflow converting <301 digits> to 64-bit integer`, and `/Annots[0]` resolves to `null` (still null after a qpdf re-save) while `pikepdf.open()` reports success. Our own `repair_log()` stays empty, which conflicts with CLAUDE.md's "never silently drop or repair data". 2. **Fill colour is accepted on create and refused on edit.** Create never screens `fill` (it is clamped component-wise by `rgb()` at `:823-825`), while `set_fill` refuses the identical value with `Invalid("invalid fill colour")` at `:2010`. Pinned by `malformed::the_same_huge_fill_is_accepted_on_create_and_refused_on_edit`. 3. **One unparseable token in a page's `/Annots` loses the whole page, silently.** For `[4 0 R notanumber]`, `page_refs()` returns `Ok([])` with `/Pages` still showing the page — so the page object itself fails to parse, every annotation on it disappears, and `repair_log()` records nothing. qpdf keeps the page and warns: `(object 3 0, offset 191): unknown token while reading object; treating as string`. Anchors in this section read against `crates/annot/src/lib.rs` at base `99941daa`; main has since split that file (`5ce4d244`). The same code at merge head `3122ebad`: `:1018` → `create.rs:416`, `:827-829` → `create.rs:17-19`, `:823-825` → `create.rs:13-15`, `:2010` → `modify.rs:626-627`. All three described behaviours re-verified unchanged at this head. These need a policy decision rather than a patch, so they are described here and will be filed as separate issues; nothing in this PR fixes them. ## CI status and base note This branch was opened at `afa8e18` (then current `main`) and rebased onto `99941da`. Two jobs were red on the original base — `test (ubuntu-latest)`, `test (windows-latest)` and the FreeBSD job, all failing in `crates/automation/tests/automation.rs` at `:354` (`signing_with_translated_labels_through_tools`, which passed a 7-character password against an 8-character minimum) and at `:359` (`a_save_that_does_not_reopen_leaves_the_file_as_it_was`), `173 passed; 2 failed`. Those were upstream failures reproduced on that commit's own CI run (**38703572296**, plus the FreeBSD run **38703573428**) in a crate this change never touches; they have since been fixed on `main` by #2420 (the signing password now meets the minimum) and #2484 (save/search regression expectations updated), which is why `main`'s latest CI run is green and why this branch was rebased. The rebase is a no-op for our code: `crates/annot/src/lib.rs` at both commits is byte-identical (`fb491e19…`), so every line number cited below still resolves as written. Since then `main` was merged in (`dc943eeb`, merge commit `3122ebad`) to clear the FreeBSD job per the CI triage on this PR: the `files_and_quit_from_the_operating_system` race was fixed on main by `12fcc641` (#2812). The merge probe was clean (zero conflicts; `Cargo.lock` the only overlapping path). Main split `crates/annot/src/lib.rs` into modules and reshaped `set_style` to take a `StyleChange`; the merge commit carries three tests-only adaptations (two `SaveOptions` literals gain `drop_unlinked: false`, the writer's default; one `set_style` call re-shaped; citations re-derived to the new file layout). No crate source diverges from main's: `git diff --stat upstream/main HEAD -- crates/annot/src/` is empty. Inline-suite counts at this head: 74 (main grew it from 42); the 42 → 92 figures above describe base `99941daa`. proptest on main's lock is now 1.12.0; one edge added, no new package. ## Where the proof stops - The first CI run on this branch was at our original base and showed the inherited failures described above; results cited here are local macOS runs (we have no Poppler locally, so qpdf cross-checks ran through pikepdf in a workspace virtualenv). - The probe PDFs used for qpdf measurements are **not** committed, because AGENTS.md §1 requires an `ATTRIBUTION.toml` entry per sample document — so CI cannot re-measure them. Each measurement carries a regenerate recipe and sha256 in the test comments (`malformed.rs`). - All oracle figures are tied to one machine's build: pikepdf 9.11 over libqpdf 12.2 (`__libqpdf_version__`; the Job API rejects `--version`, so no raw qpdf version string). Poppler comparisons would need CI, as `pdftoppm` is unavailable locally. - Mutation evidence covers single-site guard/arithmetic/key-rename mutants only — no multi-site, data-flow or off-by-one classes were attempted. - We did not measure what any viewer displays to a user after these failures; the listed-but-null entry was observed, not rendered behaviour. ## Question for maintainers CLAUDE.md asks new tests to be registered in `ROADMAP.md` and `parity/acrobat-features.toml`, but several open PRs above are editing both files right now, so we left them untouched to avoid collisions. Tell us where you would like these registered and we will add the lines here, or open a follow-up. Credit: `contributors/people.toml` deliberately carries no new entry in this PR — ours is already queued on #2073. --- Cargo.lock | 1 + crates/annot/Cargo.toml | 5 + .../tests/malformed.proptest-regressions | 6 + crates/annot/tests/malformed.rs | 859 +++++++++++++ .../tests/properties.proptest-regressions | 6 + crates/annot/tests/properties.rs | 417 +++++++ crates/annot/tests/round_trip.rs | 1086 +++++++++++++++++ crates/annot/tests/support/bytes.rs | 336 +++++ crates/annot/tests/support/fixture.rs | 207 ++++ 9 files changed, 2923 insertions(+) create mode 100644 crates/annot/tests/malformed.proptest-regressions create mode 100644 crates/annot/tests/malformed.rs create mode 100644 crates/annot/tests/properties.proptest-regressions create mode 100644 crates/annot/tests/properties.rs create mode 100644 crates/annot/tests/round_trip.rs create mode 100644 crates/annot/tests/support/bytes.rs create mode 100644 crates/annot/tests/support/fixture.rs diff --git a/Cargo.lock b/Cargo.lock index 7230c7db39..20d3f9a16a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4640,6 +4640,7 @@ dependencies = [ "pdfcraft-fonts", "pdfcraft-geom", "pdfcraft-model", + "proptest", "thiserror 2.0.21", ] diff --git a/crates/annot/Cargo.toml b/crates/annot/Cargo.toml index e91c9ed896..1d09f0f8bc 100644 --- a/crates/annot/Cargo.toml +++ b/crates/annot/Cargo.toml @@ -18,3 +18,8 @@ thiserror = { workspace = true } [dev-dependencies] hayro-syntax = { workspace = true } +# Property tests over generated annotation geometry and metadata (`tests/properties.rs`). Same +# workspace dependency the sibling test suites already carry: `crates/cos/Cargo.toml` declares it as +# `proptest = { workspace = true }`, and `crates/crypt`/`crates/filters` use the dotted form +# `proptest.workspace = true`. Nothing new enters the dependency graph. +proptest = { workspace = true } diff --git a/crates/annot/tests/malformed.proptest-regressions b/crates/annot/tests/malformed.proptest-regressions new file mode 100644 index 0000000000..341ba3ff3d --- /dev/null +++ b/crates/annot/tests/malformed.proptest-regressions @@ -0,0 +1,6 @@ +# Seeds for failure cases proptest has generated in the past. It is +# automatically read and these particular cases re-run before any +# novel cases are generated. +# +# It is recommended to check this file in to source control so that +# everyone who runs the test benefits from these saved cases. diff --git a/crates/annot/tests/malformed.rs b/crates/annot/tests/malformed.rs new file mode 100644 index 0000000000..64fc241baf --- /dev/null +++ b/crates/annot/tests/malformed.rs @@ -0,0 +1,859 @@ +//! Damaged annotation dictionaries: what the reader does, and what it must never do. +//! +//! **These are never-crash tests.** They assert that a stranger's broken annotation data produces an +//! error or a defined degradation instead of a panic. Where the current behaviour is questionable, +//! that is said out loud and pinned as it is: an expected value below is *what PdfCraft does today*, +//! not a claim that it is right. Each such place carries a `NOTE` comment naming the alternative a +//! reader could reasonably choose, so a later fix shows up as a changed expectation here rather than a +//! silent edit. (`AGENTS.md` §4 and `CLAUDE.md` Fidelity: no crash, and never repair silently.) +//! +//! The shapes come from two directions: bytes written by hand (a file we did not make, including +//! tokens our typed API cannot even express — a three-number quadrilateral or an unknown keyword), and +//! values handed to the builder (`add_annotation` with NaN in a style or geometry). + +mod support { + pub mod bytes; + pub mod fixture; +} + +use pdfcraft_annot::{ + AnnotError, AttachIcon, Meta, NewAnnotation, NoteIcon, Shape, Style, add_annotation, delete_annotation, has_visible_fill_sign, links, page_refs, + picture_rotation, props, set_annots, signature_image, summaries, +}; +use pdfcraft_cos::{Dict, Document, ObjRef, Object}; +use proptest::prelude::*; +use std::sync::Arc; + +use support::bytes; +use support::fixture::{Save, annot_entries, blank, dict_of, name_of, nums, page_object_numbers, pdf, save_and_reopen}; + +/// Open a hand-written file that must parse well enough to be examined. +fn open(objs: &[&[u8]]) -> Document { + Document::open(Arc::new(pdf(objs))).expect("a damaged file still opens") +} + +/// A one-page file whose single annotation is `body`. +fn one_annot(body: &[u8]) -> Document { + open(&[ + b"<< /Type /Catalog /Pages 2 0 R >>", + b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>", + b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Annots [4 0 R] >>", + body, + ]) +} + +/// Run every annotation reader over a document. The point is that none of them panics; the counts +/// are checked by the callers, which know what the damage was. +fn read_everything(doc: &Document) { + let listed = summaries(doc); + let pages = page_refs(doc).map(|p| p.len()).unwrap_or(0); + for page in 0..pages { + let entries = annot_entries(doc, page); + for index in 0..entries.len() + 2 { + let _ = props(doc, page, index); + } + } + let _ = links::list(doc); + let _ = has_visible_fill_sign(doc); + for page in 0..pages { + let entries = annot_entries(doc, page); + for index in 0..entries.len() { + let _ = signature_image(doc, page, index); + let _ = picture_rotation(doc, page, index); + } + } + let _ = listed; +} + +// ── wrong-shaped numbers ─────────────────────────────────────────────────────────────────────── + +/// A `/Rect` that is not four numbers cannot place a comment. Today it reads as the empty rectangle +/// at the origin and the comment is still listed, so a viewer would draw it in the page corner. +/// NOTE: refusing the entry, or listing it at no position, are both defensible; pinning whichever +/// is chosen keeps the change honest. The invariant held here is "listed, with a finite rect, no +/// panic" — not that the position is meaningful. +#[test] +fn a_malformed_rectangle_reads_as_the_origin_instead_of_panicking() { + let bodies: Vec<&[u8]> = vec![ + b"<< /Type /Annot /Subtype /Square /Rect [10 20] >>", + b"<< /Type /Annot /Subtype /Square /Rect [1 2 3] >>", + b"<< /Type /Annot /Subtype /Square /Rect [1 2 3 4 5] >>", + b"<< /Type /Annot /Subtype /Square /Rect [/a /b /c /d] >>", + b"<< /Type /Annot /Subtype /Square /Rect (a string) >>", + b"<< /Type /Annot /Subtype /Square /Rect null >>", + // Colour components outside [0,1]: clamped on read rather than refused. + b"<< /Type /Annot /Subtype /Square /Rect [10 20 30 40] /IC [0.5 2 -0.5] >>", + ]; + for (n, body) in bodies.into_iter().enumerate() { + let doc = one_annot(body); + read_everything(&doc); + let listed = summaries(&doc); + assert_eq!(listed.len(), 1, "case {n}: the comment is still listed ({body:?})"); + assert!(listed[0].rect.iter().all(|v| v.is_finite()), "case {n}: a finite rectangle, got {:?}", listed[0].rect); + assert_eq!( + name_of(&doc, &dict_of(&doc, &annot_entries(&doc, 0)[0]).expect("a dictionary"), b"Subtype").as_deref(), + Some("Square"), + "case {n}" + ); + // Save it on and the damage must not turn into a crash or a file we cannot reopen. + for path in [Save::Incremental, Save::FullTable] { + let (_, reopened) = save_and_reopen(&doc, path); + read_everything(&reopened); + assert_eq!(summaries(&reopened).len(), 1, "case {n} after {path:?}"); + } + } +} + +/// `/QuadPoints` must come in eights (§12.5.6.10). A list that does not divide evenly is truncated +/// to whole quadrilaterals: seven numbers give none, twelve give one, and the leftover numbers are +/// dropped without a word. NOTE: "drop silently" is what happens today; reporting the odd tail would +/// be kinder. What is asserted here is that the chunking never over-reads and never panics. +#[test] +fn a_quad_list_that_is_not_a_multiple_of_eight_keeps_whole_quads_only() { + let cases: Vec<(&[u8], usize)> = vec![ + (b"[1 2 3 4 5 6 7]", 0), + (b"[1 2 3 4 5 6 7 8]", 1), + (b"[1 2 3 4 5 6 7 8 9]", 1), + (b"[1 2 3 4 5 6 7 8 9 10 11 12]", 1), + (b"[16 numbers follow: this token is not a number at all]", 0), + (b"[]", 0), + ]; + for (n, (values, want_quads)) in cases.into_iter().enumerate() { + let body = format!("<< /Type /Annot /Subtype /Highlight /Rect [10 20 60 30] /QuadPoints {} >>", String::from_utf8_lossy(values)); + let doc = one_annot(body.as_bytes()); + read_everything(&doc); + if String::from_utf8_lossy(values).contains("numbers follow") { + // An unparseable token inside the array loses the whole annotation object: see the note + // on `an_unparseable_token_...` below. It is listed in /Annots but reads as nothing. + assert!(summaries(&doc).is_empty(), "case {n}"); + continue; + } + let listed = summaries(&doc); + assert_eq!(listed.len(), 1, "case {n}: the markup is still listed"); + assert_eq!(listed[0].quads.len(), want_quads, "case {n}: {}", String::from_utf8_lossy(values)); + // The stored array is preserved verbatim: reading truncates, saving must not rewrite. + let d = dict_of(&doc, &annot_entries(&doc, 0)[0]).expect("a dictionary"); + let stored = nums(&doc, &d, b"QuadPoints").unwrap_or_default(); + let written = values.iter().filter(|c| c.is_ascii_digit() || **c == b' ').count(); + assert!(stored.len() <= written, "case {n}: we read at most what is there ({} vs {written})", stored.len()); + } +} + +/// A token the object parser cannot interpret (a bare word that is not a number, name, +/// reference, string, `true`, `false` or `null`) loses the object it sits in. Inside a page's +/// `/Annots` that costs the *whole page*: `page_refs()` comes back `Ok([])` and every annotation +/// on that page disappears — with an empty repair log. Precision matters here: `/Pages` still +/// shows `Count 1, Kids [3 0 R]`, so it is not that the annotation list alone became +/// unreachable; the page object itself fails to parse, and nothing downstream sees it. +/// NOTE: this is `pdfcraft-cos` parser behaviour, reached through the annotation readers. The +/// bytes below are HAND-BUILT by this test's `open` helper — no writer path emits a bare +/// keyword there; they model damage an outside editor or a truncated edit leaves behind. +/// +/// Cross-checked against qpdf core 12.2.0 via pikepdf 9.11 on these exact bytes (sha256 +/// 582e0eb0e8a25e6975c0727d405372d7df6c8dfcb06e0289817f5b28e546b94e, 447 B — hand-built and +/// not committed; re-create it from the object bodies below, in order). Running qpdf's check, +/// `pikepdf.Job(["--check", , "/dev/null"])`, exits 3 with warnings on process stderr, +/// verbatim: +/// `WARNING: (object 3 0, offset 191): unknown token while reading object; treating as string` +/// — note `object 3 0` and the offset; there is no `/Annots` in qpdf's wording. qpdf KEEPS the +/// page, so this loss is ours alone — and qpdf's warning shows it was detectable. The word +/// 'silently' below refers only to our empty `repair_log()`, never to qpdf, which complains. +/// +/// The honest claim here is limited to: no panic, an error or an empty page list, and +/// `add_annotation` refusing cleanly rather than writing onto a page it cannot see. Fixing the +/// parser should make this test fail, and that is exactly what it is for. +#[test] +fn an_unparseable_token_inside_annots_loses_the_page_and_says_nothing() { + let doc = open(&[ + b"<< /Type /Catalog /Pages 2 0 R >>", + b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>", + b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Annots [4 0 R notanumber] >>", + b"<< /Type /Annot /Subtype /Square /Rect [10 20 60 30] >>", + ]); + read_everything(&doc); + assert_eq!(page_refs(&doc).map(|p| p.len()), Ok(0), "the page object could not be read"); + assert!(doc.repair_log().is_empty(), "and nothing was recorded about losing it"); + assert!(page_object_numbers(&doc).is_empty(), "this file's own page walk agrees there is nothing to read"); + assert!(summaries(&doc).is_empty()); + + let mut try_add = doc.clone(); + let e = add_annotation( + &mut try_add, + &NewAnnotation { + page: 0, + shape: Shape::Rectangle { rect: [10.0, 10.0, 40.0, 30.0] }, + style: Style::default(), + contents: "x".into(), + author: "A".into(), + }, + &Meta { date: None, id: "i".into() }, + ) + .err(); + assert_eq!(e, Some(AnnotError::NoSuchPage(0)), "adding to the vanished page refuses rather than inventing a page"); + assert_eq!(links::list(&doc).len(), 0); +} + +// ── broken references ────────────────────────────────────────────────────────────────────────── + +/// Dangling, duplicated and wrong-typed entries in one `/Annots` array: each is skipped by the +/// readers, none panics, and deleting one leaves the others alone. A duplicated reference really is +/// listed twice — the two comments share a `Rect` because they *are* the same object. +#[test] +fn dangling_duplicate_and_wrong_typed_entries_are_skipped() { + let doc = open(&[ + b"<< /Type /Catalog /Pages 2 0 R >>", + b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>", + b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Annots [5 0 R 4 0 R 4 0 R (a string) null] >>", + b"<< /Type /Annot /Subtype /Square /Rect [10 20 60 30] >>", + b"[7 0 R]", + ]); + read_everything(&doc); + let entries = annot_entries(&doc, 0); + assert_eq!(entries.len(), 5, "the array keeps all five slots"); + let listed = summaries(&doc); + assert_eq!(listed.iter().map(|s| s.index).collect::>(), vec![1, 2], "only the two real dictionaries are comments"); + assert_eq!(listed[0].rect, listed[1].rect, "the duplicate is the same object"); + assert!(props(&doc, 0, 0).is_none(), "an entry naming an array is not a comment"); + assert!(props(&doc, 0, 3).is_none(), "a string entry is not a comment"); + assert_eq!(signature_image(&doc, 0, 1).ok().flatten(), None); + + // Deleting one of the duplicates removes **both** slots: `delete_annotation` drops every entry + // that names a doomed object, not just the index asked for (that is how it takes pop-ups and + // replies with their parent). So the shared dictionary leaves the page entirely. + let mut cut = doc.clone(); + delete_annotation(&mut cut, 0, 1).expect("deletes the comment"); + assert_eq!(annot_entries(&cut, 0).len(), 3, "both slots naming that object are gone"); + assert!(summaries(&cut).is_empty()); + let (_, reopened) = save_and_reopen(&cut, Save::FullTable); + assert!(summaries(&reopened).is_empty(), "and the file agrees"); + + // An `/Annots` that is not an array at all reads as "no annotations". + let weird = open(&[ + b"<< /Type /Catalog /Pages 2 0 R >>", + b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>", + b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Annots (hello) >>", + ]); + read_everything(&weird); + assert!(annot_entries(&weird, 0).is_empty()); + let mut d = weird.clone(); + assert_eq!(delete_annotation(&mut d, 0, 0).err(), Some(AnnotError::NoSuchAnnotation { page: 0, index: 0 })); +} + +/// Reference loops must terminate. These are the shapes a generated or half-repaired file produces: +/// an annotation replying to itself, two replies replying to each other, and a pop-up chain whose +/// back-references point at the next annotation instead of the previous one. +#[test] +fn reference_loops_terminate_and_a_delete_takes_the_cycle_with_it() { + // Self-reference. + let self_irt = one_annot(b"<< /Type /Annot /Subtype /Text /Rect [10 20 30 40] /IRT 4 0 R >>"); + read_everything(&self_irt); + let mut cut = self_irt.clone(); + delete_annotation(&mut cut, 0, 0).expect("deletes the self-replying comment"); + assert!(annot_entries(&cut, 0).is_empty()); + + // Mutual references: deleting either must take both and stop. + let shared = open(&[ + b"<< /Type /Catalog /Pages 2 0 R >>", + b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>", + b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Annots [4 0 R 5 0 R] >>", + b"<< /Type /Annot /Subtype /Text /Rect [10 20 30 40] /IRT 5 0 R >>", + b"<< /Type /Annot /Subtype /Text /Rect [10 20 30 40] /IRT 4 0 R >>", + ]); + read_everything(&shared); + assert_eq!(summaries(&shared).len(), 2, "both halves of the pair are listed"); + let mut cut = shared.clone(); + delete_annotation(&mut cut, 0, 0).expect("deleting one of a mutual pair returns"); + assert!(annot_entries(&cut, 0).is_empty(), "the cycle is taken out together"); + + // A pop-up whose /Parent names a third annotation, which in turn names the first. + let chained = open(&[ + b"<< /Type /Catalog /Pages 2 0 R >>", + b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>", + b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Annots [4 0 R 5 0 R 6 0 R] >>", + b"<< /Type /Annot /Subtype /Text /Rect [10 20 30 40] /Popup 5 0 R >>", + b"<< /Type /Annot /Subtype /Popup /Rect [40 20 90 60] /Parent 6 0 R >>", + b"<< /Type /Annot /Subtype /Popup /Rect [40 20 90 60] /Parent 4 0 R >>", + ]); + read_everything(&chained); + assert_eq!(summaries(&chained).len(), 1, "only the text comment is a comment"); + let mut cut = chained.clone(); + delete_annotation(&mut cut, 0, 0).expect("deleting the owner of a pop-up chain returns"); + assert!(annot_entries(&cut, 0).is_empty(), "and the whole chain goes with it"); + + // A `/Popup` that names a missing object must not stop the comment being used. + let dangling_popup = one_annot(b"<< /Type /Annot /Subtype /Text /Rect [10 20 30 40] /Popup 99 0 R >>"); + read_everything(&dangling_popup); + assert_eq!(summaries(&dangling_popup).len(), 1); + let mut reply = dangling_popup.clone(); + assert!( + pdfcraft_annot::add_reply(&mut reply, 0, 0, "to you", "Ben", &Meta { date: None, id: "r".into() }).is_ok(), + "a missing pop-up does not block replying" + ); +} + +// ── wrong types where the reader wants a number or a name ───────────────────────────────────── + +/// Values of the wrong type in flag, opacity and colour entries: the reader falls back to its +/// defaults instead of panicking. NOTE on opacity: reading does **not** clamp, so `/CA 7.5` comes +/// back as 7.5 and would hand a nonsense value to a 0–1 slider; writing clamps (`add_annotation` +/// refuses non-finite and clamps the range). The asymmetry is recorded here, not endorsed. +#[test] +fn wrong_typed_flag_opacity_and_colour_entries_fall_back_without_panicking() { + let doc = one_annot(b"<< /Type /Annot /Subtype /Text /Rect [10 20 30 40] /CA 7.5 /F /NotAnInt /C [1 2] >>"); + read_everything(&doc); + let p = props(&doc, 0, 0).expect("still a comment"); + assert_eq!(p.opacity, 7.5, "the out-of-range opacity is passed through as written"); + assert!(!p.locked, "a name where /F belongs reads as no flags at all"); + assert_eq!(p.color, None, "/C with two components is not a colour"); + let listed = summaries(&doc); + assert_eq!(listed.len(), 1); + assert_eq!(listed[0].color, None); + + // And the other direction: /F as a real number is read by its integer value. + let flags_real = one_annot(b"<< /Type /Annot /Subtype /Text /Rect [10 20 30 40] /F 132.0 >>"); + let p = props(&flags_real, 0, 0).expect("still a comment"); + assert!(p.locked, "132 sets ReadOnly (bit 8) whatever the number's form"); + + // An annotation with no /Subtype at all: nothing to name, so it is not a comment and has no + // properties, but the entry survives untouched (preserve unknown data). + let no_subtype = one_annot(b"<< /Type /Annot /Rect [10 20 30 40] >>"); + read_everything(&no_subtype); + assert!(summaries(&no_subtype).is_empty()); + assert!(props(&no_subtype, 0, 0).is_none()); + assert_eq!(annot_entries(&no_subtype, 0).len(), 1); + + // A `/P` pointing at a page that does not exist is cosmetic: the comment still lists. + let bad_parent_page = one_annot(b"<< /Type /Annot /Subtype /Square /Rect [10 20 30 40] /P 77 0 R >>"); + read_everything(&bad_parent_page); + assert_eq!(summaries(&bad_parent_page).len(), 1); +} + +// ── guards that only bite on damaged data, pinned so they stay visible ──────────────────────── + +/// `move_annotation` shifts the numbers of every geometry key, but only the first four of an array +/// it treats as a rectangle (`every || i < 4`, `crates/annot/src/modify.rs:302`). A `/Rect` with +/// more than four numbers is not something PdfCraft writes, so the guard only shows up on damaged +/// data — which is precisely why it is pinned here: without this test the rule can be deleted +/// silently. What must hold is that the four rectangle numbers move together and whatever strays +/// the file carries are left exactly as they were, rather than being dragged along by half a point. +#[test] +fn moving_a_damaged_rectangle_shifts_its_four_numbers_and_leaves_the_strays_alone() { + let mut doc = one_annot(b"<< /Type /Annot /Subtype /Square /Rect [10 20 60 30] >>"); + let r = annot_entries(&doc, 0)[0].as_ref().expect("an indirect entry"); + doc.update_dict(r, |d| { + d.set( + b"Rect".to_vec(), + Object::Array(vec![ + Object::Real(10.0), + Object::Real(20.0), + Object::Real(60.0), + Object::Real(30.0), + Object::Real(9.0), + Object::Real(-9.5), + ]), + ); + }) + .expect("the entry is a dictionary"); + + pdfcraft_annot::move_annotation(&mut doc, 0, 0, 5.0, 7.0, &Meta { date: None, id: "m".into() }).expect("the comment is not locked"); + let d = dict_of(&doc, &annot_entries(&doc, 0)[0]).expect("a dictionary"); + let stored = nums(&doc, &d, b"Rect").expect("six numbers"); + assert_eq!(stored, vec![15.0, 27.0, 65.0, 37.0, 9.0, -9.5], "four shift, two strays do not"); + + // It survives a save that way, and the comment list still cannot use such a rectangle. + let (file, reopened) = save_and_reopen(&doc, Save::FullTable); + let stored_again = bytes::numbers_of(&file, "Rect"); + assert_eq!(stored_again.first(), Some(&vec![15.0, 27.0, 65.0, 37.0, 9.0, -9.5]), "the file keeps all six"); + let listed = summaries(&reopened); + assert_eq!(listed.len(), 1, "still a comment"); + assert_eq!(listed[0].rect, [0.0, 0.0, 0.0, 0.0], "and still not a usable position"); +} + +/// A link area is checked before anything is written: it needs finite corners whose span is at +/// least two points in both directions. Two different reasons, two different messages — and in +/// every case the page gains no entry. +#[test] +fn a_link_area_that_is_too_small_or_broken_is_refused_before_it_is_written() { + let cases = [ + ("one point wide", [10.0, 20.0, 11.0, 40.0], "too small"), + ("zero height", [10.0, 20.0, 50.0, 20.0], "too small"), + ("a NaN corner", [f64::NAN, 1.0, 50.0, 60.0], "finite coordinates"), + ("corners whose span overflows", [-1e308, 1.0, 1e308, 60.0], "too small or too large"), + ]; + for (label, rect, want_in_message) in cases { + let mut doc = blank(2); + let e = links::add(&mut doc, 0, rect, &links::LinkAction::Page(1), &links::LinkStyle::default()).err(); + let msg = match &e { + Some(AnnotError::Invalid(m)) => m.clone(), + other => panic!("{label}: expected Invalid, got {other:?}"), + }; + assert!(msg.contains(want_in_message), "{label}: message {msg:?} should mention {want_in_message:?}"); + assert!(annot_entries(&doc, 0).is_empty(), "{label}: nothing was written"); + assert!(links::list(&doc).is_empty(), "{label}: no link to list"); + } +} + +// ── hostile numbers handed to the builder ───────────────────────────────────────────────────── + +/// Non-finite style and geometry must be refused before anything is written: no partial object, no +/// `NaN` or exponent token in the file. (`AGENTS.md` §4: guard NaN/inf casts.) +#[test] +fn non_finite_builder_input_is_refused_and_leaves_the_document_untouched() { + let shapes = [ + ("nan rect", Shape::Rectangle { rect: [f64::NAN, 10.0, 40.0, 30.0] }), + ("infinite rect", Shape::Rectangle { rect: [f64::NEG_INFINITY, 10.0, 40.0, 30.0] }), + ("nan quad", Shape::TextMarkup { kind: pdfcraft_annot::Markup::Highlight, quads: vec![[10.0, 10.0, f64::NAN, 20.0, 10.0, 5.0, 30.0, 5.0]] }), + ("far away note", Shape::Note { at: [1e308, 2.0], icon: NoteIcon::Note }), + ("nan ink", Shape::Ink { strokes: vec![vec![[f64::NAN, 1.0], [2.0, 3.0]]] }), + ("empty ink", Shape::Ink { strokes: vec![vec![]] }), + ( + "degenerate line", + Shape::Line { from: [10.0, 10.0], to: [10.0, 10.5], start: pdfcraft_annot::LineEnding::None, end: pdfcraft_annot::LineEnding::None }, + ), + ("nan polygon", Shape::Polygon { vertices: vec![[0.0, 0.0], [f64::INFINITY, 10.0], [5.0, 5.0]], cloud: false }), + ("two point polygon", Shape::Polygon { vertices: vec![[0.0, 0.0], [10.0, 10.0]], cloud: false }), + ( + "nan callout", + Shape::Callout { + rect: [10.0, 10.0, 40.0, 30.0], + knee: [f64::NAN, 0.0], + point: [0.0, 0.0], + font_size: 12.0, + ending: pdfcraft_annot::LineEnding::None, + }, + ), + ("no quads", Shape::TextMarkup { kind: pdfcraft_annot::Markup::StrikeOut, quads: vec![] }), + ]; + for (label, shape) in shapes { + let mut doc = blank(1); + let e = add_annotation( + &mut doc, + &NewAnnotation { page: 0, shape, style: Style::default(), contents: "x".into(), author: "A".into() }, + &Meta { date: None, id: "i".into() }, + ) + .err(); + assert!(matches!(e, Some(AnnotError::Invalid(_))), "{label}: refused with Invalid, got {e:?}"); + assert!(annot_entries(&doc, 0).is_empty(), "{label}: nothing was written"); + // The refusal must not corrupt the document either: it still saves and reloads empty. + let (_, reopened) = save_and_reopen(&doc, Save::Incremental); + assert!(summaries(&reopened).is_empty(), "{label}: the file is still clean"); + } + + for (label, style) in [ + ("nan opacity", Style { color: [0.0, 0.0, 0.0], opacity: f64::NAN, width: 1.0, fill: None }), + ("infinite opacity", Style { color: [0.0, 0.0, 0.0], opacity: f64::INFINITY, width: 1.0, fill: None }), + ("nan colour", Style { color: [f64::NAN, 0.0, 0.0], opacity: 1.0, width: 1.0, fill: None }), + ("nan width", Style { color: [0.0, 0.0, 0.0], opacity: 1.0, width: f64::NAN, fill: None }), + ] { + let mut doc = blank(1); + let e = add_annotation( + &mut doc, + &NewAnnotation { page: 0, shape: Shape::Rectangle { rect: [10.0, 10.0, 40.0, 30.0] }, style, contents: "x".into(), author: "A".into() }, + &Meta { date: None, id: "i".into() }, + ) + .err(); + assert_eq!(e.as_ref(), Some(&AnnotError::Invalid("invalid style".into())), "{label}"); + assert!(annot_entries(&doc, 0).is_empty(), "{label}: nothing was written"); + } + + // Edits take the same care: moving by a non-finite offset is refused and leaves geometry alone. + let mut doc = blank(1); + add_annotation( + &mut doc, + &NewAnnotation { + page: 0, + shape: Shape::Rectangle { rect: [10.0, 20.0, 60.0, 45.0] }, + style: Style::default(), + contents: "keep".into(), + author: "A".into(), + }, + &Meta { date: None, id: "ok".into() }, + ) + .expect("adds"); + let before = summaries(&doc)[0].rect; + assert_eq!( + pdfcraft_annot::move_annotation(&mut doc, 0, 0, f64::NAN, 1.0, &Meta { date: None, id: "m".into() }).err(), + Some(AnnotError::Invalid("invalid offset".into())) + ); + assert_eq!(summaries(&doc)[0].rect, before, "a refused move does not shift the comment"); + assert_eq!( + pdfcraft_annot::set_rect(&mut doc, 0, 0, [f64::NAN, 0.0, 1e308, 1e308], &Meta { date: None, id: "m".into() }).err().as_ref(), + Some(&AnnotError::Invalid("invalid rectangle (too small)".into())) + ); + assert_eq!(summaries(&doc)[0].rect, before, "a refused resize does not shift the comment"); +} + +/// Attachment input is checked too: a blank file name is refused with an actionable message and +/// writes nothing, so no half-built file specification is left in the document. +#[test] +fn an_attachment_needs_a_name_and_leaves_nothing_behind_when_it_has_none() { + for name in ["", " ", "\t"] { + let mut doc = blank(1); + let e = add_annotation( + &mut doc, + &NewAnnotation { + page: 0, + shape: Shape::Attachment { at: [10.0, 700.0], icon: AttachIcon::Paperclip, file: name.into(), data: b"x".to_vec() }, + style: Style::default(), + contents: String::new(), + author: "A".into(), + }, + &Meta { date: None, id: "a".into() }, + ) + .err(); + assert_eq!(e.as_ref(), Some(&AnnotError::Invalid("the attached file needs a name".into())), "{name:?}"); + assert!(annot_entries(&doc, 0).is_empty(), "no orphan file specification for {name:?}"); + } +} + +// ── fields that carry no magnitude screen (recorded, not endorsed) ──────────────────────────── + +/// This is a MAGNITUDE story, not a one-field story. `rect_for` checks the rectangle of every +/// variant but passes `Shape::CustomStamp { size }` and `Shape::TypedSignature { contours }` +/// straight into `/PCPictureSize` and `/PCOutline` (`create.rs:62-82`, `create.rs:278`, +/// `create.rs:285`) with no +/// magnitude screen whatsoever — and width gets none either. The only style guard on the create +/// path (`create.rs:416`) reads `!finite(&style.color) || !style.opacity.is_finite() +/// || !style.width.is_finite()`: `finite()` (`create.rs:17-19`, i.e. `is_finite() && abs() < 1e7`) +/// magnitude-screens `color` ALONE, while `opacity` and `width` are checked for non-finiteness +/// only. So even the one cap that exists sits at ten million, far below what a reader can turn +/// into an integer. Measured with qpdf's check (`pikepdf.Job(["--check", , "/dev/null"])`, +/// warnings on process stderr, exit code 3). Read that exit code carefully: **3 is qpdf's warning +/// status**, printed together with "operation succeeded with warnings", so the check still completes +/// and writes its output — it is not a hard failure (libqpdf: 0 = no errors or warnings, +/// 2 = errors detected, 3 = warnings detected; a clean file returns 0 with no stderr at all). +/// Every warning probe in this file returns 3 — the three overflow cases below and the +/// unknown-token probe documented at `:155-157` above — so the exit code alone does not separate +/// them from each other; the warning text does. The 9,999,999 control below is the only probe +/// that returns 0. Re-measurement trap: `Job.stderr` stays `None` even when qpdf warns, because +/// the warnings go to the inherited process stderr — redirect at shell level or you will report +/// "no warnings" from a file that produced them. Measured per field, each file written by THIS +/// crate's own writer path: +/// +/// `/BS /W` = 1e299 on an Oval: qpdf reports `object 4/0: error reading object: +/// overflow/underflow converting <1 followed by 299 digits> to 64-bit integer`. +/// +/// `/PCPictureSize` = 1e300 plus NaN: same message. File 1198 B, sha256 +/// 357946a6580e7c13fbcf3c80c396cd80f961a53e55aea9e11dff5e284f759e07, 301 digits confirmed. +/// +/// `/PCOutline` = 1e300: same message. +/// +/// `/BS /W` = 9999999: clean, exit code 0 — because that value has few enough digits for a +/// reader's 64-bit integer conversion (which tops out near 9.2e18), NOT because this crate caps +/// it: width never passes through `finite()`, so the ten-million figure plays no part here. The +/// boundary that matters is the reader's integer range, and it sits far above anything a real +/// border width could be. Measured here too: `/BS /W` = 1e9 is accepted and written verbatim as +/// `1000000000`, which is well past any sane border yet still parseable — the failure only +/// begins when the digits outrun a 64-bit conversion. +/// +/// So ANY annotation number of sufficient magnitude can make the whole object unreadable to a +/// third-party reader — width included, not just stamp payload. Two measurement notes that +/// matter when re-running: `pikepdf.open()` alone prints nothing for these files and still +/// reports `/Annots` length 1, while resolving `/Annots[0]` yields **null** and stays null after +/// qpdf re-saves — a listed-but-null entry is exactly what silent corruption looks like. qpdf +/// classifies it as a WARNING and its open still reports success; pikepdf puts `WARNING:` on a +/// line of its own, so grepping raw stderr for one combined line misses it. What we did NOT +/// measure is what any particular viewer then shows a user — the null entry was observed, not a +/// renderer's behaviour. +/// Meanwhile our own `repair_log()` stays empty, which contradicts this project's rule that +/// dropped or repaired data must be recorded (`CLAUDE.md`, Fidelity). None of these probe files +/// is committed: any sample PDF would need its own `ATTRIBUTION.toml` entry (`AGENTS.md` §1), +/// which this change avoids — regenerate them from the `file` bytes bound below and re-measure. +/// +/// How far a caller can actually get there, checked in this workspace rather than assumed: only +/// `/BS /W` is reachable through a shipped path. The automation tools read `width` as any finite +/// number (`crates/automation/src/comments.rs:427-429` assigns `style.width = w.max(0.0)` after +/// `opt_num`, whose only filter is `is_finite()` at `crates/automation/src/json.rs:112-113`), +/// and the published schema sets `"minimum": 0` with no upper bound +/// (`crates/automation/src/tools.rs:774`) — so a script or MCP agent can write a file whose +/// annotation object qpdf refuses to parse. The desktop UI caps the same value at 0.5..=12.0 +/// (`crates/ui-egui/src/dialogs/comment_props.rs:240-243`, `0.5..=12.0`, or a 0.0 floor when a +/// font size is set), and `/PCPictureSize` / `/PCOutline` are computed +/// inside the engine — `crates/engine/src/edit/run.rs:331` takes the source image's pixel size, +/// scales it to a 200 pt natural box at `:335-339` and hands that size to the stamp shape at +/// `:343`, while contour sizing lives at `crates/engine/src/fill_sign.rs:14-20` (which does reject a +/// non-positive width) — so reaching those two needs a caller using the crates directly +/// rather than an app or tool action. The defect is therefore automation-reachable today, and not +/// reachable by clicking in the desktop app. +/// +/// Non-finite values are rewritten on the way out: `write_real` (`crates/cos/src/writer.rs:48`) +/// emits a literal `0` for any non-finite REAL that reaches it, which is the mechanism for +/// `size` and contour points. Colours are a different route — `rgb()` (`create.rs:13-15`) clamps +/// each component to `0.0..=1.0` BEFORE the writer sees it, so infinity becomes `1.0`, not `0` +/// (see the create-vs-edit case below). The assertions that follow pin only what we write. +/// +/// NOTE: these tests record current behaviour so a fix becomes visible. They assert nothing about +/// the result being correct — the values are wrong on the way in and quietly rewritten on the +/// way out. +#[test] +fn unvalidated_stamp_size_and_signature_contours_are_rewritten_silently_in_the_file() { + let mut doc = blank(1); + let picture = doc.add(Object::Dict(Dict::new())); + add_annotation( + &mut doc, + &NewAnnotation { + page: 0, + shape: Shape::CustomStamp { rect: [10.0, 20.0, 60.0, 50.0], name: "Sig".into(), picture, image: true, size: (1e300, f64::NAN) }, + style: Style::default(), + contents: String::new(), + author: "A".into(), + }, + &Meta { date: None, id: "cs".into() }, + ) + .expect("the size is not validated, so the comment is accepted"); + + let (file, reopened) = save_and_reopen(&doc, Save::FullTable); + let stored = bytes::numbers_of(&file, "PCPictureSize"); + assert_eq!(stored.len(), 1, "one /PCPictureSize array in the file"); + assert_eq!(stored[0][1], 0.0, "NaN was written as 0 ({:?})", stored[0]); + assert!(stored[0][0] > 1e299, "the huge size was written rather than refused ({:?})", stored[0][0]); + assert!(doc.repair_log().is_empty() && reopened.repair_log().is_empty(), "nothing recorded about either substitution"); + // The digits are really there: 301 of them, no exponent form. + let pos = file.windows(b"/PCPictureSize".len()).position(|w| w == b"/PCPictureSize").expect("the key is in the file"); + let run = &file[pos..]; + let digits = run.iter().take(400).filter(|b| b.is_ascii_digit()).count(); + assert!(digits > 300, "a 301-digit decimal was written to the file ({digits} digits seen)"); + + let mut doc2 = blank(1); + add_annotation( + &mut doc2, + &NewAnnotation { + page: 0, + shape: Shape::TypedSignature { rect: [10.0, 20.0, 60.0, 50.0], contours: vec![vec![[f64::NAN, 1.0], [2.0, 3.0], [4.0, f64::INFINITY]]] }, + style: Style::default(), + contents: String::new(), + author: "A".into(), + }, + &Meta { date: None, id: "ts".into() }, + ) + .expect("the contours are not validated either"); + let (file2, _) = save_and_reopen(&doc2, Save::FullTable); + let outline = bytes::numbers_of(&file2, "PCOutline"); + assert_eq!(outline.as_slice(), &[vec![0.0, 1.0, 2.0, 3.0, 4.0, 0.0]], "both non-finite contour points became 0"); +} + +/// The fill colour is screened differently on the two paths. `add_annotation` magnitude-screens +/// only `style.color`, through `finite()` (`create.rs:416`; the helper at `create.rs:17-19` is +/// `is_finite() && abs() < 1e7`), gives `opacity` and `width` plain finiteness checks, and never +/// screens `fill` at all; `set_fill` refuses the same value (`modify.rs:626-627`, "invalid fill +/// colour") — and that refusal calls `finite()` too, which is why it trips on anything from ten +/// million up as well as on NaN or infinity. The accepted value is then clamped component-wise by +/// `rgb()` (`create.rs:13-15`, `clamp(0.0, 1.0)`), so what lands in the file is the top of the +/// range: NaN survives clamping as NaN and `write_real` (`crates/cos/src/writer.rs:48`) then +/// emits a literal `0`, while infinity becomes `1.0`. Measured across magnitudes +/// in `the_same_huge_fill_is_accepted_on_create_and_refused_on_edit`, which pins +/// 1e7 / 1e8 / infinity as well. Border width and stroke colour behave symmetrically on both +/// paths — width is finiteness-checked only, so a huge width gets written rather than refused (see +/// the magnitude note above), and both paths clamp it at zero — while stamp `size` and signature +/// `contours` have no edit path at all, so only create can diverge for them. Pinned as current +/// behaviour, not as desired behaviour. +#[test] +fn a_nan_fill_is_accepted_on_create_and_refused_on_edit() { + let nan = [f64::NAN, 0.0, 0.0]; + let mut doc = blank(1); + add_annotation( + &mut doc, + &NewAnnotation { + page: 0, + shape: Shape::Rectangle { rect: [10.0, 20.0, 60.0, 40.0] }, + style: Style { color: [0.9, 0.1, 0.1], opacity: 1.0, width: 2.0, fill: Some(nan) }, + contents: String::new(), + author: "A".into(), + }, + &Meta { date: None, id: "nf".into() }, + ) + .expect("create does not screen the fill colour"); + let (file, reopened) = save_and_reopen(&doc, Save::FullTable); + let ic = bytes::numbers_of(&file, "IC"); + assert_eq!(ic.first(), Some(&vec![0.0, 0.0, 0.0]), "the NaN components were written as zeros"); + assert_eq!(props(&reopened, 0, 0).and_then(|p| p.fill), Some([0.0, 0.0, 0.0])); + + let e = pdfcraft_annot::set_fill(&mut reopened.clone(), 0, 0, Some(nan), &Meta { date: None, id: "nf2".into() }).err(); + assert_eq!(e.as_ref(), Some(&AnnotError::Invalid("invalid fill colour".into())), "the same value is refused two lines later in the same crate"); +} + +// ── generated damage, same rule: refuse or degrade, never panic ─────────────────────────────── + +/// proptest's assert macros cannot capture local names in their format strings, so the writer path +/// is formatted here and passed in explicitly. +fn tag(path: Save) -> String { + format!("{path:?}") +} + +/// The kinds of damage a stranger's annotation data can carry. Twelve wreck the dictionary of a +/// comment PdfCraft wrote, so the file stays structurally valid around one wrong entry; the +/// duplicate-entry kind instead repeats that comment's entry in the page's `/Annots`. +#[derive(Copy, Clone, Debug, PartialEq, Eq)] +enum Damage { + RectTooShort, + RectWrongType, + QuadPointsOddLength, + QuadPointsWrongType, + FlagsAsName, + OpacityOutOfRange, + SubtypeMissing, + PopupDangling, + ParentToMissingObject, + IrtSelfReference, + DuplicateEntryInAnnots, + InkListWrongShape, + VerticesOddLength, +} + +const DAMAGES: [Damage; 13] = [ + Damage::RectTooShort, + Damage::RectWrongType, + Damage::QuadPointsOddLength, + Damage::QuadPointsWrongType, + Damage::FlagsAsName, + Damage::OpacityOutOfRange, + Damage::SubtypeMissing, + Damage::PopupDangling, + Damage::ParentToMissingObject, + Damage::IrtSelfReference, + Damage::DuplicateEntryInAnnots, + Damage::InkListWrongShape, + Damage::VerticesOddLength, +]; + +/// Apply one damage. Twelve of the kinds wreck the annotation dictionary at `/Annots[index]` +/// itself; the duplicate-entry kind instead lists that entry twice in the page's `/Annots`. +fn damage(doc: &mut Document, index: usize, kind: Damage) { + let entries = annot_entries(doc, 0); + let Some(r) = entries.get(index).and_then(|e| e.as_ref()) else { return }; + if kind == Damage::DuplicateEntryInAnnots { + // The damage lives on the page, not the dictionary: the same entry object appears twice in + // `/Annots`, so the page lists one annotation dictionary through two slots. Routed through + // `set_annots`, the same writer the crate itself uses, so both storage shapes (array + // inline in the page, array behind a reference) are rewritten the way mainline rewrites. + let mut list = annot_entries(doc, 0); + if let Some(slot) = list.get(index).cloned() { + list.insert(index, slot); + let page = ObjRef::new(*page_object_numbers(doc).first().expect("the page exists"), 0); + set_annots(doc, page, list).expect("the page dictionary is editable"); + } + return; + } + doc.update_dict(r, |d| match kind { + Damage::RectTooShort => d.set(b"Rect".to_vec(), Object::Array(vec![Object::Real(10.0), Object::Real(20.0)])), + Damage::RectWrongType => { + d.set(b"Rect".to_vec(), Object::Array(vec![Object::name("a"), Object::name("b"), Object::name("c"), Object::name("d")])) + } + Damage::QuadPointsOddLength => d.set(b"QuadPoints".to_vec(), Object::Array((0..7).map(|i| Object::Real(i as f64)).collect())), + Damage::QuadPointsWrongType => d.set(b"QuadPoints".to_vec(), Object::Array(vec![Object::Real(1.0), Object::name("notanumber")])), + Damage::FlagsAsName => d.set(b"F".to_vec(), Object::name("Locked")), + Damage::OpacityOutOfRange => d.set(b"CA".to_vec(), Object::Real(4.25)), + Damage::SubtypeMissing => { + d.remove(b"Subtype"); + } + Damage::PopupDangling => d.set(b"Popup".to_vec(), Object::Ref(ObjRef::new(9997, 0))), + Damage::ParentToMissingObject => d.set(b"Parent".to_vec(), Object::Ref(ObjRef::new(9998, 0))), + Damage::IrtSelfReference => d.set(b"IRT".to_vec(), Object::Ref(r)), + Damage::DuplicateEntryInAnnots => unreachable!("this damage edits the page, not the dictionary"), + Damage::InkListWrongShape => d.set(b"InkList".to_vec(), Object::Array(vec![Object::Real(5.0), Object::name("notastroke")])), + Damage::VerticesOddLength => d.set(b"Vertices".to_vec(), Object::Array(vec![Object::Real(1.0), Object::Real(2.0), Object::Real(3.0)])), + }) + .expect("the entry is an annotation dictionary"); +} + +proptest! { + #![proptest_config(ProptestConfig::with_cases(64))] + + /// For any single damage, and any of the three writer paths: opening, reading every annotation + /// entry point, re-saving and reopening must all complete without a panic. Alongside that the + /// test insists on something positive, so it cannot pass by reading nothing at all — an undamaged + /// second comment on the same page keeps its exact rectangle, and the damaged comment is either + /// listed or skipped but never half-parsed into a crash. + #[test] + fn damaged_annotations_never_panic(kind in prop::sample::select(DAMAGES.to_vec()), extra_annot in 0usize..=2) { + // Build a page holding one comment that will be damaged plus `extra_annot` clean ones. + let mut doc = blank(1); + for i in 0..=extra_annot { + add_annotation(&mut doc, &NewAnnotation { page: 0, shape: Shape::TextMarkup { kind: pdfcraft_annot::Markup::Highlight, quads: vec![[20.0 + 10.0 * i as f64, 500.0, 80.0 + 10.0 * i as f64, 500.0, 20.0 + 10.0 * i as f64, 486.0, 80.0 + 10.0 * i as f64, 486.0]] }, style: Style::default(), contents: format!("ok{i}"), author: "Ada".into() }, &Meta { date: None, id: format!("ok{i}") }).expect("adds"); + } + let clean_rect = summaries(&doc).iter().map(|s| s.rect).collect::>(); + damage(&mut doc, 0, kind); + + for path in [Save::Incremental, Save::FullTable, Save::FullStreams] { + let (_, reopened) = save_and_reopen(&doc, path); + read_everything(&reopened); + // The undamaged comments are untouched by the damage and its save. + let after = summaries(&reopened); + // A comment stops being listed only when the damage removes what makes it a comment — + // its `/Subtype` (measured, not assumed). The other damages all leave it listed; the + // duplicate-entry damage lists one comment through two slots, so it adds a listing. + let want_listed = clean_rect.len() - usize::from(kind == Damage::SubtypeMissing) + usize::from(kind == Damage::DuplicateEntryInAnnots); + prop_assert_eq!(after.len(), want_listed, "damage {k} on {p}: listed comment count", k = format!("{kind:?}"), p = tag(path)); + // Every undamaged comment keeps its exact rectangle through the damage and the rewrite. + for r in &clean_rect[1..] { + prop_assert!(after.iter().any(|s| s.rect == *r), "damage {k} on {p}: the clean comment at {r:?} is gone", k = format!("{kind:?}"), p = tag(path)); + } + // And deleting by index never panics, whatever the damage was. + let mut cut = reopened.clone(); + for i in 0..clean_rect.len() + 1 { + let _ = delete_annotation(&mut cut, 0, i); + } + } + } +} + +/// Read side, measured: a negative border width arriving from another tool is reported unchanged +/// by the public API. Our own writer clamps negatives to 0 (`create.rs:47`, `create.rs:216`), and +/// the helper `border_width_of` (`modify.rs:498-500`) does apply `.max(0.0)` — but the property +/// read path used here (`props()` -> `info.rs:227-231`) takes `/BS /W` raw for non-FreeText +/// subtypes, so a foreign file +/// declaring -3 comes back as -3.0. Pinned because the asymmetry is visible in the public API: +/// what we refuse to keep, we are willing to report. (Compare `/CA`, likewise unclamped on read.) +#[test] +fn foreign_negative_border_width_is_reported_as_written() { + let doc = open(&[ + b"<< /Type /Catalog /Pages 2 0 R >>", + b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>", + b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Annots [4 0 R] >>", + b"<< /Type /Annot /Subtype /Square /Rect [10 20 60 30] /BS << /S /S /W -3 >> >>", + ]); + let p = props(&doc, 0, 0).expect("the annotation is readable"); + assert_eq!( + p.width, + Some(-3.0), + "props() reports /BS /W as written; note border_width_of (modify.rs:498-500) does clamp at zero, so this is path-specific" + ); + assert!(doc.repair_log().is_empty(), "and that neither is recorded as a repair"); +} + +/// The create-vs-edit divergence is wider than the NaN case: the edit-side refusal begins at `1e7` +/// **in magnitude**, because `finite()` (`create.rs:17-19`, called by the edit path at `modify.rs:626`) +/// tests `abs() < 1e7`, so a component of magnitude exactly ten million is refused (positive or +/// negative) while 9,999,999 passes — what THIS test pins is the positive side (1e7, 1e8, infinity); +/// a negative-magnitude row is not pinned here, only reasoned from `abs()` (independently measured +/// in review round 5, which found `-1e7` refused on the edit path) +/// while create never screens `fill` at all, so any value whatsoever is accepted +/// there. Measured, not assumed — the +/// expected `/IC` components below are what this crate's writer actually produced on re-run +/// (clamping happens in `rgb()`, `create.rs:13-15`, so an accepted huge component lands at 1.0). +#[test] +fn the_same_huge_fill_is_accepted_on_create_and_refused_on_edit() { + let cases: [([f64; 3], &[f64; 3]); 3] = + [([1e7, 0.0, 0.0], &[1.0, 0.0, 0.0]), ([1e8, 0.0, 0.0], &[1.0, 0.0, 0.0]), ([f64::INFINITY; 3], &[1.0, 1.0, 1.0])]; + for (probe, want) in cases { + let mut doc = blank(1); + add_annotation( + &mut doc, + &NewAnnotation { + page: 0, + shape: Shape::Rectangle { rect: [10.0, 20.0, 60.0, 40.0] }, + style: Style { color: [0.9, 0.1, 0.1], opacity: 1.0, width: 2.0, fill: Some(probe) }, + contents: String::new(), + author: "A".into(), + }, + &Meta { date: None, id: "huge-fill".into() }, + ) + .expect("create does not screen the fill colour"); + let (file, reopened) = save_and_reopen(&doc, Save::FullTable); + let ic = bytes::numbers_of(&file, "IC"); + assert_eq!(ic.first().map(Vec::as_slice), Some(want.as_slice()), "{probe:?}: create stores the clamped colour"); + assert_eq!(props(&reopened, 0, 0).and_then(|p| p.fill), Some([want[0], want[1], want[2]]), "{probe:?}: read-back matches what was written",); + let e = pdfcraft_annot::set_fill(&mut reopened.clone(), 0, 0, Some(probe), &Meta { date: None, id: "huge-fill-2".into() }).err(); + assert_eq!(e.as_ref(), Some(&AnnotError::Invalid("invalid fill colour".into())), "{probe:?}: the same value is refused on the edit path",); + } +} diff --git a/crates/annot/tests/properties.proptest-regressions b/crates/annot/tests/properties.proptest-regressions new file mode 100644 index 0000000000..341ba3ff3d --- /dev/null +++ b/crates/annot/tests/properties.proptest-regressions @@ -0,0 +1,6 @@ +# Seeds for failure cases proptest has generated in the past. It is +# automatically read and these particular cases re-run before any +# novel cases are generated. +# +# It is recommended to check this file in to source control so that +# everyone who runs the test benefits from these saved cases. diff --git a/crates/annot/tests/properties.rs b/crates/annot/tests/properties.rs new file mode 100644 index 0000000000..8efb6b7046 --- /dev/null +++ b/crates/annot/tests/properties.rs @@ -0,0 +1,417 @@ +//! Property tests for annotation structural fidelity, stated over the **saved bytes**. +//! +//! What is proven here is a rule about files, not about structs: for every generated comment the +//! writer produces bytes that (a) hold the geometry as fixed-decimal number arrays, and (b) parse +//! back — with our reader *and* with vendored hayro-syntax — into dictionaries whose numbers, +//! names, flags and opacity equal values computed in this file from the input plus ISO 32000-2. +//! Two things make that more than "compare an object to itself": the expectations never read the +//! pre-save document, and the number tokens are re-parsed from raw `Vec` by `support::bytes`, +//! a strict scanner that is not `pdfcraft-cos`. +//! +//! Geometry comes from a half-point grid (`x = k / 2`, |k| ≤ 450). Every such value has an exact +//! decimal form and survives Flate, `f64` arithmetic and the writer's shortest-round-trip +//! formatting, so a mismatch means data changed shape on disk rather than drifting by an ulp. +//! Text is generated from an alphabet spanning ASCII punctuation, Latin-1 letters and CJK — the +//! cases where PDF's two string encodings disagree. +//! +//! Not covered, deliberately: appearance-stream content (the five open appearance PRs named in +//! `tests/round_trip.rs`), and the comment-list ordering rule of `summaries`, which is +//! deterministic and checked there instead. + +mod support { + pub mod bytes; + pub mod fixture; +} + +use pdfcraft_annot::{LineEnding, Markup, Meta, NewAnnotation, NoteIcon, Shape, Style, add_annotation, props, summaries}; +use pdfcraft_cos::Document; +use proptest::prelude::*; + +use support::bytes; +use support::fixture::{ + FLAG_NO_ROTATE, FLAG_NO_ZOOM, FLAG_PRINT, Save, annot_entries, blank, dict_of, name_of, num, nums, page_object_numbers, save_and_reopen, str_of, +}; + +/// proptest's assert macros cannot capture local names inside their format strings (the message is +/// built in proptest's own expansion scope), so every message here passes what it names explicitly. +fn tag(path: Save) -> String { + format!("{path:?}") +} + +/// A coordinate on the half-point grid. +fn coord() -> impl Strategy { + any::().prop_map(|k| f64::from(k.rem_euclid(901) - 450) / 2.0) +} + +/// A rectangle as four grid coordinates, corners in any order (the writer normalises). +fn rect4() -> impl Strategy { + (coord(), coord(), coord(), coord()).prop_map(|(x0, y0, x1, y1)| [x0, y0, x1.max(x0 + 1.0), y1.max(y0 + 1.0)]) +} + +/// A quadrilateral: eight grid numbers, in Acrobat's corner order (§12.5.6.10). +fn quad8() -> impl Strategy { + prop::array::uniform8(coord()) +} + +/// Text from an alphabet where PDF's two string encodings disagree: printable ASCII (including the +/// punctuation a literal string has to escape around), Latin-1 letters beyond 0x7F, and CJK. +const TEXT_CHARS: &str = "abZq07 .,:;!?-_%$#*+=~()[]<>&@^|\n\t\u{e9}\u{fc}\u{f1}\u{df}\u{a7}\u{c0}\u{f6}\u{301}\u{65e5}\u{672c}"; + +fn text_of(max_len: usize) -> impl Strategy { + prop::collection::vec(prop::sample::select(TEXT_CHARS.chars().collect::>()), 0..=max_len).prop_map(|c| c.into_iter().collect()) +} + +/// ASCII-only identity strings: `/NM` is a thread key other readers match literally, so keep it +/// free of characters that would make a byte-level comparison ambiguous. +fn id_of(max_len: usize) -> impl Strategy { + prop::collection::vec( + prop::sample::select("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._".chars().collect::>()), + 0..=max_len, + ) + .prop_map(|c| c.into_iter().collect()) +} + +/// A grid coordinate's PDF decimal form, computed here rather than by the writer: integers without +/// a fraction, half-points with one digit (§7.3.3). +fn token(v: f64) -> String { + if v.fract() == 0.0 { format!("{}", v as i64) } else { format!("{v:.1}") } +} + +fn rect_token(r: &[f64]) -> String { + format!("/Rect [{}]", r.iter().map(|v| token(*v)).collect::>().join(" ")) +} + +/// Normalise as §12.5.4.2 requires a rectangle to be stored: lower-left then upper-right. +fn norm(r: [f64; 4]) -> Vec { + vec![r[0].min(r[2]), r[1].min(r[3]), r[0].max(r[2]), r[1].max(r[3])] +} + +/// Bounds of a point list, computed here rather than by the crate. +fn bounds_of(points: &[[f64; 2]]) -> Vec { + let mut out = [f64::MAX, f64::MAX, f64::MIN, f64::MIN]; + for p in points { + out[0] = out[0].min(p[0]); + out[1] = out[1].min(p[1]); + out[2] = out[2].max(p[0]); + out[3] = out[3].max(p[1]); + } + out.to_vec() +} + +fn meta(id: String) -> Meta { + Meta { date: Some("D:20261001120000Z".into()), id } +} + +fn comment(page: usize, shape: Shape, style: Style, contents: String, author: String) -> NewAnnotation { + NewAnnotation { page, shape, style, contents, author } +} + +proptest! { + #![proptest_config(ProptestConfig::with_cases(128))] + + /// A rectangle comment's `/Rect` reaches the file as four fixed-decimal numbers equal to the + /// normalised input, and parses back to exactly those numbers on all three writer paths. The + /// raw-token claim runs where the bytes are uncompressed, so it is a claim about the file. + #[test] + fn a_rectangles_stored_rectangle_is_the_input_normalised(rect in rect4(), id in id_of(12)) { + for path in [Save::Incremental, Save::FullTable, Save::FullStreams] { + let mut doc = blank(1); + add_annotation(&mut doc, &comment(0, Shape::Rectangle { rect }, Style::default(), String::new(), "Ada".into()), &meta(id.clone())) + .expect("a normalised box is at least a point wide"); + let (file, reopened) = save_and_reopen(&doc, path); + let want = norm(rect); + let entries = annot_entries(&reopened, 0); + prop_assert_eq!(entries.len(), 1, "{}: exactly the one comment", tag(path)); + let d = dict_of(&reopened, &entries[0]).expect("one annotation"); + let stored = nums(&reopened, &d, b"Rect"); + prop_assert_eq!(stored.as_deref(), Some(want.as_slice()), "{}: /Rect must be the normalised input {:?}", tag(path), rect); + if path != Save::FullStreams { + let t = rect_token(&want); + prop_assert!(file.windows(t.len()).any(|w| w == t.as_bytes()), "{}: {:?} must be written exactly as {}", tag(path), rect, t); + prop_assert!(bytes::numbers_of(&file, "Rect").contains(&want), "{}: the file itself must hold {:?}", tag(path), want); + } + } + } + + /// Markup keeps every quadrilateral, in order: `/QuadPoints` holds all 8·n numbers and `/Rect` + /// is the bounds of all of them, not just the first quad's. + #[test] + fn markup_keeps_every_quadrilateral(quads in prop::collection::vec(quad8(), 1..=3)) { + let flat: Vec = quads.concat(); + let points: Vec<[f64; 2]> = quads.iter().flat_map(|q| q.as_chunks::<2>().0.iter().copied()).collect(); + let want_rect = bounds_of(&points); + for path in [Save::Incremental, Save::FullTable, Save::FullStreams] { + let mut doc = blank(1); + add_annotation(&mut doc, &comment(0, Shape::TextMarkup { kind: Markup::Highlight, quads: quads.clone() }, Style::default(), String::new(), "Ada".into()), &meta("q".into())) + .expect("adds"); + let (file, reopened) = save_and_reopen(&doc, path); + let entries = annot_entries(&reopened, 0); + prop_assert_eq!(entries.len(), 1, "{}: exactly the one comment", tag(path)); + let d = dict_of(&reopened, &entries[0]).expect("one annotation"); + let stored = nums(&reopened, &d, b"QuadPoints"); + prop_assert_eq!(stored.as_deref(), Some(flat.as_slice()), "{}: all {} quad numbers, in order", tag(path), flat.len()); + let stored_rect = nums(&reopened, &d, b"Rect"); + prop_assert_eq!(stored_rect.as_deref(), Some(want_rect.as_slice()), "{}: /Rect bounds every quad", tag(path)); + prop_assert_eq!(summaries(&reopened).first().map(|s| s.quads.len()), Some(quads.len()), "{}: the comment list chunks them the same way", tag(path)); + if path != Save::FullStreams { + prop_assert!(bytes::numbers_of(&file, "QuadPoints").contains(&flat), "{}: {} numbers must be in the file", tag(path), flat.len()); + } + } + } + + /// `/CA` obeys its rule whatever the caller asked for: written only when clamped opacity is + /// below 1, and equal to the clamped value. A non-finite opacity is refused before any object + /// is created, so the file never holds a number PDF cannot write. + #[test] + fn opacity_and_flags_follow_their_rules(opacity in any::()) { + let mut doc = blank(1); + let added = add_annotation(&mut doc, &comment(0, Shape::Rectangle { rect: [10.0, 10.0, 60.0, 40.0] }, Style { color: [0.5, 0.25, 0.75], opacity, width: 1.0, fill: None }, String::new(), "Ada".into()), &meta("c".into())); + if !opacity.is_finite() { + prop_assert!(added.is_err(), "a non-finite opacity ({:?}) must be refused, not written", opacity); + return Ok(()); + } + let _ = added.expect("adds"); + let want = opacity.clamp(0.0, 1.0); + for path in [Save::Incremental, Save::FullTable, Save::FullStreams] { + let (file, reopened) = save_and_reopen(&doc, path); + let entries = annot_entries(&reopened, 0); + prop_assert_eq!(entries.len(), 1, "{}: exactly the one comment", tag(path)); + let d = dict_of(&reopened, &entries[0]).expect("one annotation"); + if want < 1.0 { + prop_assert_eq!(num(&reopened, &d, b"CA"), Some(want), "{}: opacity {:?} clamps to {:?}", tag(path), opacity, want); + prop_assert_eq!(props(&reopened, 0, 0).map(|p| p.opacity), Some(want), "{}: reported opacity", tag(path)); + if path != Save::FullStreams { + prop_assert_eq!(bytes::scalars_of(&file, "CA").first().copied(), Some(want), "{}: /CA must be in the file as {}", tag(path), token(want)); + } + } else { + prop_assert!(d.get(b"CA").is_none(), "{}: full opacity writes no /CA (it is the default)", tag(path)); + } + let flags = d.int(b"F").unwrap_or_default(); + prop_assert_ne!(flags & FLAG_PRINT, 0, "{}: a comment keeps its Print bit (§12.5.3)", tag(path)); + let colour = nums(&reopened, &d, b"C"); + prop_assert_eq!(colour.as_deref(), Some(&[0.5, 0.25, 0.75][..]), "{}: colours pass through unchanged", tag(path)); + } + } + + /// Text, author and id survive exactly — including the empty string. `/Contents` is stored even + /// when empty (an empty PDF string), while `/T` and `/NM` follow the crate's emptiness rule: + /// no author or id means the key is not written at all. + #[test] + fn text_author_and_id_survive_exactly(contents in text_of(40), author in text_of(16), id in id_of(12)) { + for path in [Save::Incremental, Save::FullTable] { + let mut doc = blank(1); + add_annotation(&mut doc, &comment(0, Shape::Rectangle { rect: [10.0, 20.0, 70.0, 45.0] }, Style::default(), contents.clone(), author.clone()), &meta(id.clone())) + .expect("adds"); + let (file, reopened) = save_and_reopen(&doc, path); + let entries = annot_entries(&reopened, 0); + prop_assert_eq!(entries.len(), 1, "{}: exactly the one comment", tag(path)); + let d = dict_of(&reopened, &entries[0]).expect("one annotation"); + let storedcontents = str_of(&reopened, &d, b"Contents"); + prop_assert_eq!(storedcontents.as_deref(), Some(contents.as_str()), "{}: /Contents round trip for {:?}", tag(path), contents); + let storedid = str_of(&reopened, &d, b"NM"); + if id.is_empty() { + prop_assert!(storedid.is_none(), "{}: an empty id writes no /NM, got {storedid:?}", tag(path)); + } else { + prop_assert_eq!(storedid.as_deref(), Some(id.as_str()), "{}: /NM round trip", tag(path)); + } + prop_assert!(bytes::texts_of(&file, "Contents").contains(&contents), "{:?} must appear in the file as a PDF string", contents); + if id.is_empty() { + prop_assert!(bytes::texts_of(&file, "NM").is_empty(), "{}: no /NM in the file for an empty id", tag(path)); + } else { + prop_assert!(bytes::texts_of(&file, "NM").contains(&id), "{:?} must appear in the file as a PDF string", id); + } + if author.is_empty() { + prop_assert!(d.get(b"T").is_none(), "{}: an empty author writes no /T", tag(path)); + } else { + let storedauthor = str_of(&reopened, &d, b"T"); + prop_assert_eq!(storedauthor.as_deref(), Some(author.as_str()), "{}: /T round trip for {:?}", tag(path), author); + } + } + } + + /// Several comments on one page keep their count, their order and all of their rectangles — + /// including the raw-file claim that the list of `/Rect` arrays is exactly what was added. + #[test] + fn several_rectangles_keep_count_order_and_geometry(rects in prop::collection::vec(rect4(), 1..=6), opacity_bits in any::()) { + let mut doc = blank(1); + let mut want_rects = Vec::new(); + for (i, r) in rects.iter().enumerate() { + // Two bits of the byte give opacities 1.0, 0.5, -0.5 and 0.0: written, clamped or absent. + let opacity = match opacity_bits & 3 { + 0 => 1.0, + 1 => 0.5, + 2 => -0.5, + _ => 0.0, + }; + add_annotation(&mut doc, &comment(0, Shape::Rectangle { rect: *r }, Style { color: [0.9, 0.1, 0.1], opacity, width: 2.0, fill: None }, format!("c{i}"), "Ada".into()), &meta(format!("k{i}"))) + .expect("adds"); + want_rects.push(norm(*r)); + } + for path in [Save::Incremental, Save::FullTable, Save::FullStreams] { + let (file, reopened) = save_and_reopen(&doc, path); + let want = want_rects.clone(); + let entries = annot_entries(&reopened, 0); + prop_assert_eq!(entries.len(), want.len(), "{}: one object per comment", tag(path)); + let got: Vec> = entries.iter().filter_map(|e| dict_of(&reopened, e)).flat_map(|d| nums(&reopened, &d, b"Rect")).collect(); + prop_assert_eq!(got, want.clone(), "{}: the same rectangles in the same order", tag(path)); + prop_assert_eq!(summaries(&reopened).len(), want.len(), "{}: every comment is listed", tag(path)); + if path != Save::FullStreams { + prop_assert_eq!(bytes::numbers_of(&file, "Rect"), want, "{}: every rectangle is in the file", tag(path)); + } + } + } + + /// Sticky notes arrive with a pop-up partner, and the pairing is two references: so that means + /// they still point at each other after a save, that the count is always two per note, and + /// that the icon box stays 20 pt square at the position asked for. + #[test] + fn notes_always_bring_a_popup_that_points_back(at in prop::array::uniform2(coord()), n in 1usize..=3) { + let at = [at[0], at[1].max(25.0)]; + let mut doc = blank(n); + for p in 0..n { + add_annotation(&mut doc, &comment(p, Shape::Note { at, icon: NoteIcon::Comment }, Style::default(), String::new(), "Ada".into()), &meta(format!("n{p}"))) + .expect("adds"); + } + for path in [Save::Incremental, Save::FullTable, Save::FullStreams] { + let (_, reopened) = save_and_reopen(&doc, path); + let pages = page_object_numbers(&reopened); + prop_assert_eq!(pages.len(), n, "{}", tag(path)); + for p in 0..n { + let entries = annot_entries(&reopened, p); + prop_assert_eq!(entries.len(), 2, "{}: note and pop-up on page {}", tag(path), p); + let note = dict_of(&reopened, &entries[0]).expect("note dictionary"); + let pop = dict_of(&reopened, &entries[1]).expect("pop-up dictionary"); + let notekind = name_of(&reopened, ¬e, b"Subtype"); + prop_assert_eq!(notekind.as_deref(), Some("Text"), "{}", tag(path)); + let popupkind = name_of(&reopened, &pop, b"Subtype"); + prop_assert_eq!(popupkind.as_deref(), Some("Popup"), "{}", tag(path)); + prop_assert_eq!(pop.reference(b"Parent"), entries[0].as_ref(), "{}: /Parent back-reference", tag(path)); + prop_assert_eq!(note.reference(b"Popup"), entries[1].as_ref(), "{}: /Popup forward reference", tag(path)); + let iconbox = nums(&reopened, ¬e, b"Rect"); + prop_assert_eq!(iconbox.as_deref(), Some(&[at[0], at[1] - 20.0, at[0] + 20.0, at[1]][..]), "{}: the icon box for {:?}", tag(path), at); + let flags = note.int(b"F").unwrap_or_default(); + prop_assert_ne!(flags & (FLAG_NO_ZOOM | FLAG_NO_ROTATE), 0, "{}: a note icon neither scales nor rotates", tag(path)); + } + } + } + + /// An incremental save and a garbage-collecting full rewrite must describe the same comments. + /// Their bytes differ by design; what may not differ is what a reader learns from them. + #[test] + fn every_writer_path_reports_the_same_comments(rect in rect4(), contents in text_of(20), id in id_of(8)) { + let mut doc = blank(2); + let quad = [rect[0], rect[3], rect[2], rect[3], rect[0], rect[1], rect[2], rect[1]]; + add_annotation(&mut doc, &comment(1, Shape::TextMarkup { kind: Markup::Underline, quads: vec![quad] }, Style::default(), contents, "Ada".into()), &meta(id)) + .expect("adds"); + + let (_, inc) = save_and_reopen(&doc, Save::Incremental); + let (_, full) = save_and_reopen(&doc, Save::FullTable); + let (_, packed) = save_and_reopen(&doc, Save::FullStreams); + let describe = |d: &Document| -> (Vec, Vec>, Option) { + let dicts: Vec<_> = annot_entries(d, 1).iter().filter_map(|x| dict_of(d, x)).collect(); + ( + dicts.iter().map(|x| name_of(d, x, b"Subtype").unwrap_or_default()).collect(), + dicts.iter().flat_map(|x| nums(d, x, b"QuadPoints")).collect(), + dicts.first().and_then(|x| str_of(d, x, b"Contents")), + ) + }; + prop_assert_eq!(describe(&inc), describe(&full)); + prop_assert_eq!(describe(&full), describe(&packed)); + } + + /// Border width and interior colour reach the file as given, and a `None` fill leaves no `/IC` + /// behind — "no fill" is stored as absence, not as black. + /// + /// The range includes NEGATIVE widths on purpose: `add_annotation` screens width for + /// non-finiteness only (`crates/annot/src/create.rs:416` tests `style.width.is_finite()`; the + /// `abs() < 1e7` cap inside `finite()` at `create.rs:17-19` guards `color`, never width), so + /// negatives are accepted and then clamped by `max(0.0)` on the way to `/BS /W` (`create.rs:216`). + /// Sampling `0.0..` alone left both clamps untested while this test's name implied coverage. + /// The upper end stays modest deliberately: magnitude is not screened here either, so a huge + /// width would be written verbatim — that case is pinned in `malformed.rs`, not by this + /// property, whose job is the sign clamp and the fill/absence rules. + #[test] + fn width_and_fill_are_written_as_they_were_given(width in -4.0f64..12.0, fill in prop::option::of(prop::array::uniform3(0.0f64..1.0))) { + let mut doc = blank(1); + add_annotation(&mut doc, &comment(0, Shape::Oval { rect: [5.0, 5.0, 65.0, 35.0] }, Style { color: [1.0, 0.0, 0.0], opacity: 1.0, width, fill }, String::new(), "Ada".into()), &meta("f".into())) + .expect("adds"); + for path in [Save::Incremental, Save::FullTable] { + let (file, reopened) = save_and_reopen(&doc, path); + let entries = annot_entries(&reopened, 0); + prop_assert_eq!(entries.len(), 1, "{}: exactly the one comment", tag(path)); + let d = dict_of(&reopened, &entries[0]).expect("one annotation"); + let bs = d.get(b"BS").map(|o| reopened.resolve(o)).and_then(|o| o.as_dict().cloned()).expect("/BS"); + prop_assert_eq!(num(&reopened, &bs, b"W"), Some(width.max(0.0)), "{}: /BS /W for width {:?}", tag(path), width); + prop_assert_eq!(d.contains(b"IC"), fill.is_some(), "{}: /IC is present exactly when a fill was given", tag(path)); + prop_assert_eq!(props(&reopened, 0, 0).and_then(|p| p.width), Some(width.max(0.0)), "{}: reported width {:?}", tag(path), width); + prop_assert_eq!(props(&reopened, 0, 0).and_then(|p| p.fill), fill, "{}: /IC for {:?}", tag(path), fill); + let ic = bytes::numbers_of(&file, "IC"); + match fill { + Some(c) => prop_assert_eq!(ic.first(), Some(&vec![c[0], c[1], c[2]]), "{}: /IC must be in the file", tag(path)), + None => prop_assert!(ic.is_empty(), "{}: no /IC when unfilled, got {:?}", tag(path), ic), + } + } + } + + /// A line keeps its endpoints verbatim in `/L`, and the annotation's rectangle always spans + /// both of them — the one geometry rule a line must obey however wide its stroke or arrowheads + /// are drawn (§12.5.4.2). The padding itself lives in `appearance`, so it is not pinned here. + #[test] + fn a_line_keeps_its_endpoints_and_its_rectangle_spans_them(from in prop::array::uniform2(coord()), dx in 1.0f64..300.0, dy in -300.0f64..300.0, width in 0.5f64..8.0) { + let to = [(from[0] + dx).min(450.0), from[1] + dy]; + let mut doc = blank(1); + add_annotation(&mut doc, &comment(0, Shape::Line { from, to, start: LineEnding::None, end: LineEnding::OpenArrow }, Style { color: [0.0, 0.0, 0.0], opacity: 1.0, width, fill: None }, String::new(), "Ada".into()), &meta("l".into())) + .expect("adds"); + let span = bounds_of(&[from, to]); + for path in [Save::Incremental, Save::FullTable, Save::FullStreams] { + let (file, reopened) = save_and_reopen(&doc, path); + let entries = annot_entries(&reopened, 0); + prop_assert_eq!(entries.len(), 1, "{}: exactly the one comment", tag(path)); + let d = dict_of(&reopened, &entries[0]).expect("one annotation"); + let r = nums(&reopened, &d, b"Rect").expect("/Rect"); + prop_assert!(r[0] <= span[0] && r[1] <= span[1] && r[2] >= span[2] && r[3] >= span[3], "{}: line {:?} to {:?} must lie inside {:?}", tag(path), from, to, r); + let storedline = nums(&reopened, &d, b"L"); + prop_assert_eq!(storedline.as_deref(), Some(&[from[0], from[1], to[0], to[1]][..]), "{}: /L verbatim", tag(path)); + if path != Save::FullStreams { + prop_assert!(bytes::numbers_of(&file, "L").contains(&vec![from[0], from[1], to[0], to[1]]), "{}: /L must be in the file", tag(path)); + } + } + } +} + +/// A comment is addressed as `(page, index)`, and `lib.rs` documents `index` as its position in +/// that page's `/Annots`. Fixed rather than generated, because the interesting part is not the +/// arithmetic but the interaction: a note adds its pop-up to the same array, so an index claimed +/// before a save has to still name the same comment afterwards. +#[test] +fn indices_claimed_before_a_save_still_name_the_same_comment_after_it() { + let mut doc = blank(1); + let first = add_annotation( + &mut doc, + &comment(0, Shape::Rectangle { rect: [10.0, 700.0, 90.0, 730.0] }, Style::default(), "one".into(), "A".into()), + &meta("i1".into()), + ) + .expect("adds"); + let second = add_annotation( + &mut doc, + &comment(0, Shape::Note { at: [10.0, 600.0], icon: NoteIcon::Note }, Style::default(), "two".into(), "A".into()), + &meta("i2".into()), + ) + .expect("adds"); + let third = add_annotation( + &mut doc, + &comment(0, Shape::Rectangle { rect: [10.0, 400.0, 90.0, 430.0] }, Style::default(), "three".into(), "A".into()), + &meta("i3".into()), + ) + .expect("adds"); + assert_eq!((first, second, third), (0, 1, 3), "the pop-up takes index 2"); + + for path in [Save::Incremental, Save::FullTable, Save::FullStreams] { + let (_, reopened) = save_and_reopen(&doc, path); + for (idx, want_id) in [(first, "i1"), (second, "i2"), (third, "i3")] { + let entries = annot_entries(&reopened, 0); + let d = dict_of(&reopened, &entries[idx]).unwrap_or_else(|| panic!("{}: index {idx} exists", tag(path))); + assert_eq!(str_of(&reopened, &d, b"NM").as_deref(), Some(want_id), "{}: index {idx} is still the same comment", tag(path)); + } + } +} diff --git a/crates/annot/tests/round_trip.rs b/crates/annot/tests/round_trip.rs new file mode 100644 index 0000000000..3e60601498 --- /dev/null +++ b/crates/annot/tests/round_trip.rs @@ -0,0 +1,1086 @@ +//! Structural fidelity of annotations across save and reopen (ISO 32000-2 §12.5). +//! +//! `src/tests.rs` checks comments against the document *in memory*: it edits a comment and +//! asserts what the dictionary now holds, with `reopen` used mainly to prove the bytes parse. +//! These tests take the other half — a comment is added, the file is written and re-read from +//! scratch, and what survives is checked entry by entry against values worked out here from the +//! standard rather than read back from the crate that wrote them. +//! +//! Each test replays its assertions over all three writer paths in `support::fixture` +//! (incremental, full save with a cross-reference table, full save into compressed object +//! streams). Object numbers change on the third path, so `/P`, `/Popup`, `/IRT` and `/Dest` +//! targets have to be re-pointed rather than copied — that is where reference-carrying data +//! actually breaks. +//! +//! Scope, deliberately: **structure only**. Nothing here asserts what an appearance stream draws, +//! how wide a stamp label is, or where glyphs land. Appearance generation is being rewritten by +//! several open PRs at once (#2345 stamps, #2137 pop-up windows, #2066 Vietnamese text, #1775 +//! FreeText fonts, #1513 Turkish), and a test that pinned today's drawing would be noise for +//! them. Where stored geometry is defined in terms of an appearance measurement — a line's +//! arrowhead padding, a cloud's bulge, a callout box's re-fit — these tests assert the +//! containment and internal consistency that must hold whatever that measurement is. + +mod support { + pub mod bytes; + pub mod fixture; +} + +use pdfcraft_annot::{ + AnnotError, AttachIcon, LineEnding, Markup, Meta, NewAnnotation, NoteIcon, OverlayFont, OverlayLook, ReviewState, Shape, StampKind, Style, + StyleChange, add_annotation, add_reply, delete_annotation, links, page_refs, props, set_locked, set_review_state, set_style, summaries, +}; +use pdfcraft_cos::{Dict, Document, ObjRef, Object, SaveOptions}; + +use support::bytes; +use support::fixture::{ + ALL_SAVES, FLAG_NO_ROTATE, FLAG_NO_ZOOM, FLAG_PRINT, FLAG_READONLY, Save, annot_entries, blank, blank_with_indirect_annots, dict_of, name_of, + num, nums, page_object_numbers, pdf, save_and_reopen, str_of, +}; + +/// A deterministic `/M` date and `/NM` id, so nothing here depends on the clock. +fn meta(id: &str) -> Meta { + Meta { date: Some("D:20261001120000Z".into()), id: id.into() } +} + +/// A comment with plain styling unless a test asks otherwise. +fn ann(page: usize, shape: Shape, contents: &str) -> NewAnnotation { + NewAnnotation { page, shape, style: Style::default(), contents: contents.into(), author: "Ada".into() } +} + +fn styled(page: usize, shape: Shape, contents: &str, color: [f64; 3], opacity: f64, width: f64, fill: Option<[f64; 3]>) -> NewAnnotation { + NewAnnotation { page, shape, style: Style { color, opacity, width, fill }, contents: contents.into(), author: "Ada".into() } +} + +/// The dictionary of the `k`-th `/Annots` entry of a page. +fn annot_at(doc: &Document, page: usize, k: usize, path: Save) -> Dict { + let entries = annot_entries(doc, page); + let entry = entries.get(k).unwrap_or_else(|| panic!("{path:?}: page {page} has {} /Annots entries, wanted index {k}", entries.len())); + dict_of(doc, entry).unwrap_or_else(|| panic!("{path:?}: /Annots[{k}] is not a dictionary")) +} + +fn ref_at(doc: &Document, page: usize, k: usize) -> ObjRef { + annot_entries(doc, page)[k].as_ref().expect("an indirect /Annots entry") +} + +/// Comment subtypes on a page, in `/Annots` order. +fn kinds(doc: &Document, page: usize) -> Vec { + annot_entries(doc, page).iter().filter_map(|e| dict_of(doc, e)).map(|d| name_of(doc, &d, b"Subtype").unwrap_or_default()).collect() +} + +/// A `/LE`-style array of names, as strings. +fn name_array(doc: &Document, d: &Dict, key: &[u8]) -> Option> { + let a = doc.resolve(d.get(key)?).as_array()?.clone(); + // Every element must be a name; an array like [/OpenArrow 3] is not a valid /LE. + let mut out = Vec::with_capacity(a.len()); + for x in &a { + out.push(String::from_utf8_lossy(x.as_name()?).into_owned()); + } + Some(out) +} + +// ── the sticky note: geometry, text, flags and its pop-up ───────────────────────────────────── + +/// A sticky note carries more distinct data than any other comment: a position, an icon name, the +/// flag combination that keeps the icon unscaled on zoom and rotation, a closed `Open`, opacity, +/// author, text, date, id — plus a separate pop-up annotation that points back at it. +#[test] +fn sticky_note_and_its_popup_survive_every_save_path() { + let mut doc = blank(2); + // §12.5.6.4: a sticky note is a `Text` annotation; the icon's top-left sits at `at`, and + // NOTE_SIZE (20 pt) gives the box, so /Rect is [100 680 120 700]. + let i = add_annotation(&mut doc, &ann(0, Shape::Note { at: [100.0, 700.0], icon: NoteIcon::Key }, "Left margin note"), &meta("note-1")) + .expect("adds"); + assert_eq!(i, 0); + + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + assert_eq!(kinds(&reopened, 0), vec!["Text".to_string(), "Popup".to_string()], "{path:?}"); + let n = annot_at(&reopened, 0, 0, path); + assert_eq!(name_of(&reopened, &n, b"Type").as_deref(), Some("Annot"), "{path:?}"); + assert_eq!(nums(&reopened, &n, b"Rect").as_deref(), Some(&[100.0, 680.0, 120.0, 700.0][..]), "{path:?} /Rect"); + assert_eq!(name_of(&reopened, &n, b"Name").as_deref(), Some("Key"), "{path:?}: the icon (§12.5.6.4 Table 175)"); + assert_eq!(str_of(&reopened, &n, b"Contents").as_deref(), Some("Left margin note"), "{path:?}"); + assert_eq!(str_of(&reopened, &n, b"T").as_deref(), Some("Ada"), "{path:?}"); + assert_eq!(str_of(&reopened, &n, b"NM").as_deref(), Some("note-1"), "{path:?}"); + assert_eq!(str_of(&reopened, &n, b"M").as_deref(), Some("D:20261001120000Z"), "{path:?}"); + assert_eq!(str_of(&reopened, &n, b"Subj").as_deref(), Some("Sticky Note"), "{path:?}"); + // §12.5.3: /CA defaults to 1, so full opacity writes no /CA at all. + assert!(n.get(b"CA").is_none(), "{path:?}: /CA must be absent at full opacity"); + // Notes print, and stay unscaled under zoom and rotation: Print|NoZoom|NoRotate. + assert_eq!(n.int(b"F"), Some(FLAG_PRINT | FLAG_NO_ZOOM | FLAG_NO_ROTATE), "{path:?} /F"); + assert_eq!(n.get(b"Open").map(|o| matches!(o, Object::Bool(false))), Some(true), "{path:?}: /Open false"); + assert_eq!(nums(&reopened, &n, b"C").as_deref(), Some(&[1.0, 0.82, 0.0][..]), "{path:?} /C"); + // /P names the page it belongs to — the same object, after any renumbering. + assert_eq!(n.reference(b"P").map(|r| r.num), Some(page_object_numbers(&reopened)[0]), "{path:?}: /P resolves to page 1"); + + // The pop-up names its parent and the parent names it back. + let pop = annot_at(&reopened, 0, 1, path); + assert_eq!(name_of(&reopened, &pop, b"Subtype").as_deref(), Some("Popup"), "{path:?}"); + assert_eq!(pop.reference(b"Parent"), Some(ref_at(&reopened, 0, 0)), "{path:?}: /Popup and /Parent agree both ways"); + assert_eq!(n.reference(b"Popup"), Some(ref_at(&reopened, 0, 1)), "{path:?}"); + // Acrobat's pop-up is a 200×120 pt window beside the icon, top aligned with it. + assert_eq!(nums(&reopened, &pop, b"Rect").as_deref(), Some(&[130.0, 580.0, 330.0, 700.0][..]), "{path:?}: pop-up /Rect"); + + if !matches!(path, Save::FullStreams) { + // Claims about the file's own bytes (see `support::bytes`), not via our reader. + assert_eq!(bytes::numbers_of(&file, "Rect").first(), Some(&vec![100.0, 680.0, 120.0, 700.0]), "{path:?}"); + assert!(bytes::texts_of(&file, "NM").contains(&"note-1".to_string()), "{path:?}"); + assert!(bytes::texts_of(&file, "Contents").contains(&"Left margin note".to_string()), "{path:?}"); + assert!(bytes::has_name(&file, "Key"), "{path:?}: the icon name is in the file"); + } + } +} + +/// Opacity below 1 must reach the file as `/CA`; an out-of-range value is clamped, and a clamp +/// to 1.0 means the key disappears rather than being written as `1`. +#[test] +fn opacity_is_written_only_when_it_differs_from_one() { + let cases = [(0.65, Some(0.65)), (1.0, None), (1.75, None), (0.0, Some(0.0)), (-0.25, Some(0.0))]; + for (opacity, expected) in cases { + let mut doc = blank(1); + add_annotation( + &mut doc, + &styled(0, Shape::Rectangle { rect: [10.0, 10.0, 60.0, 40.0] }, "x", [0.9, 0.1, 0.1], opacity, 2.0, None), + &meta("o"), + ) + .expect("adds"); + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + let d = annot_at(&reopened, 0, 0, path); + assert_eq!(num(&reopened, &d, b"CA"), expected, "{path:?}: /CA at the given opacity {opacity}"); + assert_eq!(props(&reopened, 0, 0).map(|p| p.opacity), Some(expected.unwrap_or(1.0)), "{path:?}: reported opacity {opacity}"); + if !matches!(path, Save::FullStreams) { + assert_eq!(bytes::scalars_of(&file, "CA").first().copied(), expected, "{path:?}: /CA written at opacity {opacity}"); + } + } + } +} + +// ── text markup: quadrilaterals are the geometry (§12.5.6.10) ───────────────────────────────── + +/// The four markup kinds differ in `/Subtype` alone; each keeps its quadrilateral list and derived +/// rectangle. The two-quad case shows the array is stored whole (16 numbers) rather than +/// truncated to the first quad, and that `/Rect` spans both. +#[test] +fn markup_kinds_keep_quads_and_rectangles() { + let kinds = + [("Highlight", Markup::Highlight), ("Underline", Markup::Underline), ("StrikeOut", Markup::StrikeOut), ("Squiggly", Markup::Squiggly)]; + let q1 = [72.0, 712.0, 200.0, 712.0, 72.0, 700.0, 200.0, 700.0]; + let q2 = [72.0, 692.0, 320.0, 692.0, 72.0, 680.0, 320.0, 680.0]; + let mut doc = blank(1); + for (k, name) in kinds.iter() { + add_annotation(&mut doc, &ann(0, Shape::TextMarkup { kind: *name, quads: vec![q1] }, "word"), &meta(&format!("m-{k}"))).expect("adds"); + } + // A two-quad highlight last, so the multi-array case sits at a known index. + let two = add_annotation(&mut doc, &ann(0, Shape::TextMarkup { kind: Markup::Highlight, quads: vec![q1, q2] }, "two lines"), &meta("m-two")) + .expect("adds"); + assert_eq!(two, kinds.len()); + + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + let mut want = kinds.iter().map(|(label, _)| (*label).to_string()).collect::>(); + want.push("Highlight".into()); // the two-quad comment added last + assert_eq!(kinds_of(&reopened, 0), want, "{path:?}"); + for (n, label) in kinds.iter().map(|(label, _)| *label).enumerate() { + let d = annot_at(&reopened, 0, n, path); + assert_eq!(nums(&reopened, &d, b"QuadPoints").as_deref(), Some(&q1[..]), "{path:?}: /QuadPoints verbatim"); // attribution dropped: nothing here tests any specific reader's ordering + assert_eq!(nums(&reopened, &d, b"Rect").as_deref(), Some(&[72.0, 700.0, 200.0, 712.0][..]), "{path:?}: /Rect bounds the quad"); + assert!(d.get(b"BS").is_none(), "{path:?}: markup writes no border style"); + assert_eq!(str_of(&reopened, &d, b"NM").as_deref(), Some(format!("m-{label}").as_str()), "{path:?}"); + } + let d = annot_at(&reopened, 0, two, path); + assert_eq!( + nums(&reopened, &d, b"QuadPoints").as_deref(), + Some(&[q1.to_vec(), q2.to_vec()].concat()[..]), + "{path:?}: two quads are 16 numbers" + ); + assert_eq!(nums(&reopened, &d, b"Rect").as_deref(), Some(&[72.0, 680.0, 320.0, 712.0][..]), "{path:?}: /Rect spans both quads"); + if !matches!(path, Save::FullStreams) { + let sixteen = [q1.to_vec(), q2.to_vec()].concat(); + assert_eq!(bytes::numbers_of(&file, "QuadPoints").last(), Some(&sixteen), "{path:?}: 16 fixed-decimal numbers in the file"); + } + } +} + +fn kinds_of(doc: &Document, page: usize) -> Vec { + kinds(doc, page) +} + +/// `Summary` reports quadrilaterals as 8-number chunks; the same list must chunk identically +/// after a save, and its rectangle must be the bounds those chunks imply. +#[test] +fn summary_quads_and_rect_agree_after_reopen() { + let q1 = [72.0, 300.0, 160.0, 300.0, 72.0, 286.0, 160.0, 286.0]; + let q2 = [72.0, 280.0, 500.0, 280.0, 72.0, 266.0, 500.0, 266.0]; + let mut doc = blank(1); + add_annotation(&mut doc, &ann(0, Shape::TextMarkup { kind: Markup::Squiggly, quads: vec![q1, q2] }, "s"), &meta("sq")).expect("adds"); + for path in ALL_SAVES { + let (_, reopened) = save_and_reopen(&doc, path); + let sum = summaries(&reopened).into_iter().find(|s| s.subtype == "Squiggly").expect("the squiggly is listed"); + assert_eq!(sum.quads, vec![q1.map(|v| v as f32), q2.map(|v| v as f32)], "{path:?}"); + assert_eq!(sum.rect, [72.0f32, 266.0, 500.0, 300.0], "{path:?}"); + assert_eq!(sum.contents.as_deref(), Some("s"), "{path:?}"); + assert_eq!(sum.author.as_deref(), Some("Ada"), "{path:?}"); + } +} + +// ── shapes, lines and drawings ──────────────────────────────────────────────────────────────── + +/// Squares, ovals and stamps keep an exact `/Rect` (reversed corners normalised as §12.5.4.2 +/// requires), interior colour, border width and stamp identity. +#[test] +fn shapes_keep_rectangles_fills_borders_and_stamp_identity() { + let mut doc = blank(1); + add_annotation( + &mut doc, + &styled(0, Shape::Rectangle { rect: [300.0, 300.0, 200.0, 200.0] }, "box", [0.9, 0.1, 0.1], 1.0, 2.0, Some([0.0, 0.5, 0.0])), + &meta("sq"), + ) + .expect("adds square"); + add_annotation(&mut doc, &styled(0, Shape::Oval { rect: [50.0, 60.0, 90.0, 120.0] }, "oval", [0.0, 0.4, 0.8], 1.0, 3.0, None), &meta("ov")) + .expect("adds oval"); + add_annotation( + &mut doc, + &styled( + 0, + Shape::Stamp { rect: [40.0, 600.0, 180.0, 650.0], stamp: StampKind::Approved, by: Some("Ada".into()) }, + "stamped", + [0.13, 0.55, 0.13], + 1.0, + 2.0, + None, + ), + &meta("st"), + ) + .expect("adds stamp"); + + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + let sq = annot_at(&reopened, 0, 0, path); + assert_eq!(name_of(&reopened, &sq, b"Subtype").as_deref(), Some("Square"), "{path:?}"); + // Corners were given as [300 300 200 200]; a rectangle is stored lower-left then upper-right. + assert_eq!(nums(&reopened, &sq, b"Rect").as_deref(), Some(&[200.0, 200.0, 300.0, 300.0][..]), "{path:?}"); + assert_eq!(nums(&reopened, &sq, b"IC").as_deref(), Some(&[0.0, 0.5, 0.0][..]), "{path:?}: /IC (§12.5.6.8)"); + assert_eq!(nums(&reopened, &sq, b"C").as_deref(), Some(&[0.9, 0.1, 0.1][..]), "{path:?}"); + let p = props(&reopened, 0, 0).expect("properties"); + assert_eq!(p.width, Some(2.0), "{path:?}: /BS /W"); + assert_eq!(p.fill, Some([0.0, 0.5, 0.0]), "{path:?}"); + assert!(p.fillable, "{path:?}: rectangles can be filled"); + + let ov = annot_at(&reopened, 0, 1, path); + assert_eq!(name_of(&reopened, &ov, b"Subtype").as_deref(), Some("Circle"), "{path:?}: an oval is /Circle (§12.5.6.9)"); + assert_eq!(nums(&reopened, &ov, b"Rect").as_deref(), Some(&[50.0, 60.0, 90.0, 120.0][..]), "{path:?}"); + assert!(ov.get(b"IC").is_none(), "{path:?}: no interior colour when unfilled"); + assert_eq!(props(&reopened, 0, 1).and_then(|q| q.width), Some(3.0), "{path:?}"); + + let st = annot_at(&reopened, 0, 2, path); + assert_eq!(name_of(&reopened, &st, b"Subtype").as_deref(), Some("Stamp"), "{path:?}"); + assert_eq!(name_of(&reopened, &st, b"Name").as_deref(), Some("Approved"), "{path:?}: a standard stamp keeps its Table 184 name"); + assert_eq!(nums(&reopened, &st, b"Rect").as_deref(), Some(&[40.0, 600.0, 180.0, 650.0][..]), "{path:?}"); + assert!(st.contains(b"PCStamp"), "{path:?}: PdfCraft's own artwork is marked as such"); + assert_eq!(str_of(&reopened, &st, b"PCByLine").as_deref(), Some("Ada"), "{path:?}"); + if !matches!(path, Save::FullStreams) { + assert_eq!(bytes::numbers_of(&file, "IC").first(), Some(&vec![0.0, 0.5, 0.0]), "{path:?}"); + assert!(bytes::has_name(&file, "Approved"), "{path:?}"); + } + } +} + +/// Lines, connected lines and polygons keep their endpoint arrays (`/L`, `/Vertices`), their +/// ending pair (`/LE`) and a cloud's intent. Their `/Rect` is grown by arrowhead and bulge +/// measurements that live in `appearance`, so this checks containment rather than exact padding. +#[test] +fn lines_and_polygons_keep_endpoints_endings_and_cloud_intent() { + let mut doc = blank(1); + add_annotation( + &mut doc, + &ann(0, Shape::Line { from: [50.0, 50.0], to: [150.0, 100.0], start: LineEnding::None, end: LineEnding::OpenArrow }, "arrow"), + &meta("l1"), + ) + .expect("adds arrow"); + add_annotation( + &mut doc, + &ann( + 0, + Shape::PolyLine { vertices: vec![[10.0, 20.0], [40.0, 60.0], [70.0, 25.0]], start: LineEnding::ClosedArrow, end: LineEnding::Butt }, + "path", + ), + &meta("pl"), + ) + .expect("adds polyline"); + add_annotation( + &mut doc, + &ann(0, Shape::Polygon { vertices: vec![[200.0, 100.0], [260.0, 110.0], [230.0, 160.0]], cloud: true }, "cloud"), + &meta("pg"), + ) + .expect("adds cloud"); + add_annotation( + &mut doc, + &ann(0, Shape::Ink { strokes: vec![vec![[0.0, 0.0], [10.0, 10.0], [20.0, 0.0]], vec![[40.0, 40.0], [50.0, 50.0]]] }, "ink"), + &meta("ink"), + ) + .expect("adds ink"); + + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + + let l = annot_at(&reopened, 0, 0, path); + assert_eq!(name_of(&reopened, &l, b"Subtype").as_deref(), Some("Line"), "{path:?}"); + assert_eq!(nums(&reopened, &l, b"L").as_deref(), Some(&[50.0, 50.0, 150.0, 100.0][..]), "{path:?}: /L (§12.5.6.7)"); + assert_eq!( + name_array(&reopened, &l, b"LE").as_deref(), + Some(&["None".to_string(), "OpenArrow".to_string()][..]), + "{path:?}: /LE (§12.5.6.7 Table 217)" + ); + let r = nums(&reopened, &l, b"Rect").expect("/Rect"); + assert!(r[0] <= 50.0 && r[1] <= 50.0 && r[2] >= 150.0 && r[3] >= 100.0, "{path:?}: /Rect must contain both endpoints, got {r:?}"); + assert_eq!(props(&reopened, 0, 0).and_then(|p| p.endings), Some(vec![LineEnding::None, LineEnding::OpenArrow]), "{path:?}"); + + let pl = annot_at(&reopened, 0, 1, path); + assert_eq!(name_of(&reopened, &pl, b"Subtype").as_deref(), Some("PolyLine"), "{path:?}"); + assert_eq!(nums(&reopened, &pl, b"Vertices").as_deref(), Some(&[10.0, 20.0, 40.0, 60.0, 70.0, 25.0][..]), "{path:?}: /Vertices (§12.5.6.9)"); + assert_eq!(props(&reopened, 0, 1).and_then(|p| p.endings), Some(vec![LineEnding::ClosedArrow, LineEnding::Butt]), "{path:?}"); + + let pg = annot_at(&reopened, 0, 2, path); + assert_eq!(name_of(&reopened, &pg, b"Subtype").as_deref(), Some("Polygon"), "{path:?}"); + assert_eq!(name_of(&reopened, &pg, b"IT").as_deref(), Some("PolygonCloud"), "{path:?}: a cloud is `/IT /PolygonCloud` (§12.5.6.9)"); + let be = pg.get(b"BE").map(|o| reopened.resolve(o)).and_then(|o| o.as_dict().cloned()).expect("/BE"); + assert_eq!(name_of(&reopened, &be, b"S").as_deref(), Some("C"), "{path:?}: cloudy border"); + assert_eq!(be.int(b"I"), Some(1), "{path:?}"); + assert_eq!(nums(&reopened, &pg, b"Vertices").as_deref(), Some(&[200.0, 100.0, 260.0, 110.0, 230.0, 160.0][..]), "{path:?}"); + + let ink = annot_at(&reopened, 0, 3, path); + assert_eq!(name_of(&reopened, &ink, b"Subtype").as_deref(), Some("Ink"), "{path:?}"); + let strokes: Vec> = ink + .get(b"InkList") + .map(|o| reopened.resolve(o)) + .and_then(|o| o.as_array().cloned()) + .expect("/InkList") + .iter() + .map(|s| reopened.resolve(s).as_array().expect("a stroke array").iter().filter_map(|x| x.as_f64()).collect()) + .collect(); + assert_eq!(strokes, vec![vec![0.0, 0.0, 10.0, 10.0, 20.0, 0.0], vec![40.0, 40.0, 50.0, 50.0]], "{path:?}: both strokes, all their points"); + if !matches!(path, Save::FullStreams) { + assert_eq!(bytes::numbers_of(&file, "L").first(), Some(&vec![50.0, 50.0, 150.0, 100.0]), "{path:?}"); + assert_eq!(bytes::numbers_of(&file, "Vertices").first(), Some(&vec![10.0, 20.0, 40.0, 60.0, 70.0, 25.0]), "{path:?}"); + } + } +} + +// ── FreeText: the box, its font size and a callout's leader line ─────────────────────────────── + +/// A text box stores its rectangle, colour and size in `/DA`/`Q`, and typewriter text marks its +/// intent (§12.5.6.6). The stored box is the requested one: re-fitting happens on later edits, +/// not at creation. +#[test] +fn text_boxes_keep_rectangles_font_size_and_intent() { + let mut doc = blank(1); + add_annotation( + &mut doc, + &styled(0, Shape::TextBox { rect: [300.0, 600.0, 500.0, 650.0], font_size: 14.0 }, "Type here", [0.1, 0.2, 0.3], 1.0, 0.0, None), + &meta("tb"), + ) + .expect("adds text box"); + add_annotation( + &mut doc, + &styled(0, Shape::Typewriter { rect: [72.0, 100.0, 300.0, 124.0], font_size: 12.0 }, "Typed words", [0.0, 0.0, 0.0], 1.0, 0.0, None), + &meta("tw"), + ) + .expect("adds typewriter"); + + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + let tb = annot_at(&reopened, 0, 0, path); + assert_eq!(name_of(&reopened, &tb, b"Subtype").as_deref(), Some("FreeText"), "{path:?}"); + assert_eq!(nums(&reopened, &tb, b"Rect").as_deref(), Some(&[300.0, 600.0, 500.0, 650.0][..]), "{path:?}"); + assert_eq!(str_of(&reopened, &tb, b"DA").as_deref(), Some("0.1 0.2 0.3 rg /Helv 14 Tf"), "{path:?}: /DA (§12.5.6.6, §12.7.2.3)"); + assert_eq!(tb.int(b"Q"), Some(0), "{path:?}: left aligned"); + assert!(tb.get(b"IT").is_none(), "{path:?}: a plain text box sets no intent"); + assert_eq!(props(&reopened, 0, 0).and_then(|p| p.font_size), Some(14.0), "{path:?}"); + assert_eq!(props(&reopened, 0, 0).and_then(|p| p.color), Some([0.1, 0.2, 0.3]), "{path:?}: FreeText colour comes from /DA"); + + let tw = annot_at(&reopened, 0, 1, path); + assert_eq!(name_of(&reopened, &tw, b"IT").as_deref(), Some("FreeTextTypeWriter"), "{path:?}"); + assert_eq!(nums(&reopened, &tw, b"Rect").as_deref(), Some(&[72.0, 100.0, 300.0, 124.0][..]), "{path:?}"); + assert_eq!(props(&reopened, 0, 1).and_then(|p| p.font_size), Some(12.0), "{path:?}"); + assert!(tw.contains(b"PCFillSign"), "{path:?}: typewriter text is a Fill & Sign item"); + if !matches!(path, Save::FullStreams) { + assert_eq!(bytes::texts_of(&file, "DA").first().map(String::as_str), Some("0.1 0.2 0.3 rg /Helv 14 Tf"), "{path:?}"); + } + } +} + +/// A callout keeps six numbers in `/CL` (arrow point, knee, box attach) plus the inset `/RD`; +/// together those must rebuild exactly the text box that was asked for. That is a consistency +/// claim, so it does not depend on how wide the arrowhead is drawn. +#[test] +fn callout_keeps_its_leader_line_and_rebuilds_the_same_text_box() { + let mut doc = blank(1); + add_annotation( + &mut doc, + &ann( + 0, + Shape::Callout { + rect: [300.0, 400.0, 420.0, 460.0], + knee: [250.0, 380.0], + point: [200.0, 350.0], + font_size: 16.0, + ending: LineEnding::OpenArrow, + }, + "why", + ), + &meta("co"), + ) + .expect("adds callout"); + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + let d = annot_at(&reopened, 0, 0, path); + assert_eq!(name_of(&reopened, &d, b"IT").as_deref(), Some("FreeTextCallout"), "{path:?}"); + // The knee is left of the box, so the leader attaches at the box's left edge midpoint. + assert_eq!(nums(&reopened, &d, b"CL").as_deref(), Some(&[200.0, 350.0, 250.0, 380.0, 300.0, 430.0][..]), "{path:?}: /CL point→knee→attach"); + assert_eq!(props(&reopened, 0, 0).and_then(|p| p.endings), Some(vec![LineEnding::OpenArrow]), "{path:?}"); + assert_eq!(props(&reopened, 0, 0).and_then(|p| p.font_size), Some(16.0), "{path:?}"); + let rect = nums(&reopened, &d, b"Rect").expect("/Rect"); + let rd = nums(&reopened, &d, b"RD").expect("/RD"); + assert!(rd.iter().all(|v| *v >= 0.0), "{path:?}: /RD insets are non-negative (§12.5.3)"); + assert_eq!( + [rect[0] + rd[0], rect[1] + rd[1], rect[2] - rd[2], rect[3] - rd[3]], + [300.0, 400.0, 420.0, 460.0], + "{path:?}: /Rect inset by /RD is the text box" + ); + if !matches!(path, Save::FullStreams) { + assert_eq!(bytes::numbers_of(&file, "CL").first(), Some(&vec![200.0, 350.0, 250.0, 380.0, 300.0, 430.0]), "{path:?}"); + } + } +} + +// ── redaction and file attachment: payload data, not just dictionary keys ───────────────────── + +/// A redaction stores the area it will cover, the colour it will paint and its overlay text with +/// style. Applying a redaction is other crates' business; here only the data has to survive. +#[test] +fn redaction_keeps_quads_fill_and_overlay_text() { + let quads = vec![[72.0, 712.0, 300.0, 712.0, 72.0, 690.0, 300.0, 690.0], [72.0, 680.0, 240.0, 680.0, 72.0, 660.0, 240.0, 660.0]]; + let mut doc = blank(1); + add_annotation( + &mut doc, + &styled( + 0, + Shape::Redact { + quads: quads.clone(), + overlay: "SECRET".into(), + look: OverlayLook { font: OverlayFont::Courier, size: 0.0, color: [1.0, 0.0, 0.0], align: 2, repeat: true }, + }, + "remove this", + [0.89, 0.13, 0.13], + 1.0, + 1.0, + Some([0.0, 0.0, 0.0]), + ), + &meta("red"), + ) + .expect("adds redaction"); + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + let d = annot_at(&reopened, 0, 0, path); + assert_eq!(name_of(&reopened, &d, b"Subtype").as_deref(), Some("Redact"), "{path:?}"); + assert_eq!(nums(&reopened, &d, b"QuadPoints").as_deref(), Some(&quads.concat()[..]), "{path:?}"); + assert_eq!(nums(&reopened, &d, b"IC").as_deref(), Some(&[0.0, 0.0, 0.0][..]), "{path:?}: /IC is the colour applied (§12.5.6.23)"); + assert_eq!(str_of(&reopened, &d, b"OverlayText").as_deref(), Some("SECRET"), "{path:?}"); + assert_eq!(str_of(&reopened, &d, b"DA").as_deref(), Some("1 0 0 rg /Cour 0 Tf"), "{path:?}: the overlay font resource"); + assert_eq!(d.int(b"Q"), Some(2), "{path:?}: right aligned"); + assert_eq!(d.get(b"Repeat").map(|o| matches!(o, Object::Bool(true))), Some(true), "{path:?}"); + assert_eq!(nums(&reopened, &d, b"Rect").as_deref(), Some(&[72.0, 660.0, 300.0, 712.0][..]), "{path:?}"); + if !matches!(path, Save::FullStreams) { + assert_eq!(bytes::texts_of(&file, "OverlayText").first().map(String::as_str), Some("SECRET"), "{path:?}"); + } + } +} + +/// An attached file is the heaviest annotation there is: a file specification, an embedded file +/// stream with its own parameters, and the bytes inside it. A full rewrite renumbers all three +/// objects and may move them into object streams, so this is the strongest reference test here. +#[test] +fn attached_file_specification_and_bytes_survive_every_save_path() { + let body = b"first line\nsecond line, 27 bytes more\n".to_vec(); + let mut doc = blank(1); + add_annotation( + &mut doc, + &ann(0, Shape::Attachment { at: [300.0, 600.0], icon: AttachIcon::Paperclip, file: "notes.txt".into(), data: body.clone() }, ""), + &meta("att"), + ) + .expect("attaches"); + for path in ALL_SAVES { + let (_, reopened) = save_and_reopen(&doc, path); + let d = annot_at(&reopened, 0, 0, path); + assert_eq!(name_of(&reopened, &d, b"Subtype").as_deref(), Some("FileAttachment"), "{path:?}"); + assert_eq!(name_of(&reopened, &d, b"Name").as_deref(), Some("Paperclip"), "{path:?}"); + // With no comment text the file's name is shown as the contents (§12.5.6.15). + assert_eq!(str_of(&reopened, &d, b"Contents").as_deref(), Some("notes.txt"), "{path:?}"); + assert_eq!(nums(&reopened, &d, b"Rect").as_deref(), Some(&[300.0, 580.0, 320.0, 600.0][..]), "{path:?}"); + + let fs_ref = d.reference(b"FS").expect("/FS must reference a file specification"); + let fs = reopened.get(fs_ref).as_dict().cloned().expect("/FS resolves to a dictionary"); + assert_eq!(name_of(&reopened, &fs, b"Type").as_deref(), Some("Filespec"), "{path:?}"); + assert_eq!(str_of(&reopened, &fs, b"F").as_deref(), Some("notes.txt"), "{path:?}"); + let ef = fs.get(b"EF").map(|o| reopened.resolve(o)).and_then(|o| o.as_dict().cloned()).expect("/EF"); + let file_ref = ef.reference(b"F").expect("/EF /F references the embedded stream"); + let Object::Stream(s) = &*reopened.get(file_ref) else { panic!("the embedded file is a stream") }; + assert_eq!(s.decoded().expect("decodes").as_slice(), &body[..], "{path:?}: the file's bytes survive"); + let params = s.dict.get(b"Params").map(|o| reopened.resolve(o)).and_then(|o| o.as_dict().cloned()).expect("/Params"); + assert_eq!(params.int(b"Size").map(|v| v as usize), Some(body.len()), "{path:?}"); + } +} + +// ── order, indices and page ownership across several comments ───────────────────────────────── + +/// Five comments on two pages keep their per-page order, the `(page, index)` addressing documented +/// at the top of `lib.rs`, and each one's `/P`. `summaries` additionally promises page order then +/// top edge first; both are checked, because `index` refers to `/Annots` position while the list +/// order does not. +/// COVERAGE HONESTY (ten single-site mutations, run independently by two reviewers plus the +/// author; run at base 99941daa, before main split `lib.rs` into modules - the anchors below +/// are the merged layout, re-derived line by line from the split files). FIVE are also killed by pre-existing inline tests in `crates/annot/src/tests.rs`, and +/// they share a family — the clamp is INVERTED, or a key/order changed rather than removed: +/// `create.rs:47` inverted (`ink_strokes_are_smooth_curves_through_their_points`), `create.rs:216` inverted +/// (six inline tests), `modify.rs:547` inverted (`restyle_and_resize_redraw_the_appearance`), +/// `info.rs:151` tie-break swapped (`stamps_draw_their_label_and_by_line`, the same tie-break as +/// here) and `create.rs:450` `/Parent` renamed (`every_tool_creates_a_drawable_comment`). This file shares that +/// credit and claims none of it alone. The other FIVE are killed only by tests added here, and +/// they share a different family — the clamp is REMOVED outright, or introduced where the code +/// does not have one: `create.rs:216` deleted, `create.rs:47` deleted, the opacity clamp at +/// `create.rs:212` removed, the colour clamp in `rgb()` at `create.rs:14` removed (killed only by +/// `malformed::the_same_huge_fill_is_accepted_on_create_and_refused_on_edit`), and a clamp ADDED +/// to the read path at `info.rs:231`. Note that `create.rs:47` appears on both sides, and +/// deliberately so: +/// inverting that clamp trips an inline test as well, while deleting it trips nothing but +/// `a_negative_and_a_zero_border_pad_a_line_identically`. Confusing those two mutations is easy +/// enough to produce a false refutation, so the distinction is recorded here rather than left to +/// whoever re-runs them. +/// Two further notes: the stored `/Annots` order checked below goes through all three save paths, +/// which no inline test does; and `properties.rs::several_rectangles_keep_count_order_and_geometry` +/// constrains stored array order only — it does NOT exercise `summaries()` ordering. +#[test] +fn several_comments_keep_order_indices_and_page_ownership() { + let mut doc = blank(4); + add_annotation(&mut doc, &ann(0, Shape::Rectangle { rect: [10.0, 100.0, 60.0, 140.0] }, "low"), &meta("a")).expect("adds"); + add_annotation(&mut doc, &ann(0, Shape::Note { at: [10.0, 700.0], icon: NoteIcon::Note }, "high note"), &meta("b")).expect("adds"); + add_annotation( + &mut doc, + &ann(0, Shape::TextMarkup { kind: Markup::Highlight, quads: vec![[10.0, 450.0, 90.0, 450.0, 10.0, 436.0, 90.0, 436.0]] }, "mid"), + &meta("c"), + ) + .expect("adds"); + add_annotation(&mut doc, &ann(2, Shape::Oval { rect: [20.0, 30.0, 80.0, 90.0] }, "p3 oval"), &meta("d")).expect("adds"); + add_annotation(&mut doc, &ann(2, Shape::Caret { rect: [300.0, 400.0, 312.0, 424.0] }, "p3 caret"), &meta("e")).expect("adds"); + + for path in ALL_SAVES { + let (_, reopened) = save_and_reopen(&doc, path); + assert_eq!(kinds(&reopened, 0), ["Square", "Text", "Popup", "Highlight"].map(str::to_owned), "{path:?}: page 1 order"); + assert_eq!(kinds(&reopened, 2), ["Circle", "Caret"].map(str::to_owned), "{path:?}: page 3 order"); + assert_eq!(annot_entries(&reopened, 1).len(), 0, "{path:?}: page 2 stays comment-free"); + assert_eq!(annot_entries(&reopened, 3).len(), 0, "{path:?}"); + + // Every comment's /P names its own page object (pop-ups carry no /P). + let pages = page_object_numbers(&reopened); + for (page, want) in [(0usize, pages[0]), (2, pages[2])] { + for e in annot_entries(&reopened, page) { + let d = dict_of(&reopened, &e).expect("a dictionary"); + if name_of(&reopened, &d, b"Subtype").as_deref() == Some("Popup") { + continue; + } + assert_eq!(d.reference(b"P").map(|r| r.num), Some(want), "{path:?}: /P of {:?}", name_of(&reopened, &d, b"Subtype")); + } + } + + let sums = summaries(&reopened); + assert_eq!(sums.len(), 5, "{path:?}: pop-ups are not comments"); + let mut got: Vec<(usize, usize, String)> = sums.iter().map(|s| (s.page, s.index, s.subtype.clone())).collect(); + got.sort(); + assert_eq!( + got, + vec![ + (0, 0, "Square".to_string()), + (0, 1, "Text".to_string()), + (0, 3, "Highlight".to_string()), + (2, 0, "Circle".to_string()), + (2, 1, "Caret".to_string()) + ], + "{path:?}: (page, index in /Annots, subtype)" + ); + for w in sums.windows(2) { + if w[0].page == w[1].page { + assert!(w[0].rect[3] >= w[1].rect[3], "{path:?}: top edge first, got {:?} then {:?}", w[0].rect, w[1].rect); + } else { + assert!(w[0].page < w[1].page, "{path:?}: page by page"); + } + } + } +} + +/// `annot::page_refs` — the crate's own page walk, cycle guard and all — must agree with this +/// file's independent walk over the same reopened bytes. +#[test] +fn page_refs_agrees_with_an_independent_walk() { + let mut doc = blank(3); + add_annotation(&mut doc, &ann(1, Shape::Rectangle { rect: [0.0, 0.0, 20.0, 20.0] }, "x"), &meta("p")).expect("adds"); + for path in ALL_SAVES { + let (_, reopened) = save_and_reopen(&doc, path); + let mine = page_object_numbers(&reopened); + let theirs: Vec = page_refs(&reopened).expect("a page tree").iter().map(|r| r.num).collect(); + assert_eq!(mine, theirs, "{path:?}"); + } +} + +// ── threads: replies and review states keep their edges ──────────────────────────────────────── + +/// A reply is a text annotation whose `/IRT` points at its parent; setting a status adds another +/// one. Deleting a comment takes its pop-up and its replies with it. Every edge there is a +/// reference, so a full rewrite has to re-point them all. +#[test] +fn reply_threads_and_the_delete_cascade_survive_every_save_path() { + let mut doc = blank(1); + add_annotation(&mut doc, &ann(0, Shape::Note { at: [100.0, 700.0], icon: NoteIcon::Comment }, "parent"), &meta("p1")).expect("adds parent"); + add_reply(&mut doc, 0, 0, "child one", "Ben", &meta("r1")).expect("replies"); + let status = set_review_state(&mut doc, 0, 0, ReviewState::Accepted, "Ben", &meta("r2")).expect("sets status"); + assert_eq!(status, 3); + + for path in ALL_SAVES { + let (_, reopened) = save_and_reopen(&doc, path); + assert_eq!(kinds(&reopened, 0), vec!["Text", "Popup", "Text", "Text"], "{path:?}: parent, pop-up, reply, status reply"); + let parent = ref_at(&reopened, 0, 0); + for k in [2usize, 3] { + let d = annot_at(&reopened, 0, k, path); + assert_eq!(d.reference(b"IRT"), Some(parent), "{path:?}: /IRT points at the parent after renumbering"); + assert_eq!(str_of(&reopened, &d, b"T").as_deref(), Some("Ben"), "{path:?}"); + } + let st = annot_at(&reopened, 0, status, path); + assert_eq!(str_of(&reopened, &st, b"State").as_deref(), Some("Accepted"), "{path:?}"); + assert_eq!(str_of(&reopened, &st, b"StateModel").as_deref(), Some("Review"), "{path:?}"); + assert_eq!(str_of(&reopened, &st, b"Subj").as_deref(), Some("Status"), "{path:?}"); + // Replies are printed but keep the icon flags of a comment; no Hidden bit here. + assert_eq!(st.int(b"F"), Some(FLAG_PRINT | FLAG_NO_ZOOM | FLAG_NO_ROTATE), "{path:?}"); + let listed = summaries(&reopened); + assert_eq!(listed.iter().filter(|s| s.in_reply_to.as_deref() == Some("p1")).count(), 2, "{path:?}: both replies name the parent's /NM"); + assert_eq!(listed.iter().filter(|s| s.state.as_deref() == Some("Accepted")).count(), 1, "{path:?}"); + + // Deleting the comment takes its pop-up and both replies with it. + let mut cut = reopened.clone(); + delete_annotation(&mut cut, 0, 0).expect("deletes the thread"); + assert_eq!(annot_entries(&cut, 0).len(), 0, "{path:?}: nothing of the thread is left in memory"); + let (_, cut) = save_and_reopen(&cut, path); + assert_eq!(annot_entries(&cut, 0).len(), 0, "{path:?}: and the file agrees"); + assert!(summaries(&cut).is_empty(), "{path:?}"); + } +} + +/// The Locked flag is not decoration: a comment that reads back locked must refuse the edits the +/// crate says it refuses. Checking after a save means the flag survived on disk, not merely in +/// memory that happened to still hold it. +#[test] +fn locked_flag_survives_and_still_refuses_edits_after_reopen() { + let mut doc = blank(1); + add_annotation(&mut doc, &ann(0, Shape::Rectangle { rect: [10.0, 20.0, 60.0, 50.0] }, "locked box"), &meta("lk")).expect("adds"); + set_locked(&mut doc, 0, 0, true).expect("locks"); + + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + let d = annot_at(&reopened, 0, 0, path); + assert_eq!(d.int(b"F"), Some(FLAG_PRINT | FLAG_READONLY), "{path:?}: Print plus ReadOnly (bit 8)"); + assert_eq!(props(&reopened, 0, 0).map(|p| p.locked), Some(true), "{path:?}"); + let mut try_move = reopened.clone(); + let e = pdfcraft_annot::move_annotation(&mut try_move, 0, 0, 5.0, 5.0, &meta("nope")).err(); + assert_eq!(e, Some(AnnotError::Invalid("the comment is locked".into())), "{path:?}: moving a locked comment refuses"); + let mut try_delete = reopened.clone(); + assert!(delete_annotation(&mut try_delete, 0, 0).is_err(), "{path:?}: deleting a locked comment refuses"); + if !matches!(path, Save::FullStreams) { + assert_eq!(bytes::scalars_of(&file, "F").first(), Some(&132.0), "{path:?}: the flag value is in the file"); + } + } +} + +// ── links (§12.5.6.5) ──────────────────────────────────────────────────────────────────────── + +/// A link's action is a destination array naming a page object, or a URI action. Page targets are +/// the interesting case across a full rewrite: the link must land on the same page after every +/// object number changes. NOTE (naming): this covers link structure — `/A`, `/Dest`, `/URI` and the +/// dash pattern. It deliberately says nothing about appearance streams, which are out of scope here +/// because #2345/#2137/#2066/#1775/#1513 are rewriting appearance generation. +#[test] +fn links_keep_page_targets_uri_and_dash_structure_across_renumbering() { + let mut doc = blank(3); + add_annotation(&mut doc, &ann(0, Shape::Rectangle { rect: [10.0, 700.0, 90.0, 720.0] }, "shape"), &meta("s")).expect("adds a comment too"); + let i = links::add( + &mut doc, + 0, + [120.0, 700.0, 240.0, 720.0], + &links::LinkAction::Page(2), + &links::LinkStyle { visible: true, width: 2.0, dashed: true, ..Default::default() }, + ) + .expect("links to page 3"); + assert_eq!(i, 1); + links::add( + &mut doc, + 1, + [50.0, 600.0, 200.0, 620.0], + &links::LinkAction::Uri("https://example.com/a?b=c&d=1".into()), + &links::LinkStyle::default(), + ) + .expect("links out"); + + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + let pages = page_object_numbers(&reopened); + let got: Vec<(usize, usize, [f64; 4], String, bool)> = links::list(&reopened) + .into_iter() + .map(|l| { + let a = match l.action { + links::LinkAction::Page(p) => format!("page {p}"), + links::LinkAction::Uri(u) => u, + links::LinkAction::Other(o) => format!("other:{o}"), + }; + (l.page, l.index, l.rect, a, l.style.visible) + }) + .collect(); + assert_eq!(got.len(), 2, "{path:?}"); + assert_eq!(got[0], (0, 1, [120.0, 700.0, 240.0, 720.0], "page 2".into(), true), "{path:?}: the target is still page 3"); + assert_eq!(got[1], (1, 0, [50.0, 600.0, 200.0, 620.0], "https://example.com/a?b=c&d=1".into(), false), "{path:?}"); + + let d = annot_at(&reopened, 0, 1, path); + let dest = d.get(b"Dest").map(|o| reopened.resolve(o)).and_then(|o| o.as_array().cloned()).expect("/Dest is an array"); + assert_eq!(dest.first().and_then(|x| x.as_ref()).map(|r| r.num), Some(pages[2]), "{path:?}: /Dest names the page object"); + assert_eq!(name_of(&reopened, &d, b"H").as_deref(), Some("I"), "{path:?}: highlight /H (invert, §12.5.3)"); + let bs = d.get(b"BS").map(|o| reopened.resolve(o)).and_then(|o| o.as_dict().cloned()).expect("/BS"); + assert_eq!(name_of(&reopened, &bs, b"S").as_deref(), Some("D"), "{path:?}: dashed"); + assert_eq!(bs.get(b"W").and_then(|w| w.as_f64()), Some(2.0), "{path:?}"); + assert_eq!(summaries(&reopened).iter().filter(|s| s.page == 0).count(), 1, "{path:?}: only the rectangle is a comment"); + if !matches!(path, Save::FullStreams) { + assert_eq!( + bytes::texts_of(&file, "URI").first().map(String::as_str), + Some("https://example.com/a?b=c&d=1"), + "{path:?}: the URI is in the file" + ); + } + } +} + +/// Removing every link leaves comments alone. Both directions are index arithmetic over one shared +/// array, so a mistake shows up as a lost comment or an orphaned link. +#[test] +fn removing_all_links_keeps_comments() { + let mut doc = blank(2); + add_annotation(&mut doc, &ann(0, Shape::Note { at: [50.0, 700.0], icon: NoteIcon::Help }, "note"), &meta("n")).expect("adds"); + links::add(&mut doc, 0, [200.0, 700.0, 300.0, 715.0], &links::LinkAction::Page(0), &links::LinkStyle::default()).expect("links"); + let removed = links::remove_all(&mut doc, None).expect("removes all links"); + assert_eq!(removed, 1); + + for path in ALL_SAVES { + let (_, reopened) = save_and_reopen(&doc, path); + assert_eq!(kinds(&reopened, 0), vec!["Text", "Popup"], "{path:?}: the note and its pop-up stay"); + assert!(links::list(&reopened).is_empty(), "{path:?}"); + } +} + +// ── data the crate does not understand, and nothing at all ───────────────────────────────────── + +/// A stranger's file can hold inline annotation dictionaries and keys PdfCraft has never heard of. +/// Fidelity says they are preserved rather than dropped (`CLAUDE.md`: preserve unknown data). +#[test] +fn inline_annotations_and_unknown_keys_survive_every_save_path() { + let objs: Vec<&[u8]> = vec![ + b"<< /Type /Catalog /Pages 2 0 R >>", + b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>", + b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Annots [<< /Type /Annot /Subtype /Square /Rect [10 10 50 50] /C [1 0 0] /OddKey (kept) /AnotherLevel << /Deep 42 >> >>] >>", + ]; + let mut doc = Document::open(std::sync::Arc::new(pdf(&objs))).expect("the stranger's file opens"); + add_annotation(&mut doc, &ann(0, Shape::Rectangle { rect: [100.0, 100.0, 150.0, 130.0] }, "ours"), &meta("mine")).expect("adds ours"); + + for path in ALL_SAVES { + let (_, reopened) = save_and_reopen(&doc, path); + assert_eq!(kinds(&reopened, 0), vec!["Square", "Square"], "{path:?}: theirs first, ours second"); + let foreign = annot_at(&reopened, 0, 0, path); + assert_eq!(str_of(&reopened, &foreign, b"OddKey").as_deref(), Some("kept"), "{path:?}: an unknown string key"); + let deep = foreign.get(b"AnotherLevel").map(|o| reopened.resolve(o)).and_then(|o| o.as_dict().cloned()).expect("an unknown dictionary"); + assert_eq!(deep.int(b"Deep"), Some(42), "{path:?}"); + assert_eq!(nums(&reopened, &foreign, b"Rect").as_deref(), Some(&[10.0, 10.0, 50.0, 50.0][..]), "{path:?}"); + assert_eq!(str_of(&reopened, &annot_at(&reopened, 0, 1, path), b"NM").as_deref(), Some("mine"), "{path:?}: our own comment is still there"); + } +} + +/// A document with nothing on it round trips without acquiring stray keys: no `/Annots` at all, +/// and an empty comment list. Cheap to check, and it is the case where a writer bug would add +/// noise that no other assertion in this file would notice. +#[test] +fn an_empty_document_stays_empty() { + let doc = blank(2); + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + let pages = page_object_numbers(&reopened); + assert_eq!(pages.len(), 2, "{path:?}"); + for (page, &number) in pages.iter().enumerate() { + assert!(annot_entries(&reopened, page).is_empty(), "{path:?}: no entries on page {}", page + 1); + let p = reopened.get(ObjRef::new(number, 0)); + assert!(p.as_dict().is_some_and(|d| !d.contains(b"Annots")), "{path:?}: page {} has no /Annots key", page + 1); + } + assert!(summaries(&reopened).is_empty(), "{path:?}"); + assert!(file.starts_with(b"%PDF-"), "{path:?}"); + } +} + +/// An empty `/Annots` array written by someone else and referenced indirectly: adding the first +/// comment must write through that shared object rather than replacing the page's reference with a +/// fresh array, or a viewer holding the old reference would still see no annotations. +#[test] +fn first_comment_into_an_indirect_annotss_array_writes_through_it() { + let mut doc = blank_with_indirect_annots(2, 1); + add_annotation(&mut doc, &ann(1, Shape::Oval { rect: [20.0, 30.0, 60.0, 70.0] }, "o"), &meta("w")).expect("adds"); + let shared = { + let pages = page_object_numbers(&doc); + doc.get(ObjRef::new(pages[1], 0)).as_dict().and_then(|d| d.reference(b"Annots")).expect("the skeleton's shared /Annots object") + }; + for path in ALL_SAVES { + let (_, reopened) = save_and_reopen(&doc, path); + assert_eq!(kinds(&reopened, 1), vec!["Circle"], "{path:?}"); + if path == Save::Incremental { + // The original object is still the page's /Annots on an incremental save. + let pages = page_object_numbers(&reopened); + let now = reopened.get(ObjRef::new(pages[1], 0)).as_dict().and_then(|d| d.reference(b"Annots")); + assert_eq!(now, Some(shared), "{path:?}: the page still points at the same array object"); + assert_eq!(reopened.get(shared).as_array().map(|a| a.len()), Some(1), "{path:?}"); + } + } +} + +/// Text is the payload a comment exists to carry. Acrobat separates lines with CR, PDF strings may +/// hold parentheses and backslashes, and anything outside printable ASCII goes out as UTF-16BE. All +/// of it must come back identical — checked against the file's bytes, not only through our reader. +#[test] +fn awkward_comment_text_survives_to_the_bytes() { + let cases = [ + "plain", + "(parenthesised) \\backslash\\", + "line one\r\nline two", + "Annà", // non-ASCII → UTF-16BE with a BOM + "emoji: \u{1F642}", // a surrogate pair in UTF-16BE + "tabs\tand\nbreaks", + ]; + for text in cases { + let mut doc = blank(1); + add_annotation(&mut doc, &ann(0, Shape::Note { at: [10.0, 700.0], icon: NoteIcon::Note }, text), &meta("t")).expect("adds"); + for path in [Save::Incremental, Save::FullTable] { + let (file, reopened) = save_and_reopen(&doc, path); + let d = annot_at(&reopened, 0, 0, path); + assert_eq!(str_of(&reopened, &d, b"Contents").as_deref(), Some(text), "{path:?}: {text:?} through our reader"); + let found = bytes::texts_of(&file, "Contents"); + assert!(found.contains(&text.to_string()), "{path:?}: {text:?} is in the file as a PDF string, got {found:?}"); + assert_eq!(props(&reopened, 0, 0).map(|p| p.subtype), Some("Text".into()), "{path:?}"); + } + } +} + +/// Enum names reach the file as the strings the standard defines, which is what other programs +/// read. `/H`'s one-letter codes are checked through the reader instead: a bare `/P` in raw bytes +/// is ambiguous with `/Pages`, `/Parent` and every page object's `/P`. +#[test] +fn enum_names_are_written_as_the_standard_name_strings() { + let mut doc = blank(1); + add_annotation(&mut doc, &ann(0, Shape::Note { at: [10.0, 700.0], icon: NoteIcon::NewParagraph }, "n"), &meta("e1")).expect("adds"); + links::add( + &mut doc, + 0, + [200.0, 700.0, 300.0, 715.0], + &links::LinkAction::Uri("https://example.com".into()), + &links::LinkStyle { highlight: links::Highlight::Inset, visible: true, ..Default::default() }, + ) + .expect("links"); + add_annotation( + &mut doc, + &ann(0, Shape::Line { from: [10.0, 200.0], to: [80.0, 240.0], start: LineEnding::RClosedArrow, end: LineEnding::Slash }, "l"), + &meta("e2"), + ) + .expect("adds line"); + + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + // The page holds the note, its pop-up, then the link and the line. + assert_eq!(name_of(&reopened, &annot_at(&reopened, 0, 0, path), b"Name").as_deref(), Some("NewParagraph"), "{path:?}"); + assert_eq!(name_of(&reopened, &annot_at(&reopened, 0, 2, path), b"H").as_deref(), Some("P"), "{path:?}: Inset highlight is /H /P (§12.5.3)"); + assert_eq!( + name_array(&reopened, &annot_at(&reopened, 0, 3, path), b"LE").as_deref(), + Some(&["RClosedArrow".to_string(), "Slash".to_string()][..]), + "{path:?}: both line endings" + ); + assert_eq!(props(&reopened, 0, 3).and_then(|p| p.endings), Some(vec![LineEnding::RClosedArrow, LineEnding::Slash]), "{path:?}"); + if !matches!(path, Save::FullStreams) { + assert!(bytes::has_name(&file, "NewParagraph"), "{path:?}"); + assert!(bytes::has_name(&file, "RClosedArrow") && bytes::has_name(&file, "Slash"), "{path:?}"); + } + } +} + +/// Which subtypes count as a comment is a reading rule, and it must not shift when the file is +/// rewritten: pop-ups and links stay out of `summaries`, everything else stays in. +#[test] +fn comment_and_non_comment_subtypes_stay_separated_after_saving() { + let mut doc = blank(1); + add_annotation( + &mut doc, + &ann(0, Shape::TextMarkup { kind: Markup::StrikeOut, quads: vec![[10.0, 700.0, 90.0, 700.0, 10.0, 686.0, 90.0, 686.0]] }, "strike"), + &meta("c1"), + ) + .expect("adds"); + add_annotation(&mut doc, &ann(0, Shape::Note { at: [10.0, 600.0], icon: NoteIcon::Comment }, "note"), &meta("c2")).expect("adds"); + links::add(&mut doc, 0, [10.0, 500.0, 90.0, 520.0], &links::LinkAction::Uri("https://example.com".into()), &links::LinkStyle::default()) + .expect("adds link"); + for path in ALL_SAVES { + let (_, reopened) = save_and_reopen(&doc, path); + assert_eq!(kinds(&reopened, 0), vec!["StrikeOut", "Text", "Popup", "Link"], "{path:?}"); + let mut listed: Vec = summaries(&reopened).iter().map(|s| s.subtype.clone()).collect(); + listed.sort(); + assert_eq!(listed, vec!["StrikeOut".to_string(), "Text".to_string()], "{path:?}: pop-ups and links are not comments"); + } +} + +/// A full save with object streams and one without must describe the same annotations: same +/// count, same subtypes, same rectangles. That makes the two writer paths interchangeable for +/// annotation data, which is what "the object graph is the model" promises. +#[test] +fn a_full_rewrite_into_object_streams_describes_the_same_comments_as_a_plain_table() { + let mut doc = blank(2); + add_annotation(&mut doc, &ann(0, Shape::Note { at: [10.0, 700.0], icon: NoteIcon::Paragraph }, "both paths"), &meta("cmp1")).expect("adds"); + add_annotation(&mut doc, &ann(0, Shape::Rectangle { rect: [10.0, 20.0, 90.0, 60.0] }, "box"), &meta("cmp2")).expect("adds"); + add_annotation( + &mut doc, + &ann(1, Shape::TextMarkup { kind: Markup::Underline, quads: vec![[50.0, 600.0, 150.0, 600.0, 50.0, 586.0, 150.0, 586.0]] }, "u"), + &meta("cmp3"), + ) + .expect("adds"); + + let (_, plain) = save_and_reopen(&doc, Save::FullTable); + let (_, packed) = save_and_reopen(&doc, Save::FullStreams); + let shape_of = |d: &Document| -> Vec<(usize, Vec, Vec<[f64; 4]>)> { + (0..page_object_numbers(d).len()) + .map(|p| { + let e = annot_entries(d, p); + ( + e.len(), + kinds(d, p), + e.iter() + .filter_map(|x| dict_of(d, x)) + .filter_map(|x| nums(d, &x, b"Rect")) + .filter_map(|v| <[f64; 4]>::try_from(v).ok()) + .collect(), + ) + }) + .filter(|t: &(usize, Vec, Vec<[f64; 4]>)| t.0 > 0) + .collect() + }; + assert_eq!(shape_of(&plain), shape_of(&packed), "the two full-save paths must agree"); + assert_eq!(shape_of(&plain).len(), 2, "and both must find the two pages that have comments"); + assert_eq!(summaries(&plain).len(), summaries(&packed).len()); + + // The plain-table output is bigger here: object streams compress, which is the point of them. + let opts = SaveOptions { mod_date: None, id_seed: 0x5052_494E_5443_5241, object_streams: true, drop_unlinked: false }; + let packed_bytes = pdfcraft_cos::write_full(&doc, &opts).expect("writes"); + assert!( + packed_bytes.len() < pdfcraft_cos::write_full(&doc, &SaveOptions { object_streams: false, ..opts }).expect("writes").len(), + "the packed file should be smaller" + ); +} + +// ── measured clamps, pinned so a change is visible (§12.5.3 border width) ────────────────── + +/// Negative border width — CURRENT behaviour, measured on this branch, not an endorsement. +/// +/// `add_annotation` screens width for NON-FINITENESS only. The guard at +/// `crates/annot/src/create.rs:416` reads +/// `!finite(&style.color) || !style.opacity.is_finite() || !style.width.is_finite()`: the +/// `abs() < 1e7` cap belongs to `finite()` (`create.rs:17-19`) and is applied to `color` alone, so width +/// carries no magnitude limit at all. Measured on this branch: `width = 1e9` and `width = 1e299` +/// are both ACCEPTED and written to `/BS /W` verbatim (a 10-digit number, then a 300-digit one), +/// while `color = [1e9, 0, 0]` is refused with `Invalid("invalid style")`. +/// So `width = -4.0` is ACCEPTED too; the value reaching `/BS /W` comes from `style.width.max(0.0)` +/// (`create.rs:216`) and the `/Rect` growth from `style.width.max(0.0) / 2.0` (`create.rs:47`). The file then holds +/// `0`, and neither document's repair log records it. (`finite()` magnitude-screens `color`; +/// `opacity` and `width` get finiteness checks only, and the interior `fill` is not screened by it.) +/// +/// The edit path behaves identically for width: `set_style` applies the same kind of screen +/// (`modify.rs:513`) and `width = Some(-2.5)` is accepted, storing `0`. There is therefore NO +/// create-vs-edit asymmetry for negative widths — unlike a huge or non-finite fill colour, which +/// creation never screens (`create.rs:416` magnitude-screens `color`, finiteness-checks `opacity` and +/// `width`, and takes no look at `fill`, which is merely clamped component-wise by `rgb()` at +/// `create.rs:13-15`) while the edit path refuses the same +/// value explicitly near `modify.rs:626`. Flagged for maintainers rather than asserted as +/// correct: a refusal, or at minimum a repair-log entry naming the substitution, would be the +/// stricter design. If either clamp changes or goes away, this test fails on purpose so that +/// decision is made in the open. +#[test] +fn negative_border_width_is_accepted_and_stored_as_zero() { + for (label, width) in [("minus-four", -4.0f64), ("minus-half", -0.5)] { + let mut doc = blank(1); + add_annotation(&mut doc, &styled(0, Shape::Oval { rect: [5.0, 5.0, 65.0, 35.0] }, "w", [1.0, 0.0, 0.0], 1.0, width, None), &meta("neg")) + .unwrap_or_else(|e| panic!("{label}: negative width {width} should be accepted today, got {e:?}")); + for path in ALL_SAVES { + let (file, reopened) = save_and_reopen(&doc, path); + let d = annot_at(&reopened, 0, 0, path); + let w_stored = d.get(b"BS").map(|o| reopened.resolve(o)).and_then(|o| o.as_dict().cloned()).and_then(|bs| num(&reopened, &bs, b"W")); + assert_eq!(w_stored, Some(0.0), "{label}: {path:?} stores the clamped zero, not {width}"); + assert_eq!(props(&reopened, 0, 0).and_then(|p| p.width), Some(0.0), "{label}: {path:?} reports the clamped zero"); + assert!(!file.windows(4).any(|x| x == b"-4.0" || x == b"-0.5"), "{label}: {path:?} must not write the negative literal it was given"); + assert!(doc.repair_log().is_empty() && reopened.repair_log().is_empty(), "{label}: {path:?} records nothing about the substitution"); + } + } + + let mut doc = blank(1); + add_annotation(&mut doc, &styled(0, Shape::Oval { rect: [5.0, 5.0, 65.0, 35.0] }, "w", [1.0, 0.0, 0.0], 1.0, 2.0, None), &meta("neg2")) + .expect("adds"); + set_style(&mut doc, 0, 0, StyleChange::new(None, None, Some(-2.5), None), &meta("neg2")) + .expect("the edit path screens non-finite and magnitude, not sign"); + let (file, reopened) = save_and_reopen(&doc, Save::FullTable); + assert_eq!(props(&reopened, 0, 0).and_then(|p| p.width), Some(0.0), "an edited negative width is stored as zero too"); + assert!(!file.windows(4).any(|x| x == b"-2.5"), "the negative literal never reaches the file"); + assert!(doc.repair_log().is_empty() && reopened.repair_log().is_empty(), "silently, with nothing recorded"); +} + +/// The `/Rect` half of the same guard (`create.rs:62-82` and `:47`). Measured on this branch: `Rectangle` and +/// `Oval` store the given `/Rect` verbatim, so they cannot detect this guard at all — a first +/// version of this test compared rectangles and survived the mutation, which is exactly how an +/// empty test looks green. `Shape::Line` IS padded by it (`create.rs:87`, `pad = half + arrow`), so the +/// comparison is made there: with `-9pt` and `0pt` borders a line's `/Rect` must grow identically, +/// because `max(0.0)` collapses both before the padding is applied. +#[test] +fn a_negative_and_a_zero_border_pad_a_line_identically() { + let line = |w: f64| { + let mut doc = blank(1); + add_annotation( + &mut doc, + &styled( + 0, + Shape::Line { from: [20.0, 700.0], to: [120.0, 740.0], start: LineEnding::None, end: LineEnding::None }, + "l", + [0.0, 0.0, 0.0], + 1.0, + w, + None, + ), + &meta("ln"), + ) + .expect("adds a line"); + save_and_reopen(&doc, Save::FullTable).0 + }; + let minus = line(-9.0); + let zero = line(0.0); + let rect_minus = bytes::numbers_of(&minus, "Rect"); + let rect_zero = bytes::numbers_of(&zero, "Rect"); + assert!(!rect_minus.is_empty(), "the -9pt file must contain a /Rect array of numbers"); + assert!(!rect_zero.is_empty(), "the 0pt file must contain a /Rect array of numbers"); + assert_eq!(rect_minus, rect_zero, "-9pt and 0pt borders must pad a line's /Rect identically — max(0.0) at create.rs:47 is what guarantees it"); + // `/BS /W` is a SCALAR real, never an array, so `numbers_of` (which only accepts `[...]`) + // compared two empty lists here and passed whatever the file contained. `scalars_of` is the + // right helper, and both sides are guarded non-empty so this can never go green on missing data. + let w_minus = bytes::scalars_of(&minus, "W"); + let w_zero = bytes::scalars_of(&zero, "W"); + assert!(!w_minus.is_empty() && !w_zero.is_empty(), "both files must actually write a /BS /W, got {w_minus:?} vs {w_zero:?}"); + assert_eq!(w_minus, w_zero, "and both store the same /BS /W"); + assert_eq!(w_minus.as_slice(), &[0.0], "the clamp at create.rs:47 stores a negative border width as 0"); +} diff --git a/crates/annot/tests/support/bytes.rs b/crates/annot/tests/support/bytes.rs new file mode 100644 index 0000000000..b06f92f6da --- /dev/null +++ b/crates/annot/tests/support/bytes.rs @@ -0,0 +1,336 @@ +//! Shared helpers compile into every integration-test binary of this crate, and not every +//! binary uses every one of them; `dead_code` would then fail `clippy -D warnings` for reasons +//! that have nothing to do with the test being written. +#![allow(dead_code)] + +//! A deliberately strict reader over the *bytes* a save produced, independent of `pdfcraft-cos`. +//! +//! Reopening saved bytes with `Document::open` and comparing dictionaries proves that our writer +//! and our reader agree. It does not prove what is actually *in the file*: a lenient parser can +//! forgive output that another implementation refuses (an exponent in what should be a fixed +//! decimal number, an unterminated string, a key written twice). These helpers look at the bytes +//! themselves and reject anything outside the narrow grammar ISO 32000-2 §7.3 allows for the +//! object types annotations use, so an assertion here is a claim about the file rather than about +//! a round trip through our own pair of implementations. +//! +//! Scope: dictionary keys whose values are number arrays (`/Rect`, `/QuadPoints`, `/L`, +//! `/Vertices`, `/CL`, `/RD`), number arrays of arrays (`/InkList`), text strings (`/Contents`, +//! `/T`, `/NM`, `/M`) and names (`/Subtype`). That covers the entries these tests care about; it +//! is not a general PDF parser and does not try to be. + +/// Every value token written for `/key` in the raw bytes, in file order. +/// +/// A name-keyed dictionary entry is `/key` preceded and followed by delimiters, so searching for +/// `Rect` does not match inside `/MyRectangle`. The returned spans include the enclosing brackets +/// or string delimiters, which the decoders below strip. +pub fn value_tokens(bytes: &[u8], key: &[u8]) -> Vec> { + let mut out = Vec::new(); + let mut i = 0; + while i + key.len() + 1 < bytes.len() { + if bytes[i] != b'/' || &bytes[i + 1..i + 1 + key.len()] != key { + i += 1; + continue; + } + let after = i + 1 + key.len(); + // The key must end here: a longer name is a different key. + if after < bytes.len() && is_name_byte(bytes[after]) { + i += 1; + continue; + } + let Some((end, token)) = capture(bytes, after) else { + i += 1; + continue; + }; + // A `/Key /Other` hit is ambiguous: it may be a key whose value is a name, or the *name* + // that is some earlier key's value (`/S /URI`). Re-scan from the next byte so a later real + // occurrence of `/Key` is still found; an array, string or number value is unambiguous. + let name_valued = token.starts_with(b"/"); + out.push(token); + i = if name_valued { i + 1 } else { end }; + } + out +} + +fn is_name_byte(b: u8) -> bool { + b.is_ascii_alphanumeric() || matches!(b, b'.' | b'-' | b'_' | b'#' | b'%') +} + +/// Capture the object that starts at `at`, with bracket/paren balance respected. A literal +/// string's brackets do not count; an array containing a string does nest. +fn capture(bytes: &[u8], mut at: usize) -> Option<(usize, Vec)> { + while bytes.get(at).is_some_and(|b| b.is_ascii_whitespace()) { + at += 1; + } + let first = *bytes.get(at)?; + match first { + b'[' => balanced(bytes, at, b'[', b']'), + b'(' => literal_string(bytes, at), + b'<' if bytes.get(at + 1) == Some(&b'<') => balanced(bytes, at, b'<', b'>'), + // A hex string: `<...>`, closed by the first `>` that is not part of a `>>`. + b'<' => { + let close = bytes.get(at + 1..)?.iter().position(|&b| b == b'>')?; + Some((at + close + 2, bytes[at..at + close + 2].to_vec())) + } + b'/' => { + let mut j = at + 1; + while bytes.get(j).is_some_and(|b| !is_delimiter(*b)) { + j += 1; + } + Some((j, bytes[at..j].to_vec())) + } + _ => { + let mut j = at; + while bytes.get(j).is_some_and(|b| !is_delimiter(*b)) { + j += 1; + } + Some((j, bytes[at..j].to_vec())) + } + } +} + +fn is_delimiter(b: u8) -> bool { + b.is_ascii_whitespace() || matches!(b, b'(' | b')' | b'<' | b'>' | b'[' | b']' | b'{' | b'}' | b'/' | b'%') +} + +/// `open` at `at`, closed by the matching `close`, skipping over literal strings so that a +/// delimiter inside `(…)` does not end the span. +fn balanced(bytes: &[u8], at: usize, open: u8, close: u8) -> Option<(usize, Vec)> { + let mut depth = 0usize; + let mut i = at; + while i < bytes.len() { + match bytes[i] { + b'(' => { + let (end, _) = literal_string(bytes, i)?; + i = end; + continue; + } + b if b == open => depth += 1, + b if b == close => { + depth -= 1; + if depth == 0 { + return Some((i + 1, bytes[at..=i].to_vec())); + } + } + _ => {} + } + i += 1; + } + None +} + +fn literal_string(bytes: &[u8], at: usize) -> Option<(usize, Vec)> { + let mut i = at + 1; + while i < bytes.len() { + match bytes[i] { + b'\\' => i += 2, + b')' => return Some((i + 1, bytes[at..=i].to_vec())), + _ => i += 1, + } + } + None +} + +/// The numbers of an array token, written in fixed decimal notation (§7.3.3: no exponent form). +/// `None` when the token is not an array, holds a non-number, or uses `e`. +pub fn numbers(token: &[u8]) -> Option> { + let inner = token.strip_prefix(b"[")?.strip_suffix(b"]")?.to_vec(); + let mut out = Vec::new(); + for word in split_words(&inner) { + if word.first() == Some(&b'[') { + // A nested array (`/InkList`): its numbers count as this one's, flattened. + out.extend(numbers(&word)?); + } else { + out.push(fixed_decimal(&word)?); + } + } + Some(out) +} + +/// A single number written for `/key` (`/CA`, `/F`, a stream's `/Length`), strictly decimal. +pub fn scalars_of(bytes: &[u8], key: &str) -> Vec { + value_tokens(bytes, key.as_bytes()).iter().filter_map(|t| fixed_decimal(t)).collect() +} + +/// All numbers of an ARRAY token written for `/key`, with the strict fixed-decimal rule. +/// +/// ONLY valid for keys whose value is an array (`/Rect`, `/QuadPoints`, `/L`, `/IC`, +/// `/PCPictureSize`). For a SCALAR key (`/W`, `/CA`, `/F`) every token fails `numbers` and the +/// result is an empty vector — so comparing two such calls against each other is vacuous: it +/// passes whether or not the file holds anything. Use [`scalars_of`] for scalars, and always +/// assert non-emptiness when a value is expected. A scalar misuse was found and fixed in +/// `round_trip.rs` (a `/BS /W` comparison that silently compared `[] == []`). +pub fn numbers_of(bytes: &[u8], key: &str) -> Vec> { + value_tokens(bytes, key.as_bytes()).iter().filter_map(|t| numbers(t)).collect() +} + +/// A number written as `[+-]?digits[.]?` or `[+-]?digits[.]digits`, with no exponent and no +/// stray characters. `str::parse::` alone would accept `1e7`, which PDF does not use. +fn fixed_decimal(word: &[u8]) -> Option { + if word.is_empty() || word.iter().any(|b| *b == b'e' || *b == b'E') { + return None; + } + let body = match word[0] { + b'+' | b'-' => &word[1..], + _ => word, + }; + if body.is_empty() { + return None; + } + let mut digits = 0; + let mut dots = 0; + for &b in body { + match b { + b'0'..=b'9' => digits += 1, + b'.' => dots += 1, + _ => return None, + } + } + if digits == 0 || dots > 1 { + return None; + } + std::str::from_utf8(word).ok()?.parse::().ok() +} + +/// The decoded bytes of a string token (literal with escapes, or hex), `None` if malformed. +pub fn raw_string(token: &[u8]) -> Option> { + match (token.first(), token.last()) { + (Some(b'('), Some(b')')) => { + let mut out = Vec::new(); + let body = &token[1..token.len() - 1]; + let mut i = 0; + while i < body.len() { + if body[i] != b'\\' { + out.push(body[i]); + i += 1; + continue; + } + let e = *body.get(i + 1)?; + match e { + b'n' => out.push(b'\n'), + b'r' => out.push(b'\r'), + b't' => out.push(b'\t'), + b'b' => out.push(0x08), + b'f' => out.push(0x0C), + b'(' | b')' | b'\\' => out.push(e), + b'0'..=b'7' => { + let mut v = 0u32; + let mut j = i + 1; + let mut n = 0; + while j < body.len() && n < 3 && (b'0'..=b'7').contains(&body[j]) { + v = v * 8 + u32::from(body[j] - b'0'); + j += 1; + n += 1; + } + out.push(u8::try_from(v).ok()?); + i = j; + continue; + } + b'\n' => {} + _ => return None, + } + i += 2; + } + Some(out) + } + (Some(b'<'), Some(b'>')) => { + let hex: Vec = token[1..token.len() - 1].iter().copied().filter(|b| !b.is_ascii_whitespace()).collect(); + if !hex.len().is_multiple_of(2) { + return None; + } + let mut out = Vec::with_capacity(hex.len() / 2); + for pair in hex.as_chunks::<2>().0 { + let s = std::str::from_utf8(pair).ok()?; + out.push(u8::from_str_radix(s, 16).ok()?); + } + Some(out) + } + _ => None, + } +} + +/// Text as the file holds it: UTF-16BE behind a BOM, PDF 2.0's UTF-8 BOM, or PDFDocEncoding — +/// approximated by Latin-1 above 0x7F. The two differ only at a handful of bytes between 0x18 +/// and 0x9F, none of which these tests assert on; ASCII and the UTF-16 cases are exact. +pub fn text_of_raw(bytes: &[u8]) -> String { + match bytes { + [0xFE, 0xFF, rest @ ..] => String::from_utf16_lossy(&rest.as_chunks::<2>().0.iter().map(|p| u16::from_be_bytes(*p)).collect::>()), + [0xEF, 0xBB, 0xBF, rest @ ..] => String::from_utf8_lossy(rest).into_owned(), + b => b.iter().map(|&c| char::from(c)).collect(), + } +} + +/// Every text value written for `/key`, decoded from the bytes. +pub fn texts_of(bytes: &[u8], key: &str) -> Vec { + value_tokens(bytes, key.as_bytes()).iter().filter_map(|t| raw_string(t)).map(|b| text_of_raw(&b)).collect() +} + +/// A name token's bytes (`/Foo` with `#hh` escapes decoded), or the bare name of a token. +pub fn name_of_token(token: &[u8]) -> Option> { + if *token.first()? != b'/' { + return None; + } + let body = &token[1..]; + let mut out = Vec::new(); + let mut i = 0; + while i < body.len() { + if body[i] == b'#' { + let s = std::str::from_utf8(body.get(i + 1..i + 3)?).ok()?; + out.push(u8::from_str_radix(s, 16).ok()?); + i += 3; + } else { + out.push(body[i]); + i += 1; + } + } + Some(out) +} + +/// Every name written for `/key`. +pub fn names_of(bytes: &[u8], key: &str) -> Vec { + value_tokens(bytes, key.as_bytes()).iter().filter_map(|t| name_of_token(t)).map(|n| String::from_utf8_lossy(&n).into_owned()).collect() +} + +/// Whether the file holds the name `/name` as its own token, so searching `Rect` cannot match +/// inside `/Rectangle`. It does not know about string objects, so a name-looking sequence inside +/// literal text would also match: use it only for names distinctive enough to be unambiguous. +pub fn has_name(bytes: &[u8], name: &str) -> bool { + let n = name.as_bytes(); + if n.is_empty() { + return false; + } + let mut i = 0; + while i + n.len() < bytes.len() { + if bytes[i] == b'/' && &bytes[i + 1..i + 1 + n.len()] == n { + let after = i + 1 + n.len(); + if after >= bytes.len() || !is_name_byte(bytes[after]) { + return true; + } + } + i += 1; + } + false +} + +/// Tokens split on whitespace, with `[` … `]` groups kept whole. +fn split_words(bytes: &[u8]) -> Vec> { + let mut out = Vec::new(); + let mut i = 0; + while i < bytes.len() { + if bytes[i].is_ascii_whitespace() { + i += 1; + continue; + } + if bytes[i] == b'[' { + let (end, tok) = balanced(bytes, i, b'[', b']').expect("an opened array closes in a token we captured"); + out.push(tok); + i = end; + continue; + } + let start = i; + while bytes.get(i).is_some_and(|b| !b.is_ascii_whitespace() && *b != b'[') { + i += 1; + } + out.push(bytes[start..i].to_vec()); + } + out +} diff --git a/crates/annot/tests/support/fixture.rs b/crates/annot/tests/support/fixture.rs new file mode 100644 index 0000000000..69567b34e9 --- /dev/null +++ b/crates/annot/tests/support/fixture.rs @@ -0,0 +1,207 @@ +//! Shared helpers compile into every integration-test binary of this crate, and not every +//! binary uses every one of them; `dead_code` would then fail `clippy -D warnings` for reasons +//! that have nothing to do with the test being written. +#![allow(dead_code)] + +//! Hand-written PDF skeletons and the save/reopen helpers these tests share. +//! +//! The shape follows `crates/annot/src/tests.rs::fixture`: build the bytes of a small +//! cross-referenced PDF by hand, open it with `pdfcraft_cos::Document::open`, and let +//! `pdfcraft-annot` add comments through its public API. Doing it this way (rather than +//! constructing a `Document` in memory) matters for these tests: the file has a real +//! cross-reference chain, so `write_incremental` takes its genuine incremental path instead of +//! silently falling back to a full rewrite. +//! +//! Every save here goes through one of three writer paths, and the tests replay their assertions +//! over all three: +//! +//! * `Save::Incremental` — the original bytes plus an appended revision and `/Prev`; +//! * `Save::FullTable` — a full rewrite with a classic cross-reference table; +//! * `Save::FullStreams` — a full rewrite that packs objects into compressed object streams and +//! renumbers everything from 1. +//! +//! The third path is the interesting one for annotation *identity*: object numbers change, so a +//! `/P`, `/Popup` or `/IRT` that survives it has really been re-pointed, not copied. + +use std::sync::Arc; + +use pdfcraft_cos::{Dict, Document, Object, SaveOptions, write_full, write_incremental}; + +/// Which writer path a round trip should take. +#[derive(Copy, Clone, Debug, PartialEq, Eq)] +pub enum Save { + Incremental, + FullTable, + FullStreams, +} + +/// Every path, in the order tests report them. +pub const ALL_SAVES: [Save; 3] = [Save::Incremental, Save::FullTable, Save::FullStreams]; + +/// The paths whose output holds plain (uncompressed) objects, so raw-byte assertions can look at +/// them. Object streams are Flate-compressed by `write_full`, so their bytes need decoding +/// first; those cases are checked through the reopened document instead. +pub const UNCOMPRESSED_SAVES: [Save; 2] = [Save::Incremental, Save::FullTable]; + +/// Objects written as indirect objects plus a classic cross-reference table and trailer. The +/// catalog is object 1, so `objs` starts with it. +pub fn pdf(objs: &[&[u8]]) -> Vec { + let mut out = b"%PDF-1.7\n".to_vec(); + let mut offsets = Vec::with_capacity(objs.len()); + for (i, o) in objs.iter().enumerate() { + offsets.push(out.len()); + out.extend_from_slice(format!("{} 0 obj\n", i + 1).as_bytes()); + out.extend_from_slice(o); + out.extend_from_slice(b"\nendobj\n"); + } + let xref = out.len(); + out.extend_from_slice(format!("xref\n0 {}\n0000000000 65535 f \n", objs.len() + 1).as_bytes()); + for o in offsets { + out.extend_from_slice(format!("{o:010} 00000 n \n").as_bytes()); + } + out.extend_from_slice(format!("trailer\n<< /Size {} /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n", objs.len() + 1).as_bytes()); + out +} + +/// A document of `pages` blank pages (612×792, no `/Annots` anywhere). +pub fn blank(pages: usize) -> Document { + let mut kids = String::new(); + for i in 0..pages { + kids.push_str(&format!("{} 0 R ", 3 + i)); + } + let mut objs: Vec> = + vec![b"<< /Type /Catalog /Pages 2 0 R >>".to_vec(), format!("<>").into_bytes()]; + for _ in 0..pages { + objs.push(b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] >>".to_vec()); + } + open(&pdf_refs(&objs)) +} + +/// Like [`blank`], but page `page` starts with an indirect (and initially empty) `/Annots` +/// array, so writes to it go through `set_annots`' shared-array branch. +pub fn blank_with_indirect_annots(pages: usize, page: usize) -> Document { + let mut objs: Vec> = vec![ + b"<< /Type /Catalog /Pages 2 0 R >>".to_vec(), + format!("<< /Type /Pages /Kids [{}] /Count {pages} >>", (0..pages).map(|i| format!("{} 0 R", 3 + i)).collect::>().join(" ")) + .into_bytes(), + ]; + for i in 0..pages { + objs.push(if i == page { + format!("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Annots {} 0 R >>", 3 + pages).into_bytes() + } else { + b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] >>".to_vec() + }); + } + objs.push(b"[]".to_vec()); + open(&pdf_refs(&objs)) +} + +/// [`pdf`] over already-owned object bodies. +fn pdf_refs(objs: &[Vec]) -> Vec { + let borrowed: Vec<&[u8]> = objs.iter().map(Vec::as_slice).collect(); + pdf(&borrowed) +} + +fn open(bytes: &[u8]) -> Document { + Document::open(Arc::new(bytes.to_vec())).expect("the skeleton parses") +} + +/// Save one document, then reopen the bytes with our reader. A second, independent parser must +/// accept the same bytes first — that is what makes "it reloads" mean more than "our own writer +/// and reader agree with each other". +pub fn save_and_reopen(doc: &Document, path: Save) -> (Vec, Document) { + let bytes = save(doc, path); + hayro_syntax::Pdf::new(bytes.clone()).unwrap_or_else(|e| panic!("{path:?} output rejected by hayro-syntax: {e:?}")); + (bytes.clone(), Document::open(Arc::new(bytes)).unwrap_or_else(|e| panic!("{path:?} output rejected by our reader: {e:?}"))) +} + +/// Save with the path's options. `/Info /ModDate` is left unset so a full save adds nothing that +/// would make byte comparisons depend on the clock. +pub fn save(doc: &Document, path: Save) -> Vec { + let opts = SaveOptions { mod_date: None, id_seed: 0x5052_494E_5443_5241, object_streams: path == Save::FullStreams, drop_unlinked: false }; + match path { + Save::Incremental => write_incremental(doc, &opts), + Save::FullTable | Save::FullStreams => write_full(doc, &opts), + } + .expect("saves") +} + +/// The leaf pages, in `/Kids` order. Local so these tests do not depend on `annot::page_refs` +/// about a page tree they are only incidentally exercising. +pub fn page_object_numbers(doc: &Document) -> Vec { + let root = doc.root().expect("a catalog"); + let pages = doc.get(root).as_dict().and_then(|d| d.reference(b"Pages")).expect("/Pages"); + let mut out = Vec::new(); + let mut seen = std::collections::HashSet::new(); + collect_pages(doc, pages, &mut seen, &mut out); + out +} + +fn collect_pages(doc: &Document, node: pdfcraft_cos::ObjRef, seen: &mut std::collections::HashSet, out: &mut Vec) { + // `seen` bounds the walk, so a cyclic page tree visits each node once and cannot recurse forever. + if !seen.insert(node) || seen.len() > 10_000 { + return; + } + let obj = doc.get(node); + let Some(d) = obj.as_dict() else { return }; + if d.name(b"Type") == Some(b"Page") { + out.push(node.num); + return; + } + let Some(kids) = d.get(b"Kids").map(|k| doc.resolve(k)).and_then(|k| k.as_array().cloned()) else { return }; + for k in kids { + // The array element itself is the reference; resolving it would give the page dictionary. + if let Object::Ref(r) = k { + collect_pages(doc, r, seen, out); + } + } +} + +/// The raw entries of page `page`'s `/Annots`, in array order (references or inline dictionaries). +pub fn annot_entries(doc: &Document, page: usize) -> Vec { + let num = *page_object_numbers(doc).get(page).expect("the page exists"); + let d = doc.get(pdfcraft_cos::ObjRef::new(num, 0)); + let Some(a) = d.as_dict().and_then(|d| d.get(b"Annots").map(|a| doc.resolve(a))) else { return Vec::new() }; + a.as_array().cloned().unwrap_or_default() +} + +/// The dictionary an `/Annots` entry names (a stream's dictionary counts as one). +pub fn dict_of(doc: &Document, entry: &Object) -> Option { + doc.resolve(entry).as_dict().cloned() +} + +/// A dictionary's number array with every element resolved, as PDF numbers. An entry that is not +/// a number (a name, a string, a dictionary) yields `None` here rather than 0.0, so tests can +/// tell "absent or wrong type" apart from "present and zero". +pub fn nums(doc: &Document, d: &Dict, key: &[u8]) -> Option> { + let a = doc.resolve(d.get(key)?).as_array()?.clone(); + a.iter().map(|x| doc.resolve(x).as_f64()).collect() +} + +/// A single number entry (`/CA`, `/BS /W`), resolving an indirect value. +pub fn num(doc: &Document, d: &Dict, key: &[u8]) -> Option { + doc.resolve(d.get(key)?).as_f64() +} + +/// A dictionary's text entry, decoded with our reader (`None` when absent or not a string). +pub fn str_of(doc: &Document, d: &Dict, key: &[u8]) -> Option { + doc.resolve(d.get(key)?).as_string().map(|s| s.to_text()) +} + +/// A dictionary's name entry as a `&str` where it is ASCII, for readable assertion messages. +pub fn name_of(doc: &Document, d: &Dict, key: &[u8]) -> Option { + let o = doc.resolve(d.get(key)?); + Some(String::from_utf8_lossy(o.as_name()?).into_owned()) +} + +/// Annotation flag bit masks, ISO 32000-2 §12.5.3 Table 165 (the spec numbers bits from 1). +/// `pdfcraft-annot` keeps these private, so they are restated here from the standard: this is +/// deliberately *not* read back from the crate, otherwise a wrong bit would be tested against +/// itself. +pub const FLAG_INVALID: i64 = 1 << 0; // bit 1 +pub const FLAG_HIDDEN: i64 = 1 << 1; // bit 2 +pub const FLAG_PRINT: i64 = 1 << 2; // bit 3 +pub const FLAG_NO_ZOOM: i64 = 1 << 3; // bit 4 +pub const FLAG_NO_ROTATE: i64 = 1 << 4; // bit 5 +pub const FLAG_NO_VIEW: i64 = 1 << 5; // bit 6 +pub const FLAG_READONLY: i64 = 1 << 7; // bit 8 (`/ReadOnly`, PdfCraft's Locked)