@jasy/pdf 1.0.0-beta.3 → 1.0.0-beta.5

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

@@ -31,9 +31,10 @@ export interface FontMetrics {
     /** Whether the document draws this code point as colour emoji rather than from the text font - it
      *  is missing from that font on purpose, so glyph coverage must not touch it. */
     rendersAsEmoji?(codePoint: number, fontFamily: string, fontStyle: FontStyle): boolean;
-    /** Told when a code point had to be removed because no font could draw it. Optional: a metrics
-     *  object used only for measuring (a test double) has nothing to report to. */
-    reportMissingGlyph?(codePoints: number[]): void;
+    /** Told when a code point had to be removed because no font could draw it - `about` is the element
+     *  it was removed from. Optional: a metrics object used only for measuring (a test double) has
+     *  nothing to report to. */
+    reportMissingGlyph?(codePoints: number[], about?: object, page?: number): void;
     /** 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, ligatures?: boolean): number | undefined;

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

@@ -3,11 +3,56 @@ declare global {
         getUint24(byteOffset: number, littleEndian?: boolean): number;
     }
 }
-interface ImageDimensions {
+/** Dots per inch, per axis. */
+export interface Resolution {
+    x: number;
+    y: number;
+}
+export interface ImageDimensions {
+    /** In pixels - what the XObject declares. */
+    width: number;
+    height: number;
+    /** The resolution the file declares; absent when it declares none. */
+    dpi?: Resolution;
+    /** How the stored pixels turn upright (EXIF, a JPEG only); absent when they already are. */
+    orientation?: Orientation;
+}
+/**
+ * EXIF orientation: 2 mirrored, 3 turned half, 4 flipped, 5 transposed, 6 turned a quarter clockwise,
+ * 7 transversed, 8 turned a quarter counterclockwise. 5-8 swap width and height.
+ */
+export type Orientation = 2 | 3 | 4 | 5 | 6 | 7 | 8;
+/**
+ * The matrix that turns the image's unit square upright, inside it - PDF's image space, y up, the first
+ * stored row at the top. Applied before the placement scales it, so the box stays the box.
+ */
+export declare const ORIENTATION_MATRIX: Record<Orientation, readonly number[]>;
+/** The resolution of a file that declares none: CSS's reference pixel, 1/96 inch. */
+export declare const DEFAULT_DPI = 96;
+/**
+ * An image's own size in points, upright: its pixels at the resolution the file declares, else 96 dpi,
+ * turned by its orientation.
+ */
+export declare function naturalSize(dims: ImageDimensions): {
     width: number;
     height: number;
+};
+/** Thrown for a JPEG we cannot embed as it is. Says what it is and what to do. */
+export declare class JpegFormatError extends Error {
+    constructor(message: string);
+}
+/** The colors an image's samples are in. */
+export type ImageColorSpace = "gray" | "rgb" | "cmyk";
+/** What an image's samples mean: their color space, and whether they are stored inverted. */
+export interface ImageColor {
+    space: ImageColorSpace;
+    /** Photoshop stores CMYK inverted (an Adobe `APP14` segment). */
+    inverted?: boolean;
 }
-export declare function getImageDimensions(buffer: Uint8Array): Promise<ImageDimensions>;
+/** The color of a JPEG as it is embedded (`DCTDecode`): the space it was saved in. */
+export declare function jpegColor(bytes: Uint8Array): ImageColor;
+/** Read from the header alone, synchronously - layout can ask it. */
+export declare function readImageDimensions(buffer: Uint8Array): ImageDimensions;
 /**
  * Converts the given image to grayscale and returns its binary data.
  * @param imagePath Path to the input image file.
@@ -26,19 +71,22 @@ export declare function decodePngToRgbFlate(pngBuffer: Uint8Array): Promise<{
     height: number;
 }>;
 export declare function convertImageToGrayscaleBuffer(imagePath: string): Promise<Uint8Array>;
+/** The drawn size of an image in its box, and where it sits there. */
 export interface FitResult {
     width: number;
     height: number;
     offsetX: number;
     offsetY: number;
 }
-export declare function applyContainFit(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number): FitResult;
-export declare function applyCoverFit(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number): FitResult;
+/** Where an image smaller or larger than its box sits in it, per axis: 0 = start, 0.5 = center, 1 = end. */
+export interface FitAlign {
+    x: number;
+    y: number;
+}
+/** Scaled to fit inside the box, whole image visible. */
+export declare function applyContainFit(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number, align?: FitAlign): FitResult;
+/** Scaled to cover the box, the overhang cut off. */
+export declare function applyCoverFit(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number, align?: FitAlign): FitResult;
 export declare function applyFillFit(containerWidth: number, containerHeight: number): FitResult;
-export declare function applyFitNone(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number): {
-    width: number;
-    height: number;
-    offsetX: number;
-    offsetY: number;
-};
-export {};
+/** At its own size (`naturalSize`), the overhang cut off. */
+export declare function applyFitNone(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number, align?: FitAlign): FitResult;

package/dist/utils/image-helper.js

@@ -8,31 +8,198 @@ DataView.prototype.getUint24 = function (byteOffset, littleEndian = false) {
     const b3 = this.getUint8(byteOffset + 2);
     return littleEndian ? (b3 << 16) | (b2 << 8) | b1 : (b1 << 16) | (b2 << 8) | b3;
 };
-export async function getImageDimensions(buffer) {
-    const dataView = new DataView(buffer.buffer);
-    // Check for JPEG (0xFFD8 is the start of JPEG file)
-    if (dataView.getUint16(0) === 0xffd8) {
-        let offset = 2;
-        while (offset < buffer.byteLength) {
-            const marker = dataView.getUint16(offset, false);
-            offset += 2;
-            if (marker === 0xffc0 || marker === 0xffc2) {
-                // SOF0 or SOF2
-                return {
-                    height: dataView.getUint16(offset + 3, false),
-                    width: dataView.getUint16(offset + 5, false),
-                };
-            }
-            else {
-                offset += dataView.getUint16(offset, false);
-            }
+/**
+ * The matrix that turns the image's unit square upright, inside it - PDF's image space, y up, the first
+ * stored row at the top. Applied before the placement scales it, so the box stays the box.
+ */
+export const ORIENTATION_MATRIX = {
+    2: [-1, 0, 0, 1, 1, 0],
+    3: [-1, 0, 0, -1, 1, 1],
+    4: [1, 0, 0, -1, 0, 1],
+    5: [0, -1, -1, 0, 1, 1],
+    6: [0, -1, 1, 0, 0, 1],
+    7: [0, 1, 1, 0, 0, 0],
+    8: [0, 1, -1, 0, 1, 0],
+};
+/** The resolution of a file that declares none: CSS's reference pixel, 1/96 inch. */
+export const DEFAULT_DPI = 96;
+/**
+ * An image's own size in points, upright: its pixels at the resolution the file declares, else 96 dpi,
+ * turned by its orientation.
+ */
+export function naturalSize(dims) {
+    const width = (dims.width * 72) / (dims.dpi?.x ?? DEFAULT_DPI);
+    const height = (dims.height * 72) / (dims.dpi?.y ?? DEFAULT_DPI);
+    return (dims.orientation ?? 1) >= 5 ? { width: height, height: width } : { width, height };
+}
+/** A resolution only counts if both axes are real numbers above zero; anything else is no declaration. */
+function resolution(x, y) {
+    return Number.isFinite(x) && Number.isFinite(y) && x > 0 && y > 0 ? { x, y } : undefined;
+}
+/** PNG `pHYs`: pixels per unit, and only unit 1 (meter) is a physical size - 0 is an aspect ratio. */
+function pngResolution(view) {
+    for (let offset = 8; offset + 8 <= view.byteLength;) {
+        const length = view.getUint32(offset);
+        const type = view.getUint32(offset + 4);
+        if (type === 0x49444154)
+            return undefined; // IDAT: pHYs must come before it
+        if (type === 0x70485973 && length >= 9 && offset + 17 <= view.byteLength) {
+            if (view.getUint8(offset + 16) !== 1)
+                return undefined;
+            return resolution(view.getUint32(offset + 8) * 0.0254, view.getUint32(offset + 12) * 0.0254);
+        }
+        offset += 12 + length;
+    }
+    return undefined;
+}
+/** JFIF `APP0`: units 1 = dots per inch, 2 = per centimeter, 0 = an aspect ratio only. */
+function jfifResolution(view, data) {
+    if (view.getUint32(data) !== 0x4a464946 || view.getUint8(data + 4) !== 0)
+        return undefined; // "JFIF\0"
+    const units = view.getUint8(data + 7);
+    const scale = units === 1 ? 1 : units === 2 ? 2.54 : 0;
+    if (scale === 0)
+        return undefined;
+    return resolution(view.getUint16(data + 8) * scale, view.getUint16(data + 10) * scale);
+}
+/** The first IFD of a TIFF block (EXIF), as tag → the entry's offset in `view`. */
+function tiffEntries(view, tiff) {
+    const le = view.getUint16(tiff) === 0x4949; // "II"
+    const ifd = tiff + view.getUint32(tiff + 4, le);
+    const entries = new Map();
+    const count = view.getUint16(ifd, le);
+    for (let i = 0; i < count; i++) {
+        const entry = ifd + 2 + i * 12;
+        entries.set(view.getUint16(entry, le), entry);
+    }
+    return { entries, le };
+}
+/**
+ * EXIF `APP1`: XResolution / YResolution (rationals) in ResolutionUnit, 2 = inch (the default), 3 = cm;
+ * Orientation 1-8.
+ */
+function exifInfo(view, data) {
+    if (view.getUint32(data) !== 0x45786966 || view.getUint16(data + 4) !== 0)
+        return undefined; // "Exif\0\0"
+    const tiff = data + 6;
+    const { entries, le } = tiffEntries(view, tiff);
+    const rational = (tag) => {
+        const entry = entries.get(tag);
+        if (entry === undefined)
+            return NaN;
+        const at = tiff + view.getUint32(entry + 8, le);
+        return view.getUint32(at, le) / view.getUint32(at + 4, le);
+    };
+    const short = (tag) => {
+        const entry = entries.get(tag);
+        return entry === undefined ? undefined : view.getUint16(entry + 8, le);
+    };
+    const unit = short(0x0128) ?? 2;
+    const scale = unit === 2 ? 1 : unit === 3 ? 2.54 : 0;
+    const dpi = scale === 0 ? undefined : resolution(rational(0x011a) * scale, rational(0x011b) * scale);
+    const turn = short(0x0112);
+    const orientation = turn !== undefined && turn >= 2 && turn <= 8 ? turn : undefined;
+    return { ...(dpi ? { dpi } : {}), ...(orientation ? { orientation } : {}) };
+}
+/** What a header declares is metadata: a malformed declaration is none, never a failed image. */
+function tryRead(read) {
+    try {
+        return read();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Start-of-frame markers; the rest of 0xFFC0..0xFFCF are tables (DHT C4, JPG C8, DAC CC). */
+const isSof = (marker) => marker >= 0xffc0 &&
+    marker <= 0xffcf &&
+    marker !== 0xffc4 &&
+    marker !== 0xffc8 &&
+    marker !== 0xffcc;
+/** Markers without a length: TEM and the restart markers. */
+const isStandalone = (marker) => marker === 0xff01 || (marker >= 0xffd0 && marker <= 0xffd7);
+function jpegHeader(view) {
+    // JFIF is the container's own declaration and wins; EXIF is what a camera writes.
+    let jfif;
+    let exif;
+    let adobe = false;
+    let offset = 2;
+    while (offset + 4 <= view.byteLength) {
+        if (view.getUint8(offset + 1) === 0xff) {
+            offset++; // a fill byte before the marker
+            continue;
+        }
+        const marker = view.getUint16(offset);
+        offset += 2;
+        if (isStandalone(marker))
+            continue;
+        if (isSof(marker)) {
+            const dpi = jfif ?? exif?.dpi;
+            const orientation = exif?.orientation;
+            return {
+                height: view.getUint16(offset + 3),
+                width: view.getUint16(offset + 5),
+                components: view.getUint8(offset + 7),
+                sof: marker,
+                adobe,
+                ...(dpi ? { dpi } : {}),
+                ...(orientation ? { orientation } : {}),
+            };
         }
+        if (marker === 0xffe0)
+            jfif ?? (jfif = tryRead(() => jfifResolution(view, offset + 2)));
+        if (marker === 0xffe1)
+            exif ?? (exif = tryRead(() => exifInfo(view, offset + 2)));
+        // "Adobe"
+        if (marker === 0xffee &&
+            view.getUint32(offset + 2) === 0x41646f62 &&
+            view.getUint8(offset + 6) === 0x65)
+            adobe = true;
+        offset += view.getUint16(offset);
+    }
+    throw new Error("Unsupported image format");
+}
+/** Thrown for a JPEG we cannot embed as it is. Says what it is and what to do. */
+export class JpegFormatError extends Error {
+    constructor(message) {
+        super(`@jasy/pdf: ${message}`);
+    }
+}
+/** Baseline, extended sequential and progressive: the codings a PDF viewer's DCTDecode reads. */
+const DCT_CODINGS = new Set([0xffc0, 0xffc1, 0xffc2]);
+/** The color of a JPEG as it is embedded (`DCTDecode`): the space it was saved in. */
+export function jpegColor(bytes) {
+    const header = jpegHeader(new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+    if (!DCT_CODINGS.has(header.sof)) {
+        throw new JpegFormatError("this JPEG is lossless, hierarchical or arithmetic-coded, which PDF viewers cannot decode. " +
+            "Save it again as a baseline or progressive JPEG, or as a PNG.");
+    }
+    switch (header.components) {
+        case 1:
+            return { space: "gray" };
+        case 3:
+            return { space: "rgb" };
+        case 4:
+            return header.adobe ? { space: "cmyk", inverted: true } : { space: "cmyk" };
+        default:
+            throw new JpegFormatError(`this JPEG has ${header.components} color channels; only gray, RGB and CMYK are embedded.`);
+    }
+}
+/** Read from the header alone, synchronously - layout can ask it. */
+export function readImageDimensions(buffer) {
+    // The view's own window: a `Uint8Array` may be a slice of a larger buffer (a Node `Buffer` usually is).
+    const dataView = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    if (dataView.getUint16(0) === 0xffd8) {
+        const { width, height, dpi, orientation } = jpegHeader(dataView);
+        return { width, height, ...(dpi ? { dpi } : {}), ...(orientation ? { orientation } : {}) };
     }
     // Check for PNG (0x89504E47 is the PNG signature)
     if (dataView.getUint32(0) === 0x89504e47) {
+        const dpi = tryRead(() => pngResolution(dataView));
         return {
             width: dataView.getUint32(16, false),
             height: dataView.getUint32(20, false),
+            ...(dpi ? { dpi } : {}),
         };
     }
     // Check for BMP (0x424D is the BMP signature)
@@ -122,75 +289,36 @@ export async function convertImageToGrayscaleBuffer(imagePath) {
     const grayscaleBuffer = await image.getBuffer(mimeType);
     return grayscaleBuffer;
 }
-export function applyContainFit(imageWidth, imageHeight, containerWidth, containerHeight) {
-    const imageAspectRatio = imageWidth / imageHeight;
-    const containerAspectRatio = containerWidth / containerHeight;
-    let width, height, offsetX, offsetY;
-    if (imageAspectRatio > containerAspectRatio) {
-        // The images width is bigger than the containers width
-        const scaleFactor = containerWidth / imageWidth;
-        width = containerWidth;
-        height = imageHeight * scaleFactor;
-        offsetX = 0;
-        offsetY = (containerHeight - height) / 2; // Center vertically
-    }
-    else {
-        // THe images height is bigge rthan the containers height
-        const scaleFactor = containerHeight / imageHeight;
-        width = imageWidth * scaleFactor;
-        height = containerHeight;
-        offsetX = (containerWidth - width) / 2; // Center horizontally
-        offsetY = 0;
-    }
+const CENTER = { x: 0.5, y: 0.5 };
+/** The one place a fitted image is positioned: what is left over (or overhangs) is split by `align`. */
+function placed(width, height, containerWidth, containerHeight, align) {
     return {
         width,
         height,
-        offsetX,
-        offsetY,
+        offsetX: (containerWidth - width) * align.x,
+        offsetY: (containerHeight - height) * align.y,
     };
 }
-export function applyCoverFit(imageWidth, imageHeight, containerWidth, containerHeight) {
-    const imageAspectRatio = imageWidth / imageHeight;
-    const containerAspectRatio = containerWidth / containerHeight;
-    let width, height, offsetX, offsetY;
-    if (imageAspectRatio > containerAspectRatio) {
-        // The images width is bigger than containers width
-        const scaleFactor = containerHeight / imageHeight;
-        width = imageWidth * scaleFactor;
-        height = containerHeight;
-        offsetX = (containerWidth - width) / 2; // Center horizontally
-        offsetY = 0;
-    }
-    else {
-        // The images height is bigger than containers height
-        const scaleFactor = containerWidth / imageWidth;
-        width = containerWidth;
-        height = imageHeight * scaleFactor;
-        offsetX = 0;
-        offsetY = (containerHeight - height) / 2; // Center vertically
-    }
-    return {
-        width,
-        height,
-        offsetX,
-        offsetY,
-    };
+/** Scaled by the width's or the height's factor; that axis takes the box's extent exactly. */
+function scaled(imageWidth, imageHeight, containerWidth, containerHeight, align, byWidthWins) {
+    const byWidth = containerWidth / imageWidth;
+    const byHeight = containerHeight / imageHeight;
+    return byWidthWins(byWidth, byHeight)
+        ? placed(containerWidth, imageHeight * byWidth, containerWidth, containerHeight, align)
+        : placed(imageWidth * byHeight, containerHeight, containerWidth, containerHeight, align);
+}
+/** Scaled to fit inside the box, whole image visible. */
+export function applyContainFit(imageWidth, imageHeight, containerWidth, containerHeight, align = CENTER) {
+    return scaled(imageWidth, imageHeight, containerWidth, containerHeight, align, (w, h) => w < h);
+}
+/** Scaled to cover the box, the overhang cut off. */
+export function applyCoverFit(imageWidth, imageHeight, containerWidth, containerHeight, align = CENTER) {
+    return scaled(imageWidth, imageHeight, containerWidth, containerHeight, align, (w, h) => w >= h);
 }
 export function applyFillFit(containerWidth, containerHeight) {
-    return {
-        width: containerWidth,
-        height: containerHeight,
-        offsetX: 0,
-        offsetY: 0,
-    };
+    return { width: containerWidth, height: containerHeight, offsetX: 0, offsetY: 0 };
 }
-export function applyFitNone(imageWidth, imageHeight, containerWidth, containerHeight) {
-    const offsetX = (containerWidth - imageWidth) / 2; // Center horizontally
-    const offsetY = (containerHeight - imageHeight) / 2; // Center vertically
-    return {
-        width: imageWidth, // Hold orignal image size
-        height: imageHeight,
-        offsetX: offsetX > 0 ? offsetX : 0, // Dont move outside the container...
-        offsetY: offsetY > 0 ? offsetY : 0,
-    };
+/** At its own size (`naturalSize`), the overhang cut off. */
+export function applyFitNone(imageWidth, imageHeight, containerWidth, containerHeight, align = CENTER) {
+    return placed(imageWidth, imageHeight, containerWidth, containerHeight, align);
 }

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

@@ -12,6 +12,8 @@ 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";
+import { Diagnostics } from "../common/diagnostics.js";
+import { type ImageColor } from "./image-helper.js";
 interface FontIndexes {
     fontIndex: number;
     resourceIndex: number;
@@ -44,8 +46,8 @@ export declare class PDFObjectManager implements FontMetrics {
     /** Shaped runs, cached face -> feature set -> text. Nested, not one map under a composed key: that
      *  key would carry the whole run's text, so every lookup would copy it into a fresh string. */
     private shapeCache;
-    /** Bumped by every font registration; `runAdvance` watches it to drop memoised widths, since a
-     *  family name can mean a different face afterwards. */
+    /** Bumped when a face is really ADDED (a repeat registration returns early, untouched); every
+     *  memoised measurement watches it, since a family name can mean a different face afterwards. */
     fontEpoch: number;
     private shapedOrigins;
     private attachments;
@@ -78,7 +80,9 @@ export declare class PDFObjectManager implements FontMetrics {
      * character went missing instead of a server log nobody reads.
      */
     private readonly missingGlyphs;
-    reportMissingGlyph(codePoints: number[]): void;
+    reportMissingGlyph(codePoints: number[], about?: object, page?: number): void;
+    /** The render's diagnostics channel (`onDiagnostic`); see `common/diagnostics.ts`. */
+    readonly diagnostics: Diagnostics;
     /** The dropped code points, in the order first seen. Empty for a document that hit none. */
     getMissingGlyphs(): number[];
     setOverflowPolicy(policy: OverflowPolicy): void;
@@ -97,6 +101,11 @@ export declare class PDFObjectManager implements FontMetrics {
      * A string INSIDE a content stream needs none of this - the stream is enciphered as a whole.
      */
     pdfString(text: string): string;
+    /**
+     * A URI: 7-bit ASCII by definition, so anything else is percent-encoded as UTF-8 - the way a browser
+     * writes the link - rather than squeezed into a text encoding.
+     */
+    pdfUri(uri: string): string;
     private streamPayload;
     private stream;
     addContentStream(content: string): number;
@@ -107,7 +116,7 @@ export declare class PDFObjectManager implements FontMetrics {
     private getCurrentByteLength;
     setParentObjectNumber(number: number): void;
     getParentObjectNumber(): number;
-    registerImage(width: number, height: number, imageType: string, imageData: string, smaskData?: string): number;
+    registerImage(width: number, height: number, imageType: string, imageData: string, smaskData?: string, color?: ImageColor): number;
     attachFile(name: string, data: Uint8Array, opts?: {
         relationship?: string;
         mimeType?: string;
@@ -159,7 +168,7 @@ export declare class PDFObjectManager implements FontMetrics {
      */
     hasGlyph(codePoint: number, fontFamily: string, fontStyle?: FontStyle): boolean;
     /**
-     * Whether the document draws this code point through the colour-emoji path instead of the text
+     * Whether the document draws this code point through the color-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.
@@ -199,7 +208,9 @@ export declare class PDFObjectManager implements FontMetrics {
      * `GPOS` tables are unparsed), so it returns zeros - never a wrong value, just no adjustment.
      */
     /** Kerning between adjacent GLYPHS - what a shaped run needs, and what the backend already holds.
-     *  Same lookup as the character path; `getKerning` is keyed by glyph id either way. */
+     *  Same lookup as the character path; `getKerning` is keyed by glyph id either way. A pair that
+     *  touches a space is never kerned, as on the character path: the line breaker measures words and
+     *  spaces apart, so a pair across a space would be drawn but never measured. */
     getGlyphKernPairs(glyphs: readonly number[], fontFamily: string, fontStyle: FontStyle): number[];
     getKernPairs(text: string, fontFamily: string, fontStyle: FontStyle, ligatures?: boolean): number[];
     /**