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

package/dist/api/gradient.d.ts

@@ -0,0 +1,53 @@
+import { type ColorInput } from "./color.js";
+import type { Gradient } from "../ir/display-list.js";
+/**
+ * Gradients for a box background.
+ *
+ * The public form is BOX-RELATIVE - an angle and some stops - because that is what an author knows
+ * when writing the document. The engine's `Gradient` wants absolute page coordinates, so the renderer
+ * resolves one against the box it is painting; see `resolveGradient`.
+ */
+/** A stop as written: a colour, optionally pinned to a position 0..1 along the axis. */
+export type StopInput = ColorInput | {
+    color: ColorInput;
+    at: number;
+};
+export interface LinearGradientInput {
+    kind: "linear";
+    /** Direction in degrees, CSS convention: 0 = to the top, 90 = to the right (default 180, downwards). */
+    angle: number;
+    stops: StopInput[];
+}
+export interface RadialGradientInput {
+    kind: "radial";
+    /** Centre as a fraction of the box, `[0.5, 0.5]` being the middle (the default). */
+    center: [number, number];
+    /** Outer radius as a fraction of the box's larger side (default 0.5, i.e. it touches the edges). */
+    radius: number;
+    stops: StopInput[];
+}
+export type GradientInput = LinearGradientInput | RadialGradientInput;
+export declare const isGradientInput: (v: unknown) => v is GradientInput;
+/**
+ * A linear gradient. `linearGradient("#fff", "#000")` runs top to bottom; pass `{ angle }` for any
+ * other direction, and `{ color, at }` for a stop that is not evenly spaced.
+ */
+export declare function linearGradient(...args: [...StopInput[]] | [{
+    angle?: number;
+    stops: StopInput[];
+}]): LinearGradientInput;
+/** A radial gradient, centred by default and reaching the edges. */
+export declare function radialGradient(...args: [...StopInput[]] | [{
+    center?: [number, number];
+    radius?: number;
+    stops: StopInput[];
+}]): RadialGradientInput;
+/**
+ * Resolve a box-relative gradient against the box it paints, into the absolute page coordinates the
+ * IR wants. Called by the renderer, which is the first place the box's geometry is known.
+ *
+ * The angle follows CSS: 0 points to the top and it turns clockwise, so 90 goes to the right. The
+ * axis runs through the box centre and is scaled so it spans the box on that diagonal - which is why
+ * a 45-degree gradient reaches the corners rather than stopping short of them.
+ */
+export declare function resolveGradient(g: GradientInput, x: number, y: number, width: number, height: number): Gradient;

package/dist/api/gradient.js

