@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Heuberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-  <code>npm i @jasy/zugferd</code> &nbsp;·&nbsp; <code>npx @jasy/cli</code> &nbsp;·&nbsp; MIT
+  <code>npm i @jasy/e-invoice</code> &nbsp;·&nbsp; <code>npx @jasy/cli</code> &nbsp;·&nbsp; MIT
 </p>
 
 ---
@@ -37,24 +37,34 @@ account, no upload, nothing leaves your machine.
 ## You bring the line items. jasy does the rest.
 
 You never compute a total, a VAT breakdown or a rounding again. You hand jasy the line items - it
-**derives** the document totals and the EN-16931 VAT breakdown, spec-correct. That is *why* the
+**derives** the document totals and the EN-16931 VAT breakdown, spec-correct. That is _why_ the
 invoices validate: the amounts are correct **by construction**, so the single biggest class of
 EN-16931 failures (the BR-CO total checks) simply cannot happen.
 
 ```ts
-import { renderZugferd } from "@jasy/zugferd";
+import { renderZugferd } from "@jasy/e-invoice";
 
 const { bytes, xml } = await renderZugferd({
   number: "RE-2026-001",
   issueDate: "2026-06-17",
   currency: "EUR",
-  seller: { name: "Northwind Studio GmbH", vatId: "DE123456789",
-            address: { city: "Berlin", postCode: "10115", country: "DE" } },
-  buyer:  { name: "Globex Corporation Ltd",
-            address: { city: "Munich", postCode: "80331", country: "DE" } },
+  seller: {
+    name: "Northwind Studio GmbH",
+    vatId: "DE123456789",
+    address: { city: "Berlin", postCode: "10115", country: "DE" },
+  },
+  buyer: {
+    name: "Globex Corporation Ltd",
+    address: { city: "Munich", postCode: "80331", country: "DE" },
+  },
   lines: [
-    { name: "Brand identity design", quantity: 2, unit: "HUR", netUnitPrice: 100,
-      vat: { category: "S", ratePercent: 19 } },
+    {
+      name: "Brand identity design",
+      quantity: 2,
+      unit: "HUR",
+      netUnitPrice: 100,
+      vat: { category: "S", ratePercent: 19 },
+    },
   ],
 });
 // bytes -> a valid ZUGFeRD PDF/A-3   ·   xml -> the embedded EN-16931 XML
@@ -107,8 +117,8 @@ const pdf = await renderToBytes(
 ```
 
 Real text layout (Adobe AFM metrics, kerning, word-wrap), flexbox-style `gap` / `justify` / `align`,
-boxes with radius and alpha, images, custom TrueType fonts, and **real pagination** - content that
-overflows flows onto the next page, headers and footers repeat.
+boxes with radius and alpha, images, custom TrueType fonts, **AES-256 password encryption**, and **real
+pagination** - content that overflows flows onto the next page, headers and footers repeat.
 
 ---
 
@@ -122,12 +132,15 @@ verify all of it:
   740 KB font ships as a ~76 KB subset, and the text stays copy- and searchable.
 - **Compression.** Content streams and images are FlateDecode-compressed; the spreadsheets `jasy export`
   writes are real `.xlsx` ZIPs we deflate with our own writer and CRC32, zero dependencies.
+- **AES-256 encryption, pure JS.** Lock a PDF with `renderToBytes(doc, { encrypt: { userPassword } })` - the
+  newest standard handler (AES-256, R6 / ISO 32000-2) via the platform WebCrypto: no native crypto, no deps,
+  the same code in Node **and** the browser. Owner password + permissions optional.
 - **Real font metrics.** Text is laid out with the Adobe AFM metrics of the standard-14 fonts - kerning
-  and word-wrap are *computed*, not guessed.
+  and word-wrap are _computed_, not guessed.
 - **PDF/A-3, matched not approximated.** The conformance graph is hand-built and **passes veraPDF**, the
   official ISO 19005 validator.
 - **Byte-exact round-trips.** Generate and parse are inverses: `generate → parse → regenerate` reproduces
-  the identical XML. 307 tests hold the line.
+  the identical XML. Over 900 tests hold the line across the workspace.
 - **Schematron, local.** The official EN-16931 + XRechnung rules run via saxon-js (the real XSLT, in pure
   JS) - no Java, no upload.
 
