Merge pull request #1243 from bilawalsidhu/claude/hal-627-starfield-cb6fa2

feat(sky): catalogue stars and a soft Milky Way instead of the blocky sky box

DATA_SOURCES.md

@@ -205,6 +205,8 @@ The [Bhote Koshi event pack](public/events/bhote-koshi-2026/README.md), under `p
 | **DataSF Analysis Neighborhoods** (41 SF neighborhood polygons)             | `neighborhoods/`                  | **PDDL 1.0** (public domain)                                                                              | ✅ (no restrictions)                             | "City & County of San Francisco — DataSF" (courtesy — not legally required) |
 | **Natural Earth countries, states and provinces** (260 admin-0/map units + 4,587 admin-1 polygons)             | `natural_earth/`                  | **Public domain**                                                                                         | ✅ (no restrictions)                             | "Made with Natural Earth" (courtesy credit — not legally required)          |
 | **US Census Bureau counties** (3,235 county polygons)                       | `us_census_counties/`             | **Public domain**                                                                                         | ✅ (no restrictions)                             | "U.S. Census Bureau" (courtesy — not legally required)                      |
+| **Yale Bright Star Catalogue** (9,096 stars, sky background)                | `sky/`                            | **Public domain**                                                                                         | ✅ (no restrictions)                             | "Yale Bright Star Catalogue (Hoffleit & Warren, via CDS)" (courtesy credit) |
+| **ESO Milky Way panorama** (eso0932a, blurred cube map, sky background)     | `sky/`                            | **CC BY 4.0**                                                                                             | ✅ (attribution; changes stated)                 | "ESO/S. Brunier"                                                            |
 | **CCTV ground heights** (3,445 cameras)                                     | `cctv_ground_heights/`            | Precomputed camera placement heights, aligned to work with Google Photorealistic 3D Tiles (folder README) | —                                                | —                                                                           |
 | **CCTV Camera Database** model-enrichment extract v2.26.0 (17 camera-model records) | `src/layers/cctv/modelSpecs.js` | **CC0-1.0** (public domain dedication) | ✅ (no restrictions) | "Specs: cctv-database.com" (courtesy — not legally required) |
 
@@ -277,6 +279,11 @@ https://www.naturalearthdata.com/about/terms-of-use/). We credit anyway: "Made w
 Earth". Registration in the in-app `dataCredits.js` attribution list ships with the resolver
 wiring (see below).
 
+### Sky background (`sky/`)
+
+Sources, licences, the changes CC BY asks to state, hashes and build commands
+are in [`sky/README.md`](src/data/local_data/sky/README.md).
+
 ### DataSF Analysis Neighborhoods (`neighborhoods/`)
 
 `neighborhoods/san-francisco.json` bundles the City & County of San Francisco's official

changelog.d/1243-starfield-sky.md

@@ -0,0 +1,5 @@
+- Replace the blocky JPEG sky around the globe with the 9,096 stars of the
+  Yale Bright Star Catalogue, drawn as sharp points where they are at the
+  scene time, over a soft Milky Way from ESO/S. Brunier (CC BY 4.0). The Sun
+  and Moon stay; the anime style hides the Milky Way. Assets: 296 kB (gekh,
+  #1243).

docs/CURRENT-STATE.md

@@ -1179,6 +1179,24 @@ snapshots, lifecycle actions and row descriptors. Remount and teardown remove
 listeners and row subscriptions; obsolete completions do not repaint old rows.
 The clear control presents busy state while its existing action owns the transaction.
 
+## Sky background
+
+`src/sky/starrySky.js` fills Cesium's `Scene#skyBox` slot with 9,096 Yale
+Bright Star Catalogue stars and a soft ESO/S. Brunier Milky Way. Both layers
+rotate from ICRF/J2000 into the Earth-fixed frame at the scene clock, with
+a TEME fallback while Cesium's IAU 2006 tables load. Bundled assets and
+their provenance are documented in `src/data/local_data/sky/README.md`.
+
+Anime fades out the Milky Way with its style intensity to avoid cel-shaded
+bands; the catalogue stars remain. A separate black 1×1 cube map preserves
+model environment lighting independently of the visible sky. The adapter
+is validated against Cesium 1.138.0 and must be revalidated on upgrades.
+
+`scripts/qa-anime-sky.mjs` checks asset readiness, visible Normal sky and
+Anime band coverage against a Vite dev server.
+`scripts/qa-sky-model-lighting.mjs` compares a lit `airplane.glb` against
+black and white environment maps in isolated scenes.
+
 ## Model atmosphere on Apple Metal
 
 Cesium's per-vertex model atmosphere is kept out of the pipeline on devices

