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.mdindex 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 includestea 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 directGGX regressions. Three composed recipe studies and their ordered 144-framefilms 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 supportdoes 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.mdindex 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-hvisual cases, and asks whether Three.js can consume independent GLSL files. A realGPU audit found that scaling the original fire by ten preserves almost the sameimage 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 asynchronouslocal FileLoader loading; standalone asset builders remain synchronous. Shaderpreflight 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.mdindex 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 originalmodules. The inventory gives each module's actual named exports, baseline andcurrent 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 remaan approximation: correct reflection geometry does not imply arbitrary-orientationphysical 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 evidenceremains 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 surfaceThe 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 sceneshadows/interreflection and is not a multilayer optical solver. Gallery sourcestaging, 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.mdindex 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 enables1024-pixel bank reflections. Bed caustics are a bounded ripple-curvatureapproximation 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 comparisonThe retained `output/refinement-baseline/<case>/src` workspaces preserve the firstdiff --git a/harness/examples/graphics_lab/REVIEW_2026-09-23.md b/harness/examples/graphics_lab/REVIEW_2026-09-23.mdnew file mode 100644index 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.mjsindex 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.mjsindex 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.pyindex 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 counteddiff --git a/harness/tests/scene_runtime/test_external_shaders.py b/harness/tests/scene_runtime/test_external_shaders.pyindex 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, declarelse: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