@@ -135,18 +148,19 @@ verify all of it:
 
 ## Packages
 
-| Package | What it is |
-| --- | --- |
-| **[@jasy/zugferd](https://www.npmjs.com/package/@jasy/zugferd)** | ZUGFeRD / XRechnung: your data → PDF/A-3 + EN-16931 XML, with local validation. **The prize.** |
-| **[@jasy/cli](https://www.npmjs.com/package/@jasy/cli)** | the `jasy` terminal: read · validate · export, headless **and** interactive |
-| **[@jasy/pdf](https://www.npmjs.com/package/@jasy/pdf)** | the declarative, Flutter-style PDF layout engine that powers them |
+| Package                                                 | What it is                                                                                     |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| **[@jasy/e-invoice](https://npmx.dev/@jasy/e-invoice)** | ZUGFeRD / XRechnung: your data → PDF/A-3 + EN-16931 XML, with local validation. **The prize.** |
+| **[@jasy/cli](https://npmx.dev/@jasy/cli)**             | the `jasy` terminal: read · validate · export, headless **and** interactive                    |
+| **[@jasy/pdf](https://npmx.dev/@jasy/pdf)**             | the declarative, Flutter-style PDF layout engine that powers them                              |
 
 ---
 
 ## Why you can trust it
 
-- **307 tests, green.** The generator and the parser are **byte-exact inverses**:
-  `generate → parse → regenerate` reproduces the identical XML. Nothing is silently lost.
+- **Over 900 tests, green** across the workspace (850 in the engine alone). The generator and the parser
+  are **byte-exact inverses**: `generate → parse → regenerate` reproduces the identical XML. Nothing is
+  silently lost.
 - **The same rules the authorities use** - the official KoSIT EN-16931 + XRechnung Schematron, and the
   official **veraPDF** for the full ISO 19005 (PDF/A) check.
 - **Proven on real third-party invoices**, not only our own.
@@ -158,7 +172,7 @@ verify all of it:
 
 jasy targets the documents that matter here: invoices, reports, quotes, datasheets. It is **not** a
 LaTeX / WeasyPrint replacement - no microtypography, hyphenation or bidi, and arbitrary multi-page flow
-of *any* content is still maturing. For e-invoices (a table, totals, a footer) it is complete - they
+of _any_ content is still maturing. For e-invoices (a table, totals, a footer) it is complete - they
 even paginate. We would rather under-promise and over-deliver in the demo above.
 
 > **Status:** young and pre-1.0. The API can still shift between minor versions. Everything shown here

package/dist/api/args.d.ts

@@ -1,4 +1,4 @@
-import { PDFElement } from "../elements/pdf-element";
+import { PDFElement } from "../elements/pdf-element.js";
 /**
  * Lets a container factory be called either `F(children)` or `F(opts, children)` - the
  * same ergonomic shape across Document/Page/Column/Row/Box. When the first argument is the

package/dist/api/args.js

@@ -1,13 +1,10 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.splitArgs = splitArgs;
 /**
  * Lets a container factory be called either `F(children)` or `F(opts, children)` - the
  * same ergonomic shape across Document/Page/Column/Row/Box. When the first argument is the
  * child array, options default to empty.
  */
-function splitArgs(a, b) {
+export function splitArgs(a, b) {
     if (Array.isArray(a))
         return { opts: {}, children: a };
-    return { opts: a, children: b !== null && b !== void 0 ? b : [] };
+    return { opts: a, children: b ?? [] };
 }

package/dist/api/color.d.ts

@@ -1,11 +1,11 @@
-import { Color } from "../common/color";
+import { Color } from "../common/color.js";
 /**
- * Every way to name a colour. The FORM picks the convention, so there is never a guess
+ * Every way to name a color. The FORM picks the convention, so there is never a guess
  * (locked design §2):
  *
  * | form                      | example                  | meaning                        |
  * |---------------------------|--------------------------|--------------------------------|
- * | named (full CSS set)      | `"steelblue"`, `"transparent"` | the ~148 CSS colour names |
+ * | named (full CSS set)      | `"steelblue"`, `"transparent"` | the ~148 CSS color names |
  * | hex 6 / 3                 | `"#1450aa"` / `"#14a"`   | CSS RGB                        |
  * | hex 8 / 4                 | `"#1450aacc"` / `"#14ac"`| CSS RGBA (alpha LAST)          |
  * | number                    | `0xff1450aa`             | Flutter ARGB (alpha FIRST)     |
@@ -19,6 +19,6 @@ export declare function rgb(r: number, g: number, b: number): Color;
 export declare function rgba(r: number, g: number, b: number, a: number): Color;
 /**
  * Normalizes any `ColorInput` to an engine `Color`. The single funnel every factory uses,
- * so a colour means the same thing no matter how it was written.
+ * so a color means the same thing no matter how it was written.
  */
 export declare function toColor(input: ColorInput): Color;

package/dist/api/color.js

@@ -1,24 +1,18 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.rgb = rgb;
-exports.rgba = rgba;
-exports.toColor = toColor;
-const color_1 = require("../common/color");
+import { Color } from "../common/color.js";
 /** Channels 0–255, fully opaque. */
-function rgb(r, g, b) {
-    return new color_1.Color(r, g, b, 1);
+export function rgb(r, g, b) {
+    return new Color(r, g, b, 1);
 }
 /** Channels 0–255, alpha 0–1. */
-function rgba(r, g, b, a) {
-    return new color_1.Color(r, g, b, a);
+export function rgba(r, g, b, a) {
+    return new Color(r, g, b, a);
 }
 /**
  * Normalizes any `ColorInput` to an engine `Color`. The single funnel every factory uses,
- * so a colour means the same thing no matter how it was written.
+ * so a color means the same thing no matter how it was written.
  */
-function toColor(input) {
-    var _a;
-    if (input instanceof color_1.Color)
+export function toColor(input) {
+    if (input instanceof Color)
         return input;
     if (typeof input === "number")
         return fromArgbNumber(input);
@@ -27,7 +21,7 @@ function toColor(input) {
         return fromHex(s);
     const named = CSS_COLORS[s];
     if (named)
-        return new color_1.Color(named[0], named[1], named[2], (_a = named[3]) !== null && _a !== void 0 ? _a : 1);
+        return new Color(named[0], named[1], named[2], named[3] ?? 1);
     throw new Error(`Unknown color: "${input}"`);
 }
 /** Flutter ARGB: 0xAARRGGBB, alpha FIRST. A 6-digit number has alpha 0x00 = transparent. */
@@ -36,7 +30,7 @@ function fromArgbNumber(n) {
     const r = (n >>> 16) & 0xff;
     const g = (n >>> 8) & 0xff;
     const b = n & 0xff;
-    return new color_1.Color(r, g, b, a / 255);
+    return new Color(r, g, b, a / 255);
 }
 /** CSS hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA. Alpha is LAST. */
 function fromHex(s) {
@@ -58,7 +52,7 @@ function fromHex(s) {
     const a = full.length === 8 ? parseInt(full.slice(6, 8), 16) / 255 : 1;
     if ([r, g, b].some(Number.isNaN))
         throw new Error(`Invalid hex color: "${s}"`);
-    return new color_1.Color(r, g, b, a);
+    return new Color(r, g, b, a);
 }
 // The full CSS named-color set (~148, incl. the synonyms grey/gray and `transparent`).
 // [r, g, b] or [r, g, b, alpha]. Lower-cased keys; `toColor` lower-cases the input.

package/dist/api/content.d.ts

@@ -1,10 +1,11 @@
-import { ImageElement, CustomImage } from "../elements/image-element";
-import { PDFElement } from "../elements/pdf-element";
-import { ColorInput } from "./color";
-import { Insets } from "./insets";
+import { ImageElement, CustomImage } from "../elements/image-element.js";
+import { PDFElement } from "../elements/pdf-element.js";
+import { ColorInput } from "./color.js";
+import { Insets } from "./insets.js";
+import { BoundsInput, SizeInput, RadiusInput } from "./dimension.js";
 /** A horizontal rule (locked §4). */
 export interface DividerOptions {
-    /** Line colour (default a light grey). */
+    /** Line color (default a light gray). */
     color?: ColorInput;
     /** Line thickness in points (default 1). */
     thickness?: number;
@@ -14,20 +15,26 @@ export interface DividerOptions {
 /**
  * A horizontal rule that spans the parent's width. Maps to a `LineElement` (hiding its
  * `xEnd`/`yEnd` mechanics) wrapped in a `PaddingElement` - the line has no height of its
- * own, so the padding gives it vertical room and centres the rule. Use inside a Column.
+ * own, so the padding gives it vertical room and centers the rule. Use inside a Column.
  */
 export declare function Divider(opts?: DividerOptions): PDFElement;
-/** An image source: a local file path, or a `CustomImage` (e.g. a browser-supplied image). */
-export type ImageSource = string | CustomImage;
+/** An image source: a local file path (Node), raw bytes (e.g. a browser fetch/upload), or a `CustomImage`. */
+export type ImageSource = string | Uint8Array | CustomImage;
 /** How the image fills its box (locked §4). Mirrors CSS `object-fit`. */
 export type ImageFit = "none" | "contain" | "cover" | "fill";
-export interface ImageOptions {
-    width?: number;
-    height?: number;
-    /** Fit within the box (default `none`). */
+export interface ImageOptions extends BoundsInput {
+    /** Size on each axis: points (fixed) or a percentage string like `"50%"` (a fraction of the offered
+     *  space). Pin exactly ONE axis and the other follows the image's aspect ratio (CSS `height: auto`). */
+    width?: SizeInput;
+    height?: SizeInput;
+    /** Fit within the box. Default `none`, except where the box was DERIVED rather than given outright -
+     *  exactly one axis pinned, or an `aspectRatio` - which defaults to `fill` so the image scales into it. */
     fit?: ImageFit;
     /** Corner radius in points (rounds the image box). */
-    radius?: number;
+    radius?: RadiusInput;
+    /** Alternate text for accessibility (tagged PDF): describes the image for screen readers. With `alt`
+     *  the image is a `Figure`; without it (and when rendered `accessible`) it counts as decoration. */
+    alt?: string;
 }
 /**
  * An image. `src` is a local file path (wrapped in a `CustomLocalImage`) or a ready

package/dist/api/content.js

@@ -1,50 +1,65 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Divider = Divider;
-exports.Image = Image;
-const line_element_1 = require("../elements/line-element");
-const padding_element_1 = require("../elements/layout/padding-element");
-const image_element_1 = require("../elements/image-element");
-const color_1 = require("./color");
-const insets_1 = require("./insets");
+import { LineElement } from "../elements/line-element.js";
+import { PaddingElement } from "../elements/layout/padding-element.js";
+import { ImageElement, CustomLocalImage, CustomBytesImage, BoxFit, } from "../elements/image-element.js";
+import { toColor } from "./color.js";
+import { toEdges } from "./insets.js";
+import { toBounds, toDimension, toRadius, } from "./dimension.js";
 const DEFAULT_DIVIDER_COLOR = "lightgray";
 const DEFAULT_DIVIDER_MARGIN = { y: 6 };
 /**
  * A horizontal rule that spans the parent's width. Maps to a `LineElement` (hiding its
  * `xEnd`/`yEnd` mechanics) wrapped in a `PaddingElement` - the line has no height of its
- * own, so the padding gives it vertical room and centres the rule. Use inside a Column.
+ * own, so the padding gives it vertical room and centers the rule. Use inside a Column.
  */
-function Divider(opts = {}) {
-    var _a, _b, _c;
-    const line = new line_element_1.LineElement({
+export function Divider(opts = {}) {
+    const line = new LineElement({
         x: 0,
         y: 0,
         xEnd: 0, // resolved to the parent's width at layout time
         yEnd: 0, // horizontal: no vertical span
-        color: (0, color_1.toColor)((_a = opts.color) !== null && _a !== void 0 ? _a : DEFAULT_DIVIDER_COLOR),
-        strokeWidth: (_b = opts.thickness) !== null && _b !== void 0 ? _b : 1,
+        color: toColor(opts.color ?? DEFAULT_DIVIDER_COLOR),
+        strokeWidth: opts.thickness ?? 1,
     });
-    return new padding_element_1.PaddingElement({
-        margin: (0, insets_1.toEdges)((_c = opts.margin) !== null && _c !== void 0 ? _c : DEFAULT_DIVIDER_MARGIN),
+    return new PaddingElement({
+        margin: toEdges(opts.margin ?? DEFAULT_DIVIDER_MARGIN),
         child: line,
     });
 }
 const FIT = {
-    none: image_element_1.BoxFit.none,
-    contain: image_element_1.BoxFit.contain,
-    cover: image_element_1.BoxFit.cover,
-    fill: image_element_1.BoxFit.fill,
+    none: BoxFit.none,
+    contain: BoxFit.contain,
+    cover: BoxFit.cover,
+    fill: BoxFit.fill,
 };
 /**
  * An image. `src` is a local file path (wrapped in a `CustomLocalImage`) or a ready
  * `CustomImage` for non-filesystem sources. Maps to an `ImageElement`.
  */
-function Image(src, opts = {}) {
-    return new image_element_1.ImageElement({
-        image: typeof src === "string" ? new image_element_1.CustomLocalImage(src) : src,
-        width: opts.width,
-        height: opts.height,
-        fit: opts.fit ? FIT[opts.fit] : undefined,
-        radius: opts.radius,
-    });
+export function Image(src, opts = {}) {
+    const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
+    const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
+    // ANY explicit size scales the image into the box (fit: fill), which is what `<img width height>`
+    // does in HTML and what react-pdf does. Two pinned axes used to keep `none` - drawing the image at
+    // its pixel size regardless - so a logo asked for at 48x48 spanned a third of the page.
+    // An image with NO size given still draws at its intrinsic size, as an unsized `<img>` does.
+    const sized = opts.width !== undefined || opts.height !== undefined || opts.aspectRatio !== undefined;
+    const fit = opts.fit ? FIT[opts.fit] : sized ? BoxFit.fill : undefined;
+    return new ImageElement({
+        image: typeof src === "string"
+            ? new CustomLocalImage(src)
+            : src instanceof Uint8Array
+                ? new CustomBytesImage(src)
+                : src,
+        width: w?.points,
+        height: h?.points,
+        widthFactor: w?.factor,
+        heightFactor: h?.factor,
+        ...toBounds(opts),
+        fit,
+        radius: opts.radius !== undefined ? toRadius(opts.radius) : undefined,
+        alt: opts.alt,
+    })
+        .withAlignSelf(opts.alignSelf)
+        .withOrder(opts.order)
+        .withFlexShrink(opts.flexShrink);
 }

package/dist/api/descriptor.d.ts

@@ -1,5 +1,5 @@
-import { PDFElement } from "../elements/pdf-element";
-import { PDFDocumentElement } from "../elements/pdf-document-element";
+import { PDFElement } from "../elements/pdf-element.js";
+import { PDFDocumentElement } from "../elements/pdf-document-element.js";
 /**
  * The framework-agnostic contract (the firewall). A binding (Vue/React, or any tree-builder)
  * produces a tree of these plain descriptors; `build` turns each node into an engine element

package/dist/api/descriptor.js

@@ -1,29 +1,26 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerElement = registerElement;
-exports.build = build;
-exports.buildDocument = buildDocument;
-const text_1 = require("./text");
-const layout_1 = require("./layout");
-const content_1 = require("./content");
-const structure_1 = require("./structure");
+import { Text, Paragraph, span } from "./text.js";
+import { Column, Row, Box, Padding, Spacer, PageBreak, keepTogether, Expanded, Positioned, Link, Anchor, Bookmark, Rotated, RotatedBox, } from "./layout.js";
+import { Divider, Image } from "./content.js";
+import { Page, Document, DefaultTextStyle } from "./structure.js";
+import { PageNumber, PageCount } from "./page-builder.js";
+import { Table } from "./table.js";
+import { Checkbox, Dropdown, ListBox, PushButton, RadioGroup, SignatureField, TextField, } from "./forms.js";
 // Element children (Column/Row/Box/Page/…) → built recursively. Text/Paragraph children are
 // strings or `span` descriptors and become content instead.
 function elementChildren(children) {
     return children.map(build);
 }
 function textOf(node) {
-    var _a;
     if (typeof node === "string")
         return node;
-    const first = (_a = node.children) === null || _a === void 0 ? void 0 : _a[0];
+    const first = node.children?.[0];
     return typeof first === "string" ? first : "";
 }
 function toSegment(c) {
     if (typeof c === "string")
-        return (0, text_1.span)(c);
+        return span(c);
     if (c.type === "span")
-        return (0, text_1.span)(textOf(c), c.props);
+        return span(textOf(c), c.props);
     throw new Error(`A Text child must be a string or a span, got "${c.type}"`);
 }
 function textContent(children) {
@@ -31,40 +28,133 @@ function textContent(children) {
         return children[0];
     return children.map(toSegment);
 }
+// A `<TableCell>`'s content → a `Cell`: a lone string stays a string (the table wraps it in Text);
+// otherwise its children are built (a single element, or a Column of several).
+function buildCell(cell) {
+    if (typeof cell === "string")
+        return cell;
+    const kids = cell.children ?? [];
+    if (kids.length === 1 && typeof kids[0] === "string")
+        return kids[0];
+    if (kids.length === 0)
+        return "";
+    const els = kids.map(build);
+    return els.length === 1 ? els[0] : Column(els);
+}
+// A `<TableRow>`'s `<TableCell>` children → one row of `Cell`s.
+function rowCells(row) {
+    return (row.children ?? [])
+        .filter((c) => typeof c !== "string" && c.type === "table-cell")
+        .map(buildCell);
+}
+// A `#header` / `#footer` slot's content → one element (a Column if it holds several; strings → Text).
+function slotElement(node) {
+    const els = (node.children ?? []).map((c) => (typeof c === "string" ? Text(c) : build(c)));
+    return els.length === 1 ? els[0] : Column(els);
+}
+// The single child a wrapper takes (`Link`, `Anchor`, `Bookmark`, `Rotated`, ...). Several children are
+// stacked in a Column, so `<JasyLink><Text/><Text/></JasyLink>` behaves like the factory would.
+function wrappedChild(children) {
+    const els = children.map((c) => (typeof c === "string" ? Text(c) : build(c)));
+    if (els.length === 0)
+        throw new Error("A wrapper element needs exactly one child");
+    return els.length === 1 ? els[0] : Column(els);
+}
 const REGISTRY = {
-    document: (props, children) => (0, structure_1.Document)(props, elementChildren(children)),
-    page: (props, children) => (0, structure_1.Page)(props, elementChildren(children)),
-    column: (props, children) => (0, layout_1.Column)(props, elementChildren(children)),
-    row: (props, children) => (0, layout_1.Row)(props, elementChildren(children)),
-    box: (props, children) => (0, layout_1.Box)(props, elementChildren(children)),
-    padding: (props, children) => { var _a; return (0, layout_1.Padding)((_a = props.insets) !== null && _a !== void 0 ? _a : 0, elementChildren(children)[0]); },
-    expanded: (props, children) => (0, layout_1.Expanded)(props, elementChildren(children)[0]),
-    spacer: (props) => (0, layout_1.Spacer)(props === null || props === void 0 ? void 0 : props.flex),
-    divider: (props) => (0, content_1.Divider)(props),
-    image: (props) => (0, content_1.Image)(props.src, props),
-    text: (props, children) => (0, text_1.Text)(textContent(children), props),
-    paragraph: (props, children) => (0, text_1.Paragraph)(textContent(children), props),
+    document: (props, children) => {
+        const doc = Document(props, elementChildren(children));
+        // A binding can register fonts declaratively: `fonts: { Name: bytes | path | family }`.
+        if (props.fonts) {
+            for (const [name, src] of Object.entries(props.fonts))
+                doc.addFont(name, src);
+        }
+        return doc;
+    },
+    page: (props, children) => {
+        // `#header` / `#footer` arrive as `page-header` / `page-footer` marker children (read raw); the rest
+        // is the body. Both repeat on every physical page the body paginates onto.
+        const slot = (type) => {
+            const m = children.find((c) => typeof c !== "string" && c.type === type);
+            return m ? slotElement(m) : undefined;
+        };
+        const body = children.filter((c) => typeof c === "string" || (c.type !== "page-header" && c.type !== "page-footer"));
+        return Page({ ...props, header: slot("page-header"), footer: slot("page-footer") }, elementChildren(body));
+    },
+    column: (props, children) => Column(props, elementChildren(children)),
+    row: (props, children) => Row(props, elementChildren(children)),
+    box: (props, children) => Box(props, elementChildren(children)),
+    padding: (props, children) => Padding(props.insets ?? 0, elementChildren(children)[0]),
+    expanded: (props, children) => Expanded(props, elementChildren(children)[0]),
+    spacer: (props) => Spacer(props?.flex),
+    "page-break": () => PageBreak(),
+    "keep-together": (_props, children) => keepTogether(elementChildren(children)),
+    divider: (props) => Divider(props),
+    image: (props) => Image(props.src, props),
+    text: (props, children) => Text(textContent(children), props),
+    paragraph: (props, children) => Paragraph(textContent(children), props),
+    // `<Table>` reads its `<TableRow>`/`<TableCell>` structure raw; one row may be marked `header`.
+    table: (props, children) => {
+        const rows = children.filter((c) => typeof c !== "string" && c.type === "table-row");
+        const header = rows.find((r) => r.props?.header);
+        const body = rows.filter((r) => !r.props?.header);
+        return Table({ ...props, header: header ? rowCells(header) : undefined }, body.map(rowCells));
+    },
+    positioned: (props, children) => Positioned(props, elementChildren(children)[0]),
+    "default-text-style": (props, children) => DefaultTextStyle(props, elementChildren(children)),
+    // Navigation. `Link` takes exactly one of `href` (a URL) or `to` (an `Anchor` name) - the factory
+    // enforces that, so a template typo surfaces as an error instead of a dead link.
+    link: (props, children) => Link(props, wrappedChild(children)),
+    anchor: (props, children) => Anchor(props, wrappedChild(children)),
+    bookmark: (props, children) => Bookmark(props, wrappedChild(children)),
+    // Transforms.
+    rotated: (props, children) => Rotated(props, wrappedChild(children)),
+    "rotated-box": (props, children) => RotatedBox(props, wrappedChild(children)),
+    // Page numbers. `PageBuilder` itself is deliberately NOT exposed: it takes a closure, which a template
+    // cannot express. These two cover what the closure exists for.
+    "page-number": (props) => PageNumber(props),
+    "page-count": (props) => PageCount(props),
+    // Form fields. The three list-like ones take their choices as a SECOND argument in TypeScript; a
+    // template has no second argument, so here they arrive as an `options` prop. `choiceList` accepts both
+    // the short spelling and the explicit one, because an export value and its label are usually the same
+    // string and having to write it twice is noise.
+    "text-field": (props) => TextField(props),
+    checkbox: (props) => Checkbox(props),
+    "radio-group": (props) => RadioGroup(props, radioChoices(props.options)),
+    dropdown: (props) => Dropdown(props, choiceList(props.options)),
+    "list-box": (props) => ListBox(props, choiceList(props.options)),
+    "push-button": (props) => PushButton(props),
+    "signature-field": (props) => SignatureField(props),
 };
+/** `["S", "M"]` or `[{ value: "DE", label: "Germany" }]` - both mean the same thing to a choice field. */
+function choiceList(raw) {
+    if (!Array.isArray(raw)) {
+        throw new Error("jasy: a choice field needs an `options` array (strings or {value, label}).");
+    }
+    return raw;
+}
+/** A radio button always shows a label, so the short spelling means "label is the value". */
+function radioChoices(raw) {
+    return choiceList(raw).map((o) => typeof o === "string" ? { value: o, label: o } : { value: o.value, label: o.label ?? o.value });
+}
 /**
  * Registers a custom element type, so a binding (or a user-defined component) can introduce
  * its own tag that resolves to an engine element through this same seam. Overwrites an
  * existing type of the same name.
  */
-function registerElement(type, factory) {
+export function registerElement(type, factory) {
     REGISTRY[type] = factory;
 }
 /** Turns one descriptor node (or bare string → `Text`) into an engine element. */
-function build(node) {
-    var _a, _b;
+export function build(node) {
     if (typeof node === "string")
-        return (0, text_1.Text)(node);
+        return Text(node);
     const factory = REGISTRY[node.type];
     if (!factory)
         throw new Error(`Unknown element type: "${node.type}"`);
-    return factory((_a = node.props) !== null && _a !== void 0 ? _a : {}, (_b = node.children) !== null && _b !== void 0 ? _b : []);
+    return factory(node.props ?? {}, node.children ?? []);
 }
 /** Builds a descriptor tree whose root is a `document` into the renderable root element. */
-function buildDocument(root) {
+export function buildDocument(root) {
     if (root.type !== "document")
         throw new Error(`Expected a "document" root, got "${root.type}"`);
     return build(root);