flpdf 0.1.9

A pure-Rust PDF toolkit modeled on qpdf — read, rewrite, linearize, and inspect PDFs.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
//! Typed accessor helpers for annotation and form-field objects, mirroring
//! `QPDFAnnotationObjectHelper` and `QPDFFormFieldObjectHelper`.
//!
//! [`AnnotationObjectHelper`] wraps an annotation [`ObjectRef`] together with
//! a `&mut Pdf<R>` and exposes typed, panic-free read-only accessors for the
//! common annotation attributes.
//!
//! [`FormFieldObjectHelper`] wraps a form-field (or widget-annotation) dictionary
//! and provides typed accessors for the four inheritable form-field attributes
//! (`/FT`, `/V`, `/DV`, `/Ff`), resolving them through the field tree's
//! `/Parent` chain when absent on the widget itself.
//!
//! Both helpers are intentionally **read-only** and **thin** — they hold no
//! copied state and re-read the live document on every call.
//!
//! # Design
//!
//! - Annotation attributes (`/Subtype`, `/Rect`, `/AP`, `/A`) are **leaf-only**
//!   — they are read directly from the annotation dictionary without walking any
//!   `/Parent` chain (per ISO 32000-1 §12.5, these keys are not inheritable).
//! - Form-field attributes (`/FT`, `/V`, `/DV`, `/Ff`) are **inheritable** in
//!   the field tree (ISO 32000-1 §12.7.3.1): the helper first checks the field
//!   object itself, then walks `/Parent` references until it finds a value or
//!   exhausts the chain. A depth limit and cycle guard prevent runaway iteration
//!   on malformed documents.
//! - String and name values are returned as raw bytes (`Vec<u8>`) without any
//!   text-string decoding.
//! - `/Rect` reuses [`PageBox`] from [`crate::page_object_helper`].
//!
//! # Examples
//!
//! ## Inspect a highlight annotation
//!
//! ```no_run
//! use std::fs::File;
//! use std::io::BufReader;
//! use flpdf::{pages, Pdf, PageObjectHelper, AnnotationObjectHelper};
//!
//! let mut pdf = Pdf::open(BufReader::new(File::open("annotated.pdf")?))?;
//! let page_refs = pages::page_refs(&mut pdf)?;
//! if let Some(&page_ref) = page_refs.first() {
//!     let mut page_helper = PageObjectHelper::new(page_ref, &mut pdf);
//!     let annot_refs = page_helper.get_annotations()?;
//!     drop(page_helper);
//!     for annot_ref in annot_refs {
//!         let mut annot = AnnotationObjectHelper::new(annot_ref, &mut pdf);
//!         if let Some(subtype) = annot.subtype()? {
//!             println!("annotation subtype: {}", String::from_utf8_lossy(&subtype));
//!         }
//!         if let Some(rect) = annot.rect()? {
//!             println!("rect: [{} {} {} {}]", rect.llx, rect.lly, rect.urx, rect.ury);
//!         }
//!     }
//! }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! ## Read an inherited field type from a widget
//!
//! ```no_run
//! use std::fs::File;
//! use std::io::BufReader;
//! use flpdf::{ObjectRef, Pdf, FormFieldObjectHelper};
//!
//! let mut pdf = Pdf::open(BufReader::new(File::open("form.pdf")?))?;
//! // Assume widget_ref is a widget annotation whose /FT lives on a parent field.
//! let widget_ref = ObjectRef::new(10, 0);
//! let mut field = FormFieldObjectHelper::new(widget_ref, &mut pdf);
//! if let Some(ft) = field.field_type()? {
//!     println!("field type: {}", String::from_utf8_lossy(&ft));
//! }
//! if let Some(flags) = field.field_flags()? {
//!     println!("Ff = 0x{:08X}", flags as u32);
//! }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```

use crate::page_object_helper::PageBox;
use crate::pages::DEFAULT_MAX_PAGE_TREE_DEPTH;
use crate::{Dictionary, Error, Object, ObjectRef, Pdf, Result};
use std::collections::BTreeSet;
use std::io::{Read, Seek};

