flpdf 0.9.0

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
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
//! Apply overlay and underlay content to a destination page.
//!
//! qpdf correspondence: QPDFPageObjectHelper.cc placement and QPDFJob.cc overlay orchestration responsibilities.
//!
//!
//! Each destination page that receives at least one overlay or underlay is
//! rewritten as follows (see [`get_form_xobject_for_page`](crate::page_form_xobject)):
//!
//! 1. The destination page itself becomes a Form XObject named `/Fx0`.
//! 2. Each source (underlay or overlay) is a Form XObject already imported into
//!    the destination; it is named `/Fx1`, `/Fx2`, … in
//!    underlays-then-overlays declaration order (qpdf's
//!    `getUniqueResourceName("/Fx", …)`).
//! 3. The page `/Resources` is replaced with `<< /XObject << /Fx0 … /FxN >> >>`
//!    (the original resources now live inside `/Fx0`).
//! 4. The page `/Contents` is replaced with a single new stream that draws, in
//!    order, the underlays, then `/Fx0`, then the overlays. Each is placed with
//!    a `placeFormXObject` fragment: underlays/overlays into the destination
//!    `/TrimBox`, `/Fx0` into the destination `/MediaBox`.
//!
//! The placement matrix follows qpdf's `getMatrixForFormXObjectPlacement`:
//! scale-to-fit (never scaling up) and centring the transformed `/BBox` inside
//! the placement rectangle. Numbers are formatted like qpdf's
//! `QUtil::double_to_string` (`%.5f` with trailing zeros and a trailing `.`
//! stripped).

use std::collections::BTreeMap;
use std::io::{Read, Seek};
use std::rc::Rc;

use super::page_range::PageRange;
use crate::page_document_helper::PageDocumentHelper;
use crate::page_form_xobject::get_form_xobject_for_page;
use crate::page_object_helper::{rectangle_from_handle, PageBox, PageObjectHelper};
use crate::{Error, Matrix, ObjectHandle, ObjectRef, Pdf, Rectangle, Result};

/// Whether a source page is drawn beneath (`Underlay`) or above (`Overlay`) the
/// destination page's own content.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OverlayKind {
    /// Drawn beneath the destination page content (before `/Fx0`).
    Underlay,
    /// Drawn above the destination page content (after `/Fx0`).
    Overlay,
}

/// A single overlay/underlay source: a source page identity retained for lazy
/// Form XObject import and the canonical foreign-document
/// `PageObjectHelper::copy_annotations_from` route.
#[derive(Debug, Clone)]
pub(crate) struct OverlaySource {
    /// The source's kind (overlay or underlay).
    pub kind: OverlayKind,
    /// `(source document index, source page reference)` used for per-placement
    /// annotation copying and lazy Form XObject import.
    pub source_page: (usize, ObjectRef),
}

/// Resolve an overlay source's imported Form XObject, importing it only on the
/// first `(source document, source page)` use. This is qpdf's persistent `fo`
/// map from `doUnderOverlayForPage`.
fn resolve_overlay_xobject<R: Read + Seek, RS: Read + Seek>(
    dest: &mut Pdf<R>,
    source_page: (usize, ObjectRef),
    imported_sources: &mut BTreeMap<(usize, ObjectRef), ObjectRef>,
    source_documents: &mut [&mut Pdf<RS>],
) -> Result<ObjectRef> {
    let (source_index, source_page_ref) = source_page;
    if let Some(&xobject_ref) = imported_sources.get(&(source_index, source_page_ref)) {
        return Ok(xobject_ref);
    }
    // cov:ignore-start: OverlaySpec constructs source-document indices from
    // the same source_documents slice; this is a defensive public-helper guard.
    let source = source_documents.get_mut(source_index).ok_or_else(|| {
        Error::Unsupported(format!(
            "overlay source document index {} is out of range",
            source_index
        ))
    })?;
    // cov:ignore-end
    let mut source_page = PageObjectHelper::new(source_page_ref, source);
    let source_form = source_page.get_form_xobject_for_page(true)?;
    let copied = dest.copy_foreign_object(&source_form)?;
    let xobject_ref = copied
        .object_ref()
        .ok_or_else(|| Error::Unsupported("imported Form XObject is not indirect".into()))?;
    imported_sources.insert((source_index, source_page_ref), xobject_ref);
    Ok(xobject_ref)
}

