@lpdfio/lpdf 0.30.0 → 0.32.0

package/dist/engine.js

@@ -3,6 +3,7 @@ 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 _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/.
@@ -29,24 +30,19 @@ class LpdfRenderError extends Error {
     }
 }
 exports.LpdfRenderError = LpdfRenderError;
-/**
- * Hands the engine the encryption options. AES-256 needs random bytes, which the engine does not
- * make: they come from Node's secure generator, 32 bytes for each render.
- */
-function configureEncryption(engine, options) {
-    const algorithm = options.algorithm ?? 'aes-256';
-    const entropy = algorithm === 'aes-256' ? new Uint8Array((0, node_crypto_1.randomBytes)(32)) : new Uint8Array(0);
-    const permsJson = JSON.stringify(options.permissions ?? {});
-    engine.set_encryption(options.userPassword, options.ownerPassword, permsJson, algorithm, entropy);
+/** 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() {
         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._encrypt = null;
     }
     /**
      * Set the license key. Returns `this` for chaining.
@@ -90,30 +86,31 @@ class PdfEngine {
         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.
+     * Register the bytes of a file the document carries, for the `<file>` of its `<attachments>` whose `ref`, or with
+     * no ref whose name, is `name`. The PDF carries them as they are. Call before `render`. Returns `this` for chaining.
      */
-    loadMarkdownStyles(src, text) {
+    loadFile(name, bytes) {
         this._throwIfDisposed();
-        this._markdownStyles.set(src, text);
+        this._files.set(name, bytes);
         return this;
     }
     /**
-     * Configure encryption for all subsequent `render` calls: AES-256 unless
-     * `options.algorithm` says `'rc4-128'`. Returns `this` for chaining.
+     * 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.
      */
-    setEncryption(options) {
+    loadProfile(name, bytes) {
         this._throwIfDisposed();
-        this._encrypt = options;
+        this._profiles.set(name, bytes);
         return this;
     }
     /**
-     * Remove any previously configured encryption.
-     * Returns `this` for chaining.
+     * 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.
      */
-    clearEncryption() {
+    loadMarkdownStyles(src, text) {
         this._throwIfDisposed();
-        this._encrypt = null;
+        this._markdownStyles.set(src, text);
         return this;
     }
     /**
@@ -142,6 +139,46 @@ class PdfEngine {
             engine.load_markdown_styles(src, text);
         }
     }
+    /**
+     * 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.
+     */
+    _loadFiles(engine, srcs) {
+        const files = new Map(this._files);
+        for (const [key, src] of srcs) {
+            if (files.has(key))
+                continue;
+            try {
+                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)}`);
+            }
+        }
+        for (const [key, bytes] of files) {
+            engine.load_file(key, bytes);
+        }
+    }
+    /**
+     * 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.
+     */
+    _loadProfiles(engine, 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 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);
+        }
+    }
     _throwIfDisposed() {
         if (this._disposed)
             throw new Error('PdfEngine has been disposed.');
@@ -176,6 +213,8 @@ class PdfEngine {
                     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)) {
@@ -185,11 +224,8 @@ class PdfEngine {
                         catch { /* skip unresolvable image */ }
                     }
                 }
-                if (this._encrypt) {
-                    configureEncryption(engine, this._encrypt);
-                }
                 const dataJson = callOptions.data != null ? JSON.stringify(callOptions.data) : null;
-                pdf = engine.render_pdf(xml, dataJson);
+                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
@@ -220,14 +256,15 @@ class PdfEngine {
                     engine.load_image(name, bytes);
                 }
                 this._loadMarkdownStyles(engine, markdownStylesSrcsOfDocument(input));
-                if (this._encrypt) {
-                    configureEncryption(engine, this._encrypt);
-                }
-                pdf = engine.render_tree_pdf(json);
+                this._loadFiles(engine, fileSrcsOfDocument(input));
+                this._loadProfiles(engine, assetSrcsOfDocument(input, 'profiles'));
+                pdf = engine.render_tree_pdf(json, ...(0, _shared_1.encryptionArguments)(callOptions, secureRandomBytes));
             }
         }
         catch (e) {
             engine.free();
+            if (e instanceof LpdfRenderError)
+                throw e;
             const msg = e instanceof Error ? e.message : String(e);
             throw new LpdfRenderError(msg);
         }
@@ -237,16 +274,40 @@ class PdfEngine {
 }
 exports.PdfEngine = PdfEngine;
 // ── Helpers ───────────────────────────────────────────────────────────────────
-/** Extract `ref??name → src` pairs from `<font>` or `<image>` tags in XML. */
+// Comments and CDATA sections, whose text is not markup: a <file> shown in a Markdown block is text, not a file.
+const XML_NOT_MARKUP_RE = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>/g;
+const XML_ATTRIBUTE_RE = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+const XML_ENTITY_RE = /&(?:(amp|lt|gt|quot|apos)|#(\d+)|#x([0-9a-fA-F]+));/g;
+const XML_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+/** An attribute value as the XML means it, with its entities and character references decoded. */
+function decodeXml(value) {
+    return value.replace(XML_ENTITY_RE, (_, name, decimal, hex) => 
+    // XML_ENTITY_RE matches exactly one of its three groups, so without a name or a decimal there is a hex.
+    name ? XML_ENTITIES[name] : String.fromCodePoint(parseInt(decimal ?? hex, decimal ? 10 : 16)));
+}
+/**
+ * The attributes of each `<tag>` element in XML, read as the engine reads them: comments and CDATA sections are left
+ * out, a quoted value may hold a `>`, either quote may be used, and the values are decoded.
+ */
+function xmlElements(xml, tag) {
+    const elements = [];
+    // Attribute values may contain '>', so quoted runs are matched whole.
+    const re = new RegExp(`<${tag}\\b((?:[^>"']|"[^"]*"|'[^']*')*)>`, 'g');
+    for (const match of xml.replace(XML_NOT_MARKUP_RE, '').matchAll(re)) {
+        const attributes = new Map();
+        for (const attribute of match[1].matchAll(XML_ATTRIBUTE_RE)) {
+            attributes.set(attribute[1], decodeXml(attribute[2] ?? attribute[3]));
+        }
+        elements.push(attributes);
+    }
+    return elements;
+}
+/** The `ref ?? name → src` pairs of the `<font>`, `<image>`, `<file>` or `<profile>` elements in XML. */
 function extractAssetSrcs(xml, tag) {
     const result = new Map();
-    const re = tag === 'font' ? /<font\s[^>]*>/g : /<image\s[^>]*>/g;
-    for (const match of xml.matchAll(re)) {
-        const t = match[0];
-        const name = /\bname="([^"]*)"/.exec(t)?.[1];
-        const ref = /\bref="([^"]*)"/.exec(t)?.[1];
-        const src = /\bsrc="([^"]*)"/.exec(t)?.[1];
-        const key = ref ?? name;
+    for (const attributes of xmlElements(xml, tag)) {
+        const key = attributes.get('ref') ?? attributes.get('name');
+        const src = attributes.get('src');
         if (key && src)
             result.set(key, src);
     }
@@ -255,8 +316,8 @@ function extractAssetSrcs(xml, tag) {
 /** The `src` of each `<markdown-styles>` in XML. */
 function markdownStylesSrcs(xml) {
     const srcs = [];
-    for (const match of xml.matchAll(/<markdown-styles\s[^>]*>/g)) {
-        const src = /\bsrc="([^"]*)"/.exec(match[0])?.[1];
+    for (const attributes of xmlElements(xml, 'markdown-styles')) {
+        const src = attributes.get('src');
         if (src)
             srcs.push(src);
     }
@@ -270,14 +331,24 @@ function markdownStylesSrcsOfDocument(document) {
             if (child.type !== 'markdown')
                 continue;
             for (const part of child.nodes) {
-                if (part.type === 'markdown-styles' && part.attrs['src'])
-                    srcs.push(part.attrs['src']);
+                const src = part.type === 'markdown-styles' ? part.attrs['src'] : undefined;
+                if (typeof src === 'string' && src)
+                    srcs.push(src);
             }
         }
     }
     return srcs;
 }
-/** The `ref ?? name → src` pairs of the fonts or images a document declares in `attrs.assets`. */
+/** The `ref ?? name → src` pairs of the files a document carries in `attrs.attachments`. */
+function fileSrcsOfDocument(document) {
+    const result = new Map();
+    for (const { name, ref, src } of document.attrs['attachments'] ?? []) {
+        if (src)
+            result.set(ref ?? name, src);
+    }
+    return result;
+}
+/** 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,9 +1,8 @@
 export { PdfEngine, LpdfRenderError } from './engine';
-export type { EncryptAlgorithm, EncryptPermissions, EncryptOptions } from './engine';
 export type { RenderOptions, EngineOptions } from './_shared';
-export { FieldType, Pin, Orientation, SectionType, FootnoteCounter, BuiltinFont, PageScope } from './constants';
-export type { PdfDocument, LpdfSectionNode, LpdfSectionChild, LpdfLayoutBlock, DocumentTokens, GradientToken, GradientStop, DocumentAssets, DocumentMeta, 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, LayoutAttr, MarkdownAttr, MarkdownStylesAttr, MarkdownH1Attr, MarkdownH2Attr, MarkdownH3Attr, MarkdownH4Attr, MarkdownH5Attr, MarkdownH6Attr, MarkdownPAttr, MarkdownCodeAttr, MarkdownQuoteAttr, MarkdownLiAttr, MarkdownAAttr, MarkdownStrongAttr, MarkdownEmAttr, MarkdownDelAttr, MarkdownTableAttr, MarkdownThAttr, MarkdownTdAttr, } from './attrs';
+export { FieldType, Pin, Orientation, SectionType, FootnoteCounter, 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 { 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.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.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,9 @@ 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, "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; } });
 Object.defineProperty(exports, "BuiltinFont", { enumerable: true, get: function () { return constants_1.BuiltinFont; } });
 Object.defineProperty(exports, "PageScope", { enumerable: true, get: function () { return constants_1.PageScope; } });
 // ── Markdown ──────────────────────────────────────────────────────────────────

package/dist/kit.d.ts

@@ -22,24 +22,12 @@
 import type { LpdfBookmarkNode, LpdfNode } from './layout';
 import type { LpdfCanvasLayerNode } from './canvas';
 import type { LpdfMarkdownNode } from './markdown';
-import type { FontAttr, ImageAttr, LayoutAttr } from './attrs';
-/** One color of a gradient: `color` is hex or a color token, at an `offset` from `'0%'` to `'100%'`. */
-export interface GradientStop {
-    offset: string;
-    color: string;
-}
-/**
- * A gradient of the tokens, which a background or a fill uses as `gradient:name`. Give `from` and `to` for two
- * colors, or `stops` for more. `angle` is the direction of a linear gradient in degrees: 0 runs top to bottom
- * and 90 left to right. A radial gradient runs from the center of the box out to its farthest corner.
- */
-export interface GradientToken {
-    type: 'linear' | 'radial';
-    from?: string;
-    to?: string;
-    angle?: number | string;
-    stops?: GradientStop[];
-}
+import type { FileAttr, FontAttr, GradientToken, ImageAttr, LayoutAttr, ProfileAttr } 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';
+/** A token row: a value for each slot it sets. */
+export type TokenRow<T> = Partial<Record<TokenSlot, T>>;
 export interface DocumentTokens {
     colors?: Record<string, string>;
     gradients?: Record<string, GradientToken>;
@@ -49,23 +37,30 @@ export interface DocumentTokens {
      * starting with a letter, and is neither a slot nor `fill` or `full`.
      */
     aliases?: Record<string, string>;
-    space?: Record<string, string>;
-    grid?: Record<string, string>;
-    border?: Record<string, string>;
-    radius?: Record<string, string>;
-    width?: Record<string, string>;
+    space?: TokenRow<string>;
+    grid?: TokenRow<string>;
+    border?: TokenRow<string>;
+    radius?: TokenRow<string>;
+    width?: TokenRow<string>;
     /** The heights `height` names: `{ xs: '16pt', s: '24pt', m: '32pt', l: '48pt', xl: '64pt', xxl: '96pt' }` by default. */
-    height?: Record<string, string>;
-    textSize?: Record<string, string>;
-    lineHeight?: Record<string, string>;
+    height?: TokenRow<string>;
+    textSize?: TokenRow<string>;
+    /** The factors `lineHeight` names, each a number above 0: `{ xs: 1, s: 1.1, m: 1.2, l: 1.4, xl: 1.6, xxl: 2 }` by default. */
+    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;
@@ -73,37 +68,107 @@ 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. */
+    lang?: string;
+}
+/**
+ * How the PDF file is written, as the `output` element of the XML is: whether it is encrypted, and what a reader
+ * may do with it, and the standard it meets. The passwords are not here: they come with the render call.
+ */
+export interface DocumentOutput {
+    /** The cipher the PDF is encrypted with, `aes-256` or `rc4-128` (`Cipher`). Without it the PDF is not encrypted. */
+    encrypt?: string;
+    /**
+     * What a reader may do without the owner password, separated by spaces (`Permission`): `all`, or any of
+     * `print`, `modify`, `copy`, `annotate`, `fill-forms`, `accessibility`, `assemble`. A permission comes only from
+     * naming it: without `allow`, or with `''`, nothing is allowed, and `all` allows everything. It needs `encrypt`.
+     */
+    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`.
+     */
+    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;
 }
 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?: 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;
 }
 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;
     tokens?: DocumentTokens;
     meta?: DocumentMeta;
-    debug?: string;
+    output?: DocumentOutput;
+    /**
+     * Files the PDF carries inside it, as the `attachments` element of the XML does: a reader lists them in its
+     * attachments panel. Each file's bytes are read from its `src`, or loaded with `loadFile` under its `ref` or name.
+     */
+    attachments?: FileAttr[];
+    debug?: boolean;
     footnoteCounter?: string;
 }
 /** A layout block — wraps an ordered list of layout nodes. */
 export interface LpdfLayoutBlock {
     type: 'layout';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: LpdfNode[];
 }
 export interface LpdfSectionNode {
     type: 'section';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: LpdfSectionChild[];
 }
 /**

package/dist/kit.js

@@ -35,13 +35,15 @@ function section(attrs, nodes = []) {
     };
 }
 function document(attrs, nodes = []) {
-    const { assets, tokens, meta, ...restOpts } = attrs ?? {};
+    const { assets, tokens, meta, output, attachments, ...restOpts } = attrs ?? {};
     const attrsObj = {
         ...(0, _shared_1.buildAttrs)(restOpts),
     };
     if (assets !== undefined)
         attrsObj['assets'] = assets;
     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;
         attrsObj['tokens'] = {
             ...rest,
@@ -51,6 +53,10 @@ function document(attrs, nodes = []) {
     }
     if (meta !== undefined)
         attrsObj['meta'] = meta;
+    if (output !== undefined)
+        attrsObj['output'] = output;
+    if (attachments !== undefined)
+        attrsObj['attachments'] = attachments;
     return {
         version: 1,
         type: 'document',

package/dist/layout.d.ts

@@ -1,98 +1,99 @@
 import type { ColumnAttr, RowAttr, GridAttr, ListAttr, LiAttr, FrameAttr, LinkAttr, TableAttr, TheadAttr, TrAttr, TdAttr, TextAttr, CodeAttr, SpanAttr, CodeSpanAttr, DividerAttr, ImgAttr, ShapeAttr, BarcodeAttr, FieldAttr, RegionAttr, BookmarkAttr } from './attrs';
+import { type AttrValue } from './_shared';
 export interface LpdfSpanNode {
     type: 'span';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: string[];
 }
 /** A run of code inside a text: its words in the code font on a tint. */
 export interface LpdfCodeSpanNode {
     type: 'code-span';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: string[];
 }
 /** A footnote: its words go at the bottom of the page where its number lands. */
 export interface LpdfFnNode {
     type: 'fn';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: (string | LpdfSpanNode)[];
 }
 export interface LpdfContainerNode {
     type: 'column' | 'row' | 'grid' | 'frame' | 'link';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: LpdfNode[];
 }
 /** A list of items, each marked with a bullet or a number the engine gives. */
 export interface LpdfListNode {
     type: 'list';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: LpdfLiNode[];
 }
 /** One item of a list: what a layout holds, beside the item's marker. */
 export interface LpdfLiNode {
     type: 'li';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: LpdfNode[];
 }
 export interface LpdfTextNode {
     type: 'text';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: (string | LpdfSpanNode | LpdfCodeSpanNode | LpdfFnNode)[];
 }
 /** Code in a box. Its strings keep their spaces and lines; its spans color parts of it. */
 export interface LpdfCodeNode {
     type: 'code';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: (string | LpdfSpanNode)[];
 }
 export interface LpdfDividerNode {
     type: 'divider';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export interface LpdfImgNode {
     type: 'img';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export interface LpdfShapeNode {
     type: 'shape';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export interface LpdfBarcodeNode {
     type: 'barcode';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export interface LpdfTheadNode {
     type: 'thead';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: LpdfTdNode[];
 }
 export interface LpdfTrNode {
     type: 'tr';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: LpdfTdNode[];
 }
 export interface LpdfTdNode {
     type: 'td';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: LpdfNode[];
 }
 export interface LpdfTableNode {
     type: 'table';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: (LpdfTheadNode | LpdfTrNode)[];
 }
 export interface LpdfRegionNode {
     type: 'region';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: LpdfNode[];
 }
 export interface LpdfFieldNode {
     type: 'field';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 /** An outline entry and link target that marks the node after it; it draws nothing. */
 export interface LpdfBookmarkNode {
     type: 'bookmark';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export type LpdfNode = LpdfContainerNode | LpdfListNode | LpdfTextNode | LpdfCodeNode | LpdfDividerNode | LpdfTableNode | LpdfImgNode | LpdfShapeNode | LpdfBarcodeNode | LpdfRegionNode | LpdfFieldNode | LpdfBookmarkNode;
 declare function column(attrs: ColumnAttr | null, nodes?: LpdfNode[]): LpdfContainerNode;

package/dist/markdown.d.ts

@@ -1,25 +1,26 @@
 import type { MarkdownAttr, MarkdownStylesAttr, MarkdownH1Attr, MarkdownH2Attr, MarkdownH3Attr, MarkdownH4Attr, MarkdownH5Attr, MarkdownH6Attr, MarkdownPAttr, MarkdownCodeAttr, MarkdownQuoteAttr, MarkdownLiAttr, MarkdownAAttr, MarkdownStrongAttr, MarkdownEmAttr, MarkdownDelAttr, MarkdownTableAttr, MarkdownThAttr, MarkdownTdAttr } from './attrs';
+import { type AttrValue } from './_shared';
 /** A rule of a markdown's styles: the element it is named after, with the attributes it sets. */
 export interface LpdfMarkdownRuleNode {
     type: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'code' | 'quote' | 'li' | 'a' | 'strong' | 'em' | 'del' | 'table' | 'th' | 'td';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 /** The rules that say how the parts of a markdown look, with a file of them in `src` when it has one. */
 export interface LpdfMarkdownStylesNode {
     type: 'markdown-styles';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: LpdfMarkdownRuleNode[];
 }
 /** The Markdown itself, as strings. */
 export interface LpdfMarkdownContentNode {
     type: 'markdown-content';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: string[];
 }
 /** A markdown, which takes the place of a layout in a section and holds only Markdown. */
 export interface LpdfMarkdownNode {
     type: 'markdown';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: (LpdfMarkdownStylesNode | LpdfMarkdownContentNode)[];
 }
 /**