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

package/dist/utils/flex-layout.js

@@ -1,20 +1,19 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FlexLayoutHelper = exports.HORIZONTAL_AXIS = exports.VERTICAL_AXIS = void 0;
-const pdf_element_1 = require("../elements/pdf-element");
-const box_constraints_1 = require("../layout/box-constraints");
-exports.VERTICAL_AXIS = {
+import { FlexiblePDFElement } from "../elements/pdf-element.js";
+import { BoxConstraints } from "../layout/box-constraints.js";
+export const VERTICAL_AXIS = {
+    mainHorizontal: false,
     mainOf: (s) => s.height,
     crossOf: (s) => s.width,
-    measureConstraints: (crossAvail) => box_constraints_1.BoxConstraints.loose(crossAvail, Infinity),
-    flexConstraints: (mainExtent, crossAvail) => box_constraints_1.BoxConstraints.loose(crossAvail, mainExtent),
+    measureConstraints: (crossAvail, mainMax = Infinity) => BoxConstraints.loose(crossAvail, mainMax),
+    flexConstraints: (mainExtent, crossAvail) => BoxConstraints.loose(crossAvail, mainExtent),
     offsetAt: (mainPos, crossPos) => ({ x: crossPos, y: mainPos }),
 };
-exports.HORIZONTAL_AXIS = {
+export const HORIZONTAL_AXIS = {
+    mainHorizontal: true,
     mainOf: (s) => s.width,
     crossOf: (s) => s.height,
-    measureConstraints: (crossAvail) => box_constraints_1.BoxConstraints.loose(Infinity, crossAvail),
-    flexConstraints: (mainExtent, crossAvail) => box_constraints_1.BoxConstraints.loose(mainExtent, crossAvail),
+    measureConstraints: (crossAvail, mainMax = Infinity) => BoxConstraints.loose(mainMax, crossAvail),
+    flexConstraints: (mainExtent, crossAvail) => BoxConstraints.loose(mainExtent, crossAvail),
     offsetAt: (mainPos, crossPos) => ({ x: mainPos, y: crossPos }),
 };
 /** Cross-axis offset of a child of size `childCross` within `crossExtent`. */
@@ -25,7 +24,21 @@ function crossOffset(align, crossExtent, childCross) {
         return Math.max(0, crossExtent - childCross);
     return 0; // start, stretch (stretch fills, so no offset)
 }
-class FlexLayoutHelper {
+/**
+ * The order children are LAID OUT in: by `order` (lowest first, ties keeping source order), then
+ * reversed if the container asks for it. The element tree itself is never touched, so the reading order
+ * a tagged PDF exposes stays the source order - which is what CSS says too.
+ *
+ * `sort` is stable in every engine we target, so equal `order` values keep their source positions and a
+ * container where nobody sets one comes back with the identical array.
+ */
+function inLayoutOrder(children, reverse) {
+    const ordered = children.some((c) => c.order !== 0)
+        ? [...children].sort((a, b) => a.order - b.order)
+        : children;
+    return reverse ? [...ordered].reverse() : ordered;
+}
+export class FlexLayoutHelper {
     /**
      * Lays out a flex line along `axis`, IN SOURCE ORDER, and places every child.
      * Fixed children take their natural main extent; flex (`ExpandedElement`) children
@@ -35,31 +48,188 @@ class FlexLayoutHelper {
      * extent occupied. Vertical with `gap 0`, `main start`, `cross stretch` reproduces the
      * previous Column layout exactly.
      */
+    /**
+     * Lays out the children along `axis`, on one line or several.
+     *
+     * Without `wrap` this is the single-line engine and nothing about it changed - the call goes
+     * straight through, which is what keeps every existing document byte-identical. With `wrap` the
+     * children are split into lines first and the SAME engine runs once per line.
+     */
     static layout(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx) {
-        var _a, _b, _c;
-        const gap = (_a = options.gap) !== null && _a !== void 0 ? _a : 0;
-        const main = (_b = options.main) !== null && _b !== void 0 ? _b : "start";
-        const cross = (_c = options.cross) !== null && _c !== void 0 ? _c : "stretch";
+        if (!options.wrap || children.length === 0 || !Number.isFinite(mainAvail)) {
+            // An unbounded main axis has no edge to wrap at, so wrapping there is meaningless, not an error.
+            return FlexLayoutHelper.layoutLine(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx);
+        }
+        return FlexLayoutHelper.layoutWrapped(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx);
+    }
+    /**
+     * The wrapping path: split into lines, lay each one out, then place the lines across the axis.
+     *
+     * Lines are laid out TWICE - once to learn how tall each is, once at its final cross position. That
+     * is the same measure-then-place shape the single-line engine already uses, and it is what
+     * `alignContent` needs: the block of lines can only be centred once its total is known.
+     */
+    static layoutWrapped(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx) {
+        const gap = options.gap ?? 0;
+        const ordered = inLayoutOrder(children, options.reverse ?? false);
+        // Which children share a line. A child is measured at its natural main extent; a flex child
+        // contributes its BASIS, which is 0 unless it asked for one - so it never forces a break by itself.
+        // A child's natural main extent. A PERCENTAGE child has no fixed answer: its size depends on how
+        // many gaps the line ends up with, which depends on who is on it. So it is asked again for every
+        // candidate membership below rather than measured once.
+        // A plain child's extent does not depend on the line, so it is laid out ONCE and remembered.
+        // Without this each membership probe re-lays every child already on the line - O(n^2) subtree
+        // layouts, which is expensive the moment those children hold a Table or a wrapping paragraph.
+        const measured = new Map();
+        const naturalMain = (child, base) => {
+            if (child instanceof FlexiblePDFElement)
+                return child.getBasis(base);
+            const factor = child.relativeSizeFactor(axis.mainHorizontal);
+            if (factor !== undefined)
+                return base * factor;
+            const cached = measured.get(child);
+            if (cached !== undefined)
+                return cached;
+            // Measured UNCAPPED, the same way the single-line engine measures a plain child. Handing the
+            // line width in as a cap would silently squash a child wider than the line - CSS lets such a
+            // child overflow, and so does our own non-wrapping path.
+            const needsBound = child.needsBoundedMain(axis.mainHorizontal);
+            const main = axis.mainOf(child.calculateLayout(axis.measureConstraints(crossAvail, needsBound ? mainAvail : Infinity), axis.offsetAt(mainStart, crossOrigin), ctx));
+            measured.set(child, main);
+            return main;
+        };
+        /** What a line of these children would occupy, resolving every `%` against ITS gap count. */
+        const lineExtent = (members) => {
+            const gaps = Math.max(0, members.length - 1) * gap;
+            const base = Math.max(0, mainAvail - gaps);
+            return members.reduce((n, c) => n + naturalMain(c, base), 0) + gaps;
+        };
+        const lines = [[]];
+        for (const child of ordered) {
+            const current = lines[lines.length - 1];
+            // A child wider than a whole line still gets one of its own rather than an empty line before it.
+            if (current.length > 0 && lineExtent([...current, child]) > mainAvail) {
+                lines.push([child]);
+            }
+            else {
+                current.push(child);
+            }
+        }
+        // Each line keeps SOURCE order internally: the ordering was applied above, and applying it again
+        // per line would reverse twice.
+        const lineOptions = { ...options, wrap: false, reverse: false };
+        const measure = lines.map((line) => FlexLayoutHelper.layoutLine(line, axis, mainAvail, Infinity, // let each line report the cross extent it actually needs
+        mainStart, crossOrigin, lineOptions, ctx));
+        const heights = measure.map((m) => m.crossUsed);
+        const totalCross = heights.reduce((n, h) => n + h, 0) + Math.max(0, lines.length - 1) * gap;
+        // `alignContent` distributes the BLOCK of lines across the axis, using the same vocabulary the main
+        // axis uses. Only meaningful in a bounded cross axis with room left over.
+        const slack = Number.isFinite(crossAvail) ? crossAvail - totalCross : 0;
+        const align = options.alignContent ?? "start";
+        let cursor = crossOrigin;
+        let between = gap;
+        if (slack > 0) {
+            if (align === "center")
+                cursor += slack / 2;
+            else if (align === "end")
+                cursor += slack;
+            else if (align === "between" && lines.length > 1)
+                between = gap + slack / (lines.length - 1);
+            else if (align === "around") {
+                const unit = slack / lines.length;
+                cursor += unit / 2;
+                between = gap + unit;
+            }
+        }
+        lines.forEach((line, i) => {
+            FlexLayoutHelper.layoutLine(line, axis, mainAvail, heights[i], // the line's own extent, so `stretch` fills the line and not the container
+            mainStart, cursor, lineOptions, ctx);
+            cursor += heights[i];
+            if (i < lines.length - 1)
+                cursor += between;
+        });
+        return { mainUsed: mainAvail, crossUsed: Math.max(totalCross, cursor - crossOrigin) };
+    }
+    static layoutLine(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx) {
+        const gap = options.gap ?? 0;
+        const main = options.main ?? "start";
+        const cross = options.cross ?? "stretch";
+        children = inLayoutOrder(children, options.reverse ?? false);
         const count = children.length;
+        const totalGap = Math.max(0, count - 1) * gap;
+        // The main extent a percentage child resolves against: the line's own extent minus the gaps
+        // between the items. So N children at (100/N)% + gaps fit exactly, instead of overflowing by the
+        // gaps (the flexbox `width: 33%` + gap trap). Only finite when the line's main axis is bounded -
+        // a fraction of an unbounded main axis has no meaning, so `%` children fall back to shrink-wrap.
+        const percentBase = mainAvail !== Infinity ? Math.max(0, mainAvail - totalGap) : Infinity;
+        // The main cap to hand a child: `percentBase` for a percentage child (so its fraction resolves) and
+        // for a child that cannot lay itself out without a bound (a nested stack holding an `Expanded`/
+        // `Spacer`); unbounded for everyone else, who keep their natural size and never fill the line.
+        // Filled by the shrink pass below; read by `mainCapFor` in pass 2. Declared here so the closure
+        // can see it - it is empty for every document that does not ask for shrinking.
+        const shrunkCap = new Map();
+        const mainCapFor = (child) => {
+            const target = shrunkCap.get(child);
+            if (target !== undefined)
+                return target;
+            if (percentBase === Infinity)
+                return Infinity;
+            const needsBound = child.relativeSizeFactor(axis.mainHorizontal) !== undefined ||
+                child.needsBoundedMain(axis.mainHorizontal);
+            return needsBound ? percentBase : Infinity;
+        };
         // Pass 1: measure the fixed children (main extent + cross size) and total the flex.
+        // A flex child's BASIS is reserved here too: it is main extent the leftover no longer contains,
+        // exactly like a fixed child's size. With the default basis of 0 this line adds nothing.
         let fixedMain = 0;
         let totalFlex = 0;
+        let totalBasis = 0;
         let crossUsed = 0;
         const fixedSize = new Map();
         for (const child of children) {
-            if (child instanceof pdf_element_1.FlexiblePDFElement) {
+            if (child instanceof FlexiblePDFElement) {
                 totalFlex += child.getFlex();
+                totalBasis += child.getBasis(percentBase);
             }
             else {
-                const size = child.calculateLayout(axis.measureConstraints(crossAvail), axis.offsetAt(mainStart, crossOrigin), ctx);
+                const size = child.calculateLayout(axis.measureConstraints(crossAvail, mainCapFor(child)), axis.offsetAt(mainStart, crossOrigin), ctx);
                 fixedMain += axis.mainOf(size);
                 crossUsed = Math.max(crossUsed, axis.crossOf(size));
                 fixedSize.set(child, size);
             }
         }
-        const totalGap = Math.max(0, count - 1) * gap;
-        const leftover = mainAvail - fixedMain - totalGap;
-        const remaining = Math.max(leftover, 0); // for flex children
+        // Shrinking: the line overflows and some children said they would give space back. CSS weights a
+        // shrinker's share by `shrink x its own size`, so a big item yields more than a small one - which is
+        // why this cannot reuse the grow maths above. Nobody shrinks by default, so a document that never
+        // asks for it never enters this block.
+        const shrinkers = children.filter((c) => c.flexShrink > 0 && !(c instanceof FlexiblePDFElement));
+        const overflow = fixedMain + totalBasis + totalGap - mainAvail;
+        if (shrinkers.length > 0 && Number.isFinite(mainAvail) && overflow > 0) {
+            const weight = (c) => c.flexShrink * axis.mainOf(fixedSize.get(c));
+            const totalWeight = shrinkers.reduce((n, c) => n + weight(c), 0);
+            if (totalWeight > 0) {
+                for (const child of shrinkers) {
+                    const natural = axis.mainOf(fixedSize.get(child));
+                    // Never below zero: when the GAPS alone outgrow the line, a proportional share asks for more
+                    // than a child has. No test can tell this clamp apart from its absence - `constrainWidth`
+                    // floors at 0 further down either way - but handing out a negative constraint is nonsense,
+                    // and the next reader should not have to work out that it happens to be harmless.
+                    const target = Math.max(0, natural - (weight(child) / totalWeight) * overflow);
+                    shrunkCap.set(child, target);
+                    // Re-measure NOW, not in pass 2: a narrower child may wrap to more lines, and the line's
+                    // cross extent is settled just below.
+                    const size = child.calculateLayout(axis.measureConstraints(crossAvail, target), axis.offsetAt(mainStart, crossOrigin), ctx);
+                    fixedMain += axis.mainOf(size) - natural;
+                    crossUsed = Math.max(crossUsed, axis.crossOf(size));
+                    fixedSize.set(child, size);
+                }
+            }
+        }
+        const leftover = mainAvail - fixedMain - totalBasis - totalGap;
+        // A flex child on an UNBOUNDED main axis has no leftover space to claim. It must collapse to zero,
+        // never to `Infinity`: an infinite extent would become the offset of every following sibling and get
+        // written into the content stream verbatim, silently corrupting the page from that point on.
+        const remaining = Number.isFinite(leftover) ? Math.max(leftover, 0) : 0;
         // Main-axis distribution only kicks in with no flex child and bounded, positive space.
         let leadingSpace = 0;
         let betweenSpace = gap;
@@ -80,8 +250,8 @@ class FlexLayoutHelper {
         // toward the line's cross extent - they're placed in pass 2, but crossExtent needs them now.
         if (totalFlex > 0) {
             for (const child of children) {
-                if (child instanceof pdf_element_1.FlexiblePDFElement) {
-                    const mainExtent = (child.getFlex() / totalFlex) * remaining;
+                if (child instanceof FlexiblePDFElement) {
+                    const mainExtent = child.getBasis(percentBase) + (child.getFlex() / totalFlex) * remaining;
                     const size = child.calculateLayout(axis.flexConstraints(mainExtent, crossAvail), axis.offsetAt(mainStart, crossOrigin), ctx);
                     crossUsed = Math.max(crossUsed, axis.crossOf(size));
                 }
@@ -92,20 +262,28 @@ class FlexLayoutHelper {
         // `stretch` caps a child's cross to `crossExtent` (not `crossAvail`) so siblings end up
         // equal across the axis. Bounded lines have crossExtent == crossAvail (byte-identical);
         // only an unbounded line (a shrink-wrap Row) now equalises instead of staying natural.
-        const stretch = cross === "stretch";
-        // Pass 2: place each child at the running main position, offset across by `cross`.
+        // A child may override the container with its own `alignSelf` (CSS), so the decision is per child.
+        const alignFor = (child) => child.alignSelf ?? cross;
+        // Pass 2: place each child at the running main position, offset across by its alignment.
         let mainPos = mainStart + leadingSpace;
         let placedCross = 0;
         children.forEach((child, index) => {
+            const align = alignFor(child);
+            const stretch = align === "stretch";
             let mainExtent;
-            if (child instanceof pdf_element_1.FlexiblePDFElement) {
-                mainExtent = (child.getFlex() / totalFlex) * remaining;
-                const size = child.calculateLayout(axis.flexConstraints(mainExtent, stretch ? crossExtent : crossAvail), axis.offsetAt(mainPos, crossOrigin), ctx);
+            if (child instanceof FlexiblePDFElement) {
+                mainExtent = child.getBasis(percentBase) + (child.getFlex() / totalFlex) * remaining;
+                // A flex child fills the MAIN axis, and its cross size is only known after layout - there is
+                // nothing to align against. So alignSelf is a no-op here, and that has to hold for the CROSS
+                // CONSTRAINT too: reading the per-child alignment would hand an `alignSelf: "start"` flex child
+                // an unbounded cross axis on a shrink-wrapping line, where the container's own rule gives it
+                // the line's extent. A no-op that changes the constraints is not a no-op.
+                const size = child.calculateLayout(axis.flexConstraints(mainExtent, cross === "stretch" ? crossExtent : crossAvail), axis.offsetAt(mainPos, crossOrigin), ctx);
                 placedCross = Math.max(placedCross, axis.crossOf(size));
             }
             else {
                 const childCross = axis.crossOf(fixedSize.get(child));
-                const size = child.calculateLayout(axis.measureConstraints(stretch ? crossExtent : crossAvail), axis.offsetAt(mainPos, crossOrigin + crossOffset(cross, crossExtent, childCross)), ctx);
+                const size = child.calculateLayout(axis.measureConstraints(stretch ? crossExtent : crossAvail, mainCapFor(child)), axis.offsetAt(mainPos, crossOrigin + crossOffset(align, crossExtent, childCross)), ctx);
                 mainExtent = axis.mainOf(size);
                 placedCross = Math.max(placedCross, axis.crossOf(size));
             }
@@ -116,4 +294,3 @@ class FlexLayoutHelper {
         return { mainUsed: mainPos - mainStart, crossUsed: placedCross };
     }
 }
-exports.FlexLayoutHelper = FlexLayoutHelper;

package/dist/utils/font-metrics.d.ts

@@ -1,4 +1,6 @@
-import type { FontStyle } from "./pdf-object-manager";
+import type { FontStyle } from "./pdf-object-manager.js";
+import type { FontVerticals } from "../text/line-metrics.js";
+import type { FontDecoration } from "../text/text-decoration.js";
 /**
  * Read-only font measurement - the slice of the object manager that the layout pass
  * needs. Keeping layout (and, later, fragmentation) behind this interface means those
@@ -9,4 +11,21 @@ import type { FontStyle } from "./pdf-object-manager";
 export interface FontMetrics {
     getStringWidth(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle): number;
     getCharWidth(char: string, fontSize: number, fullFontName?: string, fontName?: string, fontStyle?: FontStyle): number;
+    /** Ascent / descent / lineGap of a face, in em fractions - the vertical counterpart of the widths
+     *  above. Drives the line box and the baseline (see `text/line-metrics.ts`). */
+    getFontVerticals(fontFamily: string, fontStyle: FontStyle): FontVerticals;
+    /** Underline / strikethrough geometry of a face, in em fractions. GLYPH metrics, deliberately kept
+     *  apart from the LINE metrics above (see `text/text-decoration.ts`). */
+    getFontDecoration(fontFamily: string, fontStyle: FontStyle): FontDecoration;
+    /** Whether kerning is on for this document. `runAdvance` reads it so a measured advance matches the
+     *  drawn one (the backend emits a `TJ` under the same flag). */
+    readonly kerningEnabled: boolean;
+    /** Per-adjacent-pair kerning of `text`, in em/1000 (negative tightens); length `codePoints - 1`,
+     *  zero next to a space. Only meaningful when `kerningEnabled`. */
+    getKernPairs(text: string, fontFamily: string, fontStyle: FontStyle): number[];
+    /** Whether this family can draw the code point at all - what picks a face out of a fallback stack. */
+    hasGlyph(codePoint: number, fontFamily: string, fontStyle: FontStyle): boolean;
+    /** How many glyphs the run will DRAW, when a ligature made that differ from its code-point count.
+     *  Absent or `undefined` means "the same", which is every Latin run. */
+    shapedGlyphCount?(text: string, fontFamily?: string, fontStyle?: FontStyle): number | undefined;
 }

package/dist/utils/font-metrics.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/utils/font-path.js

@@ -1,9 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFontPath = getFontPath;
-const os = require("os");
-const path = require("path");
-function getFontPath(fontName) {
+import os from "node:os";
+import path from "node:path";
+export function getFontPath(fontName) {
     const platform = os.platform();
     let fontPath = "";
     if (platform === "win32") {

package/dist/utils/gsub.d.ts

@@ -0,0 +1,36 @@
+export declare class GsubTable {
+    private data;
+    private base;
+    private scriptList;
+    private featureList;
+    private lookupList;
+    private lookupCache;
+    private coverageCache;
+    constructor(data: Uint8Array, base: number);
+    /** Whether the font carries this script at all - `arab` is the question the shaper asks. */
+    hasScript(script: string): boolean;
+    /** A feature's lookup indices, under the script's DEFAULT language system - Arabic shaping features
+     *  are script-wide, so a language-specific override would only add typographic niceties. */
+    lookups(script: string, feature: string): number[];
+    /** Type 1: substitute one glyph. `null` when no subtable covers it - the feature does not apply. */
+    substituteSingle(lookupIndex: number, glyph: number): number | null;
+    /**
+     * Type 4: collapse a run of glyphs into one, starting at `at`. Longest match wins, as the spec
+     * requires - a three-glyph ligature beats the two-glyph one that starts the same way.
+     */
+    substituteLigature(lookupIndex: number, glyphs: readonly number[], at: number): {
+        glyph: number;
+        consumed: number;
+    } | null;
+    /** The type of a lookup, for reporting what a font needs that we do not do. */
+    lookupType(lookupIndex: number): number | undefined;
+    private scriptOffset;
+    /**
+     * Resolve a lookup, unwrapping type 7 (extension) - which exists only because the 16-bit offsets
+     * elsewhere cannot reach far enough in a big font. Callers never learn it was wrapped.
+     */
+    private lookup;
+    /** Coverage table -> glyph id to its INDEX in the table, which is how subtables address glyphs. */
+    private coverage;
+    private cacheCoverage;
+}

package/dist/utils/gsub.js

@@ -0,0 +1,178 @@
+import { u16, u32, i16, latin1FromBytes } from "./bytes.js";
+const EXTENSION = 7;
+/** A coverage table may not expand past this: a glyph id is a uint16, so no honest one can. */
+const MAX_COVERAGE_ENTRIES = 65536;
+export class GsubTable {
+    constructor(data, base) {
+        this.data = data;
+        this.base = base;
+        this.lookupCache = new Map();
+        this.coverageCache = new Map();
+        this.scriptList = base + u16(data, base + 4);
+        this.featureList = base + u16(data, base + 6);
+        this.lookupList = base + u16(data, base + 8);
+    }
+    /** Whether the font carries this script at all - `arab` is the question the shaper asks. */
+    hasScript(script) {
+        return this.scriptOffset(script) !== undefined;
+    }
+    /** A feature's lookup indices, under the script's DEFAULT language system - Arabic shaping features
+     *  are script-wide, so a language-specific override would only add typographic niceties. */
+    lookups(script, feature) {
+        const scriptOff = this.scriptOffset(script);
+        if (scriptOff === undefined)
+            return [];
+        // The default LangSys is optional; fall back to the first named one - a font declaring only
+        // `ARA ` still shapes Arabic.
+        const defaultOff = u16(this.data, scriptOff);
+        const langSys = defaultOff !== 0
+            ? scriptOff + defaultOff
+            : u16(this.data, scriptOff + 2) > 0
+                ? // The first LangSysRecord is at +4 and is tag(4) + offset(2), so its offset is at +8.
+                    scriptOff + u16(this.data, scriptOff + 8)
+                : undefined;
+        if (langSys === undefined)
+            return [];
+        const out = [];
+        const count = u16(this.data, langSys + 4);
+        for (let i = 0; i < count; i++) {
+            const featureIndex = u16(this.data, langSys + 6 + i * 2);
+            const record = this.featureList + 2 + featureIndex * 6;
+            if (latin1FromBytes(this.data.subarray(record, record + 4)) !== feature)
+                continue;
+            const featureOff = this.featureList + u16(this.data, record + 4);
+            const lookupCount = u16(this.data, featureOff + 2);
+            for (let j = 0; j < lookupCount; j++)
+                out.push(u16(this.data, featureOff + 4 + j * 2));
+        }
+        return out;
+    }
+    /** Type 1: substitute one glyph. `null` when no subtable covers it - the feature does not apply. */
+    substituteSingle(lookupIndex, glyph) {
+        const lookup = this.lookup(lookupIndex);
+        if (!lookup || lookup.type !== 1)
+            return null;
+        for (const sub of lookup.subtables) {
+            const coverage = this.coverage(sub + u16(this.data, sub + 2));
+            const index = coverage.get(glyph);
+            if (index === undefined)
+                continue;
+            // Format 1 shifts every covered glyph by one delta; format 2 lists a replacement per glyph.
+            return u16(this.data, sub) === 1
+                ? (glyph + i16(this.data, sub + 4)) & 0xffff
+                : u16(this.data, sub + 6 + index * 2);
+        }
+        return null;
+    }
+    /**
+     * Type 4: collapse a run of glyphs into one, starting at `at`. Longest match wins, as the spec
+     * requires - a three-glyph ligature beats the two-glyph one that starts the same way.
+     */
+    substituteLigature(lookupIndex, glyphs, at) {
+        const lookup = this.lookup(lookupIndex);
+        if (!lookup || lookup.type !== 4)
+            return null;
+        let best = null;
+        for (const sub of lookup.subtables) {
+            const coverage = this.coverage(sub + u16(this.data, sub + 2));
+            const setIndex = coverage.get(glyphs[at]);
+            if (setIndex === undefined)
+                continue;
+            const set = sub + u16(this.data, sub + 6 + setIndex * 2);
+            const ligatureCount = u16(this.data, set);
+            for (let i = 0; i < ligatureCount; i++) {
+                const lig = set + u16(this.data, set + 2 + i * 2);
+                const components = u16(this.data, lig + 2); // includes the glyph coverage already matched
+                if (at + components > glyphs.length)
+                    continue;
+                let matches = true;
+                for (let c = 1; c < components && matches; c++) {
+                    matches = glyphs[at + c] === u16(this.data, lig + 2 + c * 2);
+                }
+                if (matches && (best === null || components > best.consumed)) {
+                    best = { glyph: u16(this.data, lig), consumed: components };
+                }
+            }
+        }
+        return best;
+    }
+    /** The type of a lookup, for reporting what a font needs that we do not do. */
+    lookupType(lookupIndex) {
+        return this.lookup(lookupIndex)?.type;
+    }
+    scriptOffset(script) {
+        const count = u16(this.data, this.scriptList);
+        for (let i = 0; i < count; i++) {
+            const record = this.scriptList + 2 + i * 6;
+            if (latin1FromBytes(this.data.subarray(record, record + 4)) === script) {
+                return this.scriptList + u16(this.data, record + 4);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Resolve a lookup, unwrapping type 7 (extension) - which exists only because the 16-bit offsets
+     * elsewhere cannot reach far enough in a big font. Callers never learn it was wrapped.
+     */
+    lookup(index) {
+        const cached = this.lookupCache.get(index);
+        if (cached !== undefined)
+            return cached;
+        let result = null;
+        if (index < u16(this.data, this.lookupList)) {
+            const off = this.lookupList + u16(this.data, this.lookupList + 2 + index * 2);
+            const type = u16(this.data, off);
+            const count = u16(this.data, off + 4);
+            const subtables = [];
+            let realType = type;
+            for (let i = 0; i < count; i++) {
+                const sub = off + u16(this.data, off + 6 + i * 2);
+                if (type === EXTENSION) {
+                    realType = u16(this.data, sub + 2);
+                    subtables.push(sub + u32(this.data, sub + 4));
+                }
+                else {
+                    subtables.push(sub);
+                }
+            }
+            result = { type: realType, subtables };
+        }
+        this.lookupCache.set(index, result);
+        return result;
+    }
+    /** Coverage table -> glyph id to its INDEX in the table, which is how subtables address glyphs. */
+    coverage(off) {
+        const cached = this.coverageCache.get(off);
+        if (cached)
+            return cached;
+        const map = new Map();
+        const count = u16(this.data, off + 2);
+        if (u16(this.data, off) === 1) {
+            for (let i = 0; i < count; i++)
+                map.set(u16(this.data, off + 4 + i * 2), i);
+        }
+        else {
+            // Format 2 is RANGES, and a malformed file can claim far more glyphs than any font holds. Such
+            // a table is refused whole rather than expanded - the feature then simply does not apply.
+            let total = 0;
+            for (let i = 0; i < count; i++) {
+                const record = off + 4 + i * 6;
+                const start = u16(this.data, record);
+                const end = u16(this.data, record + 2);
+                if (end < start)
+                    continue; // an inverted range covers nothing
+                total += end - start + 1;
+                if (total > MAX_COVERAGE_ENTRIES)
+                    return this.cacheCoverage(off, new Map());
+                const startIndex = u16(this.data, record + 4);
+                for (let g = start; g <= end; g++)
+                    map.set(g, startIndex + (g - start));
+            }
+        }
+        return this.cacheCoverage(off, map);
+    }
+    cacheCoverage(off, map) {
+        this.coverageCache.set(off, map);
+        return map;
+    }
+}

package/dist/utils/image-helper.d.ts

@@ -7,7 +7,7 @@ interface ImageDimensions {
     width: number;
     height: number;
 }
-export declare function getImageDimensions(buffer: Buffer): Promise<ImageDimensions>;
+export declare function getImageDimensions(buffer: Uint8Array): Promise<ImageDimensions>;
 /**
  * Converts the given image to grayscale and returns its binary data.
  * @param imagePath Path to the input image file.
@@ -16,15 +16,16 @@ export declare function getImageDimensions(buffer: Buffer): Promise<ImageDimensi
 /**
  * Decodes a PNG into raw DeviceRGB samples, Flate-compressed, ready to embed as a PDF
  * image XObject. A PNG file is NOT a valid `/FlateDecode` stream (it's a signature plus
- * chunks of filtered, zlib-compressed scanlines), so it must be decoded first. PDF has
- * no alpha channel for DeviceRGB, so transparent pixels are composited over white.
+ * chunks of filtered, zlib-compressed scanlines), so it must be decoded first. DeviceRGB has
+ * no alpha itself, so any transparency rides alongside as a DeviceGray `/SMask` (the return's `smask`).
  */
-export declare function decodePngToRgbFlate(pngBuffer: Buffer): Promise<{
+export declare function decodePngToRgbFlate(pngBuffer: Uint8Array): Promise<{
     data: string;
+    smask?: string;
     width: number;
     height: number;
 }>;
-export declare function convertImageToGrayscaleBuffer(imagePath: string): Promise<Buffer>;
+export declare function convertImageToGrayscaleBuffer(imagePath: string): Promise<Uint8Array>;
 export interface FitResult {
     width: number;
     height: number;