Documentation

LoupePDF docs

Everything you need to embed the viewer, wire your host's services, and extend the surface with plugins. Built from the published @printwithsynergy/loupe-pdf package.

Getting started

Overview

Host-agnostic OSS PDF viewer core for React 19. A plugin-driven canvas viewer with overlay, panel, and toolbar slots. AGPL-3.0-or-later.

Architecture

How the two host contexts and the slot-aware plugin registry fit together, plus the coordinate space the viewer uses for pages, items, and sampling tools.

LoupePDFViewer (one-line viewer)

Default high-level composition. One JSX line gets you a working multi-page PDF viewer with auto-discovered pages, layers, zoom, color picker, and measure tool.

Reference

Implement only the protocols your host supports — page images, layers, separations, TAC heatmaps, color sampling, densitometer, annotations, reports. Unwired services hide their consuming components automatically.

Fallback & capability detection

Tools self-hide when their backing service is unwired. Hosts can opt into graceful degradation with the in-browser pdf.js fallback adapter for page rendering, layers, and color sampling.

Component reference

Per-component props, slots, and usage for every React component the package exports — page canvas, navigator, separations, layers, annotations, mobile chrome.

Plugin model

Slot identifiers, plugin shapes, and registration semantics. Includes the replaces mechanism for shadowing first-party plugins with third-party drop-in alternatives.

Measurement units

Built-in millimetre, inch, point, pica, and agate definitions, plus the MeasurementUnit protocol for adding custom units to the MeasureTool.

Theme, i18n, telemetry, read-only mode

Brand tokens, translation strings, analytics hooks, and the read-only flag for share-link viewers. All optional — the no-op defaults keep OSS hosts fast.

Reference server

Optional Node + Ghostscript backend that supplies real ink separations, densitometer readings, TAC heatmap, and color sampling. Deploy if you need preflight-grade tools the in-browser fallback can't provide.

Shareable links

Generate and parse shareable viewer URLs that pre-load a specific PDF with custom settings — fullscreen, zoom, page, mode, tools, and theme.

PDF validation

Client-side PDF validation — magic bytes, MIME type, file size — before handing a file to the viewer or pdf.js fallback. Runs entirely in the browser.