@woosh/meep-engine 3.14.1 → 3.14.2

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

@@ -0,0 +1,1462 @@
+# Block-compressed textures — implementation plan
+
+**Status:** proposal — revision 5
+**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.
+
+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`](../loader/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
+
+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`](../../../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/`](../../../ktx2/ktx2_read.js) — container to `ShadeTexelData`, for files already in a device format; ZLIB supercompression read rather than refused (§9.10) | additive — nothing imports it yet, and nothing existing changed except the cursor it reuses |
+| 9 | CPU Basis transcoder (§4.3), then `KHR_texture_basisu` | the expensive one. Sequenced last deliberately. |
+| 10 | GPU transcoder (§4.4) — the engine's first `copyBufferToTexture` | an optimization of step 9, not a prerequisite |
+
+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.10 What step 8 actually shipped
+
+[`ktx2_read`](../../../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 `avif/native/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](../../../avif/native/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.
+
+**`pako.inflate` directly rather than
+[`png_inflate`](../../../engine/asset/loaders/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.