Merge pull request 'Phase 2c: eclipse/overpass calculators + live-map camera polish' (#3) from phase-2c into main

Reviewed-on: #3

apps/live-map/package.json

@@ -10,7 +10,7 @@
     "preview": "vite preview --port 3001",
     "typecheck": "tsc --noEmit",
     "lint": "echo 'no linter yet'",
-    "test": "echo 'no tests yet'"
+    "test": "vitest run"
   },
   "dependencies": {
     "@kerbal-rt/shared-types": "workspace:*",
@@ -26,6 +26,7 @@
     "@types/three": "^0.169.0",
     "@vitejs/plugin-react": "^4.3.1",
     "typescript": "^5.6.2",
-    "vite": "^5.4.6"
+    "vite": "^5.4.6",
+    "vitest": "^2.1.1"
   }
 }

apps/live-map/src/App.tsx

@@ -1,313 +1,230 @@
-import { useEffect, useRef, useState } from 'react';
+/**
-import * as THREE from 'three';
+ * App — top-level live map.
-import { Pill, formatUtAsKspDate } from '@kerbal-rt/ui';
+ *
-import { sampleOrbit, positionAt } from '@kerbal-rt/orbital-math';
+ * Subscribes to the API WebSocket, manages the simulation time
-import type { CelestialBody } from '@kerbal-rt/shared-types';
+ * (UT), and renders the 3D scene plus all the UI panels.
+ *
+ * Time model:
+ *  - `liveUt`: the UT of the most recent snapshot received
+ *  - `displayUt`: what the scene is currently showing. Starts at
+ *    liveUt, advances on play, and can be scrubbed via the slider.
+ *  - When `displayUt === liveUt`, the pill shows "LIVE".
+ *    When the user scrubs backwards or speed-0 pauses, the pill
+ *    shows how far behind/ahead we are.
+ */
+import { useEffect, useState } from 'react';
+import { Scene } from './scene/Scene.js';
+import { TimeControls } from './panels/TimeControls.js';
+import { VesselList } from './panels/VesselList.js';
+import { FocusPanel } from './panels/FocusPanel.js';
+import { StatusPill } from './panels/StatusPill.js';
+import { CalculatorsPanel } from './panels/CalculatorsPanel.js';
+import { useLiveState } from './hooks/useLiveState.js';
+import type { UniverseSnapshot } from '@kerbal-rt/shared-types';
 
 const API_URL = (import.meta.env.VITE_API_URL as string | undefined) ?? '';
 