// ---------------------------------------------------------------------------
// AnnotationObjectHelper
// ---------------------------------------------------------------------------

/// Typed read-only accessor helper for a PDF annotation dictionary.
///
/// Construct with [`AnnotationObjectHelper::new`], passing the [`ObjectRef`]
/// of any annotation dictionary (e.g. one retrieved from
/// [`crate::PageObjectHelper::get_annotations`]) and a mutable borrow of the
/// open document.
///
/// All accessors are **leaf-only**: they read only the annotation dictionary
/// itself, consistent with ISO 32000-1 §12.5 which specifies that annotation
/// attributes are not inheritable.
pub struct AnnotationObjectHelper<'a, R: Read + Seek> {
    annot_ref: ObjectRef,
    pdf: &'a mut Pdf<R>,
}

impl<'a, R: Read + Seek> AnnotationObjectHelper<'a, R> {
    /// Construct a new helper for the annotation at `annot_ref`.
    ///
    /// The constructor does not resolve the object; errors are surfaced by the
    /// individual accessor methods.
    pub fn new(annot_ref: ObjectRef, pdf: &'a mut Pdf<R>) -> Self {
        Self { annot_ref, pdf }
    }

    /// Resolve the annotation dictionary.
    fn resolve_dict(&mut self) -> Result<Dictionary> {
        match self.pdf.resolve_borrowed(self.annot_ref)? {
            Object::Dictionary(d) => Ok(d.clone()),
            _ => Err(Error::Unsupported(format!(
                "annotation object {} is not a dictionary",
                self.annot_ref
            ))),
        }
    }

    // -----------------------------------------------------------------------
    // subtype — /Subtype (Name, leaf-only)
    // -----------------------------------------------------------------------

    /// Return the annotation subtype (`/Subtype`) as raw name bytes.
    ///
    /// Common values include `b"Text"`, `b"Link"`, `b"Highlight"`,
    /// `b"Widget"`, etc. (ISO 32000-1 Table 169).
    ///
    /// Returns `Ok(None)` when `/Subtype` is absent or not a name.
    ///
    /// # Errors
    ///
    /// Propagates any error from resolving the annotation object.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use flpdf::{AnnotationObjectHelper, ObjectRef, Pdf};
    /// use std::fs::File;
    /// use std::io::BufReader;
    ///
    /// let mut pdf = Pdf::open(BufReader::new(File::open("a.pdf")?))?;
    /// let mut annot = AnnotationObjectHelper::new(ObjectRef::new(5, 0), &mut pdf);
    /// if let Some(subtype) = annot.subtype()? {
    ///     println!("subtype: {}", String::from_utf8_lossy(&subtype));
    /// }
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn subtype(&mut self) -> Result<Option<Vec<u8>>> {
        let dict = self.resolve_dict()?;
        Ok(match dict.get("Subtype") {
            Some(Object::Name(bytes)) => Some(bytes.clone()),
            _ => None,
        })
    }

    // -----------------------------------------------------------------------
    // rect — /Rect (4-element array, leaf-only)
    // -----------------------------------------------------------------------

    /// Return the annotation rectangle (`/Rect`) as a [`PageBox`].
    ///
    /// The four numbers are `[llx, lly, urx, ury]` in default user-space units
    /// (ISO 32000-1 §12.5.4). Both [`Object::Integer`] and [`Object::Real`]
    /// elements are accepted and coerced to `f64`.
    ///
    /// Returns `Ok(None)` when `/Rect` is absent.
    ///
    /// # Errors
    ///
    /// - [`Error::Unsupported`] when `/Rect` is present but is not a 4-element
    ///   numeric array.
    /// - Any error from resolving the annotation object.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use flpdf::{AnnotationObjectHelper, ObjectRef, Pdf};
    /// use std::fs::File;
    /// use std::io::BufReader;
    ///
    /// let mut pdf = Pdf::open(BufReader::new(File::open("a.pdf")?))?;
    /// let mut annot = AnnotationObjectHelper::new(ObjectRef::new(5, 0), &mut pdf);
    /// if let Some(r) = annot.rect()? {
    ///     println!("[{} {} {} {}]", r.llx, r.lly, r.urx, r.ury);
    /// }
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn rect(&mut self) -> Result<Option<PageBox>> {
        let dict = self.resolve_dict()?;
        let val = match dict.get("Rect").cloned() {
            None | Some(Object::Null) => return Ok(None),
            Some(v) => v,
        };
        let arr = resolve_to_array(val, self.pdf, self.annot_ref, "Rect")?;
        parse_rect_array(&arr, b"Rect").map(Some)
    }

