flpdf 0.1.4

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
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
//! Unreferenced-resource pruning (ISO 32000-1 §7.8.3 / qpdf `--remove-unreferenced-resources`).
//!
//! Scans every page's content stream(s) via [`crate::content_stream::ContentStreamParser`],
//! collects every resource name that is actually referenced by a PDF operator, and then
//! removes entries from the page's `/Resources` sub-dictionaries that are not referenced.
//!
//! # Modes
//!
//! | Mode | Behaviour |
//! |------|-----------|
//! | [`RemoveUnreferencedResources::No`]  | No-op. |
//! | [`RemoveUnreferencedResources::Auto`] | Only prunes a page's `/Resources` when it is not shared with (or inherited by) another page. Safe heuristic, qpdf-compatible. |
//! | [`RemoveUnreferencedResources::Yes`] | Prunes on a per-page basis regardless of sharing. When multiple pages reference the same `/Resources` object, the kept set is the *union* of all referencing pages, so no rendering breakage occurs. |
//!
//! # Scope
//!
//! This module only removes entries from the `/Resources` sub-dictionaries
//! (`/Font`, `/XObject`, `/ColorSpace`, `/Pattern`, `/Shading`, `/ExtGState`,
//! `/Properties`). It does **not** garbage-collect unreachable PDF objects at
//! the xref level — that is a separate concern.

use crate::content_stream::{ContentStreamParser, ContentToken};
use crate::filters::decode_stream_data;
use crate::{Dictionary, Error, Object, ObjectRef, Pdf, Result};
use std::collections::{BTreeMap, BTreeSet};
use std::io::{Read, Seek};

/// Resource names referenced by a content scope, keyed by category
/// (`Font`, `XObject`, …) → set of referenced names.
type UsedNames = BTreeMap<Vec<u8>, BTreeSet<Vec<u8>>>;

/// Tracking information for indirect category sub-dictionary objects
/// (e.g. `/Font 6 0 R`).  Built in a global pre-pass over all pages so that
/// the sharing count includes pages Auto-mode would otherwise skip.
///
/// Key: `(category_bytes, cat_sub_dict_ref)`.
type CatRefKey = (Vec<u8>, ObjectRef);

/// Per-category-ref metadata accumulated across all top-level `/Resources`.
struct CatRefInfo {
    /// Number of distinct top-level `/Resources` groups that point to this
    /// indirect category sub-dict.  Used by Auto mode: if > 1, skip pruning.
    group_count: usize,
    /// Union of used names contributed by groups whose used-names are known.
    /// Groups skipped by Auto (shared top-level) do not contribute used-names,
    /// but they still increment `group_count`, so the ref ends up protected.
    used_union: BTreeSet<Vec<u8>>,
}

/// Canonical identifier for a top-level `/Resources` group.
///
/// Used as the key in `cat_ref_seen_groups` so that distinct group types never
/// collide even when they share the same `ObjectRef` number.
///
/// `PageInline` stores the page's own `ObjectRef` (generation 0) without
/// inventing a synthetic generation-1 value, eliminating the collision described
/// in roborev low 指摘2: a real indirect `(N, 1)` object and a page-inline
/// group for page object `(N, 0)` could previously share the same synthetic key.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
enum ResGroupKey {
    /// `/Resources` is an indirect object at the given ref.
    Indirect(ObjectRef),
    /// `/Resources` is an inline dict on the ancestor `/Pages` node at the given ref.
    AncestorInline(ObjectRef),
    /// `/Resources` is an inline dict on the page dict itself; key is the page's ObjectRef.
    PageInline(ObjectRef),
}

// ── Resource location ─────────────────────────────────────────────────────────

/// Where a page's `/Resources` dictionary physically lives.
///
/// Used to distinguish the three cases that need different pruning strategies.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
enum ResourcesLoc {
    /// The page has no `/Resources` entry anywhere in its parent chain.
    None,
    /// `/Resources` is an inline (direct) dictionary on the page dict itself.
    PageInline,
    /// `/Resources` is an inline (direct) dictionary on an ancestor `/Pages` node.
    AncestorInline(ObjectRef),
    /// `/Resources` is an indirect object reference (anywhere in the chain).
    Indirect(ObjectRef),
}

// ── Resource category names we prune ─────────────────────────────────────────

/// The seven resource sub-dictionary keys we inspect and prune.
const RESOURCE_CATEGORIES: &[&str] = &[
    "Font",
    "XObject",
    "ColorSpace",
    "Pattern",
    "Shading",
    "ExtGState",
    "Properties",
];

// ── Device-colorspace names that are never looked up in /ColorSpace ───────────

