astraeus 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (288) hide show
  1. package/CHANGELOG.md +192 -0
  2. package/README.md +205 -34
  3. package/package.json +5 -4
  4. package/src/api/AstraeusScene.d.ts +24 -6
  5. package/src/api/AstraeusScene.js +46 -19
  6. package/src/api/AstraeusScene.node.js +46 -19
  7. package/src/api/assembleScene.d.ts +36 -0
  8. package/src/api/assembleScene.js +175 -0
  9. package/src/api/bodySetChecks.d.ts +10 -0
  10. package/src/api/bodySetChecks.js +117 -0
  11. package/src/api/bodySetInput.d.ts +81 -0
  12. package/src/api/bodySetInput.js +1 -0
  13. package/src/api/containingBlock.d.ts +6 -0
  14. package/src/api/containingBlock.js +16 -0
  15. package/src/api/data.d.ts +17 -5
  16. package/src/api/data.js +28 -10
  17. package/src/api/definitionOf.d.ts +16 -0
  18. package/src/api/definitionOf.js +20 -0
  19. package/src/api/errors.d.ts +61 -1
  20. package/src/api/frozenCopy.d.ts +6 -0
  21. package/src/api/frozenCopy.js +26 -0
  22. package/src/api/group.d.ts +8 -2
  23. package/src/api/group.js +24 -5
  24. package/src/api/index.d.ts +19 -7
  25. package/src/api/index.js +2 -2
  26. package/src/api/index.node.js +2 -2
  27. package/src/api/listeners.d.ts +5 -0
  28. package/src/api/listeners.js +25 -0
  29. package/src/api/look.d.ts +47 -0
  30. package/src/api/look.js +1 -0
  31. package/src/api/lookInput.d.ts +3 -0
  32. package/src/api/lookInput.js +41 -0
  33. package/src/api/moonPanelInput.d.ts +60 -0
  34. package/src/api/moonPanelInput.js +1 -0
  35. package/src/api/mount.d.ts +10 -16
  36. package/src/api/mount.js +27 -11
  37. package/src/api/mount.node.js +27 -11
  38. package/src/api/pathProvenance.d.ts +15 -6
  39. package/src/api/pathProvenance.js +23 -11
  40. package/src/api/pickerInput.d.ts +25 -0
  41. package/src/api/pickerInput.js +1 -0
  42. package/src/api/planBodies.d.ts +72 -0
  43. package/src/api/planBodies.js +300 -0
  44. package/src/api/planBodySets.d.ts +68 -0
  45. package/src/api/planBodySets.js +234 -0
  46. package/src/api/planCamera.d.ts +83 -0
  47. package/src/api/planCamera.js +184 -0
  48. package/src/api/planGroups.d.ts +36 -0
  49. package/src/api/planGroups.js +103 -0
  50. package/src/api/planMoonPanel.d.ts +19 -0
  51. package/src/api/planMoonPanel.js +104 -0
  52. package/src/api/planPaths.d.ts +40 -0
  53. package/src/api/planPaths.js +212 -0
  54. package/src/api/planPicker.d.ts +12 -0
  55. package/src/api/planPicker.js +40 -0
  56. package/src/api/planPlaces.d.ts +16 -0
  57. package/src/api/planPlaces.js +99 -0
  58. package/src/api/planStory.d.ts +26 -0
  59. package/src/api/planStory.js +66 -0
  60. package/src/api/planTimeline.d.ts +27 -0
  61. package/src/api/planTimeline.js +68 -0
  62. package/src/api/planViews.d.ts +25 -0
  63. package/src/api/planViews.js +35 -0
  64. package/src/api/prepared.js +4 -1
  65. package/src/api/renamedInputs.d.ts +15 -0
  66. package/src/api/renamedInputs.js +39 -0
  67. package/src/api/scene.d.ts +176 -65
  68. package/src/api/scene.js +257 -725
  69. package/src/api/sceneFreeze.d.ts +4 -0
  70. package/src/api/sceneFreeze.js +10 -0
  71. package/src/api/sceneReads.d.ts +171 -0
  72. package/src/api/sceneReads.js +6 -0
  73. package/src/api/sphereOfInfluence.d.ts +20 -0
  74. package/src/api/sphereOfInfluence.js +48 -0
  75. package/src/api/story.d.ts +49 -19
  76. package/src/api/story.js +54 -22
  77. package/src/api/sunOrbit.js +9 -11
  78. package/src/api/time.d.ts +2 -1
  79. package/src/api/time.js +2 -1
  80. package/src/api/viewerCamera.d.ts +22 -0
  81. package/src/api/viewerCamera.js +84 -0
  82. package/src/api/viewerClock.d.ts +30 -0
  83. package/src/api/viewerClock.js +85 -0
  84. package/src/api/viewerFirstDraw.d.ts +14 -0
  85. package/src/api/viewerFirstDraw.js +26 -0
  86. package/src/api/viewerHandle.d.ts +79 -0
  87. package/src/api/viewerHandle.js +31 -0
  88. package/src/api/viewerLink.d.ts +91 -13
  89. package/src/api/viewerLink.js +111 -64
  90. package/src/api/viewerLooks.d.ts +19 -0
  91. package/src/api/viewerLooks.js +37 -0
  92. package/src/api/viewerPicker.d.ts +22 -0
  93. package/src/api/viewerPicker.js +49 -0
  94. package/src/api/viewerSelection.d.ts +25 -0
  95. package/src/api/viewerSelection.js +31 -0
  96. package/src/api/viewerViews.d.ts +10 -0
  97. package/src/api/viewerViews.js +18 -0
  98. package/src/api/viewerZones.d.ts +20 -0
  99. package/src/api/viewerZones.js +47 -0
  100. package/src/api/views.d.ts +41 -0
  101. package/src/api/views.js +82 -0
  102. package/src/app/App.d.ts +5 -3
  103. package/src/app/App.js +211 -75
  104. package/src/app/App.node.js +211 -75
  105. package/src/app/AstraeusScene.d.ts +19 -2
  106. package/src/app/AstraeusScene.js +4 -4
  107. package/src/app/BodyView.d.ts +4 -1
  108. package/src/app/BodyView.js +2 -2
  109. package/src/app/CameraController.d.ts +12 -0
  110. package/src/app/CameraController.js +3 -1
  111. package/src/app/DeveloperSettings.d.ts +1 -4
  112. package/src/app/DeveloperSettings.js +6 -10
  113. package/src/app/FeatureMarkers.d.ts +4 -3
  114. package/src/app/FeatureMarkers.js +8 -13
  115. package/src/app/FrameRateSection.js +2 -1
  116. package/src/app/OrbitSetView.js +1 -1
  117. package/src/app/SettingControls.d.ts +11 -3
  118. package/src/app/SettingControls.js +10 -2
  119. package/src/app/SkyView.d.ts +3 -10
  120. package/src/app/SkyView.js +6 -28
  121. package/src/app/StoryMarkers.d.ts +4 -1
  122. package/src/app/StoryMarkers.js +3 -2
  123. package/src/app/TrackedBodyView.d.ts +1 -1
  124. package/src/app/TrackedBodyView.js +20 -11
  125. package/src/app/address.d.ts +16 -0
  126. package/src/app/address.js +31 -0
  127. package/src/app/bodyDraw.d.ts +10 -7
  128. package/src/app/bodyDraw.js +12 -32
  129. package/src/app/bodyMetrics.js +2 -2
  130. package/src/app/bodySet.d.ts +4 -20
  131. package/src/app/bodySet.js +5 -16
  132. package/src/app/debugReadout.js +1 -1
  133. package/src/app/displaySwitches.d.ts +4 -0
  134. package/src/app/displaySwitches.js +6 -0
  135. package/src/app/experienceDefinition.d.ts +14 -23
  136. package/src/app/listSwitch.d.ts +8 -14
  137. package/src/app/listSwitch.js +3 -10
  138. package/src/app/liveLook.d.ts +39 -0
  139. package/src/app/liveLook.js +66 -0
  140. package/src/app/look.d.ts +36 -0
  141. package/src/app/look.js +61 -0
  142. package/src/app/mission.d.ts +16 -3
  143. package/src/app/mission.js +16 -1
  144. package/src/app/openClock.d.ts +3 -2
  145. package/src/app/openClock.js +3 -3
  146. package/src/app/sceneCamera.d.ts +2 -0
  147. package/src/app/sceneCamera.js +23 -0
  148. package/src/app/sceneFrame.d.ts +6 -4
  149. package/src/app/sceneFrame.js +55 -14
  150. package/src/app/sceneHooks.js +3 -2
  151. package/src/app/style.css +114 -139
  152. package/src/app/trackedMetrics.d.ts +10 -3
  153. package/src/app/trackedMetrics.js +22 -11
  154. package/src/app/viewHiding.d.ts +13 -0
  155. package/src/app/viewHiding.js +37 -0
  156. package/src/app/viewLink.d.ts +10 -32
  157. package/src/app/viewLink.js +10 -49
  158. package/src/app/viewerPort.d.ts +56 -0
  159. package/src/app/views.d.ts +32 -0
  160. package/src/app/views.js +2 -0
  161. package/src/assets/bodies/galileanMoons.js +1 -2
  162. package/src/assets/bodies/io.js +2 -2
  163. package/src/assets/bodies/listedMoons.d.ts +1 -1
  164. package/src/assets/bodies/listedMoons.js +2 -3
  165. package/src/assets/bodies/planetSystemMaps.js +2 -3
  166. package/src/assets/bodies/venus.js +2 -6
  167. package/src/assets/catalogue.js +1 -2
  168. package/src/assets/licence.d.ts +3 -3
  169. package/src/assets/licence.js +3 -3
  170. package/src/assets/pictures.d.ts +15 -12
  171. package/src/assets/pictures.js +24 -20
  172. package/src/assets/sky.d.ts +6 -5
  173. package/src/assets/sky.js +6 -9
  174. package/src/assets/visual.d.ts +4 -0
  175. package/src/core/bodies/index.d.ts +0 -4
  176. package/src/core/bodies/index.js +1 -6
  177. package/src/core/bodies/jupiterData.d.ts +0 -1
  178. package/src/core/bodies/jupiterData.js +2 -5
  179. package/src/core/bodies/moonSystem.d.ts +1 -1
  180. package/src/core/bodies/moonSystem.js +102 -55
  181. package/src/core/bodies/outerPlanetRingData.js +2 -2
  182. package/src/core/bodies/planetTrajectory.js +1 -1
  183. package/src/core/bodySetFamilies.d.ts +20 -0
  184. package/src/core/bodySetFamilies.js +14 -0
  185. package/src/core/chebyshevEphemeris.js +1 -1
  186. package/src/core/elementsBody.d.ts +8 -4
  187. package/src/core/elementsBody.js +32 -11
  188. package/src/core/elementsGroup.d.ts +27 -0
  189. package/src/core/elementsGroup.js +85 -0
  190. package/src/core/events.d.ts +2 -0
  191. package/src/core/events.js +2 -0
  192. package/src/core/illumination.js +1 -1
  193. package/src/core/listedOrbitGroup.d.ts +2 -0
  194. package/src/core/listedOrbitGroup.js +11 -7
  195. package/src/core/moonListText.d.ts +6 -0
  196. package/src/core/moonListText.js +19 -0
  197. package/src/core/moonTrajectory.js +1 -1
  198. package/src/core/pacing.d.ts +38 -3
  199. package/src/core/pacing.js +55 -4
  200. package/src/core/planetModels.js +2 -2
  201. package/src/core/planetSeries.d.ts +8 -0
  202. package/src/core/planetSeries.js +16 -2
  203. package/src/core/pointGroup.js +1 -1
  204. package/src/core/provenance.d.ts +2 -1
  205. package/src/core/provenance.js +2 -2
  206. package/src/core/referenceCenters.js +5 -5
  207. package/src/core/sampledTrajectory.js +1 -1
  208. package/src/core/scalePolicy.d.ts +1 -0
  209. package/src/core/startView.d.ts +19 -0
  210. package/src/core/startView.js +28 -0
  211. package/src/core/state.d.ts +6 -2
  212. package/src/core/state.js +3 -3
  213. package/src/core/storyPanels.d.ts +63 -0
  214. package/src/core/storyPanels.js +111 -0
  215. package/src/core/sunCentredSources.d.ts +4 -0
  216. package/src/core/sunCentredSources.js +9 -2
  217. package/src/core/timeInput.d.ts +4 -0
  218. package/src/core/timeInput.js +4 -0
  219. package/src/shell/AstraeusShell.d.ts +17 -3
  220. package/src/shell/AstraeusShell.js +60 -13
  221. package/src/shell/AstraeusShell.node.js +60 -13
  222. package/src/shell/Collapsible.d.ts +4 -3
  223. package/src/shell/Collapsible.js +5 -5
  224. package/src/shell/ControlsDrawer.d.ts +1 -1
  225. package/src/shell/ControlsDrawer.js +3 -1
  226. package/src/shell/DisplaySwitches.d.ts +18 -1
  227. package/src/shell/DisplaySwitches.js +20 -6
  228. package/src/shell/InfoPanel.d.ts +3 -1
  229. package/src/shell/InfoPanel.js +5 -4
  230. package/src/shell/MoonFamilyPanel.js +1 -1
  231. package/src/shell/ObjectControls.d.ts +3 -1
  232. package/src/shell/ObjectControls.js +2 -2
  233. package/src/shell/Sources.d.ts +5 -3
  234. package/src/shell/Sources.js +5 -5
  235. package/src/shell/StoryPanelView.d.ts +4 -3
  236. package/src/shell/StoryPanelView.js +8 -6
  237. package/src/shell/SwitchControl.d.ts +5 -11
  238. package/src/shell/SwitchControl.js +2 -20
  239. package/src/shell/TimelineBar.css +84 -66
  240. package/src/shell/TimelineBar.d.ts +5 -2
  241. package/src/shell/TimelineBar.js +37 -11
  242. package/src/shell/TimelineBar.node.js +37 -11
  243. package/src/shell/TopBar.css +22 -22
  244. package/src/shell/TopBar.d.ts +9 -3
  245. package/src/shell/TopBar.js +5 -5
  246. package/src/shell/TopBar.node.js +5 -5
  247. package/src/shell/bootLoader.d.ts +4 -10
  248. package/src/shell/bootLoader.js +6 -52
  249. package/src/shell/embedded.css +18 -18
  250. package/src/shell/experience.d.ts +1 -1
  251. package/src/shell/moonFamilies.d.ts +2 -6
  252. package/src/shell/moonFamilies.js +2 -18
  253. package/src/shell/phone.css +58 -58
  254. package/src/shell/storyPanels.d.ts +2 -53
  255. package/src/shell/storyPanels.js +1 -106
  256. package/src/shell/style.css +153 -134
  257. package/src/shell/timelineModel.d.ts +13 -0
  258. package/src/shell/timelineModel.js +25 -0
  259. package/src/shell/useDrawers.d.ts +3 -2
  260. package/src/shell/useDrawers.js +4 -3
  261. package/src/shell/viewCamera.d.ts +4 -0
  262. package/src/shell/viewCamera.js +13 -0
  263. package/src/shell/viewerKeys.d.ts +8 -0
  264. package/src/shell/viewerKeys.js +16 -0
  265. package/src/synthetic/syntheticDefinition.js +20 -24
  266. package/src/synthetic/syntheticJourneyScene.js +14 -4
  267. package/src/synthetic/syntheticProbeDefinition.js +2 -1
  268. package/src/synthetic/syntheticViewsDefinition.d.ts +3 -0
  269. package/src/synthetic/syntheticViewsDefinition.js +38 -0
  270. package/data/moons/jupiter.json +0 -3333
  271. package/data/moons/neptune.json +0 -555
  272. package/data/moons/pluto.json +0 -205
  273. package/data/moons/saturn.json +0 -8267
  274. package/data/moons/uranus.json +0 -887
  275. package/src/app/addressNavigation.d.ts +0 -17
  276. package/src/app/addressNavigation.js +0 -16
  277. package/src/assets/bodies/jupiterMoonCatalogue.d.ts +0 -3
  278. package/src/assets/bodies/jupiterMoonCatalogue.js +0 -4
  279. package/src/assets/bodies/outerPlanetCatalogues.d.ts +0 -7
  280. package/src/assets/bodies/outerPlanetCatalogues.js +0 -8
  281. package/src/assets/bodies/swiftTuttle.d.ts +0 -12
  282. package/src/assets/bodies/swiftTuttle.js +0 -13
  283. package/src/assets/moonCatalogue.d.ts +0 -49
  284. package/src/assets/moonCatalogue.js +0 -80
  285. package/src/core/bodies/outerPlanetData.d.ts +0 -4
  286. package/src/core/bodies/outerPlanetData.js +0 -13
  287. package/src/core/bodies/swiftTuttle.d.ts +0 -46
  288. package/src/core/bodies/swiftTuttle.js +0 -106
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  A 3D solar system for the browser. Place bodies and recorded paths in a scene, mount it, and get time controls, camera, scale choice and body information, with no React and no 3D code of your own.
4
4
 
