@johnmorrisdotca/chikyu-earth 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.8.0
+
+Satellites on the space view, the space view in the embed, and the demo's space controls in Japanese.
+
+- **Satellites** (`@johnmorrisdotca/chikyu-earth/satellites`, new, and `<chikyu-space>`): `createSatellites(elements)` turns orbital elements into positions with SGP4, and `space.setSatellites("stations", group)` draws them: a group is **one draw call** however many it holds
+  (`THREE.Points`), each shown or hidden by name (`showSatellites`), with their orbits (`orbits: true` for a group of 40 or fewer), a ring and an orbit for a chosen one (`selectSatellite`, `satelliteInfo`) and `chikyu-satellite-click` for a press on one
+  (not on one behind the Earth). **The package fetches nothing and ships no orbital data**: your page passes in elements in CelesTrak's GP JSON format (`ElementSet`), and the guide has the rules for getting them (CelesTrak's usage policy; Space-Track's
+  agreement does not let an account holder pass data on, so it is not used). Elements more than 14 days from the moment shown (`maxAgeDays`) are left out. [docs/satellites.md](docs/satellites.md), the [satellites guide](docs/guides/satellites.md) (and in Japanese).
+- **SGP4 about once a second, not once a frame**: satellite.js 6.0.2 (MIT, a new optional peer dependency; 10 KB gzipped, plain JavaScript; version 7 pulls WASM helper files that bundlers choke on) is run for the whole group at two moments a step apart, and every
+  position between is an interpolation (a metre at 1 second, a few kilometres at 60). Above 60 times real time the groups are hidden and SGP4 does not run (`MAX_SATELLITE_SPEED`); a chosen satellite is still placed exactly. The package's own part is 2.7 KB minified
+  for the maths and 5.1 KB for the drawing (3.6 KB gzipped together). A unit test checks that a satellite's longitude from the scene's axes and sidereal time agrees with satellite.js's own within 0.02 degree, and an end-to-end test centres the view under the ISS (worked
+  out in the test) and finds it in the middle of the Earth's disc.
+- **Budget, each line tested** (`e2e/satellites.gl.ts`, 6,000 made-up satellites spread round their orbits, together with the demo's 2,252 real ones): paused, 0 GL draw calls, 0 frame requests and 0 SGP4 calls in 3.5 s; at 60 times real time 29.0 frames a second, 8,242 SGP4 calls a second (one for
+  each satellite), 34.2 GL draw calls a frame against 33.4 without the 6,000 (the group is one), 0.09 ms of JavaScript a frame on average and 2.6 ms for the longest SGP4 batch of 8,252; at real time 1.00 frames a second and 2,249 SGP4 calls a second for 2,252
+  satellites; at 3,600 times real time the groups are hidden, 0 SGP4 calls and 29 frames a second; with reduced motion 1.00 frames a second at 60 times; nothing drawn out of sight or in a hidden tab; a group taken away frees its buffer; a lost context comes back with the
+  satellites. The freeze test has a third look, the space view with satellites on, and its look-changing rounds show the stations and Starlink every time (GPU objects flat at 85 after the warm-up round). The ten-minute soak adds and removes the 6,000, chooses satellites and runs
+  past the speed limit: 964 steps, JS heap 13.73 to 14.04 MB after garbage collection (while the 6,000 are on it is 20.4 MB, and it returns), GPU objects 123 to 123, 28.5 frames a second on average, one WebGL context. The soak and the new tests now run with no motion preference, at the full 30 frames a second.
+- **Demo**: a "Satellites" row (Stations, Starlink, and Find: ISS, Tiangong) in the space look, and a line about what is chosen (name, height, speed, period, age of its elements). It uses **one snapshot of CelesTrak's lists from 2 November 2026** in a file of the demo site's own
+  (`demo/celestrak-snapshot.json`, 330 KB, 105 KB gzipped, fetched only when a group is asked for): all 20 stations and every fifth Starlink satellite (2,232 of 11,156), credited on the page and in NOTICE.md. A snapshot more than 14 days old shows the day it was taken instead of today.
+  `scripts/make-satellite-snapshot.mjs` makes the file from two downloaded lists and fetches nothing.
+- **The space view in the embed** (`embed.html?look=space`): `time`, `speed` (still by default), `scale`, `body`, `zoom` (earth, moon, sun, inner, solar-system), `orbits`, `labels`, and `satellites=stations,starlink` with `sat=25544`. One context, a capped canvas, no controls, nothing but its own files, 0 draws at rest,
+  at most 30 a second at a day a second, nothing in a hidden tab (`e2e/embed.gl.ts`). The embed guide, in both languages, lists them.
+- **Japanese for the demo's space controls**: Space, Time, Scale, Go to, Look at, every body's name, Orbits, Names, the scale note, the body and satellite facts and the notices, through `demo/words.js`; the names drawn beside the bodies change too (`element.bodyNames`, `element.bodyHint`). A browser test opens the Japanese
+  page and fails on any English word left in a control, apart from ISS, Starlink, CelesTrak, SGP4 and km.
+- **Docs**: a satellites guide in English and Japanese, a page for the new entry point and every export (TSDoc and an example each), a usage example run by `pnpm test:usage` (a Vite page with the ISS on the space view, opened in a browser and made to place it; and the same elements in Node), README section, and screenshots.
+- `ThreeParts` has an optional `Points`: a three.js subset handed over by `setThreeLoader` needs it only for satellites (the demo's `three-subset.ts` has it).
+- The CHANGELOG of 0.7.0, whose published tarball showed the family-parts notes under the 0.6.0 heading, is as fixed in 6f26012; this entry is under its own heading.
+
 ## 0.7.0
 
 The space view can look at any body, bodies can be chosen, and how the Sun and the planets are drawn is a seam another package can fill.
@@ -9,6 +37,20 @@ The space view can look at any body, bodies can be chosen, and how the Sun and t
 - **A seam for drawing the bodies** (`BodyPainter`, `setBodyPainter`, `plainPainter` from `@johnmorrisdotca/chikyu-earth/space`): the space view keeps each body's place, size, light direction, name and orbit, and asks a painter only for what to draw there (an object of radius 1; `light(toSun)` each draw; the Sun's turns to face the camera). The default is what 0.6.0 drew: spheres in the planets' colours and a glow for the Sun. John chose a separate package (wakusei-planets) for the bodies' own looks, so chikyu ships no planet pictures and no rings; the Earth and the Moon keep theirs.
 - Tests: e2e (a body looked at, its name chosen by keyboard, a press on it chooses it, a drag that turns the view does not) and a unit test of the default painter.
 
