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

package/dist/svg/shapes.js

@@ -0,0 +1,177 @@
+import svgpath from "svgpath";
+import { quadToCubic } from "../vector/path.js";
+import { SvgParseError } from "./errors.js";
+import { length } from "./units.js";
+/**
+ * Every drawable SVG shape becomes one list of path commands, so the rest of the pipeline knows about
+ * exactly one kind of geometry. A rect is a path, a circle is four arcs, `<path>` is a path already.
+ *
+ * The `d` grammar - relative coordinates, the `S`/`T` shorthands, and elliptical arcs - is handled by
+ * `svgpath`: `.abs().unshort().unarc()` leaves only M/L/H/V/C/Q/Z. Arcs are the reason: converting one
+ * to Béziers is the SVG spec's own appendix, and a subtly wrong version looks ALMOST right.
+ */
+const num = (attributes, name, fallback = 0) => length(attributes[name], `the "${name}" attribute`, fallback);
+/** Four cubic arcs approximating a full ellipse. The constant is the standard circle-to-Bézier one. */
+const KAPPA = 0.5522847498307936;
+function ellipse(cx, cy, rx, ry) {
+    if (rx <= 0 || ry <= 0)
+        return [];
+    const [ox, oy] = [rx * KAPPA, ry * KAPPA];
+    return [
+        { op: "m", x: cx - rx, y: cy },
+        { op: "c", x1: cx - rx, y1: cy - oy, x2: cx - ox, y2: cy - ry, x: cx, y: cy - ry },
+        { op: "c", x1: cx + ox, y1: cy - ry, x2: cx + rx, y2: cy - oy, x: cx + rx, y: cy },
+        { op: "c", x1: cx + rx, y1: cy + oy, x2: cx + ox, y2: cy + ry, x: cx, y: cy + ry },
+        { op: "c", x1: cx - ox, y1: cy + ry, x2: cx - rx, y2: cy + oy, x: cx - rx, y: cy },
+        { op: "z" },
+    ];
+}
+function rect(attributes) {
+    const [x, y] = [num(attributes, "x"), num(attributes, "y")];
+    const [w, h] = [num(attributes, "width"), num(attributes, "height")];
+    if (w <= 0 || h <= 0)
+        return [];
+    // An `rx` alone implies the same `ry`, and vice versa; both clamp to half the side.
+    const rxRaw = attributes["rx"] !== undefined ? num(attributes, "rx") : num(attributes, "ry");
+    const ryRaw = attributes["ry"] !== undefined ? num(attributes, "ry") : rxRaw;
+    const rx = Math.min(rxRaw, w / 2);
+    const ry = Math.min(ryRaw, h / 2);
+    if (rx <= 0 || ry <= 0) {
+        return [
+            { op: "m", x, y },
+            { op: "l", x: x + w, y },
+            { op: "l", x: x + w, y: y + h },
+            { op: "l", x, y: y + h },
+            { op: "z" },
+        ];
+    }
+    const [ox, oy] = [rx * KAPPA, ry * KAPPA];
+    return [
+        { op: "m", x: x + rx, y },
+        { op: "l", x: x + w - rx, y },
+        { op: "c", x1: x + w - rx + ox, y1: y, x2: x + w, y2: y + ry - oy, x: x + w, y: y + ry },
+        { op: "l", x: x + w, y: y + h - ry },
+        {
+            op: "c",
+            x1: x + w,
+            y1: y + h - ry + oy,
+            x2: x + w - rx + ox,
+            y2: y + h,
+            x: x + w - rx,
+            y: y + h,
+        },
+        { op: "l", x: x + rx, y: y + h },
+        { op: "c", x1: x + rx - ox, y1: y + h, x2: x, y2: y + h - ry + oy, x, y: y + h - ry },
+        { op: "l", x, y: y + ry },
+        { op: "c", x1: x, y1: y + ry - oy, x2: x + rx - ox, y2: y, x: x + rx, y },
+        { op: "z" },
+    ];
+}
+function points(value) {
+    const found = String(value ?? "").match(/[+-]?(?:\d*\.\d+|\d+\.?)(?:[eE][+-]?\d+)?/g);
+    const out = [];
+    for (let i = 0; found && i + 1 < found.length; i += 2) {
+        out.push([Number(found[i]), Number(found[i + 1])]);
+    }
+    return out;
+}
+function polyline(value, close) {
+    const list = points(value);
+    if (list.length === 0)
+        return [];
+    const out = [{ op: "m", x: list[0][0], y: list[0][1] }];
+    for (const [x, y] of list.slice(1))
+        out.push({ op: "l", x, y });
+    if (close)
+        out.push({ op: "z" });
+    return out;
+}
+/** `d` through svgpath, then the remaining segment kinds mapped onto the IR's m/l/c/z. */
+export function pathData(d) {
+    const out = [];
+    let [cx, cy] = [0, 0];
+    let [startX, startY] = [0, 0];
+    try {
+        const parsed = svgpath(d);
+        // svgpath REPORTS a malformed `d` on the instance instead of throwing, so an unchecked call
+        // quietly yields an empty path - the shape simply disappears.
+        // Its bundled types omit `err`, though it IS the API: svgpath never throws on malformed input,
+        // it records the reason and yields no segments - so the shape would just disappear.
+        const err = parsed.err;
+        if (err)
+            throw new SvgParseError(`path data could not be read: ${err}`);
+        parsed
+            .abs()
+            .unshort()
+            .unarc()
+            .iterate((segment) => {
+            const [op, ...a] = segment;
+            switch (op) {
+                case "M":
+                    [cx, cy] = [a[0], a[1]];
+                    [startX, startY] = [cx, cy];
+                    out.push({ op: "m", x: cx, y: cy });
+                    break;
+                case "L":
+                    [cx, cy] = [a[0], a[1]];
+                    out.push({ op: "l", x: cx, y: cy });
+                    break;
+                case "H":
+                    cx = a[0];
+                    out.push({ op: "l", x: cx, y: cy });
+                    break;
+                case "V":
+                    cy = a[0];
+                    out.push({ op: "l", x: cx, y: cy });
+                    break;
+                case "C":
+                    out.push({ op: "c", x1: a[0], y1: a[1], x2: a[2], y2: a[3], x: a[4], y: a[5] });
+                    [cx, cy] = [a[4], a[5]];
+                    break;
+                case "Q":
+                    // PDF has no quadratic operator; the same conversion a TrueType outline needs.
+                    out.push(quadToCubic(cx, cy, a[0], a[1], a[2], a[3]));
+                    [cx, cy] = [a[2], a[3]];
+                    break;
+                case "Z":
+                    out.push({ op: "z" });
+                    [cx, cy] = [startX, startY];
+                    break;
+                default:
+                    throw new SvgParseError(`path data: unexpected segment "${op}"`);
+            }
+        });
+    }
+    catch (error) {
+        if (error instanceof SvgParseError)
+            throw error;
+        throw new SvgParseError(`path data could not be read: ${error.message}`);
+    }
+    return out;
+}
+/** The geometry of one shape element, or null if the tag is not a shape. */
+export function shapeOf(tagName, attributes) {
+    switch (tagName) {
+        case "path":
+            return attributes["d"] ? pathData(String(attributes["d"])) : [];
+        case "rect":
+            return rect(attributes);
+        case "circle": {
+            const r = num(attributes, "r");
+            return ellipse(num(attributes, "cx"), num(attributes, "cy"), r, r);
+        }
+        case "ellipse":
+            return ellipse(num(attributes, "cx"), num(attributes, "cy"), num(attributes, "rx"), num(attributes, "ry"));
+        case "line":
+            return [
+                { op: "m", x: num(attributes, "x1"), y: num(attributes, "y1") },
+                { op: "l", x: num(attributes, "x2"), y: num(attributes, "y2") },
+            ];
+        case "polyline":
+            return polyline(attributes["points"], false);
+        case "polygon":
+            return polyline(attributes["points"], true);
+        default:
+            return null;
+    }
+}

