renderpdf-js 0.2.1 → 0.3.0

package/API.md

@@ -0,0 +1,204 @@
+# Document API
+
+RenderPDF.js provides three ways to create a PDF: `renderPDF()` for supported HTML,
+`imageToPDF()` for image files, and `createDocument()` for programmatic drawing.
+All return or finalize into the same immutable `RenderPDFResult` with `pageCount`,
+`warnings`, `toBlob()`, `toUint8Array()` and `download()`.
+
+## Documents and fonts
+
+```ts
+import { createDocument } from 'renderpdf-js';
+
+const response = await fetch('/fonts/ReportSans-Regular.ttf');
+if (!response.ok) throw new Error('The font could not be loaded.');
+
+const document = await createDocument({
+  unit: 'mm',
+  format: 'A4',
+  fonts: [{ family: 'Report Sans', data: await response.arrayBuffer() }],
+  metadata: { title: 'Report' },
+});
+const page = document.addPage();
+page.drawText('Příliš žluťoučký kůň', {
+  x: 15,
+  y: 25,
+  font: 'Report Sans',
+  fontSize: 12,
+});
+await (await document.toResult()).download('report.pdf');
+```
+
+`createDocument()` is asynchronous because it prepares fonts. Drawing and
+measurement are synchronous afterwards, except `drawImage()` and `appendPDF()`,
+which must be awaited. The document API does not require a browser or font
+registration in the DOM. Use `registerFont()` separately for HTML exports.
+
+| Setting       | Default                 | Meaning                                                                       |
+| ------------- | ----------------------- | ----------------------------------------------------------------------------- |
+| `unit`        | `'pt'`                  | `'pt'`, `'mm'` or `'px'` for coordinates and dimensions.                      |
+| `format`      | `'A4'`                  | `'A4'`, `'A3'`, `'Letter'` or `{ width, height }` in document units.          |
+| `orientation` | `'portrait'`            | Landscape swaps the supplied base axes.                                       |
+| `fonts`       | Standard PDF fonts      | Static TTF/OTF programs with `family`, `data`, optional `weight` and `style`. |
+| `metadata`    | Title: `'RenderPDF.js'` | Unicode title, author, subject and keyword strings.                           |
+| `signal`      | —                       | Cooperative cancellation via `AbortSignal`.                                   |
+
+Coordinates start at the top-left. Text `y` is a **baseline**, while rectangle and
+image `y` is a top edge. Font sizes always use **points**, independent of `unit`.
+`1 mm = 72/25.4 pt`; `1 px = 0.75 pt`. Rotation uses clockwise degrees.
+
+Helvetica, Times and Courier include regular, bold, italic and bold-italic faces.
+Their character sets are limited. For Czech and other Unicode text, provide an
+appropriate font program. Select an exact face using `font`, `fontWeight` and
+`fontStyle`; missing fonts and glyphs fail explicitly. Fonts are not substituted.
+
+## Page management
+
+`addPage(options?)` returns a page handle. It inherits document defaults; each page
+can override its format and orientation. Documents start without an implicit page.
+
+- `getPage(number)` and `getPages()` return existing handles in document order.
+- `pageCount` reports the number of physical pages.
+- `insertPage(number, options?)` inserts before a one-based position.
+- `movePage(from, to)` reorders an existing page.
+- `removePage(number)` removes an unreferenced page. Bookmark/link targets and
+  pages containing interactive fields cannot be removed; flatten fields first.
+- `appendPDF(source, pageNumbers?)` imports supported native pages asynchronously.
+- `addBookmark(title, { pageNumber, parent? })` creates a hierarchical page bookmark.
+- `flattenForms()` replaces prepared form appearances with ordinary page content.
+- `toResult()` finalizes once and reuses the completed result on later calls.
+
+Page handles expose `width`, `height`, `rotation` and `setRotation(degrees)`.
+Drawing coordinates are relative to the unrotated MediaBox; imported page origins
+and `UserUnit` are normalized into physical document units. Crop boxes and view
+rotation remain part of the page.
+Page numbers are one-based. Removed handles cannot be drawn into. Bookmarks remain
+attached to the same page when pages move. A finalized document cannot be edited.
+
+## Text, graphics and images
+
+`document.measureText(text, options?)` returns `width`, `height`, `ascent` and
+`descent` in document units, using the same exact font as drawing.
+
+| Page method                  | Input                                                                                                                            |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `drawText(text, options)`    | `x`, baseline `y`; optional font face, `fontSize`, `color`, `align`, `lineHeight`, `rotation`, `maxWidth`, `opacity` and `link`. |
+| `drawLine(options)`          | `x1`, `y1`, `x2`, `y2`; optional `color`, `width`, `opacity`.                                                                    |
+| `drawRectangle(options)`     | `x`, `y`, `width`, `height` and paint settings.                                                                                  |
+| `drawEllipse(options)`       | Bounding rectangle and paint settings.                                                                                           |
+| `drawCircle(options)`        | Center `x`, `y`, `radius` and paint settings.                                                                                    |
+| `drawSvgPath(path, options)` | SVG path data, `x`, `y`, optional `scale`, `rotation` and paint settings.                                                        |
+| `drawImage(source, options)` | PNG/JPEG bytes, Blob, data URL, browser canvas/image; rectangle and optional rotation/opacity. **Await this call.**              |
+
+Paint settings are `fill`, `stroke`, `strokeWidth` and `opacity`. Colors accept
+hexadecimal, `rgb()`/`rgba()` and common named colors. Unsupported colors fail
+explicitly. Text line spacing defaults to `1.15` times the point size.
+`drawSvgPath` draws native vector geometry; it does not interpret full SVG files.
+Image placement uses the supplied rectangle and applies image orientation. For
+multipage TIFF, use `imageToPDF()` and append its PDF result.
+
+Paths use `moveTo()`, `lineTo()`, `curveTo()` and `closePath()`, followed by
+`stroke()`, `fill()` or `fillAndStroke()`. `clip()` intersects the clip with the
+current path; `discardPath()` ends the path afterwards. `clipRectangle()` combines
+these steps. Use `saveGraphicsState()` and `restoreGraphicsState()` to bound
+clipping and `transform([a,b,c,d,e,f])` changes.
+
+Pending images, unfinished paths and unmatched graphics states prevent
+finalization. Await each asynchronous image before further drawing on that page.
+
+## Links, notes and forms
+
+```ts
+page.addLink('https://example.com/report', { x: 15, y: 10, width: 100, height: 20 });
+page.addNote('Please review this value.', { x: 150, y: 30, width: 8, height: 8 });
+page.addTextField(
+  'name',
+  { x: 15, y: 50, width: 100, height: 12 },
+  {
+    value: 'Český text',
+    font: 'Report Sans',
+    fontSize: 12,
+  },
+);
+page.addCheckBox('approved', { x: 15, y: 70, width: 6, height: 6 }, { checked: true });
+page.addDropdown('status', { x: 15, y: 90, width: 60, height: 12 }, ['Draft', 'Approved'], {
+  value: 'Draft',
+});
+```
+
+Field options include font face, `fontSize`, `textColor`, `borderColor`,
+`backgroundColor`, `borderWidth`, `readOnly` and `required`. Text fields support
+`multiline` and `maxLength`; dropdowns support `editable` and `multiselect`.
+Field names must be unique. Supply a suitable font for Unicode appearances.
+Fields are axis-aligned and reject nonidentity graphics transforms.
+Field appearance colors must be opaque.
+Links accept HTTP, HTTPS, mailto and telephone URLs; executable schemes are rejected.
+
+For a left/right footer, draw independent text objects after the page count is known:
+
+```ts
+for (const [index, output] of document.getPages().entries()) {
+  output.drawText('Printed by: Example', { x: 15, y: output.height - 8, fontSize: 8 });
+  output.drawText(`Page ${index + 1} of ${document.pageCount}`, {
+    x: output.width - 15,
+    y: output.height - 8,
+    fontSize: 8,
+    align: 'right',
+  });
+}
+```
+
+## PDF composition
+
+`mergePDFs(sources, options?)` creates one PDF in source/page order.
+`extractPDFPages(source, pageNumbers, options?)` preserves the requested one-based
+order, including repeats. `splitPDF(source, options?)` returns one result per page.
+Inputs accept `File`/`Blob`, `ArrayBuffer`, `Uint8Array` and completed export results;
+the application fetches URLs itself. Options support `metadata`, `signal` and
+`onProgress` with stage-local counters.
+
+Pages retain text, vectors, image resources, sizes, crop boxes and rotation.
+Explicit internal page links are remapped to the new page references. Named
+destinations, links to omitted pages, encrypted/malformed PDFs and interactive
+AcroForm/XFA inputs fail explicitly. Flatten fields before composition.
+Document-level outlines, signatures, attachments and original metadata are not copied.
+Composition is limited to 1,000 pages, 128 MiB per input and 256 MiB total input.
+
+## DevExtreme adapter
+
+```ts
+import { createJsPDFAdapter } from 'renderpdf-js';
+import { exportDataGrid } from 'devextreme/pdf_exporter';
+
+const doc = await createJsPDFAdapter({
+  unit: 'mm',
+  format: 'A4',
+  orientation: 'landscape',
+  fonts: [{ family: 'Report Sans', data: fontBytes }],
+});
+doc.setFont('Report Sans');
+await exportDataGrid({ jsPDFDocument: doc, component: grid, selectedRowsOnly: true });
+await doc.save('grid.pdf');
+```
+
+The adapter is verified with DevExtreme 25.1.5. Its default unit is
+`'mm'`, and it creates an initial page. Font metrics and drawing methods are
+synchronous; ordered operations are flushed during asynchronous finalization.
+Use `await doc.output('blob')`, `await doc.toBlob()` or `await doc.save(name)`.
+Synchronous jsPDF output is not emulated. Fonts must be supplied to the factory;
+VFS/runtime font registration and arbitrary jsPDF plugins are unsupported.
+
+Supported methods include page selection/addition, font and color state, text
+measurement/wrapping, text/line/rectangle/image drawing, clipping, graphics-state
+save/restore and the exporter's unit/color compatibility properties. The adapter
+does not expose all jsPDF APIs or its advanced scripting features.
+
+Run the optional integration against your separately installed DevExtreme:
+
+```sh
+# Set RENDERPDF_DEVEXTREME_DIR to the absolute installed devextreme package directory.
+npm run test:devextreme
+```
+
+The regular checks do not require DevExtreme. Its implementation is not copied
+into RenderPDF.js, and it is not a runtime or development dependency of the package.

