The sky gets the things above the aeroplanes

Satellites, end to end: CelesTrak element sets behind the same TTL cache
the weather and the flights use, served as TLEs rather than as positions,
and propagated in the browser with SGP4.

Sending elements is the same trick `flights/plan.ts` plays and it has a
better excuse here — a TLE *is* the closed form, valid for days either
side of its epoch, so one cacheable fetch every six hours replaces a poll
and every viewer agrees about where everything is.

Two things are worth knowing about the shape of it:

  - There is no region parameter. An aeroplane at 10,000 m is local and
    a satellite at 550 km is above the horizon for a circle two thousand
    kilometres across, so one catalogue serves both boards and the client
    decides what is above its own horizon. Only the observer is per-city,
    which is why `main.ts` shares the elements and rebuilds the catalogue.
  - The layer draws on a dome, because it cannot draw anywhere else.
    `world.metres(550_000)` is 21,000 scene units against a far plane at
    3,000. Azimuth and elevation are real; the radius carries nothing.

Off by default: a clone that started pulling CelesTrak on `npm run dev`
would have volunteered somebody else's bandwidth for its onboarding.

Godmode gets the two dials that point at the sky rather than at the
light — fabricated traffic, which composes with a live ADS-B feed instead
of replacing it, and a switch for the satellite layer with a count beside
it. Both are god-only lies about the inputs, in the manner of the weather
override.

`satellite.js` is the second runtime dependency this package has taken.
Its entry point star-exports an Emscripten build that cannot be shaken
out, so `noWasmPropagator` in the Vite config cuts it: 308 kB of WASM
loader for a bulk propagator nothing calls, against 26 kB for the SGP4
that does the work.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/access.ts

@@ -116,7 +116,7 @@ export interface Capabilities {
 }
 
 /**
- * Which of the three feeds this deployment has actually wired.
+ * Which of the feeds this deployment has actually wired.
  *
  * A capability says what a *visitor* may have; this says what the *server* has,
  * and the app needs both before it opens a socket. `can.liveData` is true for
@@ -135,6 +135,12 @@ export interface Capabilities {
 export interface Feeds {
   weather: boolean;
   flights: boolean;
+  /**
+   * A satellite catalogue. Off on almost every box, including this repo's own
+   * default — see `loadSatellites` in the server's `config.ts` for why a clone
+   * does not start pulling CelesTrak the moment it boots.
+   */
+  satellites: boolean;
   markers: boolean;
 }
 
