@stll/folio-core 0.32.1 → 0.33.0

package/dist/pdf/objects.js

@@ -0,0 +1,237 @@
+import { panic } from "better-result";
+import { deflateSync } from "node:zlib";
+//#region src/pdf/objects.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.
+*/
+/**
+* PDF reals carry roughly five significant digits; four decimals on a
+* coordinate in points is a third of a micron, far below anything a
+* rasterizer resolves. Fixing the precision here is what makes two runs that
+* computed the same coordinate by different arithmetic routes emit the same
+* bytes.
+*/
+const NUMBER_DECIMALS = 4;
+/**
+* No page coordinate, font metric or matrix entry folio produces comes near
+* this. Past it `toFixed` switches to exponent notation, which PDF readers do
+* not accept, so a value this large is a producer bug and not something to
+* paint approximately.
+*/
+const MAX_ABS_NUMBER = 1e10;
+/** The one number formatter. Every number in the file is emitted through it. */
+const formatNumber = (value) => {
+	if (!Number.isFinite(value)) panic(`PDF numbers must be finite, got ${String(value)}`);
+	if (Math.abs(value) > MAX_ABS_NUMBER) panic(`PDF number out of range: ${String(value)}`);
+	const trimmed = value.toFixed(NUMBER_DECIMALS).replace(/0+$/u, "").replace(/\.$/u, "");
+	return trimmed === "" || trimmed === "-" || trimmed === "-0" ? "0" : trimmed;
+};
+const pdfNull = { kind: "null" };
+const pdfBool = (value) => ({
+	kind: "bool",
+	value
+});
+const pdfNumber = (value) => ({
+	kind: "number",
+	value
+});
+const pdfName = (value) => ({
+	kind: "name",
+	value
+});
+const pdfAsciiString = (value) => ({
+	kind: "asciiString",
+	value
+});
+const pdfTextString = (value) => ({
+	kind: "textString",
+	value
+});
+const pdfHexString = (value) => ({
+	kind: "hexString",
+	value
+});
+const pdfArray = (items) => ({
+	kind: "array",
+	items
+});
+const pdfNumberArray = (values) => pdfArray(values.map(pdfNumber));
+/**
+* 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`.
+*/
+const pdfDict = (entries) => ({
+	kind: "dict",
+	entries: entries.filter((entry) => entry[1] !== void 0)
+});
+const pdfStream = (dict, data) => ({
+	kind: "stream",
+	dict,
+	data
+});
+/**
+* zlib's output depends on the compression level, so it is fixed rather than
+* left to the default: two runs of the writer must agree byte for byte, and
+* "whatever zlib felt like" is not an agreement.
+*/
+const DEFLATE_LEVEL = 9;
+const deflateForPdf = (data) => {
+	const deflated = deflateSync(data, { level: DEFLATE_LEVEL });
+	return new Uint8Array(deflated.buffer, deflated.byteOffset, deflated.byteLength);
+};
+/** A `/FlateDecode` stream: the one place raw bytes become a compressed one. */
+const pdfFlateStream = (entries, data) => pdfStream(pdfDict([...entries, ["Filter", pdfName("FlateDecode")]]), deflateForPdf(data));
+/** Regular characters may appear in a name unescaped; everything else is `#xx`. */
+const NAME_REGULAR = /^[A-Za-z0-9._\-+]$/u;
+const encodeName = (value) => {
+	let out = "/";
+	for (const char of value) out += NAME_REGULAR.test(char) ? char : `#${char.charCodeAt(0).toString(16).padStart(2, "0").toUpperCase()}`;
+	return out;
+};
+const encodeAsciiString = (value) => {
+	let out = "(";
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code > 255) panic(`byte string carries a code point above 0xFF: ${value}`);
+		if (code === 40 || code === 41 || code === 92) out += `\\${String.fromCharCode(code)}`;
+		else if (code < 32 || code > 126) out += `\\${code.toString(8).padStart(3, "0")}`;
+		else out += String.fromCharCode(code);
+	}
+	return `${out})`;
+};
+const encodeTextString = (value) => {
+	let hex = "FEFF";
+	for (let index = 0; index < value.length; index += 1) hex += value.charCodeAt(index).toString(16).padStart(4, "0").toUpperCase();
+	return `<${hex}>`;
+};
+const createByteSink = () => {
+	const chunks = [];
+	let length = 0;
+	const writeBytes = (bytes) => {
+		chunks.push(bytes);
+		length += bytes.length;
+	};
+	return {
+		writeAscii: (text) => {
+			const bytes = new Uint8Array(text.length);
+			for (let index = 0; index < text.length; index += 1) bytes[index] = text.charCodeAt(index) & 255;
+			writeBytes(bytes);
+		},
+		writeBytes,
+		offset: () => length,
+		toBytes: () => {
+			const out = new Uint8Array(length);
+			let cursor = 0;
+			for (const chunk of chunks) {
+				out.set(chunk, cursor);
+				cursor += chunk.length;
+			}
+			return out;
+		}
+	};
+};
+/** Serializes everything except a stream's payload, which is raw bytes. */
+const serializeValue = (value) => {
+	switch (value.kind) {
+		case "null": return "null";
+		case "bool": return value.value ? "true" : "false";
+		case "number": return formatNumber(value.value);
+		case "name": return encodeName(value.value);
+		case "asciiString": return encodeAsciiString(value.value);
+		case "textString": return encodeTextString(value.value);
+		case "hexString": return `<${value.value}>`;
+		case "array": return `[${value.items.map(serializeValue).join(" ")}]`;
+		case "dict": return `<<${value.entries.map(([key, entry]) => `${encodeName(key)} ${serializeValue(entry)}`).join(" ")}>>`;
+		case "stream": return panic("a stream must be an indirect object, not a nested value");
+		case "ref": return `${String(value.id)} 0 R`;
+		default: return panic(`unhandled PDF value: ${JSON.stringify(value)}`);
+	}
+};
+const PDF_HEADER = "%PDF-1.7\n";
+/**
+* A comment whose bytes are all above 127 tells any tool that transfers the
+* file that it is binary. The four bytes are the conventional ones.
+*/
+const BINARY_MARKER = new Uint8Array([
+	37,
+	226,
+	227,
+	207,
+	211,
+	10
+]);
+const XREF_FREE_ENTRY = "0000000000 65535 f \n";
+const createPdfDocument = () => {
+	const values = /* @__PURE__ */ new Map();
+	let nextId = 1;
+	const allocate = () => {
+		const ref = {
+			kind: "ref",
+			id: nextId
+		};
+		nextId += 1;
+		return ref;
+	};
+	const define = (ref, value) => {
+		if (values.has(ref.id)) panic(`PDF object ${String(ref.id)} defined twice`);
+		values.set(ref.id, value);
+	};
+	const writeObject = (sink, id, value) => {
+		sink.writeAscii(`${String(id)} 0 obj\n`);
+		if (value.kind === "stream") {
+			const withLength = pdfDict([...value.dict.entries, ["Length", pdfNumber(value.data.length)]]);
+			sink.writeAscii(`${serializeValue(withLength)}\nstream\n`);
+			sink.writeBytes(value.data);
+			sink.writeAscii("\nendstream");
+		} else sink.writeAscii(serializeValue(value));
+		sink.writeAscii("\nendobj\n");
+	};
+	return {
+		allocate,
+		define,
+		add: (value) => {
+			const ref = allocate();
+			define(ref, value);
+			return ref;
+		},
+		serialize: ({ rootRef, infoRef, idHex }) => {
+			const sink = createByteSink();
+			sink.writeAscii(PDF_HEADER);
+			sink.writeBytes(BINARY_MARKER);
+			const offsets = /* @__PURE__ */ new Map();
+			for (let id = 1; id < nextId; id += 1) {
+				const value = values.get(id);
+				if (value === void 0) panic(`PDF object ${String(id)} was allocated but never defined`);
+				offsets.set(id, sink.offset());
+				writeObject(sink, id, value);
+			}
+			const xrefOffset = sink.offset();
+			const digest = idHex(sink.toBytes());
+			sink.writeAscii(`xref\n0 ${String(nextId)}\n`);
+			sink.writeAscii(XREF_FREE_ENTRY);
+			for (let id = 1; id < nextId; id += 1) {
+				const offset = offsets.get(id) ?? panic(`missing offset for PDF object ${String(id)}`);
+				sink.writeAscii(`${String(offset).padStart(10, "0")} 00000 n \n`);
+			}
+			const trailer = pdfDict([
+				["Size", pdfNumber(nextId)],
+				["Root", rootRef],
+				["Info", infoRef],
+				["ID", pdfArray([pdfHexString(digest), pdfHexString(digest)])]
+			]);
+			sink.writeAscii(`trailer\n${serializeValue(trailer)}\nstartxref\n${String(xrefOffset)}\n%%EOF\n`);
+			return sink.toBytes();
+		}
+	};
+};
+//#endregion
+export { createPdfDocument, deflateForPdf, formatNumber, pdfArray, pdfAsciiString, pdfBool, pdfDict, pdfFlateStream, pdfHexString, pdfName, pdfNull, pdfNumber, pdfNumberArray, pdfStream, pdfTextString };