/// Apply an ordered list of overlay/underlay `sources` to the destination page
/// at `dest_page_ref`, mirroring qpdf's `QPDFJob::doUnderOverlayForPage`.
///
/// The destination page becomes Form XObject `/Fx0`; each source is named
/// `/Fx1`, `/Fx2`, … in underlays-then-overlays declaration order. Imported
/// source Forms are allocated lazily after `/Fx0`, matching qpdf's allocation
/// order. The page `/Resources` is replaced with `<< /XObject << /Fx0 … >> >>`
/// and `/Contents` with one new stream that draws the underlays, then `/Fx0`,
/// then the overlays.
fn under_overlay_for_page<R: Read + Seek, RS: Read + Seek>(
    dest: &mut Pdf<R>,
    dest_page_ref: ObjectRef,
    sources: &[OverlaySource],
    imported_sources: &mut BTreeMap<(usize, ObjectRef), ObjectRef>,
    source_documents: &mut [&mut Pdf<RS>],
) -> Result<()> {
    // qpdf orders sources underlays-then-overlays for BOTH naming and drawing.
    // Build the two typed Vecs in a single pass over `sources` in encounter
    // order — each kind is appended independently, so relative order within a
    // kind is preserved. The paint order (underlays first, then overlays) is
    // enforced below when we consume `underlays` before `overlays` while
    // building the /Fx1.. names and the new content stream.
    //
    type PlacementEntry = (usize, ObjectRef);
    let mut underlays: Vec<PlacementEntry> = Vec::new();
    let mut overlays: Vec<PlacementEntry> = Vec::new();
    for src in sources {
        let entry = src.source_page;
        match src.kind {
            OverlayKind::Underlay => underlays.push(entry),
            OverlayKind::Overlay => overlays.push(entry),
        }
    }

    // Destination placement rectangles, read before /Fx0 conversion mutates the
    // page dict (it does not touch the boxes, but reading first keeps the box
    // accessors operating on the original /Type /Page dictionary).
    let media_box = page_box_or_err(dest, dest_page_ref, BoxKind::Media)?;
    let trim_box = page_box_or_err(dest, dest_page_ref, BoxKind::Trim)?;

    // The destination page's inverse transform, folded into every placement
    // (qpdf's placeFormXObject is called with invert_transformations=true for both
    // /Fx0 and the sources). Width/height come from the dest /TrimBox, matching
    // qpdf's getMatrixForTransformations(true). Identity when the dest page has no
    // /Rotate or /UserUnit, so a non-rotated page is unaffected.
    // Placement computes the destination inverse transform through the
    // canonical PageObjectHelper route below, after the destination page has
    // been wrapped as /Fx0.

    // 1. Convert the destination page itself to Form XObject /Fx0.
    let fx0_ref = get_form_xobject_for_page(dest, dest_page_ref)?;

    // 2. Name the sources /Fx1.. in underlays-then-overlays order and build the
    //    new page /Resources /XObject mapping. /Fx0 is the page; the unique-name
    //    counter continues from there (getUniqueResourceName).
    let mut xobject_entries: Vec<(Vec<u8>, ObjectHandle)> =
        Vec::with_capacity(1 + underlays.len() + overlays.len());
    xobject_entries.push((b"/Fx0".to_vec(), dest.get_object_handle(fx0_ref)));
    let mut next_index = 1u32;

    // 3. Build the new page /Contents in draw order: underlays -> /Fx0 ->
    //    overlays. Underlays/overlays place into the page /TrimBox with
    //    allow_shrink=true; /Fx0 places into the page /MediaBox with
    //    allow_shrink=false (qpdf's doUnderOverlayForPage flag split). Every
    //    placement folds in the dest inverse transform `tmatrix`. Immediately
    //    after each source placement returns `cm`, copy the source page's
    //    annotations through the canonical PageObjectHelper foreign route.
    // Placement rects mirror qpdf's getTrimBox()/getMediaBox().getArrayAsRectangle()
    // in doUnderOverlayForPage: corners normalized before scaling/centring.
    let trim_rect = normalize_rectangle(trim_box);
    let media_rect = normalize_rectangle(media_box);
    let mut content = String::new();
    for source_page in &underlays {
        let xref = resolve_overlay_xobject(dest, *source_page, imported_sources, source_documents)?;
        let name = format!("Fx{next_index}");
        xobject_entries.push((name.as_bytes().to_vec(), dest.get_object_handle(xref)));
        // cov:ignore-start: the trailing `)?;` is the defensive error edge of
        // a multiline placement call; valid source and destination pages are
        // covered by the byte-identical overlay gates.
        let (fragment, cm) = place_form_xobject_canonical(
            dest,
            dest_page_ref,
            xref,
            trim_rect,
            true,
            true,
            false,
            &name,
        )?;
        // cov:ignore-end
        content.push_str(&fragment);
        // cov:ignore-start: source-document/page identity is validated while
        // planning OverlaySpec; the successful annotation facade continuation
        // is exercised by the end-to-end qpdf overlay matrix.
        {
            let (source_index, source_page_ref) = *source_page;
            let source = source_documents.get_mut(source_index).ok_or_else(|| {
                Error::Unsupported(format!(
                    "overlay source document index {} is out of range",
                    source_index
                ))
            })?;
            let source_page = source.get_object_handle(source_page_ref);
            let mut destination_page = PageObjectHelper::new(dest_page_ref, dest);
            destination_page.copy_annotations_from(source_page, cm, source)?;
        }
        // cov:ignore-end
        next_index += 1;
    }
    {
        // cov:ignore-start: the trailing `)?;` is the defensive error edge of
        // a multiline placement call; valid source and destination pages are
        // covered by the byte-identical overlay gates.
        let (fragment, _cm) = place_form_xobject_canonical(
            dest,
            dest_page_ref,
            fx0_ref,
            media_rect,
            true,
            false,
            false,
            "Fx0",
        )?;
        // cov:ignore-end
        content.push_str(&fragment);
    }
    for source_page in &overlays {
        let xref = resolve_overlay_xobject(dest, *source_page, imported_sources, source_documents)?;
        let name = format!("Fx{next_index}");
        xobject_entries.push((name.as_bytes().to_vec(), dest.get_object_handle(xref)));
        // cov:ignore-start: symmetric defensive error edge for the multiline
        // placement call; byte gates cover successful overlay placements.
        let (fragment, cm) = place_form_xobject_canonical(
            dest,
            dest_page_ref,
            xref,
            trim_rect,
            true,
            true,
            false,
            &name,
        )?;
        // cov:ignore-end
        content.push_str(&fragment);
        // cov:ignore-start: source-document/page identity is validated while
        // planning OverlaySpec; the successful annotation facade continuation
        // is exercised by the end-to-end qpdf overlay matrix.
        {
            let (source_index, source_page_ref) = *source_page;
            let source = source_documents.get_mut(source_index).ok_or_else(|| {
                Error::Unsupported(format!(
                    "overlay source document index {} is out of range",
                    source_index
                ))
            })?;
            let source_page = source.get_object_handle(source_page_ref);
            let mut destination_page = PageObjectHelper::new(dest_page_ref, dest);
            destination_page.copy_annotations_from(source_page, cm, source)?;
        }
        // cov:ignore-end
        next_index += 1;
    }

    // 4. Allocate the new /Contents stream (uncompressed, no /Filter; the writer
    //    compresses on output).
    let contents_stream = dest.new_stream_with_data(Rc::new(content.into_bytes()))?;

    // 5. Rewrite only /Resources and /Contents on the live page handle. qpdf's
    // copyAnnotations has already appended to this same page's /Annots value;
    // retaining the page handle means that annotation state survives without a
    // raw page-dictionary snapshot or a second resolution route.
    let overlay_page = overlay_page_handle(dest, dest_page_ref)?;
    let resources = ObjectHandle::dictionary(vec![(
        b"/XObject".to_vec(),
        ObjectHandle::dictionary(xobject_entries),
    )]);
    overlay_page.replace_key(b"/Resources", resources)?;
    overlay_page.replace_key(b"/Contents", contents_stream)?;

    Ok(())
}

/// Pair selected destination pages with source pages, mirroring qpdf's
/// `QPDFJob::handleUnderOverlay` page-mapping loop (qpdf 11.9.0).
///
/// `from_pages`, `to_pages`, and `repeat_pages` are 1-based page numbers already
/// resolved from the `--from`, `--to`, and `--repeat` page ranges. The `i`-th
/// selected destination page (`to_pages[i]`) is paired with:
///
/// - `from_pages[i]` while `i < from_pages.len()`;
/// - otherwise, when `repeat_pages` is non-empty,
///   `repeat_pages[(i - from_pages.len()) % repeat_pages.len()]` (the repeat
///   pages cycle);
/// - otherwise that destination page is skipped (it receives no overlay).
///
/// The result is a `Vec<(dest_page, source_page)>` in `to_pages` order, omitting
/// the skipped destination pages.
fn map_overlay_pages(
    from_pages: &[u32],
    to_pages: &[u32],
    repeat_pages: &[u32],
) -> Vec<(u32, u32)> {
    let mut pairs = Vec::new();
    for (i, &dest) in to_pages.iter().enumerate() {
        let source = if i < from_pages.len() {
            from_pages[i]
        } else if !repeat_pages.is_empty() {
            repeat_pages[(i - from_pages.len()) % repeat_pages.len()]
        } else {
            // Source pages exhausted and no --repeat: this dest page gets nothing.
            continue;
        };
        pairs.push((dest, source));
    }
    pairs
}

/// Map a single overlay/underlay spec to its per-destination-page sources
/// **without applying them**, mirroring qpdf's `QPDFJob::handleUnderOverlay` source
/// preparation for one `--overlay`/`--underlay` group (qpdf 11.9.0).
///
/// `from`, `to`, and `repeat` are the spec's page ranges. `from` (default all
/// source pages) selects source pages; `to` (default all destination pages)
/// selects destination pages; `repeat` is `None` by default (no repetition) and,
/// when `Some`, selects source pages to cycle once `from` is exhausted. The
/// selected pages are paired by [`map_overlay_pages`].
///
/// The result is a `Vec<(dest_page, OverlaySource)>` in `to` order: each entry
/// pairs a 1-based destination page number with an [`OverlaySource`] carrying
/// the source page identity. Form XObjects are intentionally imported later,
/// on the first destination-page use, matching qpdf's `fo` cache and allocation
/// order. No destination page is rewritten here; the caller aggregates these
/// across specs and applies them.
///
/// # Errors
///
/// - [`Error::Unsupported`] when a resolved page number falls outside `dest` or
///   `source` (the page lists and counts are read once up front, so this only
///   triggers on an internally inconsistent mapping), or any error propagated
///   from [`PageRange::resolve`] or the source page walk.
#[allow(
    clippy::too_many_arguments,
    reason = "mirrors qpdf's per-spec page mapping inputs and retains source identity"
)]
fn spec_page_sources<RS>(
    source: &mut Pdf<RS>,
    kind: OverlayKind,
    from: &PageRange,
    to: &PageRange,
    repeat: Option<&PageRange>,
    n_dest: u32,
    source_document_index: usize,
) -> Result<Vec<(u32, OverlaySource)>>
where
    RS: Read + Seek,
{
    // Snapshot the source page list before mapping. The applied patches change
    // page dictionaries in place but never reorder or remove page objects, so
    // the 1-based page numbers stay valid when the later lazy import runs.
    let source_pages = PageDocumentHelper::new(source).get_all_pages()?;
    let n_source = u32_len(source_pages.len());
    let pairs = resolve_spec_pairs(n_source, from, to, repeat, n_dest)?;

    pairs
        .iter()
        .map(|&(dest_page, source_page)| {
            Ok((
                dest_page,
                OverlaySource {
                    kind,
                    source_page: (
                        source_document_index,
                        page_ref_for(&source_pages, source_page, "source")?,
                    ),
                },
            ))
        })
        .collect()
}

