@ultimat3/core 1.0.0

package/src/image/pipeline.ts

@@ -0,0 +1,117 @@
+// Single responsibility: THE image pipeline. Decode -> resize -> encode, one entry point,
+// one capability list. `storage`, `seo` and `pwa` all call this file and none of them owns a
+// second copy: responsive variants, blur placeholders and PWA icons are the same three steps
+// with different numbers, and a framework that generated them twice would drift twice.
+
+import { imageUnsupported } from './errors';
+import { decodeJpeg } from './jpeg-decode';
+import { encodeJpeg } from './jpeg-encode';
+import { DEFAULT_JPEG_QUALITY } from './jpeg-tables';
+import { decodePng, encodePng } from './png';
+import { IMAGE_MIME_TYPES, type ImageFormat, probeImage, sniffImageFormat } from './probe';
+import { hasAlpha, type Raster } from './raster';
+import { type ResizeSpec, resizeRaster } from './resize';
+
+/**
+ * What the built-in, zero-dependency pipeline can actually produce. Bun ships no image API and
+ * the contract forbids `sharp`, so WebP and AVIF are *probed and served*, never synthesised
+ * here — a caller that needs them routes transforms through a driver (see `@ultimat3/seo`'s
+ * `ImageTransformDriver`). Publishing the real list is what stops `<source type="image/avif">`
+ * from promising a variant nothing can encode.
+ */
+export const DECODABLE_FORMATS = ['png', 'jpeg'] as const;
+export const ENCODABLE_FORMATS = ['png', 'jpeg'] as const;
+
+export type DecodableFormat = (typeof DECODABLE_FORMATS)[number];
+export type EncodableFormat = (typeof ENCODABLE_FORMATS)[number];
+
+export const canDecode = (format: ImageFormat): format is DecodableFormat =>
+  (DECODABLE_FORMATS as readonly string[]).includes(format);
+
+export const canEncode = (format: ImageFormat): format is EncodableFormat =>
+  (ENCODABLE_FORMATS as readonly string[]).includes(format);
+
+/** Small enough to inline in HTML, big enough to blur convincingly. */
+export const BLUR_PLACEHOLDER_WIDTH = 16;
+
+const decodeFix =
+  'convert the source to PNG or JPEG before it reaches the pipeline, or pass a custom ' +
+  'ImageTransformDriver that can read it';
+
+const encodeFix =
+  "request 'png' or 'jpeg', or route the transform through an ImageTransformDriver (a CDN " +
+  'or an external encoder) that can produce it';
+
+/** Bytes in, RGBA out. The only place a format is turned into pixels. */
+export function decodeImage(bytes: Uint8Array): Raster {
+  const format = sniffImageFormat(bytes);
+  if (format === null) {
+    throw imageUnsupported('the bytes match no image format this pipeline knows', decodeFix);
+  }
+  if (format === 'png') return decodePng(bytes);
+  if (format === 'jpeg') return decodeJpeg(bytes);
+  throw imageUnsupported(`decoding ${format} is not built in`, decodeFix, { format });
+}
+
+/** RGBA in, bytes out. `quality` is ignored by lossless formats. */
+export function encodeImage(
+  raster: Raster,
+  format: ImageFormat,
+  quality: number = DEFAULT_JPEG_QUALITY,
+): Uint8Array {
+  if (format === 'png') return encodePng(raster);
+  if (format === 'jpeg') return encodeJpeg(raster, quality);
+  throw imageUnsupported(`encoding ${format} is not built in`, encodeFix, { format });
+}
+
+export interface ImageTransformSpec extends ResizeSpec {
+  /** Defaults to whichever encodable format preserves the source: PNG if it has alpha. */
+  readonly format?: ImageFormat | undefined;
+  /** 1-100, JPEG only. */
+  readonly quality?: number | undefined;
+}
+
+/**
+ * PNG keeps transparency, JPEG does not; picking by the pixels means a logo never silently
+ * grows a black background because nobody passed `format`.
+ */
+export const defaultFormatFor = (raster: Raster): EncodableFormat =>
+  hasAlpha(raster) ? 'png' : 'jpeg';
+
+/** The whole pipeline in one call: decode, resize, encode. */
+export function transformImageBytes(bytes: Uint8Array, spec: ImageTransformSpec = {}): Uint8Array {
+  const { format } = spec;
+  // The spec alone answers "can this be written?", so answer it here — decoding and resampling
+  // 64 megapixels first, only to refuse at the encoder, is work nobody can use.
+  if (format !== undefined && !canEncode(format)) {
+    throw imageUnsupported(`encoding ${format} is not built in`, encodeFix, { format });
+  }
+  const source = decodeImage(bytes);
+  const resized = resizeRaster(source, spec);
+  return encodeImage(resized, format ?? defaultFormatFor(resized), spec.quality);
+}
+
+/** Chunked because spreading a whole image into `String.fromCharCode` overflows the stack. */
+function base64Of(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  }
+  return btoa(binary);
+}
+
+export const dataUrl = (bytes: Uint8Array, format: ImageFormat): string =>
+  `data:${IMAGE_MIME_TYPES[format]};base64,${base64Of(bytes)}`;
+
+/**
+ * The LQIP: the source at 16px wide, as a `data:` URI. Always PNG — at this size a JPEG's
+ * own headers cost more than the pixels, and alpha survives.
+ */
+export function blurDataUrl(bytes: Uint8Array, width: number = BLUR_PLACEHOLDER_WIDTH): string {
+  const tiny = resizeRaster(decodeImage(bytes), { width });
+  return dataUrl(encodePng(tiny), 'png');
+}
+
+export type { ImageFormat };
+/** Intrinsic dimensions without decoding — this is what keeps CLS at 0 for every format. */
+export { IMAGE_MIME_TYPES, probeImage, sniffImageFormat };

