feat: add cloud shadows and ocean specular to earth shader

Cloud shadows use ray-sphere intersection to trace from each surface
point toward the sun, finding the exact cloud intersection point and
converting to equirectangular UV for accurate shadow placement. Shadow
strength scales with bloom (100% with bloom, 80% without).

Ocean specular uses two-lobe Blinn-Phong with Schlick Fresnel (F0=0.02)
and blue-channel water masking. Cloud shadows suppress glare under
overcast areas. Glare only renders when bloom is enabled.

Author: sandrwich

src/app.ts

@@ -408,7 +408,7 @@ export class App {
     this.setLoading(0.5, 'Building scene...');
 
     // Earth
-    this.earth = new Earth(dayTex, nightTex, earthNormal ?? null, earthDisp ?? null);
+    this.earth = new Earth(dayTex, nightTex, earthNormal ?? null, earthDisp ?? null, cloudTex);
     this.scene3d.add(this.earth.mesh);
 
     // Sky-view ground disc: flat plane with projected Earth texture for realistic ground
@@ -1611,7 +1611,8 @@ export class App {
     if (this.viewMode === ViewMode.VIEW_3D || isSkyView) {
       // Update 3D scene (sky view shares the 3D scene but hides ground objects)
       if (!this.orreryCtrl.isOrreryMode && !isSkyView) {
-        this.earth.update(epoch, gmstDeg, this.cfg.earthRotationOffset, this.cfg.showNightLights);
+        this.earth.update(epoch, gmstDeg, this.cfg.earthRotationOffset, this.cfg.showNightLights, this.cfg.showClouds, this.camera3d.position);
+        this.earth.setShowGlare(this.bloomEnabled);
         if (earthMode) this.cloudLayer.update(epoch, gmstDeg, this.cfg.earthRotationOffset, this.cfg.showClouds, this.cfg.showNightLights);
       }
       // Moon + sun update in both orbital and sky view

src/scene/earth.ts

@@ -8,6 +8,7 @@ import earthFragSrc from '../shaders/earth-daynight.frag.glsl?raw';
 
 const _yAxis = new THREE.Vector3(0, 1, 0);
 const _tmpSun = new THREE.Vector3();
+const _tmpView = new THREE.Vector3();
 
 export class Earth {
   mesh: THREE.Mesh;
@@ -16,7 +17,7 @@ export class Earth {
   private bumpEnabled = true;
   private aoEnabledState = true;
 
-  constructor(dayTex: THREE.Texture, nightTex: THREE.Texture, normalTex: THREE.Texture | null, displacementTex: THREE.Texture | null) {
+  constructor(dayTex: THREE.Texture, nightTex: THREE.Texture, normalTex: THREE.Texture | null, displacementTex: THREE.Texture | null, cloudTex: THREE.Texture | null) {
     const radius = EARTH_RADIUS_KM / DRAW_SCALE;
     const geometry = this.genEarthGeometry(radius, 256, 256);
 
@@ -28,6 +29,7 @@ export class Earth {
         nightTexture: { value: nightTex },
         normalMap: { value: normalTex },
         displacementMap: { value: displacementTex },
+        cloudTexture: { value: cloudTex },
         sunDir: { value: new THREE.Vector3(1, 0, 0) },
         moonPos: { value: new THREE.Vector3(0, 0, 0) },
         moonRadius: { value: MOON_RADIUS_KM },
@@ -37,6 +39,10 @@ export class Earth {
         aoEnabled: { value: 1.0 },
         displacementScale: { value: 0.007 },
         hasDisplacement: { value: displacementTex ? 1.0 : 0.0 },
+        viewPos: { value: new THREE.Vector3() },
+        cloudUVOffset: { value: 0.0 },
+        showClouds: { value: 0.0 },
+        showGlare: { value: 1.0 },
       },
       vertexShader: earthVertSrc,
       fragmentShader: earthFragSrc,
@@ -98,19 +104,35 @@ export class Earth {
     return geo;
   }
 
-  update(currentEpoch: number, gmstDeg: number, earthOffset: number, showNightLights: boolean) {
-    this.mesh.rotation.y = (gmstDeg + earthOffset) * DEG2RAD;
+  update(currentEpoch: number, gmstDeg: number, earthOffset: number, showNightLights: boolean, showClouds: boolean, cameraPosition: THREE.Vector3) {
+    const earthRotRad = (gmstDeg + earthOffset) * DEG2RAD;
+    this.mesh.rotation.y = earthRotRad;
     this.material.uniforms.showNight.value = showNightLights ? 1.0 : 0.0;
+    this.material.uniforms.showClouds.value = showClouds ? 1.0 : 0.0;
 
     const sunEci = calculateSunPosition(currentEpoch);
-    const earthRotRad = (gmstDeg + earthOffset) * DEG2RAD;
     _tmpSun.copy(sunEci).applyAxisAngle(_yAxis, -earthRotRad);
     this.material.uniforms.sunDir.value.copy(_tmpSun);
 
     // Moon position in ECEF for solar eclipse shadow
     const moonRender = calculateMoonPosition(currentEpoch);
     moonRender.applyAxisAngle(_yAxis, -earthRotRad);
     this.material.uniforms.moonPos.value.copy(moonRender);
+
+    // View position in ECEF for specular
+    _tmpView.copy(cameraPosition).applyAxisAngle(_yAxis, -earthRotRad);
+    // Scale from draw units to km for the shader
+    _tmpView.multiplyScalar(DRAW_SCALE);
+    this.material.uniforms.viewPos.value.copy(_tmpView);
+
+    // Cloud UV offset: difference between earth and cloud rotation in UV space
+    const cloudAngle = ((gmstDeg + earthOffset + currentEpoch * 360.0 * 0.04) % 360.0) * DEG2RAD;
+    const uvOffset = (earthRotRad - cloudAngle) / (2.0 * Math.PI);
+    this.material.uniforms.cloudUVOffset.value = uvOffset;
+  }
+
+  setShowGlare(on: boolean) {
+    this.material.uniforms.showGlare.value = on ? 1.0 : 0.0;
   }
 
   setNightEmission(value: number) {

src/shaders/earth-daynight.frag.glsl

@@ -2,6 +2,7 @@ uniform sampler2D dayTexture;
 uniform sampler2D nightTexture;
 uniform sampler2D normalMap;
 uniform sampler2D displacementMap;
+uniform sampler2D cloudTexture;
 uniform vec3 sunDir;
 uniform vec3 moonPos;
 uniform float moonRadius;
@@ -10,15 +11,21 @@ uniform float nightEmission;
 uniform float hasNormalMap;
 uniform float aoEnabled;
 uniform float hasDisplacement;
+uniform vec3 viewPos;
+uniform float cloudUVOffset;
+uniform float showClouds;
+uniform float showGlare;
 
 varying vec2 vUv;
+varying vec3 vWorldPos;
 
 const float PI = 3.14159265359;
 const float TWO_PI = 6.28318530718;
 const float TEX_STEP = 1.0 / 2048.0;
 const float AO_STRENGTH = 8.0;
 const float EARTH_R = 6371.0;
 const float SUN_ANG_R = 0.00465;
+const float CLOUD_ALT = 25.0;
 
 void main() {
     vec4 day = texture2D(dayTexture, vUv);
@@ -88,6 +95,70 @@ void main() {
     float surfaceHaze = pow(max(1.0 - abs(intensity), 0.0), 2.0) * smoothstep(-0.1, 0.2, intensity) * 0.1;
     scatteredDay = mix(scatteredDay, hazeColor, surfaceHaze);
 
+    // --- Cloud shadows via ray-sphere intersection ---
+    float cloudShadow = 1.0;
+    if (showClouds > 0.5 && rawIntensity > -0.1) {
+        // Trace ray from surface point toward sun, find where it hits the cloud sphere
+        vec3 surfPos = baseNormal * EARTH_R;
+        float cloudR = EARTH_R + CLOUD_ALT;
+
+        // Solve |surfPos + t*sunDir|² = cloudR²
+        float b = 2.0 * dot(surfPos, sunDir);
+        float c = EARTH_R * EARTH_R - cloudR * cloudR;
+        float disc = b * b - 4.0 * c;
+
+        // disc is always positive (surface is inside the cloud sphere)
+        float t = (-b + sqrt(disc)) * 0.5;
+        vec3 cloudHit = surfPos + t * sunDir;
+
+        // Convert cloud intersection to equirectangular UV
+        vec3 cn = normalize(cloudHit);
+        float cloudTheta = atan(-cn.z, cn.x);
+        float cloudPhi = acos(clamp(cn.y, -1.0, 1.0));
+        vec2 cloudUV = vec2(cloudTheta / TWO_PI + 0.5, 1.0 - cloudPhi / PI);
+
+        // Apply the rotation offset between earth and cloud layer
+        cloudUV.x = fract(cloudUV.x + cloudUVOffset);
+
+        float cloudAlpha = texture2D(cloudTexture, cloudUV).a;
+
+        // Softer shadows on the day side, fade out near terminator
+        float shadowDayMask = smoothstep(-0.05, 0.25, rawIntensity);
+        float shadowStrength = showGlare > 0.5 ? 1.0 : 0.8;
+        cloudShadow = 1.0 - cloudAlpha * shadowStrength * shadowDayMask;
+        scatteredDay *= cloudShadow;
+    }
+
+    // --- Ocean specular (water glare / sun glint) ---
+    if (showGlare > 0.5 && rawIntensity > 0.0) {
+        vec3 viewDir = normalize(viewPos - baseNormal * EARTH_R);
+        vec3 halfVec = normalize(sunDir + viewDir);
+
+        float NdotV = max(dot(baseNormal, viewDir), 0.0);
+        float NdotH = max(dot(normal, halfVec), 0.0);
+        float NdotL = max(rawIntensity, 0.0);
+
+        // Fresnel (Schlick) — water F0 ≈ 0.02
+        float fresnel = 0.02 + 0.98 * pow(1.0 - NdotV, 5.0);
+
+        // Ocean mask: blue-dominant pixels with low green/red
+        float waterMask = clamp((day.b - max(day.r, day.g)) * 3.0, 0.0, 1.0);
+
+        // Two-lobe specular: tight sun disk + broad Fresnel rim
+        float specTight = pow(NdotH, 256.0);
+        float specBroad = pow(NdotH, 16.0);
+        float spec = specTight * 3.0 + specBroad * 0.15;
+
+        // Sun color: warm white at high angles, reddish near horizon
+        vec3 sunColor = mix(vec3(1.0, 0.7, 0.4), vec3(1.0, 0.95, 0.9), NdotL);
+
+        // Cloud shadow suppresses glare — no sun reflection under clouds
+        vec3 glare = sunColor * spec * fresnel * waterMask * NdotL * cloudShadow;
+
+        // Roughness from normal map breaks up the glare naturally
+        scatteredDay += glare;
+    }
+
     // Boost night emission for bloom (HDR values > 1.0)
     vec4 boostedNight = vec4(night.rgb * nightEmission, night.a);
     // Eclipse: blend day toward night lights instead of black

src/shaders/earth-daynight.vert.glsl

@@ -3,6 +3,7 @@ uniform float displacementScale;
 uniform float hasDisplacement;
 
 varying vec2 vUv;
+varying vec3 vWorldPos;
 
 void main() {
     vUv = uv;
@@ -13,5 +14,6 @@ void main() {
         pos += normal * height * displacementScale;
     }
 
+    vWorldPos = (modelMatrix * vec4(pos, 1.0)).xyz;
     gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);
 }