/// Resolve a single overlay/underlay spec's `--from`/`--to`/`--repeat` ranges
/// into `(dest_page, source_page)` pairs, without touching either document.
///
/// This is the range-math half of [`spec_page_sources`]: it resolves the three
/// ranges against the caller-supplied page counts and calls
/// [`map_overlay_pages`] to produce the pairing. No pages are imported and no
/// destination pages are modified; the caller decides what to do with the
/// pairs (import + apply, or report). `n_source` and `n_dest` are the source
/// and destination page counts, computed once by the caller.
///
/// # Errors
///
/// Any error propagated from [`PageRange::resolve`].
pub(crate) fn resolve_spec_pairs(
    n_source: u32,
    from: &PageRange,
    to: &PageRange,
    repeat: Option<&PageRange>,
    n_dest: u32,
) -> Result<Vec<(u32, u32)>> {
    let from_pages = from.resolve(n_source)?;
    let to_pages = to.resolve(n_dest)?;
    let repeat_pages = match repeat {
        Some(pr) => pr.resolve(n_source)?,
        None => Vec::new(),
    };

    Ok(map_overlay_pages(&from_pages, &to_pages, &repeat_pages))
}

/// Apply a single overlay/underlay spec to `dest`, mirroring qpdf's
/// `QPDFJob::handleUnderOverlay` for one `--overlay`/`--underlay` group (qpdf 11.9.0).
///
/// A single overlay/underlay specification: a source document, its kind, and its
/// `--from`/`--to`/`--repeat` page ranges, as one `--overlay`/`--underlay` group
/// on the qpdf command line.
///
/// [`handle_under_overlay`] imports source pages via
/// [`Pdf::copy_foreign_object`], which can leave a copied Form XObject's
/// stream data unread until `dest` is written. Keep every `source` here
/// alive at least until `dest` has been fully written (see
/// [`Pdf::copy_foreign_object`]'s own documented requirement).
pub struct OverlaySpec<RS: Read + Seek + 'static> {
    /// The source document supplying the overlay/underlay pages.
    pub source: Pdf<RS>,
    /// Whether the source is drawn beneath or above the destination content.
    pub kind: OverlayKind,
    /// `--from`: which source pages are used (default all source pages).
    pub from: PageRange,
    /// `--to`: which destination pages receive the source (default all).
    pub to: PageRange,
    /// `--repeat`: source pages cycled once `from` is exhausted (default none).
    pub repeat: Option<PageRange>,
}

/// Group per-spec `(dest_page, source)` entries by destination page, preserving
/// each entry's encounter order within its page.
///
/// `entries` must already be in the order the sources should be drawn/named on a
/// page: across specs in declaration order, and within a spec in `--to` order.
/// The returned [`BTreeMap`] iterates destination pages in ascending page order
/// and, within a page, preserves that encounter order (so the canonical
/// placement helper's kind grouping yields underlays-then-overlays with each
/// kind in declaration order).
fn group_sources_by_dest_page(
    entries: &[(u32, OverlaySource)],
) -> BTreeMap<u32, Vec<OverlaySource>> {
    let mut by_page: BTreeMap<u32, Vec<OverlaySource>> = BTreeMap::new();
    for (dest_page, source) in entries {
        by_page.entry(*dest_page).or_default().push(source.clone());
    }
    by_page
}

/// Stable-partition `entries` into (underlays first, overlays second),
/// preserving each source's original relative order within its kind.
///
/// qpdf orders overlay/underlay sources this way for both painting and
/// `--verbose` progress reporting.
/// Sharing one implementation here prevents drift between painting and
/// progress reporting.
pub(crate) fn kind_stable_partition<T, F>(entries: Vec<T>, kind_of: F) -> Vec<T>
where
    F: Fn(&T) -> OverlayKind,
{
    let (underlays, overlays): (Vec<T>, Vec<T>) = entries
        .into_iter()
        .partition(|e| matches!(kind_of(e), OverlayKind::Underlay));
    let mut out = underlays;
    out.extend(overlays);
    out
}

/// Apply already-grouped overlay/underlay sources to `dest`, calling the
/// canonical placement helper **exactly once** per destination page (so each
/// page is converted to `/Fx0` only once). Pages are processed in ascending page
/// order; the per-page source order from `by_page` is preserved.
///
/// # Errors
///
/// Propagates any error from [`PageDocumentHelper::get_all_pages`], [`page_ref_for`], the placement
/// facade, or the source document handles.
fn apply_aggregated_sources<R: Read + Seek, RS: Read + Seek>(
    dest: &mut Pdf<R>,
    by_page: BTreeMap<u32, Vec<OverlaySource>>,
    source_documents: &mut [&mut Pdf<RS>],
) -> Result<()> {
    // Snapshot the repaired dest page refs once; the patches mutate page dicts
    // in place but never reorder or remove page objects, so 1-based numbers
    // stay valid. qpdf prepares all destination pages before it reads any
    // placement boxes or converts the page to a Form XObject.
    let dest_pages = PageDocumentHelper::new(dest).get_all_pages()?;
    let mut imported_sources = BTreeMap::new();
    for (dest_page, sources) in by_page {
        let dest_ref = page_ref_for(&dest_pages, dest_page, "destination")?;
        // cov:ignore-start: the delegated page application is exercised by the
        // overlay byte/QDF matrix; llvm-cov attributes its success continuation
        // to an argument line in this multiline call.
        under_overlay_for_page(
            dest,
            dest_ref,
            &sources,
            &mut imported_sources,
            source_documents,
        )?; // cov:ignore: llvm-cov attributes this successful delegated page call continuation separately
            // cov:ignore-end
    }
    Ok(())
}

/// Compose multiple overlay/underlay specs onto `dest`, mirroring qpdf's
/// `QPDFJob::handleUnderOverlay` handling of several `--overlay`/`--underlay` groups
/// (qpdf 11.9.0).
///
/// Each [`OverlaySpec`] is mapped independently against `dest`: its `from`/`to`/
/// `repeat` ranges select the source-to-destination page pairing, and each spec's
/// source pages are imported into `dest` once per source document through the
/// qpdf-shaped foreign copier (a source page used on several destination pages
/// is imported once and shared). The per-destination-page sources from all specs are
/// then aggregated **in declaration order** and each affected destination page is
/// rewritten exactly once: the page itself becomes Form XObject `/Fx0`, and the
/// sources are named `/Fx1…/FxN` and drawn in qpdf order — underlays (across
/// specs, declaration order), then `/Fx0` (the page), then overlays (across specs,
/// declaration order).
///
/// Destination pages not selected by any spec are left untouched. The specs'
/// source documents are taken by `&mut` because importing reads (and may seek)
/// them.
///
/// Imported Form XObjects are copied via [`Pdf::copy_foreign_object`] and may
/// still depend on their `source` document at write time (see that method's
/// doc). Keep every `spec.source` in `specs` alive until `dest` has been
/// fully written, not just until this function returns.
///
/// # Errors
///
/// - [`Error::Unsupported`] when a page number resolves outside its document, a
///   page lacks a usable placement box, or the object-number space is exhausted.
/// - Any error propagated from page-range resolution, the cross-document copy, or
///   canonical ObjectHandle resolution.
pub fn handle_under_overlay<RS, RT>(dest: &mut Pdf<RT>, specs: &mut [OverlaySpec<RS>]) -> Result<()>
where
    RS: Read + Seek,
    RT: Read + Seek,
{
    // qpdf returns before touching the destination page tree at all when there
    // is nothing to overlay or underlay (QPDFJob.cc:1939-1941,
    // `if (m->underlay.empty() && m->overlay.empty()) { return; }`). Match that:
    // an empty `specs` slice must not trigger the repair pass below.
    if specs.is_empty() {
        return Ok(());
    }

    // Map every spec first, collecting its per-dest-page sources in declaration
    // order. Each spec gets its own source-document foreign copier (separate
    // documents => separate qpdf identity maps).
    // The dest page count is invariant while specs are mapped (sources are
    // applied only after the loop), so query the page tree once up front
    // instead of re-walking it per spec.
    // qpdf's overlay job obtains the repaired destination page list before
    // resolving any source ranges or performing placement.
    let n_dest = u32_len(PageDocumentHelper::new(dest).get_all_pages()?.len());
    // qpdf still validates/opens the configured source documents, but its
    // page loop has no work when the destination has no pages
    // (`QPDFJob.cc:1970-1978`). Do not feed the zero count into the ordinary
    // page-range parser: that parser correctly rejects zero-page bounds for
    // page-selection callers, while underlay/overlay is a no-op here.
    if n_dest == 0 {
        return Ok(());
    }
    let mut entries: Vec<(u32, OverlaySource)> = Vec::new();
    for (spec_index, spec) in specs.iter_mut().enumerate() {
        let sources = spec_page_sources(
            &mut spec.source,
            spec.kind,
            &spec.from,
            &spec.to,
            spec.repeat.as_ref(),
            n_dest,
            spec_index,
        )?;
        entries.extend(sources);
    }
    let mut source_documents: Vec<&mut Pdf<RS>> =
        specs.iter_mut().map(|spec| &mut spec.source).collect();
    apply_aggregated_sources(
        dest,
        group_sources_by_dest_page(&entries),
        &mut source_documents,
    )
}

