byte-codec 0.0.0 → 1.0.0

package/release.config.ts

@@ -0,0 +1,65 @@
+import type { Options } from 'semantic-release';
+
+type ReleaseLevel = 'major' | 'minor' | 'patch' | false;
+
+interface CommitType {
+  readonly type: string;
+  readonly release: ReleaseLevel;
+}
+
+/**
+ * Single source of truth for the conventional-commit types this project uses. commitlint's allowed type-enum (commitlint.config.ts imports this) and commit-analyzer's releaseRules below both derive from it, so a type can't trigger a release without also being accepted by commit-msg validation, or the reverse.
+ *
+ * Defined here rather than in a shared commit-types.ts: semantic-release loads this file via cosmiconfig, which transpiles only this one file to ESM, so a sibling .ts module would not resolve. commitlint's jiti loader has no such limit, so it imports commitTypes from here.
+ */
+export const commitTypes: readonly CommitType[] = [
+  { type: 'feat', release: 'minor' },
+  { type: 'fix', release: 'patch' },
+  { type: 'perf', release: 'patch' },
+  { type: 'revert', release: 'patch' },
+  { type: 'refactor', release: 'patch' },
+  { type: 'docs', release: 'patch' },
+  { type: 'style', release: 'patch' },
+  { type: 'test', release: 'patch' },
+  { type: 'build', release: 'patch' },
+  { type: 'ci', release: 'patch' },
+  { type: 'chore', release: 'patch' },
+];
+
+/**
+ * Runs on `main`. Analyses commits since the last tag, bumps the version, publishes to npmjs.org (trusted OIDC publishing, no stored token -- see .github/workflows/ci.yml), creates a versioned tag and GitHub Release with generated notes, and commits CHANGELOG.md + package.json back to main. The release commit's [skip ci] message avoids a redundant CI run.
+ */
+const config: Options = {
+  branches: ['main'],
+  plugins: [
+    [
+      '@semantic-release/commit-analyzer',
+      {
+        preset: 'conventionalcommits',
+        releaseRules: [
+          { breaking: true, release: 'major' },
+          ...commitTypes.map((t) => ({ type: t.type, release: t.release })),
+        ],
+      },
+    ],
+    [
+      '@semantic-release/release-notes-generator',
+      {
+        // Deliberately angular, not conventionalcommits, despite commit-analyzer above using conventionalcommits without issue. conventional-changelog-conventionalcommits@10.2.1 exports its changelog body under the key `template`, but the conventional-changelog-writer version release-notes-generator@14.1.1 bundles only reads `options.mainTemplate` -- so the body silently falls back to the writer's own generic default, whose commit partial doesn't match conventionalcommits' function-based partial signature either. The result is a changelog with a version header and nothing under it, for every commit, with zero custom configuration: confirmed with `preset: 'conventionalcommits'` and no presetConfig at all. angular is release-notes-generator's own tested default and renders correctly. commitTypes above still drives commit-analyzer's releaseRules and commitlint's type-enum; it just can't also drive per-type changelog sections until this is fixed upstream, so there is no per-type `section` field here to go unused.
+        preset: 'angular',
+      },
+    ],
+    '@semantic-release/changelog',
+    ['@semantic-release/npm', { npmPublish: true }],
+    '@semantic-release/github',
+    [
+      '@semantic-release/git',
+      {
+        assets: ['CHANGELOG.md', 'package.json'],
+        message: 'chore(release): ${nextRelease.version} [skip ci]',
+      },
+    ],
+  ],
+};
+
+export default config;

package/src/bytes/crc32.ts

