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)