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

package/dist/elements/pdf-element.js

@@ -5,6 +5,24 @@ export class PDFElement {
         // fragmentation copies (adoptStructId), so a paragraph or table split across pages stays ONE structure
         // element. Only the elements that actually tag (Text, Image, StructGroup) read it.
         this._structId = _nextStructId++;
+        /**
+         * 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, and therefore the reading order a tagged
+         * PDF exposes, is untouched. Default 0.
+         */
+        this.order = 0;
+        /**
+         * How willingly this child gives up main-axis space when the line overflows (CSS `flex-shrink`),
+         * weighted by its own size as CSS does. Default 1, as in CSS: an overflowing line squeezes its
+         * children back inside instead of letting them run past the edge of the box. `0` opts out and keeps
+         * a child at its natural size.
+         *
+         * This was 0 until the alpha, so that adding flexShrink could not move an existing layout. That
+         * caution outlived its use: four of the gallery cases turned out to be overflowing their page
+         * margin without anyone noticing, because nothing ever pulled them back. Shrinking is bounded from
+         * below by `minIntrinsicMain`, so a child is never squeezed past what it can actually hold.
+         */
+        this.flexShrink = 1;
     }
     get structId() {
         return this._structId;
@@ -33,6 +51,19 @@ export class PDFElement {
     needsBoundedMain(_horizontal) {
         return false;
     }
+    /**
+     * The smallest main-axis extent this element can be squeezed into and still hold its content - CSS's
+     * `min-content` size, which is what an automatic `min-width` resolves to on a flex item. The shrink
+     * pass floors every child at this value, so a line that overflows badly stops squeezing rather than
+     * grinding a paragraph down to one word per line (which would only trade a wide box for a tall one).
+     *
+     * `horizontal` = the width. Default 0: an element with no opinion may be squeezed to nothing, which
+     * is what an empty box or a plain drawing can do without harm. Text and the layout containers
+     * override it; containers recurse, since a Row is only as unsqueezable as its children.
+     */
+    minIntrinsicMain(_horizontal, _ctx) {
+        return 0;
+    }
     /**
      * Whether this element IS a forced page break (a `PageBreak`). The pagination packer cuts the flow
      * at such a marker: everything before it stays, everything after starts a new page. Default: no.
@@ -65,6 +96,31 @@ export class PDFElement {
     breaksAfter() {
         return false;
     }
+    /** Sets `alignSelf` and returns the element, so a factory can thread it through in one expression. */
+    withAlignSelf(align) {
+        if (align !== undefined)
+            this.alignSelf = align;
+        return this;
+    }
+    /** Sets `flexShrink` and returns the element. */
+    withFlexShrink(shrink) {
+        if (shrink !== undefined) {
+            if (!Number.isFinite(shrink) || shrink < 0) {
+                throw new Error(`Invalid flexShrink ${shrink}: it must be a number of at least 0.`);
+            }
+            this.flexShrink = shrink;
+        }
+        return this;
+    }
+    /** Sets `order` and returns the element, so a factory can thread it through in one expression. */
+    withOrder(order) {
+        if (order !== undefined) {
+            if (!Number.isFinite(order))
+                throw new Error(`Invalid order ${order}: it must be a number.`);
+            this.order = order;
+        }
+        return this;
+    }
 }
 export class SizedPDFElement extends PDFElement {
     constructor(data) {
@@ -83,17 +139,40 @@ export class FlexiblePDFElement extends PDFElement {
         super();
         this.flex = data.flex;
         this.verticalChildAlignment = data.verticalChildAlignment || VerticalAlignment.middle;
+        this.basis = data.basis ?? 0;
+        this.basisFactor = data.basisFactor;
     }
     getFlex() {
         return this.flex;
     }
+    /**
+     * The main extent this child starts from, before the leftover is shared out. `lineMain` is what the
+     * line offers its items (its extent minus the gaps), so a percentage basis resolves against the same
+     * base a percentage WIDTH already does - and falls back to 0 on an unbounded axis, where a fraction
+     * has no meaning.
+     */
+    /** Whether a PERCENTAGE basis was given - it resolves to 0 on an unbounded axis, so asking for the
+     *  number alone cannot tell "no basis" from "a basis that does not apply here". */
+    hasBasisFactor() {
+        return this.basisFactor !== undefined;
+    }
+    getBasis(lineMain) {
+        if (this.basisFactor !== undefined) {
+            return Number.isFinite(lineMain) ? lineMain * this.basisFactor : 0;
+        }
+        return this.basis;
+    }
 }
 export var HorizontalAlignment;
 (function (HorizontalAlignment) {
+    /** CSS `text-align: start` - the side the writing STARTS on: left in `ltr`, right in `rtl`. The
+     *  default, so a right-to-left paragraph begins on the right without anyone asking for it. */
+    HorizontalAlignment["start"] = "START";
     HorizontalAlignment["left"] = "LEFT";
     HorizontalAlignment["right"] = "RIGHT";
     HorizontalAlignment["center"] = "CENTER";
-    HorizontalAlignment["block"] = "BLOCK";
+    /** CSS `text-align: justify` - both edges line up, the last line of a paragraph excepted. */
+    HorizontalAlignment["justify"] = "JUSTIFY";
 })(HorizontalAlignment || (HorizontalAlignment = {}));
 export var VerticalAlignment;
 (function (VerticalAlignment) {

package/dist/elements/rectangle-element.d.ts

@@ -1,3 +1,5 @@
+import type { Radii } from "../ir/display-list.js";
+import type { GradientInput } from "../api/gradient.js";
 import { Color } from "../common/color.js";
 import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 import { Fragmentable, FragmentResult } from "../layout/fragmentation.js";
@@ -12,10 +14,11 @@ export interface SideBorders {
 }
 interface RectangleElementParams extends SizedElement, WithChildren {
     color?: Color;
-    backgroundColor?: Color;
+    /** Solid colour, or a box-relative gradient the renderer resolves against this box. */
+    backgroundColor?: Color | GradientInput;
     borderWidth?: number;
-    /** Corner radius in points; 0 = sharp corners (default). */
-    radius?: number;
+    /** Corner radius in points - one number for all four corners, or per corner. 0 = sharp (default). */
+    radius?: number | Radii;
     /** Individual side borders; overrides the uniform `color` border when present. */
     sideBorders?: SideBorders;
     /** When true, this box is a positioning frame for `Positioned` descendants (CSS `relative`). */
@@ -28,6 +31,17 @@ interface RectangleElementParams extends SizedElement, WithChildren {
     widthFactor?: number;
     /** Height as a fraction (0..1) of the offered height; see `widthFactor`. */
     heightFactor?: number;
+    /** Lower / upper bounds per axis, in points or as a fraction; see `SizingParams`. */
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minWidthFactor?: number;
+    maxWidthFactor?: number;
+    minHeightFactor?: number;
+    maxHeightFactor?: number;
+    /** width / height; derives whichever axis is left open (CSS `aspect-ratio`). */
+    aspectRatio?: number;
     /** Start this box on a fresh page (CSS `break-before: page`). */
     breakBefore?: boolean;
     /** Start everything after this box on a fresh page (CSS `break-after: page`). */
@@ -45,7 +59,7 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
     private breakBefore;
     private breakAfter;
     private sizeMemory;
-    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, widthFactor, heightFactor, breakBefore, breakAfter, }: RectangleElementParams);
+    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, breakBefore, breakAfter, ...sizing }: RectangleElementParams);
     breaksBefore(): boolean;
     breaksAfter(): boolean;
     /**
@@ -64,6 +78,8 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
      *  `Spacer` in a box can only resolve if the box itself was given a bounded extent to pass down. With an
      *  explicit size on an axis the box already knows its extent there and asks for nothing. */
     needsBoundedMain(horizontal: boolean): boolean;
+    /** A Box stacks its children vertically inside its border, which is on both sides of the axis. */
+    minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     getProps(): {
         x: number;
@@ -72,9 +88,9 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
         height: number | undefined;
         children: PDFElement[];
         color: Color;
-        backgroundColor: Color | undefined;
+        backgroundColor: Color | GradientInput | undefined;
         borderWidth: number;
-        radius: number;
+        radius: number | Radii;
         sideBorders: SideBorders | undefined;
         overflow: "hidden" | "visible";
     };

package/dist/elements/rectangle-element.js

@@ -1,9 +1,10 @@
 import { Color } from "../common/color.js";
-import { BoxConstraints, resolveExtent } from "../layout/box-constraints.js";
+import { BoxConstraints, extentSpecs, resolveSize, } from "../layout/box-constraints.js";
+import { stackMinIntrinsic, withDeclaredExtent } from "../layout/min-intrinsic.js";
 import { childrenForceBreak, packChildren, } from "../layout/fragmentation.js";
 import { SizedPDFElement, } from "./pdf-element.js";
 export class RectangleElement extends SizedPDFElement {
-    constructor({ children = [], color = new Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, widthFactor, heightFactor, breakBefore, breakAfter, }) {
+    constructor({ children = [], color = new Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, breakBefore, breakAfter, ...sizing }) {
         super({ x: 0, y: 0, width, height });
         this.children = [];
         this.children = children;
@@ -17,7 +18,7 @@ export class RectangleElement extends SizedPDFElement {
         this.overflow = overflow ?? "visible";
         this.breakBefore = breakBefore ?? false;
         this.breakAfter = breakAfter ?? false;
-        this.sizeMemory = { x: 0, y: 0, width, height, widthFactor, heightFactor };
+        this.sizeMemory = { ...sizing, x: 0, y: 0, width, height };
     }
     breaksBefore() {
         return this.breakBefore;
@@ -99,18 +100,29 @@ export class RectangleElement extends SizedPDFElement {
             return false;
         return this.children.some((c) => c.needsBoundedMain(horizontal));
     }
+    /** A Box stacks its children vertically inside its border, which is on both sides of the axis. */
+    minIntrinsicMain(horizontal, ctx) {
+        const content = stackMinIntrinsic(this.children, 0, !horizontal, horizontal, ctx) + 2 * this.borderWidth;
+        return withDeclaredExtent(content, horizontal ? this.sizeMemory.width : this.sizeMemory.height, horizontal ? this.sizeMemory.minWidth : this.sizeMemory.minHeight);
+    }
     calculateLayout(constraints, offset, ctx) {
         // An explicit extent is a fixed point size or a fraction of the offered box (relative sizing);
         // the fraction only resolves in a bounded region. `undefined` = fill / shrink-wrap below.
-        const explicitWidth = resolveExtent(this.sizeMemory.width, this.sizeMemory.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
-        const explicitHeight = resolveExtent(this.sizeMemory.height, this.sizeMemory.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
+        const specs = extentSpecs(this.sizeMemory);
+        const resolved = resolveSize(specs.width, specs.height, this.sizeMemory.aspectRatio, constraints);
+        const explicitWidth = resolved.width;
+        const explicitHeight = resolved.height;
+        // min/max come back as narrowed constraints, so the fill and shrink-wrap paths below obey them too.
+        const bounds = resolved.constraints;
         // Width: an explicit size wins (clamped), else fill the offered box. (Without this a
         // fixed box would balloon to the parent's size.)
+        // Whether there is a region to fill is decided by the constraints we were GIVEN: a `maxWidth` caps
+        // a box, it does not turn a shrink-wrapping one into a filling one (CSS `max-width` does not either).
         this.width =
             explicitWidth !== undefined
-                ? constraints.constrainWidth(explicitWidth)
+                ? bounds.constrainWidth(explicitWidth)
                 : constraints.hasBoundedWidth
-                    ? constraints.maxWidth
+                    ? bounds.maxWidth
                     : this.width;
         // Width shrink-wrap: no explicit width AND an unbounded region (e.g. a `Box` badge inside a
         // `Positioned`). Resolved after the children are measured, just below.
@@ -121,9 +133,9 @@ export class RectangleElement extends SizedPDFElement {
         const shrinkWrapHeight = explicitHeight === undefined && !constraints.hasBoundedHeight;
         this.height =
             explicitHeight !== undefined
-                ? constraints.constrainHeight(explicitHeight)
+                ? bounds.constrainHeight(explicitHeight)
                 : constraints.hasBoundedHeight
-                    ? constraints.maxHeight
+                    ? bounds.maxHeight
                     : this.height;
         this.x = this.sizeMemory.x + offset.x;
         this.y = this.sizeMemory.y + offset.y;
@@ -161,11 +173,18 @@ export class RectangleElement extends SizedPDFElement {
             contentWidth = Math.max(contentWidth, childSize.width);
         }
         // No explicit width and no bounded region: shrink-wrap to the widest child.
+        // Clamped, so a min/max still applies to a box that sized itself to its content.
         if (shrinkWrapWidth)
-            this.width = contentWidth + 2 * this.borderWidth;
+            this.width = bounds.constrainWidth(contentWidth + 2 * this.borderWidth);
+        // A ratio on a shrink-wrapping box can only be applied HERE: before the children were measured
+        // there was no width to derive the height from.
+        const ratio = this.sizeMemory.aspectRatio;
+        const ratioSizesHeight = ratio !== undefined && ratio > 0 && shrinkWrapWidth && shrinkWrapHeight;
         // No explicit height and no bounded region: the border hugs its content.
-        if (shrinkWrapHeight)
-            this.height = contentHeight + 2 * this.borderWidth;
+        if (ratioSizesHeight)
+            this.height = bounds.constrainHeight((this.width ?? 0) / ratio);
+        else if (shrinkWrapHeight)
+            this.height = bounds.constrainHeight(contentHeight + 2 * this.borderWidth);
         // The box is sized now: place any out-of-flow `Positioned` descendants against its box.
         if (frame) {
             frame.origin = { x: this.x, y: this.y };

package/dist/elements/row-element.d.ts

@@ -8,11 +8,28 @@ interface RowElementParams extends WithChildren {
     main?: MainAlign;
     /** Vertical alignment of each child (cross axis); defaults to `stretch`. */
     cross?: CrossAlign;
+    /** Lay the children out backwards along the main axis (CSS `row-reverse`). */
+    reverse?: boolean;
+    /** Let the children flow onto further lines when they do not fit (CSS `flex-wrap`). */
+    wrap?: boolean;
+    /** How the block of wrapped lines sits across the axis (CSS `align-content`). */
+    alignContent?: MainAlign;
     /** Width/height as points (fixed) or a fraction (0..1) of the offered box (relative sizing). */
     width?: number;
     height?: number;
     widthFactor?: number;
     heightFactor?: number;
+    /** Lower / upper bounds per axis, in points or as a fraction; see `SizingParams`. */
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minWidthFactor?: number;
+    maxWidthFactor?: number;
+    minHeightFactor?: number;
+    maxHeightFactor?: number;
+    /** width / height; derives whichever axis is left open (CSS `aspect-ratio`). */
+    aspectRatio?: number;
     /** Start this row on a fresh page (CSS `break-before: page`). */
     breakBefore?: boolean;
     /** Start everything after this row on a fresh page (CSS `break-after: page`). */
@@ -35,16 +52,21 @@ export declare class RowElement extends SizedPDFElement {
     private gap;
     private main;
     private cross;
+    private reverse;
+    private wrap;
+    private alignContent?;
     private breakBefore;
     private breakAfter;
     private requested;
-    constructor({ children, gap, main, cross, width, height, widthFactor, heightFactor, breakBefore, breakAfter, }: RowElementParams);
+    constructor({ children, gap, main, cross, reverse, wrap, alignContent, width, height, breakBefore, breakAfter, ...sizing }: RowElementParams);
     breaksBefore(): boolean;
     breaksAfter(): boolean;
     relativeSizeFactor(horizontal: boolean): number | undefined;
     /** The mirror of `ContainerElement`: a Row's OWN flex child needs a bounded width, and the need of any
      *  descendant propagates on both axes (see the Column for the reasoning). */
     needsBoundedMain(horizontal: boolean): boolean;
+    /** A Row lays out side by side, so widths add up (gaps included) and heights overlap. */
+    minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     getProps(): {
         x: number;
@@ -55,6 +77,9 @@ export declare class RowElement extends SizedPDFElement {
         gap: number;
         main: MainAlign;
         cross: CrossAlign;
+        reverse: boolean;
+        wrap: boolean;
+        alignContent: MainAlign | undefined;
     };
 }
 export {};

package/dist/elements/row-element.js

@@ -1,5 +1,6 @@
-import { resolveExtent } from "../layout/box-constraints.js";
+import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
 import { FlexLayoutHelper, HORIZONTAL_AXIS } from "../utils/flex-layout.js";
+import { stackMinIntrinsic, withDeclaredExtent } from "../layout/min-intrinsic.js";
 import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
 /**
  * Horizontal stack: the mirror of `ContainerElement` (Column). Children are laid out
@@ -14,13 +15,16 @@ import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
  * Grid/Table concern.
  */
 export class RowElement extends SizedPDFElement {
-    constructor({ children, gap, main, cross, width, height, widthFactor, heightFactor, breakBefore, breakAfter, }) {
+    constructor({ children, gap, main, cross, reverse, wrap, alignContent, width, height, breakBefore, breakAfter, ...sizing }) {
         super({ x: 0, y: 0 });
         this.children = children;
         this.gap = gap ?? 0;
         this.main = main ?? "start";
         this.cross = cross ?? "stretch";
-        this.requested = { width, height, widthFactor, heightFactor };
+        this.reverse = reverse ?? false;
+        this.wrap = wrap ?? false;
+        this.alignContent = alignContent;
+        this.requested = { ...sizing, width, height };
         this.breakBefore = breakBefore ?? false;
         this.breakAfter = breakAfter ?? false;
     }
@@ -44,29 +48,43 @@ export class RowElement extends SizedPDFElement {
         const ownFlexChild = horizontal && this.children.some((c) => c instanceof FlexiblePDFElement);
         return ownFlexChild || this.children.some((c) => c.needsBoundedMain(horizontal));
     }
+    /** A Row lays out side by side, so widths add up (gaps included) and heights overlap. */
+    minIntrinsicMain(horizontal, ctx) {
+        const content = stackMinIntrinsic(this.children, this.gap, horizontal, horizontal, ctx, this.wrap);
+        return withDeclaredExtent(content, horizontal ? this.requested.width : this.requested.height, horizontal ? this.requested.minWidth : this.requested.minHeight);
+    }
     calculateLayout(constraints, offset, ctx) {
         this.x = offset.x;
         this.y = offset.y;
         // Relative sizing: a pinned extent (fixed or a fraction of the offered box, clamped) wins; else
         // width fills the offered space (flex children split the leftover) and height is the tallest child.
-        const explicitWidth = resolveExtent(this.requested.width, this.requested.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
-        const explicitHeight = resolveExtent(this.requested.height, this.requested.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
+        const specs = extentSpecs(this.requested);
+        const resolved = resolveSize(specs.width, specs.height, this.requested.aspectRatio, constraints);
+        const { width: explicitWidth, height: explicitHeight, constraints: bounds } = resolved;
+        // Fill-or-shrink-wrap is decided by the constraints we were GIVEN; a min/max only caps the result.
         const boundedWidth = explicitWidth !== undefined
-            ? constraints.constrainWidth(explicitWidth)
+            ? bounds.constrainWidth(explicitWidth)
             : constraints.hasBoundedWidth
-                ? constraints.maxWidth
+                ? bounds.maxWidth
                 : undefined;
         const boundedHeight = explicitHeight !== undefined
-            ? constraints.constrainHeight(explicitHeight)
+            ? bounds.constrainHeight(explicitHeight)
             : constraints.hasBoundedHeight
-                ? constraints.maxHeight
+                ? bounds.maxHeight
                 : undefined;
         // Horizontal stack: main = width (children fill it), cross = height (children can stretch to it).
         const mainAvail = boundedWidth ?? Infinity;
         const crossAvail = boundedHeight ?? Infinity;
         let result = { mainUsed: 0, crossUsed: 0 };
         if (this.children.length > 0) {
-            result = FlexLayoutHelper.layout(this.children, HORIZONTAL_AXIS, mainAvail, crossAvail, this.x, this.y, { gap: this.gap, main: this.main, cross: this.cross }, ctx);
+            result = FlexLayoutHelper.layout(this.children, HORIZONTAL_AXIS, mainAvail, crossAvail, this.x, this.y, {
+                gap: this.gap,
+                main: this.main,
+                cross: this.cross,
+                reverse: this.reverse,
+                wrap: this.wrap,
+                alignContent: this.alignContent,
+            }, ctx);
         }
         this.width = boundedWidth ?? result.mainUsed;
         this.height = boundedHeight ?? result.crossUsed;
@@ -82,6 +100,9 @@ export class RowElement extends SizedPDFElement {
             gap: this.gap,
             main: this.main,
             cross: this.cross,
+            reverse: this.reverse,
+            wrap: this.wrap,
+            alignContent: this.alignContent,
         };
     }
 }

package/dist/elements/svg-element.d.ts

@@ -0,0 +1,41 @@
+import { type SvgSize } from "../svg/index.js";
+import { BoxConstraints, Offset, Size, SizingParams } from "../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "./pdf-element.js";
+/** Markup, a file path (Node only), or the file's bytes. */
+export type SvgSource = string | Uint8Array;
+interface SvgElementParams extends SizingParams {
+    source: SvgSource;
+    /** Width/height as a fraction (0..1) of the offered box, for `"50%"`. */
+    widthFactor?: number;
+    heightFactor?: number;
+    /** Alternate text for the tagged structure tree; makes the drawing a Figure rather than decoration. */
+    alt?: string;
+}
+/**
+ * An SVG drawing placed in the layout like an image.
+ *
+ * Unlike a bitmap it needs no decoder, so its intrinsic size is known SYNCHRONOUSLY, in the
+ * constructor - which also means a broken file fails on the line that asked for it rather than deep
+ * inside a later render, the same bargain `addFont` makes.
+ */
+export declare class SvgElement extends SizedPDFElement {
+    private source;
+    private intrinsic;
+    private alt?;
+    private requested;
+    private sizing;
+    private widthFactor?;
+    private heightFactor?;
+    constructor(params: SvgElementParams);
+    getProps(): {
+        x: number;
+        y: number;
+        width: number | undefined;
+        height: number | undefined;
+        source: string;
+        intrinsic: SvgSize;
+        alt: string | undefined;
+    };
+    calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+}
+export {};

package/dist/elements/svg-element.js

@@ -0,0 +1,93 @@
+import { readFileBytes } from "../platform/node-fs.js";
+import { SvgParseError, svgSize, svgToIr } from "../svg/index.js";
+import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
+import { SizedPDFElement } from "./pdf-element.js";
+/** Markup is recognised by its first non-space character - anything else is treated as a path. */
+const looksLikeMarkup = (value) => /^\s*[<]/.test(value);
+/**
+ * Reads the file, or says what went wrong in the caller's terms. A string that is neither markup nor
+ * a readable path would otherwise surface as a bare `ENOENT`, which never mentions that the argument
+ * was taken as a PATH in the first place.
+ */
+function readSource(path) {
+    try {
+        return readFileBytes(path);
+    }
+    catch (error) {
+        const shown = path.length > 80 ? `${path.slice(0, 77)}...` : path;
+        throw new SvgParseError(`could not read "${shown}" as an SVG file. It does not start with "<", so it was taken as a ` +
+            `path: ${error.message}`);
+    }
+}
+/**
+ * An SVG drawing placed in the layout like an image.
+ *
+ * Unlike a bitmap it needs no decoder, so its intrinsic size is known SYNCHRONOUSLY, in the
+ * constructor - which also means a broken file fails on the line that asked for it rather than deep
+ * inside a later render, the same bargain `addFont` makes.
+ */
+export class SvgElement extends SizedPDFElement {
+    constructor(params) {
+        super({ x: 0, y: 0, width: params.width, height: params.height });
+        const { source, alt, widthFactor, heightFactor, ...sizing } = params;
+        this.widthFactor = widthFactor;
+        this.heightFactor = heightFactor;
+        this.source =
+            typeof source === "string"
+                ? looksLikeMarkup(source)
+                    ? source
+                    : new TextDecoder().decode(readSource(source))
+                : new TextDecoder().decode(source);
+        // Parsed here on purpose: an unreadable file is an error where it was NAMED, not inside a render
+        // three call frames later. The whole document is walked, not just its root, so an element outside
+        // the subset surfaces here too - which is what makes the error predictable rather than a lottery
+        // between construction and render time. A logo parses in well under a millisecond.
+        this.intrinsic = svgSize(this.source);
+        svgToIr(this.source, { x: 0, y: 0, width: 1, height: 1 });
+        this.alt = alt;
+        this.sizing = sizing;
+        this.requested = { width: params.width, height: params.height };
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+            source: this.source,
+            intrinsic: this.intrinsic,
+            alt: this.alt,
+        };
+    }
+    calculateLayout(constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        const specs = extentSpecs({
+            ...this.sizing,
+            width: this.requested.width,
+            height: this.requested.height,
+            widthFactor: this.widthFactor,
+            heightFactor: this.heightFactor,
+        });
+        const resolved = resolveSize(specs.width, specs.height, this.sizing.aspectRatio, constraints);
+        let w = resolved.width;
+        let h = resolved.height;
+        const bounds = resolved.constraints;
+        // One pinned axis derives the other from the drawing's own ratio (CSS `width: 120; height: auto`).
+        // A bitmap needs a decode pass before it can do this; an SVG knows it from its viewBox.
+        if (this.sizing.aspectRatio === undefined &&
+            this.intrinsic.width > 0 &&
+            this.intrinsic.height > 0) {
+            const ratio = this.intrinsic.width / this.intrinsic.height;
+            if (w !== undefined && h === undefined)
+                h = bounds.constrainHeight(w / ratio);
+            else if (h !== undefined && w === undefined)
+                w = bounds.constrainWidth(h * ratio);
+        }
+        // Nothing pinned: draw at the intrinsic size, as an unsized `<img>` does - never fill the region,
+        // which would blow a 24pt icon up to the whole page.
+        this.width = w ?? bounds.constrainWidth(this.intrinsic.width);
+        this.height = h ?? bounds.constrainHeight(this.intrinsic.height);
+        return { width: this.width, height: this.height };
+    }
+}