reamkit 1.24.0 → 1.25.0

package/dist/esm/pdf-reader/flow-build.js

@@ -2,6 +2,7 @@ import { pt } from "../core/ir/units.js";
 import { ResourceStore } from "../core/ir/resources.js";
 import { EMPTY_STYLE_SHEET, resolveBodyStyles } from "../core/style-cascade/resolver.js";
 import "../core/style-cascade/index.js";
+import { displayOf } from "./display.js";
 //#region src/pdf-reader/flow-build.ts
 /**
 * Build a paragraph {@link BodyElement} from a single plain-text string,
@@ -30,16 +31,21 @@ function paragraphFromRuns(spans, outlineLevel) {
 	const merged = [];
 	for (const s of spans) {
 		const last = merged[merged.length - 1];
-		if (last && last.href === s.href) last.text += s.text;
-		else if (s.href !== void 0) merged.push({
+		if (last && last.href === s.href && last.sizePt === s.sizePt && last.colorHex === s.colorHex && last.fontName === s.fontName && last.outline?.colorHex === s.outline?.colorHex && last.outline?.widthPt === s.outline?.widthPt && last.bold === s.bold && last.italic === s.italic) last.text += s.text;
+		else merged.push({
 			text: s.text,
-			href: s.href
+			...s.href !== void 0 ? { href: s.href } : {},
+			...s.sizePt !== void 0 ? { sizePt: s.sizePt } : {},
+			...s.colorHex !== void 0 ? { colorHex: s.colorHex } : {},
+			...s.fontName !== void 0 ? { fontName: s.fontName } : {},
+			...s.outline !== void 0 ? { outline: s.outline } : {},
+			...s.bold !== void 0 ? { bold: s.bold } : {},
+			...s.italic !== void 0 ? { italic: s.italic } : {}
 		});
-		else merged.push({ text: s.text });
 	}
 	const runs = merged.map((m) => ({
-		text: m.text.replace(/\s+/g, " "),
-		href: m.href
+		...m,
+		text: m.text.replace(/\s+/g, " ")
 	})).filter((m) => m.text.length > 0);
 	if (runs.length > 0) {
 		runs[0].text = runs[0].text.replace(/^ /, "");
@@ -51,7 +57,14 @@ function paragraphFromRuns(spans, outlineLevel) {
 			properties: outlineLevel !== void 0 ? { outlineLevel } : {},
 			runs: runs.filter((r) => r.text.length > 0).map((r) => ({
 				text: r.text,
-				properties: {},
+				properties: {
+					...r.sizePt !== void 0 ? { fontSizePt: pt(r.sizePt) } : {},
+					...r.colorHex !== void 0 ? { colorHex: r.colorHex } : {},
+					...r.fontName !== void 0 ? { fontFamily: { ascii: r.fontName } } : {},
+					...r.outline !== void 0 ? { textOutline: r.outline } : {},
+					...r.bold ? { bold: true } : {},
+					...r.italic ? { italic: true } : {}
+				},
 				...r.href ? { href: r.href } : {}
 			}))
 		}
@@ -62,11 +75,25 @@ function paragraphFromRuns(spans, outlineLevel) {
 * {@link BodyElement} that references them, sized in points from the placement
 * CTM. `alt` becomes the block's alt text when given.
 */