+### The family's published parts: demo, embed, docs and usage
+
+Chikyu Earth now has what every package of the family has, and it was missing from 0.3.0 to 0.5.0.
+
+- **Demo on GitHub Pages**, set as the repository's and the package's homepage: <https://johnmorrisdotca.github.io/chikyu-earth/>, with the family header (the kazoku-ui language picker, English and Japanese, and theme switch, the table cloths and the Help switch), light and dark, and the family footer. `pnpm site` builds it, and the Pages workflow publishes it on every push to `main`.
+- **An embed page**, `embed.html`, for an `<iframe>` with no script of your own: `?look=line|thick|realistic`, `center`, `graticule`, `turn=0|1|auto`, `time`, `clouds`, `lights`. Still by default, no controls, no location prompt; it draws only when something changes and nothing while hidden. Tested in Chromium and WebKit, and on the realistic look: one WebGL context, canvas inside its budget, nothing drawn at rest.
+- **A documentation site** at `/docs/`: a page for every export (from its TSDoc, with an example that is run when the site is built), ten guides in English and in Japanese, one language to a page, search, `llms.txt` and the family's header. Every export of every entry point has a summary, `@param`, `@returns` and an `@example` that imports the package by its name; `pnpm check` fails when one does not.
+- **Every way to use it, written down and tested** (`pnpm test:usage`): a script tag from jsDelivr and from unpkg, the realistic Earth from a CDN, the shared controls, Vite, webpack, React (and a server render of it), Vue, Svelte, Angular, an iframe, TypeScript types and Node. Each example is built or run against the package as npm packs it, opened in a browser and made to show a globe; the guides and the README must hold the same text word for word.
+- **`look` attribute**: `<chikyu-earth look="thick">` is the new name of `style`, which frameworks read as CSS (React refuses a string `style`). `style` still works.
+- **Types for the tags**: `document.querySelector("chikyu-earth")` is a `ChikyuEarth` (and `"chikyu-earth-realistic"`, `"chikyu-space"`) once the element's entry is imported.
+- **A freeze test in the release** (`e2e/freeze.demo.ts`, `pnpm test:freeze`): at rest nothing is drawn and no frame asked for, turning draws at most once for each frame of the page and asks for one frame at a time, out of sight or in a hidden tab nothing is drawn, the canvas stays inside 6 million pixels and 4096 a side on a 5K screen at a pixel ratio of 2 in the Earth from space and the space view, and six rounds of changing the look leave the GPU objects flat in one WebGL context and let the context go at the end. Every Chromium project draws WebGL in software, never on the machine's graphics card. The release workflow runs it (`freeze-command`, kazoku-ui 0.9.1).
+- **The family's must-have list**, checked: `scripts/check-standard.mjs` (kazoku-ui's, unchanged) fails `pnpm check` when a package lacks its demo, embed page, docs site with Japanese twins, family files or tested usage.
+- **Family files**: `family-template.mjs` and `family-readme.mjs` of 2026-11-02 with Chikyu Earth added to the family's list (33 packages), `family.css`, and the README's "The family" block. Added to the list here only; the other packages take the new files when they are next touched.
+
 ## 0.6.0 (never published on its own: it ships in 0.7.0)
 
 The Sun, the Moon and the planets: `<chikyu-space>`, an optional entry point, under the same performance budget as the Earth from space.