/// Names that appear as operands to the page-content `cs`/`CS` operators but
/// are **built-in** device colour spaces, not entries in the page's
/// `/ColorSpace` dictionary.
///
/// ISO 32000-1 §8.6.8: only `/DeviceGray`, `/DeviceRGB`, `/DeviceCMYK`, and
/// `/Pattern` may be selected by name directly in page content.  All other
/// colour spaces (`/CalGray`, `/CalRGB`, `/Lab`, `/ICCBased`, `/Indexed`, …)
/// are array-based and **must** be named via an entry in `/Resources/ColorSpace`.
fn is_builtin_color_space_cs_op(name: &[u8]) -> bool {
    matches!(
        name,
        b"DeviceGray" | b"DeviceRGB" | b"DeviceCMYK" | b"Pattern"
    )
}

/// Names that are valid **inline-image** colour-space specifiers (ISO 32000-1
/// Table 93) and do **not** correspond to entries in `/Resources/ColorSpace`.
///
/// This covers both the full Device names and the one-letter abbreviations
/// permitted inside inline-image dictionaries (`BI … ID … EI`).
fn is_builtin_inline_image_cs(name: &[u8]) -> bool {
    matches!(
        name,
        // Full Device names are also valid in inline images.
        b"DeviceGray"
            | b"DeviceRGB"
            | b"DeviceCMYK"
            | b"Pattern"
            // Abbreviated names (Table 93).
            | b"G"
            | b"RGB"
            | b"CMYK"
            | b"I"
    )
}

// ── Mode enum ────────────────────────────────────────────────────────────────

/// How [`remove_unreferenced_resources`] handles the `/Resources` sub-dictionaries.
///
/// Mirrors qpdf's `--remove-unreferenced-resources=auto|yes|no`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum RemoveUnreferencedResources {
    /// Safe heuristic: only prune `/Resources` that belong exclusively to one page
    /// (not shared via inheritance or the same indirect object reference).
    /// This is the default and matches qpdf's `auto` behaviour.
    #[default]
    Auto,
    /// Prune unreferenced entries on a per-page basis regardless of sharing.
    /// When the same `/Resources` object is referenced by several pages, the
    /// union of all referencing pages' used names is computed so that no page
    /// loses a resource it genuinely needs.
    Yes,
    /// No-op: leave all `/Resources` entries untouched.
    No,
}

// ── Public entry point ────────────────────────────────────────────────────────

