renderpdf-js 0.1.0 → 0.2.0

package/README.md

@@ -4,10 +4,12 @@
 
 # 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.
+An open-source TypeScript library for converting HTML/CSS and standalone images
+to PDF in the browser. HTML exports retain selectable text, local raster fallbacks
+and automatic pagination. The browser calculates HTML layout; RenderPDF.js uses
+its measured text, box, image and table coordinates to write the PDF. Standalone
+PNG/JPEG and multipage TIFF files use a separate image API. Conversion runs
+entirely on the client.
 
 The renderer is experimental and supports the bounded subset described below.
 Chromium is the verified browser; Firefox/Safari compatibility has not been
@@ -21,12 +23,68 @@ Install the library in a browser application with a bundler, such as Vite:
 npm install renderpdf-js
 ```
 
-The package provides an ESM entry and TypeScript declarations. Version 0.1.x is
+The package provides an ESM entry and TypeScript declarations. Version 0.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).
 
-## Usage
+## Standalone image files
+
+`imageToPDF` is available from version 0.2.0. It accepts one `File`/`Blob`, `ArrayBuffer` or
+`Uint8Array`; actual file signatures determine the format, not filenames or MIME
+labels. No HTML element or registered fonts are needed.
+
+```ts
+import { imageToPDF } from 'renderpdf-js';
+
+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,
+  metadata: { title: 'Scanned document' },
+  onProgress: ({ stage, completed, total }) => {
+    statusElement.textContent = `${stage}: ${completed}/${total}`;
+  },
+});
+await pdf.download('document.pdf');
+```
+
+PNG/JPEG produce one PDF page. Every main linked TIFF frame produces its own page
+in file order. Images fit completely inside the selected paper's margins, retain
+their aspect ratio and are centered; fitting can enlarge a small image. The
+defaults are A4 portrait and 24 CSS-pixel margins. A3, Letter, landscape,
+asymmetric margins and custom paper sizes use the same settings as HTML exports.
+TIFF/EXIF orientations 1–8, including mirrored orientations and PNG `eXIf`, are
+applied when painting the page. JPEG compressed bytes remain unchanged.
+
+The result has the same `pageCount`, `download()`, `toBlob()` and
+`toUint8Array()` methods as HTML exports. Image text remains part of the bitmap;
+this API does not perform OCR. Metadata and mutable input bytes are copied before
+the first asynchronous stage. Cancellation uses `signal`. Progress stages are
+`preparing`, `resources`, `pages`, `saving` and `complete`; image conversion does
+not emit HTML layout/pagination stages. Resource/page totals equal the number of
+image frames. A failed or canceled conversion returns no partial PDF.
+
+Supported TIFF input is classic TIFF with strips and either byte order, using
+uncompressed, CCITT RLE/Group 3/Group 4, LZW, PackBits or Deflate compression.
+The bounded decoder supports common bilevel/grayscale, palette and 8-bit RGB/RGBA
+profiles, including associated alpha normalization. Other modes, including
+BigTIFF, tiles, SubIFDs/RAW layouts, planar-separated samples, 16-bit/float samples
+and JPEG-compressed TIFF, fail with `UNSUPPORTED_IMAGE`. Frames are limited to
+40 million pixels each and TIFF files to 1,000 main frames. PNG must be static;
+APNG is rejected explicitly. JPEG supports 8-bit baseline/extended/progressive
+grayscale, RGB and CMYK frames.
+
+Malformed headers, checksums and out-of-file offsets are rejected. JPEG entropy
+validation and detection of every corrupt CCITT bitstream remain decoder-limited;
+structural checks do not prove that every damaged scan is recoverable. TIFF
+pixels are decoded one frame at a time with the MIT-licensed `utif2` dependency,
+which loads only when TIFF decoding is requested. The HTML `<img>` pipeline still
+accepts native PNG/JPEG resources; standalone TIFF support does not change it.
+
+## HTML usage
 
 Import the public API from the installed package in your application's browser entry:
 
@@ -80,6 +138,93 @@ 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.
 
+### Repeated table headers and page text
+
+Repeated table headers and page text are available from version 0.2.0.
+
+```ts
+const pdf = await renderPDF(source, {
+  fonts: [regular],
+  margin: 24,
+  repeatTableHeaders: true,
+  header: { text: 'Account statement', height: 32, fontSize: 12 },
+  footer: {
+    text: 'Page {pageNumber} of {pageCount}',
+    height: 28,
+    fontSize: 11,
+    align: 'right',
+  },
+});
+await pdf.download('statement.pdf');
+```
+
+`repeatTableHeaders` defaults to `false`, preserving existing exports. Enabling it
+repeats native `thead` paint and selectable text on continuation pages of a table.
+The header's measured height and spacing reduce the available body space on those
+pages. The original header stays together with the first body row. Body rows and
+spanning cells remain indivisible; a header and row that cannot fit fail with
+`PAGINATION_FAILED`. Repeated headers require nonnested native tables with a
+visible `thead` followed by body rows; raster headers, overlapping table ranges,
+header rowspans and cells spanning the header/body boundary are unsupported. Table footers are
+not repeated.
+Header paint must fit inside the measured `thead` box; text overflowing into its
+surrounding spacing fails explicitly instead of being clipped on continuation pages.
+
+`header` and `footer` each reserve their required `height` in CSS pixels **in
+addition to** the page's outer margins. They accept one plain Latin text line,
+including Czech diacritics, with `{pageNumber}` and `{pageCount}` placeholders.
+The text is black, vertically centered, and remains selectable. `fontSize`
+defaults to 12 CSS pixels and `align` to `'left'`; `'center'` and `'right'` are
+also supported. `font` can select a registered handle included in `fonts`, and
+otherwise defaults to the first supplied face. Band text never wraps or shrinks
+silently: text that exceeds its reserved height or available width fails with
+`SOURCE_OVERFLOW`. Invalid settings or bands leaving no content area fail with
+`INVALID_OPTIONS`. HTML templates and per-page callbacks are not supported.
+
+### Export progress and document properties
+
+Progress reporting and document properties are available from version 0.2.0.
+
+```ts
+const pdf = await renderPDF(source, {
+  fonts: [regular],
+  metadata: {
+    title: 'Account statement',
+    author: 'Example Company',
+    subject: 'Quarterly overview',
+    keywords: ['statement', 'quarterly'],
+  },
+  onProgress: ({ stage, completed, total }) => {
+    // Keep the status element outside the document being exported.
+    statusElement.textContent = `${stage}: ${completed}/${total}`;
+  },
+});
+await pdf.download('statement.pdf');
+```
+
+Progress events are frozen records with `stage`, `completed` and `total` fields.
+Stages are `preparing`, `layout`, `pagination`, `resources`, `pages`, `saving`
+and `complete`, in that order. Counters describe work **within the current stage**,
+not elapsed-time percentages. Preparation, layout, pagination and saving use one
+work unit; resources count font programs and processed native image/raster
+references, including reused image references. The page stage counts finished
+physical pages; its total is known after pagination. A successful export ends
+with `{ stage: 'complete', completed: 1, total: 1 }` after source validation.
+
+Providing `onProgress` allows periodic browser task yields so status updates and
+cancellation can run during export. Without it, conversion adds no progress
+timers. Callbacks are synchronous notifications; thrown callback errors reject
+the export with the original error. Keep the source static during callbacks as
+well as asynchronous rendering. Cancellation continues to use `signal` and the
+standard `AbortError`, with no partial PDF returned.
+
+`metadata` accepts optional Unicode `title`, `author`, `subject` and `keywords`
+properties. The keywords value is an array of strings. Settings and keyword
+entries are copied before the first asynchronous stage; later caller edits do
+not alter the current PDF. Invalid runtime values fail with `INVALID_OPTIONS`.
+The default title remains `RenderPDF.js`. Metadata does not add visible page
+content or change font requirements.
+
 ## Supported scope
 
 - Static block, inline, nonoverlapping Flexbox and Grid geometry with horizontal
@@ -90,8 +235,9 @@ TTF/OTF instances. Do not remove or replace registered browser faces during use.
   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.
+- Legacy `FONT`, `CENTER` and native tables with separate or collapsed borders.
+  Collapsed borders are available from version 0.2.0. 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.
@@ -116,6 +262,23 @@ TTF/OTF instances. Do not remove or replace registered browser faces during use.
   adjacent complete block siblings together when they fit. `pageBreak: 'auto'`
   ignores authored fragmentation hints and uses only measured atomic geometry.
 
+Collapsed tables support cell and outer-table borders with `solid`, `none` and
+`hidden` styles, including different widths/colors on each side, transparency,
+`rowspan` and `colspan`. Shared edges resolve conflicts before native painting:
+hidden suppresses a border, otherwise the wider solid candidate wins; cells
+outrank the table on equal widths, followed by the upper/left cell in LTR layout.
+Crossing fills are partitioned so transparency is not applied twice. Original
+browser column widths and selectable text are retained; no table screenshot is
+used. Outer borders stay with the first/last complete rows during pagination.
+
+Collapsed row, row-group, column and column-group border contributions, other
+border styles, nested collapsed tables, captions and altered native table-part
+display modes fail explicitly. Keep these contributions on cells or the table
+itself. Repeated headers on collapsed tables additionally require the same
+resolved horizontal border segments, widths and colors at every possible body
+continuation boundary; incompatible combinations fail with `UNSUPPORTED_CSS`.
+Repeated headers on tables with separate borders retain their existing scope.
+
 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.
@@ -149,7 +312,8 @@ and soft hyphens fail explicitly. Keep shaped words in one text node; cross-inli
 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.
+engine. Collapsed tables, repeated table headers and plain page text
+use the explicit options described above; arbitrary HTML page templates are unsupported.
 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
@@ -219,6 +383,8 @@ the package version and verifying the packed consumer.
 
 ## License
 
-RenderPDF.js is licensed under the [MIT License](LICENSE). Bundled Noto Sans and Noto Serif test
+RenderPDF.js is licensed under the [MIT License](LICENSE). The TIFF decoder
+`utif2` retains its MIT license; its `pako` dependency retains its MIT/Zlib notices.
+Runtime dependencies remain external to the library bundle. 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.

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];

package/dist/image-input.d.ts

@@ -0,0 +1,19 @@
+/** Validated native bitmap geometry; orientation transforms are applied by the PDF adapter. */
+export interface BitmapInfo {
+    /** Actual compressed format, independent of the filename and MIME type. */
+    format: 'png' | 'jpeg';
+    /** Encoded pixel width before EXIF rotation. */
+    width: number;
+    /** Encoded pixel height before EXIF rotation. */
+    height: number;
+    /** Standard EXIF orientation, defaulting to one when absent. */
+    orientation: number;
+}
+/** Inspect PNG/JPEG bytes without a DOM, mutation, implicit file-type guessing or pixel allocation. */
+export declare function inspectBitmap(bytes: Uint8Array): BitmapInfo;
+/** Validate PNG's complete zlib stream and row layout before pdf-lib's permissive raw inflater. */
+export declare function validatePngData(
+/** Owned PNG bytes; filenames and MIME types never establish their validity. */
+bytes: Uint8Array, 
+/** Optional cancellation released together with the native reader. */
+signal?: AbortSignal): Promise<void>;

package/dist/image-pdf.d.ts

@@ -0,0 +1,7 @@
+import type { ImagePDFOptions, ImageSource, RenderPDFResult } from './api-types.js';
+/** Convert one standalone PNG/JPEG or every main TIFF frame to an immutable PDF result. */
+export declare function imageToPDF(
+/** Complete image bytes or browser File/Blob; filenames and MIME types do not determine decoding. */
+source: ImageSource, 
+/** Shared paper settings, metadata, cancellation and optional stage-local progress. */
+options?: ImagePDFOptions): Promise<RenderPDFResult>;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { renderPDF } from './render-pdf.js';
+export { imageToPDF } from './image-pdf.js';
 export { registerFont } from './fonts.js';
 export { RenderPDFError } from './diagnostics.js';
 export type { RenderErrorCode, RenderWarning } from './diagnostics.js';
-export type { FontSource, RegisteredFont, PageMargins, CustomPageSize, RenderPDFOptions, RenderPDFResult, } from './api-types.js';
+export type { FontSource, RegisteredFont, PageMargins, PDFPageOptions, ImageSource, ImagePDFOptions, CustomPageSize, PageTextOptions, PDFMetadata, RenderStage, RenderProgress, RenderPDFOptions, RenderPDFResult, } from './api-types.js';