@woosh/meep-engine 3.1.0 → 3.3.0

package/src/DUPLICATION_AUDIT_2026_08_07/D_gfx_features.md

@@ -1,164 +1,164 @@
-# Domain D — engine/graphics feature subsystems (ecs, particles, trail, impostors, sh3, shadows)
-
-Source root for all paths: `H:/git/moh/app/src/mir-engine/meep/src/`
-
-Every finding below was verified by opening the cited files. Line numbers are from the working tree
-at the time of the audit.
-
-## Findings
-
-| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
-|---|---|---|---|---|---|---|---|
-| 1 | CRITICAL | **Octahedral impostor GLSL library copy-pasted 9× inside the domain, plus 3 more name-colliding variants.** `VecToSphereOct` / `VecToHemiSphereOct` / `VectorToGrid` / `OctaSphereDec` / `OctaHemiSphereDec` / `GridToVector` / `FrameToRay` / `ComputeFrameXform` / `BilinearWeights` / `apply_frame_xform` — ~90 lines of GLSL | `engine/graphics/impostors/octahedral/shader/ImpostorShaderV0.js:71`, `ImpostorShaderDepthV0.js:59`, `ImpostorShaderNormalsV0.js:52`, `ImpostorShaderViewportDepthV0.js:46`, `ImpostorShaderWireframeV0.js:31`, `ImpostorShaderPerPixelV0.js:39` **and** `:178` (both stages), `ImpostorShaderLitV0.js:65` **and** `:328` (both stages). Incompatible same-named variants: `shader/glsl/common.glsl:25,57`, `shader/glsl/v1/common.glsl:1,45`, `shader/glsl/v1/vertex.glsl:42,86` | 9 byte-identical copies (verified with `awk` extraction — all identical). Whole-file line overlap against `ImpostorShaderV0.js`: Depth 70%, PerPixel 85%, Wireframe 86%, ViewportDepth 65%, Normals 61%. **Drift already present**: all 9 GPU copies use `sign(v)` where the CPU reference `core/geom/3d/octahedra/octahedral_direction_to_uv.js:25` deliberately uses `sign_not_zero()` — `sign(0.0)==0.0` shrinks the L1 norm and mis-folds a direction with an exactly-zero component. The bake side (`impostors/octahedral/grid/OctahedralUvEncoder.js:7`) and the sample side must agree; they are two independent transcriptions of one invariant. `glsl/common.glsl` declares `VecToSphereOct`/`GridToVector`/`VectorToGrid` with *different* semantics (y-fold via `_ImposterFullSphere`, HLSL intrinsics `frac`/`saturate`/`tex2Dgrad`) | UNJUSTIFIED | One `engine/graphics/impostors/octahedral/shader/chunk_octahedral.js` exporting a GLSL string (or a `.glsl` file — precedent exists, `ImpostorShaderV1.js:10` already imports `./glsl/v1/vertex.glsl` through the raw loader), interpolated into every shader. Delete `glsl/common.glsl`'s colliding declarations or rename them | Medium effort / Low risk — string extraction, shaders compile-checked by the existing prototype harness |
-| 2 | CRITICAL | **The production GI probe-depth GLSL library is copy-pasted into two debug visualisers.** `sign_not_zero` (3 overloads), `quadBlendWieghts`, `VecToSphereOct`, `SampleBlended`, `lpv_probe_getDepth{,Bilinear,Triangular}`, `lpv_bilinear_lerp` (2 overloads), `lpv_sample_bilinear`, `wrapOctahedralTexelCoordinates`, `lpv_probe_getPosition` | `engine/graphics/sh3/gi/material/common.js:76-298` (production) ⟷ `engine/graphics/sh3/lpv/depth/octahedral/v2/visualise.frag.glsl:26-408` ⟷ `engine/graphics/sh3/lpv/depth/octahedral/shader/visualize.frag.glsl:1-97` | Measured line-level overlap: **220 of 320** non-empty lines of `v2/visualise.frag.glsl` (68.8%) appear verbatim in `gi/material/common.js`; 51 of 97 (52.6%) for `shader/visualize.frag.glsl`. Smoking gun: the misspelling `quadBlendWieghts` is present in both (`common.js:95`, `v2/visualise.frag.glsl:45`). The whole point of the visualiser is to show what the production sampler sees — a forked copy can silently show something else | UNJUSTIFIED | Extract `engine/graphics/sh3/lpv/depth/chunk_probe_depth.js` (GLSL string) consumed by `gi/material/common.js` and by both visualiser shaders. Note `VecToSphereOct` here folds on `v.y<0` returning `.xz` while `lpv/depth/.../shader/visualize.frag.glsl:29` folds on `direction.z<0` returning `.xy` — reconcile before extracting | Medium effort / Medium risk — the two visualisers may currently rely on their divergent fold |
-| 3 | HIGH | **`AbstractMaterialTransformer.transform()` marker-guard / clone / compose protocol copied 3×, already diverged** | `engine/graphics/render/forward_plus/plugin/MaterialTransformer.js:91` `transform`; `engine/graphics/sh3/gi/material/MaterialTransformer.js:294` `transform`; `engine/graphics/sh3/lpg/material/LightProbeGridMaterialTransformer.js:207` `transform` | The 11-line "already transformed / different instance → throw" guard is byte-identical in all three. The clone step is not: FP does `result = source.clone()` (`:107`), gi does **`result.clone();`** (`MaterialTransformer.js:311`) — a discarded expression statement, so gi mutates the caller's material in place; lpg dropped the clone entirely (`:219-223`). `AbstractMaterialTransformer` (`engine/graphics/material/manager/AbstractMaterialTransformer.js:1`) is an empty 10-line stub that owns none of this. `#onBeforeCompile` is also identical between gi (`:133`) and lpg (`:77`) — same `switch(ProbeResolutionStage)` dispatch, 14 lines | UNJUSTIFIED | Move the guard + clone + `composeCompile` wiring into `AbstractMaterialTransformer` as a concrete `transform(source)` calling an abstract `_install(material)`; subclasses supply only the marker symbol and the compile hook. Typed inheritance, no registry | Low effort / Medium risk — fixing gi's dropped clone changes behaviour (correctly) |
-| 4 | HIGH | **`Trail3DSystem` is a whole-file fork of `Trail2DSystem`, and the fork's bug fix never went back** | `engine/graphics/ecs/trail2d/Trail2DSystem.js` (274 lines) ⟷ `engine/graphics/ecs/trail3d/Trail3DSystem.js` (280 lines). Method pairs: `constructor` `:66`/`:90`, `startup` `:96`/`:110`, `__build_trail`/`#build_trail` `:129`/`:141`, `link` `:191`/`:200`, `unlink` `:210`/`:221`, `updateTrailEntity` `:224`/`:233`, `update` `:260`/`:266` | Every method is identical modulo `ribbon`↔`tube`, `Point`↔`Knot`, plugin class and layer name. **Divergence with consequences**: `Trail3DSystem.js:47` extracts `compute_head_position(result, trail, transform)` = `offset.applyMatrix4(transform.matrix)` and its 15-line comment states build-time seeding and the per-frame head update *must* agree or "the head's first move draws a segment bridging the two — a one-frame streak". `Trail2DSystem.js:157-159` still seeds with `trail_offset.x + transform_position.x` (translation only) while `Trail2DSystem.js:235-236` updates the head with `applyMatrix4` — under any rotation or scale the two disagree, which is exactly the documented defect | UNJUSTIFIED | The two ribbon/tube backends genuinely differ, but the *system* does not. Extract the shared body into `TrailSystemBase` (typed abstract class holding bvh/renderLayer/plugin-ref lifecycle + `updateTrailEntity`) with abstract `#seed_geometry` / `#obtain_plugin`. At minimum promote `compute_head_position` into `engine/graphics/trail/` and call it from both build paths | Medium effort / Medium risk — Trail2D seeding change is a behaviour fix, covered by `Trail2DSystem.spec.js` |
-| 5 | HIGH | **Trail spawn/aging state machine duplicated** — reseed-on-clear, `refitTimeDelta = maxAge/count`, head-moved detection, distance accumulation, `TrailSpawnMode.Distance ? distance>=spawnDistance : time>=refitTimeDelta`, rotate, head age/alpha/thickness write | `engine/graphics/ecs/trail2d/Trail2D.js:298` `updateHead` ⟷ `engine/graphics/ecs/trail3d/Trail3D.js:417` `updateHead`; also `Trail2D.js:210` `clear` ⟷ `Trail3D.js:275` `clear` | MinHash sim 0.766 on 309/322 tokens; reading them confirms the *policy* is line-for-line the same (~45 lines), differing only by accessor names and 3D's extra `#updateHeadFrame` call. The alpha fade law `(1 - clamp01(head_age/maxAge)) * this.color.w` is restated in both and must match the simulators (`TubeXFixedPhysicsSimulator.js:28`, `RibbonXFixedPhysicsSimulator.js:27`) — 4 copies of one law | UNJUSTIFIED | Extract `trail_update_head(trail, buffer_adapter, x, y, z, head_age)` in `engine/graphics/trail/`, where the adapter is a small typed interface (`getCount/getHeadIndex/getPosition/setPosition/rotate/setAge/setAlpha/setThickness`). Simplest alternative: rename `TubeX`'s `*Knot*` methods to `*Point*` so one function serves both | Medium effort / Medium risk — per-frame code, but not per-particle; specs exist for both components |
-| 6 | HIGH | **Voxel-impostor splat expansion GLSL copied 5×, carrying a stated cross-shader invariant** | `engine/graphics/impostors/voxel/shader/VoxelImpostorShaderV0.js:45-61`, `VoxelImpostorShaderNormalsV0.js:24-31`, `VoxelImpostorShaderDepthV0.js:31-41`, `VoxelImpostorShaderViewportDepthV0.js:22-30`, `VoxelImpostorShaderLitV0.js:57-68` | The block (`model_scale = length(modelMatrix[0].xyz)` → `radius_OS` → `centre_OS = iPosition - iNormal * radius_OS` → view-space corner offset) is identical in all five. `VoxelImpostorShaderDepthV0.js:35-37` states: *"Inward-shift must match the colour pass exactly so the cast silhouette agrees with the visible one"* — the invariant is documented but not enforced, because it lives in five separate string literals | UNJUSTIFIED | `engine/graphics/impostors/voxel/shader/chunk_voxel_splat_vertex.js` exporting the shared vertex body; the five materials interpolate it and add only their own varyings | Low effort / Low risk |
-| 7 | HIGH | **Spherical-harmonic cosine-lobe irradiance evaluator implemented 4× and the copies disagree on sign convention** | `core/geom/3d/sphere/harmonics/sh3_sample_irradiance_by_direction.js:36-48` (JS); `engine/graphics/sh3/shader/visualize.frag.js:11` `shGetIrradianceAt` (GLSL); `engine/graphics/sh3/gi/material/chunk_lpv_get_irradiance_at.js:5` `lpv_get_irradiance_at` (GLSL); `engine/graphics/sh3/lpg/material/chunk_lpg_get_irradiance_at.js:9` `lpg_get_irradiance_at` (GLSL, first two bands only) | Same magic constants (`0.8862269254527579`, `1.0233267079464885`, `0.8580855308097834`, `0.4290427654048917`, `0.7431238683011272`) in all four. Signs differ: the core JS and `visualize.frag.js` negate coefficients 1, 3, 5, 7 (three.js convention); the two chunk files use `+=` throughout. `lpg/material/chunk_lpg_get_irradiance_at.js:3` even documents itself as *"first two bands of chunk_lpv_get_irradiance_at"* — an acknowledged copy. (The sign divergence is already logged in `src/REVIEW_2026_08_06/adv-gfx.md:359`; cited here only as proof the duplication produced a real defect) | UNJUSTIFIED | One `engine/graphics/sh3/chunk_sh_irradiance.js` GLSL module exporting an L2 evaluator plus a truncated L1 evaluator over `vec3[4]`, next to the single JS `sh3_sample_irradiance_by_direction`. Pin one sign convention and state it in a comment at both | Low effort / High risk — changing signs changes rendered output; needs a bake-vs-shader A/B first |
-| 8 | MEDIUM | **Three highlight systems are the same `System` + `Supplier` scaffold with a 15-line hole** | `engine/graphics/ecs/highlight/system/MeshHighlightSystem.js` (162 ln), `RenderableHighlightSystem.js` (164 ln), `ShadedGeometryHighlightSystem.js` (175 ln). Duplicated members: `class Supplier` `:9`/`:9`/`:8`, `collect` `:33`/`:38`/`:44`, `shutdown` `:121`/`:125`/`:137`, `startup` `:137`/`:143`/`:154`, and the whole `constructor` | `diff -u` between Renderable and ShadedGeometry shows the *only* semantic differences are the traversal component pair and how the three.js object is obtained; between Mesh and Renderable, only the visibility-flag check and the object accessor. ~130 of ~165 lines are common to all three | UNJUSTIFIED | Abstract `HighlightSystemBase extends System` owning the `OutlineRenderPlugin` reference lifecycle and the `Supplier` (which delegates to an abstract `visit(highlight, component, entity)`); three thin typed subclasses. Plain inheritance — no registry, no strings | Low effort / Low risk (`ShadedGeometryHighlightSystem.spec.js` exists) |
-| 9 | MEDIUM | **Neighbour-average flood-fill ("dilate") written twice — 2D lightmap and 3D probe grid** | `engine/graphics/sh3/lightmap/lightmap_dilate.js:18` `lightmap_dilate` (4-connected, `channels` values/texel) ⟷ `engine/graphics/sh3/lpg/light_probe_grid_dilate.js:29` `light_probe_grid_dilate` (6-connected, 12 values/probe) | Identical algorithm: skip covered cells; accumulate valid neighbours into a `Float64Array` accumulator; if `n===0` continue; write `acc[c]/n`; mark newly covered; repeat. Even the guard shape (`x > 0 && coverage[index-1] !== 0`) matches per-axis. Only the pass-snapshot mechanism differs (`newly[]` array vs `__source_validity` copy) and the termination (iteration cap vs run-to-convergence). Invisible to the mechanical pass — different identifiers and one extra loop level put it under the MinHash threshold | UNJUSTIFIED | One `core/collection/grid/grid_dilate_average(data, coverage, size_x, size_y, size_z, channels, iterations)`; the lightmap call passes `size_z = 1`. Note `lightmap_dilate.js:24` allocates `newly` per iteration — folding into the LPG's snapshot form removes that too | Medium effort / Low risk — both have specs (`lightmap_dilate.spec.js`, `light_probe_grid_dilate.spec.js`) |
-| 10 | MEDIUM | **Area-weighted triangle surface sampling copy-pasted instead of reusing the function next door** | `engine/graphics/particles/particular/engine/utils/distributeParticlesOnObject3D.js:169-233` ⟷ `engine/graphics/particles/particular/engine/utils/distrubuteParticlesOnMesh.js:112-187` `distributePointsOnMesh` | ~65 lines verbatim: same `poly:` label, same `roundFair(placementCount, random)`, same index/vertex fetch, same barycentric picking including the identical source-URL comment (`https://math.stackexchange.com/questions/538458/...`) and the same `r1 = random() * (1 - r0)` sampling. `distributePointsOnMesh` is already the generic, callback-driven form and is exported — `distributeParticlesOnObject3D` just doesn't call it. There is no other area-weighted triangle sampler in the codebase (grep for the URL and for `random point on the triangle` returns exactly these two files) | UNJUSTIFIED | Split `distributePointsOnMesh` into `distribute_points_on_indexed_triangles(count, points, indices, polygon_count, transform, seed, callback)` plus the two thin `Mesh` / `Object3D` front-ends. `distributeParticlesOnObject3D`'s `visitObject` (`:20`) already flattens the hierarchy into `buffer_points`/`buffer_indices` — it only needs to hand those to the shared loop | Low effort / Low risk |
-| 11 | MEDIUM | **Two-record swap across an array of `BufferAttribute`s written twice** | `engine/graphics/particles/particular/engine/emitter/ParticlePool.js:202` `swap` ⟷ `engine/graphics/particles/particular/group/ParticleGroup.js:550` `swapAttributeValues` | MinHash sim 0.953. 25 lines, identical down to `const offsetA = indexA * itemSize`; only the temp variable name (`temp` vs `elementA`) and a trailing `attribute.needsUpdate = true` differ. Both operate on the same shape (array of three.js `BufferAttribute`) | UNJUSTIFIED | `engine/graphics/geometry/buffer_attributes_swap_records(attributes, index_a, index_b)` in `engine/graphics/geometry/`; both call it, `ParticleGroup` sets `needsUpdate` itself afterwards | Low effort / Low risk |
-| 12 | MEDIUM | **Nearest-point-on-triangle leaf handler duplicated across the two BVH nearest queries** | `engine/graphics/geometry/buffered/query/query_bvh_geometry_nearest.js:164-203` ⟷ `engine/graphics/geometry/buffered/query/bvh32_geometry_nearest.js:203-242` | The traversal halves legitimately differ (pointer-based `BVH` vs implicit-index `BinaryUint32BVH`), but the leaf halves are byte-identical for 40 lines: `tri3_closest_point_barycentric` → `w = 1-u-v` → `contact = a*u + b*v + c*w` → `v3_distance_sqr` → early-out → `result.position.set` → `tri3_compute_normal` → `result.index`. The barycentric-reconstruction convention (which of u/v/w pairs with which vertex) is the subtle part and it is stated twice | UNJUSTIFIED | Extract `tri3_nearest_accept(result, x, y, z, ax..cz, triangle_index, best_distance_sqr) -> number` (returns the new best, or the old one). Both queries call it from their leaf branch. Function-call overhead in the leaf is negligible next to the barycentric solve | Low effort / Low risk (both have specs) |
-| 13 | MEDIUM | **`load-from-storage-else-build-and-cache` + scene-bounds traversal duplicated between LPG and LPV** | `engine/graphics/sh3/lpg/light_probe_grid_obtain_storage_cached.js:18` ⟷ `engine/graphics/sh3/lpv/lpv_obtain_storage_cached_volume.js:18` | MinHash sim 0.953, 198/200 tokens. Lines 44-65 vs 46-67 are byte-identical: build an `AABB3`, `setNegativelyInfiniteBounds()`, `ecd.traverseEntities([ShadedGeometry, Transform], ...)`, allocate a fresh `AABB3` **inside the visitor** (a per-entity allocation, duplicated), `mesh_bounds.union(box)`. The un-awaited `engine.storage.promiseStoreBinary(key, buffer.data)` with no error path is also duplicated (`:81` / `:83`) | UNJUSTIFIED | Promote `scene_compute_shaded_geometry_bounds(out_aabb3, ecd)` into `engine/graphics/ecs/mesh-v2/` next to the existing `sg_hierarchy_compute_bounding_box_via_parent_entity.js:28`, using a module-static scratch box. The load/build/store protocol can stay per-subsystem (the adapter types are genuinely different) | Low effort / Low risk |
-| 14 | MEDIUM | **Bake-task-with-progress-overlay scaffold duplicated** | `engine/graphics/sh3/lpg/build_light_probe_grid_for_scene.js:18` `light_probe_grid_bake_via_task` ⟷ `engine/graphics/sh3/lpv/build_probes_for_scene.js:20` `lpv_volume_bake_via_task` | MinHash sim 0.922. ~25 lines identical: `makeSimpleTaskProgressView({task, localization, size: new Vector2(512,64)})`, a throwaway `Entity` with `GUIElement.fromView` + `ViewportPosition.fromJSON({position:(0,1), anchor:(0,1), offset:(16,-16)})`, `task.promise().finally(() => progress_entity.destroy())`, `engine.executor.runGroup(task)`, `await task.promise()`. Only the baker class differs. `makeSimpleTaskProgressView` has exactly two non-prototype callers — both of these | PROMOTION | `engine/run_task_with_progress_overlay(task, engine, ecd)` beside `engine/makeSimpleTaskProgressView.js`. Both bakers call it | Low effort / Low risk |
-| 15 | MEDIUM | **Camera depth-plane construction + render-layer depth-range accumulation duplicated** | `engine/graphics/ecs/camera/auto_set_camera_clipping_planes.js:60-84` ⟷ `engine/graphics/ecs/light/shadow/extend_shadow_camera_near_for_casters.js:69-90` | Two verbatim blocks. (a) The three.js matrix convention `nx=-m[8], ny=-m[9], nz=-m[10]`, `plane_constant = -(nx*m[12]+ny*m[13]+nz*m[14])` — a vendor-layout invariant restated twice. (b) `scratch_range.near = +Infinity; far = -Infinity;` then `layers.traverse(layer => { if(!layer.state.visible) return; const compute = layer.compute_depth_range; if (compute === null) return; compute(...) })` — identical including the null guard and the sentinel initialisation | PROMOTION | `engine/graphics/render/layers/render_layers_compute_depth_range(out_range, layers, planes, matrix_world_elements)` doing both halves. Both callers shrink to a call plus their own clamping policy | Low effort / Low risk (`auto_set_camera_clipping_planes.spec.js` exists) |
-| 16 | MEDIUM | **`compute_depth_range` BVH closure written 7× verbatim** | `engine/graphics/ecs/trail2d/Trail2DSystem.js:110`, `engine/graphics/ecs/trail3d/Trail3DSystem.js:124`, `engine/graphics/ecs/mesh/MeshSystem.js:162`, `engine/graphics/ecs/mesh-v2/ShadedGeometrySystem.js:269`, `engine/graphics/ecs/water/WaterSystem.js:110`, `engine/graphics/particles/ecs/ParticleEmitterSystem.js:104`, `engine/ecs/renderable/RenderSystem.js:74` | All seven are `const bvh = <this bvh>; layer.compute_depth_range = (result, frustum, nx, ny, nz, c) => { bvh_query_depth_range_in_frustum(result, bvh, frustum, nx, ny, nz, c); };`. The sibling helper `make_bvh_visibility_builder` already exists in `engine/graphics/render/` and is used by six of these — the depth-range half was never given the same treatment | PROMOTION | `engine/graphics/render/make_bvh_depth_range_computer(bvh)` next to `make_bvh_visibility_builder.js`; all seven become one-liners | Low effort / Low risk |
-| 17 | MEDIUM | **`DataTexture3D` configuration boilerplate restated 4×** | `engine/graphics/sh3/gi/material/makeLookupTexture3D.js:8`, `engine/graphics/sh3/lpg/light_probe_grid_textures.js:39` `make_light_probe_grid_luma_texture` and `:78` `make_light_probe_grid_chroma_texture`, `engine/graphics/render/forward_plus/LightManager.js:169` | MinHash sim 0.938 on the first three. Each restates the same 12-property incantation — `flipY=false`, `generateMipmaps=false`, `mag/minFilter`, `wrapS/T/R = ClampToEdgeWrapping`, `type`, `format`, `internalFormat`, `unpackAlignment = 4`, `needsUpdate = true` — differing only in filter mode and the type/format triple. House rule "confine vendor imports to boundaries": this is repeated three.js translation logic | UNJUSTIFIED | `engine/graphics/texture/make_data_texture_3d({data, width, height, depth, type, format, internal_format, filter, name})` — explicit typed parameters, no registry | Low effort / Low risk (`light_probe_grid_textures.spec.js` exists) |
-| 18 | MEDIUM | **Axis tick-label drawing duplicated, and the fix landed only in the copy** | `engine/graphics/canvas/canvas2d_draw_linear_scale.js:18` ⟷ `engine/animation/curve/editor/canvas2dDrawWorldAxisLabels.js:17` | MinHash sim 0.75. Lines 26-42 are byte-identical (spacing guard, delta/`v2_length`/zero guard, direction normalisation). `canvas2d_draw_linear_scale.js:44-46` uses `Math.floor` with a comment explaining that `ceil` *"would place a final tick past position_1 with an extrapolated value"*; `canvas2dDrawWorldAxisLabels.js:44` still uses `Math.ceil` — the documented defect is live in the copy | UNJUSTIFIED | `engine/graphics/canvas/canvas2d_draw_axis_ticks({ctx, position_x0..y1, spacing, label})` where `label(index, fraction)` returns the string. Both callers keep their own value/format policy; uniform control flow, no sentinel parameter | Low effort / Low risk |
-| 19 | MEDIUM | **Full-screen-quad `ShaderMaterial` option block restated 4× in one directory, with a typo divergence** | `engine/graphics/ecs/highlight/renderer/makeBlurShader_9.js:17-24`, `makeDilationShader.js:16-23`, `HighlightDecodeShader.js:57-63`, `OutlineRenderer.js:146-153` | The same 8 properties (`blending: NoBlending, lights: false, fog: false, depthTest: false, depthWrite: false, transparent: true, vertexColors: false, vertexShader: ScreenSpaceQuadShader.vertexShader()`). `makeBlurShader_9.js:18` writes **`light: false`** — three.js has no `light` property, so `Material.setValues` warns and the intended flag is never set. Classic copy-paste transcription error | UNJUSTIFIED | `engine/graphics/shaders/make_screen_space_quad_material({uniforms, fragmentShader})` beside `ScreenSpaceQuadShader.js`; the four call sites keep only their uniforms + fragment source | Low effort / Low risk |
-| 20 | MEDIUM | **Octahedral depth-probe ray kernel duplicated between the two bakers** | `engine/graphics/sh3/lpv/depth/octahedral/bake_octahedral_depth_map.js:95-133` ⟷ `bake_octahedral_depth_map_fibonacci.js:98-141` | ~40 lines byte-identical: `scene.trace` → `distance < 0 ? max_depth` → read `ray_hit[0..5]` → sink the contact along the hit normal by `NORMAL_BIAS` → `v3_distance` from the ray origin → `weight = pow(max2(0, dot(ray_dir, probe_dir)), DEPTH_SHARPNESS)`. The two sampling strategies (per-texel Hammersley jitter vs global Fibonacci splatting) genuinely differ; the shading kernel does not, and if the bias/weight law drifts the two bakers produce different depth for the same scene | UNJUSTIFIED | `trace_biased_depth_sample(scratch_ray, scene, max_depth, ray_direction, probe_direction) -> {distance, weight}` (or two out-params) in the same directory; both bakers call it inside their own sampling loop | Low effort / Low risk |
-| 21 | MEDIUM | **Per-entity event-rule subscription bookkeeping duplicated** | `engine/graphics/ecs/animation/AnimationControllerSystem.js:24` `registerRule` / `:64` `unlink` ⟷ `engine/sound/ecs/SoundControllerSystem.js:62` `registerRule` / `:103` `unlink` | `unlink` is byte-identical (9 lines). `registerRule`'s tail — `if (typeof r.stopEvent === "string") { addEntityEventListener(...); callbacks.push({name, handler}) }` then the same for `startEvent`, then `component.rules.forEach(registerRule)` — is identical modulo the parameter name. Only the two handler bodies (create an `AnimationClip` vs a `SoundTrack`) are subsystem-specific | UNJUSTIFIED | `engine/ecs/EntityEventRuleBinder` (typed class): `bind(dataset, entity, rules, {on_start, on_stop})` and `release(entity)`. Both systems keep only their handler bodies | Low effort / Low risk |
-| 22 | MEDIUM | **The impostor atlas uniform contract restated in 8 material classes** | `engine/graphics/impostors/octahedral/shader/ImpostorShaderV0.js:410`, `ImpostorShaderDepthV0.js:369`, `ImpostorShaderNormalsV0.js:356`, `ImpostorShaderViewportDepthV0.js:332`, `ImpostorShaderPerPixelV0.js:368`, `ImpostorShaderWireframeV0.js:162`, `ImpostorShaderStandard.js:256`, `ImpostorShaderV1.js:14` — all `constructor` | Token-identical constructor bodies at 117 tokens ×4 and 99 tokens ×3. Same `tBase / tGeometry / tMaterial / uFrames / uRadius / uOffset / uIsFullSphere / uDepthScale` set with the same JSDoc text, so an atlas format change (e.g. a fourth channel plane) must be made in eight places. This is not per-class `hash()`/`equals()` shape — it is one data contract restated | UNJUSTIFIED | `make_impostor_atlas_uniforms()` returning a fresh uniform object; each constructor spreads it and adds its own extras (`uParallaxStrength` etc.). Still typed and explicit — no string keys, no registry | Low effort / Low risk |
-| 23 | MEDIUM | **Diffuse-texture async binding duplicated between the two trail plugins, already diverged** | `engine/graphics/trail/tube/TubeXPlugin.js:48` `#build_material` (lines 57-77) ⟷ `engine/graphics/trail/x/RibbonXPlugin.js:96` `__build_material` (lines 110-130) | Identical: `if (typeof spec.diffuse === "string")` → `am.get({path, type: GameAssetType.Texture, callback: asset => { texture = asset.create(); texture.generateMipmaps = true; material.uniforms.uDiffuse.value = texture; }, failure: console.warn})` → `material.defines.USE_TEXTURE = true`. Tube adds `material.needsUpdate = true` (`:76`); Ribbon does not. Tube also routes through `getMaterialManager().obtain()` (`:84`, with a comment explaining Forward+ requires it); Ribbon returns the raw material (`:133`) | UNJUSTIFIED | `engine/graphics/material/bind_diffuse_texture_async(asset_manager, material, path)` handling the define + `needsUpdate`. The material-manager routing difference should be reconciled separately | Low effort / Low risk |
-| 24 | MEDIUM | **The four gi/lpg shader-builder glue functions and two transform-shader files are interchangeable** | `engine/graphics/sh3/gi/material/space_fragment/build_fragment_shader.js:40` and `build_vertex_shader.js:12`; `space_vertex/build_fragment_shader.js:19` and `build_vertex_shader.js:51`; the four identically-named `engine/graphics/sh3/lpg/material/...` counterparts; `gi/material/space_fragment/space_fragment_transform_shader.js:8` ⟷ `lpg/.../space_fragment_transform_shader.js:8`; `gi/.../space_vertex_transform_shader.js:8` ⟷ `lpg/.../space_vertex_transform_shader.js:8` | All eight builders are `result = PREAMBLE (+ PREAMBLE_COMMON) + source; result = insert_after(result, ANCHOR, CHUNK); return result;`. Both `*_transform_shader.js` pairs are 12-line files that are 90% line-identical. The anchors (`#include <lights_fragment_begin>`, `#include <fog_vertex>`) are the load-bearing part and appear in 4 separate string literals | PROMOTION | `engine/graphics/material/build_injected_shader(source, preamble, anchor, chunk)` in the material layer; the eight modules collapse to data (a preamble string, an anchor constant, a chunk string). Anchors become named constants in one place, matching the Forward+ marker contract | Low effort / Low risk (`LightProbeGridMaterialTransformer.spec.js` covers the LPG path) |
-| 25 | LOW | **`packDepthToRGBA` — a verbatim reimplementation of three.js's `<packing>` chunk — appears twice** | `engine/graphics/impostors/octahedral/shader/ImpostorShaderDepthV0.js:264-272` ⟷ `engine/graphics/impostors/voxel/shader/VoxelImpostorShaderDepthV0.js:55-63` | Identical `PackUpscale`/`PackFactors`/`ShiftRight8` constants and body. Both files are `RawShaderMaterial` so three's automatic chunk prefix does not apply — but `ShaderChunk.packing` is importable and splice-able. `VoxelImpostorShaderDepthV0.js:13` even says *"Mirrors three.js's packDepthToRGBA … identical encoding to ImpostorShaderDepthV0"*. If three changes the shadow-map depth encoding, both copies silently break | UNJUSTIFIED | Import `ShaderChunk.packing` from three at one boundary module (`engine/graphics/shaders/chunk_packing.js`) and interpolate it — house rule "confine vendor imports to boundaries" | Low effort / Low risk |
-| 26 | LOW | **Bake-camera frame reconstruction duplicated inside one file** | `engine/graphics/impostors/voxel/bake/read_atlas_to_samples.js:78-96` (`decode_normal_to_object_space`) ⟷ `:145-165` (`reconstruct_position`) | ~20 lines identical: the `abs(Dy) > 0.99999` polar nudge (`Dz + 0.0001`, renormalise), `right = normalize(cross((0,1,0), D))` written out as `(Dz, 0, -Dx)`, `up = cross(D, right)`. `:145` comments *"Same polar nudge as the normal decoder, so right/up agree"* — an explicit must-agree invariant left as two copies. Separately, the same frame concept appears 9× in GLSL as `up_OS`/`tangent_OS`/`binormal_OS` (`ImpostorShaderV0.js:245`, `DepthV0:197`, `NormalsV0:175`, `ViewportDepthV0:163`, `WireframeV0:135`, `PerPixelV0:142` and `:320`, `LitV0:191`) with a *different* degeneracy threshold (`0.999`) and a *different* fallback (swap the up vector rather than nudge Z) | UNJUSTIFIED | Extract a file-local `bake_frame_from_direction(out9, D_frame)` used by both functions in `read_atlas_to_samples.js`; fold the GLSL copies into finding #1's shared chunk | Low effort / Low risk |
-| 27 | LOW | **Two byte-size/component-count switch tables over the *same* enum** | `engine/graphics/particles/node-based/codegen/glsl/getTypeByteSize.js:8` ⟷ `engine/graphics/particles/node-based/particle/ParticleAttributeSpecification.js:23` `computeComponentCount` | Both switch on `ParticleDataTypes` over `Float/Vector2/Vector3/Vector4` and both throw on everything else; the first returns exactly 4× the second. The relationship is implicit — adding a non-4-byte component type makes them silently disagree. (`engine/graphics/particles/particular/group/itemSizeFromAttributeType.js:7` is a third table but over a different, older enum, so it is a separate concern) | UNJUSTIFIED | Keep `computeComponentCount` as the single table; `getTypeByteSize(type)` becomes `component_count(type) * BYTES_PER_COMPONENT`, or the byte width becomes a second explicit case list only if a type ever needs one | Low effort / Low risk |
-| 28 | LOW | **`TubeXFixedPhysicsSimulator` / `RibbonXFixedPhysicsSimulator`** | `engine/graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.js:18` `update` ⟷ `engine/graphics/trail/x/simulator/RibbonXFixedPhysicsSimulator.js:17` `update` | Token-identical (75 tokens ×2). 12-line loop: increment age, `clamp01(age/max_age)`, `setAlpha((1-relative_age)*alpha)`, write the flow UV. Only the method names differ (`incrementKnotAttribute_Scalar` vs `incrementPointAttribute_Scalar`, `setKnotAlpha` vs `setPointAlpha`) | UNJUSTIFIED (small) | Falls out of finding #5: unify `TubeX`'s `*Knot*` accessors with `RibbonX`'s `*Point*` names and keep one `TrailXFixedPhysicsSimulator`. Not worth an adapter interface on its own | Low effort / Low risk (`RibbonXFixedPhysicsSimulator.spec.js` exists) |
-| 29 | LOW | **`SimulationStep*` per-particle loop scaffolding ×4** | `engine/graphics/particles/particular/engine/simulator/SimulationStepApplyForce.js:7`, `SimulationStepCurlNoiseAcceleration.js:20`, `SimulationStepCurlNoiseVelocity.js:21`, `SimulationStepFixedPhysics.js:53` — all `execute` | The 12-line preamble + layer-mask gate (`readAttributeScalar(i, PARTICLE_ATTRIBUTE_LAYER_POSITION)`, `if ((layerMask & (1 << layer_position)) === 0) continue;`, `params = layer_parameters[layer_position]`) is identical in all four. The Acceleration/Velocity pair additionally share the 6-line `power_*`/`scale_*` unpack and the `noise[k] * power_k` application | **JUSTIFIED (hot loop)** for the scaffolding — this is a genuine per-particle JS inner loop; hoisting the body into a callback would make the call site megamorphic across four step types and defeat the reason the mask test is inlined. The `power/scale` unpack shared by the two curl-noise steps is *marginal* — a shared `CurlNoiseStepBase` holding the six-parameter unpack would remove it without adding a per-particle indirection | If touched at all: `AbstractCurlNoiseSimulationStep` holding `parameter_schema` and a `#unpack(params)`; leave the loops inline | Low effort / Low risk — but measure first; not worth doing blind |
-
-### The headline lead, quantified: `sh3/gi` + `sh3/lpv` vs `sh3/lpg`
-
-I measured verbatim line overlap for every corresponding file pair (non-empty, whitespace-normalised):
-
-| lpg file | lpg lines | gi/lpv lines | verbatim-shared | % of lpg |
-|---|---|---|---|---|
-| `lpg/material/LightProbeGridMaterialTransformer.js` | 187 | 256 | 104 | 56% |
-| `lpg/material/space_fragment/build_fragment_shader.js` | 30 | 32 | 24 | 80% |
-| `lpg/material/space_fragment/build_vertex_shader.js` | 38 | 22 | 19 | 50% |
-| `lpg/material/space_vertex/build_fragment_shader.js` | 22 | 21 | 19 | 86% |
-| `lpg/material/space_vertex/build_vertex_shader.js` | 33 | 48 | 20 | 61% |
-| `lpg/material/space_fragment/space_fragment_transform_shader.js` | 10 | 10 | 9 | 90% |
-| `lpg/material/space_vertex/space_vertex_transform_shader.js` | 10 | 10 | 9 | 90% |
-| `lpg/light_probe_grid_textures.js` | 126 | 28 | 20 | 16% |
-| `lpg/light_probe_grid_obtain_storage_cached.js` | 61 | 63 | 40 | 66% |
-| `lpg/build_light_probe_grid_for_scene.js` | 66 | 103 | 43 | 65% |
-| `lpg/material/common.js` | 55 | 426 | 10 | 18% |
-| `lpg/material/chunk_lpg_get_irradiance_at.js` | 18 | 21 | 9 | 50% |
-| **total** | **656** | **1040** | **326** | **50%** |
-
-**Verdict: the fork is roughly 250 deduplicable lines out of ~1700; the rest is genuinely different and
-should stay separate.** Concretely:
-
-- **Mechanically copied (findings #3, #7, #13, #14, #17, #24)**: the transformer skeleton (marker guard,
-  `#onBeforeCompile` stage dispatch, `intensity` accessor, `#uniform_version` gate) ~70 lines ×2 (plus a
-  third copy in `render/forward_plus`); the six shader-builder glue functions ~60 lines; the two
-  `*_transform_shader.js` files ~24 lines; the storage-cached scene-bounds + load/build/store protocol
-  ~45 lines ×2; the bake-via-task overlay ~25 lines ×2; the `DataTexture3D` incantation ~25 lines ×3.
-- **Genuinely different, leave alone**: `gi/material/common.js`'s 426 lines are the tetrahedral walk
-  (`lpv_walk_to_tetrahedron`, `lpv_guess_initial_tet`, barycentric masking, octahedral depth visibility) —
-  the LPG replaces all of it with a 3-line 3D-texture fetch. `lpg/light_probe_grid_textures.js`'s YCoCg
-  half-float/8-bit split encoding has no LPV counterpart. The SH truncation (L2→L1) is a real design
-  difference. `ProbeResolutionStage` is *already* correctly shared (`lpg/material/LightProbeGridMaterialTransformer.js:6`
-  imports it from `gi/material/`), which shows the seam is reachable.
-- **Where the seam belongs**: one `AbstractProbeFieldMaterialTransformer` in
-  `engine/graphics/material/manager/` owning the marker/clone/compose/stage-dispatch, plus the four
-  small promotions in findings #13/#14/#17/#24. Nothing about the tetrahedral-vs-grid lookup needs to
-  be unified.
-
-## Dismissed leads
-
-- `TubeX.js` (557 ln) vs `RibbonX.js` (578 ln) — genuine rewrite, not a copy: `#private` fields, ring topology with a duplicated seam vertex, `v3_orthonormal_matrix_from_normal`, documented throughout. Only the accessor naming (`Knot` vs `Point`) is gratuitously divergent.
-- `particles/node-based/` vs `particles/particular/` — **not a fork**. `node-based` is a GLSL-codegen design with zero importers outside its own tree; `particular` is the live CPU simulator. The two `ParticleSpecification` classes (`node-based/particle/ParticleSpecification.js` vs `particular/group/ParticleSpecification.js`) share only a name — different fields, different purpose. The `particular` one is already marked `@deprecated use AttributeGroupSpec`. This is an unfinished parallel system plus an export-name collision, not duplication.
-- `particles/node-based/nodes/math/Vector3{Add,Divide,Multiply,Subtract}.js` (13 lines each, 79-84% file similarity) — per-node typed classes; house rule explicitly prefers this over a string-keyed operator registry.
-- `AnimationGraph.getStateByDefinition` / `getTransitionByDefinition` / `TextureAtlas.getPatch` / `StaticKnowledgeDatabase.getDescriptorById` — generic "linear scan a small array by field equality"; too small and too type-specific to share.
-- `AnimationGraph.equals` / `AnimationTransitionDefinition.equals` / `AnimationState.equals` — per-class `equals()`; deliberate per house rules.
-- `AttributeGroupSpec.getAttributeByName` / `ParticleSpecification.getByName` / `ParameterTrackSet.getTrackByName` — same 8-line linear scan, but over three unrelated element types in three unrelated collections, and `ParticleSpecification` is deprecated. Not worth a generic.
-- `SGMeshHighlightSystem.js` — despite the name, a different system (propagates highlight down an SGMesh hierarchy), not a fourth copy of finding #8.
-- `engine/graphics/ecs/water` vs `water2` — `water2` contains only a shader plus a browser harness; no forked logic.
-- The "read indices a/b/c then fetch 9 floats at `*3`" block (8+ sites incl. `computeMeshSurfaceArea.js:20`, `tri3_ray_intersection_indexed.js`, `construct_ray_hit_from_geometry.js`) — all inner-loop; a shared reader would need nine out-params or an out-array, which costs more than it saves. `geometry_construct_triangle_normal.js:12` already exists for the one case where the payload justifies it.
-- `setFlag`/`clearFlag`/`writeFlag`/`getFlag` across 30 files (brief §E) — engine-wide component convention, not a domain issue.
-- `inline_lerp` / `inline_length3` hits in `lightmap_seam_fix.js`, `read_atlas_to_samples.js`, `voxelize_samples.js` — per-texel/per-sample loops; inlining is the right call.
-- **Browser harnesses (out of scope, one note as instructed)**: `makeConfig`, `configuration`, `init`, `debug_button`, `catmullRom`, `sample_style_entity` and `makeMovingShadedGeometry` are copy-pasted across at least 12 harnesses — `testPathDisplaySystem.js`, `prototypeAnimatedPathMask.js`, `testShadowMapRendering.js`, `testPointShadowMapRendering.js`, `prototypeBaker.js`, `prototype_voxel_impostors.js`, `prototypeLightProbeGrid.js`, `prototypeSH3Probe.js`, `prototypeShadedGeometry.js`, `prototype_sg_raycast.js`, `prototypeHiZ.js`, `prototypeNormalFrameBuffer.js`, `prototypeParticleVolume.js`, `testClippingPlaneComputation.js`, `testWaterShader.js`, `ptototypeFPPlugin.js`, `prototypeDecalEditor.js`, `prototypeDecalSystem.js`. A shared internal `engine/graphics/harness/` module (engine bootstrap + dat.GUI config + debug button + a spline sampler) would remove several hundred lines. Not counted as a finding.
-
-## Notes
-
-Three structural forces produce nearly all the duplication in this domain.
-
-**1. "V2 by copy".** Every second-generation subsystem here was started by duplicating the first and
-editing: `trail3d` from `trail2d`, `lpg` from `lpv`/`gi`, `mesh-v2` from `mesh`, `water2` from `water`,
-`decal/v2`. That is a defensible way to start, but nothing was ever pulled back afterwards, so the
-newer copy accumulates fixes the older one never receives. Findings #3, #4 and #18 are all the same
-failure mode with the same signature: **the newer file carries a comment explaining a bug, and the
-older file still has that bug.** `Trail3DSystem.js:31-45` documents the head-position mismatch that
-`Trail2DSystem.js:157` still exhibits; `canvas2d_draw_linear_scale.js:44` documents the `ceil`
-over-extrapolation that `canvas2dDrawWorldAxisLabels.js:44` still exhibits; `MaterialTransformer.js:107`
-clones the material where `sh3/gi/material/MaterialTransformer.js:311` throws the clone away. When
-auditing this codebase, an explanatory comment in one of a pair is a reliable index into a live defect
-in the other.
-
-**2. No shader-chunk mechanism.** GLSL lives in template literals inside `.js` files, and the codebase
-has no include mechanism for it (three's `ShaderChunk` is used only through three's own automatic
-prefix, which `RawShaderMaterial` skips). The result: every shader that needs octahedral mapping,
-depth packing, or SH evaluation gets its own transcription. The webpack raw-loader path already exists
-(`ImpostorShaderV1.js:10-11` imports `./glsl/v1/vertex.glsl`), and the `sh3/gi` side already
-demonstrates the string-export pattern (`chunk_lpv_get_irradiance_at.js`, `common.js` as a default
-string export) — the tooling is there, it just wasn't applied to the impostor family.
-
-**3. `System` boilerplate has no base.** `System` is a bare interface, so every renderable system
-re-implements the same three chores: create a render layer, wire `buildVisibleSet` + `compute_depth_range`
-to a BVH, acquire/release a plugin `Reference` in `startup`/`shutdown`. `make_bvh_visibility_builder`
-shows someone already noticed half of it. Findings #8 and #16 are the tail of that.
-
-### GLSL duplication
-
-This is where the mechanical pass is blind, and it is by far the largest volume of duplication in the
-domain. Token-based clone detection sees a shader as one string literal, so none of the following
-appeared in the brief:
-
-- **`VecToSphereOct` is declared 17 times** across `.js` template literals and `.glsl` files, in **four
-  mutually incompatible conventions**: the impostor family folds on `octahedron.y < 0` and returns
-  `.xz` using `sign()` (9 copies); `sh3/gi/material/common.js:118` uses an `l1norm` formulation, folds
-  on `v.y < 0`, returns `v.xz`; `sh3/lpv/depth/octahedral/{shader,stitching,v2}` folds on
-  `direction.z < 0` and returns `.xy` using `sign_not_zero` (4 copies); `impostors/octahedral/shader/glsl/common.glsl:57`
-  and `glsl/v1/*` are HLSL-derived and use `frac`/`saturate`/`tex2Dgrad` (3 copies). Meanwhile
-  `core/geom/3d/octahedra/octahedral_direction_to_uv.js` is the *single* JS implementation and is the
-  one the bake path uses. A shader author reading `VecToSphereOct` in this repo cannot tell which
-  mapping they will get.
-- **The whole octahedral-impostor sampling library (~90 lines)** appears 9 times (finding #1),
-  including twice within `ImpostorShaderPerPixelV0.js` and twice within `ImpostorShaderLitV0.js`
-  because each embeds it in both the vertex and the fragment stage.
-- **The probe-depth library (~220 lines)** is copied from production into a debug visualiser
-  (finding #2), typo included.
-- **The billboard card frame** (`up_OS` pole fallback → `tangent_OS = normalize(cross(up_OS, normal_OS))`
-  → `binormal_OS = cross(normal_OS, tangent_OS)`) appears 9 times in the octahedral shaders, and a
-  differently-thresholded CPU cousin appears twice in `read_atlas_to_samples.js` (finding #26).
-- **The voxel splat expansion** appears 5 times (finding #6), carrying an invariant its own comments
-  say must be kept in sync by hand.
-- **`packDepthToRGBA`** — three.js's own `<packing>` chunk — is retyped twice (finding #25).
-- **The SH cosine-lobe evaluator** appears 3 times in GLSL with two different sign conventions
-  (finding #7).
-- Smaller repeats not worth individual findings: `vec3 inverseTransformDirection(...)` retyped in
-  `sh3/shader/visualize.frag.js:5`, `sh3/lpv/depth/octahedral/shader/visualize.frag.glsl:1` and
-  `.../v2/visualise.frag.glsl:1` (three.js provides it in the standard prefix, but these are
-  `RawShaderMaterial`); the `#ifdef USE_TEXTURE { texel = texture2D(uDiffuse, vUv); diffuseColor *= texel; }`
-  block in `RibbonMaterialX.js:95` and `TubeMaterialX.js:99`; `sign_not_zero` with three overloads in
-  `gi/material/common.js:76-93` and `v2/visualise.frag.glsl:26-43`.
-
-The single highest-leverage change in this domain is not any individual extraction — it is establishing
-one GLSL chunk directory (`engine/graphics/shaders/chunks/`) with the octahedral, SH, packing and
-frame-construction primitives as named string exports, and then deleting the transcriptions. That one
-move retires findings #1, #2, #6, #7, #25 and #26 and removes roughly 1,400 lines of copied shader
-source.
+# Domain D — engine/graphics feature subsystems (ecs, particles, trail, impostors, sh3, shadows)
+
+Source root for all paths: `H:/git/moh/app/src/mir-engine/meep/src/`
+
+Every finding below was verified by opening the cited files. Line numbers are from the working tree
+at the time of the audit.
+
+## Findings
+
+| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
+|---|---|---|---|---|---|---|---|
+| 1 | CRITICAL | **Octahedral impostor GLSL library copy-pasted 9× inside the domain, plus 3 more name-colliding variants.** `VecToSphereOct` / `VecToHemiSphereOct` / `VectorToGrid` / `OctaSphereDec` / `OctaHemiSphereDec` / `GridToVector` / `FrameToRay` / `ComputeFrameXform` / `BilinearWeights` / `apply_frame_xform` — ~90 lines of GLSL | `engine/graphics/impostors/octahedral/shader/ImpostorShaderV0.js:71`, `ImpostorShaderDepthV0.js:59`, `ImpostorShaderNormalsV0.js:52`, `ImpostorShaderViewportDepthV0.js:46`, `ImpostorShaderWireframeV0.js:31`, `ImpostorShaderPerPixelV0.js:39` **and** `:178` (both stages), `ImpostorShaderLitV0.js:65` **and** `:328` (both stages). Incompatible same-named variants: `shader/glsl/common.glsl:25,57`, `shader/glsl/v1/common.glsl:1,45`, `shader/glsl/v1/vertex.glsl:42,86` | 9 byte-identical copies (verified with `awk` extraction — all identical). Whole-file line overlap against `ImpostorShaderV0.js`: Depth 70%, PerPixel 85%, Wireframe 86%, ViewportDepth 65%, Normals 61%. **Drift already present**: all 9 GPU copies use `sign(v)` where the CPU reference `core/geom/3d/octahedra/octahedral_direction_to_uv.js:25` deliberately uses `sign_not_zero()` — `sign(0.0)==0.0` shrinks the L1 norm and mis-folds a direction with an exactly-zero component. The bake side (`impostors/octahedral/grid/OctahedralUvEncoder.js:7`) and the sample side must agree; they are two independent transcriptions of one invariant. `glsl/common.glsl` declares `VecToSphereOct`/`GridToVector`/`VectorToGrid` with *different* semantics (y-fold via `_ImposterFullSphere`, HLSL intrinsics `frac`/`saturate`/`tex2Dgrad`) | UNJUSTIFIED | One `engine/graphics/impostors/octahedral/shader/chunk_octahedral.js` exporting a GLSL string (or a `.glsl` file — precedent exists, `ImpostorShaderV1.js:10` already imports `./glsl/v1/vertex.glsl` through the raw loader), interpolated into every shader. Delete `glsl/common.glsl`'s colliding declarations or rename them | Medium effort / Low risk — string extraction, shaders compile-checked by the existing prototype harness |
+| 2 | CRITICAL | **The production GI probe-depth GLSL library is copy-pasted into two debug visualisers.** `sign_not_zero` (3 overloads), `quadBlendWieghts`, `VecToSphereOct`, `SampleBlended`, `lpv_probe_getDepth{,Bilinear,Triangular}`, `lpv_bilinear_lerp` (2 overloads), `lpv_sample_bilinear`, `wrapOctahedralTexelCoordinates`, `lpv_probe_getPosition` | `engine/graphics/sh3/gi/material/common.js:76-298` (production) ⟷ `engine/graphics/sh3/lpv/depth/octahedral/v2/visualise.frag.glsl:26-408` ⟷ `engine/graphics/sh3/lpv/depth/octahedral/shader/visualize.frag.glsl:1-97` | Measured line-level overlap: **220 of 320** non-empty lines of `v2/visualise.frag.glsl` (68.8%) appear verbatim in `gi/material/common.js`; 51 of 97 (52.6%) for `shader/visualize.frag.glsl`. Smoking gun: the misspelling `quadBlendWieghts` is present in both (`common.js:95`, `v2/visualise.frag.glsl:45`). The whole point of the visualiser is to show what the production sampler sees — a forked copy can silently show something else | UNJUSTIFIED | Extract `engine/graphics/sh3/lpv/depth/chunk_probe_depth.js` (GLSL string) consumed by `gi/material/common.js` and by both visualiser shaders. Note `VecToSphereOct` here folds on `v.y<0` returning `.xz` while `lpv/depth/.../shader/visualize.frag.glsl:29` folds on `direction.z<0` returning `.xy` — reconcile before extracting | Medium effort / Medium risk — the two visualisers may currently rely on their divergent fold |
+| 3 | HIGH | **`AbstractMaterialTransformer.transform()` marker-guard / clone / compose protocol copied 3×, already diverged** | `engine/graphics/render/forward_plus/plugin/MaterialTransformer.js:91` `transform`; `engine/graphics/sh3/gi/material/MaterialTransformer.js:294` `transform`; `engine/graphics/sh3/lpg/material/LightProbeGridMaterialTransformer.js:207` `transform` | The 11-line "already transformed / different instance → throw" guard is byte-identical in all three. The clone step is not: FP does `result = source.clone()` (`:107`), gi does **`result.clone();`** (`MaterialTransformer.js:311`) — a discarded expression statement, so gi mutates the caller's material in place; lpg dropped the clone entirely (`:219-223`). `AbstractMaterialTransformer` (`engine/graphics/material/manager/AbstractMaterialTransformer.js:1`) is an empty 10-line stub that owns none of this. `#onBeforeCompile` is also identical between gi (`:133`) and lpg (`:77`) — same `switch(ProbeResolutionStage)` dispatch, 14 lines | UNJUSTIFIED | Move the guard + clone + `composeCompile` wiring into `AbstractMaterialTransformer` as a concrete `transform(source)` calling an abstract `_install(material)`; subclasses supply only the marker symbol and the compile hook. Typed inheritance, no registry | Low effort / Medium risk — fixing gi's dropped clone changes behaviour (correctly) |
+| 4 | HIGH | **`Trail3DSystem` is a whole-file fork of `Trail2DSystem`, and the fork's bug fix never went back** | `engine/graphics/ecs/trail2d/Trail2DSystem.js` (274 lines) ⟷ `engine/graphics/ecs/trail3d/Trail3DSystem.js` (280 lines). Method pairs: `constructor` `:66`/`:90`, `startup` `:96`/`:110`, `__build_trail`/`#build_trail` `:129`/`:141`, `link` `:191`/`:200`, `unlink` `:210`/`:221`, `updateTrailEntity` `:224`/`:233`, `update` `:260`/`:266` | Every method is identical modulo `ribbon`↔`tube`, `Point`↔`Knot`, plugin class and layer name. **Divergence with consequences**: `Trail3DSystem.js:47` extracts `compute_head_position(result, trail, transform)` = `offset.applyMatrix4(transform.matrix)` and its 15-line comment states build-time seeding and the per-frame head update *must* agree or "the head's first move draws a segment bridging the two — a one-frame streak". `Trail2DSystem.js:157-159` still seeds with `trail_offset.x + transform_position.x` (translation only) while `Trail2DSystem.js:235-236` updates the head with `applyMatrix4` — under any rotation or scale the two disagree, which is exactly the documented defect | UNJUSTIFIED | The two ribbon/tube backends genuinely differ, but the *system* does not. Extract the shared body into `TrailSystemBase` (typed abstract class holding bvh/renderLayer/plugin-ref lifecycle + `updateTrailEntity`) with abstract `#seed_geometry` / `#obtain_plugin`. At minimum promote `compute_head_position` into `engine/graphics/trail/` and call it from both build paths | Medium effort / Medium risk — Trail2D seeding change is a behaviour fix, covered by `Trail2DSystem.spec.js` |
+| 5 | HIGH | **Trail spawn/aging state machine duplicated** — reseed-on-clear, `refitTimeDelta = maxAge/count`, head-moved detection, distance accumulation, `TrailSpawnMode.Distance ? distance>=spawnDistance : time>=refitTimeDelta`, rotate, head age/alpha/thickness write | `engine/graphics/ecs/trail2d/Trail2D.js:298` `updateHead` ⟷ `engine/graphics/ecs/trail3d/Trail3D.js:417` `updateHead`; also `Trail2D.js:210` `clear` ⟷ `Trail3D.js:275` `clear` | MinHash sim 0.766 on 309/322 tokens; reading them confirms the *policy* is line-for-line the same (~45 lines), differing only by accessor names and 3D's extra `#updateHeadFrame` call. The alpha fade law `(1 - clamp01(head_age/maxAge)) * this.color.w` is restated in both and must match the simulators (`TubeXFixedPhysicsSimulator.js:28`, `RibbonXFixedPhysicsSimulator.js:27`) — 4 copies of one law | UNJUSTIFIED | Extract `trail_update_head(trail, buffer_adapter, x, y, z, head_age)` in `engine/graphics/trail/`, where the adapter is a small typed interface (`getCount/getHeadIndex/getPosition/setPosition/rotate/setAge/setAlpha/setThickness`). Simplest alternative: rename `TubeX`'s `*Knot*` methods to `*Point*` so one function serves both | Medium effort / Medium risk — per-frame code, but not per-particle; specs exist for both components |
+| 6 | HIGH | **Voxel-impostor splat expansion GLSL copied 5×, carrying a stated cross-shader invariant** | `engine/graphics/impostors/voxel/shader/VoxelImpostorShaderV0.js:45-61`, `VoxelImpostorShaderNormalsV0.js:24-31`, `VoxelImpostorShaderDepthV0.js:31-41`, `VoxelImpostorShaderViewportDepthV0.js:22-30`, `VoxelImpostorShaderLitV0.js:57-68` | The block (`model_scale = length(modelMatrix[0].xyz)` → `radius_OS` → `centre_OS = iPosition - iNormal * radius_OS` → view-space corner offset) is identical in all five. `VoxelImpostorShaderDepthV0.js:35-37` states: *"Inward-shift must match the colour pass exactly so the cast silhouette agrees with the visible one"* — the invariant is documented but not enforced, because it lives in five separate string literals | UNJUSTIFIED | `engine/graphics/impostors/voxel/shader/chunk_voxel_splat_vertex.js` exporting the shared vertex body; the five materials interpolate it and add only their own varyings | Low effort / Low risk |
+| 7 | HIGH | **Spherical-harmonic cosine-lobe irradiance evaluator implemented 4× and the copies disagree on sign convention** | `core/geom/3d/sphere/harmonics/sh3_sample_irradiance_by_direction.js:36-48` (JS); `engine/graphics/sh3/shader/visualize.frag.js:11` `shGetIrradianceAt` (GLSL); `engine/graphics/sh3/gi/material/chunk_lpv_get_irradiance_at.js:5` `lpv_get_irradiance_at` (GLSL); `engine/graphics/sh3/lpg/material/chunk_lpg_get_irradiance_at.js:9` `lpg_get_irradiance_at` (GLSL, first two bands only) | Same magic constants (`0.8862269254527579`, `1.0233267079464885`, `0.8580855308097834`, `0.4290427654048917`, `0.7431238683011272`) in all four. Signs differ: the core JS and `visualize.frag.js` negate coefficients 1, 3, 5, 7 (three.js convention); the two chunk files use `+=` throughout. `lpg/material/chunk_lpg_get_irradiance_at.js:3` even documents itself as *"first two bands of chunk_lpv_get_irradiance_at"* — an acknowledged copy. (The sign divergence is already logged in `src/REVIEW_2026_08_06/adv-gfx.md:359`; cited here only as proof the duplication produced a real defect) | UNJUSTIFIED | One `engine/graphics/sh3/chunk_sh_irradiance.js` GLSL module exporting an L2 evaluator plus a truncated L1 evaluator over `vec3[4]`, next to the single JS `sh3_sample_irradiance_by_direction`. Pin one sign convention and state it in a comment at both | Low effort / High risk — changing signs changes rendered output; needs a bake-vs-shader A/B first |
+| 8 | MEDIUM | **Three highlight systems are the same `System` + `Supplier` scaffold with a 15-line hole** | `engine/graphics/ecs/highlight/system/MeshHighlightSystem.js` (162 ln), `RenderableHighlightSystem.js` (164 ln), `ShadedGeometryHighlightSystem.js` (175 ln). Duplicated members: `class Supplier` `:9`/`:9`/`:8`, `collect` `:33`/`:38`/`:44`, `shutdown` `:121`/`:125`/`:137`, `startup` `:137`/`:143`/`:154`, and the whole `constructor` | `diff -u` between Renderable and ShadedGeometry shows the *only* semantic differences are the traversal component pair and how the three.js object is obtained; between Mesh and Renderable, only the visibility-flag check and the object accessor. ~130 of ~165 lines are common to all three | UNJUSTIFIED | Abstract `HighlightSystemBase extends System` owning the `OutlineRenderPlugin` reference lifecycle and the `Supplier` (which delegates to an abstract `visit(highlight, component, entity)`); three thin typed subclasses. Plain inheritance — no registry, no strings | Low effort / Low risk (`ShadedGeometryHighlightSystem.spec.js` exists) |
+| 9 | MEDIUM | **Neighbour-average flood-fill ("dilate") written twice — 2D lightmap and 3D probe grid** | `engine/graphics/sh3/lightmap/lightmap_dilate.js:18` `lightmap_dilate` (4-connected, `channels` values/texel) ⟷ `engine/graphics/sh3/lpg/light_probe_grid_dilate.js:29` `light_probe_grid_dilate` (6-connected, 12 values/probe) | Identical algorithm: skip covered cells; accumulate valid neighbours into a `Float64Array` accumulator; if `n===0` continue; write `acc[c]/n`; mark newly covered; repeat. Even the guard shape (`x > 0 && coverage[index-1] !== 0`) matches per-axis. Only the pass-snapshot mechanism differs (`newly[]` array vs `__source_validity` copy) and the termination (iteration cap vs run-to-convergence). Invisible to the mechanical pass — different identifiers and one extra loop level put it under the MinHash threshold | UNJUSTIFIED | One `core/collection/grid/grid_dilate_average(data, coverage, size_x, size_y, size_z, channels, iterations)`; the lightmap call passes `size_z = 1`. Note `lightmap_dilate.js:24` allocates `newly` per iteration — folding into the LPG's snapshot form removes that too | Medium effort / Low risk — both have specs (`lightmap_dilate.spec.js`, `light_probe_grid_dilate.spec.js`) |
+| 10 | MEDIUM | **Area-weighted triangle surface sampling copy-pasted instead of reusing the function next door** | `engine/graphics/particles/particular/engine/utils/distributeParticlesOnObject3D.js:169-233` ⟷ `engine/graphics/particles/particular/engine/utils/distrubuteParticlesOnMesh.js:112-187` `distributePointsOnMesh` | ~65 lines verbatim: same `poly:` label, same `roundFair(placementCount, random)`, same index/vertex fetch, same barycentric picking including the identical source-URL comment (`https://math.stackexchange.com/questions/538458/...`) and the same `r1 = random() * (1 - r0)` sampling. `distributePointsOnMesh` is already the generic, callback-driven form and is exported — `distributeParticlesOnObject3D` just doesn't call it. There is no other area-weighted triangle sampler in the codebase (grep for the URL and for `random point on the triangle` returns exactly these two files) | UNJUSTIFIED | Split `distributePointsOnMesh` into `distribute_points_on_indexed_triangles(count, points, indices, polygon_count, transform, seed, callback)` plus the two thin `Mesh` / `Object3D` front-ends. `distributeParticlesOnObject3D`'s `visitObject` (`:20`) already flattens the hierarchy into `buffer_points`/`buffer_indices` — it only needs to hand those to the shared loop | Low effort / Low risk |
+| 11 | MEDIUM | **Two-record swap across an array of `BufferAttribute`s written twice** | `engine/graphics/particles/particular/engine/emitter/ParticlePool.js:202` `swap` ⟷ `engine/graphics/particles/particular/group/ParticleGroup.js:550` `swapAttributeValues` | MinHash sim 0.953. 25 lines, identical down to `const offsetA = indexA * itemSize`; only the temp variable name (`temp` vs `elementA`) and a trailing `attribute.needsUpdate = true` differ. Both operate on the same shape (array of three.js `BufferAttribute`) | UNJUSTIFIED | `engine/graphics/geometry/buffer_attributes_swap_records(attributes, index_a, index_b)` in `engine/graphics/geometry/`; both call it, `ParticleGroup` sets `needsUpdate` itself afterwards | Low effort / Low risk |
+| 12 | MEDIUM | **Nearest-point-on-triangle leaf handler duplicated across the two BVH nearest queries** | `engine/graphics/geometry/buffered/query/query_bvh_geometry_nearest.js:164-203` ⟷ `engine/graphics/geometry/buffered/query/bvh32_geometry_nearest.js:203-242` | The traversal halves legitimately differ (pointer-based `BVH` vs implicit-index `BinaryUint32BVH`), but the leaf halves are byte-identical for 40 lines: `tri3_closest_point_barycentric` → `w = 1-u-v` → `contact = a*u + b*v + c*w` → `v3_distance_sqr` → early-out → `result.position.set` → `tri3_compute_normal` → `result.index`. The barycentric-reconstruction convention (which of u/v/w pairs with which vertex) is the subtle part and it is stated twice | UNJUSTIFIED | Extract `tri3_nearest_accept(result, x, y, z, ax..cz, triangle_index, best_distance_sqr) -> number` (returns the new best, or the old one). Both queries call it from their leaf branch. Function-call overhead in the leaf is negligible next to the barycentric solve | Low effort / Low risk (both have specs) |
+| 13 | MEDIUM | **`load-from-storage-else-build-and-cache` + scene-bounds traversal duplicated between LPG and LPV** | `engine/graphics/sh3/lpg/light_probe_grid_obtain_storage_cached.js:18` ⟷ `engine/graphics/sh3/lpv/lpv_obtain_storage_cached_volume.js:18` | MinHash sim 0.953, 198/200 tokens. Lines 44-65 vs 46-67 are byte-identical: build an `AABB3`, `setNegativelyInfiniteBounds()`, `ecd.traverseEntities([ShadedGeometry, Transform], ...)`, allocate a fresh `AABB3` **inside the visitor** (a per-entity allocation, duplicated), `mesh_bounds.union(box)`. The un-awaited `engine.storage.promiseStoreBinary(key, buffer.data)` with no error path is also duplicated (`:81` / `:83`) | UNJUSTIFIED | Promote `scene_compute_shaded_geometry_bounds(out_aabb3, ecd)` into `engine/graphics/ecs/mesh-v2/` next to the existing `sg_hierarchy_compute_bounding_box_via_parent_entity.js:28`, using a module-static scratch box. The load/build/store protocol can stay per-subsystem (the adapter types are genuinely different) | Low effort / Low risk |
+| 14 | MEDIUM | **Bake-task-with-progress-overlay scaffold duplicated** | `engine/graphics/sh3/lpg/build_light_probe_grid_for_scene.js:18` `light_probe_grid_bake_via_task` ⟷ `engine/graphics/sh3/lpv/build_probes_for_scene.js:20` `lpv_volume_bake_via_task` | MinHash sim 0.922. ~25 lines identical: `makeSimpleTaskProgressView({task, localization, size: new Vector2(512,64)})`, a throwaway `Entity` with `GUIElement.fromView` + `ViewportPosition.fromJSON({position:(0,1), anchor:(0,1), offset:(16,-16)})`, `task.promise().finally(() => progress_entity.destroy())`, `engine.executor.runGroup(task)`, `await task.promise()`. Only the baker class differs. `makeSimpleTaskProgressView` has exactly two non-prototype callers — both of these | PROMOTION | `engine/run_task_with_progress_overlay(task, engine, ecd)` beside `engine/makeSimpleTaskProgressView.js`. Both bakers call it | Low effort / Low risk |
+| 15 | MEDIUM | **Camera depth-plane construction + render-layer depth-range accumulation duplicated** | `engine/graphics/ecs/camera/auto_set_camera_clipping_planes.js:60-84` ⟷ `engine/graphics/ecs/light/shadow/extend_shadow_camera_near_for_casters.js:69-90` | Two verbatim blocks. (a) The three.js matrix convention `nx=-m[8], ny=-m[9], nz=-m[10]`, `plane_constant = -(nx*m[12]+ny*m[13]+nz*m[14])` — a vendor-layout invariant restated twice. (b) `scratch_range.near = +Infinity; far = -Infinity;` then `layers.traverse(layer => { if(!layer.state.visible) return; const compute = layer.compute_depth_range; if (compute === null) return; compute(...) })` — identical including the null guard and the sentinel initialisation | PROMOTION | `engine/graphics/render/layers/render_layers_compute_depth_range(out_range, layers, planes, matrix_world_elements)` doing both halves. Both callers shrink to a call plus their own clamping policy | Low effort / Low risk (`auto_set_camera_clipping_planes.spec.js` exists) |
+| 16 | MEDIUM | **`compute_depth_range` BVH closure written 7× verbatim** | `engine/graphics/ecs/trail2d/Trail2DSystem.js:110`, `engine/graphics/ecs/trail3d/Trail3DSystem.js:124`, `engine/graphics/ecs/mesh/MeshSystem.js:162`, `engine/graphics/ecs/mesh-v2/ShadedGeometrySystem.js:269`, `engine/graphics/ecs/water/WaterSystem.js:110`, `engine/graphics/particles/ecs/ParticleEmitterSystem.js:104`, `engine/ecs/renderable/RenderSystem.js:74` | All seven are `const bvh = <this bvh>; layer.compute_depth_range = (result, frustum, nx, ny, nz, c) => { bvh_query_depth_range_in_frustum(result, bvh, frustum, nx, ny, nz, c); };`. The sibling helper `make_bvh_visibility_builder` already exists in `engine/graphics/render/` and is used by six of these — the depth-range half was never given the same treatment | PROMOTION | `engine/graphics/render/make_bvh_depth_range_computer(bvh)` next to `make_bvh_visibility_builder.js`; all seven become one-liners | Low effort / Low risk |
+| 17 | MEDIUM | **`DataTexture3D` configuration boilerplate restated 4×** | `engine/graphics/sh3/gi/material/makeLookupTexture3D.js:8`, `engine/graphics/sh3/lpg/light_probe_grid_textures.js:39` `make_light_probe_grid_luma_texture` and `:78` `make_light_probe_grid_chroma_texture`, `engine/graphics/render/forward_plus/LightManager.js:169` | MinHash sim 0.938 on the first three. Each restates the same 12-property incantation — `flipY=false`, `generateMipmaps=false`, `mag/minFilter`, `wrapS/T/R = ClampToEdgeWrapping`, `type`, `format`, `internalFormat`, `unpackAlignment = 4`, `needsUpdate = true` — differing only in filter mode and the type/format triple. House rule "confine vendor imports to boundaries": this is repeated three.js translation logic | UNJUSTIFIED | `engine/graphics/texture/make_data_texture_3d({data, width, height, depth, type, format, internal_format, filter, name})` — explicit typed parameters, no registry | Low effort / Low risk (`light_probe_grid_textures.spec.js` exists) |
+| 18 | MEDIUM | **Axis tick-label drawing duplicated, and the fix landed only in the copy** | `engine/graphics/canvas/canvas2d_draw_linear_scale.js:18` ⟷ `engine/animation/curve/editor/canvas2dDrawWorldAxisLabels.js:17` | MinHash sim 0.75. Lines 26-42 are byte-identical (spacing guard, delta/`v2_length`/zero guard, direction normalisation). `canvas2d_draw_linear_scale.js:44-46` uses `Math.floor` with a comment explaining that `ceil` *"would place a final tick past position_1 with an extrapolated value"*; `canvas2dDrawWorldAxisLabels.js:44` still uses `Math.ceil` — the documented defect is live in the copy | UNJUSTIFIED | `engine/graphics/canvas/canvas2d_draw_axis_ticks({ctx, position_x0..y1, spacing, label})` where `label(index, fraction)` returns the string. Both callers keep their own value/format policy; uniform control flow, no sentinel parameter | Low effort / Low risk |
+| 19 | MEDIUM | **Full-screen-quad `ShaderMaterial` option block restated 4× in one directory, with a typo divergence** | `engine/graphics/ecs/highlight/renderer/makeBlurShader_9.js:17-24`, `makeDilationShader.js:16-23`, `HighlightDecodeShader.js:57-63`, `OutlineRenderer.js:146-153` | The same 8 properties (`blending: NoBlending, lights: false, fog: false, depthTest: false, depthWrite: false, transparent: true, vertexColors: false, vertexShader: ScreenSpaceQuadShader.vertexShader()`). `makeBlurShader_9.js:18` writes **`light: false`** — three.js has no `light` property, so `Material.setValues` warns and the intended flag is never set. Classic copy-paste transcription error | UNJUSTIFIED | `engine/graphics/shaders/make_screen_space_quad_material({uniforms, fragmentShader})` beside `ScreenSpaceQuadShader.js`; the four call sites keep only their uniforms + fragment source | Low effort / Low risk |
+| 20 | MEDIUM | **Octahedral depth-probe ray kernel duplicated between the two bakers** | `engine/graphics/sh3/lpv/depth/octahedral/bake_octahedral_depth_map.js:95-133` ⟷ `bake_octahedral_depth_map_fibonacci.js:98-141` | ~40 lines byte-identical: `scene.trace` → `distance < 0 ? max_depth` → read `ray_hit[0..5]` → sink the contact along the hit normal by `NORMAL_BIAS` → `v3_distance` from the ray origin → `weight = pow(max2(0, dot(ray_dir, probe_dir)), DEPTH_SHARPNESS)`. The two sampling strategies (per-texel Hammersley jitter vs global Fibonacci splatting) genuinely differ; the shading kernel does not, and if the bias/weight law drifts the two bakers produce different depth for the same scene | UNJUSTIFIED | `trace_biased_depth_sample(scratch_ray, scene, max_depth, ray_direction, probe_direction) -> {distance, weight}` (or two out-params) in the same directory; both bakers call it inside their own sampling loop | Low effort / Low risk |
+| 21 | MEDIUM | **Per-entity event-rule subscription bookkeeping duplicated** | `engine/graphics/ecs/animation/AnimationControllerSystem.js:24` `registerRule` / `:64` `unlink` ⟷ `engine/sound/ecs/SoundControllerSystem.js:62` `registerRule` / `:103` `unlink` | `unlink` is byte-identical (9 lines). `registerRule`'s tail — `if (typeof r.stopEvent === "string") { addEntityEventListener(...); callbacks.push({name, handler}) }` then the same for `startEvent`, then `component.rules.forEach(registerRule)` — is identical modulo the parameter name. Only the two handler bodies (create an `AnimationClip` vs a `SoundTrack`) are subsystem-specific | UNJUSTIFIED | `engine/ecs/EntityEventRuleBinder` (typed class): `bind(dataset, entity, rules, {on_start, on_stop})` and `release(entity)`. Both systems keep only their handler bodies | Low effort / Low risk |
+| 22 | MEDIUM | **The impostor atlas uniform contract restated in 8 material classes** | `engine/graphics/impostors/octahedral/shader/ImpostorShaderV0.js:410`, `ImpostorShaderDepthV0.js:369`, `ImpostorShaderNormalsV0.js:356`, `ImpostorShaderViewportDepthV0.js:332`, `ImpostorShaderPerPixelV0.js:368`, `ImpostorShaderWireframeV0.js:162`, `ImpostorShaderStandard.js:256`, `ImpostorShaderV1.js:14` — all `constructor` | Token-identical constructor bodies at 117 tokens ×4 and 99 tokens ×3. Same `tBase / tGeometry / tMaterial / uFrames / uRadius / uOffset / uIsFullSphere / uDepthScale` set with the same JSDoc text, so an atlas format change (e.g. a fourth channel plane) must be made in eight places. This is not per-class `hash()`/`equals()` shape — it is one data contract restated | UNJUSTIFIED | `make_impostor_atlas_uniforms()` returning a fresh uniform object; each constructor spreads it and adds its own extras (`uParallaxStrength` etc.). Still typed and explicit — no string keys, no registry | Low effort / Low risk |
+| 23 | MEDIUM | **Diffuse-texture async binding duplicated between the two trail plugins, already diverged** | `engine/graphics/trail/tube/TubeXPlugin.js:48` `#build_material` (lines 57-77) ⟷ `engine/graphics/trail/x/RibbonXPlugin.js:96` `__build_material` (lines 110-130) | Identical: `if (typeof spec.diffuse === "string")` → `am.get({path, type: GameAssetType.Texture, callback: asset => { texture = asset.create(); texture.generateMipmaps = true; material.uniforms.uDiffuse.value = texture; }, failure: console.warn})` → `material.defines.USE_TEXTURE = true`. Tube adds `material.needsUpdate = true` (`:76`); Ribbon does not. Tube also routes through `getMaterialManager().obtain()` (`:84`, with a comment explaining Forward+ requires it); Ribbon returns the raw material (`:133`) | UNJUSTIFIED | `engine/graphics/material/bind_diffuse_texture_async(asset_manager, material, path)` handling the define + `needsUpdate`. The material-manager routing difference should be reconciled separately | Low effort / Low risk |
+| 24 | MEDIUM | **The four gi/lpg shader-builder glue functions and two transform-shader files are interchangeable** | `engine/graphics/sh3/gi/material/space_fragment/build_fragment_shader.js:40` and `build_vertex_shader.js:12`; `space_vertex/build_fragment_shader.js:19` and `build_vertex_shader.js:51`; the four identically-named `engine/graphics/sh3/lpg/material/...` counterparts; `gi/material/space_fragment/space_fragment_transform_shader.js:8` ⟷ `lpg/.../space_fragment_transform_shader.js:8`; `gi/.../space_vertex_transform_shader.js:8` ⟷ `lpg/.../space_vertex_transform_shader.js:8` | All eight builders are `result = PREAMBLE (+ PREAMBLE_COMMON) + source; result = insert_after(result, ANCHOR, CHUNK); return result;`. Both `*_transform_shader.js` pairs are 12-line files that are 90% line-identical. The anchors (`#include <lights_fragment_begin>`, `#include <fog_vertex>`) are the load-bearing part and appear in 4 separate string literals | PROMOTION | `engine/graphics/material/build_injected_shader(source, preamble, anchor, chunk)` in the material layer; the eight modules collapse to data (a preamble string, an anchor constant, a chunk string). Anchors become named constants in one place, matching the Forward+ marker contract | Low effort / Low risk (`LightProbeGridMaterialTransformer.spec.js` covers the LPG path) |
+| 25 | LOW | **`packDepthToRGBA` — a verbatim reimplementation of three.js's `<packing>` chunk — appears twice** | `engine/graphics/impostors/octahedral/shader/ImpostorShaderDepthV0.js:264-272` ⟷ `engine/graphics/impostors/voxel/shader/VoxelImpostorShaderDepthV0.js:55-63` | Identical `PackUpscale`/`PackFactors`/`ShiftRight8` constants and body. Both files are `RawShaderMaterial` so three's automatic chunk prefix does not apply — but `ShaderChunk.packing` is importable and splice-able. `VoxelImpostorShaderDepthV0.js:13` even says *"Mirrors three.js's packDepthToRGBA … identical encoding to ImpostorShaderDepthV0"*. If three changes the shadow-map depth encoding, both copies silently break | UNJUSTIFIED | Import `ShaderChunk.packing` from three at one boundary module (`engine/graphics/shaders/chunk_packing.js`) and interpolate it — house rule "confine vendor imports to boundaries" | Low effort / Low risk |
+| 26 | LOW | **Bake-camera frame reconstruction duplicated inside one file** | `engine/graphics/impostors/voxel/bake/read_atlas_to_samples.js:78-96` (`decode_normal_to_object_space`) ⟷ `:145-165` (`reconstruct_position`) | ~20 lines identical: the `abs(Dy) > 0.99999` polar nudge (`Dz + 0.0001`, renormalise), `right = normalize(cross((0,1,0), D))` written out as `(Dz, 0, -Dx)`, `up = cross(D, right)`. `:145` comments *"Same polar nudge as the normal decoder, so right/up agree"* — an explicit must-agree invariant left as two copies. Separately, the same frame concept appears 9× in GLSL as `up_OS`/`tangent_OS`/`binormal_OS` (`ImpostorShaderV0.js:245`, `DepthV0:197`, `NormalsV0:175`, `ViewportDepthV0:163`, `WireframeV0:135`, `PerPixelV0:142` and `:320`, `LitV0:191`) with a *different* degeneracy threshold (`0.999`) and a *different* fallback (swap the up vector rather than nudge Z) | UNJUSTIFIED | Extract a file-local `bake_frame_from_direction(out9, D_frame)` used by both functions in `read_atlas_to_samples.js`; fold the GLSL copies into finding #1's shared chunk | Low effort / Low risk |
+| 27 | LOW | **Two byte-size/component-count switch tables over the *same* enum** | `engine/graphics/particles/node-based/codegen/glsl/getTypeByteSize.js:8` ⟷ `engine/graphics/particles/node-based/particle/ParticleAttributeSpecification.js:23` `computeComponentCount` | Both switch on `ParticleDataTypes` over `Float/Vector2/Vector3/Vector4` and both throw on everything else; the first returns exactly 4× the second. The relationship is implicit — adding a non-4-byte component type makes them silently disagree. (`engine/graphics/particles/particular/group/itemSizeFromAttributeType.js:7` is a third table but over a different, older enum, so it is a separate concern) | UNJUSTIFIED | Keep `computeComponentCount` as the single table; `getTypeByteSize(type)` becomes `component_count(type) * BYTES_PER_COMPONENT`, or the byte width becomes a second explicit case list only if a type ever needs one | Low effort / Low risk |
+| 28 | LOW | **`TubeXFixedPhysicsSimulator` / `RibbonXFixedPhysicsSimulator`** | `engine/graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.js:18` `update` ⟷ `engine/graphics/trail/x/simulator/RibbonXFixedPhysicsSimulator.js:17` `update` | Token-identical (75 tokens ×2). 12-line loop: increment age, `clamp01(age/max_age)`, `setAlpha((1-relative_age)*alpha)`, write the flow UV. Only the method names differ (`incrementKnotAttribute_Scalar` vs `incrementPointAttribute_Scalar`, `setKnotAlpha` vs `setPointAlpha`) | UNJUSTIFIED (small) | Falls out of finding #5: unify `TubeX`'s `*Knot*` accessors with `RibbonX`'s `*Point*` names and keep one `TrailXFixedPhysicsSimulator`. Not worth an adapter interface on its own | Low effort / Low risk (`RibbonXFixedPhysicsSimulator.spec.js` exists) |
+| 29 | LOW | **`SimulationStep*` per-particle loop scaffolding ×4** | `engine/graphics/particles/particular/engine/simulator/SimulationStepApplyForce.js:7`, `SimulationStepCurlNoiseAcceleration.js:20`, `SimulationStepCurlNoiseVelocity.js:21`, `SimulationStepFixedPhysics.js:53` — all `execute` | The 12-line preamble + layer-mask gate (`readAttributeScalar(i, PARTICLE_ATTRIBUTE_LAYER_POSITION)`, `if ((layerMask & (1 << layer_position)) === 0) continue;`, `params = layer_parameters[layer_position]`) is identical in all four. The Acceleration/Velocity pair additionally share the 6-line `power_*`/`scale_*` unpack and the `noise[k] * power_k` application | **JUSTIFIED (hot loop)** for the scaffolding — this is a genuine per-particle JS inner loop; hoisting the body into a callback would make the call site megamorphic across four step types and defeat the reason the mask test is inlined. The `power/scale` unpack shared by the two curl-noise steps is *marginal* — a shared `CurlNoiseStepBase` holding the six-parameter unpack would remove it without adding a per-particle indirection | If touched at all: `AbstractCurlNoiseSimulationStep` holding `parameter_schema` and a `#unpack(params)`; leave the loops inline | Low effort / Low risk — but measure first; not worth doing blind |
+
+### The headline lead, quantified: `sh3/gi` + `sh3/lpv` vs `sh3/lpg`
+
+I measured verbatim line overlap for every corresponding file pair (non-empty, whitespace-normalised):
+
+| lpg file | lpg lines | gi/lpv lines | verbatim-shared | % of lpg |
+|---|---|---|---|---|
+| `lpg/material/LightProbeGridMaterialTransformer.js` | 187 | 256 | 104 | 56% |
+| `lpg/material/space_fragment/build_fragment_shader.js` | 30 | 32 | 24 | 80% |
+| `lpg/material/space_fragment/build_vertex_shader.js` | 38 | 22 | 19 | 50% |
+| `lpg/material/space_vertex/build_fragment_shader.js` | 22 | 21 | 19 | 86% |
+| `lpg/material/space_vertex/build_vertex_shader.js` | 33 | 48 | 20 | 61% |
+| `lpg/material/space_fragment/space_fragment_transform_shader.js` | 10 | 10 | 9 | 90% |
+| `lpg/material/space_vertex/space_vertex_transform_shader.js` | 10 | 10 | 9 | 90% |
+| `lpg/light_probe_grid_textures.js` | 126 | 28 | 20 | 16% |
+| `lpg/light_probe_grid_obtain_storage_cached.js` | 61 | 63 | 40 | 66% |
+| `lpg/build_light_probe_grid_for_scene.js` | 66 | 103 | 43 | 65% |
+| `lpg/material/common.js` | 55 | 426 | 10 | 18% |
+| `lpg/material/chunk_lpg_get_irradiance_at.js` | 18 | 21 | 9 | 50% |
+| **total** | **656** | **1040** | **326** | **50%** |
+
+**Verdict: the fork is roughly 250 deduplicable lines out of ~1700; the rest is genuinely different and
+should stay separate.** Concretely:
+
+- **Mechanically copied (findings #3, #7, #13, #14, #17, #24)**: the transformer skeleton (marker guard,
+  `#onBeforeCompile` stage dispatch, `intensity` accessor, `#uniform_version` gate) ~70 lines ×2 (plus a
+  third copy in `render/forward_plus`); the six shader-builder glue functions ~60 lines; the two
+  `*_transform_shader.js` files ~24 lines; the storage-cached scene-bounds + load/build/store protocol
+  ~45 lines ×2; the bake-via-task overlay ~25 lines ×2; the `DataTexture3D` incantation ~25 lines ×3.
+- **Genuinely different, leave alone**: `gi/material/common.js`'s 426 lines are the tetrahedral walk
+  (`lpv_walk_to_tetrahedron`, `lpv_guess_initial_tet`, barycentric masking, octahedral depth visibility) —
+  the LPG replaces all of it with a 3-line 3D-texture fetch. `lpg/light_probe_grid_textures.js`'s YCoCg
+  half-float/8-bit split encoding has no LPV counterpart. The SH truncation (L2→L1) is a real design
+  difference. `ProbeResolutionStage` is *already* correctly shared (`lpg/material/LightProbeGridMaterialTransformer.js:6`
+  imports it from `gi/material/`), which shows the seam is reachable.
+- **Where the seam belongs**: one `AbstractProbeFieldMaterialTransformer` in
+  `engine/graphics/material/manager/` owning the marker/clone/compose/stage-dispatch, plus the four
+  small promotions in findings #13/#14/#17/#24. Nothing about the tetrahedral-vs-grid lookup needs to
+  be unified.
+
+## Dismissed leads
+
+- `TubeX.js` (557 ln) vs `RibbonX.js` (578 ln) — genuine rewrite, not a copy: `#private` fields, ring topology with a duplicated seam vertex, `v3_orthonormal_matrix_from_normal`, documented throughout. Only the accessor naming (`Knot` vs `Point`) is gratuitously divergent.
+- `particles/node-based/` vs `particles/particular/` — **not a fork**. `node-based` is a GLSL-codegen design with zero importers outside its own tree; `particular` is the live CPU simulator. The two `ParticleSpecification` classes (`node-based/particle/ParticleSpecification.js` vs `particular/group/ParticleSpecification.js`) share only a name — different fields, different purpose. The `particular` one is already marked `@deprecated use AttributeGroupSpec`. This is an unfinished parallel system plus an export-name collision, not duplication.
+- `particles/node-based/nodes/math/Vector3{Add,Divide,Multiply,Subtract}.js` (13 lines each, 79-84% file similarity) — per-node typed classes; house rule explicitly prefers this over a string-keyed operator registry.
+- `AnimationGraph.getStateByDefinition` / `getTransitionByDefinition` / `TextureAtlas.getPatch` / `StaticKnowledgeDatabase.getDescriptorById` — generic "linear scan a small array by field equality"; too small and too type-specific to share.
+- `AnimationGraph.equals` / `AnimationTransitionDefinition.equals` / `AnimationState.equals` — per-class `equals()`; deliberate per house rules.
+- `AttributeGroupSpec.getAttributeByName` / `ParticleSpecification.getByName` / `ParameterTrackSet.getTrackByName` — same 8-line linear scan, but over three unrelated element types in three unrelated collections, and `ParticleSpecification` is deprecated. Not worth a generic.
+- `SGMeshHighlightSystem.js` — despite the name, a different system (propagates highlight down an SGMesh hierarchy), not a fourth copy of finding #8.
+- `engine/graphics/ecs/water` vs `water2` — `water2` contains only a shader plus a browser harness; no forked logic.
+- The "read indices a/b/c then fetch 9 floats at `*3`" block (8+ sites incl. `computeMeshSurfaceArea.js:20`, `tri3_ray_intersection_indexed.js`, `construct_ray_hit_from_geometry.js`) — all inner-loop; a shared reader would need nine out-params or an out-array, which costs more than it saves. `geometry_construct_triangle_normal.js:12` already exists for the one case where the payload justifies it.
+- `setFlag`/`clearFlag`/`writeFlag`/`getFlag` across 30 files (brief §E) — engine-wide component convention, not a domain issue.
+- `inline_lerp` / `inline_length3` hits in `lightmap_seam_fix.js`, `read_atlas_to_samples.js`, `voxelize_samples.js` — per-texel/per-sample loops; inlining is the right call.
+- **Browser harnesses (out of scope, one note as instructed)**: `makeConfig`, `configuration`, `init`, `debug_button`, `catmullRom`, `sample_style_entity` and `makeMovingShadedGeometry` are copy-pasted across at least 12 harnesses — `testPathDisplaySystem.js`, `prototypeAnimatedPathMask.js`, `testShadowMapRendering.js`, `testPointShadowMapRendering.js`, `prototypeBaker.js`, `prototype_voxel_impostors.js`, `prototypeLightProbeGrid.js`, `prototypeSH3Probe.js`, `prototypeShadedGeometry.js`, `prototype_sg_raycast.js`, `prototypeHiZ.js`, `prototypeNormalFrameBuffer.js`, `prototypeParticleVolume.js`, `testClippingPlaneComputation.js`, `testWaterShader.js`, `ptototypeFPPlugin.js`, `prototypeDecalEditor.js`, `prototypeDecalSystem.js`. A shared internal `engine/graphics/harness/` module (engine bootstrap + dat.GUI config + debug button + a spline sampler) would remove several hundred lines. Not counted as a finding.
+
+## Notes
+
+Three structural forces produce nearly all the duplication in this domain.
+
+**1. "V2 by copy".** Every second-generation subsystem here was started by duplicating the first and
+editing: `trail3d` from `trail2d`, `lpg` from `lpv`/`gi`, `mesh-v2` from `mesh`, `water2` from `water`,
+`decal/v2`. That is a defensible way to start, but nothing was ever pulled back afterwards, so the
+newer copy accumulates fixes the older one never receives. Findings #3, #4 and #18 are all the same
+failure mode with the same signature: **the newer file carries a comment explaining a bug, and the
+older file still has that bug.** `Trail3DSystem.js:31-45` documents the head-position mismatch that
+`Trail2DSystem.js:157` still exhibits; `canvas2d_draw_linear_scale.js:44` documents the `ceil`
+over-extrapolation that `canvas2dDrawWorldAxisLabels.js:44` still exhibits; `MaterialTransformer.js:107`
+clones the material where `sh3/gi/material/MaterialTransformer.js:311` throws the clone away. When
+auditing this codebase, an explanatory comment in one of a pair is a reliable index into a live defect
+in the other.
+
+**2. No shader-chunk mechanism.** GLSL lives in template literals inside `.js` files, and the codebase
+has no include mechanism for it (three's `ShaderChunk` is used only through three's own automatic
+prefix, which `RawShaderMaterial` skips). The result: every shader that needs octahedral mapping,
+depth packing, or SH evaluation gets its own transcription. The webpack raw-loader path already exists
+(`ImpostorShaderV1.js:10-11` imports `./glsl/v1/vertex.glsl`), and the `sh3/gi` side already
+demonstrates the string-export pattern (`chunk_lpv_get_irradiance_at.js`, `common.js` as a default
+string export) — the tooling is there, it just wasn't applied to the impostor family.
+
+**3. `System` boilerplate has no base.** `System` is a bare interface, so every renderable system
+re-implements the same three chores: create a render layer, wire `buildVisibleSet` + `compute_depth_range`
+to a BVH, acquire/release a plugin `Reference` in `startup`/`shutdown`. `make_bvh_visibility_builder`
+shows someone already noticed half of it. Findings #8 and #16 are the tail of that.
+
+### GLSL duplication
+
+This is where the mechanical pass is blind, and it is by far the largest volume of duplication in the
+domain. Token-based clone detection sees a shader as one string literal, so none of the following
+appeared in the brief:
+
+- **`VecToSphereOct` is declared 17 times** across `.js` template literals and `.glsl` files, in **four
+  mutually incompatible conventions**: the impostor family folds on `octahedron.y < 0` and returns
+  `.xz` using `sign()` (9 copies); `sh3/gi/material/common.js:118` uses an `l1norm` formulation, folds
+  on `v.y < 0`, returns `v.xz`; `sh3/lpv/depth/octahedral/{shader,stitching,v2}` folds on
+  `direction.z < 0` and returns `.xy` using `sign_not_zero` (4 copies); `impostors/octahedral/shader/glsl/common.glsl:57`
+  and `glsl/v1/*` are HLSL-derived and use `frac`/`saturate`/`tex2Dgrad` (3 copies). Meanwhile
+  `core/geom/3d/octahedra/octahedral_direction_to_uv.js` is the *single* JS implementation and is the
+  one the bake path uses. A shader author reading `VecToSphereOct` in this repo cannot tell which
+  mapping they will get.
+- **The whole octahedral-impostor sampling library (~90 lines)** appears 9 times (finding #1),
+  including twice within `ImpostorShaderPerPixelV0.js` and twice within `ImpostorShaderLitV0.js`
+  because each embeds it in both the vertex and the fragment stage.
+- **The probe-depth library (~220 lines)** is copied from production into a debug visualiser
+  (finding #2), typo included.
+- **The billboard card frame** (`up_OS` pole fallback → `tangent_OS = normalize(cross(up_OS, normal_OS))`
+  → `binormal_OS = cross(normal_OS, tangent_OS)`) appears 9 times in the octahedral shaders, and a
+  differently-thresholded CPU cousin appears twice in `read_atlas_to_samples.js` (finding #26).
+- **The voxel splat expansion** appears 5 times (finding #6), carrying an invariant its own comments
+  say must be kept in sync by hand.
+- **`packDepthToRGBA`** — three.js's own `<packing>` chunk — is retyped twice (finding #25).
+- **The SH cosine-lobe evaluator** appears 3 times in GLSL with two different sign conventions
+  (finding #7).
+- Smaller repeats not worth individual findings: `vec3 inverseTransformDirection(...)` retyped in
+  `sh3/shader/visualize.frag.js:5`, `sh3/lpv/depth/octahedral/shader/visualize.frag.glsl:1` and
+  `.../v2/visualise.frag.glsl:1` (three.js provides it in the standard prefix, but these are
+  `RawShaderMaterial`); the `#ifdef USE_TEXTURE { texel = texture2D(uDiffuse, vUv); diffuseColor *= texel; }`
+  block in `RibbonMaterialX.js:95` and `TubeMaterialX.js:99`; `sign_not_zero` with three overloads in
+  `gi/material/common.js:76-93` and `v2/visualise.frag.glsl:26-43`.
+
+The single highest-leverage change in this domain is not any individual extraction — it is establishing
+one GLSL chunk directory (`engine/graphics/shaders/chunks/`) with the octahedral, SH, packing and
+frame-construction primitives as named string exports, and then deleting the transcriptions. That one
+move retires findings #1, #2, #6, #7, #25 and #26 and removes roughly 1,400 lines of copied shader
+source.