/// Remove unreferenced `/Resources` entries from every page in `pdf`.
///
/// See [`RemoveUnreferencedResources`] for mode semantics.
///
/// # Errors
///
/// Propagates errors from [`Pdf::resolve`], content-stream decoding, or
/// content-stream tokenisation. Malformed-but-recoverable content is silently
/// skipped (an error in one page's content stream does not abort the whole
/// operation, matching qpdf's liberal behaviour).
pub fn remove_unreferenced_resources<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    mode: RemoveUnreferencedResources,
) -> Result<()> {
    if mode == RemoveUnreferencedResources::No {
        return Ok(());
    }

    // ── 1. Collect all page refs ──────────────────────────────────────────────
    let page_refs = crate::pages::page_refs(pdf)?;

    // ── 2. For each page, determine where its /Resources physically lives ────────
    // This drives both the "shared" detection for Auto mode and the grouping
    // for Yes mode (union-over-sharing-pages).
    let mut page_res_loc: Vec<ResourcesLoc> = Vec::with_capacity(page_refs.len());
    for &pr in &page_refs {
        page_res_loc.push(resources_location(pdf, pr)?);
    }

    // Count how many pages reference each resources ObjectRef (Indirect or
    // AncestorInline). ref_count[r] > 1 means the resources dict is shared.
    let mut ref_count: BTreeMap<ObjectRef, usize> = BTreeMap::new();
    let mut ancestor_count: BTreeMap<ObjectRef, usize> = BTreeMap::new();
    for loc in &page_res_loc {
        match loc {
            ResourcesLoc::Indirect(r) => {
                *ref_count.entry(*r).or_insert(0) += 1;
            }
            ResourcesLoc::AncestorInline(a) => {
                *ancestor_count.entry(*a).or_insert(0) += 1;
            }
            _ => {}
        }
    }

    // ── 3. Collect used names per resources-ref (for Yes-mode union) ──────────
    // For Auto mode we only need per-page used-names for unshared pages.
    // For Yes mode we need the union grouped by resources-ref.

    // Map from indirect resources ObjectRef → union of used names per category.
    let mut ref_used: BTreeMap<ObjectRef, UsedNames> = BTreeMap::new();
    // Map from ancestor /Pages ObjectRef → union of used names (AncestorInline case).
    let mut ancestor_inline_used: BTreeMap<ObjectRef, UsedNames> = BTreeMap::new();
    // For pages with PageInline /Resources, store per-page used names keyed by index.
    let mut inline_used: Vec<Option<UsedNames>> = vec![None; page_refs.len()];

    for (i, &page_ref) in page_refs.iter().enumerate() {
        // Determine if this page's resources are shared (for Auto mode skip).
        let is_shared = match &page_res_loc[i] {
            ResourcesLoc::Indirect(r) => ref_count.get(r).copied().unwrap_or(0) > 1,
            ResourcesLoc::AncestorInline(a) => ancestor_count.get(a).copied().unwrap_or(0) > 1,
            _ => false, // PageInline and None: always unshared
        };

        if mode == RemoveUnreferencedResources::Auto && is_shared {
            // Auto: skip shared resources — we must not prune them.
            continue;
        }

        // Collect the used names for this page.
        let used = collect_used_names_for_page(pdf, page_ref)?;

        match &page_res_loc[i] {
            ResourcesLoc::Indirect(r) => {
                // Merge into the union for this resources ref.
                let entry = ref_used.entry(*r).or_default();
                for (cat, names) in used {
                    entry.entry(cat).or_default().extend(names);
                }
            }
            ResourcesLoc::AncestorInline(a) => {
                // Merge into the union for this ancestor /Pages node.
                let entry = ancestor_inline_used.entry(*a).or_default();
                for (cat, names) in used {
                    entry.entry(cat).or_default().extend(names);
                }
            }
            ResourcesLoc::PageInline => {
                // Inline resources on page itself: store per-page.
                inline_used[i] = Some(used);
            }
            ResourcesLoc::None => {}
        }
    }

    // ── 3b. Build global cat-ref sharing table (指摘1 fix) ───────────────────
    // An indirect category sub-dict (e.g. `/Font 6 0 R`) may be shared between
    // several *different* top-level /Resources objects that each belong to
    // different page groups.  Auto mode's top-level sharing detection only
    // protects pages that share the same top-level /Resources, so it cannot
    // prevent cross-group damage.
    //
    // We do a **global** pre-pass over every page's top-level /Resources
    // (regardless of Auto skip decisions) to count how many distinct top-level
    // /Resources groups contain each indirect category ref, and to accumulate
    // the union of used names from groups whose used-names are already known.
    //
    // Key insight: groups that Auto *skipped* (shared top-level) do NOT
    // contribute used-names (we have none), but they DO increment `group_count`,
    // so any cat-ref they contain ends up with group_count > 1 and is protected
    // even in Yes mode.
    let mut cat_ref_map: BTreeMap<CatRefKey, CatRefInfo> = BTreeMap::new();

    // Helper closure-equivalent: collect cat-refs from a /Resources dict.
    // `top_res_ref` is the ObjectRef of the owning top-level resources group
    // (used as a set key so the same group is only counted once per cat-ref).
    // `used_for_group` is the already-computed used-names for this group,
    // or None if this group was Auto-skipped.
    //
    // We track (cat_ref, seen_top_level_groups) to avoid double-counting when
    // multiple pages share the same top-level Indirect /Resources.
    let mut cat_ref_seen_groups: BTreeMap<CatRefKey, BTreeSet<ResGroupKey>> = BTreeMap::new();

    for (i, loc) in page_res_loc.iter().enumerate() {
        // Resolve this page's top-level /Resources dict (if any).
        let res_dict_opt: Option<Dictionary> = match loc {
            ResourcesLoc::Indirect(r) => match pdf.resolve(*r) {
                Ok(Object::Dictionary(d)) => Some(d),
                _ => None,
            },
            ResourcesLoc::PageInline => {
                // Read the inline dict from the page object.
                match pdf.resolve(page_refs[i]) {
                    Ok(Object::Dictionary(page_dict)) => {
                        match page_dict.get("Resources").cloned() {
                            Some(Object::Dictionary(d)) => Some(d),
                            _ => None,
                        }
                    }
                    _ => None,
                }
            }
            ResourcesLoc::AncestorInline(a) => match pdf.resolve(*a) {
                Ok(Object::Dictionary(anc_dict)) => match anc_dict.get("Resources").cloned() {
                    Some(Object::Dictionary(d)) => Some(d),
                    _ => None,
                },
                _ => None,
            },
            ResourcesLoc::None => None,
        };

        let Some(res_dict) = res_dict_opt else {
            continue;
        };

        // The canonical key for this top-level resources group.
        // Use the typed ResGroupKey enum so that PageInline(page_ref) never
        // collides with a real Indirect(ObjectRef) even when the object numbers
        // happen to be identical (roborev low 指摘2).
        let group_key: ResGroupKey = match loc {
            ResourcesLoc::Indirect(r) => ResGroupKey::Indirect(*r),
            ResourcesLoc::AncestorInline(a) => ResGroupKey::AncestorInline(*a),
            ResourcesLoc::PageInline => ResGroupKey::PageInline(page_refs[i]),
            ResourcesLoc::None => unreachable!("None loc filtered above by res_dict_opt"),
        };

        // What used-names does this group contribute?
        // None if the group was Auto-skipped (shared top-level).
        let group_used: Option<&UsedNames> = match loc {
            ResourcesLoc::Indirect(r) => ref_used.get(r),
            ResourcesLoc::AncestorInline(a) => ancestor_inline_used.get(a),
            ResourcesLoc::PageInline => inline_used[i].as_ref(),
            ResourcesLoc::None => None,
        };

        for &category in RESOURCE_CATEGORIES {
            let cat_key = category.as_bytes();
            if let Some(cat_ref) = res_dict.get(category).and_then(Object::as_ref_id) {
                let key: CatRefKey = (cat_key.to_vec(), cat_ref);

                let seen = cat_ref_seen_groups.entry(key.clone()).or_default();
                if seen.insert(group_key) {
                    // First time we see this cat_ref from this group.
                    let info = cat_ref_map
                        .entry(key.clone())
                        .or_insert_with(|| CatRefInfo {
                            group_count: 0,
                            used_union: BTreeSet::new(),
                        });
                    info.group_count += 1;

                    // Merge this group's known used-names for this category.
                    if let Some(used_map) = group_used {
                        if let Some(names) = used_map.get(cat_key) {
                            info.used_union.extend(names.iter().cloned());
                        }
                    }
                    // If group_used is None (Auto-skipped group), we have no
                    // used-names to contribute — group_count alone protects
                    // the ref in Auto mode.
                }
            }
        }
    }

    // ── 4. Prune: indirect resources objects ──────────────────────────────────
    for (res_ref, used) in &ref_used {
        prune_resources_object(pdf, *res_ref, used, &cat_ref_map, mode)?;
    }

    // ── 5. Prune: inline (direct) resources embedded in ancestor /Pages nodes ──
    for (ancestor_ref, used) in &ancestor_inline_used {
        prune_ancestor_inline_resources(pdf, *ancestor_ref, used, &cat_ref_map, mode)?;
    }

    // ── 6. Prune: inline (direct) resources embedded in page dicts ────────────
    for (i, used_opt) in inline_used.iter().enumerate() {
        let Some(used) = used_opt else { continue };
        let page_ref = page_refs[i];
        prune_inline_resources(pdf, page_ref, used, &cat_ref_map, mode)?;
    }

    Ok(())
}

