@jasy/pdf 1.0.0-alpha.8 → 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. 307 tests hold the line.
+  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,13 +165,16 @@ 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
 
-- **307 tests, green.** The generator and the parser are **byte-exact inverses**:
-  `generate → parse → regenerate` reproduces the identical XML. Nothing is silently lost.
+- **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
   official **veraPDF** for the full ISO 19005 (PDF/A) check.
 - **Proven on real third-party invoices**, not only our own.
@@ -169,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

@@ -2,7 +2,9 @@ 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 { SizeInput } from "./dimension.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,25 +20,63 @@ 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`. */
 export type ImageFit = "none" | "contain" | "cover" | "fill";
-export interface ImageOptions {
+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`; `fill` when exactly one axis is pinned so it scales to fit). */
+    /** 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;
 }
+/** 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

@@ -3,7 +3,9 @@ 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 { toDimension } from "./dimension.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,17 +33,100 @@ 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;
-    // Exactly one axis pinned -> the other is derived from the aspect ratio, so scale the image to the
-    // resulting box (fit: fill). Both or neither pinned keeps the default fit (none).
-    const autoScale = (opts.width !== undefined) !== (opts.height !== undefined);
-    const fit = opts.fit ? FIT[opts.fit] : autoScale ? BoxFit.fill : 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)
@@ -52,8 +137,12 @@ export function Image(src, opts = {}) {
         height: h?.points,
         widthFactor: w?.factor,
         heightFactor: h?.factor,
+        ...toBounds(opts),
         fit,
-        radius: opts.radius,
+        radius: opts.radius !== undefined ? toRadius(opts.radius) : undefined,
         alt: opts.alt,
-    });
+    })
+        .withAlignSelf(opts.alignSelf)
+        .withOrder(opts.order)
+        .withFlexShrink(opts.flexShrink);
 }

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

@@ -1,3 +1,5 @@
+import type { Radii } from "../ir/display-list.js";
+import type { CrossAlign } from "../layout/alignment.js";
 /**
  * Size input for a Box's `width` / `height` (relative sizing). Either a number of PDF points (a
  * fixed size) or a percentage string like `"50%"` - a fraction of the space the parent offers on
@@ -18,3 +20,58 @@ export interface Dimension {
  * boundary so `resolveExtent` and the layout never see a negative size.
  */
 export declare function toDimension(value: SizeInput): Dimension;
+/** The bound and ratio options every sized factory accepts, in the public `SizeInput` form. */
+export interface BoundsInput {
+    /**
+     * This element's own cross-axis alignment inside its Column / Row (CSS `align-self`), overriding the
+     * container's `align`. On a `Spacer` / `Expanded` it is a no-op - a flex child fills the main axis and
+     * has no natural cross size to align.
+     */
+    alignSelf?: CrossAlign;
+    /**
+     * Where this child sits among its siblings (CSS `order`), lowest first, source order deciding ties.
+     * It moves the child in the LAYOUT only - the element tree is untouched, so a tagged PDF still
+     * exposes the source reading order. Default 0.
+     */
+    order?: number;
+    /**
+     * How willingly this child gives up main-axis space when the line overflows (CSS `flex-shrink`),
+     * 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;
+    maxWidth?: SizeInput;
+    minHeight?: SizeInput;
+    maxHeight?: SizeInput;
+    /**
+     * width / height (CSS `aspect-ratio`). Fills in whichever axis you leave open, and sizes the box
+     * from the offered width when you leave both open. An explicit `min`/`max` still wins over it.
+     */
+    aspectRatio?: number;
+}
+/** Split `BoundsInput` into the points-and-factors form the elements take. */
+export declare function toBounds(o: BoundsInput): {
+    minWidth: number | undefined;
+    maxWidth: number | undefined;
+    minHeight: number | undefined;
+    maxHeight: number | undefined;
+    minWidthFactor: number | undefined;
+    maxWidthFactor: number | undefined;
+    minHeightFactor: number | undefined;
+    maxHeightFactor: number | undefined;
+    aspectRatio: number | undefined;
+};
+/**
+ * Corner radius input. A single number rounds all four corners; the object names them; the tuple is
+ * CSS order - `[topLeft, topRight, bottomRight, bottomLeft]`, clockwise from the top left.
+ */
+export type RadiusInput = number | {
+    topLeft?: number;
+    topRight?: number;
+    bottomRight?: number;
+    bottomLeft?: number;
+} | [number, number, number, number];
+/** Normalizes a `RadiusInput` to the engine's short corner names. */
+export declare function toRadius(r: RadiusInput): number | Radii;

package/dist/api/dimension.js

@@ -14,3 +14,30 @@ export function toDimension(value) {
         return { factor: parseFloat(m[1]) / 100 };
     throw new Error(`Invalid size "${value}": use a number of points or a percentage like "50%".`);
 }
+/** Split `BoundsInput` into the points-and-factors form the elements take. */
+export function toBounds(o) {
+    const d = (v) => (v !== undefined ? toDimension(v) : undefined);
+    const [minW, maxW, minH, maxH] = [d(o.minWidth), d(o.maxWidth), d(o.minHeight), d(o.maxHeight)];
+    if (o.aspectRatio !== undefined && !(o.aspectRatio > 0)) {
+        throw new Error(`Invalid aspectRatio ${o.aspectRatio}: it is width / height and must be above 0.`);
+    }
+    return {
+        minWidth: minW?.points,
+        maxWidth: maxW?.points,
+        minHeight: minH?.points,
+        maxHeight: maxH?.points,
+        minWidthFactor: minW?.factor,
+        maxWidthFactor: maxW?.factor,
+        minHeightFactor: minH?.factor,
+        maxHeightFactor: maxH?.factor,
+        aspectRatio: o.aspectRatio,
+    };
+}
+/** Normalizes a `RadiusInput` to the engine's short corner names. */
+export function toRadius(r) {
+    if (typeof r === "number")
+        return r;
+    if (Array.isArray(r))
+        return { tl: r[0], tr: r[1], br: r[2], bl: r[3] };
+    return { tl: r.topLeft, tr: r.topRight, br: r.bottomRight, bl: r.bottomLeft };
+}

package/dist/api/font-url.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Loading a font over the network for `doc.addFontFromUrl(...)`.
+ *
+ * `addFont` resolves its source AT REGISTRATION - a path is read there and then - and this keeps the
+ * same contract, differing only in being async. So the failure lands where you asked for the font,
+ * not somewhere inside a later render.
+ *
+ * `fetch` is used directly: it is in every browser and in Node since 18, so this needs no platform
+ * port, unlike the filesystem read beside it.
+ */
+/** One font file by URL, or a styled family of them. Mirrors `FontSource`, with strings meaning URLs. */
+export type UrlFontSource = string | {
+    normal: string;
+    bold?: string;
+    italic?: string;
+    boldItalic?: string;
+};
+/** Thrown when a font could not be fetched or is not one we can parse. Always says which URL. */
+export declare class FontUrlError extends Error {
+    constructor(message: string);
+}
+/** Fetch a whole `UrlFontSource`, in parallel for a family. */
+export declare function loadFontFromUrl(source: UrlFontSource): Promise<Uint8Array | {
+    normal: Uint8Array;
+    bold?: Uint8Array;
+    italic?: Uint8Array;
+    boldItalic?: Uint8Array;
+}>;

package/dist/api/font-url.js

@@ -0,0 +1,135 @@
+/**
+ * Loading a font over the network for `doc.addFontFromUrl(...)`.
+ *
+ * `addFont` resolves its source AT REGISTRATION - a path is read there and then - and this keeps the
+ * same contract, differing only in being async. So the failure lands where you asked for the font,
+ * not somewhere inside a later render.
+ *
+ * `fetch` is used directly: it is in every browser and in Node since 18, so this needs no platform
+ * port, unlike the filesystem read beside it.
+ */
+/** Thrown when a font could not be fetched or is not one we can parse. Always says which URL. */
+export class FontUrlError extends Error {
+    constructor(message) {
+        super(`@jasy/pdf: ${message}`);
+    }
+}
+/**
+ * What the first four bytes of an sfnt file say it is. Checked here because `TTFParser` does not look
+ * at them: it goes straight for the table directory, so an HTML error page or a WOFF would fail deep
+ * inside with `missing required table "head"` instead of saying what the file actually is.
+ */
+function describeSignature(bytes) {
+    const tag = String.fromCharCode(...bytes.subarray(0, 4));
+    const v = (bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3];
+    if (v === 0x00010000 || tag === "true")
+        return { ok: true, what: "TrueType" };
+    if (tag === "OTTO")
+        return { ok: false, what: "an OpenType/CFF font, which jasy does not parse yet" };
+    if (tag === "wOFF")
+        return { ok: true, what: "WOFF" };
+    if (tag === "wOF2")
+        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")
+        return { ok: false, what: "not a font at all" };
+    return { ok: false, what: "not a font we recognise" };
+}
+/** How long one font may take to arrive before we give up. A hung server must not hang a render. */
+const TIMEOUT_MS = 15000;
+/**
+ * How large a font file may be. Generous on purpose - a full CJK face is tens of megabytes and is a
+ * legitimate thing to embed - but not unbounded: a URL pointing at the wrong file (a video, a disk
+ * image) would otherwise be read into memory in full before anyone notices it is not a font.
+ */
+const MAX_BYTES = 32 * 1024 * 1024;
+/** Read the body with a running ceiling, so an oversized response is dropped WHILE it arrives. */
+async function readBounded(response, url) {
+    // `Content-Length` is the cheap early exit; a server may omit or misstate it, so it is a hint only
+    // and the real ceiling is enforced below while reading.
+    const declared = Number(response.headers?.get?.("content-length") ?? NaN);
+    if (Number.isFinite(declared) && declared > MAX_BYTES) {
+        throw new FontUrlError(`the font at ${url} is ${declared} bytes; the limit is ${MAX_BYTES}`);
+    }
+    const body = response.body;
+    if (!body?.getReader) {
+        // No streaming body (an older runtime, or a stubbed response): fall back to reading it whole and
+        // checking afterwards. Weaker, but never worse than not checking at all.
+        const whole = new Uint8Array(await response.arrayBuffer());
+        if (whole.length > MAX_BYTES) {
+            throw new FontUrlError(`the font at ${url} is larger than the ${MAX_BYTES} byte limit`);
+        }
+        return whole;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.length;
+        if (total > MAX_BYTES) {
+            await reader.cancel();
+            throw new FontUrlError(`the font at ${url} is larger than the ${MAX_BYTES} byte limit`);
+        }
+        chunks.push(value);
+    }
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const c of chunks) {
+        out.set(c, at);
+        at += c.length;
+    }
+    return out;
+}
+/** Fetch one font file and hand back its bytes, refusing anything we could not embed. */
+async function fetchFont(url) {
+    let response;
+    try {
+        response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    }
+    catch (e) {
+        const why = e?.name === "TimeoutError" || e?.name === "AbortError"
+            ? `it did not respond within ${TIMEOUT_MS} ms`
+            : String(e?.message ?? e);
+        throw new FontUrlError(`could not fetch the font at ${url}: ${why}`);
+    }
+    if (!response.ok) {
+        throw new FontUrlError(`the font at ${url} could not be fetched: HTTP ${response.status}`);
+    }
+    // Everything past here still talks to the network, so a failure mid-body must not escape as a raw
+    // TypeError - a caller catching FontUrlError would miss it.
+    let bytes;
+    try {
+        bytes = await readBounded(response, url);
+    }
+    catch (e) {
+        if (e instanceof FontUrlError)
+            throw e;
+        throw new FontUrlError(`the font at ${url} could not be read: ${String(e?.message ?? e)}`);
+    }
+    if (bytes.length < 4) {
+        throw new FontUrlError(`the font at ${url} is empty`);
+    }
+    const { ok, what } = describeSignature(bytes);
+    if (!ok) {
+        throw new FontUrlError(`the file at ${url} is ${what}. jasy embeds TrueType-flavoured fonts ` +
+            `(.ttf, .woff and .woff2)`);
+    }
+    return bytes;
+}
+/** Fetch a whole `UrlFontSource`, in parallel for a family. */
+export async function loadFontFromUrl(source) {
+    if (typeof source === "string")
+        return fetchFont(source);
+    const styles = ["normal", "bold", "italic", "boldItalic"];
+    const wanted = styles.filter((s) => source[s] !== undefined);
+    const loaded = await Promise.all(wanted.map((s) => fetchFont(source[s])));
+    const family = { normal: new Uint8Array() };
+    wanted.forEach((s, i) => (family[s] = loaded[i]));
+    return family;
+}