Architecture

+-----------------------------------------------------------+
|  Host app  ←  React / Vue / Angular / Svelte / plain DOM  |
+----+----------------+---------------------+---------------+
     |                |                     |
     v                v                     v
@trupdf/core    @trupdf/annotations   @trupdf/forms
     |                |                     |
     |                v                     v
     |    interactive annotation     AcroForm / XFA IO
     |    canvas                     via the PDF writer
     v
TruPDF render engine (worker-based)  +  the PDF writer
  +  the native PDF engine (WASM)
  +  the TruPDF conversion engine (server-side)

Three-layer page rendering

Layer 3 (top)    → interactive annotation canvas   pointer-events: all
Layer 2 (middle) → text layer div                  STANDARD MODE ONLY, pointer-events: none
Layer 1 (bottom) → render engine canvas            pixel-accurate render, aria-hidden

The render engine paints each page pixel-accurately onto the bottom canvas from a background worker. The text layer (standard mode only) overlays invisible selectable text for search, copy, and screen readers — it is never mounted in secure mode. The interactive annotation canvas sits on top and owns all pointer input for annotation tools.

Container is position: relative. All layers share identical CSS dimensions. The annotation canvas is initialised after the render engine paints so dimensions match.

Coordinate spaces

Space	Origin	Unit	Used in
PDF user space	bottom-left	points (1/72")	XFDF, `AnnotationRecord`
Viewport space	top-left	CSS px × scale	the page viewport (zoom / rotation applied)
Canvas space	top-left	CSS pixels	object positions on the annotation canvas

Always convert via the exported coordinate converters in @trupdf/annotations. Never hardcode coordinate math — canvas-space pixel values must never end up in XFDF.

Engineering guarantees

Memory lifecycle pairing. Every page render, document handle, per-page annotation canvas, and blob URL has a teardown paired with its creation — long sessions don't leak.
Cancellable async. Every render, load, conversion, and save accepts an AbortSignal; superseded work is cancelled, and cancellations never surface as errors.
Worker-based search. Text search runs in a background Web Worker — the UI thread never blocks on large documents.
Resilient realtime. Collaboration reconnects with exponential backoff and stops cleanly on destroy.
Structural-only redaction. The redaction engine refuses to burn unless a structural adapter is registered — there is no visual-only fallback.