@jasy/pdf 1.0.0-alpha.9 → 1.0.0-beta.1

package/README.md

@@ -116,9 +116,11 @@ 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, **AES-256 password encryption**, and **real
-pagination** - content that overflows flows onto the next page, headers and footers repeat.
+Real text layout (real font metrics, kerning, ligatures, word-wrap), full flexbox (`gap` / `justify` /
+`align`, wrap, `flexBasis`, `flexShrink`, `order`), boxes with per-corner radius, gradients and alpha, images and
+**SVG**, a `Canvas` to draw into, custom fonts from a file, bytes or a URL, AcroForm fields,
+**AES-256 password encryption**, tagged PDFs for screen readers, and **real pagination** - content that
+overflows flows onto the next page, headers and footers repeat, and a block can refuse to be split.
 
 ---
 
@@ -140,9 +142,19 @@ verify all of it:
 - **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. Over 900 tests hold the line across the workspace.
+  the identical XML. Over 1,600 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.
+- **Vectors, not bitmaps.** `Image("logo.svg")` keeps a logo a VECTOR - our own SVG reader and our own
+  XML parser, checked against 10,819 real files and compared pixel for pixel with headless Chrome. Need
+  a chart instead? `Canvas` hands you a typed pen for the same vector layer.
+- **Fonts, whatever the container.** `.ttf`, `.woff` and `.woff2` are the same thing at the call site.
+  The WOFF2 container and its `glyf` transform are ours; only Brotli is a dependency, and it is loaded
+  only if a WOFF2 actually turns up.
+- **Byte-stable output.** The same document rendered twice is byte-identical, PDF/A and ZUGFeRD
+  included, across separate processes. An archived invoice stays re-derivable and hashable years later.
+- **Accessible if you ask.** `renderToBytes(doc, { accessible })` emits a full tagged structure tree,
+  and the output passes veraPDF's machine-verifiable PDF/UA-1 checks.
 
 ---
 
