# PDF-to-HTML Visual Parity POC

## Status

Proof of concept specification.

## Goal

Convert a PDF into browser-native HTML that closely reproduces the source design while retaining the benefits of HTML:

- indexable text for search engines
- selectable and searchable text
- browser-native links
- downloadable image and font assets
- no PDF viewer, canvas renderer, embedded PDF, or full-page screenshot
- broad compatibility with current desktop and mobile browsers

The POC uses pages 1 through 5 of `Annuals-EU-2027-catalog.pdf`. Heavy conversion and browser validation run on the debian buildboxes, not on the laptop.

## Non-goals

The POC does not attempt to produce a responsive, reflowed redesign. A PDF is a fixed-layout format, so the initial HTML output remains fixed-layout and scales proportionally with the viewport.

The POC does not use Docling as the visual renderer. Docling reconstructs semantic reading flow and intentionally discards much of the source layout.

## POC approach

The first implementation uses pdf2htmlEX as a visual baseline. It converts PDF drawing operations into browser assets and fixed-position HTML:

- text becomes positioned DOM text
- embedded fonts become web fonts
- images become browser image assets or CSS backgrounds
- links become HTML anchors
- each source page becomes a fixed-size HTML page container

The resulting page is HTML, not a displayed PDF. It may use image assets extracted from the PDF, but it must not use a raster image of an entire page as its visible representation.

## Target production architecture

A production converter should use two coordinated pipelines.

### Visual extraction pipeline

A low-level PDF engine such as MuPDF extracts:

- glyphs and text transform matrices
- font programs and font metadata
- raster images
- vector paths
- clipping paths and masks
- page geometry
- links and annotations

The output generator converts these objects into:

- positioned HTML text elements
- WOFF2 web fonts
- image assets
- inline or referenced SVG
- CSS transforms and clipping
- HTML links

### Semantic extraction pipeline

Docling or an equivalent document-understanding engine identifies:

- headings
- paragraphs
- lists
- tables
- captions
- reading order
- language and document metadata

### Alignment layer

The alignment layer associates semantic elements with visual text and object bounding boxes. It then upgrades visual DOM nodes to semantic elements without changing their geometry.

For example, a positioned text run may become an `h1` while preserving the exact font, transform, and coordinates required for parity.

## Output structure

A converted document should be self-contained within one directory:

```text
output/
  index.html
  document.css
  assets/
    fonts/
    images/
    vectors/
  metadata.json
```

The POC may use the native pdf2htmlEX asset layout while validating the concept.

## Browser behavior

- Pages preserve their source aspect ratio.
- Pages scale down to fit narrow viewports.
- Text remains selectable.
- Browser find locates visible text.
- Links remain clickable.
- Pages may be lazy-loaded for large documents.
- Printing the HTML should preserve page boundaries.

## SEO requirements

- Important text must exist in the DOM as real text nodes.
- The document must include a meaningful title and description.
- Heading levels should reflect detected document structure.
- Images should receive useful alternative text when semantic extraction can provide it.
- Duplicate hidden text layers are not acceptable.
- Content must remain available without executing application JavaScript where practical.

Absolute positioning does not prevent indexing, but semantic tags and meaningful reading order are required for high-quality search results.

## Visual parity measurement

Visual parity must be measured, not judged only by inspection.

For each test page:

1. Render the source PDF page to a reference PNG at a fixed viewport and resolution.
2. Render the generated HTML page in Chromium at the same effective dimensions.
3. Compare the images using pixel difference and structural similarity metrics.
4. Produce a visual diff image for failures.

Initial POC acceptance criteria:

- no missing major images or text blocks
- no page-wide raster image used as the visible page
- text selection and browser search work
- links are represented as anchors where present
- page geometry and major visual regions match the source
- the demo loads in current Chromium without console errors

A production acceptance threshold should be established after measuring a representative PDF corpus.

## Risks

- PDF text may be stored as individual glyphs with incomplete Unicode mappings.
- Font licensing or malformed font programs may prevent web-font reuse.
- Blend modes, masks, gradients, and complex clipping can differ between PDF and browser rendering.
- Generated HTML can be large because fidelity requires many positioned elements.
- A fixed-layout conversion is not inherently mobile-reflowable.
- pdf2htmlEX is useful for proving the output model but may not be the final production engine.

## POC deliverables

- HTML conversion of catalog pages 1 through 5
- extracted fonts, images, and CSS required by the HTML
- a simple local demo launcher
- browser validation of the generated output
- documented observations that inform the production converter

## Decision rule

If pdf2htmlEX gives strong parity on the catalog, use it to validate demand and define expected output. Build the production extraction and semantic-alignment pipeline only after testing a wider corpus.

If pdf2htmlEX fails on representative documents, move directly to a MuPDF-based object extractor and custom HTML generator. Docling remains a semantic enrichment component rather than the visual conversion engine.