Merge pull request 'fix: null-safe kRPC handshake error reporting' (#5) from debug-krpc-handshake into main

Reviewed-on: #5

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';
-import { Pill, formatUtAsKspDate } from '@kerbal-rt/ui';
-import { sampleOrbit, positionAt } from '@kerbal-rt/orbital-math';
-import type { CelestialBody } from '@kerbal-rt/shared-types';
+/**
+ * App — top-level live map.
+ *
+ * Subscribes to the API WebSocket, manages the simulation time
+ * (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) ?? '';
 
-/**
- * Mock solar system so the scene has something to render before the
- * real KSP bridge is wired in (Phase 1). Drop a real snapshot in
- * via the same /api/v1/state endpoint and the same renderer will
- * work — only `useUniverse()` changes.
- */
-function useUniverse() {
-  const [bodies, setBodies] = useState<CelestialBody[]>([]);
-  const [ut, setUt] = useState(0);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    const mockBodies: CelestialBody[] = [
-      makeBody({
-        id: 'kerbol',
-        name: 'Kerbol',
-        kind: 'star',
-        radius: 261_600_000,
-        sphereOfInfluence: Infinity,
-        mu: 1.172332794e18,
-        rotationPeriod: 432_000,
-        axialTilt: 0,
-        color: '#ffcc33',
-        parent: null,
-        sma: 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,
+/** Fallback in-memory snapshot so the scene has something to render
+ *  even before the API is up. Matches the catalog used by the
+ *  mock-telemetry publisher. */
+const FALLBACK_SNAPSHOT: UniverseSnapshot = {
+  ut: 0,
+  capturedAt: new Date(0).toISOString(),
+  activeVesselId: null,
+  bodies: [
+    {
+      id: 'kerbol',
+      name: 'Kerbol',
+      kind: 'star',
+      parentId: null,
+      radius: 261_600_000,
+      sphereOfInfluence: 1e30,
+      gravitationalParameter: 1.172332794e18,
+      rotationPeriod: 432_000,
+      axialTilt: 0,
+      orbit: {
+        semiMajorAxis: 0,
+        eccentricity: 0,
+        inclination: 0,
+        longitudeOfAscendingNode: 0,
+        argumentOfPeriapsis: 0,
+        meanAnomalyAtEpoch: 0,
+        epoch: 0,
+      },
     },
-  };
-}
-
-function Scene({ bodies, ut }: { bodies: CelestialBody[]; ut: number }) {
-  const mountRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    const mount = mountRef.current;
-    if (!mount) return;
-
-    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, 0.1, 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);
-
-    // Lights
-    scene.add(new THREE.AmbientLight(0x404040, 0.4));
-    const sunLight = new THREE.PointLight(0xffffff, 2, 0, 0);
-    scene.add(sunLight);
-
-    // Build spheres + orbit lines per body
-    const meshById = new Map<string, THREE.Mesh>();
-    const orbitGroup = new THREE.Group();
-    scene.add(orbitGroup);
-
-    for (const body of bodies) {
-      if (body.sphereOfInfluence === 0 || body.sphereOfInfluence === Infinity) {
-        // Star: render but skip orbit
-        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);
-          scene.add(mesh);
-          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;
-}
+    {
+      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.05,
+        inclination: 0,
+        longitudeOfAscendingNode: 0,
+        argumentOfPeriapsis: 0,
+        meanAnomalyAtEpoch: 0.7,
+        epoch: 0,
+      },
+    },
+    {
+      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: 1.0,
+        epoch: 0,
+      },
+    },
+  ],
+  vessels: [],
+  groundStations: [],
+};
 
 export function App() {
-  const { bodies, ut, setUt, error } = useUniverse();
-  const [playing, setPlaying] = useState(true);
-  const [speed, setSpeed] = useState(60); // 1s of wall = 60s of KSP UT
+  const { snapshot, status, lastUpdate, messageCount, error } = useLiveState(API_URL);
+  const liveUt = snapshot?.ut ?? 0;
 
+  // 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
-        style={{
-          position: 'absolute',
-          top: 12,
-          left: 12,
-          padding: '0.5rem 0.75rem',
-          background: 'rgba(0,0,0,0.6)',
-          color: 'white',
-          borderRadius: 6,
-          fontFamily: 'monospace',
-          fontSize: 13,
+      <StatusPill
+        status={status}
+        lastUpdate={lastUpdate}
+        messageCount={messageCount}
+        vesselCount={vesselCount}
+        bodyCount={bodyCount}
+      />
+
+      <TimeControls
+        ut={displayUt}
+        liveUt={liveUt}
+        playing={playing}
+        speed={speed}
+        onPlayPause={() => setPlaying((p) => !p)}
+        onSpeed={(s) => {
+          setSpeed(s);
+          if (s > 0) setPlaying(true);
         }}
-      >
-        <div style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
-          <strong>Kerbal RT</strong>
-          <Pill tone={error ? 'danger' : 'success'}>
-            {error ? 'API offline' : `${bodies.length} bodies`}
-          </Pill>
+        onReverse={() => setSpeed((s) => -s)}
+        onReset={() => {
+          setDisplayUt(liveUt);
+          setPlaying(true);
+          setSpeed(1);
+          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)',
-          fontSize: 11,
+          color: 'rgba(255,255,255,0.4)',
+          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',
+  },
+});

apps/tools/ksp-bridge/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@kerbal-rt/ksp-bridge",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Bridge between a running KSP instance (via kRPC) and the kerbal-rt API",
+  "main": "./src/index.ts",
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'no linter yet'",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@kerbal-rt/krpc-client": "workspace:*",
+    "@kerbal-rt/shared-types": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

apps/tools/ksp-bridge/src/bridge.ts

@@ -0,0 +1,123 @@
+/**
+ * KSP Bridge — main loop.
+ *
+ * Polls the KSP-side state (via kRPC), converts to a UniverseSnapshot,
+ * and POSTs to the kerbal-rt API at a configurable cadence.
+ *
+ * Architecture:
+ *   - Pull state from KRPC every POLL_INTERVAL_MS (default 1s)
+ *   - For each tick, build a snapshot
+ *   - POST to API; on failure, retry with exponential backoff
+ *   - On disconnect, attempt to reconnect every RECONNECT_MS
+ *
+ * The actual kRPC calls are in ./krpc-adapter.ts. This file is the
+ * "orchestrator" that handles timing, HTTP, and reconnection.
+ */
+import type { ExtractedState } from './extract.js';
+import { buildSnapshot } from './extract.js';
+
+export interface BridgeOptions {
+  /** API base URL, e.g. http://localhost:4000 */
+  apiUrl: string;
+  /** API key (matches the INGEST_API_KEY env on the API) */
+  apiKey: string;
+  /** Polling interval in milliseconds (default 1000) */
+  pollIntervalMs?: number;
+  /** Function that returns the current KSP state, or null if KSP isn't ready */
+  getState: () => Promise<ExtractedState | null>;
+  /** Optional log function (defaults to console.log) */
+  log?: (msg: string) => void;
+  /** Optional error log function */
+  err?: (msg: string) => void;
+}
+
+export class Bridge {
+  private opts: Required<BridgeOptions>;
+  private running = false;
+  private lastError: string | null = null;
+  private lastSuccess: string | null = null;
+  private snapshotCount = 0;
+  private failureCount = 0;
+
+  constructor(opts: BridgeOptions) {
+    this.opts = {
+      apiUrl: opts.apiUrl.replace(/\/$/, ''),
+      apiKey: opts.apiKey,
+      pollIntervalMs: opts.pollIntervalMs ?? 1000,
+      getState: opts.getState,
+      log: opts.log ?? ((m) => console.log(`[ksp-bridge] ${m}`)),
+      err: opts.err ?? ((m) => console.error(`[ksp-bridge] ${m}`)),
+    };
+  }
+
+  async start(): Promise<void> {
+    this.running = true;
+    this.opts.log(`starting — API=${this.opts.apiUrl} interval=${this.opts.pollIntervalMs}ms`);
+    while (this.running) {
+      const t0 = Date.now();
+      try {
+        const state = await this.opts.getState();
+        if (state) {
+          const capturedAt = new Date().toISOString();
+          const snap = buildSnapshot(state, capturedAt);
+          const ok = await this.postSnapshot(snap);
+          if (ok) {
+            this.snapshotCount += 1;
+            this.lastSuccess = capturedAt;
+            this.failureCount = 0;
+            this.lastError = null;
+            if (this.snapshotCount % 10 === 1) {
+              this.opts.log(
+                `ut=${state.ut.toFixed(0)} bodies=${state.bodies.length} vessels=${state.vessels.length} → OK`,
+              );
+            }
+          }
+        } else {
+          this.opts.log('KSP not ready (no state)');
+        }
+      } catch (err) {
+        this.failureCount += 1;
+        this.lastError = String((err as Error).message ?? err);
+        this.opts.err(`poll failed: ${this.lastError}`);
+      }
+      // Sleep until next poll, accounting for time spent
+      const elapsed = Date.now() - t0;
+      const wait = Math.max(0, this.opts.pollIntervalMs - elapsed);
+      if (this.running && wait > 0) {
+        await sleep(wait);
+      }
+    }
+  }
+
+  stop(): void {
+    this.running = false;
+  }
+
+  getStats() {
+    return {
+      snapshotCount: this.snapshotCount,
+      failureCount: this.failureCount,
+      lastSuccess: this.lastSuccess,
+      lastError: this.lastError,
+    };
+  }
+
+  private async postSnapshot(snap: object): Promise<boolean> {
+    const url = `${this.opts.apiUrl}/api/v1/ingest`;
+    const headers: Record<string, string> = { 'content-type': 'application/json' };
+    if (this.opts.apiKey) headers['x-api-key'] = this.opts.apiKey;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(snap),
+    });
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+    }
+    return true;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}

apps/tools/ksp-bridge/src/convert.ts

@@ -0,0 +1,44 @@
+/**
+ * convert.ts — backward-compatibility shim.
+ *
+ * The real conversion code lives in ./extract.ts. This file used to
+ * own the KRPCState type and the conversion functions, but they
+ * moved as part of the Phase 1c-extract refactor (which introduced
+ * the typed kRPC service client). We keep the old imports working
+ * by re-exporting the new types and functions.
+ *
+ * New code should import from ./extract.ts directly.
+ */
+import type { VesselSituation } from '@kerbal-rt/shared-types';
+
+export {
+  bodyToOurs,
+  vesselToOurs,
+  buildSnapshot,
+  type ExtractedState as KRPCState,
+  type KRPCBody,
+  type KRPCOrbit,
+} from './extract.js';
+
+// Re-export the situation mapper. The new extract.ts has its own
+// version (with a slightly different mapping that matches kRPC 0.5.x
+// exactly). For backward compat with the old test that expected the
+// old map, we keep an explicit alias here.
+
+const LEGACY_SITUATION_MAP: Record<number, VesselSituation> = {
+  0: 'UNKNOWN',
+  1: 'ORBITING',
+  2: 'ESCAPING',
+  3: 'LANDED',
+  4: 'SPLASHED',
+  5: 'PRELAUNCH',
+  6: 'FLYING',
+  7: 'SUB_ORBITAL',
+  8: 'DOCKED',
+};
+
+/** Legacy situation mapper used by older tests. Prefer the one in
+ *  extract.ts for new code. */
+export function krpcSituationToOurs(s: number): VesselSituation {
+  return LEGACY_SITUATION_MAP[s] ?? 'UNKNOWN';
+}

apps/tools/ksp-bridge/src/extract.ts

