renderpdf-js 0.2.0 → 0.3.0

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

package/dist/fonts.d.ts

@@ -1,4 +1,8 @@
 import type { FontSource, RegisteredFont } from './api-types.js';
+/** Admit only static SFNT programs whose exact browser and PDF instances can agree.
+ * @param bytes Owned TTF/OTF program; the browser still validates its actual font tables.
+ */
+export declare function assertStaticSfnt(bytes: Uint8Array): void;
 /** 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.
  */

package/dist/index.d.ts

@@ -2,5 +2,12 @@ export { renderPDF } from './render-pdf.js';
 export { imageToPDF } from './image-pdf.js';
 export { registerFont } from './fonts.js';
 export { RenderPDFError } from './diagnostics.js';
+export { createDocument, PDFBuilder } from './document.js';
+export { PDFPageBuilder } from './document-page.js';
+export { mergePDFs, extractPDFPages, splitPDF } from './compose-pdf.js';
+export type { PDFSource, PDFCompositionOptions } from './compose-pdf.js';
+export { createJsPDFAdapter, JsPDFAdapter } from './jspdf-adapter.js';
+export type { JsPDFAdapterFont, JsPDFAdapterTextOptions, JsPDFAdapterMeasureOptions, JsPDFAdapterColorOptions, } from './jspdf-adapter.js';
+export type { DocumentUnit, DocumentPageOptions, PDFDocumentOptions, DocumentFontOptions, DocumentTextMetrics, DocumentRectangle, DocumentShapeOptions, DocumentTextOptions, DocumentLineOptions, DocumentImageSource, DocumentImageOptions, DocumentFieldOptions, DocumentTextFieldOptions, DocumentCheckBoxOptions, DocumentDropdownOptions, DocumentBookmarkOptions, DocumentBookmark, } from './document-types.js';
 export type { RenderErrorCode, RenderWarning } from './diagnostics.js';
 export type { FontSource, RegisteredFont, PageMargins, PDFPageOptions, ImageSource, ImagePDFOptions, CustomPageSize, PageTextOptions, PDFMetadata, RenderStage, RenderProgress, RenderPDFOptions, RenderPDFResult, } from './api-types.js';