@jasy/pdf 1.0.0-alpha.4 → 1.0.0-alpha.5

package/README.md

@@ -117,8 +117,8 @@ const pdf = await renderToBytes(
 ```
 
 Real text layout (Adobe AFM metrics, kerning, word-wrap), flexbox-style `gap` / `justify` / `align`,
-boxes with radius and alpha, images, custom TrueType fonts, and **real pagination** - content that
-overflows flows onto the next page, headers and footers repeat.
+boxes with radius and alpha, images, custom TrueType fonts, **AES-256 password encryption**, and **real
+pagination** - content that overflows flows onto the next page, headers and footers repeat.
 
 ---
 
@@ -132,6 +132,9 @@ verify all of it:
   740 KB font ships as a ~76 KB subset, and the text stays copy- and searchable.
 - **Compression.** Content streams and images are FlateDecode-compressed; the spreadsheets `jasy export`
   writes are real `.xlsx` ZIPs we deflate with our own writer and CRC32, zero dependencies.
+- **AES-256 encryption, pure JS.** Lock a PDF with `renderToBytes(doc, { encrypt: { userPassword } })` - the
+  newest standard handler (AES-256, R6 / ISO 32000-2) via the platform WebCrypto: no native crypto, no deps,
+  the same code in Node **and** the browser. Owner password + permissions optional.
 - **Real font metrics.** Text is laid out with the Adobe AFM metrics of the standard-14 fonts - kerning
   and word-wrap are _computed_, not guessed.
 - **PDF/A-3, matched not approximated.** The conformance graph is hand-built and **passes veraPDF**, the

package/dist/api/content.d.ts

@@ -28,6 +28,9 @@ export interface ImageOptions {
     fit?: ImageFit;
     /** Corner radius in points (rounds the image box). */
     radius?: number;
+    /** Alternate text for accessibility (tagged PDF): describes the image for screen readers. With `alt`
+     *  the image is a `Figure`; without it (and when rendered `accessible`) it counts as decoration. */
+    alt?: string;
 }
 /**
  * An image. `src` is a local file path (wrapped in a `CustomLocalImage`) or a ready

package/dist/api/content.js

@@ -45,5 +45,6 @@ export function Image(src, opts = {}) {
         height: opts.height,
         fit: opts.fit ? FIT[opts.fit] : undefined,
         radius: opts.radius,
+        alt: opts.alt,
     });
 }

package/dist/api/structure.d.ts

@@ -39,12 +39,25 @@ export declare function Page(children: PDFElement[]): PageElement;
 export declare function Page(opts: PageOptions, children: PDFElement[]): PageElement;
 /** Document options: PDF metadata plus the inheritable text defaults (font, size, color, lineHeight,
  *  align, bold/italic) every `Text` inherits unless it sets its own - Flutter's `DefaultTextStyle`. */
+/** Where color emoji come from when a code point isn't in the current text font, so `Text("Hi 😅")`
+ *  works in one string. Either a **font** (native vector, offline - recommended; register it in
+ *  `fonts`) as a string name or `{ font }`, or an **image/CDN source** `{ url, format }` (react-pdf
+ *  style: fetches `${url}${hexCodePoint}.${format}`, e.g. a Twemoji CDN). The font source is better
+ *  (vector, no network); the image source exists for parity + as an escape hatch. */
+export type EmojiSource = string | {
+    font: string;
+} | {
+    url: string;
+    format?: "png";
+};
 export interface DocumentOptions extends TextDefaults {
     /** PDF metadata. */
     meta?: {
         title?: string;
         author?: string;
     };
+    /** Color-emoji fallback: emoji code points not in the text font render from this source. */
+    emoji?: EmojiSource;
 }
 /** A single font file for `addFont`: a `.ttf` path (read on Node) or its raw bytes (e.g. a browser
  *  upload). */
@@ -125,6 +138,12 @@ export interface RenderOptions {
     /** Encrypt the PDF with a password (AES-256, the newest standard). NOT compatible with PDF/A
      *  (ZUGFeRD invoices) - encrypting one throws, since PDF/A forbids encryption. */
     encrypt?: EncryptOptions;
+    /** Emit an accessible, tagged PDF (structure tree for screen readers). */
+    accessible?: boolean;
+    /** Document language for accessibility, e.g. `"en-US"` / `"de-DE"` (default `"en-US"`). */
+    lang?: string;
+    /** Document title (used by accessible readers; also good metadata). */
+    title?: string;
 }
 /** Renders a `Document(...)` tree to the raw PDF string. */
 export declare function renderPdf(doc: PDFDocumentElement, options?: RenderOptions): Promise<string>;

package/dist/api/structure.js

@@ -8,6 +8,7 @@ import { PDFDocument } from "../renderer/pdf-document-class.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
 import { getArrayBuffer } from "../utils/utf8-to-windows1252-encoder.js";
 import { createSecurityHandler } from "../crypto/security-handler.js";
+import { uaXmp } from "../utils/ua-xmp.js";
 import { Column } from "./layout.js";
 import { toEdges } from "./insets.js";
 import { toTextStyleOverride } from "./text.js";
@@ -56,6 +57,8 @@ const docMeta = new WeakMap();
 // Fonts registered via doc.addFont(...), kept beside the element (like meta) and registered on the
 // object manager at render time. Path sources are read to bytes in addFont, so the map holds bytes.
 const docFonts = new WeakMap();
+// The document's color-emoji fallback source, kept beside the element and applied at render time.
+const docEmoji = new WeakMap();
 /** Reads any path sources to bytes, leaving bytes / families as-is. */
 function resolveFontSource(source) {
     const read = (s) => (typeof s === "string" ? readFileBytes(s) : s);
@@ -81,6 +84,8 @@ export function Document(a, b) {
     });
     if (opts.meta)
         docMeta.set(doc, opts.meta);
+    if (opts.emoji)
+        docEmoji.set(doc, opts.emoji);
     // Managed font registry: addFont registers, getFonts/hasFont query, render reads it (below).
     const registry = new Map();
     docFonts.set(doc, registry);
@@ -153,6 +158,14 @@ export async function renderPdf(doc, options) {
                     description: a.description,
                 });
             }
+            // Color-emoji fallback (Document({ emoji })): a font (native vector) or a CDN/image source.
+            const emoji = docEmoji.get(doc);
+            if (typeof emoji === "string")
+                om.setEmojiFont(emoji);
+            else if (emoji && "font" in emoji)
+                om.setEmojiFont(emoji.font);
+            else if (emoji && "url" in emoji)
+                om.setEmojiImageSource(emoji.url, emoji.format ?? "png");
             if (options?.xmp)
                 om.setXmpMetadata(options.xmp);
             if (options?.outputIntent)
@@ -163,6 +176,18 @@ export async function renderPdf(doc, options) {
                 om.enableDocumentId();
             if (securityHandler)
                 om.setSecurityHandler(securityHandler);
+            if (options?.accessible) {
+                om.struct.enabled = true;
+                if (options.lang)
+                    om.struct.lang = options.lang;
+                // Fall back to the document's own title (Document({ meta })) when no explicit title is given.
+                const title = options.title ?? meta?.title;
+                if (title)
+                    om.struct.title = title;
+                // Declare PDF/UA-1 in the XMP metadata, unless the caller supplied their own packet.
+                if (!options.xmp)
+                    om.setXmpMetadata(uaXmp({ title }));
+            }
         }
         build() {
             return doc;

package/dist/api/table.js

@@ -1,6 +1,7 @@
 import { BoxConstraints } from "../layout/box-constraints.js";
 import { RepeatingHeaderElement } from "../elements/layout/repeating-header-element.js";
 import { DeferredElement } from "../elements/layout/deferred-element.js";
+import { StructGroup } from "../elements/layout/struct-group.js";
 import { Column, Row, Box, Expanded, Padding } from "./layout.js";
 import { Text } from "./text.js";
 function asElement(c) {
@@ -52,8 +53,11 @@ function composeTable(opts, rows, columns) {
             ...(firstCol ? { borderLeft: cb } : {}),
         };
     // `ruled` rows get just a bottom line (the header underline / the table foot), without the full grid.
-    const wrap = (cell, col, firstRow, firstCol, ruled) => {
-        const inner = cellPadding !== undefined ? Padding(cellPadding, asElement(cell)) : asElement(cell);
+    const wrap = (cell, col, firstRow, firstCol, ruled, isHeader) => {
+        const content = cellPadding !== undefined ? Padding(cellPadding, asElement(cell)) : asElement(cell);
+        // Tag the cell (TH for a header cell, else TD). StructGroup is layout-transparent - visually nothing
+        // changes; it only nests the cell's content under a table-cell element in the accessible structure tree.
+        const inner = new StructGroup({ role: isHeader ? "TH" : "TD", child: content });
         // The border lives on the wrapper, which stretches to the row height (crisp lines).
         const border = {
             ...borderFor(firstRow, firstCol),
@@ -68,14 +72,18 @@ function composeTable(opts, rows, columns) {
         throw new Error(`Unsupported column width "${col}" - use a number of points or "<n>fr"`);
     };
     // align:stretch → equal-height cells, so a wrapping cell keeps the row's bottom rule straight.
-    const buildRow = (cells, firstRow, ruled = false) => Row({ gap: colGap, align: "stretch" }, cells.map((cell, i) => wrap(cell, columns[i] ?? "1fr", firstRow, i === 0, ruled)));
+    const buildRow = (cells, firstRow, ruled = false, isHeader = false) => new StructGroup({
+        role: "TR",
+        child: Row({ gap: colGap, align: "stretch" }, cells.map((cell, i) => wrap(cell, columns[i] ?? "1fr", firstRow, i === 0, ruled, isHeader))),
+    });
     // The first row (which gets the top border) is the header if present, else body row 0.
     // `rule` underlines the header and the last body row (the table foot).
     const last = rows.length - 1;
     const body = Column({ gap: rowGap }, rows.map((cells, idx) => buildRow(cells, !opts.header && idx === 0, rule !== undefined && idx === last)));
-    return opts.header
-        ? new RepeatingHeaderElement(buildRow(opts.header, true, rule !== undefined), body, rowGap)
+    const table = opts.header
+        ? new RepeatingHeaderElement(buildRow(opts.header, true, rule !== undefined, true), body, rowGap)
         : body;
+    return new StructGroup({ role: "Table", child: table });
 }
 /**
  * A `Column` of `Row`s. Fixed-point columns sit in a fixed-width `Box`, `"Nfr"` fractions

package/dist/api/text.d.ts

@@ -1,4 +1,4 @@
-import { TextElement, TextSegment } from "../elements/text-element.js";
+import { TextElement, TextRole, TextSegment } from "../elements/text-element.js";
 import { TextOverflow } from "../text/line-breaker.js";
 import { ResolvedTextStyle } from "../text/text-style.js";
 import { ColorInput } from "./color.js";
@@ -23,6 +23,9 @@ export interface TextOptions extends TextStyle {
     /** Line-height multiplier (default `1`). `1.4` gives roomier body copy; each line is
      *  `size * lineHeight` tall. */
     lineHeight?: number;
+    /** Accessibility role for the tagged structure tree (only when rendered with `accessible`): a heading
+     *  level `"h1"`..`"h6"` or `"p"` (default). Purely semantic - it does not change the visual style. */
+    role?: TextRole;
 }
 /**
  * An inline run for mixed-style `Text` (`Text([span("a", {bold:true}), span("b")])`). Each

package/dist/api/text.js

@@ -52,6 +52,7 @@ export function Text(content, opts = {}) {
         maxLines: opts.maxLines,
         overflow: opts.overflow,
         lineHeight: opts.lineHeight,
+        role: opts.role,
     });
 }
 /** `Text` with body-paragraph defaults (same options; a separate name reads as intent). */

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

@@ -52,12 +52,15 @@ interface ImageElementParams {
     fit?: BoxFit;
     /** Corner radius in points; rounds the image box (0 = sharp, default). */
     radius?: number;
+    /** Alternate text for accessibility (tagged PDF). With `alt` the image is a Figure; without, decoration. */
+    alt?: string;
 }
 export declare class ImageElement extends SizedPDFElement {
     private image;
     private fit;
     private radius;
-    constructor({ image, width, height, fit, radius }: ImageElementParams);
+    private readonly alt?;
+    constructor({ image, width, height, fit, radius, alt }: ImageElementParams);
     calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
     getProps(): {
         x: number;
@@ -67,6 +70,7 @@ export declare class ImageElement extends SizedPDFElement {
         image: CustomImage;
         fit: BoxFit;
         radius: number;
+        alt: string | undefined;
     };
 }
 export {};

package/dist/elements/image-element.js

@@ -95,12 +95,13 @@ export class CustomBytesImage extends CustomImage {
     }
 }
 export class ImageElement extends SizedPDFElement {
-    constructor({ image, width, height, fit = BoxFit.none, radius }) {
+    constructor({ image, width, height, fit = BoxFit.none, radius, alt }) {
         super({ x: 0, y: 0, width });
         this.image = image;
         this.height = height;
         this.fit = fit;
         this.radius = radius ?? 0;
+        this.alt = alt;
     }
     calculateLayout(constraints, offset, _ctx) {
         this.x = offset.x;
@@ -122,6 +123,7 @@ export class ImageElement extends SizedPDFElement {
             image: this.image,
             fit: this.fit,
             radius: this.radius,
+            alt: this.alt,
         };
     }
 }

package/dist/elements/layout/struct-group.d.ts

@@ -0,0 +1,28 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+/**
+ * A layout-TRANSPARENT wrapper that assigns an accessibility structure role (Table / TR / TH / TD / …) to
+ * its single child. It delegates ALL layout and fragmentation to the child, so the visual result is byte-
+ * identical; only its renderer opens a structure element and nests the child's tags underneath.
+ *
+ * Split across pages, the fitted and remainder halves share this group's `structId`, so it stays ONE
+ * logical structure element (a table broken over pages is a single <Table>, exactly as Acrobat produces).
+ */
+export declare class StructGroup extends PDFElement implements Fragmentable {
+    private role;
+    private child;
+    constructor({ role, child }: {
+        role: string;
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /** Only splittable when the wrapped child is - so a StructGroup(Row) is moved whole to the next page,
+     *  not clipped at the boundary (isFragmentable honours this veto). */
+    canFragment(): boolean;
+    fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    getProps(): {
+        role: string;
+        child: PDFElement;
+    };
+}

package/dist/elements/layout/struct-group.js

@@ -0,0 +1,42 @@
+import { PDFElement } from "../pdf-element.js";
+import { isFragmentable } from "../../layout/fragmentation.js";
+/**
+ * A layout-TRANSPARENT wrapper that assigns an accessibility structure role (Table / TR / TH / TD / …) to
+ * its single child. It delegates ALL layout and fragmentation to the child, so the visual result is byte-
+ * identical; only its renderer opens a structure element and nests the child's tags underneath.
+ *
+ * Split across pages, the fitted and remainder halves share this group's `structId`, so it stays ONE
+ * logical structure element (a table broken over pages is a single <Table>, exactly as Acrobat produces).
+ */
+export class StructGroup extends PDFElement {
+    constructor({ role, child }) {
+        super();
+        this.role = role;
+        this.child = child;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        return this.child.calculateLayout(constraints, offset, ctx);
+    }
+    /** Only splittable when the wrapped child is - so a StructGroup(Row) is moved whole to the next page,
+     *  not clipped at the boundary (isFragmentable honours this veto). */
+    canFragment() {
+        return isFragmentable(this.child);
+    }
+    fragment(maxHeight, width, ctx) {
+        if (!isFragmentable(this.child))
+            return { fitted: null, remainder: this };
+        const { fitted, remainder } = this.child.fragment(maxHeight, width, ctx);
+        // Re-wrap each half with the SAME role + identity, so both pages point at one structure element.
+        return {
+            fitted: fitted
+                ? new StructGroup({ role: this.role, child: fitted }).adoptStructId(this)
+                : null,
+            remainder: remainder
+                ? new StructGroup({ role: this.role, child: remainder }).adoptStructId(this)
+                : null,
+        };
+    }
+    getProps() {
+        return { role: this.role, child: this.child };
+    }
+}

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

@@ -37,6 +37,10 @@ export interface LayoutContext {
     onOverflow?: OverflowPolicy;
 }
 export declare abstract class PDFElement {
+    private _structId;
+    get structId(): number;
+    /** Make this element share `from`'s tagging identity - used by fragmentation clones. Returns this. */
+    adoptStructId(from: PDFElement): this;
     abstract getProps(): unknown;
     /**
      * Lays the element out: `constraints` bound its size (flows DOWN), `offset` is the

package/dist/elements/pdf-element.js

@@ -1,4 +1,19 @@
+let _nextStructId = 0;
 export class PDFElement {
+    constructor() {
+        // Stable identity for accessible (PDF/UA) tagging: assigned once at construction and carried through
+        // 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++;
+    }
+    get structId() {
+        return this._structId;
+    }
+    /** Make this element share `from`'s tagging identity - used by fragmentation clones. Returns this. */
+    adoptStructId(from) {
+        this._structId = from._structId;
+        return this;
+    }
 }
 export class SizedPDFElement extends PDFElement {
     constructor(data) {

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

@@ -11,6 +11,8 @@ export interface TextSegment {
     fontFamily?: string;
     fontSize?: number;
 }
+/** Accessibility role for the tagged structure tree: a heading level or a paragraph (the default). */
+export type TextRole = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p";
 interface TextElementParams {
     id?: string;
     /** Unset (undefined) inherits the cascaded size; see ResolvedTextStyle. */
@@ -26,6 +28,8 @@ interface TextElementParams {
     overflow?: TextOverflow;
     /** Line-height multiplier: each line is `fontSize * lineHeight` tall (default `1`). */
     lineHeight?: number;
+    /** Accessibility role for the tagged structure tree (heading level or paragraph; default `"p"`). */
+    role?: TextRole;
 }
 export declare class TextElement extends SizedPDFElement implements Fragmentable {
     private readonly rawFontSize?;
@@ -43,7 +47,8 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
     private content;
     private maxLines?;
     private overflow;
-    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, overflow, lineHeight, }: TextElementParams);
+    private readonly role?;
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, overflow, lineHeight, role, }: TextElementParams);
     private resolveStyle;
     private applyStyle;
     /**
@@ -80,6 +85,7 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
         maxLines: number | undefined;
         overflow: TextOverflow;
         lineHeight: number;
+        role: TextRole | undefined;
     };
 }
 export {};

package/dist/elements/text-element.js

@@ -7,8 +7,9 @@ import { DEFAULT_TEXT_STYLE } from "../text/text-style.js";
 import { wrapStringIntoLines, breakSegmentsIntoLines, segmentLinesToSegments, } from "../text/line-breaker.js";
 import { SizedPDFElement } from "./pdf-element.js";
 export class TextElement extends SizedPDFElement {
-    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, overflow = "clip", lineHeight, }) {
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, overflow = "clip", lineHeight, role, }) {
         super({ x: 0, y: 0 });
+        this.role = role;
         this.rawFontSize = fontSize;
         this.rawFontFamily = fontFamily;
         this.rawFontStyle = fontStyle;
@@ -97,7 +98,8 @@ export class TextElement extends SizedPDFElement {
             maxLines: this.maxLines,
             overflow: this.overflow,
             lineHeight: this.lineHeight,
-        });
+            role: this.role,
+        }).adoptStructId(this); // a wrapped remainder is the SAME logical paragraph (one P across pages)
     }
     calculateLayout(constraints, offset, ctx) {
         this.resolveStyle(ctx);
@@ -157,6 +159,7 @@ export class TextElement extends SizedPDFElement {
             maxLines: this.maxLines,
             overflow: this.overflow,
             lineHeight: this.lineHeight,
+            role: this.role,
         };
     }
 }

package/dist/ir/display-list.d.ts

@@ -11,6 +11,16 @@ import { FontStyle } from "../utils/pdf-object-manager.js";
  * Coordinates are in PDF points (1/72"). Which origin they use is still the
  * producer's concern for now; centralizing the Y-flip at this seam is Phase 3.
  */
+/**
+ * Structure tag for accessible (PDF/UA) tagging. `role` is the PDF structure type the content maps to
+ * (`P`, `H1`..`H6`, `Figure`, `TD`, …); `key` groups the IR nodes of one logical element (e.g. every line
+ * of a paragraph) into a single structure element; `alt` is the alternate text for a figure. A drawable
+ * node WITHOUT a tag is emitted as an Artifact (decoration, skipped by screen readers).
+ */
+export interface StructTag {
+    role: string;
+    key: number;
+}
 /**
  * A single positioned run of text in one font / size / color. Line wrapping has
  * already happened upstream: the producer emits one `TextRun` per laid-out line or
@@ -25,6 +35,7 @@ export interface TextRun {
     fontStyle: FontStyle;
     fontSize: number;
     color: Color;
+    tag?: StructTag;
 }
 /** An axis-aligned rectangle. An absent `fill` or `stroke` means that part is not drawn. */
 export interface Rect {
@@ -38,6 +49,7 @@ export interface Rect {
     strokeWidth: number;
     /** Corner radius in points; absent/0 = sharp corners (plain `re`). */
     radius?: number;
+    tag?: StructTag;
 }
 /** A straight line segment between two points. */
 export interface Line {
@@ -48,6 +60,7 @@ export interface Line {
     y2: number;
     stroke: Color;
     strokeWidth: number;
+    tag?: StructTag;
 }
 /** A raster image, already resolved to bytes by the producer (no `CustomImage` here). */
 export interface Image {
@@ -71,6 +84,7 @@ export interface Image {
     };
     /** Corner radius in points for the image box; absent/0 = sharp corners. */
     radius?: number;
+    tag?: StructTag;
 }
 /**
  * Pushes a clipping region (a rectangle, rounded when `radius` is set). Everything between this and
@@ -89,5 +103,69 @@ export interface ClipPush {
 export interface ClipPop {
     type: "clip-pop";
 }
+/**
+ * One drawing command of a `Path`, in absolute page coordinates. Curves are CUBIC because PDF
+ * content streams have no quadratic operator - a producer converts TrueType quads to cubics before
+ * emitting. `z` closes the current subpath (a glyph contour).
+ */
+export type PathCommand = {
+    op: "m";
+    x: number;
+    y: number;
+} | {
+    op: "l";
+    x: number;
+    y: number;
+} | {
+    op: "c";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x: number;
+    y: number;
+} | {
+    op: "z";
+};
+/** One color stop of a gradient: a position 0..1 along the axis and its color. */
+export interface GradientStop {
+    offset: number;
+    color: Color;
+}
+/** An axial (linear) gradient between two points, in absolute page coordinates. */
+export interface LinearGradient {
+    type: "linear";
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    stops: GradientStop[];
+    extend: "pad" | "repeat" | "reflect";
+}
+/** A radial gradient between two circles, in absolute page coordinates. */
+export interface RadialGradient {
+    type: "radial";
+    x0: number;
+    y0: number;
+    r0: number;
+    x1: number;
+    y1: number;
+    r1: number;
+    stops: GradientStop[];
+    extend: "pad" | "repeat" | "reflect";
+}
+export type Gradient = LinearGradient | RadialGradient;
+/**
+ * A filled vector path - one or more closed subpaths sharing a single fill, using the nonzero
+ * winding rule (so a glyph's inner contour cuts a hole). This is what a color glyph's layers draw
+ * onto: each COLR layer is one `Path` filled with a solid `Color` (v0) or a `Gradient` (v1).
+ */
+export interface Path {
+    type: "path";
+    commands: PathCommand[];
+    fill: Color | Gradient;
+    /** Accessibility structure tag (absent = drawn as an artifact); color-emoji layers stay untagged. */
+    tag?: StructTag;
+}
 /** The closed set of primitives the PDF backend knows how to draw. */
-export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop;
+export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop | Path;

package/dist/layout/fragmentation.js

@@ -1,7 +1,14 @@
 import { BoxConstraints } from "./box-constraints.js";
 export function isFragmentable(element) {
-    return ("fragment" in element &&
-        typeof element.fragment === "function");
+    if (!("fragment" in element) ||
+        typeof element.fragment !== "function") {
+        return false;
+    }
+    // An element may veto splitting at runtime via canFragment() - a transparent StructGroup only fragments
+    // when its wrapped child does, so a non-splittable wrapped child (e.g. a table row) is moved whole to the
+    // next page instead of being clipped at the boundary. Elements without canFragment() are always splittable.
+    const canFragment = element.canFragment;
+    return typeof canFragment !== "function" || canFragment.call(element);
 }
 function reportOverflow(child, childHeight, maxHeight, policy) {
     if (policy === "ignore")

package/dist/renderer/emoji-image.d.ts

@@ -0,0 +1,9 @@
+import { Image } from "../ir/display-list.js";
+export declare function emojiImageUrl(codePoint: number, source: {
+    url: string;
+    format: string;
+}): string;
+export declare function emojiImageNode(codePoint: number, source: {
+    url: string;
+    format: string;
+}, x: number, baselineY: number, em: number): Promise<Image | null>;

package/dist/renderer/emoji-image.js

@@ -0,0 +1,68 @@
+import { CustomBytesImage } from "../elements/image-element.js";
+import { decodePngToRgbFlate } from "../utils/image-helper.js";
+import { bytesFromLatin1 } from "../utils/bytes.js";
+// Per-URL fetch cache (process-wide): an emoji image is fetched once, however many times it appears.
+const cache = new Map();
+const FETCH_TIMEOUT_MS = 5000; // a slow CDN must not stall the whole render
+async function fetchBytes(url) {
+    const cached = cache.get(url);
+    if (cached)
+        return cached;
+    const pending = (async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        try {
+            const r = await fetch(url, { signal: controller.signal });
+            return r.ok ? new Uint8Array(await r.arrayBuffer()) : null;
+        }
+        catch {
+            return null; // offline / 404 / timeout -> null; the caller leaves a blank gap (graceful)
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    })();
+    cache.set(url, pending);
+    // Cache only SUCCESSFUL results: drop a failure so a transient error (offline) can be retried later.
+    void pending.then((bytes) => {
+        if (!bytes && cache.get(url) === pending)
+            cache.delete(url);
+    });
+    return pending;
+}
+// Twemoji-style URL: base + lowercase hex code point + "." + format (e.g. ".../1f600.png"). Single
+// code points only - multi-code-point sequences (flags, ZWJ) are out of scope for now.
+export function emojiImageUrl(codePoint, source) {
+    return `${source.url}${codePoint.toString(16)}.${source.format}`;
+}
+// Builds an `Image` IR node for an emoji drawn as a 1em square seated on the baseline (mostly above
+// it, a little below - like a text glyph), or null when the fetch/decode fails.
+export async function emojiImageNode(codePoint, source, x, baselineY, em) {
+    const bytes = await fetchBytes(emojiImageUrl(codePoint, source));
+    if (!bytes)
+        return null;
+    const img = new CustomBytesImage(bytes);
+    const imageType = await img.getImageType();
+    const fileData = await img.getFileData();
+    const dims = await img.getImageDimensions();
+    // JPEG embeds raw; PNG is decoded to DeviceRGB + an /SMask alpha channel (transparency).
+    let data = fileData;
+    let smask;
+    if (imageType === "FlateDecode") {
+        const decoded = await decodePngToRgbFlate(bytesFromLatin1(fileData));
+        data = decoded.data;
+        smask = decoded.smask;
+    }
+    return {
+        type: "image",
+        x,
+        y: baselineY - em * 0.82,
+        width: em,
+        height: em,
+        intrinsicWidth: dims.width,
+        intrinsicHeight: dims.height,
+        data,
+        imageType,
+        ...(smask ? { smask } : {}),
+    };
+}

package/dist/renderer/image-renderer.d.ts

@@ -2,5 +2,5 @@ import { ImageElement } from "../elements/image-element.js";
 import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 import { IRNode } from "../ir/display-list.js";
 export declare class ImageRenderer {
-    static render(imageElement: ImageElement, _objectManager: PDFObjectManager): Promise<IRNode[]>;
+    static render(imageElement: ImageElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
 }