From 3d5a4c973f85d38d63ab4208410cadf0641125a8 Mon Sep 17 00:00:00 2001 From: fcbwilliams Date: Tue, 17 Nov 2026 15:16:30 +0100 Subject: [PATCH 01/11] feat(byte-codec): filter a PNG's rows from a callback, and encode without an interleaved copy encodePng built one interleaved copy of the whole image before filtering it, and the palette search allocated a full index plane before it knew a palette would fit. For a 2360x1309 picture with a soft mask that was 12 MB and 3 MB more than the encode needs, at the moment its filtered rows and deflate buffer are also live. filterScanlineRows filters rows read through a callback; encodePng now writes each row straight from its colour and alpha planes into the filter's own row buffer (a missing sample still reads as 0), and finds the palette before storing any index. The bytes are unchanged: the existing known answers still hold, and new ones recorded from the previous encoder pin a short raster with alpha, a short grey raster and a palette with alpha. Co-Authored-By: Claude Opus 5.5 --- packages/byte-codec/README.md | 2 +- .../byte-codec/src/image/png-encode.test.ts | 65 +++++++++++++++++ packages/byte-codec/src/image/png-encode.ts | 69 +++++++++++-------- .../byte-codec/src/image/png-filter.test.ts | 50 +++++++++++++- packages/byte-codec/src/image/png-filter.ts | 29 +++++++- 5 files changed, 184 insertions(+), 31 deletions(-) diff --git a/packages/byte-codec/README.md b/packages/byte-codec/README.md index bce8242516..d37d4ee383 100644 --- a/packages/byte-codec/README.md +++ b/packages/byte-codec/README.md @@ -51,7 +51,7 @@ To run a single test file, pass its path to vitest directly, e.g. `pnpm exec vit | `bytes/flate` | `deflate`, `inflate`, `inflateTolerant` (fflate-backed DEFLATE compression/decompression with a safety cap) | | `image/png-encode` | `encodePng` (raw RGB/RGBA pixels → PNG bytes; a truecolour source image whose pixels reduce to 256 or fewer distinct colours is encoded both as indexed colour, PNG colour type 3 with a PLTE and, where needed, a tRNS chunk, and as plain truecolour, and whichever comes out smaller is returned — indexed colour wins for the large flat-colour images typical of diagrams and screenshots, but the PLTE/tRNS chunk overhead can make it larger for small images, so the encoder measures rather than assumes, at the cost of a full second encode for every eligible image; throws if either `width` or `height` is not a positive integer no greater than the PNG spec's own IHDR limit, or if their product exceeds a practical per-call pixel-count ceiling, since PNG's IHDR chunk has no valid encoding for zero, negative, fractional, or non-finite dimensions and this bounds an otherwise-unbounded encode to a fixed worst case) | | `image/png-decode` | `decodePng` (PNG bytes → raw pixels, handling every PNG colour type including indexed/palette via its own PLTE/tRNS lookup), `RawImage` | -| `image/png-filter` | `filterScanlines`, `unfilterScanlines` (the five PNG scanline filters) | +| `image/png-filter` | `filterScanlines`, `unfilterScanlines` (the five PNG scanline filters), `filterScanlineRows` (`filterScanlines` reading each row from a callback, so a caller whose pixels are not laid out as PNG rows writes each row as it is filtered rather than building an interleaved copy of the whole image first; `encodePng` filters its colour and alpha planes this way) | | `image/jpeg-info` | `readJpegInfo` (JPEG header reader: dimensions, components, progressive flag — no sample decoding) | | `text/decode` | `decodeText`, `tryDecodeText`, `detectByteOrderMark`, `isProbablyText`, `UndecodableTextError`, `TEXT_DECODE_CHUNK_CODE_UNITS` (bytes → text with the character encoding worked out from the bytes; see [Text decoding](#text-decoding) below) | diff --git a/packages/byte-codec/src/image/png-encode.test.ts b/packages/byte-codec/src/image/png-encode.test.ts index 26f578537d..47f2edd200 100644 --- a/packages/byte-codec/src/image/png-encode.test.ts +++ b/packages/byte-codec/src/image/png-encode.test.ts @@ -761,3 +761,68 @@ describe("encodePng and decodePng known answers over seeded images", () => { }, ); }); + +// The edge cases the row-at-a-time truecolour encoder and the two-pass palette search must reproduce byte for byte: a raster and alpha plane shorter than the image (each missing sample reads as 0), a short grey raster, and a palette with alpha. Each SHA-256 was recorded from the encoder as it was before either change, which built one interleaved copy of the image and stored palette indices as it searched. +describe("encodePng reproduces its earlier bytes for short planes and a palette with alpha", () => { + const pixels = GOLDEN_WIDTH * GOLDEN_HEIGHT; + const fewColours = seededBytes(pixels, 7).map((value) => (value % 4) * 60); + const images: Record = { + short3a: { + width: GOLDEN_WIDTH, + height: GOLDEN_HEIGHT, + channels: 3, + data: seededBytes(pixels * 3 - 100, 8), + alpha: seededBytes(pixels - 50, 9), + }, + short1: { + width: GOLDEN_WIDTH, + height: GOLDEN_HEIGHT, + channels: 1, + data: seededBytes(pixels - 77, 10), + }, + palettedAlpha: { + width: GOLDEN_WIDTH, + height: GOLDEN_HEIGHT, + channels: 3, + data: Uint8Array.from( + { length: pixels * 3 }, + (_unused, index) => fewColours[Math.floor(index / 3)]!, + ), + alpha: fewColours.map((value) => (value === 60 ? 128 : 255)), + }, + }; + it.each([ + [ + "short3a", + "adaptive", + "0ca94aa2c9200e70112786d538ea7160bd26a3822a33165adeea7bbc6d6bfffd", + ], + [ + "short3a", + "none", + "bcb89064f49ed3f0de54cefc3ff28c35a38f748c579f9d6a206019164e5828e9", + ], + [ + "short1", + "adaptive", + "e8683d85b61ad2a5facf843805d03eb1f8c12f8c77a9d78f58c6315954e819d9", + ], + [ + "short1", + "none", + "af560fde86b7a1ddc4bd793bd91d9b4def6023f62d3db67463f14add0ee8d261", + ], + [ + "palettedAlpha", + "adaptive", + "e611d66702ba9ed26b6cb2a28ef631c8b4f1327539bc1dd56f0918dfef3453b8", + ], + [ + "palettedAlpha", + "none", + "a4218aafe1d8f832f55ec19c340664e464bdbcab3fa66dcd6fc22db4fc805603", + ], + ] as const)("%s under the %s filter", (name, filter, png) => { + expect(sha256Hex(encodePng(images[name]!, { filter }))).toBe(png); + }); +}); diff --git a/packages/byte-codec/src/image/png-encode.ts b/packages/byte-codec/src/image/png-encode.ts index 8d3f1fec12..f0cf14bac7 100644 --- a/packages/byte-codec/src/image/png-encode.ts +++ b/packages/byte-codec/src/image/png-encode.ts @@ -2,7 +2,7 @@ import { crc32 } from "../bytes/crc32"; import { deflate } from "../bytes/flate"; import { ByteWriter, concatBytes } from "../bytes/writer"; import type { RawImage } from "./png-decode"; -import { filterScanlines } from "./png-filter"; +import { filterScanlineRows, filterScanlines } from "./png-filter"; // The eight-byte PNG signature (PNG spec section 5.2): a high-bit-set byte to catch 7-bit transmission, the ASCII text "PNG", a CRLF pair to detect line-ending translation, a DOS end-of-file marker to detect ASCII-mode truncation, and a final LF to detect CR stripping. const PNG_SIG_HIGH_BIT_MARKER = 0x89; @@ -39,11 +39,12 @@ const OPAQUE_ALPHA = 255; const GREEN_SHIFT = 8; const BLUE_SHIFT = 16; const ALPHA_SHIFT = 24; +const BYTE_MASK = 0xff; // The PNG spec's IHDR width/height fields are each a 'PNG four-byte unsigned integer', a datatype the spec (section 3, Terms and definitions) itself defines as "limited to the range 0 to 2^31-1 ... in order to accommodate languages that have difficulty with unsigned four-byte values" — so 2^31 and above has no valid encoding, the same way zero, a fraction, or NaN doesn't. export const PNG_MAX_DIMENSION = 0x7fffffff; -// A ceiling on width * height, on top of PNG_MAX_DIMENSION above — the spec bounds only each dimension independently, not their product, so a pair of dimensions that individually satisfy PNG_MAX_DIMENSION (e.g. 46341 x 46341, or 65536 x 65536) can still multiply into an unboundedly large pixel count. This has no PNG-spec basis — it is a practical, finite ceiling on the per-call work this encoder is willing to do, not a guarantee that encoding at or near it stays fast: measured directly, encoding a PNG_MAX_PIXELS-sized image takes tens of seconds end to end, dominated by filterScanlines' own adaptive per-row search across all five PNG filter types and the subsequent deflate pass, not by the smaller per-pixel loops in detectPalette or writeTruecolorPng's interleave step. The point of the bound is to keep that worst case finite rather than to keep it quick, and this figure is chosen high enough to reject only genuinely extreme inputs — some real sources (an above-100-megapixel medium-format sensor, a high-DPI full-page scan) do exceed it, so this is not a claim that every legitimate photograph or scan stays under the ceiling, only that one large enough to exceed it needs downsampling before it reaches this encoder. +// A ceiling on width * height, on top of PNG_MAX_DIMENSION above — the spec bounds only each dimension independently, not their product, so a pair of dimensions that individually satisfy PNG_MAX_DIMENSION (e.g. 46341 x 46341, or 65536 x 65536) can still multiply into an unboundedly large pixel count. This has no PNG-spec basis — it is a practical, finite ceiling on the per-call work this encoder is willing to do, not a guarantee that encoding at or near it stays fast: measured directly, encoding a PNG_MAX_PIXELS-sized image takes tens of seconds end to end, dominated by filterScanlines' own adaptive per-row search across all five PNG filter types and the subsequent deflate pass, not by the smaller per-pixel loops in detectPalette or writeTruecolorPng's per-row interleave. The point of the bound is to keep that worst case finite rather than to keep it quick, and this figure is chosen high enough to reject only genuinely extreme inputs — some real sources (an above-100-megapixel medium-format sensor, a high-DPI full-page scan) do exceed it, so this is not a claim that every legitimate photograph or scan stays under the ceiling, only that one large enough to exceed it needs downsampling before it reaches this encoder. export const PNG_MAX_PIXELS = 100_000_000; // Extracted from encodePng's own guard purely so its exact boundary (a pixel count of precisely PNG_MAX_PIXELS must be accepted, one more must not) is directly, cheaply testable: exercising this comparison through encodePng itself at the real boundary means actually allocating and filtering/deflating a genuine 100-million-pixel image, which — see PNG_MAX_PIXELS' own comment on what dominates cost at this size — takes tens of seconds even in the cheapest configuration, and far longer under Stryker's per-statement coverage instrumentation (multiple minutes, repeated across every mutant in the whole package's test run). A pure, standalone predicate keeps the real guard's exact logic under test without paying that cost at all. @@ -113,32 +114,39 @@ function detectPalette(image: RawImage): PaletteEncoding | undefined { const { width, height, data, alpha } = image; const pixelCount = width * height; const colorToIndex = new Map(); - const indices = new Uint8Array(pixelCount); const paletteRgb: number[] = []; const paletteAlpha: number[] = []; - - for (let i = 0; i < pixelCount; i++) { + const colorKey = (i: number): number => { const base = i * RGB_CHANNELS; - // `?? 0` rather than `!`: mirrors what writeTruecolorPng's own behaviour already implies for a data or alpha plane shorter than width*height(*channels) — writing an out-of-range `undefined` sample into that function's Uint8Array coerces it to 0 via ToUint8(ToNumber(undefined)), so a short buffer there already degrades to a per-pixel 0, never a thrown error. Without the same default here, the same missing sample would instead feed `undefined` into the arithmetic below, producing NaN and colliding every such pixel onto one arbitrary shared palette entry regardless of its real RGB — so encodePng's choice between the indexed and truecolour candidates would silently change what a short-buffered image decodes back to. Explicitly matching the default keeps that choice purely a size optimisation, never a content one. + // `?? 0` rather than `!`: mirrors writeTruecolorPng's own behaviour for a data or alpha plane shorter than width*height(*channels), which reads each missing sample as 0, so a short buffer there degrades to a per-pixel 0, never a thrown error. Without the same default here, the same missing sample would instead feed `undefined` into the arithmetic below, producing NaN and colliding every such pixel onto one arbitrary shared palette entry regardless of its real RGB — so encodePng's choice between the indexed and truecolour candidates would silently change what a short-buffered image decodes back to. Explicitly matching the default keeps that choice purely a size optimisation, never a content one. const r = data[base] ?? 0; const g = data[base + 1] ?? 0; const b = data[base + 2] ?? 0; const a = alpha === undefined ? OPAQUE_ALPHA : (alpha[i] ?? 0); // A packed bitfield (each 0..255 sample in its own byte lane) rather than a sum of scaled terms: since r/g/b/a each occupy a disjoint, non-overlapping 8-bit lane of the 32-bit key, the packing is a bijection by construction, with no arithmetic identity between the lanes for a mutation to preserve. - const key = r | (g << GREEN_SHIFT) | (b << BLUE_SHIFT) | (a << ALPHA_SHIFT); + return r | (g << GREEN_SHIFT) | (b << BLUE_SHIFT) | (a << ALPHA_SHIFT); + }; - let index = colorToIndex.get(key); - if (index === undefined) { + // The palette is found before any index is stored: most images a caller encodes are photographs that exceed it within their first rows, and an index plane allocated up front would cost them a byte per pixel for nothing, just as the truecolour path is about to allocate its own largest buffers. + for (let i = 0; i < pixelCount; i++) { + const key = colorKey(i); + if (!colorToIndex.has(key)) { if (colorToIndex.size >= MAX_PALETTE_ENTRIES) { return undefined; } - index = colorToIndex.size; - colorToIndex.set(key, index); - paletteRgb.push(r, g, b); - paletteAlpha.push(a); + colorToIndex.set(key, colorToIndex.size); + paletteRgb.push( + key & BYTE_MASK, + (key >>> GREEN_SHIFT) & BYTE_MASK, + (key >>> BLUE_SHIFT) & BYTE_MASK, + ); + paletteAlpha.push(key >>> ALPHA_SHIFT); } - indices[i] = index; } + const indices = new Uint8Array(pixelCount); + indices.forEach((_index, i) => { + indices[i] = colorToIndex.get(colorKey(i))!; + }); const palette = Uint8Array.from(paletteRgb); if (alpha === undefined) { @@ -198,22 +206,27 @@ function writeTruecolorPng( const { width, height, channels, data, alpha } = image; const outChannels = alpha === undefined ? channels : channels + 1; const bytesPerRow = width * outChannels; - const pixelCount = width * height; - - const interleaved = new Uint8Array(pixelCount * outChannels); - // Filled through the typed array's own forEach rather than a manually bounded for loop, and rather than an index array as long as the image: `interleaved` is allocated to exactly pixelCount * outChannels elements, so each position is visited once, there is no separate loop-bound comparison whose own boundary could ever be observed through it, and encoding a large image does not first build a pixelCount-entry array. Each position holds one channel of one pixel; the extra channel past `channels`, present only with an alpha plane, is that pixel's alpha. - interleaved.forEach((_byte, index) => { - const pixel = Math.floor(index / outChannels); - const channel = index % outChannels; - interleaved[index] = - alpha !== undefined && channel === channels - ? alpha[pixel]! - : data[pixel * channels + channel]!; - }); writeIhdr(writer, width, height, colorTypeFor(image)); - const filtered = filterScanlines( - interleaved, + // Each row is written straight into the filter's own row buffer rather than first into one interleaved copy of the whole image, which for a large picture would cost as much memory again as its pixels. A pixel the raster or alpha plane is too short to hold reads as 0, as it always has. + const filtered = filterScanlineRows( + alpha === undefined + ? (y, row) => { + const samples = data.subarray(y * bytesPerRow, (y + 1) * bytesPerRow); + row.set(samples); + row.fill(0, samples.length); + } + : (y, row) => { + const firstPixel = y * width; + row.forEach((_byte, index) => { + const pixel = firstPixel + Math.floor(index / outChannels); + const channel = index % outChannels; + row[index] = + (channel === channels + ? alpha[pixel] + : data[pixel * channels + channel]) ?? 0; + }); + }, height, bytesPerRow, outChannels, diff --git a/packages/byte-codec/src/image/png-filter.test.ts b/packages/byte-codec/src/image/png-filter.test.ts index 0e03e7ba06..44f6880156 100644 --- a/packages/byte-codec/src/image/png-filter.test.ts +++ b/packages/byte-codec/src/image/png-filter.test.ts @@ -1,5 +1,9 @@ import { describe, expect, it } from "vitest"; -import { filterScanlines, unfilterScanlines } from "./png-filter"; +import { + filterScanlineRows, + filterScanlines, + unfilterScanlines, +} from "./png-filter"; // Builds an unfiltered scanline stream (no filter-type bytes) for `height` rows of `bytesPerRow` bytes each, from a flat list of already-raw bytes. function raw(bytesPerRow: number, rows: readonly (readonly number[])[]) { @@ -504,3 +508,47 @@ describe("filterScanlines and unfilterScanlines against the PNG specification's ); }); }); + +describe("filterScanlineRows", () => { + it("filters rows read through the callback exactly as filterScanlines filters the same rows held in one buffer", () => { + const bytesPerRow = 12; + const height = 9; + const pixels = Uint8Array.from( + { length: bytesPerRow * height }, + (_unused, index) => (index * 37 + (index % 5) * 11) & 0xff, + ); + for (const strategy of ["adaptive", "none"] as const) { + const fromRows = filterScanlineRows( + (y, row) => { + row.set(pixels.subarray(y * bytesPerRow, (y + 1) * bytesPerRow)); + }, + height, + bytesPerRow, + 3, + strategy, + ); + expect(Array.from(fromRows)).toEqual( + Array.from(filterScanlines(pixels, height, bytesPerRow, 3, strategy)), + ); + } + }); + + it("asks for each row once, in order, in a buffer exactly one row long", () => { + const asked: [number, number][] = []; + filterScanlineRows( + (y, row) => { + asked.push([y, row.length]); + row.fill(y); + }, + 4, + 6, + 2, + ); + expect(asked).toEqual([ + [0, 6], + [1, 6], + [2, 6], + [3, 6], + ]); + }); +}); diff --git a/packages/byte-codec/src/image/png-filter.ts b/packages/byte-codec/src/image/png-filter.ts index 91020448a7..ed3951919b 100644 --- a/packages/byte-codec/src/image/png-filter.ts +++ b/packages/byte-codec/src/image/png-filter.ts @@ -167,6 +167,33 @@ export function filterScanlines( bytesPerRow: number, bpp: number, strategy: "none" | "adaptive" = "adaptive", +): Uint8Array { + return filterScanlineRows( + (y, row) => { + row.set(raw.subarray(y * bytesPerRow, (y + 1) * bytesPerRow)); + }, + height, + bytesPerRow, + bpp, + strategy, + ); +} + +/** + * Filters pixel rows into PNG's per-scanline IDAT payload shape, as `filterScanlines` does, reading each row from a callback rather than from one buffer holding the whole image: a caller whose pixels are not already laid out as PNG rows (separate colour and alpha planes, say) writes each row as it is filtered instead of building the whole interleaved image first. + * @param readRow - Writes row `y`'s unfiltered bytes into `row` (exactly `bytesPerRow` long, holding whatever an earlier row left there, so every byte must be written). Called once per row, in order. + * @param height - Rows. + * @param bytesPerRow - Unfiltered bytes per row. + * @param bpp - Bytes per complete pixel, at least 1: the distance the Sub, Average and Paeth filters look back. + * @param strategy - As for `filterScanlines`. + * @returns The filtered rows, each prefixed by its filter-type byte. + */ +export function filterScanlineRows( + readRow: (y: number, row: Uint8Array) => void, + height: number, + bytesPerRow: number, + bpp: number, + strategy: "none" | "adaptive" = "adaptive", ): Uint8Array { const stride = bytesPerRow + 1; const out = new Uint8Array(height * stride); @@ -179,7 +206,7 @@ export function filterScanlines( strategy === "none" ? [PNG_FILTER_NONE] : ALL_FILTER_TYPES; Array.from({ length: height }).forEach((_row, y) => { - current.set(raw.subarray(y * bytesPerRow, (y + 1) * bytesPerRow), bpp); + readRow(y, current.subarray(bpp)); let bestType: PngFilterType = PNG_FILTER_NONE; let bestSum = Number.POSITIVE_INFINITY; for (const filterType of filterTypes) { From 9b3688e9a0d9b8ecc2a4a30281ad74d3b639e02f Mon Sep 17 00:00:00 2001 From: fcbwilliams Date: Tue, 17 Nov 2026 15:16:54 +0100 Subject: [PATCH 02/11] perf(pdf-codec): inflate an image's stream into a buffer of its expected size Inflating a Flate image stream grew fflate's output buffer by doubling and then copied it to its exact length, so a 9 MB raster briefly cost about 27 MB. An image dictionary states how long its samples are, so readImageXObject now passes that length to decodeStream, which inflates a final FlateDecode (through its predictor's row framing) into one buffer of that size plus a spare byte. The bytes are the same either way: a stream that does not fit (the spare byte fills), does not decode, or is expected to be longer than deflate could possibly expand its data is inflated exactly as before, so a dictionary claiming a huge image over a tiny stream never buys a huge buffer. The content interpreter also imports COLOR_BLACK from document- schema.js/color rather than the package barrel, which loaded every content and layout schema (about 7 MB of heap) for one constant. Co-Authored-By: Claude Opus 5.5 --- packages/pdf-codec/src/bytes/flate.test.ts | 48 +++++++++++++++++++ packages/pdf-codec/src/bytes/flate.ts | 42 ++++++++++++++++- packages/pdf-codec/src/filters.ts | 21 +++++++-- packages/pdf-codec/src/images-read.ts | 54 +++++++++++++++++++++- packages/pdf-codec/src/interpret.ts | 4 +- packages/pdf-codec/src/predictors.test.ts | 44 +++++++++++++++++- packages/pdf-codec/src/predictors.ts | 24 ++++++++++ 7 files changed, 229 insertions(+), 8 deletions(-) diff --git a/packages/pdf-codec/src/bytes/flate.test.ts b/packages/pdf-codec/src/bytes/flate.test.ts index ada09194ea..28ac3e2df3 100644 --- a/packages/pdf-codec/src/bytes/flate.test.ts +++ b/packages/pdf-codec/src/bytes/flate.test.ts @@ -91,3 +91,51 @@ describe("inflateTolerant", () => { expect(() => inflateTolerant(new Uint8Array([1, 2, 3]))).toThrow(); }); }); + +describe("inflateTolerant with an expected length", () => { + const compressed = deflate(sample); + const unhinted = inflateTolerant(compressed); + + it.each([ + ["exactly the output's length", sample.length], + ["longer than the output", sample.length + 500], + ["shorter than the output", sample.length - 1], + ["zero", 0], + ["not an integer", sample.length + 0.5], + ["negative", -1], + ])( + "inflates to the same bytes when the expectation is %s", + (_name, expected) => { + const hinted = inflateTolerant(compressed, expected); + expect(Array.from(hinted.bytes)).toEqual(Array.from(unhinted.bytes)); + expect(hinted.recovered).toBe(false); + }, + ); + + it("inflates into one buffer of the expected length, plus a byte that shows whether the stream ran past it", () => { + vi.mocked(unzlibSync).mockClear(); + inflateTolerant(compressed, sample.length); + expect(vi.mocked(unzlibSync)).toHaveBeenCalledTimes(1); + expect(vi.mocked(unzlibSync).mock.calls[0]?.[1]?.out?.length).toBe( + sample.length + 1, + ); + }); + + it("does not act on an expectation the data could not meet, whatever a dictionary claims", () => { + vi.mocked(unzlibSync).mockClear(); + const tiny = deflate(new Uint8Array(10)); + const result = inflateTolerant(tiny, tiny.length * 1032 + 1); + expect(Array.from(result.bytes)).toEqual(Array.from(new Uint8Array(10))); + expect( + vi.mocked(unzlibSync).mock.calls.every((call) => call[1] === undefined), + ).toBe(true); + }); + + it("recovers a damaged stream exactly as it would with no expectation", () => { + const damaged = compressed.slice(0, compressed.length - 9); + const hinted = inflateTolerant(damaged, sample.length); + const plain = inflateTolerant(damaged); + expect(Array.from(hinted.bytes)).toEqual(Array.from(plain.bytes)); + expect(hinted.recovered).toBe(plain.recovered); + }); +}); diff --git a/packages/pdf-codec/src/bytes/flate.ts b/packages/pdf-codec/src/bytes/flate.ts index 57551c1d48..b80e22a4f6 100644 --- a/packages/pdf-codec/src/bytes/flate.ts +++ b/packages/pdf-codec/src/bytes/flate.ts @@ -13,6 +13,9 @@ const MAX_INFLATE_OUTPUT_MIB = 512; export const MAX_INFLATE_OUTPUT_BYTES = MAX_INFLATE_OUTPUT_MIB * KIB_PER_MIB * BYTES_PER_KIB; +// The most a deflate stream can expand: a 258-byte match costs at least two bits, so each input byte decodes to at most 1032 bytes (zlib's own technical details give the same limit). +const DEFLATE_MAX_EXPANSION = 1032; + export type DeflateLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9; export function deflate( @@ -40,7 +43,44 @@ export interface InflateResult { } // A tolerant inflate for the read path: real-world PDF/PNG streams occasionally carry a leading whitespace byte, are mistakenly raw-DEFLATE under a zlib-labelled filter, or are truncated. Tries, in order: a plain inflate(); skipping leading whitespace and retrying; raw inflateSync (some producers mislabel raw DEFLATE as FlateDecode); and finally the streaming Unzlib class, which emits chunks as they're produced, so a mid-stream truncation still yields whatever decoded successfully before the failure (`recovered: true`) rather than nothing at all. -export function inflateTolerant(data: Uint8Array): InflateResult { +// Inflates straight into a buffer as long as the caller expects the output to be, plus one byte. A stream that decodes to no more than expectedLength bytes is then decoded once, with no buffer growth and no trimming copy, to exactly the bytes inflate returns (fflate writes the same bytes whatever buffer it writes them into). Undefined when the stream does not decode or does not fit, which the spare byte filling up is how a too-long stream shows, for the caller to inflate it as before. +function inflateIntoExpectedLength( + data: Uint8Array, + expectedLength: number, +): Uint8Array | undefined { + // An expectation the data could not possibly meet is not acted on: deflate expands at most DEFLATE_MAX_EXPANSION-fold, so a dictionary claiming a huge image over a tiny stream never buys a huge buffer. + if ( + !Number.isInteger(expectedLength) || + expectedLength < 0 || + expectedLength >= MAX_INFLATE_OUTPUT_BYTES || + expectedLength > data.length * DEFLATE_MAX_EXPANSION + ) { + return undefined; + } + try { + const out = unzlibSync(data, { out: new Uint8Array(expectedLength + 1) }); + return out.length <= expectedLength ? out : undefined; + } catch { + return undefined; + } +} + +/** + * Inflates a zlib stream, recovering what it can from a damaged one. + * @param data - The zlib stream. + * @param expectedLength - How long the caller expects the output to be (an image's rows of samples), if it knows. A stream that decodes to at most this many bytes is decoded into one buffer of that size, rather than one grown by doubling and then trimmed, which for a large image is most of what inflating it costs in memory; the bytes are the same either way, and a stream that does not fit is inflated as if no length were given. + * @returns The inflated bytes, and whether recovery was needed. + */ +export function inflateTolerant( + data: Uint8Array, + expectedLength?: number, +): InflateResult { + if (expectedLength !== undefined) { + const sized = inflateIntoExpectedLength(data, expectedLength); + if (sized !== undefined) { + return { bytes: sized, recovered: false }; + } + } try { return { bytes: inflate(data), recovered: false }; } catch { diff --git a/packages/pdf-codec/src/filters.ts b/packages/pdf-codec/src/filters.ts index 9b961879f7..4ab5509ccc 100644 --- a/packages/pdf-codec/src/filters.ts +++ b/packages/pdf-codec/src/filters.ts @@ -5,7 +5,11 @@ import { decodeCcittFax } from "./image/ccitt"; import { decodeJbig2Embedded } from "./image/jbig2"; import type { PdfDict, PdfObject } from "./objects"; import { asArray, asBool, asDict, asName, asNumber, dictGet } from "./objects"; -import { applyPredictor, readPredictorParams } from "./predictors"; +import { + applyPredictor, + lengthBeforePredictor, + readPredictorParams, +} from "./predictors"; const BITS_PER_BYTE = 8; const BYTE_MASK = 0xff; // an all-ones byte: used both to bit-invert a byte (XOR) and to keep only its low 8 bits after a wider shift (AND) @@ -52,11 +56,14 @@ export type PdfIndirectResolver = ( ) => PdfObject | undefined; // Runs a stream's raw bytes through its /Filter chain (a single name or an array of names, with /DecodeParms supplying per-filter parameters in the same single-or-array shape). Recoverable per-filter issues (an unresolvable /Predictor, an unimplemented filter) degrade with a diagnostic and stop the chain rather than throwing — the caller decides whether the partially- or un-decoded result is still useful (e.g. a DCTDecode image's bytes are perfectly usable as-is). +// +// expectedLength is how long the caller expects the decoded stream to be, when it knows (an image's rows of samples). It only sizes the buffer a final FlateDecode inflates into (see inflateTolerant), so it changes what decoding costs in memory, never the bytes it produces. export function decodeStream( raw: Uint8Array, dict: PdfDict, sink: PdfDiagnosticSink, resolve?: PdfIndirectResolver, + expectedLength?: number, ): DecodedStream { const filters = filterNames(dict); const parms = decodeParmsList(dict, filters.length); @@ -66,7 +73,15 @@ export function decodeStream( const filter = filters[i]!; const parm = parms[i]; if (filter === "FlateDecode" || filter === "Fl") { - bytes = applyPredictorIfPresent(inflateTolerant(bytes).bytes, parm, sink); + const inflatedLength = + expectedLength !== undefined && i === filters.length - 1 + ? lengthBeforePredictor(expectedLength, readPredictorParams(parm)) + : undefined; + bytes = applyPredictorIfPresent( + inflateTolerant(bytes, inflatedLength).bytes, + parm, + sink, + ); } else if (filter === "LZWDecode" || filter === "LZW") { const earlyChange = (asNumber(parm ? dictGet(parm, "EarlyChange") : undefined) ?? 1) !== 0; @@ -205,7 +220,7 @@ function jbig2Decode( } } -function filterNames(dict: PdfDict): string[] { +export function filterNames(dict: PdfDict): string[] { const filterObj = dictGet(dict, "Filter") ?? dictGet(dict, "F"); if (filterObj === undefined) { return []; diff --git a/packages/pdf-codec/src/images-read.ts b/packages/pdf-codec/src/images-read.ts index fa5b2f5f06..5172d9d7e2 100644 --- a/packages/pdf-codec/src/images-read.ts +++ b/packages/pdf-codec/src/images-read.ts @@ -8,6 +8,7 @@ import { import type { Jpeg2000Image } from "./image/jpeg2000"; import { decodeJpeg2000 } from "./image/jpeg2000"; import type { PdfDiagnosticSink } from "./diagnostics"; +import { NOOP_DIAGNOSTIC_SINK } from "./diagnostics"; import { decodeStream } from "./filters"; import type { PdfObjectResolver } from "./interpret-types"; import type { PdfDict, PdfObject } from "./objects"; @@ -399,7 +400,13 @@ function readSoftMaskAlpha( if (smaskObj?.kind !== "stream") { return undefined; } - const decoded = decodeStream(smaskObj.raw, smaskObj.dict, sink); + const decoded = decodeStream( + smaskObj.raw, + smaskObj.dict, + sink, + undefined, + expectedSampleLength(smaskObj.dict, resolver), + ); if (decoded.remainingFilter !== undefined) { return undefined; // an encoded (e.g. DCT) soft mask is out of scope — degrade to no alpha rather than guess } @@ -562,6 +569,43 @@ function readJpeg2000Image( }; } +// How many bytes an image's samples take, rows padded to a whole byte (ISO 32000-1 8.9.3), from its dictionary alone: what its stream should decode to, which decodeStream sizes its inflate buffer by. Undefined when the dictionary does not say (no usable size or depth, or a colour space this module does not read), and the stream is then decoded as it would be without it. The colour space is resolved with diagnostics discarded, since readImageXObject resolves it again and reports what it finds. +function expectedSampleLength( + dict: PdfDict, + resolver: Readonly, +): number | undefined { + const width = asNumber(dictGet(dict, "Width") ?? dictGet(dict, "W")); + const height = asNumber(dictGet(dict, "Height") ?? dictGet(dict, "H")); + const bitsPerComponent = + asNumber(dictGet(dict, "BitsPerComponent") ?? dictGet(dict, "BPC")) ?? + BITS_PER_BYTE; + if ( + width === undefined || + height === undefined || + !Number.isInteger(width) || + !Number.isInteger(height) || + !Number.isInteger(bitsPerComponent) || + width <= 0 || + height <= 0 || + bitsPerComponent <= 0 + ) { + return undefined; + } + const colorSpace = resolveColorSpace( + dictGet(dict, "ColorSpace") ?? dictGet(dict, "CS"), + resolver, + NOOP_DIAGNOSTIC_SINK, + ); + if (colorSpace.kind === "unsupported") { + return undefined; + } + const components = + colorSpace.kind === "indexed" ? 1 : componentsOf(colorSpace); + return ( + height * Math.ceil((width * components * bitsPerComponent) / BITS_PER_BYTE) + ); +} + export function readImageXObject( dict: PdfDict, raw: Uint8Array, @@ -579,7 +623,13 @@ export function readImageXObject( } // The resolver is threaded in here, and only here, because JBIG2Decode's own /JBIG2Globals DecodeParms entry is a stream that a producer essentially always writes as an indirect reference — no other filter this codec implements has a parameter that needs dereferencing. - const decoded = decodeStream(raw, dict, sink, (obj) => resolver.resolve(obj)); + const decoded = decodeStream( + raw, + dict, + sink, + (obj) => resolver.resolve(obj), + expectedSampleLength(dict, resolver), + ); const jbig2Original: ExtractedPdfImage["original"] = decoded.jbig2 === undefined ? undefined diff --git a/packages/pdf-codec/src/interpret.ts b/packages/pdf-codec/src/interpret.ts index c7db7a0a6a..9b8f8ceb2e 100644 --- a/packages/pdf-codec/src/interpret.ts +++ b/packages/pdf-codec/src/interpret.ts @@ -1,4 +1,6 @@ -import { COLOR_BLACK, type Point } from "document-schema.js"; +import type { Point } from "document-schema.js"; +// The colour module alone rather than the package barrel, which would load every content and layout schema document-schema.js defines (about 7 MB of heap) into a reader that only needs this one constant. +import { COLOR_BLACK } from "document-schema.js/color"; import { decodeStream } from "./filters"; import type { Matrix } from "./matrix"; import { diff --git a/packages/pdf-codec/src/predictors.test.ts b/packages/pdf-codec/src/predictors.test.ts index 792962fba4..69054db0fe 100644 --- a/packages/pdf-codec/src/predictors.test.ts +++ b/packages/pdf-codec/src/predictors.test.ts @@ -1,7 +1,11 @@ import { describe, expect, it } from "vitest"; import type { PdfDiagnostic, PdfDiagnosticSink } from "./diagnostics"; import { pdfDict, pdfNum } from "./objects"; -import { applyPredictor, readPredictorParams } from "./predictors"; +import { + applyPredictor, + lengthBeforePredictor, + readPredictorParams, +} from "./predictors"; function collectDiagnostics(): { sink: PdfDiagnosticSink; @@ -129,3 +133,41 @@ describe("applyPredictor", () => { expect(diagnostics[0]?.code).toBe("pdf/unsupported-predictor"); }); }); + +describe("lengthBeforePredictor", () => { + const params = (predictor: number, columns = 10, colors = 3) => ({ + predictor, + colors, + bitsPerComponent: 8, + columns, + }); + + it("is the decoded length itself without a predictor and under the TIFF predictor", () => { + expect(lengthBeforePredictor(300, params(1))).toBe(300); + expect(lengthBeforePredictor(300, params(2))).toBe(300); + }); + + it("adds one filter-type byte per row under a PNG predictor", () => { + // Ten 3-byte pixels a row: 30 bytes, so 300 bytes are ten rows of 31. + expect(lengthBeforePredictor(300, params(10))).toBe(310); + expect(lengthBeforePredictor(300, params(15))).toBe(310); + // A partial last row still carries its filter byte. + expect(lengthBeforePredictor(301, params(12))).toBe(341); + }); + + it("names no length for a predictor it does not undo, or rows of no bytes", () => { + expect(lengthBeforePredictor(300, params(5))).toBeUndefined(); + expect(lengthBeforePredictor(300, params(10, 0))).toBeUndefined(); + }); + + it("agrees with what applyPredictor reads back", () => { + const rows = 4; + const bytesPerRow = 30; + const encoded = new Uint8Array( + lengthBeforePredictor(rows * bytesPerRow, params(10))!, + ); + expect(applyPredictor(encoded, params(10), () => undefined)).toHaveLength( + rows * bytesPerRow, + ); + }); +}); diff --git a/packages/pdf-codec/src/predictors.ts b/packages/pdf-codec/src/predictors.ts index 095506a729..f920ede799 100644 --- a/packages/pdf-codec/src/predictors.ts +++ b/packages/pdf-codec/src/predictors.ts @@ -45,6 +45,30 @@ export function readPredictorParams( }; } +/** + * How long a stream's data is before its predictor is undone, for data that decodes to `decodedLength` bytes: the same length for no predictor and the TIFF predictor, and one filter-type byte more per row for a PNG predictor. + * @param decodedLength - The length the predictor's output is expected to be. + * @param params - The stream's predictor parameters. + * @returns The length, or undefined for a predictor this module does not undo. + */ +export function lengthBeforePredictor( + decodedLength: number, + params: PredictorParams, +): number | undefined { + if (params.predictor <= 2) { + return decodedLength; + } + if (params.predictor < PNG_PREDICTOR_CODE_MIN) { + return undefined; + } + const bytesPerRow = Math.ceil( + (params.colors * params.bitsPerComponent * params.columns) / BITS_PER_BYTE, + ); + return bytesPerRow > 0 + ? Math.ceil(decodedLength / bytesPerRow) * (bytesPerRow + 1) + : undefined; +} + export function applyPredictor( data: Uint8Array, params: PredictorParams, From 03434e039bebfc77e258d07c48942402fcd82631 Mon Sep 17 00:00:00 2001 From: fcbwilliams Date: Tue, 17 Nov 2026 15:17:08 +0100 Subject: [PATCH 03/11] feat(pdf-codec): list a PDF's images without decoding them, and decode one at a time readPdf decodes every image a read page draws in one synchronous call and keeps each in its registry as a base64 string, so a picture-heavy file costs memory in proportion to its number of images as well as its largest: a deck shaped like the one that exceeded a 128 MB Worker isolate peaked at about 140 MB of heap and array buffers in 5.8, and 526 MB in 4.5.2. listPdfImages lists every image the pages draw by reference (an image XObject's object number, or an inline image's page and position) with its placements, exactly as readPdf's image items state them, and what its dictionary declares, without decoding any image stream. decodePdfImage decodes one image by that locator to exactly the bytes, format, size and imageId readPdf registers for it, without interpreting any page again. openPdfImages does both against one opened document. Listing and decoding that deck's 108 images one at a time peaks at about 56 MB, measured by scripts/measure-image-memory.mjs against a generated fixture of the same shape. Page geometry, the header check and page selection move out of read.ts into page-frame.ts and read-open.ts so the listing places items as readPdf does without loading readPdf's text pipeline; read.ts keeps exporting normalizeRotation and pageRotationTransform. Tests pin every decoded image of two generated fixtures to the digests pdf-codec 4.5.2 produced for them. Co-Authored-By: Claude Opus 5.5 --- packages/pdf-codec/README.md | 25 +- .../scripts/measure-image-memory-worker.mjs | 60 +++ .../scripts/measure-image-memory.mjs | 89 ++++ packages/pdf-codec/src/diagnostics.ts | 14 + packages/pdf-codec/src/index.ts | 12 + packages/pdf-codec/src/page-frame.ts | 335 ++++++++++++ packages/pdf-codec/src/raster.ts | 2 +- packages/pdf-codec/src/read-convert.ts | 13 +- packages/pdf-codec/src/read-graph.test.ts | 16 + packages/pdf-codec/src/read-images.test.ts | 286 +++++++++++ packages/pdf-codec/src/read-images.ts | 413 +++++++++++++++ packages/pdf-codec/src/read-open.ts | 39 ++ packages/pdf-codec/src/read.ts | 359 ++----------- .../test-support/image-heavy-pdf-golden.ts | 245 +++++++++ .../src/test-support/image-heavy-pdf.ts | 476 ++++++++++++++++++ 15 files changed, 2052 insertions(+), 332 deletions(-) create mode 100644 packages/pdf-codec/scripts/measure-image-memory-worker.mjs create mode 100644 packages/pdf-codec/scripts/measure-image-memory.mjs create mode 100644 packages/pdf-codec/src/page-frame.ts create mode 100644 packages/pdf-codec/src/read-images.test.ts create mode 100644 packages/pdf-codec/src/read-images.ts create mode 100644 packages/pdf-codec/src/read-open.ts create mode 100644 packages/pdf-codec/src/test-support/image-heavy-pdf-golden.ts create mode 100644 packages/pdf-codec/src/test-support/image-heavy-pdf.ts diff --git a/packages/pdf-codec/README.md b/packages/pdf-codec/README.md index 78a967458e..62644d9b53 100644 --- a/packages/pdf-codec/README.md +++ b/packages/pdf-codec/README.md @@ -115,6 +115,29 @@ Each surface, and what page items lose without it (everything else about every p 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. +**Reading images one at a time.** `readPdf` decodes every image a read page draws in its one synchronous call and keeps each in `LayoutDocument.images` as a base64 string, so its memory grows with the number of images as well as the size of the largest. For a picture-heavy file in a memory-capped runtime (a Cloudflare Worker isolate's 128 MB, which counts typed-array buffers as well as the V8 heap), `listPdfImages` and `decodePdfImage` take that registry apart: + +```ts +import { decodePdfImage, listPdfImages, openPdfImages } from "pdf-codec"; + +// Every image the pages draw, by reference, with where each is drawn; no image stream is decoded. +const listing = listPdfImages(pdfBytes); // PdfImageEntry[] +for (const entry of listing) { + // One image, to exactly the bytes, format, size and imageId readPdf's registry holds for it. + const image = decodePdfImage(pdfBytes, entry.locator); // DecodedPdfImage | undefined +} + +// Or open the file once and decode through the same opened document, so its cross-reference table and object streams are parsed once. +const images = openPdfImages(pdfBytes); +for (const entry of images.list({ pages: [0, 1] })) { + images.decode(entry.locator); +} +``` + +A `PdfImageLocator` is plain data: an image XObject's object reference (`{ kind: "xobject", objectNumber, generation }`), or for an inline image, which has no object, its page and position among that page's inline images (`{ kind: "inline", pageIndex, occurrence }`). A caller can store one and decode the image in a later call, or a later process, against the same file bytes. Decoding an image XObject interprets no page at all; decoding an inline image interprets its own page's content again to find it (inline images are small by design, and rare). Each `PdfImageEntry` carries the image's `placements` (its page, `xPt`/`yPt`/`widthPt`/`heightPt`, `rotationDeg` and `layer`, exactly as `readPdf`'s image items state them), plus what its dictionary declares without decoding: `widthPx`/`heightPx`, `filters`, `softMask` and `encodedByteLength`. The listing holds the images `readPdf`'s pages draw: an image drawn only outside its page's crop box, and an `/ImageMask` stencil, are not listed, and an image whose decoding `readPdf` would refuse (an unsupported filter, colour space or bit depth) is listed and decodes to `undefined`, with the same diagnostic. A locator naming no image of the file throws `PdfImageLocatorError`. The structure-ownership association (`structure`) is not reported, since reading it needs the whole structure tree. + +The decoded bytes are those `readPdf` produces for the same image, which are those pdf-codec 4.5.2 produced (pinned in `src/read-images.test.ts` against digests recorded from 4.5.2), so an image stored by an earlier release keeps its identity. Decoding one image holds its decoded samples, its alpha plane and the PNG encoder's filtered rows and deflate buffer at once, in proportion to its pixels: a 2360x1309 RGB image with a soft mask needs about 40 MB on top of the module and the file. `pdf-codec/read-images` serves the three functions without the text pipeline `readPdf` loads (font resolution and its glyph tables, about 12 MB of heap), and `scripts/measure-image-memory.mjs` measures a generated picture-heavy fixture against the built `dist/`: about 56 MB peak for listing and decoding its 108 images one at a time, against about 140 MB for `readPdf` in 5.8 and 526 MB in 4.5.2. + **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. **Cancellation granularity and cost, for CPU-metered runtimes.** Both pipelines are synchronous end to end — there is no `await` point for cancellation to hook into implicitly — so the `signal` is checked explicitly, once per page-loop iteration (and once before `readPdf`'s document-open phase begins). A signal aborted mid-parse therefore takes effect at the next page boundary, not instantly: `readPdf`'s document-open phase (cross-reference resolution, object parsing) and a single page's content-stream interpretation are the two spans that cannot be interrupted, and a document consisting of one enormous page is effectively uninterruptible however many pages it claims. Cost is roughly linear in decompressed content length, so budget for the worst single page, not the page count. On Cloudflare Workers this is the honest shape of the trade: the parse holds the isolate for its whole duration with no opportunity to yield or report progress, and an `AbortSignal` shared with whatever can abort concurrently (a binding, another context) makes a deadline enforceable at page granularity — but it cannot convert a synchronous parse into a resumable one. An async page-at-a-time API is a deliberate non-goal of this package's current surface. @@ -283,7 +306,7 @@ The package is layered from generic primitives outward to the codec itself: - **Embedded text faces**: `embedded-font.ts` (parses one TrueType-outline face's metrics and `GPOS` pair kerning, and `encodeForShowEmbedded` — the single code path both measurement and text-showing go through so encoding and measuring cannot disagree). Every geometry field is converted into PDF's 1000-units-per-em glyph space. `embedded-font-write.ts` builds the `/Type0`/`/CIDFontType2`/`/FontDescriptor`/`/FontFile2`/ToUnicode group, with `/CIDToGIDMap /Identity` written explicitly and `/Length1` set to the **uncompressed** subset length. Its subset tag is a CRC32 over the face's PostScript name and glyph-ID list, so identical input yields byte-identical output. - **ToUnicode CMaps**: `tounicode.ts`, shared by both embedded-font writers — a character code → Unicode code point mapping written as a bfchar CMap (9.10.3), with supplementary-plane code points encoded as UTF-16BE surrogate pairs and entries emitted in blocks of at most 100. - **CFF reading**: `cff.ts` (shared `INDEX`/`DICT` container structures), `cff-bounds.ts` (a Type 2 charstring interpreter computing each glyph's tight ink bounding box by tracking the current point through every path operator and solving each cubic's real extrema from the roots of its derivative — a path walker, not a rasteriser; verified against the vendored STIX Two Math font's whole 5,543-glyph repertoire, matching fontTools' `BoundsPen` to within 0.01 design units). `cff-probe.ts` reads a bare CFF program's header/Name INDEX/Top DICT to detect the `ROS` operator defining a CID-keyed font — the guard a future source-embedded-font phase needs before it can trust CID == GID against an arbitrary caller-supplied font. - - **Read**: `lexer.ts`/`parse.ts` (byte tokenizer and tokens → `PdfObject`), `filters.ts`/`predictors.ts` (Flate/LZW/ASCII85/ASCIIHex/RunLength/CCITTFax, TIFF/PNG predictors), `xref.ts`/`document.ts` (classic and cross-reference-stream resolution, object streams, `/Prev` chains, linear-scan recovery, the page tree with attribute inheritance), `encrypt.ts` (standard security handler: `/Encrypt` parsing, empty-user-password key derivation and `/U` verification, per-object keys, transparent string/stream decryption), `content-read.ts`/`interpret.ts`/`interpret-state.ts` (content-stream tokenizer and graphics/text state machine, with the state records and the per-glyph displacement arithmetic in the last, form-XObject recursion, general vector-path tracking), `cmap.ts`/`font-style.ts`/`font-read.ts` (`/ToUnicode` CMaps, font-dictionary resolution), `builtin-encoding.ts` (a font's own built-in encoding, read out of the embedded program itself — see [Text extraction and font encodings](#text-extraction-and-font-encodings)), `images-read.ts` (Image XObjects → PNG/JPEG bytes), `names.ts` (the document-level name-tree walker: one flattening pass for every `/Names` tenant), `navigation.ts` (named destinations from `/Dests` and `/Names` `/Dests`, reader-minted entries for direct destination arrays, and the `/Outlines` bookmark tree), `attachments.ts` (embedded files from the name tree, `/FileAttachment` filespecs, and `/AF`), `optional-content.ts` (`/OCProperties` groups and default-configuration visibility, plus the `/OC`-to-name resolution `interpret.ts` stamps onto span items), `annotations.ts` (sticky notes, FreeText, the `/QuadPoints` markup family, and residue for the opaque kinds), `form.ts` (the AcroForm field tree), `structure.ts` (the tagged-PDF `/StructTreeRoot` element tree with `/RoleMap` resolution and `/ClassMap` attribute merging, plus the `/ParentTree` walk that resolves each `(page, MCID)` pair to the owning element `read.ts` stamps onto an item), `xmp.ts` (a bounded Dublin Core extractor for the `/Metadata` packet), `pdf-text.ts` (PDF string/date scalar decoding), `read.ts` (`readPdf`, assembling all of the above into a `LayoutDocument`). + - **Read**: `lexer.ts`/`parse.ts` (byte tokenizer and tokens → `PdfObject`), `filters.ts`/`predictors.ts` (Flate/LZW/ASCII85/ASCIIHex/RunLength/CCITTFax, TIFF/PNG predictors), `xref.ts`/`document.ts` (classic and cross-reference-stream resolution, object streams, `/Prev` chains, linear-scan recovery, the page tree with attribute inheritance), `encrypt.ts` (standard security handler: `/Encrypt` parsing, empty-user-password key derivation and `/U` verification, per-object keys, transparent string/stream decryption), `content-read.ts`/`interpret.ts`/`interpret-state.ts` (content-stream tokenizer and graphics/text state machine, with the state records and the per-glyph displacement arithmetic in the last, form-XObject recursion, general vector-path tracking), `cmap.ts`/`font-style.ts`/`font-read.ts` (`/ToUnicode` CMaps, font-dictionary resolution), `builtin-encoding.ts` (a font's own built-in encoding, read out of the embedded program itself — see [Text extraction and font encodings](#text-extraction-and-font-encodings)), `images-read.ts` (Image XObjects → PNG/JPEG bytes), `read-images.ts` (`listPdfImages`/`decodePdfImage`/`openPdfImages`: the image registry taken apart into a listing that decodes nothing and a decode of one image by reference), `page-frame.ts` (a page's visible region and the matrix placing its content there, shared by `readPdf` and the image listing), `read-open.ts` (the header check and page-selection resolution both of those run first), `names.ts` (the document-level name-tree walker: one flattening pass for every `/Names` tenant), `navigation.ts` (named destinations from `/Dests` and `/Names` `/Dests`, reader-minted entries for direct destination arrays, and the `/Outlines` bookmark tree), `attachments.ts` (embedded files from the name tree, `/FileAttachment` filespecs, and `/AF`), `optional-content.ts` (`/OCProperties` groups and default-configuration visibility, plus the `/OC`-to-name resolution `interpret.ts` stamps onto span items), `annotations.ts` (sticky notes, FreeText, the `/QuadPoints` markup family, and residue for the opaque kinds), `form.ts` (the AcroForm field tree), `structure.ts` (the tagged-PDF `/StructTreeRoot` element tree with `/RoleMap` resolution and `/ClassMap` attribute merging, plus the `/ParentTree` walk that resolves each `(page, MCID)` pair to the owning element `read.ts` stamps onto an item), `xmp.ts` (a bounded Dublin Core extractor for the `/Metadata` packet), `pdf-text.ts` (PDF string/date scalar decoding), `read.ts` (`readPdf`, assembling all of the above into a `LayoutDocument`). - **Raster**: `raster.ts` — the `PageRasteriser` port and `renderPdfPage` (#1198): re-walks one page through `interpretContentStream` (the same interpreter `readPdf` runs), recomputes the page's crop/rotation geometry (test-pinned to agree with `readPdf` bit for bit, since the `clipPt` contract rides on it), and drives a caller-supplied rasteriser with device-space draw ops — rect fills, filled/stroked vector paths, affine-placed images, and text as filled glyph-outline paths resolved from the page's own embedded sfnt programs (`glyf-contours.ts`'s decoded contours through the run's text matrices, per-glyph advances corrected against the run's exact end matrix). Optional-content layers the default configuration leaves OFF are not drawn; faces with no sfnt outlines are refused by name. No canvas dependency, no backend, no OCR/vision/network — the port is pure data plus callbacks, so `pdf-raster-cpu` (or a browser canvas wrapper) implements it elsewhere. - `codec.ts` — `pdfCodec`, a `z.codec()` pair over `readPdf`/`writePdf`, plus a standalone local copy of the `%PDF-` header check. - **`src/test-support/`** — hand-built PDF fixtures (`pdf.ts`) built by literal byte/string concatenation and deliberately importing NOTHING from this package's own writer (a fixture built by `writePdf` would let a writer bug hide from the corresponding reader test). `encrypted-pdfs.ts` applies the same principle: real PDFs encrypted by [qpdf](https://qpdf.sourceforge.io/), embedded as base64, so a bug in key derivation cannot cancel out between write and read halves. `fonts.ts` holds the real vendored Carlito and Caladea faces as raw sfnt bytes, and asserts values read out of the `.ttf` files by a standalone script with a bare `DataView`, not by this package's own parsers — external cross-checks rather than a parser's output compared against itself. diff --git a/packages/pdf-codec/scripts/measure-image-memory-worker.mjs b/packages/pdf-codec/scripts/measure-image-memory-worker.mjs new file mode 100644 index 0000000000..1ca18a2df0 --- /dev/null +++ b/packages/pdf-codec/scripts/measure-image-memory-worker.mjs @@ -0,0 +1,60 @@ +// The read measure-image-memory.mjs samples: runs in a worker thread so that thread can watch this one's heap. See that script for what is measured. +import { setFlagsFromString } from "node:v8"; +import { runInNewContext } from "node:vm"; +import { parentPort, workerData } from "node:worker_threads"; + +const { mode, collect, pdf, readEntry } = workerData; +// Each mode loads only the module it measures, as a memory-capped Worker bundling that one entry would, never the barrel: the barrel's write half carries ~2.9 MB of vendored fonts, and readPdf's text pipeline (font resolution and its glyph tables) about 12 MB of heap that the per-image reader never loads. +const { readPdf } = + mode === "read-pdf" ? await import(readEntry) : { readPdf: undefined }; +const { openPdfImages } = + mode === "per-image" + ? await import("../dist/read-images.js") + : { openPdfImages: undefined }; +// A worker cannot be started with --expose-gc, so it exposes the collector to itself. +if (collect) { + setFlagsFromString("--expose-gc"); +} +const gc = collect ? runInNewContext("gc") : () => undefined; + +const counts = { images: 0, pngs: 0, jpegs: 0, largestPixels: 0, largest: "" }; +const count = (image) => { + counts.images += 1; + counts[image.format === "png" ? "pngs" : "jpegs"] += 1; + if (image.widthPx * image.heightPx > counts.largestPixels) { + counts.largestPixels = image.widthPx * image.heightPx; + counts.largest = `${String(image.widthPx)}x${String(image.heightPx)} ${image.format}`; + } +}; + +gc(); +const memory = process.memoryUsage(); +parentPort.postMessage({ kind: "ready", memory }); +const started = performance.now(); +const cpuStarted = process.cpuUsage(); + +if (mode === "per-image") { + const images = openPdfImages(pdf); + const listing = images.list(); + for (const entry of listing) { + gc(); + const decoded = images.decode(entry.locator); + if (decoded !== undefined) { + count(decoded); + } + } +} else { + gc(); + const doc = readPdf(pdf); + for (const asset of Object.values(doc.images)) { + count(asset); + } +} + +const cpu = process.cpuUsage(cpuStarted); +parentPort.postMessage({ + kind: "done", + ...counts, + wallMs: performance.now() - started, + cpuMs: (cpu.user + cpu.system) / 1000, +}); diff --git a/packages/pdf-codec/scripts/measure-image-memory.mjs b/packages/pdf-codec/scripts/measure-image-memory.mjs new file mode 100644 index 0000000000..7c6d5113f7 --- /dev/null +++ b/packages/pdf-codec/scripts/measure-image-memory.mjs @@ -0,0 +1,89 @@ +// Measures the memory reading a picture-heavy PDF's images costs, against the built dist/ (run `pnpm build` first): +// +// node scripts/measure-image-memory.mjs per-image [--gc] # openPdfImages: list, then decode every image one at a time +// node scripts/measure-image-memory.mjs read-pdf [--gc] # readPdf: every image decoded in one call, kept in its registry +// +// read-pdf mode takes --read-entry= to measure an earlier release the same way, e.g. one installed with `npm install pdf-codec@5.8.6` in a scratch directory. +// +// The PDF is src/test-support/image-heavy-pdf.ts's pictureDeckPdf: shaped like a typical picture-heavy slide deck (about 2.5 MB, 108 images, Flate RGB with soft masks up to 2360x1309), generated, never a real document. The read runs in a worker thread, and this thread samples the worker's V8 heap statistics continuously while it runs: worker.getHeapStatistics() is answered through a V8 interrupt, so it samples inside a synchronous decode too, not only between calls. The figure reported is the peak of used_heap_size + external_memory, the second of which holds every ArrayBuffer's backing store: a typed array's bytes sit outside the V8 heap (and outside --max-old-space-size) but count towards a Cloudflare Worker isolate's 128 MB all the same. Garbage counts until the collector runs; --gc collects before each image, which shows what the decode itself needs at once rather than what the collector has yet to reclaim. +import { Worker } from "node:worker_threads"; +import { fileURLToPath } from "node:url"; +import { createJiti } from "jiti"; + +const mode = process.argv[2] ?? "per-image"; +const collect = process.argv.includes("--gc"); +const readEntryArgument = process.argv.find((argument) => + argument.startsWith("--read-entry="), +); +const readEntry = + readEntryArgument === undefined + ? new URL("../dist/read.js", import.meta.url).href + : new URL(readEntryArgument.slice("--read-entry=".length), `file://${process.cwd()}/`).href; +if (mode !== "per-image" && mode !== "read-pdf") { + throw new Error(`unknown mode ${mode}: per-image or read-pdf`); +} + +const jiti = createJiti(import.meta.url); +const { pictureDeckPdf } = await jiti.import( + "../src/test-support/image-heavy-pdf.ts", +); +const pdf = pictureDeckPdf(); + +const worker = new Worker( + fileURLToPath(new URL("./measure-image-memory-worker.mjs", import.meta.url)), + { + workerData: { mode, collect, pdf, readEntry }, + }, +); +await new Promise((resolve) => worker.once("online", resolve)); + +const MB = 2 ** 20; +let peak = 0; +let baseline; +let report; +let failure; +worker.on("message", (message) => { + if (message.kind === "ready") { + baseline = message.memory; + } else { + report = message; + } +}); +worker.on("error", (error) => { + failure = error; +}); +const exited = new Promise((resolve) => worker.once("exit", resolve)); +let running = true; +void exited.then(() => { + running = false; +}); +while (running) { + try { + const stats = await worker.getHeapStatistics(); + peak = Math.max(peak, stats.used_heap_size + stats.external_memory); + } catch { + break; // the worker exited between the check and the request + } +} +await exited; +if (failure !== undefined) { + throw failure; +} + +const format = (bytes) => `${(bytes / MB).toFixed(1)} MB`; +console.log(`PDF: ${format(pdf.length)} (${String(pdf.length)} bytes)`); +console.log( + `mode: ${mode}${collect ? " (collecting before each image)" : ""}${mode === "read-pdf" ? ` from ${readEntry}` : ""}`, +); +console.log( + `before reading (module loaded, PDF bytes held): heapUsed + arrayBuffers = ${format(baseline.heapUsed + baseline.arrayBuffers)}`, +); +console.log( + `peak heapUsed + arrayBuffers (sampled V8 used_heap_size + external_memory): ${format(peak)}`, +); +console.log( + `images: ${String(report.images)} decoded (${String(report.pngs)} PNG, ${String(report.jpegs)} JPEG), largest ${report.largest}`, +); +console.log( + `time: ${String(Math.round(report.wallMs))} ms wall, ${String(Math.round(report.cpuMs))} ms CPU`, +); diff --git a/packages/pdf-codec/src/diagnostics.ts b/packages/pdf-codec/src/diagnostics.ts index a2cee8d0cf..e1b59f2a1e 100644 --- a/packages/pdf-codec/src/diagnostics.ts +++ b/packages/pdf-codec/src/diagnostics.ts @@ -1,4 +1,5 @@ // The parser's three-tier failure policy (throw / recover-with-diagnostic / degrade-with-diagnostic — see the implementation plan's Step 7.5): a hand-written parser measured in low thousands of lines cannot match a mature library's robustness against adversarial or mis-generated real-world input, so it must be explicit about which tier each situation falls into rather than silently picking one. This module is the shared vocabulary every other src/pdf/* read-side module reports through. +import type { PdfImageLocator } from "./read-images"; export type PdfDiagnosticSeverity = "info" | "warning"; @@ -51,6 +52,19 @@ export class PdfPageSelectionError extends PdfParseError { } } +/** + * A locator `decodePdfImage` (or `PdfImages.decode`) was given that names no image of the document: an object that is not an image XObject stream (code `pdf/image-not-found`), or an inline image occurrence its page does not hold (the same code; a page index naming no page throws `PdfPageSelectionError` instead). Thrown rather than reported, because a locator comes from a listing of this same file, so one naming nothing means the caller has the wrong file or a wrong locator. + */ +export class PdfImageLocatorError extends PdfParseError { + readonly locator: PdfImageLocator; + + constructor(locator: PdfImageLocator, message: string) { + super("pdf/image-not-found", message); + this.name = "PdfImageLocatorError"; + this.locator = locator; + } +} + // /Encrypt present, and encrypted in a way this codec cannot read at all: a non-standard security handler (/Filter other than /Standard, e.g. a public-key one), an unpublished or unrecognised /V, or a crypt filter naming a /CFM this codec does not implement. Distinct from PdfPasswordRequiredError below, which means the encryption itself IS supported and the file simply needs a password we do not have. export class PdfEncryptedError extends PdfParseError { constructor(message = "this PDF is encrypted and unsupported") { diff --git a/packages/pdf-codec/src/index.ts b/packages/pdf-codec/src/index.ts index eb81bb22d6..90750178a0 100644 --- a/packages/pdf-codec/src/index.ts +++ b/packages/pdf-codec/src/index.ts @@ -3,6 +3,17 @@ // Headline: read/write/diagnostics/codec. readPdf/writePdf speak LayoutDocument and there is deliberately no DocumentTree-native pair beside them. On read, PDF states positions, not structure — readPdf yields layout cheaply, and semantic content (paragraphs, headings, tables) only through a separate, lossy reconstruction pass that infers structure from geometry, genuine semantic policy that lives in documents.js (src/layout/reconstruct.ts). On write, a DocumentTree reaches PDF bytes only once a prior layout pass has already stamped frames onto it (a package with no pages, e.g. a bridge conversion's own odt-to-docx dump, cannot reach PDF at all): documents.js's layoutDocumentFromPackage walks those already-stamped frames back into a LayoutDocument, a mechanical inverse rather than a font-measuring, line-breaking pass of its own — the actual layout engine runs earlier, wherever the package first passed through an X-to-PDF or PDF-to-X conversion. ExaDev/pdf-codec#65 scoped the frames-mapping half of this boundary to this package ("readPdf/writePdf ... gain mappings to and from package frames at the edge"); that half was never implemented here and instead lives in documents.js as layoutDocumentFromPackage — a deliberate reassignment, not an oversight, but one #65 itself doesn't record. Adding a DocumentTree-facing wrapper here would mean this package owning either a reconstruction heuristic or a frame-walking pass that depends on a layout stage documents.js runs, and would make pdf-codec depend on the package that depends on it. export type { ReadPdfOptions, ReadPdfSurfaces } from "./read"; export { readPdf } from "./read"; +// Per-image reading for a memory-capped caller: list a PDF's images by reference with their placements, without decoding any, then decode one at a time to exactly the bytes readPdf's registry holds (see read-images.ts). +export type { + DecodedPdfImage, + ListPdfImagesOptions, + PdfImageEntry, + PdfImageLocator, + PdfImagePlacement, + PdfImageReadOptions, + PdfImages, +} from "./read-images"; +export { decodePdfImage, listPdfImages, openPdfImages } from "./read-images"; export type { WritePdfOptions } from "./write"; export { PdfPartialDocumentError, writePdf } from "./write"; export { PdfSkippedSurfacesError } from "./write-skipped-surfaces"; @@ -21,6 +32,7 @@ export type { export { NOOP_DIAGNOSTIC_SINK, PdfEncryptedError, + PdfImageLocatorError, PdfPageSelectionError, PdfParseError, PdfPasswordRequiredError, diff --git a/packages/pdf-codec/src/page-frame.ts b/packages/pdf-codec/src/page-frame.ts new file mode 100644 index 0000000000..bcc0275f4e --- /dev/null +++ b/packages/pdf-codec/src/page-frame.ts @@ -0,0 +1,335 @@ +import { concatBytes } from "./bytes/writer"; +import type { PdfDiagnosticSink } from "./diagnostics"; +import { decodeStream } from "./filters"; +import type { PdfObjectResolver } from "./interpret-types"; +import type { LayoutItem } from "./layout"; +import type { Matrix } from "./matrix"; +import { + applyMatrix, + multiplyMatrices, + rotatePointAboutCenter, + translationMatrix, +} from "./matrix"; +import type { PdfDict } from "./objects"; +import { asArray, asNumber, dictGet } from "./objects"; + +// A page's visible region and the matrix placing its content in it, split from read.ts so every reader that walks a page's content (readPdf, and the image listing in read-images.ts) places items identically: the crop box as the visible region (ISO 32000-1 14.11.2), /Rotate applied, and every position made relative to the visible region's lower-left corner. Kept free of the text pipeline's modules (font resolution and its glyph tables), which the image listing never needs: loading them costs a Worker isolate about 12 MB before it reads anything. + +// US Letter (ISO 32000-1's own example default, and the overwhelming common fallback in practice): used only when a page has no /MediaBox at all, even after page-tree inheritance — a genuinely malformed file. +const DEFAULT_PAGE_WIDTH_PT = 612; +const DEFAULT_PAGE_HEIGHT_PT = 792; + +export interface PageBoxRect { + readonly llx: number; + readonly lly: number; + readonly urx: number; + readonly ury: number; +} + +// One of the five page-boundary rectangles (ISO 32000-1 14.11.2), normalised to lower-left/upper-right corners — a producer may write either corner order. Undefined when the page does not declare the entry; only /MediaBox has a fallback (the malformed-file letter default below). +function readDeclaredPageBox( + page: PdfDict, + key: string, +): PageBoxRect | undefined { + const arr = asArray(dictGet(page, key)); + if (arr === undefined) { + return undefined; + } + const a = asNumber(arr[0]) ?? 0; + const b = asNumber(arr[1]) ?? 0; + const c = asNumber(arr[2]) ?? 0; + const d = asNumber(arr[3]) ?? 0; + return { + llx: Math.min(a, c), + lly: Math.min(b, d), + urx: Math.max(a, c), + ury: Math.max(b, d), + }; +} + +function readMediaBox(page: PdfDict): PageBoxRect { + return ( + readDeclaredPageBox(page, "MediaBox") ?? { + llx: 0, + lly: 0, + urx: DEFAULT_PAGE_WIDTH_PT, + ury: DEFAULT_PAGE_HEIGHT_PT, + } + ); +} + +// The axis-aligned bounds of a page rectangle after a rotation transform — all four corners transformed, then min/max, because a rotation that is not about the box's own corner does not preserve which corner is lower-left (and /Rotate's matrix is built for the media box's frame, not the crop box's). +interface RotatedRectBounds { + readonly minX: number; + readonly minY: number; + readonly maxX: number; + readonly maxY: number; +} + +function rotatedRectBounds( + rect: PageBoxRect, + matrix: Matrix, +): RotatedRectBounds { + const corners: readonly (readonly [number, number])[] = [ + [rect.llx, rect.lly], + [rect.urx, rect.lly], + [rect.llx, rect.ury], + [rect.urx, rect.ury], + ]; + const transformed = corners.map(([x, y]) => applyMatrix(matrix, { x, y })); + const xs = transformed.map((point) => point.x); + const ys = transformed.map((point) => point.y); + return { + minX: Math.min(...xs), + minY: Math.min(...ys), + maxX: Math.max(...xs), + maxY: Math.max(...ys), + }; +} + +export type PageRotation = 0 | 90 | 180 | 270; +type NonZeroPageRotation = 90 | 180 | 270; + +// The three non-zero values ISO 32000-1 7.7.3.3's /Rotate can normalize to. +const QUARTER_TURN_DEG = 90; +const HALF_TURN_DEG = 180; +const THREE_QUARTER_TURN_DEG = 270; +const DEGREES_PER_TURN = 360; + +// A user-defined type guard, rather than a plain boolean check, because `PageRotation` needs `normalized` narrowed to `NonZeroPageRotation` below: comparing against QUARTER_TURN_DEG/HALF_TURN_DEG/THREE_QUARTER_TURN_DEG (typed as plain `number`, since that is what a bare `const` initializer widens to) would not narrow the way comparing against inline literals does, and this predicate's own declared return type supplies that narrowing instead. +function isNonZeroPageRotation(n: number): n is NonZeroPageRotation { + return ( + n === QUARTER_TURN_DEG || + n === HALF_TURN_DEG || + n === THREE_QUARTER_TURN_DEG + ); +} + +export function normalizeRotation(rotate: number | undefined): PageRotation { + if (rotate === undefined) { + return 0; + } + const normalized = + (((Math.round(rotate / QUARTER_TURN_DEG) * QUARTER_TURN_DEG) % + DEGREES_PER_TURN) + + DEGREES_PER_TURN) % + DEGREES_PER_TURN; + return isNonZeroPageRotation(normalized) ? normalized : 0; +} + +export interface PageRotationResult { + readonly matrix: Matrix; + readonly widthPt: number; + readonly heightPt: number; +} + +// Each case derived and verified independently by tracking where all four MediaBox corners land after physically rotating the rendered page clockwise by the given angle (ISO 32000-1 7.7.3.3's own definition of /Rotate) — e.g. for 90, the original bottom-left corner (0,0) becomes the new page's top-left corner (0, w), and solving the resulting four-corner system gives (x,y) -> (y, w-x). +export function pageRotationTransform( + rotation: PageRotation, + w: number, + h: number, +): PageRotationResult { + if (rotation === QUARTER_TURN_DEG) { + return { matrix: [0, -1, 1, 0, 0, w], widthPt: h, heightPt: w }; + } + if (rotation === HALF_TURN_DEG) { + return { matrix: [-1, 0, 0, -1, w, h], widthPt: w, heightPt: h }; + } + if (rotation === THREE_QUARTER_TURN_DEG) { + return { matrix: [0, 1, -1, 0, h, 0], widthPt: h, heightPt: w }; + } + return { matrix: [1, 0, 0, 1, 0, 0], widthPt: w, heightPt: h }; +} + +/** A page's visible region, in output points, and the matrix that maps its content's user space into it. */ +export interface PageFrame { + readonly mediaBox: PageBoxRect; + readonly cropBox: PageBoxRect; + readonly widthPt: number; + readonly heightPt: number; + readonly pageMatrix: Matrix; +} + +/** + * Reads a page's visible region and the matrix placing its content there. + * @param pageIndex - The page's source position, for diagnostics. + * @param page - The page dictionary, inheritance already applied. + * @param sink - Receives a degenerate crop box's diagnostic. + * @returns The page's frame. + */ +export function readPageFrame( + pageIndex: number, + page: PdfDict, + sink: PdfDiagnosticSink, +): PageFrame { + const mediaBox = readMediaBox(page); + // The crop box is the visible region (ISO 32000-1 14.11.2: a viewer displays and prints it, and it defaults to the media box), so it — not the media box — is the page geometry this package reports, and content outside it is not visible at all. Inherited through the page tree like /MediaBox (one of 7.7.3.4's four inheritable attributes); /BleedBox /TrimBox /ArtBox are ordinary page-direct entries and are quarantined as residue, never clipped to. + let cropBox = readDeclaredPageBox(page, "CropBox") ?? mediaBox; + if (cropBox.urx - cropBox.llx <= 0 || cropBox.ury - cropBox.lly <= 0) { + sink({ + code: "pdf/invalid-crop-box", + severity: "warning", + pageIndex, + message: + "page /CropBox is degenerate (zero width or height); falling back to the /MediaBox as the visible region", + }); + cropBox = mediaBox; + } + const rotation = normalizeRotation(asNumber(dictGet(page, "Rotate"))); + // Only the rotation's matrix is used below, never its own widthPt/heightPt fields — and the matrix's rotation/reflection component (a, b, c, d) never depends on the w/h arguments at all, only its translation component (e, f) does. That translation is provably canceled by the origin renormalization below (translationMatrix(-visibleRect.minX, -visibleRect.minY) subtracts out exactly the offset any w/h value would have introduced), so the real mediaBox width/height would produce a byte-identical pageMatrix and visibleRect to passing 0 for both — confirmed directly against an asymmetric MediaBox/CropBox pair under every rotation, not merely the aligned case. Passing 0 rather than the real (but unobservable) mediaBox dimensions removes an arithmetic expression whose result genuinely never reaches any output. + const rotationMatrix = pageRotationTransform(rotation, 0, 0).matrix; + // The crop rect rotated into output space, then used as the origin: every item position is relative to the visible region's own lower-left corner, exactly as a viewer presents it. + const visibleRect = rotatedRectBounds(cropBox, rotationMatrix); + return { + mediaBox, + cropBox, + widthPt: visibleRect.maxX - visibleRect.minX, + heightPt: visibleRect.maxY - visibleRect.minY, + pageMatrix: multiplyMatrices( + rotationMatrix, + translationMatrix(-visibleRect.minX, -visibleRect.minY), + ), + }; +} + +// ISO 32000-1 7.8.2: when /Contents is an array, readers must treat the concatenation of the referenced streams as if they were one stream, "as though they were preceded and followed by white-space characters". Inserted here as a defensive LINE FEED, so a token straddling the end of one chunk and the start of the next can never merge into one, even when a producer omitted trailing whitespace of its own. +const CONTENT_STREAM_JOIN_BYTE = 0x0a; + +export function readPageContentBytes( + page: PdfDict, + resolver: Readonly, + sink: PdfDiagnosticSink, +): Uint8Array { + const contentsObj = resolver.resolve(dictGet(page, "Contents")); + if (contentsObj?.kind === "stream") { + return decodeStream(contentsObj.raw, contentsObj.dict, sink).bytes; + } + if (contentsObj?.kind === "array") { + const chunks: Uint8Array[] = []; + for (const item of contentsObj.items) { + const streamObj = resolver.resolve(item); + if (streamObj?.kind === "stream") { + chunks.push( + decodeStream(streamObj.raw, streamObj.dict, sink).bytes, + new Uint8Array([CONTENT_STREAM_JOIN_BYTE]), + ); + } + } + return concatBytes(chunks); + } + return new Uint8Array(0); +} + +// A content item's axis-aligned bounds in output page space — the crop-visibility filter's input. Link and internalLink kinds report undefined: an annotation is an anchored construct, not painted stream content, so the visibility filter must not claim it (the same line the optional-content filter draws, treating annotation kinds as not layer-governed content). +function contentItemBounds(item: LayoutItem): RotatedRectBounds | undefined { + if (item.kind === "link" || item.kind === "internalLink") { + return undefined; + } + const frameBounds = ( + xPt: number, + yPt: number, + widthPt: number, + heightPt: number, + ): RotatedRectBounds => ({ + minX: xPt, + minY: yPt, + maxX: xPt + widthPt, + maxY: yPt + heightPt, + }); + if ( + item.kind === "text" || + item.kind === "image" || + item.kind === "rect" || + item.kind === "ellipse" + ) { + if ( + item.kind !== "text" || + item.rotationDeg === undefined || + item.rotationDeg % HALF_TURN_DEG === 0 + ) { + // widthPt is optional on text (reported, not measured, on some paths) — a missing width still bounds the run to its anchor plus size, never an unbounded extent. + return frameBounds( + item.xPt, + item.yPt, + item.widthPt ?? 0, + item.kind === "text" ? item.sizePt : item.heightPt, + ); + } + // An obliquely rotated run's frame no longer bounds it: rotate the (width x size) frame's corners about the run's own anchor, which the conversion places invariantly, and take the hull. Generous by construction (the glyph ink stays within the em box), which errs toward keeping an edge-straddling run — the right direction for a visibility filter. + const rotationDeg = item.rotationDeg; + const anchorX = item.xPt; + const anchorY = item.yPt; + const corners: readonly (readonly [number, number])[] = [ + [0, 0], + [item.widthPt ?? 0, 0], + [0, item.sizePt], + [item.widthPt ?? 0, item.sizePt], + ]; + const rotated = corners.map(([dx, dy]) => + rotatePointAboutCenter( + { x: anchorX + dx, y: anchorY + dy }, + { x: anchorX, y: anchorY }, + rotationDeg, + ), + ); + const xs = rotated.map((point) => point.x); + const ys = rotated.map((point) => point.y); + return { + minX: Math.min(...xs), + minY: Math.min(...ys), + maxX: Math.max(...xs), + maxY: Math.max(...ys), + }; + } + if (item.kind === "line") { + return { + minX: Math.min(item.x1Pt, item.x2Pt), + minY: Math.min(item.y1Pt, item.y2Pt), + maxX: Math.max(item.x1Pt, item.x2Pt), + maxY: Math.max(item.y1Pt, item.y2Pt), + }; + } + // A path's bounds cover every subpath's start point, every segment endpoint, and every cubic control point — a Bezier can extend beyond its endpoint hull, and a visibility filter errs towards keeping, never towards inventing a tighter box the geometry does not state. + let minX = Number.POSITIVE_INFINITY; + let minY = Number.POSITIVE_INFINITY; + let maxX = Number.NEGATIVE_INFINITY; + let maxY = Number.NEGATIVE_INFINITY; + const include = (x: number, y: number): void => { + minX = Math.min(minX, x); + minY = Math.min(minY, y); + maxX = Math.max(maxX, x); + maxY = Math.max(maxY, y); + }; + for (const subpath of item.subpaths) { + include(subpath.startXPt, subpath.startYPt); + for (const segment of subpath.segments) { + include(segment.xPt, segment.yPt); + if (segment.kind === "cubic") { + include(segment.c1xPt, segment.c1yPt); + include(segment.c2xPt, segment.c2yPt); + } + } + } + return { minX, minY, maxX, maxY }; +} + +// Whether an item's bounds touch the visible page rectangle at all — touching the boundary counts as visible (a hairline rule exactly on the crop edge shows); only an item whose whole extent lies strictly beyond the edge is not visible. +export function itemIntersectsVisibleRegion( + item: LayoutItem, + widthPt: number, + heightPt: number, +): boolean { + if (item.kind === "link" || item.kind === "internalLink") { + return true; + } + const bounds = contentItemBounds(item); + if (bounds === undefined) { + return true; + } + return ( + bounds.maxX >= 0 && + bounds.minX <= widthPt && + bounds.maxY >= 0 && + bounds.minY <= heightPt + ); +} diff --git a/packages/pdf-codec/src/raster.ts b/packages/pdf-codec/src/raster.ts index 7019e63c9c..6c5d7d6c2b 100644 --- a/packages/pdf-codec/src/raster.ts +++ b/packages/pdf-codec/src/raster.ts @@ -30,7 +30,7 @@ import { multiplyMatrices, translationMatrix, } from "./matrix"; -import { normalizeRotation, pageRotationTransform } from "./read"; +import { normalizeRotation, pageRotationTransform } from "./page-frame"; import type { PdfDict } from "./objects"; import { asArray, asNumber, dictGet } from "./objects"; import { readOptionalContent } from "./optional-content"; diff --git a/packages/pdf-codec/src/read-convert.ts b/packages/pdf-codec/src/read-convert.ts index ba4ab558d1..76d99ac415 100644 --- a/packages/pdf-codec/src/read-convert.ts +++ b/packages/pdf-codec/src/read-convert.ts @@ -301,6 +301,16 @@ export function imagePlacementFrom(matrix: Matrix): { const HEX_RADIX = 16; +/** + * The id a read names a decoded image by in its registry. + * @param bytes - The image's decoded canonical bytes (PNG, or the JPEG passed through). + * @returns `img` and the bytes' CRC-32 in hexadecimal. + */ +export function imageIdOf(bytes: Uint8Array): string { + // The imageId is a crc32 of the DECODED canonical bytes (a JBIG2/JPX original must not fold into it: two different producers' compressed streams of the same raster content would then mint two ids for what every consumer sees as the same image, while a re-encoded canonical would mint a different id than the source's own re-read of the same file produced before this write — the canonical is the identity, the original is a re-emission spelling of it). + return `img${crc32(bytes).toString(HEX_RADIX)}`; +} + export function registerExtractedImage( format: "png" | "jpeg", bytes: Uint8Array, @@ -309,8 +319,7 @@ export function registerExtractedImage( images: Record, original: ExtractedPdfImage["original"], ): string { - // The imageId is a crc32 of the DECODED canonical bytes (a JBIG2/JPX original must not fold into it: two different producers' compressed streams of the same raster content would then mint two ids for what every consumer sees as the same image, while a re-encoded canonical would mint a different id than the source's own re-read of the same file produced before this write — the canonical is the identity, the original is a re-emission spelling of it). - const imageId = `img${crc32(bytes).toString(HEX_RADIX)}`; + const imageId = imageIdOf(bytes); if (!(imageId in images)) { images[imageId] = { format, diff --git a/packages/pdf-codec/src/read-graph.test.ts b/packages/pdf-codec/src/read-graph.test.ts index 11e548a37c..79b6309468 100644 --- a/packages/pdf-codec/src/read-graph.test.ts +++ b/packages/pdf-codec/src/read-graph.test.ts @@ -133,6 +133,22 @@ describe("the read path module graph excludes the write path and font assets", ( ).toEqual([]); }); + it("src/read-images.ts (the per-image reader) reaches neither the write path nor readPdf's text pipeline", () => { + const root = join(SRC_DIR, "read-images.ts"); + const reachable = reachableModules(root); + // The text pipeline (read.ts and the font resolution it drives, with its glyph tables) costs a Worker isolate about 12 MB of heap to load, and the per-image reader never shows text. + const textPipeline = new Set( + ["read.ts", "font-read.ts"].map((file) => join(SRC_DIR, file)), + ); + const forbidden = [...reachable.keys()].filter( + (module) => isForbidden(module) || textPipeline.has(module), + ); + expect( + forbidden.map((module) => chainTo(root, module, reachable)), + `the per-image reader's module graph must not reach the write path, the vendored font assets or the text pipeline; offending chain(s):\n ${forbidden.map((module) => chainTo(root, module, reachable)).join("\n ")}`, + ).toEqual([]); + }); + it("the package.json ./read export maps onto the read module, pinning the read-only entry", () => { const parsed: unknown = JSON.parse( readFileSync(join(SRC_DIR, "..", "package.json"), "utf8"), diff --git a/packages/pdf-codec/src/read-images.test.ts b/packages/pdf-codec/src/read-images.test.ts new file mode 100644 index 0000000000..11e4e5a38b --- /dev/null +++ b/packages/pdf-codec/src/read-images.test.ts @@ -0,0 +1,286 @@ +import { base64ToBytes } from "byte-codec"; +import { beforeEach, describe, expect, it, vi } from "vitest"; +import type * as ImagesRead from "./images-read"; +import { sha256 } from "./crypto/sha2"; +import type { PdfDiagnostic } from "./diagnostics"; +import { PdfImageLocatorError, PdfPageSelectionError } from "./diagnostics"; +import { readImageXObject } from "./images-read"; +import type { LayoutDocument } from "./layout"; +import { readPdf } from "./read"; +import type { PdfImageEntry, PdfImageLocator } from "./read-images"; +import { decodePdfImage, listPdfImages, openPdfImages } from "./read-images"; +import { + imageVarietyPdf, + pictureDeckPdf, +} from "./test-support/image-heavy-pdf"; +import { + IMAGE_VARIETY_4_5_2, + PICTURE_DECK_QUARTER_4_5_2, +} from "./test-support/image-heavy-pdf-golden"; + +// Observed, not stubbed: the real decoder still runs, so a test can count how many images a call decoded. +vi.mock("./images-read", async (importOriginal) => { + const actual = await importOriginal(); + return { ...actual, readImageXObject: vi.fn(actual.readImageXObject) }; +}); + +beforeEach(() => { + vi.mocked(readImageXObject).mockClear(); +}); + +function hex(bytes: Uint8Array): string { + return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join( + "", + ); +} + +function digest(bytes: Uint8Array): string { + return hex(sha256(bytes)); +} + +function locatorKey(locator: PdfImageLocator): string { + return locator.kind === "xobject" + ? `${String(locator.objectNumber)} ${String(locator.generation)} R` + : `inline ${String(locator.pageIndex)}#${String(locator.occurrence)}`; +} + +// The imageIds readPdf's page items name: an image registered but drawn only where nothing is visible is in the registry and on no page. +function drawnImageIds(doc: LayoutDocument): Set { + return new Set( + doc.pages.flatMap((page) => + page.items.flatMap((item) => + item.kind === "image" ? [item.imageId] : [], + ), + ), + ); +} + +const variety = imageVarietyPdf(); + +describe("listPdfImages", () => { + it("lists every visible image once, by reference, without decoding any of them", () => { + const diagnostics: PdfDiagnostic[] = []; + const listing = listPdfImages(variety, { + sink: (diagnostic) => { + diagnostics.push(diagnostic); + }, + }); + expect(readImageXObject).not.toHaveBeenCalled(); + // The 16-bit image is listed, though decoding it would report image/unsupported-bit-depth: nothing was decoded, so nothing was reported. + expect(diagnostics).toEqual([]); + expect(listing.map((entry) => locatorKey(entry.locator))).toEqual([ + "3 0 R", // Flate RGB with a soft mask (its soft mask is object 4) + "5 0 R", // inverted gray + "6 0 R", // indexed + "7 0 R", // 1-bit + "8 0 R", // CMYK + "9 0 R", // JPEG + "10 0 R", // ICC RGB under a PNG predictor + "13 0 R", // 16-bit, which no decoder reads + "14 0 R", // drawn inside a form XObject + "inline 1#0", + ]); + // Never listed: the /ImageMask stencil (object 11), which neither readPdf nor this reader reports as an image, and object 12, drawn only outside its page's crop box. + }); + + it("reports what each image's dictionary states", () => { + const [softMasked, , , oneBit, , jpeg] = listPdfImages(variety); + expect(softMasked).toMatchObject({ + widthPx: 64, + heightPx: 48, + filters: ["FlateDecode"], + softMask: true, + }); + expect(oneBit).toMatchObject({ + widthPx: 50, + heightPx: 20, + filters: [], + softMask: false, + encodedByteLength: 140, + }); + expect(jpeg).toMatchObject({ filters: ["DCTDecode"], softMask: false }); + }); + + it("places each image exactly where readPdf places its items, on every page that draws it", () => { + const doc = readPdf(variety); + const images = openPdfImages(variety); + for (const entry of images.list()) { + const decoded = images.decode(entry.locator); + if (decoded === undefined) { + continue; + } + const expected = doc.pages.flatMap((page, pageIndex) => + page.items.flatMap((item) => + item.kind === "image" && item.imageId === decoded.imageId + ? [ + { + pageIndex, + xPt: item.xPt, + yPt: item.yPt, + widthPt: item.widthPt, + heightPt: item.heightPt, + ...(item.rotationDeg !== undefined + ? { rotationDeg: item.rotationDeg } + : {}), + ...(item.layer !== undefined ? { layer: item.layer } : {}), + }, + ] + : [], + ), + ); + expect(entry.placements, locatorKey(entry.locator)).toEqual(expected); + } + }); + + it("collects every place one image XObject is drawn, across pages, including a rotated and cropped one", () => { + const [softMasked] = listPdfImages(variety); + expect(softMasked?.placements.map((p) => p.pageIndex)).toEqual([0, 0, 1]); + // Page 1 is rotated a quarter turn, so the image drawn on it is too. + expect(softMasked?.placements[2]?.rotationDeg).toBe(-90); + }); + + it("lists the selected pages only", () => { + const lastPage = listPdfImages(variety, { pages: [-1] }); + expect(lastPage.map((entry) => locatorKey(entry.locator))).toEqual([ + "3 0 R", + "inline 1#0", + ]); + expect(lastPage.flatMap((entry) => entry.placements)).toHaveLength(2); + expect(listPdfImages(variety, { pages: [] })).toEqual([]); + expect(() => listPdfImages(variety, { pages: [2] })).toThrow( + PdfPageSelectionError, + ); + }); + + it("states the page count, and stops at an aborted signal", () => { + expect(openPdfImages(variety).pageCount).toBe(2); + const controller = new AbortController(); + controller.abort(); + expect(() => + listPdfImages(variety, { signal: controller.signal }), + ).toThrow(); + }); +}); + +describe("decodePdfImage", () => { + it("decodes one image per call", () => { + const [, gray] = listPdfImages(variety); + const decoded = decodePdfImage(variety, gray!.locator); + expect(readImageXObject).toHaveBeenCalledTimes(1); + expect(decoded).toMatchObject({ format: "png", widthPx: 40, heightPx: 30 }); + }); + + it("decodes each image to exactly the bytes, format, size and id readPdf registers for it", () => { + const doc = readPdf(variety); + const images = openPdfImages(variety); + const decodedIds = new Set(); + for (const entry of images.list()) { + const decoded = images.decode(entry.locator); + if (decoded === undefined) { + continue; + } + decodedIds.add(decoded.imageId); + const asset = doc.images[decoded.imageId]; + expect(asset, locatorKey(entry.locator)).toBeDefined(); + expect(asset?.format).toBe(decoded.format); + expect(asset?.widthPx).toBe(decoded.widthPx); + expect(asset?.heightPx).toBe(decoded.heightPx); + expect(hex(base64ToBytes(asset!.base64))).toBe(hex(decoded.bytes)); + // The standalone call opens the file afresh and still decodes the same bytes. + expect(hex(decodePdfImage(variety, entry.locator)!.bytes)).toBe( + hex(decoded.bytes), + ); + } + expect(decodedIds).toEqual(drawnImageIds(doc)); + }); + + it("leaves out an image readPdf leaves out, with the same diagnostic", () => { + const unsupported = listPdfImages(variety).find( + (entry: PdfImageEntry) => + entry.locator.kind === "xobject" && entry.locator.objectNumber === 13, + ); + const diagnostics: PdfDiagnostic[] = []; + expect( + decodePdfImage(variety, unsupported!.locator, { + sink: (diagnostic) => { + diagnostics.push(diagnostic); + }, + }), + ).toBeUndefined(); + expect(diagnostics.map((diagnostic) => diagnostic.code)).toEqual([ + "image/unsupported-bit-depth", + ]); + }); + + it("refuses a locator that names no image of the document", () => { + const images = openPdfImages(variety); + // Object 1 is the catalog; object 99 does not exist; the form XObject is a stream, but not an image. + for (const objectNumber of [1, 99, 16]) { + expect(() => + images.decode({ kind: "xobject", objectNumber, generation: 0 }), + ).toThrow(PdfImageLocatorError); + } + expect(() => + images.decode({ kind: "inline", pageIndex: 1, occurrence: 1 }), + ).toThrow(PdfImageLocatorError); + expect(() => + images.decode({ kind: "inline", pageIndex: 0, occurrence: 0 }), + ).toThrow(PdfImageLocatorError); + expect(() => + images.decode({ kind: "inline", pageIndex: 5, occurrence: 0 }), + ).toThrow(PdfPageSelectionError); + }); +}); + +// The decoded bytes every image stored before pdf-codec 5 was produced from: per-image decoding must reproduce 4.5.2's output exactly, or every re-read image would mint a new blob. +describe("per-image decoding reproduces pdf-codec 4.5.2's decoded images byte for byte", () => { + it.each([ + ["the variety fixture", variety, IMAGE_VARIETY_4_5_2], + [ + "the picture-deck fixture at quarter scale", + pictureDeckPdf({ scale: 0.25 }), + PICTURE_DECK_QUARTER_4_5_2, + ], + ] as const)("%s", (_name, pdf, golden) => { + const images = openPdfImages(pdf); + const decoded = new Map(); + for (const entry of images.list()) { + const image = images.decode(entry.locator); + if (image !== undefined) { + decoded.set(image.imageId, digest(image.bytes)); + } + } + const drawn = drawnImageIds(readPdf(pdf)); + expect(Object.fromEntries(decoded)).toEqual( + Object.fromEntries( + Object.entries(golden).filter(([imageId]) => drawn.has(imageId)), + ), + ); + }); + + it("and readPdf still registers exactly 4.5.2's images", () => { + const doc = readPdf(variety); + expect( + Object.fromEntries( + Object.entries(doc.images).map(([imageId, asset]) => [ + imageId, + digest(base64ToBytes(asset.base64)), + ]), + ), + ).toEqual(IMAGE_VARIETY_4_5_2); + }); +}); + +describe("the picture-deck fixture", () => { + it("has the shape of the picture-heavy deck it stands in for", () => { + const listing = listPdfImages(pictureDeckPdf({ scale: 0.25 })); + expect(listing).toHaveLength(108); + expect( + listing.filter((entry) => entry.filters[0] === "DCTDecode"), + ).toHaveLength(27); + expect(listing.filter((entry) => entry.softMask).length).toBeGreaterThan( + 50, + ); + expect(listing.some((entry) => entry.placements.length > 1)).toBe(true); + }); +}); diff --git a/packages/pdf-codec/src/read-images.ts b/packages/pdf-codec/src/read-images.ts new file mode 100644 index 0000000000..628ceac57d --- /dev/null +++ b/packages/pdf-codec/src/read-images.ts @@ -0,0 +1,413 @@ +import type { PdfDiagnosticSink } from "./diagnostics"; +import { NOOP_DIAGNOSTIC_SINK, PdfImageLocatorError } from "./diagnostics"; +import { openPdfDocument } from "./document"; +import type { PdfDocument } from "./document"; +import { filterNames } from "./filters"; +import type { ExtractedPdfImage } from "./images-read"; +import { readImageXObject } from "./images-read"; +import { interpretContentStream } from "./interpret"; +import type { + ExtractedItem, + FontMetricsPort, + InterpretContext, +} from "./interpret-types"; +import { multiplyMatrices } from "./matrix"; +import type { Matrix } from "./matrix"; +import type { PdfDict, PdfObject } from "./objects"; +import { asBool, asName, asNumber, dictGet } from "./objects"; +import { readOptionalContent } from "./optional-content"; +import { + itemIntersectsVisibleRegion, + readPageContentBytes, + readPageFrame, +} from "./page-frame"; +import { imageIdOf, imagePlacementFrom } from "./read-convert"; +import { hasPdfHeader, resolvePageSelection } from "./read-open"; +import { PdfParseError } from "./diagnostics"; +import { throwIfAborted } from "./util/abort"; + +// The image registry readPdf builds, taken apart into its two halves so a memory-capped caller (a Worker isolate shelving a picture-heavy PDF) can pay for one image at a time: listing finds every image a page draws, where it draws it, and the reference that names it, without decoding any image stream; decoding turns one image, named by that reference, into exactly the bytes readPdf's registry holds for it (the same readImageXObject call on the same stream), without interpreting any page again. readPdf decodes every image during its one pass and keeps each as a base64 string, so its memory grows with the number of images; here nothing outlives the call that decoded it. + +/** + * Names one image of a PDF, as `listPdfImages` reports it and `decodePdfImage` takes it back. Plain data, so a caller can store it and decode the image in a later call (or a later process) against the same file bytes. + * + * - `xobject`: an image XObject, by its indirect object reference. One entry covers every place the document draws it. + * - `inline`: an inline image (`BI` ... `ID` ... `EI`), which has no object of its own, by its page and its position among that page's inline images in content-stream order (counted from 0, every inline image counted, including ones the listing leaves out). Decoding one interprets that page's content again to find it; inline images are small by design (ISO 32000-1 8.9.7 recommends at most 4 KB), and producers rarely write them. + */ +export type PdfImageLocator = + | { + readonly kind: "xobject"; + readonly objectNumber: number; + readonly generation: number; + } + | { + readonly kind: "inline"; + readonly pageIndex: number; + readonly occurrence: number; + }; + +/** One place a page draws an image: the same placement fields a `readPdf` image item carries, in the same page coordinates. */ +export interface PdfImagePlacement { + /** The page's zero-based source index. */ + readonly pageIndex: number; + readonly xPt: number; + readonly yPt: number; + readonly widthPt: number; + readonly heightPt: number; + readonly rotationDeg?: number; + /** The optional-content layer the image is drawn in, as `readPdf` names it. */ + readonly layer?: string; +} + +/** One image a PDF draws, read from its dictionary alone: nothing here required decoding the image's stream. */ +export interface PdfImageEntry { + readonly locator: PdfImageLocator; + /** `/Width` and `/Height` as the dictionary declares them; absent when it declares none (a JPEG 2000 image's codestream states its own). */ + readonly widthPx?: number; + readonly heightPx?: number; + /** The stream's `/Filter` names in the order they apply, as written (an inline image may use the abbreviated names). */ + readonly filters: readonly string[]; + /** Whether the image names a soft mask (`/SMask`), which decoding composites in as an alpha channel. */ + readonly softMask: boolean; + /** The length of the image's stream as stored in the file, before any filter is undone. */ + readonly encodedByteLength: number; + /** Every visible place the listed pages draw it, in page order and then content-stream order. */ + readonly placements: readonly PdfImagePlacement[]; +} + +/** One image decoded: exactly the bytes, format and size `readPdf`'s registry holds for it, and the id `readPdf` names it by. */ +export interface DecodedPdfImage extends ExtractedPdfImage { + /** `img` and the CRC-32 of `bytes`, the key `readPdf` registers the image under in `LayoutDocument.images`. */ + readonly imageId: string; +} + +export interface PdfImageReadOptions { + /** Receives every recoverable diagnostic, as `readPdf`'s sink does. */ + readonly sink?: PdfDiagnosticSink; + /** Checked before the document is opened, before each listed page, and before each decode. */ + readonly signal?: AbortSignal; +} + +export interface ListPdfImagesOptions { + /** The pages to list images from, exactly as `ReadPdfOptions.pages` takes them (negative indices from the end; an entry naming no page throws `PdfPageSelectionError`). Omitted, every page is listed. */ + readonly pages?: readonly number[]; +} + +/** One opened PDF's images. Listing and decoding share the opened document, so its cross-reference table and object streams are parsed once however many images are decoded. */ +export interface PdfImages { + /** The number of pages in the document's page tree. */ + readonly pageCount: number; + /** + * Lists the images the selected pages draw, without decoding any of them. + * @param options - Which pages to list. + * @returns One entry per image XObject drawn (in the order first drawn), and one per inline image, each with every visible placement. + */ + list: (options?: ListPdfImagesOptions) => PdfImageEntry[]; + /** + * Decodes one image. + * @param locator - The image, as a listing of this same file named it. + * @returns The image, or undefined for one `readPdf` would leave out of its registry too (an `/ImageMask` stencil, an unsupported filter, colour space or bit depth, an invalid size, or an undecodable stream), with the same diagnostic `readPdf` reports for it. + * @throws PdfImageLocatorError if the locator names no image of this document. + */ + decode: (locator: PdfImageLocator) => DecodedPdfImage | undefined; +} + +// Listing places images and never shows text, so the interpreter's text advances only have to keep it moving: an image's placement is the CTM at its Do, which no text operator changes. Answering every glyph with a zero advance spares resolving, and parsing the program of, every font a page uses. +const PLACEMENT_ONLY_FONT_METRICS: FontMetricsPort = { + glyphAdvance: () => ({ widthPer1000: 0, byteLengthConsumed: 1 }), + isVertical: () => false, +}; + +function isImageMask(dict: PdfDict): boolean { + return asBool(dictGet(dict, "ImageMask") ?? dictGet(dict, "IM")) === true; +} + +// A page's content as the interpreter extracts it, with the matrix that places it on the page and the page's visible size. Undefined for a page with no /Resources, which readPdf interprets no content for either. +function interpretPage( + doc: PdfDocument, + pageIndex: number, + page: PdfDict, + layerNameOf: InterpretContext["layerNameOf"], + sink: PdfDiagnosticSink, +): + | { + readonly items: ExtractedItem[]; + readonly pageMatrix: Matrix; + readonly widthPt: number; + readonly heightPt: number; + } + | undefined { + const resources = doc.resolveDict(dictGet(page, "Resources")); + if (resources === undefined) { + return undefined; + } + const frame = readPageFrame(pageIndex, page, sink); + const items = interpretContentStream( + readPageContentBytes(page, doc, sink), + resources, + { + fontMetrics: PLACEMENT_ONLY_FONT_METRICS, + resolver: doc, + sink, + ...(layerNameOf !== undefined ? { layerNameOf } : {}), + }, + ); + return { items, ...frame }; +} + +// Where an image item lands, or undefined when it lies wholly outside the visible region, which readPdf drops too. +function visiblePlacement( + pageIndex: number, + matrix: Matrix, + layerName: string | undefined, + page: { + readonly pageMatrix: Matrix; + readonly widthPt: number; + readonly heightPt: number; + }, +): PdfImagePlacement | undefined { + const { rotationDeg, ...frame } = imagePlacementFrom( + multiplyMatrices(matrix, page.pageMatrix), + ); + const visible = itemIntersectsVisibleRegion( + { kind: "image", imageId: "", ...frame }, + page.widthPt, + page.heightPt, + ); + if (!visible) { + return undefined; + } + return { + pageIndex, + ...frame, + ...(rotationDeg !== undefined ? { rotationDeg } : {}), + ...(layerName !== undefined ? { layer: layerName } : {}), + }; +} + +function entryFacts( + dict: PdfDict, + encodedByteLength: number, +): Omit { + const widthPx = asNumber(dictGet(dict, "Width") ?? dictGet(dict, "W")); + const heightPx = asNumber(dictGet(dict, "Height") ?? dictGet(dict, "H")); + return { + ...(widthPx !== undefined ? { widthPx } : {}), + ...(heightPx !== undefined ? { heightPx } : {}), + filters: filterNames(dict), + softMask: dictGet(dict, "SMask") !== undefined, + encodedByteLength, + }; +} + +// The reference a page's /XObject resource names an image by. Undefined for a direct (unreferenced) entry, which ISO 32000-1 7.3.8.1 rules out for a stream. +function xobjectReference( + doc: PdfDocument, + resources: PdfDict, + resourceName: string, +): Extract | undefined { + const xobjects = doc.resolveDict(dictGet(resources, "XObject")); + const entry = + xobjects === undefined ? undefined : dictGet(xobjects, resourceName); + return entry?.kind === "ref" ? entry : undefined; +} + +function listImages( + doc: PdfDocument, + pageDicts: readonly PdfDict[], + options: ListPdfImagesOptions | undefined, + signal: AbortSignal | undefined, + sink: PdfDiagnosticSink, +): PdfImageEntry[] { + const selection = + options?.pages === undefined + ? undefined + : resolvePageSelection(options.pages, pageDicts.length); + const { layerNameOf } = readOptionalContent(doc.catalog, doc, sink); + const entries: PdfImageEntry[] = []; + // Each image XObject's entry, by object number, with the placements still being collected into it. + const xobjects = new Map(); + pageDicts.forEach((page, pageIndex) => { + if (selection !== undefined && !selection.has(pageIndex)) { + return; + } + throwIfAborted(signal); + const interpreted = interpretPage(doc, pageIndex, page, layerNameOf, sink); + if (interpreted === undefined) { + return; + } + let occurrence = 0; + for (const item of interpreted.items) { + if (item.kind === "inlineImage") { + const locator: PdfImageLocator = { + kind: "inline", + pageIndex, + occurrence: occurrence++, + }; + const placement = visiblePlacement( + pageIndex, + item.matrix, + item.layerName, + interpreted, + ); + if (placement !== undefined && !isImageMask(item.dict)) { + entries.push({ + locator, + ...entryFacts(item.dict, item.data.length), + placements: [placement], + }); + } + continue; + } + if (item.kind !== "image") { + continue; + } + const ref = xobjectReference(doc, item.resources, item.resourceName); + const stream = ref === undefined ? undefined : doc.resolve(ref); + if ( + ref === undefined || + stream?.kind !== "stream" || + isImageMask(stream.dict) + ) { + continue; + } + const placement = visiblePlacement( + pageIndex, + item.matrix, + item.layerName, + interpreted, + ); + if (placement === undefined) { + continue; + } + const placements = xobjects.get(ref.num); + if (placements !== undefined) { + placements.push(placement); + continue; + } + const collected = [placement]; + xobjects.set(ref.num, collected); + entries.push({ + locator: { + kind: "xobject", + objectNumber: ref.num, + generation: ref.gen, + }, + ...entryFacts(stream.dict, stream.raw.length), + placements: collected, + }); + } + }); + return entries; +} + +function decodeImage( + doc: PdfDocument, + pageDicts: readonly PdfDict[], + locator: PdfImageLocator, + sink: PdfDiagnosticSink, +): DecodedPdfImage | undefined { + let extracted: ExtractedPdfImage | undefined; + if (locator.kind === "xobject") { + const stream = doc.resolve({ + kind: "ref", + num: locator.objectNumber, + gen: locator.generation, + }); + // The interpreter draws an XObject as an image exactly when its /Subtype says so, so that is what a locator must name. + if ( + stream?.kind !== "stream" || + asName(dictGet(stream.dict, "Subtype")) !== "Image" + ) { + throw new PdfImageLocatorError( + locator, + `object ${String(locator.objectNumber)} ${String(locator.generation)} R is not an image XObject stream of this document`, + ); + } + extracted = readImageXObject(stream.dict, stream.raw, doc, sink); + } else { + // The page index is resolved like a one-page selection, so a locator naming no page throws PdfPageSelectionError as a selection would. + const [pageIndex = 0] = resolvePageSelection( + [locator.pageIndex], + pageDicts.length, + ); + const page = pageDicts[pageIndex]; + const inline = + page === undefined + ? undefined + : interpretPage(doc, pageIndex, page, undefined, sink)?.items.filter( + (item) => item.kind === "inlineImage", + )[locator.occurrence]; + if (inline === undefined) { + throw new PdfImageLocatorError( + locator, + `page ${String(locator.pageIndex)} holds no inline image at occurrence ${String(locator.occurrence)}`, + ); + } + extracted = readImageXObject(inline.dict, inline.data, doc, sink); + } + return extracted === undefined + ? undefined + : { ...extracted, imageId: imageIdOf(extracted.bytes) }; +} + +/** + * Opens a PDF for reading its images one at a time. + * @param bytes - The PDF file. + * @param options - A diagnostic sink and an abort signal. + * @returns The document's images, listed and decoded on request. + * @throws PdfParseError (or a subclass) for a file that cannot be opened at all, as `readPdf` does. + */ +export function openPdfImages( + bytes: Uint8Array, + options?: PdfImageReadOptions, +): PdfImages { + const sink = options?.sink ?? NOOP_DIAGNOSTIC_SINK; + const signal = options?.signal; + if (!hasPdfHeader(bytes)) { + throw new PdfParseError( + "pdf/no-header", + 'no "%PDF-" header found within the first bytes of the file; this does not look like a PDF at all', + ); + } + throwIfAborted(signal); + const doc = openPdfDocument(bytes, sink); + const pageDicts = doc.pages(); + return { + pageCount: pageDicts.length, + list: (listOptions) => + listImages(doc, pageDicts, listOptions, signal, sink), + decode: (locator) => { + throwIfAborted(signal); + return decodeImage(doc, pageDicts, locator, sink); + }, + }; +} + +/** + * Lists the images a PDF's pages draw, by reference and with their placements, without decoding any image stream or keeping any image's bytes. + * @param bytes - The PDF file. + * @param options - Which pages to list, a diagnostic sink and an abort signal. + * @returns One entry per image (see `PdfImages.list`). + */ +export function listPdfImages( + bytes: Uint8Array, + options?: PdfImageReadOptions & ListPdfImagesOptions, +): PdfImageEntry[] { + return openPdfImages(bytes, options).list(options); +} + +/** + * Decodes one image of a PDF, named by a locator a listing of the same file returned, without interpreting any page (except an inline image's own page). + * @param bytes - The PDF file. + * @param locator - The image. + * @param options - A diagnostic sink and an abort signal. + * @returns The image, byte-identical to `readPdf`'s registry entry for it, or undefined for one `readPdf` would leave out (see `PdfImages.decode`). + */ +export function decodePdfImage( + bytes: Uint8Array, + locator: PdfImageLocator, + options?: PdfImageReadOptions, +): DecodedPdfImage | undefined { + return openPdfImages(bytes, options).decode(locator); +} diff --git a/packages/pdf-codec/src/read-open.ts b/packages/pdf-codec/src/read-open.ts new file mode 100644 index 0000000000..5cb6cde899 --- /dev/null +++ b/packages/pdf-codec/src/read-open.ts @@ -0,0 +1,39 @@ +import { PdfPageSelectionError } from "./diagnostics"; + +// What every whole-document reader (readPdf, and read-images.ts's image listing) checks before it reads a page, split from read.ts so both check it the same way. + +// Resolves a page selection against the page tree's length: negative indices counted from the end, duplicates collapsed, and the result as a set, since a reader walks the tree in document order and asks it per page. Throws on the first entry that names no page, before any page is read. +export function resolvePageSelection( + selection: readonly number[], + pageCount: number, +): ReadonlySet { + const resolved = new Set(); + for (const requested of selection) { + const index = requested < 0 ? pageCount + requested : requested; + if (!Number.isInteger(requested) || index < 0 || index >= pageCount) { + throw new PdfPageSelectionError(requested, pageCount); + } + resolved.add(index); + } + return resolved; +} + +const PDF_HEADER_BYTES = new TextEncoder().encode("%PDF-"); +// Real producers occasionally prepend a small amount of junk (a UTF-8 BOM, blank lines) before the header — ISO 32000-1 7.5.2 itself permits leading bytes before "%PDF-", so this scans a window rather than requiring it at offset 0. +const HEADER_SEARCH_WINDOW = 1024; + +export function hasPdfHeader(bytes: Uint8Array): boolean { + const window = bytes.subarray( + 0, + Math.min(HEADER_SEARCH_WINDOW, bytes.length), + ); + outer: for (let i = 0; i <= window.length - PDF_HEADER_BYTES.length; i++) { + for (let j = 0; j < PDF_HEADER_BYTES.length; j++) { + if (window[i + j] !== PDF_HEADER_BYTES[j]) { + continue outer; + } + } + return true; + } + return false; +} diff --git a/packages/pdf-codec/src/read.ts b/packages/pdf-codec/src/read.ts index b46639ac12..4155a77961 100644 --- a/packages/pdf-codec/src/read.ts +++ b/packages/pdf-codec/src/read.ts @@ -1,4 +1,3 @@ -import { concatBytes } from "./bytes/writer"; import { readPageAnnotations } from "./annotations"; import type { ImageRegistry } from "./read-convert"; import { @@ -23,30 +22,30 @@ import { LAYOUT_FORMAT_VERSION, LayoutDocumentSurfaceSchema } from "./layout"; import { openPdfDocument } from "./document"; import type { PdfDocument } from "./document"; import type { PdfDiagnosticSink } from "./diagnostics"; -import { - NOOP_DIAGNOSTIC_SINK, - PdfPageSelectionError, - PdfParseError, -} from "./diagnostics"; +import { NOOP_DIAGNOSTIC_SINK, PdfParseError } from "./diagnostics"; +import { hasPdfHeader, resolvePageSelection } from "./read-open"; import { decodeStream } from "./filters"; import { throwIfAborted } from "./util/abort"; import type { FontResolverService } from "./font-read"; import { createFontResolver } from "./font-read"; import type { PdfObjectResolver } from "./interpret-types"; import { interpretContentStream } from "./interpret"; -import type { Matrix } from "./matrix"; +import type { PageBoxRect } from "./page-frame"; +import { + itemIntersectsVisibleRegion, + readPageContentBytes, + readPageFrame, +} from "./page-frame"; +import type { PageRotation, PageRotationResult } from "./page-frame"; import { - applyMatrix, - multiplyMatrices, - rotatePointAboutCenter, - translationMatrix, -} from "./matrix"; + normalizeRotation as normalizePageRotation, + pageRotationTransform as pageRotationMatrix, +} from "./page-frame"; import type { DestinationRegistry } from "./navigation"; import { createDestinationRegistry, readOutline } from "./navigation"; import type { PdfDict, PdfObject } from "./objects"; import { asArray, - asNumber, dictGet, pdfArray, pdfDict, @@ -113,45 +112,6 @@ const UNREAD_DESTINATION_REGISTRY: DestinationRegistry = { intern: () => undefined, }; -// Resolves a page selection against the page tree's length: negative indices counted from the end, duplicates collapsed, and the result as a set, since readPdf walks the tree in document order and asks it per page. Throws on the first entry that names no page, before any page is read. -function resolvePageSelection( - selection: readonly number[], - pageCount: number, -): ReadonlySet { - const resolved = new Set(); - for (const requested of selection) { - const index = requested < 0 ? pageCount + requested : requested; - if (!Number.isInteger(requested) || index < 0 || index >= pageCount) { - throw new PdfPageSelectionError(requested, pageCount); - } - resolved.add(index); - } - return resolved; -} - -const PDF_HEADER_BYTES = new TextEncoder().encode("%PDF-"); -// Real producers occasionally prepend a small amount of junk (a UTF-8 BOM, blank lines) before the header — ISO 32000-1 7.5.2 itself permits leading bytes before "%PDF-", so this scans a window rather than requiring it at offset 0. -const HEADER_SEARCH_WINDOW = 1024; -// US Letter (ISO 32000-1's own example default, and the overwhelming common fallback in practice): used only when a page has no /MediaBox at all, even after page-tree inheritance — a genuinely malformed file. -const DEFAULT_PAGE_WIDTH_PT = 612; -const DEFAULT_PAGE_HEIGHT_PT = 792; - -function hasPdfHeader(bytes: Uint8Array): boolean { - const window = bytes.subarray( - 0, - Math.min(HEADER_SEARCH_WINDOW, bytes.length), - ); - outer: for (let i = 0; i <= window.length - PDF_HEADER_BYTES.length; i++) { - for (let j = 0; j < PDF_HEADER_BYTES.length; j++) { - if (window[i + j] !== PDF_HEADER_BYTES[j]) { - continue outer; - } - } - return true; - } - return false; -} - export function readPdf( bytes: Uint8Array, options?: ReadPdfOptions, @@ -284,272 +244,34 @@ function noStructureOwner(): undefined { // --- Page geometry: MediaBox origin shift + /Rotate, composed into one matrix applied to every extracted item on the page. --- -interface PageBoxRect { - readonly llx: number; - readonly lly: number; - readonly urx: number; - readonly ury: number; -} - -// One of the five page-boundary rectangles (ISO 32000-1 14.11.2), normalised to lower-left/upper-right corners — a producer may write either corner order. Undefined when the page does not declare the entry; only /MediaBox has a fallback (the malformed-file letter default below). -function readDeclaredPageBox( - page: PdfDict, - key: string, -): PageBoxRect | undefined { - const arr = asArray(dictGet(page, key)); - if (arr === undefined) { - return undefined; - } - const a = asNumber(arr[0]) ?? 0; - const b = asNumber(arr[1]) ?? 0; - const c = asNumber(arr[2]) ?? 0; - const d = asNumber(arr[3]) ?? 0; - return { - llx: Math.min(a, c), - lly: Math.min(b, d), - urx: Math.max(a, c), - ury: Math.max(b, d), - }; -} - -function readMediaBox(page: PdfDict): PageBoxRect { - return ( - readDeclaredPageBox(page, "MediaBox") ?? { - llx: 0, - lly: 0, - urx: DEFAULT_PAGE_WIDTH_PT, - ury: DEFAULT_PAGE_HEIGHT_PT, - } - ); -} - -// The axis-aligned bounds of a page rectangle after a rotation transform — all four corners transformed, then min/max, because a rotation that is not about the box's own corner does not preserve which corner is lower-left (and /Rotate's matrix is built for the media box's frame, not the crop box's). -interface RotatedRectBounds { - readonly minX: number; - readonly minY: number; - readonly maxX: number; - readonly maxY: number; -} - -function rotatedRectBounds( - rect: PageBoxRect, - matrix: Matrix, -): RotatedRectBounds { - const corners: readonly (readonly [number, number])[] = [ - [rect.llx, rect.lly], - [rect.urx, rect.lly], - [rect.llx, rect.ury], - [rect.urx, rect.ury], - ]; - const transformed = corners.map(([x, y]) => applyMatrix(matrix, { x, y })); - const xs = transformed.map((point) => point.x); - const ys = transformed.map((point) => point.y); - return { - minX: Math.min(...xs), - minY: Math.min(...ys), - maxX: Math.max(...xs), - maxY: Math.max(...ys), - }; -} - -type PageRotation = 0 | 90 | 180 | 270; -type NonZeroPageRotation = 90 | 180 | 270; - -// The three non-zero values ISO 32000-1 7.7.3.3's /Rotate can normalize to. -const QUARTER_TURN_DEG = 90; -const HALF_TURN_DEG = 180; -const THREE_QUARTER_TURN_DEG = 270; -const DEGREES_PER_TURN = 360; - -// A user-defined type guard, rather than a plain boolean check, because `PageRotation` needs `normalized` narrowed to `NonZeroPageRotation` below: comparing against QUARTER_TURN_DEG/HALF_TURN_DEG/THREE_QUARTER_TURN_DEG (typed as plain `number`, since that is what a bare `const` initializer widens to) would not narrow the way comparing against inline literals does, and this predicate's own declared return type supplies that narrowing instead. -function isNonZeroPageRotation(n: number): n is NonZeroPageRotation { - return ( - n === QUARTER_TURN_DEG || - n === HALF_TURN_DEG || - n === THREE_QUARTER_TURN_DEG - ); -} +// --- Page rotation: implemented in page-frame.ts (which the image listing loads without this module's text pipeline), and still served from here, where the pdf-codec/read entry has always exported them. --- +/** + * Normalizes a page's /Rotate to one of the four quarter turns (ISO 32000-1 7.7.3.3). + * @param rotate - The /Rotate value, if any. + * @returns 0, 90, 180 or 270. + */ export function normalizeRotation(rotate: number | undefined): PageRotation { - if (rotate === undefined) { - return 0; - } - const normalized = - (((Math.round(rotate / QUARTER_TURN_DEG) * QUARTER_TURN_DEG) % - DEGREES_PER_TURN) + - DEGREES_PER_TURN) % - DEGREES_PER_TURN; - return isNonZeroPageRotation(normalized) ? normalized : 0; + return normalizePageRotation(rotate); } -interface PageRotationResult { - readonly matrix: Matrix; - readonly widthPt: number; - readonly heightPt: number; -} - -// Each case derived and verified independently by tracking where all four MediaBox corners land after physically rotating the rendered page clockwise by the given angle (ISO 32000-1 7.7.3.3's own definition of /Rotate) — e.g. for 90, the original bottom-left corner (0,0) becomes the new page's top-left corner (0, w), and solving the resulting four-corner system gives (x,y) -> (y, w-x). +/** + * The matrix a page's /Rotate applies, for a media box `w` by `h` points, and the rotated page's size. + * @param rotation - A normalized rotation. + * @param w - The media box width. + * @param h - The media box height. + * @returns The matrix and the rotated size. + */ export function pageRotationTransform( rotation: PageRotation, w: number, h: number, ): PageRotationResult { - if (rotation === QUARTER_TURN_DEG) { - return { matrix: [0, -1, 1, 0, 0, w], widthPt: h, heightPt: w }; - } - if (rotation === HALF_TURN_DEG) { - return { matrix: [-1, 0, 0, -1, w, h], widthPt: w, heightPt: h }; - } - if (rotation === THREE_QUARTER_TURN_DEG) { - return { matrix: [0, 1, -1, 0, h, 0], widthPt: h, heightPt: w }; - } - return { matrix: [1, 0, 0, 1, 0, 0], widthPt: w, heightPt: h }; + return pageRotationMatrix(rotation, w, h); } // --- Page content: /Contents (single stream or array), interpretation, and per-item conversion into LayoutItem. --- -// ISO 32000-1 7.8.2: when /Contents is an array, readers must treat the concatenation of the referenced streams as if they were one stream, "as though they were preceded and followed by white-space characters". Inserted here as a defensive LINE FEED, so a token straddling the end of one chunk and the start of the next can never merge into one, even when a producer omitted trailing whitespace of its own. -const CONTENT_STREAM_JOIN_BYTE = 0x0a; - -function readPageContentBytes( - page: PdfDict, - resolver: Readonly, - sink: PdfDiagnosticSink, -): Uint8Array { - const contentsObj = resolver.resolve(dictGet(page, "Contents")); - if (contentsObj?.kind === "stream") { - return decodeStream(contentsObj.raw, contentsObj.dict, sink).bytes; - } - if (contentsObj?.kind === "array") { - const chunks: Uint8Array[] = []; - for (const item of contentsObj.items) { - const streamObj = resolver.resolve(item); - if (streamObj?.kind === "stream") { - chunks.push( - decodeStream(streamObj.raw, streamObj.dict, sink).bytes, - new Uint8Array([CONTENT_STREAM_JOIN_BYTE]), - ); - } - } - return concatBytes(chunks); - } - return new Uint8Array(0); -} - -// A content item's axis-aligned bounds in output page space — the crop-visibility filter's input. Link and internalLink kinds report undefined: an annotation is an anchored construct, not painted stream content, so the visibility filter must not claim it (the same line the optional-content filter draws, treating annotation kinds as not layer-governed content). -function contentItemBounds(item: LayoutItem): RotatedRectBounds | undefined { - if (item.kind === "link" || item.kind === "internalLink") { - return undefined; - } - const frameBounds = ( - xPt: number, - yPt: number, - widthPt: number, - heightPt: number, - ): RotatedRectBounds => ({ - minX: xPt, - minY: yPt, - maxX: xPt + widthPt, - maxY: yPt + heightPt, - }); - if ( - item.kind === "text" || - item.kind === "image" || - item.kind === "rect" || - item.kind === "ellipse" - ) { - if ( - item.kind !== "text" || - item.rotationDeg === undefined || - item.rotationDeg % HALF_TURN_DEG === 0 - ) { - // widthPt is optional on text (reported, not measured, on some paths) — a missing width still bounds the run to its anchor plus size, never an unbounded extent. - return frameBounds( - item.xPt, - item.yPt, - item.widthPt ?? 0, - item.kind === "text" ? item.sizePt : item.heightPt, - ); - } - // An obliquely rotated run's frame no longer bounds it: rotate the (width x size) frame's corners about the run's own anchor, which the conversion places invariantly, and take the hull. Generous by construction (the glyph ink stays within the em box), which errs toward keeping an edge-straddling run — the right direction for a visibility filter. - const rotationDeg = item.rotationDeg; - const anchorX = item.xPt; - const anchorY = item.yPt; - const corners: readonly (readonly [number, number])[] = [ - [0, 0], - [item.widthPt ?? 0, 0], - [0, item.sizePt], - [item.widthPt ?? 0, item.sizePt], - ]; - const rotated = corners.map(([dx, dy]) => - rotatePointAboutCenter( - { x: anchorX + dx, y: anchorY + dy }, - { x: anchorX, y: anchorY }, - rotationDeg, - ), - ); - const xs = rotated.map((point) => point.x); - const ys = rotated.map((point) => point.y); - return { - minX: Math.min(...xs), - minY: Math.min(...ys), - maxX: Math.max(...xs), - maxY: Math.max(...ys), - }; - } - if (item.kind === "line") { - return { - minX: Math.min(item.x1Pt, item.x2Pt), - minY: Math.min(item.y1Pt, item.y2Pt), - maxX: Math.max(item.x1Pt, item.x2Pt), - maxY: Math.max(item.y1Pt, item.y2Pt), - }; - } - // A path's bounds cover every subpath's start point, every segment endpoint, and every cubic control point — a Bezier can extend beyond its endpoint hull, and a visibility filter errs towards keeping, never towards inventing a tighter box the geometry does not state. - let minX = Number.POSITIVE_INFINITY; - let minY = Number.POSITIVE_INFINITY; - let maxX = Number.NEGATIVE_INFINITY; - let maxY = Number.NEGATIVE_INFINITY; - const include = (x: number, y: number): void => { - minX = Math.min(minX, x); - minY = Math.min(minY, y); - maxX = Math.max(maxX, x); - maxY = Math.max(maxY, y); - }; - for (const subpath of item.subpaths) { - include(subpath.startXPt, subpath.startYPt); - for (const segment of subpath.segments) { - include(segment.xPt, segment.yPt); - if (segment.kind === "cubic") { - include(segment.c1xPt, segment.c1yPt); - include(segment.c2xPt, segment.c2yPt); - } - } - } - return { minX, minY, maxX, maxY }; -} - -// Whether an item's bounds touch the visible page rectangle at all — touching the boundary counts as visible (a hairline rule exactly on the crop edge shows); only an item whose whole extent lies strictly beyond the edge is not visible. -function itemIntersectsVisibleRegion( - item: LayoutItem, - widthPt: number, - heightPt: number, -): boolean { - if (item.kind === "link" || item.kind === "internalLink") { - return true; - } - const bounds = contentItemBounds(item); - if (bounds === undefined) { - return true; - } - return ( - bounds.maxX >= 0 && - bounds.minX <= widthPt && - bounds.maxY >= 0 && - bounds.minY <= heightPt - ); -} - // One page's contribution to the package-level page-boxes residue row: the declared boundary rectangles that carry a fact beyond the visible one. A page contributes when a declared /CropBox differs from the media box (the outer region and the crop's own absolute position are both left behind by reading the visible box alone) or when any of /BleedBox /TrimBox /ArtBox is declared (print-production facts with no field in the layout model). Values are the parsed source arrays, serialised verbatim, so a same-format restorer re-emits exactly what the producer wrote. Undefined when the page's declarations carry nothing beyond the visible box. function pageBoxResidueEntry( pageIndex: number, @@ -605,29 +327,10 @@ function readPage( sink: PdfDiagnosticSink, ): ReadPage { const resources = resolver.resolveDict(dictGet(page, "Resources")); - const mediaBox = readMediaBox(page); - // The crop box is the visible region (ISO 32000-1 14.11.2: a viewer displays and prints it, and it defaults to the media box), so it — not the media box — is the page geometry this package reports, and content outside it is not visible at all. Inherited through the page tree like /MediaBox (one of 7.7.3.4's four inheritable attributes); /BleedBox /TrimBox /ArtBox are ordinary page-direct entries and are quarantined as residue, never clipped to. - let cropBox = readDeclaredPageBox(page, "CropBox") ?? mediaBox; - if (cropBox.urx - cropBox.llx <= 0 || cropBox.ury - cropBox.lly <= 0) { - sink({ - code: "pdf/invalid-crop-box", - severity: "warning", - pageIndex, - message: - "page /CropBox is degenerate (zero width or height); falling back to the /MediaBox as the visible region", - }); - cropBox = mediaBox; - } - const rotation = normalizeRotation(asNumber(dictGet(page, "Rotate"))); - // Only rotationResult.matrix is used below, never its own widthPt/heightPt fields — and the matrix's rotation/reflection component (a, b, c, d) never depends on the w/h arguments at all, only its translation component (e, f) does. That translation is provably canceled by the origin renormalization two lines down (translationMatrix(-visibleRect.minX, -visibleRect.minY) subtracts out exactly the offset any w/h value would have introduced), so the real mediaBox width/height computed here would produce a byte-identical pageMatrix and visibleRect to passing 0 for both — confirmed directly against an asymmetric MediaBox/CropBox pair under every rotation, not merely the aligned case. Passing 0 rather than the real (but unobservable) mediaBox dimensions removes an arithmetic expression whose result genuinely never reaches any output. - const rotationResult = pageRotationTransform(rotation, 0, 0); - // The crop rect rotated into output space, then used as the origin: every item position is relative to the visible region's own lower-left corner, exactly as a viewer presents it. - const visibleRect = rotatedRectBounds(cropBox, rotationResult.matrix); - const widthPt = visibleRect.maxX - visibleRect.minX; - const heightPt = visibleRect.maxY - visibleRect.minY; - const pageMatrix = multiplyMatrices( - rotationResult.matrix, - translationMatrix(-visibleRect.minX, -visibleRect.minY), + const { mediaBox, cropBox, widthPt, heightPt, pageMatrix } = readPageFrame( + pageIndex, + page, + sink, ); const boxRow = pageBoxResidueEntry(pageIndex, page, mediaBox, cropBox); diff --git a/packages/pdf-codec/src/test-support/image-heavy-pdf-golden.ts b/packages/pdf-codec/src/test-support/image-heavy-pdf-golden.ts new file mode 100644 index 0000000000..e90bd94069 --- /dev/null +++ b/packages/pdf-codec/src/test-support/image-heavy-pdf-golden.ts @@ -0,0 +1,245 @@ +// SHA-256 of every image pdf-codec 4.5.2's readPdf decoded from the fixtures in image-heavy-pdf.ts, keyed by the imageId it registered each under: the decoded output every image shelved before 5.x was produced from, which per-image decoding has to reproduce byte for byte (a changed byte would mint a new blob for an image already stored). Recorded by reading each fixture with the published pdf-codec@4.5.2 (npm install pdf-codec@4.5.2 in a scratch directory, then readPdf from its dist/read.js and SHA-256 of each LayoutDocument.images entry's decoded base64); 5.8.6 decodes every one of them to the same bytes. + +// imageVarietyPdf(), read by 4.5.2: every image its registry held. +export const IMAGE_VARIETY_4_5_2: Readonly> = { + imgb79c90df: + "1a66df6dcc99666af758d59e6119f7c47459e7cd987fb88f6743d77ae3dfac83", + imgf34133bc: + "e49a50c9d370268a171f5c8c2b1f1bf4b800e3070780bb737c096e25cf22e26c", + imgc043fc33: + "44116bae3fcf09162bc0dacbd3c1a58e7e6652d6996f350efa61890a39f59415", + img967c6225: + "b3c3717f2a5a41277ee809a4e18ce1f161263be23da9c3445e023d5a5bebe2ef", + img7a5ef8f1: + "d0017b84312de54370b1604455c6f0a4cfa90eaae50dca8888d3080742aadcbc", + imgca0e0cc5: + "3db77419a13d16b1c07f209a9c43e477be71bbbbb47e4fd5e89257ddbb856484", + imgbc64a60a: + "7e5bef30cf6ed7e1d854393bf9b2089449444868d495b5a404bf416077ed77b1", + img9af17359: + "a1eef93b91752af0a0764d66bc221940aec3a20200b24a88643364d252bdc6c4", + img14400be8: + "7ab24eb7d0edb72ebfde4686eaf8cebf75f0a5fdf130cec784c485833242eb5f", + img41bcfb9b: + "86efe3a3fe71cb9598a32574be352e73e1b1d9491396e7d2fe203ee7a31323a5", +}; + +// pictureDeckPdf({ scale: 0.25 }), read by 4.5.2: every image its registry held. +export const PICTURE_DECK_QUARTER_4_5_2: Readonly> = { + img73ec537b: + "dd49187e0aa23fce914b8bfedc51c4b998319be0f7bca1d91dfbb25f9eed75dc", + imgc6193e7b: + "bc45ec9bc59a4619b1f6d7722619e85b5ce6e1d52026c950015898d63f602862", + img95f64a17: + "a7c7618d8857e9d4c7a85cee5e4a6fc59847983411ab8a9ed27711622a025506", + imga39c57c6: + "da765afa4060d3ef651dea0ba06b594d9376c446ed113d67cc51763663493812", + imgf3b952af: + "4c961131f66bf47bf3820437645bca84c600cb7ca16b454925d835fd5b6077ba", + imgd579b5e6: + "d35ba06007b9cb1d6f5f738cafe333c6f960aac8e8cf145154f2e36a3d37d120", + imgfd9c15a6: + "487f87f372f2bc096a26a8727a004050939196fdc6f87b805401c67c21c1d795", + img5e3b7ec1: + "2bc9f60e7f9a2c18ef7abc4867fe9603b164c1b4ddee419e24e38db971efc556", + img9a1b205: + "ba93014162267d030a45b82b900042bc9884ad4ea99bb1763b43da149911338b", + imga3e784d3: + "7aa8b27032cc24973b3bd62e59d7d7d950c92ab80945ec32fc81963f8743ee0c", + imga26dfc25: + "d1a7bc982bb175859a96b9edb2e9d2d93801d84b9f2c555f252dd5d4de388c27", + img5338231e: + "044204953d98fcd5fde449bc1aee7cd1d26beb77bb75f5967ed7abb942dea175", + img8ed0e591: + "a3888e48e2ecc2b7262efc3592a576f374c110286e7a0466fd58ffa767e3e9dc", + img4c992a66: + "a23b46be790f432dfb1b924143924144644a1eb60e6fe644785fb7dcc571851d", + imgbbd1cc65: + "06142c527b538040510ee28b639755163d9a39c5cca0f1b861b3002942fb1b3e", + img8a4b0f0f: + "00bb32acafec9bd836bf0f5a667424601e743ab6573af1df414960c976514689", + imgbd6422fc: + "8b0bb11dec09f2e57b2785f67e0eb448c901f1a5c1202903633ad248827206bf", + img812ab5c0: + "de74fee8c90799028978b573fc6afdc3a826586754fdf0b1f8160de92bcdd8a8", + imgab9dc922: + "b85dbda1ff4da7f1cd922bbdac21bb347007b104aa9610ae95f4f8c0313a1530", + imgaad1c580: + "334747340a01e2adb8cd5c9230607dd1659c397b3b309cc05cd1b553a0bb5193", + img9981c09: + "f09892659cf86412874aa3f1d594534bf8172c6e996fb70d705f74e5aa2579c4", + img662dd86f: + "923bf48997746ce97b5cc62596261fc44565c43a3c4a2317f137daae03f26890", + img2e885b60: + "984da07c55563477519cc9142660f61f84df9882480bfbe29a03b77294a2d501", + imgb4da7f99: + "2b91cb7de78b3b706b129b7ec83aba4dbcb89c9ee4c8f7bfdecd599ec5234792", + imge80c357a: + "6caa16dd15e0c64ecd3034aad1b3ac2861df80f7c90c4bd06e35931d225eb7a6", + imgef306566: + "51c367753a669c86834609d94e13bfbba654ef8e750e790c502c5f3954c54018", + img86ca764: + "e7e0259cb501f502e7afa1fd8047f25dd716ba20235d9be1170fbf635d6cc8a0", + img83e3ac2b: + "10c38be530505b0b83f5365d2b313b757f25190beba59cc5c4a470e7f2708a9c", + img3c186e4e: + "c39c438aad52b33e3db82f348d81ed00e5553c8712855650462c2cb4d02ddd6a", + img54323e66: + "10e70724c6709f2e623df9980401c1cd02c8ffe79d18dcb2b538cb77797fa4d9", + img29d8b9ed: + "d324eacc9b2d94a6b4903cbebb0c5e5145567f4e37dab3fb213ec767ebf60b4a", + img5a062d72: + "5d6809cbb246c16fc8d37c9d9547c138233e65259f98d5f857f579a6c6f01d52", + img9275f8d5: + "d79e0c4bf4e5701810ff6f2a0014234b7bd41e4b283c175ed957989f1fd3d6d0", + imgfc5f723f: + "8e5429749f1bbfb6994b4e4b5f4f6b6d5522f1ff61540e4e9402f8db742db7bb", + imge396b7cc: + "f9bbca2980d285e6135451f346443b64baede8f43b42bbabc30d95701fec6b09", + img971823d5: + "3fe80d7494aa4aa6033e3975b15da8b579cba9ee4aa553452baba1f84ca7dda1", + img6b4e74e5: + "ac091a75a38cda4febb641161de7b8d6119ca81ed5219b2f2a0e93b523701500", + imgdd6786fc: + "9f5c8c6e40ebd30d66c16b289e953f3188df3212246b848444d68380896bba49", + imgda158ce4: + "24b9ae190178cf1c2fa10a12d01406cd5446bcf417184aca6bfd25f84bfbecf1", + imgacf2e90: + "a50fd9d2aac1b668cc391ea3fcbe120816bce8868f7a08c1bb701eba58f8c82e", + img72e42075: + "c1af458e31bc32291e55bfbfce096701e7d3e30e71b296bb6364cc0a7bc18712", + imgc006d75a: + "e34b6212b16c255bcdafb15f838c077cd3eaddaa983172c67087622d73d5a8b0", + img9ef7cde8: + "24180b835ef7a4734e4e376ad510ea35ad04b0abd5c9f834f962d234f2d07537", + imged1ce40a: + "023486c29d98de08a34052d744e2549ec65d258169a0e22635f5575bac021ffb", + img53935a78: + "e8177fe6a39c3a9e1f6ce01ed20685b76e7cbdb938ca9852578dde7851b5b0dd", + img48756d45: + "b8b982013a1ba3fbb2f9c9102a94cbb5104936713275571fa09fd00466c0f9a2", + img73c78cf1: + "daef23f65c4262c3324fd8023418cdb536cdfb42a64a1ddb4c9a63d424192410", + imgc0559116: + "ffb898b59acca065bfe31758db04329047b31927e1028337c7162ee4c73e9da4", + img9523bab6: + "3505d088975abc0a479d915e9be723529e1838a7c13f7e4f9a92a99c9da8246b", + img4f98e783: + "2ad9fb13b74be7aa41d657af13f7e6a2c7701cc020f27835760e067e6834dccb", + imgeb1f18ea: + "54670de24faaa6ccbcf6b8fff382341b89a8857623e837a0fe6d706f2ca1f4f5", + imge29f123: + "d830876e62fd0a013bae3e4775a0d881d44e413fa50a512897e0363fdad8fde6", + imga67e0fd0: + "6e3f18d1c2f700646d328f31fb9e52bfa182e46e811b6663718420df1f24b291", + imgc61e4a2e: + "1c9ab7a6df40c28d812c2c748383bac70b1380645121de40412a7ca6e6fb215b", + imgfa4a1c47: + "13792ec8a1c3583c6ceddcd65b110a08bd171ba6a323995dd09797fce9cad7e7", + imgb8cc9e87: + "16441e161d1cee8efb4d24912326a5e14ce388757a0a86131c554e0e214c930c", + img1e89dd5d: + "a6412ef2a919b075fe94418b7a9bcdcdf1632a68066c9025a8b3e0f26a20d49b", + img64fbdd3d: + "9afd98408a006e00c53546d4fbf9d634840c60ee689d5027b932f1223db86310", + img194e2cad: + "06f0c9928767bc35036ec2f58d849782e6cb16105d044ff807e840ca705c0c4f", + imga416d22c: + "b60b0de13c3b5fc2c0880df6c2c5def4aed420be84b8bf204c08031d6be0915c", + img959641f9: + "a684e88ff99ad4457b13ff6350804360ad0da464c59d0a9a1459d11033c4f5af", + img1e42395b: + "763e30967caafde29af06fe44bd075a6806a24d49ae89b91f4a3e0bf80443cc8", + imgfeaed729: + "291749dcc1f14cc66161745024b68e5c0f0e6b85fb67bd980e26787dc9b17324", + img2e68b608: + "a6daf76c5a2184e6317a6c7884ff21e1e2daab577d69b28b8cd456c17a29ec85", + imgb5b9b724: + "ea4a168059f8b63878489db6aef4cf21e3c74293979d03cdbda28e851f420fcf", + img500a6a97: + "c0b11d12cfe6207b89379cbbf04fc42766b6c7e40f4109ea62075281a3593eef", + imgbb43cd6a: + "9da751f46e52260df46467ce29faef23fc3bfe27fb1b6a1bb14d5bf7584bf4ae", + imgb009a7b: + "4bcd9ea099cd2a2eca3ad1a9a020f4e6006fbc63b7e8417a96fbfabf6d474635", + img8228b2e9: + "bee132d965eb050a8203e2ecc869cdffbac3a2f97fddbdde04e8e48aa9da673a", + img8a3c644: + "6d9388623b836709f3df9a843869094e88d00e3da664fd940e44ce873ba69aa8", + img9864a5d6: + "bab53b88778e271d8d4dfe3a5e11ae8b44ba6658761d8df0e04356c5aab4c908", + imgb7267805: + "03f21522fafc996a097c85ff59d4e6bf9314cbe60388700ae263778dd887611f", + imga3cf1cee: + "d0a8526c1ce113f56cb9afac7659ebe1246d23be21471b1550541ddf33f08340", + img7e992533: + "656303a5563e82b7fa0e8a6b616222e6f19e546682f2fcc73c528e2bac38e611", + img204f1964: + "bfdb136d9c115e6c6a2d1d1d9965be153bfce70fe6a5d9684c837f0e57fffc4a", + imgf867afff: + "6d494bfc18d5c778f268731356a0f5872aecc3ee3657281510cbd627f93381ea", + img1e04106e: + "5c8cb3723a87d75b4c0f5cc717efde274ed57e9ac0bcf7d09ac3182973cd02c6", + imge1eafb9e: + "37e837bcd5e05a57d859b146a2037bf4765428a2a0cb28026a8e671de0660873", + img8381d5df: + "b9d91bb0a7fe27dba5df117445b2ed6ec934707283e092dee0555604648ffd18", + img8dfb24d2: + "5cea9c3fd59b4eeb2bbc50882a3eb6a1b70d77641f0d98e6fea178458087716a", + img5588b5c1: + "9ae97036075b92a6279a9a1eae50c6da3a6e1c0c80ab51afede945163a8ed58d", + img12e059b9: + "f6c791a8e0c8ccd7936cd8ba568165102bb38bd3e28656dac19f201ccf231aa1", + img817719ee: + "a2a7a2b1111103de854ec2bf404a90cae360d305fec0ebfe1f92019c6dbe91c9", + imga82572a2: + "52f91d561ec554f2226c3af3f02cde83acae86769aff249f5d40140710540d04", + img4e54622d: + "4717eaf246366bd0b656099b2dac12c45c640cac1f3ea416c432cc5b0fd4cd14", + img4f6a34d1: + "b0eb1296bc29ee859e4fbd99cbd568fc522dc013cac2ba19273cdff8c415461e", + img6a653140: + "8d487306f3a0fabf3796ab126b53beb2a6f6f2304a10856abdbba2cb385964e8", + imge438bea9: + "d30b83b7fe3701cf5aa29ea5a6f29d2775d86a1a46c0bd903dfe230d7a87e8e5", + img55766d76: + "66b18036bd00455998ba7efd2f86174e8f95f72c3a8ebcdec2bca26a6cc22511", + img722b9c67: + "904b4ade47467b721ae84db6e1baee21df8147ead9ca0f26bfb1792364960aaa", + img1cfaf26f: + "48b572386adcaa372a6bc54a9dd17cb57ac3579fdffcc665788db6668a3d9547", + img37b52cb2: + "3429f9a0d2d67a1369970e7fb90e25a0b953bce25b5ff95a64d6dcfb75a64e3a", + img28e48bd9: + "6dad3c4358a7d44d39315760681313aa879d89138a6a7b36dc507617320041b4", + imge633934a: + "5b3c34f9ebec8b4647ac3ee3a4f472dae50817e86ac9a14da55f7d2c60b3a978", + img9150c6d1: + "472ba898106d4289629627cc8e6fd1ff3679734894ecd2c455080fdf0da83e1f", + img4b01db90: + "ae4fdbd8bb7677d5cee147b3d7775e77153b58c484791df2eb41e2be4bf8d3f2", + imgf0874bb4: + "3e22f086a106b5fe36fb8b445d46453ffbcd2528ae8f52d4478e441a5850259a", + imge0a70587: + "11a2785c495925507d7b69168e0b017e8dce4d4543cca8e537c937314155fc56", + imgf2e8b80: + "603e156169e6d028dc402223ba1b9bda2cb40e4513f9f929945eb18e946f1967", + imgd5c3cb25: + "4292e935585123f1cc0d940a3b008790ba5c57f4a759c0e8fb5c08ddc27910ff", + imge9459c70: + "36926b5fd758da298ab52ea0b5f03aab8cbe78207a732882e0614ffecd821438", + img850d1a0a: + "e80bfde2359045e3c7f102cfa36c3e1c589f7c6a948cd6906f3a7bd952fa6b72", + img348819c3: + "bbe273c913bfa1bc4352c5cdb2a722caf367ac2ca722ce8f0ba4bfd641c8ddda", + img8e23bf98: + "cf33c714d87795cbe1b8e788143679d9aa52d0fc48e31c129b60e913469e33e7", + img7df501ab: + "09a357f0a72e7d5ba8dcbe2485726c10ccc23a230dee686ebb9435b40c77ef94", + img70f6356f: + "f865e776560b2c6a859a69dfe9430fe6214958d6fc9fdee5d444fb5d5e467289", + img251458dd: + "3079c4abf1224a30c8847f37a73bee2cff9387b0b6c2db8a5c41713583e8e5c6", + img851cd5c0: + "1e9e7fa9ebda477237b821740294cb7cdb4ec06c9daf7e3dfb862560f78a25b9", +}; diff --git a/packages/pdf-codec/src/test-support/image-heavy-pdf.ts b/packages/pdf-codec/src/test-support/image-heavy-pdf.ts new file mode 100644 index 0000000000..c1cb47c065 --- /dev/null +++ b/packages/pdf-codec/src/test-support/image-heavy-pdf.ts @@ -0,0 +1,476 @@ +import { zlibSync } from "fflate"; +import { ByteWriter } from "../bytes/writer"; +import { FixtureBuilder, enc } from "./pdf"; +import { seededRandom } from "./seeded-random"; + +// Picture-heavy PDF fixtures for the per-image reader (read-images.ts), built like every fixture in pdf.ts: by literal concatenation through FixtureBuilder, never through this package's own writer. Two shapes: +// +// - imageVarietyPdf: one small image of each kind the read path decodes differently (Flate RGB with a soft mask, PNG-predicted ICC RGB, inverted gray, indexed, 1-bit, CMYK, a JPEG passed through, an image inside a form XObject, an inline image), plus the cases the listing has to leave out or report as undecodable. Its objects are numbered in a fixed order (images from 3, image 0's soft mask straight after it, then the ICC profile and the form), which read-images.test.ts names them by. Its decoded bytes are pinned against pdf-codec 4.5.2's (image-heavy-pdf-golden.ts). +// - pictureDeckPdf: shaped like a typical picture-heavy slide deck (20 pages, about a hundred distinct images, most of them Flate RGB with soft masks and the largest 2360x1309, the rest JPEG), generated from a seed. At full scale it is about 2.5 MB; `scale` shrinks every image's pixel size for a unit test that wants the same structure without the cost. + +const PAGE_WIDTH_PT = 960; +const PAGE_HEIGHT_PT = 540; + +interface FixtureImage { + // The image XObject dictionary without /Length (FixtureBuilder.stream inserts it). + readonly dict: string; + readonly data: Uint8Array; + // A soft mask the dictionary names as "/SMask 0 R"; its object number is allocated by the builder. + readonly smask?: { + readonly dict: string; + readonly data: Uint8Array; + }; +} + +function flate(bytes: Uint8Array): Uint8Array { + const compressed = zlibSync(bytes); + const copy = new Uint8Array(compressed.length); + copy.set(compressed); + return copy; +} + +// Picture-like samples, cheaply: smooth gradients with seeded noise, optionally posterized into flat bands (as a chart, a diagram or a cut-out picture is), so Flate compresses them the way it compresses a real picture rather than to nothing. +function photoSamples( + width: number, + height: number, + channels: number, + seed: number, + noise: number, + posterize = 1, +): Uint8Array { + const random = seededRandom(seed); + const out = new Uint8Array(width * height * channels); + const phase = random() * 6; + let at = 0; + for (let y = 0; y < height; y++) { + for (let x = 0; x < width; x++) { + for (let c = 0; c < channels; c++) { + const base = + 128 + + 90 * + Math.sin((x / width) * 3 + phase + c) * + Math.cos((y / height) * 2 + c); + const value = base + (random() - 0.5) * noise; + out[at++] = Math.max( + 0, + Math.min(255, Math.round(value / posterize) * posterize), + ); + } + } + } + return out; +} + +// An alpha channel with a soft edge: opaque in the middle, fading out towards the border, as a cut-out picture's mask does. +function softMaskSamples( + width: number, + height: number, +): Uint8Array { + const out = new Uint8Array(width * height); + for (let y = 0; y < height; y++) { + for (let x = 0; x < width; x++) { + const edge = Math.min(x, y, width - 1 - x, height - 1 - y); + out[y * width + x] = Math.min(255, edge * 16); + } + } + return out; +} + +// A JPEG the reader passes through untouched: SOI, a baseline SOF0 stating the size, a payload of seeded bytes standing in for the entropy-coded scan, and EOI. Nothing decodes the scan, so its content need not be real. +function fakeJpeg( + width: number, + height: number, + payloadLength: number, + seed: number, +): Uint8Array { + const random = seededRandom(seed); + const w = new ByteWriter(); + w.writeBytes( + new Uint8Array([ + 0xff, + 0xd8, + 0xff, + 0xc0, + 0x00, + 0x11, + 0x08, + height >> 8, + height & 0xff, + width >> 8, + width & 0xff, + 0x03, + 0x01, + 0x22, + 0x00, + 0x02, + 0x11, + 0x01, + 0x03, + 0x11, + 0x01, + 0xff, + 0xda, + ]), + ); + // The scan's bytes, kept free of 0xFF so no stray marker appears inside it. + w.writeBytes( + Uint8Array.from({ length: payloadLength }, () => + Math.floor(random() * 255), + ), + ); + w.writeBytes(new Uint8Array([0xff, 0xd9])); + return w.toBytes(); +} + +function rgbImage( + width: number, + height: number, + seed: number, + noise: number, + withSoftMask: boolean, + posterize = 1, +): FixtureImage { + return { + dict: `<< /Type /XObject /Subtype /Image /Width ${width} /Height ${height} /ColorSpace /DeviceRGB /BitsPerComponent 8 /Filter /FlateDecode >>`, + data: flate(photoSamples(width, height, 3, seed, noise, posterize)), + ...(withSoftMask + ? { + smask: { + dict: `<< /Type /XObject /Subtype /Image /Width ${width} /Height ${height} /ColorSpace /DeviceGray /BitsPerComponent 8 /Filter /FlateDecode >>`, + data: flate(softMaskSamples(width, height)), + }, + } + : {}), + }; +} + +function jpegImage( + width: number, + height: number, + payloadLength: number, + seed: number, +): FixtureImage { + return { + dict: `<< /Type /XObject /Subtype /Image /Width ${width} /Height ${height} /ColorSpace /DeviceRGB /BitsPerComponent 8 /Filter /DCTDecode >>`, + data: fakeJpeg(width, height, payloadLength, seed), + }; +} + +// A placement operator for the unit square: an image of the given size drawn at (x, y). +function drawAt( + name: string, + x: number, + y: number, + w: number, + h: number, +): string { + return `q ${w} 0 0 ${h} ${x} ${y} cm /${name} Do Q`; +} + +interface FixturePage { + // The page's /XObject resources: a name and the object it names, as a token assemble resolves (`@image:N` for image N of the list, `@extra:N` for extra object N). + readonly xobjects: Readonly>; + readonly content: Uint8Array; + readonly extraPageEntries?: string; +} + +interface FixtureObject { + readonly dict: string; + readonly data?: Uint8Array; +} + +// Lays out catalog, pages, every image (and its soft mask) as an indirect object, any extra objects, then each page and its content stream. Every dictionary may name another object by token (`@image:N`, `@extra:N`), replaced with its reference once every object is numbered, so one XObject drawn on several pages is one object. +function assemble( + images: readonly FixtureImage[], + pages: readonly FixturePage[], + extraObjects: readonly FixtureObject[] = [], +): Uint8Array { + const b = new FixtureBuilder().header("1.7"); + let next = 3; + const imageObjects: number[] = []; + const smaskObjects = new Map(); + for (const [index, image] of images.entries()) { + imageObjects.push(next++); + if (image.smask !== undefined) { + smaskObjects.set(index, next++); + } + } + const extraObjectNumbers = extraObjects.map(() => next++); + const pageObjects = pages.map(() => { + const page = next; + next += 2; + return page; + }); + const resolve = (dict: string): string => + dict.replace(/@(image|extra):(\d+)/g, (_, kind: string, index: string) => { + const num = (kind === "image" ? imageObjects : extraObjectNumbers)[ + Number(index) + ]; + if (num === undefined) { + throw new Error(`fixture token @${kind}:${index} names no object`); + } + return `${num} 0 R`; + }); + b.object(1, "<< /Type /Catalog /Pages 2 0 R >>"); + b.object( + 2, + `<< /Type /Pages /Kids [${pageObjects.map((n) => `${n} 0 R`).join(" ")}] /Count ${pages.length} >>`, + ); + for (const [index, image] of images.entries()) { + const smaskObj = smaskObjects.get(index); + const dict = + smaskObj === undefined + ? image.dict + : image.dict.replace(/>>\s*$/, ` /SMask ${smaskObj} 0 R >>`); + b.stream(imageObjects[index]!, resolve(dict), image.data); + if (smaskObj !== undefined && image.smask !== undefined) { + b.stream(smaskObj, image.smask.dict, image.smask.data); + } + } + for (const [index, extra] of extraObjects.entries()) { + const num = extraObjectNumbers[index]!; + if (extra.data === undefined) { + b.object(num, resolve(extra.dict)); + } else { + b.stream(num, resolve(extra.dict), extra.data); + } + } + for (const [index, page] of pages.entries()) { + const pageObj = pageObjects[index]!; + const xobjects = Object.entries(page.xobjects) + .map(([name, token]) => `/${name} ${token}`) + .join(" "); + b.object( + pageObj, + resolve( + `<< /Type /Page /Parent 2 0 R /MediaBox [0 0 ${PAGE_WIDTH_PT} ${PAGE_HEIGHT_PT}] /Resources << /XObject << ${xobjects} >> /Font << /F1 << /Type /Font /Subtype /Type1 /BaseFont /Helvetica >> >> >> /Contents ${pageObj + 1} 0 R${page.extraPageEntries ?? ""} >>`, + ), + ); + b.stream(pageObj + 1, "<< >>", page.content); + } + b.classicXrefAndTrailer(next - 1, "/Root 1 0 R"); + return b.bytes(); +} + +// Each row prefixed with the PNG Sub filter's type byte and filtered by it, as a PDF /Predictor 15 stream's rows are (ISO 32000-1 7.4.4.4). +function pngSubPredicted( + samples: Uint8Array, + rowBytes: number, + bytesPerPixel: number, +): Uint8Array { + const rows = samples.length / rowBytes; + const out = new Uint8Array(rows * (rowBytes + 1)); + for (let row = 0; row < rows; row++) { + const from = row * rowBytes; + const to = row * (rowBytes + 1); + out[to] = 1; + for (let i = 0; i < rowBytes; i++) { + const left = i >= bytesPerPixel ? samples[from + i - bytesPerPixel]! : 0; + out[to + 1 + i] = (samples[from + i]! - left) & 0xff; + } + } + return out; +} + +/** + * One small image of every kind the read path decodes differently, on two pages (the second rotated and cropped), plus an inline image, an image inside a form XObject, an /ImageMask stencil (never listed), an image drawn only outside the crop box (never listed), and one with an unsupported bit depth (listed, not decodable). + * @returns The PDF bytes. + */ +export function imageVarietyPdf(): Uint8Array { + const indexedPalette = Array.from({ length: 16 }, (_, i) => + [i * 16, 255 - i * 16, (i * 37) % 256] + .map((v) => v.toString(16).padStart(2, "0")) + .join(""), + ).join(""); + const iccProfile = { + dict: "<< /N 3 /Alternate /DeviceRGB >>", + data: enc("not a real profile"), + }; + const iccRgb = photoSamples(31, 9, 3, 11, 40); + const images: FixtureImage[] = [ + // 0: Flate RGB with a soft mask + rgbImage(64, 48, 1, 60, true), + // 1: inverted gray (/Decode [1 0]) + { + dict: "<< /Type /XObject /Subtype /Image /Width 40 /Height 30 /ColorSpace /DeviceGray /BitsPerComponent 8 /Decode [1 0] /Filter /FlateDecode >>", + data: flate(photoSamples(40, 30, 1, 2, 30)), + }, + // 2: indexed, four bits per index + { + dict: `<< /Type /XObject /Subtype /Image /Width 33 /Height 17 /ColorSpace [/Indexed /DeviceRGB 15 <${indexedPalette}>] /BitsPerComponent 4 /Filter /FlateDecode >>`, + data: flate( + Uint8Array.from({ length: 17 * 17 }, (_, i) => (i * 29) & 0xff), + ), + }, + // 3: one bit per pixel, uncompressed + { + dict: "<< /Type /XObject /Subtype /Image /Width 50 /Height 20 /ColorSpace /DeviceGray /BitsPerComponent 1 >>", + data: Uint8Array.from({ length: 7 * 20 }, (_, i) => (i * 73) & 0xff), + }, + // 4: CMYK + { + dict: "<< /Type /XObject /Subtype /Image /Width 20 /Height 20 /ColorSpace /DeviceCMYK /BitsPerComponent 8 /Filter /FlateDecode >>", + data: flate(photoSamples(20, 20, 4, 4, 50)), + }, + // 5: a JPEG, passed through + jpegImage(120, 80, 900, 5), + // 6: ICC-based RGB under a PNG predictor (ICC profile is extra object 0) + { + dict: "<< /Type /XObject /Subtype /Image /Width 31 /Height 9 /ColorSpace [/ICCBased @extra:0] /BitsPerComponent 8 /Filter /FlateDecode /DecodeParms << /Predictor 15 /Colors 3 /Columns 31 >> >>", + data: flate(pngSubPredicted(iccRgb, 31 * 3, 3)), + }, + // 7: an /ImageMask stencil, which neither readPdf nor the listing reports as an image + { + dict: "<< /Type /XObject /Subtype /Image /Width 8 /Height 8 /ImageMask true /BitsPerComponent 1 >>", + data: new Uint8Array(8).fill(0xaa), + }, + // 8: drawn only outside the crop box, so never visible + rgbImage(10, 10, 8, 20, false), + // 9: an unsupported bit depth + { + dict: "<< /Type /XObject /Subtype /Image /Width 4 /Height 4 /ColorSpace /DeviceGray /BitsPerComponent 16 >>", + data: new Uint8Array(32), + }, + // 10: drawn only inside the form XObject (extra object 1) + rgbImage(16, 12, 10, 80, false), + ]; + const inline = new ByteWriter(); + inline.writeAscii("q 30 0 0 20 300 300 cm BI /W 2 /H 2 /CS /RGB /BPC 8 ID "); + inline.writeBytes( + new Uint8Array([255, 0, 0, 0, 255, 0, 0, 0, 255, 255, 255, 0]), + ); + inline.writeAscii(" EI Q"); + const page0 = [ + drawAt("Im0", 10, 10, 128, 96), + drawAt("Im0", 400, 10, 64, 48), + drawAt("Im1", 150, 10, 80, 60), + drawAt("Im2", 250, 10, 66, 34), + drawAt("Im3", 330, 10, 100, 40), + drawAt("Im4", 10, 200, 40, 40), + drawAt("Im5", 60, 200, 120, 80), + drawAt("Im6", 200, 200, 62, 18), + drawAt("Im7", 300, 200, 16, 16), + drawAt("Im9", 340, 200, 8, 8), + "q 1 0 0 1 500 300 cm /Fm1 Do Q", + "BT /F1 12 Tf 10 500 Td (Pictures) Tj ET", + ].join("\n"); + const pages: FixturePage[] = [ + { + xobjects: { + Im0: "@image:0", + Im1: "@image:1", + Im2: "@image:2", + Im3: "@image:3", + Im4: "@image:4", + Im5: "@image:5", + Im6: "@image:6", + Im7: "@image:7", + Im9: "@image:9", + Fm1: "@extra:1", + }, + content: enc(page0), + }, + { + xobjects: { Im0: "@image:0", Im8: "@image:8" }, + content: (() => { + const w = new ByteWriter(); + w.writeAscii( + `${drawAt("Im0", 100, 100, 200, 150)}\n${drawAt("Im8", 2000, 2000, 20, 20)}\n`, + ); + w.writeBytes(inline.toBytes()); + return w.toBytes(); + })(), + extraPageEntries: " /Rotate 90 /CropBox [50 50 900 500]", + }, + ]; + return assemble(images, pages, [ + iccProfile, + { + dict: "<< /Type /XObject /Subtype /Form /BBox [0 0 48 36] /Resources << /XObject << /Inner @image:10 >> >> >>", + data: enc(drawAt("Inner", 0, 0, 48, 36)), + }, + ]); +} + +/** The picture-deck fixture's options. */ +export interface PictureDeckOptions { + /** Multiplies every image's pixel width and height (default 1, the full-size shape). */ + readonly scale?: number; +} + +/** + * The shape of a real picture-heavy slide deck: 20 pages, 108 distinct images (81 Flate RGB, most with soft masks and the largest 2360x1309, and 27 JPEGs), several drawn on more than one page. About 2.5 MB at full scale. Generated from fixed seeds, so the same bytes every run. + * @param options - The scale. + * @returns The PDF bytes. + */ +export function pictureDeckPdf( + options?: PictureDeckOptions, +): Uint8Array { + const scale = options?.scale ?? 1; + const px = (n: number): number => Math.max(1, Math.round(n * scale)); + const random = seededRandom(700); + const images: FixtureImage[] = []; + // The large pictures: a 2360x1309 hero image and a run of decreasing slide-sized ones, all with soft masks. + const large: readonly (readonly [number, number])[] = [ + [2360, 1309], + [1920, 1080], + [1600, 900], + [1280, 720], + [1280, 720], + [1024, 768], + [960, 540], + [800, 600], + ]; + for (const [index, [w, h]] of large.entries()) { + images.push(rgbImage(px(w), px(h), 100 + index, 0, true, 3)); + } + // Medium and small Flate RGB pictures (icons, logos, charts), most with soft masks. + for (let i = 0; i < 73; i++) { + const w = 64 + Math.floor(random() * 540); + const h = 48 + Math.floor(random() * 380); + images.push(rgbImage(px(w), px(h), 200 + i, 0, i % 4 !== 3, 8)); + } + // Photographs kept as JPEG. + for (let i = 0; i < 27; i++) { + const w = 400 + Math.floor(random() * 1200); + const h = 300 + Math.floor(random() * 700); + images.push( + jpegImage( + px(w), + px(h), + Math.round((8000 + random() * 22000) * scale * scale), + 300 + i, + ), + ); + } + const pages: FixturePage[] = []; + const pageCount = 20; + for (let page = 0; page < pageCount; page++) { + const xobjects: Record = {}; + const draws: string[] = []; + // Each image appears on page (index mod 20); every fifth also reappears on the next page, as a logo or a repeated chart does. + for (let index = 0; index < images.length; index++) { + const onPage = + index % pageCount === page || + (index % 5 === 0 && (index + 1) % pageCount === page); + if (!onPage) { + continue; + } + const name = `Im${index}`; + xobjects[name] = `@image:${index}`; + const slot = draws.length; + draws.push( + drawAt( + name, + 20 + (slot % 4) * 230, + 20 + Math.floor(slot / 4) * 170, + 220, + 160, + ), + ); + } + draws.push(`BT /F1 18 Tf 20 510 Td (Slide ${page + 1}) Tj ET`); + pages.push({ xobjects, content: enc(draws.join("\n")) }); + } + return assemble(images, pages); +} From bc963f0581bbf5e449ceb823ba00f568d39349e1 Mon Sep 17 00:00:00 2001 From: fcbwilliams Date: Tue, 17 Nov 2026 16:02:40 +0100 Subject: [PATCH 04/11] perf(byte-codec): encode a PNG's truecolour form before its palette encodePng now builds the palette and its index plane only after the truecolour pass has finished with its filtered rows and deflate buffer, so the two are never held at once. The result is unchanged: the same comparison picks the smaller encoding. Also states filterScanlineRows' contract plainly: a byte the callback leaves unwritten keeps the previous row's value, which is how filterScanlines treats a raw buffer shorter than its rows. Co-Authored-By: Claude Opus 5.5 --- packages/byte-codec/src/image/png-encode.ts | 13 +++++-------- packages/byte-codec/src/image/png-filter.ts | 2 +- 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/packages/byte-codec/src/image/png-encode.ts b/packages/byte-codec/src/image/png-encode.ts index f0cf14bac7..aed236a135 100644 --- a/packages/byte-codec/src/image/png-encode.ts +++ b/packages/byte-codec/src/image/png-encode.ts @@ -259,15 +259,15 @@ export function encodePng( ); } + // Truecolour is encoded first, so the palette's index plane is built only once the larger truecolour pass has finished with its filtered rows and deflate buffer, and the two are never held at once. + const truecolor = buildPng((writer) => { + writeTruecolorPng(writer, image, options); + }); const paletteEncoding = image.channels === RGB_CHANNELS ? detectPalette(image) : undefined; - if (paletteEncoding === undefined) { - return buildPng((writer) => { - writeTruecolorPng(writer, image, options); - }); + return truecolor; } - const indexed = buildPng((writer) => { writeIndexedPng( writer, @@ -277,8 +277,5 @@ export function encodePng( options, ); }); - const truecolor = buildPng((writer) => { - writeTruecolorPng(writer, image, options); - }); return indexed.length <= truecolor.length ? indexed : truecolor; } diff --git a/packages/byte-codec/src/image/png-filter.ts b/packages/byte-codec/src/image/png-filter.ts index ed3951919b..02c881ab05 100644 --- a/packages/byte-codec/src/image/png-filter.ts +++ b/packages/byte-codec/src/image/png-filter.ts @@ -181,7 +181,7 @@ export function filterScanlines( /** * Filters pixel rows into PNG's per-scanline IDAT payload shape, as `filterScanlines` does, reading each row from a callback rather than from one buffer holding the whole image: a caller whose pixels are not already laid out as PNG rows (separate colour and alpha planes, say) writes each row as it is filtered instead of building the whole interleaved image first. - * @param readRow - Writes row `y`'s unfiltered bytes into `row` (exactly `bytesPerRow` long, holding whatever an earlier row left there, so every byte must be written). Called once per row, in order. + * @param readRow - Writes row `y`'s unfiltered bytes into `row` (exactly `bytesPerRow` long, holding whatever an earlier row left there: a byte the callback leaves unwritten keeps that value, which is how `filterScanlines` treats a `raw` shorter than `height` rows, so a caller wanting each row to stand alone writes every byte). Called once per row, in order. * @param height - Rows. * @param bytesPerRow - Unfiltered bytes per row. * @param bpp - Bytes per complete pixel, at least 1: the distance the Sub, Average and Paeth filters look back. From 998d0633722e85486fa366ecc7720d9c1ea42cbf Mon Sep 17 00:00:00 2001 From: fcbwilliams Date: Tue, 17 Nov 2026 16:02:46 +0100 Subject: [PATCH 05/11] fix(pdf-codec): size an inflate buffer only for an image that decodes An image dictionary's declared size now sizes the inflate buffer only when readImageXObject would go on to decode that image: its width, height and pixel count within encodePng's limits, and a bit depth it reads. The size is worked out only when FlateDecode is the stream's last filter. A soft mask is checked against its image's size and depth before it is decoded, so a mask that cannot be used is never inflated. A stream shorter than its declared size is copied out, so the buffer sized for the declaration is not kept alive behind a view. Co-Authored-By: Claude Opus 5.5 --- packages/pdf-codec/src/bytes/flate.test.ts | 6 +++ packages/pdf-codec/src/bytes/flate.ts | 10 +++-- packages/pdf-codec/src/filters.test.ts | 28 ++++++++++++- packages/pdf-codec/src/filters.ts | 10 +++-- packages/pdf-codec/src/images-read.ts | 48 ++++++++++++---------- 5 files changed, 72 insertions(+), 30 deletions(-) diff --git a/packages/pdf-codec/src/bytes/flate.test.ts b/packages/pdf-codec/src/bytes/flate.test.ts index 28ac3e2df3..f9230a1cd2 100644 --- a/packages/pdf-codec/src/bytes/flate.test.ts +++ b/packages/pdf-codec/src/bytes/flate.test.ts @@ -121,6 +121,12 @@ describe("inflateTolerant with an expected length", () => { ); }); + it("returns a stream shorter than expected in a buffer of its own length, not the one sized for the expectation", () => { + const hinted = inflateTolerant(compressed, sample.length + 500); + expect(hinted.bytes.length).toBe(sample.length); + expect(hinted.bytes.buffer.byteLength).toBe(sample.length); + }); + it("does not act on an expectation the data could not meet, whatever a dictionary claims", () => { vi.mocked(unzlibSync).mockClear(); const tiny = deflate(new Uint8Array(10)); diff --git a/packages/pdf-codec/src/bytes/flate.ts b/packages/pdf-codec/src/bytes/flate.ts index b80e22a4f6..0a0d71195a 100644 --- a/packages/pdf-codec/src/bytes/flate.ts +++ b/packages/pdf-codec/src/bytes/flate.ts @@ -43,12 +43,12 @@ export interface InflateResult { } // A tolerant inflate for the read path: real-world PDF/PNG streams occasionally carry a leading whitespace byte, are mistakenly raw-DEFLATE under a zlib-labelled filter, or are truncated. Tries, in order: a plain inflate(); skipping leading whitespace and retrying; raw inflateSync (some producers mislabel raw DEFLATE as FlateDecode); and finally the streaming Unzlib class, which emits chunks as they're produced, so a mid-stream truncation still yields whatever decoded successfully before the failure (`recovered: true`) rather than nothing at all. -// Inflates straight into a buffer as long as the caller expects the output to be, plus one byte. A stream that decodes to no more than expectedLength bytes is then decoded once, with no buffer growth and no trimming copy, to exactly the bytes inflate returns (fflate writes the same bytes whatever buffer it writes them into). Undefined when the stream does not decode or does not fit, which the spare byte filling up is how a too-long stream shows, for the caller to inflate it as before. +// Inflates straight into a buffer as long as the caller expects the output to be, plus one byte. A stream that decodes to no more than expectedLength bytes is then decoded once, with no buffer growth and no trimming copy, to exactly the bytes inflate returns (fflate writes the same bytes whatever buffer it writes them into). A stream that decodes to fewer bytes is copied into a buffer of its own length. Undefined when the stream does not decode or does not fit, which the spare byte filling up is how a too-long stream shows, for the caller to inflate it as before. function inflateIntoExpectedLength( data: Uint8Array, expectedLength: number, ): Uint8Array | undefined { - // An expectation the data could not possibly meet is not acted on: deflate expands at most DEFLATE_MAX_EXPANSION-fold, so a dictionary claiming a huge image over a tiny stream never buys a huge buffer. + // An expectation the data could not possibly meet is not acted on: deflate expands at most DEFLATE_MAX_EXPANSION-fold, so a dictionary claiming a huge image over a tiny stream never buys a huge buffer. One that overstates what a stream holds still buys a buffer of the stated size, but never a larger one than a stream of the same length that really does decode that far costs without an expectation. if ( !Number.isInteger(expectedLength) || expectedLength < 0 || @@ -59,7 +59,11 @@ function inflateIntoExpectedLength( } try { const out = unzlibSync(data, { out: new Uint8Array(expectedLength + 1) }); - return out.length <= expectedLength ? out : undefined; + if (out.length > expectedLength) { + return undefined; + } + // A stream shorter than expected is copied out, so the buffer sized for the expectation is not kept alive behind a view onto its start. + return out.length === expectedLength ? out : out.slice(); } catch { return undefined; } diff --git a/packages/pdf-codec/src/filters.test.ts b/packages/pdf-codec/src/filters.test.ts index 2f5bcc2d22..416b87d520 100644 --- a/packages/pdf-codec/src/filters.test.ts +++ b/packages/pdf-codec/src/filters.test.ts @@ -1,5 +1,5 @@ import { zlibSync } from "fflate"; -import { describe, expect, it } from "vitest"; +import { describe, expect, it, vi } from "vitest"; import type { PdfDiagnostic, PdfDiagnosticSink } from "./diagnostics"; import { ascii85Decode, @@ -270,6 +270,32 @@ describe("decodeStream", () => { expect(diagnostics).toEqual([]); }); + it("asks for the expected length only when FlateDecode is the last filter, and decodes the same bytes either way", () => { + const { sink } = collectDiagnostics(); + const compressed = zlibSync(textBytes("Hello, stream!")); + const expectedLength = vi.fn(() => 14); + const flateLast = decodeStream( + compressed, + pdfDict({ Filter: pdfName("FlateDecode") }), + sink, + undefined, + expectedLength, + ); + expect(decodedText(flateLast.bytes)).toBe("Hello, stream!"); + expect(expectedLength).toHaveBeenCalledTimes(1); + + expectedLength.mockClear(); + const dct = decodeStream( + new Uint8Array([0xff, 0xd8]), + pdfDict({ Filter: pdfName("DCTDecode") }), + sink, + undefined, + expectedLength, + ); + expect(dct.remainingFilter).toBe("DCTDecode"); + expect(expectedLength).not.toHaveBeenCalled(); + }); + it("decodes FlateDecode combined with a PNG predictor (Predictor 12)", () => { const { sink } = collectDiagnostics(); // Two rows of 3 samples each, both "None" (filter type 0) — pre-predictor bytes are the raw samples with a leading 0 per row. diff --git a/packages/pdf-codec/src/filters.ts b/packages/pdf-codec/src/filters.ts index 4ab5509ccc..6a95a19a1f 100644 --- a/packages/pdf-codec/src/filters.ts +++ b/packages/pdf-codec/src/filters.ts @@ -57,13 +57,13 @@ export type PdfIndirectResolver = ( // Runs a stream's raw bytes through its /Filter chain (a single name or an array of names, with /DecodeParms supplying per-filter parameters in the same single-or-array shape). Recoverable per-filter issues (an unresolvable /Predictor, an unimplemented filter) degrade with a diagnostic and stop the chain rather than throwing — the caller decides whether the partially- or un-decoded result is still useful (e.g. a DCTDecode image's bytes are perfectly usable as-is). // -// expectedLength is how long the caller expects the decoded stream to be, when it knows (an image's rows of samples). It only sizes the buffer a final FlateDecode inflates into (see inflateTolerant), so it changes what decoding costs in memory, never the bytes it produces. +// expectedLength says how long the caller expects the decoded stream to be, when it knows (an image's rows of samples). It is asked only when FlateDecode is the last filter, since it only sizes the buffer that inflate writes into (see inflateTolerant): it changes what decoding costs in memory, never the bytes it produces, and a stream ending in any other filter never pays for working it out. export function decodeStream( raw: Uint8Array, dict: PdfDict, sink: PdfDiagnosticSink, resolve?: PdfIndirectResolver, - expectedLength?: number, + expectedLength?: () => number | undefined, ): DecodedStream { const filters = filterNames(dict); const parms = decodeParmsList(dict, filters.length); @@ -73,9 +73,11 @@ export function decodeStream( const filter = filters[i]!; const parm = parms[i]; if (filter === "FlateDecode" || filter === "Fl") { + const expected = + i === filters.length - 1 ? expectedLength?.() : undefined; const inflatedLength = - expectedLength !== undefined && i === filters.length - 1 - ? lengthBeforePredictor(expectedLength, readPredictorParams(parm)) + expected !== undefined + ? lengthBeforePredictor(expected, readPredictorParams(parm)) : undefined; bytes = applyPredictorIfPresent( inflateTolerant(bytes, inflatedLength).bytes, diff --git a/packages/pdf-codec/src/images-read.ts b/packages/pdf-codec/src/images-read.ts index 5172d9d7e2..55812c554d 100644 --- a/packages/pdf-codec/src/images-read.ts +++ b/packages/pdf-codec/src/images-read.ts @@ -46,6 +46,14 @@ const RGB_CHANNEL_COUNT = 3; // One PDF sample byte's full range (ISO 32000-1 7.4.9's implicit 8-bit-per-sample assumption once BitsPerComponent is scaled up to it), and the width of one byte in bits. const MAX_BYTE_VALUE = 255; const BITS_PER_BYTE = 8; +// The third of PDF's four legal /BitsPerComponent depths for a sampled image (1, 2, 4, 8 — ISO 32000-1 Table 89, or Table 6 in later editions); 1 and 2 need no name of their own, exempt from this rule as structurally self-evident, and 8 reuses BITS_PER_BYTE. This module decodes every one of the four. +const FOUR_BIT_DEPTH = 4; +const SUPPORTED_BITS_PER_COMPONENT: ReadonlySet = new Set([ + 1, + 2, + FOUR_BIT_DEPTH, + BITS_PER_BYTE, +]); function componentsOf(cs: ResolvedColorSpace): number { if (cs.kind === "gray") { @@ -400,20 +408,11 @@ function readSoftMaskAlpha( if (smaskObj?.kind !== "stream") { return undefined; } - const decoded = decodeStream( - smaskObj.raw, - smaskObj.dict, - sink, - undefined, - expectedSampleLength(smaskObj.dict, resolver), - ); - if (decoded.remainingFilter !== undefined) { - return undefined; // an encoded (e.g. DCT) soft mask is out of scope — degrade to no alpha rather than guess - } const smaskWidth = asNumber(dictGet(smaskObj.dict, "Width")) ?? width; const smaskHeight = asNumber(dictGet(smaskObj.dict, "Height")) ?? height; const smaskBpc = asNumber(dictGet(smaskObj.dict, "BitsPerComponent")) ?? BITS_PER_BYTE; + // Checked before the mask is decoded, so a mask that is never used never costs a decode: its size is then the image's own, which readImageXObject has already bounded. if ( smaskWidth !== width || smaskHeight !== height || @@ -421,6 +420,16 @@ function readSoftMaskAlpha( ) { return undefined; // a differently-sized or differently-depthed mask needs resampling this module doesn't do } + const decoded = decodeStream( + smaskObj.raw, + smaskObj.dict, + sink, + undefined, + () => expectedSampleLength(smaskObj.dict, resolver), + ); + if (decoded.remainingFilter !== undefined) { + return undefined; // an encoded (e.g. DCT) soft mask is out of scope — degrade to no alpha rather than guess + } return decoded.bytes.subarray(0, width * height); } @@ -569,7 +578,7 @@ function readJpeg2000Image( }; } -// How many bytes an image's samples take, rows padded to a whole byte (ISO 32000-1 8.9.3), from its dictionary alone: what its stream should decode to, which decodeStream sizes its inflate buffer by. Undefined when the dictionary does not say (no usable size or depth, or a colour space this module does not read), and the stream is then decoded as it would be without it. The colour space is resolved with diagnostics discarded, since readImageXObject resolves it again and reports what it finds. +// How many bytes an image's samples take, rows padded to a whole byte (ISO 32000-1 8.9.3), from its dictionary alone: what its stream should decode to, which decodeStream sizes its inflate buffer by. Undefined when the dictionary does not say, or says something readImageXObject goes on to refuse (no usable size, a size past its PNG ceilings, a depth it does not read, or a colour space it does not read), and the stream is then decoded as it would be without it: a dictionary's size is trusted for a buffer only where it describes an image that would be decoded. The colour space is resolved with diagnostics discarded, since readImageXObject resolves it again and reports what it finds. function expectedSampleLength( dict: PdfDict, resolver: Readonly, @@ -584,10 +593,12 @@ function expectedSampleLength( height === undefined || !Number.isInteger(width) || !Number.isInteger(height) || - !Number.isInteger(bitsPerComponent) || width <= 0 || height <= 0 || - bitsPerComponent <= 0 + width > PNG_MAX_DIMENSION || + height > PNG_MAX_DIMENSION || + width * height > PNG_MAX_PIXELS || + !SUPPORTED_BITS_PER_COMPONENT.has(bitsPerComponent) ) { return undefined; } @@ -628,7 +639,7 @@ export function readImageXObject( dict, sink, (obj) => resolver.resolve(obj), - expectedSampleLength(dict, resolver), + () => expectedSampleLength(dict, resolver), ); const jbig2Original: ExtractedPdfImage["original"] = decoded.jbig2 === undefined @@ -693,14 +704,7 @@ export function readImageXObject( const bitsPerComponent = asNumber(dictGet(dict, "BitsPerComponent") ?? dictGet(dict, "BPC")) ?? BITS_PER_BYTE; - // The third of PDF's four legal /BitsPerComponent depths (1, 2, 4, 8 — ISO 32000-1 Table 89, or Table 6 in later editions); 1 and 2 need no name of their own, exempt from this rule as structurally self-evident, and 8 reuses BITS_PER_BYTE. - const FOUR_BIT_DEPTH = 4; - if ( - bitsPerComponent !== 1 && - bitsPerComponent !== 2 && - bitsPerComponent !== FOUR_BIT_DEPTH && - bitsPerComponent !== BITS_PER_BYTE - ) { + if (!SUPPORTED_BITS_PER_COMPONENT.has(bitsPerComponent)) { sink({ code: "image/unsupported-bit-depth", severity: "warning", From 9c3fa1300e20819dfe731a6911e7350e93f58f1a Mon Sep 17 00:00:00 2001 From: fcbwilliams Date: Tue, 17 Nov 2026 16:02:55 +0100 Subject: [PATCH 06/11] feat(pdf-codec): export pdf-codec/read-images and a locator schema pdf-codec/read-images is now an explicit package entry, with a typesVersions mapping, and the smoke and workerd suites read an image through it. PdfImageLocator moves to its own module with PdfImageLocatorSchema, so a stored locator can be validated. Per-image reading also changes: - A decoded image's bytes are its own, never a view onto the file. - Two references resolving to one stream are listed once. - An inline locator with a negative or fractional index throws PdfImageLocatorError. - Finding an inline image again no longer re-reports its page's diagnostics. Co-Authored-By: Claude Opus 5.5 --- packages/pdf-codec/package.json | 11 + packages/pdf-codec/src/diagnostics.ts | 4 +- packages/pdf-codec/src/image-locator.ts | 31 +++ packages/pdf-codec/src/index.ts | 5 +- packages/pdf-codec/src/read-images.test.ts | 210 +++++++++++++++--- packages/pdf-codec/src/read-images.ts | 153 ++++++++----- packages/pdf-codec/src/read.ts | 15 +- .../src/test-support/image-heavy-pdf.ts | 55 +++++ packages/pdf-codec/test/smoke.test.mjs | 27 +++ .../pdf-codec/test/workers/pdf-codec.test.ts | 19 +- 10 files changed, 431 insertions(+), 99 deletions(-) create mode 100644 packages/pdf-codec/src/image-locator.ts diff --git a/packages/pdf-codec/package.json b/packages/pdf-codec/package.json index 945b9967dd..0318cd40c0 100644 --- a/packages/pdf-codec/package.json +++ b/packages/pdf-codec/package.json @@ -29,6 +29,14 @@ "import": "./dist/read.js", "require": "./dist/read.cjs" }, + "./read-images": { + "types": { + "import": "./dist/read-images.d.ts", + "require": "./dist/read-images.d.cts" + }, + "import": "./dist/read-images.js", + "require": "./dist/read-images.cjs" + }, "./*": { "types": { "import": "./dist/*.d.ts", @@ -45,6 +53,9 @@ "*": { "read": [ "./dist/read.d.ts" + ], + "read-images": [ + "./dist/read-images.d.ts" ] } }, diff --git a/packages/pdf-codec/src/diagnostics.ts b/packages/pdf-codec/src/diagnostics.ts index e1b59f2a1e..a886ff9ead 100644 --- a/packages/pdf-codec/src/diagnostics.ts +++ b/packages/pdf-codec/src/diagnostics.ts @@ -1,5 +1,5 @@ // The parser's three-tier failure policy (throw / recover-with-diagnostic / degrade-with-diagnostic — see the implementation plan's Step 7.5): a hand-written parser measured in low thousands of lines cannot match a mature library's robustness against adversarial or mis-generated real-world input, so it must be explicit about which tier each situation falls into rather than silently picking one. This module is the shared vocabulary every other src/pdf/* read-side module reports through. -import type { PdfImageLocator } from "./read-images"; +import type { PdfImageLocator } from "./image-locator"; export type PdfDiagnosticSeverity = "info" | "warning"; @@ -53,7 +53,7 @@ export class PdfPageSelectionError extends PdfParseError { } /** - * A locator `decodePdfImage` (or `PdfImages.decode`) was given that names no image of the document: an object that is not an image XObject stream (code `pdf/image-not-found`), or an inline image occurrence its page does not hold (the same code; a page index naming no page throws `PdfPageSelectionError` instead). Thrown rather than reported, because a locator comes from a listing of this same file, so one naming nothing means the caller has the wrong file or a wrong locator. + * A locator `decodePdfImage` (or `PdfImages.decode`) was given that names no image of the document: an object that is not an image XObject stream (code `pdf/image-not-found`), or an inline image locator whose page index or occurrence is negative or not an integer, or an occurrence its page does not hold (the same code; a page index naming no page throws `PdfPageSelectionError` instead). Thrown rather than reported, because a locator comes from a listing of this same file, so one naming nothing means the caller has the wrong file or a wrong locator. */ export class PdfImageLocatorError extends PdfParseError { readonly locator: PdfImageLocator; diff --git a/packages/pdf-codec/src/image-locator.ts b/packages/pdf-codec/src/image-locator.ts new file mode 100644 index 0000000000..cade2fa61c --- /dev/null +++ b/packages/pdf-codec/src/image-locator.ts @@ -0,0 +1,31 @@ +import { z } from "zod"; + +// The name per-image reading gives an image, in a module of its own so diagnostics.ts can carry it on PdfImageLocatorError without depending on read-images.ts, and so the schema's zod import stays off the per-image reader's module graph (read-images.ts imports only the type). + +const PdfImageLocatorIndexSchema = z.number().int().nonnegative(); + +/** + * Names one image of a PDF, as `listPdfImages` reports it and `decodePdfImage` takes it back. Plain data, so a caller can store it and decode the image in a later call (or a later process) against the same file bytes; the schema validates one read back from storage. + * + * - `xobject`: an image XObject, by its indirect object reference. One entry covers every place the document draws it. `generation` is informational: the cross-reference table this package reads keeps one entry per object number, so an object is found by its number whatever generation the locator carries. + * - `inline`: an inline image (`BI` ... `ID` ... `EI`), which has no object of its own, by its page's zero-based source index and its position among that page's inline images in content-stream order (counted from 0, every inline image counted, including ones the listing leaves out). Decoding one interprets that page's content again to find it; inline images are small by design (ISO 32000-1 8.9.7 recommends at most 4 KB), and producers rarely write them. + */ +export const PdfImageLocatorSchema = z.discriminatedUnion("kind", [ + z + .object({ + kind: z.literal("xobject"), + objectNumber: PdfImageLocatorIndexSchema, + generation: PdfImageLocatorIndexSchema, + }) + .readonly(), + z + .object({ + kind: z.literal("inline"), + pageIndex: PdfImageLocatorIndexSchema, + occurrence: PdfImageLocatorIndexSchema, + }) + .readonly(), +]); + +/** See `PdfImageLocatorSchema`. */ +export type PdfImageLocator = z.infer; diff --git a/packages/pdf-codec/src/index.ts b/packages/pdf-codec/src/index.ts index 90750178a0..7dff3496f3 100644 --- a/packages/pdf-codec/src/index.ts +++ b/packages/pdf-codec/src/index.ts @@ -1,4 +1,4 @@ -// pdf-codec's public surface: a curated barrel export with exactly one deliberate companion entry — `pdf-codec/read` (package.json's explicit ./read export onto src/read.ts, the read pipeline's own module), the read-only entry whose module graph excludes this barrel's write half and the vendored font assets it eagerly imports. Everything else matches document-schema.js/odf.js/ooxml.js's own barrel-only precedent. What's exported here is every symbol a real external consumer needs — headline read/write/codec entry points, the Layout item family this package owns outright as its native document model (src/layout.ts, exported wholesale below), the formula/math port documents.js's own MathML layout engine passes real values through, the text-layout and font-resolution helpers every layout engine built on this codec needs, and the full bytes/image surface (re-exported from byte-codec, the neutral shared package these pure utilities now live in — see the export site below for exactly why the public surface sources them from there rather than this package's own internal src/bytes/ and src/image/ copies). Internal plumbing (objects.ts, serialize.ts, lexer.ts, parse.ts, xref.ts, document.ts, interpret.ts, content-read.ts, content-write.ts, filters.ts, predictors.ts, images-read.ts, cmap.ts, font-read.ts, font-style.ts, and the cmap-table/hmtx-table/font-tables/glyf/sfnt/sfnt-subset/cff/cff-probe/cff-bounds/tounicode/ot-layout-common/gpos-table/math-font-write/math-content-write/embedded-font-write font-parsing, font-subsetting, and font-embedding internals) stays unexported — math-table.ts is a partial exception, exporting its MathVariants types alone (see below), and glyph-bounds.ts another, exporting the GlyphInkBounds shape those outline readers report through — nothing outside this package's own src/ consumes it today. embedded-font.ts is the one partial exception: its EmbeddedFace is the type ResolvedFace's own 'embedded' variant carries, and its EmbeddedFaceSubstitution is what WritePdfOptions.onMissingGlyph reports, so both must be nameable by an external caller even though nothing else in that module is exported. +// pdf-codec's public surface: a curated barrel export with two deliberate companion entries — `pdf-codec/read` (package.json's explicit ./read export onto src/read.ts, the read pipeline's own module), the read-only entry whose module graph excludes this barrel's write half and the vendored font assets it eagerly imports, and `pdf-codec/read-images` (onto src/read-images.ts), the per-image reader, whose graph excludes readPdf's text pipeline as well. Everything else matches document-schema.js/odf.js/ooxml.js's own barrel-only precedent. What's exported here is every symbol a real external consumer needs — headline read/write/codec entry points, the Layout item family this package owns outright as its native document model (src/layout.ts, exported wholesale below), the formula/math port documents.js's own MathML layout engine passes real values through, the text-layout and font-resolution helpers every layout engine built on this codec needs, and the full bytes/image surface (re-exported from byte-codec, the neutral shared package these pure utilities now live in — see the export site below for exactly why the public surface sources them from there rather than this package's own internal src/bytes/ and src/image/ copies). Internal plumbing (objects.ts, serialize.ts, lexer.ts, parse.ts, xref.ts, document.ts, interpret.ts, content-read.ts, content-write.ts, filters.ts, predictors.ts, images-read.ts, cmap.ts, font-read.ts, font-style.ts, and the cmap-table/hmtx-table/font-tables/glyf/sfnt/sfnt-subset/cff/cff-probe/cff-bounds/tounicode/ot-layout-common/gpos-table/math-font-write/math-content-write/embedded-font-write font-parsing, font-subsetting, and font-embedding internals) stays unexported — math-table.ts is a partial exception, exporting its MathVariants types alone (see below), and glyph-bounds.ts another, exporting the GlyphInkBounds shape those outline readers report through — nothing outside this package's own src/ consumes it today. embedded-font.ts is the one partial exception: its EmbeddedFace is the type ResolvedFace's own 'embedded' variant carries, and its EmbeddedFaceSubstitution is what WritePdfOptions.onMissingGlyph reports, so both must be nameable by an external caller even though nothing else in that module is exported. // Headline: read/write/diagnostics/codec. readPdf/writePdf speak LayoutDocument and there is deliberately no DocumentTree-native pair beside them. On read, PDF states positions, not structure — readPdf yields layout cheaply, and semantic content (paragraphs, headings, tables) only through a separate, lossy reconstruction pass that infers structure from geometry, genuine semantic policy that lives in documents.js (src/layout/reconstruct.ts). On write, a DocumentTree reaches PDF bytes only once a prior layout pass has already stamped frames onto it (a package with no pages, e.g. a bridge conversion's own odt-to-docx dump, cannot reach PDF at all): documents.js's layoutDocumentFromPackage walks those already-stamped frames back into a LayoutDocument, a mechanical inverse rather than a font-measuring, line-breaking pass of its own — the actual layout engine runs earlier, wherever the package first passed through an X-to-PDF or PDF-to-X conversion. ExaDev/pdf-codec#65 scoped the frames-mapping half of this boundary to this package ("readPdf/writePdf ... gain mappings to and from package frames at the edge"); that half was never implemented here and instead lives in documents.js as layoutDocumentFromPackage — a deliberate reassignment, not an oversight, but one #65 itself doesn't record. Adding a DocumentTree-facing wrapper here would mean this package owning either a reconstruction heuristic or a frame-walking pass that depends on a layout stage documents.js runs, and would make pdf-codec depend on the package that depends on it. export type { ReadPdfOptions, ReadPdfSurfaces } from "./read"; @@ -8,12 +8,13 @@ export type { DecodedPdfImage, ListPdfImagesOptions, PdfImageEntry, - PdfImageLocator, PdfImagePlacement, PdfImageReadOptions, PdfImages, } from "./read-images"; export { decodePdfImage, listPdfImages, openPdfImages } from "./read-images"; +export type { PdfImageLocator } from "./image-locator"; +export { PdfImageLocatorSchema } from "./image-locator"; export type { WritePdfOptions } from "./write"; export { PdfPartialDocumentError, writePdf } from "./write"; export { PdfSkippedSurfacesError } from "./write-skipped-surfaces"; diff --git a/packages/pdf-codec/src/read-images.test.ts b/packages/pdf-codec/src/read-images.test.ts index 11e4e5a38b..ef987aac19 100644 --- a/packages/pdf-codec/src/read-images.test.ts +++ b/packages/pdf-codec/src/read-images.test.ts @@ -1,15 +1,22 @@ import { base64ToBytes } from "byte-codec"; +import type * as Fflate from "fflate"; +import { unzlibSync } from "fflate"; import { beforeEach, describe, expect, it, vi } from "vitest"; import type * as ImagesRead from "./images-read"; +import type * as Interpret from "./interpret"; import { sha256 } from "./crypto/sha2"; import type { PdfDiagnostic } from "./diagnostics"; import { PdfImageLocatorError, PdfPageSelectionError } from "./diagnostics"; +import type { PdfImageLocator } from "./image-locator"; +import { PdfImageLocatorSchema } from "./image-locator"; import { readImageXObject } from "./images-read"; +import { interpretContentStream } from "./interpret"; import type { LayoutDocument } from "./layout"; import { readPdf } from "./read"; -import type { PdfImageEntry, PdfImageLocator } from "./read-images"; +import type { PdfImageEntry } from "./read-images"; import { decodePdfImage, listPdfImages, openPdfImages } from "./read-images"; import { + imageEdgeCasesPdf, imageVarietyPdf, pictureDeckPdf, } from "./test-support/image-heavy-pdf"; @@ -24,8 +31,23 @@ vi.mock("./images-read", async (importOriginal) => { return { ...actual, readImageXObject: vi.fn(actual.readImageXObject) }; }); +// Observed the same way: how many pages a call interprets, and which buffers inflate was handed. +vi.mock("./interpret", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + interpretContentStream: vi.fn(actual.interpretContentStream), + }; +}); +vi.mock("fflate", async (importOriginal) => { + const actual = await importOriginal(); + return { ...actual, unzlibSync: vi.fn(actual.unzlibSync) }; +}); + beforeEach(() => { vi.mocked(readImageXObject).mockClear(); + vi.mocked(interpretContentStream).mockClear(); + vi.mocked(unzlibSync).mockClear(); }); function hex(bytes: Uint8Array): string { @@ -56,6 +78,8 @@ function drawnImageIds(doc: LayoutDocument): Set { } const variety = imageVarietyPdf(); +const edgeCases = imageEdgeCasesPdf(); +const pictureDeckQuarter = pictureDeckPdf({ scale: 0.25 }); describe("listPdfImages", () => { it("lists every visible image once, by reference, without decoding any of them", () => { @@ -156,43 +180,102 @@ describe("listPdfImages", () => { expect(openPdfImages(variety).pageCount).toBe(2); const controller = new AbortController(); controller.abort(); - expect(() => - listPdfImages(variety, { signal: controller.signal }), - ).toThrow(); + let thrown: unknown; + try { + listPdfImages(variety, { signal: controller.signal }); + } catch (error) { + thrown = error; + } + expect(thrown).toBeInstanceOf(DOMException); + expect(thrown).toMatchObject({ name: "AbortError" }); + }); + + it("lists an image named through a reference to its reference once, under the first reference drawn", () => { + const [chained] = listPdfImages(edgeCases); + expect(chained?.locator).toEqual({ + kind: "xobject", + objectNumber: 3, + generation: 0, + }); + expect(chained?.placements.map((p) => p.xPt)).toEqual([0, 30]); + }); + + it("counts an inline stencil mask among its page's inline images, without listing it", () => { + const inline = listPdfImages(edgeCases).filter( + (entry) => entry.locator.kind === "inline", + ); + expect(inline.map((entry) => entry.locator)).toEqual([ + { kind: "inline", pageIndex: 0, occurrence: 1 }, + ]); + expect(decodePdfImage(edgeCases, inline[0]!.locator)).toMatchObject({ + format: "png", + widthPx: 1, + heightPx: 1, + }); + // Occurrence 0 is the stencil, which readPdf leaves out of its registry too. + expect( + decodePdfImage(edgeCases, { + kind: "inline", + pageIndex: 0, + occurrence: 0, + }), + ).toBeUndefined(); + }); + + it("reports locators the schema accepts", () => { + for (const entry of listPdfImages(variety)) { + expect(PdfImageLocatorSchema.parse(entry.locator)).toEqual(entry.locator); + } + expect( + PdfImageLocatorSchema.safeParse({ + kind: "inline", + pageIndex: -1, + occurrence: 0, + }).success, + ).toBe(false); }); }); describe("decodePdfImage", () => { - it("decodes one image per call", () => { - const [, gray] = listPdfImages(variety); - const decoded = decodePdfImage(variety, gray!.locator); + it("decodes one image per call, without interpreting any page", () => { + const images = openPdfImages(variety); + const [, gray] = images.list(); + vi.mocked(interpretContentStream).mockClear(); + const decoded = images.decode(gray!.locator); expect(readImageXObject).toHaveBeenCalledTimes(1); + expect(interpretContentStream).not.toHaveBeenCalled(); expect(decoded).toMatchObject({ format: "png", widthPx: 40, heightPx: 30 }); }); - it("decodes each image to exactly the bytes, format, size and id readPdf registers for it", () => { - const doc = readPdf(variety); - const images = openPdfImages(variety); - const decodedIds = new Set(); - for (const entry of images.list()) { - const decoded = images.decode(entry.locator); - if (decoded === undefined) { - continue; + it.each([ + ["the variety fixture", variety], + ["the picture-deck fixture at quarter scale", pictureDeckQuarter], + ] as const)( + "decodes each image of %s to exactly the bytes, format, size and id readPdf registers for it", + (_name, pdf) => { + const doc = readPdf(pdf); + const images = openPdfImages(pdf); + const decodedIds = new Set(); + for (const entry of images.list()) { + const decoded = images.decode(entry.locator); + if (decoded === undefined) { + continue; + } + decodedIds.add(decoded.imageId); + const asset = doc.images[decoded.imageId]; + expect(asset, locatorKey(entry.locator)).toBeDefined(); + expect(asset?.format).toBe(decoded.format); + expect(asset?.widthPx).toBe(decoded.widthPx); + expect(asset?.heightPx).toBe(decoded.heightPx); + expect(hex(base64ToBytes(asset!.base64))).toBe(hex(decoded.bytes)); + // The standalone call opens the file afresh and still decodes the same bytes. + expect(hex(decodePdfImage(pdf, entry.locator)!.bytes)).toBe( + hex(decoded.bytes), + ); } - decodedIds.add(decoded.imageId); - const asset = doc.images[decoded.imageId]; - expect(asset, locatorKey(entry.locator)).toBeDefined(); - expect(asset?.format).toBe(decoded.format); - expect(asset?.widthPx).toBe(decoded.widthPx); - expect(asset?.heightPx).toBe(decoded.heightPx); - expect(hex(base64ToBytes(asset!.base64))).toBe(hex(decoded.bytes)); - // The standalone call opens the file afresh and still decodes the same bytes. - expect(hex(decodePdfImage(variety, entry.locator)!.bytes)).toBe( - hex(decoded.bytes), - ); - } - expect(decodedIds).toEqual(drawnImageIds(doc)); - }); + expect(decodedIds).toEqual(drawnImageIds(doc)); + }, + ); it("leaves out an image readPdf leaves out, with the same diagnostic", () => { const unsupported = listPdfImages(variety).find( @@ -212,6 +295,63 @@ describe("decodePdfImage", () => { ]); }); + it("returns a JPEG's bytes as an array of its own, not a view onto the file", () => { + const jpeg = listPdfImages(variety).find( + (entry) => entry.filters[0] === "DCTDecode", + ); + const decoded = decodePdfImage(variety, jpeg!.locator); + expect(decoded?.format).toBe("jpeg"); + expect(decoded?.bytes.buffer).not.toBe(variety.buffer); + expect(decoded?.bytes.byteLength).toBe(decoded?.bytes.buffer.byteLength); + }); + + it("finds an image by its object number whatever generation the locator names", () => { + const images = openPdfImages(variety); + const named = images.decode({ + kind: "xobject", + objectNumber: 5, + generation: 0, + }); + const otherGeneration = images.decode({ + kind: "xobject", + objectNumber: 5, + generation: 3, + }); + expect(otherGeneration?.imageId).toBe(named?.imageId); + }); + + it("decodes an image without its soft mask when the mask is the wrong size, never inflating the mask", () => { + const decoded = decodePdfImage(edgeCases, { + kind: "xobject", + objectNumber: 4, + generation: 0, + }); + expect(decoded).toMatchObject({ format: "png", widthPx: 2, heightPx: 1 }); + // The image's own stream, and not its 4000x4000 mask's. + expect(unzlibSync).toHaveBeenCalledTimes(1); + }); + + it("never sizes an inflate buffer by a dictionary that declares an image too large to decode", () => { + const diagnostics: PdfDiagnostic[] = []; + expect( + decodePdfImage( + edgeCases, + { kind: "xobject", objectNumber: 7, generation: 0 }, + { + sink: (diagnostic) => { + diagnostics.push(diagnostic); + }, + }, + ), + ).toBeUndefined(); + expect(diagnostics.map((diagnostic) => diagnostic.code)).toContain( + "image/undecodable", + ); + expect( + vi.mocked(unzlibSync).mock.calls.every((call) => call[1] === undefined), + ).toBe(true); + }); + it("refuses a locator that names no image of the document", () => { const images = openPdfImages(variety); // Object 1 is the catalog; object 99 does not exist; the form XObject is a stream, but not an image. @@ -229,6 +369,14 @@ describe("decodePdfImage", () => { expect(() => images.decode({ kind: "inline", pageIndex: 5, occurrence: 0 }), ).toThrow(PdfPageSelectionError); + // A page index counted from the end is a page selection's, never a locator's. + for (const locator of [ + { kind: "inline", pageIndex: -1, occurrence: 0 }, + { kind: "inline", pageIndex: 1, occurrence: -1 }, + { kind: "inline", pageIndex: 1, occurrence: 0.5 }, + ] as const) { + expect(() => images.decode(locator)).toThrow(PdfImageLocatorError); + } }); }); @@ -238,7 +386,7 @@ describe("per-image decoding reproduces pdf-codec 4.5.2's decoded images byte fo ["the variety fixture", variety, IMAGE_VARIETY_4_5_2], [ "the picture-deck fixture at quarter scale", - pictureDeckPdf({ scale: 0.25 }), + pictureDeckQuarter, PICTURE_DECK_QUARTER_4_5_2, ], ] as const)("%s", (_name, pdf, golden) => { @@ -273,7 +421,7 @@ describe("per-image decoding reproduces pdf-codec 4.5.2's decoded images byte fo describe("the picture-deck fixture", () => { it("has the shape of the picture-heavy deck it stands in for", () => { - const listing = listPdfImages(pictureDeckPdf({ scale: 0.25 })); + const listing = listPdfImages(pictureDeckQuarter); expect(listing).toHaveLength(108); expect( listing.filter((entry) => entry.filters[0] === "DCTDecode"), diff --git a/packages/pdf-codec/src/read-images.ts b/packages/pdf-codec/src/read-images.ts index 628ceac57d..bced3da2f2 100644 --- a/packages/pdf-codec/src/read-images.ts +++ b/packages/pdf-codec/src/read-images.ts @@ -1,8 +1,13 @@ import type { PdfDiagnosticSink } from "./diagnostics"; -import { NOOP_DIAGNOSTIC_SINK, PdfImageLocatorError } from "./diagnostics"; +import { + NOOP_DIAGNOSTIC_SINK, + PdfImageLocatorError, + PdfParseError, +} from "./diagnostics"; import { openPdfDocument } from "./document"; import type { PdfDocument } from "./document"; import { filterNames } from "./filters"; +import type { PdfImageLocator } from "./image-locator"; import type { ExtractedPdfImage } from "./images-read"; import { readImageXObject } from "./images-read"; import { interpretContentStream } from "./interpret"; @@ -23,28 +28,9 @@ import { } from "./page-frame"; import { imageIdOf, imagePlacementFrom } from "./read-convert"; import { hasPdfHeader, resolvePageSelection } from "./read-open"; -import { PdfParseError } from "./diagnostics"; import { throwIfAborted } from "./util/abort"; -// The image registry readPdf builds, taken apart into its two halves so a memory-capped caller (a Worker isolate shelving a picture-heavy PDF) can pay for one image at a time: listing finds every image a page draws, where it draws it, and the reference that names it, without decoding any image stream; decoding turns one image, named by that reference, into exactly the bytes readPdf's registry holds for it (the same readImageXObject call on the same stream), without interpreting any page again. readPdf decodes every image during its one pass and keeps each as a base64 string, so its memory grows with the number of images; here nothing outlives the call that decoded it. - -/** - * Names one image of a PDF, as `listPdfImages` reports it and `decodePdfImage` takes it back. Plain data, so a caller can store it and decode the image in a later call (or a later process) against the same file bytes. - * - * - `xobject`: an image XObject, by its indirect object reference. One entry covers every place the document draws it. - * - `inline`: an inline image (`BI` ... `ID` ... `EI`), which has no object of its own, by its page and its position among that page's inline images in content-stream order (counted from 0, every inline image counted, including ones the listing leaves out). Decoding one interprets that page's content again to find it; inline images are small by design (ISO 32000-1 8.9.7 recommends at most 4 KB), and producers rarely write them. - */ -export type PdfImageLocator = - | { - readonly kind: "xobject"; - readonly objectNumber: number; - readonly generation: number; - } - | { - readonly kind: "inline"; - readonly pageIndex: number; - readonly occurrence: number; - }; +// The image registry readPdf builds, taken apart into its two halves so a memory-capped caller (a Worker isolate shelving a picture-heavy PDF) can pay for one image at a time: listing finds every image a page draws, where it draws it, and the reference that names it (image-locator.ts), without decoding any image stream; decoding turns one image, named by that reference, into exactly the bytes readPdf's registry holds for it (the same readImageXObject call on the same stream), without interpreting any page again. readPdf decodes every image during its one pass and keeps each as a base64 string, so its memory grows with the number of images; here nothing outlives the call that decoded it. /** One place a page draws an image: the same placement fields a `readPdf` image item carries, in the same page coordinates. */ export interface PdfImagePlacement { @@ -75,7 +61,7 @@ export interface PdfImageEntry { readonly placements: readonly PdfImagePlacement[]; } -/** One image decoded: exactly the bytes, format and size `readPdf`'s registry holds for it, and the id `readPdf` names it by. */ +/** One image decoded: exactly the bytes, format and size `readPdf`'s registry holds for it, and the id `readPdf` names it by. Its byte arrays are its own, never views onto the PDF file's bytes, so keeping one does not keep the file alive. */ export interface DecodedPdfImage extends ExtractedPdfImage { /** `img` and the CRC-32 of `bytes`, the key `readPdf` registers the image under in `LayoutDocument.images`. */ readonly imageId: string; @@ -84,7 +70,7 @@ export interface DecodedPdfImage extends ExtractedPdfImage { export interface PdfImageReadOptions { /** Receives every recoverable diagnostic, as `readPdf`'s sink does. */ readonly sink?: PdfDiagnosticSink; - /** Checked before the document is opened, before each listed page, and before each decode. */ + /** Checked before the document is opened, before each listed page, and before each decode. The signal given when the document is opened is the one every later `list` and `decode` of it checks. */ readonly signal?: AbortSignal; } @@ -99,15 +85,18 @@ export interface PdfImages { readonly pageCount: number; /** * Lists the images the selected pages draw, without decoding any of them. + * + * The listing follows the images `readPdf`'s pages draw, not its registry: two entries whose streams decode to the same bytes (the same picture stored twice) both appear here, and decode to the same `imageId`, where the registry holds the picture once. A caller storing decoded images by `imageId` stores it once too. * @param options - Which pages to list. * @returns One entry per image XObject drawn (in the order first drawn), and one per inline image, each with every visible placement. + * @throws PdfPageSelectionError if `pages` names a page the document does not have. */ list: (options?: ListPdfImagesOptions) => PdfImageEntry[]; /** * Decodes one image. * @param locator - The image, as a listing of this same file named it. * @returns The image, or undefined for one `readPdf` would leave out of its registry too (an `/ImageMask` stencil, an unsupported filter, colour space or bit depth, an invalid size, or an undecodable stream), with the same diagnostic `readPdf` reports for it. - * @throws PdfImageLocatorError if the locator names no image of this document. + * @throws PdfImageLocatorError if the locator names no image of this document: an object that is not an image XObject stream, or a page index or occurrence that is negative, not an integer, or past the page's inline images. */ decode: (locator: PdfImageLocator) => DecodedPdfImage | undefined; } @@ -225,8 +214,8 @@ function listImages( : resolvePageSelection(options.pages, pageDicts.length); const { layerNameOf } = readOptionalContent(doc.catalog, doc, sink); const entries: PdfImageEntry[] = []; - // Each image XObject's entry, by object number, with the placements still being collected into it. - const xobjects = new Map(); + // Each image XObject's placements, still being collected, by its stream: two references that resolve to one stream (a reference to a reference) name one image, listed under the first reference seen. + const xobjects = new Map(); pageDicts.forEach((page, pageIndex) => { if (selection !== undefined && !selection.has(pageIndex)) { return; @@ -280,13 +269,13 @@ function listImages( if (placement === undefined) { continue; } - const placements = xobjects.get(ref.num); + const placements = xobjects.get(stream); if (placements !== undefined) { placements.push(placement); continue; } const collected = [placement]; - xobjects.set(ref.num, collected); + xobjects.set(stream, collected); entries.push({ locator: { kind: "xobject", @@ -301,13 +290,46 @@ function listImages( return entries; } +// The bytes a decode returns as an array of their own: an image whose stream needs no decoding (a JPEG's, or a JPEG 2000 or JBIG2 original) is otherwise a view onto the file, and would keep the whole file alive for as long as the caller keeps the image. +function detachedFrom( + file: ArrayBufferLike, + bytes: Uint8Array, +): Uint8Array { + return bytes.buffer === file ? bytes.slice() : bytes; +} + +function detachedImage( + file: ArrayBufferLike, + image: ExtractedPdfImage, +): ExtractedPdfImage { + const { original } = image; + return { + ...image, + bytes: detachedFrom(file, image.bytes), + ...(original !== undefined + ? { + original: { + ...original, + bytes: detachedFrom(file, original.bytes), + ...(original.globalsBytes !== undefined + ? { globalsBytes: detachedFrom(file, original.globalsBytes) } + : {}), + }, + } + : {}), + }; +} + +function isLocatorIndex(value: number): boolean { + return Number.isInteger(value) && value >= 0; +} + function decodeImage( doc: PdfDocument, pageDicts: readonly PdfDict[], locator: PdfImageLocator, sink: PdfDiagnosticSink, -): DecodedPdfImage | undefined { - let extracted: ExtractedPdfImage | undefined; +): ExtractedPdfImage | undefined { if (locator.kind === "xobject") { const stream = doc.resolve({ kind: "ref", @@ -324,31 +346,44 @@ function decodeImage( `object ${String(locator.objectNumber)} ${String(locator.generation)} R is not an image XObject stream of this document`, ); } - extracted = readImageXObject(stream.dict, stream.raw, doc, sink); - } else { - // The page index is resolved like a one-page selection, so a locator naming no page throws PdfPageSelectionError as a selection would. - const [pageIndex = 0] = resolvePageSelection( - [locator.pageIndex], - pageDicts.length, + return readImageXObject(stream.dict, stream.raw, doc, sink); + } + // A locator's page index is the page's own source index, as a listing reports it, never one counted from the end as a page selection's may be. + if ( + !isLocatorIndex(locator.pageIndex) || + !isLocatorIndex(locator.occurrence) + ) { + throw new PdfImageLocatorError( + locator, + `an inline image locator's pageIndex and occurrence are non-negative integers (got ${String(locator.pageIndex)} and ${String(locator.occurrence)})`, ); - const page = pageDicts[pageIndex]; - const inline = - page === undefined - ? undefined - : interpretPage(doc, pageIndex, page, undefined, sink)?.items.filter( - (item) => item.kind === "inlineImage", - )[locator.occurrence]; - if (inline === undefined) { - throw new PdfImageLocatorError( - locator, - `page ${String(locator.pageIndex)} holds no inline image at occurrence ${String(locator.occurrence)}`, - ); - } - extracted = readImageXObject(inline.dict, inline.data, doc, sink); } - return extracted === undefined - ? undefined - : { ...extracted, imageId: imageIdOf(extracted.bytes) }; + // Resolved like a one-page selection, so a locator naming no page throws PdfPageSelectionError as a selection would. + const [pageIndex = 0] = resolvePageSelection( + [locator.pageIndex], + pageDicts.length, + ); + const page = pageDicts[pageIndex]; + // The page's own diagnostics were reported when it was listed; finding the image again reports nothing new, and only the image's decode below reports to the caller. + const inline = + page === undefined + ? undefined + : interpretPage( + doc, + pageIndex, + page, + undefined, + NOOP_DIAGNOSTIC_SINK, + )?.items.filter((item) => item.kind === "inlineImage")[ + locator.occurrence + ]; + if (inline === undefined) { + throw new PdfImageLocatorError( + locator, + `page ${String(locator.pageIndex)} holds no inline image at occurrence ${String(locator.occurrence)}`, + ); + } + return readImageXObject(inline.dict, inline.data, doc, sink); } /** @@ -356,7 +391,7 @@ function decodeImage( * @param bytes - The PDF file. * @param options - A diagnostic sink and an abort signal. * @returns The document's images, listed and decoded on request. - * @throws PdfParseError (or a subclass) for a file that cannot be opened at all, as `readPdf` does. + * @throws PdfParseError (or a subclass) for a file that cannot be opened at all, as `readPdf` does; a DOMException named AbortError if the signal is already aborted. */ export function openPdfImages( bytes: Uint8Array, @@ -379,7 +414,13 @@ export function openPdfImages( listImages(doc, pageDicts, listOptions, signal, sink), decode: (locator) => { throwIfAborted(signal); - return decodeImage(doc, pageDicts, locator, sink); + const extracted = decodeImage(doc, pageDicts, locator, sink); + if (extracted === undefined) { + return undefined; + } + // The id is the CRC-32 of the same bytes either way: detaching copies them, never changes them. + const image = detachedImage(bytes.buffer, extracted); + return { ...image, imageId: imageIdOf(image.bytes) }; }, }; } @@ -389,6 +430,7 @@ export function openPdfImages( * @param bytes - The PDF file. * @param options - Which pages to list, a diagnostic sink and an abort signal. * @returns One entry per image (see `PdfImages.list`). + * @throws PdfParseError (or a subclass) for a file that cannot be opened; PdfPageSelectionError for a page the document does not have; a DOMException named AbortError once the signal is aborted. */ export function listPdfImages( bytes: Uint8Array, @@ -403,6 +445,7 @@ export function listPdfImages( * @param locator - The image. * @param options - A diagnostic sink and an abort signal. * @returns The image, byte-identical to `readPdf`'s registry entry for it, or undefined for one `readPdf` would leave out (see `PdfImages.decode`). + * @throws PdfParseError (or a subclass) for a file that cannot be opened; PdfImageLocatorError for a locator naming no image of it; PdfPageSelectionError for an inline locator's page the document does not have; a DOMException named AbortError if the signal is already aborted. */ export function decodePdfImage( bytes: Uint8Array, diff --git a/packages/pdf-codec/src/read.ts b/packages/pdf-codec/src/read.ts index 4155a77961..7ef82d32d1 100644 --- a/packages/pdf-codec/src/read.ts +++ b/packages/pdf-codec/src/read.ts @@ -30,16 +30,17 @@ import type { FontResolverService } from "./font-read"; import { createFontResolver } from "./font-read"; import type { PdfObjectResolver } from "./interpret-types"; import { interpretContentStream } from "./interpret"; -import type { PageBoxRect } from "./page-frame"; -import { - itemIntersectsVisibleRegion, - readPageContentBytes, - readPageFrame, +import type { + PageBoxRect, + PageRotation, + PageRotationResult, } from "./page-frame"; -import type { PageRotation, PageRotationResult } from "./page-frame"; import { + itemIntersectsVisibleRegion, normalizeRotation as normalizePageRotation, pageRotationTransform as pageRotationMatrix, + readPageContentBytes, + readPageFrame, } from "./page-frame"; import type { DestinationRegistry } from "./navigation"; import { createDestinationRegistry, readOutline } from "./navigation"; @@ -242,8 +243,6 @@ function noStructureOwner(): undefined { return undefined; } -// --- Page geometry: MediaBox origin shift + /Rotate, composed into one matrix applied to every extracted item on the page. --- - // --- Page rotation: implemented in page-frame.ts (which the image listing loads without this module's text pipeline), and still served from here, where the pdf-codec/read entry has always exported them. --- /** diff --git a/packages/pdf-codec/src/test-support/image-heavy-pdf.ts b/packages/pdf-codec/src/test-support/image-heavy-pdf.ts index c1cb47c065..8f1f45322c 100644 --- a/packages/pdf-codec/src/test-support/image-heavy-pdf.ts +++ b/packages/pdf-codec/src/test-support/image-heavy-pdf.ts @@ -6,6 +6,7 @@ import { seededRandom } from "./seeded-random"; // Picture-heavy PDF fixtures for the per-image reader (read-images.ts), built like every fixture in pdf.ts: by literal concatenation through FixtureBuilder, never through this package's own writer. Two shapes: // // - imageVarietyPdf: one small image of each kind the read path decodes differently (Flate RGB with a soft mask, PNG-predicted ICC RGB, inverted gray, indexed, 1-bit, CMYK, a JPEG passed through, an image inside a form XObject, an inline image), plus the cases the listing has to leave out or report as undecodable. Its objects are numbered in a fixed order (images from 3, image 0's soft mask straight after it, then the ICC profile and the form), which read-images.test.ts names them by. Its decoded bytes are pinned against pdf-codec 4.5.2's (image-heavy-pdf-golden.ts). +// - imageEdgeCasesPdf: one page of the cases a locator has to survive: an image named through a reference to its reference, an image whose soft mask is the wrong size to use, one whose dictionary declares more pixels than any image decodes to, and an inline stencil mask before an inline image. // - pictureDeckPdf: shaped like a typical picture-heavy slide deck (20 pages, about a hundred distinct images, most of them Flate RGB with soft masks and the largest 2360x1309, the rest JPEG), generated from a seed. At full scale it is about 2.5 MB; `scale` shrinks every image's pixel size for a unit test that wants the same structure without the cost. const PAGE_WIDTH_PT = 960; @@ -392,6 +393,60 @@ export function imageVarietyPdf(): Uint8Array { ]); } +/** + * One page of the edge cases per-image reading has to handle, numbered for read-images.test.ts: + * + * - 3: a 2x1 Flate RGB image, drawn as /A and again as /B through object 6, which holds only a reference to 3. + * - 4: a 2x1 Flate RGB image whose soft mask (object 5) declares 4000x4000, a size readImageXObject does not resample, so it is never used. + * - 7: a Flate gray image whose dictionary declares 10001x10000 (past encodePng's pixel ceiling) over a stream of about 100 KB. + * - two inline images: a stencil mask (`/IM true`, occurrence 0, never listed) and a 1x1 RGB image (occurrence 1). + * @returns The PDF. + */ +export function imageEdgeCasesPdf(): Uint8Array { + const images: FixtureImage[] = [ + rgbImage(2, 1, 1, 0, false), + { + ...rgbImage(2, 1, 2, 0, false), + smask: { + dict: "<< /Type /XObject /Subtype /Image /Width 4000 /Height 4000 /ColorSpace /DeviceGray /BitsPerComponent 8 /Filter /FlateDecode >>", + data: flate(new Uint8Array(4)), + }, + }, + ]; + const content = new ByteWriter(); + content.writeAscii( + [ + drawAt("A", 0, 0, 20, 10), + drawAt("B", 30, 0, 20, 10), + drawAt("C", 60, 0, 20, 10), + drawAt("D", 90, 0, 20, 10), + "q 8 0 0 1 120 0 cm BI /IM true /W 8 /H 1 ID U EI Q", + "q 10 0 0 10 150 0 cm BI /W 1 /H 1 /CS /RGB /BPC 8 ID abc EI Q\n", + ].join("\n"), + ); + return assemble( + images, + [ + { + xobjects: { + A: "@image:0", + B: "@extra:0", + C: "@image:1", + D: "@extra:1", + }, + content: content.toBytes(), + }, + ], + [ + { dict: "@image:0" }, + { + dict: "<< /Type /XObject /Subtype /Image /Width 10001 /Height 10000 /ColorSpace /DeviceGray /BitsPerComponent 8 /Filter /FlateDecode >>", + data: flate(photoSamples(320, 320, 1, 5, 255)), + }, + ], + ); +} + /** The picture-deck fixture's options. */ export interface PictureDeckOptions { /** Multiplies every image's pixel width and height (default 1, the full-size shape). */ diff --git a/packages/pdf-codec/test/smoke.test.mjs b/packages/pdf-codec/test/smoke.test.mjs index 5c2fefc71b..a6bc4ee302 100644 --- a/packages/pdf-codec/test/smoke.test.mjs +++ b/packages/pdf-codec/test/smoke.test.mjs @@ -3,11 +3,13 @@ import { createRequire } from 'node:module'; import { describe, expect, it } from 'vitest'; import * as esm from '../dist/index.js'; import * as esmRead from '../dist/read.js'; +import * as esmReadImages from '../dist/read-images.js'; import * as esmPdfText from '../dist/pdf-text.js'; const require = createRequire(import.meta.url); const cjs = require('../dist/index.cjs'); const cjsRead = require('../dist/read.cjs'); +const cjsReadImages = require('../dist/read-images.cjs'); const cjsPdfText = require('../dist/pdf-text.cjs'); // A representative slice of the public surface, not an exhaustive list — enough to catch a genuinely broken dual build without duplicating src/index.ts's own export list here. Classes (ByteReader, ByteWriter, PdfParseError, PdfEncryptedError) are real invocable functions at runtime (typeof === 'function'), so they're checked here alongside ordinary functions rather than in OBJECTS below. @@ -174,6 +176,31 @@ describe.each([ }); }); +// The per-image entry (package.json `./read-images` -> dist/read-images.js/.cjs): loads in both builds and lists and decodes a PDF's image through the built artifact, to the bytes and id readPdf registers for it. Like the read entry, its module graph's width is held at the source level by src/read-graph.test.ts. +describe.each([ + ['ESM', esmReadImages], + ['CJS', cjsReadImages], +])('%s read-images entry', (_label, api) => { + it('lists a PDF\'s image without decoding it, then decodes it to exactly what readPdf registers', () => { + const rgb = new Uint8Array([255, 0, 0, 0, 255, 0, 0, 0, 255, 255, 255, 255]); + const png = esm.encodePng({ width: 2, height: 2, channels: 3, data: rgb }); + const pdfBytes = esm.writePdf({ + formatVersion: 1, + metadata: {}, + pages: [{ widthPt: 200, heightPt: 100, items: [{ kind: 'image', imageId: 'pixel', xPt: 10, yPt: 10, widthPt: 40, heightPt: 40 }] }], + images: { pixel: { format: 'png', base64: Buffer.from(png).toString('base64'), widthPx: 2, heightPx: 2 } }, + }); + expect(typeof api.openPdfImages).toBe('function'); + const listing = api.listPdfImages(pdfBytes); + expect(listing).toHaveLength(1); + expect(listing[0]).toMatchObject({ widthPx: 2, heightPx: 2, placements: [{ pageIndex: 0, widthPt: 40, heightPt: 40 }] }); + const decoded = api.decodePdfImage(pdfBytes, listing[0].locator); + const registered = esmRead.readPdf(pdfBytes).images[decoded.imageId]; + expect(registered).toBeDefined(); + expect(Buffer.from(decoded.bytes).toString('base64')).toBe(registered.base64); + }); +}); + // The pdf-text deep module (package.json `./*` wildcard -> dist/pdf-text.js/.cjs): PDF string/date scalar decoding lives here, not on the read entry, per the README's entry-surface note — the read entry carries only readPdf and the read pipeline's own helpers, while pdf-codec/pdf-text stays deep-importable and asset-free the same way. This block proves that advertised deep surface actually loads from the built artifact in both module formats. describe.each([ ['ESM', esmPdfText], diff --git a/packages/pdf-codec/test/workers/pdf-codec.test.ts b/packages/pdf-codec/test/workers/pdf-codec.test.ts index c0d8154363..4c06425910 100644 --- a/packages/pdf-codec/test/workers/pdf-codec.test.ts +++ b/packages/pdf-codec/test/workers/pdf-codec.test.ts @@ -1,6 +1,8 @@ import { describe, expect, it } from 'vitest'; +import { bytesToBase64 } from 'byte-codec'; import { readPdf } from '../../src/read'; -import { createFontRegistry, writePdf } from '../../src'; +import { decodePdfImage, listPdfImages } from '../../src/read-images'; +import { createFontRegistry, encodePng, writePdf } from '../../src'; // Proves pdf-codec's read path executes inside a Cloudflare Workers isolate (workerd, via @cloudflare/vitest-pool-workers) with no Node-only APIs. The read test imports through src/read.ts — the module behind the package.json `./read` entry point — so one test proves both that the read pipeline executes in the isolate and that the read-only entry itself works; the module-graph-width half of that entry's guarantee is held separately by src/read-graph.test.ts. The write test below exercises the opposite end: a real font registry resolving Calibri onto the vendored, metric-compatible Carlito face, which decodes the embedded asset, subsets it, and embeds a genuine TrueType font program — exactly the modules the read entry exists to exclude, proven to run in the isolate when a caller does want them. Fixtures are built inline rather than read from disk because workerd exposes no node:fs — and building them from the package's own format rules (object table, classic cross-reference, parenthesised content-stream string) is itself a check that nothing in the construction path needs Node either. This is the runtime complement to attw's static module-resolution check. @@ -67,6 +69,21 @@ describe('pdf-codec under the Cloudflare Workers runtime', () => { expect(textItems[0]).toMatchObject({ kind: 'text', text: 'Hello' }); }); + it('lists and decodes a PDF\'s image one at a time (via the ./read-images entry module) inside a workerd isolate', () => { + const png = encodePng({ width: 2, height: 1, channels: 3, data: new Uint8Array([255, 0, 0, 0, 0, 255]) }); + const pdfBytes = writePdf({ + formatVersion: 1, + metadata: {}, + pages: [{ widthPt: 200, heightPt: 100, items: [{ kind: 'image', imageId: 'pixels', xPt: 10, yPt: 10, widthPt: 40, heightPt: 20 }] }], + images: { pixels: { format: 'png', base64: bytesToBase64(png), widthPx: 2, heightPx: 1 } }, + }); + const [entry] = listPdfImages(pdfBytes); + expect(entry).toMatchObject({ widthPx: 2, heightPx: 1, placements: [{ pageIndex: 0 }] }); + const decoded = decodePdfImage(pdfBytes, entry!.locator); + expect(decoded).toMatchObject({ format: 'png', widthPx: 2, heightPx: 1 }); + expect(bytesToBase64(decoded!.bytes)).toBe(readPdf(pdfBytes).images[decoded!.imageId]?.base64); + }); + it('writePdf embeds the vendored Carlito face through a font registry inside a workerd isolate', () => { // Read a real document back, relabel its one text run's family as Calibri, and write it through a registry: the registry resolves Calibri onto the vendored Carlito face, so this exercises the asset modules the read-only entry exists to exclude — font-registry.ts's module-scope asset imports, the sfnt parse, the glyph subsetting, and the /Type0 + /CIDFontType2 + /FontFile2 embedding group — inside the isolate. const doc = readPdf(minimalClassicXrefPdf()); From d7166d82bdecfb6d75ea1c80f57e975cbdee1f96 Mon Sep 17 00:00:00 2001 From: fcbwilliams Date: Tue, 17 Nov 2026 16:03:11 +0100 Subject: [PATCH 07/11] docs(pdf-codec): give per-image reading's memory with and without GC The README now leads its per-image example with openPdfImages from pdf-codec/read-images. It gives the measured peaks both with a collection forced before each image and left to the collector, which is what a Worker sees. It also states the failure policy for locators, that two entries can decode to one imageId, and that an open encrypted document keeps the streams it has decrypted. The measuring script says it reports heap in use, not committed heap, and that its timings are taken under sampling. Co-Authored-By: Claude Opus 5.5 --- packages/pdf-codec/README.md | 41 ++++++++++++------- .../scripts/measure-image-memory.mjs | 9 ++-- 2 files changed, 33 insertions(+), 17 deletions(-) diff --git a/packages/pdf-codec/README.md b/packages/pdf-codec/README.md index 62644d9b53..124d2550c6 100644 --- a/packages/pdf-codec/README.md +++ b/packages/pdf-codec/README.md @@ -115,28 +115,39 @@ Each surface, and what page items lose without it (everything else about every p 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. -**Reading images one at a time.** `readPdf` decodes every image a read page draws in its one synchronous call and keeps each in `LayoutDocument.images` as a base64 string, so its memory grows with the number of images as well as the size of the largest. For a picture-heavy file in a memory-capped runtime (a Cloudflare Worker isolate's 128 MB, which counts typed-array buffers as well as the V8 heap), `listPdfImages` and `decodePdfImage` take that registry apart: +**Reading images one at a time.** `readPdf` decodes every image a read page draws in its one synchronous call and keeps each in `LayoutDocument.images` as a base64 string, so its memory grows with the number of images as well as the size of the largest. For a picture-heavy file in a memory-capped runtime (a Cloudflare Worker isolate's 128 MB, which counts typed-array buffers as well as the V8 heap), `openPdfImages` takes that registry apart. Import it from `pdf-codec/read-images`, which loads neither the write half nor `readPdf`'s text pipeline: ```ts -import { decodePdfImage, listPdfImages, openPdfImages } from "pdf-codec"; +import { openPdfImages } from "pdf-codec/read-images"; +// Open the file once: listing and every decode share its parsed cross-reference table and object streams. +const images = openPdfImages(pdfBytes, { signal }); // Every image the pages draw, by reference, with where each is drawn; no image stream is decoded. -const listing = listPdfImages(pdfBytes); // PdfImageEntry[] -for (const entry of listing) { - // One image, to exactly the bytes, format, size and imageId readPdf's registry holds for it. - const image = decodePdfImage(pdfBytes, entry.locator); // DecodedPdfImage | undefined -} - -// Or open the file once and decode through the same opened document, so its cross-reference table and object streams are parsed once. -const images = openPdfImages(pdfBytes); for (const entry of images.list({ pages: [0, 1] })) { - images.decode(entry.locator); + // One image, to exactly the bytes, format, size and imageId readPdf's registry holds for it. + const image = images.decode(entry.locator); // DecodedPdfImage | undefined + if (image !== undefined) { + await store(image.imageId, image.bytes); // two entries can decode to one imageId: store by it + } } ``` -A `PdfImageLocator` is plain data: an image XObject's object reference (`{ kind: "xobject", objectNumber, generation }`), or for an inline image, which has no object, its page and position among that page's inline images (`{ kind: "inline", pageIndex, occurrence }`). A caller can store one and decode the image in a later call, or a later process, against the same file bytes. Decoding an image XObject interprets no page at all; decoding an inline image interprets its own page's content again to find it (inline images are small by design, and rare). Each `PdfImageEntry` carries the image's `placements` (its page, `xPt`/`yPt`/`widthPt`/`heightPt`, `rotationDeg` and `layer`, exactly as `readPdf`'s image items state them), plus what its dictionary declares without decoding: `widthPx`/`heightPx`, `filters`, `softMask` and `encodedByteLength`. The listing holds the images `readPdf`'s pages draw: an image drawn only outside its page's crop box, and an `/ImageMask` stencil, are not listed, and an image whose decoding `readPdf` would refuse (an unsupported filter, colour space or bit depth) is listed and decodes to `undefined`, with the same diagnostic. A locator naming no image of the file throws `PdfImageLocatorError`. The structure-ownership association (`structure`) is not reported, since reading it needs the whole structure tree. +`listPdfImages(bytes, options)` and `decodePdfImage(bytes, locator, options)` are the same two calls on a file opened afresh each time, for a caller that decodes in a later call or process than it lists. The root `pdf-codec` barrel exports all three as well, at the cost of loading its write half. + +A `PdfImageLocator` is plain data: an image XObject's object reference (`{ kind: "xobject", objectNumber, generation }`, where the object is found by its number and `generation` is informational), or for an inline image, which has no object, its page's source index and position among that page's inline images (`{ kind: "inline", pageIndex, occurrence }`, both non-negative integers). A caller can store one, validate it on the way back in with `PdfImageLocatorSchema`, and decode the image in a later call, or a later process, against the same file bytes. Decoding an image XObject interprets no page at all; decoding an inline image interprets its own page's content again to find it (inline images are small by design, and rare). Each `PdfImageEntry` carries the image's `placements` (its page, `xPt`/`yPt`/`widthPt`/`heightPt`, `rotationDeg` and `layer`, exactly as `readPdf`'s image items state them), plus what its dictionary declares without decoding: `widthPx`/`heightPx`, `filters`, `softMask` and `encodedByteLength`. The listing follows the images `readPdf`'s pages draw, not its registry: an image drawn only outside its page's crop box, and an `/ImageMask` stencil, are not listed; an image whose decoding `readPdf` would refuse (an unsupported filter, colour space or bit depth) is listed and decodes to `undefined`, with the same diagnostic; and two image objects holding the same picture are two entries that decode to one `imageId`, where the registry holds it once. A decoded image's byte arrays are its own, never views onto the file, so keeping one does not keep the file alive. The `signal` given to `openPdfImages` is the one each later `list` and `decode` of that document checks. The structure-ownership association (`structure`) is not reported, since reading it needs the whole structure tree. -The decoded bytes are those `readPdf` produces for the same image, which are those pdf-codec 4.5.2 produced (pinned in `src/read-images.test.ts` against digests recorded from 4.5.2), so an image stored by an earlier release keeps its identity. Decoding one image holds its decoded samples, its alpha plane and the PNG encoder's filtered rows and deflate buffer at once, in proportion to its pixels: a 2360x1309 RGB image with a soft mask needs about 40 MB on top of the module and the file. `pdf-codec/read-images` serves the three functions without the text pipeline `readPdf` loads (font resolution and its glyph tables, about 12 MB of heap), and `scripts/measure-image-memory.mjs` measures a generated picture-heavy fixture against the built `dist/`: about 56 MB peak for listing and decoding its 108 images one at a time, against about 140 MB for `readPdf` in 5.8 and 526 MB in 4.5.2. +Failures follow the [read failure policy](#conventions): a file that cannot be opened throws as `readPdf` does; a locator naming no image of the file (an object that is not an image XObject, or an inline locator with a negative or fractional index, or an occurrence its page does not hold) throws `PdfImageLocatorError`, code `pdf/image-not-found`; an inline locator's page the document does not have throws `PdfPageSelectionError`; and an aborted signal throws a `DOMException` named `AbortError`. In an encrypted file, the document keeps each stream it has decrypted for as long as it stays open, as `readPdf`'s does, so an opened `PdfImages` holds every decoded image's encrypted stream in the clear until it is dropped; for an encrypted file, open a fresh one per batch of images rather than keeping one open across all of them. + +The decoded bytes are those `readPdf` produces for the same image, which are those pdf-codec 4.5.2 produced (pinned in `src/read-images.test.ts` against digests recorded from 4.5.2), so an image stored by an earlier release keeps its identity. Decoding one image holds its decoded samples, its alpha plane and the PNG encoder's filtered rows and deflate buffer at once, in proportion to its pixels: a 2360x1309 RGB image with a soft mask needs about 40 MB on top of the module and the file. `pdf-codec/read-images` serves the three functions without the text pipeline `readPdf` loads (font resolution and its glyph tables, about 12 MB of heap). `scripts/measure-image-memory.mjs` measures a generated picture-heavy fixture (2.4 MB, 108 images) against the built `dist/`, as the peak of the V8 heap in use plus every `ArrayBuffer`'s backing store: + +| Read | Collecting before each image (`--gc`) | Left to the collector | +| ------------------------------------- | ------------------------------------- | ------------------------------------ | +| One image at a time (`openPdfImages`) | about 56 MB | 57-63 MB in most runs, 70 MB in some | +| `readPdf` | 83-87 MB | 86-96 MB | +| `readPdf` in pdf-codec 5.8 | 140-148 MB | 139-148 MB | +| `readPdf` in pdf-codec 4.5.2 | about 526 MB | about 526 MB | + +A Worker cannot force a collection, so its figure is the right-hand one: what an image leaves behind counts until the collector reclaims it, which in most runs it has before the next large image and in some it has not. **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. @@ -287,6 +298,8 @@ One subpath is a declared entry point in its own right: **`pdf-codec/read`** (an import { readPdf } from "pdf-codec/read"; ``` +A second declared entry, **`pdf-codec/read-images`** (onto `src/read-images.ts`), serves `openPdfImages`, `listPdfImages` and `decodePdfImage` (see "Reading images one at a time" under [Usage](#usage)) with a narrower graph still: none of the write half, and none of `readPdf`'s text pipeline either. + `src/read-graph.test.ts` walks the entry's static import graph and fails the build if `write.ts`, `math-font.ts`, `font-registry.ts`, or any asset module becomes reachable (type-only imports are exempt — they erase at compile time — so a read-side module can keep typing against the root barrel's types while its runtime graph stays narrow). The entry carries `readPdf` and the read pipeline's own helpers (`normalizeRotation`, `pageRotationTransform`); the other read-adjacent surfaces it does not itself own stay deep-importable through the wildcard and are asset-free the same way — the diagnostics vocabulary (`pdf-codec/diagnostics`), the `LayoutDocument` item family (`pdf-codec/layout`), PDF string/date scalar decoding (`pdf-codec/pdf-text`), standard-14 resolution/AFM metrics (`pdf-codec/fonts`, `pdf-codec/afm-widths`), and the rasterisation port (`pdf-codec/raster`, whose glyph machinery reads outlines out of the page's own embedded font programs rather than any vendored face). ## Architecture @@ -320,7 +333,7 @@ Dependency direction is strictly downward and checkable: `layout` imports only ` - **`PdfObject` has no Zod schema at all**, deliberately: it never crosses a public boundary or round-trips through JSON, and is constructed exclusively by this package's own parser. It narrows natively on its own `kind` discriminant. - **The `MathBox`/`MathFontMetrics` family is structurally typed on purpose, not validated by Zod** — the mechanism that lets a caller (`documents.js`) hand this package a real value produced by a completely independent module, with zero cast, zero wrapper, and no shared class or branded type. - **No type assertions anywhere.** Every third-party or loosely-typed value is narrowed through a type guard or a Zod parse at the boundary. -- **A three-tier PDF-read failure policy**: throw a typed `PdfParseError`/`PdfEncryptedError`/`PdfPasswordRequiredError` for a file that cannot be meaningfully processed at all (or `PdfPageSelectionError` for a page selection naming no page of it); recover with a `PdfDiagnostic` (`severity: 'warning'`) for something malformed but salvageable; degrade with a diagnostic for an individual unsupported feature while the rest of the document still reads. +- **A three-tier PDF-read failure policy**: throw a typed `PdfParseError`/`PdfEncryptedError`/`PdfPasswordRequiredError` for a file that cannot be meaningfully processed at all (or `PdfPageSelectionError` for a page selection naming no page of it, or `PdfImageLocatorError` for an image locator naming no image of it); recover with a `PdfDiagnostic` (`severity: 'warning'`) for something malformed but salvageable; degrade with a diagnostic for an individual unsupported feature while the rest of the document still reads. - **Conventional commits**, enforced via commitlint + husky. ## Gotchas and quirks diff --git a/packages/pdf-codec/scripts/measure-image-memory.mjs b/packages/pdf-codec/scripts/measure-image-memory.mjs index 7c6d5113f7..3895fc95a2 100644 --- a/packages/pdf-codec/scripts/measure-image-memory.mjs +++ b/packages/pdf-codec/scripts/measure-image-memory.mjs @@ -5,7 +5,7 @@ // // read-pdf mode takes --read-entry= to measure an earlier release the same way, e.g. one installed with `npm install pdf-codec@5.8.6` in a scratch directory. // -// The PDF is src/test-support/image-heavy-pdf.ts's pictureDeckPdf: shaped like a typical picture-heavy slide deck (about 2.5 MB, 108 images, Flate RGB with soft masks up to 2360x1309), generated, never a real document. The read runs in a worker thread, and this thread samples the worker's V8 heap statistics continuously while it runs: worker.getHeapStatistics() is answered through a V8 interrupt, so it samples inside a synchronous decode too, not only between calls. The figure reported is the peak of used_heap_size + external_memory, the second of which holds every ArrayBuffer's backing store: a typed array's bytes sit outside the V8 heap (and outside --max-old-space-size) but count towards a Cloudflare Worker isolate's 128 MB all the same. Garbage counts until the collector runs; --gc collects before each image, which shows what the decode itself needs at once rather than what the collector has yet to reclaim. +// The PDF is src/test-support/image-heavy-pdf.ts's pictureDeckPdf: shaped like a typical picture-heavy slide deck (about 2.5 MB, 108 images, Flate RGB with soft masks up to 2360x1309), generated, never a real document. The read runs in a worker thread, and this thread samples the worker's V8 heap statistics continuously while it runs: worker.getHeapStatistics() is answered through a V8 interrupt, so it samples inside a synchronous decode too, not only between calls. The figure reported is the peak of used_heap_size + external_memory, the second of which holds every ArrayBuffer's backing store: a typed array's bytes sit outside the V8 heap (and outside --max-old-space-size) but count towards a Cloudflare Worker isolate's 128 MB all the same. This is the heap in use, not the heap V8 has committed (which is larger, and is what process RSS shows). Garbage counts until the collector runs; --gc collects before each image, which shows what the decode itself needs at once rather than what the collector has yet to reclaim. A Worker cannot force a collection, so the run without --gc is the one a Worker sees, and it varies from run to run with when the collector happens to run. The time reported is measured while this thread samples the worker continuously, which slows it, so it is a comparison between modes rather than what a read costs on its own. import { Worker } from "node:worker_threads"; import { fileURLToPath } from "node:url"; import { createJiti } from "jiti"; @@ -18,7 +18,10 @@ const readEntryArgument = process.argv.find((argument) => const readEntry = readEntryArgument === undefined ? new URL("../dist/read.js", import.meta.url).href - : new URL(readEntryArgument.slice("--read-entry=".length), `file://${process.cwd()}/`).href; + : new URL( + readEntryArgument.slice("--read-entry=".length), + `file://${process.cwd()}/`, + ).href; if (mode !== "per-image" && mode !== "read-pdf") { throw new Error(`unknown mode ${mode}: per-image or read-pdf`); } @@ -85,5 +88,5 @@ console.log( `images: ${String(report.images)} decoded (${String(report.pngs)} PNG, ${String(report.jpegs)} JPEG), largest ${report.largest}`, ); console.log( - `time: ${String(Math.round(report.wallMs))} ms wall, ${String(Math.round(report.cpuMs))} ms CPU`, + `time, measured under continuous sampling: ${String(Math.round(report.wallMs))} ms wall, ${String(Math.round(report.cpuMs))} ms CPU`, ); From 716ed94c25661a12b57df071c5a0329254bd430b Mon Sep 17 00:00:00 2001 From: fcbwilliams Date: Tue, 17 Nov 2026 16:28:36 +0100 Subject: [PATCH 08/11] fix(pdf-codec): never act on an inflate size hint past 32 MiB A dictionary can state any size up to its stream's deflate bound, and a Worker isolate ends rather than throws on an allocation that large, so an expected length past 32 MiB is inflated into a growable buffer instead. Co-Authored-By: Claude Opus 5.5 --- packages/pdf-codec/src/bytes/flate.test.ts | 25 ++++++++++++++++++++++ packages/pdf-codec/src/bytes/flate.ts | 12 ++++++++--- 2 files changed, 34 insertions(+), 3 deletions(-) diff --git a/packages/pdf-codec/src/bytes/flate.test.ts b/packages/pdf-codec/src/bytes/flate.test.ts index f9230a1cd2..47811b12ea 100644 --- a/packages/pdf-codec/src/bytes/flate.test.ts +++ b/packages/pdf-codec/src/bytes/flate.test.ts @@ -2,6 +2,7 @@ import type * as Fflate from "fflate"; import { deflateSync, unzlibSync } from "fflate"; import { describe, expect, it, vi } from "vitest"; import { + MAX_EXPECTED_LENGTH_BYTES, MAX_INFLATE_OUTPUT_BYTES, deflate, inflate, @@ -137,6 +138,30 @@ describe("inflateTolerant with an expected length", () => { ).toBe(true); }); + it("inflates into a growable buffer, as with no expectation, when the expectation is past the ceiling a dictionary's word may buy", () => { + // Incompressible bytes, so the stream is long enough that its deflate bound allows the expectation and only the ceiling refuses it. + let state = 1; + const noise = Uint8Array.from({ length: 64 * 1024 }, () => { + state ^= state << 13; + state ^= state >>> 17; + state ^= state << 5; + return state >>> 24; + }); + const stream = deflate(noise); + expect(stream.length * 1032).toBeGreaterThan(MAX_EXPECTED_LENGTH_BYTES); + vi.mocked(unzlibSync).mockClear(); + const result = inflateTolerant(stream, MAX_EXPECTED_LENGTH_BYTES + 1); + expect(Array.from(result.bytes)).toEqual(Array.from(noise)); + expect( + vi.mocked(unzlibSync).mock.calls.every((call) => call[1] === undefined), + ).toBe(true); + vi.mocked(unzlibSync).mockClear(); + inflateTolerant(stream, MAX_EXPECTED_LENGTH_BYTES); + expect(vi.mocked(unzlibSync).mock.calls[0]?.[1]?.out?.length).toBe( + MAX_EXPECTED_LENGTH_BYTES + 1, + ); + }); + it("recovers a damaged stream exactly as it would with no expectation", () => { const damaged = compressed.slice(0, compressed.length - 9); const hinted = inflateTolerant(damaged, sample.length); diff --git a/packages/pdf-codec/src/bytes/flate.ts b/packages/pdf-codec/src/bytes/flate.ts index 0a0d71195a..e2bbb55222 100644 --- a/packages/pdf-codec/src/bytes/flate.ts +++ b/packages/pdf-codec/src/bytes/flate.ts @@ -13,6 +13,12 @@ const MAX_INFLATE_OUTPUT_MIB = 512; export const MAX_INFLATE_OUTPUT_BYTES = MAX_INFLATE_OUTPUT_MIB * KIB_PER_MIB * BYTES_PER_KIB; +// The largest expected length acted on, in mebibytes: past it a stream is inflated into a growable buffer, as with no expectation. A dictionary can state any size up to its stream's deflate bound, and in a Worker isolate an allocation that size ends the isolate rather than throwing into the catch below, so a buffer bought on a dictionary's word alone stays small enough to survive. 32 MiB holds an 11-megapixel RGB image's samples. +const MAX_EXPECTED_LENGTH_MIB = 32; + +export const MAX_EXPECTED_LENGTH_BYTES = + MAX_EXPECTED_LENGTH_MIB * KIB_PER_MIB * BYTES_PER_KIB; + // The most a deflate stream can expand: a 258-byte match costs at least two bits, so each input byte decodes to at most 1032 bytes (zlib's own technical details give the same limit). const DEFLATE_MAX_EXPANSION = 1032; @@ -48,11 +54,11 @@ function inflateIntoExpectedLength( data: Uint8Array, expectedLength: number, ): Uint8Array | undefined { - // An expectation the data could not possibly meet is not acted on: deflate expands at most DEFLATE_MAX_EXPANSION-fold, so a dictionary claiming a huge image over a tiny stream never buys a huge buffer. One that overstates what a stream holds still buys a buffer of the stated size, but never a larger one than a stream of the same length that really does decode that far costs without an expectation. + // An expectation the data could not possibly meet is not acted on: deflate expands at most DEFLATE_MAX_EXPANSION-fold, so a dictionary claiming a huge image over a tiny stream never buys a huge buffer. One that overstates what a stream holds still buys a buffer of the stated size, but never one past MAX_EXPECTED_LENGTH_BYTES, nor a larger one than a stream of the same length that really does decode that far costs without an expectation. if ( !Number.isInteger(expectedLength) || expectedLength < 0 || - expectedLength >= MAX_INFLATE_OUTPUT_BYTES || + expectedLength > MAX_EXPECTED_LENGTH_BYTES || expectedLength > data.length * DEFLATE_MAX_EXPANSION ) { return undefined; @@ -72,7 +78,7 @@ function inflateIntoExpectedLength( /** * Inflates a zlib stream, recovering what it can from a damaged one. * @param data - The zlib stream. - * @param expectedLength - How long the caller expects the output to be (an image's rows of samples), if it knows. A stream that decodes to at most this many bytes is decoded into one buffer of that size, rather than one grown by doubling and then trimmed, which for a large image is most of what inflating it costs in memory; the bytes are the same either way, and a stream that does not fit is inflated as if no length were given. + * @param expectedLength - How long the caller expects the output to be (an image's rows of samples), if it knows. A stream that decodes to at most this many bytes is decoded into one buffer of that size (for an expectation of at most `MAX_EXPECTED_LENGTH_BYTES`), rather than one grown by doubling and then trimmed, which for a large image is most of what inflating it costs in memory; the bytes are the same either way, and a stream that does not fit is inflated as if no length were given. * @returns The inflated bytes, and whether recovery was needed. */ export function inflateTolerant( From 2aac8274d5dce82a0112007b95d32dddb89a77b9 Mon Sep 17 00:00:00 2001 From: fcbwilliams Date: Tue, 17 Nov 2026 16:28:49 +0100 Subject: [PATCH 09/11] fix(pdf-codec): report an image's diagnostics as readPdf did before the size hint Sizing an image's inflate buffer resolved its colour space a second time, reporting a missing reference twice and decoding an Indexed lookup table twice; it now resolves only the space's shape, through a resolver the decode shares. A soft mask of the wrong size is decoded again, so its filters still report what they find, but into a buffer that grows with its stream rather than one its dictionary sized. Co-Authored-By: Claude Opus 5.5 --- packages/pdf-codec/src/images-read.ts | 52 +++++++++++++------ packages/pdf-codec/src/read-images.test.ts | 49 +++++++++++++++-- .../src/test-support/image-heavy-pdf.ts | 19 +++++-- 3 files changed, 98 insertions(+), 22 deletions(-) diff --git a/packages/pdf-codec/src/images-read.ts b/packages/pdf-codec/src/images-read.ts index 55812c554d..cc2329aae4 100644 --- a/packages/pdf-codec/src/images-read.ts +++ b/packages/pdf-codec/src/images-read.ts @@ -12,7 +12,7 @@ import { NOOP_DIAGNOSTIC_SINK } from "./diagnostics"; import { decodeStream } from "./filters"; import type { PdfObjectResolver } from "./interpret-types"; import type { PdfDict, PdfObject } from "./objects"; -import { asArray, asBool, asName, asNumber, dictGet } from "./objects"; +import { asArray, asBool, asDict, asName, asNumber, dictGet } from "./objects"; // Turns an Image XObject (or an inline image's dict+data) into bytes ready to store as a LayoutImageAsset. A DCTDecode (JPEG) image passes through completely undecoded — its compressed bytes ARE the deliverable, exactly mirroring the write path's own lossless JPEG passthrough. Everything else is decoded to raw samples and re-encoded as PNG via byte-codec's own encodePng, since LayoutImageAsset only ever stores 'png' or 'jpeg' — byte-codec's encodePng is this package's only PNG encoder: a caller's own imageId is a crc32 of the PNG bytes it originally supplied (see documents.js's registerImageBytes), so this module's re-encode of the same raster data must run through the identical function a caller would have used, not a second, independently-maintained copy that could silently diverge from it. @@ -65,10 +65,12 @@ function componentsOf(cs: ResolvedColorSpace): number { return RGB_CHANNEL_COUNT; // rgb, and indexed's own per-pixel sample count (handled separately — this is only used for a resolved *base* space) } +// An Indexed space's lookup table is decoded unless `decodeLookup` is false, for a caller that needs only the space's shape (its lookup is then empty). function resolveColorSpace( csObj: PdfObject | undefined, resolver: Readonly, sink: PdfDiagnosticSink, + decodeLookup = true, ): ResolvedColorSpace { const resolved = resolver.resolve(csObj); const directName = resolved?.kind === "name" ? resolved.name : undefined; @@ -112,8 +114,8 @@ function resolveColorSpace( return { kind: "rgb" }; // 3-component ICC (by far the common case) and any unlabelled profile both treated as RGB } if (family === "Indexed") { - const base = resolveColorSpace(arr[1], resolver, sink); - const lookupObj = resolver.resolve(arr[3]); + const base = resolveColorSpace(arr[1], resolver, sink, decodeLookup); + const lookupObj = decodeLookup ? resolver.resolve(arr[3]) : undefined; let lookup: Uint8Array; if (lookupObj?.kind === "stream") { lookup = decodeStream(lookupObj.raw, lookupObj.dict, sink).bytes; @@ -136,6 +138,23 @@ function resolveColorSpace( }; } +// A resolver that hands back what it resolved before for the same object, so an image's colour space resolved twice (once to size its inflate buffer, once to read its samples) reports a missing or cyclic reference once, as resolving it once did. +function resolvingOnce( + resolver: Readonly, +): PdfObjectResolver { + const resolved = new Map(); + const resolve = (obj: PdfObject | undefined): PdfObject | undefined => { + if (obj === undefined) { + return undefined; + } + if (!resolved.has(obj)) { + resolved.set(obj, resolver.resolve(obj)); + } + return resolved.get(obj); + }; + return { resolve, resolveDict: (obj) => asDict(resolve(obj)) }; +} + /** * 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. */ @@ -412,24 +431,24 @@ function readSoftMaskAlpha( const smaskHeight = asNumber(dictGet(smaskObj.dict, "Height")) ?? height; const smaskBpc = asNumber(dictGet(smaskObj.dict, "BitsPerComponent")) ?? BITS_PER_BYTE; - // Checked before the mask is decoded, so a mask that is never used never costs a decode: its size is then the image's own, which readImageXObject has already bounded. - if ( - smaskWidth !== width || - smaskHeight !== height || - smaskBpc !== BITS_PER_BYTE - ) { - return undefined; // a differently-sized or differently-depthed mask needs resampling this module doesn't do - } + const imageSized = + smaskWidth === width && + smaskHeight === height && + smaskBpc === BITS_PER_BYTE; + // Only a mask of the image's own size, which readImageXObject has already bounded, is inflated into a buffer of the size it should decode to (one 8-bit sample per pixel). A mask of any other size goes unused, but is still decoded, so its filters report what they find, into a buffer that grows with what its stream really holds rather than one its dictionary sized. const decoded = decodeStream( smaskObj.raw, smaskObj.dict, sink, undefined, - () => expectedSampleLength(smaskObj.dict, resolver), + imageSized ? () => width * height : undefined, ); if (decoded.remainingFilter !== undefined) { return undefined; // an encoded (e.g. DCT) soft mask is out of scope — degrade to no alpha rather than guess } + if (!imageSized) { + return undefined; // a differently-sized or differently-depthed mask needs resampling this module doesn't do + } return decoded.bytes.subarray(0, width * height); } @@ -578,7 +597,7 @@ function readJpeg2000Image( }; } -// How many bytes an image's samples take, rows padded to a whole byte (ISO 32000-1 8.9.3), from its dictionary alone: what its stream should decode to, which decodeStream sizes its inflate buffer by. Undefined when the dictionary does not say, or says something readImageXObject goes on to refuse (no usable size, a size past its PNG ceilings, a depth it does not read, or a colour space it does not read), and the stream is then decoded as it would be without it: a dictionary's size is trusted for a buffer only where it describes an image that would be decoded. The colour space is resolved with diagnostics discarded, since readImageXObject resolves it again and reports what it finds. +// How many bytes an image's samples take, rows padded to a whole byte (ISO 32000-1 8.9.3), from its dictionary alone: what its stream should decode to, which decodeStream sizes its inflate buffer by. Undefined when the dictionary does not say, or says something readImageXObject goes on to refuse (no usable size, a size past its PNG ceilings, a depth it does not read, or a colour space it does not read), and the stream is then decoded as it would be without it: a dictionary's size is trusted for a buffer only where it describes an image that would be decoded. Only the colour space's shape is resolved, never an Indexed lookup table's stream, with diagnostics discarded, since readImageXObject resolves it again, through the same resolver, and reports what it finds. function expectedSampleLength( dict: PdfDict, resolver: Readonly, @@ -606,6 +625,7 @@ function expectedSampleLength( dictGet(dict, "ColorSpace") ?? dictGet(dict, "CS"), resolver, NOOP_DIAGNOSTIC_SINK, + false, ); if (colorSpace.kind === "unsupported") { return undefined; @@ -633,13 +653,15 @@ export function readImageXObject( return undefined; } + // The colour space is resolved through this for the inflate size hint and again for the samples, so a reference it follows is fetched, and any warning about it reported, once. + const colorSpaceResolver = resolvingOnce(resolver); // The resolver is threaded in here, and only here, because JBIG2Decode's own /JBIG2Globals DecodeParms entry is a stream that a producer essentially always writes as an indirect reference — no other filter this codec implements has a parameter that needs dereferencing. const decoded = decodeStream( raw, dict, sink, (obj) => resolver.resolve(obj), - () => expectedSampleLength(dict, resolver), + () => expectedSampleLength(dict, colorSpaceResolver), ); const jbig2Original: ExtractedPdfImage["original"] = decoded.jbig2 === undefined @@ -715,7 +737,7 @@ export function readImageXObject( const colorSpace = resolveColorSpace( dictGet(dict, "ColorSpace") ?? dictGet(dict, "CS"), - resolver, + colorSpaceResolver, sink, ); if (colorSpace.kind === "unsupported") { diff --git a/packages/pdf-codec/src/read-images.test.ts b/packages/pdf-codec/src/read-images.test.ts index ef987aac19..39b427dac3 100644 --- a/packages/pdf-codec/src/read-images.test.ts +++ b/packages/pdf-codec/src/read-images.test.ts @@ -320,15 +320,56 @@ describe("decodePdfImage", () => { expect(otherGeneration?.imageId).toBe(named?.imageId); }); - it("decodes an image without its soft mask when the mask is the wrong size, never inflating the mask", () => { + it("decodes an image without its soft mask when the mask is the wrong size, inflating the mask only as far as its stream goes and reporting its filters as readPdf does", () => { + const diagnostics: PdfDiagnostic[] = []; + const decoded = decodePdfImage( + edgeCases, + { kind: "xobject", objectNumber: 4, generation: 0 }, + { + sink: (diagnostic) => { + diagnostics.push(diagnostic); + }, + }, + ); + expect(decoded).toMatchObject({ format: "png", widthPx: 2, heightPx: 1 }); + expect(diagnostics.map((diagnostic) => diagnostic.code)).toEqual([ + "pdf/unsupported-predictor", + ]); + // The image's own stream into a buffer of its size, then the 4000x4000 mask's into one that grows with what it holds. + const calls = vi.mocked(unzlibSync).mock.calls; + expect(calls).toHaveLength(2); + expect(calls[0]?.[1]?.out?.length).toBe(2 * 3 + 1); + expect(calls[1]?.[1]).toBeUndefined(); + }); + + it("reports a missing colour space object once, though sizing the inflate buffer resolves it too", () => { + const diagnostics: PdfDiagnostic[] = []; + expect( + decodePdfImage( + edgeCases, + { kind: "xobject", objectNumber: 8, generation: 0 }, + { + sink: (diagnostic) => { + diagnostics.push(diagnostic); + }, + }, + ), + ).toBeUndefined(); + expect(diagnostics.map((diagnostic) => diagnostic.code)).toEqual([ + "pdf/object-missing-value", + "image/unsupported-colorspace", + ]); + }); + + it("decodes an Indexed image's lookup table once", () => { const decoded = decodePdfImage(edgeCases, { kind: "xobject", - objectNumber: 4, + objectNumber: 9, generation: 0, }); expect(decoded).toMatchObject({ format: "png", widthPx: 2, heightPx: 1 }); - // The image's own stream, and not its 4000x4000 mask's. - expect(unzlibSync).toHaveBeenCalledTimes(1); + // The image's samples and its lookup table, each inflated once. + expect(unzlibSync).toHaveBeenCalledTimes(2); }); it("never sizes an inflate buffer by a dictionary that declares an image too large to decode", () => { diff --git a/packages/pdf-codec/src/test-support/image-heavy-pdf.ts b/packages/pdf-codec/src/test-support/image-heavy-pdf.ts index 8f1f45322c..b7242f631a 100644 --- a/packages/pdf-codec/src/test-support/image-heavy-pdf.ts +++ b/packages/pdf-codec/src/test-support/image-heavy-pdf.ts @@ -6,7 +6,7 @@ import { seededRandom } from "./seeded-random"; // Picture-heavy PDF fixtures for the per-image reader (read-images.ts), built like every fixture in pdf.ts: by literal concatenation through FixtureBuilder, never through this package's own writer. Two shapes: // // - imageVarietyPdf: one small image of each kind the read path decodes differently (Flate RGB with a soft mask, PNG-predicted ICC RGB, inverted gray, indexed, 1-bit, CMYK, a JPEG passed through, an image inside a form XObject, an inline image), plus the cases the listing has to leave out or report as undecodable. Its objects are numbered in a fixed order (images from 3, image 0's soft mask straight after it, then the ICC profile and the form), which read-images.test.ts names them by. Its decoded bytes are pinned against pdf-codec 4.5.2's (image-heavy-pdf-golden.ts). -// - imageEdgeCasesPdf: one page of the cases a locator has to survive: an image named through a reference to its reference, an image whose soft mask is the wrong size to use, one whose dictionary declares more pixels than any image decodes to, and an inline stencil mask before an inline image. +// - imageEdgeCasesPdf: one page of the cases a locator has to survive: an image named through a reference to its reference, an image whose soft mask is the wrong size to use, one whose dictionary declares more pixels than any image decodes to, an inline stencil mask before an inline image, and two images no page draws, with a missing and an Indexed colour space. // - pictureDeckPdf: shaped like a typical picture-heavy slide deck (20 pages, about a hundred distinct images, most of them Flate RGB with soft masks and the largest 2360x1309, the rest JPEG), generated from a seed. At full scale it is about 2.5 MB; `scale` shrinks every image's pixel size for a unit test that wants the same structure without the cost. const PAGE_WIDTH_PT = 960; @@ -397,8 +397,9 @@ export function imageVarietyPdf(): Uint8Array { * One page of the edge cases per-image reading has to handle, numbered for read-images.test.ts: * * - 3: a 2x1 Flate RGB image, drawn as /A and again as /B through object 6, which holds only a reference to 3. - * - 4: a 2x1 Flate RGB image whose soft mask (object 5) declares 4000x4000, a size readImageXObject does not resample, so it is never used. + * - 4: a 2x1 Flate RGB image whose soft mask (object 5) declares 4000x4000, a size readImageXObject does not resample, so it is never used, and an unsupported predictor, which decoding it reports. * - 7: a Flate gray image whose dictionary declares 10001x10000 (past encodePng's pixel ceiling) over a stream of about 100 KB. + * - 8, 9 (never drawn): a 2x1 Flate image whose /ColorSpace is a reference to an object the file does not have, and a 2x1 Indexed one whose lookup table is the Flate stream 10. * - two inline images: a stencil mask (`/IM true`, occurrence 0, never listed) and a 1x1 RGB image (occurrence 1). * @returns The PDF. */ @@ -408,7 +409,7 @@ export function imageEdgeCasesPdf(): Uint8Array { { ...rgbImage(2, 1, 2, 0, false), smask: { - dict: "<< /Type /XObject /Subtype /Image /Width 4000 /Height 4000 /ColorSpace /DeviceGray /BitsPerComponent 8 /Filter /FlateDecode >>", + dict: "<< /Type /XObject /Subtype /Image /Width 4000 /Height 4000 /ColorSpace /DeviceGray /BitsPerComponent 8 /Filter /FlateDecode /DecodeParms << /Predictor 5 >> >>", data: flate(new Uint8Array(4)), }, }, @@ -443,6 +444,18 @@ export function imageEdgeCasesPdf(): Uint8Array { dict: "<< /Type /XObject /Subtype /Image /Width 10001 /Height 10000 /ColorSpace /DeviceGray /BitsPerComponent 8 /Filter /FlateDecode >>", data: flate(photoSamples(320, 320, 1, 5, 255)), }, + { + dict: "<< /Type /XObject /Subtype /Image /Width 2 /Height 1 /ColorSpace 99 0 R /BitsPerComponent 8 /Filter /FlateDecode >>", + data: flate(new Uint8Array(6)), + }, + { + dict: "<< /Type /XObject /Subtype /Image /Width 2 /Height 1 /ColorSpace [/Indexed /DeviceRGB 1 @extra:4] /BitsPerComponent 8 /Filter /FlateDecode >>", + data: flate(new Uint8Array([0, 1])), + }, + { + dict: "<< /Filter /FlateDecode >>", + data: flate(new Uint8Array([255, 0, 0, 0, 0, 255])), + }, ], ); } From def7396409fb54a341f6c70c82a20c91672ef4e2 Mon Sep 17 00:00:00 2001 From: fcbwilliams Date: Tue, 17 Nov 2026 16:29:07 +0100 Subject: [PATCH 10/11] perf(pdf-codec): interpret a page once for all of its inline images An opened PdfImages keeps the last page's inline images, so decoding them one after another no longer interprets the page once per image. Documents that an xobject locator is not checked against a listing and decodes any image stream it names. Co-Authored-By: Claude Opus 5.5 --- packages/pdf-codec/README.md | 4 +- packages/pdf-codec/src/read-images.test.ts | 35 +++++++++++ packages/pdf-codec/src/read-images.ts | 70 ++++++++++++++++------ 3 files changed, 90 insertions(+), 19 deletions(-) diff --git a/packages/pdf-codec/README.md b/packages/pdf-codec/README.md index 124d2550c6..022c83c327 100644 --- a/packages/pdf-codec/README.md +++ b/packages/pdf-codec/README.md @@ -134,9 +134,9 @@ for (const entry of images.list({ pages: [0, 1] })) { `listPdfImages(bytes, options)` and `decodePdfImage(bytes, locator, options)` are the same two calls on a file opened afresh each time, for a caller that decodes in a later call or process than it lists. The root `pdf-codec` barrel exports all three as well, at the cost of loading its write half. -A `PdfImageLocator` is plain data: an image XObject's object reference (`{ kind: "xobject", objectNumber, generation }`, where the object is found by its number and `generation` is informational), or for an inline image, which has no object, its page's source index and position among that page's inline images (`{ kind: "inline", pageIndex, occurrence }`, both non-negative integers). A caller can store one, validate it on the way back in with `PdfImageLocatorSchema`, and decode the image in a later call, or a later process, against the same file bytes. Decoding an image XObject interprets no page at all; decoding an inline image interprets its own page's content again to find it (inline images are small by design, and rare). Each `PdfImageEntry` carries the image's `placements` (its page, `xPt`/`yPt`/`widthPt`/`heightPt`, `rotationDeg` and `layer`, exactly as `readPdf`'s image items state them), plus what its dictionary declares without decoding: `widthPx`/`heightPx`, `filters`, `softMask` and `encodedByteLength`. The listing follows the images `readPdf`'s pages draw, not its registry: an image drawn only outside its page's crop box, and an `/ImageMask` stencil, are not listed; an image whose decoding `readPdf` would refuse (an unsupported filter, colour space or bit depth) is listed and decodes to `undefined`, with the same diagnostic; and two image objects holding the same picture are two entries that decode to one `imageId`, where the registry holds it once. A decoded image's byte arrays are its own, never views onto the file, so keeping one does not keep the file alive. The `signal` given to `openPdfImages` is the one each later `list` and `decode` of that document checks. The structure-ownership association (`structure`) is not reported, since reading it needs the whole structure tree. +A `PdfImageLocator` is plain data: an image XObject's object reference (`{ kind: "xobject", objectNumber, generation }`, where the object is found by its number and `generation` is informational), or for an inline image, which has no object, its page's source index and position among that page's inline images (`{ kind: "inline", pageIndex, occurrence }`, both non-negative integers). A caller can store one, validate it on the way back in with `PdfImageLocatorSchema`, and decode the image in a later call, or a later process, against the same file bytes. Decoding an image XObject interprets no page at all, and is not checked against a listing: an `xobject` locator names any stream in the file whose `/Subtype` is `/Image`, so one naming a stream no page draws (another image's `/SMask`, or a `/Thumb` thumbnail) decodes it as an image. Decoding an inline image interprets its own page's content again to find it (inline images are small by design, and rare); an opened `PdfImages` keeps the last such page's inline images, so decoding a page's inline images one after another interprets it once. Each `PdfImageEntry` carries the image's `placements` (its page, `xPt`/`yPt`/`widthPt`/`heightPt`, `rotationDeg` and `layer`, exactly as `readPdf`'s image items state them), plus what its dictionary declares without decoding: `widthPx`/`heightPx`, `filters`, `softMask` and `encodedByteLength`. The listing follows the images `readPdf`'s pages draw, not its registry: an image drawn only outside its page's crop box, and an `/ImageMask` stencil, are not listed; an image whose decoding `readPdf` would refuse (an unsupported filter, colour space or bit depth) is listed and decodes to `undefined`, with the same diagnostic; and two image objects holding the same picture are two entries that decode to one `imageId`, where the registry holds it once. A decoded image's byte arrays are its own, never views onto the file, so keeping one does not keep the file alive. The `signal` given to `openPdfImages` is the one each later `list` and `decode` of that document checks. The structure-ownership association (`structure`) is not reported, since reading it needs the whole structure tree. -Failures follow the [read failure policy](#conventions): a file that cannot be opened throws as `readPdf` does; a locator naming no image of the file (an object that is not an image XObject, or an inline locator with a negative or fractional index, or an occurrence its page does not hold) throws `PdfImageLocatorError`, code `pdf/image-not-found`; an inline locator's page the document does not have throws `PdfPageSelectionError`; and an aborted signal throws a `DOMException` named `AbortError`. In an encrypted file, the document keeps each stream it has decrypted for as long as it stays open, as `readPdf`'s does, so an opened `PdfImages` holds every decoded image's encrypted stream in the clear until it is dropped; for an encrypted file, open a fresh one per batch of images rather than keeping one open across all of them. +Failures follow the [read failure policy](#conventions): a file that cannot be opened throws as `readPdf` does; a locator naming nothing that can be decoded as an image (an object that is not a stream with `/Subtype /Image`, or an inline locator with a negative or fractional index, or an occurrence its page does not hold) throws `PdfImageLocatorError`, code `pdf/image-not-found`; an inline locator's page the document does not have throws `PdfPageSelectionError`; and an aborted signal throws a `DOMException` named `AbortError`. In an encrypted file, the document keeps each stream it has decrypted for as long as it stays open, as `readPdf`'s does, so an opened `PdfImages` holds every decoded image's encrypted stream in the clear until it is dropped; for an encrypted file, open a fresh one per batch of images rather than keeping one open across all of them. The decoded bytes are those `readPdf` produces for the same image, which are those pdf-codec 4.5.2 produced (pinned in `src/read-images.test.ts` against digests recorded from 4.5.2), so an image stored by an earlier release keeps its identity. Decoding one image holds its decoded samples, its alpha plane and the PNG encoder's filtered rows and deflate buffer at once, in proportion to its pixels: a 2360x1309 RGB image with a soft mask needs about 40 MB on top of the module and the file. `pdf-codec/read-images` serves the three functions without the text pipeline `readPdf` loads (font resolution and its glyph tables, about 12 MB of heap). `scripts/measure-image-memory.mjs` measures a generated picture-heavy fixture (2.4 MB, 108 images) against the built `dist/`, as the peak of the V8 heap in use plus every `ArrayBuffer`'s backing store: diff --git a/packages/pdf-codec/src/read-images.test.ts b/packages/pdf-codec/src/read-images.test.ts index 39b427dac3..04b592dd6d 100644 --- a/packages/pdf-codec/src/read-images.test.ts +++ b/packages/pdf-codec/src/read-images.test.ts @@ -342,6 +342,28 @@ describe("decodePdfImage", () => { expect(calls[1]?.[1]).toBeUndefined(); }); + it("interprets a page once for all of its inline images, keeping one page's at a time", () => { + const images = openPdfImages(edgeCases); + vi.mocked(interpretContentStream).mockClear(); + expect( + images.decode({ kind: "inline", pageIndex: 0, occurrence: 0 }), + ).toBeUndefined(); + expect( + images.decode({ kind: "inline", pageIndex: 0, occurrence: 1 }), + ).toMatchObject({ format: "png", widthPx: 1, heightPx: 1 }); + expect(interpretContentStream).toHaveBeenCalledTimes(1); + + const varietyImages = openPdfImages(variety); + vi.mocked(interpretContentStream).mockClear(); + const inline = { kind: "inline", pageIndex: 1, occurrence: 0 } as const; + const first = varietyImages.decode(inline); + expect(() => + varietyImages.decode({ kind: "inline", pageIndex: 0, occurrence: 0 }), + ).toThrow(PdfImageLocatorError); + expect(varietyImages.decode(inline)?.imageId).toBe(first?.imageId); + expect(interpretContentStream).toHaveBeenCalledTimes(3); + }); + it("reports a missing colour space object once, though sizing the inflate buffer resolves it too", () => { const diagnostics: PdfDiagnostic[] = []; expect( @@ -372,6 +394,19 @@ describe("decodePdfImage", () => { expect(unzlibSync).toHaveBeenCalledTimes(2); }); + it("decodes an image stream no page draws, since an xobject locator is not checked against a listing", () => { + expect( + listPdfImages(edgeCases).map((entry) => entry.locator), + ).not.toContainEqual({ kind: "xobject", objectNumber: 9, generation: 0 }); + expect( + decodePdfImage(edgeCases, { + kind: "xobject", + objectNumber: 9, + generation: 0, + }), + ).toBeDefined(); + }); + it("never sizes an inflate buffer by a dictionary that declares an image too large to decode", () => { const diagnostics: PdfDiagnostic[] = []; expect( diff --git a/packages/pdf-codec/src/read-images.ts b/packages/pdf-codec/src/read-images.ts index bced3da2f2..39e1bbed94 100644 --- a/packages/pdf-codec/src/read-images.ts +++ b/packages/pdf-codec/src/read-images.ts @@ -94,9 +94,11 @@ export interface PdfImages { list: (options?: ListPdfImagesOptions) => PdfImageEntry[]; /** * Decodes one image. + * + * An `xobject` locator is not checked against a listing: it names any image XObject stream in the file by its object number, so one naming a stream no page draws (another image's `/SMask`, or a page's `/Thumb` thumbnail) decodes that stream as an image, as `readPdf` would decode it had a page drawn it. The handle keeps the inline images of the last page it found an inline image on, so decoding a page's inline images one after another interprets that page once. * @param locator - The image, as a listing of this same file named it. * @returns The image, or undefined for one `readPdf` would leave out of its registry too (an `/ImageMask` stencil, an unsupported filter, colour space or bit depth, an invalid size, or an undecodable stream), with the same diagnostic `readPdf` reports for it. - * @throws PdfImageLocatorError if the locator names no image of this document: an object that is not an image XObject stream, or a page index or occurrence that is negative, not an integer, or past the page's inline images. + * @throws PdfImageLocatorError if the locator names nothing that can be decoded as an image: an object that is not a stream whose `/Subtype` is `/Image`, or a page index or occurrence that is negative, not an integer, or past the page's inline images. */ decode: (locator: PdfImageLocator) => DecodedPdfImage | undefined; } @@ -324,11 +326,38 @@ function isLocatorIndex(value: number): boolean { return Number.isInteger(value) && value >= 0; } +// One page's inline images, in content-stream order. +interface PageInlineImages { + readonly pageIndex: number; + readonly images: readonly Extract[]; +} + +// The inline images a page draws, found by interpreting its content again. The page's own diagnostics were reported when it was listed, so finding them again reports nothing new. +function inlineImagesOf( + doc: PdfDocument, + pageIndex: number, + page: PdfDict | undefined, +): PageInlineImages { + const items = + page === undefined + ? [] + : (interpretPage(doc, pageIndex, page, undefined, NOOP_DIAGNOSTIC_SINK) + ?.items ?? []); + return { + pageIndex, + images: items.filter((item) => item.kind === "inlineImage"), + }; +} + function decodeImage( doc: PdfDocument, pageDicts: readonly PdfDict[], locator: PdfImageLocator, sink: PdfDiagnosticSink, + inlineImagesOn: ( + pageIndex: number, + page: PdfDict | undefined, + ) => PageInlineImages, ): ExtractedPdfImage | undefined { if (locator.kind === "xobject") { const stream = doc.resolve({ @@ -336,7 +365,7 @@ function decodeImage( num: locator.objectNumber, gen: locator.generation, }); - // The interpreter draws an XObject as an image exactly when its /Subtype says so, so that is what a locator must name. + // The interpreter draws an XObject as an image exactly when its /Subtype says so, so that is what a locator must name. Whether a page draws it is not checked, since that would mean interpreting every page. if ( stream?.kind !== "stream" || asName(dictGet(stream.dict, "Subtype")) !== "Image" @@ -363,20 +392,10 @@ function decodeImage( [locator.pageIndex], pageDicts.length, ); - const page = pageDicts[pageIndex]; - // The page's own diagnostics were reported when it was listed; finding the image again reports nothing new, and only the image's decode below reports to the caller. - const inline = - page === undefined - ? undefined - : interpretPage( - doc, - pageIndex, - page, - undefined, - NOOP_DIAGNOSTIC_SINK, - )?.items.filter((item) => item.kind === "inlineImage")[ - locator.occurrence - ]; + // Only the image's decode below reports to the caller. + const inline = inlineImagesOn(pageIndex, pageDicts[pageIndex]).images[ + locator.occurrence + ]; if (inline === undefined) { throw new PdfImageLocatorError( locator, @@ -408,13 +427,30 @@ export function openPdfImages( throwIfAborted(signal); const doc = openPdfDocument(bytes, sink); const pageDicts = doc.pages(); + // The last page whose inline images were looked for, kept so decoding a page's inline images one by one interprets it once rather than once per image. One page at most: its inline images are views onto its decoded content, which this keeps alive until another page's are looked for. + let lastInlinePage: PageInlineImages | undefined; + const inlineImagesOn = ( + pageIndex: number, + page: PdfDict | undefined, + ): PageInlineImages => { + if (lastInlinePage?.pageIndex !== pageIndex) { + lastInlinePage = inlineImagesOf(doc, pageIndex, page); + } + return lastInlinePage; + }; return { pageCount: pageDicts.length, list: (listOptions) => listImages(doc, pageDicts, listOptions, signal, sink), decode: (locator) => { throwIfAborted(signal); - const extracted = decodeImage(doc, pageDicts, locator, sink); + const extracted = decodeImage( + doc, + pageDicts, + locator, + sink, + inlineImagesOn, + ); if (extracted === undefined) { return undefined; } From 6cab21ca045a0208f343aeee7613f1a548ba7a07 Mon Sep 17 00:00:00 2001 From: fcbwilliams Date: Tue, 17 Nov 2026 16:36:42 +0100 Subject: [PATCH 11/11] docs(pdf-codec): widen per-image and readPdf memory ranges to this round's runs Co-Authored-By: Claude Opus 5.5 --- packages/pdf-codec/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/pdf-codec/README.md b/packages/pdf-codec/README.md index 022c83c327..70edb1f7ec 100644 --- a/packages/pdf-codec/README.md +++ b/packages/pdf-codec/README.md @@ -140,12 +140,12 @@ Failures follow the [read failure policy](#conventions): a file that cannot be o The decoded bytes are those `readPdf` produces for the same image, which are those pdf-codec 4.5.2 produced (pinned in `src/read-images.test.ts` against digests recorded from 4.5.2), so an image stored by an earlier release keeps its identity. Decoding one image holds its decoded samples, its alpha plane and the PNG encoder's filtered rows and deflate buffer at once, in proportion to its pixels: a 2360x1309 RGB image with a soft mask needs about 40 MB on top of the module and the file. `pdf-codec/read-images` serves the three functions without the text pipeline `readPdf` loads (font resolution and its glyph tables, about 12 MB of heap). `scripts/measure-image-memory.mjs` measures a generated picture-heavy fixture (2.4 MB, 108 images) against the built `dist/`, as the peak of the V8 heap in use plus every `ArrayBuffer`'s backing store: -| Read | Collecting before each image (`--gc`) | Left to the collector | -| ------------------------------------- | ------------------------------------- | ------------------------------------ | -| One image at a time (`openPdfImages`) | about 56 MB | 57-63 MB in most runs, 70 MB in some | -| `readPdf` | 83-87 MB | 86-96 MB | -| `readPdf` in pdf-codec 5.8 | 140-148 MB | 139-148 MB | -| `readPdf` in pdf-codec 4.5.2 | about 526 MB | about 526 MB | +| Read | Collecting before each image (`--gc`) | Left to the collector | +| ------------------------------------- | ------------------------------------- | ------------------------------------------ | +| One image at a time (`openPdfImages`) | 55-57 MB | 57-63 MB in most runs, up to 77 MB in some | +| `readPdf` | 83-87 MB | 86-100 MB | +| `readPdf` in pdf-codec 5.8 | 140-148 MB | 139-148 MB | +| `readPdf` in pdf-codec 4.5.2 | about 526 MB | about 526 MB | A Worker cannot force a collection, so its figure is the right-hand one: what an image leaves behind counts until the collector reclaims it, which in most runs it has before the next large image and in some it has not.