@stll/folio-core 0.32.2 → 0.33.0

package/dist/pdf/fonts.js

@@ -0,0 +1,593 @@
+import { parseSfnt } from "../fonts/sfnt/parse.js";
+import { subsetTrueType } from "../fonts/sfnt/subset.js";
+import { toSfntBytes } from "../fonts/sfnt/woff.js";
+import { needsShaping, placeRun } from "../shaping/placeRun.js";
+import { pdfArray, pdfAsciiString, pdfDict, pdfFlateStream, pdfName, pdfNumber, pdfNumberArray } from "./objects.js";
+import { Result, TaggedError, panic } from "better-result";
+//#region src/pdf/fonts.ts
+/**
+* Font embedding.
+*
+* Every face the document paints becomes a composite (Type 0) font with
+* `Identity-H` encoding, so a run is written as two-byte glyph ids and the
+* file carries no encoding table to disagree with the font. A face the source
+* cannot supply, or whose licence bits forbid embedding, falls back to a
+* base-14 face and is *reported*: a substitution the caller cannot see is a
+* silently different document.
+*
+* ## A face is not a binary
+*
+* A packaged family arrives cut into disjoint script subsets: one binary
+* carries ASCII, another the Central European letters, and Czech, Slovak or
+* Polish text needs both at once. Each binary is its own sfnt with its own
+* glyph space, so one face becomes one PDF font resource *per binary the
+* document actually uses*, and a code point is served by the first binary
+* whose cmap covers it.
+*/
+var PdfFontError = class extends TaggedError("PdfFontError") {};
+/** Text space is 1000 units to the em whatever the font's own head is. */
+const TEXT_SPACE_UNITS_PER_EM = 1e3;
+/** `fsType` bit 1: the vendor forbids embedding this face outright. */
+const FSTYPE_RESTRICTED_LICENSE = 2;
+const FONT_FLAG_FIXED_PITCH = 1;
+const FONT_FLAG_SERIF = 2;
+const FONT_FLAG_SYMBOLIC = 4;
+const FONT_FLAG_ITALIC = 64;
+/**
+* `/StemV` has no counterpart in an sfnt table folio parses. A reader only
+* uses it to synthesize a stand-in when the embedded program is unusable, so
+* an approximation from the weight is honest and a wrong number is harmless.
+*/
+const STEM_V_REGULAR = 80;
+const STEM_V_BOLD = 160;
+const BOLD_WEIGHT_THRESHOLD = 600;
+const NOTDEF_GLYPH = 0;
+const SUBSET_TAG_LENGTH = 6;
+const ALPHABET_LENGTH = 26;
+const UPPERCASE_A = 65;
+const WOFF_SIGNATURES = ["wOFF", "wOF2"];
+const readTag = (bytes) => String.fromCharCode(bytes[0] ?? 0, bytes[1] ?? 0, bytes[2] ?? 0, bytes[3] ?? 0);
+/**
+* Six uppercase letters derived from the face and the exact glyph set, so the
+* tag is stable across runs and two different subsets of one family do not
+* collide under the same name.
+*/
+const subsetTag = (seed) => {
+	const FNV_OFFSET = 2166136261;
+	const FNV_PRIME = 16777619;
+	let hash = FNV_OFFSET;
+	for (let index = 0; index < seed.length; index += 1) hash = Math.imul(hash ^ seed.charCodeAt(index), FNV_PRIME) >>> 0;
+	let tag = "";
+	for (let index = 0; index < SUBSET_TAG_LENGTH; index += 1) {
+		tag += String.fromCharCode(UPPERCASE_A + hash % ALPHABET_LENGTH);
+		hash = Math.floor(hash / ALPHABET_LENGTH);
+	}
+	return tag;
+};
+const BASE_14_ROMAN = {
+	helvetica: "Helvetica",
+	times: "Times-Roman",
+	courier: "Courier"
+};
+const BASE_14_BOLD = {
+	helvetica: "Helvetica-Bold",
+	times: "Times-Bold",
+	courier: "Courier-Bold"
+};
+const BASE_14_ITALIC = {
+	helvetica: "Helvetica-Oblique",
+	times: "Times-Italic",
+	courier: "Courier-Oblique"
+};
+const BASE_14_BOLD_ITALIC = {
+	helvetica: "Helvetica-BoldOblique",
+	times: "Times-BoldItalic",
+	courier: "Courier-BoldOblique"
+};
+/**
+* Total over the display list's generic categories: a new category is a
+* compile error here rather than a face that silently lands on Helvetica.
+*/
+const GENERIC_TO_BASE_14 = {
+	serif: "times",
+	"sans-serif": "helvetica",
+	monospace: "courier",
+	cursive: "times",
+	fantasy: "helvetica"
+};
+const base14Name = (face) => {
+	const family = GENERIC_TO_BASE_14[face.generic];
+	const bold = face.weight >= BOLD_WEIGHT_THRESHOLD;
+	if (bold && face.italic) return BASE_14_BOLD_ITALIC[family];
+	if (bold) return BASE_14_BOLD[family];
+	return face.italic ? BASE_14_ITALIC[family] : BASE_14_ROMAN[family];
+};
+/**
+* The code points WinAnsiEncoding places in 0x80..0x9F, where it departs from
+* Latin-1. Outside that block WinAnsi and Latin-1 agree.
+*/
+const WIN_ANSI_HIGH_RANGE = [
+	[128, 8364],
+	[130, 8218],
+	[131, 402],
+	[132, 8222],
+	[133, 8230],
+	[134, 8224],
+	[135, 8225],
+	[136, 710],
+	[137, 8240],
+	[138, 352],
+	[139, 8249],
+	[140, 338],
+	[142, 381],
+	[145, 8216],
+	[146, 8217],
+	[147, 8220],
+	[148, 8221],
+	[149, 8226],
+	[150, 8211],
+	[151, 8212],
+	[152, 732],
+	[153, 8482],
+	[154, 353],
+	[155, 8250],
+	[156, 339],
+	[158, 382],
+	[159, 376]
+];
+const WIN_ANSI_QUESTION_MARK = 63;
+const buildWinAnsiTable = () => {
+	const table = /* @__PURE__ */ new Map();
+	const PRINTABLE_ASCII_START = 32;
+	const PRINTABLE_ASCII_END = 126;
+	const LATIN1_HIGH_START = 160;
+	const LATIN1_HIGH_END = 255;
+	for (let code = PRINTABLE_ASCII_START; code <= PRINTABLE_ASCII_END; code += 1) table.set(code, code);
+	for (let code = LATIN1_HIGH_START; code <= LATIN1_HIGH_END; code += 1) table.set(code, code);
+	for (const [byte, codePoint] of WIN_ANSI_HIGH_RANGE) table.set(codePoint, byte);
+	return table;
+};
+const WIN_ANSI_BY_CODE_POINT = buildWinAnsiTable();
+const utf16BeHexOf = (text) => [...text].map((character) => utf16BeHex(character.codePointAt(0) ?? 0)).join("");
+const utf16BeHex = (codePoint) => {
+	const SUPPLEMENTARY_START = 65536;
+	const SURROGATE_HALF_BITS = 10;
+	const LOW_SURROGATE_MASK = 1023;
+	const HIGH_SURROGATE_BASE = 55296;
+	const LOW_SURROGATE_BASE = 56320;
+	const hex = (unit) => unit.toString(16).padStart(4, "0").toUpperCase();
+	if (codePoint < SUPPLEMENTARY_START) return hex(codePoint);
+	const offset = codePoint - SUPPLEMENTARY_START;
+	return hex(HIGH_SURROGATE_BASE + (offset >> SURROGATE_HALF_BITS)) + hex(LOW_SURROGATE_BASE + (offset & LOW_SURROGATE_MASK));
+};
+/** Entries per `beginbfchar` block; the CMap syntax caps this at 100. */
+const BFCHAR_BLOCK_SIZE = 100;
+const toUnicodeCMap = (glyphToText) => {
+	const entries = [...glyphToText.entries()].sort(([left], [right]) => left - right);
+	let body = "";
+	for (let start = 0; start < entries.length; start += BFCHAR_BLOCK_SIZE) {
+		const block = entries.slice(start, start + BFCHAR_BLOCK_SIZE);
+		body += `${String(block.length)} beginbfchar\n`;
+		for (const [glyphId, text] of block) body += `<${utf16BeHex(glyphId)}> <${utf16BeHexOf(text)}>\n`;
+		body += "endbfchar\n";
+	}
+	return `/CIDInit /ProcSet findresource begin
+12 dict begin
+begincmap
+/CIDSystemInfo << /Registry (Adobe) /Ordering (UCS) /Supplement 0 >> def
+/CMapName /Adobe-Identity-UCS def
+/CMapType 2 def
+1 begincodespacerange
+<0000> <FFFF>
+endcodespacerange
+${body}endcmap
+CMapName currentdict /CMap defineresource pop
+end
+end
+`;
+};
+/**
+* `/W` as consecutive runs: `[ firstGid [w w w] nextGid [w] ]`. A subset's
+* glyph ids are dense, so this is normally one run.
+*/
+const widthsArray = (widths) => {
+	const items = [];
+	let runStart = null;
+	let expected = 0;
+	let run = [];
+	const flush = () => {
+		if (runStart !== null && run.length > 0) items.push(pdfNumber(runStart), pdfNumberArray(run));
+	};
+	for (const glyphId of [...widths.keys()].sort((left, right) => left - right)) {
+		if (runStart === null || glyphId !== expected) {
+			flush();
+			runStart = glyphId;
+			run = [];
+		}
+		run.push(widths.get(glyphId) ?? panic("width run lost a glyph"));
+		expected = glyphId + 1;
+	}
+	flush();
+	return pdfArray(items);
+};
+const asciiOnly = (value) => value.replace(/[^\x20-\x7e]/gu, "");
+const fontDescriptor = ({ font, face, fontName, fontFileKey, fontFileRef }) => {
+	const scale = TEXT_SPACE_UNITS_PER_EM / font.unitsPerEm;
+	const italic = face.italic || font.italicAngle !== 0;
+	const flags = FONT_FLAG_SYMBOLIC | (face.generic === "serif" ? FONT_FLAG_SERIF : 0) | (face.generic === "monospace" ? FONT_FLAG_FIXED_PITCH : 0) | (italic ? FONT_FLAG_ITALIC : 0);
+	return pdfDict([
+		["Type", pdfName("FontDescriptor")],
+		["FontName", pdfName(fontName)],
+		["Flags", pdfNumber(flags)],
+		["FontBBox", pdfNumberArray(font.bbox.map((value) => value * scale))],
+		["ItalicAngle", pdfNumber(font.italicAngle)],
+		["Ascent", pdfNumber(font.ascender * scale)],
+		["Descent", pdfNumber(font.descender * scale)],
+		["CapHeight", pdfNumber(font.capHeight * scale)],
+		["StemV", pdfNumber(face.weight >= BOLD_WEIGHT_THRESHOLD ? STEM_V_BOLD : STEM_V_REGULAR)],
+		[fontFileKey, fontFileRef]
+	]);
+};
+const planFont = ({ font, face, codePoints, shapedGlyphIds, textByShapedGlyphId }) => {
+	const sourceGlyphByCodePoint = /* @__PURE__ */ new Map();
+	const sourceGlyphIds = /* @__PURE__ */ new Set([NOTDEF_GLYPH]);
+	for (const codePoint of codePoints) {
+		const glyphId = font.glyphIdFor(codePoint);
+		sourceGlyphByCodePoint.set(codePoint, glyphId);
+		sourceGlyphIds.add(glyphId);
+	}
+	for (const glyphId of shapedGlyphIds ?? []) sourceGlyphIds.add(glyphId);
+	let glyphIdMap;
+	let programBytes;
+	if (font.isCff) {
+		glyphIdMap = new Map([...sourceGlyphIds].map((glyphId) => [glyphId, glyphId]));
+		programBytes = font.bytes;
+	} else {
+		const subset = subsetTrueType(font, sourceGlyphIds);
+		if (subset.isErr()) return Result.err(new PdfFontError({ message: `subsetting failed: ${subset.error.message}` }));
+		glyphIdMap = subset.value.glyphIdMap;
+		programBytes = subset.value.bytes;
+	}
+	const scale = TEXT_SPACE_UNITS_PER_EM / font.unitsPerEm;
+	const glyphIdByCodePoint = /* @__PURE__ */ new Map();
+	const widthByGlyphId = /* @__PURE__ */ new Map();
+	const glyphToText = /* @__PURE__ */ new Map();
+	for (const sourceGlyphId of [...sourceGlyphIds].sort((left, right) => left - right)) {
+		const targetGlyphId = glyphIdMap.get(sourceGlyphId);
+		if (targetGlyphId === void 0) return Result.err(new PdfFontError({ message: `subset dropped glyph ${String(sourceGlyphId)}` }));
+		widthByGlyphId.set(targetGlyphId, Math.round(font.advanceWidthFor(sourceGlyphId) * scale));
+	}
+	for (const codePoint of [...sourceGlyphByCodePoint.keys()].sort((left, right) => left - right)) {
+		const sourceGlyphId = sourceGlyphByCodePoint.get(codePoint) ?? NOTDEF_GLYPH;
+		const targetGlyphId = glyphIdMap.get(sourceGlyphId) ?? NOTDEF_GLYPH;
+		glyphIdByCodePoint.set(codePoint, targetGlyphId);
+		if (!glyphToText.has(targetGlyphId)) glyphToText.set(targetGlyphId, String.fromCodePoint(codePoint));
+	}
+	for (const [sourceGlyphId, text] of textByShapedGlyphId ?? []) {
+		const targetGlyphId = glyphIdMap.get(sourceGlyphId);
+		if (targetGlyphId !== void 0 && !glyphToText.has(targetGlyphId)) glyphToText.set(targetGlyphId, text);
+	}
+	const baseName = asciiOnly(font.postScriptName) || asciiOnly(face.family) || "Unknown";
+	const fontName = `${subsetTag(`${baseName}:${[...sourceGlyphIds].sort((left, right) => left - right).join(",")}`)}+${baseName}`;
+	return Result.ok({
+		font,
+		face,
+		fontName,
+		programBytes,
+		glyphIdByCodePoint,
+		widthByGlyphId,
+		glyphToText,
+		glyphIdMap
+	});
+};
+const emitFont = (document, plan) => {
+	const { font, face, fontName, programBytes } = plan;
+	const fontFileRef = document.add(font.isCff ? pdfFlateStream([["Subtype", pdfName("OpenType")]], programBytes) : pdfFlateStream([["Length1", pdfNumber(programBytes.length)]], programBytes));
+	const descriptorRef = document.add(fontDescriptor({
+		font,
+		face,
+		fontName,
+		fontFileKey: font.isCff ? "FontFile3" : "FontFile2",
+		fontFileRef
+	}));
+	const toUnicodeRef = document.add(pdfFlateStream([], new TextEncoder().encode(toUnicodeCMap(plan.glyphToText))));
+	const descendantRef = document.add(pdfDict([
+		["Type", pdfName("Font")],
+		["Subtype", pdfName(font.isCff ? "CIDFontType0" : "CIDFontType2")],
+		["BaseFont", pdfName(fontName)],
+		["CIDSystemInfo", pdfDict([
+			["Registry", pdfAsciiString("Adobe")],
+			["Ordering", pdfAsciiString("Identity")],
+			["Supplement", pdfNumber(0)]
+		])],
+		["FontDescriptor", descriptorRef],
+		["DW", pdfNumber(TEXT_SPACE_UNITS_PER_EM)],
+		["W", widthsArray(plan.widthByGlyphId)],
+		["CIDToGIDMap", font.isCff ? void 0 : pdfName("Identity")]
+	]));
+	return document.add(pdfDict([
+		["Type", pdfName("Font")],
+		["Subtype", pdfName("Type0")],
+		["BaseFont", pdfName(fontName)],
+		["Encoding", pdfName("Identity-H")],
+		["DescendantFonts", pdfArray([descendantRef])],
+		["ToUnicode", toUnicodeRef]
+	]));
+};
+const standardFont = (document, face) => document.add(pdfDict([
+	["Type", pdfName("Font")],
+	["Subtype", pdfName("Type1")],
+	["BaseFont", pdfName(base14Name(face))],
+	["Encoding", pdfName("WinAnsiEncoding")]
+]));
+const parseFace = (binaries) => {
+	if (binaries.length === 0) return {
+		kind: "unusable",
+		reason: "the font source supplied no bytes for this face"
+	};
+	const fonts = [];
+	let reason = "";
+	for (const bytes of binaries) {
+		let sfntBytes = bytes;
+		if (WOFF_SIGNATURES.includes(readTag(bytes))) {
+			const decoded = toSfntBytes(bytes);
+			if (decoded.isErr()) {
+				reason = `WOFF decoding failed: ${decoded.error.message}`;
+				continue;
+			}
+			sfntBytes = decoded.value;
+		}
+		const parsed = parseSfnt(sfntBytes);
+		if (parsed.isErr()) {
+			reason = `font parsing failed: ${parsed.error.message}`;
+			continue;
+		}
+		if ((parsed.value.fsType & FSTYPE_RESTRICTED_LICENSE) !== 0) {
+			reason = "the face's fsType bits forbid embedding";
+			continue;
+		}
+		fonts.push(parsed.value);
+	}
+	return fonts.length === 0 ? {
+		kind: "unusable",
+		reason
+	} : {
+		kind: "usable",
+		fonts
+	};
+};
+/** Where a code point no binary covers is painted from: `.notdef` is there. */
+const FALLBACK_BINARY = 0;
+/**
+* Which binary of the face serves a code point, or -1 when none does. One
+* answer for the whole file: coverage and shaping must agree about which
+* binary a character belongs to, or a run is shaped against one face and
+* painted from another's glyph space.
+*/
+const binaryIndexFor = (fonts, codePoint) => fonts.findIndex((font) => font.glyphIdFor(codePoint) !== NOTDEF_GLYPH);
+const resolveCoverage = (fonts, codePoints) => {
+	const codePointsByBinary = /* @__PURE__ */ new Map();
+	const uncovered = [];
+	for (const codePoint of codePoints) {
+		const found = binaryIndexFor(fonts, codePoint);
+		if (found === -1) uncovered.push(codePoint);
+		const binary = found === -1 ? FALLBACK_BINARY : found;
+		const bucket = codePointsByBinary.get(binary) ?? [];
+		bucket.push(codePoint);
+		codePointsByBinary.set(binary, bucket);
+	}
+	return {
+		codePointsByBinary,
+		uncovered
+	};
+};
+const segmentRun = (fonts, text) => {
+	const segments = [];
+	let open = null;
+	let index = 0;
+	for (const character of text) {
+		const found = binaryIndexFor(fonts, character.codePointAt(0) ?? 0);
+		const binaryIndex = found === -1 ? FALLBACK_BINARY : found;
+		if (open === null || open.binaryIndex !== binaryIndex) {
+			open = {
+				binaryIndex,
+				startIndex: index,
+				text: character
+			};
+			segments.push(open);
+		} else open.text += character;
+		index += 1;
+	}
+	return segments;
+};
+const EMPTY_SHAPING = {
+	glyphIdsByBinary: /* @__PURE__ */ new Map(),
+	textByGlyphByBinary: /* @__PURE__ */ new Map(),
+	placementsByRun: /* @__PURE__ */ new Map()
+};
+const runKeyOf = ({ text, direction, fontSizePx }) => `${direction}\u0000${String(fontSizePx)}\u0000${text}`;
+/**
+* The characters behind one glyph: the code points of its cluster, carried by
+* the first glyph of that cluster only. Giving every mark of a cluster the same
+* characters would repeat them on extraction.
+*/
+const clusterText = (characters, glyphs, position) => {
+	const glyph = glyphs[position];
+	if (glyph === void 0) return "";
+	if (glyphs.find((other) => other.clusterIndex === glyph.clusterIndex) !== glyph) return "";
+	const next = [...new Set(glyphs.map((other) => other.clusterIndex))].sort((left, right) => left - right).find((start) => start > glyph.clusterIndex) ?? characters.length;
+	return characters.slice(glyph.clusterIndex, next).join("");
+};
+const shapeFace = (fonts, runs, shaper) => {
+	const glyphIdsByBinary = /* @__PURE__ */ new Map();
+	const textByGlyphByBinary = /* @__PURE__ */ new Map();
+	const placementsByRun = /* @__PURE__ */ new Map();
+	for (const run of runs) {
+		const key = runKeyOf(run);
+		if (placementsByRun.has(key)) continue;
+		const placed = [];
+		for (const segment of segmentRun(fonts, run.text)) {
+			const font = fonts[segment.binaryIndex];
+			if (font === void 0 || !needsShaping(segment.text)) continue;
+			const glyphs = placeRun({
+				shaper,
+				font: font.bytes,
+				text: segment.text,
+				fontSizePx: run.fontSizePx,
+				direction: run.direction
+			});
+			placed.push({
+				binaryIndex: segment.binaryIndex,
+				startIndex: segment.startIndex,
+				glyphs
+			});
+			const ids = glyphIdsByBinary.get(segment.binaryIndex) ?? /* @__PURE__ */ new Set();
+			const texts = textByGlyphByBinary.get(segment.binaryIndex) ?? /* @__PURE__ */ new Map();
+			const characters = [...segment.text];
+			for (const [position, glyph] of glyphs.entries()) {
+				ids.add(glyph.glyphId);
+				const text = clusterText(characters, glyphs, position);
+				if (text !== "" && !texts.has(glyph.glyphId)) texts.set(glyph.glyphId, text);
+			}
+			glyphIdsByBinary.set(segment.binaryIndex, ids);
+			textByGlyphByBinary.set(segment.binaryIndex, texts);
+		}
+		placementsByRun.set(key, placed);
+	}
+	return {
+		glyphIdsByBinary,
+		textByGlyphByBinary,
+		placementsByRun
+	};
+};
+/**
+* Turns the display list's font table into PDF font objects. A face nothing
+* paints is skipped entirely: an unused face is not a substitution, and
+* embedding it would put bytes in the file no page reads.
+*/
+const prepareFonts = ({ document, faces, usedCodePoints, shapedRuns, shaper = null, source }) => {
+	const byFontIndex = /* @__PURE__ */ new Map();
+	const fontRefByResourceIndex = /* @__PURE__ */ new Map();
+	const substitutions = [];
+	const unencodable = [];
+	let nextResourceIndex = 0;
+	const claimResource = (ref) => {
+		const resourceIndex = nextResourceIndex;
+		nextResourceIndex += 1;
+		fontRefByResourceIndex.set(resourceIndex, ref);
+		return resourceIndex;
+	};
+	const reported = /* @__PURE__ */ new Set();
+	const report = (face, codePoints) => {
+		for (const codePoint of codePoints) {
+			const key = `${face.family}${String(face.weight)}${String(face.italic)}${String(codePoint)}`;
+			if (reported.has(key)) continue;
+			reported.add(key);
+			unencodable.push({
+				codePoint,
+				family: face.family,
+				weight: face.weight,
+				italic: face.italic
+			});
+		}
+	};
+	const substitute = (fontIndex, face, codePoints, reason) => {
+		substitutions.push({
+			family: face.family,
+			weight: face.weight,
+			italic: face.italic,
+			reason
+		});
+		report(face, codePoints.filter((codePoint) => !WIN_ANSI_BY_CODE_POINT.has(codePoint)));
+		byFontIndex.set(fontIndex, {
+			kind: "standard",
+			resourceIndex: claimResource(standardFont(document, face)),
+			byteFor: (codePoint) => WIN_ANSI_BY_CODE_POINT.get(codePoint) ?? WIN_ANSI_QUESTION_MARK
+		});
+	};
+	for (const [fontIndex, face] of faces.entries()) {
+		const used = usedCodePoints.get(fontIndex);
+		if (used === void 0 || used.size === 0) continue;
+		const codePoints = [...used].sort((left, right) => left - right);
+		const binaries = face.embedded === void 0 ? source.load(face) : [face.embedded.bytes];
+		const parsed = parseFace(binaries);
+		if (parsed.kind === "unusable") {
+			substitute(fontIndex, face, codePoints, parsed.reason);
+			continue;
+		}
+		const shaping = shaper === null ? EMPTY_SHAPING : shapeFace(parsed.fonts, shapedRuns?.get(fontIndex) ?? [], shaper);
+		const coverage = resolveCoverage(parsed.fonts, codePoints);
+		const binaryIndices = [.../* @__PURE__ */ new Set([...coverage.codePointsByBinary.keys(), ...shaping.glyphIdsByBinary.keys()])].sort((left, right) => left - right);
+		const plans = [];
+		let failure = null;
+		for (const binaryIndex of binaryIndices) {
+			const plan = planFont({
+				font: parsed.fonts[binaryIndex] ?? panic(`face lost binary ${String(binaryIndex)}`),
+				face,
+				codePoints: coverage.codePointsByBinary.get(binaryIndex) ?? [],
+				shapedGlyphIds: shaping.glyphIdsByBinary.get(binaryIndex),
+				textByShapedGlyphId: shaping.textByGlyphByBinary.get(binaryIndex)
+			});
+			if (plan.isErr()) {
+				failure = plan.error;
+				break;
+			}
+			plans.push(plan.value);
+		}
+		if (failure !== null) {
+			substitute(fontIndex, face, codePoints, failure.message);
+			continue;
+		}
+		const glyphByCodePoint = /* @__PURE__ */ new Map();
+		const emitted = /* @__PURE__ */ new Map();
+		for (const [position, plan] of plans.entries()) {
+			const resourceIndex = claimResource(emitFont(document, plan));
+			emitted.set(binaryIndices[position] ?? FALLBACK_BINARY, {
+				plan,
+				resourceIndex
+			});
+			for (const [codePoint, glyphId] of plan.glyphIdByCodePoint) glyphByCodePoint.set(codePoint, {
+				resourceIndex,
+				glyphId,
+				widthUnits: plan.widthByGlyphId.get(glyphId) ?? panic(`no width for glyph ${String(glyphId)}`)
+			});
+		}
+		report(face, coverage.uncovered);
+		byFontIndex.set(fontIndex, {
+			kind: "embedded",
+			glyphFor: (codePoint) => glyphByCodePoint.get(codePoint) ?? panic(`code point ${String(codePoint)} was painted but never collected`),
+			placeShapedRun: (request) => {
+				const segments = shaping.placementsByRun.get(runKeyOf(request));
+				if (segments === void 0 || segments.length === 0) return null;
+				return segments.flatMap(({ binaryIndex, startIndex, glyphs }) => {
+					const target = emitted.get(binaryIndex) ?? panic(`shaped run used binary ${String(binaryIndex)}, which was never emitted`);
+					return glyphs.map(({ glyphId, clusterIndex, xAdvancePx, xOffsetPx, yOffsetPx }) => {
+						const subsetGlyphId = target.plan.glyphIdMap.get(glyphId) ?? panic(`subset dropped shaped glyph ${String(glyphId)}`);
+						return {
+							resourceIndex: target.resourceIndex,
+							glyphId: subsetGlyphId,
+							widthUnits: target.plan.widthByGlyphId.get(subsetGlyphId) ?? panic(`no width for glyph ${String(subsetGlyphId)}`),
+							clusterIndex: startIndex + clusterIndex,
+							xAdvancePx,
+							xOffsetPx,
+							yOffsetPx
+						};
+					});
+				});
+			}
+		});
+	}
+	const byCodeUnit = (left, right) => {
+		if (left === right) return 0;
+		return left < right ? -1 : 1;
+	};
+	unencodable.sort((left, right) => byCodeUnit(left.family, right.family) || left.weight - right.weight || Number(left.italic) - Number(right.italic) || left.codePoint - right.codePoint);
+	return {
+		byFontIndex,
+		fontRefByResourceIndex,
+		substitutions,
+		unencodable
+	};
+};
+//#endregion
+export { prepareFonts };