package/dist/pdf/pageSpace.d.ts

@@ -0,0 +1,43 @@
+//#region src/pdf/pageSpace.d.ts
+/**
+ * The single conversion between display-list space and PDF space.
+ *
+ * The display list is CSS px at 96 dpi with the origin at the page's top-left
+ * and y growing down. PDF user space is points (72/inch) with the origin at
+ * the bottom-left and y growing up. Both the scale and the flip happen here
+ * and nowhere else: a second place that flips y is a second opinion about
+ * where the top of the page is, and the two will eventually disagree.
+ *
+ * Everything downstream, content streams included, is written in
+ * display-list coordinates. The page's base CTM ({@link basePageMatrix}) does
+ * the conversion for painted geometry; annotations and destinations, which
+ * are not affected by a content stream's CTM, run the same matrix themselves
+ * through {@link displayPointToPdf}.
+ */
+/** 72 points per inch over 96 CSS px per inch. */
+declare const POINTS_PER_PIXEL = 0.75;
+/** `[a b c d e f]` as PDF writes a matrix. */
+type PdfMatrix = readonly [number, number, number, number, number, number];
+declare const pxToPt: (px: number) => number;
+/**
+ * Scales px to points and flips y about the page's height, so a primitive
+ * emitted at display-list y 0 paints at the top of the page.
+ */
+declare const basePageMatrix: (pageHeightPx: number) => PdfMatrix;
+declare const applyMatrix: (matrix: PdfMatrix, x: number, y: number) => {
+  readonly x: number;
+  readonly y: number;
+};
+/** A display-list page point in PDF default user space. */
+declare const displayPointToPdf: (pageHeightPx: number, xPx: number, yPx: number) => {
+  readonly x: number;
+  readonly y: number;
+};
+/**
+ * Rotation about a point, expressed in display-list space. The space is
+ * y-down, so the usual `[cos sin -sin cos]` reads as a clockwise rotation on
+ * screen, which is what a positive CSS/OOXML angle means.
+ */
+declare const rotationMatrix: (degrees: number, originXPx: number, originYPx: number) => PdfMatrix;
+//#endregion
+export { POINTS_PER_PIXEL, PdfMatrix, applyMatrix, basePageMatrix, displayPointToPdf, pxToPt, rotationMatrix };

