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
@@ -1,4 +1,5 @@
1
1
  import type { SimulationClock } from "./clock.js";
2
+ import type { TimelineEvent } from "./events.js";
2
3
  /**
3
4
  * One stretch of the timeline with its own playback rate: full `rate` from `fromUtcMs` to `toUtcMs`, easing back to the surrounding rate over
4
5
  * `rampMs` of simulated time on either side. The ramp is in simulated time, so the paced rate stays a pure function of the clock's time.
@@ -8,7 +9,29 @@ export interface PaceZone {
8
9
  readonly toUtcMs: number;
9
10
  readonly rate: number;
10
11
  readonly rampMs: number;
12
+ /** The event this zone comes from (an event rule's zones); absent for a span, which applies everywhere. */
13
+ readonly eventId?: string;
11
14
  }
15
+ /** Where an event zone lies: the part of a zone the host report and the view filter read. A `PaceZone` is one with a rate. */
16
+ export type EventZone = Pick<PaceZone, "fromUtcMs" | "toUtcMs" | "eventId">;
17
+ /** The zone of `event`: its own `withinMs` where it has one, else `defaultWithinMs`, either side of its time. The one place an event zone is cut. */
18
+ export declare function zoneAround(event: TimelineEvent, defaultWithinMs: number): EventZone;
19
+ /**
20
+ * Every event zone of a scene: those of the pacing rules (`paceZones`, which already read each event's own `withinMs`) and the own zone of each event that has a `withinMs`
21
+ * and no rule zone. A scene without pacing still has the second kind.
22
+ */
23
+ export declare function eventZonesOf(events: readonly TimelineEvent[], paceZones: readonly PaceZone[]): readonly EventZone[];
24
+ /** The ids of the events a view shows; absent means every zone applies (a scene without views). */
25
+ export type ShownEvents = ReadonlySet<string> | undefined;
26
+ /** Whether a zone applies when only `shown` events are in play: spans always do, an event zone only when its event is shown. */
27
+ export declare function zoneInView<Z extends EventZone>(zone: Z, shown: ShownEvents): boolean;
28
+ /** The zones that apply when only `shown` events are in play (the same filter `pacedRate` reads; a host reads it to tell where playback is slowed for the view). */
29
+ export declare function zonesInView<Z extends EventZone>(zones: readonly Z[], shown: ShownEvents): readonly Z[];
30
+ /**
31
+ * The ids of the events whose zone (from `withinSeconds` or a pacing rule) holds `timeUtcMs` (edges included, as `pacedRate` reads them), among the zones the showing view has; each id once, in zone order.
32
+ * Span zones carry no event and never count. A pure function of its arguments.
33
+ */
34
+ export declare function activeEventZones(zones: readonly EventZone[], shown: ShownEvents, timeUtcMs: number): readonly string[];
12
35
  /** A scene's pacing: the rate outside every zone and its zones. Where zones overlap the slowest wins whatever order they are listed in (`pacedRate` lays the fastest first and the slowest last). */
