Add optional Enhanced Earth oceans, raised clouds and shadows

[Protonmatter]

Outcome

Earth's historical clouds currently sit on the ground, and its ocean presentation is brighter than the requested deep blue. This adds an optional Earth layers → Enhanced Earth mode with darker, less saturated offshore water, a raised cloud shell, Sun-directed offset ground shadows, and independent cloud drift during Play time. The original view remains the default; the NASA source images and engine state are unchanged.

The comparison is a controlled offscreen OpenGL ES software render using the actual production shaders, original maps and identical camera/Sun direction. It is not a browser or mobile qualification.

Specification and traceability

• Requirement: SOL-VIS-009; preserves SOL-VIS-004/006 boundaries.
• Accepted design: docs/rfcs/0008-enhanced-earth.md, owner-approved in conversation on 2026-09-23.
• Governing specification and evidence: docs/SPEC.md, docs/validation/enhanced-earth/README.md.
• ADR not required: existing rendering, resource and simulation boundaries are retained.
• Scope excludes other planets, solar changes, live weather, qualified ocean reflectance and volumetric clouds. The other-planet draft PR Add optional illustrative looks for seven planets #115 is separate.

Correctness and risk

• A deterministic, hash-pinned 512×256 Natural Earth land/ice mask and blue/brightness guards restrict ocean grading. It is intentionally coarse and omits small islands.
• The cloud shell is nominally 8 km high. Shadows intersect it toward the Sun and share its UV phase. Clouds are drawn once, depth-tested without depth writes. Shadows attenuate direct ground light without dimming atmospheric haze.
• Drift follows 3% of displayed Earth rotation with a real-time cap. Pause, hidden/inactive views and reduced motion freeze it; camera redraws do not advance phase. Context restoration preserves phase.
• MODIS swaths containing the ground and the scientific sea-ice palette suspend enhancement. Missing/off clouds cast no shadows. Mask upload failure is disclosed and can be retried by toggling the mode off/on.
• No new runtime dependency, external request, data schema or source-image mutation. The two new rendering modules participate in the release science fingerprint; staged-digest regression coverage verifies this.
• The cloud pass uses existing illustrative haze, while the ground retains its reference optical path. Height, drift, color grading and shadow strength are display choices, not retrieved weather.
• The actual GLES compiler exposed an existing reserved GLSL local named packed. Rename it to columnValues without changing formulas. Regenerate the source-bound atmosphere manifest with the normal generator; both 2 MiB numerical fields reproduce byte-for-byte.
• Rollback: uncheck Enhanced Earth or revert this feature. No merge, deployment or release qualification is claimed.

UI and UX

• Native unchecked checkbox within Earth layers with associated help and active/suspended/unavailable status.
• Renderer lifecycle tests cover reduced motion, pause, hidden/inactive scenes, missing resources and recovery. UX structure and static-web checks pass.
• Manual keyboard/touch, Safari/iOS/native-device appearance, physical-path visual quality and frame-time checks remain pending.

Validation evidence

• Positive, boundary and negative unit cases; production renderer lifecycle and executed GLSL helper checks.
• Consumer integration, uniform propagation, source identity and release-fingerprint checks.
• Native browser end-to-end and visual qualification.
• Deterministic ocean-mask and atmosphere field regeneration.
• Fresh Rust/Python/Node/whole-web 90% coverage gates.
• Locally unavailable checks are named for CI.

npm test
  1,323 passed; 0 failed/skipped.
PYTHONPATH=tools python -m unittest discover -s tests/python -p 'test_*.py' -v
  390 ran; 5 errors caused by missing cargo/rustc, 3 skipped, no assertion failures.
  Errors: 3 native snapshot subcases, native hybrid-time case, Rust evidence capture.
python tools/typecheck_web.py
  114 files clean.
python tools/validate_web_static.py
python tools/validate_ux_contract.py
python tools/validate_sdlc.py
python tools/validate_docs.py
  Passed; 24 requirements and 140 Markdown files.
python tools/prepare_earth_ocean_mask.py --check
  Exact regeneration passed.
python tools/render_enhanced_earth_probe.py
  Mesa llvmpipe GLES 3.2: base and physical production programs compiled/linked.
  Base-haze image, drift, shadow and black-ground haze-isolation checks passed.
git diff --check
  Passed.

Rust/WASM and native WebGL2/browser checks remain for required CI/device validation; no immutable release was built without those inputs. The physical program was compiled, but only the base-haze path was rendered in the comparison. Fresh full coverage was not claimed. Independent review's two minor findings were fixed and confirmed in focused follow-up review.

Documentation

• README usage instructions and source limitations updated.
• SPEC, requirement catalogue, traceability, RFC and implementation plan updated.
• Status and reproducible validation record updated.
• UI help matches implemented behavior and qualification limits.