@@ -0,0 +1,97 @@
+import { toColor } from "./color.js";
+export const isGradientInput = (v) => typeof v === "object" && v !== null && "kind" in v && "stops" in v;
+/**
+ * A linear gradient. `linearGradient("#fff", "#000")` runs top to bottom; pass `{ angle }` for any
+ * other direction, and `{ color, at }` for a stop that is not evenly spaced.
+ */
+export function linearGradient(...args) {
+    const first = args[0];
+    if (args.length === 1 && typeof first === "object" && first !== null && "stops" in first) {
+        return { kind: "linear", angle: first.angle ?? 180, stops: first.stops };
+    }
+    return { kind: "linear", angle: 180, stops: args };
+}
+/** A radial gradient, centred by default and reaching the edges. */
+export function radialGradient(...args) {
+    const first = args[0];
+    if (args.length === 1 && typeof first === "object" && first !== null && "stops" in first) {
+        return {
+            kind: "radial",
+            center: first.center ?? [0.5, 0.5],
+            radius: first.radius ?? 0.5,
+            stops: first.stops,
+        };
+    }
+    return { kind: "radial", center: [0.5, 0.5], radius: 0.5, stops: args };
+}
+/**
+ * Spread the stops that carry no `at` evenly, first to last, the way CSS does - and check the pinned
+ * ones, because they end up in a PDF stitching function's `/Bounds`, which the format requires to be
+ * strictly increasing inside the domain. A bad offset there is not a wrong-looking gradient, it is a
+ * malformed file, so it is refused by name here rather than emitted.
+ */
+function toStops(stops) {
+    if (stops.length < 2) {
+        throw new Error("A gradient needs at least two colour stops.");
+    }
+    const last = stops.length - 1;
+    const out = stops.map((s, i) => {
+        const pinned = typeof s === "object" && s !== null && "at" in s;
+        const at = pinned ? s.at : i / last;
+        if (!Number.isFinite(at) || at < 0 || at > 1) {
+            throw new Error(`Invalid gradient stop position ${at}: it must be a number between 0 and 1.`);
+        }
+        return {
+            offset: at,
+            color: toColor(pinned ? s.color : s),
+        };
+    });
+    for (let i = 1; i < out.length; i++) {
+        if (out[i].offset <= out[i - 1].offset) {
+            throw new Error(`Gradient stops must move forward: stop ${i} sits at ${out[i].offset}, which is not after ` +
+                `${out[i - 1].offset}. (Two stops at the SAME position would be a hard colour edge in CSS; ` +
+                `PDF cannot express that in one shading, so it is refused rather than drawn wrongly.)`);
+        }
+    }
+    // A pinned first or last stop would otherwise be IGNORED - the shading's domain is always 0..1 and
+    // only the INTERIOR offsets reach /Bounds. Carrying the edge colour outwards is what CSS does.
+    if (out[0].offset > 0)
+        out.unshift({ offset: 0, color: out[0].color });
+    if (out[out.length - 1].offset < 1)
+        out.push({ offset: 1, color: out[out.length - 1].color });
+    return out;
+}
+/**
+ * Resolve a box-relative gradient against the box it paints, into the absolute page coordinates the
+ * IR wants. Called by the renderer, which is the first place the box's geometry is known.
+ *
+ * The angle follows CSS: 0 points to the top and it turns clockwise, so 90 goes to the right. The
+ * axis runs through the box centre and is scaled so it spans the box on that diagonal - which is why
+ * a 45-degree gradient reaches the corners rather than stopping short of them.
+ */
+export function resolveGradient(g, x, y, width, height) {
+    const stops = toStops(g.stops);
+    if (g.kind === "radial") {
+        const cx = x + g.center[0] * width;
+        const cy = y + g.center[1] * height;
+        const r = g.radius * Math.max(width, height);
+        return { type: "radial", x0: cx, y0: cy, r0: 0, x1: cx, y1: cy, r1: r, stops, extend: "pad" };
+    }
+    const rad = ((g.angle % 360) * Math.PI) / 180;
+    // CSS angles: 0 = up, clockwise. The engine lays out top-left down, so "up" is -y here.
+    const dx = Math.sin(rad);
+    const dy = -Math.cos(rad);
+    // Half the box's extent along the axis, so the line covers the whole box for any angle.
+    const half = (Math.abs(dx) * width + Math.abs(dy) * height) / 2;
+    const cx = x + width / 2;
+    const cy = y + height / 2;
+    return {
+        type: "linear",
+        x0: cx - dx * half,
+        y0: cy - dy * half,
+        x1: cx + dx * half,
+        y1: cy + dy * half,
+        stops,
+        extend: "pad",
+    };
+}

package/dist/api/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./color.js";
 export * from "./insets.js";
+export * from "./gradient.js";
+export * from "./font-url.js";
 export * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.js";

package/dist/api/index.js

@@ -3,6 +3,8 @@
 // core classes stay untouched and remain exported for power users.
 export * from "./color.js";
 export * from "./insets.js";
+export * from "./gradient.js";
+export * from "./font-url.js";
 export * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.js";

package/dist/api/insets.d.ts

@@ -1,16 +1,23 @@
+import { SizeInput } from "./dimension.js";
+import type { EdgeSpecs } from "../layout/insets.js";
 /**
- * Spacing input for padding / margin (locked design §3). Units are PDF points. Every form
- * normalizes to the engine's `[top, right, bottom, left]` via `toEdges`, so you can reach
+ * Spacing input for padding / margin (locked design §3). Points, or a percentage string like `"5%"`.
+ * Every form normalizes to the engine's `[top, right, bottom, left]` via `toEdges`, so you can reach
  * for whichever shape fits and never think about the engine order.
+ *
+ * **A percentage resolves against the available WIDTH - on all four sides, top and bottom included.**
+ * That is the CSS rule, and Yoga's, so react-pdf behaves the same. It reads as wrong the first time and
+ * is what makes `padding-bottom: 56.25%` a 16:9 box on the web. A percentage needs a bounded width; in
+ * an unbounded region it resolves to 0, the same no-op a percentage SIZE gives there.
  */
