@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/utils/ttf-subsetter.d.ts

@@ -1 +1 @@
-export declare function subsetTTF(data: Buffer, used: Set<number>): Buffer;
+export declare function subsetTTF(data: Uint8Array, used: Set<number>): Uint8Array;

package/dist/utils/ttf-subsetter.js

@@ -1,32 +1,30 @@
-"use strict";
 // Builds a subset TrueType font that KEEPS the original glyph ids: the PDF content stream emits
 // original gids and /W + CIDToGIDMap=Identity stay valid, so only the font program shrinks. We drop
 // the `glyf` outlines of unused glyphs (the bulk of the file) and rebuild `loca`; every other table
 // is copied verbatim. The used-glyph set is closed over composite-glyph components first, so a glyph
 // built from others (e.g. "ä") keeps its parts. Fonts without `glyf`/`loca` (CFF/OTF) pass through.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.subsetTTF = subsetTTF;
-const u32 = (n) => n >>> 0;
+import { concatBytes, i16, latin1FromBytes, u16, u32, wi16, wu16, wu32, writeLatin1, } from "./bytes.js";
+const wrap32 = (n) => n >>> 0;
 /** TrueType table checksum: sum of big-endian uint32 over the 4-byte-padded table data. */
 function checksum(buf) {
     let sum = 0;
     for (let i = 0; i < buf.length; i += 4)
-        sum = u32(sum + buf.readUInt32BE(i));
+        sum = wrap32(sum + u32(buf, i));
     return sum;
 }
 /** Right-pad to a 4-byte boundary (table data is aligned in the sfnt). */
 function pad4(buf) {
     const rem = buf.length % 4;
-    return rem === 0 ? buf : Buffer.concat([buf, Buffer.alloc(4 - rem)]);
+    return rem === 0 ? buf : concatBytes([buf, new Uint8Array(4 - rem)]);
 }