@@ -28,20 +70,6 @@ The Sun, the Moon and the planets: `<chikyu-space>`, an optional entry point, un
 - **Research, no code** ([docs/satellite-sources.md](docs/satellite-sources.md), MODULES-85): CelesTrak (grey), Space-Track (red for a package), the r/SpaceX API (archived, offline), Launch Library 2 (grey), Wikipedia and Wikidata
   (green) for launches; the recommendation is a satellite view that takes elements the page supplies. John chooses before MODULES-86 and MODULES-87 start.
 
-### The family's published parts: demo, embed, docs and usage
-
-Chikyu Earth now has what every package of the family has, and it was missing from 0.3.0 to 0.5.0.
-
-- **Demo on GitHub Pages**, set as the repository's and the package's homepage: <https://johnmorrisdotca.github.io/chikyu-earth/>, with the family header (the kazoku-ui language picker, English and Japanese, and theme switch, the table cloths and the Help switch), light and dark, and the family footer. `pnpm site` builds it, and the Pages workflow publishes it on every push to `main`.
-- **An embed page**, `embed.html`, for an `<iframe>` with no script of your own: `?look=line|thick|realistic`, `center`, `graticule`, `turn=0|1|auto`, `time`, `clouds`, `lights`. Still by default, no controls, no location prompt; it draws only when something changes and nothing while hidden. Tested in Chromium and WebKit, and on the realistic look: one WebGL context, canvas inside its budget, nothing drawn at rest.
-- **A documentation site** at `/docs/`: a page for every export (from its TSDoc, with an example that is run when the site is built), ten guides in English and in Japanese, one language to a page, search, `llms.txt` and the family's header. Every export of every entry point has a summary, `@param`, `@returns` and an `@example` that imports the package by its name; `pnpm check` fails when one does not.
-- **Every way to use it, written down and tested** (`pnpm test:usage`): a script tag from jsDelivr and from unpkg, the realistic Earth from a CDN, the shared controls, Vite, webpack, React (and a server render of it), Vue, Svelte, Angular, an iframe, TypeScript types and Node. Each example is built or run against the package as npm packs it, opened in a browser and made to show a globe; the guides and the README must hold the same text word for word.
-- **`look` attribute**: `<chikyu-earth look="thick">` is the new name of `style`, which frameworks read as CSS (React refuses a string `style`). `style` still works.
-- **Types for the tags**: `document.querySelector("chikyu-earth")` is a `ChikyuEarth` (and `"chikyu-earth-realistic"`, `"chikyu-space"`) once the element's entry is imported.
-- **A freeze test in the release** (`e2e/freeze.demo.ts`, `pnpm test:freeze`): at rest nothing is drawn and no frame asked for, turning draws at most once for each frame of the page and asks for one frame at a time, out of sight or in a hidden tab nothing is drawn, the canvas stays inside 6 million pixels and 4096 a side on a 5K screen at a pixel ratio of 2 in the Earth from space and the space view, and six rounds of changing the look leave the GPU objects flat in one WebGL context and let the context go at the end. Every Chromium project draws WebGL in software, never on the machine's graphics card. The release workflow runs it (`freeze-command`, kazoku-ui 0.9.1).
-- **The family's must-have list**, checked: `scripts/check-standard.mjs` (kazoku-ui's, unchanged) fails `pnpm check` when a package lacks its demo, embed page, docs site with Japanese twins, family files or tested usage.
-- **Family files**: `family-template.mjs` and `family-readme.mjs` of 2026-11-02 with Chikyu Earth added to the family's list (33 packages), `family.css`, and the README's "The family" block. Added to the list here only; the other packages take the new files when they are next touched.
-
 ## 0.5.0
 
 The Earth from space, and markers for any place on either globe, both under a hard performance budget.

package/NOTICE.md

@@ -44,6 +44,17 @@ item to: NASA's Scientific Visualization Studio" (Visualizer Ernie Wright, USRA;
 `<chikyu-space>` computes positions with **astronomy-engine** (https://github.com/cosinekitty/astronomy, MIT, copyright Don Cross), the page's own optional peer dependency: this package does not
 bundle or ship it. The planets are drawn as plain colours, from no picture.
 
+## Satellites
+
+`<chikyu-space>` draws satellites from orbital elements that **your page** passes in; this package fetches and ships none. SGP4 is run by **satellite.js** (https://github.com/shashwatak/satellite-js, MIT, by
+Shashwat Kandadai and contributors), the page's own optional peer dependency: this package does not bundle or ship it.
+
+The demo's file `demo/celestrak-snapshot.json` (the demo site only, not the npm package) holds element sets from **CelesTrak** (https://celestrak.org, T.S. Kelso), which serves the U.S. Space Force's
+18th Space Defense Squadron's general-perturbation (GP) data and, for Starlink, SpaceX's own supplemental elements. It is one download of the `stations` list and one of the `starlink` list on 2026-11-02
+(about 17:07 UTC), within CelesTrak's usage policy (https://celestrak.org/usage-policy.php, read 2026-11-02: one download per update per list, nothing fetched at a visitor's request), with every fifth Starlink satellite
+kept (2,232 of 11,156), as numbers only. CelesTrak states no licence or credit rule for the data; it is credited on the demo page, and the demo shows the age of the elements. The tier is "grey" in John's
+terms: a snapshot with credit, never a live fetch. Space-Track's data are not used: its user agreement does not let an account holder pass the data on.
+
 ## Sun position
 
 `src/realistic/sun.ts` uses the low-precision solar position formulas of NOAA's solar calculator (https://gml.noaa.gov/grad/solcalc/, after Jean Meeus,

