@johnmorrisdotca/chikyu-earth 0.7.0 → 0.8.0

package/dist/space/element.d.ts

@@ -1,5 +1,7 @@
 import type { GeoPoint } from "../types.ts";
 import { setThreeLoader } from "../realistic/shared.ts";
+import type { SatelliteInfo, SatelliteRef, Satellites } from "../satellites/types.ts";
+import { type SatelliteStyle } from "./satellite-layer.ts";
 import { type ScaleMode } from "./scale.ts";
 import { BODY_NAMES, type BodyName, type BodyPainter } from "./scene.ts";
 export { BODY_NAMES, type BodyName };
@@ -61,6 +63,18 @@ export type SpaceState = "loading" | "live" | "unavailable" | "lost" | "idle";
  * ```
  */
 export type SpacePreset = "earth" | "moon" | "sun" | "inner" | "solar-system";
+type SatelliteStats = {
+    groups: number;
+    placed: number;
+    tooFast: boolean;
+    propagations: number;
+    lastBatchMs: number;
+    maxBatchMs: number;
+    updateMs: number;
+    maxUpdateMs: number;
+    averageUpdateMs: number;
+    updates: number;
+};
 /**
  * The `<chikyu-space>` custom element: the Earth, the Moon, the Sun and the planets where they are at a date and time, drawn with three.js through the shared renderer. It takes `center`, `time` (`now` or an ISO date), `speed` (1 is real time, 0 holds, 86400 is a day a second, negative runs backwards), `scale` (`compressed` or `true`), `labels` and `orbits` (`off` hides them); positions are computed in the browser by astronomy-engine, an optional peer dependency. It draws only when something changes, and nothing while it is out of sight.
  *
@@ -103,6 +117,36 @@ export declare class ChikyuSpace extends HTMLElement {
     /** The body the camera looks at: at zoom 1 it fills the view; the yaw and tilt turn the camera round it. */
     get body(): BodyName;
     set body(name: BodyName);
+    /**
+     * Show a group of satellites (made by `createSatellites`) under a name, or take the group away with `null`. A group is one draw call however many satellites it holds. Giving the name of a group
+     * that is already shown replaces it. `style`: `color` and `size` (CSS pixels) of the dots, and `orbits` to draw every orbit (only for a group of 40 or fewer, such as the stations).
+     * The groups are placed by SGP4 about once a second and interpolated between, and are hidden while the clock runs faster than `MAX_SATELLITE_SPEED`.
+     *
+     * @param group - The group's name, for `showSatellites`, `selectSatellite` and the events.
+     * @param satellites - The group, or `null` to remove it.
+     * @param style - How to draw it.
+     */
+    setSatellites(group: string, satellites: Satellites | null, style?: Partial<SatelliteStyle>): void;
+    /** Show or hide a group without losing it. */
+    showSatellites(group: string, on: boolean): void;
+    /** The groups now set, with how many satellites each holds and whether it is shown. */
+    get satelliteGroups(): {
+        name: string;
+        count: number;
+        visible: boolean;
+    }[];
+    /** Mark one satellite: a larger ring round it, its orbit drawn, and its name beside it. `null` lets it go. */
+    selectSatellite(ref: SatelliteRef | null): void;
+    /** The satellite marked by `selectSatellite` or by a press on it, if any. */
+    get selectedSatellite(): SatelliteRef | null;
+    /** Facts about one satellite at the moment shown (name, number, element age, height, speed, period); undefined if it cannot be placed then. */
+    satelliteInfo(ref: SatelliteRef): SatelliteInfo | undefined;
+    /** The words shown beside each body, for a page in another language (`{ Mars: "火星" }`). A body left out keeps its English name. */
+    get bodyNames(): Partial<Record<BodyName, string>>;
+    set bodyNames(value: Partial<Record<BodyName, string>>);
+    /** What a screen reader hears after a body's name: "choose to look at it" by default, or the page's own words. */
+    get bodyHint(): string;
+    set bodyHint(value: string);
     /** The radius and the distance from the Earth of a body now, for a page's own caption. */
     bodyInfo(name: BodyName): BodyInfo;
     /** The zoom that shows a part of the sky: the Earth alone, the Moon's orbit, the Sun, the planets out to Mars, or all of them, at this scale and moment. */
@@ -125,6 +169,7 @@ export declare class ChikyuSpace extends HTMLElement {
         };
         time: number;
         lookups: number;
+        satellites: SatelliteStats;
     };
 }
 declare global {

package/dist/space/element.js

@@ -1,7 +1,9 @@
 import { createGate, frameCap } from "../realistic/gate.js";
 import { setThreeLoader, takeRenderer } from "../realistic/shared.js";
 import { MAX_TEXTURE } from "../realistic/tiers.js";
+import { MAX_SATELLITE_SPEED } from "../satellites/limits.js";
 import { AU_IN_EARTH_RADII, EARTH_RADIUS_KM, frameAt } from "./ephemeris.js";
+import { MAX_ORBIT_GROUP } from "./satellite-layer.js";
 import { placeAround, placeMoon, placeSun } from "./scale.js";
 import { BODY_NAMES, createSpaceItem, FIT_DISTANCE, newSpaceModel } from "./scene.js";
 export { BODY_NAMES };
@@ -29,6 +31,9 @@ export { setThreeLoader };
 const RAD = Math.PI / 180;
 /** The Earth's own turn, degrees a second. */
 const EARTH_RATE = 360 / 86_164.0905;
+/** The quickest a satellite goes round, degrees a second (a low orbit: 88 minutes). */
+const SATELLITE_RATE = 360 / (88 * 60);
+const SATELLITE_COLORS = ["#ffd54f", "#7fd4ff", "#ff8fa3", "#9ef0a8"];
 const REAL_TIME_TICK_MS = 60_000;
 const readCentre = (value) => {
     if (!value)
@@ -72,6 +77,9 @@ export class ChikyuSpace extends HTMLElement {
     #last = 0;
     #pool = new Map();
     #places;
+    #chosenLabel;
+    #names = {};
+    #hint = "choose to look at it";
     #tiers = {};
     connectedCallback() {
         this.#model.centre = readCentre(this.getAttribute("center")) ?? this.#model.centre;
@@ -82,12 +90,13 @@ export class ChikyuSpace extends HTMLElement {
         this.#model.labels = this.getAttribute("labels") !== "off";
         this.#model.orbits = this.getAttribute("orbits") !== "off";
         this.#model.stepMs = Math.max(1000, Math.abs(this.#speed) * 1000);
+        this.#model.speed = this.#speed;
         if (!this.hasAttribute("role"))
             this.setAttribute("role", "img");
         if (!this.hasAttribute("aria-label"))
             this.setAttribute("aria-label", "The Earth, the Moon, the Sun and the planets in their places for the date shown");
         const root = this.shadowRoot ?? this.attachShadow({ mode: "open" });
-        root.innerHTML = `<style>:host{display:block;aspect-ratio:1/1;position:relative;overflow:hidden}#stage,#labels{position:absolute;inset:0}#labels{pointer-events:none;overflow:hidden}.sp-label{position:absolute;left:0;top:0;margin:0;padding:0;border:0;background:none;font:12px/16px system-ui,-apple-system,sans-serif;color:#fff;white-space:nowrap;text-shadow:0 0 3px #000,0 0 3px #000;will-change:transform;pointer-events:none}.sp-label:focus-visible{outline:2px solid #6cd0ff;outline-offset:2px;border-radius:4px}.sp-label::before{content:"";display:inline-block;width:5px;height:5px;margin:0 5px 1px -2px;border-radius:50%;background:#fff}.sp-label[hidden]{display:none}</style><div id="stage"></div><div id="labels" aria-hidden="true"></div>`;
+        root.innerHTML = `<style>:host{display:block;aspect-ratio:1/1;position:relative;overflow:hidden}#stage,#labels{position:absolute;inset:0}#labels{pointer-events:none;overflow:hidden}.sp-label{position:absolute;left:0;top:0;margin:0;padding:0;border:0;background:none;font:12px/16px system-ui,-apple-system,sans-serif;color:#fff;white-space:nowrap;text-shadow:0 0 3px #000,0 0 3px #000;will-change:transform;pointer-events:none}.sp-label:focus-visible{outline:2px solid #6cd0ff;outline-offset:2px;border-radius:4px}.sp-label::before{content:"";display:inline-block;width:5px;height:5px;margin:0 5px 1px -2px;border-radius:50%;background:#fff}.sp-label[hidden]{display:none}.sp-sat{position:absolute;left:0;top:0;font:12px/16px system-ui,-apple-system,sans-serif;color:#fff;white-space:nowrap;text-shadow:0 0 3px #000,0 0 3px #000;will-change:transform;pointer-events:none}.sp-sat[hidden]{display:none}</style><div id="stage"></div><div id="labels" aria-hidden="true"></div>`;
         this.#stage = root.getElementById("stage");
         this.#labelBox = root.getElementById("labels");
         this.#pool.clear();
