pretext-pdf 0.9.3 → 1.0.0

package/dist/pipeline-footnotes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-footnotes.js","sourceRoot":"","sources":["../src/pipeline-footnotes.ts"],"names":[],"mappings":"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"}

package/dist/pipeline-toc.d.ts

@@ -0,0 +1,11 @@
+import type { PdfDocument } from './types-public.js';
+import type { MeasuredBlock } from './types-internal.js';
+/**
+ * Two-pass TOC entry building.
+ *
+ * Pass 1: draft pagination to collect heading page numbers.
+ * Splices real TOC entry blocks into measuredBlocks at the placeholder index.
+ * Returns the updated measuredBlocks array (new reference, original untouched).
+ */
+export declare function runTocTwoPass(measuredBlocks: MeasuredBlock[], doc: Pick<PdfDocument, 'content' | 'defaultFont'> & Partial<PdfDocument>, contentWidth: number, contentHeight: number): Promise<MeasuredBlock[]>;
+//# sourceMappingURL=pipeline-toc.d.ts.map

package/dist/pipeline-toc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-toc.d.ts","sourceRoot":"","sources":["../src/pipeline-toc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGxD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,cAAc,EAAE,aAAa,EAAE,EAC/B,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,aAAa,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,EACxE,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,aAAa,EAAE,CAAC,CA0B1B"}

package/dist/pipeline-toc.js

@@ -0,0 +1,28 @@
+import { paginate } from './paginate.js';
+/**
+ * Two-pass TOC entry building.
+ *
+ * Pass 1: draft pagination to collect heading page numbers.
+ * Splices real TOC entry blocks into measuredBlocks at the placeholder index.
+ * Returns the updated measuredBlocks array (new reference, original untouched).
+ */
+export async function runTocTwoPass(measuredBlocks, doc, contentWidth, contentHeight) {
+    const tocIndex = doc.content.findIndex(el => el.type === 'toc');
+    if (tocIndex === -1)
+        return measuredBlocks;
+    const tocElement = doc.content[tocIndex];
+    if (!tocElement || tocElement.type !== 'toc')
+        throw new Error('TOC element type mismatch');
+    // Pass 1: paginate without real TOC content to collect heading page numbers
+    const draftPaginatedDoc = paginate(measuredBlocks, contentHeight);
+    // Dynamic import preserves lazy-load semantics (measure.ts can be heavy)
+    const { buildTocEntryBlocks } = await import('./measure.js');
+    const tocEntryBlocks = await buildTocEntryBlocks(draftPaginatedDoc.headings, tocElement, contentWidth, doc);
+    // Splice TOC entries in place of the placeholder (zero-height) block at tocIndex
+    return [
+        ...measuredBlocks.slice(0, tocIndex),
+        ...tocEntryBlocks,
+        ...measuredBlocks.slice(tocIndex + 1),
+    ];
+}
+//# sourceMappingURL=pipeline-toc.js.map

package/dist/pipeline-toc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-toc.js","sourceRoot":"","sources":["../src/pipeline-toc.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,cAA+B,EAC/B,GAAwE,EACxE,YAAoB,EACpB,aAAqB;IAErB,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,KAAK,KAAK,CAAC,CAAA;IAC/D,IAAI,QAAQ,KAAK,CAAC,CAAC;QAAE,OAAO,cAAc,CAAA;IAE1C,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IACxC,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,IAAI,KAAK,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAA;IAE1F,4EAA4E;IAC5E,MAAM,iBAAiB,GAAG,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC,CAAA;IAEjE,yEAAyE;IACzE,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAA;IAE5D,MAAM,cAAc,GAAG,MAAM,mBAAmB,CAC9C,iBAAiB,CAAC,QAAQ,EAC1B,UAAU,EACV,YAAY,EACZ,GAAkB,CACnB,CAAA;IAED,iFAAiF;IACjF,OAAO;QACL,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;QACpC,GAAG,cAAc;QACjB,GAAG,cAAc,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;KACtC,CAAA;AACH,CAAC"}

package/dist/pipeline.d.ts