@@ -305,7 +311,12 @@ function access(
 function feedsFrom(raw: unknown): Feeds {
   const sources = (typeof raw === "object" && raw !== null ? raw : {}) as Record<string, unknown>;
   const wired = (key: string) => typeof sources[key] === "string" && sources[key] !== "none";
-  return { weather: wired("weather"), flights: wired("flights"), markers: wired("markers") };
+  return {
+    weather: wired("weather"),
+    flights: wired("flights"),
+    satellites: wired("satellites"),
+    markers: wired("markers"),
+  };
 }
 
 /**

src/adapters/http.ts

@@ -42,6 +42,7 @@ import {
   type SimRoute,
   type SkyRegion,
 } from "../engine/flights.ts";
+import type { SatelliteElements } from "../engine/satellites.ts";
 import type { Aircraft, FlightSource, Marker, MarkerPalette } from "../engine/types.ts";
 import { seededRandom } from "../engine/world.ts";
 import type {
@@ -51,6 +52,7 @@ import type {
   MarkersBody,
   OfficeDoc,
   PresenceBody,
+  SatellitesBody,
   WeatherBody,
 } from "../server/wire.ts";
 import { SAMPLE_MARKERS, SAMPLE_PALETTE } from "./sample.ts";
@@ -223,6 +225,13 @@ export interface TeraClient {
    * should pass them; `sampleRoutesFor` in `sample.ts` has them.
    */
   flights(region: SkyRegion, fallbackRoutes?: SimRoute[]): TrafficSource;
+  /**
+   * Every element set this deployment serves, once. `[]` when it serves none,
+   * which is the default and is not an error.
+   *
+   * Not per-region and not watched — see the implementation for both reasons.
+   */
+  satellites(options?: { signal?: AbortSignal }): Promise<SatelliteElements[]>;
   /**
    * One office pack. `null` for anything the server will not serve — including
    * a private one, which answers 404 rather than 403 so the endpoint cannot be
@@ -361,6 +370,28 @@ export function createTeraClient(options: TeraApiOptions = {}): TeraClient {
       return new HttpFlights(get, region, fallbackRoutes ?? syntheticRoutes(region));
     },
 
+    /**
+     * The satellite catalogue, once.
+     *
+     * The only feed here with no watcher, no back-off ladder and no fallback,
+     * and all three absences are the same fact: element sets are good for days
+     * and the server caches them for hours, so there is nothing to poll for. One
+     * fetch per page load is not a compromise, it is the whole requirement.
+     *
+     * No sample constellation underneath it either, unlike `markers` and
+     * `flights`. An invented aeroplane is a plausible aeroplane; an invented
+     * Starlink is a false claim about a numbered object somebody could go
+     * outside and fail to find. `[]` is the honest answer and it renders as an
+     * empty sky, which is what a box with no satellite source actually has.
+     */
+    async satellites(opts: { signal?: AbortSignal } = {}): Promise<SatelliteElements[]> {
+      const body = await get<SatellitesBody>("/satellites", {
+        ...(opts.signal ? { signal: opts.signal } : {}),
+      });
+      if (!body || !Array.isArray(body.satellites)) return [];
+      return body.satellites;
+    },
+
     office: (id) => get<OfficeDoc>(`/offices/${encodeURIComponent(id)}`),
 
     /**

src/engine/flights.ts

@@ -181,6 +181,95 @@ export function syntheticRoutes(region: SkyRegion, count = 6, seed = 20_617): Si
   return routes;
 }
 
+/**
+ * A source with a dial on it: whatever it was going to draw, plus N invented
+ * aircraft.
+ *
+ * This exists for one control in the godmode panel — "how busy would this look
+ * with three times the traffic" — and the shape it takes is chosen to make that
+ * question answerable without corrupting the answer to any other one.
+ *
+ * **It composes rather than substitutes.** The base source is polled unchanged
+ * and its aircraft are passed through untouched; the fabricated ones are a
+ * second list concatenated onto the end. That is what lets the dial work over a
+ * *live* ADS-B feed as well as over the simulator — the real traffic stays real
+ * and stays complete, and turning the dial back to zero returns exactly the
+ * sky that was there before, because nothing was ever taken away.
+ *
+ * The alternative was to mutate the simulator's route list, and it is worse in
+ * both directions: it does nothing at all when the server is serving its own
+ * plan (`HttpFlights` ignores its fallback in that mode, so the slider would be
+ * inert on every deployment that has an API), and it is destructive when it does
+ * work, because the authored corridors would have to be rebuilt to get back.
+ *
+ * ### On fabricating traffic at all
+ *
+ * The same argument as `weatherOverride` in `main.ts`: a god-only lie about the
+ * inputs, told to see what the renderer does with it. It is deliberately **not**
+ * available to anyone else, and the invented aircraft carry a callsign prefix of
+ * their own so that a screenshot of a busy sky can be told from a screenshot of
+ * a real one. Note what this breaks while it is on — every viewer agreeing about
+ * where the aircraft are, which is the property the server's plan exists to buy.
+ * That is acceptable for a debug dial and would not be for a feature.
+ */
+export interface TrafficDial {
+  /** The source to hand `createScene`. Stable for the dial's whole life. */
+  source: FlightSource;
+  /** Fabricate this many additional aircraft. `0` turns the dial off entirely. */
+  setExtra(count: number): void;
+  extra(): number;
+}
+
+/**
+ * Callsign prefix for fabricated traffic.
+ *
+ * Distinct from `syntheticRoutes`'s own `SIM`, and it has to be: `sampleRoute`
+ * derives an aircraft's id from its callsign, `createFlightLayer` keys its
+ * tracks on that id, and a deployment with no API is already flying `SIM 1`
+ * through `SIM 6` from the fallback. Reuse the prefix and every fabricated
+ * aircraft would land on an existing track, teleporting it across the board on
+ * alternate polls.
+ */
+const FABRICATED_PREFIX = "GOD";
+
+/** As many as the dial goes to. Past this the sky is soup and the point is made. */
+export const MAX_EXTRA_TRAFFIC = 400;
+
+export function withTrafficDial(base: FlightSource, region: SkyRegion): TrafficDial {
+  let extra: SimulatedFlights | null = null;
+  let count = 0;
+
+  return {
+    source: {
+      interval: base.interval,
+      poll(): Aircraft[] | Promise<Aircraft[]> {
+        const theirs = base.poll();
+        if (extra === null) return theirs;
+        const mine = extra.poll();
+        // `poll` is synchronous on every source in this build, but the interface
+        // permits a promise and `HttpFlights` documents its synchrony as a
+        // deliberate property rather than an accident. Handling both here costs
+        // one branch and means the dial cannot be what breaks that.
+        return theirs instanceof Promise ? theirs.then((a) => [...a, ...mine]) : [...theirs, ...mine];
+      },
+      dispose: () => base.dispose?.(),
+    },
+    setExtra(next: number) {
+      count = Math.max(0, Math.min(MAX_EXTRA_TRAFFIC, Math.round(next)));
+      if (count === 0) {
+        extra = null;
+        return;
+      }
+      const routes = syntheticRoutes(region, count).map((route, i) => ({
+        ...route,
+        callsign: `${FABRICATED_PREFIX} ${i + 1}`,
+      }));
+      extra = new SimulatedFlights(routes);
+    },
+    extra: () => count,
+  };
+}
+
 /**
  * Traffic that behaves like the real thing without being it: aircraft move
  * along fixed legs at fixed speeds, looping, with each one offset in phase so

src/engine/satellites.ts

@@ -0,0 +1,490 @@
+/**
+ * Satellites over the city — on a dome, because they cannot be anywhere else.
+ *
+ * Every other thing in this scene lives in projected metric space: a building is
+ * where the building is, an aircraft at 10,000 m is at `world.metres(10000)`
+ * above the ground it is over. That rule breaks completely here, and it is worth
+ * being explicit about how badly, because the alternative is a layer that renders
+ * nothing and looks broken.
+ *
+ * Starlink flies at about 550 km. The Bay Area board is ~94 m per scene unit with
+ * a 3.6× vertical exaggeration, so `world.metres(550_000)` is **21,000 scene
+ * units** — against a board 1,000 units across and a camera far plane at 3,000.
+ * The satellite is seven times beyond the horizon of the projection, over ground
+ * two thousand kilometres away that this city pack does not contain. There is no
+ * camera position from which the true placement is both visible and meaningful.
+ *
+ * So this layer draws **what you would see if you looked up**: each satellite at
+ * its real azimuth and elevation from the city centre, on a dome big enough to
+ * sit outside the buildings and inside the far plane. A dot due east at 30° above
+ * the horizon is genuinely due east at 30°. The dome's *radius* is arbitrary and
+ * carries no information; the direction carries all of it.
+ *
+ * That is not a compromise so much as the correct frame for the question. Nobody
+ * looking at a satellite layer wants to know its ECEF coordinates. They want to
+ * know whether one is passing over, where to look, and whether it is lit — and
+ * the last of those is why this bothers with `shadowFraction` rather than drawing
+ * every object the same brightness. A Starlink is visible to the naked eye when
+ * it is in sunlight while the ground below it is dark, which is the whole reason
+ * anybody ever noticed the constellation existed.
+ *
+ * ### Where the propagation happens, and why it is here
+ *
+ * The server sends element sets, not positions (`wire.ts`, `SatellitesBody`), for
+ * the same reason it sends a flight plan rather than aircraft: a TLE is already
+ * the closed form, SGP4 is the function that evaluates it, and every browser
+ * evaluating it agrees. One cacheable fetch every six hours replaces a poll.
+ *
+ * `satellite.js` is the second runtime dependency this package has ever taken,
+ * after three.js, and the bar it had to clear was "would hand-rolling this be
+ * better". SGP4 is a 1980 Fortran model with a specific set of drag and
+ * resonance terms, a published reference implementation, and a well-known list of
+ * ways a re-implementation goes subtly wrong; the library is MIT, is a direct
+ * translation of Vallado's C++, and is the one everybody checks against. Writing
+ * our own would have been a worse copy of it.
+ */
+
+import * as THREE from "three";
+import {
+  eciToEcf,
+  ecfToLookAngles,
+  gstime,
+  jday,
+  propagate,
+  shadowFraction,
+  sunPos,
+  twoline2satrec,
+  type SatRec,
+} from "satellite.js";
+import type { City, SatelliteGroup } from "./types.ts";
+
+/**
+ * One satellite's element set, as the catalogue takes it.
+ *
+ * Structurally `WireSatellite` from `server/wire.ts`, restated rather than
+ * imported for the same reason `SimRoute` is: the server must be able to build
+ * one without three.js becoming one of its dependencies.
+ */
+export interface SatelliteElements {
+  noradId: number;
+  name: string;
+  group: SatelliteGroup;
+  line1: string;
+  line2: string;
+}
+
+/** Where one satellite is in the observer's sky, right now. */
+export interface SatelliteFix {
+  noradId: number;
+  name: string;
+  group: SatelliteGroup;
+  /** Radians clockwise from true north. */
+  azimuth: number;
+  /** Radians above the horizon. Only non-negative fixes are ever produced. */
+  elevation: number;
+  /** Observer to satellite, in kilometres. Straight-line, not ground track. */
+  rangeKm: number;
+  /**
+   * How much of the sun's disc the earth is covering, from the satellite's point
+   * of view. `0` is full sunlight, `1` is umbra, and the values in between are
+   * the penumbra — which is where the fade at the end of a Starlink train comes
+   * from, and is the reason this is a fraction rather than a boolean.
+   */
+  shadow: number;
+}
+
+/**
+ * Observer height above the ellipsoid, in kilometres.
+ *
+ * Zero. The correction for a city at 50 m matters to a radar and not to a dot on
+ * a dome — it moves a look angle by well under a hundredth of a degree — and
+ * pretending otherwise would mean threading a ground elevation through here for
+ * no visible change.
+ */
+const OBSERVER_HEIGHT_KM = 0;
+
+/**
+ * How much of a frame the rolling sweep may spend propagating.
+ *
+ * SGP4 costs roughly ten microseconds per object, so a six-thousand-object
+ * catalogue is about sixty milliseconds — four frames' worth, in one lump, and
+ * a visible hitch if it happens all at once. Doing it every frame is out of the
+ * question and doing it on a timer just moves the hitch somewhere less
+ * predictable.
+ *
+ * So the sweep is **time-budgeted and rolling**: each call propagates as many
+ * objects as fit in this budget and remembers where it stopped, wrapping around
+ * the catalogue continuously. Two milliseconds is under a seventh of a 60 Hz
+ * frame, and it walks six thousand objects in about half a second.
+ *
+ * The staleness that buys is the thing to check, and it is negligible: half a
+ * second at Starlink's ~0.8° per second of apparent motion overhead is under
+ * half a degree of arc. Nobody can see that. An aircraft interpolated half a
+ * second late would be visibly behind; a satellite is not, because the dome is
+ * angular and the angles barely move.
+ *
+ * (`satellite.js` ships a WASM `BulkPropagator` that would make this a
+ * non-question. It is not used here because it needs a binary loaded at runtime
+ * and a fallback path for when that fails, which is a lot of machinery to buy
+ * back two milliseconds a frame that are already accounted for.)
+ */
+const SWEEP_BUDGET_MS = 2;
+
+/**
+ * The observer's own coordinates, in the radians `ecfToLookAngles` wants.
+ *
+ * Built once. `geodeticToEcf` would recompute the same three numbers on every
+ * call otherwise, several thousand times a second.
+ */
+interface Observer {
+  longitude: number;
+  latitude: number;
+  height: number;
+}
+
+/**
+ * A catalogue of element sets, propagated continuously, reporting what is up.
+ *
+ * Deliberately shaped like `SimulatedFlights` and `AdsbFlights` — construct with
+ * data, ask for the current state — but it is **not** a `FlightSource` and does
+ * not implement that interface. A `FlightSource.poll()` returns positions on the
+ * ground; this returns look angles on a dome, and collapsing the two into one
+ * interface would mean a renderer that could not tell which space it was in.
+ */
+export class SatelliteCatalogue {
+  private readonly records: { rec: SatRec; meta: SatelliteElements }[] = [];
+  private readonly observer: Observer;
+
+  /** Latest fix per NORAD id. Entries are deleted as they set below the horizon. */
+  private readonly current = new Map<number, SatelliteFix>();
+
+  /** Where the rolling sweep stopped last time. */
+  private cursor = 0;
+
+  /**
+   * How many objects the last full pass found above the horizon, for the panel.
+   * Counted rather than derived from `current.size` so that a partial sweep does
+   * not make the number jump around while it is still walking the catalogue.
+   */
+  private lastPassVisible = 0;
+  private passVisible = 0;
+
+  constructor(elements: SatelliteElements[], center: City["center"]) {
+    for (const el of elements) {
+      // A TLE this build cannot read is one satellite missing, never a throw:
+      // the catalogue arrives over the network and one malformed line must not
+      // take the layer down.
+      //
+      // `rec.error` is necessary and **not sufficient**, which is worth stating
+      // because the obvious version of this check is wrong. `twoline2satrec`
+      // reads fixed columns with `parseFloat` and does not validate: hand it two
+      // lines of prose that merely start "1 " and "2 " and it returns `error: 0`
+      // with `NaN` in the orbital elements. Those propagate to `NaN` positions,
+      // which become `NaN` look angles, which land in the layer's vertex buffer
+      // — and one `NaN` vertex is enough to make a `Points` draw call render
+      // nothing at all. So the elements are checked for being numbers.
+      const rec = twoline2satrec(el.line1, el.line2);
+      if (rec.error !== 0) continue;
+      if (!Number.isFinite(rec.no) || !Number.isFinite(rec.inclo) || !Number.isFinite(rec.ecco)) {
+        continue;
+      }
+      this.records.push({ rec, meta: el });
+    }
+
+    this.observer = {
+      longitude: (center.lng * Math.PI) / 180,
+      latitude: (center.lat * Math.PI) / 180,
+      height: OBSERVER_HEIGHT_KM,
+    };
+  }
+
+  /** How many element sets this build could actually read. */
+  get size(): number {
+    return this.records.length;
+  }
+
+  /** How many were above the horizon at the end of the last complete pass. */
+  get visibleCount(): number {
+    return this.lastPassVisible;
+  }
+
+  /**
+   * Advance the rolling sweep and return everything currently above the horizon.
+   *
+   * `when` is passed in rather than read from the clock because godmode scrubs
+   * time — the whole panel exists to put the scene at an arbitrary instant, and
+   * a layer that quietly used `new Date()` would be the one thing on screen that
+   * ignored the scrubber. It is also what makes a time-lapse capture possible at
+   * all: `shots/` steps the clock rather than recording it.
+   */
+  fixes(when: Date): SatelliteFix[] {
+    if (this.records.length === 0) return [];
+
+    const gmst = gstime(when);
+    // The sun moves a degree a day; computing its position once per sweep call
+    // rather than once per satellite is free accuracy-wise and saves a few
+    // thousand redundant evaluations.
+    const sun = sunPos(jday(when));
+
+    const deadline = performance.now() + SWEEP_BUDGET_MS;
+    let stepped = 0;
+
+    // At least one per call, so a machine so slow that `performance.now()` has
+    // already passed the deadline still makes progress instead of freezing the
+    // sky forever.
+    do {
+      const entry = this.records[this.cursor];
+      if (entry !== undefined) {
+        const fix = this.fixOne(entry.rec, entry.meta, when, gmst, sun.rsun);
+        if (fix === null) this.current.delete(entry.meta.noradId);
+        else {
+          this.current.set(entry.meta.noradId, fix);
+          this.passVisible += 1;
+        }
+      }
+
+      this.cursor += 1;
+      if (this.cursor >= this.records.length) {
+        // A pass completed: publish its count and start the next one's tally.
+        this.cursor = 0;
+        this.lastPassVisible = this.passVisible;
+        this.passVisible = 0;
+      }
+      stepped += 1;
+    } while (performance.now() < deadline && stepped < this.records.length);
+
+    return [...this.current.values()];
+  }
+
+  /** One satellite, or `null` if it is below the horizon or will not propagate. */
+  private fixOne(
+    rec: SatRec,
+    meta: SatelliteElements,
+    when: Date,
+    gmst: number,
+    sunEciAU: { x: number; y: number; z: number },
+  ): SatelliteFix | null {
+    // `propagate` returns null for a decayed object and for an element set it
+    // cannot carry to this date — both of which are ordinary in a catalogue that
+    // is hours old, and neither of which is this layer's problem.
+    const state = propagate(rec, when);
+    const eci = state?.position;
+    if (eci === undefined || typeof eci === "boolean") return null;
+
+    const look = ecfToLookAngles(this.observer, eciToEcf(eci, gmst));
+    // Below the horizon is the common case by a wide margin — a few hundred of
+    // several thousand objects are up at any instant — so this returns before
+    // the shadow calculation rather than after it.
+    //
+    // `NaN < 0` is false, so this comparison alone would let a degenerate
+    // element set through to the vertex buffer. The constructor screens for that
+    // and this is the belt: an object can also decay or go numerically unstable
+    // partway through a session, long after it was admitted.
+    if (!(look.elevation >= 0)) return null;
+
+    return {
+      noradId: meta.noradId,
+      name: meta.name,
+      group: meta.group,
+      azimuth: look.azimuth,
+      elevation: look.elevation,
+      rangeKm: look.rangeSat,
+      shadow: shadowFraction(sunEciAU, eci),
+    };
+  }
+}
+
+// ---- Rendering ------------------------------------------------------------
+
+export interface SatelliteLayer {
+  group: THREE.Group;
+  /** Redraw from a set of fixes. Cheap enough to call every frame, and is. */
+  update(fixes: SatelliteFix[]): void;
+  /**
+   * Whether the layer draws at all. The catalogue keeps propagating either way —
+   * see `setVisible` for why that is deliberate rather than wasteful.
+   */
+  setVisible(visible: boolean): void;
+  dispose(): void;
+}
+
+/**
+ * The dome's radius, as a fraction of the board's longest side.
+ *
+ * It has to clear the city — a dot inside the buildings would be occluded by
+ * them, which is the one thing that is definitely wrong — and it has to stay
+ * inside the camera's far plane, which `scene.ts` sets at three board spans. At
+ * 1.2 the dome is outside every building and comfortably clear of the far plane
+ * even with the camera pulled all the way back.
+ */
+const DOME_RADIUS_FACTOR = 1.2;
+
+/**
+ * How large a dot is drawn, in scene units, before attenuation.
+ *
+ * Everything on the dome is the same distance away, so `sizeAttenuation` cannot
+ * separate near from far here the way it does for a starfield — it only makes
+ * the whole layer shrink as the camera retreats, which is what keeps the sky
+ * looking like a sky rather than like a fixed-size overlay pasted on the frame.
+ */
+const DOT_SIZE_FACTOR = 0.012;
+
+/** Ceiling on dots, so the buffers are allocated once and never grow. */
+const MAX_DOTS = 4096;
+
+/**
+ * Colour per constellation.
+ *
+ * Starlink is the one that gets a colour of its own, for the same reason it gets
+ * its own group in the wire type: it is what people are looking for. The rest are
+ * deliberately close to white — a sky where every object is a different hue is a
+ * chart, not a sky.
+ */
+const GROUP_COLORS: Record<SatelliteGroup, THREE.Color> = {
+  starlink: new THREE.Color(0xbfd8ff),
+  comms: new THREE.Color(0xd8e2ee),
+  navigation: new THREE.Color(0xe6e0cf),
+  station: new THREE.Color(0xfff0d0),
+  weather: new THREE.Color(0xd4ecdf),
+  other: new THREE.Color(0xdcdcdc),
+};
+
+/**
+ * Below this elevation a dot is faded out entirely.
+ *
+ * Not because the geometry is wrong down there but because it is *useless*: an
+ * object one degree above the horizon is behind the hills, behind the buildings,
+ * and behind more atmosphere than it can be seen through. Fading the last few
+ * degrees also hides the pop that a hard cut-off produces every time something
+ * rises, which on a busy constellation is several times a minute.
+ */
+const HORIZON_FADE_DEG = 8;
+
+/**
+ * Alpha for an object in full shadow, relative to a sunlit one.
+ *
+ * Not zero. A satellite in the earth's shadow is genuinely invisible to the eye,
+ * and drawing nothing would be the physically honest choice — but this layer is
+ * also a map of what is overhead, and a sky that empties itself at local midnight
+ * reads as a broken feed rather than as a correct one. So an eclipsed object is
+ * drawn faintly: present, obviously not lit, and clearly a different thing from
+ * the one crossing above it in sunlight.
+ */
+const SHADOW_ALPHA = 0.16;
+
+export function createSatelliteLayer(boardSpan: number): SatelliteLayer {
+  const group = new THREE.Group();
+  group.name = "satellites";
+
+  const radius = boardSpan * DOME_RADIUS_FACTOR;
+
+  const positions = new Float32Array(MAX_DOTS * 3);
+  const colors = new Float32Array(MAX_DOTS * 4);
+  // Held as locals rather than looked up through `geo.attributes` on every
+  // update: the lookup is a string index into a dictionary typed as possibly
+  // holding nothing, and the alternative to keeping the references is a
+  // non-null assertion on the hot path twice a frame.
+  const positionAttr = new THREE.BufferAttribute(positions, 3);
+  const colorAttr = new THREE.BufferAttribute(colors, 4);
+  const geo = new THREE.BufferGeometry();
+  geo.setAttribute("position", positionAttr);
+  geo.setAttribute("color", colorAttr);
+  geo.setDrawRange(0, 0);
+
+  const material = new THREE.PointsMaterial({
+    size: boardSpan * DOT_SIZE_FACTOR,
+    sizeAttenuation: true,
+    vertexColors: true,
+    transparent: true,
+    // Dots are drawn over the sky and over each other; letting them write depth
+    // makes whichever drew first punch a hole in the ones behind, which on a
+    // dense constellation is most of them.
+    depthWrite: false,
+    // The sky is the darkest thing in the frame at the hour this layer matters,
+    // and additive blending is what makes a lit satellite read as a light source
+    // rather than as a grey sticker.
+    blending: THREE.AdditiveBlending,
+  });
+
+  const points = new THREE.Points(geo, material);
+  points.name = "satellite-dots";
+  // The buffer is rewritten in scene space every update, so its bounding sphere
+  // is permanently stale and culling on it would cull the whole sky.
+  points.frustumCulled = false;
+  group.add(points);
+
+  const scratch = new THREE.Color();
+
+  /**
+   * The dome is centred on the board's origin and not on the camera.
+   *
+   * Centring it on the camera would keep every dot at a constant apparent size
+   * and would be the right call for a true skybox. It is the wrong call here,
+   * because this dome is *anchored to a place*: the look angles were computed for
+   * the city centre, so a dot means "from the middle of this board, look there".
+   * Following the camera would silently turn a measured direction into a
+   * decoration.
+   */
+  function place(fix: SatelliteFix, into: THREE.Vector3): void {
+    const cosEl = Math.cos(fix.elevation);
+    // Azimuth is clockwise from north, and scene north is −Z with +X east —
+    // which is exactly `sin` on X and `−cos` on Z, with no sign fudge. The same
+    // convention `world.project` uses; see `District.gridAngle` for the other
+    // place this rule is stated.
+    into.set(
+      Math.sin(fix.azimuth) * cosEl * radius,
+      Math.sin(fix.elevation) * radius,
+      -Math.cos(fix.azimuth) * cosEl * radius,
+    );
+  }
+
+  const scratchVec = new THREE.Vector3();
+
+  function update(fixes: SatelliteFix[]): void {
+    let n = 0;
+    for (const fix of fixes) {
+      if (n >= MAX_DOTS) break;
+
+      const elevationDeg = (fix.elevation * 180) / Math.PI;
+      const horizon = Math.min(1, elevationDeg / HORIZON_FADE_DEG);
+      if (horizon <= 0) continue;
+
+      place(fix, scratchVec);
+      positions[n * 3] = scratchVec.x;
+      positions[n * 3 + 1] = scratchVec.y;
+      positions[n * 3 + 2] = scratchVec.z;
+
+      scratch.copy(GROUP_COLORS[fix.group] ?? GROUP_COLORS.other);
+      const lit = 1 - fix.shadow;
+      colors[n * 4] = scratch.r;
+      colors[n * 4 + 1] = scratch.g;
+      colors[n * 4 + 2] = scratch.b;
+      colors[n * 4 + 3] = horizon * (SHADOW_ALPHA + (1 - SHADOW_ALPHA) * lit);
+      n += 1;
+    }
+
+    geo.setDrawRange(0, n);
+    positionAttr.needsUpdate = true;
+    colorAttr.needsUpdate = true;
+  }
+
+  return {
+    group,
+    update,
+    /**
+     * Hiding the layer stops it drawing and does **not** stop the catalogue
+     * propagating, which is the right way round: turning the sky back on should
+     * show where things are now, not resume a sweep from wherever it was
+     * abandoned and then crawl back into agreement with reality over the next
+     * half second. The propagation is two milliseconds a frame; correctness on
+     * re-entry is worth more than reclaiming it.
+     */
+    setVisible(visible: boolean) {
+      group.visible = visible;
+    },
+    dispose() {
+      geo.dispose();
+      material.dispose();
+    },
+  };
+}

src/engine/scene.ts

@@ -32,6 +32,11 @@ import { createBlocks, createLandmarks } from "./blocks.ts";
 import { createNightLights, type NightLights } from "./nightlights.ts";
 import { createFlightLayer, type FlightLayer } from "./flights.ts";
 import { createMarkerLayer, type MarkerLayer } from "./markers.ts";
+import {
+  createSatelliteLayer,
+  type SatelliteCatalogue,
+  type SatelliteLayer,
+} from "./satellites.ts";
 import { createSceneKit, type Pose } from "./scenekit.ts";
 import type { Stage, StageScene } from "./stage.ts";
 import { createBridges, createRoads } from "./structures.ts";
@@ -51,6 +56,15 @@ export interface SceneOptions {
   city: City;
   markerPalette?: MarkerPalette;
   flights?: FlightSource;
+  /**
+   * Element sets to propagate, if this deployment has any.
+   *
+   * A catalogue rather than a source, and the asymmetry with `flights` is the
+   * point: a `FlightSource` is polled because there is no closed form for where
+   * aircraft are, and a `SatelliteCatalogue` is *evaluated* because a TLE is
+   * exactly that closed form. Nothing here is ever fetched on a timer.
+   */
+  satellites?: SatelliteCatalogue;
   /** Fires on hover/click of a marker head. */
   onMarkerPick?: (marker: Marker | null) => void;
   /**
@@ -97,6 +111,27 @@ export interface SceneHandle {
    * elevation, so the number has to arrive separately.
    */
   setSolarElevation(degrees: number): void;
+  /**
+   * Freeze the satellite sky at an instant, or pass `null` to follow the wall
+   * clock. Exactly the shape of `main.ts`'s own time override, deliberately.
+   *
+   * Separate from `setSolarElevation` even though both follow the same clock,
+   * because they need different things from it: the night-lights want a scalar
+   * the caller has already worked out, and SGP4 wants the date itself. Handing
+   * the layer an elevation would mean it could not propagate, and handing the
+   * lights a `Date` would mean two modules computing the sun.
+   *
+   * No-op on a deployment with no catalogue.
+   */
+  setSkyInstant(when: Date | null): void;
+  /** Draw the satellite layer, or do not. No-op with no catalogue. */
+  setSatellitesVisible(visible: boolean): void;
+  /**
+   * How many objects were above the horizon at the end of the last complete
+   * propagation pass, and how many element sets this build could read at all.
+   * Both zero without a catalogue. For the godmode readout; nothing renders it.
+   */
+  satelliteCounts(): { visible: number; total: number };
   flyTo(chapterId: string): void;
   current(): string;
   onChapterChange(fn: (id: string) => void): void;
@@ -198,6 +233,29 @@ export async function createScene(
     scene.add(flightLayer.group);
   }
 
+  let satelliteLayer: SatelliteLayer | null = null;
+  if (options.satellites) {
+    satelliteLayer = createSatelliteLayer(boardSpan);
+    scene.add(satelliteLayer.group);
+  }
+
+  /**
+   * The instant the sky is drawn for, or `null` for the wall clock.
+   *
+   * Satellites are the one layer whose content is a function of *absolute* time
+   * rather than of elapsed time, so `tick(dt)` cannot serve them: godmode scrubs
+   * the clock to an arbitrary date and the sky has to follow it there.
+   *
+   * It holds the **override** rather than a resolved `Date`, which is the same
+   * shape `main.ts` keeps its own clock in and is load-bearing here. A resolved
+   * instant would have to be pushed in on a timer, and the only timer available
+   * is `updateSun`'s — which runs about once a second, so the sky would advance
+   * in one-second jumps while everything around it moved smoothly. Holding the
+   * override means an unscrubbed scene reads the clock afresh every frame and a
+   * scrubbed one is frozen exactly where it was put.
+   */
+  let skyOverride: Date | null = null;
+
   // ---- Chapters -----------------------------------------------------------
 
   const chapterById = Object.fromEntries(city.chapters.map((c) => [c.id, c]));
@@ -261,10 +319,17 @@ export async function createScene(
           void Promise.resolve(options.flights.poll()).then((ac) => flightLayer?.update(ac));
         }
       }
+      // Every frame and on no timer of its own. The catalogue's sweep is
+      // time-budgeted internally — see `SWEEP_BUDGET_MS` — so calling it more
+      // often makes it walk the catalogue sooner, never makes it cost more.
+      if (options.satellites && satelliteLayer) {
+        satelliteLayer.update(options.satellites.fixes(skyOverride ?? new Date()));
+      }
     },
     dispose() {
       options.flights?.dispose?.();
       flightLayer?.dispose();
+      satelliteLayer?.dispose();
       nightLights.dispose();
       markerLayer.dispose();
       kit.dispose();
@@ -286,6 +351,14 @@ export async function createScene(
     stageScene,
     setLighting: (state) => kit.applyLighting(state),
     setSolarElevation: (degrees) => nightLights.setSolarElevation(degrees),
+    setSkyInstant: (when) => {
+      skyOverride = when;
+    },
+    setSatellitesVisible: (visible) => satelliteLayer?.setVisible(visible),
+    satelliteCounts: () => ({
+      visible: options.satellites?.visibleCount ?? 0,
+      total: options.satellites?.size ?? 0,
+    }),
     flyTo,
     current: () => currentChapter,
     onChapterChange(fn) {

src/engine/types.ts

@@ -299,3 +299,29 @@ export interface FlightSource {
   interval: number;
   dispose?(): void;
 }
+
+// ---- Satellites -----------------------------------------------------------
+
+/**
+ * Which constellation a satellite belongs to, as far as anyone looking up cares.
+ *
+ * A **display bucket and not a taxonomy**: no orbital regime, no operator, no
+ * launch date. `engine/satellites.ts` picks a colour from it and nothing else
+ * reads it, and a field that carried more would be a field that got wrong.
+ *
+ * `starlink` is broken out from `comms` because it is the reason the layer
+ * exists — it is the constellation people can see with their eyes, in a train,
+ * forty minutes after sunset. `other` is not a failure; most of the catalogue is
+ * other.
+ *
+ * This lives here rather than in `server/wire.ts` for the same reason `Marker`
+ * does: the renderer owns the vocabulary and the wire carries it, so a body off
+ * the network is handed to the engine as-is with no adapter in between.
+ */
+export type SatelliteGroup =
+  | "starlink"
+  | "comms"
+  | "navigation"
+  | "station"
+  | "weather"
+  | "other";

src/main.ts

@@ -19,7 +19,13 @@ import {
   type WeatherObservation,
 } from "./engine/atmosphere.ts";
 import { createScene, type SceneHandle } from "./engine/scene.ts";
-import { regionOf, SimulatedFlights } from "./engine/flights.ts";
+import {
+  regionOf,
+  SimulatedFlights,
+  withTrafficDial,
+  type TrafficDial,
+} from "./engine/flights.ts";
+import { SatelliteCatalogue, type SatelliteElements } from "./engine/satellites.ts";
 import type { Pose } from "./engine/scenekit.ts";
 import { createStage, deviceProfile } from "./engine/stage.ts";
 import { daylightPhase } from "./engine/solar.ts";
@@ -156,6 +162,44 @@ let weatherWatch: WeatherWatch | null = null;
  * which is never live and does not need asking.
  */
 let cityFlights: TrafficSource | null = null;
+/**
+ * The satellite element sets, fetched once for the page rather than once per city.
+ *
+ * Every other feed here is per-city and is torn down on a switch. These are not,
+ * and the asymmetry is the physics: an aircraft at 10,000 m is visible for tens
+ * of kilometres and the two boards are six hundred apart, but a satellite at
+ * 550 km is above the horizon for a circle two thousand kilometres across. The
+ * same element sets serve both cities and would serve a continent.
+ *
+ * **The elements are shared and the catalogue is not.** A `SatelliteCatalogue`
+ * is built around an observer, and the observer is the city centre: reusing one
+ * across a city switch would compute the Southland's sky from San Francisco and
+ * put every look angle several degrees out, with nothing on screen to say so.
+ * So the expensive, universal half is cached here and the cheap, local half is
+ * rebuilt per board.
+ *
+ * `null` until the first fetch is started, and on the overwhelming majority of
+ * deployments forever: `TERA_SATELLITES_SOURCE` is off by default. A promise
+ * rather than a value so that a second city mounted while the first fetch is
+ * still in the air waits for it instead of starting another.
+ */
+let satelliteElements: Promise<SatelliteElements[]> | null = null;
+/**
+ * The fabricated-traffic dial for the board on screen, rebuilt with every city.
+ *
+ * Held here rather than inside the godmode closure because the panel is mounted
+ * once and the board is not: a dial captured when the panel opened would keep
+ * pushing aircraft at a scene that had been disposed two city switches ago.
+ */
+let trafficDial: TrafficDial | null = null;
+/**
+ * Whether the satellite layer is drawn, remembered across city switches.
+ *
+ * A new board builds a new layer, which starts visible, so a god who turned the
+ * sky off and then changed city would have it come back on — a setting that
+ * quietly undoes itself is worse than one that is not there.
+ */
+let satellitesVisible = true;
 /**
  * The build in progress. Aborting it is what makes a second click on the other
  * city cheap: `createScene` drops the heightfield, resolves `null`, and has
@@ -319,6 +363,11 @@ function updateSun() {
   const env = observe(active.center.lat, active.center.lng, currentInstant(), currentWeather());
   city.setLighting(atmosphere.apply(env));
   city.setSolarElevation(env.sun.elevation);
+  // The override itself, not `currentInstant()`. Handing over a resolved date
+  // would peg the sky to whatever second this ran in, and this runs about once a
+  // second — so an unscrubbed sky would advance in visible steps while the
+  // aircraft beside it moved smoothly. `null` means "read the clock yourself".
+  city.setSkyInstant(instantOverride);
   // The plan view follows the same day the map does. It computes its own
   // palette from this one number rather than reading the rig, because a rig is
   // a set of three.js lights and the minimap has none.
@@ -406,10 +455,47 @@ async function mountCity(id: string) {
     access.can.liveEnvironment && access.feeds?.flights ? tera.flights(region, routes) : null;
   cityFlights = traffic;
 
+  /**
+   * Started here and awaited below, so the fetch overlaps the heightfield build
+   * rather than following it. Gated on the deployment for the same reason the
+   * traffic is: a box with no satellite source answers with an empty catalogue,
+   * and asking it once per page load for that is a request nobody needs.
+   *
+   * Not gated on the visitor. There is no `can.` check because there is nothing
+   * to grant — the objects in this catalogue broadcast their positions to
+   * anybody with a radio, and every element set in it is a US Government work.
+   */
+  if (satelliteElements === null && access.feeds?.satellites) {
+    satelliteElements = tera.satellites();
+  }
+  const elements = (await satelliteElements) ?? [];
+  // Rebuilt per board: the observer is this city's centre. See the note on
+  // `satelliteElements` for why only the elements are shared.
+  const catalogue =
+    elements.length === 0 ? undefined : new SatelliteCatalogue(elements, entry.city.center);
+  // The build may have been abandoned while that was in the air.
+  if (mount.signal.aborted) {
+    traffic?.dispose();
+    if (cityFlights === traffic) cityFlights = null;
+    return;
+  }
+
+  // Wrapped, not replaced: the dial passes the real sky through untouched and
+  // concatenates fabricated aircraft after it, so it composes with a live ADS-B
+  // feed as readily as with the simulator. `cityFlights` stays the unwrapped
+  // source — the corner label asks it whether what is on screen was observed,
+  // and the answer is about the feed rather than about the dial.
+  const dial = withTrafficDial(traffic ?? new SimulatedFlights(routes), region);
+  // Carried across the switch, so a dial somebody set on the last board is still
+  // set on this one.
+  dial.setExtra(trafficDial?.extra() ?? 0);
+  trafficDial = dial;
+
   const handle = await createScene(stage, {
     city: entry.city,
     markerPalette: palette,
-    flights: traffic ?? new SimulatedFlights(routes),
+    flights: dial.source,
+    ...(catalogue ? { satellites: catalogue } : {}),
     onMarkerPick: (m) => showDetail(m ? `${m.label}${m.blurb ? ` — ${m.blurb}` : ""}` : null),
     signal: mount.signal,
     // An abandoned build keeps its worker running for a tick or two after the
@@ -430,6 +516,10 @@ async function mountCity(id: string) {
     return;
   }
   city = handle;
+  // A new board builds a new layer, and a new layer starts visible. Reapply
+  // whatever the panel last said, or the setting silently undoes itself on the
+  // first city switch.
+  handle.setSatellitesVisible(satellitesVisible);
 
   /**
    * The weather, started only now that the board exists.
@@ -1496,6 +1586,32 @@ async function mountGodmode() {
       // on screen is one somebody typed.
       renderSource();
     },
+    /**
+     * Both dials read through the module-level handles rather than closing over
+     * a board, because the panel outlives the city: it is mounted once and every
+     * later `mountCity` swaps `city` and `trafficDial` underneath it. A closure
+     * over the board that was current when the panel opened would go on driving
+     * a disposed scene after the first city switch.
+     */
+    sky: {
+      onExtraTraffic(count) {
+        trafficDial?.setExtra(count);
+      },
+      onSatellitesVisible(visible) {
+        satellitesVisible = visible;
+        city?.setSatellitesVisible(visible);
+      },
+      read() {
+        const counts = city?.satelliteCounts();
+        return {
+          extraTraffic: trafficDial?.extra() ?? 0,
+          trafficIsLive: cityFlights?.live() ?? false,
+          // `total: 0` is a board with no catalogue, which is not the same as a
+          // catalogue with nothing above the horizon — the panel says so.
+          satellites: counts && counts.total > 0 ? counts : null,
+        };
+      },
+    },
   });
 
   // The city was built before this chunk arrived, so its pose editor is built

src/server/wire.ts

@@ -22,6 +22,7 @@
  * | ---------------- | --------------- | --------- |
  * | `GET /health`    | `HealthBody`    | no        |
  * | `GET /flights`   | `FlightsBody`   | yes       |
+ * | `GET /satellites` | `SatellitesBody` | yes    |
  * | `GET /weather`   | `WeatherBody`   | yes       |
  * | `GET /markers`   | `MarkersBody`   | yes       |
  * | `GET /offices/:id` | `OfficeDoc`   | public offices only |
@@ -30,9 +31,11 @@
  * See CONTRACT.md §5.
  */
 
-import type { Marker } from "../engine/types.ts";
+import type { Marker, SatelliteGroup } from "../engine/types.ts";
 import type { Office, Presence } from "../interiors/types.ts";
 
+export type { SatelliteGroup };
+
 /** Path prefix every route lives under. Stated here so both sides read it once. */
 export type ApiBase = "/api/v1";
 
@@ -56,6 +59,7 @@ export interface ErrorBody {
 
 export type WeatherSourceId = "none" | "nws" | "metno" | "openmeteo";
 export type FlightsSourceId = "sim" | "adsb" | "dump1090";
+export type SatellitesSourceId = "none" | "celestrak";
 export type MarkersSourceId = "none" | "file";
 export type AuthMode = "none" | "sso" | "jwt";
 
@@ -75,6 +79,7 @@ export interface HealthBody {
   sources: {
     weather: WeatherSourceId;
     flights: FlightsSourceId;
+    satellites: SatellitesSourceId;
     markers: MarkersSourceId;
   };
   auth: {
@@ -154,6 +159,65 @@ export interface FlightsLiveBody {
 
 export type FlightsBody = FlightsPlanBody | FlightsLiveBody;
 
+// ---- Satellites -----------------------------------------------------------
+
+/**
+ * One satellite, sent as its **element set** rather than as a position.
+ *
+ * The same trick `FlightsPlanBody` plays, for the same reason and with better
+ * justification: a TLE is already a closed-form description of an orbit, valid
+ * for days either side of its epoch, and SGP4 is the function that evaluates it.
+ * Sending positions would mean polling — a satellite crosses the sky in ten
+ * minutes — and would mean two people looking at the same overhead pass from
+ * different machines disagreeing about where it is. Sending the elements means
+ * one cacheable request every few hours and universal agreement, which is
+ * exactly the property the flight plan exists to buy.
+ *
+ * It is also the *honest* shape. CelesTrak publishes element sets; positions are
+ * something a consumer computes. A server that computed them would be inserting
+ * itself into a calculation it adds nothing to.
+ *
+ * `line1` and `line2` are the two 69-character TLE lines, verbatim. They are
+ * carried as strings rather than parsed into fields because SGP4 implementations
+ * take exactly this and every parse in between is a chance to lose a digit.
+ */
+export interface WireSatellite {
+  /** NORAD catalogue number, from columns 3–7 of line 1. Stable for the object's life. */
+  noradId: number;
+  name: string;
+  group: SatelliteGroup;
+  /** The first TLE line, 69 characters, unmodified. */
+  line1: string;
+  /** The second TLE line, 69 characters, unmodified. */
+  line2: string;
+}
+
+/**
+ * The catalogue this box is serving, and when it last managed to fetch one.
+ *
+ * There is no `mode` discriminant here, unlike `FlightsBody`, because there is
+ * only ever one mode: elements. A box with no satellite source configured serves
+ * `source: "none"` and an **empty array** rather than a synthetic constellation,
+ * and that asymmetry with the flight plan is deliberate. An invented aeroplane is
+ * a plausible aeroplane; an invented Starlink is a lie about a specific object
+ * with a catalogue number, and somebody standing in a field with a telescope
+ * would be entitled to be annoyed about it. The sky either has the real thing in
+ * it or it has nothing.
+ */
+export interface SatellitesBody {
+  source: SatellitesSourceId;
+  /**
+   * ISO-8601, the last time a fetch **succeeded**. Not the time of this response:
+   * a body served from a six-hour-old snapshot must say so, because the client
+   * has no other way to tell a fresh catalogue from a stale one and SGP4 accuracy
+   * degrades with distance from the element epoch.
+   */
+  fetchedAt: string;
+  satellites: WireSatellite[];
+  ttlSeconds: number;
+  attribution?: string[];
+}
+
 // ---- Weather --------------------------------------------------------------
 
 /**

src/test/satellites.test.ts

@@ -0,0 +1,200 @@
+/**
+ * `SatelliteCatalogue`: the propagation, and the units it is easy to get wrong.
+ *
+ * SGP4 itself is `satellite.js`'s problem and is not re-tested here — it is a
+ * direct translation of Vallado's reference implementation and has its own
+ * conformance suite. What *is* tested is the chain around it, which is where
+ * every bug in a satellite layer actually lives: ECI to ECF needs the sidereal
+ * angle for the right instant, `ecfToLookAngles` wants the observer in **radians**
+ * and kilometres, and getting either wrong produces angles that are plausible to
+ * look at and completely false.
+ *
+ * The check that catches all of it is the **slant range**. It is a physical
+ * consequence of the geometry rather than a number copied from somewhere: an
+ * object above the horizon can be no closer than its own altitude (straight
+ * overhead) and no further than the horizon-grazing chord, and that is a tight
+ * window — roughly 400–2,400 km for the ISS. Feed the observer degrees instead
+ * of radians and the ranges leave it immediately.
+ *
+ * The layer itself is not tested. It is three.js buffer writes with no branch
+ * worth pinning, and testing it would mean standing up a GL context to assert
+ * that a float landed in an array.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { SatelliteCatalogue, type SatelliteElements } from "../engine/satellites.ts";
+
+/** San Francisco, which is `SAN_FRANCISCO.center` and is the default board. */
+const SF = { lat: 37.7749, lng: -122.4194 };
+
+/**
+ * A real ISS element set. Chosen because the ISS is the one object whose orbit
+ * everybody can check independently — 51.6° inclination, ~420 km, ~92 minutes —
+ * and because at that inclination it genuinely passes over San Francisco
+ * several times a day, which is what makes the visibility test below meaningful
+ * rather than vacuous.
+ */
+const ISS: SatelliteElements = {
+  noradId: 25544,
+  name: "ISS (ZARYA)",
+  group: "station",
+  line1: "1 25544U 98067A   26037.51782528 -.00002182  00000-0 -11606-4 0  2927",
+  line2: "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537",
+};
+
+/**
+ * Near the element set's own epoch — day 37 of 2026. A TLE is good for days
+ * either side of its epoch and degrades after that, so a test that propagated
+ * one six months forward would be measuring the decay of the model rather than
+ * the correctness of this module.
+ */
+const NEAR_EPOCH = new Date(Date.UTC(2026, 1, 6, 12, 0, 0));
+
+/**
+ * Bounds on how far away something above the horizon can be, in kilometres.
+ *
+ * The lower bound is the orbit's own altitude, less a margin for the ellipsoid
+ * and for the object being a little low. The upper bound is the slant range to
+ * an object on the horizon at this altitude, which is about 2,340 km for the
+ * ISS; 2,600 leaves room without admitting anything absurd.
+ */
+const MIN_RANGE_KM = 350;
+const MAX_RANGE_KM = 2600;
+
+/** Walks the whole catalogue, however many budgeted calls that takes. */
+function sweep(catalogue: SatelliteCatalogue, when: Date) {
+  // The budget is two milliseconds a call and this catalogue holds one object,
+  // so one call is a full pass — but looping to `size` keeps the helper honest
+  // if a test ever hands it a larger set.
+  let fixes = catalogue.fixes(when);
+  for (let i = 0; i < catalogue.size; i += 1) fixes = catalogue.fixes(when);
+  return fixes;
+}
+
+describe("reading element sets", () => {
+  it("keeps the ones it can read", () => {
+    assert.equal(new SatelliteCatalogue([ISS], SF).size, 1);
+  });
+
+  it("skips a malformed set rather than throwing", () => {
+    const broken: SatelliteElements = { ...ISS, line1: "1 nonsense", line2: "2 nonsense" };
+    const catalogue = new SatelliteCatalogue([broken, ISS], SF);
+    assert.equal(catalogue.size, 1, "the good set should survive its neighbour");
+  });
+
+  it("reports nothing at all for an empty catalogue, and does not divide by zero", () => {
+    const catalogue = new SatelliteCatalogue([], SF);
+    assert.equal(catalogue.size, 0);
+    assert.deepEqual(catalogue.fixes(NEAR_EPOCH), []);
+  });
+});
+
+describe("the look angles", () => {
+  /**
+   * A day of the ISS over San Francisco, five minutes at a time.
+   *
+   * Sampled rather than asserted at one instant because a single sample proves
+   * nothing: the ISS is below the horizon from any one place about ninety-five
+   * per cent of the time, so a test pinned to one moment would almost certainly
+   * be asserting on an empty array and would pass with the propagation deleted.
+   */
+  function passesOverADay() {
+    const catalogue = new SatelliteCatalogue([ISS], SF);
+    const seen: { elevation: number; azimuth: number; rangeKm: number; shadow: number }[] = [];
+    for (let minute = 0; minute < 24 * 60; minute += 5) {
+      const when = new Date(NEAR_EPOCH.getTime() + minute * 60_000);
+      for (const fix of sweep(catalogue, when)) seen.push(fix);
+    }
+    return seen;
+  }
+
+  it("puts the ISS over San Francisco several times a day", () => {
+    const seen = passesOverADay();
+    // At 51.6° inclination and ~92 minutes, several passes a day is arithmetic,
+    // not luck. Zero would mean the propagation or the observer is wrong.
+    assert.ok(seen.length > 5, `only ${seen.length} five-minute samples were above the horizon`);
+  });
+
+  it("never reports something below the horizon", () => {
+    for (const fix of passesOverADay()) {
+      assert.ok(fix.elevation >= 0, `elevation ${fix.elevation} rad is under the horizon`);
+    }
+  });
+
+  it("keeps elevation inside a quarter turn and azimuth inside a full one", () => {
+    for (const fix of passesOverADay()) {
+      assert.ok(fix.elevation <= Math.PI / 2 + 1e-6, `elevation ${fix.elevation} is past zenith`);
+      assert.ok(Math.abs(fix.azimuth) <= 2 * Math.PI, `azimuth ${fix.azimuth} is off the compass`);
+    }
+  });
+
+  /** The one that catches degrees-for-radians. See the note at the top. */
+  it("reports a slant range the geometry actually permits", () => {
+    const seen = passesOverADay();
+    assert.ok(seen.length > 0);
+    for (const fix of seen) {
+      assert.ok(
+        fix.rangeKm >= MIN_RANGE_KM && fix.rangeKm <= MAX_RANGE_KM,
+        `range ${Math.round(fix.rangeKm)} km is outside ${MIN_RANGE_KM}–${MAX_RANGE_KM} km, ` +
+          `which is not a range a 420 km orbit can be seen at`,
+      );
+    }
+  });
+
+  it("reports a shadow fraction, not a boolean and not a stray number", () => {
+    for (const fix of passesOverADay()) {
+      assert.ok(fix.shadow >= 0 && fix.shadow <= 1, `shadow ${fix.shadow} is not a fraction`);
+    }
+  });
+
+  it("is a pure function of the instant it is given", () => {
+    const a = new SatelliteCatalogue([ISS], SF);
+    const b = new SatelliteCatalogue([ISS], SF);
+    // Two viewers on two machines must agree, which is the whole reason the
+    // server sends elements rather than positions.
+    assert.deepEqual(sweep(a, NEAR_EPOCH), sweep(b, NEAR_EPOCH));
+  });
+
+  it("moves when the clock does", () => {
+    const catalogue = new SatelliteCatalogue([ISS], SF);
+    // A minute apart, so any instant where it is up at both ends has visibly
+    // moved: the ISS crosses the sky in about ten.
+    let differed = false;
+    for (let minute = 0; minute < 24 * 60 && !differed; minute += 5) {
+      const at = new Date(NEAR_EPOCH.getTime() + minute * 60_000);
+      const later = new Date(at.getTime() + 60_000);
+      const [before] = sweep(catalogue, at);
+      const [after] = sweep(catalogue, later);
+      if (before && after) differed = before.azimuth !== after.azimuth;
+    }
+    assert.ok(differed, "the sky never changed across a minute");
+  });
+});
+
+describe("the observer", () => {
+  /**
+   * The bug this exists for is a real one and it is invisible on screen: reusing
+   * one catalogue across a city switch computes the second board's sky from the
+   * first board's coordinates. Everything still renders, and every angle is
+   * wrong. `main.ts` rebuilds per city because of this.
+   */
+  it("is where the catalogue was told it is", () => {
+    const sf = new SatelliteCatalogue([ISS], SF);
+    const antipode = new SatelliteCatalogue([ISS], { lat: -37.7749, lng: 57.5806 });
+
+    let disagreed = false;
+    for (let minute = 0; minute < 24 * 60 && !disagreed; minute += 5) {
+      const when = new Date(NEAR_EPOCH.getTime() + minute * 60_000);
+      const here = sweep(sf, when);
+      const there = sweep(antipode, when);
+      // Two observers on opposite sides of the earth cannot both be looking at
+      // the same low-orbit object.
+      if (here.length > 0 && there.length > 0) {
+        disagreed = here[0]?.azimuth !== there[0]?.azimuth;
+      }
+      if (here.length !== there.length) disagreed = true;
+    }
+    assert.ok(disagreed, "the observer coordinate made no difference to the answer");
+  });
+});

src/tools/godmode.ts

@@ -65,6 +65,7 @@ import {
   type SkyCondition,
   type WeatherObservation,
 } from "../engine/atmosphere.ts";
+import { MAX_EXTRA_TRAFFIC } from "../engine/flights.ts";
 import { daylightPhase, solarPosition, sunTimes } from "../engine/solar.ts";
 import type { Stage } from "../engine/stage.ts";
 
@@ -117,6 +118,44 @@ export interface GodmodePlace {
   marineStrength?(env: Environment): number | null;
 }
 
+/**
+ * The two dials that point at the sky rather than at the light.
+ *
+ * Optional as a unit, and the whole interface is absent rather than each method
+ * being nullable: without a scene there is nothing for either control to do, and
+ * a panel that showed a dead traffic slider next to a live sun scrubber would be
+ * inviting somebody to drag it and conclude the renderer was broken. `main.ts`
+ * passes this only once a board is up.
+ *
+ * `read()` is polled on the panel's own refresh rather than pushed, because both
+ * numbers it returns change without anybody touching a control — traffic goes
+ * live when a fetch lands, and the satellite count changes every time the
+ * propagation sweep completes a pass.
+ */
+export interface GodmodeSky {
+  /**
+   * Fabricate this many aircraft on top of whatever is being drawn, or `0` for
+   * none. Composes with a live feed rather than replacing it; see
+   * `withTrafficDial` in `engine/flights.ts` for why that direction, and for the
+   * argument about fabricating traffic at all.
+   */
+  onExtraTraffic(count: number): void;
+  /** Draw the satellite layer, or do not. */
+  onSatellitesVisible(visible: boolean): void;
+  read(): {
+    extraTraffic: number;
+    /** True when the aircraft underneath the fabricated ones were observed. */
+    trafficIsLive: boolean;
+    /**
+     * Objects above the horizon at the last completed propagation pass, and
+     * element sets this build could read. `null` on the overwhelming majority of
+     * deployments, which serve no catalogue at all — a different state from a
+     * catalogue with nothing in it, and one the panel says out loud.
+     */
+    satellites: { visible: number; total: number } | null;
+  };
+}
+
 export interface GodmodeOptions {
   /**
    * Where to mount. The root positions *itself* — bottom centre, over the map,
@@ -131,6 +170,8 @@ export interface GodmodeOptions {
   onTimeChange(instant: Date | null): void;
   /** A fabricated observation, or `null` for whatever the deployment reports. */
   onWeatherOverride(w: WeatherObservation | null): void;
+  /** Traffic and satellites, when there is a board to point them at. */
+  sky?: GodmodeSky;
   /** Start with the drawer open. Default `false`: the tab, and nothing else. */
   open?: boolean;
   /**
@@ -605,6 +646,46 @@ export function createGodmode(options: GodmodeOptions): Godmode {
     labelled("cond", conditionSelect),
   );
 
+  // ---- Sky ------------------------------------------------------------------
+
+  /**
+   * Built unconditionally and appended only when `options.sky` is present.
+   *
+   * The alternative — branching around the whole block — means every readout
+   * below has to be nullable and `refreshSky` becomes a pyramid of guards. One
+   * check at append time is cheaper to read and the unappended nodes are
+   * garbage a moment later.
+   */
+  const skySection = section("sky");
+  const trafficLine = el("div", "gm-line");
+  const trafficSlider = slider("Fabricated aircraft", 0, MAX_EXTRA_TRAFFIC, 1, (value) => {
+    options.sky?.onExtraTraffic(value);
+    refresh();
+  });
+  const trafficNote = el("div", "gm-hint");
+  trafficNote.textContent =
+    "invented traffic, added to whatever is being drawn — trails run out past ~190 aircraft";
+  const satelliteLine = el("div", "gm-line");
+  const satelliteChips = el("div", "gm-chips");
+  let satellitesOn = true;
+  const satelliteChip = button("gm-chip", "satellites", () => {
+    satellitesOn = !satellitesOn;
+    options.sky?.onSatellitesVisible(satellitesOn);
+    refresh();
+  });
+  const satelliteNote = el("div", "gm-hint");
+  satelliteNote.textContent =
+    "drawn on a dome at true azimuth and elevation — 550 km will not fit on the board";
+  satelliteChips.append(satelliteChip);
+  skySection.body.append(
+    trafficLine,
+    labelled("extra", trafficSlider.el, trafficSlider.value),
+    trafficNote,
+    satelliteLine,
+    satelliteChips,
+    satelliteNote,
+  );
+
   // ---- Performance ----------------------------------------------------------
 
   const perfSection = section("performance");
@@ -650,6 +731,7 @@ export function createGodmode(options: GodmodeOptions): Godmode {
   body.append(
     timeSection.el,
     weatherSection.el,
+    ...(options.sky ? [skySection.el] : []),
     perfSection.el,
     overlaySection.el,
   );
@@ -797,11 +879,46 @@ export function createGodmode(options: GodmodeOptions): Godmode {
     if (open) {
       refreshTime();
       refreshWeather();
+      refreshSky();
       refreshLive();
     }
     refreshHud();
   }
 
+  function refreshSky() {
+    const sky = options.sky;
+    if (!sky) return;
+    const state = sky.read();
+
+    // The slider is not written back from `state` — it is an input somebody may
+    // be dragging, and four writes a second to its value while they do that
+    // fights the pointer. `state.extraTraffic` is read for the line above it,
+    // which is the readout, and the two agree because the app is the only other
+    // writer and there is nothing else to disagree with.
+    setText(
+      trafficLine,
+      `traffic  ${state.trafficIsLive ? "observed" : "simulated"}` +
+        `${state.extraTraffic > 0 ? `  +${state.extraTraffic} fabricated` : ""}`,
+    );
+    setText(trafficSlider.value, String(state.extraTraffic));
+
+    // Three states, not two, and the middle one is the one worth distinguishing:
+    // a deployment with no catalogue is not the same as a catalogue on a night
+    // when nothing happens to be up, and an operator debugging an empty sky needs
+    // to know which they have.
+    if (state.satellites === null) {
+      setText(satelliteLine, "satellites  no catalogue — set TERA_SATELLITES_SOURCE=celestrak");
+    } else {
+      setText(
+        satelliteLine,
+        `satellites  ${state.satellites.visible} above the horizon ` +
+          `of ${state.satellites.total} tracked`,
+      );
+    }
+    satelliteChip.disabled = state.satellites === null;
+    satelliteChip.setAttribute("aria-pressed", String(satellitesOn && state.satellites !== null));
+  }
+
   function refreshBanner() {
     const parts: string[] = [];
     if (override) parts.push(`time ${fmtStamp(override)}`);