@ultimat3/core 1.0.0

package/src/image/jpeg-headers.ts

@@ -0,0 +1,267 @@
+// Single responsibility: what a JPEG's descriptive segments DECLARE, and what they are refused for
+// declaring — the DQT tables, the SOF geometry, the SOS component selection, and every coding
+// flavour this decoder names rather than guesses at. No entropy decoding and no pixels: that half
+// is `jpeg-decode.ts`, and keeping the two apart is what keeps either inside one file's worth of job.
+
+import { imageDecodeFailed, imageUnsupported } from './errors';
+import type { HuffmanTable } from './jpeg-huffman';
+import { AAN_SCALE, ZIGZAG } from './jpeg-tables';
+import { assertPixelBudget } from './raster';
+
+export const BASELINE_FIX =
+  're-encode to baseline JPEG: `convert in.jpg -interlace none baseline.jpg`';
+
+export const readU16 = (bytes: Uint8Array, at: number): number =>
+  ((bytes[at] ?? 0) << 8) | (bytes[at + 1] ?? 0);
+
+export const hex = (value: number | undefined): string =>
+  (value ?? 0).toString(16).toUpperCase().padStart(2, '0');
+
+/** Every SOF flavour this decoder refuses, named the way a re-encoding tool names it. */
+const REFUSED_SOF: Readonly<Record<number, string>> = {
+  194: 'SOF2 progressive DCT',
+  195: 'SOF3 lossless',
+  197: 'SOF5 differential sequential DCT',
+  198: 'SOF6 differential progressive DCT',
+  199: 'SOF7 differential lossless',
+  201: 'SOF9 extended sequential DCT, arithmetic coding',
+  202: 'SOF10 progressive DCT, arithmetic coding',
+  203: 'SOF11 lossless, arithmetic coding',
+  204: 'DAC arithmetic coding conditioning',
+  205: 'SOF13 differential sequential DCT, arithmetic coding',
+  206: 'SOF14 differential progressive DCT, arithmetic coding',
+  207: 'SOF15 differential lossless, arithmetic coding',
+};
+
+/** Refused at the marker, before a single coefficient is read: the name is the whole point. */
+export function assertSupportedCoding(marker: number): void {
+  const refused = REFUSED_SOF[marker];
+  if (refused === undefined) return;
+  throw imageUnsupported(`this JPEG is ${refused}, which is not baseline`, BASELINE_FIX, {
+    marker: `FF${hex(marker)}`,
+  });
+}
+
+/** APP14 payload `Adobe` + version + two flag words, then the colour transform at byte 11. */
+const ADOBE = [0x41, 0x64, 0x6f, 0x62, 0x65] as const;
+export const isAdobe = (seg: Uint8Array): boolean =>
+  seg.length >= 12 && ADOBE.every((byte, i) => seg[i] === byte);
+
+export interface Component {
+  readonly id: number;
+  readonly h: number;
+  readonly v: number;
+  readonly quantId: number;
+  /** MCU-padded sample plane; `stride` exceeds the image width whenever `h < maxH`. */
+  readonly samples: Uint8ClampedArray;
+  readonly stride: number;
+  readonly blocksPerLine: number;
+  readonly blocksPerColumn: number;
+  dequant: Float32Array;
+  /** The running DC predictor, reset at every restart interval and at every scan. */
+  pred: number;
+}
+
+export interface Frame {
+  readonly width: number;
+  readonly height: number;
+  readonly components: readonly Component[];
+  readonly maxH: number;
+  readonly maxV: number;
+  readonly mcusPerLine: number;
+  readonly mcusPerColumn: number;
+}
+
+/** One component as this scan selects it — resolved once, so no block decode re-checks a table. */
+export interface ScanComponent {
+  readonly comp: Component;
+  readonly dc: HuffmanTable;
+  readonly ac: HuffmanTable;
+}
+
+/**
+ * The shared AAN scale factors, folded into the quantisation table at DQT time along with the 1/8
+ * the two-dimensional inverse owes. That is what lets `idct1d` be 11 multiplies per row instead of
+ * the 64 a direct evaluation costs, without a single scaling step in the per-block hot path.
+ * `Float32Array` because every value it multiplies is float32 — the widths must match, not the
+ * numbers only.
+ */
+const AAN = Float32Array.from(AAN_SCALE);
+
+/** DQT carries any number of tables; 16-bit precision doubles each entry. */
+export function readQuantTables(seg: Uint8Array, quant: Array<Float32Array | undefined>): void {
+  let at = 0;
+  while (at < seg.length) {
+    const spec = seg[at] ?? 0;
+    at += 1;
+    const precision = spec >> 4;
+    const id = spec & 15;
+    if (precision > 1 || id > 3) {
+      throw imageDecodeFailed(`DQT declares table ${id} with precision code ${precision}`, {
+        id,
+        precision,
+      });
+    }
+    const size = precision === 1 ? 2 : 1;
+    if (at + 64 * size > seg.length) {
+      throw imageDecodeFailed(`DQT table ${id} is truncated: it needs ${64 * size} more bytes`, {
+        id,
+      });
+    }
+    const table = new Float32Array(64);
+    for (let k = 0; k < 64; k += 1) {
+      const value = size === 2 ? readU16(seg, at) : (seg[at] ?? 0);
+      at += size;
+      const natural = ZIGZAG[k] ?? 0;
+      table[natural] = value * (AAN[natural >> 3] ?? 1) * (AAN[natural & 7] ?? 1) * 0.125;
+    }
+    quant[id] = table;
+  }
+}
+
+export function readFrame(seg: Uint8Array, marker: number): Frame {
+  if (seg.length < 6) throw imageDecodeFailed('the frame header (SOF) is shorter than its fields');
+  const precision = seg[0] ?? 0;
+  if (precision !== 8) {
+    throw imageUnsupported(
+      `this JPEG codes ${precision}-bit samples; only 8-bit precision is decoded`,
+      BASELINE_FIX,
+      { precision, marker: `FF${hex(marker)}` },
+    );
+  }
+  const height = readU16(seg, 1);
+  const width = readU16(seg, 3);
+  assertPixelBudget(width, height, 'jpeg');
+  const count = seg[5] ?? 0;
+  if (count !== 1 && count !== 3) {
+    const model = count === 4 ? 'CMYK or YCCK' : 'an unknown colour model';
+    throw imageUnsupported(
+      `this JPEG has ${count} components (${model}); only 1-component greyscale and ` +
+        '3-component YCbCr are decoded',
+      BASELINE_FIX,
+      { components: count },
+    );
+  }
+  if (seg.length < 6 + count * 3) {
+    throw imageDecodeFailed(`the frame header ends before its ${count} component descriptors`);
+  }
+  const specs: Array<readonly [number, number, number, number]> = [];
+  let maxH = 1;
+  let maxV = 1;
+  for (let i = 0; i < count; i += 1) {
+    const at = 6 + i * 3;
+    const sampling = seg[at + 1] ?? 0;
+    const h = sampling >> 4;
+    const v = sampling & 15;
+    if (h < 1 || h > 4 || v < 1 || v > 4) {
+      throw imageDecodeFailed(`component ${i} declares ${h}x${v} sampling factors, outside 1-4`, {
+        h,
+        v,
+      });
+    }
+    maxH = Math.max(maxH, h);
+    maxV = Math.max(maxV, v);
+    specs.push([seg[at] ?? 0, h, v, seg[at + 2] ?? 0]);
+  }
+  const mcusPerLine = Math.ceil(width / (8 * maxH));
+  const mcusPerColumn = Math.ceil(height / (8 * maxV));
+  const components = specs.map(([id, h, v, quantId]) => {
+    const blocksPerLine = mcusPerLine * h;
+    const blocksPerColumn = mcusPerColumn * v;
+    const stride = blocksPerLine * 8;
+    return {
+      id,
+      h,
+      v,
+      quantId,
+      samples: new Uint8ClampedArray(stride * blocksPerColumn * 8),
+      stride,
+      blocksPerLine,
+      blocksPerColumn,
+      dequant: new Float32Array(64),
+      pred: 0,
+    };
+  });
+  return { width, height, components, maxH, maxV, mcusPerLine, mcusPerColumn };
+}
+
+const pickTable = (
+  tables: ReadonlyArray<HuffmanTable | undefined>,
+  id: number,
+  kind: string,
+  component: number,
+): HuffmanTable => {
+  const table = tables[id];
+  if (table === undefined) {
+    throw imageDecodeFailed(
+      `component ${component} selects ${kind} Huffman table ${id}, which no DHT segment defined`,
+      { component, kind, table: id },
+    );
+  }
+  return table;
+};
+
+/**
+ * The last three SOS bytes, which a sequential scan is only allowed one value of: the whole band
+ * (Ss=0, Se=63) at full precision (Ah=Al=0). Anything else is a progressive scan's shape wearing a
+ * baseline frame header — `decodeBlock` would read its coefficients as complete ones and emit a
+ * plausible, wrong image, which is exactly what this decoder refuses to do.
+ */
+function assertWholeBand(seg: Uint8Array, count: number): void {
+  const ss = seg[1 + count * 2] ?? 0;
+  const se = seg[2 + count * 2] ?? 0;
+  const approx = seg[3 + count * 2] ?? 0;
+  const ah = approx >> 4;
+  const al = approx & 15;
+  if (ss === 0 && se === 63 && ah === 0 && al === 0) return;
+  throw imageUnsupported(
+    `this JPEG's scan codes coefficients ${ss}-${se} at successive approximation ${ah}/${al}; a ` +
+      'sequential scan must carry the whole 0-63 band at 0/0',
+    BASELINE_FIX,
+    { ss, se, ah, al },
+  );
+}
+
+/**
+ * SOS: the components this scan codes, bound to the tables each one selects. Resolving them once,
+ * here, is what leaves the per-block hot path with no lookups and no validation of its own.
+ */
+export function readScanHeader(
+  seg: Uint8Array,
+  frame: Frame,
+  quant: ReadonlyArray<Float32Array | undefined>,
+  dcTables: ReadonlyArray<HuffmanTable | undefined>,
+  acTables: ReadonlyArray<HuffmanTable | undefined>,
+): ScanComponent[] {
+  const count = seg[0] ?? 0;
+  if (count < 1 || seg.length < 1 + count * 2 + 3) {
+    throw imageDecodeFailed(`the scan header (SOS) declares ${count} components but is too short`);
+  }
+  assertWholeBand(seg, count);
+  const scan: ScanComponent[] = [];
+  for (let i = 0; i < count; i += 1) {
+    const id = seg[1 + i * 2] ?? 0;
+    const selector = seg[2 + i * 2] ?? 0;
+    const comp = frame.components.find((candidate) => candidate.id === id);
+    if (comp === undefined) {
+      throw imageDecodeFailed(`the scan names component ${id}, which the frame never declared`, {
+        component: id,
+      });
+    }
+    const table = quant[comp.quantId];
+    if (table === undefined) {
+      throw imageDecodeFailed(
+        `component ${id} selects quantisation table ${comp.quantId}, which no DQT segment defined`,
+        { component: id, table: comp.quantId },
+      );
+    }
+    comp.dequant = table;
+    comp.pred = 0;
+    scan.push({
+      comp,
+      dc: pickTable(dcTables, selector >> 4, 'DC', id),
+      ac: pickTable(acTables, selector & 15, 'AC', id),
+    });
+  }
+  return scan;
+}

