renderpdf-js 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Michálek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,224 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/MichalekJan93/renderPDF.js/main/assets/renderpdf-logo.png" alt="RenderPDF.js logo" width="560" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 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.
+
+The renderer is experimental and supports the bounded subset described below.
+Chromium is the verified browser; Firefox/Safari compatibility has not been
+established.
+
+## Getting started
+
+Install the library in a browser application with a bundler, such as Vite:
+
+```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).
+
+## Usage
+
+Import the public API from the installed package in your application's browser entry:
+
+```ts
+import { registerFont, renderPDF, RenderPDFError } from 'renderpdf-js';
+
+// Fetch a licensed static TTF/OTF program owned by the 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;
+}
+```
+
+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.
+
+## 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.
+
+## 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:
+
+```sh
+npm ci
+npm run build
+```
+
+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.
+
+## 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.

package/dist/api-types.d.ts

@@ -0,0 +1,84 @@
+import type { RenderWarning } from './diagnostics.js';
+/** One explicit static font program registered for browser layout and PDF embedding. */
+export interface RegisteredFont {
+    /** CSS family name; provide the same family in the source element's styles. */
+    readonly family: string;
+    /** Explicit CSS weight of this static face, without browser-synthesized styling. */
+    readonly weight: number;
+    /** Supported face style. */
+    readonly style: 'normal' | 'italic';
+    /** Exact font bytes; registration owns its program rather than extracting system fonts. */
+    readonly bytes: Uint8Array;
+}
+/** Input for explicit font registration; bytes are supplied by the application. */
+export interface FontSource {
+    /** CSS family to register in the current document. */
+    family: string;
+    /** Complete TTF/OTF program available to the browser and PDF adapter. */
+    data: Uint8Array | ArrayBuffer;
+    /** Static face weight, defaulting to 400. */
+    weight?: number;
+    /** Static face style, defaulting to normal. */
+    style?: 'normal' | 'italic';
+}
+/** Physical page and source-to-page margins in CSS reference pixels. */
+export interface PageGeometry {
+    /** Page width in CSS reference pixels (1px = 0.75pt). */
+    width: number;
+    /** Page height in CSS reference pixels. */
+    height: number;
+    /** Empty page edges in CSS pixels. */
+    margin: PageMargins;
+}
+/** Per-edge empty page space, measured in CSS pixels. */
+export interface PageMargins {
+    /** Top empty edge. */
+    top: number;
+    /** Right empty edge. */
+    right: number;
+    /** Bottom empty edge. */
+    bottom: number;
+    /** Left empty edge. */
+    left: number;
+}
+/** Explicit physical paper dimensions in the shared CSS reference pixel units. */
+export interface CustomPageSize {
+    /** Base paper width in CSS pixels; landscape orientation swaps the supplied axes. */
+    width: number;
+    /** 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[];
+    /** 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;
+    /** 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';
+    /** 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;
+}
+/** Complete PDF result with independently usable browser output forms. */
+export interface RenderPDFResult {
+    /** Number of generated pages. */
+    readonly pageCount: number;
+    /** Frozen diagnostics for this export; there is no production console logging. */
+    readonly warnings: readonly RenderWarning[];
+    /** Return a fresh byte copy so callers cannot corrupt future downloads. */
+    toUint8Array(): Promise<Uint8Array>;
+    /** Return a browser PDF Blob without triggering a download. */
+    toBlob(): Promise<Blob>;
+    /** Download the completed PDF without invoking a print dialog. */
+    download(filename?: string): Promise<void>;
+}

package/dist/breaks.d.ts

@@ -0,0 +1,7 @@
+import type { LayoutSnapshot } from './types.js';
+/** Collect the supported CSS page-break subset from existing measured browser geometry. */
+export declare function collectPageBreaks(
+/** Connected current-document root; collection leaves its source DOM unchanged. */
+root: HTMLElement, 
+/** Ordered display list identifying intrinsic raster boundaries and source extent. */
+snapshot: LayoutSnapshot): Pick<LayoutSnapshot, 'forcedBreaks' | 'avoidBreakBounds'>;

package/dist/diagnostics.d.ts

@@ -0,0 +1,26 @@
+/** 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';
+/** 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. */
+    readonly code: RenderErrorCode;
+    /** Construct an error without hiding its original lower-level cause. */
+    constructor(
+    /** Stable category that callers can branch on without parsing message text. */
+    code: RenderErrorCode, 
+    /** Human-readable explanation of the failed requirement. */
+    message: string, 
+    /** Optional original browser or adapter failure. */
+    options?: ErrorOptions);
+}
+/** Supported approximations and explicit local raster choices, reported without console noise. */
+export interface RenderWarning {
+    /** Stable warning category for application diagnostics. */
+    readonly code: 'TEXT_METRICS_APPROXIMATED' | 'RASTER_FALLBACK' | 'RASTER_TEXT_OMITTED' | 'BREAK_AVOID_RELAXED';
+    /** Explanation of the behavior and its relevant fidelity limit. */
+    readonly message: string;
+}
+/** Stop at asynchronous stage boundaries using the browser's standard AbortError contract. */
+export declare function throwIfAborted(
+/** Optional caller cancellation signal. */
+signal?: AbortSignal): void;

package/dist/fonts.d.ts

@@ -0,0 +1,9 @@
+import type { FontSource, RegisteredFont } from './api-types.js';
+/** Validate immutable registration handles against the current browser's live font set.
+ * @param fonts Explicit handles whose owned programs must still control browser font selection.
+ */
+export declare function validateRegisteredFonts(fonts: readonly RegisteredFont[]): void;
+/** Register explicit static TTF/OTF bytes in the current browser document.
+ * @param source Caller-supplied program and its exact CSS family, weight, and style.
+ */
+export declare function registerFont(source: FontSource): Promise<RegisteredFont>;

package/dist/images.d.ts

@@ -0,0 +1,4 @@
+/** Identify native bitmap bytes and reject unsupported or ambiguous JPEG orientation. */
+export declare function nativeImageFormat(
+/** Original browser-accessible compressed image; no filename or MIME type is trusted. */
+bytes: Uint8Array): 'png' | 'jpeg';

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { renderPDF } from './render-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';