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

package/dist/utils/outline.js

@@ -0,0 +1,79 @@
+// A PDF literal string escape (same rule as elsewhere): backslash first, then the string delimiters.
+const num = (n) => Number(n.toFixed(2));
+/**
+ * Builds the PDF document outline (`/Outlines`) - the viewer's bookmark panel. Entries are collected
+ * flat in reading order with a 1-based `level`; `finalize` nests each entry under the nearest preceding
+ * entry of a smaller level (so level 2s hang under the last level 1), emits the outline objects and
+ * returns the catalog addition `/Outlines N 0 R`. A no-op returning "" when nothing was added, so a
+ * document without bookmarks stays byte-identical.
+ */
+export class OutlineBuilder {
+    constructor() {
+        this.entries = [];
+    }
+    add(entry) {
+        this.entries.push(entry);
+    }
+    get isEmpty() {
+        return this.entries.length === 0;
+    }
+    finalize(om) {
+        if (this.entries.length === 0)
+            return "";
+        // Nest by level: a stack where stack[i] is the last open node at level i+1. An entry at level L
+        // becomes a child of stack[L-2] (the enclosing smaller level), or a root when L is 1. Levels that
+        // skip a step (1 -> 3) are clamped to one deeper than the current stack so nothing is orphaned.
+        const roots = [];
+        const stack = [];
+        for (const e of this.entries) {
+            const level = Math.max(1, Math.min(e.level, stack.length + 1));
+            stack.length = level - 1; // pop back to this entry's parent depth
+            const node = { ...e, children: [] };
+            if (level === 1)
+                roots.push(node);
+            else
+                stack[level - 2].children.push(node);
+            stack[level - 1] = node;
+        }
+        // Reserve an object number for every node up front - parent/child/prev/next all cross-reference.
+        const objOf = new Map();
+        const walk = (nodes) => {
+            for (const n of nodes) {
+                objOf.set(n, om.addObject(""));
+                walk(n.children);
+            }
+        };
+        walk(roots);
+        const rootNum = om.addObject(""); // the /Outlines dictionary itself
+        // Count of all descendants of a node (used for the /Count of an open item, which shows them all).
+        const descendantCount = (n) => n.children.reduce((sum, c) => sum + 1 + descendantCount(c), 0);
+        const totalCount = roots.reduce((sum, r) => sum + 1 + descendantCount(r), 0);
+        // Emit each item dict, wired to its parent, siblings (prev/next) and first/last child.
+        const emit = (nodes, parentNum) => {
+            nodes.forEach((n, i) => {
+                const parts = [`/Title ${om.pdfString(n.title)}`, `/Parent ${parentNum} 0 R`];
+                if (i > 0)
+                    parts.push(`/Prev ${objOf.get(nodes[i - 1])} 0 R`);
+                if (i < nodes.length - 1)
+                    parts.push(`/Next ${objOf.get(nodes[i + 1])} 0 R`);
+                if (n.children.length > 0) {
+                    parts.push(`/First ${objOf.get(n.children[0])} 0 R`);
+                    parts.push(`/Last ${objOf.get(n.children[n.children.length - 1])} 0 R`);
+                    parts.push(`/Count ${descendantCount(n)}`); // positive = shown open
+                }
+                // /Dest: jump to this page, scrolling the target's top into view; null left/zoom keep the
+                // viewer's current horizontal position and magnification. Guard the top: a non-finite value
+                // (e.g. a bookmark under a Spacer in an unbounded column) would emit invalid PDF, so fall back
+                // to the page top (0 flips to the page top edge).
+                const top = Number.isFinite(n.top) ? num(n.top) : 0;
+                parts.push(`/Dest [${n.pageObjNum} 0 R /XYZ null ${top} null]`);
+                om.replaceObject(objOf.get(n), `<< ${parts.join(" ")} >>`);
+                emit(n.children, objOf.get(n));
+            });
+        };
+        emit(roots, rootNum);
+        om.replaceObject(rootNum, `<< /Type /Outlines /First ${objOf.get(roots[0])} 0 R ` +
+            `/Last ${objOf.get(roots[roots.length - 1])} 0 R /Count ${totalCount} >>`);
+        return `/Outlines ${rootNum} 0 R`;
+    }
+}

package/dist/utils/pdf-object-manager.d.ts

