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

package/dist/renderer/text-renderer.js

@@ -1,32 +1,44 @@
 import { Color } from "../common/color.js";
 import { HorizontalAlignment } from "../elements/pdf-element.js";
+import { VERTICAL_TEXT_SHIFT } from "../elements/text-element.js";
 import { isEmojiCodePoint } from "../text/emoji-codepoints.js";
 import { emojiImageNode } from "./emoji-image.js";
-import { wrapStringIntoLines, breakSegmentsIntoLines, } from "../text/line-breaker.js";
+import { singleLineWidth, MAX_SPACE_SHRINK, wrapStringIntoLines, breakSegmentsIntoLines, } from "../text/line-breaker.js";
 import { lineBoxForSegmentLine, lineBoxForString } from "../text/line-metrics.js";
 import { runAdvance } from "../text/advance.js";
+import { visualRuns, visualRunsOf } from "../text/bidi.js";
 import { skipInkSegments, strikethroughStroke, underlineStroke, } from "../text/text-decoration.js";
+import { quadToCubic } from "../vector/path.js";
 export class TextRenderer {
     // Measuring only needs metrics, not the full object manager. (The render pass below
     // still receives the manager because it also registers fonts/images.)
-    static calculateTextHeight(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, maxLines, overflow, lineHeight, letterSpacing = 0) {
+    static calculateTextHeight(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, maxLines, overflow, lineHeight, letterSpacing = 0, lineOptions = {}) {
         // Plain string: every wrapped line gets the same box.
         if (typeof content === "string") {
-            const lines = wrapStringIntoLines(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager, maxLines, overflow, letterSpacing);
+            const lines = wrapStringIntoLines(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager, maxLines, overflow, letterSpacing, lineOptions);
             const box = lineBoxForString(objectManager, fontFamily, fontStyle, fontSize, lineHeight);
             return lines.length * box.height;
         }
-        // Segments: each line's box comes from the fonts actually on it.
-        const defaults = { fontFamily, fontSize, fontStyle, letterSpacing };
+        // Segments: each line's box comes from the fonts actually on it. `splitting` has to travel with
+        // them for the same reason `letterSpacing` does: it changes where a line ENDS, so leaving it out
+        // measures a paragraph at one line count and draws it at another.
+        const defaults = {
+            fontFamily,
+            fontSize,
+            fontStyle,
+            letterSpacing,
+            splitting: lineOptions.splitting,
+            ligatures: lineOptions.ligatures,
+        };
         const lines = breakSegmentsIntoLines(content, defaults, maxWidth, objectManager, maxLines, overflow);
         return lines.reduce((total, line) => total + lineBoxForSegmentLine(line, defaults, objectManager, lineHeight).height, 0);
     }
     static async render(textElement, objectManager) {
-        const { x, y, width, fontSize, color, content, fontFamily, fontStyle, textAlignment, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, role, } = textElement.getProps();
+        const { x, y, width, fontSize, color, content, fontFamily, fontStyle, textAlignment, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, wordSpacing, textIndent, breakWord, hyphenate, ligatures, role, } = textElement.getProps();
         // Component -> display list. Wrapping and positioning stay here; the backend
         // turns each run into BT/Tf/Td/Tj/ET. The wrapping algorithm is unchanged from
         // the original renderer - unifying it into the engine is Phase 3.
-        const { runs, links, decorations } = TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, x, y, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing);
+        const { runs, links, decorations } = TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, x, y, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, wordSpacing, textIndent, breakWord, hyphenate, ligatures);
         // Accessible tagging: this whole text block is one structure element (a paragraph P, or a heading
         // from `role`); each run's text lands under it. Emoji sub-nodes produced below stay untagged (drawn
         // as artifacts). Keyed by structId so a block split across pages stays one element.
@@ -61,6 +73,13 @@ export class TextRenderer {
         const imageSource = om.getEmojiImageSource();
         if (!own && !fallback && !imageSource)
             return [run];
+        // A SHAPED run cannot be split here: the sub-runs are cut by code point, while `glyphs` is a
+        // drawn-order list in which a ligature is one glyph for several code points - so no sub-run could
+        // be given the right slice, and inheriting the whole list would draw every glyph again per piece.
+        // Passed through whole instead: an emoji inside Arabic then comes from the text font rather than
+        // the emoji source (`todo.md`).
+        if (run.glyphs)
+            return [run];
         const nodes = [];
         let cursorX = run.x; // absolute x of the next glyph
         let pending = ""; // run of consecutive non-color characters
@@ -152,19 +171,9 @@ export class TextRenderer {
                 out.push({ op: "l", x: curX, y: curY });
             }
             else if (cmd.type === "Q") {
-                const ctrlX = mapX(cmd.cx, cmd.cy);
-                const ctrlY = mapY(cmd.cx, cmd.cy);
                 const endX = mapX(cmd.x, cmd.y);
                 const endY = mapY(cmd.x, cmd.y);
-                out.push({
-                    op: "c",
-                    x1: curX + (2 / 3) * (ctrlX - curX),
-                    y1: curY + (2 / 3) * (ctrlY - curY),
-                    x2: endX + (2 / 3) * (ctrlX - endX),
-                    y2: endY + (2 / 3) * (ctrlY - endY),
-                    x: endX,
-                    y: endY,
-                });
+                out.push(quadToCubic(curX, curY, mapX(cmd.cx, cmd.cy), mapY(cmd.cx, cmd.cy), endX, endY));
                 curX = endX;
                 curY = endY;
             }
@@ -215,7 +224,7 @@ export class TextRenderer {
     // Lay the content out into absolutely-positioned text runs. Glyph positions match
     // the previous hand-written operators exactly (verified by pixel-identical render);
     // only the output form changed from PDF strings to `TextRun`s.
-    static _buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, textAlignment, color, initialX, yPosition, maxLines, overflow, lineHeight, underline = false, strikethrough = false, skipInk = false, letterSpacing = 0) {
+    static _buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, textAlignment, color, initialX, yPosition, maxLines, overflow, lineHeight, underline = false, strikethrough = false, skipInk = false, letterSpacing = 0, direction = "ltr", wordSpacing = 0, textIndent = 0, breakWord = false, hyphenate, ligatures = true) {
         const runs = [];
         // /Link annotation rects for any `href` spans, collected as we place segments. Empty for the
         // common (no-href) case, so plain text keeps producing exactly the runs it did before.
@@ -224,13 +233,74 @@ export class TextRenderer {
         // per line, and a decorated span only spans its own glyphs).
         const decorations = [];
         // Horizontal offset of a line of the given width under the current alignment.
-        const alignmentOffset = (lineWidth) => {
-            if (textAlignment === HorizontalAlignment.center)
-                return (maxWidth - lineWidth) / 2;
-            if (textAlignment === HorizontalAlignment.right)
-                return maxWidth - lineWidth;
+        // `start` is the one alignment that depends on the direction, resolved at the single place
+        // alignment is consumed.
+        const align = textAlignment === HorizontalAlignment.start
+            ? direction === "rtl"
+                ? HorizontalAlignment.right
+                : HorizontalAlignment.left
+            : textAlignment;
+        const alignmentOffset = (lineWidth, indent = 0) => {
+            const room = maxWidth - indent;
+            if (align === HorizontalAlignment.center)
+                return (room - lineWidth) / 2;
+            if (align === HorizontalAlignment.right)
+                return room - lineWidth;
             return 0;
         };
+        /**
+         * Justification: how much extra to put in EACH space of a line so it reaches the full width.
+         * The LAST line of a paragraph keeps its natural spacing, as it does in CSS and in print - a
+         * justified last line is the classic sign of a broken text engine.
+         *
+         * Spaces are stretched by moving the pen, not by the `Tw` operator: `Tw` applies only to the
+         * single byte 32, so an embedded (Identity-H) font would ignore it entirely.
+         */
+        const justifyExtra = (line, naturalWidth, isLast, indent = 0) => {
+            if (align !== HorizontalAlignment.justify)
+                return 0;
+            const gaps = [...line].filter((c) => c === " ").length;
+            if (gaps === 0)
+                return 0;
+            const slack = maxWidth - indent - naturalWidth;
+            // Negative slack is real now: the breaker keeps a word when the line can be SQUEEZED to hold
+            // it, so justification has to deliver that squeeze. The floor is the same limit the breaker
+            // used, which is what stops a line it never promised from being crushed.
+            const spaceWidth = runAdvance(objectManager, " ", { fontFamily, fontSize, fontStyle }, letterSpacing);
+            const extra = Math.max(slack / gaps, -spaceWidth * MAX_SPACE_SHRINK);
+            // The last line is never STRETCHED - the rule print and CSS follow. It may still be SQUEEZED:
+            // the breaker was allowed to pack it that way, and drawing it loose would push it out of its box.
+            return isLast ? Math.min(0, extra) : extra;
+        };
+        /**
+         * Push one drawn piece and return the advance it took. When the line is justified the pen jumps an
+         * extra `extra` at every space, which means one run per word - the only way that works for an
+         * embedded font, whose spaces `Tw` cannot reach.
+         *
+         * A SHAPED piece is never split: its glyph list is in drawn order with ligatures merged, so no
+         * slice of it is correct. Such a piece keeps its natural spacing.
+         */
+        const emitPiece = (piece, x, extra, style, runFont, spacing) => {
+            const push = (at, text, glyphs) => {
+                runs.push({ type: "text", x: at, text, ...(glyphs ? { glyphs } : {}), ...style });
+            };
+            if (extra === 0 || piece.glyphs || !piece.text.includes(" ")) {
+                push(x, piece.text, piece.glyphs);
+                return runAdvance(objectManager, piece.text, runFont, spacing);
+            }
+            const spaceWidth = runAdvance(objectManager, " ", runFont, spacing);
+            const words = piece.text.split(" ");
+            let pen = x;
+            words.forEach((word, i) => {
+                if (word !== "") {
+                    push(pen, word);
+                    pen += runAdvance(objectManager, word, runFont, spacing);
+                }
+                if (i < words.length - 1)
+                    pen += spaceWidth + extra;
+            });
+            return pen - x;
+        };
         // The decoration strokes for one drawn run, at the geometry ITS OWN font declares. A mixed-size
         // line therefore gets a thicker line under the bigger span, which is what a browser does too.
         const decorate = (text, runX, runWidth, baselineY, family, style, size, runColor, wantsUnderline, wantsStrikethrough, runLetterSpacing) => {
@@ -276,31 +346,62 @@ export class TextRenderer {
             const inkSpans = objectManager.getInkSpansInBand(text, size, family, style, -below + half, -below - half, runLetterSpacing);
             return skipInkSegments(runWidth, inkSpans, stroke.thickness);
         };
+        /**
+         * One drawn piece of a line. SHAPING must see the run's LOGICAL text - a letter's form comes from
+         * its neighbours, and a reversed run has those swapped - so we shape that and then reverse the
+         * GLYPHS for an rtl run. A font that does not shape keeps the old path exactly: draw the visual
+         * text, no glyph list, byte-identical output.
+         */
+        const shapedPiece = (part, family, style) => {
+            // The run's OWN setting, not the default: measuring asked with it (`runAdvance` -> RunFont), and
+            // drawing has to ask the same question or the line is measured one width and drawn another.
+            const shaped = objectManager.shapeText(part.logical, family, style, ligatures ? undefined : []);
+            if (!shaped)
+                return { text: part.text };
+            const ordered = part.rtl ? [...shaped].reverse() : shaped;
+            return { text: part.logical, glyphs: ordered.map((g) => g.glyph) };
+        };
         // The advance the viewer will use: plain glyph widths (a `Tj` never kerns) plus one
         // `letterSpacing` per code point (the `Tc` operator), from the one shared `advance.ts` primitive.
-        const font = { fontFamily, fontSize, fontStyle };
+        const font = { fontFamily, fontSize, fontStyle, ligatures };
         // --- Plain string: one run per wrapped line. ---
         if (typeof content === "string") {
-            const lines = wrapStringIntoLines(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager, maxLines, overflow, letterSpacing);
+            const lines = wrapStringIntoLines(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager, maxLines, overflow, letterSpacing, 
+            // The SAME knobs the measure pass used (`TextElement.lineOptions`), or a line would be
+            // measured one width and drawn another.
+            {
+                wordSpacing,
+                indent: textIndent,
+                shrink: align === HorizontalAlignment.justify ? MAX_SPACE_SHRINK : 0,
+                splitting: { breakWord, hyphenate },
+                ligatures,
+            });
             // yPosition is the top of the text box (top-left). The line box seats its own baseline; lines
             // then stack by that box's height. Same numbers as calculateTextHeight, by construction.
             const box = lineBoxForString(objectManager, fontFamily, fontStyle, fontSize, lineHeight);
             lines.forEach((line, index) => {
-                const lineWidth = runAdvance(objectManager, line, font, letterSpacing);
-                const x = initialX + alignmentOffset(lineWidth);
+                const lineWidth = singleLineWidth(line, font, objectManager, letterSpacing, wordSpacing);
+                // CSS `text-indent`: the FIRST line starts in, and had that much less room to fill.
+                const indent = index === 0 ? textIndent : 0;
+                let x = initialX + indent + alignmentOffset(lineWidth, indent);
                 const baseline = yPosition + box.baseline + box.height * index;
-                runs.push({
-                    type: "text",
-                    x,
-                    y: baseline,
-                    text: line,
-                    fontFamily,
-                    fontStyle,
-                    fontSize,
-                    color,
-                    ...(letterSpacing ? { letterSpacing } : {}),
-                });
-                decorate(line, x, lineWidth, baseline, fontFamily, fontStyle, fontSize, color, underline, strikethrough, letterSpacing);
+                // Latin-only text in an `ltr` paragraph comes back as one unchanged piece.
+                // Word-spacing is a per-gap advance just like the justification slack, so it rides the same
+                // mechanism: `Tw` would reach only the single byte 32 and miss every embedded font.
+                const extra = wordSpacing + justifyExtra(line, lineWidth, index === lines.length - 1, indent);
+                for (const part of visualRuns(line, direction)) {
+                    const piece = shapedPiece(part, fontFamily, fontStyle);
+                    const partWidth = emitPiece(piece, x, extra, {
+                        y: baseline,
+                        fontFamily,
+                        fontStyle,
+                        fontSize,
+                        color,
+                        ...(letterSpacing ? { letterSpacing } : {}),
+                    }, font, letterSpacing);
+                    decorate(piece.text, x, partWidth, baseline, fontFamily, fontStyle, fontSize, color, underline, strikethrough, letterSpacing);
+                    x += partWidth;
+                }
             });
             return { runs, links, decorations };
         }
@@ -309,27 +410,34 @@ export class TextRenderer {
         // the previous segment's kerning-free advance. Each line drops by its OWN leading
         // (tallest font on that line), so mixed-font lines space correctly and the drawn
         // height matches the measured height.
-        const pushLine = (line, lineY) => {
+        const pushLine = (line, lineY, isLast) => {
             let x = initialX + alignmentOffset(line.width);
-            line.segments.forEach((segment) => {
+            const extra = justifyExtra(line.segments.map((seg) => seg.content).join(""), line.width, isLast);
+            // Across span boundaries, so a Hebrew span is ordered against its neighbours rather than inside
+            // itself. Each run keeps the segment it came from, and with it that span's style.
+            const ordered = visualRunsOf(line.segments.map((segment) => ({ text: segment.content, source: segment })), direction);
+            ordered.forEach((part) => {
+                const segment = part.source;
                 const family = segment.fontFamily || fontFamily;
                 const size = segment.fontSize || fontSize;
                 const style = segment.fontStyle || fontStyle;
                 const segLetterSpacing = segment.letterSpacing ?? letterSpacing;
-                const advance = runAdvance(objectManager, segment.content, { fontFamily: family, fontSize: size, fontStyle: style }, segLetterSpacing);
+                const piece = shapedPiece(part, family, style);
+                const runText = piece.text;
                 const runColor = segment.fontColor || color;
-                runs.push({
-                    type: "text",
-                    x,
-                    y: lineY,
-                    text: segment.content,
+                // `vertical-align`: this run alone leaves the line's baseline. Its own decoration and link box
+                // ride along, since both are placed from the same y.
+                const shift = VERTICAL_TEXT_SHIFT[segment.verticalAlign ?? "baseline"] * size;
+                const runY = lineY - shift;
+                const drawn = emitPiece(piece, x, extra, {
+                    y: runY,
                     fontFamily: family,
                     fontStyle: style,
                     fontSize: size,
                     color: runColor,
                     ...(segLetterSpacing ? { letterSpacing: segLetterSpacing } : {}),
-                });
-                decorate(segment.content, x, advance, lineY, family, style, size, runColor, segment.underline ?? underline, segment.strikethrough ?? strikethrough, segLetterSpacing);
+                }, { fontFamily: family, fontSize: size, fontStyle: style }, segLetterSpacing);
+                decorate(runText, x, drawn, runY, family, style, size, runColor, segment.underline ?? underline, segment.strikethrough ?? strikethrough, segLetterSpacing);
                 // An href/to span becomes a /Link annotation over exactly this run's glyph box: from its own
                 // ascent above the baseline down to its own descender. A span wrapped across lines yields
                 // one rect per line.
@@ -338,14 +446,14 @@ export class TextRenderer {
                     links.push({
                         type: "link",
                         x,
-                        y: lineY - v.ascent * size,
-                        width: advance,
+                        y: runY - v.ascent * size,
+                        width: drawn,
                         height: (v.ascent + v.descent) * size,
                         href: segment.href,
                         dest: segment.dest,
                     });
                 }
-                x += advance;
+                x += drawn;
             });
         };
         // yPosition is the top of the text box (top-left). Each line seats its own baseline inside its
@@ -353,13 +461,24 @@ export class TextRenderer {
         // The seam flips the whole thing to PDF space. `letterSpacing` MUST be in the defaults so a span
         // that does not override it wraps and aligns with the element's spacing - the same defaults the
         // measure path (calculateTextHeight) uses, or segmented spaced text mis-wraps (measured != drawn).
-        const defaults = { fontFamily, fontSize, fontStyle, letterSpacing };
+        const defaults = {
+            fontFamily,
+            fontSize,
+            fontStyle,
+            letterSpacing,
+            splitting: { breakWord, hyphenate },
+            ligatures,
+        };
         let top = yPosition;
-        for (const line of breakSegmentsIntoLines(content, defaults, maxWidth, objectManager, maxLines, overflow)) {
+        // Materialised, because justification has to know which line is the LAST one of the paragraph.
+        const segmentLines = [
+            ...breakSegmentsIntoLines(content, defaults, maxWidth, objectManager, maxLines, overflow),
+        ];
+        segmentLines.forEach((line, index) => {
             const box = lineBoxForSegmentLine(line, defaults, objectManager, lineHeight);
-            pushLine(line, top + box.baseline);
+            pushLine(line, top + box.baseline, index === segmentLines.length - 1);
             top += box.height;
-        }
+        });
         return { runs, links, decorations };
     }
 }

package/dist/svg/css.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The `<style>` block - the third way an SVG carries style, beside presentation attributes and the
+ * `style=""` bag.
+ *
+ * It exists here because it is the case that BREAKS in practice: Illustrator's default export option
+ * is "Internal CSS", which puts every fill into a class and leaves the shapes with nothing but
+ * `class="st0"`. Dropping the block therefore does not lose a detail - it makes the whole logo black.
+ * (react-pdf drops it, with a warning; we dropped it silently until this module existed.)
+ *
+ * Only FLAT selectors are resolved - a tag, `.class`, `#id`, and compounds of those - because that is
+ * what exporters emit. A combinator or a pseudo-class is reported rather than quietly mismatched: a
+ * selector that silently fails to match is the same black logo again, one level down.
+ */
+export interface CssRule {
+    tag?: string;
+    id?: string;
+    classes: string[];
+    /** CSS specificity as one number, and the source order that breaks ties. */
+    weight: number;
+    order: number;
+    declarations: Record<string, string>;
+}
+/**
+ * Parses every `<style>` block's text into rules, in source order.
+ *
+ * The brace matching is done by hand rather than with one regex: `@media print { .a { … } }` nests,
+ * and a regex that skips to the first balanced-looking block silently applies the INNER rule while
+ * never seeing the at-rule that guards it.
+ */
+export declare function parseStylesheet(css: string): CssRule[];
+/**
+ * The declarations that apply to one element, weakest first - so a caller can just assign them in
+ * order and let the last one win, as the cascade does.
+ */
+export declare function declarationsFor(rules: readonly CssRule[], tagName: string, attributes: {
+    class?: string;
+    id?: string;
+}): Record<string, string>;

package/dist/svg/css.js

@@ -0,0 +1,115 @@
+import { SvgUnsupportedError } from "./errors.js";
+const COMMENTS = /\/\*[\s\S]*?\*\//g;
+/** One compound selector, e.g. `rect.st0#a`. Anything structural is refused, not approximated. */
+function parseSelector(selector, order) {
+    const text = selector.trim();
+    if (/[\s>+~]/.test(text)) {
+        throw new SvgUnsupportedError(`the CSS selector "${text}" (it combines elements)`, "Only flat selectors are resolved. Re-export with presentation attributes instead.");
+    }
+    if (text.includes(":") || text.includes("[")) {
+        throw new SvgUnsupportedError(`the CSS selector "${text}" (pseudo-class or attribute selector)`, "Only a tag, .class and #id are resolved. Re-export with presentation attributes instead.");
+    }
+    const classes = [...text.matchAll(/\.([\w-]+)/g)].map((m) => m[1]);
+    const id = /#([\w-]+)/.exec(text)?.[1];
+    const tag = /^[\w-]+/.exec(text)?.[0];
+    // The usual a-b-c weights, flattened: an id beats any number of classes, a class beats a tag.
+    const weight = (id ? 10000 : 0) + classes.length * 100 + (tag ? 1 : 0);
+    return { tag, id, classes, weight, order };
+}
+function parseDeclarations(body) {
+    const out = {};
+    for (const declaration of body.split(";")) {
+        const colon = declaration.indexOf(":");
+        if (colon === -1)
+            continue;
+        const property = declaration.slice(0, colon).trim();
+        // `!important` would need a second cascade level; exporters do not emit it, so it is refused
+        // rather than silently treated as a normal declaration.
+        const value = declaration.slice(colon + 1).trim();
+        if (!property)
+            continue;
+        if (/!\s*important$/i.test(value)) {
+            throw new SvgUnsupportedError(`"!important" in a <style> block`, "Remove it, or re-export with presentation attributes.");
+        }
+        out[property] = value;
+    }
+    return out;
+}
+/**
+ * Parses every `<style>` block's text into rules, in source order.
+ *
+ * The brace matching is done by hand rather than with one regex: `@media print { .a { … } }` nests,
+ * and a regex that skips to the first balanced-looking block silently applies the INNER rule while
+ * never seeing the at-rule that guards it.
+ */
+export function parseStylesheet(css) {
+    const text = css.replace(COMMENTS, "");
+    const rules = [];
+    let order = 0;
+    let i = 0;
+    while (i < text.length) {
+        const open = text.indexOf("{", i);
+        if (open === -1)
+            break;
+        // A statement at-rule (`@import "a";`) ends at its semicolon. Taking everything up to the next
+        // brace as one prelude would swallow the rule that follows it.
+        const head = text.slice(i, open);
+        const prelude = head.slice(head.lastIndexOf(";") + 1).trim();
+        let depth = 1;
+        let j = open + 1;
+        while (j < text.length && depth > 0) {
+            if (text[j] === "{")
+                depth++;
+            else if (text[j] === "}")
+                depth--;
+            j++;
+        }
+        if (prelude.startsWith("@")) {
+            // An at-rule is DROPPED, not reported - which is what CSS itself does with one it cannot
+            // evaluate, and what the corpus demanded: 68 of 10,819 real files carry a `@media
+            // (prefers-color-scheme)` or a `@keyframes` that can never apply to a static page, and
+            // refusing them meant those files did not render at all.
+            // The exception is a query that always holds for print, whose rules DO apply.
+            const [at, ...rest] = prelude.split(/\s+/);
+            // A media list applies if ANY of its components does - `@media print, screen` is for print too.
+            const applies = at === "@media" &&
+                rest
+                    .join(" ")
+                    .split(",")
+                    .some((q) => ["print", "all", ""].includes(q.trim()));
+            if (applies) {
+                // Its body is a nested stylesheet; parse it in place so the rules keep their source order.
+                for (const rule of parseStylesheet(text.slice(open + 1, j - 1))) {
+                    rules.push({ ...rule, order: order++ });
+                }
+            }
+            i = j;
+            continue;
+        }
+        const declarations = parseDeclarations(text.slice(open + 1, j - 1));
+        for (const selector of prelude.split(",")) {
+            if (selector.trim() === "")
+                continue;
+            rules.push({ ...parseSelector(selector, order++), declarations });
+        }
+        i = j;
+    }
+    return rules;
+}
+/**
+ * The declarations that apply to one element, weakest first - so a caller can just assign them in
+ * order and let the last one win, as the cascade does.
+ */
+export function declarationsFor(rules, tagName, attributes) {
+    if (rules.length === 0)
+        return {};
+    const classes = (attributes.class ?? "").trim().split(/\s+/).filter(Boolean);
+    const matched = rules.filter((rule) => (rule.tag === undefined || rule.tag === tagName) &&
+        (rule.id === undefined || rule.id === attributes.id) &&
+        rule.classes.every((name) => classes.includes(name)));
+    matched.sort((a, b) => a.weight - b.weight || a.order - b.order);
+    const out = {};
+    for (const rule of matched)
+        Object.assign(out, rule.declarations);
+    return out;
+}

package/dist/svg/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SVG is a document format, not a graphics format: it carries CSS, text layout, filters, masks and
+ * animation. Filters and masks are PIXEL operations, so no vector backend can express them - which is
+ * why every complete SVG renderer owns a rasterizer, and why every PDF library ships a subset instead.
+ *
+ * We ship a subset too. The difference is what happens at its edge: an element we cannot draw is a
+ * NAMED ERROR, never a silent skip. Two reasons, and the second is the important one.
+ *
+ * 1. A silently dropped element leaves a logo that renders and is quietly wrong - the fill missing,
+ *    the icon half there - and nobody finds out. (react-pdf skips, and its `<style>` handling loses
+ *    every fill of an Illustrator export made with the default "Internal CSS" option.)
+ * 2. It keeps every later stage a MINOR. Supporting something new turns an error into a picture, which
+ *    can never break a document that worked. Going the other way - from silently skipping to drawing -
+ *    would change existing output.
+ */
+/** An element or attribute value we deliberately do not support yet. */
+export declare class SvgUnsupportedError extends Error {
+    readonly feature: string;
+    constructor(feature: string, hint: string);
+}
+/** The file is not SVG we can read at all - malformed, or with no root `<svg>`. */
+export declare class SvgParseError extends Error {
+    constructor(message: string);
+}

package/dist/svg/errors.js

@@ -0,0 +1,30 @@
+/**
+ * SVG is a document format, not a graphics format: it carries CSS, text layout, filters, masks and
+ * animation. Filters and masks are PIXEL operations, so no vector backend can express them - which is
+ * why every complete SVG renderer owns a rasterizer, and why every PDF library ships a subset instead.
+ *
+ * We ship a subset too. The difference is what happens at its edge: an element we cannot draw is a
+ * NAMED ERROR, never a silent skip. Two reasons, and the second is the important one.
+ *
+ * 1. A silently dropped element leaves a logo that renders and is quietly wrong - the fill missing,
+ *    the icon half there - and nobody finds out. (react-pdf skips, and its `<style>` handling loses
+ *    every fill of an Illustrator export made with the default "Internal CSS" option.)
+ * 2. It keeps every later stage a MINOR. Supporting something new turns an error into a picture, which
+ *    can never break a document that worked. Going the other way - from silently skipping to drawing -
+ *    would change existing output.
+ */
+/** An element or attribute value we deliberately do not support yet. */
+export class SvgUnsupportedError extends Error {
+    constructor(feature, hint) {
+        super(`@jasy/pdf: ${feature} is not supported yet. ${hint}`);
+        this.feature = feature;
+        this.name = "SvgUnsupportedError";
+    }
+}
+/** The file is not SVG we can read at all - malformed, or with no root `<svg>`. */
+export class SvgParseError extends Error {
+    constructor(message) {
+        super(`@jasy/pdf: ${message}`);
+        this.name = "SvgParseError";
+    }
+}

package/dist/svg/gradients.d.ts

@@ -0,0 +1,34 @@
+import type { Gradient, GradientStop, PathCommand } from "../ir/display-list.js";
+import { type Attributes } from "./style.js";
+import type { XmlNode } from "./xml.js";
+/**
+ * `<linearGradient>` and `<radialGradient>`.
+ *
+ * The backend has painted shadings since colour emoji, and `Box({ bg: linearGradient(...) })` uses
+ * the same node - so this file only has to turn a `url(#id)` reference into that node. Two things
+ * make it more than a lookup:
+ *
+ * - **`gradientUnits` defaults to `objectBoundingBox`**, i.e. the coordinates are fractions of the
+ *   SHAPE's bounding box, not of the page. So a gradient cannot be resolved where it is defined,
+ *   only where it is used - which is why this takes the shape's commands.
+ * - **`href` chains.** Illustrator emits one gradient with the stops and a second that references it
+ *   and only moves the coordinates. Missing that leaves a shape with no stops at all.
+ */
+export interface GradientDef {
+    kind: "linear" | "radial";
+    attributes: Attributes;
+    stops: GradientStop[];
+    /** The `stop-opacity` of each stop, in the same order. */
+    opacities: number[];
+    /** The id this definition inherits from (`href` / `xlink:href`), without the `#`. */
+    href?: string;
+}
+/** Every gradient definition in the document, by id - they are referenced, not drawn in place. */
+export declare function gradientsOf(node: XmlNode, into?: Map<string, GradientDef>, depth?: number): Map<string, GradientDef>;
+/**
+ * Resolves a reference into an IR gradient positioned on `commands`.
+ *
+ * The anchors are mapped into the shape's own space, then through `gradientTransform` - so they end
+ * up in the SAME coordinates as the path, which is what the backend and the Y-flip both assume.
+ */
+export declare function resolveSvgGradient(def: GradientDef, defs: ReadonlyMap<string, GradientDef>, commands: readonly PathCommand[]): Gradient;