pdf-codec 5.5.1 → 5.6.1

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 };