// ── Helpers ───────────────────────────────────────────────────────────────────

/// Determine where a page's `/Resources` dictionary physically lives.
///
/// Walks the parent chain looking for the first `/Resources` entry and
/// returns a [`ResourcesLoc`] discriminating among:
/// - [`ResourcesLoc::Indirect`] – indirect object reference (anywhere in chain)
/// - [`ResourcesLoc::PageInline`] – inline dict on the page dict itself
/// - [`ResourcesLoc::AncestorInline`] – inline dict on a `/Pages` ancestor
/// - [`ResourcesLoc::None`] – no `/Resources` found at all
fn resources_location<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    page_ref: ObjectRef,
) -> Result<ResourcesLoc> {
    // Walk the parent chain looking for the first /Resources entry.
    let mut current = page_ref;
    let mut seen: BTreeSet<ObjectRef> = BTreeSet::new();
    let mut depth = 0usize;
    const MAX_DEPTH: usize = 100;

    loop {
        if depth >= MAX_DEPTH {
            return Ok(ResourcesLoc::None);
        }
        if !seen.insert(current) {
            return Ok(ResourcesLoc::None); // cycle
        }
        depth += 1;

        let node_obj = pdf.resolve(current)?;
        let Some(dict) = node_obj.into_dict() else {
            return Ok(ResourcesLoc::None);
        };

        match dict.get("Resources").cloned() {
            Some(Object::Reference(r)) => return Ok(ResourcesLoc::Indirect(r)),
            Some(Object::Dictionary(_)) => {
                // Inline dict: distinguish page-level vs ancestor.
                if current == page_ref {
                    return Ok(ResourcesLoc::PageInline);
                } else {
                    return Ok(ResourcesLoc::AncestorInline(current));
                }
            }
            Some(Object::Null) | None => {
                // Fall through to parent.
                match dict.get("Parent").cloned() {
                    Some(Object::Reference(parent)) => {
                        current = parent;
                    }
                    _ => return Ok(ResourcesLoc::None),
                }
            }
            _ => return Ok(ResourcesLoc::None),
        }
    }
}

/// Collect every resource name actually referenced by a page's content stream.
///
/// Returns a `BTreeMap<category_name, BTreeSet<resource_name>>` covering the
/// seven resource categories.
///
/// Form XObjects are recursed into (using their own `/Resources` scope), and
/// any name that falls outside a Form's own resources sub-category is
/// attributed to the calling page's resources.
fn collect_used_names_for_page<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    page_ref: ObjectRef,
) -> Result<UsedNames> {
    let content_bytes = crate::pages::page_content_bytes(pdf, page_ref)?;

    // Resolve the page's own /Resources for Form recursion scoping.
    let page_resources = crate::pages::resolve_inherited_resources(pdf, page_ref)?;

    let mut used: UsedNames = BTreeMap::new();
    let mut visited_xobjects: BTreeSet<ObjectRef> = BTreeSet::new();

    collect_from_stream(
        pdf,
        &content_bytes,
        page_resources.as_ref(),
        &mut used,
        &mut visited_xobjects,
        0,
    )?;

    Ok(used)
}