package/README.md

@@ -135,6 +135,20 @@ computed in the browser by astronomy-engine (MIT), nothing is fetched. [docs/spa
 
 <p align="center"><img alt="The solar system on 2 November 2026 in the compressed scale: orbits round the Sun, the planets named" src="docs/images/space-solar.png" width="420"></p>
 
+## Satellites
+
+The ISS, a space station or thousands of Starlink satellites at the places SGP4 puts them for the date and time shown, on `<chikyu-space>`: a group is one draw call however many it holds, press one to get its name, height and speed, and its orbit is drawn. Chikyu fetches nothing: your page passes in orbital elements (CelesTrak's JSON, within its usage policy), and satellite.js (MIT, an optional peer) does the maths about once a second, with every frame between interpolated. A group is hidden while the clock runs faster than 60 times real time. The guide has the rules for getting elements and the budget, each line tested: [satellites guide](docs/guides/satellites.md), [docs/satellites.md](docs/satellites.md).
+
+<p align="center"><img alt="The ISS, ringed, over South Africa on 3 November 2026, with its orbit and the stations' orbits" src="docs/images/space-sat-iss.png" width="420"></p>
+
+```ts no-run
+import "@johnmorrisdotca/chikyu-earth/space/element";
+import { createSatellites, type ElementSet } from "@johnmorrisdotca/chikyu-earth/satellites";
+
+const elements: ElementSet[] = await (await fetch("/my-celestrak-copy.json")).json();
+document.querySelector("chikyu-space")!.setSatellites("stations", createSatellites(elements), { orbits: true });
+```
+
 ## Markers
 
 Mark any place at `[lon, lat]` with a label, colour or icon, in groups you can show or hide, on either look. Chikyu ships no places; yours move with the globe, fade on the far side, make room

package/dist/realistic/textures.d.ts

@@ -14,6 +14,9 @@ import { type Layer } from "./tiers.ts";
  */
 export type ThreeParts = {
     [Name in "Texture" | "BufferGeometry" | "BufferAttribute" | "ShaderMaterial" | "Group" | "Mesh" | "Scene" | "OrthographicCamera" | "PerspectiveCamera" | "Vector3" | "WebGLRenderer" | "RepeatWrapping" | "ClampToEdgeWrapping" | "LinearMipmapLinearFilter" | "LinearFilter" | "BackSide" | "DoubleSide" | "LineLoop" | "LineBasicMaterial" | "Color"]: (typeof THREE)[Name];
+} & {
+    /** Only the satellites use it, so a loader that hands over a subset of three.js without it still draws everything else. */
+    Points?: typeof THREE.Points;
 };
 /** Milliseconds a lower texture size must be enough before the larger one is let go. */
 export declare const DOWNGRADE_AFTER_MS = 4000;

package/dist/satellites/index.d.ts

@@ -0,0 +1,3 @@
+export { createSatellites, type SatellitesOptions } from "./track.ts";
+export { DEFAULT_MAX_AGE_DAYS, MAX_SATELLITE_SPEED } from "./limits.ts";
+export type { ElementSet, RefusedElementSet, SatelliteInfo, SatelliteRef, Satellites } from "./types.ts";

package/dist/satellites/index.js

@@ -0,0 +1,3 @@
+// The satellites' pure parts: orbital elements in, positions out (SGP4 by satellite.js, an optional peer). They import on a server. The space view takes a group with `setSatellites`.
+export { createSatellites } from "./track.js";
+export { DEFAULT_MAX_AGE_DAYS, MAX_SATELLITE_SPEED } from "./limits.js";

package/dist/satellites/limits.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How old, in days, an element set may be at the moment shown before the satellite is left out: SGP4's error grows by a few kilometres a day, so a fortnight is as far as a picture should trust.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_MAX_AGE_DAYS } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * console.log(DEFAULT_MAX_AGE_DAYS);
+ * ```
+ */
+export declare const DEFAULT_MAX_AGE_DAYS = 14;
+/**
+ * The fastest clock, in game seconds a second, at which the space view still places a group of satellites: above it the two moments SGP4 is run at would be too far apart to interpolate, so the group is hidden rather than drawn wrongly. A satellite that was chosen with `selectSatellite` or ridden along is still placed exactly, one SGP4 call a frame.
+ *
+ * @example
+ * ```ts
+ * import { MAX_SATELLITE_SPEED } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * console.log(MAX_SATELLITE_SPEED);
+ * ```
+ */
+export declare const MAX_SATELLITE_SPEED = 60;

package/dist/satellites/limits.js

@@ -0,0 +1,23 @@
+// The satellites' two limits, apart from the SGP4 code so the space view can read them without needing satellite.js.
+/**
+ * How old, in days, an element set may be at the moment shown before the satellite is left out: SGP4's error grows by a few kilometres a day, so a fortnight is as far as a picture should trust.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_MAX_AGE_DAYS } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * console.log(DEFAULT_MAX_AGE_DAYS);
+ * ```
+ */
+export const DEFAULT_MAX_AGE_DAYS = 14;
+/**
+ * The fastest clock, in game seconds a second, at which the space view still places a group of satellites: above it the two moments SGP4 is run at would be too far apart to interpolate, so the group is hidden rather than drawn wrongly. A satellite that was chosen with `selectSatellite` or ridden along is still placed exactly, one SGP4 call a frame.
+ *
+ * @example
+ * ```ts
+ * import { MAX_SATELLITE_SPEED } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * console.log(MAX_SATELLITE_SPEED);
+ * ```
+ */
+export const MAX_SATELLITE_SPEED = 60;

package/dist/satellites/track.d.ts

@@ -0,0 +1,50 @@
+import type { ElementSet, Satellites } from "./types.ts";
+/**
+ * What `createSatellites` can be told.
+ *
+ * @example
+ * ```ts
+ * import type { SatellitesOptions } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const options: SatellitesOptions = { maxAgeDays: 7 };
+ * console.log(options.maxAgeDays);
+ * ```
+ */
+export interface SatellitesOptions {
+    /** The oldest an element set may be at the moment shown, in days (14 by default). */
+    maxAgeDays?: number;
+}
+/**
+ * Make a group of satellites from their element sets. Each starts SGP4 once here; one that does not (bad numbers, decayed at its own epoch) is listed in `refused` and left out.
+ * It needs satellite.js (MIT, an optional peer dependency) and imports in a browser or on a server.
+ *
+ * @param sets - Element sets in CelesTrak's JSON format (`ElementSet`), fetched by your page.
+ * @param options - `maxAgeDays`: the oldest an element set may be at the moment shown.
+ * @returns The group: `at(ms, out)` for positions, `exact`, `orbit`, `info`, and counters.
+ *
+ * @example
+ * ```ts
+ * import { createSatellites } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const group = createSatellites([
+ *   {
+ *     OBJECT_NAME: "ISS (ZARYA)",
+ *     OBJECT_ID: "1998-067A",
+ *     EPOCH: "2026-11-02T10:25:21.580320",
+ *     MEAN_MOTION: 15.49150046,
+ *     ECCENTRICITY: 0.0007139,
+ *     INCLINATION: 51.6332,
+ *     RA_OF_ASC_NODE: 335.9757,
+ *     ARG_OF_PERICENTER: 339.3739,
+ *     MEAN_ANOMALY: 20.6961,
+ *     NORAD_CAT_ID: 25544,
+ *     BSTAR: 0.00012,
+ *     MEAN_MOTION_DOT: 0.0001,
+ *     MEAN_MOTION_DDOT: 0,
+ *   },
+ * ]);
+ * const noon = Date.UTC(2026, 10, 2, 12);
+ * console.log(group.count, group.info(0, noon)?.altitudeKm.toFixed(0));
+ * ```
+ */
+export declare function createSatellites(sets: readonly ElementSet[], options?: SatellitesOptions): Satellites;

package/dist/satellites/track.js

@@ -0,0 +1,227 @@
+// SGP4 for a group of satellites, kept cheap: the whole group is run at two moments a step apart and every position in between is an interpolation, so the cost is one batch a step
+// (about once a second), never one a frame. satellite.js (MIT) does the SGP4 itself; this file never touches the screen and imports on a server.
+import { json2satrec, sgp4 } from "satellite.js";
+import { DEFAULT_MAX_AGE_DAYS } from "./limits.js";
+/** The Earth's mean radius in kilometres: the unit of every position here (the same as the space view's). */
+const EARTH_RADIUS_KM = 6371;
+const DAY_MS = 86_400_000;
+const MIN_STEP_MS = 1000;
+const MAX_STEP_MS = 60_000;
+const epochOf = (text) => Date.parse(/[zZ]|[+-]\d\d:?\d\d$/.test(text) ? text : `${text}Z`);
+/**
+ * Make a group of satellites from their element sets. Each starts SGP4 once here; one that does not (bad numbers, decayed at its own epoch) is listed in `refused` and left out.
+ * It needs satellite.js (MIT, an optional peer dependency) and imports in a browser or on a server.
+ *
+ * @param sets - Element sets in CelesTrak's JSON format (`ElementSet`), fetched by your page.
+ * @param options - `maxAgeDays`: the oldest an element set may be at the moment shown.
+ * @returns The group: `at(ms, out)` for positions, `exact`, `orbit`, `info`, and counters.
+ *
+ * @example
+ * ```ts
+ * import { createSatellites } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const group = createSatellites([
+ *   {
+ *     OBJECT_NAME: "ISS (ZARYA)",
+ *     OBJECT_ID: "1998-067A",
+ *     EPOCH: "2026-11-02T10:25:21.580320",
+ *     MEAN_MOTION: 15.49150046,
+ *     ECCENTRICITY: 0.0007139,
+ *     INCLINATION: 51.6332,
+ *     RA_OF_ASC_NODE: 335.9757,
+ *     ARG_OF_PERICENTER: 339.3739,
+ *     MEAN_ANOMALY: 20.6961,
+ *     NORAD_CAT_ID: 25544,
+ *     BSTAR: 0.00012,
+ *     MEAN_MOTION_DOT: 0.0001,
+ *     MEAN_MOTION_DDOT: 0,
+ *   },
+ * ]);
+ * const noon = Date.UTC(2026, 10, 2, 12);
+ * console.log(group.count, group.info(0, noon)?.altitudeKm.toFixed(0));
+ * ```
+ */
+export function createSatellites(sets, options = {}) {
+    const maxAgeDays = options.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS;
+    const maxAgeMs = maxAgeDays * DAY_MS;
+    const recs = [];
+    const usable = [];
+    const epochs = [];
+    const refused = [];
+    for (const set of sets) {
+        const epoch = epochOf(set.EPOCH);
+        const refuse = (reason) => void refused.push({ name: set.OBJECT_NAME, noradId: set.NORAD_CAT_ID, reason });
+        if (!Number.isFinite(epoch)) {
+            refuse("the epoch is not a date");
+            continue;
+        }
+        try {
+            const rec = json2satrec(set);
+            const start = sgp4(rec, 0);
+            if (!start || !start.position || !start.velocity || rec.error !== 0) {
+                refuse("SGP4 could not start from these elements");
+                continue;
+            }
+            recs.push(rec);
+            usable.push(set);
+            epochs.push(epoch);
+        }
+        catch (error) {
+            refuse(error instanceof Error ? error.message : "SGP4 could not start from these elements");
+        }
+    }
+    const n = recs.length;
+    let a = new Float32Array(n * 3);
+    let b = new Float32Array(n * 3);
+    let okA = new Uint8Array(n);
+    let okB = new Uint8Array(n);
+    const shown = new Uint8Array(n);
+    let aMs = 0;
+    let bMs = 0;
+    let ready = false;
+    let stepMs = MIN_STEP_MS;
+    let propagations = 0;
+    let placed = 0;
+    const timing = { lastBatchMs: 0, maxBatchMs: 0 };
+    /** SGP4 for the whole group at one moment, into `buffer` in the space view's axes (TEME x, z, -y: x to the vernal equinox, y north). */
+    const sample = (buffer, ok, ms) => {
+        const started = performance.now();
+        for (let i = 0; i < n; i += 1) {
+            const epoch = epochs[i];
+            if (Math.abs(ms - epoch) > maxAgeMs) {
+                ok[i] = 0;
+                continue;
+            }
+            propagations += 1;
+            const result = sgp4(recs[i], (ms - epoch) / 60_000);
+            const p = result && result.position;
+            if (!p || !Number.isFinite(p.x)) {
+                ok[i] = 0;
+                continue;
+            }
+            ok[i] = 1;
+            buffer[i * 3] = p.x / EARTH_RADIUS_KM;
+            buffer[i * 3 + 1] = p.z / EARTH_RADIUS_KM;
+            buffer[i * 3 + 2] = -p.y / EARTH_RADIUS_KM;
+        }
+        timing.lastBatchMs = performance.now() - started;
+        if (timing.lastBatchMs > timing.maxBatchMs)
+            timing.maxBatchMs = timing.lastBatchMs;
+    };
+    const exactAt = (index, ms, out) => {
+        const epoch = epochs[index];
+        if (epoch === undefined || Math.abs(ms - epoch) > maxAgeMs)
+            return false;
+        propagations += 1;
+        const result = sgp4(recs[index], (ms - epoch) / 60_000);
+        if (!result || !result.position || !result.velocity || !Number.isFinite(result.position.x))
+            return false;
+        out[0] = result.position.x / EARTH_RADIUS_KM;
+        out[1] = result.position.z / EARTH_RADIUS_KM;
+        out[2] = -result.position.y / EARTH_RADIUS_KM;
+        out[3] = result.velocity.x;
+        out[4] = result.velocity.z;
+        out[5] = -result.velocity.y;
+        return true;
+    };
+    return {
+        count: n,
+        sets: usable,
+        refused,
+        maxAgeDays,
+        get propagations() {
+            return propagations;
+        },
+        timing,
+        get placed() {
+            return placed;
+        },
+        setStep(ms) {
+            const next = Math.min(MAX_STEP_MS, Math.max(MIN_STEP_MS, Math.round(ms)));
+            if (next !== stepMs) {
+                stepMs = next;
+                ready = false;
+            }
+        },
+        at(ms, out) {
+            if (n === 0)
+                return;
+            if (!ready || ms < aMs || ms > bMs) {
+                if (ready && ms > bMs && ms - bMs < stepMs) {
+                    [a, b] = [b, a];
+                    [okA, okB] = [okB, okA];
+                    aMs = bMs;
+                    bMs = aMs + stepMs;
+                    sample(b, okB, bMs);
+                }
+                else if (ready && ms < aMs && aMs - ms < stepMs) {
+                    [a, b] = [b, a];
+                    [okA, okB] = [okB, okA];
+                    bMs = aMs;
+                    aMs = bMs - stepMs;
+                    sample(a, okA, aMs);
+                }
+                else {
+                    aMs = ms;
+                    bMs = ms + stepMs;
+                    sample(a, okA, aMs);
+                    sample(b, okB, bMs);
+                    ready = true;
+                }
+            }
+            const t = (ms - aMs) / (bMs - aMs);
+            let count = 0;
+            for (let i = 0; i < n; i += 1) {
+                const k = i * 3;
+                if (okA[i] === 1 && okB[i] === 1) {
+                    out[k] = a[k] + (b[k] - a[k]) * t;
+                    out[k + 1] = a[k + 1] + (b[k + 1] - a[k + 1]) * t;
+                    out[k + 2] = a[k + 2] + (b[k + 2] - a[k + 2]) * t;
+                    shown[i] = 1;
+                    count += 1;
+                }
+                else {
+                    out[k] = 0;
+                    out[k + 1] = 0;
+                    out[k + 2] = 0;
+                    shown[i] = 0;
+                }
+            }
+            placed = count;
+        },
+        visible: (index) => shown[index] === 1,
+        exact: exactAt,
+        orbit(index, ms, points) {
+            const path = new Float32Array((points + 1) * 3);
+            const period = 1440 / (usable[index]?.MEAN_MOTION || 15);
+            const one = new Float64Array(6);
+            for (let k = 0; k < points; k += 1) {
+                if (exactAt(index, ms + (k / points) * period * 60_000, one))
+                    path.set(one.subarray(0, 3), k * 3);
+                else if (k > 0)
+                    path.copyWithin(k * 3, (k - 1) * 3, k * 3);
+            }
+            path.copyWithin(points * 3, 0, 3);
+            return path;
+        },
+        info(index, ms) {
+            const set = usable[index];
+            const one = new Float64Array(6);
+            if (!set || !exactAt(index, ms, one))
+                return undefined;
+            const info = {
+                index,
+                name: set.OBJECT_NAME,
+                noradId: set.NORAD_CAT_ID,
+                objectId: set.OBJECT_ID,
+                epochMs: epochs[index],
+                ageDays: (ms - epochs[index]) / DAY_MS,
+                altitudeKm: Math.hypot(one[0], one[1], one[2]) * EARTH_RADIUS_KM - EARTH_RADIUS_KM,
+                speedKmS: Math.hypot(one[3], one[4], one[5]),
+                periodMinutes: 1440 / set.MEAN_MOTION,
+                inclinationDeg: set.INCLINATION,
+            };
+            return info;
+        },
+    };
+}

package/dist/satellites/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * One satellite's orbital elements in the "GP" format that CelesTrak and Space-Track both serve as JSON (CCSDS OMM, one object per satellite). Only these fields are read.
+ * The package fetches nothing: your page gets the elements (see the satellites guide for the rules of the sources) and passes them in.
+ *
+ * @example
+ * ```ts
+ * import type { ElementSet } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const iss: ElementSet = {
+ *   OBJECT_NAME: "ISS (ZARYA)",
+ *   OBJECT_ID: "1998-067A",
+ *   EPOCH: "2026-11-02T10:25:21.580320",
+ *   MEAN_MOTION: 15.49150046,
+ *   ECCENTRICITY: 0.0007139,
+ *   INCLINATION: 51.6332,
+ *   RA_OF_ASC_NODE: 335.9757,
+ *   ARG_OF_PERICENTER: 339.3739,
+ *   MEAN_ANOMALY: 20.6961,
+ *   NORAD_CAT_ID: 25544,
+ *   BSTAR: 0.00012,
+ *   MEAN_MOTION_DOT: 0.0001,
+ *   MEAN_MOTION_DDOT: 0,
+ * };
+ * console.log(iss.OBJECT_NAME);
+ * ```
+ */
+export interface ElementSet {
+    OBJECT_NAME: string;
+    OBJECT_ID?: string;
+    /** The moment the elements describe, ISO 8601 in UTC (a trailing `Z` is optional). */
+    EPOCH: string;
+    /** Revolutions a day. */
+    MEAN_MOTION: number;
+    ECCENTRICITY: number;
+    /** Degrees. */
+    INCLINATION: number;
+    /** Degrees. */
+    RA_OF_ASC_NODE: number;
+    /** Degrees. */
+    ARG_OF_PERICENTER: number;
+    /** Degrees. */
+    MEAN_ANOMALY: number;
+    NORAD_CAT_ID: number;
+    BSTAR: number;
+    MEAN_MOTION_DOT: number;
+    MEAN_MOTION_DDOT: number;
+    EPHEMERIS_TYPE?: number;
+    CLASSIFICATION_TYPE?: string;
+    ELEMENT_SET_NO?: number;
+    REV_AT_EPOCH?: number;
+}
+/**
+ * What a page can tell a reader about one satellite at a moment: its name, its number, how old its elements are, how high and how fast it is.
+ *
+ * @example
+ * ```ts
+ * import type { SatelliteInfo } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const describe = (info: SatelliteInfo): string => `${info.name}: ${info.altitudeKm.toFixed(0)} km up, ${info.speedKmS.toFixed(2)} km/s`;
+ * console.log(typeof describe);
+ * ```
+ */
+export interface SatelliteInfo {
+    /** Where it is in its group. */
+    index: number;
+    name: string;
+    /** The NORAD catalogue number. */
+    noradId: number;
+    /** The international designator (for example `1998-067A`), when the elements carry one. */
+    objectId: string | undefined;
+    /** The moment of its elements, in milliseconds since the Unix epoch. */
+    epochMs: number;
+    /** Days between the elements' moment and the moment asked about (negative before it). */
+    ageDays: number;
+    /** Height above the mean Earth radius (6371 km) at that moment. */
+    altitudeKm: number;
+    /** Speed against the stars, kilometres a second. */
+    speedKmS: number;
+    /** One revolution, minutes. */
+    periodMinutes: number;
+    /** Degrees. */
+    inclinationDeg: number;
+}
+/**
+ * A satellite chosen from a group: which group and which place in it.
+ *
+ * @example
+ * ```ts
+ * import type { SatelliteRef } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const first: SatelliteRef = { group: "stations", index: 0 };
+ * console.log(first.group);
+ * ```
+ */
+export interface SatelliteRef {
+    group: string;
+    index: number;
+}
+/**
+ * A satellite the group could not use, and why: its elements did not start SGP4 (bad numbers), or it had decayed at its own epoch.
+ *
+ * @example
+ * ```ts
+ * import type { RefusedElementSet } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const show = (one: RefusedElementSet): string => `${one.name}: ${one.reason}`;
+ * console.log(typeof show);
+ * ```
+ */
+export interface RefusedElementSet {
+    name: string;
+    noradId: number;
+    reason: string;
+}
+/**
+ * A group of satellites, ready to give positions for any moment: what `createSatellites` returns, and what `<chikyu-space>` takes in `setSatellites`.
+ * Positions are in Earth radii (6371 km) from the Earth's centre, in the space view's axes (x to the vernal equinox, y north); a satellite whose elements
+ * are older than `maxAgeDays` at the moment asked about is not placed (its place stays at the centre and `visible(index)` is false).
+ *
+ * @example
+ * ```ts
+ * import type { Satellites } from "@johnmorrisdotca/chikyu-earth/satellites";
+ *
+ * const first = (group: Satellites): string => group.sets[0]?.OBJECT_NAME ?? "none";
+ * console.log(typeof first);
+ * ```
+ */
+export interface Satellites {
+    /** Satellites that started SGP4. */
+    readonly count: number;
+    /** Their elements, in the order of their places. */
+    readonly sets: readonly ElementSet[];
+    /** The ones left out, with the reason. */
+    readonly refused: readonly RefusedElementSet[];
+    /** The oldest an element set may be at the moment shown, in days. */
+    readonly maxAgeDays: number;
+    /** SGP4 calls made so far, for a page or a test to count. */
+    readonly propagations: number;
+    /** Milliseconds the last batch of SGP4 took, and the longest so far. */
+    readonly timing: {
+        lastBatchMs: number;
+        maxBatchMs: number;
+    };
+    /**
+     * Fill `out` (3 numbers a satellite) with the positions at `ms`: SGP4 is run for the whole group at two moments `step` apart and the positions between are interpolated, so a
+     * steady clock costs one batch a step and every call in between is arithmetic.
+     */
+    at(ms: number, out: Float32Array): void;
+    /** True if satellite `index` was placed by the last `at` (its elements are not too old at that moment). */
+    visible(index: number): boolean;
+    /** How many of them the last `at` placed. */
+    readonly placed: number;
+    /** The game time between the two moments SGP4 is run at (1000 to 60000 ms); the space view sets it from the clock's speed. */
+    setStep(ms: number): void;
+    /** One satellite at exactly `ms` (no interpolation): position in Earth radii and velocity in km/s into `out` (6 numbers). False if its elements are too old or SGP4 gave up. */
+    exact(index: number, ms: number, out: Float64Array): boolean;
+    /** The path of satellite `index` for one revolution from `ms`, `points` + 1 points in order along it (the last on the first), into a new array of Earth radii. */
+    orbit(index: number, ms: number, points: number): Float32Array;
+    /** Facts about one satellite at `ms`; undefined if it cannot be placed then. */
+    info(index: number, ms: number): SatelliteInfo | undefined;
+}

package/dist/satellites/types.js

@@ -0,0 +1,3 @@
+// What the satellites are made of and what the space view asks of them. Types only: nothing here imports satellite.js, so the space element can use them
+// without needing it.
+export {};