package/src/image/jpeg-huffman.ts

@@ -0,0 +1,202 @@
+// Single responsibility: JPEG's entropy layer — the canonical Huffman decode table derived from a
+// DHT segment's bits/values, and the MSB-first bit reader that unstuffs `FF 00` and refuses to read
+// through a marker. Split out of the decoder because it knows nothing of blocks, colour or frames.
+
+import { imageDecodeFailed } from './errors';
+
+/**
+ * T.81 Annex F's `MINCODE`/`MAXCODE`/`VALPTR` form rather than a code tree: three flat arrays
+ * indexed by code length decode a symbol in one comparison per bit, with no pointer chasing and
+ * no allocation per block. `maxcode[l]` is -1 when the table has no code of length `l`.
+ */
+export interface HuffmanTable {
+  readonly mincode: Int32Array;
+  readonly maxcode: Int32Array;
+  readonly valptr: Int32Array;
+  readonly values: Uint8Array;
+}
+
+/** `bits[i]` counts the codes of length `i + 1`; `values` lists the symbols in code order. */
+export function buildHuffmanTable(bits: Uint8Array, values: Uint8Array): HuffmanTable {
+  const mincode = new Int32Array(17);
+  const maxcode = new Int32Array(17).fill(-1);
+  const valptr = new Int32Array(17);
+  let code = 0;
+  let assigned = 0;
+  for (let length = 1; length <= 16; length += 1) {
+    const count = bits[length - 1] ?? 0;
+    if (count > 0) {
+      valptr[length] = assigned;
+      mincode[length] = code;
+      assigned += count;
+      code += count;
+      maxcode[length] = code - 1;
+    }
+    // More codes than the length can hold means the table is over-subscribed: some code would
+    // be a prefix of another and the scan would decode into a different image than it encodes.
+    if (code > 1 << length) {
+      throw imageDecodeFailed(
+        `a DHT table is over-subscribed at code length ${length}: it needs more codes than ` +
+          `${1 << length} distinct ones`,
+        { length, codes: code },
+      );
+    }
+    code <<= 1;
+  }
+  if (assigned !== values.length) {
+    throw imageDecodeFailed(
+      `a DHT table declares ${assigned} codes but carries ${values.length} symbols`,
+      { codes: assigned, symbols: values.length },
+    );
+  }
+  return { mincode, maxcode, valptr, values };
+}
+
+/** A DHT segment packs several tables, each a class/id byte then 16 counts then the symbols. */
+export function readHuffmanTables(
+  seg: Uint8Array,
+  dc: Array<HuffmanTable | undefined>,
+  ac: Array<HuffmanTable | undefined>,
+): void {
+  let at = 0;
+  while (at < seg.length) {
+    const spec = seg[at] ?? 0;
+    at += 1;
+    const kind = spec >> 4;
+    const id = spec & 15;
+    if (kind > 1 || id > 3) {
+      throw imageDecodeFailed(`DHT declares class ${kind} table ${id}, outside class 0-1 id 0-3`, {
+        kind,
+        id,
+      });
+    }
+    if (at + 16 > seg.length) {
+      throw imageDecodeFailed(`DHT table ${id} is truncated before its 16 code-length counts`, {
+        id,
+      });
+    }
+    const bits = seg.subarray(at, at + 16);
+    at += 16;
+    let total = 0;
+    for (let i = 0; i < 16; i += 1) total += bits[i] ?? 0;
+    if (at + total > seg.length) {
+      throw imageDecodeFailed(
+        `DHT table ${id} declares ${total} symbols but the segment holds ${seg.length - at}`,
+        { id, symbols: total },
+      );
+    }
+    (kind === 0 ? dc : ac)[id] = buildHuffmanTable(bits, seg.subarray(at, at + total));
+    at += total;
+  }
+}
+
+/**
+ * Walks entropy-coded data one bit at a time, most significant first. Every failure is a coded
+ * error rather than a zero bit, because padding a truncated scan with zeros yields a plausible
+ * grey image and no signal that anything went wrong.
+ */
+export class JpegBitReader {
+  private readonly bytes: Uint8Array;
+  private at: number;
+  private buffer = 0;
+  private count = 0;
+
+  constructor(bytes: Uint8Array, start: number) {
+    this.bytes = bytes;
+    this.at = start;
+  }
+
+  /** Where the next unread byte begins — the marker walk resumes the file from here. */
+  get position(): number {
+    return this.at;
+  }
+
+  private nextByte(): number {
+    if (this.at >= this.bytes.length) {
+      throw imageDecodeFailed('the entropy-coded data ends before the scan does (truncated JPEG)', {
+        at: this.at,
+      });
+    }
+    const byte = this.bytes[this.at] ?? 0;
+    this.at += 1;
+    if (byte !== 0xff) return byte;
+    let next = this.bytes[this.at];
+    while (next === 0xff) {
+      this.at += 1; // repeated 0xFF ahead of a marker is fill, and carries no bits
+      next = this.bytes[this.at];
+    }
+    if (next === 0x00) {
+      this.at += 1; // `FF 00` is a stuffed literal 0xFF sample byte
+      return 0xff;
+    }
+    this.at -= 1;
+    throw imageDecodeFailed(
+      next === undefined
+        ? 'the entropy-coded data ends inside a marker (truncated JPEG)'
+        : `marker FF${next.toString(16).toUpperCase().padStart(2, '0')} interrupts the scan ` +
+            'before its last block was decoded',
+      { at: this.at, marker: next ?? null },
+    );
+  }
+
+  readBit(): number {
+    if (this.count === 0) {
+      this.buffer = this.nextByte();
+      this.count = 8;
+    }
+    this.count -= 1;
+    return (this.buffer >> this.count) & 1;
+  }
+
+  receive(length: number): number {
+    let value = 0;
+    for (let i = 0; i < length; i += 1) value = (value << 1) | this.readBit();
+    return value;
+  }
+
+  /** T.81's EXTEND: an `length`-bit magnitude whose top bit is 0 is the negative half of the range. */
+  receiveAndExtend(length: number): number {
+    if (length === 0) return 0;
+    const value = this.receive(length);
+    return value < 1 << (length - 1) ? value - (1 << length) + 1 : value;
+  }
+
+  decode(table: HuffmanTable): number {
+    let code = this.readBit();
+    for (let length = 1; length <= 16; length += 1) {
+      const max = table.maxcode[length] ?? -1;
+      if (max >= 0 && code <= max) {
+        const symbol =
+          table.values[(table.valptr[length] ?? 0) + code - (table.mincode[length] ?? 0)];
+        if (symbol === undefined) {
+          throw imageDecodeFailed(
+            `a ${length}-bit Huffman code resolves outside the symbols its table defines`,
+            { length, code },
+          );
+        }
+        return symbol;
+      }
+      if (length < 16) code = (code << 1) | this.readBit();
+    }
+    throw imageDecodeFailed('no Huffman code of 16 bits or fewer matches the entropy data', {
+      code,
+    });
+  }
+
+  /**
+   * Byte-aligns and swallows one `RSTn` marker, reporting whether it was there. The bit buffer
+   * dies with it: a restart interval exists precisely so a decoder can resynchronise mid-scan.
+   */
+  restart(): boolean {
+    this.count = 0;
+    this.buffer = 0;
+    let at = this.at;
+    while (this.bytes[at] === 0xff && this.bytes[at + 1] === 0xff) at += 1;
+    const marker = this.bytes[at] === 0xff ? this.bytes[at + 1] : undefined;
+    if (marker !== undefined && marker >= 0xd0 && marker <= 0xd7) {
+      this.at = at + 2;
+      return true;
+    }
+    return false;
+  }
+}