/// Maximum recursion depth for Form XObject traversal.
///
/// Indirect Form XObjects are guarded by `visited` (ObjectRef cycle detection).
/// Direct-stream Form XObjects are owned by their containing dict and cannot
/// form cycles in well-formed PDFs, but we cap depth as an extra safeguard.
const MAX_FORM_DEPTH: usize = 64;

/// Core recursive walker: tokenises `stream_bytes` and records every resource
/// reference into `used`. `resources` is the `/Resources` dict in scope for
/// this stream (the page dict's or a Form XObject's). `visited` prevents
/// infinite recursion through cyclic Form XObjects.
fn collect_from_stream<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    stream_bytes: &[u8],
    resources: Option<&Dictionary>,
    used: &mut UsedNames,
    visited: &mut BTreeSet<ObjectRef>,
    depth: usize,
) -> Result<()> {
    let parser = ContentStreamParser::new(stream_bytes);
    for token_result in parser {
        // On parse error: skip the rest of this stream gracefully.
        let Ok(token) = token_result else { break };

        match token {
            ContentToken::Op { operands, operator } => {
                process_operator(pdf, &operator, &operands, resources, used, visited, depth)?;
            }
            ContentToken::InlineImage { dict, .. } => {
                // /CS operand in an inline image may reference /ColorSpace.
                // Abbreviated key is /CS (ISO 32000-1 Table 93).
                let cs_val = dict.get("CS").or_else(|| dict.get("ColorSpace")).cloned();
                if let Some(name) = cs_val.and_then(Object::into_name) {
                    if !is_builtin_inline_image_cs(&name) {
                        used.entry(b"ColorSpace".to_vec()).or_default().insert(name);
                    }
                }
            }
            ContentToken::Comment(_) => {}
        }
    }
    Ok(())
}

/// Process a single content-stream operator and record any resource references
/// into `used`.
fn process_operator<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    operator: &[u8],
    operands: &[Object],
    resources: Option<&Dictionary>,
    used: &mut UsedNames,
    visited: &mut BTreeSet<ObjectRef>,
    depth: usize,
) -> Result<()> {
    match operator {
        // /XObject — `name Do`
        b"Do" => {
            if let Some(name) = operands.first().and_then(Object::as_name) {
                used.entry(b"XObject".to_vec())
                    .or_default()
                    .insert(name.to_vec());

                // Recurse into Form XObjects.
                recurse_form_xobject(pdf, name, resources, used, visited, depth)?;
            }
        }

        // /Font — `name size Tf`
        b"Tf" => {
            if let Some(name) = operands.first().and_then(Object::as_name) {
                used.entry(b"Font".to_vec())
                    .or_default()
                    .insert(name.to_vec());
            }
        }

        // /ExtGState — `name gs`
        b"gs" => {
            if let Some(name) = operands.first().and_then(Object::as_name) {
                used.entry(b"ExtGState".to_vec())
                    .or_default()
                    .insert(name.to_vec());
            }
        }

        // /ColorSpace — `name cs` (non-stroking) / `name CS` (stroking)
        b"cs" | b"CS" => {
            if let Some(name) = operands.first().and_then(Object::as_name) {
                if !is_builtin_color_space_cs_op(name) {
                    used.entry(b"ColorSpace".to_vec())
                        .or_default()
                        .insert(name.to_vec());
                }
            }
        }

        // /Pattern — `scn` / `SCN`: last operand may be a Name (pattern name).
        b"scn" | b"SCN" => {
            if let Some(name) = operands.last().and_then(Object::as_name) {
                used.entry(b"Pattern".to_vec())
                    .or_default()
                    .insert(name.to_vec());
            }
        }

        // /Shading — `name sh`
        b"sh" => {
            if let Some(name) = operands.first().and_then(Object::as_name) {
                used.entry(b"Shading".to_vec())
                    .or_default()
                    .insert(name.to_vec());
            }
        }

        // /Properties — `tag props BDC` / `tag props DP`
        // Operand index 1 is the property list: a Name → /Properties ref, or
        // a direct dict << … >> (not a /Properties ref; skip).
        b"BDC" | b"DP" => {
            if let Some(name) = operands.get(1).and_then(Object::as_name) {
                used.entry(b"Properties".to_vec())
                    .or_default()
                    .insert(name.to_vec());
            }
        }

        _ => {}
    }
    Ok(())
}

