@lpdfio/lpdf 0.31.0 → 0.33.0

package/dist/engine.js

@@ -3,13 +3,44 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PdfEngine = exports.LpdfRenderError = void 0;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_worker_threads_1 = require("node:worker_threads");
 const _shared_1 = require("./_shared");
-// require() path is relative to the compiled output at dist/engine.js.
-// In the published package, wasm-pack artifacts live in dist/wasm/.
-// In the monorepo, `npm run build` copies them there from <root>/dist/node/.
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const wasmModule = require('./wasm/lpdf.js');
-const WasmEngine = wasmModule.LpdfEngine;
+const render_error_1 = require("./render-error");
+const stamp_1 = require("./stamp");
+const render_queue_1 = require("./render-queue");
+var render_error_2 = require("./render-error");
+Object.defineProperty(exports, "LpdfRenderError", { enumerable: true, get: function () { return render_error_2.LpdfRenderError; } });
+/**
+ * The engine's license check on this thread, loaded on first use: a render runs on the worker, which loads the engine
+ * itself, so an app that only renders loads it once.
+ */
+function checkLicense(token, nowUnix) {
+    // require() path is relative to the compiled output at dist/engine.js.
+    // In the published package, wasm-pack artifacts live in dist/wasm/.
+    // In the monorepo, `npm run build` copies them there from <root>/dist/node/.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const wasm = require('./wasm/lpdf.js');
+    return wasm.check_license(token, nowUnix);
+}
+/**
+ * Starts the worker of `render-worker.js`. It keeps the process running only while it renders, so a script that has
+ * rendered ends by itself.
+ */
+function startNodeWorker(events) {
+    const worker = new node_worker_threads_1.Worker((0, node_path_1.join)(__dirname, 'render-worker.js'));
+    worker.on('message', (reply) => events.replied(reply));
+    worker.on('error', error => events.failed(error.message));
+    worker.on('messageerror', error => events.failed(error.message));
+    worker.on('exit', code => events.failed(`The render worker stopped with exit code ${code}.`));
+    return {
+        post: job => worker.postMessage(job),
+        terminate: () => void worker.terminate(),
+        hold: busy => (busy ? worker.ref() : worker.unref()),
+    };
+}
+// One worker for the process, as renders ran one at a time on the calling thread before they moved to a worker.
+let renderQueue;
 /**
  * The clock the engine checks a key's expiry against.
  *
@@ -22,26 +53,28 @@ const WasmEngine = wasmModule.LpdfEngine;
 function nowUnix() {
     return BigInt(Math.floor(Date.now() / 1000));
 }
-/** Thrown when the lpdf engine returns a layout or parse error. */
-class LpdfRenderError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'LpdfRenderError';
-    }
-}
-exports.LpdfRenderError = LpdfRenderError;
 /** Node's secure generator, for the entropy of AES-256. */
 function secureRandomBytes(count) {
     return new Uint8Array((0, node_crypto_1.randomBytes)(count));
 }
 class PdfEngine {
-    constructor() {
+    /**
+     * @param options - Engine-level options: `timeout`, the seconds a render may run before it rejects with an
+     *   `LpdfRenderError` that names the limit, 5 when left out and no limit at 0; `maxMemoryMb`, the megabytes a render
+     *   may allocate before it rejects with an `LpdfRenderError` that names the cap, 1024 when left out.
+     * @throws {RangeError} when `timeout` is negative or not a finite number, or `maxMemoryMb` is not a whole number
+     *   from 1 to 4096.
+     */
+    constructor(options = {}) {
         this._licenseKey = '';
         this._fonts = new Map();
         this._images = new Map();
         this._files = new Map();
+        this._profiles = new Map();
         this._markdownStyles = new Map();
         this._disposed = false;
+        this._timeout = (0, render_queue_1.renderTimeout)(options.timeout);
+        this._maxMemoryMb = (0, _shared_1.maxMemoryMb)(options.maxMemoryMb);
     }
     /**
      * Set the license key. Returns `this` for chaining.
@@ -64,7 +97,7 @@ class PdfEngine {
      */
     checkLicenseKey(key) {
         this._throwIfDisposed();
-        return JSON.parse(wasmModule.check_license(key ?? this._licenseKey, nowUnix()));
+        return JSON.parse(checkLicense(key ?? this._licenseKey, nowUnix()));
     }
     /**
      * Register raw TTF/OTF bytes for a custom font name used in `<font src="…">`.
@@ -93,6 +126,16 @@ class PdfEngine {
         this._files.set(name, bytes);
         return this;
     }
+    /**
+     * Register the bytes of an ICC color profile, for the `<profile>` of the document's `<assets>` whose `ref`, or with
+     * no ref whose name, is `name`: the press profile a PDF/X document names in its output. Call before `render`.
+     * Returns `this` for chaining.
+     */
+    loadProfile(name, bytes) {
+        this._throwIfDisposed();
+        this._profiles.set(name, bytes);
+        return this;
+    }
     /**
      * Register the text of a file of Markdown rules, the root of which is a `<markdown-styles>`, for the `src` that
      * names it, as `<markdown-styles src="…">` does. Call before `render`. Returns `this` for chaining.
@@ -111,10 +154,10 @@ class PdfEngine {
     }
     [Symbol.dispose]() { this.dispose(); }
     /**
-     * Hand the engine the files of Markdown rules that a document names: the ones loaded here, and the ones read from
-     * their `src`. A file that can't be read is left for the engine to report, naming the `src`.
+     * The files of Markdown rules that a document names: the ones loaded here, and the ones read from their `src`. A
+     * file that can't be read is left for the engine to report, naming the `src`.
      */
-    _loadMarkdownStyles(engine, srcs) {
+    _markdownStylesFor(srcs) {
         const files = new Map(this._markdownStyles);
         for (const src of srcs) {
             if (!files.has(src)) {
@@ -124,15 +167,13 @@ class PdfEngine {
                 catch { /* not found; the engine says so */ }
             }
         }
-        for (const [src, text] of files) {
-            engine.load_markdown_styles(src, text);
-        }
+        return files;
     }
     /**
-     * Hand the engine the files the document carries: the ones loaded here, and the ones read from the `src` of a file
-     * that wasn't. A `src` that can't be read is an error that names the file and the path.
+     * The files the document carries: the ones loaded here, and the ones read from the `src` of a file that wasn't. A
+     * `src` that can't be read is an error that names the file and the path.
      */
-    _loadFiles(engine, srcs) {
+    _filesFor(srcs) {
         const files = new Map(this._files);
         for (const [key, src] of srcs) {
             if (files.has(key))
@@ -141,12 +182,28 @@ class PdfEngine {
                 files.set(key, (0, node_fs_1.readFileSync)(src));
             }
             catch (e) {
-                throw new LpdfRenderError(`file '${key}' of <attachments>: cannot read its src '${src}': ${e instanceof Error ? e.message : String(e)}`);
+                throw new render_error_1.LpdfRenderError(`file '${key}' of <attachments>: cannot read its src '${src}': ${e instanceof Error ? e.message : String(e)}`);
             }
         }
-        for (const [key, bytes] of files) {
-            engine.load_file(key, bytes);
+        return files;
+    }
+    /**
+     * The color profiles the document declares: the ones loaded here, and the ones read from the `src` of a profile
+     * that wasn't. A `src` that can't be read is an error that names the profile and the path.
+     */
+    _profilesFor(srcs) {
+        const profiles = new Map(this._profiles);
+        for (const [key, src] of srcs) {
+            if (profiles.has(key))
+                continue;
+            try {
+                profiles.set(key, (0, node_fs_1.readFileSync)(src));
+            }
+            catch (e) {
+                throw new render_error_1.LpdfRenderError(`profile '${key}' of <assets>: cannot read its src '${src}': ${e instanceof Error ? e.message : String(e)}`);
+            }
         }
+        return profiles;
     }
     _throwIfDisposed() {
         if (this._disposed)
@@ -154,89 +211,115 @@ class PdfEngine {
     }
     async render(input, callOptions = {}) {
         this._throwIfDisposed();
-        const engine = new WasmEngine(this._licenseKey);
-        // Without a clock the engine cannot check the key's expiry, and an expired key renders as
-        // though it were current.
-        engine.set_now(nowUnix());
-        if (callOptions.createdOn) {
-            engine.set_created_on(callOptions.createdOn);
-        }
-        let pdf;
-        try {
-            if (typeof input === 'string') {
-                // XML path — auto-load fonts and images declared via src="…".
-                const xml = input;
-                const allFonts = new Map(this._fonts);
-                for (const [key, src] of extractAssetSrcs(xml, 'font')) {
-                    if (!allFonts.has(key)) {
-                        try {
-                            allFonts.set(key, (0, node_fs_1.readFileSync)(src));
-                        }
-                        catch { /* not found; Rust falls back to Helvetica */ }
+        const job = this._job(input, callOptions);
+        renderQueue ?? (renderQueue = new render_queue_1.RenderQueue(startNodeWorker));
+        return renderQueue.render(job, this._timeout);
+    }
+    /**
+     * Draw PNG images over the pages of an existing PDF, and return the PDF with them (Node.js). Nothing is laid out:
+     * each image is drawn in its stamp's box, over the pages its `page` names.
+     *
+     * The output is the input, byte for byte, with an incremental update after it, so an owner password and its
+     * permissions stay, and so does a digital signature, for the revision it signed. A PDF/A file stays PDF/A. Without a
+     * license key each stamped page gets the attribution line in its top-right corner. A stamp covers what is under it
+     * and does not remove it: the text under an image can still be selected and found, so a stamp is not a redaction.
+     *
+     * The stamp runs on a worker thread, as a render does, with its `timeout` and `maxMemoryMb`. It rejects with an
+     * `LpdfRenderError` when the input is not a PDF, needs a password to open, or doesn't have a page a stamp names, and
+     * when an image is not a PNG or a stamp's options are wrong.
+     *
+     * @throws {TypeError} when a stamp's `image` is not the PNG's bytes.
+     */
+    async stamp(pdf, stamps) {
+        this._throwIfDisposed();
+        const { stamps: json, images } = (0, stamp_1.stampRequest)(stamps);
+        const job = {
+            licenseKey: this._licenseKey,
+            now: nowUnix(),
+            maxMemoryMb: this._maxMemoryMb,
+            createdOn: undefined,
+            fonts: new Map(),
+            images,
+            files: new Map(),
+            profiles: new Map(),
+            markdownStyles: new Map(),
+            document: { pdf, stamps: json },
+            encryption: [null, null, false, new Uint8Array()],
+        };
+        renderQueue ?? (renderQueue = new render_queue_1.RenderQueue(startNodeWorker));
+        return renderQueue.render(job, this._timeout);
+    }
+    /**
+     * A render of `input` with every file it needs, read here from the `src` of each font, image, file, profile and
+     * file of rules the document names and that wasn't loaded: the worker reads nothing itself.
+     */
+    _job(input, callOptions) {
+        const fonts = new Map(this._fonts);
+        const images = new Map(this._images);
+        let document;
+        let markdownStyles;
+        let files;
+        let profiles;
+        if (typeof input === 'string') {
+            // XML path — auto-load fonts and images declared via src="…".
+            for (const [key, src] of extractAssetSrcs(input, 'font')) {
+                if (!fonts.has(key)) {
+                    try {
+                        fonts.set(key, (0, node_fs_1.readFileSync)(src));
                     }
+                    catch { /* not found; Rust falls back to Helvetica */ }
                 }
-                for (const [name, bytes] of allFonts) {
-                    engine.load_font(name, bytes);
-                }
-                for (const [name, bytes] of this._images) {
-                    engine.load_image(name, bytes);
-                }
-                this._loadMarkdownStyles(engine, markdownStylesSrcs(xml));
-                this._loadFiles(engine, extractAssetSrcs(xml, 'file'));
-                // Auto-load images declared via <image src="…"> that weren't pre-loaded.
-                for (const [key, src] of extractAssetSrcs(xml, 'image')) {
-                    if (!this._images.has(key)) {
-                        try {
-                            engine.load_image(key, (0, node_fs_1.readFileSync)(src));
-                        }
-                        catch { /* skip unresolvable image */ }
+            }
+            for (const [key, src] of extractAssetSrcs(input, 'image')) {
+                if (!images.has(key)) {
+                    try {
+                        images.set(key, (0, node_fs_1.readFileSync)(src));
                     }
+                    catch { /* skip unresolvable image */ }
                 }
-                const dataJson = callOptions.data != null ? JSON.stringify(callOptions.data) : null;
-                pdf = engine.render_pdf(xml, dataJson, ...(0, _shared_1.encryptionArguments)(callOptions, secureRandomBytes));
             }
-            else {
-                // JSON (Kit tree) path — pass JSON directly to render_tree_pdf. Fonts and images the
-                // document declares with a src are read from there, as on the XML path.
-                const json = JSON.stringify(input);
-                const allFonts = new Map(this._fonts);
-                for (const [key, src] of assetSrcsOfDocument(input, 'fonts')) {
-                    if (!allFonts.has(key)) {
-                        try {
-                            allFonts.set(key, (0, node_fs_1.readFileSync)(src));
-                        }
-                        catch { /* not found; Rust falls back to Helvetica */ }
+            markdownStyles = this._markdownStylesFor(markdownStylesSrcs(input));
+            files = this._filesFor(extractAssetSrcs(input, 'file'));
+            profiles = this._profilesFor(extractAssetSrcs(input, 'profile'));
+            document = { xml: input, data: callOptions.data != null ? JSON.stringify(callOptions.data) : null };
+        }
+        else {
+            // JSON (Kit tree) path. Fonts and images the document declares with a src are read from there, as on the XML
+            // path.
+            for (const [key, src] of assetSrcsOfDocument(input, 'fonts')) {
+                if (!fonts.has(key)) {
+                    try {
+                        fonts.set(key, (0, node_fs_1.readFileSync)(src));
                     }
+                    catch { /* not found; Rust falls back to Helvetica */ }
                 }
-                for (const [name, bytes] of allFonts) {
-                    engine.load_font(name, bytes);
-                }
-                const allImages = new Map(this._images);
-                for (const [key, src] of assetSrcsOfDocument(input, 'images')) {
-                    if (!allImages.has(key)) {
-                        try {
-                            allImages.set(key, (0, node_fs_1.readFileSync)(src));
-                        }
-                        catch { /* skip unresolvable image */ }
+            }
+            for (const [key, src] of assetSrcsOfDocument(input, 'images')) {
+                if (!images.has(key)) {
+                    try {
+                        images.set(key, (0, node_fs_1.readFileSync)(src));
                     }
+                    catch { /* skip unresolvable image */ }
                 }
-                for (const [name, bytes] of allImages) {
-                    engine.load_image(name, bytes);
-                }
-                this._loadMarkdownStyles(engine, markdownStylesSrcsOfDocument(input));
-                this._loadFiles(engine, fileSrcsOfDocument(input));
-                pdf = engine.render_tree_pdf(json, ...(0, _shared_1.encryptionArguments)(callOptions, secureRandomBytes));
             }
+            markdownStyles = this._markdownStylesFor(markdownStylesSrcsOfDocument(input));
+            files = this._filesFor(fileSrcsOfDocument(input));
+            profiles = this._profilesFor(assetSrcsOfDocument(input, 'profiles'));
+            document = { tree: JSON.stringify(input) };
         }
-        catch (e) {
-            engine.free();
-            if (e instanceof LpdfRenderError)
-                throw e;
-            const msg = e instanceof Error ? e.message : String(e);
-            throw new LpdfRenderError(msg);
-        }
-        engine.free();
-        return pdf;
+        return {
+            licenseKey: this._licenseKey,
+            now: nowUnix(),
+            maxMemoryMb: this._maxMemoryMb,
+            createdOn: callOptions.createdOn,
+            fonts,
+            images,
+            files,
+            profiles,
+            markdownStyles,
+            document,
+            encryption: (0, _shared_1.encryptionArguments)(callOptions, secureRandomBytes),
+        };
     }
 }
 exports.PdfEngine = PdfEngine;
@@ -269,7 +352,7 @@ function xmlElements(xml, tag) {
     }
     return elements;
 }
-/** The `ref ?? name → src` pairs of the `<font>`, `<image>` or `<file>` elements in XML. */
+/** The `ref ?? name → src` pairs of the `<font>`, `<image>`, `<file>` or `<profile>` elements in XML. */
 function extractAssetSrcs(xml, tag) {
     const result = new Map();
     for (const attributes of xmlElements(xml, tag)) {
@@ -315,7 +398,7 @@ function fileSrcsOfDocument(document) {
     }
     return result;
 }
-/** The `ref ?? name → src` pairs of the fonts or images a document declares in `attrs.assets`. */
+/** The `ref ?? name → src` pairs of the fonts, images or color profiles a document declares in `attrs.assets`. */
 function assetSrcsOfDocument(document, kind) {
     const result = new Map();
     const declared = document.attrs['assets']?.[kind] ?? [];

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { PdfEngine, LpdfRenderError } from './engine';
 export type { RenderOptions, EngineOptions } from './_shared';
-export { FieldType, Pin, Orientation, SectionType, FootnoteCounter, Cipher, Permission, FileRelationship, BuiltinFont, PageScope, } from './constants';
+export type { StampAttr } from './stamp';
+export { FieldType, Pin, Orientation, SectionType, FootnoteCounter, ColumnFill, Cipher, Permission, FileRelationship, BuiltinFont, PageScope, } from './constants';
 export type { PdfDocument, LpdfSectionNode, LpdfSectionChild, LpdfLayoutBlock, DocumentTokens, TokenSlot, TokenRow, DocumentAssets, DocumentMeta, DocumentOutput, SectionAttr, DocumentAttr, } from './kit';
-export type { ColumnAttr, RowAttr, GridAttr, ListAttr, LiAttr, FrameAttr, LinkAttr, TableAttr, TheadAttr, TrAttr, TdAttr, TextAttr, CodeAttr, SpanAttr, CodeSpanAttr, DividerAttr, ImgAttr, ShapeAttr, BarcodeAttr, RegionAttr, FieldAttr, BookmarkAttr, LayerAttr, RectAttr, CircleAttr, EllipseAttr, LineAttr, PathAttr, TextAtAttr, ImgAtAttr, BarcodeAtAttr, FontAttr, ImageAttr, FileAttr, LayoutAttr, GradientToken, GradientStop, MarkdownAttr, MarkdownStylesAttr, MarkdownH1Attr, MarkdownH2Attr, MarkdownH3Attr, MarkdownH4Attr, MarkdownH5Attr, MarkdownH6Attr, MarkdownPAttr, MarkdownCodeAttr, MarkdownQuoteAttr, MarkdownLiAttr, MarkdownAAttr, MarkdownStrongAttr, MarkdownEmAttr, MarkdownDelAttr, MarkdownTableAttr, MarkdownThAttr, MarkdownTdAttr, } from './attrs';
+export type { ColumnAttr, RowAttr, GridAttr, ListAttr, LiAttr, FrameAttr, LinkAttr, TableAttr, TheadAttr, TrAttr, TdAttr, TextAttr, CodeAttr, SpanAttr, CodeSpanAttr, DividerAttr, ImgAttr, ShapeAttr, BarcodeAttr, RegionAttr, FieldAttr, BookmarkAttr, LayerAttr, RectAttr, CircleAttr, EllipseAttr, LineAttr, PathAttr, TextAtAttr, ImgAtAttr, BarcodeAtAttr, FontAttr, ImageAttr, FileAttr, ProfileAttr, LayoutAttr, GradientToken, GradientStop, RulingToken, RulingLines, MarkdownAttr, MarkdownStylesAttr, MarkdownH1Attr, MarkdownH2Attr, MarkdownH3Attr, MarkdownH4Attr, MarkdownH5Attr, MarkdownH6Attr, MarkdownPAttr, MarkdownCodeAttr, MarkdownQuoteAttr, MarkdownLiAttr, MarkdownAAttr, MarkdownStrongAttr, MarkdownEmAttr, MarkdownDelAttr, MarkdownTableAttr, MarkdownThAttr, MarkdownTdAttr, } from './attrs';
 export type { LpdfNode, LpdfContainerNode, LpdfListNode, LpdfLiNode, LpdfTextNode, LpdfCodeNode, LpdfSpanNode, LpdfCodeSpanNode, LpdfFnNode, LpdfDividerNode, LpdfImgNode, LpdfShapeNode, LpdfBarcodeNode, LpdfTableNode, LpdfTheadNode, LpdfTrNode, LpdfTdNode, LpdfRegionNode, LpdfFieldNode, LpdfBookmarkNode, } from './layout';
 export { LMarkdown } from './markdown';
 export type { LpdfMarkdownNode, LpdfMarkdownStylesNode, LpdfMarkdownContentNode, LpdfMarkdownRuleNode, } from './markdown';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NoAttr = exports.L = exports.CanvasTransform = exports.LMarkdown = exports.PageScope = exports.BuiltinFont = exports.FileRelationship = exports.Permission = exports.Cipher = exports.FootnoteCounter = exports.SectionType = exports.Orientation = exports.Pin = exports.FieldType = exports.LpdfRenderError = exports.PdfEngine = void 0;
+exports.NoAttr = exports.L = exports.CanvasTransform = exports.LMarkdown = exports.PageScope = exports.BuiltinFont = exports.FileRelationship = exports.Permission = exports.Cipher = exports.ColumnFill = exports.FootnoteCounter = exports.SectionType = exports.Orientation = exports.Pin = exports.FieldType = exports.LpdfRenderError = exports.PdfEngine = void 0;
 // ── Engine ────────────────────────────────────────────────────────────────────
 var engine_1 = require("./engine");
 Object.defineProperty(exports, "PdfEngine", { enumerable: true, get: function () { return engine_1.PdfEngine; } });
@@ -12,6 +12,7 @@ Object.defineProperty(exports, "Pin", { enumerable: true, get: function () { ret
 Object.defineProperty(exports, "Orientation", { enumerable: true, get: function () { return constants_1.Orientation; } });
 Object.defineProperty(exports, "SectionType", { enumerable: true, get: function () { return constants_1.SectionType; } });
 Object.defineProperty(exports, "FootnoteCounter", { enumerable: true, get: function () { return constants_1.FootnoteCounter; } });
+Object.defineProperty(exports, "ColumnFill", { enumerable: true, get: function () { return constants_1.ColumnFill; } });
 Object.defineProperty(exports, "Cipher", { enumerable: true, get: function () { return constants_1.Cipher; } });
 Object.defineProperty(exports, "Permission", { enumerable: true, get: function () { return constants_1.Permission; } });
 Object.defineProperty(exports, "FileRelationship", { enumerable: true, get: function () { return constants_1.FileRelationship; } });

package/dist/kit-to-xml.js

@@ -19,9 +19,6 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.kitToXml = kitToXml;
-// Load the standalone kit_to_xml export from the compiled WASM module.
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const { kit_to_xml: wasmKitToXml } = require('./wasm/lpdf.js');
 /**
  * Convert an `LpdfDocument` tree (built with `LpdfKit`) into an lpdf XML
  * string.
@@ -33,5 +30,9 @@ const { kit_to_xml: wasmKitToXml } = require('./wasm/lpdf.js');
  * @returns A well-formed XML string with an `<?xml ...?>` declaration.
  */
 function kitToXml(doc) {
-    return wasmKitToXml(JSON.stringify(doc));
+    // The engine is loaded on this thread on first use: a render runs on a worker, which loads it itself, so an app that
+    // only renders loads it once.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const wasm = require('./wasm/lpdf.js');
+    return wasm.kit_to_xml(JSON.stringify(doc));
 }

package/dist/kit.d.ts

@@ -22,7 +22,7 @@
 import type { LpdfBookmarkNode, LpdfNode } from './layout';
 import type { LpdfCanvasLayerNode } from './canvas';
 import type { LpdfMarkdownNode } from './markdown';
-import type { FileAttr, FontAttr, GradientToken, ImageAttr, LayoutAttr } from './attrs';
+import type { FileAttr, FontAttr, GradientToken, ImageAttr, LayoutAttr, ProfileAttr, RulingToken } from './attrs';
 import { type AttrValue } from './_shared';
 /** A slot of a token row, from the smallest to the largest. */
 export type TokenSlot = 'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl';
@@ -31,6 +31,11 @@ export type TokenRow<T> = Partial<Record<TokenSlot, T>>;
 export interface DocumentTokens {
     colors?: Record<string, string>;
     gradients?: Record<string, GradientToken>;
+    /**
+     * Lines a section draws on every page with `ruling: 'name'`, by name: `{ graph: { origin: 'margin', lines: [{ step:
+     * '5mm' }, { step: '25mm', color: '#b5c4d6' }] } }`. Each set of lines is cut by a step or a count, in x, in y or both.
+     */
+    rulings?: Record<string, RulingToken>;
     /**
      * Names for the slots of the scale, each to the slot it stands for: `{ caption: 'xs' }` lets `fontSize: 'caption'`
      * mean the text size `xs`, and `gap: 'caption'` the space `xs`. A name is lowercase letters, digits and `-`,
@@ -49,12 +54,18 @@ export interface DocumentTokens {
     lineHeight?: TokenRow<number>;
 }
 /**
- * The fonts and images the document declares, as the `assets` element of the XML does. A font or image
- * is picked by its `name`: text sets `font` to a font's name, an `img` sets `name` to an image's.
+ * The fonts, images and color profiles the document declares, as the `assets` element of the XML does. A font or
+ * image is picked by its `name`: text sets `font` to a font's name, an `img` sets `name` to an image's, and the
+ * output's `profile` names a profile.
  */
 export interface DocumentAssets {
     fonts?: FontAttr[];
     images?: ImageAttr[];
+    /**
+     * ICC color profiles: the profile of the printing press a PDF/X document is made for, which the printer gives out.
+     * Each is read from its `src`, or loaded with `loadProfile` under its `ref` or name.
+     */
+    profiles?: ProfileAttr[];
 }
 export interface DocumentMeta {
     title?: string;
@@ -62,6 +73,11 @@ export interface DocumentMeta {
     subject?: string;
     keywords?: string;
     creator?: string;
+    /**
+     * The language the document is written in, as a language tag such as `en-US`. A PDF/UA document needs it, and a
+     * PDF/A document of level a takes it only as a language tag.
+     */
+    lang?: string;
 }
 /**
  * How the PDF file is written, as the `output` element of the XML is: whether it is encrypted, and what a reader
@@ -78,24 +94,90 @@ export interface DocumentOutput {
     allow?: string;
     /**
      * Writes the PDF as PDF/A, the standard for files kept for the long term: `2b`, or `2u` when its text must also
-     * be searchable. The render needs `createdOn`, and every text a font of `assets`. What PDF/A cannot hold is an
-     * error that says what to change: a built-in font, a CMYK color, a form field, a barcode's digits, `encrypt`.
+     * be searchable, or `2a` when it must also be tagged, and `3a`, `3b` or `3u` to carry attachments of any kind. The
+     * render needs `createdOn`, and every text a font of `assets`. Level a tags the file as `pdfua` does, without
+     * PDF/UA's checks: add `pdfua` for a file a screen reader can use. What PDF/A cannot hold is an error that says what
+     * to change: a built-in font, a CMYK color, a form field, a barcode's digits, `encrypt`, attachments in part 2, and
+     * in level a a `lang` that is not a language tag and a character of Unicode's private use area. With `3a`, `3b` or
+     * `3u`, an attachment named `factur-x.xml`, or `xrechnung.xml` for the XRECHNUNG profile, makes the file a Factur-X
+     * or ZUGFeRD e-invoice: the engine reads the profile from BT-24 of that XML and names the invoice in the file's
+     * metadata. The XML is attached as given, and its content is not checked.
      */
     pdfa?: string;
+    /**
+     * Writes the PDF as PDF/UA-1, a tagged PDF a screen reader can read: `1`. It combines with `pdfa`. The render
+     * needs `createdOn`, the meta a `title` and a `lang`, every image and barcode of the layout an `alt`, and every
+     * text a font of `assets`. What PDF/UA cannot hold is an error that says what to change.
+     */
+    pdfua?: string;
+    /**
+     * Writes the PDF as PDF/X-4, for a commercial printer: `4`. It needs `profile`, and combines with `pdfua`. Every
+     * page gets a TrimBox and a BleedBox, RGB is tied to sRGB, and links print as text, as PDF/X allows nothing
+     * clickable. The render needs `createdOn`, the meta a `title`, and every text a font of `assets`. What PDF/X cannot
+     * hold is an error that says what to change: a profile that is not a printer profile, a built-in font, a form
+     * field, a CMYK color with a profile that is not a CMYK one, `encrypt`, `pdfa`, attachments.
+     */
+    pdfx?: string;
+    /** The profile of `assets` that a PDF/X file is made for: the ICC profile of the printing press. It needs `pdfx`. */
+    profile?: string;
+    /**
+     * Writes the PDF linearized, for fast web view: page 1 comes first in the file, with hints that say where every
+     * other page is, so a viewer that fetches the file by byte ranges, as a browser does, shows page 1 while the rest
+     * downloads. Each page then names only the fonts and images it draws. With `encrypt` the file is encrypted first
+     * and linearized last. Any change to the file afterwards, such as a stamp, ends the linearization.
+     */
+    linearize?: boolean;
+    /**
+     * Refuses, in a Factur-X e-invoice, the attachments the Factur-X spec does not allow: an invoice file whose `mime`
+     * is not `text/xml`, an invoice file whose `relationship` its profile does not allow, and another file with no
+     * `mime` or one that is not of a format the spec lists (PDF, TXT, GIF, TIFF, JPG, CSV, XML, JSON, XLS, XLSX, ODS).
+     * Without it, every file is written as the document gives it. It does nothing in a document without
+     * `factur-x.xml` or `xrechnung.xml`. It is `facturx-strict` in the XML.
+     */
+    facturxStrict?: boolean;
 }
 export interface SectionAttr {
     size?: string;
     orientation?: string;
+    /** How far this section's pages reach past their trim edge, such as `5mm`. Overrides the document's; `0mm` takes it away. */
+    bleed?: string;
     background?: string;
     title?: string;
     debug?: boolean;
     type?: string;
     tocIndentStep?: string;
     footnoteCounter?: string;
+    /**
+     * The number of the section's first page, which starts a new run of pages: `1` restarts the count. Without it the
+     * pages count on from the section before. `{page}` prints a page's number, and `{pages}` how many pages its run has.
+     */
+    pageStart?: number;
+    /**
+     * How the section's page numbers are written: `decimal`, `lower-alpha`, `upper-alpha`, `lower-roman` or
+     * `upper-roman`. Without it the section keeps the format before.
+     */
+    pageFormat?: string;
+    /** Text before the section's page numbers, such as `A-`. Without it the section keeps the prefix before; `''` takes it away. */
+    pagePrefix?: string;
+    /** Sets the section's flow in this many columns, 1 to 12, each filled like a small page, left to right. */
+    columns?: number;
+    /** The space between two columns, a space token or a length; `l` by default. */
+    columnGap?: string;
+    /** A line in the middle of each gap between two columns, as a border, such as `0.5pt #ccc`. */
+    columnRule?: string;
+    /** How the last page's columns fill: `ColumnFill.Auto`, in order, the default, or `ColumnFill.Balance`, levelled. */
+    columnFill?: string;
+    /** The name of a ruling of the tokens, whose lines are drawn on every page of the section, under everything else. */
+    ruling?: string;
 }
 export interface DocumentAttr {
     size?: string;
     orientation?: string;
+    /**
+     * How far each page reaches past its trim edge, such as `3mm`, for a background or an image that runs off the page
+     * when it is cut. The page grows by it and its background fills it; the layout keeps to the trimmed page.
+     */
+    bleed?: string;
     background?: string;
     font?: string;
     assets?: DocumentAssets;

package/dist/kit.js

@@ -34,6 +34,13 @@ function section(attrs, nodes = []) {
         nodes,
     };
 }
+/**
+ * The rulings of the tokens as the document tree takes them: a set of lines names its attributes as an element does,
+ * so `stepX` is `step-x`.
+ */
+function rulingsTree(rulings) {
+    return Object.fromEntries(Object.entries(rulings).map(([name, { lines, ...ruling }]) => [name, { ...ruling, lines: (lines ?? []).map((set) => (0, _shared_1.buildAttrs)(set)) }]));
+}
 function document(attrs, nodes = []) {
     const { assets, tokens, meta, output, attachments, ...restOpts } = attrs ?? {};
     const attrsObj = {
@@ -44,17 +51,19 @@ function document(attrs, nodes = []) {
     if (tokens !== undefined) {
         // A factor of the line-height row and a gradient's angle are numbers, which JSON can't hold as NaN or infinity.
         (0, _shared_1.assertFiniteIn)('tokens', tokens);
-        const { textSize, lineHeight, ...rest } = tokens;
+        const { textSize, lineHeight, rulings, ...rest } = tokens;
         attrsObj['tokens'] = {
             ...rest,
             ...(textSize !== undefined ? { 'text-size': textSize } : {}),
             ...(lineHeight !== undefined ? { 'line-height': lineHeight } : {}),
+            ...(rulings !== undefined ? { rulings: rulingsTree(rulings) } : {}),
         };
     }
     if (meta !== undefined)
         attrsObj['meta'] = meta;
+    // The engine reads the schema's names: `facturxStrict` is `facturx-strict`.
     if (output !== undefined)
-        attrsObj['output'] = output;
+        attrsObj['output'] = (0, _shared_1.buildAttrs)(output);
     if (attachments !== undefined)
         attrsObj['attachments'] = attachments;
     return {

package/dist/render-error.d.ts

@@ -0,0 +1,11 @@
+/** What a render that crashes the engine rejects with, the same in every SDK of Lpdf. */
+export declare const ENGINE_CRASHED: string;
+/**
+ * Thrown when the lpdf engine returns a layout or parse error, a render runs past its timeout or its memory cap, or
+ * the engine crashes.
+ */
+export declare class LpdfRenderError extends Error {
+    /** For an engine that crashed, the error the engine itself gave, such as `RuntimeError: unreachable`. */
+    readonly cause?: string;
+    constructor(message: string, cause?: string);
+}