@stll/folio-core 0.32.2 → 0.33.0

package/dist/pdf/images.js

@@ -0,0 +1,439 @@
+import { pdfArray, pdfHexString, pdfName, pdfNumber } from "./objects.js";
+import { Result, TaggedError } from "better-result";
+import { inflateSync } from "node:zlib";
+//#region src/pdf/images.ts
+/**
+* Image decoding for PDF image XObjects.
+*
+* JPEG bytes go into the file untouched under `/DCTDecode`: re-encoding a
+* lossy image to paint it is a fidelity loss with nothing to gain. PNG is
+* decoded only as far as PDF needs, which is less far than a rasterizer
+* would go: the filters are reversed and the samples handed over as they are,
+* so a 4-bit palette image stays 4-bit and an alpha channel becomes an
+* `/SMask` rather than being composited against a guess at the backdrop.
+*
+* A form this module cannot represent exactly (16-bit samples, interlacing)
+* is an error, never an approximation: painting the wrong pixels silently is
+* worse than refusing the page.
+*/
+var PdfImageError = class extends TaggedError("PdfImageError") {};
+const PNG_SIGNATURE = [
+	137,
+	80,
+	78,
+	71,
+	13,
+	10,
+	26,
+	10
+];
+const PNG_COLOR_TYPE = {
+	greyscale: 0,
+	rgb: 2,
+	palette: 3,
+	greyscaleAlpha: 4,
+	rgba: 6
+};
+const CHANNELS_PER_COLOR_TYPE = {
+	[PNG_COLOR_TYPE.greyscale]: 1,
+	[PNG_COLOR_TYPE.rgb]: 3,
+	[PNG_COLOR_TYPE.palette]: 1,
+	[PNG_COLOR_TYPE.greyscaleAlpha]: 2,
+	[PNG_COLOR_TYPE.rgba]: 4
+};
+const FULLY_OPAQUE = 255;
+const EIGHT_BIT = 8;
+const toHex = (bytes) => {
+	let out = "";
+	for (const byte of bytes) out += byte.toString(16).padStart(2, "0").toUpperCase();
+	return out;
+};
+const readPngChunks = (bytes) => {
+	for (let index = 0; index < PNG_SIGNATURE.length; index += 1) if (bytes[index] !== PNG_SIGNATURE[index]) return Result.err(new PdfImageError({ message: "not a PNG: bad signature" }));
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let header = null;
+	let palette = null;
+	let transparency = null;
+	const idat = [];
+	let cursor = PNG_SIGNATURE.length;
+	const CHUNK_HEADER_BYTES = 8;
+	const CHUNK_CRC_BYTES = 4;
+	while (cursor + CHUNK_HEADER_BYTES <= bytes.length) {
+		const length = view.getUint32(cursor);
+		const type = String.fromCharCode(bytes[cursor + 4] ?? 0, bytes[cursor + 5] ?? 0, bytes[cursor + 6] ?? 0, bytes[cursor + 7] ?? 0);
+		const dataStart = cursor + CHUNK_HEADER_BYTES;
+		const dataEnd = dataStart + length;
+		if (dataEnd > bytes.length) return Result.err(new PdfImageError({ message: `PNG chunk ${type} runs past the end` }));
+		const data = bytes.subarray(dataStart, dataEnd);
+		if (type === "IHDR") header = data;
+		else if (type === "PLTE") palette = data;
+		else if (type === "tRNS") transparency = data;
+		else if (type === "IDAT") idat.push(data);
+		else if (type === "IEND") break;
+		cursor = dataEnd + CHUNK_CRC_BYTES;
+	}
+	if (header === null || header.length < 13) return Result.err(new PdfImageError({ message: "PNG has no IHDR" }));
+	if (idat.length === 0) return Result.err(new PdfImageError({ message: "PNG has no IDAT" }));
+	const totalPixelBytes = idat.reduce((sum, chunk) => sum + chunk.length, 0);
+	const pixels = new Uint8Array(totalPixelBytes);
+	let pixelCursor = 0;
+	for (const chunk of idat) {
+		pixels.set(chunk, pixelCursor);
+		pixelCursor += chunk.length;
+	}
+	return Result.ok({
+		header,
+		palette,
+		transparency,
+		pixels
+	});
+};
+const paeth = (left, above, upperLeft) => {
+	const estimate = left + above - upperLeft;
+	const distanceLeft = Math.abs(estimate - left);
+	const distanceAbove = Math.abs(estimate - above);
+	const distanceUpperLeft = Math.abs(estimate - upperLeft);
+	if (distanceLeft <= distanceAbove && distanceLeft <= distanceUpperLeft) return left;
+	return distanceAbove <= distanceUpperLeft ? above : upperLeft;
+};
+/**
+* Reverses the five PNG filter types in place over a copy, leaving the
+* scanlines byte-aligned exactly as PDF expects them.
+*/
+const unfilterPng = ({ filtered, bytesPerRow, bytesPerPixel, height }) => {
+	const expected = height * (bytesPerRow + 1);
+	if (filtered.length < expected) return Result.err(new PdfImageError({ message: `PNG pixel data is ${String(filtered.length)} bytes, expected ${String(expected)}` }));
+	const out = new Uint8Array(height * bytesPerRow);
+	for (let row = 0; row < height; row += 1) {
+		const filterType = filtered[row * (bytesPerRow + 1)] ?? 0;
+		const source = row * (bytesPerRow + 1) + 1;
+		const target = row * bytesPerRow;
+		const previous = target - bytesPerRow;
+		for (let index = 0; index < bytesPerRow; index += 1) {
+			const raw = filtered[source + index] ?? 0;
+			const left = index >= bytesPerPixel ? out[target + index - bytesPerPixel] ?? 0 : 0;
+			const above = row > 0 ? out[previous + index] ?? 0 : 0;
+			const upperLeft = row > 0 && index >= bytesPerPixel ? out[previous + index - bytesPerPixel] ?? 0 : 0;
+			let value;
+			switch (filterType) {
+				case 0:
+					value = raw;
+					break;
+				case 1:
+					value = raw + left;
+					break;
+				case 2:
+					value = raw + above;
+					break;
+				case 3:
+					value = raw + (left + above >> 1);
+					break;
+				case 4:
+					value = raw + paeth(left, above, upperLeft);
+					break;
+				default: return Result.err(new PdfImageError({ message: `unknown PNG filter type ${String(filterType)}` }));
+			}
+			out[target + index] = value & 255;
+		}
+	}
+	return Result.ok(out);
+};
+/** One byte per pixel index, for sub-byte palette and greyscale depths. */
+const expandIndices = ({ rows, bytesPerRow, width, height, bitDepth }) => {
+	if (bitDepth === EIGHT_BIT) return rows;
+	const out = new Uint8Array(width * height);
+	const perByte = EIGHT_BIT / bitDepth;
+	const mask = (1 << bitDepth) - 1;
+	for (let row = 0; row < height; row += 1) for (let column = 0; column < width; column += 1) {
+		const byte = rows[row * bytesPerRow + Math.floor(column / perByte)] ?? 0;
+		const shift = EIGHT_BIT - bitDepth * (column % perByte + 1);
+		out[row * width + column] = byte >> shift & mask;
+	}
+	return out;
+};
+const decodePng = (bytes) => {
+	const chunks = readPngChunks(bytes);
+	if (chunks.isErr()) return Result.err(chunks.error);
+	const { header, palette, transparency, pixels } = chunks.value;
+	const headerView = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	const width = headerView.getUint32(0);
+	const height = headerView.getUint32(4);
+	const bitDepth = header[8] ?? 0;
+	const colorType = header[9] ?? 0;
+	const interlace = header[12] ?? 0;
+	if (width === 0 || height === 0) return Result.err(new PdfImageError({ message: "PNG has a zero dimension" }));
+	if (interlace !== 0) return Result.err(new PdfImageError({ message: "interlaced PNG is not supported" }));
+	const channels = CHANNELS_PER_COLOR_TYPE[colorType];
+	if (channels === void 0) return Result.err(new PdfImageError({ message: `unknown PNG colour type ${String(colorType)}` }));
+	if (!(colorType === PNG_COLOR_TYPE.greyscale || colorType === PNG_COLOR_TYPE.palette ? [
+		1,
+		2,
+		4,
+		EIGHT_BIT
+	].includes(bitDepth) : bitDepth === EIGHT_BIT)) return Result.err(new PdfImageError({ message: `PNG bit depth ${String(bitDepth)} with colour type ${String(colorType)} is not supported` }));
+	const bitsPerPixel = bitDepth * channels;
+	const bytesPerRow = Math.ceil(bitsPerPixel * width / EIGHT_BIT);
+	const bytesPerPixel = Math.max(1, Math.ceil(bitsPerPixel / EIGHT_BIT));
+	const inflatedBytesExpected = height * (bytesPerRow + 1);
+	const inflated = Result.try({
+		try: () => inflateSync(pixels, { maxOutputLength: inflatedBytesExpected }),
+		catch: (cause) => new PdfImageError({ message: `PNG IDAT does not inflate to the ${String(inflatedBytesExpected)} bytes its IHDR declares: ${cause instanceof Error ? cause.message : String(cause)}` })
+	});
+	if (inflated.isErr()) return Result.err(inflated.error);
+	const filtered = new Uint8Array(inflated.value.buffer, inflated.value.byteOffset, inflated.value.byteLength);
+	const unfiltered = unfilterPng({
+		filtered,
+		bytesPerRow,
+		bytesPerPixel,
+		height
+	});
+	if (unfiltered.isErr()) return Result.err(unfiltered.error);
+	const rows = unfiltered.value;
+	const pixelCount = width * height;
+	switch (colorType) {
+		case PNG_COLOR_TYPE.greyscale:
+		case PNG_COLOR_TYPE.rgb: {
+			const isRgb = colorType === PNG_COLOR_TYPE.rgb;
+			let alpha;
+			if (transparency !== null) {
+				const built = buildColorKeyAlpha({
+					rows,
+					bitDepth,
+					bytesPerRow,
+					width,
+					height,
+					components: isRgb ? 3 : 1,
+					key: isRgb ? [
+						transparency[1] ?? 0,
+						transparency[3] ?? 0,
+						transparency[5] ?? 0
+					] : [transparency[1] ?? 0]
+				});
+				if (built.isErr()) return Result.err(built.error);
+				alpha = built.value;
+			}
+			return Result.ok({
+				widthPx: width,
+				heightPx: height,
+				bitsPerComponent: isRgb ? EIGHT_BIT : bitDepth,
+				colorSpace: pdfName(isRgb ? "DeviceRGB" : "DeviceGray"),
+				encoding: "raw",
+				data: rows,
+				...alpha === void 0 ? {} : { alpha }
+			});
+		}
+		case PNG_COLOR_TYPE.palette: {
+			if (palette === null) return Result.err(new PdfImageError({ message: "palette PNG has no PLTE chunk" }));
+			const entries = Math.floor(palette.length / 3);
+			const colorSpace = pdfArray([
+				pdfName("Indexed"),
+				pdfName("DeviceRGB"),
+				pdfNumber(entries - 1),
+				pdfHexString(toHex(palette))
+			]);
+			let alpha;
+			if (transparency !== null) {
+				const indices = expandIndices({
+					rows,
+					bytesPerRow,
+					width,
+					height,
+					bitDepth
+				});
+				const data = new Uint8Array(pixelCount);
+				for (let index = 0; index < pixelCount; index += 1) data[index] = transparency[indices[index] ?? 0] ?? FULLY_OPAQUE;
+				alpha = {
+					data,
+					bitsPerComponent: EIGHT_BIT
+				};
+			}
+			return Result.ok({
+				widthPx: width,
+				heightPx: height,
+				bitsPerComponent: bitDepth,
+				colorSpace,
+				encoding: "raw",
+				data: rows,
+				...alpha === void 0 ? {} : { alpha }
+			});
+		}
+		case PNG_COLOR_TYPE.greyscaleAlpha:
+		case PNG_COLOR_TYPE.rgba: {
+			const colorComponents = colorType === PNG_COLOR_TYPE.rgba ? 3 : 1;
+			const color = new Uint8Array(pixelCount * colorComponents);
+			const alphaData = new Uint8Array(pixelCount);
+			for (let index = 0; index < pixelCount; index += 1) {
+				const source = index * (colorComponents + 1);
+				for (let component = 0; component < colorComponents; component += 1) color[index * colorComponents + component] = rows[source + component] ?? 0;
+				alphaData[index] = rows[source + colorComponents] ?? FULLY_OPAQUE;
+			}
+			return Result.ok({
+				widthPx: width,
+				heightPx: height,
+				bitsPerComponent: EIGHT_BIT,
+				colorSpace: pdfName(colorComponents === 3 ? "DeviceRGB" : "DeviceGray"),
+				encoding: "raw",
+				data: color,
+				alpha: {
+					data: alphaData,
+					bitsPerComponent: EIGHT_BIT
+				}
+			});
+		}
+		default: return Result.err(new PdfImageError({ message: `unknown PNG colour type ${String(colorType)}` }));
+	}
+};
+/**
+* `tRNS` on a truecolour or greyscale PNG names one fully transparent sample
+* value. PDF has no colour-key transparency for image XObjects, so it becomes
+* a soft mask.
+*/
+const buildColorKeyAlpha = ({ rows, bitDepth, bytesPerRow, width, height, components, key }) => {
+	if (bitDepth !== EIGHT_BIT) return Result.err(new PdfImageError({ message: `tRNS on a ${String(bitDepth)}-bit non-palette PNG is not supported` }));
+	const data = new Uint8Array(width * height);
+	for (let row = 0; row < height; row += 1) for (let column = 0; column < width; column += 1) {
+		const source = row * bytesPerRow + column * components;
+		let matches = true;
+		for (let component = 0; component < components; component += 1) if ((rows[source + component] ?? 0) !== (key[component] ?? 0)) {
+			matches = false;
+			break;
+		}
+		data[row * width + column] = matches ? 0 : FULLY_OPAQUE;
+	}
+	return Result.ok({
+		data,
+		bitsPerComponent: EIGHT_BIT
+	});
+};
+const JPEG_COMPONENTS_TO_COLOR_SPACE = {
+	1: "DeviceGray",
+	3: "DeviceRGB",
+	4: "DeviceCMYK"
+};
+const CMYK_INVERTED_DECODE = [
+	1,
+	0,
+	1,
+	0,
+	1,
+	0,
+	1,
+	0
+];
+/**
+* The frame headers of the 0xC0..0xCF marker block, minus DHT (0xC4) and DAC
+* (0xCC), which are tables rather than frames. `/DCTDecode` is defined over
+* the Huffman-coded sequential and progressive modes only; a lossless,
+* arithmetic-coded or hierarchical frame passed through unchanged is a stream
+* no viewer can decode, so it is refused by name. Reading geometry is as far
+* as this decoder goes either way: it never transcodes a frame it accepts.
+*/
+const JPEG_FRAME_MODES = {
+	192: {
+		name: "baseline DCT",
+		dctDecodable: true
+	},
+	193: {
+		name: "extended sequential DCT",
+		dctDecodable: true
+	},
+	194: {
+		name: "progressive DCT",
+		dctDecodable: true
+	},
+	195: {
+		name: "lossless",
+		dctDecodable: false
+	},
+	197: {
+		name: "differential sequential DCT",
+		dctDecodable: false
+	},
+	198: {
+		name: "differential progressive DCT",
+		dctDecodable: false
+	},
+	199: {
+		name: "differential lossless",
+		dctDecodable: false
+	},
+	200: {
+		name: "reserved JPG extension",
+		dctDecodable: false
+	},
+	201: {
+		name: "arithmetic extended sequential DCT",
+		dctDecodable: false
+	},
+	202: {
+		name: "arithmetic progressive DCT",
+		dctDecodable: false
+	},
+	203: {
+		name: "arithmetic lossless",
+		dctDecodable: false
+	},
+	205: {
+		name: "differential arithmetic sequential DCT",
+		dctDecodable: false
+	},
+	206: {
+		name: "differential arithmetic progressive DCT",
+		dctDecodable: false
+	},
+	207: {
+		name: "differential arithmetic lossless",
+		dctDecodable: false
+	}
+};
+const decodeJpeg = (bytes) => {
+	const MARKER_PREFIX = 255;
+	const START_OF_IMAGE = 216;
+	const START_OF_SCAN = 218;
+	const APP14 = 238;
+	if (bytes[0] !== MARKER_PREFIX || bytes[1] !== START_OF_IMAGE) return Result.err(new PdfImageError({ message: "not a JPEG: bad SOI marker" }));
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let cursor = 2;
+	let adobe = false;
+	while (cursor + 4 <= bytes.length) {
+		if (bytes[cursor] !== MARKER_PREFIX) return Result.err(new PdfImageError({ message: "JPEG marker segment is out of step" }));
+		const marker = bytes[cursor + 1] ?? 0;
+		if (marker === START_OF_SCAN) break;
+		const length = view.getUint16(cursor + 2);
+		const segment = cursor + 4;
+		const frame = JPEG_FRAME_MODES[marker];
+		if (marker === APP14 && length >= 12) adobe = String.fromCharCode(...bytes.subarray(segment, segment + 5)) === "Adobe";
+		if (frame !== void 0) {
+			if (!frame.dctDecodable) return Result.err(new PdfImageError({ message: `JPEG ${frame.name} frame (marker 0xff${marker.toString(16)}) has no /DCTDecode equivalent` }));
+			const height = view.getUint16(segment + 1);
+			const width = view.getUint16(segment + 3);
+			const components = bytes[segment + 5] ?? 0;
+			const colorSpace = JPEG_COMPONENTS_TO_COLOR_SPACE[components];
+			if (colorSpace === void 0) return Result.err(new PdfImageError({ message: `JPEG with ${String(components)} components is not supported` }));
+			const inverted = components === 4 && adobe;
+			return Result.ok({
+				widthPx: width,
+				heightPx: height,
+				bitsPerComponent: EIGHT_BIT,
+				colorSpace: pdfName(colorSpace),
+				encoding: "jpeg",
+				data: bytes,
+				...inverted ? { decode: CMYK_INVERTED_DECODE } : {}
+			});
+		}
+		cursor += 2 + length;
+	}
+	return Result.err(new PdfImageError({ message: "JPEG has no frame header" }));
+};
+const decodeImage = (source) => {
+	switch (source.format) {
+		case "png": return decodePng(source.bytes);
+		case "jpeg": return decodeJpeg(source.bytes);
+		default: {
+			const unreachable = source.format;
+			return Result.err(new PdfImageError({ message: `unsupported image format ${String(unreachable)}` }));
+		}
+	}
+};
+//#endregion
+export { PdfImageError, decodeImage };