/// A single overlay/underlay source contributing to one destination page, as
/// reported by [`overlay_verbose_report`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OverlayVerboseSource {
    /// Zero-based index of the source's spec in the `specs` slice passed to
    /// [`overlay_verbose_report`].
    pub spec_index: usize,
    /// Whether the source is drawn beneath or above the destination content.
    pub kind: OverlayKind,
    /// One-based source page number contributing to this destination page.
    pub src_page: u32,
}

/// One destination page's overlay/underlay plan, as reported by
/// [`overlay_verbose_report`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OverlayVerbosePage {
    /// One-based destination page number.
    pub dest_page: u32,
    /// Sources drawn on this page, ordered underlays-first (declaration order
    /// across specs) then overlays. Empty when no spec targets this page.
    pub sources: Vec<OverlayVerboseSource>,
}

/// Return the per-destination-page overlay/underlay plan without importing any
/// source page or drawing on the destination.
///
/// The returned vector covers every destination page in ascending order
/// (`1..=n_dest`). Per-page sources are ordered underlays first (in declaration
/// order across `specs`), then overlays (also in declaration order), matching
/// the order [`handle_under_overlay`] uses to paint the same page. Destination
/// pages that no spec targets appear in the result with an empty `sources`.
///
/// The source documents are taken by `&mut` because [`PageRange::resolve`]
/// reads their page trees; the destination is taken by `&mut` for the same
/// reason, and because [`PageDocumentHelper::get_all_pages`] repairs any page
/// lacking an effective `/MediaBox` in place, matching qpdf's own
/// `QPDFPageDocumentHelper::getAllPages` (qpdf 11.9.0). No source page is
/// imported and no destination content stream is drawn on. Calling this before
/// [`handle_under_overlay`] on the same specs yields the paint plan that will be
/// applied.
///
/// # Errors
///
/// - [`Error::Parse`] when a `--from`/`--to`/`--repeat` range references a
///   page number outside its document (propagated from
///   [`PageRange::resolve`]).
/// - Any error propagated from [`PageDocumentHelper::get_all_pages`]
///   — typically [`Error::Missing`] for a missing `/Root`/`/Pages`, or
///   [`Error::Unsupported`] for a malformed page tree.
pub fn overlay_verbose_report<RS, RT>(
    dest: &mut Pdf<RT>,
    specs: &mut [OverlaySpec<RS>],
) -> Result<Vec<OverlayVerbosePage>>
where
    RS: Read + Seek,
    RT: Read + Seek,
{
    let n_dest = u32_len(PageDocumentHelper::new(dest).get_all_pages()?.len());
    // Flatten every spec's (dest_page, source) pairs in declaration order.
    let mut flat: Vec<(u32, OverlayVerboseSource)> = Vec::new();
    for (spec_index, spec) in specs.iter_mut().enumerate() {
        let n_source = u32_len(
            PageDocumentHelper::new(&mut spec.source)
                .get_all_pages()?
                .len(),
        );
        let pairs =
            resolve_spec_pairs(n_source, &spec.from, &spec.to, spec.repeat.as_ref(), n_dest)?;
        for (dest_page, src_page) in pairs {
            flat.push((
                dest_page,
                OverlayVerboseSource {
                    spec_index,
                    kind: spec.kind,
                    src_page,
                },
            ));
        }
    }
    // Group by destination page (ascending order via BTreeMap).
    let mut by_page: BTreeMap<u32, Vec<OverlayVerboseSource>> = BTreeMap::new();
    for (dest_page, src) in flat {
        by_page.entry(dest_page).or_default().push(src);
    }
    // Emit one entry per dest page in 1..=n_dest, with underlays-then-overlays
    // per page (shared with the paint path via kind_stable_partition).
    let mut out = Vec::with_capacity(n_dest as usize);
    for dest_page in 1..=n_dest {
        let sources = by_page.remove(&dest_page).unwrap_or_default();
        let sources = kind_stable_partition(sources, |s| s.kind);
        out.push(OverlayVerbosePage { dest_page, sources });
    }
    Ok(out)
}

/// Convert a page-list length to `u32`, the width [`PageRange::resolve`] expects.
///
/// A document with more than `u32::MAX` pages is not representable; clamp to
/// `u32::MAX` so a pathological count cannot wrap (qpdf's page index is `int`,
/// far below this bound, so real documents never reach the clamp).
fn u32_len(len: usize) -> u32 {
    u32::try_from(len).unwrap_or(u32::MAX)
}

/// Look up the [`ObjectRef`] of a 1-based `page` number in `pages`, erroring when
/// it is out of range. `which` names the document (`"source"`/`"destination"`)
/// for the error message.
fn page_ref_for(pages: &[ObjectRef], page: u32, which: &str) -> Result<ObjectRef> {
    let idx = (page as usize)
        .checked_sub(1)
        .filter(|&i| i < pages.len())
        .ok_or_else(|| {
            Error::Unsupported(format!(
                "{which} page {page} is out of range (document has {} page(s))",
                pages.len()
            ))
        })?;
    Ok(pages[idx])
}

/// Which destination page box a placement rectangle comes from.
#[derive(Clone, Copy)]
enum BoxKind {
    Media,
    Trim,
}

/// Read the destination page's effective `/MediaBox` or `/TrimBox` (inheritance
/// and fallback resolved by [`PageObjectHelper`]). A present but malformed box
/// maps to qpdf's zero rectangle from `getArrayAsRectangle`; only an absent
/// effective box is an error.
fn page_box_or_err<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    page_ref: ObjectRef,
    kind: BoxKind,
) -> Result<PageBox> {
    let mut helper = PageObjectHelper::new(page_ref, pdf);
    let value = match kind {
        BoxKind::Media => helper.get_media_box(false)?,
        BoxKind::Trim => helper.get_trim_box(false, false)?,
    };
    // Resolving accessor (matches the sibling `try_is_null()` calls inside
    // `get_crop_box`/`get_bleed_box`/`get_trim_box` in page_object_helper.rs
    // for the same `get_attribute` return value): the non-resolving
    // `is_null()` would answer `false` for an unresolved indirect handle
    // even when it resolves to null (`ObjectHandle::is_null` doc). Both
    // `false, false` call sites above already force resolution before
    // returning here -- `get_attribute`'s `result.try_is_null()?` is always
    // evaluated regardless of outcome, and `apply_fallback` short-circuits
    // to `Ok(fallback)` unchanged when `copy_if_fallback` is false -- so
    // this has no observable effect today; it keeps the accessor contract
    // consistent so a future caller with different arguments stays correct.
    if value.try_is_null()? {
        return Err(Error::Unsupported(format!(
            "destination page {page_ref} has no usable placement box"
        )));
    }
    // qpdf's getArrayAsRectangle returns the zero rectangle for a present but
    // malformed value; the destination Form-XObject conversion owns the
    // warning that makes the overlay operation observable as repaired.
    let rectangle = rectangle_from_handle(&value)?.unwrap_or_default();
    Ok(PageBox::new(
        rectangle.llx,
        rectangle.lly,
        rectangle.urx,
        rectangle.ury,
    ))
}