package/dist/svg/style.d.ts

@@ -0,0 +1,61 @@
+import { Color } from "../common/color.js";
+import type { StrokeStyle } from "../ir/display-list.js";
+/**
+ * The presentation style of one element, resolved against its parent's.
+ *
+ * SVG styles two ways at once: presentation ATTRIBUTES (`fill="red"`) and a CSS `style=""` bag, with
+ * the style bag winning. Most of them INHERIT, which is what lets a logo set `fill` once on the root
+ * `<g>`. A `<style>` block with class selectors is a third way and is not resolved yet - it is a
+ * NAMED error, not a silent loss, because that is exactly the case that leaves a logo blank.
+ */
+/** A paint is a colour, or a `url(#id)` reference that only the SHAPE can resolve - a gradient in
+ *  the default `objectBoundingBox` units is positioned on the bounding box of the thing it fills. */
+export type PaintRef = {
+    ref: string;
+};
+export type SvgPaint = Color | PaintRef;
+export declare const isPaintRef: (paint: SvgPaint | undefined) => paint is PaintRef;
+export interface SvgStyle {
+    /** Absent = `fill="none"`. The RAW paint - see `paintAlpha` for why the opacity is not in it. */
+    fill?: SvgPaint;
+    fillRule: "nonzero" | "evenodd";
+    stroke?: StrokeStyle;
+    /** `currentColor` resolves to this; set by the `color` attribute, black at the root. */
+    color: Color;
+    /**
+     * `fill-opacity` / `stroke-opacity` (both inherit) and the accumulated `opacity` of this element
+     * and its ancestors. They are kept OUT of the colours and applied once, at the leaf that paints:
+     * folding them in at every level would multiply a group's opacity in again for each generation.
+     */
+    fillOpacity: number;
+    strokeOpacity: number;
+    opacity: number;
+}
+/** The colour a shape actually paints with: its raw colour, times the opacities that reached it. */
+export declare function paintAlpha(color: Color, opacity: number): Color;
+export declare const ROOT_STYLE: SvgStyle;
+/** Raw attributes, exactly as written. Our own XML reader never coerces them (`svg-parser` did,
+ *  turning `id="58310095e0"` into a number). */
+export type Attributes = Record<string, string | undefined>;
+/**
+ * Reads a property from all three sources, in CSS order: a presentation attribute is the weakest, a
+ * matching `<style>` rule beats it, and the inline `style=""` bag beats both.
+ *
+ * Exported because anything that INSPECTS a property has to see the same value the style resolver
+ * would - `filter="url(#f)"` and `style="filter:url(#f)"` are the same instruction, and checking only
+ * the attribute lets the second one through unnoticed.
+ */
+export declare function cascadedReader(attributes: Attributes, css?: Record<string, string>): (name: string) => string | undefined;
+/**
+ * A colour, with the value quoted in the message. `toColor` throws a bare `Unknown color: "x"`, which
+ * inside a 900-element logo says nothing about WHERE - and a malformed file reaches here with pieces
+ * of its own markup as the value, so the raw error is actively misleading.
+ */
+export declare function svgColor(value: string): Color;
+/**
+ * Resolves one element's style against its parent's. Everything SVG inherits is inherited; `opacity`
+ * is the exception - it applies to the element itself, so it is MULTIPLIED down and folded into the
+ * paint of each leaf. That differs from a browser for a `<g opacity>` whose children OVERLAP (a real
+ * group needs one transparency group), and is the one approximation in this file.
+ */
+export declare function resolveStyle(parent: SvgStyle, attributes: Attributes, css?: Record<string, string>): SvgStyle;

