The KillerPDF.Engine | PDF 2.0 library and developer guide

Independent .NET document library

The

.Engine

The KillerPDF.Engine reads, validates, authors, structurally edits, signs, encrypts and writes PDF files. It was built from scratch as KillerPDF's PDF 2.0 foundation, with a public API intended for other applications as well as the KillerPDF desktop editor.

151engine source files

47,792physical C# lines

1,437engine tests

47,024corpus PDFs

A real library boundary

The engine is not a renamed collection of desktop helpers. It is a UI-free .NET 10 library with no dependency on WPF, KillerPDF application code, PDFium, PdfPig, PdfSharpCore or PDFsharp.

KillerPDF desktop application

WPF interface and workflows
PDFium page rendering
PdfPig text extraction
OCR, printing and desktop integration

→

The KillerPDF.Engine

PDF syntax and object graphs
Authoring and structural editing
Forms, annotations and navigation
Encryption, signatures and standards

The monorepo keeps the application, library, tests and corpus gates in one reviewable change while the project reference enforces the reusable boundary. The formal display name is The KillerPDF.Engine; the assembly, package identifier and namespaces use KillerPdf.Engine.

Major capabilities

Parse real-world PDF structure

Headers, tokens, objects, streams, classic xref tables, xref streams, object streams, trailers, incremental revisions, page trees, name trees and number trees, with bounded parsing and source-aware diagnostics.

Preserve or rewrite deliberately

Byte-preserving incremental updates retain the original file prefix. Deterministic full rewrites produce reproducible output and can use classic xref tables or compressed object and xref streams.

Author complete documents

Pages, content streams, graphics state, paths, text, embedded fonts, images, color spaces, shadings, patterns, transparency, metadata, output intents and viewer behavior.

Edit document structure

Insert, import, remove, reorder, rotate, crop, resize and trim pages while preserving dependent resources and rejecting unsafe partial graph imports.

Build interactive PDFs

Bookmarks, named destinations, links, attachments, annotations, replies, popups, optional content and AcroForm text, button, choice and signature fields.

Protect and sign

RC4, AES-128 and AES-256 Standard Security, crypt filters, permission enforcement, detached CMS signing, certification permissions, field locks and signed-revision analysis.

Author for modern standards

PDF 2.0, tagged PDF, PDF/UA-2, PDF/A-4, PDF/A-4e and PDF/A-4f safeguards coordinate metadata, structure, fonts, annotations, forms and associated files.

Diagnose before writing

Structural inspection distinguishes credentials, recoverable damage and unsafe structure. Round-trip checks and fail-closed preflight prevent ambiguous documents from being silently rewritten.

Architecture

Layer	Responsibility
`Syntax` and `Objects`	Binary-safe tokens and the typed PDF object model.
`CrossReference`, `Filters`, `Documents`	Revision discovery, stream decoding, lazy object resolution and authenticated document access.
`Authoring`	Typed construction of pages, content, resources, metadata, interactive features and conformance structures.
`Editing`	High-level, byte-preserving changes to existing documents and safe cross-document imports.
`Writing`	Incremental revisions, deterministic full rewrites, metadata policy and output sanitization.
`Security` and `Signing`	Password authentication, permissions, encryption, digital signatures and revision verification.
`Diagnostics` and `Validation`	Bounded inspection, implementation limits, structural reports and round-trip validation.

Design rule: preserve existing bytes when the change can be expressed as an incremental revision; fail closed when the structure required for a safe edit cannot be interpreted or preserved.

Developer quick start

KillerPdf.Engine on NuGet.org

dotnet add package KillerPdf.Engine

The engine targets .NET 10. Reference the project directly from a checkout of the KillerPDF repository:

<ProjectReference Include="path\to\KillerPDF\engine\KillerPdf.Engine\KillerPdf.Engine.csproj" />

Author a PDF 2.0 document

using KillerPdf.Engine.Authoring;

byte[] pdf = new PdfDocumentBuilder()
    .SetMetadata(new PdfDocumentMetadata
    {
        Title = "Engine quick start",
        Author = "Example application",
        Language = "en-US"
    })
    .AddBlankPage(612, 792)
    .Build();

File.WriteAllBytes("hello.pdf", pdf);

Inspect and deterministically rewrite

using KillerPdf.Engine.Diagnostics;
using KillerPdf.Engine.Documents;
using KillerPdf.Engine.Writing;

byte[] source = File.ReadAllBytes("input.pdf");
PdfInspectionReport report = PdfDocumentInspector.Inspect(source);

if (!report.IsStructurallyValid)
    throw new InvalidOperationException("The document is not safe to rewrite.");

PdfDocument document = PdfDocument.Open(source);
byte[] rewritten = PdfDocumentWriter.Write(document);
File.WriteAllBytes("output.pdf", rewritten);

Edit an existing document incrementally

using KillerPdf.Engine.Documents;
using KillerPdf.Engine.Editing;

PdfDocument document = PdfDocument.Open(File.ReadAllBytes("input.pdf"));

byte[] updated = new PdfIncrementalPageEditor(document)
    .RotateClockwise(0)
    .AddBlankPage(612, 792)
    .Build();

File.WriteAllBytes("updated.pdf", updated);

The high-level editor also exposes typed operations for page boxes, imports, metadata, output intents, bookmarks, destinations, attachments, forms and page content. Use PdfIncrementalUpdateBuilder only when you deliberately need the lower-level PDF object boundary.

Validation is part of the design

Format support is not inferred from a header or from whether one generated file opens in one viewer. The release gate combines 1,437 engine tests, strict zero-warning Release builds, two 2,907-file public corpus gates, the reproducible 47,024-file full corpus baseline, qpdf structural checks, veraPDF PDF/A-4 and PDF/UA-2 validation, and OpenSSL verification of detached CMS signatures.

Gate	What it catches
Unit and regression tests	Syntax, graph, writer, editor and public API behavior.
Incremental corpus	Unexpected failures or structural damage across deliberately hostile inputs.
Selected-page import corpus	Unsafe graph transfer, stale references and unsupported global dependencies.
qpdf and veraPDF	Independent structural and standards failures.
OpenSSL fixtures	Real detached CMS signature interoperability.

Using the engine in another application

Keep rendering and UI outside the library. The engine operates on PDF bytes and typed document concepts.
Inspect unfamiliar input before selecting an editing or rewrite path.
Use high-level authoring and editing APIs wherever possible. They enforce graph and standards invariants together.
Prefer incremental output for preservation-sensitive edits and signed-document analysis.
Use deterministic rewrites when canonical output, object-stream packing or metadata policy matters.
Run an independent validator appropriate to the profile your application claims.

Public XML documentation is generated during normal builds. The engine README, changelog and architecture decisions remain the source-level reference while the API approaches its first standalone package.

Scope and explicit limits

The KillerPDF.Engine is a document engine, not a renderer or desktop framework. It does not draw pages to the screen, provide UI controls, perform OCR or extract page text. KillerPDF currently uses PDFium for rendering, PdfPig for text extraction and Tesseract for OCR.

Some operations intentionally refuse incomplete global structures. Examples include unsafe partial imports from tagged documents, ambiguous shared object graphs, unsupported XFA merges, missing credentials and edits forbidden by authenticated user permissions. A refusal is safer than producing a file that opens but has silently damaged navigation, forms, accessibility or signatures.

Source, documentation and license

The KillerPDF.Engine is licensed under GPLv3 as part of the KillerPDF repository.