@jasy/pdf 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/utils/pdf-object-manager.js

@@ -5,12 +5,15 @@ import { zlibSync } from "fflate";
 import { bytesFromLatin1, latin1FromBytes } from "./bytes.js";
 import { AFMParser } from "./afm-parser.js";
 import { mergeSpans, TTFParser } from "./ttf-parser.js";
+import { isWoff, woffToSfnt } from "./woff.js";
 import { subsetTTF } from "./ttf-subsetter.js";
-import { getArrayBuffer } from "./utf8-to-windows1252-encoder.js";
+import { shapeRun } from "../text/shape.js";
+import { getArrayBuffer, isWindows1252 } from "./utf8-to-windows1252-encoder.js";
 import { isEmojiCodePoint } from "../text/emoji-codepoints.js";
 import { StructTree } from "./struct-tree.js";
 import { OutlineBuilder } from "./outline.js";
 import { DestRegistry } from "./dest-registry.js";
+import { AcroFormCollector } from "../forms/acroform.js";
 // Enums come from the leaf config module (never in a cycle); the config type is
 // erased at runtime so it can come from the cyclic module safely.
 import { ColorMode, Orientation } from "../renderer/pdf-config.js";
@@ -134,6 +137,9 @@ export class PDFObjectManager {
     get dests() {
         return this._dests;
     }
+    get acroform() {
+        return this._acroform;
+    }
     constructor(pageSize) {
         this.objects = [];
         this.objectPositions = [];
@@ -157,6 +163,11 @@ export class PDFObjectManager {
         // Per-registered face: the reserved font-object numbers + the glyph ids actually used. The font
         // program is subsetted and the objects filled in by finalizeCustomFonts(), after the render pass.
         this.customFontEmit = new Map();
+        // Shaped runs, keyed by font + text; `null` means "asked, and there was nothing to shape".
+        this.shapeCache = new Map();
+        // Per font, glyph -> the code points it stands for. A shaped glyph is often absent from the cmap (a
+        // ligature) or maps back to a presentation form, so `ToUnicode` cannot come from the cmap alone.
+        this.shapedOrigins = new Map();
         // Embedded file attachments (their /Filespec object numbers + display names). Referenced from
         // the catalog's /Names/EmbeddedFiles + /AF. Drives ZUGFeRD's embedded factur-x.xml.
         this.attachments = [];
@@ -167,6 +178,7 @@ export class PDFObjectManager {
         this.compress = false;
         this.overflowPolicy = "error";
         this.encJobs = [];
+        this.strJobs = [];
         // Accessible (PDF/UA) tagging, off by default (byte-identical output); the API turns it on.
         this._struct = new StructTree();
         // Document outline (bookmarks). Empty unless a `Bookmark` was placed; then finalize() emits /Outlines.
@@ -174,6 +186,9 @@ export class PDFObjectManager {
         // Named destinations (internal-link jump targets). Empty unless an `Anchor` was placed; then it emits
         // a /Names /Dests tree.
         this._dests = new DestRegistry();
+        // Interactive form fields (AcroForm). Empty unless a form field was placed; then finalize() emits the
+        // catalog /AcroForm dict and each field's widget lands in its page /Annots.
+        this._acroform = new AcroFormCollector();
         // Whether to kern. Document-level: measuring (via `runAdvance`, which reads this off the metrics)
         // and drawing (the backend emits a `TJ`) both consult it, so they can never disagree. OFF while the
         // embedded-font path (kern/GPOS) is unbuilt - a standard-14-only kerning would set the 14 system
@@ -213,6 +228,32 @@ export class PDFObjectManager {
     encToken(id) {
         return `
JENC:${id}
`;
     }
+    // The same trick for a literal STRING. A separate marker because the two are swapped differently: a
+    // stream keeps its delimiters and only the payload changes, a string is replaced whole by a hex one.
+    strToken(id) {
+        return `\x00\x02JSTR:${id}\x02\x00`;
+    }
+    /**
+     * The single choke-point every literal string in an OBJECT goes through - a field's `/T` and `/V`, a
+     * bookmark `/Title`, a link `/URI`, an `/Alt` text, a destination name.
+     *
+     * Without a security handler this is the escaped literal we have always written, so output stays
+     * byte-identical. With one, the raw bytes are registered for the finalize pass and a placeholder takes
+     * their place: ISO 32000-1 7.6.2 requires ALL strings and streams to be encrypted, and the ones missed
+     * here were exactly the values a password is supposed to protect (ISSUE-7).
+     *
+     * A string INSIDE a content stream needs none of this - the stream is enciphered as a whole.
+     */
+    pdfString(text) {
+        if (!this.security) {
+            return `(${text.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)")})`;
+        }
+        // Encrypt the bytes the unencrypted path would have written, so a viewer decrypts to the same value.
+        // No escaping is applied: the result is emitted as a HEX string, which has no escapes to get wrong.
+        const bytes = new Uint8Array(getArrayBuffer(text));
+        const id = this.strJobs.push(bytes) - 1;
+        return this.strToken(id);
+    }
     // The single encryption choke-point every stream emitter routes through (stream(), registerImage). Without
     // a security handler: the bytes as a latin1 string + their length. With one: register the raw bytes for the
     // finalize pass and return a placeholder + the pre-computable encrypted length (16-byte IV + PKCS#7 padding).
@@ -246,6 +287,14 @@ export class PDFObjectManager {
     addContentStream(content) {
         return this.addObject(this.stream("", new Uint8Array(getArrayBuffer(content))));
     }
+    // A Form XObject: a self-contained content stream with its own /BBox (+ optional /Resources). Used for
+    // form-field appearance streams (/AP). Routes through the same choke-point as page content, so
+    // compression and encryption apply. Returns the object number.
+    addFormXObject(bbox, content, resources) {
+        const dict = `/Type /XObject /Subtype /Form /BBox ${bbox}` +
+            (resources ? ` /Resources << ${resources} >>` : "");
+        return this.addObject(this.stream(dict, new Uint8Array(getArrayBuffer(content))));
+    }
     changePDFConfig(config) {
         this.pdfConfig = { ...this.pdfConfig, ...config };
     }
@@ -327,9 +376,8 @@ endstream`;
     attachFile(name, data, opts = {}) {
         const subtype = (opts.mimeType ?? "application/octet-stream").replace(/\//g, "#2F");
         const embedded = this.addObject(this.stream(`/Type /EmbeddedFile /Subtype /${subtype} /Params << /Size ${data.length} >>`, data));
-        const escaped = (s) => s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
-        const desc = opts.description ? ` /Desc (${escaped(opts.description)})` : "";
-        const filespec = this.addObject(`<< /Type /Filespec /F (${escaped(name)}) /UF (${escaped(name)}) ` +
+        const desc = opts.description ? ` /Desc ${this.pdfString(opts.description)}` : "";
+        const filespec = this.addObject(`<< /Type /Filespec /F ${this.pdfString(name)} /UF ${this.pdfString(name)} ` +
             `/AFRelationship /${opts.relationship ?? "Unspecified"}${desc} ` +
             `/EF << /F ${embedded} 0 R /UF ${embedded} 0 R >> >>`);
         this.attachments.push({ name, filespec });
@@ -350,8 +398,8 @@ endstream`;
     setOutputIntent(icc, opts = {}) {
         const profile = this.addObject(this.stream("/N 3", icc));
         this.outputIntent = this.addObject(`<< /Type /OutputIntent /S /GTS_PDFA1 ` +
-            `/OutputConditionIdentifier (${opts.identifier ?? "sRGB"}) ` +
-            `/Info (${opts.info ?? "sRGB IEC61966-2.1"}) /DestOutputProfile ${profile} 0 R >>`);
+            `/OutputConditionIdentifier ${this.pdfString(opts.identifier ?? "sRGB")} ` +
+            `/Info ${this.pdfString(opts.info ?? "sRGB IEC61966-2.1")} /DestOutputProfile ${profile} 0 R >>`);
     }
     getOutputIntent() {
         return this.outputIntent;
@@ -399,6 +447,18 @@ endstream`;
             if (idx >= 0)
                 this.objects[idx] = this.objects[idx].replace(token, () => ciphertext);
         }
+        // Strings: the same idea, but a string is replaced WHOLE - `(text)` becomes `<ciphertext>`. Hex,
+        // because the ciphertext is binary and a hex string has no escape rules to get wrong.
+        for (let id = 0; id < this.strJobs.length; id++) {
+            const cipher = await this.security.encrypt(this.strJobs[id]);
+            const hex = Array.from(cipher, (b) => b.toString(16).padStart(2, "0").toUpperCase()).join("");
+            const token = this.strToken(id);
+            const idx = this.objects.findIndex((o) => o.includes(token));
+            if (idx >= 0)
+                this.objects[idx] = this.objects[idx].replace(token, () => `<${hex}>`);
+        }
+        // Added LAST on purpose: the /Encrypt dictionary's own strings must stay in the clear (7.6.2), and
+        // they would otherwise be swept up by the pass above.
         this.encryptObjNum = this.addObject(`<< ${this.security.encryptDict()} >>`);
     }
     // Registers (or reuses) a transparency graphics state and returns its resource name
@@ -505,7 +565,10 @@ endstream`;
         }
         if (byStyle.has(style))
             return;
-        byStyle.set(style, new TTFParser(data));
+        // A WOFF is the same sfnt behind a small wrapper, so it is unpacked HERE - the one place every
+        // font path meets (a file, raw bytes, a URL, a browser upload) - and TTFParser never learns a
+        // second container format.
+        byStyle.set(style, new TTFParser(isWoff(data) ? woffToSfnt(data) : data));
         this.verticalsCache.delete(name); // this family now answers from the .ttf, not from an AFM
         this.decorationCache.delete(name);
         // Emission (the PDF font objects + page resource) is DEFERRED to first use via ensureEmitted(),
@@ -542,13 +605,13 @@ endstream`;
     // Fills the reserved font objects with a SUBSET of each font (only the glyphs the document used),
     // tagged "ABCDEF+" as PDF/A requires for subsets. Call once, after the render pass, before output.
     finalizeCustomFonts() {
-        for (const e of this.customFontEmit.values()) {
+        for (const [key, e] of this.customFontEmit) {
             const ttf = e.ttf;
             const base = `${this.subsetTag(e.pdfName, e.used)}+${e.pdfName}`;
             this.replaceObject(e.fontFile, this.buildFontFile2(ttf, e.used));
             this.replaceObject(e.descriptor, this.buildFontDescriptor(base, ttf, e.fontFile));
             this.replaceObject(e.cidFont, this.buildCIDFont(base, ttf, e.descriptor, e.used));
-            this.replaceObject(e.toUnicode, this.buildToUnicode(ttf, e.used));
+            this.replaceObject(e.toUnicode, this.buildToUnicode(ttf, e.used, this.shapedOrigins.get(key)));
             this.replaceObject(e.type0, this.buildType0(base, e.cidFont, e.toUnicode));
         }
     }
@@ -620,6 +683,17 @@ endstream`;
         return this.emojiImage;
     }
     // Whether `ttf` has a COLOR glyph for a code point (i.e. it would render it as color emoji).
+    /**
+     * Whether a family can draw this code point at all. An embedded face answers from its `cmap`; a
+     * standard-14 one can only draw what Windows-1252 encodes, which is what its `/Widths` array covers.
+     * Used to pick a family out of a fallback stack, per code point.
+     */
+    hasGlyph(codePoint, fontFamily, fontStyle = FontStyle.Normal) {
+        const ttf = this.getCustomFont(fontFamily, fontStyle);
+        if (ttf)
+            return ttf.getGlyphIndex(codePoint) !== 0;
+        return isWindows1252(codePoint);
+    }
     colorRenders(ttf, codePoint) {
         return ttf.getColorGlyph(ttf.getGlyphIndex(codePoint)) !== null;
     }
@@ -632,6 +706,53 @@ endstream`;
         this.ensureEmitted(name, resolved);
         return this.fonts.getFont(name, resolved);
     }
+    /** How many glyphs a run draws - its code-point count unless a ligature merged some. `letterSpacing`
+     *  is per glyph (`Tc`), so this is what it multiplies. */
+    shapedGlyphCount(text, fontFamily, fontStyle) {
+        return this.shapeText(text, fontFamily, fontStyle)?.length;
+    }
+    /**
+     * The shaped glyphs of a run, or undefined when nothing needed shaping. The ONE place shaping is
+     * decided, so measuring and drawing cannot disagree. Memoised: a paragraph is measured several
+     * times (layout, pagination, drawing).
+     */
+    shapeText(text, fontFamily, fontStyle = FontStyle.Normal) {
+        const resolved = this.resolveCustomStyle(fontFamily, fontStyle);
+        if (!resolved)
+            return undefined;
+        const key = `${this.customKey(fontFamily, resolved)}\u0000${text}`;
+        const cached = this.shapeCache.get(key);
+        if (cached !== undefined)
+            return cached ?? undefined;
+        const ttf = this.customFonts.get(fontFamily).get(resolved);
+        const shaped = shapeRun([...text].map((c) => c.codePointAt(0)), ttf) ?? null;
+        this.shapeCache.set(key, shaped);
+        if (shaped) {
+            // Recorded at shaping time - the only moment the glyph and its code points are known together.
+            const fontKey = this.customKey(fontFamily, resolved);
+            let origins = this.shapedOrigins.get(fontKey);
+            if (!origins)
+                this.shapedOrigins.set(fontKey, (origins = new Map()));
+            for (const g of shaped)
+                origins.set(g.glyph, g.codePoints);
+        }
+        return shaped ?? undefined;
+    }
+    /** Hex Identity-H for glyphs the producer already resolved (a shaped run), which cannot be given as
+     *  text. Recording each keeps it in the subset. */
+    registerGlyphs(name, glyphs, style = FontStyle.Normal) {
+        const resolved = this.resolveCustomStyle(name, style);
+        if (!resolved)
+            return "";
+        this.ensureEmitted(name, resolved);
+        const emit = this.customFontEmit.get(this.customKey(name, resolved));
+        let out = "";
+        for (const g of glyphs) {
+            emit.used.add(g);
+            out += g.toString(16).padStart(4, "0").toUpperCase();
+        }
+        return out;
+    }
     // Encodes text as a hex Identity-H string for an embedded font's Tj operator: each codepoint
     // becomes its 2-byte glyph id (CID == GID under /CIDToGIDMap /Identity).
     encodeCustomText(name, text, style = FontStyle.Normal) {
@@ -642,11 +763,22 @@ endstream`;
         // Once per text run, not per character: the flat key is fine here.
         const emit = this.customFontEmit.get(this.customKey(name, resolved));
         const { ttf, used } = emit;
+        const hex4 = (gid) => gid.toString(16).padStart(4, "0").toUpperCase();
+        // The SAME shaped run the measuring path used, so the glyphs drawn are the glyphs measured.
+        const shaped = this.shapeText(text, name, style);
+        if (shaped) {
+            let out = "";
+            for (const g of shaped) {
+                used.add(g.glyph);
+                out += hex4(g.glyph);
+            }
+            return out;
+        }
         let hex = "";
         for (const ch of text) {
             const gid = ttf.getGlyphIndex(ch.codePointAt(0));
             used.add(gid); // record the glyph so the subset keeps it
-            hex += gid.toString(16).padStart(4, "0").toUpperCase();
+            hex += hex4(gid);
         }
         return hex;
     }
@@ -673,23 +805,30 @@ endstream`;
             .map((g) => `${g} [${all[g] ?? 1000}]`)
             .join(" ");
         return (`<< /Type /Font /Subtype /CIDFontType2 /BaseFont /${pdfName(name)} ` +
-            `/CIDSystemInfo << /Registry (Adobe) /Ordering (Identity) /Supplement 0 >> ` +
+            `/CIDSystemInfo << /Registry ${this.pdfString("Adobe")} /Ordering ${this.pdfString("Identity")} /Supplement 0 >> ` +
             `/FontDescriptor ${descriptor} 0 R /CIDToGIDMap /Identity ` +
             `/DW 1000 /W [${w}] >>`);
     }
     // Maps glyph id -> Unicode so the text stays copy-/searchable (rendering doesn't need it). Only
     // the used glyphs are listed, to match the subset.
-    buildToUnicode(ttf, used) {
+    buildToUnicode(ttf, used, shapedOrigins = new Map()) {
         const hex4 = (n) => n.toString(16).padStart(4, "0").toUpperCase();
+        // A code point above the BMP needs its surrogate PAIR here - a `bfchar` destination is UTF-16BE.
+        const utf16 = (code) => code > 0xffff
+            ? hex4(0xd800 + ((code - 0x10000) >> 10)) + hex4(0xdc00 + ((code - 0x10000) & 0x3ff))
+            : hex4(code);
         const rev = ttf.reverseCmap();
+        // A SHAPED glyph wins: it is often absent from the cmap (a ligature) or maps back to a
+        // presentation form rather than the letter that was written (a joining form), so the reverse
+        // cmap alone would make copied text wrong.
         const entries = [...used]
             .sort((a, b) => a - b)
-            .filter((g) => rev.has(g))
-            .map((g) => [g, rev.get(g)]);
+            .filter((g) => shapedOrigins.has(g) || rev.has(g))
+            .map((g) => [g, shapedOrigins.get(g) ?? [rev.get(g)]]);
         const blocks = [];
         for (let i = 0; i < entries.length; i += 100) {
             const block = entries.slice(i, i + 100);
-            const lines = block.map(([gid, code]) => `<${hex4(gid)}> <${hex4(code)}>`);
+            const lines = block.map(([gid, codes]) => `<${hex4(gid)}> <${codes.map(utf16).join("")}>`);
             blocks.push(`${block.length} beginbfchar\n${lines.join("\n")}\nendbfchar`);
         }
         const body = `/CIDInit /ProcSet findresource begin\n12 dict begin\nbegincmap\n` +
@@ -765,6 +904,11 @@ endstream`;
         const chars = [...text];
         if (chars.length < 2)
             return [];
+        // A shaped run does not kern here: these pairs are keyed by the UNSHAPED glyphs, and the `TJ`
+        // path would re-shape each chunk on its own, turning every letter isolated. Arabic kerning is in
+        // GPOS, applied during shaping - not built (`todo.md`).
+        if (this.shapeText(text, fontFamily, fontStyle))
+            return [];
         const out = [];
         // An embedded font kerns by GLYPH id (kern table / GPOS); a standard-14 one by character (AFM).
         const ttf = this.getCustomFont(fontFamily, fontStyle);
@@ -816,6 +960,13 @@ endstream`;
     }
     // Returns the current width of a text, included kernings
     getStringWidth(text, fontFamily, fontSize, fontStyle) {
+        // Shaping first: a joined run is narrower than the same letters apart, so measuring the unshaped
+        // form while drawing the shaped one would break every line. Both sides ask `shapeText`.
+        const shaped = this.shapeText(text, fontFamily, fontStyle);
+        if (shaped) {
+            const ttf = this.getCustomFont(fontFamily, fontStyle);
+            return shaped.reduce((w, g) => w + ttf.unitsToPoints(g.advance, fontSize), 0);
+        }
         let width = 0;
         // Iterate code points, not UTF-16 units: an astral char (emoji, CJK-ext) is a surrogate pair,
         // and indexing by unit would measure each half as its own (zero-width) "char". The spread splits

package/dist/utils/struct-tree.js

@@ -1,5 +1,4 @@
 // Escapes a PDF literal string ( ... ) - the language tag is safe ASCII, but /Alt can carry arbitrary text.
-const esc = (s) => s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
 // A structure role reaches the PDF as a raw name (/H1, /S /Table). Roles come from a controlled set,
 // but restrict them to a safe PDF-name token anyway (defence-in-depth) so a stray "/", whitespace, or
 // operator can never corrupt the content stream / object dictionary. Empty after stripping -> /Span.
@@ -90,7 +89,7 @@ export class StructTree {
                 ...childrenOf(e.key).map((c) => `${objNum.get(c.key)} 0 R`),
                 ...e.mc.map((m) => `<< /Type /MCR /Pg ${pg(m.structParents)} 0 R /MCID ${m.mcid} >>`),
             ].join(" ");
-            const alt = e.alt ? ` /Alt (${esc(e.alt)})` : "";
+            const alt = e.alt ? ` /Alt ${om.pdfString(e.alt)}` : "";
             // PDF/UA 7.5: a header cell needs a Scope so a reader can associate data cells with it. Our headers
             // are a header ROW (the Table `header` option), so each TH is the head of its Column.
             const attr = e.role === "TH" ? " /A << /O /Table /Scope /Column >>" : "";
@@ -125,6 +124,6 @@ export class StructTree {
         om.replaceObject(parentTreeNum, `<< /Nums [ ${nums.join(" ")} ] >>`);
         om.replaceObject(rootNum, `<< /Type /StructTreeRoot /K ${docNum} 0 R /ParentTree ${parentTreeNum} 0 R ` +
             `/ParentTreeNextKey ${this.structParentsCounter} >>`);
-        return `/MarkInfo << /Marked true >> /StructTreeRoot ${rootNum} 0 R /Lang (${esc(this.lang)})`;
+        return `/MarkInfo << /Marked true >> /StructTreeRoot ${rootNum} 0 R /Lang ${om.pdfString(this.lang)}`;
     }
 }

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

@@ -1,4 +1,5 @@
 import type { FontDecoration } from "../text/text-decoration.js";
+import { GsubTable } from "./gsub.js";
 export type GlyphPathCommand = {
     type: "M";
     x: number;
@@ -77,14 +78,19 @@ export declare class TTFParser {
     private kernPairs;
     private hasKerning;
     private gposPairPos;
+    private gsubTable?;
     constructor(data: Uint8Array);
     getData(): Uint8Array;
     glyphCount(): number;
     glyphWidths(): number[];
     reverseCmap(): Map<number, number>;
     private toGlyphSpace;
+    /** The font's `GSUB`, or undefined when it has none. Parsed once, on demand. */
+    gsub(): GsubTable | undefined;
     getGlyphIndex(codePoint: number): number;
     getAdvanceWidth(glyphIndex: number): number;
+    /** Font units -> points at `fontSize`; the one scaling rule for shaped and plain advances alike. */
+    unitsToPoints(units: number, fontSize: number): number;
     getCharWidth(char: string, fontSize: number): number;
     getStringWidth(text: string, fontSize: number): number;
     private readDecorationMetrics;

package/dist/utils/ttf-parser.js

@@ -2,6 +2,7 @@
 // Slice 1: glyph advance widths (hmtx) + the Unicode→glyph map (cmap), enough to compute
 // text width the same way AFMParser does for the standard-14. Embedding/subsetting come later.
 import { i16, latin1FromBytes, u8, u16, u32 } from "./bytes.js";
+import { GsubTable } from "./gsub.js";
 const IDENTITY = [1, 0, 0, 1, 0, 0];
 /** Sorts x-intervals and unions the overlapping ones. */
 export function mergeSpans(spans) {
@@ -151,6 +152,20 @@ export class TTFParser {
     toGlyphSpace(v) {
         return Math.round((v * 1000) / this.unitsPerEm);
     }
+    /** The font's `GSUB`, or undefined when it has none. Parsed once, on demand. */
+    gsub() {
+        if (this.gsubTable === undefined) {
+            const record = this.tables["GSUB"];
+            // Degrade to "no shaping" rather than break font loading - same rule as kern.
+            try {
+                this.gsubTable = record ? new GsubTable(this.data, record.offset) : null;
+            }
+            catch {
+                this.gsubTable = null;
+            }
+        }
+        return this.gsubTable ?? undefined;
+    }
     // Codepoint → glyph id (0 = .notdef when the font has no glyph for it).
     getGlyphIndex(codePoint) {
         const g = this.cmap.get(codePoint);
@@ -169,6 +184,10 @@ export class TTFParser {
         return this.advanceWidths[i] ?? 0;
     }
     // Char width at fontSize, scaled from font units (em = unitsPerEm) to points.
+    /** Font units -> points at `fontSize`; the one scaling rule for shaped and plain advances alike. */
+    unitsToPoints(units, fontSize) {
+        return (units / this.unitsPerEm) * fontSize;
+    }
     getCharWidth(char, fontSize) {
         const units = this.getAdvanceWidth(this.getGlyphIndex(char.codePointAt(0)));
         return (units / this.unitsPerEm) * fontSize;

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

@@ -33,6 +33,16 @@ 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). */
 export function getArrayBuffer(data) {
     const u8 = new Uint8Array(data.length);

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.js

@@ -41,9 +41,20 @@ export class Validator {
         }
     }
     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 (hasChildProp(element)) {

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@jasy/pdf",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.9",
   "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",
@@ -30,9 +32,15 @@
     ".": {
       "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"
   },