/// If `xobject_name` resolves to a Form XObject, decode and recurse into its
/// content stream.
///
/// Scoping rule (PDF spec §8.10.4):
/// - If the Form XObject has its own `/Resources` entry, resource names used
///   inside the Form resolve against the Form's own resources dict. Those names
///   must NOT be added to the calling page's `used` set — doing so would cause
///   page-level resources with the same name (but unused by the page itself) to
///   be incorrectly retained when pruning.
/// - If the Form XObject has no `/Resources` entry, it inherits the calling
///   scope's resources; names referenced inside the Form are attributed to the
///   page's `used` set as before.
///
/// The XObject entry in `/Resources/XObject` may be either an indirect
/// `Object::Reference` (the common case) or a direct `Object::Stream` (allowed
/// by the PDF spec for inline stream objects).  Both are handled here.
///
/// Indirect references use `visited` (an `ObjectRef` set) for cycle detection.
/// Direct streams are owned by their containing dictionary and therefore cannot
/// be reached through a cycle in well-formed PDFs; `depth` provides an extra
/// guard against pathological documents.
fn recurse_form_xobject<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    xobject_name: &[u8],
    page_resources: Option<&Dictionary>,
    used: &mut UsedNames,
    visited: &mut BTreeSet<ObjectRef>,
    depth: usize,
) -> Result<()> {
    // Guard against excessively deep recursion (applies to direct-stream forms
    // in particular, since indirect refs are additionally guarded by `visited`).
    if depth >= MAX_FORM_DEPTH {
        return Ok(());
    }

    // Locate the XObject entry in the current /Resources scope. The
    // `/XObject` resource category itself may be a direct dictionary *or*
    // an indirect reference (`/XObject 6 0 R`) — resolve the latter, the
    // same way `apply_pruning` already treats indirect category dicts.
    let xobj_val: Option<Object> = match page_resources.and_then(|res| res.get("XObject").cloned())
    {
        Some(Object::Dictionary(xobj_dict)) => xobj_dict.get(xobject_name).cloned(),
        Some(Object::Reference(cat_ref)) => match pdf.resolve(cat_ref)? {
            Object::Dictionary(xobj_dict) => xobj_dict.get(xobject_name).cloned(),
            _ => None,
        },
        _ => None,
    };

    let Some(xobj_val) = xobj_val else {
        return Ok(());
    };

    // For indirect XObject references, record the ObjectRef so we can do
    // stack-pop cycle detection (see below).  Direct streams cannot form cycles
    // in well-formed PDFs, so no entry is needed for them.
    let indirect_ref: Option<ObjectRef> = match &xobj_val {
        Object::Reference(r) => Some(*r),
        _ => None,
    };

    // Resolve to a Stream, handling both indirect references and direct streams.
    let stream: crate::object::Stream = match xobj_val {
        Object::Reference(xobj_ref) => {
            let obj = pdf.resolve(xobj_ref)?;
            match obj {
                Object::Stream(s) => s,
                _ => return Ok(()),
            }
        }
        Object::Stream(s) => {
            // Direct stream: owned by its parent dict, so cycles are impossible
            // in well-formed PDFs.  Depth guard above is sufficient.
            s
        }
        _ => return Ok(()),
    };

    // Only recurse into Form XObjects.
    let is_form = stream
        .dict
        .get("Subtype")
        .is_some_and(|v| matches!(v, Object::Name(n) if n.as_slice() == b"Form"));
    if !is_form {
        return Ok(());
    }

    // Decode the Form's content stream.
    let form_bytes = match decode_stream_data(&stream.dict, &stream.data) {
        Ok(b) => b,
        Err(_) => return Ok(()), // graceful degradation
    };

    // Determine whether the Form has its own /Resources entry.
    // We check for key *presence* (not the resolved value) because an empty or
    // indirect /Resources still means the Form owns its resource scope.
    let form_has_own_resources = stream.dict.get("Resources").is_some();

    // ── Cycle guard (stack-pop style, roborev medium 指摘1) ──────────────────
    //
    // The cycle check is deferred until just before recursion so that early
    // returns above (non-Stream, non-Form, decode failure) never leave the
    // ObjectRef stranded in `visited`.
    //
    // By inserting here and removing *after* the recursive call returns, `visited`
    // acts as a "currently on the call stack" set rather than a "ever visited"
    // set.  This means that the same XObject can be legitimately visited via
    // multiple independent paths (e.g. first inside a Form with its own
    // /Resources, then directly from the page scope) without the first path
    // blocking the second.
    //
    // True cycles (A → B → A) are still caught: while recursing into A, `visited`
    // contains A; when B tries to recurse into A again, `insert` returns false
    // and we return immediately, breaking the loop.  Once B returns and we remove
    // A from `visited`, no infinite loop is possible.
    if let Some(r) = indirect_ref {
        if !visited.insert(r) {
            return Ok(()); // cycle detected — already on the current call stack
        }
    }

    if form_has_own_resources {
        // Resolve the Form's own /Resources dict (may be direct or indirect).
        let form_resources: Option<Dictionary> = match stream.dict.get("Resources").cloned() {
            Some(Object::Dictionary(d)) => Some(d),
            Some(Object::Reference(r)) => match pdf.resolve(r)? {
                Object::Dictionary(d) => Some(d),
                _ => None, // broken ref → treat as empty own scope
            },
            _ => None,
        };

        // Use a throwaway accumulator so that resource names referenced inside
        // the Form do NOT pollute the calling page's used set.
        let mut form_used: UsedNames = BTreeMap::new();
        collect_from_stream(
            pdf,
            &form_bytes,
            form_resources.as_ref(),
            &mut form_used,
            visited,
            depth + 1,
        )?;
        // form_used is intentionally discarded; Form's own /Resources pruning
        // is out of scope for this minimum fix (flpdf-9hc.12.4).
    } else {
        // No /Resources key → Form inherits the calling scope's resources.
        // Attribute all references to the page's used set (original behaviour).
        collect_from_stream(pdf, &form_bytes, page_resources, used, visited, depth + 1)?;
    }

    // ── Stack pop: remove from visited so sibling/later paths can visit this ref ─
    if let Some(r) = indirect_ref {
        visited.remove(&r);
    }

    Ok(())
}

