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

package/dist/crypto/security-handler.d.ts

@@ -0,0 +1,46 @@
+/** A handler encrypts/decrypts the strings + streams of a document and describes itself as an `/Encrypt` dict. */
+export interface SecurityHandler {
+    /** The `/Encrypt` dictionary body (between `<<` and `>>`). Its own strings are never encrypted. */
+    encryptDict(): string;
+    /** Encrypt one string/stream. `ref` is unused for V5/R6 (one file key) but kept for future per-object schemes. */
+    encrypt(data: Uint8Array, ref?: {
+        num: number;
+        gen: number;
+    }): Promise<Uint8Array>;
+    /** Decrypt one string/stream (the groundwork the future "open/edit existing PDF" path reuses). */
+    decrypt(data: Uint8Array, ref?: {
+        num: number;
+        gen: number;
+    }): Promise<Uint8Array>;
+}
+/** What the user grants; everything defaults to allowed. Maps to the `/P` bitfield (ISO 32000-2 Table 22). */
+export interface Permissions {
+    printing?: boolean;
+    copying?: boolean;
+    modifying?: boolean;
+    annotating?: boolean;
+}
+export interface EncryptOptions {
+    /** Only "aes-256" today - the seam for future algorithms. */
+    algorithm?: "aes-256";
+    userPassword: string;
+    /** Full-rights password; defaults to the user password if omitted. */
+    ownerPassword?: string;
+    permissions?: Permissions;
+}
+declare class StandardAes256 implements SecurityHandler {
+    private readonly fileKey;
+    private readonly dict;
+    private constructor();
+    static create(opts: EncryptOptions): Promise<StandardAes256>;
+    encryptDict(): string;
+    encrypt(data: Uint8Array): Promise<Uint8Array>;
+    decrypt(data: Uint8Array): Promise<Uint8Array>;
+    /** Recover the file key from a password as a reader does: validate it against /U FIRST (so a wrong
+     *  password is rejected, not silently turned into a garbage key), then decrypt /UE. The groundwork the
+     *  future "open/edit existing PDF" path reuses. Throws on a wrong password. */
+    static recoverFileKey(userPassword: string, u: Uint8Array, ue: Uint8Array): Promise<Uint8Array>;
+}
+/** The factory = the seam. Today it always returns the AES-256 handler. */
+export declare function createSecurityHandler(opts: EncryptOptions): Promise<SecurityHandler>;
+export { StandardAes256 };

package/dist/crypto/security-handler.js