    // -----------------------------------------------------------------------
    // appearance — /AP (Dictionary or Reference → Dictionary, leaf-only)
    // -----------------------------------------------------------------------

    /// Return the annotation appearance dictionary (`/AP`).
    ///
    /// `/AP` contains the appearance streams keyed by `/N` (normal), `/R`
    /// (rollover), and `/D` (down) (ISO 32000-1 §12.5.5). The dictionary is
    /// returned as-is; individual appearance streams must be fetched separately.
    ///
    /// An indirect `/AP` reference is resolved automatically.
    ///
    /// Returns `Ok(None)` when `/AP` is absent or null.
    ///
    /// # Errors
    ///
    /// - [`Error::Unsupported`] when `/AP` resolves to a non-dictionary.
    /// - Any error from [`Pdf::resolve`].
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use flpdf::{AnnotationObjectHelper, ObjectRef, Pdf};
    /// use std::fs::File;
    /// use std::io::BufReader;
    ///
    /// let mut pdf = Pdf::open(BufReader::new(File::open("a.pdf")?))?;
    /// let mut annot = AnnotationObjectHelper::new(ObjectRef::new(5, 0), &mut pdf);
    /// if let Some(ap) = annot.appearance()? {
    ///     let has_normal = ap.get("N").is_some();
    ///     println!("has normal appearance: {has_normal}");
    /// }
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn appearance(&mut self) -> Result<Option<Dictionary>> {
        let dict = self.resolve_dict()?;
        resolve_optional_dict(dict.get("AP").cloned(), self.pdf, self.annot_ref, "AP")
    }

    // -----------------------------------------------------------------------
    // action — /A (Dictionary or Reference → Dictionary, leaf-only)
    // -----------------------------------------------------------------------

    /// Return the annotation action dictionary (`/A`).
    ///
    /// The returned dictionary contains at minimum `/S` (action subtype, e.g.
    /// `b"URI"`, `b"GoTo"`) plus action-specific keys (ISO 32000-1 §12.6).
    ///
    /// An indirect `/A` reference is resolved automatically.
    ///
    /// Returns `Ok(None)` when `/A` is absent or null.
    ///
    /// # Errors
    ///
    /// - [`Error::Unsupported`] when `/A` resolves to a non-dictionary.
    /// - Any error from [`Pdf::resolve`].
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use flpdf::{AnnotationObjectHelper, ObjectRef, Pdf};
    /// use std::fs::File;
    /// use std::io::BufReader;
    ///
    /// let mut pdf = Pdf::open(BufReader::new(File::open("a.pdf")?))?;
    /// let mut annot = AnnotationObjectHelper::new(ObjectRef::new(5, 0), &mut pdf);
    /// if let Some(action) = annot.action()? {
    ///     if let Some(Object::Name(s)) = action.get("S") {
    ///         println!("action subtype: {}", String::from_utf8_lossy(s));
    ///     }
    /// }
    /// # use flpdf::Object;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn action(&mut self) -> Result<Option<Dictionary>> {
        let dict = self.resolve_dict()?;
        resolve_optional_dict(dict.get("A").cloned(), self.pdf, self.annot_ref, "A")
    }
}

// ---------------------------------------------------------------------------
// FormFieldObjectHelper
// ---------------------------------------------------------------------------

