astraeus 0.9.0 → 0.9.2

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.
Files changed (84) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +102 -35
  3. package/package.json +1 -1
  4. package/src/api/assembleScene.js +5 -5
  5. package/src/api/errors.d.ts +1 -1
  6. package/src/api/index.d.ts +2 -2
  7. package/src/api/look.d.ts +14 -0
  8. package/src/api/lookInput.d.ts +1 -1
  9. package/src/api/lookInput.js +6 -2
  10. package/src/api/planBodies.d.ts +2 -1
  11. package/src/api/planBodies.js +6 -1
  12. package/src/api/planCamera.d.ts +19 -2
  13. package/src/api/planCamera.js +45 -6
  14. package/src/api/planPaths.d.ts +2 -0
  15. package/src/api/planPaths.js +13 -8
  16. package/src/api/planStory.d.ts +3 -1
  17. package/src/api/planStory.js +5 -0
  18. package/src/api/planTimeline.d.ts +1 -1
  19. package/src/api/planTimeline.js +10 -1
  20. package/src/api/planViews.d.ts +3 -1
  21. package/src/api/planViews.js +4 -0
  22. package/src/api/providerPathTimes.d.ts +10 -0
  23. package/src/api/providerPathTimes.js +109 -0
  24. package/src/api/scene.d.ts +17 -5
  25. package/src/api/scene.js +16 -2
  26. package/src/api/sceneReads.d.ts +31 -1
  27. package/src/api/shownDuring.d.ts +12 -0
  28. package/src/api/shownDuring.js +30 -0
  29. package/src/api/story.d.ts +10 -3
  30. package/src/api/story.js +11 -4
  31. package/src/api/switches.d.ts +1 -0
  32. package/src/api/switches.js +3 -1
  33. package/src/api/time.d.ts +1 -1
  34. package/src/api/time.js +4 -1
  35. package/src/app/App.js +58 -21
  36. package/src/app/App.node.js +58 -21
  37. package/src/app/AstraeusScene.d.ts +8 -1
  38. package/src/app/CameraController.d.ts +4 -1
  39. package/src/app/CameraController.js +15 -3
  40. package/src/app/SkyFiguresView.d.ts +2 -2
  41. package/src/app/SkyFiguresView.js +25 -14
  42. package/src/app/displaySwitches.d.ts +2 -0
  43. package/src/app/displaySwitches.js +1 -1
  44. package/src/app/liveLook.d.ts +4 -1
  45. package/src/app/liveLook.js +29 -1
  46. package/src/app/look.d.ts +5 -0
  47. package/src/app/look.js +8 -2
  48. package/src/app/sceneCamera.js +14 -2
  49. package/src/app/sceneContentsHooks.js +1 -1
  50. package/src/app/sceneFrame.d.ts +14 -5
  51. package/src/app/sceneFrame.js +31 -21
  52. package/src/app/scenePointer.d.ts +5 -1
  53. package/src/app/scenePointer.js +8 -3
  54. package/src/app/timeLook.d.ts +7 -0
  55. package/src/app/timeLook.js +8 -0
  56. package/src/app/viewHiding.d.ts +8 -1
  57. package/src/app/viewHiding.js +23 -0
  58. package/src/core/clock.js +2 -1
  59. package/src/core/lookValues.d.ts +13 -0
  60. package/src/core/lookValues.js +39 -0
  61. package/src/core/pacing.d.ts +38 -6
  62. package/src/core/pacing.js +141 -21
  63. package/src/core/state.d.ts +2 -0
  64. package/src/core/state.js +5 -1
  65. package/src/core/storyPanels.d.ts +8 -4
  66. package/src/core/storyPanels.js +17 -5
  67. package/src/shell/AstraeusShell.d.ts +7 -1
  68. package/src/shell/AstraeusShell.js +39 -14
  69. package/src/shell/AstraeusShell.node.js +39 -14
  70. package/src/shell/ObjectControls.js +2 -2
  71. package/src/shell/TimelineBar.d.ts +6 -2
  72. package/src/shell/TimelineBar.js +17 -12
  73. package/src/shell/TimelineBar.node.js +17 -12
  74. package/src/shell/experience.d.ts +9 -0
  75. package/src/shell/infoModel.d.ts +2 -1
  76. package/src/shell/infoModel.js +10 -10
  77. package/src/shell/objectModel.d.ts +3 -2
  78. package/src/shell/objectModel.js +6 -4
  79. package/src/shell/storyPanels.d.ts +19 -1
  80. package/src/shell/storyPanels.js +34 -2
  81. package/src/shell/timelineModel.d.ts +11 -0
  82. package/src/shell/timelineModel.js +28 -0
  83. package/src/shell/useStoryPanels.d.ts +4 -0
  84. package/src/shell/useStoryPanels.js +27 -6