@@ -110,6 +119,8 @@ export class ChikyuSpace extends HTMLElement {
                 this.#tiers[layer] = width;
             },
             onLabels: (places) => this.#placeLabels(places),
+            onSelected: (place) => this.#placeChosen(place),
+            onSatellitesError: (error) => this.dispatchEvent(new CustomEvent("chikyu-satellites-unavailable", { detail: { reason: error instanceof Error ? error.message : String(error) } })),
             ...(painter ? { painter } : {}),
         });
         this.#view = taken.renderer.view(this.#stage, item, { still: null });
@@ -178,6 +189,7 @@ export class ChikyuSpace extends HTMLElement {
     }
     set speed(value) {
         this.#speed = Number.isFinite(value) ? value : 1;
+        this.#model.speed = this.#speed;
         this.#model.stepMs = Math.max(1000, Math.abs(this.#speed) * 1000);
         this.#last = performance.now();
         this.#schedule();
@@ -225,6 +237,85 @@ export class ChikyuSpace extends HTMLElement {
         this.#model.focus = name;
         this.#gate?.request();
     }
+    // --- satellites ---------------------------------------------------------------------------------------------------------------------------------
+    /**
+     * Show a group of satellites (made by `createSatellites`) under a name, or take the group away with `null`. A group is one draw call however many satellites it holds. Giving the name of a group
+     * that is already shown replaces it. `style`: `color` and `size` (CSS pixels) of the dots, and `orbits` to draw every orbit (only for a group of 40 or fewer, such as the stations).
+     * The groups are placed by SGP4 about once a second and interpolated between, and are hidden while the clock runs faster than `MAX_SATELLITE_SPEED`.
+     *
+     * @param group - The group's name, for `showSatellites`, `selectSatellite` and the events.
+     * @param satellites - The group, or `null` to remove it.
+     * @param style - How to draw it.
+     */
+    setSatellites(group, satellites, style = {}) {
+        const groups = this.#model.satellites.groups;
+        if (satellites === null) {
+            groups.delete(group);
+            if (this.#model.satellites.selected?.group === group)
+                this.#model.satellites.selected = null;
+        }
+        else {
+            const was = groups.get(group);
+            groups.set(group, {
+                satellites,
+                color: style.color ?? was?.color ?? SATELLITE_COLORS[groups.size % SATELLITE_COLORS.length],
+                size: style.size ?? was?.size ?? 3,
+                orbits: (style.orbits ?? was?.orbits ?? false) && satellites.count <= MAX_ORBIT_GROUP,
+                visible: was?.visible ?? true,
+            });
+        }
+        this.#last = performance.now();
+        this.#schedule();
+        this.#gate?.request();
+    }
+    /** Show or hide a group without losing it. */
+    showSatellites(group, on) {
+        const found = this.#model.satellites.groups.get(group);
+        if (!found || found.visible === on)
+            return;
+        found.visible = on;
+        this.#schedule();
+        this.#gate?.request();
+    }
+    /** The groups now set, with how many satellites each holds and whether it is shown. */
+    get satelliteGroups() {
+        return [...this.#model.satellites.groups].map(([name, group]) => ({ name, count: group.satellites.count, visible: group.visible }));
+    }
+    /** Mark one satellite: a larger ring round it, its orbit drawn, and its name beside it. `null` lets it go. */
+    selectSatellite(ref) {
+        const found = ref ? this.#model.satellites.groups.get(ref.group) : undefined;
+        this.#model.satellites.selected = ref && found && ref.index >= 0 && ref.index < found.satellites.count ? { group: ref.group, index: ref.index } : null;
+        if (this.#chosenLabel)
+            this.#chosenLabel.hidden = true;
+        this.#gate?.request();
+    }
+    /** The satellite marked by `selectSatellite` or by a press on it, if any. */
+    get selectedSatellite() {
+        const chosen = this.#model.satellites.selected;
+        return chosen ? { ...chosen } : null;
+    }
+    /** Facts about one satellite at the moment shown (name, number, element age, height, speed, period); undefined if it cannot be placed then. */
+    satelliteInfo(ref) {
+        return this.#model.satellites.groups.get(ref.group)?.satellites.info(ref.index, this.#model.time);
+    }
+    /** The words shown beside each body, for a page in another language (`{ Mars: "火星" }`). A body left out keeps its English name. */
+    get bodyNames() {
+        return { ...this.#names };
+    }
+    set bodyNames(value) {
+        this.#names = { ...value };
+        for (const [name, button] of this.#pool)
+            this.#nameLabel(button, name);
+    }
+    /** What a screen reader hears after a body's name: "choose to look at it" by default, or the page's own words. */
+    get bodyHint() {
+        return this.#hint;
+    }
+    set bodyHint(value) {
+        this.#hint = value;
+        for (const [name, button] of this.#pool)
+            this.#nameLabel(button, name);
+    }
     /** The radius and the distance from the Earth of a body now, for a page's own caption. */
     bodyInfo(name) {
         const frame = this.#model.drawn?.frame ?? frameAt(this.#model.time);
@@ -259,25 +350,49 @@ export class ChikyuSpace extends HTMLElement {
             assets: { entries: stats?.assets.entries ?? 0, refs: stats?.assets.refs ?? 0 },
             time: this.#model.time,
             lookups: this.#model.lookups,
+            satellites: this.#satelliteStats(),
         };
     }
+    #satelliteStats() {
+        const drawn = this.#model.satellites.drawn;
+        let propagations = 0;
+        let lastBatchMs = 0;
+        let maxBatchMs = 0;
+        for (const group of this.#model.satellites.groups.values()) {
+            propagations += group.satellites.propagations;
+            lastBatchMs = Math.max(lastBatchMs, group.satellites.timing.lastBatchMs);
+            maxBatchMs = Math.max(maxBatchMs, group.satellites.timing.maxBatchMs);
+        }
+        return { groups: this.#model.satellites.groups.size, placed: drawn.placed, tooFast: drawn.tooFast, propagations, lastBatchMs, maxBatchMs, updateMs: drawn.updateMs, maxUpdateMs: drawn.maxUpdateMs, averageUpdateMs: drawn.updates ? drawn.totalMs / drawn.updates : 0, updates: drawn.updates };
+    }
     // --- the game clock ----------------------------------------------------------------------------------------------------------------------------
     #readSpeed() {
         const raw = this.getAttribute("speed");
         const value = raw === null || raw === "" ? 1 : Number(raw);
         return Number.isFinite(value) ? value : 1;
     }
-    /** While time runs, draw as often as it shows: real time once a minute; faster time as often as the Earth's turn moves a pixel (1 to 30 times a second). */
+    /** Is anything on show that moves faster than the Earth turns: a group of satellites the clock is slow enough to place? */
+    #satellitesMoving() {
+        if (Math.abs(this.#speed) > MAX_SATELLITE_SPEED)
+            return false;
+        for (const group of this.#model.satellites.groups.values())
+            if (group.visible && group.satellites.count > 0)
+                return true;
+        return false;
+    }
+    /** While time runs, draw as often as it shows: real time once a minute; faster time as often as the Earth's turn moves a pixel (1 to 30 times a second). Satellites go round in 90 minutes, so with a group on show real time draws once a second, and 1 a second is all a reader who asked for reduced motion gets. */
     #schedule() {
         clearTimeout(this.#timer);
         this.#timer = undefined;
         if (!this.isConnected || this.#speed === 0)
             return;
-        const realTime = this.#speed === 1 && this.#mode === "now";
+        const satellites = this.#satellitesMoving();
         const radius = this.#model.drawn?.radiusPx ?? 200;
-        const pixelsPerSecond = EARTH_RATE * RAD * Math.abs(this.#speed) * radius;
-        const perSecond = Math.min(30, Math.max(1, pixelsPerSecond));
-        const wait = realTime || this.#speed === 1 ? REAL_TIME_TICK_MS : 1000 / perSecond;
+        const pixelsPerSecond = (satellites ? SATELLITE_RATE : EARTH_RATE) * RAD * Math.abs(this.#speed) * radius;
+        let perSecond = Math.min(30, Math.max(1, pixelsPerSecond));
+        if (satellites && matchMedia("(prefers-reduced-motion: reduce)").matches)
+            perSecond = 1;
+        const wait = !satellites && this.#speed === 1 ? REAL_TIME_TICK_MS : 1000 / perSecond;
         this.#timer = setTimeout(this.#tick, wait);
     }
     #tick = () => {
@@ -307,8 +422,7 @@ export class ChikyuSpace extends HTMLElement {
                 button.type = "button";
                 button.className = "sp-label";
                 button.dataset["body"] = name;
-                button.textContent = name;
-                button.setAttribute("aria-label", `${name}: choose to look at it`);
+                this.#nameLabel(button, name);
                 box.append(button);
                 this.#pool.set(name, button);
                 label = button;
@@ -323,6 +437,32 @@ export class ChikyuSpace extends HTMLElement {
             label.style.transform = `translate(${Math.round(at.x + Math.max(4, Math.min(at.r, 40)))}px,${Math.round(at.y - 8)}px)`;
         }
     }
+    #placeChosen(place) {
+        const box = this.#labelBox;
+        if (!box)
+            return;
+        if (!place) {
+            if (this.#chosenLabel)
+                this.#chosenLabel.hidden = true;
+            return;
+        }
+        const chosen = this.#model.satellites.selected;
+        const name = chosen ? this.satelliteInfo(chosen)?.name : undefined;
+        if (!this.#chosenLabel) {
+            this.#chosenLabel = box.ownerDocument.createElement("div");
+            this.#chosenLabel.className = "sp-sat";
+            box.append(this.#chosenLabel);
+        }
+        if (this.#chosenLabel.textContent !== (name ?? ""))
+            this.#chosenLabel.textContent = name ?? "";
+        this.#chosenLabel.hidden = !name;
+        this.#chosenLabel.style.transform = `translate(${Math.round(place.x + 10)}px,${Math.round(place.y - 8)}px)`;
+    }
+    #nameLabel(button, name) {
+        const text = this.#names[name] ?? name;
+        button.textContent = text;
+        button.setAttribute("aria-label", `${text}: ${this.#hint}`);
+    }
     // A body is chosen by pressing on it or on its name (and by Tab and Enter on the name); a drag that turns the view is not a choice.
     #downX = 0;
     #downY = 0;
@@ -334,11 +474,18 @@ export class ChikyuSpace extends HTMLElement {
         window.addEventListener("pointerup", this.#up, { capture: true, once: true });
     };
     #up = (event) => {
-        if (Math.hypot(event.clientX - this.#downX, event.clientY - this.#downY) > 6 || !this.#places)
+        if (Math.hypot(event.clientX - this.#downX, event.clientY - this.#downY) > 6)
             return;
         const rect = this.getBoundingClientRect();
         const x = event.clientX - rect.left;
         const y = event.clientY - rect.top;
+        const satellite = this.#model.pick?.(x, y, 12);
+        if (satellite) {
+            this.dispatchEvent(new CustomEvent("chikyu-satellite-click", { detail: { ...satellite, info: this.satelliteInfo(satellite) }, bubbles: true, composed: true }));
+            return;
+        }
+        if (!this.#places)
+            return;
         let best;
         let bestD = Infinity;
         for (const name of BODY_NAMES) {

package/dist/space/satellite-layer.d.ts

@@ -0,0 +1,53 @@
+import type * as THREE from "three";
+import type { SatelliteRef, Satellites } from "../satellites/types.ts";
+import type { ThreeParts } from "../realistic/textures.ts";
+type Three = ThreeParts;
+/** How a group looks: the colour of its dots and their size in CSS pixels, and whether every orbit is drawn (only for a small group). */
+export interface SatelliteStyle {
+    color: string;
+    size: number;
+    orbits: boolean;
+}
+export interface SatelliteGroupState extends SatelliteStyle {
+    satellites: Satellites;
+    visible: boolean;
+}
+/** The part of the space view's model the satellites read and write. */
+export interface SatelliteState {
+    groups: Map<string, SatelliteGroupState>;
+    selected: SatelliteRef | null;
+    /** Written at each draw: satellites placed, whether the clock is too fast for the groups, and the milliseconds the last update took. */
+    drawn: {
+        placed: number;
+        tooFast: boolean;
+        updateMs: number;
+        maxUpdateMs: number;
+        updates: number;
+        totalMs: number;
+    };
+}
+export declare const newSatelliteState: () => SatelliteState;
+/** The most orbits a group may draw all at once, one line each. */
+export declare const MAX_ORBIT_GROUP = 40;
+export interface SatelliteLayer {
+    /** Place every shown group for `model.time` and the chosen satellite exactly. */
+    update(time: number, speed: number): void;
+    /** The satellite nearest to a point of the view (CSS pixels) within `radius`, if one is in front of the Earth. */
+    pick(x: number, y: number, camera: THREE.PerspectiveCamera, size: {
+        width: number;
+        height: number;
+    }, radius: number): SatelliteRef | null;
+    /** Where the chosen satellite is in the view, if it is. */
+    place(camera: THREE.PerspectiveCamera, size: {
+        width: number;
+        height: number;
+    }): {
+        x: number;
+        y: number;
+    } | null;
+    /** The chosen satellite's position and velocity now (Earth radii, km/s), or false. */
+    exact(ref: SatelliteRef, time: number, out: Float64Array): boolean;
+    dispose(): void;
+}
+export declare function createSatelliteLayer(three: Three, scene: THREE.Scene, state: SatelliteState, ratio: () => number): SatelliteLayer;
+export {};

package/dist/space/satellite-layer.js

@@ -0,0 +1,230 @@
+import { MAX_SATELLITE_SPEED } from "../satellites/limits.js";
+export const newSatelliteState = () => ({ groups: new Map(), selected: null, drawn: { placed: 0, tooFast: false, updateMs: 0, maxUpdateMs: 0, updates: 0, totalMs: 0 } });
+/** The most orbits a group may draw all at once, one line each. */
+export const MAX_ORBIT_GROUP = 40;
+const ORBIT_POINTS = 120;
+const ORBIT_REFRESH_GAME_MS = 30 * 60_000;
+const ORBIT_REFRESH_WALL_MS = 1000;
+const POINT_VERT = /* glsl */ `
+uniform float size;
+void main() {
+  gl_PointSize = size;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}`;
+const POINT_FRAG = /* glsl */ `
+uniform vec3 tint;
+uniform float ring;
+void main() {
+  float d = length(gl_PointCoord - vec2(0.5));
+  if (d > 0.5) discard;
+  float a = ring > 0.5 ? smoothstep(0.30, 0.38, d) * (1.0 - smoothstep(0.44, 0.5, d)) : smoothstep(0.5, 0.2, d);
+  gl_FragColor = vec4(tint, a);
+}`;
+export function createSatelliteLayer(three, scene, state, ratio) {
+    if (!three.Points)
+        throw new Error("Satellites need `Points` from three.js: add it to the parts the three loader hands over (see setThreeLoader)");
+    const Points = three.Points;
+    const drawn = new Map();
+    const tmp = new Float64Array(6);
+    const projected = new three.Vector3();
+    const selectedMaterial = new three.ShaderMaterial({ vertexShader: POINT_VERT, fragmentShader: POINT_FRAG, uniforms: { size: { value: 14 }, tint: { value: new three.Color("#ffffff") }, ring: { value: 1 } }, transparent: true, depthWrite: false });
+    const selectedPosition = new Float32Array(3);
+    const selectedGeometry = new three.BufferGeometry();
+    selectedGeometry.setAttribute("position", new three.BufferAttribute(selectedPosition, 3));
+    const selectedPoints = new Points(selectedGeometry, selectedMaterial);
+    selectedPoints.frustumCulled = false;
+    selectedPoints.renderOrder = 6;
+    selectedPoints.visible = false;
+    scene.add(selectedPoints);
+    const selectedLine = { positions: new Float32Array(ORBIT_POINTS * 3), geometry: new three.BufferGeometry(), material: new three.LineBasicMaterial({ color: "#ffffff", transparent: true, opacity: 0.85 }) };
+    selectedLine.geometry.setAttribute("position", new three.BufferAttribute(selectedLine.positions, 3));
+    const selectedLoop = new three.LineLoop(selectedLine.geometry, selectedLine.material);
+    selectedLoop.frustumCulled = false;
+    selectedLoop.visible = false;
+    scene.add(selectedLoop);
+    let selectedKey = "";
+    let selectedAt = 0;
+    let selectedWall = 0;
+    const drop = (entry) => {
+        scene.remove(entry.points);
+        entry.geometry.dispose();
+        entry.material.dispose();
+        for (const line of entry.lines) {
+            scene.remove(line.loop);
+            line.geometry.dispose();
+            line.loop.material.dispose();
+        }
+    };
+    const orbitsOf = (entry, group, time, wall) => {
+        const wanted = group.orbits && group.satellites.count <= MAX_ORBIT_GROUP;
+        if (!wanted) {
+            for (const line of entry.lines)
+                line.loop.visible = false;
+            return;
+        }
+        if (entry.lines.length === group.satellites.count && Math.abs(time - entry.linesAt) < ORBIT_REFRESH_GAME_MS && wall - entry.linesWall < 60_000) {
+            for (const line of entry.lines)
+                line.loop.visible = true;
+            return;
+        }
+        if (entry.lines.length === group.satellites.count && wall - entry.linesWall < ORBIT_REFRESH_WALL_MS)
+            return;
+        while (entry.lines.length < group.satellites.count) {
+            const positions = new Float32Array(ORBIT_POINTS * 3);
+            const geometry = new three.BufferGeometry();
+            geometry.setAttribute("position", new three.BufferAttribute(positions, 3));
+            const material = new three.LineBasicMaterial({ color: group.color, transparent: true, opacity: 0.45 });
+            const loop = new three.LineLoop(geometry, material);
+            loop.frustumCulled = false;
+            scene.add(loop);
+            entry.lines.push({ loop, geometry, positions });
+        }
+        for (let i = 0; i < group.satellites.count; i += 1) {
+            const line = entry.lines[i];
+            const path = group.satellites.orbit(i, time, ORBIT_POINTS);
+            line.positions.set(path.subarray(0, ORBIT_POINTS * 3));
+            line.geometry.getAttribute("position").needsUpdate = true;
+            line.loop.visible = group.satellites.visible(i) || path.some((v) => v !== 0);
+        }
+        entry.linesAt = time;
+        entry.linesWall = wall;
+    };
+    const find = (ref) => state.groups.get(ref.group)?.satellites;
+    return {
+        update(time, speed) {
+            const started = performance.now();
+            const tooFast = Math.abs(speed) > MAX_SATELLITE_SPEED;
+            const step = Math.min(60_000, Math.max(1000, Math.abs(speed) * 1000));
+            for (const [name, entry] of drawn) {
+                if (state.groups.get(name)?.satellites !== entry.source) {
+                    drop(entry);
+                    drawn.delete(name);
+                }
+            }
+            let placed = 0;
+            for (const [name, group] of state.groups) {
+                let entry = drawn.get(name);
+                if (!entry) {
+                    const positions = new Float32Array(group.satellites.count * 3);
+                    const geometry = new three.BufferGeometry();
+                    const attribute = new three.BufferAttribute(positions, 3);
+                    geometry.setAttribute("position", attribute);
+                    const material = new three.ShaderMaterial({ vertexShader: POINT_VERT, fragmentShader: POINT_FRAG, uniforms: { size: { value: group.size * ratio() }, tint: { value: new three.Color(group.color) }, ring: { value: 0 } }, transparent: true, depthWrite: false });
+                    const points = new Points(geometry, material);
+                    points.frustumCulled = false;
+                    points.renderOrder = 5;
+                    scene.add(points);
+                    entry = { source: group.satellites, points, geometry, material, positions, attribute, lines: [], linesAt: Number.NaN, linesWall: 0, style: "" };
+                    drawn.set(name, entry);
+                }
+                const style = `${group.color}|${group.size}|${ratio()}`;
+                if (style !== entry.style) {
+                    entry.style = style;
+                    entry.material.uniforms["size"].value = group.size * ratio();
+                    entry.material.uniforms["tint"].value.set(group.color);
+                }
+                const show = group.visible && !tooFast;
+                entry.points.visible = show;
+                if (!show) {
+                    for (const line of entry.lines)
+                        line.loop.visible = false;
+                    continue;
+                }
+                group.satellites.setStep(step);
+                group.satellites.at(time, entry.positions);
+                entry.attribute.needsUpdate = true;
+                placed += group.satellites.placed;
+                orbitsOf(entry, group, time, started);
+            }
+            const chosen = state.selected;
+            const set = chosen ? find(chosen) : undefined;
+            if (chosen && set && set.exact(chosen.index, time, tmp)) {
+                selectedPosition[0] = tmp[0];
+                selectedPosition[1] = tmp[1];
+                selectedPosition[2] = tmp[2];
+                selectedGeometry.getAttribute("position").needsUpdate = true;
+                selectedPoints.visible = true;
+                const key = `${chosen.group}:${chosen.index}`;
+                if (key !== selectedKey || (Math.abs(time - selectedAt) > ORBIT_REFRESH_GAME_MS && started - selectedWall > ORBIT_REFRESH_WALL_MS)) {
+                    selectedKey = key;
+                    selectedAt = time;
+                    selectedWall = started;
+                    selectedLine.positions.set(set.orbit(chosen.index, time, ORBIT_POINTS).subarray(0, ORBIT_POINTS * 3));
+                    selectedLine.geometry.getAttribute("position").needsUpdate = true;
+                }
+                selectedLoop.visible = true;
+                selectedMaterial.uniforms["size"].value = 14 * ratio();
+            }
+            else {
+                selectedPoints.visible = false;
+                selectedLoop.visible = false;
+                selectedKey = "";
+            }
+            state.drawn.placed = placed;
+            state.drawn.tooFast = tooFast;
+            state.drawn.updateMs = performance.now() - started;
+            if (state.drawn.updateMs > state.drawn.maxUpdateMs)
+                state.drawn.maxUpdateMs = state.drawn.updateMs;
+            state.drawn.updates += 1;
+            state.drawn.totalMs += state.drawn.updateMs;
+        },
+        pick(x, y, camera, size, radius) {
+            let best = null;
+            let bestD = radius * radius;
+            const c = camera.position;
+            for (const [name, entry] of drawn) {
+                const group = state.groups.get(name);
+                if (!group || !entry.points.visible)
+                    continue;
+                const p = entry.positions;
+                for (let i = 0; i < group.satellites.count; i += 1) {
+                    if (!group.satellites.visible(i))
+                        continue;
+                    projected.set(p[i * 3], p[i * 3 + 1], p[i * 3 + 2]).project(camera);
+                    if (projected.z > 1 || projected.z < -1)
+                        continue;
+                    const dx = ((projected.x + 1) / 2) * size.width - x;
+                    const dy = ((1 - projected.y) / 2) * size.height - y;
+                    const d = dx * dx + dy * dy;
+                    if (d > bestD)
+                        continue;
+                    // behind the Earth: the line from the camera to the satellite passes through the unit sphere before it gets there
+                    const px = p[i * 3] - c.x;
+                    const py = p[i * 3 + 1] - c.y;
+                    const pz = p[i * 3 + 2] - c.z;
+                    const len2 = px * px + py * py + pz * pz;
+                    const t = Math.max(0, Math.min(1, -(c.x * px + c.y * py + c.z * pz) / len2));
+                    const nx = c.x + px * t;
+                    const ny = c.y + py * t;
+                    const nz = c.z + pz * t;
+                    if (nx * nx + ny * ny + nz * nz < 0.998)
+                        continue;
+                    best = { group: name, index: i };
+                    bestD = d;
+                }
+            }
+            return best;
+        },
+        place(camera, size) {
+            if (!selectedPoints.visible)
+                return null;
+            projected.set(selectedPosition[0], selectedPosition[1], selectedPosition[2]).project(camera);
+            if (projected.z > 1 || projected.z < -1)
+                return null;
+            return { x: ((projected.x + 1) / 2) * size.width, y: ((1 - projected.y) / 2) * size.height };
+        },
+        exact(ref, time, out) {
+            return find(ref)?.exact(ref.index, time, out) ?? false;
+        },
+        dispose() {
+            for (const entry of drawn.values())
+                drop(entry);
+            drawn.clear();
+            scene.remove(selectedPoints, selectedLoop);
+            selectedGeometry.dispose();
+            selectedMaterial.dispose();
+            selectedLine.geometry.dispose();
+            selectedLine.material.dispose();
+        },
+    };
+}

package/dist/space/scene.d.ts

@@ -4,6 +4,8 @@ import { type ThreeParts } from "../realistic/textures.ts";
 import type { Layer } from "../realistic/tiers.ts";
 import { type Frame, type PlanetName, type Vec3 } from "./ephemeris.ts";
 import { type ScaleMode } from "./scale.ts";
+import type { SatelliteRef } from "../satellites/types.ts";
+import { type SatelliteState } from "./satellite-layer.ts";
 type Three = ThreeParts;
 /** The camera's distance, in Earth radii, at which the Earth fills the view at zoom 1. */
 export declare const FIT_DISTANCE = 3.4;
@@ -61,6 +63,12 @@ export interface SpaceModel {
     } | null;
     /** How many times astronomy-engine has been asked for a frame. */
     lookups: number;
+    /** Game seconds a second (the clock's speed). */
+    speed: number;
+    /** The satellites shown, the one chosen, and what the last draw did with them. */
+    satellites: SatelliteState;
+    /** The satellite at a point of the view (CSS pixels), within a radius, if a draw has been made and one is there. */
+    pick: ((x: number, y: number, radius: number) => SatelliteRef | null) | null;
     ratio(): number;
 }
 export declare const newSpaceModel: () => SpaceModel;
@@ -113,6 +121,13 @@ export interface SpaceDeps {
     onTier?: (layer: Layer, width: number) => void;
     /** Where each body is on the screen, in CSS pixels in the box, or null when it is behind the camera. Called at each draw. */
     onLabels?: (places: Record<BodyName, BodyPlace | null>) => void;
+    /** Where the chosen satellite is on the screen, or null. Called at each draw while a satellite is chosen (and once when it is let go). */
+    onSelected?: (place: {
+        x: number;
+        y: number;
+    } | null) => void;
+    /** The satellites could not be drawn (the three.js parts handed over lack `Points`). */
+    onSatellitesError?: (error: unknown) => void;
     /** How the Sun and the planets are drawn; left out, plain spheres in the right colours (see `BodyPainter`). */
     painter?: BodyPainter;
 }