/// Typed read-only accessor helper for a PDF AcroForm field or widget
/// annotation dictionary.
///
/// Construct with [`FormFieldObjectHelper::new`], passing the [`ObjectRef`]
/// of a field or widget-annotation dictionary and a mutable borrow of the
/// open document.
///
/// The four form-field attributes (`/FT`, `/V`, `/DV`, `/Ff`) are
/// **inheritable** in the field tree (ISO 32000-1 §12.7.3.1): when absent on
/// the field itself, the helper walks the `/Parent` chain until a value is
/// found or the chain is exhausted. A cycle guard and depth limit prevent
/// infinite loops on malformed documents.
///
/// Note: a widget annotation and a terminal form field may be represented by
/// the same dictionary. In that case the same [`ObjectRef`] can be wrapped by
/// both [`AnnotationObjectHelper`] and [`FormFieldObjectHelper`].
pub struct FormFieldObjectHelper<'a, R: Read + Seek> {
    field_ref: ObjectRef,
    pdf: &'a mut Pdf<R>,
}

impl<'a, R: Read + Seek> FormFieldObjectHelper<'a, R> {
    /// Construct a new helper for the form field at `field_ref`.
    ///
    /// The constructor does not resolve the object; errors are surfaced by the
    /// individual accessor methods.
    pub fn new(field_ref: ObjectRef, pdf: &'a mut Pdf<R>) -> Self {
        Self { field_ref, pdf }
    }

    // -----------------------------------------------------------------------
    // field_type — /FT (inheritable Name)
    // -----------------------------------------------------------------------

    /// Return the field type (`/FT`) as raw name bytes.
    ///
    /// Common values are `b"Tx"` (text), `b"Btn"` (button), `b"Ch"` (choice),
    /// `b"Sig"` (signature) (ISO 32000-1 §12.7.3.1).
    ///
    /// `/FT` is inheritable: when absent on the field itself, the `/Parent`
    /// chain is walked until a value is found.
    ///
    /// Returns `Ok(None)` when no node in the chain carries `/FT`.
    ///
    /// # Errors
    ///
    /// - [`Error::Unsupported`] if the field-tree depth limit is exceeded.
    /// - Any error from [`Pdf::resolve`].
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use flpdf::{FormFieldObjectHelper, ObjectRef, Pdf};
    /// use std::fs::File;
    /// use std::io::BufReader;
    ///
    /// let mut pdf = Pdf::open(BufReader::new(File::open("form.pdf")?))?;
    /// let mut field = FormFieldObjectHelper::new(ObjectRef::new(10, 0), &mut pdf);
    /// if let Some(ft) = field.field_type()? {
    ///     println!("field type: {}", String::from_utf8_lossy(&ft));
    /// }
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn field_type(&mut self) -> Result<Option<Vec<u8>>> {
        self.resolve_inherited_name(b"FT")
    }

    // -----------------------------------------------------------------------
    // field_value — /V (inheritable, any Object)
    // -----------------------------------------------------------------------

    /// Return the field value (`/V`).
    ///
    /// The value type depends on the field type: a string for text fields,
    /// a name for check boxes and radio buttons, an array for list boxes, etc.
    /// (ISO 32000-1 §12.7.3.1). The raw [`Object`] is returned without any
    /// text-string decoding.
    ///
    /// `/V` is inheritable: when absent on the field itself, the `/Parent`
    /// chain is walked until a value is found.
    ///
    /// Returns `Ok(None)` when no node in the chain carries `/V`.
    ///
    /// # Errors
    ///
    /// - [`Error::Unsupported`] if the field-tree depth limit is exceeded.
    /// - Any error from [`Pdf::resolve`].
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use flpdf::{FormFieldObjectHelper, Object, ObjectRef, Pdf};
    /// use std::fs::File;
    /// use std::io::BufReader;
    ///
    /// let mut pdf = Pdf::open(BufReader::new(File::open("form.pdf")?))?;
    /// let mut field = FormFieldObjectHelper::new(ObjectRef::new(10, 0), &mut pdf);
    /// match field.field_value()? {
    ///     Some(Object::String(bytes)) => println!("value: {}", String::from_utf8_lossy(&bytes)),
    ///     Some(Object::Name(bytes))   => println!("value: /{}", String::from_utf8_lossy(&bytes)),
    ///     Some(other)                 => println!("value type: {other:?}"),
    ///     None                        => println!("no value"),
    /// }
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn field_value(&mut self) -> Result<Option<Object>> {
        self.resolve_inherited_object(b"V")
    }