package/dist/svg/style.js

@@ -0,0 +1,144 @@
+import { Color } from "../common/color.js";
+import { toColor } from "../api/color.js";
+import { SvgParseError, SvgUnsupportedError } from "./errors.js";
+import { length, ratio } from "./units.js";
+export const isPaintRef = (paint) => paint !== undefined && !(paint instanceof Color);
+/** The colour a shape actually paints with: its raw colour, times the opacities that reached it. */
+export function paintAlpha(color, opacity) {
+    if (opacity >= 1)
+        return color;
+    const [r, g, b] = color.toArray();
+    return new Color(r, g, b, color.getAlpha() * opacity);
+}
+export const ROOT_STYLE = {
+    fill: new Color(0, 0, 0),
+    fillRule: "nonzero",
+    stroke: undefined,
+    color: new Color(0, 0, 0),
+    fillOpacity: 1,
+    strokeOpacity: 1,
+    opacity: 1,
+};
+/** Splits a `style=""` bag into declarations. It wins over both other sources, as in CSS. */
+function styleBag(value) {
+    if (typeof value !== "string")
+        return {};
+    const out = {};
+    for (const declaration of value.split(";")) {
+        const colon = declaration.indexOf(":");
+        if (colon === -1)
+            continue;
+        const property = declaration.slice(0, colon).trim();
+        if (property)
+            out[property] = declaration.slice(colon + 1).trim();
+    }
+    return out;
+}
+/**
+ * Reads a property from all three sources, in CSS order: a presentation attribute is the weakest, a
+ * matching `<style>` rule beats it, and the inline `style=""` bag beats both.
+ *
+ * Exported because anything that INSPECTS a property has to see the same value the style resolver
+ * would - `filter="url(#f)"` and `style="filter:url(#f)"` are the same instruction, and checking only
+ * the attribute lets the second one through unnoticed.
+ */
+export function cascadedReader(attributes, css = {}) {
+    const bag = styleBag(attributes["style"]);
+    return (name) => {
+        const value = bag[name] ?? css[name] ?? attributes[name];
+        return value === undefined ? undefined : String(value);
+    };
+}
+const dashNumbers = (list) => {
+    const found = list.match(/[+-]?(?:\d*\.\d+|\d+\.?)(?:[eE][+-]?\d+)?/g);
+    return found ? found.map(Number) : [];
+};
+/**
+ * A paint value. `none` is the absence of paint, which is NOT the same as transparent black - a shape
+ * with `fill="none"` and a stroke draws its outline only. A `url(#...)` reference means a gradient or
+ * pattern, which we do not resolve yet and therefore name.
+ */
+function paint(value, current) {
+    const v = value.trim();
+    if (v === "none")
+        return undefined;
+    if (v === "currentColor")
+        return current;
+    const reference = /^url\(\s*#([^)\s]+)\s*\)/.exec(v);
+    // A paint reference may name a fallback after it (`url(#g) red`), which is what a renderer uses
+    // when the reference is broken - so it is kept as the reference, and resolution decides.
+    if (reference)
+        return { ref: reference[1] };
+    if (v.startsWith("url(")) {
+        throw new SvgUnsupportedError(`the paint "${v}"`, "Only a `url(#id)` reference to a gradient is resolved.");
+    }
+    return svgColor(v);
+}
+/**
+ * A colour, with the value quoted in the message. `toColor` throws a bare `Unknown color: "x"`, which
+ * inside a 900-element logo says nothing about WHERE - and a malformed file reaches here with pieces
+ * of its own markup as the value, so the raw error is actively misleading.
+ */
+export function svgColor(value) {
+    try {
+        return toColor(value);
+    }
+    catch {
+        throw new SvgParseError(`"${value}" is not a colour this SVG can use - expected a name, #hex, rgb() or hsl().`);
+    }
+}
+/**
+ * Resolves one element's style against its parent's. Everything SVG inherits is inherited; `opacity`
+ * is the exception - it applies to the element itself, so it is MULTIPLIED down and folded into the
+ * paint of each leaf. That differs from a browser for a `<g opacity>` whose children OVERLAP (a real
+ * group needs one transparency group), and is the one approximation in this file.
+ */
+export function resolveStyle(parent, attributes, css = {}) {
+    const read = cascadedReader(attributes, css);
+    const color = read("color") !== undefined ? svgColor(read("color")) : parent.color;
+    // `Number("50%")` is NaN and `Number("")` is 0, both of which travel silently into the paint.
+    const opacity = parent.opacity * ratio(read("opacity"));
+    const fillValue = read("fill");
+    const strokeValue = read("stroke");
+    const dashValue = read("stroke-dasharray");
+    const strokePaint = strokeValue !== undefined ? paint(strokeValue, color) : parent.stroke?.color;
+    if (isPaintRef(strokePaint)) {
+        // PDF strokes with a colour, never with a shading; painting the outline solid would be a colour
+        // the file did not name.
+        throw new SvgUnsupportedError("a gradient on a stroke", "PDF strokes with a colour only. Use a solid stroke, or convert the outline to a filled shape.");
+    }
+    const parts = {
+        color: strokePaint,
+        width: length(read("stroke-width"), 'the "stroke-width" attribute', parent.stroke?.width ?? 1),
+        cap: read("stroke-linecap") ?? parent.stroke?.cap,
+        join: read("stroke-linejoin") ?? parent.stroke?.join,
+        miterLimit: length(read("stroke-miterlimit"), 'the "stroke-miterlimit" attribute', parent.stroke?.miterLimit ?? 4),
+        dash: dashValue !== undefined
+            ? dashValue.trim() === "none"
+                ? undefined
+                : dashNumbers(dashValue)
+            : parent.stroke?.dash,
+        dashOffset: length(read("stroke-dashoffset"), 'the "stroke-dashoffset" attribute', parent.stroke?.dashOffset ?? 0),
+    };
+    return {
+        fill: fillValue !== undefined ? paint(fillValue, color) : parent.fill,
+        fillRule: read("fill-rule") ?? parent.fillRule,
+        // A stroke with no colour or no width paints nothing; dropping it here keeps every consumer from
+        // having to ask twice.
+        stroke: parts.color && parts.width > 0
+            ? {
+                color: parts.color,
+                width: parts.width,
+                cap: parts.cap,
+                join: parts.join,
+                miterLimit: parts.miterLimit,
+                dash: parts.dash,
+                dashOffset: parts.dashOffset,
+            }
+            : undefined,
+        color,
+        fillOpacity: ratio(read("fill-opacity"), parent.fillOpacity),
+        strokeOpacity: ratio(read("stroke-opacity"), parent.strokeOpacity),
+        opacity,
+    };
+}

package/dist/svg/transform.d.ts

@@ -0,0 +1,13 @@
+import type { Affine } from "../utils/ttf-parser.js";
+/**
+ * The `transform` attribute. SVG's `matrix(a b c d e f)` is exactly the PDF `cm` operand and exactly
+ * our IR's `TransformPush.matrix`, both read in a top-left, y-down space - so a transform maps across
+ * with no sign flips. That is also why we keep transforms in the graphics state instead of baking them
+ * into the coordinates: a stroke inside a scaled group scales WITH it, which is what SVG specifies.
+ */
+export declare const IDENTITY: Affine;
+/** `a` then `b` - the matrix that applies `b` in the space `a` established. */
+export declare function multiply(a: Affine, b: Affine): Affine;
+export declare const isIdentity: (m: Affine) => boolean;
+/** Parses a whole `transform` attribute; several functions compose left to right, as in SVG. */
+export declare function parseTransform(value: string): Affine;

package/dist/svg/transform.js

@@ -0,0 +1,68 @@
+import { SvgParseError } from "./errors.js";
+/**
+ * The `transform` attribute. SVG's `matrix(a b c d e f)` is exactly the PDF `cm` operand and exactly
+ * our IR's `TransformPush.matrix`, both read in a top-left, y-down space - so a transform maps across
+ * with no sign flips. That is also why we keep transforms in the graphics state instead of baking them
+ * into the coordinates: a stroke inside a scaled group scales WITH it, which is what SVG specifies.
+ */
+export const IDENTITY = [1, 0, 0, 1, 0, 0];
+/** `a` then `b` - the matrix that applies `b` in the space `a` established. */
+export function multiply(a, b) {
+    return [
+        a[0] * b[0] + a[2] * b[1],
+        a[1] * b[0] + a[3] * b[1],
+        a[0] * b[2] + a[2] * b[3],
+        a[1] * b[2] + a[3] * b[3],
+        a[0] * b[4] + a[2] * b[5] + a[4],
+        a[1] * b[4] + a[3] * b[5] + a[5],
+    ];
+}
+export const isIdentity = (m) => m.every((n, i) => n === IDENTITY[i]);
+const TRANSFORM = /([a-zA-Z]+)\s*\(([^)]*)\)/g;
+const radians = (deg) => (deg * Math.PI) / 180;
+/** Numbers in an SVG list: separated by commas, whitespace, or nothing at all before a minus sign. */
+function numbers(list) {
+    const found = list.match(/[+-]?(?:\d*\.\d+|\d+\.?)(?:[eE][+-]?\d+)?/g);
+    return found ? found.map(Number) : [];
+}
+/** Parses a whole `transform` attribute; several functions compose left to right, as in SVG. */
+export function parseTransform(value) {
+    let out = IDENTITY;
+    TRANSFORM.lastIndex = 0;
+    let match;
+    while ((match = TRANSFORM.exec(value)) !== null) {
+        out = multiply(out, single(match[1], numbers(match[2])));
+    }
+    return out;
+}
+function single(name, a) {
+    switch (name) {
+        case "matrix":
+            if (a.length < 6)
+                throw new SvgParseError(`transform: matrix() needs six numbers`);
+            return [a[0], a[1], a[2], a[3], a[4], a[5]];
+        case "translate":
+            return [1, 0, 0, 1, a[0] ?? 0, a[1] ?? 0];
+        case "scale": {
+            const sx = a[0] ?? 1;
+            // One number scales both axes - the SVG rule, and a common source of squashed logos if missed.
+            return [sx, 0, 0, a[1] ?? sx, 0, 0];
+        }
+        case "rotate": {
+            const t = radians(a[0] ?? 0);
+            const [cos, sin] = [Math.cos(t), Math.sin(t)];
+            const r = [cos, sin, -sin, cos, 0, 0];
+            if (a.length < 3)
+                return r;
+            // rotate(angle cx cy) = translate(cx,cy) rotate(angle) translate(-cx,-cy).
+            const [cx, cy] = [a[1], a[2]];
+            return multiply(multiply([1, 0, 0, 1, cx, cy], r), [1, 0, 0, 1, -cx, -cy]);
+        }
+        case "skewX":
+            return [1, 0, Math.tan(radians(a[0] ?? 0)), 1, 0, 0];
+        case "skewY":
+            return [1, Math.tan(radians(a[0] ?? 0)), 0, 1, 0, 0];
+        default:
+            throw new SvgParseError(`transform: unknown function "${name}()"`);
+    }
+}