@@ -0,0 +1,24 @@
+// Table-driven CRC32 (polynomial 0xEDB88320, the standard IEEE 802.3 / ZIP / PNG polynomial). fflate exports no CRC32 of its own (only an internal one used by its ZIP writer), and PNG's chunk format requires one per chunk, so this is genuinely new code, not a duplicate of anything already in the tree.
+const CRC32_POLYNOMIAL = 0xedb88320;
+const BYTE_VALUES = 256;
+const BITS_PER_BYTE = 8;
+
+const CRC32_TABLE: Uint32Array = (() => {
+  const table = new Uint32Array(BYTE_VALUES);
+  for (let n = 0; n < BYTE_VALUES; n++) {
+    let c = n;
+    for (let k = 0; k < BITS_PER_BYTE; k++) {
+      c = (c & 1) === 1 ? CRC32_POLYNOMIAL ^ (c >>> 1) : c >>> 1;
+    }
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+export function crc32(bytes: Uint8Array<ArrayBuffer>): number {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc = CRC32_TABLE[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}

package/src/bytes/flate.ts

@@ -0,0 +1,69 @@
+import { Unzlib, inflateSync, unzlibSync, zlibSync } from 'fflate';
+import { isAsciiWhitespace } from './reader';
+import { concatBytes } from './writer';
+
+// The only file in the package that imports fflate -- the direct analogue of ooxml.js's own src/zip.ts ("a thin wrapper over fflate's zipSync/unzipSync, isomorphic and dependency-free"). PDF's FlateDecode filter and PNG's IDAT payload both use zlib-framed DEFLATE (RFC 1950 -- a 2-byte header plus a trailing Adler-32 checksum) -- that is zlibSync/unzlibSync, NOT fflate's deflateSync/inflateSync, which are raw DEFLATE (RFC 1951) with no wrapper. Emitting or expecting the wrong framing produces a stream every conformant PDF/PNG reader rejects.
+
+// Guards every call in this module against a maliciously or accidentally huge decompressed output -- both PDF and PNG streams here come from arbitrary, potentially adversarial input.
+export const MAX_INFLATE_OUTPUT_BYTES = 512 * 1024 * 1024;
+
+export type DeflateLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+export function deflate(data: Uint8Array<ArrayBuffer>, level?: DeflateLevel): Uint8Array<ArrayBuffer> {
+  return zlibSync(data, level === undefined ? undefined : { level });
+}
+
+export function inflate(data: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer> {
+  const out = unzlibSync(data);
+  if (out.length > MAX_INFLATE_OUTPUT_BYTES) {
+    throw new Error(`inflated output exceeds the ${MAX_INFLATE_OUTPUT_BYTES}-byte limit`);
+  }
+  return out;
+}
+
+export interface InflateResult {
+  readonly bytes: Uint8Array<ArrayBuffer>;
+  readonly recovered: boolean;
+}
+
+// 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<ArrayBuffer>): InflateResult {
+  try {
+    return { bytes: inflate(data), recovered: false };
+  } catch {
+    // fall through to the recovery ladder below
+  }
+
+  let offset = 0;
+  while (offset < data.length && isAsciiWhitespace(data[offset])) {
+    offset++;
+  }
+  if (offset > 0) {
+    try {
+      return { bytes: inflate(data.subarray(offset)), recovered: true };
+    } catch {
+      // fall through
+    }
+  }
+
+  try {
+    return { bytes: inflateSync(data), recovered: true };
+  } catch {
+    // fall through
+  }
+
+  const chunks: Uint8Array<ArrayBuffer>[] = [];
+  const unzlib = new Unzlib((chunk) => {
+    chunks.push(chunk);
+  });
+  try {
+    // Pushed as NOT final: fflate only flushes decoded output incrementally as it's produced when a push is not marked as the stream's end -- marking truncated data `final: true` instead makes it run the end-of-stream/checksum finalisation path, which throws atomically before emitting anything at all (verified empirically against fflate 0.8.3). Since this is already the last-resort recovery tier, skipping checksum verification here is an acceptable trade.
+    unzlib.push(data, false);
+  } catch {
+    // whatever chunks were emitted before the throw are still valid partial output
+  }
+  if (chunks.length === 0) {
+    throw new Error('unable to inflate stream: no data could be recovered');
+  }
+  return { bytes: concatBytes(chunks), recovered: true };
+}

package/src/bytes/reader.ts

@@ -0,0 +1,73 @@
+const ASCII_WHITESPACE_BYTES = new Set([0x00, 0x09, 0x0a, 0x0c, 0x0d, 0x20]);
+
+export function isAsciiWhitespace(byte: number | undefined): boolean {
+  return byte !== undefined && ASCII_WHITESPACE_BYTES.has(byte);
+}
+
+// A forward-only cursor over a byte buffer, with explicit mark()/reset() for the backtracking a tokenizer needs -- e.g. the PDF lexer's `N G R` (a reference) vs `N G obj` (an indirect object header) ambiguity, resolved only by trying to read two integers and a keyword, then rewinding if it doesn't match.
+export class ByteReader {
+  private readonly bytes: Uint8Array<ArrayBuffer>;
+  private position = 0;
+
+  constructor(bytes: Uint8Array<ArrayBuffer>) {
+    this.bytes = bytes;
+  }
+
+  get offset(): number {
+    return this.position;
+  }
+
+  get length(): number {
+    return this.bytes.length;
+  }
+
+  atEnd(): boolean {
+    return this.position >= this.bytes.length;
+  }
+
+  peek(aheadBy = 0): number | undefined {
+    return this.bytes[this.position + aheadBy];
+  }
+
+  next(): number | undefined {
+    const byte = this.bytes[this.position];
+    if (byte !== undefined) {
+      this.position++;
+    }
+    return byte;
+  }
+
+  // Returns a resumption point for reset(); does not itself change position.
+  mark(): number {
+    return this.position;
+  }
+
+  reset(mark: number): void {
+    this.position = mark;
+  }
+
+  seek(offset: number): void {
+    this.position = offset;
+  }
+
+  slice(start: number, end: number): Uint8Array<ArrayBuffer> {
+    return this.bytes.subarray(start, end);
+  }
+
+  skipWhitespace(): void {
+    while (isAsciiWhitespace(this.peek())) {
+      this.position++;
+    }
+  }
+
+  // Consumes `keyword` as a literal ASCII sequence at the current position, advancing past it, and returns true; otherwise leaves the position unchanged and returns false.
+  matchKeyword(keyword: string): boolean {
+    for (let i = 0; i < keyword.length; i++) {
+      if (this.peek(i) !== keyword.charCodeAt(i)) {
+        return false;
+      }
+    }
+    this.position += keyword.length;
+    return true;
+  }
+}

package/src/bytes/writer.ts

@@ -0,0 +1,45 @@
+// A chunked, growable byte-output builder: writes accumulate into a list of chunks rather than repeatedly reallocating and copying one growing buffer, which is O(n^2) for many small writes -- exactly the access pattern the PDF writer (one write per operator) and the PNG encoder (one write per scanline) both have.
+export class ByteWriter {
+  private readonly chunks: Uint8Array<ArrayBuffer>[] = [];
+  private byteLength = 0;
+
+  get length(): number {
+    return this.byteLength;
+  }
+
+  writeBytes(bytes: Uint8Array<ArrayBuffer>): void {
+    if (bytes.length === 0) {
+      return;
+    }
+    this.chunks.push(bytes);
+    this.byteLength += bytes.length;
+  }
+
+  writeByte(byte: number): void {
+    this.writeBytes(new Uint8Array([byte]));
+  }
+
+  // Encodes `text` as UTF-8 (ASCII in practice, for the PDF/PNG syntax this writer produces) and appends it.
+  writeAscii(text: string): void {
+    this.writeBytes(new TextEncoder().encode(text));
+  }
+
+  toBytes(): Uint8Array<ArrayBuffer> {
+    const out = new Uint8Array(this.byteLength);
+    let offset = 0;
+    for (const chunk of this.chunks) {
+      out.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return out;
+  }
+}
+
+// Concatenates a list of byte chunks into one contiguous array without the O(n^2) cost of repeated single-chunk concatenation.
+export function concatBytes(chunks: readonly Uint8Array<ArrayBuffer>[]): Uint8Array<ArrayBuffer> {
+  const writer = new ByteWriter();
+  for (const chunk of chunks) {
+    writer.writeBytes(chunk);
+  }
+  return writer.toBytes();
+}

package/src/image/jpeg-info.ts

@@ -0,0 +1,90 @@
+// A JPEG's compressed byte stream passes through this whole package unchanged in both directions (embedded via a PDF Image XObject's /DCTDecode filter on write; extracted as-is on read) -- the single biggest scope reduction in the hand-written PDF codec, since no JPEG decoder or encoder is needed at all. The one piece of information still needed from a JPEG that isn't available without looking inside it is its pixel dimensions and component count, which the PDF Image XObject dictionary requires (/Width, /Height, /ColorSpace) -- this module recovers exactly that, by scanning marker segments, without decoding a single sample.
+export interface JpegInfo {
+  readonly width: number;
+  readonly height: number;
+  readonly components: number;
+  readonly precision: number;
+  readonly progressive: boolean;
+  // The Adobe APP14 marker's transform byte, if present: 0 = unknown/CMYK-as-is, 1 = YCbCr, 2 = YCCK. A 4-component (CMYK) JPEG with transform 2, or an untagged 4-component JPEG, almost always needs colour inversion (/Decode [1 0 1 0 1 0 1 0]) to render correctly -- a well-known, near-universal convention rather than something this scanner can verify from the bytes alone.
+  readonly adobeTransform: number | undefined;
+}
+
+const SOI = 0xd8;
+const EOI = 0xd9;
+const APP14 = 0xee;
+// SOF0 (baseline), SOF1 (extended sequential Huffman), SOF2 (progressive Huffman), SOF9 (extended sequential arithmetic), SOF10 (progressive arithmetic) -- the marker codes actually used to carry frame dimensions. SOF3/SOF5-7/SOF11/SOF13-15 (lossless / differential / hierarchical variants) are not handled, since they are not produced by mainstream PDF-embedding producers.
+const SOF_MARKERS = new Set([0xc0, 0xc1, 0xc2, 0xc9, 0xca]);
+const PROGRESSIVE_SOF_MARKERS = new Set([0xc2, 0xca]);
+// Markers with no following length/payload: TEM, SOI, EOI, and the eight restart markers.
+const NO_PAYLOAD_MARKERS = new Set([0x01, 0xd8, 0xd9, 0xd0, 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7]);
+
+function requireByte(bytes: Uint8Array<ArrayBuffer>, index: number): number {
+  const value = bytes[index];
+  if (value === undefined) {
+    throw new Error('unexpected end of JPEG data');
+  }
+  return value;
+}
+
+function readUint16BE(bytes: Uint8Array<ArrayBuffer>, offset: number): number {
+  return (requireByte(bytes, offset) << 8) | requireByte(bytes, offset + 1);
+}
+
+// Scans a JPEG file's marker segments for its SOF (start-of-frame) segment, recovering dimensions, component count and progressive-ness without decoding any entropy-coded scan data. Throws if the bytes don't start with SOI or no SOF marker is found before EOI/truncation.
+export function readJpegInfo(bytes: Uint8Array<ArrayBuffer>): JpegInfo {
+  if (requireByte(bytes, 0) !== 0xff || requireByte(bytes, 1) !== SOI) {
+    throw new Error('not a valid JPEG file: missing SOI marker');
+  }
+
+  let offset = 2;
+  let adobeTransform: number | undefined;
+
+  while (offset < bytes.length) {
+    if (bytes[offset] !== 0xff) {
+      offset++;
+      continue;
+    }
+    let markerOffset = offset + 1;
+    while (bytes[markerOffset] === 0xff) {
+      markerOffset++;
+    }
+    const marker = bytes[markerOffset];
+    if (marker === undefined) {
+      break;
+    }
+    offset = markerOffset + 1;
+
+    if (marker === EOI) {
+      break;
+    }
+    if (NO_PAYLOAD_MARKERS.has(marker)) {
+      continue;
+    }
+
+    const segmentLength = readUint16BE(bytes, offset); // includes the 2 length bytes themselves
+
+    if (marker === APP14 && segmentLength >= 14) {
+      adobeTransform = requireByte(bytes, offset + 2 + 11);
+    }
+
+    if (SOF_MARKERS.has(marker)) {
+      const p = offset + 2;
+      const precision = requireByte(bytes, p);
+      const height = readUint16BE(bytes, p + 1);
+      const width = readUint16BE(bytes, p + 3);
+      const components = requireByte(bytes, p + 5);
+      return {
+        width,
+        height,
+        components,
+        precision,
+        progressive: PROGRESSIVE_SOF_MARKERS.has(marker),
+        adobeTransform,
+      };
+    }
+
+    offset += segmentLength;
+  }
+
+  throw new Error('no SOF marker found in JPEG file');
+}

package/src/image/png-decode.ts

@@ -0,0 +1,263 @@
+import { crc32 } from '../bytes/crc32';
+import { inflateTolerant } from '../bytes/flate';
+import { concatBytes } from '../bytes/writer';
+import { unfilterScanlines } from './png-filter';
+
+// Normalising every PNG colour type down to 8-bit gray-or-RGB plus a separate alpha plane is deliberate: it is exactly the shape a PDF Image XObject wants (/DeviceGray or /DeviceRGB, /BitsPerComponent 8, alpha as a separate /SMask /DeviceGray XObject), so the PDF writer does zero rearranging of whatever this decoder produces.
+export interface RawImage {
+  readonly width: number;
+  readonly height: number;
+  readonly channels: 1 | 3;
+  readonly data: Uint8Array<ArrayBuffer>;
+  readonly alpha?: Uint8Array<ArrayBuffer>;
+}
+
+export interface PngDecodeOptions {
+  readonly onWarning?: (message: string) => void;
+}
+
+const PNG_SIGNATURE: readonly number[] = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+interface PngChunk {
+  readonly type: string;
+  readonly data: Uint8Array<ArrayBuffer>;
+}
+
+function requireDataView(bytes: Uint8Array<ArrayBuffer>): DataView {
+  return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+function readChunks(bytes: Uint8Array<ArrayBuffer>, onWarning: ((m: string) => void) | undefined): PngChunk[] {
+  const chunks: PngChunk[] = [];
+  const view = requireDataView(bytes);
+  let offset = PNG_SIGNATURE.length;
+  while (offset + 8 <= bytes.length) {
+    const length = view.getUint32(offset);
+    const typeBytes = bytes.subarray(offset + 4, offset + 8);
+    const type = new TextDecoder('latin1').decode(typeBytes);
+    const dataStart = offset + 8;
+    const dataEnd = dataStart + length;
+    if (dataEnd + 4 > bytes.length) {
+      throw new Error(`PNG chunk '${type}' declares a length that runs past the end of the file`);
+    }
+    const data = bytes.subarray(dataStart, dataEnd);
+    if (onWarning !== undefined) {
+      const storedCrc = view.getUint32(dataEnd);
+      const computedCrc = crc32(concatBytes([typeBytes, data]));
+      if (storedCrc !== computedCrc) {
+        onWarning(`PNG chunk '${type}' failed its CRC32 check`);
+      }
+    }
+    chunks.push({ type, data });
+    offset = dataEnd + 4;
+    if (type === 'IEND') {
+      break;
+    }
+  }
+  return chunks;
+}
+
+interface Ihdr {
+  readonly width: number;
+  readonly height: number;
+  readonly bitDepth: number;
+  readonly colorType: number;
+  readonly interlace: number;
+}
+
+function parseIhdr(data: Uint8Array<ArrayBuffer>): Ihdr {
+  const view = requireDataView(data);
+  return {
+    width: view.getUint32(0),
+    height: view.getUint32(4),
+    bitDepth: data[8]!,
+    colorType: data[9]!,
+    interlace: data[12]!,
+  };
+}
+
+function channelsForColorType(colorType: number): number {
+  if (colorType === 0) {
+    return 1; // grayscale
+  }
+  if (colorType === 2) {
+    return 3; // truecolor
+  }
+  if (colorType === 3) {
+    return 1; // palette index
+  }
+  if (colorType === 4) {
+    return 2; // grayscale + alpha
+  }
+  if (colorType === 6) {
+    return 4; // truecolor + alpha
+  }
+  throw new Error(`unsupported PNG colour type: ${colorType}`);
+}
+
+// PNG's own "bpp" for filtering purposes: bytes per complete pixel, rounded up, minimum 1.
+function filterBpp(bitDepth: number, channels: number): number {
+  return Math.max(1, Math.ceil((bitDepth * channels) / 8));
+}
+
+// Unpacks one already-unfiltered scanline into one number per sample (raw, unscaled -- 0..2^bitDepth-1 for bit depths under 16, or the 16-bit value's high byte for bitDepth 16, per this decoder's documented 16-bit handling: reduce every depth down to an 8-bit-equivalent raw sample here, and scale to a full 0..255 display range later only for grayscale, where sub-8-bit depths need it).
+function unpackRow(rowBytes: Uint8Array<ArrayBuffer>, width: number, channels: number, bitDepth: number): number[] {
+  const sampleCount = width * channels;
+  const samples: number[] = new Array<number>(sampleCount);
+  if (bitDepth === 8) {
+    for (let i = 0; i < sampleCount; i++) {
+      samples[i] = rowBytes[i]!;
+    }
+  } else if (bitDepth === 16) {
+    for (let i = 0; i < sampleCount; i++) {
+      samples[i] = rowBytes[i * 2]!; // high byte only
+    }
+  } else {
+    const mask = (1 << bitDepth) - 1;
+    for (let i = 0; i < sampleCount; i++) {
+      const bitOffset = i * bitDepth;
+      const byteIndex = bitOffset >> 3;
+      const shift = 8 - bitDepth - (bitOffset & 7);
+      samples[i] = (rowBytes[byteIndex]! >> shift) & mask;
+    }
+  }
+  return samples;
+}
+
+function readTrnsGrayValue(trns: Uint8Array<ArrayBuffer>): number {
+  return requireDataView(trns).getUint16(0);
+}
+
+function readTrnsRgbKey(trns: Uint8Array<ArrayBuffer>): readonly [number, number, number] {
+  const view = requireDataView(trns);
+  return [view.getUint16(0), view.getUint16(2), view.getUint16(4)];
+}
+
+function scaleToByte(sample: number, bitDepth: number): number {
+  if (bitDepth === 16) {
+    return sample; // already the high byte, i.e. already 0..255
+  }
+  const maxSample = (1 << bitDepth) - 1;
+  return Math.round((sample * 255) / maxSample);
+}
+
+// Decodes PNG file bytes into raw, normalised pixel data. Supports colour types 0/2/3/4/6 (gray, truecolor, indexed+PLTE, gray+alpha, truecolor+alpha) at bit depths 1/2/4/8/16 as applicable, plus tRNS transparency for all three non-alpha colour types. Adam7-interlaced sources are rejected explicitly (diagnostic-worthy but essentially never produced by Office/mainstream tooling) rather than silently decoded wrong.
+export function decodePng(bytes: Uint8Array<ArrayBuffer>, options: PngDecodeOptions = {}): RawImage {
+  for (let i = 0; i < PNG_SIGNATURE.length; i++) {
+    if (bytes[i] !== PNG_SIGNATURE[i]) {
+      throw new Error('not a valid PNG file: bad signature');
+    }
+  }
+
+  const chunks = readChunks(bytes, options.onWarning);
+  const ihdrChunk = chunks[0];
+  if (ihdrChunk?.type !== 'IHDR') {
+    throw new Error('PNG file does not begin with an IHDR chunk');
+  }
+  const ihdr = parseIhdr(ihdrChunk.data);
+  if (ihdr.interlace !== 0) {
+    throw new Error('Adam7-interlaced PNG images are not supported');
+  }
+
+  const channels = channelsForColorType(ihdr.colorType);
+  const bpp = filterBpp(ihdr.bitDepth, channels);
+  const bytesPerRow = Math.ceil((ihdr.width * channels * ihdr.bitDepth) / 8);
+
+  const idatChunks = chunks.filter((c) => c.type === 'IDAT').map((c) => c.data);
+  if (idatChunks.length === 0) {
+    throw new Error('PNG file has no IDAT chunks');
+  }
+  // Every IDAT chunk must be concatenated before inflating -- multi-IDAT files are routine (Office emits them), and inflating only the first chunk is the single most common PNG-decoder bug.
+  const compressed = concatBytes(idatChunks);
+  const { bytes: inflated, recovered } = inflateTolerant(compressed);
+  if (recovered && options.onWarning !== undefined) {
+    options.onWarning('PNG IDAT stream required tolerant recovery (truncated or malformed)');
+  }
+  const unfiltered = unfilterScanlines(inflated, ihdr.height, bytesPerRow, bpp);
+
+  const palette = ihdr.colorType === 3 ? chunks.find((c) => c.type === 'PLTE')?.data : undefined;
+  if (ihdr.colorType === 3 && palette === undefined) {
+    throw new Error('indexed-colour PNG has no PLTE chunk');
+  }
+  const trns = chunks.find((c) => c.type === 'tRNS')?.data;
+
+  return buildRawImage(ihdr, channels, bytesPerRow, unfiltered, palette, trns);
+}
+
+function buildRawImage(
+  ihdr: Ihdr,
+  channels: number,
+  bytesPerRow: number,
+  unfiltered: Uint8Array<ArrayBuffer>,
+  palette: Uint8Array<ArrayBuffer> | undefined,
+  trns: Uint8Array<ArrayBuffer> | undefined,
+): RawImage {
+  const { width, height, bitDepth, colorType } = ihdr;
+  const outChannels: 1 | 3 = colorType === 0 || colorType === 4 ? 1 : 3;
+  const data = new Uint8Array(width * height * outChannels);
+  const hasAlpha = colorType === 4 || colorType === 6 || trns !== undefined;
+  const alpha = hasAlpha ? new Uint8Array(width * height).fill(255) : undefined;
+
+  const trnsGray = colorType === 0 && trns !== undefined ? readTrnsGrayValue(trns) : undefined;
+  const trnsRgb = colorType === 2 && trns !== undefined ? readTrnsRgbKey(trns) : undefined;
+
+  for (let y = 0; y < height; y++) {
+    const rowStart = y * bytesPerRow;
+    const rowBytes = unfiltered.subarray(rowStart, rowStart + bytesPerRow);
+    const samples = unpackRow(rowBytes, width, channels, bitDepth);
+    for (let x = 0; x < width; x++) {
+      const pixelBase = x * channels;
+      const outBase = (y * width + x) * outChannels;
+      const alphaIndex = y * width + x;
+
+      if (colorType === 0) {
+        const g = samples[pixelBase]!;
+        data[outBase] = scaleToByte(g, bitDepth);
+        if (alpha !== undefined && trnsGray !== undefined) {
+          alpha[alphaIndex] = g === trnsGray ? 0 : 255;
+        }
+      } else if (colorType === 2) {
+        const r = samples[pixelBase]!;
+        const g = samples[pixelBase + 1]!;
+        const b = samples[pixelBase + 2]!;
+        data[outBase] = r;
+        data[outBase + 1] = g;
+        data[outBase + 2] = b;
+        if (alpha !== undefined && trnsRgb !== undefined) {
+          const [kr, kg, kb] = trnsRgb;
+          alpha[alphaIndex] = r === kr && g === kg && b === kb ? 0 : 255;
+        }
+      } else if (colorType === 3) {
+        const index = samples[pixelBase]!;
+        if (palette === undefined) {
+          throw new Error('indexed-colour PNG has no PLTE chunk');
+        }
+        data[outBase] = palette[index * 3]!;
+        data[outBase + 1] = palette[index * 3 + 1]!;
+        data[outBase + 2] = palette[index * 3 + 2]!;
+        if (alpha !== undefined && trns !== undefined) {
+          alpha[alphaIndex] = index < trns.length ? trns[index]! : 255;
+        }
+      } else if (colorType === 4) {
+        const g = samples[pixelBase]!;
+        const a = samples[pixelBase + 1]!;
+        data[outBase] = scaleToByte(g, bitDepth);
+        if (alpha !== undefined) {
+          alpha[alphaIndex] = scaleToByte(a, bitDepth);
+        }
+      } else {
+        // colorType === 6: truecolor + alpha
+        data[outBase] = samples[pixelBase]!;
+        data[outBase + 1] = samples[pixelBase + 1]!;
+        data[outBase + 2] = samples[pixelBase + 2]!;
+        if (alpha !== undefined) {
+          alpha[alphaIndex] = samples[pixelBase + 3]!;
+        }
+      }
+    }
+  }
+
+  return alpha === undefined
+    ? { width, height, channels: outChannels, data }
+    : { width, height, channels: outChannels, data, alpha };
+}