    // -----------------------------------------------------------------------
    // field_default_value — /DV (inheritable, any Object)
    // -----------------------------------------------------------------------

    /// Return the field default value (`/DV`).
    ///
    /// Same typing rules as [`field_value`](FormFieldObjectHelper::field_value).
    ///
    /// `/DV` is inheritable: when absent on the field itself, the `/Parent`
    /// chain is walked until a value is found.
    ///
    /// Returns `Ok(None)` when no node in the chain carries `/DV`.
    ///
    /// # Errors
    ///
    /// Same as [`field_value`](FormFieldObjectHelper::field_value).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use flpdf::{FormFieldObjectHelper, Object, ObjectRef, Pdf};
    /// use std::fs::File;
    /// use std::io::BufReader;
    ///
    /// let mut pdf = Pdf::open(BufReader::new(File::open("form.pdf")?))?;
    /// let mut field = FormFieldObjectHelper::new(ObjectRef::new(10, 0), &mut pdf);
    /// if let Some(dv) = field.field_default_value()? {
    ///     println!("default: {dv:?}");
    /// }
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn field_default_value(&mut self) -> Result<Option<Object>> {
        self.resolve_inherited_object(b"DV")
    }

    // -----------------------------------------------------------------------
    // field_flags — /Ff (inheritable Integer bit-field)
    // -----------------------------------------------------------------------

    /// Return the field flags (`/Ff`) as a 64-bit integer bit-field.
    ///
    /// `/Ff` is a 32-bit unsigned integer in the PDF spec (ISO 32000-1 Table
    /// 221) but is stored as [`Object::Integer`] (`i64`) in the object model.
    /// Callers that need the unsigned view may cast with `as u32`.
    ///
    /// `/Ff` is inheritable: when absent on the field itself, the `/Parent`
    /// chain is walked until a value is found.
    ///
    /// Returns `Ok(None)` when no node in the chain carries `/Ff`.
    ///
    /// # Errors
    ///
    /// - [`Error::Unsupported`] if the field-tree depth limit is exceeded.
    /// - Any error from [`Pdf::resolve`].
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use flpdf::{FormFieldObjectHelper, ObjectRef, Pdf};
    /// use std::fs::File;
    /// use std::io::BufReader;
    ///
    /// let mut pdf = Pdf::open(BufReader::new(File::open("form.pdf")?))?;
    /// let mut field = FormFieldObjectHelper::new(ObjectRef::new(10, 0), &mut pdf);
    /// if let Some(ff) = field.field_flags()? {
    ///     // Bit 1 (0-indexed): ReadOnly
    ///     let read_only = (ff as u32) & 1 != 0;
    ///     println!("read-only: {read_only}");
    /// }
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn field_flags(&mut self) -> Result<Option<i64>> {
        self.resolve_inherited_integer(b"Ff")
    }

    // -----------------------------------------------------------------------
    // Private: walk /Parent chain for a Name value
    // -----------------------------------------------------------------------

    fn resolve_inherited_name(&mut self, key: &[u8]) -> Result<Option<Vec<u8>>> {
        let mut seen: BTreeSet<ObjectRef> = BTreeSet::new();
        let mut current = self.field_ref;
        let mut depth: usize = 0;

        loop {
            if depth >= DEFAULT_MAX_PAGE_TREE_DEPTH {
                return Err(Error::Unsupported(format!(
                    "field tree depth exceeds maximum of {} at {}",
                    DEFAULT_MAX_PAGE_TREE_DEPTH, current
                )));
            }

            if !seen.insert(current) {
                return Ok(None); // cycle detected
            }

            let node_obj = self.pdf.resolve_borrowed(current)?;
            let Some(dict) = node_obj.as_dict() else {
                return Err(Error::Unsupported(format!(
                    "field tree node {current} is not a dictionary"
                )));
            };

            // Extract the matched value and the /Parent reference before any
            // mutable resolve, releasing the borrow on `node_obj`/`self.pdf`.
            let found = dict.get(key).cloned();
            let parent_ref = match dict.get("Parent") {
                Some(Object::Reference(r)) => Some(*r),
                _ => None,
            };
            // The clones above copy what we need; drop the `node_obj` borrow
            // here so `self.pdf.resolve` can run below (matches appearance.rs).
            let _ = node_obj;

            if let Some(val) = found {
                // The value may be stored as an indirect reference; resolve one
                // level so an inherited /FT stored as a reference is not
                // silently dropped (matches AcroFormDocumentHelper's deref_leaf).
                // A reference resolving to Null is treated as absent.
                let resolved = match val {
                    Object::Reference(r) => self.pdf.resolve(r)?,
                    other => other,
                };
                match resolved {
                    Object::Null => {} // treat as absent per §7.3.9
                    Object::Name(bytes) => return Ok(Some(bytes)),
                    _ => {} // unexpected type: skip silently, do not error
                }
            }

            // Climb to /Parent.
            match parent_ref {
                Some(r) => {
                    current = r;
                    depth += 1;
                }
                None => return Ok(None),
            }
        }
    }

