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

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

@@ -5,8 +5,10 @@ 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";
@@ -161,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 = [];
@@ -558,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(),
@@ -595,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));
         }
     }
@@ -673,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;
     }
@@ -685,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) {
@@ -695,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;
     }
@@ -732,17 +811,24 @@ endstream`;
     }
     // 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` +
@@ -818,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);
@@ -869,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/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

@@ -44,10 +44,17 @@ export class Validator {
         // 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();
-        if (flex <= 0) {
+        // `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.");
+                "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,6 +1,6 @@
 {
   "name": "@jasy/pdf",
-  "version": "1.0.0-alpha.8",
+  "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",
@@ -40,6 +40,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "bidi-js": "^1.0.3",
     "fflate": "^0.8.3",
     "jimp": "^1.6.0"
   },