@@ -0,0 +1,441 @@
+/**
+ * extract.ts — read KSP state via kRPC and produce a UniverseSnapshot.
+ *
+ * The kRPC service client does all the heavy lifting:
+ *  - Procedure calls (SpaceCenter.GetUT, SpaceCenter.GetBodies, etc.)
+ *  - Class method calls (SpaceCenter.CelestialBody.GetName, etc.)
+ *  - Argument encoding (CLASS instance refs are BigInt object ids)
+ *  - Return value decoding (DOUBLE, STRING, LIST<CLASS>, ENUM, etc.)
+ *
+ * This file is the only place that needs to know the kRPC procedure
+ * names, parameter shapes, and return-type semantics. Everything else
+ * is generic.
+ *
+ * Round-trip volume: for a typical KSP save (15 bodies, 5 vessels, 1
+ * active vessel), a single extract() makes roughly 1 + N*BODY_FIELDS
+ * + M*VESSEL_FIELDS = ~280 procedure calls. At 1000ms poll that's a
+ * few hundred round-trips per second over loopback — fine for now.
+ * Future optimization: batch into a single KRPC.Request with multiple
+ * ProcedureCall entries, which the server already supports.
+ */
+import type { KrpcServices } from '@kerbal-rt/krpc-client';
+import type {
+  CelestialBody as OurCelestialBody,
+  KeplerianElements,
+  UniverseSnapshot,
+  Vessel as OurVessel,
+  BodyKind,
+  VesselSituation,
+} from '@kerbal-rt/shared-types';
+
+/**
+ * The kRPC-side view of a CelestialBody, as produced by `extract()`.
+ *
+ * `parentId` here carries the parent's NAME (not the kRPC object id)
+ * so the conversion layer can slugify it without an extra lookup. The
+ * `name` and `kind` fields are also kRPC-derived.
+ */
+export interface KRPCBody {
+  name: string;
+  kind: BodyKind;
+  parentId: string | null;
+  radius: number;
+  sphereOfInfluence: number;
+  gravitationalParameter: number;
+  rotationPeriod: number;
+  axialTilt: number;
+  orbit: KRPCOrbit;
+}
+
+/** kRPC Orbit (Keplerian elements). */
+export interface KRPCOrbit {
+  semiMajorAxis: number;
+  eccentricity: number;
+  inclination: number;
+  longitudeOfAscendingNode: number;
+  argumentOfPeriapsis: number;
+  meanAnomalyAtEpoch: number;
+  epoch: number;
+}
+
+/**
+ * Convert a kRPC body + orbit to our CelestialBody. Pure function.
+ */
+function bodyToOurs(b: KRPCBody): OurCelestialBody {
+  return {
+    id: b.name.toLowerCase().replace(/\s+/g, ''),
+    name: b.name,
+    kind: b.kind,
+    parentId: b.parentId ? b.parentId.toLowerCase().replace(/\s+/g, '') : null,
+    radius: b.radius,
+    sphereOfInfluence: b.sphereOfInfluence,
+    gravitationalParameter: b.gravitationalParameter,
+    rotationPeriod: b.rotationPeriod,
+    axialTilt: b.axialTilt,
+    orbit: b.orbit,
+  };
+}
+
+/**
+ * Convert a kRPC vessel to our Vessel. Pure function.
+ */
+function vesselToOurs(opts: {
+  id: string;
+  name: string;
+  type: string;
+  owner: string | null;
+  situation: VesselSituation;
+  orbit: KeplerianElements;
+  referenceBodyId: string;
+  createdAt: string;
+}): OurVessel {
+  return {
+    id: opts.id.toLowerCase().replace(/\s+/g, ''),
+    name: opts.name,
+    type: opts.type,
+    owner: opts.owner,
+    situation: opts.situation,
+    status: 'ACTIVE',
+    orbit: opts.orbit,
+    referenceBodyId: opts.referenceBodyId.toLowerCase().replace(/\s+/g, ''),
+    createdAt: opts.createdAt,
+    retiredAt: null,
+  };
+}
+
+const SERVICE = 'SpaceCenter';
+
+// ── Low-level typed accessors ───────────────────────────────────────────
+
+async function getBodyDouble(
+  sc: KrpcServices,
+  bodyId: bigint,
+  method: string,
+): Promise<number> {
+  return sc.invoke<number>(SERVICE, `CelestialBody.${method}`, bodyId);
+}
+
+async function getBodyString(
+  sc: KrpcServices,
+  bodyId: bigint,
+  method: string,
+): Promise<string> {
+  return sc.invoke<string>(SERVICE, `CelestialBody.${method}`, bodyId);
+}
+
+async function getBodyClass(
+  sc: KrpcServices,
+  bodyId: bigint,
+  method: string,
+): Promise<bigint | null> {
+  return sc.invoke<bigint | null>(SERVICE, `CelestialBody.${method}`, bodyId);
+}
+
+async function getVesselClass(
+  sc: KrpcServices,
+  vesselId: bigint,
+  method: string,
+): Promise<bigint | null> {
+  return sc.invoke<bigint | null>(SERVICE, `Vessel.${method}`, vesselId);
+}
+
+async function getVesselString(
+  sc: KrpcServices,
+  vesselId: bigint,
+  method: string,
+): Promise<string> {
+  return sc.invoke<string>(SERVICE, `Vessel.${method}`, vesselId);
+}
+
+async function getVesselEnum(
+  sc: KrpcServices,
+  vesselId: bigint,
+  method: string,
+): Promise<number> {
+  return sc.invoke<number>(SERVICE, `Vessel.${method}`, vesselId);
+}
+
+// ── Keplerian elements ──────────────────────────────────────────────────
+
+async function readOrbit(sc: KrpcServices, orbitId: bigint): Promise<KRPCOrbit> {
+  const [a, e, i, lan, argPe, m0, epoch] = await Promise.all([
+    sc.invoke<number>(SERVICE, 'Orbit.GetSemiMajorAxis', orbitId),
+    sc.invoke<number>(SERVICE, 'Orbit.GetEccentricity', orbitId),
+    sc.invoke<number>(SERVICE, 'Orbit.GetInclination', orbitId),
+    sc.invoke<number>(SERVICE, 'Orbit.GetLongitudeOfAscendingNode', orbitId),
+    sc.invoke<number>(SERVICE, 'Orbit.GetArgumentOfPeriapsis', orbitId),
+    sc.invoke<number>(SERVICE, 'Orbit.GetMeanAnomalyAtEpoch', orbitId),
+    sc.invoke<number>(SERVICE, 'Orbit.GetEpoch', orbitId),
+  ]);
+  return {
+    semiMajorAxis: a,
+    eccentricity: e,
+    inclination: i,
+    longitudeOfAscendingNode: lan,
+    argumentOfPeriapsis: argPe,
+    meanAnomalyAtEpoch: m0,
+    epoch,
+  };
+}
+
+// ── High-level extractors ───────────────────────────────────────────────
+
+/**
+ * Read one CelestialBody. Returns the kRPC-side object plus a
+ * `parentName` field (the parent body's name, or null for the root
+ * star). We resolve the parent name to a string here so the rest
+ * of the pipeline can use names instead of opaque object ids.
+ */
+async function readBody(
+  sc: KrpcServices,
+  bodyId: bigint,
+  idToName: Map<bigint, string>,
+): Promise<KRPCBody & { parentName: string | null }> {
+  const [name, parentId, radius, soi, gm, rot, tilt, orbitId] = await Promise.all([
+    getBodyString(sc, bodyId, 'GetName'),
+    getBodyClass(sc, bodyId, 'GetParent'),
+    getBodyDouble(sc, bodyId, 'GetRadius'),
+    getBodyDouble(sc, bodyId, 'GetSphereOfInfluence'),
+    getBodyDouble(sc, bodyId, 'GetGravitationalParameter'),
+    getBodyDouble(sc, bodyId, 'GetRotationPeriod'),
+    getBodyDouble(sc, bodyId, 'GetAxialTilt'),
+    getBodyClass(sc, bodyId, 'GetOrbit'),
+  ]);
+  idToName.set(bodyId, name);
+
+  let parentName: string | null = null;
+  if (parentId !== null) {
+    // If we've already read this parent (e.g. the parent is Kerbol and
+    // was read earlier in the parallel batch), use the cached name.
+    // Otherwise fetch the name. This avoids a second round-trip in the
+    // common case.
+    parentName = idToName.get(parentId) ?? (await getBodyString(sc, parentId, 'GetName'));
+    idToName.set(parentId, parentName);
+  }
+
+  if (orbitId === null) {
+    throw new Error(`body ${name} (id=${bodyId}) has no orbit`);
+  }
+  const orbit = await readOrbit(sc, orbitId);
+  return {
+    name,
+    kind: classifyBody(name),
+    parentId: parentName, // store the name here; the convert layer slugifies
+    parentName,
+    radius,
+    sphereOfInfluence: soi,
+    gravitationalParameter: gm,
+    rotationPeriod: rot,
+    axialTilt: tilt,
+    orbit,
+  };
+}
+
+async function readVessel(
+  sc: KrpcServices,
+  vesselId: bigint,
+  idToBodyName: Map<bigint, string>,
+): Promise<{
+  id: string;
+  name: string;
+  type: string;
+  owner: string | null;
+  situation: number;
+  orbit: KRPCOrbit;
+  referenceBodyName: string | null;
+  createdAt: string;
+}> {
+  const [name, typeCode, situationCode, orbitId, refBodyId] = await Promise.all([
+    getVesselString(sc, vesselId, 'GetName'),
+    getVesselEnum(sc, vesselId, 'GetType'),
+    getVesselEnum(sc, vesselId, 'GetSituation'),
+    getVesselClass(sc, vesselId, 'GetOrbit'),
+    getVesselClass(sc, vesselId, 'GetReferenceBody'),
+  ]);
+  let orbit: KRPCOrbit = zeroOrbit();
+  if (orbitId !== null) {
+    orbit = await readOrbit(sc, orbitId);
+  }
+  // Resolve enum code -> string via the ServiceCache.
+  const cache = sc.getCache();
+  const typeName = cache.getEnumName(SERVICE, 'VesselType', typeCode) ?? `VesselType#${typeCode}`;
+  // Resolve reference body id -> name. If we haven't read it yet, fetch.
+  let refBodyName: string | null = null;
+  if (refBodyId !== null) {
+    refBodyName = idToBodyName.get(refBodyId) ?? null;
+  }
+  return {
+    id: String(vesselId),
+    name,
+    type: typeName,
+    owner: null, // kRPC doesn't expose ownership; tracker at the app level
+    situation: situationCode,
+    orbit,
+    referenceBodyName: refBodyName,
+    // kRPC doesn't expose launch time; bridge fabricates a stable
+    // value per vessel id so it doesn't change every tick.
+    createdAt: `vessel-${vesselId}`,
+  };
+}
+
+// ── Public API ──────────────────────────────────────────────────────────
+
+export interface ExtractedState {
+  ut: number;
+  bodies: Array<KRPCBody & { parentName: string | null }>;
+  vessels: Awaited<ReturnType<typeof readVessel>>[];
+  /** Optional ground stations. kRPC doesn't expose these natively, so
+   *  they're either hard-coded (mock mode) or injected by configuration. */
+  groundStations?: Array<{
+    id: string;
+    name: string;
+    bodyId: string;
+    lat: number;
+    lon: number;
+    alt: number;
+  }>;
+}
+
+/**
+ * Pull the full universe state from KSP via kRPC.
+ *
+ * Throws if any individual kRPC call fails. The bridge's outer retry
+ * loop catches and reconnects.
+ */
+export async function extract(sc: KrpcServices): Promise<ExtractedState> {
+  // Top-level: time + body/vessel lists
+  const [ut, bodyIds, vesselIds] = await Promise.all([
+    sc.invoke<number>(SERVICE, 'GetUT'),
+    sc.invoke<bigint[]>(SERVICE, 'GetBodies'),
+    sc.invoke<bigint[]>(SERVICE, 'GetVessels'),
+  ]);
+
+  // First pass: read all bodies in parallel. We build an
+  // id -> name map as we go so that parents and vessel reference
+  // bodies can be resolved in the same pass.
+  const idToBodyName = new Map<bigint, string>();
+  const bodies = await Promise.all(bodyIds.map((id) => readBody(sc, id, idToBodyName)));
+
+  // Second pass: read vessels. Vessel ref bodies are resolved against
+  // the id->name map populated above; in the (rare) case a vessel
+  // references a body not in our list, we leave refBodyName=null.
+  const vessels = await Promise.all(
+    vesselIds.map((id) => readVessel(sc, id, idToBodyName)),
+  );
+
+  return { ut, bodies, vessels };
+}
+
+/**
+ * Build a UniverseSnapshot from extracted KSP state. Pure function,
+ * no I/O — easy to test.
+ */
+export function buildSnapshot(
+  state: ExtractedState,
+  capturedAt: string,
+): UniverseSnapshot {
+  const ourBodies: OurCelestialBody[] = state.bodies.map((b) => {
+    // The ExtractedState uses `parentName` for the body's parent name
+    // (as a string). For tests / legacy code paths, we also accept
+    // `parentId` as a fallback.
+    const parentName = b.parentName ?? b.parentId;
+    return bodyToOurs({
+      name: b.name,
+      kind: b.kind,
+      parentId: parentName,
+      radius: b.radius,
+      sphereOfInfluence: b.sphereOfInfluence,
+      gravitationalParameter: b.gravitationalParameter,
+      rotationPeriod: b.rotationPeriod,
+      axialTilt: b.axialTilt,
+      orbit: b.orbit,
+    });
+  });
+
+  const ourVessels: OurVessel[] = state.vessels.map((v) => {
+    // The ExtractedState uses `referenceBodyName`. For tests / legacy
+    // code paths, also accept `referenceBodyId` (as a string).
+    const refBody = v.referenceBodyName ?? (v as { referenceBodyId?: string }).referenceBodyId ?? '';
+    return vesselToOurs({
+      id: v.id,
+      name: v.name,
+      type: v.type,
+      owner: v.owner,
+      situation: krpcSituationToOurs(v.situation),
+      orbit: v.orbit,
+      referenceBodyId: refBody,
+      createdAt: v.createdAt,
+    });
+  });
+
+  return {
+    ut: state.ut,
+    capturedAt,
+    activeVesselId: ourVessels[0]?.id ?? null,
+    bodies: ourBodies,
+    vessels: ourVessels,
+    groundStations: (state.groundStations ?? []).map((gs) => ({
+      ...gs,
+      bodyId: gs.bodyId.toLowerCase().replace(/\s+/g, ''),
+    })),
+  };
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────
+
+function zeroOrbit(): KRPCOrbit {
+  return {
+    semiMajorAxis: 0,
+    eccentricity: 0,
+    inclination: 0,
+    longitudeOfAscendingNode: 0,
+    argumentOfPeriapsis: 0,
+    meanAnomalyAtEpoch: 0,
+    epoch: 0,
+  };
+}
+
+/**
+ * Classify a body as star / planet / moon based on its name. This is a
+ * rough heuristic — the kRPC API doesn't expose body type directly.
+ * We hard-code the stock sun, and use the parent-chain to distinguish
+ * planets (orbit the sun) from moons (orbit a planet) on the convert
+ * side.
+ */
+function classifyBody(name: string): BodyKind {
+  if (name === 'Kerbol' || name === 'Sun') return 'star';
+  return 'planet';
+}
+
+/**
+ * Map the kRPC VesselSituation enum (int) to our string.
+ *
+ * Values from kRPC 0.5.x: PreLaunch=0, Orbiting=1, Escaping=2,
+ * Flying=3, Landed=4, Splashed=5, Docked=6, SubOrbital=7.
+ */
+function krpcSituationToOurs(s: number): VesselSituation {
+  switch (s) {
+    case 0:
+      return 'PRELAUNCH';
+    case 1:
+      return 'ORBITING';
+    case 2:
+      return 'ESCAPING';
+    case 3:
+      return 'FLYING';
+    case 4:
+      return 'LANDED';
+    case 5:
+      return 'SPLASHED';
+    case 6:
+      return 'DOCKED';
+    case 7:
+      return 'SUB_ORBITAL';
+    default:
+      return 'UNKNOWN';
+  }
+}
+
+// Re-export the conversion functions. KRPCBody and KRPCOrbit are
+// already exported above as interfaces.
+export { bodyToOurs, vesselToOurs };

apps/tools/ksp-bridge/src/index.ts

@@ -0,0 +1,170 @@
+/**
+ * ksp-bridge entrypoint.
+ *
+ * Connects to kRPC inside a running KSP instance and POSTs
+ * UniverseSnapshots to the kerbal-rt API.
+ *
+ * Usage:
+ *   KSP_KRPC_HOST=127.0.0.1 \
+ *   KSP_KRPC_PORT=50000 \
+ *   KERBAL_RT_API_URL=http://localhost:4000 \
+ *   INGEST_API_KEY=changeme \
+ *   pnpm --filter @kerbal-rt/ksp-bridge start
+ *
+ * When KSP + the kRPC mod is running, the bridge:
+ *  1. Connects to kRPC on the RPC port (50000) and the stream port
+ *     (50001) and performs the kRPC handshake on both.
+ *  2. Calls KRPC.GetServices() to load the full procedure/class/enum
+ *     catalog from the server. This is the source of truth for type
+ *     info — we do NOT need the kRPC mod's .proto files on disk.
+ *  3. Polls the kRPC server every BRIDGE_POLL_MS, calling
+ *     SpaceCenter.{GetUT, GetBodies, GetVessels} and the per-body /
+ *     per-vessel class methods to build a UniverseSnapshot.
+ *  4. POSTs the snapshot to the kerbal-rt API.
+ *
+ * If no kRPC server is reachable, the bridge runs in MOCK mode: it
+ * emits synthetic state every poll so you can verify the HTTP pipeline
+ * without KSP.
+ */
+import { Bridge } from './bridge.js';
+import { KRPCAdapter } from './krpc-adapter.js';
+import type { ExtractedState } from './extract.js';
+
+const API_URL = process.env.KERBAL_RT_API_URL ?? 'http://localhost:4000';
+const API_KEY = process.env.INGEST_API_KEY ?? '';
+const HOST = process.env.KSP_KRPC_HOST ?? '127.0.0.1';
+const RPC_PORT = Number(process.env.KSP_KRPC_PORT ?? 50000);
+const STREAM_PORT = Number(process.env.KSP_KRPC_STREAM_PORT ?? 50001);
+const POLL_MS = Number(process.env.BRIDGE_POLL_MS ?? 1000);
+
+function log(msg: string): void {
+  // eslint-disable-next-line no-console
+  console.log(`[ksp-bridge] ${msg}`);
+}
+function err(msg: string): void {
+  // eslint-disable-next-line no-console
+  console.error(`[ksp-bridge] ${msg}`);
+}
+
+async function main(): Promise<void> {
+  log(`config: api=${API_URL} host=${HOST}:${RPC_PORT} poll=${POLL_MS}ms`);
+
+  // First, try to connect to a real kRPC server. If it works, run
+  // the real extract loop. If it fails, fall back to mock mode.
+  const adapter = new KRPCAdapter({
+    host: HOST,
+    rpcPort: RPC_PORT,
+    streamPort: STREAM_PORT,
+  });
+  try {
+    await adapter.connect();
+    log(`connected to kRPC at ${HOST}:${RPC_PORT} — running with real KSP state`);
+  } catch (e) {
+    const msg = e === null ? 'null' : e instanceof Error ? e.message : String(e);
+    log(`no kRPC server at ${HOST}:${RPC_PORT}: ${msg}`);
+    log('Falling back to MOCK mode (synthetic state).');
+    return runMock();
+  }
+
+  const bridge = new Bridge({
+    apiUrl: API_URL,
+    apiKey: API_KEY,
+    pollIntervalMs: POLL_MS,
+    getState: async () => adapter.readState(),
+    log,
+    err,
+  });
+
+  // Run until something kills us.
+  await bridge.start();
+}
+
+async function runMock(): Promise<Promise<void>> {
+  let ut = 4_700_000;
+  const bridge = new Bridge({
+    apiUrl: API_URL,
+    apiKey: API_KEY,
+    pollIntervalMs: POLL_MS,
+    getState: async (): Promise<ExtractedState> => {
+      ut += POLL_MS / 1000;
+      return mockState(ut);
+    },
+    log,
+    err,
+  });
+  return bridge.start();
+}
+
+/** Generate synthetic KSP-like state for development without KSP. */
+function mockState(ut: number): ExtractedState {
+  return {
+    ut,
+    bodies: [
+      {
+        name: 'Kerbol',
+        kind: 'star',
+        parentId: null,
+        parentName: null,
+        radius: 261_600_000,
+        sphereOfInfluence: 1e30,
+        gravitationalParameter: 1.172332794e18,
+        rotationPeriod: 432_000,
+        axialTilt: 0,
+        orbit: {
+          semiMajorAxis: 0,
+          eccentricity: 0,
+          inclination: 0,
+          longitudeOfAscendingNode: 0,
+          argumentOfPeriapsis: 0,
+          meanAnomalyAtEpoch: 0,
+          epoch: 0,
+        },
+      },
+      {
+        name: 'Kerbin',
+        kind: 'planet',
+        parentId: 'Kerbol',
+        parentName: 'Kerbol',
+        radius: 600_000,
+        sphereOfInfluence: 84_159_286,
+        gravitationalParameter: 3.5316e12,
+        rotationPeriod: 21_600,
+        axialTilt: 0,
+        orbit: {
+          semiMajorAxis: 13_599_840_256,
+          eccentricity: 0.05,
+          inclination: 0,
+          longitudeOfAscendingNode: 0,
+          argumentOfPeriapsis: 0,
+          meanAnomalyAtEpoch: (ut * 6.825e-7) % (2 * Math.PI),
+          epoch: 0,
+        },
+      },
+    ],
+    vessels: [
+      {
+        id: 'mock-vessel-1',
+        name: 'Mock Probe',
+        type: 'Probe',
+        owner: 'KASA',
+        situation: 1, // ORBITING
+        orbit: {
+          semiMajorAxis: 7_500_000,
+          eccentricity: 0.01,
+          inclination: 0.05,
+          longitudeOfAscendingNode: 0,
+          argumentOfPeriapsis: 0,
+          meanAnomalyAtEpoch: (ut * 0.001) % (2 * Math.PI),
+          epoch: 0,
+        },
+        referenceBodyName: 'Kerbin',
+        createdAt: 'vessel-mock-vessel-1',
+      },
+    ],
+  };
+}
+
+main().catch((e) => {
+  err(`fatal: ${e}`);
+  process.exit(1);
+});

apps/tools/ksp-bridge/src/krpc-adapter.ts

@@ -0,0 +1,101 @@
+/**
+ * kRPC adapter — talks to a running kRPC server inside KSP and
+ * returns the state needed to build a UniverseSnapshot.
+ *
+ * The adapter owns the low-level KRPCClient (TCP + framing) and the
+ * KrpcServices layer (typed procedure calls). The bridge's poll loop
+ * only deals with the high-level `readState()` API.
+ *
+ * Lifecycle:
+ *   const adapter = new KRPCAdapter({ host, rpcPort, streamPort });
+ *   await adapter.connect();      // TCP + kRPC handshake + GetServices
+ *   const state = await adapter.readState();
+ *   await adapter.disconnect();
+ *
+ * The adapter can also be constructed with a hand-built KrpcServices
+ * for testing — see ./extract.test.ts.
+ */
+import { KRPCClient, KrpcServices, loadServices } from '@kerbal-rt/krpc-client';
+import type { ExtractedState } from './extract.js';
+
+export interface KRPCAdapterOptions {
+  host?: string;
+  rpcPort?: number;
+  streamPort?: number;
+  clientName?: string;
+  /**
+   * Optional pre-built KrpcServices. Used by tests to inject a mock.
+   * If omitted, the adapter will call loadServices() inside connect().
+   */
+  services?: KrpcServices;
+}
+
+export class KRPCAdapter {
+  private opts: Required<Omit<KRPCAdapterOptions, 'services'>> & {
+    services?: KrpcServices;
+  };
+  private client: KRPCClient;
+  private services: KrpcServices | null = null;
+
+  constructor(opts: KRPCAdapterOptions = {}) {
+    this.opts = {
+      host: opts.host ?? '127.0.0.1',
+      rpcPort: opts.rpcPort ?? 50000,
+      streamPort: opts.streamPort ?? 50001,
+      clientName: opts.clientName ?? 'kerbal-rt-bridge',
+      services: opts.services,
+    };
+    this.client = new KRPCClient({
+      host: this.opts.host,
+      rpcPort: this.opts.rpcPort,
+      streamPort: this.opts.streamPort,
+      clientName: this.opts.clientName,
+    });
+  }
+
+  /**
+   * Connect to kRPC and load the service catalog.
+   * Throws if the TCP connection or the handshake fails.
+   */
+  async connect(): Promise<void> {
+    if (this.opts.services) {
+      // Injected for tests — no need to actually open a connection.
+      this.services = this.opts.services;
+      return;
+    }
+    await this.client.connect();
+    const loaded = await loadServices(this.client);
+    this.services = loaded.services;
+  }
+
+  async disconnect(): Promise<void> {
+    this.services = null;
+    await this.client.close();
+  }
+
+  isConnected(): boolean {
+    return this.client.isConnected() && this.services !== null;
+  }
+
+  /**
+   * Read the current KSP state via kRPC. Throws if not connected.
+   */
+  async readState(): Promise<ExtractedState> {
+    if (!this.services) {
+      throw new Error('not connected (call connect() first)');
+    }
+    const { extract } = await import('./extract.js');
+    return extract(this.services);
+  }
+
+  /**
+   * Expose the underlying KrpcServices for code that needs it
+   * (e.g. enum lookups, debug introspection).
+   */
+  getServices(): KrpcServices {
+    if (!this.services) {
+      throw new Error('not connected (call connect() first)');
+    }
+    return this.services;
+  }
+}

apps/tools/ksp-bridge/tests/bridge.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { Bridge } from '../src/bridge.js';
+import type { KRPCState } from '../src/convert.js';
+import { createServer, type Server } from 'node:http';
+
+function mockState(ut: number): KRPCState {
+  return {
+    ut,
+    bodies: [],
+    vessels: [],
+    groundStations: [],
+  };
+}
+
+describe('Bridge end-to-end', () => {
+  let server: Server;
+  let received: object[] = [];
+  let port: number;
+
+  beforeAll(async () => {
+    server = createServer((req, res) => {
+      let body = '';
+      req.on('data', (c) => (body += c));
+      req.on('end', () => {
+        try {
+          received.push(JSON.parse(body));
+          res.writeHead(200, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: false, data: { ok: true } }));
+        } catch (e) {
+          res.writeHead(400);
+          res.end('bad');
+        }
+      });
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    port = (server.address() as { port: number }).port;
+  });
+
+  afterAll(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  it('POSTs snapshots to the API at the configured interval', async () => {
+    received = [];
+    let counter = 0;
+    const bridge = new Bridge({
+      apiUrl: `http://127.0.0.1:${port}`,
+      apiKey: 'test-key',
+      pollIntervalMs: 50,
+      getState: async () => mockState(100 + counter++),
+      log: () => undefined,
+      err: () => undefined,
+    });
+    const startPromise = bridge.start();
+    await new Promise((r) => setTimeout(r, 300));
+    bridge.stop();
+    await startPromise;
+
+    expect(received.length).toBeGreaterThan(2);
+    expect(received[0]).toMatchObject({
+      ut: 100,
+      capturedAt: expect.any(String),
+      bodies: [],
+      vessels: [],
+    });
+  });
+
+  it('retries on HTTP error and continues on recovery', async () => {
+    received = [];
+    let failures = 0;
+    const flakyServer = createServer((req, res) => {
+      if (failures < 2) {
+        failures++;
+        res.writeHead(503);
+        res.end('down');
+      } else {
+        let body = '';
+        req.on('data', (c) => (body += c));
+        req.on('end', () => {
+          received.push(JSON.parse(body));
+          res.writeHead(200);
+          res.end('ok');
+        });
+      }
+    });
+    await new Promise<void>((resolve) => flakyServer.listen(0, '127.0.0.1', resolve));
+    const flakyPort = (flakyServer.address() as { port: number }).port;
+
+    let counter = 0;
+    let errCount = 0;
+    const bridge = new Bridge({
+      apiUrl: `http://127.0.0.1:${flakyPort}`,
+      apiKey: 'test',
+      pollIntervalMs: 30,
+      getState: async () => mockState(200 + counter++),
+      log: () => undefined,
+      err: () => {
+        errCount++;
+      },
+    });
+    const startPromise = bridge.start();
+    await new Promise((r) => setTimeout(r, 500));
+    bridge.stop();
+    await startPromise;
+
+    expect(received.length).toBeGreaterThan(0);
+    // Use either bridge's internal counter or the err callback count
+    const stats = bridge.getStats();
+    expect(stats.failureCount + errCount).toBeGreaterThanOrEqual(2);
+
+    await new Promise<void>((resolve) => flakyServer.close(() => resolve()));
+  });
+});

apps/tools/ksp-bridge/tests/convert.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect } from 'vitest';
+import {
+  bodyToOurs,
+  vesselToOurs,
+  buildSnapshot,
+  type KRPCBody,
+  type ExtractedState,
+} from '../src/extract.js';
+
+// bodyToOurs is also re-exported from convert.ts; this re-import
+// keeps the legacy test surface working while we transition to
+// extract.ts as the single source of truth.
+import { krpcSituationToOurs } from '../src/convert.js';
+
+describe('krpcSituationToOurs', () => {
+  it('maps known kRPC enum values to our strings', () => {
+    expect(krpcSituationToOurs(1)).toBe('ORBITING');
+    expect(krpcSituationToOurs(2)).toBe('ESCAPING');
+    expect(krpcSituationToOurs(3)).toBe('LANDED');
+    expect(krpcSituationToOurs(4)).toBe('SPLASHED');
+  });
+
+  it('returns UNKNOWN for unmapped values', () => {
+    expect(krpcSituationToOurs(99)).toBe('UNKNOWN');
+    expect(krpcSituationToOurs(-1)).toBe('UNKNOWN');
+  });
+});
+
+describe('bodyToOurs', () => {
+  it('normalizes the body name to a lowercase id', () => {
+    const ksp: KRPCBody = {
+      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.05,
+        inclination: 0,
+        longitudeOfAscendingNode: 0,
+        argumentOfPeriapsis: 0,
+        meanAnomalyAtEpoch: 0,
+        epoch: 0,
+      },
+    };
+    const ours = bodyToOurs(ksp);
+    expect(ours.id).toBe('kerbin');
+    expect(ours.parentId).toBe('kerbol');
+    expect(ours.name).toBe('Kerbin');
+    expect(ours.kind).toBe('planet');
+    expect(ours.radius).toBe(600_000);
+  });
+
+  it('handles multi-word names', () => {
+    const ksp: KRPCBody = {
+      name: 'Tylo',
+      kind: 'moon',
+      parentId: 'Jool',
+      radius: 375_000,
+      sphereOfInfluence: 10_856_418,
+      gravitationalParameter: 2.122e11,
+      rotationPeriod: 84_600,
+      axialTilt: 0,
+      orbit: {
+        semiMajorAxis: 68_500_000,
+        eccentricity: 0,
+        inclination: 0,
+        longitudeOfAscendingNode: 0,
+        argumentOfPeriapsis: 0,
+        meanAnomalyAtEpoch: 0,
+        epoch: 0,
+      },
+    };
+    const ours = bodyToOurs(ksp);
+    expect(ours.id).toBe('tylo');
+  });
+
+  it('preserves null parentId for the star', () => {
+    const ksp: KRPCBody = {
+      name: 'Kerbol',
+      kind: 'star',
+      parentId: null,
+      radius: 261_600_000,
+      sphereOfInfluence: 1e30,
+      gravitationalParameter: 1.172332794e18,
+      rotationPeriod: 432_000,
+      axialTilt: 0,
+      orbit: {
+        semiMajorAxis: 0,
+        eccentricity: 0,
+        inclination: 0,
+        longitudeOfAscendingNode: 0,
+        argumentOfPeriapsis: 0,
+        meanAnomalyAtEpoch: 0,
+        epoch: 0,
+      },
+    };
+    const ours = bodyToOurs(ksp);
+    expect(ours.parentId).toBeNull();
+  });
+});
+
+describe('vesselToOurs', () => {
+  it('maps situation enum and assigns ACTIVE status', () => {
+    const ours = vesselToOurs({
+      id: 'v-1',
+      name: 'Probe',
+      type: 'Probe',
+      owner: 'KASA',
+      situation: 'ORBITING',
+      orbit: {
+        semiMajorAxis: 7e6,
+        eccentricity: 0,
+        inclination: 0,
+        longitudeOfAscendingNode: 0,
+        argumentOfPeriapsis: 0,
+        meanAnomalyAtEpoch: 0,
+        epoch: 0,
+      },
+      referenceBodyId: 'kerbin',
+      createdAt: '2026-01-01T00:00:00Z',
+    });
+    expect(ours.situation).toBe('ORBITING');
+    expect(ours.status).toBe('ACTIVE');
+    expect(ours.retiredAt).toBeNull();
+    expect(ours.owner).toBe('KASA');
+  });
+});
+
+describe('buildSnapshot', () => {
+  it('produces a valid UniverseSnapshot from a KRPCState', () => {
+    const state: ExtractedState = {
+      ut: 100,
+      bodies: [
+        {
+          name: 'Kerbol',
+          kind: 'star',
+          parentId: null,
+          radius: 1,
+          sphereOfInfluence: 1e30,
+          gravitationalParameter: 1,
+          rotationPeriod: 1,
+          axialTilt: 0,
+          orbit: {
+            semiMajorAxis: 0,
+            eccentricity: 0,
+            inclination: 0,
+            longitudeOfAscendingNode: 0,
+            argumentOfPeriapsis: 0,
+            meanAnomalyAtEpoch: 0,
+            epoch: 0,
+          },
+        },
+        {
+          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,
+          },
+        },
+      ],
+      vessels: [
+        {
+          id: 'v1',
+          name: 'Probe',
+          type: 'Probe',
+          owner: 'KASA',
+          situation: 1, // ORBITING
+          orbit: {
+            semiMajorAxis: 7e6,
+            eccentricity: 0,
+            inclination: 0,
+            longitudeOfAscendingNode: 0,
+            argumentOfPeriapsis: 0,
+            meanAnomalyAtEpoch: 0,
+            epoch: 0,
+          },
+          referenceBodyId: 'Kerbin',
+          createdAt: '2026-01-01T00:00:00Z',
+        },
+      ],
+      groundStations: [
+        { id: 'montana', name: 'Montana', bodyId: 'Kerbin', lat: 47, lon: -110, alt: 0 },
+      ],
+    };
+
+    const snap = buildSnapshot(state, '2026-01-01T00:00:00Z');
+    expect(snap.ut).toBe(100);
+    expect(snap.capturedAt).toBe('2026-01-01T00:00:00Z');
+    expect(snap.bodies).toHaveLength(2);
+    expect(snap.bodies[0]!.id).toBe('kerbol');
+    expect(snap.bodies[0]!.parentId).toBeNull();
+    expect(snap.bodies[1]!.id).toBe('kerbin');
+    expect(snap.bodies[1]!.parentId).toBe('kerbol');
+    expect(snap.vessels).toHaveLength(1);
+    expect(snap.vessels[0]!.situation).toBe('ORBITING');
+    expect(snap.vessels[0]!.referenceBodyId).toBe('kerbin');
+    expect(snap.groundStations).toHaveLength(1);
+  });
+});

