@woosh/meep-engine 3.60.4 → 3.60.6

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

@@ -1,815 +0,0 @@
-# Image codecs — duplication and shared-construct review
-
-Review, 2026-08-28. Alex Goldring / Company Named Limited.
-
-Scope: `src/format/image/avif/`, `src/format/image/png/`, `src/format/image/jpeg/`. Everything below
-is an itemised proposal; nothing has been changed.
-
-> **2026-09-02.** The three trees were relocated under `src/format/image/` (see
-> `src/CODEC_LAYOUT_VERIFICATION.md`); the links below were rewritten to follow them, and the paths in
-> prose were not. C1 has since landed in three parts, all in `engine/asset/`: `codec/DecodedImage.js`
-> is the one result struct; `loaders/image/codec/{JpegCodec,AvifCodec}.js` put both decoders behind
-> the `Codec` door, last in `ImageRGBADataLoader`'s chain so a browser keeps its native decoder and
-> node gains both; `guessAssetType` maps `.avif` to `"image"`. One inversion from the proposal:
-> `AvifCodec` wraps `avif_to_sampler2d` rather than the other way round, because the adapter is the
-> one with the HDR path and the reusable decoder context, and an 8-bit asset codec wants neither.
->
-> Not on this review's list, and gone the same day: `shade/renderer/loader/usd/usd_decode_image.js` carried a
-> *third* PNG decoder (8-bit RGB/RGBA, fixed-Huffman only, its own inflate). It now calls `PNGReader` and
-> widens the result to RGBA8 — one more `itemSize → RGBA` loop for C2 to fold, and one fewer decoder.
-
-Placed here rather than under `src/format/image/avif/` because the majority of the *cross-tree* items land
-on the loader side, and `src/format/image/avif/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](../../../../format/image/avif/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](../../../../format/image/avif/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](../../../graphics/texture/sampler/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](../../../../format/image/avif/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](../../../graphics/texture/sampler/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](../../../../format/image/avif/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](../../../../format/image/avif/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/format/image/avif/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](../../../../format/image/avif/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](../../../../format/image/avif/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](../../../../format/image/avif/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](../../../../core/binary/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](../../../../format/scene/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](../../../../core/binary/ByteCursor.js#L307) has a private `utf8_decode`
-with the stated reason that `TextDecoder` is not universally available.
-[BoxWriter.js:205](../../../../format/image/avif/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/format/image/avif/` — 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](../../../../format/image/avif/av1/obu/parse_frame_header.js#L250) and
-[write_frame_header.js:162–179](../../../../format/image/avif/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](../../../../format/image/avif/av1/entropy/SymbolReader.js#L178) and
-[SymbolWriter.js:216–240](../../../../format/image/avif/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](../../../../format/image/avif/av1/entropy/SymbolWriter.js#L200) and
-[:206](../../../../format/image/avif/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](../../../../format/image/avif/av1/decode/decode_tile.js#L115) and
-[:125](../../../../format/image/avif/av1/decode/decode_tile.js#L125); the same two functions verbatim at
-[encode_tile.js:277](../../../../format/image/avif/av1/encode/encode_tile.js#L277) and
-[:287](../../../../format/image/avif/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](../../../../format/image/avif/av1/decode/reconstruct.js#L222) and
-[:235](../../../../format/image/avif/av1/decode/reconstruct.js#L235); identical copies at
-[quantise.js:193](../../../../format/image/avif/av1/encode/quantise.js#L193) and
-[:206](../../../../format/image/avif/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](../../../../format/image/avif/av1/decode/decode_tile.js#L273) and
-[encode_tile.js:838](../../../../format/image/avif/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](../../../../format/image/avif/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](../../../../format/image/avif/av1/decode/decode_tile.js#L572) (as a named function)
-- [encode_tile.js:525](../../../../format/image/avif/av1/encode/encode_tile.js#L525),
-  [:1728](../../../../format/image/avif/av1/encode/encode_tile.js#L1728),
-  [:2088](../../../../format/image/avif/av1/encode/encode_tile.js#L2088),
-  [:2179](../../../../format/image/avif/av1/encode/encode_tile.js#L2179) (four times, inline)
-- [coefficient_context.js:50](../../../../format/image/avif/av1/entropy/coefficient_context.js#L50)
-- [loop_filter.js:110](../../../../format/image/avif/av1/filter/loop_filter.js#L110)
-
-**Proposal.** Export `plane_residual_size(mi_size, sub_x, sub_y)` from
-[derived_block_tables.js](../../../../format/image/avif/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](../../../../format/image/avif/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](../../../../format/image/avif/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](../../../../format/image/avif/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](../../../../format/image/avif/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](../../../../format/image/avif/api/decode_avif.js#L15), [encode_avif.js:41](../../../../format/image/avif/api/encode_avif.js#L41) |
-| `QM_TOTAL_SIZE` | [av1_symbols.js:261](../../../../format/image/avif/av1/tables/av1_symbols.js#L261) (exported) and [reconstruct.js:33](../../../../format/image/avif/av1/decode/reconstruct.js#L33) (local copy of the same `3344`) |
-| `HLG_A/B/C` | [transfer_to_linear.js:50](../../../../format/image/avif/color/transfer_to_linear.js#L50), [linear_to_transfer.js:18](../../../../format/image/avif/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](../../../../format/image/avif/av1/tables/av1_symbols.js#L176) exports
-`MAX_TX_DEPTH = 2` (a scalar bound).
-[block_tables.js:12](../../../../format/image/avif/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](../../../../format/image/avif/api/convert_to_rgba.js#L217) and
-  [ycbcr_row_to_rgb.js:83](../../../../format/image/avif/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](../../../../format/image/avif/av1/encode/choose_restoration.js#L622) and
-  [upsample_chroma_row.js:94](../../../../format/image/avif/color/upsample_chroma_row.js#L94) — same body,
-  different parameter names.
-- [floor_log2.js:15](../../../../format/image/avif/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](../../../../format/image/avif/api/convert_to_rgba.js#L199) `quantise` and
-  [encode_avif.js:415](../../../../format/image/avif/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 `format/image/avif/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](../../../../format/image/avif/bitstream/BitReader.js#L216),
-`BitWriter.ns`, [SymbolReader.js:286](../../../../format/image/avif/av1/entropy/SymbolReader.js#L286) and
-[SymbolWriter.js:283](../../../../format/image/avif/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](../../../../format/image/avif/av1/filter/loop_filter.js) (a deblocking
-  edge) and [predict_intra.js](../../../../format/image/avif/av1/predict/predict_intra.js) (an intra edge
-  smoothing kernel). Unrelated jobs, identical name.
-- `restore_block` — [loop_restoration.js](../../../../format/image/avif/av1/filter/loop_restoration.js)
-  (Wiener/SGR restoration) and
-  [Av1BlockSnapshot.js](../../../../format/image/avif/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](../../../../format/image/avif/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/format/image/avif/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.