    // -----------------------------------------------------------------------
    // Private: walk /Parent chain for an arbitrary Object value
    // -----------------------------------------------------------------------

    fn resolve_inherited_object(&mut self, key: &[u8]) -> Result<Option<Object>> {
        let mut seen: BTreeSet<ObjectRef> = BTreeSet::new();
        let mut current = self.field_ref;
        let mut depth: usize = 0;

        loop {
            if depth >= DEFAULT_MAX_PAGE_TREE_DEPTH {
                return Err(Error::Unsupported(format!(
                    "field tree depth exceeds maximum of {} at {}",
                    DEFAULT_MAX_PAGE_TREE_DEPTH, current
                )));
            }

            if !seen.insert(current) {
                return Ok(None);
            }

            let node_obj = self.pdf.resolve_borrowed(current)?;
            let Some(dict) = node_obj.as_dict() else {
                return Err(Error::Unsupported(format!(
                    "field tree node {current} is not a dictionary"
                )));
            };

            // Extract the matched value and the /Parent reference before any
            // mutable resolve, releasing the borrow on `node_obj`/`self.pdf`.
            // The value must be cloned (it may be returned as an owned Object);
            // /Parent is always a reference, so only the copyable ObjectRef is
            // taken to avoid cloning a whole Object.
            let found = dict.get(key).cloned();
            let parent_ref = match dict.get("Parent") {
                Some(Object::Reference(r)) => Some(*r),
                _ => None,
            };
            // The clones above copy what we need; drop the `node_obj` borrow
            // here so `self.pdf.resolve` can run below (matches appearance.rs).
            let _ = node_obj;

            if let Some(val) = found {
                match val {
                    Object::Null => {} // absent per §7.3.9
                    // The value may be stored as an indirect reference; resolve
                    // one level so callers receive the materialized object, not
                    // a bare Reference (matches AcroFormDocumentHelper's
                    // deref_leaf, keeping the two read paths consistent). A
                    // reference resolving to Null is treated as absent, so we
                    // keep climbing the /Parent chain.
                    Object::Reference(r) => match self.pdf.resolve(r)? {
                        Object::Null => {}
                        resolved => return Ok(Some(resolved)),
                    },
                    other => return Ok(Some(other)),
                }
            }

            match parent_ref {
                Some(r) => {
                    current = r;
                    depth += 1;
                }
                None => return Ok(None),
            }
        }
    }

    // -----------------------------------------------------------------------
    // Private: walk /Parent chain for an Integer value
    // -----------------------------------------------------------------------

