astraeus 0.8.0 → 0.8.1
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 +13 -0
- package/README.md +21 -5
- package/data/ephemerides/planets/planets.json +1 -1
- package/package.json +1 -1
- package/src/api/errors.d.ts +2 -0
- package/src/api/viewerHandle.d.ts +8 -2
- package/src/api/viewerHandle.js +1 -0
- package/src/api/viewerLink.d.ts +1 -0
- package/src/api/viewerLink.js +8 -2
- package/src/api/viewerSelection.d.ts +6 -1
- package/src/api/viewerSelection.js +15 -0
- package/src/api/views.d.ts +3 -1
- package/src/api/views.js +5 -1
- package/src/app/App.js +24 -4
- package/src/app/App.node.js +24 -4
- package/src/app/AstraeusScene.d.ts +2 -0
- package/src/app/sceneCamera.d.ts +2 -0
- package/src/app/sceneCamera.js +2 -1
- package/src/app/viewerPort.d.ts +2 -0
- package/src/app/views.d.ts +2 -0
- package/src/core/astronomyAdapter.d.ts +1 -1
- package/src/core/astronomyAdapter.js +3 -3
- package/src/core/bodies/index.js +13 -12
- package/src/core/bodies/jupiter.js +1 -1
- package/src/core/bodies/mars.js +1 -1
- package/src/core/bodies/mercury.js +1 -1
- package/src/core/bodies/outerPlanets.d.ts +2 -3
- package/src/core/bodies/outerPlanets.js +4 -13
- package/src/core/bodies/planetMoons.d.ts +0 -2
- package/src/core/bodies/planetMoons.js +1 -18
- package/src/core/bodies/planetRecords.d.ts +8 -2
- package/src/core/bodies/planetRecords.js +13 -5
- package/src/core/bodies/planetTrajectory.d.ts +21 -4
- package/src/core/bodies/planetTrajectory.js +28 -4
- package/src/core/bodies/venus.js +1 -1
- package/src/core/planetModels.d.ts +1 -1
- package/src/core/planetModels.js +1 -1
- package/src/core/planetSeries.d.ts +2 -2
- package/src/core/planetSeries.js +1 -1
- package/src/shell/AstraeusShell.d.ts +13 -1
- package/src/shell/AstraeusShell.js +33 -3
- package/src/shell/AstraeusShell.node.js +33 -3
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,19 @@
|
|
|
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.8.1 (2026-11-10)
|
|
6
|
+
|
|
7
|
+
First download of the packed example (`npm run measure:example`): 1,720,047 bytes raw, 493,478 bytes gzip (code and styles loaded on first open), against 1,716,429 raw and 492,249 gzip at 0.8.0 (+3,618 raw, +1,229 gzip, the new host calls). The planet data is a lazy chunk and not part of that total.
|
|
8
|
+
|
|
9
|
+
Additions, and the host-call fixes below; no existing call shape or error code changed.
|
|
10
|
+
|
|
11
|
+
- A host `setCamera` is no longer lost. One written order rule (README, "Host calls"): after `ready` every call takes effect or throws, in call order, last call wins. A call made before the first frame is applied after the opening view (it was discarded by it), and a call made inside an `onChange` report of a view switch is applied after the view's own camera rule (it was overwritten by it). No call shape or error code changed.
|
|
12
|
+
- `setViews`: a view's `camera` framing `{ follow: id }` / `{ focus: id }` accepts `always: true`, which applies it on every switch to that view, also when the camera follows an object both views show (I-153). Without it a view behaves exactly as before. `ViewCameraInput` gains the optional field.
|
|
13
|
+
- `setSelected(id | undefined)` on the viewer handle (`mount` and `AstraeusScene`): a host selects an object the showing view shows, or clears the selection. `onSelect` hears it with `cause: "host"`; an unknown or hidden id throws the new error code `bad-selection`. It follows the host-call order rule (it holds straight after `ready` and inside an `onChange` report of a view switch), and a listener's host call made inside an `onChange` report no longer leaves the rest of that report on the older reading. `ViewerHandle` and `MountedScene` gain one call; the `selected` read is no longer read-only.
|
|
14
|
+
- A host `setTime` counts as a seek for story panels, as a visitor's slider seek does: it re-bases the panel crossing check, so a jump across a panel's time while playing no longer opens the panel (I-151).
|
|
15
|
+
- README: an event has one zone, as wide as its widest pacing rule ("Event zones").
|
|
16
|
+
- Planet positions now come from JPL Horizons (DE441 with each planet's satellite ephemeris), not VSOP87A (O-063, owner-approved core data change, DATA-01). Every planet's series is its system barycentre as Horizons reports the planet, and a planet with a moon system (Mars, Jupiter, Saturn, Uranus, Neptune, Pluto) adds its own offset from the barycentre from its moon package when that is loaded, so the planet sits on Horizons' planet centre and a probe's Horizons samples about a planet land on it without re-placing. Measured gain at the Voyager closest approaches: Jupiter 755 and 629 km to 0.24 and 0.22 km, Saturn 1,629 and 1,790 km to 0.31 and 0.11 km, Uranus 6,314 km to 0.20 km, Neptune 13,338 km to 0.27 km; across 1972 to 2044 within 0.6 km with the moon package (Neptune's worst was 43,747 km over 1950 to 2044). Without the package a planet sits at its barycentre (up to 304 km from its centre for Saturn). Planets move by these amounts from 0.8.0: a scene that pinned planet positions sees them change. `planets.json` shrinks from 432,063 to 348,839 bytes (a lazy chunk, not in the first download). No call shape or error code changed.
|
|
17
|
+
|
|
5
18
|
## 0.8.0 (2026-11-07)
|
|
6
19
|
|
|
7
20
|
First download of the packed example (`npm run measure:example`): 1,716,429 bytes raw, 492,249 bytes gzip (code and styles loaded on first open), against 1,652,632 raw and 472,929 gzip at 0.7.0.
|
package/README.md
CHANGED
|
@@ -102,7 +102,7 @@ The full reference, generated from the types and doc comments, is at <https://as
|
|
|
102
102
|
| `scene.camera.fitOrbit(body)` | Sets the farthest zoom-out so the whole orbit of a body that circles the Sun (a planet, or a comet or asteroid 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")` |
|
|
103
103
|
| `scene.setLook({ starBrightness?, milkyWay?, milkyWayBrightness?, skyVisible?, sunGlow?: { sizePx?, brightness?, scale? }, markerSwapRadiusPx?, featureMinBodyPx?, loadFadeSeconds?, desktopPictures? })` | The looks, presentation settings that change how the scene is drawn and never where anything is; each is optional and keeps its default when not named (the call replaces the whole look). Ranges and defaults: star and Milky Way brightness 0 to 2 (1); `milkyWay` and `skyVisible` true or false (Milky Way off, sky shown); `sunGlow.sizePx` 0 to 400 (the Sun record's 72), `sunGlow.brightness` 0 to 2 (1), `sunGlow.scale` 1 to 6 (2.5); `markerSwapRadiusPx` 0 to 100 (3), the screen radius under which a sphere is drawn as a dot; `featureMinBodyPx` 0 to 2000 (60); `loadFadeSeconds` 0 to 3 (0.6); `desktopPictures` true or false (false) lets a body with a larger desktop picture use it on a wide screen, read when the viewer is built, so a later `setLook` neither swaps pictures nor changes what `look` reads. A page address parameter (table below) overrides the look it names when `address` is on. An unknown look or a value out of range throws `bad-look`. |
|
|
104
104
|
| `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), so it shows only when the viewer was built with `developerTools` on; with it off there is no drawer and the switch is simply not shown. `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`. |
|
|
105
|
-
| `scene.setViews(views, { place, start? })` | Names views of one scene: each `{ id, label, objects?, events?, panels?, camera? }` lists the `addBody`, `addGroup` and `addTrajectory` ids (`objects`), `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. |
|
|
105
|
+
| `scene.setViews(views, { place, start? })` | Names views of one scene: each `{ id, label, objects?, events?, panels?, camera? }` lists the `addBody`, `addGroup` and `addTrajectory` ids (`objects`), `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, unless the framing opts in: `{ follow: id, always: true }` / `{ focus: id, always: true }` applies it on every switch to the view, also when the camera follows an object both views show (a host's own `setCamera` made after the switch still wins over it). 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 (`always` must be `true` when given); an unknown id or a camera target the view hides throws `bad-view` when the scene is built. |
|
|
106
106
|
| `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 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 or fitted moon's data loads with `await scene.load({ data })` (or at `mount`, once `ready` resolves); before that it throws `missing-data`. `const au = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm) / 149597870.7;` |
|
|
107
107
|
| `scene.load({ data? })` | Loads what `stateOf` and `provenanceOf` need, without a viewer: the planet series and, for each moon the scene holds, the chunks its data package provides for the scene's window. Pass the same `data` as `mount`. Rejects with `missing-data` (a body needs a package not passed) or `out-of-span`; harmless to call twice, allowed on a mounted scene, and a later `mount` re-uses what it loaded. Works in plain Node. `await scene.load({ data: [jupiterData] });` |
|
|
108
108
|
| `scene.check({ data? })` | Runs the checks `mount` runs before it draws and throws the same `SceneError` for a build fault, without loading or freezing anything. `scene.check({ data: [jupiterData] });` |
|
|
@@ -122,7 +122,7 @@ The full reference, generated from the types and doc comments, is at <https://as
|
|
|
122
122
|
| `scene.timeline` | `{ windowStartUtcMs, windowEndUtcMs, openUtcMs, rates, rate, loop }`: the span and opening moment in UTC milliseconds, the speeds offered, the opening speed and whether playback wraps. With nothing setting a span or moment and no path or activity, the span is a month about the moment of the read. Planet orbit lines and the far plane answer from `scene.bodies[].orbit` and `scene.camera.farEarthRadii` (when none was given, the far plane is 2.5 times `scene.camera.reachEarthRadii`). |
|
|
123
123
|
| `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. |
|
|
124
124
|
| `scene.camera.focus(id, { azimuthDeg?, elevationDeg?, distance? })` | The same opening view without following. The last of `follow` and `focus` wins. The viewer's camera menu gets a Focus and a Follow entry for every body and path. |
|
|
125
|
-
| `mount(element, scene, { data?, onChange?, address?, developerTools? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), timeUtcMs, rate, playing, view, camera, eventZones, selected, look, scale, switches, pick, setTime(t), setRate(r), setPlaying(p), setView(id), setCamera(target), setLook(look), setScale(id), setSwitch(id), setPick(value), onChange(fn), onEventZone(fn), onSelect(fn), onCameraChange(fn), onFirstDraw(fn), onPick(fn) }`. `data` is a list of data packages (below); `address` is off by default (see "Page address"); `developerTools` is off by default (the cog and the Developer drawer are not drawn, and the drawer's code is never fetched; the demo site turns it on); the time and speed members are described under "Reading and setting the time". |
|
|
125
|
+
| `mount(element, scene, { data?, onChange?, address?, developerTools? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), timeUtcMs, rate, playing, view, camera, eventZones, selected, look, scale, switches, pick, setTime(t), setRate(r), setPlaying(p), setView(id), setCamera(target), setSelected(id), setLook(look), setScale(id), setSwitch(id), setPick(value), onChange(fn), onEventZone(fn), onSelect(fn), onCameraChange(fn), onFirstDraw(fn), onPick(fn) }`. `data` is a list of data packages (below); `address` is off by default (see "Page address"); `developerTools` is off by default (the cog and the Developer drawer are not drawn, and the drawer's code is never fetched; the demo site turns it on); the time and speed members are described under "Reading and setting the time". |
|
|
126
126
|
| `<AstraeusScene scene data? ref? onReady? onError? time? rate? view? camera? onChange? onEventZone? onPick? onFirstDraw? address? developerTools? className? style? />` | The same viewer as a React component (below). |
|
|
127
127
|
| `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. |
|
|
128
128
|
|
|
@@ -156,13 +156,13 @@ Props: `scene`, `data` (as for `mount`), `ref` (a React 19 ref prop that receive
|
|
|
156
156
|
|
|
157
157
|
## Reading and setting the time
|
|
158
158
|
|
|
159
|
-
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.
|
|
159
|
+
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. **Order rule:** after `ready`, every call on the handle takes effect or throws, in the order the host made it, and the last host call wins. A `setCamera` made before the scene's first frame is kept and applied after the scene's opening view, not discarded by it. A `setCamera` made inside an `onChange` report of a view switch is applied after the view's own camera rule for that switch. A view's camera rule is a default for a switch, so a later host call replaces it.
|
|
160
160
|
|
|
161
161
|
| Name | What it does |
|
|
162
162
|
|------|--------------|
|
|
163
163
|
| `handle.ready` | Resolves once the scene's data has loaded, it is drawn and the host link is attached, so `timeUtcMs`, `rate`, `view` and every `set` call work on the line after `await handle.ready`; no extra frame or wait. Rejects if loading failed, and with `not-mounted` if `unmount` came first; it never stays pending. |
|
|
164
164
|
| `handle.timeUtcMs`, `handle.rate` | The clock now. `undefined` until `ready` has resolved and after `unmount`. |
|
|
165
|
-
| `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 `not-mounted`. |
|
|
165
|
+
| `handle.setTime(time)` | Moves the viewer to `time` (ISO text, a `Date` or milliseconds). Outside the timeline throws `bad-time`. It counts as a seek for story panels, as the visitor's slider does: moving across a panel's time opens nothing by itself. Before `ready` or after `unmount` throws `not-mounted`. |
|
|
166
166
|
| `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`. |
|
|
167
167
|
| `handle.playing` and `handle.setPlaying(playing)` | `playing` reads whether the viewer is playing (undefined before `ready` and after `unmount`). `setPlaying(true)` or `setPlaying(false)` plays or pauses through the same handler as the visitor's play button; `onChange` hears it with `cause: "host"` and the new `playing`. A non-boolean, or a scene with `setTimeline({ none: true })` (no play control for a visitor either), throws `bad-timeline`. |
|
|
168
168
|
| `handle.look`, `handle.setLook(look)` | `look` reads the looks in force with every one filled in (`starBrightness`, `milkyWay`, `milkyWayBrightness`, `skyVisible`, `sunGlow?` as `{ sizePx, brightness, scale }`, `markerSwapRadiusPx`, `featureMinBodyPx`, `loadFadeSeconds`, `desktopPictures`), whoever set them: the scene's `setLook`, the page address, your `setLook` or a visitor in the Developer drawer. `setLook(look)` replaces the whole look (a look not named takes its default) and is checked as `Scene.setLook` checks it (`bad-look`); a live `setLook` wins over the same look in the page address, which only starts the viewer. Presentation only. `look` is `undefined` until `ready` and after `unmount`; `setLook` before `ready` or after `unmount` throws `not-mounted`. |
|
|
@@ -173,6 +173,7 @@ The viewer has one clock (and, with `setViews`, one current view: rows below). A
|
|
|
173
173
|
| `handle.onChange(fn)` or `mount(..., { onChange })` | `fn({ timeUtcMs, rate, playing, view?, scale, look, switches?, cause })` on every change (`view` only in a scene with views; `switches` only in a scene that placed some); 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, the view choice, the scale, a display switch or the Developer drawer) or `host` (your own `setTime`, `setRate`, `setPlaying`, `setView`, `setScale`, `setSwitch` or `setLook`). Nothing arrives after `unmount`. |
|
|
174
174
|
| `<AstraeusScene ref onReady />` | The `ref` and the `onReady(handle)` argument are the handle above (`timeUtcMs`, `rate`, `playing`, `view`, `camera`, `eventZones`, `selected`, the `set` calls, `onChange`, `onEventZone`, `onSelect`, `onCameraChange`): `onReady={(handle) => handle.setTime(...)}` or `ref.current` after it. |
|
|
175
175
|
| `<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`. |
|
|
176
|
+
| `handle.selected`, `handle.setSelected(id)` | The id of the selected object, and a choice of another (or `undefined` to clear): see "Selection" below. An id the showing view does not show throws `bad-selection`; before `ready` or after `unmount`, `not-mounted`. `onSelect` hears it with `cause: "host"`. |
|
|
176
177
|
| `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`, `not-mounted`. `onChange` hears it with `cause: "host"` (a visitor's own choice is `"visitor"`). |
|
|
177
178
|
| `<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`. |
|
|
178
179
|
| `handle.setCamera(target)` | Points the camera, through the same request path a view's camera rule uses; it eases there. `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, and a pose from `handle.camera` puts the camera back (below). The object must be one the showing view shows: an unknown or hidden id, or a malformed argument, throws `bad-camera`; before `ready` or after `unmount`, `not-mounted`. |
|
|
@@ -224,12 +225,14 @@ Speeds ease between pieces in log space over `rampSeconds` simulated seconds (de
|
|
|
224
225
|
|
|
225
226
|
In a scene with views (`setViews`), an event rule slows playback only near the events the showing view has (an event no view names is in every view); spans apply in every view. A switch that changes the paced speed eases to the new one in log space over about a second, while seeking lands on the paced speed at once. A scene without views paces exactly as before.
|
|
226
227
|
|
|
227
|
-
Selection: `mounted.selected` reads the id of the object whose information the viewer has open (undefined before `ready`, after `unmount`, and when nothing is selected), and `mounted.onSelect(listener)` calls `listener({ object?, timeUtcMs, cause })` when it changes: `object` is the new id (absent when the selection was dropped and nothing took its place), `cause` is `visitor` for the object menu, a click or a time, speed or view the visitor chose, `host` for a drop caused by the host's own `setTime`, `setRate`, `setPlaying` or `setView`, and `playback` for a drop caused by the clock running (for example past the end of a path's samples); a drop names the same cause `onChange` gave the move that caused it. The selection the viewer opens with is read, not reported.
|
|
228
|
+
Selection: `mounted.selected` reads the id of the object whose information the viewer has open (undefined before `ready`, after `unmount`, and when nothing is selected), and `mounted.onSelect(listener)` calls `listener({ object?, timeUtcMs, cause })` when it changes: `object` is the new id (absent when the selection was dropped and nothing took its place), `cause` is `visitor` for the object menu, a click or a time, speed or view the visitor chose, `host` for `setSelected` and for a drop caused by the host's own `setTime`, `setRate`, `setPlaying` or `setView`, and `playback` for a drop caused by the clock running (for example past the end of a path's samples); a drop names the same cause `onChange` gave the move that caused it. The selection the viewer opens with is read, not reported. `mounted.setSelected(id)` selects an object the showing view shows, or clears the selection with `undefined`: `selected` reads it at once and `onSelect` hears it with `cause: "host"` (nothing is reported when the selection is already that). An unknown or hidden id, an empty or non-string id throws `bad-selection`; before `ready` or after `unmount`, `not-mounted`. It follows the order rule: made straight after `await ready`, or inside an `onChange` report of a view switch, it holds over the view's own framing. It selects as the object menu does, minus the camera: the object's card opens and the camera stays (`setCamera` points it); a clear closes the card. A selection cleared by the host stays cleared until someone selects again. `onSelect` returns the function that stops it; nothing arrives after `unmount`.
|
|
228
229
|
|
|
229
230
|
The mount handle's members live on its prototype (the same builder serves the React `ref`), so spreading it (`{ ...handle }`) or `Object.keys(handle)` shows only `ready` and `unmount`. Read and call members by name (`handle.timeUtcMs`, `handle.setTime(...)`, or destructure them); they are all there.
|
|
230
231
|
|
|
231
232
|
Camera: `mounted.onCameraChange(listener)` calls `listener(pose)` with the camera as a plain value (`{ focus, azimuthDeg, elevationDeg, distance }`, what `mounted.camera` reads) when it changes: a visitor's drag, zoom or pick, a view's camera rule, or your own `setCamera` (it reports as the camera eases, then stops when the pose settles). At most about ten reports a second; an unchanged pose reports nothing, and a camera following a moving object at a fixed pose reports nothing. The opening pose is read from `camera`, not reported. It returns the function that stops it; nothing arrives after `unmount`; a listener that throws is reported to the page and does not stop the others.
|
|
232
233
|
|
|
234
|
+
An event has one zone, as wide as its widest pacing rule: when several rules match the same event the event is in its zone while playback is inside any of them (the rules' stretches are centred on the event, so the widest one), and `onEventZone` reports it once, not once per rule. An event's own `withinSeconds` replaces each rule's width for that event.
|
|
235
|
+
|
|
233
236
|
Event zones: `mounted.onEventZone(listener)` (React: the `onEventZone` prop) tells the page when playback enters or leaves the zone of an event (its `withinSeconds`, or a pacing `near` rule), for an event the showing view has, in a scene with pacing or without. `listener({ event, type?, object?, entered, timeUtcMs, cause, via })` gets the event's id, its `type` and `object`, `entered` true on entering and false on leaving, the viewer's time, and `cause`: `playback` (the clock ran), `visitor` (timeline or view choice) or `host` (`setTime`, `setView`); and `via`: `"time"` (playback crossed the zone, or a seek moved the clock across it) or `"view"` (a view switch showed or hid it). After a `"view"` leave the view's own camera rule owns the camera, so a page that restores a camera does so only for `via === "time"`. The zones are the ones pacing uses (an event's own `withinSeconds` wins over a rule's `withinSeconds`), never a span, and only the showing view's events. A view switch that hides an active zone reports leave and one that shows a zone the time is inside reports enter; overlapping zones report separately. A zone the time is already inside when the viewer opens reports `entered` once, with the first report after `ready` (within a tenth of a second, cause `playback`), so a listener added right after `await ready` hears it; a rebuilt viewer starts over the same way. `onEventZone` returns the function that stops it; nothing arrives after `unmount`. `mounted.eventZones` reads the ids of the zones active now (`[]` in a scene with no event zones; `undefined` before `ready` and after `unmount`). The engine moves nothing in response; the page composes its own behaviour:
|
|
234
237
|
|
|
235
238
|
```ts
|
|
@@ -350,6 +353,7 @@ Every call that refuses its input throws a `SceneError`, a `RangeError` with a s
|
|
|
350
353
|
| `bad-activity` | An activity curve is malformed. |
|
|
351
354
|
| `bad-camera` | A camera call or pose is malformed, or names an object the view cannot show. |
|
|
352
355
|
| `bad-view` | A scene view is malformed, repeated, or not one of the scene's views. |
|
|
356
|
+
| `bad-selection` | `setSelected` was given something other than an id of an object the showing view shows, or `undefined`. |
|
|
353
357
|
| `bad-look` | A look (`setLook`) is unknown or out of its range. |
|
|
354
358
|
| `renamed` | An input field was given under a name it no longer has; the message names the old field and its replacement. |
|
|
355
359
|
<!-- error-table:end -->
|
|
@@ -379,6 +383,18 @@ The engine alone draws the Sun, Earth, Moon and the eight planets with their pic
|
|
|
379
383
|
|
|
380
384
|
Years each package covers: the main moons and the planet reach back to 1950 in `astraeus-data-jupiter` (Io, Europa, Ganymede, Callisto), `-saturn` (Mimas, Enceladus, Tethys, Dione, Rhea, Titan, Hyperion, Iapetus, Phoebe), `-uranus` (Miranda, Ariel, Umbriel, Titania, Oberon) and `-neptune` (Triton, Nereid), 1950 to 2030; every other moon, and all of `-mars` and `-pluto`, covers 2010 to 2030. A scene whose timeline reaches outside a body's years fails once at mount with `SceneError` code `out-of-span`.
|
|
381
385
|
|
|
386
|
+
Planet positions are JPL Horizons' (DE441, with each planet's satellite ephemeris), fitted within 1 km: each planet's series is its system barycentre, and a planet's moon package, when loaded for the date, adds the planet's own offset from it, so the planet sits on Horizons' planet centre. Measured against Horizons on 2 January of each year 1972 to 2044 and at the Voyager closest approaches (a probe's Horizons samples about a planet then land on the engine's planet):
|
|
387
|
+
|
|
388
|
+
| Planet | With its moon package (years it covers) | Without it (the system barycentre) |
|
|
389
|
+
|---|---|---|
|
|
390
|
+
| Mercury, Venus | within 0.6 km (no moons) | same |
|
|
391
|
+
| Mars | within 0.6 km (2010 to 2029) | under a metre further |
|
|
392
|
+
| Jupiter, Saturn | within 0.5 km (1950 to 2029); 0.11 to 0.31 km at the Voyager flybys | up to 216 km (Jupiter), 304 km (Saturn) |
|
|
393
|
+
| Uranus, Neptune | within 0.6 km (1950 to 2029); 0.20 and 0.27 km at the Voyager 2 flybys | up to 45 km (Uranus), 74 km (Neptune) |
|
|
394
|
+
| Pluto | within 1.5 km (2010 to 2029) | up to about 2,100 km |
|
|
395
|
+
|
|
396
|
+
Before 1972 a date can sit up to 0.7 s from Horizons' reading of it (Horizons uses UT1 to 1962 and UTC's rubber seconds to 1972), up to 35 km along Mercury's path. Earth stays on the EPV00 model: within 7.3 km of Horizons 1972 to 2044.
|
|
397
|
+
|
|
382
398
|
```js
|
|
383
399
|
import { Scene, jupiter, io, mount } from "astraeus";
|
|
384
400
|
import { dataSource as jupiterMoons } from "astraeus-data-jupiter";
|