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
@@ -0,0 +1,4 @@
1
+ /** Freezes a scene: every later edit throws `scene-mounted`. Called once its definition is built. */
2
+ export declare function markMounted(scene: object): void;
3
+ /** Whether a viewer has taken the scene. */
4
+ export declare function isMounted(scene: object): boolean;
@@ -0,0 +1,10 @@
1
+ /** Scenes a viewer has taken. Kept outside `Scene` so the freeze adds nothing to the public surface. */
2
+ const mounted = new WeakSet();
3
+ /** Freezes a scene: every later edit throws `scene-mounted`. Called once its definition is built. */
4
+ export function markMounted(scene) {
5
+ mounted.add(scene);
6
+ }
7
+ /** Whether a viewer has taken the scene. */
8
+ export function isMounted(scene) {
9
+ return mounted.has(scene);
10
+ }
@@ -0,0 +1,171 @@
1
+ import type { BodyId } from "../core/body.js";
2
+ import type { Provenance } from "../core/provenance.js";
3
+ import type { TextureRef } from "../assets/licence.js";
4
+ /** A body the scene holds, as `Scene.bodies` lists it (in the order they were added; the first is the scene's centre). */
5
+ export interface SceneBodyRead {
6
+ readonly id: BodyId;
7
+ readonly label: string;
8
+ /** The body it circles in the catalogue (a planet's is the Sun, a moon's its planet); absent for the Sun. */
9
+ readonly parent?: BodyId;
10
+ /** Whether `addBody(..., { orbit: true })` asked for its orbit line. */
11
+ readonly orbit: boolean;
12
+ /** How many times larger than life it is drawn (`enlarge`); 1 when not enlarged. */
13
+ readonly enlarge: number;
14
+ /** The words on its info card: the `description` given to `addBody`, else absent. */
15
+ readonly description?: string;
16
+ /** The known limits on its info card: those given to `addBody`, else the catalogue's own. */
17
+ readonly knownLimitations: readonly string[];
18
+ /** Whether the object menu offers it (`listed`); true unless `addBody` said false. */
19
+ readonly listed: boolean;
20
+ /** The facts on its info card, as `addBody` gave them (`facts`); absent when none were given. */
21
+ readonly facts?: readonly {
22
+ readonly label: string;
23
+ readonly value: string;
24
+ }[];
25
+ /** The picture and licence the engine ships for the body (what a credits page lists); absent for a body drawn from a picture a data package brings, or from a flat colour. */
26
+ readonly texture?: TextureRef;
27
+ }
28
+ /** A path the scene holds (`addTrajectory`), as `Scene.paths` lists it. */
29
+ export interface ScenePathRead {
30
+ readonly id: string;
31
+ readonly label: string;
32
+ /** The body its positions are measured from. */
33
+ readonly center: BodyId;
34
+ readonly provenance: Provenance;
35
+ /** The words on its info card: those given to `addTrajectory`, else absent. */
36
+ readonly description?: string;
37
+ /** The known limits on its info card: those given to `addTrajectory`, else empty. */
38
+ readonly knownLimitations: readonly string[];
39
+ }
40
+ /** A group of listed orbits the scene holds (`addGroup`), as `Scene.groups` lists it. */
41
+ export interface SceneGroupRead {
42
+ readonly id: string;
43
+ readonly label: string;
44
+ /** How many orbits (dots) it draws. */
45
+ readonly count: number;
46
+ /** The body the orbits circle. */
47
+ readonly center: BodyId;
48
+ /** The plane the elements are given in. */
49
+ readonly plane: "ecliptic-j2000" | "EQJ";
50
+ /** The provenance its card shows: always illustrative, with the source's own type kept in the accuracy line. */
51
+ readonly provenance: Provenance;
52
+ /** The words on its info card: those given to `addGroup`, else a sentence stating the count. */
53
+ readonly description: string;
54
+ /** The known limits on its info card: those given, then the engine's own about the dots' placement and motion (and the clump, when set). */
55
+ readonly knownLimitations: readonly string[];
56
+ }
57
+ /** A body set the scene holds (`addBodySet`), as `Scene.bodySets` lists it. */
58
+ export interface SceneBodySetRead {
59
+ readonly id: string;
60
+ /** The body the members circle. */
61
+ readonly center: BodyId;
62
+ /** How many members (dots) it draws. */
63
+ /** How many members (dots) it draws. */
64
+ readonly count: number;
65
+ /** The ids of its families, in order. */
66
+ readonly families: readonly string[];
67
+ }
68
+ /** An activity the scene holds (`addActivity`), as `Scene.activities` lists it (in the order added). */
69
+ export interface SceneActivityRead {
70
+ readonly id: string;
71
+ readonly label: string;
72
+ /** What the rate counts, per unit of time, such as "events per hour". */
73
+ readonly unit: string;
74
+ /** The first and last moment of the activity, in UTC milliseconds. */
75
+ readonly windowStartUtcMs: number;
76
+ readonly windowEndUtcMs: number;
77
+ /** The peak mark on the rate bar: its name, the rate there (the curve's highest sample when no `peak` moment was given) and its moment in UTC milliseconds (absent when no `peak` was given). */
78
+ readonly peak: {
79
+ readonly label: string;
80
+ readonly value: number;
81
+ readonly timeUtcMs?: number;
82
+ };
83
+ /** The curve's points, sorted by time. */
84
+ readonly samples: readonly {
85
+ readonly timeUtcMs: number;
86
+ readonly value: number;
87
+ }[];
88
+ /** Where each stretch of the curve comes from; absent when none was stated. */
89
+ readonly provenance?: readonly {
90
+ readonly stretchStartUtcMs: number;
91
+ readonly stretchEndUtcMs: number;
92
+ readonly provenance: Provenance;
93
+ }[];
94
+ /** The free word given to `addActivity` (`type`); absent when none was given. */
95
+ readonly type?: string;
96
+ }
97
+ /** A timeline event the scene holds (`addEvents`), as `Scene.events` lists it (sorted by time). */
98
+ export interface SceneEventRead {
99
+ readonly id: string;
100
+ readonly label: string;
101
+ readonly timeUtcMs: number;
102
+ readonly type?: string;
103
+ /** The id of the body or path the event is about. */
104
+ readonly object?: string;
105
+ /** The half-width of the event's own zone in simulated seconds (`withinSeconds` of `addEvents`); absent when it has none. */
106
+ readonly withinSeconds?: number;
107
+ /** Where the event's time comes from: its own, else the batch's; absent when neither was given. */
108
+ readonly provenance?: Provenance;
109
+ }
110
+ /** A story panel the scene holds (`addStoryPanels`), as `Scene.panels` lists it (sorted by time, the times resolved). */
111
+ export interface ScenePanelRead {
112
+ readonly id: string;
113
+ readonly timeUtcMs: number;
114
+ readonly title: string;
115
+ /** Paragraphs, in order. */
116
+ readonly body: readonly string[];
117
+ /** Paragraphs of exact figures and measured-versus-reconstructed notes; empty when none. */
118
+ readonly details: readonly string[];
119
+ /** Where the panel's facts come from and how far to trust them, as given to `addStoryPanels`. */
120
+ readonly provenance: Provenance;
121
+ /** The id of the object the panel marks. */
122
+ readonly object?: string;
123
+ }
124
+ /** One named view of the scene (`setViews`). */
125
+ export interface SceneViewRead {
126
+ readonly id: string;
127
+ readonly label: string;
128
+ /** The ids of the bodies, groups and paths the view shows, as the viewer resolves them: the ones the view names plus every one no view names (those show in every view). In the order the scene holds them (paths, bodies, groups). */
129
+ readonly objects: readonly string[];
130
+ /** The ids of the events the view shows, resolved the same way (the view's own plus every event no view names), sorted by time. */
131
+ readonly events: readonly string[];
132
+ /** The ids of the story panels the view shows, resolved the same way (the view's own plus every panel no view names), sorted by time. */
133
+ readonly panels: readonly string[];
134
+ }
135
+ /** The views the scene names (`setViews`), as `Scene.views` states them. Reading it checks the view ids against the finished scene, as `mount` does: an id the scene does not hold, or a camera target the view hides, throws `bad-view`; a bad panel throws `bad-panels`. */
136
+ export interface SceneViewsRead {
137
+ /** The id of the opening view. */
138
+ readonly startId: string;
139
+ /** Where the view choice shows: "top-bar" or "panel". */
140
+ readonly place: "top-bar" | "panel";
141
+ readonly items: readonly SceneViewRead[];
142
+ }
143
+ /** The moon panel the scene holds (`setMoonPanel`), as `Scene.moonPanel` states it. */
144
+ export interface SceneMoonPanelRead {
145
+ /** How many moons the panel lists, in every family. */
146
+ readonly count: number;
147
+ /** The count with its source and date, such as "115 moons in the JPL Horizons list of 18 October 2026". */
148
+ readonly summary: string;
149
+ }
150
+ /** The tagged places a body holds (`addPlaces`), as `Scene.places` lists them. */
151
+ export interface ScenePlacesRead {
152
+ readonly body: BodyId;
153
+ readonly count: number;
154
+ }
155
+ /** The timeline the scene opens with, as `Scene.timeline` states it. */
156
+ export interface SceneTimelineRead {
157
+ /** Where the span the timeline covers begins, in UTC milliseconds. With nothing setting a span or a moment, a month about the moment of the read. */
158
+ readonly windowStartUtcMs: number;
159
+ /** Where that span ends, in UTC milliseconds. */
160
+ readonly windowEndUtcMs: number;
161
+ /** The moment the scene opens at, in UTC milliseconds. */
162
+ readonly openUtcMs: number;
163
+ /** The speeds the viewer offers, in simulated seconds per second. */
164
+ readonly rates: readonly number[];
165
+ /** The speed the scene opens at, in simulated seconds per second. */
166
+ readonly rate: number;
167
+ /** Whether playback wraps from the end to the start. */
168
+ readonly loop: boolean;
169
+ }
170
+ /** Freezes a list and each of its items, and returns it. */
171
+ export declare function frozenList<T extends object>(items: readonly T[]): readonly T[];
@@ -0,0 +1,6 @@
1
+ /** Freezes a list and each of its items, and returns it. */
2
+ export function frozenList(items) {
3
+ for (const item of items)
4
+ Object.freeze(item);
5
+ return Object.freeze([...items]);
6
+ }
@@ -1,10 +1,10 @@
1
1
  import { type TimelineEvent } from "../core/events.js";