package/dist/pdf/objects.d.ts

@@ -0,0 +1,93 @@
+//#region src/pdf/objects.d.ts
+/**
+ * The PDF object model: values, serialization, the cross-reference table and
+ * the trailer.
+ *
+ * Everything a backend writes into a PDF file passes through here, which is
+ * what makes byte-for-byte determinism enforceable rather than aspirational:
+ * numbers go through one formatter, dictionaries carry their entries as an
+ * ordered list (never an object or a `Map` whose iteration order depends on
+ * how it was built), and object numbers come from one allocator in call
+ * order.
+ */
+/** The one number formatter. Every number in the file is emitted through it. */
+declare const formatNumber: (value: number) => string;
+type PdfRef = {
+  readonly kind: "ref";
+  readonly id: number;
+};
+type PdfDictEntry = readonly [string, PdfValue];
+type PdfDict = {
+  readonly kind: "dict";
+  readonly entries: readonly PdfDictEntry[];
+};
+type PdfStream = {
+  readonly kind: "stream";
+  readonly dict: PdfDict;
+  readonly data: Uint8Array;
+};
+type PdfValue = {
+  readonly kind: "null";
+} | {
+  readonly kind: "bool";
+  readonly value: boolean;
+} | {
+  readonly kind: "number";
+  readonly value: number;
+} | {
+  readonly kind: "name";
+  readonly value: string;
+} |
+/** A byte string: every code unit must be < 256 (URIs, dates, CMap names). */
+{
+  readonly kind: "asciiString";
+  readonly value: string;
+} |
+/** A text string, emitted as UTF-16BE with a BOM so any script survives. */
+{
+  readonly kind: "textString";
+  readonly value: string;
+} |
+/** Pre-formatted hex digits, for values that are already bytes (`/ID`). */
+{
+  readonly kind: "hexString";
+  readonly value: string;
+} | {
+  readonly kind: "array";
+  readonly items: readonly PdfValue[];
+} | PdfDict | PdfStream | PdfRef;
+declare const pdfNull: PdfValue;
+declare const pdfBool: (value: boolean) => PdfValue;
+declare const pdfNumber: (value: number) => PdfValue;
+declare const pdfName: (value: string) => PdfValue;
+declare const pdfAsciiString: (value: string) => PdfValue;
+declare const pdfTextString: (value: string) => PdfValue;
+declare const pdfHexString: (value: string) => PdfValue;
+declare const pdfArray: (items: readonly PdfValue[]) => PdfValue;
+declare const pdfNumberArray: (values: readonly number[]) => PdfValue;
+/**
+ * Entries keep the order they are written in, and an `undefined` value drops
+ * the key entirely: an optional entry is either present with a value or
+ * absent, never `/Key null`.
+ */
+declare const pdfDict: (entries: readonly (readonly [string, PdfValue | undefined])[]) => PdfDict;
+declare const pdfStream: (dict: PdfDict, data: Uint8Array) => PdfStream;
+declare const deflateForPdf: (data: Uint8Array) => Uint8Array;
+/** A `/FlateDecode` stream: the one place raw bytes become a compressed one. */
+declare const pdfFlateStream: (entries: readonly (readonly [string, PdfValue | undefined])[], data: Uint8Array) => PdfStream;
+type PdfDocumentOptions = {
+  readonly rootRef: PdfRef;
+  readonly infoRef: PdfRef;
+  /** Two copies of this hex digest become `/ID`. */
+  readonly idHex: (bodyBytes: Uint8Array) => string;
+};
+type PdfDocument = {
+  /** Reserves an object number; the value may be supplied later. */
+  readonly allocate: () => PdfRef;
+  readonly define: (ref: PdfRef, value: PdfValue) => void;
+  readonly add: (value: PdfValue) => PdfRef;
+  readonly serialize: (options: PdfDocumentOptions) => Uint8Array;
+};
+declare const createPdfDocument: () => PdfDocument;
+//#endregion
+export { PdfDict, PdfDictEntry, PdfDocument, PdfDocumentOptions, PdfRef, PdfStream, PdfValue, createPdfDocument, deflateForPdf, formatNumber, pdfArray, pdfAsciiString, pdfBool, pdfDict, pdfFlateStream, pdfHexString, pdfName, pdfNull, pdfNumber, pdfNumberArray, pdfStream, pdfTextString };