@lpdfio/lpdf 0.32.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,20 +53,19 @@ 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();
@@ -43,6 +73,8 @@ class PdfEngine {
         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.
@@ -65,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="…">`.
@@ -122,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)) {
@@ -135,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))
@@ -152,18 +182,16 @@ 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;
     }
     /**
-     * Hand the engine 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.
+     * 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.
      */
-    _loadProfiles(engine, srcs) {
+    _profilesFor(srcs) {
         const profiles = new Map(this._profiles);
         for (const [key, src] of srcs) {
             if (profiles.has(key))
@@ -172,12 +200,10 @@ class PdfEngine {
                 profiles.set(key, (0, node_fs_1.readFileSync)(src));
             }
             catch (e) {
-                throw new LpdfRenderError(`profile '${key}' of <assets>: cannot read its src '${src}': ${e instanceof Error ? e.message : String(e)}`);
+                throw new render_error_1.LpdfRenderError(`profile '${key}' of <assets>: cannot read its src '${src}': ${e instanceof Error ? e.message : String(e)}`);
             }
         }
-        for (const [key, bytes] of profiles) {
-            engine.load_profile(key, bytes);
-        }
+        return profiles;
     }
     _throwIfDisposed() {
         if (this._disposed)
@@ -185,91 +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'));
-                this._loadProfiles(engine, extractAssetSrcs(xml, 'profile'));
-                // 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));
-                this._loadProfiles(engine, assetSrcsOfDocument(input, 'profiles'));
-                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;

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, ProfileAttr, 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, ProfileAttr } 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 `-`,
@@ -68,7 +73,10 @@ 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. */
+    /**
+     * 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;
 }
 /**
@@ -86,8 +94,14 @@ 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;
     /**
@@ -113,6 +127,14 @@ export interface DocumentOutput {
      * 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;
@@ -137,6 +159,16 @@ export interface SectionAttr {
     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;

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);
+}

package/dist/render-error.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LpdfRenderError = exports.ENGINE_CRASHED = void 0;
+/** What a render that crashes the engine rejects with, the same in every SDK of Lpdf. */
+exports.ENGINE_CRASHED = 'The engine crashed during the render. This is a bug in Lpdf, or the render ran out of memory before its cap ' +
+    'stopped it: please report it with the document at https://github.com/lpdfio/lpdf/issues.';
+/**
+ * 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.
+ */
+class LpdfRenderError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = 'LpdfRenderError';
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+exports.LpdfRenderError = LpdfRenderError;

package/dist/render-job.d.ts

@@ -0,0 +1,67 @@
+/** The engine's render calls, as wasm-bindgen exposes them in both builds. */
+export interface WasmRenderEngine {
+    render_pdf(xml: string, json_data: string | null, user_password: string | null, owner_password: string | null, skip_encryption: boolean, entropy: Uint8Array): Uint8Array;
+    render_tree_pdf(json: string, user_password: string | null, owner_password: string | null, skip_encryption: boolean, entropy: Uint8Array): Uint8Array;
+    stamp(pdf: Uint8Array, stamps: string): Uint8Array;
+    load_font(name: string, bytes: Uint8Array): void;
+    load_image(name: string, bytes: Uint8Array): void;
+    load_file(name: string, bytes: Uint8Array): void;
+    load_profile(name: string, bytes: Uint8Array): void;
+    load_markdown_styles(src: string, xml: string): void;
+    set_created_on(iso: string): void;
+    set_now(unix: bigint): void;
+    set_max_memory_mb(mb: number): void;
+    free(): void;
+}
+/** The user password, the owner password, `skipEncryption` and the entropy, in the order the render calls take them. */
+export type EncryptionArguments = [string | null, string | null, boolean, Uint8Array];
+/**
+ * One render: the document and every file it needs, already read, since a worker reads nothing itself. A stamp runs as
+ * a render does, with the PDF and the JSON of its stamps as its document and their PNGs as its images.
+ */
+export interface RenderJob {
+    licenseKey: string;
+    /** The host's clock in Unix seconds, for the key's expiry. */
+    now: bigint;
+    /** The megabytes the render may allocate. */
+    maxMemoryMb: number;
+    createdOn: string | undefined;
+    fonts: Map<string, Uint8Array>;
+    images: Map<string, Uint8Array>;
+    files: Map<string, Uint8Array>;
+    profiles: Map<string, Uint8Array>;
+    markdownStyles: Map<string, string>;
+    /** An XML document with its data as JSON, a document tree as JSON, or a PDF to stamp. */
+    document: {
+        xml: string;
+        data: string | null;
+    } | {
+        tree: string;
+    } | {
+        pdf: Uint8Array;
+        stamps: string;
+    };
+    encryption: EncryptionArguments;
+}
+/**
+ * What the worker sends back: the PDF, or the engine's error. `broken` says that the engine trapped, after which its
+ * memory can't be trusted, so the worker is replaced before the next render. A crash of the engine has the error every
+ * SDK gives for one, and the engine's own as its `cause`.
+ */
+export type RenderReply = {
+    pdf: Uint8Array;
+} | {
+    error: string;
+    broken: boolean;
+    cause?: string;
+};
+/**
+ * Runs a render on an engine of its own, which is freed after it, and returns the PDF or the error. It never throws: a
+ * failure is the reply.
+ */
+export declare function runRenderJob(createEngine: (licenseKey: string) => WasmRenderEngine, job: RenderJob): RenderReply;
+/**
+ * The buffers a reply moves to the other thread instead of copying: the PDF's, when the PDF has a buffer of its own.
+ * A view into a larger buffer, such as the engine's memory, is copied.
+ */
+export declare function transferList(reply: RenderReply): ArrayBuffer[];