@woosh/meep-engine 3.14.1 → 3.14.3

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

@@ -0,0 +1,2345 @@
+# Block-compressed textures — implementation plan
+
+**Status:** proposal — revision 6
+**Date:** 2026-09-01
+**Author:** Alex Goldring / Company Named Limited
+**Scope:** `src/shade/renderer/texture/`, `src/shade/descriptor/texture/format/`,
+`src/shade/device/mock/`, `src/engine/asset/`
+
+> **Revision 2** rewrites §4 and §5, which had the wrong shape. Revision 1 treated transcoding as a
+> rejected alternative and per-format delivery as a container feature; both were wrong. Transcoding
+> is a **supported path** — KTX2/Basis is what the web's model pipeline emits, and the engine has to
+> read it — and format selection is a **network concern**, not a packaging one, which also reverses
+> revision 1's "do not ship ETC2" (§5.2). §3.4 gains one-level-at-a-time upload, which is what
+> streaming actually requires, and §7 is new: what compressed virtual textures need the rest of the
+> design not to preclude.
+>
+> **Revision 3** fixes §3.2, which was wrong in the way this document spends §0 warning against.
+> Revision 2 had `GenerateMipMaps` mean "generate, unless levels were supplied, in which case
+> quietly do nothing" — an explicit instruction silently reinterpreted from the data. It is now
+> honoured or it throws (§3.2), which also removes revision 2's separate rule about single-level
+> compressed payloads by subsuming it. §2 loses a module that turned out to already exist (§5.3).
+>
+> **Revision 4** adds §2.1. A `TextureFormat` enum is worth having, though not for the reason it was
+> asked for — `GPUTextureFormat` is a string and never throws. The load-time `GPUTextureUsage` read
+> in `TextureDescriptor` does throw, outside vitest, which is where the node-side consumers this
+> plan adds will all be standing.
+>
+> **Revision 5** records an adversarial pass (§11) and applies it. Six findings: "no shader changes"
+> was false (§11.1 — BC5 normals need Z reconstruction at five sites), `ShadeImage.format` cannot be
+> 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.
+
+---
+
+## 0. The one thing this document is about
+
+There is an obvious way to do this and it is wrong: give `ShadeImage` an `is_compressed` flag, add
+`if (compressed)` to the descriptor builder and the uploader, and let the two halves drift for a
+year. The reason that is tempting is that the engine currently decides a texture's **format at
+upload time** by inspecting the pixel data — and compressed data has no pixels to inspect.
+
+So the plan is one structural move, and the rest follows from it:
+
+> **`ShadeImage` stops describing pixels and starts describing texels.** It carries a
+> `GPUTextureFormat` and a list of mip levels. Uncompressed data is the degenerate case — a
+> 1×1 block — exactly as [`gpu_texture_format_info`](../../descriptor/texture/format/gpu_texture_format_info.js)
+> already models it.
+
+The invariant that keeps this honest:
+
+> **Below `ShadeImage`, nothing knows whether a texture is compressed.** Every difference is either
+> (a) a value read out of the one format table, or (b) a decision taken *above* `ShadeImage` — in
+> the asset layer, before the image exists.
+
+**The axis that legitimately forks is not compressed/uncompressed.** It is *how the bytes reach the
+GPU*, and it forks into three (§4): an external image, host bytes, or a device-side producer. That
+split exists today, has nothing to do with compression, and is where transcoding and — later —
+runtime compression belong.
+
+**No shader *variants*.** A `bc7-rgba-unorm` texture binds as `texture_2d<f32>` and samples like
+`rgba8unorm` — no pipeline variants, no codegen, nothing in [wgsl](../../wgsl) that branches on
+format. One shared decode change is needed, and only because two-channel normal formats exist:
+Z reconstruction, applied identically to compressed and uncompressed sources (§11.1).
+
+---
+
+## 1. What is there now
+
+Five places encode "a texture's bytes are `channel_count` samples of `data_type` per texel".
+
+| Place | Assumption |
+|---|---|
+| [`ShadeImage`](source/ShadeImage.js) | pixels are `(data_type, channel_count, normalized)` plus a `color_space`. No format, no mip levels. |
+| [`inferFormatFromImage`](texture_descriptor_from_texture_shade.js:99) | the format is *derived at upload* from those four fields, by string-building `${prefix}${bit_size}${ending}` |
+| [`texture_descriptor_from_texture_shade`](texture_descriptor_from_texture_shade.js:149) | `GenerateMipMaps` implies `RENDER_ATTACHMENT` **and** a full generated chain. Both are illegal for a block format. |
+| [`texture_write_raw`](texture_write_to_gpu.js:93) | one `writeTexture` hard-coded to `mipLevel: 0`, with `bytesPerRow = channels × bytes × width`; plus RGB→RGBA padding and CPU premultiplication, neither of which can be done to a block |
+| [`TextureDescriptor.bits_per_sample`](../../descriptor/texture/TextureDescriptor.js:100) | a per-channel bit table. Every block format misses it, so `memory_footprint` warns and reports **0 bytes**. |
+
+Second order, all of them one-liners once the above is fixed: the resident material atlas
+([`GPUResidentMaterialContext.js:338`](../material/resident/GPUResidentMaterialContext.js:338)), the
+software device ([`SoftwareGPUQueue.js:220`](../../device/mock/SoftwareGPUQueue.js:220)), the
+bindless allocator ([`GPUBindlessTextureManager.js:114`](bindless/GPUBindlessTextureManager.js:114)),
+[`shade_texture_might_have_alpha`](shade_texture_might_have_alpha.js), and the VT cache's
+`bytes_per_row ?? this.slot_size * 4` ([`VTPhysicalCache.js:324`](virtual/VTPhysicalCache.js:324)).
+
+**What is already right, and is the reason this is cheap:**
+
+- [`gpu_texture_format_info`](../../descriptor/texture/format/gpu_texture_format_info.js) already
+  tabulates every BC, ETC2/EAC and ASTC format with correct block dimensions and byte sizes, and
+  already exposes `gpu_texture_format_row_bytes` / `gpu_texture_format_row_count`, which round up to
+  whole blocks. This is the table the whole plan runs on. It has three consumers today.
+- [`texture_copy.js`](../../device/mock/texture_copy.js:221) in the software device is already
+  block-aware, and the mock already implements `copyBufferToTexture`
+  ([`SoftwareGPUCommandEncoder.js:329`](../../device/mock/SoftwareGPUCommandEncoder.js:329)) — which
+  no engine code uses yet, and which the GPU transcode path (§4.4) will be the first to want.
+- [`VTPhysicalCache`](virtual/VTPhysicalCache.js:69) is **already parameterised by a per-layer
+  `GPUTextureFormat`**. §7 is smaller than it looks.
+- [`SamplerDescriptor`](../../descriptor/texture/SamplerDescriptor.js:17) already carries
+  `lodMinClamp`, which is the mechanism mip streaming needs (§3.4).
+- [`gpu_texture_format_srg_to_linear`](format/gpu_texture_format_srg_to_linear.js) and
+  [`gpu_texture_format_to_color_space`](format/gpu_texture_format_to_color_space.js) already
+  enumerate every BC, ETC2 and ASTC srgb pair — written compressed-aware, never yet handed a
+  compressed format (§5.3).
+
+---
+
+## 2. Modules
+
+```
+shade/renderer/texture/source/
+    ShadeTexelData.js              NEW  format + size + mip levels. The compressed payload,
+                                        and the general case of the uncompressed one.
+    ShadeImage.js                  CHG  gains .format, .level_count, .alpha_mode
+    AlphaMode.js                   NEW  @enum Opaque | Straight | Premultiplied (§11.3)
+
+shade/renderer/texture/format/
+    gpu_texture_format_is_block_compressed.js   NEW  one-liner over gpu_texture_format_info
+    gpu_texture_format_can_generate_mipmaps.js  NEW  can the generator render into it (§3.2)
+    gpu_texture_format_srg_to_linear.js         CHG  gains its inverse; already knows BC/ETC2/ASTC
+    gpu_texture_compression_support.js          NEW  device -> Set<GPUTextureFormat>
+    texture_format_preference.js                NEW  (role, support) -> ordered format list
+
+shade/renderer/texture/
+    texture_write_level.js                      NEW  one level, block-driven. The primitive.
+    texture_write_to_gpu.js                     CHG  dispatch on source kind; loops levels
+    texture_descriptor_from_texture_shade.js    CHG  reads image.format; stops inventing one
+    shade_texture_might_have_alpha.js           CHG  answers from the format
+
+shade/descriptor/texture/
+    TextureDescriptor.js                        CHG  memory_footprint via gpu_texture_format_info
+
+shade/device/mock/
+    SoftwareGPUQueue.js                         CHG  block-aware writeTexture
+```
+
+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`](../../../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
+
+```
+shade/descriptor/texture/format/
+    TextureFormat.js               NEW  @enum {string} — every GPUTextureFormat, by name
+shade/descriptor/
+    GPUTextureUsage.js             NEW  the usage bits, beside the existing GPUShaderStage.js
+```
+
+The precise state of this, because the failure is not quite where it looks:
+
+**`GPUTextureFormat` never throws.** It is a WebIDL enum, which in JavaScript is a plain string — no
+global is read, and `gpu_texture_format_info("bc7-rgba-unorm")` runs in node today. A grep confirms
+it: the identifier appears in this tree only inside JSDoc and inside one error message. So a
+`TextureFormat` enum is not what keeps node running.
+
+**What it does buy is worth having anyway**, and the third item is a real hole:
+
+1. One enumeration instead of a convention. The names already exist as the keys of `FORMATS` in
+   [`gpu_texture_format_info.js`](../../descriptor/texture/format/gpu_texture_format_info.js), which
+   even exports `gpu_texture_format_names()` for tests to sweep. Promoting that key set to a named
+   enum makes it the source rather than an implementation detail of one table.
+2. A typo becomes `undefined` at the call site instead of `'rgba8'` reaching
+   `gpu_texture_format_info` and throwing one layer down — which is a thing that has already been
+   worth writing a test for ([`SoftwareGPUValidation.spec.js:95`](../../device/mock/SoftwareGPUValidation.spec.js:95)).
+3. **`@webgpu/types` is not a dependency of this package.** Every `@param {GPUTextureFormat}` in the
+   tree therefore resolves to nothing, and `npm run generate-types` emits `any` for all of them. An
+   in-tree `@enum {string}` resolves without taking that dependency, which is the cheaper of the two
+   fixes and the one that does not put a browser typings package in a node tool's path.
+
+**The enum must be a proxy, not a parallel identifier space.** Its values are the WebGPU strings
+verbatim, so `TextureFormat.BC7_RGBA_UNORM` is passable straight to `createTexture` and no
+translation exists at any boundary — the same discipline
+[`WebGPUExtensionType`](../WebGPUExtensionType.js) already keeps (`Subgroups: "subgroups"`). A spec
+asserting `Object.values(TextureFormat)` and `gpu_texture_format_names()` are the same set is what
+stops the two drifting (§10.1).
+
+**Keys are `SCREAMING_SNAKE_CASE`** — `BC7_RGBA_UNORM`, `ASTC_6X6_UNORM_SRGB`. Settled, so it is not
+re-argued at review: this enum mirrors a specification's namespace rather than naming an engine
+concept, which is the case [`GPUShaderStage`](../GPUShaderStage.js) already answers the same way,
+and `Bc7RgbaUnorm` reads worse than the name every specification and tool writes.
+[`WebGPUExtensionType`](../WebGPUExtensionType.js)'s PascalCase is the deliberate exception, not the
+rule this follows — its keys are engine-facing labels for capabilities, not format identifiers.
+
+**Now the thing that actually throws in node.** [`TextureDescriptor.js:61`](../../descriptor/texture/TextureDescriptor.js:61)
+reads `GPUTextureUsage.TEXTURE_BINDING` as a **class field initializer** — at module load, not at
+call time. Under vitest that is covered, by a global stubbed in
+[`vitest.setup.mjs`](../../vitest.setup.mjs). Outside vitest nothing stubs it, so `import`ing
+`TextureDescriptor` from a CLI, an asset-pipeline script, or the offline encoder of §8 throws
+`ReferenceError` before a line of it runs.
+
+That matters *because of this plan*: §4.3's CPU transcoder, the container readers, and the offline
+encoder are all node-side consumers of the texture stack, and none of them is a test. The existing
+in-tree precedent is [`descriptor/GPUShaderStage.js`](../GPUShaderStage.js) — "useful for when WebGPU
+constants are not available" — which does exactly this for shader stages and was never extended to
+the other three namespaces. Add `GPUTextureUsage.js` beside it and import it rather than reading the
+global.
+
+The vitest stub stays regardless: it covers modules this plan does not touch, and a shim that is
+imported and a global that is stubbed do not conflict.
+
+---
+
+## 3. The design
+
+### 3.1 `ShadeTexelData` — the payload, and `ShadeImage.format` — the seam
+
+```js
+export class ShadeTexelData {
+    /** @type {GPUTextureFormat} */
+    format;
+
+    /** texels, of the base level */
+    width; height; depth;
+
+    /**
+     * One entry per mip, index 0 = base. Rows of blocks, tightly packed, no padding
+     * between rows or levels — exactly what gpu_texture_format_row_bytes describes.
+     * A hole is a level that has not arrived yet (§3.4).
+     * @type {(Uint8Array|undefined)[]}
+     */
+    levels;
+}
+```
+
+`ShadeImage.source` may now also be a `ShadeTexelData`, alongside the existing
+`ImageBitmap | Sampler2D | ArrayBuffer`. Two new members on `ShadeImage`, and one free function:
+
+```js
+get level_count() // 1 for everything that exists today
+get alpha_mode()  // §3.3
+
+texture_format_from_shade_image(image) -> GPUTextureFormat   // format/, not a member
+```
+
+**The format is a function, not a getter.** `ShadeImage` describes data — a channel count, a data
+type, a colour space, some bytes — and what WebGPU calls that arrangement is not the data's business.
+Keeping it off the class is what lets the encoder, the container readers and the asset pipeline hold
+an image without any of them importing a graphics API, and it is the same rule the colour package
+already follows: free functions over the model, not methods on it.
+
+For a `ShadeTexelData`, the answer is the payload's. For everything else it is exactly what
+[`inferFormatFromImage`](texture_descriptor_from_texture_shade.js:99) computes today — both of its
+arms, the `ImageBitmap` one included — [moved from the descriptor builder to the
+image](texture_descriptor_from_texture_shade.js:12). That move is the whole trick: format stops being
+something the upload path *guesses from the data* and becomes something the image *states*, and a
+compressed image states it the same way an uncompressed one does.
+
+**A plain getter, not memoised.** `color_space` is mutated after construction — see §11.2, where
+caching it silently strips sRGB from every glTF albedo map.
+
+[`texture_descriptor_from_texture_shade`](texture_descriptor_from_texture_shade.js) then loses
+`inferFormatFromImage` entirely and reads `image.format`. It is the only caller.
+
+Keeping `ShadeTexelData` as an object in `source` rather than as fields on `ShadeImage` is
+deliberate: [`optimize_texture_set`](../scene/optimization/optimize_texture_set.js:15) and
+[`serialize_scene`](../scene/serialization/serialize_scene.js:321) key maps on `image.source` by
+identity to deduplicate. A payload is one object, so both keep working untouched.
+
+### 3.2 Mip levels are data; `GenerateMipMaps` is an instruction
+
+Two independent facts, currently welded together.
+
+**Where a texture's mip levels come from** is a property of the image: it has `level_count` of them,
+and that is how many the texture gets. Nothing infers, nothing fills in.
+
+**Whether to run the mip generator** is an instruction the caller gives, and
+`ShadeTextureFlags.GenerateMipMaps` is that instruction. It is honoured or it throws:
+
+```js
+// texture_descriptor_from_texture_shade
+const generate = (shade.flags & ShadeTextureFlags.GenerateMipMaps) !== 0;
+
+let mipLevelCount;
+
+if (generate) {
+    if (!gpu_texture_format_can_generate_mipmaps(format)) {
+        throw new Error(
+            `${shade.label}: mipmap generation requested for '${format}', which cannot be a render`
+            + ` attachment. Mips for this format come from the encoder — supply them in the payload`
+            + ` and clear ShadeTextureFlags.GenerateMipMaps.`
+        );
+    }
+
+    mipLevelCount = compute_max_mip_count(image.width, image.height);
+    usage |= GPUTextureUsage.RENDER_ATTACHMENT;
+} else {
+    mipLevelCount = image.level_count;
+}
+```
+
+and [`TextureManager.contextFromShadeTexture`](TextureManager.js:128) schedules the generator if and
+only if `generate` — not if some level count comparison suggests it might be useful.
+
+Three consequences, and none of them is a fallback:
+
+- **The flag always means what it says.** Set it on an image that already has a chain and the chain
+  is regenerated; the supplied levels above 0 are not uploaded, because you asked for generated ones
+  instead. That is a real use — a DDS or KTX2 whose mips were built with a filter you do not want,
+  re-derived through [`mipmaps/filters/`](mipmaps/filters) — and not merely a pedantic reading.
+- **The flag on a block format is an error, always**, whatever the level count. Nothing on the device
+  turns a BC7 base into BC7 mips (that is §4.5, and it is not built). The message names the format
+  and says what to do instead.
+- **An uncompressed image carrying its own mips works**, which the engine cannot do today, by simply
+  not setting the flag.
+
+`gpu_texture_format_can_generate_mipmaps` is the honesty predicate: the generator renders between mip
+levels, so the format must be usable as a colour attachment. Block-compressed is the case this plan
+adds; `rgb9e5ufloat` and the `snorm` formats are non-renderable *today* and would already fail deeper
+in [`WebGPUMipmapGenerator`](mipmaps/WebGPUMipmapGenerator.js) with a worse message. One predicate
+over the format table closes both.
+
+**On `DEFAULT_FLAGS`.** [`ShadeTexture`](ShadeTexture.js:8) defaults the flag *on*, so a loader
+building a compressed texture must clear it, and forgetting to is a hard error naming the texture.
+The tempting alternative — have `ShadeTexture.from` derive the default from the image, the way it
+already derives `dimensions` — is rejected for the same reason revision 2's §3.2 was: it makes
+behaviour depend on data. An uncompressed asset that ships with mips would silently stop generating
+them, and re-exporting it without mips would silently start again. A two-line `clearFlag` at each
+compressed loader is the cheaper price.
+
+**Rule, unchanged:** `level_count` is either `1` or the full chain for the base size. A partial chain
+is a malformed payload, rejected in `ShadeTexelData`, which keeps
+[`WebGPUMipmapGenerator`](mipmaps/WebGPUMipmapGenerator.js) unchanged — it is never asked to start
+from a level other than 0. Not to be confused with a chain whose *levels have not all arrived yet*,
+which is §3.4 and is fine.
+
+A single-level block-compressed payload is **not** an error. A LUT, a UI sprite, a 4×4 icon
+legitimately has one level, and rejecting content because it might alias somewhere is the engine
+overruling the asset pipeline about a decision that is not its own. Whether a wall texture should
+have shipped with mips is a validator's question.
+
+### 3.3 Alpha mode is declared, not inferred
+
+[`texture_write_to_gpu:217`](texture_write_to_gpu.js:217) decides to premultiply from
+`image.color_space !== ColorSpace.None`. That is a proxy for "this is colour, so it probably has
+straight alpha", and it is already wrong in one direction — an `ArrayBuffer` image that arrives
+already premultiplied gets premultiplied twice. For a block payload it is unfixable: you cannot
+premultiply BC7 without decoding it.
+
+Make it a property of the data:
+
+```js
+export const AlphaMode = {
+    Opaque: 0,        // no meaningful alpha — data. Never premultiply.
+    Straight: 1,      // colour with straight alpha
+    Premultiplied: 2, // already done, by the encoder or by copyExternalImageToTexture
+};
+```
+
+Three states, not two: premultiplication is not a property of the alpha channel but of whether that
+channel *means* opacity, and collapsing `Opaque` into `Straight` premultiplies every height field and
+ORM map on upload (§11.3). `ShadeImage.alpha_mode` defaults from `color_space` where the image is
+built — `ColorSpace.None` to `Opaque`, otherwise `Straight` — which is today's rule, preserved. At
+upload:
+
+| declared | format | action |
+|---|---|---|
+| `Opaque` | either | nothing. Today's `color_space === None` behaviour. |
+| `Straight` | uncompressed | premultiply on the CPU — today's code, unchanged |
+| `Straight` | block | **throw.** The producer had to do this; nothing here can. |
+| `Premultiplied` | either | nothing |
+
+`ImageBitmap` sources keep using `copyExternalImageToTexture`'s `premultipliedAlpha`, which is the
+same decision expressed through the API that owns it.
+
+This is the one place the compressed path imposes a requirement on the *producer* rather than on the
+engine, and it is better stated loudly than discovered as dark fringes on foliage.
+
+### 3.4 One level at a time — the primitive, and what streaming needs
+
+[`texture_write_raw`](texture_write_to_gpu.js:93) computes its own layout from
+`channel_count × dataTypeByteSize(data_type)` and writes exactly one thing, at `mipLevel: 0`. Both
+have to go, and the replacement is not "a loop over levels" but **a function that writes one level**,
+with the loop as its caller:
+
+`texture_write_to_gpu` gains a level range alongside it — without one it cannot honour §3.2's rule
+that generated mips replace supplied ones, because the flag lives on the `ShadeTexture` and the
+uploader never receives it (§11.4). The same parameter is what lets a streaming arrival write exactly
+one level, so it is one addition serving both.
+
+```js
+// texture_write_level.js — the primitive
+export function texture_write_level(queue, texture, format, level, bytes, size) {
+    const w = Math.max(size[0] >> level, 1);
+    const h = Math.max(size[1] >> level, 1);
+    const d = is_3d ? Math.max(size[2] >> level, 1) : size[2];
+
+    queue.writeTexture(
+        { texture, mipLevel: level, origin: { x: 0, y: 0, z: 0 } },
+        bytes,
+        {
+            offset: 0,
+            bytesPerRow:  gpu_texture_format_row_bytes(format, w),
+            rowsPerImage: gpu_texture_format_row_count(format, h),
+        },
+        [w, h, d]
+    );
+}
+```
+
+The level, not the image, is the unit — because **meep streams**. A texture is not a thing that
+arrives; it is a thing that keeps arriving. The descriptor is built from a header (format, base size,
+level count) before any texel bytes exist, the texture is allocated once at full size, and levels
+land as the network delivers them, coarsest first.
+
+Two mechanics make that work, and both already exist:
+
+- **Sampling a partly-resident texture.** Unwritten mips read as zero, so a texture with only its
+  coarse levels present must not be sampled at its fine ones. Clamp with
+  [`SamplerDescriptor.lodMinClamp`](../../descriptor/texture/SamplerDescriptor.js:17), lowered as
+  levels arrive. This keeps the texture's dimensions and UV mapping correct, which a narrowed
+  `TextureViewDescriptor` would not — a view starting at `baseMipLevel: 8` makes the texture claim to
+  be 1/256 the size and puts every LOD computation downstream out by eight.
+- **Level-tail ordering.** The coarse levels of a mip chain are a rounding error in bytes — level 0
+  is 3/4 of the pyramid — so "everything but level 0" is a cheap first request that makes a texture
+  usable, and level 0 is a second one. Block formats make that tail *exact*: the 1×1 mip of a BC7
+  texture is one 16-byte block, which `gpu_texture_format_row_bytes` already rounds up to correctly
+  and a hand-rolled `width * bytes_per_texel` does not.
+
+Two properties of `writeTexture` worth recording, because the GPU transcode path (§4.4) has neither:
+
+- **No `bytesPerRow` alignment requirement.** That is `copyBufferToTexture`'s rule (256 bytes), not
+  `writeTexture`'s. Tightly-packed levels upload directly, with no staging buffer and no padding.
+  This is what makes "the bytes are already in JS memory" the easy case it should be.
+- **`rowsPerImage` is now always supplied**; today it is set only when `depth > 1`
+  ([:165](texture_write_to_gpu.js:165)). Harmless for 2D, required for arrays.
+
+The RGB→RGBA padding and the premultiply pass stop being branches *inside* the writer and become a
+transform producing a payload *before* it.
+
+### 3.5 Capability is the engine's; selection is the asset layer's
+
+Add to [`WebGPUExtensionType`](../../descriptor/WebGPUExtensionType.js):
+
+```js
+TextureCompressionBC:    "texture-compression-bc",
+TextureCompressionETC2:  "texture-compression-etc2",
+TextureCompressionASTC:  "texture-compression-astc",
+```
+
+and to `optional_desired` in [`Renderer.js:1165`](../Renderer.js:1165) — all three, taken when
+offered, exactly as `TextureFormatsTier1` already is. None is required.
+
+The engine then exposes two things and stops:
+
+```js
+// what this device can sample
+gpu_texture_compression_support(device) -> Set<GPUTextureFormat>
+
+// what this engine would prefer for this kind of content, best first,
+// filtered to what the device has
+texture_format_preference(role, support) -> GPUTextureFormat[]
+```
+
+`role` is albedo / normal / orm / emissive — the same distinction
+[`image_compression_quality_from_usage`](../scene/serialization/serialize_scene.js:168) already
+draws. The renderer owns this because the renderer is what knows BC5 is right for a normal map and
+BC1 is not.
+
+**It does not own what happens next.** The asset layer takes that ordered list, resolves the first
+entry to a concrete resource, and fetches only that one (§5). The engine never sees the formats it
+did not ask for.
+
+---
+
+## 4. Three ways bytes reach a texture
+
+### 4.1 The axis that actually forks
+
+`texture_write_to_gpu` already dispatches on *source kind*: an `ImageBitmap` goes through
+`copyExternalImageToTexture`, a `Sampler2D` or `ArrayBuffer` through `writeTexture`. So does
+[`VTPhysicalCache.upload`](virtual/VTPhysicalCache.js:306), independently, in the same shape.
+
+Adding compression does not add a fourth kind. It adds **texels the host cannot look inside**, which
+the `writeTexture` arm handles by asking the format table for the layout instead of computing it.
+What *does* add a third kind is a producer that runs on the device:
+
+| kind | mechanism | why it exists |
+|---|---|---|
+| external image | `copyExternalImageToTexture` | the browser decoded it; never compressed |
+| host bytes | `writeTexture` | the common case, compressed or not |
+| device-side producer | compute pass → `copyBufferToTexture` | GPU transcode (§4.4), and later runtime compression (§4.5) |
+
+The third row is not a compressed-texture feature. Procedural and GPU-generated content wants the
+same shape, and the mock device already implements the API for it
+([`SoftwareGPUCommandEncoder.js:329`](../../device/mock/SoftwareGPUCommandEncoder.js:329)) while no
+engine code uses it yet. Naming the three explicitly is worth doing regardless of this plan; doing it
+here is what keeps the transcoder from becoming a private path inside `TextureManager`.
+
+### 4.2 Transcoding is supported, and is not the main path
+
+KTX2 with Basis Universal (ETC1S or UASTC) is what the web's model pipeline emits.
+`KHR_texture_basisu` is a ratified glTF extension, `gltf-transform` and `toktx` produce it by
+default, and a viewer that cannot read it cannot read the ecosystem's models. Support it.
+
+But it is a **compatibility path, not the delivery path**. Transcoding pays CPU or GPU time on load
+to recover a format the device could have been handed directly, and meep's own pipeline hands it
+directly (§5). The distinction to hold on to:
+
+- **Third-party content** — a glTF someone exported, a model dropped on the canvas — arrives as
+  KTX2/Basis and is transcoded.
+- **First-party content** — anything meep's own tools produced — arrives already in a device format
+  and is never transcoded.
+
+Both produce a compressed texture, and below that they are the same texture.
+
+### 4.3 The CPU transcoder
+
+Signature, and the whole of its contract:
+
+```js
+// bytes in, texels out. No device, no queue, no engine.
+transcode_basis(payload, target_format) -> ShadeTexelData
+```
+
+That is the §3.1 seam exactly, so a CPU-transcoded texture enters through the ordinary door: a
+`ShadeImage` over a `ShadeTexelData`, uploaded by `texture_write_level` with no knowledge that a
+transcoder was involved. It is worker-safe by construction — it imports nothing outside `core/` —
+which is where it should run.
+
+ETC1S→BC1/BC7 and UASTC→BC7/ASTC are block-to-block transforms with no cross-block dependencies, and
+the Basis format specification is public. This repo's convention — meshopt, AVIF — is to implement
+from a specification rather than vendor a wasm blob. That is a real cost, and it should be paid
+deliberately, which is why §9 sequences it last.
+
+### 4.4 The GPU transcoder
+
+The same transform, per block, with no dependencies between blocks — which is a compute shader with
+one invocation per output block. It cannot write its result as a storage texture, because block
+formats are not storage-bindable, so it writes a buffer and copies:
+
+```
+source blocks (storage buffer, uploaded once)
+    -> compute pass, one invocation per output block
+    -> output buffer
+    -> copyBufferToTexture, one call per mip level
+    -> the ordinary compressed texture
+```
+
+Three constraints shape the output buffer's layout, and are worth writing down now rather than
+discovering at the copy:
+
+1. **`copyBufferToTexture` requires `bytesPerRow % 256 === 0`.** `writeTexture` does not (§3.4). For
+   BC7 a row is `ceil(w / 4) × 16` bytes, so alignment needs `ceil(w / 4)` to be a multiple of 16 —
+   which for the power-of-two widths of a mip chain means `w >= 64`, and every level below that needs
+   its rows padded. Lay the buffer out padded from the start.
+2. **Origin and extent must be block multiples**, as everywhere else. Trivially satisfied for a
+   whole-level copy, since the physical extent of a mip is its size rounded up to whole blocks.
+3. **One `copyBufferToTexture` per level**, since each level has its own row padding. They share one
+   encoder and one buffer.
+
+The output of this path is a `GPUTexture`, not a `ShadeTexelData` — it never touches host memory,
+which is the point. So it enters as §4.1's third kind, not through `ShadeImage`. That is a genuine
+second route into a texture, and it is justified by *where the bytes are*, not by whether they are
+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.
+
+Compressing at runtime — an ordinary decoded image in, block data out — is the same shape as §4.4
+with a different shader: a compute pass over 4×4 texel neighbourhoods, an output buffer of blocks, a
+`copyBufferToTexture`. Everything in §4.4's numbered list applies unchanged. Fixed-rate formats make
+this tractable in a way variable-rate ones never are: the output size is known before the shader
+runs, so the buffer is allocated up front and every invocation knows exactly where to write.
+
+The thing that would preclude it is treating "compressed" as a property of *how a texture was
+loaded*. It is a property of the texture's format, and a texture compressed on the device five
+seconds ago is indistinguishable from one that arrived that way. §3.1 is what buys that.
+
+---
+
+## 5. Delivery: one format per resource, chosen at request time
+
+### 5.1 The philosophy point
+
+meep streams. It is not a packaged engine that loads a level file and starts; it fetches what it
+needs, when it needs it, at the granularity it needs. The SHADE scene container
+([`serialize_scene.js`](../scene/serialization/serialize_scene.js)) is one delivery mechanism among
+several — useful, and not the model to design around.
+
+So: **a texture is not one resource with variants inside it. It is several resources, one per format,
+and the client fetches the one it wants.** The engine's part is §3.5's ordered preference list; the
+asset layer's part is turning the first entry into a URL.
+
+```js
+const formats = texture_format_preference(role, support);   // e.g. [bc7, astc-4x4]
+
+for (const format of formats) {
+    const description = resolve(logical_name, format);      // may not exist
+    if (description !== undefined) {
+        return load(description);
+    }
+}
+
+return load(resolve(logical_name, undefined));              // raw — AVIF, PNG, whatever ships
+```
+
+`resolve` must answer from a **manifest known before the first request** — which formats were built
+for this texture — or a device whose preferred format was never built pays a 404 round-trip per
+preference-list entry before reaching the fallback (§11.5). That list belongs beside whatever already
+names the texture.
+
+[`AssetManager.assignAlias`](../../../engine/asset/AssetManager.js:1396) is the mechanism that
+already exists for exactly this indirection — a logical name resolving to a concrete
+`AssetDescription`. Making that resolution format-aware, rather than inventing a parallel one, is the
+smaller change and the one that lets a texture be requested by name from anywhere.
+
+The uncompressed resource is not a fallback bolted on: it is the entry with no format constraint, and
+it is what a device with no compression support, a tool, or a test asks for.
+
+### 5.2 Which formats to build — and why revision 1 had this backwards
+
+Revision 1 argued against shipping ETC2 because "every variant added is bytes every user downloads".
+Under per-format delivery that is simply false: **a format nobody requests costs origin storage and
+build time, and zero bytes of anyone's download.** The calculus is entirely different, and the answer
+becomes "build whatever the audience's devices can sample":
+
+| Content | Format | Note |
+|---|---|---|
+| albedo, emissive | `bc7-rgba-unorm` | desktop. Best quality-per-byte for colour with alpha. |
+| normal maps | `bc5-rg-unorm` | two channels, **and Z reconstruction in the shader** — the one shader change this plan carries, §11.1 |
+| ORM, single-channel masks | `bc4-r-unorm` / `bc7-rgba-unorm` | linear |
+| anything, mobile / Apple | `astc-4x4-unorm`, coarser blocks per role | see §7.2 for why 4×4 specifically |
+| ETC2 | `etc2-rgba8unorm` | build it if the audience has it — it costs everyone else nothing |
+
+### 5.3 sRGB is not a separate resource
+
+`bc7-rgba-unorm` and `bc7-rgba-unorm-srgb` are **the same encoded bytes**; the suffix changes how the
+sampler decodes them, not what is stored. The same holds for every BC/ETC2/ASTC pair.
+
+So the delivery key is the non-srgb name, and the `-srgb` variant is chosen when the texture is
+created, from the image's `color_space` — which `ShadeImage` already carries and
+[`gltf_create_material.js:54`](../loader/gltf/gltf_create_material.js:54) already sets. This halves
+the artifact count for free, and keeps the sRGB decision where it belongs: with the content role, not
+with the bytes.
+
+The mapping that does it already exists.
+[`gpu_texture_format_srg_to_linear`](format/gpu_texture_format_srg_to_linear.js) enumerates every
+BC/ETC2/ASTC srgb pair, and so does
+[`gpu_texture_format_to_color_space`](format/gpu_texture_format_to_color_space.js) — both were
+written compressed-aware and neither has ever been handed a compressed format. What is missing is
+only the inverse direction, in the file that already holds the forward one.
+
+---
+
+## 6. Everything that breaks, and what it becomes
+
+### 6.1 Memory accounting reports zero
+
+[`TextureDescriptor.bits_per_sample`](../../descriptor/texture/TextureDescriptor.js:100) misses every
+block format, so `memory_footprint` warns and returns 0 — a compressed scene would report an empty
+texture budget through [`TextureManager.gpu_memory_usage`](TextureManager.js:172) and through the
+transient pool's `sizeOf` in [`GPUTextureAllocator`](GPUTextureAllocator.js).
+
+Rewrite `memory_footprint` on `gpu_texture_format_info`:
+
+```js
+const info = gpu_texture_format_info(this.format);
+
+total += Math.ceil(w / info.block_width) * Math.ceil(h / info.block_height) * d * info.bytes_per_block;
+```
+
+which is verbatim what
+[`frame_graph_extract_topology.js:42`](../../device/timing/profile/frame_graph_extract_topology.js:42)
+already computes. Two implementations of one thing become one — as
+`gpu_texture_format_memory_footprint`, exported from the table's own module beside
+`gpu_texture_format_row_bytes`, since that is where this file already keeps derived helpers.
+
+**`bits_per_sample` is deleted, not kept.** An earlier revision said it stays for
+[`ColorTargetState`](../../descriptor/pipeline/render/ColorTargetState.js:49); that was a misreading.
+`ColorTargetState` computes its own local sum straight from
+`gpu_texture_format_channel_bit_count` and has never called the getter, whose only caller was
+`memory_footprint` itself. A public accessor that warns and returns 0 for sixty-odd formats is worth
+removing rather than leaving for someone to find. The table it read stays, for `ColorTargetState`.
+
+**The signature is positional and every argument is required** —
+`(format, size, dimension, mip_level_count, sample_count)`. Not an options object: the two callers
+hold their fields under different names (`size` against `resolution`), so a destructured parameter
+would have been satisfied by passing a whole descriptor and would have coupled this function to the
+shape of both. And no defaults, because there is no sensible default for a mip or sample count — a
+caller that does not know them is not in a position to ask the question, and a defaulted `1` answers
+a different one convincingly. The counts are asserted instead, so a missing argument is loud rather
+than `NaN`.
+
+**A second bug, found while writing it.** Both implementations halved the *third size component*
+per mip level. That is right for a 3D texture and wrong for an array one, whose layers each carry the
+whole chain — a six-layer cube map was under-reported by nearly half. The shared function takes
+`dimension` and halves only for `"3d"`. Neither descriptor had to change to supply it; both already
+carry the field.
+
+### 6.2 The resident material atlas's fast path
+
+[`GPUResidentMaterialContext.js:338`](../material/resident/GPUResidentMaterialContext.js:338) takes
+`copyTextureToTexture` from the source into an `rgba8unorm` array when the source is square, POT and
+not sRGB — otherwise it re-renders through `render_copy_texture`. The `!is_srgb` term is standing in
+for "the formats are copy-compatible", which happens to be true today because every material texture
+is `rgba8unorm`. A BC7 source would reach it and fail validation.
+
+Replace the proxy with the fact: `source_ctx.gpu_texture.format === target.format`. Compressed
+sources then take the render path, which is correct and already exists — sampling a BC7 texture into
+an `rgba8unorm` attachment is legal, and re-encoding to fit the atlas is what that path is for.
+
+### 6.3 The software device cannot write blocks
+
+[`SoftwareGPUQueue.writeTexture:220`](../../device/mock/SoftwareGPUQueue.js:220) computes
+`texture.bytes_per_texel`, which
+[throws for block formats by design](../../device/mock/SoftwareGPUTexture.js:105). Restate the row
+loop in blocks using `gpu_texture_format_row_bytes` / `gpu_texture_format_row_count` — the same shape
+[`texture_copy.js:221`](../../device/mock/texture_copy.js:221) already uses for
+`copyTextureToTexture`. This is what makes the orchestration tier testable without a GPU, and it is
+why step 5 of §9 is not optional.
+
+### 6.4 Things that want CPU pixels
+
+| Caller | Resolution |
+|---|---|
+| [`shade_texture_might_have_alpha`](shade_texture_might_have_alpha.js) | **Improved, not broken.** It currently guesses from `source.itemSize` and otherwise defaults to `true`. The format answers exactly: `bc4`/`bc5`/`etc2-rgb8unorm` have no alpha, while `bc7`/`bc3`/`astc` may — and `bc1-rgba-unorm` and `etc2-rgb8a1unorm` carry 1-bit alpha and must answer **true** (§11.6). |
+| [`download_texture_data`](download_texture_data.js) | Debug readback, via `parse_gpu_texture_format`, whose regex cannot parse a block name. Throw a message naming the format rather than fail inside a regex. |
+| [`VTSourceImage`](virtual/source/VTSourceImage.js) | Builds mip pyramids on `OffscreenCanvas` from `ImageBitmap`. Structurally incompatible with block data — §7.3. |
+
+### 6.5 Bindless
+
+[`GPUBindlessTextureManager.js:114`](bindless/GPUBindlessTextureManager.js:114) sizes its allocation
+via `parse_gpu_texture_format(...).getByteSize()`. Its `upload` throws `Not implemented`, so nothing
+regresses today — but the arithmetic should move to `gpu_texture_format_info` when it is finished,
+for the same reason as §6.1.
+
+---
+
+## 7. Virtual textures — what this must not preclude
+
+Compressed VT is **out of scope to build** and in scope to not design out. What follows is the list
+of things that would have made it impossible, and what the plan does about each.
+
+### 7.1 WebGPU permits it
+
+Writing compressed tiles into a compressed atlas is legal. The rules, from the copy-validation
+sections of the specification, are the same three for `writeTexture`, `copyBufferToTexture` and
+`copyTextureToTexture`:
+
+- `origin.x` a multiple of the format's `block_width`, `origin.y` of `block_height`
+- `copySize.width` a multiple of `block_width`, `copySize.height` of `block_height`
+- the copy fits within the *physical* extent of the subresource, which for a compressed format is the
+  level's size rounded up to whole blocks
+
+No decompression, no intermediate, no per-tile texture. A tile upload stays exactly what it is today:
+one `writeTexture` at an offset.
+
+### 7.2 The cache is already most of the way there
+
+[`VTPhysicalCache`](virtual/VTPhysicalCache.js:69) takes a `VTCacheLayer[]`, each with its own
+`GPUTextureFormat`, and creates one atlas texture per layer. Albedo as BC7 beside normals as BC5 is
+already expressible. Three things stand between that and working:
+
+1. **`bytes_per_row ?? this.slot_size * 4`** ([:324](virtual/VTPhysicalCache.js:324)) — the one
+   uncompressed assumption in the upload. Becomes
+   `gpu_texture_format_row_bytes(layer.format, this.slot_size)`, the same call §3.4 makes.
+2. **`RENDER_ATTACHMENT`** ([:164](virtual/VTPhysicalCache.js:164)) is requested unconditionally, for
+   the `copyExternalImageToTexture` path. Illegal on a compressed format, and unnecessary — a
+   compressed layer has no external-image path to serve. Condition it on the layer's format.
+3. **`slot_size = page_size + border × 2` must be a multiple of the block size.** Slot origins are
+   `slot_index × slot_size`, so aligning the slot size aligns every origin for free — one assertion
+   in the constructor covers the whole system.
+
+That last constraint binds unevenly, which is worth spelling out. For a 4×4 block and the default
+128-texel page, any even border works (128 + 2·4 = 136 = 34 blocks). For `astc-6x6` it needs
+`(128 + 2·border) ≡ 0 (mod 6)`, i.e. `border ≡ 2 (mod 3)` — satisfiable, and a trap. **This is the
+argument for `astc-4x4` in the VT path** even where a coarser block would be chosen for an ordinary
+texture: it makes the alignment rule the same one BC already imposes.
+
+### 7.3 Borders must be baked in, which rules out one source
+
+[`VTSourceImage`](virtual/source/VTSourceImage.js) builds pyramids on `OffscreenCanvas` and resolves
+each page's border at runtime by blitting from neighbouring content. That is impossible for block
+data — border and interior share blocks at the seam, and re-encoding a block at runtime is precisely
+the machinery this is not building.
+
+So a compressed stack must come from a source whose tiles are **produced with their borders already
+inside them**, which is what [`VTSourceTiled`](virtual/source/VTSourceTiled.js) is for and what
+`VTPhysicalCache.upload` already documents ("border already baked in"). `VTSourceImage` stays the
+uncompressed runtime-virtualization path and should say so rather than produce blank pages.
+
+This is not a new limitation so much as §3.2's rule restated at tile granularity: **blocks are
+produced by an encoder that can see the texels, and nothing downstream re-derives them.**
+
+### 7.4 What this plan owes VT
+
+Nothing structural — which is the finding. Block-aware row arithmetic through
+`gpu_texture_format_row_bytes` (§3.4), format-carrying payloads (§3.1), and per-format delivery (§5)
+are what the tile path needs, and it needs them in the same form the texture path does. The tile
+becomes the streaming unit instead of the mip level, and §3.4's primitive is already written at the
+right granularity for that.
+
+---
+
+## 8. Out of scope
+
+- **Compressed 3D textures** — they need `texture-compression-bc-sliced-3d` or
+  `texture-compression-astc-sliced-3d`, and nothing in the engine wants one.
+- **Compressed virtual textures** — §7. Not built; not designed out.
+- **Runtime compression** — §4.5. Not built; not designed out.
+- **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`](../../../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.
+
+---
+
+## 9. Staging
+
+Each step is independently committable and leaves the engine working.
+
+| # | Change | Risk |
+|---|---|---|
+| 0 | **Landed.** `TextureFormat` enum; `GPUTextureUsage.js` shim beside `GPUShaderStage.js`; `TextureDescriptor` **and `TextureResourceDescriptor`** import it (§2.1, §9.1) | none. Unblocks every node-side consumer this plan later adds. The `{GPUTextureFormat}` → `{TextureFormat}` JSDoc sweep is mechanical, changes no behaviour — both are strings — and still lags. |
+| 1 | **Landed.** `memory_footprint` onto `gpu_texture_format_info`; duplicate in `frame_graph_extract_topology` dropped; `bits_per_sample` deleted; array-vs-3D mip depth fixed (§6.1) | none — it fixes two wrong numbers |
+| 2 | **Landed.** `AlphaMode`, `ShadeTexelData`, `ShadeImage.format` / `.level_count` / `.alpha_mode`; descriptor builder and uploader read them (§3.1, §3.3, §9.2) | pure refactor. **No new formats.** Every existing texture test passed with its assertions untouched — `"color_space None skips premultiplication entirely"` included, which is the §11.3 guard. |
+| 3 | **Landed.** `texture_write_level` as the primitive; `texture_write_to_gpu` becomes its caller (§3.4, §11.4, §9.3) | as above — the existing upload tests pass with their assertions untouched |
+| 3b | **Landed.** `chunk_decode_tangent_normal` at the five normal-sample sites; `texture_format_preference` now leads with BC5 (§11.1, §9.8) | one shared chunk, verified on today's RGB normal maps — the stored blue channel is redundant, so the decode agrees with it to 5 decimal places |
+| 4 | **Landed.** `GenerateMipMaps` honoured or thrown; levels otherwise come from the image; `texture_write_to_gpu` gains a required `level_count` (§3.2, §9.5) | behaviour identical for every image that exists today — nothing the engine currently builds can reach the new throw |
+| 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/`](../../../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
+6, the engine is strictly better than it is now (correct memory accounting, one format table,
+declared alpha, level-at-a-time upload, mips from data) and nothing has been added that must be
+maintained for a feature that did not land.
+
+### 9.1 What step 0 actually shipped
+
+Two class fields read `GPUTextureUsage` at module load, not one:
+[`TextureDescriptor.js:61`](../../descriptor/texture/TextureDescriptor.js:61) and
+[`TextureResourceDescriptor.js:56`](../../device/graph/TextureResourceDescriptor.js:56). Both now
+import the shim. Everything else in the tree that touches the namespace — 139 sites — reads it inside
+a function body or a default parameter, which is call-time and only reachable from a node tool that
+gets that far; those stay on the global for now and convert with the JSDoc sweep.
+
+[`TextureFormat`](../../descriptor/texture/format/TextureFormat.js) is generated from the key set of
+`FORMATS`, so the two cannot start out disagreeing. 101 formats, and the key transform is mechanical
+for every one of them — no exceptions to hand-tune, which is what made the reversibility test worth
+writing.
+
+The node-side test was checked against its own absence: with the shim import removed from
+`TextureDescriptor`, it fails with `ReferenceError: GPUTextureUsage is not defined`, which is the
+regression it exists to catch. A test that passes with and without the fix would have been the §11
+failure mode applied to the test suite.
+
+### 9.3 What step 3 actually shipped
+
+**`texture_write_level(queue, texture, level, bytes)`** — and nothing else. §3.4 sketched it taking
+`format` and `size` too; both come off the texture, which is the authority on all three because it is
+the thing being written into, and passing them would be one more pair of things that can disagree.
+
+**No level range, and no optional parameter.** §11.4 asked for one so the uploader could honour
+§3.2's "generated mips replace supplied ones". Two named functions answer that better than one
+function with an optional argument: `texture_write_to_gpu` writes the whole image,
+`texture_write_level` writes one level, and step 4 calls whichever the flag calls for. The decision
+belongs where the flag is, which is `TextureManager`, not threaded through the uploader as a
+parameter it would have to interpret.
+
+The row stride the raw path used to compute for itself is gone — it comes from the format now, which
+also fixes the padded case honestly: after RGB→RGBA padding the stride is the texture's four
+channels because the *texture's format* says four, rather than because the padding code remembered to
+recompute it.
+
+**One test fixture changed, no assertions.** `texture_write_to_gpu.spec.js`'s stand-in `GPUTexture`
+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`](../../../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
+graphics API to get it.
+
+**It reads what first-party tooling emits and refuses everything else by name**, one refusal per
+feature, each naming the scheme or the format: BasisLZ, Zstandard, an unknown scheme number, ETC1S,
+UASTC, an unmapped `vkFormat`, array textures, cube maps, 1D textures, 3D block-compressed payloads,
+`levelCount == 0` on a block format, a flipped `KTXorientation`, a non-identity `KTXswizzle`.
+
+#### The reuse sweep, and what it moved
+
+§9.4's lesson was applied before writing rather than discovered afterwards. Three things came out of
+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 `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
+  container, so it is stated once at `init`** rather than at each of the eighty-odd accessor calls —
+  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](../../../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
+  belongs in the table's own module beside `gpu_texture_format_row_bytes` — which is what §6.1
+  already decided for derived helpers — and a container reader cannot import from
+  `shade/renderer/`. The three sites that had it written out inline (`SoftwareGPUTexture`,
+  `gpu_texture_format_can_generate_mipmaps`, `download_texture_data`) now call it, so the reader's
+  two uses are the fourth and fifth callers of one predicate rather than copies five and six.
+- **Nothing else was written from scratch that already existed.** Level byte lengths are
+  `ShadeTexelData`'s, which checks them against the format table; the chain-length rule is
+  `ShadeTexelData`'s; the identifier comparison is `isArrayEqualStrict`; the key/value strings are
+  `utf8_decode`. The reader computes no extent and no row stride at all — it reads `byteLength` from
+  the level index and lets the payload type disagree with it if the file is wrong.
+
+**It is not behind [`Codec`](../../../engine/asset/codec/Codec.js).** That interface is
+`async decode(Uint8Array) -> T` and lives under `engine/asset/loaders/image/`, so subclassing it
+would put engine code in a container reader's import graph and make a synchronous byte-shuffle a
+promise for no reason. The image-codec review is still right that every image format should reach the
+engine through one door — but the door is an adapter, written when the compressed-texture *loader*
+lands and has somewhere to put the `ShadeImage` it builds. Nothing consumes this reader yet, exactly
+as nothing consumed step 7 until now.
+
+#### Where the plan was overturned, and the judgement calls
+
+**ZLIB is read, not refused.** §11.6 says "transport compression is the delivery layer's business",
+and it is right — about what meep *writes*. It says nothing about what meep must be able to *read*,
+and a KTX2 file with `supercompressionScheme` 3 holds device-format blocks behind an RFC 1950 stream
+that `pako` — already a dependency, already inflating every PNG — undoes in one call. Refusing it
+would have meant refusing a file the engine can use completely, over a wrapper it can already remove.
+The declared `uncompressedByteLength` is checked against what the stream actually inflates to, and
+then `ShadeTexelData` checks that against the format table, so a mislabelled file fails twice rather
+than uploading garbage. Zstandard stays refused because there is no decompressor here at all, and
+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`](../../../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
+from the PNG loader for the sake of a wrapper whose whole content it wants to opt out of.
+
+**`levelCount == 0` is refused for a block format and read as one level otherwise.** It means
+"generate the mip chain at load", which is an *instruction*, and §3.1's payload carries data. The
+engine's instruction is `ShadeTextureFlags.GenerateMipMaps`, honoured or thrown by §3.2, and it is
+the caller's to state — so the reader returns the level the file physically contains and does not
+pretend to carry the request. For a block-compressed payload the request cannot be honoured by
+anything at any layer, so it is refused here, naming the format, rather than left to fail later with
+a message about a flag the file never mentioned.
+
+**Both BC1 spellings map to `bc1-rgba-unorm`.** `VK_FORMAT_BC1_RGB_*` and `VK_FORMAT_BC1_RGBA_*` are
+the same sixty-four bits; the difference is whether a three-colour-mode block's fourth index reads as
+opaque black or transparent, and WebGPU exposes only the RGBA name. Mapped rather than refused,
+because an encoder targeting the RGB spelling has no alpha to store and so no reason to emit that
+index — refusing would reject a large share of real BC1 content over a difference the content does
+not contain. Written down in the table rather than left as a coincidence.
+
+**Two refusals the plan never mentioned**, both because the failure is a *silent misread* rather than
+an error: `KTXorientation` other than right-down loads the texture upside down, and `KTXswizzle`
+other than `rgba` loads it in the wrong channels. Neither looks like a bug in the reader. Reading the
+key/value section costs forty lines and turns both into a named refusal quoting the value. The third
+axis of a 3D orientation is checked strictly — `rdi` and not `rdo` — which may be stricter than real
+files need; the refusal names the value, so a file that is genuinely fine is a one-line change rather
+than a mystery.
+
+**The `vkFormat` table names its gaps.** 97 numbers map to 95 formats — 54 rows onto 52 distinct
+block-compressed ones, the two BC1 spellings collapsing, and 43 onto the uncompressed ones.
+Twenty-three more are *named* with a reason they cannot be mapped — three-channel formats,
+single-channel sRGB, `A2R10G10B10` and `A8B8G8R8_PACK32` byte order, depth and stencil — so a file
+carrying one is told what is wrong with it rather than handed a number. Anything outside both tables
+is refused by number, which is the honest answer for a format nobody here has heard of.
+
+A spec asserts that **every colour format in `gpu_texture_format_info` is reachable from some
+`vkFormat`**, which is the tripwire for a format landing in the engine's table and not in this one.
+That assertion started out scoped to block-compressed formats, on the stated theory that several
+uncompressed formats had no Vulkan counterpart; measuring it during review showed the theory false —
+all 43 are mapped — so the tripwire is now as wide as the mapping, and depth and stencil are the only
+exclusions.
+
+#### Testing, and the gap in it
+
+Forty specs over the reader and its `vkFormat` table, and six more over the cursor's new parameter —
+the same bytes reading differently in each order, and `init` refusing to guess. The two that could
+have passed against a broken reader were checked against their own absence:
+
+1. **Level ordering.** The level index is base-first and the image data is conventionally stored
+   smallest-first, so a reader that walked the file would return a plausible payload with the pyramid
+   upside down — right byte counts, right level count, every texture blurred to its 1×1 mip. The
+   fixture builder lays the data out either way; with `cursor.seek(byte_offset)` removed the
+   smallest-first test fails and the base-first ones still pass, which is exactly the asymmetry that
+   makes it worth having.
+2. **Truncation.** Removing the per-level bounds check fails both the truncated-file test and the
+   level-index-past-the-end test.
+
+**The fixtures are synthesised, and that is the gap.** `ktx2_build` writes the container from the
+specification, so the reader and the fixture share one reading of it: a misreading would be
+reproduced identically on both sides and pass. What synthesis buys is every malformed variant as a
+one-line override, which a committed binary cannot give, and it is why the whole refusal surface is
+covered at all. The missing check is a file from `toktx` — an independent authority on the layout —
+and until one is read the byte offsets in this reader are believed rather than known. First contact
+with a real file is the test that has not been run.
+
+#### What an adversarial pass found afterwards
+
+Three things, all in the parts that were argued for hardest.
+
+**`pako` throws a bare string, and the ZLIB path let it escape.** `pako.inflate` on a corrupt stream
+throws `"incorrect header check"` — a `String`, not an `Error`, with no `.message` and nothing naming
+the file or the level. So the one capability added beyond what this step was asked for was the one
+path that did not refuse by name, and the JSDoc's `@throws {Error}` was false for it. Now wrapped,
+and the message names the level. Worth recording *why* it was missed: the comment justifying
+`pako.inflate` over `png_inflate` listed two differences and was satisfied with them — multi-chunk
+streams and lenient adler32 — when there was a third, and the third was the one that mattered. An
+argument for not reusing something is only as good as its enumeration of what the thing does.
+
+**`ShadeTexelData` refuses a legitimate 3D file with a full mip chain**, and this reader is the first
+code able to reach it. Its per-level byte lengths are 3D-correct — `level_byte_length` goes through
+`texture_mip_extent(…, "3d", …)`, which halves depth — but its chain-length rule is
+`compute_max_mip_count(width, height)`, which does not see depth at all. A 4×4×16 volume has a
+five-level chain and the constructor insists on three; `level_byte_length` will meanwhile happily
+size the two levels the constructor rejects. The type disagrees with itself.
+
+**And it is not only there.** `texture_descriptor_from_texture_shade.js:50` computes the *generate*
+path's `mipLevelCount` the same way, as do `TextureResourceDescriptor` and `GPULightCollection` — so
+a 3D texture asking for generated mips gets a short chain today, with no container reader involved.
+That makes it §9.4's finding again, one axis over: the depth rule was given a home in
+`texture_mip_extent` and the *count* rule never was. Deliberately not fixed in that commit — it is a
+change to step 2's contract and to call sites that have nothing to do with KTX2, and burying it in a
+container reader's commit is how a shared invariant gets changed without anyone reviewing it. The
+reader refuses rather than misreads in the meantime, which is the behaviour that matters.
+
+**Fixed since, on its own.** `texture_mip_level_count(width, height, depth_or_layers, dimension)` is
+now the counterpart §9.4 was missing, beside the extent in the same file, and
+`compute_max_mip_count` — which took no depth and so could not be told — is gone rather than
+deprecated, because a depth-blind mip count left reachable is a thing someone reaches for. All six
+callers went through it, and the sweep is the reason to have done it as its own change rather than
+only patching the two sites that were wrong:
+
+- `ShadeTexelData` and `texture_descriptor_from_texture_shade` were the live bugs — a volume's chain
+  and a volume's *generated* chain, both truncated to what width and height implied.
+- `TextureResourceDescriptor.from` had the dimension in its own argument list and was not passing it,
+  which mattered: `graph_import_texture` re-derives `mipLevelCount` from resolution for anything with
+  mips, so a 3D import would have had its chain recomputed short. It now also reads the padded
+  `r.resolution` rather than the raw argument, so a two-axis caller reads as depth 1 and not
+  `undefined`.
+- `GPULightCollection` (equirectangular environment), `HierarchicalZBuffer` (screen-space depth
+  pyramid) and `GPULightMap` are 2D and were never wrong. The first now asks its descriptor for its
+  dimension instead of the call site assuming one; the other two say `"2d"` at the call, which is the
+  whole of what they know.
+
+A spec pins the part that matters more than any single call site: for a range of shapes, the level
+the count ends on is the one where the halving axes reach 1, and the level before it is not. The
+count and the extent agree because they are derived from one rule, rather than because both call
+sites were written by someone who remembered.
+
+Also corrected: an exported constant with no importers (`BC1_RGB_NOTE`, now prose beside the rows it
+explains), a `supercompression_scheme_name` whose only caller could never reach anything but its
+fallback — producing "supercompressionScheme 7 is an unknown scheme, which this reader does not
+know" — and an unused `truncate_to` option in the fixture builder. Three tests were added for
+promises nothing checked: an `ArrayBuffer` and an offset view as input, and a multi-level ZLIB file.
+The new ZLIB guard was checked against its own absence like the other two.
+
+### 9.9 What step 7 actually shipped, and where §5.1 was wrong
+
+§5.1 said `AssetManager.assignAlias` "is the mechanism that already exists for exactly this
+indirection" and proposed making alias resolution format-aware. **That was wrong, for the reason
+`ShadeImage.format` was wrong:** it would push `GPUTextureFormat`, `TextureRole` and a device
+capability set into the generic asset system, which loads sounds and fonts and JSON and has no
+business knowing what a texel block is.
+
+The indirection belongs in the texture layer, and once it is there `AssetManager` needs no change at
+all. [`TextureVariantSet`](TextureVariantSet.js) is §11.5's manifest — which encodings exist and
+where, known before the first request. [`texture_variant_select`](format/texture_variant_select.js)
+walks the preference list against it and returns a path, which the existing `AssetManager.promise`
+loads like anything else.
+
+**It returns a path and nothing else.** Not the format it chose: a reader determines a payload's
+format from the payload's own header, which is the only source that cannot be wrong, and handing back
+a format alongside would invite someone to trust the manifest over the bytes. That also means the
+manifest is deliberately dumb about content — a manifest that lies produces a failed read rather than
+a texture full of garbage.
+
+**It always answers.** There is no "nothing suitable" case for a caller to handle: a device with no
+compression, or one whose preferred formats were never built, gets the fallback — the same path a
+tool or a test asks for. A texture with no universally readable encoding is a broken manifest, not a
+runtime condition.
+
+**Nothing consumes this yet**, which is the plan's shape rather than an oversight: step 8's KTX2
+reader is the first caller, and this is the contract it is written against.
+
+### 9.8 What step 3b actually shipped
+
+[`chunk_decode_tangent_normal`](../../shader/chunk/geometry/normal/chunk_decode_tangent_normal.js)
+reconstructs Z from XY instead of reading the blue channel, at all five sites. §11.1's resolution,
+unchanged by contact with the code: one decode serving both channel counts, so nothing branches on
+the format and no pipeline is compiled twice.
+
+Verified three ways, because the failure mode is a shader that renders wrong rather than one that
+fails to build:
+
+1. **Against the blue channel it ignores.** The chunk spec runs in the WGSL emulator and asserts the
+   reconstruction agrees with the stored Z to five decimals over a set of normals, and that a
+   two-channel texel decodes identically to a three-channel one. That is what makes this safe to land
+   before any compressed texture exists — every RGB normal map in the engine should look exactly as
+   it did.
+2. **Against a missing registration.**
+   [`normal_decode_call_sites.spec.js`](../../shader/chunk/geometry/normal/normal_decode_call_sites.spec.js)
+   compiles each site and asserts the function is declared exactly once and called. Checked against
+   its own absence: removing one registration fails it with an `undeclared-call` diagnostic. Three of
+   the four sites had **no WGSL compile coverage at all** before this — only the VT shader did.
+3. **Against the `max(0, …)` guard.** Filtering and lossy compression push samples off the unit
+   circle; without it `sqrt` of a negative gives `NaN` rather than a normal in the tangent plane.
+
+`texture_format_preference` now leads with `bc5-rg-unorm` for normals, and §9.7's tripwire — the test
+asserting two-channel formats were *absent* — has fired and been replaced by its opposite. That is the
+payoff: two channels of budget where four were being spent, on the one map type where a colour codec
+bands visibly.
+
+### 9.7 What step 6 actually shipped
+
+The three features are requested when offered and never required, beside `TextureFormatsTier1`.
+[`gpu_texture_compression_support`](format/gpu_texture_compression_support.js) turns "which features
+did we get" into "which formats may we ask for", deriving the families from the format table's own
+names rather than a second list — 14 BC, 10 ETC2/EAC, 28 ASTC.
+
+[`texture_format_preference`](format/texture_format_preference.js) is the engine's whole part in
+choosing an encoding, over a new [`TextureRole`](../TextureRole.js). It answers what would be good and
+stops: no fetching, no knowledge of what was built, no fallback — all of which are the asset layer's,
+in step 7.
+
+**It deliberately offers no two-channel format for normals.** `bc5-rg-unorm` is the right answer and
+handing it out now would render black, because §11.1's Z reconstruction has not landed: BC5 samples as
+`(x, y, 0, 1)` and the five normal reads are still `.rgb * 2.0 - 1.0`. There is a test asserting the
+absence, which is a tripwire meant to fail — and be deleted — in the change that fixes the shader.
+Until then the list offers three-channel formats, which are worse for normals and correct.
+
+**§6.2's guard found the real invariant.** `!is_srgb` was standing in for "the formats are
+copy-compatible", true only because every material texture was `rgba8unorm`. It is now
+`source.format === target.format`, which covers every format at once.
+
+**§6.4's alpha rewrite regressed a case, and the test caught it.** Answering purely from the format
+called every three-channel image possibly-transparent: the upload pads RGB to RGBA because WebGPU has
+no three-channel format, so the *texture* has alpha while the *content* has none. Loose pixels are now
+answered by their channel count first, and only a texel payload — whose encoder already chose a
+format that says how many channels there are — is answered by the format alone. `bc1-rgba-unorm`
+correctly reports alpha (§11.6).
+
+### 9.6 What step 5 actually shipped
+
+§6.3 proposed restating the queue's row loop in blocks. §9.4's lesson said to look at the mock first,
+and looking found that no restating was needed: `writeTexture` is `copyBufferToTexture` with the bytes
+supplied inline, and [`texture_copy.js`](../../device/mock/texture_copy.js) already had both halves —
+`texture_copy_refusal` and `texture_copy_execute`, block-aware since they were written, and already
+used by `SoftwareGPUCommandEncoder` for the buffer version.
+
+So `writeTexture` now wraps its `data` and `dataLayout` as a buffer endpoint and calls the same two
+functions. Three things came with that beyond block support: multi-layer writes (the
+`depth === 1` assertion is gone), `rowsPerImage` honoured rather than ignored, and stricter
+validation — `texture_endpoint_refusal` turned out to be a superset of the queue's private
+`texture_write_refusal`, adding a `copyable` check, a mip-range check and a bounds check, with the
+same wording for the three they shared.
+
+[`compressed_texture_upload.spec.js`](compressed_texture_upload.spec.js) is §10.4: a BC7 payload
+through `TextureManager`, the descriptor builder and the uploader, asserted byte-for-byte at every
+level, with no GPU. Checked against its own absence — against the pre-step-5 queue it fails with
+`bytes_per_texel: 'bc7-rgba-unorm' is block-compressed`.
+
+Its "no validation error" assertion is itself guarded: the mock reports refusals through an error
+scope rather than by throwing, so a test that watched the wrong channel would pass against a texture
+nothing had been written to. A second test writes to a texture without `COPY_DST` and asserts the
+error does land, which is what makes the first one mean something.
+
+### 9.5 What step 4 actually shipped
+
+The flag is now an instruction. `generate` is read once, the format is checked against
+[`gpu_texture_format_can_generate_mipmaps`](format/gpu_texture_format_can_generate_mipmaps.js), and a
+request that cannot be honoured throws with a message naming the texture, the format and what to do
+instead. Otherwise `mipLevelCount` is `image.level_count` — no inference, no comparison.
+
+**The predicate covers three classes and says so.** Block-compressed and depth/stencil come out of
+`gpu_texture_format_info`; `snorm` and `rgb9e5ufloat` are a listed set. It is deliberately *not* a
+general renderability table — `rg11b10ufloat` is renderable only behind a feature and this does not
+check for it — because a partial table presented as complete is worse than a predicate whose scope is
+written down. Everything outside those classes answers `true`, which is correct for every format the
+engine currently produces.
+
+**`texture_write_to_gpu` did get a `level_count` after all** — required, not optional, so every caller
+states it. Step 3 argued two named functions were enough; that was wrong for one case, which is a
+`ShadeTexelData` carrying a chain *and* the generate flag. `texture_write_level` cannot serve it,
+because an `ImageBitmap` still has to go through `copyExternalImageToTexture` and `TextureManager`
+should not be re-deriving which source kind it holds. A required argument keeps the decision at the
+caller without reintroducing an optional one.
+
+**Nothing existing can reach the new throw.** `infer_format_from_parameters` only ever produces
+`unorm`, `unorm-srgb`, `uint` and `float` endings — never `snorm`, never a packed format — so no
+image the engine builds today has a format the generator would refuse.
+
+### 9.4 One mip-arithmetic rule, four copies
+
+`SoftwareGPUTexture` has had `mip_width` / `mip_height` / `row_bytes` / `row_count` / `layer_bytes`
+all along — the oldest and most complete statement of per-level layout in the tree, and one this plan
+walked straight past. Steps 1, 2 and 3 each added another copy of the same arithmetic
+(`memory_footprint`'s loop, `ShadeTexelData.level_byte_length`, `texture_write_level`), which is
+precisely the outcome §0 exists to prevent, committed three times in a row.
+
+Each rule now has one home:
+
+- [`texture_mip_size(size, level)`](../../util/texture_mip_extent.js) — halve, floor at one.
+- [`texture_mip_extent(width, height, depth_or_layers, dimension, level)`](../../util/texture_mip_extent.js)
+  — that, plus **only a 3D texture's depth halves**. This is the one worth naming: written by hand it
+  reads as an obvious `>> level` on all three components, and that mistake is what §6.1 found already
+  shipped in two places.
+- [`texture_mip_level_count(width, height, depth_or_layers, dimension)`](../../util/texture_mip_extent.js)
+  — how long the chain the other two describe actually is: as long as the longest axis that halves,
+  which is the *same* distinction one derivative up. Added after step 8, once §9.10 found that the
+  extent rule having a home and the count rule not having one is a gap and not a tidiness complaint —
+  `ShadeTexelData` had ended up sizing levels it then refused. It lives in the same file as the extent
+  so the two cannot drift.
+- [`gpu_texture_format_level_bytes`](../../descriptor/texture/format/gpu_texture_format_info.js) —
+  `row_bytes × row_count × layers`, which was written out in four.
+
+`SoftwareGPUTexture` keeps its API — `texture_copy` and `SoftwareGPUQueue` both use it — and delegates
+to these. Nothing in `src/shade/` computes a mip dimension inline any more; the only surviving
+`>> level` is inside `texture_mip_size`, and the only `log2` is inside `texture_mip_level_count`.
+
+The general lesson for the rest of the plan: **the mock is not a lesser implementation.** It was
+written against the format table from the start and had the block-aware answer to three of these
+questions before the renderer did.
+
+### 9.2 What step 2 actually shipped
+
+`alpha_mode` **derives lazily, and cannot be captured at construction.** §11.3 said the default comes
+from `color_space` "at the point that constructs the image", which would have been wrong for the same
+reason §11.2 was: nine places assign `color_space` *after* the image exists, and two of them assign
+`ColorSpace.None` — `shade_load_data_image` and `build_lut_fog_parameters_jendersie_deon`. A value
+captured at construction would premultiply exactly the data textures the rule exists to protect. It
+is a getter over a private override: unset, it derives; set, it wins and keeps winning.
+
+**`AlphaMode.Unspecified` is a member of the enum**, not a `undefined` sitting in a field typed as
+one. "Nothing has said yet" is a state the field genuinely has, so it gets a name; assigning it is
+also how a caller goes back to deriving after an override. The getter resolves and never returns it,
+which is its own test.
+
+**The format lives in `format/texture_format_from_shade_image.js`**, not on `ShadeImage`. After the
+move the image imports neither `isImageBitmap` nor the inference — it is back to describing data and
+nothing else.
+
+`infer_format_from_parameters` moved to
+[`format/infer_format_from_parameters.js`](format/infer_format_from_parameters.js), and its spec with
+it. `ShadeImage` needed it, and a data model importing from the descriptor *builder* is a dependency
+pointing the wrong way. The spec's assertions are byte-identical; only its import paths changed.
+
+`texture_write_to_gpu` now asks `image.alpha_mode` instead of re-deriving `color_space !== None`
+inline. Provably the same decision today — which is what the untouched regression test shows — and
+the point is that it is now a decision an image can be *told*.
+
+Steps 8 and 9 are separable on purpose: **a KTX2 file that already holds BC7 needs no transcoder**,
+and that is what first-party tooling produces. The transcoder is only for ETC1S/UASTC payloads, which
+is third-party content, which is why it can wait behind everything else.
+
+---
+
+## 10. Testing
+
+Per the tiers this repo uses:
+
+1. **The enum does not drift.** `Object.values(TextureFormat)` and `gpu_texture_format_names()` are
+   the same set — the one check that keeps §2.1's enum a view of the format table rather than a
+   second copy of it. Cheap, and it fails the moment a new format lands in one and not the other.
+2. **Node-side import.** A spec that imports `TextureDescriptor` with the vitest globals *removed*
+   proves the §2.1 shim actually replaced the load-time global read, rather than the stub quietly
+   continuing to cover for it. Without this the fix is untested by construction.
+3. **Pure functions.** `gpu_texture_format_row_bytes` against hand-computed BC7/BC5/ASTC sizes
+   including non-block-multiple widths — a 5-texel-wide BC7 row is two blocks, the case the current
+   uploader's arithmetic gets wrong. `ShadeTexelData` rejecting a partial chain, and a payload whose
+   byte length disagrees with its declared format and size. `texture_format_preference` returning
+   only formats in the support set, and returning empty rather than guessing.
+4. **Software device.** Build a `ShadeImage` over a synthetic BC7 payload, run it through
+   `TextureManager`, and assert the mock texture's per-level bytes are exactly the input — end to end
+   through `texture_descriptor_from_texture_shade` and `texture_write_level`, with no GPU. This is
+   the test that proves the two paths really are one path.
+5. **Streaming.** The same, but delivering levels out of order, coarsest first: each arrival writes
+   only its own level, and `lodMinClamp` tracks the finest resident one.
+6. **Descriptor, and the §3.2 instruction.** Over a compressed image with the flag clear:
+   `RENDER_ATTACHMENT` is not set and `mipLevelCount` equals the supplied level count. With the flag
+   set: throws, **for one supplied level and for a full chain alike** — the case that would regress
+   silently if anyone reintroduced a level-count comparison. Over an uncompressed image with a full
+   chain and the flag set: the generator is scheduled and only level 0 is uploaded.
+7. **Alignment, for §7's benefit.** `VTPhysicalCache` constructed with a compressed layer asserts on a
+   `slot_size` that is not a block multiple — the one check that keeps the tile path honest, worth
+   writing before the tile path exists.
+8. **Playground.** One scene, loaded with support forced to bc / astc / none, compared visually and by
+   `TextureManager.gpu_memory_usage` — which, after §6.1, is the number that shows the feature
+   working: the same scene at roughly a quarter of the VRAM.
+
+---
+
+## 11. Adversarial pass
+
+Written against revision 4, before any code. Four findings change the design; two are corrections of
+fact. Each was checked against the tree rather than against the argument that produced it.
+
+### 11.1 "No shader changes" is false, and §5.2 is what makes it false
+
+**§0 claims no shader changes. §5.2 recommends `bc5-rg-unorm` for normal maps. These cannot both
+stand.**
+
+BC5 has two channels. A sample returns `(x, y, 0, 1)`. Every normal-map read in the tree is
+`.rgb * 2.0 - 1.0`, at five sites:
+
+| Site | |
+|---|---|
+| [`fragment_gbuffer.js:325`](../material/standard/fragment_gbuffer.js:325) | the main deferred path |
+| [`fragment_gbuffer_vt.js:129`](../material/standard/fragment_gbuffer_vt.js:129) | virtual textures |
+| [`chunk_sample_material_data.js:205`](../path_tracer/shader/chunk_sample_material_data.js:205) | path tracer |
+| [`chunk_forward_shade_standard_fragment_ibl.js:40`](../rasterize/native/oit/chunk_forward_shade_standard_fragment_ibl.js:40) | forward / OIT |
+| [`chunk_forward_shade_standard_fragment_brick4.js:37`](../rasterize/native/oit/chunk_forward_shade_standard_fragment_brick4.js:37) | forward / OIT |
+
+Against a BC5 texture each of those computes `z = 0 * 2 - 1 = -1`: every normal points directly into
+the surface. Not subtly wrong — no lighting at all.
+
+**Resolution: always reconstruct Z, never read it.** A tangent-space normal has `z > 0` by
+construction, so `z = sqrt(max(0, 1 - x² - y²))` is exact for a unit normal and is *equally correct
+for an RGB source*, whose stored blue channel is redundant. One chunk, applied at all five sites,
+serving BC5 and RGB identically — no variant, no branch on format, nothing that would need
+[per-format codegen](../../wgsl).
+
+So the honest statement is not "no shader changes" but:
+
+> **No shader *variants*.** One decode change, shared by compressed and uncompressed alike, and after
+> it the sampling path does not know which it has.
+
+Which is the invariant of §0 restated, rather than a hole in it — but it is a change to five shaders
+and it belongs in §9, not in a sentence claiming it does not exist. Two caveats worth stating: this
+assumes tangent-space normals (what glTF's `normalTexture` is, by specification), and the VT normal
+default `vec4(0.5, 0.5, 1.0, 1.0)` still reconstructs to `z = 1` unchanged.
+
+The alternative — BC7 for normals, keeping `.rgb` — costs no shader work and real quality: BC7 spends
+its budget on three channels where BC5 spends the same 8 bpp on two. Recommendation stands with BC5,
+now that its actual price is on the table rather than hidden behind a false claim.
+
+### 11.2 `ShadeImage.format` cannot be memoised — the inputs are mutated after construction
+
+§3.1 says format is `infer_format_from_parameters(...)` "and memoised". It cannot be.
+[`gltf_create_material.js:86`](../loader/gltf/gltf_create_material.js:86) and
+[`:54`](../loader/gltf/gltf_create_material.js:54) set `texture.image.color_space = ColorSpace.SRGB`
+**after** [`load_gltf.js:404`](../loader/gltf/load_gltf.js:404) has already built the `ShadeImage`.
+A format cached at construction is `rgba8unorm` forever, and every albedo and emissive texture in
+every glTF silently loses its sRGB decode.
+
+`format` is therefore a plain getter, recomputed. It is a table lookup and a string concat on a path
+that runs once per texture, not per frame.
+
+§3.1 was also inaccurate about *what* it computes:
+[`inferFormatFromImage`](texture_descriptor_from_texture_shade.js:99) has two arms, and the
+`ImageBitmap` one does **not** call `infer_format_from_parameters` — it returns `rgba16float`,
+`rgba8unorm-srgb` or `rgba8unorm` directly. Both arms move to `ShadeImage.format` unchanged.
+
+**A pre-existing bug this surfaces, worth its own fix.** Images are deduplicated
+([`load_gltf.js:403`](../loader/gltf/load_gltf.js:403) indexes by glTF image index), so one
+`ShadeImage` can back two textures. `gltf_create_material` then assigns `color_space` per *material
+slot*. An image used as both a base-colour and an ORM map gets whichever material was visited last —
+today that flips a decode, and under this plan it flips a format. Not caused by this plan, made
+load-bearing by it.
+
+### 11.3 The `alpha_mode` default silently premultiplies every data texture
+
+§3.3 defaults `alpha_mode` to `Straight` and premultiplies `Straight` + uncompressed. Today's rule is
+`premultiplyAlpha = image.color_space !== ColorSpace.None`
+([texture_write_to_gpu.js:217](texture_write_to_gpu.js:217)) — so **non-colour data is never
+premultiplied**, and under §3.3 as written it would be. Height fields, masks, ORM maps, LUTs: all
+scaled by their alpha channel on upload.
+
+There is a regression test named for exactly this — `"color_space None skips premultiplication
+entirely"` ([texture_write_to_gpu.spec.js:84](texture_write_to_gpu.spec.js:84)) — which §9 step 2
+claims will pass unmodified. It would not.
+
+**Resolution: three states, not two.** Premultiplication is not a property of the alpha channel; it
+is a property of whether the channel *means* opacity.
+
+```js
+export const AlphaMode = {
+    Opaque: 0,        // there is no meaningful alpha — data. Never premultiply. (ColorSpace.None today)
+    Straight: 1,      // colour with straight alpha. Premultiply if uncompressed; throw if block.
+    Premultiplied: 2, // already done, by the encoder or by copyExternalImageToTexture
+};
+```
+
+The default is derived from `color_space` at the point that constructs the image — which preserves
+today's behaviour exactly, keeps the regression test green, and gives a compressed payload somewhere
+truthful to declare itself. Note this is a *default*, not an inference at use time; §3.2's rule
+against data-dependent behaviour concerns instructions being reinterpreted, and there is no
+instruction here to reinterpret.
+
+### 11.4 `texture_write_to_gpu` cannot honour §3.2, because it cannot see the flag
+
+§3.2 says that when generation is requested the supplied levels above 0 are not uploaded. Nothing
+implements that: the signature is `texture_write_to_gpu(image, texture, queue)`
+([:189](texture_write_to_gpu.js:189)), with two non-spec callers
+([`TextureManager.js:147`](TextureManager.js:147),
+[`GPULightCollection.js:201`](../light/GPULightCollection.js:201)), and `ShadeTextureFlags` lives on
+the `ShadeTexture`, which it never receives.
+
+**Resolution:** the uploader takes an explicit level range — `texture_write_to_gpu(image, texture,
+queue, { levels })` — defaulting to all of them. `TextureManager` passes `[0, 1)` when it is about to
+schedule the generator. This is the same parameter mip streaming needs (§3.4) in order to write one
+arriving level, so it is one addition serving both, not a special case for generation.
+
+### 11.5 Per-format resolution needs a manifest, which §5.1 does not have
+
+§5.1's loop asks `resolve(logical_name, format)` and says a description "may not exist". It does not
+say how the client knows. If existence is discovered by requesting, every texture on a device whose
+preferred format was not built costs a 404 round-trip — possibly several, walking the preference
+list — before the fallback. On a streaming engine that is the worst place to put a stall.
+
+The plan needs a **per-texture set of available formats, known before the first request**: a field in
+whatever index already names the texture, or in the alias list that
+[`loadAssetAliasList`](../../../engine/asset/loadAssetAliasList.js) reads. Cheap, but it is a
+prerequisite of §5.1 rather than a detail of it, and §9 step 7 currently reads as though the
+resolution rule were the whole job.
+
+### 11.6 Corrections of fact
+
+- **BC1 has alpha.** §6.4 lists `bc1` among formats with "no usable alpha". WebGPU exposes it only as
+  `bc1-rgba-unorm`, which decodes 1-bit punch-through alpha. `shade_texture_might_have_alpha` must
+  answer **true** for it. `bc4`, `bc5` and `etc2-rgb8unorm` in that list are correct;
+  `etc2-rgb8a1unorm` would be another true.
+- **The 256-alignment arithmetic in §4.4 is stated too strongly.** `ceil(w/4) × 16 ≡ 0 (mod 256)`
+  requires `ceil(w/4)` to be a multiple of 16, which `w = 61…64` also satisfies — not only multiples
+  of 64. For a mip chain, where widths are powers of two, the practical rule is `w ≥ 64`. The
+  conclusion (pad the rows) is unchanged; the stated condition was wrong.
+- **`gpu_texture_format_info` has three consumers, not two** — `SoftwareGPUDevice`,
+  `SoftwareGPUTexture`, `frame_graph_extract_topology`. Said twice, wrong twice.
+- **The LZ4 reference in §1 is vestigial.** It survives from revision 1's container, which revision 2
+  deleted in favour of per-format resources (§5). Nothing in the plan now wraps block payloads in
+  anything — transport compression is the delivery layer's business, and a BC7 payload compresses
+  ~10–15 % anyway. Drop the bullet rather than leave a dependency the plan does not use.
+
+### 11.7 What survived
+
+The load-bearing claims were checked and hold: `gpu_texture_format_info` is block-correct and is the
+right single table; `VTPhysicalCache` really is per-layer format-parameterised, so §7 stays small;
+`lodMinClamp` exists; `gpu_texture_format_srg_to_linear` and `gpu_texture_format_to_color_space`
+really are already compressed-aware; `@webgpu/types` really is absent (`"webgpu"` in `package.json`
+is a keyword, not a dependency); `GPUTextureFormat` really is never read as a runtime value; and
+`TextureDescriptor.js:61` really does read `GPUTextureUsage` at module load.
+
+§0's central move — format on the image rather than inferred at upload — is untouched by all six
+findings. Three of them (11.2, 11.3, 11.4) are cases where the *transition* was underspecified rather
+than the destination being wrong, which is the failure mode a plan of this shape should expect.