5
- > **0.2 preview.** The public API below is the promise: it is small on purpose and may still change between `0.x` versions, with every change listed in [CHANGELOG.md](./CHANGELOG.md). Anything not exported from `astraeus` is internal and may change or disappear in any release.
5
+ > **Before 1.0.** The public API below is the promise: it is small on purpose and may still change between `0.x` versions, with every change listed in [CHANGELOG.md](./CHANGELOG.md). Anything not exported from `astraeus` is internal and may change or disappear in any release.
6
6
 
7
7
  ## Install
8
8
 
@@ -14,7 +14,7 @@ npm install astraeus react react-dom @react-three/fiber three
14
14
 
15
15
  A plain-JavaScript page still needs React: `mount` draws the viewer with React and `@react-three/fiber` inside, so all four peers must be installed even if your own code never touches React.
16
16
 
17
- `mount` loads the viewer's stylesheet itself. If you use the `AstraeusScene` component instead, add `import "astraeus/style.css";` once in your app.
17
+ Both `mount` and the `AstraeusScene` component load the viewer's stylesheet themselves; you add no CSS import. (`astraeus/style.css` is exported for a host that wants the file on its own, for example to load it ahead of time.)
18
18
 
19
19
  You need a bundler. These were each built and run with the packed packages (a scene with Saturn and Titan from `astraeus-data-saturn`): Vite 8, webpack 5 (5.112) and Parcel 2 (2.16, which needs `"@parcel/resolver-default": { "packageExports": true }` in your `package.json` so it reads the package `exports`). Others are untried. The package is plain ES modules that reference their pictures with `new URL(..., import.meta.url)`; drawing needs a bundler and a browser, so do not load it from a bare `<script type="module">`. Node and Vitest can import it for scene definitions and tests (see "Loading in your build and in tests").
20
20
 
@@ -40,7 +40,7 @@ scene.camera.follow("probe", { distance: 110 });
40
40
  mount(document.getElementById("app"), scene);
41
41
  ```
42
42
 
43
- The element needs a size (for example `height: 100%` all the way up). The probe's circle and the Moon's own orbit (tilted to it, because the circle lies in the reference frame's x-y plane) are both drawn. The finished app, grown into a small made-up story with every call below, is in the repository at `examples/hello-scene`.
43
+ The element needs a size (for example `height: 100%` all the way up). The viewer styles nothing outside its element: it sets no style on `html`, `body` or `#app`, so give the element its size (and, for a full-page viewer, your own `html, body { height: 100%; margin: 0 }` and background) yourself; it makes its own element a containing block (`position: relative` if static, `overflow: hidden` if visible). The probe's circle and the Moon's own orbit (tilted to it, because the circle lies in the reference frame's x-y plane) are both drawn. The finished app, grown into a small made-up story with every call below, is in the repository at `examples/hello-scene`; `examples/hello-planets` shows the same calls with a page's own controls.
44
44
 
45
45
  ### A probe across the solar system
46
46
 
@@ -67,7 +67,11 @@ scene.camera.fitOrbit(mars);
67
67
  mount(document.getElementById("app"), scene);