@@ -153,12 +165,14 @@ verify all of it:
 | **[@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                              |
+| **[@jasy/vue](https://npmx.dev/@jasy/vue)**             | author PDFs as Vue components - and render them in the browser                                 |
+| **[@jasy/nuxt](https://npmx.dev/@jasy/nuxt)**           | the Nuxt module: zero-config PDFs, client **or** server                                        |
 
 ---
 
 ## Why you can trust it
 
-- **Over 900 tests, green** across the workspace (850 in the engine alone). The generator and the parser
+- **Over 1,600 tests, green** across the workspace (1,190 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
@@ -170,10 +184,14 @@ verify all of it:
 
 ## Honest scope
 
-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
-even paginate. We would rather under-promise and over-deliver in the demo above.
+jasy targets the documents that matter here: invoices, reports, quotes, datasheets - and it now sets
+text properly: kerning and Latin ligatures from the font's own tables, justification, pluggable
+hyphenation, right-to-left and Arabic shaping, underlines that step around descenders. Pagination is
+real: text splits at line boxes, `keepTogether` moves a card whole, orphans and widows are honoured.
+
+It is still **not** a LaTeX or WeasyPrint replacement, and does not try to be: no automatic
+microtypography, no floats, no CSS engine. What it will not draw, it **names** - an SVG filter, a font
+without the glyph, a word that cannot be split - rather than quietly drawing something else.
 
 > **Status:** young and pre-1.0. The API can still shift between minor versions. Everything shown here
 > works and is tested.

package/dist/api/color.js

@@ -22,8 +22,77 @@ export function toColor(input) {
     const named = CSS_COLORS[s];
     if (named)
         return new Color(named[0], named[1], named[2], named[3] ?? 1);
+    const call = /^([a-z-]+)\(([^)]*)\)$/.exec(s);
+    if (call)
+        return fromFunction(call[1], call[2], input);
     throw new Error(`Unknown color: "${input}"`);
 }
+/**
+ * The CSS colour FUNCTIONS. `rgb()`/`rgba()` and `hsl()`/`hsla()` are the sRGB family, so they convert
+ * exactly and are supported; a wide-gamut function (`color()`, `lab()`, `oklch()`) is named and
+ * refused rather than silently squashed into sRGB, since the result would be a colour nobody chose.
+ *
+ * Both syntaxes are accepted, because both occur in the wild: the legacy comma form
+ * `rgb(20, 90, 170)` and the modern space form with an optional slash-alpha `rgb(20 90 170 / 50%)`.
+ */
+function fromFunction(name, body, original) {
+    if (name !== "rgb" && name !== "rgba" && name !== "hsl" && name !== "hsla") {
+        throw new Error(`Unsupported color function "${name}()" in "${String(original)}". ` +
+            `Use a hex value, a CSS colour name, rgb()/rgba() or hsl()/hsla().`);
+    }
+    const [main, alphaPart] = body.split("/");
+    const parts = main
+        .trim()
+        .split(/[\s,]+/)
+        .filter(Boolean);
+    const alphaText = alphaPart !== undefined ? alphaPart.trim() : parts[3];
+    if (parts.length < 3)
+        throw new Error(`Unknown color: "${String(original)}"`);
+    const alpha = alphaText === undefined ? 1 : ratio(alphaText, original);
+    const [a, b, c] = parts;
+    if (name === "rgb" || name === "rgba") {
+        return new Color(channel(a, original), channel(b, original), channel(c, original), alpha);
+    }
+    const [r, g, bl] = hslToRgb(number(a, original), ratio(b, original), ratio(c, original));
+    return new Color(r, g, bl, alpha);
+}
+const NUMERIC = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+/**
+ * One component of a colour function. `Number.parseFloat` stops at the first character it cannot use
+ * and returns what it had, so `rgb(20abc, 90, 170)` would silently become `rgb(20, 90, 170)` - a
+ * colour nobody wrote. The whole token has to be a number.
+ */
+function number(text, original) {
+    const t = text.trim();
+    if (!NUMERIC.test(t))
+        throw new Error(`Unknown color: "${String(original)}"`);
+    return Number(t);
+}
+/** An rgb channel: 0-255, or a percentage of 255. */
+const channel = (text, original) => text.trim().endsWith("%")
+    ? (number(text.trim().slice(0, -1), original) / 100) * 255
+    : number(text, original);
+/** A 0..1 ratio written either as a number or as a percentage (alpha, saturation, lightness). */
+const ratio = (text, original) => text.trim().endsWith("%")
+    ? number(text.trim().slice(0, -1), original) / 100
+    : number(text, original);
+/** CSS hue-saturation-lightness to 0-255 channels. */
+function hslToRgb(hue, s, l) {
+    const h = ((hue % 360) + 360) % 360;
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = l - c / 2;
+    const sector = Math.floor(h / 60) % 6;
+    const rgbPrime = [
+        [c, x, 0],
+        [x, c, 0],
+        [0, c, x],
+        [0, x, c],
+        [x, 0, c],
+        [c, 0, x],
+    ][sector];
+    return rgbPrime.map((v) => Math.round((v + m) * 255));
+}
 /** Flutter ARGB: 0xAARRGGBB, alpha FIRST. A 6-digit number has alpha 0x00 = transparent. */
 function fromArgbNumber(n) {
     const a = (n >>> 24) & 0xff;

package/dist/api/content.d.ts

@@ -3,6 +3,8 @@ import { PDFElement } from "../elements/pdf-element.js";
 import { ColorInput } from "./color.js";
 import { Insets } from "./insets.js";
 import { BoundsInput, SizeInput, RadiusInput } from "./dimension.js";
+import { SvgElement, type SvgSource } from "../elements/svg-element.js";
+import { CanvasElement, type CanvasPaint } from "../elements/canvas-element.js";
 /** A horizontal rule (locked §4). */
 export interface DividerOptions {
     /** Line color (default a light gray). */
@@ -18,6 +20,13 @@ export interface DividerOptions {
  * own, so the padding gives it vertical room and centers the rule. Use inside a Column.
  */
 export declare function Divider(opts?: DividerOptions): PDFElement;
+/** Options for `Svg`. The same sizing and bounds as an image; `fit` and `radius` do not apply yet. */
+export interface SvgOptions extends BoundsInput {
+    width?: SizeInput;
+    height?: SizeInput;
+    /** Alternate text (tagged PDF). With it the drawing is a `Figure`; without it, decoration. */
+    alt?: string;
+}
 /** 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`. */
@@ -36,8 +45,38 @@ export interface ImageOptions extends BoundsInput {
      *  the image is a `Figure`; without it (and when rendered `accessible`) it counts as decoration. */
     alt?: string;
 }
+/** Options for `Canvas`. Sizing only - what is drawn is entirely the callback's business. */
+export interface CanvasOptions extends BoundsInput {
+    width?: SizeInput;
+    height?: SizeInput;
+    /** Alternate text (tagged PDF). With it the drawing is a `Figure`; without it, decoration. */
+    alt?: string;
+}
+/**
+ * A box you draw into yourself - the escape hatch for what the declarative layer has no component
+ * for: a sparkline, a seal, a chart, a signature flourish.
+ *
+ * With no size it FILLS the box it is offered, because there is nothing to derive an intrinsic size
+ * from. The callback is handed that resolved size, so a drawing written against `size.width` works
+ * at any width. It is clipped to its own box: a canvas is a block IN the layout, never a way around
+ * it - text still belongs in `Text`, and this still paginates as one unbreakable block.
+ */
+export declare function Canvas(opts: CanvasOptions, paint: CanvasPaint): CanvasElement;
+export declare function Canvas(paint: CanvasPaint): CanvasElement;
+/**
+ * A vector drawing from SVG. `source` is markup, a file path (Node) or the file's bytes. It is read
+ * and parsed HERE, not at render time, so a broken file fails on the line that named it.
+ *
+ * With no size it draws at its intrinsic size; pin one axis and the other follows the `viewBox`. The
+ * drawing is scaled uniformly and centred inside its box - SVG's own `preserveAspectRatio` default,
+ * which is `fit: "contain"` by another name.
+ */
+export declare function Svg(source: SvgSource, opts?: SvgOptions): SvgElement;
 /**
  * An image. `src` is a local file path (wrapped in a `CustomLocalImage`) or a ready
  * `CustomImage` for non-filesystem sources. Maps to an `ImageElement`.
+ *
+ * An SVG source is routed to `Svg` instead, so `Image({ src: "logo.svg" })` just works and a logo
+ * stays a VECTOR in the PDF rather than becoming a bitmap.
  */
-export declare function Image(src: ImageSource, opts?: ImageOptions): ImageElement;
+export declare function Image(src: ImageSource, opts?: ImageOptions): ImageElement | SvgElement;

package/dist/api/content.js

@@ -4,6 +4,8 @@ import { ImageElement, CustomLocalImage, CustomBytesImage, BoxFit, } from "../el
 import { toColor } from "./color.js";
 import { toEdges } from "./insets.js";
 import { toBounds, toDimension, toRadius, } from "./dimension.js";
+import { SvgElement } from "../elements/svg-element.js";
+import { CanvasElement } from "../elements/canvas-element.js";
 const DEFAULT_DIVIDER_COLOR = "lightgray";
 const DEFAULT_DIVIDER_MARGIN = { y: 6 };
 /**
@@ -31,11 +33,92 @@ const FIT = {
     cover: BoxFit.cover,
     fill: BoxFit.fill,
 };
+export function Canvas(a, b) {
+    const opts = typeof a === "function" ? {} : a;
+    const paint = typeof a === "function" ? a : b;
+    // Without it the renderer would call `undefined` and hand back a bare "paint is not a function",
+    // which says nothing about WHICH element or what to pass. A framework binding cannot cover this:
+    // Vue's `required: true` only warns, it still renders.
+    if (typeof paint !== "function") {
+        throw new Error("@jasy/pdf: Canvas needs a paint callback - Canvas({ width, height }, (c, size) => …).");
+    }
+    const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
+    const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
+    return new CanvasElement({
+        paint,
+        width: w?.points,
+        height: h?.points,
+        widthFactor: w?.factor,
+        heightFactor: h?.factor,
+        ...toBounds(opts),
+        alt: opts.alt,
+    })
+        .withAlignSelf(opts.alignSelf)
+        .withOrder(opts.order)
+        .withFlexShrink(opts.flexShrink);
+}
+/**
+ * A vector drawing from SVG. `source` is markup, a file path (Node) or the file's bytes. It is read
+ * and parsed HERE, not at render time, so a broken file fails on the line that named it.
+ *
+ * With no size it draws at its intrinsic size; pin one axis and the other follows the `viewBox`. The
+ * drawing is scaled uniformly and centred inside its box - SVG's own `preserveAspectRatio` default,
+ * which is `fit: "contain"` by another name.
+ */
+export function Svg(source, opts = {}) {
+    const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
+    const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
+    return new SvgElement({
+        source,
+        width: w?.points,
+        height: h?.points,
+        widthFactor: w?.factor,
+        heightFactor: h?.factor,
+        ...toBounds(opts),
+        alt: opts.alt,
+    })
+        .withAlignSelf(opts.alignSelf)
+        .withOrder(opts.order)
+        .withFlexShrink(opts.flexShrink);
+}
+/** SVG is recognised by its extension or by its own opening bytes - never by a caller having to say. */
+function isSvg(src) {
+    if (typeof src === "string") {
+        // `.svgz` is a GZIPPED svg. It is caught here rather than left to the image path, because the
+        // error a user needs says what the file is - not "unsupported image bytes".
+        if (/\.svgz$/i.test(src.trim())) {
+            throw new Error("@jasy/pdf: SVGZ (a gzip-compressed SVG) is not supported. Decompress it first " +
+                "(`gunzip logo.svgz`) and pass the plain .svg.");
+        }
+        return /\.svg$/i.test(src.trim()) || /^\s*[<\ufeff]/.test(src);
+    }
+    if (src instanceof Uint8Array) {
+        const head = new TextDecoder().decode(src.subarray(0, 200)).trimStart();
+        return head.startsWith("<?xml") || head.startsWith("<svg");
+    }
+    return false;
+}
 /**
  * An image. `src` is a local file path (wrapped in a `CustomLocalImage`) or a ready
  * `CustomImage` for non-filesystem sources. Maps to an `ImageElement`.
+ *
+ * An SVG source is routed to `Svg` instead, so `Image({ src: "logo.svg" })` just works and a logo
+ * stays a VECTOR in the PDF rather than becoming a bitmap.
  */
 export function Image(src, opts = {}) {
+    if (isSvg(src)) {
+        if (opts.fit !== undefined && opts.fit !== "contain") {
+            throw new Error(`@jasy/pdf: fit: "${opts.fit}" is not supported for an SVG yet - it is always drawn ` +
+                `contained, which is SVG's own default. Remove the fit, or rasterise the file.`);
+        }
+        if (opts.radius !== undefined) {
+            throw new Error("@jasy/pdf: radius is not supported for an SVG yet - wrap it in a Box instead.");
+        }
+        return Svg(src, opts);
+    }
+    return rasterImage(src, opts);
+}
+function rasterImage(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>`

package/dist/api/descriptor.js

@@ -1,6 +1,6 @@
 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 { Canvas, Divider, Image, Svg } from "./content.js";
 import { Page, Document, DefaultTextStyle } from "./structure.js";
 import { PageNumber, PageCount } from "./page-builder.js";
 import { Table } from "./table.js";
@@ -90,6 +90,11 @@ const REGISTRY = {
     "keep-together": (_props, children) => keepTogether(elementChildren(children)),
     divider: (props) => Divider(props),
     image: (props) => Image(props.src, props),
+    // `src` is markup, a path or bytes - the same three the factory takes.
+    svg: (props) => Svg(props.src, props),
+    // `paint` is a function PROP - `<Canvas :paint="drawChart" />` in a template passes one like any
+    // other value. (Unlike `PageBuilder`, whose closure is the CHILD and has no template form.)
+    canvas: (props) => Canvas(props, props.paint),
     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`.

package/dist/api/dimension.d.ts

@@ -36,8 +36,9 @@ export interface BoundsInput {
     order?: number;
     /**
      * How willingly this child gives up main-axis space when the line overflows (CSS `flex-shrink`),
-     * weighted by its own size. **Default 0, deliberately unlike CSS's 1** - shrinking changes what a
-     * document looks like, so it is opted into per child rather than applied to everything at once.
+     * weighted by its own size. Default 1, as in CSS: an overflowing line pulls its children back inside
+     * instead of letting them run past the edge. Set `0` to keep a child at its natural size and let it
+     * overflow. A child is never squeezed below what it can hold - a text stops at its longest word.
      */
     flexShrink?: number;
     minWidth?: SizeInput;

package/dist/api/font-url.js

@@ -29,7 +29,7 @@ function describeSignature(bytes) {
     if (tag === "wOFF")
         return { ok: true, what: "WOFF" };
     if (tag === "wOF2")
-        return { ok: false, what: "a WOFF2 font, which jasy does not parse yet" };
+        return { ok: true, what: "WOFF2" };
     if (tag === "ttcf")
         return { ok: false, what: "a TrueType Collection, which jasy does not parse yet" };
     if (tag.startsWith("<") || tag === "%PDF")
@@ -117,7 +117,8 @@ async function fetchFont(url) {
     }
     const { ok, what } = describeSignature(bytes);
     if (!ok) {
-        throw new FontUrlError(`the file at ${url} is ${what}. jasy embeds TrueType-flavoured fonts (.ttf and .woff)`);
+        throw new FontUrlError(`the file at ${url} is ${what}. jasy embeds TrueType-flavoured fonts ` +
+            `(.ttf, .woff and .woff2)`);
     }
     return bytes;
 }

package/dist/api/structure.d.ts

@@ -151,6 +151,13 @@ export interface RenderOptions {
     /** What to do when content is taller than a page and cannot break: `"error"` throws (default),
      *  `"warn"` logs and clips, `"ignore"` clips silently. It is always clipped either way. */
     onOverflow?: OverflowPolicy;
+    /**
+     * Called once, after the render, with the characters no font could draw - they were removed rather
+     * than emitted as `.notdef`, which PDF/A forbids. Deliberately a callback and not a policy: a
+     * missing tick mark must never stop an invoice from being produced, but the application should be
+     * able to SAY which character went missing, where a server log would never be read.
+     */
+    onMissingGlyphs?: (characters: string[]) => void;
     /** Encrypt the PDF with a password (AES-256, the newest standard). NOT compatible with PDF/A
      *  (ZUGFeRD invoices) - encrypting one throws, since PDF/A forbids encryption. */
     encrypt?: EncryptOptions;

package/dist/api/structure.js

@@ -14,6 +14,7 @@ import { Column } from "./layout.js";
 import { loadFontFromUrl } from "./font-url.js";
 import { toEdges } from "./insets.js";
 import { toTextStyleOverride } from "./text.js";
+import { isWoff2, woff2ToSfnt } from "../utils/woff2.js";
 const MM_TO_PT = 72 / 25.4; // 1 mm in PDF points
 /** Millimetres → a custom page size, e.g. a 50×65 mm label: `Page({ size: mm(50, 65) }, …)`. */
 export function mm(width, height) {
@@ -67,6 +68,29 @@ const docMeta = new WeakMap();
 const docFonts = new WeakMap();
 // The document's color-emoji fallback source, kept beside the element and applied at render time.
 const docEmoji = new WeakMap();
+/**
+ * Unwraps a WOFF2 into plain sfnt bytes. WOFF1 is left alone - `registerCustomFont` handles it
+ * synchronously, having no dependency to load - so only the async case needs to happen up here.
+ */
+async function unwrapFontContainers(fonts) {
+    const convert = async (bytes) => isWoff2(bytes) ? await woff2ToSfnt(bytes) : bytes;
+    const out = {};
+    for (const [name, value] of Object.entries(fonts)) {
+        if (isFontBytes(value)) {
+            out[name] = await convert(value);
+            continue;
+        }
+        const family = { normal: await convert(value.normal) };
+        if (value.bold)
+            family.bold = await convert(value.bold);
+        if (value.italic)
+            family.italic = await convert(value.italic);
+        if (value.boldItalic)
+            family.boldItalic = await convert(value.boldItalic);
+        out[name] = family;
+    }
+    return out;
+}
 /** Reads any path sources to bytes, leaving bytes / families as-is. */
 function resolveFontSource(source) {
     const read = (s) => (typeof s === "string" ? readFileBytes(s) : s);
@@ -130,10 +154,13 @@ export async function renderPdf(doc, options) {
     };
     // Fonts registered via doc.addFont(...) plus any passed in options (options win on a name clash).
     const registered = docFonts.get(doc);
-    const fonts = {
+    // Containers are unwrapped HERE, before the (synchronous) document constructor registers anything.
+    // WOFF2 needs Brotli, which is imported lazily and is therefore async - and this is the last async
+    // point every font passes through, whether it came from `addFont`, a URL, or these options.
+    const fonts = await unwrapFontContainers({
         ...Object.fromEntries(registered ?? []),
         ...options?.fonts,
-    };
+    });
     const attachments = options?.attachments ?? [];
     // The security handler's key derivation is async (WebCrypto), so build it here, before the sync
     // PDFDocument constructor wires it into the object manager.
@@ -143,10 +170,14 @@ export async function renderPdf(doc, options) {
     // A throwaway PDFDocument whose build() yields this tree, reusing the engine's standard
     // font registration + config handling (the constructor does both). Custom fonts are
     // registered here, before layout/render, so both the metrics and the backend see them.
+    // Captured so the caller can be told what had to be dropped: `render()` is static and builds its own
+    // instance, so this is the only place the object manager surfaces.
+    let manager;
     const Anon = class extends PDFDocument {
         constructor() {
             super(config);
             const om = this.objectManager;
+            manager = om;
             om.setCompress(options?.compress !== false); // FlateDecode streams by default
             om.setOverflowPolicy(options?.onOverflow ?? "error");
             om.setKerning(options?.kerning !== false); // on by default (experimental); `kerning:false` opts out
@@ -207,7 +238,11 @@ export async function renderPdf(doc, options) {
             return doc;
         }
     };
-    return Anon.render();
+    const pdf = await Anon.render();
+    const missing = manager?.getMissingGlyphs() ?? [];
+    if (missing.length > 0)
+        options?.onMissingGlyphs?.(missing.map((cp) => String.fromCodePoint(cp)));
+    return pdf;
 }
 /** Renders a `Document(...)` tree to PDF bytes (e.g. for a download / save dialog). */
 export async function renderToBytes(doc, options) {

package/dist/api/text.d.ts

@@ -3,7 +3,8 @@ import { TextOverflow } from "../text/line-breaker.js";
 import type { Direction } from "../text/bidi.js";
 import { ResolvedTextStyle, type TextTransform } from "../text/text-style.js";
 import { ColorInput } from "./color.js";
-export type { TextOverflow };
+import type { Hyphenator } from "../text/word-splitting.js";
+export type { TextOverflow, Direction, TextTransform, Hyphenator };
 /** Text styling shared by `Text`, `Paragraph` and `span`. `bold`/`italic` are booleans
  *  (locked §7.3) and combine into one engine `FontStyle`. */
 export interface TextStyle {
@@ -35,6 +36,16 @@ export interface TextStyle {
     wordSpacing?: number;
     /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
     textIndent?: number;
+    /** Split a word that is wider than its box, anywhere, no hyphen (CSS `overflow-wrap:
+     *  break-word`). The floor under `hyphenate`: an e-mail, an IBAN or an invoice number has no
+     *  valid hyphenation point anywhere. Off by default - a too-wide word overflows, as in CSS. */
+    breakWord?: boolean;
+    /** The ligatures the font's designer drew (`fi`, `fl`, `ffi`). ON by default, like kerning -
+     *  `false` opts this text out. Embedded fonts only; the standard-14 have no GSUB. */
+    ligatures?: boolean;
+    /** Language-aware splitting: given a word, return its parts. A hyphen is drawn at the break.
+     *  Pluggable, so no pattern data ships here: pass `hyphen`, `hyphenopoly`, or your own. */
+    hyphenate?: Hyphenator;
     /** CSS `vertical-align` for a SPAN: raises a footnote marker or lowers an index. It shifts the
      *  baseline only - pass a smaller `size` too if you want the browser's `<sup>` look. */
     verticalAlign?: VerticalTextAlign;
@@ -45,7 +56,7 @@ export interface TextStyle {
      *  same-document /GoTo instead of a URL). Use for a clickable table of contents / cross-reference. */
     to?: string;
 }
-export interface TextOptions extends TextStyle {
+export interface TextOptions extends Omit<TextStyle, "verticalAlign"> {
     /** Text-internal alignment (left/center/right) - independent of a parent's `cross` (§5). */
     align?: "left" | "center" | "right" | "justify";
     /** Cap the number of wrapped lines (default: unlimited - the text grows down as far as it needs,
@@ -108,6 +119,16 @@ export interface TextDefaults {
     wordSpacing?: number;
     /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
     textIndent?: number;
+    /** Split a word that is wider than its box, anywhere, no hyphen (CSS `overflow-wrap:
+     *  break-word`). The floor under `hyphenate`: an e-mail, an IBAN or an invoice number has no
+     *  valid hyphenation point anywhere. Off by default - a too-wide word overflows, as in CSS. */
+    breakWord?: boolean;
+    /** The ligatures the font's designer drew (`fi`, `fl`, `ffi`). ON by default, like kerning -
+     *  `false` opts this text out. Embedded fonts only; the standard-14 have no GSUB. */
+    ligatures?: boolean;
+    /** Language-aware splitting: given a word, return its parts. A hyphen is drawn at the break.
+     *  Pluggable, so no pattern data ships here: pass `hyphen`, `hyphenopoly`, or your own. */
+    hyphenate?: Hyphenator;
 }
 /** Maps the `Text`-style option names onto a partial engine `ResolvedTextStyle` (only the set
  *  fields), for seeding the inheritance cascade. */

package/dist/api/text.js

@@ -100,6 +100,9 @@ export function Text(content, opts = {}) {
         textTransform: opts.textTransform,
         wordSpacing: opts.wordSpacing,
         textIndent: opts.textIndent,
+        breakWord: opts.breakWord,
+        ligatures: opts.ligatures,
+        hyphenate: opts.hyphenate,
         role: opts.role,
     });
 }
@@ -142,5 +145,11 @@ export function toTextStyleOverride(opts) {
         style.wordSpacing = opts.wordSpacing;
     if (opts.textIndent !== undefined)
         style.textIndent = opts.textIndent;
+    if (opts.breakWord !== undefined)
+        style.breakWord = opts.breakWord;
+    if (opts.ligatures !== undefined)
+        style.ligatures = opts.ligatures;
+    if (opts.hyphenate !== undefined)
+        style.hyphenate = opts.hyphenate;
     return style;
 }

package/dist/canvas/painter.d.ts

@@ -0,0 +1,102 @@
+import { type ColorInput } from "../api/color.js";
+import { type GradientInput } from "../api/gradient.js";
+import type { IRNode, StrokeStyle } from "../ir/display-list.js";
+/**
+ * The imperative escape hatch: a box in the layout that you draw into yourself.
+ *
+ * It is the SECOND producer of the vector layer (SVG is the first), so it needs no new IR and no
+ * backend change - everything it draws is a `Path` node like any other, which means it tags, it
+ * paginates, and it works in the browser.
+ *
+ * Three deliberate departures from the PDFKit-shaped painters (react-pdf's included):
+ *
+ * 1. **Typed to the value.** `cap: "round"` autocompletes and a wrong one is a compile error, where
+ *    react-pdf's `paint` callback receives `painter: any` - no help on the one thing you use.
+ * 2. **No hidden state.** There is no `lineWidth(2)` that a later `stroke()` happens to pick up, and
+ *    no `save()`/`restore()` pair to forget: a transform or a clip is a SCOPE (`group`, `clipped`)
+ *    that closes itself.
+ * 3. **One coordinate system.** Top-left, y down, points - the same as every other element in jasy
+ *    and the same as SVG. The origin is the canvas box, so `0,0` is its own corner.
+ */
+/** Where a shape ends up. A gradient resolves against the shape's own bounding box, as in SVG. */
+export type PaintInput = ColorInput | GradientInput;
+export interface StrokeOptions {
+    /** Line width in points. Default 1. */
+    width?: number;
+    cap?: StrokeStyle["cap"];
+    join?: StrokeStyle["join"];
+    miterLimit?: number;
+    /** Dash lengths in points, plus the phase to start at. */
+    dash?: number[];
+    dashOffset?: number;
+}
+export interface FillOptions {
+    /** `evenodd` cuts a hole where subpaths overlap an odd number of times. Default `nonzero`. */
+    rule?: "nonzero" | "evenodd";
+}
+/** A transform applied for the duration of a `group`. Composed in this order: translate, rotate, scale. */
+export interface TransformOptions {
+    translate?: [number, number];
+    /** Degrees, clockwise on the page. */
+    rotate?: number;
+    /** One number scales both axes. */
+    scale?: number | [number, number];
+    /** The point `rotate` and `scale` happen around. Default `[0, 0]`. */
+    origin?: [number, number];
+}
+/** The size the callback was given, so a drawing can be written relative to its box. */
+export interface CanvasSize {
+    width: number;
+    height: number;
+}
+export declare class CanvasPainter {
+    readonly size: CanvasSize;
+    /** The nodes drawn so far, in order. */
+    private readonly nodes;
+    /** The path being built. Emptied by every painting call, so a shape cannot leak into the next. */
+    private current;
+    private cursor;
+    private start;
+    constructor(size: CanvasSize);
+    /** Everything drawn, for the renderer. */
+    drawn(): IRNode[];
+    move(x: number, y: number): this;
+    line(x: number, y: number): this;
+    /** A cubic Bézier - the curve PDF draws natively. */
+    curve(x1: number, y1: number, x2: number, y2: number, x: number, y: number): this;
+    /** A quadratic Bézier. PDF has no operator for one, so it is raised to a cubic exactly. */
+    quad(cx: number, cy: number, x: number, y: number): this;
+    close(): this;
+    rect(x: number, y: number, width: number, height: number): this;
+    circle(cx: number, cy: number, r: number): this;
+    /** Four cubics; the constant is the standard circle-to-Bézier one. */
+    ellipse(cx: number, cy: number, rx: number, ry: number): this;
+    polygon(points: readonly (readonly [number, number])[]): this;
+    /** SVG path data, through the same reader `Svg()` uses - arcs and shorthands included. */
+    path(d: string): this;
+    /** Fills the path built so far and starts a new one. Default black, as in SVG and PDF. */
+    fill(paint?: PaintInput, options?: FillOptions): this;
+    /** Strokes the path built so far and starts a new one. */
+    stroke(color?: ColorInput, options?: StrokeOptions): this;
+    fillAndStroke(paint: PaintInput, color: ColorInput, options?: StrokeOptions & FillOptions): this;
+    /**
+     * Draws inside a transform. It closes itself, so there is no `restore()` to forget - and a nested
+     * `group` composes, exactly like a `<g transform>` in SVG.
+     */
+    group(transform: TransformOptions, draw: (c: CanvasPainter) => void): this;
+    /**
+     * Draws clipped to a path. `build` draws the clip shape (nothing is painted from it), `draw` draws
+     * what the clip applies to.
+     */
+    clipped(build: (c: CanvasPainter) => void, draw: (c: CanvasPainter) => void, options?: FillOptions): this;
+    private paint;
+    /**
+     * A path may not cross the edge of a scope. It would be built in one coordinate space and painted
+     * in another, and the version that just dropped it made a shape vanish without a word - exactly
+     * the silence this codebase refuses everywhere else.
+     */
+    private assertNoPendingPath;
+    private resolve;
+    private strokeStyle;
+    private matrixOf;
+}