-export type Insets = number | {
-    x?: number;
-    y?: number;
+export type Insets = SizeInput | {
+    x?: SizeInput;
+    y?: SizeInput;
 } | {
-    top?: number;
-    right?: number;
-    bottom?: number;
-    left?: number;
-} | [number, number, number, number];
-/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`. */
-export declare function toEdges(i: Insets): [number, number, number, number];
+    top?: SizeInput;
+    right?: SizeInput;
+    bottom?: SizeInput;
+    left?: SizeInput;
+} | [SizeInput, SizeInput, SizeInput, SizeInput];
+/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`, percentages still unresolved. */
+export declare function toEdges(i: Insets): EdgeSpecs;

package/dist/api/insets.js

@@ -1,17 +1,28 @@
-/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`. */
+import { toDimension } from "./dimension.js";
+// A fixed side stays a plain NUMBER, so the output is unchanged for every input that was legal before
+// this file learned percentages - `toEdges` is publicly exported and did not need to break.
+const spec = (v) => {
+    if (v === undefined)
+        return 0;
+    const d = toDimension(v);
+    return d.points ?? { factor: d.factor };
+};
+/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`, percentages still unresolved. */
 export function toEdges(i) {
-    if (typeof i === "number")
-        return [i, i, i, i];
+    if (typeof i === "number" || typeof i === "string") {
+        const s = spec(i);
+        return [s, s, s, s];
+    }
     if (Array.isArray(i))
-        return i;
+        return [spec(i[0]), spec(i[1]), spec(i[2]), spec(i[3])];
     // Axis form ({x, y}) and per-side form ({top,...}) are both all-optional objects (TS
     // can't discriminate them), so read through one shape: an axis key present picks the
     // axis interpretation (an empty object is all-zero either way).
     const o = i;
     if (o.x !== undefined || o.y !== undefined) {
-        const x = o.x ?? 0;
-        const y = o.y ?? 0;
+        const x = spec(o.x);
+        const y = spec(o.y);
         return [y, x, y, x];
     }
-    return [o.top ?? 0, o.right ?? 0, o.bottom ?? 0, o.left ?? 0];
+    return [spec(o.top), spec(o.right), spec(o.bottom), spec(o.left)];
 }

package/dist/api/layout.d.ts

@@ -11,10 +11,11 @@ import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
 import { PDFElement } from "../elements/pdf-element.js";
 import { MainAlign, CrossAlign } from "../utils/flex-layout.js";
 import { ColorInput } from "./color.js";
+import { type GradientInput } from "./gradient.js";
 import { Insets } from "./insets.js";
-import { SizeInput } from "./dimension.js";
+import { BoundsInput, SizeInput, RadiusInput } from "./dimension.js";
 /** Options shared by the `Column` and `Row` stacks (locked §4). */
-export interface StackOptions {
+export interface StackOptions extends BoundsInput {
     /** Space inserted between children, in points. */
     gap?: number;
     /** Distribution along the main axis (CSS `justify-content`): start (default) · center · end ·
@@ -35,6 +36,13 @@ export interface StackOptions {
     /** Try to keep this stack on one page (CSS `break-inside: avoid`). If it does not fit here but would
      *  fit on a fresh page, it moves there whole; if it is taller than a whole page, it splits anyway. */
     keepTogether?: boolean;
+    /** Lay the children out backwards along the axis (CSS `row-reverse` / `column-reverse`). */
+    reverse?: boolean;
+    /** Let the children flow onto further lines when they do not fit (CSS `flex-wrap: wrap`). The `gap`
+     *  is used BETWEEN the lines as well as between the items. */
+    wrap?: boolean;
+    /** How the block of wrapped lines sits across the axis (CSS `align-content`). Default `start`. */
+    alignContent?: MainAlign;
 }
 /** A vertical stack. `Column(children)` or `Column(opts, children)`. */
 export declare function Column(children: PDFElement[]): PDFElement;
@@ -50,7 +58,7 @@ export declare function Row(opts: StackOptions, children: PDFElement[]): PDFElem
  */
 export declare function keepTogether(children: PDFElement[]): KeepTogetherElement;
 /** A bordered / filled box that wraps its children (locked §4). */
-export interface BoxOptions {
+export interface BoxOptions extends BoundsInput {
     /** Border (stroke) color. A box has a border only when `border` or `borderWidth` is set. */
     border?: ColorInput;
     /** Per-side border colors - override/add to `border`. Any of these makes the box draw
@@ -62,8 +70,8 @@ export interface BoxOptions {
     borderLeft?: ColorInput;
     /** Border thickness in points (default 1 when a border is present). */
     borderWidth?: number;
-    /** Background fill color. */
-    bg?: ColorInput;
+    /** Background: a colour, or a gradient from `linearGradient()` / `radialGradient()`. */
+    bg?: ColorInput | GradientInput;
     /** Inner padding between the border and the children. */
     padding?: Insets;
     /** Size on each axis: a number of points (fixed) or a percentage string like `"50%"` (a fraction
@@ -72,7 +80,7 @@ export interface BoxOptions {
     width?: SizeInput;
     height?: SizeInput;
     /** Corner radius in points. */
-    radius?: number;
+    radius?: RadiusInput;
     /** Make this box a positioning frame: `Positioned` children placed inside it resolve their
      *  offsets against this box (CSS `position: relative`). */
     relative?: boolean;
@@ -173,6 +181,12 @@ export declare function PageBreak(): PageBreakElement;
 export interface ExpandedOptions {
     /** Share of the leftover space vs other flex children (default 1). */
     flex?: number;
+    /**
+     * Main-axis size reserved BEFORE the leftover is shared out (CSS `flex-basis`): points, or a
+     * percentage of what the line offers its items. The child ends up with `basis + its share of the
+     * rest`, so `flexBasis: 120` with `flex: 0` is simply a fixed 120pt slot. Default 0.
+     */
+    flexBasis?: SizeInput;
 }
 /**
  * Makes a child fill the leftover space along the stack's main axis (height in a Column,

package/dist/api/layout.js

@@ -12,14 +12,21 @@ import { AnchorElement } from "../elements/layout/anchor-element.js";
 import { RotatedElement } from "../elements/layout/rotated-element.js";
 import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
 import { toColor } from "./color.js";
+import { isGradientInput } from "./gradient.js";
 import { toEdges } from "./insets.js";
-import { toDimension } from "./dimension.js";
+import { toBounds, toDimension, toRadius, } from "./dimension.js";
 import { splitArgs } from "./args.js";
 /** Splits `StackOptions` width/height into the fixed points + fraction the stack elements expect. */
 function stackSize(opts) {
     const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
     const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
-    return { width: w?.points, height: h?.points, widthFactor: w?.factor, heightFactor: h?.factor };
+    return {
+        width: w?.points,
+        height: h?.points,
+        widthFactor: w?.factor,
+        heightFactor: h?.factor,
+        ...toBounds(opts),
+    };
 }
 // The public default for `cross` is `start` (locked §5) - i.e. don't stretch a child unless
 // asked. The engine default is `stretch`; the factory sets the friendlier public one.
@@ -33,6 +40,9 @@ export function Column(a, b) {
         gap: opts.gap,
         main: opts.justify, // undefined → engine default `start` (matches §5)
         cross: opts.align ?? DEFAULT_CROSS,
+        reverse: opts.reverse,
+        wrap: opts.wrap,
+        alignContent: opts.alignContent,
         breakBefore: opts.breakBefore,
         breakAfter: opts.breakAfter,
         ...stackSize(opts),
@@ -45,6 +55,9 @@ export function Row(a, b) {
         gap: opts.gap,
         main: opts.justify,
         cross: opts.align ?? DEFAULT_CROSS,
+        reverse: opts.reverse,
+        wrap: opts.wrap,
+        alignContent: opts.alignContent,
         breakBefore: opts.breakBefore,
         breakAfter: opts.breakAfter,
         ...stackSize(opts),
@@ -53,7 +66,12 @@ export function Row(a, b) {
 /** Wraps `element` in a `keepTogether` group when the `keepTogether` option is set; otherwise returns it
  *  unchanged (byte-identical). Shared by the `Box`/`Column`/`Row` prop shortcut. */
 function maybeKeepTogether(opts, element) {
-    return opts.keepTogether ? new KeepTogetherElement({ child: element }) : element;
+    // alignSelf and order go on the OUTERMOST element - that is the one the surrounding stack places.
+    const wrapped = opts.keepTogether ? new KeepTogetherElement({ child: element }) : element;
+    return wrapped
+        .withAlignSelf(opts.alignSelf)
+        .withOrder(opts.order)
+        .withFlexShrink(opts.flexShrink);
 }
 /**
  * Keep a group of elements on ONE page (CSS `break-inside: avoid`). `keepTogether([...])` stacks the
@@ -92,13 +110,14 @@ export function Box(a, b) {
         y: 0,
         children: content,
         color: opts.border !== undefined ? toColor(opts.border) : undefined,
-        backgroundColor: opts.bg !== undefined ? toColor(opts.bg) : undefined,
+        backgroundColor: opts.bg === undefined ? undefined : isGradientInput(opts.bg) ? opts.bg : toColor(opts.bg),
         borderWidth: hasBorder ? (opts.borderWidth ?? 1) : 0,
         width: w?.points,
         height: h?.points,
         widthFactor: w?.factor,
         heightFactor: h?.factor,
-        radius: opts.radius,
+        ...toBounds(opts),
+        radius: opts.radius !== undefined ? toRadius(opts.radius) : undefined,
         sideBorders: hasPerSide
             ? {
                 top: side(opts.borderTop),
@@ -201,5 +220,11 @@ export function Expanded(a, b) {
     const isOptsForm = b !== undefined;
     const opts = (isOptsForm ? a : {});
     const child = (isOptsForm ? b : a);
-    return new ExpandedElement({ flex: opts.flex ?? 1, child });
+    const basis = opts.flexBasis !== undefined ? toDimension(opts.flexBasis) : undefined;
+    return new ExpandedElement({
+        flex: opts.flex ?? 1,
+        basis: basis?.points,
+        basisFactor: basis?.factor,
+        child,
+    });
 }

package/dist/api/page-builder.d.ts

@@ -16,6 +16,10 @@ export type { PageInfo };
  * `pageNumber` is 1-based and counts PHYSICAL pages (an overflowing `Page` contributes several);
  * `pageCount` is the document total; `pageSize` is the media box in points.
  *
+ * `subPageNumber` / `subPageTotalPages` are the same counts WITHIN one logical `Page` element - what you
+ * want when a document is several sections and the footer should say "Attachment, page 1 of 4" beside
+ * "sheet 4 of 7". With a single `Page` they are identical to the document counts.
+ *
  * The numbers themselves are always exact. Two sizing caveats, both from the same chicken-and-egg (the
  * content decides the count that the content displays): in the flowing BODY the box is reserved before the
  * total is known, so a much wider final string can paint slightly past it; and a conditional header may
@@ -30,3 +34,7 @@ export interface PageNumberOptions extends TextOptions {
 export declare function PageNumber({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
 /** The document's total page count as text. Sugar for `PageBuilder`. */
 export declare function PageCount({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
+/** The page number WITHIN its logical `Page` (a section), as text. Sugar for `PageBuilder`. */
+export declare function SubPageNumber({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
+/** How many pages the surrounding logical `Page` produced, as text. Sugar for `PageBuilder`. */
+export declare function SubPageCount({ offset, ...style }?: PageNumberOptions): PageBuilderElement;

package/dist/api/page-builder.js

@@ -14,6 +14,10 @@ import { Text } from "./text.js";
  * `pageNumber` is 1-based and counts PHYSICAL pages (an overflowing `Page` contributes several);
  * `pageCount` is the document total; `pageSize` is the media box in points.
  *
+ * `subPageNumber` / `subPageTotalPages` are the same counts WITHIN one logical `Page` element - what you
+ * want when a document is several sections and the footer should say "Attachment, page 1 of 4" beside
+ * "sheet 4 of 7". With a single `Page` they are identical to the document counts.
+ *
  * The numbers themselves are always exact. Two sizing caveats, both from the same chicken-and-egg (the
  * content decides the count that the content displays): in the flowing BODY the box is reserved before the
  * total is known, so a much wider final string can paint slightly past it; and a conditional header may
@@ -30,3 +34,11 @@ export function PageNumber({ offset = 0, ...style } = {}) {
 export function PageCount({ offset = 0, ...style } = {}) {
     return PageBuilder(({ pageCount }) => Text(String(pageCount + offset), style));
 }
+/** The page number WITHIN its logical `Page` (a section), as text. Sugar for `PageBuilder`. */
+export function SubPageNumber({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ subPageNumber }) => Text(String(subPageNumber + offset), style));
+}
+/** How many pages the surrounding logical `Page` produced, as text. Sugar for `PageBuilder`. */
+export function SubPageCount({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ subPageTotalPages }) => Text(String(subPageTotalPages + offset), style));
+}

package/dist/api/structure.d.ts

@@ -7,6 +7,7 @@ import { PageSize } from "../constants/page-sizes.js";
 import { type EncryptOptions } from "../crypto/security-handler.js";
 export type { EncryptOptions, Permissions } from "../crypto/security-handler.js";
 import { StackOptions } from "./layout.js";
+import { type UrlFontSource } from "./font-url.js";
 import { Insets } from "./insets.js";
 import { TextDefaults } from "./text.js";
 /** A custom page size. Use the `mm()` helper for millimetres, or pass points directly. */
@@ -78,6 +79,10 @@ export interface JasyDocument extends PDFDocumentElement {
      *  path (read now, on Node), raw bytes, or a styled family. Re-adding a name overwrites it.
      *  A registered font that no `Text` actually uses is dropped at render and costs nothing. */
     addFont(name: string, source: FontSource): this;
+    /** The same, from a URL. Async because the fetch happens NOW, exactly as `addFont` reads a path
+     *  now - so a broken link fails where you asked for the font, not inside a later render.
+     *  `await doc.addFontFromUrl("Inter", "https://…/Inter-Regular.ttf")`, or a styled family of URLs. */
+    addFontFromUrl(name: string, source: UrlFontSource): Promise<this>;
     /** The names of the registered fonts. */
     getFonts(): string[];
     /** Whether a font is registered under `name`. */
@@ -146,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

@@ -2,7 +2,8 @@ import { readFileBytes } from "../platform/node-fs.js";
 import { PDFDocumentElement } from "../elements/pdf-document-element.js";
 import { PageElement } from "../elements/page-element.js";
 import { DefaultTextStyleElement } from "../elements/layout/default-text-style-element.js";
-import { PageSize } from "../constants/page-sizes.js";
+import { PageSize, pageFormats } from "../constants/page-sizes.js";
+import { resolveEdges } from "../layout/insets.js";
 import { Orientation } from "../renderer/pdf-config.js";
 import { PDFDocument } from "../renderer/pdf-document-class.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
@@ -10,8 +11,10 @@ import { getArrayBuffer } from "../utils/utf8-to-windows1252-encoder.js";
 import { createSecurityHandler } from "../crypto/security-handler.js";
 import { uaXmp } from "../utils/ua-xmp.js";
 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) {
@@ -38,10 +41,16 @@ export function Page(a, b) {
     const isOpts = !Array.isArray(a);
     const opts = (isOpts ? a : {});
     const children = (isOpts ? (b ?? []) : a);
-    const [top, right, bottom, left] = toEdges(opts.margin ?? DEFAULT_MARGIN);
+    const size = resolveSize(opts.size);
+    const landscape = opts.orientation === "landscape";
+    // A percentage margin resolves against the page WIDTH (see `Insets`), which is known right here -
+    // the page is the one box whose geometry does not depend on a parent.
+    const [w, h] = size.customSize ?? pageFormats[size.pageSize ?? PageSize.A4];
+    const pageWidth = landscape ? h : w;
+    const [top, right, bottom, left] = resolveEdges(toEdges(opts.margin ?? DEFAULT_MARGIN), pageWidth);
     const config = {
-        ...resolveSize(opts.size),
-        orientation: opts.orientation === "landscape" ? Orientation.landscape : Orientation.portrait,
+        ...size,
+        orientation: landscape ? Orientation.landscape : Orientation.portrait,
         margin: { top, right, bottom, left },
     };
     return new PageElement({
@@ -59,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);
@@ -93,6 +125,10 @@ export function Document(a, b) {
         registry.set(name, resolveFontSource(source));
         return doc;
     };
+    doc.addFontFromUrl = async (name, source) => {
+        registry.set(name, await loadFontFromUrl(source));
+        return doc;
+    };
     doc.getFonts = () => [...registry.keys()];
     doc.hasFont = (name) => registry.has(name);
     return doc;
@@ -118,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.
@@ -131,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
@@ -195,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) {