/// Prune `res_ref` (an indirect /Resources object) in-place: remove every
/// entry from each category sub-dict that is NOT in `used`.
fn prune_resources_object<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    res_ref: ObjectRef,
    used: &UsedNames,
    cat_ref_map: &BTreeMap<CatRefKey, CatRefInfo>,
    mode: RemoveUnreferencedResources,
) -> Result<()> {
    let obj = pdf.resolve(res_ref)?;
    let Some(mut res_dict) = obj.into_dict() else {
        return Ok(()); // not a dict — nothing to prune
    };

    apply_pruning(pdf, &mut res_dict, used, cat_ref_map, mode)?;
    pdf.set_object(res_ref, Object::Dictionary(res_dict));
    Ok(())
}

/// Prune the /Resources that is embedded directly in a page dictionary (not an
/// indirect object). We must re-resolve and re-write the whole page dict.
fn prune_inline_resources<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    page_ref: ObjectRef,
    used: &UsedNames,
    cat_ref_map: &BTreeMap<CatRefKey, CatRefInfo>,
    mode: RemoveUnreferencedResources,
) -> Result<()> {
    let page_obj = pdf.resolve(page_ref)?;
    let Some(mut page_dict) = page_obj.into_dict() else {
        return Err(Error::Unsupported(format!(
            "page {page_ref} resolved to non-dictionary"
        )));
    };

    // Pull out the inline /Resources dict, prune it, put it back.
    let resources_val = page_dict.get("Resources").cloned();
    match resources_val {
        Some(Object::Dictionary(mut res_dict)) => {
            apply_pruning(pdf, &mut res_dict, used, cat_ref_map, mode)?;
            page_dict.insert("Resources", Object::Dictionary(res_dict));
        }
        _ => return Ok(()), // nothing inline to prune
    }

    pdf.set_object(page_ref, Object::Dictionary(page_dict));
    Ok(())
}

/// Prune the /Resources that is embedded directly in an ancestor /Pages node.
/// The union of used names across all pages that inherit from this ancestor is
/// given by `used`. We resolve the ancestor node, mutate its inline /Resources,
/// and write it back via `set_object`.
fn prune_ancestor_inline_resources<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    ancestor_ref: ObjectRef,
    used: &UsedNames,
    cat_ref_map: &BTreeMap<CatRefKey, CatRefInfo>,
    mode: RemoveUnreferencedResources,
) -> Result<()> {
    let ancestor_obj = pdf.resolve(ancestor_ref)?;
    let Some(mut ancestor_dict) = ancestor_obj.into_dict() else {
        return Ok(()); // not a dict — nothing to prune
    };

    let resources_val = ancestor_dict.get("Resources").cloned();
    match resources_val {
        Some(Object::Dictionary(mut res_dict)) => {
            apply_pruning(pdf, &mut res_dict, used, cat_ref_map, mode)?;
            ancestor_dict.insert("Resources", Object::Dictionary(res_dict));
        }
        _ => return Ok(()), // not an inline dict — nothing to prune here
    }

    pdf.set_object(ancestor_ref, Object::Dictionary(ancestor_dict));
    Ok(())
}