@@ -0,0 +1,24 @@
+import { PDFDocument } from '@cantoo/pdf-lib';
+import type { PdfDocument, RenderOptions } from './types-public.js';
+import type { PageGeometry, FontMap, ImageMap, MeasuredBlock } from './types-internal.js';
+import { runFootnoteTwoPass } from './pipeline-footnotes.js';
+export declare function stageValidate(doc: PdfDocument, options?: RenderOptions): void;
+export declare function stageInit(doc: PdfDocument): Promise<{
+    pdfDoc: PDFDocument;
+    geo: Omit<PageGeometry, 'contentHeight' | 'headerHeight' | 'footerHeight'>;
+    defaultFont: string;
+}>;
+export declare function stageLoadAssets(doc: PdfDocument, pdfDoc: PDFDocument, contentWidth: number, plugins?: import('./plugin-types.js').PluginDefinition[]): Promise<{
+    fontMap: FontMap;
+    imageMap: ImageMap;
+}>;
+export declare function stageFinalizeGeo(doc: PdfDocument, partialGeo: Omit<PageGeometry, 'contentHeight' | 'headerHeight' | 'footerHeight'>, defaultFont: string): Promise<PageGeometry>;
+export declare function stageMeasure(doc: PdfDocument, contentWidth: number, imageMap: ImageMap, contentHeight: number, plugins?: import('./plugin-types.js').PluginDefinition[]): Promise<MeasuredBlock[]>;
+export declare function stagePaginate(measuredBlocks: MeasuredBlock[], contentHeight: number, doc: PdfDocument): ReturnType<typeof runFootnoteTwoPass>;
+export declare function stageRender(paginatedDoc: ReturnType<typeof stagePaginate>, doc: PdfDocument, fontMap: FontMap, imageMap: ImageMap, pdfDoc: PDFDocument, geo: PageGeometry, plugins?: import('./plugin-types.js').PluginDefinition[]): Promise<Uint8Array>;
+/**
+ * Run all 5 stages in sequence and return raw PDF bytes.
+ * Post-processing (signature, encryption) is applied by the public render() in index.ts.
+ */
+export declare function runPipeline(doc: PdfDocument, options?: RenderOptions): Promise<Uint8Array>;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAsB,MAAM,iBAAiB,CAAA;AACjE,OAAO,KAAK,EAAE,WAAW,EAAW,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAUzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAI5D,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAE7E;AAID,wBAAsB,SAAS,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC;IACzD,MAAM,EAAE,WAAW,CAAA;IACnB,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,cAAc,GAAG,cAAc,CAAC,CAAA;IAC1E,WAAW,EAAE,MAAM,CAAA;CACpB,CAAC,CAwCD;AAID,wBAAsB,eAAe,CACnC,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,WAAW,EACnB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,mBAAmB,EAAE,gBAAgB,EAAE,GACvD,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC,CAMnD;AAID,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,cAAc,GAAG,cAAc,CAAC,EACjF,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CAiCvB;AAID,wBAAsB,YAAY,CAChC,GAAG,EAAE,WAAW,EAChB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,OAAO,mBAAmB,EAAE,gBAAgB,EAAE,GACvD,OAAO,CAAC,aAAa,EAAE,CAAC,CAI1B;AAID,wBAAgB,aAAa,CAC3B,cAAc,EAAE,aAAa,EAAE,EAC/B,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,WAAW,GACf,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAGvC;AAID,wBAAsB,WAAW,CAC/B,YAAY,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,EAC9C,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,YAAY,EACjB,OAAO,CAAC,EAAE,OAAO,mBAAmB,EAAE,gBAAgB,EAAE,GACvD,OAAO,CAAC,UAAU,CAAC,CAErB;AAID;;;GAGG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAiBhG"}

package/dist/pipeline.js

