Skip to content

Official Codebase of 3DCodeVerse

Python

graphics: a sky-named backdrop in any naming style stays out of the framing, and an undeclared uniform is excused only by the shader that ran

gaoypeng043c0ebf6d4a
diff --git a/harness/docs/GRAPHICS_LIBRARY.md b/harness/docs/GRAPHICS_LIBRARY.md
index 4924d748..d4a79c50 100644
--- a/harness/docs/GRAPHICS_LIBRARY.md
+++ b/harness/docs/GRAPHICS_LIBRARY.md
@@ -111,6 +111,26 @@ 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
@@ -136,8 +156,9 @@ 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 maintenance checkpoint on September 23 passed **2,890 offline tests** and
-Ruff, before the subsequent large-fire and external-shader additions. This is
-behavioral/runtime evidence, not a claim that every procedural effect is
-photorealistic. Final integration results are recorded separately in the
-[development record](GRAPHICS_ROADMAP.md).
+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
index 56b7b081..037e5d56 100644
--- a/harness/docs/GRAPHICS_ROADMAP.md
+++ b/harness/docs/GRAPHICS_ROADMAP.md
@@ -96,25 +96,47 @@ The subsequent request specifically adds campfire, large open fire and burning-h
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. A bounded shared multi-emitter field with optional explicit opaque-depth
-termination is in development. Existing candle and small-fire behavior is retained.
+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.
-Thirteen existing/new shader diagnostics tests pass, including real GPU valid and
-broken external shaders. Gallery staging, capture, verification and transfer
-packaging now preserve those shader files and retained input frames; twenty
-build/media/package regressions pass. An actual external-shader material study is
-being authored alongside the two fire compositions.
-
-## Final integration still pending
-
-Freeze the final library and complete gallery registry, render the authored cameras
-and films into a new output directory, inspect them, run the full browser control
-and strict decoded-media checks, then repeat the complete offline regression.
-Refresh the inventory and final evidence record from that exact source snapshot.
-Prior packages, comparison baselines and published media stay immutable. Passing
-checks does not imply fluid/combustion simulation, recursive transparent transport
-or photorealism; remaining effect-specific limitations stay documented.
+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/graphics_audit_core.md b/harness/docs/graphics_audit_core.md
index 667e308d..605faea1 100644
--- a/harness/docs/graphics_audit_core.md
+++ b/harness/docs/graphics_audit_core.md
@@ -12,18 +12,19 @@ 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 seven additional modules: six visual capabilities and one
-ownership helper. They are not counted among the original 50. The subsequently
-requested `firefield.js` extension is still under development at this ledger
-checkpoint and is excluded from the seven accepted additions below.
+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.
-Current hashes describe the recorded checkpoint, not a promise that concurrent
-integration has stopped. The bounded cloud refinement has been accepted; final
-combined gallery capture and the later fire extension remain separate work.
+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
@@ -51,7 +52,7 @@ integration status are distinguished below.
| `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` | 3 | 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. |
+| `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. |
@@ -131,10 +132,11 @@ reproduced the fix on the GPU. Ordinary horizontal calm-water normal fields rema
an approximation: correct reflection geometry does not imply arbitrary-orientation
physical water shading, a multiple-reflector coordinator or recursive transport.
-## Seven accepted additions, kept separate from the original fifty
+## 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. |
@@ -144,10 +146,24 @@ physical water shading, a multiple-reflector coordinator or recursive transport.
| `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
+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`.
@@ -178,36 +194,76 @@ 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.
-## Verification checkpoint and remaining integration
-
-The clean retained maintenance log is
-`/tmp/graphics-seven-hour/offline-maintenance-checkpoint.log`: **2,890 passed,
-one Pillow deprecation warning**, in 196.94 seconds. This is a historical clean
-maintenance checkpoint, preceding the descendant follow-up and external-shader/fire
-extensions. The earlier `/tmp/graphics-seven-hour/offline-integration-1.log`
-(2,872 passed and one documentation-map failure) remains historical evidence;
-the map defect was corrected. Neither log is relabelled as a final combined run.
-The descendant follow-up has its own retained **48 passing** relevant checks,
-cloud refinement **7**, tree detail **16**, and shader prompt coverage **53**.
-Counts overlap and must not be summed into an aggregate final-source pass claim.
-
-The prior test collection `/tmp/graphics-seven-hour/historical-final-inventory-test-collection.txt`
-recorded 742 cases across 67 files. The inventory generator is prepared to recollect
-current parameterized tests and actual exports at final source freeze. Collection
-is distinct from execution; final counts and hashes await the root integration
-checkpoint, including the in-progress `firefield.js` extension. Family snapshots
-prove their exact captured module versions, not current identity of all shared
-shader and lifecycle dependencies.
-
-Rain's accepted V5 scene is a composition change, not an isolated library comparison.
+## 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 fixed-camera appearance, six GPU frames and reduced background leaf geometry.
-The read-only V2 shelter checks remain applicable because later planting revisions
-leave roof/deck/rain/splash construction unchanged: 4,092 deck probes per camera have
-zero roof misses and all 720 splash positions avoid sheltered ground-level impacts.
-Waterfall's final reflective composition, accepted cloud support refinement and
-external shader study await combined final-gallery capture/verification with the
-remaining additions. Existing delivered packages remain immutable. Repository
-source/tests are durable references; `/tmp` evidence is local until explicitly
-included in a portable artifact. This ledger does not claim that every temporary
-capture is already packaged.
+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/examples/graphics_lab/README.md b/harness/examples/graphics_lab/README.md
index 8eda97f6..017eb66f 100644
--- a/harness/examples/graphics_lab/README.md
+++ b/harness/examples/graphics_lab/README.md
@@ -1,7 +1,8 @@
# Graphics Lab
-See [validation results and actual model trials](VALIDATION.md) for measured
-checks, rendered artifacts and remaining limitations.
+See the [current maintenance and expansion record](REVIEW_2026-09-23.md),
+[earlier refinement](REFINEMENT.md), and
+[initial validation and actual model trials](VALIDATION.md) for evidence and limits.
Sixteen executable studies of fire, water, terrain, vegetation,
atmosphere, worked materials and independent shader files, plus three GPT-6 Luna cases.
@@ -126,6 +127,21 @@ map only. Use at most one planar reflector in a scene. The brook study enables
1024-pixel bank reflections. Bed caustics are a bounded ripple-curvature
approximation applied to direct lighting, not a fluid or photon simulation.
+## Independent shader files
+
+The external shader study loads [a vertex shader](shaders/external_shader.vert),
+[a fragment shader](shaders/external_shader.frag) and
+[shared GLSL helpers](shaders/external_shader_common.glsl) from async
+[scene creation](scenes/external_shader.js). It uses `THREE.FileLoader`,
+module-relative URLs and `ShaderMaterial` with `THREE.GLSL3`; no bundler or raw
+shader import extension is required. JavaScript owns the geometry, uniforms and
+absolute-time update. This is an artistic alloy response with analytic studio
+reflections, not measured anodization or scene-wide ray tracing.
+
+For complete API conventions see Three's [ShaderMaterial documentation](https://threejs.org/docs/pages/ShaderMaterial.html)
+and [FileLoader documentation](https://threejs.org/docs/pages/FileLoader.html).
+Native OpenGL host programs require adaptation to WebGL and GLSL ES.
+
## Controlled refinement comparison
The retained `output/refinement-baseline/<case>/src` workspaces preserve the first
diff --git a/harness/examples/graphics_lab/REVIEW_2026-09-23.md b/harness/examples/graphics_lab/REVIEW_2026-09-23.md
new file mode 100644
index 00000000..ab80d7a6
--- /dev/null
+++ b/harness/examples/graphics_lab/REVIEW_2026-09-23.md
@@ -0,0 +1,168 @@
+# Graphics library maintenance and expansion — September 23, 2026
+
+This record covers the expanded gallery and shared library after the earlier
+[water and material refinement](REFINEMENT.md). All examples, shader sources,
+comments and gallery controls are English. Images are rendered from scene code;
+there are no generated backgrounds or downloaded photographic textures.
+
+## Library changes
+
+All 50 original modules have an explicit disposition in the four family audits.
+Forty-seven received visual, numerical, composition or resource-ownership fixes;
+`caustics`, `finish` and `ocean` were retained with recorded justification. The
+current library has 58 modules and 190 named exports. Seven additions provide
+trees/shrubs, bounded volume clouds, smoke/steam, fractured ice, falling water,
+paving and shared flame/soot fields. `lifecycle` is the eighth addition, for owned
+resource cleanup. The inventory preserves the original 50 source hashes.
+
+Water maintenance corrects transformed reflection planes, nested renderer-state
+restoration, attached-object transforms, finite HDR edges and graded stream-bed
+sampling. Cloud support no longer regrows against its proxy walls as noise moves.
+Vegetation, terrain, rain coverage, walking contact, material normals and borrowed
+resource ownership have separate behavioral and actual GPU checks. The rain scene
+uses lower-detail background leaves while preserving leaf placement/count; its
+tested geometry falls from 20.7 to 12.4 million triangles.
+
+The gallery contains 16 authored studies and three agent cases. The original six
+remain first. Additional studies cover trees, clouds, smoke, ice, waterfalls, rain,
+worked materials, campfire/bonfire, a burning structure and an independent shader.
+Agent provenance distinguishes original Luna CLI output from later delegated
+refinements. No new paid model API call was made during this maintenance pass.
+
+## Fire at several scales
+
+[`makeFireField`](../../codeverse3d/languages/scene_threejs/starter/src/lib/firefield.js)
+combines up to 16 emitters into one bounded flame/soot volume, with rising embers
+and up to four practical lights. An optional depth pass over explicit borrowed
+opaque objects terminates rays at visible walls or fuel. Sources share a baked
+atlas, avoiding a per-sample loop over every emitter. The original candle and
+small-fire API remains available.
+
+[Campfire](scenes/campfire.js) includes close fuel/ember and large open-fire cameras.
+[Structural fire](scenes/structural_fire.js) places a shared field through actual
+window and roof openings, with whole-house, window and roof views. The examples
+use the shipped library, with scene-specific ground, timber and lighting.
+
+Balanced quality uses an approximately 1.49 MB atlas/noise allocation, 80 view
+samples and five soot-light samples; high uses approximately 2.49 MB, 128 and
+seven. Optional opaque depth adds a pass over the supplied occluders. These are
+bounded rendering costs, not isolated frame-rate measurements.
+
+This is prescribed turbulent transport. It does not solve combustion, fuel
+consumption, ventilation, structural collapse or fire spread. Bright windows can
+saturate and fine ray-march grain remains visible in large wisps. Glass and several
+overlapping transparent volumes are not resolved by the opaque-depth pass. The
+authored cottage and vegetation remain recognizably procedural.
+
+## Independent GLSL
+
+[The alloy study](scenes/external_shader.js) loads separate
+[vertex](shaders/external_shader.vert), [fragment](shaders/external_shader.frag)
+and [helper](shaders/external_shader_common.glsl) files using `THREE.FileLoader`
+inside asynchronous scene creation. `ShaderMaterial` uses `THREE.GLSL3`;
+JavaScript supplies geometry, uniforms and absolute-time updates. The runtime
+serves these local files and maps external compiler errors back to source lines.
+The gallery builder, capture records and transfer packager preserve their bytes
+and SHA-256 values. Direct browser imports of raw shader text need a loader;
+desktop OpenGL host programs need adaptation to WebGL and GLSL ES.
+
+The alloy appearance is an artistic analytic studio response. It is not a measured
+anodization model or scene-wide ray tracing.
+
+Visual review also retains broader limits: distant mountain geometry is coarse,
+some rocks have conspicuously faceted silhouettes, and cloud billows remain
+strongly authored. Reflections and transmission improve depth cues but do not
+turn the water into a free-surface fluid solver. These are useful executable
+effect studies, not a claim of photographic realism across every gallery view.
+
+## Integration and artifact status
+
+The final complete offline suite passed **2,922 tests in 225.65 seconds**, with
+one existing Pillow deprecation warning. Ruff passed. Commands and retained logs:
+
+```bash
+C3D_CACHE_DIR=/tmp/c3d-graphics-final-integration python -m pytest tests -q -n4
+ruff check codeverse3d tests examples/graphics_lab
+```
+
+Logs are `/tmp/graphics-seven-hour/offline-final-clean.log` and
+`/tmp/graphics-seven-hour/final-ruff-clean.log`. The maintenance checkpoint passed
+2,890 tests before the fire/external-shader additions. The first integration
+attempt had 2,917 passes and two failures: a closed Chrome target during a cloud
+probe, and an over-broad downgrade of an unused shader's static diagnostic.
+The isolated cloud module passed all seven tests. The diagnostic now requires
+unambiguous source participation in evaluated shader text; 29 focused tests,
+including three unused/duplicate-literal regressions, pass. The interrupted
+`gallery-v1` capture is retained as a failed attempt, not a release artifact.
+
+The final snapshot is [`output/seven-hour/gallery-v2/`](output/seven-hour/gallery-v2/).
+It contains **159 stills across 19 cases and 53 cameras**, with no shader, console
+or update errors. All **30 films / 4,320 frames** decoded successfully: 19 primary
+views and 11 additional cameras, each six seconds at 24 fps and 1280 by 720.
+Every film passed source ownership, encoded digest and three retained input-PNG
+checks. All 63 captured source files per case match the manifest. A separate
+120-file check binds current library, scene, shader and runtime sources to the
+captured snapshot.
+
+The maximum first decoded-frame difference from its still is 4.689/255 mean RGB;
+the maximum downsampled difference from a retained encoding input is 1.317/255.
+Twenty-seven films have measurable motion at the verifier's anchor-mask threshold
+and follow their own changing inputs. Rock, sand and workshop views do not exceed
+that threshold; they are not counted as demonstrated motion. These are integrity
+checks, not aesthetic scores. Reports and decoded contact sheets are in
+[`media-verification/`](output/seven-hour/gallery-v2/media-verification/).
+
+The [browser check](output/seven-hour/gallery-v2/browser-check.json) passed all
+19 cases and 53 cameras: actual video playback, orbit-camera selection, pause,
+time scrubbing, tab reopening and cancelled scene creation. There were no browser
+errors. It checked 4,407 English source/document files before the new transfer
+package was created. A separate final
+[English scan](output/seven-hour/gallery-v2/verification/english-check.json)
+also includes JSON and the extracted transfer packages. Final visual reviews inspected the actual frozen stills,
+selected detail views and decoded fire/water/shader contact sheets. Fire samples
+at 0/2/4 seconds show changing flame/embers with stable structural occlusion;
+this sampled review does not claim to have watched every encoded frame.
+
+Selected test logs and visual-review summaries are retained in
+[`verification/`](output/seven-hour/gallery-v2/verification/), with runtime hashes
+in [`runtime-source.sha256.json`](output/seven-hour/gallery-v2/runtime-source.sha256.json).
+The gallery runs with `node examples/graphics_lab/serve.mjs --out
+examples/graphics_lab/output/seven-hour/gallery-v2`; open the printed loopback URL.
+Additional films, including `bonfire.mp4`, `window_fire.mp4` and `roof_fire.mp4`,
+are in the gallery root; the same authored cameras are available in live mode.
+
+## Transfer package
+
+The new [folder](output/seven-hour/gallery-v2/packages/graphics_lab_first_six_maintained_2026-09-23/)
+and [ZIP](output/seven-hour/gallery-v2/packages/graphics_lab_first_six_maintained_2026-09-23.zip)
+contain the first six scene modules, 58 matching library modules, three independent
+shader files, seven films including the hearth view, six previews, retained
+encoding inputs and capture provenance. Open the package's `index.html` directly
+to watch offline; running scene code requires the compatible Three.js host.
+
+The ZIP contains **113 files / 74,973,979 bytes (71.50 MiB)**. Published, staged
+and captured-source checks, encoded digests, archive CRC and extracted-file hashes
+all passed. SHA-256:
+
+```text
+26efcebd51c76ba7b1a27eb8fdeea5cab0851ec0b9ef628bfaf556f3ae501098
+```
+
+An actual browser opened the extracted package over a `file:` URL without a
+server and played all seven six-second, 1280-by-720 videos with zero errors;
+the [offline playback report](output/seven-hour/gallery-v2/verification/offline-package-browser.json)
+records the result. The final independent artifact audit also rehashed the ZIP
+and all payloads, checked 38 relative HTML assets and found no blocking mismatch.
+The documentation checks passed all 19 tests after the final integration edits.
+
+Both previously published ZIPs remain byte-identical; no earlier package or
+comparison baseline was replaced. The new package contains scene/library/shader
+code and media, not runtime binaries or npm dependencies.
+
+The canonical inventory is `output/seven-hour/inventory.json`. Family audits are
+[`core`](../../docs/graphics_audit_core.md),
+[`weather`](../../docs/graphics_audit_weather.md),
+[`life`](../../docs/graphics_audit_life.md) and
+[`surfaces`](../../docs/graphics_audit_surfaces.md). Their historical checkpoints
+are identified separately from final combined verification. Local `/tmp` render
+evidence is not implicitly included in a transfer ZIP.
diff --git a/harness/runtime_js/lib/backdrop.mjs b/harness/runtime_js/lib/backdrop.mjs
index ab0b91b3..2e31a14f 100644
--- a/harness/runtime_js/lib/backdrop.mjs
+++ b/harness/runtime_js/lib/backdrop.mjs
@@ -6,7 +6,7 @@
* word "content" means exactly one thing everywhere.
*
* Rules (name + world-box shape, in order):
- * sky a sky-ish name spanning > 50 m, or anything enormous (span > 2 km,
+ * sky a sky-ish name spanning > 50 m or not writing depth, or anything enormous (span > 2 km,
* or tall AND wide: sy > 300 with span > 300)
* content an InstancedMesh (scatter spans the map but is not ground)
* ground a ground-ish name on a wide, flat box (span > 20, sy < 6 % of span)
@@ -59,10 +59,16 @@ export const GROUND_NAME_RE = /\b(ground|terrain|floor|water|ocean|sea|lake|rive
* @param {number} contentSpan horizontal span of the known content bbox (0 = unknown)
*/
export function classifyBackdrop(obj, box, contentSpan = 0) {
- const name = obj.name || (obj.parent && obj.parent.name) || '';
+ // Generated scene names normally use PascalCase / snake_case. Word boundaries
+ // alone missed PlanetSkyBackdrop and SkyAtmosphereBand0, framing the sky as a
+ // building. Keep the same vocabulary and shape rules for every naming style.
+ const name = (obj.name || (obj.parent && obj.parent.name) || '')
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ');
const sx = box.max.x - box.min.x, sy = box.max.y - box.min.y, sz = box.max.z - box.min.z;
const span = Math.max(sx, sz);
- if (SKY_NAME_RE.test(name) && span > 50) return 'sky';
+ // sunRig's MoonDisc can be only five metres wide in a compact worldShell, but
+ // its non-depth-writing light image still must not move the scene's centre.
+ if (SKY_NAME_RE.test(name) && (span > 50 || nonSolid(obj))) return 'sky';
if (span > 2000 || (sy > 300 && span > 300)) return 'sky';
// a small thing kilometres from the origin is a backdrop whatever it is called: the sun/moon
// disc `sunRig` parks at 0.9 × the sky radius ('SunDisc' — no word boundary for the regex)
diff --git a/harness/runtime_js/lib/shader_report.mjs b/harness/runtime_js/lib/shader_report.mjs
index 9cfa1caf..04d32f39 100644
--- a/harness/runtime_js/lib/shader_report.mjs
+++ b/harness/runtime_js/lib/shader_report.mjs
@@ -15,7 +15,7 @@
import fs from 'node:fs';
import path from 'node:path';
-import { auditFile, fixHintFor, hasGlsl, isShaderSource, locateSourceLine } from './glsl_audit.mjs';
+import { auditFile, extractGlslStrings, fixHintFor, hasGlsl, isShaderSource, locateSourceLine } from './glsl_audit.mjs';
import { errorSummary } from './host_page.mjs';
import { listSourceFiles } from './syntax_check.mjs';
@@ -42,6 +42,27 @@ export function listSources(root, sub = 'src') {
* `files`, so a COMPILE error inside one still maps back to its file:line. */
const LIB_RE = /^src\/lib\//;
+/** Match source literals to the evaluated shader, conservatively. A successful
+ * unrelated program says nothing about a declaration in an unused file (or an
+ * unused literal beside a live shader). Duplicate text cannot prove its origin.
+ */
+function verifiedDeclarations(files, evaluatedSources) {
+ const normalize = (text) => text.replace(/\\[nrt]/g, (escape) =>
+ ({ '\\n': '\n', '\\r': '\r', '\\t': '\t' })[escape]).trim();
+ const blocks = files.flatMap(({ file, text }) =>
+ (isShaderSource(file) ? [{ text }] : extractGlslStrings(text))
+ .map((block) => ({ file, text: normalize(block.text) })));
+ const evaluated = evaluatedSources.map(normalize);
+ const verified = new Set();
+ for (const file of new Set(blocks.map((block) => block.file))) {
+ const reads = blocks.filter((block) => block.file === file && /\buTime\b/.test(block.text));
+ if (reads.length && reads.every((block) => !block.text.includes('${')
+ && blocks.filter((other) => other.text.includes(block.text)).length === 1
+ && evaluated.some((source) => source.includes(block.text)))) verified.add(file);
+ }
+ return verified;
+}
+
/**
* Static-audit stage: build the report skeleton with the node-side GLSL
* findings. `module` (optional) restricts the audit to one source file.
@@ -89,7 +110,16 @@ export async function compileIntoReport(report, files, host) {
if (!boot.ok) {
errors.push({ file: 'src/scene.js', line: null, kind: 'boot', message: `scene did not boot at stage '${boot.stage}': ${boot.error}`.slice(0, 1200), fix_hint: 'fix the import/runtime error first; then compile again' });
} else {
- const comp = await page.evaluate((spec) => window.__c3v.compileAll(spec || undefined), null);
+ const comp = await page.evaluate(async (needDeclarationProof) => {
+ const result = window.__c3v.compileAll();
+ if (needDeclarationProof && result.programs > 0 && result.shader_errors.length === 0) {
+ // Reuse the host's captured material sources; do not infer participation
+ // from a program count or from the mere presence of an external header.
+ const { captured } = await import('/__runtime/lib/host_compile.mjs');
+ result.evaluated_sources = captured.flatMap(({ vs, fs }) => [vs, fs]);
+ }
+ return result;
+ }, errors.some((e) => e.kind === 'undeclared_uniform'));
const shaderErrors = comp.shader_errors.map(({ _key, ...e }) => e);
for (const e of shaderErrors) {
const loc = locateSourceLine(files, e.source_line);
@@ -105,9 +135,11 @@ export async function compileIntoReport(report, files, host) {
}
report.compile = { ms: comp.compile_ms, programs: comp.programs, custom_materials: comp.custom_materials, renderer: boot.renderer, gpu: host.gpu };
if (comp.programs > 0 && shaderErrors.length === 0) {
+ const declarationFiles = verifiedDeclarations(files, comp.evaluated_sources || []);
for (let i = errors.length - 1; i >= 0; i--) {
const e = errors[i];
if (!staticLanguageErrors.has(e)) continue;
+ if (e.kind === 'undeclared_uniform' && !declarationFiles.has(e.file)) continue;
errors.splice(i, 1);
warnings.push({ ...e, fix_hint: '', validation: 'runtime_compile_passed',
message: `${e.message} — source-only warning: all evaluated shader programs compiled successfully; JavaScript may transform this literal or join external source before use.` });
diff --git a/harness/tests/scene_runtime/test_backdrop.py b/harness/tests/scene_runtime/test_backdrop.py
index 079f4b52..538039af 100644
--- a/harness/tests/scene_runtime/test_backdrop.py
+++ b/harness/tests/scene_runtime/test_backdrop.py
@@ -26,6 +26,11 @@ CASES = [
("Path", [30, 0.1, 30], False, 5, "ground"), # far larger than the content bbox
("Path", [30, 0.1, 30], False, 0, "content"), # same box, no content bbox known
("Rug", [3, 0.05, 3], False, 40, "content"), # small relative to content: not backdrop
+ ("PlanetSkyBackdrop", [205, 205, 205], False, 0, "sky"),
+ ("planet_sky_backdrop", [205, 205, 205], False, 0, "sky"),
+ ("SkyAtmosphereBand0", [90, 4, 90], False, 0, "sky"),
+ ("MoonLamp", [1, 1, 1], False, 0, "content"), # a solid prop remains content
+ ("SkyScraper", [25, 200, 25], False, 0, "content"), # the size guard still matters
]
@@ -55,3 +60,26 @@ def test_classifier_rule_table():
["SunDisc", [48, 48, 48], False, 40, [10, 20, 10]],
])
assert got == [c[4] for c in CASES] + ["sky", "content"], list(zip([c[0] for c in CASES], got, strict=False))
+
+
+def test_background_planet_and_small_moon_do_not_move_content_framing():
+ body = f"""
+import * as THREE from 'three';
+import {{ sceneCensus }} from '{RUNTIME_JS}/lib/host_census.mjs';
+import {{ framingBox }} from '{RUNTIME_JS}/lib/orbit.mjs';
+const scene = new THREE.Scene(), environment = new THREE.Group();
+environment.name = 'Environment'; scene.add(environment);
+const subject = new THREE.Mesh(new THREE.BoxGeometry(30, 20, 40), new THREE.MeshStandardMaterial());
+subject.name = 'Hangar'; subject.position.y = 10; environment.add(subject);
+const planet = new THREE.Mesh(new THREE.SphereGeometry(100), new THREE.MeshBasicMaterial());
+planet.name = 'PlanetSkyBackdrop'; planet.position.set(25, -55, -200); environment.add(planet);
+const moon = new THREE.Mesh(new THREE.CircleGeometry(2.5), new THREE.MeshBasicMaterial({{ depthWrite: false }}));
+moon.name = 'MoonDisc'; moon.position.set(-277, 137, -103); environment.add(moon);
+const census = sceneCensus(scene, THREE);
+console.log(JSON.stringify({{ content: census.content_bbox, all: census.bbox, framed: framingBox(census) }}));
+"""
+ got = run_node_json(body)
+ assert got["content"]["min"] == [-15, 0, -20]
+ assert got["content"]["max"] == [15, 20, 20]
+ assert got["framed"] == got["content"]
+ assert got["all"]["min"][0] < -270 # background geometry is retained and still counted
diff --git a/harness/tests/scene_runtime/test_external_shaders.py b/harness/tests/scene_runtime/test_external_shaders.py
index 1857718a..af0662ff 100644
--- a/harness/tests/scene_runtime/test_external_shaders.py
+++ b/harness/tests/scene_runtime/test_external_shaders.py
@@ -107,3 +107,36 @@ def test_external_uniform_header_can_be_joined_with_inline_glsl(tmp_path, declar
else:
assert any(item["kind"] == "compile" for item in report["errors"])
assert any(item["kind"] == "undeclared_uniform" for item in report["errors"])
+
+
+@needs_browser
[email protected]("unused", ["other_file", "same_file", "duplicate_file"])
+def test_valid_external_header_does_not_clear_unused_declaration_errors(tmp_path, unused):
+ """GPU success proves the evaluated body, not every literal in the workspace."""
+ root = stage(tmp_path)
+ (root / "src/shaders/panel.frag").write_text("uniform float uTime;\n")
+ body = "void main(){gl_FragColor=vec4(vec3(uTime),1.0);}"
+ scene = SCENE.replace("fragmentShader:common + '\\n' + fragment,",
+ f"fragmentShader:common + '\\n' + fragment + `\\n{body}`, ")
+ inactive = body if unused == "duplicate_file" else body.replace("vec3(uTime)", "vec3(uTime*.37)")
+ unused_source = f"export const unusedFragment = `{inactive}`;\n"
+ if unused == "same_file":
+ scene += unused_source
+ expected_file = "src/scene.js"
+ else:
+ expected_file = "src/shaders/unused.js"
+ (root / expected_file).write_text(unused_source)
+ (root / "src/scene.js").write_text(scene)
+ proc = subprocess.run(["node", str(RUNTIME_JS / "check_shaders.mjs"), "--ws", str(root)],
+ capture_output=True, text=True, timeout=120)
+ assert proc.returncode == 1, proc.stdout + proc.stderr
+ report = json.loads(proc.stdout.strip().splitlines()[-1])
+ assert report["compile"]["programs"] > 0
+ assert not any(item["kind"] == "compile" for item in report["errors"])
+ assert any(item["kind"] == "undeclared_uniform" and item["file"] == expected_file
+ for item in report["errors"]), report
+ if unused == "other_file":
+ assert any(item["kind"] == "undeclared_uniform" and item["file"] == "src/scene.js"
+ and item.get("validation") == "runtime_compile_passed"
+ for item in report["warnings"]), report