package/dist/pdf/images.d.ts

@@ -0,0 +1,28 @@
+import { DisplayImageSource } from "../display-list/types.js";
+import { PdfValue } from "./objects.js";
+import { Result } from "better-result";
+//#region src/pdf/images.d.ts
+declare const PdfImageError_base: import("better-result").TaggedErrorClass<"PdfImageError">;
+declare class PdfImageError extends PdfImageError_base<{
+  message: string;
+}> {}
+/** A soft mask: one alpha sample per pixel, matching the image's dimensions. */
+type PdfImageAlpha = {
+  readonly data: Uint8Array;
+  readonly bitsPerComponent: number;
+};
+type PdfImageSamples = {
+  readonly widthPx: number;
+  readonly heightPx: number;
+  readonly bitsPerComponent: number;
+  readonly colorSpace: PdfValue;
+  /** `jpeg` is written as `/DCTDecode`; `raw` is deflated by the writer. */
+  readonly encoding: "raw" | "jpeg";
+  readonly data: Uint8Array;
+  /** Component inversion, for Adobe CMYK JPEGs. */
+  readonly decode?: readonly number[];
+  readonly alpha?: PdfImageAlpha;
+};
+declare const decodeImage: (source: DisplayImageSource) => Result<PdfImageSamples, PdfImageError>;
+//#endregion
+export { PdfImageAlpha, PdfImageError, PdfImageSamples, decodeImage };