@@ -0,0 +1,129 @@
+// PDF Standard security handler. The PDFObjectManager talks to the `SecurityHandler` interface, never to a
+// concrete algorithm - so adding another scheme later (a new revision, or per-object RC4/AES-128) is just a
+// second implementation + a factory branch, with the writer untouched. Today we ship exactly one:
+// `StandardAes256` = AES-256, V5/R6 (ISO 32000-2 / PDF 2.0), the newest standard PDF encryption.
+import { aesCbcDecrypt, aesCbcDecryptNoPad, aesCbcEncrypt, aesCbcEncryptNoPad, randomBytes, sha, } from "./webcrypto.js";
+const utf8 = (s) => new TextEncoder().encode(s).subarray(0, 127); // R6 truncates passwords to 127 bytes
+const concat = (...parts) => {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+};
+const toHex = (a) => [...a].map((b) => b.toString(16).padStart(2, "0")).join("");
+// Constant-time-ish equality for password validation (no early-out on the first differing byte).
+const bytesEqual = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+};
+// ISO 32000-2 Algorithm 2.B: the hardened password hash. Loops AES-128-CBC + SHA-256/384/512 until the
+// stopping rule. `udata` is the 48-byte /U for the owner computations, empty for the user ones.
+async function hash2B(password, salt, udata) {
+    let k = await sha(256, concat(password, salt, udata));
+    let e = new Uint8Array(0);
+    // At least 64 rounds; then stop once the last byte of E <= round - 32 (ISO 32000-2 Algorithm 2.B).
+    for (let round = 0; round < 64 || e[e.length - 1] > round - 32; round++) {
+        const block = concat(password, k, udata);
+        const k1 = new Uint8Array(block.length * 64);
+        for (let i = 0; i < 64; i++)
+            k1.set(block, i * block.length);
+        e = await aesCbcEncryptNoPad(k.subarray(0, 16), k.subarray(16, 32), k1);
+        let sum = 0;
+        for (let i = 0; i < 16; i++)
+            sum += e[i]; // big-endian 128-bit mod 3 == byte-sum mod 3 (256 ≡ 1 mod 3)
+        k = await sha([256, 384, 512][sum % 3], e);
+    }
+    return k.subarray(0, 32);
+}
+function permissionBits(p = {}) {
+    const { printing = true, copying = true, modifying = true, annotating = true } = p;
+    let bits = 0xfffff000 | 0b11000000; // reserved-1 bits (positions 7-8 and 13-32)
+    if (printing)
+        bits |= 4 | 2048;
+    if (modifying)
+        bits |= 8 | 1024;
+    if (copying)
+        bits |= 16 | 512;
+    if (annotating)
+        bits |= 32 | 256;
+    return bits | 0; // int32
+}
+class StandardAes256 {
+    constructor(fileKey, dict) {
+        this.fileKey = fileKey;
+        this.dict = dict;
+    }
+    static async create(opts) {
+        const user = utf8(opts.userPassword);
+        const owner = utf8(opts.ownerPassword ?? opts.userPassword);
+        const fileKey = randomBytes(32);
+        const p = permissionBits(opts.permissions);
+        // Algorithm 8: /U and /UE.
+        const uVS = randomBytes(8);
+        const uKS = randomBytes(8);
+        const empty = new Uint8Array(0);
+        const u = concat(await hash2B(user, uVS, empty), uVS, uKS); // 48 bytes
+        const ue = await aesCbcEncryptNoPad(await hash2B(user, uKS, empty), new Uint8Array(16), fileKey);
+        // Algorithm 9: /O and /OE (these also fold in /U).
+        const oVS = randomBytes(8);
+        const oKS = randomBytes(8);
+        const o = concat(await hash2B(owner, oVS, u), oVS, oKS); // 48 bytes
+        const oe = await aesCbcEncryptNoPad(await hash2B(owner, oKS, u), new Uint8Array(16), fileKey);
+        // Algorithm 10: /Perms (a 16-byte block, ECB == single-block CBC with a zero IV).
+        const perms = new Uint8Array(16);
+        perms[0] = p & 0xff;
+        perms[1] = (p >> 8) & 0xff;
+        perms[2] = (p >> 16) & 0xff;
+        perms[3] = (p >> 24) & 0xff;
+        perms[4] = perms[5] = perms[6] = perms[7] = 0xff;
+        perms[8] = 0x46; // 'F' - metadata (XMP) stays unencrypted (standard; keeps it indexer-readable)
+        perms[9] = 0x61; // 'a'
+        perms[10] = 0x64; // 'd'
+        perms[11] = 0x62; // 'b'
+        perms.set(randomBytes(4), 12);
+        const permsEnc = await aesCbcEncryptNoPad(fileKey, new Uint8Array(16), perms);
+        const dict = `/Filter /Standard /V 5 /R 6 /Length 256 /P ${p} /EncryptMetadata false ` +
+            `/CF << /StdCF << /CFM /AESV3 /AuthEvent /DocOpen /Length 32 >> >> /StmF /StdCF /StrF /StdCF ` +
+            `/U <${toHex(u)}> /UE <${toHex(ue)}> /O <${toHex(o)}> /OE <${toHex(oe)}> /Perms <${toHex(permsEnc)}>`;
+        return new StandardAes256(fileKey, dict);
+    }
+    encryptDict() {
+        return this.dict;
+    }
+    async encrypt(data) {
+        const iv = randomBytes(16);
+        const ct = await aesCbcEncrypt(this.fileKey, iv, data);
+        return concat(iv, ct);
+    }
+    async decrypt(data) {
+        return aesCbcDecrypt(this.fileKey, data.subarray(0, 16), data.subarray(16));
+    }
+    /** Recover the file key from a password as a reader does: validate it against /U FIRST (so a wrong
+     *  password is rejected, not silently turned into a garbage key), then decrypt /UE. The groundwork the
+     *  future "open/edit existing PDF" path reuses. Throws on a wrong password. */
+    static async recoverFileKey(userPassword, u, ue) {
+        const pw = utf8(userPassword);
+        // Algorithm 11: hash(password + validation salt) must equal the first 32 bytes of /U.
+        const check = await hash2B(pw, u.subarray(32, 40), new Uint8Array(0));
+        if (!bytesEqual(check, u.subarray(0, 32))) {
+            throw new Error("@jasy/pdf: wrong password.");
+        }
+        const intermediate = await hash2B(pw, u.subarray(40, 48), new Uint8Array(0));
+        return aesCbcDecryptNoPad(intermediate, new Uint8Array(16), ue);
+    }
+}
+/** The factory = the seam. Today it always returns the AES-256 handler. */
+export async function createSecurityHandler(opts) {
+    if (opts.algorithm && opts.algorithm !== "aes-256") {
+        throw new Error(`@jasy/pdf: unsupported encryption algorithm "${opts.algorithm}" (only "aes-256").`);
+    }
+    return StandardAes256.create(opts);
+}
+export { StandardAes256 };

package/dist/crypto/webcrypto.d.ts