    fn resolve_inherited_integer(&mut self, key: &[u8]) -> Result<Option<i64>> {
        let mut seen: BTreeSet<ObjectRef> = BTreeSet::new();
        let mut current = self.field_ref;
        let mut depth: usize = 0;

        loop {
            if depth >= DEFAULT_MAX_PAGE_TREE_DEPTH {
                return Err(Error::Unsupported(format!(
                    "field tree depth exceeds maximum of {} at {}",
                    DEFAULT_MAX_PAGE_TREE_DEPTH, current
                )));
            }

            if !seen.insert(current) {
                return Ok(None);
            }

            let node_obj = self.pdf.resolve_borrowed(current)?;
            let Some(dict) = node_obj.as_dict() else {
                return Err(Error::Unsupported(format!(
                    "field tree node {current} is not a dictionary"
                )));
            };

            // Extract the matched value and the /Parent reference before any
            // mutable resolve, releasing the borrow on `node_obj`/`self.pdf`.
            let found = dict.get(key).cloned();
            let parent_ref = match dict.get("Parent") {
                Some(Object::Reference(r)) => Some(*r),
                _ => None,
            };
            // The clones above copy what we need; drop the `node_obj` borrow
            // here so `self.pdf.resolve` can run below (matches appearance.rs).
            let _ = node_obj;

            if let Some(val) = found {
                // Resolve one level if /Ff is stored as an indirect reference,
                // so an inherited reference value is not silently dropped
                // (matches AcroFormDocumentHelper's deref_leaf). A reference
                // resolving to Null is treated as absent.
                let resolved = match val {
                    Object::Reference(r) => self.pdf.resolve(r)?,
                    other => other,
                };
                match resolved {
                    Object::Null => {}
                    Object::Integer(n) => return Ok(Some(n)),
                    _ => {} // wrong type: skip
                }
            }

            match parent_ref {
                Some(r) => {
                    current = r;
                    depth += 1;
                }
                None => return Ok(None),
            }
        }
    }
}

// ---------------------------------------------------------------------------
// Private free functions
// ---------------------------------------------------------------------------

/// Resolve `val` to an `Array`, following at most one level of indirection.
fn resolve_to_array<R: Read + Seek>(
    val: Object,
    pdf: &mut Pdf<R>,
    origin: ObjectRef,
    key: &str,
) -> Result<Vec<Object>> {
    match val {
        Object::Array(arr) => Ok(arr),
        Object::Reference(r) => match pdf.resolve_borrowed(r)? {
            Object::Array(arr) => Ok(arr.clone()),
            _ => Err(Error::Unsupported(format!(
                "/{key} reference {r} on object {origin} does not resolve to an array"
            ))),
        },
        _ => Err(Error::Unsupported(format!(
            "/{key} on object {origin} has unexpected type"
        ))),
    }
}

/// Resolve an optional dictionary value, handling indirection.
///
/// Returns `Ok(None)` when `val` is `None` or `Some(Null)`.
fn resolve_optional_dict<R: Read + Seek>(
    val: Option<Object>,
    pdf: &mut Pdf<R>,
    origin: ObjectRef,
    key: &str,
) -> Result<Option<Dictionary>> {
    match val {
        None | Some(Object::Null) => Ok(None),
        Some(Object::Dictionary(d)) => Ok(Some(d)),
        Some(Object::Reference(r)) => match pdf.resolve_borrowed(r)? {
            Object::Dictionary(d) => Ok(Some(d.clone())),
            Object::Null => Ok(None),
            _ => Err(Error::Unsupported(format!(
                "/{key} reference {r} on object {origin} does not resolve to a dictionary"
            ))),
        },
        Some(_) => Err(Error::Unsupported(format!(
            "/{key} on object {origin} has unexpected type"
        ))),
    }
}

/// Parse a 4-element PDF rectangle array into a [`PageBox`].
///
/// Mirrors `page_object_helper::parse_rect_array` — kept private here to
/// avoid coupling across modules.
fn parse_rect_array(arr: &[Object], key: &[u8]) -> Result<PageBox> {
    if arr.len() != 4 {
        return Err(Error::Unsupported(format!(
            "/{} rectangle array has {} elements, expected 4",
            String::from_utf8_lossy(key),
            arr.len()
        )));
    }
    let mut coords = [0f64; 4];
    for (i, elem) in arr.iter().take(4).enumerate() {
        coords[i] = match elem {
            Object::Integer(n) => *n as f64,
            Object::Real(r) => *r,
            other => {
                return Err(Error::Unsupported(format!(
                    "/{} rectangle element {i} has unexpected type {:?}",
                    String::from_utf8_lossy(key),
                    std::mem::discriminant(other)
                )));
            }
        };
    }
    Ok(PageBox::new(coords[0], coords[1], coords[2], coords[3]))
}