@woosh/meep-engine 3.14.1 → 3.14.3

package/README.md

@@ -64,8 +64,9 @@ type names come from.
   extend the frame by declaring where your work goes, not by patching the renderer.
 
 If you want the mechanisms behind these - visibility buffer, meshlet clustering, clustered lighting,
-occlusion culling, the frame graph - they are in **[the renderer contract](src/shade/RENDERER_CONTRACT.md)**,
-which also covers how to put a model on the screen and how to add your own work to the frame.
+occlusion culling, the frame graph - they are in **the renderer contract**, which ships in the
+package at `src/shade/RENDERER_CONTRACT.md`. It also covers how to put a model on the screen and
+how to add your own work to the frame.
 
 ## How the features interact
 
@@ -127,8 +128,8 @@ Two things to know. Anti-aliasing is the only thing that upscales, so switching
 resolution scale is below full leaves the frame un-upscaled. And if you drive the `Renderer`
 directly rather than through `Engine`, none of this is wired for you.
 
-A neural upscaler ships alongside the default one - a port of ARM's Neural Super Sampling, weights
-included, no setup needed - one assignment away at `renderer.upscale_type = ShadeUpscalerType.NSS`.
+A neural network-based upscaler ships alongside the default one, weights included and no setup
+needed - one assignment away at `renderer.upscale_type = ShadeUpscalerType.NSS`.
 
 ## Correct by default
 
@@ -169,7 +170,11 @@ targets WebGPU, and everything above follows from that.
 The floor is fixed and checked before anything is created: WebGPU plus a small set of capabilities
 that mainstream desktop GPUs have had for years. Hardware that does not clear it gets a clear
 failure message written to be shown to a person, rather than a degraded picture. The exact features
