astraeus 0.5.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -0
- package/README.md +31 -8
- package/data/moons/jupiter.json +351 -115
- package/data/moons/neptune.json +54 -16
- package/data/moons/pluto.json +21 -5
- package/data/moons/saturn.json +882 -292
- package/data/moons/uranus.json +90 -28
- package/package.json +1 -1
- package/src/api/AstraeusScene.d.ts +4 -2
- package/src/api/AstraeusScene.js +13 -10
- package/src/api/AstraeusScene.node.js +13 -10
- package/src/api/bodies.d.ts +6 -1
- package/src/api/bodies.js +15 -2
- package/src/api/data.d.ts +2 -1
- package/src/api/data.js +4 -13
- package/src/api/errors.d.ts +1 -1
- package/src/api/index.d.ts +2 -1
- package/src/api/index.js +1 -1
- package/src/api/index.node.js +1 -1
- package/src/api/mount.d.ts +5 -1
- package/src/api/mount.js +2 -0
- package/src/api/mount.node.js +2 -0
- package/src/api/pathProvenance.d.ts +15 -6
- package/src/api/pathProvenance.js +23 -11
- package/src/api/scene.d.ts +18 -1
- package/src/api/scene.js +110 -15
- package/src/api/sphereOfInfluence.d.ts +20 -0
- package/src/api/sphereOfInfluence.js +48 -0
- package/src/api/viewerLink.d.ts +7 -1
- package/src/api/viewerLink.js +13 -2
- package/src/api/views.d.ts +42 -0
- package/src/api/views.js +80 -0
- package/src/app/App.js +32 -5
- package/src/app/App.node.js +32 -5
- package/src/app/AstraeusScene.d.ts +3 -0
- package/src/app/CameraController.d.ts +6 -0
- package/src/app/CameraController.js +3 -1
- package/src/app/PathView.d.ts +3 -2
- package/src/app/PathView.js +5 -5
- package/src/app/StoryMarkers.d.ts +4 -1
- package/src/app/StoryMarkers.js +3 -2
- package/src/app/TrackedBodyView.d.ts +1 -1
- package/src/app/TrackedBodyView.js +20 -11
- package/src/app/experienceDefinition.d.ts +3 -0
- package/src/app/mission.d.ts +15 -2
- package/src/app/mission.js +15 -0
- package/src/app/sceneCamera.d.ts +2 -0
- package/src/app/sceneCamera.js +14 -0
- package/src/app/sceneFrame.d.ts +2 -0
- package/src/app/sceneFrame.js +42 -6
- package/src/app/sceneHooks.js +1 -1
- package/src/app/viewHiding.d.ts +13 -0
- package/src/app/viewHiding.js +37 -0
- package/src/app/viewerPort.d.ts +6 -0
- package/src/app/views.d.ts +31 -0
- package/src/app/views.js +2 -0
- package/src/assets/bodies/listedMoons.d.ts +4 -0
- package/src/assets/bodies/listedMoons.js +7 -0
- package/src/assets/catalogue.d.ts +3 -0
- package/src/assets/catalogue.js +8 -0
- package/src/assets/moonCatalogue.d.ts +3 -1
- package/src/assets/moonCatalogue.js +1 -0
- package/src/core/bodies/jupiterMoons.d.ts +1 -1
- package/src/core/bodies/listedMoonBodies.d.ts +18 -0
- package/src/core/bodies/listedMoonBodies.js +36 -0
- package/src/core/bodies/listedMoons.d.ts +18 -0
- package/src/core/bodies/listedMoons.js +483 -0
- package/src/core/bodies/moonSystem.d.ts +3 -2
- package/src/core/bodies/moonSystem.js +1 -1
- package/src/shell/AstraeusShell.d.ts +12 -2
- package/src/shell/AstraeusShell.js +42 -4
- package/src/shell/AstraeusShell.node.js +42 -4
- package/src/shell/DisplaySwitches.d.ts +18 -1
- package/src/shell/DisplaySwitches.js +18 -5
- package/src/shell/TimelineBar.css +18 -0
- package/src/shell/TimelineBar.js +29 -4
- package/src/shell/TimelineBar.node.js +29 -4
- package/src/shell/TopBar.d.ts +4 -2
- package/src/shell/TopBar.js +3 -3
- package/src/shell/TopBar.node.js +3 -3
- package/src/shell/timelineModel.d.ts +13 -0
- package/src/shell/timelineModel.js +25 -0
- package/src/shell/viewCamera.d.ts +4 -0
- package/src/shell/viewCamera.js +13 -0
- package/src/synthetic/syntheticJourneyScene.d.ts +2 -1
- package/src/synthetic/syntheticJourneyScene.js +29 -14
- package/src/synthetic/syntheticViewsDefinition.d.ts +6 -0
- package/src/synthetic/syntheticViewsDefinition.js +44 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,32 @@
|
|
|
2
2
|
|
|
3
3
|
Versions follow [semantic versioning](https://semver.org). While the version starts with `0.`, the public API (the names exported from `astraeus`) may still change between minor versions; each change is listed here.
|
|
4
4
|
|
|
5
|
+
## 0.7.0 (2026-11-01)
|
|
6
|
+
|
|
7
|
+
First download of the packed example (`npm run measure:example`): 1,652,632 bytes raw, 472,929 bytes gzip (code and styles loaded on first open).
|
|
8
|
+
|
|
9
|
+
A probe followed as one path, close timeline markers each reachable, the picture-pack moon list documented (O-050), and views of one scene switched inside the viewer (O-051), from the fourth round of findings sent back by the outside interplanetary probe app built on 0.6.0 (G-014).
|
|
10
|
+
|
|
11
|
+
- Views of one scene (O-051 T-218, I-124, API half), no existing call changes. New `Scene.setViews([{ id, label, paths?, bodies?, events?, panels?, camera? }], { place, start? })` names views, each listing the paths, bodies, events and story panels it shows; anything no view names shows in every view. `toDefinition` resolves each view's membership once into `definition.views`. A bad list, id, place, camera or start throws the new `bad-view` code. New exported types `ViewInput`, `ViewsOptions`, `ViewCameraInput`. The viewer does not switch views yet (next steps). A scene without views is unchanged.
|
|
12
|
+
- The viewer shows the view choice (O-051 T-219, I-124, viewer half): one button per view in the top bar, or a row each in the switch panel, and in the phone drawer, the opening view pressed. Choosing a view hides the other views' paths, bodies, labels, picking targets, timeline events, story panels and story markers at once, from one hidden-id set the frame reads; nothing is rebuilt, and time, speed and playing state carry over. An object the view hides is dropped from the object menu, and a selection or follow on it is dropped, with the camera handled by the per-view camera rule of the next entry. A scene without views is unchanged. The per-view camera rule and the host's `setView` follow in the next entry.
|
|
13
|
+
- Each view steers the camera and the host picks the view (O-051 T-220, I-124, camera and host half). When a switch takes away the object the camera follows or focuses on, the new view's `camera` rule decides: `"stay"` (default) holds the camera where it is (target fixed in the scene, pose kept), stops following and closes that object's card; `"start"` takes the scene's opening framing; `{ follow: id }` / `{ focus: id }` takes that framing. A followed object still in the view is left alone. New `MountedScene.view` and `setView(id)` (unknown id or no views: `bad-view`; before `ready` or after `unmount`: `missing-data`), `AstraeusScene` prop `view`, and `ViewerChange.view` (only in a scene with views; `cause` `visitor` for the buttons, `host` for `setView`). A scene without views is unchanged.
|
|
14
|
+
- Proof on the packed package (O-051 T-221, I-124): `npm run check:node-consumer` builds three views on two made-up probe paths and a shared body from the packed package and asserts the resolved views, `start`, camera rules and every `bad-view` fault; the made-up `synthetic-views` scene is switched by a visitor and by a host `setView` at 1280x720 and 375x667, and the "stay" rule holds the camera still while the clock runs, checked by `npm run check:browser`.
|
|
15
|
+
- `addTrajectory`'s `lineFixedTo` also takes a list of `{ start, end, body }` stretches (O-050 T-213, I-125): each stretch of the line is drawn against its own body, so a flyby (Sun-fixed cruise, planet-fixed encounter, Sun-fixed cruise) is one path with one menu entry and card. Same span rules as `provenanceSpans`; a fault throws `bad-trajectory` naming the index. A single body id behaves as before.
|
|
16
|
+
- `lineFixedTo: "auto"` (O-050 T-216, I-125): the stretches are picked from the path's own samples. Each sample is fixed to the innermost scene body whose sphere of influence (`a (m / M)^(2/5)`, GMs from the catalogue) holds the probe, else the scene centre, so any flyby or orbiter is one path without working out switch times. Resolved once at mount or `prepare`; a body without a catalogue GM is skipped.
|
|
17
|
+
- Close timeline markers stay reachable (O-050 T-214, I-126): events, story panels and window peaks that sit under 22 px apart on the measured track gather into one numbered mark whose list opens each member as a full-size button; nothing gathers until the track has a measured width.
|
|
18
|
+
- Proof on the packed package (O-050 T-217, I-125 to I-127): `npm run check:node-consumer` builds a listed-stretch path, a `"auto"` path and a Moon-orbit path and asserts one menu object per path and the resolved stretches; the made-up synthetic journey draws its traveller against the Sun, Jupiter and the Sun again and adds three moon passes within nine hours of Jupiter's, checked by `npm run check:browser` (the camera stays on the traveller across both stretch boundaries; each gathered marker opens its own event at 1280x720 and 375x667).
|
|
19
|
+
- First download of the packed example (`node tools/measure-example.mjs`, after `npm run build`): 1,652,632 bytes raw, 472,929 bytes gzip at release, against 1,638,245 raw and 468,717 gzip at 0.6.0 (+14,387 raw, +4,212 gzip: the stretch drawing, sphere-of-influence resolver and marker grouping, +5,956 raw and +1,752 gzip as measured after O-050; the views, the view choice, the hide stage and the camera hold add +8,387 raw and +2,426 gzip, measured after O-051 T-221; the I-129 repair adds +44 raw and +34 gzip).
|
|
20
|
+
|
|
21
|
+
## 0.6.0 (2026-11-01)
|
|
22
|
+
|
|
23
|
+
First download of the packed example (`npm run measure:example`): 1,638,245 bytes raw, 468,717 bytes gzip (code and styles loaded on first open).
|
|
24
|
+
|
|
25
|
+
Every listed moon can be added by id (O-049, G-014), from a third finding sent back by the outside interplanetary probe app built on 0.5.1: Uranus's main moons had positions but no bodies.
|
|
26
|
+
|
|
27
|
+
- Every moon in the engine's moon lists (458 across Mars, Jupiter, Saturn, Uranus, Neptune and Pluto) now carries a sidereal orbit period from the JPL Planetary Satellite Mean Elements table (O-049 T-210, I-122), and a small generated lookup (`core/bodies/listedMoons`: id, label, mean radius, parent, period, data package, fit-set body) lets a later step add any listed moon by id without loading the full lists. Importing the lookup from the entry adds 17,716 bytes raw and 7,126 bytes gzip to the first download (`npm run measure:example`, measured with the lookup consulted from `addBody`); the full lists stay out of it.
|
|
28
|
+
- `scene.addBody(id)` takes every moon in the moon lists, not only the ready-made ones (O-049 T-211, I-122). One rule: the listed moon becomes a grey sphere at its JPL mean radius (the picture pack's picture when it holds one under the moon's id), positioned from its planet's fits in `astraeus-data-<planet>`, with `{ orbit: true }` drawing one lap of its JPL period about the planet; a moon without a period throws `no-orbit`, a missing package `missing-data`, a window outside its fit years `out-of-span`. The detailed moons (Io to Callisto, Saturn's seven, Triton, Charon, Phobos, Deimos) keep their own definitions. A moon is defined only when a scene adds it, so an unused moon costs nothing at run time. New `listedMoons(planet?)` lists every addable moon with the data package it needs (`requires`); the `unknown-body` message names the built-in ids and `listedMoons(planet)` rather than hundreds of ids. With the lookup used, the first download of the packed example is 1,638,245 bytes raw, 468,717 bytes gzip (+19,682 raw, +7,617 gzip on 0.5.1; re-measured after T-212 with `npm run build` and `node tools/measure-example.mjs`).
|
|
29
|
+
- Proof on the packed package (O-049 T-212, I-122): `npm run check:node-consumer` adds Miranda and Titania by id with `{ orbit: true }` and lists Uranus's moons; the made-up synthetic journey now passes Uranus on 24 January 1986 and adds its five main moons, checked by `npm run check:browser`. No change to the package's code or size.
|
|
30
|
+
|
|
5
31
|
## 0.5.1 (2026-10-31)
|
|
6
32
|
|
|
7
33
|
First download of the packed example (`npm run measure:example`): 1,618,563 bytes raw, 461,100 bytes gzip (code and styles loaded on first open).
|
package/README.md
CHANGED
|
@@ -67,7 +67,7 @@ scene.camera.fitOrbit(mars);
|
|
|
67
67
|
mount(document.getElementById("app"), scene);
|
|
68
68
|
```
|
|
69
69
|
|
|
70
|
-
Positions are about the scene centre (here the Sun, the first body) unless `center` says otherwise. `lineFixedTo: "sun"` keeps the line still against the Sun while the planets move; `plane` turns the ecliptic vectors into the engine's equatorial frame once; `solarSystemScale` keeps the distances true and draws the named bodies larger; the probe's name shows at any distance in a Sun-centred scene. The repository's dev site opens a fuller version at `?experience=synthetic-probe`, and a made-up 1977-to-170-AU journey past Jupiter and Saturn (moons at their dates, paced playback, provenance by stretch) at `?experience=synthetic-journey`.
|
|
70
|
+
Positions are about the scene centre (here the Sun, the first body) unless `center` says otherwise. `lineFixedTo: "sun"` keeps the line still against the Sun while the planets move (`lineFixedTo: "auto"` picks the Sun or a planet for each stretch from the path's own samples, or give a list such as `[{ start, end, body: "earth" }]`); `plane` turns the ecliptic vectors into the engine's equatorial frame once; `solarSystemScale` keeps the distances true and draws the named bodies larger; the probe's name shows at any distance in a Sun-centred scene. The repository's dev site opens a fuller version at `?experience=synthetic-probe`, and a made-up 1977-to-170-AU journey past Jupiter and Saturn (moons at their dates, paced playback, provenance by stretch) at `?experience=synthetic-journey`.
|
|
71
71
|
|
|
72
72
|
## The public API
|
|
73
73
|
|
|
@@ -76,8 +76,8 @@ The full reference, generated from the types and doc comments, is at <https://as
|
|
|
76
76
|
| Call | What it does |
|
|
77
77
|
|---|---|
|
|
78
78
|
| `new Scene()` | An empty scene. Every method below returns the scene, so calls chain. |
|
|
79
|
-
| `scene.addBody(body, { orbit?, enlarge?, showLabel?, labelReach?, description?, color?, knownLimitations? })` | Adds a catalogued body: a ready-made one (`sun`, `mercury`, `venus`, `earth`, `moon`, `mars`, `jupiter`, `saturn`, `uranus`, `neptune`, `pluto`, and the moons `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`, `phobos`, `deimos`) or its id. The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line: any catalogued moon with a period in its data (`moon`, `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`) about its planet, one lap of that period (the planet must be in the scene; `phobos
|
|
80
|
-
| `scene.addTrajectory({ id, label?, color?, center?, plane?, lineFixedTo?, labelReach?, samples, provenance?, provenanceSpans?, description?, knownLimitations?, anchors?, readouts? })` | A recorded path. Each sample is `{ time, positionKm, velocityKmS? }` measured from `center` (default: the scene's centre, its first body, so a Sun-first scene reads them from the Sun and an Earth-first one from Earth; Earth if no body is added) in equatorial J2000 (EQJ) axes; `plane: "ecliptic-j2000"` instead takes ecliptic J2000 vectors as JPL Horizons publishes them and rotates them to EQJ once on the way in (positions and velocities, from samples or a provider; a provider's `orientation` quaternion passes through unrotated, a known limit; any other `plane` throws `bad-trajectory`); `lineFixedTo` names the body the line is drawn against (default the scene centre): each sample is placed from that body at the sample's own time, then the line is carried to that body's place from the scene centre at the clock time, so `"sun"` fixes a probe's line to the Sun in any scene, Sun-centred ones included, and a body the scene does not hold throws `bad-trajectory`; `labelReach` (a positive number, in the camera's distance units) limits how far from the camera its name shows, in place of the scene's shared rule; a bad value throws `bad-trajectory`; `time` is ISO text, a `Date` or Unix milliseconds. Instead of `samples` you may give `provider` (an object with `stateAt(timeUtcMs)`) and `bounds: { start, end }`. `description` and `knownLimitations` (a list of sentences) go on its info card with `provenance`. `anchors: [{ id, time }]` draw labelled dots where the source published a point (the time must fall within the path). `readouts` are bars on the card, in order: `{ kind: "range", marker? }` (distance from the centre; `marker` names a body to mark), `{ kind: "speed" }`, `{ kind: "distance", to }` and `{ kind: "altitude", above }`; a named body must be in the scene. `provenanceSpans` (a list of `{ start, end, provenance }`, sorted, not overlapping, inside the path) gives each stretch its own provenance, shown with the path as time moves (as an activity's `provenance`); where no span covers the time, `provenance` (or the illustrative default) shows; a fault throws `bad-trajectory` naming the index. |
|
|
79
|
+
| `scene.addBody(body, { orbit?, enlarge?, showLabel?, labelReach?, description?, color?, knownLimitations? })` | Adds a catalogued body: a ready-made one (`sun`, `mercury`, `venus`, `earth`, `moon`, `mars`, `jupiter`, `saturn`, `uranus`, `neptune`, `pluto`, and the moons `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`, `phobos`, `deimos`) or its id; every moon in the moon lists is also taken by its id (`addBody("miranda")` with `astraeus-data-uranus` passed to `mount`) as a grey sphere at its mean radius, and `listedMoons(planet?)` names them with the data package each needs (`requires`). Moons with pictures: Io, Europa, Ganymede, Callisto, Mimas, Enceladus, Tethys, Dione, Rhea, Titan, Iapetus, Triton and Charon. Every other listed moon, among them Uranus's Miranda, Ariel, Umbriel, Titania and Oberon, draws flat-coloured with this package loaded. The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line: any catalogued moon with a period in its data (every listed moon but those the list gives no period for, and `moon`, `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`) about its planet, one lap of that period (the planet must be in the scene; `phobos`, `deimos` and any moon with no period throw `no-orbit`), or, with `sun` in the scene, one turn round the Sun of any body that circles it (the planets, Earth's year, a body from `addBodyFromElements`), from the opening time: one full turn of the body's own positions where they cover a whole turn, else (Uranus and Neptune, whose turn outlasts the planet series) the two-body ellipse osculating at the opening time, which the info card says; anything else throws `no-orbit`. `camera.fitOrbit` follows the same rule. `enlarge` (a number of at least 1) draws the body that many times larger than life (in a Sun-centred scene the viewer then offers its "Solar system" scale, true distances with the named bodies enlarged, as the second scale in place of Readable); `showLabel: false` starts its label off; `labelReach` (a positive number, in the camera's distance units) shows its label only within that distance of the camera, in place of the scene's shared rule. A scene whose first body is the Sun sets no label reach, so labels stay when zoomed out, and it can hold a path (`addTrajectory`, drawn with `lineFixedTo: "sun"`). `color` (a hex colour such as `"#9fd8ff"`) sets the colour on its info card and label; `knownLimitations` (a list of non-empty texts) replaces the catalogue's limits shown with its provenance; a bad value throws `bad-body`. Jupiter, Saturn, Uranus and Neptune are drawn with their rings (bands at the NASA NSSDC ring fact sheet radii) whenever you add them; Mercury, Venus, Earth, Mars and Pluto have none. |
|
|
80
|
+
| `scene.addTrajectory({ id, label?, color?, center?, plane?, lineFixedTo?, labelReach?, samples, provenance?, provenanceSpans?, description?, knownLimitations?, anchors?, readouts? })` | A recorded path. Each sample is `{ time, positionKm, velocityKmS? }` measured from `center` (default: the scene's centre, its first body, so a Sun-first scene reads them from the Sun and an Earth-first one from Earth; Earth if no body is added) in equatorial J2000 (EQJ) axes; `plane: "ecliptic-j2000"` instead takes ecliptic J2000 vectors as JPL Horizons publishes them and rotates them to EQJ once on the way in (positions and velocities, from samples or a provider; a provider's `orientation` quaternion passes through unrotated, a known limit; any other `plane` throws `bad-trajectory`); `lineFixedTo` names the body the line is drawn against (default the scene centre): each sample is placed from that body at the sample's own time, then the line is carried to that body's place from the scene centre at the clock time, so `"sun"` fixes a probe's line to the Sun in any scene, Sun-centred ones included, and a body the scene does not hold throws `bad-trajectory`; a list of `{ start, end, body }` (sorted, not overlapping, inside the path, times as in `provenanceSpans`) draws each stretch against its own body, so a flyby (Sun-fixed cruise, planet-fixed encounter, Sun-fixed cruise) is one path with one menu entry and card, time outside every stretch is drawn against the scene centre, and a fault throws `bad-trajectory` naming the index; `lineFixedTo: "auto"` builds that list from the path's own samples, once, when the planet series are in: each sample is fixed to the innermost body in the scene whose sphere of influence (`a (m / M)^(2/5)`, `a` its distance from its parent, GMs from the catalogue; the Sun holds everything) holds the probe, else the scene centre, consecutive samples on one body merging; a body with no catalogue GM (the built-in comet, every moon added only by id) is skipped, and `"auto"` is not usable as a body id; `labelReach` (a positive number, in the camera's distance units) limits how far from the camera its name shows, in place of the scene's shared rule; a bad value throws `bad-trajectory`; `time` is ISO text, a `Date` or Unix milliseconds. Instead of `samples` you may give `provider` (an object with `stateAt(timeUtcMs)`) and `bounds: { start, end }`. `description` and `knownLimitations` (a list of sentences) go on its info card with `provenance`. `anchors: [{ id, time }]` draw labelled dots where the source published a point (the time must fall within the path). `readouts` are bars on the card, in order: `{ kind: "range", marker? }` (distance from the centre; `marker` names a body to mark), `{ kind: "speed" }`, `{ kind: "distance", to }` and `{ kind: "altitude", above }`; a named body must be in the scene. `provenanceSpans` (a list of `{ start, end, provenance }`, sorted, not overlapping, inside the path) gives each stretch its own provenance, shown with the path as time moves (as an activity's `provenance`); where no span covers the time, `provenance` (or the illustrative default) shows; a fault throws `bad-trajectory` naming the index. |
|
|
81
81
|
| `scene.addBodyFromElements(record, options?)` | Your own body that circles the Sun, from published orbit elements: `record` is `{ id, label, elements: { semiMajorAxisAu, eccentricity, inclinationDeg, ascendingNodeDeg, argumentOfPerihelionDeg, meanAnomalyDeg or perihelionJdTdb }, epoch: { jd, timeScale, ttMinusUtcSeconds? }, frame: "ecliptic-j2000", source: { name, url, solution, accessed }, radius?, accuracy: { classification, statement, validFromUtc, validToUtc, limitations }, marker?: { color, sizePx } }`. Drawn as a marker on unperturbed two-body motion about the Sun; the source, accuracy and limits show on its info card, with a live "Distance from Sun" row. `options` are `addBody`'s (`{ orbit: true }` draws its whole orbit from periapsis, smooth even for a sharp comet orbit). A bad record throws `bad-element` naming the field; a repeated id throws `duplicate-id`. |
|
|
82
82
|
| `scene.addGroup({ id, orbits, label?, center?, plane?, color?, dotSizePx?, referenceTime?, seed?, clump?, refillAfterMs?, refillSliceMs?, provenance?, description?, knownLimitations? })` | A list of orbits drawn as one group of dots: `orbits` is `[{ id, semiMajorAxisKm, eccentricity, inclinationDeg, raanDeg, argumentOfPeriapsisDeg, time? }]` (bound orbits, ids distinct), measured about `center` (default the scene's centre; it must be in the scene) in `plane` (`"ecliptic-j2000"` default, or `"EQJ"`). One colour (`color`, a hex colour), dot size (`dotSizePx`), menu item, info card, provenance and known limits. Where each dot sits along its orbit is a drawing choice, marked illustrative: an even spread shuffled by `seed`, fixed at `referenceTime` (default the opening time), then two-body motion. `clump: { near, fraction, widthDeg }` draws a share of the dots near a body's place along its orbit (a model; the body must be in the scene and not the centre; it may be one added with `addBodyFromElements` before the group). `refillAfterMs` is how often the dots are placed again; `refillSliceMs` (0 or more) is how much of a frame may go on computing the next fill ahead of time. The group's card shows "illustrative" as its source type, with the elements' own type in the accuracy sentence. The id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be a panel's `object`. A mistake throws `bad-group`. |
|
|
83
83
|
| `scene.setTime(time)` | The moment the scene opens at. |
|
|
@@ -89,12 +89,13 @@ The full reference, generated from the types and doc comments, is at <https://as
|
|
|
89
89
|
| `scene.camera.setReach(distance)` | How far the viewer can zoom out, in Earth radii; labels reach as far, a path's own name (at its marker, switched by `labels`) included. A bad value throws `bad-camera`. Without `setReach` or `fitOrbit`, a Sun-centred scene with a path about the Sun widens its farthest zoom-out to fit that path whole (twice its farthest Sun distance, for the live canvas shape), so a path out to 170 AU can be seen entire. The object the scene opens on (`camera.follow` or `camera.lookAt`) is selected, and a selected object's label wins every label collision: it is never the one hidden because it overlaps another. Other labels keep their priority order. `camera.follow` and `camera.lookAt` take `up: "ecliptic"` (default `"equatorial"`) to orbit about the ecliptic's pole; any other value throws `bad-camera`. `setTimeline` takes `loop: true` so playback wraps from the end to the start. |
|
|
90
90
|
| `scene.camera.fitOrbit(body)` | Sets the farthest zoom-out so the whole orbit of a body that circles the Sun (a planet, the built-in comet, or one from `addBodyFromElements`, already added) fits the canvas from any view direction: 1.1 times its farthest Sun distance over the sine of the narrower half field of view. The fit follows the live canvas shape (a phone turning, a window resizing) and the far plane is 2.5 times the reach. The opening view is not moved, except that it is clamped to the limit like any other. Labels are not limited in a fitted scene. It and `setReach` set the same limit; the later call wins. A body that does not circle the Sun throws `bad-camera`; one not in the scene, `unknown-body`. `scene.camera.fitOrbit("c-2025-a1")` |
|
|
91
91
|
| `scene.setSwitches({ orbitLines?, labels?, milkyWay? })` | Where each display switch shows: `{ place: "top-bar" \| "panel" \| "developer", on? }`. A top-bar switch is a button in the bar, a panel switch is a row in one switch panel opened from the bar, and a developer switch is only in the Developer drawer (where every switch stays). `orbitLines` is the orbit ring, trailing arc and moon orbits; `labels` is body and anchor labels; `milkyWay` is the sky picture. `on` is the starting state (default on). Nothing placed: the bar is as before. A bad name, place or `on` throws `bad-switch`. |
|
|
92
|
+
| `scene.setViews(views, { place, start? })` | Names views of one scene: each `{ id, label, paths?, bodies?, events?, panels?, camera? }` lists the `addTrajectory` ids, `addBody`/`addGroup` ids, `addEvents` ids and `addStoryPanels` ids it shows. Anything no view names shows in every view; anything named shows only in the views that name it. `place` is `"top-bar"` or `"panel"`; `start` is the opening view (default the first). `camera` is `"stay"` (default), `"start"` or `{ follow: id }` / `{ focus: id }` (the object must be in the view). The rule applies only when switching to the view takes away the object the camera follows or focuses on: `"stay"` holds the camera where it is (its target fixed in the scene, so it does not move on with the hidden object), stops following and closes that object's card; `"start"` takes the scene's opening framing; `{ follow: id }` / `{ focus: id }` follows or focuses that object. A followed object still in the new view leaves the camera alone. Read and set the view from `mount` or `AstraeusScene` ("Views from the host page"). Presentation only: State is unchanged. An empty list, a repeated id, a bad place, camera or `start` throws `bad-view` at the call; an unknown id or a camera target the view hides throws `bad-view` when the scene is built. |
|
|
92
93
|
| `scene.stateOf(id, time)` | The state of any body in the scene at a moment, for figures a story quotes. `positionKm` is always there; `velocityKmS` (km/s) only where the body's source gives one, so check it before use: a path from `addTrajectory` whose samples or provider carry velocities, and a moon from fitted data (Io); planets, Earth, the Sun, built-in Swift-Tuttle and elements bodies give position only. Bodies: a path from `addTrajectory` (about its centre, in EQJ axes whatever `plane` it was given in), or a ready-made body, moon or elements body (about its parent). Ready-made and elements bodies answer at any date; only a moment outside an `addTrajectory` path throws `bad-time`. A planet's data lives in the planet series, so it answers only once they are loaded (at `mount`), else `missing-data`. `const au = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm) / 149597870.7;` |
|
|
93
94
|
| `scene.provenanceOf(id)` | Where a body's position comes from, as its info card shows it. Where a comparison with an independent ephemeris exists it carries `accuracyClass` and `maxErrorFraction`. For built-in Swift-Tuttle that fraction is measured (0.00857). For a body from `addBodyFromElements` it is the limit of its class (0.01 `approximate`, 0.05 `indicative`): an upper bound, not a measured figure. Other bodies carry neither field. |
|
|
94
95
|
| `scene.camera.follow(id, { azimuthDeg?, elevationDeg?, distance? })` | Opens framed on a body or trajectory already added, and already following it. `distance` is in Earth radii. |
|
|
95
96
|
| `scene.camera.lookAt(id, { azimuthDeg?, elevationDeg?, distance? })` | The same opening view without following. The last of `follow` and `lookAt` wins. The viewer's camera menu gets a Focus and a Follow entry for every body and path. |
|
|
96
|
-
| `mount(element, scene, { data?, onChange? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), time, rate, setTime(t), setRate(r), onChange(fn) }`. `data` is a list of data packages (below); the time and speed members are described under "Reading and setting the time". |
|
|
97
|
-
| `<AstraeusScene scene data? onReady? onError? time? rate? onChange? />` | The same viewer as a React component (below). |
|
|
97
|
+
| `mount(element, scene, { data?, onChange? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), time, rate, view, setTime(t), setRate(r), setView(id), onChange(fn) }`. `data` is a list of data packages (below); the time and speed members are described under "Reading and setting the time". |
|
|
98
|
+
| `<AstraeusScene scene data? onReady? onError? time? rate? view? onChange? />` | The same viewer as a React component (below). |
|
|
98
99
|
| `SceneError` | Thrown for bad input. `error.code` is one of the documented `SceneErrorCode` values (for example `unknown-body`, `bad-time`, `missing-data`, `no-orbit`) and the message says what to do. |
|
|
99
100
|
|
|
100
101
|
Checking accuracy and records without a scene: the class limits are root exports (`APPROXIMATE_LIMIT_FRACTION`, `INDICATIVE_LIMIT_FRACTION`), `classifyPositionError(maxFraction)` returns `"approximate"`, `"indicative"` or `null` (neither) for a measured largest error fraction, and `parseElementsBodyRecord(record)` validates an elements record (the same check `addBodyFromElements` makes, throwing `bad-element` naming the field):
|
|
@@ -127,15 +128,17 @@ Props: `scene`, `data` (as for `mount`), `onReady`, `onError` (a bad scene or fa
|
|
|
127
128
|
|
|
128
129
|
## Reading and setting the time
|
|
129
130
|
|
|
130
|
-
The viewer has one clock. A host page reads it, moves it and hears about changes, from the `mount` handle or from `AstraeusScene` props. Time is Unix milliseconds UTC; speed is simulated seconds per real second.
|
|
131
|
+
The viewer has one clock (and, with `setViews`, one current view: rows below). A host page reads it, moves it and hears about changes, from the `mount` handle or from `AstraeusScene` props. Time is Unix milliseconds UTC; speed is simulated seconds per real second.
|
|
131
132
|
|
|
132
133
|
| Name | What it does |
|
|
133
134
|
|------|--------------|
|
|
134
135
|
| `handle.time`, `handle.rate` | The clock now. `undefined` until `ready` has resolved and after `unmount`. |
|
|
135
136
|
| `handle.setTime(time)` | Moves the viewer to `time` (ISO text, a `Date` or milliseconds). Outside the timeline throws `bad-time`. Before `ready` or after `unmount` throws `missing-data`. |
|
|
136
137
|
| `handle.setRate(rate)` | Sets the speed to one the timeline offers (`setTimeline({ rates })`). Any other number throws `bad-timeline`: the speed menu always shows what is running, so a custom speed is refused, not added. `handle.setRate("auto")` hands the speed back to the scene's pacing (below); without pacing it throws `bad-timeline`. |
|
|
137
|
-
| `handle.onChange(fn)` or `mount(..., { onChange })` | `fn({ time, rate, playing, cause })` on every change; returns a function that stops it. `cause` is `playback` (the clock ran on; about ten calls a second while playing), `visitor` (someone used the timeline) or `host` (your own `setTime` or `
|
|
138
|
+
| `handle.onChange(fn)` or `mount(..., { onChange })` | `fn({ time, rate, playing, view?, cause })` on every change (`view` only in a scene with views); returns a function that stops it. `cause` is `playback` (the clock ran on; about ten calls a second while playing), `visitor` (someone used the timeline) or `host` (your own `setTime`, `setRate` or `setView`). Nothing arrives after `unmount`. |
|
|
138
139
|
| `<AstraeusScene time rate onChange />` | `time` and `rate` are applied once the viewer is drawn and again whenever their value changes (a new `Date` of the same moment does not seek again); they are not controlled values, so read the live time from `onChange`. A bad one goes to `onError`. |
|
|
140
|
+
| `handle.view`, `handle.setView(id)` | The id of the view showing (`setViews`), and a switch to another, as if a visitor pressed its button: the same camera rule applies. `view` is `undefined` until `ready`, after `unmount`, and in a scene without views. `setView` with an unknown id, or on a scene without views, throws `bad-view`; before `ready` or after `unmount`, `missing-data`. `onChange` hears it with `cause: "host"` (a visitor's own choice is `"visitor"`). |
|
|
141
|
+
| `<AstraeusScene view />` | Switches to that view once drawn and whenever it changes; not a controlled value (a visitor can switch too), so read the live view from `onChange`. An unknown id goes to `onError` as `bad-view`. |
|
|
139
142
|
|
|
140
143
|
```ts
|
|
141
144
|
const mounted = mount(el, scene);
|
|
@@ -149,6 +152,26 @@ const stop = mounted.onChange(({ time, cause }) => {
|
|
|
149
152
|
|
|
150
153
|
The speed menu shows exactly the `rates` the scene gives (`setTimeline({ rates })`) and no others.
|
|
151
154
|
|
|
155
|
+
### Views of one scene
|
|
156
|
+
|
|
157
|
+
Two probes, one shared Earth, three views that keep the clock, the speed and the camera's distance when you switch (the Object list, timeline events, story panels, markers and paths follow the chosen view):
|
|
158
|
+
|
|
159
|
+
```ts
|
|
160
|
+
const scene = new Scene()
|
|
161
|
+
.addBody(earth)
|
|
162
|
+
.addTrajectory({ id: "probe-a", label: "Probe A", samples: samplesA })
|
|
163
|
+
.addTrajectory({ id: "probe-b", label: "Probe B", samples: samplesB })
|
|
164
|
+
.addEvents([{ id: "a-burn", label: "A burn", time: t0 + HOUR }, { id: "b-burn", label: "B burn", time: t0 + 2 * HOUR }])
|
|
165
|
+
.setViews([
|
|
166
|
+
{ id: "a", label: "Probe A", paths: ["probe-a"], events: ["a-burn"], camera: "stay" }, // the camera holds where it is
|
|
167
|
+
{ id: "b", label: "Probe B", paths: ["probe-b"], events: ["b-burn"], camera: { follow: "probe-b" } },
|
|
168
|
+
{ id: "both", label: "Both", paths: ["probe-a", "probe-b"], events: ["a-burn", "b-burn"] },
|
|
169
|
+
], { place: "top-bar" });
|
|
170
|
+
const mounted = mount(el, scene);
|
|
171
|
+
await mounted.ready;
|
|
172
|
+
mounted.setView("b"); // as if the visitor pressed Probe B; onChange hears cause "host"
|
|
173
|
+
```
|
|
174
|
+
|
|
152
175
|
### Paced playback
|
|
153
176
|
|
|
154
177
|
A long journey wants fast cruising and slow encounters. `setTimeline` takes `pacing`, a list of pieces; outside every piece playback runs at the timeline's `rate`.
|
|
@@ -197,7 +220,7 @@ window.addEventListener("vite:preloadError", () => window.location.reload());
|
|
|
197
220
|
|
|
198
221
|
For tests, the package has a `node` export condition: Node and Vitest's Node environment import a copy of the package without the stylesheet import, so `new Scene()...toDefinition()` works with no `test.server.deps.inline` setting. The jsdom and happy-dom Vitest environments also take the `node` condition, so the viewer's CSS is not loaded there; this does not matter for tests that check scene definitions or behaviour. Bundlers do not use the `node` condition and load the normal build.
|
|
199
222
|
|
|
200
|
-
First download: the packed `examples/hello-scene` loads 1,
|
|
223
|
+
First download: the packed `examples/hello-scene` loads 1,652,632 bytes (472,929 gzip) of code and styles, measured at this commit on first open (`npm run measure:example`; pictures and data files are not counted).
|
|
201
224
|
|
|
202
225
|
## What `astraeus-data` adds
|
|
203
226
|
|