-function imageBlock(image, resources, alt) {
+function imageBlock(image, resources, alt, frame, zOrder) {
+	const resource = resources.put(image.bytes);
+	const float = frame !== void 0 ? {
+		wrap: "none",
+		...zOrder !== void 0 ? { zOrder } : {},
+		posH: {
+			relativeFrom: "page",
+			offsetPt: pt(image.x - frame.left)
+		},
+		posV: {
+			relativeFrom: "page",
+			offsetPt: pt(Math.max(0, frame.top - image.y - image.heightPt))
+		}
+	} : void 0;
 	return {
 		kind: "image",
 		image: {
-			resource: resources.put(image.bytes),
+			...float ? { float } : {},
+			resource,
 			width: pt(image.widthPt),
 			height: pt(image.heightPt),
 			paragraphProperties: {},
@@ -74,6 +101,60 @@ function imageBlock(image, resources, alt) {
 		}
 	};
 }
+/**
+* A line of text as an anchored box, standing where the page set it.
+*
+* The flowed reconstruction reads a document OUT of a page: paragraphs in
+* reading order, re-flowable, free to land wherever the next medium puts them.
+* A form is not that document. 160F-2019.pdf is a grid of ruled boxes with a
+* label in each, and a label means nothing an inch from the box it labels — the
+* artwork is placed absolutely, so text that flows beside it lines up with none
+* of it.
+*
+* @param spans       The line's runs.
+* @param box         Its page-space rectangle (y-up, as PDF measures).
+* @param frame       The page's own corner, to measure the box off.
+* @param zOrder      Its place in the page's painting order.
+* @param rotation60k §20.1.7.6 — how far the box turns about its own centre,
+*                    for a baseline the page did not set flat.
+* @returns A shape carrying the text, anchored where the glyphs were.
+*/
+function positionedText(spans, box, frame, zOrder, rotation60k) {
+	const paragraph = paragraphFromRuns(spans);
+	return {
+		kind: "shape",
+		shape: {
+			float: {
+				wrap: "none",
+				zOrder,
+				posH: {
+					relativeFrom: "page",
+					offsetPt: pt(box.x - frame.left)
+				},
+				posV: {
+					relativeFrom: "page",
+					offsetPt: pt(Math.max(0, frame.top - box.y - box.height))
+				}
+			},
+			width: pt(Math.max(1, box.width)),
+			height: pt(Math.max(1, box.height)),
+			...rotation60k !== void 0 ? { transform: { rotation60k } } : {},
+			geometry: {
+				kind: "preset",
+				preset: "rect"
+			},
+			fill: { kind: "none" },
+			text: {
+				content: [paragraph],
+				insetLeft: pt(0),
+				insetTop: pt(0),
+				insetRight: pt(0),
+				insetBottom: pt(0)
+			},
+			paragraphProperties: {}
+		}
+	};
+}
 /** Collapse losses sharing a `detail` message (the same colour space dropped on many pages). */
 function dedupeLosses(losses) {
 	const byDetail = /* @__PURE__ */ new Map();
@@ -84,10 +165,14 @@ function dedupeLosses(losses) {
 * Turn a lifted {@link PdfVector} path (filled EP10 / stroked EP11) into a
 * custom-geometry shape {@link BodyElement}. Page-space points (y-up) become
 * path-space (bbox-relative, y-down); the shape is sized from the bounding box
-* (plus the stroke thickness) and placed in flow order by the caller. A fill
-* becomes a solid fill, a stroke becomes the outline.
+* (plus the stroke thickness). A fill becomes a solid fill, a stroke the outline.
+*
+* Given the page's frame the shape is ANCHORED where the page drew it, behind
+* the text, rather than taking a place of its own in the flow. A drawing is not
+* a paragraph: 22060_A1_01_Plans.pdf is one A3 sheet of vectors, and stacking
+* its forty-nine paths one under another spilled it onto a second page.
 */
-function shapeBlock(v) {
+function shapeBlock(v, frame, zOrder) {
 	const w = v.maxX - v.minX;
 	const h = v.maxY - v.minY;
 	const fx = (x) => x - v.minX;
@@ -116,22 +201,41 @@ function shapeBlock(v) {
 			case "close": return { cmd: "close" };
 		}
 	});
-	const thick = v.strokeHex !== void 0 ? Math.max(v.lineWidth ?? .75, .5) : 0;
+	const HAIRLINE_PT = .1;
+	const stated = v.lineWidth ?? .75;
+	const pen = v.strokeHex !== void 0 ? stated > 0 ? stated : HAIRLINE_PT : 0;
+	const thick = v.strokeHex !== void 0 ? Math.max(pen, .5) : 0;
+	const alpha = v.alpha !== void 0 ? { alpha: v.alpha } : {};
 	const fill = v.gradient !== void 0 ? {
 		kind: "gradient",
-		gradient: v.gradient
+		gradient: v.gradient,
+		...alpha
 	} : v.fillHex !== void 0 ? {
 		kind: "solid",
-		colorHex: v.fillHex
+		colorHex: v.fillHex,
+		...alpha
 	} : { kind: "none" };
 	const line = v.strokeHex !== void 0 ? {
-		width: pt(thick),
+		width: pt(pen),
 		colorHex: v.strokeHex,
 		fill: "solid"
 	} : void 0;
+	const float = frame !== void 0 ? {
+		wrap: "none",
+		...zOrder !== void 0 ? { zOrder } : {},
+		posH: {
+			relativeFrom: "page",
+			offsetPt: pt(v.minX - frame.left)
+		},
+		posV: {
+			relativeFrom: "page",
+			offsetPt: pt(Math.max(0, frame.top - v.maxY))
+		}
+	} : void 0;
 	return {
 		kind: "shape",
 		shape: {
+			...float ? { float } : {},
 			width: pt(Math.max(w, thick)),
 			height: pt(Math.max(h, thick)),
 			geometry: {
@@ -160,10 +264,11 @@ function shapeBlock(v) {
 * `A4`. Returns `undefined` when there is no usable first-page box.
 */
 function sectionFromPdfPages(pages) {
-	const box = pages[0]?.mediaBox;
-	if (!box) return void 0;
-	const width = Math.abs(box[2] - box[0]);
-	const height = Math.abs(box[3] - box[1]);
+	const first = pages[0];
+	if (!first) return void 0;
+	const shown = displayOf(first);
+	const width = shown.width;
+	const height = shown.height;
 	if (!(width > 0 && height > 0)) return void 0;
 	return {
 		pageSize: {
@@ -188,15 +293,16 @@ function sectionFromPdfPages(pages) {
 * both reconstruction paths (the tagged fast-path EP3 and the heuristic layout
 * path EP4).
 */
-function buildFlowDoc(body, resources = new ResourceStore(), section) {
+function buildFlowDoc(body, resources = new ResourceStore(), section, embeddedFonts) {
 	return {
 		kind: "flow",
 		body: resolveBodyStyles([...body], EMPTY_STYLE_SHEET),
 		sections: [],
 		...section ? { section } : {},
+		...embeddedFonts && embeddedFonts.size > 0 ? { embeddedFonts } : {},
 		styles: EMPTY_STYLE_SHEET,
 		resources
 	};
 }
 //#endregion
-export { buildFlowDoc, dedupeLosses, imageBlock, paragraphBlock, paragraphFromRuns, sectionFromPdfPages, shapeBlock };
+export { buildFlowDoc, dedupeLosses, imageBlock, paragraphBlock, paragraphFromRuns, positionedText, sectionFromPdfPages, shapeBlock };

package/dist/esm/pdf-reader/font.js

@@ -1,4 +1,6 @@
+import { parseTtf } from "../core/font/ttf-parser.js";
 import { PDF_NULL, PdfName, PdfStream } from "../pdf/objects.js";
+import { embeddedFontName } from "./embedded-fonts.js";
 import { parseToUnicodeCMap } from "./cmap.js";
 //#region src/pdf-reader/font.ts
 /**
@@ -21,16 +23,195 @@ function buildContentFont(file, fontDict) {
 	if (tu instanceof PdfStream) {
 		const parsed = parseToUnicodeCMap(file.streamData(tu));
 		toUnicode = parsed.map;
-		codeBytes = parsed.codeBytes;
+		if (isType0) codeBytes = parsed.codeBytes;
 	}
-	const width = isType0 ? cidWidths(file, fontDict) : simpleWidths(file, fontDict);
+	const unicode = (isType0 && toUnicode.size === 0 ? embeddedCmap(file, fontDict) : void 0) ?? toUnicode;
 	const bytesPerCode = codeBytes;
+	const style = faceStyle(file, fontDict, isType0);
+	const name = embeddedFontName(file, fontDict);
+	const type3 = asName(file.resolve(fontDict.get("Subtype") ?? PDF_NULL)) === "Type3" ? type3Face(file, fontDict) : void 0;
+	const simple = simpleWidths(file, fontDict);
+	const width = isType0 ? cidWidths(file, fontDict) : type3 ? (code) => simple(code) * type3.matrix[0] * 1e3 : simple;
 	return {
 		bytesPerCode,
-		decode: (codes) => codes.map((c) => toUnicode.get(c) ?? (bytesPerCode === 1 ? String.fromCharCode(c) : "")).join(""),
-		width
+		...type3 ? { type3 } : {},
+		...name !== void 0 ? { name } : {},
+		decode: (codes) => codes.map((c) => unicode.get(c) ?? (bytesPerCode === 1 ? String.fromCharCode(c) : "")).join(""),
+		width,
+		...style
 	};
 }
+/** The last Unicode code point in the BMP, and the surrogate block inside it. */
+var BMP_END = 65535;
+var SURROGATE_FIRST = 55296;
+var SURROGATE_LAST = 57343;
+/**
+* §9.10.2 — code → Unicode read out of an embedded TrueType program's `cmap`,
+* for a composite font that states no `/ToUnicode`.
+*
+* A `cmap` maps the other way, code point → glyph, so it is walked once and
+* turned round. With `Identity-H` and no `/CIDToGIDMap` a code IS a glyph
+* index, which is the case this exists for; a `/CIDToGIDMap` stream is read
+* where one is present.
+*
+* Only TrueType (`/FontFile2`) is read. A CFF program (`/FontFile3`) carries
+* its own charset and is a separate reading; a font with neither says nothing
+* about its glyphs and nothing is invented.
+*/
+function embeddedCmap(file, fontDict) {
+	const cidFont = descendantFont(file, fontDict);
+	const descriptor = file.resolve(cidFont.get("FontDescriptor") ?? PDF_NULL);
+	if (!(descriptor instanceof Map)) return void 0;
+	const program = file.resolve(descriptor.get("FontFile2") ?? PDF_NULL);
+	if (!(program instanceof PdfStream)) return void 0;
+	let glyphOf;
+	try {
+		glyphOf = parseTtf(file.streamData(program)).glyphForCodepoint;
+	} catch {
+		return;
+	}
+	const byGlyph = /* @__PURE__ */ new Map();
+	for (let cp = 32; cp <= BMP_END; cp++) {
+		if (cp >= SURROGATE_FIRST && cp <= SURROGATE_LAST) continue;
+		let gid = 0;
+		try {
+			gid = glyphOf(cp);
+		} catch {
+			continue;
+		}
+		if (gid > 0 && !byGlyph.has(gid)) byGlyph.set(gid, String.fromCodePoint(cp));
+	}
+	if (byGlyph.size === 0) return void 0;
+	const cidToGid = readCidToGid(file, cidFont);
+	if (!cidToGid) return byGlyph;
+	const out = /* @__PURE__ */ new Map();
+	cidToGid.forEach((gid, cid) => {
+		const text = byGlyph.get(gid);
+		if (text !== void 0) out.set(cid, text);
+	});
+	return out.size > 0 ? out : void 0;
+}
+/** §9.7.4.2 `/CIDToGIDMap` — a stream of two-byte glyph indices, CID by CID. */
+function readCidToGid(file, cidFont) {
+	const map = file.resolve(cidFont.get("CIDToGIDMap") ?? PDF_NULL);
+	if (!(map instanceof PdfStream)) return void 0;
+	const bytes = file.streamData(map);
+	const out = [];
+	for (let i = 0; i + 1 < bytes.length; i += 2) out.push(bytes[i] << 8 | bytes[i + 1]);
+	return out;
+}
+/**
+* §9.6.5 — a Type 3 font's glyphs are content streams, not outlines: what the
+* face draws is whatever each procedure paints, in the resources the font
+* states. `/Encoding` `/Differences` names the procedure a code selects and
+* `/CharProcs` holds it.
+*
+* ContentStreamCycleType3insideType3.pdf is a page of them — a stroked square
+* and a stroked triangle, with a second Type 3 font shown from inside the
+* square — and with the procedures unread the page came back as two letters of
+* substituted type an eighth of an inch tall.
+*/
+function type3Face(file, fontDict) {
+	const procs = file.resolve(fontDict.get("CharProcs") ?? PDF_NULL);
+	if (!(procs instanceof Map)) return void 0;
+	const names = differences(file, fontDict);
+	const resourcesVal = file.resolve(fontDict.get("Resources") ?? PDF_NULL);
+	return {
+		matrix: fontMatrix(file, fontDict),
+		resources: resourcesVal instanceof Map ? resourcesVal : void 0,
+		proc: (code) => {
+			const glyph = names.get(code);
+			if (glyph === void 0) return void 0;
+			const stream = file.resolve(procs.get(glyph) ?? PDF_NULL);
+			return stream instanceof PdfStream ? stream : void 0;
+		}
+	};
+}
+/** §9.6.5 `/FontMatrix` — glyph space to text space; a thousandth by default. */
+function fontMatrix(file, fontDict) {
+	const m = file.resolve(fontDict.get("FontMatrix") ?? PDF_NULL);
+	if (!Array.isArray(m) || m.length !== 6) return [
+		.001,
+		0,
+		0,
+		.001,
+		0,
+		0
+	];
+	const n = m.map((v) => asNumber(file.resolve(v), 0));
+	return [
+		n[0],
+		n[1],
+		n[2],
+		n[3],
+		n[4],
+		n[5]
+	];
+}
+/** §9.6.6.1 `/Encoding` `/Differences` — code → glyph name, as the array runs. */
+function differences(file, fontDict) {
+	const out = /* @__PURE__ */ new Map();
+	const encoding = file.resolve(fontDict.get("Encoding") ?? PDF_NULL);
+	if (!(encoding instanceof Map)) return out;
+	const list = file.resolve(encoding.get("Differences") ?? PDF_NULL);
+	if (!Array.isArray(list)) return out;
+	let code = 0;
+	for (const entry of list) {
+		const value = file.resolve(entry);
+		if (typeof value === "number") code = value;
+		else if (value instanceof PdfName) out.set(code++, value.value);
+	}
+	return out;
+}
+/** §9.8.2 `/Flags` — bit 7 is Italic, bit 19 ForceBold (bits numbered from 1). */
+var FLAG_ITALIC = 64;
+var FLAG_FORCE_BOLD = 1 << 18;
+/** §9.8.1 `/FontWeight` — 400 is normal, 700 bold; 600 is where "bold" begins. */
+var BOLD_WEIGHT = 600;
+/**
+* §9.8.1 — whether the face a run is shown in is bold or slanted.
+*
+* A descriptor is the witness where there is one, and the ONLY witness: it
+* states `/FontWeight`, `/ItalicAngle` and the `/Flags` bits, so one that gives
+* neither a weight nor the ForceBold bit is saying the face is not bold.
+* ArabicCIDTrueType.pdf shows why that matters — two of its four faces are
+* called `NewBasrahBold` and `DamascusBold`, which is the family's own name and
+* not a weight, and reading the name over the descriptor set two lines heavy
+* that no reader sets heavy.
+*
+* The name is read only where no descriptor exists at all, which is the
+* standard-14 case (§9.6.2.2): `Helvetica-BoldOblique` has nothing else to go
+* on. The subset prefix (`ISVAYD+`) is dropped first — six arbitrary capitals
+* may spell anything.
+*/
+function faceStyle(file, fontDict, isType0) {
+	const owner = isType0 ? descendantFont(file, fontDict) : fontDict;
+	const descriptor = file.resolve(owner.get("FontDescriptor") ?? PDF_NULL);
+	if (descriptor instanceof Map) {
+		const flags = asNumber(file.resolve(descriptor.get("Flags") ?? PDF_NULL), 0);
+		const weight = asNumber(file.resolve(descriptor.get("FontWeight") ?? PDF_NULL), 0);
+		const slant = asNumber(file.resolve(descriptor.get("ItalicAngle") ?? PDF_NULL), 0);
+		const bold = weight >= BOLD_WEIGHT || (flags & FLAG_FORCE_BOLD) !== 0;
+		const italic = slant !== 0 || (flags & FLAG_ITALIC) !== 0;
+		return {
+			...bold ? { bold } : {},
+			...italic ? { italic } : {}
+		};
+	}
+	const name = asName(file.resolve(fontDict.get("BaseFont") ?? PDF_NULL)).replace(/^[A-Z]{6}\+/u, "");
+	const bold = /bold|black|heavy/iu.test(name);
+	const italic = /italic|oblique/iu.test(name);
+	return {
+		...bold ? { bold } : {},
+		...italic ? { italic } : {}
+	};
+}
+/** §9.7.4 — a `/Type0` font's one descendant CIDFont, which owns the descriptor. */
+function descendantFont(file, fontDict) {
+	const descFonts = file.resolve(fontDict.get("DescendantFonts") ?? PDF_NULL);
+	const first = Array.isArray(descFonts) ? file.resolve(descFonts[0] ?? PDF_NULL) : PDF_NULL;
+	return first instanceof Map ? first : /* @__PURE__ */ new Map();
+}
 function simpleWidths(file, fontDict) {
 	const first = asNumber(file.resolve(fontDict.get("FirstChar") ?? PDF_NULL), 0);
 	const widthsVal = file.resolve(fontDict.get("Widths") ?? PDF_NULL);

package/dist/esm/pdf-reader/image-decode.js

@@ -3,6 +3,7 @@ import { encodePng } from "../core/png-encode.js";
 import { lzwDecodeMsb } from "../core/lzw.js";
 import { reversePredictor } from "./predictor.js";
 import { decodeCcitt } from "./ccitt.js";
+import { decodeJpeg } from "./jpeg.js";
 import { unzlibSync } from "fflate";
 //#region src/pdf-reader/image-decode.ts
 var MAX_PIXELS = 4e7;
@@ -30,10 +31,13 @@ function decodePdfImage(file, stream) {
 	const filters = filterNames(file, d);
 	const last = filters[filters.length - 1];
 	if (last === "DCTDecode" || last === "DCT") {
-		const degraded = hasSMask(file, d) ? "image transparency dropped (JPEG carries no alpha)" : void 0;
+		const jpegBytes = applyChainExceptLast(filters, stream.data);
+		const masked = hasSMask(file, d) ? maskedJpeg(file, d, jpegBytes, width, height) : void 0;
+		if (masked) return masked;
+		const degraded = hasSMask(file, d) ? "image transparency dropped (JPEG could not be decoded to attach its mask)" : void 0;
 		return {
 			ok: true,
-			bytes: applyChainExceptLast(filters, stream.data),
+			bytes: jpegBytes,
 			format: "jpeg",
 			widthPx: width,
 			heightPx: height,
@@ -276,14 +280,49 @@ function unpackSamples(raw, width, height, ncomp, bpc) {
 	}
 	return out;
 }
+/**
+* A JPEG with its `/SMask` folded in, as a PNG.
+*
+* A JPEG has no alpha channel, so the only way to honour the mask is to decode
+* the picture, decode the mask, put them together and re-encode. Both are
+* usually DCT themselves — 22060_A1_01_Plans.pdf stores each floor plan as a
+* wash and its line work as a grey JPEG mask of the same 2480x2630 — so this
+* costs a full baseline decode of two images, and is spent only where a mask
+* actually exists.
+*
+* @returns The recomposed PNG, or `undefined` when either image is beyond the
+*          baseline decoder — the caller then carries the JPEG through as it is.
+*/
+function maskedJpeg(file, d, jpegBytes, width, height) {
+	const image = decodeJpeg(jpegBytes);
+	if (!image) return void 0;
+	const alpha = decodeSMask(file, d, image.width, image.height);
+	if (!alpha) return void 0;
+	const { color: pngColor, samples } = combineAlpha(image.components === 1 ? {
+		color: "gray",
+		samples: image.samples
+	} : {
+		color: "rgb",
+		samples: image.samples
+	}, alpha);
+	return {
+		ok: true,
+		bytes: encodePng(image.width, image.height, pngColor, samples),
+		format: "png",
+		widthPx: width,
+		heightPx: height
+	};
+}
 function decodeSMask(file, d, width, height) {
 	const sm = file.resolve(d.get("SMask") ?? PDF_NULL);
 	if (!(sm instanceof PdfStream)) return void 0;
 	const sw = intOf(file.get(sm.dict, "Width"));
 	const sh = intOf(file.get(sm.dict, "Height"));
 	if (sw <= 0 || sh <= 0) return void 0;
-	const decoded = decodeToSamples(file, sm, filterNames(file, sm.dict), sw, sh);
-	if (typeof decoded === "string") return void 0;
+	const maskFilters = filterNames(file, sm.dict);
+	const maskLast = maskFilters[maskFilters.length - 1];
+	const decoded = maskLast === "DCTDecode" || maskLast === "DCT" ? jpegSamples(applyChainExceptLast(maskFilters, sm.data)) : decodeToSamples(file, sm, maskFilters, sw, sh);
+	if (decoded === void 0 || typeof decoded === "string") return void 0;
 	const ch = decoded.color === "rgb" ? 3 : 1;
 	const gray = new Uint8Array(sw * sh);
 	for (let i = 0; i < sw * sh; i++) gray[i] = decoded.samples[i * ch];
@@ -298,6 +337,18 @@ function decodeSMask(file, d, width, height) {
 	}
 	return { data: out };
 }
+/** A DCT-coded mask decoded to samples, or `undefined` past the baseline decoder. */
+function jpegSamples(bytes) {
+	const decoded = decodeJpeg(bytes);
+	if (!decoded) return void 0;
+	return decoded.components === 1 ? {
+		color: "gray",
+		samples: decoded.samples
+	} : {
+		color: "rgb",
+		samples: decoded.samples
+	};
+}
 function combineAlpha(color, alpha) {
 	const px = alpha.data.length;
 	if (color.color === "gray") {

package/dist/esm/pdf-reader/images.d.ts

@@ -17,6 +17,12 @@ export interface PdfImage {
     readonly y: number;
     /** Enclosing marked-content id, if the placement was inside a `/Figure`. */
     readonly mcid?: number;
+    /**
+     * §8.5.3 — where this was painted, as the chain of positions leading to it.
+     * The same key a lifted path carries, so the two can be ordered against each
+     * other: a picture drawn over a filled box has the larger key.
+     */
+    readonly orderKey: ReadonlyArray<number>;
 }
 /** The images lifted off one page plus any losses for images that could not be reconstructed. */
 export interface PageImages {

package/dist/esm/pdf-reader/images.js

@@ -2,6 +2,7 @@ import { PDF_NULL, PdfName, PdfStream } from "../pdf/objects.js";
 import { FEATURES } from "../core/ir/features.js";
 import { interpretContent, multiply } from "./content.js";
 import { decodePdfImage } from "./image-decode.js";
+import { collectPageAppearances } from "./annots.js";
 //#region src/pdf-reader/images.ts
 var NO_FONTS = /* @__PURE__ */ new Map();
 var MAX_FORM_DEPTH = 12;
@@ -26,10 +27,23 @@ function collectPageImages(file, page) {
 			detail
 		});
 	};
-	const walk = (resources, content, baseCtm, depth, inheritedMcid) => {
+	const walk = (resources, content, baseCtm, depth, inheritedMcid, prefix) => {
 		const xobjects = resources ? file.get(resources, "XObject") : PDF_NULL;
 		const xobjDict = xobjects instanceof Map ? xobjects : void 0;
-		for (const placement of interpretContent(content, NO_FONTS, baseCtm).images) {
+		const result = interpretContent(content, NO_FONTS, baseCtm);
+		const patterns = resources ? file.get(resources, "Pattern") : PDF_NULL;
+		const patternDict = patterns instanceof Map ? patterns : void 0;
+		for (const vector of result.vectors) {
+			if (vector.patternName === void 0 || depth >= MAX_FORM_DEPTH) continue;
+			const stream = patternDict ? file.resolve(patternDict.get(vector.patternName) ?? PDF_NULL) : PDF_NULL;
+			if (!(stream instanceof PdfStream) || visiting.has(stream)) continue;
+			if (file.get(stream.dict, "PatternType") !== 1) continue;
+			visiting.add(stream);
+			const patternRes = file.get(stream.dict, "Resources");
+			walk(patternRes instanceof Map ? patternRes : resources, file.streamData(stream), multiply(matrixOf(file, stream.dict), baseCtm), depth + 1, inheritedMcid, [...prefix, vector.order]);
+			visiting.delete(stream);
+		}
+		for (const placement of result.images) {
 			if (images.length >= MAX_IMAGES) return;
 			const stream = xobjDict ? file.resolve(xobjDict.get(placement.name) ?? PDF_NULL) : PDF_NULL;
 			if (!(stream instanceof PdfStream)) continue;
@@ -38,13 +52,16 @@ function collectPageImages(file, page) {
 			if (subtype === "Image") {
 				const decoded = decodePdfImage(file, stream);
 				if (decoded.ok) {
-					images.push(geometry(placement.ctm, decoded, mcid));
+					images.push({
+						...geometry(placement.ctm, decoded, mcid),
+						orderKey: [...prefix, placement.order]
+					});
 					if (decoded.degraded) addLoss("degraded", decoded.degraded);
 				} else addLoss(decoded.severity, decoded.detail);
 			} else if (subtype === "Form" && depth < MAX_FORM_DEPTH && !visiting.has(stream)) {
 				visiting.add(stream);
 				const formRes = file.get(stream.dict, "Resources");
-				walk(formRes instanceof Map ? formRes : resources, file.streamData(stream), multiply(matrixOf(file, stream.dict), placement.ctm), depth + 1, mcid);
+				walk(formRes instanceof Map ? formRes : resources, file.streamData(stream), multiply(matrixOf(file, stream.dict), placement.ctm), depth + 1, mcid, [...prefix, placement.order]);
 				visiting.delete(stream);
 			}
 		}
@@ -56,7 +73,10 @@ function collectPageImages(file, page) {
 		1,
 		0,
 		0
-	], 0, void 0);
+	], 0, void 0, []);
+	collectPageAppearances(file, page).forEach((appearance, index) => {
+		walk(appearance.resources ?? page.resources, file.streamData(appearance.stream), appearance.ctm, 1, void 0, [Number.MAX_SAFE_INTEGER, index]);
+	});
 	return {
 		images,
 		losses: [...lossByDetail.values()]

package/dist/esm/pdf-reader/jpeg.d.ts

@@ -0,0 +1,18 @@
+/** A decoded JPEG: 8-bit interleaved samples, one or three components. */
+export interface DecodedJpeg {
+    readonly width: number;
+    readonly height: number;
+    /** 1 = grayscale, 3 = RGB (already converted from YCbCr where it applies). */
+    readonly components: 1 | 3;
+    /** `width * height * components` bytes, row-major. */
+    readonly samples: Uint8Array;
+}
+/**
+ * Decode a baseline JPEG to interleaved 8-bit samples.
+ *
+ * @param bytes The JPEG stream, starting at its SOI marker.
+ * @returns The decoded image, or `undefined` when the stream is not a baseline
+ *          JPEG this decoder handles (progressive, arithmetic, 12-bit, CMYK) or
+ *          is malformed — the caller then carries the original bytes through.
+ */
+export declare function decodeJpeg(bytes: Uint8Array): DecodedJpeg | undefined;