How EggPdf Works

The 8-stage pipeline

EggPdf is a pure data transformation pipeline. Each stage takes a well-defined input type and produces a well-defined output type. No stage holds state between renders.

Project structure

The pipeline maps to independent C# projects with strict one-way dependencies. No circular dependencies are permitted; EggPdf.Core depends on nothing.

EggPdf (public API facade)
  ├── EggPdf.Html        (depends on: Core)
  ├── EggPdf.Css         (depends on: Core, Html)
  ├── EggPdf.Style       (depends on: Core, Css, Text)
  ├── EggPdf.Layout      (depends on: Core, Style, Text)
  ├── EggPdf.Fragmentation (depends on: Core, Layout)
  ├── EggPdf.Paint       (depends on: Core, Layout, Fragmentation, Text)
  ├── EggPdf.Pdf         (depends on: Core, Paint, Text)
  ├── EggPdf.Text        (depends on: Core)
  └── EggPdf.Core        (no dependencies — primitives only)

Key design decisions

Infallible parsers

The HTML and CSS parsers never throw. The HTML parser produces error-recovery DOM nodes per the HTML5 specification — any string input, however malformed, produces a valid HtmlDocument. The CSS parser skips invalid declarations and continues; no CSS parse error will crash a render.

Region-based pagination

Rather than separating layout and pagination into two distinct passes, each layout element receives a sequence of regions: the remaining space on the current page, then full subsequent pages. The element decides how to split itself across those regions. This means new layout modes (flex, grid, table) get correct pagination automatically without extra pagination logic.

Three-state layout response

Every layout element reports one of three outcomes after layout:

• Fit — the element fits entirely in the current region.
• Split — the element partially fits; render the part that fits now and continue the remainder on the next page.
• Skip — the element does not fit at all; move it entirely to the next page.

This three-state contract drives automatic, lossless pagination across all layout modes.

Pluggable paint backend

The paint layer emits abstract drawing commands: draw text, draw rectangle, draw image, draw border. The PDF backend consumes these commands and produces PDF operators. A raster backend exists for visual regression testing — the layout engine produces pixel-accurate output without any PDF round-trip, making test diffs fast and deterministic.

Self-serializing PDF objects

Each PDF object writes itself to the output stream. A central reference table assigns object numbers and tracks byte offsets, which are then used to build the cross-reference table at the end of the file. This avoids buffering the entire document in memory.

Thread and memory model

HtmlToPdf is safe to use from multiple threads simultaneously. Each RenderAsync() call creates its own pipeline instances — DOM tree, CSS cascade, layout tree — with no shared mutable state. The only shared state (font cache, UA stylesheet) is read-only after initialization and requires no locking.

Memory scales with document size but is bounded: only the current page's layout and paint data are in memory at any time. Previous pages have already been written to the output stream and their memory released.

Error handling strategy