/// Build a placement fragment through the canonical page/Form handle route.
///
/// This is the consumer-side counterpart of
/// [`PageObjectHelper::get_matrix_for_form_xobject_placement`].  Keeping the
/// content fragment here preserves overlay's naming and annotation ordering,
/// while all page-tree inheritance, Form `/BBox`/`/Matrix` resolution, and
/// transformation handling live in the qpdf-shaped helper API.
#[allow(
    clippy::too_many_arguments,
    reason = "mirrors qpdf placement inputs while retaining overlay naming and ordering"
)]
fn place_form_xobject_canonical<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    dest_page_ref: ObjectRef,
    form_ref: ObjectRef,
    rect: Rectangle,
    invert_transformations: bool,
    allow_shrink: bool,
    allow_expand: bool,
    name: &str,
) -> Result<(String, Matrix)> {
    let form = pdf.get_object_handle(form_ref);
    let mut helper = PageObjectHelper::new(dest_page_ref, pdf);
    let resource_name = format!("/{name}");
    helper.place_form_xobject(
        form,
        &resource_name,
        rect,
        invert_transformations,
        allow_shrink,
        allow_expand,
    )
}

/// Normalize a rectangle's corners the way qpdf's
/// `QPDFObjectHandle::getArrayAsRectangle` does: `llx = min(x0, x2)`,
/// `lly = min(x1, x3)`, `urx = max(x0, x2)`, `ury = max(x1, x3)`. qpdf reads all
/// box geometry for placement through this accessor, so a page with a reversed box
/// (`llx > urx` or `lly > ury`) still yields a non-negative width/height and places
/// identically to its ordered form.
fn normalize_rectangle(rectangle: PageBox) -> Rectangle {
    Rectangle::new(
        rectangle.llx.min(rectangle.urx),
        rectangle.lly.min(rectangle.ury),
        rectangle.llx.max(rectangle.urx),
        rectangle.lly.max(rectangle.ury),
    )
}

/// Resolve the destination page through the canonical handle registry and
/// validate its dictionary shape before mutating it.
fn overlay_page_handle<R: Read + Seek>(
    pdf: &mut Pdf<R>,
    page_ref: ObjectRef,
) -> Result<ObjectHandle> {
    let page = pdf.get_object_handle(page_ref);
    page.try_dereference()?;
    if !page.try_is_dictionary()? {
        return Err(Error::Unsupported(format!(
            "page {page_ref} is not a dictionary"
        )));
    }
    Ok(page)
}

// Feature-gated byte-identity gate: a single overlay applied to a destination
// page, written through the `--static-id` full-rewrite path, must be
// byte-identical to qpdf 11.9.0's overlay output. Gated on `qpdf-zlib-compat`
// because byte-identity requires flpdf's deflate output to match qpdf's classic
// libz output (see CLAUDE.md DEFLATE carve-out). It lives inside the crate, not
// in `tests/`, because the overlay entry points are `pub(crate)`.
//
// Overlay/underlay byte-identity matrix. Each row is a
// `qpdf 11.9.0 --static-id` invocation reproduced byte-for-byte at the library
// layer; the golden recipes live in tests/golden/regenerate.sh. Goldens under
// tests/golden/references/overlay/.
//
//   case                | kind     | dest          | source        | --from | --to  | --repeat
//   --------------------|----------|---------------|---------------|--------|-------|---------
//   one-page (.16.3)    | overlay  | three-page    | one-page      | -      | -     | -
//   two-page default    | overlay  | three-page    | two-page      | -      | -     | -
//   one-page repeat1    | overlay  | three-page    | one-page      | -      | -     | 1
//   two-page to=2-3     | overlay  | three-page    | two-page      | -      | 2-3   | -
//   two overlays (.16.5)| overlay×2| three-page    | one + two     | -      | -     | -
//   overlay+underlay    | over+und | three-page    | one + two     | -      | -     | -
//   two-page from=2     | overlay  | three-page    | two-page      | 2      | -     | -
//   two-page from= rpt2 | overlay  | three-page    | two-page      | (empty)| -     | 2
//   underlay two-page   | underlay | three-page    | two-page      | -      | -     | -
//   rotated source mtx  | overlay  | three-page    | one-page-r90  | -      | -     | -
//   one-page to=1-3 rpt1| overlay  | three-page    | one-page      | -      | 1-3   | 1
//   multi-stream (.16.10)| overlay | three-page    | multi-stream  | -      | -     | -
//   rotated dest (.16.10)| overlay | one-page-r90  | one-page      | -      | -     | -
//   userunit (.16.10)   | overlay  | three-page    | userunit      | -      | -     | -
//   swapped box (lkk7)  | overlay  | swapped-box   | one-page      | -      | -     | -
//   swapped+r90 (lkk7)  | overlay  | swapped-r90   | swapped-r90   | -      | -     | -
//
// The reversed-box rows cover page boxes (llx>urx AND lly>ury): qpdf reads
// all placement geometry through getArrayAsRectangle (min/max normalized). The
// swapped-box row proves the placement-rect normalization (a raw rect would reflect
// the source cm). The swapped+r90 row (overlaid onto itself) additionally proves the
// source/dest Form /Matrix dims normalize -- the /Matrix array is serialized into
// the output, so a raw width flips its sign. (The dest tmatrix dims are ALSO
// normalized in code, but that is an output no-op here: their only effect is the
// tmatrix translation, which the placement centring absorbs -- see
// apply_overlays_to_page. So no gate isolates it.) Both fixtures are pinned to 1.3.
//
// The rotated-source row is the matrix-transformed placement check: the source
// page carries /Rotate 90, so its imported Form XObject gets a non-identity
// /Matrix. The extended rows widen the gate to the four byte-parity gaps
// the narrow fixtures had masked: multi-stream exercises the conditional /Matrix
// omission (no /Rotate) and qpdf's newline content coalescing; rotated dest
// exercises the destination inverse transform folded into every placement cm;
// userunit exercises the /UserUnit scale folded into the Form /Matrix. The
// .16.10 source fixtures are pinned to PDF 1.3 (== the three-page dest) so the
// orthogonal source version-floor limitation does not perturb the bytes.
//
// Source version-floor + Adobe extension_level propagation (pure header
// bump AND AES-256 /Extensions/ADBE injection) is covered by
// `overlay_bumps_header_from_non_encrypted_higher_version_source` and
// `overlay_bumps_header_and_injects_adbe_from_encrypted_source` in
// `crates/flpdf-cli/tests/cli_overlay.rs`.
//
// CLI-level overlay byte-identity coverage lives in
// `crates/flpdf-cli/tests/cli_byte_identical_overlay.rs` (gated on
// `qpdf-zlib-compat`, same policy as the linearize `cli_byte_identical`
// gate). Those tests run the actual `flpdf` binary with `--static-id`
// [`--qdf --no-original-object-ids`] against a subset of the overlay
// goldens used here (the version-floor / encrypted-source / annotation-
// copy families remain library-only for now), catching CLI-layer wiring
// divergences (argv parsing, PdfWriter setting assembly, defaults) that
// library-only gates cannot see.

// Feature-gated byte-identity gate for overlay copy-annotations parity.
//
// A single overlay applied to a destination page, written through the
// `--static-id --qdf --no-original-object-ids` full-rewrite path, must be
// byte-identical to qpdf 11.9.0's output. Gated on `qpdf-zlib-compat` because
// byte-identity requires flpdf's deflate output to match qpdf's classic libz
// output (see CLAUDE.md's DEFLATE carve-out). It lives inside the crate, not in
// `tests/`, because `handle_under_overlay` reaches page internals that the
// integration-test crate cannot.
//
// The overlay/underlay placement families (rotation, /UserUnit, swapped boxes,
// multi-stream sources) are covered end to end by
// `crates/flpdf-cli/tests/cli_byte_identical_overlay.rs`. The copy-annotations
// family below has no CLI counterpart: `--overlay` with form fields exercises
// `addAndRenameFormFields` (`QPDFAcroFormDocumentHelper.cc:105-108`) and
// `copyAnnotations` (`QPDFPageObjectHelper.cc:1030`), whose per-placement
// qualified-name cache behaviour only shows up in the written bytes.
//
// Goldens live in `tests/golden/references/overlay/`; the recipes that produced
// them are in `tests/golden/regenerate.sh`.
#[cfg(all(test, feature = "qpdf-zlib-compat"))]
mod byte_gate {
    use super::{handle_under_overlay, OverlayKind, OverlaySpec};
    use crate::pages::page_refs;
    use crate::PageRange;
    use crate::{ObjectHandle, Pdf, PdfWriter};
    use std::io::{Read, Seek};
    use std::path::Path;