2
- import type { Pacing } from "../core/pacing.js";
2
+ import { type Pacing } from "../core/pacing.js";
3
3
  import { type Provenance } from "../core/provenance.js";
4
4
  import type { TimeBounds } from "../core/trajectory.js";
5
- import { type PanelLookup, type StoryPanelSet } from "../shell/storyPanels.js";
5
+ import { type CheckedPanel, type PanelLookup, type PanelPlayback, type StoryPanelSet } from "../core/storyPanels.js";
6
6
  import { type TimeInput } from "./time.js";
7
- /** A timed event: a labelled moment on the timeline. The id is unique among the scene's events. */
7
+ /** A timed event: a labelled moment on the timeline. The id is unique among the scene's events: a repeat throws `duplicate-id`. */
8
8
  export interface EventInput {
9
9
  readonly id: string;
10
10
  readonly label: string;
@@ -13,8 +13,13 @@ export interface EventInput {
13
13
  readonly type?: string;
14
14
  /** Where this event's time comes from. Shown with the event; an event without one shows the `provenance` of `addEvents`. Malformed: `addEvents` throws "bad-event" naming the event. */
15
15
  readonly provenance?: Provenance;
16
- /** The body or trajectory (its id) this event is about. Go to this event seeks to its time and frames the object as `camera.lookAt` does. Not in the scene when the scene is built (`mount`): "bad-event" naming the event and the id. Without one, Go to only seeks. */
16
+ /** The body or trajectory (its id) this event is about. Go to this event seeks to its time and frames the object as `camera.focus` does. Not in the scene when the scene is built (`mount`): "bad-event" naming the event and the id. Without one, Go to only seeks. */
17
17
  readonly object?: string;
18
+ /**
19
+ * Gives the event a zone of its own: from `withinSeconds` before its time to `withinSeconds` after it (simulated seconds, positive and finite). A host hears entering and leaving it
20
+ * (`onEventZone`, `eventZones`), with or without pacing; a pacing rule for the event's type uses this width instead of its own `withinSeconds`. Not positive and finite: `addEvents` throws "bad-event" naming the event.
21
+ */
22
+ readonly withinSeconds?: number;
18
23
  }
19
24
  /** Options of `addEvents`. */
20
25
  export interface AddEventsOptions {
@@ -40,23 +45,23 @@ export type TimelineInput = {
40
45
  readonly rate?: number;
41
46
  };
42
47
  /**
43
- * One piece of a timeline's pacing. A span `{ from, to, rate }` plays at `rate` between two moments; an event rule `{ near: { type, within }, rate }` plays at `rate`
44
- * within `within` seconds (simulated) of every event of that `type` (see `addEvents`). Outside every piece playback runs at the timeline's `rate`. Between a piece and
45
- * what surrounds it the speed eases over `ramp` simulated seconds (default: `within` for an event rule, a tenth of the span for a span). `rate` here is any positive number;
48
+ * One piece of a timeline's pacing. A span `{ start, end, rate }` plays at `rate` between two moments; an event rule `{ near: { type, withinSeconds }, rate }` plays at `rate`
49
+ * within `withinSeconds` (simulated) of every event of that `type` (see `addEvents`). Outside every piece playback runs at the timeline's `rate`. Between a piece and
50
+ * what surrounds it the speed eases over `rampSeconds` simulated seconds (default: `withinSeconds` for an event rule, a tenth of the span for a span). `rate` here is any positive number;
46
51
  * it need not be one of the offered `rates`. 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.
47
52
  */
48
53
  export type PacingInput = {
49
- readonly from: TimeInput;
50
- readonly to: TimeInput;
54
+ readonly start: TimeInput;
55
+ readonly end: TimeInput;
51
56
  readonly rate: number;
52
- readonly ramp?: number;
57
+ readonly rampSeconds?: number;
53
58
  } | {
54
59
  readonly near: {
55
60
  readonly type: string;
56
- readonly within: number;
61
+ readonly withinSeconds: number;
57
62
  };
58
63
  readonly rate: number;
59
- readonly ramp?: number;
64
+ readonly rampSeconds?: number;
60
65
  };
61
66
  /** A checked pacing piece: moments as Unix milliseconds, seconds as milliseconds. */
62
67
  export type PacingPiece = {
@@ -84,28 +89,53 @@ export interface TimelineSetting {
84
89
  /** For no timeline: the moment time is frozen at, or runs on from. */
85
90
  readonly atUtcMs?: number;
86
91
  }
92
+ /** When a story panel opens: a moment, an event of `addEvents` by id, or an anchor of a path by id. Exactly one. */
93
+ export type StoryPanelAt = {
94
+ readonly time: TimeInput;
95
+ } | {
96
+ readonly event: string;
97
+ } | {
98
+ readonly anchor: string;
99
+ };
87
100
  /**
88
- * The raw settings of a scene's story panels: `{ pauseSeconds?, autoOpen?, panels: [{ id, at: { utc } | { event } | { anchor }, title, body, details?, badge, sources, object? }] }`.
89
- * `badge` is "observed", "modelled" or "illustrative"; `sources` is never empty. A panel's time may name an event of `addEvents` or an anchor of a path, and `object` a
90
- * body or path of the scene; these are checked when the scene is turned into a definition (mount), and a mistake throws `bad-panels` naming the panel and field.
101
+ * One story panel. Its shape is checked at `addStoryPanels`, which throws `bad-panels` naming the panel and field. What it names is checked when the scene is built (`check`, `mount`),
102
+ * because the event, anchor or object may be added later: a mistake there, or a moment outside the timeline, throws `bad-panels` too.
91
103
  */
92
- export interface StoryPanelsInput {
104
+ export interface StoryPanelInput {
105
+ /** Unique among the scene's panels: a repeat throws `duplicate-id`. */
106
+ readonly id: string;
107
+ readonly at: StoryPanelAt;
108
+ readonly title: string;
109
+ /** Paragraphs, in order; one text is one paragraph. */
110
+ readonly body: string | readonly string[];
111
+ /** Paragraphs of exact figures, shown folded above the sources. */
112
+ readonly details?: string | readonly string[];
113
+ /** Where the panel's facts come from. The badge shows the word for `sourceType`; `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. */
114
+ readonly provenance: Provenance;
115
+ /** The id of a body or path the panel is about; it gets a marker that reopens the panel. */
116
+ readonly object?: string;
117
+ }
118
+ /** The playback settings of a scene's story panels. */
119
+ export interface StoryPanelPlaybackInput {
93
120
  /** Seconds playback holds when a panel opens by itself (0 to 20, default 6; 0 never pauses). Playback then restarts, unless the visitor pressed Play during the hold, which ends it at once. */
94
121
  readonly pauseSeconds?: number;
95
122
  /** Whether panels open by themselves as forward playback crosses them (default true). */
96
123
  readonly autoOpen?: boolean;
97
- readonly panels: readonly unknown[];
98
124
  }
99
125
  /** Throws "bad-event" naming the first event whose `object` is not among the scene's `objectIds`. */
100
126
  export declare function checkEventObjects(events: readonly TimelineEvent[], objectIds: ReadonlySet<string>): void;
101
127
  /** Checks a provenance given to `addEvents` (for the whole batch, or for the event `eventId`) and returns it frozen; throws "bad-event" when malformed. */
102
128
  export declare function eventProvenanceOf(value: unknown, eventId?: string): Provenance;
103
- /** The events merged with `inputs`, sorted by time; each needs a distinct non-empty id and label and a valid moment. */
129
+ /** The events merged with `inputs`, sorted by time; each needs a non-empty id and label and a valid moment, and an id already in `known` or repeated in the batch throws `duplicate-id`. */
104
130
  export declare function eventsOf(inputs: readonly EventInput[], known: readonly TimelineEvent[]): readonly TimelineEvent[];
105
131
  /** Checks a `setTimeline` argument and converts its moments. */
106
132
  export declare function timelineOf(input: TimelineInput): TimelineSetting;
133
+ /** Checks the shape of a batch for `addStoryPanels`: old forms throw `renamed`, a bad shape `bad-panels`, and an id already in `known` or repeated in the batch `duplicate-id`. */
134
+ export declare function panelBatchOf(inputs: readonly StoryPanelInput[], known: readonly CheckedPanel[]): readonly CheckedPanel[];
135
+ /** Checks a `setStoryPanelPlayback` argument; a mistake throws `bad-panels`. */
136
+ export declare function panelPlaybackOf(input: StoryPanelPlaybackInput): PanelPlayback;
107
137
  /** The story panels resolved against the scene's events, anchors, objects and window; a mistake becomes a `bad-panels` SceneError. */
108
- export declare function panelsOf(raw: StoryPanelsInput, lookup: PanelLookup): StoryPanelSet;
138
+ export declare function panelsOf(panels: readonly CheckedPanel[], playback: PanelPlayback, lookup: PanelLookup): StoryPanelSet;
109
139
  /**
110
140
  * The pacing the viewer runs, laid over the events: spans, then one zone per event of each rule's type. `pacedRate` lays the zones fastest first, so the slowest applicable piece wins wherever they meet, whatever contains what.
111
141
  * A rule whose type has no event throws `bad-timeline` naming the piece (a mistyped type would otherwise slow nothing, silently).
package/src/api/story.js CHANGED
@@ -1,7 +1,9 @@
1
1
  import { createEvents } from "../core/events.js";
2
+ import { zoneAround } from "../core/pacing.js";
2
3
  import { createProvenance } from "../core/provenance.js";
3
- import { parseStoryPanels, StoryPanelError } from "../shell/storyPanels.js";
4
+ import { checkPanelPlayback, checkStoryPanel, resolveStoryPanels, StoryPanelError } from "../core/storyPanels.js";
4
5
  import { SceneError } from "./errors.js";
6
+ import { rejectRenamed } from "./renamedInputs.js";
5
7
  import { toUtcMs } from "./time.js";
6
8
  /** Throws "bad-event" naming the first event whose `object` is not among the scene's `objectIds`. */
7
9
  export function checkEventObjects(events, objectIds) {
@@ -20,7 +22,7 @@ export function eventProvenanceOf(value, eventId) {
20
22
  throw new SceneError("bad-event", `${where} is malformed (${error instanceof Error ? error.message : String(error)})`);
21
23
  }
22
24
  }
23
- /** The events merged with `inputs`, sorted by time; each needs a distinct non-empty id and label and a valid moment. */
25
+ /** The events merged with `inputs`, sorted by time; each needs a non-empty id and label and a valid moment, and an id already in `known` or repeated in the batch throws `duplicate-id`. */
24
26
  export function eventsOf(inputs, known) {
25
27
  if (!Array.isArray(inputs))
26
28
  throw new SceneError("bad-event", "addEvents: events must be a list");
@@ -31,12 +33,14 @@ export function eventsOf(inputs, known) {
31
33
  if (typeof input.label !== "string" || input.label === "")
32
34
  throw new SceneError("bad-event", `addEvents: event "${input.id}" needs a non-empty label`);
33
35
  if (ids.has(input.id))
34
- throw new SceneError("bad-event", `addEvents: event "${input.id}" appears twice`);
36
+ throw new SceneError("duplicate-id", `addEvents: event "${input.id}" is already in the scene's events`);
35
37
  ids.add(input.id);
36
38
  const timeUtcMs = toUtcMs(input.time, `addEvents: event "${input.id}" time`);
37
39
  if (input.object !== undefined && (typeof input.object !== "string" || input.object === ""))
38
40
  throw new SceneError("bad-event", `addEvents: event "${input.id}" object must be a non-empty id`);
39
- return { id: input.id, label: input.label, timeUtcMs, ...(input.type === undefined ? {} : { type: input.type }), ...(input.object === undefined ? {} : { object: input.object }) };
41
+ if (input.withinSeconds !== undefined && !(typeof input.withinSeconds === "number" && Number.isFinite(input.withinSeconds) && input.withinSeconds > 0))
42
+ throw new SceneError("bad-event", `addEvents: event "${input.id}" withinSeconds must be a positive, finite number of seconds, got ${String(input.withinSeconds)}`);
43
+ return { id: input.id, label: input.label, timeUtcMs, ...(input.withinSeconds === undefined ? {} : { withinMs: input.withinSeconds * 1000 }), ...(input.type === undefined ? {} : { type: input.type }), ...(input.object === undefined ? {} : { object: input.object }) };
40
44
  });
41
45
  return createEvents([...known, ...added].sort((a, b) => a.timeUtcMs - b.timeUtcMs));
42
46
  }
@@ -60,48 +64,76 @@ export function timelineOf(input) {
60
64
  const pacing = pacingOf(input.pacing, bad);
61
65
  return { none: false, window, ...(rates === undefined ? {} : { rates }), ...(pacing === undefined ? {} : { pacing }), ...(input.rate === undefined ? {} : { rate: input.rate }), ...(input.loop === true ? { loop: true } : {}) };
62
66
  }
63
- /** The story panels resolved against the scene's events, anchors, objects and window; a mistake becomes a `bad-panels` SceneError. */
64
- export function panelsOf(raw, lookup) {
67
+ /** Runs a core panel check, turning a `StoryPanelError` into a `bad-panels` SceneError that leads with `call`. */
68
+ function panelCheck(call, check) {
65
69
  try {
66
- return parseStoryPanels(raw, lookup);
70
+ return check();
67
71
  }
68
72
  catch (error) {
69
73
  if (error instanceof StoryPanelError)
70
- throw new SceneError("bad-panels", `addStoryPanels: ${error.message}`);
74
+ throw new SceneError("bad-panels", `${call}: ${error.message}`);
71
75
  throw error;
72
76
  }
73
77
  }
78
+ /** Checks the shape of a batch for `addStoryPanels`: old forms throw `renamed`, a bad shape `bad-panels`, and an id already in `known` or repeated in the batch `duplicate-id`. */
79
+ export function panelBatchOf(inputs, known) {
80
+ rejectRenamed("AddStoryPanelsCall", inputs, "addStoryPanels");
81
+ if (!Array.isArray(inputs))
82
+ throw new SceneError("bad-panels", "addStoryPanels: give a list of panels");
83
+ const ids = new Set(known.map(({ id }) => id));
84
+ return inputs.map((input, index) => {
85
+ const named = input?.id;
86
+ const where = `addStoryPanels: story panel ${typeof named === "string" ? named : `#${index + 1}`}`;
87
+ rejectRenamed("StoryPanelInput", input, where);
88
+ rejectRenamed("StoryPanelAt", input?.at, `${where} at`);
89
+ const panel = panelCheck("addStoryPanels", () => checkStoryPanel(input, index));
90
+ if (ids.has(panel.id))
91
+ throw new SceneError("duplicate-id", `${where}: that id is already in the scene's panels`);
92
+ ids.add(panel.id);
93
+ return panel;
94
+ });
95
+ }
96
+ /** Checks a `setStoryPanelPlayback` argument; a mistake throws `bad-panels`. */
97
+ export function panelPlaybackOf(input) {
98
+ return panelCheck("setStoryPanelPlayback", () => checkPanelPlayback(input));
99
+ }
100
+ /** The story panels resolved against the scene's events, anchors, objects and window; a mistake becomes a `bad-panels` SceneError. */
101
+ export function panelsOf(panels, playback, lookup) {
102
+ return panelCheck("addStoryPanels", () => resolveStoryPanels(panels, playback, lookup));
103
+ }
74
104
  /** Checks `pacing`: each piece names the field that is wrong (`pacing[2].rate`); spans must not overlap. */
75
105
  function pacingOf(input, bad) {
76
106
  if (input === undefined)
77
107
  return undefined;
78
108
  if (!Array.isArray(input))
79
- throw bad("pacing must be a list of { from, to, rate } and { near: { type, within }, rate }");
109
+ throw bad("pacing must be a list of { start, end, rate } and { near: { type, withinSeconds }, rate }");
80
110
  const positive = (value) => typeof value === "number" && Number.isFinite(value) && value > 0;
81
111
  const pieces = input.map((raw, index) => {
82
112
  const at = `pacing[${index}]`;
83
113
  if (typeof raw !== "object" || raw === null)
84
114
  throw bad(`${at} must be an object`);
85
115
  const piece = raw;
116
+ rejectRenamed(piece.near === undefined ? "PacingSpan" : "PacingRule", piece, `setTimeline: ${at}`);
86
117
  if (!positive(piece.rate))
87
118
  throw bad(`${at}.rate must be a positive number, got ${String(piece.rate)}`);
88
- if (piece.ramp !== undefined && !(typeof piece.ramp === "number" && Number.isFinite(piece.ramp) && piece.ramp >= 0))
89
- throw bad(`${at}.ramp must be zero or more seconds, got ${String(piece.ramp)}`);
119
+ if (piece.rampSeconds !== undefined && !(typeof piece.rampSeconds === "number" && Number.isFinite(piece.rampSeconds) && piece.rampSeconds >= 0))
120
+ throw bad(`${at}.rampSeconds must be zero or more seconds, got ${String(piece.rampSeconds)}`);
90
121
  if (piece.near !== undefined) {
91
- const { type, within } = piece.near;
122
+ rejectRenamed("PacingNear", piece.near, `setTimeline: ${at}.near`);
123
+ const { type, withinSeconds } = piece.near;
92
124
  if (typeof type !== "string" || type === "")
93
125
  throw bad(`${at}.near.type must be a non-empty event type`);
94
- if (!positive(within))
95
- throw bad(`${at}.near.within must be a positive number of seconds, got ${String(within)}`);
96
- return { type, withinMs: within * 1000, rate: piece.rate, rampMs: (piece.ramp ?? within) * 1000 };
126
+ if (!positive(withinSeconds))
127
+ throw bad(`${at}.near.withinSeconds must be a positive number of seconds, got ${String(withinSeconds)}`);
128
+ return { type, withinMs: withinSeconds * 1000, rate: piece.rate, rampMs: (piece.rampSeconds ?? withinSeconds) * 1000 };
97
129
  }
98
- if (piece.from === undefined || piece.to === undefined)
99
- throw bad(`${at} needs { from, to, rate } or { near: { type, within }, rate }`);
100
- const fromUtcMs = toUtcMs(piece.from, `setTimeline ${at}.from`);
101
- const toUtcMsValue = toUtcMs(piece.to, `setTimeline ${at}.to`);
130
+ if (piece.start === undefined || piece.end === undefined)
131
+ throw bad(`${at} needs { start, end, rate } or { near: { type, withinSeconds }, rate }`);
132
+ const fromUtcMs = toUtcMs(piece.start, `setTimeline ${at}.start`);
133
+ const toUtcMsValue = toUtcMs(piece.end, `setTimeline ${at}.end`);
102
134
  if (toUtcMsValue <= fromUtcMs)
103
- throw bad(`${at}.to must be after ${at}.from`);
104
- return { fromUtcMs, toUtcMs: toUtcMsValue, rate: piece.rate, rampMs: piece.ramp === undefined ? (toUtcMsValue - fromUtcMs) / 10 : piece.ramp * 1000 };
135
+ throw bad(`${at}.end must be after ${at}.start`);
136
+ return { fromUtcMs, toUtcMs: toUtcMsValue, rate: piece.rate, rampMs: piece.rampSeconds === undefined ? (toUtcMsValue - fromUtcMs) / 10 : piece.rampSeconds * 1000 };
105
137
  });
106
138
  const spans = pieces.flatMap((piece, index) => ("fromUtcMs" in piece ? [{ piece, index }] : [])).sort((a, b) => a.piece.fromUtcMs - b.piece.fromUtcMs);
107
139
  for (let i = 1; i < spans.length; i += 1) {
@@ -128,7 +160,7 @@ export function pacingFor(setting, events, baseRate) {
128
160
  if (matching.length === 0)
129
161
  throw new SceneError("bad-timeline", `setTimeline: pacing[${index}].near.type "${piece.type}" matches no event; give the events that type with addEvents`);
130
162
  for (const event of matching)
131
- near.push({ fromUtcMs: event.timeUtcMs - piece.withinMs, toUtcMs: event.timeUtcMs + piece.withinMs, rate: piece.rate, rampMs: piece.rampMs });
163
+ near.push({ ...zoneAround(event, piece.withinMs), rate: piece.rate, rampMs: piece.rampMs });
132
164
  });
133
165
  return { baseRate, zones: [...spans, ...near] };
134
166
  }
@@ -1,9 +1,10 @@
1
1
  import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
2
- import { BUILT_IN_SAMPLING, EARTH_EPHEMERIS } from "../core/bodies/index.js";
2
+ import { EARTH_EPHEMERIS } from "../core/bodies/index.js";
3
3
  import { fillKeplerRangeKm, keplerElementsFromStates } from "../core/keplerElements.js";
4
4
  import { createState, EQJ } from "../core/state.js";
5
5
  import { TimeScaleOutOfRangeError } from "../core/timeScale.js";
6
- import { createEarthSunTrajectory, fullTurnSpanMs } from "../core/sunCentredSources.js";
6
+ import { PlanetFitsUncoveredError } from "../core/planetSeries.js";
7
+ import { createEarthSunTrajectory, fullTurnSpanMs, NoFullTurnError } from "../core/sunCentredSources.js";
7
8
  import { rootBodyId } from "../assets/catalogue.js";
8
9
  import { SceneError } from "./errors.js";
9
10
  const DAY_MS = 86_400_000;
@@ -64,22 +65,19 @@ function ellipseSource(id, elements) {
64
65
  stateAt(timeUtcMs) {
65
66
  const out = new Float64Array(3);
66
67
  fillKeplerRangeKm(elements, timeUtcMs, out, 0, 1);
67
- return createState({ body: id, center: "sun", timeUtcMs, frame: EQJ, positionKm: out, orientation: null }, () => false);
68
+ return createState({ body: id, center: "sun", timeUtcMs, plane: EQJ, positionKm: out, orientation: null }, () => false);
68
69
  },
69
70
  });
70
71
  }
71
72
  /**
72
- * How a body that circles the Sun is drawn, one rule for every body and never by name: with published elements (`given`, or the catalogue's comet
73
- * sampling) from periapsis for one period; else one full turn of its own source when the source covers a whole turn from `startUtcMs`; else (a source
74
- * that ends first, such as the planet series for Uranus and Neptune) the two-body ellipse osculating at `startUtcMs`. Undefined when none can be drawn.
73
+ * How a body that circles the Sun is drawn, one rule for every body and never by name: with published elements (`given`) from periapsis for one period; else one full turn of its own source when the source covers a whole turn from `startUtcMs`; else (a source that ends first, such as the planet series for Uranus and Neptune) the two-body ellipse osculating at `startUtcMs`. Undefined when none can be drawn.
75
74
  */
76
75
  function drawnOrbit(catalogue, id, startUtcMs, given) {
77
76
  const source = trajectoryOf(catalogue, id);
78
- const sampling = given ?? BUILT_IN_SAMPLING[id];
79
- if (sampling !== undefined) {
77
+ if (given !== undefined) {
80
78
  const gm = catalogue.get(rootBodyId(catalogue)).definition.gmKm3S2;
81
- const semiMajorKm = Math.cbrt(gm * (sampling.periodMs / 1000 / (2 * Math.PI)) ** 2);
82
- return { source, span: { startUtcMs: sampling.periapsisUtcMs, endUtcMs: sampling.periapsisUtcMs + Math.round(sampling.periodMs) }, sampling, osculating: false, farthestKm: semiMajorKm * (1 + sampling.eccentricity) };
79
+ const semiMajorKm = Math.cbrt(gm * (given.periodMs / 1000 / (2 * Math.PI)) ** 2);
80
+ return { source, span: { startUtcMs: given.periapsisUtcMs, endUtcMs: given.periapsisUtcMs + Math.round(given.periodMs) }, sampling: given, osculating: false, farthestKm: semiMajorKm * (1 + given.eccentricity) };
83
81
  }
84
82
  const span = turnSpan(source, startUtcMs);
85
83
  if (span !== undefined)
@@ -128,7 +126,7 @@ function turnSpan(source, startUtcMs) {
128
126
  }
129
127
  catch (error) {
130
128
  // No full turn in the search, or the source's years end first (the planet series): the source does not cover a whole turn.
131
- if (error instanceof TimeScaleOutOfRangeError || (error instanceof RangeError && /no full turn|do not cover/.test(error.message)))
129
+ if (error instanceof TimeScaleOutOfRangeError || error instanceof NoFullTurnError || error instanceof PlanetFitsUncoveredError)
132
130
  return undefined;
133
131
  throw error;
134
132
  }
package/src/api/time.d.ts CHANGED
@@ -1,4 +1,5 @@
1
+ import { type TimeInput } from "../core/timeInput.js";
1
2
  /** A moment: ISO text, a Date, or Unix milliseconds. */
2
- export type TimeInput = string | number | Date;
3
+ export type { TimeInput };
3
4
  /** Converts a moment to Unix milliseconds, or throws a `bad-time` SceneError naming it. */
4
5
  export declare function toUtcMs(time: TimeInput, what?: string): number;
package/src/api/time.js CHANGED
@@ -1,7 +1,8 @@
1
1
  import { SceneError } from "./errors.js";
2
+ import { timeInputMs } from "../core/timeInput.js";
2
3
  /** Converts a moment to Unix milliseconds, or throws a `bad-time` SceneError naming it. */
3
4
  export function toUtcMs(time, what = "time") {
4
- const ms = time instanceof Date ? time.getTime() : typeof time === "number" ? time : Date.parse(time);
5
+ const ms = timeInputMs(time);
5
6
  if (!Number.isFinite(ms))
6
7
  throw new SceneError("bad-time", `${what} "${String(time)}" is not a valid moment; use an ISO text such as "1969-07-20T20:17:40Z", a Date or Unix milliseconds`);
7
8
  return ms;
@@ -0,0 +1,22 @@
1
+ import type { CameraPose, CameraTarget, LinkAccess } from "./viewerLink.js";
2
+ /** The host link's camera: the pose read and `setCamera`, with its request check. */
3
+ export declare class ViewerCamera {
4
+ #private;
5
+ private readonly access;
6
+ constructor(access: LinkAccess);
7
+ /** The viewer attached (the opening pose is read, not reported) or detached (nothing is known). */
8
+ reset(): void;
9
+ clearListeners(): void;
10
+ /** Calls `listener` with the new pose when the camera's object, angles or distance change (at most about ten times a second); returns the function that stops it. */
11
+ onCameraChange(listener: (camera: CameraPose) => void): () => void;
12
+ /** A viewer publish (its tick, or a host or visitor action): reports the pose when it differs from the last one. */
13
+ publish(): void;
14
+ /** The camera pose, or undefined before the viewer is drawn and after it is gone; before its first frame it is the opening camera. */
15
+ get camera(): CameraPose | undefined;
16
+ /**
17
+ * Points the camera: `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, a pose (from `camera`) puts the camera back where it was read,
18
+ * relative to its object. The id must be an object the showing view shows; an unknown or hidden id, or a malformed argument, throws `bad-camera`.
19
+ * Before the viewer is drawn or after it is gone, `not-mounted`. The move eases in as a view's camera rule does.
20
+ */
21
+ setCamera(target: CameraTarget): void;
22
+ }