package/src/image/png-bytes.ts

@@ -0,0 +1,91 @@
+// Single responsibility: PNG's byte-level primitives — signature, chunk framing, the two
+// checksums and the Paeth predictor. Both directions of the codec need every one of them, so
+// they live here once: a CRC that agreed with itself but not with libpng would be invisible
+// if the reader and the writer each carried their own copy.
+
+const NO_BYTES = new Uint8Array(0);
+
+export const PNG_SIGNATURE = Uint8Array.of(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a);
+
+export const EMPTY_CHUNK_DATA: Uint8Array = NO_BYTES;
+
+const CRC_TABLE = new Uint32Array(256).map((_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k += 1) c = (c & 1) === 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c;
+});
+
+export function crc32(bytes: Uint8Array, start: number, end: number): number {
+  let c = 0xffffffff;
+  for (let i = start; i < end; i += 1) {
+    c = (CRC_TABLE[(c ^ (bytes[i] ?? 0)) & 0xff] ?? 0) ^ (c >>> 8);
+  }
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** RFC 1950 checksum. 5552 is the most sums that fit before the accumulators overflow. */
+export function adler32(bytes: Uint8Array): number {
+  let a = 1;
+  let b = 0;
+  let i = 0;
+  while (i < bytes.length) {
+    const end = Math.min(i + 5552, bytes.length);
+    for (; i < end; i += 1) {
+      a += bytes[i] ?? 0;
+      b += a;
+    }
+    a %= 65521;
+    b %= 65521;
+  }
+  return ((b << 16) | a) >>> 0;
+}
+
+export const readU32 = (bytes: Uint8Array, at: number): number =>
+  (bytes[at] ?? 0) * 0x1000000 +
+  (((bytes[at + 1] ?? 0) << 16) | ((bytes[at + 2] ?? 0) << 8) | (bytes[at + 3] ?? 0));
+
+export function writeU32(out: Uint8Array, at: number, value: number): void {
+  out[at] = (value >>> 24) & 0xff;
+  out[at + 1] = (value >>> 16) & 0xff;
+  out[at + 2] = (value >>> 8) & 0xff;
+  out[at + 3] = value & 0xff;
+}
+
+export function joinBytes(parts: readonly Uint8Array[]): Uint8Array {
+  if (parts.length === 1) return parts[0] ?? NO_BYTES;
+  let total = 0;
+  for (const part of parts) total += part.length;
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+}
+
+/** One framed chunk: length, type, data, CRC-32 over type and data. */
+export function chunk(type: string, data: Uint8Array): Uint8Array {
+  const out = new Uint8Array(data.length + 12);
+  writeU32(out, 0, data.length);
+  for (let i = 0; i < 4; i += 1) out[4 + i] = type.charCodeAt(i);
+  out.set(data, 8);
+  writeU32(out, data.length + 8, crc32(out, 4, data.length + 8));
+  return out;
+}
+
+/** Bun's zlib refuses a view onto a SharedArrayBuffer, and decoder input can be backed by one. */
+export const unshared = (view: Uint8Array): Uint8Array<ArrayBuffer> =>
+  view.buffer instanceof ArrayBuffer
+    ? new Uint8Array(view.buffer, view.byteOffset, view.byteLength)
+    : Uint8Array.from(view);
+
+/** The filter both directions predict with: the decoder adds it back, the encoder subtracts it. */
+export function paeth(a: number, b: number, c: number): number {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+}

package/src/image/png.ts

@@ -0,0 +1,433 @@
+// Single responsibility: the PNG codec. Every colour type, bit depth and row filter the format
+// allows decodes into the one 8-bit RGBA raster; encoding has exactly one output shape (colour
+// type 6, adaptive filters). Chunk CRCs are verified on the way in because a decoder that
+// tolerates a corrupt chunk hands the app wrong pixels instead of a coded error.
+
+import { imageDecodeFailed, imageUnsupported } from './errors';
+import {
+  adler32,
+  chunk,
+  crc32,
+  EMPTY_CHUNK_DATA,
+  joinBytes,
+  PNG_SIGNATURE,
+  paeth,
+  readU32,
+  unshared,
+  writeU32,
+} from './png-bytes';
+import { assertPixelBudget, type Raster, rasterFrom } from './raster';
+
+/** Bytes per pixel of the encoder's one output shape, and its filter offset. */
+const RGBA_BPP = 4;
+
+/** Samples per pixel, by colour type. A palette row carries one index, not one colour. */
+const CHANNELS = Uint8Array.of(1, 0, 3, 1, 2, 0, 4);
+
+/**
+ * PNG spec table 11.1, keyed by colour type. Every legal depth is a power of two, so the set of
+ * them masks directly — which is also why a depth like 3 has to be rejected as not one at all.
+ */
+const LEGAL_DEPTHS: Readonly<Record<number, number>> = {
+  0: 1 | 2 | 4 | 8 | 16,
+  2: 8 | 16,
+  3: 1 | 2 | 4 | 8,
+  4: 8 | 16,
+  6: 8 | 16,
+};
+
+const channelsOf = (colourType: number): number => CHANNELS[colourType] ?? 1;
+
+const isLegalShape = (colourType: number, bitDepth: number): boolean =>
+  bitDepth !== 0 &&
+  (bitDepth & (bitDepth - 1)) === 0 &&
+  ((LEGAL_DEPTHS[colourType] ?? 0) & bitDepth) === bitDepth;
+
+/** Stretches a sub-byte sample across the full range, so depth 1 reads 0/255 rather than 0/1. */
+const UPSCALE: Readonly<Record<number, number>> = { 1: 255, 2: 85, 4: 17 };
+
+interface PngHeader {
+  readonly width: number;
+  readonly height: number;
+  readonly bitDepth: number;
+  readonly colourType: number;
+}
+
+function assertSignature(bytes: Uint8Array): void {
+  for (let i = 0; i < PNG_SIGNATURE.length; i += 1) {
+    if (bytes[i] === PNG_SIGNATURE[i]) continue;
+    const found = Array.from(bytes.subarray(0, 8));
+    throw imageDecodeFailed(`the bytes are not a PNG: signature reads ${found}`, {
+      signature: found,
+    });
+  }
+}
+
+function readHeader(bytes: Uint8Array, at: number, length: number): PngHeader {
+  if (length !== 13) {
+    throw imageDecodeFailed(`the PNG IHDR chunk carries ${length} bytes, not the required 13`, {
+      length,
+    });
+  }
+  const width = readU32(bytes, at);
+  const height = readU32(bytes, at + 4);
+  const bitDepth = bytes[at + 8] ?? 0;
+  const colourType = bytes[at + 9] ?? 0;
+  const compression = bytes[at + 10] ?? 0;
+  const filter = bytes[at + 11] ?? 0;
+  const interlace = bytes[at + 12] ?? 0;
+  if (!isLegalShape(colourType, bitDepth)) {
+    throw imageDecodeFailed(
+      `the PNG declares colour type ${colourType} at ${bitDepth} bits, a pair the format omits`,
+      { colourType, bitDepth },
+    );
+  }
+  if (compression !== 0 || filter !== 0 || interlace > 1) {
+    throw imageDecodeFailed(
+      `the PNG declares compression ${compression}, filter method ${filter}, interlace ` +
+        `${interlace}; only 0, 0 and 0-or-1 have ever been defined`,
+      { compression, filter, interlace },
+    );
+  }
+  // Before a single byte is allocated: the declared size is the only bomb guard that is cheap.
+  assertPixelBudget(width, height, 'png');
+  if (interlace === 1) {
+    throw imageUnsupported(
+      'the file is an Adam7 interlaced PNG, which the built-in decoder does not implement',
+      'convert the file to a non-interlaced PNG: `convert in.png -interlace none out.png`',
+      { width, height },
+    );
+  }
+  return { width, height, bitDepth, colourType };
+}
+
+/**
+ * PNG wraps its deflate stream in zlib, so the 2-byte header and 4-byte Adler-32 trailer are
+ * validated and stripped here and the payload is inflated as RAW deflate. `windowBits: -15` states
+ * that: Bun's documented default is 15, meaning zlib-wrapped, and a version that starts honouring
+ * it would otherwise reject every PNG we read.
+ */
+function inflateIdat(stream: Uint8Array): Uint8Array {
+  const cmf = stream[0] ?? 0;
+  const flg = stream[1] ?? 0;
+  const check = ((cmf << 8) | flg) >>> 0;
+  if (stream.length < 6 || (cmf & 0x0f) !== 8 || check % 31 !== 0) {
+    throw imageDecodeFailed(
+      `the PNG IDAT stream is ${stream.length} bytes opening 0x${check.toString(16)}, not zlib`,
+      { header: check, compressed: stream.length },
+    );
+  }
+  if ((flg & 0x20) !== 0) {
+    throw imageUnsupported(
+      'the PNG IDAT stream sets a zlib preset dictionary, which the PNG format forbids',
+      're-export the file with a conformant encoder: `convert in.png out.png`',
+    );
+  }
+  try {
+    return Bun.inflateSync(unshared(stream.subarray(2, stream.length - 4)), { windowBits: -15 });
+  } catch (error) {
+    const why = error instanceof Error ? error.message : String(error);
+    throw imageDecodeFailed(`the PNG IDAT stream could not be inflated: ${why}`, {
+      compressed: stream.length,
+    });
+  }
+}
+
+/** Reverses the per-scanline filter in place, leaving each row's raw bytes where they lay. */
+function unfilter(raw: Uint8Array, height: number, rowBytes: number, bpp: number): void {
+  const stride = rowBytes + 1;
+  for (let y = 0; y < height; y += 1) {
+    const at = y * stride;
+    const filter = raw[at] ?? 0;
+    const row = at + 1;
+    const prev = row - stride;
+    const hasPrev = y > 0;
+    switch (filter) {
+      case 0:
+        break;
+      case 1: {
+        for (let i = bpp; i < rowBytes; i += 1) {
+          raw[row + i] = ((raw[row + i] ?? 0) + (raw[row + i - bpp] ?? 0)) & 0xff;
+        }
+        break;
+      }
+      case 2: {
+        if (!hasPrev) break;
+        for (let i = 0; i < rowBytes; i += 1) {
+          raw[row + i] = ((raw[row + i] ?? 0) + (raw[prev + i] ?? 0)) & 0xff;
+        }
+        break;
+      }
+      // Average and Paeth read the same three neighbours; only the predictor differs.
+      case 3:
+      case 4: {
+        for (let i = 0; i < rowBytes; i += 1) {
+          const left = i >= bpp ? (raw[row + i - bpp] ?? 0) : 0;
+          const up = hasPrev ? (raw[prev + i] ?? 0) : 0;
+          const upLeft = hasPrev && i >= bpp ? (raw[prev + i - bpp] ?? 0) : 0;
+          const guess = filter === 3 ? (left + up) >> 1 : paeth(left, up, upLeft);
+          raw[row + i] = ((raw[row + i] ?? 0) + guess) & 0xff;
+        }
+        break;
+      }
+      default:
+        throw imageDecodeFailed(
+          `PNG scanline ${y} declares filter type ${filter}, which is not one of 0-4`,
+          { row: y, filter },
+        );
+    }
+  }
+}
+
+/** One scanline of unfiltered bytes into whole samples, at whatever precision the file uses. */
+function readSamples(raw: Uint8Array, at: number, out: Uint16Array, bitDepth: number): void {
+  const count = out.length;
+  if (bitDepth === 8) {
+    for (let i = 0; i < count; i += 1) out[i] = raw[at + i] ?? 0;
+    return;
+  }
+  if (bitDepth === 16) {
+    for (let i = 0; i < count; i += 1) {
+      out[i] = ((raw[at + i * 2] ?? 0) << 8) | (raw[at + i * 2 + 1] ?? 0);
+    }
+    return;
+  }
+  const perByte = 8 / bitDepth;
+  const mask = (1 << bitDepth) - 1;
+  for (let i = 0; i < count; i += 1) {
+    const byte = raw[at + ((i / perByte) | 0)] ?? 0;
+    out[i] = (byte >> (8 - bitDepth * ((i % perByte) + 1))) & mask;
+  }
+}
+
+/**
+ * `tRNS` on a greyscale or truecolour image is not a table: it names ONE sample value that is
+ * fully transparent, at the image's own bit depth. Ignoring it drops a logo's cut-out.
+ */
+function transparentKey(colourType: number, trns: Uint8Array | undefined): Uint16Array | undefined {
+  if (trns === undefined || (colourType !== 0 && colourType !== 2)) return undefined;
+  const samples = colourType === 2 ? 3 : 1;
+  if (trns.length < samples * 2) return undefined;
+  const key = new Uint16Array(samples);
+  for (let i = 0; i < samples; i += 1) {
+    key[i] = ((trns[i * 2] ?? 0) << 8) | (trns[i * 2 + 1] ?? 0);
+  }
+  return key;
+}
+
+/**
+ * Which sample of a pixel feeds R, G, B and A, by colour type; `-1` is "no alpha sample". Stating
+ * the mapping once stops four colour types from becoming four loops that can each be wrong.
+ */
+const RGBA_SOURCE: Readonly<Record<number, readonly [number, number, number, number]>> = {
+  0: [0, 0, 0, -1],
+  2: [0, 1, 2, -1],
+  4: [0, 0, 0, 1],
+  6: [0, 1, 2, 3],
+};
+
+/** Opaque unless a `tRNS` key colour matches this pixel's samples exactly. */
+function opacityFor(samples: Uint16Array, at: number, key: Uint16Array | undefined): number {
+  if (key === undefined) return 255;
+  for (let i = 0; i < key.length; i += 1) {
+    if (samples[at + i] !== key[i]) return 255;
+  }
+  return 0;
+}
+
+function expand(
+  raw: Uint8Array,
+  header: PngHeader,
+  palette: Uint8Array | undefined,
+  trns: Uint8Array | undefined,
+): Uint8ClampedArray {
+  const { width, height, bitDepth, colourType } = header;
+  if (colourType === 3 && palette === undefined) {
+    throw imageDecodeFailed('the PNG is indexed colour but carries no PLTE chunk');
+  }
+  const plte = palette ?? EMPTY_CHUNK_DATA;
+  const entries = (plte.length / 3) | 0;
+  const channels = channelsOf(colourType);
+  const stride = Math.ceil((width * channels * bitDepth) / 8) + 1;
+  const upscale = UPSCALE[bitDepth] ?? 1;
+  const key = transparentKey(colourType, trns);
+  const samples = new Uint16Array(width * channels);
+  const pixels = new Uint8ClampedArray(width * height * 4);
+  const [sr, sg, sb, sa] = RGBA_SOURCE[colourType] ?? [0, 0, 0, -1];
+  const byteOf = (sample: number): number => (bitDepth === 16 ? sample >>> 8 : sample * upscale);
+
+  for (let y = 0; y < height; y += 1) {
+    readSamples(raw, y * stride + 1, samples, bitDepth);
+    let p = y * width * 4;
+    for (let x = 0; x < width; x += 1) {
+      const s = x * channels;
+      if (colourType === 3) {
+        const index = samples[s] ?? 0;
+        if (index >= entries) {
+          throw imageDecodeFailed(
+            `PNG pixel ${x},${y} uses palette index ${index} but PLTE holds ${entries} entries`,
+            { x, y, index, entries },
+          );
+        }
+        pixels[p] = plte[index * 3] ?? 0;
+        pixels[p + 1] = plte[index * 3 + 1] ?? 0;
+        pixels[p + 2] = plte[index * 3 + 2] ?? 0;
+        pixels[p + 3] = trns !== undefined && index < trns.length ? (trns[index] ?? 255) : 255;
+      } else {
+        pixels[p] = byteOf(samples[s + sr] ?? 0);
+        pixels[p + 1] = byteOf(samples[s + sg] ?? 0);
+        pixels[p + 2] = byteOf(samples[s + sb] ?? 0);
+        pixels[p + 3] = sa >= 0 ? byteOf(samples[s + sa] ?? 0) : opacityFor(samples, s, key);
+      }
+      p += 4;
+    }
+  }
+  return pixels;
+}
+
+/** PNG bytes in, RGBA out. Every chunk is CRC-checked before a single pixel is believed. */
+export function decodePng(bytes: Uint8Array): Raster {
+  assertSignature(bytes);
+  let header: PngHeader | undefined;
+  let palette: Uint8Array | undefined;
+  let trns: Uint8Array | undefined;
+  const idat: Uint8Array[] = [];
+  let ended = false;
+  let offset = 8;
+
+  while (offset + 8 <= bytes.length) {
+    const length = readU32(bytes, offset);
+    const type = String.fromCharCode(...bytes.subarray(offset + 4, offset + 8));
+    const dataAt = offset + 8;
+    const crcAt = dataAt + length;
+    if (crcAt + 4 > bytes.length) {
+      throw imageDecodeFailed(
+        `the PNG ends after ${bytes.length} bytes, inside chunk ${type} at offset ${offset}`,
+        { chunk: type, offset, declared: length },
+      );
+    }
+    const declared = readU32(bytes, crcAt);
+    const actual = crc32(bytes, offset + 4, crcAt);
+    if (declared !== actual) {
+      throw imageDecodeFailed(
+        `PNG chunk ${type} fails its CRC-32: the file says ${declared}, the bytes hash to ${actual}`,
+        { chunk: type, declared, actual },
+      );
+    }
+    if (header === undefined && type !== 'IHDR') {
+      throw imageDecodeFailed(`the first PNG chunk is ${type}, not IHDR`, { chunk: type });
+    }
+    if (type === 'IHDR') {
+      if (header !== undefined) throw imageDecodeFailed('the PNG carries more than one IHDR chunk');
+      header = readHeader(bytes, dataAt, length);
+    } else if (type === 'PLTE') {
+      palette = bytes.subarray(dataAt, crcAt);
+    } else if (type === 'tRNS') {
+      trns = bytes.subarray(dataAt, crcAt);
+    } else if (type === 'IDAT') {
+      idat.push(bytes.subarray(dataAt, crcAt));
+    } else if (type === 'IEND') {
+      ended = true;
+      break;
+    }
+    offset = crcAt + 4;
+  }
+
+  if (!ended) throw imageDecodeFailed('the PNG never reaches IEND, so the file is truncated');
+  if (header === undefined) throw imageDecodeFailed('the PNG carries no IHDR chunk');
+  if (idat.length === 0)
+    throw imageDecodeFailed('the PNG carries no IDAT chunk, so it has no rows');
+
+  const { width, height, bitDepth, colourType } = header;
+  const channels = channelsOf(colourType);
+  const rowBytes = Math.ceil((width * channels * bitDepth) / 8);
+  const expected = height * (rowBytes + 1);
+  const raw = inflateIdat(joinBytes(idat));
+  if (raw.length !== expected) {
+    throw imageDecodeFailed(
+      `the PNG inflates to ${raw.length} bytes but ${width}x${height} at ${bitDepth} bits over ` +
+        `${channels} channels needs exactly ${expected}`,
+      { inflated: raw.length, expected },
+    );
+  }
+  unfilter(raw, height, rowBytes, Math.max(1, Math.ceil((bitDepth * channels) / 8)));
+  return rasterFrom(width, height, expand(raw, header, palette, trns));
+}
+
+/**
+ * Filters one scanline into `out`, scored by the libpng heuristic: the sum of its bytes read as
+ * signed. The lowest sum is the row deflate compresses best, which is why an encoder that always
+ * wrote filter 0 would ship files roughly twice this size. A negative `prev` is "no row above".
+ */
+function filterScanline(
+  pixels: Uint8ClampedArray,
+  row: number,
+  prev: number,
+  stride: number,
+  filter: number,
+  out: Uint8Array,
+): number {
+  let score = 0;
+  const hasPrev = prev >= 0;
+  for (let i = 0; i < stride; i += 1) {
+    const raw = pixels[row + i] ?? 0;
+    const left = i >= RGBA_BPP ? (pixels[row + i - RGBA_BPP] ?? 0) : 0;
+    const up = hasPrev ? (pixels[prev + i] ?? 0) : 0;
+    let value = raw;
+    if (filter === 1) value = raw - left;
+    else if (filter === 2) value = raw - up;
+    else if (filter === 3) value = raw - ((left + up) >> 1);
+    else if (filter === 4) {
+      const upLeft = hasPrev && i >= RGBA_BPP ? (pixels[prev + i - RGBA_BPP] ?? 0) : 0;
+      value = raw - paeth(left, up, upLeft);
+    }
+    value &= 0xff;
+    out[i] = value;
+    score += value < 128 ? value : 256 - value;
+  }
+  return score;
+}
+
+/**
+ * RGBA in, PNG bytes out — always 8-bit colour type 6, non-interlaced. Branching on opacity would
+ * give the framework two encoders to keep correct, and alpha on an opaque image is nearly free
+ * after deflate, so there is one path.
+ */
+export function encodePng(raster: Raster): Uint8Array {
+  const { width, height, pixels } = raster;
+  const stride = width * 4;
+  const filtered = new Uint8Array(height * (stride + 1));
+  const scratch = new Uint8Array(stride);
+  for (let y = 0; y < height; y += 1) {
+    const row = y * stride;
+    const at = y * (stride + 1);
+    let best = Number.POSITIVE_INFINITY;
+    for (let filter = 0; filter <= 4; filter += 1) {
+      const score = filterScanline(pixels, row, y > 0 ? row - stride : -1, stride, filter, scratch);
+      if (score >= best) continue;
+      best = score;
+      filtered[at] = filter;
+      filtered.set(scratch, at + 1);
+    }
+  }
+
+  // `windowBits: -15` asks for RAW deflate explicitly, because the zlib envelope PNG requires is
+  // written by hand below — leaving it to the default would double-wrap the stream the day Bun's
+  // documented default (15, zlib-wrapped) is the one that actually applies.
+  const deflated = Bun.deflateSync(filtered, { windowBits: -15 });
+  const idat = new Uint8Array(deflated.length + 6);
+  idat.set([0x78, 0x01]);
+  idat.set(deflated, 2);
+  writeU32(idat, deflated.length + 2, adler32(filtered));
+
+  const ihdr = new Uint8Array(13);
+  writeU32(ihdr, 0, width);
+  writeU32(ihdr, 4, height);
+  ihdr.set([8, 6], 8);
+  return joinBytes([
+    PNG_SIGNATURE,
+    chunk('IHDR', ihdr),
+    chunk('IDAT', idat),
+    chunk('IEND', EMPTY_CHUNK_DATA),
+  ]);
+}