package/CHANGELOG.md CHANGED
@@ -2,6 +2,46 @@
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.9.2 (2026-11-17)
6
+
7
+ First download of the packed example (`npm run measure:example`): 1,773,029 bytes raw, 510,085 bytes gzip (code and styles loaded on first open), against 1,764,446 raw and 507,330 gzip at 0.9.1 (+8,583 raw, +2,755 gzip). Additions and fixes only (G-020); every `astraeus-data*` package still peers on `>=0.9.0 <0.10.0`.
8
+
9
+ - Added: `astraeus-data` gains the subpath `astraeus-data/milky-way`, exporting `milkyWaySource`: a data source holding the Milky Way picture alone, so a sky-only app (stars and constellations, no moons) builds with that one picture and not the moon and Venus maps. The main `astraeus-data` export, every picture and every licence record are unchanged.
10
+ - Added: `astraeus-data-constellations` gains `constellationFinder()`, which resolves to a synchronous function from a J2000 direction `{ raDeg, decDeg }` to the IAU abbreviation of the constellation that holds it (both Serpens loops answer `"Ser"`; right ascension modulo 360; a bad declination or non-finite number throws a `RangeError` naming the field; a direction on a shared edge answers the alphabetically first abbreviation), and `constellations(..., { outlineLabel })`, a function that names each boundary outline's label (for example `"Aries"` to `"Aries boundary"`) so an app can tell outlines from figures; a non-function or a result that is not a non-empty string throws a `RangeError`. Labels are unchanged without it. No engine change; the peer range stays `>=0.9.0 <0.10.0`.
11
+ - Added: a scene reads back what it was set to, with no browser: `scene.look` (every look filled in, the same values `handle.look` reads on a fresh mount), `scene.switches` (`{ place, on, label? }` per placed switch), `scene.panelPlayback` (`{ pauseSeconds, autoOpen, closeAfterSeconds? }`) and `scene.timeline.pacing`. New types `ScenePanelPlaybackRead`, `SceneSwitchRead`, `ScenePacingRead`.
12
+ - Added: a host chooses which bodies offer Focus and whether Overview shows. `scene.camera.setFocusChoices(ids)` mirrors `setFollowChoices` (an unknown id throws `unknown-body`; `[]` offers Focus on none; an opening `camera.focus` of an unlisted object throws `bad-camera` when the scene is built), and `scene.camera.setOverview(false)` leaves out the Overview button (a non-boolean throws `bad-camera`). With every kind empty, a look-out-only scene shows no orbit camera buttons. Defaults are unchanged.
13
+ - Added: `setSwitches` entries take `label`, the switch's own name in the top-bar button and the panel row (a non-empty text, else `bad-switch`). The Developer drawer's controls keep their own names.
14
+ - Added: story panels can close themselves. `setStoryPanelPlayback({ closeAfterSeconds })` (or `closeAfterSeconds` on one moment panel, which wins) closes an open moment panel on the first forward-playing tick after it opened whose clock is at or past its time plus that many simulated seconds (so a span shorter than one frame still closes, on the next tick, never the opening one); `onPanel` hears it with `cause: "playback"`. A panel is armed when it opens while the clock, after any jump the open makes (opening from the timeline track or event list moves the clock to the panel), is before that moment; one opened at or past it without moving the clock (for example from its scene marker, or by the host) stays open until closed. A seek, rewind or pause never closes it; a step takes none (`bad-panels`); with none set, panels behave as before. `StoryPanelInput` and `StoryPanelPlaybackInput` gain `closeAfterSeconds`.
15
+ - Added: the look `sheetMaxPercent` (30 to 85, default 50; `scene.setLook`, `handle.setLook`, read by `handle.look`) caps the height of a phone's information and story sheet. It is the same value as the Developer drawer's "Sheet height" slider and has no page address parameter; `LookRead` gains `sheetMaxPercent`.
16
+ - Added: the look `time: { zone?, precision? }` (`scene.setLook`, `handle.setLook`; `handle.look.time` reads it back, default `{ zone: "UTC", precision: "second" }`) sets how the clock bar, the slider's spoken text, the bound dates, the event list and the event and window cards read: `zone` is `"UTC"` (ISO text, as before), `"local"` or an IANA name (the visitor's language style with the zone's short name), `precision` is `"day"`, `"minute"` or `"second"`. A zone the runtime does not know or an unknown precision throws `bad-look`. No page address parameter; the Developer drawer, `<time dateTime>` and the address `t` stay UTC. New types `TimeLook`; `LookRead` gains `time`.
17
+ - Fixed: a fractional or out-of-range time given to a call that takes a time (`stateOf`, `setTime`, timeline, event, sample, provider and body-set times) now throws a `SceneError` with code `bad-time` (still an `instanceof RangeError`), where `stateOf` and a provider's `stateAt` used to throw a plain `RangeError` and `stateOf(provider, 1e16)` threw "Invalid time value". The engine still refuses a fractional time rather than rounding it (I-176).
18
+ - Changed: a fractional or out-of-range story panel `at.time`, anchor `time` or `shownDuring` start or end, accepted before, is now refused with that call's own code (`bad-panels`, `bad-anchor`, `bad-body` or `bad-trajectory`), so every time the engine takes is a whole Unix millisecond.
19
+ - Fixed: a sky-line colour with alpha (`rgba()`, `hsla()`, `#rrggbbaa`, `#rgba`) now draws with that alpha, multiplied into the line's opacity, for figures, outlines, the ecliptic and equator, traces and the selected figure; the drawing library used to ignore it and log a warning.
20
+ - Fixed: the README, `EventInput` and `SceneEventRead` now agree that an event's `object` may be a body, path or sky figure.
21
+ - Added: `setTimeline({ playing: false })` opens the viewer paused on its opening time before the first frame (default stays playing); `scene.timeline.playing` reads it (a new field on `SceneTimelineRead`). A non-boolean throws `bad-timeline`.
22
+ - Fixed: playback that runs into a timeline edge now stops exactly on it (it used to land a few milliseconds past), and a moment panel at the timeline's end opens when forward playback stops there; a seek to the end still opens nothing.
23
+ - Fixed: `clearSkyTrace(id, { durationSeconds: 0 })` removes the lines and label on the next drawn frame even when the viewer is paused and still.
24
+ - Fixed: while the camera is already looking out, `setCamera({ lookOut, direction?, fovDeg? })`, a story panel's camera and the timeline's Go to now ease the look direction and the field of view instead of cutting; with `prefers-reduced-motion: reduce` they arrive on the next frame. Entering a look-out from the orbit camera still cuts.
25
+ - Fixed: in a look-out camera a tap on a sky figure's name or line wins over a body under it, and a tap on a body selects it and keeps the sky view instead of flying away; orbit-camera taps are unchanged.
26
+
27
+ ## 0.9.1 (2026-11-12)
28
+
29
+ First download of the packed example (`npm run measure:example`): 1,764,446 bytes raw, 507,330 bytes gzip (code and styles loaded on first open), against 1,759,084 raw and 505,483 gzip at 0.9.0 (+5,362 raw, +1,847 gzip). Additions and fixes only (G-019); every `astraeus-data*` package still peers on `>=0.9.0 <0.10.0`.
30
+
31
+ Added: `shownDuring: { start?, end? }` on `addBody`, `addBodyFromElements` and `addTrajectory` shows the body or path only while `start <= t < end` (an absent end is unbounded). Outside it the scene draws none of it (marker, line, label, orbit line) and it cannot be picked, in every view, through the same per-frame hidden set a view uses. Presentation only: `stateOf` and the readouts are unchanged. A bad value throws `bad-body` or `bad-trajectory`. An object outside its span is absent from the object menu (bar and phone drawer), `setSelected` and `setCamera` refuse it as they refuse a view-hidden id (`bad-selection`, `bad-camera`), and a selection it held is dropped when the clock leaves the span (`onSelect` reports the move's cause; the camera keeps its pose).
32
+
33
+ Fix: a `provider` path is no longer drawn at 128 evenly spaced moments alone. A one-hour flyby on a six-year path fell between two of them and was drawn as a straight line past the marker. The line now also takes moments where the path bends or the body moves fast, as seen from the path's `center`, up to 4,096 in all; where more would be needed (a very close, fast pass) the most useful are kept. A `samples` path and the public API are unchanged.
34
+
35
+ Fix: where pacing pieces overlap or their ramps meet, the paced speed is now what the README says, instead of a product of eases that was slower than both. Faster spans set the cruise (the faster wins where they meet); slower spans and event rules ease down from it (the slowest of what each alone would give wins where they meet), so a slow-down inside a faster span starts without a jump in speed. No call shape changed.
36
+
37
+ Fix: a `provider` path's `stateAt` is no longer handed a fractional time. `scene.stateOf` on a provider path now refuses a fractional or out-of-range time with the same plain `RangeError` a body or `samples` path gives, so a provider only ever sees whole Unix milliseconds, as documented (I-177).
38
+
39
+ Fix: with `prefers-reduced-motion: reduce`, every eased camera move (host `setCamera`, a view's camera rule, the timeline's Go to framing, the visitor's own picks) now arrives on the next frame instead of gliding; without it nothing changes. No call shape changed.
40
+
41
+ Docs: the README now states the whole-millisecond time rule (a fractional time throws a plain `RangeError` today), the ecliptic obliquity the engine rotates `plane: "ecliptic-j2000"` data by (84381.406 arcseconds, against JPL Horizons' 84381.448, about 30 km at 1 au), the `provider` `stateAt(timeUtcMs, center?)` contract and the State it returns, the orbit camera's 45 degree vertical field of view, the colours of an `addBodyFromElements` body and that path anchor labels are off until the `labels` switch is on.
42
+
43
+ Fix: playback now steps through every slow-down whatever the frame length. A frame used to run at the one speed read at its start, so a long frame at cruise could carry the clock over a whole zone and its ramps (a short one still could, at a fast cruise); each frame is now advanced through the speeds it crosses, so playback always eases into a zone and `onEventZone` reports it; the same holds while a view switch eases the speed (the ease now smooths only the change the switch caused, so a zone reached during it still slows playback). No call shape changed.
44
+
5
45
  ## 0.9.0 (2026-11-11)
6
46
 
7
47
  Look out at the sky, draw and trace any figure on it, tap it for a card, and tell a story in steps that turns to it and traces it (G-018). The new optional package `astraeus-data-constellations` supplies all 88 IAU constellations. Additions only, apart from one type-level change for apps that read the camera (`CameraPose` is now `OrbitPose | SkyPose`, see "Look out from a body" below). Every `astraeus-data*` package now peers on `astraeus` `>=0.9.0 <0.10.0`.
package/README.md CHANGED
@@ -77,39 +77,77 @@ The viewer's looks, scale and switches are settings, so a page can draw its own
77
77
 
78
78
  The full reference, generated from the types and doc comments, is at <https://astraeus.anipatke.com/api/>. The table below is the short form.
79
79
 
80
+ ### Bodies and paths
81
+
80
82
  | Call | What it does |
81
83
  |---|---|
82
84
  | `new Scene()` | An empty scene. Every method below returns the scene, so calls chain. |
83
- | `scene.addBody(body, { orbit?, enlarge?, showLabel?, labelReachEarthRadii?, description?, color?, knownLimitations?, readouts?, listed?, facts?, sources?, labelPriority? })` | 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; `labelReachEarthRadii` (a positive number, in Earth radii, 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`. `readouts` takes the list `addTrajectory` takes (`range`, `speed`, `distance`, `altitude`), measured from the scene's centre body, and draws it on the body's info card in place of the catalogue's own distance rows; a bad readout throws `bad-readout`, and a named body the scene does not hold throws `bad-readout` when the scene is built. `listed: false` (default true) leaves the body out of the object menu; it is still drawn and selectable, and the menu shows it while it is selected. `facts` (default none) is a list of `{ label, value }` rows, both non-empty, shown on the info card in order. `sources` (default none) is a list of non-empty texts added to the card's provenance after the body's own, and `scene.provenanceOf` includes them. `labelPriority` (a finite number; default `100 - index`, so bodies added earlier win) decides which label shows when labels overlap, the higher number winning. A bad value of any of these throws `bad-body`. `orbit` also takes `{ lapDays, fades? }` for a moon: it draws the line about its parent over one lap of `lapDays` (a positive number), whether or not the moon's data give a period (`phobos` and `deimos`, which have none, take it); `fades: true` fades the line's far end and `false` closes the loop, and when absent the moon's own rule applies (the Moon's line fades, others close); a bad lap throws `bad-body`, and a body that circles the Sun throws `no-orbit`. The scene's centre needs no setting: it is the first body added. 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. |
84
- | `scene.addTrajectory({ id, label?, color?, center?, plane?, lineFixedTo?, labelReachEarthRadii?, 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 (a comet from `addBodyFromElements`, every moon added only by id) is skipped, and `"auto"` is not usable as a body id; `labelReachEarthRadii` (a positive number, in Earth radii, 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. |
85
- | `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? }, plane: "ecliptic-j2000", source: { name, url, solution, accessed }, radius?, accuracy: { classification, statement, valid: { start, end }, limitations }, marker?: { color, sizePx } }`; `accuracy.valid` is `{ start, end }`, each ISO text such as `2030-01-01T00:00:00Z` (a record is usually JSON), a `Date` or milliseconds. 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`. |
85
+ | `scene.addBody(body, { orbit?, enlarge?, showLabel?, labelReachEarthRadii?, description?, color?, knownLimitations?, readouts?, listed?, facts?, sources?, labelPriority?, shownDuring? })` | 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; `labelReachEarthRadii` (a positive number, in Earth radii, 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`. `readouts` takes the list `addTrajectory` takes (`range`, `speed`, `distance`, `altitude`), measured from the scene's centre body, and draws it on the body's info card in place of the catalogue's own distance rows; a bad readout throws `bad-readout`, and a named body the scene does not hold throws `bad-readout` when the scene is built. `listed: false` (default true) leaves the body out of the object menu; it is still drawn and selectable, and the menu shows it while it is selected. `facts` (default none) is a list of `{ label, value }` rows, both non-empty, shown on the info card in order. `sources` (default none) is a list of non-empty texts added to the card's provenance after the body's own, and `scene.provenanceOf` includes them. `labelPriority` (a finite number; default `100 - index`, so bodies added earlier win) decides which label shows when labels overlap, the higher number winning. A bad value of any of these throws `bad-body`. `orbit` also takes `{ lapDays, fades? }` for a moon: it draws the line about its parent over one lap of `lapDays` (a positive number), whether or not the moon's data give a period (`phobos` and `deimos`, which have none, take it); `fades: true` fades the line's far end and `false` closes the loop, and when absent the moon's own rule applies (the Moon's line fades, others close); a bad lap throws `bad-body`, and a body that circles the Sun throws `no-orbit`. The scene's centre needs no setting: it is the first body added. 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. `shownDuring: { start?, end? }` (moments as `TimeInput`, at least one) shows the body only while `start <= t < end` (an absent end is unbounded); outside it nothing of it is drawn (marker, line, label, orbit line) and it cannot be picked, in every view; `stateOf` and the readouts are unchanged. Not an object, neither end, a bad moment or an end not after the start throws `bad-body`. |
86
+ | `scene.addTrajectory({ id, label?, color?, center?, plane?, lineFixedTo?, labelReachEarthRadii?, samples, provenance?, provenanceSpans?, shownDuring?, 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, about the engine's obliquity of 84381.406 arcseconds (IAU 2006; JPL Horizons uses 84381.448 arcseconds, IAU 1976, a difference of about 0.2 microradian, so ecliptic data from Horizons lands about 30 km off at 1 au) (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 (a comet from `addBodyFromElements`, every moon added only by id) is skipped, and `"auto"` is not usable as a body id; `labelReachEarthRadii` (a positive number, in Earth radii, 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. Every moment the API takes is whole Unix milliseconds once converted, never floored, so round a time converted from a Julian date: a fractional or out-of-range number throws a `SceneError` (still a `RangeError`) with code `bad-time` (`stateOf`, `setTime`, timeline, event, sample and provider times), or the call's own code where it has one for a bad moment (a story panel's `at.time`: `bad-panels`; an anchor's `time`: `bad-anchor`; `shownDuring`: `bad-body` or `bad-trajectory`). Instead of `samples` you may give `provider` (an object with `stateAt(timeUtcMs, center?)`) and `bounds: { start, end }`. The engine calls `stateAt` with whole-millisecond times inside `bounds`, sometimes with `center` (the path's centre body id, when it plans the line, checks its reach and answers `stateOf`) and sometimes without it; a fractional time is refused with `bad-time` before it reaches `stateAt`; either way return the State measured from the path's `center`. A State holds `body` (the path's id), `center`, `timeUtcMs`, `plane: "EQJ"` (for a path with `plane: "ecliptic-j2000"` the engine rotates the vectors itself), `positionKm` as a `Float64Array` of three finite numbers, `velocityKmS` (optional: without it the speed readout and the peak anchor speed show nothing) and `orientation: null` (a path has no modelled attitude). `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); their labels are off by default and show when the `labels` display switch is on (`handle.setSwitch("labels", true)`, the visitor's Labels button, or a scene whose `labels` switch starts on). `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. A `provider` path's line is drawn through 128 evenly spaced moments plus up to 3,968 more the engine adds where the path bends or the body moves fast, judged from the path's `center` (at most 4,096 in all), so a bend seen only against another body is not refined (a Sun-centred path drawn with `lineFixedTo: "earth"` past Earth keeps its chords there; give such a path an Earth `center` to draw the curve); a very close, fast pass that needs more is drawn at the most useful of them, so the line can still cut a corner there. A `samples` path is drawn at every sample. `shownDuring: { start?, end? }` (moments as `TimeInput`, at least one) shows the path only while `start <= t < end` (an absent end is unbounded); outside it nothing of it is drawn (marker, line, label, orbit line) and it cannot be picked, in every view; `stateOf` and the readouts are unchanged. Not an object, neither end, a bad moment or an end not after the start throws `bad-trajectory`. |
87
+ | `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? }, plane: "ecliptic-j2000", source: { name, url, solution, accessed }, radius?, accuracy: { classification, statement, valid: { start, end }, limitations }, marker?: { color, sizePx } }`; `accuracy.valid` is `{ start, end }`, each ISO text such as `2030-01-01T00:00:00Z` (a record is usually JSON), a `Date` or milliseconds. Drawn as a marker on unperturbed two-body motion about the Sun; colours: with a `color` option (`addBody`'s) the orbit line and the label take it and the dot takes `marker.color`, and without one all three take `marker.color` (default a pale blue); the source, accuracy and limits show on its info card, with a live "Distance from Sun" row. `options` are `addBody`'s, `shownDuring` included (`{ 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`. |
86
88
  | `scene.addBodySet({ id, families, members, provenance, center?, bodies?, centerGmKm3S2?, balancePoint?, orbitHistoryMs? })` | Many small bodies about one centre as one batch of dots, each selectable with an info card, with orbit lines coloured by family. `families` is one to sixteen of `{ id, label, color?, brightness? }` (colour a CSS hex colour, default the palette in family order; `brightness` the orbit-line multiplier, default 1). A member is `{ id, family, label?, radiusKm?, elements?, description?, facts?, provenance?, knownLimitations?, listed? }`: with no `elements` it is a listed moon of `center` (`listedMoons(planet)`; its positions come through `data`, as for `addBody`, and its label and radius default to the list's); with `elements` (`semiMajorAxisKm`, `eccentricity`, `inclinationDeg`, `raanDeg`, `argumentOfPeriapsisDeg`, `trueAnomalyDeg`, `time?`, `plane?`) it is a made-up member on two-body motion and needs `label` and `radiusKm`. A set is one kind or the other. `center` is a body in the scene (default the scene's first); `centerGmKm3S2` sizes each orbit line to one lap (default the centre's moon system, else its catalogue record; neither is `bad-body-set`). `bodies` are bodies added with `addBody` that belong to a family: their orbit lines take its colour, and one with no `orbit` of its own, if it is a listed moon of `center`, gets its line in this batch. `balancePoint` (`{ body, gmKm3S2 }`, a member or such a body) draws the lines about the balance point of the centre and that body (default the centre's moon system's own when its body is drawn here). `orbitHistoryMs` loads positions that long before the window so a line can reach back (default 0). Members are not in the Object menu unless `listed: true`. `stateOf` and `provenanceOf` accept member ids; story panels may name them; a view cannot name a set or a member. A repeated id throws `duplicate-id`; a mistake throws `bad-body-set`. |
87
- | `scene.setMoonPanel({ label, families, featuredFamily?, listSource?, listDate? })` | The sliding panel of a planet's moons by family. `label` is the name in the heading ("<label>'s moons"). `families` is `{ id, label, description, moons }` each, where a moon is `{ id, named? }`: a body (`addBody`) or a body-set member (`addBodySet`) of the scene, checked when the scene is built; its label comes from there, and `named: false` folds a provisional designation under "+N unnamed". A moon that is a body gets the picture the viewer's `data` brings for it (the packages' `pictures`); a dot gets none. `featuredFamily` is the family id listed first with pictures. `listSource` and `listDate` (a moment, kept as its day) say where and when the list was taken. Replaces any earlier panel. A malformed panel, or a moon the scene does not hold, throws `bad-moon-panel`. |
88
- | `scene.setPicker({ id, label, options, value })` | A choice in the viewer's top bar and phone drawer: one button per option `{ value, label }` (values unique), the option with `value` pressed when the viewer opens, `label` the accessible name of the group and `id` carried on the buttons as `data-switch-param`. Fewer than two options draw nothing. Replaces any earlier picker. A press only tells the host (`handle.onPick`, the `onPick` prop): the viewer never navigates, reads or writes the page address, or keeps a time, and the pressed button does not move until the host calls `handle.setPick` or mounts a new scene. A malformed picker, or a `value` that is not an option, throws `bad-picker`. |
89
- | `scene.addSkyFigures(figures)` | Figures and outlines drawn on the sky at infinity, like the stars (J2000 equatorial frame, presentation only), each with a label. Each is `{ id, label, kind?, segments?, points?, labelAt?, shown?, color?, labelColor?, labelFont?, labelSizePx?, description?, facts?, sources?, provenance?, listed? }`. A `"figure"` (the default `kind`) has `segments`, a non-empty list of `[end, end]` pairs, an end being `{ star: <Hipparcos number> }` (a star of the engine's star list, magnitude 6.5 or brighter) or `{ raDeg, decDeg }`; a `"boundary"` has `points`, a closed loop of at least three `{ raDeg, decDeg }` (the last joins the first). `labelAt` is `{ raDeg, decDeg }`; without it the label stands at the mean direction of the ends. Lines draw above the Sun's glow, from the orbit camera and from a look-out view; the labels join the viewer's one name layout and give way to body names. The switches `skyFigures` (on) and `skyBoundaries` (off) show each kind, and `ecliptic` and `celestialEquator` (both off) draw the two reference circles (`setSwitches`). `id` must be new among the scene's bodies, paths, groups, body sets and sky figures (`duplicate-id`, also for a repeat inside one call); a malformed figure throws `bad-sky-figure` and adds none of the call. A star number not in the star list throws `unknown-star` when the scene is built (`mount`, `prepare`; the list loads then, not at this call); a star list that cannot be read throws `missing-data` then. `color` and `labelColor` (CSS colours), `labelFont` (a CSS font-family text) and `labelSizePx` (8 to 24) are the figure's own line colour and label look, over the looks `skyLines` and `labels`; a bad one throws `bad-sky-figure`. `shown` is `"always"` (the default) or `"whenTraced"`: a `"whenTraced"` figure draws nothing (lines or label) until `traceSkyFigure` starts a trace of it (below); any other value throws `bad-sky-figure`. The card fields work as for `addBody` and `addTrajectory`: `description` (a non-empty text), `facts` (`{ label, value }` pairs), `sources` (texts added after the provenance's own), `provenance` (default illustrative, "Supplied by the caller") and `listed` (default true; false leaves the figure out of the object menu until it is selected); a bad one throws `bad-sky-figure`. A visitor selects a figure by tapping its name or within 16 px of one of its lines (never inside an outline); a body hit wins over a figure; a figure that is not drawn (its switch off, or `"whenTraced"` with no trace showing) cannot be tapped. The selected figure's lines and name take the look `skyLines.selected` and its card opens as a body's does. Read the result from `scene.skyFigures`. |
90
89
  | `scene.addPlaces(body, { categories, places, provenance, knownLimitations? })` | The tagged surface places of one body, drawn as markers on it and opened in the information panel. `categories` are `{ key, label, color }` (a CSS hex colour); `places` are `{ id, name, kind, category, latitudeDeg, longitudeDeg, description, details? }` (`id` unique within the body, `kind` shown as the place's kind such as "Crater", an unknown `category` draws white, longitude east-positive as the marker draws it, coordinates kept exactly as given, `details` card facts). `provenance` is shown with every place (PROV-01). The body must be in the scene when it is built; a second call for one body throws `duplicate-id`; a mistake throws `bad-places`. The place lists of 24 bodies ship as data in `astraeus-data` (`astraeus-data/bodies/<body>/{features,categories,map,overview}.json`, with `catalogue.json`); an app converts them to this input. |
91
90
  | `scene.addGroup({ id, orbits, plane, label?, center?, 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`, which you must give (`"ecliptic-j2000"` or `"EQJ"`; a group without one throws `bad-group`). 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`. |
91
+
92
+ ### Time, events and story
93
+
94
+ | Call | What it does |
95
+ |---|---|
92
96
  | `scene.setTime(time)` | The moment the scene opens at. |
93
- | `scene.setScale(trueScale \| readableScale \| solarSystemScale, { only? })` | The opening scale; the viewer can switch to the other unless `{ only: true }` offers that scale alone. `solarSystemScale` (true distances, enlarged bodies drawn larger) needs a Sun-centred scene with an enlarged body, else `bad-scale`; such a scene offers it second in place of `readableScale`. |
94
- | `scene.addEvents(events, { provenance? })` | Timed events on the timeline: `[{ id, label, time, type?, provenance?, object?, withinSeconds? }]`; it appends, and a repeated id, in one call or across calls, throws `duplicate-id`. `withinSeconds` (positive, finite, simulated seconds) gives the event its own zone, `time ± withinSeconds`, that a host hears with `onEventZone` and `eventZones` with or without pacing; a pacing `near` rule uses it in place of its own `withinSeconds` for that event. A bad value throws `bad-event` naming the event. `object` is the id of a body or trajectory in the scene the event is about: the timeline's Go to (and Previous/Next) seeks to the event and frames that object as `camera.focus` does (it is selected and Focus shows pressed); an event without one only seeks. An `object` the scene lacks throws `bad-event` naming the event and the id when the scene is built. `provenance` says where the times come from; an event's own `provenance` wins over the batch's. A provenance `sourceType` is `ephemeris`, `observed`, `reconstructed`, `modelled` or `illustrative`; `modelled` is shown as "Modelled". Batch and per-event provenance are checked: a malformed one throws `bad-event`. May be called more than once. |
95
- | `scene.addStoryPanels(list)` | Appends story panels: those with `at` open as playback reaches them; those without are steps (below): `[{ id, at?: { time } \| { event } \| { anchor }, title, body, details?, provenance, object?, camera?, select?, trace? }]`. `at.time` is any moment (ISO text, a `Date` or Unix milliseconds). `provenance` is `{ sourceType, sources, accuracy, notes }`: the badge shows the word for `sourceType`, and `sources`, `accuracy` and `notes` show in the panel's folded section. `sources` is never empty and `accuracy` is never blank; where a source states none, say so. A bad shape throws `bad-panels` at the call, naming the panel and field; a repeated id throws `duplicate-id`. The events, anchors and objects a panel names may be added later, so they are checked at `check` and `mount`, which throw `bad-panels`. A panel with no `at` is a step: steps keep the order added (across calls), never open from playback, and show Back and Next on the panel (Back is disabled on the first step, Next on the last). With steps and no moment panel the first step is open when the viewer opens, with or without a timeline (`setTimeline({ none: true })`); beside moment panels a step opens from its `object`'s marker or the host's `setPanel`. A panel's `object` may name a sky figure (it has no marker). Whenever a panel opens (by time, as a step, by the host or by a visitor) its actions apply, in this order, through the same paths as the host calls: `camera` (any target `setCamera` takes, checked as it checks; a look-out `direction` may name a sky figure, and without a `direction` the one already looked along is kept), `select: true` (selects the panel's `object`; needs an `object`; the card follows a visitor's tap, not `setSelected`: it opens on a wide screen and not on a phone, where it would cover the panel's Back and Next) and `trace` (`true` or options as `traceSkyFigure` takes; traces the panel's `object`, which must be a sky figure). Leaving the panel (another opens, or it closes) clears the trace it started with `clearSkyTrace`'s default fade; the camera and selection are left as they are, and so is anything the host or a visitor did in between. A bad shape throws `bad-panels` naming the panel and field, at the call; a name the scene lacks, at `check` and `mount`. |
96
- | `scene.setStoryPanelPlayback({ pauseSeconds?, autoOpen? })` | How story panels play: the seconds playback holds when a panel opens by itself (0 to 20, default 6; 0 never pauses) and whether panels open by themselves (default true). Replaces the whole setting; a bad value throws `bad-panels`. |
97
- | `scene.setTimeline({ start, end, rates?, rate?, loop?, pacing? })` | The timeline's span, the playback speeds offered (simulated seconds per real second) and the one it opens at. When `rate` or an offered rate would cross the whole span in under one real second (as `rate: 86_400_000`, a day in milliseconds, does over 120 days), `setTimeline` warns on the console naming the unit and the value, since the number is probably in milliseconds; it does not throw. `{ none: true, at?, rate? }` draws no timeline bar: time is frozen at `at`, or runs on at `rate`. The speed menu shows exactly the `rates` you give (ascending), and no others; without `rates` it offers 1 minute, 1 hour and 1 day per second. `pacing` slows playback for encounters and speeds it up for cruise, see "Paced playback" below. With a timeline bar and no `loop`, playback stops on the timeline's end instead of running past it. |
97
+ | `scene.addEvents(events, { provenance? })` | Timed events on the timeline: `[{ id, label, time, type?, provenance?, object?, withinSeconds? }]`; it appends, and a repeated id, in one call or across calls, throws `duplicate-id`. `withinSeconds` (positive, finite, simulated seconds) gives the event its own zone, `time ± withinSeconds`, that a host hears with `onEventZone` and `eventZones` with or without pacing; a pacing `near` rule uses it in place of its own `withinSeconds` for that event. A bad value throws `bad-event` naming the event. `object` is the id of a body, path (trajectory) or sky figure in the scene the event is about: the timeline's Go to (and Previous/Next) seeks to the event and frames that object as `camera.focus` does (it is selected and Focus shows pressed); an event without one only seeks. An `object` the scene lacks throws `bad-event` naming the event and the id when the scene is built. `provenance` says where the times come from; an event's own `provenance` wins over the batch's. A provenance `sourceType` is `ephemeris`, `observed`, `reconstructed`, `modelled` or `illustrative`; `modelled` is shown as "Modelled". Batch and per-event provenance are checked: a malformed one throws `bad-event`. May be called more than once. |
98
+ | `scene.addStoryPanels(list)` | Appends story panels: those with `at` open as playback reaches them; those without are steps (below): `[{ id, at?: { time } \| { event } \| { anchor }, title, body, details?, provenance, object?, camera?, select?, trace?, closeAfterSeconds? }]`. `at.time` is any whole-millisecond moment (ISO text, a `Date` or Unix milliseconds); a fractional or out-of-range one throws `bad-panels`. `provenance` is `{ sourceType, sources, accuracy, notes }`: the badge shows the word for `sourceType`, and `sources`, `accuracy` and `notes` show in the panel's folded section. `sources` is never empty and `accuracy` is never blank; where a source states none, say so. A bad shape throws `bad-panels` at the call, naming the panel and field; a repeated id throws `duplicate-id`. The events, anchors and objects a panel names may be added later, so they are checked at `check` and `mount`, which throw `bad-panels`. A panel with no `at` is a step: steps keep the order added (across calls), never open from playback, and show Back and Next on the panel (Back is disabled on the first step, Next on the last). With steps and no moment panel the first step is open when the viewer opens, with or without a timeline (`setTimeline({ none: true })`); beside moment panels a step opens from its `object`'s marker or the host's `setPanel`. A panel's `object` may name a sky figure (it has no marker). Whenever a panel opens (by time, as a step, by the host or by a visitor) its actions apply, in this order, through the same paths as the host calls: `camera` (any target `setCamera` takes, checked as it checks; a look-out `direction` may name a sky figure, and without a `direction` the one already looked along is kept), `select: true` (selects the panel's `object`; needs an `object`; the card follows a visitor's tap, not `setSelected`: it opens on a wide screen and not on a phone, where it would cover the panel's Back and Next) and `trace` (`true` or options as `traceSkyFigure` takes; traces the panel's `object`, which must be a sky figure). Leaving the panel (another opens, or it closes) clears the trace it started with `clearSkyTrace`'s default fade; the camera and selection are left as they are, and so is anything the host or a visitor did in between. A bad shape throws `bad-panels` naming the panel and field, at the call; a name the scene lacks, at `check` and `mount`. `closeAfterSeconds` (simulated seconds, above 0) on a moment panel closes it on the first forward-playing tick after it opened whose clock is at or past its time plus that span (armed when it opens while the clock, after any jump the open makes such as opening from the timeline, is before that moment; a panel opened at or past it without moving the clock, for example from its scene marker, stays open), overriding the playback setting; on a step, or when not a number above 0, it throws `bad-panels`. |
99
+ | `scene.setStoryPanelPlayback({ pauseSeconds?, autoOpen?, closeAfterSeconds? })` | How story panels play: the seconds playback holds when a panel opens by itself (0 to 20, default 6; 0 never pauses), whether panels open by themselves (default true) and `closeAfterSeconds`, the simulated seconds after a moment panel's time at which forward playback closes it (above 0; default none: a panel closes only when the visitor or host closes it; a panel's own `closeAfterSeconds` wins). The close is a state test: a panel that opened while the clock was before its close moment (by playback crossing it, or by the visitor or host opening it; the clock is read after any jump the open makes, so a panel opened from the timeline track or event list, which moves the clock to the panel, is armed) closes on the first forward-playing tick after the one it opened on whose clock ends at or past that moment, even when one frame carries the clock past the whole span; never on the opening tick, so a panel opened at high speed is seen first. A panel opened at or past its close moment (a visitor reopening it from its scene marker after the span, or the host) stays open until closed. A seek, rewind or pause never closes one, and `onPanel` hears the close with `cause: "playback"`. Replaces the whole setting; a bad value throws `bad-panels`. |
100
+ | `scene.setTimeline({ start, end, rates?, rate?, loop?, playing?, pacing? })` | The timeline's span, the playback speeds offered (simulated seconds per real second) and the one it opens at. When `rate` or an offered rate would cross the whole span in under one real second (as `rate: 86_400_000`, a day in milliseconds, does over 120 days), `setTimeline` warns on the console naming the unit and the value, since the number is probably in milliseconds; it does not throw. `{ none: true, at?, rate? }` draws no timeline bar: time is frozen at `at`, or runs on at `rate`. The speed menu shows exactly the `rates` you give (ascending), and no others; without `rates` it offers 1 minute, 1 hour and 1 day per second. `pacing` slows playback for encounters and speeds it up for cruise, see "Paced playback" below. With a timeline bar and no `loop`, playback stops exactly on the timeline's end (or start, at a negative rate) instead of running past it; a moment panel at the end opens when forward playback stops there (a seek to the end opens nothing). `playing: false` opens the viewer paused on its opening time before the first frame (default true: it opens playing); a non-boolean throws `bad-timeline`. `scene.timeline` states the opening play state as `playing`. Both `mount` and `AstraeusScene` honour it. |
98
101
  | `scene.addActivity({ id, label, unit, start, end, samples, peak?, provenance?, type?, peakLabel? })` | A period of activity on the timeline: a rate curve `samples: [{ time, value }]` (at least two, sorted, inside `start` to `end`; straight lines between) that the timeline glows by, with an optional `peak` mark and `provenance: [{ start, end, provenance }]` for where each stretch comes from. A group's `readouts: [{ kind: "rate", activity? }]` shows the live rate (unavailable outside the period) against the peak on its card. Without `setTimeline` the timeline spans the activities. A repeated id throws `duplicate-id`; a bad curve, peak or source throws `bad-activity`; a rate readout with no activity is `bad-readout`. |
102
+
103
+ ### The sky
104
+
105
+ | Call | What it does |
106
+ |---|---|
107
+ | `scene.addSkyFigures(figures)` | Figures and outlines drawn on the sky at infinity, like the stars (J2000 equatorial frame, presentation only), each with a label. Each is `{ id, label, kind?, segments?, points?, labelAt?, shown?, color?, labelColor?, labelFont?, labelSizePx?, description?, facts?, sources?, provenance?, listed? }`. A `"figure"` (the default `kind`) has `segments`, a non-empty list of `[end, end]` pairs, an end being `{ star: <Hipparcos number> }` (a star of the engine's star list, magnitude 6.5 or brighter) or `{ raDeg, decDeg }`; a `"boundary"` has `points`, a closed loop of at least three `{ raDeg, decDeg }` (the last joins the first). `labelAt` is `{ raDeg, decDeg }`; without it the label stands at the mean direction of the ends. Lines draw above the Sun's glow, from the orbit camera and from a look-out view; the labels join the viewer's one name layout and give way to body names. The switches `skyFigures` (on) and `skyBoundaries` (off) show each kind, and `ecliptic` and `celestialEquator` (both off) draw the two reference circles (`setSwitches`). `id` must be new among the scene's bodies, paths, groups, body sets and sky figures (`duplicate-id`, also for a repeat inside one call); a malformed figure throws `bad-sky-figure` and adds none of the call. A star number not in the star list throws `unknown-star` when the scene is built (`mount`, `prepare`; the list loads then, not at this call); a star list that cannot be read throws `missing-data` then. `color` and `labelColor` (CSS colours), `labelFont` (a CSS font-family text) and `labelSizePx` (8 to 24) are the figure's own line colour and label look, over the looks `skyLines` and `labels`; a bad one throws `bad-sky-figure`. `shown` is `"always"` (the default) or `"whenTraced"`: a `"whenTraced"` figure draws nothing (lines or label) until `traceSkyFigure` starts a trace of it (below); any other value throws `bad-sky-figure`. The card fields work as for `addBody` and `addTrajectory`: `description` (a non-empty text), `facts` (`{ label, value }` pairs), `sources` (texts added after the provenance's own), `provenance` (default illustrative, "Supplied by the caller") and `listed` (default true; false leaves the figure out of the object menu until it is selected); a bad one throws `bad-sky-figure`. A visitor selects a figure by tapping its name or within 16 px of one of its lines (never inside an outline); orbiting, a body hit wins over a figure; looking out, a figure's name or line wins over a body under it (the sky is the subject), and a tap on a body selects it without leaving the look-out (the menu's Focus and Follow still fly there); a figure that is not drawn (its switch off, or `"whenTraced"` with no trace showing) cannot be tapped. The selected figure's lines and name take the look `skyLines.selected` and its card opens as a body's does. Read the result from `scene.skyFigures`. |
108
+
109
+ ### The camera
110
+
111
+ | Call | What it does |
112
+ |---|---|
99
113
  | `scene.camera.setReach(distance, { farEarthRadii? })` | How far the viewer can zoom out, in Earth radii; the far plane (where drawing stops) is 2.5 times it unless `farEarthRadii` (a finite number of at least `distance`, in Earth radii) sets it; 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.focus`) 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.focus` 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. |
100
114
  | `scene.camera.setStartView(pose)` | Opens at a pose (what `handle.camera` reads, either kind: an orbit pose `{ focus, azimuthDeg, elevationDeg, distance }`, distance in Earth radii, or a sky pose `{ lookOut, raDeg, decDeg, fovDeg }`) with no camera button pressed, so Focus does not show as pressed and choosing another body moves the camera as it would without a start. `focus` or `lookOut` must be a body or path already added (`unknown-body`); a bad angle, distance or field of view throws `bad-camera`. The last of `follow`, `focus`, `lookOut` and `setStartView` wins. Default: none. |
101
115
  | `scene.camera.lookOut(body, { direction?, fovDeg? })` | Opens standing inside a body (at its centre) and looking out, with no camera button pressed. `direction` takes the same forms as `setCamera`'s look-out, checked by the same rule: a star-map position `{ raDeg, decDeg }` (J2000 equatorial degrees; default right ascension 0, declination 0), or the id of an object or sky figure to turn toward (an object the opening view shows, or a figure added before or after this call); `fovDeg` is the vertical field of view in degrees (5 to 100; default 60). The body must be already added (`unknown-body`); a direction or field of view out of range, a malformed direction, an unknown key, or a `look` that is not an object throws `bad-camera` at the call; an id that names nothing the opening view can turn toward throws `bad-camera` naming it when the scene is built. With a position it is the same as `setStartView` with a sky pose. With an id the viewer turns toward it on its first frame as `setCamera` does, so until then there is no pose: `scene.camera.pose` is undefined and `handle.camera` reads undefined before the first frame. The body stood in is not drawn while looking out. `scene.camera.lookOut("earth", { direction: { raDeg: 83.6, decDeg: 22 }, fovDeg: 40 })`, `scene.camera.lookOut("earth", { direction: "Leo", fovDeg: 80 })` |
102
116
  | `scene.camera.setFollowChoices(ids)` | Which objects offer a Follow button in the camera menu, by body or id already added (`unknown-body`); the others offer Focus only, and an empty list offers Follow on none. Default: every body, path and group. An opening `camera.follow` of an object not in the list throws `bad-camera` when the scene is built. |
103
117
  | `scene.camera.setLookOutChoices(ids)` | Which bodies offer a "Look out from" entry in the camera menu (O-064 T-293), by body or id already added (`unknown-body`; a non-list is `bad-camera`). The entry sits with Focus and Follow on the bar and the phone drawer and stands inside the body looking toward right ascension 0, declination 0; Focus, Follow, Overview or an orbit `setCamera` leaves the sky view. Default: none. The opening `camera.lookOut` does not need the body listed. `scene.camera.setLookOutChoices(["earth", "mars"])` |
118
+ | `scene.camera.setFocusChoices(ids)` | Which objects offer a Focus button in the camera menu, by body or id already added (`unknown-body`; a non-list is `bad-camera`); the others offer none, and an empty list offers Focus on none. Default: every body, path and group. An opening `camera.focus` of an object not in the list throws `bad-camera` when the scene is built. |
119
+ | `scene.camera.setOverview(on)` | Whether the camera menu offers Overview (default true); a non-boolean throws `bad-camera`. Overview is also what the viewer returns to when the camera's object goes away, so a scene with it off holds its pose instead. |
120
+ | `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 orbit camera's vertical field of view is 45 degrees). 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")` |
121
+ | `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. |
122
+ | `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. |
123
+
124
+ A sky-only viewer (Look out and its switches, no orbit-camera buttons): `scene.camera.setFocusChoices([]).setFollowChoices([]).setOverview(false).setLookOutChoices(["earth"])`, `scene.setScale(x, { only: true })` to drop the scale choice, and `scene.setSwitches({ skyBoundaries: { place: "top-bar", label: "Constellation outlines" } })` for a named switch. The Info button and related-object buttons stay.
125
+
126
+ ### Looks, controls and views
127
+
128
+ | Call | What it does |
129
+ |---|---|
130
+ | `scene.setMoonPanel({ label, families, featuredFamily?, listSource?, listDate? })` | The sliding panel of a planet's moons by family. `label` is the name in the heading ("<label>'s moons"). `families` is `{ id, label, description, moons }` each, where a moon is `{ id, named? }`: a body (`addBody`) or a body-set member (`addBodySet`) of the scene, checked when the scene is built; its label comes from there, and `named: false` folds a provisional designation under "+N unnamed". A moon that is a body gets the picture the viewer's `data` brings for it (the packages' `pictures`); a dot gets none. `featuredFamily` is the family id listed first with pictures. `listSource` and `listDate` (a moment, kept as its day) say where and when the list was taken. Replaces any earlier panel. A malformed panel, or a moon the scene does not hold, throws `bad-moon-panel`. |
131
+ | `scene.setPicker({ id, label, options, value })` | A choice in the viewer's top bar and phone drawer: one button per option `{ value, label }` (values unique), the option with `value` pressed when the viewer opens, `label` the accessible name of the group and `id` carried on the buttons as `data-switch-param`. Fewer than two options draw nothing. Replaces any earlier picker. A press only tells the host (`handle.onPick`, the `onPick` prop): the viewer never navigates, reads or writes the page address, or keeps a time, and the pressed button does not move until the host calls `handle.setPick` or mounts a new scene. A malformed picker, or a `value` that is not an option, throws `bad-picker`. |
132
+ | `scene.setScale(trueScale \| readableScale \| solarSystemScale, { only? })` | The opening scale; the viewer can switch to the other unless `{ only: true }` offers that scale alone. `solarSystemScale` (true distances, enlarged bodies drawn larger) needs a Sun-centred scene with an enlarged body, else `bad-scale`; such a scene offers it second in place of `readableScale`. |
104
133
  | `scene.setBodyReadouts(kinds)` | Which rows a body's info card shows, in order: `"distance"`, `"phase"`, `"coordinates"`; replaces the earlier choice. Default `["distance"]`. A body whose `addBody` gave its own `readouts` keeps those. An unknown kind throws `bad-readout`. |
105
- | `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")` |
106
- | `scene.setLook({ starBrightness?, milkyWay?, milkyWayBrightness?, skyVisible?, sunGlow?: { sizePx?, brightness?, scale? }, markerSwapRadiusPx?, featureMinBodyPx?, loadFadeSeconds?, skyFadeInSeconds?, desktopPictures?, skyLines?: { figure?, label?, boundary?, ecliptic?, equator?, traced?, faded?, selected? }, labels?: { fontFamily?, sizePx? } })` | 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); `skyFadeInSeconds` 0 to 3 (0.5), how long sky figures, outlines and the reference circles, with their names, take to fade in when the viewer opens and each time their switch turns on (0 shows them at once, as does a visitor's reduced-motion setting; a figure shown only when traced appears by its trace), with no page address parameter; `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. `skyLines` sets the colours of the sky lines and their names as CSS colour texts (hex, a name, or comma-form `rgb()`/`rgba()`/`hsl()`/`hsla()`): `figure` `"#8fb4ff"`, `label` `"#cfe0ff"` (the names), `boundary` `"#5f7a9c"`, `ecliptic` `"#e0b25a"`, `equator` `"#7fd1b9"`, `traced` `"#ffd166"` and `faded` `"#44546d"` (the last two are for the lines a trace draws, in a later step); `labels` sets the font (`fontFamily`, a CSS font-family text, default `"inherit"`, the page's own) and size (`sizePx`, 8 to 24, default 12) of every label in the viewer (bodies, paths, sky figures and anchors), so the defaults keep the labels as they were; a sky figure may set its own. A colour the viewer cannot read, an empty font or a size out of range throws `bad-look`. `skyLines` and `labels` have no page address parameter: they are set here, with `handle.setLook` and in the Developer drawer only. 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`. |
107
- | `scene.setSwitches({ orbitLines?, labels?, milkyWay?, skyFigures?, skyBoundaries?, ecliptic?, celestialEquator? })` | 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; `skyFigures` and `skyBoundaries` are the figures and the outlines of `addSkyFigures` (a switch the scene has no figure of shows nowhere); `ecliptic` and `celestialEquator` are the two reference circles of the sky. `on` is the starting state (default on, except `skyBoundaries`, `ecliptic` and `celestialEquator`, which start off). Nothing placed: the bar is as before. A bad name, place or `on` throws `bad-switch`. |
134
+ | `scene.setLook({ starBrightness?, milkyWay?, milkyWayBrightness?, skyVisible?, sunGlow?: { sizePx?, brightness?, scale? }, markerSwapRadiusPx?, featureMinBodyPx?, loadFadeSeconds?, skyFadeInSeconds?, desktopPictures?, skyLines?: { figure?, label?, boundary?, ecliptic?, equator?, traced?, faded?, selected? }, labels?: { fontFamily?, sizePx? }, time?: { zone?, precision? }, sheetMaxPercent? })` | 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); `skyFadeInSeconds` 0 to 3 (0.5), how long sky figures, outlines and the reference circles, with their names, take to fade in when the viewer opens and each time their switch turns on (0 shows them at once, as does a visitor's reduced-motion setting; a figure shown only when traced appears by its trace), with no page address parameter; `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. `skyLines` sets the colours of the sky lines and their names as CSS colour texts (hex, a name, or comma-form `rgb()`/`rgba()`/`hsl()`/`hsla()`; a colour with alpha, such as `rgba(143, 180, 255, 0.5)` or `#8fb4ff80`, draws its lines with that alpha times the line's own opacity, for every line colour and a figure's own `color`): `figure` `"#8fb4ff"`, `label` `"#cfe0ff"` (the names), `boundary` `"#5f7a9c"`, `ecliptic` `"#e0b25a"`, `equator` `"#7fd1b9"`, `traced` `"#ffd166"` and `faded` `"#44546d"` (the last two are for the lines a trace draws, in a later step); `labels` sets the font (`fontFamily`, a CSS font-family text, default `"inherit"`, the page's own) and size (`sizePx`, 8 to 24, default 12) of every label in the viewer (bodies, paths, sky figures and anchors), so the defaults keep the labels as they were; a sky figure may set its own. A colour the viewer cannot read, an empty font or a size out of range throws `bad-look`. `time` sets how times read (clock bar, slider text, bound dates, event list, event and window cards): `zone` is `"UTC"` (default, ISO text as before), `"local"` or an IANA name such as `"Australia/Sydney"`, `precision` is `"day"`, `"minute"` or `"second"` (default); a local or named zone reads in the visitor's language style with its short zone name. `sheetMaxPercent` 30 to 85 (50) is the tallest a phone's information or story sheet grows, as a percent of the screen height; the Developer drawer's "Sheet height" slider is this same value, and it has no address parameter. A zone `Intl` refuses throws `bad-look`. `<time dateTime>`, the Developer drawer and the address `t` stay UTC. `skyLines`, `labels` and `time` have no address parameter: set them here or with `handle.setLook` (`skyLines` and `labels` also in the Developer drawer). 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`. |
135
+ | `scene.setSwitches({ orbitLines?, labels?, milkyWay?, skyFigures?, skyBoundaries?, ecliptic?, celestialEquator? })` | Where each display switch shows: `{ place: "top-bar" \| "panel" \| "developer", on?, label? }`. 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; `skyFigures` and `skyBoundaries` are the figures and the outlines of `addSkyFigures` (a switch the scene has no figure of shows nowhere); `ecliptic` and `celestialEquator` are the two reference circles of the sky. `on` is the starting state (default on, except `skyBoundaries`, `ecliptic` and `celestialEquator`, which start off). Nothing placed: the bar is as before. A bad name, place or `on` throws `bad-switch`. `label` (a non-empty text, else `bad-switch`) is the switch's own name in the bar button and the panel row in place of the built-in one (the Developer drawer's controls keep their own fixed names); a later call replaces the whole entry, so one without `label` returns the built-in name. |
108
136
  | `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. |
137
+
138
+ ### Numbers without a viewer
139
+
140
+ | Call | What it does |
141
+ |---|---|
109
142
  | `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;` |
110
143
  | `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] });` |
111
144
  | `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] });` |
112
145
  | `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 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. |
146
+
147
+ ### What a scene holds
148
+
149
+ | Call | What it does |
150
+ |---|---|
113
151
  | `scene.bodies` | What the scene holds, as plain frozen lists you can check in a test without a viewer (a fresh list on every read; they answer on a scene a viewer has taken). `bodies`: `{ id, label, parent?, orbit, enlarge, description?, knownLimitations, listed, facts?, texture? }` in the order added (the first is the scene's centre; `orbit` says its orbit line is on, `enlarge` is 1 unless enlarged; `knownLimitations` are the card's: given, else the catalogue's; `listed` and `facts` are what `addBody` set, `listed` true by default; `texture` is the picture and licence the engine ships for the body, as a credits page lists it, absent for a body drawn from a data package's picture or a flat colour). |
114
152
  | `scene.paths` | `{ id, label, center, provenance, description?, knownLimitations }` per `addTrajectory`, in the order added. |
115
153
  | `scene.bodySets` | `{ id, center, count, families }` per `addBodySet`, in the order added; a fresh frozen list on every read. |
@@ -123,9 +161,15 @@ The full reference, generated from the types and doc comments, is at <https://as
123
161
  | `scene.panels` | `{ id, timeUtcMs?, title, body, details, provenance, object? }` per `addStoryPanels` (the actions are not read): the moment panels sorted by time, the times resolved as `mount` resolves them, then the steps (no `timeUtcMs`) in the order added (a bad panel throws `bad-panels`). |
124
162
  | `scene.views` | `{ startId, place, items: [{ id, label, objects, events, panels }] }` as named with `setViews`; undefined when none were named. `objects`, `events` and `panels` are the ids each view shows, as the viewer resolves them: what the view names plus whatever no view names (shared bodies show in every view). Fresh frozen lists on every read. The ids are checked as `mount` checks them, so an unknown one throws `bad-view`. |
125
163
  | `scene.scales` | The scale choices the viewer will offer, in order, as ids (`"true-scale"`, `"readable-scale"`, `"solar-system"`); the first is the opening scale. |
126
- | `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`). |
127
- | `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. |
128
- | `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. |
164
+ | `scene.look` | The looks `setLook` set, every one filled in (`LookRead`): the values `handle.look` reads on a fresh mount with no page address override; `sunGlow` is absent without the Sun. Frozen. |
165
+ | `scene.switches` | `{ [id]: { place, on, label? } }` for each switch `setSwitches` named (`on` true when not given); an unnamed switch is absent. Frozen. |
166
+ | `scene.panelPlayback` | `{ pauseSeconds, autoOpen, closeAfterSeconds? }` from `setStoryPanelPlayback`, defaults filled in; `closeAfterSeconds` absent when none was set. Frozen. |
167
+ | `scene.timeline` | `{ windowStartUtcMs, windowEndUtcMs, openUtcMs, rates, rate, loop, playing, pacing? }`: the span and opening moment in UTC milliseconds, the speeds offered, the opening speed, whether playback wraps and `pacing` (when `setTimeline` gave it: `{ spanStartUtcMs, spanEndUtcMs, rate, rampSeconds }` or `{ near: { type, withinSeconds }, rate, rampSeconds }` pieces, ramps filled in; frozen). 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`). |
168
+
169
+ ### Drawing it
170
+
171
+ | Call | What it does |
172
+ |---|---|
129
173
  | `mount(element, scene, { data?, onChange?, address?, developerTools? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), timeUtcMs, rate, playing, view, camera, eventZones, selected, panel, look, scale, switches, skyFigures, pick, setTime(t), setRate(r), setPlaying(p), setView(id), setCamera(target), setSelected(id), setPanel(id), setLook(look), setScale(id), setSwitch(id), traceSkyFigure(id), clearSkyTrace(id), setPick(value), onChange(fn), onEventZone(fn), onSelect(fn), onPanel(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". |
130
174
  | `<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). |
131
175
  | `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. |
@@ -162,6 +206,8 @@ Props: `scene`, `data` (as for `mount`), `ref` (a React 19 ref prop that receive
162
206
 
163
207
  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.
164
208
 
209
+ ### Clock and changes
210
+
165
211
  | Name | What it does |
166
212
  |------|--------------|
167
213
  | `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. |
@@ -169,24 +215,10 @@ The viewer has one clock (and, with `setViews`, one current view: rows below). A
169
215
  | `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`. |
170
216
  | `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`. |
171
217
  | `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`. |
172
- | `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`, `skyFadeInSeconds`, `desktopPictures`, `skyLines` and `labels` as filled-in objects), 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
218
  | `handle.onFirstDraw(fn)` or `<AstraeusScene onFirstDraw />` | `fn()` once when the scene's first frame has been drawn (not `ready`, which resolves a moment earlier, when the clock attaches), for fading your own loading cover; returns a function that stops it. A listener added after that frame is called at once. A rebuild with a new `scene` draws a new first frame and calls the listeners still added again (the React prop is called again). A listener that throws is reported to the page (`reportError`) and does not stop the next; nothing arrives after `unmount`. |
174
- | `handle.pick`, `handle.setPick(value)`, `handle.onPick(fn)` or `<AstraeusScene onPick />` | `pick` reads the value of the pressed option of the scene's picker (`undefined` until `ready`, after `unmount`, and without a picker). `setPick(value)` moves the pressed option and does nothing else (no signal); a scene without a picker, or an unknown value, throws `bad-picker`; before `ready` or after `unmount`, `not-mounted`. `fn({ picker, value })` is called when a visitor presses an option other than the pressed one; the pressed option stays where it was until the host calls `setPick` (or builds a new scene). To keep the clock across a choice, read `handle.timeUtcMs` inside `fn`, build the next scene and call `setTime` on it once ready. Returns a function that stops it. A listener that throws is reported to the page (`reportError`) and does not stop the next; nothing arrives after `unmount`. |
175
- | `handle.scale`, `handle.setScale(id)` | The id of the scale showing, and a switch to one of `scene.scales` as if a visitor pressed the scale button; any other id throws `bad-scale`. |
176
- | `handle.switches`, `handle.setSwitch(id, on)` | The display switches the scene placed with `setSwitches` (`orbitLines`, `labels`, `milkyWay`, `skyFigures`, `skyBoundaries`, `ecliptic`, `celestialEquator`; wherever it placed them) that have something to act on, each `true` (on) or `false`; `{}` when it placed none. `setSwitch` turns one on or off as the visitor's button does; an id the scene did not place, or a non-boolean, throws `bad-switch`. |
177
- | `handle.skyFigures` | The sky figures the viewer draws (`scene.addSkyFigures`), `{ id, label, kind, listed, provenance, description?, facts? }` each, in the order added; `[]` when the scene added none; undefined before `ready` and after `unmount`. |
178
- | `handle.traceSkyFigure(id, { durationSeconds?, after? })` | Draws the sky figure `id` (one of `handle.skyFigures`) line by line: its segments in the order added, each growing from its first end, over `durationSeconds` (0.1 to 60, default 2) in the look's `skyLines.traced` colour. Then `after` decides: `"stay"` (default) keeps the traced lines until the figure is traced again, `"fade"` eases them to `skyLines.faded` over a second and removes them (`clearSkyTrace` removes a trace at any time). The trace is drawn over the figure (for a figure with `shown: "whenTraced"` the trace is the whole drawing: lines growing in order, the label appearing when the trace starts; `"stay"` keeps both, `"fade"` dims both to nothing over the second, `clearSkyTrace` removes both, and a new trace starts again from nothing) and follows its switch (`skyFigures` or `skyBoundaries`): with the switch off it runs unseen. It runs on real time, so pausing or changing the speed of the scene clock does not change it, and it starts only when the app asks (no trace is timed by the scene clock). Calling again restarts it. With `prefers-reduced-motion: reduce` the whole figure shows at once, stays for `durationSeconds`, and then `after` applies (a `fade` ends at once). An id the viewer does not draw throws `unknown-sky-figure`; bad options throw `bad-sky-trace`; before `ready` or after `unmount`, `not-mounted`. Like every host call it lands in call order. |
179
219
  | `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`. |
180
220
  | `<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. |
181
221
  | `<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`. |
182
- | `handle.clearSkyTrace(id, { durationSeconds? })` | Removes the trace of the sky figure `id` at any time: while it runs, after `"stay"`, or during a `"fade"`. The traced lines ease out over `durationSeconds` (0 to 60, default 1, the time a `"fade"` takes; 0 removes them at once), keeping the part drawn so far. A figure with `shown: "whenTraced"` is then hidden (lines and label); an always-shown figure only loses the trace highlight. A figure with no trace is left alone (no error), and a new trace starts from nothing. With `prefers-reduced-motion: reduce` the trace goes at once. An id the viewer does not draw throws `unknown-sky-figure`; bad options throw `bad-sky-trace`; before `ready` or after `unmount`, `not-mounted`. Like every host call it lands in call order. |
183
- | `handle.panel`, `handle.setPanel(id)`, `handle.onPanel(fn)` | The id of the open story panel or step (undefined when none), opening another by id (or `undefined` to close the open one), and `onPanel({ panel?, timeUtcMs, cause })` when it changes (`panel` absent when it closed; `cause` is `visitor` for Close, Back, Next, a marker or the timeline, `host` for `setPanel` or a drop by the host's `setView`, `playback` for a moment panel that opened by itself). The panel the viewer opens with is read, not reported. An id the showing view does not show, or a non-string, throws `bad-panels`; before `ready` or after `unmount`, `not-mounted`. Calls land in order. |
184
- | `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"`. |
185
- | `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"`). |
186
- | `<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`. |
187
- | `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, `{ lookOut: id, direction?, fovDeg? }` stands inside the body looking out (`direction` is `{ raDeg, decDeg }`, J2000 equatorial degrees, or the id of an object or sky figure to turn toward; omitted, it keeps the direction already looked along, else right ascension 0, declination 0; `fovDeg` is 5 to 100 degrees, omitted keeps the current one, else 60; Focus, Follow, Overview or an orbit pose return to the orbit camera), and a pose from `handle.camera` (either kind) puts the camera back (below). Every id must be an object the showing view shows: an unknown or hidden id (the body, or the object to turn toward), a direction or field of view out of range, or a malformed argument, throws `bad-camera`; before `ready` or after `unmount`, `not-mounted`. |
188
- | `handle.camera` | The camera now as a plain value of one of two kinds, a `CameraPose`, which is an `OrbitPose` or a `SkyPose`. Tell them apart with `"lookOut" in pose` (a sky pose has no `distance`): an app that reads `pose.distance` must first check `if ("lookOut" in pose) { /* sky pose: lookOut, raDeg, decDeg, fovDeg */ } else { /* orbit pose */ }`. While the camera orbits an object it is the orbit pose `{ focus, azimuthDeg, elevationDeg, distance }`; while it stands inside a body looking out it is the sky pose `{ lookOut, raDeg, decDeg, fovDeg }` (the body's id; where it points in J2000 equatorial degrees, right ascension 0 up to 360 and declination within ±90, rounded to 0.01; the vertical field of view in degrees, 5 to 100) and the copied view link carries it as `?view=body,raDeg,decDeg,fovDeg,sky`. For an orbit pose (the pose a copied view link carries: the object's id, angles about the up direction in degrees to 0.01, distance in Earth radii to five figures). Safe to keep, store or `JSON.stringify`. `undefined` until `ready` and after `unmount`; from `ready` on it is defined (before the scene's first frame it is the opening pose, the scene's start view or default framing), except that an opening `lookOut` toward an object or sky figure id reads `undefined` until the first frame has turned toward it. `setCamera(handle.camera)` after the visitor has moved the camera puts it back at the same angles and distance from the same object, within the rounding; the offset is the object's own, so an object that moved meanwhile is followed from where it is now. A camera held in place by a view's `"stay"` rule reads as its last object, which is not where it looks. |
189
- | `<AstraeusScene camera />` | `{ follow: id }`, `{ focus: id }`, `{ lookOut: id, direction?, fovDeg? }` or a pose (either kind), applied once drawn and whenever its value changes (a new object with the same target, or a pose with its keys in another order, does not apply again); not a controlled value. A bad one goes to `onError` as `bad-camera`. |
190
222
 
191
223
  ```ts
192
224
  const mounted = mount(el, scene);
@@ -200,6 +232,41 @@ const stop = mounted.onChange(({ timeUtcMs, cause }) => {
200
232
 
201
233
  The speed menu shows exactly the `rates` the scene gives (`setTimeline({ rates })`) and no others.
202
234
 
235
+ ### Looks, picker, scale and switches
236
+
237
+ | Name | What it does |
238
+ |------|--------------|
239
+ | `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`, `skyFadeInSeconds`, `desktopPictures`, `skyLines`, `labels` and `time` as filled-in objects, and `sheetMaxPercent`; `time` is `{ zone, precision }`, default `{ zone: "UTC", precision: "second" }`), 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`. |
240
+ | `handle.pick`, `handle.setPick(value)`, `handle.onPick(fn)` or `<AstraeusScene onPick />` | `pick` reads the value of the pressed option of the scene's picker (`undefined` until `ready`, after `unmount`, and without a picker). `setPick(value)` moves the pressed option and does nothing else (no signal); a scene without a picker, or an unknown value, throws `bad-picker`; before `ready` or after `unmount`, `not-mounted`. `fn({ picker, value })` is called when a visitor presses an option other than the pressed one; the pressed option stays where it was until the host calls `setPick` (or builds a new scene). To keep the clock across a choice, read `handle.timeUtcMs` inside `fn`, build the next scene and call `setTime` on it once ready. Returns a function that stops it. A listener that throws is reported to the page (`reportError`) and does not stop the next; nothing arrives after `unmount`. |
241
+ | `handle.scale`, `handle.setScale(id)` | The id of the scale showing, and a switch to one of `scene.scales` as if a visitor pressed the scale button; any other id throws `bad-scale`. |
242
+ | `handle.switches`, `handle.setSwitch(id, on)` | The display switches the scene placed with `setSwitches` (`orbitLines`, `labels`, `milkyWay`, `skyFigures`, `skyBoundaries`, `ecliptic`, `celestialEquator`; wherever it placed them) that have something to act on, each `true` (on) or `false`; `{}` when it placed none. `setSwitch` turns one on or off as the visitor's button does; an id the scene did not place, or a non-boolean, throws `bad-switch`. |
243
+
244
+ ### Sky traces
245
+
246
+ | Name | What it does |
247
+ |------|--------------|
248
+ | `handle.skyFigures` | The sky figures the viewer draws (`scene.addSkyFigures`), `{ id, label, kind, listed, provenance, description?, facts? }` each, in the order added; `[]` when the scene added none; undefined before `ready` and after `unmount`. |
249
+ | `handle.traceSkyFigure(id, { durationSeconds?, after? })` | Draws the sky figure `id` (one of `handle.skyFigures`) line by line: its segments in the order added, each growing from its first end, over `durationSeconds` (0.1 to 60, default 2) in the look's `skyLines.traced` colour. Then `after` decides: `"stay"` (default) keeps the traced lines until the figure is traced again, `"fade"` eases them to `skyLines.faded` over a second and removes them (`clearSkyTrace` removes a trace at any time). The trace is drawn over the figure (for a figure with `shown: "whenTraced"` the trace is the whole drawing: lines growing in order, the label appearing when the trace starts; `"stay"` keeps both, `"fade"` dims both to nothing over the second, `clearSkyTrace` removes both, and a new trace starts again from nothing) and follows its switch (`skyFigures` or `skyBoundaries`): with the switch off it runs unseen. It runs on real time, so pausing or changing the speed of the scene clock does not change it, and it starts only when the app asks (no trace is timed by the scene clock). Calling again restarts it. With `prefers-reduced-motion: reduce` the whole figure shows at once, stays for `durationSeconds`, and then `after` applies (a `fade` ends at once). An id the viewer does not draw throws `unknown-sky-figure`; bad options throw `bad-sky-trace`; before `ready` or after `unmount`, `not-mounted`. Like every host call it lands in call order. |
250
+ | `handle.clearSkyTrace(id, { durationSeconds? })` | Removes the trace of the sky figure `id` at any time: while it runs, after `"stay"`, or during a `"fade"`. The traced lines ease out over `durationSeconds` (0 to 60, default 1, the time a `"fade"` takes; 0 removes them at once, on the next drawn frame even while paused), keeping the part drawn so far. A figure with `shown: "whenTraced"` is then hidden (lines and label); an always-shown figure only loses the trace highlight. A figure with no trace is left alone (no error), and a new trace starts from nothing. With `prefers-reduced-motion: reduce` the trace goes at once. An id the viewer does not draw throws `unknown-sky-figure`; bad options throw `bad-sky-trace`; before `ready` or after `unmount`, `not-mounted`. Like every host call it lands in call order. |
251
+
252
+ ### Story panels, selection and views
253
+
254
+ | Name | What it does |
255
+ |------|--------------|
256
+ | `handle.panel`, `handle.setPanel(id)`, `handle.onPanel(fn)` | The id of the open story panel or step (undefined when none), opening another by id (or `undefined` to close the open one), and `onPanel({ panel?, timeUtcMs, cause })` when it changes (`panel` absent when it closed; `cause` is `visitor` for Close, Back, Next, a marker or the timeline, `host` for `setPanel` or a drop by the host's `setView`, `playback` for a moment panel that opened by itself). The panel the viewer opens with is read, not reported. An id the showing view does not show, or a non-string, throws `bad-panels`; before `ready` or after `unmount`, `not-mounted`. Calls land in order. |
257
+ | `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"`. |
258
+ | `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"`). |
259
+ | `<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`. |
260
+
261
+ ### Camera from the host
262
+
263
+ | Name | What it does |
264
+ |------|--------------|
265
+ | `handle.setCamera(target)` | Points the camera, through the same request path a view's camera rule uses; it eases there (a look-out turn and field of view too, when the camera is already looking out; entering a look-out from the orbit camera cuts), or, with `prefers-reduced-motion: reduce`, arrives on the next frame (as does every camera move in the viewer: a view's camera rule, the timeline's Go to framing, the visitor's own picks). `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, `{ lookOut: id, direction?, fovDeg? }` stands inside the body looking out (`direction` is `{ raDeg, decDeg }`, J2000 equatorial degrees, or the id of an object or sky figure to turn toward; omitted, it keeps the direction already looked along, else right ascension 0, declination 0; `fovDeg` is 5 to 100 degrees, omitted keeps the current one, else 60; Focus, Follow, Overview or an orbit pose return to the orbit camera), and a pose from `handle.camera` (either kind) puts the camera back (below). Every id must be an object the showing view shows: an unknown or hidden id (the body, or the object to turn toward), a direction or field of view out of range, or a malformed argument, throws `bad-camera`; before `ready` or after `unmount`, `not-mounted`. |
266
+ | `handle.camera` | The camera now as a plain value of one of two kinds, a `CameraPose`, which is an `OrbitPose` or a `SkyPose`. Tell them apart with `"lookOut" in pose` (a sky pose has no `distance`): an app that reads `pose.distance` must first check `if ("lookOut" in pose) { /* sky pose: lookOut, raDeg, decDeg, fovDeg */ } else { /* orbit pose */ }`. While the camera orbits an object it is the orbit pose `{ focus, azimuthDeg, elevationDeg, distance }`; while it stands inside a body looking out it is the sky pose `{ lookOut, raDeg, decDeg, fovDeg }` (the body's id; where it points in J2000 equatorial degrees, right ascension 0 up to 360 and declination within ±90, rounded to 0.01; the vertical field of view in degrees, 5 to 100) and the copied view link carries it as `?view=body,raDeg,decDeg,fovDeg,sky`. For an orbit pose (the pose a copied view link carries: the object's id, angles about the up direction in degrees to 0.01, distance in Earth radii to five figures). Safe to keep, store or `JSON.stringify`. `undefined` until `ready` and after `unmount`; from `ready` on it is defined (before the scene's first frame it is the opening pose, the scene's start view or default framing), except that an opening `lookOut` toward an object or sky figure id reads `undefined` until the first frame has turned toward it. `setCamera(handle.camera)` after the visitor has moved the camera puts it back at the same angles and distance from the same object, within the rounding; the offset is the object's own, so an object that moved meanwhile is followed from where it is now. A camera held in place by a view's `"stay"` rule reads as its last object, which is not where it looks. |
267
+ | `<AstraeusScene camera />` | `{ follow: id }`, `{ focus: id }`, `{ lookOut: id, direction?, fovDeg? }` or a pose (either kind), applied once drawn and whenever its value changes (a new object with the same target, or a pose with its keys in another order, does not apply again); not a controlled value. A bad one goes to `onError` as `bad-camera`. |
268
+
269
+
203
270
  ### Views of one scene
204
271
 
205
272
  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):
@@ -229,11 +296,11 @@ A long journey wants fast cruising and slow encounters. `setTimeline` takes `pac
229
296
  | `{ start, end, rate, rampSeconds? }` | Plays at `rate` between the two moments. |
230
297
  | `{ near: { type, withinSeconds }, rate, rampSeconds? }` | Plays at `rate` within `withinSeconds` seconds (simulated) of every event whose `type` matches (`addEvents`). |
231
298
 
232
- Speeds ease between pieces in log space over `rampSeconds` simulated seconds (default: `withinSeconds` for an event rule, a tenth of the span for a span; `rampSeconds: 0` steps), so a jump from cruise to encounter is smooth both ways. The paced speed depends only on the time, so seeking or looping lands on the right speed at once. Spans may not overlap (touching is fine); where an event rule meets a span or another rule, the slowest speed wins, whichever contains the other and in whatever order they are listed. A piece's `rate` is any positive number and need not be in `rates`. Mistakes throw `bad-timeline` naming the field (`pacing[1].rate`); an event `type` that matches no event is refused too, since a typo would otherwise slow nothing.
299
+ Speeds ease between pieces in log space over `rampSeconds` simulated seconds (default: `withinSeconds` for an event rule, a tenth of the span for a span; `rampSeconds: 0` steps), so a jump from cruise to encounter is smooth both ways. The paced speed depends only on the time, so seeking or looping lands on the right speed at once. Playback eases into every slow-down whatever the frame rate: each frame is stepped through the speeds it crosses, so a slow or stalled frame (or a fast cruise) never carries the clock past a zone or its ramp, and `onEventZone` hears every zone. Spans may not overlap (touching is fine). Faster spans (above the timeline's `rate`) set the cruise, and the faster wins where two meet. Slower spans and event rules ease down from that cruise, so the speed never jumps where a slow-down starts inside a faster span; where such pieces overlap or their ramps meet, the speed is the slowest of what each alone would give at that moment (never slower than all of them), whichever contains the other and in whatever order they are listed. A piece that would be faster than the cruise there changes nothing. A piece's `rate` is any positive number and need not be in `rates`. Mistakes throw `bad-timeline` naming the field (`pacing[1].rate`); an event `type` that matches no event is refused too, since a typo would otherwise slow nothing.
233
300
 
234
- 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.
301
+ 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: the ease smooths only the change the switch itself caused, and a slow-down reached during it still slows playback (frames are still stepped through the eased speed), while seeking lands on the paced speed at once. A scene without views paces exactly as before.
235
302
 
236
- 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 a sky figure (an id in `skyFigures`; its card opens), 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`.
303
+ 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, or out of an object's `shownDuring` span); 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 a sky figure (an id in `skyFigures`; its card opens), 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 id, one the view hides or one outside its `shownDuring` span, 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 is dropped when its object leaves its shown time (the camera then keeps its pose), and an object outside its span is absent from the object menu. A selection cleared by the host stays cleared until someone selects again. `onSelect` returns the function that stops it; nothing arrives after `unmount`.
237
304
 
238
305
  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.
239
306
 
@@ -335,7 +402,7 @@ Every call that refuses its input throws a `SceneError`, a `RangeError` with a s
335
402
  |---|---|
336
403
  | `unknown-body` | A body or path id is not in the catalogue or the scene. |
337
404
  | `duplicate-id` | An id is already used in the scene, so the new body, path, group, orbit line, activity, event or story panel cannot take it. |
338
- | `bad-time` | A moment is not a valid time, or lies outside the span it must fall in. |
405
+ | `bad-time` | A moment is not a valid or whole time, or lies outside the span it must fall in. |
339
406
  | `bad-trajectory` | A path (`addTrajectory`) is malformed: its id, provider, bounds, plane, spans or line stretches. |
340
407
  | `bad-data` | A data package passed to the viewer is malformed, for example moon positions that name a planet without a moon system. |
341
408
  | `bad-scale` | The scale is not one of the engine's scales, or does not suit this scene. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "astraeus",
3
- "version": "0.9.0",
3
+ "version": "0.9.2",
4
4
  "description": "A 3D solar system engine for the browser: place bodies and recorded paths in a scene, mount it, and get time controls, camera, scale choice and body info. Planet positions and the main pictures included.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -8,7 +8,7 @@ import { needsPlanetSeries } from "../app/planetNeeds.js";
8
8
  import { createReadoutMetrics } from "../app/trackedMetrics.js";
9
9
  import { checkDataSources, installData } from "./data.js";
10
10
  import { SceneError } from "./errors.js";
11
- import { cameraPresetsOf, checkOpeningLook, fitFarthestKm, startPresetEntry, startViewEntry, viewEntries } from "./planCamera.js";
11
+ import { cameraChoicesOf, cameraPresetsOf, checkOpeningChoices, checkOpeningLook, fitFarthestKm, startPresetEntry, startViewEntry, viewEntries } from "./planCamera.js";
12
12
  import { groupLayersEntry, lateGroups } from "./planGroups.js";
13
13
  import { autoPaths, checkNamedReadouts, checkReadouts, pathCover } from "./planPaths.js";
14
14
  import { loadStarCatalogue, starIdsOf } from "../assets/sky.js";
@@ -100,12 +100,11 @@ export function assembleScene(parts, data) {
100
100
  const setLayers = bodySets.layers({ ids, catalogue: plan.catalogue, orbits: plan.orbits, window, startUtcMs });
101
101
  const labelled = [...plan.bodies.values(), ...tracked, ...[...groupPlan.groups.values()]].map(({ id, label }) => ({ id, label }));
102
102
  const catalogue = plan.catalogue;
103
- if (camera.following && camera.target !== undefined && camera.followChoices !== undefined && !camera.followChoices.includes(camera.target))
104
- throw new SceneError("bad-camera", `camera.follow("${camera.target}"): the opening view follows "${camera.target}", which camera.setFollowChoices does not list`);
103
+ checkOpeningChoices(camera);
105
104
  story.checkObjects(new Set([...labelled.map(({ id }) => id), ...skyFigures.figures.keys()]));
106
105
  const objects = [
107
106
  ...[...plan.bodies.values()].map((body) => plan.bodyObject(body, ids, sunCentred, camera)),
108
- ...[...trackedMap.values()].map(({ body, description, knownLimitations, provenanceSpans }) => ({ id: body.id, label: body.label, color: body.color, availability: body.trajectory.bounds, labelPriority: 80, ...plan.labelReach(body.id, sunCentred, camera), provenance: body.provenance, ...(provenanceSpans === undefined ? {} : { provenanceSpans }), ...(description === undefined ? {} : { description }), ...(knownLimitations === undefined ? {} : { knownLimitations }) })),
107
+ ...[...trackedMap.values()].map(({ body, description, knownLimitations, provenanceSpans, shownDuring }) => ({ id: body.id, label: body.label, color: body.color, availability: body.trajectory.bounds, labelPriority: 80, ...plan.labelReach(body.id, sunCentred, camera), provenance: body.provenance, ...(provenanceSpans === undefined ? {} : { provenanceSpans }), ...(shownDuring === undefined ? {} : { shownDuring }), ...(description === undefined ? {} : { description }), ...(knownLimitations === undefined ? {} : { knownLimitations }) })),
109
108
  ...bodySets.objects({ ids, catalogue: plan.catalogue }),
110
109
  ];
111
110
  const pictures = mergePictures(data.map((source) => source.pictures));
@@ -116,7 +115,8 @@ export function assembleScene(parts, data) {
116
115
  const definition = {
117
116
  experience: {
118
117
  objects,
119
- cameraPresets: cameraPresetsOf(labelled, camera.followChoices, camera.lookOutChoices),
118
+ cameraPresets: cameraPresetsOf(labelled, cameraChoicesOf(camera)),
119
+ ...(cameraChoicesOf(camera).focus === undefined ? {} : { focusListed: true }),
120
120
  ...startPresetEntry(camera),
121
121
  ...(moonFamilies === undefined ? {} : { moonFamilies }),
122
122
  ...(bodyFeatures.length === 0 ? {} : { bodyFeatures }),
@@ -4,7 +4,7 @@ export type SceneErrorCode =
4
4
  "unknown-body"
5
5
  /** An id is already used in the scene, so the new body, path, group, orbit line, activity, event or story panel cannot take it. */
6
6
  | "duplicate-id"
7
- /** A moment is not a valid time, or lies outside the span it must fall in. */
7
+ /** A moment is not a valid or whole time, or lies outside the span it must fall in. */
8
8
  | "bad-time"
9
9
  /** A path (`addTrajectory`) is malformed: its id, provider, bounds, plane, spans or line stretches. */
10
10
  | "bad-trajectory"
@@ -1,4 +1,4 @@
1
- export { Scene, type SceneCamera, type AddBodyOptions, type CardFactInput, type OrbitLapInput, type BodyReadoutKind, type AnchorInput, type ReadoutInput, type DataSource, type SceneLoadOptions, type SceneBodyRead, type SceneActivityRead, type ScenePathRead, type SceneGroupRead, type SceneBodySetRead, type SceneMoonPanelRead, type ScenePlacesRead, type SceneSkyFigureRead, type SceneEventRead, type ScenePanelRead, type SceneViewRead, type SceneViewsRead, type SceneTimelineRead, type MoonPositions, type MoonIndex, type FollowView, type GroupInput, type GroupOrbitInput, type GroupClumpInput, type GroupReadoutInput, type ActivityInput, type ActivitySampleInput, type ActivitySourceInput, type ElementsBodyRecord, type TimeInput, type TrajectoryInput, type TrajectorySampleInput, type TrajectoryBase } from "./scene.js";
1
+ export { Scene, type SceneCamera, type AddBodyOptions, type CardFactInput, type OrbitLapInput, type BodyReadoutKind, type AnchorInput, type ReadoutInput, type DataSource, type SceneLoadOptions, type SceneBodyRead, type SceneActivityRead, type ScenePathRead, type SceneGroupRead, type SceneBodySetRead, type SceneMoonPanelRead, type ScenePlacesRead, type SceneSkyFigureRead, type SceneEventRead, type ScenePanelRead, type SceneViewRead, type SceneViewsRead, type SceneTimelineRead, type ScenePacingRead, type ScenePanelPlaybackRead, type SceneSwitchRead, type MoonPositions, type MoonIndex, type FollowView, type GroupInput, type GroupOrbitInput, type GroupClumpInput, type GroupReadoutInput, type ActivityInput, type ActivitySampleInput, type ActivitySourceInput, type ShownDuringInput, type ElementsBodyRecord, type TimeInput, type TrajectoryInput, type TrajectorySampleInput, type TrajectoryBase } from "./scene.js";
2
2
  export type { MoonPanelInput, MoonPanelFamilyInput, MoonPanelMoonInput, PlacesInput, PlaceInput, PlaceCategoryInput } from "./moonPanelInput.js";
3
3
  export type { SkyFigureInput, SkyFigureEnd } from "./skyFigureInput.js";
4
4
  export type { SkyClearOptions, SkyTraceOptions } from "./skyTraceInput.js";
@@ -6,7 +6,7 @@ export type { PickerInput, PickerOptionInput, PickChange } from "./pickerInput.j
6
6
  export type { BodySetInput, BodySetFamilyInput, BodySetMemberInput, BodySetElementsInput, BodySetBodyInput, BodySetBalanceInput } from "./bodySetInput.js";
7
7
  export { type EventInput, type AddEventsOptions, type TimelineInput, type PacingInput, type StoryPanelAt, type StoryPanelInput, type StoryPanelPlaybackInput } from "./story.js";
8
8
  export { type SwitchesInput } from "./switches.js";
9
- export { type LookInput, type LookRead, type SunGlowLook, type SkyLinesLook, type LabelsLook } from "./look.js";
9
+ export { type LookInput, type LookRead, type SunGlowLook, type SkyLinesLook, type LabelsLook, type TimeLook } from "./look.js";
10
10
  export { type ViewsOptions, type ViewInput, type ViewCameraInput } from "./views.js";
11
11
  export { mount, type MountOptions, type MountedScene } from "./mount.js";
12
12
  export { type ViewerHandle } from "./viewerHandle.js";