@woosh/meep-engine 3.14.2 → 3.14.4

package/src/shade/renderer/texture/COMPRESSED_TEXTURE_PLAN_2026_09_01.md

@@ -1,6 +1,6 @@
 # Block-compressed textures — implementation plan
 
-**Status:** proposal — revision 5
+**Status:** proposal — revision 6
 **Date:** 2026-09-01
 **Author:** Alex Goldring / Company Named Limited
 **Scope:** `src/shade/renderer/texture/`, `src/shade/descriptor/texture/format/`,
@@ -30,6 +30,11 @@
 > memoised (§11.2), `alpha_mode` needed a third state or it would premultiply every data texture
 > (§11.3), the uploader could not see the flag it was told to honour (§11.4), per-format resolution
 > needs a manifest (§11.5), plus corrections of fact (§11.6). §0's central move survived all six.
+>
+> **Revision 6** adds step 11, the GPU block encoder of §4.5 (§9.20), and corrects §4.4's item 2: a
+> copy of a block-compressed level is sized in whole blocks against its physical extent, which the
+> first real `copyBufferToTexture` found and which `texture_write_level` had been getting wrong on
+> hardware since step 3.
 
 Assumes the payload is already an `ArrayBuffer` in JS memory. Fetching is not discussed, except in
 §5, where *which* bytes to fetch is the whole point.
@@ -139,7 +144,7 @@ shade/device/mock/
 
 Container readers (KTX2, DDS, whatever ships next) are **not** engine code in this list: each is a
 free function `bytes -> ShadeTexelData` living with its container, the way
-[`GltfBufferViewExtension`](../loader/gltf/ext/GltfBufferViewExtension.js) keeps meshopt out of the
+[`GltfBufferViewExtension`](../../../format/scene/gltf/ext/GltfBufferViewExtension.js) keeps meshopt out of the
 glTF parser. The engine names no container. Transcoders (§4) are likewise their own tree.
 
 ### 2.1 `TextureFormat` — and the load-time globals underneath it
@@ -560,6 +565,12 @@ compressed: an uncompressed procedural texture takes the same route.
 
 ### 4.5 Runtime compression, later
 
+> **Landed 2026-09-02, as step 11** — [`texture_encode`](encode/texture_encode.js), with BC4 as the
+> first encoder and the rest refused by name; see §9.20 and
+> [`encode/ENCODE_NOTES_2026_09_02.md`](encode/ENCODE_NOTES_2026_09_02.md). Everything below held,
+> with one correction: the copy extent for a partial mip is the level's *physical* size, rounded up to
+> whole blocks, not its logical one.
+
 Not being built now. Recorded because the seam either admits it or does not, and it costs nothing to
 make sure it does.
 
@@ -808,7 +819,7 @@ right granularity for that.
 - **On-GPU BC/ASTC encoders** — the shader behind §4.5.
 - **The offline encoder.** First-party content has to be compressed by something, and that something
   is a tool, not the engine. It belongs beside the AVIF encoder
-  ([`avif/threaded_image_encoder.js`](../../../avif/threaded_image_encoder.js)), reusing its worker
+  ([`avif/threaded_image_encoder.js`](../../../engine/asset/loaders/image/avif/threaded_image_encoder.js)), reusing its worker
   pool. Mips are generated *before* compression, from the source texels, with the same filters
   [`mipmaps/filters/`](mipmaps/filters) uses — compressing level 0 and decompressing it to build
   level 1 is how a pyramid rots.
@@ -830,9 +841,17 @@ Each step is independently committable and leaves the engine working.
 | 5 | **Landed.** `writeTexture` delegates to `texture_copy` (§6.3, §9.6). A BC7 texture now goes end to end with no GPU. | test tier only |
 | 6 | **Landed.** Device features, `gpu_texture_compression_support`, `TextureRole`, `texture_format_preference`; §6.2 and §6.4 guards (§3.5, §9.7) | none until a compressed texture exists |
 | 7 | **Landed.** `TextureVariantSet` (the manifest) and `texture_variant_select`; **not** in `AssetManager` (§5.1, §9.9) | additive — an unbuilt format falls through to the fallback, and nothing consumes this until step 8 |
-| 8 | **Landed.** KTX2 reader in [`src/ktx2/`](../../../ktx2/ktx2_read.js) — container to `ShadeTexelData`, for files already in a device format; ZLIB supercompression read rather than refused (§9.10) | additive — nothing imports it yet, and nothing existing changed except the cursor it reuses |
-| 9 | CPU Basis transcoder (§4.3), then `KHR_texture_basisu` | the expensive one. Sequenced last deliberately. |
-| 10 | GPU transcoder (§4.4) — the engine's first `copyBufferToTexture` | an optimization of step 9, not a prerequisite |
+| 8 | **Landed.** KTX2 reader in [`src/ktx2/`](../../../format/texture/ktx2/ktx2_read.js) — container to `ShadeTexelData`, for files already in a device format; ZLIB supercompression read rather than refused (§9.10) | additive — nothing imports it yet, and nothing existing changed except the cursor it reuses |
+| 9 | **Landed.** CPU Basis transcoder in [`src/basis/`](../../../format/texture/basis/transcode_basis.js) — ETC1S to BC7 and BC1, implemented from the specification; `ktx2_read` accepts BasisLZ; `KHR_texture_basisu` read at both glTF sites (§4.3, §9.11) | the expensive one, and sequenced last deliberately |
+| 9b | **Landed.** UASTC to BC7 and BC5 — the other Basis encoding, and the one normal maps use; every UASTC mode carried into the BC7 mode the specification pairs it with, partitions included; the glTF loader picks a target from the material slot, so a normal map reaches BC5; Zstandard read from RFC 8878, which is what real UASTC is wrapped in (§9.12) | additive, and within a few tenths of a decibel of the reference transcoder on every fixture |
+| 9c | **Landed.** [`playground/basis_textures`](../../playground/basis_textures/README.md) — tier 8, and the first GPU to see any of this. Sponza at **4.00x** less texture memory, 69/69 textures accepted. Found the `GenerateMipMaps` refusal and the cumulative-total misreading (§9.13) | fixes one real defect in `load_gltf`; the playground itself is additive |
+| 9d | **Landed.** `rgba8unorm` from both transcoders, and the glTF loader falls to it when the device can sample no compressed target — closing §9.13's refusal. ETC1S's uncompressed output is byte-exact against the reference (§9.15) | removes a refusal; costs 4x the memory, and only where there was no texture before |
+| 9e | **Landed.** ETC1S to ETC2, byte-exact against the reference; EAC alpha fitted. `ktx2_read` takes an ordered target list so alpha can decide. **ASTC written and removed** — the layout was derived but the interpolation could not be verified and no ASTC device was reachable (§9.16) | additive; the target-list change also fixes a live BC1 hazard |
+| 9f | **Landed.** ETC1S to ASTC 4x4, from the specification: exact interpolation, the CEM 8 endpoint ordering rule, placement search and endpoint refinement. **48.81 dB against the reference's 48.28** (§9.17), and §9.16's removal is retracted | additive; ASTC leads every role's preference where the device has it |
+| 9g | **Landed.** The ordered target list falls through on *encoding* as well as alpha — an ASTC-first device went from 24 failures on Sponza to none. **UASTC to ASTC measured and declined**: 34.9 dB on real normal maps against an exact floor (§9.18) | bug fix; the decline leaves UASTC on the floor where it already was |
+| 9h | **Landed.** UASTC to ASTC by repack — partition seeds searched, trit/quint packings inverted from the spec's decode, block modes assembled from the layout. Byte-identical to the reference on 2320 of 2352 blocks and provably equivalent on the rest. **Mobile reaches desktop parity: 173.1 -> 83.8 MiB** (§9.19) | additive; closes the last gap for third-party UASTC content |
+| 10 | GPU transcoder (§4.4) — Basis payload to BC on the device | an optimization of step 9, not a prerequisite |
+| 11 | **Landed, in part.** GPU block encoder (§4.5) — any sampleable texture to a named block format, on the device: the framework, the padded layout, the per-level copies, the format registry and the test harness, carried by `bc4-r-unorm`, then `bc5-rg-unorm`, `bc1-rgba-unorm`, `bc7-rgba-unorm` in mode 6, the two signed formats, `bc6h-rgb-ufloat` in mode 11 and `astc-4x4-unorm` in the one-partition block of step 9f; the engine's first real `copyBufferToTexture`. Found `texture_write_level` refusing every BC chain's tail on hardware since step 3, and fixed it (§9.20) | additive; `astc-6x6` and `astc-8x8` are refused by name until each lands |
 
 Steps 1–6 introduce **no new capability and no new branch** — they are the refactor that makes
 everything after them a data change rather than a second code path. If the project stops after step