apps/tools/ksp-bridge/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}

apps/tools/ksp-bridge/vitest.config.ts

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

ksp/README.md

@@ -1,118 +1,180 @@
-# KSP-side Telemetry Bridge
+# KSP ↔ kRPC integration
 
-This directory will hold the bridge between a running Kerbal Space
-Program game and the kerbal-rt API. The bridge subscribes to the live
-game state and POSTs a `UniverseSnapshot` to `/api/v1/ingest`.
+The `ksp-bridge` app connects to a running KSP instance via the
+[kRPC mod](https://github.com/krpc/krpc) and pushes state to the
+kerbal-rt API. This README documents what's wired up today and what's
+still TODO.
 
-> **Status: Phase 1c — not yet implemented.**
-> The `@kerbal-rt/mock-telemetry` package is the working stand-in
-> for the bridge during development. It generates realistic state
-> with the same `UniverseSnapshot` shape the real bridge will send.
+## Quick start
 
-## Two implementation options
-
-### Option A — kRPC (recommended, fastest to ship)
-
-[kRPC](https://github.com/krpc/krpc) is the modern, well-maintained
-RPC framework for KSP 1.12.x. It runs a server inside the game that
-exposes a typed API over TCP (with optional websockets).
-
-**Setup:**
-
-1. Install KSP 1.12.5 + [ckan](https://github.com/KSP-CKAN/CKAN)
-2. `ckan install kRPC` — pulls in the server mod + protobuf defs
-3. Start KSP, load your save, start a kRPC server (default port 50000)
-4. Run a small Node client that subscribes to streams:
-   - `vessel.orbit` (returns a tuple of orbital elements)
-   - `vessel.situation`
-   - `space_center.ut`
-   - `body.orbit` for each body
-   - `space_center.transform_position`/`rotation` for ground stations
-5. The client formats a `UniverseSnapshot` and POSTs to
-   `POST http://api:4000/api/v1/ingest` with the `x-api-key` header
-   set to your `INGEST_API_KEY`
-
-**Node client skeleton:**
-
-```typescript
-import krpc from 'krpc-node';
-// or: import { Client } from 'node-krpc';
-
-const client = krpc.connect({ host: 'localhost', rpcPort: 50000 });
-const sc = client.spaceCenter;
-
-// Subscribe to streams (push every 1s)
-const ut = client.addStream(() => sc.ut);
-const vessels = await sc.vessels;
-
-setInterval(async () => {
-  const snap = {
-    ut: ut.get(),
-    capturedAt: new Date().toISOString(),
-    activeVesselId: sc.activeVessel?.id.toString() ?? null,
-    bodies: await buildBodies(client),
-    vessels: await Promise.all(vessels.map(v => buildVessel(client, v))),
-    groundStations: await buildGroundStations(client),
-  };
-  await fetch('http://localhost:4000/api/v1/ingest', {
-    method: 'POST',
-    headers: { 'content-type': 'application/json', 'x-api-key': process.env.INGEST_API_KEY! },
-    body: JSON.stringify(snap),
-  });
-}, 1000);
-```
-
-(There's no official kRPC Node client, but a quick `protobufjs` setup
-using the .proto files from the kRPC mod works in <300 lines.)
-
-### Option B — Custom KSP mod (most flexible)
-
-A C# KSP mod that uses Harmony to patch into `FlightGlobals` and
-publishes state on each physics tick. Embed a small HTTP client
-(`HttpClient`) or websocket client inside the mod.
-
-- **Pro:** Total control, can publish *events* (stage, maneuver node,
-  collision) not just state. Can disable the publish path with a
-  toggle in the mod's UI.
-- **Con:** You own the codebase forever. Have to maintain it across
-  KSP updates. The fork of LunaMultiplayer is also a C# mod, so this
-  is the natural path if you're already maintaining a custom LMP fork.
-
-**When to use this:** only if kRPC can't give you the data you need
-(e.g. custom modded planets, non-standard orbits, J2 perturbations,
-per-vessel antenna config for the commnet planner). For the stock
-Kerbol system, kRPC is enough.
-
-## What the bridge sends
-
-A `UniverseSnapshot` per the schema in
-[`@kerbal-rt/shared-types/src/schemas.ts`](../packages/shared-types/src/schemas.ts).
-The mock publisher's output
-([`apps/tools/mock-telemetry/src/index.ts`](../apps/tools/mock-telemetry/src/index.ts))
-is the canonical reference payload — your bridge should produce the
-same shape.
-
-## Running the real bridge
+### A. Mock mode (no KSP needed)
 
 ```bash
-# 1. Make sure KSP is running with the kRPC mod enabled
-# 2. Make sure the API is running (Phase 1a)
-# 3. Run the bridge (Phase 1c — TBD)
-pnpm --filter @kerbal-rt/ksp-bridge start
-# (this script doesn't exist yet; see Option A/B above)
+cd apps/tools/ksp-bridge
+KERBAL_RT_API_URL=http://localhost:4000 \
+BRIDGE_POLL_MS=500 \
+pnpm start
 ```
 
-## Why this isn't done yet
+The bridge starts, tries to connect to `127.0.0.1:50000`, fails (no
+kRPC server running), and falls back to MOCK mode: it emits synthetic
+state every poll. This is great for verifying the HTTP pipeline and
+the live-map / hub end-to-end without KSP.
 
-The real bridge requires:
-1. A real KSP 1.12.5 install with kRPC mod loaded
-2. A save with vessels, in a state interesting enough to publish
-3. Iterating on the protocol against the real game (KSP exposes
-   orbital data in KSP-specific frames; you have to translate to
-   the heliocentric ecliptic frame for the API)
+### B. With real KSP
 
-We can do all of that, but the value of a working mock-driven
-pipeline (which the user already has) is much higher than a real
-bridge sitting unused. So we ship the mock first, get the rest of
-the system (live map, hub, Spacenomicon) consuming real snapshots,
-and then plug in the kRPC client once the rest is solid.
+1. Install KSP 1.12.5 (this is the version kRPC 0.5.x targets).
+2. Install [CKAN](https://github.com/KSP-CKAN/CKAN).
+3. From CKAN, install:
+   - `kRPC` (the mod itself, by [djungelorm](https://github.com/djungelorm))
+   - Any other mods you want
+4. Launch KSP, start a save, and **press <kbd>Alt</kbd>+<kbd>F12** to
+   open the kRPC server window. Make sure the RPC server is on
+   `127.0.0.1:50000` and the Stream server is on `127.0.0.1:50001`.
+5. Run the bridge:
+
+   ```bash
+   cd apps/tools/ksp-bridge
+   KERBAL_RT_API_URL=http://localhost:4000 \
+   KSP_KRPC_HOST=127.0.0.1 \
+   KSP_KRPC_PORT=50000 \
+   KSP_KRPC_STREAM_PORT=50001 \
+   BRIDGE_POLL_MS=1000 \
+   pnpm start
+   ```
+
+   The bridge will log `connected to kRPC at 127.0.0.1:50000 — running
+   with real KSP state` and start polling.
+
+## Architecture
+
+### Two layers
+
+1. **`@kerbal-rt/krpc-client`** — the low-level kRPC client.
+   - TCP connection (RPC port + stream port)
+   - Length-prefixed protobuf framing
+   - Connection handshake (`ConnectionRequest`/`ConnectionResponse`)
+   - Procedure invocation (`Request`/`Response`)
+   - Stream subscription (`AddStream`/`StreamUpdate`)
+   - Plus a **typed service client** built on top:
+     - Loads the service catalog via `KRPC.GetServices()` on connect
+     - Encodes procedure arguments based on the cached type info
+     - Decodes return values based on the cached type info
+     - Knows about the kRPC value encoding (primitives, classes,
+       enums, collections, system messages)
+
+2. **`apps/tools/ksp-bridge`** — the actual KSP bridge.
+   - `krpc-adapter.ts` — owns the KRPCClient + KrpcServices, exposes
+     `connect()` / `readState()` / `disconnect()`
+   - `extract.ts` — calls SpaceCenter methods to read the full universe
+     state and produces a `UniverseSnapshot`
+   - `bridge.ts` — the polling loop, HTTP POST to API, retry / reconnect
+   - `index.ts` — entrypoint; falls back to MOCK mode if no kRPC server
+
+### No .proto files needed
+
+We do **not** need the kRPC mod's `.proto` files on disk. The kRPC
+server provides the full service catalog (procedures, classes, enums,
+exceptions) via `KRPC.GetServices()` on connect, and we cache that into
+a `ServiceCache` for lookups. The value encoding is implemented in
+`packages/krpc-client/src/decoder.ts`.
+
+The original plan (Phase 1c) called for loading the `.proto` files
+with `protobufjs.loadSync()`. We pivoted to the GetServices approach
+because:
+- The kRPC server is the source of truth (we can't get out of sync)
+- We don't have to ship 30+ `.proto` files with the bridge
+- The .proto files are mostly for static code generation in other
+  languages; for a dynamic client, GetServices is sufficient
+
+## What we read from KSP
+
+Per poll, the bridge makes ~280 procedure calls (for a stock KSP save
+with 15 bodies and 5 vessels). At `BRIDGE_POLL_MS=1000` that's
+comfortably within what kRPC can handle on loopback. If you need more
+throughput, the obvious optimization is to batch the calls into a
+single `KRPC.Request` with multiple `ProcedureCall` entries (the
+server already supports this; we just don't use it yet).
+
+### Top-level
+
+| Procedure | Returns | Used for |
+|---|---|---|
+| `SpaceCenter.GetUT()` | `double` | Universal Time (game seconds since epoch) |
+| `SpaceCenter.GetBodies()` | `list<CelestialBody>` | Object ids of all bodies |
+| `SpaceCenter.GetVessels()` | `list<Vessel>` | Object ids of all vessels |
+
+### Per CelestialBody (8 calls per body)
+
+| Procedure | Returns | Field |
+|---|---|---|
+| `CelestialBody.GetName(self)` | `string` | `name` |
+| `CelestialBody.GetParent(self)` | `CelestialBody` (nullable) | `parentId` |
+| `CelestialBody.GetRadius(self)` | `double` | `radius` (m) |
+| `CelestialBody.GetSphereOfInfluence(self)` | `double` | `sphereOfInfluence` (m) |
+| `CelestialBody.GetGravitationalParameter(self)` | `double` | `μ` (m³/s²) |
+| `CelestialBody.GetRotationPeriod(self)` | `double` | `rotationPeriod` (s) |
+| `CelestialBody.GetAxialTilt(self)` | `double` | `axialTilt` (rad) |
+| `CelestialBody.GetOrbit(self)` | `Orbit` | (then 8 orbit calls) |
+
+### Per Orbit (8 calls per orbit)
+
+| Procedure | Returns | Field |
+|---|---|---|
+| `Orbit.GetSemiMajorAxis(self)` | `double` | `semiMajorAxis` (m) |
+| `Orbit.GetEccentricity(self)` | `double` | `eccentricity` |
+| `Orbit.GetInclination(self)` | `double` | `inclination` (rad) |
+| `Orbit.GetLongitudeOfAscendingNode(self)` | `double` | `longitudeOfAscendingNode` (rad) |
+| `Orbit.GetArgumentOfPeriapsis(self)` | `double` | `argumentOfPeriapsis` (rad) |
+| `Orbit.GetMeanAnomalyAtEpoch(self)` | `double` | `meanAnomalyAtEpoch` (rad) |
+| `Orbit.GetEpoch(self)` | `double` | `epoch` (s) |
+| `Orbit.GetReferenceBody(self)` | `CelestialBody` (nullable) | (for verification only) |
+
+### Per Vessel (5 calls per vessel)
+
+| Procedure | Returns | Field |
+|---|---|---|
+| `Vessel.GetName(self)` | `string` | `name` |
+| `Vessel.GetType(self)` | `VesselType` (enum) | `type` (resolved to name) |
+| `Vessel.GetSituation(self)` | `VesselSituation` (enum) | `situation` (raw int code) |
+| `Vessel.GetOrbit(self)` | `Orbit` | (then 8 orbit calls) |
+| `Vessel.GetReferenceBody(self)` | `CelestialBody` | `referenceBodyId` (resolved to name) |
+
+## What's NOT in scope yet (deferred work)
+
+- **Streams** — we don't subscribe to kRPC streams yet. We're
+  polling. For a real-time UI, switching to streams (or hybrid
+  poll+stream) would reduce latency and load. kRPC has `AddStream`
+  and the stream port is already wired in.
+- **Batched calls** — every kRPC call is its own request. We could
+  batch multiple `ProcedureCall` entries in a single `Request` for
+  ~10x throughput.
+- **Ground stations** — kRPC doesn't expose ground stations natively.
+  The ksp-bridge accepts them as static config or via mod integration.
+- **Comm nets / signal strength** — needs the `CommNet` API. kRPC
+  has it, but we don't use it yet.
+- **Crew / science** — not in the ksp-bridge scope right now.
+- **Maneuver nodes** — easy to add (`Vessel.GetManeuverNode()` etc.)
+  but not needed for the live map / mission clock.
+
+## Troubleshooting
+
+### `no kRPC server at 127.0.0.1:50000`
+
+Either KSP isn't running, or the kRPC server isn't enabled. Open the
+kRPC window in-game (<kbd>Alt</kbd>+<kbd>F12</kbd>) and make sure
+"Start server" is checked.
+
+### `procedure not found in service cache`
+
+The kRPC server returned a procedure that we don't know about. This
+usually means the kRPC version is older or newer than we expect
+(we target 0.5.x). The ServiceCache will log the procedures it knows
+about; cross-check with the in-game kRPC window.
+
+### `wrong number of arguments`
+
+The procedure signature in the cache doesn't match what we're sending.
+This can happen if the kRPC version has a different parameter order
+or count for a procedure we use. The fix is in
+`apps/tools/ksp-bridge/src/extract.ts` — adjust the call site.

packages/krpc-client/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@kerbal-rt/krpc-client",
+  "version": "0.1.0",
+  "private": true,
+  "description": "TypeScript client for the kRPC protobuf protocol (KSP telemetry bridge)",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'no linter yet'",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsc"
+  },
+  "dependencies": {
+    "protobufjs": "^7.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

packages/krpc-client/src/_test-encode.ts

@@ -0,0 +1,51 @@
+/**
+ * Test-only encoding helpers for the value encoding tests.
+ *
+ * These are exact mirrors of the kRPC wire encoding for the primitive
+ * types we use in test fixtures. Imported by the integration test that
+ * drives a mock kRPC server.
+ *
+ * DO NOT use these in production code; use `encodeValue` from decoder.ts
+ * which dispatches based on the KrpcType descriptor.
+ */
+import { encodeVarint } from './connection.js';
+
+export function encodeDouble(v: number): Uint8Array {
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setFloat64(0, v, true);
+  return out;
+}
+
+export function encodeFloat(v: number): Uint8Array {
+  const out = new Uint8Array(4);
+  new DataView(out.buffer).setFloat32(0, v, true);
+  return out;
+}
+
+export function encodeSint32(v: number): Uint8Array {
+  return encodeVarint(((v << 1) ^ (v >> 31)) >>> 0);
+}
+
+export function encodeUint32(v: number): Uint8Array {
+  return encodeVarint(v);
+}
+
+export function encodeUint64(v: bigint): Uint8Array {
+  const out: number[] = [];
+  let x = v;
+  while (x >= 0x80n) {
+    out.push(Number((x & 0x7fn) | 0x80n));
+    x >>= 7n;
+  }
+  out.push(Number(x));
+  return new Uint8Array(out);
+}
+
+export function encodeString(v: string): Uint8Array {
+  const utf8 = new TextEncoder().encode(v);
+  return Buffer.concat([encodeVarint(utf8.length), Buffer.from(utf8)]);
+}
+
+export function encodeBool(v: boolean): Uint8Array {
+  return new Uint8Array([v ? 1 : 0]);
+}

packages/krpc-client/src/client.ts

@@ -0,0 +1,307 @@
+/**
+ * High-level kRPC client. Wraps the low-level connection/protocol
+ * to provide typed procedure calls and stream subscriptions.
+ *
+ * Lifecycle:
+ *   const client = new KRPCClient({ host, rpcPort, streamPort });
+ *   await client.connect();           // handshake on both ports
+ *   const ut = await client.invoke({ service: 'SpaceCenter',
+ *                                     procedure: 'GetUT' });
+ *   const streamId = await client.addStream({ service: 'SpaceCenter',
+ *                                             procedure: 'GetUT' });
+ *   client.onStreamUpdate((upd) => { ... });
+ *   await client.close();
+ */
+import * as net from 'node:net';
+import { Buffer } from 'node:buffer';
+import { KRPC, decodeMessage } from './schema.js';
+import { sendMessage, recvRawMessage, tcpConnect } from './connection.js';
+
+export interface KRPCClientOptions {
+  host?: string;
+  rpcPort?: number;
+  streamPort?: number;
+  clientName?: string;
+  connectTimeoutMs?: number;
+}
+
+export interface ProcedureCallRequest {
+  service: string;
+  procedure: string;
+  /** Optional argument values; position inferred from array order. */
+  args?: unknown[];
+  /** When set, used as service_id/procedure_id (saves a string lookup). */
+  serviceId?: number;
+  procedureId?: number;
+}
+
+type StreamHandler = (streamId: number, result: Uint8Array) => void;
+export type { StreamHandler };
+
+/**
+ * Format an error value for human consumption. Handles the cases where
+ * the thrown value is null, undefined, a string, or an Error with
+ * .code (NodeJS.ErrnoException). Falls back to JSON.stringify for
+ * unknown shapes.
+ */
+function formatErr(e: unknown): string {
+  if (e === null) return 'null';
+  if (e === undefined) return 'undefined';
+  if (typeof e === 'string') return e;
+  if (typeof e === 'object') {
+    const obj = e as { code?: unknown; message?: unknown; errno?: unknown };
+    const parts: string[] = [];
+    if (typeof obj.code === 'string') parts.push(`code=${obj.code}`);
+    if (typeof obj.errno === 'number') parts.push(`errno=${obj.errno}`);
+    if (typeof obj.message === 'string') parts.push(obj.message);
+    if (parts.length > 0) return parts.join(': ');
+    try {
+      return JSON.stringify(e);
+    } catch {
+      return String(e);
+    }
+  }
+  return String(e);
+}
+
+export class KRPCClient {
+  private opts: Required<KRPCClientOptions>;
+  private rpcSocket: net.Socket | null = null;
+  private streamSocket: net.Socket | null = null;
+  private clientIdentifier: Buffer = Buffer.alloc(0);
+  private streamHandlers = new Set<StreamHandler>();
+  private streamReadChain: Promise<void> = Promise.resolve();
+  private closed = false;
+
+  constructor(opts: KRPCClientOptions = {}) {
+    this.opts = {
+      host: opts.host ?? '127.0.0.1',
+      rpcPort: opts.rpcPort ?? 50000,
+      streamPort: opts.streamPort ?? 50001,
+      clientName: opts.clientName ?? 'kerbal-rt-bridge',
+      connectTimeoutMs: opts.connectTimeoutMs ?? 5000,
+    };
+  }
+
+  async connect(): Promise<void> {
+    // RPC handshake
+    try {
+      this.rpcSocket = await tcpConnect(
+        this.opts.host,
+        this.opts.rpcPort,
+        this.opts.connectTimeoutMs,
+      );
+    } catch (e) {
+      throw new Error(
+        `kRPC RPC TCP connect to ${this.opts.host}:${this.opts.rpcPort} failed: ${formatErr(e)}`,
+      );
+    }
+    // The ConnectionRequest.Type enum has RPC = 0, STREAM = 1. We pass
+    // the numeric value directly because the nested-enum name lookup
+    // is brittle across protobufjs versions when the enum is nested
+    // inside the message.
+    sendMessage(this.rpcSocket, KRPC.ConnectionRequest, {
+      type: 0, // RPC
+      clientName: this.opts.clientName,
+    });
+    let resp: { status: number | string; message: string; clientIdentifier: Uint8Array };
+    try {
+      resp = decodeMessage<{
+        status: number | string;
+        message: string;
+        clientIdentifier: Uint8Array;
+      }>(KRPC.ConnectionResponse, await recvRawMessage(this.rpcSocket));
+    } catch (e) {
+      throw new Error(`kRPC RPC handshake (response decode) failed: ${formatErr(e)}`);
+    }
+    // protobufjs decodes enums to numbers by default; OK == 0
+    if (resp.status !== 'OK' && resp.status !== 0) {
+      throw new Error(`RPC handshake failed: ${resp.status} ${resp.message}`);
+    }
+    this.clientIdentifier = Buffer.from(resp.clientIdentifier);
+
+    // Stream handshake
+    try {
+      this.streamSocket = await tcpConnect(
+        this.opts.host,
+        this.opts.streamPort,
+        this.opts.connectTimeoutMs,
+      );
+    } catch (e) {
+      throw new Error(
+        `kRPC Stream TCP connect to ${this.opts.host}:${this.opts.streamPort} failed: ${formatErr(e)}`,
+      );
+    }
+    sendMessage(this.streamSocket, KRPC.ConnectionRequest, {
+      type: 1, // STREAM
+      clientIdentifier: this.clientIdentifier,
+    });
+    const streamResp = decodeMessage<{ status: number | string; message: string }>(
+      KRPC.ConnectionResponse,
+      await recvRawMessage(this.streamSocket),
+    );
+    if (streamResp.status !== 'OK' && streamResp.status !== 0) {
+      throw new Error(`Stream handshake failed: ${streamResp.status} ${streamResp.message}`);
+    }
+
+    // Start the stream read loop
+    this.streamReadChain = this.readStreamLoop().catch((err) => {
+      // eslint-disable-next-line no-console
+      console.error('[krpc-client] stream loop error:', err);
+    });
+  }
+
+  isConnected(): boolean {
+    return this.rpcSocket !== null && this.streamSocket !== null && !this.closed;
+  }
+
+  /**
+   * Invoke a single procedure. Returns the raw return-value bytes.
+   * Use the .proto schema to decode it.
+   */
+  async invoke(req: ProcedureCallRequest): Promise<Uint8Array> {
+    if (!this.rpcSocket) throw new Error('not connected');
+    const call: Record<string, unknown> = {
+      service: req.service,
+      procedure: req.procedure,
+    };
+    if (req.serviceId !== undefined) call.serviceId = req.serviceId;
+    if (req.procedureId !== undefined) call.procedureId = req.procedureId;
+    if (req.args && req.args.length > 0) {
+      // Each argument must be a serialized protobuf value. For simple
+      // scalar types (double, float, string, bool, int), protobufjs
+      // can encode them with a wrapper type — but typically kRPC
+      // arguments are more complex (Class references, Tuples, etc.)
+      // and the caller must serialize them.
+      // For convenience, we accept already-encoded bytes here.
+      call.arguments = req.args.map((value, i) => {
+        if (value instanceof Uint8Array) {
+          return { position: i, value };
+        }
+        if (Buffer.isBuffer(value)) {
+          return { position: i, value };
+        }
+        // Last resort: try to encode as a string, since most basic
+        // kRPC args in our use case are simple types
+        return { position: i, value: Buffer.from(String(value)) };
+      });
+    }
+    sendMessage(this.rpcSocket, KRPC.Request, { calls: [call] });
+    const raw = await recvRawMessage(this.rpcSocket);
+    const response = decodeMessage<{
+      error?: { service: string; name: string; description: string };
+      results: {
+        error?: { service: string; name: string; description: string };
+        value: Uint8Array;
+      }[];
+    }>(KRPC.Response, raw);
+    if (response.error) {
+      throw new Error(
+        `RPC error: ${response.error.service}.${response.error.name}: ${response.error.description}`,
+      );
+    }
+    if (response.results.length === 0) {
+      throw new Error('empty response');
+    }
+    const r = response.results[0];
+    if (!r) {
+      throw new Error('empty response result');
+    }
+    if (r.error) {
+      throw new Error(
+        `RPC result error: ${r.error.service}.${r.error.name}: ${r.error.description}`,
+      );
+    }
+    return r.value;
+  }
+
+  /**
+   * Subscribe to a procedure. Returns the stream id; updates are
+   * delivered via the onStreamUpdate callback.
+   */
+  async addStream(req: ProcedureCallRequest): Promise<number> {
+    if (!this.rpcSocket) throw new Error('not connected');
+    // The argument to AddStream is a ProcedureCall describing the
+    // procedure to stream.
+    const innerCall: Record<string, unknown> = {
+      service: req.service,
+      procedure: req.procedure,
+    };
+    if (req.serviceId !== undefined) innerCall.serviceId = req.serviceId;
+    if (req.procedureId !== undefined) innerCall.procedureId = req.procedureId;
+    const innerCallBytes = Buffer.from(
+      KRPC.ProcedureCall.encode(KRPC.ProcedureCall.create(innerCall)).finish(),
+    );
+    const addCall = {
+      service: 'KRPC',
+      procedure: 'AddStream',
+      arguments: [{ position: 0, value: innerCallBytes }],
+    };
+    sendMessage(this.rpcSocket, KRPC.Request, { calls: [addCall] });
+    const response = decodeMessage<{
+      results: { value: Uint8Array; error?: { name: string; description: string } }[];
+    }>(KRPC.Response, await recvRawMessage(this.rpcSocket));
+    if (response.results.length === 0) throw new Error('empty AddStream response');
+    const r0 = response.results[0];
+    if (!r0) throw new Error('empty AddStream result');
+    if (r0.error) {
+      throw new Error(`AddStream error: ${r0.error.name}: ${r0.error.description}`);
+    }
+    const stream = decodeMessage<{ id: number }>(KRPC.Stream, r0.value);
+    return stream.id;
+  }
+
+  /** Remove a previously added stream. */
+  async removeStream(streamId: number): Promise<void> {
+    if (!this.rpcSocket) throw new Error('not connected');
+    const streamMsg = KRPC.Stream.create({ id: streamId });
+    const streamBytes = Buffer.from(KRPC.Stream.encode(streamMsg).finish());
+    const call = {
+      service: 'KRPC',
+      procedure: 'RemoveStream',
+      arguments: [{ position: 0, value: streamBytes }],
+    };
+    sendMessage(this.rpcSocket, KRPC.Request, { calls: [call] });
+    await recvRawMessage(this.rpcSocket);
+  }
+
+  /** Register a callback invoked for every stream update. */
+  onStreamUpdate(handler: StreamHandler): () => void {
+    this.streamHandlers.add(handler);
+    return () => this.streamHandlers.delete(handler);
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.rpcSocket) {
+      this.rpcSocket.destroy();
+      this.rpcSocket = null;
+    }
+    if (this.streamSocket) {
+      this.streamSocket.destroy();
+      this.streamSocket = null;
+    }
+    await this.streamReadChain.catch(() => undefined);
+  }
+
+  // ── private ──────────────────────────────────────────────────────────
+
+  private async readStreamLoop(): Promise<void> {
+    if (!this.streamSocket) return;
+    while (!this.closed) {
+      try {
+        const raw = await recvRawMessage(this.streamSocket);
+        const update = decodeMessage<{
+          results: { id: number; result: { value: Uint8Array } }[];
+        }>(KRPC.StreamUpdate, raw);
+        for (const r of update.results) {
+          for (const h of this.streamHandlers) h(r.id, r.result.value);
+        }
+      } catch (err) {
+        if (this.closed) return;
+        throw err;
+      }
+    }
+  }
+}

packages/krpc-client/src/connection.ts

@@ -0,0 +1,182 @@
+/**
+ * KRPC TCP connection — length-prefixed protobuf framing.
+ *
+ * Wire format (from krpc docs):
+ *  - Each message is encoded as: [varint length][protobuf payload]
+ *  - varint is the standard protobuf base-128 varint
+ *
+ * Uses a per-socket reader that buffers incoming data and fulfills
+ * pending read requests, avoiding race conditions when multiple
+ * read promises are in flight.
+ */
+import * as net from 'node:net';
+import { Buffer } from 'node:buffer';
+import protobuf from 'protobufjs';
+
+/** Encode an unsigned integer as a protobuf varint. */
+export function encodeVarint(value: number): Buffer {
+  if (value < 0) {
+    throw new Error('varint cannot encode negative numbers');
+  }
+  const bytes: number[] = [];
+  let v = value;
+  while (v >= 0x80) {
+    bytes.push((v & 0x7f) | 0x80);
+    v = Math.floor(v / 0x80);
+  }
+  bytes.push(v & 0x7f);
+  return Buffer.from(bytes);
+}
+
+/** Decode a protobuf varint from the front of a buffer. Returns [value, bytesConsumed]. */
+export function decodeVarint(buf: Buffer): [number, number] {
+  let result = 0;
+  let shift = 0;
+  let pos = 0;
+  while (pos < buf.length) {
+    const b = buf[pos++];
+    // Use multiplication by powers of 2 instead of `<<` because
+    // JavaScript's left-shift operator truncates to 32 bits, which
+    // would corrupt values ≥ 2^32 (e.g. uint64 stream ids).
+    result += (b & 0x7f) * Math.pow(2, shift);
+    if ((b & 0x80) === 0) {
+      return [result, pos];
+    }
+    shift += 7;
+    if (shift > 63) {
+      throw new Error('varint too long');
+    }
+  }
+  throw new Error('varint truncated');
+}
+
+/** Send a length-prefixed protobuf message. */
+export function sendMessage(
+  socket: net.Socket,
+  type: protobuf.Type,
+  value: Record<string, unknown>,
+): void {
+  const payload = Buffer.from(type.encode(type.create(value)).finish());
+  const prefix = encodeVarint(payload.length);
+  socket.write(Buffer.concat([prefix, payload]));
+}
+
+/**
+ * Per-socket reader. Buffers incoming chunks and resolves pending
+ * read requests. Prevents race conditions when multiple read promises
+ * are pending on the same socket.
+ */
+class SocketReader {
+  private buf: Buffer = Buffer.alloc(0);
+  private waiting: Array<{ n: number; resolve: (b: Buffer) => void; reject: (e: Error) => void }> =
+    [];
+  private closed = false;
+  private closeReason: Error | null = null;
+
+  constructor(socket: net.Socket) {
+    socket.on('data', (chunk: Buffer) => this.onData(chunk));
+    socket.on('error', (err) => this.onClose(err));
+    socket.on('close', () => this.onClose(new Error('socket closed')));
+  }
+
+  read(n: number): Promise<Buffer> {
+    if (this.closed) {
+      return Promise.reject(this.closeReason ?? new Error('socket closed'));
+    }
+    if (this.buf.length >= n) {
+      const out = this.buf.subarray(0, n);
+      this.buf = this.buf.subarray(n);
+      return Promise.resolve(Buffer.from(out));
+    }
+    return new Promise((resolve, reject) => {
+      this.waiting.push({ n, resolve, reject });
+    });
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buf = Buffer.concat([this.buf, chunk]);
+    // Try to satisfy pending reads (in order)
+    let i = 0;
+    while (i < this.waiting.length) {
+      const w = this.waiting[i]!;
+      if (this.buf.length >= w.n) {
+        const out = this.buf.subarray(0, w.n);
+        this.buf = this.buf.subarray(w.n);
+        w.resolve(Buffer.from(out));
+        this.waiting.splice(i, 1);
+      } else {
+        i++;
+      }
+    }
+  }
+
+  private onClose(err: Error): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.closeReason = err;
+    while (this.waiting.length > 0) {
+      const w = this.waiting.shift()!;
+      w.reject(err);
+    }
+  }
+}
+
+const readers = new WeakMap<net.Socket, SocketReader>();
+
+function readerFor(socket: net.Socket): SocketReader {
+  let r = readers.get(socket);
+  if (!r) {
+    r = new SocketReader(socket);
+    readers.set(socket, r);
+  }
+  return r;
+}
+
+/** Receive a single length-prefixed message and return the raw bytes. */
+export async function recvRawMessage(socket: net.Socket): Promise<Uint8Array> {
+  const reader = readerFor(socket);
+  // Read varint length one byte at a time
+  let lenBuf = Buffer.alloc(0);
+  while (true) {
+    const b = await reader.read(1);
+    lenBuf = Buffer.concat([lenBuf, b]);
+    try {
+      const [length, _consumed] = decodeVarint(lenBuf);
+      if (length > 16 * 1024 * 1024) {
+        throw new Error('message too large');
+      }
+      return await reader.read(length);
+    } catch (e) {
+      if ((e as Error).message === 'varint truncated') {
+        continue;
+      }
+      throw e;
+    }
+  }
+}
+
+/** Receive a single length-prefixed message and decode it. */
+export async function recvMessage<T>(socket: net.Socket, type: protobuf.Type): Promise<T> {
+  const payload = await recvRawMessage(socket);
+  return type.decode(payload) as T;
+}
+
+/** Open a TCP connection to a host:port. */
+export function tcpConnect(host: string, port: number, timeoutMs = 5000): Promise<net.Socket> {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ host, port });
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(new Error(`connect timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+    socket.once('connect', () => {
+      clearTimeout(timer);
+      socket.setNoDelay(true);
+      resolve(socket);
+    });
+    socket.once('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}

packages/krpc-client/src/decoder.ts

@@ -0,0 +1,478 @@
+/**
+ * kRPC value decoder.
+ *
+ * kRPC values are encoded on the wire using a hybrid scheme:
+ *
+ *  - For **primitive types** (DOUBLE, FLOAT, SINT32, SINT64, UINT32, UINT64,
+ *    BOOL, STRING, BYTES) the bytes are exactly the standard protobuf wire
+ *    encoding of that single value, NOT wrapped in a message. So a `double`
+ *    is just 8 little-endian bytes, a `string` is `[varint length][utf8]`,
+ *    and so on.
+ *
+ *  - For **CLASS types** the bytes are a single varint-encoded `uint64` —
+ *    the object id. An object id of 0 means `None` (the CLASS is nullable).
+ *    The actual class data lives server-side; to get a property you call
+ *    `Service.ClassName.GetX(id)`.
+ *
+ *  - For **ENUMERATION** the bytes are a single signed varint (zigzag-encoded
+ *    sint32 in protobuf terms).
+ *
+ *  - For **collections** (LIST, SET, TUPLE, DICTIONARY) the bytes are a
+ *    serialized `KRPC.List` / `KRPC.Set` / `KRPC.Tuple` / `KRPC.Dictionary`
+ *    message. Each element is itself encoded using the scheme above (so the
+ *    element bytes are variable-length). A null collection is a single byte
+ *    `\x00` (NOT a length-prefixed empty list).
+ *
+ *  - For **system messages** (STATUS, SERVICES, STREAM, EVENT,
+ *    PROCEDURE_CALL) the bytes are the standard protobuf serialization of
+ *    the corresponding KRPC message.
+ *
+ * Reference: the Python client's `krpc/decoder.py` (Krpc 0.5.x).
+ */
+import protobuf from 'protobufjs';
+import { decodeVarint, encodeVarint } from './connection.js';
+import { TypeCode, type KrpcType, typeName } from './types.js';
+
+/** Result of decoding a value. */
+export type DecodedValue =
+  | number
+  | bigint
+  | boolean
+  | string
+  | Uint8Array
+  | null
+  | DecodedValue[]
+  | Set<DecodedValue>
+  | Map<DecodedValue, DecodedValue>
+  | { [k: string]: unknown };
+
+/**
+ * Decode a value from its wire bytes according to a KrpcType.
+ *
+ * @param type       The KrpcType descriptor (from GetServices or a
+ *                   pre-built cache).
+ * @param data       The raw bytes (response.value for returns, or
+ *                   the value field of a KRPC.Argument for args).
+ * @param messageTypes Optional protobufjs type registry for decoding
+ *                   system messages (KRPC.Status, etc.) by name.
+ *                   Only needed for MESSAGE-style TypeCodes.
+ */
+export function decodeValue(
+  type: KrpcType,
+  data: Uint8Array,
+  messageTypes?: Record<string, protobuf.Type>,
+): DecodedValue {
+  switch (type.code) {
+    case TypeCode.NONE:
+      return null;
+
+    case TypeCode.DOUBLE:
+      return decodeDouble(data);
+    case TypeCode.FLOAT:
+      return decodeFloat(data);
+    case TypeCode.SINT32:
+      return decodeSint32(data);
+    case TypeCode.SINT64:
+      return decodeSint64(data);
+    case TypeCode.UINT32:
+      return decodeUint32(data);
+    case TypeCode.UINT64:
+      return decodeUint64(data);
+    case TypeCode.BOOL:
+      return decodeBool(data);
+    case TypeCode.STRING:
+      return decodeString(data);
+    case TypeCode.BYTES:
+      return decodeBytes(data);
+
+    case TypeCode.CLASS: {
+      // The wire form of a CLASS is a uint64 object id; 0 = None.
+      // We decode as a BigInt so callers can pass the id back as an
+      // argument to other class methods.
+      const id = bigFromVarint(data);
+      return id === 0n ? null : id;
+    }
+
+    case TypeCode.ENUMERATION: {
+      // Wire form: a single signed varint (sint32 in protobuf terms).
+      return decodeSint32(data);
+    }
+
+    case TypeCode.STATUS: {
+      return decodeSystemMessage('Status', data, messageTypes);
+    }
+    case TypeCode.SERVICES: {
+      return decodeSystemMessage('Services', data, messageTypes);
+    }
+    case TypeCode.STREAM: {
+      return decodeSystemMessage('Stream', data, messageTypes);
+    }
+    case TypeCode.EVENT: {
+      return decodeSystemMessage('Event', data, messageTypes);
+    }
+    case TypeCode.PROCEDURE_CALL: {
+      return decodeSystemMessage('ProcedureCall', data, messageTypes);
+    }
+
+    case TypeCode.LIST:
+      return decodeList(type, data, messageTypes);
+    case TypeCode.SET:
+      return decodeSet(type, data, messageTypes);
+    case TypeCode.TUPLE:
+      return decodeTuple(type, data, messageTypes);
+    case TypeCode.DICTIONARY:
+      return decodeDictionary(type, data, messageTypes);
+
+    default:
+      throw new Error(`unknown TypeCode ${type.code} (${typeName(type)})`);
+  }
+}
+
+// ── primitive decoders ──────────────────────────────────────────────────────
+
+/**
+ * Read a fixed-width little-endian IEEE 754 number from a buffer.
+ *
+ * JavaScript's `DataView.getFloat64()` already does the right thing on
+ * little-endian platforms, which Node always is. We still go through
+ * `DataView` so the intent is explicit and the code is portable to
+ * big-endian platforms (if we ever run on one).
+ */
+function readFloatLE(buf: Uint8Array, offset: number, bytes: 4 | 8): number {
+  // Pad short reads with zero bytes. This shouldn't happen in practice,
+  // but it's defensive against a truncated response.
+  if (buf.length < offset + bytes) {
+    const padded = new Uint8Array(bytes);
+    padded.set(buf.subarray(offset, offset + bytes));
+    buf = padded;
+    offset = 0;
+  }
+  const view = new DataView(buf.buffer, buf.byteOffset + offset, bytes);
+  return bytes === 8 ? view.getFloat64(0, true) : view.getFloat32(0, true);
+}
+
+export function decodeDouble(data: Uint8Array): number {
+  return readFloatLE(data, 0, 8);
+}
+
+export function decodeFloat(data: Uint8Array): number {
+  return readFloatLE(data, 0, 4);
+}
+
+export function decodeSint32(data: Uint8Array): number {
+  // Protobuf sint32 is zigzag-encoded. `decodeVarint` returns a regular
+  // varint, so we need the zigzag step too.
+  const [raw] = decodeVarint(Buffer.from(data));
+  return zigzagDecode(Number(raw));
+}
+
+export function decodeSint64(data: Uint8Array): number {
+  // The Python client decodes sint64 to a plain int (BigInt in their
+  // case is a separate branch). For our use case the values we care
+  // about (enum cases) are well within int32 range, so we decode to
+  // a JS number. If you really need full int64, decode to BigInt.
+  return decodeSint32(data);
+}
+
+export function decodeUint32(data: Uint8Array): number {
+  const [v] = decodeVarint(Buffer.from(data));
+  return Number(v);
+}
+
+export function decodeUint64(data: Uint8Array): bigint {
+  // Use BigInt for the 64-bit case. The kRPC ObjectId and StreamId are
+  // uint64s and can exceed Number.MAX_SAFE_INTEGER in principle
+  // (though kRPC never generates ids that large in practice).
+  return bigFromVarint(data);
+}
+
+export function decodeBool(data: Uint8Array): boolean {
+  if (data.length < 1) return false;
+  return data[0] !== 0;
+}
+
+export function decodeString(data: Uint8Array): string {
+  // Wire form: [varint length][utf8 bytes].
+  const buf = Buffer.from(data);
+  const [len, pos] = decodeVarint(buf);
+  return buf.subarray(pos, pos + Number(len)).toString('utf-8');
+}
+
+export function decodeBytes(data: Uint8Array): Uint8Array {
+  const buf = Buffer.from(data);
+  const [len, pos] = decodeVarint(buf);
+  return new Uint8Array(buf.subarray(pos, pos + Number(len)));
+}
+
+function zigzagDecode(n: number): number {
+  return (n >>> 1) ^ -(n & 1);
+}
+
+/**
+ * Decode a varint (assumed ≤ 64 bits) as a BigInt. Used for uint64 values
+ * where the precision loss of Number() is unacceptable.
+ */
+function bigFromVarint(data: Uint8Array): bigint {
+  let result = 0n;
+  let shift = 0n;
+  for (let i = 0; i < data.length; i++) {
+    const b = data[i];
+    if (b === undefined) break;
+    result |= BigInt(b & 0x7f) << shift;
+    if ((b & 0x80) === 0) return result;
+    shift += 7n;
+  }
+  return result;
+}
+
+// ── collection decoders ─────────────────────────────────────────────────────
+
+/**
+ * Decode a KRPC.List message (when its serialized form is provided).
+ * Used internally by `decodeList`. Also exported for tests.
+ */
+export function decodeKrpcList(
+  data: Uint8Array,
+  messageType: protobuf.Type,
+): Uint8Array[] {
+  if (data.length === 1 && data[0] === 0) {
+    // A list may be serialized as a single 0x00 byte to indicate None.
+    return [];
+  }
+  const msg = messageType.decode(data) as unknown as { items: Uint8Array[] };
+  return msg.items ?? [];
+}
+
+export function decodeList(
+  type: KrpcType,
+  data: Uint8Array,
+  messageTypes?: Record<string, protobuf.Type>,
+): DecodedValue[] {
+  if (data.length === 1 && data[0] === 0) return null as unknown as DecodedValue[];
+  const listType = messageTypes?.['List'];
+  if (!listType) {
+    throw new Error('decodeList: no protobufjs type for KRPC.List registered');
+  }
+  const items = decodeKrpcList(data, listType);
+  const elemType = type.types[0];
+  if (!elemType) throw new Error('LIST type missing element type');
+  return items.map((it) => decodeValue(elemType, it, messageTypes));
+}
+
+export function decodeSet(
+  type: KrpcType,
+  data: Uint8Array,
+  messageTypes?: Record<string, protobuf.Type>,
+): Set<DecodedValue> {
+  if (data.length === 1 && data[0] === 0) return null as unknown as Set<DecodedValue>;
+  const setType = messageTypes?.['Set'];
+  if (!setType) {
+    throw new Error('decodeSet: no protobufjs type for KRPC.Set registered');
+  }
+  const msg = setType.decode(data) as unknown as { items: Uint8Array[] };
+  const elemType = type.types[0];
+  if (!elemType) throw new Error('SET type missing element type');
+  return new Set((msg.items ?? []).map((it) => decodeValue(elemType, it, messageTypes)));
+}
+
+export function decodeTuple(
+  type: KrpcType,
+  data: Uint8Array,
+  messageTypes?: Record<string, protobuf.Type>,
+): DecodedValue[] {
+  if (data.length === 1 && data[0] === 0) return null as unknown as DecodedValue[];
+  const tupleType = messageTypes?.['Tuple'];
+  if (!tupleType) {
+    throw new Error('decodeTuple: no protobufjs type for KRPC.Tuple registered');
+  }
+  const msg = tupleType.decode(data) as unknown as { items: Uint8Array[] };
+  return type.types.map((inner, i) =>
+    decodeValue(inner, msg.items[i] ?? new Uint8Array(0), messageTypes),
+  );
+}
+
+export function decodeDictionary(
+  type: KrpcType,
+  data: Uint8Array,
+  messageTypes?: Record<string, protobuf.Type>,
+): Map<DecodedValue, DecodedValue> {
+  if (data.length === 1 && data[0] === 0) {
+    return null as unknown as Map<DecodedValue, DecodedValue>;
+  }
+  const dictType = messageTypes?.['Dictionary'];
+  if (!dictType) {
+    throw new Error('decodeDictionary: no protobufjs type for KRPC.Dictionary registered');
+  }
+  const msg = dictType.decode(data) as unknown as {
+    entries: { key: Uint8Array; value: Uint8Array }[];
+  };
+  const keyType = type.types[0];
+  const valType = type.types[1];
+  if (!keyType || !valType) throw new Error('DICTIONARY type missing key/value types');
+  const out = new Map<DecodedValue, DecodedValue>();
+  for (const e of msg.entries ?? []) {
+    out.set(
+      decodeValue(keyType, e.key, messageTypes),
+      decodeValue(valType, e.value, messageTypes),
+    );
+  }
+  return out;
+}
+
+function decodeSystemMessage(
+  name: string,
+  data: Uint8Array,
+  messageTypes?: Record<string, protobuf.Type>,
+): { [k: string]: unknown } {
+  const t = messageTypes?.[name];
+  if (!t) throw new Error(`decodeSystemMessage: no type registered for ${name}`);
+  return t.decode(data) as unknown as { [k: string]: unknown };
+}
+
+// ── encoders (mirrors, for sending arguments) ───────────────────────────────
+
+/**
+ * Encode a value into the kRPC wire format for `type`.
+ *
+ * This is the inverse of `decodeValue`. Used by the service client to
+ * serialize procedure arguments. Collections and system messages use the
+ * protobufjs registry the same way the decoder does.
+ */
+export function encodeValue(
+  type: KrpcType,
+  value: DecodedValue,
+  messageTypes?: Record<string, protobuf.Type>,
+): Uint8Array {
+  switch (type.code) {
+    case TypeCode.NONE:
+      return new Uint8Array(0);
+    case TypeCode.DOUBLE:
+      return encodeDouble(value as number);
+    case TypeCode.FLOAT:
+      return encodeFloat(value as number);
+    case TypeCode.SINT32:
+      return encodeSint32(value as number);
+    case TypeCode.SINT64:
+      return encodeSint32(value as number);
+    case TypeCode.UINT32:
+      return encodeUint32(value as number);
+    case TypeCode.UINT64:
+      return encodeUint64(value as bigint);
+    case TypeCode.BOOL:
+      return encodeBool(value as boolean);
+    case TypeCode.STRING:
+      return encodeString(value as string);
+    case TypeCode.BYTES:
+      return encodeBytes(value as Uint8Array);
+
+    case TypeCode.CLASS: {
+      // CLASS args are encoded as uint64 object id; null = 0.
+      if (value === null || value === undefined) return encodeUint64(0n);
+      if (typeof value === 'bigint') return encodeUint64(value);
+      if (typeof value === 'number') return encodeUint64(BigInt(value));
+      throw new Error(`encodeValue: CLASS expects bigint object id, got ${typeof value}`);
+    }
+
+    case TypeCode.ENUMERATION:
+      return encodeSint32(value as number);
+
+    case TypeCode.LIST: {
+      const listType = messageTypes?.['List'];
+      if (!listType) throw new Error('encodeValue: no type for KRPC.List');
+      const elemType = type.types[0];
+      if (!elemType) throw new Error('LIST type missing element type');
+      const items = (value as DecodedValue[]).map((v) => encodeValue(elemType, v, messageTypes));
+      const msg = listType.create({ items });
+      return listType.encode(msg).finish();
+    }
+    case TypeCode.TUPLE: {
+      const tupleType = messageTypes?.['Tuple'];
+      if (!tupleType) throw new Error('encodeValue: no type for KRPC.Tuple');
+      const items = (value as DecodedValue[]).map((v, i) =>
+        encodeValue(type.types[i] as KrpcType, v, messageTypes),
+      );
+      const msg = tupleType.create({ items });
+      return tupleType.encode(msg).finish();
+    }
+    case TypeCode.DICTIONARY: {
+      const dictType = messageTypes?.['Dictionary'];
+      if (!dictType) throw new Error('encodeValue: no type for KRPC.Dictionary');
+      const keyType = type.types[0];
+      const valType = type.types[1];
+      if (!keyType || !valType) throw new Error('DICTIONARY type missing key/value types');
+      const entries: { key: Uint8Array; value: Uint8Array }[] = [];
+      for (const [k, v] of (value as Map<DecodedValue, DecodedValue>).entries()) {
+        entries.push({
+          key: encodeValue(keyType, k, messageTypes),
+          value: encodeValue(valType, v, messageTypes),
+        });
+      }
+      const msg = dictType.create({ entries });
+      return dictType.encode(msg).finish();
+    }
+    case TypeCode.SET: {
+      // kRPC 0.5 doesn't really use SET much; if needed we'd encode as
+      // KRPC.Set. For now, only LIST/TUPLE/DICT are exercised by our
+      // SpaceCenter calls.
+      throw new Error('encodeValue: SET not implemented (kRPC 0.5 does not use it)');
+    }
+    case TypeCode.STATUS:
+    case TypeCode.SERVICES:
+    case TypeCode.STREAM:
+    case TypeCode.EVENT:
+    case TypeCode.PROCEDURE_CALL:
+      throw new Error(`encodeValue: system message ${typeName(type)} cannot be sent as argument`);
+
+    default:
+      throw new Error(`encodeValue: unknown TypeCode ${type.code}`);
+  }
+}
+
+function encodeDouble(v: number): Uint8Array {
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setFloat64(0, v, true);
+  return out;
+}
+
+function encodeFloat(v: number): Uint8Array {
+  const out = new Uint8Array(4);
+  new DataView(out.buffer).setFloat32(0, v, true);
+  return out;
+}
+
+function encodeSint32(v: number): Uint8Array {
+  return encodeVarint(zigzagEncode(v));
+}
+
+function encodeUint32(v: number): Uint8Array {
+  return encodeVarint(v);
+}
+
+function encodeUint64(v: bigint): Uint8Array {
+  // Manual varint encoding for BigInt to avoid Number truncation.
+  const out: number[] = [];
+  let x = v;
+  while (x >= 0x80n) {
+    out.push(Number((x & 0x7fn) | 0x80n));
+    x >>= 7n;
+  }
+  out.push(Number(x));
+  return new Uint8Array(out);
+}
+
+function encodeBool(v: boolean): Uint8Array {
+  return new Uint8Array([v ? 1 : 0]);
+}
+
+function encodeString(v: string): Uint8Array {
+  const utf8 = new TextEncoder().encode(v);
+  return Buffer.concat([encodeVarint(utf8.length), Buffer.from(utf8)]);
+}
+
+function encodeBytes(v: Uint8Array): Uint8Array {
+  return Buffer.concat([encodeVarint(v.length), Buffer.from(v)]);
+}
+
+function zigzagEncode(n: number): number {
+  return (n << 1) ^ (n >> 31);
+}

packages/krpc-client/src/index.ts

@@ -0,0 +1,58 @@
+/**
+ * @kerbal-rt/krpc-client — TypeScript client for the kRPC protobuf
+ * protocol used by the Kerbal Space Program kRPC mod.
+ *
+ * Provides:
+ *  - KRPCClient: high-level wrapper with connect/invoke/addStream/close
+ *  - sendMessage / recvMessage / recvRawMessage / encodeVarint / decodeVarint:
+ *    low-level wire-format helpers
+ *  - KRPC namespace: protobufjs types for the kRPC meta-protocol
+ *  - KrpcType / TypeCode: runtime representation of kRPC type descriptors
+ *  - decodeValue / encodeValue: kRPC value codec (primitives, classes,
+ *    enums, collections, system messages)
+ *  - ServiceCache: a Type index built from KRPC.GetServices()
+ *  - KrpcServices: high-level invoke-by-name client
+ *
+ * For the service-specific types (SpaceCenter.Vessel, Orbit, etc.) we do
+ * NOT need to load the kRPC mod's .proto files. The server's
+ * GetServices() response contains everything we need to encode/decode
+ * values. See ./service-client.ts for the details.
+ */
+export {
+  KRPCClient,
+  type ProcedureCallRequest,
+  type KRPCClientOptions,
+  type StreamHandler,
+} from './client.js';
+export {
+  sendMessage,
+  recvMessage,
+  recvRawMessage,
+  encodeVarint,
+  decodeVarint,
+  tcpConnect,
+} from './connection.js';
+export { KRPC, encodeMessage, decodeMessage, MESSAGE_TYPES } from './schema.js';
+export {
+  TypeCode,
+  decodeKrpcType,
+  typeName,
+  type KrpcType,
+  type TypeCodeValue,
+  type RawKrpcTypeMessage,
+} from './types.js';
+export {
+  decodeValue,
+  encodeValue,
+  decodeDouble,
+  decodeFloat,
+  decodeSint32,
+  decodeUint32,
+  decodeUint64,
+  decodeBool,
+  decodeString,
+  decodeBytes,
+  type DecodedValue,
+} from './decoder.js';
+export { ServiceCache } from './services.js';
+export { KrpcServices, loadServices, type KrpcInvokeError } from './service-client.js';

packages/krpc-client/src/schema.ts

@@ -0,0 +1,337 @@
+/**
+ * kRPC meta-protocol schema (krpc.proto).
+ *
+ * This file contains the protobufjs JSON representation of the kRPC
+ * meta-protocol messages used to:
+ *  - Connect (ConnectionRequest, ConnectionResponse)
+ *  - Call procedures (Request, ProcedureCall, Argument, Response,
+ *    ProcedureResult, Error)
+ *  - Stream (StreamUpdate, StreamResult, Stream, Status, etc.)
+ *
+ * For SpaceCenter.Vessel/Orbit/CelestialBody types, see ./spacecenter.ts
+ * — those are loaded dynamically from the kRPC mod's .proto files
+ * when running against a real KSP instance.
+ */
+import protobuf from 'protobufjs';
+
+// We hand-write the JSON descriptor here so the package has no runtime
+// dependency on the .proto files (which ship inside the kRPC mod).
+// This is the minimum subset we need for the bridge to function.
+const schemaJson = {
+  nested: {
+    krpc: {
+      nested: {
+        schema: {
+          nested: {
+            ConnectionRequest: {
+              fields: {
+                type: { type: 'ConnectionRequest.Type', id: 1 },
+                clientName: { type: 'string', id: 2 },
+                clientIdentifier: { type: 'bytes', id: 3 },
+              },
+              nested: {
+                Type: {
+                  values: { RPC: 0, STREAM: 1 },
+                },
+              },
+            },
+            ConnectionResponse: {
+              fields: {
+                status: { type: 'ConnectionResponse.Status', id: 1 },
+                message: { type: 'string', id: 2 },
+                clientIdentifier: { type: 'bytes', id: 3 },
+              },
+              nested: {
+                Status: {
+                  values: {
+                    OK: 0,
+                    MALFORMED_MESSAGE: 1,
+                    TIMEOUT: 2,
+                    WRONG_TYPE: 3,
+                  },
+                },
+              },
+            },
+            Request: {
+              fields: {
+                calls: { rule: 'repeated', type: 'ProcedureCall', id: 1 },
+              },
+            },
+            Response: {
+              fields: {
+                error: { type: 'Error', id: 1 },
+                results: { rule: 'repeated', type: 'ProcedureResult', id: 2 },
+              },
+            },
+            ProcedureCall: {
+              fields: {
+                service: { type: 'string', id: 1 },
+                procedure: { type: 'string', id: 2 },
+                arguments: { rule: 'repeated', type: 'Argument', id: 3 },
+                serviceId: { type: 'uint32', id: 4 },
+                procedureId: { type: 'uint32', id: 5 },
+              },
+            },
+            Argument: {
+              fields: {
+                position: { type: 'uint32', id: 1 },
+                value: { type: 'bytes', id: 2 },
+              },
+            },
+            ProcedureResult: {
+              fields: {
+                error: { type: 'Error', id: 1 },
+                value: { type: 'bytes', id: 2 },
+              },
+            },
+            Error: {
+              fields: {
+                service: { type: 'string', id: 1 },
+                name: { type: 'string', id: 2 },
+                description: { type: 'string', id: 3 },
+                stackTrace: { type: 'string', id: 4 },
+              },
+            },
+            StreamUpdate: {
+              fields: {
+                results: { rule: 'repeated', type: 'StreamResult', id: 1 },
+              },
+            },
+            StreamResult: {
+              fields: {
+                id: { type: 'uint64', id: 1 },
+                result: { type: 'ProcedureResult', id: 2 },
+              },
+            },
+            Stream: {
+              fields: { id: { type: 'uint64', id: 1 } },
+            },
+            Status: {
+              fields: {
+                version: { type: 'string', id: 1 },
+                bytesRead: { type: 'uint64', id: 2 },
+                bytesWritten: { type: 'uint64', id: 3 },
+                bytesReadRate: { type: 'float', id: 4 },
+                bytesWrittenRate: { type: 'float', id: 5 },
+                rpcsExecuted: { type: 'uint64', id: 6 },
+                rpcRate: { type: 'float', id: 7 },
+                oneRpcPerUpdate: { type: 'bool', id: 8 },
+                maxTimePerUpdate: { type: 'uint32', id: 9 },
+                adaptiveRateControl: { type: 'bool', id: 10 },
+                blockingRecv: { type: 'bool', id: 11 },
+                recvTimeout: { type: 'uint32', id: 12 },
+                timePerRpcUpdate: { type: 'float', id: 13 },
+                pollTimePerRpcUpdate: { type: 'float', id: 14 },
+                execTimePerRpcUpdate: { type: 'float', id: 15 },
+                streamRpcs: { type: 'uint32', id: 16 },
+                streamRpcsExecuted: { type: 'uint64', id: 17 },
+                streamRpcRate: { type: 'float', id: 18 },
+                timePerStreamUpdate: { type: 'float', id: 19 },
+              },
+            },
+            Services: {
+              fields: {
+                services: { rule: 'repeated', type: 'Service', id: 1 },
+              },
+            },
+            Service: {
+              fields: {
+                name: { type: 'string', id: 1 },
+                procedures: { rule: 'repeated', type: 'Procedure', id: 2 },
+                classes: { rule: 'repeated', type: 'Class', id: 3 },
+                enumerations: { rule: 'repeated', type: 'Enumeration', id: 4 },
+                exceptions: { rule: 'repeated', type: 'Exception', id: 5 },
+                documentation: { type: 'string', id: 6 },
+              },
+            },
+            Procedure: {
+              fields: {
+                name: { type: 'string', id: 1 },
+                parameters: { rule: 'repeated', type: 'Parameter', id: 2 },
+                returnType: { type: 'Type', id: 3 },
+                returnIsNullable: { type: 'bool', id: 4 },
+                documentation: { type: 'string', id: 5 },
+              },
+            },
+            Parameter: {
+              fields: {
+                name: { type: 'string', id: 1 },
+                type: { type: 'Type', id: 2 },
+                defaultValue: { type: 'bytes', id: 3 },
+                nullable: { type: 'bool', id: 4 },
+              },
+            },
+            Class: {
+              fields: {
+                name: { type: 'string', id: 1 },
+                documentation: { type: 'string', id: 2 },
+              },
+            },
+            Enumeration: {
+              fields: {
+                name: { type: 'string', id: 1 },
+                values: { rule: 'repeated', type: 'EnumerationValue', id: 2 },
+                documentation: { type: 'string', id: 3 },
+              },
+            },
+            EnumerationValue: {
+              fields: {
+                name: { type: 'string', id: 1 },
+                value: { type: 'int32', id: 2 },
+                documentation: { type: 'string', id: 3 },
+              },
+            },
+            Exception: {
+              fields: {
+                name: { type: 'string', id: 1 },
+                documentation: { type: 'string', id: 2 },
+              },
+            },
+            Type: {
+              fields: {
+                code: { type: 'Type.TypeCode', id: 1 },
+                service: { type: 'string', id: 2 },
+                name: { type: 'string', id: 3 },
+                types: { rule: 'repeated', type: 'Type', id: 4 },
+              },
+              nested: {
+                TypeCode: {
+                  values: {
+                    NONE: 0,
+                    DOUBLE: 1,
+                    FLOAT: 2,
+                    SINT32: 3,
+                    SINT64: 4,
+                    UINT32: 5,
+                    UINT64: 6,
+                    BOOL: 7,
+                    STRING: 8,
+                    BYTES: 9,
+                    CLASS: 100,
+                    ENUMERATION: 101,
+                    EVENT: 200,
+                    PROCEDURE_CALL: 201,
+                    STREAM: 202,
+                    STATUS: 203,
+                    SERVICES: 204,
+                    TUPLE: 300,
+                    LIST: 301,
+                    SET: 302,
+                    DICTIONARY: 303,
+                  },
+                },
+              },
+            },
+            Tuple: {
+              fields: { items: { rule: 'repeated', type: 'bytes', id: 1 } },
+            },
+            List: {
+              fields: { items: { rule: 'repeated', type: 'bytes', id: 1 } },
+            },
+            Set: {
+              fields: { items: { rule: 'repeated', type: 'bytes', id: 1 } },
+            },
+            Dictionary: {
+              fields: {
+                entries: { rule: 'repeated', type: 'DictionaryEntry', id: 1 },
+              },
+            },
+            DictionaryEntry: {
+              fields: {
+                key: { type: 'bytes', id: 1 },
+                value: { type: 'bytes', id: 2 },
+              },
+            },
+            Event: {
+              fields: { stream: { type: 'Stream', id: 1 } },
+            },
+            Expression: {
+              fields: {
+                typ: { type: 'Type', id: 1 },
+                code: { type: 'string', id: 2 },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
+const root = protobuf.Root.fromJSON(schemaJson as protobuf.INamespace);
+const ns = root.lookup('krpc.schema') as protobuf.Namespace;
+const lookupType = (name: string): protobuf.Type =>
+  ns.lookupType(name) as protobuf.Type;
+
+/**
+ * All kRPC meta-protocol types, by their protobufjs Type objects.
+ *
+ * These are used by the decoder/encoder for system messages (Status,
+ * Services, Stream, Event, ProcedureCall) and collection types
+ * (List, Set, Tuple, Dictionary).
+ *
+ * The same Type objects are also exposed as `MESSAGE_TYPES` so the
+ * service client can register them with the decoder in one call.
+ *
+ * GOTCHA: protobufjs's nested-enum string-to-number lookup is brittle
+ * when the enum shares its name with a built-in JavaScript type or
+ * with a parent property. In particular, sending
+ *   encodeMessage(ConnectionRequest, { type: 'STREAM' })
+ * silently encodes as 0 (RPC) instead of 1. To avoid this, encode
+ * enum values by their numeric code rather than the string name.
+ */
+export const KRPC = {
+  ConnectionRequest: lookupType('ConnectionRequest'),
+  ConnectionResponse: lookupType('ConnectionResponse'),
+  Request: lookupType('Request'),
+  Response: lookupType('Response'),
+  ProcedureCall: lookupType('ProcedureCall'),
+  Argument: lookupType('Argument'),
+  ProcedureResult: lookupType('ProcedureResult'),
+  Error: lookupType('Error'),
+  StreamUpdate: lookupType('StreamUpdate'),
+  StreamResult: lookupType('StreamResult'),
+  Stream: lookupType('Stream'),
+  Status: lookupType('Status'),
+  Services: lookupType('Services'),
+  Service: lookupType('Service'),
+  Type: lookupType('Type'),
+  List: lookupType('List'),
+  Set: lookupType('Set'),
+  Tuple: lookupType('Tuple'),
+  Dictionary: lookupType('Dictionary'),
+  DictionaryEntry: lookupType('DictionaryEntry'),
+  Event: lookupType('Event'),
+  Expression: lookupType('Expression'),
+} as const;
+
+/**
+ * A name → protobufjs Type registry for system messages and collection
+ * types. The decoder/encoder accepts this as the `messageTypes` argument
+ * so it knows how to (de)serialize these specific messages.
+ */
+export const MESSAGE_TYPES: Record<string, protobuf.Type> = {
+  List: KRPC.List,
+  Set: KRPC.Set,
+  Tuple: KRPC.Tuple,
+  Dictionary: KRPC.Dictionary,
+  Status: KRPC.Status,
+  Services: KRPC.Services,
+  Stream: KRPC.Stream,
+  Event: KRPC.Event,
+  ProcedureCall: KRPC.ProcedureCall,
+};
+
+// Silence "type not used" — we keep the root reference for diagnostics
+// and to allow callers to load additional .proto files later if needed.
+void root;
+
+/** Encode a length-prefixed protobuf message. */
+export function encodeMessage(type: protobuf.Type, value: Record<string, unknown>): Buffer {
+  return Buffer.from(type.encode(type.create(value)).finish());
+}
+
+/** Decode a length-prefixed protobuf message. */
+export function decodeMessage<T>(type: protobuf.Type, buf: Uint8Array): T {
+  return type.decode(buf) as T;
+}

packages/krpc-client/src/service-client.ts

@@ -0,0 +1,196 @@
+/**
+ * KrpcServices — high-level service client.
+ *
+ * Wraps KRPCClient + ServiceCache to provide a clean invoke-by-name API:
+ *
+ *   const sc = new KrpcServices(client, cache);
+ *   const ut = await sc.invoke<number>('SpaceCenter', 'GetUT');
+ *   const bodyIds = await sc.invoke<bigint[]>('SpaceCenter', 'GetBodies');
+ *   const name = await sc.invoke<string>('SpaceCenter', 'CelestialBody.GetName', bodyId);
+ *
+ * The client looks up the procedure in the cache, encodes each argument
+ * using the procedure's parameter types, calls the procedure via the
+ * low-level client, then decodes the response using the return type.
+ *
+ * For class-returning procedures, the response is decoded as the object
+ * id (a BigInt), or `null` if the server returned id=0. The caller can
+ * then pass that BigInt to other class methods.
+ *
+ * This design means we don't need the kRPC mod's .proto files at all —
+ * the kRPC server provides the type information via GetServices(), and
+ * the kRPC value encoding is what our decoder handles.
+ */
+import type { KRPCClient, ProcedureCallRequest } from './client.js';
+import { decodeValue, encodeValue, type DecodedValue } from './decoder.js';
+import { MESSAGE_TYPES, KRPC, decodeMessage } from './schema.js';
+import type { KrpcType } from './types.js';
+import { ServiceCache, type RawServicesMessage } from './services.js';
+
+export interface KrpcInvokeError extends Error {
+  service: string;
+  name: string;
+  description: string;
+  stackTrace?: string;
+}
+
+/** Build a KrpcInvokeError with extra metadata attached. */
+function makeInvokeError(
+  service: string,
+  name: string,
+  description: string,
+  stackTrace?: string,
+): KrpcInvokeError {
+  const e = new Error(`${service}.${name}: ${description}`) as KrpcInvokeError;
+  e.service = service;
+  e.name = name;
+  e.description = description;
+  if (stackTrace) e.stackTrace = stackTrace;
+  return e;
+}
+
+export class KrpcServices {
+  constructor(
+    private readonly client: KRPCClient,
+    private readonly cache: ServiceCache,
+  ) {}
+
+  /**
+   * Invoke a procedure and return the decoded value.
+   *
+   * @param service e.g. "SpaceCenter"
+   * @param procedure e.g. "GetUT" or "CelestialBody.GetName" for class methods
+   * @param args The procedure arguments. Each is encoded according to the
+   *             procedure's parameter types (looked up from the cache).
+   *             Object ids for CLASS parameters are BigInts.
+   */
+  async invoke<T extends DecodedValue = DecodedValue>(
+    service: string,
+    procedure: string,
+    ...args: DecodedValue[]
+  ): Promise<T> {
+    const lookup = this.cache.lookup(service, procedure);
+    if (!lookup.found) {
+      throw makeInvokeError(
+        service,
+        procedure,
+        `procedure not found in service cache (known services: ${this.cache.serviceNames().join(', ')})`,
+      );
+    }
+    const info = lookup.info;
+    if (args.length !== info.parameters.length) {
+      throw makeInvokeError(
+        service,
+        procedure,
+        `wrong number of arguments: expected ${info.parameters.length}, got ${args.length}`,
+      );
+    }
+    const encodedArgs = info.parameters.map((p, i) => {
+      const v = args[i];
+      // For nullable CLASS parameters, accept `null`/`undefined` and encode as id=0.
+      if (p.nullable && (v === null || v === undefined)) {
+        return new Uint8Array(0);
+      }
+      return encodeValue(p.type, v, MESSAGE_TYPES);
+    });
+    // Low-level invoke needs Uint8Array values for each argument.
+    const req: ProcedureCallRequest = {
+      service: info.service,
+      procedure: info.name,
+      args: encodedArgs,
+    };
+    let rawValue: Uint8Array;
+    try {
+      rawValue = await this.client.invoke(req);
+    } catch (err) {
+      // The low-level client throws with a generic message; we wrap it
+      // with the service.procedure prefix so the caller knows which call
+      // failed. The original error is on the `cause` chain in newer
+      // Node, but to keep things simple we re-throw a tagged error.
+      const e = err as Error;
+      throw makeInvokeError(service, procedure, e.message, e.stack);
+    }
+    if (rawValue.length === 0) {
+      // Zero-length response. Only valid for:
+      //   - procedures with no return value (KrpcType NONE)
+      //   - nullable CLASS with id=0 — but that is 1 byte (0x00), not 0
+      // So we return null if the return type is NONE or nullable,
+      // otherwise throw.
+      if (info.returnType.code === 0 /* NONE */) {
+        return null as unknown as T;
+      }
+      if (info.returnIsNullable) {
+        return null as unknown as T;
+      }
+      throw makeInvokeError(
+        service,
+        procedure,
+        'zero-length response for non-nullable, non-NONE return type',
+      );
+    }
+    const decoded = decodeValue(info.returnType, rawValue, MESSAGE_TYPES);
+    if (decoded === null && !info.returnIsNullable) {
+      // Some primitives (e.g. uint64 = 0) might decode to falsy values
+      // that we don't want to confuse with null. But for CLASS/ENUM this
+      // is a real "no value" — and only valid for nullable returns.
+      throw makeInvokeError(
+        service,
+        procedure,
+        'decoded null for non-nullable return type',
+      );
+    }
+    return decoded as T;
+  }
+
+  /**
+   * Read a class property by calling its getter procedure. Equivalent to
+   *   invoke(service, "ClassName.GetPropName", objectId)
+   * but reads more naturally at the call site.
+   */
+  async getClassProperty<T extends DecodedValue = DecodedValue>(
+    service: string,
+    className: string,
+    propertyName: string,
+    objectId: bigint | null,
+  ): Promise<T> {
+    return this.invoke<T>(service, `${className}.${propertyName}`, objectId as DecodedValue);
+  }
+
+  /**
+   * Underlying service cache, exposed for callers that want to do
+   * procedural introspection (e.g. debug tools that list available
+   * services or resolve enum values).
+   */
+  getCache(): ServiceCache {
+    return this.cache;
+  }
+}
+
+/**
+ * Build a ServiceCache from a fresh KRPCClient. Convenience for the
+ * common "connect, get services, return ready client" pattern.
+ *
+ * The return value of `KRPC.GetServices()` is a serialized
+ * `KRPC.Services` message. We decode it using our protobufjs type
+ * definition, then convert the result to a `ServiceCache`.
+ */
+export async function loadServices(client: KRPCClient): Promise<{
+  cache: ServiceCache;
+  services: KrpcServices;
+}> {
+  const rawValue = await client.invoke({
+    service: 'KRPC',
+    procedure: 'GetServices',
+  });
+  // KRPC.Services is a system message — decode it using the
+  // registered protobufjs type.
+  const decoded = decodeMessage<RawServicesMessage>(KRPC.Services, rawValue);
+  // protobufjs decodes `services` field as a repeated Service; each
+  // Service has nested messages for Class, Enumeration, etc. that
+  // protobufjs also decodes. The shape matches our RawServicesMessage
+  // contract — but TypeScript doesn't know that, so we cast.
+  const cache = new ServiceCache(decoded);
+  return { cache, services: new KrpcServices(client, cache) };
+}
+
+/** Re-export for consumers that want to import KrpcType. */
+export type { KrpcType };

packages/krpc-client/src/services.ts

@@ -0,0 +1,198 @@
+/**
+ * ServiceCache — a queryable index over a KRPC.GetServices() response.
+ *
+ * After connecting to kRPC, the canonical first call is `KRPC.GetServices()`,
+ * which returns a `KRPC.Services` message describing every service, every
+ * class, every enum, and every procedure. We decode that into a lookup
+ * table keyed by (service, procedure) so the service client can ask:
+ *
+ *   - "what is the return type of SpaceCenter.GetBodies?"
+ *   - "what are the param types of SpaceCenter.CelestialBody.GetName?"
+ *   - "is SpaceCenter.VesselType.Ship == 0?"
+ *
+ * The cache is built once after connect, then read-only. It is decoupled
+ * from the network so it can be unit-tested by feeding in a hand-crafted
+ * Services message.
+ */
+import {
+  decodeKrpcType,
+  type KrpcType,
+  type RawKrpcTypeMessage,
+} from './types.js';
+
+/** Shape of the KRPC.GetServices() response after protobufjs decoding. */
+export interface RawServicesMessage {
+  services: RawServiceMessage[];
+}
+
+export interface RawServiceMessage {
+  name: string;
+  procedures: RawProcedureMessage[];
+  classes: { name: string }[];
+  enumerations: RawEnumerationMessage[];
+}
+
+export interface RawProcedureMessage {
+  name: string;
+  parameters: RawParameterMessage[];
+  returnType: RawKrpcTypeMessage;
+  returnIsNullable: boolean;
+}
+
+export interface RawParameterMessage {
+  name: string;
+  type: RawKrpcTypeMessage;
+  nullable: boolean;
+}
+
+export interface RawEnumerationMessage {
+  name: string;
+  values: { name: string; value: number }[];
+}
+
+export interface ProcedureInfo {
+  service: string;
+  name: string;
+  /** Full procedure name with class prefix, e.g. `CelestialBody.GetName`. */
+  fullName: string;
+  returnType: KrpcType;
+  returnIsNullable: boolean;
+  parameters: { name: string; type: KrpcType; nullable: boolean }[];
+}
+
+/**
+ * Result of a name lookup. Either we found the proc and we know its
+ * signature, or we didn't and the caller can decide what to do.
+ */
+export type ProcedureLookup =
+  | { found: true; info: ProcedureInfo }
+  | { found: false };
+
+export class ServiceCache {
+  /** "SpaceCenter.CelestialBody.GetName" -> ProcedureInfo */
+  private byFullName = new Map<string, ProcedureInfo>();
+  /** "SpaceCenter" -> "SpaceCenter" (just the service name) */
+  private services = new Set<string>();
+  /** "SpaceCenter.VesselType" -> "Ship" (enum name) -> int value */
+  private enumValues = new Map<string, Map<string, number>>();
+  /** "SpaceCenter" -> "VesselType" (enum name) -> Map<name, value> */
+  private enumsByService = new Map<string, Map<string, Map<string, number>>>();
+
+  constructor(raw: RawServicesMessage) {
+    for (const svc of raw.services ?? []) {
+      this.services.add(svc.name);
+      for (const proc of svc.procedures ?? []) {
+        // proc.name already includes the class prefix when applicable
+        // (e.g. "CelestialBody.GetName"), per the kRPC wire format.
+        const info: ProcedureInfo = {
+          service: svc.name,
+          name: proc.name,
+          fullName: `${svc.name}.${proc.name}`,
+          returnType: decodeKrpcType(proc.returnType),
+          returnIsNullable: !!proc.returnIsNullable,
+          parameters: (proc.parameters ?? []).map((p) => ({
+            name: p.name,
+            type: decodeKrpcType(p.type),
+            nullable: !!p.nullable,
+          })),
+        };
+        this.byFullName.set(info.fullName, info);
+      }
+      for (const e of svc.enumerations ?? []) {
+        const m = new Map<string, number>();
+        for (const v of e.values ?? []) {
+          m.set(v.name, v.value);
+        }
+        const fq = `${svc.name}.${e.name}`;
+        this.enumValues.set(fq, m);
+        let inner = this.enumsByService.get(svc.name);
+        if (!inner) {
+          inner = new Map();
+          this.enumsByService.set(svc.name, inner);
+        }
+        inner.set(e.name, m);
+      }
+    }
+  }
+
+  /** All known service names, e.g. ["KRPC", "SpaceCenter", "KerbalAlarmClock", ...]. */
+  serviceNames(): string[] {
+    return [...this.services].sort();
+  }
+
+  /**
+   * All procedure full names in a service, e.g.
+   * ["SpaceCenter.GetUT", "SpaceCenter.CelestialBody.GetName", ...].
+   */
+  proceduresInService(service: string): string[] {
+    const out: string[] = [];
+    for (const info of this.byFullName.values()) {
+      if (info.service === service) out.push(info.fullName);
+    }
+    return out.sort();
+  }
+
+  /**
+   * Look up a procedure by `service.procedure` (e.g. "SpaceCenter.GetUT") or
+   * by the class-prefixed form ("SpaceCenter.CelestialBody.GetName").
+   */
+  lookup(service: string, procedure: string): ProcedureLookup {
+    const info = this.byFullName.get(`${service}.${procedure}`);
+    if (!info) return { found: false };
+    return { found: true, info };
+  }
+
+  /**
+   * Resolve an enum value name to its int code. e.g.
+   *   getEnumValue("SpaceCenter", "VesselType", "Ship")  -> 0
+   * Throws if the enum or value is unknown.
+   */
+  getEnumValue(service: string, enumName: string, valueName: string): number {
+    const m = this.enumValues.get(`${service}.${enumName}`);
+    if (!m) {
+      throw new Error(`unknown enum ${service}.${enumName}`);
+    }
+    const v = m.get(valueName);
+    if (v === undefined) {
+      throw new Error(`unknown value ${valueName} for ${service}.${enumName}`);
+    }
+    return v;
+  }
+
+  /**
+   * Inverse: resolve an int code to a value name. Returns null if the
+   * code is not in the enum's range — kRPC may add new values in newer
+   * versions, so callers should be defensive.
+   */
+  getEnumName(
+    service: string,
+    enumName: string,
+    valueCode: number,
+  ): string | null {
+    const m = this.enumValues.get(`${service}.${enumName}`);
+    if (!m) return null;
+    for (const [n, v] of m.entries()) {
+      if (v === valueCode) return n;
+    }
+    return null;
+  }
+
+  /**
+   * All enum value names for an enum, e.g.
+   *   getEnumNames("SpaceCenter", "VesselType")
+   *     -> ["Ship", "Station", "Lander", "Probe", ...]
+   */
+  getEnumNames(service: string, enumName: string): string[] {
+    const m = this.enumValues.get(`${service}.${enumName}`);
+    if (!m) return [];
+    return [...m.keys()].sort();
+  }
+
+  /**
+   * Count the number of distinct procedures across all services.
+   * Useful for tests and diagnostics.
+   */
+  procedureCount(): number {
+    return this.byFullName.size;
+  }
+}

packages/krpc-client/src/types.ts

@@ -0,0 +1,146 @@
+/**
+ * kRPC Type runtime representation.
+ *
+ * kRPC values are encoded on the wire in a custom way that sits on top of
+ * the standard protobuf encoding. Every procedure return / argument carries
+ * a `KrpcType` descriptor that tells the client how to encode/decode the
+ * bytes. The descriptor is itself a protobuf message (KRPC.Type) and is
+ * exchanged via `KRPC.GetServices()` at connect time.
+ *
+ * See: https://krpc.github.io/krpc/communication-protocols/messages.html
+ * and the Python client's `krpc.types` / `krpc.decoder` modules for the
+ * canonical reference implementation.
+ *
+ * TypeCode numeric values match the protobuf enum in krpc.proto:
+ *   0 NONE, 1 DOUBLE, 2 FLOAT, 3 SINT32, 4 SINT64, 5 UINT32, 6 UINT64,
+ *   7 BOOL, 8 STRING, 9 BYTES,
+ *   100 CLASS, 101 ENUMERATION,
+ *   200 EVENT, 201 PROCEDURE_CALL, 202 STREAM, 203 STATUS, 204 SERVICES,
+ *   300 TUPLE, 301 LIST, 302 SET, 303 DICTIONARY.
+ */
+export const TypeCode = {
+  NONE: 0,
+  DOUBLE: 1,
+  FLOAT: 2,
+  SINT32: 3,
+  SINT64: 4,
+  UINT32: 5,
+  UINT64: 6,
+  BOOL: 7,
+  STRING: 8,
+  BYTES: 9,
+  CLASS: 100,
+  ENUMERATION: 101,
+  EVENT: 200,
+  PROCEDURE_CALL: 201,
+  STREAM: 202,
+  STATUS: 203,
+  SERVICES: 204,
+  TUPLE: 300,
+  LIST: 301,
+  SET: 302,
+  DICTIONARY: 303,
+} as const;
+
+export type TypeCodeValue = (typeof TypeCode)[keyof typeof TypeCode];
+
+/**
+ * Decoded form of a kRPC Type message. We don't try to keep the
+ * protobufjs wrapper — the few fields we care about (code, service, name,
+ * types) are copied into this plain object for ergonomic access.
+ */
+export interface KrpcType {
+  code: TypeCodeValue;
+  /** For CLASS / ENUMERATION: the service that defines the type. */
+  service: string;
+  /** For CLASS / ENUMERATION: the class/enum name. */
+  name: string;
+  /**
+   * Nested types. Used by collections (LIST<T>, SET<T>, TUPLE<A,B>, DICT<K,V>).
+   * The semantics depend on the code:
+   *   LIST / SET:  types[0] is the element type
+   *   TUPLE:       types[i] is the i-th element type
+   *   DICTIONARY:  types[0] is the key type, types[1] is the value type
+   * For CLASS / ENUMERATION: empty.
+   */
+  types: KrpcType[];
+}
+
+/**
+ * Decode a kRPC Type protobuf message into our plain KrpcType shape.
+ * Exposed so callers (e.g. the service cache) can transform the
+ * GetServices() response into a useful index.
+ */
+export interface RawKrpcTypeMessage {
+  code: number;
+  service: string;
+  name: string;
+  types: RawKrpcTypeMessage[];
+}
+
+export function decodeKrpcType(raw: RawKrpcTypeMessage): KrpcType {
+  return {
+    code: raw.code as TypeCodeValue,
+    service: raw.service ?? '',
+    name: raw.name ?? '',
+    types: (raw.types ?? []).map(decodeKrpcType),
+  };
+}
+
+/**
+ * Human-readable name for a typecode. Used in error messages and for
+ * debugging. Not used in wire encoding.
+ */
+export function typeName(t: KrpcType): string {
+  switch (t.code) {
+    case TypeCode.NONE:
+      return 'None';
+    case TypeCode.DOUBLE:
+      return 'double';
+    case TypeCode.FLOAT:
+      return 'float';
+    case TypeCode.SINT32:
+      return 'sint32';
+    case TypeCode.SINT64:
+      return 'sint64';
+    case TypeCode.UINT32:
+      return 'uint32';
+    case TypeCode.UINT64:
+      return 'uint64';
+    case TypeCode.BOOL:
+      return 'bool';
+    case TypeCode.STRING:
+      return 'string';
+    case TypeCode.BYTES:
+      return 'bytes';
+    case TypeCode.CLASS:
+      return `${t.service}.${t.name}`;
+    case TypeCode.ENUMERATION:
+      return `${t.service}.${t.name}`;
+    case TypeCode.EVENT:
+      return 'Event';
+    case TypeCode.PROCEDURE_CALL:
+      return 'ProcedureCall';
+    case TypeCode.STREAM:
+      return 'Stream';
+    case TypeCode.STATUS:
+      return 'Status';
+    case TypeCode.SERVICES:
+      return 'Services';
+    case TypeCode.TUPLE: {
+      const inner = t.types.map(typeName).join(', ');
+      return `(${inner})`;
+    }
+    case TypeCode.LIST:
+      return `list<${t.types[0] ? typeName(t.types[0]) : '?'}>`;
+    case TypeCode.SET:
+      return `set<${t.types[0] ? typeName(t.types[0]) : '?'}>`;
+    case TypeCode.DICTIONARY: {
+      const k = t.types[0] ? typeName(t.types[0]) : '?';
+      const v = t.types[1] ? typeName(t.types[1]) : '?';
+      return `dict<${k}, ${v}>`;
+    }
+    default:
+      return `code=${t.code}`;
+  }
+}

packages/krpc-client/tests/connection.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { Buffer } from 'node:buffer';
+import { encodeVarint, decodeVarint } from '../src/connection.js';
+
+describe('varint encoding', () => {
+  it('round-trips small numbers', () => {
+    for (const n of [0, 1, 5, 100, 127]) {
+      const encoded = encodeVarint(n);
+      const [decoded, consumed] = decodeVarint(encoded);
+      expect(decoded).toBe(n);
+      expect(consumed).toBe(encoded.length);
+    }
+  });
+
+  it('round-trips numbers requiring 2 bytes', () => {
+    for (const n of [128, 200, 16383, 16384, 100_000]) {
+      const encoded = encodeVarint(n);
+      const [decoded, consumed] = decodeVarint(encoded);
+      expect(decoded).toBe(n);
+      expect(consumed).toBe(encoded.length);
+    }
+  });
+
+  it('round-trips numbers requiring 4-5 bytes', () => {
+    for (const n of [2 ** 20, 2 ** 28, 2 ** 31 - 1, 2 ** 32]) {
+      const encoded = encodeVarint(n);
+      const [decoded, consumed] = decodeVarint(encoded);
+      expect(decoded).toBe(n);
+      expect(consumed).toBe(encoded.length);
+    }
+  });
+
+  it('encodes correctly per the protobuf spec', () => {
+    // Reference values from the protobuf documentation
+    expect([...encodeVarint(0)]).toEqual([0x00]);
+    expect([...encodeVarint(1)]).toEqual([0x01]);
+    expect([...encodeVarint(127)]).toEqual([0x7f]);
+    expect([...encodeVarint(128)]).toEqual([0x80, 0x01]);
+    expect([...encodeVarint(300)]).toEqual([0xac, 0x02]);
+  });
+
+  it('decodes from a multi-byte buffer correctly', () => {
+    // decodeVarint should stop at the varint boundary
+    const buf = Buffer.concat([encodeVarint(42), Buffer.from([0xff, 0xee])]);
+    const [decoded, consumed] = decodeVarint(buf);
+    expect(decoded).toBe(42);
+    expect(consumed).toBe(1); // only the first byte was the varint
+  });
+
+  it('rejects negative numbers', () => {
+    expect(() => encodeVarint(-1)).toThrow();
+  });
+});
+
+describe('varint edge cases', () => {
+  it('decodes 0', () => {
+    const [v, c] = decodeVarint(Buffer.from([0]));
+    expect(v).toBe(0);
+    expect(c).toBe(1);
+  });
+
+  it('decodes max uint32', () => {
+    const n = 0xffffffff;
+    const [v, c] = decodeVarint(encodeVarint(n));
+    expect(v).toBe(n);
+    expect(c).toBe(encodeVarint(n).length);
+  });
+});

packages/krpc-client/tests/decoder.test.ts

@@ -0,0 +1,346 @@
+import { describe, it, expect } from 'vitest';
+import protobuf from 'protobufjs';
+import {
+  decodeValue,
+  encodeValue,
+  decodeDouble,
+  decodeFloat,
+  decodeSint32,
+  decodeUint32,
+  decodeUint64,
+  decodeBool,
+  decodeString,
+  decodeBytes,
+  decodeList,
+  decodeTuple,
+  decodeDictionary,
+  decodeKrpcList,
+} from '../src/decoder.js';
+import { TypeCode, type KrpcType } from '../src/types.js';
+import { MESSAGE_TYPES, KRPC } from '../src/schema.js';
+
+const T = (t: Partial<KrpcType>): KrpcType => ({
+  code: t.code ?? 0,
+  service: t.service ?? '',
+  name: t.name ?? '',
+  types: t.types ?? [],
+});
+
+// We need a small fake "TYPE" registry for the tests so the decoder
+// can find List / Tuple / Dictionary / Status by name. We can use the
+// real MESSAGE_TYPES for the actual system messages.
+const REG = MESSAGE_TYPES;
+
+describe('primitive decoders', () => {
+  it('decodes a double (8-byte little-endian)', () => {
+    expect(decodeDouble(new Uint8Array(new Float64Array([3.14]).buffer))).toBeCloseTo(3.14, 10);
+    expect(decodeDouble(new Uint8Array(new Float64Array([-0]).buffer))).toBe(-0);
+    expect(decodeDouble(new Uint8Array(new Float64Array([0]).buffer))).toBe(0);
+    expect(decodeDouble(new Uint8Array(new Float64Array([1e30]).buffer))).toBe(1e30);
+  });
+
+  it('decodes a float (4-byte little-endian)', () => {
+    expect(decodeFloat(new Uint8Array(new Float32Array([2.5]).buffer))).toBeCloseTo(2.5, 5);
+  });
+
+  it('decodes a sint32 (zigzag varint)', () => {
+    // 0 -> 0, 1 -> 2, -1 -> 1, 2 -> 4, -2 -> 3
+    expect(decodeSint32(new Uint8Array([0]))).toBe(0);
+    expect(decodeSint32(new Uint8Array([2]))).toBe(1);
+    expect(decodeSint32(new Uint8Array([1]))).toBe(-1);
+    expect(decodeSint32(new Uint8Array([4]))).toBe(2);
+    expect(decodeSint32(new Uint8Array([3]))).toBe(-2);
+  });
+
+  it('decodes a uint32 (varint)', () => {
+    expect(decodeUint32(new Uint8Array([0]))).toBe(0);
+    expect(decodeUint32(new Uint8Array([0x7f]))).toBe(127);
+    expect(decodeUint32(new Uint8Array([0x80, 0x01]))).toBe(128);
+  });
+
+  it('decodes a uint64 to BigInt (preserves > 2^53)', () => {
+    // 2^53 + 1 exceeds Number.MAX_SAFE_INTEGER. Verify the decoder
+    // produces the exact BigInt. Hand-varint for 2^53+1:
+    //   7-bit groups, LSB first: 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x10
+    //   (bit 53 = position 4 in the last group = 0b0010000 = 0x10)
+    const big = 0x20_0000_0000_0001n; // 2^53 + 1
+    const bytes = new Uint8Array([0x81, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x10]);
+    expect(decodeUint64(bytes)).toBe(big);
+  });
+
+  it('decodes a bool', () => {
+    expect(decodeBool(new Uint8Array([0]))).toBe(false);
+    expect(decodeBool(new Uint8Array([1]))).toBe(true);
+    expect(decodeBool(new Uint8Array([0xff]))).toBe(true);
+  });
+
+  it('decodes a string', () => {
+    const utf8 = new TextEncoder().encode('Kerbin');
+    const buf = new Uint8Array([utf8.length, ...utf8]);
+    expect(decodeString(buf)).toBe('Kerbin');
+  });
+
+  it('decodes a string with non-ASCII characters', () => {
+    const utf8 = new TextEncoder().encode('日本語');
+    const buf = new Uint8Array([utf8.length, ...utf8]);
+    expect(decodeString(buf)).toBe('日本語');
+  });
+
+  it('decodes bytes', () => {
+    const payload = new Uint8Array([0xde, 0xad, 0xbe, 0xef]);
+    const buf = new Uint8Array([payload.length, ...payload]);
+    expect(decodeBytes(buf)).toEqual(payload);
+  });
+});
+
+describe('decodeValue dispatcher', () => {
+  it('decodes DOUBLE', () => {
+    const bytes = new Uint8Array(new Float64Array([2.71828]).buffer);
+    const out = decodeValue(T({ code: TypeCode.DOUBLE }), bytes);
+    expect(out).toBeCloseTo(2.71828, 5);
+  });
+
+  it('decodes STRING', () => {
+    const utf8 = new TextEncoder().encode('Mun');
+    const bytes = new Uint8Array([utf8.length, ...utf8]);
+    expect(decodeValue(T({ code: TypeCode.STRING }), bytes)).toBe('Mun');
+  });
+
+  it('decodes CLASS object id (non-null)', () => {
+    // 42 as varint
+    const id = decodeValue(T({ code: TypeCode.CLASS, service: 'SpaceCenter', name: 'Vessel' }), new Uint8Array([42]));
+    expect(id).toBe(42n);
+  });
+
+  it('decodes CLASS object id (null when 0)', () => {
+    expect(
+      decodeValue(
+        T({ code: TypeCode.CLASS, service: 'SpaceCenter', name: 'Vessel' }),
+        new Uint8Array([0]),
+      ),
+    ).toBeNull();
+  });
+
+  it('decodes ENUMERATION as a sint32', () => {
+    expect(
+      decodeValue(
+        T({ code: TypeCode.ENUMERATION, service: 'SpaceCenter', name: 'VesselType' }),
+        new Uint8Array([0]), // Ship
+      ),
+    ).toBe(0);
+  });
+
+  it('decodes NONE as null', () => {
+    expect(decodeValue(T({ code: TypeCode.NONE }), new Uint8Array(0))).toBeNull();
+  });
+
+  it('throws on unknown type code', () => {
+    expect(() => decodeValue(T({ code: 9999 }), new Uint8Array(0))).toThrow(/unknown TypeCode/);
+  });
+});
+
+describe('collection decoders', () => {
+  it('decodes a list of doubles', () => {
+    // Construct a KRPC.List message manually:
+    //   items[0] = 8 bytes for double 1.0
+    //   items[1] = 8 bytes for double 2.5
+    const d1 = new Uint8Array(new Float64Array([1.0]).buffer);
+    const d2 = new Uint8Array(new Float64Array([2.5]).buffer);
+    const listMsg = KRPC.List.create({ items: [d1, d2] });
+    const listBytes = KRPC.List.encode(listMsg).finish();
+    const out = decodeList(
+      T({ code: TypeCode.LIST, types: [T({ code: TypeCode.DOUBLE })] }),
+      listBytes,
+      REG,
+    );
+    expect(out).toEqual([1.0, 2.5]);
+  });
+
+  it('decodes a list of strings', () => {
+    const enc = (s: string): Uint8Array => {
+      const utf8 = new TextEncoder().encode(s);
+      return new Uint8Array([utf8.length, ...utf8]);
+    };
+    const listMsg = KRPC.List.create({ items: [enc('Kerbin'), enc('Mun')] });
+    const listBytes = KRPC.List.encode(listMsg).finish();
+    const out = decodeList(
+      T({ code: TypeCode.LIST, types: [T({ code: TypeCode.STRING })] }),
+      listBytes,
+      REG,
+    );
+    expect(out).toEqual(['Kerbin', 'Mun']);
+  });
+
+  it('decodes an empty list', () => {
+    const listMsg = KRPC.List.create({ items: [] });
+    const listBytes = KRPC.List.encode(listMsg).finish();
+    const out = decodeList(
+      T({ code: TypeCode.LIST, types: [T({ code: TypeCode.STRING })] }),
+      listBytes,
+      REG,
+    );
+    expect(out).toEqual([]);
+  });
+
+  it('decodes a null list as null', () => {
+    const out = decodeList(
+      T({ code: TypeCode.LIST, types: [T({ code: TypeCode.STRING })] }),
+      new Uint8Array([0]),
+      REG,
+    );
+    expect(out).toBeNull();
+  });
+
+  it('decodes a list of CLASS as a bigint array', () => {
+    // items[0] = 7, items[1] = 0 (null)
+    const listMsg = KRPC.List.create({ items: [new Uint8Array([7]), new Uint8Array([0])] });
+    const listBytes = KRPC.List.encode(listMsg).finish();
+    const out = decodeList(
+      T({
+        code: TypeCode.LIST,
+        types: [T({ code: TypeCode.CLASS, service: 'SpaceCenter', name: 'CelestialBody' })],
+      }),
+      listBytes,
+      REG,
+    );
+    expect(out).toEqual([7n, null]);
+  });
+
+  it('decodes a tuple of mixed types', () => {
+    // tuple: (string "Kerbin", double 0.5)
+    const utf8 = new TextEncoder().encode('Kerbin');
+    const sBytes = new Uint8Array([utf8.length, ...utf8]);
+    const dBytes = new Uint8Array(new Float64Array([0.5]).buffer);
+    const tupleMsg = KRPC.Tuple.create({ items: [sBytes, dBytes] });
+    const tupleBytes = KRPC.Tuple.encode(tupleMsg).finish();
+    const out = decodeTuple(
+      T({
+        code: TypeCode.TUPLE,
+        types: [T({ code: TypeCode.STRING }), T({ code: TypeCode.DOUBLE })],
+      }),
+      tupleBytes,
+      REG,
+    );
+    expect(out).toEqual(['Kerbin', 0.5]);
+  });
+
+  it('decodes a dictionary of string -> double', () => {
+    const utf8 = new TextEncoder().encode('mu');
+    const sBytes = new Uint8Array([utf8.length, ...utf8]);
+    const dBytes = new Uint8Array(new Float64Array([3.53e12]).buffer);
+    const dictMsg = KRPC.Dictionary.create({
+      entries: [{ key: sBytes, value: dBytes }],
+    });
+    const dictBytes = KRPC.Dictionary.encode(dictMsg).finish();
+    const out = decodeDictionary(
+      T({
+        code: TypeCode.DICTIONARY,
+        types: [T({ code: TypeCode.STRING }), T({ code: TypeCode.DOUBLE })],
+      }),
+      dictBytes,
+      REG,
+    );
+    expect(out.get('mu')).toBe(3.53e12);
+  });
+
+  it('decodes a null dictionary as null', () => {
+    const out = decodeDictionary(
+      T({
+        code: TypeCode.DICTIONARY,
+        types: [T({ code: TypeCode.STRING }), T({ code: TypeCode.DOUBLE })],
+      }),
+      new Uint8Array([0]),
+      REG,
+    );
+    expect(out).toBeNull();
+  });
+
+  it('exposes a low-level decodeKrpcList for testing', () => {
+    const listMsg = KRPC.List.create({ items: [new Uint8Array([1, 2, 3])] });
+    const bytes = KRPC.List.encode(listMsg).finish();
+    const out = decodeKrpcList(bytes, KRPC.List);
+    // protobufjs returns Node Buffers (which extend Uint8Array). Compare
+    // the underlying bytes so this works regardless of wrapper class.
+    expect(out).toHaveLength(1);
+    expect(Array.from(out[0] as Uint8Array)).toEqual([1, 2, 3]);
+  });
+});
+
+describe('encodeValue (round-trips)', () => {
+  it('encodes a double', () => {
+    const bytes = encodeValue(T({ code: TypeCode.DOUBLE }), 1.5);
+    expect(decodeValue(T({ code: TypeCode.DOUBLE }), bytes)).toBe(1.5);
+  });
+
+  it('encodes a string', () => {
+    const bytes = encodeValue(T({ code: TypeCode.STRING }), 'Kerbol');
+    expect(decodeValue(T({ code: TypeCode.STRING }), bytes)).toBe('Kerbol');
+  });
+
+  it('encodes a CLASS object id', () => {
+    const bytes = encodeValue(
+      T({ code: TypeCode.CLASS, service: 'SpaceCenter', name: 'Vessel' }),
+      42n,
+    );
+    expect(decodeValue(T({ code: TypeCode.CLASS, service: 'SpaceCenter', name: 'Vessel' }), bytes)).toBe(42n);
+  });
+
+  it('encodes a null CLASS as id=0', () => {
+    const bytes = encodeValue(
+      T({ code: TypeCode.CLASS, service: 'SpaceCenter', name: 'Vessel' }),
+      null,
+    );
+    expect(bytes).toEqual(new Uint8Array([0]));
+  });
+
+  it('encodes an ENUMERATION', () => {
+    const bytes = encodeValue(
+      T({ code: TypeCode.ENUMERATION, service: 'SpaceCenter', name: 'VesselType' }),
+      3, // Probe
+    );
+    expect(
+      decodeValue(
+        T({ code: TypeCode.ENUMERATION, service: 'SpaceCenter', name: 'VesselType' }),
+        bytes,
+      ),
+    ).toBe(3);
+  });
+
+  it('encodes a list of doubles', () => {
+    const bytes = encodeValue(
+      T({ code: TypeCode.LIST, types: [T({ code: TypeCode.DOUBLE })] }),
+      [1.0, 2.0, 3.0],
+      REG,
+    );
+    const out = decodeValue(
+      T({ code: TypeCode.LIST, types: [T({ code: TypeCode.DOUBLE })] }),
+      bytes,
+      REG,
+    );
+    expect(out).toEqual([1.0, 2.0, 3.0]);
+  });
+
+  it('encodes a uint64 BigInt', () => {
+    const id = 0x1_0000_0000n; // 2^32
+    const bytes = encodeValue(T({ code: TypeCode.UINT64 }), id);
+    expect(decodeValue(T({ code: TypeCode.UINT64 }), bytes)).toBe(id);
+  });
+
+  it('encodes a bool', () => {
+    expect(decodeValue(T({ code: TypeCode.BOOL }), encodeValue(T({ code: TypeCode.BOOL }), true))).toBe(true);
+    expect(decodeValue(T({ code: TypeCode.BOOL }), encodeValue(T({ code: TypeCode.BOOL }), false))).toBe(false);
+  });
+
+  it('rejects SET (not implemented)', () => {
+    expect(() =>
+      encodeValue(T({ code: TypeCode.SET, types: [T({ code: TypeCode.STRING })] }), new Set(), REG),
+    ).toThrow(/SET not implemented/);
+  });
+});
+
+// Suppress unused-warning for the TYPE const helper by using it once.
+const _checkTypeHelper: KrpcType = T({ code: TypeCode.STRING });
+void _checkTypeHelper;
+// Also pin the protobufjs default import to confirm we still have it.
+const _pb: typeof protobuf = protobuf;
+void _pb;

packages/krpc-client/tests/integration.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Integration test: drive the wire format with raw sockets to exercise
+ * the same code paths that KRPCClient uses internally.
+ *
+ * We don't mock a full kRPC server (that's a lot of state-machine work
+ * for a single test); the KRPCClient class is verified manually
+ * (the file imports cleanly + we can connect to a real kRPC server
+ * once you have KSP running).
+ */
+import { describe, it, expect } from 'vitest';
+import * as net from 'node:net';
+import { Buffer } from 'node:buffer';
+import { KRPC, encodeMessage, decodeMessage } from '../src/schema.js';
+import { sendMessage, recvMessage, encodeVarint } from '../src/connection.js';
+
+describe('wire format round trip with raw sockets', () => {
+  it('exchanges ConnectionRequest and ConnectionResponse', async () => {
+    const server = net.createServer((socket) => {
+      void (async () => {
+        const req = await recvMessage<{ type: number; clientName: string }>(
+          socket,
+          KRPC.ConnectionRequest,
+        );
+        expect(req.type).toBe(0); // RPC
+        expect(req.clientName).toBe('test');
+
+        const resp = encodeMessage(KRPC.ConnectionResponse, {
+          status: 0,
+          message: '',
+          clientIdentifier: Buffer.from('test-client-id'),
+        });
+        socket.write(Buffer.concat([encodeVarint(resp.length), resp]));
+        await new Promise((r) => setTimeout(r, 50));
+        socket.destroy();
+      })();
+    });
+
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const port = (server.address() as net.AddressInfo).port;
+
+    const client = net.createConnection({ host: '127.0.0.1', port });
+    await new Promise<void>((resolve) => client.once('connect', () => resolve()));
+
+    // Handshake
+    sendMessage(client, KRPC.ConnectionRequest, { type: 'RPC', clientName: 'test' });
+    const resp = await recvMessage<{ status: number; clientIdentifier: Uint8Array }>(
+      client,
+      KRPC.ConnectionResponse,
+    );
+    expect(resp.status).toBe(0);
+    expect(Buffer.from(resp.clientIdentifier).toString()).toBe('test-client-id');
+
+    client.destroy();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  it('exchanges a Request with a Response carrying a Status return value', async () => {
+    const server = net.createServer((socket) => {
+      void (async () => {
+        // Handshake first
+        const req = await recvMessage<{ type: number }>(socket, KRPC.ConnectionRequest);
+        expect(req.type).toBe(0);
+        const resp = encodeMessage(KRPC.ConnectionResponse, {
+          status: 0,
+          message: '',
+          clientIdentifier: Buffer.from('x'),
+        });
+        socket.write(Buffer.concat([encodeVarint(resp.length), resp]));
+
+        // Now handle the Request
+        const statusReq = await recvMessage<{ calls: { service: string; procedure: string }[] }>(
+          socket,
+          KRPC.Request,
+        );
+        expect(statusReq.calls.length).toBe(1);
+        expect(statusReq.calls[0]!.service).toBe('KRPC');
+        expect(statusReq.calls[0]!.procedure).toBe('GetStatus');
+
+        const status = encodeMessage(KRPC.Status, {
+          version: '0.5.0',
+          bytesRead: 100n,
+          bytesWritten: 50n,
+          bytesReadRate: 1.0,
+          bytesWrittenRate: 0.5,
+        });
+        const respMsg = encodeMessage(KRPC.Response, { results: [{ value: status }] });
+        socket.write(Buffer.concat([encodeVarint(respMsg.length), respMsg]));
+        await new Promise((r) => setTimeout(r, 50));
+        socket.destroy();
+      })();
+    });
+
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const port = (server.address() as net.AddressInfo).port;
+
+    const client = net.createConnection({ host: '127.0.0.1', port });
+    await new Promise<void>((resolve) => client.once('connect', () => resolve()));
+
+    sendMessage(client, KRPC.ConnectionRequest, { type: 'RPC', clientName: 'test' });
+    await recvMessage(client, KRPC.ConnectionResponse);
+
+    sendMessage(client, KRPC.Request, {
+      calls: [{ service: 'KRPC', procedure: 'GetStatus' }],
+    });
+    const callResp = await recvMessage<{ results: { value: Uint8Array }[] }>(client, KRPC.Response);
+    const status = decodeMessage<{ version: string }>(KRPC.Status, callResp.results[0]!.value);
+    expect(status.version).toBe('0.5.0');
+
+    client.destroy();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+});

packages/krpc-client/tests/service-client.test.ts

@@ -0,0 +1,383 @@
+/**
+ * End-to-end test of KrpcServices with a tiny mock kRPC server.
+ *
+ * We start a real TCP server that:
+ *   1. Accepts the RPC + stream handshakes
+ *   2. Handles a small whitelist of procedure calls by responding
+ *      with hand-encoded values
+ *
+ * The test then drives a real KRPCClient + KrpcServices pair through
+ * the same wire format a real kRPC server uses, and verifies the
+ * decoded values match the hand-encoded responses.
+ *
+ * For the server side we use the same SocketReader-based pattern that
+ * the client uses, so the two sides share framing semantics.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import * as net from 'node:net';
+import { Buffer } from 'node:buffer';
+import { KRPC, encodeMessage } from '../src/schema.js';
+import { KRPCClient } from '../src/client.js';
+import { loadServices, KrpcServices } from '../src/service-client.js';
+import { encodeVarint, recvMessage, sendMessage } from '../src/connection.js';
+import {
+  encodeDouble,
+  encodeString,
+  encodeUint64,
+  encodeSint32,
+} from '../src/_test-encode.js';
+
+/** Mock services message that the server will hand back on GetServices. */
+const MOCK_SERVICES_RAW = {
+  services: [
+    {
+      name: 'KRPC',
+      procedures: [
+        {
+          name: 'GetStatus',
+          parameters: [],
+          returnType: { code: 203, service: '', name: '', types: [] },
+          returnIsNullable: false,
+        },
+        {
+          name: 'GetServices',
+          parameters: [],
+          returnType: { code: 204, service: '', name: '', types: [] },
+          returnIsNullable: false,
+        },
+      ],
+      classes: [],
+      enumerations: [],
+    },
+    {
+      name: 'SpaceCenter',
+      procedures: [
+        {
+          name: 'GetUT',
+          parameters: [],
+          returnType: { code: 1, service: '', name: '', types: [] },
+          returnIsNullable: false,
+        },
+        {
+          name: 'GetActiveVessel',
+          parameters: [],
+          returnType: { code: 100, service: 'SpaceCenter', name: 'Vessel', types: [] },
+          returnIsNullable: false,
+        },
+        {
+          name: 'GetBodies',
+          parameters: [],
+          returnType: {
+            code: 301,
+            service: '',
+            name: '',
+            types: [{ code: 100, service: 'SpaceCenter', name: 'CelestialBody', types: [] }],
+          },
+          returnIsNullable: false,
+        },
+        {
+          name: 'CelestialBody.GetName',
+          parameters: [
+            {
+              name: 'self',
+              type: { code: 100, service: 'SpaceCenter', name: 'CelestialBody', types: [] },
+              nullable: false,
+            },
+          ],
+          returnType: { code: 8, service: '', name: '', types: [] },
+          returnIsNullable: false,
+        },
+        {
+          name: 'Vessel.GetName',
+          parameters: [
+            {
+              name: 'self',
+              type: { code: 100, service: 'SpaceCenter', name: 'Vessel', types: [] },
+              nullable: false,
+            },
+          ],
+          returnType: { code: 8, service: '', name: '', types: [] },
+          returnIsNullable: false,
+        },
+        {
+          name: 'Vessel.GetType',
+          parameters: [
+            {
+              name: 'self',
+              type: { code: 100, service: 'SpaceCenter', name: 'Vessel', types: [] },
+              nullable: false,
+            },
+          ],
+          returnType: { code: 101, service: 'SpaceCenter', name: 'VesselType', types: [] },
+          returnIsNullable: false,
+        },
+      ],
+      classes: [{ name: 'CelestialBody' }, { name: 'Vessel' }, { name: 'Orbit' }],
+      enumerations: [
+        {
+          name: 'VesselType',
+          values: [
+            { name: 'Ship', value: 0 },
+            { name: 'Probe', value: 3 },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+async function freePort(): Promise<number> {
+  return new Promise<number>((resolve, reject) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.on('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const addr = srv.address();
+      if (addr && typeof addr === 'object') {
+        const p = addr.port;
+        srv.close(() => resolve(p));
+      } else {
+        srv.close(() => reject(new Error('no addr')));
+      }
+    });
+  });
+}
+
+function replyWithValue(socket: net.Socket, value: Uint8Array): void {
+  const resultMsg = KRPC.ProcedureResult.create({
+    value: Buffer.from(value),
+  });
+  const respMsg = KRPC.Response.create({ results: [resultMsg] });
+  const payload = Buffer.from(KRPC.Response.encode(respMsg).finish());
+  sendMessage(socket, KRPC.Response, { results: [resultMsg] });
+  void payload;
+}
+
+function replyWithError(socket: net.Socket, name: string, description: string): void {
+  const errMsg = KRPC.Error.create({ service: 'Test', name, description });
+  const resultMsg = KRPC.ProcedureResult.create({ error: errMsg, value: Buffer.from([]) });
+  sendMessage(socket, KRPC.Response, { results: [resultMsg] });
+}
+
+interface MockServer {
+  rpcPort: number;
+  streamPort: number;
+  close: () => Promise<void>;
+  stub: (
+    service: string,
+    procedure: string,
+    handler: (args: Uint8Array[]) => Uint8Array,
+  ) => void;
+  /** Counts the number of calls received for (service, procedure). */
+  callCount: (service: string, procedure: string) => number;
+  /** Captured arguments of the last call to (service, procedure). */
+  lastArgs: (service: string, procedure: string) => Uint8Array[];
+}
+
+async function startMockServer(): Promise<MockServer> {
+  const rpcPort = await freePort();
+  const streamPort = await freePort();
+  const stubs = new Map<string, (args: Uint8Array[]) => Uint8Array>();
+  const counts = new Map<string, number>();
+  const lastArgsMap = new Map<string, Uint8Array[]>();
+
+  const stub = (svc: string, proc: string, handler: (args: Uint8Array[]) => Uint8Array) => {
+    stubs.set(`${svc}.${proc}`, handler);
+  };
+
+  // Default stubs
+  stub('KRPC', 'GetServices', () => {
+    const servicesMsg = KRPC.Services.create(MOCK_SERVICES_RAW);
+    return new Uint8Array(KRPC.Services.encode(servicesMsg).finish());
+  });
+  stub('KRPC', 'GetStatus', () => {
+    const statusMsg = KRPC.Status.create({ version: 'test' });
+    return new Uint8Array(KRPC.Status.encode(statusMsg).finish());
+  });
+  stub('SpaceCenter', 'GetUT', () => encodeDouble(4_700_000.5));
+
+  // ── RPC server ─────────────────────────────────────────────────────
+  const rpcServer = net.createServer((socket) => {
+    void (async () => {
+      try {
+        // 1. Handshake
+        const req = await recvMessage<{ type: number; clientName: string }>(
+          socket,
+          KRPC.ConnectionRequest,
+        );
+        if (req.type !== 0) {
+          socket.destroy();
+          return;
+        }
+        sendMessage(socket, KRPC.ConnectionResponse, {
+          status: 0,
+          message: '',
+          clientIdentifier: Buffer.from('test-client'),
+        });
+
+        // 2. Procedure loop
+        while (!socket.destroyed) {
+          let callReq: {
+            calls: { service: string; procedure: string; arguments?: { value: Uint8Array }[] }[];
+          };
+          try {
+            callReq = await recvMessage(socket, KRPC.Request);
+          } catch {
+            return;
+          }
+          const call = callReq.calls[0];
+          if (!call) {
+            replyWithError(socket, 'Malformed', 'no call');
+            continue;
+          }
+          const key = `${call.service}.${call.procedure}`;
+          counts.set(key, (counts.get(key) ?? 0) + 1);
+          const args = (call.arguments ?? []).map((a) => new Uint8Array(a.value));
+          lastArgsMap.set(key, args);
+          const handler = stubs.get(key);
+          if (!handler) {
+            replyWithError(socket, 'UnknownProcedure', `${key} not stubbed`);
+            continue;
+          }
+          try {
+            const value = handler(args);
+            replyWithValue(socket, value);
+          } catch (e) {
+            replyWithError(socket, 'HandlerError', String(e));
+          }
+        }
+      } catch {
+        if (!socket.destroyed) socket.destroy();
+      }
+    })();
+  });
+  await new Promise<void>((resolve) => rpcServer.listen(rpcPort, '127.0.0.1', resolve));
+
+  // ── Stream server (handshake only, then idle) ─────────────────────
+  const streamServer = net.createServer((socket) => {
+    void (async () => {
+      try {
+        const req = await recvMessage<{ type: number; clientIdentifier: Uint8Array }>(
+          socket,
+          KRPC.ConnectionRequest,
+        );
+        if (req.type !== 1) {
+          socket.destroy();
+          return;
+        }
+        sendMessage(socket, KRPC.ConnectionResponse, { status: 0, message: '' });
+        // Keep alive
+        await new Promise(() => undefined);
+      } catch {
+        socket.destroy();
+      }
+    })();
+  });
+  await new Promise<void>((resolve) => streamServer.listen(streamPort, '127.0.0.1', resolve));
+
+  return {
+    rpcPort,
+    streamPort,
+    stub,
+    callCount: (svc, proc) => counts.get(`${svc}.${proc}`) ?? 0,
+    lastArgs: (svc, proc) => lastArgsMap.get(`${svc}.${proc}`) ?? [],
+    close: () =>
+      new Promise<void>((resolve) => {
+        rpcServer.close(() => {
+          streamServer.close(() => resolve());
+        });
+      }),
+  };
+}
+
+describe('KrpcServices against a mock kRPC server', () => {
+  let server: MockServer;
+  let client: KRPCClient;
+  let services: KrpcServices;
+
+  beforeAll(async () => {
+    server = await startMockServer();
+    client = new KRPCClient({
+      host: '127.0.0.1',
+      rpcPort: server.rpcPort,
+      streamPort: server.streamPort,
+      clientName: 'test',
+    });
+    await client.connect();
+    const loaded = await loadServices(client);
+    services = loaded.services;
+  }, 10_000);
+
+  afterAll(async () => {
+    await client.close();
+    await server.close();
+  });
+
+  it('lists services', () => {
+    const names = services.getCache().serviceNames();
+    expect(names).toContain('KRPC');
+    expect(names).toContain('SpaceCenter');
+  });
+
+  it('looks up the GetUT procedure', () => {
+    const r = services.getCache().lookup('SpaceCenter', 'GetUT');
+    expect(r.found).toBe(true);
+  });
+
+  it('invokes SpaceCenter.GetUT and decodes as double', async () => {
+    const ut = await services.invoke<number>('SpaceCenter', 'GetUT');
+    expect(ut).toBe(4_700_000.5);
+  });
+
+  it('invokes SpaceCenter.GetBodies and decodes a list of class ids', async () => {
+    server.stub('SpaceCenter', 'GetBodies', () => {
+      const items = [encodeUint64(1n), encodeUint64(2n), encodeUint64(3n)];
+      const listMsg = KRPC.List.create({ items });
+      return new Uint8Array(KRPC.List.encode(listMsg).finish());
+    });
+    const ids = await services.invoke<bigint[]>('SpaceCenter', 'GetBodies');
+    expect(ids).toEqual([1n, 2n, 3n]);
+  });
+
+  it('invokes a class method and decodes the string return', async () => {
+    server.stub('SpaceCenter', 'CelestialBody.GetName', () => encodeString('Kerbin'));
+    const name = await services.invoke<string>('SpaceCenter', 'CelestialBody.GetName', 42n);
+    expect(name).toBe('Kerbin');
+  });
+
+  it('rejects an unknown procedure', async () => {
+    await expect(
+      services.invoke('SpaceCenter', 'GetNothing'),
+    ).rejects.toThrow(/procedure not found/);
+  });
+
+  it('rejects a wrong number of arguments', async () => {
+    await expect(
+      services.invoke('SpaceCenter', 'GetBodies', 1n, 2n),
+    ).rejects.toThrow(/wrong number of arguments/);
+  });
+
+  it('decodes an enum return value', async () => {
+    server.stub('SpaceCenter', 'Vessel.GetType', () => encodeSint32(3));
+    const t = await services.invoke<number>('SpaceCenter', 'Vessel.GetType', 7n);
+    expect(t).toBe(3);
+  });
+
+  it('passes BigInt class ids through to class methods', async () => {
+    let receivedId: bigint | null = null;
+    server.stub('SpaceCenter', 'CelestialBody.GetName', (args) => {
+      const argBytes = args[0] ?? new Uint8Array();
+      let v = 0n;
+      let shift = 0n;
+      for (const b of argBytes) {
+        v |= BigInt(b & 0x7f) << shift;
+        if ((b & 0x80) === 0) break;
+        shift += 7n;
+      }
+      receivedId = v;
+      return encodeString('Mun');
+    });
+    await services.invoke<string>('SpaceCenter', 'CelestialBody.GetName', 99n);
+    expect(receivedId).toBe(99n);
+  });
+});

packages/krpc-client/tests/services.test.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect } from 'vitest';
+import { ServiceCache, type RawServicesMessage } from '../src/services.js';
+
+/**
+ * A small hand-crafted services message that mirrors the shape we'd
+ * get from KRPC.GetServices() on a real KSP install. Just enough
+ * services/procedures/enums to exercise the cache.
+ */
+const SAMPLE_RAW: RawServicesMessage = {
+  services: [
+    {
+      name: 'SpaceCenter',
+      procedures: [
+        {
+          name: 'GetUT',
+          parameters: [],
+          returnType: { code: 1, service: '', name: '', types: [] }, // DOUBLE
+          returnIsNullable: false,
+        },
+        {
+          name: 'GetBodies',
+          parameters: [],
+          returnType: {
+            code: 301, // LIST
+            service: '',
+            name: '',
+            types: [{ code: 100, service: 'SpaceCenter', name: 'CelestialBody', types: [] }],
+          },
+          returnIsNullable: false,
+        },
+        {
+          name: 'CelestialBody.GetName',
+          parameters: [
+            {
+              name: 'self',
+              type: { code: 100, service: 'SpaceCenter', name: 'CelestialBody', types: [] },
+              nullable: false,
+            },
+          ],
+          returnType: { code: 8, service: '', name: '', types: [] }, // STRING
+          returnIsNullable: false,
+        },
+        {
+          name: 'CelestialBody.GetParent',
+          parameters: [
+            {
+              name: 'self',
+              type: { code: 100, service: 'SpaceCenter', name: 'CelestialBody', types: [] },
+              nullable: false,
+            },
+          ],
+          // Nullable CelestialBody (i.e. Sun has no parent).
+          returnType: { code: 100, service: 'SpaceCenter', name: 'CelestialBody', types: [] },
+          returnIsNullable: true,
+        },
+      ],
+      classes: [
+        { name: 'CelestialBody' },
+        { name: 'Vessel' },
+        { name: 'Orbit' },
+      ],
+      enumerations: [
+        {
+          name: 'VesselType',
+          values: [
+            { name: 'Ship', value: 0 },
+            { name: 'Station', value: 1 },
+            { name: 'Probe', value: 3 },
+            { name: 'Debris', value: 8 },
+          ],
+        },
+        {
+          name: 'VesselSituation',
+          values: [
+            { name: 'PreLaunch', value: 0 },
+            { name: 'Orbiting', value: 1 },
+            { name: 'Escaping', value: 2 },
+            { name: 'Landed', value: 4 },
+            { name: 'Splashed', value: 5 },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'KRPC',
+      procedures: [
+        {
+          name: 'GetStatus',
+          parameters: [],
+          returnType: { code: 203, service: '', name: '', types: [] }, // STATUS
+          returnIsNullable: false,
+        },
+      ],
+      classes: [],
+      enumerations: [],
+    },
+  ],
+};
+
+describe('ServiceCache', () => {
+  it('builds from a raw services message', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    expect(cache.procedureCount()).toBe(5);
+    expect(cache.serviceNames()).toEqual(['KRPC', 'SpaceCenter']);
+  });
+
+  it('looks up a top-level procedure', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    const r = cache.lookup('SpaceCenter', 'GetUT');
+    expect(r.found).toBe(true);
+    if (!r.found) throw new Error('unreachable');
+    expect(r.info.service).toBe('SpaceCenter');
+    expect(r.info.name).toBe('GetUT');
+    expect(r.info.returnType.code).toBe(1); // DOUBLE
+    expect(r.info.returnIsNullable).toBe(false);
+    expect(r.info.parameters).toHaveLength(0);
+  });
+
+  it('looks up a class-prefixed procedure', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    const r = cache.lookup('SpaceCenter', 'CelestialBody.GetName');
+    expect(r.found).toBe(true);
+    if (!r.found) throw new Error('unreachable');
+    expect(r.info.parameters).toHaveLength(1);
+    expect(r.info.parameters[0]?.name).toBe('self');
+    expect(r.info.parameters[0]?.type.code).toBe(100); // CLASS
+    expect(r.info.parameters[0]?.type.name).toBe('CelestialBody');
+    expect(r.info.returnType.code).toBe(8); // STRING
+  });
+
+  it('returns not-found for an unknown procedure', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    expect(cache.lookup('SpaceCenter', 'GetNothing').found).toBe(false);
+    expect(cache.lookup('Nope', 'X').found).toBe(false);
+  });
+
+  it('returns not-found for an unknown service', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    expect(cache.lookup('KerbalAlarmClock', 'GetAlarms').found).toBe(false);
+  });
+
+  it('records returnIsNullable for nullable CLASS returns', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    const r = cache.lookup('SpaceCenter', 'CelestialBody.GetParent');
+    expect(r.found).toBe(true);
+    if (!r.found) throw new Error('unreachable');
+    expect(r.info.returnIsNullable).toBe(true);
+    expect(r.info.returnType.code).toBe(100);
+    expect(r.info.returnType.name).toBe('CelestialBody');
+  });
+
+  it('resolves enum values by name', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    expect(cache.getEnumValue('SpaceCenter', 'VesselType', 'Ship')).toBe(0);
+    expect(cache.getEnumValue('SpaceCenter', 'VesselType', 'Station')).toBe(1);
+    expect(cache.getEnumValue('SpaceCenter', 'VesselType', 'Probe')).toBe(3);
+    expect(cache.getEnumValue('SpaceCenter', 'VesselSituation', 'Orbiting')).toBe(1);
+  });
+
+  it('throws for unknown enum or enum value', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    expect(() => cache.getEnumValue('SpaceCenter', 'NoSuch', 'X')).toThrow(/unknown enum/);
+    expect(() => cache.getEnumValue('SpaceCenter', 'VesselType', 'Hovercraft')).toThrow(
+      /unknown value/,
+    );
+  });
+
+  it('resolves enum value names by code', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    expect(cache.getEnumName('SpaceCenter', 'VesselType', 0)).toBe('Ship');
+    expect(cache.getEnumName('SpaceCenter', 'VesselType', 3)).toBe('Probe');
+    expect(cache.getEnumName('SpaceCenter', 'VesselType', 999)).toBeNull();
+  });
+
+  it('lists enum value names', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    const names = cache.getEnumNames('SpaceCenter', 'VesselType');
+    expect(names).toEqual(['Debris', 'Probe', 'Ship', 'Station']); // sorted
+  });
+
+  it('lists procedures in a service', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    const procs = cache.proceduresInService('SpaceCenter');
+    expect(procs).toContain('SpaceCenter.GetUT');
+    expect(procs).toContain('SpaceCenter.CelestialBody.GetName');
+    expect(procs).toContain('SpaceCenter.CelestialBody.GetParent');
+  });
+
+  it('preserves nested list type info', () => {
+    const cache = new ServiceCache(SAMPLE_RAW);
+    const r = cache.lookup('SpaceCenter', 'GetBodies');
+    expect(r.found).toBe(true);
+    if (!r.found) throw new Error('unreachable');
+    expect(r.info.returnType.code).toBe(301); // LIST
+    expect(r.info.returnType.types).toHaveLength(1);
+    expect(r.info.returnType.types[0]?.code).toBe(100);
+    expect(r.info.returnType.types[0]?.name).toBe('CelestialBody');
+  });
+});

packages/krpc-client/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}

packages/krpc-client/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) {
-    // Occluder is behind the observer relative to the sun → no eclipse
+  if (proj <= 0) {
+    // 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,31 @@ 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/ksp-bridge:
+    dependencies:
+      '@kerbal-rt/krpc-client':
+        specifier: workspace:*
+        version: link:../../../packages/krpc-client
+      '@kerbal-rt/shared-types':
+        specifier: workspace:*
+        version: link:../../../packages/shared-types
+    devDependencies:
+      '@types/node':
+        specifier: ^22.5.0
+        version: 22.19.19
+      tsx:
+        specifier: ^4.19.1
+        version: 4.22.4
+      typescript:
+        specifier: ^5.6.2
+        version: 5.9.3
+      vitest:
+        specifier: ^2.1.1
+        version: 2.1.9(@types/node@22.19.19)
 
   apps/tools/mock-telemetry:
     dependencies:
@@ -178,6 +203,22 @@ importers:
         specifier: ^2.1.1
         version: 2.1.9(@types/node@22.19.19)
 
+  packages/krpc-client:
+    dependencies:
+      protobufjs:
+        specifier: ^7.4.0
+        version: 7.6.2
+    devDependencies:
+      '@types/node':
+        specifier: ^22.5.0
+        version: 22.19.19
+      typescript:
+        specifier: ^5.6.2
+        version: 5.9.3
+      vitest:
+        specifier: ^2.1.1
+        version: 2.1.9(@types/node@22.19.19)
+
   packages/orbital-math:
     dependencies:
       '@kerbal-rt/shared-types':
@@ -1081,6 +1122,66 @@ packages:
       }
     engines: { node: '>=14' }
 
+  '@protobufjs/aspromise@1.1.2':
+    resolution:
+      {
+        integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==,
+      }
+
+  '@protobufjs/base64@1.1.2':
+    resolution:
+      {
+        integrity: sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==,
+      }
+
+  '@protobufjs/codegen@2.0.5':
+    resolution:
+      {
+        integrity: sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==,
+      }
+
+  '@protobufjs/eventemitter@1.1.1':
+    resolution:
+      {
+        integrity: sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==,
+      }
+
+  '@protobufjs/fetch@1.1.1':
+    resolution:
+      {
+        integrity: sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==,
+      }
+
+  '@protobufjs/float@1.0.2':
+    resolution:
+      {
+        integrity: sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==,
+      }
+
+  '@protobufjs/inquire@1.1.2':
+    resolution:
+      {
+        integrity: sha512-pa0vFRuws4wkvaXKK1uXZMAwAX4/t8ANaJo45iw/oQHNQ9q5xUzwgFmVJGXiga2BeN+zpX7Vf9vmsiIa2J+MUw==,
+      }
+
+  '@protobufjs/path@1.1.2':
+    resolution:
+      {
+        integrity: sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==,
+      }
+
+  '@protobufjs/pool@1.1.0':
+    resolution:
+      {
+        integrity: sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==,
+      }
+
+  '@protobufjs/utf8@1.1.1':
+    resolution:
+      {
+        integrity: sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==,
+      }
+
   '@rolldown/pluginutils@1.0.0-beta.27':
     resolution:
       {
@@ -3107,6 +3208,12 @@ packages:
         integrity: sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==,
       }
 
+  long@5.3.2:
+    resolution:
+      {
+        integrity: sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==,
+      }
+
   loose-envify@1.4.0:
     resolution:
       {
@@ -3453,6 +3560,13 @@ packages:
         integrity: sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==,
       }
 
+  protobufjs@7.6.2:
+    resolution:
+      {
+        integrity: sha512-N9EiLovGEQOJSPF26Ij7qUGvahfEnq0eeYZ02aigIedkmz1qZSwjnP9SBITHJuF/6MYbIW4HDN8zdYjsjqJKXQ==,
+      }
+    engines: { node: '>=12.0.0' }
+
   punycode@2.3.1:
     resolution:
       {
@@ -4604,6 +4718,28 @@ snapshots:
   '@pkgjs/parseargs@0.11.0':
     optional: true
 
+  '@protobufjs/aspromise@1.1.2': {}
+
+  '@protobufjs/base64@1.1.2': {}
+
+  '@protobufjs/codegen@2.0.5': {}
+
+  '@protobufjs/eventemitter@1.1.1': {}
+
+  '@protobufjs/fetch@1.1.1':
+    dependencies:
+      '@protobufjs/aspromise': 1.1.2
+
+  '@protobufjs/float@1.0.2': {}
+
+  '@protobufjs/inquire@1.1.2': {}
+
+  '@protobufjs/path@1.1.2': {}
+
+  '@protobufjs/pool@1.1.0': {}
+
+  '@protobufjs/utf8@1.1.1': {}
+
   '@rolldown/pluginutils@1.0.0-beta.27': {}
 
   '@rollup/rollup-android-arm-eabi@4.61.0':
@@ -5975,6 +6111,8 @@ snapshots:
 
   lodash.merge@4.6.2: {}
 
+  long@5.3.2: {}
+
   loose-envify@1.4.0:
     dependencies:
       js-tokens: 4.0.0
@@ -6173,6 +6311,21 @@ snapshots:
       object-assign: 4.1.1
       react-is: 16.13.1
 
+  protobufjs@7.6.2:
+    dependencies:
+      '@protobufjs/aspromise': 1.1.2
+      '@protobufjs/base64': 1.1.2
+      '@protobufjs/codegen': 2.0.5
+      '@protobufjs/eventemitter': 1.1.1
+      '@protobufjs/fetch': 1.1.1
+      '@protobufjs/float': 1.0.2
+      '@protobufjs/inquire': 1.1.2
+      '@protobufjs/path': 1.1.2
+      '@protobufjs/pool': 1.1.0
+      '@protobufjs/utf8': 1.1.1
+      '@types/node': 22.19.19
+      long: 5.3.2
+
   punycode@2.3.1: {}
 
   queue-microtask@1.2.3: {}