@@ -0,0 +1,116 @@
+import { PDFDocument, PDFName, PDFString } from '@cantoo/pdf-lib';
+import { PretextPdfError } from './errors.js';
+import { resolvePageDimensions } from './page-sizes.js';
+import { validate } from './validate.js';
+import { loadFonts } from './fonts.js';
+import { loadImages } from './assets.js';
+import { measureAllBlocks, measureHeaderFooterHeight } from './measure.js';
+import { LINE_HEIGHT_COMPACT } from './render-utils.js';
+import { renderDocument } from './render.js';
+import { runTocTwoPass } from './pipeline-toc.js';
+import { runFootnoteTwoPass } from './pipeline-footnotes.js';
+// ─── Stage 1: Validate ────────────────────────────────────────────────────────
+export function stageValidate(doc, options) {
+    validate(doc, options);
+}
+// ─── Stage 2a: Init (geometry + pdfDoc + metadata) ───────────────────────────
+export async function stageInit(doc) {
+    const [pageWidth, pageHeight] = resolvePageDimensions(doc.pageSize);
+    const margins = {
+        top: doc.margins?.top ?? 72,
+        bottom: doc.margins?.bottom ?? 72,
+        left: doc.margins?.left ?? 72,
+        right: doc.margins?.right ?? 72,
+    };
+    const contentWidth = pageWidth - margins.left - margins.right;
+    if (contentWidth <= 0) {
+        throw new PretextPdfError('PAGE_TOO_SMALL', `Content width is ${contentWidth}pt after applying margins. Reduce margins or increase page size.`);
+    }
+    const pdfDoc = await PDFDocument.create();
+    if (doc.metadata) {
+        const m = doc.metadata;
+        if (m.title)
+            pdfDoc.setTitle(m.title);
+        if (m.author)
+            pdfDoc.setAuthor(m.author);
+        if (m.subject)
+            pdfDoc.setSubject(m.subject);
+        if (m.keywords)
+            pdfDoc.setKeywords(m.keywords);
+        pdfDoc.setCreator(m.creator ?? 'pretext-pdf');
+        if (m.producer)
+            pdfDoc.setProducer(m.producer);
+        if (m.language) {
+            pdfDoc.catalog.set(PDFName.of('Lang'), PDFString.of(m.language));
+        }
+    }
+    const creationDate = doc.renderDate
+        ? (doc.renderDate instanceof Date ? doc.renderDate : new Date(doc.renderDate))
+        : new Date();
+    pdfDoc.setCreationDate(creationDate);
+    pdfDoc.setModificationDate(creationDate);
+    return {
+        pdfDoc,
+        geo: { pageWidth, pageHeight, margins, contentWidth },
+        defaultFont: doc.defaultFont ?? 'Inter',
+    };
+}
+// ─── Stage 2b: Load assets (fonts + images in parallel) ──────────────────────
+export async function stageLoadAssets(doc, pdfDoc, contentWidth, plugins) {
+    const [fontMap, imageMap] = await Promise.all([
+        loadFonts(doc, pdfDoc),
+        loadImages(doc, pdfDoc, contentWidth, plugins),
+    ]);
+    return { fontMap, imageMap };
+}
+// ─── Stage 2c: Finalize geometry (header/footer heights) ─────────────────────
+export async function stageFinalizeGeo(doc, partialGeo, defaultFont) {
+    const { pageHeight, margins, contentWidth } = partialGeo;
+    const headerHeight = doc.header
+        ? await measureHeaderFooterHeight(doc.header.text, doc.header.fontSize ?? 10, doc.header.fontFamily ?? defaultFont, contentWidth, (doc.header.fontSize ?? 10) * LINE_HEIGHT_COMPACT) + 8
+        : 0;
+    const footerHeight = doc.footer
+        ? await measureHeaderFooterHeight(doc.footer.text, doc.footer.fontSize ?? 10, doc.footer.fontFamily ?? defaultFont, contentWidth, (doc.footer.fontSize ?? 10) * LINE_HEIGHT_COMPACT) + 8
+        : 0;
+    const contentHeight = pageHeight - margins.top - margins.bottom - headerHeight - footerHeight;
+    if (contentHeight <= 0) {
+        throw new PretextPdfError('PAGE_TOO_SMALL', `Content height is ${contentHeight}pt after applying margins + header/footer. Try reducing margins, header/footer font size, or increasing page size.`);
+    }
+    return { ...partialGeo, headerHeight, footerHeight, contentHeight };
+}
+// ─── Stage 3: Measure ─────────────────────────────────────────────────────────
+export async function stageMeasure(doc, contentWidth, imageMap, contentHeight, plugins) {
+    let measuredBlocks = await measureAllBlocks(doc, contentWidth, imageMap, contentHeight, plugins);
+    measuredBlocks = await runTocTwoPass(measuredBlocks, doc, contentWidth, contentHeight);
+    return measuredBlocks;
+}
+// ─── Stage 4: Paginate ────────────────────────────────────────────────────────
+export function stagePaginate(measuredBlocks, contentHeight, doc) {
+    const paginateConfig = { minOrphanLines: 2, minWidowLines: 2 };
+    return runFootnoteTwoPass(measuredBlocks, contentHeight, paginateConfig, doc);
+}
+// ─── Stage 5: Render ──────────────────────────────────────────────────────────
+export async function stageRender(paginatedDoc, doc, fontMap, imageMap, pdfDoc, geo, plugins) {
+    return renderDocument(paginatedDoc, doc, fontMap, imageMap, pdfDoc, geo, plugins);
+}
+// ─── Composed pipeline ────────────────────────────────────────────────────────
+/**
+ * Run all 5 stages in sequence and return raw PDF bytes.
+ * Post-processing (signature, encryption) is applied by the public render() in index.ts.
+ */
+export async function runPipeline(doc, options) {
+    // Node canvas polyfill MUST be installed before any Pretext import (measure.ts uses it)
+    if (typeof OffscreenCanvas === 'undefined' && typeof window === 'undefined') {
+        const { installNodePolyfill } = await import('./node-polyfill.js');
+        await installNodePolyfill();
+    }
+    const plugins = options?.plugins;
+    stageValidate(doc, options);
+    const { pdfDoc, geo: partialGeo, defaultFont } = await stageInit(doc);
+    const { fontMap, imageMap } = await stageLoadAssets(doc, pdfDoc, partialGeo.contentWidth, plugins);
+    const geo = await stageFinalizeGeo(doc, partialGeo, defaultFont);
+    const measuredBlocks = await stageMeasure(doc, geo.contentWidth, imageMap, geo.contentHeight, plugins);
+    const paginatedDoc = stagePaginate(measuredBlocks, geo.contentHeight, doc);
+    return stageRender(paginatedDoc, doc, fontMap, imageMap, pdfDoc, geo, plugins);
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/plugin-registry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Plugin registry — orchestration helpers for the 4 injection points.
+ *
+ * All functions are pure (no module-level state). The plugin list is
+ * threaded through the pipeline via RenderOptions and passed explicitly.
+ *
+ * @internal Not part of the public API. Import PluginDefinition from plugin-types.ts.
+ */
+import type { PluginDefinition, PluginMeasureContext } from './plugin-types.js';
+import type { MeasuredBlock, PageGeometry } from './types-internal.js';
+/**
+ * Return the first plugin whose `type` matches `elementType`, or `undefined`.
+ * @internal
+ */
+export declare function findPlugin(plugins: PluginDefinition[], elementType: string): PluginDefinition | undefined;
+/**
+ * Run a plugin's optional `validate` hook.
+ * Returns the rejection message if the hook rejects, or `undefined` if accepted.
+ */
+export declare function runPluginValidate(plugin: PluginDefinition, element: Record<string, unknown>): string | undefined;
+/**
+ * Run a plugin's optional `loadAsset` hook and return the resulting PDFImage key
+ * if an image was embedded.
+ *
+ * Callers are responsible for setting `imageMap.set(key, image)` with the returned image.
+ */
+export declare function runPluginLoadAsset(plugin: PluginDefinition, element: Record<string, unknown>, pdfDoc: import('@cantoo/pdf-lib').PDFDocument, contentWidth: number, contentIndex: number): Promise<{
+    key: string;
+    image: import('@cantoo/pdf-lib').PDFImage;
+} | undefined>;
+/**
+ * Run a plugin's `measure` hook and wrap the result into a `MeasuredBlock`.
+ */
+export declare function runPluginMeasure(plugin: PluginDefinition, element: Record<string, unknown>, context: PluginMeasureContext, pluginImageKey?: string): Promise<MeasuredBlock>;
+/**
+ * Run a plugin's `render` hook with the fully-assembled render context.
+ * Wraps thrown errors in RENDER_FAILED so callers see a consistent error type.
+ */
+export declare function runPluginRender(plugin: PluginDefinition, block: MeasuredBlock, pdfPage: import('@cantoo/pdf-lib').PDFPage, pdfDoc: import('@cantoo/pdf-lib').PDFDocument, x: number, y: number, geo: PageGeometry, imageMap: import('./types-internal.js').ImageMap): void;
+//# sourceMappingURL=plugin-registry.d.ts.map

package/dist/plugin-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../src/plugin-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAA4C,MAAM,mBAAmB,CAAA;AACzH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAKtE;;;GAGG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,WAAW,EAAE,MAAM,GAClB,gBAAgB,GAAG,SAAS,CAE9B;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,GAAG,SAAS,CAKpB;AAID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,EAAE,OAAO,iBAAiB,EAAE,WAAW,EAC7C,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,iBAAiB,EAAE,QAAQ,CAAA;CAAE,GAAG,SAAS,CAAC,CAMjF;AAID;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,oBAAoB,EAC7B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,aAAa,CAAC,CA+BxB;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,OAAO,iBAAiB,EAAE,OAAO,EAC1C,MAAM,EAAE,OAAO,iBAAiB,EAAE,WAAW,EAC7C,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,OAAO,qBAAqB,EAAE,QAAQ,GAC/C,IAAI,CAwBN"}

package/dist/plugin-registry.js

@@ -0,0 +1,104 @@
+/**
+ * Plugin registry — orchestration helpers for the 4 injection points.
+ *
+ * All functions are pure (no module-level state). The plugin list is
+ * threaded through the pipeline via RenderOptions and passed explicitly.
+ *
+ * @internal Not part of the public API. Import PluginDefinition from plugin-types.ts.
+ */
+import { PretextPdfError } from './errors.js';
+// ─── Lookup ───────────────────────────────────────────────────────────────────
+/**
+ * Return the first plugin whose `type` matches `elementType`, or `undefined`.
+ * @internal
+ */
+export function findPlugin(plugins, elementType) {
+    return plugins.find(p => p.type === elementType);
+}
+// ─── Stage 1: validate ────────────────────────────────────────────────────────
+/**
+ * Run a plugin's optional `validate` hook.
+ * Returns the rejection message if the hook rejects, or `undefined` if accepted.
+ */
+export function runPluginValidate(plugin, element) {
+    if (!plugin.validate)
+        return undefined;
+    const result = plugin.validate(element);
+    // Normalize: only non-empty strings are rejections; '' and void are acceptance
+    return typeof result === 'string' && result.length > 0 ? result : undefined;
+}
+// ─── Stage 2b: load assets ────────────────────────────────────────────────────
+/**
+ * Run a plugin's optional `loadAsset` hook and return the resulting PDFImage key
+ * if an image was embedded.
+ *
+ * Callers are responsible for setting `imageMap.set(key, image)` with the returned image.
+ */
+export async function runPluginLoadAsset(plugin, element, pdfDoc, contentWidth, contentIndex) {
+    if (!plugin.loadAsset)
+        return undefined;
+    const image = await plugin.loadAsset(element, pdfDoc, contentWidth);
+    if (!image)
+        return undefined;
+    const key = `${plugin.type}-${contentIndex}`;
+    return { key, image };
+}
+// ─── Stage 3: measure ─────────────────────────────────────────────────────────
+/**
+ * Run a plugin's `measure` hook and wrap the result into a `MeasuredBlock`.
+ */
+export async function runPluginMeasure(plugin, element, context, pluginImageKey) {
+    let result;
+    try {
+        result = await plugin.measure(element, context);
+    }
+    catch (err) {
+        throw new PretextPdfError('RENDER_FAILED', `Plugin '${plugin.type}' measure hook threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof result.height !== 'number' || !isFinite(result.height) || result.height < 0) {
+        throw new PretextPdfError('RENDER_FAILED', `Plugin '${plugin.type}' measure hook returned invalid height: ${result.height}. Must be a finite non-negative number.`);
+    }
+    const block = {
+        element: element,
+        height: result.height,
+        lines: [],
+        fontSize: 0,
+        lineHeight: 0,
+        fontKey: '',
+        spaceAfter: result.spaceAfter ?? 0,
+        spaceBefore: result.spaceBefore ?? 0,
+        pluginData: result.pluginData,
+    };
+    if (pluginImageKey !== undefined)
+        block.pluginImageKey = pluginImageKey;
+    return block;
+}
+// ─── Stage 5: render ──────────────────────────────────────────────────────────
+/**
+ * Run a plugin's `render` hook with the fully-assembled render context.
+ * Wraps thrown errors in RENDER_FAILED so callers see a consistent error type.
+ */
+export function runPluginRender(plugin, block, pdfPage, pdfDoc, x, y, geo, imageMap) {
+    const pdfImage = block.pluginImageKey ? imageMap.get(block.pluginImageKey) : undefined;
+    const ctx = {
+        element: block.element,
+        pdfPage,
+        pdfDoc,
+        pageWidth: geo.pageWidth,
+        pageHeight: geo.pageHeight,
+        margins: geo.margins,
+        x,
+        y,
+        width: geo.contentWidth,
+        height: block.height,
+        pluginData: block.pluginData,
+        ...(pdfImage !== undefined ? { pdfImage } : {}),
+    };
+    try {
+        plugin.render(ctx);
+    }
+    catch (err) {
+        throw new PretextPdfError('RENDER_FAILED', `Plugin '${plugin.type}' render hook threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=plugin-registry.js.map

package/dist/plugin-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-registry.js","sourceRoot":"","sources":["../src/plugin-registry.ts"],"names":[],"mappings":"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"}

package/dist/plugin-types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Plugin extension points for pretext-pdf.
+ *
+ * Register custom element types by passing an array of `PluginDefinition` objects
+ * in `RenderOptions.plugins`. Each definition handles one `type` string.
+ *
+ * @example
+ * ```ts
+ * import { render } from 'pretext-pdf'
+ * import type { PluginDefinition } from 'pretext-pdf/plugin-types'
+ *
+ * const boxPlugin: PluginDefinition = {
+ *   type: 'highlight-box',
+ *   measure: async (el, { contentWidth }) => ({ height: 50, spaceBefore: 8, spaceAfter: 8 }),
+ *   render: ({ pdfPage, x, y, width, height }) => {
+ *     pdfPage.drawRectangle({ x, y: y - height, width, height, color: rgb(1, 0.9, 0.8) })
+ *   },
+ * }
+ *
+ * const bytes = await render(doc, { plugins: [boxPlugin] })
+ * ```
+ *
+ * @module
+ * @beta
+ */
+import type { PdfDocument, Margins } from './types-public.js';
+/**
+ * Context passed to a plugin's `measure` hook.
+ * @beta
+ */
+export interface PluginMeasureContext {
+    /** Available content width in pt (page width minus left/right margins) */
+    contentWidth: number;
+    /** Available content height per page in pt */
+    contentHeight: number;
+    /** The full document being rendered */
+    doc: PdfDocument;
+}
+/**
+ * Return value from a plugin's `measure` hook.
+ * @beta
+ */
+export interface PluginMeasureResult {
+    /** Total block height in pt. Must be a finite non-negative number. */
+    height: number;
+    /** Space before the block in pt. Defaults to 0. */
+    spaceBefore?: number;
+    /** Space after the block in pt. Defaults to 0. */
+    spaceAfter?: number;
+    /**
+     * Arbitrary plugin-specific data that the pipeline carries untouched from
+     * `measure` to `render`. Use this to avoid re-computing expensive values.
+     */
+    pluginData?: unknown;
+}
+/**
+ * Context passed to a plugin's `render` hook.
+ * @beta
+ */
+export interface PluginRenderContext {
+    /** The raw element object from doc.content */
+    element: Record<string, unknown>;
+    /** The pdf-lib page object to draw onto */
+    pdfPage: import('@cantoo/pdf-lib').PDFPage;
+    /** The pdf-lib document — use for color/font helpers */
+    pdfDoc: import('@cantoo/pdf-lib').PDFDocument;
+    /** Page width in pt */
+    pageWidth: number;
+    /** Page height in pt */
+    pageHeight: number;
+    /** Page margins in pt */
+    margins: Margins;
+    /** Left edge of the block's bounding box in pt (from page left) */
+    x: number;
+    /**
+     * pdf-lib Y coordinate of the **top** edge of the block in pt.
+     *
+     * pdf-lib uses a bottom-left origin, so `y` decreases as you move down the page.
+     * To draw a rectangle that fills the block exactly:
+     * ```ts
+     * pdfPage.drawRectangle({ x, y: y - height, width, height })
+     * ```
+     * To draw text starting at the top of the block:
+     * ```ts
+     * pdfPage.drawText(line1, { x, y: y - fontSize })
+     * pdfPage.drawText(line2, { x, y: y - fontSize - lineHeight })
+     * // For subsequent lines: y - fontSize - (n * lineHeight)
+     * ```
+     * `y - fontSize` places the baseline of the first line flush against the block top.
+     * For wrapped or multi-line text, subtract `lineHeight` per additional line.
+     */
+    y: number;
+    /** Block width in pt */
+    width: number;
+    /** Block height in pt (as returned by measure) */
+    height: number;
+    /**
+     * Embedded image, if the plugin's `loadAsset` hook returned a PDFImage.
+     * Undefined when the plugin has no `loadAsset` or it returned undefined.
+     */
+    pdfImage?: import('@cantoo/pdf-lib').PDFImage;
+    /**
+     * Data returned by the plugin's `measure` hook in `PluginMeasureResult.pluginData`.
+     * Undefined when measure did not set pluginData.
+     */
+    pluginData?: unknown;
+}
+/**
+ * Defines a custom element type that can be used in `doc.content`.
+ *
+ * All four hooks correspond to the pipeline stage they participate in:
+ * - `validate` → Stage 1
+ * - `loadAsset` → Stage 2b
+ * - `measure` → Stage 3 (required)
+ * - `render` → Stage 5 (required)
+ *
+ * @beta
+ */
+export interface PluginDefinition {
+    /**
+     * Unique type string. Must match the `type` field of the custom element objects
+     * in `doc.content`. Must not collide with any built-in type.
+     */
+    type: string;
+    /**
+     * Validate hook — Stage 1.
+     *
+     * Called once per matching element during validation.
+     * Return a non-empty string to reject the element; the message is used verbatim
+     * in the thrown `VALIDATION_ERROR`. Return `void`, `undefined`, or `''` to accept.
+     *
+     * @param element - The raw element object from doc.content
+     * @returns A rejection reason string, or void to accept
+     */
+    validate?: (element: Record<string, unknown>) => string | void;
+    /**
+     * Load asset hook — Stage 2b.
+     *
+     * Called during image/asset loading for each matching element.
+     * Return a `PDFImage` to embed it into the document; the embedded image is
+     * passed to `render` via `PluginRenderContext.pdfImage`.
+     * Return `undefined` to skip asset loading for this element.
+     *
+     * The image key used in the imageMap is `${plugin.type}-${contentIndex}`.
+     *
+     * **Error handling:** Errors thrown here are handled differently from `measure`/`render`.
+     * If this hook throws a `PretextPdfError`, it propagates and aborts the render.
+     * If it throws any other error, the error is logged via `console.warn` and asset loading
+     * is silently skipped for this element (the render continues without `pdfImage`).
+     * This asymmetry means non-critical asset failures don't abort the whole document.
+     *
+     * **File safety:** If you load files based on element data, validate the path against
+     * `doc.allowedFileDirs` yourself. The framework does not apply its PATH_TRAVERSAL guard
+     * to files loaded inside this hook.
+     *
+     * @param element - The raw element object
+     * @param pdfDoc - The pdf-lib PDFDocument (use pdfDoc.embedPng / embedJpg)
+     * @param contentWidth - Available width in pt (for sizing decisions)
+     */
+    loadAsset?: (element: Record<string, unknown>, pdfDoc: import('@cantoo/pdf-lib').PDFDocument, contentWidth: number) => Promise<import('@cantoo/pdf-lib').PDFImage | undefined>;
+    /**
+     * Measure hook — Stage 3. **Required.**
+     *
+     * Called once per matching element to determine its height and layout metadata.
+     * The returned `height` drives pagination; `pluginData` is carried to `render`.
+     * Return `height: 0` to produce an invisible zero-height block (acts like a spacer).
+     *
+     * @param element - The raw element object
+     * @param context - Content dimensions and the full document
+     */
+    measure: (element: Record<string, unknown>, context: PluginMeasureContext) => Promise<PluginMeasureResult>;
+    /**
+     * Render hook — Stage 5. **Required.**
+     *
+     * Called once per page-slice of the element during rendering.
+     * Draw directly onto `context.pdfPage` using pdf-lib's drawing API.
+     *
+     * This hook must be synchronous. If you need async work (e.g. font loading),
+     * do it in `measure` and pass the result via `PluginMeasureResult.pluginData`.
+     *
+     * @param context - Page, geometry, embedded image, and plugin data
+     */
+    render: (context: PluginRenderContext) => void;
+}
+//# sourceMappingURL=plugin-types.d.ts.map

package/dist/plugin-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-types.d.ts","sourceRoot":"","sources":["../src/plugin-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAI7D;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAA;IACpB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAA;IACrB,uCAAuC;IACvC,GAAG,EAAE,WAAW,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAA;IACd,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,2CAA2C;IAC3C,OAAO,EAAE,OAAO,iBAAiB,EAAE,OAAO,CAAA;IAC1C,wDAAwD;IACxD,MAAM,EAAE,OAAO,iBAAiB,EAAE,WAAW,CAAA;IAC7C,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,yBAAyB;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,mEAAmE;IACnE,CAAC,EAAE,MAAM,CAAA;IACT;;;;;;;;;;;;;;;;OAgBG;IACH,CAAC,EAAE,MAAM,CAAA;IACT,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,iBAAiB,EAAE,QAAQ,CAAA;IAC7C;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAID;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,IAAI,CAAA;IAE9D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,EAAE,CACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,EAAE,OAAO,iBAAiB,EAAE,WAAW,EAC7C,YAAY,EAAE,MAAM,KACjB,OAAO,CAAC,OAAO,iBAAiB,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAA;IAE5D;;;;;;;;;OASG;IACH,OAAO,EAAE,CACP,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,oBAAoB,KAC1B,OAAO,CAAC,mBAAmB,CAAC,CAAA;IAEjC;;;;;;;;;;OAUG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,IAAI,CAAA;CAC/C"}

package/dist/plugin-types.js

@@ -0,0 +1,27 @@
+/**
+ * Plugin extension points for pretext-pdf.
+ *
+ * Register custom element types by passing an array of `PluginDefinition` objects
+ * in `RenderOptions.plugins`. Each definition handles one `type` string.
+ *
+ * @example
+ * ```ts
+ * import { render } from 'pretext-pdf'
+ * import type { PluginDefinition } from 'pretext-pdf/plugin-types'
+ *
+ * const boxPlugin: PluginDefinition = {
+ *   type: 'highlight-box',
+ *   measure: async (el, { contentWidth }) => ({ height: 50, spaceBefore: 8, spaceAfter: 8 }),
+ *   render: ({ pdfPage, x, y, width, height }) => {
+ *     pdfPage.drawRectangle({ x, y: y - height, width, height, color: rgb(1, 0.9, 0.8) })
+ *   },
+ * }
+ *
+ * const bytes = await render(doc, { plugins: [boxPlugin] })
+ * ```
+ *
+ * @module
+ * @beta
+ */
+export {};
+//# sourceMappingURL=plugin-types.js.map

package/dist/plugin-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-types.js","sourceRoot":"","sources":["../src/plugin-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}

package/dist/post-process.d.ts

@@ -0,0 +1,16 @@
+import type { PdfDocument } from './types-public.js';
+/**
+ * Apply PKCS#7 digital signature to pre-rendered PDF bytes.
+ * Requires the @signpdf/signpdf peer dependency.
+ */
+export declare function applySignature(pdfBytes: Uint8Array, sig: NonNullable<PdfDocument['signature']>): Promise<Uint8Array>;
+/**
+ * Apply AES-128 or AES-256 encryption to pre-rendered PDF bytes.
+ */
+export declare function applyEncryption(pdfBytes: Uint8Array, enc: NonNullable<PdfDocument['encryption']>): Promise<Uint8Array>;
+/**
+ * Apply signature and encryption post-processing to raw pipeline bytes.
+ * Called by both render() in index.ts and PdfBuilder.build() in builder.ts.
+ */
+export declare function applyPostProcessing(rawBytes: Uint8Array, doc: PdfDocument): Promise<Uint8Array>;
+//# sourceMappingURL=post-process.d.ts.map

package/dist/post-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-process.d.ts","sourceRoot":"","sources":["../src/post-process.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAGpD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,UAAU,EACpB,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,GACzC,OAAO,CAAC,UAAU,CAAC,CA4DrB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,UAAU,EACpB,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,GAC1C,OAAO,CAAC,UAAU,CAAC,CAarB;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,UAAU,EACpB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,UAAU,CAAC,CAGrB"}