13
36
  export interface Pacing {
14
37
  readonly baseRate: number;
@@ -19,6 +42,18 @@ export interface Pacing {
19
42
  * (smoothstep); the rate blends in log space, so a jump of several orders of magnitude eases evenly. Every weight is continuous in time, so the
20
43
  * result is continuous too. A pure function of its arguments: nothing about the State changes.
21
44
  */
22
- export declare function pacedRate(pacing: Pacing, timeUtcMs: number): number;
23
- /** Sets the clock to the paced rate for its current time (skipped when it already runs at it). */
24
- export declare function applyPacing(clock: SimulationClock, pacing: Pacing): void;
45
+ export declare function pacedRate(pacing: Pacing, timeUtcMs: number, shown?: ShownEvents): number;
46
+ /** How long, in real milliseconds, a change of the paced rate that comes from a view switch takes to ease in. */
47
+ export declare const PACE_EASE_MS = 1000;
48
+ /** What pacing reads besides the clock: the events the showing view has, and an ease in progress from a view switch (`applyPacing` clears it when it ends). */
49
+ export interface PaceView {
50
+ shown?: ShownEvents;
51
+ ease?: {
52
+ readonly fromRate: number;
53
+ readonly startMs: number;
54
+ };
55
+ }
56
+ /** Starts the ease from the clock's present rate; the next `applyPacing` calls blend from it to the paced rate over `PACE_EASE_MS`. */
57
+ export declare function startPaceEase(view: PaceView, fromRate: number, nowMs: number): void;
58
+ /** Sets the clock to the paced rate for its current time (skipped when it already runs at it); mid-ease it is the log-space blend from the ease's start rate. */
59
+ export declare function applyPacing(clock: SimulationClock, pacing: Pacing, view?: PaceView, nowMs?: number): void;
@@ -1,3 +1,38 @@
1
+ /** The zone of `event`: its own `withinMs` where it has one, else `defaultWithinMs`, either side of its time. The one place an event zone is cut. */
2
+ export function zoneAround(event, defaultWithinMs) {
3
+ const within = event.withinMs ?? defaultWithinMs;
4
+ return { fromUtcMs: event.timeUtcMs - within, toUtcMs: event.timeUtcMs + within, eventId: event.id };
5
+ }
6
+ /**
7
+ * Every event zone of a scene: those of the pacing rules (`paceZones`, which already read each event's own `withinMs`) and the own zone of each event that has a `withinMs`
8
+ * and no rule zone. A scene without pacing still has the second kind.
9
+ */
10
+ export function eventZonesOf(events, paceZones) {
11
+ const ruled = paceZones.filter((zone) => zone.eventId !== undefined);
12
+ const covered = new Set(ruled.map((zone) => zone.eventId));
13
+ const own = events.filter((event) => event.withinMs !== undefined && !covered.has(event.id)).map((event) => zoneAround(event, 0));
14
+ return [...ruled, ...own];
15
+ }
16
+ /** Whether a zone applies when only `shown` events are in play: spans always do, an event zone only when its event is shown. */
17
+ export function zoneInView(zone, shown) {
18
+ return shown === undefined || zone.eventId === undefined || shown.has(zone.eventId);
19
+ }
20
+ /** The zones that apply when only `shown` events are in play (the same filter `pacedRate` reads; a host reads it to tell where playback is slowed for the view). */
21
+ export function zonesInView(zones, shown) {
22
+ return shown === undefined ? zones : zones.filter((zone) => zoneInView(zone, shown));
23
+ }
24
+ /**
25
+ * The ids of the events whose zone (from `withinSeconds` or a pacing rule) holds `timeUtcMs` (edges included, as `pacedRate` reads them), among the zones the showing view has; each id once, in zone order.
26
+ * Span zones carry no event and never count. A pure function of its arguments.
27
+ */
28
+ export function activeEventZones(zones, shown, timeUtcMs) {
29
+ const ids = [];
30
+ for (const zone of zonesInView(zones, shown)) {
31
+ if (zone.eventId !== undefined && timeUtcMs >= zone.fromUtcMs && timeUtcMs <= zone.toUtcMs && !ids.includes(zone.eventId))
32
+ ids.push(zone.eventId);
33
+ }
34
+ return ids;
35
+ }
1
36
  const slowestLast = new WeakMap();
2
37
  /** The zones fastest first, so the slowest is laid last and wins wherever zones meet, ramps included. Cached per zone list. */
3
38
  function inLayerOrder(zones) {
@@ -14,10 +49,12 @@ const smooth = (x) => x * x * (3 - 2 * x);
14
49
  * (smoothstep); the rate blends in log space, so a jump of several orders of magnitude eases evenly. Every weight is continuous in time, so the
15
50
  * result is continuous too. A pure function of its arguments: nothing about the State changes.
16
51
  */
17
- export function pacedRate(pacing, timeUtcMs) {
52
+ export function pacedRate(pacing, timeUtcMs, shown) {
18
53
  let logRate = Math.log(pacing.baseRate);
19
54
  let touched = false;
20
55
  for (const zone of inLayerOrder(pacing.zones)) {
56
+ if (!zoneInView(zone, shown))
57
+ continue;
21
58
  const distance = timeUtcMs < zone.fromUtcMs ? zone.fromUtcMs - timeUtcMs : timeUtcMs > zone.toUtcMs ? timeUtcMs - zone.toUtcMs : 0;
22
59
  const weight = distance === 0 ? 1 : distance >= zone.rampMs ? 0 : smooth(1 - distance / zone.rampMs);
23
60
  if (weight > 0)
@@ -27,9 +64,23 @@ export function pacedRate(pacing, timeUtcMs) {
27
64
  }
28
65
  return touched ? Math.exp(logRate) : pacing.baseRate; // untouched: exactly the base, not its log round trip
29
66
  }
30
- /** Sets the clock to the paced rate for its current time (skipped when it already runs at it). */
31
- export function applyPacing(clock, pacing) {
32
- const rate = pacedRate(pacing, clock.now());
67
+ /** How long, in real milliseconds, a change of the paced rate that comes from a view switch takes to ease in. */
68
+ export const PACE_EASE_MS = 1000;
69
+ /** Starts the ease from the clock's present rate; the next `applyPacing` calls blend from it to the paced rate over `PACE_EASE_MS`. */
70
+ export function startPaceEase(view, fromRate, nowMs) {
71
+ view.ease = { fromRate, startMs: nowMs };
72
+ }
73
+ /** Sets the clock to the paced rate for its current time (skipped when it already runs at it); mid-ease it is the log-space blend from the ease's start rate. */
74
+ export function applyPacing(clock, pacing, view, nowMs = performance.now()) {
75
+ let rate = pacedRate(pacing, clock.now(), view?.shown);
76
+ const ease = view?.ease;
77
+ if (ease !== undefined) {
78
+ const progress = (nowMs - ease.startMs) / PACE_EASE_MS;
79
+ if (progress >= 1)
80
+ delete view.ease;
81
+ else if (progress >= 0)
82
+ rate = Math.exp(Math.log(ease.fromRate) + (Math.log(rate) - Math.log(ease.fromRate)) * smooth(progress));
83
+ }
33
84
  if (rate !== clock.rate)
34
85
  clock.setRate(rate);
35
86
  }
@@ -1,6 +1,6 @@
1
1
  import fits from "../../data/ephemerides/planets/planets.json" with { type: "json" };
2
2
  import { chunkCovers, chunkPositionInto, decodeChunk } from "./chebyshevSeries.js";
3
- import { PLANET_IDS } from "./planetSeries.js";
3
+ import { PLANET_IDS, PlanetFitsUncoveredError } from "./planetSeries.js";
4
4
  import { assertTimeScaleTable, ttMinusUtcSeconds } from "./timeScale.js";
5
5
  /** The astronomical unit in km that the astronomy adapter multiplies the model's au by; the fits are stored in km with the same value. */
6
6
  const AU_KM = 149_597_870.7;
@@ -19,7 +19,7 @@ function planetModel(chunk, table) {
19
19
  const utcMs = date.getTime();
20
20
  const tt = (utcMs - J2000_UNIX_MS) / 1000 + ttMinusUtcSeconds(table, utcMs);
21
21
  if (!chunkCovers(chunk, tt))
22
- throw new RangeError(`the planet curve fits do not cover ${date.toISOString()}`);
22
+ throw new PlanetFitsUncoveredError(date);
23
23
  chunkPositionInto(chunk, tt, km, 0);
24
24
  return { x: km[0] / AU_KM, y: km[1] / AU_KM, z: km[2] / AU_KM, coordinate_keywords: "ecliptic rectangular j2000", unit_keywords: "au" };
25
25
  },
@@ -1,4 +1,12 @@
1
1
  import type { TimeBounds } from "./trajectory.js";
2
+ /** Data the engine needs was asked for before it was loaded (the planet series, a moon system's fits). The public API turns it into a `missing-data` `SceneError` that names `scene.load`. */
3
+ export declare class NotLoadedError extends Error {
4
+ constructor(message: string);
5
+ }
6
+ /** A planet curve fit was asked for a moment its stored years do not cover; a `RangeError` so existing range handlers still see it. */
7
+ export declare class PlanetFitsUncoveredError extends RangeError {
8
+ constructor(date: Date);
9
+ }
2
10
  /** Planets the astronomy adapter has a heliocentric model for (Saturn to Pluto added by O-033 T-114). */
3
11
  export type PlanetId = "mercury" | "venus" | "mars" | "jupiter" | "saturn" | "uranus" | "neptune" | "pluto";
4
12
  export declare const PLANET_IDS: readonly PlanetId[];
@@ -1,3 +1,17 @@
1
+ /** Data the engine needs was asked for before it was loaded (the planet series, a moon system's fits). The public API turns it into a `missing-data` `SceneError` that names `scene.load`. */
2
+ export class NotLoadedError extends Error {
3
+ constructor(message) {
4
+ super(message);
5
+ this.name = "NotLoadedError";
6
+ }
7
+ }
8
+ /** A planet curve fit was asked for a moment its stored years do not cover; a `RangeError` so existing range handlers still see it. */
9
+ export class PlanetFitsUncoveredError extends RangeError {
10
+ constructor(date) {
11
+ super(`the planet curve fits do not cover ${date.toISOString()}`);
12
+ this.name = "PlanetFitsUncoveredError";
13
+ }
14
+ }
1
15
  export const PLANET_IDS = Object.freeze(["mercury", "venus", "mars", "jupiter", "saturn", "uranus", "neptune", "pluto"]);
2
16
  export function isPlanetId(id) {
3
17
  return PLANET_IDS.includes(id);
@@ -22,12 +36,12 @@ export function planetSeriesLoaded() {
22
36
  /** The years the loaded planet series cover (UTC); throws before `loadPlanetSeries()` resolved. A date outside it throws rather than extrapolate. */
23
37
  export function planetSeriesSpan() {
24
38
  if (span === undefined)
25
- throw new Error("the planet series are not loaded: await loadPlanetSeries() before asking their span");
39
+ throw new NotLoadedError("the planet series are not loaded: await loadPlanetSeries() before asking their span");
26
40
  return span;
27
41
  }
28
42
  /** The loaded planet models; throws before `loadPlanetSeries()` resolved rather than falling back to the compact tables. */
29
43
  export function planetModels() {
30
44
  if (models === undefined)
31
- throw new Error("the planet series are not loaded: await loadPlanetSeries() before mounting a composition with a planet");
45
+ throw new NotLoadedError("the planet series are not loaded: await loadPlanetSeries() before mounting a composition with a planet");
32
46
  return models;
33
47
  }
@@ -42,7 +42,7 @@ export function memberState(group, index, timeUtcMs, positionKm) {
42
42
  body: `${group.id}:${index}`,
43
43
  center: group.center,
44
44
  timeUtcMs,
45
- frame: EQJ,
45
+ plane: EQJ,
46
46
  positionKm,
47
47
  orientation: null,
48
48
  });
@@ -1,5 +1,6 @@
1
- /** What kind of source a path or body position comes from. `"modelled"` is a computed result of a stated model (shown as "Modelled", the same word as the story-panel badge). */
1
+ /** What kind of source a path or body position comes from. `"modelled"` is a computed result of a stated model (shown as "Modelled"). */
2
2
  export type ProvenanceSourceType = "ephemeris" | "observed" | "reconstructed" | "modelled" | "illustrative";
3
+ export declare const PROVENANCE_SOURCE_TYPES: readonly ProvenanceSourceType[];
3
4
  /** Where a path or body position came from and how far to trust it: `sourceType`, the `sources`, the `accuracy` and `notes`. Pass one as `addTrajectory({ provenance })`. Never affects State. */
4
5
  export interface Provenance {
5
6
  readonly sourceType: ProvenanceSourceType;
@@ -1,6 +1,6 @@
1
- const SOURCE_TYPES = ["ephemeris", "observed", "reconstructed", "modelled", "illustrative"];
1
+ export const PROVENANCE_SOURCE_TYPES = ["ephemeris", "observed", "reconstructed", "modelled", "illustrative"];
2
2
  export function createProvenance(input) {
3
- if (!SOURCE_TYPES.includes(input.sourceType))
3
+ if (!PROVENANCE_SOURCE_TYPES.includes(input.sourceType))
4
4
  throw new RangeError("provenance sourceType is not recognised");
5
5
  if (input.sources.some((source) => typeof source !== "string" || source.length === 0)) {
6
6
  throw new TypeError("provenance sources must be non-empty strings");
@@ -4,7 +4,7 @@ import { createCenteredPosition, createState, EQJ } from "./state.js";
4
4
  function sameEpochAndFrame(a, b) {
5
5
  if (a.timeUtcMs !== b.timeUtcMs)
6
6
  throw new RangeError("center composition requires identical timestamps");
7
- if (a.frame !== b.frame)
7
+ if (a.plane !== b.plane)
8
8
  throw new RangeError("center composition requires identical frames");
9
9
  }
10
10
  export function composeCenteredPositions(bodyFromOrigin, originFromCenter) {
@@ -16,7 +16,7 @@ export function composeCenteredPositions(bodyFromOrigin, originFromCenter) {
16
16
  body: bodyFromOrigin.body,
17
17
  center: originFromCenter.center,
18
18
  timeUtcMs: bodyFromOrigin.timeUtcMs,
19
- frame: bodyFromOrigin.frame,
19
+ plane: bodyFromOrigin.plane,
20
20
  positionKm: [
21
21
  bodyFromOrigin.positionKm[0] + originFromCenter.positionKm[0],
22
22
  bodyFromOrigin.positionKm[1] + originFromCenter.positionKm[1],
@@ -30,7 +30,7 @@ export function inverseCenteredPosition(position) {
30
30
  body: position.center,
31
31
  center: position.body,
32
32
  timeUtcMs: position.timeUtcMs,
33
- frame: position.frame,
33
+ plane: position.plane,
34
34
  positionKm: [-position.positionKm[0], -position.positionKm[1], -position.positionKm[2]],
35
35
  });
36
36
  }
@@ -39,7 +39,7 @@ export function earthStateAt(adapter, timeUtcMs) {
39
39
  body: "earth",
40
40
  center: "sun",
41
41
  timeUtcMs,
42
- frame: EQJ,
42
+ plane: EQJ,
43
43
  positionKm: adapter.earthPositionFromSunKm(timeUtcMs),
44
44
  orientation: earthOrientationFromEcefToEqj(adapter.earthFixedToEqjMatrix(timeUtcMs)),
45
45
  });
@@ -49,7 +49,7 @@ export function sunPositionFromEarthAt(adapter, timeUtcMs) {
49
49
  body: "sun",
50
50
  center: "earth",
51
51
  timeUtcMs,
52
- frame: EQJ,
52
+ plane: EQJ,
53
53
  positionKm: adapter.sunPositionFromEarthKm(timeUtcMs),
54
54
  });
55
55
  }
@@ -74,7 +74,7 @@ export class SampledTrajectory {
74
74
  body: this.body,
75
75
  center: this.#center,
76
76
  timeUtcMs,
77
- frame: EQJ,
77
+ plane: EQJ,
78
78
  positionKm: position,
79
79
  ...(velocity === undefined ? {} : { velocityKmS: velocity }),
80
80
  orientation: null,
@@ -36,6 +36,7 @@ export interface SolarSystemScaleOptions {
36
36
  readonly exaggeration: Readonly<Record<BodyId, number>>;
37
37
  readonly defaultExaggeration: number;
38
38
  }
39
+ /** The scale policy `solarSystemScale` is: a `ScalePolicy` with a per-body radius exaggeration. */
39
40
  export interface SolarSystemScalePolicy extends ScalePolicy {
40
41
  readonly id: "solar-system";
41
42
  /** The enlargement applied to a body (the default when it has no declared factor). */
@@ -0,0 +1,19 @@
1
+ /**
2
+ * A camera view as a short text: `?view=<focus>,<azimuthDeg>,<elevationDeg>,<distance>`, with the scale (`scale=`), up direction (`up=`)
3
+ * and time (`t=`, ISO UTC) beside it. Azimuth and elevation are the scene camera's own angles about the up direction in force;
4
+ * distance is the scene camera's own (scaled units, camera to focus). Pure text handling: no body is named here.
5
+ */
6
+ export interface StartView {
7
+ /** The focus target's id (a body, group or path the scene knows). */
8
+ readonly focus: string;
9
+ /** Degrees, 0 up to 360, about the up direction. */
10
+ readonly azimuthDeg: number;
11
+ /** Degrees above the orbit plane, within ±89. */
12
+ readonly elevationDeg: number;
13
+ /** Camera-to-focus distance in scaled units; positive. */
14
+ readonly distance: number;
15
+ }
16
+ export declare const MAX_ELEVATION_DEG = 89;
17
+ export declare const wrapAzimuth: (deg: number) => number;
18
+ /** Checks a view's fields, naming the offending one (`where` is its path, e.g. `look.startView`). Returns the view with the azimuth wrapped. */
19
+ export declare function validateStartView(raw: unknown, where?: string): StartView;
@@ -0,0 +1,28 @@
1
+ export const MAX_ELEVATION_DEG = 89;
2
+ export const wrapAzimuth = (deg) => ((deg % 360) + 360) % 360;
3
+ /** Checks a view's fields, naming the offending one (`where` is its path, e.g. `look.startView`). Returns the view with the azimuth wrapped. */
4
+ export function validateStartView(raw, where = "startView") {
5
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw))
6
+ throw new RangeError(`${where} must be an object with focus, azimuthDeg, elevationDeg and distance`);
7
+ const record = raw;
8
+ for (const key of Object.keys(record)) {
9
+ if (!["focus", "azimuthDeg", "elevationDeg", "distance"].includes(key))
10
+ throw new RangeError(`${where}.${key} is not a view field`);
11
+ }
12
+ if (typeof record.focus !== "string" || record.focus === "")
13
+ throw new RangeError(`${where}.focus must be a non-empty id, got ${String(record.focus)}`);
14
+ const number = (key) => {
15
+ const value = record[key];
16
+ if (typeof value !== "number" || !Number.isFinite(value))
17
+ throw new RangeError(`${where}.${key} must be a finite number, got ${String(value)}`);
18
+ return value;
19
+ };
20
+ const azimuthDeg = number("azimuthDeg");
21
+ const elevationDeg = number("elevationDeg");
22
+ const distance = number("distance");
23
+ if (Math.abs(elevationDeg) > MAX_ELEVATION_DEG)
24
+ throw new RangeError(`${where}.elevationDeg must be within ±${MAX_ELEVATION_DEG}, got ${elevationDeg}`);
25
+ if (!(distance > 0))
26
+ throw new RangeError(`${where}.distance must be positive, got ${distance}`);
27
+ return { focus: record.focus, azimuthDeg: wrapAzimuth(azimuthDeg), elevationDeg, distance };
28
+ }
@@ -1,12 +1,16 @@
1
1
  import { type BodyId, type CenterId } from "./body.js";
2
2
  export declare const EQJ: "EQJ";
3
+ /** The reference frame of a state: `"EQJ"`, equatorial J2000. */
3
4
  export type FrameId = typeof EQJ;
5
+ /** A rotation as a unit quaternion `[x, y, z, w]`. */
4
6
  export type Quaternion = readonly [x: number, y: number, z: number, w: number];
7
+ /** Where a body is, in km relative to a centre, with the velocity when known (a `State` without its orientation). */
5
8
  export interface CenteredPosition {
6
9
  readonly body: BodyId;
7
10
  readonly center: CenterId;
8
11
  readonly timeUtcMs: number;
9
- readonly frame: FrameId;
12
+ /** The plane the position is measured in: `"EQJ"`, equatorial J2000. */
13
+ readonly plane: FrameId;
10
14
  readonly positionKm: Float64Array;
11
15
  readonly velocityKmS?: Float64Array;
12
16
  }
@@ -19,7 +23,7 @@ export interface StateInput {
19
23
  readonly body: BodyId;
20
24
  readonly center: CenterId;
21
25
  readonly timeUtcMs: number;
22
- readonly frame?: FrameId;
26
+ readonly plane?: FrameId;
23
27
  readonly positionKm: ArrayLike<number>;
24
28
  readonly velocityKmS?: ArrayLike<number>;
25
29
  readonly orientation: Quaternion | null;
package/src/core/state.js CHANGED
@@ -42,14 +42,14 @@ export function createCenteredPosition(input) {
42
42
  && (positionKm.some((component) => component !== 0) || velocityKmS?.some((component) => component !== 0))) {
43
43
  throw new RangeError("a body can be positioned relative to itself only at exactly zero");
44
44
  }
45
- const frame = input.frame ?? EQJ;
46
- if (frame !== EQJ)
45
+ const plane = input.plane ?? EQJ;
46
+ if (plane !== EQJ)
47
47
  throw new RangeError("this spike's scientific states use the EQJ frame only");
48
48
  return Object.freeze({
49
49
  body: input.body,
50
50
  center: input.center,
51
51
  timeUtcMs: input.timeUtcMs,
52
- frame,
52
+ plane,
53
53
  positionKm,
54
54
  ...(velocityKmS === undefined ? {} : { velocityKmS }),
55
55
  });
@@ -0,0 +1,63 @@
1
+ import { type Provenance } from "./provenance.js";
2
+ import type { TimeBounds } from "./trajectory.js";
3
+ /** One short story panel, resolved to a UTC time. */
4
+ export interface StoryPanel {
5
+ readonly id: string;
6
+ readonly timeUtcMs: number;
7
+ readonly title: string;
8
+ /** Paragraphs, in order. */
9
+ readonly body: readonly string[];
10
+ /** Short paragraphs of exact figures and measured-versus-reconstructed notes, shown in the folded section above the sources. Empty when the panel has none. */
11
+ readonly details: readonly string[];
12
+ /** Where the panel's facts come from and how far to trust them (PROV-01): its `sourceType` is the badge word; `sources` is never empty and `accuracy` is always stated. */
13
+ readonly provenance: Provenance;
14
+ /** A shell object this panel is about; the scene draws a marker on it that reopens the panel. */
15
+ readonly objectId?: string;
16
+ }
17
+ /** The panels an experience offers, with the defaults of the two settings that govern them. */
18
+ export interface StoryPanelSet {
19
+ readonly panels: readonly StoryPanel[];
20
+ /** How long playback holds when a panel opens by itself, in seconds (0 never pauses). */
21
+ readonly pauseSeconds: number;
22
+ /** Whether panels open by themselves as forward playback reaches them. */
23
+ readonly autoOpen: boolean;
24
+ }
25
+ export declare const DEFAULT_PANEL_PAUSE_SECONDS = 6;
26
+ export declare const MAX_PANEL_PAUSE_SECONDS = 20;
27
+ /** The two playback settings of a scene's story panels. */
28
+ export type PanelPlayback = Pick<StoryPanelSet, "pauseSeconds" | "autoOpen">;
29
+ export declare const DEFAULT_PANEL_PLAYBACK: PanelPlayback;
30
+ /** A panel whose own shape is sound and whose moment is converted. What it names (an event, an anchor, an object) is left for `resolveStoryPanels`, because those may be added later. */
31
+ export interface CheckedPanel extends Omit<StoryPanel, "timeUtcMs" | "objectId"> {
32
+ readonly at: {
33
+ readonly timeUtcMs: number;
34
+ } | {
35
+ readonly event: string;
36
+ } | {
37
+ readonly anchor: string;
38
+ };
39
+ readonly object?: string;
40
+ }
41
+ /** What a story's settings may point a panel's time at, besides a plain UTC time. */
42
+ export interface PanelLookup {
43
+ readonly events: readonly {
44
+ readonly id: string;
45
+ readonly timeUtcMs: number;
46
+ }[];
47
+ /** Source anchors by id, when the experience has them. */
48
+ readonly anchors?: ReadonlyMap<string, number>;
49
+ /** Ids a panel's `object` may name. Absent: any id is accepted. */
50
+ readonly objectIds?: readonly string[];
51
+ /** When given, every panel must fall inside it. */
52
+ readonly window?: TimeBounds;
53
+ }
54
+ /** A panel's settings entry is wrong; the message names the panel and the field. */
55
+ export declare class StoryPanelError extends Error {
56
+ constructor(panel: string, field: string, problem: string);
57
+ }
58
+ /** Checks the shape of one panel, the `index`th of the list it came in. Nothing here looks at the scene: links are `resolveStoryPanels`' job. */
59
+ export declare function checkStoryPanel(raw: unknown, index: number): CheckedPanel;
60
+ /** Checks the two playback settings; a setting left out takes its default, so the result is the whole setting. */
61
+ export declare function checkPanelPlayback(raw: unknown): PanelPlayback;
62
+ /** Resolves each checked panel's time and links against the scene as built. Panels come back sorted by time. */
63
+ export declare function resolveStoryPanels(panels: readonly CheckedPanel[], playback: PanelPlayback, lookup: PanelLookup): StoryPanelSet;
@@ -0,0 +1,111 @@
1
+ import { createProvenance, PROVENANCE_SOURCE_TYPES } from "./provenance.js";
2
+ import { timeInputMs } from "./timeInput.js";
3
+ export const DEFAULT_PANEL_PAUSE_SECONDS = 6;
4
+ export const MAX_PANEL_PAUSE_SECONDS = 20;
5
+ export const DEFAULT_PANEL_PLAYBACK = Object.freeze({ pauseSeconds: DEFAULT_PANEL_PAUSE_SECONDS, autoOpen: true });
6
+ /** A panel's settings entry is wrong; the message names the panel and the field. */
7
+ export class StoryPanelError extends Error {
8
+ constructor(panel, field, problem) {
9
+ super(`story panel ${panel}: ${field} ${problem}`);
10
+ this.name = "StoryPanelError";
11
+ }
12
+ }
13
+ const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
14
+ function text(panel, field, value) {
15
+ if (typeof value !== "string" || value.trim() === "")
16
+ throw new StoryPanelError(panel, field, "must be non-empty text");
17
+ return value;
18
+ }
19
+ function lines(panel, field, value) {
20
+ const list = typeof value === "string" ? [value] : value;
21
+ if (!Array.isArray(list) || list.length === 0)
22
+ throw new StoryPanelError(panel, field, "must be one or more non-empty lines");
23
+ return list.map((line, index) => text(panel, `${field}[${index}]`, line));
24
+ }
25
+ function atOf(panel, at) {
26
+ if (!isRecord(at))
27
+ throw new StoryPanelError(panel, "at", "must name a time: { time }, { event } or { anchor }");
28
+ const keys = ["time", "event", "anchor"].filter((key) => at[key] !== undefined);
29
+ if (keys.length !== 1)
30
+ throw new StoryPanelError(panel, "at", "must give exactly one of time, event or anchor");
31
+ if (keys[0] === "event")
32
+ return { event: text(panel, "at.event", at.event) };
33
+ if (keys[0] === "anchor")
34
+ return { anchor: text(panel, "at.anchor", at.anchor) };
35
+ const timeUtcMs = timeInputMs(at.time);
36
+ if (!Number.isFinite(timeUtcMs))
37
+ throw new StoryPanelError(panel, "at.time", `must be a valid moment (ISO text, a Date or Unix milliseconds), got ${JSON.stringify(at.time)}`);
38
+ return { timeUtcMs };
39
+ }
40
+ function provenanceOf(panel, value) {
41
+ if (!isRecord(value))
42
+ throw new StoryPanelError(panel, "provenance", "must be an object: { sourceType, sources, accuracy, notes }");
43
+ if (!PROVENANCE_SOURCE_TYPES.includes(value.sourceType))
44
+ throw new StoryPanelError(panel, "provenance.sourceType", `must be one of ${PROVENANCE_SOURCE_TYPES.join(", ")}, got ${JSON.stringify(value.sourceType)}`);
45
+ if (!Array.isArray(value.sources))
46
+ throw new StoryPanelError(panel, "provenance.sources", "must be one or more non-empty lines");
47
+ lines(panel, "provenance.sources", value.sources);
48
+ text(panel, "provenance.accuracy", value.accuracy);
49
+ if (typeof value.notes !== "string")
50
+ throw new StoryPanelError(panel, "provenance.notes", "must be text");
51
+ return createProvenance(value);
52
+ }
53
+ /** Checks the shape of one panel, the `index`th of the list it came in. Nothing here looks at the scene: links are `resolveStoryPanels`' job. */
54
+ export function checkStoryPanel(raw, index) {
55
+ if (!isRecord(raw))
56
+ throw new StoryPanelError(`#${index + 1}`, "entry", "must be an object");
57
+ const id = text(`#${index + 1}`, "id", raw.id);
58
+ const object = raw.object === undefined ? undefined : text(id, "object", raw.object);
59
+ return {
60
+ id,
61
+ at: atOf(id, raw.at),
62
+ title: text(id, "title", raw.title),
63
+ body: lines(id, "body", raw.body),
64
+ details: raw.details === undefined ? [] : lines(id, "details", raw.details),
65
+ provenance: provenanceOf(id, raw.provenance),
66
+ ...(object === undefined ? {} : { object }),
67
+ };
68
+ }
69
+ /** Checks the two playback settings; a setting left out takes its default, so the result is the whole setting. */
70
+ export function checkPanelPlayback(raw) {
71
+ if (!isRecord(raw))
72
+ throw new StoryPanelError("settings", "playback", "must be an object: { pauseSeconds?, autoOpen? }");
73
+ const pauseSeconds = raw.pauseSeconds ?? DEFAULT_PANEL_PLAYBACK.pauseSeconds;
74
+ if (typeof pauseSeconds !== "number" || !Number.isFinite(pauseSeconds) || pauseSeconds < 0 || pauseSeconds > MAX_PANEL_PAUSE_SECONDS) {
75
+ throw new StoryPanelError("settings", "pauseSeconds", `must be between 0 and ${MAX_PANEL_PAUSE_SECONDS}, got ${JSON.stringify(pauseSeconds)}`);
76
+ }
77
+ const autoOpen = raw.autoOpen ?? DEFAULT_PANEL_PLAYBACK.autoOpen;
78
+ if (typeof autoOpen !== "boolean")
79
+ throw new StoryPanelError("settings", "autoOpen", "must be true or false");
80
+ return { pauseSeconds, autoOpen };
81
+ }
82
+ function timeOf({ id, at }, lookup) {
83
+ if ("timeUtcMs" in at)
84
+ return at.timeUtcMs;
85
+ if ("event" in at) {
86
+ const event = lookup.events.find((candidate) => candidate.id === at.event);
87
+ if (event === undefined)
88
+ throw new StoryPanelError(id, "at.event", `names "${at.event}", which the experience's events lack`);
89
+ return event.timeUtcMs;
90
+ }
91
+ const anchor = lookup.anchors?.get(at.anchor);
92
+ if (anchor === undefined)
93
+ throw new StoryPanelError(id, "at.anchor", `names "${at.anchor}", which the experience's anchors lack`);
94
+ return anchor;
95
+ }
96
+ function resolvePanel(panel, lookup) {
97
+ const { id, title, body, details, provenance, object } = panel;
98
+ const timeUtcMs = timeOf(panel, lookup);
99
+ if (lookup.window !== undefined && (timeUtcMs < lookup.window.startUtcMs || timeUtcMs > lookup.window.endUtcMs)) {
100
+ throw new StoryPanelError(id, "at", "falls outside the timeline window");
101
+ }
102
+ if (object !== undefined && lookup.objectIds !== undefined && !lookup.objectIds.includes(object)) {
103
+ throw new StoryPanelError(id, "object", `names "${object}", which the experience lacks`);
104
+ }
105
+ return { id, timeUtcMs, title, body, details, provenance, ...(object === undefined ? {} : { objectId: object }) };
106
+ }
107
+ /** Resolves each checked panel's time and links against the scene as built. Panels come back sorted by time. */
108
+ export function resolveStoryPanels(panels, playback, lookup) {
109
+ const resolved = panels.map((panel) => resolvePanel(panel, lookup));
110
+ return { panels: resolved.sort((a, b) => a.timeUtcMs - b.timeUtcMs), ...playback };
111
+ }
@@ -53,6 +53,10 @@ export declare function samplePositionsKm(source: Trajectory, timesUtcMs: readon
53
53
  * its end inclusive: 3 × count values. This is all a path is; no orbit maths lives here.
54
54
  */
55
55
  export declare function samplePathKm(source: Trajectory, span: TimeBounds, count: number, center?: CenterId): Float64Array;
56
+ /** The turn search found no full turn within its steps; a `RangeError` so existing range handlers still see it. */
57
+ export declare class NoFullTurnError extends RangeError {
58
+ constructor(maxSteps: number, stepMs: number);
59
+ }
56
60
  /**
57
61
  * How long a state source takes to sweep one full turn about its centre, found by walking forward from `startUtcMs` in `stepMs` steps,
58
62
  * adding the angle between successive positions, and interpolating inside the step that completes the turn. For a path that should
@@ -50,7 +50,7 @@ export function createTwoBodyTrajectory(input, adapter) {
50
50
  assertWithinBounds(bounds, timeUtcMs);
51
51
  const position = new Float64Array(3);
52
52
  adapter.propagateMemberInto(states, 0, (timeUtcMs - epochUtcMs) / 1000, native, position);
53
- return createState({ body, center: native, timeUtcMs, frame: EQJ, positionKm: position, orientation: null });
53
+ return createState({ body, center: native, timeUtcMs, plane: EQJ, positionKm: position, orientation: null });
54
54
  },
55
55
  });
56
56
  }
@@ -155,6 +155,13 @@ export function samplePositionsKm(source, timesUtcMs, center) {
155
155
  export function samplePathKm(source, span, count, center) {
156
156
  return samplePositionsKm(source, pathTimesUtcMs(span, count), center);
157
157
  }
158
+ /** The turn search found no full turn within its steps; a `RangeError` so existing range handlers still see it. */
159
+ export class NoFullTurnError extends RangeError {
160
+ constructor(maxSteps, stepMs) {
161
+ super(`no full turn within ${maxSteps} steps of ${stepMs} ms`);
162
+ this.name = "NoFullTurnError";
163
+ }
164
+ }
158
165
  /**
159
166
  * How long a state source takes to sweep one full turn about its centre, found by walking forward from `startUtcMs` in `stepMs` steps,
160
167
  * adding the angle between successive positions, and interpolating inside the step that completes the turn. For a path that should
@@ -175,5 +182,5 @@ export function fullTurnSpanMs(source, startUtcMs, stepMs, maxSteps, center) {
175
182
  swept += angle;
176
183
  previous = next;
177
184
  }
178
- throw new RangeError(`no full turn within ${maxSteps} steps of ${stepMs} ms`);
185
+ throw new NoFullTurnError(maxSteps, stepMs);
179
186
  }
@@ -0,0 +1,4 @@
1
+ /** A moment: ISO text, a Date, or Unix milliseconds. Declared here so `core/` records can take one; the public `TimeInput` is this type. */
2
+ export type TimeInput = string | number | Date;
3
+ /** The moment as Unix milliseconds, or NaN when it is not one. The one conversion every moment input goes through; each caller reports a bad moment in its own words. */
4
+ export declare function timeInputMs(time: TimeInput): number;
@@ -0,0 +1,4 @@
1
+ /** The moment as Unix milliseconds, or NaN when it is not one. The one conversion every moment input goes through; each caller reports a bad moment in its own words. */
2
+ export function timeInputMs(time) {
3
+ return time instanceof Date ? time.getTime() : typeof time === "number" ? time : Date.parse(time);
4
+ }