@@ -0,0 +1,11 @@
+export declare function randomBytes(n: number): Uint8Array;
+export declare function sha(bits: 256 | 384 | 512, data: Uint8Array): Promise<Uint8Array>;
+/** AES-CBC with PKCS#7 padding (the AESV3 mode for PDF strings/streams). */
+export declare function aesCbcEncrypt(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+export declare function aesCbcDecrypt(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+/** AES-CBC WITHOUT padding (`data.length` must be a multiple of 16). WebCrypto pads unconditionally, so we
+ *  encrypt and drop the extra full pad block - the leading blocks are the true unpadded CBC. */
+export declare function aesCbcEncryptNoPad(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+/** AES-CBC no-padding DECRYPT (`data` a multiple of 16). We append one cipher block crafted to decrypt to a
+ *  full 0x10 PKCS#7 pad (so WebCrypto accepts and strips it), leaving the original. */
+export declare function aesCbcDecryptNoPad(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Promise<Uint8Array>;

package/dist/crypto/webcrypto.js

@@ -0,0 +1,62 @@
+// Isomorphic crypto via the platform WebCrypto (`globalThis.crypto.subtle`) - native in the browser AND in
+// Node 20+, with zero dependencies. This is the primitive layer the PDF Standard security handler (AES-256,
+// R6) builds on. Everything is async (so is `render()`), so that is no constraint.
+//
+// One wrinkle: WebCrypto's AES-CBC ALWAYS applies PKCS#7 padding and offers no raw/no-pad mode. The PDF R6
+// key derivation (Algorithm 2.B, /UE, /OE, /Perms) needs UNPADDED AES, so we synthesize it from the padded
+// primitive (encrypt: drop the trailing pad block; decrypt: append a block that decrypts to a full pad, then
+// let WebCrypto strip it). Document strings/streams use the padded primitive directly - that IS AESV3.
+const subtle = () => {
+    const c = globalThis.crypto;
+    if (!c?.subtle) {
+        throw new Error("@jasy/pdf: PDF encryption needs WebCrypto (globalThis.crypto.subtle), unavailable here.");
+    }
+    return c.subtle;
+};
+export function randomBytes(n) {
+    const b = new Uint8Array(n);
+    globalThis.crypto.getRandomValues(b);
+    return b;
+}
+// WebCrypto's types want a BufferSource backed by ArrayBuffer; our Uint8Arrays are ArrayBuffer-backed, so
+// this cast at the platform boundary is safe (TS 5.7+ just can't prove it isn't a SharedArrayBuffer).
+const buf = (a) => a;
+export async function sha(bits, data) {
+    return new Uint8Array(await subtle().digest(`SHA-${bits}`, buf(data)));
+}
+async function aesKey(key, usage) {
+    return subtle().importKey("raw", buf(key), { name: "AES-CBC" }, false, [usage]);
+}
+/** AES-CBC with PKCS#7 padding (the AESV3 mode for PDF strings/streams). */
+export async function aesCbcEncrypt(key, iv, data) {
+    return new Uint8Array(await subtle().encrypt({ name: "AES-CBC", iv: buf(iv) }, await aesKey(key, "encrypt"), buf(data)));
+}
+export async function aesCbcDecrypt(key, iv, data) {
+    return new Uint8Array(await subtle().decrypt({ name: "AES-CBC", iv: buf(iv) }, await aesKey(key, "decrypt"), buf(data)));
+}
+/** AES-CBC WITHOUT padding (`data.length` must be a multiple of 16). WebCrypto pads unconditionally, so we
+ *  encrypt and drop the extra full pad block - the leading blocks are the true unpadded CBC. */
+export async function aesCbcEncryptNoPad(key, iv, data) {
+    if (data.length % 16 !== 0)
+        throw new Error("aesCbcEncryptNoPad: data must be a multiple of 16 bytes.");
+    return (await aesCbcEncrypt(key, iv, data)).subarray(0, data.length);
+}
+const xor16 = (a, b) => {
+    const o = new Uint8Array(16);
+    for (let i = 0; i < 16; i++)
+        o[i] = a[i] ^ b[i];
+    return o;
+};
+/** AES-CBC no-padding DECRYPT (`data` a multiple of 16). We append one cipher block crafted to decrypt to a
+ *  full 0x10 PKCS#7 pad (so WebCrypto accepts and strips it), leaving the original. */
+export async function aesCbcDecryptNoPad(key, iv, data) {
+    if (data.length === 0 || data.length % 16 !== 0)
+        throw new Error("aesCbcDecryptNoPad: data must be a non-zero multiple of 16 bytes.");
+    const prev = data.length >= 16 ? data.subarray(data.length - 16) : iv;
+    // ECB(x) == first block of CBC(iv=0, x); we want the appended block to decrypt to 0x10*16 after the CBC xor.
+    const appended = await aesCbcEncryptNoPad(key, new Uint8Array(16), xor16(new Uint8Array(16).fill(16), prev));
+    const withPad = new Uint8Array(data.length + 16);
+    withPad.set(data);
+    withPad.set(appended, data.length);
+    return aesCbcDecrypt(key, iv, withPad);
+}

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>;