/// Mutate `res_dict` by removing every entry from each resource sub-category
/// that is not listed in `used`. Empty sub-category dicts are removed entirely.
///
/// Handles both direct Dictionary values and indirect Reference values for
/// category sub-dictionaries (e.g., `/Font 10 0 R`). When the category value
/// is a Reference, the referenced object is pruned in-place via `pdf.set_object`.
///
/// # Indirect category sub-dict sharing (指摘1 fix)
///
/// An indirect category sub-dict (e.g. `/Font 6 0 R`) may be referenced by
/// several different top-level `/Resources` groups.  `cat_ref_map` carries
/// the global sharing count and the union of used names across all groups.
///
/// - **Auto mode**: if `group_count > 1`, leave the sub-dict untouched
///   (same philosophy as top-level sharing protection).
/// - **Yes mode**: always use the global `used_union` rather than the
///   per-group `used` argument, so no cross-group used name is lost.
///
/// Because the same `cat_ref` may appear in multiple calls to `apply_pruning`
/// (once per top-level resources group that contains it), we do the actual
/// `set_object` write on the first call only.  A written `cat_ref` is detected
/// on subsequent calls by the fact that its resolved dict will have already
/// had entries removed; since we only write (never expand), idempotency is
/// guaranteed — but to avoid redundant I/O we rely on `cat_ref_map` tracking.
///
/// Note: when all entries are pruned from an indirect cat sub-dict, the empty
/// indirect object is left in place (as an orphan).  Removing the containing
/// category key from *all* top-level `/Resources` dicts that reference it would
/// require tracking every such res_dict across calls, which is out of scope;
/// xref-level GC handles orphans separately.
fn apply_pruning<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    res_dict: &mut Dictionary,
    used: &UsedNames,
    cat_ref_map: &BTreeMap<CatRefKey, CatRefInfo>,
    mode: RemoveUnreferencedResources,
) -> Result<()> {
    for &category in RESOURCE_CATEGORIES {
        let cat_key = category.as_bytes();
        let cat_val = res_dict.get(category).cloned();

        match cat_val {
            Some(Object::Dictionary(mut cat_dict)) => {
                // Direct dictionary — prune in place and write back.
                let empty_set = BTreeSet::new();
                let used_names = used.get(cat_key).unwrap_or(&empty_set);

                let to_remove: Vec<Vec<u8>> = cat_dict
                    .iter()
                    .filter(|(k, _)| !used_names.contains(*k))
                    .map(|(k, _)| k.to_vec())
                    .collect();
                for key in to_remove {
                    cat_dict.remove(&key);
                }

                if cat_dict.iter().next().is_none() {
                    res_dict.remove(category);
                } else {
                    res_dict.insert(category, Object::Dictionary(cat_dict));
                }
            }
            Some(Object::Reference(cat_ref)) => {
                // Indirect reference to category sub-dictionary.
                //
                // Check the global cat-ref sharing table first (指摘1):
                let map_key: CatRefKey = (cat_key.to_vec(), cat_ref);

                if let Some(info) = cat_ref_map.get(&map_key) {
                    if mode == RemoveUnreferencedResources::Auto && info.group_count > 1 {
                        // Auto: multiple top-level /Resources groups share this
                        // indirect cat sub-dict → protect it, same as top-level
                        // sharing protection.
                        continue;
                    }

                    // Yes (or Auto with group_count == 1): prune using the
                    // global union, not just the per-group `used`.
                    let resolved = pdf.resolve(cat_ref)?;
                    let Some(mut cat_dict) = resolved.into_dict() else {
                        continue; // not a dict — skip safely
                    };

                    let to_remove: Vec<Vec<u8>> = cat_dict
                        .iter()
                        .filter(|(k, _)| !info.used_union.contains(*k))
                        .map(|(k, _)| k.to_vec())
                        .collect();
                    for key in to_remove {
                        cat_dict.remove(&key);
                    }

                    if cat_dict.iter().next().is_none() {
                        // All entries pruned — leave the empty indirect object as
                        // an orphan (xref GC is out of scope for this module).
                        // Do not remove the category from res_dict here because
                        // the same cat_ref may still be referenced by other
                        // top-level /Resources dicts; their apply_pruning calls
                        // will each see an already-empty dict and remove their
                        // own res_dict entry.
                        res_dict.remove(category);
                    } else {
                        pdf.set_object(cat_ref, Object::Dictionary(cat_dict));
                    }
                } else {
                    // No entry in cat_ref_map (e.g. this page was fully
                    // Auto-skipped and no used-names were collected). Fall back
                    // to the legacy per-group path which leaves the dict untouched
                    // when used_names is empty — a safe conservative choice.
                    let resolved = pdf.resolve(cat_ref)?;
                    let Some(mut cat_dict) = resolved.into_dict() else {
                        continue;
                    };

                    let empty_set = BTreeSet::new();
                    let used_names = used.get(cat_key).unwrap_or(&empty_set);

                    let to_remove: Vec<Vec<u8>> = cat_dict
                        .iter()
                        .filter(|(k, _)| !used_names.contains(*k))
                        .map(|(k, _)| k.to_vec())
                        .collect();
                    for key in to_remove {
                        cat_dict.remove(&key);
                    }

                    if cat_dict.iter().next().is_none() {
                        res_dict.remove(category);
                    } else {
                        pdf.set_object(cat_ref, Object::Dictionary(cat_dict));
                    }
                }
            }
            _ => {
                // Absent or non-dictionary/non-reference value — skip.
                continue;
            }
        }
    }
    Ok(())
}