@woosh/meep-engine 3.14.2 → 3.14.3

package/src/format/scene/gltf/MESHOPT_COMPRESSION_PLAN.md

@@ -0,0 +1,793 @@
+# `EXT_meshopt_compression` / `KHR_meshopt_compression` — implementation plan
+
+Status: plan. Written 2026-08-20.
+
+Scope: decode side of both extensions.
+
+- `EXT_meshopt_compression` — ratified, Vendor.
+  <https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_meshopt_compression>
+- `KHR_meshopt_compression` — ratified, Khronos, merged 2026-01-23 (PR #2517).
+  <https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_meshopt_compression>
+
+Reference encoder/decoder: <https://github.com/zeux/meshoptimizer>. Consulted for questions the
+specification text leaves ambiguous; **not vendored and not transcribed** — no new dependency, and
+the bitstream below is implemented from the two specifications.
+
+## 1. What these extensions are, and why that shapes the split
+
+Neither is a geometry extension. Both are *bufferView* extensions: a bufferView declares that its
+bytes are produced by running a decoder over a byte range of some other buffer. Nothing about the
+decode depends on what the bufferView is later read as — vertex attributes, index data, morph
+deltas, animation keyframes and `EXT_mesh_gpu_instancing` transforms all go through the same three
+modes and (now) five filters.
+
+That is the seam. Everything except roughly two dozen lines is a **byte-array in, byte-array out**
+codec with no knowledge of glTF at all:
+
+```
+src/core/binary/meshopt/                       pure codec — bytes in, bytes out.
+        ^                                      No glTF, no geometry, no engine.
+        | called by
+src/format/scene/gltf/ext/meshopt/             one bufferView's worth of meshopt: read the
+        ^                                      extension object, check it, return the bytes.
+        | called through GltfBufferViewExtension by
+src/format/scene/gltf/ext/                     the generic bufferView-extension layer — which
+        ^                                      extension claims a view, and what becomes of what
+        |                                      it produced. Names no codec.
+        | called by
+src/shade/renderer/loader/gltf/tiny-gltf.js    one call, after buffers resolve. Names no
+                                               extension at all.
+```
+
+`core/binary` is the codec's right home: it is where meep already keeps byte-level codecs
+(`base64/`, `base58/`, `half_to_float_uint16`, `BinaryBuffer`'s LEB128 `readUintVar`). The codec
+imports nothing outside `core/`, so it is usable from a worker, a tool, or the USD loader without
+dragging Shade in.
+
+### 1.1 KHR is EXT plus three things
+
+The two extensions share a JSON shape, a `bufferView`/`buffer` model, fallback buffers, and modes
+1 and 2 byte for byte. KHR adds:
+
+1. **Attribute codec version 1** (header `0xa1`). A genuinely different bitstream for mode 0: a
+   per-block control header, four control modes, an extra 1-bit sentinel encoding, and three
+   *channel* modes that widen the delta from 8-bit to 16-bit or to a rotated 32-bit XOR.
+   Version 0 (`0xa0`) remains legal under KHR and is bit-identical to EXT.
+2. **Filter 4, `COLOR`** — YCoCg, `byteStride` 4 or 8.
+3. One extra validity rule (`ATTRIBUTES` requires `byteStride >= 4`) and the constraint that a
+   bufferView must not carry both extensions.
+
+So there is one codec that decodes everything, and a glTF layer that enforces the per-name subset:
+a `0xa1` stream or a `COLOR` filter under the `EXT_` name is an invalid file and is rejected.
+
+## 2. Modules
+
+### 2.1 `src/core/binary/meshopt/` — the codec
+
+| File | Export |
+|:--|:--|
+| `MeshoptCompressionMode.js` | `@enum` — `Attributes: 0`, `Triangles: 1`, `Indices: 2` |
+| `MeshoptCompressionFilter.js` | `@enum` — `None: 0`, `Octahedral: 1`, `Quaternion: 2`, `Exponential: 3`, `Color: 4` |
+| `MESHOPT_GROUP_SIZE.js` | the group size, and the 24-byte bound a group read stays inside |
+| `meshopt_decode_byte_group.js` | one group of 16 byte-deltas at a given sentinel width |
+| `meshopt_decode_data_block.js` | one "data block": header bits + its groups, for one byte position |
+| `meshopt_decode_vertex_buffer.js` | mode 0, versions 0 and 1 |
+| `meshopt_decode_index_buffer.js` | mode 1 |
+| `meshopt_decode_index_sequence.js` | mode 2 |
+| `meshopt_decode_filter_octahedral.js` | filter 1, in place |
+| `meshopt_decode_filter_quaternion.js` | filter 2, in place |
+| `meshopt_decode_filter_exponential.js` | filter 3, in place |
+| `meshopt_decode_filter_color.js` | filter 4, in place |
+| `meshopt_decode.js` | dispatch: mode, then filter |
+| `meshopt_read_uint_var.js` | bounded LEB128 over a `Uint8Array` |
+| `__meshopt_test_streams.js` | test-only encoders, shared by the codec specs and the glTF fixtures |
+
+Signatures:
+
+```js
+meshopt_decode_vertex_buffer(destination, count, byte_stride, source)
+meshopt_decode_index_buffer(destination, index_count, index_size, source)
+meshopt_decode_index_sequence(destination, index_count, index_size, source)
+meshopt_decode_filter_*(destination, count, byte_stride)
+meshopt_decode(destination, count, byte_stride, mode, filter, source)
+```
+
+`destination` and `source` are `Uint8Array` throughout — the codec never assumes an aligned
+`ArrayBuffer` offset, because a compressed source range in a glTF is only byte-aligned. Index modes
+and filters build their typed views internally from `index_size` / `byte_stride`.
+
+Two additions outside the package, both genuinely generic and both matching meep's existing naming:
+
+- `src/core/math/round_half_away_from_zero.js` — `Math.round` breaks ties toward `+Infinity`
+  (`Math.round(-2.5) === -2`). Four of the five filters specify `round()` on a signed symmetric
+  quantity and round half away from zero. Sits beside the existing `round_up.js`.
+- nothing else: `msb_32` (`core/binary`) is already `findMSB` including its `-1` for zero, `exp2`
+  and `copysign` (`core/math`) already exist, and `decode_octahedron_to_unit`
+  (`core/geom/3d/normal/octahedron`) is reused by filter 1 — see §4.1.
+
+### 2.2 `src/format/scene/gltf/ext/` — bufferView extensions, generically
+
+A bufferView extension says "these bytes are not in the buffer I point at; run this to get them".
+Meshopt is two of them; a future codec would be a third. The parser should know that shape and
+nothing else, so the layer is split in two — see §9 for why this is not how it was first written.
+
+| File | What it is |
+|:--|:--|
+| `GltfBufferViewExtension.js` | the contract one extension implements: a `name`, `decode()`, and whether it declares placeholder buffers |
+| `GltfBufferViewExtensionSet.js` | which extensions a parser honours, and `claim(view)` — the *only* thing that decides whether anything happens |
+| `gltf_apply_buffer_view_extensions.js` | the walk: claim, delegate, append the buffer, replace the descriptor. Identical for every extension |
+| `gltf_buffer_view_extensions.js` | `GLTF_BUFFER_VIEW_EXTENSIONS`, the set the parser uses by default |
+| `meshopt/MeshoptBufferViewExtension.js` | one class, two instances: `EXT_MESHOPT_COMPRESSION`, `KHR_MESHOPT_COMPRESSION` |
+
+The walker:
+
+1. returns a **new** `bufferViews` array — claimed entries are replaced by fresh descriptors,
+   unclaimed entries pass through **by reference**,
+2. **appends** each decoded buffer to `buffers`, pointing the new descriptor at it with
+   `byteOffset: 0`,
+3. keeps `byteStride`, `target` and everything else from the parent, so accessor reads are unchanged,
+4. refuses a decoder that answered with the wrong number of bytes, whichever decoder it was.
+
+Returning a new array rather than mutating the old descriptors is load-bearing, not taste — §6.3.
+
+The difference between the two meshopt instances is two fields and no branches: which filter names
+the extension defines, and the newest codec version each *mode* may carry. Per mode because both
+index codecs' version 1 is legal under either extension; it is only the attribute codec that the
+vendor extension pins at 0.
+
+### 2.3 `tiny-gltf.js` — the call site
+
+Three edits, all in `loadFromJson`:
+
+- **`~L422-448`, buffer resolution.** Today a buffer with no `uri` outside the GLB fast path is fed
+  to `resolveUri(undefined, baseUrl)` and fetched as `<baseUrl>undefined`. That is exactly the shape
+  of a meshopt *fallback* buffer (`{ "byteLength": N }`, no URI), so today a `gltfpack`-produced
+  `.gltf` cannot load at all. A buffer that is marked `fallback` or has no `uri` resolves to a
+  zero-length `ArrayBuffer` instead of a request (§6.8). Also: the GLB branch currently loads *only*
+  the binary chunk and ignores `buffers[1..n]`, which is where both extensions put the placeholder —
+  the branch becomes "buffer 0 is the chunk, the rest resolve normally".
+- **`~L524-534`, an image sourced from a bufferView.** Throw if that bufferView is compressed. The
+  combination is legal in the abstract and pointless in practice (the payload is already a PNG or a
+  JPEG); the alternative to throwing is handing `createImageBitmap` the fallback buffer's bytes,
+  which is a silent wrong answer.
+- **`~L557`, after `await Promise.all(pendingBuffers)`.** One call to
+  `gltf_apply_buffer_view_extensions` before `json.buffers` and `json.bufferViews` are published.
+
+The parser names no extension: it asks `this.bufferViewExtensions` — a public field, defaulted to the
+standard set and replaceable — and the set is the one place that knows what is implemented.
+
+**Nothing in `load_gltf.js` changes.** It reads `gltf.bufferViews` / `gltf.buffers` inside
+`process()`, which runs after `loadFromJson` has returned, so it sees decoded views and never learns
+either extension exists. That is the point of doing this at the bufferView layer.
+
+## 3. The bitstream, as implemented
+
+Written from the two specifications' Appendix A/B. Notes marked ⚠ are places where a plausible
+reading is wrong.
+
+### 3.1 Mode 0 — attributes
+
+```
+header       1 byte: 0xa0 (version 0) or 0xa1 (version 1, KHR only)
+blocks       one or more attribute blocks
+tail padding zero bytes
+tail block   baseline element (byte_stride bytes)
+             channel modes (byte_stride / 4 bytes, version 1 only)
+```
+
+⚠ **The padding comes BEFORE the tail block; the tail block is flush against the end of the
+stream.** So the baseline element starts at `byteLength - tail_size`, where
+
+```
+tail_size     = byte_stride + (version === 1 ? byte_stride / 4 : 0)
+tail_size_pad = max(tail_size, version === 1 ? 24 : 32)
+```
+
+and the decoder must have consumed exactly `byteLength - tail_size_pad` bytes when the blocks are
+done. EXT's wording — "a baseline element stored verbatim, padded to 32 bytes" — reads equally well
+as element-then-padding, which for any stride below 32 puts the baseline in the wrong place and
+decodes garbage. KHR's rewording ("Tail padding, which pads the size of the *subsequent* tail
+block…") settles it, and the reference decoder agrees: it takes the baseline from
+`data_end - tail_size`, with `tail_size` **unpadded**, while validating the remainder against
+`tail_size_pad`. Two different quantities that coincide only when `byte_stride >= 32`.
+
+Block loop, identical in both versions:
+
+```
+max_block_elements = min(floor(8192 / byte_stride) & ~15, 256)
+block_elements     = min(remaining, max_block_elements)
+group_count        = ceil(block_elements / 16)
+```
+
+⚠ `8192 / byte_stride` is integer division — `floor` before the mask. With `byte_stride <= 256` the
+result is never below 32, so the loop always advances.
+
+A block is, in order:
+
+- a **control header** of `byte_stride / 4` bytes — **version 1 only**,
+- `byte_stride` **data blocks**, one per byte position `k` of the element.
+
+The control header packs a 2-bit *control mode* per byte position, low bits first:
+`(c0 << 0) | (c1 << 2) | (c2 << 4) | (c3 << 6)`, one byte per aligned group of four byte positions.
+The control mode selects what the data block for that byte position looks like:
+
+| control mode | data block |
+|:--|:--|
+| 0 | header bits, group encodings `{zero, 1-bit, 2-bit, 4-bit}` |
+| 1 | header bits, group encodings `{1-bit, 2-bit, 4-bit, raw}` |
+| 2 | nothing at all — every delta byte is 0, no header bits, no bytes consumed |
+| 3 | literal: `group_count * 16` delta bytes, no header bits |
+
+Version 0 has no control header and behaves as a fixed table
+`{zero, 2-bit, 4-bit, raw}` for every byte position.
+
+Where header bits are present they are `ceil(group_count / 4)` bytes, 2 bits per group, packed
+**low bits first**: `(g0 << 0) | (g1 << 2) | (g2 << 4) | (g3 << 6)`. Group encodings:
+
+| encoding | packed bytes | sentinel | total |
+|:--|:--|:--|:--|
+| zero | 0 | — | 0 |
+| 1-bit | 2 | `1` | 2..18 |
+| 2-bit | 4 | `3` | 4..20 |
+| 4-bit | 8 | `15` | 8..24 |
+| raw | 16 | — | 16 |
+
+⚠ Bit order inside a packed byte is **not uniform**. 2-bit and 4-bit run high bits first —
+`(d3 << 0) | (d2 << 2) | (d1 << 4) | (d0 << 6)` and `(d1 << 0) | (d0 << 4)` — while **1-bit runs low
+bits first**, `(d0 << 0) | (d1 << 1) | … | (d7 << 7)`. The spec says so explicitly (it is there to
+let SIMD implementations reuse a lookup table); it is not a transcription slip.
+
+A delta equal to the sentinel means the real value is outside the bit range and is taken as a whole
+byte from the run that follows the packed bytes, in order of appearance.
+
+The delta bytes so recovered are then turned into values by the **channel mode**. Channels are
+aligned groups of four byte positions; version 1 stores one mode byte per channel in the tail, and
+version 0 behaves as though every channel were mode 0.
+
+| channel mode | reconstruction |
+|:--|:--|
+| 0 | per byte: `v = (unzigzag8(d) + prev) & 0xff` |
+| 1 | per aligned 2 bytes, little-endian: `v = (unzigzag16(d) + prev) & 0xffff` |
+| 2 | per aligned 4 bytes, little-endian: `v = rotl32(d, r) ^ prev` |
+
+`r` is the **high** 4 bits of the channel mode byte and applies only to mode 2. ⚠ The decoder
+rotates **left by `r`** — the spec's `rotate(v, r) = (v << r) | (v >> ((32 - r) & 31))` is the
+decode direction, despite the surrounding sentence describing how the encoder produced the delta.
+A mode byte whose low nibble is 3 or above, or whose high nibble is non-zero for mode 0 or 1, makes
+the stream invalid.
+
+Groups always decode sixteen elements; anything past `block_elements` is discarded and does not
+advance the delta chain. Each block ends by taking its **last decoded element** as the next block's
+baseline.
+
+The specification's own worked example is the acceptance test for the group decoder (§5.1).
+
+### 3.2 Mode 1 — triangles
+
+```
+header      1 byte, (h & 0xf0) == 0xe0; version = h & 0x0f, 0 or 1 (both specs pin 0xe1)
+codes       index_count / 3 bytes, one per triangle
+data        variable, immediately after the codes
+codeaux     the last 16 bytes
+```
+
+State: `next` (high-watermark, 0), `last` (0), a 16-entry edge FIFO and a 16-entry vertex FIFO, both
+filled with `0xFFFFFFFF`. `data` must end exactly at the start of `codeaux` — that equality is the
+stream's own checksum.
+
+`fec_max` is 13 for version 1 and 15 for version 0; it is what makes codes `0xXd`/`0xXe` mean
+`last - 1` / `last + 1` rather than two more FIFO slots. Reading it from the header rather than
+hard-coding 13 is why both versions decode correctly.
+
+⚠ The two branches index the vertex FIFO differently: the `code < 0xf0` path reads
+`(offset - 1 - fec) & 15`, the `0xf0..0xff` paths read `(offset - feb) & 15`. This follows from the
+spec's own wording ("index Y" versus "index Z-1") and is not a slip.
+
+⚠ A conditional push writes the value at `offset` and then does not advance `offset`. Skipping the
+write as well is *not* equivalent: every later FIFO read at distance `d` would see what belongs at
+`d - 1`. Two tests reach back past a vertex that was not pushed, because until something does the
+difference is invisible.
+
+⚠ The explicit indices in the `0xfe`/`0xff` branch are read in the order a, b, c, and `last` chains
+through them, so that order is load-bearing. Their position relative to the `next++` allocations is
+*not*: an index is either fresh or explicit, never both, so the two passes do not interfere. (The
+plan asserted otherwise; see §8.)
+
+### 3.3 Mode 2 — indices
+
+```
+header      1 byte, (h & 0xf0) == 0xd0 (both specs pin 0xd1)
+deltas      one LEB128 varint per index
+tail        4 reserved bytes
+```
+
+`v & 1` selects one of two running baselines; `v >> 1` is a zigzag delta applied to it. Two
+baselines rather than one is what lets an encoder splice two monotonic runs (strips, line lists)
+cheaply. Again `data` must land exactly on the 4-byte tail.
+
+### 3.4 Filters
+
+All five are in place over the already-decoded bufferView, `count` elements of `byte_stride` bytes.
+
+- **Octahedral** — `byte_stride` 4 → `Int8Array`, 8 → `Int16Array`. Components 0 and 1 are the
+  octahedral pair, component 2 encodes 1.0 at the element's own precision `K`, component 3 passes
+  through untouched. Output scaled by `max` = 127 or 32767. Reuses meep's own
+  `decode_octahedron_to_unit` — see §4.1.
+- **Quaternion** — `byte_stride` 8, `Int16Array`. `one = input[3] | 3`,
+  `max_component = input[3] & 3`; outputs land at `(max_component + 1..3) & 3` for x/y/z and
+  `(max_component + 0) & 3` for w.
+  ⚠ `input[3]` is read for *both* purposes before any output is written — one of the four writes
+  lands on it.
+  ⚠ The radicand `1 - x² - y² - z²` is clamped at 0. meep already learned this in
+  `quat3_decode_from_uint32`; a NaN quaternion out of a loader poisons every transform downstream.
+- **Exponential** — `byte_stride` divisible by 4. Each 32-bit word is `e = word >> 24` (signed),
+  `m = (word << 8) >> 8` (signed); the result `2^e · m` is written back as a float32. `e` is
+  spec-bounded to [-100, 100] and `|m| < 2^23`, so the product is exact in float32 and computing it
+  in JS doubles and storing through a `Float32Array` is bit-identical to the reference's
+  build-the-exponent-and-multiply.
+- **Color** (KHR only) — `byte_stride` 4 → `Uint8Array`, 8 → `Uint16Array`. YCoCg:
+
+  ```
+  as = (1 << (msb_32(input[3]) + 1)) - 1
+  r  = input[0] + int(input[1]) - int(input[2])
+  g  = input[0] + int(input[2])
+  b  = input[0] - int(input[1]) - int(input[2])
+  a  = input[3] & (as >> 1);  a = (a << 1) | (a & 1)
+  output = round(component * (UINTN_MAX / as))
+  ```
+
+  ⚠ Components 0 and 3 are **unsigned**, components 1 and 2 are **signed**, in the same element.
+  `msb_32` already returns `-1` for zero, so a malformed `input[3] === 0` yields `as = 0`, an
+  infinite scale, and finite garbage bytes once stored through a `Uint8Array` — defined, ugly, and
+  not worth a guard (§6.9).
+
+## 4. What is reused, and what deliberately is not
+
+### 4.1 Reused
+
+- **`decode_octahedron_to_unit`** (`core/geom/3d/normal/octahedron`) implements filter 1's core.
+  meep's fold is the same arithmetic as the spec's `copysign` form (`x + t·sign(x)` either way) and
+  it renormalises, but it is written **Y-up**: meep's `(x, y, z)` is the spec's `(x, z, y)`. The
+  swizzle is the whole of the adaptation, and a spec checks the composition against the
+  specification's formula directly rather than against meep's.
+- **`msb_32`** (`core/binary`) is `findMSB` for filter 4, `-1`-on-zero included.
+- **`exp2`** and **`copysign`** (`core/math`).
+- **`gltf_test_fixtures.js`** (`engine/asset/loaders`) already builds a one-triangle glTF and GLB by
+  hand; the end-to-end fixture extends it rather than introducing a second fixture vocabulary.
+
+### 4.2 Deliberately not
+
+- **`BinaryBuffer.readUintVar`** is the same LEB128 scheme and reusing it would honour "use meep's
+  existing code". It is still wrong here: it reads through a `DataView` bound to a whole
+  `ArrayBuffer` where the compressed range is a slice, it is unbounded on malformed input where the
+  reference stops at five bytes, and `value |= (b & 0x7f) << shift` turns negative once `shift`
+  reaches 28 — which is inside the range mode 1 and mode 2 indices legitimately use. The deviation
+  and its three reasons are documented where `meshopt_read_uint_var` is defined, so the next reader
+  does not "fix" the duplication.
+- **`quat3_decode_from_uint32`** is a different packing — 10-bit, fixed range, dropped component
+  inserted *at* index `max` — where filter 2 is 16-bit, variable precision and *cyclic*. Documented
+  as deliberately not reused rather than left to look overlooked.
+- **`Vector3` / `Quaternion` / `vec3` helpers.** The filters run over hundreds of thousands of
+  elements through typed-array views; routing each through an object allocation would be the one
+  place in this feature where reuse costs more than it is worth. Scalars, module-static scratch.
+
+## 5. Tests
+
+Every module gets a `.spec.js` beside it. House rules apply: black-box, no mocks, and no rejection
+tests against `assert.*` (stripped in production) — everything that must reject bad *file* input
+does so with a real `throw`, and those are tested.
+
+### 5.1 The independent oracle
+
+The single most valuable test is free: **Appendix A of both specifications contains a worked
+example** of the 4-bit sentinel encoding —
+
+```
+0x17 0x5f 0xf0 0xbc 0x77 0xa9 0x21 0x00 0x34 0xb5
+  ->  -1 -4 -3 26 -91 0 -6 6 -4 -4 5 -5 1 -1 0 0
+```
+
+— which pins the packed-nibble order, the sentinel value, the sentinel run's position and its
+ordering, and the zigzag, all at once, from a document that is not this implementation. It is the
+first test written, and the group decoder is developed against it. (Checked by hand while writing
+this plan: the nibbles are `1 7 5 S S 0 11 12 7 7 10 9 2 1 0 0`, the two sentinels take `0x34` and
+`0xb5`, and de-zigzagging reproduces the stated line exactly.)
+
+### 5.2 Hand-derived vectors
+
+The remaining streams are small enough to author by hand from the spec, with the derivation in the
+test as a comment. Worked out in advance so this plan can be checked before any code exists:
+
+- **mode 0 v0, all-zero groups.** `byte_stride` 4, `count` 3 → one block, one group, four data
+  blocks each a single `0x00` header byte: `[0xa0, 0x00, 0x00, 0x00, 0x00]` then 28 zero bytes then
+  the 4 baseline bytes. All three elements equal the baseline. This is the test that fails if the
+  tail is read from the wrong end (§3.1 ⚠) — under the element-then-padding reading the baseline
+  comes out `0,0,0,0`.
+- **mode 0 v1, control modes.** The same shape with header `0xa1`, one control byte, and one tail
+  channel-mode byte: control mode 2 (nothing stored) on every byte position; then control mode 3
+  (literal) with hand-written delta bytes; then control mode 0 with a 1-bit sentinel group, which
+  is the only place the low-bits-first packing is exercised.
+- **mode 0 v1, channel modes 1 and 2.** `byte_stride` 4, one channel: a 16-bit delta pair that
+  wraps modulo 65536, and a rotated XOR whose `r` is non-zero — the two places where a
+  left-versus-right rotation or a byte-order slip is invisible at `r = 0`.
+- **mode 1, one triangle.** `[0xe1, 0xf0]` + 16 `codeaux` bytes with `codeaux[0] = 0x00` →
+  `feb = fec = 0` → `a, b, c = next++, next++, next++` → `[0, 1, 2]`. 18 bytes, `1 + 6/3 + 16`;
+  `data` lands exactly on `codeaux`.
+- **mode 1, two triangles sharing an edge.** Append code `0x00`: after triangle one the edge FIFO
+  holds `(1,0), (2,1), (0,2)` at offset 3, so `fe = 0` reads `(0, 2)` and `fec = 0` takes
+  `c = next = 3` → `[0, 1, 2, 0, 2, 3]`. This is the test that fails if the edge-FIFO push order is
+  wrong.
+- **mode 1, the `0xXf` and `0xfe`/`0xff` paths** — explicit indices through `decodeIndex`, and the
+  `codeaux == 0` restart that resets `next`.
+- **mode 2.** `[0xd1, 0x14, 0x08, 0, 0, 0, 0]` → `0x14 = 20`: baseline 0, zigzag 10, delta +5 → `5`;
+  `0x08 = 8`: baseline 0, zigzag 4, delta +2 → `7`. Output `[5, 7]`. Plus a vector that alternates
+  the baseline bit, which is the whole reason mode 2 exists.
+- **filters.** Values computed from each spec's own pseudo-code in the test, not from the
+  implementation: unit ±X/±Y/±Z normals through octahedral at both strides, identity and
+  each-of-four-`max_component` quaternions, exponential words with negative exponents, negative
+  mantissas and `m = 0`, and for colour a grey, a saturated primary and a partial alpha at both
+  strides and at a `K` below the component width.
+- **rejection.** Truncated streams, wrong header bytes, a `0xa1` stream offered under the `EXT_`
+  name, a `COLOR` filter under the `EXT_` name, an invalid channel mode byte, and a mode 1 stream
+  whose `data` does not land on `codeaux`.
+
+### 5.3 Round trip
+
+A **test-only** mode 0 encoder in the spec file (raw-byte groups only, the simplest legal encoding)
+gives a randomised round trip over strides 4/8/12/16/64 and counts that straddle the 16-element
+group and 256-element block boundaries. It is deliberately *secondary*: it shares the layout
+assumptions of the decoder, so a shared misreading passes. Its job is exercising the block and group
+loop bounds, not proving the format. §5.1 and §5.2 prove the format.
+
+### 5.4 End to end
+
+`gltf_test_fixtures.js` gains `build_meshopt_triangle_gltf_json(extension_name, buffer_uri, options)`
+and a matching `_glb`: the one-triangle model with its four bufferViews compressed (positions, normals and
+uvs in mode 0, indices in mode 1) by the fixture's own minimal encoder, a `fallback: true`
+placeholder buffer with no URI, and `extensionsUsed` / `extensionsRequired` set. A spec then loads
+it through the real `AssetManager` and `GLTFSceneBundleAssetLoader` — as
+`GLTFSceneBundleAssetLoader.spec.js` already does — under **both** extension names, and asserts the
+resulting bundle's geometry equals the uncompressed fixture's. That covers the fallback-buffer path,
+the bufferView rewrite, and the fact that `load_gltf.js` needs no changes.
+
+That file, though, is one the *vendor* extension could have described just as well — the Khronos name
+on it and nothing else. `options` makes it a file only KHR defines: attribute streams at codec
+version 1 carrying a channel mode each (a rotated exclusive-or over the positions, byte deltas over
+the normals, 16-bit deltas over the texture coordinates), and a `COLOR`-filtered `COLOR_0` the mesh
+reader maps to `StandardAttributes.Color`. Each of the two is served on its own as well as together,
+so that a test watching the vendor extension refuse one is refusing *that* one — asserting against a
+file carrying both passes on either constraint, and then removing one of them from the vendor
+extension goes unnoticed.
+
+### 5.5 What none of this covers
+
+No test here decodes a stream produced by `gltfpack`. Every byte under test was authored from a
+specification by me or by a fixture encoder I also wrote; a misreading shared between them survives.
+§5.1 is the only genuinely external oracle, and it covers one group encoding of one mode.
+
+**Recommendation to the sponsor: drop one `gltfpack -noq -cc` output (and one `-cc -vv` for codec
+version 1) into the repo, and add a golden test that decodes it and checks every `POSITION`
+accessor's values against that accessor's declared `min`/`max`, and every index against the vertex
+count.** Those bounds are written by the encoder, are not derivable from the compressed bytes, and
+would catch a systematic misreading immediately. Left out of this plan because it needs files only
+the sponsor can supply.
+
+## 6. Adversarial review of this plan
+
+Each item is a way this plan is wrong or insufficient, and what it changes.
+
+### 6.1 The tail was read from the wrong end
+
+The first draft of this plan had the baseline element at the **start** of a `max(stride, 32)`-byte
+tail, from EXT's "a baseline element stored verbatim, padded to 32 bytes", and cited a reading of
+the reference decoder that appeared to confirm it. Both were wrong, and for any `byteStride` below
+32 — which is every attribute meshopt is actually used on — it decodes an entire model to garbage
+while every unit test written from the same misreading passes.
+
+What caught it was reading KHR, which reworded the same clause to "Tail padding, which pads the size
+of the *subsequent* tail block…" and added a second item to the tail block that forces the question.
+The corroborating detail is that the reference keeps two quantities, `tail_size` and
+`tail_size_pad`, uses the **unpadded** one to locate the baseline and the **padded** one to validate
+the remainder — a distinction that has no meaning at all under the wrong reading.
+
+**Changes:** §3.1 states both quantities and where each is used; §5.2's first vector is chosen
+specifically to discriminate them; and the general lesson is written into §6.11.
+
+### 6.2 `Uint8Array` out-of-bounds reads return `undefined`, and `undefined & 0xff` is `0`
+
+The worst failure mode in the design. JavaScript does not fault on a typed-array read past the end —
+it yields `undefined`, and every bitwise operator coerces that to `0`. A truncated or malformed
+stream therefore decodes to *plausible-looking zeros* rather than an error, and the model loads
+wrong instead of failing. The reference is bounds-checked at every group and every index read for
+exactly this reason.
+
+**Change:** explicit bounds checks are not optional, and are not `assert` (stripped in production —
+this input is a file, not a caller). Real `throw` at the header, at each byte group against the
+24-byte decode limit, at each literal and control-header read, at each index varint, and at the
+final data-lands-on-the-tail equality in all three modes. Reject-a-truncated-stream cases added to
+§5.2.
+
+### 6.3 Mutating the bufferView descriptors races the image loader
+
+The first draft rewrote `json.bufferViews[i]` in place. `loadFromJson` builds the image promises
+*before* buffers resolve, and each one closes over its `bufferView` object and reads `.byteOffset` /
+`.byteLength` inside a `.then()` that runs *after* the rewrite. Mutating in place changes what an
+already-scheduled image read sees, from a different code path, with no visible link between the two.
+
+**Change:** §2.2 returns a new array of new descriptors and leaves the originals untouched. The
+image path keeps reading exactly what it reads today, whatever order the promises settle in. This is
+the reason for a design choice that otherwise looks like needless allocation, and it is recorded
+where the code lives.
+
+### 6.4 `Math.round` is not the spec's `round`
+
+`Math.round(-2.5)` is `-2`. The filters round signed symmetric quantities and the reference rounds
+half away from zero. Half a quantisation step on normals is invisible in a screenshot and visible in
+a diff against any other decoder — exactly the kind of drift nobody attributes correctly six months
+later.
+
+**Change:** `round_half_away_from_zero` in `core/math`, used by every filter, with the asymmetry
+named in its JSDoc.
+
+### 6.5 A green suite here does not mean a `gltfpack` file loads
+
+Two things sit between this feature and a real compressed asset, and neither is in scope:
+
+- **`KHR_mesh_quantization`.** `gltfpack`'s default output quantises as well as compresses, and meep
+  does not implement that extension. Worse, quantised attributes are padded — a `VEC3`/`SHORT`
+  position gets `byteStride` 8, not 6 — and `load_gltf.js` rejects any bufferView whose `byteStride`
+  differs from `componentSize × componentCount` with `'Interleaved attributes are not supported'`.
+  So a default `gltfpack` file will fail *after* decompressing correctly.
+- **Interleaved attributes**, same rejection, for the same reason.
+
+`gltfpack -noq -cc` produces meshopt-compressed, non-quantised, non-interleaved output, and that is
+the configuration this feature makes work. Stated here rather than discovered later; picking up
+`KHR_mesh_quantization` is separate work and is not silently folded into this one.
+
+### 6.6 Pure JS is roughly an order of magnitude off the reference
+
+The reference reaches ~1 GB/s with WebAssembly SIMD. This will not, and the extension exists partly
+*because* decode is meant to be nearly free. Decompression is synchronous inside `loadFromJson`, so
+it lands on whichever thread is parsing — the main thread for a foreground load.
+
+Accepted, not designed around: the alternative is a WASM dependency, which the brief excludes.
+Mitigated by the shape the reference already uses — a module-static 8 KiB delta scratch (one
+attribute block's worth: `byte_stride × max_block_elements <= 8192` by construction) and a 256-byte
+group buffer, so the strided writes stay in cache and there is no per-block allocation. No
+performance claim is made without a measurement, and none has been taken.
+
+### 6.7 The extension's `count` is not the accessor's `count`
+
+`count` is the number of *stride-sized elements in the bufferView*; for index modes that is the
+index count, not the triangle count. Reading it as either is a silent 3× error that only shows on
+non-triangle-aligned data.
+
+**Change:** each spec's own invariants become the validation list, checked before decode and thrown
+on. Parent `byteLength === byteStride × count`; parent `byteStride`, when present, equals the
+extension's; `ATTRIBUTES` → stride divisible by 4, `>= 4` (KHR) and `<= 256`; `TRIANGLES` → count
+divisible by 3; `TRIANGLES`/`INDICES` → stride 2 or 4 and filter absent or `NONE`; `OCTAHEDRAL` →
+stride 4 or 8; `QUATERNION` → stride 8; `EXPONENTIAL` → stride divisible by 4; `COLOR` → stride 4
+or 8 **and** the KHR name. Plus the source range lying inside the source buffer, which both specs
+leave implicit, and the KHR rule that a bufferView must not carry both extension names.
+
+### 6.8 The fallback buffer is allocated at its declared `byteLength`
+
+Both specs require a placeholder large enough to hold every uncompressed view referencing it — a
+megabyte-scale allocation for a real model, of a buffer that by construction nothing reads once the
+views are rewritten.
+
+**Change:** it resolves to a **zero-length** buffer. A well-formed file never touches it; a
+malformed one — a view referencing the fallback without carrying the extension — fails loudly on an
+out-of-range typed-array construction, which is the correct outcome and is preferable to quietly
+handing out a megabyte of zeros that renders as a degenerate mesh.
+
+### 6.9 Version and name policy has three different answers, and uniformity would be a bug
+
+The temptation is one rule for all three headers. They are not the same:
+
+- Mode 0 version 1 is a *different bitstream*, so decoding `0xa1` as `0xa0` is a silent wrong
+  answer. It is supported, and it is rejected under the `EXT_` name, which does not define it.
+- Mode 1 and mode 2 versions 0 and 1 differ only in `fec_max`, which is read from the header, so
+  both decode correctly and both are accepted under either name.
+- Filter `COLOR` is accepted only under the `KHR_` name.
+
+And two decode-time hazards are left alone on purpose, because the specs declare them unspecified
+and JavaScript's typed arrays already contain the damage: a colour element whose fourth component is
+zero (infinite scale, finite garbage bytes on store) and a quaternion whose retained components
+exceed unit length (already clamped at the radicand). Neither can produce a `NaN` that escapes into
+the scene, and neither gets a guard.
+
+### 6.10 Nothing checks `extensionsRequired`
+
+The loader ignores `extensionsRequired` entirely, so a file requiring an extension meep does not
+implement loads and renders wrong. Pre-existing and out of scope — noted so it is not mistaken for
+something this change introduced or fixed.
+
+### 6.11 The residual risk this plan cannot retire
+
+Three details are taken from questions put to the reference implementation rather than from
+specification text, and one is taken from an inference:
+
+- literal control mode 3 consumes the **group-aligned** element count per byte position, not the
+  block's unaligned count (inferred: all four control modes must agree on the scratch stride);
+- channel mode 2 rotates **left** by `r` on decode;
+- the version 1 tail-padding minimum is 24 bytes, not 32.
+
+Each is a silent-garbage failure if wrong, and none is discriminated by any test in §5 — a fixture
+encoder written from the same understanding agrees with the decoder. They are the specific reason
+§5.5's ask matters: one real `gltfpack -cc -vv` file settles all three at once. Until there is one,
+**version 1 support is implemented and tested but not evidenced**, and this paragraph is the honest
+statement of that.
+
+## 7. Commit sequence
+
+Each commit is independently green (`npm run test` from `H:/git/moh`).
+
+1. `feat(math): rounding that breaks its ties away from zero`
+2. `feat(binary): meshopt's attribute codec, against the bytes the spec itself decodes`
+   — mode 0 version 0, the group and channel decoders, the varint, the two enums, specs.
+3. `feat(binary): the attribute codec's second version, and the channels it decodes through`
+   — mode 0 version 1: control header, control modes, 1-bit groups, channel modes, specs.
+4. `feat(binary): meshopt's two index codecs, and the tail that checks them`
+   — modes 1 and 2, specs.
+5. `feat(binary): four meshopt filters, one of them meep's own octahedron`
+   — filters 1/2/3/4, specs.
+6. `feat(binary): one entry point per compressed buffer view`
+   — `meshopt_decode` dispatch, spec.
+7. `feat(gltf): a compressed buffer view becomes an ordinary one`
+   — the binding module and its validation, under both extension names, spec.
+8. `fix(gltf): a buffer with no URI is a placeholder, not a request`
+   — the tiny-gltf buffer loop, GLB buffers past the chunk.
+9. `feat(gltf): the loader decodes compressed views before an accessor reads one`
+   — the `loadFromJson` call, the compressed-image-view throw, the end-to-end fixture and spec.
+
+## 8. What execution changed
+
+Written after the work landed. The plan above is corrected in place where it was factually wrong
+about the format; everything else is recorded here rather than edited away, because a plan that
+quietly matches its outcome is not evidence of anything.
+
+### 8.1 The plan was wrong about the `0xfe`/`0xff` ordering
+
+§3.2 claimed that computing and explicitly reading each of the three indices in turn "diverges on
+the first triangle that mixes them". It does not. An index in that branch is either fresh — and
+takes a turn at `next` — or explicit, and takes a varint; never both. The two passes are disjoint
+per index, so interleaving them is equivalent.
+
+Found by mutation: rewriting the branch to interleave them left all fifty-four tests green, and the
+question "which test should have caught this?" has the answer "none, because there is nothing to
+catch". What *is* order-dependent is the sequence of the explicit reads, because `last` chains
+through them; a test with a codeaux of `0xff`, where all three indices are explicit, now pins it.
+
+§3.2 also conflated two things about the conditional FIFO push. The *write* at a non-advancing
+offset is unobservable (no well-formed stream reads distance 16). The *non-advance* is very much
+observable, at any distance a later code reaches. Two tests now do.
+
+### 8.2 A specification erratum, in both documents
+
+Of the three worked examples both extensions print for the varint encoding,
+
+```
+0x7f => 0x7f
+0x81 0x04 => 0x201
+0xff 0xa0 0x05 => 0x1fd005
+```
+
+the third is wrong. Those bytes are the LEB128 encoding of `0x1fd005` written back to front; read as
+LEB128 they are `0x1507f`, and `0x1fd005` encodes as `0x85 0xa0 0x7f`. The example only works if the
+groups are read most significant first, which contradicts the example above it, the encoding the
+document names, and the reference implementation.
+
+`meshopt_read_uint_var.spec.js` pins both readings of both byte strings so that nobody later "fixes"
+the reader to match the printed line.
+
+### 8.3 Two things the plan claimed mattered, which cannot be observed
+
+Both were found by mutating the implementation and watching the suite stay green, and both are now
+written down where they live rather than left to look like tested behaviour.
+
+- **§6.4, the rounding mode.** `round_half_away_from_zero` cannot be told from `Math.round` through
+  any of the four filters. A renormalised octahedral component is a ratio with an irrational
+  denominator and never lands halfway between two integers — checked exhaustively over the whole
+  8-bit input space, 8388477 component values, no ties — and the quaternion filter's scale is
+  irrational for the same reason. The colour filter's scale is rational, but its inputs are
+  non-negative for any valid element, and a positive tie rounds the same way either way. The helper
+  is kept because it is what the specifications say; the claim that a test proves it is withdrawn,
+  and a standing sweep now asserts the no-ties property that makes it moot.
+- **§3.4, the quaternion radicand's clamp.** The output goes through an `Int16Array`, and storing a
+  `NaN` there yields the same zero the clamp produces. Kept so the function is total on its own
+  rather than by a coincidence thirty lines downstream — which is exactly the kind of thing a
+  refactor removes — but nothing tests it, and the spec now says so.
+
+### 8.4 Structure
+
+- Planned commits 2 and 3 (attribute codec versions 0 and 1) landed as one. The block loop, the
+  group decoder and the channel reconstruction are shared; splitting them would have meant writing
+  the module twice.
+- The test-only encoder §5.3 put inline in a spec file became `__meshopt_test_streams.js`, because
+  the end-to-end glTF fixtures need the same streams. `**/__**.js` is already how meep's coverage
+  configuration spells "scaffolding".
+- Three test vectors in the first draft were wrong and the implementation was right: a quaternion
+  component stored at full scale is `1/sqrt(2)` and not 1; a quaternion whose four components are
+  equal has its dropped component absorb all three of the others' rounding, so it is up to three and
+  a half quantisation steps out rather than half a step; and a colour alpha of `0x80` is the marker
+  bit over an empty field, which is zero and not one. The bounds are now derived in the test from
+  the quantisation step rather than picked.
+
+### 8.5 The record
+
+Thirty-two mutations were applied to the finished implementation to check the suite says so. Thirty
+failed at least one test. The two that did not are §8.3, and are documented rather than papered over.
+
+`npm run test` from `H:/git/moh` covers all of it; the meshopt package and its glTF binding are 96
+tests across 12 files, plus 7 end-to-end through the real asset framework.
+
+### 8.6 What is still owed
+
+§5.5 and §6.11 stand unchanged, and are the honest limit of this work:
+
+**No test here decodes a stream `gltfpack` produced.** Every byte under test was authored from a
+specification by me, or by a fixture encoder I also wrote. Three details — literal control mode 3's
+element count, channel mode 2's rotation direction, and version 1's 24-byte tail minimum — come from
+questions put to the reference rather than from specification text, and no test discriminates any of
+them.
+
+One `gltfpack -noq -cc` output and one `-cc -vv` output, checked in with a golden test that
+validates every `POSITION` accessor against its own declared `min`/`max` and every index against the
+vertex count, would settle all three at once. Those bounds are written by the encoder and are not
+derivable from the compressed bytes.
+
+Until then: version 0 is corroborated by the specification's own worked example, and **version 1 is
+implemented and tested but not evidenced.**
+
+## 9. The seam this was first built on the wrong side of
+
+The first version put the whole glTF half in one module, `gltf_meshopt_compression.js`, exporting
+`gltf_meshopt_decode_buffer_views(buffer_views, buffers)`. The parser imported that by name and
+called it on every model it loaded.
+
+It worked, and every test above passed against it. It was still the wrong shape, for reasons worth
+writing down because none of them is a bug:
+
+- **The name described the caller's hope, not the function.** A thing called
+  `gltf_meshopt_decode_buffer_views` does not decode bufferViews. It walks all of them, works out
+  which are anybody's, decodes those, and rewrites the array. Three jobs under one codec's name.
+- **Detection was welded to decoding.** The parser assumed meshopt by importing it, and the check
+  that it was meshopt happened *inside*, four frames down. Reading the call site told you nothing
+  about whether a plain glTF paid anything — which is exactly the question it should answer.
+- **The second extension proved the point and the third would have made it.** `KHR_` was bolted on
+  as `if (name === MESHOPT_COMPRESSION_EXT && ...)` inside the decoder. A Draco or a future codec
+  would have been another module the parser imported by name, and another branch.
+
+What replaced it is in §2.2. The parser asks a set what claims a view; the set answers with an
+extension or with nothing; the walk is identical for all of them. `tiny-gltf.js` no longer contains
+the string "meshopt" anywhere, comments included.
+
+Two smaller things went the same way:
+
+- `meshopt_decode`'s mode and filter dispatch were a seven-branch `if / else if` chain. The three
+  modes already share a signature and the filters already share theirs, so both are now arrays
+  indexed by the enum, and "none" is a function that does nothing rather than a branch that asks
+  whether to.
+- The extension validator was fourteen `if (...) throw` in a row, several of them comparing mode and
+  filter names. The specifications state those constraints as a table, so it is a table: what each
+  mode and each filter admits of a stride and a count, with the rule's own wording carried alongside
+  for the message. Eight guards, none of them naming a mode.
+
+Eight mutations were applied to the new seams to check the suite says so — the walker decoding
+unclaimed views, the walker dropping its length backstop, the set taking the first claimant, the set
+forgetting placeholder buffers, meshopt admitting any filter it can name, one version ceiling for
+every mode, and each dispatch table shuffled. All eight fail at least one test.
+
+## Addendum, 2026-08-20: a document's resolved buffers are `Uint8Array`
+
+Written into the plan as `ArrayBuffer`, and changed when the virtual-geometry builder started
+reading containers through the same layer. A buffer is a *range* of bytes: a `.glb`'s binary chunk
+is a range of the file it arrived in, and a buffer read off a filesystem starts wherever the runtime
+put it. Carrying the offset with the bytes is what lets the chunk be handed on without copying a
+model-sized allocation, and `Uint8Array.subarray` is what a decoder's source range wants anyway —
+`MeshoptBufferViewExtension` reads one with `subarray` rather than a three-argument constructor that
+can only be laid over an aligned offset.
+
+`decode()` answers with a `Uint8Array` for the same reason, and the length check over it is
+unchanged.