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

package/dist/utils/renderer-registry.d.ts

@@ -1,6 +1,18 @@
+/**
+ * Thrown when an element reaches the render pass with no registered renderer.
+ *
+ * This used to return undefined and every call site skipped the element silently, so a whole document
+ * could serialize to an empty content stream and still be a valid PDF - a blank page, no warning
+ * (ISSUE-11). The registry is keyed on the CONSTRUCTOR, which makes it the one place in the engine that
+ * two loaded copies of the library break: elements built by copy A are invisible to copy B.
+ */
+export declare class MissingRendererError extends Error {
+    readonly elementName: string;
+    constructor(elementName: string);
+}
 export declare class RendererRegistry {
     private static renderers;
     static register(elementClass: Function, renderer: Function): void;
-    static getRenderer(element: object): Function | undefined;
+    static getRenderer(element: object): Function;
     static isRendererAsync(renderer: Function): boolean;
 }

package/dist/utils/renderer-registry.js

@@ -1,19 +1,36 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RendererRegistry = void 0;
-class RendererRegistry {
+/**
+ * Thrown when an element reaches the render pass with no registered renderer.
+ *
+ * This used to return undefined and every call site skipped the element silently, so a whole document
+ * could serialize to an empty content stream and still be a valid PDF - a blank page, no warning
+ * (ISSUE-11). The registry is keyed on the CONSTRUCTOR, which makes it the one place in the engine that
+ * two loaded copies of the library break: elements built by copy A are invisible to copy B.
+ */
+export class MissingRendererError extends Error {
+    constructor(elementName) {
+        super(`@jasy/pdf: no renderer registered for "${elementName}". Either the element was never registered ` +
+            `in PDFRenderer.render(), or two copies of @jasy/pdf are loaded - the registry is keyed on the ` +
+            `element's constructor, so elements built by one copy cannot be rendered by the other. ` +
+            `Check the dependency tree for a duplicate (e.g. \`pnpm why @jasy/pdf\`).`);
+        this.elementName = elementName;
+    }
+}
+export class RendererRegistry {
     static register(elementClass, renderer) {
         if (!RendererRegistry.renderers.has(elementClass)) {
             RendererRegistry.renderers.set(elementClass, renderer);
         }
     }
     // Keyed on the element's constructor, so it only needs an object - not `any`.
+    // Throws rather than returning undefined: a missing renderer is always a bug, and skipping it drew nothing.
     static getRenderer(element) {
-        return RendererRegistry.renderers.get(element.constructor);
+        const renderer = RendererRegistry.renderers.get(element.constructor);
+        if (!renderer)
+            throw new MissingRendererError(element.constructor.name);
+        return renderer;
     }
     static isRendererAsync(renderer) {
         return renderer.constructor.name === "AsyncFunction";
     }
 }
-exports.RendererRegistry = RendererRegistry;
 RendererRegistry.renderers = new Map();

package/dist/utils/struct-tree.d.ts

@@ -0,0 +1,44 @@
+import type { StructTag } from "../ir/display-list.js";
+import type { PDFObjectManager } from "./pdf-object-manager.js";
+/** Per-page tagging context: hands out page-local MCIDs and links them to their StructElem. */
+export declare class PageStructContext {
+    readonly structParents: number;
+    private readonly tree;
+    private mcid;
+    constructor(structParents: number, tree: StructTree);
+    /** Marked-content delimiters for one drawable node. Tagged content gets an MCID linked to its (already
+     *  registered) StructElem; untagged content becomes an Artifact (decoration, skipped by assistive tech). */
+    mark(tag?: StructTag): {
+        open: string;
+        close: string;
+    };
+}
+/** Builds the PDF structure tree for accessible tagging. One instance per document (held by the object manager). */
+export declare class StructTree {
+    enabled: boolean;
+    lang: string;
+    title?: string;
+    private counter;
+    private structParentsCounter;
+    private elems;
+    private byStructId;
+    private stack;
+    private pageObjByStructParents;
+    /** Register a structure element for a logical element (keyed by its stable `structId`, so a paragraph or
+     *  table split across pages resolves to the SAME element - MCIDs then accrue from every page). Its parent
+     *  is the currently-open container, else the Document. Containers also push()/pop() around their children. */
+    openElement(structId: number, role: string, opts?: {
+        alt?: string;
+    }): number;
+    push(key: number): void;
+    pop(): void;
+    /** Begin a page: allocates its StructParents index (its slot in the ParentTree). */
+    beginPage(): PageStructContext;
+    /** Tie a page's StructParents index to its now-known page object number (for /Pg references). */
+    setPageObject(structParents: number, pageObjNum: number): void;
+    /** Link a page-local MCID to an element (called by the backend while serializing). */
+    linkMarkedContent(key: number, structParents: number, mcid: number): void;
+    /** Emit the struct-tree objects and return the catalog additions (`/MarkInfo`, `/StructTreeRoot`, `/Lang`).
+     *  A no-op returning "" when disabled or nothing was tagged, so a plain document stays byte-identical. */
+    finalize(om: PDFObjectManager): string;
+}

package/dist/utils/struct-tree.js

@@ -0,0 +1,129 @@
+// Escapes a PDF literal string ( ... ) - the language tag is safe ASCII, but /Alt can carry arbitrary text.
+// 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.
+const roleName = (role) => role.replace(/[^A-Za-z0-9]/g, "") || "Span";
+/** Per-page tagging context: hands out page-local MCIDs and links them to their StructElem. */
+export class PageStructContext {
+    constructor(structParents, tree) {
+        this.structParents = structParents;
+        this.tree = tree;
+        this.mcid = 0;
+    }
+    /** Marked-content delimiters for one drawable node. Tagged content gets an MCID linked to its (already
+     *  registered) StructElem; untagged content becomes an Artifact (decoration, skipped by assistive tech). */
+    mark(tag) {
+        // Artifact = decoration, no properties -> BMC (BDC would need a second operand and is a syntax error).
+        if (!tag)
+            return { open: "/Artifact BMC\n", close: "EMC\n" };
+        const mcid = this.mcid++;
+        this.tree.linkMarkedContent(tag.key, this.structParents, mcid);
+        return { open: `/${roleName(tag.role)} <</MCID ${mcid}>> BDC\n`, close: "EMC\n" };
+    }
+}
+/** Builds the PDF structure tree for accessible tagging. One instance per document (held by the object manager). */
+export class StructTree {
+    constructor() {
+        this.enabled = false;
+        this.lang = "en-US";
+        this.counter = 0;
+        this.structParentsCounter = 0;
+        this.elems = new Map(); // insertion order = render order = reading order
+        this.byStructId = new Map(); // element structId -> element key (dedup across pages)
+        this.stack = []; // open containers; top is the current parent
+        this.pageObjByStructParents = new Map();
+    }
+    /** Register a structure element for a logical element (keyed by its stable `structId`, so a paragraph or
+     *  table split across pages resolves to the SAME element - MCIDs then accrue from every page). Its parent
+     *  is the currently-open container, else the Document. Containers also push()/pop() around their children. */
+    openElement(structId, role, opts) {
+        const existing = this.byStructId.get(structId);
+        if (existing !== undefined)
+            return existing; // already opened on an earlier page/fragment
+        const key = this.counter++;
+        this.byStructId.set(structId, key);
+        this.elems.set(key, {
+            key,
+            role,
+            alt: opts?.alt,
+            parent: this.stack[this.stack.length - 1],
+            mc: [],
+        });
+        return key;
+    }
+    push(key) {
+        this.stack.push(key);
+    }
+    pop() {
+        this.stack.pop();
+    }
+    /** Begin a page: allocates its StructParents index (its slot in the ParentTree). */
+    beginPage() {
+        return new PageStructContext(this.structParentsCounter++, this);
+    }
+    /** Tie a page's StructParents index to its now-known page object number (for /Pg references). */
+    setPageObject(structParents, pageObjNum) {
+        this.pageObjByStructParents.set(structParents, pageObjNum);
+    }
+    /** Link a page-local MCID to an element (called by the backend while serializing). */
+    linkMarkedContent(key, structParents, mcid) {
+        this.elems.get(key)?.mc.push({ structParents, mcid });
+    }
+    /** Emit the struct-tree objects and return the catalog additions (`/MarkInfo`, `/StructTreeRoot`, `/Lang`).
+     *  A no-op returning "" when disabled or nothing was tagged, so a plain document stays byte-identical. */
+    finalize(om) {
+        if (!this.enabled || this.elems.size === 0)
+            return "";
+        // Reserve object numbers first - root <-> Document <-> elements <-> ParentTree reference each other.
+        const rootNum = om.addObject("");
+        const docNum = om.addObject("");
+        const parentTreeNum = om.addObject("");
+        const objNum = new Map();
+        for (const key of this.elems.keys())
+            objNum.set(key, om.addObject(""));
+        const pg = (structParents) => this.pageObjByStructParents.get(structParents);
+        const childrenOf = (parent) => [...this.elems.values()].filter((e) => e.parent === parent); // Map order = reading order
+        // One StructElem per registered element: /K = its child elements ++ its marked-content references.
+        for (const e of this.elems.values()) {
+            const kids = [
+                ...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 ${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 >>" : "";
+            const parentRef = e.parent !== undefined ? objNum.get(e.parent) : docNum;
+            om.replaceObject(objNum.get(e.key), `<< /Type /StructElem /S /${roleName(e.role)} /P ${parentRef} 0 R${alt}${attr} /K [ ${kids} ] >>`);
+        }
+        // The Document element wraps the top-level elements in reading order.
+        const docKids = childrenOf(undefined)
+            .map((e) => `${objNum.get(e.key)} 0 R`)
+            .join(" ");
+        om.replaceObject(docNum, `<< /Type /StructElem /S /Document /P ${rootNum} 0 R /K [ ${docKids} ] >>`);
+        // ParentTree: for each page (StructParents index), an array where [mcid] = the owning StructElem.
+        const byPage = new Map();
+        for (const e of this.elems.values()) {
+            for (const m of e.mc) {
+                const list = byPage.get(m.structParents) ?? [];
+                list.push({ mcid: m.mcid, key: e.key });
+                byPage.set(m.structParents, list);
+            }
+        }
+        const nums = [...byPage.keys()]
+            .sort((a, b) => a - b)
+            .map((sp) => {
+            const refs = byPage
+                .get(sp)
+                .slice()
+                .sort((a, b) => a.mcid - b.mcid)
+                .map((r) => `${objNum.get(r.key)} 0 R`)
+                .join(" ");
+            return `${sp} [ ${refs} ]`;
+        });
+        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 ${om.pdfString(this.lang)}`;
+    }
+}

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

@@ -1,29 +1,161 @@
+import type { FontDecoration } from "../text/text-decoration.js";
+import { GsubTable } from "./gsub.js";
+export type GlyphPathCommand = {
+    type: "M";
+    x: number;
+    y: number;
+} | {
+    type: "L";
+    x: number;
+    y: number;
+} | {
+    type: "Q";
+    cx: number;
+    cy: number;
+    x: number;
+    y: number;
+} | {
+    type: "Z";
+};
+export interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export interface ColorStop {
+    offset: number;
+    color: RGBA | null;
+}
+export type Paint = {
+    type: "solid";
+    color: RGBA | null;
+} | {
+    type: "linearGradient";
+    p0: [number, number];
+    p1: [number, number];
+    stops: ColorStop[];
+    extend: "pad" | "repeat" | "reflect";
+} | {
+    type: "radialGradient";
+    c0: [number, number, number];
+    c1: [number, number, number];
+    stops: ColorStop[];
+    extend: "pad" | "repeat" | "reflect";
+};
+export type Affine = [number, number, number, number, number, number];
+export interface ColorGlyphLayer {
+    glyphId: number;
+    paint: Paint;
+    transform?: Affine;
+}
+/** Sorts x-intervals and unions the overlapping ones. */
+export declare function mergeSpans(spans: Array<[number, number]>): Array<[number, number]>;
 export declare class TTFParser {
     private data;
     unitsPerEm: number;
     ascent: number;
     descent: number;
+    lineGap: number;
+    private underlinePositionRaw;
+    private underlineThicknessRaw;
+    private xHeightRaw;
+    private capHeightRaw;
+    private cachedDecoration?;
     bbox: [number, number, number, number];
     private numGlyphs;
     private numHMetrics;
+    private indexToLocFormat;
     private advanceWidths;
     private cmap;
     private cmapGroups;
     private tables;
-    constructor(data: Buffer);
-    getData(): Buffer;
+    private colrBase;
+    private colrLayersOffset;
+    private palette;
+    private colrBaseV1;
+    private colrLayerListOffset;
+    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;
+    /**
+     * Underline / strikethrough geometry, as fractions of the em.
+     *
+     * A font without `post` (rare) gets the classic 10% below the baseline at 5% thickness - the same
+     * numbers all 14 standard AFMs happen to declare, so it is a measured convention rather than an
+     * invention. A font whose `OS/2` predates version 2 has no x- or cap-height, so we MEASURE them off
+     * the outlines of `x` and `H` instead of guessing.
+     */
+    decoration(): FontDecoration;
+    /** The highest ON-CURVE point of a code point's outline, in font units; 0 for a missing glyph.
+     *  A quadratic's control point may sit above the curve, so it is not a bound - and `x`/`H` have
+     *  flat tops in any face where this fallback matters. */
+    private outlineTop;
+    /**
+     * Where a glyph's INK crosses a horizontal band, as x-intervals in font units (pen origin at 0).
+     * This is what lets an underline step around a descender ("skip-ink"), the way a browser does.
+     *
+     * Scanline fill: sample a few horizontal lines across the band, find every place the outline
+     * crosses them, and pair the crossings up into filled spans. A handful of scanlines is plenty -
+     * the band is a few percent of the em tall, and a descender stem does not wander inside it.
+     *
+     * `yTop` / `yBottom` are in font units, y UP from the baseline (so both are negative under it).
+     * Returns [] for a glyph with no outline (a space, an unmapped code point, a composite we cannot
+     * decompose) - the caller then leaves the line unbroken there, which is the safe direction.
+     */
+    inkSpansInBand(codePoint: number, yTop: number, yBottom: number): Array<[number, number]>;
+    /** True if the font declares any horizontal kerning (kern table or GPOS). */
+    kerns(): boolean;
+    private kernCache;
+    /** Kerning between two glyphs, in em/1000 (the standard-14 unit); 0 if the pair is not kerned.
+     *  Negative tightens, matching the AFM sign. GPOS wins over the legacy `kern` table when both
+     *  exist (it is what a modern shaper uses, and can carry more pairs). */
+    getKerning(leftGid: number, rightGid: number): number;
+    private readKern;
+    private readGpos;
+    private gposKern;
+    private static valueRecordSize;
+    private xAdvance;
+    private coverageIndex;
+    private classOf;
     private table;
     private readTableDirectory;
     private readHmtx;
     private readCmap;
     private readCmapFormat4;
     private readCmapFormat12;
+    hasGlyfOutlines(): boolean;
+    private glyfRange;
+    getGlyphPath(glyphId: number): GlyphPathCommand[];
+    private parseSimpleGlyph;
+    private readCoordinates;
+    private contourToCommands;
+    hasColorGlyphs(): boolean;
+    getColorGlyph(glyphId: number): ColorGlyphLayer[] | null;
+    private walkColrLayers;
+    private resolveFill;
+    private readColorLine;
+    private paletteColor;
+    private u24;
+    private f2dot14;
+    private i32;
+    private readAffine;
+    private readColr;
+    private readCpal;
 }