-and limits are in [§2 of the contract](src/shade/RENDERER_CONTRACT.md).
+and limits are in §2 of `src/shade/RENDERER_CONTRACT.md`.
+
+To see what a given browser and GPU actually report, open
+**[webgpu.report](https://webgpu.report/)** on the machine in question - it lists the adapter's
+features and limits, which is what the floor is checked against.
 
 ## Numbers
 
@@ -182,7 +187,7 @@ The renderer records `.sgpt` GPU profile captures - per-pass timings, and at hig
 the frame-graph structure, dispatch and draw counts. Assign a
 `GPUProfileSession({ level: GPUProfileLevel.WORKLOAD })` to `renderer.profile_session`, call
 `start()`, run frames, and `stop()` returns an `ArrayBuffer` to write out. The recorder and the
-[format specification](src/shade/device/timing/profile/SGPT_FORMAT.md) both ship in this package.
+format specification (`src/shade/device/timing/profile/SGPT_FORMAT.md`) both ship in this package.
 
 ---
 
@@ -197,32 +202,34 @@ The rest of what a game needs, in the same package. Each links out to its own do
   with the determinism covered by replay tests - which is what lets it sit under rollback netcode.
   Convex and mesh collision, continuous collision detection for fast movers, and bodies that stop
   costing anything once they settle. A raycast vehicle, a character controller that handles stairs
-  and slopes, and inverse kinematics. [Fluid simulation](src/engine/physics/mls-mpm/README.md) is
+  and slopes, and inverse kinematics. [Fluid simulation](https://meep.company-named.com/docs/physics/fluid/) is
   separate and can run off the main thread.
 * **Audio.** The Wwise/FMOD feature set without the middleware: events, a mixer bus tree, real-time
   parameters, voice stealing, snapshots and ducking, all authored as engine data you can serialize.
-  Opt-in [acoustic simulation](src/engine/sound/simulation/README.md) adds occlusion, transmission
+  Opt-in [acoustic simulation](https://meep.company-named.com/docs/audio/overview/) adds occlusion, transmission
   and reverb driven by the scene's own geometry.
-* **[Networking](src/engine/network/README.md).** Server-authoritative rollback: client-side
-  prediction, reconciliation, and binary snapshots. Transports for WebRTC, WebTransport, WebSocket
-  and Node UDP, plus loopback and deliberately lossy ones for tests. Bandwidth metering, packet
-  record and replay, and cross-peer desync detection.
-* **Navigation & AI.** Grid A\*, and a [navigation mesh](src/engine/navigation/mesh/README.md) with
-  any-angle paths and obstacle carving at build time. Behaviour trees and blackboards, [Monte-Carlo
-  tree search](src/engine/intelligence/mcts/README.md) for agents that search a game tree rather
-  than follow one, and a planner for spending limited resources. Ray, box, frustum and point queries
-  against the scene.
-* **Procedural generation.** [A rule-driven grid generator](src/generation): cellular automata,
-  layered grids, rule sets that place markers and spawn entities, theme-driven selection. Generation
+* **[Networking](https://meep.company-named.com/docs/platform/networking/).** Server-authoritative
+  rollback: client-side prediction, reconciliation, and binary snapshots. Transports for WebRTC,
+  WebTransport, WebSocket and Node UDP, plus loopback and deliberately lossy ones for tests.
+  Bandwidth metering, packet record and replay, and cross-peer desync detection.
+* **Navigation & AI.** Grid A\*, and a [navigation
+  mesh](https://meep.company-named.com/docs/physics/navigation-meshes/) with any-angle paths and
+  obstacle carving at build time. Behaviour trees and blackboards, [Monte-Carlo tree
+  search](https://meep.company-named.com/docs/ai-and-simulation/) for agents that search a game tree
+  rather than follow one, and a planner for spending limited resources. Ray, box, frustum and point
+  queries against the scene.
+* **Procedural generation.** [A rule-driven grid
+  generator](https://meep.company-named.com/docs/generation/overview/): cellular automata, layered
+  grids, rule sets that place markers and spawn entities, theme-driven selection. Generation
   composes as tasks over shared state, so building a world is a graph of steps rather than a script.
 * **Assets & codecs.** glTF, including meshopt compression, loading into **entities** rather than
   one opaque tree. PNG, JPEG and AVIF decoded in-engine - the AV1 codec is a from-scratch encoder
   *and* decoder in pure JavaScript, no WebAssembly. Web-first asset streaming, and binary
   serialization that upgrades across versions.
-* **Tooling.** An in-app editor that attaches to and detaches from a running engine. [GPU profile
-  capture](src/shade/device/timing/profile/SGPT_FORMAT.md) that records per-pass timings and leaves
-  the build entirely when you don't import it. A software WebGPU implementation and a WGSL
-  interpreter, so shaders and pipelines are testable on machines with no GPU.
+* **Tooling.** An in-app editor that attaches to and detaches from a running engine. GPU profile
+  capture that records per-pass timings and leaves the build entirely when you don't import it. A
+  software WebGPU implementation and a WGSL interpreter, so shaders and pipelines are testable on
+  machines with no GPU.
 * **Everything smaller.** Input across touch, mouse, keyboard and gamepad behind one abstraction ·
   an optional DOM UI layer, replaceable with React or Vue · colour management with perceptual
   spaces, HDR transfer functions, tone mapping and gamut clipping · node graphs · achievements ·
@@ -260,5 +267,5 @@ raise that ceiling for a one-time fee per project, and add 24 months of major-ve
 Short version: ship anything you like, just don't redistribute the source and don't build a
 competing engine.
 
-See [LICENSE](LICENSE) for the terms covering this package, and the
+See the `LICENSE` file in the package for the terms covering this package, and the
 [pricing page](https://meep.company-named.com/pricing/) for the tier ladder.

package/editor/prototypeEditorShell.js

@@ -6,6 +6,9 @@ import { ArrayBufferLoader } from "../src/engine/asset/loaders/ArrayBufferLoader
 import {
     GLTFSceneBundleAssetLoader
 } from "../src/engine/asset/loaders/GLTFSceneBundleAssetLoader.js";
+import {
+    USDSceneBundleAssetLoader
+} from "../src/engine/asset/loaders/USDSceneBundleAssetLoader.js";
 import { ImageBitmapAssetLoader } from "../src/engine/asset/loaders/image/ImageBitmapAssetLoader.js";
 import { ImageRGBADataLoader } from "../src/engine/asset/loaders/image/ImageRGBADataLoader.js";
 import { load_model_scene_bundle } from "../src/engine/asset/load_model_scene_bundle.js";
@@ -68,6 +71,9 @@ function addModelLoaders(config) {
     config.addLoader(GameAssetType.ModelGLTF, loader);
     config.addLoader(GameAssetType.ModelGLTF_JSON, loader);
 
+    // `.usd`, `.usda` and `.usdz` all arrive under the one type — see `GameAssetType.ModelUSD`
+    config.addLoader(GameAssetType.ModelUSD, new USDSceneBundleAssetLoader());
+
     // `load_gltf` asks the asset manager for each of a model's images rather than fetching them
     // itself (D34), so a shell without this loader loads geometry and no textures
     config.addLoader(GameAssetType.ImageBitmap, new ImageBitmapAssetLoader());

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.14.1",
+  "version": "3.14.3",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/CODEC_LAYOUT_VERIFICATION.md

@@ -0,0 +1,420 @@
+# Codec layout — verification before the move
+
+2026-09-02. Re-derivation of the earlier session's claims about where the file-format codecs sit and
+what they depend on, done by resolving imports rather than by reading directory listings. Every
+claim is marked **confirmed**, **corrected** or **refuted**, with the command that decided it.
+
+All commands run from `packages/meep-engine/src`. The suite was green before anything moved:
+`npx vitest run` — 2227 files, 15393 tests, 69 s.
+
+The one tool this used that the earlier session did not is an import resolver: the task's grep
+(`from ['"].*(engine|shade|view)/`) only matches specifiers that *spell* one of those directory
+names, so a file inside `shade/renderer/loader/gltf/` importing `../../texture/TextureRole.js` is
+invisible to it. Resolving each relative specifier against the importing file and classifying the
+result by its top-level directory catches those. The script is a few lines of node; the resolved
+tables below come from it.
+
+```bash
+# resolve every relative import under DIR and print those landing in engine/, shade/ or view/
+node resolve_imports.mjs avif basis ktx2 shade/renderer/loader/gltf shade/renderer/loader/usd \
+     engine/asset/loaders/image/png engine/asset/loaders/image/jpeg
+```
+
+---
+
+## Claim A — pure core plus thin skin: **confirmed, with three corrections and one finding that changes the rule**
+
+Resolved imports into `engine/`, `shade/` or `view/`, production files only:
+
+| Tree | Files importing engine/shade/view | What they import |
+|---|---|---|
+| `avif/native/` (110 files) | **1** — `api/avif_to_sampler2d.js` | `engine/graphics/texture/sampler/Sampler2D.js` |
+| `avif/` top level (3 files) | 0 | the encoder pool depends on `native/` and on `OffscreenCanvas` |
+| `basis/` (26 files) | **2** — `transcode_basis.js`, `transcode_uastc.js` | `TextureFormat`, `ShadeTexelData`, `texture_mip_size` |
+| `ktx2/` (7 files) | **2** — `ktx2_read.js`, `vk_format_to_texture_format.js` | `ShadeTexelData`, `gpu_texture_format_is_block_compressed`, `TextureFormat` |
+| `loaders/image/png/` | **1** — `prototypePNG.js` | `Sampler2D`, `sampler2d_to_html_canvas`, `AssetRequestScope`, `ArrayBufferLoader` |
+| `loaders/image/jpeg/` | 0 | — |
+| `loader/gltf/` | see below | — |
+| `loader/usd/` | see below | — |
+
+**Correction A1 — the AVIF skin is one file, not two.** `sampler2d_to_avif.js` imports nothing from
+`engine/`; it takes a duck-typed `{data, width, height, itemSize}` and reaches only `core/`. It is an
+adapter by *intent* (it is named after, and is the inverse of, the `Sampler2D` reader) but not by
+dependency. It still moves with its inverse, because the two are documented as a pair (AVIF decision
+D32) and their round-trip spec tests them together — but the reason is cohesion, not the rule.
+
+**Correction A2 — PNG has two doors, not one.** `ImageDecoderWorker.js` imports `png/PNGReader.js`
+and `codec/ThreadedImageDecoder.js` imports `png/PNG_HEADER_BYTES.js`. Both sit in
+`engine/asset/loaders/image/`, so the earlier "the worker is the only door" undercounted by one; the
+practical consequence is the same — two import lines to update. `prototypePNG.js` is a browser dev
+harness (hard-coded asset path, appends a canvas to `document.body`) and imports the engine; it is
+not format code and cannot move into `format/`. It moves up one level to `loaders/image/`.
+
+**Correction A3 — the glTF/USD seam is not where the earlier table drew it.** The resolver, not the
+grep, decides:
+
+```
+glTF, engine-free (imports core/ only, or nothing):
+  gltf_parse_container.js  gltf_read_accessor.js  gltf_component_type.js  GLTF_PRIMITIVE_MODE.js
+  gltf_used_image_indices.js  coalesce_array_duplicates.js  gltf_node_world_matrices.js  ext/**
+glTF, engine-facing:
+  load_gltf.js  tiny-gltf.js  gltf_create_material.js  gltf_create_texture.js
+  fix_up_material_sides.js  gltf_parse_alpha_mode.js (TransparencyMode)  gltf_image_roles.js (TextureRole)
+
+USD, engine-free:
+  parse_usda.js  usd_triangulate.js  usd_lz4.js  unpack_usdz.js  UsdError.js  usd_compose_transform.js
+USD, engine-facing:
+  load_usd.js  usd_build_scene.js  usd_decode_image.js (ShadeTexture, ShadeImage)
+USD, import-free but renderer-facing by contract:
+  UsdExtensionRegistry.js — its hooks return Node3D; it exists to plug into usd_build_scene
+```
+
+Against the earlier table: `gltf_node_world_matrices` (pure, and already consumed by the node-side
+virtual-geometry builder) was missing from the core list; `usd_compose_transform` was listed as skin
+and is pure; `UsdExtensionRegistry` was listed as core and is the scene builder's plugin registry.
+`gltf_image_roles` and `gltf_parse_alpha_mode` are skin, which the task's grep could not see.
+
+**Is `ktx2_read.js` a clean extraction or a rewrite? Extraction.** The engine coupling is in exactly
+three places, all at the boundary:
+
+1. The three `return` sites construct `ShadeTexelData` (two of them via the transcoders).
+2. Level byte-length validation is *delegated* to that constructor — the reader deliberately does
+   not check that a level's byte count matches its format and extent ("one authority on what a level
+   should weigh"). Two spec tests depend on this delegation.
+3. Its refusals are phrased in terms of what `ShadeTexelData` can model (no arrays, no cubes, no 1D).
+
+The decode path itself — header, DFD, key/values, level index, supercompression, Basis dispatch —
+touches nothing of the engine. The cut is: return a plain `{format, width, height, depth, levels}`
+record; have the reader check each level's byte length against the format table itself (it is a
+container reader, and a mislabelled payload is a malformed file); and move the *engine's*
+constraint — "one level or the whole chain" — into the adapter that builds `ShadeTexelData`, where
+the two spec tests that exercise it go too. The refusal messages that name `ShadeTexelData` are
+reworded to name the constraint. That is a dozen lines and two relocated tests, not a redesign.
+
+**Finding A4 — the texture tier speaks WebGPU format strings, and rule 1 as written cannot be met
+literally without duplication.** Every file on the texture side — the transcoders' target tables,
+`vk_format_to_texture_format`, the reader's block-compressed refusals — is written in terms of
+`TextureFormat` (the `GPUTextureFormat` enum as named constants) and `gpu_texture_format_info` (the
+block-size table), both under `shade/descriptor/texture/format/`, plus `texture_mip_size` from
+`shade/util/`. These are not engine code: they are a web standard's vocabulary as data, with no
+device, no renderer and no DOM behind them, and `shade/descriptor/` as a whole imports nothing but
+`core/` and its own `util/`. A transcoder that writes BC7 blocks has to be able to say "BC7", and the
+alternatives — a parallel enum inside `format/` translated at the adapter, or moving three vendored
+Shade files into `core/` — are either duplication or a change to Shade's layout that this refactor has
+no business making. Importer counts (5, 12 and 11 respectively) are small enough that moving them
+would be *possible*; it would just be the wrong reason to do it.
+
+So rule 1 is refined: **a format package may import `core/`, npm packages, and an explicit allowlist
+of three vocabulary modules — and nothing else under `shade/`, `engine/` or `view/`.** The allowlist
+is enumerated in the structural spec so it is a finite, visible list rather than a directory
+exception, and any fourth entry has to be argued for in a diff. This is the same shape as
+`STILL_COUPLED` in `meep_three_free.spec.js`, and it stays greppable.
+
+**Revised 2026-09-02.** The allowlist is a statement about depth, not about directories. A format
+module may import anything that is itself as low-level as `core/` — the structural spec's second test
+holds every entry to importing nothing but `core/` and other entries — and `Sampler2D` qualifies, a
+typed array with a width and a height. It joined the list together with the two error measures under
+`engine/graphics/texture/sampler/compare/` when the transcode and AVIF specs' five private PSNR copies
+were consolidated there. The rule's job is unchanged: no device, renderer or DOM behind a codec.
+
+---
+
+## Claim B — JPEG is dead: **confirmed**
+
+```bash
+grep -rn "jpeg_decode\|JpegImage\|buildHuffmanTable\|idct8x8\|JpegFrame\|decodeScan\|buildComponentData\|jpeg_component_row" \
+  --include=*.js . | grep -v "^./engine/asset/loaders/image/jpeg/"
+# → empty
+grep -rn "loaders/image/jpeg\|/jpeg/" --include=*.js --include=*.json . \
+  | grep -v "^./engine/asset/loaders/image/jpeg/" | grep -v "avif/native/av1/tables"
+# → empty
+```
+
+`guessAssetType.js` maps `jpg`/`jpeg`/`png` to `"image"`. The `"image"` loader is
+`ImageRGBADataLoader`, whose codec chain is `CodecWithFallback(ThreadedImageDecoder, NativeImageDecoder)`.
+`ThreadedImageDecoder.test` sniffs `PNG_HEADER_BYTES` and returns false for everything else;
+`NativeImageDecoder` inherits `Codec.test`, which returns true unconditionally, and decodes through
+`new Image()` and a canvas. So every JPEG the engine has ever loaded went through the browser's
+decoder. The in-tree decoder is reachable from nothing but its own three spec files, which pass.
+
+---
+
+## Claim C — `engine/asset/loaders/gltf/` is dead: **already resolved — the directory does not exist**
+
+```bash
+ls engine/asset/loaders/gltf          # → No such file or directory
+git log --oneline -3 -- engine/asset/loaders/gltf
+# a10895194 vestigial GLTF code from before Shade
+```
+
+Commit `a10895194` (five commits back) removed it. Migration step 1 is a no-op and is dropped.
+
+---
+
+## Claim D — `core/binary/` is the right home for generic compression: **confirmed; the stated reasoning was wrong**
+
+The claim's justification — "zstd is used by KTX2 and by USD via lz4" — conflates two codecs. The
+actual consumers:
+
+```bash
+grep -rln "binary/lz4\|binary/zstd" --include=*.js . | grep -v "^./core/binary/" | grep -v spec
+# ktx2/ktx2_read.js                                         (zstd)
+# shade/renderer/geometry/virtual/format/frame/vgeo_*.js    (zstd, three files)
+# shade/renderer/loader/usd/usd_lz4.js                      (lz4)
+grep -rn "binary/meshopt" --include=*.js . | grep -v "^./core/binary/meshopt/" | grep -v spec
+# shade/renderer/loader/gltf/ext/meshopt/MeshoptBufferViewExtension.js   (three imports)
+# engine/asset/loaders/gltf_test_fixtures.js                             (test-only encoder)
+```
+
+zstd is shared between KTX2 and the virtual-geometry frame format; lz4 is USD-only today; meshopt is
+glTF-only today. So "shared between formats" holds for zstd alone. What actually justifies the tier
+is not the consumer count but the *dependency*: `core/binary/meshopt/` imports `core/assert`,
+`core/math` and `core/geom` and nothing else — it is a byte-array-in, byte-array-out codec with no
+notion of a bufferView, an accessor or a `KHR_` prefix. Everything glTF-specific about meshopt
+(reading the extension object, validating stride and count rules per mode, the two extension names'
+filter sets and version ceilings) already lives in `gltf/ext/meshopt/MeshoptBufferViewExtension.js`,
+exactly where the plan document that introduced it (`MESHOPT_COMPRESSION_PLAN.md` §1) drew the
+seam. `MeshoptCompressionFilter`/`Mode` cite the glTF spec in their doc comments because that is where
+the numbering is defined, not because they depend on it.
+
+**Held: the tier boundary is dependency direction, and meshopt is below formats by that test.**
+That it happens to have one consumer is a fact about today's format list, not about the codec.
+
+---
+
+## Claim E — consumer counts are small: **confirmed for five of seven; glTF is larger and USD is zero**
+
+Production importers from outside each tree (specs listed separately):
+
+| Tree | Outside importers (prod) | Files | Outside spec importers |
+|---|---|---|---|
+| `avif/` | 3 lines | `shade/renderer/scene/serialization/{decode_image_source_hdr,deserialize_scene,write_image_source}.js` | 0 |
+| `basis/` | 2 files | `ktx2/ktx2_read.js`, `shade/renderer/loader/gltf/tiny-gltf.js` | 0 imports; **1 spec reading `basis/__fixtures__` by filesystem path** (`gltf_texture_basisu.spec.js`) |
+| `ktx2/` | 1 file | `shade/renderer/loader/gltf/tiny-gltf.js` | 2 (`basis/transcode_*.spec.js` read their fixtures through `ktx2_read`) |
+| `png/` | 2 files, both inside `loaders/image/` | `ImageDecoderWorker.js`, `codec/ThreadedImageDecoder.js` | 0 |
+| `jpeg/` | 0 | — | 0 |
+| `loader/gltf/` engine-free files | **5 files** | `shade/renderer/geometry/virtual/build/gltf/{gltf_open_document,gltf_collect_geometries,gltf_read_geometry}.js` + `GltfDocument.spec.js` + `engine/asset/loaders/gltf_meshopt_compression_loading.spec.js` | — |
+| `loader/gltf/` engine-facing (`load_gltf`) | 5 files | `engine/asset/loaders/GLTFSceneBundleAssetLoader.js`, four `shade/playground/*/main.js` | 1 |
+| `loader/usd/` | **0** | nothing imports `load_usd` anywhere in the repository | 0 |
+
+Outside this package: the game repository at `H:/git/moh` vendors a frozen *copy* of meep
+(`app/src/mir-engine/meep`, version 3.1.0) and its own code imports no codec path
+(`grep -rn "src/(avif|basis|ktx2)/|loaders/image/(png|jpeg)/|renderer/loader/(gltf|usd)/"` over
+`moh` excluding the vendored copy and coverage output → empty). `packages/gpu-inspector-tool` imports
+only `shade/device/timing/profile/*`. **No external importer breaks.**
+
+The migration order changes on one count: the glTF split touches the virtual-geometry builder, which
+the earlier plan did not mention, so it stays last — but for blast radius, not for "judgement about
+the seam" (Claim A settled the seam). USD having zero importers means it is a public API with no
+in-tree caller; that is not a reason to delete it (the package exports `./src/*`), but it is worth
+knowing that nothing but its own specs will exercise the move.
+
+---
+
+## Hazards — the earlier list, checked, plus what it missed
+
+| Hazard | Status |
+|---|---|
+| `threaded_image_encoder.js:122` resolves `./encoder_worker.js` via `import.meta.url` | **Real.** The three encoder files move together. It is the only worker `new URL` outside `engine/physics/fluid` (`grep -rn "new URL(" --include=*.js`). |
+| `__fixtures__/` relative paths | Fixture loaders resolve relative to their own spec (`path.resolve(HERE, "__fixtures__")`) and move with them. `basis/__fixtures__/index.json` holds no paths. |
+| `rollup.config.js` | Bundles `engine/asset/loaders/image/ImageDecoderWorker.js`, which stays put; only its import of `PNGReader` changes. `tsconfig.types.json` globs `src/**`. `vitest.config.mjs` globs. `package.json#files` excludes `src/**/__fixtures__/**` by glob. |
+| specs beside sources | Moved with them. |
+| `ktx2` → `basis` edge | Legal within `format/texture/`. |
+| **Missed:** `shade/renderer/loader/gltf/gltf_texture_basisu.spec.js:24,196` reads `../../../../basis/__fixtures__/*.ktx2` by filesystem path | Breaks silently as a missing file, not an import error. Updated in step 2. |
+| **Missed:** `jsdoc_function_type_contract.spec.js` skips top-level `VENDORED = ["shade", "avif"]` | After the move `avif` is no longer top-level; the skip becomes dead. The avif tree contains zero instances of the anti-pattern (`grep` for `function(name:` inside braces → 0), so it can simply be scanned. Entry removed. |
+| **Missed:** `SHADE_ORIGIN.md` records `src/avif` "kept as a sibling so Shade's `../../../../avif/…` imports still resolve" | A note is added under the divergences. |
+| **Missed:** documentation links | `IMAGE_CODEC_REVIEW_2026_08_28.md` (~70 relative links into `avif/native`, `png/`, `jpeg/`), `COMPRESSED_TEXTURE_PLAN_2026_09_01.md` (8), `MESHOPT_COMPRESSION_PLAN.md`, `tools/geometry/virtual/README.md`, `core/color/COLOR_REVIEW_2026_08_28.md`, `avif/native/DECISIONS.md`. Rewritten with `sed` per step. `REVIEW_2026_08_06/*.md` cite absolute paths on another machine and are left as the snapshots they are. |
+| **Missed:** `usd_decode_image.js` carries a *third* PNG decoder (8-bit RGB/RGBA, fixed-Huffman only) | Not a layout matter; recorded as a follow-up below. |
+
+---
+
+## The principle, as verified
+
+Unchanged in substance: sort by dependency direction. `core/binary/` below `format/`, `format/` below
+adapters, adapters beside the engine type they produce, loaders on top. Two rules:
+
+1. **A format package imports `core/`, npm packages, and the vocabulary allowlist —
+   nothing else under `engine/`, `shade/` or `view/`.** Enforced by
+   `src/format_tier_boundary.spec.js`, written in the style of `meep_three_free.spec.js`, added in
+   step 2 so every later step runs under it rather than after it.
+2. **An adapter lives beside the engine type it produces**, not beside the format it reads.
+
+## The tree, as it will be built
+
+The `image/texture/scene` grouping is kept. The task's test for it was whether it predicts the
+adapter, and it does at the level that matters — what kind of thing comes out:
+
+| Group | Decodes to | Adapter target(s) actually found |
+|---|---|---|
+| `image/` | interleaved pixel samples | `Sampler2D` (AVIF, directly; PNG via `ImageRGBADataAsset.create()`, which returns a `Sampler2D`) |
+| `texture/` | GPU-format block payloads | `ShadeTexelData` (KTX2; Basis reaches it only through KTX2) |
+| `scene/` | node graphs | `SceneBundle` (glTF), `Node3D[]` (USD — no bundle; `load_usd` returns roots) |
+
+Two of seven are loose at the *type* level (PNG's asset wrapper, USD's bare array) and none at the
+*kind* level. That is enough to justify one directory level; a flat seven would lose the fact that
+`ktx2 → basis` is a within-kind edge. Recorded so the next person does not re-derive it.
+
+```
+src/format/
+  image/avif/       ← avif/native/**      (api/ loses the two sampler files; index.js loses their exports)
+  image/png/        ← engine/asset/loaders/image/png/**  minus prototypePNG.js
+  image/jpeg/       ← engine/asset/loaders/image/jpeg/**
+  texture/basis/    ← basis/**
+  texture/ktx2/     ← ktx2/**
+  scene/gltf/       ← the engine-free glTF files listed under A3, plus ext/**, plus MESHOPT_COMPRESSION_PLAN.md
+  scene/usd/        ← the engine-free USD files listed under A3
+
+src/shade/renderer/texture/source/texel_data_from_ktx2.js      NEW — the ShadeTexelData half of ktx2_read
+src/engine/graphics/texture/sampler/avif_to_sampler2d.js       ← avif/native/api/  (names kept, see below)
+src/engine/graphics/texture/sampler/sampler2d_to_avif.js       ← avif/native/api/
+src/engine/asset/loaders/image/avif/{threaded_image_encoder,encoder_worker,encode_image_source}.js
+src/engine/asset/loaders/image/prototypePNG.js                 ← png/prototypePNG.js
+src/engine/asset/loaders/image/codec/JpegCodec.js              NEW — decision 1
+```
+
+Deviations from the proposed tree, and why:
+
+- **No `texel_data_from_basis.js`.** Nothing outside `ktx2_read` calls the transcoders with a
+  payload; `tiny-gltf` imports only their `*_formats()` lists. One adapter, one door.
+- **No `vk_format_to_texture_format.js` in `shade/renderer/texture/source/`.** It maps Vulkan format
+  numbers to WebGPU format strings using nothing but the vocabulary allowlist. It is KTX2 knowledge and
+  stays in `format/texture/ktx2/`. Moving it would have been the earlier session's rule 1 forcing a file
+  uphill for want of the refinement in A4.
+- **The AVIF sampler pair keeps its file and function names** (`avif_to_sampler2d`,
+  `sampler2d_to_avif`) rather than becoming `sampler2d_from_avif`. Three consumers, a decision log
+  (D32) and a plan document name them; the destination directory is not uniformly prefixed
+  (`downloadSamplerAsPNG.js`, `HarmonicDiffusionGrid.js`); and a rename is not what this refactor is for.
+- **`avif/index.js` is deleted, `avif/native/index.js` becomes `format/image/avif/index.js`.**
+  Neither has an importer. The outer one re-exported the worker pool alongside the codec, which is
+  the tier mix this refactor exists to undo; its `decode`/`encode` aliases for the old WebAssembly
+  names have no caller.
+- **`UsdExtensionRegistry.js` stays with `usd_build_scene`.** Import-free, but its whole contract is
+  "return a `Node3D`", and it is consulted from the builder. Dependency direction is the rule; where
+  a file has none, the type its contract names decides.
+- **The encoder pool lands in `engine/asset/loaders/image/avif/` with a caveat.** It encodes, and
+  "loaders" is the wrong verb. It goes there anyway because its decode-direction sibling
+  (`codec/ThreadedImageDecoder.js`, also a worker pool) already lives one directory over, and one
+  place for "image codec worker pools" beats a new top-level directory for three files.
+
+## Decision 1 — JPEG: **move it and wire it, as the last fallback**
+
+The 2026-08-28 review (item C1) recommended registering it behind `Codec`, and its item C4 was then
+*done* — `getData` was rewritten around `jpeg_component_row.js` a week ago, with byte-for-byte
+verification against the old output. Deleting a decoder somebody just finished refactoring, with
+three passing spec files, would be the wrong reading of "dead". It is unreachable, not unwanted.
+
+What "wire it" means here is constrained by one fact: in a browser, `NativeImageDecoder` decodes
+JPEG with the platform's own decoder, and a pure-JavaScript decoder on the main thread is slower and
+blocks. So `JpegCodec` goes **after** `NativeImageDecoder` in `ImageRGBADataLoader`'s chain —
+`[ThreadedImageDecoder, NativeImageDecoder, JpegCodec]`. `NativeImageDecoder.test` claims everything
+(it inherits the base class's `return true`), so in a browser nothing changes; where there is no
+`Image` — node, a worker — the native decoder throws, `CodecWithFallback` moves on, and JPEG becomes
+loadable for the first time. Zero behaviour change where it already worked; a working decoder where
+it did not. Teaching `ImageDecoderWorker` to decode JPEG off the main thread is the version with a
+real payoff for the browser, and it is a measured trade (a JS decoder in a worker versus the
+platform's on the main thread), so it is a follow-up rather than a side effect of a layout change.
+
+## Decision 2 — how far the skins are cut
+
+| Skin | Verdict | What is done |
+|---|---|---|
+| `ktx2_read.js` | extraction | plain record out; per-level byte check moves in; "1 or full chain" moves to the adapter with its two tests |
+| `transcode_basis.js`, `transcode_uastc.js` | extraction | plain record out; `TextureFormat` stays via allowlist |
+| `avif_to_sampler2d.js` | already separate | relocated |
+| glTF, USD | file moves only | the seam is a file boundary already |
+| `tiny-gltf.js` | left as is | it *is* the loader; it imports the adapter |
+| `usd_decode_image.js` | left as is, then taken as a follow-up | duplicate PNG decoder, since replaced by `PNGReader` + the adapter |
+| `UsdExtensionRegistry.js` | left with the builder | see above |
+
+## Migration order, resequenced
+
+Each step: `git mv`, fix imports, run the suite, commit with `--only`.
+
+0. This document.
+1. ~~Delete `engine/asset/loaders/gltf/`~~ — already gone (`a10895194`).
+2. `format/texture/` — Basis and KTX2; the `ShadeTexelData` cut; the adapter; the structural spec;
+   `gltf_texture_basisu.spec.js` fixture path; `tiny-gltf` import.
+3. `format/image/avif/` — plus the sampler pair to `engine/graphics/texture/sampler/`, the encoder
+   trio to `engine/asset/loaders/image/avif/`, the jsdoc spec's vendored list, `SHADE_ORIGIN.md`.
+4. `format/image/{png,jpeg}/` — plus `prototypePNG.js` up a level, `JpegCodec`, the two PNG doors.
+5. `format/scene/{gltf,usd}/` — plus the virtual-geometry builder's five imports and the tools README.
+
+Step 6 (the structural spec) is folded into step 2 so it guards steps 3–5 as they land.
+
+## As executed
+
+Six commits on `master`, each green on the full suite (2227 → 2230 spec files; 15393 → 15401 tests —
+the adapter spec, the JPEG codec spec, the loader chain tests and the boundary spec are the additions).
+The plan above held. What execution added:
+
+- **Moves went file by file, not by directory.** A directory rename under `src/` was refused with
+  "Permission denied": two vite dev servers and an IDE hold watcher handles on the tree, and Windows
+  will not rename a directory with an open handle. Moving the files out of it is not blocked, so the
+  move tool does that and removes the emptied directories afterwards. History follows the files
+  either way (`git log --follow`).
+- **Imports and markdown links were rewritten by resolution, not substitution.** Every relative
+  specifier — `import … from`, `export … from`, `import()`, `new URL(…, import.meta.url)`, and
+  `](…)` links with `#L` anchors or `:line` suffixes — was resolved against the file's old location,
+  mapped through the move, and re-expressed from the new one. Only specifiers whose target or whose
+  own file moved were touched. Paths in *prose* (backticked, not linked) were updated by hand where
+  they name a live file; recipes of the form `git checkout <sha> -- src/avif/native/…` were left, since
+  they name a path at that commit.
+- **Some working-copy files are CRLF** (`core.autocrlf=true`; `jsdoc_function_type_contract.spec.js`
+  was one). Edit scripts that match multi-line blocks have to match `\r?\n` and write the file's own
+  ending back.
+- **The rollup worker bundle was built** after step 4 (`npx rollup -c`) to prove
+  `ImageDecoderWorker.js` still resolves `PNGReader` from `format/image/png/`; it does, and the output
+  was removed again (`build/` is gitignored).
+- **`Base64.decode` returns an `ArrayBuffer`**, which the codec `test()` contracts do not accept;
+  the two new JPEG specs wrap it in a `Uint8Array`.
+
+Final shape, as committed:
+
+```
+src/format/
+  image/avif/   api/ av1/ bitstream/ color/ heif/ isobmff/ __fixtures__/ index.js DECISIONS.md NOTICE.md
+  image/png/    PNG.js PNGReader.js PNG_HEADER_BYTES.js chunk/ filter/ crc32.js png_inflate.js png_unpack_samples.js
+  image/jpeg/   JpegImage.js jpeg_decode.js jpeg_component_row.js … NOTES.md
+  texture/      TexelPayload.js
+  texture/basis/  etc1s/ uastc/ transcode/ BasisBitReader.js BasisHuffmanTable.js transcode_basis.js transcode_uastc.js __fixtures__/
+  texture/ktx2/   ktx2_read.js ktx2_read_basis_lz_global_data.js vk_format_to_texture_format.js KhrDfModel.js SupercompressionScheme.js __fixtures__/
+  scene/gltf/   gltf_parse_container.js gltf_read_accessor.js gltf_component_type.js GLTF_PRIMITIVE_MODE.js
+                gltf_used_image_indices.js coalesce_array_duplicates.js gltf_node_world_matrices.js ext/ MESHOPT_COMPRESSION_PLAN.md
+  scene/usd/    parse_usda.js usd_triangulate.js usd_lz4.js unpack_usdz.js UsdError.js usd_compose_transform.js
+
+src/shade/renderer/texture/source/texel_data_from_ktx2.js       KTX2 → ShadeTexelData
+src/engine/graphics/texture/sampler/{avif_to_sampler2d,sampler2d_to_avif}.js   AVIF ↔ Sampler2D
+src/engine/asset/loaders/image/avif/                            encoder worker pool
+src/engine/asset/loaders/image/codec/JpegCodec.js               JPEG behind Codec, last in the chain
+src/engine/asset/loaders/image/prototypePNG.js                  dev harness, up one level
+src/shade/renderer/loader/{gltf,usd}/                           scene builders, unchanged in role
+src/format_tier_boundary.spec.js                                the rule
+```
+
+## Follow-ups this refactor surfaced, and where they stand
+
+- **`ImageDecoderWorker` learning JPEG — measured and declined** (2026-09-02). On 1024×1024 Sponza
+  textures the platform decoder takes 6–11 ms wall with about 1.5 ms of that on the main thread; the
+  in-tree decoder takes 128–178 ms wherever it runs, and a worker saves only the 1.5 ms. Fifteen to
+  twenty times the latency for a read-back's worth of main-thread time is the wrong trade for a
+  loader. The bench and its numbers are `shade/playground/image_decode_bench/`; `ThreadedImageDecoder`
+  says why it sniffs PNG only. JPEG and AVIF reach the in-tree decoders only where no browser decoder
+  exists.
+- **`usd_decode_image.js`'s private PNG decoder — taken, 2026-09-02** (separate session): `decode_png`
+  now calls `PNGReader` and widens whatever it returns to RGBA8; the private inflate and its "Dynamic
+  Huffman blocks not supported" throw are gone. The adapter stays with the loader. Spec beside it.
+- **The rest of review item C1 — done** (2026-09-02): `engine/asset/codec/DecodedImage.js` is the one
+  result shape; `AvifCodec` sits last in the chain beside `JpegCodec`; `guessAssetType` maps `.avif`
+  to `"image"`. The codec wraps `avif_to_sampler2d`, not the reverse — the adapter owns the HDR path
+  and the reusable decoder context, and an 8-bit asset codec wants neither.
+- **KTX2 arrays and cube maps — the reader returns them** (2026-09-02). `TexelPayload` carries
+  `layers` and `faces`, a level holds `layers * faces` images in KTX2's order, and the byte check
+  accounts for them. `texel_data_from_ktx2` refuses layers and faces by name until `ShadeTexelData`
+  grows a layer, and is the only place that changes when it does. The format tier still refuses a 3D
+  array (no GPU API has one) and a Basis payload with layers (the transcoders take one image per
+  level).
+- **A USD asset loader** — `load_usd` had no in-tree caller. A loader beside
+  `GLTFSceneBundleAssetLoader`, with `guessAssetType` entries for the USD extensions, was spun off as
+  its own task.
+- **Open:** `NativeImageDecoder.test` returns true for any bytes. A sniff (`PNG`, `0xFFD8`, `ftyp`)
+  would let the chain be ordered by capability rather than by "the browser will probably manage".