@@ -881,9 +900,868 @@ recompute it.
 had no `mipLevelCount` or `dimension`; every real one has both, and the primitive reads them. The
 fake was wrong, not the test.
 
+### 9.20 The GPU block encoder, and what the first real `copyBufferToTexture` found
+
+§4.5 said runtime compression was "the same shape as §4.4 with a different shader" and that
+everything in §4.4's numbered list applied unchanged. It is, and it did — with one item of that list
+wrong in a way only a device could show, and one older step wrong the same way.
+
+**What landed.** [`texture_encode`](encode/texture_encode.js): a sampleable texture in, a
+block-compressed texture out, the target named by the caller and nothing else known — not the role,
+not the preference list, not the material. One compute dispatch over every level of the chain, one
+`copyBufferToTexture` per level, the block buffer laid out with 256-byte rows by
+[`texture_encode_layout`](encode/texture_encode_layout.js) before anything runs. The shader carries no
+immediates and no uniforms: a flat level table in a storage buffer is the whole of its parameters,
+which is what lets one dispatch cover a chain and what lets it run on a browser build with no
+immediate data. Fifteen targets are listed; `bc4-r-unorm` is implemented and the other fourteen are
+refused by name, each as "planned, not implemented" rather than approximated by a neighbour.
+
+**The encoder** is a fixed budget: extremes, two rounds of least squares, then a five-by-five search
+of integer endpoint pairs at spacings of eight, two and one, in both of BC4's palette modes with the
+six-value line seeded over the interior texels alone. Measured in the emulator against an exhaustive
+search over every endpoint pair, it is within 0.5 dB on every fixture; the least-squares answer alone
+was 3 dB short on the mask fixture, because the optimum sits in a basin no rounding of the
+least-squares line reaches. The reading behind those choices, source by source, is in
+[`encode/ENCODE_NOTES_2026_09_02.md`](encode/ENCODE_NOTES_2026_09_02.md).
+
+**§4.4's item 2 was wrong.** "Origin and extent must be block multiples — trivially satisfied for a
+whole-level copy, since the physical extent of a mip is its size rounded up to whole blocks." The
+first half is right and the conclusion did not follow from it: a whole-level copy at the level's
+*logical* size is not a block multiple for the 2×2 and 1×1 tail, and Dawn refuses it —
+`copySize.width (2) is not a multiple of compressed texture format block width (4)`. The copy is
+sized in whole blocks against the physical mip size, which
+[`gpu_texture_format_physical_size`](../../descriptor/texture/format/gpu_texture_format_info.js) now
+states in one place. The software device had implemented Vulkan's allowance instead — a partial
+extent is fine where it reaches the edge — and so could not have caught it; it now implements
+WebGPU's rule, refuses a compressed texture whose base size is not whole blocks, requires the
+compression feature a block format needs, and validates a copy's row stride, offset and view formats.
+
+**Which means step 3 had been failing on hardware all along.** `texture_write_level` wrote every
+level at its logical extent, so `writeTexture` of a BC chain's last two levels was refused on every
+device — silently, since a validation error does not throw, and §9.13's "69 of 69 accepted" counted
+exceptions. Its spec asserted `[1, 1, 1]` for the 1×1 mip of a BC7 texture and passed. Fixed: the
+extent is the physical size, the spec asserts `[4, 4, 1]`, and the stricter software device would
+fail the old code.
+
+**What the device said about the picture.** 2048² with twelve levels, 349,527 blocks, in 8.6 ms
+wall from record to done; every level's blocks read back from the texture identical to the buffer;
+the device choosing the same block as the f64 emulator on 83% of blocks and a block of equal error on
+almost all the rest. And the hardware's BC4 decoder, read at full precision over every endpoint pair,
+is not the specification's arithmetic: a palette entry is `A + (B − A) · c / 257` over 16-bit
+endpoints with `c = 36, 72, 113, 144, 185, 221` for the eight-value mode and `48, 96, 161, 209` for
+the six — within a level of the CPU decoder on 85% of entries and up to seven off on the widest
+six-value spans, which on real content is 0.6 dB between what the specification decoder predicts and
+what the GPU shows. The encoder keeps fitting against the specification's palette: a vendor's weights
+would be wrong on the next vendor.
+
+**Then BC5 and BC1.** BC5 is the BC4 chunk twice, red then green, and the kernel spec holds it to
+exactly that: each level's blocks must equal the BC4 encoder over the red channel followed by the
+BC4 encoder over the green, block for block. BC1 is the RGB line fit BC7 builds on — principal axis
+by power iteration from the box diagonal, least squares with the thirds shared across channels,
+5:6:5 quantisation and coordinate descent against the decoder's truncated palette, with a flat
+block's stored pair searched per channel for the one-third mix nearest its colour. Measured in the
+emulator: 40.3 dB on a correlated colour fixture and 30.6 on three unrelated channels, against 25.3
+and 24.3 for the 2007 inset bounding box; BC5 38.0 dB on a rough heightfield's normal map. On the
+device: BC1 41.5 dB on the correlated source with the hardware decode within 0.02 dB of the CPU
+decoder's, BC5 45.2 dB, both texture-equals-buffer on every level, and the device choosing the
+emulator's BC1 block on 16,380 of 16,384. One thing the emulator taught: it aliases a vector on
+assignment, so writing one component of a copy changed the original and broke both BC1 searches
+silently; the chunk now builds the altered vector through `select`, which means the same on both.
+
+**Then BC7, mode 6.** The same fit in four dimensions with sixteen points on the line and
+eight-bit ends: the parity bit each end carries is chosen by rounding to all four combinations and
+scoring each against the decoder's own palette, and the anchor is honoured by writing a block the
+other way up when texel 0 lands in the upper half. The pack is held byte for byte against
+`bc7_write_block`, the writer the transcoders use. 44.9 dB on correlated colour in the emulator,
+3.6 dB over BC1 on the channels they share; and on the device the cleanest result of the day — the
+hardware decode identical to the CPU decoder on every sample of every level, because BC7's
+interpolation is fully specified where BC4's is not. 46.0 dB at 512², 8.2 ms for a 2048² chain.
+Mode 6 alone; the partitioned modes are where the rest of BC7's quality is, and a mode search is a
+separate chunk for a later day.
+
+**Then the signed formats**, which the brief called a path and not a tag, and which turned out to
+be a domain: the BC4 fit takes its bounds as arguments and the signed entry point calls it over
+`[-127, 127]` with the six-value mode's hard entries at the extremes, the pack taking the two's
+complement. Two shaders, no new fitting code. On the device, a normal map as signed bytes encodes
+to `bc5-rg-snorm` at exactly the unsigned figure less the 6.02 dB a halved peak costs, which is
+what "the same fit" has to come out as.
+
+**Then BC6H, mode 11.** The same line fitted in the half-float bit domain, because that is where
+the format's decoder interpolates: an endpoint is a half's bit pattern quantised to ten bits, and
+the palette is linear in bit patterns — a log-like scale, so the error the fit minimises is a
+relative one. 45.1 dB over half bits and 0.078 stops RMS log error on an HDR fixture spanning
+fourteen stops with a sun; on the device the hardware decode identical to the CPU decoder on every
+sample of every level, which the format requires of a decoder and this was the first chance to see.
+Mode 11 alone: a block holding the sun and its surround wants the two-region modes.
+
+**Then ASTC 4×4**, in the one corner of the format §9.17 derived and §9.19 repacked into: block
+mode `0x53`, one partition, colour endpoint mode 8, eight-bit ends and three-bit weights — the BC1
+line under ASTC's own interpolation and its endpoint-order rule, both of which cost a level if
+ignored and both of which those steps already had in JavaScript. 43.3 dB on correlated colour in
+the emulator, between BC1 and BC7 mode 6 as eight levels over eight-bit ends should be. Not seen on
+hardware: nothing in reach samples ASTC, and the section says so rather than implying otherwise.
+The 6×6 and 8×8 footprints wait on block modes and partition seeds the tree does not hold.
+
+**Testing, and the discipline §9.11 set.** The block layout is written twice, in JavaScript under
+`format/texture/bc/` — which the UASTC→BC5 and ETC1S→BC1 transcoders now pack through — and in
+WGSL, and the emulator specs require the same bytes from both five hundred times over. The kernel's per-level
+output must equal the encoder run directly over each level's image, byte for byte. Quality floors are
+in the spec, from measurement: 51.5, 42 and 54 dB on the three fixtures, and the fit must strictly
+beat the bounding line it starts from, which is the guard against the refinement's absence. On the
+software device the copies execute over host-written bytes, so the padded layout landing as tight
+rows in the right mip is asserted without a shader. Full suite: 15,583 passed.
+
+### 9.19 UASTC to ASTC, repacked — mobile reaches parity
+
+§9.18 declined a *re-encode* at 34.9 dB and costed the repack. This is the repack, and it lands where
+the format intended: **mobile now costs exactly what desktop costs**.
+
+| Sponza | before | after |
+|---|---|---|
+| desktop (BC) | 83.8 MiB | 83.8 MiB |
+| mobile (ASTC + ETC2, no BC) | 173.1 MiB | **83.8 MiB** |
+
+The 24 UASTC normal maps that were falling to the uncompressed floor are now `astc-4x4-unorm`, and
+the scene is 66 ASTC plus 3 ETC2 for the textures with alpha.
+
+**Nothing is fitted and nothing is lost.** UASTC's fields *are* ASTC's fields — endpoints already
+quantized at a range ASTC names, weights already ASTC weights, patterns taken from ASTC's own hash.
+The work is arithmetic on bit positions: ASTC interleaves its integer sequences where UASTC keeps
+them in two plain runs, and puts its weights at the top of the block in reverse.
+
+**Verified by byte equality with the reference transcoder, which a re-encode could never be.**
+
+| fixture | identical | equivalent | different |
+|---|---|---|---|
+| `uastc_gradient_64x64` | 256 | 0 | 0 |
+| `uastc_partitions_32x24` | 48 | 0 | 0 |
+| `uastc_subsets_128x128` | 1016 | 8 | 0 |
+| `uastc_zoo_128x128` | 1000 | 24 | 0 |
+
+"Equivalent" is not a hedge. ASTC's integer sequence encoding is *redundant* — 256 packed trit groups
+carry 243 tuples and 128 quint groups carry 125 — so two correct encoders can differ bit for bit. The
+32 such blocks are required to decode to identical endpoint values, and do; the spec reads both
+sequences back rather than accepting the difference.
+
+**Three things were derived rather than copied**, and each is checked by its own failure mode:
+
+- **The partition seeds.** ASTC computes patterns from a ten-bit seed through a hash rather than
+  storing them, so UASTC's pattern indices have to be matched to seeds. The reference has that table;
+  this searches all 1024 seeds for one whose grouping agrees texel for texel. All 60 patterns across
+  the three tables resolve — which a wrong hash could not do — and dropping the small-block coordinate
+  doubling fails five tests.
+- **The trit and quint packings.** The specification gives the decode only, saying outright that
+  encoding is the implementation's business. So the decode is written and inverted by enumeration:
+  256 groups yield exactly 243 distinct trit tuples and 128 yield exactly 125 quint tuples, which is
+  the check that the decode is right.
+- **The block modes.** Assembled from the layout — `D` at bit 10, `H` at 9, height at 8:7, width at
+  6:5, `R0` at 4, `R2` and `R1` at 1:0 — rather than tabulated. Swapping `R1` and `R2` fails four
+  tests.
+
+**Two rules with no flag, both caught by the byte comparison.** Endpoint modes 8 and 12 swap their
+pair and blue-contract when the second endpoint's channel sum falls below the first's, and UASTC
+orders its endpoints for BC7's rules instead — so a subset that would trip it has its pair exchanged
+and its weights inverted, which is the same block the other way up. And a void-extent block's bits 10
+and 11 are reserved and set; leaving them clear produced solid blocks that differed from the
+reference in nothing else.
+
+**One thing that cannot be tested and is kept anyway.** A seed found by search need only *group* the
+texels as UASTC does; which group it calls subset 0 is the hash's business, and an encoder would in
+general have to reorder its endpoint pairs. No UASTC pattern actually needs it — all 60 come back as
+the identity, which follows from UASTC having taken its patterns from ASTC. Rather than carry
+reordering code that never runs and therefore is never right, the identity is asserted and a
+violation refused. Removing that assertion fails nothing, and the file says so.
+
+**Still not written:** ETC2 from UASTC. An ETC2-capable device without ASTC would take the floor for
+UASTC content — a population the availability figures suggest is close to empty, since the two
+features report 29% and 30% with identical per-browser splits.
+
+#### What the adversarial pass over §9.19 found
+
+**Five of nineteen modes were never decoded by any fixture** — 5, 10, 15, 16 and 18. Everything the
+repack claims is per-mode, so those were untested bit layouts that happened to compile. Mode 18 was
+the one that mattered: the only user of the 32-level weight range *and* the 32-level endpoint range,
+and the tightest budget of any mode at 127 bits of 128.
+
+Three fixtures were built to reach them, by giving `basisu` content shaped for the modes rather than
+for the eye: a luminance ramp with noise (15), a high-precision colour and alpha field (5, 10), and a
+single long smooth ramp at encoder level 4 (18). Coverage is now 18 of 19, and misreading mode 18's
+weight range now fails a test where it used to pass. **Mode 16 — two-subset luminance — remains
+unreached**: pure greyscale with a hard split inside every block, at every encoder level, produced
+single-subset modes every time. That is asserted as a known gap rather than left implicit, so a
+future fixture that happens to contain it will fail and shorten the list.
+
+**A bit-budget scare that turned out to be sound.** Counting header, endpoints and weights suggested
+five modes overrun 128 bits — and four of those are in the fixtures and match the reference byte for
+byte. The size arithmetic was wrong, not the encoder: ASTC charges a partial trailing group only the
+bits it needs, where the naive count charges a whole one. The writer pads such a group with zeros and
+formally advances its cursor past where the weights begin, which raised the real question of whether
+a padded group's high bits could ever land in the weight field. Swept exhaustively over every mode
+and every value of every trailing group: they cannot, because zero digits give zero high bits. The
+unused size helper that started the scare is gone, with a note where it stood.
+
+**Two pieces of dead logic removed.** The seed-table choice carried a `pat_bits === 4` branch and a
+repeated `subsets === 3` test, neither of which can be true where they were tested — no two-subset
+mode has four pattern bits. And the literal `7` selecting mode 7's borrowed pattern table is now the
+named constant the decoder already had.
+
+Checked and found sound: `partition` is a full sixteen-entry array of zeros for single-subset blocks,
+so the per-subset weight inversion does reach them.
+
+
+### 9.18 The list did not fall through, and UASTC to ASTC does not pay
+
+Two findings from taking every Sponza texture through an ASTC-first preference, which is what a
+modern phone would ask for.
+
+**A bug §9.16's list resolution introduced.** Handing `ktx2_read` an ordered list was meant to stop a
+target being committed to and then refused. It only ever filtered on *alpha*, and returned the head
+of the list unchanged for UASTC — so a list headed by `astc-4x4-unorm` threw on all 24 of Sponza's
+normal maps, because ASTC is a format ETC1S reaches and UASTC does not. The comment even said so:
+"UASTC carries its alpha in the block ... so its first choice always stands". It does not stand when
+the first choice is a format that encoding cannot write at all.
+
+The resolution now filters on both, against the writing transcoder's own format list. The ASTC-first
+run goes from 24 failures to none: **42 ASTC, 3 ETC2 for the alpha textures, 24 falling to the
+uncompressed floor**.
+
+**Why those 24 stay on the floor: UASTC to ASTC was written, measured, and not shipped.** Not for the
+reasons §9.16 gave — this time the measurement is sound and it says the approach is wrong.
+
+Decoding a UASTC block to texels and fitting one ASTC partition to them gives, over Sponza's 24
+normal maps, **34.9 dB mean with a worst channel error of 140**. That is not a fitting failure. The
+adversarial block is legible: a 4x4 where red and blue vary along x while green varies along y — two
+independent gradients, which a single pair of endpoints and one weight plane cannot represent at any
+precision. Normal maps are made of exactly that, which is why `texture_format_preference` leads with
+`bc5-rg-unorm` for the role and why UASTC itself spends dual-plane and multi-subset modes on 46% of
+the blocks in the zoo fixture.
+
+So the trade on offer was a quarter of the memory for a visibly wrong normal, against an uncompressed
+floor that is exact. Taken on those terms it is a regression, and the floor wins.
+
+**What the real path costs.** UASTC's modes were laid out to map onto ASTC's, endpoints and weights
+already in ASTC's quantized space — a repack that loses nothing. Reaching it needs three things this
+tree does not have: the full block-mode table rather than the two single-plane 4x4 rows in
+`astc_block.js`, integer sequence encoding for endpoints and weights at trit and quint ranges, and
+ASTC's partition-seed function. Dual plane alone would fix the block above, and does not fit at eight
+bits an endpoint: 64 weight bits and two selector bits leave 45, so it needs the endpoint
+quantization too. That is the next piece of work, and it is a real one.
+
+**What did land:** `astc_block.js`, holding the block mode derivation, the weight unquantization, the
+mode 8 endpoint ordering rule and the writer, shared by whatever encodes into it.
+
+### 9.17 ASTC, finished — and what §9.16 got wrong
+
+§9.16 pulled ASTC on the grounds that its decode could not be verified. **That conclusion was
+wrong, and wrong in a way worth recording.**
+
+The measurement it rested on was this: decoding `basisu`'s own ASTC blocks and comparing against the
+ETC1S texels gave 748 exact, 1938 off by one, and a tail to five. That was read as *this decoder is
+inaccurate*. It is not what the number says. Those are the reference encoder's blocks and its
+endpoint choices, so the gap is **`basisu`'s ASTC encoding loss against the ETC1S source** — the
+lossy step everyone expects, attributed to the wrong side. The right control was never run: compare
+the two decode formulas against *each other* on the same blocks. They disagree on 160 samples of
+2928, all by one level. That is what a wrong interpolation model looks like, and five is not it.
+
+With the specification in hand the remaining pieces were small.
+
+**The interpolation is not the direct form.** ASTC widens each 8-bit endpoint to sixteen bits by
+replication, interpolates there with a `+32` round, and takes the top eight bits —
+`((c << 8 | c) * (64 - w) + ... + 32) / 64 >> 8`. Against `c0 + (c1 - c0) * w / 64` that is one texel
+in twenty, always by a level. Both the encoder's scoring and the test decoder now use the real one;
+fitting against one and decoding with the other would have put that disagreement into the output for
+nothing.
+
+**Colour endpoint mode 8 has a rule about which way round the endpoints go.** With the second
+endpoint's channel sum below the first's, a decoder *swaps them and blue-contracts both* —
+`r = (r + b) >> 1`, `g = (g + b) >> 1`. That is a different picture rather than an inverted one, and
+no bit in the block records that it happened. §9.16 suspected this from the evidence that `basisu`
+never emits such a block in 61 tries, and was right to. `order_endpoints` now guarantees it, swapping
+the pair and inverting the weight levels, which leaves the decoded block identical where it does
+nothing.
+
+**The block mode was already right.** `0x42` is the low-precision row `D H 0 B A R0 0 0 R2 R1` with
+`A = B = 2` for a 4x4 grid and `R = 4` for four weight levels on one plane — derived empirically in
+§9.16, confirmed against the layout table here.
+
+**Quality, measured against the reference on both axes.** Over the 61 blocks `basisu` also writes
+single-plane it reaches 48.28 dB with a worst channel error of 4. This reaches **48.81 dB over all
+64**, with a worst of 5. Better on the whole and marginally worse at the peak, and the reason is
+visible in one block: block 12, where both encoders pick identical weights and the endpoints differ
+by two in one channel. This pair has the lower summed squared error and the reference's has the lower
+maximum. Least squares is what the fit optimises and what PSNR rewards, so the trade is deliberate.
+`etc1s_antidiag_64x64` comes back exact.
+
+Two things earn that: the placement search from §9.16 — spreading a block's *used* selectors over all
+four weight levels rather than mapping them one to one, worth nine decibels — and a bounded
+refinement of the winning placement's endpoints, since the rounded least-squares pair is usually but
+not always the best integer pair once `interpolate`'s own rounding is applied.
+
+**Still not written:** ETC2 and ASTC from UASTC. A UASTC normal map on a device with neither BC nor
+ASTC still falls to the uncompressed floor.
+
+**The lesson, which is §9.11's again.** A number that looks like evidence of a bug in your own code
+is worth attributing before acting on it. The control that would have settled it — the two formulas
+against each other — costs nothing and was not run, and the cost of not running it was deleting a
+working encoder.
+
+### 9.16 ETC2 landed; ASTC was written, could not be verified, and was removed
+
+Asked for both. One shipped.
+
+**ETC2 is a repack, and is checked byte for byte.** ETC1S is a constrained ETC1 and ETC1 is a subset
+of ETC2, so a Basis block is ETC1's differential mode with both subblocks given the same colour:
+deltas zero, both table codewords the block's intensity. Nothing is fitted and nothing is lost. All
+64 blocks of the noise fixture come out identical to `basisu -unpack`'s own ETC1 output, and the
+RGBA8 spelling matches its ETC2_RGBA byte for byte too. Eight bits a texel against the uncompressed
+floor's thirty-two, at no cost in quality at all.
+
+Two things that were not free:
+
+- **The selector remap.** `INTENSITY_MODIFIER` is ordered darkest to brightest and ETC1 indexes the
+  same four modifiers as `+a, +b, -a, -b`, so a selector written through unchanged mirrors every
+  block through its own mid-grey. `[3, 2, 0, 1]`.
+- **EAC's alpha block**, the only encoded part. A payload with no alpha slice is written exactly
+  opaque through table row 13, the one row containing a zero modifier — an opaque texture has to come
+  back 255 and not 254, and `basisu` uses the same trick, which is why those blocks match bit for bit.
+  A real alpha slice is fitted by searching all sixteen rows against sixteen multipliers, landing at
+  54.4 dB with a worst error of 1 against the payload's own alpha.
+
+**The bug the opaque fixture hid.** EAC numbers its texels down each column like ETC1, and the first
+version wrote them in raster order. A constant block takes the exact path and never touches the
+fitter, so every opaque fixture agreed with the reference perfectly while every non-constant block was
+transposed — worth ten levels. The mutation pass caught it a second time after the fix, because the
+only ETC2 RGBA test at that point still used an opaque fixture; a test over the alpha fixture is what
+now holds it.
+
+**ASTC: written, measured, and taken back out.** The block layout was derived empirically from the
+reference transcoder rather than from the specification's mode tables — block mode `0x42`, one
+partition, colour endpoint mode 8, six eight-bit endpoints at bit 17, thirty-two weight bits at the
+top of the block with the field's bit order mirrored. That much is real: decoding `basisu`'s own
+blocks with it reproduces the ETC1S texels. An encoder on top of it reached 47.6 dB with a
+placement search over which weight levels a block's used selectors take.
+
+It was removed anyway, for two reasons that together make it unverifiable here:
+
+1. **The interpolation model is wrong by up to five levels.** Reading the reference's blocks back
+   gives 748 texels exact, 1938 off by one, and a tail to five. Whatever hardware does with the
+   endpoints — expansions and shifts at some width — is not the weighted average this computes, and
+   the encoder was fitting against the same approximation, so the error on a real device is unknown
+   rather than bounded.
+2. **CEM 8 appears to carry an endpoint-swap rule this does not implement.** Across 61 reference
+   blocks, `basisu` never once emits endpoints whose first sum exceeds the second — exactly what a
+   swap-and-blue-contract rule would punish. This encoder could emit such a block, and the result
+   would be wrong colours rather than slightly wrong ones.
+
+No ASTC hardware was reachable to test on: the device here reports fourteen compressed formats, all
+BC. Shipping a colour path to every iOS device that could not be checked, on a format where the
+failure mode is "wrong colours, silently", is worse than not shipping it. What would unblock it is
+the ASTC specification's Table C.2.8, its endpoint unquantization, and the CEM 8 rule — or an ASTC
+decoder from real tooling to test against, which is the same standard every other transcoder here was
+held to.
+
+**A hazard ASTC surfaced, which was kept.** ASTC cannot hold an ETC1S payload's alpha — the colour
+and alpha slices have their own selectors, and the dual-plane block mode that would separate them
+cannot also hold eight endpoints and thirty-two weight bits in 128 bits. Being first in every colour
+role's preference, it would have been committed to and then refused, after the point where another
+format could still have been chosen. The same hazard was already live for BC1.
+
+The fix outlives ASTC: `ktx2_read` now accepts an **ordered list** of acceptable targets and picks
+from it, because the container's descriptor is the only thing that knows whether the file carries
+alpha, and the caller is the only thing that knows what the device can sample. The loader hands over
+its whole preference order ending in the uncompressed floor. `transcode_basis_carries_alpha` is what
+the reader asks.
+
+**Still not written:** ASTC, and both ETC2 and ASTC from UASTC. A UASTC normal map on a device with
+neither BC nor a verified ASTC path falls to the uncompressed floor, which costs memory rather than
+correctness.
+
+### 9.15 The uncompressed target, and the end of the "no BC" refusal
+
+§9.13 recorded a gap: a device advertising no compressed format got a named refusal rather than a
+picture. That is now closed. `transcode_basis` and `transcode_uastc` both write `rgba8unorm`, and the
+glTF loader falls to it when the device can sample none of the compressed targets.
+
+**Why it had to exist.** Every compressed format in WebGPU is an optional feature —
+`texture-compression-bc`, `-etc2` and `-astc` alike — so a device exposing none of them is legal, and
+so is one exposing only the family this transcoder does not write. `rgba8unorm` is mandatory. Four
+bytes a texel against BC7's one is a poor outcome and no texture at all is a worse one.
+
+Measured on the same scene, forcing the support set empty: 69 textures at **335.3 MiB**, which is
+exactly what the JPEG path costs, split `rgba8unorm-srgb` for the 25 albedo maps and `rgba8unorm` for
+the other 44 — the same sRGB split §9.14 fixed, arrived at through a different branch. It also loads
+in 11.4 s against the compressed path's ~19 s, because the BC re-encode is the expensive half and
+this skips it.
+
+**The ETC1S path is byte-exact and the specs say so.** Every other target re-encodes the decoded
+texels and is therefore compared against a PSNR bound; `rgba8unorm` *is* the decode and nothing more,
+so it must equal the reference transcoder's own texels exactly. It does, across four fixtures and
+seven mip levels. That makes it the strictest check in the file, and it is only possible because
+there is no lossy step to hide behind. UASTC is bounded instead, against the reference's BC7, since
+the reference publishes no uncompressed output to compare with — what that bound really tests is
+arrangement rather than fidelity, because a row-order or crop error moves every texel at once.
+
+Against the source JPEGs the whole chain lands at 31 to 49 dB, which is the ETC1S encode's own loss.
+
+**One thing the mutation pass found, worth writing down.** Removing either bounds check in the two
+writers changes no output, and the tests were right not to fail. The index is row-major, so a write
+past the right edge of row `y` lands at the start of row `y + 1`, which is written afterwards and
+overwrites it; the only spill nothing corrects runs past the end of the buffer, where a typed array
+drops it silently. The guards are therefore unobservable — and they stay, because they are
+unobservable only while the iteration order holds, which is a coincidence and not a contract. Both
+files now say so, so that nobody removes them on the evidence of a green suite.
+
+**Still not implemented:** ETC2 and ASTC. An ETC1S block already *is* an ETC1 block and UASTC was
+designed to transcode to ASTC nearly for free, so both remain much cheaper than the BC7 path already
+written, and both would beat four bytes a texel on the mobile devices that expose them. The
+difference is that failing to write them is now a memory cost rather than a refusal.
+
+### 9.14 The albedo maps were never decoded as sRGB
+
+Reported by eye — "they feel colder than the JPEGs" — and true. All 25 of Sponza's albedo textures
+were created as `bc7-rgba-unorm` while the same model's JPEGs reached `rgba8unorm-srgb`, so the GPU
+skipped the sRGB-to-linear decode and the shader read sRGB-encoded values as though they were linear.
+
+Measured over one 1024x1024 albedo map, comparing what the shader saw against what it should have:
+
+| | correct | as sampled | change |
+|---|---|---|---|
+| mean saturation | 0.2712 | 0.1488 | **-45.1%** |
+| mean luminance | 0.1316 | 0.3575 | **+171.7%** |
+| warmth (R-B) relative to luminance | 0.242 | 0.116 | **-52.4%** |
+
+Both halves of the report fall out of that. The decode is a power curve, so it *stretches* the gap
+between channels; skipping it compresses them, which is the lost saturation. And warm surfaces have
+the widest R-to-B gap, so they lose the most — absolute R-B rises with everything else, but as a
+fraction of brightness it halves, which is what reads as cold.
+
+**The cause was a pinned decision, not an oversight.** `texture_format_from_shade_image` returned a
+texel payload's format verbatim, and a test asserted it: *"a texel payload states its own format,
+whatever the colour space says"*, reasoning that "there is nothing to infer from, so nothing to be
+overridden by". That conflates two things. Channel count and data type are inference, and a payload
+does state them. sRGB-ness is not inference at all — `bc7-rgba-unorm` and `bc7-rgba-unorm-srgb` are
+the same bytes, so a transcoder targeting either does identical work and a payload *cannot* express
+the choice. Naming one leaves the question open rather than answering it.
+
+The test immediately above it already states the correct rule, for the other branch: a format decided
+before `color_space` is assigned "would leave every glTF albedo map on `rgba8unorm` and silently drop
+its sRGB decode". The texel branch did exactly that. Both branches now read `color_space`, and a
+payload with no sRGB counterpart under an sRGB image is refused by name rather than quietly returning
+the linear format — the silent wrong answer being the whole failure mode here.
+
+`gpu_texture_format_srgb` is new and derives its pairs from the format table by suffix rather than
+listing them, so a format added to the table brings its own pairing.
+
+**Two notes for the next person.** VRAM is unchanged: sRGB-ness is a decode, not a size, so nothing
+about §9.13's 4.00x moves. And the playground reported the *payload's* format, which is why its own
+table showed `bc7-rgba-unorm` for albedo and looked right while the render did not; it now reports
+what `texture_format_from_shade_image` returns, so the two paths' albedo rows can be compared.
+
+**Separately checked and not a problem:** whether ETC1S itself desaturates. Across the opaque JPEGs
+it is within about 3%, rising to 9% only on near-pure primaries where quantization lifts a
+near-zero channel by roughly 2/255. That is ordinary lossy behaviour and not what was visible.
+
+### 9.13 What tier 8 found — the first GPU to see any of this
+
+Run 2026-09-02 on an NVIDIA Lovelace device, through
+[`playground/basis_textures`](../../playground/basis_textures/README.md): Sponza twice, once as JPEG
+and once re-encoded by `basisu` to KTX2 with UASTC normals and ETC1S everything else.
+
+| | textures | GPU memory | formats |
+|---|---|---|---|
+| JPEG | 69 | 335.3 MiB | 69 x `rgba8` |
+| Basis | 69 | 83.8 MiB | 45 x `bc7-rgba-unorm`, 24 x `bc5-rg-unorm` |
+
+**4.00x**, both sides counted through `TextureDescriptor.memory_footprint` and both including their
+full mip chain. All 69 textures were accepted by the device. The 24 BC5 textures are exactly the 24
+normal maps, which is §3b's role-driven choice arriving where it was aimed.
+
+Two defects, and both are §9.11's lesson a third time — a rule that held everywhere it had been
+checked, and had never been checked here.
+
+1. **Mip *generation* was requested for formats that cannot generate mips.** `ShadeTexture` sets
+   `GenerateMipMaps` by default, which is right for a decoded JPEG and impossible for a transcoded
+   payload: the generator renders between levels and no BC format can be a render attachment.
+   `texture_descriptor_from_texture_shade` refuses that combination by name (§9.7 made it refuse
+   rather than reinterpret, which is why this surfaced as a legible message instead of a black
+   texture) — but nothing cleared the flag, so **every compressed texture in the scene was refused at
+   upload**. `load_gltf` now clears it when the image's format cannot generate them, and the chain
+   the container already carries is used. Every device-free test had built its textures directly and
+   never went through the glTF loader's default flags.
+2. **`TextureManager.gpu_memory_usage` is a running total, and removing a scene evicts nothing.**
+   Reading it after each load reported the sum of every load so far, which inflated whichever variant
+   was measured second — the one being argued for. It read 5.00x before this was noticed. The
+   playground measures the difference across its own uploads instead. Worth recording as a property
+   of the manager rather than of the playground: there is no eviction API, and a long-running editor
+   that swaps scenes will accumulate.
+
+**Then a third, which the numbers could not have found — every texture was upside down.** The
+converter passed `-y_flip` to `basisu`. glTF puts UV (0,0) at the top-left, and a KTX2 with no
+`KTXorientation` key means exactly that, so `KHR_texture_basisu` requires a top-down payload;
+`basisu` writes no such key either way, so the flag bakes a vertical mirror into the pixels and
+records nothing a reader could detect or undo. Confirmed by encoding a top-white/bottom-black image
+both ways and transcoding each: with the flag the top row decodes black, without it white. Then on
+the re-converted model itself, comparing each texture's top-band luminance against its bottom-band in
+the browser: all six asymmetric enough to judge agree in sign with the JPEG they came from, one to 0.3
+out of 143. The bug was in the dev tool and not in the engine — the container reader and both
+transcoders preserve orientation, which the fixture comparisons against reference-decoded output
+already pin, and nothing on the upload path flips either (`createImageBitmap` is left at the default
+`from-image`, `copyExternalImageToTexture` sets no `flipY`), so the JPEG and KTX2 paths agree.
+
+Worth separating from the two above: those were found by *running* it, and this one only by
+*looking* at it. The VRAM table was correct in every particular while the scene was upside down,
+which is the caveat below arriving in practice rather than in principle.
+
+**Still not seen — and that turned out to matter.** The renderer needs `maxImmediateSize` >= 24 and
+assumes the 64-byte floor; the Chrome build available here reports 0, so the frame loop dies in
+`GPUTypedTable/Upload elements` for every playground in the directory. The measurements above are
+taken through `TextureManager.obtain` — the same call the renderer makes, and the same moment the
+device accepts a format or does not — so what is proven is that the device takes these textures.
+That the sampled result *looks* like the picture is established only on the CPU side, against the
+reference decoder, and the `-y_flip` defect is what that gap costs: an asset bug that every number
+on the page was blind to, and that a single glance caught.
+
+**The gap tier 8 made concrete.** There is no uncompressed transcode target, so a device advertising
+no BC at all gets a named refusal. No real WebGPU device is in that position, but the two cheap
+fillers should be recorded: an ETC1S block already *is* an ETC1 block, and UASTC was designed to
+transcode to ASTC nearly for free. Both are far cheaper than the BC7 path already written.
+
+### 9.12 What step 9b actually shipped — UASTC, and the one thing it still cannot open
+
+**UASTC is the encoding normal maps use, and that is why it stopped being optional.** ETC1S puts a
+block's four colours on a line through the grey axis, which is a good model of a photograph and a bad
+model of a direction — a normal map encoded as ETC1S bands visibly. `gltf-transform uastc` and
+`toktx --uastc` exist for that, and any pipeline that cares about normals emits it.
+
+Nineteen modes, 128-bit blocks, varying in subset count, endpoint precision, weight precision and
+whether one channel is interpolated separately, with the endpoints trit- or quint-coded in most modes
+and the weights packed a bit short at each subset's anchor texel. Implemented from the UASTC LDR 4x4
+specification.
+
+**The tables were transcribed mechanically, not typed.** Sixty partition patterns, sixty anchor
+tables, eleven dequantisation tables and nineteen mode descriptors were extracted from the
+specification's own listings into
+[`uastc_tables.js`](../../../format/texture/basis/uastc/uastc_tables.js). The only thing computed is each mode's
+field offsets, and those are checked against the offsets the specification prints for every mode.
+
+#### What it transcodes to, and the one that matters
+
+**BC5, which is the point.** §11.1 established that a tangent-space normal's Z is reconstructed in
+the shader, so `bc5-rg-unorm` spends its whole budget on the two channels that carry something —
+and `texture_format_preference` has led with it for the normal role since step 3b with nothing able
+to produce one. Two independent scalar channels means no line through colour space to place, so the
+encode is near-optimal: worst channel error of **1** on the gradient fixture.
+
+**BC7, by carrying the block across rather than re-encoding it.** A UASTC block already *is* two
+endpoints and a weight per texel, which is what BC7 stores, so the transcode is a change of
+representation. Decoding to RGBA and fitting a fresh line instead — which is what this did first —
+costs **eighteen decibels**, and the measurement is worth keeping because the wrong version looked
+entirely reasonable. Dual plane blocks go to BC7 mode 5, whose second index set is exactly what their
+separately-interpolated channel needs; everything else single-subset goes to mode 6, whose four-bit
+weight table is ASTC's. Where those two cover every block the output matches the reference
+transcoder's own figures: **55.68 dB with a worst channel of 1**, against its 55.68 and 1.
+
+#### The role finally reaches the format choice
+
+§9.11 recorded that the texture's role did not enter the target choice and that this would start
+mattering "the moment ETC1S→BC5 lands". It landed as UASTC→BC5 instead, and the rest followed:
+[`gltf_image_roles`](../loader/gltf/gltf_image_roles.js) reads the materials to learn which image is
+the normal map, and the loader orders its candidates by `texture_format_preference(role, ...)`.
+
+**Ordering, not filtering.** A role's preference lists what is *good*, not what is acceptable — BC1
+is in no role's list — so a device that can sample only BC1 still gets a texture. The role moves a
+format to the front and never removes one.
+
+#### Partitioned blocks, and what closing that gap turned up
+
+The first version of this flattened every two- and three-subset block onto one BC7 line, because BC7's
+partitioned modes were not written. That cost **more than twenty decibels** on partitioned content —
+the subsets fixture scored 25.8 dB then and 52.0 now — and it is closed: every UASTC mode goes to the
+BC7 mode the specification pairs it with, including mode 7's oddity of being two subsets in UASTC and
+three in BC7, written with two of BC7's endpoint pairs alike.
+
+One writer serves all six modes, because the specification says the fields are in the same order for
+every mode and only their widths change. Against the reference transcoder, colour only: identical on
+two fixtures, +0.14 dB on a third, and 0.21 and 0.44 dB behind on the other two.
+
+**Two defects surfaced while closing it, and both were about alpha nobody authored.** Mode 1 was
+mapped to BC7 mode 6 rather than mode 3 — and the specification's choice is not arbitrary: mode 3 is
+the only mode holding eight-bit endpoints *without* an alpha channel, and mode 6's alpha parity bit is
+shared with colour, so it must be traded against it. That trade was the second defect: choosing the
+parity by total error over all four channels let a constant alpha outvote colour, and on an RGB source
+that alpha is 255 by construction rather than by authorship. Forcing it kept alpha exact and cost
+**1.66 dB of colour**; excluding it from the vote is right, because §9.2 already settled that a
+texture's alpha mode is declared rather than inferred from its texels. The reference makes the same
+trade — its own output carries 181,026 texels at alpha 254 on the same opaque file.
+
+#### The mutation harness was lying, which is the more useful finding
+
+The checks ran through `sed`, and `sed` reports nothing when it matches nothing — so a mutation whose
+pattern had the wrong indentation silently tested the *unmodified* code and was recorded as caught.
+Three of them had. The harness now fails loudly on a no-op and every mutation claimed for this work
+was re-run through it.
+
+Two real holes appeared once they ran for real, and both are the §9.11 lesson again — a guard checked
+against its own absence says nothing about code no fixture reaches:
+
+- **BC7's anchor tables were untested.** The anchor is texel 15 for the first seventeen partitions and
+  something else after that, and every fixture happened to land in the first seventeen — so the table
+  could have been replaced by the constant 15. `uastc_partitions_32x24` reaches anchors 2 and 8: one
+  block per partition pattern, each subset ramping in its own direction, because two flat colours are
+  collinear and an encoder answers them with a single subset.
+- **The three-subset permutation was untested by any bound that could see it.** Only seven blocks use
+  a non-identity one, which moves an average by under a decibel while moving the worst texel by a
+  hundred. The transcode tests now carry a per-channel bound beside the PSNR one — the same division
+  §9.11 settled for ETC1S, arrived at a second time by getting it wrong.
+
+#### Zstandard, which turned out not to be optional
+
+`basisu -uastc -ktx2` compresses with Zstandard *by default*, and so do `gltf-transform` and
+`toktx` — so almost all UASTC in the wild sits behind it, and a UASTC transcoder without a Zstandard
+decompressor reads only files written with `-ktx2_no_zstandard`, which is not what anyone writes by
+accident. It was going to be step 9c and became part of this one, because the feature was not real
+without it.
+
+**Implemented from RFC 8878**, in [`core/binary/zstd/`](../../../core/binary/zstd/zstd_decompress.js)
+beside `lz4/` and `meshopt/`, on the same argument that put those there. §9.10 read ZLIB rather than
+refusing it because `pako` was already present; this is the same conclusion reached the other way,
+by writing the decompressor rather than taking one.
+
+It is Lempel-Ziv with two entropy stages over it, both read *backwards* — Finite State Entropy
+carries a state between symbols, so decoding runs opposite to encoding. Two details cost a debugging
+session each and are commented where they bit:
+
+- **The normalised-count field width shrinks with a running threshold** rather than being recomputed
+  from the probability that remains. The two readings look equivalent and are not: the halving lags
+  behind the remainder, so a decoder that recomputes reads most distributions correctly and a few
+  wrongly.
+- **The interleaved two-state weight decode emits, then advances**, and stops when an advance runs
+  past the start of the stream — not when the *other* state could not advance. The wrong version
+  produced weight sets right for most of their length, which surfaced as two literals swapped.
+
+No dictionaries, and the content checksum is skipped rather than verified: the containers carrying
+these streams check their own payload sizes, and XXH64 to re-check a length is not worth a file.
+
+Tested against `node:zlib`'s Zstandard — the reference library, so the oracle is somebody else's
+implementation and not this one's own output. Three thousand fuzz cases over six input shapes and
+every compression level, thirteen committed cases, and five mutations all caught. A
+Zstandard-wrapped UASTC file now transcodes byte-identically to the same file written uncompressed.
+
+#### Testing
+
+**17 of the 19 modes are exercised and verified** — every one an encoder could be made to emit.
+Modes 10 and 18 are not selected by `basisu` at any quality level or content tried, so they are
+implemented from the specification and unproven, which is stated here rather than left to be assumed.
+Getting the coverage took building content to provoke modes rather than to look like anything: solid
+blocks, sharply partitioned blocks, blocks with alpha independent of colour.
+
+The ground truth is the reference transcoder's BC7 output, which the specification itself calls lossy
+by 0.75 to 1.5 dB — so it is a bound rather than an equality, and at a worst channel error of **6**
+across every fixture it is a decisive one: misreading a mode, a partition, an endpoint range or an
+anchor moves a block by tens or hundreds. UASTC→ASTC is the lossless transcode and would give an
+exact check; nothing here can decode an ASTC block to make use of it.
+
+**And the test decoder now shares its tables with the writer**, which means it cannot disagree with
+it — a transcription error in a partition, anchor or mode table would be invisible to every
+comparison between the two. What breaks that symmetry is decoding blocks this repository did not
+write: the reference's output for these fixtures spans BC7 modes 1, 2, 3, 5, 6 and 7, and reproducing
+the texels it published for them is exact. That check runs before any other in the file, and it is
+what makes sharing the tables safe rather than circular.
+
+Twelve mutations across the decoder and both transcoders, all caught — after the harness was fixed to
+report the ones that had silently applied to nothing.
+
+### 9.11 What step 9 actually shipped, and the two places §4.3 was optimistic
+
+[`transcode_basis`](../../../format/texture/basis/transcode_basis.js) is the public surface, with §4.3's contract
+intact: bytes in, texels out, no device and no queue. `src/basis/` sits beside `src/ktx2/` and
+`src/avif/` for the same reason those do — a worker, a node tool and the offline encoder will each
+want it, and none should have to import a graphics API to get it.
+
+**ETC1S only.** Both Basis encodings were in scope and one landed. UASTC is a different bitstream —
+mode-switched 128-bit blocks with BISE-coded weights, sharing nothing with ETC1S but the file it
+arrives in — and it is refused by name rather than half-implemented. ETC1S is the common case in the
+wild and the whole of what `basisu` and `gltf-transform` emit at their default settings, so the
+capability is useful without it; step 9b is the rest.
+
+`ktx2_read` accepts BasisLZ, and `KHR_texture_basisu` is read at both glTF sites.
+
+#### Where §4.3 was optimistic
+
+**1. `payload` is not a byte array.** The signature reads `transcode_basis(payload, target_format)`,
+which suggests one buffer. An ETC1S texture is not stored that way: its endpoint and selector
+codebooks and its four Huffman tables live in KTX2's *supercompression global data*, its slices live
+in the mip levels, and which bytes are which is a question about the container. So `payload` is a
+`BasisEtc1sPayload` — the sections, already located — and finding them is
+[`ktx2_read_basis_lz_global_data`](../../../format/texture/ktx2/ktx2_read_basis_lz_global_data.js), which is KTX2
+Appendix C and therefore container code. A `.basis` reader would build the same payload from a
+different layout. Nothing about "no device, no queue, no engine" changes.
+
+**2. "Block-to-block transforms with no cross-block dependencies" is true of the structure and badly
+understates the work.** The transform really is per block with no neighbours involved. But the
+obvious mapping — take the ETC1S palette's darkest and brightest colours as the destination's two
+endpoints — lands **8 to 10 dB below the reference transcoder**, and a texture that far down is
+visibly banded on saturated content. Three things close it, none of them evident from the format
+descriptions:
+
+- **Clamping breaks the collinearity the transform depends on.** An ETC1S block is a base colour plus
+  one modifier applied to all three channels, so its four colours are collinear *before* clamping.
+  A base near white with a large modifier gives red `{67, 203, 255, 255}` beside green
+  `{0, 0, 57, 193}` — still ordered, no longer on a line, because red saturated and green did not.
+  Endpoints have to be **fitted** (least squares, alternating with the weight assignment), not read
+  off the ends.
+- **The fit has to know which selectors the block actually uses.** That is a property of its
+  *selector* codebook entry, not of the endpoint entry, so the tables are keyed on the **pairing** of
+  the two. A block spanning only the darkest two colours is a line those two define exactly, and
+  fitting it against colours it never samples throws that away.
+- **For BC1, which colour goes at which of the four positions has to be enumerated.** The best pair
+  frequently lies **outside** the colours it encodes: three evenly spaced colours have no endpoints
+  putting them at weights 0, something and 64, but a pair extended past both ends puts them at 64,
+  43 and 21 almost exactly. There are at most fifteen such assignments, so they are tried rather than
+  searched for. BC1's pair is then searched in 5:6:5 space rather than rounded into it, because five-
+  and six-bit endpoints are coarse enough that the best representable pair is not always the rounding
+  of the best real-valued one.
+
+All of it is per (endpoint entry, selector span) pairing — a few hundred to a few thousand — rather
+than per block, of which a texture has tens of thousands.
+
+**Which of those is worth what, measured, because the first write-up of this got it wrong.** On the
+noise fixture, against 48.0 dB for BC7 and 44.1 for BC1:
+
+| removed | BC7 | BC1 |
+|---|---|---|
+| selector-span conditioning | 38.8 dB, worst channel 30 | 38.1 dB, worst channel 36 |
+| BC1's assignment enumeration | — | 37.6 dB, worst channel 30 |
+| the least-squares solve | 48.0 dB, worst channel 2 | — |
+| BC1's 5:6:5 search | — | 43.9 dB |
+
+So **span conditioning is the whole of it for BC7, and span conditioning plus the assignment
+enumeration are the whole of it for BC1.** The least-squares solve on top contributes nothing
+measurable on that fixture and about a decibel on the harder mip levels of the gradient and
+non-power-of-two files; the 5:6:5 search contributes 0.2 to 1.3 dB. The commit that landed this
+credited the 5:6:5 search with 9 dB, which was the assignment enumeration's — the two were written
+at the same time and never ablated apart until afterwards.
+
+The result matches the reference transcoder: BC7 at 48.0 / 52.1 / 49.1 dB against its
+46.6 / 51.7 / 51.8, BC1 at 44.1 / 49.7 against 44.0 / 49.8.
+
+**And it is not fast.** A 1024×1024 texture takes **127 ms** to reach BC7 and **389 ms** to reach
+BC1, on the main thread, of which the codebooks and the slice decode are 22 ms together and the rest
+is building the templates — 18,620 pairings for that file, of which 71% are actually referenced.
+§4.2 said transcoding "pays CPU time on load"; this is what that costs, and a model with a dozen
+textures pays it a dozen times. The obvious places to go next are running it in the worker pool
+`avif/threaded_image_encoder.js` already has, building templates lazily for the pairings a slice
+actually names, and §4.4's GPU transcoder — which is step 10 and was always the answer to this.
+
+#### The judgement calls
+
+**BC7 needs two modes, and the plan assumed one transform.** Mode 6 gives every texel one four-bit
+index shared by all four channels; mode 5 gives colour and alpha their own indices, two bits each. An
+ETC1S file's alpha lives in a **second slice with its own selectors**, unrelated to the colour
+slice's, so mode 6's single index set cannot express an alpha payload at all. Opaque payloads take
+mode 6 for the finer index; alpha payloads take mode 5. Mode 6 additionally fixes its parity bit at
+one rather than fitting it, because that bit is shared between an endpoint's colour channels and its
+alpha, and an opaque texture decoding to alpha 254 is a bug nothing notices until something blends.
+
+**`ktx2_read` gained a parameter, and it is not defaulted.** An ETC1S payload has no format of its
+own — what it should become depends on the device and on the material slot — so `transcode_target` is
+the caller's to state. Absent, an ETC1S file is refused naming `texture_format_preference` as where
+one comes from. Every other file ignores it, so no existing caller changed.
+
+**BC1 refuses an alpha payload rather than dropping it.** BC1 has no alpha channel in the mode this
+writes. A payload carries alpha slices because something needed them, and a texture arriving opaque
+surfaces far away as a cutout that does not cut out.
+
+**Both glTF sites now share one function rather than agreeing by inspection.**
+`gltf_texture_image_index` is the preference order, written once:
+`KHR_texture_basisu`, then `EXT_texture_webp`, then `source`. §9.10's neighbouring incident — the two
+disagreeing, and not one model in the level loading — is not fixed by being careful, it is fixed by
+there being one decision.
+
+#### What this did not build, and why
+
+**Device support does not reach the asset layer.** §3.5 divides capability (the engine's) from
+selection (the asset layer's), and the asset layer here is the glTF loader — which has an
+`assetManager` and a `scope` and **no device**. `load_gltf` gains a `texture_support` option and
+nothing passes it, because opening a channel from the renderer to every asset loader is a change of
+its own shape. Absent one, the loader targets BC7: an assumption about the hardware meep aims at,
+stated as one, and a caller that knows better passes its device's support and gets a named refusal
+instead of a texture the device cannot hold. `gpu_texture_compression_support` still has no
+non-test caller.
+
+**The texture's role does not enter the choice.** Every format this transcoder writes is a
+four-channel BC colour format, so a normal map and an albedo map get the same answer and asking
+`texture_format_preference` for the role would be ceremony. It stops being ceremony the moment
+ETC1S→BC5 lands — BC5 is what §11.1 already established normals want, and an ETC1S file with an alpha
+slice carries exactly the two channels it needs.
+
+#### Testing, and what §9.10's gap became
+
+**Step 8's fixtures were synthesised and this one's are not.** §9.10 named that as its gap — "first
+contact with a real file is the test that has not been run" — and these are files from
+`basisu 1.16.4`, so for the ETC1S path the byte offsets are now known rather than believed. That
+includes the level index and the global data layout the KTX2 reader had only ever read from its own
+writer.
+
+Three things make the specs load-bearing rather than self-confirming:
+
+1. **The ground truth is the encoder's own decode.** `basisu` unpacks each file to ETC1, which *is*
+   the ETC1S texels; every level of every fixture comes out of this decoder byte-identical to it.
+   That covers the global data, four Huffman tables, both codebooks, the endpoint predictor and the
+   selector history in one assertion.
+2. **The block decoder the transcode tests judge with is validated before it is trusted.** A decoder
+   written beside an encoder can share the encoder's misreading and agree with it perfectly, so it is
+   first pointed at blocks the *reference* transcoder produced and checked against the texels the
+   reference published for them.
+3. **Every guard was checked against its own absence.** Fourteen mutations, all caught — among them
+   dropping the move-to-front promotion, misreading the upper-left predictor as the upper, floating
+   the parity bit, skipping the anchor flip, starting the endpoint codebook from black instead of
+   `(16, 16, 16)`, dropping the selector DPCM, shifting a five-bit channel instead of replicating it,
+   dropping the endpoint index wraparound, reading alpha presence as always absent, and the three
+   glTF ones. One found a real hole: **no fixture reached the upper-left endpoint predictor**, so
+   that branch could have been deleted silently. `etc1s_antidiag_64x64` exists to exercise it, and
+   diagonal structure is what made an encoder want it.
+
+**What is still untested.** Alpha has no exact reference — `basisu` never emits the alpha slice in a
+form that is not already re-encoded — so that one path is bounded rather than exact.
+
+**Tier 8 has now been run** — see §9.13.
+
+#### What an adversarial pass over the above then found
+
+Worth recording because two of the four were defects that the tests as written could not have caught,
+and both were of the same kind: a rule read once and then assumed.
+
+1. **`KHR_texture_basisu` images were identified by MIME type, and the extension does not require
+   one.** `image/ktx2` is mandatory only inside a GLB, where the image comes from a bufferView; an
+   image referenced by URI is merely *permitted* to declare it. So an ordinary `.gltf` carrying
+   `{"uri": "wood.ktx2"}` went to `createImageBitmap` — which is precisely the failure
+   `gltf_used_image_indices` exists to prevent, reintroduced by the change that cited it. The
+   extension's own reference is now the authority and the MIME type a supplementary signal.
+2. **A corrupt slice produced silent wrong texels rather than a refusal.** The three reuse predictors
+   each name a neighbour that does not exist at an edge; the specification asserts an encoder never
+   does this, and the decoder trusted that. Reading past the start of the previous row's array yields
+   `undefined`, which compares false against every bound and stores as endpoint zero. Now refused,
+   naming the predictor and the position.
+3. **Two more branches had no fixture reaching them**, exactly as the upper-left predictor had none:
+   the **grayscale endpoint codebook**, which sends one channel and means three — deletable with
+   every test still passing — and **non-power-of-two** dimensions, where every mip tail is square in
+   the fixtures that existed. Both work; neither was proven. `gray_64x64` and `npot_100x60` are here
+   now. The lesson is that "verify a guard against its own absence" catches broken code and says
+   nothing about code no test reaches, and only counting which branches a fixture set actually
+   executes finds those.
+4. **The quality attribution in the commit message was wrong**, as the table above records. Two
+   optimisations written in the same sitting were credited by measuring their sum.
+
+The non-power-of-two fixture is also the one place a bound had to be *loosened* rather than a bug
+fixed: its first form used a pattern with wrapping discontinuities, on which the transcode's worst
+channel error is 59 — and the reference transcoder's is 69, because no two-endpoint format holds four
+colours that far off a line. That is a fact about the format pair, so the fixture was re-made with
+smooth content, leaving the geometry under test and the thin per-channel bound intact.
+
 ### 9.10 What step 8 actually shipped
 
-[`ktx2_read`](../../../ktx2/ktx2_read.js) is the whole public surface: `bytes -> ShadeTexelData`, one
+[`ktx2_read`](../../../format/texture/ktx2/ktx2_read.js) is the whole public surface: `bytes -> ShadeTexelData`, one
 free function, no device and no queue. It lives at `src/ktx2/`, beside `src/avif/` rather than inside
 the renderer, which is §2's "living with its container" taken literally — the same function is what a
 worker, a node tool and the offline encoder will each want, and none of them should have to import a
@@ -901,7 +1779,7 @@ it, and two of them are changes to existing code:
 
 - **`ByteCursor` moved to [`core/binary/`](../../../core/binary/ByteCursor.js) and takes its byte
   order at `init`.** It was exactly the cursor this needed — bounds-checked, zero-copy, a named error
-  per truncated field — and it was big-endian and living in `avif/native/isobmff/`. The alternatives
+  per truncated field — and it was big-endian and living in `format/image/avif/isobmff/`. The alternatives
   were both worse: `BinaryBuffer` is a growable stream whose reads throw `RangeError` from a
   `DataView` rather than naming the field that ran out, and a second cursor in `ktx2/` would have
   been the fourth copy of bounds-checked reading in this tree. **Endianness is a property of the
@@ -909,7 +1787,7 @@ it, and two of them are changes to existing code:
   which is also why no AVIF accessor call site changed, only the ten places that construct a
   cursor, two of them outside tests. (The commit message says "four". It is wrong; this is the
   count.)
-  [D10](../../../avif/native/DECISIONS.md) is amended to record this; the decision it made — read
+  [D10](../../../format/image/avif/DECISIONS.md) is amended to record this; the decision it made — read
   with a cursor, write with `BinaryBuffer` — is untouched.
 - **`gpu_texture_format_is_block_compressed` exists, and not where §2 put it.** §2 listed it under
   `renderer/texture/format/`. That was wrong twice over: it is a fact about the format table, so it
@@ -945,8 +1823,13 @@ than uploading garbage. Zstandard stays refused because there is no decompressor
 BasisLZ stays refused because it is not a wrapper — it is an encoding with its own codebooks, and
 undoing it is a transcoder.
 
+> **Both of those refusals are gone now.** BasisLZ became step 9's transcoder, and step 9b wrote the
+> Zstandard decompressor this section said did not exist — see §9.12 for why that stopped being
+> optional. The reasoning above is left as it was written: it was right about the *kind* of thing
+> each is, and being right about that is what made both of them tractable when the time came.
+
 **`pako.inflate` directly rather than
-[`png_inflate`](../../../engine/asset/loaders/image/png/png_inflate.js).** What that function adds
+[`png_inflate`](../../../format/image/png/png_inflate.js).** What that function adds
 over the bare call is PNG's two peculiarities: a stream split across `IDAT` chunks, and a fallback
 that abandons the adler32 check because real encoders get it wrong. A KTX2 level is one stream, and a
 texture payload whose checksum fails should fail. Reusing it would have meant a KTX2 reader importing