astraeus 0.7.0 → 0.8.1

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 (287) hide show
  1. package/CHANGELOG.md +189 -0
  2. package/README.md +202 -38
  3. package/data/ephemerides/planets/planets.json +1 -1
  4. package/package.json +5 -4
  5. package/src/api/AstraeusScene.d.ts +21 -5
  6. package/src/api/AstraeusScene.js +34 -10
  7. package/src/api/AstraeusScene.node.js +34 -10
  8. package/src/api/assembleScene.d.ts +36 -0
  9. package/src/api/assembleScene.js +175 -0
  10. package/src/api/bodySetChecks.d.ts +10 -0
  11. package/src/api/bodySetChecks.js +117 -0
  12. package/src/api/bodySetInput.d.ts +81 -0
  13. package/src/api/bodySetInput.js +1 -0
  14. package/src/api/containingBlock.d.ts +6 -0
  15. package/src/api/containingBlock.js +16 -0
  16. package/src/api/data.d.ts +17 -5
  17. package/src/api/data.js +28 -10
  18. package/src/api/definitionOf.d.ts +16 -0
  19. package/src/api/definitionOf.js +20 -0
  20. package/src/api/errors.d.ts +63 -1
  21. package/src/api/frozenCopy.d.ts +6 -0
  22. package/src/api/frozenCopy.js +26 -0
  23. package/src/api/group.d.ts +8 -2
  24. package/src/api/group.js +24 -5
  25. package/src/api/index.d.ts +18 -7
  26. package/src/api/index.js +2 -2
  27. package/src/api/index.node.js +2 -2
  28. package/src/api/listeners.d.ts +5 -0
  29. package/src/api/listeners.js +25 -0
  30. package/src/api/look.d.ts +47 -0
  31. package/src/api/look.js +1 -0
  32. package/src/api/lookInput.d.ts +3 -0
  33. package/src/api/lookInput.js +41 -0
  34. package/src/api/moonPanelInput.d.ts +60 -0
  35. package/src/api/moonPanelInput.js +1 -0
  36. package/src/api/mount.d.ts +9 -19
  37. package/src/api/mount.js +27 -13
  38. package/src/api/mount.node.js +27 -13
  39. package/src/api/pathProvenance.js +1 -1
  40. package/src/api/pickerInput.d.ts +25 -0
  41. package/src/api/pickerInput.js +1 -0
  42. package/src/api/planBodies.d.ts +72 -0
  43. package/src/api/planBodies.js +300 -0
  44. package/src/api/planBodySets.d.ts +68 -0
  45. package/src/api/planBodySets.js +234 -0
  46. package/src/api/planCamera.d.ts +83 -0
  47. package/src/api/planCamera.js +184 -0
  48. package/src/api/planGroups.d.ts +36 -0
  49. package/src/api/planGroups.js +103 -0
  50. package/src/api/planMoonPanel.d.ts +19 -0
  51. package/src/api/planMoonPanel.js +104 -0
  52. package/src/api/planPaths.d.ts +40 -0
  53. package/src/api/planPaths.js +212 -0
  54. package/src/api/planPicker.d.ts +12 -0
  55. package/src/api/planPicker.js +40 -0
  56. package/src/api/planPlaces.d.ts +16 -0
  57. package/src/api/planPlaces.js +99 -0
  58. package/src/api/planStory.d.ts +26 -0
  59. package/src/api/planStory.js +66 -0
  60. package/src/api/planTimeline.d.ts +27 -0
  61. package/src/api/planTimeline.js +68 -0
  62. package/src/api/planViews.d.ts +25 -0
  63. package/src/api/planViews.js +35 -0
  64. package/src/api/prepared.js +4 -1
  65. package/src/api/renamedInputs.d.ts +15 -0
  66. package/src/api/renamedInputs.js +39 -0
  67. package/src/api/scene.d.ts +162 -68
  68. package/src/api/scene.js +247 -793
  69. package/src/api/sceneFreeze.d.ts +4 -0
  70. package/src/api/sceneFreeze.js +10 -0
  71. package/src/api/sceneReads.d.ts +171 -0
  72. package/src/api/sceneReads.js +6 -0
  73. package/src/api/story.d.ts +49 -19
  74. package/src/api/story.js +54 -22
  75. package/src/api/sunOrbit.js +9 -11
  76. package/src/api/time.d.ts +2 -1
  77. package/src/api/time.js +2 -1
  78. package/src/api/viewerCamera.d.ts +22 -0
  79. package/src/api/viewerCamera.js +84 -0
  80. package/src/api/viewerClock.d.ts +30 -0
  81. package/src/api/viewerClock.js +85 -0
  82. package/src/api/viewerFirstDraw.d.ts +14 -0
  83. package/src/api/viewerFirstDraw.js +26 -0
  84. package/src/api/viewerHandle.d.ts +85 -0
  85. package/src/api/viewerHandle.js +32 -0
  86. package/src/api/viewerLink.d.ts +88 -15
  87. package/src/api/viewerLink.js +117 -75
  88. package/src/api/viewerLooks.d.ts +19 -0
  89. package/src/api/viewerLooks.js +37 -0
  90. package/src/api/viewerPicker.d.ts +22 -0
  91. package/src/api/viewerPicker.js +49 -0
  92. package/src/api/viewerSelection.d.ts +30 -0
  93. package/src/api/viewerSelection.js +46 -0
  94. package/src/api/viewerViews.d.ts +10 -0
  95. package/src/api/viewerViews.js +18 -0
  96. package/src/api/viewerZones.d.ts +20 -0
  97. package/src/api/viewerZones.js +47 -0
  98. package/src/api/views.d.ts +7 -6
  99. package/src/api/views.js +12 -6
  100. package/src/app/App.d.ts +5 -3
  101. package/src/app/App.js +211 -82
  102. package/src/app/App.node.js +211 -82
  103. package/src/app/AstraeusScene.d.ts +18 -2
  104. package/src/app/AstraeusScene.js +4 -4
  105. package/src/app/BodyView.d.ts +4 -1
  106. package/src/app/BodyView.js +2 -2
  107. package/src/app/CameraController.d.ts +6 -0
  108. package/src/app/DeveloperSettings.d.ts +1 -4
  109. package/src/app/DeveloperSettings.js +6 -10
  110. package/src/app/FeatureMarkers.d.ts +4 -3
  111. package/src/app/FeatureMarkers.js +8 -13
  112. package/src/app/FrameRateSection.js +2 -1
  113. package/src/app/OrbitSetView.js +1 -1
  114. package/src/app/SettingControls.d.ts +11 -3
  115. package/src/app/SettingControls.js +10 -2
  116. package/src/app/SkyView.d.ts +3 -10
  117. package/src/app/SkyView.js +6 -28
  118. package/src/app/address.d.ts +16 -0
  119. package/src/app/address.js +31 -0
  120. package/src/app/bodyDraw.d.ts +10 -7
  121. package/src/app/bodyDraw.js +12 -32
  122. package/src/app/bodyMetrics.js +2 -2
  123. package/src/app/bodySet.d.ts +4 -20
  124. package/src/app/bodySet.js +5 -16
  125. package/src/app/debugReadout.js +1 -1
  126. package/src/app/displaySwitches.d.ts +4 -0
  127. package/src/app/displaySwitches.js +6 -0
  128. package/src/app/experienceDefinition.d.ts +11 -23
  129. package/src/app/listSwitch.d.ts +8 -14
  130. package/src/app/listSwitch.js +3 -10
  131. package/src/app/liveLook.d.ts +39 -0
  132. package/src/app/liveLook.js +66 -0
  133. package/src/app/look.d.ts +36 -0
  134. package/src/app/look.js +61 -0
  135. package/src/app/mission.d.ts +1 -1
  136. package/src/app/mission.js +1 -1
  137. package/src/app/openClock.d.ts +3 -2
  138. package/src/app/openClock.js +3 -3
  139. package/src/app/sceneCamera.d.ts +2 -0
  140. package/src/app/sceneCamera.js +11 -1
  141. package/src/app/sceneFrame.d.ts +4 -4
  142. package/src/app/sceneFrame.js +13 -8
  143. package/src/app/sceneHooks.js +3 -2
  144. package/src/app/style.css +114 -139
  145. package/src/app/trackedMetrics.d.ts +10 -3
  146. package/src/app/trackedMetrics.js +22 -11
  147. package/src/app/viewLink.d.ts +10 -32
  148. package/src/app/viewLink.js +10 -49
  149. package/src/app/viewerPort.d.ts +52 -0
  150. package/src/app/views.d.ts +3 -0
  151. package/src/assets/bodies/galileanMoons.js +1 -2
  152. package/src/assets/bodies/io.js +2 -2
  153. package/src/assets/bodies/listedMoons.d.ts +1 -1
  154. package/src/assets/bodies/listedMoons.js +2 -3
  155. package/src/assets/bodies/planetSystemMaps.js +2 -3
  156. package/src/assets/bodies/venus.js +2 -6
  157. package/src/assets/catalogue.js +1 -2
  158. package/src/assets/licence.d.ts +3 -3
  159. package/src/assets/licence.js +3 -3
  160. package/src/assets/pictures.d.ts +15 -12
  161. package/src/assets/pictures.js +24 -20
  162. package/src/assets/sky.d.ts +6 -5
  163. package/src/assets/sky.js +6 -9
  164. package/src/assets/visual.d.ts +4 -0
  165. package/src/core/astronomyAdapter.d.ts +1 -1
  166. package/src/core/astronomyAdapter.js +3 -3
  167. package/src/core/bodies/index.d.ts +0 -4
  168. package/src/core/bodies/index.js +14 -18
  169. package/src/core/bodies/jupiter.js +1 -1
  170. package/src/core/bodies/jupiterData.d.ts +0 -1
  171. package/src/core/bodies/jupiterData.js +2 -5
  172. package/src/core/bodies/mars.js +1 -1
  173. package/src/core/bodies/mercury.js +1 -1
  174. package/src/core/bodies/moonSystem.d.ts +1 -1
  175. package/src/core/bodies/moonSystem.js +102 -55
  176. package/src/core/bodies/outerPlanetRingData.js +2 -2
  177. package/src/core/bodies/outerPlanets.d.ts +2 -3
  178. package/src/core/bodies/outerPlanets.js +4 -13
  179. package/src/core/bodies/planetMoons.d.ts +0 -2
  180. package/src/core/bodies/planetMoons.js +1 -18
  181. package/src/core/bodies/planetRecords.d.ts +8 -2
  182. package/src/core/bodies/planetRecords.js +13 -5
  183. package/src/core/bodies/planetTrajectory.d.ts +21 -4
  184. package/src/core/bodies/planetTrajectory.js +29 -5
  185. package/src/core/bodies/venus.js +1 -1
  186. package/src/core/bodySetFamilies.d.ts +20 -0
  187. package/src/core/bodySetFamilies.js +14 -0
  188. package/src/core/chebyshevEphemeris.js +1 -1
  189. package/src/core/elementsBody.d.ts +8 -4
  190. package/src/core/elementsBody.js +32 -11
  191. package/src/core/elementsGroup.d.ts +27 -0
  192. package/src/core/elementsGroup.js +85 -0
  193. package/src/core/events.d.ts +2 -0
  194. package/src/core/events.js +2 -0
  195. package/src/core/illumination.js +1 -1
  196. package/src/core/listedOrbitGroup.d.ts +2 -0
  197. package/src/core/listedOrbitGroup.js +11 -7
  198. package/src/core/moonListText.d.ts +6 -0
  199. package/src/core/moonListText.js +19 -0
  200. package/src/core/moonTrajectory.js +1 -1
  201. package/src/core/pacing.d.ts +38 -3
  202. package/src/core/pacing.js +55 -4
  203. package/src/core/planetModels.d.ts +1 -1
  204. package/src/core/planetModels.js +3 -3
  205. package/src/core/planetSeries.d.ts +10 -2
  206. package/src/core/planetSeries.js +17 -3
  207. package/src/core/pointGroup.js +1 -1
  208. package/src/core/provenance.d.ts +2 -1
  209. package/src/core/provenance.js +2 -2
  210. package/src/core/referenceCenters.js +5 -5
  211. package/src/core/sampledTrajectory.js +1 -1
  212. package/src/core/scalePolicy.d.ts +1 -0
  213. package/src/core/startView.d.ts +19 -0
  214. package/src/core/startView.js +28 -0
  215. package/src/core/state.d.ts +6 -2
  216. package/src/core/state.js +3 -3
  217. package/src/core/storyPanels.d.ts +63 -0
  218. package/src/core/storyPanels.js +111 -0
  219. package/src/core/sunCentredSources.d.ts +4 -0
  220. package/src/core/sunCentredSources.js +9 -2
  221. package/src/core/timeInput.d.ts +4 -0
  222. package/src/core/timeInput.js +4 -0
  223. package/src/shell/AstraeusShell.d.ts +18 -2
  224. package/src/shell/AstraeusShell.js +53 -14
  225. package/src/shell/AstraeusShell.node.js +53 -14
  226. package/src/shell/Collapsible.d.ts +4 -3
  227. package/src/shell/Collapsible.js +5 -5
  228. package/src/shell/ControlsDrawer.d.ts +1 -1
  229. package/src/shell/ControlsDrawer.js +3 -1
  230. package/src/shell/DisplaySwitches.js +2 -1
  231. package/src/shell/InfoPanel.d.ts +3 -1
  232. package/src/shell/InfoPanel.js +5 -4
  233. package/src/shell/MoonFamilyPanel.js +1 -1
  234. package/src/shell/ObjectControls.d.ts +3 -1
  235. package/src/shell/ObjectControls.js +2 -2
  236. package/src/shell/Sources.d.ts +5 -3
  237. package/src/shell/Sources.js +5 -5
  238. package/src/shell/StoryPanelView.d.ts +4 -3
  239. package/src/shell/StoryPanelView.js +8 -6
  240. package/src/shell/SwitchControl.d.ts +5 -11
  241. package/src/shell/SwitchControl.js +2 -20
  242. package/src/shell/TimelineBar.css +81 -81
  243. package/src/shell/TimelineBar.d.ts +5 -2
  244. package/src/shell/TimelineBar.js +9 -8
  245. package/src/shell/TimelineBar.node.js +9 -8
  246. package/src/shell/TopBar.css +22 -22
  247. package/src/shell/TopBar.d.ts +5 -1
  248. package/src/shell/TopBar.js +2 -2
  249. package/src/shell/TopBar.node.js +2 -2
  250. package/src/shell/bootLoader.d.ts +4 -10
  251. package/src/shell/bootLoader.js +6 -52
  252. package/src/shell/embedded.css +18 -18
  253. package/src/shell/experience.d.ts +1 -1
  254. package/src/shell/moonFamilies.d.ts +2 -6
  255. package/src/shell/moonFamilies.js +2 -18
  256. package/src/shell/phone.css +58 -58
  257. package/src/shell/storyPanels.d.ts +2 -53
  258. package/src/shell/storyPanels.js +1 -106
  259. package/src/shell/style.css +153 -134
  260. package/src/shell/useDrawers.d.ts +3 -2
  261. package/src/shell/useDrawers.js +4 -3
  262. package/src/shell/viewerKeys.d.ts +8 -0
  263. package/src/shell/viewerKeys.js +16 -0
  264. package/src/synthetic/syntheticDefinition.js +20 -24
  265. package/src/synthetic/syntheticJourneyScene.js +3 -3
  266. package/src/synthetic/syntheticProbeDefinition.js +2 -1
  267. package/src/synthetic/syntheticViewsDefinition.d.ts +0 -3
  268. package/src/synthetic/syntheticViewsDefinition.js +10 -16
  269. package/data/moons/jupiter.json +0 -3333
  270. package/data/moons/neptune.json +0 -555
  271. package/data/moons/pluto.json +0 -205
  272. package/data/moons/saturn.json +0 -8267
  273. package/data/moons/uranus.json +0 -887
  274. package/src/app/addressNavigation.d.ts +0 -17
  275. package/src/app/addressNavigation.js +0 -16
  276. package/src/assets/bodies/jupiterMoonCatalogue.d.ts +0 -3
  277. package/src/assets/bodies/jupiterMoonCatalogue.js +0 -4
  278. package/src/assets/bodies/outerPlanetCatalogues.d.ts +0 -7
  279. package/src/assets/bodies/outerPlanetCatalogues.js +0 -8
  280. package/src/assets/bodies/swiftTuttle.d.ts +0 -12
  281. package/src/assets/bodies/swiftTuttle.js +0 -13
  282. package/src/assets/moonCatalogue.d.ts +0 -49
  283. package/src/assets/moonCatalogue.js +0 -80
  284. package/src/core/bodies/outerPlanetData.d.ts +0 -4
  285. package/src/core/bodies/outerPlanetData.js +0 -13
  286. package/src/core/bodies/swiftTuttle.d.ts +0 -46
  287. package/src/core/bodies/swiftTuttle.js +0 -106
@@ -31,7 +31,21 @@ export class ElementsBodyError extends TypeError {
31
31
  function fail(path, problem) {
32
32
  throw new ElementsBodyError(`body record ${path} ${problem}`);
33
33
  }
34
- const { record, text, finite, instant } = fieldReaders(fail);
34
+ const { record, text, finite } = fieldReaders(fail);
35
+ /** A moment a record gives: ISO text (kept as written), a Date or Unix milliseconds (both returned as ISO text); anything else is refused naming the field. */
36
+ function moment(parent, key, path) {
37
+ const value = parent[key];
38
+ if (typeof value === "string") {
39
+ if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(value) || !Number.isFinite(Date.parse(value))) {
40
+ fail(`${path}.${key}`, `must be an ISO-8601 UTC time like 2030-01-01T00:00:00Z, got "${value}"`);
41
+ }
42
+ return value;
43
+ }
44
+ const ms = value instanceof Date ? value.getTime() : value;
45
+ if (typeof ms !== "number" || !Number.isFinite(ms))
46
+ fail(`${path}.${key}`, `is required and must be an ISO-8601 UTC time like 2030-01-01T00:00:00Z, a Date or Unix milliseconds, got ${String(value)}`);
47
+ return new Date(ms).toISOString();
48
+ }
35
49
  /** The five orbit-shape elements and the one placement along the orbit (exactly one of mean anomaly and perihelion time). */
36
50
  function parseOrbitElements(raw, here) {
37
51
  const semiMajorAxisAu = finite(raw, "semiMajorAxisAu", here);
@@ -86,14 +100,19 @@ function parseAccuracy(raw, here) {
86
100
  const classification = raw.classification;
87
101
  if (classification !== "approximate" && classification !== "indicative")
88
102
  fail(`${here}.classification`, `must be "approximate" or "indicative", got ${String(classification)}`);
89
- const validFromUtc = instant(raw, "validFromUtc", here);
90
- const validToUtc = instant(raw, "validToUtc", here);
91
- if (Date.parse(validToUtc) <= Date.parse(validFromUtc))
92
- fail(`${here}.validToUtc`, "must be after accuracy.validFromUtc");
103
+ for (const [old, use] of [["validFromUtc", "valid.start"], ["validToUtc", "valid.end"]]) {
104
+ if (Object.hasOwn(raw, old))
105
+ fail(`${here}.${old}`, `is now \`${use}\` inside \`valid: { start, end }\` (the old name is not accepted)`);
106
+ }
107
+ const valid = record(raw.valid, `${here}.valid`);
108
+ const start = moment(valid, "start", `${here}.valid`);
109
+ const end = moment(valid, "end", `${here}.valid`);
110
+ if (Date.parse(end) <= Date.parse(start))
111
+ fail(`${here}.valid.end`, "must be after accuracy.valid.start");
93
112
  const limitations = raw.limitations ?? [];
94
113
  if (!Array.isArray(limitations) || limitations.some((item) => typeof item !== "string" || item.trim().length === 0))
95
114
  fail(`${here}.limitations`, "must be a list of non-empty text");
96
- return { classification, statement: text(raw, "statement", here), validFromUtc, validToUtc, limitations: [...limitations] };
115
+ return { classification, statement: text(raw, "statement", here), valid: { start, end }, limitations: [...limitations] };
97
116
  }
98
117
  function parseMarker(raw, here) {
99
118
  const color = raw.color === undefined ? DEFAULT_ELEMENTS_MARKER_COLOUR : text(raw, "color", here);
@@ -113,13 +132,15 @@ export function parseElementsBodyRecord(input, path = "body") {
113
132
  const label = text(root, "label", path);
114
133
  const elements = parseOrbitElements(record(root.elements, `${path}.elements`), `${path}.elements`);
115
134
  const epoch = parseEpoch(record(root.epoch, `${path}.epoch`), `${path}.epoch`);
116
- if (root.frame !== "ecliptic-j2000")
117
- fail(`${path}.frame`, `must be "ecliptic-j2000", got ${String(root.frame)}`);
135
+ if (Object.hasOwn(root, "frame"))
136
+ fail(`${path}.frame`, "is now `plane` (the old name is not accepted)");
137
+ if (root.plane !== "ecliptic-j2000")
138
+ fail(`${path}.plane`, `must be "ecliptic-j2000", got ${String(root.plane)}`);
118
139
  const source = parseSource(record(root.source, `${path}.source`), `${path}.source`);
119
140
  const radius = root.radius === undefined ? undefined : parseRadius(record(root.radius, `${path}.radius`), `${path}.radius`);
120
141
  const accuracy = parseAccuracy(record(root.accuracy, `${path}.accuracy`), `${path}.accuracy`);
121
142
  const marker = parseMarker(root.marker === undefined ? {} : record(root.marker, `${path}.marker`), `${path}.marker`);
122
- return { id, label, elements, epoch, frame: "ecliptic-j2000", source, ...(radius === undefined ? {} : { radius }), accuracy, marker };
143
+ return { id, label, elements, epoch, plane: "ecliptic-j2000", source, ...(radius === undefined ? {} : { radius }), accuracy, marker };
123
144
  }
124
145
  /** The epoch of a record in UTC milliseconds. */
125
146
  export function epochUtcMsOf(epoch) {
@@ -151,7 +172,7 @@ export function buildElementsBody(input, centre) {
151
172
  const create = () => createTwoBodyTrajectory({
152
173
  body: body.id,
153
174
  center: centre.id,
154
- plane: body.frame,
175
+ plane: body.plane,
155
176
  epochUtcMs,
156
177
  elements: {
157
178
  semiMajorAxisKm,
@@ -187,7 +208,7 @@ export function buildElementsBody(input, centre) {
187
208
  accuracyClass: body.accuracy.classification,
188
209
  maxErrorFraction: body.accuracy.classification === "approximate" ? APPROXIMATE_LIMIT_FRACTION : INDICATIVE_LIMIT_FRACTION,
189
210
  }),
190
- validUtc: Object.freeze({ startUtcMs: Date.parse(body.accuracy.validFromUtc), endUtcMs: Date.parse(body.accuracy.validToUtc) }),
211
+ validUtc: Object.freeze({ startUtcMs: Date.parse(body.accuracy.valid.start), endUtcMs: Date.parse(body.accuracy.valid.end) }),
191
212
  orientationLimitations: Object.freeze([
192
213
  `Unperturbed two-body motion about the Sun from osculating elements at JD ${body.epoch.jd} ${body.epoch.timeScale}: no planetary perturbations and no non-gravitational forces.`,
193
214
  ...body.accuracy.limitations,
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Made-up members on two-body motion as a point group with the `EphemerisGroup` shape: each member has its own elements and moment, and the group
3
+ * answers the same questions a curve-fit group does (batch fill, one state, a position at any time, how far back the data reach), so a body set
4
+ * draws them with no change. Motion is unperturbed two-body about the centre; the centre's gravity comes from the adapter.
5
+ */
6
+ import type { BodyId, CenterId } from "./body.js";
7
+ import type { EphemerisGroup } from "./ephemerisGroup.js";
8
+ import { type ElementPlane, type OrbitElements } from "./orbitGroup.js";
9
+ import type { Provenance } from "./provenance.js";
10
+ import type { TimeBounds } from "./trajectory.js";
11
+ import type { TwoBodyAdapter } from "./twoBodyAdapter.js";
12
+ /** One member: its id, its elements (km, degrees) and the moment they hold. */
13
+ export interface ElementsGroupMember {
14
+ readonly id: BodyId;
15
+ readonly elements: OrbitElements;
16
+ readonly epochUtcMs: number;
17
+ /** The plane the elements are given in. */
18
+ readonly plane: ElementPlane;
19
+ }
20
+ export interface ElementsGroupInput {
21
+ readonly id: BodyId;
22
+ readonly center: CenterId;
23
+ readonly members: readonly ElementsGroupMember[];
24
+ readonly bounds: TimeBounds;
25
+ readonly provenance: Provenance;
26
+ }
27
+ export declare function createElementsGroup(input: ElementsGroupInput, adapter: TwoBodyAdapter): EphemerisGroup;
@@ -0,0 +1,85 @@
1
+ import { memberStatesOf, propagatedPositionOf } from "./orbitGroup.js";
2
+ import { assertFillBuffer, assertMemberIndex, assertWithinBounds, GroupElementsError, memberState } from "./pointGroup.js";
3
+ import { assertUtcUnixMs, EQJ, createState } from "./state.js";
4
+ const RADIANS = Math.PI / 180;
5
+ /** Half the step of the centred difference that gives a member's velocity, ms. */
6
+ const VELOCITY_HALF_STEP_MS = 500;
7
+ function classical(elements, id) {
8
+ for (const key of ["semiMajorAxisKm", "eccentricity", "inclinationDeg", "raanDeg", "argumentOfPeriapsisDeg", "trueAnomalyDeg"]) {
9
+ if (!Number.isFinite(elements[key]))
10
+ throw new GroupElementsError(`member "${id}" ${key} must be finite`);
11
+ }
12
+ const { semiMajorAxisKm, eccentricity } = elements;
13
+ if (!(semiMajorAxisKm > 0) || !(eccentricity >= 0 && eccentricity < 1))
14
+ throw new GroupElementsError(`member "${id}" needs a bound orbit: a positive semi-major axis and an eccentricity from 0 to below 1`);
15
+ if (!(elements.inclinationDeg >= 0 && elements.inclinationDeg <= 180))
16
+ throw new GroupElementsError(`member "${id}" inclination must be from 0 to 180 degrees`);
17
+ return {
18
+ semiMajorAxisKm,
19
+ eccentricity,
20
+ inclinationRad: elements.inclinationDeg * RADIANS,
21
+ raanRad: elements.raanDeg * RADIANS,
22
+ argumentOfPeriapsisRad: elements.argumentOfPeriapsisDeg * RADIANS,
23
+ trueAnomalyRad: elements.trueAnomalyDeg * RADIANS,
24
+ };
25
+ }
26
+ export function createElementsGroup(input, adapter) {
27
+ const { id, center, bounds, provenance } = input;
28
+ const members = Object.freeze(input.members.map((member) => member.id));
29
+ if (members.length === 0)
30
+ throw new RangeError(`group "${id}" lists no members`);
31
+ if (new Set(members).size !== members.length)
32
+ throw new RangeError(`group "${id}" lists a member twice`);
33
+ if (!(bounds.endUtcMs >= bounds.startUtcMs))
34
+ throw new RangeError(`group "${id}" bounds end before they start`);
35
+ input.members.forEach((member) => assertUtcUnixMs(member.epochUtcMs));
36
+ // One state per member at its own moment: the shared placement takes each member's elements in turn.
37
+ const states = input.members.map((member) => memberStatesOf([classical(member.elements, member.id)], member.plane, center, adapter));
38
+ const count = members.length;
39
+ const one = new Float64Array(3);
40
+ const at = (index, timeUtcMs, out, offset) => {
41
+ assertMemberIndex(count, index);
42
+ assertUtcUnixMs(timeUtcMs);
43
+ out.set(propagatedPositionOf(states[index], 0, (timeUtcMs - input.members[index].epochUtcMs) / 1000, center, adapter), offset);
44
+ };
45
+ const group = {
46
+ id,
47
+ count,
48
+ center,
49
+ frame: EQJ,
50
+ bounds,
51
+ provenance,
52
+ members,
53
+ fillPositionsKm(timeUtcMs, out) {
54
+ assertWithinBounds(bounds, timeUtcMs);
55
+ assertFillBuffer(count, out);
56
+ for (let index = 0; index < count; index += 1)
57
+ at(index, timeUtcMs, out, 3 * index);
58
+ },
59
+ stateAt(index, timeUtcMs) {
60
+ assertWithinBounds(bounds, timeUtcMs);
61
+ at(index, timeUtcMs, one, 0);
62
+ return memberState(group, index, timeUtcMs, one);
63
+ },
64
+ memberPositionKmInto(index, timeUtcMs, out, offset) {
65
+ at(index, timeUtcMs, out, offset);
66
+ },
67
+ // Two-body motion needs no loaded data: it reaches back as far as asked.
68
+ memberLoadedFromUtcMs(index) {
69
+ assertMemberIndex(count, index);
70
+ return -Infinity;
71
+ },
72
+ memberStateAt(index, timeUtcMs) {
73
+ assertWithinBounds(bounds, timeUtcMs);
74
+ const here = new Float64Array(3);
75
+ const before = new Float64Array(3);
76
+ const after = new Float64Array(3);
77
+ at(index, timeUtcMs, here, 0);
78
+ at(index, timeUtcMs - VELOCITY_HALF_STEP_MS, before, 0);
79
+ at(index, timeUtcMs + VELOCITY_HALF_STEP_MS, after, 0);
80
+ const velocityKmS = Float64Array.from([0, 1, 2].map((k) => (after[k] - before[k]) / (2 * VELOCITY_HALF_STEP_MS / 1000)));
81
+ return createState({ body: members[index], center, timeUtcMs, plane: EQJ, positionKm: here, velocityKmS, orientation: null });
82
+ },
83
+ };
84
+ return Object.freeze(group);
85
+ }
@@ -6,6 +6,8 @@ export interface TimelineEvent {
6
6
  readonly type?: string;
7
7
  /** The id of an object in the scene the event is about; Go to frames it. */
8
8
  readonly object?: string;
9
+ /** Half-width of the event's own zone, in simulated milliseconds: the zone is `timeUtcMs ± withinMs`. Absent: the event has no zone of its own (a pacing rule may still give it one). */
10
+ readonly withinMs?: number;
9
11
  }
10
12
  /** Validates and returns a frozen copy: times sorted ascending (ties allowed), ids unique. */
11
13
  export declare function createEvents(input: readonly TimelineEvent[]): readonly TimelineEvent[];
@@ -11,6 +11,8 @@ export function createEvents(input) {
11
11
  throw new RangeError(`duplicate event id "${event.id}"`);
12
12
  if (event.timeUtcMs < previousMs)
13
13
  throw new RangeError("events must be sorted by time");
14
+ if (event.withinMs !== undefined && !(Number.isFinite(event.withinMs) && event.withinMs > 0))
15
+ throw new RangeError(`event "${event.id}" withinMs must be positive and finite`);
14
16
  ids.add(event.id);
15
17
  previousMs = event.timeUtcMs;
16
18
  }
@@ -10,7 +10,7 @@ function unit(vector, label) {
10
10
  function validateSameCenter(a, b) {
11
11
  if (a.timeUtcMs !== b.timeUtcMs)
12
12
  throw new RangeError("illumination geometry requires identical timestamps");
13
- if (a.frame !== b.frame)
13
+ if (a.plane !== b.plane)
14
14
  throw new RangeError("illumination geometry requires identical frames");
15
15
  if (a.center !== b.center)
16
16
  throw new RangeError("illumination geometry requires positions with the same center");
@@ -57,6 +57,8 @@ export declare function eccentricAnomalyRad(meanAnomalyRad: number, e: number):
57
57
  export declare function trueAnomalyFromMeanRad(meanAnomalyRad: number, e: number): number;
58
58
  /** Mean anomaly (radians, 0 to 2π) of a body with the given position and velocity about a centre of gravitational parameter `mu`. */
59
59
  export declare function meanAnomalyFromStateRad(r: ArrayLike<number>, v: ArrayLike<number>, mu: number): number;
60
+ /** The provenance a group's own card carries: always illustrative, since the position along each orbit is a drawing choice; the source's type stays in the accuracy line. */
61
+ export declare function listedGroupProvenance(source: Provenance, concentrated: boolean): Provenance;
60
62
  /**
61
63
  * A group drawn from a list of measured orbits: each member has its own elements, record time and source record id. Only the
62
64
  * position along each orbit is chosen here (see ListedPhase); every member then moves on its own ellipse by two-body motion.
@@ -147,6 +147,15 @@ function assignMeanAnomaliesDeg(count, phase, referenceDeg) {
147
147
  const PHASE_NOTE = "Each orbit's shape and orientation come from its record, but the records give no position along the orbit: "
148
148
  + "that position is an even spread of mean anomaly at the reference time, a drawing choice (illustrative), advanced by unperturbed two-body motion about the centre.";
149
149
  const CONCENTRATION_NOTE = "A stated share of the dots is placed near the reference body's position along the orbit: a model, not a measurement. No orbit is added.";
150
+ /** The provenance a group's own card carries: always illustrative, since the position along each orbit is a drawing choice; the source's type stays in the accuracy line. */
151
+ export function listedGroupProvenance(source, concentrated) {
152
+ return createProvenance({
153
+ sourceType: "illustrative",
154
+ sources: source.sources,
155
+ accuracy: `${source.accuracy} Orbit elements are as listed (${source.sourceType}); the position along each orbit is illustrative.`.trim(),
156
+ notes: `${source.notes} ${PHASE_NOTE}${concentrated ? ` ${CONCENTRATION_NOTE}` : ""}`.trim(),
157
+ });
158
+ }
150
159
  /**
151
160
  * A group drawn from a list of measured orbits: each member has its own elements, record time and source record id. Only the
152
161
  * position along each orbit is chosen here (see ListedPhase); every member then moves on its own ellipse by two-body motion.
@@ -171,12 +180,7 @@ export function createListedOrbitGroup(input, adapter) {
171
180
  trueAnomalyRad: trueAnomalyFromMeanRad(anomaliesDeg[member] * RADIANS, elements.eccentricity),
172
181
  })), input.plane, center, adapter);
173
182
  const recordIds = input.members.map((member) => member.recordId);
174
- const provenance = createProvenance({
175
- sourceType: "illustrative",
176
- sources: input.provenance.sources,
177
- accuracy: `${input.provenance.accuracy} Orbit elements are as listed (${input.provenance.sourceType}); the position along each orbit is illustrative.`.trim(),
178
- notes: `${input.provenance.notes} ${PHASE_NOTE}${concentration === undefined ? "" : ` ${CONCENTRATION_NOTE}`}`.trim(),
179
- });
183
+ const provenance = listedGroupProvenance(input.provenance, concentration !== undefined);
180
184
  let kepler = null;
181
185
  const group = {
182
186
  id: input.id,
@@ -206,7 +210,7 @@ export function createListedOrbitGroup(input, adapter) {
206
210
  assertUtcUnixMs(timeUtcMs);
207
211
  assertWithinBounds(bounds, timeUtcMs);
208
212
  const position = propagatedPositionOf(states, index, (timeUtcMs - referenceUtcMs) / 1000, center, adapter);
209
- return createState({ body: `${input.id}:${recordIds[index]}`, center, timeUtcMs, frame: EQJ, positionKm: position, orientation: null });
213
+ return createState({ body: `${input.id}:${recordIds[index]}`, center, timeUtcMs, plane: EQJ, positionKm: position, orientation: null });
210
214
  },
211
215
  recordIdAt(index) {
212
216
  assertMemberIndex(count, index);
@@ -0,0 +1,6 @@
1
+ /** A family's heading count: "5 moons", "1 moon". */
2
+ export declare function moonCountText(count: number): string;
3
+ /** A date from the data (YYYY-MM-DD, or an ISO timestamp) as "18 October 2026"; the text itself when it is not a date. */
4
+ export declare function moonListDateText(date: string): string;
5
+ /** "115 moons in the JPL Horizons list of 18 October 2026": the count is the moons the list holds, the source and date come from the data. */
6
+ export declare function moonListSummary(count: number, source?: string, date?: string): string;
@@ -0,0 +1,19 @@
1
+ // The words of a moon list's count line, shared by the moon panel and `Scene.moonPanel` (no display code here, so the api can use it without loading the panel).
2
+ /** A family's heading count: "5 moons", "1 moon". */
3
+ export function moonCountText(count) {
4
+ return count === 1 ? "1 moon" : `${count} moons`;
5
+ }
6
+ /** A date from the data (YYYY-MM-DD, or an ISO timestamp) as "18 October 2026"; the text itself when it is not a date. */
7
+ export function moonListDateText(date) {
8
+ const parsed = /^\d{4}-\d{2}-\d{2}/.test(date) ? new Date(`${date.slice(0, 10)}T00:00:00Z`) : new Date(Number.NaN);
9
+ return Number.isNaN(parsed.getTime()) ? date : parsed.toLocaleDateString("en-GB", { day: "numeric", month: "long", year: "numeric", timeZone: "UTC" });
10
+ }
11
+ /** "115 moons in the JPL Horizons list of 18 October 2026": the count is the moons the list holds, the source and date come from the data. */
12
+ export function moonListSummary(count, source, date) {
13
+ const head = moonCountText(count);
14
+ if (source !== undefined && date !== undefined)
15
+ return `${head} in the ${source} list of ${moonListDateText(date)}`;
16
+ if (date !== undefined)
17
+ return `${head}, list of ${moonListDateText(date)}`;
18
+ return head;
19
+ }
@@ -18,7 +18,7 @@ export class MoonTrajectory {
18
18
  body: "moon",
19
19
  center: "earth",
20
20
  timeUtcMs,
21
- frame: EQJ,
21
+ plane: EQJ,
22
22
  positionKm: moonFromEarthKm,
23
23
  orientation,
24
24
  });
@@ -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
  }
@@ -4,7 +4,7 @@ import type { TimeBounds } from "./trajectory.js";
4
4
  export declare function planetSeriesSpan(): TimeBounds;
5
5
  /**
6
6
  * The planet models from the stored curve fits (`data/ephemerides/planets/`, O-025 T-101): heliocentric ecliptic-J2000 positions as piecewise
7
- * Chebyshev series in TT, refitted from Orb's full VSOP87A series within 1 km (Pluto: fitted to Horizons states; tools/import/planet-fits.mjs). UTC to TT uses the table stored
7
+ * Chebyshev series in TT of each planet's system barycentre as JPL Horizons reports the planet, within 1 km (O-063 T-290; tools/import/planet-fits.mjs). UTC to TT uses the table stored
8
8
  * beside them. Dates outside the fitted span (1950 to 2045) throw rather than extrapolate. Only planetSeries.ts imports this, lazily.
9
9
  */
10
10
  export declare function createPlanetModels(): PlanetModels;
@@ -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
  },
@@ -32,7 +32,7 @@ export function planetSeriesSpan() {
32
32
  }
33
33
  /**
34
34
  * The planet models from the stored curve fits (`data/ephemerides/planets/`, O-025 T-101): heliocentric ecliptic-J2000 positions as piecewise
35
- * Chebyshev series in TT, refitted from Orb's full VSOP87A series within 1 km (Pluto: fitted to Horizons states; tools/import/planet-fits.mjs). UTC to TT uses the table stored
35
+ * Chebyshev series in TT of each planet's system barycentre as JPL Horizons reports the planet, within 1 km (O-063 T-290; tools/import/planet-fits.mjs). UTC to TT uses the table stored
36
36
  * beside them. Dates outside the fitted span (1950 to 2045) throw rather than extrapolate. Only planetSeries.ts imports this, lazily.
37
37
  */
38
38
  export function createPlanetModels() {
@@ -1,9 +1,17 @@
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[];
5
13
  export declare function isPlanetId(id: string): id is PlanetId;
6
- /** One planet's heliocentric ecliptic-J2000 model (curve fits of VSOP87A), as the astronomy adapter reads it. */
14
+ /** One planet's heliocentric ecliptic-J2000 model (curve fits of its system barycentre from JPL Horizons), as the astronomy adapter reads it. */
7
15
  export interface PlanetModel {
8
16
  xyz(date: Date): {
9
17
  readonly x: number;
@@ -17,7 +25,7 @@ export type PlanetModels = {
17
25
  readonly [P in PlanetId]: PlanetModel;
18
26
  };
19
27
  /**
20
- * Builds the planet models, once, from the stored curve fits of the full VSOP87A series (Pluto: of JPL Horizons states) (O-025 T-101, O-033 T-114; the library's compact
28
+ * Builds the planet models, once, from the stored curve fits of JPL Horizons states (O-025 T-101, O-033 T-114, O-063 T-290; before O-063 the full VSOP87A series; the library's compact
21
29
  * default tables are off by tens of thousands of km, docs/ASTRONOMY_VALIDATION.md, and its full series were about 0.8 MB of code).
22
30
  * The fits are a separate chunk fetched only when a mounted composition contains a planet; an experience without one never
23
31
  * downloads them (I-022).
@@ -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);
@@ -6,7 +20,7 @@ let loading;
6
20
  let models;
7
21
  let span;
8
22
  /**
9
- * Builds the planet models, once, from the stored curve fits of the full VSOP87A series (Pluto: of JPL Horizons states) (O-025 T-101, O-033 T-114; the library's compact
23
+ * Builds the planet models, once, from the stored curve fits of JPL Horizons states (O-025 T-101, O-033 T-114, O-063 T-290; before O-063 the full VSOP87A series; the library's compact
10
24
  * default tables are off by tens of thousands of km, docs/ASTRONOMY_VALIDATION.md, and its full series were about 0.8 MB of code).
11
25
  * The fits are a separate chunk fetched only when a mounted composition contains a planet; an experience without one never
12
26
  * downloads them (I-022).
@@ -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");