-/**
+/** Fallback in-memory snapshot so the scene has something to render
- * Mock solar system so the scene has something to render before the
+ *  even before the API is up. Matches the catalog used by the
- * real KSP bridge is wired in (Phase 1). Drop a real snapshot in
+ *  mock-telemetry publisher. */
- * via the same /api/v1/state endpoint and the same renderer will
+const FALLBACK_SNAPSHOT: UniverseSnapshot = {
- * work — only `useUniverse()` changes.
+  ut: 0,
- */
+  capturedAt: new Date(0).toISOString(),
-function useUniverse() {
+  activeVesselId: null,
-  const [bodies, setBodies] = useState<CelestialBody[]>([]);
+  bodies: [
-  const [ut, setUt] = useState(0);
+    {
-  const [error, setError] = useState<string | null>(null);
+      id: 'kerbol',
-
+      name: 'Kerbol',
-  useEffect(() => {
+      kind: 'star',
-    const mockBodies: CelestialBody[] = [
+      parentId: null,
-      makeBody({
+      radius: 261_600_000,
-        id: 'kerbol',
+      sphereOfInfluence: 1e30,
-        name: 'Kerbol',
+      gravitationalParameter: 1.172332794e18,
-        kind: 'star',
+      rotationPeriod: 432_000,
-        radius: 261_600_000,
+      axialTilt: 0,
-        sphereOfInfluence: Infinity,
+      orbit: {
-        mu: 1.172332794e18,
+        semiMajorAxis: 0,
-        rotationPeriod: 432_000,
+        eccentricity: 0,
-        axialTilt: 0,
+        inclination: 0,
-        color: '#ffcc33',
+        longitudeOfAscendingNode: 0,
-        parent: null,
+        argumentOfPeriapsis: 0,
-        sma: 0,
+        meanAnomalyAtEpoch: 0,
-      }),
+        epoch: 0,
-      makeBody({
+      },
-        id: 'kerbin',
-        name: 'Kerbin',
-        kind: 'planet',
-        radius: 600_000,
-        sphereOfInfluence: 84_159_286,
-        mu: 3.5316e12,
-        rotationPeriod: 21_600,
-        axialTilt: 0,
-        color: '#3a7d8c',
-        parent: 'kerbol',
-        sma: 13_599_840_256,
-      }),
-      makeBody({
-        id: 'mun',
-        name: 'Mun',
-        kind: 'moon',
-        radius: 200_000,
-        sphereOfInfluence: 2_429_559,
-        mu: 6.514e10,
-        rotationPeriod: 138_984,
-        axialTilt: 0,
-        color: '#aaa',
-        parent: 'kerbin',
-        sma: 12_000_000,
-      }),
-    ];
-    setBodies(mockBodies);
-    setUt(4_700_000);
-
-    // Try to fetch real state if API is reachable
-    fetch(`${API_URL}/api/v1/state`)
-      .then((r) => (r.ok ? r.json() : null))
-      .then((j) => {
-        if (j?.data?.bodies?.length) {
-          setBodies(j.data.bodies);
-          setUt(j.data.ut);
-        }
-      })
-      .catch((e) => setError(String(e)));
-  }, []);
-
-  return { bodies, ut, setUt, error };
-}
-
-function makeBody(opts: {
-  id: string;
-  name: string;
-  kind: CelestialBody['kind'];
-  radius: number;
-  sphereOfInfluence: number;
-  mu: number;
-  rotationPeriod: number;
-  axialTilt: number;
-  color: string;
-  parent: string | null;
-  sma: number;
-}): CelestialBody {
-  return {
-    id: opts.id,
-    name: opts.name,
-    kind: opts.kind,
-    parentId: opts.parent,
-    radius: opts.radius,
-    sphereOfInfluence: opts.sphereOfInfluence,
-    gravitationalParameter: opts.mu,
-    rotationPeriod: opts.rotationPeriod,
-    axialTilt: opts.axialTilt,
-    orbit: {
-      semiMajorAxis: opts.sma,
-      eccentricity: 0,
-      inclination: 0,
-      longitudeOfAscendingNode: 0,
-      argumentOfPeriapsis: 0,
-      meanAnomalyAtEpoch: Math.random() * Math.PI * 2,
-      epoch: 0,
     },
-  };
+    {
-}
+      id: 'kerbin',
-
+      name: 'Kerbin',
-function Scene({ bodies, ut }: { bodies: CelestialBody[]; ut: number }) {
+      kind: 'planet',
-  const mountRef = useRef<HTMLDivElement>(null);
+      parentId: 'kerbol',
-
+      radius: 600_000,
-  useEffect(() => {
+      sphereOfInfluence: 84_159_286,
-    const mount = mountRef.current;
+      gravitationalParameter: 3.5316e12,
-    if (!mount) return;
+      rotationPeriod: 21_600,
-
+      axialTilt: 0,
-    const width = mount.clientWidth;
+      orbit: {
-    const height = mount.clientHeight;
+        semiMajorAxis: 13_599_840_256,
-
+        eccentricity: 0.05,
-    const scene = new THREE.Scene();
+        inclination: 0,
-    scene.background = new THREE.Color(0x000005);
+        longitudeOfAscendingNode: 0,
-
+        argumentOfPeriapsis: 0,
-    const camera = new THREE.PerspectiveCamera(60, width / height, 0.1, 1e12);
+        meanAnomalyAtEpoch: 0.7,
-    camera.position.set(0, 5e9, 1.5e10);
+        epoch: 0,
-    camera.lookAt(0, 0, 0);
+      },
-
+    },
-    const renderer = new THREE.WebGLRenderer({ antialias: true });
+    {
-    renderer.setSize(width, height);
+      id: 'mun',
-    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+      name: 'Mun',
-    mount.appendChild(renderer.domElement);
+      kind: 'moon',
-
+      parentId: 'kerbin',
-    // Lights
+      radius: 200_000,
-    scene.add(new THREE.AmbientLight(0x404040, 0.4));
+      sphereOfInfluence: 2_429_559,
-    const sunLight = new THREE.PointLight(0xffffff, 2, 0, 0);
+      gravitationalParameter: 6.514e10,
-    scene.add(sunLight);
+      rotationPeriod: 138_984,
-
+      axialTilt: 0,
-    // Build spheres + orbit lines per body
+      orbit: {
-    const meshById = new Map<string, THREE.Mesh>();
+        semiMajorAxis: 12_000_000,
-    const orbitGroup = new THREE.Group();
+        eccentricity: 0,
-    scene.add(orbitGroup);
+        inclination: 0,
-
+        longitudeOfAscendingNode: 0,
-    for (const body of bodies) {
+        argumentOfPeriapsis: 0,
-      if (body.sphereOfInfluence === 0 || body.sphereOfInfluence === Infinity) {
+        meanAnomalyAtEpoch: 1.0,
-        // Star: render but skip orbit
+        epoch: 0,
-        if (body.kind === 'star') {
+      },
-          const geo = new THREE.SphereGeometry(Math.max(body.radius, 1e8), 32, 16);
+    },
-          const mat = new THREE.MeshBasicMaterial({ color: 0xffcc33 });
+  ],
-          const mesh = new THREE.Mesh(geo, mat);
+  vessels: [],
-          scene.add(mesh);
+  groundStations: [],
-          meshById.set(body.id, mesh);
+};
-        }
-        continue;
-      }
-
-      // Sphere — small planets/moons get a minimum size so they're visible
-      const displayRadius = Math.max(body.radius, 1e6);
-      const geo = new THREE.SphereGeometry(displayRadius, 32, 16);
-      const mat = new THREE.MeshPhongMaterial({
-        color: bodyColor(body.id),
-        emissive: 0x111111,
-      });
-      const mesh = new THREE.Mesh(geo, mat);
-      scene.add(mesh);
-      meshById.set(body.id, mesh);
-
-      // Orbit line
-      const points = sampleOrbit(body.orbit, body.gravitationalParameter, 256);
-      const positions = new Float32Array(points.length * 3);
-      points.forEach((p, i) => {
-        positions[i * 3] = p.x;
-        positions[i * 3 + 1] = p.y;
-        positions[i * 3 + 2] = p.z;
-      });
-      const lineGeo = new THREE.BufferGeometry();
-      lineGeo.setAttribute('position', new THREE.BufferAttribute(positions, 3));
-      const lineMat = new THREE.LineBasicMaterial({
-        color: bodyColor(body.id),
-        opacity: 0.6,
-        transparent: true,
-      });
-      orbitGroup.add(new THREE.LineLoop(lineGeo, lineMat));
-    }
-
-    // Resize
-    const onResize = () => {
-      if (!mount) return;
-      const w = mount.clientWidth;
-      const h = mount.clientHeight;
-      camera.aspect = w / h;
-      camera.updateProjectionMatrix();
-      renderer.setSize(w, h);
-    };
-    window.addEventListener('resize', onResize);
-
-    // Animation loop: place each body at the current propagated position
-    let raf = 0;
-    const render = () => {
-      for (const body of bodies) {
-        if (body.sphereOfInfluence === 0 || body.sphereOfInfluence === Infinity) continue;
-        const parent = bodies.find((b) => b.id === body.parentId);
-        if (!parent) continue;
-        const pos = positionAt(body.orbit, parent.gravitationalParameter, ut);
-        const mesh = meshById.get(body.id);
-        if (mesh) mesh.position.set(pos.x, pos.y, pos.z);
-      }
-      renderer.render(scene, camera);
-      raf = requestAnimationFrame(render);
-    };
-    render();
-
-    return () => {
-      cancelAnimationFrame(raf);
-      window.removeEventListener('resize', onResize);
-      renderer.dispose();
-      mount.removeChild(renderer.domElement);
-    };
-  }, [bodies, ut]);
-
-  return <div ref={mountRef} style={{ width: '100%', height: '100%' }} />;
-}
-
-function bodyColor(id: string): number {
-  // Map common body names to colors; default to white
-  const map: Record<string, number> = {
-    kerbol: 0xffcc33,
-    kerbin: 0x3a7d8c,
-    mun: 0xaaaaaa,
-    minmus: 0x997a66,
-    duna: 0xc46030,
-    ike: 0x776655,
-    eve: 0x6b4ea0,
-    gilly: 0x665544,
-    jool: 0xa55a2a,
-    laythe: 0x4a6da0,
-    vall: 0x665544,
-    tylo: 0x997a66,
-    bop: 0x444444,
-    pol: 0x333333,
-    moho: 0x664433,
-    eeloo: 0xeeeeff,
-  };
-  return map[id] ?? 0xffffff;
-}
 
 export function App() {
-  const { bodies, ut, setUt, error } = useUniverse();
+  const { snapshot, status, lastUpdate, messageCount, error } = useLiveState(API_URL);
-  const [playing, setPlaying] = useState(true);
+  const liveUt = snapshot?.ut ?? 0;
-  const [speed, setSpeed] = useState(60); // 1s of wall = 60s of KSP UT
 
+  // Time controls
+  const [displayUt, setDisplayUt] = useState<number>(liveUt);
+  const [playing, setPlaying] = useState(true);
+  const [speed, setSpeed] = useState(1);
+
+  // Selection
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  // Focus toggles
+  const [showPlanetOrbits, setShowPlanetOrbits] = useState(true);
+  const [showMoonOrbits, setShowMoonOrbits] = useState(true);
+  const [showVesselOrbits, setShowVesselOrbits] = useState(true);
+
+  // When a new snapshot arrives, jump displayUt to liveUt if we're
+  // currently "in sync" (playing and at the live edge).
+  useEffect(() => {
+    if (playing && displayUt >= liveUt - 1) {
+      setDisplayUt(liveUt);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [liveUt]);
+
+  // Advance displayUt when playing
   useEffect(() => {
     if (!playing) return;
-    const id = setInterval(() => setUt((u) => u + speed), 1000);
+    const id = setInterval(() => {
+      setDisplayUt((u) => u + speed);
+    }, 1000);
     return () => clearInterval(id);
   }, [playing, speed]);
 
+  const displaySnapshot: UniverseSnapshot = snapshot ?? FALLBACK_SNAPSHOT;
+  const vesselCount = displaySnapshot.vessels.length;
+  const bodyCount = displaySnapshot.bodies.length;
+
   return (
     <div style={{ width: '100vw', height: '100vh', position: 'relative', background: '#000' }}>
-      <Scene bodies={bodies} ut={ut} />
+      <Scene
+        snapshot={displaySnapshot}
+        ut={displayUt}
+        followId={selectedId}
+        showPlanetOrbits={showPlanetOrbits}
+        showMoonOrbits={showMoonOrbits}
+        showVesselOrbits={showVesselOrbits}
+        onSelect={setSelectedId}
+      />
 
-      <div
+      <StatusPill
-        style={{
+        status={status}
-          position: 'absolute',
+        lastUpdate={lastUpdate}
-          top: 12,
+        messageCount={messageCount}
-          left: 12,
+        vesselCount={vesselCount}
-          padding: '0.5rem 0.75rem',
+        bodyCount={bodyCount}
-          background: 'rgba(0,0,0,0.6)',
+      />
-          color: 'white',
+
-          borderRadius: 6,
+      <TimeControls
-          fontFamily: 'monospace',
+        ut={displayUt}
-          fontSize: 13,
+        liveUt={liveUt}
+        playing={playing}
+        speed={speed}
+        onPlayPause={() => setPlaying((p) => !p)}
+        onSpeed={(s) => {
+          setSpeed(s);
+          if (s > 0) setPlaying(true);
         }}
-      >
+        onReverse={() => setSpeed((s) => -s)}
-        <div style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
+        onReset={() => {
-          <strong>Kerbal RT</strong>
+          setDisplayUt(liveUt);
-          <Pill tone={error ? 'danger' : 'success'}>
+          setPlaying(true);
-            {error ? 'API offline' : `${bodies.length} bodies`}
+          setSpeed(1);
-          </Pill>
+          setSelectedId(null);
+        }}
+        onScrub={(u) => {
+          setDisplayUt(u);
+          setPlaying(false);
+        }}
+      />
+
+      <VesselList
+        vessels={displaySnapshot.vessels}
+        selectedId={selectedId}
+        onSelect={setSelectedId}
+      />
+
+      <FocusPanel
+        showPlanetOrbits={showPlanetOrbits}
+        showMoonOrbits={showMoonOrbits}
+        showVesselOrbits={showVesselOrbits}
+        onTogglePlanet={() => setShowPlanetOrbits((v) => !v)}
+        onToggleMoon={() => setShowMoonOrbits((v) => !v)}
+        onToggleVessel={() => setShowVesselOrbits((v) => !v)}
+      />
+
+      <CalculatorsPanel snapshot={displaySnapshot} scanFromUt={displayUt} />
+
+      {error && (
+        <div
+          style={{
+            position: 'absolute',
+            bottom: 12,
+            left: 12,
+            padding: '0.4rem 0.6rem',
+            background: 'rgba(200, 0, 0, 0.3)',
+            color: '#fff',
+            borderRadius: 4,
+            fontFamily: 'monospace',
+            fontSize: 11,
+          }}
+        >
+          {error}
         </div>
-        <div style={{ marginTop: 4 }}>UT {formatUtAsKspDate(ut)}</div>
+      )}
-        <div style={{ display: 'flex', gap: '0.25rem', marginTop: 8 }}>
-          <button onClick={() => setPlaying((p) => !p)}>{playing ? '⏸' : '▶'}</button>
-          <button onClick={() => setUt(0)}>Reset</button>
-          {[1, 60, 3600, 86400].map((s) => (
-            <button
-              key={s}
-              onClick={() => setSpeed(s)}
-              style={{ fontWeight: speed === s ? 'bold' : 'normal' }}
-            >
-              ×{s < 60 ? s : s < 3600 ? `${s / 60}m` : `${s / 3600}h`}
-            </button>
-          ))}
-        </div>
-      </div>
 
       <div
         style={{
           position: 'absolute',
           bottom: 12,
           right: 12,
-          color: 'rgba(255,255,255,0.5)',
+          color: 'rgba(255,255,255,0.4)',
-          fontSize: 11,
+          fontSize: 10,
           fontFamily: 'monospace',
         }}
       >
-        Phase 0 skeleton · Three.js
+        Phase 2 — live map · mock-telemetry driving the WS
       </div>
     </div>
   );

apps/live-map/src/calculators/eclipse.ts

@@ -0,0 +1,243 @@
+/**
+ * Eclipse calculator — finds the next N times when the sun (Kerbol)
+ * is occluded from an observer's point of view by another body.
+ *
+ * Algorithm: scan forward in UT at fixed steps, refining around
+ * the transition points with bisection. Treats the sun as a point
+ * source (parallel rays) — accurate for KSP scale.
+ */
+import type { CelestialBody } from '@kerbal-rt/shared-types';
+import { bodyPositionAt } from '../scene/layout.js';
+import { shadowFraction } from '@kerbal-rt/orbital-math';
+
+export interface EclipseWindow {
+  /** UT at which the eclipse begins (sun starts being occluded). */
+  utStart: number;
+  /** UT at which the eclipse ends. */
+  utEnd: number;
+  /** Maximum shadow fraction during the window (0..1). */
+  maxFraction: number;
+  /** UT at which the max occurs. */
+  utPeak: number;
+}
+
+export interface EclipseOptions {
+  observerId: string;
+  eclipserId: string;
+  /** Scan starts at this UT. */
+  startUt: number;
+  /** How many windows to find. */
+  count?: number;
+  /** Max time to scan forward (default ~1 KSP year). */
+  maxSearchTime?: number;
+  /** Coarse scan step (default 600 = 10 KSP minutes). */
+  stepSec?: number;
+  /** Threshold for "eclipse started". */
+  threshold?: number;
+}
+
+/**
+ * Find the next `count` eclipse windows where `eclipser` occludes
+ * the sun as seen from `observer`.
+ *
+ * Returns an empty array if observer and eclipser are the same body
+ * or if either is Kerbol (the sun can't eclipse itself, and
+ * eclipsers behind the sun don't make sense).
+ */
+export function findEclipseWindows(
+  bodies: CelestialBody[],
+  options: EclipseOptions,
+): EclipseWindow[] {
+  const {
+    observerId,
+    eclipserId,
+    startUt,
+    count = 3,
+    maxSearchTime = 426 * 6 * 3600, // 1 KSP year
+    stepSec = 600,
+    threshold = 0.05,
+  } = options;
+
+  if (observerId === eclipserId) return [];
+  const observer = bodies.find((b) => b.id === observerId);
+  const eclipser = bodies.find((b) => b.id === eclipserId);
+  if (!observer || !eclipser) return [];
+
+  const windows: EclipseWindow[] = [];
+  const end = startUt + maxSearchTime;
+
+  // Coarse scan: find the start of an eclipse (transition from below
+  // threshold to above threshold). Then refine to find utStart, utPeak,
+  // utEnd.
+  let inEclipse = false;
+  let current: Partial<EclipseWindow> = {};
+
+  // If we start in the middle of an eclipse, bisect backwards to find utStart.
+  const startF = computeShadowFraction(bodies, observerId, eclipserId, startUt);
+  if (startF > threshold) {
+    inEclipse = true;
+    const utStart = refine(
+      bodies,
+      observerId,
+      eclipserId,
+      Math.max(0, startUt - stepSec),
+      startUt,
+      threshold,
+      'down',
+    );
+    current = { utStart };
+  }
+
+  let t = startUt + stepSec;
+  while (t < end && windows.length < count) {
+    const f = computeShadowFraction(bodies, observerId, eclipserId, t);
+    if (!inEclipse && f > threshold) {
+      // Eclipse just started — bisect to find exact start
+      const utStart = refine(bodies, observerId, eclipserId, t - stepSec, t, threshold, 'up');
+      inEclipse = true;
+      current = { utStart };
+    } else if (inEclipse && f < threshold) {
+      // Eclipse just ended
+      const utEnd = refine(bodies, observerId, eclipserId, t - stepSec, t, threshold, 'down');
+      const utPeak = refine(
+        bodies,
+        observerId,
+        eclipserId,
+        current.utStart!,
+        utEnd,
+        threshold,
+        'max',
+      );
+      const maxFraction = computeShadowFraction(bodies, observerId, eclipserId, utPeak);
+      windows.push({
+        utStart: current.utStart!,
+        utPeak,
+        utEnd,
+        maxFraction,
+      });
+      inEclipse = false;
+      current = {};
+    }
+    t += stepSec;
+  }
+
+  // If we ended while still in eclipse, close it.
+  if (inEclipse) {
+    const utEnd = refine(
+      bodies,
+      observerId,
+      eclipserId,
+      t - stepSec,
+      t + stepSec,
+      threshold,
+      'down',
+    );
+    const utPeak = refine(
+      bodies,
+      observerId,
+      eclipserId,
+      current.utStart!,
+      utEnd,
+      threshold,
+      'max',
+    );
+    const maxFraction = computeShadowFraction(bodies, observerId, eclipserId, utPeak);
+    windows.push({
+      utStart: current.utStart!,
+      utPeak,
+      utEnd,
+      maxFraction,
+    });
+  }
+
+  return windows;
+}
+
+/** Shadow fraction at a single instant. */
+export function computeShadowFraction(
+  bodies: CelestialBody[],
+  observerId: string,
+  eclipserId: string,
+  ut: number,
+): number {
+  const observer = bodies.find((b) => b.id === observerId);
+  const eclipser = bodies.find((b) => b.id === eclipserId);
+  if (!observer || !eclipser) return 0;
+
+  // Sun is Kerbol (the system root). For this to work the catalog
+  // must have a single body with parentId === null — the star.
+  const sun = bodies.find((b) => b.parentId === null);
+  if (!sun) return 0;
+
+  // The reference frame for shadowFraction is: vectors from the
+  // observer toward the sun, and from the observer toward the
+  // eclipser. We compute them in heliocentric coordinates then
+  // shift.
+  const sunPos = bodyPositionAt(bodies, sun.id, ut);
+  const eclipserPos = bodyPositionAt(bodies, eclipserId, ut);
+  const observerPos = bodyPositionAt(bodies, observerId, ut);
+
+  // For solar eclipses, "eclipser" sits between observer and sun.
+  // We treat the eclipser as the occluder and the sun as the light
+  // source. shadowFraction() expects: vector from observer to sun,
+  // and vector from observer to eclipser.
+  // Observer-to-sun = sunPos - observerPos
+  // Observer-to-eclipser = eclipserPos - observerPos
+  // BUT shadowFraction actually wants: vector from observer to sun,
+  // and the eclipser center RELATIVE to the observer-to-sun line.
+  // Re-reading the function: it computes perpDist of occluder
+  // center to sun-direction line, and uses the sun-direction
+  // projection. So the right call is:
+  return shadowFraction(
+    { x: sunPos.x - observerPos.x, y: sunPos.y - observerPos.y, z: sunPos.z - observerPos.z },
+    {
+      x: eclipserPos.x - observerPos.x,
+      y: eclipserPos.y - observerPos.y,
+      z: eclipserPos.z - observerPos.z,
+    },
+    eclipser.radius,
+  );
+}
+
+/**
+ * Bisection to find when the shadow fraction crosses the threshold.
+ * direction = 'up'  → find t such that f(t) ≈ threshold going upward
+ * direction = 'down' → find t such that f(t) ≈ threshold going downward
+ * direction = 'max' → find t that maximizes f in the range
+ */
+function refine(
+  bodies: CelestialBody[],
+  observerId: string,
+  eclipserId: string,
+  tLo: number,
+  tHi: number,
+  threshold: number,
+  direction: 'up' | 'down' | 'max',
+): number {
+  if (direction === 'max') {
+    // Golden-section or simple ternary search on a small interval.
+    // For 600s windows this is plenty.
+    let lo = tLo;
+    let hi = tHi;
+    for (let i = 0; i < 32; i++) {
+      const m1 = lo + (hi - lo) / 3;
+      const m2 = hi - (hi - lo) / 3;
+      const f1 = computeShadowFraction(bodies, observerId, eclipserId, m1);
+      const f2 = computeShadowFraction(bodies, observerId, eclipserId, m2);
+      if (f1 < f2) lo = m1;
+      else hi = m2;
+    }
+    return (lo + hi) / 2;
+  }
+
+  // Bisection: 30 iterations gets us to 1-second precision on a 600s range.
+  let lo = tLo;
+  let hi = tHi;
+  for (let i = 0; i < 30; i++) {
+    const mid = (lo + hi) / 2;
+    const f = computeShadowFraction(bodies, observerId, eclipserId, mid);
+    if (direction === 'up' ? f < threshold : f > threshold) lo = mid;
+    else hi = mid;
+  }
+  return (lo + hi) / 2;
+}

apps/live-map/src/calculators/overpass.ts

@@ -0,0 +1,151 @@
+/**
+ * Overpass calculator — finds the next N closest approaches between
+ * a vessel and a target (vessel, body, or ground station).
+ *
+ * Approach: sample the distance at fixed steps, then refine each
+ * minimum with ternary search.
+ */
+import type { CelestialBody, Vessel, GroundStation } from '@kerbal-rt/shared-types';
+import { bodyPositionAt, vesselPositionAt } from '../scene/layout.js';
+
+export type TargetKind = 'vessel' | 'body' | 'station';
+
+export interface Target {
+  kind: TargetKind;
+  id: string;
+  name: string;
+}
+
+export interface OverpassWindow {
+  /** UT at which the closest approach occurs. */
+  utPeak: number;
+  /** Distance at closest approach (meters). */
+  minDistance: number;
+  /** The target. */
+  target: Target;
+}
+
+export interface OverpassOptions {
+  observer: Vessel;
+  target: Target;
+  bodies: CelestialBody[];
+  vessels: Vessel[];
+  groundStations: GroundStation[];
+  startUt: number;
+  count?: number;
+  maxSearchTime?: number;
+  stepSec?: number;
+  /** Distance threshold for "interesting" passes (default 1000 km). */
+  distanceThreshold?: number;
+}
+
+/**
+ * Find the next `count` closest-approach events.
+ *
+ * Coarse scan: at each step, compute distance. Track the local minima
+ * (a point lower than both neighbors). For each local min, refine
+ * with ternary search to find the true peak (min distance).
+ *
+ * Returns at most `count` events with minDistance < distanceThreshold.
+ */
+export function findOverpasses(options: OverpassOptions): OverpassWindow[] {
+  const {
+    observer,
+    target,
+    bodies,
+    vessels,
+    groundStations,
+    startUt,
+    count = 5,
+    maxSearchTime = 426 * 6 * 3600, // 1 KSP year
+    stepSec = 120, // 2 minutes
+    distanceThreshold = 1_000_000, // 1000 km
+  } = options;
+
+  const dist = (t: number) => distanceAt(bodies, vessels, groundStations, observer, target, t);
+
+  const passes: OverpassWindow[] = [];
+  const end = startUt + maxSearchTime;
+  let prev = dist(startUt);
+  let curr = prev;
+  let t = startUt + stepSec;
+
+  while (t < end && passes.length < count) {
+    const next = dist(t);
+    // Local minimum: curr < prev AND curr < next
+    if (curr < prev && curr < next && curr < distanceThreshold) {
+      // Refine
+      const utPeak = refineMinimum((a: number) => dist(a), t - stepSec, t + stepSec);
+      const minDistance = dist(utPeak);
+      passes.push({ utPeak, minDistance, target });
+      // Skip ahead past the peak so we don't double-count
+      t = utPeak + stepSec * 5;
+      prev = dist(t);
+      curr = prev;
+      t += stepSec;
+      continue;
+    }
+    prev = curr;
+    curr = next;
+    t += stepSec;
+  }
+
+  return passes;
+}
+
+function distanceAt(
+  bodies: CelestialBody[],
+  vessels: Vessel[],
+  groundStations: GroundStation[],
+  observer: Vessel,
+  target: Target,
+  ut: number,
+): number {
+  const obs = vesselPositionAt(bodies, observer, ut);
+  let tgt: { x: number; y: number; z: number };
+  if (target.kind === 'vessel') {
+    const v = vessels.find((x) => x.id === target.id);
+    if (!v) return Number.POSITIVE_INFINITY;
+    tgt = vesselPositionAt(bodies, v, ut);
+  } else if (target.kind === 'body') {
+    tgt = bodyPositionAt(bodies, target.id, ut);
+  } else {
+    // station
+    const s = groundStations.find((x) => x.id === target.id);
+    if (!s) return Number.POSITIVE_INFINITY;
+    const body = bodies.find((b) => b.id === s.bodyId);
+    if (!body) return Number.POSITIVE_INFINITY;
+    const bodyPos = bodyPositionAt(bodies, body.id, ut);
+    // Ground station sits on the body surface. Convert (lat, lon, alt)
+    // to a heliocentric offset relative to the body's center.
+    // For simplicity (no rotation) we just add a small offset along
+    // the body's orbital direction.
+    const R = body.radius + s.alt;
+    const lat = (s.lat * Math.PI) / 180;
+    const lon = (s.lon * Math.PI) / 180;
+    tgt = {
+      x: bodyPos.x + R * Math.cos(lat) * Math.cos(lon),
+      y: bodyPos.y + R * Math.cos(lat) * Math.sin(lon),
+      z: bodyPos.z + R * Math.sin(lat),
+    };
+  }
+  const dx = obs.x - tgt.x;
+  const dy = obs.y - tgt.y;
+  const dz = obs.z - tgt.z;
+  return Math.hypot(dx, dy, dz);
+}
+
+/** Ternary search to find the minimum of dist in [tLo, tHi]. */
+function refineMinimum(dist: (t: number) => number, tLo: number, tHi: number): number {
+  let lo = tLo;
+  let hi = tHi;
+  for (let i = 0; i < 40; i++) {
+    const m1 = lo + (hi - lo) / 3;
+    const m2 = hi - (hi - lo) / 3;
+    const f1 = dist(m1);
+    const f2 = dist(m2);
+    if (f1 > f2) lo = m1;
+    else hi = m2;
+  }
+  return (lo + hi) / 2;
+}

apps/live-map/src/hooks/useLiveState.ts

@@ -0,0 +1,123 @@
+/**
+ * useLiveState — subscribe to the kerbal-rt API over WebSocket and
+ * expose the latest UniverseSnapshot plus connection status.
+ *
+ * Auto-reconnects with exponential backoff on drop. Falls back to
+ * polling /api/v1/state every 5s if WebSocket fails to connect after
+ * 3 retries (e.g. a proxy doesn't support upgrade).
+ */
+import { useEffect, useRef, useState } from 'react';
+import type { LiveMessage, UniverseSnapshot } from '@kerbal-rt/shared-types';
+
+export type ConnectionState = 'connecting' | 'open' | 'closed' | 'fallback';
+
+export interface LiveState {
+  snapshot: UniverseSnapshot | null;
+  status: ConnectionState;
+  lastUpdate: string | null;
+  messageCount: number;
+  error: string | null;
+}
+
+const RECONNECT_DELAYS_MS = [1000, 2000, 5000, 10_000, 30_000];
+
+export function useLiveState(apiUrl: string): LiveState {
+  const [snapshot, setSnapshot] = useState<UniverseSnapshot | null>(null);
+  const [status, setStatus] = useState<ConnectionState>('connecting');
+  const [lastUpdate, setLastUpdate] = useState<string | null>(null);
+  const [messageCount, setMessageCount] = useState(0);
+  const [error, setError] = useState<string | null>(null);
+  const reconnectAttempt = useRef(0);
+  const stopped = useRef(false);
+
+  useEffect(() => {
+    stopped.current = false;
+    let pollTimer: number | null = null;
+    let reconnectTimer: number | null = null;
+    let ws: WebSocket | null = null;
+
+    const startPollingFallback = () => {
+      if (pollTimer) return;
+      setStatus('fallback');
+      const tick = async () => {
+        try {
+          const res = await fetch(`${apiUrl}/api/v1/state`);
+          if (res.ok) {
+            const body = await res.json();
+            if (!body.error && body.data) {
+              setSnapshot(body.data as UniverseSnapshot);
+              setLastUpdate(new Date().toISOString());
+              setMessageCount((n) => n + 1);
+            }
+          }
+        } catch (e) {
+          setError(String((e as Error).message ?? e));
+        }
+      };
+      void tick();
+      pollTimer = window.setInterval(tick, 5000);
+    };
+
+    const scheduleReconnect = () => {
+      if (stopped.current) return;
+      if (reconnectAttempt.current >= RECONNECT_DELAYS_MS.length) {
+        // Gave up on WS, fall back to polling.
+        startPollingFallback();
+        return;
+      }
+      const delay = RECONNECT_DELAYS_MS[reconnectAttempt.current] ?? 30_000;
+      reconnectAttempt.current += 1;
+      setStatus('closed');
+      reconnectTimer = window.setTimeout(connect, delay);
+    };
+
+    const connect = () => {
+      if (stopped.current) return;
+      setStatus('connecting');
+      setError(null);
+      const wsUrl = apiUrl.replace(/^http/, 'ws') + '/api/v1/live';
+      try {
+        ws = new WebSocket(wsUrl);
+      } catch (e) {
+        setError(String((e as Error).message ?? e));
+        scheduleReconnect();
+        return;
+      }
+      ws.onopen = () => {
+        setStatus('open');
+        reconnectAttempt.current = 0; // success — reset backoff
+      };
+      ws.onmessage = (event) => {
+        setMessageCount((n) => n + 1);
+        setLastUpdate(new Date().toISOString());
+        try {
+          const msg = JSON.parse(event.data) as LiveMessage;
+          if (msg.type === 'snapshot') {
+            setSnapshot(msg.snapshot);
+          }
+        } catch (e) {
+          setError(`bad message: ${String((e as Error).message ?? e)}`);
+        }
+      };
+      ws.onerror = () => {
+        // close will fire too
+      };
+      ws.onclose = () => {
+        scheduleReconnect();
+      };
+    };
+
+    connect();
+    return () => {
+      stopped.current = true;
+      if (reconnectTimer) window.clearTimeout(reconnectTimer);
+      if (pollTimer) window.clearInterval(pollTimer);
+      if (ws) {
+        ws.onclose = null;
+        ws.close();
+      }
+    };
+  }, [apiUrl]);
+
+  return { snapshot, status, lastUpdate, messageCount, error };
+}

apps/live-map/src/panels/CalculatorsPanel.tsx

@@ -0,0 +1,365 @@
+/**
+ * CalculatorsPanel — collapsible panel with two calculators:
+ *
+ *   - Eclipse: when does the sun get occluded for a given observer
+ *     by a given body?
+ *   - Overpass: when does a vessel come closest to a target
+ *     (vessel / body / ground station)?
+ *
+ * The math lives in ./calculators/{eclipse,overpass}.ts and is
+ * tested independently.
+ */
+import { useMemo, useState } from 'react';
+import type { UniverseSnapshot, Vessel } from '@kerbal-rt/shared-types';
+import { findEclipseWindows, type EclipseWindow } from '../calculators/eclipse.js';
+import { findOverpasses, type OverpassWindow, type Target } from '../calculators/overpass.js';
+import { formatKspTime } from '../timeFormat.js';
+
+export interface CalculatorsPanelProps {
+  snapshot: UniverseSnapshot;
+  /** UT to start scanning from. Usually the current scene UT. */
+  scanFromUt: number;
+}
+
+const PANEL_STYLE: React.CSSProperties = {
+  position: 'absolute',
+  bottom: 12,
+  left: '50%',
+  transform: 'translateX(-50%)',
+  width: 540,
+  maxHeight: 'calc(100vh - 200px)',
+  background: 'rgba(0,0,0,0.7)',
+  color: 'white',
+  borderRadius: 6,
+  fontFamily: 'monospace',
+  fontSize: 12,
+  backdropFilter: 'blur(4px)',
+  border: '1px solid rgba(255,255,255,0.1)',
+  display: 'flex',
+  flexDirection: 'column',
+  overflow: 'hidden',
+};
+
+const HEADER_STYLE: React.CSSProperties = {
+  padding: '0.4rem 0.7rem',
+  display: 'flex',
+  alignItems: 'center',
+  gap: 6,
+  borderBottom: '1px solid rgba(255,255,255,0.1)',
+  cursor: 'pointer',
+  userSelect: 'none',
+};
+
+const TAB_STYLE: (active: boolean) => React.CSSProperties = (active) => ({
+  padding: '0.4rem 0.7rem',
+  cursor: 'pointer',
+  background: active ? 'rgba(255,255,255,0.12)' : 'transparent',
+  borderRight: '1px solid rgba(255,255,255,0.05)',
+});
+
+const BODY_STYLE: React.CSSProperties = {
+  padding: '0.6rem 0.7rem',
+  overflow: 'auto',
+  maxHeight: 280,
+};
+
+const ROW_STYLE: React.CSSProperties = {
+  display: 'flex',
+  gap: 4,
+  alignItems: 'center',
+  marginBottom: 4,
+  fontSize: 11,
+};
+
+const INPUT_STYLE: React.CSSProperties = {
+  background: 'rgba(0,0,0,0.4)',
+  color: 'white',
+  border: '1px solid rgba(255,255,255,0.15)',
+  padding: '0.15rem 0.3rem',
+  borderRadius: 3,
+  fontFamily: 'inherit',
+  fontSize: 11,
+};
+
+const RESULT_STYLE: React.CSSProperties = {
+  marginTop: 8,
+  padding: '0.3rem 0.5rem',
+  background: 'rgba(255,255,255,0.04)',
+  borderRadius: 3,
+  fontSize: 11,
+};
+
+const BUTTON_STYLE: React.CSSProperties = {
+  background: 'rgba(68, 170, 255, 0.2)',
+  border: '1px solid rgba(68, 170, 255, 0.4)',
+  color: 'white',
+  padding: '0.2rem 0.5rem',
+  borderRadius: 3,
+  cursor: 'pointer',
+  fontFamily: 'inherit',
+  fontSize: 11,
+};
+
+type Tab = 'eclipse' | 'overpass';
+
+export function CalculatorsPanel({ snapshot, scanFromUt }: CalculatorsPanelProps) {
+  const [open, setOpen] = useState(false);
+  const [tab, setTab] = useState<Tab>('eclipse');
+
+  return (
+    <div style={PANEL_STYLE}>
+      <div style={HEADER_STYLE} onClick={() => setOpen((o) => !o)}>
+        <span
+          style={{
+            fontWeight: 700,
+            textTransform: 'uppercase',
+            letterSpacing: '0.05em',
+            fontSize: 10,
+          }}
+        >
+          Calculators
+        </span>
+        <div style={{ flex: 1 }} />
+        <span style={{ opacity: 0.6, fontSize: 10 }}>{open ? '▼' : '▲'}</span>
+      </div>
+      {open && (
+        <>
+          <div style={{ display: 'flex', borderBottom: '1px solid rgba(255,255,255,0.1)' }}>
+            <div style={TAB_STYLE(tab === 'eclipse')} onClick={() => setTab('eclipse')}>
+              Eclipse
+            </div>
+            <div style={TAB_STYLE(tab === 'overpass')} onClick={() => setTab('overpass')}>
+              Overpass
+            </div>
+          </div>
+          <div style={BODY_STYLE}>
+            {tab === 'eclipse' ? (
+              <EclipseTab snapshot={snapshot} scanFromUt={scanFromUt} />
+            ) : (
+              <OverpassTab snapshot={snapshot} scanFromUt={scanFromUt} />
+            )}
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+
+// ─── Eclipse tab ──────────────────────────────────────────────────────────
+
+function EclipseTab({ snapshot, scanFromUt }: { snapshot: UniverseSnapshot; scanFromUt: number }) {
+  const planets = snapshot.bodies.filter((b) => b.kind === 'planet');
+  const moons = snapshot.bodies.filter((b) => b.kind === 'moon');
+  const observers = [...planets, ...moons];
+  const eclipsers = snapshot.bodies.filter((b) => b.kind !== 'star');
+
+  const [observerId, setObserverId] = useState<string>(observers[0]?.id ?? '');
+  const [eclipserId, setEclipserId] = useState<string>(eclipsers[1]?.id ?? eclipsers[0]?.id ?? '');
+  const [result, setResult] = useState<EclipseWindow[] | null>(null);
+
+  const canRun = !!observerId && !!eclipserId && observerId !== eclipserId;
+
+  const calculate = () => {
+    if (!canRun) return;
+    const windows = findEclipseWindows(snapshot.bodies, {
+      observerId,
+      eclipserId,
+      startUt: scanFromUt,
+      count: 3,
+    });
+    setResult(windows);
+  };
+
+  return (
+    <div>
+      <div style={ROW_STYLE}>
+        <span style={{ minWidth: 70 }}>Observer:</span>
+        <select
+          style={INPUT_STYLE}
+          value={observerId}
+          onChange={(e) => setObserverId(e.target.value)}
+        >
+          {observers.map((b) => (
+            <option key={b.id} value={b.id}>
+              {b.name}
+            </option>
+          ))}
+        </select>
+      </div>
+      <div style={ROW_STYLE}>
+        <span style={{ minWidth: 70 }}>Eclipser:</span>
+        <select
+          style={INPUT_STYLE}
+          value={eclipserId}
+          onChange={(e) => setEclipserId(e.target.value)}
+        >
+          {eclipsers.map((b) => (
+            <option key={b.id} value={b.id}>
+              {b.name}
+            </option>
+          ))}
+        </select>
+      </div>
+      <div style={ROW_STYLE}>
+        <span style={{ minWidth: 70 }}>From UT:</span>
+        <span style={{ opacity: 0.8 }}>{formatKspTime(scanFromUt)}</span>
+      </div>
+      <div style={ROW_STYLE}>
+        <button style={BUTTON_STYLE} onClick={calculate} disabled={!canRun}>
+          Calculate
+        </button>
+      </div>
+      {result !== null && (
+        <div>
+          {result.length === 0 ? (
+            <div style={{ ...RESULT_STYLE, opacity: 0.6 }}>
+              No eclipse windows found within 1 KSP year.
+            </div>
+          ) : (
+            result.map((w, i) => (
+              <div key={i} style={RESULT_STYLE}>
+                <div>
+                  #{i + 1} — {formatKspTime(w.utStart)} → {formatKspTime(w.utEnd)}
+                </div>
+                <div style={{ opacity: 0.7, fontSize: 10 }}>
+                  peak at {formatKspTime(w.utPeak)}, max fraction {(w.maxFraction * 100).toFixed(0)}
+                  %
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ─── Overpass tab ─────────────────────────────────────────────────────────
+
+function OverpassTab({ snapshot, scanFromUt }: { snapshot: UniverseSnapshot; scanFromUt: number }) {
+  const vessels = snapshot.vessels;
+  const allBodies = snapshot.bodies;
+
+  const [observerId, setObserverId] = useState<string>(vessels[0]?.id ?? '');
+  const [targetKind, setTargetKind] = useState<'vessel' | 'body' | 'station'>('body');
+  const [targetId, setTargetId] = useState<string>(
+    allBodies.find((b) => b.kind === 'planet')?.id ?? '',
+  );
+  const [distanceKm, setDistanceKm] = useState(1000);
+  const [result, setResult] = useState<OverpassWindow[] | null>(null);
+
+  const observer = vessels.find((v: Vessel) => v.id === observerId);
+  const targetOptions = useMemo(() => {
+    if (targetKind === 'vessel') return vessels.filter((v) => v.id !== observerId);
+    if (targetKind === 'body') return allBodies.filter((b) => b.kind !== 'star');
+    return snapshot.groundStations;
+  }, [targetKind, observerId, vessels, allBodies, snapshot.groundStations]);
+
+  const target: Target | null = useMemo(() => {
+    if (!targetId) return null;
+    return {
+      kind: targetKind,
+      id: targetId,
+      name: targetOptions.find((o) => o.id === targetId)?.name ?? targetId,
+    };
+  }, [targetKind, targetId, targetOptions]);
+
+  const canRun = !!observer && !!target;
+
+  const calculate = () => {
+    if (!canRun || !target) return;
+    const passes = findOverpasses({
+      observer,
+      target,
+      bodies: snapshot.bodies,
+      vessels: snapshot.vessels,
+      groundStations: snapshot.groundStations,
+      startUt: scanFromUt,
+      count: 5,
+      distanceThreshold: distanceKm * 1000,
+    });
+    setResult(passes);
+  };
+
+  return (
+    <div>
+      <div style={ROW_STYLE}>
+        <span style={{ minWidth: 80 }}>Observer:</span>
+        <select
+          style={INPUT_STYLE}
+          value={observerId}
+          onChange={(e) => setObserverId(e.target.value)}
+        >
+          {vessels.map((v) => (
+            <option key={v.id} value={v.id}>
+              {v.name}
+            </option>
+          ))}
+        </select>
+      </div>
+      <div style={ROW_STYLE}>
+        <span style={{ minWidth: 80 }}>Target kind:</span>
+        <select
+          style={INPUT_STYLE}
+          value={targetKind}
+          onChange={(e) => {
+            const k = e.target.value as 'vessel' | 'body' | 'station';
+            setTargetKind(k);
+            setTargetId(targetOptions[0]?.id ?? '');
+          }}
+        >
+          <option value="vessel">Vessel</option>
+          <option value="body">Body</option>
+          <option value="station">Ground station</option>
+        </select>
+      </div>
+      <div style={ROW_STYLE}>
+        <span style={{ minWidth: 80 }}>Target:</span>
+        <select style={INPUT_STYLE} value={targetId} onChange={(e) => setTargetId(e.target.value)}>
+          {targetOptions.map((o) => (
+            <option key={o.id} value={o.id}>
+              {o.name}
+            </option>
+          ))}
+        </select>
+      </div>
+      <div style={ROW_STYLE}>
+        <span style={{ minWidth: 80 }}>Max dist:</span>
+        <input
+          type="number"
+          min={1}
+          step={100}
+          value={distanceKm}
+          onChange={(e) => setDistanceKm(Number(e.target.value))}
+          style={{ ...INPUT_STYLE, width: 90 }}
+        />
+        <span style={{ opacity: 0.6, fontSize: 10 }}>km</span>
+      </div>
+      <div style={ROW_STYLE}>
+        <button style={BUTTON_STYLE} onClick={calculate} disabled={!canRun}>
+          Calculate
+        </button>
+      </div>
+      {result !== null && (
+        <div>
+          {result.length === 0 ? (
+            <div style={{ ...RESULT_STYLE, opacity: 0.6 }}>
+              No passes within {distanceKm} km in the next KSP year.
+            </div>
+          ) : (
+            result.map((w, i) => (
+              <div key={i} style={RESULT_STYLE}>
+                <div>
+                  #{i + 1} — {formatKspTime(w.utPeak)}
+                </div>
+                <div style={{ opacity: 0.7, fontSize: 10 }}>
+                  {target?.name}: min distance {(w.minDistance / 1000).toFixed(1)} km
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

apps/live-map/src/panels/FocusPanel.tsx

@@ -0,0 +1,74 @@
+/**
+ * FocusPanel — toggles for which orbit-line categories are visible.
+ */
+export interface FocusPanelProps {
+  showPlanetOrbits: boolean;
+  showMoonOrbits: boolean;
+  showVesselOrbits: boolean;
+  onTogglePlanet: () => void;
+  onToggleMoon: () => void;
+  onToggleVessel: () => void;
+}
+
+const PANEL_STYLE: React.CSSProperties = {
+  position: 'absolute',
+  top: 12,
+  right: 12,
+  padding: '0.5rem 0.75rem',
+  background: 'rgba(0,0,0,0.7)',
+  color: 'white',
+  borderRadius: 6,
+  fontSize: 11,
+  fontFamily: 'monospace',
+  backdropFilter: 'blur(4px)',
+  border: '1px solid rgba(255,255,255,0.1)',
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+};
+
+const ROW_STYLE: React.CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 6,
+  cursor: 'pointer',
+  userSelect: 'none',
+};
+
+export function FocusPanel(props: FocusPanelProps) {
+  const {
+    showPlanetOrbits,
+    showMoonOrbits,
+    showVesselOrbits,
+    onTogglePlanet,
+    onToggleMoon,
+    onToggleVessel,
+  } = props;
+  return (
+    <div style={PANEL_STYLE}>
+      <div
+        style={{
+          fontSize: 10,
+          opacity: 0.6,
+          textTransform: 'uppercase',
+          letterSpacing: '0.05em',
+          marginBottom: 4,
+        }}
+      >
+        Orbits
+      </div>
+      <label style={ROW_STYLE}>
+        <input type="checkbox" checked={showPlanetOrbits} onChange={onTogglePlanet} />
+        Planets
+      </label>
+      <label style={ROW_STYLE}>
+        <input type="checkbox" checked={showMoonOrbits} onChange={onToggleMoon} />
+        Moons
+      </label>
+      <label style={ROW_STYLE}>
+        <input type="checkbox" checked={showVesselOrbits} onChange={onToggleVessel} />
+        Vessels
+      </label>
+    </div>
+  );
+}

apps/live-map/src/panels/StatusPill.tsx

@@ -0,0 +1,73 @@
+/**
+ * StatusPill — connection + stale-data indicator.
+ *
+ * Shows:
+ *  - WS connection state (open / connecting / closed / fallback)
+ *  - "Data may be stale" warning if lastUpdate > STALE_THRESHOLD_S
+ *  - Number of messages received
+ */
+import { Pill } from '@kerbal-rt/ui';
+import type { ConnectionState } from '../hooks/useLiveState.js';
+
+export interface StatusPillProps {
+  status: ConnectionState;
+  lastUpdate: string | null;
+  messageCount: number;
+  vesselCount: number;
+  bodyCount: number;
+}
+
+const STALE_THRESHOLD_S = 60;
+
+export function StatusPill({
+  status,
+  lastUpdate,
+  messageCount,
+  vesselCount,
+  bodyCount,
+}: StatusPillProps) {
+  const isStale = lastUpdate
+    ? (Date.now() - new Date(lastUpdate).getTime()) / 1000 > STALE_THRESHOLD_S
+    : true;
+  const tone =
+    status === 'open' && !isStale
+      ? 'success'
+      : status === 'connecting' || status === 'fallback'
+        ? 'warn'
+        : 'danger';
+  const label =
+    status === 'open'
+      ? isStale
+        ? 'STALE'
+        : 'LIVE'
+      : status === 'connecting'
+        ? 'CONNECTING'
+        : status === 'fallback'
+          ? 'POLLING'
+          : 'OFFLINE';
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        top: 12,
+        left: '50%',
+        transform: 'translateX(-50%)',
+        display: 'flex',
+        gap: 6,
+        padding: '0.4rem 0.6rem',
+        background: 'rgba(0,0,0,0.6)',
+        borderRadius: 6,
+        backdropFilter: 'blur(4px)',
+        border: '1px solid rgba(255,255,255,0.1)',
+        fontFamily: 'monospace',
+        fontSize: 11,
+      }}
+    >
+      <Pill tone={tone}>{label}</Pill>
+      <Pill tone="neutral">{bodyCount} bodies</Pill>
+      <Pill tone="neutral">{vesselCount} vessels</Pill>
+      <Pill tone="neutral">{messageCount} msgs</Pill>
+    </div>
+  );
+}

apps/live-map/src/panels/TimeControls.tsx

@@ -0,0 +1,125 @@
+/**
+ * TimeControls — play/pause, speed multiplier, reverse, reset,
+ * and a slider to scrub the simulation UT.
+ *
+ * Time source of truth: `ut`. The Scene re-propagates every time
+ * `ut` changes. Mock-telemetry advances UT at 1 KSP-second per
+ * wall-clock second; pressing ▶ at speed ×1 gives you live
+ * playback. Higher speeds fast-forward.
+ */
+import type { ChangeEvent } from 'react';
+import { formatKspTime, formatKspDuration } from '../timeFormat.js';
+
+export interface TimeControlsProps {
+  ut: number;
+  /** UT of the most recent server snapshot (the "live edge"). */
+  liveUt: number;
+  playing: boolean;
+  speed: number;
+  onPlayPause: () => void;
+  onSpeed: (s: number) => void;
+  onReverse: () => void;
+  onReset: () => void;
+  onScrub: (ut: number) => void;
+}
+
+const SPEEDS: { value: number; label: string }[] = [
+  { value: 1, label: '×1' },
+  { value: 10, label: '×10' },
+  { value: 100, label: '×100' },
+  { value: 1000, label: '×1k' },
+  { value: 10000, label: '×10k' },
+  { value: 100000, label: '×100k' },
+];
+
+const PANEL_STYLE: React.CSSProperties = {
+  position: 'absolute',
+  top: 12,
+  left: 12,
+  padding: '0.5rem 0.75rem',
+  background: 'rgba(0,0,0,0.7)',
+  color: 'white',
+  borderRadius: 6,
+  fontFamily: 'monospace',
+  fontSize: 12,
+  minWidth: 380,
+  backdropFilter: 'blur(4px)',
+  border: '1px solid rgba(255,255,255,0.1)',
+};
+
+const BUTTON_STYLE: React.CSSProperties = {
+  background: 'rgba(255,255,255,0.08)',
+  border: '1px solid rgba(255,255,255,0.15)',
+  color: '#e6e6ee',
+  padding: '0.2rem 0.4rem',
+  borderRadius: 3,
+  cursor: 'pointer',
+  fontSize: 11,
+};
+
+const ACTIVE_BUTTON: React.CSSProperties = {
+  ...BUTTON_STYLE,
+  fontWeight: 700,
+  background: 'rgba(255,255,255,0.2)',
+};
+
+export function TimeControls(props: TimeControlsProps) {
+  const { ut, liveUt, playing, speed, onPlayPause, onSpeed, onReverse, onReset, onScrub } = props;
+  const isLive = ut === liveUt;
+  const behind = liveUt - ut;
+  const behindLabel =
+    behind === 0
+      ? 'live'
+      : behind > 0
+        ? `${formatKspDuration(behind)} behind`
+        : `${formatKspDuration(-behind)} ahead`;
+
+  return (
+    <div style={PANEL_STYLE}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 6, marginBottom: 6 }}>
+        <button onClick={onPlayPause} style={BUTTON_STYLE} title={playing ? 'Pause' : 'Play'}>
+          {playing ? '⏸' : '▶'}
+        </button>
+        <button onClick={onReverse} style={BUTTON_STYLE} title="Reverse time">
+          ⏪
+        </button>
+        <button onClick={onReset} style={BUTTON_STYLE} title="Snap to live">
+          ⤴
+        </button>
+        <div style={{ flex: 1 }} />
+        {SPEEDS.map((s) => (
+          <button
+            key={s.value}
+            onClick={() => onSpeed(s.value)}
+            style={speed === s.value ? ACTIVE_BUTTON : BUTTON_STYLE}
+          >
+            {s.label}
+          </button>
+        ))}
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 6, fontSize: 11 }}>
+        <span style={{ opacity: 0.6 }}>UT</span>
+        <span style={{ minWidth: 120 }}>{formatKspTime(ut)}</span>
+        <input
+          type="range"
+          min={Math.max(0, liveUt - 5 * 365 * 24 * 3600)}
+          max={liveUt + 365 * 24 * 3600}
+          step={60}
+          value={ut}
+          onChange={(e: ChangeEvent<HTMLInputElement>) => onScrub(Number(e.target.value))}
+          style={{ flex: 1 }}
+        />
+        <span
+          style={{
+            opacity: 0.7,
+            color: isLive ? '#7dff7d' : '#ffcc44',
+            minWidth: 90,
+            textAlign: 'right',
+          }}
+        >
+          {behindLabel}
+        </span>
+      </div>
+    </div>
+  );
+}

apps/live-map/src/panels/VesselList.tsx

@@ -0,0 +1,109 @@
+/**
+ * VesselList — sidebar of currently-known vessels.
+ *
+ * Click a vessel to track it (the camera follows + the orbit is
+ * highlighted). Click again to untrack.
+ */
+import type { Vessel } from '@kerbal-rt/shared-types';
+import { vesselColor } from '../scene/color.js';
+
+export interface VesselListProps {
+  vessels: Vessel[];
+  selectedId: string | null;
+  onSelect: (id: string | null) => void;
+}
+
+const PANEL_STYLE: React.CSSProperties = {
+  position: 'absolute',
+  top: 110,
+  left: 12,
+  width: 280,
+  maxHeight: 'calc(100vh - 200px)',
+  overflow: 'auto',
+  padding: '0.5rem',
+  background: 'rgba(0,0,0,0.7)',
+  color: 'white',
+  borderRadius: 6,
+  fontSize: 12,
+  fontFamily: 'monospace',
+  backdropFilter: 'blur(4px)',
+  border: '1px solid rgba(255,255,255,0.1)',
+};
+
+const ROW_STYLE: React.CSSProperties = {
+  padding: '0.4rem 0.5rem',
+  marginBottom: 2,
+  borderRadius: 3,
+  cursor: 'pointer',
+  background: 'rgba(255,255,255,0.04)',
+  border: '1px solid transparent',
+  display: 'flex',
+  alignItems: 'center',
+  gap: 6,
+};
+
+const ROW_ACTIVE: React.CSSProperties = {
+  ...ROW_STYLE,
+  background: 'rgba(255,255,255,0.12)',
+  border: '1px solid rgba(255,255,255,0.3)',
+};
+
+const DOT_STYLE: (color: number) => React.CSSProperties = (color) => ({
+  width: 8,
+  height: 8,
+  borderRadius: '50%',
+  background: `#${color.toString(16).padStart(6, '0')}`,
+  flexShrink: 0,
+});
+
+export function VesselList({ vessels, selectedId, onSelect }: VesselListProps) {
+  const sorted = [...vessels].sort((a, b) => a.name.localeCompare(b.name));
+  return (
+    <div style={PANEL_STYLE}>
+      <div
+        style={{
+          fontSize: 10,
+          opacity: 0.6,
+          textTransform: 'uppercase',
+          letterSpacing: '0.05em',
+          marginBottom: 4,
+        }}
+      >
+        Vessels ({vessels.length})
+      </div>
+      {sorted.length === 0 ? (
+        <div style={{ opacity: 0.4, padding: 4 }}>No vessels yet.</div>
+      ) : (
+        sorted.map((v) => {
+          const color = vesselColor(v.owner);
+          const isActive = selectedId === v.id;
+          return (
+            <div
+              key={v.id}
+              style={isActive ? ROW_ACTIVE : ROW_STYLE}
+              onClick={() => onSelect(isActive ? null : v.id)}
+              title={v.id}
+            >
+              <span style={DOT_STYLE(color)} />
+              <div style={{ flex: 1, minWidth: 0 }}>
+                <div
+                  style={{
+                    whiteSpace: 'nowrap',
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    fontWeight: isActive ? 700 : 400,
+                  }}
+                >
+                  {v.name}
+                </div>
+                <div style={{ opacity: 0.6, fontSize: 10 }}>
+                  {v.owner ?? '—'} · {v.situation.toLowerCase()} · {v.referenceBodyId}
+                </div>
+              </div>
+            </div>
+          );
+        })
+      )}
+    </div>
+  );
+}

apps/live-map/src/scene/Scene.tsx

@@ -0,0 +1,295 @@
+/**
+ * Scene — the 3D Three.js rendering of the universe.
+ *
+ *  - Builds body meshes, orbit lines, vessel markers
+ *  - Adds atmospheric glow on planets
+ *  - Uses CameraController for log-scale distance, mouse zoom,
+ *    drag-to-rotate, click-to-track via raycasting
+ */
+import { useEffect, useRef } from 'react';
+import * as THREE from 'three';
+import { sampleOrbit } from '@kerbal-rt/orbital-math';
+import type { UniverseSnapshot } from '@kerbal-rt/shared-types';
+import { bodyColor, vesselColor } from './color.js';
+import { bodyPositionAt, vesselPositionAt } from './layout.js';
+import { CameraController } from './camera.js';
+import { createGlow } from './glow.js';
+
+export interface SceneProps {
+  snapshot: UniverseSnapshot;
+  ut: number;
+  followId: string | null;
+  showPlanetOrbits: boolean;
+  showMoonOrbits: boolean;
+  showVesselOrbits: boolean;
+  onSelect: (id: string | null) => void;
+}
+
+interface SceneRefs {
+  scene: THREE.Scene;
+  camera: THREE.PerspectiveCamera;
+  renderer: THREE.WebGLRenderer;
+  bodyMeshes: Map<string, THREE.Mesh>;
+  vesselMeshes: Map<string, THREE.Mesh>;
+  orbitLines: Map<string, THREE.Line>;
+  controller: CameraController;
+  raf: number;
+}
+
+const ORBIT_OPACITY: Record<string, number> = {
+  planet: 0.5,
+  moon: 0.4,
+  vessel: 0.6,
+};
+
+export function Scene(props: SceneProps) {
+  const { snapshot, ut, followId, showPlanetOrbits, showMoonOrbits, showVesselOrbits, onSelect } =
+    props;
+  const mountRef = useRef<HTMLDivElement>(null);
+  const refsRef = useRef<SceneRefs | null>(null);
+  // Latest-snapshot / ut / followId refs so the camera controller
+  // always sees the current values without needing to be recreated.
+  const stateRef = useRef({ snapshot, ut, followId, onSelect });
+  stateRef.current = { snapshot, ut, followId, onSelect };
+
+  // One-time scene setup
+  useEffect(() => {
+    const mount = mountRef.current;
+    if (!mount) return;
+    const refs = createScene(mount, stateRef);
+    refsRef.current = refs;
+
+    const onResize = () => {
+      const r = refsRef.current;
+      if (!r) return;
+      const w = mount.clientWidth;
+      const h = mount.clientHeight;
+      r.camera.aspect = w / h;
+      r.camera.updateProjectionMatrix();
+      r.renderer.setSize(w, h);
+    };
+    window.addEventListener('resize', onResize);
+
+    return () => {
+      window.removeEventListener('resize', onResize);
+      cancelAnimationFrame(refs.raf);
+      refs.controller.dispose();
+      refs.renderer.dispose();
+      if (mount.contains(refs.renderer.domElement)) {
+        mount.removeChild(refs.renderer.domElement);
+      }
+    };
+  }, []);
+
+  // Rebuild meshes when bodies/vessels set changes
+  useEffect(() => {
+    const refs = refsRef.current;
+    if (!refs) return;
+    rebuildMeshes(refs, snapshot);
+  }, [snapshot.bodies, snapshot.vessels, snapshot]);
+
+  // Toggle orbit visibility
+  useEffect(() => {
+    const refs = refsRef.current;
+    if (!refs) return;
+    for (const [id, line] of refs.orbitLines.entries()) {
+      const isPlanet = snapshot.bodies.find((b) => b.id === id && b.kind === 'planet');
+      const isMoon = snapshot.bodies.find((b) => b.id === id && b.kind === 'moon');
+      if (isPlanet) line.visible = showPlanetOrbits;
+      else if (isMoon) line.visible = showMoonOrbits;
+      else line.visible = showVesselOrbits;
+    }
+  }, [showPlanetOrbits, showMoonOrbits, showVesselOrbits, snapshot.bodies]);
+
+  // Per-frame
+  useEffect(() => {
+    const refs = refsRef.current;
+    if (!refs) return;
+
+    let lastUt = Number.NEGATIVE_INFINITY;
+    const render = () => {
+      const cur = stateRef.current;
+      if (cur.ut !== lastUt) {
+        lastUt = cur.ut;
+        positionMeshes(refs, cur.snapshot, cur.ut);
+      }
+      refs.controller.update();
+      refs.renderer.render(refs.scene, refs.camera);
+      refs.raf = requestAnimationFrame(render);
+    };
+    refs.raf = requestAnimationFrame(render);
+    return () => cancelAnimationFrame(refs.raf);
+  }, []);
+
+  return <div ref={mountRef} style={{ width: '100%', height: '100%', cursor: 'grab' }} />;
+}
+
+// ─── Three.js setup helpers ────────────────────────────────────────────────
+
+function createScene(
+  mount: HTMLDivElement,
+  stateRef: React.MutableRefObject<{
+    snapshot: UniverseSnapshot;
+    ut: number;
+    followId: string | null;
+    onSelect: (id: string | null) => void;
+  }>,
+): SceneRefs {
+  const width = mount.clientWidth;
+  const height = mount.clientHeight;
+
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color(0x000005);
+
+  const camera = new THREE.PerspectiveCamera(60, width / height, 1e6, 1e12);
+  camera.position.set(0, 5e9, 1.5e10);
+  camera.lookAt(0, 0, 0);
+
+  const renderer = new THREE.WebGLRenderer({ antialias: true });
+  renderer.setSize(width, height);
+  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+  mount.appendChild(renderer.domElement);
+
+  scene.add(new THREE.AmbientLight(0x404040, 0.4));
+  scene.add(new THREE.PointLight(0xffffff, 2, 0, 0));
+
+  const controller = new CameraController({
+    camera,
+    domElement: mount,
+    getSnapshot: () => stateRef.current.snapshot,
+    getUt: () => stateRef.current.ut,
+    getFollowId: () => stateRef.current.followId,
+    onSelect: (id) => stateRef.current.onSelect(id),
+  });
+
+  return {
+    scene,
+    camera,
+    renderer,
+    bodyMeshes: new Map(),
+    vesselMeshes: new Map(),
+    orbitLines: new Map(),
+    controller,
+    raf: 0,
+  };
+}
+
+function rebuildMeshes(refs: SceneRefs, snap: UniverseSnapshot): void {
+  for (const mesh of refs.bodyMeshes.values()) {
+    refs.scene.remove(mesh);
+    mesh.geometry.dispose();
+    if (Array.isArray(mesh.material)) {
+      mesh.material.forEach((m) => m.dispose());
+    } else {
+      (mesh.material as THREE.Material).dispose();
+    }
+  }
+  for (const mesh of refs.vesselMeshes.values()) {
+    refs.scene.remove(mesh);
+    mesh.geometry.dispose();
+    (mesh.material as THREE.Material).dispose();
+  }
+  for (const line of refs.orbitLines.values()) {
+    refs.scene.remove(line);
+    line.geometry.dispose();
+    (line.material as THREE.Material).dispose();
+  }
+  refs.bodyMeshes.clear();
+  refs.vesselMeshes.clear();
+  refs.orbitLines.clear();
+
+  for (const body of snap.bodies) {
+    if (body.kind === 'star') {
+      const geo = new THREE.SphereGeometry(Math.max(body.radius, 1e8), 32, 16);
+      const mat = new THREE.MeshBasicMaterial({ color: bodyColor(body.id) });
+      const mesh = new THREE.Mesh(geo, mat);
+      mesh.userData = { id: body.id };
+      refs.scene.add(mesh);
+      refs.bodyMeshes.set(body.id, mesh);
+      continue;
+    }
+    if (body.parentId === null) continue;
+
+    const displayRadius = Math.max(body.radius, 1e6);
+    const geo = new THREE.SphereGeometry(displayRadius, 32, 16);
+    const mat = new THREE.MeshPhongMaterial({
+      color: bodyColor(body.id),
+      emissive: 0x111111,
+    });
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.userData = { id: body.id };
+    refs.scene.add(mesh);
+    refs.bodyMeshes.set(body.id, mesh);
+
+    // Atmospheric glow for planets/moons (skip very small bodies)
+    if (body.kind === 'planet' || (body.kind === 'moon' && body.radius > 100_000)) {
+      const glow = createGlow(body.radius, bodyColor(body.id), 0.35, 1.35);
+      mesh.add(glow); // attach as child so it follows position
+    }
+
+    // Orbit line
+    const points = sampleOrbit(body.orbit, body.gravitationalParameter, 256);
+    const positions = new Float32Array(points.length * 3);
+    points.forEach((p, i) => {
+      positions[i * 3] = p.x;
+      positions[i * 3 + 1] = p.y;
+      positions[i * 3 + 2] = p.z;
+    });
+    const lineGeo = new THREE.BufferGeometry();
+    lineGeo.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+    const lineMat = new THREE.LineBasicMaterial({
+      color: bodyColor(body.id),
+      opacity: ORBIT_OPACITY[body.kind] ?? 0.5,
+      transparent: true,
+    });
+    const line = new THREE.LineLoop(lineGeo, lineMat);
+    refs.scene.add(line);
+    refs.orbitLines.set(body.id, line);
+  }
+
+  for (const vessel of snap.vessels) {
+    const geo = new THREE.SphereGeometry(2e5, 12, 8);
+    const mat = new THREE.MeshBasicMaterial({ color: vesselColor(vessel.owner) });
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.userData = { id: vessel.id };
+    refs.scene.add(mesh);
+    refs.vesselMeshes.set(vessel.id, mesh);
+
+    if (vessel.referenceBodyId) {
+      const ref = snap.bodies.find((b) => b.id === vessel.referenceBodyId);
+      if (ref) {
+        const points = sampleOrbit(vessel.orbit, ref.gravitationalParameter, 128);
+        const positions = new Float32Array(points.length * 3);
+        points.forEach((p, i) => {
+          positions[i * 3] = p.x;
+          positions[i * 3 + 1] = p.y;
+          positions[i * 3 + 2] = p.z;
+        });
+        const lineGeo = new THREE.BufferGeometry();
+        lineGeo.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+        const lineMat = new THREE.LineBasicMaterial({
+          color: vesselColor(vessel.owner),
+          opacity: 0.5,
+          transparent: true,
+        });
+        const line = new THREE.LineLoop(lineGeo, lineMat);
+        refs.scene.add(line);
+        refs.orbitLines.set(vessel.id, line);
+      }
+    }
+  }
+}
+
+function positionMeshes(refs: SceneRefs, snap: UniverseSnapshot, ut: number): void {
+  for (const body of snap.bodies) {
+    if (body.kind === 'star' || body.parentId === null) continue;
+    const pos = bodyPositionAt(snap.bodies, body.id, ut);
+    const mesh = refs.bodyMeshes.get(body.id);
+    if (mesh) mesh.position.set(pos.x, pos.y, pos.z);
+  }
+  for (const vessel of snap.vessels) {
+    const pos = vesselPositionAt(snap.bodies, vessel, ut);
+    const mesh = refs.vesselMeshes.get(vessel.id);
+    if (mesh) mesh.position.set(pos.x, pos.y, pos.z);
+  }
+}

apps/live-map/src/scene/camera.ts

@@ -0,0 +1,224 @@
+/**
+ * Camera controller — log-scale distance, mouse wheel zoom,
+ * drag-to-rotate, click-to-track via raycasting.
+ *
+ * Three modes:
+ *   - 'free'   : user-controlled, no target
+ *   - 'follow' : tracks a vessel/body (smooth lerp to position)
+ *
+ * Log-scale: the user operates in "zoom levels" z ∈ [-3, 12]. We
+ * map z → camera distance via d = exp(z) * 1e8 m. This gives a smooth
+ * range from ~50 Mm to ~1 Tm, covering Kerbin (13.6 Gm) to Jool (68.8 Gm)
+ * with reasonable framing.
+ */
+import * as THREE from 'three';
+import type { UniverseSnapshot, CelestialBody, Vessel } from '@kerbal-rt/shared-types';
+import { bodyPositionAt, vesselPositionAt } from './layout.js';
+import { inverseLogScale } from './layout.js';
+
+export interface CameraControllerOptions {
+  camera: THREE.PerspectiveCamera;
+  domElement: HTMLElement;
+  getSnapshot: () => UniverseSnapshot;
+  getUt: () => number;
+  getFollowId: () => string | null;
+  /** Notify host when a vessel/body is clicked in the scene. */
+  onSelect: (id: string | null) => void;
+}
+
+export class CameraController {
+  private opts: CameraControllerOptions;
+  /** Camera "zoom level" — log-scale distance from origin/target. */
+  private zoomLevel = inverseLogScale(1.5e10);
+  /** Spherical coords around the current target. */
+  private azimuth = 0;
+  private elevation = 0.3;
+  private target = new THREE.Vector3(0, 0, 0);
+  /** "free" or "follow" */
+  private follow: boolean;
+  /** Last computed distance (for follow lerp). */
+  private desiredDistance = 1.5e10;
+
+  // Mouse state
+  private dragging = false;
+  private lastX = 0;
+  private lastY = 0;
+  private pointerDownPos: { x: number; y: number } | null = null;
+
+  constructor(opts: CameraControllerOptions) {
+    this.opts = opts;
+    this.follow = opts.getFollowId() !== null;
+
+    const dom = opts.domElement;
+    dom.style.touchAction = 'none';
+
+    dom.addEventListener('mousedown', this.onMouseDown);
+    dom.addEventListener('mousemove', this.onMouseMove);
+    window.addEventListener('mouseup', this.onMouseUp);
+    dom.addEventListener('wheel', this.onWheel, { passive: false });
+    dom.addEventListener('click', this.onClick);
+  }
+
+  dispose(): void {
+    const dom = this.opts.domElement;
+    dom.removeEventListener('mousedown', this.onMouseDown);
+    dom.removeEventListener('mousemove', this.onMouseMove);
+    window.removeEventListener('mouseup', this.onMouseUp);
+    dom.removeEventListener('wheel', this.onWheel);
+    dom.removeEventListener('click', this.onClick);
+  }
+
+  /** Call once per frame to keep the camera in sync. */
+  update(): void {
+    const id = this.opts.getFollowId();
+    const wantFollow = id !== null;
+    if (wantFollow !== this.follow) {
+      this.follow = wantFollow;
+    }
+
+    if (this.follow && id) {
+      const pos = this.resolveTargetPosition(id);
+      if (pos) {
+        this.target.lerp(new THREE.Vector3(pos.x, pos.y, pos.z), 0.1);
+        // Zoom level is preserved (user zoom still works)
+        this.desiredDistance = this.distanceForZoom();
+      }
+    } else {
+      // Free mode: keep current target, just orbit around it
+      this.desiredDistance = this.distanceForZoom();
+    }
+
+    // Position the camera at (target + offset) where offset is
+    // determined by spherical coords + distance.
+    const sinE = Math.sin(this.elevation);
+    const cosE = Math.cos(this.elevation);
+    const sinA = Math.sin(this.azimuth);
+    const cosA = Math.cos(this.azimuth);
+    const offset = new THREE.Vector3(
+      this.desiredDistance * cosE * sinA,
+      this.desiredDistance * sinE,
+      this.desiredDistance * cosE * cosA,
+    );
+    const desiredPos = this.target.clone().add(offset);
+    this.opts.camera.position.lerp(desiredPos, 0.1);
+    this.opts.camera.lookAt(this.target);
+  }
+
+  /** Expose current target + distance for tests / external code. */
+  getState(): { target: THREE.Vector3; distance: number; zoomLevel: number } {
+    return {
+      target: this.target.clone(),
+      distance: this.desiredDistance,
+      zoomLevel: this.zoomLevel,
+    };
+  }
+
+  // ── helpers ──────────────────────────────────────────────────────────
+
+  private distanceForZoom(): number {
+    return Math.exp(this.zoomLevel) * 1e8;
+  }
+
+  private resolveTargetPosition(id: string): { x: number; y: number; z: number } | null {
+    const snap = this.opts.getSnapshot();
+    const ut = this.opts.getUt();
+    const vessel = snap.vessels.find((v: Vessel) => v.id === id);
+    if (vessel) return vesselPositionAt(snap.bodies, vessel, ut);
+    const body = snap.bodies.find((b: CelestialBody) => b.id === id);
+    if (body) return bodyPositionAt(snap.bodies, id, ut);
+    return null;
+  }
+
+  // ── event handlers ──────────────────────────────────────────────────
+
+  private onMouseDown = (e: MouseEvent): void => {
+    if (e.button !== 0) return;
+    this.dragging = true;
+    this.lastX = e.clientX;
+    this.lastY = e.clientY;
+    this.pointerDownPos = { x: e.clientX, y: e.clientY };
+  };
+
+  private onMouseMove = (e: MouseEvent): void => {
+    if (!this.dragging) return;
+    const dx = e.clientX - this.lastX;
+    const dy = e.clientY - this.lastY;
+    this.lastX = e.clientX;
+    this.lastY = e.clientY;
+    // Sensitivity scaled to viewport
+    const sens = 0.005;
+    this.azimuth -= dx * sens;
+    this.elevation += dy * sens;
+    // Clamp elevation to avoid gimbal flip
+    const HALF_PI = Math.PI / 2 - 0.05;
+    if (this.elevation > HALF_PI) this.elevation = HALF_PI;
+    if (this.elevation < -HALF_PI) this.elevation = -HALF_PI;
+  };
+
+  private onMouseUp = (): void => {
+    this.dragging = false;
+  };
+
+  private onWheel = (e: WheelEvent): void => {
+    e.preventDefault();
+    // Positive deltaY = scroll down = zoom out (increase distance)
+    const delta = e.deltaY * 0.001;
+    this.zoomLevel = Math.max(-3, Math.min(12, this.zoomLevel + delta));
+  };
+
+  private onClick = (e: MouseEvent): void => {
+    // Only treat as a click if the pointer barely moved (not a drag)
+    if (!this.pointerDownPos) return;
+    const dx = e.clientX - this.pointerDownPos.x;
+    const dy = e.clientY - this.pointerDownPos.y;
+    if (Math.hypot(dx, dy) > 5) {
+      this.pointerDownPos = null;
+      return;
+    }
+    this.pointerDownPos = null;
+
+    // Raycast against body and vessel meshes
+    const dom = this.opts.domElement;
+    const rect = dom.getBoundingClientRect();
+    const ndc = new THREE.Vector2(
+      ((e.clientX - rect.left) / rect.width) * 2 - 1,
+      -((e.clientY - rect.top) / rect.height) * 2 + 1,
+    );
+    const raycaster = new THREE.Raycaster();
+    raycaster.setFromCamera(ndc, this.opts.camera);
+
+    // Build a list of {mesh, id} from the scene
+    const hits: { id: string; dist: number }[] = [];
+    const snap = this.opts.getSnapshot();
+    raycaster.intersectObjects(this.opts.camera.parent?.children ?? [], true).forEach((hit) => {
+      const id = (hit.object.userData as { id?: string }).id;
+      if (id) hits.push({ id, dist: hit.distance });
+    });
+    if (hits.length === 0) {
+      this.opts.onSelect(null);
+      return;
+    }
+    hits.sort((a, b) => a.dist - b.dist);
+    // Toggle: if clicking the same selected object, deselect
+    const current = this.opts.getFollowId();
+    if (current && hits[0] && hits[0].id === current) {
+      this.opts.onSelect(null);
+    } else {
+      this.opts.onSelect(hits[0]?.id ?? null);
+    }
+    // Snap zoom to a reasonable level for the new target
+    if (hits[0]) {
+      const pos = this.resolveTargetPosition(hits[0].id);
+      if (pos) {
+        this.target.set(pos.x, pos.y, pos.z);
+        // Set zoom based on body size (bodies need more zoom out)
+        const body = snap.bodies.find((b: CelestialBody) => b.id === hits[0]?.id);
+        if (body) {
+          this.zoomLevel = inverseLogScale(body.radius * 10);
+        } else {
+          this.zoomLevel = inverseLogScale(5e6);
+        }
+      }
+    }
+  };
+}

apps/live-map/src/scene/color.ts

@@ -0,0 +1,40 @@
+/**
+ * Color-coding for celestial bodies. Identical to the catalog in
+ * apps/tools/mock-telemetry/src/catalog.ts so the mock and the
+ * renderer agree.
+ *
+ * Returns a Three.js-friendly 0xRRGGBB number.
+ */
+export function bodyColor(id: string): number {
+  const map: Record<string, number> = {
+    kerbol: 0xffcc33,
+    kerbin: 0x3a7d8c,
+    mun: 0xaaaaaa,
+    minmus: 0x997a66,
+    duna: 0xc46030,
+    ike: 0x776655,
+    eve: 0x6b4ea0,
+    gilly: 0x665544,
+    jool: 0xa55a2a,
+    laythe: 0x4a6da0,
+    vall: 0x665544,
+    tylo: 0x997a66,
+    bop: 0x444444,
+    pol: 0x333333,
+    moho: 0x664433,
+    dres: 0x665544,
+    eeloo: 0xeeeeff,
+  };
+  return map[id] ?? 0xffffff;
+}
+
+/**
+ * Color-coding for vessels by owner agency.
+ */
+export function vesselColor(owner: string | null): number {
+  const map: Record<string, number> = {
+    KASA: 0x44aaff, // blue
+    SPES: 0xff6644, // orange
+  };
+  return map[owner ?? ''] ?? 0xcccccc;
+}

apps/live-map/src/scene/glow.ts

@@ -0,0 +1,67 @@
+/**
+ * Atmospheric glow — a simple additive shell around a body that fades
+ * from a small radius to a larger one. Looks like a soft halo when
+ * viewed from any angle.
+ *
+ * Implementation: a slightly larger sphere with a custom shader that
+ * fades from opaque at the inner edge to transparent at the outer edge.
+ * The fade uses view-direction dot product so we always see the rim.
+ */
+import * as THREE from 'three';
+
+const VERTEX = /* glsl */ `
+  varying vec3 vNormal;
+  varying vec3 vViewDir;
+  void main() {
+    vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
+    gl_Position = projectionMatrix * mvPosition;
+    vNormal = normalize(normalMatrix * normal);
+    vViewDir = normalize(-mvPosition.xyz);
+  }
+`;
+
+const FRAGMENT = /* glsl */ `
+  uniform vec3 uColor;
+  uniform float uIntensity;
+  varying vec3 vNormal;
+  varying vec3 vViewDir;
+  void main() {
+    // Strongest at the rim (where the surface is parallel to view)
+    float rim = 1.0 - max(0.0, dot(vNormal, vViewDir));
+    rim = pow(rim, 2.5); // sharpen the falloff
+    gl_FragColor = vec4(uColor * rim * uIntensity, rim);
+  }
+`;
+
+/**
+ * Create a glow shell mesh for a body. Add it to the scene as a child
+ * of the body so it follows the body's transform.
+ *
+ * @param bodyRadius  the actual radius of the body
+ * @param color       the glow color
+ * @param intensity   brightness multiplier (0..1, default 0.4)
+ * @param scaleFactor how much bigger than the body to make the shell
+ */
+export function createGlow(
+  bodyRadius: number,
+  color: number,
+  intensity = 0.4,
+  scaleFactor = 1.4,
+): THREE.Mesh {
+  const inner = Math.max(bodyRadius, 1e6);
+  const outer = inner * scaleFactor;
+  const geo = new THREE.SphereGeometry(outer, 32, 16);
+  const mat = new THREE.ShaderMaterial({
+    uniforms: {
+      uColor: { value: new THREE.Color(color) },
+      uIntensity: { value: intensity },
+    },
+    vertexShader: VERTEX,
+    fragmentShader: FRAGMENT,
+    transparent: true,
+    blending: THREE.AdditiveBlending,
+    side: THREE.BackSide, // render the back side, so the rim shows on the outside
+    depthWrite: false,
+  });
+  return new THREE.Mesh(geo, mat);
+}

apps/live-map/src/scene/layout.ts

@@ -0,0 +1,75 @@
+/**
+ * Layout helpers for the 3D scene.
+ *
+ *  - bodies are positioned in heliocentric inertial frame, in meters
+ *  - the KSP system is huge (Eeloo is ~9e10 m from Kerbol) so we
+ *    render with a logarithmic distance scale for the camera radius
+ *    to keep the inner planets visible alongside the outer ones
+ */
+import type { CelestialBody, Vessel } from '@kerbal-rt/shared-types';
+import { positionAt } from '@kerbal-rt/orbital-math';
+
+/** Find a body's gravitational parameter (μ) given its id.
+ *  Misleadingly named "findParentMu" historically; the function
+ *  returns the body's own μ, used for propagating vessels around it. */
+export function findBodyMu(bodies: CelestialBody[], id: string | null): number {
+  if (!id) return 0;
+  const body = bodies.find((b) => b.id === id);
+  return body?.gravitationalParameter ?? 0;
+}
+
+/**
+ * Position of a body in the heliocentric inertial frame, propagated
+ * to the given UT. Walks up the parent chain so the result is the
+ * true absolute position, not the parent-relative position.
+ */
+export function bodyPositionAt(
+  bodies: CelestialBody[],
+  bodyId: string,
+  ut: number,
+): { x: number; y: number; z: number } {
+  const body = bodies.find((b) => b.id === bodyId);
+  if (!body) return { x: 0, y: 0, z: 0 };
+  if (!body.parentId) return { x: 0, y: 0, z: 0 }; // system root
+  const parent = bodies.find((b) => b.id === body.parentId);
+  if (!parent) return { x: 0, y: 0, z: 0 };
+  const parentPos = bodyPositionAt(bodies, parent.id, ut);
+  const local = positionAt(body.orbit, parent.gravitationalParameter, ut);
+  return {
+    x: parentPos.x + local.x,
+    y: parentPos.y + local.y,
+    z: parentPos.z + local.z,
+  };
+}
+
+/** Position of a vessel, propagated to UT, in the heliocentric frame. */
+export function vesselPositionAt(
+  bodies: CelestialBody[],
+  vessel: Vessel,
+  ut: number,
+): { x: number; y: number; z: number } {
+  const refMu = findBodyMu(bodies, vessel.referenceBodyId);
+  const refPos = bodyPositionAt(bodies, vessel.referenceBodyId, ut);
+  const local = positionAt(vessel.orbit, refMu, ut);
+  return {
+    x: refPos.x + local.x,
+    y: refPos.y + local.y,
+    z: refPos.z + local.z,
+  };
+}
+
+/**
+ * Log-scaled camera distance. Maps a desired real distance to a
+ * Three.js camera position that keeps both inner and outer planets
+ * visible. d_real = exp(t) * 1e8 m  →  e.g. for t=4, distance=5.5e9 m.
+ */
+export function logScale(t: number): number {
+  return Math.exp(t) * 1e8;
+}
+
+export function inverseLogScale(d: number): number {
+  return Math.log(d / 1e8);
+}
+
+/** A reasonable initial camera radius that shows the inner planets. */
+export const DEFAULT_CAMERA_RADIUS = 1.5e10;

apps/live-map/src/timeFormat.ts

@@ -0,0 +1,28 @@
+/**
+ * KSP time formatting helpers — 1 KSP day = 6 hours, 1 KSP year = 426 days.
+ * Source: stock KSP config.
+ */
+
+const KSP_DAY_SECONDS = 6 * 3600;
+const KSP_YEAR_DAYS = 426;
+
+/** Format a UT value as "Y1 D001 12:34". */
+export function formatKspTime(ut: number): string {
+  const totalDays = ut / KSP_DAY_SECONDS;
+  const year = Math.floor(totalDays / KSP_YEAR_DAYS) + 1;
+  const day = (Math.floor(totalDays) % KSP_YEAR_DAYS) + 1;
+  const secondsInDay = ut % KSP_DAY_SECONDS;
+  const h = Math.floor(secondsInDay / 3600);
+  const m = Math.floor((secondsInDay % 3600) / 60);
+  return `Y${year} D${String(day).padStart(3, '0')} ${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`;
+}
+
+/** Format a duration in seconds as a human-readable string. */
+export function formatKspDuration(seconds: number): string {
+  const abs = Math.abs(seconds);
+  if (abs < 60) return `${Math.floor(abs)}s`;
+  if (abs < 3600) return `${Math.floor(abs / 60)}m`;
+  if (abs < 86400) return `${(abs / 3600).toFixed(1)}h`;
+  if (abs < KSP_YEAR_DAYS * KSP_DAY_SECONDS) return `${(abs / 86400).toFixed(1)}d`;
+  return `${(abs / (KSP_YEAR_DAYS * KSP_DAY_SECONDS)).toFixed(1)}y`;
+}

apps/live-map/tests/calculators.test.ts

@@ -0,0 +1,305 @@
+import { describe, it, expect } from 'vitest';
+import { findEclipseWindows, computeShadowFraction } from '../src/calculators/eclipse.js';
+import { findOverpasses, type Target } from '../src/calculators/overpass.js';
+import type { CelestialBody, GroundStation, Vessel } from '@kerbal-rt/shared-types';
+
+const KSP_DAY = 6 * 3600;
+
+// ─── Minimal solar system: Kerbol + Kerbin + Mun (a simple eclipse scenario)
+const kerbol: CelestialBody = {
+  id: 'kerbol',
+  name: 'Kerbol',
+  kind: 'star',
+  parentId: null,
+  radius: 261_600_000,
+  sphereOfInfluence: 1e30,
+  gravitationalParameter: 1.172e18,
+  rotationPeriod: 432_000,
+  axialTilt: 0,
+  orbit: {
+    semiMajorAxis: 0,
+    eccentricity: 0,
+    inclination: 0,
+    longitudeOfAscendingNode: 0,
+    argumentOfPeriapsis: 0,
+    meanAnomalyAtEpoch: 0,
+    epoch: 0,
+  },
+};
+
+// Kerbin in a circular orbit at 13.6e9 m
+const kerbin: CelestialBody = {
+  id: 'kerbin',
+  name: 'Kerbin',
+  kind: 'planet',
+  parentId: 'kerbol',
+  radius: 600_000,
+  sphereOfInfluence: 84_159_286,
+  gravitationalParameter: 3.5316e12,
+  rotationPeriod: 21_600,
+  axialTilt: 0,
+  orbit: {
+    semiMajorAxis: 13_599_840_256,
+    eccentricity: 0,
+    inclination: 0,
+    longitudeOfAscendingNode: 0,
+    argumentOfPeriapsis: 0,
+    meanAnomalyAtEpoch: 0,
+    epoch: 0,
+  },
+};
+
+// Mun in a circular orbit around Kerbin at 12e6 m
+const mun: CelestialBody = {
+  id: 'mun',
+  name: 'Mun',
+  kind: 'moon',
+  parentId: 'kerbin',
+  radius: 200_000,
+  sphereOfInfluence: 2_429_559,
+  gravitationalParameter: 6.514e10,
+  rotationPeriod: 138_984,
+  axialTilt: 0,
+  orbit: {
+    semiMajorAxis: 12_000_000,
+    eccentricity: 0,
+    inclination: 0,
+    longitudeOfAscendingNode: 0,
+    argumentOfPeriapsis: 0,
+    meanAnomalyAtEpoch: 0, // start at (12e6, 0, 0) in kerbin frame
+    epoch: 0,
+  },
+};
+
+const systemBodies = [kerbol, kerbin, mun];
+
+describe('computeShadowFraction', () => {
+  it('returns 0 when eclipser is on the far side of the observer from the sun', () => {
+    // t=0, Mun meanAnomalyAtEpoch=0 → Mun at (+12e6, 0, 0) in kerbin frame
+    // → Mun world position (13.6e9 + 12e6, 0, 0) — BEHIND Kerbin from the sun.
+    // Sun is at (-x) from Kerbin; Mun is at (+x). No eclipse.
+    const munBehind: CelestialBody = {
+      ...mun,
+      orbit: { ...mun.orbit, meanAnomalyAtEpoch: 0 },
+    };
+    const sys = [kerbol, kerbin, munBehind];
+    const f = computeShadowFraction(sys, 'kerbin', 'mun', 0);
+    expect(f).toBe(0);
+  });
+
+  it('returns high fraction when occluder sits between observer and sun', () => {
+    // Set up Mun directly between Kerbin and Kerbol (anti-aligned).
+    // Mun's meanAnomalyAtEpoch = π → Mun at (-12e6, 0, 0) in kerbin frame,
+    // i.e. world position (13.6e9 - 12e6, 0, 0). Sun at (0,0,0).
+    // Kerbin is at (13.6e9, 0, 0). So Mun is between them.
+    const munAntialigned: CelestialBody = {
+      ...mun,
+      orbit: { ...mun.orbit, meanAnomalyAtEpoch: Math.PI },
+    };
+    const sys = [kerbol, kerbin, munAntialigned];
+    const f = computeShadowFraction(sys, 'kerbin', 'mun', 0);
+    // Should be ≥ 0.5 (Mun is ~0.6 Mm radius, observer is 12 Mm from it;
+    // angular size is small but the center of Mun is exactly on the
+    // sun-line so the umbra is total)
+    expect(f).toBeGreaterThan(0.5);
+  });
+
+  it('returns 0 for self-eclipse (observer == eclipser)', () => {
+    // findEclipseWindows early-returns on this, but computeShadowFraction
+    // would compute a 1.0 trivially. Either is fine; just verify the API
+    // returns a number.
+    const f = computeShadowFraction(systemBodies, 'kerbin', 'kerbin', 0);
+    expect(typeof f).toBe('number');
+  });
+
+  it('returns 1 when occluder is exactly on the sun-line (centered eclipse)', () => {
+    // Mun anti-aligned → directly between Kerbin and Kerbol at t=0
+    const munAntialigned: CelestialBody = {
+      ...mun,
+      orbit: { ...mun.orbit, meanAnomalyAtEpoch: Math.PI },
+    };
+    const sys = [kerbol, kerbin, munAntialigned];
+    const f = computeShadowFraction(sys, 'kerbin', 'mun', 0);
+    expect(f).toBeGreaterThan(0.99);
+  });
+
+  it('returns a value in [0, 1]', () => {
+    const f = computeShadowFraction(systemBodies, 'kerbin', 'mun', 0);
+    expect(f).toBeGreaterThanOrEqual(0);
+    expect(f).toBeLessThanOrEqual(1);
+  });
+});
+
+describe('findEclipseWindows', () => {
+  it('returns empty array for self-eclipse', () => {
+    const w = findEclipseWindows(systemBodies, {
+      observerId: 'kerbin',
+      eclipserId: 'kerbin',
+      startUt: 0,
+    });
+    expect(w).toEqual([]);
+  });
+
+  it('returns empty array for unknown bodies', () => {
+    const w = findEclipseWindows(systemBodies, {
+      observerId: 'kerbin',
+      eclipserId: 'unknown',
+      startUt: 0,
+    });
+    expect(w).toEqual([]);
+  });
+
+  it('finds an eclipse window when Mun passes between Kerbin and Kerbol', () => {
+    // Set up a system where Mun is currently in front of the sun from Kerbin's
+    // perspective. The Mun orbits Kerbin in ~6.8 days, so we should find
+    // an eclipse within a few days of t=0.
+    const sys = [
+      kerbol,
+      kerbin,
+      { ...mun, orbit: { ...mun.orbit, meanAnomalyAtEpoch: Math.PI } }, // start anti-aligned
+    ];
+    const windows = findEclipseWindows(sys, {
+      observerId: 'kerbin',
+      eclipserId: 'mun',
+      startUt: 0,
+      count: 1,
+      stepSec: 300, // 5 KSP minutes for the coarse scan
+    });
+    expect(windows.length).toBeGreaterThan(0);
+    if (windows[0]) {
+      expect(windows[0].utStart).toBeGreaterThanOrEqual(0);
+      expect(windows[0].utEnd).toBeGreaterThan(windows[0].utStart);
+      expect(windows[0].utPeak).toBeGreaterThanOrEqual(windows[0].utStart);
+      expect(windows[0].utPeak).toBeLessThanOrEqual(windows[0].utEnd);
+      expect(windows[0].maxFraction).toBeGreaterThan(0);
+    }
+  });
+});
+
+// ─── Overpass tests ───────────────────────────────────────────────────────
+
+const vesselA: Vessel = {
+  id: 'v-a',
+  name: 'Vessel A',
+  type: 'Probe',
+  owner: 'KASA',
+  situation: 'ORBITING',
+  status: 'ACTIVE',
+  orbit: {
+    semiMajorAxis: 7_000_000,
+    eccentricity: 0,
+    inclination: 0,
+    longitudeOfAscendingNode: 0,
+    argumentOfPeriapsis: 0,
+    meanAnomalyAtEpoch: 0,
+    epoch: 0,
+  },
+  referenceBodyId: 'kerbin',
+  createdAt: '2026-01-01T00:00:00Z',
+  retiredAt: null,
+};
+
+const vesselB: Vessel = {
+  id: 'v-b',
+  name: 'Vessel B',
+  type: 'Probe',
+  owner: 'SPES',
+  situation: 'ORBITING',
+  status: 'ACTIVE',
+  orbit: {
+    semiMajorAxis: 7_000_000,
+    eccentricity: 0,
+    inclination: 0,
+    longitudeOfAscendingNode: 0,
+    argumentOfPeriapsis: 0,
+    meanAnomalyAtEpoch: Math.PI, // opposite side
+    epoch: 0,
+  },
+  referenceBodyId: 'kerbin',
+  createdAt: '2026-01-01T00:00:00Z',
+  retiredAt: null,
+};
+
+const station: GroundStation = {
+  id: 'montana',
+  name: 'Montana DSN',
+  bodyId: 'kerbin',
+  lat: 47.0,
+  lon: -110.0,
+  alt: 1200,
+};
+
+describe('findOverpasses', () => {
+  it('finds a close approach between two vessels in different orbits', () => {
+    // Two vessels in different circular orbits around Kerbin. They will
+    // occasionally align and approach each other. Use a small step to
+    // catch the close approach.
+    const vesselBDifferent: Vessel = {
+      ...vesselB,
+      orbit: { ...vesselB.orbit, semiMajorAxis: 7_500_000 }, // different SMA
+    };
+    const passes = findOverpasses({
+      observer: vesselA,
+      target: { kind: 'vessel', id: 'v-b', name: 'Vessel B' },
+      bodies: systemBodies,
+      vessels: [vesselA, vesselBDifferent],
+      groundStations: [],
+      startUt: 0,
+      count: 1,
+      stepSec: 60, // 1 min coarse scan
+      distanceThreshold: 5_000_000, // 5000 km
+      maxSearchTime: 426 * 6 * 3600, // 1 KSP year
+    });
+    expect(passes.length).toBeGreaterThan(0);
+    if (passes[0]) {
+      expect(passes[0].minDistance).toBeLessThan(5_000_000);
+      expect(passes[0].utPeak).toBeGreaterThan(0);
+    }
+  });
+
+  it('handles body target (observer passes near a body)', () => {
+    // Vessel A is in LKO around Kerbin, so distance to Mun varies a lot.
+    // We should find at least one "close" approach (within 100 Mm).
+    const passes = findOverpasses({
+      observer: vesselA,
+      target: { kind: 'body', id: 'mun', name: 'Mun' },
+      bodies: systemBodies,
+      vessels: [vesselA],
+      groundStations: [],
+      startUt: 0,
+      count: 1,
+      stepSec: 3600,
+      distanceThreshold: 100_000_000, // 100 Mm
+    });
+    // Just verify the API works; we can't easily assert on the value
+    expect(Array.isArray(passes)).toBe(true);
+  });
+
+  it('handles ground station target', () => {
+    const passes = findOverpasses({
+      observer: vesselA,
+      target: { kind: 'station', id: 'montana', name: 'Montana' },
+      bodies: systemBodies,
+      vessels: [vesselA],
+      groundStations: [station],
+      startUt: 0,
+      count: 1,
+      stepSec: 60,
+      distanceThreshold: 50_000_000, // 50 Mm
+    });
+    expect(Array.isArray(passes)).toBe(true);
+  });
+
+  it('returns empty when target is unknown', () => {
+    const target: Target = { kind: 'vessel', id: 'unknown', name: '?' };
+    const passes = findOverpasses({
+      observer: vesselA,
+      target,
+      bodies: systemBodies,
+      vessels: [vesselA],
+      groundStations: [],
+      startUt: 0,
+    });
+    expect(passes).toEqual([]);
+  });
+});

apps/live-map/tests/camera.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { inverseLogScale, logScale } from '../src/scene/layout.js';
+
+describe('camera log-scale', () => {
+  it('inverseLogScale undoes logScale', () => {
+    for (const t of [-3, 0, 4, 8, 12]) {
+      expect(inverseLogScale(logScale(t))).toBeCloseTo(t, 6);
+    }
+  });
+
+  it('produces distances spanning the KSP system', () => {
+    // t = 0: 1e8 m = 100 Mm (close zoom)
+    expect(logScale(0)).toBeCloseTo(1e8, -3);
+    // t = 4: ~5.5e9 m (Kerbin at 13.6 Gm is just outside)
+    expect(logScale(4)).toBeGreaterThan(1e9);
+    // t = 10: ~22e12 m (Eeloo at 90 Gm is well inside)
+    expect(logScale(10)).toBeGreaterThan(1e10);
+    // t = 12: ~1.6e13 m (max zoom)
+    expect(logScale(12)).toBeGreaterThan(1e12);
+  });
+});
+
+describe('spherical math (used by camera)', () => {
+  // The camera controller uses spherical coords. Test the
+  // cartesian conversion (extracted for testability).
+  function sphericalToCartesian(distance: number, az: number, el: number) {
+    const sinE = Math.sin(el);
+    const cosE = Math.cos(el);
+    const sinA = Math.sin(az);
+    const cosA = Math.cos(az);
+    return {
+      x: distance * cosE * sinA,
+      y: distance * sinE,
+      z: distance * cosE * cosA,
+    };
+  }
+
+  it('produces a point on the sphere of given radius', () => {
+    for (const az of [0, 1, 2.5, 4.7]) {
+      for (const el of [-0.5, 0, 0.7]) {
+        const p = sphericalToCartesian(1e10, az, el);
+        const d = Math.hypot(p.x, p.y, p.z);
+        expect(d).toBeCloseTo(1e10, 4);
+      }
+    }
+  });
+
+  it('azimuth=0, elevation=0 produces +Z vector', () => {
+    const p = sphericalToCartesian(100, 0, 0);
+    expect(p.z).toBeCloseTo(100, 6);
+    expect(p.x).toBeCloseTo(0, 6);
+    expect(p.y).toBeCloseTo(0, 6);
+  });
+
+  it('azimuth=π/2, elevation=0 produces +X vector', () => {
+    const p = sphericalToCartesian(100, Math.PI / 2, 0);
+    expect(p.x).toBeCloseTo(100, 6);
+    expect(p.z).toBeCloseTo(0, 6);
+    expect(p.y).toBeCloseTo(0, 6);
+  });
+
+  it('elevation=π/2 produces +Y vector', () => {
+    const p = sphericalToCartesian(100, 0, Math.PI / 2);
+    expect(p.y).toBeCloseTo(100, 6);
+    expect(p.x).toBeCloseTo(0, 6);
+    expect(p.z).toBeCloseTo(0, 6);
+  });
+});

apps/live-map/tests/scene.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from 'vitest';
+import {
+  bodyPositionAt,
+  vesselPositionAt,
+  findBodyMu,
+  logScale,
+  inverseLogScale,
+} from '../src/scene/layout.js';
+import type { CelestialBody, Vessel } from '@kerbal-rt/shared-types';
+
+const kerbol: CelestialBody = {
+  id: 'kerbol',
+  name: 'Kerbol',
+  kind: 'star',
+  parentId: null,
+  radius: 261_600_000,
+  sphereOfInfluence: 1e30,
+  gravitationalParameter: 1.172e18,
+  rotationPeriod: 432_000,
+  axialTilt: 0,
+  orbit: {
+    semiMajorAxis: 0,
+    eccentricity: 0,
+    inclination: 0,
+    longitudeOfAscendingNode: 0,
+    argumentOfPeriapsis: 0,
+    meanAnomalyAtEpoch: 0,
+    epoch: 0,
+  },
+};
+
+const kerbin: CelestialBody = {
+  id: 'kerbin',
+  name: 'Kerbin',
+  kind: 'planet',
+  parentId: 'kerbol',
+  radius: 600_000,
+  sphereOfInfluence: 84_159_286,
+  gravitationalParameter: 3.5316e12,
+  rotationPeriod: 21_600,
+  axialTilt: 0,
+  orbit: {
+    semiMajorAxis: 13_599_840_256,
+    eccentricity: 0, // circular for predictable test math
+    inclination: 0,
+    longitudeOfAscendingNode: 0,
+    argumentOfPeriapsis: 0,
+    meanAnomalyAtEpoch: 0,
+    epoch: 0,
+  },
+};
+
+const mun: CelestialBody = {
+  id: 'mun',
+  name: 'Mun',
+  kind: 'moon',
+  parentId: 'kerbin',
+  radius: 200_000,
+  sphereOfInfluence: 2_429_559,
+  gravitationalParameter: 6.514e10,
+  rotationPeriod: 138_984,
+  axialTilt: 0,
+  orbit: {
+    semiMajorAxis: 12_000_000,
+    eccentricity: 0,
+    inclination: 0,
+    longitudeOfAscendingNode: 0,
+    argumentOfPeriapsis: 0,
+    meanAnomalyAtEpoch: 0,
+    epoch: 0,
+  },
+};
+
+const bodies: CelestialBody[] = [kerbol, kerbin, mun];
+
+describe('bodyPositionAt', () => {
+  it('returns origin for the star', () => {
+    const p = bodyPositionAt(bodies, 'kerbol', 100);
+    expect(p.x).toBe(0);
+    expect(p.y).toBe(0);
+    expect(p.z).toBe(0);
+  });
+
+  it('returns a non-zero position for a planet at t > 0', () => {
+    const p = bodyPositionAt(bodies, 'kerbin', 1_000_000);
+    const dist = Math.hypot(p.x, p.y, p.z);
+    // SMA is 13.6 billion meters, so position is on that order
+    expect(dist).toBeGreaterThan(1e10);
+    expect(dist).toBeLessThan(2e10);
+  });
+
+  it('returns origin for a body not in the catalog', () => {
+    const p = bodyPositionAt(bodies, 'unknown', 1);
+    expect(p).toEqual({ x: 0, y: 0, z: 0 });
+  });
+
+  it('is periodic (returns near the same position after one full orbit)', () => {
+    // Kerbin orbits Kerbol, so the period is computed with kerbol's μ
+    const p1 = bodyPositionAt(bodies, 'kerbin', 0);
+    const period =
+      (2 * Math.PI) / Math.sqrt(kerbol.gravitationalParameter / Math.pow(13_599_840_256, 3));
+    const p2 = bodyPositionAt(bodies, 'kerbin', period);
+    expect(p1.x).toBeCloseTo(p2.x, -2);
+    expect(p1.y).toBeCloseTo(p2.y, -2);
+  });
+});
+
+describe('vesselPositionAt', () => {
+  const vessel: Vessel = {
+    id: 'v1',
+    name: 'Test',
+    type: 'Probe',
+    owner: 'KASA',
+    situation: 'ORBITING',
+    status: 'ACTIVE',
+    orbit: {
+      semiMajorAxis: 7_000_000,
+      eccentricity: 0,
+      inclination: 0,
+      longitudeOfAscendingNode: 0,
+      argumentOfPeriapsis: 0,
+      meanAnomalyAtEpoch: 0,
+      epoch: 0,
+    },
+    referenceBodyId: 'kerbin',
+    createdAt: '2026-01-01T00:00:00Z',
+    retiredAt: null,
+  };
+
+  it('returns the kerbin-centered position when reference body is kerbin', () => {
+    // At t=0, vessel is at (7e6, 0, 0) in kerbin frame
+    const p = vesselPositionAt(bodies, vessel, 0);
+    // kerbin is at (sma, 0, 0) = (13.6e9, 0, 0)
+    // so vessel should be at roughly (13.6e9 + 7e6, 0, 0)
+    expect(p.x).toBeCloseTo(13_599_840_256 + 7_000_000, -2);
+    expect(p.y).toBeCloseTo(0, 2);
+  });
+});
+
+describe('findBodyMu', () => {
+  it("returns the body's own gravitational parameter", () => {
+    expect(findBodyMu(bodies, 'kerbin')).toBe(kerbin.gravitationalParameter);
+  });
+  it('returns 0 for null id', () => {
+    expect(findBodyMu(bodies, null)).toBe(0);
+  });
+  it('returns 0 for unknown id', () => {
+    expect(findBodyMu(bodies, 'nope')).toBe(0);
+  });
+});
+
+describe('logScale', () => {
+  it('is the inverse of inverseLogScale', () => {
+    for (const t of [0, 4, 8, 12]) {
+      const d = logScale(t);
+      expect(inverseLogScale(d)).toBeCloseTo(t, 6);
+    }
+  });
+  it('produces reasonable distances for camera placement', () => {
+    // t=4 → ~5.5e9 m (good for showing Kerbin at 13.6e9)
+    expect(logScale(4)).toBeGreaterThan(1e9);
+    expect(logScale(4)).toBeLessThan(1e10);
+    // t=10 → ~22e12 m (good for showing all planets)
+    expect(logScale(10)).toBeGreaterThan(1e12);
+  });
+});

apps/live-map/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    environment: 'node',
+  },
+});

packages/orbital-math/src/occultation.ts

@@ -28,10 +28,14 @@ export function shadowFraction(
   const sy = observerToSun.y / sunDist;
   const sz = observerToSun.z / sunDist;
 
-  // Project occluder center onto the sun-direction line
+  // Project occluder center onto the sun-direction line.
+  // Both `observerToSun` and `occluderToObserver` point AWAY from
+  // the observer (toward the sun / toward the occluder). When the
+  // occluder sits between observer and sun, both vectors point in
+  // roughly the same direction and `proj` is positive.
   const proj = occluderToObserver.x * sx + occluderToObserver.y * sy + occluderToObserver.z * sz;
-  if (proj >= 0) {
+  if (proj <= 0) {
-    // Occluder is behind the observer relative to the sun → no eclipse
+    // Occluder is behind the observer (opposite direction from sun) → no eclipse
     return 0;
   }
   // Perpendicular distance from occluder center to sun ray

pnpm-lock.yaml

@@ -139,6 +139,9 @@ importers:
       vite:
         specifier: ^5.4.6
         version: 5.4.21(@types/node@22.19.19)
+      vitest:
+        specifier: ^2.1.1
+        version: 2.1.9(@types/node@22.19.19)
 
   apps/tools/mock-telemetry:
     dependencies: