astraeus 0.7.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 (271) hide show
  1. package/CHANGELOG.md +176 -0
  2. package/README.md +185 -37
  3. package/package.json +5 -4
  4. package/src/api/AstraeusScene.d.ts +21 -5
  5. package/src/api/AstraeusScene.js +34 -10
  6. package/src/api/AstraeusScene.node.js +34 -10
  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 +18 -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 +9 -19
  36. package/src/api/mount.js +27 -13
  37. package/src/api/mount.node.js +27 -13
  38. package/src/api/pathProvenance.js +1 -1
  39. package/src/api/pickerInput.d.ts +25 -0
  40. package/src/api/pickerInput.js +1 -0
  41. package/src/api/planBodies.d.ts +72 -0
  42. package/src/api/planBodies.js +300 -0
  43. package/src/api/planBodySets.d.ts +68 -0
  44. package/src/api/planBodySets.js +234 -0
  45. package/src/api/planCamera.d.ts +83 -0
  46. package/src/api/planCamera.js +184 -0
  47. package/src/api/planGroups.d.ts +36 -0
  48. package/src/api/planGroups.js +103 -0
  49. package/src/api/planMoonPanel.d.ts +19 -0
  50. package/src/api/planMoonPanel.js +104 -0
  51. package/src/api/planPaths.d.ts +40 -0
  52. package/src/api/planPaths.js +212 -0
  53. package/src/api/planPicker.d.ts +12 -0
  54. package/src/api/planPicker.js +40 -0
  55. package/src/api/planPlaces.d.ts +16 -0
  56. package/src/api/planPlaces.js +99 -0
  57. package/src/api/planStory.d.ts +26 -0
  58. package/src/api/planStory.js +66 -0
  59. package/src/api/planTimeline.d.ts +27 -0
  60. package/src/api/planTimeline.js +68 -0
  61. package/src/api/planViews.d.ts +25 -0
  62. package/src/api/planViews.js +35 -0
  63. package/src/api/prepared.js +4 -1
  64. package/src/api/renamedInputs.d.ts +15 -0
  65. package/src/api/renamedInputs.js +39 -0
  66. package/src/api/scene.d.ts +162 -68
  67. package/src/api/scene.js +247 -793
  68. package/src/api/sceneFreeze.d.ts +4 -0
  69. package/src/api/sceneFreeze.js +10 -0
  70. package/src/api/sceneReads.d.ts +171 -0
  71. package/src/api/sceneReads.js +6 -0
  72. package/src/api/story.d.ts +49 -19
  73. package/src/api/story.js +54 -22
  74. package/src/api/sunOrbit.js +9 -11
  75. package/src/api/time.d.ts +2 -1
  76. package/src/api/time.js +2 -1
  77. package/src/api/viewerCamera.d.ts +22 -0
  78. package/src/api/viewerCamera.js +84 -0
  79. package/src/api/viewerClock.d.ts +30 -0
  80. package/src/api/viewerClock.js +85 -0
  81. package/src/api/viewerFirstDraw.d.ts +14 -0
  82. package/src/api/viewerFirstDraw.js +26 -0
  83. package/src/api/viewerHandle.d.ts +79 -0
  84. package/src/api/viewerHandle.js +31 -0
  85. package/src/api/viewerLink.d.ts +87 -15
  86. package/src/api/viewerLink.js +111 -75
  87. package/src/api/viewerLooks.d.ts +19 -0
  88. package/src/api/viewerLooks.js +37 -0
  89. package/src/api/viewerPicker.d.ts +22 -0
  90. package/src/api/viewerPicker.js +49 -0
  91. package/src/api/viewerSelection.d.ts +25 -0
  92. package/src/api/viewerSelection.js +31 -0
  93. package/src/api/viewerViews.d.ts +10 -0
  94. package/src/api/viewerViews.js +18 -0
  95. package/src/api/viewerZones.d.ts +20 -0
  96. package/src/api/viewerZones.js +47 -0
  97. package/src/api/views.d.ts +4 -5
  98. package/src/api/views.js +7 -5
  99. package/src/app/App.d.ts +5 -3
  100. package/src/app/App.js +191 -82
  101. package/src/app/App.node.js +191 -82
  102. package/src/app/AstraeusScene.d.ts +16 -2
  103. package/src/app/AstraeusScene.js +4 -4
  104. package/src/app/BodyView.d.ts +4 -1
  105. package/src/app/BodyView.js +2 -2
  106. package/src/app/CameraController.d.ts +6 -0
  107. package/src/app/DeveloperSettings.d.ts +1 -4
  108. package/src/app/DeveloperSettings.js +6 -10
  109. package/src/app/FeatureMarkers.d.ts +4 -3
  110. package/src/app/FeatureMarkers.js +8 -13
  111. package/src/app/FrameRateSection.js +2 -1
  112. package/src/app/OrbitSetView.js +1 -1
  113. package/src/app/SettingControls.d.ts +11 -3
  114. package/src/app/SettingControls.js +10 -2
  115. package/src/app/SkyView.d.ts +3 -10
  116. package/src/app/SkyView.js +6 -28
  117. package/src/app/address.d.ts +16 -0
  118. package/src/app/address.js +31 -0
  119. package/src/app/bodyDraw.d.ts +10 -7
  120. package/src/app/bodyDraw.js +12 -32
  121. package/src/app/bodyMetrics.js +2 -2
  122. package/src/app/bodySet.d.ts +4 -20
  123. package/src/app/bodySet.js +5 -16
  124. package/src/app/debugReadout.js +1 -1
  125. package/src/app/displaySwitches.d.ts +4 -0
  126. package/src/app/displaySwitches.js +6 -0
  127. package/src/app/experienceDefinition.d.ts +11 -23
  128. package/src/app/listSwitch.d.ts +8 -14
  129. package/src/app/listSwitch.js +3 -10
  130. package/src/app/liveLook.d.ts +39 -0
  131. package/src/app/liveLook.js +66 -0
  132. package/src/app/look.d.ts +36 -0
  133. package/src/app/look.js +61 -0
  134. package/src/app/mission.d.ts +1 -1
  135. package/src/app/mission.js +1 -1
  136. package/src/app/openClock.d.ts +3 -2
  137. package/src/app/openClock.js +3 -3
  138. package/src/app/sceneCamera.js +9 -0
  139. package/src/app/sceneFrame.d.ts +4 -4
  140. package/src/app/sceneFrame.js +13 -8
  141. package/src/app/sceneHooks.js +3 -2
  142. package/src/app/style.css +114 -139
  143. package/src/app/trackedMetrics.d.ts +10 -3
  144. package/src/app/trackedMetrics.js +22 -11
  145. package/src/app/viewLink.d.ts +10 -32
  146. package/src/app/viewLink.js +10 -49
  147. package/src/app/viewerPort.d.ts +50 -0
  148. package/src/app/views.d.ts +1 -0
  149. package/src/assets/bodies/galileanMoons.js +1 -2
  150. package/src/assets/bodies/io.js +2 -2
  151. package/src/assets/bodies/listedMoons.d.ts +1 -1
  152. package/src/assets/bodies/listedMoons.js +2 -3
  153. package/src/assets/bodies/planetSystemMaps.js +2 -3
  154. package/src/assets/bodies/venus.js +2 -6
  155. package/src/assets/catalogue.js +1 -2
  156. package/src/assets/licence.d.ts +3 -3
  157. package/src/assets/licence.js +3 -3
  158. package/src/assets/pictures.d.ts +15 -12
  159. package/src/assets/pictures.js +24 -20
  160. package/src/assets/sky.d.ts +6 -5
  161. package/src/assets/sky.js +6 -9
  162. package/src/assets/visual.d.ts +4 -0
  163. package/src/core/bodies/index.d.ts +0 -4
  164. package/src/core/bodies/index.js +1 -6
  165. package/src/core/bodies/jupiterData.d.ts +0 -1
  166. package/src/core/bodies/jupiterData.js +2 -5
  167. package/src/core/bodies/moonSystem.d.ts +1 -1
  168. package/src/core/bodies/moonSystem.js +102 -55
  169. package/src/core/bodies/outerPlanetRingData.js +2 -2
  170. package/src/core/bodies/planetTrajectory.js +1 -1
  171. package/src/core/bodySetFamilies.d.ts +20 -0
  172. package/src/core/bodySetFamilies.js +14 -0
  173. package/src/core/chebyshevEphemeris.js +1 -1
  174. package/src/core/elementsBody.d.ts +8 -4
  175. package/src/core/elementsBody.js +32 -11
  176. package/src/core/elementsGroup.d.ts +27 -0
  177. package/src/core/elementsGroup.js +85 -0
  178. package/src/core/events.d.ts +2 -0
  179. package/src/core/events.js +2 -0
  180. package/src/core/illumination.js +1 -1
  181. package/src/core/listedOrbitGroup.d.ts +2 -0
  182. package/src/core/listedOrbitGroup.js +11 -7
  183. package/src/core/moonListText.d.ts +6 -0
  184. package/src/core/moonListText.js +19 -0
  185. package/src/core/moonTrajectory.js +1 -1
  186. package/src/core/pacing.d.ts +38 -3
  187. package/src/core/pacing.js +55 -4
  188. package/src/core/planetModels.js +2 -2
  189. package/src/core/planetSeries.d.ts +8 -0
  190. package/src/core/planetSeries.js +16 -2
  191. package/src/core/pointGroup.js +1 -1
  192. package/src/core/provenance.d.ts +2 -1
  193. package/src/core/provenance.js +2 -2
  194. package/src/core/referenceCenters.js +5 -5
  195. package/src/core/sampledTrajectory.js +1 -1
  196. package/src/core/scalePolicy.d.ts +1 -0
  197. package/src/core/startView.d.ts +19 -0
  198. package/src/core/startView.js +28 -0
  199. package/src/core/state.d.ts +6 -2
  200. package/src/core/state.js +3 -3
  201. package/src/core/storyPanels.d.ts +63 -0
  202. package/src/core/storyPanels.js +111 -0
  203. package/src/core/sunCentredSources.d.ts +4 -0
  204. package/src/core/sunCentredSources.js +9 -2
  205. package/src/core/timeInput.d.ts +4 -0
  206. package/src/core/timeInput.js +4 -0
  207. package/src/shell/AstraeusShell.d.ts +5 -1
  208. package/src/shell/AstraeusShell.js +20 -11
  209. package/src/shell/AstraeusShell.node.js +20 -11
  210. package/src/shell/Collapsible.d.ts +4 -3
  211. package/src/shell/Collapsible.js +5 -5
  212. package/src/shell/ControlsDrawer.d.ts +1 -1
  213. package/src/shell/ControlsDrawer.js +3 -1
  214. package/src/shell/DisplaySwitches.js +2 -1
  215. package/src/shell/InfoPanel.d.ts +3 -1
  216. package/src/shell/InfoPanel.js +5 -4
  217. package/src/shell/MoonFamilyPanel.js +1 -1
  218. package/src/shell/ObjectControls.d.ts +3 -1
  219. package/src/shell/ObjectControls.js +2 -2
  220. package/src/shell/Sources.d.ts +5 -3
  221. package/src/shell/Sources.js +5 -5
  222. package/src/shell/StoryPanelView.d.ts +4 -3
  223. package/src/shell/StoryPanelView.js +8 -6
  224. package/src/shell/SwitchControl.d.ts +5 -11
  225. package/src/shell/SwitchControl.js +2 -20
  226. package/src/shell/TimelineBar.css +81 -81
  227. package/src/shell/TimelineBar.d.ts +5 -2
  228. package/src/shell/TimelineBar.js +9 -8
  229. package/src/shell/TimelineBar.node.js +9 -8
  230. package/src/shell/TopBar.css +22 -22
  231. package/src/shell/TopBar.d.ts +5 -1
  232. package/src/shell/TopBar.js +2 -2
  233. package/src/shell/TopBar.node.js +2 -2
  234. package/src/shell/bootLoader.d.ts +4 -10
  235. package/src/shell/bootLoader.js +6 -52
  236. package/src/shell/embedded.css +18 -18
  237. package/src/shell/experience.d.ts +1 -1
  238. package/src/shell/moonFamilies.d.ts +2 -6
  239. package/src/shell/moonFamilies.js +2 -18
  240. package/src/shell/phone.css +58 -58
  241. package/src/shell/storyPanels.d.ts +2 -53
  242. package/src/shell/storyPanels.js +1 -106
  243. package/src/shell/style.css +153 -134
  244. package/src/shell/useDrawers.d.ts +3 -2
  245. package/src/shell/useDrawers.js +4 -3
  246. package/src/shell/viewerKeys.d.ts +8 -0
  247. package/src/shell/viewerKeys.js +16 -0
  248. package/src/synthetic/syntheticDefinition.js +20 -24
  249. package/src/synthetic/syntheticJourneyScene.js +3 -3
  250. package/src/synthetic/syntheticProbeDefinition.js +2 -1
  251. package/src/synthetic/syntheticViewsDefinition.d.ts +0 -3
  252. package/src/synthetic/syntheticViewsDefinition.js +10 -16
  253. package/data/moons/jupiter.json +0 -3333
  254. package/data/moons/neptune.json +0 -555
  255. package/data/moons/pluto.json +0 -205
  256. package/data/moons/saturn.json +0 -8267
  257. package/data/moons/uranus.json +0 -887
  258. package/src/app/addressNavigation.d.ts +0 -17
  259. package/src/app/addressNavigation.js +0 -16
  260. package/src/assets/bodies/jupiterMoonCatalogue.d.ts +0 -3
  261. package/src/assets/bodies/jupiterMoonCatalogue.js +0 -4
  262. package/src/assets/bodies/outerPlanetCatalogues.d.ts +0 -7
  263. package/src/assets/bodies/outerPlanetCatalogues.js +0 -8
  264. package/src/assets/bodies/swiftTuttle.d.ts +0 -12
  265. package/src/assets/bodies/swiftTuttle.js +0 -13
  266. package/src/assets/moonCatalogue.d.ts +0 -49
  267. package/src/assets/moonCatalogue.js +0 -80
  268. package/src/core/bodies/outerPlanetData.d.ts +0 -4
  269. package/src/core/bodies/outerPlanetData.js +0 -13
  270. package/src/core/bodies/swiftTuttle.d.ts +0 -46
  271. package/src/core/bodies/swiftTuttle.js +0 -106
