@woosh/meep-engine 2.168.0 → 2.169.0

package/src/REVIEW_2026_08_06/engine-asset.md

@@ -0,0 +1,166 @@
+# Correctness review — `meep/src/engine/asset/`
+
+Scope: 81 non-spec source files under `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/`.
+Existing suite state at review time: 18 suites / 119 tests pass, 1 suite skipped (`NativeImageDecoder.spec.js`).
+
+---
+
+### ASSET-1 Adam7 de-interlacing overflows its scanline buffer on pass 7
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/image/png/PNGReader.js:497` (allocation) and `:523` (offset)
+- **Defect**: `interlaceAdam7` uses a double-buffered scanline (`line_offset = (y % 2) * passLineBytes`) but allocates only **one** line: `new Uint8Array(width * bytes_per_pixel)`. Pass 7 has `pass_width === width`, so `passLineBytes === width * bytes_per_pixel` — the whole buffer. Every odd-`y` scanline of pass 7 is therefore written entirely past the end of the typed array (writes silently dropped) and read back as `undefined` → stored as 0. The same odd-`y` region is also handed to the next line as `output_offset_previous`, so Up/Average/Paeth rows in pass 7 predict from zeros as well.
+- **Failure scenario**: Any Adam7-interlaced PNG at least 4 pixels tall. Verified with a synthetic 2x4 8-bit grayscale interlaced PNG whose pixels are `[10,11, 20,21, 30,31, 40,41]`; `PNGReader.parse()` returns `[10,11, 20,21, 30,31, 0,0]`. Same test in RGB (colorType 2) returns the last row as `0,0,0, 0,0,0`. On a real interlaced PNG this blacks out output rows 3, 7, 11, 15, … (≈25% of the image) and corrupts more when non-`None` filters are used.
+- **Fix**: allocate two lines — `new Uint8Array(2 * width * bytes_per_pixel)` (or `2 * max_pass_line_bytes`). Note pass 5 with an odd width also overruns by `bytes_per_pixel` today, and the same fix covers it.
+- **Confidence**: Confirmed (reproduced by execution)
+
+---
+
+### ASSET-2 Fetch stream error during download hangs the load forever
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/ArrayBufferLoader.js:43-63`
+- **Defect**: `observeResponseProgress`'s `pump()` does `reader.read().then(({done, value}) => {...})` with **no rejection handler**. If the underlying body stream errors mid-download (dropped connection, TLS reset, server abort, `net::ERR_INCOMPLETE_CHUNKED_ENCODING`), the read promise rejects; `controller.close()` / `controller.error()` are never called, so the wrapper `ReadableStream` stays open forever. `await response.arrayBuffer()` on line 154 never settles, so `load()` neither calls `success` nor `failure` and never rejects.
+- **Failure scenario**: `assetManager.promise('data/models/big.glb', 'arraybuffer')`, server drops the connection after 3 MB of a 10 MB body → the `PendingAsset` stays in `request_map` and in `#pending_asset_active_load_set` forever. With a finite `load_concurrency` it also permanently consumes a concurrency slot. `AssetPreloader` never fires `levelFinished` for that level, so the loading screen never advances, and a graceful `AssetManager.shutdown()` never resolves (`#drain` waits on `request_map.size === 0`). Also produces an unhandled promise rejection. All PNG loads go through this loader (`ImageRGBADataLoader.__decode_via_worker`), so this is on the default image path.
+- **Fix**: attach a rejection handler in `pump()` that calls `controller.error(e)` (and stop pumping), e.g. `reader.read().then(onChunk, e => controller.error(e))`. A `cancel(reason)` on the stream prototype that calls `reader.cancel(reason)` is also worth adding so an aborted consumer releases the reader.
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-3 Alpha-tested GLTF meshes never receive their custom depth material
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/GLTFAssetLoader.js:260-272`
+- **Defect**: The comment says a custom depth material is needed whenever `alphaTest !== 0`, and a `MeshDepthMaterial` is constructed unconditionally in that branch — but the assignment to `object.customDepthMaterial` sits inside `if (this.__enable_texture_cache)`. `__enable_texture_cache` is initialised to `false` (line 171) and there is no setter anywhere in the repo, so the branch is never taken. The freshly built `MeshDepthMaterial` is allocated and immediately dropped.
+- **Failure scenario**: Load a GLTF whose foliage/decal material has `alphaTest = 0.5`. `object.customDepthMaterial` stays undefined → three renders the shadow pass with the default depth material, which ignores `alphaTest`+`map`, so a cut-out leaf plane casts a solid rectangular shadow. Every such mesh also allocates a throwaway `MeshDepthMaterial` per load.
+- **Fix**: always assign, and only route through the cache when de-duplication is enabled:
+  `object.customDepthMaterial = this.__enable_texture_cache ? materialCache.acquire(depthMaterial) : depthMaterial;`
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-4 Texture loader rejects `jpeg` — including every `data:image/jpeg` URI
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/texture/TextureAssetLoader.js:33-44`
+- **Defect**: The dispatch switch handles only `'dds'`, `'png'`, `'jpg'`. The data-URI branch above it extracts the extension from the MIME subtype (`match[1]`), and the canonical MIME type for JPEG is `image/jpeg` — never `image/jpg`. So the one input format the data-URI branch exists to support cannot reach a loader. Plain files named `*.jpeg` fail the same way.
+- **Failure scenario**: `assetManager.promise('data:image/jpeg;base64,/9j/4AAQSkZJRg...', 'texture')` → `computeFileExtension` returns `null` (base64 contains no `.`), the regex matches, `fileExtension = 'jpeg'`, the switch falls to `default` and throws `Unsupported texture file format: 'jpeg'`. The manager catches the synchronous throw and fails the request. Same for `assetManager.promise('data/ui/portrait.jpeg', 'texture')`.
+- **Fix**: add `case 'jpeg':` (and `case 'webp':`, which `loadStandardImageTexture` handles fine via three's `TextureLoader`) alongside `case 'jpg':`.
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-5 Texture loaders violate the `progress(current, total)` contract
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/texture/loadStandardImageTexture.js:37` and `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/texture/loadDDSTexture.js:36`
+- **Defect**: Both pass the manager's `progress` callback straight into three.js's `onProgress` slot. three invokes `onProgress(progressEvent)` with a *single* `ProgressEvent` argument, but `AssetLoader.load`'s documented contract (and everything downstream) is `progress(current: number, total: number)`. `GLTFAssetLoader.load:443-445` gets this right (`progress(xhr.loaded, xhr.total)`); the texture loaders do not.
+- **Failure scenario**: `assetManager.promise('data/t/rock.png', 'texture', { progress: (loaded, total) => bar.set(loaded / total) })` → `loaded` is a `ProgressEvent`, `total` is `undefined`, so `bar.set(NaN)`. Independently, `AssetManager.#dispatch_pending_asset`'s `progress` closure does `pendingAsset.progress.setValue(progressEvent)` / `setUpperLimit(undefined)` on a `BoundedValue`, which accepts them without validation (`BoundedValue.setValue` has no numeric guard) — any UI reading `PendingAsset.progress` gets a non-numeric value and a NaN ratio.
+- **Fix**: wrap, as GLTFAssetLoader does: `e => progress(e.loaded, e.total)`.
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-6 `NativeImageDecoder.decodeSync` always throws — it reads the image before it has loaded
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/image/codec/NativeImageDecoder.js:71-85`
+- **Defect**: `decodeSync` sets `image.src = objectURL` and calls `make_decoded_data(image)` on the next line. Loading a blob URL into an `HTMLImageElement` is asynchronous — at that point `image.width`/`image.height` are still `0`. `decode()` sizes the canvas to `0x0` and calls `context.getImageData(0, 0, 0, 0)`, which per the HTML spec throws `IndexSizeError` when `sw` or `sh` is zero. There is no code path in which this method can return a decoded image.
+- **Failure scenario**: `new NativeImageDecoder().decodeSync(pngBytes)` → `IndexSizeError: Failed to execute 'getImageData' on 'CanvasRenderingContext2D': The source width is 0.` The only test for it (`NativeImageDecoder.spec.js:18`) is `test.skip`ped, and its expectation asserts a `channels: 4` field the implementation never produces — the method has never been executed.
+- **Fix**: there is no synchronous path from encoded bytes to pixels in the DOM; either delete `decodeSync` or reimplement it over an already-decoded source (`ImageBitmap`/`ImageData`) rather than raw bytes.
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-7 Palette PNG: indices past the end of `tRNS` become fully transparent instead of opaque
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/image/png/PNG.js:216-230` (specifically `:219-221`)
+- **Defect**: `getPixel`, colour-type 3, does `a = this.transparency_lookup[pixels[i]]` with no bounds check. The PNG spec allows a `tRNS` chunk shorter than the palette; missing entries are fully opaque (255). Reading past the `Uint8Array` yields `undefined`, which a `Uint8Array` destination stores as **0** — fully transparent. `getUint8Data_case3` (`PNG.js:369-377`) implements the spec rule correctly, so the two readers of the same PNG disagree.
+- **Failure scenario**: An indexed PNG with a 256-entry PLTE and a 2-entry tRNS (the common "index 0 and 1 are the transparent ones" encoding produced by pngquant/optipng). `png.getRGBA8Array()` → `getRGBA8Array_generic` → `getPixel`: every pixel using palette index ≥ 2 gets alpha 0, i.e. the whole opaque body of the image is returned invisible.
+- **Fix**: mirror `getUint8Data_case3`: `const idx = pixels[i]; a = idx < this.transparency_lookup.length ? this.transparency_lookup[idx] : 255;`
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-8 `decodetEXt` / `decodeiEXt` parse the whole PNG file instead of the chunk
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/image/png/PNGReader.js:260-267` and `:273-295`
+- **Defect**: `PNGReader.readBytes` returns `new Uint8Array(buffer.data, buffer.position, length)` — a *view* into the whole-file `ArrayBuffer` with a non-zero `byteOffset`. Both text decoders then do `BinaryBuffer.fromArrayBuffer(chunk.buffer)`, which binds the **entire PNG file** and resets `position` to 0, discarding `chunk.byteOffset` entirely. `png_chunk_decode_zTXt`/`png_chunk_decode_iTXt` handle this correctly (they explicitly set `buffer.position = chunk.byteOffset`); these two do not. `decodetEXt` additionally computes the value length as `keyword.length - 1`, which has no relation to the value's actual length (it should be `chunk.length - keyword.length - 1`).
+- **Failure scenario**: `reader.decodetEXt(chunk)` on any PNG → the keyword is read from byte 0 of the file, i.e. the PNG signature `\x89PNG\r\n\x1a\n…`, stopping at the first NUL; `png.text` is keyed by that garbage and holds a value sliced at an arbitrary length. Never the chunk's real keyword/value.
+- **Fix**: bind the chunk's own range in both methods, as the `png_chunk_decode_*` helpers do (`fromArrayBuffer(chunk.buffer)` + `position = chunk.byteOffset`, bounded by `chunk.byteLength`), and compute the tEXt value length as `chunk.byteLength - (position - chunk.byteOffset)`.
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-9 Stale `Asset` value returned from `STATIC_ASSET_CACHE` after an asset is replaced
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/STATIC_ASSET_CACHE.js:9-16` (with `Asset.equals`/`Asset.hash` at `Asset.js:45-63`)
+- **Defect**: The cache is keyed by `Asset` using `invokeObjectEquals`/`invokeObjectHash`, and `Asset.equals` treats two *distinct* `Asset` objects as equal whenever their `description` matches (`AssetManager.#settle` stamps `value.description = assetDescription` on every load). So the cache key identifies the *description*, not the instance, and a replacement `Asset` for the same `(path, type)` collides with the old one's cached materialisation.
+- **Failure scenario**: `assetManager.remove('data/models/hero.glb', 'model/gltf')` (or `insert()` with a rebuilt asset — `AssetManager.insert:664` explicitly supports replacement and only warns) followed by a fresh load produces a new `Asset` B with the same description as the evicted `Asset` A. `SGMeshSystem` (`engine/graphics/ecs/mesh-v2/aggregate/SGMeshSystem.js:144`) calls `STATIC_ASSET_CACHE.get(B)`, hits A's entry, and renders the *old* `Object3D` — the replacement is silently ignored until the cache evicts. Secondarily, every `Asset` whose `description` is still `null` hashes to 0, so all pre-settle assets pile into one bucket.
+- **Fix**: key the cache by identity (a `Map`/`WeakMap` on the `Asset` instance) rather than by description equality, or purge the entry for a description on `AssetManager.remove`/`insert`.
+- **Confidence**: Confirmed (mechanism); trigger requires an asset replacement flow
+
+---
+
+### ASSET-10 `guessAssetType` mis-slices any URL that does not contain `data/`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/guessAssetType.js:12`
+- **Defect**: `url.substring(url.indexOf('data/') + 'data/'.length)` — when `'data/'` is absent, `indexOf` returns `-1` and the expression becomes `substring(4)`, silently chopping the first four characters of the URL and then deriving the "asset directory" from the mangled remainder. There is no `-1` branch.
+- **Failure scenario**: `guessAssetType('assets/models/hero.json')` → `indexOf` is `-1` → `substring(4)` = `'ts/models/hero.json'` → directory `'ts'` → returns `'json'` instead of `'three.js'`. `GameCreationScene.js:153` and `view/renderModel.js:77` feed the result straight into `assetManager.get({ type })`, so the model is handed to `JsonAssetLoader` and the caller receives a raw object where an `Object3D` factory was expected.
+- **Fix**: `const i = url.indexOf(assetRootPath); let assetDirectory = i === -1 ? url : url.substring(i + assetRootPath.length);`
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-11 `textureMipmapEqual` compares height against width
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/material/computeTextureEquality.js:207`
+- **Defect**: `if (a.height !== b.width) { return false; }` — copy-paste; should be `a.height !== b.height`.
+- **Failure scenario**: Two byte-identical 512x256 compressed-texture mip levels: `a.width === b.width` passes, then `a.height (256) !== b.width (512)` returns `false`. `computeTextureEquality` therefore reports identical non-square textures as different, so `GLTFAssetLoader.__texture_cache` and `StaticMaterialCache.textureCache` never de-duplicate non-square DDS/compressed textures — every GLTF instance keeps its own GPU upload.
+- **Fix**: `if (a.height !== b.height) { return false; }`
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-12 `computeImageBitmapHash` hashes the red channel `itemSize` times and ignores G/B/A
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/material/computeImageBitmapHash.js:31-36`
+- **Defect**: The inner loop reads `sampler_data[address]` — `address` is never offset by the loop variable `i`, so channel 0 is folded into the hash four times and channels 1..3 are never read.
+- **Failure scenario**: Two 8x8 `ImageBitmap`s that share the red channel but differ entirely in green/blue/alpha (e.g. a red-channel-packed roughness map vs. a metalness map baked from the same source) hash identically. Every such texture lands in the same `HashSet` bucket in `GLTFAssetLoader.__texture_cache` (capacity 2048), degrading the de-dup pass to a linear scan with a full `computeImageBitmapEquality` (GPU readback + array compare) per collision. The result stays correct because equality is exact; the cost is not.
+- **Fix**: `const v = sampler_data[address + i];`
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-13 `NativeImageDecoder.decode` leaks the object URL when decoding fails
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/image/codec/NativeImageDecoder.js:87-104`
+- **Defect**: `URL.revokeObjectURL(url)` runs only after `await image.decode()` resolves. If `decode()` rejects (corrupt/unsupported bytes) the function throws and the blob URL — and the blob it pins — is never released.
+- **Failure scenario**: `CodecWithFallback` routes every non-PNG through `NativeImageDecoder`. A batch of truncated or unsupported image assets (a CDN serving an HTML error page under an image path, so `image.decode()` rejects) leaks one `Blob` per failed asset for the lifetime of the document.
+- **Fix**: wrap in `try { … } finally { URL.revokeObjectURL(url); }`.
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-14 Preloader global progress never reaches 1 once any asset fails
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/preloader/AssetPreloader.js:264-281` and `:291-304`
+- **Defect**: `on.progress` is dispatched only from `assetLoadSuccess`, and the global ratio is `#asset_count_loaded / #asset_count`. Failures increment `#asset_count_failed` (which counts toward `#try_finish`) but are excluded from the progress numerator and emit no progress event at all. The last progress event a listener ever sees is therefore `(total - failures) / total`.
+- **Failure scenario**: 20 queued assets, one 404s. The final `on.progress` reports `0.95`; `on.resolved` then fires with `(19, 1)`. A loading bar driven by `on.progress` freezes at 95% and the scene switches under it. (Note the previously-suspected missing level-completion check in `assetLoadFailed` is present and correct at lines 299-301 — a failure does close its level batch.)
+- **Fix**: dispatch progress from `assetLoadFailed` too, and compute the ratio from processed count: `(#asset_count_loaded + #asset_count_failed) / #asset_count`, keeping the loaded count as a separate field on the payload.
+- **Confidence**: Confirmed
+
+---
+
+### ASSET-15 JPEG malformed-APP1 recovery compares a 16-bit marker against 8-bit constants
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/asset/loaders/image/jpeg/JpegImage.js:365`
+- **Defect**: `fileMarker` comes from `readUint16()`, so APP0/APP1 are `0xFFE0`/`0xFFE1`. The recovery branch tests `fileMarker === 0xE0 || fileMarker === 0xE1`, which can never be true. The whole `malformedDataOffset` recovery path (lines 365-377), added per the comment to handle "malformed APP1 markers popular in some phone models", is unreachable.
+- **Failure scenario**: A phone-camera JPEG with a malformed APP1 segment reaches the `default` case; instead of resynchronising it falls through to `throw new Error("unknown JPEG marker " + …)` and `jpeg_decode` fails outright, where the intended behaviour was to skip the bad segment and decode.
+- **Fix**: compare against `0xFFE0`/`0xFFE1`.
+- **Confidence**: Confirmed
+
+---
+
+## Status of the pre-declared "already known" items
+
+| Item | Status |
+| --- | --- |
+| `AssetPreloader.assetLoadFailed` missing the level-completion check | **FIXED** — the `(batchElementLoadedCount + batchElementFailedCount) >= batch_size` guard is present at `AssetPreloader.js:299-301`; a failure closes its level. (Separate, still-live progress accounting issue filed as ASSET-14.) |
+| 1-bit and sub-8-bit palette PNG decoding to garbage | **STILL PRESENT** — `png_filter_unFilterNone` unpacks sub-byte samples one-per-byte while filters 1–4 (`Sub`/`Up`/`Average`/`Paeth`) copy packed bytes, and `interlaceNone` sizes both `pixels` and `length` as *packed* bytes (`ceil(bpp*width)`), so even the None path only emits `ceil(width/2)` of `width` nibbles. `PNG.getUint8Data_case3` compounds it with `d = colors * ceil(bitDepth/8)` → 1, reading two 4-bit indices as one. Interlaced sub-8-bit is worse still: `interlaceAdam7`'s `bytes_per_pixel` is fractional, so `new Uint8Array(fractional)` truncates to a zero/short buffer. |
+| `SVGAssetLoader` hanging on any non-200 response | **STILL PRESENT** — `SVGAssetLoader.js:9-21`: the `load` handler only acts when `status === 200`, and the `error` listener does not fire for HTTP error statuses, so 404/500/3xx neither resolve nor reject. Additionally the 200 path never checks for a `<parsererror>` root, so malformed SVG resolves as a "successful" asset whose `create()` clones an error node. |
+| Worker image decoder detaching a cached `ArrayBuffer` | **STILL PRESENT** — `ThreadedImageDecoder.decode` passes `[data.buffer]` to `OnDemandWorkerManager.request`, transferring/neutering the buffer that `ImageRGBADataLoader.__decode_via_worker` obtained from the cached `arraybuffer` `Asset`. Second request for the same path re-uses the cached (now detached) asset → zero-length image. It also kills the `CodecWithFallback` chain: after the threaded codec fails, `NativeImageDecoder` receives a detached `data` and can only produce an empty blob. |