Skip to content

Official Codebase of 3DCodeVerse

Python

docs: effects_catalog, the module comments and ARCHITECTURE are the one home for the effect library — the graphics logs and restatements are gone

gaoypeng3f124dd7ef8e
diff --git a/harness/README.md b/harness/README.md
index 82a48001..0cd9c56a 100644
--- a/harness/README.md
+++ b/harness/README.md
@@ -95,5 +95,4 @@ Docs: `docs/INSTALL.md` (install / prerequisites / doctor troubleshooting) ·
(signatures) · `docs/RUNBOOK.md` (operate / extend) · `docs/DECISIONS.md` (ADRs) ·
`eval/docs/EVAL.md` (evaluation protocol + judge calibration) · `CLAUDE.md` (working rules).
-Graphics library: [integration and scope](docs/GRAPHICS_LIBRARY.md) ·
-[executable Graphics Lab](examples/graphics_lab/README.md).
+Effect library studies: [Graphics Lab](examples/graphics_lab/README.md).
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index f9282662..a59e352a 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -338,7 +338,8 @@ summary:
Plus the harness-owned, read-only **effect library** `src/lib/*.js` (the starter's other
`.js` files are the example scene), shipped into every workspace by BOTH skeleton paths and
listed in `HARNESS_OWNED_SRC` so agent writes to it are reverted (D51, D97). The want → call
- table the prompts carry is `prompts/scene_threejs/effects_catalog.md`.
+ table the prompts carry is `prompts/scene_threejs/effects_catalog.md`; an asset module
+ imports only `three` (`prompts/scene_threejs/asset.md`), so effects are called from zone/env code.
* **glsl_shader**: `src/shader.frag` (+ optional `src/common.glsl`,
`src/buffer_a.frag` for feedback; the harness-owned, read-only `src/recipes.glsl`
is pasted above them when the track seeded recipes) — the agent never writes
diff --git a/harness/docs/DECISIONS.md b/harness/docs/DECISIONS.md
index f91147cc..8de5ab2b 100644
--- a/harness/docs/DECISIONS.md
+++ b/harness/docs/DECISIONS.md
@@ -1000,7 +1000,7 @@ Pointers: EVAL, PAPER_WRITING = `eval/docs/*.md`; COST, RUNBOOK, ARCHITECTURE, I
modules join `starter/src/lib/` as source (D51): fire / firefield / smoke / cloudvolume (bounded ray
marches over baked 3D noise — prescribed transport, not simulation), ocean / stream / waterfall / ice,
meadow / tree / rock / sand / paving, and `lifecycle.js`: `snapshotResources` + `attachDisposal` are the
- one rule every factory disposes by (construction-owned geometry, materials, instance buffers released
+ one rule every object factory in `src/lib/` disposes by (construction-owned geometry, materials, instance buffers released
once; textures and caller additions borrowed). `shader.js` gained `clonePatchedMaterial`,
`withRendererState`, alpha/normal/transmission hooks and inverse-transpose normals; finish patches now
change roughness per pixel under their own mask, not the material's. Scenes may load
@@ -1008,8 +1008,10 @@ Pointers: EVAL, PAPER_WRITING = `eval/docs/*.md`; COST, RUNBOOK, ARCHITECTURE, I
`PCFSoftShadowMap` as BASIC (the renderer uses `PCFShadowMap`); the census missed shader-instanced
geometry; GlHost doubled a relative out dir. Tests follow D96 (a BUILD row + a GPU group each). The
catalog and planner say the effects are zone code, never assets, with no limits stated (D93).
- `examples/graphics_lab/` is a dev lab (one scene per
- module, captures tied to source hashes); its `output/` is ignored and none of its media is committed.
+ `examples/graphics_lab/` is a dev lab (sixteen hand-composed studies rendered through the production
+ scene and GL hosts); its `output/` is ignored and none of its media is committed. 2026-09-23: the lab's
+ session notes, provenance tooling, audit logs and the unused cinematic judge were deleted (owner); the lab
+ keeps build/capture/viewer/serve/scenes.
## Rejected / deferred
diff --git a/harness/docs/GRAPHICS_LIBRARY.md b/harness/docs/GRAPHICS_LIBRARY.md
deleted file mode 100644
index d4a79c50..00000000
--- a/harness/docs/GRAPHICS_LIBRARY.md
+++ /dev/null
@@ -1,164 +0,0 @@
-# Graphics libraries and the scene authoring surface
-
-The harness already supplied reusable graphics code before the natural-element
-extension. There are two distinct authoring paths:
-
-| Track | Agent-facing reusable code | Execution |
-| --- | --- | --- |
-| `scene` / `scene_threejs` | `src/lib/*.js`, copied from `codeverse3d/languages/scene_threejs/starter/src/lib/`; factories and shader patches indexed in `codeverse3d/prompts/scene_threejs/effects_catalog.md` | Three.js WebGL scene host, authored cameras, absolute-time scene update, shared post chain |
-| `graphics` / `glsl_shader` | Selected cookbook functions and dependencies seeded into harness-owned `src/recipes.glsl` by `tracks/graphics.py` | Fragment shader frames and motion probes through the graphics runtime |
-| `graphics` / `opengl_python` | Raw moderngl and GLSL with cookbook guidance | Python-driven OpenGL passes; no Three.js object library |
-
-The scene library is the right place for reusable objects that coexist in a
-Three.js world. Imports from the shipped tree are explicitly allowed under the
-raw-language contract. The harness freezes those files against agent edits;
-the agent composes them from its own scene, zone and environment files.
-The dedicated standalone asset-generation stage still permits only Three.js
-imports. Instantiate shipped effects in zone/environment code instead of planning
-duplicate flame, water-ribbon or grass-patch assets. The scene planner now states
-this distinction explicitly; the first live trials exposed that ambiguity.
-
-The initial audit found 44 scene library modules, including procedural
-materials, noise, shader composition, grass, reflective water, sky, weather,
-terrain, foliage, buildings and placement helpers. This shares its lineage
-with a separate reference project outside this repository.
-That reference has additional modules, but it is not a drop-in replacement:
-the harness has its own renderer, lifecycle and effect budget, and D74 records
-the deliberate removal of eight unused effects. Copying every reference
-module back would undo that decision.
-
-The first natural-element extension added six modules, expanding the original
-44-module library to 50:
-
-| Module | What it adds | Material limitation |
-| --- | --- | --- |
-| `fire.js` | Local volumetric flames, animated illumination, embers, wax candles with pools, drips and wicks | Transparent-volume ordering requires care; no combustion simulation |
-| `ocean.js` | A directional Gerstner spectrum, sampled height/normal, filtered reflection and crest foam | Reflection uses a mean plane; no breaking-wave fluid solver |
-| `stream.js` | A descending curved channel, refracted stone bed, flowing ripples, obstacle wakes and optional bank reflections | Opaque-scene screen-space refraction; approximate caustics and mean-grade reflection; no fluid/solid coupling |
-| `sand.js` | Seeded dunes, filtered wind ripples, grain detail and moving windborne grains | Dune shape is static; no granular erosion simulation |
-| `rock.js` | Closed fracture-plane rock geometry, strata, minerals, moisture and moss | Procedural geometry rather than scanned geological assets |
-| `meadow.js` | Multiple leaf growth forms, habitat/age variation, optional seed heads, coherent wind and thin-leaf lighting | Density and shadow resolution must suit the viewing distance |
-
-Every new factory returns a Three.js object with `userData.update(t, dt)` and
-`userData.dispose()`. `t` is absolute seconds; update each effect once from the
-zone or scene. Sampling APIs operate in the object's local coordinates. The
-factory owns its internal resources; externally attached props retain their
-own lifecycle. Individual module JSDoc specifies dimensions, options and limits.
-
-The extension reuses existing `noise.js`, `shader.js`, material and lighting
-helpers. The shared renderer owns tone mapping and postprocessing; examples
-do not replace the renderer or change its global settings. A separately
-verified Three r182 shadow-filter compatibility fix is recorded in D97.
-
-See [Graphics Lab](../examples/graphics_lab/README.md) for runnable studies,
-stills, deterministic H.264 capture, a live viewer and browser validation.
-The hand-composed studies and actual model-generated trials are kept separate,
-so a curated demonstration is never presented as an autonomous agent result.
-
-The second refinement replaces the stream's alpha overlay with Three's physical
-transmission path (IOR 1.333). `waterColor` now specifies volume absorption over
-`attenuationDistance` metres, rather than painted surface colour. Opaque objects
-under the water are refracted; transparent objects and offscreen geometry are
-outside that screen-space source. `reflectionSize: 0` is the default; a value of
-256–2048 adds one planar capture of the banks, and must not be combined with
-another water/Reflector capture. The built-in transmission pass has its own
-rendering cost even with bank reflections disabled.
-
-Graphics Lab's `compare.py` retains immutable baseline workspaces and replaces
-exactly one module per comparison. Its before/after manifest records source
-hashes, identical cameras and time, and real GPU metrics. Scene dressing in the
-main gallery is separate from that controlled library comparison.
-
-The subsequent full-library review is tracked in [the development record](GRAPHICS_ROADMAP.md).
-It includes explicit resource ownership, transformed normal/placement fixes,
-point-light shadow silhouettes, patch-preserving material clones and local
-physical surface response. Shader-material clones also retain borrowed texture
-samplers, including live render targets, and static batches retain source uniform
-controls. Added capabilities with inspected GPU compositions include
-structural trees, self-shadowed cloud volumes and closed fractured ice. `tree.js`
-provides connected oak/birch/willow and shrub architecture with individual leaves,
-wind and shadow deformation. Default trees are roughly one million triangles;
-use their leaf budget and actual census results for each composition. A bounded
-`leafSegments` option reduces distant leaf geometry while keeping the seeded
-placement, count, colour and woody structure unchanged. Species defaults retain
-the close-view silhouette; four segments suit unresolved background leaves. `cloudvolume.js`
-provides a bounded density field with internal sun attenuation, not terrain
-shadows or fluid dynamics. `ice.js` builds closed floes with real gaps, local
-surface queries and approximate face-dependent optical paths.
-
-`waterfall.js` adds a weir/free-fall sheet with conserved flow thickness,
-advected surface detail and existing impact spray. Its origin is receiving
-water level, lip at `[0,height,0]`, with flow toward +Z. The caller supplies
-the upstream surface, backing/cliff and pool. The CPU query and actual GPU
-position/thickness are checked independently. The composed stone/woodland weir
-study uses one 512-pixel downstream reflection capture.
-
-`paving.js` adds foreground cobbles and rectangular setts as closed bevelled
-geometry with recessed joints. Its exact local height query includes both stone
-tops and the joint bed, so props can be seated correctly. It uses two meshes and
-a bounded stone count; the material-only cobble preset remains useful at distance.
-This is procedural paving rather than photogrammetric stone.
-
-`smoke.js` adds `makeSmoke` and `makeSteam`: seeded, rising volume density with
-wind, expansion, dilution, Beer extinction and directional/point illumination.
-The emitter is at local y=0; density queries use local coordinates and optical
-extinction uses world metres, including nonuniform object scale. Both return a
-Mesh with absolute-time update and owned disposal. In ordinary depth mode smoke
-and cloud volumes test their first contributing density sample, so an opaque
-object behind visible density no longer incorrectly erases the entire volume.
-Neither volume integrates scene depth to truncate density at embedded opaque
-objects; logarithmic depth retains the proxy-box fallback. No collision solver,
-scene-shadow reception or shadow casting is implied. The smoke study includes
-tea and charcoal examples with captured source hashes and six-second films.
-
-`firefield.js` adds `makeFireField` for campfires, larger fuel beds and authored
-window/roof flames. Up to 16 emitters share one integrated flame/soot field, with
-metre-sized embers and at most four practical lights. A baked source atlas keeps
-the per-sample density cost independent of emitter count; source layout and wind
-are construction-time settings. The balanced tier uses 80 view samples, five
-soot-light samples and about 1.49 MB of 3D texture storage, before optional depth
-targets. Screen coverage and quality still determine render cost.
-
-An explicit `occluders` list enables a separate borrowed-geometry depth pass and
-truncates volume rays at those opaque surfaces. Perspective/orthographic cameras,
-offset viewports, transformed fields, camera layers, alpha cuts, instances and
-supported depth-material deformation have actual GPU regressions. This resolves
-embedded-wall intersections that the older first-density test cannot handle.
-Glass and overlapping transparent volumes remain unsupported; skinned occluders,
-morphed InstancedMesh occluders and logarithmic-depth capture are excluded.
-Unmatched custom vertex deformation needs a corresponding `customDepthMaterial`.
-The implementation does not simulate combustion, fluid flow, fire spread or
-structural collapse. Legacy `makeFire` and `makeCandle` remain available unchanged
-by this addition. See the campfire/bonfire and structural-fire gallery studies.
-
-The GLSL authoring surface also has executable SDF, volume-transport and direct
-GGX regressions. Three composed recipe studies and their ordered 144-frame
-films are built with `examples/graphics_lab/build_recipes.py --video`. These
-are authored examples, with source/recipe hashes, rather than model outputs.
-
-Standalone `.vert`, `.frag` and `.glsl` files also work inside a Three.js scene.
-Load their text using `THREE.FileLoader` and a module-relative `new URL(...)`
-inside async `createScene`; use the resulting strings in `ShaderMaterial` or
-`RawShaderMaterial`. JavaScript still owns object construction, uniforms and
-updates. The browser does not support a raw `.frag` ES module import or a bundler
-`?raw` suffix here. Arbitrary GLSL helper files must be loaded and joined explicitly;
-Three's `#include <chunk>` resolves its own shader chunks, not filesystem paths.
-See the [scene contract](../codeverse3d/prompts/scene_threejs/contract.md) for the
-loading pattern and GLSL ES conventions. Synchronous asset builders retain their
-existing contract; perform loading in the scene factory before returning.
-
-The source writer, snapshots and candidate promotion preserve these shader
-files. Shader preflight includes them in source reports and maps GPU compiler
-errors to their original file and line. Cross-file uniform declarations and
-bindings are checked after material assembly, avoiding JavaScript-only assumptions
-about standalone GLSL. Graphics Lab stages and hashes all three shader suffixes
-alongside scenes and library modules, including capture and transfer packages.
-Desktop OpenGL host code requires a browser/WebGL adaptation; shader-text support
-does not make native OpenGL programs directly executable in Three.js.
-
-The final September 23 integration passed **2,922 offline tests** and Ruff,
-including the large-fire and external-shader additions. One existing Pillow
-deprecation warning remains. This is behavioral/runtime evidence, not a claim
-that every procedural effect is photorealistic. Gallery and media results are
-recorded separately in the [development record](GRAPHICS_ROADMAP.md) and
-[gallery review](../examples/graphics_lab/REVIEW_2026-09-23.md).
diff --git a/harness/docs/GRAPHICS_ROADMAP.md b/harness/docs/GRAPHICS_ROADMAP.md
deleted file mode 100644
index 037e5d56..00000000
--- a/harness/docs/GRAPHICS_ROADMAP.md
+++ /dev/null
@@ -1,142 +0,0 @@
-# Graphics effects development record — September 23, 2026
-
-## Objective and scope
-
-The user requested a thorough review and refinement of the existing graphics
-effects, plus useful new effects, allowing seven hours of sustained development.
-Work began around 07:27 UTC. This record separates completed verification
-checkpoints from work still awaiting final integration.
-
-The review covers all 50 existing Three.js library modules, their agent-facing
-catalog, lifecycle and composition contracts, rendered appearance and runtime
-behavior. It also checks the separate GLSL graphics cookbook/recipe surface and
-OpenGL authoring guidance. Existing upload packages remain immutable; new
-gallery revisions and transfer packages use distinct artifacts.
-
-Every existing module needs an explicit disposition: improve with evidence,
-retain with justification, or supersede while preserving a documented caller
-path. Passing compilation alone does not establish visual quality. New effects
-must fill a meaningful gap, remain usable by scene authors, and have inspected
-GPU cases plus appropriate behavioral validation.
-
-## Review ownership
-
-| Family | Existing modules | Evidence record |
-| --- | --- | --- |
-| Weather, water and atmospheric light | accumulation, atmosphere, caustics, celestial, clouds, damp, godrays, rain, sky, submerged, veils, water, watermist, waterside, wetground | `graphics_audit_weather.md` |
-| Living scenes and animation | canopy, cloth, dapple, figure, fire, flock, flowers, foliage_shade, grass, meadow, smalllife, woodland | `graphics_audit_life.md` |
-| Built environment and surfaces | aging, building, finish, materials, neon, roadway, rock, sand, signage, strata, surface_wear, terrain, terrain_shade, urban, windows | `graphics_audit_surfaces.md` |
-| Shared code and recent water | environment, instancing, merge, noise, ocean, place, shader, stream | `graphics_audit_core.md` |
-
-The complete baseline source, original hashes and export inventory are retained
-in `examples/graphics_lab/output/seven-hour/`. The inventory contains 50 rows;
-reviews must not silently omit older effects because recent showcase modules
-already have stronger tests.
-
-## Work sequence
-
-1. Inspect each module and its tests; render representative factory/material
- combinations and identify visual, numerical and ownership defects.
-2. Correct substantive existing defects and improve effect appearance, with
- fixed-camera evidence where appearance changes. Keep shared rendering
- behavior stable unless a separately demonstrated renderer defect requires it.
-3. Add distinct missing capabilities identified by that review. Use bounded
- algorithms, absolute simulation time, seeded construction, documented local
- coordinates and owned-resource disposal. Do not duplicate an existing effect
- under a new name merely to increase the library count.
-4. Integrate agent guidance, inspect composition cases and exercise the library
- through independent coding-agent cases where useful. Preserve source/model
- provenance and distinguish authored demonstrations from model output.
-5. Run relevant regression checks, real GPU rendering, animation and browser
- controls; inspect code/video correspondence and English-only example text.
- Record limitations and performance costs, then audit the full objective.
-
-## Maintenance checkpoint
-
-All 50 original modules have an explicit, evidence-backed disposition: 47 received
-visual, behavioral or ownership corrections; three were retained with stated
-justification. The original source/hash baseline remains unchanged. Six new visual
-modules (tree, cloud volume, ice, smoke, waterfall and paving) and one resource
-ownership module have inspected cases and focused tests.
-
-The complete offline suite passed **2,890 tests** in 196.94 seconds, with one
-unrelated Pillow deprecation warning. Ruff also passed. Retained logs are
-`/tmp/graphics-seven-hour/offline-maintenance-checkpoint.log` and
-`/tmp/graphics-seven-hour/maintenance-ruff.log`. These establish the maintenance
-checkpoint before the later fire-field and external-shader extension.
-
-Substantive final maintenance corrections include:
-
-- Stream, calm water and wet-floor captures use the correct transformed plane and
- restore nested renderer state after success or exceptions. Sixteen real GPU
- state cases pass; transformed mirror-camera error falls from 6.876 metres to
- floating-point noise. Existing raw water/floor pixels remain bit-identical.
-- Cloud support no longer reaches the proxy box walls or wraps separated shapes
- through the boundary. Five seeds and multiple times/cameras were inspected.
- Wind moves internal density detail; whole-cloud translation remains explicit.
-- Tree leaf geometry can be reduced independently of seeded leaf placement and
- woody structure. The rain composition falls from 20.7 to 12.4 million triangles
- while retaining its foliage count and silhouette at the tested cameras.
-- Rain shelter coverage, stream/meadow finite HDR edges, true terrain sampling,
- owned resource disposal, transformed normals and animation contact retain their
- focused actual-GPU/behavioral evidence in the family records.
-- The revised Luna creek now matches bank geometry to its water grade and seats
- actual pebbles. Original CLI output and later delegated refinement remain
- separately identified in the agent-case provenance.
-
-The three GLSL recipe films have been decoded and compared with ordered source
-frames. The gallery verifier now binds source snapshots, encoded-file digests and
-three retained input PNGs; it checks complete camera plans and rejects substituted
-primary scenes, stale sources, changed video bytes and frozen animation. Pixel
-change is not an aesthetic score.
-
-## User-requested extension after maintenance
-
-The subsequent request specifically adds campfire, large open fire and burning-house
-visual cases, and asks whether Three.js can consume independent GLSL files. A real
-GPU audit found that scaling the original fire by ten preserves almost the same
-image structure and motion; it also integrates density behind embedded opaque
-walls. The new bounded shared multi-emitter field now provides optional explicit
-opaque-depth termination. Ten focused tests and an independent depth/layer/opacity/
-displacement review pass. Campfire, open-bonfire and structural-fire compositions
-have inspected GPU frames. Existing candle and small-fire behavior is retained.
-
-Independent `.vert`, `.frag` and `.glsl` loading already works in the scene runtime,
-writer, snapshots and candidate promotion. Guidance now documents asynchronous
-local FileLoader loading; standalone asset builders remain synchronous. Shader
-preflight now maps external compile errors to their original file and line.
-Real GPU valid and broken external shaders have source-line tests. Gallery
-staging, capture, verification and transfer packaging preserve those shader files
-and retained input frames; 22 build/media/package regressions pass. The completed
-external-shader material study has nine inspected stills, finite HDR/replay/disposal
-checks, a source-bound six-second film and a passing browser-control check.
-
-## Final integration
-
-The first combined attempt recorded 2,917 passes and two failures: Chrome closed
-during a cloud probe, and the mixed external/inline GLSL support downgraded a static
-diagnostic from an unused shader. The isolated cloud module passes all seven tests;
-the diagnostic was repaired using unambiguous evaluated-source participation.
-Twenty-nine focused diagnostic tests pass. The interrupted `gallery-v1` capture
-remains a failed attempt, separate from the final gallery.
-
-The complete final offline suite passed **2,922 tests in 225.65 seconds**, with one
-existing Pillow deprecation warning. Ruff passed. Logs are
-`/tmp/graphics-seven-hour/offline-final-clean.log` and `final-ruff-clean.log`.
-Regression and final video capture use separate task-specific browser caches and
-run sequentially. The frozen `gallery-v2` registry contains 19 cases, 58 library
-modules and three independent shader files. All 159 stills across 53 cameras
-rendered cleanly. The complete 30-film / 4,320-frame plan passed strict decode,
-source ownership, encoded digest and retained input-frame checks. Browser checks
-passed all 19 cases and 53 cameras with playback, pause/scrub/reopen/cancellation
-and zero errors. Twenty-seven films demonstrated anchor motion; static or very
-subtle rock/sand/workshop views are not reported as motion evidence.
-
-The new first-six transfer package contains 113 files and 74,973,979 bytes, with
-source/capture checks, ZIP CRC and extracted-file hashes verified. Original ZIPs,
-comparison baselines and published historical media remain byte-identical.
-The [final gallery record](../examples/graphics_lab/REVIEW_2026-09-23.md) links the
-actual output, package, verification reports, costs and remaining visual limits.
-Passing checks does not imply fluid/combustion simulation, recursive transparent
-transport or photorealism. Far terrain, some geology/cloud shapes, fire highlights
-and the authored architecture retain visible procedural limits.
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 82d0a02d..4421c98c 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -268,25 +268,8 @@ BuildResult.error_type spellings (languages/_common.py): MISSING_ENTRY = "Missin
| `GlslShaderRuntime` | `src/shader.frag`, `src/common.glsl`, `src/buffer_a.frag` (+ the harness-owned `src/recipes.glsl` when seeded) | harness owns `#version`/uniforms/`out` (wrap.HEADER: u_time/u_resolution/u_mouse/u_frame/u_prev/u_noise + iTime/iChannel* aliases); `wrap.compose(shader, common, recipes_src=…)` pastes header < recipes < common < shader; build renders judge frames via GlHost; compile errors → GlslCompileError at mapped src file:line (recipes.glsl included); lint ERROR `redefines_recipe` when an agent file defines a recipes.glsl name; artifacts frames/, frames_sheet.png, preview.gif, metrics.json |
| `OpenGLPythonRuntime` | `src/program.py`, `src/*.glsl` | `setup(ctx,w,h)->state` + `render(ctx,state,t,frame,fbo)` run in a moderngl subprocess (`wrappers/run_gl.py`); exceptions map to src/program.py:line, in-string GLSL errors carry both line numbers |
-**Scene effect ownership and shader composition.** The agent imports the frozen
-`src/lib/` modules from zone/environment code. Object effects expose
-`userData.update(t, dt)` with absolute seconds; older `tick(t)` aliases remain
-compatible. Call one update path once per frame. Factories with
-`userData.dispose()` capture construction-owned resources, including instance
-buffers and custom shadow materials; later caller additions and borrowed
-materials/textures retain their owner's lifetime. `lifecycle.snapshotResources`
-excludes textures by default, and `attachDisposal(root, resources)` releases an
-explicit set once, attempting all cleanup before reporting aggregate errors.
-
-`shader.patchStandard(material, opts)` composes registered patches, including
-`alphaBody` before alpha testing, `normalBody` after normal maps and
-`transmissionBody` after Physical-material optical maps but before refraction.
-`clonePatchedMaterial(material, {shareUniforms:false})` reconstructs registered
-patches and independently copies typed uniforms while borrowing textures;
-ShaderMaterial/RawShaderMaterial uniforms follow the same rule.
-`shareUniforms:true` retains the source map for externally controlled static
-batches. `shadowLike` supplies both displaced depth and point-distance materials.
-External unregistered shader wrappers must be reapplied by their owner.
+**Scene effect ownership and shader composition** are stated where they live: `src/lib/lifecycle.js`
+(`snapshotResources` / `attachDisposal`) and `src/lib/shader.js` (`patchStandard`, `clonePatchedMaterial`) (D97).
Wrappers are standalone (never import codeverse3d). The three python build wrappers live
together in `languages/wrappers/` — `run_bpy.py`, `run_bpy_links.py` (Blender's python 3.11),
diff --git a/harness/docs/graphics_audit_core.md b/harness/docs/graphics_audit_core.md
deleted file mode 100644
index 605faea1..00000000
--- a/harness/docs/graphics_audit_core.md
+++ /dev/null
@@ -1,269 +0,0 @@
-# Shared graphics, water and runtime audit
-
-> Historical working notes from the development snapshot (2026-09-23). The per-module test files
-> and case counts cited below were folded into `tests/scene_runtime/lib/test_library.py` when the
-> library landed on main (D96, D97); `/tmp/...` evidence paths are from that session and are not kept.
-
-This is the integration audit for the eight original modules assigned to the
-core pass, with the later shared-runtime regressions and new capabilities recorded
-separately. The authoritative module ledger is
-[`inventory.json`](../examples/graphics_lab/output/seven-hour/inventory.json).
-Its 50 historical source hashes all match the untouched
-[`baseline/src/lib`](../examples/graphics_lab/output/seven-hour/baseline/src/lib/).
-At this checkpoint, 47 original modules changed; `caustics.js`, `finish.js` and
-`ocean.js` were retained unchanged. Retention is an explicit disposition, not an
-omission. There are eight additional modules: seven visual capabilities and one
-ownership helper. They are not counted among the original 50. The accepted frozen
-source contains **58 modules and 190 actual named exports**. The gallery registry
-contains 19 scenes (16 library studies and three independent agent cases), plus
-three external shader files.
-
-The [weather](graphics_audit_weather.md), [life](graphics_audit_life.md) and
-[surface](graphics_audit_surfaces.md) ledgers explain the other 42 original
-modules. The inventory gives each module's actual named exports, baseline and
-current SHA-256, disposition, tests, concrete evidence and remaining limits.
-The inventory binds the accepted frozen sources and completed integration evidence.
-The final offline suite, gallery captures, strict media checks, browser controls and
-maintained first-six transfer package pass, with the limits recorded below.
-
-## Original core modules
-
-| Module | Final disposition, concrete evidence and limits |
-| --- | --- |
-| `shader.js` | **Corrected shared behavior and ownership.** Surface normals now use the inverse transpose, including mirrored transforms; local directions use the full reciprocal basis under composed shear. Sixteen model/instance combinations are compared to CPU references on the GPU. Displaced point-light distance shadows now accompany depth shadows, with shared alpha silhouettes. Normal and transmission hooks preserve patch order. Depth-pass guards compose existing callbacks and restore authored draw ranges. Typed material cloning preserves borrowed samplers, control sharing and registered patches. The shared synchronous `withRendererState` scope now restores nested capture state on success and failure. See `test_shader_geometry.py` and the detailed regression table below. Arbitrary external shader wrappers and host postprocessing remain outside this helper's contract. |
-| `place.js` | **Corrected world/local placement.** The frozen valid scaled-parent fixture buried a seated base by 16.5506 m, moved it horizontally by 7.8634 m and missed the requested heading by 94.18 degrees. Seating, facing and route placement now preserve world targets; hidden ancestors cannot supply supports or obstructions. `test_spatial_ownership.py` measures resulting positions and headings. Baseline measurements are retained in `/tmp/graphics-seven-hour/baseline/core/probes.json`. These are placement heuristics, not rigid-body collision simulation. |
-| `instancing.js` | **Corrected geometry and cleanup.** A mirrored baseline box had all 12 triangles wound against its normals, and a hidden sibling was baked into the result. Prototype mirrors now reverse winding; mirrored placements use a corrected batch with positive-determinant matrices. Hidden branches are omitted. Cleanup owns copied geometry and instance buffers while borrowing prototype materials. Invalid zero/infinite spacing fails without unbounded construction. Evidence: `test_instancing.py`, `test_spatial_ownership.py` and the frozen core probes. Batching still depends on compatible prototype materials and geometry. |
-| `merge.js` | **Corrected material preservation and cleanup.** Batches previously replaced physical materials with MeshStandardMaterial, losing transmission, thickness, IOR and attenuation. Cloning now retains the material type and registered patches, with deliberately shared animation controls. Mismatch diagnostics cover optical maps/properties, and cleanup owns only output geometry/material. Existing colour baking and mirrored winding remain. `test_merge.py` and the live render-target clone/merge regression verify behavior. Merging is not a substitute for transparent-object sorting. |
-| `environment.js` | **Corrected enclosure geometry and ownership; retained background appearance.** Independently built sill/lintel strips refilled overlapping door/window openings. The enclosure now subtracts their union, checked by more than 1,500 occupancy rays in `test_room_shell.py`. Environment factories dispose their own maps and light shadow targets; caller attachments stay borrowed. `test_environment.py` and spatial ownership tests cover the contracts. The inexpensive horizon, ground continuation and mood lighting remain lighting/background tools, not volumetric weather. |
-| `noise.js` | **Corrected numerical limits and retained field appearance.** The seed-offset cache is bounded without changing deterministic values; zero octaves produces a flat field and nonfinite/overflow inputs fail clearly. Displacement refreshes existing culling bounds. `test_noise.py` and spatial ownership checks cover these changes. The established seeded ImprovedNoise field remains, avoiding changes to every dependent effect's geometry. It is a procedural field, not a measured physical distribution. |
-| `ocean.js` | **Retained unchanged after prior visual refinement.** Its existing implementation has 32 dispersive directional bands, analytic normals, filtered micro-slope roughness, directional sky reflection and bounded mean-plane reflection. The ten current tests cover inverse surface sampling, narrow shore contraction, light refresh, ownership and GPU compilation. Prior fixed-camera images are in `examples/graphics_lab/output/comparison/renders/ocean/after/`; the refined first-six package includes the film. Those visual changes predate this seven-hour pass and are not counted again. Limits remain non-overturning kinematic waves, one mean-plane reflection and no fluid solver. |
-| `stream.js` | **Corrected composed optics and reflection state; retained recent flow design.** Border fallback blends radiance rather than folding UVs. Optical rays intersect the graded bed under full world/local transforms, and optional endpoint fade supports weir joins. The reflector uses an inverse-transpose world-plane normal under scale/shear, and scoped cleanup restores renderer state on success or failure. The 15 current cases include actual refraction/border pixels, transformed optical rays, mean-plane camera geometry and GPU state restoration. The waterfall black patch was traced to upstream meadow NaNs, not repaired by hiding the sheet. Matched evidence and limits are recorded below. |
-
-## Shared regressions checked against the actual tests
-
-These are current collected cases, including parameter expansion. Counts identify
-coverage. The later planar and external-shader follow-ups have retained execution
-logs and real GPU evidence. Historical family execution results and final combined
-integration status are distinguished below.
-
-| Component and test file | Cases | Behavior demonstrated |
-| --- | ---: | --- |
-| `tests/scene_runtime/lib/test_shader_geometry.py` | 8 | Inverse-transpose normals and reciprocal directions cover 16 model/instance combinations. Depth/distance variants share deformation, time and alpha silhouettes. Callback guards support arrays, later material replacement and authored ranges. Physical transmission hooks execute after maps and survive cloning. ShaderMaterial/RawShaderMaterial clones retain ordinary and render-target texture identity while copying typed values, unless sharing is explicit. A real GPU check samples a live render target through a clone and a merged batch, including later source-uniform edits. |
-| `tests/scene_runtime/lib/test_meadow.py` | 6 | Fractional blade-height powers use a finite domain. A 3,000-blade, four-sample, half-float target with NoToneMapping is read back at two times; the failing fixture had 699 nonfinite HDR channels and the corrected fixture has zero. Other cases retain seeded geometry, motion, validation and ownership coverage. |
-| `tests/scene_runtime/lib/test_stream.py` | 15 | Actual checkerboard refraction and border-radiance tests accompany CPU/GPU flow and sampling checks. Independent ray/plane calculations cover transformed optics. Reflection camera geometry covers scale/shear. Eight renderer-state configurations cover pixel ratios 1/2, default versus post-binding target rectangles, and successful versus injected-failure capture. |
-| `tests/scene_runtime/lib/test_planar_capture.py` | 3 | Water and wet-ground addon capture cameras and projected coordinates agree with independent plane math under uniform, nonuniform, mirrored and composed transforms. Sixteen success/failure target configurations preserve renderer state. Caller-attached Mesh, Camera/inverse, Bone hierarchy and manually managed world matrices survive nested capture and return with their authored update flags; disposal preserves caller resources. The third test checks nested shared-state scopes and callback results/exceptions. |
-| `tests/scene_runtime/test_external_shaders.py` | 8 | Actual GPU loading of separate `.vert`, `.frag` and `.glsl` files succeeds; a broken raw fragment maps to its actual source line. Raw shader static auditing does not reinterpret helper text as an independent JavaScript material. A successful GPU compile resolves uncertain declarations only when the audited literal participates in the evaluated shader and its source origin is unambiguous. Three additional regressions preserve errors in unused/ambiguous bodies; missing runtime bindings remain errors. |
-| `tests/scene_runtime/test_census_instances.py` | 3 | The bound `geometry._maxInstanceCount` is authoritative. An unused short instance attribute cannot reduce the actual draw count. GPU submissions with requested instance counts 8, 3 and Infinity agree with renderer statistics; pre-binding inference remains conservative. Hidden ancestors, draw-range starts and primitive type are covered. |
-| `tests/graphics/test_graphics_lab_lifecycle.py` | 1 browser test, six scenarios | Authoritative disposal, fallback ownership boundaries, fallback cleanup failure, throwing scene/renderer cleanup, invalid scene contracts and cancelled asynchronous creation all release renderer/context/canvas exactly once. Borrowed textures, cached materials and caller attachments survive. Cleanup failure cannot prevent later cleanup steps. |
-
-The shader clone repair addresses two distinct native-clone failures: ordinary
-textures were duplicated, and render-target uniforms could become null. Aliasing
-between `material.uniforms` and the library control map is preserved. Registered
-Astra patches are copied; an arbitrary caller's `onBeforeCompile` wrapper still
-requires explicit reattachment. The tests check runtime values and rendered pixels,
-not merely shader source spelling.
-
-Scene census counts visible submitted geometry. It does not multiply that count by
-shadow, reflection, transmission or postprocessing passes, and points/lines do not
-become triangle counts. Viewer fallback cleanup observes ownership boundaries;
-an explicit scene disposer remains authoritative rather than being followed by an
-unconditional resource traversal.
-
-## Waterfall composition: isolated failure and repair
-
-The stream investigation is frozen at
-`/tmp/graphics-seven-hour/stream-reflection-fix/README.md`, with before sources,
-an isolated clamp-only variant, exact final sources/tests, `comparison.jpg` and
-`sha256.json`. The matched waterfall view used a 512-pixel reflection target.
-In the fixed region x390:510, y475:525, near-black pixels fell from 793 to zero.
-
-Captured half-float transmission and reflection targets established the cause:
-multisample edge interpolation made a meadow height coordinate slightly negative;
-fractional powers generated NaNs. The falling film sampled that invalid HDR
-radiance and mip filtering spread it. Hiding the film removed propagation but left
-the bad upstream target. Clamping only the meadow power inputs removed the visible
-patch with the film, its transmission and stream reflection all enabled. This is
-supported by the separate meadow HDR regression; it is not a claim that every
-black pixel is a transmission defect.
-
-The stream's independent plane-transform repair agrees with an analytic reflected
-camera within 2.2e-9 m in its fixture; the 1e-7 tolerance permits the Float32 ribbon
-anchor. Capture restores target, cube face, mip, logical and actual viewport/scissor,
-scissor test, XR, shadow auto-update, tone mapping, clear colour/alpha and prior
-surface visibility. Post-binding rectangle overrides are retained without changing
-target metadata. A `finally` block covers errors in capture; it cannot reconstruct
-a partially rendered frame after arbitrary errors inside Three.js.
-
-The earlier border-only comparison remains at
-`/tmp/graphics-seven-hour/new/stream-edge-comparison/`: only `stream.js` changed,
-with six matched GPU frames. Sixteen transformed optical-ray fixtures agree with
-independent bed-plane intersections within 0.012 mm at these scene scales.
-The later final-b reflection evidence contains eight frames at four matched cameras
-and times 0/1.5, with no shader/console errors; all 15 stream cases passed in its
-recorded checkpoint. One mean-grade reflection and screen-space transmission remain
-approximations, without recursive transparent transport or hydraulic collisions.
-
-## Addon planar capture maintenance follow-up
-
-`/tmp/graphics-seven-hour/planar-capture-review/README.md` freezes the Water and
-wet-ground transform/state repair. Stock addon rotation extraction cannot represent
-the inverse-transpose normal under shear/nonuniform scale. A temporary rigid plane
-frame supplies the correct reflected camera, while each addon retains its own
-projection convention: Reflector's matrix is remapped to actual mesh-local geometry;
-Water's matrix projects world positions and is not remapped. Identity-scene RGBA
-readback stayed bit-identical in 1,228,800 channels. Thirty-two matched full-post
-frames cover water, wet ground, rain and cloud scenes with no compile/console errors;
-the retained repeated-baseline controls quantify minor postprocessing variation.
-
-The shared `withRendererState` guard restores target/cube face/mip, logical and
-actual viewport/scissor, scissor test, XR, shadow update, tone mapping and clear
-colour/alpha. Foreign override/material passes and capture re-entry are skipped.
-The addon mesh's real world matrix and update flags are restored after capture.
-
-Independent review then found that the nested scene update propagated the temporary
-rigid matrix to caller descendants. `/tmp/graphics-seven-hour/planar-descendant-review/`
-retains exact before/after sources and a regression that fails both old factories.
-The final fix freezes descendant world recomputation for the capture and restores
-both authored update flags in `finally`. Mesh, Camera including its inverse matrix,
-Bones and manually managed transforms are checked during and after actual rendering,
-on success and injected failure. Camera/bone ownership remains with the caller.
-The relevant 48-case suite passed in 20.43 seconds; the independent reviewer also
-reproduced the fix on the GPU. Ordinary horizontal calm-water normal fields remain
-an approximation: correct reflection geometry does not imply arbitrary-orientation
-physical water shading, a multiple-reflector coordinator or recursive transport.
-
-## Eight accepted additions, kept separate from the original fifty
-
-| New module | Capability, evidence and explicit limits |
-| --- | --- |
-| `firefield.js` | `makeFireField` combines 1–16 authored sources into a bounded flame/soot field with a baked source atlas, rising reaction sheets, world-distance optical extinction, sized embers and practical lights. **Ten tests pass.** `/tmp/graphics-seven-hour/firefield-final/` freezes the accepted SHA `bbb4c77b1e4b88f23f9cdc34d88d3b2f428b510ea2c48422546328ff789c1fff`, nine structural-fire GPU views, and exact sources. Optional isolated borrowed-geometry depth proxies terminate rays at opaque geometry; perspective/orthographic, transformed cameras, hidden parents/layers, opacity/alpha cuts and dynamic displacement are checked. Camera-layer, inactive-emission, displacement-refresh and opacity defects were independently reproduced, repaired and rechecked. This is prescribed fire/soot transport, not combustion, fuel consumption, ventilation, fluid dynamics or structural failure. Skinned/morphed-instanced occluders and optional log-depth capture are unsupported; transparent intersections remain limited. |
-| `cloudvolume.js` | Bounded ray-marched clouds, self-shadowing, Beer extinction, quality tiers and a CPU density query. **Seven tests pass.** `/tmp/graphics-seven-hour/cloud-final-refinement/` is the accepted latest source and 48 matched composed/independent-seed GPU images. Stationary unequal convection towers and support prevent advected noise regrowing against proxy faces; G/B erosion noise still moves. CPU/GPU inset-boundary density falls from about 0.028 to zero for the regression. Earlier first-density depth and rounded base-fade repairs remain. This does not simulate evolving convection, truncate rays at intersecting opaque geometry, or cast terrain cloud shadows; log-depth retains the proxy fallback. |
-| `ice.js` | Closed bevelled fracture floes, fitted gaps, absorption/frost, internal air lenses and an exact top-triangle height query. Nine tests and `/tmp/graphics-seven-hour/ice-final/` provide source and three-view evidence. Optical exit distance is approximate; Three transmission does not recursively trace water or other floes. Fractures are authored, not a mechanics simulation. |
-| `paving.js` | Closed crowned/bevelled cobbles or setts, recessed joints, moisture response and triangle-based height sampling in two merged meshes. Eight tests and `/tmp/graphics-seven-hour/paving-final/` plus `paving-variants/` cover geometry and dry/wet appearance. Patches are rectangular, without arbitrary-route conformity or standing-water optics. |
-| `smoke.js` | Seeded rising smoke/steam, bounded density, CPU query, quality tiers, lighting and world-metre extinction. Six tests include nonuniform optical path scale and first-density depth testing. Frozen evidence includes `/tmp/graphics-seven-hour/new/smoke/renders-v7-dilution/` and `new/smoke-v7-films/`. These are prescribed transport/scattering fields, without fluid dynamics or scene-depth truncation; logarithmic depth keeps the proxy fallback. |
-| `tree.js` | Connected branches, petioles and leaves, species-specific forms, coherent wind and filtered bark. **Sixteen tests pass**, including finite HDR and supersampled bark for three species. `/tmp/graphics-seven-hour/tree-bark-refinement/final/` freezes the material refinement. Later opt-in `leafSegments` reduces leaf triangles while preserving wood, leaf count, placements and colours; species defaults stay unchanged. Rain V5 uses four segments for background leaves: 20,706,817 to 12,419,137 scene triangles (40.02% less), with the same 102 meshes and 490,979 instances. This is a geometry reduction, not an FPS claim. Wind is prescribed and host AO sees rest geometry. |
-| `waterfall.js` | Accelerating free-fall film with width/velocity/thickness conservation, advected breakup, local aeration and existing impact spray. Four tests compare CPU/GPU film position and thickness and cover quality, replay and ownership. Current composed evidence is `/tmp/graphics-seven-hour/waterfall-composition/final-reflective/`, with the lower stream reflector enabled at 512 pixels; the earlier `new/waterfall-v9-films/` films retain their own source versions. This is an authored sheet, not hydraulic collision simulation; its transmission sees the opaque scene and impact spray is not simulated droplets. |
-| `lifecycle.js` | **Support module, not a visual effect.** Construction-time resource snapshots and idempotent, failure-tolerant cleanup. Two direct tests and family ownership regressions verify the contract. Textures are not implicitly owned; factories must add allocated textures and other private resources explicitly. |
-
-The accepted cloud support refinement retains the final-b depth/base repairs and
-supersedes the earlier five/six-test cloud checkpoints. The later meadow HDR repair
-and tree bark refinement likewise supersede those specific life-family snapshots. Earlier immutable evidence
-remains useful but is not silently relabelled as the latest source.
-
-The separately composed campfire/open-bonfire V4 study retains nine accepted GPU
-frames under `/tmp/graphics-seven-hour/campfire-root-v4/`. The shared field's bounded
-local emitters, smoke, embers and practical lights scale independently; legacy
-`fire.js` remains unchanged by this extension. The structural scene is visibly
-procedural, and fine upper-wisp ray-march grain and saturated bright windows remain
-honest visual limits. Whole-image motion includes other animated scene content;
-the dedicated regression isolates field motion and exact absolute-time replay.
-
-The independent integration review is retained at
-`/tmp/graphics-seven-hour/final-integration-review/README.md`. In addition to the
-four firefield issues above, it records repaired external-GLSL declaration handling,
-a package verification-to-copy race, and planar descendant transforms. Corrections
-have independent rechecks; this does not replace the final combined suite/gallery.
-
-## Separate graphics authoring surface
-
-The GLSL cookbook is executable library content seeded into `src/recipes.glsl`.
-Its star distance function, zero-length segments, reversed smoothstep edges and
-rain-cell advection were corrected using numerical GL checks. Bounded-volume
-transport and direct GGX recipes provide explicit conventions and dependency
-seeding; they are neither a fluid simulator nor a complete path tracer.
-The OpenGL cookbook's sphere winding now agrees with its outward normals, and its
-normal/ownership guidance matches the actual setup/render host contract.
-
-Three six-second GLSL films are retained under
-`examples/graphics_lab/output/seven-hour/recipes-motion-v1/`, with source hashes,
-ordered frame verification and a recorded mean compression error of 1.03–1.48/255.
-The explicit frame order prevents lexical `f100`-before-`f10` encoding. A real
-relative-output render exposed double resolution of the GL job path; resolving
-the output directory once fixed it. These recipes and runtime fixes are additional
-work, not extra JavaScript modules in the 50-plus-seven census.
-
-The Three.js scene authoring contract now explicitly supports local shader source
-files through `FileLoader(loaders.manager)` and module-relative URLs in async
-`createScene`. Browser loading remains outside synchronous asset builders. The
-accepted `external_shader.js` study loads a `.vert`, `.frag` and `.glsl` helper,
-uses explicit GLSL3 interfaces and animates cached uniforms/transforms at absolute
-time. `/tmp/graphics-seven-hour/external-shader/` retains three camera views at
-three times, clean actual-GPU shader diagnostics, zero nonfinite HDR channels under
-4x MSAA, exact time replay and exactly-once owned-resource disposal. Its restrained
-alloy finish uses an analytic studio reflection field; it does not receive scene
-shadows/interreflection and is not a multilayer optical solver. Gallery source
-staging, hashes and portable packaging are separate integration checks.
-
-## Final verification and retained history
-
-The final whole offline suite is **clean: 2,922 passed, one existing Pillow
-deprecation warning**, in 225.65 seconds. The retained dedicated-cache log is
-`/tmp/graphics-seven-hour/offline-final-clean.log`. Ruff also passes, retained in
-`/tmp/graphics-seven-hour/final-ruff-clean.log`.
-
-The completed [gallery V2](../examples/graphics_lab/output/seven-hour/gallery-v2/index.html)
-contains **19 cases, 53 cameras and 159 stills**, with no shader, console or update
-errors in the retained render metrics. Its 19 primary films and 11 extra views
-produce **30 verified films and 4,320 decoded frames**. The
-[strict media report](../examples/graphics_lab/output/seven-hour/gallery-v2/media-verification/report.json)
-checks every encoded digest, three retained encoding-input PNGs per film and all
-63 source files per staged scene. Twenty-seven films have measurable anchor-motion
-masks; rocks, sand and workshop remain below that threshold without failing.
-Maximum first-frame RGB error is 4.688922882/255; maximum 160×90 input-anchor error
-is 1.316990733/255. Motion/error metrics verify media correspondence, not realism.
-
-The [browser report](../examples/graphics_lab/output/seven-hour/gallery-v2/browser-check.json)
-passes all 19 cases and 53 cameras, playback/pause/scrub/reopen/cancellation controls,
-with zero errors. Its English scan covered 4,407 files before the final transfer
-package was added; this statement does not substitute for a later expanded scan.
-The local gallery is served at [http://127.0.0.1:45649/](http://127.0.0.1:45649/).
-The water/atmosphere still review is retained in
-`/tmp/graphics-seven-hour/final-water-gallery-review.md`: 15 selected final views
-match accepted work without a material capture regression. Rounded cloud billows,
-faceted terrain, the interior terrain edge, prescribed water motion and other
-explicit procedural limits remain visible.
-
-The maintained first-six transfer is available as a
-[folder](../examples/graphics_lab/output/seven-hour/gallery-v2/packages/graphics_lab_first_six_maintained_2026-09-23/)
-and [ZIP](../examples/graphics_lab/output/seven-hour/gallery-v2/packages/graphics_lab_first_six_maintained_2026-09-23.zip).
-It contains 113 files; the ZIP is 74,973,979 bytes with SHA-256
-`26efcebd51c76ba7b1a27eb8fdeea5cab0851ec0b9ef628bfaf556f3ae501098`.
-The source manifest, ZIP CRC and extracted hashes pass, recorded in
-`/tmp/graphics-seven-hour/final-transfer-package.json`. This package covers fire,
-ocean, stream, sand, rocks and meadow; the full 19-case gallery is a separate
-local output. Earlier delivered packages remain immutable.
-
-Historical attempts remain explicit. Gallery V1 is **failed and retained**, and
-is not a completed deliverable. `/tmp/graphics-seven-hour/offline-integration-1.log`
-records 2,872 passes and the subsequently repaired documentation-map failure.
-`offline-maintenance-checkpoint.log` records the clean but earlier 2,890-pass
-maintenance checkpoint. `offline-final-integration.log` records 2,917 passes and
-two failures: the cloud boundary fixture's browser closed with `Target closed`,
-and an unused `bad.js` declaration error was wrongly cleared after an unrelated
-starter shader compiled. Despite that test's historical `without_compile` name,
-preflight compiled the starter. The final correction requires literal participation
-in the evaluated shader and unambiguous source origin. The retained diagnostic
-checkpoint (`shader-report-focused.log`) has 29 passes; the isolated cloud recheck
-(`cloud-recheck-isolated.log`) has seven passes in 18.97 seconds with no source
-relaxation. The clean 2,922-pass final run supersedes the failed attempt. All these
-log names resolve under `/tmp/graphics-seven-hour/`; none is relabelled as another run.
-
-The previous collection preserves 742 cases across 67 files in
-`/tmp/graphics-seven-hour/historical-final-inventory-test-collection.txt`.
-The final collection contains **768 cases across 70 files** in
-`/tmp/graphics-seven-hour/final-inventory-test-collection.txt`, including library,
-census, viewer lifecycle and external-source tests. Actual module imports verify
-190 named exports, and all 58 library hashes match the frozen canonical files.
-Collection remains distinct from execution. Family checkpoint counts overlap and
-must not be summed into the final pass count; their snapshots prove the exact
-captured module versions, not the latest identity of all shared dependencies.
-
-Rain V5 is a composition change, not an isolated library comparison.
-`/tmp/graphics-seven-hour/rain-composition/REVIEW.md` and `leaf-detail-comparison.json`
-record its fixed-camera appearance and background leaf reduction. The earlier
-shelter probe remains applicable because later planting revisions leave roof,
-deck, rain and splash construction unchanged: 4,092 deck probes per camera have
-zero roof misses, and all 720 splash positions avoid sheltered ground impacts.
-Repository source/tests and the final gallery reports are durable references;
-`/tmp` studies are local unless explicitly packaged. This ledger does not claim
-that every historical temporary capture is included in the maintained six-case ZIP.
diff --git a/harness/docs/graphics_audit_life.md b/harness/docs/graphics_audit_life.md
deleted file mode 100644
index fa4aeada..00000000
--- a/harness/docs/graphics_audit_life.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# Living and animated graphics audit
-
-> Historical working notes from the development snapshot (2026-09-23). The per-module test files
-> and case counts cited below were folded into `tests/scene_runtime/lib/test_library.py` when the
-> library landed on main (D96, D97); `/tmp/...` evidence paths are from that session and are not kept.
-
-Audit started 2026-09-23 07:29 UTC against the current working tree. The first sections preserve the baseline assessment; implementation and validation below describe the completed changes. No shared gallery configuration was edited by this family owner.
-
-The frozen source, source hashes, probe script/results, render scenes, PNGs, runtime logs and full test output are under `/tmp/graphics-seven-hour/baseline/life`. Every case contains its own copy of the frozen library so later shared-workspace edits cannot alter the baseline. The tests completed with **148 passed in 27.93 seconds**. Compilation and structural tests pass; this does not establish realism or complete resource cleanup.
-
-The audit uses the production Three.js host and post chain at 960 × 640, times 0 and 0.7 seconds. Most scenes adapt the existing compile fixtures, adding a background or closer camera where needed. They are diagnostic scenes, not claimed polished showcases. The woodland compile fixture places cards closer than its own documented 35 m exclusion distance; `woodland_far` is the appropriate additional visual comparison. `meadow_showcase` uses the already authored meadow example for a composed reference. A sparse test fixture or missing scene ground is not attributed to a library defect.
-
-## Frozen baseline findings
-
-| Module / exports | Assessment and evidence | Priority and proposed work |
-| --- | --- | --- |
-| `canopy.js`: `makeCanopy` | Real leaf silhouettes, one instanced draw, seeded crowns and shared gusts already work. `canopy/renders/a_t0.png` shows an overly regular ellipsoid/hedge envelope, radial leaf orientation and very dark lower cards. Leaves move independently of any branch skeleton because none is supplied. FrontSide cards lose their reverse faces. Bounds expand by leaf size but do not explicitly include arbitrary wind excursion; frustum culling is disabled. No update/dispose hooks. | **High visual / medium reliability.** Add coherent leaf sprays and growth/age variation with restrained two-sided leaf lighting; make bounds account for wind. Keep crown placement and batching APIs. Add ownership lifecycle. A separate tree factory should supply actual branches rather than silently changing the canopy-only contract. |
-| `cloth.js`: `makeFlag`, `makeBanner`, `makeWheatField` | Flag attachment, travelling waves, banner folds and crop gust propagation are more developed than a generic sine deformation. The rendered flag/banner at both times are readable and do not need a solver rewrite. Wheat remains a field of bare stems and paper-thin ears. No dispose/update hooks; each wheat material owns a generated `uWheatWave` DataTexture. All displaced shadows depend on custom depth only. | **High reliability, medium visual.** Capture and dispose owned geometry, materials, shadow materials and gust texture. Preserve the existing cloth motion; improve light response with actual cloth sheen/transmission and add crop leaf/ear structure within the same draw budget. Clarify point-light shadow limitations or implement distance shadows through the shared helper. |
-| `dapple.js`: `patchDappledLight`, `patchCanopyShade` | `dapple/renders/a_t0.png` shows useful multiscale flecks, but they are an emissive lighting approximation and do not obey actual scene-light intensity or shadow visibility. Dapple normal transformation uses `mat3(modelMatrix) * normal` (and instanceMatrix) rather than inverse transpose, which gives wrong facing on non-uniformly scaled objects. Projection uses canopy height without subtracting the fragment's own elevation, so elevated receivers do not share the same projected gaps. | **High correctness.** Correct receiver normals and projected height. Add controlled light-strength/visibility behavior while preserving the deliberately approximate canopy-shade mode. Verify a tilted, non-uniformly scaled receiver and receivers at multiple elevations. Avoid replacing this with another arbitrary noise pattern. |
-| `figure.js`: `figure`, `sit`, `walk`, `carry` | Seated placement, joints and materials are well tested, but the person is visibly a segmented mannequin at close range (`figure/renders/face_t0.png`); do not claim realistic humans. At speed 1.2 m/s, the lowest shoe penetrates ground by **5.44 cm** during the sampled cycle. `walk(...,{speed:0})` still changes hip angle by 0.0234 rad between t=0 and .4. Cadence arithmetic alone does not produce foot contact. Own geometry and borrowed globally cached materials are mixed. | **High motion / medium lifecycle.** Correct zero-speed behavior and stance/swing contact, add deterministic foot-clearance tests. Improve visible neck/limb junctions conservatively; retain the distant-human scope. Disposal must release owned geometries while preserving material-cache and shared-eye resources and caller-held objects. |
-| `fire.js`: `makeFire`, `makeCandle` | New volumetric flame, seeded motion, candle geometry and real light remain convincing in `fire/renders/fire_t0.png`; preserve them. The existing disposer captures geometry/materials but does **not** call `InstancedMesh.dispose()` on `FireEmbers`, leaving its separate instance buffers allocated after rendering. Log-depth and intersecting transparency limits are already explicit. | **High lifecycle, justified no large visual rewrite.** Fix owned ember-instance disposal with a real disposal-event regression. A rising smoke plume would add a missing capability, but belongs in a separate emitter effect rather than changing existing fire defaults. |
-| `flock.js`: `makeFlock` | Bird/fish silhouettes and decorrelated beats read well at their intended distance (`flock/renders/sky_t0.png`). The claimed speed in metres/second is only an average: the shader advances uniform Catmull-Rom parameter, not arc length. A valid irregular five-point path requested at 9 m/s measures **0.141–21.937 m/s**. Lighting direction is manually supplied and interpreted in local axes. No lifecycle hooks beyond tick. | **High motion.** Use an arc-length lookup and derivative-aligned banking; keep a seeded shader path, one draw and absolute time. Add a CPU sampler or testable path table. Preserve documented distant-silhouette scope. Add lifecycle and transform/light-space regression. |
-| `flowers.js`: `makeFlowers`, `makeFalling` | Individual petals already have curved geometry, species-dependent profiles and seeded variation. `flowers/renders/a_t0.png` nevertheless shows many white heads on bare straight stems: missing foliage/branching and shared head attitude dominate the artificial appearance. Transparent unsorted instancing uses depthWrite, so overlapping petal edges deserve an occlusion check. Existing falling leaves/petals already fill that capability. No dispose/update hooks. | **High visual.** Add species-appropriate basal/cauline leaves, head age/openness and subtle asymmetric curvature; retain one draw and existing kinds. Evaluate alpha coverage or an opaque clipped core with physically motivated thin edges. Improve petal lighting via the shared leaf patch, not extra albedo brightening. Add lifecycle and overlap tests. |
-| `foliage_shade.js`: `patchLeafSSS`, `patchWind`, `patchRootContact` | Leaf transmission adds a view-dependent term to albedo before ordinary lighting, so it is not a shadowed incident-light scattering term; it uses a copied sun direction. `patchWind` moves vertices without correcting surface normals, and its static shadows are explicitly documented. Root contact is a useful world/local-aware material treatment and needs no ornamental rewrite. | **High lighting.** Add normal-correct wind deformation and a scene-light-driven transmission path with shadow attenuation, preserving explicit overrides and patch retuning. Keep root-contact behavior unless a regression demonstrates a problem. The patches own no material, so disposal belongs to their callers. |
-| `grass.js`: `makeGrass`, `windOf` | Efficient older field, useful for medium/far ground cover; the composed close-view role now belongs to meadow. `grass/renders/a_t0.png` is very dark with pointed, similarly shaped leaves. Its shader comment still says this host has no AO, although the host now has GTAO. Bounds cover the root footprint plus vertical height, not lateral bent blades; culling is disabled. Transmission adds light without shadow attenuation. No lifecycle disposal. | **Medium visual, high compatibility.** Preserve low-cost far-field role and windOf API. Fix conservative bounds and disposal; revisit darkness/transmitted sun against the current host, with matched front/backlight renders. Avoid making it a second expensive meadow. |
-| `meadow.js`: `makeMeadow` | Recently improved mixed growth forms, botanical age/habitat variation, rooted curved geometry, wind, shadows and sparse geometric seed culms already have matched GPU evidence. Do not undo this work or raise density as a cosmetic fix. Ownership snapshot preserves caller additions, but neither blades nor culms receive `InstancedMesh.dispose()`. | **High lifecycle, justified no major visual rewrite.** Dispose captured instances as well as geometry/materials. Add a regression with seed heads enabled and a caller-owned appended InstancedMesh. Point-light rest-pose shadows and AO limitations are explicitly documented; coordinate any shared shadow-helper improvement. |
-| `smalllife.js`: `makeInsects`, `makeReeds` | Insect kinds have distinct bounded motion, wingbeat and lighting. `smalllife_close/renders/a_t0.png` shows reeds as bare thin poles with pointed billboard heads; strap leaves are missing. An artificial underwater positional offset also moves the submerged root, despite the rooted contract, and can duplicate actual stream refraction. Scene-light refresh depends on tick count. No disposal/update hooks. | **High reed visual / medium reliability.** Add curved strap leaves and rounded/tapered heads, rooted below-water motion, and optional rather than baked-in refraction distortion. Preserve insect batching; improve deterministic relighting/update semantics and lifecycle. More insect species alone would be lower value. |
-| `woodland.js`: `patchBark`, `makeImposters` | Bark already has distinct species-dependent ridges and weathering. Distant cards are explicitly unsuitable inside ~35 m; the compile fixture violates that rule, so its close result is not evidence to replace them with full trees. Even in `woodland_far/renders/a_t0.png`, a continuous pale rim and repeated rounded crowns remain obvious. No lifecycle on the imposter group. | **Medium visual/reliability.** Reduce continuous halo, increase coherent crown silhouette variation, validate light space under allowed parent transforms and add disposal. Keep their far-field performance role. Near trees should be a new geometry-based factory. |
-
-## Reproducible defects and validation gaps
-
-`probes.json` records the lifecycle inventory, the flock speed measurement and the shoe-height probe; the exact executable script is `src/audit_probe.mjs`. Fire and meadow both report one owned InstancedMesh and zero instance-disposal events in the minimal probes. Installed Three r182 `WebGLObjects.js` removes instanceMatrix/instanceColor buffers in its InstancedMesh dispose listener, independently of BufferGeometry disposal.
-
-Most older factory tests are strong on seeded attributes, shader strings, counts and compilation. New tests should verify the physical or lifecycle behavior being changed: disposal of owned buffers and textures exactly once; caller-resource survival; finite-difference normals; light/shadow response; actual speed and foot contact; same-time rewind. Replacing one asserted shader string with another is insufficient.
-
-At the frozen baseline, shared `shadowLike` supplied customDepthMaterial only. A shared customDistanceMaterial improvement could benefit several modules and should be coordinated with the owner of shader.js; independent per-module copies would duplicate sensitive Three.js shader integration. Flower alpha silhouettes also need the same cut in any new distance pass.
-
-## Proposed implementation order
-
-1. **Ownership and compatibility:** one agreed reusable ownership helper or small explicit snapshots, including textures, custom shadow materials and InstancedMesh buffers. Add update aliases without removing tick. Figure materials remain borrowed; patched materials remain caller-owned.
-2. **Measurable motion and lighting:** flock arc-length speed, figure stance contact/zero speed, dapple receiver projection/normals, wind normals and leaf transmission. Test each behavior on controlled fixtures before aesthetic tuning.
-3. **Botanical silhouette:** flower leaves/head variation, reed leaves/seedheads and canopy spray structure; inspect matched close and wide views, motion and backlighting. Keep instance/draw budgets visible.
-4. **New capability:** a seeded branch-aware `makeTree` / `makeShrub` module, with tapered branch junctions, leaf sprays located at branch tips, optional age/species presets and coherent branch wind. Existing canopy creates only a leaf cloud, and existing imposters only distant cards. This fills the missing near/mid-tree role without duplicating grass, falling particles or fog.
-
-A buoyant smoke/steam emitter is also valuable, particularly with fire/candles, but should be coordinated with the air-family work. Existing watermist and atmospheric fog are surface/region veils, not a rising turbulent plume. Prefer one well-tested emitter with emission history, bounded lifetime and scene lighting over several superficially renamed particle presets.
-
-Any approved implementation should retain these frozen cameras/sources for comparison, add composed ecological scenes where the compile fixtures are insufficient, and reserve time for integration/GPU checks rather than consuming the full seven hours on optional species.
-
-
-## Implemented changes and verification
-
-The current family source is frozen under `/tmp/graphics-seven-hour/after/life/src/lib`, with SHA-256 hashes in `source-hashes.json`. The original 15 diagnostic workspaces were rendered again with identical cameras, lights, resolution and timestamps: **34 GPU images across 17 views**, with no shader or runtime errors. `comparison-metrics.json` records image differences and motion; these values demonstrate changed pixels, not a perceptual quality score. Inspect the PNG pairs for appearance.
-
-The family suite completed with **183 tests passed in 33.10 seconds**. The final denser flock test and tree tests then completed with **24 passed in 5.71 seconds**. Ruff passed after import ordering was corrected in the new tree test. This is a family-level result, not a claim that the entire repository suite has run.
-
-| Module | Final behavior and evidence |
-| --- | --- |
-| `canopy` | Leaves now grow in coherent six-leaf sprays, with curved 24-triangle surfaces, two-sided lighting, analytic surface normals and wind-aware bounds. The existing ellipsoid-placement API remains a canopy-only abstraction; it does not pretend to contain branches. Matched `canopy/renders/a_t0.png` and `a_t0p7.png` show the changed silhouette and coherent motion. |
-| `cloth` | Flag and banner motion retained; actual physical-material cloth sheen added. Wheat gains two curved strap leaves and curved ear geometry in the same instanced draw. The generated gust DataTexture is explicitly owned and released. Existing attachment/wave and GPU tests remain green. |
-| `dapple` | Receiver elevation now changes the canopy-ray intersection correctly. Normals use the shared inverse transpose, and fleck radiance follows actual directional-light intensity and shadow visibility, with irradiance-to-diffuse-radiance division by PI. GPU tests compare translated receivers on the same light ray and light-off behavior. |
-| `figure` | Two-bone leg IK, stance and swing phases, measured shoe-vertex clearance, and compensating ankle pitch keep one foot on the ground. Zero speed restores a stable neutral pose. A high requested speed shortens the gait period instead of silently clamping travel and sliding the stance foot. Neck geometry now bridges the visible gap. Tests cover three body heights, rewind and actual stance velocity up to 4 m/s; this remains a stylized distant mannequin, not a realistic human model. |
-| `fire` | Flame and wax appearance retained. Disposal now includes captured ember InstancedMesh buffers and lights. The custom render guard preserves its mesh receiver when delegating to the shared depth-pass guard. The matched frame differs by only 0.008/255 mean RGB, while animation remains active. |
-| `flock` | A 2,048-sample arc-length DataTexture drives both shader motion and a new CPU `samplePath(t)` sampler. Centripetal interpolation avoids cusps caused by uneven waypoint spacing. The final irregular 9 m/s route measures 8.9955–9.0011 m/s over 1,600 dense samples; the regression uses 8,000 samples around the full period. Lighting normals now reach world space correctly. |
-| `flowers` | Six species-scaled basal/cauline leaves replace bare stalks. Petals use opaque alpha clipping with consistent directional and point-shadow silhouettes, eliminating unsorted translucent overlap. Corrected petal/boss normal orientation prevents black sunlit heads. Transmission preserves flower pigment instead of applying green-leaf variation. A real GPU test verifies sunlit white petals remain bright. |
-| `foliage_shade` | Transmission is shadowed incident radiance, following the scene directional light unless an explicit direction overrides it. Wind uses the analytic deformation Jacobian to update normals; a finite-difference GPU reference agrees within one degree. `patchRootContact` was retained because no defect justified changing its useful behavior. Material patches borrow their inputs and never install ownership disposal. |
-| `grass` | Low-cost medium/far blades remain eight triangles each. Root occlusion and fill were adjusted against the current renderer, transmission obeys shadows, and conservative bounds include bent blades. It remains distinct from the richer close-view meadow. |
-| `meadow` | The existing recent botanical, age, habitat and shape variation was preserved. Captured blades, seed culms and custom shadow resources now dispose completely, including instance buffers. Directional and point-light deformation share the improved global shadow helper. |
-| `smalllife` | Reeds now include four curved strap leaves and shorter, rounded seed heads with extra longitudinal samples around their shoulders. Underwater optical distortion is opt-in and vanishes at the root. Insects refresh scene-light intensity on every update, so lighting and rewind no longer depend on frame count. Close reed matched images show the largest structural change. |
-| `woodland` | Crown silhouettes have seeded lean/shape differences, porous foliage edges and interior gaps, filtered fine breakup and reduced continuous rim brightness. Opaque clipping removes partial-alpha coverage halos between unsorted cards. World normals use the shared inverse transpose. The documented limit now emphasizes crowns about 60 screen pixels or smaller: the older 35 m guideline depended on a 512 px image and was not resolution-independent. Existing bark patch retained; the new tree factory supplies true near wood. |
-
-All object factories expose both `userData.update(t)` and the compatible `tick(t)` alias, plus captured, idempotent disposal. The lifecycle regression covers 15 factories, original resources removed from the returned hierarchy, subsequently appended borrowed meshes and textures, and shared figure material caches. Ownership uses the new shared `lifecycle.js`, authored by the integration owner. Shared `shadowLike` now supplies depth and point-distance materials; flower cuts are shared between passes. The integration owner also corrected world normals, world-to-local directions and mirrored/nonuniform/sheared transforms in `shader.js`. Those shared fixes are dependencies, not duplicated implementations in this family.
-
-### Measurement precision
-
-The initial shoe probe reported a conservative transformed bounding-box penetration of 5.44 cm. A later **exact vertex** probe on the frozen source measured 3.364 cm of actual shoe penetration and up to 2.208 cm with both feet above ground. The same exact probe on the new source reports ground error below 3e-16 m and a maximum swing lift of 11.18 cm. These are procedural fixture measurements, not motion-capture validation. The scripts/results are `/tmp/graphics-seven-hour/life_measure.mjs`, `baseline-foot-vertices.json`, and `after/life/probes.json`.
-
-### Explicit geometry cost
-
-The frozen baseline host census counted `InstancedMesh` correctly but undercounted `InstancedBufferGeometry.instanceCount`. The integrated runtime now counts both, using the bound active-attribute capacity when available. The older-effect budget below includes the geometry instance multiplier; historical render metrics remain unchanged:
-
-| Effect | Base triangles per instance, before → after | Draw impact |
-| --- | ---: | --- |
-| Canopy leaf | 6 → 24 | One instanced mesh retained; 4,000 leaves = 96,000 triangles. |
-| Wheat stalk/ear/leaves | 14 → 38 | One instanced mesh retained; cap 70,000 means up to 2.66 million triangles. |
-| Default daisy plant | 86 → 230 | One instanced mesh retained, including its new foliage. |
-| Reed stem/head/leaves | 24 → 272 | One instanced mesh retained; choose density for close stands deliberately. |
-| Grass blade | 8 → 8 | No density increase or extra blade draw. |
-| Imposter card | 2 → 2 | Porosity and lighting are shader changes. Crossed trees use two cards. |
-
-## New connected tree and shrub library
-
-`tree.js` exports `makeTree(opts)` and `makeShrub(opts)`. Oak, birch and willow presets have connected primary limbs, secondary branches, twigs, fine shoots, real petioles and individually instanced species-shaped leaves. Primary radius follows its tapered parent's cross-section. Variable curvature, apical continuation, branch collars and buttress roots replace equal-weight repeated Y forks. Bark has procedural plate/fissure color and a filtered continuous height gradient; no generated bitmap or model was used. Leaf age/autumn variation, scene-lit transmission and coherent rooted wind are included.
-
-The API uses nominal `height` and `crownRadius`, seeded `leafDensity`, `leafSize`, `maxLeaves`, `autumn`, colors, shadows and the existing wind vocabulary. `maxLeaves` thins the entire crown without stripping later-created branches. `userData.bounds` gives the actual local envelope, `branches` exposes parent/attachment/sample information, `leafAttachments` locates botanical anchors, and `sampleWind(point,t)` samples the wood deformation. These are deterministic absolute-time operations.
-
-Each factory uses two geometry draws, one if bare, excluding shadow passes. Default oak is **961,224 triangles / 15,540 leaves**, birch **1,130,544 / 14,504**, willow **954,060 / 17,765**, and shrub **734,010 / 11,700**. This is a near/mid asset; leaf density/cap should be reduced for background use. The composed `examples/graphics_lab/scenes/tree.js` contains three species, a shrub, meadow, rock and a small projected distant treeline. Its independently counted total is **2,771,713 triangles and 14 geometry draws**. The frozen older census reports 918 fewer triangles because it misses the far cards' instance multiplier; the integrated runtime corrects that count.
-
-Final source and hashes are frozen in `/tmp/graphics-seven-hour/new/tree/final`; renders at 1280 × 800 and t=0/.7 are in `final/renders`. The identical woodland/branches cameras were retained through v1–v11 iterations, so branch refinements are reviewable. Final GPU tests cover fog, directional plus point shadows, nested nonuniform transforms, actual pixel motion and exact time rewind. Structural tests verify branch and petiole attachment, whole-crown cap distribution, outward wood winding, bounds, seeded equality, invalid options and borrowed-resource survival.
-
-Remaining limits are explicit: wind is a coherent deformation field rather than a dynamic beam solver; the host AO sees real tree/meadow geometry in its rest pose; standalone `patchWind` cannot install moving shadow materials on meshes it does not own; imposters remain distant cards; the figure remains a mannequin; fire retains its documented transparent-intersection and logarithmic-depth limits. None of the images is claimed to establish universal photorealism.
diff --git a/harness/docs/graphics_audit_surfaces.md b/harness/docs/graphics_audit_surfaces.md
deleted file mode 100644
index c9c299b8..00000000
--- a/harness/docs/graphics_audit_surfaces.md
+++ /dev/null
@@ -1,174 +0,0 @@
-# Graphics library audit: surfaces and built environments
-
-> Historical working notes from the development snapshot (2026-09-23). The per-module test files
-> and case counts cited below were folded into `tests/scene_runtime/lib/test_library.py` when the
-> library landed on main (D96, D97); `/tmp/...` evidence paths are from that session and are not kept.
-
-Audit date: 2026-09-23, starting at approximately 07:27 UTC. This is a read-only assessment of the current worktree, including its uncommitted refinements. No shipped module, gallery source, video or delivered package was changed during this phase.
-
-## Evidence and scope
-
-All 15 assigned modules and their exports/tests were inspected. The focused suite passed **185 tests in 13.10 seconds**:
-
-```bash
-python -m pytest tests/scene_runtime/lib/test_{aging,building,finish,materials,neon,roadway,rock,sand,signage,strata,surface_wear,terrain,terrain_shade,urban,windows}.py -q -n 2 -m 'not live'
-```
-
-The frozen source and evidence directory is `/tmp/graphics-seven-hour/baseline/surfaces/`:
-
-- `src/lib/`: complete baseline library snapshot; `source_hashes.json` records every module digest.
-- `src/scene.js`: material palette, metallic weathering and combined terrain/road study.
-- `renders/material_close_t0.png`, `material_palette_t0.png`, `metal_weathering_t0.png`, `terrain_road_t0.png`: real 1440 × 810 GPU frames.
-- `architecture/src/scene.js` and `architecture/renders/`: cottage, block, tower, window interiors, curtain wall, billboard and power-line study; three 1440 × 810 views.
-- `finish/` and `neon/`: staged GPU examples derived from existing test fixtures. The neon staging moves the tubes in front of the wall; the original compile fixture hides them behind it. This fixture correction does not change library code.
-- `reproductions.json`: numerical option, patch-cloning and surface-sampling failures described below.
-
-The production host ran on the RTX 5090 Laptop GPU with its normal post-processing chain. Material/terrain, architecture and finish renders reported zero console/shader errors. Neon also renders at t=0 and t=1. Images were visually inspected; passing shader tests is not treated as proof of realism. Initial fixture imports through an external symlink were rejected by the workspace server; copying the frozen libraries into those workspaces resolved that staging issue.
-
-## Highest-value corrections
-
-### P1: weathering must change the local BRDF, not the entire material
-
-`aging.js:126,267,385`, `surface_wear.js:217`, `roadway.js:208,413,533` and `strata.js:396` retain whole-material `composeRoughness` adjustments. Several comments still describe per-pixel roughness/metalness as unreachable. Those hooks now exist in `shader.js:726,732`, and `shader.js:825` explicitly recommends them for partial coverage.
-
-Reproduction: applying full rust to metalness 1 / roughness 0.2 leaves metalness at **1** and changes roughness everywhere to **0.32**. Setting the live `uRustAmt` uniform to zero leaves roughness at **0.32**. A clean region therefore loses its original finish, an oxide patch continues reflecting as metal, and animating coverage does not restore the original physical response. The GPU weathering frame shows this limitation on identical cylinders.
-
-Fix: use the same spatial mask for colour, roughness, metalness and bounded surface-normal relief. Preserve clean substrate values exactly; rust and dust should become dielectrics only under their masks. Add final-frame comparisons under a moving specular highlight and a uniform-zero regression. Existing tests which assert global roughness multiplication encode the old limitation and must be deliberately replaced, not blindly preserved.
-
-### P1: wrong transformed normals affect several whole families
-
-`shader.js:777` (`worldBody`) transforms a normal with `modelMatrix` and `instanceMatrix`, rather than their inverse transpose. Direct copies also occur in `roadway.js:71`, `neon.js:454` and `urban.js:71`. Position transforms are correctly included; the problem is specifically normals under nonuniform scale.
-
-For a 45-degree normal and scale `[4,1,1]`, the helper produces approximately `[0.970,0.243,0]` while the correct result is `[0.243,0.970,0]`. That reverses the interpretation of a nearly horizontal surface into a steep slope. Snow, dust, erosion, triplanar weights, edge wear and spill lighting can all be affected.
-
-Fix centrally with a shared normal-transform helper, including instances. Verify GPU equivalence between scaling geometry in advance and applying the equivalent object/instance transform. Coordinate this with the shared-shader owner; fixing only one material family leaves contradictory surface masks.
-
-### P1: material names currently promise structures they do not generate
-
-`materials.js:253–300` makes brick, cobble, fabric, granite and most other presets from the same generic value-noise texture builder. Only palette, noise scale, streak strength and scalar PBR values distinguish them. The close GPU palette confirms that brick has no courses/mortar, cobble has no individual stones, and fabric has no woven structure. These are coherent noise swatches, not reusable close-view material models.
-
-Fix selected existing factories before adding parallel aliases: periodic masonry courses and recessed mortar; irregular cobble cells with physically scaled joints; filtered warp/weft normal and roughness structure; multi-scale wood grain and pores. Keep caching and deterministic variation, with explicit metre scale and an opt-out for generic distant materials. Use close and grazing renders, plus seam/scale tests.
-
-### P1: seating functions disagree with their actual meshes
-
-`terrain.js:55–69` returns the continuous field while rendering a triangulated approximation. `terrain.js:253` similarly returns analytic cliff depth instead of the rendered triangle intersection. The current tests establish agreement at vertices, which does not establish agreement between vertices.
-
-Measured with raycasts at 200 deterministic positions:
-
-| Configuration | Maximum absolute error | Mean absolute error |
-| --- | ---: | ---: |
-| Ground: size 100, relief 6, scale 12, 8 segments | 2.677 m | 0.834 m |
-| Same ground, 32 segments | 0.899 m | 0.205 m |
-| Same ground, 128 segments | 0.166 m | 0.017 m |
-| Cliff: length 20, height 8, relief 2 | 0.783 m | Not aggregated |
-
-Fix with barycentric interpolation of the actual grid triangles, while retaining the analytic field privately for construction. `sand.js:123` already implements the appropriate pattern and its current contract should be preserved. A normal sampler would also let props sit flush with inclined surfaces.
-
-### P1/P2: material option and composition defects
-
-- **Confirmed option bug:** `materials.js:241–248` unconditionally restores `bumpMap` when `repeat != 1`, overriding `bump: 0`. The reproduction returns `bumpZero=true` and `bumpZeroRepeat=false`.
-- **Confirmed composition loss:** `materials.js:379` (`tint`) clones materials without preserving `onBeforeCompile`; a previously patched material loses its procedural shader. `weather()` has the same clone path for shared materials. `windows.js:379` knowingly clears an existing shared material's patch chain before adding windows. Decide on one supported clone-before-patch or patch-aware-clone contract, then test actual compiled output. Do not silently advertise arbitrary chaining through these mutators.
-- **Sharp-edge limitation:** `surface_wear.js:238` estimates curvature from interpolated normal derivatives. Hard BoxGeometry faces have constant normals, so the effect cannot reliably discover their geometric edges. A bevel/curvature attribute or an explicit edge-distance input is needed for architectural edge chipping; a larger strength parameter is not a remedy.
-
-## Per-module disposition
-
-Priorities: P1 fixes materially incorrect behaviour or a major reusable realism gap; P2 is a bounded enhancement; keep means retain the working capability while addressing shared fixes.
-
-| Module and exports | Current evidence / limitations | Disposition |
-| --- | --- | --- |
-| `aging.js`: `patchDripStains`, `patchRust`, `patchDust` | 11 tests; gravity-oriented, seeded, multi-tone masks are already implemented. GPU rust is a metallic stain; local mask does not control BRDF. Live strength does not undo global roughness. | **P1:** local dielectric/roughness/normal masks. Preserve spatial logic and explicit sill `from`. |
-| `building.js`: `block`, `casement`, `cottage`, `tower`, `roofClutter`, `cityFabric` | 34 tests cover real openings, reveals, glazing, anchoring, dormers, budgets and district layout. GPU cottage/block geometry reads clearly. Roof remains a smooth mottled terracotta sheet; wall structure inherits generic material shortcomings. | **P2:** tile/shingle relief and intentional construction details. Keep opening, placement and merge architecture; improve underlying materials first. |
-| `finish.js`: `patchTranslucency`, `patchIridescence` | 13 tests including real chained shader compilation. GPU thin shell lights successfully; film produces coloured interference-like regions. Iridescence is an analytic light/colour approximation, not a proper layered physical coating, and documentation recommends reducing metalness to make it visible. | **P2:** evaluate Three Physical iridescence/coating support for reflective metal, keep the current lightweight thin-transmission option. Add shadow/occluder and angular tests before stronger physical claims. |
-| `materials.js`: 16 opaque preset factories; `water`, `glass`; `noiseTexture`, `weather`, `tint` | 11 tests verify cache, colours, tiling and dielectric flags. GPU palette exposes missing material-specific structures. Repeat/bump and shader-clone defects reproduced. Glass uses alpha transparency; the water helper is a simple legacy surface. | **P1:** targeted structured materials and option/composition fixes. Preserve caching. Do not confuse legacy `water()` with the richer ocean/stream modules. |
-| `neon.js`: `makeNeonTube`, `patchNeonSpill`, `makeLightTrails` | 16 tests, tube transport frames, time-driven gas variation and depth-pass exclusions exist. Source fixture's tubes were hidden behind its wall; baseline staging corrects that. Spill has the nonuniform-normal bug. Animated factories expose legacy `tick`, not the newer `update`/owned-dispose contract. | **P1 shared normal fix; P2** lifecycle aliases and owned cleanup. Keep tube geometry and colour budgeting unless matched visible renders justify changes. |
-| `roadway.js`: `patchRoadSurface`, `patchSeamBand`, `patchTracks` | 13 tests establish lane frame, filtered grain, bounded seams and track direction. GPU road remains flat shaded lanes/streaks, with no rut/aggregate normal relief. All patches use global roughness. | **P1:** physically coupled local damp/rut/aggregate masks and normal relief; retain road-coordinate framing. Geometry displacement should be optional and bounded. |
-| `rock.js`: `makeRock`, `makeRockField` | 6 tests cover closed topology, determinism, concavity, disposal ownership and GPU pixels. Current source already includes multi-scale fractures and subdued mineral shading from the prior refinement. Some broad faces still read as processed polygons; high detail can be expensive. | **P2:** lower-cost LOD/prototypes, edge/chip hierarchy and geologically coherent fracture sets. Preserve current closed shell, size/burial and owned cleanup; do not restart with a noisy sphere. |
-| `sand.js`: `makeSandTerrain` | 5 tests; asymmetric dunes, directional analytic ripples, grains, actual-triangle height sampling and owned cleanup already exist in current source. Dunes are static, fairly coherent parallel ridges. | **Keep core. P2:** optional multi-direction dune fields and sheltered deposition, with meaningful geometry variation. No new sampling repair is needed here. |
-| `signage.js`: `loadHelvetiker`, `makeText` | 9 tests; shipped local font, extruded/bevelled geometry, darkening-only colour variation, actual glyph shadows and practical lighting. Labels rendered successfully in the material baseline. Resource lifetime remains caller-managed. | **Keep first phase. P2:** idempotent owned disposal and optional material-safe text variants if integration needs them. A font-loader rewrite or cosmetic recolouring is not justified. |
-| `strata.js`: `patchRockStrata`, `patchErosionStreaks` | 13 tests; nonperiodic beds, tilted altitude frame, fall-line erosion and anti-aliasing are implemented. GPU strata/erosion have useful colour structure but largely look painted over the coarse cliff. Erosion globally polishes the surface. | **P1/P2:** local washed-region roughness and bounded relief tied to existing masks. Keep nonperiodic stratigraphy, filtering and fall-line logic. |
-| `surface_wear.js`: `patchMicroBreakup`, `patchEdgeWear` | 11 tests including instance positions, physical curvature scale and filtering. Microbreakup is useful. Hard-face edges are not recoverable from smooth curvature derivatives; scalar polishing changes unworn areas. | **P1:** local finish/substrate response and supported curvature/edge inputs. Keep scale-aware anti-aliasing. |
-| `terrain.js`: `ground`, `cliff` | 8 tests; real displaced geometry, shared-material isolation and connected cliff ribbon already exist. Sampling mismatch reproduced. Default missing PRNG silently creates a constant lattice despite documentation saying required. Cliff strata changes can be abrupt and its base mesh has no thickness/back. | **P1:** exact triangle sampling and explicit input handling. **P2:** cliff depth/edge closure options and improved multiscale terrain; preserve authored origin. |
-| `terrain_shade.js`: `patchTriplanar`, `patchSlopeSplat` | 11 tests; UV-free world projection, slope/altitude gating, patch composition and snow opt-in work. Only albedo changes; grass, scree, rock and snow share the substrate's normal/roughness response. Shared normal-transform defect changes classification under scale. | **P1:** central transform repair and coupled per-zone physical channels. **P2:** optional texture triplets/normal blending instead of only procedural colour. |
-| `urban.js`: `patchCurtainWall`, `makePowerLines`, `makeBillboard` | 11 tests. True catenary cables, pixel-width filtering, poster texture and optional practical spill are present. GPU curtain wall looks like a flat grid with synthetic sky colours; this is a distant-facade approximation. Billboards are bright even in the day fixture with `lit:true`; current `ambient` is author-supplied. | **P1 shared normal fix; P2** richer close-facade roughness/reflection variation, lifecycle ownership, viewport updates. Keep catenary and filtered cable rendering. |
-| `windows.js`: `patchWindowInteriors`, `makeNightWindows` | 13 tests; room-box parallax, stable room hashes, occupancy, furniture/blinds and pane size gates exist. GPU window room depth is visible. Real glass thickness/refraction is not provided. Cloning shared facade material can remove earlier patches. | **P1 composition contract; otherwise keep. P2** interior atlas/room variety and optional physical foreground glazing. Avoid replacing effective far-view parallax with thousands of interior meshes. |
-
-## New capabilities with a distinct purpose
-
-1. **Fractured ice:** a closed, locally transformed mesh with seeded crack planes, frost/clear-ice masks, physical absorption/transmission and a bounded internal-scattering approximation. It fills a missing material/geometry family. Validate silhouette, topology, background distortion, thickness response and offscreen limitations.
-2. **Geometric snow caps and drifts:** complement existing `accumulation.patchSnow`, which is a surface patch, with actual overhang/ledge accumulation and a sampler. Reuse snow masks and shared wind inputs rather than adding a second colour-only snow shader. Test grounding, cap thickness, directional accumulation and disposal.
-3. **Projected surface marks:** a reusable decal API for cracks, paint loss, puddle boundaries, markings and localized stains, with metre scale, normal/roughness contribution, controlled depth bias and resource ownership. This supplies authored locality that world-noise patches cannot express. Reuse existing road tracks rather than duplicate them.
-4. **Cooling lava/crust:** a bounded animated flow surface with real crust plates or displaced lobes, emissive fissures, temporal crust formation and restrained heat shimmer. Useful after shared material channels are correct; clearly distinguish the visual approximation from fluid/thermal simulation.
-
-For this work window, structured masonry/fabric plus correct local weathering should precede adding four unrelated new modules. Fractured ice is the strongest independent new effect candidate; geometric snow is a compatible second candidate if the accumulation owner agrees.
-
-## Validation plan for the coordinated implementation
-
-- Keep these baseline workspaces fixed and render matched cameras after one library change at a time.
-- Add nonuniform object/instance scale equivalence checks to the shared normal code and direct-copy users.
-- Compare source height/face samplers against actual triangle raycasts at interior points, including low resolution.
-- Exercise roughness/metalness mask response with coverage zero/full and a moving highlight; do not merely inspect generated GLSL text.
-- Add true material structure tests: brick course dimensions/mortar, cobble boundaries, weave direction, filtering and tiling.
-- Retain all existing topology, determinism, cache, palette, authored-origin and disposal tests unless an explicitly changed contract makes a test obsolete.
-- Add final-frame tests for reused compile fixtures where geometry was previously occluded, especially neon.
-- Record construction cost, draw calls, triangles, GPU time and retained resources for any new instanced or transmissive effect. Compilation alone is not a quality verdict.
-
-No model calls were made. Implementation ownership and any shared shader/API changes require coordination with the root task before editing modules.
-
-## Coordinated implementation checkpoint: 08:10 UTC
-
-The read-only baseline above remains frozen. The authorized implementation now fixes the following existing contracts:
-
-- Rust, dust and drip deposits use their own coverage for roughness and dielectric metalness. Rust has multiscale corrosion islands and millimetre surface-gradient relief, filtered by pixel footprint. Clean substrate and live strength zero retain the original optical values.
-- Micro breakup, edge polish, road ruts, gutters, collected grit, pressed tracks, erosion runs and curtain-wall glass now modify their local roughness masks rather than the entire material. Curtain mullions keep their substrate finish.
-- Roadway, neon spill, windows and curtain walls use the shared inverse-transpose normal helper. Other world-surface patches inherit the corrected shared helper.
-- Brick has offset courses, mortar and chipped bevel height; cobble has seeded irregular stone cells and recessed sediment; fabric has alternating over/under yarn relief. The structured height and roughness map are linear data, separate from sRGB albedo. All material textures now use linear filtering and mipmaps. These remain UV materials: authors control physical tile scale through UVs/repeat; they are not geometry displacement or a replacement for foreground masonry meshes.
-- Texture repeat preserves `bump: 0` and custom bump maps. Tint, weather, ground and night-window cloning preserve registered Astra shader patches and typed independent uniforms while borrowing texture identities. Cache keys track source material version.
-- Ground and cliff placement samplers interpolate the actual rendered triangles, including off-vertex positions and transformed parents. Flat cliffs no longer produce nonfinite vertex colors.
-- Building factories, roof furniture, text, neon, light trails, power lines, billboards, terrain and cloned night-window materials expose idempotent cleanup of construction-owned resources. Cached materials, borrowed textures, supplied materials and later attachments remain alive. Animated neon/power-line/billboard helpers expose `update` alongside the existing `tick` alias.
-- Rock and sand now register their normal relief through the shared normal hook, so patch-preserving clones retain that relief too. Their closed rock topology and exact sand sampler remain intact.
-
-The 15-module test set now contains **196 tests**. The combined run passed 195 and exposed one old normal-spelling assertion in `test_terrain_shade`; updating it to the shared helper made its complete 11-test file pass. All changed Python tests pass Ruff. Tests added here cover off-vertex raycasts, zero-relief finiteness, shared resource ownership, material map registration, weave ordering, filtering, disabled/custom bumps, typed shader cloning and actual GPU optical factors.
-
-The GPU rust probe found 5,388 covered and 9,365 uncovered pixels: every covered pixel became rougher, uncovered roughness stayed at 0.2, and metalness equaled one minus coverage within one 8-bit level. Setting strength to zero restored the base factors within the same tolerance. The complete shader compiled with pre-existing bump and normal maps as well.
-
-Matched 1440 × 810 renders now live under `/tmp/graphics-seven-hour/after/surfaces/`, using the same baseline scene code and cameras. All ten frames across the palette/weathering/terrain, architecture, finish and neon studies rendered on the GPU with zero shader or console errors. These images were inspected. Masonry structure is now visible; larger architectural massing and the legacy generic wood/granite presets still have the limitations described above. The images are diagnostic fixtures, not a claim that a cube palette is a finished environment. A composed ice/shoreline study follows as the approved new capability.
-
-
-## Existing-family freeze: 09:20 UTC
-
-The coordinated surface pass is frozen for review under `/tmp/graphics-seven-hour/surfaces-final/`, with source hashes and a compact `validation.json`. It reuses the original palette, architecture, finish and visible-neon fixture scenes and cameras. All ten 1440 × 810 frames rendered on the real GPU with zero console or shader errors and were visually inspected. The complete owned test set now passes **208 tests** (199 existing-family tests and nine ice tests), and Ruff passes.
-
-Additional work after the earlier checkpoint:
-
-- `roadway.js` supplies filtered metric normal relief for aggregate, wheel ruts, seam grit, pressed tread and raised track rims. Each fine octave fades by its own wavelength. Repair masks use ordered `smoothstep` edges. The GPU regression measures perturbed normals, exact restoration at live depth zero and preservation of an existing normal map. This is normal relief; silhouettes and collision meshes remain unchanged.
-- `terrain_shade.js` filters each procedural octave by pixel footprint. Triplanar mineral shading now has `relief` in metres (default 0.002, zero disables) and `roughness` (default 0.86). Slope splats use independently configurable grass/scree/rock/snow roughness and dielectric metalness. A GPU readback verifies the actual zone values after both patches compose. Shared transformed normals remain the basis for zone classification.
-- `materials.js` adds coherent longitudinal wood grain, bent growth rings and seeded knots to weathered and painted wood, with matching linear height and roughness. Grain follows UV +V. Painted relief is smaller than weathered relief; default bump heights are 0.0015 m and 0.006 m. The structured brick/cobble/fabric/wood maps are now 512 square with mipmaps. Contrast, grain scale and streak options affect this path, and explicit external color maps do not acquire unrelated procedural mortar. Tests check weave ordering, grain anisotropy, texture seams, cache sharing, option behavior and custom map preservation.
-- `aging.js` separates corrosion islands, centimetre flakes and filtered millimetre grain; the coarse pixel-sized rust relief exposed by a close cylinder study was reduced. The original coverage, clean-substrate optics and strength-zero guarantees remain tested.
-
-Final disposition of the original 15 modules: `aging`, `building`, `materials`, `neon`, `roadway`, `rock`, `sand`, `signage`, `strata`, `surface_wear`, `terrain`, `terrain_shade`, `urban` and `windows` received the fixes above or the earlier ownership/transform/composition fixes. `finish` retains its working lightweight effects and explicitly remains an optical approximation; its matched GPU scene and complete tests passed. None of these effects is declared physically exact. The earlier per-module table retains the remaining limitations, including distant facade approximations, flat patch silhouettes and unmodelled architectural construction detail.
-
-A composed workshop study lives at `examples/graphics_lab/scenes/workshop.js` and `/tmp/graphics-seven-hour/workshop-study/`. Four close and wide GPU views expose real masonry scale, cloth, aligned board grain, worn metal, pavement and road response. Its previous structured-material snapshot remains at `/tmp/graphics-seven-hour/workshop-structure-before/`. The study revealed that a flat cobble material cannot provide foreground stone silhouettes or contact; a separately scoped geometric paving capability is approved next rather than increasing bump amplitude.
-
-## New capability: fractured freshwater ice
-
-`ice.js` exports `makeFracturedIce`. Each seeded cell is a closed, bevelled volume with a nominal local upper surface at zero, variable thickness, optional heave, a physically transmissive material, filtered frost and stress cracks, and true instanced air lenses inside the solid. Authored convex outlines are supported. `userData.sampleHeight(x,z)` queries actual Float32 upper triangles and returns null in fissures or outside; `update` is static, and disposal releases only construction-owned geometry, materials, instances and the optical texture.
-
-The shared fracture deformation runs before gaps are opened. A floe is shrunk toward a point inside its polygon visibility kernel, so neighboring outlines fit and subsequent side-ring cuts remain inward. This corrected an overlap defect that closed-manifold checks alone missed. The regression covers twelve seed/gap combinations down to 2 mm, in addition to closed topology, positive volume, determinism, transformed raycast agreement, internal-air containment, input validation, resource ownership and GPU compilation. An actual checker transmission render verifies thickness-dependent colored absorption and reduced background contrast through frost.
-
-The composed frozen-shoreline study is `examples/graphics_lab/scenes/ice.js`, staged at `/tmp/graphics-seven-hour/ice-study/`, with three fixed 1440 × 810 views. A previous visual checkpoint is preserved at `/tmp/graphics-seven-hour/ice-study-v1/`. Root independently reviewed the updated sheet, submerged objects and shoreline as suitable for integration. The pressure ridge is now visibly tilted and seated against a frost-covered lower floe and the main sheet, using actual transformed vertex contact. All three final GPU views are clean and visually inspected; the immutable source/image snapshot is `/tmp/graphics-seven-hour/ice-final/`.
-
-Limits: optical path uses local top/bottom thickness and an estimated floe width on side faces, not an exact exit intersection. Three transmission sees the opaque scene and does not recursively trace transparent water or another ice volume. The fracture network is a seeded visual model, not a mechanical fracture simulation; very small degenerate chips can be omitted. The exposed pressure slab still has a broadly flat top and geometric fracture bands, and frost distribution could gain finer directional crystal structure in a future polish pass. Large bubbles are individually instanced geometry; at the shoreline study's chosen area/density, the main ice group represents about 174,000 triangles including its air lenses, in two meshes. The complete scenic fixture, including terrain and many unique rocks, is about 805,000 triangles; its observed 130–211 FPS range on the RTX 5090 Laptop GPU is environment-specific, not a portable performance guarantee.
-
-## New capability: geometric paving
-
-`paving.js` exports `makePaving({size, stoneSize, pattern, joint, thickness, relief, seed, color, jointColor, roughness, moisture, name})`. `pattern` selects irregular cobbles or staggered rectangular setts. Units are metres; the nominal walking surface is local y=0, its underside is `-thickness`, and `relief` varies stone height and tilt. The returned named Group has two merged meshes, a static `update`, idempotent construction-owned `dispose`, and `sampleHeight(x,z)` over the exact Float32 upper triangles and recessed joint bed. Queries outside the rectangular patch return null. Requested density is bounded at 4,096 stones by making oversized patches coarser; this is foreground geometry, not a terrain streaming system.
-
-Every stone is a closed solid with trimmed corners, cut bevels, minor chipped edge variation, an intrinsic crown and restrained seeded color variation. The gap is formed by inward clipping of disjoint cells; corners and subsequent rings remain inside their stone footprint. The initial rendered version looked soft and pale, so the accepted version reduced crown/bevel width, retained cut-face normal discontinuities and used a darker mineral base. Fine normal grain fades with pixel footprint. Moisture darkens the albedo and lowers roughness together while metalness remains zero; this is a damp stone finish, not a reflective puddle layer.
-
-Matched evidence is preserved at `/tmp/graphics-seven-hour/workshop-paving-before/` and `/tmp/graphics-seven-hour/paving-final/`. The earlier rounded-stone iteration is `/tmp/graphics-seven-hour/workshop-paving-after-v1/`. The same four 1440 × 810 cameras show the material-only yard before and the real stone yard after. The only accompanying assembly correction was marking authored mounted parts as free placement: the runtime had lowered the wall sign backing by 0.251 m and one interior timber by 0.17 m. The final fixture reports zero automatic placement moves. All four final views were inspected. Dry/wet cobble/setts diagnostic panels are additionally rendered and inspected under `/tmp/graphics-seven-hour/paving-variants/`.
-
-Eight focused tests cover closed positive-volume stones, bounds, deterministic geometry/color, noncrossing footprints, exact raycast sampling through stones and joints under nested transforms, owned cleanup, bounded construction, actual GPU compilation with fog/shadows/normal maps/cloned patches, and GPU optical-channel readback. The moisture probe verifies roughness changing from approximately 0.84 to 0.30, an albedo multiplier near 0.63 and zero metallic response. A particularly useful regression exposed Three's transformed bounding-sphere underestimate under shear: direct local triangle intersection agreed with the sampler, but the world raycast skipped a real stone-edge hit. Paving uses conservative sphere radii to avoid that early cull while retaining exact bounding boxes.
-
-The workshop's 6.9 × 11 m patch contains 1,334 stones and 124,588 triangles in two meshes, using about 3.09 MB of geometry arrays. One measured Node construction took 138 ms; 10,000 height queries took 13 ms. The complete workshop rendered 225–269 FPS on the RTX 5090 Laptop GPU, with 128 draw calls and 147,128 triangles, no shader/console/update errors. These are hardware-specific observations. The final complete owned test run passes **216 tests**: 199 existing-family tests, nine ice tests and eight paving tests. Python test lint passes.
-
-Remaining limits: this is cut-stone paving with a generic procedural mineral finish, not a scan library or a geology simulator. Rectangular patches do not yet conform to arbitrary curved paths or a caller-provided heightfield, and wetness supplies no standing-water optics. The workshop is a composed material study; its simplified building envelope, flat UV brick faces and procedural rust grading remain visible and are not presented as a finished photoreal environment. The original fifteen-module audit and matched fixtures remain frozen independently of this added capability.
diff --git a/harness/docs/graphics_audit_weather.md b/harness/docs/graphics_audit_weather.md
deleted file mode 100644
index 7f99db4f..00000000
--- a/harness/docs/graphics_audit_weather.md
+++ /dev/null
@@ -1,125 +0,0 @@
-# Weather, water, and light effects audit
-
-> Historical working notes from the development snapshot (2026-09-23). The per-module test files
-> and case counts cited below were folded into `tests/scene_runtime/lib/test_library.py` when the
-> library landed on main (D96, D97); `/tmp/...` evidence paths are from that session and are not kept.
-
-Audit owner: water_library. Baseline captured 2026-09-23, starting 07:27 UTC. The initial findings below describe the preserved baseline. The implementation ledger at the end records subsequent changes and distinguishes completed work from the remaining proposals.
-
-## Evidence and method
-
-The source snapshot, matching test files, executable lighting probe, staged scenes, original PNG frames, and render metrics are under `/tmp/graphics-seven-hour/baseline/weather/`. The snapshot contains the complete library to make every scene reproducible. The two kinds of scenes are deliberately separated:
-
-- `fixtures/<module>` renders the module's existing shader fixture. These primarily establish compilation and basic behavior; several fixtures have black backgrounds or no environment and are unsuitable for judging final composition.
-- `representative/<case>` adds controlled daytime or night lighting, a physical sky, an environment, and useful geometry. `surface_patches` compares individual material effects on a floor, box and spheres; `cloud_sky` exposes distant cloud silhouettes; `rain_shelter` exposes rainfall around and underneath a roof; `heat_shimmer` provides a structured background.
-
-Renders use the actual production GPU host with its default postprocessing, 960 × 600, absolute times 0 and 1.5 seconds. Metrics identify the RTX 5090 Laptop GPU through ANGLE. The image `audit-contact.jpg` is an overview, not the sole evidence: individual images were also inspected. Initial staging failures from symlink restrictions and unexpanded fixture `__FOG__` tokens were corrected in temporary staging; they were not library failures. The completed renders have no console or shader errors. The 15 corresponding test files pass: **182 tests in 23.90 seconds**. This does not establish visual realism. The final evidence inventory contains **46 PNG frames across 14 staged render scenes**, with hashes in `manifest.json`.
-
-Priorities: **P1** is a clear visual or correctness defect worth addressing in this work period; **P2** is a useful improvement with a functioning existing implementation; **P3 / retain** means no immediate replacement is justified by the inspected evidence.
-
-## Module findings
-
-| Module | Public exports | Evidence and current strengths | Main limitations or defects | Priority and concrete proposal |
-|---|---|---|---|---|
-| `accumulation.js` | `patchSnow`, `patchSand` | `representative/surface_patches/renders/snow_t0.png`, `sand_t0.png`; slope, wind and curvature masks work and preserve the underlying material outside their masks. Seeded patterns and distance filtering are already present. | Snow reads as blue marbling on a flat coating; it creates no thickness or silhouette. Both effects change material-wide roughness despite local coverage. Snow thaw and sand height are anchored to the world origin, which is useful only when explicitly understood. | **P2.** Improve snow luminance and granular breakup, add masked roughness/normal treatment using existing patch hooks, and document coating-only geometry. Add a separate optional snow-cap mesh API only if geometric deposits are prioritized. |
-| `atmosphere.js` | `makeHeightFog`, `patchAerialPerspective` | `fixtures/atmosphere/renders/a_t0.png`; Beer extinction per sheet correctly avoids constant-opacity near fog. Terrain-following sheets and depth-prepass exclusion are already implemented. | Fog is 20 horizontal surfaces, not a continuous volume: oblique/inside views and intersections can reveal layers. Scene lighting is read only at construction; hidden lights are included and directional targets/parent transforms are ignored. Aerial perspective modifies albedo before lighting, so it does not represent final-radiance scattering. | **P1 correctness, P2 appearance.** Use visible world-space light directions, define refresh behavior, and retain the cheap height-fog mode. A depth-aware analytic or bounded raymarched fog option would be a genuine new capability; do not claim the existing sheets are volumetric ray integration. |
-| `caustics.js` | `patchCaustics` | `representative/surface_patches/renders/caustics_t0.png` and time 1.5; connected moving light webs cross floors and curved geometry, with Snell direction shift, depth extinction and antialiasing. This is one of the stronger existing effects. | Emissive caustics are procedural projection, independent of an actual water surface and scene occluders. They can illuminate a surface even when the source path is blocked. The pattern and hue breakup are artistic rather than a focused-ray solution. | **P3 / retain core.** Keep the useful lightweight projector, document its unoccluded/procedural scope, and consider a shadow-aware opt-in if a pool showcase demonstrates the need. Do not replace it merely to increase effect count. |
-| `celestial.js` | `makeHeatShimmer`, `makeStars`, `makeAurora` | `representative/night_sky/renders/night_t0.png` and `representative/heat_shimmer/renders/heat_t0.png`; actual framebuffer distortion exists, and seeded sky fields animate. | Aurora has conspicuously uniform narrow vertical bars and a repeated wavy curtain hem. Shimmer's framebuffer/texture are hidden in a closure with no final teardown; target dimensions are taken from drawing-buffer size rather than the active render target. A color-only distortion cannot reject foreground sampling. | **P1 lifecycle/RTT correctness; P2 aurora.** Expose owned-resource disposal, use current-target dimensions and restore GL bindings safely. Make aurora ray spacing, lengths and curtain luminosity less regular. Preserve truthful color-only distortion limitations. |
-| `clouds.js` | `cloudTexture`, `makeClouds`, `makeCirrus` | `representative/cloud_sky/renders/clouds_t0.png` and `clouds_side_t0.png`; inexpensive instanced layer, directional rim response and bounded haze. | Cumulus appear as repeated gray outlined discs; clusters do not produce convincing volume or internal shadow. Cirrus are stretched versions of the same puff, producing conspicuous horizontal parallel lines. Billboards change their apparent body with camera orientation; no true volume or light transmittance. | **P1 visual.** Reduce the uniform perimeter highlight, generate non-identical billowy density masks, and give cirrus its own filament field. Highest-value new capability: a separately named bounded cloud volume with raymarching, extinction and self-shadowing, with explicit performance tiers. |
-| `damp.js` | `patchMoss`, `patchMoisture`, `patchCrackedMud` | `representative/surface_patches/renders/moss_t0.png`, `mud_t0.png`, `shore_t0.png`; directional moss placement and a coherent moisture apron already work. | Moss is a sparse flat green coating at close range. Mud has extremely dark, relatively uniform-width graphic outlines without actual curl/normal relief. Roughness changes affect the whole material. Moisture reach is world-Y height, not distance from a shoreline. | **P2.** Add pixel-filtered micro-normal and masked roughness; reduce the uniform crack outline and derive lip normals from the existing cell border. Retain the height-based moisture API but keep its meaning explicit. |
-| `godrays.js` | `makeGodRays` | `fixtures/godrays/renders/a_t0.png`; several beams read as solid illuminated tubes. Shaft/pool/mote intensity budgets and depth-prepass exclusion already exist. | Confirmed source-space mismatch: `vN` uses `normalMatrix` (view space) but `eye` is `cameraPosition - vW` (world space) before `astraFacing`. No scene occlusion clips a beam; a floor pool assumes the local ground plane. Geometry is a shell with approximate chord weighting, not a scattering volume. | **P1 correctness and visual.** Correct the coordinate space first and compare identical views. Then soften/unstructure the beam cross section and expose an optional authored blocker/length constraint; a separate shadow-aware volume is larger work. |
-| `rain.js` | `makeRain`, `splashTexture`, `makeSplashes`, `wetten`, `makePuddle` | `representative/rain_shelter/renders/rain_shelter_t0.png`, `under_roof_t0.png`; streaks, surface-oriented splash atlases, and real animated puddle geometry are available. Splash placement already raycasts caller-provided static surfaces. | Falling streaks do not stop at roofs/terrain; impact phases are independent of the visible falling drops. Impact positions stay baked when receiving objects move. Rain uses world camera coordinates inside a model-space vertex path. `makePuddle` updates every vertex and recomputes normals on CPU; amplitude zero divides color calculation by zero (executable probe: all 2,352 color components become nonfinite). | **P1 finite/transform correctness; P2 coherence.** Fix zero-amplitude and coordinate contracts. A valuable new rain-field API can couple deterministic trajectories to a static terrain/roof height map and synchronize impact births; retain the cheaper existing layers. Bound moving-collider support honestly. |
-| `sky.js` | `SKY_GRADE`, `nightAmount`, `afterglowAmount`, `lowSunAmount`, `skyRadiance`, `makeSky` | Day `cloud_sky`, night `night_sky`, and existing CPU radiance tests; the graded physical sky is a sound base and shares conventions with `sunRig`. | Creation clones a direction and derives twilight uniforms once: changing a rig later does not update the dome, and changing only `sunPosition` leaves derived twilight terms stale. Dome/environment mismatch is possible when custom sky parameters are used without rebaking the environment. | **P3 / retain appearance; P2 API.** Add an explicit update-sun setter that recomputes all derived terms, plus clear instructions for environment refresh. A wholesale atmospheric-scattering rewrite is lower value than cloud/fog repairs in this time budget. |
-| `submerged.js` | `patchUnderwater`, `makeRainRings`, `patchThinIce` | `representative/surface_patches/renders/caustics_t0.png`, `ice_t0.png`; depth- and view-path extinction, procedural rings, and branching ice cracks are implemented. | Underwater extinction partly edits albedo and adds emissive veiling, without refracted scene depth. Ice looks like bright painted fractures on every shape; no interface thickness/refraction or change of silhouette. Rain rings are color overlays rather than displacement/reflection-normal changes. | **P2.** Preserve the useful absorption patch, add masked normal/roughness for ice, and offer ring normals to appropriate water materials. A real shallow-water transmission API already exists in `stream.js`; avoid duplicating it under another name. |
-| `veils.js` | `makeRainVeil`, `makeSnowfall`, `makeMotes` | `fixtures/veils/renders/a_t0.png`; deterministic snow tumble/drift and a separate distant-rain layer exist. | Rain curtain visibly exposes a straight rectangular lower edge and a regular diagonal comb. Lighting traversal includes lights below hidden ancestors; the 15-frame cache and early return when no lights remain leave stale illumination. Snowfall is not missing, but terrain/roof collision and accumulation coupling are. | **P1 veil and lighting.** Fade every card boundary, break up filament spacing, and fix visibility/reset behavior with tests. Keep snowfall/motes unless composed close views reveal further problems. Geometry-aware precipitation is more useful than a second snowfall constructor. |
-| `water.js` | `makeWaterNormals`, `BROADBAND_EXTENT_M`, `makeOcean` | `fixtures/water/renders/graze_t0.png`; inexpensive normal-animated planar water with real RTT reflections remains useful for calm pools/ponds. | Lights are sampled only once. Executable probe records `keyColor.r=1.2732395` both before and after removing the light. Hidden ancestors are ignored. `_oceans` is process-global and never decremented, causing misleading cross-scene warnings. No owned-resource disposal contract. The plane has no wave geometry; Phong glints and scrolling normal/color fields are not the newer ocean model. | **P1 lifecycle/light correctness; P3 retain visual niche.** Repair dynamic scene reading and resource ownership without replacing the API. Direct displaced-sea users to the already improved `ocean.js`; do not make legacy `makeOcean` silently become a heavy ocean simulator. |
-| `watermist.js` | `makeWaterMist`, `makeSpray` | `fixtures/watermist/renders/a_t0.png`; broad drifting mist, ballistic spray trajectories, and terrain/flow options already exist. | Mist cards can merge into a milky solid bank with no depth-aware soft intersections; source color/lighting are authored rather than live scene irradiance. Spray is deterministic visual ballistics without fluid collision. No returned disposal helper. | **P2.** Add owned-resource teardown, soften card/ground intersections within available information, and tune density under a composed waterfall or stream. A spray solver is not necessary to improve the useful visual effect. |
-| `waterside.js` | `patchShoreWet`, `patchShoreFoam`, `patchShallowWater` | `representative/surface_patches/renders/shore_t0.png`, `shallow_t0.png`; composable waterline wetting and explicit shallow-color grading exist. | Foam can appear as pale vertical stripes on curved shore objects. Wet roughness applies globally. Shallow water reduces an arbitrary `bedAt` callback to a single best-fit plane, then adds noise: channels and local shoals cannot be represented. Color grading alone supplies no transparency or refraction. | **P2.** Use local wet masks for roughness, less directional foam breakup, and an optional sampled height texture for nonlinear bed depth. Preserve current planar fallback and describe it accurately. |
-| `wetground.js` | `makeMirrorFloor` | `fixtures/wetground/renders/a_t0.png`; real reflected object and a rough dirt overlay establish a useful wet-ground base. | Reflection blur is a fixed five-tap vertical screen-space smear; ripple field is static. World normal uses `mat3(modelMatrix)` rather than inverse transpose. Reflection and generated maps have no owned disposal entry point. A second reflector conflicts with other RTT water surfaces. | **P1 ownership/normal correctness; P2 appearance.** Add teardown and correct normals; improve roughness-dependent filtering and optional time-driven rain ripples. Preserve the documented one-reflector constraint unless shared runtime recursion is deliberately addressed. |
-
-## Bounded priorities for the seven-hour work period
-
-1. Repair clear correctness and ownership defects first: hidden/removed light handling, godray coordinate mismatch, zero-amplitude puddles, framebuffer lifetime and active-target sizing. Add behavioral regressions rather than tests that only search shader strings.
-2. Improve the conspicuous existing cloud and rain-veil appearance against the preserved views. Their silhouettes are larger realism failures than missing tiny details elsewhere.
-3. Add one substantial **cloud volume** capability with a stable local-coordinate box, deterministic noise, Beer extinction, sun transmittance, a bounded ray budget and owned-resource teardown. Keep the current distant-cloud option for cheap background use. Explicitly state that this is prescribed density, not weather simulation.
-4. If the time budget permits, add **surface-aware rainfall** with a static height field and synchronized impacts. Height-field support handles terrain and roofs with a single highest surface per XZ; overhang interiors and moving geometry require stronger collision data and should not be advertised as solved.
-5. Improve material coating realism using masked roughness and filtered normal detail where the existing geometry is already adequate. Do not spend the entire period rewriting all 15 modules, or confuse snow albedo with accumulated snow geometry.
-
-Deferred capabilities with genuine value are depth-aware participating-media lighting and geometric snow caps. Existing snowfall, spray, caustic projection, aurora, stars, rain rings, heat shimmer and puddles should not be relabeled as missing new effects.
-
-## Scope and verification limits
-
-Every assigned module's implementation and corresponding test coverage were inspected for its public API and rendering approach. Existing material patches were additionally exercised together through the real GPU host. Not every parameter combination, transform, reflection interaction or camera-inside-volume case has been exhaustively evaluated. The findings distinguish directly observed images, reproduced runtime behavior and source-derived risks. Temporary source copies and rendered baselines remain outside delivered packages and output galleries.
-
-
-## Implementation ledger — 2026-09-23, 08:58 UTC
-
-The first correctness and visual pass is implemented in source. The baseline folder remains immutable. `weather-refine/existing-matched-v2/` contains the same 14 scene sources/cameras, 960 × 600 dimensions, and absolute times 0 and 1.5: **46 after frames, no shader or console errors**. Only the assigned module files and shared `shader.js`/`lifecycle.js` repairs were replaced in those staged workspaces. `comparison.jpg` places selected original/after views beside one another. Shared normal/depth-pass fixes therefore contribute to these comparisons; they are not evidence for an individual material patch in isolation.
-
-| Module | Implemented change | Behavioral evidence and remaining scope |
-|---|---|---|
-| `accumulation` | Snow/sand roughness and metalness now follow their existing local coverage masks; the authored substrate properties stay intact. | GPU reads of actual `roughnessFactor` distinguish uncovered vertical faces from covered upward faces. Snow remains a color/material coating without geometric thickness; its blue marbling is not yet redesigned. |
-| `atmosphere` | Visible world-space directional-light probing refreshes on rendering; removed/hidden keys reset, authored pins remain respected. Added explicit refresh hook and owned disposal. | Tests change sun parent visibility/removal and target direction after construction. Height fog remains a finite sheet approximation and aerial perspective still operates inside the material patch. |
-| `caustics` | Core retained after inspection. | Existing moving projection remains useful; scene occlusion and water-derived focused rays are not implemented. |
-| `celestial` | Heat shimmer sizes its framebuffer copy from the active render target, restores GL bindings in `finally`, and releases owned GL framebuffer/texture. All factories own disposal. | Stubbed GL tests cover the target-size mismatch, throwing blit and exact cleanup counts. Stars and aurora appearance are retained in this pass; aurora's regular bars remain an open visual item. |
-| `clouds` | Replaced one repeated puff with an eight-variant density/normal atlas, removed the uniform bright ring, and gave cirrus a separate curved filament field. Card edges are transparent; camera/sun basis handles transformed parents. | Matched `cloud_sky` views show the former gray outlined discs replaced by softer lit masses. Public `cloudTexture` preserves white RGB/alpha contract. These are inexpensive distant billboards, not a substitute for the new cloud volume. |
-| `damp` | Moss, moisture and cracked mud apply roughness locally; opaque coatings suppress metalness only where covered. Wetting already polished substrate cannot increase its roughness. | GPU coverage tests verify dry substrate and polished wet surfaces. Moss/cracks remain shader detail without geometric tufting/curling. |
-| `godrays` | Facing attenuation now compares world-space view and normal vectors; owned disposal added. | Identical fixtures lose the incorrect hard-sided strips. Beams are still authored shell volumes without scene occluder integration. |
-| `rain` | Zero-amplitude puddles stay finite. Rain camera/field coordinates now agree under parents. Added an optional roof/terrain shelter atlas; all factories capture owned resources. | Atlas tests cover roofs, ground, transformed parents, camera movement, cache reuse, explicit refresh, hidden/moved source meshes, and caller ownership. GPU pixels verify that a roof cuts the rain field off. Detailed atlas contract follows below. |
-| `sky` | `setSunDirection` refreshes sun position and every derived night/afterglow/low-sun uniform atomically; sky handle and mesh own disposal. | Setter validation and day/night transitions are covered. It updates the dome only; caller-owned scene lights and baked environment still require their own update. |
-| `submerged` | Rain ring factory owns disposal. | Existing absorption and thin-ice patch behavior retained; no new refraction or water-depth buffer is claimed. |
-| `veils` | Rain fades at the lower boundary and has less regular filament spacing. Lighting reads visible objects, resets after removal, and uses a frame-bounded cache. Billboards/camera distance use the correct local basis. | Matched fixture visibly removes the straight clipped lower edge and comb. Hidden-ancestor/removal and transformed-camera tests pass. Snowfall remains visual precipitation without roof collision/accumulation. |
-| `water` | Live visible lighting resets removed contributions; no process-global water-count warning. Owns generated normals, geometry/material and the addon's private reflection target through a narrowly scoped render hook. | Actual GPU render/dispose cycles return texture counts to baseline and restore the renderer method identity. Caller-provided normal textures remain borrowed. This API remains planar calm water; displaced oceans use `ocean.js`. |
-| `watermist` | Owned disposal plus world-facing cards under rotated/nonuniformly scaled/sheared parents; world light/view vectors no longer mix with local density/ballistics. | GPU derivative-normal readback verifies both mist and spray planes under nested transforms. Gravity, flow and height callbacks are local; rotating a spray group rotates its local gravity. No depth-aware intersection or droplet collision solver. |
-| `waterside` | Wet roughness follows the actual wet mask, preserving dry regions of a shared material. | GPU dry/wet samples verify the different finishes. Shore foam and the planar approximation to `bedAt` are unchanged in this pass. |
-| `wetground` | Correct inverse-transpose world normal; explicit disposal of its reflector target, generated maps, geometry and materials. | Lifecycle tests retain caller-added children. Fixed reflection blur and static ripple limitation remain; no shared multiple-reflector integration is claimed. |
-
-All moving factories that previously exposed only `userData.tick(t)` now also expose the identical `userData.update(t)` function: height fog; stars, aurora and shimmer; godrays; rain veil, snowfall and motes; water mist and spray. Lifecycle tests call the actual factory APIs and verify shader time, disposal idempotency and protection of caller-appended children. Patch functions operate on caller-owned materials and do not take ownership of them.
-
-### New bounded cloud volume
-
-`cloudvolume.js` exports `makeCloudVolume(options)`. It returns a local, centered `THREE.Mesh` with `userData.update(t)`, `sampleDensity(x,y,z,t)`, `setSunDirection(direction)` and `dispose()`.
-
-- `size: [x,y,z]` uses local metres; default `[600,180,360]`. `wind: [x,z]` uses local metres/second and absolute time. `seed` controls a periodic 80³ RGBA density texture (2,048,000 bytes before driver allocation).
-- `coverage` and `detail` range from 0 to 1; `density` is extinction per world metre. The local-to-world path metric preserves optical thickness under nonuniform scale and composed shear.
-- `quality: 'low' | 'balanced' | 'high'` selects 40/6, 72/10 or 112/16 view/sun integration steps without changing the underlying field. Secondary sun integration supplies self-shadowing. Beer transmittance accumulates front to back; a bounded multiple-scattering approximation lifts dense interiors.
-- Lighting follows the strongest visible directional light and ambient/hemisphere/environment fill. Hidden/removed lights reset. `sunDirection` pins a world-space direction; the setter supports changes without rebaking density.
-- This is prescribed animated density, not a weather/fluid simulation. It has ordinary transparent-object sorting, no terrain cloud-shadow projection, no scene-shadow-map sampling, no temporal reconstruction, and no scene-depth-aware termination inside its bounds. Opaque geometry wholly in front works through depth testing; opaque geometry intersecting the box can reject the whole cloud fragment. Use separate distant sky volumes.
-
-`examples/graphics_lab/scenes/cloud_volume.js` composes three cloud volumes over a reflected mountain lake. Frozen final source and images are in `weather-refine/cloudvolume-final/`: lake, close cloud, and camera-inside views at 0 and 7 seconds, 1200 × 750, production postprocessing, zero shader/console errors. `cloudvolume-fractal-a/` preserves the earlier density experiment; the selected field replaces visibly smooth ellipsoid clusters with eroded multiscale structure. Tier comparisons use the exact same close camera at `cloudvolume-quality-{low,balanced,high}/`. Two-second host throughput samples were approximately 813/658/519 FPS on the RTX 5090 Laptop GPU; these are scene/device-specific short measurements, not guaranteed performance or mobile budgets.
-
-Five module tests check seeded density bytes, absolute-time replay, CPU/GPU texture sampling agreement, boundary behavior, transformed camera/light transport, hidden/removed lights, all three actual GPU programs, camera-inside rendering, foreground geometry, pixel motion/replay, and GPU 3D-texture cleanup. Exact replay compares rendered bytes, not merely uniform values.
-
-### Optional bounded rain shelter atlas
-
-`makeRain({surfaces, heightAt, groundY, shelterResolution, shelterUpdateDistance, ...})` retains its existing lightweight path when no surfaces/height callback are supplied. `surfaces` are borrowed `Object3D` roots; `heightAt(x,z)` returns a local height or `null`. `groundY` supplies an optional flat local cutoff even without an atlas.
-
-The atlas records the highest receiving height at each local XZ texel. It follows the camera when `follow` is enabled and covers the rain radius plus an update margin. Resolution is bounded to 8–64 per side (default 32): each rebuild uses at most resolution² downward ray queries, whose cost still depends on supplied mesh complexity. It rebuilds initially, after sufficient camera movement, after effect-transform changes, or on the next draw after `userData.refreshShelter()`. Moving, modifying or hiding a source mesh requires that explicit refresh. `userData.shelter` exposes bounds, texel size and rebuild count; `sampleShelterHeight(x,z)` reports cached local height or `null` outside/unbuilt coverage.
-
-The leading edge of each rain streak disappears at the highest roof/ground height. This is a vertical height-field approximation: it does not solve wind entering laterally under eaves, layered overhang interiors, moving-body collisions, or synchronization of visible drops with independently phased splash sprites. Narrow roofs can be missed between texels. The factory disposes its atlas but never source geometry/materials.
-
-`rain-shelter-matched/` preserves the original roof case with only the opt-in shelter configuration added, at its original camera/dimensions/times. `rain-shelter-composed-v2/` is a separate wet courtyard demonstration with a pitched shelter, dry deck and surface splashes. Roof/ground/camera behavior has both CPU and actual GPU tests. The composed deck exposed small regular dark postprocessing dots: they remain with `receiveShadow=false`, remain after both rain and splash objects are removed, and remain without the reflector; they disappear with `--no-post`. Those isolated copies are `rain-shelter-no-shadow`, `rain-shelter-no-effects` and `rain-shelter-no-floor`. This is a shared postprocessing investigation, not evidence that precipitation leaks into the depth pass; the runtime owner has the reproducer.
-
-### Verification and remaining work
-
-The first complete assigned suite passed **200 tests in 8.33 seconds** before the additional cloud pixel and transformed-mist tests. Subsequent focused checks passed all 5 cloud tests, all 16 mist/lifecycle tests, and all 24 damp/waterside/GPU-finish tests. Final integration should rerun the complete suite against the shared renderer and library state. All evidence above was captured through the actual GPU host; tests are supporting evidence, not a replacement for image inspection.
-
-Unimplemented proposals remain unimplemented: geometric snow accumulation; aurora ray irregularity; filtered moss/crack normals; nonlinear shallow-bed sampling; scene-depth-aware cloud/fog intersections; geometry-aware snowfall; synchronized rain-impact births. No claim of comprehensive physical simulation is made. All generated source, comments, example labels and this report are English. Published galleries and delivered packages were left unchanged.
-
-Primary references for the bounded volume design are Guerrilla Games' [Nubis](https://www.guerrilla-games.com/read/nubis-realtime-volumetric-cloudscapes-in-a-nutshell) and [Nubis Evolved](https://www.guerrilla-games.com/read/nubis-evolved), and NVIDIA's [Volume Rendering Techniques](https://developer.nvidia.com/gpugems/gpugems/part-vi-beyond-triangles/chapter-39-volume-rendering-techniques). They motivate density/erosion and transmittance integration; this small implementation does not claim their production feature set.
-
-
-## Second visual pass and final snapshot
-
-The subsequent visual pass changes the items explicitly left open in the first ledger:
-
-- **Snow:** default albedo is nearly neutral, its tonal modulation is narrower, and deep deposits become opaque. Blue shadow color now comes primarily from scene illumination rather than large blue albedo patches. A filtered 0.9 mm height signal perturbs the lit normal without changing geometry. A real GPU albedo test verifies neutrality, adequate brightness and resolved tonal variation.
-- **Aurora:** jittered Gaussian strands replace the hard, evenly spaced strokes. Each strand has its own brightness and upper extent, broader folds modulate the curtain, and the lower boundary fades unevenly. The folded normal uses the shared inverse transpose under parent transforms. This remains a luminous ribbon approximation, not a charged-particle simulation.
-- **Shore foam:** world-anchored triplanar noise replaces projection onto a spatially changing tangent. On a centered sphere the former coordinates collapsed one axis, producing repeated stripe fans. The new field retains variation around the full curved shore; a GPU sampling regression measures that variation. Filtering reduces unresolved bubble detail.
-- **Moss and mud:** filtered local height signals supply small moss/lichen relief and curled mud-lip shading. Narrower mud cracks reduce the thick graphic outlines, with less baked highlight color now that actual normals respond to light. `amount: 0` also removes moss's formerly unmasked damp-rim darkening. These remain surface coatings without silhouette changes.
-
-The final assigned suite passes **203 tests in 8.76 seconds**. It includes all 15 original modules, new cloud volumes, factory lifecycle, transformed particle geometry, and local PBR finish checks. No shader/console errors were observed in the final rendering pass.
-
-`/tmp/graphics-seven-hour/weather-refine/source-final-a/` freezes the complete dependency library plus owned tests and the two new examples. `existing-matched-final/` is the final 46-frame baseline replay at identical cameras, dimensions and times, using one frozen source snapshot throughout; both folders carry SHA-256 inventories. The earlier `existing-matched-v2`, `detail-before`, `detail-v2-night_sky`, and `detail-v4-surface_patches` folders remain available to separate the first and second visual passes. The original baseline stays unchanged.
-
-Still deferred: geometric snow accumulation; nonlinear shallow-bed sampling; scene-depth-aware cloud/fog intersections; geometry-aware snowfall; synchronized individual rain-impact births. The cloud/shelter composed scenes remain separate from the matched fixture evidence. Shared renderer investigations and later root integration should preserve these snapshots rather than overwrite them.