@ultimat3/core 1.0.0

package/src/image/fixtures.ts

@@ -0,0 +1,263 @@
+// Single responsibility: byte-exact image fixtures produced by an INDEPENDENT encoder
+// (Pillow 10.2 and ffmpeg), plus the pixels they must decode to. A codec that only
+// round-trips against itself proves nothing — these bytes are the outside reference, so a
+// decoder bug shows up as a pixel mismatch rather than a mutually agreed hallucination.
+
+export interface ImageFixture {
+  /** The encoded file, base64. */
+  readonly base64: string;
+  readonly width: number;
+  readonly height: number;
+  /** Expected RGBA decode, row-major. Omitted for probe-only and lossy fixtures. */
+  readonly pixels?: readonly number[] | undefined;
+}
+
+export const fixtureBytes = (fixture: ImageFixture): Uint8Array =>
+  Uint8Array.from(atob(fixture.base64), (c) => c.charCodeAt(0));
+
+/** Truecolour + alpha (PNG colour type 6), including fully transparent and premature zeros. */
+export const PNG_RGBA_4X4: ImageFixture = {
+  base64:
+    'iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAYAAACp8Z5+AAAAQUlEQVR4nAXBKQGAABAAweU5Po1GE4I4hEBeCpIQ' +
+    'gjjoM8sMgIJIgqC6rNv+3qdN2/VkpoqookREVFUd1/PN0zj84AIej7U060EAAAAASUVORK5CYII=',
+  width: 4,
+  height: 4,
+  pixels: [
+    0, 0, 0, 255, 255, 0, 0, 255, 0, 255, 0, 128, 0, 0, 255, 0, 255, 255, 255, 255, 10, 20, 30, 40,
+    200, 150, 100, 255, 1, 2, 3, 4, 128, 128, 128, 255, 255, 255, 0, 255, 0, 255, 255, 255, 255, 0,
+    255, 255, 5, 5, 5, 5, 250, 250, 250, 250, 60, 120, 180, 240, 9, 8, 7, 6,
+  ],
+};
+
+/** Truecolour, no alpha (colour type 2) — alpha must be synthesised as 255. */
+export const PNG_RGB_3X2: ImageFixture = {
+  base64:
+    'iVBORw0KGgoAAAANSUhEUgAAAAMAAAACCAIAAAASFvFNAAAAF0lEQVR4nGP4z8DAAMFcInInUowYGBgANh8EmGKC' +
+    'N2kAAAAASUVORK5CYII=',
+  width: 3,
+  height: 2,
+  pixels: [
+    255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 10, 20, 30, 255, 200, 100, 50, 255, 0, 0, 0,
+    255,
+  ],
+};
+
+/** Greyscale (colour type 0) — one channel replicated across RGB. */
+export const PNG_GRAY_2X2: ImageFixture = {
+  base64:
+    'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAAAAABX3VL4AAAADklEQVR4nGNgCGVY9R8AA60B/2f7ygkAAAAASUVO' +
+    'RK5CYII=',
+  width: 2,
+  height: 2,
+  pixels: [0, 0, 0, 255, 85, 85, 85, 255, 170, 170, 170, 255, 255, 255, 255, 255],
+};
+
+/** Indexed colour (type 3) with a `tRNS` alpha table — the entry PNG readers forget. */
+export const PNG_PALETTE_4X1: ImageFixture = {
+  base64:
+    'iVBORw0KGgoAAAANSUhEUgAAAAQAAAABCAMAAADO4v//AAADAFBMVEX/AAAA/wAAAP///wAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' +
+    'AAAAAAAAAAAAAAAAAAAAAAAX3fWLAAAABHRSTlP/gAD/oaGUZgAAAA1JREFUeJxjYGBkYgYAAA8AB4SOmW0AAAAA' +
+    'SUVORK5CYII=',
+  width: 4,
+  height: 1,
+  pixels: [255, 0, 0, 255, 0, 255, 0, 128, 0, 0, 255, 0, 255, 255, 0, 255],
+};
+
+/** Greyscale + alpha (colour type 4). */
+export const PNG_GRAY_ALPHA_2X2: ImageFixture = {
+  base64:
+    'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAQAAADYv8WvAAAAEklEQVR4nGNk+N/QyHCC4b8DABPwBAkrfI8bAAAA' +
+    'AElFTkSuQmCC',
+  width: 2,
+  height: 2,
+  pixels: [0, 0, 0, 255, 128, 128, 128, 128, 200, 200, 200, 0, 255, 255, 255, 64],
+};
+
+/** 16 bits per channel — must be reduced to 8 by taking the high byte. */
+export const PNG_GRAY16_2X2: ImageFixture = {
+  base64:
+    'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACEAAAAAAHTY67AAAAEklEQVR4nGNgYHBgYGhg+P8fAAbHAr89RY6RAAAA' +
+    'AElFTkSuQmCC',
+  width: 2,
+  height: 2,
+  pixels: [0, 0, 0, 255, 64, 64, 64, 255, 128, 128, 128, 255, 255, 255, 255, 255],
+};
+
+/** Big enough that Pillow picks a different row filter per scanline — all five must work. */
+export const PNG_GRADIENT_32X24: ImageFixture = {
+  base64:
+    'iVBORw0KGgoAAAANSUhEUgAAACAAAAAYCAIAAAAUMWhjAAAAuklEQVR4nLXSyw6DIBCF4WNrr/aiaNHamL7/W3aB' +
+    'GFDEgQ7JtxjGxR/UDMAppRwFgCydKbBLxAzsU5gFcnbLwIGXM3BktBZg+1E9gTMLf+Dyv83ANdagBkqgCNHPNsTA' +
+    'jaBz7umB+zrpeRoUeCw0rqUlNPA01PbRLSJQAiUg9LAhLlDRRQQEUAGC5hsaqPUNBFB7DWoICjTGK1KBxuVjHqO/' +
+    'wRR42frZhh6Q6wGpvY15xHIDCbRAB7RLPwPnHDcTUr+XAAAAAElFTkSuQmCC',
+  width: 32,
+  height: 24,
+};
+
+/** The exact source of `PNG_GRADIENT_32X24` and the JPEG fixtures, as a formula. */
+export const gradientPixel = (x: number, y: number): readonly [number, number, number] => [
+  (x * 7) % 256,
+  (y * 11) % 256,
+  (x * y) % 256,
+];
+
+/**
+ * A genuine Adam7 interlaced PNG (written by ImageMagick — Pillow's writer silently ignores
+ * `interlace=True`, which is why this one is not generated with the others). The pipeline
+ * refuses it with a coded error rather than garbling it.
+ */
+export const PNG_INTERLACED_8X8: ImageFixture = {
+  base64:
+    'iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAAE8ahlKAAAAS0lEQVQI12NgYGBgqGFQYWQoUalhUGGwYxDaxWDG' +
+    'wlCiwsCgwshgJWTHAEUQMSEIYpRn4ESSsRKCy+DmMDLIcsozYEEQVZyYiHQJAE1EC4Be7arJAAAAAElFTkSuQmCC',
+  width: 8,
+  height: 8,
+};
+
+/** Baseline JPEG, 4:4:4, quality 95 — the closest a lossy codec gets to exact. */
+export const JPEG_444_16X16: ImageFixture = {
+  base64:
+    '/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJ' +
+    'BwYGCAsICQoKCgoKBggLDAsKDAkKCgr/2wBDAQICAgICAgUDAwUKBwYHCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoK' +
+    'CgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgr/wAARCAAQABADAREAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAA' +
+    'AAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAk' +
+    'M2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKT' +
+    'lJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QA' +
+    'HwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdh' +
+    'cRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hp' +
+    'anN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk' +
+    '5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD83/gx+yH/AKr/AIlfp/BRg8Z5h4eeIfwe+fW3wX/ZDz5X/Er9' +
+    'P4K+qweM21P7r8PPEP4PfPpT4L/sh48r/iV+n8FfleDxm2p/hT4eeIfwe+fW3wY/ZD/1X/Er9P4K+qweM8z+6/Dz' +
+    'xD+D3z//2Q==',
+  width: 16,
+  height: 16,
+};
+
+/** Baseline JPEG, 4:2:0 — chroma is half resolution and must be upsampled. */
+export const JPEG_420_16X16: ImageFixture = {
+  base64:
+    '/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYIDAoMDAsKCwsNDhIQDQ4R' +
+    'DgsLEBYQERMUFRUVDA8XGBYUGBIUFRT/2wBDAQMEBAUEBQkFBQkUDQsNFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQU' +
+    'FBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBT/wAARCAAQABADASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAA' +
+    'AAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAk' +
+    'M2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKT' +
+    'lJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QA' +
+    'HwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdh' +
+    'cRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hp' +
+    'anN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk' +
+    '5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD4/wDBfwh/1f7j9K958F/CH/V/uP0r2PwX8If9X+4/SvefBfwh' +
+    '/wBX+4/SjB4zbUPDzxD+D3z/2Q==',
+  width: 16,
+  height: 16,
+};
+
+/** The exact source of the 16x16 JPEG fixtures, as a formula. */
+export const jpegPixel = (x: number, y: number): readonly [number, number, number] => [
+  (x * 16) % 256,
+  (y * 16) % 256,
+  ((x + y) * 8) % 256,
+];
+
+/** Odd dimensions with 4:2:0: the last MCU column and row are padded and must be cropped. */
+export const JPEG_420_ODD_33X17: ImageFixture = {
+  base64:
+    '/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAQDAwMDAgQDAwMEBAQFBgoGBgUFBgwICQcKDgwPDg4MDQ0PERYTDxAV' +
+    'EQ0NExoTFRcYGRkZDxIbHRsYHRYYGRj/2wBDAQQEBAYFBgsGBgsYEA0QGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgY' +
+    'GBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBj/wAARCAARACEDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAA' +
+    'AAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAk' +
+    'M2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKT' +
+    'lJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QA' +
+    'HwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdh' +
+    'cRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hp' +
+    'anN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk' +
+    '5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD5Q0fwT5u39z+ld1pvw/iSISTIqL6nvXp/h3weiW/nSRfKoyeO' +
+    'tdhpvg/di6uot8jcJGBjPsPQf561rgMVg4YSnWrQU5zV9X7sY931d3oktZO6Tvv4XDfG0nJJTPLNO8D2h4hs5JTx' +
+    'g7dqn+v6VR+JHgq2Hgu0AtIUYX6AgkyEfu5OwGRX0dZeEGLhZ4ix2gmJDtRQOef59/5VQ+InhLb4LtDs+UXyZ8v5' +
+    'F/1cnAPU9OlZ0M4w6xkI8kY66+7HTfpZyVutpuS+0lu/1vNuNH/q7ivf+x380fHP/CERf8+8H/fl6K96/wCEIi/5' +
+    '94P+/L0V9J/bf/Til/4Gfz7/AK6f32eh6N/yA3/4D/6EK7LTv+Qlb/8AXIfzNFFfmMP4OE/wUv8A0uofC8M7/f8A' +
+    'kjpNG/5Ab/8AAf8A0IVB8RP+QBp3/XxH/wCgy0UV8/k/8bAf4aX/AKXUP2DOf+Sexv8Ahf6HjNFFFfmh+Hn/2Q==',
+  width: 33,
+  height: 17,
+};
+
+/** The exact source of `JPEG_420_ODD_33X17`, as a formula. */
+export const oddJpegPixel = (x: number, y: number): readonly [number, number, number] => [
+  (x * 9) % 256,
+  (y * 13) % 256,
+  (x * y * 3) % 256,
+];
+
+/** Single-component (greyscale) JPEG. */
+export const JPEG_GRAY_16X16: ImageFixture = {
+  base64:
+    '/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsO' +
+    'CwkJDRENDg8QEBEQCgwSExIQEw8QEBD/wAALCAAQABABAREA/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcI' +
+    'CQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcY' +
+    'GRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKj' +
+    'pKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEBAAA/APzK' +
+    '8P8Ah/8AtXb8mc+1el+H/gt/au3/AETOf9mj4LeH/wC1fI+TOcdq+9fgt8Fv7V8j/RM5x/DX/9k=',
+  width: 16,
+  height: 16,
+};
+
+/** Progressive JPEG — refused with a coded error, never decoded as noise. */
+export const JPEG_PROGRESSIVE_16X16: ImageFixture = {
+  base64:
+    '/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYIDAoMDAsKCwsNDhIQDQ4R' +
+    'DgsLEBYQERMUFRUVDA8XGBYUGBIUFRT/2wBDAQMEBAUEBQkFBQkUDQsNFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQU' +
+    'FBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBT/wgARCAAQABADASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAA' +
+    'Bgf/xAAUAQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIQAxAAAAGPvGTw/8QAFhAAAwAAAAAAAAAAAAAAAAAAAAQF' +
+    '/9oACAEBAAEFAkpAlIEpAlIP/8QAFxEBAAMAAAAAAAAAAAAAAAAABgAhMf/aAAgBAwEBPwE8hy5//8QAFREBAQAA' +
+    'AAAAAAAAAAAAAAAAAwD/2gAIAQIBAT8BFr//xAAWEAADAAAAAAAAAAAAAAAAAAAAASH/2gAIAQEABj8CUFBQUP/E' +
+    'ABQQAQAAAAAAAAAAAAAAAAAAACD/2gAIAQEAAT8hCqq//9oADAMBAAIAAwAAABBT/8QAFBEBAAAAAAAAAAAAAAAA' +
+    'AAAAAP/aAAgBAwEBPxB//8QAFhEAAwAAAAAAAAAAAAAAAAAAACEx/9oACAECAQE/EIM//8QAFRABAQAAAAAAAAAA' +
+    'AAAAAAAAAPH/2gAIAQEAAT8QgoKCgv/Z',
+  width: 16,
+  height: 16,
+};
+
+/** Probe-only: GIF87a/89a header. */
+export const GIF_5X7: ImageFixture = {
+  base64: 'R0lGODdhBQAHAIEAAAAAAAAAAAAAAAAAACwAAAAABQAHAAAIDAABCBxIsKDBgwcDAgA7',
+  width: 5,
+  height: 7,
+};
+
+/** Probe-only: lossy VP8 inside RIFF/WEBP. */
+export const WEBP_9X11: ImageFixture = {
+  base64: 'UklGRiQAAABXRUJQVlA4IBgAAAAwAQCdASoJAAsAAUAmJaQAA3AA/v02aAA=',
+  width: 9,
+  height: 11,
+};
+
+/** Probe-only: AVIF, dimensions read from the `ispe` property box. */
+export const AVIF_12X16: ImageFixture = {
+  base64:
+    'AAAAIGZ0eXBhdmlmAAAAAGF2aWZtaWYxbWlhZk1BMUIAAAD5bWV0YQAAAAAAAAAvaGRscgAAAAAAAAAAcGljdAAA' +
+    'AAAAAAAAAAAAAFBpY3R1cmVIYW5kbGVyAAAAAA5waXRtAAAAAAABAAAAHmlsb2MAAAAARAAAAQABAAAAAQAAASEA' +
+    'AAAiAAAAKGlpbmYAAAAAAAEAAAAaaW5mZQIAAAAAAQAAYXYwMUNvbG9yAAAAAGppcHJwAAAAS2lwY28AAAAUaXNw' +
+    'ZQAAAAAAAAAMAAAAEAAAABBwaXhpAAAAAAMICAgAAAAMYXYxQ4EADAAAAAATY29scm5jbHgAAgACAAIAAAAAF2lw' +
+    'bWEAAAAAAAAAAQABBAECgwQAAAAqbWRhdAoKAAAAAZ35//MAgDIUEADAAAACgAAAAKmObLaqsca2hUA=',
+  width: 12,
+  height: 16,
+};
+
+/** Probe-only: SVG is vector — it has a declared box but no raster to decode. */
+export const SVG_120X45: ImageFixture = {
+  base64:
+    'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMjAiIGhlaWdodD0iNDUiIHZp' +
+    'ZXdCb3g9IjAgMCAxMjAgNDUiPjwvc3ZnPg==',
+  width: 120,
+  height: 45,
+};