package/dist/svg/units.d.ts

@@ -0,0 +1,11 @@
+/** A plain number, with nothing else in the string. */
+export declare function strictNumber(text: string): number | undefined;
+/**
+ * A length in user units. `undefined` and `""` mean "not given" and return `fallback`; a resolvable
+ * absolute unit is converted; a relative one (`%`, `em`, `rem`, `ex`, `ch`, `vw`, …) is NAMED,
+ * because resolving it needs a font or a viewport that a shape attribute does not carry.
+ */
+export declare function length(value: string | undefined, where: string, fallback?: number): number;
+/** A 0..1 ratio, written as a number or a percentage, clamped - an opacity outside the range is a
+ *  malformed file, and CSS clamps rather than rejecting. */
+export declare function ratio(value: string | undefined, fallback?: number): number;

package/dist/svg/units.js

@@ -0,0 +1,73 @@
+import { SvgUnsupportedError } from "./errors.js";
+/**
+ * Reading NUMBERS out of an SVG.
+ *
+ * `Number.parseFloat` is the wrong tool on its own: it stops at the first character it cannot use and
+ * returns what it had, so `"10px"` is 10 and `"20abc"` is 20. That is convenient exactly once and
+ * wrong everywhere else - a length we silently misread draws a shape the file did not describe.
+ *
+ * So the rules here are explicit: a plain number is a number, `px` is the user unit and means the
+ * same thing, a percentage is only valid where a ratio is expected, and anything else is NAMED. In
+ * 10,819 real files, 53 use `px` on a shape attribute (we drew nothing for them) and one uses a
+ * percentage opacity.
+ */
+/** Absolute CSS units are defined against the user unit, which SVG pins to 1/96 inch. */
+const ABSOLUTE = {
+    px: 1,
+    pt: 96 / 72,
+    pc: 16,
+    in: 96,
+    cm: 96 / 2.54,
+    mm: 96 / 25.4,
+    q: 96 / 101.6,
+};
+const NUMBER = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+const WITH_UNIT = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)\s*([a-zA-Z%]+)$/;
+/** A plain number, with nothing else in the string. */
+export function strictNumber(text) {
+    const t = text.trim();
+    if (!NUMBER.test(t))
+        return undefined;
+    const n = Number(t);
+    // `1e400` matches the grammar and overflows to Infinity. A non-finite number reaches the content
+    // stream as the literal text `Infinity`, which viewers discard the rest of the page over.
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * A length in user units. `undefined` and `""` mean "not given" and return `fallback`; a resolvable
+ * absolute unit is converted; a relative one (`%`, `em`, `rem`, `ex`, `ch`, `vw`, …) is NAMED,
+ * because resolving it needs a font or a viewport that a shape attribute does not carry.
+ */
+export function length(value, where, fallback = 0) {
+    if (value === undefined || value.trim() === "")
+        return fallback;
+    const plain = strictNumber(value);
+    if (plain !== undefined)
+        return plain;
+    const parts = WITH_UNIT.exec(value.trim());
+    if (parts) {
+        const factor = ABSOLUTE[parts[2].toLowerCase()];
+        if (factor !== undefined) {
+            // The conversion itself can overflow (`1e308in`), and a non-finite number reaches the content
+            // stream as the literal text `Infinity`.
+            const converted = Number(parts[1]) * factor;
+            return Number.isFinite(converted) ? converted : fallback;
+        }
+        throw new SvgUnsupportedError(`the length "${value.trim()}" on ${where}`, "Only absolute units (px, pt, pc, in, cm, mm, q) and plain numbers are resolved.");
+    }
+    // Not a number at all: the file is malformed here. Treat it as absent rather than as zero-with-a-
+    // shrug, so a caller sees the same thing as for a missing attribute.
+    return fallback;
+}
+/** A 0..1 ratio, written as a number or a percentage, clamped - an opacity outside the range is a
+ *  malformed file, and CSS clamps rather than rejecting. */
+export function ratio(value, fallback = 1) {
+    if (value === undefined || value.trim() === "")
+        return fallback;
+    const t = value.trim();
+    const raw = t.endsWith("%") ? strictNumber(t.slice(0, -1)) : strictNumber(t);
+    if (raw === undefined)
+        return fallback;
+    const scaled = t.endsWith("%") ? raw / 100 : raw;
+    return Math.max(0, Math.min(1, scaled));
+}

package/dist/svg/xml.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A minimal XML reader for SVG.
+ *
+ * We used `svg-parser` first. It COERCES an attribute that looks numeric, so `id="58310095e0"` came
+ * back as the number 58310095 and `id="1e999"` as Infinity - the original string simply gone. That
+ * breaks the one thing it is needed for, resolving `url(#id)` references, and no amount of care on
+ * our side can undo it. An XML attribute is a string; this reader treats it as one.
+ *
+ * The scope is what SVG actually needs: elements, attributes, text, CDATA, comments, the XML
+ * declaration and a doctype. No entity expansion beyond the five predefined ones plus numeric
+ * references, no DTD processing, no namespace resolution (the caller strips prefixes itself).
+ */
+export interface XmlElement {
+    type: "element";
+    tagName: string;
+    attributes: Record<string, string>;
+    children: XmlNode[];
+}
+export interface XmlText {
+    type: "text";
+    value: string;
+}
+export type XmlNode = XmlElement | XmlText;
+export declare function parseXml(source: string): XmlElement[];