pdf-codec 5.5.0 → 5.6.0

package/README.md

@@ -95,7 +95,7 @@ Both accept an optional `signal` (`AbortSignal`); `readPdf` additionally takes a
 
 **Reading a subset of pages.** `readPdf(bytes, { pages: [0, 1, 2, -1] })` reads only the listed pages: zero-based indices into the page tree, a negative index counted from the end (`-1` is the last page). What a selected read skips: an unselected page's content stream is never fetched, decoded or interpreted, so the fonts and images only unselected pages use are never resolved, and no embedded file is decoded, so `attachments` is absent from a page-selected result (an attachment is document-level payload whose size is independent of the pages asked for); an absent `attachments` therefore means "not read" whenever `pageCount` is set, which only a page-selected read does, so check `pageCount` before concluding a document has no attachments. The case this exists for is identifying a document from its first pages, or reading a code from its last page, inside a memory-capped runtime such as a Cloudflare Worker isolate, without paying for every page's content. What it still reads whole, because page references resolve against it or because it is document-level and holds no page content stream: the page tree, the outline, named destinations, optional-content layers, the AcroForm, the structure element tree and the `/ParentTree` number tree (both of which scale with the document), metadata and package residue; every one of those but the page tree and metadata can be left out too, with `surfaces` (below). Two surfaces are built from page content and so cover selected pages only: the structure-ownership association an item's `structure` field names (with its parent-tree diagnostics) and the `page-boxes` residue row. A destination a link states as a direct array is minted into `destinations` (as `dest1`, `dest2`, ...) only when its page is interpreted, so an unselected page's direct link destinations are absent and a minted name depends on which pages were read (and on whether the outline was read, below); named destinations are unaffected. Duplicates collapse and the result's `pages` holds the selected pages in ascending document order, each carrying its source position as `index` (read it through `sourcePageIndex(page, position)`, which falls back to the position on a full read), with the page tree's length as the document's `pageCount`; every document-level page reference keeps naming source indices, so a reference to a selected page resolves through `index`, and one to an unselected page names a page the result does not hold. A full read sets neither field, because there `pages.length` and each page's position already state them. An empty selection is valid and reads no page, which makes `{ pages: [] }` the cheapest way to learn a file's page count and metadata. An entry naming no page (outside `-pageCount` to `pageCount - 1`, or not an integer, `NaN` and the infinities included; `-0` is page 0) throws `PdfPageSelectionError` (a `PdfParseError` with code `pdf/page-out-of-range` or `pdf/page-index-not-integer`, carrying `pageIndex` and `pageCount`) before any page is read. A page-selected `LayoutDocument` is a reading of part of a file, not a document to re-emit: `writePdf` refuses one (any document carrying `pageCount`) with `PdfPartialDocumentError`, since it places pages by position and the references would point at the wrong pages.
 
-**Leaving document-level surfaces out.** `readPdf(bytes, { surfaces: { structure: false, outline: false } })` reads the document without the surfaces turned off. `ReadPdfOptions.surfaces` is one object of independent booleans (`ReadPdfSurfaces`), one per surface, each read unless set to `false`, so omitting the setting reads everything exactly as before. It is independent of `pages`, applying to a full read and a page-selected read alike, and combined with a small selection it is what keeps identifying a document cheap: on a long tagged PDF the structure element tree and its `/ParentTree` can be most of what a page-selected read still parses, and `{ pages: [0, 1, 2, -1], surfaces: { outline: false, destinations: false, form: false, layers: false, structure: false, residue: false } }` reads nothing beyond opening the document (cross-reference table, trailer, catalog and any encryption dictionary), the page tree, metadata and those four pages. A surface turned off is never parsed (its part of the catalog is not walked, so a malformed outline, form, layer list or structure tree reports no diagnostic), its `LayoutDocument` field is absent whatever the file holds, and the result names it in `skippedSurfaces` (in the order `LayoutDocumentSurfaceSchema` lists them, absent when every surface was read). An absent `outline`, `destinations`, `form`, `layers`, `structure` or `source` therefore means "not read" whenever `skippedSurfaces` names it, so check `skippedSurfaces` before concluding a document has none, as with `pageCount` and attachments.
+**Leaving document-level surfaces out.** `readPdf(bytes, { surfaces: { structure: false, outline: false } })` reads the document without the surfaces turned off. `ReadPdfOptions.surfaces` is one object of independent booleans (`ReadPdfSurfaces`), one per surface, each read unless set to `false`, so omitting the setting reads everything exactly as before. It is independent of `pages`, applying to a full read and a page-selected read alike, and combined with a small selection it is what keeps identifying a document cheap: on a long tagged PDF the structure element tree and its `/ParentTree` can be most of what a page-selected read still parses, and `{ pages: [0, 1, 2, -1], surfaces: { outline: false, destinations: false, form: false, layers: false, structure: false, residue: false, images: false } }` reads nothing beyond opening the document (cross-reference table, trailer, catalog and any encryption dictionary), the page tree, metadata and those four pages' text and vector content. A surface turned off is never parsed (its part of the catalog is not walked, so a malformed outline, form, layer list or structure tree reports no diagnostic), its `LayoutDocument` field is absent whatever the file holds (`images`, which every `LayoutDocument` carries, is left empty instead), and the result names it in `skippedSurfaces` (in the order `LayoutDocumentSurfaceSchema` lists them, absent when every surface was read). An absent `outline`, `destinations`, `form`, `layers`, `structure` or `source`, or an empty `images`, therefore means "not read" whenever `skippedSurfaces` names it, so check `skippedSurfaces` before concluding a document has none, as with `pageCount` and attachments.
 
 Each surface, and what page items lose without it (everything else about every page item is exactly what a read with the surface on produces, apart from the renumbering a skipped outline causes):
 
@@ -111,6 +111,8 @@ Each surface, and what page items lose without it (everything else about every p
 
 - `residue`: the package-level residue rows (`source`), the per-page `page-boxes` row included. Page items do not depend on it, and `metadata` still reads the XMP packet it falls back to.
 
+- `images`: the image registry (`images`), every image XObject and inline image a read page draws, decoded to PNG or passed through as JPEG. Without it no image stream is decoded or diagnosed, `images` is an empty record, and each page's `image` items are left out, since they would name assets that were never read. Decoding an image holds its decoded stream, its 8-bit raster (unless the stream already is one) and the PNG encoder's buffers at once, in proportion to its pixels, so a read that wants only text, such as text extraction in a memory-capped Worker isolate, leaves this out.
+
 A `LayoutDocument` read with any surface skipped is a reading with parts of the file deliberately unread, so `writePdf` refuses one (any document carrying `skippedSurfaces`) with `PdfSkippedSurfacesError`, which names the skipped surfaces; a document that is also page-selected reports `PdfPartialDocumentError` first.
 
 **Page boundaries: the crop box is the visible region** (ISO 32000-1 14.11.2). A page's reported `widthPt`/`heightPt` and coordinate frame come from its effective `/CropBox` — the rectangle a viewer displays and prints, inherited through the page tree like `/MediaBox` and defaulting to it — not from the media box: content an author placed outside the crop box (printer's marks, bleed, off-page slugs) is not visible and does not extract. Content wholly outside the crop box is dropped; content straddling the boundary keeps its original unclipped geometry (the item layer records what the file states — a viewer's clipping is a rendering fact, not source data); link annotations are anchored constructs rather than painted content and are never filtered, the same line the optional-content filter draws. The declared boundary rectangles a distinct crop box hides — plus `/BleedBox`/`/TrimBox`/`/ArtBox`, print-production facts with no field in the layout model — are quarantined verbatim as the `page-boxes` package-level residue row rather than silently dropped. A degenerate `/CropBox` (zero width or height) falls back to the media box with a `pdf/invalid-crop-box` warning.

package/dist/codec.d.cts

@@ -321,6 +321,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
   }, z.core.$strict>>>;
   skippedSurfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
     structure: "structure";
+    images: "images";
     destinations: "destinations";
     outline: "outline";
     layers: "layers";

package/dist/codec.d.ts

@@ -321,6 +321,7 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
   }, z.core.$strict>>>;
   skippedSurfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
     structure: "structure";
+    images: "images";
     destinations: "destinations";
     outline: "outline";
     layers: "layers";

package/dist/filters.cjs

@@ -8,6 +8,24 @@ const require_predictors = require("./predictors.cjs");
 //#region src/filters.ts
 const BITS_PER_BYTE = 8;
 const BYTE_MASK = 255;