package/dist/pdf/pageSpace.js

@@ -0,0 +1,57 @@
+//#region src/pdf/pageSpace.ts
+/**
+* The single conversion between display-list space and PDF space.
+*
+* The display list is CSS px at 96 dpi with the origin at the page's top-left
+* and y growing down. PDF user space is points (72/inch) with the origin at
+* the bottom-left and y growing up. Both the scale and the flip happen here
+* and nowhere else: a second place that flips y is a second opinion about
+* where the top of the page is, and the two will eventually disagree.
+*
+* Everything downstream, content streams included, is written in
+* display-list coordinates. The page's base CTM ({@link basePageMatrix}) does
+* the conversion for painted geometry; annotations and destinations, which
+* are not affected by a content stream's CTM, run the same matrix themselves
+* through {@link displayPointToPdf}.
+*/
+/** 72 points per inch over 96 CSS px per inch. */
+const POINTS_PER_PIXEL = .75;
+const pxToPt = (px) => px * POINTS_PER_PIXEL;
+/**
+* Scales px to points and flips y about the page's height, so a primitive
+* emitted at display-list y 0 paints at the top of the page.
+*/
+const basePageMatrix = (pageHeightPx) => [
+	POINTS_PER_PIXEL,
+	0,
+	0,
+	-.75,
+	0,
+	pxToPt(pageHeightPx)
+];
+const applyMatrix = (matrix, x, y) => ({
+	x: matrix[0] * x + matrix[2] * y + matrix[4],
+	y: matrix[1] * x + matrix[3] * y + matrix[5]
+});
+/** A display-list page point in PDF default user space. */
+const displayPointToPdf = (pageHeightPx, xPx, yPx) => applyMatrix(basePageMatrix(pageHeightPx), xPx, yPx);
+/**
+* Rotation about a point, expressed in display-list space. The space is
+* y-down, so the usual `[cos sin -sin cos]` reads as a clockwise rotation on
+* screen, which is what a positive CSS/OOXML angle means.
+*/
+const rotationMatrix = (degrees, originXPx, originYPx) => {
+	const radians = degrees * Math.PI / 180;
+	const cos = Math.cos(radians);
+	const sin = Math.sin(radians);
+	return [
+		cos,
+		sin,
+		-sin,
+		cos,
+		originXPx - originXPx * cos + originYPx * sin,
+		originYPx - originXPx * sin - originYPx * cos
+	];
+};
+//#endregion
+export { POINTS_PER_PIXEL, applyMatrix, basePageMatrix, displayPointToPdf, pxToPt, rotationMatrix };