-function subsetTTF(data, used) {
-    const numTables = data.readUInt16BE(4);
+export function subsetTTF(data, used) {
+    const numTables = u16(data, 4);
     const dir = new Map();
     let p = 12;
     for (let i = 0; i < numTables; i++) {
-        dir.set(data.toString("latin1", p, p + 4), {
-            offset: data.readUInt32BE(p + 8),
-            length: data.readUInt32BE(p + 12),
+        dir.set(latin1FromBytes(data.subarray(p, p + 4)), {
+            offset: u32(data, p + 8),
+            length: u32(data, p + 12),
         });
         p += 16;
     }
@@ -34,14 +32,14 @@ function subsetTTF(data, used) {
     if (!dir.has("glyf") || !dir.has("loca") || !dir.has("head") || !dir.has("maxp"))
         return data;
     const headOff = dir.get("head").offset;
-    const longLoca = data.readInt16BE(headOff + 50) === 1;
-    const numGlyphs = data.readUInt16BE(dir.get("maxp").offset + 4);
+    const longLoca = i16(data, headOff + 50) === 1;
+    const numGlyphs = u16(data, dir.get("maxp").offset + 4);
     const locaOff = dir.get("loca").offset;
     const glyfOff = dir.get("glyf").offset;
     // Original glyph offsets (numGlyphs + 1 entries; short loca stores half-offsets).
     const loca = [];
     for (let g = 0; g <= numGlyphs; g++) {
-        loca.push(longLoca ? data.readUInt32BE(locaOff + g * 4) : data.readUInt16BE(locaOff + g * 2) * 2);
+        loca.push(longLoca ? u32(data, locaOff + g * 4) : u16(data, locaOff + g * 2) * 2);
     }
     const glyphBytes = (g) => data.subarray(glyfOff + loca[g], glyfOff + loca[g + 1]);
     // Close the used set over composite components (and always keep .notdef = gid 0).
@@ -53,12 +51,12 @@ function subsetTTF(data, used) {
             continue;
         keep.add(g);
         const gd = glyphBytes(g);
-        if (gd.length >= 10 && gd.readInt16BE(0) < 0) {
+        if (gd.length >= 10 && i16(gd, 0) < 0) {
             // Composite glyph: walk the component records to collect the referenced gids.
             let q = 10; // numberOfContours(2) + xMin/yMin/xMax/yMax(8)
             for (;;) {
-                const flags = gd.readUInt16BE(q);
-                stack.push(gd.readUInt16BE(q + 2));
+                const flags = u16(gd, q);
+                stack.push(u16(gd, q + 2));
                 q += 4 + (flags & 0x0001 ? 4 : 2); // ARG_1_AND_2_ARE_WORDS
                 if (flags & 0x0008)
                     q += 2; // WE_HAVE_A_SCALE
@@ -73,24 +71,24 @@ function subsetTTF(data, used) {
     }
     // Rebuild glyf (kept glyphs only, original numbering) + a long-format loca.
     const parts = [];
-    const newLoca = Buffer.alloc((numGlyphs + 1) * 4);
+    const newLoca = new Uint8Array((numGlyphs + 1) * 4);
     let off = 0;
     for (let g = 0; g < numGlyphs; g++) {
-        newLoca.writeUInt32BE(off, g * 4);
+        wu32(newLoca, off, g * 4);
         if (keep.has(g)) {
-            let gd = Buffer.from(glyphBytes(g));
+            let gd = glyphBytes(g).slice(); // copy: padded + concatenated, must not view `data`
             if (gd.length % 2 === 1)
-                gd = Buffer.concat([gd, Buffer.alloc(1)]); // keep offsets even
+                gd = concatBytes([gd, new Uint8Array(1)]); // keep offsets even
             parts.push(gd);
             off += gd.length;
         }
     }
-    newLoca.writeUInt32BE(off, numGlyphs * 4);
-    const newGlyf = Buffer.concat(parts);
+    wu32(newLoca, off, numGlyphs * 4);
+    const newGlyf = concatBytes(parts);
     // head copy with indexToLocFormat = 1 (long); checkSumAdjustment zeroed, fixed up at the end.
-    const newHead = Buffer.from(data.subarray(headOff, headOff + dir.get("head").length));
-    newHead.writeInt16BE(1, 50);
-    newHead.writeUInt32BE(0, 8);
+    const newHead = data.slice(headOff, headOff + dir.get("head").length);
+    wi16(newHead, 1, 50);
+    wu32(newHead, 0, 8);
     // Tables a PDF-embedded CIDFontType2 doesn't need - layout (GSUB/GPOS…), hinting hints and the
     // signature are dead weight; dropping them is most of the size win. `post` is reduced to format 3
     // (header only, no glyph names). cmap/name/OS-2 are kept for a still-valid standalone font.
@@ -119,8 +117,8 @@ function subsetTTF(data, used) {
             body = newHead;
         else if (tag === "post") {
             // Keep the 32-byte header, force version 3.0 (drops the per-glyph name list).
-            body = Buffer.from(data.subarray(dir.get("post").offset, dir.get("post").offset + 32));
-            body.writeUInt32BE(0x00030000, 0);
+            body = data.slice(dir.get("post").offset, dir.get("post").offset + 32);
+            wu32(body, 0x00030000, 0);
         }
         else {
             const d = dir.get(tag);
@@ -132,30 +130,30 @@ function subsetTTF(data, used) {
     const n = tables.length;
     const maxPow2 = 1 << Math.floor(Math.log2(n));
     const out = [];
-    const offsetTable = Buffer.alloc(12);
-    offsetTable.writeUInt32BE(data.readUInt32BE(0), 0); // sfntVersion
-    offsetTable.writeUInt16BE(n, 4);
-    offsetTable.writeUInt16BE(maxPow2 * 16, 6); // searchRange
-    offsetTable.writeUInt16BE(Math.floor(Math.log2(n)), 8); // entrySelector
-    offsetTable.writeUInt16BE(n * 16 - maxPow2 * 16, 10); // rangeShift
+    const offsetTable = new Uint8Array(12);
+    wu32(offsetTable, u32(data, 0), 0); // sfntVersion
+    wu16(offsetTable, n, 4);
+    wu16(offsetTable, maxPow2 * 16, 6); // searchRange
+    wu16(offsetTable, Math.floor(Math.log2(n)), 8); // entrySelector
+    wu16(offsetTable, n * 16 - maxPow2 * 16, 10); // rangeShift
     out.push(offsetTable);
-    const dirBuf = Buffer.alloc(n * 16);
+    const dirBuf = new Uint8Array(n * 16);
     let tableOffset = 12 + n * 16;
     const dataBufs = [];
     tables.forEach((t, i) => {
         const padded = pad4(t.body);
-        dirBuf.write(t.tag, i * 16, 4, "latin1");
-        dirBuf.writeUInt32BE(checksum(padded), i * 16 + 4);
-        dirBuf.writeUInt32BE(tableOffset, i * 16 + 8);
-        dirBuf.writeUInt32BE(t.length, i * 16 + 12); // real (unpadded) length
+        writeLatin1(dirBuf, t.tag, i * 16);
+        wu32(dirBuf, checksum(padded), i * 16 + 4);
+        wu32(dirBuf, tableOffset, i * 16 + 8);
+        wu32(dirBuf, t.length, i * 16 + 12); // real (unpadded) length
         tableOffset += padded.length;
         dataBufs.push(padded);
     });
     out.push(dirBuf, ...dataBufs);
-    const font = Buffer.concat(out);
+    const font = concatBytes(out);
     // head.checkSumAdjustment = 0xB1B0AFBA - checksum(whole font). Locate head in the assembled font.
     const headIdx = tables.findIndex((t) => t.tag === "head");
-    const headPos = dirBuf.readUInt32BE(headIdx * 16 + 8);
-    font.writeUInt32BE(u32(0xb1b0afba - checksum(font)), headPos + 8);
+    const headPos = u32(dirBuf, headIdx * 16 + 8);
+    wu32(font, wrap32(0xb1b0afba - checksum(font)), headPos + 8);
     return font;
 }

package/dist/utils/ua-xmp.d.ts

@@ -0,0 +1,9 @@
+/**
+ * XMP metadata packet that identifies the document as PDF/UA-1 (accessible). A fully conformant PDF/UA file
+ * also needs a displayed title (the /ViewerPreferences /DisplayDocTitle flag + this dc:title) and embedded
+ * fonts - the same font rule PDF/A has, so the standard-14 fonts do not qualify. Language is declared once
+ * in the catalog `/Lang`, not here (the dc:title uses `x-default`), so this takes only the title.
+ */
+export declare function uaXmp(opts?: {
+    title?: string;
+}): string;

package/dist/utils/ua-xmp.js

@@ -0,0 +1,32 @@
+// Escapes text for XML AND keeps the packet ASCII-safe: XML metacharacters become entities, and any
+// non-ASCII / control character becomes a numeric character reference. The PDF writer emits the
+// metadata stream one byte per char (Latin-1), so a raw non-ASCII title like "R\u00E9sum\u00E9" would corrupt
+// the UTF-8 XMP (and misalign /Length); escaping keeps every char <= 0x7e.
+const esc = (s) => s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/[^ -~]/gu, (c) => `&#${c.codePointAt(0)};`); // any non printable-ASCII char
+/**
+ * XMP metadata packet that identifies the document as PDF/UA-1 (accessible). A fully conformant PDF/UA file
+ * also needs a displayed title (the /ViewerPreferences /DisplayDocTitle flag + this dc:title) and embedded
+ * fonts - the same font rule PDF/A has, so the standard-14 fonts do not qualify. Language is declared once
+ * in the catalog `/Lang`, not here (the dc:title uses `x-default`), so this takes only the title.
+ */
+export function uaXmp(opts = {}) {
+    const title = esc(opts.title ?? "");
+    return (
+    // The xpacket marker is the 3-byte UTF-8 BOM (EF BB BF) written as Latin-1 chars so the
+    // single-byte writer emits it verbatim - a literal U+FEFF would be mangled to "?".
+    `<?xpacket begin="\u00EF\u00BB\u00BF" id="W5M0MpCehiHzreSzNTczkc9d"?>` +
+        `<x:xmpmeta xmlns:x="adobe:ns:meta/">` +
+        `<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">` +
+        `<rdf:Description rdf:about="" xmlns:pdfuaid="http://www.aiim.org/pdfua/ns/id/">` +
+        `<pdfuaid:part>1</pdfuaid:part>` +
+        `</rdf:Description>` +
+        `<rdf:Description rdf:about="" xmlns:dc="http://purl.org/dc/elements/1.1/">` +
+        `<dc:title><rdf:Alt><rdf:li xml:lang="x-default">${title}</rdf:li></rdf:Alt></dc:title>` +
+        `</rdf:Description>` +
+        `</rdf:RDF></x:xmpmeta>` +
+        `<?xpacket end="w"?>`);
+}

package/dist/utils/utf8-to-windows1252-encoder.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Whether Windows-1252 can carry this code point - which is exactly what a standard-14 font can draw,
+ * since that is the encoding its `/Widths` array is indexed by. Latin-1 passes straight through,
+ * except the C1 range, which the table above fills with printable punctuation instead.
+ */
+export declare function isWindows1252(codePoint: number): boolean;
 /** Encodes a JavaScript string to a Windows-1252 byte buffer (the PDF text encoding). */
 export declare function getArrayBuffer(data: string): ArrayBuffer;

package/dist/utils/utf8-to-windows1252-encoder.js

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getArrayBuffer = getArrayBuffer;
 // Windows-1252 equals Latin-1 (codepoint == byte) EXCEPT in 0x80-0x9F, where it carries
 // printable punctuation - the Euro sign, smart quotes, dashes, ellipsis, ... - instead of
 // C1 controls. Those glyphs sit at Unicode codepoints far outside 0x00-0xFF, so a naive
@@ -36,8 +33,18 @@ const CP1252_FROM_UNICODE = {
     0x017e: 0x9e, // ž z caron
     0x0178: 0x9f, // Ÿ Y diaeresis
 };
+/**
+ * Whether Windows-1252 can carry this code point - which is exactly what a standard-14 font can draw,
+ * since that is the encoding its `/Widths` array is indexed by. Latin-1 passes straight through,
+ * except the C1 range, which the table above fills with printable punctuation instead.
+ */
+export function isWindows1252(codePoint) {
+    if (codePoint in CP1252_FROM_UNICODE)
+        return true;
+    return codePoint <= 0xff && !(codePoint >= 0x80 && codePoint <= 0x9f);
+}
 /** Encodes a JavaScript string to a Windows-1252 byte buffer (the PDF text encoding). */
-function getArrayBuffer(data) {
+export function getArrayBuffer(data) {
     const u8 = new Uint8Array(data.length);
     for (let i = 0; i < data.length; i++) {
         const code = data.charCodeAt(i);

package/dist/utils/woff.d.ts

@@ -0,0 +1,10 @@
+export declare class WoffError extends Error {
+    constructor(message: string);
+}
+/** Whether these bytes are a WOFF 1.0 container. Cheap enough to call on every font. */
+export declare const isWoff: (bytes: Uint8Array) => boolean;
+/**
+ * Unpack a WOFF into the sfnt it wraps. The result is byte-for-byte what a `.ttf` of the same font
+ * would be, apart from table padding, so nothing downstream can tell the difference.
+ */
+export declare function woffToSfnt(woff: Uint8Array): Uint8Array;

package/dist/utils/woff.js

@@ -0,0 +1,116 @@
+import { inflateBounded } from "./inflate.js";
+/**
+ * WOFF 1.0 -> plain sfnt, so the existing `TTFParser` never learns a second container format.
+ *
+ * A WOFF is not a different FONT, it is a different wrapper: the same sfnt tables, each optionally
+ * zlib-compressed, behind a small header. Unpacking it back into an sfnt is therefore the whole job -
+ * every metric, glyph and cmap path downstream stays exactly as it was.
+ *
+ * WOFF2 is deliberately NOT here: it compresses with Brotli, which `fflate` does not do, and it also
+ * TRANSFORMS the glyf/loca tables rather than merely deflating them. That is a different piece of work,
+ * not a bigger version of this one.
+ */
+const SIG_WOFF = 0x774f4646; // "wOFF"
+const HEADER = 44;
+const DIR_ENTRY = 20;
+/** One table may not inflate past this. A single sfnt table above 64 MB is not a real font. */
+const MAX_TABLE_BYTES = 64 * 1024 * 1024;
+/**
+ * And all of them together may not either. The per-table ceiling alone is not a bound: `numTables` is a
+ * uint16, so 65535 directory entries may all point at the SAME small compressed blob, and each would be
+ * inflated and kept. Generous enough for a full CJK face, which is the largest real font there is.
+ */
+const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+export class WoffError extends Error {
+    constructor(message) {
+        super(`@jasy/pdf: ${message}`);
+    }
+}
+const be32 = (b, at) => ((b[at] << 24) | (b[at + 1] << 16) | (b[at + 2] << 8) | b[at + 3]) >>> 0;
+const be16 = (b, at) => (b[at] << 8) | b[at + 1];
+/** Whether these bytes are a WOFF 1.0 container. Cheap enough to call on every font. */
+export const isWoff = (bytes) => bytes.length >= HEADER && be32(bytes, 0) === SIG_WOFF;
+/**
+ * Unpack a WOFF into the sfnt it wraps. The result is byte-for-byte what a `.ttf` of the same font
+ * would be, apart from table padding, so nothing downstream can tell the difference.
+ */
+export function woffToSfnt(woff) {
+    if (!isWoff(woff))
+        throw new WoffError("these bytes are not a WOFF container");
+    const flavor = be32(woff, 4);
+    const numTables = be16(woff, 12);
+    if (numTables === 0)
+        throw new WoffError("this WOFF declares no tables");
+    if (woff.length < HEADER + numTables * DIR_ENTRY) {
+        throw new WoffError("this WOFF is truncated: its table directory does not fit in the file");
+    }
+    // Read the directory first, then the tables, so a malformed offset is caught before any allocation.
+    const entries = Array.from({ length: numTables }, (_, i) => {
+        const at = HEADER + i * DIR_ENTRY;
+        return {
+            tag: be32(woff, at),
+            offset: be32(woff, at + 4),
+            compLength: be32(woff, at + 8),
+            origLength: be32(woff, at + 12),
+            checksum: be32(woff, at + 16),
+        };
+    });
+    // Tracked across ALL tables, and checked BEFORE each inflate so a hostile directory costs neither the
+    // CPU of unpacking nor the memory of keeping the result.
+    let unpacked = 0;
+    const claim = (bytes) => {
+        unpacked += bytes;
+        if (unpacked > MAX_TOTAL_BYTES) {
+            throw new WoffError(`this WOFF unpacks to more than ${MAX_TOTAL_BYTES} bytes in total; no real font is that large`);
+        }
+    };
+    const tables = entries.map((e) => {
+        if (e.offset + e.compLength > woff.length) {
+            throw new WoffError(`this WOFF is truncated: a table runs past the end of the file`);
+        }
+        claim(e.origLength); // what it DECLARES, before any work is done on it
+        const raw = woff.subarray(e.offset, e.offset + e.compLength);
+        // Equal lengths mean the table was stored as-is; anything else is zlib, per the spec.
+        if (e.compLength === e.origLength)
+            return raw;
+        let out;
+        try {
+            out = inflateBounded(raw, MAX_TABLE_BYTES);
+        }
+        catch (err) {
+            throw new WoffError(`a table in this WOFF could not be unpacked: ${String(err?.message ?? err)}`);
+        }
+        if (out.length !== e.origLength) {
+            throw new WoffError(`a table in this WOFF unpacked to ${out.length} bytes where it declared ${e.origLength}`);
+        }
+        return out;
+    });
+    // Reassemble: offset table, directory, then the tables each padded to a 4-byte boundary.
+    const padded = (n) => (n + 3) & ~3;
+    const dirSize = numTables * 16;
+    const total = 12 + dirSize + tables.reduce((n, t) => n + padded(t.length), 0);
+    const out = new Uint8Array(total);
+    const view = new DataView(out.buffer);
+    // The binary-search hints an sfnt offset table carries. Readers may ignore them; a correct file has
+    // them right, and getting them wrong is the classic way a "valid" font is rejected by a strict one.
+    const entrySelector = Math.floor(Math.log2(numTables));
+    const searchRange = 2 ** entrySelector * 16;
+    view.setUint32(0, flavor);
+    view.setUint16(4, numTables);
+    view.setUint16(6, searchRange);
+    view.setUint16(8, entrySelector);
+    view.setUint16(10, numTables * 16 - searchRange);
+    let dir = 12;
+    let body = 12 + dirSize;
+    entries.forEach((e, i) => {
+        const data = tables[i];
+        view.setUint32(dir, e.tag);
+        view.setUint32(dir + 4, e.checksum);
+        view.setUint32(dir + 8, body);
+        view.setUint32(dir + 12, data.length); // the DECLARED length excludes the padding
+        out.set(data, body);
+        dir += 16;
+        body += padded(data.length);
+    });
+    return out;
+}

package/dist/validators/element-validator.d.ts

@@ -1,5 +1,5 @@
-import { PDFDocumentElement } from "../elements/pdf-document-element";
-import { PDFElement, FlexiblePDFElement, SizedPDFElement } from "../elements/pdf-element";
+import { PDFDocumentElement } from "../elements/pdf-document-element.js";
+import { PDFElement, FlexiblePDFElement, SizedPDFElement } from "../elements/pdf-element.js";
 export declare class Validator {
     static validateDocument(document: PDFDocumentElement): void;
     static validateElement(element: PDFElement): void;

package/dist/validators/element-validator.js

@@ -1,14 +1,11 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Validator = void 0;
-const pdf_document_element_1 = require("../elements/pdf-document-element");
-const pdf_element_1 = require("../elements/pdf-element");
-class Validator {
+import { PDFDocumentElement } from "../elements/pdf-document-element.js";
+import { FlexiblePDFElement, hasChildProp, SizedPDFElement, } from "../elements/pdf-element.js";
+export class Validator {
     static validateDocument(document) {
         // More validation will be added later...
         document.getProps().children.forEach((page) => {
             page.getProps().children.forEach((element) => {
-                if (element instanceof pdf_document_element_1.PDFDocumentElement) {
+                if (element instanceof PDFDocumentElement) {
                     throw new Error("PDFDocument cannot be nested inside another element.");
                 }
             });
@@ -16,46 +13,54 @@ class Validator {
     }
     static validateElement(element) {
         // Structural validation
-        if (element instanceof pdf_document_element_1.PDFDocumentElement) {
+        if (element instanceof PDFDocumentElement) {
             throw new Error("PDFDocument cannot be nested inside another element.");
         }
         // Layout validation: geometry comes from the typed getSize(), not the props bag.
-        if (element instanceof pdf_element_1.SizedPDFElement) {
-            const { x, y, width, height } = element.getSize();
-            if (x < 0 || y < 0) {
-                throw new Error(`Element ${element.constructor.name} has invalid coordinates (x: ${x}, y: ${y})`);
-            }
-            // 0 is legitimate (a hairline divider, an empty spacer); only a NEGATIVE size is invalid.
+        if (element instanceof SizedPDFElement) {
+            const { width, height } = element.getSize();
+            // Negative coordinates are allowed: a `Positioned` child overflows its frame on purpose,
+            // and the page clips anything past its edge. 0 size is legitimate (a hairline divider, an
+            // empty spacer); only a NEGATIVE size is invalid.
             if ((width !== undefined && width < 0) || (height !== undefined && height < 0)) {
                 throw new Error(`Element ${element.constructor.name} has invalid size (width: ${width}, height: ${height})`);
             }
         }
         // Logical validation: Flexible and fixed elements
-        if (element instanceof pdf_element_1.FlexiblePDFElement) {
+        if (element instanceof FlexiblePDFElement) {
             this.validateFlexElement(element);
         }
     }
     static validateSizedElement(element) {
-        const { x, y, width, height } = element.getSize();
-        if (x < 0 || y < 0) {
-            throw new Error(`Element ${element.constructor.name} has invalid coordinates (x: ${x}, y: ${y})`);
-        }
-        // A size must be set, but 0 is legitimate (a hairline divider); only NEGATIVE is invalid.
+        const { width, height } = element.getSize();
+        // Negative coordinates are legitimate: a `Positioned` child overflows its frame on purpose
+        // (a corner badge), and the page clips anything off its edge. A size must be set, but 0 is
+        // legitimate (a hairline divider); only a NEGATIVE size is invalid.
         if (width === undefined || height === undefined || width < 0 || height < 0) {
             throw new Error(`Element ${element.constructor.name} has invalid size (width: ${width}, height: ${height})`);
         }
     }
     static validateFlexElement(element) {
-        // Ensure flexible elements have valid flex values
-        if (element.getFlex() <= 0) {
-            throw new Error(`Flexible element ${element.constructor.name} has invalid flex value`);
+        // Ensure flexible elements have valid flex values. The message names what the CALLER wrote, not the
+        // element class: `Spacer` and `Expanded` are what exists in their document, `ExpandedElement` is not.
+        const flex = element.getFlex();
+        // `flex: 0` used to be meaningless - claiming no share is what leaving the element out does. With a
+        // `flexBasis` it is not: the child is then exactly its basis, a fixed slot that still participates
+        // in the line. So the rule now reads "claim SOMETHING": a share, a basis, or both.
+        // A percentage basis resolves to 0 on an unbounded axis, so it is measured against a finite
+        // reference instead - otherwise `flexBasis: "0%"` would claim nothing and still pass.
+        const claimsSpace = element.getBasis(Infinity) > 0 || element.getBasis(1) > 0;
+        if (flex < 0 || (flex === 0 && !claimsSpace)) {
+            throw new Error(`@jasy/pdf: Spacer/Expanded needs a flex above 0, got ${flex}. Flex is a SHARE of the leftover ` +
+                "space, so 0 would claim none - which is what leaving the element out does. For a fixed gap " +
+                "use the `gap` of the surrounding Column or Row, or a Box with a height. (A `flexBasis` " +
+                "makes `flex: 0` meaningful: the child is then exactly its basis.)");
         }
         // Ensure a flexible element does not contain another flexible element
-        if ((0, pdf_element_1.hasChildProp)(element)) {
-            if (element.child instanceof pdf_element_1.FlexiblePDFElement) {
+        if (hasChildProp(element)) {
+            if (element.child instanceof FlexiblePDFElement) {
                 throw new Error(`Flexible element ${element.constructor.name} cannot hold another flexible element`);
             }
         }
     }
 }
-exports.Validator = Validator;

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@jasy/pdf",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.11",
   "description": "Declarative, component-based PDF generation in pure TypeScript - Flutter-style components, real AFM font metrics, a hand-rolled PDF writer. No headless browser, no Java.",
   "keywords": [
     "declarative",
+    "e-invoice",
     "factur-x",
     "invoice",
     "layout",
@@ -12,6 +13,7 @@
     "pdf-a",
     "pdf-generation",
     "typescript",
+    "xrechnung",
     "zugferd"
   ],
   "license": "MIT",
@@ -19,9 +21,27 @@
   "files": [
     "dist"
   ],
+  "type": "module",
   "main": "dist/index.js",
+  "browser": {
+    "./dist/platform/node-fs.js": "./dist/platform/browser-fs.js",
+    "./dist/platform/node-image.js": "./dist/platform/browser-image.js"
+  },
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./edit": {
+      "types": "./dist/edit/index.d.ts",
+      "default": "./dist/edit/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "dependencies": {
+    "bidi-js": "^1.0.3",
+    "fflate": "^0.8.3",
     "jimp": "^1.6.0"
   },
   "devDependencies": {
@@ -41,7 +61,7 @@
     "play": "pnpm --filter @jasy/playground play",
     "test": "vitest",
     "test:coverage": "vitest --coverage",
-    "build": "tsc && pnpm run copy-assets",
+    "build": "tsc && node scripts/fix-dts-ext.mjs && pnpm run copy-assets",
     "lint": "oxlint",
     "lint:fix": "oxlint --fix",
     "fmt": "oxfmt",