@woosh/meep-engine 3.14.2 → 3.14.3

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

@@ -2,12 +2,24 @@
 
 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.
+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.
 
 ---
 
@@ -20,7 +32,7 @@ substantially the same job.
 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.
+[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.
 
@@ -35,7 +47,7 @@ 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
+([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
@@ -88,7 +100,7 @@ These are the ones where a construct exists in one tree and is re-invented in an
 | --- | --- | --- |
 | 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 |
+| 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`
@@ -104,7 +116,7 @@ browser canvas path — which is why the native JPEG decoder has never needed to
    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
+   [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
@@ -130,7 +142,7 @@ Same job — take interleaved samples with `itemSize` channels and produce RGBA
 - [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
+- [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),
@@ -160,7 +172,7 @@ expansion — but it should call the shared function for the final write rather
 
 | 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` |
+| [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 |
 
@@ -170,13 +182,13 @@ The JPEG constants are not "close to" BT.601 — they *are* `colour_transform_in
 `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
+([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/avif/native/color/` into `src/core/color/`. They have no AV1 dependency beyond the `MC_*` /
+`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).
 
@@ -203,7 +215,7 @@ 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
+[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
@@ -239,10 +251,10 @@ and option state.
 
 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
+- [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](../../../../avif/native/av1/obu/for_each_obu.js#L25) — same contract, two
+- [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:
@@ -310,7 +322,7 @@ a plausible-looking wrong picture instead of throwing.
 [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
+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.
 
@@ -329,7 +341,7 @@ records choices like this in `DECISIONS.md`. Give the PNG folder the same treatm
 
 [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](../../../../avif/native/isobmff/BoxWriter.js#L205) has the matching encoder inline
+[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.
@@ -350,15 +362,15 @@ This does **not** conflict with D10: it shares the character codec, not the curs
 
 ---
 
-## 2. Inside `src/avif/native/` — finishing D30
+## 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](../../../../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
+[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.
@@ -370,8 +382,8 @@ uniform-spacing loop reads and writes, so a divergence here is a bitstream desyn
 
 ### 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
+[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
@@ -380,17 +392,17 @@ adaptation rate is normative and shared by construction; there is no reason for
 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,
+([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](../../../../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).
+[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
@@ -398,10 +410,10 @@ 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
+[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.
 
@@ -409,8 +421,8 @@ never made the trip.
 
 ### 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
+[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
@@ -418,7 +430,7 @@ encoder does the same thing with no explanation, which is the half of the pair t
 "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
+[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.
 
@@ -426,23 +438,23 @@ reentrancy coupling), only the fill and the save/restore discipline move.
 
 `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)
+- [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](../../../../avif/native/av1/tables/derived_block_tables.js) — which already
+[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](../../../../avif/native/av1/decode/decode_tile.js#L963)) clamps a chroma
+([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](../../../../avif/native/av1/encode/encode_tile.js#L2167)) does not, and adds a
+([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
@@ -450,12 +462,12 @@ function with the encoder's extra cases guarded, or leave a comment on both stat
 
 ### A7 — Losslessness derived twice, and the two do not agree
 
-[parse_frame_header.js:527](../../../../avif/native/av1/obu/parse_frame_header.js#L527)
+[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](../../../../avif/native/av1/encode/build_headers.js#L236) does:
+[build_headers.js:236](../../../../format/image/avif/av1/encode/build_headers.js#L236) does:
 
 ```js
 const lossless = frame.base_q_idx === 0;
@@ -476,9 +488,9 @@ rather than a parallel implementation of it.
 
 | 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) |
+| `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
@@ -487,9 +499,9 @@ map). `QM_TOTAL_SIZE` → delete the local copy, import the exported one. `HLG_A
 
 ### A9 — `MAX_TX_DEPTH` is two different exported symbols
 
-[av1_symbols.js:176](../../../../avif/native/av1/tables/av1_symbols.js#L176) exports
+[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](../../../../avif/native/av1/tables/block_tables.js#L12) exports
+[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
@@ -504,23 +516,23 @@ that needs both gets a shadowing bug that will look like a table lookup returnin
 ### 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
+  [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](../../../../avif/native/av1/encode/choose_restoration.js#L622) and
-  [upsample_chroma_row.js:94](../../../../avif/native/color/upsample_chroma_row.js#L94) — same body,
+  [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](../../../../avif/native/av1/util/floor_log2.js#L15) is `31 - Math.clz32(x)`,
+- [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](../../../../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
+- [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
@@ -534,14 +546,14 @@ there needs evidence rather than taste. Three runs of the AVIF suite before and
 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/`,
+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](../../../../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
+[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.
 
@@ -549,12 +561,12 @@ in style in the first place.
 
 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
+- `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](../../../../avif/native/av1/filter/loop_restoration.js)
+- `restore_block` — [loop_restoration.js](../../../../format/image/avif/av1/filter/loop_restoration.js)
   (Wiener/SGR restoration) and
-  [Av1BlockSnapshot.js](../../../../avif/native/av1/encode/Av1BlockSnapshot.js) (undo an encoder
+  [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`.
 
@@ -567,7 +579,7 @@ file-local, so each rename is contained to one file.
 `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.
+[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
@@ -788,7 +800,7 @@ 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 —
+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.
 

package/src/engine/asset/loaders/image/ImageDecoderWorker.js

@@ -1,4 +1,4 @@
-import { PNGReader } from "./png/PNGReader.js";
+import { PNGReader } from "../../../../format/image/png/PNGReader.js";
 
 async function decode_png(png_bytes) {
     return new Promise((resolve, reject) => {
@@ -32,7 +32,7 @@ async function decode_png(png_bytes) {
  *
  * @param {ArrayBuffer} data
  * @param {string} type
- * @returns {Promise<unknown>}
+ * @returns {Promise<DecodedImage>} `data` is an `ArrayBuffer`, for the transfer back
  */
 async function decode(data, type = 'png') {
     if (!(data instanceof ArrayBuffer)) {

package/src/engine/asset/loaders/image/ImageRGBADataLoader.d.ts

@@ -5,22 +5,21 @@ export class ImageRGBADataLoader extends AssetLoader<any, any> {
      */
     constructor({ worker_path }?: string);
     /**
+     * In order: PNG off the main thread; whatever the browser's own decoder will take, through a
+     * canvas; and last, the in-tree JPEG and AVIF decoders. Last because
+     * {@link NativeImageDecoder} claims every input and is the faster decoder for both wherever
+     * it exists — the codecs after it are what make those files loadable where it does not: node,
+     * or a worker without `Image`.
      *
-     * @type {CodecWithFallback<{data, width:number, height:number, itemSize:number, bitDepth:number}>}
+     * @type {CodecWithFallback<DecodedImage>}
      */
-    decoder: CodecWithFallback<{
-        data;
-        width: number;
-        height: number;
-        itemSize: number;
-        bitDepth: number;
-    }>;
+    decoder: CodecWithFallback<DecodedImage>;
     link(assetManager: any, engine: any): Promise<void>;
     /**
      *
      * @param {string} path
      * @param {AssetRequestScope} scope
-     * @returns {Promise<{data:ArrayBuffer, width: number, height:number, itemSize: number, bitDepth:number}>}
+     * @returns {Promise<DecodedImage>}
      * @private
      */
     private __decode_via_worker;

package/src/engine/asset/loaders/image/ImageRGBADataLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ImageRGBADataLoader.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/asset/loaders/image/ImageRGBADataLoader.js"],"names":[],"mappings":"AASA;IACI;;;OAGG;IACH,8BAFW,MAAM,EAehB;IARG;;;OAGG;IACH,SAFU,kBAAkB;QAAC,IAAI,CAAC;QAAC,KAAK,EAAC,MAAM,CAAC;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,QAAQ,EAAC,MAAM,CAAC;QAAC,QAAQ,EAAC,MAAM,CAAA;KAAC,CAAC,CAKjG;IAGL,oDAOC;IAED;;;;;;OAMG;IACH,4BASC;IAED;;;;;;OAMG;IACH,mBAyBC;IAED,sFAEC;CACJ;4BA5F2B,mBAAmB;kCACb,kCAAkC"}
+{"version":3,"file":"ImageRGBADataLoader.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/asset/loaders/image/ImageRGBADataLoader.js"],"names":[],"mappings":"AAWA;IACI;;;OAGG;IACH,8BAFW,MAAM,EAsBhB;IAfG;;;;;;;;OAQG;IACH,SAFU,kBAAkB,YAAY,CAAC,CAOxC;IAGL,oDAOC;IAED;;;;;;OAMG;IACH,4BASC;IAED;;;;;;OAMG;IACH,mBAyBC;IAED,sFAEC;CACJ;4BArG2B,mBAAmB;kCACb,kCAAkC"}

package/src/engine/asset/loaders/image/ImageRGBADataLoader.js

@@ -1,6 +1,8 @@
 import { ArrayBufferLoader } from "../ArrayBufferLoader.js";
 import { AssetLoader } from "../AssetLoader.js";
 import { CodecWithFallback } from "../../codec/CodecWithFallback.js";
+import { AvifCodec } from "./codec/AvifCodec.js";
+import { JpegCodec } from "./codec/JpegCodec.js";
 import { NativeImageDecoder } from "./codec/NativeImageDecoder.js";
 import { ThreadedImageDecoder } from "./codec/ThreadedImageDecoder.js";
 import { ImageRGBADataAsset } from "./ImageRGBADataAsset.js";
@@ -18,12 +20,19 @@ export class ImageRGBADataLoader extends AssetLoader {
         super();
 
         /**
+         * In order: PNG off the main thread; whatever the browser's own decoder will take, through a
+         * canvas; and last, the in-tree JPEG and AVIF decoders. Last because
+         * {@link NativeImageDecoder} claims every input and is the faster decoder for both wherever
+         * it exists — the codecs after it are what make those files loadable where it does not: node,
+         * or a worker without `Image`.
          *
-         * @type {CodecWithFallback<{data, width:number, height:number, itemSize:number, bitDepth:number}>}
+         * @type {CodecWithFallback<DecodedImage>}
          */
         this.decoder = new CodecWithFallback(
             new ThreadedImageDecoder({ worker_path }),
-            new NativeImageDecoder()
+            new NativeImageDecoder(),
+            new JpegCodec(),
+            new AvifCodec()
         );
     }
 
@@ -40,7 +49,7 @@ export class ImageRGBADataLoader extends AssetLoader {
      *
      * @param {string} path
      * @param {AssetRequestScope} scope
-     * @returns {Promise<{data:ArrayBuffer, width: number, height:number, itemSize: number, bitDepth:number}>}
+     * @returns {Promise<DecodedImage>}
      * @private
      */
     async __decode_via_worker(path, scope) {

package/src/engine/asset/loaders/image/avif/encode_image_source.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Encoding one image source, whichever side of a worker boundary it happens on.
+ *
+ * The encoder is meep's own, under `./native` — pure JavaScript, synchronous and portable — so the
+ * same two functions serve the worker pool and the fallback for environments that have no workers.
+ * Keeping them here rather than in the worker is what stops the two paths from drifting apart.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * The effort a caller's `speed` asks for.
+ *
+ * `speed` is the dial the WebAssembly encoder took: zero is slowest and best, ten is fastest. The
+ * native encoder names three points on that curve instead of eleven, because those are the three
+ * that measure differently; this maps one onto the other so that existing callers keep meaning what
+ * they meant.
+ *
+ * @param {number} [speed] `0 .. 10`
+ * @returns {number} one of the `EFFORT_*` constants
+ */
+export function effort_of_speed(speed?: number): number;
+/**
+ * An encode context to hand back to the functions below.
+ *
+ * One per worker, or one per process for the inline path: it holds the planes and contexts an
+ * encode needs, and reusing it is what keeps a run of encodes from allocating a fresh set each time.
+ *
+ * @returns {Av1EncodeContext}
+ */
+export function create_encoder(): Av1EncodeContext;
+/**
+ * Encode an image bitmap.
+ *
+ * Needs a canvas to read the bitmap's samples back out — a bitmap is an opaque handle, and drawing
+ * it is the only way to see it. That is a platform capability rather than a codec one, which is why
+ * this is the operation that can be unavailable where the other cannot.
+ *
+ * @param {{bitmap: ImageBitmap, quality: number, speed: (number|undefined)}} request the bitmap is
+ *   closed once it has been read
+ * @param {Av1EncodeContext} encoder
+ * @returns {ArrayBuffer}
+ */
+export function encode_bitmap_source(request: {
+    bitmap: ImageBitmap;
+    quality: number;
+    speed: (number | undefined);
+}, encoder: Av1EncodeContext): ArrayBuffer;
+/**
+ * Encode a sampler.
+ *
+ * Half float samplers are taken as linear light in the renderer's normalisation and coded through
+ * the PQ transfer function; eight bit ones are coded as ordinary sRGB. Which of the two it is comes
+ * from the data itself, so it survives being posted to a worker.
+ *
+ * @param {{data: TypedArray, width: number, height: number, item_size: number, quality: number,
+ *   speed: (number|undefined)}} request
+ * @param {Av1EncodeContext} encoder
+ * @returns {ArrayBuffer}
+ */
+export function encode_sampler_source(request: {
+    data: TypedArray;
+    width: number;
+    height: number;
+    item_size: number;
+    quality: number;
+    speed: (number | undefined);
+}, encoder: Av1EncodeContext): ArrayBuffer;
+import { Av1EncodeContext } from '../../../../../format/image/avif/av1/encode/Av1EncodeContext.js';
+//# sourceMappingURL=encode_image_source.d.ts.map

package/src/engine/asset/loaders/image/avif/encode_image_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode_image_source.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/avif/encode_image_source.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,wCAHW,MAAM,GACJ,MAAM,CAgBlB;AAED;;;;;;;GAOG;AACH,kCAFa,gBAAgB,CAI5B;AAED;;;;;;;;;;;GAWG;AACH;YALoB,WAAW;aAAW,MAAM;WAAS,CAAC,MAAM,GAAC,SAAS,CAAC;YAEhE,gBAAgB,GACd,WAAW,CA6BvB;AAED;;;;;;;;;;;GAWG;AACH;;WALqC,MAAM;YAAU,MAAM;eAAa,MAAM;aAAW,MAAM;WACnF,CAAC,MAAM,GAAC,SAAS,CAAC;YACnB,gBAAgB,GACd,WAAW,CAUvB;iCApHgC,iEAAiE"}