package/CHANGELOG.md CHANGED
@@ -2,6 +2,182 @@
2
2
 
3
3
  Versions follow [semantic versioning](https://semver.org). While the version starts with `0.`, the public API (the names exported from `astraeus`) may still change between minor versions; each change is listed here.
4
4
 
5
+ ## 0.8.0 (2026-11-07)
6
+
7
+ First download of the packed example (`npm run measure:example`): 1,716,429 bytes raw, 492,249 bytes gzip (code and styles loaded on first open), against 1,652,632 raw and 472,929 gzip at 0.7.0.
8
+
9
+ A modular, consumable package (G-016, O-053 to O-060): one front door, the same abilities from `mount` and React, a viewer that behaves as a good guest on any page, numbers without a viewer, looks as public settings, standalone event zones, consistent names, units and shapes, and a scene builder split by concern. This is a clean break: old names are removed, not aliased. Apps built on 0.7.0 follow the migration table below.
10
+
11
+ ### Migration from 0.7.0 to 0.8.0
12
+
13
+ This one table lists every change an app built on 0.7.0 must act on, from O-053 to O-059 and from the renames of O-057. Old names are removed, not aliased: TypeScript flags each one, and a plain JavaScript caller who passes an old input name gets a `SceneError` with code `renamed` naming its replacement. Each row is checked against the 0.7.0 surface and `api-surface.lock.json` by `packages/astraeus-site/tests/migrationTable.test.ts`, which also fails if a change between them has no row; `behaviour` rows hold what no type can show. The step entries further down were written as each step landed and keep the words of that day; where they differ, this table wins.
14
+
15
+ | Kind | 0.7.0 | 0.8.0 | What to do |
16
+ |---|---|---|---|
17
+ | removed | `Scene.toDefinition` | `Scene.check`, `Scene.load` and the reads in the `read` rows | Stop calling it; use the row for what you read from it. |
18
+ | removed | `Scene.missingData` | `Scene.check` | Call `scene.check({ data })`; it throws `missing-data` naming what is missing. |
19
+ | read | `toDefinition(data)` as a build check | `Scene.check` | `scene.check({ data })` throws the `SceneError` that `mount` would, and loads and freezes nothing. |
20
+ | read | `toDefinition(data).prepare()` | `Scene.load` | `await scene.load({ data })`, then call `stateOf` and `provenanceOf`. |
21
+ | read | `composition.bodies` | `Scene.bodies`, `SceneBodyRead.id` | `scene.bodies.map((body) => body.id)`; the centre is `scene.bodies[0].id`. |
22
+ | read | `scaleChoices` | `Scene.scales` | Read `scene.scales`, opening scale first. |
23
+ | read | `trackedBodies` | `Scene.paths`, `ScenePathRead.id` | `scene.paths.map((path) => path.id)`. |
24
+ | read | `views.views` (id, label), `views.start`, `views.place` | `Scene.views`, `SceneViewsRead.items`, `SceneViewsRead.startId`, `SceneViewsRead.place` | Read `scene.views.items`, `.startId` and `.place`. |
25
+ | read | `views.views[i].objects`, `.events` and `.panels` (what a view shows) | `SceneViewRead.objects`, `SceneViewRead.events`, `SceneViewRead.panels` | Read `scene.views.items[i].objects`, `.events` and `.panels`: id lists, with what no view names included in every view. Reading checks the ids as `mount` does (`bad-view`). |
26
+ | read | `paths` entries whose id ends `-orbit` | `Scene.bodies`, `SceneBodyRead.orbit` | `scene.bodies.filter((body) => body.orbit)`. |
27
+ | read | `experience.objects` label, description, known limits | `SceneBodyRead.label`, `SceneBodyRead.description`, `SceneBodyRead.knownLimitations`, `ScenePathRead.label`, `ScenePathRead.description`, `ScenePathRead.knownLimitations` | Find the entry by id in `scene.bodies` or `scene.paths`. |
28
+ | read | `experience.objects` provenance | `Scene.provenanceOf` | `scene.provenanceOf(id)`, unchanged. |
29
+ | read | `groups[i].object`, `groups[i].group.count`, `groups[i].group.provenance` | `Scene.groups`, `SceneGroupRead.id`, `SceneGroupRead.description`, `SceneGroupRead.knownLimitations`, `SceneGroupRead.count`, `SceneGroupRead.provenance` | Read the same facts from `scene.groups[i]`. |
30
+ | read | `experience.events` | `Scene.events`, `SceneEventRead.id`, `SceneEventRead.timeUtcMs` | Read `scene.events`. |
31
+ | read | `experience.eventProvenance`, `eventProvenanceById` | `SceneEventRead.provenance` | Read `scene.events[i].provenance`: the event's own, else the batch's. |
32
+ | read | `experience.storyPanels.panels` | `Scene.panels`, `ScenePanelRead.object`, `ScenePanelRead.provenance` | Read `scene.panels`: `object` for `objectId`, `provenance.sourceType` for `badge`, `provenance.sources` for `sources`. |
33
+ | read | `clock.startUtcMs` | `Scene.timeline`, `SceneTimelineRead.openUtcMs` | Read `scene.timeline.openUtcMs`. |
34
+ | read | `camera.far` | `SceneCamera.farEarthRadii`, `SceneCamera.reachEarthRadii` | Read `scene.camera.farEarthRadii`; when you gave none, the far plane is `scene.camera.reachEarthRadii * 2.5`. |
35
+ | read | `camera.fitOrbit`, `camera.maxFocusDistance` | `SceneCamera.fitted`, `SceneCamera.reachEarthRadii` | Read `scene.camera.fitted` and `scene.camera.reachEarthRadii`. |
36
+ | changed | `SceneCamera` (a class you could build) | `SceneCamera` (a type only) | Reach it as `scene.camera`; `new SceneCamera()` no longer exists. |
37
+ | renamed | `SceneCamera.lookAt` | `SceneCamera.focus` | Rename the call. |
38
+ | renamed | `SceneCamera.reach` | `SceneCamera.reachEarthRadii` | Rename the read; `setReach` keeps its name. |
39
+ | removed | `RateSource` | nothing | Delete the import; nothing public returned it. |
40
+ | renamed | `AddBodyOptions.labelReach` | `AddBodyOptions.labelReachEarthRadii` | Rename the option on `addBody`. |
41
+ | renamed | `labelReach` on `addTrajectory` | `TrajectoryBase.labelReachEarthRadii` | Rename the option on `addTrajectory`. |
42
+ | renamed | `MoonPositions.centre` | `MoonPositions.center` | Rename it in your own data package. |
43
+ | changed | `MoonPositions.loadIndex` (returns `unknown`) | `MoonPositions.loadIndex` (returns `MoonIndex`) | Type your own `loadIndex`; the shipped packages already do. |
44
+ | changed | `GroupInput.plane` (optional) | `GroupInput.plane` (required) | State it. The old default was `"ecliptic-j2000"`; without it `addGroup` throws `bad-group`. |
45
+ | renamed | `ElementsBodyRecord.frame` | `ElementsBodyRecord.plane` | Rename it in every record and file. |
46
+ | renamed | `ElementsBodyRecord.accuracy.validFromUtc` | `ElementsBodyRecord.accuracy.valid.start` | Move it into `accuracy.valid: { start, end }`: ISO text as before, or a `Date` or milliseconds. |
47
+ | renamed | `ElementsBodyRecord.accuracy.validToUtc` | `ElementsBodyRecord.accuracy.valid.end` | As the row above. |
48
+ | renamed | `PacingInput.from` | `PacingInput.start` | Rename it in each pacing span. |
49
+ | renamed | `PacingInput.to` | `PacingInput.end` | Rename it in each pacing span. |
50
+ | renamed | `PacingInput.ramp` | `PacingInput.rampSeconds` | Rename it in each span and rule; the value is still seconds. |
51
+ | renamed | `PacingInput.near.within` | `PacingInput.near.withinSeconds` | Rename it in each event rule; the value is still seconds. |
52
+ | renamed | `ViewInput.paths` | `ViewInput.objects` | Merge it with `bodies` into one `objects` list. |
53
+ | renamed | `ViewInput.bodies` | `ViewInput.objects` | As the row above; `events` and `panels` stay. |
54
+ | renamed | `MountedScene.time` | `MountedScene.timeUtcMs`, `ViewerHandle.timeUtcMs` | Rename the read, from `mount` and from the React handle. The React `time` prop and `setTime` keep their names. |
55
+ | renamed | `ViewerChange.time` | `ViewerChange.timeUtcMs` | Rename it in `onChange` listeners. |
56
+ | renamed | `State.frame` | `State.plane` | Rename the read on what `scene.stateOf` returns; the value is still `"EQJ"`. |
57
+ | renamed | `TextureRef.desktop.minViewportWidth` | `TextureRef.desktop.minViewportWidthPx` | Rename it; the value is CSS pixels. |
58
+ | removed | `StoryPanelsInput` | `StoryPanelInput`, `StoryPanelPlaybackInput` | Use the two new types. |
59
+ | changed | `Scene.addStoryPanels` (one object, replaced what was there) | `Scene.addStoryPanels` (a list, appends) | Pass a list of panels. A second call now adds to the first, and a repeated id throws `duplicate-id`. |
60
+ | renamed | `StoryPanelsInput.panels` | `Scene.addStoryPanels` | Pass the list itself. |
61
+ | renamed | `StoryPanelsInput.pauseSeconds` | `Scene.setStoryPanelPlayback`, `StoryPanelPlaybackInput.pauseSeconds` | Move it out of `addStoryPanels` to its own call, which replaces the whole setting. |
62
+ | renamed | `StoryPanelsInput.autoOpen` | `Scene.setStoryPanelPlayback`, `StoryPanelPlaybackInput.autoOpen` | Move it out of `addStoryPanels`, as the row above. |
63
+ | renamed | Panel `badge` | `StoryPanelInput.provenance`, `provenance.sourceType` | Give `provenance: { sourceType, sources, accuracy, notes }`; the old word is `sourceType`. |
64
+ | renamed | Panel `sources` | `StoryPanelInput.provenance`, `provenance.sources` | Move it into `provenance`, and state `accuracy` and `notes`. Where a source states none, say so; invent nothing. |
65
+ | renamed | Panel `at.utc` | `StoryPanelAt.time` | Rename it; it takes any `TimeInput`. |
66
+ | behaviour | Malformed panels failed at `mount` | `bad-panels` at the call | A wrong shape throws at `addStoryPanels`. A wrong link to an event, anchor or object still throws at `check` and `mount`. |
67
+ | behaviour | `addBody("swift-tuttle")` | `Scene.addBodyFromElements` | The comet left the catalogue and `addBody` throws `unknown-body`. Add it from a record; the catalogue holds the Sun, the planets, Pluto and the moons. |
68
+ | behaviour | A repeated event id threw `bad-event` | `duplicate-id` | Catch `duplicate-id`, in one call or across calls (I-145). |
69
+ | behaviour | A repeated activity id threw `bad-activity` | `duplicate-id` | Catch `duplicate-id`. |
70
+ | behaviour | Moon positions naming a planet with no moon system threw a `RangeError` | `SceneError` code `bad-data` | Catch `SceneError`. |
71
+ | behaviour | Handle calls before `ready` or after `unmount` threw `missing-data` | `not-mounted` | Catch `not-mounted`; `missing-data` now means only missing data packages. Listener registration never throws. |
72
+ | behaviour | `ready` stayed pending or resolved unusable after an early `unmount` | `ready` rejects with `not-mounted` | Handle or ignore that rejection. |
73
+ | behaviour | Edits to a mounted scene were ignored | `scene-mounted` | Build a new `Scene`; the same scene may be mounted again. |
74
+ | changed | `AstraeusSceneProps.onReady` (no argument) | `AstraeusSceneProps.onReady` (receives the handle), `AstraeusSceneProps.ref` | Read and set through the handle. An `onReady` with no argument keeps working. |
75
+ | changed | `SceneErrorCode` | `SceneErrorCode` | The codes above are new, as are `bad-look`, `bad-body-set`, `bad-moon-panel`, `bad-places`, `bad-picker` and `renamed`. An exhaustive `switch` must handle them. |
76
+ | behaviour | The viewer read and wrote the page address | `MountOptions.address`, `AstraeusSceneProps.address` | Pass `address: true` to keep it; the default is off. |
77
+ | behaviour | The Developer cog and drawer always showed | `MountOptions.developerTools`, `AstraeusSceneProps.developerTools` | Pass it to keep them; "Copy view link" lives in the drawer. |
78
+ | behaviour | The viewer styled `html`, `body` and `#app` | The viewer styles only its own root | Size the element you mount into. A full-page viewer needs `html, body, #app { height: 100%; margin: 0 }` and your own background. |
79
+ | behaviour | Viewer element ids were fixed | Ids are generated per viewer | Do not select viewer parts by id. |
80
+ | behaviour | The viewer faded a page element `#boot` | It fades only a cover its host hands it | Remove your own `#boot` yourself. |
81
+ | behaviour | Escape closed the viewer's panels from anywhere | Only inside that viewer or on the bare page | Call the handle yourself if your own input relied on it. |
82
+ | behaviour | Any viewer drew pictures another had loaded | A viewer draws only the `data` passed to it | Pass `astraeus-data` to each viewer that shows pictures. |
83
+ | behaviour | A pacing `near` rule slowed every view | It slows only at the showing view's events | Add the events to each view that should slow. A scene without views is unchanged. |
84
+ | behaviour | A throwing listener stopped the rest | The rest run; the error goes to `reportError` | Remove any `try`/`catch` kept only to protect other listeners. |
85
+ | behaviour | `astraeus-data*` peers took any `0.x` engine | Each peers on the engine's own minor | Install every `astraeus-data*` package at the engine's version. |
86
+
87
+ `EventZoneChange` is new since 0.7.0 and carries `timeUtcMs` from the start, as do `SelectionChange` and the reads; the step entries list everything else that is new, none of which needs action.
88
+
89
+ #### Note for the Voyagers app (on 0.7.0)
90
+
91
+ - `src/scene.ts`: `camera.lookAt` becomes `camera.focus`; pass `labelReachEarthRadii` to `addBody`; `PACING` maps `data/pacing.json` onto `{ start, end, rate, rampSeconds }` and `{ near: { type, withinSeconds }, rate }`.
92
+ - `src/voyagers.ts`: `view()` gives one `objects` list in place of `paths` and `bodies`.
93
+ - `src/data/enginePlanets.ts`: `await scene.toDefinition([]).prepare?.()` becomes `await scene.load()`. Test set-ups use `await scene.load({ data: DATA })`.
94
+ - Tests: `toDefinition(DATA)` as a check becomes `scene.check({ data: DATA })`; `composition.bodies` is `scene.bodies`; `trackedBodies` is `scene.paths`; `scaleChoices` is `scene.scales`; `views.views` and `views.start` are `scene.views.items` and `scene.views.startId`; `def.paths` ending `-orbit` is `scene.bodies.filter((body) => body.orbit)`; `scene.camera.reach` is `scene.camera.reachEarthRadii`.
95
+ - What each view shows (`view.objects`, `view.events` in `src/voyagers.test.ts`) is `scene.views.items[i].objects`, `.events` and `.panels` (I-146): the ids the viewer shows, so a shared body that no view names is in every list. Replace the `Set` reads with these lists (`toEqual([...])` or `.includes(id)`).
96
+ - `src/main.ts` keeps the view in the address itself, so it needs no `address` option. `src/style.css` already sizes `html` and `body`; check `#viewer` has its own height.
97
+
98
+ #### Note for the showers app (on 0.2.0)
99
+
100
+ This app also crosses 0.3.0 to 0.7.0, so read those sections too.
101
+
102
+ - Swift-Tuttle: `addBody("swift-tuttle")` now fails. Copy the `parentElements` record from `packages/astraeus-demo-showers/data/showers/perseids.json` in this repository into a new `data/parents/109p-swift-tuttle.json`, and change the Perseids row of `data/parents/associations.json` from `{ "bodyId": "swift-tuttle" }` to `{ "file": "data/parents/109p-swift-tuttle.json" }`. `buildShowerScene` then adds it through `scene.addBodyFromElements`, as it does the other parents; the Astraeus demo proved the positions identical to the old built-in body over 1990 to 2030. `cataloguedParent` in `tests/parentAssociations.test.ts` no longer applies to it.
103
+ - Records: in `data/parents/*.json` and `parentElements` in `data/showers/*.json`, `frame` becomes `plane`, and `validFromUtc` and `validToUtc` become `accuracy.valid: { start, end }`. `src/showers/showerSettings.ts` and `tests/parentRecords.test.ts` follow.
104
+ - Panels: `panelsOf` in `src/showers/showerScene.ts` passes the old object. Pass its `panels` list to `addStoryPanels`, and `pauseSeconds` and `autoOpen` to `setStoryPanelPlayback`. In `data/stories/*/panels.json`, `badge` and `sources` move into `provenance`, `at.utc` becomes `at.time`, and each panel needs `accuracy` and `notes` stated from its source, or "Not stated by the source."
105
+ - Scene: `camera.lookAt` becomes `camera.focus`, and `streamOf` states `plane: "ecliptic-j2000"`, the old default.
106
+ - Tests: `toDefinition()` as a check becomes `scene.check()`; `composition.bodies` is `scene.bodies`; `clock.startUtcMs` is `scene.timeline.openUtcMs`; `experience.events` and `eventProvenance` are `scene.events`; `experience.objects` is `scene.bodies`, with `scene.provenanceOf(id)` for provenance; `groups[0].object` and `groups[0].group` are `scene.groups[0]`; `experience.storyPanels.panels` is `scene.panels`; `camera.far` is `scene.camera.farEarthRadii`, or `scene.camera.reachEarthRadii * 2.5` when none was given; `scene.camera.reach` is `scene.camera.reachEarthRadii`.
107
+ - `src/site/page.ts`: size `.viewer-host` yourself, and pass `address: true` only if the site wants the viewer's address parameters.
108
+
109
+ Changed (O-057 T-280, I-147, I-148, G-016, breaking before 0.8.0): `TextureRef.desktop.minViewportWidth` is refused with `renamed` naming `minViewportWidthPx`, in a `pictures` entry of a data source, like the other old input names. The checks a data source needs no loading for (a picture without rights or with an old name, moon positions with an old name or a planet with no moon system) now run at `scene.check` as well as `load` and `mount`, so `check` throws what `mount` would.
110
+
111
+ Changed (O-057 T-280, I-145, G-016, breaking before 0.8.0): a repeated event id throws `duplicate-id`, inside one `addEvents` call or across calls, like every other `add*` call (it threw `bad-event`).
112
+
113
+ Changed (O-057 T-279, G-016, breaking before 0.8.0): the catalogue holds only the Sun, the planets, Pluto and the moons. Comet 109P/Swift-Tuttle is no longer built in: `scene.addBody("swift-tuttle")` throws `unknown-body`, like any id the catalogue does not hold, and the `renamed` code is not used because the body is not renamed but gone. Add a comet or asteroid with `scene.addBodyFromElements(record)`; the Showers demo does this for Swift-Tuttle from its Perseids settings file, with positions identical to the old built-in body (the largest difference over 285 dates from 1990 to 2030 is 0 km). The engine no longer exports `SWIFT_TUTTLE` or `SWIFT_TUTTLE_SAMPLING` from its body index, and the whole-orbit line of a body now comes only from its own source or its record's sampling (no body is drawn by name).
114
+
115
+ Changed (O-057 T-278, G-016, breaking before 0.8.0): story panels are typed, checked at the call and honest about their sources. `addStoryPanels(list)` takes a list of `StoryPanelInput` and appends: a bad shape throws `bad-panels` at the call naming the panel and field, a repeated id throws `duplicate-id`, and links to events, anchors and objects are still checked at `check` and `mount`. `provenance` (`{ sourceType, sources, accuracy, notes }`) replaces `badge` and `sources`, with no second way: the badge shows the word for `sourceType`, so it can also read Ephemeris or Reconstructed, and the folded section shows the accuracy and notes above the sources. `at.utc` is `at.time`, a `TimeInput`, so text without a Z, a `Date` and Unix milliseconds all work. `pauseSeconds` and `autoOpen` move to `scene.setStoryPanelPlayback({ pauseSeconds, autoOpen })`, which replaces the whole setting. `scene.panels` carries `provenance` in place of `badge` and `sources`. `StoryPanelsInput` is gone; `StoryPanelInput`, `StoryPanelAt` and `StoryPanelPlaybackInput` are exported. A plain JavaScript caller who passes `badge`, `sources`, `at.utc` or the old `{ panels, pauseSeconds, autoOpen }` object gets `renamed`, naming the replacement.
116
+
117
+ Changed (O-057 T-277, G-016, breaking before 0.8.0): what the viewer reports carries its unit, and orbit records say `plane`. `ViewerHandle.time`, `ViewerChange.time` and `EventZoneChange.time` are `timeUtcMs` (Unix milliseconds UTC), on `mount` and on `<AstraeusScene>` (`ref`, `onReady`, `onChange`, `onEventZone`); the React `time` prop and `setTime` are inputs and keep their names. `ElementsBodyRecord.frame` is `plane`, and `accuracy.validFromUtc` and `accuracy.validToUtc` become `accuracy.valid: { start, end }` (ISO text as before, or a `Date` or milliseconds). `addBodyFromElements` and `parseElementsBodyRecord` refuse the old names, naming the replacement (`renamed`, or `bad-element` from the parser). `State.frame` and `CenteredPosition.frame`, which `scene.stateOf` returns, are `plane` (the value is still `"EQJ"`), and `TextureRef.desktop.minViewportWidth` is `minViewportWidthPx` (CSS pixels, compared with `window.innerWidth`). See the migration table above.
118
+
119
+ Changed (O-057 T-276, G-016, breaking before 0.8.0): the names a caller gives follow one rule (API-04: the unit in the name, `center`, spans as `{ start, end }`), and the old names are removed, not aliased. `MoonPositions.centre` is `center`, and `loadIndex` returns a `MoonIndex` (new type export) instead of `unknown`, in the engine and all six `astraeus-data-*` packages. Pacing is `{ start, end, rate, rampSeconds }` and `{ near: { type, withinSeconds }, rate, rampSeconds }`. `camera.lookAt` is `camera.focus`. A view lists one `objects` list in place of `paths` and `bodies` (a body, group or path id; `events` and `panels` stay). `labelReach` is `labelReachEarthRadii` on `addBody` and `addTrajectory`, and the `camera.reach` read is `camera.reachEarthRadii` (`setReach` keeps its name). `plane` is required on `addGroup`: a group without one throws `bad-group`, where it once defaulted to `"ecliptic-j2000"`. A plain JavaScript caller who still passes an old input name gets a `SceneError` with the new code `renamed`, whose message names the replacement; see the migration table above.
120
+
121
+ Changed (O-057 T-274, G-016, breaking before 0.8.0): the scene's internal output leaves the public API. `Scene.toDefinition()` and `Scene.missingData()` are removed (use `scene.check({ data })`, `await scene.load({ data })` and the reads `scene.bodies`, `paths`, `groups`, `bodySets`, `events`, `panels`, `views`, `timeline`, `activities`); `SceneCamera` is now exported as a type only (reach it as `scene.camera`; it can no longer be built by a host); `RateSource` is no longer exported (it was only the type of an internal field of the viewer's link). Added: `scene.activities`, a fresh frozen list per `addActivity` of `{ id, label, unit, windowStartUtcMs, windowEndUtcMs, peak: { label, value, timeUtcMs? }, samples, provenance?, type? }` (type `SceneActivityRead`).
122
+
123
+ Added (O-057 T-275, G-016): the root names every type a host can reach. New type exports: `BodyId`, `DisplaySwitchId`, `DisplaySwitchPlace`, `ViewPlace`, `ViewerChangeCause`, `LineStretchInput` and `TrajectoryBase` (the fields shared by the `TrajectoryInput` variants), and the types behind already-named ones: `CenteredPosition`, `Quaternion`, `FrameId`, `CenterId`, `ElementsSource`, `ElementsTimeScale`, `LocalOnlyDeclaration`, `PublicReplacement`, `SolarSystemScalePolicy`. Types only; nothing existing changes.
124
+
125
+ O-059 (G-016) moves the planets demo and the site onto the public API. The new public parts below (T-266 to T-269) are what they needed, each general and with a default; T-265 and T-270 to T-272 are not API entries: the place lists moved to `astraeus-data`, the moon lists and fit errors to `astraeus-data-<planet>`, and the private `App` props, definition `switcher` and boot-cover code were deleted, none of which was public.
126
+
127
+ Added (O-059 T-269, G-016): a picker an app offers in the viewer's top bar and phone drawer, and a signal for what the visitor picks. `scene.setPicker({ id, label, options, value })` (`PickerInput`, options `{ value, label }` as `PickerOptionInput`; fewer than two options draw nothing) and the read `scene.picker`; on the handle, the same from `mount` and `AstraeusScene`, `handle.pick` (the pressed option's value), `handle.setPick(value)` (moves it, no signal) and `handle.onPick(fn)` (`fn({ picker, value })`, a `PickChange`, when a visitor presses an option other than the pressed one), and the `onPick` prop of `AstraeusScene`. The viewer only reports the press: it never navigates, reads or writes the page address, or keeps a time, and the pressed option stays until the host calls `setPick` or builds a new scene; a host keeps the clock across a choice by reading `handle.timeUtcMs` in `onPick` and calling `setTime` on the next scene. New error code `bad-picker` (a malformed picker, an unknown `setPick` value, or `setPick` on a scene without a picker). Nothing existing changes.
128
+
129
+ Added (O-059 T-268, G-016): `scene.setMoonPanel({ label, families, featuredFamily?, listSource?, listDate? })` shows the sliding moon panel (families of `{ id, label, description, moons }`, a moon being `{ id, named? }`, a body or body-set member of the scene; pictures come from the viewer's `data`), `scene.addPlaces(body, { categories, places, provenance, knownLimitations? })` draws tagged surface places on a body (`PlaceInput`: `id`, `name`, `kind`, `category`, `latitudeDeg`, `longitudeDeg`, `description`, `details?`). New reads `scene.moonPanel` (`count`, `summary`) and `scene.places` (`body`, `count`), new error codes `bad-moon-panel` and `bad-places`, and the types `MoonPanelInput`, `MoonPanelFamilyInput`, `MoonPanelMoonInput`, `PlacesInput`, `PlaceInput`, `PlaceCategoryInput`, `SceneMoonPanelRead` and `ScenePlacesRead`. The place lists of 24 bodies moved from the engine's `data/bodies/` to `astraeus-data` (`astraeus-data/bodies/<body>/...`), published for the first time with a NOTICE line.
130
+
131
+ Added (O-059 T-267, G-016): `scene.addBodySet(input)` draws many small bodies about one centre as one batch (dots with a pixel floor, a ball at true size close up, names on hover, tap or near zoom, orbit lines coloured by family), each member selectable with an info card. `BodySetInput`: `id`, `center?`, `families` (one to sixteen of `{ id, label, color?, brightness? }`), `members`, `bodies?` (bodies added with `addBody` that belong to a family; one with no `orbit` of its own gets its line in the batch), `provenance`, `centerGmKm3S2?`, `balancePoint?` (`{ body, gmKm3S2 }`) and `orbitHistoryMs?` (default 0; asks the moon loader for that much before the window). A member is a listed moon of the centre (no `elements`; positions come through `data`, label and radius default to the list's) or a made-up one on two-body motion (`elements` with `time?` and `plane?`; `label` and `radiusKm` required); a set is one kind or the other. Members take `description`, `facts`, `provenance`, `knownLimitations` and `listed` (default false) as `addBody` does. New read `scene.bodySets` (`id`, `center`, `count`, `families`), new error code `bad-body-set`, and the new types `BodySetInput`, `BodySetFamilyInput`, `BodySetMemberInput`, `BodySetElementsInput`, `BodySetBodyInput`, `BodySetBalanceInput` and `SceneBodySetRead`. `stateOf` and `provenanceOf` accept member ids, story panels may name them, `scene.check`, `scene.load` and `scene.missingData` count them, and a view cannot name a set or a member (`bad-view`). Nothing existing changes.
132
+
133
+ Added (O-059 T-266, G-016): the small public settings the planets demo and the site need, each with a default and a test on a made-up scene. `addBody` options `listed` (default true; false leaves the body out of the object menu), `facts` (`CardFactInput` rows `{ label, value }` for the info card; none), `sources` (added after the body's own provenance sources, also in `scene.provenanceOf`; none) and `labelPriority` (default `100 - index`); `orbit` also takes `{ lapDays, fades? }` (`OrbitLapInput`) to draw a moon's line from a lap you state, which works for moons with no period on record such as `phobos` and `deimos`; `scene.setBodyReadouts(kinds)` (`BodyReadoutKind`: `"distance"`, `"phase"`, `"coordinates"`; default `["distance"]`); `scene.camera.setReach(distance, { farEarthRadii })` (the far plane; default 2.5 times `distance`), `scene.camera.setStartView(pose)` (opens at a pose with no camera button pressed; the last of `follow`, `lookAt` and `setStartView` wins) and `scene.camera.setFollowChoices(ids)` (which objects offer Follow; default all); `LookInput.desktopPictures` and `LookRead.desktopPictures` (default false; read when the viewer is built; page address `?desktop=on|off`); `scene.bodies` items gain `listed`, `facts?` and `texture?` (the engine's picture and licence for the body); `handle.onFirstDraw(listener)` and the `onFirstDraw` prop of `AstraeusScene` (called once when the scene's first frame is drawn, and again after a rebuild). The scene centre needs no setting: it is the first body added. Removed (internal, not public): the experience definition's `alternates` and `developerSections` fields and the Developer drawer's Data group and "This demo" group; nothing set them any more. API-04: the type lint no longer reads a listener named `on...` as a coordinate-frame field, so `onFirstDraw` is not a `frame` break.
134
+
135
+ Added (O-056 T-264, G-016): a third example, `examples/hello-planets` (repository only, not in the package): the Sun, Mercury, Venus, Earth and Mars on plain `mount` with orbit lines, `scene.camera.fitOrbit`, `scene.setLook`, a distance-from-the-Sun readout on Earth, and a page with its own sliders (star brightness, Sun glow brightness and size) and scale button driving `handle.setLook` and `handle.setScale`. It installs the packed engine only, so it has no Milky Way slider (the picture comes from `astraeus-data`). No change to the public API in this step.
136
+
137
+ Added (O-056 T-263, G-016): an event can carry its own zone. `EventInput.withinSeconds` (positive, finite simulated seconds; else `bad-event` naming the event) gives the event a zone of `time ± withinSeconds`. `onEventZone` and `eventZones` report every event zone, from `withinSeconds` or from a pacing `near` rule, in a scene with no pacing at all (`via` and the showing view's filter are unchanged). A pacing rule uses each matching event's own `withinSeconds` where it has one and its own `within` otherwise. `scene.events` reads `withinSeconds` back. Pacing input names are unchanged.
138
+
139
+ Added (O-056 T-262, G-016): a running viewer's looks, scale and display switches are read and set from the handle, the same from `mount` and `AstraeusScene`: `handle.look` (every look filled in) and `handle.setLook(look)` (replaces the whole look; a live set wins over the page address), `handle.scale` and `handle.setScale(id)` (one of `scene.scales`; else `bad-scale`), `handle.switches` and `handle.setSwitch(id, on)` (a switch placed with `setSwitches`; else `bad-switch`). `onChange` now also carries `scale`, `look` and, when the scene placed switches, `switches`, and hears these changes with cause `host` (a visitor's scale button, switch or Developer drawer slider reports `visitor`); new public types `LookRead`. `addBody(x, { readouts })` takes the same readout list a path takes and draws it on the body's info card (replacing the catalogue's own distance rows); a named body the scene does not hold throws `bad-readout`. Internal: `skyVisible` is now live (the sky is always built and hidden by `skyVisible`). The default look is unchanged.
140
+
141
+ Added (O-056 T-261, G-016): `scene.setLook(look)` and the `LookInput` type make every look a public setting with a default: `starBrightness`, `milkyWay`, `milkyWayBrightness`, `skyVisible`, `sunGlow` (`sizePx`, `brightness`, `scale`), `markerSwapRadiusPx`, `featureMinBodyPx` and `loadFadeSeconds` (units and ranges in the README). Before, these were reachable only through the page address or the Developer drawer. A bad look throws the new `SceneError` code `bad-look`. The page address, when the viewer's `address` option is on, still overrides the look it names. Behaviour change: `?loadfade=` with a value that is not a number now falls through to the saved setting or the default instead of always using the default. The default look is unchanged.
142
+
143
+ Added (O-056 T-260, G-016): a scene says what it holds in plain read-only properties, so tests need not call `toDefinition` (removed in 0.8.0, O-057). `scene.bodies` (`id`, `label`, `parent?`, `orbit`, `enlarge`, `description?`, `knownLimitations`), `scene.paths` (`id`, `label`, `center`, `provenance`, `description?`, `knownLimitations`), `scene.groups` (`id`, `label`, `count`, `center`, `plane`, `provenance`, `description`, `knownLimitations`), `scene.events` (`id`, `label`, `timeUtcMs`, `type?`, `object?`, `provenance?`), `scene.panels` (`id`, `timeUtcMs`, `title`, `body`, `badge`, `details`, `sources`, `object?`), `scene.views` (`startId`, `place`, `items`; undefined when none), `scene.scales` (ids, opening scale first) and `scene.timeline` (`windowStartUtcMs`, `windowEndUtcMs`, `openUtcMs`, `rates`, `rate`, `loop`). Each is a frozen list or object built from the scene's own plans, fresh on every read, and answers on a scene a viewer has taken. New public types: `SceneBodyRead`, `ScenePathRead`, `SceneGroupRead`, `SceneEventRead`, `ScenePanelRead`, `SceneViewRead`, `SceneViewsRead`, `SceneTimelineRead`. `scene.panels` and `scene.timeline` throw `bad-panels` and `bad-timeline` for the faults `mount` would throw for. What replaces each `toDefinition` read is in the migration table above.
144
+
145
+ Added (O-056 T-259, G-016): numbers without a viewer. `scene.load({ data })` loads the planet series and, for each moon the scene holds, the chunks its data package provides for the scene's window, so a Node or server app can `await scene.load({ data })` and then call `stateOf` and `provenanceOf` for any body, moons included (it rejects with `missing-data` or `out-of-span` as `mount`'s `ready` does; harmless twice; allowed on a mounted scene; a later `mount` re-uses what it loaded). `scene.check({ data })` runs the checks `mount` runs before it draws and throws the same `SceneError`, loading and freezing nothing. `stateOf` on a planet or fitted moon before its data is loaded still throws `missing-data`, and the message now names `scene.load` instead of an internal function. New type `SceneLoadOptions`. Moon chunks given as `file:` addresses (a data package's `dataSource` in plain Node) are now read from disk, as Node's `fetch` cannot. Migration: none; nothing existing changes.
146
+
147
+ Upgrading from 0.7.0, O-055 (G-016) makes the viewer a good guest on any page, and several can share one. Migration for app makers, beside O-054's below: (1) the viewer no longer styles `html`, `body` or `#app`; size the element you mount into yourself (a full-page viewer needs `html, body, #app { height: 100%; margin: 0 }` and your own background). (2) The Developer drawer is hidden unless you pass `developerTools: true` (`mount`) or `developerTools` (React), and the "Copy view link" button lives in it. (3) Element ids are generated per viewer; do not select viewer parts by id. (4) A viewer draws pictures only from the data packages passed to it. (5) Moon data now loads for every scene of a planet on the page. The per-step lines stay below.
148
+
149
+ Changed (O-055 T-256): the viewer's main stylesheets no longer style the host page. `app/style.css` used to set a font, colour, background and `height: 100%` on `:root`, `html`, `body` and `#app`, and `position: relative; overflow: hidden` on `#app`; every rule in it and in `shell/style.css` now sits under the viewer's root class `.astraeus-shell`, which also carries the custom properties (`--ui-*`, `--perf-*`), `color-scheme`, the base font and the black background. `mount` and `<AstraeusScene>` make their own element a containing block (`position: relative` if it is static, `overflow: hidden` if it is visible; a position or overflow you set is kept), so the viewer fills that element and not the page. Migration: give the element you mount into a size yourself (for a full-page viewer, `html, body, #app { height: 100%; margin: 0 }` and your own background); the viewer no longer sets them, and a page that relied on its `html`, `body` or `#app` font, colour or `height: 100%` must now say so. The public API surface is unchanged.
150
+
151
+ Fixed (O-055 T-255): the viewer no longer touches page elements outside its own. It used to look up a page element `#boot` and fade or remove it on the first frame; now it fades only a loading cover its host hands it (the demo site does; `mount` and `<AstraeusScene>` take none, so your own `#boot` is left alone). Escape closes a viewer's drawer, story panel or switch panel only when pressed inside that viewer or on the bare page (body), not in the other viewer or in your own controls; and the tagged-place markers measure only their own viewer's panels. Migration: none for `mount` and `<AstraeusScene>` users; a page with one viewer behaves as before, but a host that relied on Escape in its own input closing the viewer's panels must call the handle itself.
152
+
153
+ Changed (O-055 T-253): the Developer cog and drawer are hidden unless the host asks. `mount` takes `developerTools?: boolean` and `<AstraeusScene>` takes a `developerTools` prop (both default false, read when the viewer is built). Off, the viewer draws no Developer toggle or drawer and never fetches the drawer's code; on, the drawer is as before (the demo site turns it on). "Copy view link" lives in the drawer, so `address: true` without `developerTools` reads the address but has no copy button, and a switch placed `"developer"` shows only when the option is on (with it off it is simply not shown). Migration: an app that relied on the cog passes `developerTools: true` (`mount`) or `developerTools` (React); an outside page that never wanted it changes nothing.
154
+
155
+ Fixed (O-055 T-252): a viewer draws only the pictures of the data packages passed to it. The pictures (`astraeus-data`: moon maps, the 8k Venus map, the Milky Way) used to sit in one page-wide book that any viewer's `data` filled, so a second viewer given no pictures still drew the first one's; each viewer now holds its own, and a body whose picture was not passed to it is a flat colour and its sky has no Milky Way picture, as before. Migration: none for `mount` or `<AstraeusScene data>`; the removed `registerPictures` and `pictureOf` were never on the front door. A host that builds a definition by hand sets `pictures` on it.
156
+
157
+ Fixed (O-055 T-251): a planet's moon data loads for every scene on a page. A second scene, a rebuild with a new `scene` or a remount used to get no moons when an earlier scene of the same planet had loaded first; each load now fetches the chunks its own window, history and year-after need that are not yet held (a chunk is fetched once), and a window outside a moon's years still refuses with `out-of-span`. No migration: nothing to change in an app.
158
+
159
+ Upgrading from 0.7.0, O-054 (G-016) makes the plain and React paths one handle and tightens its lifecycle; the entries below give the detail. Migration for app makers: (1) handle calls made before `ready` or after `unmount` throw `not-mounted` (they threw `missing-data`, which now means only missing data packages), and `ready` rejects with `not-mounted` when `unmount` comes first, so handle or ignore that rejection; listener registration (`onChange`, `onEventZone` and the other `on*`) never throws and its listeners get nothing after `unmount`. (2) In React, `onReady` receives the `ViewerHandle` and the new `ref` prop gives the same handle; read and set through it. (3) A repeated `addActivity` id throws `duplicate-id` (was `bad-activity`), and a data package whose moon positions name a planet without a moon system throws `bad-data` (was a `RangeError`). (4) Once mounted, a `Scene` is frozen: any `add*`, `set*` or `scene.camera` edit throws `scene-mounted`, so build a new `Scene` for changes (the same scene may be mounted again). (5) A listener that throws no longer stops the others; it is reported with `reportError` after the rest have run. New: `playing` and `setPlaying(boolean)` (`bad-timeline` without a play control), `selected` and `onSelect`, `onCameraChange`. `examples/hello-react` now puts the camera back after an encounter through the handle.
160
+
161
+ Upgrading from 0.7.0, two behaviours change: the viewer no longer reads or writes the page address unless you pass `address: true` (T-223), and a `pacing` event rule in a scene with views slows playback only at the showing view's events (T-224). The O-054 changes are listed in the next paragraph; the other entries below only add.
162
+
163
+ First download of the packed example (`npm run measure:example`, `examples/hello-scene`, which now also carries two probes, three views, pacing and the camera-to-the-encounter host code): 1,659,659 bytes raw, 478,702 bytes gzip (code and styles loaded on first open), against 1,652,632 raw and 472,929 gzip at 0.7.0 (+7,027 raw, +5,773 gzip, most of it the new host API surface and the longer example).
164
+
165
+ - The host can hear the camera move (O-054 T-248, G-016). `ViewerHandle` (from `mount` and from `AstraeusScene` `ref` and `onReady`) gains `onCameraChange(listener)`, which calls `listener(pose)` with the `CameraPose` (`{ focus, azimuthDeg, elevationDeg, distance }`, as `camera` reads it) only when it differs from the last report, at most about ten times a second (the opening pose is read, not reported), and returns a stop function. Migration: in an app built on 0.7.0, replace any polling of `handle.camera` on a timer with `handle.onCameraChange(...)`; nothing else changes.
166
+ - The host can read which object is selected and hear when it changes (O-054 T-247, G-016). `ViewerHandle` (from `mount` and from `AstraeusScene` `ref` and `onReady`) gains `selected` (the id of the object whose information is open; undefined before `ready`, after `unmount` and when nothing is selected) and `onSelect(listener)`, which calls `listener({ object?, timeUtcMs, cause })` only when the selection differs from the last report (the opening selection is read, not reported) and returns a stop function; the new type `SelectionChange` is exported. Read only: no setter. Migration: in an app built on 0.7.0, replace any reading of the viewer's object menu or a poll of the page for the selected object with `handle.selected` and `handle.onSelect(...)`; nothing else changes.
167
+ - The host can pause and play the viewer (O-054 T-246, G-016). `ViewerHandle` (from `mount` and from `AstraeusScene` `ref` and `onReady`) gains `playing` (undefined before `ready` and after `unmount`) and `setPlaying(boolean)`, which goes through the visitor's own play handler (one clock); `onChange` hears it with `cause: "host"`. A non-boolean, or a scene with `setTimeline({ none: true })` (no play control), throws `bad-timeline`; before `ready` or after `unmount`, `not-mounted`. Migration: in an app built on 0.7.0, replace any click on the play button or `rate` workaround for pausing with `handle.setPlaying(false)` and read `handle.playing`; nothing else changes.
168
+ - A scene is frozen once a viewer takes it (O-054 T-245, G-016). After `mount(element, scene)` or an `<AstraeusScene scene>` build, every `add*`, `set*` and `scene.camera` edit (`follow`, `lookAt`, `setReach`, `fitOrbit`) throws the new `SceneErrorCode` `scene-mounted` instead of being silently ignored; `stateOf`, `provenanceOf`, `missingData` and the camera getters still answer, and the same scene can be mounted again, also into a second element. A build that fails (an empty scene, a missing data package) leaves the scene editable, and `toDefinition` on its own does not freeze. Migration: in an app built on 0.7.0, build a new `Scene` instead of editing one already mounted, and pass it as the new `scene` prop or mount it again.
169
+ - One throwing listener no longer silences the others (O-054 T-244, G-016). `onChange` and `onEventZone` listeners (the handle's, the scene option and the React props) are all called through one helper: a listener that throws is reported to the page with `reportError` (else rethrown on a timer) after the rest have run. Migration: none needed; in an app built on 0.7.0, an error thrown in one listener now shows up as a page error instead of cutting off later listeners, so remove any try/catch kept only to protect them.
170
+ - Package ranges now state what was tested (O-053 T-230, G-016). The engine's `react` and `react-dom` peers are `>=19 <20` (all of React 19; they stopped at `<19.4`), checked by installing the latest React 19.x into the packed engine (`npm run check:react-consumer`). Each `astraeus-data*` package's `astraeus` peer is the engine's current minor, `>=0.7.0 <0.8.0` today, instead of `>=0.1.0 <1.0.0`. The engine now exports `./package.json`, as the data packages already did.
171
+ - Every `SceneErrorCode` now carries a doc comment that says what it means (O-053 T-229, G-016); the README error table is generated from them (`npm run api:errors`). The set of codes is unchanged; only the comments in the lock's `SceneErrorCode` signature differ.
172
+ - React apps get the same handle as `mount` (O-054 T-242, G-016). `AstraeusScene` takes a React 19 `ref` prop that receives the `ViewerHandle` (one object for the component's life, also across a rebuild with a new `scene`; reads `undefined` and calls throw `not-mounted` until drawn and after unmount), and `onReady` now receives that handle. `onReady` under React StrictMode fires once per build, after the viewer has attached (before, the replayed effect closed the link for good and it never fired); the `camera` prop is compared by value whatever the key order of a pose. `mount` and `AstraeusScene` build the handle with one shared helper. Migration: in an app built on 0.7.0, read and set through the handle from `ref` or `onReady(handle)` (the props stay as shortcuts); an `onReady` that took no argument keeps working.
173
+ - The mount handle has one shared type and an honest error before and after use (O-054 T-241, G-016). New exported type `ViewerHandle` holds every read, setter and signal of the handle; `MountedScene` is `ViewerHandle` plus `ready` and `unmount`. New `SceneErrorCode` `not-mounted`: any handle call before `ready` or after `unmount` throws it (was `missing-data`, which now means only missing data packages), and `ready` now rejects with it when `unmount` comes before the viewer is drawn (it used to stay pending or resolve unusable). Migration: in an app built on 0.7.0, catch `not-mounted` instead of `missing-data` for handle calls made before `ready` or after `unmount`, and handle (or ignore) a rejected `ready` after an early `unmount`.
174
+ - Errors follow one rule (O-054 T-240, G-016). A repeated `addActivity` id now throws `duplicate-id` (was `bad-activity`), like every other repeated id; a data package whose moon positions name a planet without a moon system now throws `SceneError("bad-data")` (new code; was a `RangeError`); a `lineFixedTo` stretch with no body is a `bad-trajectory` `SceneError` throughout; the sun-orbit code recognises its two internal range faults by named error classes (still `RangeError` subclasses) instead of by message text. Migration: an app that catches `bad-activity` for a repeated activity id should catch `duplicate-id`, and one that catches a `RangeError` from a bad data package should catch `SceneError` code `bad-data`.
175
+ - The host hears when playback enters and leaves a flyby (O-052 T-226, G-015). New `MountedScene.onEventZone(listener)` and `AstraeusScene` prop `onEventZone` call `listener({ event, type?, object?, entered, time, cause, via })` (`via` is `"time"` for playback or a seek and `"view"` for a view switch that showed or hid the zone, so a host restores a camera only for `"time"`) as playback crosses, or a seek or view switch moves across, the zone of a pacing `near` rule for an event the showing view has (`cause` `playback`, `visitor` or `host`); `MountedScene.eventZones` reads the active event ids. A zone already active when the viewer opens reports `entered` once after `ready`. New exported type `EventZoneChange`. The engine builds in no camera behaviour: the README's "camera to the encounter" example composes `onEventZone` with `setCamera` and `camera`. No new event field and no pacing option.
176
+ - The host can point the camera and read its pose (O-052 T-225, G-015). `MountedScene.setCamera(target)` and the `AstraeusScene` `camera` prop take `{ follow: id }`, `{ focus: id }` or a pose; `MountedScene.camera` (defined from `ready` on) reads the camera as a plain `{ focus, azimuthDeg, elevationDeg, distance }` value (the pose a view link carries), and `setCamera(handle.camera)` restores it. 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` `missing-data`. New exported types `CameraPose` and `CameraTarget`. The engine moves no camera on its own.
177
+ - Pacing follows views (O-052 T-224, G-015): in a scene with `setViews`, a `pacing` event rule `{ near: { type, within }, rate }` now slows playback only near the events the showing view has; in 0.7.0 every view slowed at every event of the type. Spans apply in every view. A view switch that changes the paced speed eases to the new speed over about a second (log space, reported by `onChange` with `cause: "playback"`); seeking lands on the paced speed at once, and a speed the visitor or host picked still wins until `"auto"`. A scene without views is unchanged.
178
+ - The viewer leaves the page address alone unless asked (O-052 T-223, G-015). New `address` option on `mount` (`MountOptions.address`) and `AstraeusScene` (`address` prop), default `false`: off, the viewer reads no address parameter (`view`, `t`, `scale`, `up`, `show`, `stars`, `milkyway`, `milkywaybrightness`, `sky`, `labels`, `loop`, `markerpx`, `featurepx`, `sunglow`, `sunbrightness`, `sunglowscale`, `loadfade`), never calls `history.replaceState`, and hides the Developer tools' "Copy view link" button. Behaviour change from 0.7.0, which read and wrote the address regardless; pass `address: true` for it (the demo site does). With it on, a copied link in a scene with views also writes `show=<view id>`, and opening it shows that view (an unknown id opens the scene's `start` view). The README's new "Page address" section lists every parameter. A new test fails if source outside `src/app/address.ts` reads the address.
179
+ - `ready` means usable (O-052 T-222, G-015): `mount`'s `ready` resolves, and `AstraeusScene`'s `onReady` fires, only once the viewer has attached its clock, so `time`, `rate`, `view`, `setTime`, `setRate` and `setView` work straight after `await ready`. In 0.7.0 `ready` resolved about two frames earlier and `await ready; setView(...)` threw `missing-data`. A load failure still rejects `ready`; `unmount` before the viewer is drawn never makes it usable. No change to the handle's shape or error codes.
180
+
5
181
  ## 0.7.0 (2026-11-01)
6
182
 
7
183
  First download of the packed example (`npm run measure:example`): 1,652,632 bytes raw, 472,929 bytes gzip (code and styles loaded on first open).