@@ -1,5 +1,16 @@
-import type { PDFConfig } from "../renderer/pdf-document-class";
-import type { FontMetrics } from "./font-metrics";
+import type { OverflowPolicy } from "../layout/fragmentation.js";
+import { TTFParser } from "./ttf-parser.js";
+import { type ShapedGlyph } from "../text/shape.js";
+import type { SecurityHandler } from "../crypto/security-handler.js";
+import type { Gradient } from "../ir/display-list.js";
+import type { FontVerticals } from "../text/line-metrics.js";
+import type { FontDecoration } from "../text/text-decoration.js";
+import { StructTree } from "./struct-tree.js";
+import { OutlineBuilder } from "./outline.js";
+import { DestRegistry } from "./dest-registry.js";
+import { AcroFormCollector } from "../forms/acroform.js";
+import type { PDFConfig } from "../renderer/pdf-document-class.js";
+import type { FontMetrics } from "./font-metrics.js";
 interface FontIndexes {
     fontIndex: number;
     resourceIndex: number;
@@ -19,31 +30,79 @@ export declare class PDFObjectManager implements FontMetrics {
     private fonts;
     private images;
     private extGStates;
+    private shadings;
+    private emojiFontName?;
+    private emojiImage?;
     private pdfConfig;
     pageFormat: [number, number];
     private afmParsers;
     private customFonts;
+    private verticalsCache;
+    private decorationCache;
     private customFontEmit;
+    private shapeCache;
+    private shapedOrigins;
     private attachments;
     private xmpMetadata?;
     private outputIntent?;
     private pdfVersion;
     private documentId;
     private compress;
+    private overflowPolicy;
+    private security?;
+    private encJobs;
+    private strJobs;
+    private encryptObjNum?;
+    private _struct;
+    get struct(): StructTree;
+    private _outline;
+    get outline(): OutlineBuilder;
+    private _dests;
+    get dests(): DestRegistry;
+    private _acroform;
+    get acroform(): AcroFormCollector;
     constructor();
     addObject(content: string): number;
     replaceObject(objectNumber: number, content: string): void;
     setCompress(on: boolean): void;
+    /**
+     * Code points no font in the document could draw, so they were removed rather than emitted as
+     * `.notdef` (which PDF/A forbids). Collected here because this object is the one thing threaded
+     * through BOTH passes; the caller gets them back with the bytes, so an application can say which
+     * character went missing instead of a server log nobody reads.
+     */
+    private readonly missingGlyphs;
+    reportMissingGlyph(codePoints: number[]): void;
+    /** The dropped code points, in the order first seen. Empty for a document that hit none. */
+    getMissingGlyphs(): number[];
+    setOverflowPolicy(policy: OverflowPolicy): void;
+    getOverflowPolicy(): OverflowPolicy;
+    private encToken;
+    private strToken;
+    /**
+     * 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: string): string;
+    private streamPayload;
     private stream;
     addContentStream(content: string): number;
+    addFormXObject(bbox: string, content: string, resources?: string): number;
     changePDFConfig(config: PDFConfig): void;
     getPDFConfig(): PDFConfig;
     private fillConfigWithStandardValues;
     private getCurrentByteLength;
     setParentObjectNumber(number: number): void;
     getParentObjectNumber(): number;
-    registerImage(width: number, height: number, imageType: string, imageData: string): number;
-    attachFile(name: string, data: Buffer, opts?: {
+    registerImage(width: number, height: number, imageType: string, imageData: string, smaskData?: string): number;
+    attachFile(name: string, data: Uint8Array, opts?: {
         relationship?: string;
         mimeType?: string;
         description?: string;
@@ -54,7 +113,7 @@ export declare class PDFObjectManager implements FontMetrics {
     }[];
     setXmpMetadata(xml: string): void;
     getXmpMetadata(): string | undefined;
-    setOutputIntent(icc: Buffer, opts?: {
+    setOutputIntent(icc: Uint8Array, opts?: {
         identifier?: string;
         info?: string;
     }): void;
@@ -63,10 +122,15 @@ export declare class PDFObjectManager implements FontMetrics {
     getPdfVersion(): string;
     getHeader(): string;
     enableDocumentId(): void;
+    setSecurityHandler(handler: SecurityHandler): void;
+    finalizeEncryption(): Promise<void>;
     registerExtGState(fillAlpha: number, strokeAlpha: number): string;
     getAllExtGStatesRaw(): Map<string, number>;
+    registerShading(g: Gradient): string;
+    private buildShadingFunction;
+    getAllShadingsRaw(): Map<string, number>;
     registerFont(fontName: string, fontStyle?: FontStyle, fullName?: string): FontIndexes;
-    registerCustomFont(name: string, data: Buffer, style?: FontStyle): void;
+    registerCustomFont(name: string, data: Uint8Array, style?: FontStyle): void;
     private ensureEmitted;
     finalizeCustomFonts(): void;
     private subsetTag;
@@ -74,18 +138,73 @@ export declare class PDFObjectManager implements FontMetrics {
     private resolveCustomStyle;
     private getCustomFont;
     isCustomFont(name?: string, style?: FontStyle): boolean;
+    getColorFont(name: string, style?: FontStyle): TTFParser | undefined;
+    setEmojiFont(name: string): void;
+    getEmojiFont(): string | undefined;
+    setEmojiImageSource(url: string, format: string): void;
+    getEmojiImageSource(): {
+        url: string;
+        format: string;
+    } | undefined;
+    /**
+     * 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: number, fontFamily: string, fontStyle?: FontStyle): boolean;
+    /**
+     * Whether the document draws this code point through the colour-emoji path instead of the text
+     * font - a fallback emoji FONT, or an image source (`Document({ emoji })`). Such a code point is
+     * missing from the text font ON PURPOSE, so glyph coverage must leave it alone. Mirrors exactly
+     * what `getCharWidth` measures it as, or a dropped emoji would have been measured and not drawn.
+     */
+    rendersAsEmoji(codePoint: number, fontFamily: string, fontStyle: FontStyle): boolean;
+    private colorRenders;
     getCustomFontResource(name: string, style?: FontStyle): FontIndexes | undefined;
+    /** 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: string, fontFamily?: string, fontStyle?: FontStyle): number | undefined;
+    /**
+     * 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: string, fontFamily?: string, fontStyle?: FontStyle): ShapedGlyph[] | 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: string, glyphs: readonly number[], style?: FontStyle): string;
     encodeCustomText(name: string, text: string, style?: FontStyle): string;
     private buildFontFile2;
     private buildFontDescriptor;
     private buildCIDFont;
     private buildToUnicode;
     private buildType0;
+    getFontVerticals(fontFamily: string, fontStyle: FontStyle): FontVerticals;
+    getFontDecoration(fontFamily: string, fontStyle: FontStyle): FontDecoration;
+    kerningEnabled: boolean;
+    setKerning(enabled: boolean): void;
+    /**
+     * The kerning adjustment for each adjacent code-point pair of `text`, in em/1000 (the sign the
+     * font declares: negative tightens). Length is `codePointCount - 1`. Zero at any pair next to a
+     * space - letters are never kerned against a space, which also keeps a per-word measure equal to a
+     * whole-line one (the space pairs contribute nothing either way).
+     *
+     * Standard-14 answers from the AFM `KPX` pairs. An embedded font has no kerning yet (its `kern` /
+     * `GPOS` tables are unparsed), so it returns zeros - never a wrong value, just no adjustment.
+     */
+    getKernPairs(text: string, fontFamily: string, fontStyle: FontStyle): number[];
+    /**
+     * Where the glyphs of `text` put ink inside a horizontal band, as x-intervals in POINTS measured
+     * from the start of the run. This is what an underline steps around ("skip-ink").
+     *
+     * `bandTop` / `bandBottom` are in points relative to the baseline, y UP (so both negative under
+     * it). Only an EMBEDDED font can answer: the standard-14 outlines live in the viewer, not here.
+     * Callers must check `isCustomFont` first rather than treat an empty result as "no descenders".
+     */
+    getInkSpansInBand(text: string, fontSize: number, fontFamily: string, fontStyle: FontStyle, bandTop: number, bandBottom: number, letterSpacing?: number): Array<[number, number]>;
     getStringWidth(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle): number;
-    private getCharCode;
     private getAVMParserByFont;
     getCharWidth(char: string, fontSize: number, fullFontName?: string, fontName?: string, fontStyle?: FontStyle): number;
-    private getKerning;
     getAllFontsRaw(): Map<string, FontIndexes>;
     getAllImagesRaw(): Map<string, number>;
     getRenderedObjects(): string;