package/src/image/jpeg-decode.ts

@@ -0,0 +1,283 @@
+// Single responsibility: turning a baseline or extended sequential Huffman JPEG (SOF0/SOF1) into
+// RGBA — the marker walk, the entropy-coded scan, the inverse DCT and the sample planes. What each
+// segment DECLARES, and which codings are refused by name, is `jpeg-headers.ts`; this file is the
+// algorithm those declarations describe.
+
+import { imageDecodeFailed } from './errors';
+import {
+  assertSupportedCoding,
+  type Component,
+  type Frame,
+  hex,
+  isAdobe,
+  readFrame,
+  readQuantTables,
+  readScanHeader,
+  readU16,
+  type ScanComponent,
+} from './jpeg-headers';
+import { type HuffmanTable, JpegBitReader, readHuffmanTables } from './jpeg-huffman';
+import { ycbcrToRgb, ZIGZAG } from './jpeg-tables';
+import { type Raster, rasterFrom } from './raster';
+
+const SQRT2 = Math.SQRT2;
+
+/** Reused across every block of every image: the decoder is synchronous and single-threaded. */
+const COEF = new Int32Array(64);
+const WORK = new Float32Array(64);
+
+/** libjpeg's AAN float butterfly, in place over the 8 samples `step` apart from `base`. */
+function idct1d(v: Float32Array, base: number, step: number): void {
+  const s0 = v[base] ?? 0;
+  const s1 = v[base + step] ?? 0;
+  const s2 = v[base + step * 2] ?? 0;
+  const s3 = v[base + step * 3] ?? 0;
+  const s4 = v[base + step * 4] ?? 0;
+  const s5 = v[base + step * 5] ?? 0;
+  const s6 = v[base + step * 6] ?? 0;
+  const s7 = v[base + step * 7] ?? 0;
+  const e10 = s0 + s4;
+  const e11 = s0 - s4;
+  const e13 = s2 + s6;
+  const e12 = (s2 - s6) * SQRT2 - e13;
+  const t0 = e10 + e13;
+  const t3 = e10 - e13;
+  const t1 = e11 + e12;
+  const t2 = e11 - e12;
+  const z13 = s5 + s3;
+  const z10 = s5 - s3;
+  const z11 = s1 + s7;
+  const z12 = s1 - s7;
+  const t7 = z11 + z13;
+  const t11 = (z11 - z13) * SQRT2;
+  const z5 = (z10 + z12) * 1.847759065;
+  const t10 = 1.0823922 * z12 - z5;
+  const t12 = -2.61312593 * z10 + z5;
+  const t6 = t12 - t7;
+  const t5 = t11 - t6;
+  const t4 = t10 + t5;
+  v[base] = t0 + t7;
+  v[base + step * 7] = t0 - t7;
+  v[base + step] = t1 + t6;
+  v[base + step * 6] = t1 - t6;
+  v[base + step * 2] = t2 + t5;
+  v[base + step * 5] = t2 - t5;
+  v[base + step * 4] = t3 + t4;
+  v[base + step * 3] = t3 - t4;
+}
+
+/** `Uint8ClampedArray` is the level shift: it rounds and clamps to 0-255 on every store. */
+function writeBlock(comp: Component, at: number, flat: boolean): void {
+  const { samples, stride } = comp;
+  if (flat) {
+    const value = (COEF[0] ?? 0) * (comp.dequant[0] ?? 0) + 128;
+    for (let r = 0; r < 8; r += 1) samples.fill(value, at + r * stride, at + r * stride + 8);
+    return;
+  }
+  for (let i = 0; i < 64; i += 1) WORK[i] = (COEF[i] ?? 0) * (comp.dequant[i] ?? 0);
+  for (let c = 0; c < 8; c += 1) idct1d(WORK, c, 8);
+  for (let r = 0; r < 8; r += 1) idct1d(WORK, r * 8, 1);
+  for (let r = 0; r < 8; r += 1) {
+    const row = at + r * stride;
+    for (let c = 0; c < 8; c += 1) samples[row + c] = (WORK[r * 8 + c] ?? 0) + 128;
+  }
+}
+
+function decodeBlock(reader: JpegBitReader, scan: ScanComponent, row: number, col: number): void {
+  const { comp } = scan;
+  if (row >= comp.blocksPerColumn || col >= comp.blocksPerLine) {
+    throw imageDecodeFailed(`block ${col},${row} falls outside component ${comp.id}`, { row, col });
+  }
+  COEF.fill(0);
+  const size = reader.decode(scan.dc);
+  if (size > 15) {
+    throw imageDecodeFailed(`a DC coefficient claims ${size} magnitude bits, over the 15 allowed`);
+  }
+  comp.pred += reader.receiveAndExtend(size);
+  COEF[0] = comp.pred;
+  let k = 1;
+  let last = 0;
+  while (k < 64) {
+    const rs = reader.decode(scan.ac);
+    const bits = rs & 15;
+    const run = rs >> 4;
+    if (bits === 0) {
+      if (run !== 15) break; // 0x00 is end-of-block; 0xF0 is a run of 16 zeros
+      k += 16;
+      continue;
+    }
+    k += run;
+    if (k > 63) {
+      throw imageDecodeFailed(`an AC run overruns block ${col},${row} of component ${comp.id}`, {
+        row,
+        col,
+      });
+    }
+    COEF[ZIGZAG[k] ?? 0] = reader.receiveAndExtend(bits);
+    last = k;
+    k += 1;
+  }
+  writeBlock(comp, row * 8 * comp.stride + col * 8, last === 0);
+}
+
+/** Leaves the walk at the next marker, or at the end when the file carries no EOI. */
+function skipToMarker(bytes: Uint8Array, from: number): number {
+  for (let at = from; at + 1 < bytes.length; at += 1) {
+    if ((bytes[at] ?? 0) === 0xff && (bytes[at + 1] ?? 0) !== 0x00) return at;
+  }
+  return bytes.length;
+}
+
+/** One scan's entropy-coded data, from the byte after its header to the marker that ends it. */
+function decodeScan(
+  bytes: Uint8Array,
+  start: number,
+  seg: Uint8Array,
+  frame: Frame,
+  quant: ReadonlyArray<Float32Array | undefined>,
+  dcTables: ReadonlyArray<HuffmanTable | undefined>,
+  acTables: ReadonlyArray<HuffmanTable | undefined>,
+  restartInterval: number,
+): number {
+  const scan: readonly ScanComponent[] = readScanHeader(seg, frame, quant, dcTables, acTables);
+  const reader = new JpegBitReader(bytes, start);
+  const single = scan.length === 1 ? scan[0] : undefined;
+  // A non-interleaved scan walks the component's own blocks, which for a subsampled component is
+  // fewer than its MCU-padded plane holds; an interleaved one walks whole MCUs.
+  const perLine =
+    single === undefined
+      ? frame.mcusPerLine
+      : Math.ceil(Math.ceil((frame.width * single.comp.h) / frame.maxH) / 8);
+  const perColumn =
+    single === undefined
+      ? frame.mcusPerColumn
+      : Math.ceil(Math.ceil((frame.height * single.comp.v) / frame.maxV) / 8);
+  for (let n = 0; n < perLine * perColumn; n += 1) {
+    if (restartInterval > 0 && n > 0 && n % restartInterval === 0) {
+      if (!reader.restart()) {
+        throw imageDecodeFailed(`the scan omits the restart marker due after ${n} units`, { n });
+      }
+      for (const entry of scan) entry.comp.pred = 0;
+    }
+    const row = (n / perLine) | 0;
+    const col = n % perLine;
+    if (single !== undefined) {
+      decodeBlock(reader, single, row, col);
+      continue;
+    }
+    for (const entry of scan) {
+      for (let v = 0; v < entry.comp.v; v += 1) {
+        for (let h = 0; h < entry.comp.h; h += 1) {
+          decodeBlock(reader, entry, row * entry.comp.v + v, col * entry.comp.h + h);
+        }
+      }
+    }
+  }
+  return skipToMarker(bytes, reader.position);
+}
+
+/**
+ * Sample planes to RGBA, cropped to the declared size: the MCU-padded edge columns and rows exist
+ * only so the last block is whole, and a decoder that returns them reports the wrong dimensions.
+ * Chroma is upsampled by replication, which is what `h`/`v` below the maxima mean.
+ */
+function toRaster(frame: Frame, adobeTransform: number): Raster {
+  const { width, height, components, maxH, maxV } = frame;
+  const pixels = new Uint8ClampedArray(width * height * 4);
+  const luma = components[0];
+  if (luma === undefined) throw imageDecodeFailed('the frame declares no components');
+  const cb = components[1];
+  const cr = components[2];
+  // Adobe transform 0 over three components means the samples already ARE R, G and B.
+  const alreadyRgb = adobeTransform === 0;
+  for (let y = 0; y < height; y += 1) {
+    const lumaRow = (((y * luma.v) / maxV) | 0) * luma.stride;
+    let out = y * width * 4;
+    if (cb === undefined || cr === undefined) {
+      for (let x = 0; x < width; x += 1) {
+        const grey = luma.samples[lumaRow + (((x * luma.h) / maxH) | 0)] ?? 0;
+        pixels[out] = grey;
+        pixels[out + 1] = grey;
+        pixels[out + 2] = grey;
+        pixels[out + 3] = 255;
+        out += 4;
+      }
+      continue;
+    }
+    const cbRow = (((y * cb.v) / maxV) | 0) * cb.stride;
+    const crRow = (((y * cr.v) / maxV) | 0) * cr.stride;
+    for (let x = 0; x < width; x += 1) {
+      const a = luma.samples[lumaRow + (((x * luma.h) / maxH) | 0)] ?? 0;
+      const b = cb.samples[cbRow + (((x * cb.h) / maxH) | 0)] ?? 0;
+      const c = cr.samples[crRow + (((x * cr.h) / maxH) | 0)] ?? 0;
+      if (alreadyRgb) {
+        pixels[out] = a;
+        pixels[out + 1] = b;
+        pixels[out + 2] = c;
+      } else {
+        const [r, g, blue] = ycbcrToRgb(a, b, c);
+        pixels[out] = r;
+        pixels[out + 1] = g;
+        pixels[out + 2] = blue;
+      }
+      pixels[out + 3] = 255;
+      out += 4;
+    }
+  }
+  return rasterFrom(width, height, pixels);
+}
+
+/** JPEG bytes to RGBA. Baseline and extended sequential only; everything else is named and refused. */
+export function decodeJpeg(bytes: Uint8Array): Raster {
+  if ((bytes[0] ?? 0) !== 0xff || (bytes[1] ?? 0) !== 0xd8) {
+    throw imageDecodeFailed('the bytes do not open with a JPEG SOI marker (FF D8)', {
+      first: `${hex(bytes[0])} ${hex(bytes[1])}`,
+    });
+  }
+  const quant: Array<Float32Array | undefined> = [];
+  const dcTables: Array<HuffmanTable | undefined> = [];
+  const acTables: Array<HuffmanTable | undefined> = [];
+  let frame: Frame | undefined;
+  let restartInterval = 0;
+  let adobeTransform = -1;
+  let offset = 2;
+  while (offset + 1 < bytes.length) {
+    if ((bytes[offset] ?? 0) !== 0xff) {
+      throw imageDecodeFailed(
+        `expected a marker at byte ${offset}, found 0x${hex(bytes[offset])}`,
+        {
+          offset,
+        },
+      );
+    }
+    while (bytes[offset + 1] === 0xff) offset += 1; // fill bytes between segments
+    const marker = bytes[offset + 1];
+    if (marker === undefined) throw imageDecodeFailed('the file ends inside a marker');
+    offset += 2;
+    if (marker === 0xd9) break; // EOI
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue; // no payload
+    assertSupportedCoding(marker);
+    const length = readU16(bytes, offset);
+    if (length < 2 || offset + length > bytes.length) {
+      throw imageDecodeFailed(
+        `segment FF${hex(marker)} declares ${length} bytes but ${bytes.length - offset} remain`,
+        { marker: `FF${hex(marker)}`, length },
+      );
+    }
+    const seg = bytes.subarray(offset + 2, offset + length);
+    offset += length;
+    if (marker === 0xdb) readQuantTables(seg, quant);
+    else if (marker === 0xc4) readHuffmanTables(seg, dcTables, acTables);
+    else if (marker === 0xc0 || marker === 0xc1) frame = readFrame(seg, marker);
+    else if (marker === 0xdd) restartInterval = readU16(seg, 0);
+    else if (marker === 0xee && isAdobe(seg)) adobeTransform = seg[11] ?? adobeTransform;
+    else if (marker === 0xda) {
+      if (frame === undefined) {
+        throw imageDecodeFailed('a scan (SOS) arrives before any frame header (SOF)');
+      }
+      offset = decodeScan(bytes, offset, seg, frame, quant, dcTables, acTables, restartInterval);
+    }
+  }
+  if (frame === undefined) throw imageDecodeFailed('the file carries no frame header (SOF)');
+  return toRaster(frame, adobeTransform);
+}