package/src/image/jpeg-tables.ts

@@ -0,0 +1,117 @@
+// Single responsibility: the constant tables JPEG's decoder and encoder must agree on —
+// zig-zag order, the Annex K quantisation tables and the Annex K Huffman code lengths.
+// They live here, once, so the two halves of the codec structurally cannot drift apart.
+
+/** Zig-zag index -> natural (row-major) index within an 8x8 block. */
+export const ZIGZAG: readonly number[] = Object.freeze([
+  0, 1, 8, 16, 9, 2, 3, 10, 17, 24, 32, 25, 18, 11, 4, 5, 12, 19, 26, 33, 40, 48, 41, 34, 27, 20,
+  13, 6, 7, 14, 21, 28, 35, 42, 49, 56, 57, 50, 43, 36, 29, 22, 15, 23, 30, 37, 44, 51, 58, 59, 52,
+  45, 38, 31, 39, 46, 53, 60, 61, 54, 47, 55, 62, 63,
+]);
+
+/**
+ * cos(k*PI/16) * sqrt(2) — the scaling an AAN butterfly leaves in its output. The encoder folds it
+ * into the quantiser and the decoder into the dequantiser, so both halves read the same 8 numbers:
+ * a decoder scaled by anything else than the encoder assumed reads every coefficient wrong.
+ */
+export const AAN_SCALE: readonly number[] = Object.freeze([
+  1, 1.387039845, 1.306562965, 1.175875602, 1, 0.785694958, 0.5411961, 0.275899379,
+]);
+
+/** ITU T.81 Annex K.1, luminance, in NATURAL order. */
+export const STD_LUMINANCE_QUANT: readonly number[] = Object.freeze([
+  16, 11, 10, 16, 24, 40, 51, 61, 12, 12, 14, 19, 26, 58, 60, 55, 14, 13, 16, 24, 40, 57, 69, 56,
+  14, 17, 22, 29, 51, 87, 80, 62, 18, 22, 37, 56, 68, 109, 103, 77, 24, 35, 55, 64, 81, 104, 113,
+  92, 49, 64, 78, 87, 103, 121, 120, 101, 72, 92, 95, 98, 112, 100, 103, 99,
+]);
+
+/** ITU T.81 Annex K.1, chrominance, in NATURAL order. */
+export const STD_CHROMINANCE_QUANT: readonly number[] = Object.freeze([
+  17, 18, 24, 47, 99, 99, 99, 99, 18, 21, 26, 66, 99, 99, 99, 99, 24, 26, 56, 99, 99, 99, 99, 99,
+  47, 66, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99,
+  99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99, 99,
+]);
+
+/** Annex K.3 code-length counts (index 0 == codes of length 1) and the symbols they map to. */
+export const STD_DC_LUMINANCE_BITS: readonly number[] = Object.freeze([
+  0, 1, 5, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0,
+]);
+export const STD_DC_LUMINANCE_VALUES: readonly number[] = Object.freeze([
+  0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
+]);
+
+export const STD_DC_CHROMINANCE_BITS: readonly number[] = Object.freeze([
+  0, 3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0,
+]);
+export const STD_DC_CHROMINANCE_VALUES: readonly number[] = Object.freeze([
+  0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
+]);
+
+export const STD_AC_LUMINANCE_BITS: readonly number[] = Object.freeze([
+  0, 2, 1, 3, 3, 2, 4, 3, 5, 5, 4, 4, 0, 0, 1, 0x7d,
+]);
+export const STD_AC_LUMINANCE_VALUES: readonly number[] = Object.freeze([
+  0x01, 0x02, 0x03, 0x00, 0x04, 0x11, 0x05, 0x12, 0x21, 0x31, 0x41, 0x06, 0x13, 0x51, 0x61, 0x07,
+  0x22, 0x71, 0x14, 0x32, 0x81, 0x91, 0xa1, 0x08, 0x23, 0x42, 0xb1, 0xc1, 0x15, 0x52, 0xd1, 0xf0,
+  0x24, 0x33, 0x62, 0x72, 0x82, 0x09, 0x0a, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x25, 0x26, 0x27, 0x28,
+  0x29, 0x2a, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3a, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49,
+  0x4a, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5a, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69,
+  0x6a, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7a, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89,
+  0x8a, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9a, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7,
+  0xa8, 0xa9, 0xaa, 0xb2, 0xb3, 0xb4, 0xb5, 0xb6, 0xb7, 0xb8, 0xb9, 0xba, 0xc2, 0xc3, 0xc4, 0xc5,
+  0xc6, 0xc7, 0xc8, 0xc9, 0xca, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8, 0xd9, 0xda, 0xe1, 0xe2,
+  0xe3, 0xe4, 0xe5, 0xe6, 0xe7, 0xe8, 0xe9, 0xea, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7, 0xf8,
+  0xf9, 0xfa,
+]);
+
+export const STD_AC_CHROMINANCE_BITS: readonly number[] = Object.freeze([
+  0, 2, 1, 2, 4, 4, 3, 4, 7, 5, 4, 4, 0, 1, 2, 0x77,
+]);
+export const STD_AC_CHROMINANCE_VALUES: readonly number[] = Object.freeze([
+  0x00, 0x01, 0x02, 0x03, 0x11, 0x04, 0x05, 0x21, 0x31, 0x06, 0x12, 0x41, 0x51, 0x07, 0x61, 0x71,
+  0x13, 0x22, 0x32, 0x81, 0x08, 0x14, 0x42, 0x91, 0xa1, 0xb1, 0xc1, 0x09, 0x23, 0x33, 0x52, 0xf0,
+  0x15, 0x62, 0x72, 0xd1, 0x0a, 0x16, 0x24, 0x34, 0xe1, 0x25, 0xf1, 0x17, 0x18, 0x19, 0x1a, 0x26,
+  0x27, 0x28, 0x29, 0x2a, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3a, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48,
+  0x49, 0x4a, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5a, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68,
+  0x69, 0x6a, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7a, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87,
+  0x88, 0x89, 0x8a, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9a, 0xa2, 0xa3, 0xa4, 0xa5,
+  0xa6, 0xa7, 0xa8, 0xa9, 0xaa, 0xb2, 0xb3, 0xb4, 0xb5, 0xb6, 0xb7, 0xb8, 0xb9, 0xba, 0xc2, 0xc3,
+  0xc4, 0xc5, 0xc6, 0xc7, 0xc8, 0xc9, 0xca, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8, 0xd9, 0xda,
+  0xe2, 0xe3, 0xe4, 0xe5, 0xe6, 0xe7, 0xe8, 0xe9, 0xea, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7, 0xf8,
+  0xf9, 0xfa,
+]);
+
+export const DEFAULT_JPEG_QUALITY = 80;
+
+/**
+ * Annex K's quality scaling, the same curve libjpeg uses, so a `quality: 80` here is the
+ * `quality: 80` every other tool means. Returns a table in NATURAL order.
+ */
+export function scaleQuantTable(base: readonly number[], quality: number): Uint8Array {
+  const clamped = Math.min(100, Math.max(1, Math.round(quality)));
+  const scale = clamped < 50 ? Math.floor(5000 / clamped) : 200 - clamped * 2;
+  const table = new Uint8Array(64);
+  for (let i = 0; i < 64; i += 1) {
+    const value = Math.floor((((base[i] ?? 1) * scale + 50) / 100) | 0);
+    table[i] = Math.min(255, Math.max(1, value));
+  }
+  return table;
+}
+
+/** BT.601 full-range, the transform every baseline JFIF file is written in. */
+export function rgbToYcbcr(r: number, g: number, b: number): readonly [number, number, number] {
+  return [
+    0.299 * r + 0.587 * g + 0.114 * b,
+    128 - 0.168736 * r - 0.331264 * g + 0.5 * b,
+    128 + 0.5 * r - 0.418688 * g - 0.081312 * b,
+  ];
+}
+
+/** The exact inverse of `rgbToYcbcr`; both halves must round the same way. */
+export function ycbcrToRgb(y: number, cb: number, cr: number): readonly [number, number, number] {
+  return [
+    y + 1.402 * (cr - 128),
+    y - 0.344136 * (cb - 128) - 0.714136 * (cr - 128),
+    y + 1.772 * (cb - 128),
+  ];
+}