Skip to content

Add a stationery plan: templates per page range plus a default - #9

Merged
MPCoreDeveloper merged 3 commits into
mainfrom
feature/stationery-overlay
Nov 14, 2026
Merged

MPCoreDeveloper merged 3 commits into
mainfrom
feature/stationery-overlay

Conversation

@MPCoreDeveloper

@MPCoreDeveloper MPCoreDeveloper commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds a stationery plan on top of the underlay layer the editor already writes, closing the range/default gap in #6.

  • PdfStationery (src/SharpCorePDF.Domain/ValueObjects/PdfStationery.cs): an immutable mapping of templates to PageRanges plus a default; Assign, AssignDefault, AssignNone, ResolveForPage, Validate.
  • PdfEditPlan.ApplyStationery(...) records it as one PdfStationeryOperation (PdfEditOperationKind.ApplyStationery = 25), so page numbers resolve against the document state at that point in the plan.
  • The engine expands each assignment to the existing underlay form XObject (PdfEditEngine.Pages.cs, PdfEditEngine.Sources.cs), so content streams are untouched and nothing is rasterized.
  • Assignments are tried last first (a narrower range overrides a broader one); a page with no assignment gets the default; AssignNone opts a range out. A one-page template repeats; a multi-page template maps one page for one page and a range that reaches past it is refused at run time.
  • PDF/A-1b refuses a translucent or blended stationery, matching the existing overlay rule.

Acceptance criteria (#6)

Each criterion has a test named for it in PdfDocumentEditorTests.StationeryAcceptance.cs:

Criterion Test
Different stationery on selected pages/ranges Acceptance_criterion_1_applies_different_stationery_to_pages_and_ranges
Default stationery on the remaining pages Acceptance_criterion_2_applies_default_stationery_to_the_remaining_pages
Multi-page content PDF Acceptance_criterion_3_supports_a_multi_page_content_pdf
Page dimensions and content positioning preserved Acceptance_criterion_4_preserves_page_dimensions_and_content_positioning
Vector graphics and selectable text preserved Acceptance_criterion_5_preserves_vector_graphics_and_selectable_text
Valid combined PDF, no rasterization Acceptance_criterion_6_produces_a_valid_pdf_without_rasterization

Tests

  • 20 new tests: 14 behaviour tests in PdfDocumentEditorTests.Stationery.cs and 6 acceptance tests (one per criterion above).
  • Full suite: 1185 passed / 0 failed / 0 skipped on net10.0 and net11.0.
  • Scoped Stryker over PdfStationery.cs: 100% (survivors read and killed).
  • External validation of the stationery example output with the repo's pikepdf/qpdf tool:
    • qpdf check: no problems, PDF 1.7, 3 pages
    • page sizes preserved: 842x595, 832x595, 822x595
    • 3 form (vector) XObjects, 0 image XObjects — nothing rasterized

Docs

  • Manual: docs/manual/src/14-editing.md section "Stationery".
  • docs/parity.md US2 note.
  • Example: stationery scenario.

Closes #6.

PdfStationery describes which background goes behind which pages, and PdfEditPlan.ApplyStationery records it as one operation that expands to the underlay layers the editor already writes. Assignments are tried last first, a page no assignment covers gets the default, and AssignNone opts a range out. A one-page template repeats across its range; a multi-page template maps one page for one page, and a range that reaches past it is refused when the plan runs.

The PDF/A-1b no-transparency rule the overlay path already enforces applies to stationery too. Fourteen tests pin the mapping, the default, the opt-out, value semantics and the refusal; the manual, the parity record and a stationery example describe it. Refs #6.
Six tests named after the checklist in the issue prove, end to end, that stationery applies per page and per range, fills the rest from a default, supports a multi-page content document, keeps every page size and every letter baseline, preserves the template's vector and text operators, and writes a valid document with no image XObject to show for rasterization.

All six pass on net10.0 and net11.0; the full suite is 1185 tests.
The release checklist G3 refuses a version whose notes do not exist, so the public addition this branch already carries is written down before the release commit: PdfStationery, PdfEditPlan.ApplyStationery, the underlay form XObject and the range/default rules, with the manual and the acceptance tests named.
@MPCoreDeveloper
MPCoreDeveloper merged commit 1788d8a into main Nov 14, 2026
5 checks passed
@MPCoreDeveloper
MPCoreDeveloper deleted the feature/stationery-overlay branch November 14, 2026 13:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] Overlay PDF Content onto Configurable PDF Stationery

1 participant