@woosh/meep-engine 3.9.0 → 3.10.0

package/src/engine/asset/loaders/image/IMAGE_CODEC_REVIEW_2026_08_28.md

@@ -0,0 +1,803 @@
+# Image codecs — duplication and shared-construct review
+
+Review, 2026-08-28. Alex Goldring / Company Named Limited.
+
+Scope: `src/avif/native/`, `src/engine/asset/loaders/image/png/`,
+`src/engine/asset/loaders/image/jpeg/`. Everything below is an itemised proposal; nothing has been
+changed.
+
+Placed here rather than under `src/avif/native/` because the majority of the *cross-tree* items land
+on the loader side, and `src/avif/native/DECISIONS.md` is a decision log rather than a review.
+
+---
+
+## 0. Verdict
+
+Three decoders, written at three different times against three different sets of conventions, doing
+substantially the same job.
+
+**The AVIF tree is the disciplined one.** It already has the abstractions the other two lack —
+a bounds-checked cursor, a container walker, a parameterised colour transform, generated tables, a
+decision log. Its own duplication is residue rather than structure: about **fifteen verbatim
+copy-paste sites**, almost all of them the encode/decode mirror that
+[D30](../../../../avif/native/DECISIONS.md) already set out to eliminate and did not quite finish.
+Cheap to close, and closing it is the difference between a mirror that stays honest and one that
+drifts.
+
+**The cross-tree duplication is the expensive one, and it is not symmetrical.** PNG and JPEG each
+reimplement, badly and privately, things AVIF already has generalised — channel expansion to RGBA,
+YCbCr conversion, chroma upsampling, chunk walking, bounds checking. The single most valuable move
+in this document is not a merge: it is **registering AVIF and JPEG behind the `Codec` interface that
+already exists** ([Codec.js](codec/Codec.js)) so that all three formats reach the engine through one
+door with one result shape. Today PNG goes through a worker, JPEG goes nowhere at all, and AVIF
+bypasses the asset-loader system entirely via `avif_to_sampler2d`.
+
+**One number worth stating up front:** `JpegImage.getData` hard-codes the coefficients `1.402`,
+`-0.3441363`, `-0.71413636`, `1.772`. Those are *exactly* what
+`colour_transform_init(t, MC_BT_601, ·, 1, 8)` computes
+([ColourTransform.js:98](../../../../avif/native/color/ColourTransform.js#L98)). The JPEG decoder is
+a hand-inlined special case of a general transform that already exists two directories away.
+
+To be clear about what that is and is not worth: JFIF is full-range BT.601, so those constants are
+*correct* and JPEG has no need for the other matrices. The win is not new format coverage. It is
+that the derivation `cr_to_r = 2(1 − kr)`, `cb_to_g = −2·kb(1 − kb)/kg`, … is computed once in
+`ColourTransform` and hand-transcribed twice more — as BT.601 literals in `JpegImage`, as BT.709
+literals in `core/color/YCbCr/` — and that adopting the row-based transform is what makes C4
+possible.
+
+**What not to do:** do not merge `ByteCursor` into `BinaryBuffer`, and do not try to fold
+`encode_tile` into `decode_tile`. D10 and D30 already settled both, with reasons that still hold.
+Section 6 says so explicitly so nobody re-litigates them from this document.
+
+Priority ordering is in section 7.
+
+---
+
+## Status
+
+Eleven items were selected and have landed. **File and line references below are as of the review
+date and pre-date those changes** — the proposals for the remaining items still hold, but their
+anchors have moved.
+
+| Item | Commit | Departure from the proposal |
+| --- | --- | --- |
+| D1, D4 | `chore(image): the unreachable halves…` | none |
+| P4 | `refactor(png): the reader keeps one cursor…` | also removed `this.bytes`, assigned and never read |
+| J2, J4 | `refactor(jpeg): frame components become a Map…` | none |
+| C7 | `refactor(binary): crc32 moves to core…` | none |
+| C8 | `refactor(binary): one UTF-8 codec…` | three functions, not two: splitting `utf8_encoded_length` off is what lets `BoxWriter` grow once and encode straight into the buffer |
+| A10 | `refactor(avif): the small numeric helpers…` | six inline `clz32` sites, not seven — see the correction in A10 |
+| P2 | `refactor(png): one inflate path…` | no deprecation shim; the export changes name, arity and return type |
+| P3 | `fix(png): bit depths of 1, 2 and 4 decode correctly…` | the suspected bug was real, and worse than described — see P3 |
+| C4 | `refactor(jpeg): one row sampler…` | **`upsample_chroma_row` is not reusable here** — see the correction in C4 |
+
+Not taken this round: C1, C2, C3, C5, C6, A1–A9, A11, A12, D2, D3, D5, D6, P1, P5, P6, J1, J3.
+D5 and D6 came along with P4 and J2 respectively.
+
+---
+
+## 1. Cross-package items
+
+These are the ones where a construct exists in one tree and is re-invented in another.
+
+### C1 — One `Codec` door for all three formats *(highest value)*
+
+**Today.** Three formats, three unrelated entry conventions, three result shapes:
+
+| Format | Entry point | Result shape |
+| --- | --- | --- |
+| PNG | worker → [ImageDecoderWorker.js:3](ImageDecoderWorker.js#L3) → `PNGReader` | `{data, width, height, itemSize, bitDepth}` |
+| JPEG | [jpeg_decode.js:9](jpeg/jpeg_decode.js#L9) — **not reachable from any loader** | `{data, width, height, exifBuffer, comments?}` — no `itemSize`, no `bitDepth`, always 3-channel |
+| AVIF | [avif_to_sampler2d.js:26](../../../../avif/native/api/avif_to_sampler2d.js#L26) — bypasses the loader entirely, called direct from `deserialize_scene` | `{data, width, height}` — no `itemSize`, no `bitDepth`, always RGBA |
+
+`ImageDecoderWorker.decode` has a `switch (type)` with exactly one arm and a `default: throw new
+Error('Unsupported type')`. `ThreadedImageDecoder.test` sniffs `PNG_HEADER_BYTES` and returns `false`
+for everything else, so a JPEG or AVIF asset silently falls through to `NativeImageDecoder` — the
+browser canvas path — which is why the native JPEG decoder has never needed to work.
+
+**Proposal.**
+
+1. Define one result struct, `DecodedImage {data, width, height, itemSize, bitDepth, ...}`, next to
+   `Codec.js`. Fill it in from all three decoders. `exifBuffer` and `comments` become optional
+   fields rather than a shape difference.
+2. Add `PngCodec`, `JpegCodec`, `AvifCodec`, each a `Codec` subclass whose `test(data)` is a magic
+   sniff and whose `decode(data)` returns a `DecodedImage`. The sniffs already exist in three places
+   in three styles — `PNG_HEADER_BYTES` as an exported array, `0xFFD8` inline at
+   [JpegImage.js:139](jpeg/JpegImage.js#L139), and `ftyp`/`meta` presence at
+   [parse_avif_file.js:51](../../../../avif/native/heif/parse_avif_file.js#L51). Give each format a
+   `*_HEADER_BYTES` (or a `test` predicate) beside its decoder and have the codec use it.
+3. `CodecWithFallback` ([CodecWithFallback.js:11](codec/CodecWithFallback.js#L11)) already does
+   ordered try-with-sniff correctly. Compose `[Threaded(PNG), Jpeg, Avif, Native]` and the format
+   switch disappears from `ImageRGBADataLoader` and from `ImageDecoderWorker`.
+4. `avif_to_sampler2d` stays — it is the HDR-aware adapter and the exact inverse of
+   `sampler2d_to_avif` (D32) — but it becomes a thin wrapper over `AvifCodec` rather than a second
+   independent path into the decoder.
+
+**Payoff.** JPEG becomes reachable. AVIF becomes loadable as an asset. The worker learns a second
+format for free. One place decides what "a decoded image" is.
+
+**Risk.** Low. `CodecWithFallback` and `Codec` already exist and are spec-covered; this is
+population, not new machinery.
+
+---
+
+### C2 — Channel expansion to RGBA is written four times
+
+Same job — take interleaved samples with `itemSize` channels and produce RGBA — in four places:
+
+- [PNG.js:303](png/PNG.js#L303) `getRGBA8Array` + `getRGBA8Array_fromRGB` +
+  `getRGBA8Array_generic` + `getPixel` — **all four dead**, see D1 below
+- [PNG.js:325](png/PNG.js#L325) `getUint8Data_case3`, palette expansion with the `tRNS` alpha rule
+- [JpegImage.js:561](jpeg/JpegImage.js#L561) `copyToImageData`, one loop per component count with
+  `formatAsRGBA` deciding whether to emit the fourth channel
+- [sampler2d_to_avif.js:68](../../../../avif/native/api/sampler2d_to_avif.js#L68) `to_rgba`, the
+  cleanest of the four and the only one that handles half-float input
+
+And the engine already has a fifth: [sampler2d_to_uint8_RGBA.js](../../../graphics/texture/sampler/sampler2d_to_uint8_RGBA.js),
+wrapped by `sampler2d_ensure_uint8_RGBA`.
+
+**Proposal.** One free function in `core/` or beside `Codec.js`:
+
+```js
+expand_to_rgba(source, item_size, count, destination, opaque_value)
+```
+
+with the three input families (`Uint8`, `Uint16` half-float, `Float32`) selected by the caller, not
+sniffed. `to_rgba`'s structure is the right one to generalise from: it is the only one that already
+handles `item_size < 3` by zero-filling and `item_size < 4` by writing opaque.
+
+Palette expansion (`getUint8Data_case3`) stays PNG-specific — a palette lookup is not a channel
+expansion — but it should call the shared function for the final write rather than open-coding the
+`destination_address + 0..3` stores.
+
+**Payoff.** Removes ~120 lines of dead code plus ~150 lines of live duplication, and makes the
+"what fills alpha when the source has none" rule a single decision instead of four (today: `255`,
+`255`, `255`, and `1` for float — all correct, but nothing says so in one place).
+
+---
+
+### C3 — YCbCr → RGB exists three times, with three different capability levels
+
+| Where | Matrix | Range | Depth | Parameterised? |
+| --- | --- | --- | --- | --- |
+| [ycbcr_row_to_rgb.js:24](../../../../avif/native/color/ycbcr_row_to_rgb.js#L24) | any `MC_*`, plus identity and YCgCo | full or limited | 8/10/12 | yes, via `ColourTransform` |
+| [JpegImage.js:491](jpeg/JpegImage.js#L491) | BT.601 only, hard-coded | full only | 8 only | no |
+| [YCbCr_to_rgb_uint24.js](../../../../core/color/YCbCr/YCbCr_to_rgb_uint24.js) | BT.709 only, hard-coded | full only | 8 only | no |
+
+The JPEG constants are not "close to" BT.601 — they *are* `colour_transform_init` with
+`MC_BT_601`, `color_range = 1`, `bit_depth = 8`. `cr_to_r = 2(1 − 0.299) = 1.402`,
+`cb_to_b = 2(1 − 0.114) = 1.772`, `cb_to_g = −2·0.114·0.886/0.587 = −0.3441363`,
+`cr_to_g = −2·0.299·0.701/0.587 = −0.71413636`. Digit for digit.
+
+The same holds for YCgCo. `rgb_row_to_ycbcr`'s `CONVERSION_YCGCO` branch
+([rgb_row_to_ycbcr.js:40](../../../../avif/native/color/rgb_row_to_ycbcr.js#L40)) computes
+`0.25r + 0.5g + 0.25b`, `−0.25r + 0.5g − 0.25b`, `0.5r − 0.5b` — which is
+[rgb_to_ycocg.js](../../../../core/color/YCoCg/rgb_to_ycocg.js) verbatim, with Cg and Co swapped in
+the output order. Its inverse likewise reproduces `ycocg_to_rgb`.
+
+**Proposal.** Promote `ColourTransform` + `colour_transform_init` + the two row functions out of
+`src/avif/native/color/` into `src/core/color/`. They have no AV1 dependency beyond the `MC_*` /
+`CP_*` symbol constants, which should move with them (they are CICP codes from ITU-T H.273, not AV1
+inventions — the AVIF tree just happens to be where they were first needed).
+
+Then:
+
+- `JpegImage.getData` builds a `ColourTransform` once per image from `adobe.transformCode` /
+  component count and calls `ycbcr_row_to_rgb` per row. The arithmetic is unchanged — JFIF is
+  full-range BT.601 and that is exactly what `MC_BT_601` with `color_range = 1` produces — so this
+  is deduplication, not a behaviour change. What it buys is the row-based shape that C4 needs, and
+  one fewer transcription of the coefficients.
+- `YCbCr_to_rgb_uint24` / `rgb_to_YCbCr_uint24` keep their packed-uint24 signature but derive their
+  coefficients from a module-level `ColourTransform` initialised with `MC_BT_709`, so the constants
+  stop being transcribed.
+- The `CONVERSION_YCGCO` branches delegate to `rgb_to_ycocg` / `ycocg_to_rgb`.
+
+**Risk.** Medium. This moves live colour code. `color.spec.js` and the AVIF fixture round-trips cover
+the AVIF side; the JPEG side is a bit-exactness question — the current code computes in `number` with
+those literals, the shared path computes the same coefficients from `kr`/`kb`, and the two can differ
+in the last ulp before rounding. Extend `jpeg_decode.spec.js` with a per-pixel comparison against the
+current output (tolerance 0, then 1) before it lands. The JPEG path is currently unreachable (C1), so
+the exposure while that is settled is nil.
+
+---
+
+### C4 — Chroma upsampling is written twice, one of them by accident
+
+[upsample_chroma_row.js:36](../../../../avif/native/color/upsample_chroma_row.js#L36) has nearest and
+bilinear modes, edge clamping, and honours `subsampling_x` / `subsampling_y` independently.
+
+`JpegImage.getData` does the same thing implicitly, in every one of its four `switch` arms: the
+expression `0 | (· * componentN.scale· · ·)` appears **27 times** in that one function (17 on the
+column axis, 10 on the row axis). That is
+nearest-neighbour upsampling combined with output rescaling, inlined per component per arm. It is
+also why JPEG 4:2:0 chroma is visibly blockier than AVIF 4:2:0 chroma at the same subsampling.
+
+**Proposal.** Have the JPEG component loop upsample each component to a full-width row, then run
+one interleave loop instead of four near-identical ones. `getData`'s four cases collapse to: build
+N full-width rows, then one component-count-dependent combine.
+
+**Correction, from doing it.** The row sampler could *not* be `upsample_chroma_row`.
+`upsample_chroma_row` expresses subsampling as a shift — `sub_x` and `sub_y` are 0 or 1 — so it can
+say "half" and not "a third", while JPEG's `h` and `v` sampling factors run from one to four and
+`getData` also rescales to an arbitrary requested output size. Generalising it to rational scaling
+would have changed the AVIF decoder's per-row path for no AVIF benefit. The sampler lives in
+`jpeg/jpeg_component_row.js` instead, with that reasoning on it, and stays nearest-neighbour: the
+four arms were nearest-neighbour, and interpolating would change every decoded picture.
+
+So the shared-with-AVIF half of this item is withdrawn. The deduplication half stands and was worth
+it on its own.
+
+**Payoff, realised.** `getData` drops from ~140 lines to ~55 across three functions, the twenty-seven
+sampling expressions become one, and the colour-transform decision — spelt out twice with a
+different default each time — becomes one method. Verified byte-for-byte against the previous
+implementation over 300+ combinations of sampling ratio, output size, component count, Adobe marker
+and option state.
+
+---
+
+### C5 — A container walker for length-prefixed records
+
+The AVIF tree has this construct twice, correctly, in two variants:
+
+- [for_each_box.js:24](../../../../avif/native/isobmff/for_each_box.js#L24) — reusable header
+  instance, visitor returns `false` to stop, cursor repositioned to the next record regardless of how
+  much the visitor consumed
+- [for_each_obu.js:25](../../../../avif/native/av1/obu/for_each_obu.js#L25) — same contract, two
+  reusable readers
+
+PNG has the same construct, open-coded and split across two methods:
+[PNGReader.decodeChunk:151](png/PNGReader.js#L151) reads `length / type / payload / crc` and then
+`switch`es on type in the same function, and [PNGReader.parse:654](png/PNGReader.js#L654) is the
+`for(;;)` that drives it and detects `IEND`. JPEG has it as a 200-line `switch` inside
+`JpegImage.parse` with `offset` mutated by nested closures.
+
+**Proposal.** Two separable pieces, and the second matters more than the first:
+
+1. `for_each_png_chunk(cursor, visit)` in the PNG folder, mirroring `for_each_box`'s contract
+   exactly — reusable `PngChunkHeader {type, offset, payload_offset, payload_size, crc}`, visitor
+   returns `false` to stop. `decodeChunk` becomes a visitor with a `switch` and nothing else; the
+   CRC check moves into the walker where it belongs.
+2. **Separate parsing from dispatch in JPEG.** `JpegImage.parse` currently reads the segment,
+   interprets it, and mutates decoder state in one 250-line function with four closures
+   (`readUint16`, `readDataBlock`, `prepareComponents`) capturing `offset`. Split it into
+   `for_each_jpeg_segment(data, visit)` plus one handler per marker family. The malformed-APP1
+   recovery ([JpegImage.js:368](jpeg/JpegImage.js#L368)) and the eaten-`0xFF` recovery belong to the
+   walker, not to the `default:` arm of a dispatch switch.
+
+I am **not** proposing one generic TLV walker across all three formats. The record headers differ
+too much (ISOBMFF has three size encodings and a `uuid` case; PNG has a trailing CRC; JPEG has
+stuffed bytes and standalone markers). What should be shared is the *contract* — reusable header
+struct, visitor returns `false`, walker guarantees forward progress — so that the three read alike.
+
+---
+
+### C6 — Bounds checking exists on one side of the fence only
+
+`ByteCursor.require(count, what)` ([ByteCursor.js:96](../../../../avif/native/isobmff/ByteCursor.js#L96))
+validates every read and names the field in the error. `BitReader` does the same for every
+descriptor. There is a `robustness.spec.js` that feeds the decoder truncated and hostile files.
+
+PNG reads through two unchecked private helpers
+([PNGReader.js:28](png/PNGReader.js#L28), [PNGReader.js:42](png/PNGReader.js#L42)):
+
+```js
+function readUInt32(buffer, offset) {
+    return (buffer[offset] << 24) | (buffer[offset+1] << 16) | (buffer[offset+2] << 8) | buffer[offset+3];
+}
+```
+
+Past the end this yields `NaN`-free garbage — `undefined << 24` is `0` — so a truncated `IHDR`
+produces a plausible width and height rather than an error. JPEG reads `data[offset++]` throughout
+with no checks at all.
+
+Both of those helpers are also **already redundant with the `BinaryBuffer` the same constructor
+built**: `PNGReader` creates `this.buffer` with `endianness = BigEndian`
+([PNGReader.js:83](png/PNGReader.js#L83)) and then reads chunk payloads with the unchecked free
+functions anyway. `buffer.readUint32()` / `readUint8()` were there the whole time.
+
+**Proposal.** Delete `readUInt32` and `readUInt8` from `PNGReader.js`; read chunk payloads through a
+`BinaryBuffer` positioned on the chunk (or through the `for_each_png_chunk` header from C5). Add a
+`robustness.spec.js` to the PNG and JPEG folders modelled on the AVIF one — truncated header,
+truncated chunk, chunk length exceeding the file, garbage after `IEND`.
+
+**Payoff.** Removes two functions and closes the class of failure where a malformed image decodes to
+a plausible-looking wrong picture instead of throwing.
+
+---
+
+### C7 — `crc32` is a general utility living in the PNG folder
+
+[crc32.js](png/crc32.js) is a complete, spec-cited, tested CRC-32/ISO-3309 implementation with an
+`(buffer, offset, length)` signature. It sits under `png/` and is imported by exactly one file.
+
+Meanwhile [unpack_usdz.js:66](../../../../shade/renderer/loader/usd/unpack_usdz.js#L66) reads ZIP
+local file headers and *skips* the CRC field with a comment, because verifying it would mean writing
+this function again.
+
+**Proposal.** Move to `src/core/binary/hash/crc32.js`, beside `xxh3_64` and `xxh3_128`. Re-export
+from `png/crc32.js` for one release if any external consumer matters, otherwise just move it and fix
+the two imports.
+
+Also worth noting while it moves: `PNGReader.crc_enabled` defaults to `false`
+([PNGReader.js:91](png/PNGReader.js#L91)) and, when enabled, `console.warn`s rather than throwing.
+That is a defensible choice for a game engine — but it is an undocumented one, and the AVIF tree
+records choices like this in `DECISIONS.md`. Give the PNG folder the same treatment.
+
+---
+
+### C8 — NUL-terminated UTF-8, encoded and decoded privately in two places
+
+[ByteCursor.js:307](../../../../avif/native/isobmff/ByteCursor.js#L307) has a private `utf8_decode`
+with the stated reason that `TextDecoder` is not universally available.
+[BoxWriter.js:205](../../../../avif/native/isobmff/BoxWriter.js#L205) has the matching encoder inline
+in `utf8_string`. `BinaryBuffer` has `readUTF8String` / `writeUTF8String` but they are
+**length-prefixed** (meep's own serialisation format) and therefore genuinely unusable here — this
+is a real gap, not a missed reuse.
+
+**Proposal.** One pair of free functions in `core/binary/`:
+
+```js
+utf8_decode_range(bytes, start, end)   // → string
+utf8_encode_into(text, buffer)         // → bytes written
+```
+
+`ByteCursor.utf8_string` and `BoxWriter.utf8_string` become three-line wrappers that add the
+NUL handling. Optionally give `BinaryBuffer` `readUTF8StringNullTerminated` /
+`writeUTF8StringNullTerminated` built on the same pair, which would let a future ISOBMFF-adjacent
+reader use it directly.
+
+This does **not** conflict with D10: it shares the character codec, not the cursor.
+
+---
+
+## 2. Inside `src/avif/native/` — finishing D30
+
+D30 says derived state is shared and traversal is mirrored. That is the right rule. These are the
+places where derived state is still written twice, and they are the residue D30 was aiming at.
+
+### A1 — Tile geometry derivation, 18 identical lines
+
+[parse_frame_header.js:250–267](../../../../avif/native/av1/obu/parse_frame_header.js#L250) and
+[write_frame_header.js:162–179](../../../../avif/native/av1/obu/write_frame_header.js#L162) open with
+the same eighteen lines: `sb_shift`, `sb_size`, `sb_cols`, `sb_rows`, `max_tile_width_sb`,
+`max_tile_area_sb`, `min_log2_tile_cols`, `max_log2_tile_cols`, `max_log2_tile_rows`,
+`min_log2_tiles`. Character for character, `let` versus `const` on `max_tile_area_sb` aside.
+
+**Proposal.** `derive_tile_limits(sequence, header, out)` in a shared module (`av1/obu/tile_limits.js`
+or extending the existing `av1/util/`), filling a small struct or an `Int32Array`. Both call it. This
+is the highest-consequence one in this section: these ten values decide how many `f(1)` bits the
+uniform-spacing loop reads and writes, so a divergence here is a bitstream desync, not a wrong pixel.
+
+### A2 — CDF adaptation, 24 identical lines in reader and writer
+
+[SymbolReader.js:178–202](../../../../avif/native/av1/entropy/SymbolReader.js#L178) and
+[SymbolWriter.js:216–240](../../../../avif/native/av1/entropy/SymbolWriter.js#L216) are the same
+block verbatim: the `rate` computation, the `tmp` sweep, the count saturation at 32.
+
+**Proposal.** `cdf_adapt(cdf, offset, n, symbol)` beside `symbol_cost.js`. Both call it. The
+adaptation rate is normative and shared by construction; there is no reason for two copies.
+
+While there: the interval boundary
+`((range_high * (f >> EC_PROB_SHIFT)) >> (7 - EC_PROB_SHIFT)) + EC_MIN_PROB * (n - symbol - 1)`
+appears once in the reader and twice in the writer
+([SymbolWriter.js:200](../../../../avif/native/av1/entropy/SymbolWriter.js#L200) and
+[:206](../../../../avif/native/av1/entropy/SymbolWriter.js#L206)). A `symbol_boundary(range_high,
+cdf, offset, n, symbol)` helper covers all three; it is on the per-symbol path, so measure before
+committing, but it is a pure function of five numbers and should inline.
+
+### A3 — `clear_above_context` / `clear_left_context`, byte-identical
+
+[decode_tile.js:115](../../../../avif/native/av1/decode/decode_tile.js#L115) and
+[:125](../../../../avif/native/av1/decode/decode_tile.js#L125); the same two functions verbatim at
+[encode_tile.js:277](../../../../avif/native/av1/encode/encode_tile.js#L277) and
+[:287](../../../../avif/native/av1/encode/encode_tile.js#L287).
+
+**Proposal.** Move both onto `Av1FrameContext` as methods, or export them from
+`av1/entropy/coefficient_context.js` — which is already the shared home for exactly this kind of
+context state. Twelve lines, zero risk.
+
+### A4 — `dc_delta` / `ac_delta`, byte-identical
+
+[reconstruct.js:222](../../../../avif/native/av1/decode/reconstruct.js#L222) and
+[:235](../../../../avif/native/av1/decode/reconstruct.js#L235); identical copies at
+[quantise.js:193](../../../../avif/native/av1/encode/quantise.js#L193) and
+[:206](../../../../avif/native/av1/encode/quantise.js#L206). `reconstruct.js` already exports
+`dc_quant`, `ac_quant` and `get_qindex` and `quantise.js` already imports from it — these two just
+never made the trip.
+
+**Proposal.** Export them from `reconstruct.js` alongside their siblings. Delete the copies.
+
+### A5 — `BINARY_PARTITION_CDF` construction
+
+[decode_tile.js:273](../../../../avif/native/av1/decode/decode_tile.js#L273) and
+[encode_tile.js:838](../../../../avif/native/av1/encode/encode_tile.js#L838) each declare a
+three-element scratch and each fill it with `(1<<15) - psum, 1<<15, 0`, each save and restore
+`disable_cdf_update` around the call. The decoder explains in a comment why the adaptation is
+skipped (the spec rebuilds this CDF from scratch every time, so any update is discarded); the
+encoder does the same thing with no explanation, which is the half of the pair that will get
+"simplified" by someone who does not know.
+
+**Proposal.** `build_binary_partition_cdf(psum, out)` in
+[partition_cdf.js](../../../../avif/native/av1/entropy/partition_cdf.js), which is already the shared
+module for partition CDF selection. The scratch array stays per-module (correctly — it prevents
+reentrancy coupling), only the fill and the save/restore discipline move.
+
+### A6 — `plane_residual_size`, one expression in seven places
+
+`SUBSAMPLED_SIZE[(size * 2 + sub_x) * 2 + sub_y]` appears at:
+
+- [decode_tile.js:572](../../../../avif/native/av1/decode/decode_tile.js#L572) (as a named function)
+- [encode_tile.js:525](../../../../avif/native/av1/encode/encode_tile.js#L525),
+  [:1728](../../../../avif/native/av1/encode/encode_tile.js#L1728),
+  [:2088](../../../../avif/native/av1/encode/encode_tile.js#L2088),
+  [:2179](../../../../avif/native/av1/encode/encode_tile.js#L2179) (four times, inline)
+- [coefficient_context.js:50](../../../../avif/native/av1/entropy/coefficient_context.js#L50)
+- [loop_filter.js:110](../../../../avif/native/av1/filter/loop_filter.js#L110)
+
+**Proposal.** Export `plane_residual_size(mi_size, sub_x, sub_y)` from
+[derived_block_tables.js](../../../../avif/native/av1/tables/derived_block_tables.js) — which already
+exists for precisely this purpose ("Deriving beats transcribing: the two can never drift apart") —
+and use it in all seven sites.
+
+**And flag while you are there:** the decoder's `get_tx_size`
+([decode_tile.js:963](../../../../avif/native/av1/decode/decode_tile.js#L963)) clamps a chroma
+transform of 64 down to 32/16x32/32x16; the encoder's `transform_size`
+([encode_tile.js:2167](../../../../avif/native/av1/encode/encode_tile.js#L2167)) does not, and adds a
+`lossless → TX_4X4` case the decoder handles elsewhere. They may both be correct given the encoder's
+narrow syntax (D30: blocks 8x8 to 32x32, so 64 is unreachable) — but that is an invariant holding by
+accident across two files, which is exactly the shape of bug D30 exists to prevent. Either share the
+function with the encoder's extra cases guarded, or leave a comment on both stating the invariant.
+
+### A7 — Losslessness derived twice, and the two do not agree
+
+[parse_frame_header.js:527](../../../../avif/native/av1/obu/parse_frame_header.js#L527)
+`compute_losslessness` walks all `MAX_SEGMENTS`, checks all five quantiser deltas, fills
+`lossless_array` and `seg_qm_level`, and derives `all_lossless` from `frame_width ===
+upscaled_width`.
+
+[build_headers.js:236](../../../../avif/native/av1/encode/build_headers.js#L236) does:
+
+```js
+const lossless = frame.base_q_idx === 0;
+frame.coded_lossless = lossless ? 1 : 0;
+frame.all_lossless = frame.coded_lossless;
+frame.lossless_array.fill(lossless ? 1 : 0);
+```
+
+Correct *today*, because the encoder emits no segmentation and no non-zero deltas (D30). It stops
+being correct the moment either is added — and `seg_qm_level` is never populated on the encode side
+at all, which matters if `using_qmatrix` is ever turned on.
+
+**Proposal.** Export `compute_losslessness` and have `build_headers` call it after setting
+`base_q_idx` and the deltas. The encoder's assumptions then become inputs to the shared derivation
+rather than a parallel implementation of it.
+
+### A8 — Shared constants declared twice
+
+| Constant | Sites |
+| --- | --- |
+| `ALPHA_AUX_TYPE` | [decode_avif.js:15](../../../../avif/native/api/decode_avif.js#L15), [encode_avif.js:41](../../../../avif/native/api/encode_avif.js#L41) |
+| `QM_TOTAL_SIZE` | [av1_symbols.js:261](../../../../avif/native/av1/tables/av1_symbols.js#L261) (exported) and [reconstruct.js:33](../../../../avif/native/av1/decode/reconstruct.js#L33) (local copy of the same `3344`) |
+| `HLG_A/B/C` | [transfer_to_linear.js:50](../../../../avif/native/color/transfer_to_linear.js#L50), [linear_to_transfer.js:18](../../../../avif/native/color/linear_to_transfer.js#L18) |
+
+**Proposal.** `ALPHA_AUX_TYPE` → a shared `heif/aux_types.js` (there will be others: depth, gain
+map). `QM_TOTAL_SIZE` → delete the local copy, import the exported one. `HLG_A/B/C` → a small
+`color/hlg_constants.js`, or better, a `core/color/HLG/` module beside the existing `core/color/PQ/`
+— the two curves are peers and only one of them has a home today.
+
+### A9 — `MAX_TX_DEPTH` is two different exported symbols
+
+[av1_symbols.js:176](../../../../avif/native/av1/tables/av1_symbols.js#L176) exports
+`MAX_TX_DEPTH = 2` (a scalar bound).
+[block_tables.js:12](../../../../avif/native/av1/tables/block_tables.js#L12) exports
+`MAX_TX_DEPTH = new Uint8Array([...])` (a 22-entry table).
+
+`decode_tile.js` imports the table under the alias `MAX_TX_DEPTH_TABLE`; `encode_tile.js` imports it
+unaliased. Nothing currently imports both into one module, so nothing is broken — but the next file
+that needs both gets a shadowing bug that will look like a table lookup returning a number.
+
+**Proposal.** Rename the generated table to `MAX_TX_DEPTH_BY_BLOCK` in the generator's naming rule
+(D22 — the generator is out of tree, so this is a rename in `block_tables.js` plus a note in
+`DECISIONS.md` recording the deviation from the spec's name), or rename the scalar to
+`MAX_TX_DEPTH_LIMIT`. Either way, not both.
+
+### A10 — `clamp_unit`, `clamp_index`, and friends against `core/math`
+
+- `clamp_unit` is duplicated at
+  [convert_to_rgba.js:217](../../../../avif/native/api/convert_to_rgba.js#L217) and
+  [ycbcr_row_to_rgb.js:83](../../../../avif/native/color/ycbcr_row_to_rgb.js#L83) — and is
+  byte-for-byte [core/math/clamp01.js](../../../../core/math/clamp01.js), which `loop_restoration.js`
+  already knows how to import from (it uses `core/math/clamp.js`).
+- `clamp_index` is duplicated at
+  [choose_restoration.js:622](../../../../avif/native/av1/encode/choose_restoration.js#L622) and
+  [upsample_chroma_row.js:94](../../../../avif/native/color/upsample_chroma_row.js#L94) — same body,
+  different parameter names.
+- [floor_log2.js:15](../../../../avif/native/av1/util/floor_log2.js#L15) is `31 - Math.clz32(x)`,
+  which is [core/binary/msb_32.js](../../../../core/binary/msb_32.js) exactly. And it is
+  *re-inlined* six more times in `SymbolReader`/`SymbolWriter` rather than called. (Six, not seven:
+  `SymbolWriter.#normalize`'s `32 - Math.clz32(range)` is a bit *length*, libaom's `OD_ILOG_NZ`,
+  not a floor log. It computes the same shift as the reader's `15 - floor_log2(x)` and is
+  deliberately left alone — rewriting it would break the correspondence with the source it was
+  transliterated from.)
+- [convert_to_rgba.js:199](../../../../avif/native/api/convert_to_rgba.js#L199) `quantise` and
+  [encode_avif.js:415](../../../../avif/native/api/encode_avif.js#L415) `clamp_sample` are the same
+  "round then clamp to `0..maximum`", differing only in whether the scale-up happens inside.
+
+**Proposal.** Import `clamp01` for `clamp_unit`. Extract one `clamp_index(index, extent)` beside
+`clamp01`. Make `floor_log2` an alias — `export const floor_log2 = msb_32;` with the AV1 spec
+docstring retained, since the spec-named alias is genuinely useful — and replace the six inline
+`31 - Math.clz32(...)` sites with calls. Unify `quantise` / `clamp_sample` into one function.
+
+**Note on the entropy coder.** `SymbolReader` says of itself that it is the hottest code in the
+decoder, and it bypasses `BitReader` for that reason, so replacing an inline expression with a call
+there needs evidence rather than taste. Three runs of the AVIF suite before and after: 13.77s,
+15.19s, 12.74s against 13.03s, 12.91s, 12.77s. No regression, so the change stands; had there been
+one, the inline forms should have kept a comment naming them instead.
+
+The landed shape put `clamp_sample(value, maximum)` — round then clamp — in `avif/native/color/`,
+with `convert_to_rgba` keeping `quantise` as a one-line normalised wrapper over it, so the inner
+loop reads as it did.
+
+The `w`/`m` derivation for `ns(n)` is a fourth instance of the same theme: it appears at
+[BitReader.js:216](../../../../avif/native/bitstream/BitReader.js#L216),
+`BitWriter.ns`, [SymbolReader.js:286](../../../../avif/native/av1/entropy/SymbolReader.js#L286) and
+[SymbolWriter.js:283](../../../../avif/native/av1/entropy/SymbolWriter.js#L283). The two symbol-coder
+copies use the inline `clz32` form rather than calling `floor_log2`, which is how they drifted apart
+in style in the first place.
+
+### A11 — Name collisions across unrelated modules
+
+Not duplication, but the same trap as A9 and worth one pass:
+
+- `filter_edge` — [loop_filter.js](../../../../avif/native/av1/filter/loop_filter.js) (a deblocking
+  edge) and [predict_intra.js](../../../../avif/native/av1/predict/predict_intra.js) (an intra edge
+  smoothing kernel). Unrelated jobs, identical name.
+- `restore_block` — [loop_restoration.js](../../../../avif/native/av1/filter/loop_restoration.js)
+  (Wiener/SGR restoration) and
+  [Av1BlockSnapshot.js](../../../../avif/native/av1/encode/Av1BlockSnapshot.js) (undo an encoder
+  trial). Opposite meanings of "restore".
+- `MAX_SIDE` — 64 in `Av1BlockSnapshot.js`, a different 64 in `forward_transform_2d.js`.
+
+**Proposal.** Rename to the job: `filter_deblock_edge` / `filter_intra_edge`,
+`restore_lr_block` / `snapshot_restore_block`, `SNAPSHOT_MAX_SIDE` / `TRANSFORM_MAX_SIDE`. All six are
+file-local, so each rename is contained to one file.
+
+### A12 — Table shape exports are almost entirely unused
+
+`block_tables.js` exports a `*_SHAPE` array next to every table (`SUBSAMPLED_SIZE_SHAPE`,
+`MAX_TX_DEPTH_SHAPE`, …). Exactly one is consumed outside the tables folder:
+`PARTITION_SUBSIZE_SHAPE` at
+[encode_tile.js:142](../../../../avif/native/av1/encode/encode_tile.js#L142), to derive a stride.
+
+**Proposal.** Either keep them (they are generated, they cost nothing at runtime, and they document
+the flattening) — in which case say so in `DECISIONS.md` so nobody prunes them — or have the
+generator emit `*_STRIDE` scalars for the multi-dimensional tables only, which is the thing callers
+actually want. I lean towards keeping and documenting: D24 validates the generated tables
+structurally, and the shapes are what that validation reads.
+
+---
+
+## 3. Inside the PNG loader
+
+### P1 — `PNGReader` is prototype-style in an ES-class codebase
+
+[PNGReader.js:51](png/PNGReader.js#L51) is a `function` constructor with fourteen
+`PNGReader.prototype.x = function` assignments. Everything around it — `PNG`, `Codec`,
+`ColourTransform`, `ByteCursor`, `JpegImage` — is an ES class. The file also opens with
+`"use strict"` and a `/*global Uint8Array:true ArrayBuffer:true */` comment, both vestigial.
+
+**Proposal.** Straight mechanical conversion to `class PNGReader`. No behaviour change, no signature
+change. Worth doing as its own commit before any of the other PNG items so their diffs stay readable.
+
+### P2 — Two inflate paths in one package
+
+[PNGReader.decodePixels:356](png/PNGReader.js#L356) constructs a `zlib.Inflate`, pushes chunks,
+and on error falls back to `inflateRaw` on the concatenated bytes with the 2-byte header stripped —
+about 30 lines with a well-argued comment about real-world encoders and libpng leniency.
+
+[inflate.js:8](png/inflate.js#L8) is a separate, simpler wrapper used only by the two text-chunk
+decoders, with no leniency and a different error shape (`throw new Error(inflator.err)` — a numeric
+code, not a message).
+
+**Proposal.** One `png_inflate(chunks, {lenient})` in `inflate.js` covering both. The multi-chunk
+concatenation is the general case; single-chunk is `[chunk]`. The lenient fallback stays opt-in and
+keeps its comment, which is the most valuable thing in that function.
+
+### P3 — Unfilter functions have five different signatures
+
+| Filter | Signature |
+| --- | --- |
+| `None` | `(data, addr, out, out_offset, length, bit_depth)` |
+| `Sub` | `(data, addr, out, bpp, out_offset, length)` |
+| `Up` | `(data, addr, out, out_offset, prev_offset, length)` |
+| `Average` | `(data, addr, out, bpp, out_offset, prev_offset, length)` |
+| `Paeth` | `(data, addr, out, bpp, out_offset, prev_offset, length)` |
+
+Which forces [PNGReader.unFilter:576](png/PNGReader.js#L576) to be a 60-line `switch` that
+reassembles a different argument list per case.
+
+**Proposal.** One uniform signature — `(data, scanline_address, output, bytes_per_pixel,
+output_offset, output_offset_previous, length, bit_depth)` — with each filter ignoring what it does
+not need, and a frozen dispatch table `PNG_UNFILTER = [none, sub, up, average, paeth]`. `unFilter`
+becomes a bounds check plus `PNG_UNFILTER[filter_type](...)`.
+
+**The signature mess is hiding a bug — check this before refactoring.** `png_filter_unFilterNone` is
+doing two jobs: unfiltering *and* unpacking sub-byte samples (bit depths 1/2/4). No other filter
+unpacks. Two consequences follow from reading `interlaceNone`
+([PNGReader.js:420](png/PNGReader.js#L420)) against it:
+
+- It passes `length = color_bytes_per_row`, a **byte** count, and `unFilterNone` treats that as a
+  **sample** count when `bit_depth < 8`. A 16-pixel-wide 1-bit greyscale row has
+  `color_bytes_per_row = 2`, so two samples get unpacked instead of sixteen — and `pixels` is
+  allocated at `color_bytes_per_row * height`, so there is nowhere to put the other fourteen anyway.
+- Filters 1–4 write packed bytes into an output that `PNG.getUint8Data` then reads as unpacked
+  samples, so any sub-byte-depth image using them is wrong on a second axis.
+
+`PNGReader.spec.js` tests bit depths 8 and 16 only — **no test anywhere uses depth 1, 2 or 4**, which
+is why this has survived. Write that test first; the refactor must not preserve the behaviour.
+Separating "unfilter" (byte-wise, all five filters) from "unpack samples" (a second pass, depth-aware)
+fixes both axes at once and is the right shape regardless of whether you agree with the diagnosis.
+
+**Confirmed, and there was a third axis.** The tests were written first and failed exactly as
+predicted: a 16-wide 1-bit row produced two samples, and a Sub-filtered 4-bit row came back as raw
+packed bytes. What the diagnosis missed is `interlaceAdam7`, which was worse — its bytes-per-pixel
+was `colors * bitDepth / 8`, a *fraction* below eight bits, and every length and buffer size derived
+from it. Seven new decoder tests cover it now, two of them rebuilding an 8x8 image from all seven
+Adam7 passes at 1 and 4 bits.
+
+### P4 — `PNGReader` carries two cursors and uses one
+
+The constructor sets `this.i = 0` ([PNGReader.js:56](png/PNGReader.js#L56)) *and* builds a
+`BinaryBuffer` with its own `position`. `this.i` is written once, read once (in `decodeHeader`'s
+`if (this.i !== 0) throw`) and never advanced — a dead cursor guarding a condition that can never be
+false.
+
+**Proposal.** Delete `this.i` and the guard. `this.header` (an 8-byte `Uint8Array` field) can be a
+local in `decodeHeader`.
+
+### P5 — `crc_enabled` defaults off with a `console.warn` on failure
+
+Covered in C7. Restating here because it is a PNG-side decision that deserves a written rationale in
+the same place the other PNG decisions will live.
+
+### P6 — Text chunks are decoded and thrown away
+
+`decodeChunk` calls `png_chunk_decode_zTXt(chunk)` and `png_chunk_decode_iTXt(chunk)`
+([PNGReader.js:212](png/PNGReader.js#L212)) and **discards both return values**. `png.text` is only
+ever written by `decodetEXt` / `decodeiEXt`, which the dispatch switch never reaches (D2 below).
+
+So the PNG decoder pays for inflating every compressed text chunk and keeps none of it.
+
+**Proposal.** Either wire the results into `png.text` (three lines, and it makes the `text` field
+mean something), or stop calling them from `decodeChunk` and keep the two decoders as a library the
+metadata path can use when there is one. Pick one; the current state is the cost of the first with
+the benefit of neither.
+
+---
+
+## 4. Inside the JPEG loader
+
+### J1 — `JpegImage.parse` is one function doing six jobs
+
+250 lines, four nested closures capturing a mutable `offset`, a `switch` with sixteen cases, two
+error-recovery paths, and the component-preparation pass all in one scope. There is also a
+duplicated `case 0xFFEC:` (APP12 appears twice, [JpegImage.js:161](jpeg/JpegImage.js#L161) and
+[:162](jpeg/JpegImage.js#L162)) — harmless, but a symptom.
+
+**Proposal.** Covered structurally by C5.2. Concretely: `for_each_jpeg_segment` walker, then
+`parse_app_segment`, `parse_dqt`, `parse_sof`, `parse_dht`, `parse_sos`, `prepare_components` as
+free functions taking explicit state. `prepareComponents` in particular is a pure function of a
+`JpegFrame` and belongs in its own file next to `JpegFrame.js`.
+
+### J2 — `for...in` over `frame.components` with `hasOwnProperty` guards
+
+`frame.components` is a plain object keyed by numeric component id, iterated with `for (componentId
+in frame.components)` plus `hasOwnProperty` checks
+([JpegImage.js:74](jpeg/JpegImage.js#L74)), and later mutated with `delete cp[j].quantizationIdx`
+([JpegImage.js:390](jpeg/JpegImage.js#L390)). `frame.componentsOrder` already carries the ids in
+order.
+
+**Proposal.** `components` becomes a `Map<number, JpegFrameComponent>`, or the array indexed by
+`componentsOrder` that the code already maintains alongside it. The `delete` goes away — a
+`quantizationIdx` that has been resolved into `quantizationTable` can simply stay, or be set to
+`-1`. Deleting a property to mark state is a deopt and a lie about the struct's shape, and
+`JpegFrameComponent` is a declared class with declared fields
+([JpegFrameComponent.js](jpeg/JpegFrameComponent.js)) — the delete contradicts it.
+
+### J3 — `getData` and `copyToImageData` both switch on component count
+
+[JpegImage.js:421](jpeg/JpegImage.js#L421) `getData` has arms for 1, 2, 3, 4 components.
+[JpegImage.js:561](jpeg/JpegImage.js#L561) `copyToImageData` has arms for 1, 3, 4 — no 2, so a
+two-component PDF-style JPEG parses and then throws at the last step. The CMYK arm inverts twice
+(`255 - C` inside `getData`, `255 - clampTo8bit(C * (1 - K/255) + K)` in `copyToImageData`), which is
+correct but only legible if you read both functions together.
+
+**Proposal.** After C3 and C4 land, `getData` produces normalised RGB (or RGBA) rows directly and
+`copyToImageData` becomes the channel-expansion call from C2. The component-count switch survives in
+exactly one place: choosing the colour transform.
+
+### J4 — `clampTo8bit` against `core/math`
+
+[JpegImage.js:39](jpeg/JpegImage.js#L39) is `clamp(a, 0, 255)` with a nested ternary.
+`core/math/clamp.js` exists and `core/binary/float_to_uint8.js` exists. Use one.
+
+---
+
+## 5. Dead code
+
+Removing these first makes every other item in this document a smaller diff.
+
+| # | What | Lines | Evidence |
+| --- | --- | --- | --- |
+| D1 | [PNG.js:188](png/PNG.js#L188) `getPixel`, [:257](png/PNG.js#L257) `getRGBA8Array_fromRGB`, [:282](png/PNG.js#L282) `getRGBA8Array_generic`, [:303](png/PNG.js#L303) `getRGBA8Array` | ~120 | No importer, no spec. Only `getUint8Data` is called. |
+| D2 | [PNGReader.js:260](png/PNGReader.js#L260) `decodetEXt`, [:273](png/PNGReader.js#L273) `decodeiEXt` | ~35 | `decodeChunk`'s switch has no `tEXt` or `iTXt`→`decodeiEXt` arm. Also **both are wrong if revived**: `decodetEXt` reads the value with `readASCIICharacters(keyword.length - 1)` (the *keyword's* length), and `decodeiEXt` calls `readUTF8String()`, which reads a 4-byte length prefix PNG does not have. |
+| D3 | [prototypePNG.js](png/prototypePNG.js) | 37 | A hard-coded-path browser demo with top-level side effects, sitting in `src/`. No importer. |
+| D4 | [idct8x8_fixed.js](jpeg/idct8x8_fixed.js) | 213 | No importer. `buildComponentData` uses `idct8x8_float`. If it is kept as a documented alternative, say so in a header comment and give it a spec — otherwise the MBOIT-chunk precedent (guarded + spec'd + a note saying why) is the bar. |
+| D5 | [PNGReader.js:56](png/PNGReader.js#L56) `this.i` | 3 | P4. |
+| D6 | [JpegImage.js:162](jpeg/JpegImage.js#L162) duplicate `case 0xFFEC` | 1 | J1. |
+
+Total: roughly 410 lines, none of it reachable.
+
+---
+
+## 6. What *not* to unify
+
+Recording these so the document cannot be read as arguing for them.
+
+- **`ByteCursor` into `BinaryBuffer`.** D10 settled this: growable stream for writing, zero-copy
+  `DataView` cursor for reading. The reasoning still holds, and `ByteCursor.sub_cursor` has no sane
+  `BinaryBuffer` equivalent. C8 shares the UTF-8 codec, not the cursor. What *is* worth doing is
+  making the naming rhyme — `ByteCursor.u32()` versus `BoxWriter.u32()` versus
+  `BinaryBuffer.readUint32BE()` are three spellings of one operation, and `BoxWriter` already chose
+  the cursor's spelling for its own methods, so the cursor pair is self-consistent and only
+  `BinaryBuffer` reads differently. Leave it.
+- **`encode_tile` into `decode_tile`.** D30 settled this. The traversal is mirrored deliberately;
+  inverting the decoder's control flow to serve both would be worse. Every item in section 2 shares
+  *derived state*, which is precisely what D30 asks for, and none of them touches traversal.
+- **`BitReader` / `BitWriter` into one class.** They are a clean symmetric pair with no shared
+  implementation to extract — A10's `ns` width derivation is the only overlap and that is four
+  lines.
+- **A single generic TLV walker for boxes, chunks and markers.** See C5. Share the contract, not the
+  implementation.
+- **The generated tables.** D4 and D22 settled provenance; A9 and A12 are naming and documentation
+  items, not proposals to hand-edit generated output.
+
+---
+
+## 7. Sequencing
+
+Ordered by value per unit of risk. Each row is independently landable.
+
+| Order | Items | Effort | Risk | Why here |
+| --- | --- | --- | --- | --- |
+| 1 | **D1–D6** (dead code) | ~1h | none | Shrinks every later diff. |
+| 2 | **A3, A4, A5, A8, A10** (verbatim AVIF duplicates) | ~2h | none | Pure deletion + import. Fixture round-trips cover it. |
+| 3 | **A1, A2** (tile limits, CDF adapt) | ~2h | low | Highest-consequence duplicates: divergence here is a bitstream desync. Do them while the memory of section 2 is fresh. |
+| 4 | **P1, P4, C6** (PNG class conversion, dead cursor, checked reads) | ~3h | low | Mechanical, and C6 needs P1's shape to be clean. |
+| 5 | **C7, C8** (crc32 and UTF-8 to `core`) | ~2h | low | Unblocks USDZ CRC verification as a side effect. |
+| 6 | **C1** (`Codec` registration) | ~1d | low | The one that changes what the engine can load. Everything above makes it a smaller change. |
+| 7 | **A6, A7, A9** (plane_residual_size, losslessness, MAX_TX_DEPTH) | ~half day | low–med | A7 needs a decision about whether the encoder's assumptions become inputs or stay assumptions. |
+| 8 | **P2, P3, J1, J2** (PNG inflate, filter table, JPEG parse split) | ~1d | med | P3 wants the sub-byte-depth test from section P3 written **first**. |
+| 9 | **C3, C4, C2** (colour transform, upsampling, channel expansion to `core`) | ~2d | med | The largest win and the largest blast radius. Needs the JPEG fixtures extended first; do it last, when JPEG is reachable (C1) and therefore testable end to end. |
+| 10 | **A11, A12, P5, P6** (naming, docs, text chunks) | ~half day | none | Housekeeping; can slot in anywhere. |
+
+Items 1–5 are about a day and a half and are all deletions or moves. If only one thing from this
+document gets done, do row 1 and row 3.
+
+---
+
+## 8. One thing this review did not do
+
+I read `src/avif/native/DECISIONS.md` before writing, and several proposals here are shaped by it —
+sections 2 and 6 in particular. **PNG and JPEG have no equivalent.** There is a `jpeg/NOTES.md` with
+two URLs in it and nothing else.
+
+That asymmetry is itself a finding. The AVIF tree's `crc_enabled`-style choices are all written
+down; the PNG tree's are not, which is why C6 (unchecked reads), P5 (CRC off by default) and P6
+(text decoded and discarded) each read as "possible oversight" rather than "decision". Some of them
+almost certainly *are* decisions — a game engine that warns on a bad CRC instead of refusing the
+texture is making a defensible call — but nothing in the tree says so, so the next person to touch it
+has to guess.
+
+Whatever subset of this document gets acted on, a `src/engine/asset/loaders/image/DECISIONS.md`
+recording the ones that get **rejected** is worth as much as the refactors that get accepted.