scripts/build-bright-stars.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Build src/data/local_data/sky/bright_stars.json from the Yale Bright Star
+ * Catalogue, 5th Revised Edition (Hoffleit & Warren 1991).
+ *
+ * Source:   CDS VizieR catalogue V/50, https://cdsarc.cds.unistra.fr/viz-bin/cat/V/50
+ * Fetched:  https://cdsarc.cds.unistra.fr/ftp/V/50/catalog.gz
+ * Format:   fixed-width ASCII, 197 bytes per record, byte layout in
+ *           https://cdsarc.cds.unistra.fr/ftp/V/50/ReadMe
+ * License:  public domain (Yale University Observatory / NASA ADC); CDS asks
+ *           for an acknowledgement, which the Data attribution popover carries.
+ *
+ * Transform (deterministic):
+ *   1. J2000 RA/Dec (bytes 76-90), V magnitude (103-107) and B−V (110-114).
+ *   2. The 14 records without a J2000 position (novae and other objects later
+ *      found not to be stars) are dropped.
+ *   3. RA/Dec rounded to 3 decimals of a degree (3.6″ — a fraction of a pixel
+ *      at any field of view the globe uses), magnitudes to 2.
+ *   4. Missing B−V is stored as null; the renderer gives it a neutral colour.
+ *   5. Records keep catalogue (HR) order for a stable diff.
+ *
+ * Usage:
+ *   node scripts/build-bright-stars.mjs [catalog | catalog.gz]
+ * With no argument it downloads the catalogue from CDS.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { fileURLToPath } from 'node:url';
+
+const SOURCE_URL = 'https://cdsarc.cds.unistra.fr/ftp/V/50/catalog.gz';
+const OUT = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'src',
+  'data',
+  'local_data',
+  'sky',
+  'bright_stars.json',
+);
+
+/** Slice 1-based inclusive byte columns the way the CDS ReadMe numbers them. */
+function columns(line, from, to) {
+  return line.slice(from - 1, to).trim();
+}
+
+/** Parse a fixed-width float; blank fields are null. */
+function parseField(text) {
+  if (text === '') return null;
+  const value = Number(text);
+  return Number.isFinite(value) ? value : null;
+}
+
+/**
+ * Parse one BSC5 record. Returns null for records without a J2000 position
+ * or V magnitude.
+ */
+export function parseBscRecord(line) {
+  const hr = parseField(columns(line, 1, 4));
+  const raH = parseField(columns(line, 76, 77));
+  const raM = parseField(columns(line, 78, 79));
+  const raS = parseField(columns(line, 80, 83));
+  const sign = columns(line, 84, 84);
+  const deD = parseField(columns(line, 85, 86));
+  const deM = parseField(columns(line, 87, 88));
+  const deS = parseField(columns(line, 89, 90));
+  const vmag = parseField(columns(line, 103, 107));
+  const bv = parseField(columns(line, 110, 114));
+  if (
+    hr === null ||
+    raH === null ||
+    raM === null ||
+    raS === null ||
+    deD === null ||
+    deM === null ||
+    deS === null ||
+    vmag === null ||
+    (sign !== '+' && sign !== '-')
+  )
+    return null;
+  const raDeg = (raH + raM / 60 + raS / 3600) * 15;
+  const decDeg = (sign === '-' ? -1 : 1) * (deD + deM / 60 + deS / 3600);
+  return { hr, raDeg, decDeg, vmag, bv };
+}
+
+const round = (value, decimals) => {
+  const scale = 10 ** decimals;
+  return Math.round(value * scale) / scale;
+};
+
+/** Build the committed pack from the raw catalogue text. */
+export function buildStarPack(text, { fetched = null } = {}) {
+  const stars = [];
+  let dropped = 0;
+  for (const line of text.split('\n')) {
+    if (line.trim() === '') continue;
+    const record = parseBscRecord(line);
+    if (!record) {
+      dropped += 1;
+      continue;
+    }
+    stars.push(
+      round(record.raDeg, 3),
+      round(record.decDeg, 3),
+      round(record.vmag, 2),
+      record.bv === null ? null : round(record.bv, 2),
+    );
+  }
+  return {
+    meta: {
+      source:
+        'Yale Bright Star Catalogue, 5th Revised Ed. (Hoffleit & Warren 1991), CDS V/50',
+      url: SOURCE_URL,
+      license: 'public domain',
+      fetched,
+      frame: 'ICRF/J2000, epoch 2000.0',
+      columns: ['raDeg', 'decDeg', 'vmag', 'bv'],
+      count: stars.length / 4,
+      dropped,
+    },
+    stars,
+  };
+}
+
+async function readCatalogue(file) {
+  if (!file) {
+    const response = await fetch(SOURCE_URL);
+    if (!response.ok) throw new Error(`${SOURCE_URL}: HTTP ${response.status}`);
+    return zlib
+      .gunzipSync(Buffer.from(await response.arrayBuffer()))
+      .toString('latin1');
+  }
+  const bytes = fs.readFileSync(file);
+  return (file.endsWith('.gz') ? zlib.gunzipSync(bytes) : bytes).toString(
+    'latin1',
+  );
+}
+
+async function main() {
+  const [file] = process.argv.slice(2);
+  const text = await readCatalogue(file);
+  const pack = buildStarPack(text, {
+    fetched: new Date().toISOString().slice(0, 10),
+  });
+  // One star per line keeps the JSON compact and the diff readable.
+  const rows = [];
+  for (let i = 0; i < pack.stars.length; i += 4)
+    rows.push(JSON.stringify(pack.stars.slice(i, i + 4)).slice(1, -1));
+  const body = `{"meta":${JSON.stringify(pack.meta)},\n"stars":[\n${rows.join(',\n')}\n]}\n`;
+  fs.mkdirSync(path.dirname(OUT), { recursive: true });
+  fs.writeFileSync(OUT, body);
+  console.log(
+    `wrote ${pack.meta.count} stars (${pack.meta.dropped} dropped) → ${path.relative(process.cwd(), OUT)} (${body.length} bytes)`,
+  );
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

scripts/build-milky-way.mjs

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+/**
+ * Build the soft Milky Way cube map in src/data/local_data/sky/ from the ESO
+ * all-sky Milky Way panorama.
+ *
+ * Source page: https://www.eso.org/public/images/eso0932a/
+ * Fetched:     https://cdn.eso.org/images/original/eso0932a.tif
+ *              (6000×3000 8-bit sRGB TIFF, 27.7 MB; sha256 in README.md)
+ * Credit:      ESO/S. Brunier
+ * License:     CC BY 4.0 (https://www.eso.org/public/outreach/copyright/).
+ *              Modified: stars removed, blurred, reprojected to ICRF cube
+ *              faces and tone-mapped, as below.
+ * Frame:       plate carrée in galactic coordinates, centred on the Galactic
+ *              Centre, galactic longitude increasing to the left.
+ *
+ * Transform (deterministic):
+ *   1. Resample to WORK_WIDTH×WORK_WIDTH/2, sRGB to linear light.
+ *   2. Remove stars with a morphological opening: the renderer draws
+ *      catalogue stars itself, sharp and in the right place.
+ *   3. Paint out the planets the 2008–2010 exposures caught (PLANETS).
+ *   4. Blur, round on the sphere: σ = BLUR_DEG, widening to FAINT_BLUR_DEG
+ *      in the faint glow so unresolved stars leave no clumps.
+ *   5. Resample into six WebGL cube faces (uploaded without flipY) with the
+ *      ICRF axes: +X to the March equinox, +Z to the north celestial pole.
+ *   6. Median sky to black with a soft knee, brightest 0.01 % to ~97 %
+ *      white, on luminance to keep the hue; gamma 1/2.2, dither, WebP.
+ *
+ * Usage:
+ *   node scripts/build-milky-way.mjs <eso0932a.tif>
+ * Needs the sharp dev dependency.
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const FACE_SIZE = 1024;
+export const BLUR_DEG = 0.4;
+// Faint glow is grain of unresolved stars and needs the wide blur; bright
+// parts keep the fine one and their dust lanes. FAINT_RANGE (fraction of
+// black-to-white) is where the two blend.
+export const FAINT_BLUR_DEG = 2;
+const FAINT_RANGE = [0.005, 0.08];
+const WORK_WIDTH = 4096;
+const OPEN_RADIUS = 3;
+const WEBP_QUALITY = 96;
+// The median sky is black: above it the glow away from the plane reads as
+// grey blotches. SOFT_KNEE eases the cut in so it draws no edges.
+const BLACK_PERCENTILE = 0.5;
+const SOFT_KNEE = 0.03;
+const WHITE_PERCENTILE = 0.9999;
+const OUT_DIR = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'src',
+  'data',
+  'local_data',
+  'sky',
+);
+
+/**
+ * Bright planets in the panorama, galactic longitude/latitude in degrees and
+ * the radius painted over with the surrounding sky. By position both are
+ * Jupiter, in Sagittarius (2008) and Aquarius (2010); no catalogue star lies
+ * under either.
+ */
+export const PLANETS = Object.freeze([
+  { l: 13.4, b: -16.6, radiusDeg: 2.5 },
+  { l: 69.0, b: -58.4, radiusDeg: 2.5 },
+]);
+
+/** Cube faces in WebGL upload order. */
+export const CUBE_FACES = Object.freeze([
+  'positiveX',
+  'negativeX',
+  'positiveY',
+  'negativeY',
+  'positiveZ',
+  'negativeZ',
+]);
+export const FACE_FILE_SUFFIX = Object.freeze({
+  positiveX: 'px',
+  negativeX: 'nx',
+  positiveY: 'py',
+  negativeY: 'ny',
+  positiveZ: 'pz',
+  negativeZ: 'nz',
+});
+
+/**
+ * ICRF (J2000 equatorial) → galactic rotation, rows = galactic axes
+ * (Hipparcos catalogue, ESA SP-1200 vol. 1 §1.5.3).
+ */
+export const ICRF_TO_GALACTIC = Object.freeze([
+  [-0.0548755604162154, -0.873437090234885, -0.4838350155487132],
+  [0.4941094278755837, -0.4448296299600112, 0.7469822444972189],
+  [-0.867666149019004, -0.1980763734312015, 0.4559837761750669],
+]);
+
+/**
+ * Direction (not normalized) that the WebGL cube-map lookup sends to texel
+ * coordinate (s, t) ∈ [0, 1]² of `face`, t = 0 being the first image row.
+ * Inverse of the OpenGL ES 3.0 §3.8.10 major-axis table.
+ */
+export function cubeFaceDirection(face, s, t) {
+  const sc = 2 * s - 1;
+  const tc = 2 * t - 1;
+  switch (face) {
+    case 'positiveX':
+      return [1, -tc, -sc];
+    case 'negativeX':
+      return [-1, -tc, sc];
+    case 'positiveY':
+      return [sc, 1, tc];
+    case 'negativeY':
+      return [sc, -1, -tc];
+    case 'positiveZ':
+      return [sc, -tc, 1];
+    case 'negativeZ':
+      return [-sc, -tc, -1];
+    default:
+      throw new RangeError(`Unknown cube face ${face}`);
+  }
+}
+
+/** Rotate an ICRF direction into galactic coordinates. */
+export function icrfToGalactic([x, y, z]) {
+  return ICRF_TO_GALACTIC.map((row) => row[0] * x + row[1] * y + row[2] * z);
+}
+
+/**
+ * Map a direction to (u, v) ∈ [0, 1)² of a plate carrée centred on
+ * longitude 0 with longitude increasing to the left and v = 0 at +90°.
+ */
+export function directionToPlateCarree(x, y, z) {
+  const longitude = Math.atan2(y, x);
+  const latitude = Math.atan2(z, Math.hypot(x, y));
+  let u = 0.5 - longitude / (2 * Math.PI);
+  u -= Math.floor(u);
+  return [u, 0.5 - latitude / Math.PI];
+}
+
+/** Box widths whose three passes approximate a Gaussian of `sigma` (Kovesi). */
+function boxRadii(sigma) {
+  const ideal = Math.sqrt((12 * sigma * sigma) / 3 + 1);
+  let lower = Math.floor(ideal);
+  if (lower % 2 === 0) lower -= 1;
+  const upper = lower + 2;
+  const m = Math.round(
+    (12 * sigma * sigma - 3 * lower * lower - 12 * lower - 9) /
+      (-4 * lower - 4),
+  );
+  return [0, 1, 2].map((i) => ((i < m ? lower : upper) - 1) / 2);
+}
+
+/** Index along a line, wrapped or clamped at the ends. */
+function lineIndex(i, length, wrap) {
+  if (wrap) return ((i % length) + length) % length;
+  return i < 0 ? 0 : i >= length ? length - 1 : i;
+}
+
+/** Running-sum box blur of one strided line. */
+function boxLine(src, dst, offset, stride, length, radius, wrap) {
+  if (radius < 1) {
+    for (let i = 0; i < length; i++)
+      dst[offset + i * stride] = src[offset + i * stride];
+    return;
+  }
+  const r = wrap ? Math.min(radius, Math.floor((length - 1) / 2)) : radius;
+  const at = (i) => src[offset + lineIndex(i, length, wrap) * stride];
+  let sum = 0;
+  for (let i = -r; i <= r; i++) sum += at(i);
+  const scale = 1 / (2 * r + 1);
+  for (let i = 0; i < length; i++) {
+    dst[offset + i * stride] = sum * scale;
+    sum += at(i + r + 1) - at(i - r);
+  }
+}
+
+/** Minimum or maximum over a (2r+1) window of one strided line. */
+function extremumLine(src, dst, offset, stride, length, radius, wrap, pick) {
+  for (let i = 0; i < length; i++) {
+    let value = src[offset + lineIndex(i - radius, length, wrap) * stride];
+    for (let k = -radius + 1; k <= radius; k++)
+      value = pick(
+        value,
+        src[offset + lineIndex(i + k, length, wrap) * stride],
+      );
+    dst[offset + i * stride] = value;
+  }
+}
+
+/** Separable minimum or maximum filter over a plate-carrée plane, in place. */
+function extremumPlane(plane, width, height, radius, pick) {
+  const scratch = new Float32Array(plane.length);
+  for (let y = 0; y < height; y++)
+    extremumLine(plane, scratch, y * width, 1, width, radius, true, pick);
+  for (let x = 0; x < width; x++)
+    extremumLine(scratch, plane, x, width, height, radius, false, pick);
+}
+
+/** Blur one plate-carrée channel in place, round on the sphere. */
+function blurPlane(plane, width, height, sigmaPx) {
+  const scratch = new Float32Array(plane.length);
+  for (let y = 0; y < height; y++) {
+    const latitude = (0.5 - (y + 0.5) / height) * Math.PI;
+    const sigmaX = Math.min(
+      width / 4,
+      sigmaPx / Math.max(Math.cos(latitude), 1e-3),
+    );
+    for (const radius of boxRadii(sigmaX)) {
+      boxLine(plane, scratch, y * width, 1, width, Math.round(radius), true);
+      plane.set(scratch.subarray(y * width, (y + 1) * width), y * width);
+    }
+  }
+  for (const radius of boxRadii(sigmaPx)) {
+    for (let x = 0; x < width; x++)
+      boxLine(plane, scratch, x, width, height, Math.round(radius), false);
+    plane.set(scratch);
+  }
+}
+
+/** Unit vector for galactic longitude and latitude in degrees. */
+function galacticVector(l, b) {
+  const lr = (l * Math.PI) / 180;
+  const br = (b * Math.PI) / 180;
+  return [
+    Math.cos(br) * Math.cos(lr),
+    Math.cos(br) * Math.sin(lr),
+    Math.sin(br),
+  ];
+}
+
+/**
+ * Replace a disc of the sky with the median of the ring just outside it, per
+ * channel. A median, not a mean: the planet's diffraction spikes reach far
+ * past the disc and would lift a mean well above the sky. The blur that
+ * follows hides the seam.
+ */
+function paintOut(planes, width, height, { l, b, radiusDeg }) {
+  const centre = galacticVector(l, b);
+  const inner = Math.cos((radiusDeg * Math.PI) / 180);
+  const outer = Math.cos(((radiusDeg + 1) * Math.PI) / 180);
+  const disc = [];
+  const ring = [];
+  const span = Math.ceil(((radiusDeg + 1) / 180) * height);
+  const row = Math.round((0.5 - b / 180) * height);
+  for (let y = Math.max(0, row - span); y < Math.min(height, row + span); y++) {
+    const latitude = 90 - ((y + 0.5) * 180) / height;
+    for (let x = 0; x < width; x++) {
+      const longitude = (0.5 - (x + 0.5) / width) * 360;
+      const p = galacticVector(longitude, latitude);
+      const cos = p[0] * centre[0] + p[1] * centre[1] + p[2] * centre[2];
+      if (cos >= inner) disc.push(y * width + x);
+      else if (cos >= outer) ring.push(y * width + x);
+    }
+  }
+  for (const plane of planes) {
+    const values = Float32Array.from(ring, (index) => plane[index]).sort();
+    const median = values[values.length >> 1];
+    for (const index of disc) plane[index] = median;
+  }
+}
+
+/** Bilinear sample with longitude wrap and latitude clamp. */
+function samplePlane(plane, width, height, u, v) {
+  const fx = u * width - 0.5;
+  const fy = Math.min(Math.max(v * height - 0.5, 0), height - 1);
+  const x0 = Math.floor(fx);
+  const y0 = Math.floor(fy);
+  const ax = fx - x0;
+  const ay = fy - y0;
+  const xa = ((x0 % width) + width) % width;
+  const xb = (xa + 1) % width;
+  const yb = Math.min(y0 + 1, height - 1);
+  const top = plane[y0 * width + xa] * (1 - ax) + plane[y0 * width + xb] * ax;
+  const bottom =
+    plane[yb * width + xa] * (1 - ax) + plane[yb * width + xb] * ax;
+  return top * (1 - ay) + bottom * ay;
+}
+
+/** Deterministic hash noise in [-0.5, 0.5) for dithering. */
+function dither(index, channel) {
+  let h = (index * 374761393 + channel * 668265263) | 0;
+  h = Math.imul(h ^ (h >>> 13), 1274126177);
+  h ^= h >>> 16;
+  return (h >>> 0) / 4294967296 - 0.5;
+}
+
+/**
+ * Black level with a soft knee: 0 at and below the level, then a quadratic
+ * ease that joins the straight line, so faint sky fades out instead of
+ * ending in a contour.
+ */
+export function softBlack(x, knee = SOFT_KNEE) {
+  return x <= 0 ? 0 : (x * x) / (x + knee);
+}
+
+export function smoothstep(edge0, edge1, x) {
+  const t = Math.min(Math.max((x - edge0) / (edge1 - edge0), 0), 1);
+  return t * t * (3 - 2 * t);
+}
+
+/**
+ * Per pixel, keep `fine` where `weight(luminance of coarse)` is 1 and take
+ * `coarse` where it is 0, blending in between. The weight follows the coarse
+ * copy, so it is smooth itself and draws no seams along dark lanes. Writes
+ * into `fine`.
+ */
+function blendByBrightness(fine, coarse, weight) {
+  const [r] = fine;
+  for (let i = 0; i < r.length; i++) {
+    const w = weight((coarse[0][i] + coarse[1][i] + coarse[2][i]) / 3);
+    for (let c = 0; c < 3; c++)
+      fine[c][i] = coarse[c][i] + (fine[c][i] - coarse[c][i]) * w;
+  }
+}
+
+/** Value at `fraction` of the sorted luminance. */
+function luminancePercentile(planes, fraction) {
+  const [r, g, b] = planes;
+  const lum = new Float32Array(r.length);
+  for (let i = 0; i < lum.length; i++) lum[i] = (r[i] + g[i] + b[i]) / 3;
+  lum.sort();
+  return lum[Math.min(lum.length - 1, Math.floor(fraction * lum.length))];
+}
+
+const srgbToLinear = (value) =>
+  value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+
+async function decodePanorama(sharp, file) {
+  const width = WORK_WIDTH;
+  const height = WORK_WIDTH / 2;
+  const raw = await sharp(file)
+    .resize(width, height, { fit: 'fill', kernel: 'lanczos3' })
+    .removeAlpha()
+    .raw()
+    .toBuffer();
+  const lut = Float32Array.from({ length: 256 }, (_, i) =>
+    srgbToLinear(i / 255),
+  );
+  const planes = [0, 1, 2].map(() => new Float32Array(width * height));
+  for (let i = 0; i < width * height; i++)
+    for (let c = 0; c < 3; c++) planes[c][i] = lut[raw[i * 3 + c]];
+  return { width, height, planes };
+}
+
+async function main() {
+  const [file] = process.argv.slice(2);
+  if (!file) throw new Error('usage: build-milky-way.mjs <eso0932a.tif>');
+  const { default: sharp } = await import('sharp');
+  const { width, height, planes } = await decodePanorama(sharp, file);
+  const sigmaPx = (BLUR_DEG / 180) * height;
+  for (const plane of planes) {
+    extremumPlane(plane, width, height, OPEN_RADIUS, Math.min);
+    extremumPlane(plane, width, height, OPEN_RADIUS, Math.max);
+  }
+  // After the opening: it sinks the starry sky to the dark gaps between
+  // stars, and a fill taken before it would stay brighter than the sky.
+  for (const planet of PLANETS) paintOut(planes, width, height, planet);
+  const wide = planes.map((plane) => Float32Array.from(plane));
+  for (const plane of planes) blurPlane(plane, width, height, sigmaPx);
+  for (const plane of wide)
+    blurPlane(plane, width, height, (FAINT_BLUR_DEG / 180) * height);
+  // Levels from the fine blur, so the blend weight and the output share
+  // them; the blend moves the median only in the faint sky it smooths.
+  const black = luminancePercentile(planes, BLACK_PERCENTILE);
+  const white = luminancePercentile(planes, WHITE_PERCENTILE);
+  blendByBrightness(planes, wide, (luminance) =>
+    smoothstep(
+      FAINT_RANGE[0],
+      FAINT_RANGE[1],
+      (luminance - black) / (white - black),
+    ),
+  );
+  let total = 0;
+  for (const face of CUBE_FACES) {
+    const pixels = Buffer.alloc(FACE_SIZE * FACE_SIZE * 3);
+    for (let j = 0; j < FACE_SIZE; j++) {
+      for (let i = 0; i < FACE_SIZE; i++) {
+        const direction = cubeFaceDirection(
+          face,
+          (i + 0.5) / FACE_SIZE,
+          (j + 0.5) / FACE_SIZE,
+        );
+        const [u, v] = directionToPlateCarree(...icrfToGalactic(direction));
+        const index = j * FACE_SIZE + i;
+        const rgb = [0, 1, 2].map((c) =>
+          samplePlane(planes[c], width, height, u, v),
+        );
+        const luminance = (rgb[0] + rgb[1] + rgb[2]) / 3;
+        const level = softBlack((luminance - black) / (white - black));
+        for (let c = 0; c < 3; c++) {
+          // Scale every channel by the luminance curve to keep the hue.
+          const linear = luminance > 0 ? (rgb[c] / luminance) * level : 0;
+          const encoded = Math.min(linear, 1) ** (1 / 2.2) * 255;
+          pixels[index * 3 + c] = Math.min(
+            255,
+            Math.max(0, Math.round(encoded + dither(index, c))),
+          );
+        }
+      }
+    }
+    const out = path.join(OUT_DIR, `milkyway_${FACE_FILE_SUFFIX[face]}.webp`);
+    const info = await sharp(pixels, {
+      raw: { width: FACE_SIZE, height: FACE_SIZE, channels: 3 },
+    })
+      .webp({ quality: WEBP_QUALITY, smartSubsample: true, effort: 6 })
+      .toFile(out);
+    total += info.size;
+    console.log(`${path.relative(process.cwd(), out)}: ${info.size} bytes`);
+  }
+  console.log(`total ${total} bytes`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

scripts/format-scope.json

@@ -1071,7 +1071,16 @@
   "scripts/assemble-changelog.mjs",
   "src/tooling/changelogFragments.test.mjs",
   "src/data/gbfsProxyRateLimit.test.mjs",
+  "src/data/routeSegment.test.mjs",
   "src/terrainHeightsBounds.test.mjs",
+  "scripts/build-bright-stars.mjs",
+  "scripts/build-milky-way.mjs",
+  "src/sky/stars.test.mjs",
+  "src/sky/starrySky.test.mjs",
+  "src/tooling/skyAssets.test.mjs",
+  "src/tooling/skyAssets.paintOut.test.mjs",
+  "scripts/qa-anime-sky.mjs",
+  "scripts/qa-sky-model-lighting.mjs",
   "server/providers/overpass/requestAdmission.test.mjs",
   "src/tooling/trackArrivalObservation.test.mjs",
   "src/ui/styles/status-badge.css",

scripts/package-boundaries.json

@@ -22,7 +22,14 @@
   },
   "viewer": {
     "exports": ["./application/viewer"],
-    "modules": ["src/app/viewer.js", "src/app/atmosphereCompat.js"],
+    "modules": [
+      "src/app/viewer.js",
+      "src/app/atmosphereCompat.js",
+      "src/sky/starrySky.js",
+      "src/sky/stars.js",
+      "src/data/bundledJson.js",
+      "src/renderGovernor.js"
+    ],
     "external": ["cesium"]
   },
   "vite-build": {
@@ -1730,6 +1737,8 @@
       "src/app/surfaceServices.js",
       "src/app/tools.js",
       "src/app/viewer.js",
+      "src/sky/starrySky.js",
+      "src/sky/stars.js",
       "src/app/atmosphereCompat.js",
       "src/bloom.js",
       "src/camera.js",

scripts/qa-anime-sky.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * qa-anime-sky — the anime style must leave the sky without bands.
+ *
+ * Anime's luminance bands turn the faint Milky Way into blotches, so
+ * src/ui/visualEffects.js fades the glow out with the style. Headless against
+ * a Vite dev server, both sky assets must be ready. Normal must show the
+ * Galactic Centre glow (at least 2 % of pixels at luma >= 10/255), then
+ * Anime must retain stars while at most 0.5 % reaches the first cel band.
+ * The Normal baseline measured 43 % in headless Chromium at 1000×700;
+ * the 2 % floor leaves room for GPU differences while rejecting a black sky.
+ *
+ * Usage: node scripts/qa-anime-sky.mjs [--url http://localhost:4333/]
+ * Exit: 0 pass, 1 fail, 2 the anime style was not reached.
+ */
+import puppeteer from 'puppeteer';
+
+const i = process.argv.indexOf('--url');
+const URL_ =
+  i > 0 && process.argv[i + 1] ? process.argv[i + 1] : 'http://localhost:4333/';
+
+const browser = await puppeteer.launch({
+  headless: 'new',
+  args: ['--no-sandbox', '--ignore-gpu-blocklist'],
+});
+try {
+  const page = await browser.newPage();
+  await page.setRequestInterception(true);
+  page.on('request', (request) => {
+    const host = new URL(request.url()).hostname;
+    if (host.endsWith('halfpixel.ai') || host.includes('worldfx'))
+      request.abort();
+    else request.continue();
+  });
+  page.on('pageerror', (e) => console.log('PAGEERR', String(e).slice(0, 300)));
+  await page.setViewport({ width: 1000, height: 700 });
+  await page.evaluateOnNewDocument(() =>
+    localStorage.setItem('gev:first-run-mission:v1', 'suppressed'),
+  );
+  await page.goto(URL_, { waitUntil: 'domcontentloaded' });
+  await page.waitForFunction(() => window.__godsEyeView?.viewer?.scene, {
+    timeout: 120000,
+  });
+  await page.waitForFunction(
+    () => {
+      const sky = window.__godsEyeView.viewer.scene.skyBox;
+      return (
+        sky?._milkyWayCubeMap &&
+        sky?._starCommand &&
+        document.getElementById('loading-screen')?.classList.contains('hidden')
+      );
+    },
+    { timeout: 60000 },
+  );
+  const r = await page.evaluate(async () => {
+    const entry = performance
+      .getEntriesByType('resource')
+      .map((e) => e.name)
+      .find((n) => /\.vite\/deps\/cesium\.js/.test(n));
+    if (!entry)
+      throw new Error(
+        'run against the Vite dev server (needs .vite/deps/cesium.js)',
+      );
+    const C = await import(entry),
+      g = window.__godsEyeView,
+      v = g.viewer,
+      s = v.scene;
+    g.styleManager.setStyle('normal', { userInitiated: true });
+    const t = v.clock.currentTime;
+    await C.Transforms.preloadIcrfFixed(
+      new C.TimeInterval({
+        start: C.JulianDate.addDays(t, -1, new C.JulianDate()),
+        stop: C.JulianDate.addDays(t, 1, new C.JulianDate()),
+      }),
+    );
+    const m = C.Transforms.computeIcrfToFixedMatrix(t);
+    const ra = C.Math.toRadians(266.4),
+      dec = C.Math.toRadians(-29);
+    const look = C.Matrix3.multiplyByVector(
+      m,
+      new C.Cartesian3(
+        Math.cos(dec) * Math.cos(ra),
+        Math.cos(dec) * Math.sin(ra),
+        Math.sin(dec),
+      ),
+      new C.Cartesian3(),
+    );
+    const north = C.Matrix3.multiplyByVector(
+      m,
+      C.Cartesian3.UNIT_Z,
+      new C.Cartesian3(),
+    );
+    const right = C.Cartesian3.normalize(
+      C.Cartesian3.cross(look, north, new C.Cartesian3()),
+      new C.Cartesian3(),
+    );
+    s.camera.cancelFlight();
+    s.tweens.removeAll();
+    s.camera.setView({
+      destination: C.Cartesian3.multiplyByScalar(look, 3e7, new C.Cartesian3()),
+      orientation: {
+        direction: look,
+        up: C.Cartesian3.cross(right, look, new C.Cartesian3()),
+      },
+    });
+    const gl = s.context._gl,
+      w = gl.drawingBufferWidth,
+      h = gl.drawingBufferHeight,
+      px = new Uint8Array(w * h * 4);
+    const measure = async () => {
+      await new Promise((res) => setTimeout(res, 2500));
+      s.requestRender();
+      s.render();
+      gl.readPixels(0, 0, w, h, gl.RGBA, gl.UNSIGNED_BYTE, px);
+      let banded = 0;
+      let visible = 0;
+      for (let i = 0; i < px.length; i += 4) {
+        const luma = 0.299 * px[i] + 0.587 * px[i + 1] + 0.114 * px[i + 2];
+        if (luma >= 51) banded++;
+        if (luma >= 10) visible++;
+      }
+      return { banded, visible };
+    };
+    const normal = await measure();
+    g.styleManager.setStyle('anime', { userInitiated: true });
+    const anime = await measure();
+    let animeOn = false;
+    for (let i = 0; i < s.postProcessStages.length; i++) {
+      const stage = s.postProcessStages.get(i);
+      if (stage.name === 'godsEyeView_anime')
+        animeOn = stage.enabled && stage.uniforms.intensity > 0.99;
+    }
+    return {
+      total: px.length / 4,
+      normal,
+      ...anime,
+      assetsReady: Boolean(s.skyBox._milkyWayCubeMap && s.skyBox._starCommand),
+      visibility: s.skyBox.milkyWayVisibility,
+      animeOn,
+    };
+  });
+  const tag =
+    !r.animeOn || !r.assetsReady
+      ? 'UNREACHED'
+      : r.normal.visible >= 0.02 * r.total &&
+          r.banded > 0 &&
+          r.banded <= 0.005 * r.total &&
+          r.visibility === 0
+        ? 'PASS'
+        : 'FAIL';
+  console.log(
+    `${tag}: ${r.banded} of ${r.total} sky pixels at or above the first cel band (luma >= 0.2)\n     ${JSON.stringify(r)}`,
+  );
+  process.exitCode = tag === 'PASS' ? 0 : tag === 'FAIL' ? 1 : 2;
+} catch (error) {
+  console.error(`UNREACHED: ${error.message}`);
+  process.exitCode = 2;
+} finally {
+  await browser.close();
+}

scripts/qa-sky-model-lighting.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * Lit airplane regression: StarrySky must match a black environment baseline.
+ * A white environment is a positive control: it must visibly brighten the
+ * same model. Each case uses a fresh scene and dynamic environment map.
+ * Usage: node scripts/qa-sky-model-lighting.mjs [--url http://localhost:4333/]
+ */
+import assert from 'node:assert/strict';
+import puppeteer from 'puppeteer';
+
+const i = process.argv.indexOf('--url');
+const base = i > 0 ? process.argv[i + 1] : 'http://localhost:4333/';
+const url = new URL('/__qa_sky_model__', base);
+const browser = await puppeteer.launch({
+  headless: true,
+  args: ['--no-sandbox', '--ignore-gpu-blocklist'],
+});
+try {
+  const page = await browser.newPage();
+  page.on('pageerror', (error) => console.log('PAGEERR', error.message));
+  await page.setRequestInterception(true);
+  page.on('request', (request) => {
+    if (request.url() === url.href)
+      request.respond({
+        contentType: 'text/html',
+        body: '<!doctype html><html><body></body></html>',
+      });
+    else if (new URL(request.url()).origin !== url.origin) request.abort();
+    else request.continue();
+  });
+  await page.goto(url.href);
+  const results = await page.evaluate(async () => {
+    window.CESIUM_BASE_URL = '/cesium/';
+    // Use StarrySky's exact Vite dependency URL, including its version query.
+    const source = await fetch('/src/sky/starrySky.js').then((r) => r.text());
+    const cesiumUrl = source.match(
+      /from ["']([^"']*\/cesium\.js[^"']*)["']/,
+    )?.[1];
+    if (!cesiumUrl) throw new Error('run against the Vite dev server');
+    const C = await import(cesiumUrl);
+    const { StarrySky } = await import('/src/sky/starrySky.js');
+    const time = C.JulianDate.fromIso8601('2026-10-19T00:00:00Z');
+    const results = {};
+    for (const kind of ['black', 'starry', 'white']) {
+      const canvas = document.createElement('canvas');
+      canvas.width = 400;
+      canvas.height = 300;
+      document.body.append(canvas);
+      const scene = new C.Scene({ canvas });
+      scene.rethrowRenderErrors = true;
+      let cubeMap;
+      try {
+        scene.backgroundColor = C.Color.BLACK;
+        scene.light = new C.DirectionalLight({
+          direction: new C.Cartesian3(1, 0, 0),
+          intensity: 0.2,
+        });
+        if (kind === 'starry') {
+          scene.skyBox = new StarrySky({ requestRender() {} });
+          scene.skyBox._loading = true; // visible sky is outside this probe
+        } else {
+          const value = kind === 'white' ? 255 : 0;
+          const face = {
+            width: 1,
+            height: 1,
+            arrayBufferView: new Uint8Array([value, value, value, 255]),
+          };
+          cubeMap = new C.CubeMap({
+            context: scene.context,
+            source: Object.fromEntries(
+              [...C.CubeMap.faceNames()].map((name) => [name, face]),
+            ),
+          });
+          scene.skyBox = { _cubeMap: cubeMap, update() {}, destroy() {} };
+        }
+        const position = C.Cartesian3.fromDegrees(0, 0, 10000);
+        const model = await C.Model.fromGltfAsync({
+          url: '/models/airplane.glb',
+          modelMatrix: C.Transforms.eastNorthUpToFixedFrame(position),
+        });
+        scene.primitives.add(model);
+        scene.camera.lookAt(position, new C.HeadingPitchRange(0.4, -0.5, 45));
+        let framed = false;
+        for (let frame = 0; frame < 240; frame++) {
+          scene.initializeFrame();
+          scene.render(time);
+          if (model.ready && !framed) {
+            scene.camera.viewBoundingSphere(
+              model.boundingSphere,
+              new C.HeadingPitchRange(
+                0.4,
+                -0.5,
+                model.boundingSphere.radius * 3,
+              ),
+            );
+            framed = true;
+          }
+          await new Promise(requestAnimationFrame);
+        }
+        if (!model.ready || !model.environmentMapManager.radianceCubeMap)
+          throw new Error(`${kind}: model or dynamic lighting did not load`);
+        scene.initializeFrame();
+        scene.render(time);
+        const gl = scene.context._gl;
+        const px = new Uint8Array(canvas.width * canvas.height * 4);
+        gl.readPixels(
+          0,
+          0,
+          canvas.width,
+          canvas.height,
+          gl.RGBA,
+          gl.UNSIGNED_BYTE,
+          px,
+        );
+        let total = 0;
+        let visible = 0;
+        for (let p = 0; p < px.length; p += 4) {
+          const luma = 0.299 * px[p] + 0.587 * px[p + 1] + 0.114 * px[p + 2];
+          total += luma;
+          if (luma > 1) visible++;
+        }
+        results[kind] = { total, visible };
+      } finally {
+        scene.destroy();
+        cubeMap?.destroy();
+        canvas.remove();
+      }
+    }
+    return results;
+  });
+  console.log(JSON.stringify(results));
+  assert.ok(results.black.visible > 100, 'the lit model must be visible');
+  assert.ok(
+    Math.abs(results.starry.total - results.black.total) <=
+      results.black.total * 0.01,
+    'StarrySky must match black environment lighting within 1%',
+  );
+  assert.ok(
+    results.white.total > results.black.total * 1.03,
+    'white environment control must brighten the model by at least 3%',
+  );
+  console.log(
+    'PASS: lit airplane matches black sky; white control is brighter',
+  );
+} finally {
+  await browser.close();
+}

src/app/application.test.mjs

@@ -219,6 +219,17 @@ test('the separate viewer export imports without constructing a browser viewer',
   assert.throws(() => createApplicationViewer({}), /containers are required/);
 });
 
+test('the viewer gets the starry sky as an option, which keeps the Sun and Moon', async () => {
+  const { applicationViewerOptions } = await import('./viewer.js');
+  const { StarrySky } = await import('../sky/starrySky.js');
+  const creditContainer = {};
+  const options = applicationViewerOptions(creditContainer);
+  // CesiumWidget skips scene.sun and scene.moon when skyBox is false.
+  assert.ok(options.skyBox instanceof StarrySky);
+  assert.equal(options.creditContainer, creditContainer);
+  options.skyBox.destroy();
+});
+
 function pinchFixture({ zoomEventTypes } = {}) {
   const handlers = new Set();
   const relayed = [];

src/app/viewer.js

@@ -1,5 +1,6 @@
 import * as Cesium from 'cesium';
 import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js';
+import { StarrySky } from '../sky/starrySky.js';
 
 const PINCH_ZOOM_MULTIPLIER = 8;
 const MAX_PINCH_PIXEL_DELTA = 120;
@@ -102,11 +103,9 @@ export function installTrackpadPinchZoom(
   };
 }
 
-/** Create the standard globe viewer in caller-owned, visible containers. */
+/** Cesium.Viewer options of the standard globe viewer. */
-export function createApplicationViewer({ container, creditContainer }) {
+export function applicationViewerOptions(creditContainer) {
-  if (!container || !creditContainer)
+  return {
-    throw new TypeError('Viewer and credit containers are required');
-  const viewer = new Cesium.Viewer(container, {
     timeline: false,
     animation: false,
     baseLayerPicker: false,
@@ -119,10 +118,23 @@ export function createApplicationViewer({ container, creditContainer }) {
     selectionIndicator: false,
     infoBox: false,
     baseLayer: false,
+    // Replaces the blocky Tycho-2 default. An option, not `skyBox: false`,
+    // which would also stop CesiumWidget from creating the Sun and Moon.
+    skyBox: new StarrySky(),
     creditContainer,
     msaaSamples: 4,
     contextOptions: { webgl: { preserveDrawingBuffer: true } },
-  });
+  };
+}
+
+/** Create the standard globe viewer in caller-owned, visible containers. */
+export function createApplicationViewer({ container, creditContainer }) {
+  if (!container || !creditContainer)
+    throw new TypeError('Viewer and credit containers are required');
+  const viewer = new Cesium.Viewer(
+    container,
+    applicationViewerOptions(creditContainer),
+  );
   try {
     viewer.targetFrameRate = 60;
     // Before any tile builds a draw command: Cesium's per-vertex model

src/data/dataCredits.js

@@ -429,6 +429,13 @@ export const DATA_CREDITS = [
       'ECMWF does not accept any liability whatsoever for any error or omission in the data, their availability, or for any loss or damage arising from their use.',
   },
   // ── Bundled snapshots ───────────────────────────────────────────
+  {
+    key: 'sky-background',
+    html:
+      'Stars: <a href="https://cdsarc.cds.unistra.fr/viz-bin/cat/V/50" target="_blank" rel="noopener">Yale Bright Star Catalogue</a> ' +
+      '(Hoffleit &amp; Warren, via CDS). Milky Way: <a href="https://www.eso.org/public/images/eso0932a/" target="_blank" rel="noopener">ESO/S. Brunier</a> ' +
+      '(<a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="noopener">CC BY 4.0</a>; stars removed, blurred and reprojected)',
+  },
   {
     key: 'dams',
     html: 'Dams: Open Infrastructure Map',

src/data/local_data/sky/README.md

@@ -0,0 +1,51 @@
+# Sky background
+
+Catalogue stars over a soft Milky Way, drawn by `src/sky/starrySky.js` in
+place of Cesium's blocky Tycho-2 sky box.
+
+| File | Content | Size |
+| ---- | ------- | ---- |
+| `bright_stars.json` | 9,096 stars: J2000 RA/Dec, V magnitude, B−V | 235 KB |
+| `milkyway_{px,nx,py,ny,pz,nz}.webp` | Milky Way glow, six 1024² cube faces, no stars | 62 KB |
+
+## Stars — Yale Bright Star Catalogue
+
+**Source:** 5th Revised Edition (Hoffleit & Warren 1991), CDS catalogue
+[V/50](https://cdsarc.cds.unistra.fr/viz-bin/cat/V/50), file
+`https://cdsarc.cds.unistra.fr/ftp/V/50/catalog.gz` (sha256
+`3dc44b1e90be8fbe5bcc7656032560f51275f985c7e3f783c9028e1838ec7bed`, fetched
+2026-10-19).
+
+**License:** public domain. CDS asks for an acknowledgement; the "Data
+attribution" popover carries it.
+
+**Build:** `node scripts/build-bright-stars.mjs [catalog.gz]`. Drops the 14
+records without a J2000 position; rounds RA/Dec to 0.001° and magnitudes to
+0.01.
+
+## Milky Way — ESO/S. Brunier
+
+**Source:** ESO image [eso0932a](https://www.eso.org/public/images/eso0932a/),
+`https://cdn.eso.org/images/original/eso0932a.tif` (6000×3000 sRGB TIFF, sha256
+`10f209ab83e1fd89e7fa1ed70277ffc6ed19c43549f04ec637c6806d98aff035`, fetched
+2026-10-19).
+
+**License:** [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+**Credit: ESO/S. Brunier.**
+
+**Changes made** (CC BY 4.0 asks for them): resampled to 4096×2048; stars
+removed; two images of Jupiter painted over; blurred (0.4°, 2° in the faint
+glow); reprojected to ICRF cube faces; black level at the median sky; saved as
+WebP. Build: `node scripts/build-milky-way.mjs <eso0932a.tif>`.
+
+The panorama's stars sit up to ~2° off; that is invisible in the blurred glow,
+and every sharp star comes from the catalogue.
+
+NASA SVS "Deep Star Maps 2020" was not used: it derives from Gaia DR2, which
+ESA licenses CC BY-NC 3.0 IGO.
+
+## Frame
+
+Both layers are in ICRF/J2000. The cube faces use the WebGL face layout, +X
+to the March equinox and +Z to the north celestial pole, uploaded without
+`flipY`.

src/sky/starrySky.js

@@ -0,0 +1,451 @@
+import * as Cesium from 'cesium';
+import { loadBundledJson } from '../data/bundledJson.js';
+import { governorRequestRender } from '../renderGovernor.js';
+import { buildStarVertices, STAR_VERTEX_FLOATS } from './stars.js';
+
+/**
+ * Space background in the `Scene#skyBox` slot: catalogue stars as point
+ * sprites over a soft Milky Way cube map, both turned by one ICRF→fixed
+ * rotation at the scene clock (TEME until Cesium's tables load). Scene runs
+ * the command from `update()` first in the environment pass, so the sky
+ * stays behind everything without depth. Revalidate on engine upgrades.
+ */
+export const STARRY_SKY_CESIUM_VERSION = '1.138.0';
+
+/** Brightness of the Milky Way glow; the stars carry the sky. */
+export const MILKY_WAY_INTENSITY = 0.4;
+/** Clock change, in seconds, below which the sky rotation is reused. */
+export const SKY_ROTATION_EPSILON_SECONDS = 1;
+
+const STAR_PACK_URL = new URL(
+  '../data/local_data/sky/bright_stars.json',
+  import.meta.url,
+);
+const MILKY_WAY_FACE_URLS = Object.freeze({
+  positiveX: new URL(
+    '../data/local_data/sky/milkyway_px.webp',
+    import.meta.url,
+  ),
+  negativeX: new URL(
+    '../data/local_data/sky/milkyway_nx.webp',
+    import.meta.url,
+  ),
+  positiveY: new URL(
+    '../data/local_data/sky/milkyway_py.webp',
+    import.meta.url,
+  ),
+  negativeY: new URL(
+    '../data/local_data/sky/milkyway_ny.webp',
+    import.meta.url,
+  ),
+  positiveZ: new URL(
+    '../data/local_data/sky/milkyway_pz.webp',
+    import.meta.url,
+  ),
+  negativeZ: new URL(
+    '../data/local_data/sky/milkyway_nz.webp',
+    import.meta.url,
+  ),
+});
+
+// Directions, not points: w = 0 drops the camera translation, and z just
+// under w keeps every fragment at the far plane, inside any frustum.
+const SKY_DIRECTION_GLSL = `
+uniform mat3 u_icrfToFixed;
+vec4 skyClipPosition(vec3 icrfDirection)
+{
+    vec3 eye = czm_viewRotation * (u_icrfToFixed * icrfDirection);
+    vec4 clip = czm_projection * vec4(eye, 0.0);
+    clip.z = clip.w * 0.99999;
+    return clip;
+}
+`;
+
+const MILKY_WAY_VS = `${SKY_DIRECTION_GLSL}
+in vec3 position;
+out vec3 v_direction;
+void main()
+{
+    gl_Position = skyClipPosition(position);
+    v_direction = position;
+}
+`;
+
+const MILKY_WAY_FS = `
+uniform samplerCube u_milkyWay;
+uniform float u_intensity;
+in vec3 v_direction;
+void main()
+{
+    vec3 color = czm_textureCube(u_milkyWay, normalize(v_direction)).rgb * u_intensity;
+    // Interleaved-gradient dither: the dim glow spans only a few 8-bit steps.
+    float noise = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))));
+    color = max(color + (noise - 0.5) / 255.0, 0.0);
+    out_FragColor = vec4(czm_gammaCorrect(color), 1.0);
+}
+`;
+
+const STAR_VS = `${SKY_DIRECTION_GLSL}
+in vec3 position;
+in float sigma;
+in vec4 color;
+out vec4 v_color;
+out float v_sigma;
+out float v_radius;
+void main()
+{
+    gl_Position = skyClipPosition(position);
+    // σ is in CSS pixels; the sprite holds ±3σ plus a pixel of margin.
+    v_sigma = sigma * czm_pixelRatio;
+    v_radius = ceil(3.0 * v_sigma) + 1.0;
+    gl_PointSize = 2.0 * v_radius;
+    v_color = color;
+}
+`;
+
+const STAR_FS = `
+in vec4 v_color;
+in float v_sigma;
+in float v_radius;
+void main()
+{
+    vec2 offset = (gl_PointCoord - 0.5) * (2.0 * v_radius);
+    float alpha = v_color.a *
+        exp(-0.5 * dot(offset, offset) / (v_sigma * v_sigma));
+    if (alpha < 1.0 / 512.0) discard;
+    out_FragColor = vec4(czm_gammaCorrect(v_color.rgb) * alpha, alpha);
+}
+`;
+
+/** Pick the ICRF→fixed rotation for `time`, or TEME while tables load. */
+export function computeSkyRotation(time, result) {
+  const { Transforms } = Cesium;
+  const icrf = Transforms.computeIcrfToFixedMatrix(time, result);
+  if (icrf) return { matrix: icrf, precise: true };
+  return {
+    matrix: Transforms.computeTemeToPseudoFixedMatrix(time, result),
+    precise: false,
+  };
+}
+
+/** Whether a cached rotation at `cachedTime` still serves `time`. */
+export function isSkyRotationCurrent(cachedTime, time) {
+  return (
+    cachedTime !== undefined &&
+    Math.abs(Cesium.JulianDate.secondsDifference(time, cachedTime)) <
+      SKY_ROTATION_EPSILON_SECONDS
+  );
+}
+
+export class StarrySky {
+  /**
+   * @param {object} [options]
+   * @param {() => void} [options.requestRender] renders one frame when an
+   *   asset or the precise rotation arrives; the idle governor by default.
+   */
+  constructor({
+    requestRender = () => governorRequestRender('sky-assets'),
+  } = {}) {
+    /** Matches `SkyBox#show`. */
+    this.show = true;
+    this.milkyWayIntensity = MILKY_WAY_INTENSITY;
+    /** 0..1 multiplier a style sets to hide the glow (see visualEffects.js). */
+    this.milkyWayVisibility = 1;
+    this._requestRender = requestRender;
+    this._rotation = Cesium.Matrix3.clone(Cesium.Matrix3.IDENTITY);
+    this._rotationTime = undefined;
+    this._rotationPrecise = false;
+    this._icrfRequest = undefined;
+    this._icrfUnavailable = false;
+    this._icrfMissing = undefined;
+    this._loading = false;
+    this._starData = undefined;
+    this._faceImages = undefined;
+    // 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;
+    this._starCommand = undefined;
+    this._useHdr = undefined;
+    this._destroyed = false;
+    const uniforms = {
+      u_icrfToFixed: () => this._rotation,
+    };
+    this._milkyWayUniforms = {
+      ...uniforms,
+      u_milkyWay: () => this._milkyWayCubeMap,
+      u_intensity: () => this.milkyWayIntensity * this.milkyWayVisibility,
+    };
+    this._starUniforms = uniforms;
+    const commands = [];
+    this._commands = commands;
+    // The environment pass reads `derivedCommands` (log depth, HDR, picking)
+    // before calling `execute`; none apply to a far-plane background.
+    this._compositeCommand = {
+      derivedCommands: {},
+      execute(context, passState) {
+        for (const command of commands) command.execute(context, passState);
+      },
+    };
+  }
+
+  /** Start loading assets; failures leave a plain black sky. */
+  _load() {
+    if (this._loading) return;
+    this._loading = true;
+    loadBundledJson(STAR_PACK_URL)
+      .then((pack) => {
+        if (this._destroyed) return;
+        this._starData = buildStarVertices(pack);
+        this._requestRender();
+      })
+      .catch((error) =>
+        console.warn('[sky] star catalogue unavailable', error),
+      );
+    const faces = Object.entries(MILKY_WAY_FACE_URLS);
+    Promise.all(
+      faces.map(([, url]) => Cesium.Resource.fetchImage({ url: url.href })),
+    )
+      .then((images) => {
+        if (this._destroyed) return;
+        this._faceImages = Object.fromEntries(
+          faces.map(([face], index) => [face, images[index]]),
+        );
+        this._requestRender();
+      })
+      .catch((error) => console.warn('[sky] Milky Way unavailable', error));
+  }
+
+  _updateRotation(time) {
+    // An approximate rotation is final only while nothing better can come.
+    const settled =
+      this._rotationPrecise || this._icrfRequest || !this._canPreloadIcrf(time);
+    if (settled && isSkyRotationCurrent(this._rotationTime, time)) return;
+    const { precise } = computeSkyRotation(time, this._rotation);
+    this._rotationPrecise = precise;
+    this._rotationTime = Cesium.JulianDate.clone(time, this._rotationTime);
+    if (!precise) this._preloadIcrf(time);
+  }
+
+  /** Whether loading Cesium's IAU 2006 tables could still help at `time`. */
+  _canPreloadIcrf(time) {
+    return (
+      !this._icrfUnavailable &&
+      !(
+        this._icrfMissing &&
+        Cesium.TimeInterval.contains(this._icrfMissing, time)
+      )
+    );
+  }
+
+  /** Fetch Cesium's IAU 2006 tables around `time` once per span. */
+  _preloadIcrf(time) {
+    if (this._icrfRequest || !this._canPreloadIcrf(time)) return;
+    const interval = new Cesium.TimeInterval({
+      start: Cesium.JulianDate.addDays(time, -1, new Cesium.JulianDate()),
+      stop: Cesium.JulianDate.addDays(time, 1, new Cesium.JulianDate()),
+    });
+    this._icrfRequest = Promise.resolve(
+      Cesium.Transforms.preloadIcrfFixed(interval),
+    )
+      .then(
+        () => {
+          // The tables cover roughly 1975–2050; outside them the preload
+          // resolves with nothing, and TEME stays for this span.
+          if (!Cesium.Transforms.computeIcrfToFixedMatrix(time)) {
+            this._icrfMissing = interval;
+            return;
+          }
+          this._rotationTime = undefined;
+          if (!this._destroyed) this._requestRender();
+        },
+        (error) => {
+          // TEME is within a fraction of a degree; do not retry every frame.
+          this._icrfUnavailable = true;
+          console.warn('[sky] ICRF tables unavailable, using TEME', error);
+        },
+      )
+      .finally(() => {
+        this._icrfRequest = undefined;
+      });
+  }
+
+  _createMilkyWayCommand(context) {
+    const cubeMap = new Cesium.CubeMap({
+      context,
+      source: this._faceImages,
+      flipY: false,
+    });
+    cubeMap.generateMipmap();
+    cubeMap.sampler = new Cesium.Sampler({
+      minificationFilter: Cesium.TextureMinificationFilter.LINEAR_MIPMAP_LINEAR,
+    });
+    this._milkyWayCubeMap = cubeMap;
+    this._faceImages = undefined;
+    const geometry = Cesium.BoxGeometry.createGeometry(
+      Cesium.BoxGeometry.fromDimensions({
+        dimensions: new Cesium.Cartesian3(2, 2, 2),
+        vertexFormat: Cesium.VertexFormat.POSITION_ONLY,
+      }),
+    );
+    const attributeLocations =
+      Cesium.GeometryPipeline.createAttributeLocations(geometry);
+    this._milkyWayCommand = new Cesium.DrawCommand({
+      owner: this,
+      vertexArray: Cesium.VertexArray.fromGeometry({
+        context,
+        geometry,
+        attributeLocations,
+        bufferUsage: Cesium.BufferUsage.STATIC_DRAW,
+      }),
+      renderState: Cesium.RenderState.fromCache({}),
+      uniformMap: this._milkyWayUniforms,
+    });
+    this._milkyWayAttributes = attributeLocations;
+  }
+
+  _createStarCommand(context) {
+    const { count, vertices } = this._starData;
+    this._starData = undefined;
+    if (count === 0) return;
+    const vertexBuffer = Cesium.Buffer.createVertexBuffer({
+      context,
+      typedArray: vertices,
+      usage: Cesium.BufferUsage.STATIC_DRAW,
+    });
+    const stride = STAR_VERTEX_FLOATS * Float32Array.BYTES_PER_ELEMENT;
+    const attribute = (index, components, offsetFloats) => ({
+      index,
+      vertexBuffer,
+      componentsPerAttribute: components,
+      componentDatatype: Cesium.ComponentDatatype.FLOAT,
+      offsetInBytes: offsetFloats * Float32Array.BYTES_PER_ELEMENT,
+      strideInBytes: stride,
+    });
+    this._starCommand = new Cesium.DrawCommand({
+      owner: this,
+      primitiveType: Cesium.PrimitiveType.POINTS,
+      count,
+      vertexArray: new Cesium.VertexArray({
+        context,
+        attributes: [
+          attribute(0, 3, 0),
+          attribute(1, 1, 3),
+          attribute(2, 4, 4),
+        ],
+      }),
+      // Premultiplied additive: starlight adds to the Milky Way glow and
+      // leaves the framebuffer alpha alone.
+      renderState: Cesium.RenderState.fromCache({
+        blending: {
+          enabled: true,
+          equationRgb: Cesium.BlendEquation.ADD,
+          equationAlpha: Cesium.BlendEquation.ADD,
+          functionSourceRgb: Cesium.BlendFunction.ONE,
+          functionDestinationRgb: Cesium.BlendFunction.ONE,
+          functionSourceAlpha: Cesium.BlendFunction.ZERO,
+          functionDestinationAlpha: Cesium.BlendFunction.ONE,
+        },
+      }),
+      uniformMap: this._starUniforms,
+    });
+  }
+
+  _updateShaders(context, useHdr) {
+    if (this._useHdr === useHdr) return;
+    this._useHdr = useHdr;
+    const defines = useHdr ? ['HDR'] : [];
+    for (const [command, vs, fs, attributeLocations] of [
+      [
+        this._milkyWayCommand,
+        MILKY_WAY_VS,
+        MILKY_WAY_FS,
+        this._milkyWayAttributes,
+      ],
+      [
+        this._starCommand,
+        STAR_VS,
+        STAR_FS,
+        { position: 0, sigma: 1, color: 2 },
+      ],
+    ]) {
+      if (!command) continue;
+      command.shaderProgram?.destroy();
+      command.shaderProgram = Cesium.ShaderProgram.fromCache({
+        context,
+        vertexShaderSource: vs,
+        fragmentShaderSource: new Cesium.ShaderSource({
+          defines,
+          sources: [fs],
+        }),
+        attributeLocations,
+      });
+    }
+  }
+
+  /** `Scene#skyBox` contract: the command to draw this frame, if any. */
+  update(frameState, useHdr) {
+    if (!this.show) return undefined;
+    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) {
+      this._createMilkyWayCommand(context);
+      rebuilt = true;
+    }
+    if (this._starData && !this._starCommand) {
+      this._createStarCommand(context);
+      rebuilt = true;
+    }
+    if (rebuilt) this._useHdr = undefined;
+    this._updateShaders(context, Boolean(useHdr));
+    this._commands.length = 0;
+    if (this._milkyWayCommand) this._commands.push(this._milkyWayCommand);
+    if (this._starCommand) this._commands.push(this._starCommand);
+    if (this._commands.length === 0) return undefined;
+    this._updateRotation(frameState.time);
+    return this._compositeCommand;
+  }
+
+  isDestroyed() {
+    return this._destroyed;
+  }
+
+  destroy() {
+    for (const command of [this._milkyWayCommand, this._starCommand]) {
+      if (!command) continue;
+      command.vertexArray?.destroy();
+      command.shaderProgram?.destroy();
+    }
+    this._milkyWayCubeMap = this._milkyWayCubeMap?.destroy();
+    this._cubeMap = this._cubeMap?.destroy();
+    this._milkyWayCommand = undefined;
+    this._starCommand = undefined;
+    this._commands.length = 0;
+    this._destroyed = true;
+    return undefined;
+  }
+}

src/sky/starrySky.test.mjs

@@ -0,0 +1,200 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import {
+  MILKY_WAY_INTENSITY,
+  STARRY_SKY_CESIUM_VERSION,
+  SKY_ROTATION_EPSILON_SECONDS,
+  StarrySky,
+  computeSkyRotation,
+  isSkyRotationCurrent,
+} from './starrySky.js';
+
+const close = (actual, expected, epsilon = 1e-9) =>
+  assert.ok(Math.abs(actual - expected) <= epsilon, `${actual} vs ${expected}`);
+
+test('the sky-box adapter was validated against this engine version', () => {
+  assert.equal(
+    Cesium.VERSION,
+    STARRY_SKY_CESIUM_VERSION,
+    'engine upgrades require revalidating the Scene#skyBox contract',
+  );
+});
+
+test('the ICRF rotation is preferred and TEME fills in while tables load', () => {
+  const time = Cesium.JulianDate.fromIso8601('2026-10-19T00:00:00Z');
+  const icrf = Cesium.Matrix3.fromRotationZ(0.3);
+  const teme = Cesium.Matrix3.fromRotationZ(0.2);
+  const { Transforms } = Cesium;
+  const original = { ...Transforms };
+  try {
+    Transforms.computeIcrfToFixedMatrix = (_, result) =>
+      Cesium.Matrix3.clone(icrf, result);
+    Transforms.computeTemeToPseudoFixedMatrix = () =>
+      assert.fail('TEME not needed');
+    const precise = computeSkyRotation(time, new Cesium.Matrix3());
+    assert.equal(precise.precise, true);
+    assert.ok(Cesium.Matrix3.equals(precise.matrix, icrf));
+    Transforms.computeIcrfToFixedMatrix = () => undefined;
+    Transforms.computeTemeToPseudoFixedMatrix = (_, result) =>
+      Cesium.Matrix3.clone(teme, result);
+    const approximate = computeSkyRotation(time, new Cesium.Matrix3());
+    assert.equal(approximate.precise, false);
+    assert.ok(Cesium.Matrix3.equals(approximate.matrix, teme));
+  } finally {
+    Object.assign(Transforms, original);
+  }
+});
+
+test('the TEME fallback keeps the celestial pole on the Earth axis', () => {
+  // TEME only spins about Z; ICRF differs from it by precession (~0.36° by
+  // 2026), so the fallback sky is right up to a fraction of a degree.
+  const time = Cesium.JulianDate.fromIso8601('2026-10-19T00:00:00Z');
+  const teme = Cesium.Transforms.computeTemeToPseudoFixedMatrix(time);
+  const pole = Cesium.Matrix3.multiplyByVector(
+    teme,
+    Cesium.Cartesian3.UNIT_Z,
+    new Cesium.Cartesian3(),
+  );
+  assert.ok(Math.abs(pole.z - 1) < 1e-9);
+});
+
+test('the rotation is reused only within the clock epsilon', () => {
+  const time = Cesium.JulianDate.fromIso8601('2026-10-19T00:00:00Z');
+  const later = (seconds) =>
+    Cesium.JulianDate.addSeconds(time, seconds, new Cesium.JulianDate());
+  assert.equal(isSkyRotationCurrent(undefined, time), false);
+  assert.equal(isSkyRotationCurrent(time, later(0.5)), true);
+  assert.equal(isSkyRotationCurrent(time, later(-0.5)), true);
+  assert.equal(
+    isSkyRotationCurrent(time, later(SKY_ROTATION_EPSILON_SECONDS)),
+    false,
+  );
+});
+
+test('the sky draws nothing when hidden, outside 3D, or in a pick pass', () => {
+  const sky = new StarrySky({ requestRender: () => {} });
+  const frameState = (overrides) => ({
+    mode: Cesium.SceneMode.SCENE3D,
+    passes: { render: true },
+    ...overrides,
+  });
+  sky._loading = true; // keep the test off the network
+  sky.show = false;
+  assert.equal(sky.update(frameState()), undefined);
+  sky.show = true;
+  assert.equal(
+    sky.update(frameState({ mode: Cesium.SceneMode.SCENE2D })),
+    undefined,
+  );
+  assert.equal(
+    sky.update(frameState({ passes: { render: false, pick: true } })),
+    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);
+  assert.equal(sky.isDestroyed(), true);
+});
+
+const frame = () => new Promise((resolve) => setImmediate(resolve));
+
+for (const iso of ['1970-01-01T00:00:00Z', '2060-01-01T00:00:00Z']) {
+  test(`a clock outside the IAU 2006 tables (${iso}) settles on TEME instead of re-rendering every frame`, async () => {
+    const time = Cesium.JulianDate.fromIso8601(iso);
+    let renders = 0;
+    let preloads = 0;
+    const original = Cesium.Transforms.preloadIcrfFixed;
+    Cesium.Transforms.preloadIcrfFixed = (interval) => {
+      preloads += 1;
+      return original(interval);
+    };
+    try {
+      const sky = new StarrySky({ requestRender: () => (renders += 1) });
+      for (let i = 0; i < 20; i += 1) {
+        sky._updateRotation(time); // what update() does once per frame
+        await frame();
+      }
+      assert.ok(
+        renders <= 1 && preloads <= 1,
+        `20 frames at a frozen clock -> ${preloads} preloads, ${renders} render requests (expected <= 1 each)`,
+      );
+    } finally {
+      Cesium.Transforms.preloadIcrfFixed = original;
+    }
+  });
+}
+
+test('the Milky Way glow scales with its visibility, for styles that hide it', () => {
+  const sky = new StarrySky({ requestRender: () => {} });
+  close(sky._milkyWayUniforms.u_intensity(), MILKY_WAY_INTENSITY);
+  sky.milkyWayVisibility = 0;
+  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;
+  }
+});

src/sky/stars.js

@@ -0,0 +1,121 @@
+/**
+ * Bright-star appearance: catalogue pack → GPU vertex data.
+ *
+ * Pure functions, no Cesium. The pack is `local_data/sky/bright_stars.json`
+ * (Yale Bright Star Catalogue, built by scripts/build-bright-stars.mjs): a
+ * flat `[raDeg, decDeg, vmag, bv, …]` array in ICRF/J2000. Each star is a
+ * small Gaussian sprite, sized in CSS pixels so it stays a crisp dot at any DPR.
+ *
+ * @module sky/stars
+ */
+
+/** Brightness reference; fainter catalogue stars are drawn like it. */
+export const STAR_LIMIT_MAGNITUDE = 6.5;
+/** Gaussian σ of the faintest star, CSS pixels. */
+export const STAR_MIN_SIGMA_PX = 0.55;
+/** Gaussian σ cap for the brightest star, CSS pixels. */
+export const STAR_MAX_SIGMA_PX = 1.35;
+/** Peak opacity of the faintest star. */
+export const STAR_MIN_ALPHA = 0.22;
+/** B−V for stars the catalogue gives no colour (a solar-type white). */
+export const STAR_DEFAULT_BV = 0.6;
+/** Floats per star in the vertex buffer: xyz, σ, rgb, alpha. */
+export const STAR_VERTEX_FLOATS = 8;
+
+const DEG = Math.PI / 180;
+// Fraction of the colour kept: the eye sees all but the most extreme stars
+// as nearly white, and saturated dots read as UI markers on the globe.
+const COLOR_SATURATION = 0.55;
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+/** ICRF unit vector for J2000 right ascension and declination in degrees. */
+export function raDecToUnitVector(raDeg, decDeg) {
+  const ra = raDeg * DEG;
+  const dec = decDeg * DEG;
+  const cosDec = Math.cos(dec);
+  return [cosDec * Math.cos(ra), cosDec * Math.sin(ra), Math.sin(dec)];
+}
+
+/**
+ * Perceived brightness relative to the limit magnitude. Flux grows 2.512×
+ * per magnitude; the square root compresses Sirius-to-6.5m (≈ 1600×) into a
+ * range a display can show without the bright stars turning into discs.
+ */
+export function starBrightness(vmag) {
+  const magnitude = Number.isFinite(vmag) ? vmag : STAR_LIMIT_MAGNITUDE;
+  return (
+    10 **
+    (-0.2 * (Math.min(magnitude, STAR_LIMIT_MAGNITUDE) - STAR_LIMIT_MAGNITUDE))
+  );
+}
+
+/**
+ * Sprite parameters for a visual magnitude: `sigmaPx` is the Gaussian σ in
+ * CSS pixels and `alpha` its peak opacity. Faint stars keep the minimum width
+ * and fade; bright stars saturate and grow slowly.
+ */
+export function starAppearance(vmag) {
+  const brightness = starBrightness(vmag);
+  return {
+    sigmaPx: clamp(
+      STAR_MIN_SIGMA_PX * brightness ** 0.3,
+      STAR_MIN_SIGMA_PX,
+      STAR_MAX_SIGMA_PX,
+    ),
+    alpha: clamp(STAR_MIN_ALPHA * brightness, STAR_MIN_ALPHA, 1),
+  };
+}
+
+/** Effective temperature from B−V (Ballesteros 2012). */
+export function bvToTemperature(bv) {
+  const index = clamp(Number.isFinite(bv) ? bv : STAR_DEFAULT_BV, -0.4, 2.0);
+  return 4600 * (1 / (0.92 * index + 1.7) + 1 / (0.92 * index + 0.62));
+}
+
+/** Black-body colour of a temperature, sRGB 0..1 (Helland's fit). */
+export function temperatureToRgb(kelvin) {
+  const t = clamp(kelvin, 1000, 40000) / 100;
+  const red = t <= 66 ? 255 : 329.698727446 * (t - 60) ** -0.1332047592;
+  const green =
+    t <= 66
+      ? 99.4708025861 * Math.log(t) - 161.1195681661
+      : 288.1221695283 * (t - 60) ** -0.0755148492;
+  const blue =
+    t >= 66
+      ? 255
+      : t <= 19
+        ? 0
+        : 138.5177312231 * Math.log(t - 10) - 305.0447927307;
+  return [red, green, blue].map((channel) => clamp(channel, 0, 255) / 255);
+}
+
+/**
+ * Display colour for a B−V index: the black-body hue, desaturated towards
+ * white and normalized so the brightest channel is 1 (brightness belongs to
+ * the magnitude alone).
+ */
+export function bvToRgb(bv) {
+  const rgb = temperatureToRgb(bvToTemperature(bv)).map(
+    (channel) => 1 - COLOR_SATURATION + COLOR_SATURATION * channel,
+  );
+  const peak = Math.max(...rgb);
+  return rgb.map((channel) => channel / peak);
+}
+
+/** Decode a catalogue pack into interleaved vertex data, `STAR_VERTEX_FLOATS` per star. */
+export function buildStarVertices({ stars }) {
+  const count = stars.length / 4;
+  const vertices = new Float32Array(count * STAR_VERTEX_FLOATS);
+  for (let i = 0; i < count; i++) {
+    const [raDeg, decDeg, vmag, bv] = stars.slice(i * 4, i * 4 + 4);
+    const { sigmaPx, alpha } = starAppearance(vmag);
+    vertices.set(
+      [...raDecToUnitVector(raDeg, decDeg), sigmaPx, ...bvToRgb(bv), alpha],
+      i * STAR_VERTEX_FLOATS,
+    );
+  }
+  return { count, vertices };
+}

src/sky/stars.test.mjs

@@ -0,0 +1,130 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, statSync } from 'node:fs';
+import {
+  STAR_LIMIT_MAGNITUDE,
+  STAR_MAX_SIGMA_PX,
+  STAR_MIN_ALPHA,
+  STAR_MIN_SIGMA_PX,
+  STAR_VERTEX_FLOATS,
+  buildStarVertices,
+  bvToRgb,
+  bvToTemperature,
+  raDecToUnitVector,
+  starAppearance,
+  starBrightness,
+} from './stars.js';
+
+const close = (actual, expected, epsilon = 1e-9) =>
+  assert.ok(
+    Math.abs(actual - expected) <= epsilon,
+    `${actual} is not within ${epsilon} of ${expected}`,
+  );
+
+const skyFile = (name) =>
+  new URL(`../data/local_data/sky/${name}`, import.meta.url);
+
+test('right ascension and declination map onto the ICRF axes', () => {
+  const equinox = raDecToUnitVector(0, 0);
+  close(equinox[0], 1);
+  close(equinox[1], 0);
+  close(equinox[2], 0);
+  const sixHours = raDecToUnitVector(90, 0);
+  close(sixHours[0], 0);
+  close(sixHours[1], 1);
+  const pole = raDecToUnitVector(123, 90);
+  close(pole[2], 1);
+  const south = raDecToUnitVector(200, -30);
+  close(Math.hypot(...south), 1);
+  close(south[2], -0.5);
+});
+
+test('brightness grows with each magnitude and stops at the catalogue limit', () => {
+  close(starBrightness(STAR_LIMIT_MAGNITUDE), 1);
+  close(starBrightness(STAR_LIMIT_MAGNITUDE + 1.5), 1);
+  close(starBrightness(STAR_LIMIT_MAGNITUDE - 5), 10);
+  close(starBrightness(Number.NaN), 1);
+});
+
+test('brighter stars are never smaller or fainter, and both ends clamp', () => {
+  let previous = starAppearance(8);
+  assert.deepEqual(previous, {
+    sigmaPx: STAR_MIN_SIGMA_PX,
+    alpha: STAR_MIN_ALPHA,
+  });
+  for (let vmag = 7.5; vmag >= -1.5; vmag -= 0.25) {
+    const next = starAppearance(vmag);
+    assert.ok(next.sigmaPx >= previous.sigmaPx, `σ shrank at ${vmag}`);
+    assert.ok(next.alpha >= previous.alpha, `alpha dropped at ${vmag}`);
+    previous = next;
+  }
+  const sirius = starAppearance(-1.46);
+  assert.equal(sirius.alpha, 1);
+  assert.ok(sirius.sigmaPx <= STAR_MAX_SIGMA_PX);
+  assert.ok(sirius.sigmaPx > starAppearance(2).sigmaPx);
+  // Sprites stay point-like: ±3σ of the brightest star is a few pixels.
+  assert.ok(6 * STAR_MAX_SIGMA_PX < 10);
+});
+
+test('B−V colours run from blue-white to orange with the peak channel at 1', () => {
+  close(bvToTemperature(0.65), 5_800, 120);
+  close(bvToTemperature(0), 10_100, 200);
+  const hot = bvToRgb(-0.3);
+  const sunLike = bvToRgb(0.65);
+  const cool = bvToRgb(1.6);
+  for (const rgb of [hot, sunLike, cool]) {
+    close(Math.max(...rgb), 1);
+    assert.ok(Math.min(...rgb) > 0.5, 'colours stay desaturated');
+  }
+  assert.ok(hot[2] > hot[0], 'hot stars are blue');
+  assert.ok(cool[0] > cool[2], 'cool stars are orange');
+  assert.deepEqual(bvToRgb(null), bvToRgb(0.6));
+  assert.deepEqual(bvToRgb(9), bvToRgb(2));
+});
+
+test('vertex data is interleaved per star', () => {
+  const { count, vertices } = buildStarVertices({
+    stars: [0, 0, 1, 0.5, 90, 45, 3, null],
+  });
+  assert.equal(count, 2);
+  assert.equal(vertices.length, 2 * STAR_VERTEX_FLOATS);
+  assert.deepEqual(Array.from(vertices.subarray(0, 3)), [1, 0, 0]);
+  close(vertices[STAR_VERTEX_FLOATS + 1], Math.SQRT1_2, 1e-6);
+  close(vertices[STAR_VERTEX_FLOATS + 2], Math.SQRT1_2, 1e-6);
+  close(vertices[3], starAppearance(1).sigmaPx, 1e-6);
+  close(vertices[7], starAppearance(1).alpha, 1e-6);
+});
+
+test('the committed catalogue holds the Yale Bright Star Catalogue', () => {
+  const pack = JSON.parse(readFileSync(skyFile('bright_stars.json'), 'utf8'));
+  assert.deepEqual(pack.meta.columns, ['raDeg', 'decDeg', 'vmag', 'bv']);
+  assert.equal(pack.stars.length, pack.meta.count * 4);
+  assert.equal(pack.meta.count, 9096);
+  let brightest = 0;
+  for (let i = 0; i < pack.stars.length; i += 4) {
+    const [ra, dec, vmag] = pack.stars.slice(i, i + 4);
+    assert.ok(ra >= 0 && ra < 360 && dec >= -90 && dec <= 90);
+    assert.ok(Number.isFinite(vmag));
+    if (vmag < pack.stars[brightest + 2]) brightest = i;
+  }
+  // Sirius, α CMa: 06h45m08.9s −16°42′58″, V = −1.46.
+  assert.deepEqual(
+    pack.stars.slice(brightest, brightest + 4),
+    [101.287, -16.716, -1.46, 0],
+  );
+  assert.equal(buildStarVertices(pack).count, pack.meta.count);
+});
+
+test('sky assets stay inside the 5 MB budget', () => {
+  const files = [
+    'bright_stars.json',
+    ...['px', 'nx', 'py', 'ny', 'pz', 'nz'].map(
+      (face) => `milkyway_${face}.webp`,
+    ),
+  ];
+  const total = files.reduce(
+    (sum, name) => sum + statSync(skyFile(name)).size,
+    0,
+  );
+  assert.ok(total < 5 * 1024 * 1024, `${total} bytes`);
+});

src/tooling/skyAssets.paintOut.test.mjs

@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import sharp from 'sharp';
+import {
+  CUBE_FACES,
+  FACE_FILE_SUFFIX,
+  PLANETS,
+  cubeFaceDirection,
+  icrfToGalactic,
+} from '../../scripts/build-milky-way.mjs';
+import { raDecToUnitVector } from '../sky/stars.js';
+
+const SKY = new URL('../data/local_data/sky/', import.meta.url);
+// Allowed excess of the painted disc over the surrounding sky, in 8-bit
+// levels of the encoded face: the blur and dither move values by a few.
+const TOLERANCE = 4;
+
+test('painted-out planets leave no disc brighter than the sky around them', async () => {
+  const centres = PLANETS.map((planet) => ({
+    planet,
+    vector: raDecToUnitVector(planet.l, planet.b),
+    disc: [],
+    ring: [],
+  }));
+  for (const face of CUBE_FACES) {
+    const { data, info } = await sharp(
+      new URL(`milkyway_${FACE_FILE_SUFFIX[face]}.webp`, SKY).pathname,
+    )
+      .raw()
+      .toBuffer({ resolveWithObject: true });
+    const size = info.width;
+    for (let j = 0; j < size; j++) {
+      for (let i = 0; i < size; i++) {
+        const d = cubeFaceDirection(face, (i + 0.5) / size, (j + 0.5) / size);
+        const n = Math.hypot(...d);
+        const g = icrfToGalactic(d.map((x) => x / n));
+        for (const centre of centres) {
+          const cos =
+            g[0] * centre.vector[0] +
+            g[1] * centre.vector[1] +
+            g[2] * centre.vector[2];
+          const degrees = (Math.acos(Math.min(1, cos)) * 180) / Math.PI;
+          const k = (j * size + i) * info.channels;
+          const luma = (data[k] + data[k + 1] + data[k + 2]) / 3;
+          if (degrees <= centre.planet.radiusDeg - 0.5) centre.disc.push(luma);
+          else if (
+            degrees >= centre.planet.radiusDeg + 1 &&
+            degrees <= centre.planet.radiusDeg + 3.5
+          )
+            centre.ring.push(luma);
+        }
+      }
+    }
+  }
+  const median = (values) => values.sort((a, b) => a - b)[values.length >> 1];
+  for (const { planet, disc, ring } of centres) {
+    const discMean = disc.reduce((s, v) => s + v, 0) / disc.length;
+    const ringMedian = median(ring);
+    assert.ok(
+      discMean <= ringMedian + TOLERANCE,
+      `l=${planet.l} b=${planet.b}: disc mean ${discMean.toFixed(1)} vs surrounding sky ${ringMedian.toFixed(1)}`,
+    );
+  }
+});

src/tooling/skyAssets.test.mjs

@@ -0,0 +1,132 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  buildStarPack,
+  parseBscRecord,
+} from '../../scripts/build-bright-stars.mjs';
+import {
+  CUBE_FACES,
+  cubeFaceDirection,
+  directionToPlateCarree,
+  icrfToGalactic,
+  smoothstep,
+  softBlack,
+} from '../../scripts/build-milky-way.mjs';
+import { raDecToUnitVector } from '../sky/stars.js';
+
+// Verbatim CDS V/50 records: HR 1, Sirius (HR 2491) and a nova with no J2000
+// position. Columns matter, so the padding is part of the fixture.
+const HR_1 =
+  '   1          BD+44 4550      3 36042          46           000001.1+444022000509.9+451345114.44-16.88 6.70  +0.07 +0.08         A1Vn               -0.012-0.018      -018      195  4.2  21.6AC   3';
+const SIRIUS =
+  '2491  9Alp CMaBD-16 1591  48915151881 257I   5423           064044.6-163444064508.9-164258227.22-08.88-1.46   0.00 -0.05 -0.03   A1Vm               -0.553-1.205 +.375-008SBO    13 10.3  11.2AB   4*';
+const NOVA =
+  '  92 NOVA 1572                                     B Cas                                                                                                                                            *';
+
+const close = (actual, expected, epsilon = 1e-9) =>
+  assert.ok(
+    Math.abs(actual - expected) <= epsilon,
+    `${actual} is not within ${epsilon} of ${expected}`,
+  );
+
+test('BSC5 records parse J2000 position, V magnitude and B−V', () => {
+  const sirius = parseBscRecord(SIRIUS);
+  assert.equal(sirius.hr, 2491);
+  close(sirius.raDeg, (6 + 45 / 60 + 8.9 / 3600) * 15);
+  close(sirius.decDeg, -(16 + 42 / 60 + 58 / 3600));
+  assert.equal(sirius.vmag, -1.46);
+  assert.equal(sirius.bv, 0);
+  const first = parseBscRecord(HR_1);
+  close(first.raDeg, (5 / 60 + 9.9 / 3600) * 15);
+  close(first.decDeg, 45 + 13 / 60 + 45 / 3600);
+  assert.equal(first.vmag, 6.7);
+  assert.equal(first.bv, 0.07);
+  assert.equal(parseBscRecord(NOVA), null);
+});
+
+test('the star pack is a flat, rounded column array that counts its drops', () => {
+  const pack = buildStarPack([HR_1, NOVA, SIRIUS, ''].join('\n'), {
+    fetched: '2026-10-19',
+  });
+  assert.deepEqual(
+    pack.stars,
+    [1.291, 45.229, 6.7, 0.07, 101.287, -16.716, -1.46, 0],
+  );
+  assert.equal(pack.meta.count, 2);
+  assert.equal(pack.meta.dropped, 1);
+  assert.equal(pack.meta.fetched, '2026-10-19');
+});
+
+test('cube faces use the WebGL major-axis layout', () => {
+  // Each face centre looks down its own axis …
+  const axes = {
+    positiveX: [1, 0, 0],
+    negativeX: [-1, 0, 0],
+    positiveY: [0, 1, 0],
+    negativeY: [0, -1, 0],
+    positiveZ: [0, 0, 1],
+    negativeZ: [0, 0, -1],
+  };
+  for (const face of CUBE_FACES)
+    assert.deepEqual(
+      cubeFaceDirection(face, 0.5, 0.5).map((v) => v + 0),
+      axes[face],
+    );
+  // … and the first texel row and column follow OpenGL ES 3.0 §3.8.10:
+  // on +X, s grows towards −Z and t towards −Y.
+  assert.deepEqual(cubeFaceDirection('positiveX', 0, 0), [1, 1, 1]);
+  assert.deepEqual(cubeFaceDirection('positiveZ', 1, 1), [1, -1, 1]);
+  assert.deepEqual(cubeFaceDirection('negativeY', 0, 1), [-1, -1, -1]);
+  assert.throws(() => cubeFaceDirection('up', 0, 0), RangeError);
+});
+
+test('plate carrée is centred on longitude 0, growing to the left, north up', () => {
+  assert.deepEqual(directionToPlateCarree(1, 0, 0), [0.5, 0.5]);
+  const sixHours = directionToPlateCarree(0, 1, 0);
+  close(sixHours[0], 0.25);
+  const eighteenHours = directionToPlateCarree(0, -1, 0);
+  close(eighteenHours[0], 0.75);
+  close(directionToPlateCarree(0, 0, 1)[1], 0);
+  close(directionToPlateCarree(0, 0, -1)[1], 1);
+  const twelveHours = directionToPlateCarree(-1, 0, 0);
+  assert.ok(twelveHours[0] === 0 || twelveHours[0] === 1);
+});
+
+test('the galactic rotation puts the Galactic Centre and pole where the IAU does', () => {
+  // Galactic origin l = b = 0 at RA 266.405°, Dec −28.936° (J2000).
+  const centre = icrfToGalactic(raDecToUnitVector(266.40499, -28.93617));
+  close(centre[0], 1, 1e-6);
+  // North galactic pole at RA 192.85948°, Dec +27.12825°.
+  const pole = icrfToGalactic(raDecToUnitVector(192.85948, 27.12825));
+  close(pole[2], 1, 1e-6);
+  // ESO's panorama: the Large Magellanic Cloud (l ≈ 280.5°, b ≈ −32.9°) sits
+  // right of and below the centre.
+  const [u, v] = directionToPlateCarree(
+    ...icrfToGalactic(raDecToUnitVector(80.894, -69.756)),
+  );
+  close(u, 0.5 + (360 - 280.47) / 360, 2e-3);
+  close(v, 0.5 + 32.89 / 180, 2e-3);
+});
+
+test('the black level eases in instead of cutting the faint sky into contours', () => {
+  assert.equal(softBlack(-0.2), 0);
+  assert.equal(softBlack(0), 0);
+  // Continuous, rising, with no step at the black level.
+  let previous = 0;
+  for (let x = 0.001; x <= 1; x += 0.001) {
+    const y = softBlack(x);
+    assert.ok(y > previous && y - previous < 0.0011, `step at ${x.toFixed(3)}`);
+    previous = y;
+  }
+  // Starts flat, then joins the straight line just below it.
+  assert.ok(softBlack(0.003) < 0.0003);
+  close(softBlack(1), 1 - 0.03, 1e-3);
+});
+
+test('the faint-glow blend weight eases between its edges', () => {
+  assert.equal(smoothstep(0.1, 0.2, 0), 0);
+  assert.equal(smoothstep(0.1, 0.2, 0.1), 0);
+  close(smoothstep(0.1, 0.2, 0.15), 0.5, 1e-9);
+  assert.equal(smoothstep(0.1, 0.2, 0.2), 1);
+  assert.equal(smoothstep(0.1, 0.2, 9), 1);
+});

src/ui/visualEffects.js

@@ -112,6 +112,13 @@ export class VisualEffects {
     if (this.stopped || !stage) return;
     stage.uniforms.intensity = value;
     stage.enabled = value > 0.001;
+    // Anime's bands turn the faint Milky Way into blotches, and depth cannot
+    // tell the sky from far geometry, so the glow fades with the style.
+    if (
+      stage === this.stages.anime &&
+      this.viewer.scene.skyBox?.milkyWayVisibility !== undefined
+    )
+      this.viewer.scene.skyBox.milkyWayVisibility = 1 - value;
     if (stage.enabled && stage.uniforms.time !== undefined)
       this.startAnimationLoop();
     this.requestRender('style-stage');

src/ui/visualEffects.test.mjs

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import { VisualEffects } from './visualEffects.js';
+import { MILKY_WAY_INTENSITY, StarrySky } from '../sky/starrySky.js';
 import {
   GLOBAL_POST_DEFAULTS,
   STYLE_PRESET_DEFAULTS,
@@ -36,7 +37,9 @@ function fixture() {
     },
   };
   const effects = new VisualEffects({
-    viewer: { scene: { postProcessStages: pipeline } },
+    viewer: {
+      scene: { postProcessStages: pipeline, skyBox: { milkyWayVisibility: 1 } },
+    },
     requestRender: (reason) => requests.push(reason),
     holdRender: (reason) => holds.add(reason),
     releaseRender: (reason) => holds.delete(reason),
@@ -158,6 +161,38 @@ test('direct Cockpit intensity writes are reconciled before rendering', () => {
   f.effects.destroy();
 });
 
+test('the anime stage fades the Milky Way out with its own intensity', () => {
+  const f = fixture();
+  const sky = new StarrySky({ requestRender: () => {} });
+  const glow = () => sky._milkyWayUniforms.u_intensity();
+  f.effects.viewer.scene.skyBox = sky;
+  f.effects.initStyles();
+  f.effects.setStageIntensity(f.effects.stages.thermal, 1);
+  assert.equal(glow(), MILKY_WAY_INTENSITY, 'other styles keep the glow');
+  f.effects.setStageIntensity(f.effects.stages.anime, 0.25);
+  assert.equal(glow(), MILKY_WAY_INTENSITY * 0.75);
+  f.effects.setStageIntensity(f.effects.stages.anime, 1);
+  assert.equal(glow(), 0);
+  f.effects.setStageIntensity(f.effects.stages.anime, 0);
+  assert.equal(glow(), MILKY_WAY_INTENSITY);
+  sky.destroy();
+  f.effects.destroy();
+});
+
+for (const skyBox of [undefined, null, {}]) {
+  test(`anime works without StarrySky (${JSON.stringify(skyBox)})`, () => {
+    const f = fixture();
+    f.effects.viewer.scene.skyBox = skyBox;
+    f.effects.initStyles();
+    f.effects.setStageIntensity(f.effects.stages.anime, 1);
+    assert.equal(f.effects.stages.anime.enabled, true);
+    f.effects.setStageIntensity(f.effects.stages.anime, 0);
+    assert.equal(f.effects.stages.anime.enabled, false);
+    if (skyBox) assert.equal('milkyWayVisibility' in skyBox, false);
+    f.effects.destroy();
+  });
+}
+
 test('bloom retains its dead zone, normalized intensity and independent toggle', () => {
   const f = fixture();
   f.effects.initPostProcess();