fix(sky): preserve dark model lighting and address review

Merge origin/main and retain both format-scope additions.
Give StarrySky a separate black environment cube map and release it on destroy.
Guard anime updates when StarrySky is absent, require a visible Normal sky
before anime QA, and compare a lit airplane against black and white controls.
Document the sky background contract and its verification.

Co-Authored-By: GPT-6 (Codex) <[email protected]>

src/sky/starrySky.js

@@ -161,9 +161,9 @@ export class StarrySky {
     this._loading = false;
     this._starData = undefined;
     this._faceImages = undefined;
-    // Not `_cubeMap`: Scene reads `skyBox._cubeMap` as the environment map
-    // that lights models, in the TEME, flipY layout of its own sky box. This
-    // ICRF map would light them rotated, so models keep Cesium's default.
+    // Scene reads `_cubeMap` for model lighting. Keep it dark as on main;
+    // Cesium's fallback is white, and the ICRF glow is only a background.
+    this._cubeMap = undefined;
     this._milkyWayCubeMap = undefined;
     this._milkyWayCommand = undefined;
     this._milkyWayAttributes = undefined;
@@ -391,6 +391,25 @@ export class StarrySky {
     const { mode, passes, context } = frameState;
     if (mode !== Cesium.SceneMode.SCENE3D) return undefined;
     if (!passes.render) return undefined;
+    if (!this._cubeMap) {
+      const face = {
+        width: 1,
+        height: 1,
+        arrayBufferView: new Uint8Array([0, 0, 0, 255]),
+      };
+      this._cubeMap = new Cesium.CubeMap({
+        context,
+        source: {
+          positiveX: face,
+          negativeX: face,
+          positiveY: face,
+          negativeY: face,
+          positiveZ: face,
+          negativeZ: face,
+        },
+        flipY: false,
+      });
+    }
     this._load();
     let rebuilt = false;
     if (this._faceImages && !this._milkyWayCommand) {
@@ -422,6 +441,7 @@ export class StarrySky {
       command.shaderProgram?.destroy();
     }
     this._milkyWayCubeMap = this._milkyWayCubeMap?.destroy();
+    this._cubeMap = this._cubeMap?.destroy();
     this._milkyWayCommand = undefined;
     this._starCommand = undefined;
     this._commands.length = 0;

src/sky/starrySky.test.mjs

@@ -92,6 +92,7 @@ test('the sky draws nothing when hidden, outside 3D, or in a pick pass', () => {
     undefined,
   );
   // Nothing has loaded yet, so even a render pass has no command.
+  sky._cubeMap = { destroy() {} }; // no WebGL context in this unit test
   assert.equal(sky.update(frameState()), undefined);
   assert.equal(sky.isDestroyed(), false);
   assert.equal(sky.destroy(), undefined);
@@ -133,3 +134,67 @@ test('the Milky Way glow scales with its visibility, for styles that hide it', (
   assert.equal(sky._milkyWayUniforms.u_intensity(), 0);
   sky.destroy();
 });
+
+test('destroy releases both the background and model environment maps', () => {
+  const sky = new StarrySky({ requestRender: () => {} });
+  let destroyed = 0;
+  sky._cubeMap = {
+    destroy: () => {
+      destroyed++;
+    },
+  };
+  sky._milkyWayCubeMap = {
+    destroy: () => {
+      destroyed++;
+    },
+  };
+  sky.destroy();
+  assert.equal(destroyed, 2);
+  assert.equal(sky._cubeMap, undefined);
+  assert.equal(sky._milkyWayCubeMap, undefined);
+  sky.destroy();
+  assert.equal(destroyed, 2);
+});
+
+test('a render update uploads six opaque black environment faces only once', () => {
+  const uploads = [];
+  const gl = {
+    ...Cesium.WebGLConstants,
+    createTexture: () => ({}),
+    activeTexture() {},
+    bindTexture() {},
+    texParameteri() {},
+    pixelStorei() {},
+    texImage2D: (...args) => uploads.push(args),
+    deleteTexture() {},
+  };
+  const previous = Cesium.ContextLimits._maximumCubeMapSize;
+  Cesium.ContextLimits._maximumCubeMapSize = 16;
+  const sky = new StarrySky({ requestRender: () => {} });
+  sky._loading = true;
+  const state = {
+    context: { _gl: gl },
+    mode: Cesium.SceneMode.SCENE3D,
+    passes: { render: true },
+  };
+  try {
+    sky.update(state);
+    const environment = sky._cubeMap;
+    assert.ok(environment instanceof Cesium.CubeMap);
+    assert.equal(uploads.length, 6);
+    assert.equal(new Set(uploads.map((args) => args[0])).size, 6);
+    for (const args of uploads) {
+      assert.equal(args[3], 1);
+      assert.equal(args[4], 1);
+      assert.deepEqual([...args[8]], [0, 0, 0, 255]);
+    }
+    sky.update(state);
+    assert.equal(sky._cubeMap, environment);
+    assert.equal(uploads.length, 6);
+    sky.destroy();
+    assert.equal(environment.isDestroyed(), true);
+  } finally {
+    if (!sky.isDestroyed()) sky.destroy();
+    Cesium.ContextLimits._maximumCubeMapSize = previous;
+  }
+});