PDF Viewer — Vector-First Engine Migration Bundle
Status (2026-10-25): the migration is complete. Since v4.0.0 the published app has no PDFium (M10): the own engine opens, draws, searches, edits and saves every document, and PDFium stays only in developer and test builds as the reference. These files are kept as the design record (decisions, ADRs, gates). The “current repository facts” below describe the 2026-09-21 baseline, not today. For the current state, read 18_IMPLEMENTATION_STATUS.md and the README.
Repository: ramanacr/pdf-viewer
Baseline reviewed: main, commit/tree observed 2026-09-21
Migration strategy: Own PDF core + vector IR + native Windows renderer; retain PDFium as a temporary compatibility fallback and development oracle; remove it from production only after measurable compatibility gates are met.
Product intent
The existing viewer is retained. This is not a viewer rewrite. The migration replaces the rendering/interpretation heart incrementally while preserving current user-facing capabilities and regression coverage.
The target is:
A small, native-oriented, vector-first PDF engine in which PDF text and graphics remain semantic/vector primitives as long as possible; rasterization is localized to content that inherently requires it or is temporarily unsupported.
The term vector-first does not mean “never rasterize.” Embedded raster images, transparency groups, masks, certain blend operations, and fallback regions may legitimately use intermediate raster surfaces.
Current repository facts used by this bundle
The repository currently contains:
PdfEngine.AbstractionsPdfEngine.PdfiumPdfViewer.Core- WPF
PdfViewer - installer, tests, and benchmarks
- pinned PDFium runtime under
src/PdfViewer/runtimes/win-x64/native/pdfium.dll - PDFium engineering assets under
eng/pdfium - existing tests including engine, comparison/OCR, cache, annotations, security/sanitization, save, layout, and text-selection workflows
- existing
docs/archive/coding-agent-docs(archived)
The current viewer is .NET 9/WPF. Keep it during the engine migration. UI/native-shell replacement is a separate future program.
Read order
01_DECISIONS_AND_SCOPE.md02_CURRENT_TO_TARGET_ARCHITECTURE.md03_REPOSITORY_CHANGE_PLAN.md04_VECTOR_IR_AND_RENDERING_CONTRACT.md05_PDF_CORE_IMPLEMENTATION_PLAN.md06_PDFIUM_FALLBACK_AND_EXIT_PLAN.md07_TEST_CORPUS_AND_VERIFICATION.md08_PERFORMANCE_MEMORY_BUDGETS.md09_SECURITY_ROBUSTNESS.md10_MIGRATION_MILESTONES.md11_CODING_AGENT_EXECUTION.md12_ACCEPTANCE_AND_RELEASE_GATES.md13_RISK_REGISTER.md14_ADRS.md15_BACKLOG.md16_REFERENCE_AND_STANDARDS.md17_IMPLEMENTATION_CHECKLIST.md18_IMPLEMENTATION_STATUS.md— audit, evidence, gate status and remaining work (keep current)
Non-negotiable principles
- Existing viewer behavior must continue to work throughout migration.
PdfEngine.Abstractionsremains UI-neutral.- New code must not expose PDFium handles/types above the PDFium adapter.
- The canonical page representation for the new engine is a display list/vector IR, not a page bitmap.
- Zoom must not mean scaling a cached full-page bitmap.
- Unsupported constructs must be observable and classified.
- PDFium fallback is temporary, explicit, measurable, and removable.
- Parsing untrusted PDFs is hostile-input processing: bounded allocations, recursion, decompression, object counts, and execution time are mandatory.
- No JavaScript execution or automatic active-content execution is introduced.
- Every milestone begins with fail-first tests and ends with measurable gates.
Desired end state
PdfViewer (existing WPF shell)
|
PdfViewer.Core
|
PdfEngine.Abstractions
|
+---------------------------+
| |
PdfEngine.Vector PdfEngine.Pdfium
(primary) (temporary fallback/oracle)
|
PDF Core -> Display List -> Windows Vector Backend
-> localized raster surfaces where required
Final production state removes the right-hand PDFium branch after compatibility gates are achieved.