    fn fixture(name: &str) -> Pdf<std::io::BufReader<std::fs::File>> {
        let path = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("../../tests/fixtures/compat")
            .join(name);
        let file = std::fs::File::open(&path).unwrap_or_else(|e| panic!("open {path:?}: {e}"));
        Pdf::open(std::io::BufReader::new(file)).unwrap()
    }

    fn write_qpdf<R, F>(dest: &mut Pdf<R>, configure: F) -> Vec<u8>
    where
        R: Read + Seek + 'static,
        F: FnOnce(&mut PdfWriter<'_, R>),
    {
        let mut writer = PdfWriter::new(dest);
        configure(&mut writer);
        writer.set_output_memory().unwrap();
        writer.write().unwrap();
        writer.get_buffer().unwrap()
    }

    /// Write `dest` through the `flpdf rewrite --static-id --qdf
    /// --no-original-object-ids` recipe. QDF applies qpdf's conditional
    /// `last_char != '\n'` framing rule so `endstream` stays line-anchored, so
    /// `newline_before_endstream` stays at its default (`Never`).
    fn write_qdf_nooid<R: Read + Seek + 'static>(dest: &mut Pdf<R>) -> Vec<u8> {
        write_qpdf(dest, |writer| {
            writer.set_static_id(true);
            writer.set_qdf_mode(true);
            writer.set_suppress_original_object_ids(true);
        })
    }

    fn golden(name: &str) -> Vec<u8> {
        let path = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("../../tests/golden/references/overlay")
            .join(name);
        std::fs::read(&path).unwrap_or_else(|e| panic!("read golden {path:?}: {e}"))
    }

    /// Parse a page-range string, panicking with context on error.
    fn pr(input: &str) -> PageRange {
        if input.is_empty() {
            PageRange::all()
        } else {
            PageRange::parse_numrange(input).unwrap_or_else(|e| panic!("parse {input:?}: {e}"))
        }
    }

    // cov:ignore-start: every line but the equal-inputs early return belongs to
    // the mismatch report, which only runs when a gate fails — a red build
    // rather than a covered line. llvm-cov attributes the `if a == b` guard to
    // the same region as the walk below it, so the whole function is excluded.
    fn first_diff(a: &[u8], b: &[u8]) -> Option<usize> {
        if a == b {
            return None;
        }
        let common = a.len().min(b.len());
        (0..common).find(|&i| a[i] != b[i]).or(Some(common))
    }
    // cov:ignore-end

    /// Assert `actual` is byte-identical to the golden named `golden_name`,
    /// reporting the first diff offset and surrounding bytes on mismatch.
    fn assert_byte_identical(actual: &[u8], golden_name: &str) {
        let expected = golden(golden_name);
        if let Some(off) = first_diff(actual, &expected) {
            // cov:ignore-start: the mismatch report only runs when a gate
            // fails, which is a red build rather than a covered line.
            let lo = off.saturating_sub(24);
            let g = expected.get(off).copied().unwrap_or(0);
            let f = actual.get(off).copied().unwrap_or(0);
            panic!(
                "overlay output not byte-identical to qpdf golden {golden_name} \
                 (flpdf={} bytes, golden={} bytes)\n\
                 first diff at offset {off} (golden=0x{g:02x} flpdf=0x{f:02x})\n\
                 golden[{lo}..]: {:?}\nflpdf [{lo}..]: {:?}",
                actual.len(),
                expected.len(),
                String::from_utf8_lossy(&expected[lo..(off + 24).min(expected.len())]),
                String::from_utf8_lossy(&actual[lo..(off + 24).min(actual.len())]),
            );
            // cov:ignore-end
        }
    }

    /// Return `(max_pdf_version, max_extension_level)` over two open PDFs using
    /// qpdf's pairwise rule: the higher version wins outright, and a higher
    /// version RESETS the extension level (only equal versions merge via `max`).
    /// Mirrors what `flpdf rewrite` accumulates across dest plus every source.
    fn accumulate_max<R1: Read + Seek, R2: Read + Seek>(
        a: &mut Pdf<R1>,
        b: &mut Pdf<R2>,
    ) -> crate::PdfVersion {
        let a_version =
            crate::parse_pdf_version(a.version()).unwrap_or(crate::PdfVersion::new(1, 0, 0));
        let b_version =
            crate::parse_pdf_version(b.version()).unwrap_or(crate::PdfVersion::new(1, 0, 0));
        let mut best = crate::PdfVersion::new(
            a_version.major(),
            a_version.minor(),
            a.adobe_extension_level().unwrap_or(None).unwrap_or(0),
        );
        best.update_if_greater(crate::PdfVersion::new(
            b_version.major(),
            b_version.minor(),
            b.adobe_extension_level().unwrap_or(None).unwrap_or(0),
        ));
        best
    }

    /// Return a page's `/Annots` entries as canonical handles, or `None` when
    /// the page has no annotation array.
    fn page_annots<R: Read + Seek>(
        pdf: &mut Pdf<R>,
        page_ref: crate::ObjectRef,
    ) -> Option<Vec<ObjectHandle>> {
        let page = pdf.get_object_handle(page_ref);
        page.try_dereference().unwrap();
        page.try_get_key(b"/Annots")
            .unwrap()
            .try_as_array()
            .unwrap()
    }
    #[test]
    fn overlay_copy_annotations_fxo_red_repeat1_is_byte_identical_qdf() {
        let mut dest = fixture("fxo-red.pdf");
        let mut src = fixture("form-fields-and-annotations.pdf");
        // qpdf floors the output at max(dest, all sources) — form-fields-and-
        // annotations.pdf is PDF 1.6, fxo-red.pdf is PDF 1.3, so the output
        // header must be 1.6.
        let (version, max_ext) = accumulate_max(&mut dest, &mut src).get_version();
        let mut specs = vec![OverlaySpec {
            source: src,
            kind: OverlayKind::Overlay,
            from: pr(""),
            to: pr(""),
            repeat: Some(pr("1")),
        }];
        handle_under_overlay(&mut dest, &mut specs).unwrap();
        let actual = write_qpdf(&mut dest, |writer| {
            writer.set_static_id(true);
            writer.set_qdf_mode(true);
            writer.set_suppress_original_object_ids(true);
            writer.set_minimum_pdf_version(version, max_ext);
        });
        assert_byte_identical(&actual, "overlay-copy-annotations.pdf");
    }

    /// Two `--overlay` specs from the same source, both targeting
    /// destination page 1 — the distinguishing shape between per-placement
    /// and per-page finalization of `addAndRenameFormFields`. The qpdf
    /// 11.9.0 real-CLI probe `qpdf fxo-red.pdf --overlay
    /// form-fields-and-annotations.pdf --to=1 -- --overlay
    /// form-fields-and-annotations.pdf --to=1 -- --qdf --static-id
    /// --no-original-object-ids out.pdf` renames the second placement's
    /// fields "Text Box 1+1"/"Text Box 2+1"/"r1+1": qpdf's `copyAnnotations`
    /// (`QPDFPageObjectHelper.cc:1030`) calls `addAndRenameFormFields` once
    /// per placement, and the trailing `addFormField` walk
    /// (`QPDFAcroFormDocumentHelper.cc:105-108`) updates the qualified-name
    /// cache before the second placement's BFS rename pass reads it. The
    /// sibling `..._fxo_red_repeat1_...` test above repeats one placement
    /// across 16 distinct destination pages and does not exercise this: each
    /// page gets its own fresh `AcroFormDocumentHelper::new(dest).analyze()`
    /// regardless of whether finalization is per-placement or per-page, so
    /// only two placements landing on the *same* page tell them apart.
    #[test]
    fn overlay_copy_annotations_two_specs_same_page_is_byte_identical_qdf() {
        let mut dest = fixture("fxo-red.pdf");
        let mut src1 = fixture("form-fields-and-annotations.pdf");
        let src2 = fixture("form-fields-and-annotations.pdf");
        let (version, max_ext) = accumulate_max(&mut dest, &mut src1).get_version();
        let mut specs = vec![
            OverlaySpec {
                source: src1,
                kind: OverlayKind::Overlay,
                from: pr(""),
                to: pr("1"),
                repeat: None,
            },
            OverlaySpec {
                source: src2,
                kind: OverlayKind::Overlay,
                from: pr(""),
                to: pr("1"),
                repeat: None,
            },
        ];
        handle_under_overlay(&mut dest, &mut specs).unwrap();
        let actual = write_qpdf(&mut dest, |writer| {
            writer.set_static_id(true);
            writer.set_qdf_mode(true);
            writer.set_suppress_original_object_ids(true);
            writer.set_minimum_pdf_version(version, max_ext);
        });
        assert_byte_identical(&actual, "overlay-copy-annotations-two-specs-same-page.pdf");
    }

