HTML derivation coverage

Optional module · pdftoolkit/pdf-to-html 0.1.1

English · Français

Reference scope

The retained reference is Deriving HTML from PDF 1.2, September 2026, a PDF Association usage specification for Well-Tagged ISO 32000-2 files. It has 74 physical pages, including front matter and annexes. It is not an HTML-to-PDF specification or a specification for visual layout reconstruction.

resources/reference.json inventories its sections. Recording a section does not prove implementation of every rule. Released code, executable tests, independent validation and diagnostics must be considered together.

Three scopes to distinguish

1. Source model and semantic derivation: applications supply explicit structure, Unicode content, attributes, widgets, associated files and policies.
2. PDF file adapter: the reader recovers those facts from accepted encodings, operators and mechanisms. A modeled feature does not mean that every external PDF using it can be ingested.
3. Browser/runtime integration: serving HTML, resolving assets, accepting form submissions and providing a JavaScript runtime belong to the application. Returning script bytes does not execute or emulate them.

Implemented mechanisms and evidence

The table describes executable behavior in this package, including explicit application ports. Its tests do not establish universal input-file acceptance or certification of the source document.

For the numbered body, the physical PDF page equals the printed page plus six. The source inventory records physical ranges.

MathML filtering admits 192 element names from the W3C MathML 3 RelaxNG modules, their 129 schema attribute names and explicitly supported global/Core additions. This is a vocabulary/security filter, not validation against every MathML grammar constraint. Presentation, Content and elementary MathML are preserved where accepted; Content MathML and mstack are not obsolete, but native browser rendering is not promised. Vocabulary outside the supported Core subset reports extended-mathml-vocabulary. No computer algebra system or rendering polyfill is supplied. Namespace and HTML-integration tests in HtmlBoundaryTest also cover forged MathML names, foreign XML and embedded HTML. SVG/OpenMath foreign XML is outside this profile.

File-ingestion boundaries

• The native reader accepts PDF 1.0–2.0 syntax and PDF 2.0 UTF-8 strings. It still rejects encrypted input, hybrid xrefs, unsupported filters and damaged syntax. An AuthenticationProvider supplies the external authenticated/decrypted model; this package does not include native cryptographic authentication.
• The input needs a usable structure tree. No OCR, inferred tagging or geometric reading-order reconstruction is performed. MCIDs, parents, cycles, page membership and namespace identities are checked explicitly.
• Text uses embedded ToUnicode codespaces, bfchar/bfrange and embedded-stream UseCMap inheritance, or known simple-font encoding vectors/Differences with unambiguous glyph mappings. Named external CMaps and composite fonts without a usable ToUnicode collection are not implicitly resolved. Unsupported text becomes an explicit graphic/diagnostic node; malformed mappings are rejected.
• Inline BI…ID…EI images are rejected explicitly rather than scanned heuristically. Image extraction accepts supported DeviceGray/DeviceRGB JPEG or decoded eight-bit samples without Mask/SMask/Decode transformations. Other codecs, masks, colour spaces and depths need an application decoder/renderer.
• Affine transforms determine logical edge lengths, not sample dimensions or a complete CSS reproduction of PDF positioning/clipping. Degenerate/non-finite transforms and ambiguous reused Form/image contexts fail explicitly or produce an unsupported-image node. Rendering paths, shadings and full appearance groups requires the explicit ContentRenderer/AppearanceRenderer ports.

Safe defaults and enabled profiles

The default DerivationPolicy disables allowActiveContent and allowRemoteResources, keeps preferVisualFigures=false and produces semantic figure content. Native PHP derivation never executes scripts or fetches URLs. Supported, sanitized embedded HTML/MathML and raster assets can still be derived.

Enabling allowActiveContent deliberately exports trusted JavaScript/runtime and allows restricted imported CSS/SVG; it is not a browser sandbox or proof that source scripts are safe. allowRemoteResources separately permits output resource URLs, which a receiving browser may fetch. It does not make the PHP library fetch them. Neither setting implements the full Acrobat/ISO 21757-1 JavaScript API.

ScriptAssetEmitter externalizes enabled script source as pdf-script-<sha256>.js, retaining its exact JavaScript bytes without HTML closing-script ambiguities. Applications must write every returned asset beside the HTML, or consistently remap URLs. This is packaging, not script sanitization. HtmlBoundaryTest exercises closing-script payloads; the default safe profile emits no script runtime.

preferVisualFigures=true requests rendering through the supplied engine; it neither installs nor launches one. Readonly controls without native HTML readonly behavior report the required application/runtime enforcement. Form submission, trust and permission enforcement remain application responsibilities.

Accessible HTML still requires review of authoring, reading order, text alternatives, forms and actual assistive-technology behavior. No blanket ISO, WTPDF, PDF/UA or WCAG certification is claimed.

Reproducible evidence

CI runs PHP 8.3–8.5, PHPUnit, static analysis and formatting. It also runs:

1. validate_reference.py: original filename, 900894 bytes, SHA-256, CC-BY-4.0 identity and 74 pages via an independent reader.
2. build_reading_fixture.py --check: recreate the original MIT PDF 2.0 fixture using pinned pypdf 6.20.1 and compare its bytes and manifest. No PHP writer creates this input.
3. validate_derivation.py: independently inspect the PDF with pypdf, run the PHP conversion and parse the real result with html5lib's HTML5 parser. Check Unicode, title/language, forms, links, unique IDs, alternatives and asset hashes, plus six synthetic semantic transformations. It also checks PDF 2.0 simple-font metrics, indirect descriptors and the AcroForm default-appearance font resources independently of text extraction.
4. runtime.cjs: execute the opt-in bridge in a bounded Node harness, exercising common field operations without a browser or network.

The initial 0.1.0 candidate passes 192 tests / 592 assertions on each PHP version, PHPStan level 8, PSR-12 checks across 78 PHP files and Composer's strict, platform and advisory checks. These counts identify the reviewed candidate; the executable suite remains the source of truth for subsequent changes.

The input has SHA-256 53b69e6ab8bf438c5fd896990ce26e1fbd0eb8a8a475c4a1bbd9e8e90fab23c0. Its one-pixel image is painted at 20 PDF points: reading preserves 20 × 20 points and derivation produces rounded 27 × 27 CSS pixels, rather than treating the sample grid as its physical size. Matrix tests additionally cover q/Q, nested Forms, rotation, shear and UserUnit.

Central documentation presents the input PDF, every rendered page, executable PHP, actual HTML/JSON and exact released-source provenance. HTML5 parsing and these tests are evidence for the exercised cases, not a universal HTML/CSS/ARIA validator or automatic accessibility certification.

Documented HTML and security adaptations

The reference and current HTML authoring rules do not agree in every case. These decisions are explicit adaptations, with diagnostics, rather than claims that incompatible markup can be reproduced unchanged:

HTML authorities: obsolete features, file inputs, table scope, and ARIA naming requirements. MathML authorities: official RelaxNG modules, presentation markup, content markup and MathML Core. See security before enabling an active-content policy.

Guide source at the documented commit ↗