68
68
  ```
69
69
 
70
- Positions are about the scene centre (here the Sun, the first body) unless `center` says otherwise. `lineFixedTo: "sun"` keeps the line still against the Sun while the planets move; `plane` turns the ecliptic vectors into the engine's equatorial frame once; `solarSystemScale` keeps the distances true and draws the named bodies larger; the probe's name shows at any distance in a Sun-centred scene. The repository's dev site opens a fuller version at `?experience=synthetic-probe`, and a made-up 1977-to-170-AU journey past Jupiter and Saturn (moons at their dates, paced playback, provenance by stretch) at `?experience=synthetic-journey`.
70
+ Positions are about the scene centre (here the Sun, the first body) unless `center` says otherwise. `lineFixedTo: "sun"` keeps the line still against the Sun while the planets move (`lineFixedTo: "auto"` picks the Sun or a planet for each stretch from the path's own samples, or give a list such as `[{ start, end, body: "earth" }]`); `plane` turns the ecliptic vectors into the engine's equatorial frame once; `solarSystemScale` keeps the distances true and draws the named bodies larger; the probe's name shows at any distance in a Sun-centred scene. The repository's dev site opens a fuller version at `?experience=synthetic-probe`, and a made-up 1977-to-170-AU journey past Jupiter and Saturn (moons at their dates, paced playback, provenance by stretch) at `?experience=synthetic-journey`.
71
+
72
+ ### Your own controls
73
+
74
+ The viewer's looks, scale and switches are settings, so a page can draw its own controls and drive them through the handle: `handle.look` and `handle.setLook(look)` (star brightness, Sun glow size and brightness and so on; see `scene.setLook` below for the ranges), `handle.scale` and `handle.setScale(id)` (one of `scene.scales`), `handle.switches` and `handle.setSwitch(id, on)`. The repository's `examples/hello-planets` is a plain `mount` app of the Sun to Mars with no data package and three sliders and a scale button of its own under the viewer; it has no Milky Way slider because the Milky Way picture comes from `astraeus-data`, which it does not install.
71
75
 
72
76
  ## The public API
73
77
 
@@ -76,25 +80,50 @@ The full reference, generated from the types and doc comments, is at <https://as
76
80
  | Call | What it does |
77
81
  |---|---|
78
82
  | `new Scene()` | An empty scene. Every method below returns the scene, so calls chain. |
79
- | `scene.addBody(body, { orbit?, enlarge?, showLabel?, labelReach?, description?, color?, knownLimitations? })` | Adds a catalogued body: a ready-made one (`sun`, `mercury`, `venus`, `earth`, `moon`, `mars`, `jupiter`, `saturn`, `uranus`, `neptune`, `pluto`, and the moons `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`, `phobos`, `deimos`) or its id; 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`). The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line: any catalogued moon with a period in its data (every listed moon but those the list gives no period for, and `moon`, `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`) about its planet, one lap of that period (the planet must be in the scene; `phobos`, `deimos` and any moon with no period throw `no-orbit`), or, with `sun` in the scene, one turn round the Sun of any body that circles it (the planets, Earth's year, a body from `addBodyFromElements`), from the opening time: one full turn of the body's own positions where they cover a whole turn, else (Uranus and Neptune, whose turn outlasts the planet series) the two-body ellipse osculating at the opening time, which the info card says; anything else throws `no-orbit`. `camera.fitOrbit` follows the same rule. `enlarge` (a number of at least 1) draws the body that many times larger than life (in a Sun-centred scene the viewer then offers its "Solar system" scale, true distances with the named bodies enlarged, as the second scale in place of Readable); `showLabel: false` starts its label off; `labelReach` (a positive number, in the camera's distance units) shows its label only within that distance of the camera, in place of the scene's shared rule. A scene whose first body is the Sun sets no label reach, so labels stay when zoomed out, and it can hold a path (`addTrajectory`, drawn with `lineFixedTo: "sun"`). `color` (a hex colour such as `"#9fd8ff"`) sets the colour on its info card and label; `knownLimitations` (a list of non-empty texts) replaces the catalogue's limits shown with its provenance; a bad value throws `bad-body`. Jupiter, Saturn, Uranus and Neptune are drawn with their rings (bands at the NASA NSSDC ring fact sheet radii) whenever you add them; Mercury, Venus, Earth, Mars and Pluto have none. |
80
- | `scene.addTrajectory({ id, label?, color?, center?, plane?, lineFixedTo?, labelReach?, samples, provenance?, provenanceSpans?, description?, knownLimitations?, anchors?, readouts? })` | A recorded path. Each sample is `{ time, positionKm, velocityKmS? }` measured from `center` (default: the scene's centre, its first body, so a Sun-first scene reads them from the Sun and an Earth-first one from Earth; Earth if no body is added) in equatorial J2000 (EQJ) axes; `plane: "ecliptic-j2000"` instead takes ecliptic J2000 vectors as JPL Horizons publishes them and rotates them to EQJ once on the way in (positions and velocities, from samples or a provider; a provider's `orientation` quaternion passes through unrotated, a known limit; any other `plane` throws `bad-trajectory`); `lineFixedTo` names the body the line is drawn against (default the scene centre): each sample is placed from that body at the sample's own time, then the line is carried to that body's place from the scene centre at the clock time, so `"sun"` fixes a probe's line to the Sun in any scene, Sun-centred ones included, and a body the scene does not hold throws `bad-trajectory`; `labelReach` (a positive number, in the camera's distance units) limits how far from the camera its name shows, in place of the scene's shared rule; a bad value throws `bad-trajectory`; `time` is ISO text, a `Date` or Unix milliseconds. Instead of `samples` you may give `provider` (an object with `stateAt(timeUtcMs)`) and `bounds: { start, end }`. `description` and `knownLimitations` (a list of sentences) go on its info card with `provenance`. `anchors: [{ id, time }]` draw labelled dots where the source published a point (the time must fall within the path). `readouts` are bars on the card, in order: `{ kind: "range", marker? }` (distance from the centre; `marker` names a body to mark), `{ kind: "speed" }`, `{ kind: "distance", to }` and `{ kind: "altitude", above }`; a named body must be in the scene. `provenanceSpans` (a list of `{ start, end, provenance }`, sorted, not overlapping, inside the path) gives each stretch its own provenance, shown with the path as time moves (as an activity's `provenance`); where no span covers the time, `provenance` (or the illustrative default) shows; a fault throws `bad-trajectory` naming the index. |
81
- | `scene.addBodyFromElements(record, options?)` | Your own body that circles the Sun, from published orbit elements: `record` is `{ id, label, elements: { semiMajorAxisAu, eccentricity, inclinationDeg, ascendingNodeDeg, argumentOfPerihelionDeg, meanAnomalyDeg or perihelionJdTdb }, epoch: { jd, timeScale, ttMinusUtcSeconds? }, frame: "ecliptic-j2000", source: { name, url, solution, accessed }, radius?, accuracy: { classification, statement, validFromUtc, validToUtc, limitations }, marker?: { color, sizePx } }`. Drawn as a marker on unperturbed two-body motion about the Sun; the source, accuracy and limits show on its info card, with a live "Distance from Sun" row. `options` are `addBody`'s (`{ orbit: true }` draws its whole orbit from periapsis, smooth even for a sharp comet orbit). A bad record throws `bad-element` naming the field; a repeated id throws `duplicate-id`. |
82
- | `scene.addGroup({ id, orbits, label?, center?, plane?, color?, dotSizePx?, referenceTime?, seed?, clump?, refillAfterMs?, refillSliceMs?, provenance?, description?, knownLimitations? })` | A list of orbits drawn as one group of dots: `orbits` is `[{ id, semiMajorAxisKm, eccentricity, inclinationDeg, raanDeg, argumentOfPeriapsisDeg, time? }]` (bound orbits, ids distinct), measured about `center` (default the scene's centre; it must be in the scene) in `plane` (`"ecliptic-j2000"` default, or `"EQJ"`). One colour (`color`, a hex colour), dot size (`dotSizePx`), menu item, info card, provenance and known limits. Where each dot sits along its orbit is a drawing choice, marked illustrative: an even spread shuffled by `seed`, fixed at `referenceTime` (default the opening time), then two-body motion. `clump: { near, fraction, widthDeg }` draws a share of the dots near a body's place along its orbit (a model; the body must be in the scene and not the centre; it may be one added with `addBodyFromElements` before the group). `refillAfterMs` is how often the dots are placed again; `refillSliceMs` (0 or more) is how much of a frame may go on computing the next fill ahead of time. The group's card shows "illustrative" as its source type, with the elements' own type in the accuracy sentence. The id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be a panel's `object`. A mistake throws `bad-group`. |
83
+ | `scene.addBody(body, { orbit?, enlarge?, showLabel?, labelReachEarthRadii?, description?, color?, knownLimitations?, readouts?, listed?, facts?, sources?, labelPriority? })` | Adds a catalogued body: a ready-made one (`sun`, `mercury`, `venus`, `earth`, `moon`, `mars`, `jupiter`, `saturn`, `uranus`, `neptune`, `pluto`, and the moons `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`, `phobos`, `deimos`) or its id; every moon in the moon lists is also taken by its id (`addBody("miranda")` with `astraeus-data-uranus` passed to `mount`) as a grey sphere at its mean radius, and `listedMoons(planet?)` names them with the data package each needs (`requires`). Moons with pictures: Io, Europa, Ganymede, Callisto, Mimas, Enceladus, Tethys, Dione, Rhea, Titan, Iapetus, Triton and Charon. Every other listed moon, among them Uranus's Miranda, Ariel, Umbriel, Titania and Oberon, draws flat-coloured with this package loaded. The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line: any catalogued moon with a period in its data (every listed moon but those the list gives no period for, and `moon`, `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`) about its planet, one lap of that period (the planet must be in the scene; `phobos`, `deimos` and any moon with no period throw `no-orbit`), or, with `sun` in the scene, one turn round the Sun of any body that circles it (the planets, Earth's year, a body from `addBodyFromElements`), from the opening time: one full turn of the body's own positions where they cover a whole turn, else (Uranus and Neptune, whose turn outlasts the planet series) the two-body ellipse osculating at the opening time, which the info card says; anything else throws `no-orbit`. `camera.fitOrbit` follows the same rule. `enlarge` (a number of at least 1) draws the body that many times larger than life (in a Sun-centred scene the viewer then offers its "Solar system" scale, true distances with the named bodies enlarged, as the second scale in place of Readable); `showLabel: false` starts its label off; `labelReachEarthRadii` (a positive number, in Earth radii, the camera's distance units) shows its label only within that distance of the camera, in place of the scene's shared rule. A scene whose first body is the Sun sets no label reach, so labels stay when zoomed out, and it can hold a path (`addTrajectory`, drawn with `lineFixedTo: "sun"`). `color` (a hex colour such as `"#9fd8ff"`) sets the colour on its info card and label; `knownLimitations` (a list of non-empty texts) replaces the catalogue's limits shown with its provenance; a bad value throws `bad-body`. `readouts` takes the list `addTrajectory` takes (`range`, `speed`, `distance`, `altitude`), measured from the scene's centre body, and draws it on the body's info card in place of the catalogue's own distance rows; a bad readout throws `bad-readout`, and a named body the scene does not hold throws `bad-readout` when the scene is built. `listed: false` (default true) leaves the body out of the object menu; it is still drawn and selectable, and the menu shows it while it is selected. `facts` (default none) is a list of `{ label, value }` rows, both non-empty, shown on the info card in order. `sources` (default none) is a list of non-empty texts added to the card's provenance after the body's own, and `scene.provenanceOf` includes them. `labelPriority` (a finite number; default `100 - index`, so bodies added earlier win) decides which label shows when labels overlap, the higher number winning. A bad value of any of these throws `bad-body`. `orbit` also takes `{ lapDays, fades? }` for a moon: it draws the line about its parent over one lap of `lapDays` (a positive number), whether or not the moon's data give a period (`phobos` and `deimos`, which have none, take it); `fades: true` fades the line's far end and `false` closes the loop, and when absent the moon's own rule applies (the Moon's line fades, others close); a bad lap throws `bad-body`, and a body that circles the Sun throws `no-orbit`. The scene's centre needs no setting: it is the first body added. Jupiter, Saturn, Uranus and Neptune are drawn with their rings (bands at the NASA NSSDC ring fact sheet radii) whenever you add them; Mercury, Venus, Earth, Mars and Pluto have none. |
84
+ | `scene.addTrajectory({ id, label?, color?, center?, plane?, lineFixedTo?, labelReachEarthRadii?, samples, provenance?, provenanceSpans?, description?, knownLimitations?, anchors?, readouts? })` | A recorded path. Each sample is `{ time, positionKm, velocityKmS? }` measured from `center` (default: the scene's centre, its first body, so a Sun-first scene reads them from the Sun and an Earth-first one from Earth; Earth if no body is added) in equatorial J2000 (EQJ) axes; `plane: "ecliptic-j2000"` instead takes ecliptic J2000 vectors as JPL Horizons publishes them and rotates them to EQJ once on the way in (positions and velocities, from samples or a provider; a provider's `orientation` quaternion passes through unrotated, a known limit; any other `plane` throws `bad-trajectory`); `lineFixedTo` names the body the line is drawn against (default the scene centre): each sample is placed from that body at the sample's own time, then the line is carried to that body's place from the scene centre at the clock time, so `"sun"` fixes a probe's line to the Sun in any scene, Sun-centred ones included, and a body the scene does not hold throws `bad-trajectory`; a list of `{ start, end, body }` (sorted, not overlapping, inside the path, times as in `provenanceSpans`) draws each stretch against its own body, so a flyby (Sun-fixed cruise, planet-fixed encounter, Sun-fixed cruise) is one path with one menu entry and card, time outside every stretch is drawn against the scene centre, and a fault throws `bad-trajectory` naming the index; `lineFixedTo: "auto"` builds that list from the path's own samples, once, when the planet series are in: each sample is fixed to the innermost body in the scene whose sphere of influence (`a (m / M)^(2/5)`, `a` its distance from its parent, GMs from the catalogue; the Sun holds everything) holds the probe, else the scene centre, consecutive samples on one body merging; a body with no catalogue GM (a comet from `addBodyFromElements`, every moon added only by id) is skipped, and `"auto"` is not usable as a body id; `labelReachEarthRadii` (a positive number, in Earth radii, the camera's distance units) limits how far from the camera its name shows, in place of the scene's shared rule; a bad value throws `bad-trajectory`; `time` is ISO text, a `Date` or Unix milliseconds. Instead of `samples` you may give `provider` (an object with `stateAt(timeUtcMs)`) and `bounds: { start, end }`. `description` and `knownLimitations` (a list of sentences) go on its info card with `provenance`. `anchors: [{ id, time }]` draw labelled dots where the source published a point (the time must fall within the path). `readouts` are bars on the card, in order: `{ kind: "range", marker? }` (distance from the centre; `marker` names a body to mark), `{ kind: "speed" }`, `{ kind: "distance", to }` and `{ kind: "altitude", above }`; a named body must be in the scene. `provenanceSpans` (a list of `{ start, end, provenance }`, sorted, not overlapping, inside the path) gives each stretch its own provenance, shown with the path as time moves (as an activity's `provenance`); where no span covers the time, `provenance` (or the illustrative default) shows; a fault throws `bad-trajectory` naming the index. |
85
+ | `scene.addBodyFromElements(record, options?)` | Your own body that circles the Sun, from published orbit elements: `record` is `{ id, label, elements: { semiMajorAxisAu, eccentricity, inclinationDeg, ascendingNodeDeg, argumentOfPerihelionDeg, meanAnomalyDeg or perihelionJdTdb }, epoch: { jd, timeScale, ttMinusUtcSeconds? }, plane: "ecliptic-j2000", source: { name, url, solution, accessed }, radius?, accuracy: { classification, statement, valid: { start, end }, limitations }, marker?: { color, sizePx } }`; `accuracy.valid` is `{ start, end }`, each ISO text such as `2030-01-01T00:00:00Z` (a record is usually JSON), a `Date` or milliseconds. Drawn as a marker on unperturbed two-body motion about the Sun; the source, accuracy and limits show on its info card, with a live "Distance from Sun" row. `options` are `addBody`'s (`{ orbit: true }` draws its whole orbit from periapsis, smooth even for a sharp comet orbit). A bad record throws `bad-element` naming the field; a repeated id throws `duplicate-id`. |
86
+ | `scene.addBodySet({ id, families, members, provenance, center?, bodies?, centerGmKm3S2?, balancePoint?, orbitHistoryMs? })` | Many small bodies about one centre as one batch of dots, each selectable with an info card, with orbit lines coloured by family. `families` is one to sixteen of `{ id, label, color?, brightness? }` (colour a CSS hex colour, default the palette in family order; `brightness` the orbit-line multiplier, default 1). A member is `{ id, family, label?, radiusKm?, elements?, description?, facts?, provenance?, knownLimitations?, listed? }`: with no `elements` it is a listed moon of `center` (`listedMoons(planet)`; its positions come through `data`, as for `addBody`, and its label and radius default to the list's); with `elements` (`semiMajorAxisKm`, `eccentricity`, `inclinationDeg`, `raanDeg`, `argumentOfPeriapsisDeg`, `trueAnomalyDeg`, `time?`, `plane?`) it is a made-up member on two-body motion and needs `label` and `radiusKm`. A set is one kind or the other. `center` is a body in the scene (default the scene's first); `centerGmKm3S2` sizes each orbit line to one lap (default the centre's moon system, else its catalogue record; neither is `bad-body-set`). `bodies` are bodies added with `addBody` that belong to a family: their orbit lines take its colour, and one with no `orbit` of its own, if it is a listed moon of `center`, gets its line in this batch. `balancePoint` (`{ body, gmKm3S2 }`, a member or such a body) draws the lines about the balance point of the centre and that body (default the centre's moon system's own when its body is drawn here). `orbitHistoryMs` loads positions that long before the window so a line can reach back (default 0). Members are not in the Object menu unless `listed: true`. `stateOf` and `provenanceOf` accept member ids; story panels may name them; a view cannot name a set or a member. A repeated id throws `duplicate-id`; a mistake throws `bad-body-set`. |
87
+ | `scene.setMoonPanel({ label, families, featuredFamily?, listSource?, listDate? })` | The sliding panel of a planet's moons by family. `label` is the name in the heading ("<label>'s moons"). `families` is `{ id, label, description, moons }` each, where a moon is `{ id, named? }`: a body (`addBody`) or a body-set member (`addBodySet`) of the scene, checked when the scene is built; its label comes from there, and `named: false` folds a provisional designation under "+N unnamed". A moon that is a body gets the picture the viewer's `data` brings for it (the packages' `pictures`); a dot gets none. `featuredFamily` is the family id listed first with pictures. `listSource` and `listDate` (a moment, kept as its day) say where and when the list was taken. Replaces any earlier panel. A malformed panel, or a moon the scene does not hold, throws `bad-moon-panel`. |
88
+ | `scene.setPicker({ id, label, options, value })` | A choice in the viewer's top bar and phone drawer: one button per option `{ value, label }` (values unique), the option with `value` pressed when the viewer opens, `label` the accessible name of the group and `id` carried on the buttons as `data-switch-param`. Fewer than two options draw nothing. Replaces any earlier picker. A press only tells the host (`handle.onPick`, the `onPick` prop): the viewer never navigates, reads or writes the page address, or keeps a time, and the pressed button does not move until the host calls `handle.setPick` or mounts a new scene. A malformed picker, or a `value` that is not an option, throws `bad-picker`. |
89
+ | `scene.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. |
90
+ | `scene.addGroup({ id, orbits, plane, label?, center?, color?, dotSizePx?, referenceTime?, seed?, clump?, refillAfterMs?, refillSliceMs?, provenance?, description?, knownLimitations? })` | A list of orbits drawn as one group of dots: `orbits` is `[{ id, semiMajorAxisKm, eccentricity, inclinationDeg, raanDeg, argumentOfPeriapsisDeg, time? }]` (bound orbits, ids distinct), measured about `center` (default the scene's centre; it must be in the scene) in `plane`, which you must give (`"ecliptic-j2000"` or `"EQJ"`; a group without one throws `bad-group`). One colour (`color`, a hex colour), dot size (`dotSizePx`), menu item, info card, provenance and known limits. Where each dot sits along its orbit is a drawing choice, marked illustrative: an even spread shuffled by `seed`, fixed at `referenceTime` (default the opening time), then two-body motion. `clump: { near, fraction, widthDeg }` draws a share of the dots near a body's place along its orbit (a model; the body must be in the scene and not the centre; it may be one added with `addBodyFromElements` before the group). `refillAfterMs` is how often the dots are placed again; `refillSliceMs` (0 or more) is how much of a frame may go on computing the next fill ahead of time. The group's card shows "illustrative" as its source type, with the elements' own type in the accuracy sentence. The id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be a panel's `object`. A mistake throws `bad-group`. |
83
91
  | `scene.setTime(time)` | The moment the scene opens at. |
84
92
  | `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`. |
85
- | `scene.addEvents(events, { provenance? })` | Timed events on the timeline: `[{ id, label, time, type?, provenance?, object? }]`, ids unique. `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.lookAt` 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. |
86
- | `scene.addStoryPanels({ pauseSeconds?, autoOpen?, panels })` | Story panels that open as playback reaches them: `{ id, at: { utc } \| { event } \| { anchor }, title, body, details?, badge, sources, object? }`. `badge` is `observed`, `modelled` or `illustrative`; `sources` is never empty. A mistake throws `bad-panels` naming the panel and field. |
93
+ | `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. |
94
+ | `scene.addStoryPanels(list)` | Appends story panels that open as playback reaches them: `[{ id, at: { time } \| { event } \| { anchor }, title, body, details?, provenance, object? }]`. `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`. |
95
+ | `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`. |
87
96
  | `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. `{ 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. |
88
- | `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 or a bad curve, peak or source throws `bad-activity`; a rate readout with no activity is `bad-readout`. |
89
- | `scene.camera.setReach(distance)` | How far the viewer can zoom out, in Earth radii; labels reach as far, a path's own name (at its marker, switched by `labels`) included. A bad value throws `bad-camera`. Without `setReach` or `fitOrbit`, a Sun-centred scene with a path about the Sun widens its farthest zoom-out to fit that path whole (twice its farthest Sun distance, for the live canvas shape), so a path out to 170 AU can be seen entire. The object the scene opens on (`camera.follow` or `camera.lookAt`) is selected, and a selected object's label wins every label collision: it is never the one hidden because it overlaps another. Other labels keep their priority order. `camera.follow` and `camera.lookAt` take `up: "ecliptic"` (default `"equatorial"`) to orbit about the ecliptic's pole; any other value throws `bad-camera`. `setTimeline` takes `loop: true` so playback wraps from the end to the start. |
90
- | `scene.camera.fitOrbit(body)` | Sets the farthest zoom-out so the whole orbit of a body that circles the Sun (a planet, the built-in comet, or one from `addBodyFromElements`, already added) fits the canvas from any view direction: 1.1 times its farthest Sun distance over the sine of the narrower half field of view. The fit follows the live canvas shape (a phone turning, a window resizing) and the far plane is 2.5 times the reach. The opening view is not moved, except that it is clamped to the limit like any other. Labels are not limited in a fitted scene. It and `setReach` set the same limit; the later call wins. A body that does not circle the Sun throws `bad-camera`; one not in the scene, `unknown-body`. `scene.camera.fitOrbit("c-2025-a1")` |
91
- | `scene.setSwitches({ orbitLines?, labels?, milkyWay? })` | Where each display switch shows: `{ place: "top-bar" \| "panel" \| "developer", on? }`. A top-bar switch is a button in the bar, a panel switch is a row in one switch panel opened from the bar, and a developer switch is only in the Developer drawer (where every switch stays). `orbitLines` is the orbit ring, trailing arc and moon orbits; `labels` is body and anchor labels; `milkyWay` is the sky picture. `on` is the starting state (default on). Nothing placed: the bar is as before. A bad name, place or `on` throws `bad-switch`. |
92
- | `scene.stateOf(id, time)` | The state of any body in the scene at a moment, for figures a story quotes. `positionKm` is always there; `velocityKmS` (km/s) only where the body's source gives one, so check it before use: a path from `addTrajectory` whose samples or provider carry velocities, and a moon from fitted data (Io); planets, Earth, the Sun, built-in Swift-Tuttle and elements bodies give position only. Bodies: a path from `addTrajectory` (about its centre, in EQJ axes whatever `plane` it was given in), or a ready-made body, moon or elements body (about its parent). Ready-made and elements bodies answer at any date; only a moment outside an `addTrajectory` path throws `bad-time`. A planet's data lives in the planet series, so it answers only once they are loaded (at `mount`), else `missing-data`. `const au = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm) / 149597870.7;` |
93
- | `scene.provenanceOf(id)` | Where a body's position comes from, as its info card shows it. Where a comparison with an independent ephemeris exists it carries `accuracyClass` and `maxErrorFraction`. For built-in Swift-Tuttle that fraction is measured (0.00857). For a body from `addBodyFromElements` it is the limit of its class (0.01 `approximate`, 0.05 `indicative`): an upper bound, not a measured figure. Other bodies carry neither field. |
97
+ | `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`. |
98
+ | `scene.camera.setReach(distance, { farEarthRadii? })` | How far the viewer can zoom out, in Earth radii; the far plane (where drawing stops) is 2.5 times it unless `farEarthRadii` (a finite number of at least `distance`, in Earth radii) sets it; labels reach as far, a path's own name (at its marker, switched by `labels`) included. A bad value throws `bad-camera`. Without `setReach` or `fitOrbit`, a Sun-centred scene with a path about the Sun widens its farthest zoom-out to fit that path whole (twice its farthest Sun distance, for the live canvas shape), so a path out to 170 AU can be seen entire. The object the scene opens on (`camera.follow` or `camera.focus`) is selected, and a selected object's label wins every label collision: it is never the one hidden because it overlaps another. Other labels keep their priority order. `camera.follow` and `camera.focus` take `up: "ecliptic"` (default `"equatorial"`) to orbit about the ecliptic's pole; any other value throws `bad-camera`. `setTimeline` takes `loop: true` so playback wraps from the end to the start. |
99
+ | `scene.camera.setStartView(pose)` | Opens at a pose `{ focus, azimuthDeg, elevationDeg, distance }` (what `handle.camera` reads; distance in Earth radii) with no camera button pressed, so Focus does not show as pressed and choosing another body moves the camera as it would without a start. `focus` must be a body or path already added (`unknown-body`); a bad angle or distance throws `bad-camera`. The last of `follow`, `focus` and `setStartView` wins. Default: none. |
100
+ | `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. |
101
+ | `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`. |
102
+ | `scene.camera.fitOrbit(body)` | Sets the farthest zoom-out so the whole orbit of a body that circles the Sun (a planet, or a comet or asteroid from `addBodyFromElements`, already added) fits the canvas from any view direction: 1.1 times its farthest Sun distance over the sine of the narrower half field of view. The fit follows the live canvas shape (a phone turning, a window resizing) and the far plane is 2.5 times the reach. The opening view is not moved, except that it is clamped to the limit like any other. Labels are not limited in a fitted scene. It and `setReach` set the same limit; the later call wins. A body that does not circle the Sun throws `bad-camera`; one not in the scene, `unknown-body`. `scene.camera.fitOrbit("c-2025-a1")` |
103
+ | `scene.setLook({ starBrightness?, milkyWay?, milkyWayBrightness?, skyVisible?, sunGlow?: { sizePx?, brightness?, scale? }, markerSwapRadiusPx?, featureMinBodyPx?, loadFadeSeconds?, desktopPictures? })` | The looks, presentation settings that change how the scene is drawn and never where anything is; each is optional and keeps its default when not named (the call replaces the whole look). Ranges and defaults: star and Milky Way brightness 0 to 2 (1); `milkyWay` and `skyVisible` true or false (Milky Way off, sky shown); `sunGlow.sizePx` 0 to 400 (the Sun record's 72), `sunGlow.brightness` 0 to 2 (1), `sunGlow.scale` 1 to 6 (2.5); `markerSwapRadiusPx` 0 to 100 (3), the screen radius under which a sphere is drawn as a dot; `featureMinBodyPx` 0 to 2000 (60); `loadFadeSeconds` 0 to 3 (0.6); `desktopPictures` true or false (false) lets a body with a larger desktop picture use it on a wide screen, read when the viewer is built, so a later `setLook` neither swaps pictures nor changes what `look` reads. A page address parameter (table below) overrides the look it names when `address` is on. An unknown look or a value out of range throws `bad-look`. |
104
+ | `scene.setSwitches({ orbitLines?, labels?, milkyWay? })` | Where each display switch shows: `{ place: "top-bar" \| "panel" \| "developer", on? }`. A top-bar switch is a button in the bar, a panel switch is a row in one switch panel opened from the bar, and a developer switch is only in the Developer drawer (where every switch stays), so it shows only when the viewer was built with `developerTools` on; with it off there is no drawer and the switch is simply not shown. `orbitLines` is the orbit ring, trailing arc and moon orbits; `labels` is body and anchor labels; `milkyWay` is the sky picture. `on` is the starting state (default on). Nothing placed: the bar is as before. A bad name, place or `on` throws `bad-switch`. |
105
+ | `scene.setViews(views, { place, start? })` | Names views of one scene: each `{ id, label, objects?, events?, panels?, camera? }` lists the `addBody`, `addGroup` and `addTrajectory` ids (`objects`), `addEvents` ids and `addStoryPanels` ids it shows. Anything no view names shows in every view; anything named shows only in the views that name it. `place` is `"top-bar"` or `"panel"`; `start` is the opening view (default the first). `camera` is `"stay"` (default), `"start"` or `{ follow: id }` / `{ focus: id }` (the object must be in the view). The rule applies only when switching to the view takes away the object the camera follows or focuses on: `"stay"` holds the camera where it is (its target fixed in the scene, so it does not move on with the hidden object), stops following and closes that object's card; `"start"` takes the scene's opening framing; `{ follow: id }` / `{ focus: id }` follows or focuses that object. A followed object still in the new view leaves the camera alone. Read and set the view from `mount` or `AstraeusScene` ("Views from the host page"). Presentation only: State is unchanged. An empty list, a repeated id, a bad place, camera or `start` throws `bad-view` at the call; an unknown id or a camera target the view hides throws `bad-view` when the scene is built. |
106
+ | `scene.stateOf(id, time)` | The state of any body in the scene at a moment, for figures a story quotes. `positionKm` is always there; `velocityKmS` (km/s) only where the body's source gives one, so check it before use: a path from `addTrajectory` whose samples or provider carry velocities, and a moon from fitted data (Io); planets, Earth, the Sun and elements bodies give position only. Bodies: a path from `addTrajectory` (about its centre, in EQJ axes whatever `plane` it was given in), or a ready-made body, moon or elements body (about its parent). Ready-made and elements bodies answer at any date; only a moment outside an `addTrajectory` path throws `bad-time`. A planet's or fitted moon's data loads with `await scene.load({ data })` (or at `mount`, once `ready` resolves); before that it throws `missing-data`. `const au = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm) / 149597870.7;` |
107
+ | `scene.load({ data? })` | Loads what `stateOf` and `provenanceOf` need, without a viewer: the planet series and, for each moon the scene holds, the chunks its data package provides for the scene's window. Pass the same `data` as `mount`. Rejects with `missing-data` (a body needs a package not passed) or `out-of-span`; harmless to call twice, allowed on a mounted scene, and a later `mount` re-uses what it loaded. Works in plain Node. `await scene.load({ data: [jupiterData] });` |
108
+ | `scene.check({ data? })` | Runs the checks `mount` runs before it draws and throws the same `SceneError` for a build fault, without loading or freezing anything. `scene.check({ data: [jupiterData] });` |
109
+ | `scene.provenanceOf(id)` | Where a body's position comes from, as its info card shows it. Where a comparison with an independent ephemeris exists it carries `accuracyClass` and `maxErrorFraction`. For a body from `addBodyFromElements` it is the limit of its class (0.01 `approximate`, 0.05 `indicative`): an upper bound, not a measured figure. Other bodies carry neither field. |
110
+ | `scene.bodies` | What the scene holds, as plain frozen lists you can check in a test without a viewer (a fresh list on every read; they answer on a scene a viewer has taken). `bodies`: `{ id, label, parent?, orbit, enlarge, description?, knownLimitations, listed, facts?, texture? }` in the order added (the first is the scene's centre; `orbit` says its orbit line is on, `enlarge` is 1 unless enlarged; `knownLimitations` are the card's: given, else the catalogue's; `listed` and `facts` are what `addBody` set, `listed` true by default; `texture` is the picture and licence the engine ships for the body, as a credits page lists it, absent for a body drawn from a data package's picture or a flat colour). |
111
+ | `scene.paths` | `{ id, label, center, provenance, description?, knownLimitations }` per `addTrajectory`, in the order added. |
112
+ | `scene.bodySets` | `{ id, center, count, families }` per `addBodySet`, in the order added; a fresh frozen list on every read. |
113
+ | `scene.moonPanel` | `{ count, summary }` of the moon panel, or `undefined` before `setMoonPanel`; `summary` reads like "115 moons in the JPL Horizons list of 18 October 2026". |
114
+ | `scene.picker` | The picker as set (`{ id, label, options, value }`, frozen), or `undefined` before `setPicker`. |
115
+ | `scene.places` | `{ body, count }` per `addPlaces`, in the order added; a fresh frozen list on every read. |
116
+ | `scene.groups` | `{ id, label, count, center, plane, provenance, description, knownLimitations }` per `addGroup`: `provenance`, `description` and `knownLimitations` are what the group's card shows (always illustrative, with the engine's placement and motion limits). |
117
+ | `scene.activities` | `{ id, label, unit, windowStartUtcMs, windowEndUtcMs, peak: { label, value, timeUtcMs? }, samples: [{ timeUtcMs, value }], provenance?: [{ stretchStartUtcMs, stretchEndUtcMs, provenance }], type? }` per `addActivity`, in the order added; a fresh frozen copy. `peak.value` is the highest sample when no peak moment was given. |
118
+ | `scene.events` | `{ id, label, timeUtcMs, type?, object?, withinSeconds?, provenance? }` per `addEvents`, sorted by time; `provenance` is the event's own, else the batch's. |
119
+ | `scene.panels` | `{ id, timeUtcMs, title, body, details, provenance, object? }` per `addStoryPanels`, sorted by time, the times resolved as `mount` resolves them (a bad panel throws `bad-panels`). |
120
+ | `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`. |
121
+ | `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. |
122
+ | `scene.timeline` | `{ windowStartUtcMs, windowEndUtcMs, openUtcMs, rates, rate, loop }`: the span and opening moment in UTC milliseconds, the speeds offered, the opening speed and whether playback wraps. With nothing setting a span or moment and no path or activity, the span is a month about the moment of the read. Planet orbit lines and the far plane answer from `scene.bodies[].orbit` and `scene.camera.farEarthRadii` (when none was given, the far plane is 2.5 times `scene.camera.reachEarthRadii`). |
94
123
  | `scene.camera.follow(id, { azimuthDeg?, elevationDeg?, distance? })` | Opens framed on a body or trajectory already added, and already following it. `distance` is in Earth radii. |
95
- | `scene.camera.lookAt(id, { azimuthDeg?, elevationDeg?, distance? })` | The same opening view without following. The last of `follow` and `lookAt` wins. The viewer's camera menu gets a Focus and a Follow entry for every body and path. |
96
- | `mount(element, scene, { data?, onChange? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), time, rate, setTime(t), setRate(r), onChange(fn) }`. `data` is a list of data packages (below); the time and speed members are described under "Reading and setting the time". |
97
- | `<AstraeusScene scene data? onReady? onError? time? rate? onChange? />` | The same viewer as a React component (below). |
124
+ | `scene.camera.focus(id, { azimuthDeg?, elevationDeg?, distance? })` | The same opening view without following. The last of `follow` and `focus` wins. The viewer's camera menu gets a Focus and a Follow entry for every body and path. |
125
+ | `mount(element, scene, { data?, onChange?, address?, developerTools? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), timeUtcMs, rate, playing, view, camera, eventZones, selected, look, scale, switches, pick, setTime(t), setRate(r), setPlaying(p), setView(id), setCamera(target), setLook(look), setScale(id), setSwitch(id), setPick(value), onChange(fn), onEventZone(fn), onSelect(fn), onCameraChange(fn), onFirstDraw(fn), onPick(fn) }`. `data` is a list of data packages (below); `address` is off by default (see "Page address"); `developerTools` is off by default (the cog and the Developer drawer are not drawn, and the drawer's code is never fetched; the demo site turns it on); the time and speed members are described under "Reading and setting the time". |
126
+ | `<AstraeusScene scene data? ref? onReady? onError? time? rate? view? camera? onChange? onEventZone? onPick? onFirstDraw? address? developerTools? className? style? />` | The same viewer as a React component (below). |
98
127
  | `SceneError` | Thrown for bad input. `error.code` is one of the documented `SceneErrorCode` values (for example `unknown-body`, `bad-time`, `missing-data`, `no-orbit`) and the message says what to do. |
99
128
 
100
129
  Checking accuracy and records without a scene: the class limits are root exports (`APPROXIMATE_LIMIT_FRACTION`, `INDICATIVE_LIMIT_FRACTION`), `classifyPositionError(maxFraction)` returns `"approximate"`, `"indicative"` or `null` (neither) for a measured largest error fraction, and `parseElementsBodyRecord(record)` validates an elements record (the same check `addBodyFromElements` makes, throwing `bad-element` naming the field):
@@ -123,42 +152,110 @@ export const App = () => (
123
152
  );
124
153
  ```
125
154
 
126
- Props: `scene`, `data` (as for `mount`), `onReady`, `onError` (a bad scene or failed data load), `className` and `style` for the wrapper. Build the `Scene` once (outside the component or in `useMemo`): a new `Scene` object rebuilds the viewer. It needs React 19 and the peer dependencies (`react`, `react-dom`, `@react-three/fiber`, `three`). See `examples/hello-react` in the repository.
155
+ Props: `scene`, `data` (as for `mount`), `ref` (a React 19 ref prop that receives the same handle `mount` returns, minus `ready` and `unmount`: one object for the component's life, reads `undefined` and calls throwing `not-mounted` until drawn and after unmount), `onReady(handle)` (called with that handle once drawn and the viewer's clock is attached, the same moment `mount`'s `ready` resolves, and again after each rebuild; under React StrictMode it still fires once per build), `onError` (a bad scene or failed data load), `className` and `style` for the wrapper. Build the `Scene` once (outside the component or in `useMemo`): a new `Scene` object rebuilds the viewer. It needs React 19 and the peer dependencies (`react`, `react-dom`, `@react-three/fiber`, `three`). See `examples/hello-react` in the repository.
127
156
 
128
157
  ## Reading and setting the time
129
158
 
130
- The viewer has one clock. A host page reads it, moves it and hears about changes, from the `mount` handle or from `AstraeusScene` props. Time is Unix milliseconds UTC; speed is simulated seconds per real second.
159
+ The viewer has one clock (and, with `setViews`, one current view: rows below). A host page reads it, moves it and hears about changes, from the `mount` handle or from `AstraeusScene` props. Time is Unix milliseconds UTC; speed is simulated seconds per real second.
131
160
 
132
161
  | Name | What it does |
133
162
  |------|--------------|
134
- | `handle.time`, `handle.rate` | The clock now. `undefined` until `ready` has resolved and after `unmount`. |
135
- | `handle.setTime(time)` | Moves the viewer to `time` (ISO text, a `Date` or milliseconds). Outside the timeline throws `bad-time`. Before `ready` or after `unmount` throws `missing-data`. |
163
+ | `handle.ready` | Resolves once the scene's data has loaded, it is drawn and the host link is attached, so `timeUtcMs`, `rate`, `view` and every `set` call work on the line after `await handle.ready`; no extra frame or wait. Rejects if loading failed, and with `not-mounted` if `unmount` came first; it never stays pending. |
164
+ | `handle.timeUtcMs`, `handle.rate` | The clock now. `undefined` until `ready` has resolved and after `unmount`. |
165
+ | `handle.setTime(time)` | Moves the viewer to `time` (ISO text, a `Date` or milliseconds). Outside the timeline throws `bad-time`. Before `ready` or after `unmount` throws `not-mounted`. |
136
166
  | `handle.setRate(rate)` | Sets the speed to one the timeline offers (`setTimeline({ rates })`). Any other number throws `bad-timeline`: the speed menu always shows what is running, so a custom speed is refused, not added. `handle.setRate("auto")` hands the speed back to the scene's pacing (below); without pacing it throws `bad-timeline`. |
137
- | `handle.onChange(fn)` or `mount(..., { onChange })` | `fn({ time, rate, playing, cause })` on every change; returns a function that stops it. `cause` is `playback` (the clock ran on; about ten calls a second while playing), `visitor` (someone used the timeline) or `host` (your own `setTime` or `setRate`). Nothing arrives after `unmount`. |
167
+ | `handle.playing` and `handle.setPlaying(playing)` | `playing` reads whether the viewer is playing (undefined before `ready` and after `unmount`). `setPlaying(true)` or `setPlaying(false)` plays or pauses through the same handler as the visitor's play button; `onChange` hears it with `cause: "host"` and the new `playing`. A non-boolean, or a scene with `setTimeline({ none: true })` (no play control for a visitor either), throws `bad-timeline`. |
168
+ | `handle.look`, `handle.setLook(look)` | `look` reads the looks in force with every one filled in (`starBrightness`, `milkyWay`, `milkyWayBrightness`, `skyVisible`, `sunGlow?` as `{ sizePx, brightness, scale }`, `markerSwapRadiusPx`, `featureMinBodyPx`, `loadFadeSeconds`, `desktopPictures`), whoever set them: the scene's `setLook`, the page address, your `setLook` or a visitor in the Developer drawer. `setLook(look)` replaces the whole look (a look not named takes its default) and is checked as `Scene.setLook` checks it (`bad-look`); a live `setLook` wins over the same look in the page address, which only starts the viewer. Presentation only. `look` is `undefined` until `ready` and after `unmount`; `setLook` before `ready` or after `unmount` throws `not-mounted`. |
169
+ | `handle.onFirstDraw(fn)` or `<AstraeusScene onFirstDraw />` | `fn()` once when the scene's first frame has been drawn (not `ready`, which resolves a moment earlier, when the clock attaches), for fading your own loading cover; returns a function that stops it. A listener added after that frame is called at once. A rebuild with a new `scene` draws a new first frame and calls the listeners still added again (the React prop is called again). A listener that throws is reported to the page (`reportError`) and does not stop the next; nothing arrives after `unmount`. |
170
+ | `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`. |
171
+ | `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`. |
172
+ | `handle.switches`, `handle.setSwitch(id, on)` | The display switches the scene placed with `setSwitches` (`orbitLines`, `labels`, `milkyWay`; 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`. |
173
+ | `handle.onChange(fn)` or `mount(..., { onChange })` | `fn({ timeUtcMs, rate, playing, view?, scale, look, switches?, cause })` on every change (`view` only in a scene with views; `switches` only in a scene that placed some); returns a function that stops it. `cause` is `playback` (the clock ran on; about ten calls a second while playing), `visitor` (someone used the timeline, the view choice, the scale, a display switch or the Developer drawer) or `host` (your own `setTime`, `setRate`, `setPlaying`, `setView`, `setScale`, `setSwitch` or `setLook`). Nothing arrives after `unmount`. |
174
+ | `<AstraeusScene ref onReady />` | The `ref` and the `onReady(handle)` argument are the handle above (`timeUtcMs`, `rate`, `playing`, `view`, `camera`, `eventZones`, `selected`, the `set` calls, `onChange`, `onEventZone`, `onSelect`, `onCameraChange`): `onReady={(handle) => handle.setTime(...)}` or `ref.current` after it. |
138
175
  | `<AstraeusScene time rate onChange />` | `time` and `rate` are applied once the viewer is drawn and again whenever their value changes (a new `Date` of the same moment does not seek again); they are not controlled values, so read the live time from `onChange`. A bad one goes to `onError`. |
176
+ | `handle.view`, `handle.setView(id)` | The id of the view showing (`setViews`), and a switch to another, as if a visitor pressed its button: the same camera rule applies. `view` is `undefined` until `ready`, after `unmount`, and in a scene without views. `setView` with an unknown id, or on a scene without views, throws `bad-view`; before `ready` or after `unmount`, `not-mounted`. `onChange` hears it with `cause: "host"` (a visitor's own choice is `"visitor"`). |
177
+ | `<AstraeusScene view />` | Switches to that view once drawn and whenever it changes; not a controlled value (a visitor can switch too), so read the live view from `onChange`. An unknown id goes to `onError` as `bad-view`. |
178
+ | `handle.setCamera(target)` | Points the camera, through the same request path a view's camera rule uses; it eases there. `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, and a pose from `handle.camera` puts the camera back (below). The object must be one the showing view shows: an unknown or hidden id, or a malformed argument, throws `bad-camera`; before `ready` or after `unmount`, `not-mounted`. |
179
+ | `handle.camera` | The camera now as a plain value `{ focus, azimuthDeg, elevationDeg, distance }` (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 always defined (before the scene's first frame it is the opening pose, the scene's start view or default framing). `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. |
180
+ | `<AstraeusScene camera />` | `{ follow: id }`, `{ focus: id }` or a pose, 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`. |
139
181
 
140
182
  ```ts
141
183
  const mounted = mount(el, scene);
142
184
  await mounted.ready;
143
185
  mounted.setTime("2026-08-12T21:00:00Z"); // jump to the flyby
144
186
  mounted.setRate(3600); // one hour per second (must be in setTimeline's rates)
145
- const stop = mounted.onChange(({ time, cause }) => {
187
+ const stop = mounted.onChange(({ timeUtcMs, cause }) => {
146
188
  if (cause !== "host") console.log(new Date(time).toISOString());
147
189
  });
148
190
  ```
149
191
 
150
192
  The speed menu shows exactly the `rates` the scene gives (`setTimeline({ rates })`) and no others.
151
193
 
194
+ ### Views of one scene
195
+
196
+ Two probes, one shared Earth, three views that keep the clock, the speed and the camera's distance when you switch (the Object list, timeline events, story panels, markers and paths follow the chosen view):
197
+
198
+ ```ts
199
+ const scene = new Scene()
200
+ .addBody(earth)
201
+ .addTrajectory({ id: "probe-a", label: "Probe A", samples: samplesA })
202
+ .addTrajectory({ id: "probe-b", label: "Probe B", samples: samplesB })
203
+ .addEvents([{ id: "a-burn", label: "A burn", time: t0 + HOUR }, { id: "b-burn", label: "B burn", time: t0 + 2 * HOUR }])
204
+ .setViews([
205
+ { id: "a", label: "Probe A", objects: ["probe-a"], events: ["a-burn"], camera: "stay" }, // the camera holds where it is
206
+ { id: "b", label: "Probe B", objects: ["probe-b"], events: ["b-burn"], camera: { follow: "probe-b" } },
207
+ { id: "both", label: "Both", objects: ["probe-a", "probe-b"], events: ["a-burn", "b-burn"] },
208
+ ], { place: "top-bar" });
209
+ const mounted = mount(el, scene);
210
+ await mounted.ready;
211
+ mounted.setView("b"); // as if the visitor pressed Probe B; onChange hears cause "host"
212
+ ```
213
+
152
214
  ### Paced playback
153
215
 
154
216
  A long journey wants fast cruising and slow encounters. `setTimeline` takes `pacing`, a list of pieces; outside every piece playback runs at the timeline's `rate`.
155
217
 
156
218
  | Piece | Meaning |
157
219
  |-------|---------|
158
- | `{ from, to, rate, ramp? }` | Plays at `rate` between the two moments. |
159
- | `{ near: { type, within }, rate, ramp? }` | Plays at `rate` within `within` seconds (simulated) of every event whose `type` matches (`addEvents`). |
220
+ | `{ start, end, rate, rampSeconds? }` | Plays at `rate` between the two moments. |
221
+ | `{ near: { type, withinSeconds }, rate, rampSeconds? }` | Plays at `rate` within `withinSeconds` seconds (simulated) of every event whose `type` matches (`addEvents`). |
222
+
223
+ Speeds ease between pieces in log space over `rampSeconds` simulated seconds (default: `withinSeconds` for an event rule, a tenth of the span for a span; `rampSeconds: 0` steps), so a jump from cruise to encounter is smooth both ways. The paced speed depends only on the time, so seeking or looping lands on the right speed at once. Spans may not overlap (touching is fine); where an event rule meets a span or another rule, the slowest speed wins, whichever contains the other and in whatever order they are listed. A piece's `rate` is any positive number and need not be in `rates`. Mistakes throw `bad-timeline` naming the field (`pacing[1].rate`); an event `type` that matches no event is refused too, since a typo would otherwise slow nothing.
224
+
225
+ In a scene with views (`setViews`), an event rule slows playback only near the events the showing view has (an event no view names is in every view); spans apply in every view. A switch that changes the paced speed eases to the new one in log space over about a second, while seeking lands on the paced speed at once. A scene without views paces exactly as before.
226
+
227
+ Selection: `mounted.selected` reads the id of the object whose information the viewer has open (undefined before `ready`, after `unmount`, and when nothing is selected), and `mounted.onSelect(listener)` calls `listener({ object?, timeUtcMs, cause })` when it changes: `object` is the new id (absent when the selection was dropped and nothing took its place), `cause` is `visitor` for the object menu, a click or a time, speed or view the visitor chose, `host` for a drop caused by the host's own `setTime`, `setRate`, `setPlaying` or `setView`, and `playback` for a drop caused by the clock running (for example past the end of a path's samples); a drop names the same cause `onChange` gave the move that caused it. The selection the viewer opens with is read, not reported. It is read-only: a host cannot select. `onSelect` returns the function that stops it; nothing arrives after `unmount`.
160
228
 
161
- Speeds ease between pieces in log space over `ramp` simulated seconds (default: `within` for an event rule, a tenth of the span for a span; `ramp: 0` steps), so a jump from cruise to encounter is smooth both ways. The paced speed depends only on the time, so seeking or looping lands on the right speed at once. Spans may not overlap (touching is fine); where an event rule meets a span or another rule, the slowest speed wins, whichever contains the other and in whatever order they are listed. A piece's `rate` is any positive number and need not be in `rates`. Mistakes throw `bad-timeline` naming the field (`pacing[1].rate`); an event `type` that matches no event is refused too, since a typo would otherwise slow nothing.
229
+ The mount handle's members live on its prototype (the same builder serves the React `ref`), so spreading it (`{ ...handle }`) or `Object.keys(handle)` shows only `ready` and `unmount`. Read and call members by name (`handle.timeUtcMs`, `handle.setTime(...)`, or destructure them); they are all there.
230
+
231
+ Camera: `mounted.onCameraChange(listener)` calls `listener(pose)` with the camera as a plain value (`{ focus, azimuthDeg, elevationDeg, distance }`, what `mounted.camera` reads) when it changes: a visitor's drag, zoom or pick, a view's camera rule, or your own `setCamera` (it reports as the camera eases, then stops when the pose settles). At most about ten reports a second; an unchanged pose reports nothing, and a camera following a moving object at a fixed pose reports nothing. The opening pose is read from `camera`, not reported. It returns the function that stops it; nothing arrives after `unmount`; a listener that throws is reported to the page and does not stop the others.
232
+
233
+ Event zones: `mounted.onEventZone(listener)` (React: the `onEventZone` prop) tells the page when playback enters or leaves the zone of an event (its `withinSeconds`, or a pacing `near` rule), for an event the showing view has, in a scene with pacing or without. `listener({ event, type?, object?, entered, timeUtcMs, cause, via })` gets the event's id, its `type` and `object`, `entered` true on entering and false on leaving, the viewer's time, and `cause`: `playback` (the clock ran), `visitor` (timeline or view choice) or `host` (`setTime`, `setView`); and `via`: `"time"` (playback crossed the zone, or a seek moved the clock across it) or `"view"` (a view switch showed or hid it). After a `"view"` leave the view's own camera rule owns the camera, so a page that restores a camera does so only for `via === "time"`. The zones are the ones pacing uses (an event's own `withinSeconds` wins over a rule's `withinSeconds`), never a span, and only the showing view's events. A view switch that hides an active zone reports leave and one that shows a zone the time is inside reports enter; overlapping zones report separately. A zone the time is already inside when the viewer opens reports `entered` once, with the first report after `ready` (within a tenth of a second, cause `playback`), so a listener added right after `await ready` hears it; a rebuilt viewer starts over the same way. `onEventZone` returns the function that stops it; nothing arrives after `unmount`. `mounted.eventZones` reads the ids of the zones active now (`[]` in a scene with no event zones; `undefined` before `ready` and after `unmount`). The engine moves nothing in response; the page composes its own behaviour:
234
+
235
+ ```ts
236
+ // Camera to the encounter and back: the page decides, the engine only says when.
237
+ let saved = mounted.camera;
238
+ mounted.onEventZone(({ entered, object, via }) => {
239
+ if (entered) { saved = mounted.camera; if (object) mounted.setCamera({ follow: object }); } // follow the probe at the flyby
240
+ else if (via === "time" && saved) mounted.setCamera(saved); // and put the camera back after it
241
+ if (!entered) saved = undefined; // a view switch's camera rule owns the camera: nothing to restore
242
+ });
243
+ ```
244
+
245
+ In React the same composition goes through the handle that `AstraeusScene` gives through `ref` (or `onReady(handle)`):
246
+
247
+ ```tsx
248
+ const handle = useRef<ViewerHandle>(null);
249
+ const saved = useRef<CameraPose>(undefined);
250
+ const onEventZone = ({ entered, object, via }: EventZoneChange) => {
251
+ const viewer = handle.current;
252
+ if (!viewer) return;
253
+ if (entered) { saved.current = viewer.camera; if (object) viewer.setCamera({ follow: object }); }
254
+ else if (via === "time" && saved.current) viewer.setCamera(saved.current);
255
+ if (!entered) saved.current = undefined;
256
+ };
257
+ return <AstraeusScene ref={handle} scene={scene} onEventZone={onEventZone} />;
258
+ ```
162
259
 
163
260
  With pacing the speed menu gains an **Auto** choice, selected from the start. Picking a speed (menu, or `setRate(number)`) takes over until the visitor chooses Auto or the host calls `setRate("auto")`. `onChange` reports the speed pacing runs at (`cause: "playback"`), and `handle.rate` reads it.
164
261
 
@@ -169,8 +266,8 @@ const scene = new Scene()
169
266
  .setTimeline({
170
267
  start: "2030-01-01", end: "2031-01-01", rate: 86_400, rates: [3_600, 86_400, 604_800],
171
268
  pacing: [
172
- { from: "2030-02-01", to: "2030-04-01", rate: 604_800 }, // a week per second through the long coast
173
- { near: { type: "flyby", within: 3 * 86_400 }, rate: 600 }, // ten minutes per second within 3 days of each flyby
269
+ { start: "2030-02-01", end: "2030-04-01", rate: 604_800 }, // a week per second through the long coast
270
+ { near: { type: "flyby", withinSeconds: 3 * 86_400 }, rate: 600 }, // ten minutes per second within 3 days of each flyby
174
271
  ],
175
272
  });
176
273
  mounted.setRate(3_600); // the visitor's choice wins ...
@@ -181,9 +278,81 @@ mounted.setRate("auto"); // ... until it is released
181
278
 
182
279
  The viewer is built to sit in a host page without taking it over. It never changes `document.title`. It isolates its own layers (`isolation: isolate` on the element given to `mount` and on the `AstraeusScene` wrapper), so its `z-index` values (0 to 9) stay inside the viewer and cannot cover or sit under your page's layers; `mount` does not restore the element's old `isolation` on `unmount`. Its Escape handlers (story panel, phone drawer, switch panel) ignore a keydown your page already stopped with `preventDefault()`. It honours `prefers-reduced-motion`: the viewer's own animations and transitions are switched off.
183
280
 
281
+ ### Several viewers on one page
282
+
283
+ You can mount more than one viewer on a page. Each keeps its own data (moon positions load per planet and are shared only as fetched files), its own pictures (a viewer draws only the pictures of the data packages passed to it), its own element ids (generated; do not select viewer parts by id) and its own styles (every viewer rule sits under the viewer's root class `.astraeus-shell`, so the viewer's rules never reach your page's elements; your page's generic rules, such as `button { ... }`, can still reach the viewer's elements for any property the viewer does not set itself). Give each element a size. Escape closes a viewer's drawer, story panel or switch panel only when pressed inside that viewer or on the bare page, never in another viewer or in your own controls (call the handle yourself for those). The viewer never looks up page elements outside its own, and the Developer drawer is not drawn unless you pass `developerTools`. Panel sizes follow the browser window, not the viewer's element, so a small viewer keeps the desktop layout of its panels.
284
+
184
285
  A scene with no `setTime`, `setTimeline` or trajectory opens on the current time, with a window of a month around it.
185
286
 
186
- Story panels (`addStoryPanels`): a panel opens only when forward playback crosses its time, so one at the opening instant never opens by itself. `at.utc` may be any instant inside the timeline, in any year. When a panel opens by itself, `pauseSeconds` (default 6) holds playback and then restarts it, unless the visitor pressed Play during the hold. On a phone, a wheel or pinch over an open story sheet zooms the scene behind it. `camera.setReach(d)` sets how far the camera can zoom out and also sets the far plane to 2.5 times `d`.
287
+ Story panels (`addStoryPanels`): a panel opens only when forward playback crosses its time, so one at the opening instant never opens by itself. `at.time` may be any moment inside the timeline, in any year. When a panel opens by itself, `pauseSeconds` (default 6) holds playback and then restarts it, unless the visitor pressed Play during the hold. On a phone, a wheel or pinch over an open story sheet zooms the scene behind it. `camera.setReach(d)` sets how far the camera can zoom out and also sets the far plane to 2.5 times `d`.
288
+
289
+ ## Page address
290
+
291
+ The viewer leaves your page's address alone. By default it reads no address parameter, never calls `history.replaceState`, and shows no "Copy view link" button, so your own `?view=` or `?t=` means nothing to it. Turn it on with `mount(element, scene, { address: true })` or `<AstraeusScene scene={scene} address />` (read once, when the viewer is built). With it on the viewer reads the parameters below when it opens, and the "Copy view link" button, which is part of the Developer tools (so it appears only with `developerTools` on as well; `address: true` alone reads the address but has no copy button), writes `view`, `scale`, `up`, `t` and, in a scene with views, `show` into the address (other parameters are kept) and copies the link. Everything the viewer does with the address goes through one file in the engine's source, so this table is complete.
292
+
293
+ Behaviour change from 0.7.0: 0.7.0 read these parameters and wrote the address whatever the host did, which made a host's own `?view=` or `?t=` move the viewer and let a copied link overwrite the host's address. Hosts that want the old behaviour pass `address: true`; the demo site does.
294
+
295
+ | Parameter | Meaning | Format | Read | Written |
296
+ |-----------|---------|--------|------|---------|
297
+ | `view` | Camera view at the start | `focus,azimuthDeg,elevationDeg,distance` (focus is an id in the scene; a bad value is ignored) | yes | yes |
298
+ | `t` | Time at the start | ISO UTC, such as `2026-08-12T21:00:00Z` | yes | yes, to the second |
299
+ | `scale` | Distance scale at the start | an id the scene's scale menu offers (others ignored) | yes | yes |
300
+ | `up` | Which direction is up for the camera | `ecliptic` or `equatorial` | yes | yes |
301
+ | `show` | The view showing, in a scene with `setViews` | a view id; an unknown id opens the scene's `start` view | yes | yes, with views only |
302
+ | `stars` | Star brightness | number 0 to 2 | yes | no |
303
+ | `milkyway` | The Milky Way picture | `on` or `off` | yes | no |
304
+ | `milkywaybrightness` | Milky Way brightness | number 0 to 2 | yes | no |
305
+ | `sky` | The whole sky | `off` hides it | yes | no |
306
+ | `labels` | Object labels at the start | `id:on` or `id:off`, comma-separated | yes | no |
307
+ | `loop` | Looping playback | `on` or `off` | yes | no |
308
+ | `markerpx` | Size below which a sphere is drawn as a marker | number 0 to 100 | yes | no |
309
+ | `featurepx` | Narrowest body that still shows its feature markers | number 0 to 2000 | yes | no |
310
+ | `sunglow`, `sunbrightness`, `sunglowscale` | The Sun's glow: size in pixels, brightness, scale | numbers 0 to 400, 0 to 2, 1 to 6 | yes | no |
311
+ | `loadfade` | Seconds the loading cover fades | number 0 to 3 | yes | no |
312
+ | `desktop` | Larger desktop pictures on a wide screen | `on` or `off` | yes | no |
313
+
314
+ Each parameter from `stars` to `desktop` that is not `labels`, `loop` or `view` has a matching `scene.setLook` key (`stars` is `starBrightness`, `markerpx` is `markerSwapRadiusPx`, `loadfade` is `loadFadeSeconds`, `desktop` is `desktopPictures`, and so on), so a look no longer needs the address; the address overrides the scene when it is on.
315
+
316
+ The demo site's own switchers (`experience`, `planet`, `shower`, and the Developer tools' data choice) change the page address to rebuild the page; they belong to the site, not to `mount` or `AstraeusScene`.
317
+
318
+ ## Errors
319
+
320
+ Every call that refuses its input throws a `SceneError`, a `RangeError` with a stable `code` to branch on and a message that names the offending value and what to do. One code means one cause. The table is generated from the doc comments of `SceneErrorCode` (`npm run api:errors` rewrites it) and a test keeps it in sync.
321
+
322
+ <!-- error-table:start (generated from the SceneErrorCode doc comments in packages/astraeus/src/api/errors.ts by `npm run api:errors`) -->
323
+ | `code` | Meaning |
324
+ |---|---|
325
+ | `unknown-body` | A body or path id is not in the catalogue or the scene. |
326
+ | `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. |
327
+ | `bad-time` | A moment is not a valid time, or lies outside the span it must fall in. |
328
+ | `bad-trajectory` | A path (`addTrajectory`) is malformed: its id, provider, bounds, plane, spans or line stretches. |
329
+ | `bad-data` | A data package passed to the viewer is malformed, for example moon positions that name a planet without a moon system. |
330
+ | `bad-scale` | The scale is not one of the engine's scales, or does not suit this scene. |
331
+ | `missing-data` | Position data a body needs was not given to the viewer: pass its data package. |
332
+ | `not-mounted` | The viewer is not drawn yet, or has been unmounted: a handle call before `ready` or after `unmount`. |
333
+ | `out-of-span` | The timeline reaches outside the years a body's data package covers. |
334
+ | `scene-mounted` | The scene was edited after a viewer took it; build a new scene instead. |
335
+ | `empty-scene` | The scene has no bodies to show. |
336
+ | `bad-element` | An orbital-elements record, or the element to mount into, is malformed. |
337
+ | `no-orbit` | An orbit line was asked for a body whose data give no closed orbit, or about a body not in the scene. |
338
+ | `bad-anchor` | A path anchor is malformed, repeated or outside the path. |
339
+ | `bad-readout` | A readout is of an unknown kind, or lacks or misnames the body or activity it measures. |
340
+ | `bad-event` | An event is malformed or names an object that is not in the scene. |
341
+ | `bad-panels` | The story panels are malformed. |
342
+ | `bad-timeline` | The timeline, its pacing or its speeds are malformed, or a call needs pacing the scene lacks. |
343
+ | `bad-switch` | A display switch is unknown or malformed. |
344
+ | `bad-body` | An option of `addBody` is malformed. |
345
+ | `bad-group` | A point group is malformed or refers to a body that is not in the scene. |
346
+ | `bad-body-set` | A body set (`addBodySet`) is malformed, or names a centre, moon, body or balance point the scene cannot draw it with. |
347
+ | `bad-moon-panel` | The moon panel (`setMoonPanel`) is malformed, or names a moon the scene does not hold. |
348
+ | `bad-picker` | The picker (`setPicker`, `setPick`) is malformed, or a pick names an option it does not have. |
349
+ | `bad-places` | A body's places (`addPlaces`) are malformed, or name a body the scene does not hold. |
350
+ | `bad-activity` | An activity curve is malformed. |
351
+ | `bad-camera` | A camera call or pose is malformed, or names an object the view cannot show. |
352
+ | `bad-view` | A scene view is malformed, repeated, or not one of the scene's views. |
353
+ | `bad-look` | A look (`setLook`) is unknown or out of its range. |
354
+ | `renamed` | An input field was given under a name it no longer has; the message names the old field and its replacement. |
355
+ <!-- error-table:end -->
187
356
 
188
357
  ## Loading in your build and in tests
189
358
 
@@ -195,9 +364,9 @@ window.addEventListener("vite:preloadError", () => window.location.reload());
195
364
 
196
365
  (The Developer drawer also says when its file cannot be fetched and asks for a reload.)
197
366
 
198
- For tests, the package has a `node` export condition: Node and Vitest's Node environment import a copy of the package without the stylesheet import, so `new Scene()...toDefinition()` works with no `test.server.deps.inline` setting. The jsdom and happy-dom Vitest environments also take the `node` condition, so the viewer's CSS is not loaded there; this does not matter for tests that check scene definitions or behaviour. Bundlers do not use the `node` condition and load the normal build.
367
+ For tests, the package has a `node` export condition: Node and Vitest's Node environment import a copy of the package without the stylesheet import, so `new Scene()...check()` and the `scene.bodies`-style reads work with no `test.server.deps.inline` setting. The jsdom and happy-dom Vitest environments also take the `node` condition, so the viewer's CSS is not loaded there; this does not matter for tests that check what a scene holds or how it behaves. Bundlers do not use the `node` condition and load the normal build.
199
368
 
200
- First download: the packed `examples/hello-scene` loads 1,638,245 bytes (468,717 gzip) of code and styles, measured at this commit on first open (`npm run measure:example`; pictures and data files are not counted).
369
+ First download: the packed `examples/hello-scene` loads 1,716,429 bytes (492,249 gzip) of code and styles, measured at this commit on first open (`npm run measure:example`; pictures and data files are not counted).
201
370
 
202
371
  ## What `astraeus-data` adds
203
372
 
@@ -223,6 +392,8 @@ Nothing is looked up behind your back. A moon added without its data package mak
223
392
 
224
393
  Only what `import ... from "astraeus"` (and `astraeus/style.css`) gives you is public. Deep imports, file paths inside the package and the repository's other workspaces (the demos and the site) are internal and may change in any release.
225
394
 
395
+ The public surface is locked: a test compares what `astraeus` exports with a checked-in lock (`api-surface.lock.json`), so a change to it cannot slip in unnoticed. Every change to it is listed in the [CHANGELOG](CHANGELOG.md).
396
+
226
397
  ## Licence
227
398
 
228
399
  MIT for the code. Pictures and data carry their own credits and licences: see `NOTICE` and `licenses/`, and each picture's `licence` record.
@@ -252,7 +423,7 @@ A demo is a package that depends on `astraeus`, builds an `ExperienceDefinition`
252
423
 
253
424
  A complete small example with no real data is `src/synthetic/syntheticDefinition.ts`: a made-up object on a tilted loop with marks, events and story panels. Read it first; the site lists it as the `synthetic` experience (`packages/astraeus-site/src/main.tsx`).
254
425
 
255
- The source `exports` list is broad (one pattern per folder) for the demos and the site; the published package exports only `.` (the public API) and `./style.css`, written into `dist/package.json` from the `x-publish` block of this manifest.
426
+ The source `exports` list is broad (one pattern per folder) for the demos and the site; the published package exports only `.` (the public API), `./style.css` and `./package.json`, written into `dist/package.json` from the `x-publish` block of this manifest.
256
427
 
257
428
  ## Check it alone
258
429
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "astraeus",
3
- "version": "0.6.0",
3
+ "version": "0.8.0",
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",
@@ -9,8 +9,8 @@
9
9
  },
10
10
  "peerDependencies": {
11
11
  "@react-three/fiber": ">=9.8.2 <10",
12
- "react": ">=19 <19.4",
13
- "react-dom": ">=19 <19.4",
12
+ "react": ">=19 <20",
13
+ "react-dom": ">=19 <20",
14
14
  "three": ">=0.169.0 <1"
15
15
  },
16
16
  "exports": {
@@ -19,7 +19,8 @@
19
19
  "node": "./src/api/index.node.js",
20
20
  "import": "./src/api/index.js"
21
21
  },
22
- "./style.css": "./src/app/style.css"
22
+ "./style.css": "./src/app/style.css",
23
+ "./package.json": "./package.json"
23
24
  },
24
25
  "sideEffects": [
25
26
  "**/*.css"
@@ -1,24 +1,42 @@
1
- import { type CSSProperties, type ReactElement } from "react";
1
+ import { type CSSProperties, type ReactElement, type Ref } from "react";
2
2
  import "../app/style.css";
3
3
  import type { DataSource, Scene } from "./scene.js";
4
4
  import { type TimeInput } from "./time.js";
5
- import { type ViewerChange } from "./viewerLink.js";
5
+ import { type ViewerHandle } from "./viewerHandle.js";
6
+ import type { PickChange } from "./pickerInput.js";
7
+ import { type CameraTarget, type EventZoneChange, type ViewerChange } from "./viewerLink.js";
6
8
  /** Props of `AstraeusScene`. */
7
9
  export interface AstraeusSceneProps {
8
10
  /** The scene to draw. Passing a different `Scene` object rebuilds the viewer; changing the same object in place does not. */
9
11
  readonly scene: Scene;
10
12
  /** Data packages the scene's bodies need, such as moon pictures or positions. Read when the scene is built, so a new array alone does not rebuild. */
11
13
  readonly data?: readonly DataSource[];
12
- /** Called once the scene's data has loaded and it is drawn (again after each rebuild). */
13
- readonly onReady?: () => void;
14
+ /** The viewer's handle (the same `ViewerHandle` `mount` returns): one object for the component's life, also across a rebuild with a new `scene`. Reads are undefined and calls throw `not-mounted` until the viewer is drawn and after unmount. A React 19 ref prop. */
15
+ readonly ref?: Ref<ViewerHandle>;
16
+ /** Called with the handle once the scene's data has loaded, it is drawn and the viewer's clock is attached, so a host can read and set from here (again, with the same handle, after each rebuild). */
17
+ readonly onReady?: (handle: ViewerHandle) => void;
14
18
  /** Called when the scene cannot be built (a `SceneError`) or its data fails to load. */
15
19
  readonly onError?: (error: Error) => void;
16
20
  /** Moves the viewer to this moment (ISO text, a `Date` or Unix milliseconds) once it is drawn, and again whenever the moment changes. Outside the timeline reports `bad-time` to `onError`. Not a controlled value: the viewer keeps running from there, so the current time arrives through `onChange`. */
17
21
  readonly time?: TimeInput;
18
22
  /** Sets the playback speed once drawn and whenever it changes; must be one of the speeds the timeline offers (or `"auto"`, to hand it back to the scene's pacing), else `bad-timeline` goes to `onError`. */
19
23
  readonly rate?: number | "auto";
20
- /** Called whenever the viewer's time, speed or playing state changes: playback running, a visitor using the timeline, or the `time` / `rate` props. About ten times a second while playing. */
24
+ /** Switches to this view (an id from `setViews`) once drawn, and again whenever it changes. Not a controlled value: a visitor can switch too, and the view showing arrives through `onChange`. An unknown id, or a scene without views, reports `bad-view` to `onError`. */
25
+ readonly view?: string;
26
+ /** Points the camera once drawn, and whenever the target changes by value (a new object with the same target does not re-apply): `{ follow: id }`, `{ focus: id }` or a pose read from a `mount` handle. Not a controlled value: a visitor can move the camera afterwards. A bad one reports `bad-camera` to `onError`. */
27
+ readonly camera?: CameraTarget;
28
+ /** Called whenever the viewer's time, speed, playing state or view changes: playback running, a visitor using the timeline or the view choice, or the `time` / `rate` / `view` props. About ten times a second while playing. */
21
29
  readonly onChange?: (change: ViewerChange) => void;
30
+ /** Called when playback enters or leaves the zone of an event the showing view has (its `withinSeconds`, or a pacing rule): `{ event, type?, object?, entered, timeUtcMs, cause }` (see `MountedScene.onEventZone`). A zone already active when the viewer opens reports `entered` once, just after `onReady`. */
31
+ readonly onEventZone?: (change: EventZoneChange) => void;
32
+ /** Called when a visitor presses a picker option other than the pressed one (`Scene.setPicker`; see `ViewerHandle.onPick`). The pressed option does not move until the host calls `handle.setPick`, or passes a new `scene`. */
33
+ readonly onPick?: (change: PickChange) => void;
34
+ /** Called once when the scene's first frame has been drawn (`MountedScene.onFirstDraw`), and again after each rebuild with a new `scene`. */
35
+ readonly onFirstDraw?: () => void;
36
+ /** Whether the viewer reads the page address and offers a copy-link button that writes it (default false: the address stays the host page's own). Read when the viewer is built. See the README's "Page address" section. */
37
+ readonly address?: boolean;
38
+ /** Whether the viewer shows the Developer toggle and drawer (default false: no cog, and the drawer's code is never fetched). Read when the viewer is built. "Copy view link" lives in the drawer, so `address` without this has no copy button; a switch placed `"developer"` shows only when this is on. */
39
+ readonly developerTools?: boolean;
22
40
  /** Class for the wrapper element, which fills its parent's width and height unless `style` says otherwise. */
23
41
  readonly className?: string;
24
42
  /** Style for the wrapper element. */
@@ -32,4 +50,4 @@ export interface AstraeusSceneProps {
32
50
  * return <div style={{ height: "100vh" }}><AstraeusScene scene={scene} onError={console.error} /></div>;
33
51
  * }
34
52
  */
35
- export declare function AstraeusScene({ scene, data, onReady, onError, time, rate, onChange, className, style }: AstraeusSceneProps): ReactElement;
53
+ export declare function AstraeusScene({ ref, scene, data, onReady, onError, time, rate, view, camera, onChange, onEventZone, onPick, onFirstDraw, address, developerTools, className, style }: AstraeusSceneProps): ReactElement;