    /// Overlay a source that mixes two edge shapes into its page's
    /// `/Annots` array:
    /// - one widget (obj 3, "Text Box 1") carries an explicit `/P`
    ///   pointing at the source page — after copy that ref goes stale
    ///   and gets Null'd by canonical foreign-object replacement, so the
    ///   `PageObjectHelper::copy_annotations_from` path must repoint it at
    ///   dest_page_ref;
    /// - one entry is a DIRECT annot dictionary (an inline
    ///   `<< /Subtype /FreeText ... >>` where an indirect ref would
    ///   normally live) — the canonical AcroForm transform path must preserve
    ///   it as a fresh source-doc indirect object (qpdf
    ///   transformAnnotations line 954-956).
    ///
    /// Fixture: `form-fields-and-annotations-p-and-inline.pdf` is the
    /// primary source with `/P 17 0 R` added to Text Box 1 and one
    /// FreeText annot inlined into the page's `/Annots`.
    #[test]
    fn overlay_copy_annotations_source_p_and_inline_is_byte_identical_qdf() {
        let mut dest = fixture("fxo-red.pdf");
        let mut src = fixture("form-fields-and-annotations-p-and-inline.pdf");
        let (version, max_ext) = accumulate_max(&mut dest, &mut src).get_version();
        let mut specs = vec![OverlaySpec {
            source: src,
            kind: OverlayKind::Overlay,
            from: pr(""),
            to: pr(""),
            repeat: Some(pr("1")),
        }];
        handle_under_overlay(&mut dest, &mut specs).unwrap();
        let actual = write_qpdf(&mut dest, |writer| {
            writer.set_static_id(true);
            writer.set_qdf_mode(true);
            writer.set_suppress_original_object_ids(true);
            writer.set_minimum_pdf_version(version, max_ext);
        });
        assert_byte_identical(&actual, "overlay-source-p-and-inline.pdf");
    }

    /// Overlay a source that has annotations (a `/Link` annot) but NO
    /// `/AcroForm` on the catalog — a valid, common shape (only widget
    /// annots require an /AcroForm; link, stamp, freetext, ... do not).
    /// Exercises the "no /AcroForm" branch of
    /// `read_source_acroform_defaults` (`source_dr`, `source_default_da`,
    /// `source_default_q` all return None) that the primary target does
    /// not hit because its source PDF carries an /AcroForm.
    #[test]
    fn overlay_copy_annotations_source_no_acroform_is_byte_identical_qdf() {
        let mut dest = fixture("fxo-red.pdf");
        let mut src = fixture("link-annot-no-acroform.pdf");
        let (version, max_ext) = accumulate_max(&mut dest, &mut src).get_version();
        let mut specs = vec![OverlaySpec {
            source: src,
            kind: OverlayKind::Overlay,
            from: pr(""),
            to: pr(""),
            repeat: Some(pr("1")),
        }];
        handle_under_overlay(&mut dest, &mut specs).unwrap();
        let actual = write_qpdf(&mut dest, |writer| {
            writer.set_static_id(true);
            writer.set_qdf_mode(true);
            writer.set_suppress_original_object_ids(true);
            writer.set_minimum_pdf_version(version, max_ext);
        });
        assert_byte_identical(&actual, "overlay-link-annot-no-acroform.pdf");
    }

    /// The destination already carries a `/Annots` array with a link
    /// annotation and has no `/AcroForm`. qpdf's overlay appends the imported
    /// Form XObject to the page contents without disturbing the existing
    /// annotations (`copyAnnotations` only runs for the source's own annots),
    /// so the destination array must come out unchanged.
    #[test]
    fn overlay_destination_existing_annotation_is_byte_identical_qdf() {
        let mut dest = fixture("link-annot-no-acroform.pdf");
        let source = fixture("one-page.pdf");
        let dest_page = page_refs(&mut dest).unwrap()[0];
        let before = page_annots(&mut dest, dest_page)
            .expect("destination fixture must have an annotation array");

        let mut specs = vec![OverlaySpec {
            source,
            kind: OverlayKind::Overlay,
            from: pr(""),
            to: pr("1"),
            repeat: None,
        }];
        handle_under_overlay(&mut dest, &mut specs).unwrap();

        let after = page_annots(&mut dest, dest_page)
            .expect("destination annotations must survive the overlay rewrite");
        assert_eq!(
            after.len(),
            before.len(),
            "overlay must preserve destination annotations"
        );
        for (a, b) in after.iter().zip(before.iter()) {
            assert!(
                a.is_same_object_as(b),
                "overlay must not rebind a destination annotation handle"
            );
        }

        let actual = write_qdf_nooid(&mut dest);
        assert_byte_identical(&actual, "overlay-destination-existing-annotation.pdf");
    }

    /// Overlay onto a dest whose `/AcroForm/Fields` is stored as an
    /// indirect reference (`/Fields 5 0 R`) instead of a direct array —
    /// a valid PDF shape. Exercises
    /// the canonical helper's indirect `/Fields` append (updates the array
    /// object in place rather than storing a new direct array on the
    /// AcroForm).
    ///
    /// Fixture: `fxo-red-indirect-fields.pdf` is fxo-red with a hand-added
    /// `/AcroForm { /Fields <ref> }` whose Fields ref points at a
    /// standalone array object containing one widget "Text Box 1"; the
    /// source's Text Box 1 must therefore rename to +N on every placement.
    #[test]
    fn overlay_copy_annotations_onto_indirect_fields_is_byte_identical_qdf() {
        let mut dest = fixture("fxo-red-indirect-fields.pdf");
        let mut src = fixture("form-fields-and-annotations.pdf");
        let (version, max_ext) = accumulate_max(&mut dest, &mut src).get_version();
        let mut specs = vec![OverlaySpec {
            source: src,
            kind: OverlayKind::Overlay,
            from: pr(""),
            to: pr(""),
            repeat: Some(pr("1")),
        }];
        handle_under_overlay(&mut dest, &mut specs).unwrap();
        let actual = write_qpdf(&mut dest, |writer| {
            writer.set_static_id(true);
            writer.set_qdf_mode(true);
            writer.set_suppress_original_object_ids(true);
            writer.set_minimum_pdf_version(version, max_ext);
        });
        assert_byte_identical(&actual, "overlay-onto-indirect-fields.pdf");
    }

    /// Overlay a source whose `/AcroForm/DR` is stored inline as a direct
    /// dictionary (rather than the usual indirect ref). Exercises
    /// `read_source_acroform_defaults`' direct-`/DR` materialize path
    /// (allocate a fresh source-doc indirect object, register the direct
    /// dict on it, and return that ref for downstream copy).
    #[test]
    fn overlay_copy_annotations_source_direct_dr_is_byte_identical_qdf() {
        let mut dest = fixture("fxo-red.pdf");
        let mut src = fixture("form-fields-and-annotations-direct-dr.pdf");
        let (version, max_ext) = accumulate_max(&mut dest, &mut src).get_version();
        let mut specs = vec![OverlaySpec {
            source: src,
            kind: OverlayKind::Overlay,
            from: pr(""),
            to: pr(""),
            repeat: Some(pr("1")),
        }];
        handle_under_overlay(&mut dest, &mut specs).unwrap();
        let actual = write_qpdf(&mut dest, |writer| {
            writer.set_static_id(true);
            writer.set_qdf_mode(true);
            writer.set_suppress_original_object_ids(true);
            writer.set_minimum_pdf_version(version, max_ext);
        });
        assert_byte_identical(&actual, "overlay-source-direct-dr.pdf");
    }

