renderpdf-js 0.1.0 → 0.2.1

package/README.md

@@ -4,221 +4,294 @@
 
 # RenderPDF.js
 
-An open-source TypeScript library for converting HTML/CSS to PDF in the browser,
-with selectable text, local raster fallbacks and automatic pagination. The browser
-calculates layout; RenderPDF.js uses its measured text, box, image and table
-coordinates to write the PDF. Conversion runs entirely on the client.
+**Convert HTML, PNG, JPEG and multipage TIFF to PDF in the browser.**
 
-The renderer is experimental and supports the bounded subset described below.
-Chromium is the verified browser; Firefox/Safari compatibility has not been
-established.
+[![npm version](https://img.shields.io/npm/v/renderpdf-js)](https://www.npmjs.com/package/renderpdf-js)
+[![CI](https://github.com/MichalekJan93/renderPDF.js/actions/workflows/check.yml/badge.svg?branch=main)](https://github.com/MichalekJan93/renderPDF.js/actions/workflows/check.yml)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/MichalekJan93/renderPDF.js/blob/main/LICENSE)
 
-## Getting started
+HTML exports use the browser's layout, keep text selectable and split content
+across pages. Conversion runs locally, without a conversion server.
+
+**Experimental.** Chromium is the verified browser. Firefox and Safari have not
+been verified. HTML rendering supports the [subset described below](#supported-scope).
+
+## Features
 
-Install the library in a browser application with a bundler, such as Vite:
+- Selectable HTML text with embedded fonts, native boxes, images and tables.
+- Automatic pagination, repeated table headers, page headers and page numbers.
+- PNG/JPEG conversion and one PDF page per frame of a multipage TIFF.
+- Paper sizes, margins, document properties, progress events and cancellation.
+- ESM package with TypeScript declarations.
+
+## Getting started
 
 ```sh
 npm install renderpdf-js
 ```
 
-The package provides an ESM entry and TypeScript declarations. Version 0.1.x is
-experimental; review the supported scope and limits before using it for documents.
-To try HTML preview and PDF download from a source checkout, run the independent
-[playground](https://github.com/MichalekJan93/renderPDF.js/tree/main/playground).
+Use the package in a browser application with an ESM bundler, such as Vite.
+The [playground](https://github.com/MichalekJan93/renderPDF.js/tree/main/playground)
+provides an HTML editor, preview and PDF download from a source checkout.
 
-## Usage
+## HTML usage
 
-Import the public API from the installed package in your application's browser entry:
+Register a font, select an existing element and export it:
 
 ```ts
-import { registerFont, renderPDF, RenderPDFError } from 'renderpdf-js';
+import { registerFont, renderPDF } from 'renderpdf-js';
 
-// Fetch a licensed static TTF/OTF program owned by the application.
+// Supply a licensed static TTF/OTF file from your application.
 const response = await fetch('/fonts/MyFont-Regular.ttf');
 if (!response.ok) throw new Error('The document font could not be loaded.');
-// Register before displaying/measuring the source; use a family owned by this registration.
+
 const regular = await registerFont({
   family: 'Document Sans',
   data: await response.arrayBuffer(),
 });
-// The source stays connected and keeps its existing browser-calculated dimensions.
+
 const source = document.querySelector<HTMLElement>('#invoice');
 if (!source) throw new Error('Invoice element was not found.');
 source.style.fontFamily = 'Document Sans';
 
-try {
-  // At the default A4 margins the source must fit within approximately 745.7 CSS pixels.
-  const pdf = await renderPDF(source, {
-    fonts: [regular],
-    format: 'A4',
-    orientation: 'portrait',
-    margin: 24,
-    rasterScale: 2,
-    fallback: 'auto',
-    pageBreak: 'css',
-    onWarning: (warning) => console.info(warning.code, warning.message),
-  });
-  await pdf.download('invoice.pdf');
-  // Independent byte and Blob forms do not render the source again.
-  const bytes = await pdf.toUint8Array();
-  // Applications can preview, store or upload this Blob themselves if required.
-  const blob = await pdf.toBlob();
-  console.info(pdf.pageCount, bytes.byteLength, blob.type);
-} catch (error) {
-  if (error instanceof RenderPDFError) console.error(error.code, error.message);
-  else throw error;
-}
+const pdf = await renderPDF(source, {
+  fonts: [regular],
+  format: 'A4',
+  margin: 24,
+});
+
+await pdf.download('invoice.pdf');
 ```
 
-Register each used family, weight and style explicitly, including bold headings.
-`registerFont({ family, data, weight: 700, style: 'normal' })` registers a bold
-program; italic uses `style: 'italic'`. The first computed CSS family must match a
-provided handle. System fonts cannot be recovered through browser layout APIs.
-Registration copies bytes, rejects conflicting browser faces and reuses identical
-registrations. Importing the module is safe without a DOM; conversion and font
-registration require a browser document.
-Variable fonts, WOFF/WOFF2 and font collections are rejected; supply static
-TTF/OTF instances. Do not remove or replace registered browser faces during use.
+Register every font family, weight and style used by the source, including bold
+and italic faces. For example, add `weight: 700` when registering a bold font.
+The first computed CSS font family must match a registered face. Static TTF/OTF
+files are required; system fonts, variable fonts, WOFF/WOFF2 and font collections
+are unsupported.
+
+Keep the source connected to the document and unchanged during export. Its width
+and wrapping are preserved, so it must already fit the page's content width:
+about **745.7 CSS pixels** for A4 with the default margins. Oversized HTML is not
+automatically scaled down.
+
+## Standalone image files
+
+`imageToPDF` accepts a `File`, `Blob`, `ArrayBuffer` or `Uint8Array`. It detects
+the format from the file contents and requires no HTML element or fonts.
+
+```ts
+import { imageToPDF } from 'renderpdf-js';
+
+const fileInput = document.querySelector<HTMLInputElement>('#image');
+const file = fileInput?.files?.[0];
+if (!file) throw new Error('Select a PNG, JPEG or TIFF file.');
+
+const pdf = await imageToPDF(file, { format: 'A4', margin: 24 });
+await pdf.download('document.pdf');
+```
+
+PNG and JPEG produce one page. Each main TIFF frame produces a page in file order.
+Images are centered and scaled to fit within the margins, preserving their aspect
+ratio; small images can be enlarged. TIFF/EXIF orientations, including mirrored
+orientations and PNG `eXIf`, are applied. JPEG compressed bytes are preserved.
+Image text remains a bitmap; there is no OCR.
+
+See [image format limits](#image-format-limits) for supported TIFF profiles.
+TIFF support applies to this API; HTML `<img>` elements accept PNG/JPEG.
+
+## Options
+
+Both conversion functions accept these settings:
+
+| Option        | Default                 | Description                                                           |
+| ------------- | ----------------------- | --------------------------------------------------------------------- |
+| `format`      | `'A4'`                  | `'A4'`, `'A3'`, `'Letter'` or `{ width, height }`.                    |
+| `orientation` | `'portrait'`            | `'portrait'` or `'landscape'`.                                        |
+| `margin`      | `24`                    | One value or `{ top, right, bottom, left }`.                          |
+| `metadata`    | Title: `'RenderPDF.js'` | Unicode `title`, `author`, `subject` and `keywords` (a string array). |
+| `onProgress`  | —                       | Receives `{ stage, completed, total }`.                               |
+| `signal`      | —                       | An `AbortSignal` for cancellation.                                    |
+
+Dimensions and margins use **CSS pixels**: `1 px = 0.75 PDF pt`. Custom paper
+dimensions include margins; landscape swaps the supplied width and height.
+
+HTML exports also accept:
+
+| Option               | Default  | Description                                                                            |
+| -------------------- | -------- | -------------------------------------------------------------------------------------- |
+| `fonts`              | Required | Registered faces used by the source and page text.                                     |
+| `pageBreak`          | `'css'`  | Honor supported CSS breaks, or use `'auto'` for geometry alone.                        |
+| `repeatTableHeaders` | `false`  | Repeat native `thead` groups on continuation pages.                                    |
+| `header`, `footer`   | —        | One plain text line in a reserved area on every page.                                  |
+| `fallback`           | `'auto'` | Rasterize supported local effects; `'strict'` requires explicit `data-raster` regions. |
+| `rasterScale`        | `2`      | Raster pixels per CSS pixel.                                                           |
+| `onWarning`          | —        | Receives export warnings.                                                              |
+
+### Repeated table headers and page text
+
+```ts
+const pdf = await renderPDF(source, {
+  fonts: [regular],
+  repeatTableHeaders: true,
+  header: { text: 'Account statement', height: 32 },
+  footer: {
+    text: 'Page {pageNumber} of {pageCount}',
+    height: 28,
+    fontSize: 11,
+    align: 'right',
+  },
+});
+await pdf.download('statement.pdf');
+```
+
+Header and footer `height` is required and reserves space **in addition to** the
+outer margins. Each accepts one plain Latin text line, including Czech diacritics,
+with `{pageNumber}` and `{pageCount}` placeholders. Text stays selectable and does
+not wrap. `fontSize` defaults to `12`, `align` to `'left'`, and `font` to the first
+face in `fonts`. Alignment can also be `'center'` or `'right'`. Text that does not
+fit fails explicitly. HTML page templates and per-page callbacks are unsupported.
+
+### Export progress and document properties
+
+```ts
+const pdf = await renderPDF(source, {
+  fonts: [regular],
+  metadata: { title: 'Account statement', author: 'Example Company' },
+  onProgress: ({ stage, completed, total }) => {
+    console.log(stage, completed, total);
+  },
+});
+```
+
+Counters describe work within the current stage, rather than elapsed-time
+percentages. HTML stages are `preparing`, `layout`, `pagination`, `resources`,
+`pages`, `saving` and `complete`. Image conversion omits `layout` and `pagination`.
+Callbacks are synchronous; a thrown callback error rejects the export. Cancellation
+is cooperative between stages and rejects with `AbortError`, without a partial PDF.
+
+## Output and errors
+
+Both functions return the same result:
+
+```ts
+await pdf.download('document.pdf');
+const blob = await pdf.toBlob();
+const bytes = await pdf.toUint8Array();
+console.log(pdf.pageCount, pdf.warnings);
+```
+
+These output methods reuse the completed PDF. `RenderPDFError`, exported from the
+package, exposes a `code` and `message` for conversion failures. Warnings are
+available through `onWarning` for HTML exports and `pdf.warnings`. Unsupported
+input fails explicitly instead of silently producing a whole-page screenshot.
 
 ## Supported scope
 
-- Static block, inline, nonoverlapping Flexbox and Grid geometry with horizontal
-  Latin text, including Czech diacritics.
-- Solid backgrounds, uniform solid rectangular borders and browser-measured
-  padding, margins and alignment.
-- Native PNG/JPEG images loaded from data, blob, same-origin or CORS-readable URLs.
-  Other image formats fail explicitly. External images can require a browser
-  fetch at export time; document data is never submitted to a conversion service.
-  JPEG EXIF orientation must be absent or 1; normalize rotated image pixels first.
-- Legacy `FONT`, `CENTER` and simple tables with separate borders. Table rows and
-  rowspan cells remain atomic; oversized atomic content fails.
-- A4, A3 and Letter, portrait/landscape, a numeric margin or four explicit edges.
-  Custom paper uses `format: { width: 500, height: 400 }`; dimensions include
-  margins. Landscape swaps the supplied base axes, including custom dimensions.
-  Page dimensions and margins use CSS pixels; `1 CSS px = 0.75 PDF pt`. The renderer preserves
-  source width and wrapping and fails if it exceeds the page's content width.
-- Automatic local fallback for gradients, inline bitmap backgrounds, rounded
-  corners, inset shadows and opacity on independently capturable rectangular
-  blocks. Plain parents stay native; a selected parent owns all nested effects
-  and is captured once in paint order. Descendant text adds extraction-only PDF
-  objects where safe. Layout/order/overlap guards also apply inside automatic
-  regions. Inline fragments and table-internal raster boundaries are rejected.
-  Raster resources must be inline bitmaps; external resources, backdrop effects,
-  transforms and effects outside the border box are rejected.
-  Wrapped native inline backgrounds/borders need an explicit containing raster;
-  a single union rectangle cannot reproduce their separate line fragments.
-- Explicit `data-raster` remains available. `fallback: 'strict'` disables automatic
-  selection while honoring these caller-selected boundaries. Neither mode silently
-  substitutes a whole-document screenshot when a local feature cannot be rendered.
-- `pageBreak: 'css'` (default) respects block/table-row `break-before: page` and
-  `break-after: page`, their legacy `page-break-*: always` aliases, and
-  `break-inside: avoid/avoid-page`. Before/after avoidance conservatively keeps
-  adjacent complete block siblings together when they fit. `pageBreak: 'auto'`
-  ignores authored fragmentation hints and uses only measured atomic geometry.
-
-Page mapping keeps consecutive source intervals: native backgrounds and boxes may
-span pages, while measured text lines, images, raster regions, table rows and
-rowspan cells remain atomic. Fitting avoid blocks move intact to the next page.
-An oversized or incompatible avoid preference relaxes with `BREAK_AVOID_RELAXED`;
-it never authorizes cutting an atomic item. Forced breaks take precedence over
-soft avoidance, and coincident/root-edge rules create no empty pages. A forced
-break through an atomic object, including a raster descendant or spanning cell,
-fails with `PAGINATION_FAILED`. Atomic content taller than a page also fails.
-
-Keep the source static while exporting. The renderer waits for fonts and image
-decoding, observes source and stylesheet mutations, and checks computed styles and
-geometry across asynchronous stages. A changed source fails with `SOURCE_CHANGED`.
-Pause animations before export. Cancellation uses `signal: controller.signal` and
-rejects with the standard `AbortError`; it is cooperative between rendering
-stages. No partial PDF is returned. Temporary observers and download URLs are
-released.
-
-## Diagnostics and limits
-
-`RenderPDFError.code` distinguishes invalid options/source, missing fonts/glyphs,
-unsupported CSS/elements, failed resources, source changes/overflow, pagination,
-raster and PDF writing failures. Warnings are available through both `onWarning`
-and the immutable `result.warnings` collection, without runtime console logging.
-
-PDF text uses browser word origins and fontkit's shaped glyph advances and offsets;
-glyph outlines retain their original proportions. Default OpenType ligatures,
-kerning (including `font-kerning: none`) and combining marks retain a selectable
-Unicode text layer. Baselines still use Canvas font metrics. Nondefault font
-features/variants, stretched faces, font-size adjustment, automatic hyphenation
-and soft hyphens fail explicitly. Keep shaped words in one text node; cross-inline
-ligatures and zero-width text fragments are unsupported and reject explicitly.
-Exact output across shaping engines, arbitrary ligatures, complex scripts, bidi
-and variable font instances are not a fidelity promise. There is no arbitrary CSS/stacking
-engine, collapsed table borders, repeated table headers or header/footer engine.
-Pagination is a measured source-to-page mapping, not full CSS Paged Media: parity
-breaks (`left/right/recto/verso`), column breaks, inline/cell break directives,
-margin-break rules, widow/orphan line-count policies and cloned page decorations
-are unsupported. Nondefault native `widows`/`orphans` and
-`box-decoration-break: clone` fail explicitly. Default line-count values are not
-enforced. Unsupported visible behavior must fail rather than silently produce an
-apparently successful export.
-Direct text overlapping later visible paint is also rejected when the simple
-ordered paint list cannot reproduce the browser's block/inline paint phases.
+HTML rendering supports static blocks, inline content, nonoverlapping Flexbox and
+Grid layouts, horizontal Latin text (including Czech diacritics), solid backgrounds,
+rectangular borders and native tables with `rowspan` and `colspan`.
+
+PNG/JPEG resources can use data, blob, same-origin or CORS-readable URLs. External
+images may be fetched by the browser; documents are never sent to a conversion
+service. JPEG orientation in HTML must be absent or `1`; normalize rotated pixels
+before using them in an `<img>` element.
+
+Gradients, rounded corners, inline bitmap backgrounds, inset shadows and opacity
+can use local raster fallback on supported rectangular blocks. `data-raster`
+selects a region explicitly. Regions are captured once in paint order; descendant
+text gets an extraction layer where safe. Raster resources must be inline bitmaps;
+external resources, transforms, backdrop effects and effects outside the border
+box are unsupported. Wrapped inline backgrounds or borders require a containing
+raster region; inline and table-internal raster boundaries are unsupported.
+
+### Pagination and tables
+
+The default `pageBreak: 'css'` respects block/table-row `break-before: page`,
+`break-after: page`, their legacy `page-break-*: always` aliases and
+`break-inside: avoid/avoid-page`. Before/after avoidance keeps adjacent complete
+block siblings together when they fit.
+
+Text lines, images, raster regions, table rows and spanning cells stay whole.
+Content taller than a page, or a forced break through an indivisible item, fails
+with `PAGINATION_FAILED`. An avoid preference that cannot be honored can be relaxed
+with a `BREAK_AVOID_RELAXED` warning. Parity/column breaks, inline/cell break rules,
+widow/orphan policies and cloned page decorations are unsupported.
+
+<details>
+<summary>Table restrictions</summary>
+
+Collapsed tables support solid, none and hidden borders on cells and the outer
+table, including different widths, colors and transparency. Shared borders are
+painted once. Row, row-group, column and column-group border contributions, other
+border styles, captions, nested collapsed tables and altered table-part display
+modes are unsupported.
+
+Repeated headers require a visible native `thead` followed by body rows. The
+header reserves space on continuation pages and stays with the first body row.
+Headers and rows must fit on a page. Nested tables, raster headers, overlapping
+table ranges, header rowspans and cells spanning the header/body boundary are
+unsupported. Header paint must fit its measured box. Table footers are not repeated.
+Collapsed tables also require matching resolved horizontal borders at every
+possible header/body continuation boundary.
+
+</details>
+
+### Text and layout limits
+
+Default kerning, ligatures and combining marks are supported. Keep shaped words in
+one text node; cross-inline ligatures and zero-width fragments are unsupported.
+Complex scripts, bidirectional text, custom font features/variants, stretched
+faces, font-size adjustment, automatic hyphenation and soft hyphens are unsupported.
+Exact text appearance can vary between shaping engines.
+
+Arbitrary CSS stacking and overlapping paint are unsupported. Pause animations
+and keep source styles, geometry and registered fonts stable during export.
+Changes to the source fail with `SOURCE_CHANGED`.
+
+### Image format limits
+
+- **PNG:** static images only; APNG is rejected.
+- **JPEG:** 8-bit baseline, extended and progressive grayscale, RGB or CMYK.
+- **TIFF:** classic stripped TIFF in either byte order; common bilevel/grayscale,
+  palette and 8-bit RGB/RGBA profiles. Compression: uncompressed, CCITT RLE/Group
+  3/Group 4, LZW, PackBits and Deflate. Limited to **40 million pixels per frame**
+  and **1,000 main frames**.
+
+BigTIFF, tiled TIFF, SubIFDs/RAW layouts, planar-separated samples, 16-bit/float
+samples and JPEG-compressed TIFF fail with `UNSUPPORTED_IMAGE`. The TIFF decoder
+loads only when needed. Structural checks reject malformed input, but cannot
+identify every damaged JPEG scan or CCITT bitstream.
 
 ## Development
 
-Development requires Node.js 22.18+ on the 22.x release line, 24.11+ on 24.x, or
-26+. The `.node-version` file records the verified 22.22.0 runtime. From a source checkout:
+Use Node.js 22.18+ (22.x), 24.11+ (24.x) or 26+. `.node-version` records the
+verified runtime.
 
 ```sh
 npm ci
 npm run build
+npm run check
 ```
 
-Source code lives in `src/`. Browser regression pages live in `tests/fixtures/`;
-their measurement helpers in `experiments/` use the same rendering pipeline as
-the public API. `npm run dev` serves these fixtures for development, while
-`npm run build` builds only the library.
-
-The independent HTML editor in `playground/` installs the
-packed library as an npm dependency. It provides a live preview and PDF download
-without importing renderer source files.
-
-Vite+ provides the development server, builds, Oxlint, Oxfmt and Vitest. Shared
-lint, format and unit-test settings live in `vite.config.ts`; the library build
-uses `vite.library.config.ts` and TypeScript to generate declarations. The toolchain
-is installed locally by `npm ci`; a global Vite+ installation is optional.
-
-The playground deliberately uses one explicitly stated font family;
-the reusable API supports multiple families. Private documents and local system
-font programs belong only in ignored `artifacts/`; regression tests use synthetic
-documents and do not require them.
-
-Run `npm run check` before submitting a change. It checks types, lint, unit tests,
-browser tests, builds, formatting and package contents. Browser tests require an installed Google
-Chrome and use synthetic fixtures, Playwright and PDF.js; those tools never run in
-conversion code. Generated PDFs, screenshots and reports stay outside versioned
-source files.
-
-Typography regressions compare tight browser/PDF text crops for Noto Sans regular,
-bold and italic plus Noto Serif, including Czech accents, ligatures, kerning and
-wrapped mixed-font lines on multiple pages. The [benchmark guide](https://github.com/MichalekJan93/renderPDF.js/blob/main/BENCHMARKS.md)
-describes repeatable exports of small, medium, large and hybrid documents.
-Run `npm run benchmark` to record timings separately from correctness checks.
-GitHub Actions runs the checks and preserves rendered comparisons and timing reports.
-
-### Local package
-
-`npm pack --pack-destination artifacts` builds the library and checks its contents
-before creating a local archive. Create the `artifacts/` directory first if it is
-absent. The package includes the ESM entry, TypeScript declarations, package metadata,
-README, MIT license and README logo. Demos, test fonts, source files and local
-documents are excluded by an explicit `files` allowlist.
-
-`npm run check:package` checks the current build through npm's dry-run inventory;
-run `npm run build:library` first when no build exists. The check rejects missing
-entry points, empty files and unexpected contents. Packaging does not publish the
-library. Maintainers publish a reviewed archive with
-`npm publish ./artifacts/renderpdf-js-<version>.tgz --access public` after updating
-the package version and verifying the packed consumer.
+`npm run check` runs formatting, lint, types, unit tests, browser tests, build and
+package checks. Google Chrome must be installed for browser tests. Vite+ provides
+the development toolchain; Playwright and PDF.js are used for testing.
+
+Run `npm run dev` to serve synthetic test fixtures. The independent
+[playground](https://github.com/MichalekJan93/renderPDF.js/tree/main/playground)
+tests the packaged library. See the
+[benchmark guide](https://github.com/MichalekJan93/renderPDF.js/blob/main/BENCHMARKS.md)
+for `npm run benchmark` and timing reports.
+
+To create a local package, create `artifacts/` if needed, then run
+`npm pack --pack-destination artifacts`. Only the library build, declarations,
+package metadata, README, license and logo are packaged. Keep private documents
+and generated files out of Git.
 
 ## License
 
-RenderPDF.js is licensed under the [MIT License](LICENSE). Bundled Noto Sans and Noto Serif test
-fonts retain their [SIL Open Font License](https://github.com/MichalekJan93/renderPDF.js/blob/main/public/fonts/README.md); they are not
-bundled into the library entry. Third-party dependencies retain their own licenses.
+[MIT](https://github.com/MichalekJan93/renderPDF.js/blob/main/LICENSE).
+Third-party dependencies retain their own licenses: `utif2` uses MIT and `pako`
+retains MIT/Zlib notices. Noto Sans and Noto Serif test fonts retain the
+[SIL Open Font License](https://github.com/MichalekJan93/renderPDF.js/blob/main/public/fonts/README.md)
+and are not included in the npm package.

package/dist/api-types.d.ts

@@ -48,26 +48,85 @@ export interface CustomPageSize {
     /** Base paper height in CSS pixels, including margins. */
     height: number;
 }
-/** Small supported API surface; unsupported layout fails explicitly. */
-export interface RenderPDFOptions {
-    /** Explicit registered faces used by the supplied source; no implicit font substitution. */
-    fonts: readonly RegisteredFont[];
+/** One selectable line repeated in a reserved area above or below each page's content. */
+export interface PageTextOptions {
+    /** Plain Latin text; {pageNumber} and {pageCount} expand after pagination. */
+    text: string;
+    /** Reserved height in CSS pixels, in addition to the page's outer margins. */
+    height: number;
+    /** Exact face included in fonts; defaults to its first registered face. */
+    font?: RegisteredFont;
+    /** Text size in CSS pixels, defaulting to 12. */
+    fontSize?: number;
+    /** Horizontal alignment within the page's content width, defaulting to left. */
+    align?: 'left' | 'center' | 'right';
+}
+/** Document properties stored in the PDF, independent of visible page content. */
+export interface PDFMetadata {
+    /** Human-readable document title; defaults to RenderPDF.js when omitted. */
+    title?: string;
+    /** Author displayed in PDF document properties. */
+    author?: string;
+    /** Short description of the document's subject. */
+    subject?: string;
+    /** Search keywords copied before export begins. */
+    keywords?: readonly string[];
+}
+/** Observable export stages; counters describe work within one stage, never elapsed-time estimates. */
+export type RenderStage = 'preparing' | 'layout' | 'pagination' | 'resources' | 'pages' | 'saving' | 'complete';
+/** Immutable progress notification delivered synchronously to the application's callback. */
+export interface RenderProgress {
+    /** Current stage, in pipeline order. */
+    readonly stage: RenderStage;
+    /** Finished work units within the current stage. */
+    readonly completed: number;
+    /** Known work units in this stage; page totals are available after pagination. */
+    readonly total: number;
+}
+/** Shared physical paper settings for HTML and standalone image conversion. */
+export interface PDFPageOptions {
     /** Standard page size (default A4) or explicit physical dimensions in CSS pixels. */
     format?: 'A4' | 'A3' | 'Letter' | CustomPageSize;
     /** Page orientation, defaulting to portrait. */
     orientation?: 'portrait' | 'landscape';
     /** CSS-pixel margins, defaulting to 24 on every edge; content is never implicitly rescaled. */
     margin?: number | PageMargins;
+}
+/** Small supported API surface; unsupported layout fails explicitly. */
+export interface RenderPDFOptions extends PDFPageOptions {
+    /** Explicit registered faces used by the supplied source; no implicit font substitution. */
+    fonts: readonly RegisteredFont[];
     /** Physical pixels per CSS pixel in selected local raster regions, defaulting to 2. */
     rasterScale?: number;
     /** Automatically rasterize safe local effects (default auto); strict requires explicit data-raster. */
     fallback?: 'auto' | 'strict';
     /** Honor supported CSS page breaks (default css), or use geometry-only automatic cuts. */
     pageBreak?: 'auto' | 'css';
+    /** Repeat native THEAD groups on table continuation pages; defaults to false. */
+    repeatTableHeaders?: boolean;
+    /** Plain text vertically centered in a reserved area above the source on every page. */
+    header?: PageTextOptions;
+    /** Plain text vertically centered in a reserved area below the source on every page. */
+    footer?: PageTextOptions;
+    /** Unicode document properties; all supplied values are copied before asynchronous preparation. */
+    metadata?: PDFMetadata;
     /** Stop preparation and subsequent rendering stages without producing a partial PDF. */
     signal?: AbortSignal;
     /** Observe documented approximations, raster choices and relaxed pagination preferences. */
     onWarning?: (warning: RenderWarning) => void;
+    /** Observe stage-local work counts; the renderer yields for browser updates when provided. */
+    onProgress?: (progress: RenderProgress) => void;
+}
+/** One caller-owned image file or its complete binary bytes; the signature determines its format. */
+export type ImageSource = Blob | ArrayBuffer | Uint8Array;
+/** Convert one PNG/JPEG or all main image frames of a TIFF, without HTML or font registration. */
+export interface ImagePDFOptions extends PDFPageOptions {
+    /** Copied Unicode PDF properties. */
+    metadata?: PDFMetadata;
+    /** Cancel between input reading, frame decoding, image embedding and page writing stages. */
+    signal?: AbortSignal;
+    /** Frozen stage-local counters; image conversion omits HTML layout/pagination stages. */
+    onProgress?: (progress: RenderProgress) => void;
 }
 /** Complete PDF result with independently usable browser output forms. */
 export interface RenderPDFResult {

package/dist/diagnostics.d.ts

@@ -1,5 +1,5 @@
 /** Machine-readable failure reasons for the supported browser rendering pipeline. */
-export type RenderErrorCode = 'INVALID_OPTIONS' | 'INVALID_SOURCE' | 'FONT_LOAD_FAILED' | 'MISSING_FONT' | 'MISSING_GLYPH' | 'UNSUPPORTED_CSS' | 'UNSUPPORTED_ELEMENT' | 'RESOURCE_LOAD_FAILED' | 'SOURCE_CHANGED' | 'SOURCE_OVERFLOW' | 'PAGINATION_FAILED' | 'RASTER_FAILED' | 'PDF_WRITE_FAILED';
+export type RenderErrorCode = 'INVALID_OPTIONS' | 'INVALID_SOURCE' | 'FONT_LOAD_FAILED' | 'MISSING_FONT' | 'MISSING_GLYPH' | 'UNSUPPORTED_CSS' | 'UNSUPPORTED_ELEMENT' | 'UNSUPPORTED_IMAGE' | 'RESOURCE_LOAD_FAILED' | 'SOURCE_CHANGED' | 'SOURCE_OVERFLOW' | 'PAGINATION_FAILED' | 'RASTER_FAILED' | 'PDF_WRITE_FAILED';
 /** A rendering failure with a stable code and an actionable English explanation. */
 export declare class RenderPDFError extends Error {
     /** Stable category that callers can branch on without parsing message text. */

package/dist/export-options.d.ts

@@ -0,0 +1,12 @@
+import type { PDFMetadata } from './api-types.js';
+import type { PDFDocument } from 'pdf-lib';
+/** Validate and own metadata before the caller can mutate nested settings during an export. */
+export declare function resolveMetadata(
+/** Optional caller-owned PDF document properties. */
+value: PDFMetadata | undefined): Readonly<PDFMetadata> | undefined;
+/** Apply the same document properties for HTML and standalone image exports. */
+export declare function applyPDFMetadata(
+/** PDF document owning these Info dictionary values. */
+pdf: PDFDocument, 
+/** Validated, copied properties; omitted fields retain the shared defaults. */
+metadata: Readonly<PDFMetadata> | undefined): void;

package/dist/image-geometry.d.ts

@@ -0,0 +1,19 @@
+import type { PageGeometry } from './api-types.js';
+/** Bound per-frame decoding allocations while allowing typical 600-DPI A4 scans. */
+export declare const MAX_IMAGE_PIXELS = 40000000;
+/** Reject invalid and excessive dimensions before a decoder allocates pixel buffers. */
+export declare function assertImageSize(
+/** Encoded pixel width, before orientation. */
+width: number, 
+/** Encoded pixel height, before orientation. */
+height: number): void;
+/** Fit and orient an image's unit square inside the page, returning a CSS-pixel PDF matrix. */
+export declare function imagePlacement(
+/** Original encoded image width. */
+width: number, 
+/** Original encoded image height. */
+height: number, 
+/** TIFF/EXIF orientation, including mirrored variants. */
+orientation: number, 
+/** Physical page with validated margins. */
+page: PageGeometry): [number, number, number, number, number, number];