astraeus 0.9.1 → 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 (70) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +20 -13
  3. package/package.json +1 -1
  4. package/src/api/assembleScene.js +4 -4
  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/planCamera.d.ts +19 -2
  11. package/src/api/planCamera.js +45 -6
  12. package/src/api/planPaths.js +2 -2
  13. package/src/api/planStory.d.ts +3 -1
  14. package/src/api/planStory.js +5 -0
  15. package/src/api/planTimeline.d.ts +1 -1
  16. package/src/api/planTimeline.js +10 -1
  17. package/src/api/planViews.d.ts +3 -1
  18. package/src/api/planViews.js +4 -0
  19. package/src/api/scene.d.ts +11 -5
  20. package/src/api/scene.js +16 -2
  21. package/src/api/sceneReads.d.ts +31 -1
  22. package/src/api/story.d.ts +9 -2
  23. package/src/api/story.js +10 -3
  24. package/src/api/switches.d.ts +1 -0
  25. package/src/api/switches.js +3 -1
  26. package/src/api/time.d.ts +1 -1
  27. package/src/api/time.js +4 -1
  28. package/src/app/App.js +26 -6
  29. package/src/app/App.node.js +26 -6
  30. package/src/app/AstraeusScene.d.ts +8 -1
  31. package/src/app/CameraController.d.ts +2 -0
  32. package/src/app/CameraController.js +11 -1
  33. package/src/app/SkyFiguresView.d.ts +2 -2
  34. package/src/app/SkyFiguresView.js +25 -14
  35. package/src/app/displaySwitches.d.ts +2 -0
  36. package/src/app/displaySwitches.js +1 -1
  37. package/src/app/liveLook.d.ts +4 -1
  38. package/src/app/liveLook.js +29 -1
  39. package/src/app/look.d.ts +5 -0
  40. package/src/app/look.js +8 -2
  41. package/src/app/sceneCamera.js +14 -2
  42. package/src/app/sceneContentsHooks.js +1 -1
  43. package/src/app/sceneFrame.js +2 -2
  44. package/src/app/scenePointer.d.ts +5 -1
  45. package/src/app/scenePointer.js +8 -3
  46. package/src/app/timeLook.d.ts +7 -0
  47. package/src/app/timeLook.js +8 -0
  48. package/src/core/clock.js +2 -1
  49. package/src/core/lookValues.d.ts +13 -0
  50. package/src/core/lookValues.js +39 -0
  51. package/src/core/state.d.ts +2 -0
  52. package/src/core/state.js +5 -1
  53. package/src/core/storyPanels.d.ts +8 -4
  54. package/src/core/storyPanels.js +17 -5
  55. package/src/shell/AstraeusShell.d.ts +5 -1
  56. package/src/shell/AstraeusShell.js +15 -8
  57. package/src/shell/AstraeusShell.node.js +15 -8
  58. package/src/shell/ObjectControls.js +1 -1
  59. package/src/shell/TimelineBar.d.ts +6 -2
  60. package/src/shell/TimelineBar.js +17 -12
  61. package/src/shell/TimelineBar.node.js +17 -12
  62. package/src/shell/experience.d.ts +2 -0
  63. package/src/shell/infoModel.d.ts +2 -1
  64. package/src/shell/infoModel.js +10 -10
  65. package/src/shell/storyPanels.d.ts +19 -1
  66. package/src/shell/storyPanels.js +34 -2
  67. package/src/shell/timelineModel.d.ts +11 -0
  68. package/src/shell/timelineModel.js +28 -0
  69. package/src/shell/useStoryPanels.d.ts +4 -0
  70. package/src/shell/useStoryPanels.js +27 -6
package/CHANGELOG.md CHANGED
@@ -2,6 +2,28 @@
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
+
5
27
  ## 0.9.1 (2026-11-12)
6
28
 
7
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`.
package/README.md CHANGED
@@ -83,7 +83,7 @@ The full reference, generated from the types and doc comments, is at <https://as
83
83
  |---|---|
84
84
  | `new Scene()` | An empty scene. Every method below returns the scene, so calls chain. |
85
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. Times the engine is asked about (`stateOf`, a provider's `stateAt`) are whole Unix milliseconds: a fractional or out-of-range number throws a plain `RangeError` (no `code`, not a `SceneError`; I-176 tracks changing that), so round a time converted from a Julian date. 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 the `RangeError` above 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`. |
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
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`. |
88
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`. |
89
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. |
@@ -94,17 +94,17 @@ The full reference, generated from the types and doc comments, is at <https://as
94
94
  | Call | What it does |
