@woosh/meep-engine 2.168.0 → 2.169.0

package/src/REVIEW_2026_08_06/gfx-render.md

@@ -0,0 +1,740 @@
+# Correctness review — `engine/graphics` (ecs, render, shaders, camera, root)
+
+Scope: every non-spec, non-prototype source file under
+`meep/src/engine/graphics/{ecs,render,shaders,camera}` plus the files directly in
+`meep/src/engine/graphics/`. three.js r136.
+
+---
+
+### GFXR-1 `Camera.projectWorldPointOntoNearPlane` projects onto the RIGHT frustum plane
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/camera/Camera.js:279`
+- **Defect**: The method takes `scratch_frustum.planes[0]` as "the near plane". `frustum_from_camera`
+  fills the frustum via three's `Frustum.setFromProjectionMatrix`, whose plane order is
+  `[0]=right, [1]=left, [2]=bottom, [3]=top, [4]=far, [5]=near`. Index 0 is the RIGHT side plane.
+  The sibling file `ecs/camera/pp/PerfectPanner.js:9-10` states the correct convention
+  (`NEAR_PLANE_INDEX = 5; FAR_PLANE_INDEX = 4;`), so the codebase already knows the ordering.
+- **Failure scenario**: Camera at the origin looking down `-Z`, 45° fov, near 0.1. Call
+  `camera.projectWorldPointOntoNearPlane(0, 0, -10, out)`. Expected `out ≈ (0, 0, -0.1)` — the point
+  pushed onto the near plane in front of the eye. Actual: the point is projected onto the right
+  side plane of the frustum, landing several units off to the camera's right at a depth of 10.
+  Any UI/marker/clamping code built on this public method places its output in the wrong place
+  entirely, and gets *worse* the further off-axis the input point is.
+- **Fix**: `const near = scratch_frustum.planes[5];`
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-2 Orthographic aspect correction uses the wrong delta when the viewport narrows
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/camera/set_camera_aspect_ratio.js:35-40`
+- **Defect**: The widening branch (`aspectDelta > 0`) grows the horizontal extent by `h * aspectDelta`,
+  which is exactly right (`w' = w + h·aspect − w = h·aspect`). The narrowing branch grows the vertical
+  extent by `-h * aspectDelta`, which does **not** solve `w / h' = aspect`. The required delta is
+  `w/aspect − h`, i.e. `-h * aspectDelta / aspect`.
+  ```js
+  } else if (aspectDelta < 0) {
+      const d = -h * aspectDelta;     // <-- missing the /aspect
+      c.top += d / 2;
+      c.bottom -= d / 2;
+  }
+  ```
+- **Failure scenario**: `OrthographicCamera(-10, 10, 10, -10, …)` (square frustum) in a portrait
+  viewport, `set_camera_aspect_ratio(camera, 100, 200)`. Requested aspect 0.5; the code produces
+  `top=15, bottom=-15`, i.e. frustum aspect `20/30 = 0.667`. Everything rendered through that camera
+  is stretched vertically by 33%: circles become ellipses, a square tile is drawn as a rectangle.
+  Verified numerically. The existing spec (`set_camera_aspect_ratio.spec.js`) only exercises the
+  widening case, which is why this survives.
+- **Fix**: `const d = -h * aspectDelta / aspect;` — or, uniformly for both branches, set
+  `h' = w / aspect` when `aspect < existingAspect` and `w' = h * aspect` otherwise.
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-3 `CameraSystem` rebuild leaks a THREE camera into the scene on every fov/projection change
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/camera/CameraSystem.js:146-148`
+- **Defect**: `rebuild()` replaces `camera.object` with a freshly built THREE camera but never removes
+  the previous one from `this.scene`. `link()` is the only place that does `this.scene.add(...)`, and
+  `unlink()` removes only the *current* `camera.object`. The new object gets re-added to the scene by
+  `GraphicsEngine.render` (`if (scene.children.indexOf(camera) < 0) scene.add(camera)`), so every
+  rebuild adds one more permanent child. `rebuild` is wired to `camera.fov.onChanged` and
+  `camera.projectionType.onChanged` (lines 172, 174).
+- **Failure scenario**: A fov-zoom effect animates `Camera.fov` (a `Vector1`, observable precisely so
+  it can be animated) at 60 Hz. Each frame builds a new `THREE.PerspectiveCamera` and appends it to
+  `graphics.scene.children`, which is never pruned. After one minute `scene.children` holds ~3600 dead
+  cameras: unbounded memory growth, an O(n) `scene.children.indexOf(camera)` in `GraphicsEngine.render`
+  every frame, and an O(n) root walk in `NormalFrameBuffer.render`, which traverses `scene.children`
+  each frame. Frame time degrades continuously for as long as the zoom runs.
+- **Fix**: In `rebuild()`, capture the old object, `this.scene.remove(old)` and
+  `this.scene.add(camera.object)` after building. Better still, do not rebuild for a fov change — set
+  `camera.object.fov` and call `updateProjectionMatrix()`; only `projectionType` genuinely needs a new
+  object.
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-4 `Trail2DSystem` seeds the ribbon at a different point from where the head is driven
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/trail2d/Trail2DSystem.js:156-158` vs `:234-235`
+- **Defect**: Build-time seeding adds the offset in world space, ignoring the entity's rotation and
+  scale:
+  ```js
+  const position_x = trail_offset.x + transform_position.x;   // __build_trail
+  ```
+  while the per-frame head update carries the offset through the entity's full transform:
+  ```js
+  newPosition.copy(trail.offset);
+  newPosition.applyMatrix4(transform.matrix);                 // updateTrailEntity
+  ```
+  The sibling `Trail3DSystem` has exactly this invariant written down and enforced via a shared
+  `compute_head_position` helper (`ecs/trail3d/Trail3DSystem.js:34-53`), whose doc comment describes
+  the resulting artifact verbatim. `Trail2DSystem` was not given the same treatment.
+- **Failure scenario**: A projectile entity with `Trail2D.offset = (0, 0, -1)` (trail emitted from the
+  tail) rotated 90° about Y so it flies along `+X`. `__build_trail` seeds every ribbon point at
+  `position + (0, 0, -1)`; the first `updateTrailEntity` puts the head at `position + (-1, 0, 0)`.
+  The first rendered frame contains a ~1.41-unit ribbon streak pointing in a direction that has
+  nothing to do with the projectile's travel — a visible flash at every spawn.
+- **Fix**: Replace lines 156-158 with the same transform-carried computation used in
+  `updateTrailEntity` (ideally extract a shared `compute_head_position(result, trail, transform)` as
+  Trail3D does).
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-5 `loadCubeTexture` calls `ImageUtils.loadTextureCube`, removed from three long before r136
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/loadCubeTexture.js:27`
+- **Defect**: `const textureCube = ImageUtils.loadTextureCube(urls);` — in the vendored
+  `three@0.136.0`, `src/extras/ImageUtils.js` declares exactly one member, `static getDataURL(image)`.
+  There is no `loadTextureCube`.
+- **Failure scenario**: Any caller of this exported (public-surface) helper —
+  `loadCubeTexture('assets/sky', 'png')` — throws `TypeError: ImageUtils.loadTextureCube is not a
+  function` on the first line that matters, so no cubemap is ever produced. The function cannot
+  succeed under any input.
+- **Fix**: Delete the function, or reimplement it on `CubeTextureLoader`:
+  `new CubeTextureLoader().load(urls)` (which already returns a `CubeTexture` with
+  `CubeReflectionMapping`). Note the package already has a working path for this —
+  `texture/cubemap/load_environment_map.js`, used by `load_and_set_cubemap_v0.js`.
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-6 `Lines` writes `drawRange.count` in the wrong units (twice, two different wrong values)
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/render/Lines.js:61` and `:105`
+- **Defect**: `geometry.drawRange.count` is a **vertex** count for a non-indexed geometry. The
+  geometry stores `capacity * 2` vertices (2 per line segment).
+  - `setCount(x)` writes `x * 6` — the *float* count of the position attribute.
+  - `add_line` then overwrites it with `this.count` — the *line* count.
+  Neither is `count * 2`. Separately, `ensure_capacity` → `build()` replaces `this.geometry` without
+  disposing the old `BufferGeometry`, and `dispose()` never disposes `this.mesh.material`.
+- **Failure scenario**: `const l = new Lines(); l.add_line([0,0,0],[1,0,0],[1,1,1,1]);` and add
+  `l.mesh` to a scene. `drawRange.count === 1`; `LineSegments` needs vertex pairs, so zero segments
+  are drawn. Adding 10 lines draws 5. Had `add_line` not overwritten line 61's value, `x*6` would
+  exceed the allocated `x*2` vertices and WebGL would raise
+  `INVALID_OPERATION: attempt to access out of range vertices`.
+- **Fix**: `this.geometry.drawRange.count = x * 2;` in `setCount`, and delete the redundant
+  assignment at line 105. Dispose the replaced geometry in `build()`.
+- **Confidence**: Confirmed (the class also logs `'feature not fully implemented'`, so this is
+  acknowledged WIP — listed for completeness)
+
+---
+
+### GFXR-7 `OutlineRenderer` caches the ID-pass mesh with a frozen geometry reference
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/highlight/renderer/OutlineRenderer.js:96-117`
+- **Defect**: `obtain_id_mesh` builds the silhouette proxy once per source `Object3D` and caches it in
+  a module-level `WeakMap`. On a cache hit it refreshes the skinning state (`bindMatrix`,
+  `bindMatrixInverse`, `skeleton`) but never re-reads `object.geometry`. The equivalent proxy builder
+  in the same package, `render/utils/ThreeBypassRenderer.js:101`, *does* re-assign
+  `mesh.geometry = geometry` on every rebuild — the divergence is the tell.
+- **Failure scenario**: A highlighted `SGMesh` entity crosses an LOD threshold and
+  `SGMeshSystem`/`ShadedGeometrySystem` swaps the `Object3D`'s `geometry` for the next LOD. The
+  visible mesh changes silhouette; the outline keeps tracing the previous LOD's geometry, so the
+  highlight no longer hugs the object — offset/oversized outline until the object is unhighlighted.
+- **Fix**: In `obtain_id_mesh`, after the cache lookup, add `mesh.geometry = object.geometry;`
+  unconditionally.
+- **Confidence**: Likely
+
+---
+
+### GFXR-8 `Water.updateShaderForTerrain` leaks a full terrain heightmap texture per call
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/water/Water.js:138-152`
+- **Defect**: A new `DataTexture` wrapping the whole terrain height sampler is allocated and assigned
+  to `shader.uniforms.tHeightTexture.value`; the texture previously held by that uniform is never
+  `.dispose()`d. `WaterSystem.link` pushes the component onto `updateQueue`, so this runs once per
+  link — and `link` reuses the existing `component.__shader` when the component is re-linked
+  (`WaterSystem.js:164-175`), so each re-link allocates another one.
+- **Failure scenario**: Level reload cycles unlink and re-link the Water component. Each cycle uploads
+  a fresh `R32F` heightmap — for a 1024×1024 terrain that is 4 MB of GPU memory — and orphans the
+  previous one. Twenty reloads leak ~80 MB of VRAM that three.js will never reclaim, because nothing
+  holds a reference to call `dispose()` on.
+- **Fix**: Capture `const previous = shader.uniforms.tHeightTexture.value;` before the assignment and
+  `previous?.dispose()` after — the same replace-then-release shape `GraphicsEngine#bake_environment`
+  already uses for the PMREM target.
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-9 `FrameGraph.exportToJson` conflates resource-node ids with resource-registry ids
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/render/frame_graph/FrameGraph.js:479-508`
+- **Defect**: The two id spaces are independent — `_createResourceEntry` numbers entries by
+  `__resource_registry.length`, `_createResourceNode` numbers nodes by `__resource_nodes.length` —
+  and `clone_resource` adds nodes without adding entries, so they diverge. The export passes a
+  registry id where a node id is required:
+  ```js
+  const node = this.getResourceNode(entry.resource_id);   // registry id -> node lookup
+  ...
+  if (pass.reads(entry.resource_id))                      // registry id vs node ids in resource_reads
+  ```
+  `getResourceNode`'s only protection is an `assert.equal`, which is compiled out in production.
+- **Failure scenario**: `FramePassBuilder.write()` calls `graph.clone_resource()` for any write to a
+  resource the pass did not create — the normal case as soon as two passes touch one resource. In a
+  three-pass graph where pass B writes pass A's target, node ids run ahead of registry ids and
+  `exportToJson()` labels resources with another resource's name and emits reader/writer lists that
+  point at the wrong passes. The rendered GraphViz/JSON diagram misrepresents the pipeline it exists
+  to debug.
+- **Fix**: Track the owning node per entry (or resolve registry id → node by scanning
+  `__resource_nodes` for `resource_id === entry.resource_id`), and compare `pass.reads/writes` against
+  node ids, not registry ids.
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-10 `PathDisplayContext.__build` aborts the whole build on one unknown spec type
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/path/PathDisplaySystem.js:135-139`
+- **Defect**: Inside the loop over `display.specs`, an unrecognised `spec.type` logs a warning and
+  `return`s out of the entire method — skipping the remaining specs, the `ParentEntity` attachment
+  loop, `__build_existing_entities()`, and the `PathDisplayEvents.BuildComplete` dispatch. The
+  neighbouring failure path in the same loop (a builder that throws, lines 141-146) correctly
+  `catch`es and continues.
+- **Failure scenario**: A `PathDisplay` with two specs, `[Ribbon, <stale type from an old save>]`. The
+  Ribbon builder runs and pushes its entities into `__owned_entities`, then the second spec hits the
+  `return`. Those entities are never `build(ecd)`-ed into the dataset, so the path renders nothing at
+  all — and `BuildComplete` never fires, so anything awaiting that event waits forever.
+- **Fix**: `continue;` instead of `return;`.
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-11 `ShadedGeometrySystem.shutdown` never removes its render layer
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/mesh-v2/ShadedGeometrySystem.js:254` (create) vs `:280-294` (shutdown)
+- **Defect**: `startup` does `this.__render_layer = graphics.layers.create('shaded-geometry')` and installs a
+  `buildVisibleSet` closure that resolves a per-view context from `this.__view_contexts`. `shutdown`
+  tears down every view context but never calls `graphics.layers.remove(this.__render_layer)`.
+  `graphics.layers` lives on the `GraphicsEngine`, which outlives the `EntityManager`. Every peer
+  system does remove its layer — `MeshSystem.js:247`, `WaterSystem.js:73`, `Trail2DSystem.js:117`,
+  `Trail3DSystem.js:134`, `GizmoRenderingPlugin.js:18`.
+- **Failure scenario**: Level teardown/reload. `EntityManager.shutdown()` runs
+  `ShadedGeometrySystem.shutdown`, emptying `__view_contexts`; the layer stays registered and visible.
+  (a) If any frame renders before the new dataset is up, `VisibilityComputer.__processLayer` calls the
+  stale `buildVisibleSet`, `this.__view_contexts.get(view)` is `undefined`, and
+  `ctx.collect(...)` throws `TypeError: Cannot read properties of undefined (reading 'collect')` —
+  which aborts the whole visibility build, so *every* layer stops rendering.
+  (b) Adding a fresh `ShadedGeometrySystem` for the next level makes
+  `graphics.layers.create('shaded-geometry')` throw
+  `RenderLayer named 'shaded-geometry' already exists` (`RenderLayerManager.js:117`) — a hard crash on
+  level reload. The stale `compute_depth_range` closure also pins the dead BVH.
+- **Fix**: In `shutdown`, `graphics.layers.remove(this.__render_layer); this.__render_layer = null;`
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-12 `SGMesh.materialOverride` is applied after `link`, bypassing the Forward+ material transform
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshSystem.js:205-207`, and the same defect at `aggregate/SGMesh.js:120-131`
+- **Defect**: `ShadedGeometrySystem.link` exists precisely to close this hole; its own comment says the
+  material is forced "through the manager's transform chain, so that shader injection performed by the
+  lighting engine (Forward+ clustered lights, decals) cannot be skipped by callers that assign
+  `sg.material` directly" (`ShadedGeometrySystem.js:305-311`). In `SGMeshSystem`,
+  `entity_node.build(ecd)` (line 179) synchronously drives `ShadedGeometrySystem.link` for every child
+  `ShadedGeometry`, installing the transformed material — and *then* the traverse at 190-207 overwrites
+  it with the raw override:
+  ```js
+  if (material_override !== null) {
+      sg.material = material_override;
+  }
+  ```
+  `SGMesh.applyMaterialOverride()`, reached from the `set materialOverride` setter, does the same on an
+  already-linked hierarchy.
+- **Failure scenario**: A unit is spawned with `SGMesh.fromURL('unit.gltf')` and a `materialOverride`
+  (team tint / ghost preview / damage flash) using a lit `MeshStandardMaterial`. Every part receives
+  the raw material, which never went through `MaterialManager.obtain`, so the Forward+
+  `onBeforeCompile` clustered-light injection is absent. The overridden unit renders with *no*
+  clustered point lights and no decals while every neighbouring unit in the same scene is lit
+  correctly — it looks flat/black at night. The `assert.ok(!isForwardPlusLightingSkipped(...))` guard
+  in `link` cannot catch it: it runs before the override, and asserts are stripped in production.
+  Reference counting is also skipped, so `MaterialManager` can neither dedupe nor reclaim the override.
+- **Fix**: Route both sites through the manager
+  (`sg.material = materialManager.obtain(material_override).getValue()`), tracking/releasing the
+  reference the same way `ShadedGeometrySystem`'s `#material_references` does.
+- **Confidence**: Confirmed (ordering verified; the lighting consequence follows from the contract
+  documented in `ShadedGeometrySystem.link`)
+
+---
+
+### GFXR-13 `BoneMapping.build` commits the WORST bone name match first
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/mesh/skeleton/BoneMapping.js:13-15, 55, 61`
+- **Defect**: `string_compute_similarity` is Jaro-Winkler and is documented "Higher value means string
+  are more similar". The comparator sorts **descending** (best first), and the consumption loop then
+  takes from the tail:
+  ```js
+  function byDistance(a, b) { return b.distance - a.distance; }   // descending
+  matches.sort(byDistance);
+  ...
+  const match = matches.pop();                                     // takes the LEAST similar pair
+  ```
+  Because the inner loop immediately evicts every remaining entry sharing that `boneIndex` or
+  `inputIndex`, the worst pairing is locked in permanently — this is a greedy assignment run in
+  exactly reverse order.
+- **Failure scenario**: Load a rigged glTF whose bones are `Hips, Spine, Chest, Neck, Head, …`.
+  `SkeletonUtils.findSkeletonBoneByType` builds the mapping on first use. The globally least-similar
+  (bone, name) pair — say (`HumanoidBoneType.Head`, `"toe-right"`) — is committed first and consumes
+  the `Head` slot. `Mesh.getBonePositionByType(result, HumanoidBoneType.Head)` then returns the world
+  position of the right toe, so anything anchored to a humanoid bone (weapon socket, head-mounted VFX,
+  nameplate) attaches to the wrong body part.
+- **Fix**: Consume best-first — either flip the comparator to `a.distance - b.distance` and keep
+  `pop()`, or keep the sort and use `matches.shift()` (with the inner splice loop starting at 0).
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-14 `SGMeshAnimationControllerSystem.update` spins on one unloaded mesh and starves the rest of the queue
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshAnimationControllerSystem.js:159-167` with `:57-68`, `:90-92`
+- **Defect**: `update` pops up to 1000 entities per tick and calls `this.#process(entity)` without
+  awaiting. `#process` re-enqueues synchronously when the mesh has not loaded
+  (`if (mesh.node === null) { this.#enqueue(entity); return; }`), and `#enqueue` **pushes to the tail**
+  while `update` **pops from the tail**. The same entity is therefore popped and re-pushed
+  immediately, for all 1000 iterations.
+  ```js
+  const entity = this.#queue.pop();
+  this.#process(entity);          // re-pushes to the same end it was popped from
+  ```
+- **Failure scenario**: Three units spawn in the same frame; A and B have cached meshes, C's glTF is
+  still downloading. The queue is `[A, B, C]`. Frame 1: `pop()` yields C, C re-queues, `pop()` yields C
+  again — 1000 times. A and B are never reached. This repeats every frame until C's asset resolves, so
+  A and B never get `controller.bound` populated and stand completely frozen for the whole duration of
+  C's download, even though their own meshes were ready immediately. Also burns 1000 pop/push cycles
+  per frame doing nothing.
+- **Fix**: Use FIFO — `this.#queue.shift()` in `update` (or push to the head in `#enqueue`) — and cap
+  the loop by the queue length captured *before* the loop, so re-queued entities are deferred to the
+  next tick rather than reprocessed within the same one.
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-15 HiZ occlusion query samples `n_max.y` as an x coordinate
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/render/visibility/hiz/query/QueryShader.js:108`
+- **Defect**: The four taps are meant to be the four corners of the projected AABB. The
+  bottom-right tap reads `vec2(n_max.y, n_min.y)` — `n_max.y` where `n_max.x` was meant:
+  ```glsl
+  float n1 = textureLod(utDepth, vec2(n_min.x, n_max.y), float(mip_to_use)).x;
+  float n2 = textureLod(utDepth, vec2(n_max.y, n_min.y), float(mip_to_use)).x;   // n_max.x
+  ```
+- **Failure scenario**: A wide, short object — a wall whose projected box spans x∈[0.1, 0.9],
+  y∈[0.40, 0.45]. `n2` samples at x = 0.45 instead of x = 0.9, so the depth in front of the wall's
+  right-hand half is never read. `n = max(n0..n3)` therefore under-reports the scene depth over that
+  region and `depth_delta = n - n_min.z` goes negative: the wall is classified occluded and culled
+  while plainly on screen. The error is silent, view-dependent, and worse the wider the object.
+- **Fix**: `float n2 = textureLod(utDepth, vec2(n_max.x, n_min.y), float(mip_to_use)).x;`
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-16 `HierarchicalZBuffer.build_mips` publishes the mip chain on a property three.js never reads
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/render/visibility/hiz/buffer/HierarchicalZBuffer.js:168-169`
+- **Defect**: `this.__input_buffer.mips = mips.map(m => m.texture);` — `THREE.Texture` in r136 has no
+  `mips` field; the array `WebGLTextures` consults when `generateMipmaps === false` is `mipmaps`.
+  The assignment creates an inert own-property, so the reduction targets are never bound as mip levels
+  of the texture that `BatchOcclusionQuery.execute` hands to the shader as `utDepth`.
+- **Failure scenario**: The reduction pass fills every mip render target correctly, but `utDepth` still
+  has only level 0 (`minFilter: NearestFilter`, no uploaded chain), so every
+  `textureLod(utDepth, uv, float(mip_to_use))` clamps to level 0. A distant object whose AABB covers
+  one texel at `mip_to_use = 6` is tested with four full-resolution point samples instead of the
+  conservative max over its footprint: the hierarchical test degenerates into a 4-sample point test
+  and reports visible objects as occluded — geometry pops in and out at distance.
+- **Fix**: Bind the reduction targets' textures as explicit `sampler2D` uniforms and index them in the
+  shader, or build a real `mipmaps` chain on `__input_buffer` that `WebGLTextures` will upload.
+  Renaming the property alone is not sufficient — `mipmaps` entries are image-like objects, not render
+  targets.
+- **Confidence**: Likely (only in-repo consumer today is `hiz/prototypeHiZ.js`, so this is latent)
+
+---
+
+### GFXR-17 `SGMesh.copy()` does not copy `flags`, so `clone()` re-enables shadow casting
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/mesh-v2/aggregate/SGMesh.js:82-88`
+- **Defect**: `copy(other)` transfers `__url`, `__node`, `__initial_bounds` and `#material_override`
+  but not `flags` — the sole backing store for `castShadow`/`receiveShadow`/`Loaded`. `equals()`
+  (line 68) nonetheless compares `this.flags === other.flags`.
+- **Failure scenario**: A prefab `SGMesh` with `castShadow = false` (a flat ground decal mesh, say).
+  `prefab.clone()` yields a component with `DEFAULT_FLAGS = CastShadow | ReceiveShadow`, so every
+  cloned instance casts a shadow the original explicitly disabled. Additionally
+  `prefab.equals(prefab.clone())` is `false`, defeating any equality/hash-keyed reuse of the component.
+- **Fix**: Add `this.flags = other.flags & ~SGMeshFlags.Loaded;` to `copy()` (`Loaded` must be cleared
+  because `__node` is reset to `null`).
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-18 `SGMeshAnimationControllerSystem` has no `unlink`, so destroyed entities stay queued
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshAnimationControllerSystem.js:57-68` (no `unlink` anywhere in the class)
+- **Defect**: `link` enqueues the entity when its mesh has not loaded. The class defines no `unlink`,
+  so nothing drains `#queue` when the entity is destroyed. `#process` then does
+  `ecd.getComponent(entity, SGMesh)` — which returns `undefined` for a removed entity
+  (`EntityComponentDataset` deletes the slot) — and dereferences `mesh.node`.
+- **Failure scenario**: Spawn an entity with `SGMesh.fromURL(...)` + `SGMeshAnimationController`; the
+  asset is not yet resolved so `link` queues it. Destroy the entity the same frame (unit dies, preview
+  cancelled). Next tick, `update` pops it and `#process` throws
+  `TypeError: Cannot read properties of undefined (reading 'node')`. Because `update` calls the async
+  `#process` without awaiting, this surfaces as an unhandled promise rejection rather than a thrown
+  frame error — silent in production, and the diagnostics for the real problem are lost.
+- **Fix**: Add `unlink(anim, mesh, entity)` that removes `entity` from `#queue`.
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-19 Ambient light with `castShadow` builds a shadow view, then crashes the frame
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/light/binding/three/ThreeLightBinding.js:476-491`
+- **Defect**: `__apply_castShadow` calls `__shadowmap_link()` whenever `castShadow` is true, with no check
+  that the underlying three light actually owns a `shadow`. `THREE.AmbientLight` does not — only
+  Directional/Spot/Point define one. Every *other* shadow site in the file guards for exactly this
+  (`applySettings:525` `if (shadow !== undefined)`, `__shadowmap_unlink:316`), and
+  `LightSystem.__visit_entity_to_update_shadow:210` excludes AMBIENT with the comment "only non-ambient
+  lights can cast shadow" — so this is a state the code already treats as reachable, not a can't-happen.
+- **Failure scenario**: An entity carries `Light{type: AMBIENT, castShadow: true}` —
+  `Light.fromJSON` and `LightSerializationAdapter.serialize` both persist `castShadow` unconditionally
+  for every light type, so an editor toggle or a saved blueprint produces it. `link()` registers a
+  shadow `CameraView` with `graphics.views`. On the next `constructVisibleScene`,
+  `__shadowmap_prepare_view` does `const shadow = light.shadow;` (undefined) then
+  `const camera = shadow.camera;` → `TypeError`. That throw propagates out of
+  `CameraView.build_visibility` → `CameraViewManager.build_visibility` →
+  `GraphicsEngine.constructVisibleScene`, so the whole frame dies — every frame, permanently.
+- **Fix**: `if (v && this.__shadow_map === null && light.shadow !== undefined) { … }`
+- **Confidence**: Confirmed (crash mechanism verified against three r136; reachability requires the
+  ambient+castShadow authoring combination)
+
+---
+
+### GFXR-20 Shadow cameras have `matrixAutoUpdate = false`, so `LightShadow.updateMatrices` cannot refresh their pose
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/light/binding/three/ThreeLightBinding.js:549`
+- **Defect**: `applySettings` sets `shadow.camera.matrixAutoUpdate = false` for directional/spot shadows.
+  three r136's `LightShadow.updateMatrices` writes `shadowCamera.position` / calls `lookAt(...)` and then
+  relies on `shadowCamera.updateMatrixWorld()` to recompose — but `Object3D.updateMatrixWorld` only calls
+  `updateMatrix()` when `matrixAutoUpdate` is true, and `matrixWorldNeedsUpdate` is false at that point,
+  so neither `matrix` nor `matrixWorld`/`matrixWorldInverse` is updated. (`lookAt` itself calls
+  `updateWorldMatrix(true,false)`, which is equally inert, so even the look rotation is derived from the
+  stale world position.) The point-light branch two lines above documents precisely this requirement and
+  keeps `matrixAutoUpdate = true`; the directional/spot branch does the opposite. `LightSystem.js:325`
+  even has a comment asserting the opposite of what happens: *"refresh shadow camera world matrix from
+  the light's pose before we read matrixWorldInverse"* — `shadow.updateMatrices(light, 0)` there is a
+  no-op with respect to `matrixWorldInverse`.
+- **Failure scenario**: The only place that ever bakes the pose is `__shadowmap_prepare_view`
+  (`camera.updateMatrix(); camera.updateMatrixWorld();`), fired from `preVisibilityBuild` — i.e. earlier
+  in the frame than `three_update_shadow_camera_extents`, which runs on
+  `visibilityConstructionEnded`. (a) First frame a light starts casting: `prepare_view` bakes the
+  constructor pose (origin, identity), so `compute_view_frustum_aabb_in_space` fits the ortho box in
+  **world** space instead of light space — a visibly wrong/missing shadow flash on level load.
+  (b) Steady state: a spot light carried by a moving character always renders and fits from the pose
+  captured on the previous frame, so its shadow trails the light while strafing.
+- **Fix**: Leave `matrixAutoUpdate` at three's default `true` for all shadow cameras (three's own
+  `WebGLShadowMap` never disables it), or explicitly call `shadow.camera.updateMatrix();
+  shadow.camera.updateMatrixWorld();` after every `shadow.updateMatrices(light, i)`.
+- **Confidence**: Confirmed (mechanism verified against `three/src/lights/LightShadow.js` and
+  `Object3D.updateMatrixWorld` in r136)
+
+---
+
+### GFXR-21 `three_update_shadow_camera_extents` rebuilds the main camera's projection matrix, discarding every projection modifier
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/light/LightSystem.js:334-345`
+- **Defect**: To fit the shadow box, the function truncates `camera.far`, calls
+  `camera.updateProjectionMatrix()`, reads the matrix, then restores `far` and calls
+  `updateProjectionMatrix()` again. The in-code claim that "callers downstream see no change" is wrong:
+  `updateProjectionMatrix()` regenerates the matrix from `fov/aspect/near/far`, restoring the *default*
+  projection — not whatever the matrix previously contained. `CameraView.set_from_camera:123` writes
+  modified matrices straight back into `camera.projectionMatrix.elements`, and it runs *earlier* in the
+  same frame (`GraphicsEngine.constructVisibleScene`: `set_from_camera` at line 707,
+  `visibilityConstructionEnded` — where this function is hooked — at line 710).
+- **Failure scenario**: `TemporalSupersamplingRenderPlugin` is enabled and one shadow-casting
+  directional light has a finite `maxShadowDistance` below `camera.far` (e.g. 60 vs 1000), so
+  `needs_truncation` is true. Every frame the jitter written into `elements[8]/[9]` is wiped before the
+  scene is drawn, so TAA resamples the identical position forever: the image never converges and edge
+  aliasing is exactly as if TAA were off, while the plugin still pays its full cost. Setting
+  `maxShadowDistance = Infinity` makes TAA start working — a baffling coupling. Any other registered
+  `CameraView.projection_modifier` is destroyed the same way.
+- **Fix**: Do not mutate the live camera. Build the truncated projection into a scratch `Matrix4` with
+  `makePerspective(...)` and multiply that by `camera.matrixWorldInverse`; failing that, save and restore
+  the 16 elements of `projectionMatrix` (and `projectionMatrixInverse`) verbatim.
+- **Confidence**: Confirmed (mechanism and frame ordering both verified)
+
+---
+
+### GFXR-22 Binary light serializer drops POINT `distance` and DIRECTION `maxShadowDistance`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/light/LightSerializationAdapter.js:22-26` and `:41-45`
+- **Defect**: `distance` is written and read only inside `if (type === LightType.SPOT)`, but the
+  component uses `distance` for POINT as well (`Light.js:51`, `LightBinding.scaled_distance`,
+  `ThreeLightBinding.__apply_distance`, `FPLightBinding.#updateDistance`). The JSON adapter gets it right
+  — `Light.toJSON` writes `distance` for `SPOT || POINT` (verified) — which pins this as an oversight
+  rather than a schema decision. `maxShadowDistance` (written by `toJSON` for DIRECTION) is absent from
+  the binary format entirely.
+- **Failure scenario**: A torch entity `Light{type: POINT, distance: 20}` is saved through the binary ECS
+  serializer. On load, `deserialize` never reads `distance`, so the component keeps
+  `DEFAULT_DISTANCE = 1`; `__apply_distance` sets the three `PointLight.distance = 1` (or the Forward+
+  `radius = 1`). The torch illuminates a 1-unit sphere and the room around it is black — while the exact
+  same scene loaded from a JSON save looks correct.
+- **Fix**: Write/read `distance` in a `SPOT || POINT` branch mirroring `Light.toJSON`, add
+  `maxShadowDistance` for DIRECTION, and bump `version` from 0 since the byte layout changes.
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-23 `LightSystem.shutdown` never detaches the three light cache
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/light/LightSystem.js:97` (attach, in the constructor) vs `:162-171` (shutdown)
+- **Defect**: The constructor does `this.__three_light_cache.attach(this.scene)`. `shutdown()` releases
+  the Forward+ plugin and detaches the `visibilityConstructionEnded` handler, but never calls the
+  `ThreeLightCache.detach()` that exists for exactly this purpose. Every three light the cache ever
+  created — including pooled, currently-unused ones — stays parented to `graphics.scene`, which outlives
+  the `EntityManager`.
+- **Failure scenario**: The host app keeps one `GraphicsEngine` across level loads and rebuilds the
+  `EntityManager` (a new `LightSystem` each time). After each cycle the previous cycle's
+  `DirectionalLight`/`PointLight`/`SpotLight`/`AmbientLight` objects remain in the scene.
+  `WebGLRenderer.projectObject` pushes every visible `isLight` object into `WebGLLights` regardless of
+  intensity, so `NUM_DIR_LIGHTS`/`NUM_POINT_LIGHTS`/`NUM_SPOT_LIGHTS` grow one generation per load: every
+  material's program cache key changes so **all** materials recompile on each load (multi-second hitch),
+  and after a handful of cycles the fragment uniform budget is exceeded and materials fail to link —
+  black scene.
+- **Fix**: Call `this.__three_light_cache.detach()` in `shutdown()`, and move the `attach(this.scene)`
+  from the constructor into `startup()` so a stopped-then-restarted system still works.
+- **Confidence**: Confirmed (leak); the recompile/black-scene escalation depends on the host recycling
+  the `EntityManager`
+
+---
+
+### GFXR-24 Shadow texel snapping uses a grid whose spacing changes every frame
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/ecs/light/shadow/setShadowCameraDimensionsDiscrete.js:28-36`
+- **Defect**: `rX = dX / shadow_map_width` where `dX`/`dY` are the light-space extents of the *current*
+  frame's view-frustum AABB, recomputed every frame by `three_update_shadow_camera_extents`. Snapping a
+  moving origin to a grid whose spacing also moves does not produce a stable world-space texel lattice —
+  the step the algorithm depends on ("Fix the overall size of the frustum based on the longest diagonal
+  … Don't allow the shadow frustum to change size as the camera rotates", `LightSystem.js:201`) is
+  documented but never implemented. Secondary: for negative `x0`, JS `%` returns a negative remainder, so
+  `x0_d = x0 - (x0 % rX) - rX/2` can land up to half a texel *inside* `x0`, clipping coverage off the
+  left/bottom edge (the `(w+1)/w` slack is added only at the far edge).
+- **Failure scenario**: Slowly orbit the camera over a static scene lit by one shadow-casting sun. The
+  shadow map re-quantises onto a different lattice each frame, so shadow boundaries crawl and shimmer
+  texel by texel — exactly the artifact the discretisation exists to remove. With the camera positioned
+  so the fit box straddles the origin, up to half a texel of shadow is also missing along one edge.
+- **Fix**: Derive a frame-invariant extent from the view frustum's longest diagonal at the shadow
+  distance and use it for `dX`/`dY`, then snap with `Math.floor(x / rX) * rX` instead of `%`.
+- **Confidence**: Likely
+
+---
+
+### GFXR-25 Forward+ vertex-only lighting reads `gl_Position` before `<project_vertex>` writes it
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/render/forward_plus/materials/fp_build_vertex_lighting_shared.js:9-13, 26`
+- **Defect**: The froxel-lookup preamble is injected immediately after `void main() {`:
+  ```js
+  result = insert_after(result, 'void main() {', accumulation_pars);
+  ```
+  and `accumulation_pars` begins with
+  `vec3 fp_normalized_screen_position = ((gl_Position.xyz / gl_Position.w)+vec3(1.0))*0.5;`.
+  In a three.js vertex shader `gl_Position` is assigned much later, by `#include <project_vertex>`.
+  This is an unconditional read of a vertex-stage built-in output before it is written.
+- **Failure scenario**: A lit material compiled with `defines.LIGHTING_VERTEX_ONLY === true` (the branch
+  `MaterialTransformer.js:63` selects) computes `clip_v` from an undefined value, so
+  `v3_cluster_position` indexes a random froxel. Out-of-range `texelFetch` returns 0 →
+  `fp_cluster_metadata.y == 0` → the mesh receives **zero** clustered light and renders unlit; in-range,
+  it is lit by an unrelated part of the screen and flickers per vertex as the garbage changes.
+- **Fix**: Inject after `#include <project_vertex>` instead, or compute the clip position locally
+  (`projectionMatrix * modelViewMatrix * vec4(position, 1.0)`) rather than reading `gl_Position`.
+- **Confidence**: Confirmed (the read-before-write is unconditional; no in-repo material currently sets
+  `LIGHTING_VERTEX_ONLY`, so this is public-surface breakage rather than a live regression)
+
+---
+
+### GFXR-26 `LightManager.dispose()` frees GPU objects but leaves every light still subscribed to the dead manager
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/render/forward_plus/LightManager.js:1137-1142`
+- **Defect**: `dispose()` disposes four textures and nothing else. Three subscription families survive:
+  `LightRenderMetadata.link` (`LightRenderMetadata.js:52`) binds `this.update` to
+  `light.position.onChanged` / `light.radius.onChanged` (removed only by `removeLight` → `unlink()`);
+  `__handle_visible_light_added` (`:596-597`) binds `__handle_light_dimensions_change` /
+  `__handle_light_appearance_change`; `__handle_visible_decal_added` (`:538-546`) binds to
+  `patch_uv.position.onChanged` / `patch_uv.size.onChanged` and stores an un-released
+  `Reference<AtlasPatch>`. `__decal_atlas` is never disposed either.
+- **Failure scenario**: `ForwardPlusRenderingPlugin.shutdown()` disposes the manager while a scene with
+  FP point lights and decals is still loaded (plugin released before entities unlink, or an engine
+  reconfiguration). Every live `PointLight.position` signal still holds a handler bound to the dead
+  manager, keeping it, its BVH, its cluster-plane buffers and all atlas patches reachable — a full leak
+  per plugin cycle. Worse, moving any of those lights afterwards still runs
+  `LightRenderMetadata.update()`, writing bounds into the abandoned BVH; re-acquiring the plugin creates
+  a second `LightManager` while the first keeps mutating.
+- **Fix**: In `dispose()`, iterate `#metadata_map` calling `data.unlink()` and clear it; drain
+  `__visible_lights`/`__visible_decals` through the existing `__handle_visible_*_removed` teardown so the
+  handlers and atlas references are released; dispose `__decal_atlas`.
+- **Confidence**: Likely
+
+---
+
+### GFXR-27 Forward+ `SpotLight` is accepted by `addLight` and then silently never rendered
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/render/forward_plus/LightManager.js:771-796`
+- **Defect**: The visibility dispatch branches on `light.isDecal` then `light.isPointLight` and drops
+  everything else on the floor. `render/forward_plus/model/SpotLight.js` implements everything `addLight`
+  requires (`getAABB` via `cone_compute_bounding_box`, `onDimensionChanged`, `toArray`), so
+  `addLight(spotLight)` succeeds and inserts a BVH leaf — it is simply never binned.
+  `encode_light_type` would have thrown on it and `spot_light_inside_volume` exists, but neither is
+  reached.
+- **Failure scenario**: A consumer builds a `SpotLight` from `forward_plus/model/SpotLight.js` and adds
+  it to the manager expecting a cone of light. Nothing appears and nothing is logged — the light silently
+  contributes zero for the lifetime of the scene. Companion trap: `SpotLight.prototype.ENCODED_SLOT_COUNT`
+  is never assigned and `toArray` returns 13 (not a multiple of 4), so naively adding the branch makes
+  `address += undefined` produce `NaN` and trips the "Expected light data size" throw at `:878`.
+- **Fix**: Either reject unsupported light types loudly in `addLight`, or complete the spot path —
+  `SpotLight.prototype.ENCODED_SLOT_COUNT = 16` (pad `toArray` to a 4-slot boundary), a type code in
+  `encode_light_type`, an `isSpotLight` branch here using `spot_light_inside_volume`, and the matching
+  branch in `query_bvh_frustum_from_texture`.
+- **Confidence**: Likely
+
+---
+
+### GFXR-28 `decal_filtering_enabled` setter never re-uploads, and leaves a mipmap-incomplete texture
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/render/forward_plus/LightManager.js:359-367` (constructor at `:221-223`)
+- **Defect**: The setter flips `t.generateMipmaps` and stops — `texture.version` is never bumped, so
+  three does not re-upload and the setting has no effect until an unrelated atlas repack. When that
+  repack eventually happens, `generateMipmaps === false` while `minFilter` is still
+  `LinearMipMapLinearFilter`; on WebGL2 three's `setTextureParameters` applies `LINEAR_MIPMAP_LINEAR`
+  verbatim and `uploadTexture` skips `generateMipmap`.
+- **Failure scenario**: A game follows the method's own JSDoc ("Please set this to false if you have a
+  lot of overlapping decals") and sets `lightManager.decal_filtering_enabled = false`. Nothing changes on
+  screen. Later a new decal texture is registered, the atlas repacks and re-uploads — and every decal now
+  samples a mipmap-incomplete texture, rendering solid black instead of its diffuse.
+- **Fix**: `t.generateMipmaps = v; t.minFilter = v ? LinearMipMapLinearFilter : LinearFilter;
+  t.needsUpdate = true;`
+- **Confidence**: Confirmed (missing re-upload); Likely (black-decal consequence)
+
+---
+
+### GFXR-29 Debug froxel grid uses a 3-channel stride on the RGBA cluster texture and overruns each axis
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/render/forward_plus/debug/createScreenGrid.js:47-51` and `:272-281`
+- **Defect**: `const texel_address = texel_index * 3; // RGB format` — the cluster texture is RGBA:
+  `LightManager.__assign_lights_to_clusters` writes at `tile_index * 4` (`LightManager.js:970`) and
+  `LightManager.spec.js:23` asserts a 4-element image for a 1×1×1 grid. Stride 3 aliases into the wrong
+  texel for every cell but index 0. The loops additionally run `i < resolution.N + 1`, so
+  `resolution.x - 1 - i_x` reaches `-1` and the z loop reads a slice past the end.
+- **Failure scenario**: Open the debug screen grid on a 12×6×4 grid. Cell (3,2,1)'s reported light count
+  is read from a completely different froxel, so both the heatmap and the click-tooltip light list
+  describe the wrong cells — the tool actively misleads anyone debugging the binning.
+- **Fix**: Use `texel_index * 4` / `index * 4` in both places and drop the `+ 1` from all three loop
+  bounds.
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-30 Cluster-volume debug widget clones the 3D cluster texture every frame and never disposes it
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/render/forward_plus/debug/buildLightClusterWidget.js:56-64`
+- **Defect**: `const t = lm.getTextureClusters().clone(); t.needsUpdate = true; m.uniforms.map.value = t;`
+  — a fresh `DataTexture3D` per `update()`, with the previous clone dropped without `.dispose()`. Its GL
+  texture object stays in `WebGLTextures`' property map for the widget's renderer until context loss.
+- **Failure scenario**: `update()` is driven from the render loop. At 60 fps with the default
+  32×16×16 RGBA16UI volume (~64 KB each) that is ~4 MB/s of leaked GPU memory; a couple of minutes of
+  debugging and the tab hits out-of-memory / context-lost.
+- **Fix**: Clone once outside `update()` (the clone shares `image`, so only `needsUpdate = true` is
+  needed per frame), or `m.uniforms.map.value?.dispose()` before assigning the new clone.
+- **Confidence**: Confirmed
+
+---
+
+### GFXR-31 `sort_decal_data` uses a moving pivot and sorts on slots that hold colour, not priority
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/render/forward_plus/sort_decal_data.js:20-24, 65-76`
+- **Defect**: Two independent errors. (a) The comparator reads `data[address + 20]` as `draw_priority`
+  and `+ 21` as `id`, but `Decal.toArray` (`model/Decal.js:116-121`) has both of those writes commented
+  out and `array_copy(this.color, 0, destination, address + 20, 4)` occupies slots 20-23 — so it sorts
+  decals by their red and green channels. (b) The quicksort pivot is an *index*, not a captured value;
+  `lookup[pivotIndex]` is itself swapped during partitioning, destroying the scan sentinel. The correct
+  sibling `core/collection/array/array_sort_quick.js` captures the pivot value before the loop.
+- **Failure scenario**: Re-enable the call site the `TODO fix decal sorting artifacts` block at
+  `LightManager.js:995-1003` currently guards (or call this exported function directly). When the pivot
+  entry is swapped to a higher-priority value, `i` walks past `right`, `compare_decals` starts reading
+  `undefined`, and the subsequent `lookup[j] = lookup[i]` stores `0` into a neighbouring froxel's lookup
+  run — that froxel's decal slot then points at light-data texel 0 and renders the wrong decal. This is
+  precisely the artifact the TODO describes.
+- **Fix**: Capture the pivot record (`const pivot_encoded = lookup[pivotIndex];`) and compare values, not
+  indices; and restore the `draw_priority`/`id` writes in `Decal.toArray` (widening
+  `ENCODED_SLOT_COUNT` past 24) or read priority from a slot that is actually written.
+- **Confidence**: Likely
+
+---
+
+## Verified clean / non-issues checked along the way
+
+- `GraphicsEngine.prepareRenderPass` writes `visibleGroup.length = j` where `children.length` was
+  meant — harmless: `clearVisibleGroup()` truncates `children` to 0 first, so `children.length`
+  already equals `j`. No failure scenario, not reported.
+- `OutlineRenderer.writeParameters` → `HashMap.forEach` passes `(value, key)`, which matches
+  `__write_parameters_for_definition(id, definition)`. Correct.
+- `OutlineRenderPlugin` subscribe/unsubscribe pairs match (`Vector2.process` adds to `onChanged` with
+  the same handler + context that `shutdown` removes).
+- `AmbientOcclusionPostProcessEffect` startup/shutdown binding pairs all match; all four GPU resources
+  are disposed.
+- TAA jitter indices (`elements[8]`/`[9]`) and magnitude match the pinned spec; the `=` (rather than
+  `+=`) is deliberate, since `CameraView.set_from_camera` writes the jittered matrix back onto the
+  camera and `CameraSystem`'s `visibilityConstructionStarted` hook rebuilds it each frame.
+- `Water.updateBounds` BVH box agrees with the plane mesh's rotated/offset world extent.
+- `FrameBufferManager.computeRenderOrder` splice-while-iterating is correctly compensated
+  (`i--; openSetCount--`), as is `WaterSystem.processUpdateQueue`.
+- `GizmoRenderingPlugin` overrides `RenderLayer.buildVisibleSet` (whose prototype version throws
+  `'deprecated'`) — but `VisibilityComputer.__processLayer` still calls it, so gizmos do render.
+- `RenderLayer.js:59`'s comment claims near is `planes[4]` and far is `planes[5]` (they are the other
+  way round), but it documents `computeNearFarClippingPlanes`, which unconditionally throws
+  `'deprecated'`. Stale doc only.
+- Forward+ cluster index arithmetic, depth-slice distribution, plane orientation, the near/far swap and
+  X-flip in `computeFrustumCorners`, texel packing and the light-count overflow/recursion path are all
+  internally consistent and agree with `cluster_binning.spec.js` /
+  `light_culling_no_false_exclusion.spec.js`.
+- `query_bvh_frustum_from_texture.js:132` masks the light address with `& 0xFFFFFFF8` where the encoding
+  (`type | address << 2`) calls for `& 0xFFFFFFFC`. Currently harmless — every record length in use
+  (`PointLight` 8, `Decal` 24) is a multiple of 8 — so no failure scenario exists today. Noted, not filed.
+- `LightBinding` / `FPLightBinding` / `LightContext` link-unlink subscription pairs are symmetric;
+  `ThreeLightCache.release` keys off `light2type(threeObject)` rather than the already-changed component
+  type, so type-change rebuilds return the light to the correct pool.
+- `__shadowmap_unlink` disposes both `shadow.map` and `shadow.mapPass`;
+  `three_set_shadow_resolution` disposes before resizing; `compute_view_frustum_aabb_in_space`'s plane
+  ordering and `near = -z1 / far = -z0` are correct.
+- `ShadedGeometrySystem.link/unlink`, `SGMeshSystem.process`, `SGMeshHighlightSystem` and
+  `IncrementalDeltaSet` were checked in detail and are balanced/correct.
+- `FPDecalSystem.Context` correctly handles the async texture-load race (`__is_linked` and
+  `this.__fp_decal === fpDecal` re-checks) — the only defect there is the known `subscribe`/`unsubscribe`
+  typo.
+- `SpriteSystemPE`, `AnimationControllerSystem`, `RenderableHighlightSystem`,
+  `ShadedGeometryHighlightSystem`, `Trail3DSystem` and `GizmoRenderingPlugin` have matching
+  subscribe/unsubscribe pairs.
+
+## Coverage note
+
+Not exhaustively reviewed for lack of time: `ecs/path/tube/build/*` and `ecs/path/ribbon/`
+(heavily spec-covered geometry builders), `ecs/animation/animator/*` (graph/blend-space state machine,
+little graphics-correctness surface), and the GLSL bodies of `shaders/TerrainShader.js` /
+`shaders/AmbientOcclusionShader.js` / `render/buffer/simple-fx/ao/SAOShader.js` (the JS-side uniform
+wiring for those *was* reviewed and is clean).