package/dist/pdf/paint.d.ts

@@ -0,0 +1,32 @@
+import { DisplayPage } from "../display-list/types.js";
+import { PreparedFont, ShapedRunRequest } from "./fonts.js";
+import { ContentPart } from "./contentStream.js";
+import { Result } from "better-result";
+//#region src/pdf/paint.d.ts
+declare const PaintError_base: import("better-result").TaggedErrorClass<"PaintError">;
+declare class PaintError extends PaintError_base<{
+  message: string;
+}> {}
+type PaintPageOptions = {
+  readonly page: DisplayPage;
+  readonly fonts: ReadonlyMap<number, PreparedFont>;
+};
+declare const paintPage: ({ page, fonts }: PaintPageOptions) => readonly ContentPart[];
+/** What the file must carry, gathered before anything is written. */
+type DisplayUsage = {
+  readonly codePointsByFont: ReadonlyMap<number, ReadonlySet<number>>;
+  /**
+   * Runs whose glyphs shaping has to choose, by font index. Collected here
+   * because the subset has to carry those glyphs before the first page is
+   * written, and they are not reachable from any code point.
+   */
+  readonly shapedRunsByFont: ReadonlyMap<number, readonly ShapedRunRequest[]>;
+  readonly imageIndices: ReadonlySet<number>;
+};
+/**
+ * Walks the pages once before anything is written, because subsetting needs
+ * every glyph the document uses before the first one is emitted.
+ */
+declare const collectUsage: (pages: readonly DisplayPage[], fontCount: number, imageCount: number) => Result<DisplayUsage, PaintError>;
+//#endregion
+export { DisplayUsage, PaintError, PaintPageOptions, collectUsage, paintPage };