95
95
  |---|---|
96
96
  | `scene.setTime(time)` | The moment the scene opens at. |
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 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. |
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? }]`. `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`. |
99
- | `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`. |
100
- | `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. |
101
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
102
 
103
103
  ### The sky
104
104
 
105
105
  | Call | What it does |
106
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); 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`. |
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
108
 
109
109
  ### The camera
110
110
 
@@ -115,10 +115,14 @@ The full reference, generated from the types and doc comments, is at <https://as
115
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 })` |
116
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. |
117
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. |
118
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")` |
119
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. |
120
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. |
121
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
+
122
126
  ### Looks, controls and views
123
127
 
124
128
  | Call | What it does |
@@ -127,8 +131,8 @@ The full reference, generated from the types and doc comments, is at <https://as
127
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`. |
128
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`. |
129
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`. |
130
- | `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`. |
131
- | `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. |
132
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. |
133
137
 
134
138
  ### Numbers without a viewer
@@ -157,7 +161,10 @@ The full reference, generated from the types and doc comments, is at <https://as
157
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`). |
158
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`. |
159
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. |
160
- | `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`). |
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`). |
161
168
 
162
169
  ### Drawing it
163
170
 
@@ -229,7 +236,7 @@ The speed menu shows exactly the `rates` the scene gives (`setTimeline({ rates }
229
236
 
230
237
  | Name | What it does |
231
238
  |------|--------------|
232
- | `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`. |
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`. |
233
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`. |
234
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`. |
235
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`. |
@@ -240,7 +247,7 @@ The speed menu shows exactly the `rates` the scene gives (`setTimeline({ rates }
240
247
  |------|--------------|
241
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`. |
242
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. |
243
- | `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. |
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. |
244
251
 
245
252
  ### Story panels, selection and views
246
253
 
@@ -255,7 +262,7 @@ The speed menu shows exactly the `rates` the scene gives (`setTimeline({ rates }
255
262
 
256
263
  | Name | What it does |
257
264
  |------|--------------|
258
- | `handle.setCamera(target)` | Points the camera, through the same request path a view's camera rule uses; it eases there, 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`. |
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`. |
259
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. |
260
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`. |
261
268
 
@@ -395,7 +402,7 @@ Every call that refuses its input throws a `SceneError`, a `RangeError` with a s
395
402
  |---|---|
396
403
  | `unknown-body` | A body or path id is not in the catalogue or the scene. |
397
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. |
398
- | `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. |
399
406
  | `bad-trajectory` | A path (`addTrajectory`) is malformed: its id, provider, bounds, plane, spans or line stretches. |
400
407
  | `bad-data` | A data package passed to the viewer is malformed, for example moon positions that name a planet without a moon system. |
401
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.1",
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,8 +100,7 @@ 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)),
@@ -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 ShownDuringInput, 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";
package/src/api/look.d.ts CHANGED
@@ -33,6 +33,13 @@ export interface LabelsLook {
33
33
  /** Text size in pixels, 8 to 24. Default 12. */
34
34
  readonly sizePx?: number;
35
35
  }
36
+ /** The zone and precision of the viewer's times. */
37
+ export interface TimeLook {
38
+ /** `"UTC"` (default, ISO text), `"local"` (the visitor's zone) or an IANA name such as `"Australia/Sydney"`; else `bad-look`. */
39
+ readonly zone?: string;
40
+ /** `"day"`, `"minute"` or `"second"` (default). */
41
+ readonly precision?: "day" | "minute" | "second";
42
+ }
36
43
  /** The looks a scene may set with `Scene.setLook`: presentation settings that change how the scene is drawn, never where anything is. Each is optional and keeps its default when absent. */
37
44
  export interface LookInput {
38
45
  /** Brightness of the catalogue stars, 0 to 2; 1 is the baseline star curve and 0 hides them in effect. Default 1. */
@@ -59,6 +66,10 @@ export interface LookInput {
59
66
  readonly skyLines?: SkyLinesLook;
60
67
  /** The font and size of every label. Default: the page's font at 12 pixels, as before. */
61
68
  readonly labels?: LabelsLook;
69
+ /** How times read in the clock bar, event list and cards. Default UTC to the second. */
70
+ readonly time?: TimeLook;
71
+ /** The tallest a phone's information or story sheet grows, as a percent of the screen height, 30 to 85. Default 50. Has no page address parameter; the Developer drawer's "Sheet height" slider is this same value. */
72
+ readonly sheetMaxPercent?: number;
62
73
  }
63
74
  /** The looks a running viewer shows, every one filled in (`ViewerHandle.look`): the scene's `setLook`, the page address and the Developer drawer laid over the defaults. `sunGlow` is absent in a scene without the Sun. */
64
75
  export interface LookRead {
@@ -93,4 +104,7 @@ export interface LookRead {
93
104
  readonly fontFamily: string;
94
105
  readonly sizePx: number;
95
106
  };
107
+ readonly time: Required<TimeLook>;
108
+ /** The phone sheet's height cap in force, a percent of the screen height (30 to 85). */
109
+ readonly sheetMaxPercent: number;
96
110
  }
@@ -1,3 +1,3 @@
1
1
  import type { LookInput } from "./look.js";
2
- /** Checks a `setLook` argument: an object of known looks, each a finite number in its range, a boolean, a CSS colour or a font-family text as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
2
+ /** Checks a `setLook` argument: an object of known looks, each a finite number in its range, a boolean, a CSS colour, a font-family text, a time zone or one of a few names as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
3
3
  export declare function checkedLook(input: LookInput): LookInput;
@@ -1,8 +1,8 @@
1
- import { isCssColour, isFontFamily } from "../core/lookValues.js";
1
+ import { isCssColour, isFontFamily, isTimeZone } from "../core/lookValues.js";
2
2
  import { LOOK_FIELDS, lookName, lookValue, lookWith } from "../app/look.js";
3
3
  import { SceneError } from "./errors.js";
4
4
  const TOP_LEVEL = [...new Set(LOOK_FIELDS.map(({ path }) => path[0]))];
5
- /** Checks a `setLook` argument: an object of known looks, each a finite number in its range, a boolean, a CSS colour or a font-family text as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
5
+ /** Checks a `setLook` argument: an object of known looks, each a finite number in its range, a boolean, a CSS colour, a font-family text, a time zone or one of a few names as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
6
6
  export function checkedLook(input) {
7
7
  const bad = (message) => new SceneError("bad-look", `setLook: ${message}`);
8
8
  const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -40,6 +40,10 @@ function valueProblem(field, value) {
40
40
  return typeof value === "number" && Number.isFinite(value) && value >= spec.min && value <= spec.max ? null : `must be a number from ${spec.min} to ${spec.max}`;
41
41
  if (spec.kind === "colour")
42
42
  return isCssColour(value) ? null : "must be a CSS colour such as \"#8fb4ff\" or \"rgb(143, 180, 255)\"";
43
+ if (spec.kind === "zone")
44
+ return isTimeZone(value) ? null : "must be \"UTC\", \"local\" or an IANA zone name such as \"Australia/Sydney\"";
45
+ if (spec.kind === "choice")
46
+ return typeof value === "string" && spec.values.includes(value) ? null : `must be one of ${spec.values.map((v) => JSON.stringify(v)).join(", ")}`;
43
47
  if (spec.kind === "font")
44
48
  return isFontFamily(value) ? null : "must be a non-empty CSS font-family text";
45
49
  return typeof value === "boolean" ? null : "must be true or false";
@@ -6,6 +6,10 @@ import type { BodyRef } from "./bodies.js";
6
6
  import type { FollowView } from "./scene.js";
7
7
  import type { CameraPose, SkyDirection } from "./viewerLink.js";
8
8
  import type { TimelineSetting } from "./story.js";
9
+ /** Every camera button choice the scene made: `focus` and `follow` list objects (undefined: every one), `lookOut` the bodies, `overview` whether Overview shows. */
10
+ export declare function cameraChoicesOf(camera: SceneCamera): CameraChoices & {
11
+ readonly overview: boolean;
12
+ };
9
13
  /** The scene's camera: what it opens on. */
10
14
  export declare class SceneCamera {
11
15
  #private;
@@ -43,6 +47,10 @@ export declare class SceneCamera {
43
47
  * scene.camera.setFollowChoices(["moon"]);
44
48
  */
45
49
  setFollowChoices(ids: readonly (BodyRef | BodyId)[]): this;
50
+ /** The objects offering Focus, as `setFollowChoices`. */
51
+ setFocusChoices(ids: readonly (BodyRef | BodyId)[]): this;
52
+ /** Whether Overview shows (default true). */
53
+ setOverview(on: boolean): this;
46
54
  /**
47
55
  * Chooses the bodies whose "Look out from" entry the camera menu offers, by body, id or path already added to the scene (else `unknown-body`); the entry stands inside the body and looks out, and any other camera entry leaves it.
48
56
  * Default: none. An empty list offers none. The opening view is separate: `lookOut` opens looking out whether or not the body is listed.
@@ -86,6 +94,8 @@ export declare class SceneCamera {
86
94
  get following(): boolean;
87
95
  get view(): FollowView;
88
96
  }
97
+ /** Refuses an opening `follow` or `focus` of an object the scene's `setFollowChoices` or `setFocusChoices` leaves out. Called when the scene is built. */
98
+ export declare function checkOpeningChoices(camera: SceneCamera): void;
89
99
  /**
90
100
  * Refuses an opening look-out toward an id `setCamera` would refuse on the opening view (`checkToward`, the same check and wording): the direction must name an object the opening view shows or a sky figure.
91
101
  * Called when the scene is built, after every figure is in.
@@ -104,8 +114,15 @@ export declare function startPresetEntry(camera: SceneCamera): {
104
114
  export declare function startViewEntry(camera: SceneCamera): Pick<ExperienceDefinition, "startView">;
105
115
  /** The playback and camera settings the scene asked for: looping, the farthest zoom-out and the ecliptic up. */
106
116
  export declare function viewEntries(timeline: TimelineSetting | undefined, camera: SceneCamera, farthestKm: (() => number) | undefined, cover: (() => number) | undefined): Pick<ExperienceDefinition, "loop" | "camera" | "viewUp">;
107
- /** The camera menu: Overview, Focus for every body and path, Follow for every one unless `setFollowChoices` named fewer, and "Look out from" for the bodies `setLookOutChoices` listed (the look is toward right ascension 0, declination 0 until the visitor turns). */
117
+ /** Which camera buttons the menu offers: `focus` and `follow` list the objects (undefined: every one), `lookOut` the bodies (none by default), `overview` whether Overview shows (default true). */
118
+ export interface CameraChoices {
119
+ readonly focus?: readonly string[];
120
+ readonly follow?: readonly string[];
121
+ readonly lookOut?: readonly string[];
122
+ readonly overview?: boolean;
123
+ }
124
+ /** The camera menu: Overview unless `setOverview(false)`, Focus and Follow for every body and path unless `setFocusChoices` or `setFollowChoices` named fewer, and "Look out from" for the bodies `setLookOutChoices` listed (the look is toward right ascension 0, declination 0 until the visitor turns). */
108
125
  export declare function cameraPresetsOf(objects: readonly {
109
126
  readonly id: string;
110
127
  readonly label: string;
111
- }[], followChoices?: readonly string[], lookOutChoices?: readonly string[]): ExperienceDefinition["experience"]["cameraPresets"];
128
+ }[], choices?: CameraChoices): ExperienceDefinition["experience"]["cameraPresets"];
@@ -7,6 +7,14 @@ import { farthestSunDistanceKm } from "./sunOrbit.js";
7
7
  import { planetSeriesLoaded } from "../core/planetSeries.js";
8
8
  /** Each camera's opening look-out toward an id, kept out of the public class: the request the viewer runs on its first frame, as it runs a `setCamera` one. */
9
9
  const towardIds = new WeakMap();
10
+ /** Each camera's Focus choices and Overview flag (`setFocusChoices`, `setOverview`), kept out of the public class: the assembler reads them with `cameraChoicesOf`. */
11
+ const choices = new WeakMap();
12
+ const offered = (camera) => { let own = choices.get(camera); if (own === undefined)
13
+ choices.set(camera, (own = { overview: true })); return own; };
14
+ /** Every camera button choice the scene made: `focus` and `follow` list objects (undefined: every one), `lookOut` the bodies, `overview` whether Overview shows. */
15
+ export function cameraChoicesOf(camera) {
16
+ return { focus: offered(camera).focus, follow: camera.followChoices, lookOut: camera.lookOutChoices, overview: offered(camera).overview };
17
+ }
10
18
  /** The scene's camera: what it opens on. */
11
19
  export class SceneCamera {
12
20
  #target;
@@ -129,6 +137,26 @@ export class SceneCamera {
129
137
  this.#followIds = Object.freeze([...new Set(named)]);
130
138
  return this;
131
139
  }
140
+ /** The objects offering Focus, as `setFollowChoices`. */
141
+ setFocusChoices(ids) {
142
+ this.#editable();
143
+ if (!Array.isArray(ids))
144
+ throw new SceneError("bad-camera", "camera.setFocusChoices: give a list of bodies or ids");
145
+ const named = ids.map((item) => (typeof item === "string" ? item : item?.id));
146
+ for (const id of named)
147
+ if (typeof id !== "string" || !this.#has(id))
148
+ throw new SceneError("unknown-body", `camera.setFocusChoices("${String(id)}"): no body or trajectory with that id has been added to the scene`);
149
+ offered(this).focus = Object.freeze([...new Set(named)]);
150
+ return this;
151
+ }
152
+ /** Whether Overview shows (default true). */
153
+ setOverview(on) {
154
+ this.#editable();
155
+ if (typeof on !== "boolean")
156
+ throw new SceneError("bad-camera", `camera.setOverview: give true or false, got ${JSON.stringify(on)}`);
157
+ offered(this).overview = on;
158
+ return this;
159
+ }
132
160
  /**
133
161
  * Chooses the bodies whose "Look out from" entry the camera menu offers, by body, id or path already added to the scene (else `unknown-body`); the entry stands inside the body and looks out, and any other camera entry leaves it.
134
162
  * Default: none. An empty list offers none. The opening view is separate: `lookOut` opens looking out whether or not the body is listed.
@@ -202,6 +230,16 @@ export class SceneCamera {
202
230
  get following() { return this.#following; }
203
231
  get view() { return this.#view; }
204
232
  }
233
+ /** Refuses an opening `follow` or `focus` of an object the scene's `setFollowChoices` or `setFocusChoices` leaves out. Called when the scene is built. */
234
+ export function checkOpeningChoices(camera) {
235
+ const { target, following } = camera;
236
+ if (target === undefined)
237
+ return;
238
+ const own = cameraChoicesOf(camera);
239
+ const [call, listed, setter] = following ? ["follow", own.follow, "setFollowChoices"] : ["focus", own.focus, "setFocusChoices"];
240
+ if (listed !== undefined && !listed.includes(target))
241
+ throw new SceneError("bad-camera", `camera.${call}("${target}"): the opening view ${call === "follow" ? "follows" : "focuses"} "${target}", which camera.${setter} does not list`);
242
+ }
205
243
  /**
206
244
  * Refuses an opening look-out toward an id `setCamera` would refuse on the opening view (`checkToward`, the same check and wording): the direction must name an object the opening view shows or a sky figure.
207
245
  * Called when the scene is built, after every figure is in.
@@ -254,14 +292,15 @@ export function viewEntries(timeline, camera, farthestKm, cover) {
254
292
  ...(view.up === undefined || target === undefined ? {} : { viewUp: view.up }),
255
293
  };
256
294
  }
257
- /** The camera menu: Overview, Focus for every body and path, Follow for every one unless `setFollowChoices` named fewer, and "Look out from" for the bodies `setLookOutChoices` listed (the look is toward right ascension 0, declination 0 until the visitor turns). */
258
- export function cameraPresetsOf(objects, followChoices, lookOutChoices = []) {
295
+ /** The camera menu: Overview unless `setOverview(false)`, Focus and Follow for every body and path unless `setFocusChoices` or `setFollowChoices` named fewer, and "Look out from" for the bodies `setLookOutChoices` listed (the look is toward right ascension 0, declination 0 until the visitor turns). */
296
+ export function cameraPresetsOf(objects, choices = {}) {
297
+ const { focus, follow, lookOut = [], overview = true } = choices;
259
298
  return [
260
- { id: "overview", label: "Overview", request: { kind: "overview" } },
299
+ ...(overview ? [{ id: "overview", label: "Overview", request: { kind: "overview" } }] : []),
261
300
  ...objects.flatMap(({ id, label }) => [
262
- { id: `focus-${id}`, label: `Focus ${label}`, request: { kind: "focus", target: id } },
263
- ...(followChoices === undefined || followChoices.includes(id) ? [{ id: `follow-${id}`, label: `Follow ${label}`, request: { kind: "follow", target: id } }] : []),
264
- ...(lookOutChoices.includes(id) ? [{ id: `lookout-${id}`, label: `Look out from ${label}`, request: { kind: "lookOut", body: id, direction: eqjUnitVector(0, 0) } }] : []),
301
+ ...(focus === undefined || focus.includes(id) ? [{ id: `focus-${id}`, label: `Focus ${label}`, request: { kind: "focus", target: id } }] : []),
302
+ ...(follow === undefined || follow.includes(id) ? [{ id: `follow-${id}`, label: `Follow ${label}`, request: { kind: "follow", target: id } }] : []),
303
+ ...(lookOut.includes(id) ? [{ id: `lookout-${id}`, label: `Look out from ${label}`, request: { kind: "lookOut", body: id, direction: eqjUnitVector(0, 0) } }] : []),
265
304
  ]),
266
305
  ];
267
306
  }
@@ -1,6 +1,6 @@
1
1
  import { createProvenance } from "../core/provenance.js";
2
2
  import { SampledTrajectory } from "../core/sampledTrajectory.js";
3
- import { assertUtcUnixMs, createState } from "../core/state.js";
3
+ import { createState } from "../core/state.js";
4
4
  import { createOrbTwoBodyAdapter } from "../core/twoBodyAdapter.js";
5
5
  import { createStateResolver } from "../core/stateResolver.js";
6
6
  import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
@@ -81,7 +81,7 @@ function providerBody(common, input, center, toEqj) {
81
81
  throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): bounds must end after they start`);
82
82
  const trajectory = { body: common.id, bounds, stateAt: (timeUtcMs, center) => {
83
83
  // Every call reaches the host here (`stateOf`, line planning, reach, sampling): a provider only ever sees whole milliseconds (I-177).
84
- assertUtcUnixMs(timeUtcMs);
84
+ toUtcMs(timeUtcMs, `addTrajectory("${common.id}") provider time`);
85
85
  return rotatedState(toEqj, input.provider.stateAt(timeUtcMs, center));
86
86
  } };
87
87
  // Whole milliseconds, because the state resolver refuses a fractional time (the line is placed against another body at these times). The 128 even moments gain more where the path bends or the body moves fast, as seen from `center`.
@@ -4,7 +4,7 @@ import { type StoryPanelSet } from "../core/storyPanels.js";
4
4
  import type { ExperienceConfig } from "../shell/experience.js";
5
5
  import { type AddEventsOptions, type EventInput, type StoryPanelInput, type StoryPanelPlaybackInput } from "./story.js";
6
6
  import type { Tracked } from "./planPaths.js";
7
- import { type SceneEventRead, type ScenePanelRead } from "./sceneReads.js";
7
+ import { type SceneEventRead, type ScenePanelPlaybackRead, type ScenePanelRead } from "./sceneReads.js";
8
8
  /** What a `Scene` has planned for its story layer: events, where their times come from, and story panels. */
9
9
  export declare class StoryPlan {
10
10
  #private;
@@ -13,6 +13,8 @@ export declare class StoryPlan {
13
13
  /** Appends a batch; one that fails its checks adds nothing. */
14
14
  addPanels(panels: readonly StoryPanelInput[]): void;
15
15
  setPanelPlayback(playback: StoryPanelPlaybackInput): void;
16
+ /** How panels play, as the public read states it. */
17
+ playbackRead(): ScenePanelPlaybackRead;
16
18
  /** The events name only objects the scene holds. */
17
19
  checkObjects(ids: ReadonlySet<string>): void;
18
20
  /** The story panels, resolved against this scene's events, the anchors of its paths, its objects and timeline span. */
@@ -26,6 +26,11 @@ export class StoryPlan {
26
26
  setPanelPlayback(playback) {
27
27
  this.#playback = panelPlaybackOf(playback);
28
28
  }
29
+ /** How panels play, as the public read states it. */
30
+ playbackRead() {
31
+ const { pauseSeconds, autoOpen, closeAfterSeconds } = this.#playback;
32
+ return Object.freeze({ pauseSeconds, autoOpen, ...(closeAfterSeconds === undefined ? {} : { closeAfterSeconds }) });
33
+ }
29
34
  /** The events name only objects the scene holds. */
30
35
  checkObjects(ids) {
31
36
  checkEventObjects(this.events, ids);