package/README.md

@@ -4,25 +4,35 @@
 
 # RenderPDF.js
 
-**Convert HTML, PNG, JPEG and multipage TIFF to PDF in the browser.**
+**Create PDFs from HTML, images or code, and merge or split existing PDFs.**
 
 [![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)
 
+RenderPDF.js is a JavaScript and TypeScript library for creating PDF documents,
+converting HTML and images, and working with existing PDF pages. It runs locally,
+without a conversion server.
+
 HTML exports use the browser's layout, keep text selectable and split content
-across pages. Conversion runs locally, without a conversion server.
+across pages. Document creation and PDF composition also work in Node.js,
+without a DOM.
 
-**Experimental.** Chromium is the verified browser. Firefox and Safari have not
-been verified. HTML rendering supports the [subset described below](#supported-scope).
+**Experimental.** HTML rendering is verified in Chromium; Firefox and Safari have
+not been verified. Supported HTML and CSS are [described below](#supported-scope).
 
 ## Features
 
-- 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.
+- Create documents with text, images, vector graphics, links and form fields.
+- Merge PDFs, extract selected pages and split documents without rasterizing them.
+- Export supported HTML/CSS with selectable text and automatic pagination.
+- Convert PNG/JPEG and multipage TIFF files to PDF.
+- Add repeated table headers, page text, page numbers and document properties.
+- Use the DevExtreme PDF exporter through an optional compatibility adapter.
+- ESM package with TypeScript declarations, cancellation and conversion progress.
+
+See the [API guide](https://github.com/MichalekJan93/renderPDF.js/blob/main/API.md)
+for methods, coordinate conventions and compatibility limits.
 
 ## Getting started
 
@@ -30,10 +40,61 @@ been verified. HTML rendering supports the [subset described below](#supported-s
 npm install renderpdf-js
 ```
 
-Use the package in a browser application with an ESM bundler, such as Vite.
+For browser applications, use 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.
 
+## Create a document
+
+```ts
+import { createDocument } from 'renderpdf-js';
+
+const document = await createDocument({ unit: 'mm', format: 'A4' });
+const page = document.addPage();
+page.drawText('Invoice', { x: 20, y: 25, fontSize: 18 });
+page.drawRectangle({ x: 20, y: 35, width: 170, height: 20, stroke: '#333333' });
+
+const pdf = await document.toResult();
+await pdf.download('invoice.pdf');
+```
+
+Coordinates start at the top-left; text `y` is its baseline. Font sizes always use
+points. The document API works without a DOM. Built-in Helvetica, Times and Courier
+cover basic text; provide static TTF/OTF bytes in `fonts` for Czech and other Unicode
+characters. Fonts are prepared before drawing. After `toResult()`, the document is
+immutable.
+
+Use `pdf.toUint8Array()` or `pdf.toBlob()` outside the browser; `download()` is a
+browser action.
+
+## Combine and split PDFs
+
+```ts
+import { mergePDFs, extractPDFPages, splitPDF } from 'renderpdf-js';
+
+const combined = await mergePDFs([firstFile, secondFile]);
+await combined.download('combined.pdf');
+
+const selected = await extractPDFPages(firstFile, [3, 1]);
+const individualPages = await splitPDF(firstFile);
+```
+
+Inputs can be `File`/`Blob`, `ArrayBuffer`, `Uint8Array` or a completed export result.
+Page numbers are one-based. Pages retain their native text, vectors, sizes and
+rotation. Flatten interactive forms before importing them; encrypted PDFs and
+unsupported destinations fail explicitly. Document-level bookmarks, signatures and
+metadata are not merged. See the [composition limits](https://github.com/MichalekJan93/renderPDF.js/blob/main/API.md#pdf-composition).
+
+## DevExtreme integration
+
+`createJsPDFAdapter()` provides the synchronous drawing and text measurement
+contract used by the DevExtreme PDF exporter. Supply fonts when creating it, pass
+the result as `jsPDFDocument`, then **await** `save()` or `output('blob')`.
+The adapter covers the tested exporter contract; it does not emulate every jsPDF
+plugin or its synchronous serialization. The [API guide](https://github.com/MichalekJan93/renderPDF.js/blob/main/API.md#devextreme-adapter)
+includes an example and the optional integration test command. DevExtreme is not
+a dependency of this library.
+
 ## HTML usage
 
 Register a font, select an existing element and export it:

package/dist/compose-pdf.d.ts

@@ -0,0 +1,26 @@
+import { PDFDocument } from 'pdf-lib';
+import type { PDFPage } from 'pdf-lib';
+import type { PDFMetadata, RenderPDFResult, RenderProgress } from './api-types.js';
+/** An existing PDF or an immutable export result; URLs are fetched by the application. */
+export type PDFSource = Blob | ArrayBuffer | Uint8Array | Pick<RenderPDFResult, 'toUint8Array'>;
+/** Shared metadata and cooperative cancellation for native page composition. */
+export interface PDFCompositionOptions {
+    /** Properties of the new document; source document metadata is not merged. */
+    metadata?: PDFMetadata;
+    /** Cancel between loading, page copying and serialization stages. */
+    signal?: AbortSignal;
+    /** Frozen stage-local counters, using preparing/resources/pages/saving/complete. */
+    onProgress?: (progress: RenderProgress) => void;
+}
+/** Share strict PDF input loading with the document builder; not a public entry-point export. */
+export declare function loadPDFSource(source: PDFSource, signal?: AbortSignal): Promise<PDFDocument>;
+/** Reuse validated native page copying and local navigation in the document builder. */
+export declare function appendPDFPages(target: PDFDocument, donor: PDFDocument, pageNumbers?: readonly number[], signal?: AbortSignal): Promise<readonly PDFPage[]>;
+/** Merge native pages in source order, preserving text, vectors, dimensions and rotation.
+ * Interactive forms must be flattened. Document-level outlines, signatures and attachments are not copied.
+ */
+export declare function mergePDFs(sources: readonly PDFSource[], options?: PDFCompositionOptions): Promise<RenderPDFResult>;
+/** Copy selected one-based pages in caller order; repeated numbers produce repeated pages. */
+export declare function extractPDFPages(source: PDFSource, pageNumbers: readonly number[], options?: PDFCompositionOptions): Promise<RenderPDFResult>;
+/** Split into one PDF per page; cross-page links require a multi-page extraction instead. */
+export declare function splitPDF(source: PDFSource, options?: PDFCompositionOptions): Promise<readonly RenderPDFResult[]>;

package/dist/document-colors.d.ts

@@ -0,0 +1,8 @@
+import type { RGB } from 'pdf-lib';
+/** Color components and alpha stay separate so native PDF paint retains transparency. */
+export interface DocumentColor {
+    color: RGB;
+    opacity: number;
+}
+/** Parse portable CSS hex/rgb colors without relying on a browser document. */
+export declare function parseDocumentColor(value: string): DocumentColor;

package/dist/document-page.d.ts

@@ -0,0 +1,115 @@
+import type { PDFPage } from 'pdf-lib';
+import type { DocumentCheckBoxOptions, DocumentDropdownOptions, DocumentImageOptions, DocumentImageSource, DocumentLineOptions, DocumentPageContext, DocumentRectangle, DocumentShapeOptions, DocumentTextFieldOptions, DocumentTextOptions } from './document-types.js';
+/** Six coefficients map top-left document coordinates to transformed document coordinates. */
+type Matrix = readonly [number, number, number, number, number, number];
+/** Native drawing surface; asynchronous image calls must finish before later drawing. */
+export declare class PDFPageBuilder {
+    private readonly page;
+    private readonly context;
+    /** Path and graphics state are tracked because PDF readers otherwise accept accidental leakage. */
+    private pathOpen;
+    private pendingImages;
+    private matrix;
+    private readonly stack;
+    private readonly userUnit;
+    private readonly scale;
+    /** The owning document supplies registered fonts, units and finalization/cancellation checks. */
+    constructor(page: PDFPage, context: DocumentPageContext);
+    /** Physical page width in document units. */
+    get width(): number;
+    /** Physical page height in document units. */
+    get height(): number;
+    /** Reader-facing page rotation does not change its unrotated drawing coordinates. */
+    get rotation(): number;
+    /** Rotate the completed page view by an integral number of quarter turns. */
+    setRotation(angle: number): this;
+    /** Guard both finalization and paint order before a synchronous operation changes the page. */
+    private ready;
+    /** Finalization refuses incomplete operations instead of silently saving partial content. */
+    assertComplete(): void;
+    /** Convert a caller point to the backend's upward-pointing page coordinates. */
+    private point;
+    /** Emit a separate native text run per line so alignment remains correct after wrapping. */
+    drawText(text: string, options: DocumentTextOptions): this;
+    /** Draw one native line with a width in document units. */
+    drawLine(options: DocumentLineOptions): this;
+    /** Resolve shared paint before rectangle, ellipse or SVG operators are appended. */
+    private paint;
+    /** Rectangle coordinates identify its top-left corner. */
+    drawRectangle(options: DocumentRectangle & DocumentShapeOptions): this;
+    /** Ellipses use a top-left bounding rectangle, matching other document shapes. */
+    drawEllipse(options: DocumentRectangle & DocumentShapeOptions): this;
+    /** Circle x/y identify its center; radius uses document units. */
+    drawCircle(options: {
+        x: number;
+        y: number;
+        radius: number;
+    } & DocumentShapeOptions): this;
+    /** Draw SVG path geometry; this API does not load or interpret SVG documents. */
+    drawSvgPath(path: string, options: {
+        x: number;
+        y: number;
+        scale?: number;
+        rotation?: number;
+    } & DocumentShapeOptions): this;
+    /** Save clipping and transforms together with the PDF graphics state. */
+    saveGraphicsState(): this;
+    /** Restore a previously saved state; an unmatched restore is an error. */
+    restoreGraphicsState(): this;
+    /** Compose an affine transform expressed in top-left document coordinates. */
+    transform(matrix: Matrix): this;
+    /** Start a new subpath without implicitly discarding an earlier subpath. */
+    moveTo(x: number, y: number): this;
+    /** Append a native straight segment to the current path. */
+    lineTo(x: number, y: number): this;
+    /** Append a cubic Bezier curve using two control points and one end point. */
+    curveTo(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number): this;
+    /** Close the current subpath while retaining it for painting or clipping. */
+    closePath(): this;
+    /** Require actual geometry before a path-ending operation. */
+    private requirePath;
+    /** Intersect the clip with the current path; discardPath ends the path afterwards. */
+    clip(rule?: 'nonzero' | 'evenodd'): this;
+    /** Clip to one rectangle and consume its path. */
+    clipRectangle(options: DocumentRectangle): this;
+    /** Discard pending geometry without painting it. */
+    discardPath(): this;
+    /** Stroke an accumulated native path. */
+    stroke(options?: {
+        color?: string;
+        width?: number;
+        opacity?: number;
+    }): this;
+    /** Fill an accumulated native path. */
+    fill(options?: {
+        color?: string;
+        opacity?: number;
+    }): this;
+    /** Fill and stroke an accumulated native path in one paint operation. */
+    fillAndStroke(options?: DocumentShapeOptions): this;
+    /** Alpha is stored in a page resource and scoped to this path operation. */
+    private paintPath;
+    /** Read image bytes before modifying page paint; no network is initiated for string inputs. */
+    private imageBytes;
+    /** Embed one PNG/JPEG at explicit dimensions, applying EXIF orientation and clockwise rotation. */
+    drawImage(source: DocumentImageSource, options: DocumentImageOptions): Promise<this>;
+    /** Transform annotation rectangles separately because PDF annotations do not inherit page graphics state. */
+    private annotationRectangle;
+    /** Add a clickable external link without an opaque border. */
+    addLink(url: string, rect: DocumentRectangle): this;
+    /** Add a Unicode note annotation; it remains separate from visible page content. */
+    addNote(text: string, rect: DocumentRectangle, options?: {
+        title?: string;
+    }): this;
+    /** Field appearances cannot faithfully represent sheared or arbitrary transformed widgets. */
+    private fieldOptions;
+    /** Apply common flags after creating a field but before marking appearances clean. */
+    private fieldFlags;
+    /** Create a Unicode-capable text input with its explicitly selected embedded font. */
+    addTextField(name: string, rect: DocumentRectangle, options?: DocumentTextFieldOptions): this;
+    /** Create an interactive checkbox with a native checkmark appearance. */
+    addCheckBox(name: string, rect: DocumentRectangle, options?: DocumentCheckBoxOptions): this;
+    /** Create a dropdown with copied choices and a validated initial selection. */
+    addDropdown(name: string, rect: DocumentRectangle, choices: readonly string[], options?: DocumentDropdownOptions): this;
+}
+export {};

package/dist/document-types.d.ts

@@ -0,0 +1,135 @@
+import type { PDFFont, PDFDocument } from 'pdf-lib';
+import type { FontSource, PDFMetadata, ImageSource } from './api-types.js';
+/** Coordinate unit; font sizes always use typographic points. */
+export type DocumentUnit = 'pt' | 'mm' | 'px';
+/** Physical page dimensions in the document's chosen coordinate unit. */
+export interface DocumentPageOptions {
+    /** Named paper or explicit width and height, including page edges. */
+    format?: 'A4' | 'A3' | 'Letter' | {
+        width: number;
+        height: number;
+    };
+    /** Landscape swaps the supplied base dimensions. */
+    orientation?: 'portrait' | 'landscape';
+}
+/** Prepare a document independently of browser layout and the DOM. */
+export interface PDFDocumentOptions extends DocumentPageOptions {
+    /** Coordinate unit, defaulting to points. */
+    unit?: DocumentUnit;
+    /** Static fonts embedded before synchronous drawing and measurement begin. */
+    fonts?: readonly FontSource[];
+    /** PDF document properties. */
+    metadata?: PDFMetadata;
+    /** Cooperative cancellation during resource preparation and serialization. */
+    signal?: AbortSignal;
+}
+/** Exact font face; all built-in families have regular, bold and italic variants. */
+export interface DocumentFontOptions {
+    /** Registered family, defaulting to Helvetica. */
+    font?: string;
+    /** Static weight, defaulting to 400. */
+    fontWeight?: number;
+    /** Static face style, defaulting to normal. */
+    fontStyle?: 'normal' | 'italic';
+}
+/** Text metrics use the document's coordinate unit. */
+export interface DocumentTextMetrics {
+    /** Largest line width. */
+    width: number;
+    /** Total line advance, including line spacing. */
+    height: number;
+    /** Distance from the baseline to the top of the font. */
+    ascent: number;
+    /** Positive distance below the baseline. */
+    descent: number;
+}
+/** Axis-aligned rectangle measured from the page's top-left corner. */
+export interface DocumentRectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Vector paint settings; colors use CSS color strings. */
+export interface DocumentShapeOptions {
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+/** Text position uses a baseline measured down from the top edge. */
+export interface DocumentTextOptions extends DocumentFontOptions {
+    x: number;
+    y: number;
+    /** Font size in points, independent of coordinate units. */
+    fontSize?: number;
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+    /** Baseline advance as a multiple of fontSize, defaulting to 1.15. */
+    lineHeight?: number;
+    rotation?: number;
+    maxWidth?: number;
+    opacity?: number;
+    link?: string;
+}
+/** One line segment in top-left page coordinates. */
+export interface DocumentLineOptions {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    color?: string;
+    width?: number;
+    opacity?: number;
+}
+/** Native bitmap bytes, a data URL, or an existing browser image/canvas. */
+export type DocumentImageSource = ImageSource | string | HTMLCanvasElement | HTMLImageElement;
+/** Explicit image placement; dimensions use document units. */
+export interface DocumentImageOptions extends DocumentRectangle {
+    rotation?: number;
+    opacity?: number;
+}
+/** Common interactive field appearance and validation settings. */
+export interface DocumentFieldOptions extends DocumentFontOptions {
+    fontSize?: number;
+    textColor?: string;
+    borderColor?: string;
+    backgroundColor?: string;
+    borderWidth?: number;
+    readOnly?: boolean;
+    required?: boolean;
+}
+/** Text field content and display behavior. */
+export interface DocumentTextFieldOptions extends DocumentFieldOptions {
+    value?: string;
+    multiline?: boolean;
+    maxLength?: number;
+}
+/** Checkbox initial state. */
+export interface DocumentCheckBoxOptions extends DocumentFieldOptions {
+    checked?: boolean;
+}
+/** Dropdown selection and editability. */
+export interface DocumentDropdownOptions extends DocumentFieldOptions {
+    value?: string | readonly string[];
+    editable?: boolean;
+    multiselect?: boolean;
+}
+/** Internal page services; the public page API does not expose backend objects. */
+export interface DocumentPageContext {
+    readonly pdf: PDFDocument;
+    readonly scale: number;
+    resolveFont(options?: DocumentFontOptions): PDFFont;
+    assertActive(): void;
+}
+/** Page destinations are one-based and belong to the current document. */
+export interface DocumentBookmarkOptions {
+    pageNumber: number;
+    /** Optional parent returned by addBookmark. */
+    parent?: DocumentBookmark;
+}
+/** Opaque destination handle used to build a bookmark hierarchy. */
+export interface DocumentBookmark {
+    readonly title: string;
+    readonly pageNumber: number;
+}

package/dist/document.d.ts

@@ -0,0 +1,64 @@
+import type { RenderPDFResult } from './api-types.js';
+import type { DocumentBookmark, DocumentBookmarkOptions, DocumentFontOptions, DocumentPageOptions, DocumentTextMetrics, DocumentUnit, PDFDocumentOptions } from './document-types.js';
+import type { PDFSource } from './compose-pdf.js';
+import { PDFPageBuilder } from './document-page.js';
+/** Mutable PDF document; drawing is synchronous after resources are prepared. */
+export declare class PDFBuilder {
+    private readonly pdf;
+    private readonly fonts;
+    private readonly fontNames;
+    private readonly defaults;
+    private readonly signal;
+    /** Point conversion shared by page drawing and compatibility adapters. */
+    readonly unitScale: number;
+    /** Coordinate unit selected at document creation. */
+    readonly unit: DocumentUnit;
+    private readonly pages;
+    private readonly activePages;
+    private readonly characterSets;
+    private readonly bookmarks;
+    private readonly roots;
+    private readonly outlines;
+    private finished;
+    private pending;
+    private output;
+    private constructor();
+    /** Prepare font programs without reading any browser globals. */
+    static create(options?: PDFDocumentOptions): Promise<PDFBuilder>;
+    /** Number of physical pages currently in the document. */
+    get pageCount(): number;
+    /** Snapshot of registered family names, including standard PDF fonts. */
+    getFontNames(): readonly string[];
+    private assertMutable;
+    private assertActive;
+    private resolveFont;
+    private wrapPage;
+    /** Add an independently sized page; no empty page is created implicitly. */
+    addPage(options?: DocumentPageOptions): PDFPageBuilder;
+    /** Insert a page before the given one-based position; pageCount + 1 appends. */
+    insertPage(pageNumber: number, options?: DocumentPageOptions): PDFPageBuilder;
+    /** Reorder existing pages while retaining native destination references. */
+    movePage(from: number, to: number): this;
+    /** Remove a page only when it is not a bookmark/link target or interactive form owner. */
+    removePage(pageNumber: number): this;
+    /** Look up an existing page by its one-based number. */
+    getPage(pageNumber: number): PDFPageBuilder;
+    /** Return page handles in document order without exposing the mutable page list. */
+    getPages(): readonly PDFPageBuilder[];
+    /** Measure using the same embedded font program used by page drawing. */
+    measureText(text: string, options?: DocumentFontOptions & {
+        fontSize?: number;
+        lineHeight?: number;
+    }): DocumentTextMetrics;
+    /** Append native PDF pages, preserving page geometry and supported page content. */
+    appendPDF(source: PDFSource, pageNumbers?: readonly number[]): Promise<this>;
+    /** Flatten prepared interactive appearances into ordinary page content. */
+    flattenForms(): this;
+    /** Create a bookmark pointing to an existing page, optionally below another bookmark. */
+    addBookmark(title: string, options: DocumentBookmarkOptions): DocumentBookmark;
+    private writeBookmarks;
+    /** Finalize once; subsequent output requests reuse the same immutable PDF. */
+    toResult(): Promise<RenderPDFResult>;
+}
+/** Prepare an empty document with registered fonts and explicit coordinate units. */
+export declare function createDocument(options?: PDFDocumentOptions): Promise<PDFBuilder>;