    /// Overlay `form-fields-and-annotations.pdf` onto a dest that already
    /// carries an `/AcroForm` with a pre-existing `/Fields` entry named
    /// "Text Box 1" — the same partial name as one of the source's
    /// top-level fields, so the +N collision rename must fire once for
    /// every placement (the source page is repeated onto all 16 dest
    /// pages, so the rename runs 16 times: "Text Box 1+1", "Text Box 1+2",
    /// ...). Also exercises `ensure_dest_acroform_dr`'s existing-`/DR`
    /// short-circuit, the canonical helper's reference-`/AcroForm` and
    /// reference-`/Fields` paths over the pre-existing field, and the tail of
    /// `duplicate_field_tree` that
    /// leaves an existing dest `/DR` untouched.
    ///
    /// Fixture: `fxo-red-with-existing-acroform.pdf` is fxo-red with a
    /// small hand-added `/AcroForm { /DR ... /Fields [<field>] }` whose
    /// field has `/T (Text Box 1)`.
    #[test]
    fn overlay_copy_annotations_onto_existing_acroform_is_byte_identical_qdf() {
        let mut dest = fixture("fxo-red-with-existing-acroform.pdf");
        let mut src = fixture("form-fields-and-annotations.pdf");
        let (version, max_ext) = accumulate_max(&mut dest, &mut src).get_version();
        let mut specs = vec![OverlaySpec {
            source: src,
            kind: OverlayKind::Overlay,
            from: pr(""),
            to: pr(""),
            repeat: Some(pr("1")),
        }];
        handle_under_overlay(&mut dest, &mut specs).unwrap();
        let actual = write_qpdf(&mut dest, |writer| {
            writer.set_static_id(true);
            writer.set_qdf_mode(true);
            writer.set_suppress_original_object_ids(true);
            writer.set_minimum_pdf_version(version, max_ext);
        });
        assert_byte_identical(&actual, "overlay-onto-existing-acroform.pdf");
    }

    /// Overlay onto a dest whose `/AcroForm/DR` is already populated with a
    /// `/Font /F1` that collides with the source's own `/DR/Font/F1` (dest
    /// `/F1` is Helvetica, source `/F1` is Courier — different refs).
    /// Exercises four qpdf helpers not reached by
    /// `overlay_copy_annotations_onto_existing_acroform_is_byte_identical_qdf`
    /// (whose dest `/AcroForm` has no `/DR` at all):
    ///   1. `QPDFObjectHandle::mergeResources` — rename source `/F1` to
    ///      `/F1_1` on merge into the existing dest `/DR/Font`.
    ///   2. `init_dr_map` — populate `dr_map = {Font: {F1: F1_1}}`.
    ///   3. `adjustDefaultAppearances` — rewrite each copied field's `/DA`
    ///      to reference `/F1_1` instead of `/F1`.
    ///   4. `adjustAppearanceStream` (`ResourceReplacer`) — rewrite the
    ///      `/F1` operand inside each copied field's AP stream content to
    ///      `/F1_1`.
    ///
    /// Fixture: `fxo-red-with-existing-acroform-dr.pdf` is
    /// `fxo-red-with-existing-acroform.pdf` with an indirect `/AcroForm/DR`
    /// added (`/Font << /F1 <ref-to-Helvetica> >>`).
    ///
    /// Golden generated with (qpdf 11.9.0):
    /// ```text
    /// qpdf --qdf --static-id --no-original-object-ids --min-version=1.6 \
    ///   tests/fixtures/compat/fxo-red-with-existing-acroform-dr.pdf \
    ///   --overlay tests/fixtures/compat/form-fields-and-annotations.pdf --repeat=1 \
    ///   -- tests/golden/references/overlay/overlay-onto-existing-acroform-dr.pdf
    /// ```
    ///
    /// Golden inspection confirms all three of:
    ///   - dest `/AcroForm/DR/Font` has both `/F1 -> Helvetica` and
    ///     `/F1_1 -> Courier`.
    ///   - every copied field `/DA` string reads `/F1_1 ... Tf`.
    ///   - at least one copied AP stream content is
    ///     `/Tx BMC q BT /F1_1 18 Tf ... ET Q EMC` with its own
    ///     `/Resources/Font/F1_1` pointing at the Courier font — proving
    ///     `ResourceReplacer` fired on the stream, not just the `/DA` string.
    #[test]
    fn overlay_copy_annotations_onto_existing_acroform_dr_is_byte_identical_qdf() {
        let mut dest = fixture("fxo-red-with-existing-acroform-dr.pdf");
        let mut src = fixture("form-fields-and-annotations.pdf");
        let (version, max_ext) = accumulate_max(&mut dest, &mut src).get_version();
        let mut specs = vec![OverlaySpec {
            source: src,
            kind: OverlayKind::Overlay,
            from: pr(""),
            to: pr(""),
            repeat: Some(pr("1")),
        }];
        handle_under_overlay(&mut dest, &mut specs).unwrap();
        let actual = write_qpdf(&mut dest, |writer| {
            writer.set_static_id(true);
            writer.set_qdf_mode(true);
            writer.set_suppress_original_object_ids(true);
            writer.set_minimum_pdf_version(version, max_ext);
        });
        assert_byte_identical(&actual, "overlay-onto-existing-acroform-dr.pdf");
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Cursor;

    /// Build a minimal PDF from a contiguous run of `1..=objects.len()`
    /// objects, in `(object_number, body_literal)` order. `catalog_ref` is
    /// the object number of the `/Catalog` object. Mirrors the identically
    /// named helper in `page_object_helper.rs`.
    fn pdf_from_objects(catalog_ref: u32, objects: &[(u32, String)]) -> Vec<u8> {
        let mut data: Vec<u8> = b"%PDF-1.4\n".to_vec();
        let mut offsets: Vec<u64> = Vec::with_capacity(objects.len());
        for (num, body) in objects {
            offsets.push(data.len() as u64);
            data.extend_from_slice(format!("{num} 0 obj\n{body}\nendobj\n").as_bytes());
        }
        let xref_start = data.len() as u64;
        let total = objects.len() + 1;
        let mut xref = format!("xref\n0 {total}\n0000000000 65535 f \n");
        for off in &offsets {
            xref.push_str(&format!("{off:010} 00000 n \n"));
        }
        data.extend_from_slice(xref.as_bytes());
        let trailer = format!(
            "trailer\n<< /Size {total} /Root {catalog_ref} 0 R >>\nstartxref\n{xref_start}\n%%EOF\n"
        );
        data.extend_from_slice(trailer.as_bytes());
        data
    }

    /// `page_box_or_err` must reject a destination page whose `/MediaBox` is
    /// absent from its whole ancestor chain, exercising the resolving
    /// `try_is_null()` check (not the non-resolving `is_null()` that never
    /// forces the dereference `ObjectHandle::is_null`'s own doc warns about).
    #[test]
    fn page_box_or_err_rejects_a_page_with_no_media_box_in_its_ancestry() {
        let objects = vec![
            (1, "<< /Type /Catalog /Pages 2 0 R >>".to_string()),
            (2, "<< /Type /Pages /Kids [3 0 R] /Count 1 >>".to_string()),
            (3, "<< /Type /Page /Parent 2 0 R >>".to_string()),
        ];
        let bytes = pdf_from_objects(1, &objects);
        let mut pdf = Pdf::open(Cursor::new(bytes)).expect("PDF should parse");
        let page_ref = ObjectRef::new(3, 0);

        let error = page_box_or_err(&mut pdf, page_ref, BoxKind::Media)
            .expect_err("a page with no /MediaBox anywhere in its ancestry has no usable box");
        assert!(
            error.to_string().contains("has no usable placement box"),
            "unexpected error: {error}"
        );
    }

    /// The non-null path (an actual `/MediaBox`) must still resolve to a
    /// usable `PageBox`, so the changed `try_is_null()` branch does not
    /// regress the common case.
    #[test]
    fn page_box_or_err_accepts_a_page_with_a_media_box() {
        let objects = vec![
            (1, "<< /Type /Catalog /Pages 2 0 R >>".to_string()),
            (2, "<< /Type /Pages /Kids [3 0 R] /Count 1 >>".to_string()),
            (
                3,
                "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] >>".to_string(),
            ),
        ];
        let bytes = pdf_from_objects(1, &objects);
        let mut pdf = Pdf::open(Cursor::new(bytes)).expect("PDF should parse");
        let page_ref = ObjectRef::new(3, 0);

        let page_box = page_box_or_err(&mut pdf, page_ref, BoxKind::Media)
            .expect("a page with a direct /MediaBox has a usable box");
        assert_eq!(page_box, PageBox::new(0.0, 0.0, 612.0, 792.0));
    }
}