+var GrowableBytes = class {
+	#buffer;
+	#length = 0;
+	constructor(capacity) {
+		this.#buffer = new Uint8Array(Math.max(1, capacity));
+	}
+	push(byte) {
+		if (this.#length === this.#buffer.length) {
+			const grown = new Uint8Array(this.#buffer.length * 2);
+			grown.set(this.#buffer);
+			this.#buffer = grown;
+		}
+		this.#buffer[this.#length++] = byte;
+	}
+	toBytes() {
+		return this.#buffer.slice(0, this.#length);
+	}
+};
 function decodeStream(raw, dict, sink, resolve) {
 	const filters = filterNames(dict);
 	const parms = decodeParmsList(dict, filters.length);
@@ -162,7 +180,7 @@ function concatTwo(a, b) {
 	return out;
 }
 function lzwDecode(data, earlyChange, sink) {
-	const out = [];
+	const out = new GrowableBytes(data.length);
 	let dict = initialLzwDictionary();
 	let nextCode = LZW_FIRST_NEW_CODE;
 	let codeWidth = LZW_INITIAL_CODE_WIDTH;
@@ -214,7 +232,7 @@ function lzwDecode(data, earlyChange, sink) {
 		}
 		prevEntry = entry;
 	}
-	return Uint8Array.from(out);
+	return out.toBytes();
 }
 const ASCII85_GROUP_BYTES = 4;
 const ASCII85_ZERO_GROUP_MARKER = 122;
@@ -238,7 +256,7 @@ function ascii85GroupBytes(digits, byteCount) {
 	].slice(0, byteCount);
 }
 function ascii85Decode(data) {
-	const out = [];
+	const out = new GrowableBytes(data.length);
 	let tuple = [];
 	let i = 0;
 	if (data.length >= 2 && data[0] === ASCII85_OPTIONAL_PREFIX_LT && data[1] === ASCII85_END_MARKER) i = 2;
@@ -247,22 +265,22 @@ function ascii85Decode(data) {
 		if (byte === ASCII85_END_MARKER) break;
 		if (require_bytes_reader.isAsciiWhitespace(byte)) continue;
 		if (byte === ASCII85_ZERO_GROUP_MARKER && tuple.length === 0) {
-			out.push(0, 0, 0, 0);
+			for (let zero = 0; zero < ASCII85_GROUP_BYTES; zero++) out.push(0);
 			continue;
 		}
 		if (byte < ASCII85_MIN_DIGIT || byte > ASCII85_MAX_DIGIT) continue;
 		tuple.push(byte - ASCII85_MIN_DIGIT);
 		if (tuple.length === ASCII85_GROUP_DIGITS) {
-			out.push(...ascii85GroupBytes(tuple, ASCII85_GROUP_BYTES));
+			for (const decoded of ascii85GroupBytes(tuple, ASCII85_GROUP_BYTES)) out.push(decoded);
 			tuple = [];
 		}
 	}
 	if (tuple.length > 1) {
 		const padded = tuple.slice();
 		while (padded.length < ASCII85_GROUP_DIGITS) padded.push(ASCII85_MAX_DIGIT_VALUE);
-		out.push(...ascii85GroupBytes(padded, tuple.length - 1));
+		for (const decoded of ascii85GroupBytes(padded, tuple.length - 1)) out.push(decoded);
 	}
-	return Uint8Array.from(out);
+	return out.toBytes();
 }
 const ASCII_DIGIT_ZERO = 48;
 const ASCII_DIGIT_NINE = 57;
@@ -279,21 +297,28 @@ function hexDigitValue(byte) {
 	if (byte >= ASCII_LOWER_A && byte <= ASCII_LOWER_F) return byte - ASCII_LOWER_A + HEX_LETTER_DIGIT_OFFSET;
 }
 function asciiHexDecode(data) {
-	const digits = [];
+	let digitCount = 0;
+	for (const byte of data) {
+		if (byte === ASCII_HEX_TERMINATOR) break;
+		if (hexDigitValue(byte) !== void 0) digitCount++;
+	}
+	const out = new Uint8Array(Math.ceil(digitCount / 2));
+	let digit = 0;
 	for (const byte of data) {
 		if (byte === ASCII_HEX_TERMINATOR) break;
 		const value = hexDigitValue(byte);
-		if (value !== void 0) digits.push(value);
+		if (value !== void 0) {
+			const index = Math.floor(digit / 2);
+			out[index] = digit % 2 === 0 ? value << HEX_NIBBLE_BITS : (out[index] ?? 0) | value;
+			digit++;
+		}
 	}
-	if (digits.length % 2 === 1) digits.push(0);
-	const out = new Uint8Array(digits.length / 2);
-	for (let i = 0; i < out.length; i++) out[i] = digits[i * 2] << HEX_NIBBLE_BITS | digits[i * 2 + 1];
 	return out;
 }
 const RUN_LENGTH_EOD = 128;
 const RUN_LENGTH_REPEAT_COUNT_BASE = 257;
 function runLengthDecode(data) {
-	const out = [];
+	const out = new GrowableBytes(data.length);
 	let i = 0;
 	while (i < data.length) {
 		const length = data[i];
@@ -309,7 +334,7 @@ function runLengthDecode(data) {
 			for (let j = 0; j < count; j++) out.push(byte);
 		}
 	}
-	return Uint8Array.from(out);
+	return out.toBytes();
 }
 //#endregion
 exports.ascii85Decode = ascii85Decode;

package/dist/filters.js

@@ -7,6 +7,24 @@ import { applyPredictor, readPredictorParams } from "./predictors.js";
 //#region src/filters.ts
 const BITS_PER_BYTE = 8;
 const BYTE_MASK = 255;
+var GrowableBytes = class {
+	#buffer;
+	#length = 0;
+	constructor(capacity) {
+		this.#buffer = new Uint8Array(Math.max(1, capacity));
+	}
+	push(byte) {
+		if (this.#length === this.#buffer.length) {
+			const grown = new Uint8Array(this.#buffer.length * 2);
+			grown.set(this.#buffer);
+			this.#buffer = grown;
+		}
+		this.#buffer[this.#length++] = byte;
+	}
+	toBytes() {
+		return this.#buffer.slice(0, this.#length);
+	}
+};
 function decodeStream(raw, dict, sink, resolve) {
 	const filters = filterNames(dict);
 	const parms = decodeParmsList(dict, filters.length);
@@ -161,7 +179,7 @@ function concatTwo(a, b) {
 	return out;
 }
 function lzwDecode(data, earlyChange, sink) {
-	const out = [];
+	const out = new GrowableBytes(data.length);
 	let dict = initialLzwDictionary();
 	let nextCode = LZW_FIRST_NEW_CODE;
 	let codeWidth = LZW_INITIAL_CODE_WIDTH;
@@ -213,7 +231,7 @@ function lzwDecode(data, earlyChange, sink) {
 		}
 		prevEntry = entry;
 	}
-	return Uint8Array.from(out);
+	return out.toBytes();
 }
 const ASCII85_GROUP_BYTES = 4;
 const ASCII85_ZERO_GROUP_MARKER = 122;
@@ -237,7 +255,7 @@ function ascii85GroupBytes(digits, byteCount) {
 	].slice(0, byteCount);
 }
 function ascii85Decode(data) {
-	const out = [];
+	const out = new GrowableBytes(data.length);
 	let tuple = [];
 	let i = 0;
 	if (data.length >= 2 && data[0] === ASCII85_OPTIONAL_PREFIX_LT && data[1] === ASCII85_END_MARKER) i = 2;
@@ -246,22 +264,22 @@ function ascii85Decode(data) {
 		if (byte === ASCII85_END_MARKER) break;
 		if (isAsciiWhitespace(byte)) continue;
 		if (byte === ASCII85_ZERO_GROUP_MARKER && tuple.length === 0) {
-			out.push(0, 0, 0, 0);
+			for (let zero = 0; zero < ASCII85_GROUP_BYTES; zero++) out.push(0);
 			continue;
 		}
 		if (byte < ASCII85_MIN_DIGIT || byte > ASCII85_MAX_DIGIT) continue;
 		tuple.push(byte - ASCII85_MIN_DIGIT);
 		if (tuple.length === ASCII85_GROUP_DIGITS) {
-			out.push(...ascii85GroupBytes(tuple, ASCII85_GROUP_BYTES));
+			for (const decoded of ascii85GroupBytes(tuple, ASCII85_GROUP_BYTES)) out.push(decoded);
 			tuple = [];
 		}
 	}
 	if (tuple.length > 1) {
 		const padded = tuple.slice();
 		while (padded.length < ASCII85_GROUP_DIGITS) padded.push(ASCII85_MAX_DIGIT_VALUE);
-		out.push(...ascii85GroupBytes(padded, tuple.length - 1));
+		for (const decoded of ascii85GroupBytes(padded, tuple.length - 1)) out.push(decoded);
 	}
-	return Uint8Array.from(out);
+	return out.toBytes();
 }
 const ASCII_DIGIT_ZERO = 48;
 const ASCII_DIGIT_NINE = 57;
@@ -278,21 +296,28 @@ function hexDigitValue(byte) {
 	if (byte >= ASCII_LOWER_A && byte <= ASCII_LOWER_F) return byte - ASCII_LOWER_A + HEX_LETTER_DIGIT_OFFSET;
 }
 function asciiHexDecode(data) {
-	const digits = [];
+	let digitCount = 0;
+	for (const byte of data) {
+		if (byte === ASCII_HEX_TERMINATOR) break;
+		if (hexDigitValue(byte) !== void 0) digitCount++;
+	}
+	const out = new Uint8Array(Math.ceil(digitCount / 2));
+	let digit = 0;
 	for (const byte of data) {
 		if (byte === ASCII_HEX_TERMINATOR) break;
 		const value = hexDigitValue(byte);
-		if (value !== void 0) digits.push(value);
+		if (value !== void 0) {
+			const index = Math.floor(digit / 2);
+			out[index] = digit % 2 === 0 ? value << HEX_NIBBLE_BITS : (out[index] ?? 0) | value;
+			digit++;
+		}
 	}
-	if (digits.length % 2 === 1) digits.push(0);
-	const out = new Uint8Array(digits.length / 2);
-	for (let i = 0; i < out.length; i++) out[i] = digits[i * 2] << HEX_NIBBLE_BITS | digits[i * 2 + 1];
 	return out;
 }
 const RUN_LENGTH_EOD = 128;
 const RUN_LENGTH_REPEAT_COUNT_BASE = 257;
 function runLengthDecode(data) {
-	const out = [];
+	const out = new GrowableBytes(data.length);
 	let i = 0;
 	while (i < data.length) {
 		const length = data[i];
@@ -308,7 +333,7 @@ function runLengthDecode(data) {
 			for (let j = 0; j < count; j++) out.push(byte);
 		}
 	}
-	return Uint8Array.from(out);
+	return out.toBytes();
 }
 //#endregion
 export { ascii85Decode, asciiHexDecode, decodeStream, lzwDecode, runLengthDecode };

package/dist/images-read.cjs

@@ -58,27 +58,51 @@ function resolveColorSpace(csObj, resolver, sink) {
 		name: family ?? "(unrecognised array colour space)"
 	};
 }
-function unpackSamples(data, width, height, componentsPerPixel, bitsPerComponent) {
-	if (bitsPerComponent === BITS_PER_BYTE) return Array.from(data.subarray(0, width * height * componentsPerPixel));
+/**
+* Allocates the buffers one `decodeImageSamples` call needs and counts their bytes, so a test can bound the decode's memory in bytes rather than time.
+*/
+var SampleDecodeWork = class {
+	#bytesAllocated = 0;
+	/** Bytes of every buffer the decode allocated: its raster, its one reusable row and its lookup table. Each lives until the decode returns, so this is also the decode's peak; a view onto the stream it was given costs nothing. */
+	get bytesAllocated() {
+		return this.#bytesAllocated;
+	}
+	/**
+	* A zero-filled buffer of `length` bytes, counted.
+	* @param length - Its length in bytes.
+	* @returns The buffer.
+	*/
+	allocate(length) {
+		this.#bytesAllocated += length;
+		return new Uint8Array(length);
+	}
+};
+function readSampleRow(data, row, bitsPerComponent, target) {
+	const samplesPerRow = target.length;
+	if (bitsPerComponent === BITS_PER_BYTE) {
+		const rowStart = row * samplesPerRow;
+		for (let s = 0; s < samplesPerRow; s++) target[s] = data[rowStart + s] ?? 0;
+		return;
+	}
+	const rowStart = row * Math.ceil(samplesPerRow * bitsPerComponent / BITS_PER_BYTE);
+	const sampleMask = (1 << bitsPerComponent) - 1;
+	for (let s = 0; s < samplesPerRow; s++) {
+		const bitPos = s * bitsPerComponent;
+		const byte = data[rowStart + Math.floor(bitPos / BITS_PER_BYTE)] ?? 0;
+		const shift = BITS_PER_BYTE - bitsPerComponent - bitPos % BITS_PER_BYTE;
+		target[s] = byte >> shift & sampleMask;
+	}
+}
+function forEachSampleRow(data, width, height, componentsPerPixel, bitsPerComponent, work, visit) {
 	const samplesPerRow = width * componentsPerPixel;
-	const bytesPerRow = Math.ceil(samplesPerRow * bitsPerComponent / BITS_PER_BYTE);
-	const out = [];
+	const rowSamples = work.allocate(samplesPerRow);
 	for (let row = 0; row < height; row++) {
-		const rowStart = row * bytesPerRow;
-		let bitPos = 0;
-		for (let s = 0; s < samplesPerRow; s++) {
-			let value = 0;
-			for (let b = 0; b < bitsPerComponent; b++) {
-				const byteIndex = rowStart + Math.floor(bitPos / BITS_PER_BYTE);
-				const bitIndex = 7 - bitPos % BITS_PER_BYTE;
-				const bit = (data[byteIndex] ?? 0) >> bitIndex & 1;
-				value = value << 1 | bit;
-				bitPos++;
-			}
-			out.push(value);
-		}
+		readSampleRow(data, row, bitsPerComponent, rowSamples);
+		visit(rowSamples, row * samplesPerRow);
 	}
-	return out;
+}
+function availableSampleCount(data, sampleCount, bitsPerComponent) {
+	return bitsPerComponent === BITS_PER_BYTE ? Math.min(data.length, sampleCount) : sampleCount;
 }
 function scaleToByte(value, maxValue, inverted) {
 	const v = inverted ? maxValue - value : value;
@@ -107,56 +131,89 @@ function sampleFromPalette(base, lookup, offset) {
 		b: lookup[offset + 2] ?? 0
 	};
 }
-function buildRawImage(data, width, height, bitsPerComponent, colorSpace, inverted) {
+function scaleTable(maxValue, inverted, work) {
+	const table = work.allocate(maxValue + 1);
+	for (let value = 0; value <= maxValue; value++) table[value] = scaleToByte(value, maxValue, inverted);
+	return table;
+}
+/**
+* Decodes an image's samples into the 8-bit raster `encodePng` takes, holding at most the raster itself, one row of samples and a lookup table of at most 256 entries beside the stream; nothing is allocated per sample.
+* @param data - The image's decoded stream: rows of `width` pixels padded to a whole byte, sub-byte samples packed most significant bit first.
+* @param width - Pixels per row.
+* @param height - Rows.
+* @param bitsPerComponent - 1, 2, 4 or 8.
+* @param colorSpace - The resolved colour space; never `unsupported`.
+* @param inverted - Whether `/Decode` is `[1 0]`, which a gray, RGB or CMYK sample is inverted by and an indexed one ignores.
+* @param work - Counts the bytes allocated; see SampleDecodeWork.
+* @returns A gray or RGB raster. An 8-bit gray or RGB image with no `/Decode` inversion is already that raster, so its data is a view onto `data` and costs no allocation. An 8-bit stream shorter than the image yields a gray, RGB or indexed raster holding only the pixels the stream covers, and a CMYK one in which each missing sample reads as 0.
+*/
+function decodeImageSamples(data, width, height, bitsPerComponent, colorSpace, inverted, work = new SampleDecodeWork()) {
 	const maxValue = (1 << bitsPerComponent) - 1;
+	const pixelCount = width * height;
 	if (colorSpace.kind === "indexed") {
-		const indices = unpackSamples(data, width, height, 1, bitsPerComponent);
+		const channels = colorSpace.base.kind === "gray" ? 1 : RGB_CHANNEL_COUNT;
 		const baseComponents = componentsOf(colorSpace.base);
-		const out = new Uint8Array(width * height * (colorSpace.base.kind === "gray" ? 1 : RGB_CHANNEL_COUNT));
-		let outIdx = 0;
-		for (const index of indices) {
+		const palette = work.allocate((maxValue + 1) * channels);
+		for (let index = 0; index <= maxValue; index++) {
 			const rgb = sampleFromPalette(colorSpace.base, colorSpace.lookup, index * baseComponents);
-			if (colorSpace.base.kind === "gray") out[outIdx++] = rgb.r;
-			else {
-				out[outIdx++] = rgb.r;
-				out[outIdx++] = rgb.g;
-				out[outIdx++] = rgb.b;
+			palette[index * channels] = rgb.r;
+			if (channels === RGB_CHANNEL_COUNT) {
+				palette[index * channels + 1] = rgb.g;
+				palette[index * channels + 2] = rgb.b;
 			}
 		}
+		const out = work.allocate(pixelCount * channels);
+		const indexed = availableSampleCount(data, pixelCount, bitsPerComponent);
+		forEachSampleRow(data, width, height, 1, bitsPerComponent, work, (indices, firstPixel) => {
+			const count = Math.min(indices.length, indexed - firstPixel);
+			for (let i = 0; i < count; i++) {
+				const entry = indices[i] * channels;
+				const at = (firstPixel + i) * channels;
+				for (let channel = 0; channel < channels; channel++) out[at + channel] = palette[entry + channel];
+			}
+		});
 		return {
 			width,
 			height,
-			channels: colorSpace.base.kind === "gray" ? 1 : RGB_CHANNEL_COUNT,
+			channels,
 			data: out
 		};
 	}
-	if (colorSpace.kind === "gray") {
-		const samples = unpackSamples(data, width, height, 1, bitsPerComponent);
-		return {
+	if (colorSpace.kind === "gray" || colorSpace.kind === "rgb") {
+		const channels = colorSpace.kind === "gray" ? 1 : RGB_CHANNEL_COUNT;
+		const available = availableSampleCount(data, pixelCount * channels, bitsPerComponent);
+		if (bitsPerComponent === BITS_PER_BYTE && !inverted) return {
 			width,
 			height,
-			channels: 1,
-			data: Uint8Array.from(samples, (v) => scaleToByte(v, maxValue, inverted))
+			channels,
+			data: data.subarray(0, available)
 		};
-	}
-	if (colorSpace.kind === "rgb") {
-		const samples = unpackSamples(data, width, height, RGB_CHANNEL_COUNT, bitsPerComponent);
-		const out = Uint8Array.from(samples, (v) => scaleToByte(v, maxValue, inverted));
+		const scale = scaleTable(maxValue, inverted, work);
+		const out = work.allocate(available);
+		forEachSampleRow(data, width, height, channels, bitsPerComponent, work, (samples, firstSample) => {
+			const count = Math.min(samples.length, available - firstSample);
+			for (let i = 0; i < count; i++) out[firstSample + i] = scale[samples[i]];
+		});
 		return {
 			width,
 			height,
-			channels: RGB_CHANNEL_COUNT,
+			channels,
 			data: out
 		};
 	}
-	const samples = unpackSamples(data, width, height, CMYK_COMPONENT_COUNT, bitsPerComponent);
-	const out = new Uint8Array(width * height * RGB_CHANNEL_COUNT);
-	for (let px = 0; px < width * height; px++) {
-		const rgb = cmykToRgbByte(scaleToByte(samples[px * CMYK_COMPONENT_COUNT] ?? 0, maxValue, inverted) / MAX_BYTE_VALUE, scaleToByte(samples[px * CMYK_COMPONENT_COUNT + 1] ?? 0, maxValue, inverted) / MAX_BYTE_VALUE, scaleToByte(samples[px * CMYK_COMPONENT_COUNT + 2] ?? 0, maxValue, inverted) / MAX_BYTE_VALUE, scaleToByte(samples[px * CMYK_COMPONENT_COUNT + 3] ?? 0, maxValue, inverted) / MAX_BYTE_VALUE);
-		out[px * RGB_CHANNEL_COUNT] = rgb.r;
-		out[px * RGB_CHANNEL_COUNT + 1] = rgb.g;
-		out[px * RGB_CHANNEL_COUNT + 2] = rgb.b;
-	}
+	const scale = scaleTable(maxValue, inverted, work);
+	const out = work.allocate(pixelCount * RGB_CHANNEL_COUNT);
+	forEachSampleRow(data, width, height, CMYK_COMPONENT_COUNT, bitsPerComponent, work, (samples, firstSample) => {
+		const firstPixel = firstSample / CMYK_COMPONENT_COUNT;
+		for (let px = 0; px < width; px++) {
+			const base = px * CMYK_COMPONENT_COUNT;
+			const rgb = cmykToRgbByte(scale[samples[base]] / MAX_BYTE_VALUE, scale[samples[base + 1]] / MAX_BYTE_VALUE, scale[samples[base + 2]] / MAX_BYTE_VALUE, scale[samples[base + 3]] / MAX_BYTE_VALUE);
+			const outBase = (firstPixel + px) * RGB_CHANNEL_COUNT;
+			out[outBase] = rgb.r;
+			out[outBase + 1] = rgb.g;
+			out[outBase + 2] = rgb.b;
+		}
+	});
 	return {
 		width,
 		height,
@@ -327,7 +384,7 @@ function readImageXObject(dict, raw, resolver, sink) {
 	}
 	const decodeArr = require_objects.asArray(require_objects.dictGet(dict, "Decode"));
 	const inverted = decodeArr !== void 0 && require_objects.asNumber(decodeArr[0]) === 1 && require_objects.asNumber(decodeArr[1]) === 0;
-	const rawImage = buildRawImage(decoded.bytes, width, height, bitsPerComponent, colorSpace, inverted);
+	const rawImage = decodeImageSamples(decoded.bytes, width, height, bitsPerComponent, colorSpace, inverted);
 	const alpha = readSoftMaskAlpha(dict, width, height, resolver, sink);
 	const withAlpha = alpha !== void 0 ? {
 		...rawImage,
@@ -342,7 +399,9 @@ function readImageXObject(dict, raw, resolver, sink) {
 	};
 }
 //#endregion
+exports.SampleDecodeWork = SampleDecodeWork;
 exports.cmykToRgbByte = cmykToRgbByte;
+exports.decodeImageSamples = decodeImageSamples;
 exports.readImageXObject = readImageXObject;
 exports.sampleFromPalette = sampleFromPalette;
 exports.scaleToByte = scaleToByte;

package/dist/images-read.d.cts

@@ -1,6 +1,7 @@
 import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { n as PdfDict } from "./objects-e2RS3-yT.cjs";
 import { PdfObjectResolver } from "./interpret-types.cjs";
+import { RawImage } from "byte-codec";
 //#region src/images-read.d.ts
 interface ExtractedPdfImage {
   readonly format: "png" | "jpeg";
@@ -27,6 +28,20 @@ type ResolvedColorSpace = {
   readonly kind: "unsupported";
   readonly name: string;
 };
+/**
+ * Allocates the buffers one `decodeImageSamples` call needs and counts their bytes, so a test can bound the decode's memory in bytes rather than time.
+ */
+declare class SampleDecodeWork {
+  #private;
+  /** Bytes of every buffer the decode allocated: its raster, its one reusable row and its lookup table. Each lives until the decode returns, so this is also the decode's peak; a view onto the stream it was given costs nothing. */
+  get bytesAllocated(): number;
+  /**
+   * A zero-filled buffer of `length` bytes, counted.
+   * @param length - Its length in bytes.
+   * @returns The buffer.
+   */
+  allocate(length: number): Uint8Array<ArrayBuffer>;
+}
 declare function scaleToByte(value: number, maxValue: number, inverted: boolean): number;
 declare function cmykToRgbByte(c: number, m: number, y: number, k: number): {
   r: number;
@@ -38,6 +53,20 @@ declare function sampleFromPalette(base: ResolvedColorSpace, lookup: Uint8Array<
   g: number;
   b: number;
 };
+/**
+ * Decodes an image's samples into the 8-bit raster `encodePng` takes, holding at most the raster itself, one row of samples and a lookup table of at most 256 entries beside the stream; nothing is allocated per sample.
+ * @param data - The image's decoded stream: rows of `width` pixels padded to a whole byte, sub-byte samples packed most significant bit first.
+ * @param width - Pixels per row.
+ * @param height - Rows.
+ * @param bitsPerComponent - 1, 2, 4 or 8.
+ * @param colorSpace - The resolved colour space; never `unsupported`.
+ * @param inverted - Whether `/Decode` is `[1 0]`, which a gray, RGB or CMYK sample is inverted by and an indexed one ignores.
+ * @param work - Counts the bytes allocated; see SampleDecodeWork.
+ * @returns A gray or RGB raster. An 8-bit gray or RGB image with no `/Decode` inversion is already that raster, so its data is a view onto `data` and costs no allocation. An 8-bit stream shorter than the image yields a gray, RGB or indexed raster holding only the pixels the stream covers, and a CMYK one in which each missing sample reads as 0.
+ */
+declare function decodeImageSamples(data: Uint8Array<ArrayBuffer>, width: number, height: number, bitsPerComponent: number, colorSpace: Exclude<ResolvedColorSpace, {
+  readonly kind: "unsupported";
+}>, inverted: boolean, work?: SampleDecodeWork): RawImage;
 declare function readImageXObject(dict: PdfDict, raw: Uint8Array<ArrayBuffer>, resolver: Readonly<PdfObjectResolver>, sink: PdfDiagnosticSink): ExtractedPdfImage | undefined;
 //#endregion
-export { ExtractedPdfImage, cmykToRgbByte, readImageXObject, sampleFromPalette, scaleToByte };
+export { ExtractedPdfImage, ResolvedColorSpace, SampleDecodeWork, cmykToRgbByte, decodeImageSamples, readImageXObject, sampleFromPalette, scaleToByte };

package/dist/images-read.d.ts

@@ -1,6 +1,7 @@
 import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { n as PdfDict } from "./objects-e2RS3-yT.js";
 import { PdfObjectResolver } from "./interpret-types.js";
+import { RawImage } from "byte-codec";
 //#region src/images-read.d.ts
 interface ExtractedPdfImage {
   readonly format: "png" | "jpeg";
@@ -27,6 +28,20 @@ type ResolvedColorSpace = {
   readonly kind: "unsupported";
   readonly name: string;
 };
+/**
+ * Allocates the buffers one `decodeImageSamples` call needs and counts their bytes, so a test can bound the decode's memory in bytes rather than time.
+ */
+declare class SampleDecodeWork {
+  #private;
+  /** Bytes of every buffer the decode allocated: its raster, its one reusable row and its lookup table. Each lives until the decode returns, so this is also the decode's peak; a view onto the stream it was given costs nothing. */
+  get bytesAllocated(): number;
+  /**
+   * A zero-filled buffer of `length` bytes, counted.
+   * @param length - Its length in bytes.
+   * @returns The buffer.
+   */
+  allocate(length: number): Uint8Array<ArrayBuffer>;
+}
 declare function scaleToByte(value: number, maxValue: number, inverted: boolean): number;
 declare function cmykToRgbByte(c: number, m: number, y: number, k: number): {
   r: number;
@@ -38,6 +53,20 @@ declare function sampleFromPalette(base: ResolvedColorSpace, lookup: Uint8Array<
   g: number;
   b: number;
 };
+/**
+ * Decodes an image's samples into the 8-bit raster `encodePng` takes, holding at most the raster itself, one row of samples and a lookup table of at most 256 entries beside the stream; nothing is allocated per sample.
+ * @param data - The image's decoded stream: rows of `width` pixels padded to a whole byte, sub-byte samples packed most significant bit first.
+ * @param width - Pixels per row.
+ * @param height - Rows.
+ * @param bitsPerComponent - 1, 2, 4 or 8.
+ * @param colorSpace - The resolved colour space; never `unsupported`.
+ * @param inverted - Whether `/Decode` is `[1 0]`, which a gray, RGB or CMYK sample is inverted by and an indexed one ignores.
+ * @param work - Counts the bytes allocated; see SampleDecodeWork.
+ * @returns A gray or RGB raster. An 8-bit gray or RGB image with no `/Decode` inversion is already that raster, so its data is a view onto `data` and costs no allocation. An 8-bit stream shorter than the image yields a gray, RGB or indexed raster holding only the pixels the stream covers, and a CMYK one in which each missing sample reads as 0.
+ */
+declare function decodeImageSamples(data: Uint8Array<ArrayBuffer>, width: number, height: number, bitsPerComponent: number, colorSpace: Exclude<ResolvedColorSpace, {
+  readonly kind: "unsupported";
+}>, inverted: boolean, work?: SampleDecodeWork): RawImage;
 declare function readImageXObject(dict: PdfDict, raw: Uint8Array<ArrayBuffer>, resolver: Readonly<PdfObjectResolver>, sink: PdfDiagnosticSink): ExtractedPdfImage | undefined;
 //#endregion
-export { ExtractedPdfImage, cmykToRgbByte, readImageXObject, sampleFromPalette, scaleToByte };
+export { ExtractedPdfImage, ResolvedColorSpace, SampleDecodeWork, cmykToRgbByte, decodeImageSamples, readImageXObject, sampleFromPalette, scaleToByte };

package/dist/images-read.js

@@ -57,27 +57,51 @@ function resolveColorSpace(csObj, resolver, sink) {
 		name: family ?? "(unrecognised array colour space)"
 	};
 }
-function unpackSamples(data, width, height, componentsPerPixel, bitsPerComponent) {
-	if (bitsPerComponent === BITS_PER_BYTE) return Array.from(data.subarray(0, width * height * componentsPerPixel));
+/**
+* Allocates the buffers one `decodeImageSamples` call needs and counts their bytes, so a test can bound the decode's memory in bytes rather than time.
+*/
+var SampleDecodeWork = class {
+	#bytesAllocated = 0;
+	/** Bytes of every buffer the decode allocated: its raster, its one reusable row and its lookup table. Each lives until the decode returns, so this is also the decode's peak; a view onto the stream it was given costs nothing. */
+	get bytesAllocated() {
+		return this.#bytesAllocated;
+	}
+	/**
+	* A zero-filled buffer of `length` bytes, counted.
+	* @param length - Its length in bytes.
+	* @returns The buffer.
+	*/
+	allocate(length) {
+		this.#bytesAllocated += length;
+		return new Uint8Array(length);
+	}
+};
+function readSampleRow(data, row, bitsPerComponent, target) {
+	const samplesPerRow = target.length;
+	if (bitsPerComponent === BITS_PER_BYTE) {
+		const rowStart = row * samplesPerRow;
+		for (let s = 0; s < samplesPerRow; s++) target[s] = data[rowStart + s] ?? 0;
+		return;
+	}
+	const rowStart = row * Math.ceil(samplesPerRow * bitsPerComponent / BITS_PER_BYTE);
+	const sampleMask = (1 << bitsPerComponent) - 1;
+	for (let s = 0; s < samplesPerRow; s++) {
+		const bitPos = s * bitsPerComponent;
+		const byte = data[rowStart + Math.floor(bitPos / BITS_PER_BYTE)] ?? 0;
+		const shift = BITS_PER_BYTE - bitsPerComponent - bitPos % BITS_PER_BYTE;
+		target[s] = byte >> shift & sampleMask;
+	}
+}
+function forEachSampleRow(data, width, height, componentsPerPixel, bitsPerComponent, work, visit) {
 	const samplesPerRow = width * componentsPerPixel;
-	const bytesPerRow = Math.ceil(samplesPerRow * bitsPerComponent / BITS_PER_BYTE);
-	const out = [];
+	const rowSamples = work.allocate(samplesPerRow);
 	for (let row = 0; row < height; row++) {
-		const rowStart = row * bytesPerRow;
-		let bitPos = 0;
-		for (let s = 0; s < samplesPerRow; s++) {
-			let value = 0;
-			for (let b = 0; b < bitsPerComponent; b++) {
-				const byteIndex = rowStart + Math.floor(bitPos / BITS_PER_BYTE);
-				const bitIndex = 7 - bitPos % BITS_PER_BYTE;
-				const bit = (data[byteIndex] ?? 0) >> bitIndex & 1;
-				value = value << 1 | bit;
-				bitPos++;
-			}
-			out.push(value);
-		}
+		readSampleRow(data, row, bitsPerComponent, rowSamples);
+		visit(rowSamples, row * samplesPerRow);
 	}
-	return out;
+}
+function availableSampleCount(data, sampleCount, bitsPerComponent) {
+	return bitsPerComponent === BITS_PER_BYTE ? Math.min(data.length, sampleCount) : sampleCount;
 }
 function scaleToByte(value, maxValue, inverted) {
 	const v = inverted ? maxValue - value : value;
@@ -106,56 +130,89 @@ function sampleFromPalette(base, lookup, offset) {
 		b: lookup[offset + 2] ?? 0
 	};
 }
-function buildRawImage(data, width, height, bitsPerComponent, colorSpace, inverted) {
+function scaleTable(maxValue, inverted, work) {
+	const table = work.allocate(maxValue + 1);
+	for (let value = 0; value <= maxValue; value++) table[value] = scaleToByte(value, maxValue, inverted);
+	return table;
+}
+/**
+* Decodes an image's samples into the 8-bit raster `encodePng` takes, holding at most the raster itself, one row of samples and a lookup table of at most 256 entries beside the stream; nothing is allocated per sample.
+* @param data - The image's decoded stream: rows of `width` pixels padded to a whole byte, sub-byte samples packed most significant bit first.
+* @param width - Pixels per row.
+* @param height - Rows.
+* @param bitsPerComponent - 1, 2, 4 or 8.
+* @param colorSpace - The resolved colour space; never `unsupported`.
+* @param inverted - Whether `/Decode` is `[1 0]`, which a gray, RGB or CMYK sample is inverted by and an indexed one ignores.
+* @param work - Counts the bytes allocated; see SampleDecodeWork.
+* @returns A gray or RGB raster. An 8-bit gray or RGB image with no `/Decode` inversion is already that raster, so its data is a view onto `data` and costs no allocation. An 8-bit stream shorter than the image yields a gray, RGB or indexed raster holding only the pixels the stream covers, and a CMYK one in which each missing sample reads as 0.
+*/
+function decodeImageSamples(data, width, height, bitsPerComponent, colorSpace, inverted, work = new SampleDecodeWork()) {
 	const maxValue = (1 << bitsPerComponent) - 1;
+	const pixelCount = width * height;
 	if (colorSpace.kind === "indexed") {
-		const indices = unpackSamples(data, width, height, 1, bitsPerComponent);
+		const channels = colorSpace.base.kind === "gray" ? 1 : RGB_CHANNEL_COUNT;
 		const baseComponents = componentsOf(colorSpace.base);
-		const out = new Uint8Array(width * height * (colorSpace.base.kind === "gray" ? 1 : RGB_CHANNEL_COUNT));
-		let outIdx = 0;
-		for (const index of indices) {
+		const palette = work.allocate((maxValue + 1) * channels);
+		for (let index = 0; index <= maxValue; index++) {
 			const rgb = sampleFromPalette(colorSpace.base, colorSpace.lookup, index * baseComponents);
-			if (colorSpace.base.kind === "gray") out[outIdx++] = rgb.r;
-			else {
-				out[outIdx++] = rgb.r;
-				out[outIdx++] = rgb.g;
-				out[outIdx++] = rgb.b;
+			palette[index * channels] = rgb.r;
+			if (channels === RGB_CHANNEL_COUNT) {
+				palette[index * channels + 1] = rgb.g;
+				palette[index * channels + 2] = rgb.b;
 			}
 		}
+		const out = work.allocate(pixelCount * channels);
+		const indexed = availableSampleCount(data, pixelCount, bitsPerComponent);
+		forEachSampleRow(data, width, height, 1, bitsPerComponent, work, (indices, firstPixel) => {
+			const count = Math.min(indices.length, indexed - firstPixel);
+			for (let i = 0; i < count; i++) {
+				const entry = indices[i] * channels;
+				const at = (firstPixel + i) * channels;
+				for (let channel = 0; channel < channels; channel++) out[at + channel] = palette[entry + channel];
+			}
+		});
 		return {
 			width,
 			height,
-			channels: colorSpace.base.kind === "gray" ? 1 : RGB_CHANNEL_COUNT,
+			channels,
 			data: out
 		};
 	}
-	if (colorSpace.kind === "gray") {
-		const samples = unpackSamples(data, width, height, 1, bitsPerComponent);
-		return {
+	if (colorSpace.kind === "gray" || colorSpace.kind === "rgb") {
+		const channels = colorSpace.kind === "gray" ? 1 : RGB_CHANNEL_COUNT;
+		const available = availableSampleCount(data, pixelCount * channels, bitsPerComponent);
+		if (bitsPerComponent === BITS_PER_BYTE && !inverted) return {
 			width,
 			height,
-			channels: 1,
-			data: Uint8Array.from(samples, (v) => scaleToByte(v, maxValue, inverted))
+			channels,
+			data: data.subarray(0, available)
 		};
-	}
-	if (colorSpace.kind === "rgb") {
-		const samples = unpackSamples(data, width, height, RGB_CHANNEL_COUNT, bitsPerComponent);
-		const out = Uint8Array.from(samples, (v) => scaleToByte(v, maxValue, inverted));
+		const scale = scaleTable(maxValue, inverted, work);
+		const out = work.allocate(available);
+		forEachSampleRow(data, width, height, channels, bitsPerComponent, work, (samples, firstSample) => {
+			const count = Math.min(samples.length, available - firstSample);
+			for (let i = 0; i < count; i++) out[firstSample + i] = scale[samples[i]];
+		});
 		return {
 			width,
 			height,
-			channels: RGB_CHANNEL_COUNT,
+			channels,
 			data: out
 		};
 	}
-	const samples = unpackSamples(data, width, height, CMYK_COMPONENT_COUNT, bitsPerComponent);
-	const out = new Uint8Array(width * height * RGB_CHANNEL_COUNT);
-	for (let px = 0; px < width * height; px++) {
-		const rgb = cmykToRgbByte(scaleToByte(samples[px * CMYK_COMPONENT_COUNT] ?? 0, maxValue, inverted) / MAX_BYTE_VALUE, scaleToByte(samples[px * CMYK_COMPONENT_COUNT + 1] ?? 0, maxValue, inverted) / MAX_BYTE_VALUE, scaleToByte(samples[px * CMYK_COMPONENT_COUNT + 2] ?? 0, maxValue, inverted) / MAX_BYTE_VALUE, scaleToByte(samples[px * CMYK_COMPONENT_COUNT + 3] ?? 0, maxValue, inverted) / MAX_BYTE_VALUE);
-		out[px * RGB_CHANNEL_COUNT] = rgb.r;
-		out[px * RGB_CHANNEL_COUNT + 1] = rgb.g;
-		out[px * RGB_CHANNEL_COUNT + 2] = rgb.b;
-	}
+	const scale = scaleTable(maxValue, inverted, work);
+	const out = work.allocate(pixelCount * RGB_CHANNEL_COUNT);
+	forEachSampleRow(data, width, height, CMYK_COMPONENT_COUNT, bitsPerComponent, work, (samples, firstSample) => {
+		const firstPixel = firstSample / CMYK_COMPONENT_COUNT;
+		for (let px = 0; px < width; px++) {
+			const base = px * CMYK_COMPONENT_COUNT;
+			const rgb = cmykToRgbByte(scale[samples[base]] / MAX_BYTE_VALUE, scale[samples[base + 1]] / MAX_BYTE_VALUE, scale[samples[base + 2]] / MAX_BYTE_VALUE, scale[samples[base + 3]] / MAX_BYTE_VALUE);
+			const outBase = (firstPixel + px) * RGB_CHANNEL_COUNT;
+			out[outBase] = rgb.r;
+			out[outBase + 1] = rgb.g;
+			out[outBase + 2] = rgb.b;
+		}
+	});
 	return {
 		width,
 		height,
@@ -326,7 +383,7 @@ function readImageXObject(dict, raw, resolver, sink) {
 	}
 	const decodeArr = asArray(dictGet(dict, "Decode"));
 	const inverted = decodeArr !== void 0 && asNumber(decodeArr[0]) === 1 && asNumber(decodeArr[1]) === 0;
-	const rawImage = buildRawImage(decoded.bytes, width, height, bitsPerComponent, colorSpace, inverted);
+	const rawImage = decodeImageSamples(decoded.bytes, width, height, bitsPerComponent, colorSpace, inverted);
 	const alpha = readSoftMaskAlpha(dict, width, height, resolver, sink);
 	const withAlpha = alpha !== void 0 ? {
 		...rawImage,
@@ -341,4 +398,4 @@ function readImageXObject(dict, raw, resolver, sink) {
 	};
 }
 //#endregion
-export { cmykToRgbByte, readImageXObject, sampleFromPalette, scaleToByte };
+export { SampleDecodeWork, cmykToRgbByte, decodeImageSamples, readImageXObject, sampleFromPalette, scaleToByte };

package/dist/layout.cjs

@@ -270,7 +270,7 @@ const LayoutStructureElementSchema = zod.z.lazy(() => zod.z.object({
 	children: zod.z.array(LayoutStructureElementSchema)
 }));
 /**
-* The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers` and `structure` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
+* The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers`, `structure` and `images` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
 */
 const LayoutDocumentSurfaceSchema = zod.z.enum([
 	"outline",
@@ -278,7 +278,8 @@ const LayoutDocumentSurfaceSchema = zod.z.enum([
 	"form",
 	"layers",
 	"structure",
-	"residue"
+	"residue",
+	"images"
 ]);
 const LayoutDocumentSchema = zod.z.object({
 	formatVersion: zod.z.literal(1),

package/dist/layout.d.cts

@@ -785,10 +785,11 @@ interface LayoutStructureElement {
   readonly children: readonly LayoutStructureElement[];
 }
 /**
- * The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers` and `structure` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
+ * The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers`, `structure` and `images` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
  */
 declare const LayoutDocumentSurfaceSchema: z.ZodEnum<{
   structure: "structure";
+  images: "images";
   destinations: "destinations";
   outline: "outline";
   layers: "layers";
@@ -1115,6 +1116,7 @@ declare const LayoutDocumentSchema: z.ZodObject<{
   }, z.core.$strict>>>;
   skippedSurfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
     structure: "structure";
+    images: "images";
     destinations: "destinations";
     outline: "outline";
     layers: "layers";

package/dist/layout.d.ts

@@ -785,10 +785,11 @@ interface LayoutStructureElement {
   readonly children: readonly LayoutStructureElement[];
 }
 /**
- * The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers` and `structure` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
+ * The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers`, `structure` and `images` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
  */
 declare const LayoutDocumentSurfaceSchema: z.ZodEnum<{
   structure: "structure";
+  images: "images";
   destinations: "destinations";
   outline: "outline";
   layers: "layers";
@@ -1115,6 +1116,7 @@ declare const LayoutDocumentSchema: z.ZodObject<{
   }, z.core.$strict>>>;
   skippedSurfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
     structure: "structure";
+    images: "images";
     destinations: "destinations";
     outline: "outline";
     layers: "layers";

package/dist/layout.js

@@ -269,7 +269,7 @@ const LayoutStructureElementSchema = z.lazy(() => z.object({
 	children: z.array(LayoutStructureElementSchema)
 }));
 /**
-* The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers` and `structure` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
+* The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers`, `structure` and `images` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
 */
 const LayoutDocumentSurfaceSchema = z.enum([
 	"outline",
@@ -277,7 +277,8 @@ const LayoutDocumentSurfaceSchema = z.enum([
 	"form",
 	"layers",
 	"structure",
-	"residue"
+	"residue",
+	"images"
 ]);
 const LayoutDocumentSchema = z.object({
 	formatVersion: z.literal(1),

package/dist/read-convert.cjs

@@ -7,14 +7,25 @@ const require_bytes_crc32 = require("./bytes/crc32.cjs");
 const require_images_read = require("./images-read.cjs");
 let byte_codec = require("byte-codec");
 //#region src/read-convert.ts
-function convertExtractedItem(item, pageMatrix, fontResolver, images, imageIdCache, resolver, sink) {
+/**
+* Converts one interpreted item to a layout item in page space.
+* @param item - The item the content-stream interpreter extracted.
+* @param pageMatrix - Maps the interpreter's user space into the page's output space.
+* @param fontResolver - Resolves a text item's font.
+* @param imageRegistry - Where images are decoded into, or undefined for a read that skips images, which converts no image item and decodes no image stream.
+* @param resolver - Resolves indirect objects an image names.
+* @param sink - Receives diagnostics.
+* @returns The layout item, or undefined for an item that converts to none: an image that could not be decoded, or any image when `imageRegistry` is undefined.
+*/
+function convertExtractedItem(item, pageMatrix, fontResolver, imageRegistry, resolver, sink) {
 	if (item.kind === "text") return convertText(item, pageMatrix, fontResolver);
 	if (item.kind === "rect") return convertRect(item, pageMatrix);
 	if (item.kind === "ellipse") return convertEllipse(item, pageMatrix);
 	if (item.kind === "line") return convertLine(item, pageMatrix);
 	if (item.kind === "path") return convertPath(item, pageMatrix);
-	if (item.kind === "image") return convertImage(item, pageMatrix, images, imageIdCache, resolver, sink);
-	return convertInlineImage(item, pageMatrix, images, resolver, sink);
+	if (imageRegistry === void 0) return;
+	if (item.kind === "image") return convertImage(item, pageMatrix, imageRegistry.images, imageRegistry.imageIdCache, resolver, sink);
+	return convertInlineImage(item, pageMatrix, imageRegistry.images, resolver, sink);
 }
 function convertText(item, pageMatrix, fontResolver) {
 	const font = fontResolver.resolve(item.fontResourceName, item.resources);

package/dist/read-convert.d.cts

@@ -8,7 +8,24 @@ import { DestinationRegistry } from "./navigation.cjs";
 import { ExtractedPdfImage } from "./images-read.cjs";
 import { Color } from "document-schema.js";
 //#region src/read-convert.d.ts
-declare function convertExtractedItem(item: ExtractedItem, pageMatrix: Matrix, fontResolver: FontResolverService, images: Record<string, LayoutImageAsset>, imageIdCache: Map<PdfDict, string | null>, resolver: Readonly<PdfObjectResolver>, sink: PdfDiagnosticSink): LayoutItem | undefined;
+/**
+ * Where a read's images go: the registry each decoded image is stored in once, and the id each image XObject dictionary already decoded to (null for one that could not be).
+ */
+interface ImageRegistry {
+  readonly images: Record<string, LayoutImageAsset>;
+  readonly imageIdCache: Map<PdfDict, string | null>;
+}
+/**
+ * Converts one interpreted item to a layout item in page space.
+ * @param item - The item the content-stream interpreter extracted.
+ * @param pageMatrix - Maps the interpreter's user space into the page's output space.
+ * @param fontResolver - Resolves a text item's font.
+ * @param imageRegistry - Where images are decoded into, or undefined for a read that skips images, which converts no image item and decodes no image stream.
+ * @param resolver - Resolves indirect objects an image names.
+ * @param sink - Receives diagnostics.
+ * @returns The layout item, or undefined for an item that converts to none: an image that could not be decoded, or any image when `imageRegistry` is undefined.
+ */
+declare function convertExtractedItem(item: ExtractedItem, pageMatrix: Matrix, fontResolver: FontResolverService, imageRegistry: ImageRegistry | undefined, resolver: Readonly<PdfObjectResolver>, sink: PdfDiagnosticSink): LayoutItem | undefined;
 declare function convertText(item: ExtractedTextRun, pageMatrix: Matrix, fontResolver: FontResolverService): LayoutText | undefined;
 declare function paintFields(paint: ExtractedPaint): {
   fill?: Color;
@@ -55,4 +72,4 @@ declare function convertImage(item: ExtractedImage, pageMatrix: Matrix, images:
 declare function readLinkAnnotations(page: PdfDict, pageMatrix: Matrix, resolver: Readonly<PdfObjectResolver>, destinationRegistry: DestinationRegistry): (LayoutLink | LayoutInternalLink)[];
 declare function readPageNotes(page: PdfDict, resolver: Readonly<PdfObjectResolver>): string | undefined;
 //#endregion
-export { convertEllipse, convertExtractedItem, convertImage, convertLine, convertPath, convertRect, convertText, imagePlacementFrom, paintFields, readLinkAnnotations, readPageNotes, registerExtractedImage, resolveCachedImageId, transformBox, transformSubpath };
+export { ImageRegistry, convertEllipse, convertExtractedItem, convertImage, convertLine, convertPath, convertRect, convertText, imagePlacementFrom, paintFields, readLinkAnnotations, readPageNotes, registerExtractedImage, resolveCachedImageId, transformBox, transformSubpath };

package/dist/read-convert.d.ts

@@ -8,7 +8,24 @@ import { DestinationRegistry } from "./navigation.js";
 import { ExtractedPdfImage } from "./images-read.js";
 import { Color } from "document-schema.js";
 //#region src/read-convert.d.ts
-declare function convertExtractedItem(item: ExtractedItem, pageMatrix: Matrix, fontResolver: FontResolverService, images: Record<string, LayoutImageAsset>, imageIdCache: Map<PdfDict, string | null>, resolver: Readonly<PdfObjectResolver>, sink: PdfDiagnosticSink): LayoutItem | undefined;
+/**
+ * Where a read's images go: the registry each decoded image is stored in once, and the id each image XObject dictionary already decoded to (null for one that could not be).
+ */
+interface ImageRegistry {
+  readonly images: Record<string, LayoutImageAsset>;
+  readonly imageIdCache: Map<PdfDict, string | null>;
+}
+/**
+ * Converts one interpreted item to a layout item in page space.
+ * @param item - The item the content-stream interpreter extracted.
+ * @param pageMatrix - Maps the interpreter's user space into the page's output space.
+ * @param fontResolver - Resolves a text item's font.
+ * @param imageRegistry - Where images are decoded into, or undefined for a read that skips images, which converts no image item and decodes no image stream.
+ * @param resolver - Resolves indirect objects an image names.
+ * @param sink - Receives diagnostics.
+ * @returns The layout item, or undefined for an item that converts to none: an image that could not be decoded, or any image when `imageRegistry` is undefined.
+ */
+declare function convertExtractedItem(item: ExtractedItem, pageMatrix: Matrix, fontResolver: FontResolverService, imageRegistry: ImageRegistry | undefined, resolver: Readonly<PdfObjectResolver>, sink: PdfDiagnosticSink): LayoutItem | undefined;
 declare function convertText(item: ExtractedTextRun, pageMatrix: Matrix, fontResolver: FontResolverService): LayoutText | undefined;
 declare function paintFields(paint: ExtractedPaint): {
   fill?: Color;
@@ -55,4 +72,4 @@ declare function convertImage(item: ExtractedImage, pageMatrix: Matrix, images:
 declare function readLinkAnnotations(page: PdfDict, pageMatrix: Matrix, resolver: Readonly<PdfObjectResolver>, destinationRegistry: DestinationRegistry): (LayoutLink | LayoutInternalLink)[];
 declare function readPageNotes(page: PdfDict, resolver: Readonly<PdfObjectResolver>): string | undefined;
 //#endregion
-export { convertEllipse, convertExtractedItem, convertImage, convertLine, convertPath, convertRect, convertText, imagePlacementFrom, paintFields, readLinkAnnotations, readPageNotes, registerExtractedImage, resolveCachedImageId, transformBox, transformSubpath };
+export { ImageRegistry, convertEllipse, convertExtractedItem, convertImage, convertLine, convertPath, convertRect, convertText, imagePlacementFrom, paintFields, readLinkAnnotations, readPageNotes, registerExtractedImage, resolveCachedImageId, transformBox, transformSubpath };

package/dist/read-convert.js

@@ -6,14 +6,25 @@ import { crc32 } from "./bytes/crc32.js";
 import { readImageXObject } from "./images-read.js";
 import { bytesToBase64 } from "byte-codec";
 //#region src/read-convert.ts
-function convertExtractedItem(item, pageMatrix, fontResolver, images, imageIdCache, resolver, sink) {
+/**
+* Converts one interpreted item to a layout item in page space.
+* @param item - The item the content-stream interpreter extracted.
+* @param pageMatrix - Maps the interpreter's user space into the page's output space.
+* @param fontResolver - Resolves a text item's font.
+* @param imageRegistry - Where images are decoded into, or undefined for a read that skips images, which converts no image item and decodes no image stream.
+* @param resolver - Resolves indirect objects an image names.
+* @param sink - Receives diagnostics.
+* @returns The layout item, or undefined for an item that converts to none: an image that could not be decoded, or any image when `imageRegistry` is undefined.
+*/
+function convertExtractedItem(item, pageMatrix, fontResolver, imageRegistry, resolver, sink) {
 	if (item.kind === "text") return convertText(item, pageMatrix, fontResolver);
 	if (item.kind === "rect") return convertRect(item, pageMatrix);
 	if (item.kind === "ellipse") return convertEllipse(item, pageMatrix);
 	if (item.kind === "line") return convertLine(item, pageMatrix);
 	if (item.kind === "path") return convertPath(item, pageMatrix);
-	if (item.kind === "image") return convertImage(item, pageMatrix, images, imageIdCache, resolver, sink);
-	return convertInlineImage(item, pageMatrix, images, resolver, sink);
+	if (imageRegistry === void 0) return;
+	if (item.kind === "image") return convertImage(item, pageMatrix, imageRegistry.images, imageRegistry.imageIdCache, resolver, sink);
+	return convertInlineImage(item, pageMatrix, imageRegistry.images, resolver, sink);
 }
 function convertText(item, pageMatrix, fontResolver) {
 	const font = fontResolver.resolve(item.fontResourceName, item.resources);

package/dist/read.cjs

@@ -59,11 +59,14 @@ function readPdf(bytes, options) {
 		sink
 	});
 	const images = {};
-	const imageIdCache = /* @__PURE__ */ new Map();
 	const pageDicts = doc.pages();
 	const selection = options?.pages === void 0 ? void 0 : resolvePageSelection(options.pages, pageDicts.length);
 	const skippedSurfaces = skippedSurfacesOf(options?.surfaces);
 	const reads = (surface) => !skippedSurfaces.includes(surface);
+	const imageRegistry = reads("images") ? {
+		images,
+		imageIdCache: /* @__PURE__ */ new Map()
+	} : void 0;
 	const destinationRegistry = reads("destinations") ? require_navigation.createDestinationRegistry(doc.catalog, doc, (obj) => doc.pageIndex(obj), sink) : UNREAD_DESTINATION_REGISTRY;
 	const outline = reads("outline") ? require_navigation.readOutline(doc.catalog, destinationRegistry, doc, sink) : void 0;
 	const attachments = selection === void 0 ? require_attachments.readAttachments(doc.catalog, pageDicts, doc, sink) : [];
@@ -75,7 +78,7 @@ function readPdf(bytes, options) {
 	const pages = pageDicts.flatMap((pageDict, index) => {
 		if (selection !== void 0 && !selection.has(index)) return [];
 		require_util_abort.throwIfAborted(signal);
-		const read = readPage(index, pageDict, doc, fontResolver, images, imageIdCache, destinationRegistry, optionalContent?.layerNameOf ?? noLayerName, structure?.ownerOf ?? noStructureOwner, sink);
+		const read = readPage(index, pageDict, doc, fontResolver, imageRegistry, destinationRegistry, optionalContent?.layerNameOf ?? noLayerName, structure?.ownerOf ?? noStructureOwner, sink);
 		if (read.boxRow !== void 0) pageBoxRows.push(read.boxRow);
 		return [selection === void 0 ? read.page : {
 			...read.page,
@@ -309,7 +312,7 @@ function pageBoxResidueEntry(pageIndex, page, mediaBox, cropBox) {
 	for (const [key, value] of declaredBoxes) if (value !== void 0) entries[key] = value;
 	return require_objects.pdfDict(entries);
 }
-function readPage(pageIndex, page, resolver, fontResolver, images, imageIdCache, destinationRegistry, layerNameOf, structureOwnerOf, sink) {
+function readPage(pageIndex, page, resolver, fontResolver, imageRegistry, destinationRegistry, layerNameOf, structureOwnerOf, sink) {
 	const resources = resolver.resolveDict(require_objects.dictGet(page, "Resources"));
 	const mediaBox = readMediaBox(page);
 	let cropBox = readDeclaredPageBox(page, "CropBox") ?? mediaBox;
@@ -338,7 +341,7 @@ function readPage(pageIndex, page, resolver, fontResolver, images, imageIdCache,
 			layerNameOf
 		});
 		for (const item of extracted) {
-			const converted = require_read_convert.convertExtractedItem(item, pageMatrix, fontResolver, images, imageIdCache, resolver, sink);
+			const converted = require_read_convert.convertExtractedItem(item, pageMatrix, fontResolver, imageRegistry, resolver, sink);
 			if (converted === void 0 || !itemIntersectsVisibleRegion(converted, widthPt, heightPt)) continue;
 			const owner = item.mcid === void 0 ? void 0 : structureOwnerOf(pageIndex, item.mcid);
 			items.push(owner === void 0 ? converted : withStructure(converted, owner));

package/dist/read.d.cts

@@ -18,7 +18,7 @@ interface ReadPdfOptions {
   /**
    * Which document-level surfaces to read. Each is read unless its entry is `false`, so omitting the setting, or an entry, reads it as before. Independent of `pages`: it applies to a full read and a page-selected read alike.
    *
-   * A surface turned off is never parsed (its part of the catalog is not walked, so a malformed outline, form, layer list or structure tree reports no diagnostic) and its field is absent from the result whatever the file holds; the result lists it in `skippedSurfaces`, which is how a caller tells "not read" from "none". What each one covers, and what page items lose without it:
+   * A surface turned off is never parsed (its part of the catalog is not walked, so a malformed outline, form, layer list or structure tree reports no diagnostic, and no image a page draws is decoded or diagnosed) and its field is absent from the result whatever the file holds (`images` is left empty instead); the result lists it in `skippedSurfaces`, which is how a caller tells "not read" from "none". What each one covers, and what page items lose without it:
    *
    * - `outline`: the `/Outlines` bookmark tree (`outline`). Page items do not depend on it, except through minted names: a destination stated as a direct array is named with the first unused `destN` in the order the reader meets it, and the outline is read before any page, so an outline entry's direct destination takes a lower number than any link's. Without the outline, the names minted for page links' direct destinations are renumbered, and `destinations` loses the entries only the outline minted; each link still resolves to the same target.
    * - `destinations`: the named destinations of the catalog `/Dests` dictionary and the `/Names /Dests` name tree, and the registry links and outline entries name their targets through (`destinations`). Without it nothing can name an internal target, so a link whose target is internal (a `/Dest`, or a `/GoTo` action, named or direct) is left out of its page's items, and a read outline entry carries no `destination`; a link to a URI is kept as usual.
@@ -26,6 +26,7 @@ interface ReadPdfOptions {
    * - `layers`: optional content, the `/OCProperties` groups and their default visibility (`layers`). Without it no item carries a `layer`, since an `/OC` membership resolves to no name; the items themselves are all still read, so content the default view hides is indistinguishable from visible content.
    * - `structure`: the `/StructTreeRoot` element tree and its `/ParentTree` ownership map (`structure`). Without it no item carries a `structure` owner, and the parent-tree diagnostics are not reported.
    * - `residue`: the package-level residue rows (`source`), including the per-page `page-boxes` row. Page items do not depend on it; `metadata` still reads the XMP packet it falls back to.
+   * - `images`: the image registry (`images`), which holds every image XObject and inline image a read page draws, decoded to PNG or passed through as JPEG. Without it no image's stream is decoded, `images` is an empty record (every `LayoutDocument` carries one), and each page's `image` items are left out, since they would name assets that were never read. Decoding an image costs memory in proportion to its pixels, so a read that wants only a page's text leaves this out.
    *
    * Apart from those stated losses and the renumbering a skipped outline causes, every page item is exactly what a read with the surface on produces.
    */

package/dist/read.d.ts

@@ -18,7 +18,7 @@ interface ReadPdfOptions {
   /**
    * Which document-level surfaces to read. Each is read unless its entry is `false`, so omitting the setting, or an entry, reads it as before. Independent of `pages`: it applies to a full read and a page-selected read alike.
    *
-   * A surface turned off is never parsed (its part of the catalog is not walked, so a malformed outline, form, layer list or structure tree reports no diagnostic) and its field is absent from the result whatever the file holds; the result lists it in `skippedSurfaces`, which is how a caller tells "not read" from "none". What each one covers, and what page items lose without it:
+   * A surface turned off is never parsed (its part of the catalog is not walked, so a malformed outline, form, layer list or structure tree reports no diagnostic, and no image a page draws is decoded or diagnosed) and its field is absent from the result whatever the file holds (`images` is left empty instead); the result lists it in `skippedSurfaces`, which is how a caller tells "not read" from "none". What each one covers, and what page items lose without it:
    *
    * - `outline`: the `/Outlines` bookmark tree (`outline`). Page items do not depend on it, except through minted names: a destination stated as a direct array is named with the first unused `destN` in the order the reader meets it, and the outline is read before any page, so an outline entry's direct destination takes a lower number than any link's. Without the outline, the names minted for page links' direct destinations are renumbered, and `destinations` loses the entries only the outline minted; each link still resolves to the same target.
    * - `destinations`: the named destinations of the catalog `/Dests` dictionary and the `/Names /Dests` name tree, and the registry links and outline entries name their targets through (`destinations`). Without it nothing can name an internal target, so a link whose target is internal (a `/Dest`, or a `/GoTo` action, named or direct) is left out of its page's items, and a read outline entry carries no `destination`; a link to a URI is kept as usual.
@@ -26,6 +26,7 @@ interface ReadPdfOptions {
    * - `layers`: optional content, the `/OCProperties` groups and their default visibility (`layers`). Without it no item carries a `layer`, since an `/OC` membership resolves to no name; the items themselves are all still read, so content the default view hides is indistinguishable from visible content.
    * - `structure`: the `/StructTreeRoot` element tree and its `/ParentTree` ownership map (`structure`). Without it no item carries a `structure` owner, and the parent-tree diagnostics are not reported.
    * - `residue`: the package-level residue rows (`source`), including the per-page `page-boxes` row. Page items do not depend on it; `metadata` still reads the XMP packet it falls back to.
+   * - `images`: the image registry (`images`), which holds every image XObject and inline image a read page draws, decoded to PNG or passed through as JPEG. Without it no image's stream is decoded, `images` is an empty record (every `LayoutDocument` carries one), and each page's `image` items are left out, since they would name assets that were never read. Decoding an image costs memory in proportion to its pixels, so a read that wants only a page's text leaves this out.
    *
    * Apart from those stated losses and the renumbering a skipped outline causes, every page item is exactly what a read with the surface on produces.
    */

package/dist/read.js

@@ -58,11 +58,14 @@ function readPdf(bytes, options) {
 		sink
 	});
 	const images = {};
-	const imageIdCache = /* @__PURE__ */ new Map();
 	const pageDicts = doc.pages();
 	const selection = options?.pages === void 0 ? void 0 : resolvePageSelection(options.pages, pageDicts.length);
 	const skippedSurfaces = skippedSurfacesOf(options?.surfaces);
 	const reads = (surface) => !skippedSurfaces.includes(surface);
+	const imageRegistry = reads("images") ? {
+		images,
+		imageIdCache: /* @__PURE__ */ new Map()
+	} : void 0;
 	const destinationRegistry = reads("destinations") ? createDestinationRegistry(doc.catalog, doc, (obj) => doc.pageIndex(obj), sink) : UNREAD_DESTINATION_REGISTRY;
 	const outline = reads("outline") ? readOutline(doc.catalog, destinationRegistry, doc, sink) : void 0;
 	const attachments = selection === void 0 ? readAttachments(doc.catalog, pageDicts, doc, sink) : [];
@@ -74,7 +77,7 @@ function readPdf(bytes, options) {
 	const pages = pageDicts.flatMap((pageDict, index) => {
 		if (selection !== void 0 && !selection.has(index)) return [];
 		throwIfAborted(signal);
-		const read = readPage(index, pageDict, doc, fontResolver, images, imageIdCache, destinationRegistry, optionalContent?.layerNameOf ?? noLayerName, structure?.ownerOf ?? noStructureOwner, sink);
+		const read = readPage(index, pageDict, doc, fontResolver, imageRegistry, destinationRegistry, optionalContent?.layerNameOf ?? noLayerName, structure?.ownerOf ?? noStructureOwner, sink);
 		if (read.boxRow !== void 0) pageBoxRows.push(read.boxRow);
 		return [selection === void 0 ? read.page : {
 			...read.page,
@@ -308,7 +311,7 @@ function pageBoxResidueEntry(pageIndex, page, mediaBox, cropBox) {
 	for (const [key, value] of declaredBoxes) if (value !== void 0) entries[key] = value;
 	return pdfDict(entries);
 }
-function readPage(pageIndex, page, resolver, fontResolver, images, imageIdCache, destinationRegistry, layerNameOf, structureOwnerOf, sink) {
+function readPage(pageIndex, page, resolver, fontResolver, imageRegistry, destinationRegistry, layerNameOf, structureOwnerOf, sink) {
 	const resources = resolver.resolveDict(dictGet(page, "Resources"));
 	const mediaBox = readMediaBox(page);
 	let cropBox = readDeclaredPageBox(page, "CropBox") ?? mediaBox;
@@ -337,7 +340,7 @@ function readPage(pageIndex, page, resolver, fontResolver, images, imageIdCache,
 			layerNameOf
 		});
 		for (const item of extracted) {
-			const converted = convertExtractedItem(item, pageMatrix, fontResolver, images, imageIdCache, resolver, sink);
+			const converted = convertExtractedItem(item, pageMatrix, fontResolver, imageRegistry, resolver, sink);
 			if (converted === void 0 || !itemIntersectsVisibleRegion(converted, widthPt, heightPt)) continue;
 			const owner = item.mcid === void 0 ? void 0 : structureOwnerOf(pageIndex, item.mcid);
 			items.push(owner === void 0 ? converted : withStructure(converted, owner));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-codec",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "description": "Hand-written, dependency-minimal PDF codec: parses arbitrary real-world PDFs and generates new ones, built on its own codec-owned LayoutDocument item model and Zod 4 codecs.",
   "type": "module",
   "repository": {
@@ -100,7 +100,7 @@
   "packageManager": "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
   "dependencies": {
     "byte-codec": "2.0.2",
-    "document-schema.js": "7.16.1",
+    "document-schema.js": "7.16.2",
     "fflate": "0.8.3",
     "zod": "4.4.3"
   },