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
@@ -0,0 +1,41 @@
1
+ import { LOOK_FIELDS, lookName, lookValue, lookWith } from "../app/look.js";
2
+ import { SceneError } from "./errors.js";
3
+ const TOP_LEVEL = [...new Set(LOOK_FIELDS.map(({ path }) => path[0]))];
4
+ /** Checks a `setLook` argument: an object of known looks, each a finite number in its range or a boolean as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
5
+ export function checkedLook(input) {
6
+ const bad = (message) => new SceneError("bad-look", `setLook: ${message}`);
7
+ const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
8
+ if (!isObject(input))
9
+ throw bad(`give an object such as { starBrightness: 1.4 } (looks: ${TOP_LEVEL.join(", ")})`);
10
+ for (const [key, value] of Object.entries(input)) {
11
+ const fields = LOOK_FIELDS.filter(({ path }) => path[0] === key);
12
+ if (fields.length === 0)
13
+ throw bad(`"${key}" is not a look (known: ${TOP_LEVEL.join(", ")})`);
14
+ const nested = fields.some(({ path }) => path.length === 2);
15
+ if (nested && value !== undefined) {
16
+ if (!isObject(value))
17
+ throw bad(`${key} must be an object such as { sizePx: 100 }, got ${JSON.stringify(value)}`);
18
+ const names = fields.map(({ path }) => path[1]);
19
+ const unknown = Object.keys(value).find((name) => !names.includes(name));
20
+ if (unknown !== undefined)
21
+ throw bad(`${key}.${unknown} is not a look (known: ${names.join(", ")})`);
22
+ }
23
+ }
24
+ let look = {};
25
+ for (const field of LOOK_FIELDS) {
26
+ const value = lookValue(input, field);
27
+ if (value === undefined)
28
+ continue;
29
+ const problem = valueProblem(field, value);
30
+ if (problem !== null)
31
+ throw bad(`${lookName(field)} ${problem}, got ${JSON.stringify(value)}`);
32
+ look = lookWith(look, field, value);
33
+ }
34
+ return Object.freeze(look);
35
+ }
36
+ function valueProblem(field, value) {
37
+ const { spec } = field;
38
+ if (spec.kind === "range")
39
+ return typeof value === "number" && Number.isFinite(value) && value >= spec.min && value <= spec.max ? null : `must be a number from ${spec.min} to ${spec.max}`;
40
+ return typeof value === "boolean" ? null : "must be true or false";
41
+ }
@@ -0,0 +1,60 @@
1
+ import type { Provenance } from "../core/provenance.js";
2
+ import type { CardFactInput } from "./scene.js";
3
+ import type { TimeInput } from "./time.js";
4
+ /** One moon of a family in the moon panel. */
5
+ export interface MoonPanelMoonInput {
6
+ /** A body or body-set member of the scene; checked when the scene is built. Its label comes from there. */
7
+ readonly id: string;
8
+ /** False for a provisional designation, folded under "+N unnamed". Default true. */
9
+ readonly named?: boolean;
10
+ }
11
+ /** One family of moons in the moon panel. */
12
+ export interface MoonPanelFamilyInput {
13
+ readonly id: string;
14
+ readonly label: string;
15
+ /** One plain line. */
16
+ readonly description: string;
17
+ readonly moons: readonly MoonPanelMoonInput[];
18
+ }
19
+ /** The sliding panel of a planet's moons by family (`Scene.setMoonPanel`). */
20
+ export interface MoonPanelInput {
21
+ /** The name in the panel's heading ("<label>'s moons"). */
22
+ readonly label: string;
23
+ readonly families: readonly MoonPanelFamilyInput[];
24
+ /** A family id listed first, with pictures; the others fold. */
25
+ readonly featuredFamily?: string;
26
+ /** Where the list comes from, such as "JPL Horizons". */
27
+ readonly listSource?: string;
28
+ /** When the list was taken. */
29
+ readonly listDate?: TimeInput;
30
+ }
31
+ /** One tagged place's category: its key, label and marker colour. */
32
+ export interface PlaceCategoryInput {
33
+ readonly key: string;
34
+ readonly label: string;
35
+ /** A CSS hex colour such as "#9de3a8". */
36
+ readonly color: string;
37
+ }
38
+ /** One tagged place on a body's surface. */
39
+ export interface PlaceInput {
40
+ /** Unique within the body. */
41
+ readonly id: string;
42
+ readonly name: string;
43
+ /** Shown as the place's kind, such as "Crater". */
44
+ readonly kind: string;
45
+ /** One of `categories`; an unknown one draws white. */
46
+ readonly category: string;
47
+ readonly latitudeDeg: number;
48
+ /** East-positive as the marker draws it; a caller with west longitudes converts first. */
49
+ readonly longitudeDeg: number;
50
+ readonly description: string;
51
+ readonly details?: readonly CardFactInput[];
52
+ }
53
+ /** The tagged surface places of one body (`Scene.addPlaces`). */
54
+ export interface PlacesInput {
55
+ readonly categories: readonly PlaceCategoryInput[];
56
+ readonly places: readonly PlaceInput[];
57
+ /** Shown with every place's information (PROV-01). */
58
+ readonly provenance: Provenance;
59
+ readonly knownLimitations?: readonly string[];
60
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -1,6 +1,6 @@
1
1
  import "../app/style.css";
2
2
  import type { DataSource, Scene } from "./scene.js";
3
- import type { TimeInput } from "./time.js";
3
+ import { type ViewerHandle } from "./viewerHandle.js";
4
4
  import { type ViewerChange } from "./viewerLink.js";
5
5
  /** Options of `mount`. */
6
6
  export interface MountOptions {
@@ -8,27 +8,17 @@ export interface MountOptions {
8
8
  readonly data?: readonly DataSource[];
9
9
  /** Called whenever the viewer's time, speed or playing state changes: playback running, a visitor using the timeline, or the host's own `setTime` / `setRate` / `setView`. About ten times a second while playing. */
10
10
  readonly onChange?: (change: ViewerChange) => void;
11
+ /** Whether the viewer reads the page address and offers a copy-link button that writes it (default false: the address stays the host page's own). See the README's "Page address" section. */
12
+ readonly address?: boolean;
13
+ /** Whether the viewer shows the Developer toggle and drawer (default false: an outside page gets no developer cog and the drawer's code is never fetched). The "Copy view link" button lives in the drawer, so `address: true` without this has no copy button. A switch placed `"developer"` shows only when this is on. */
14
+ readonly developerTools?: boolean;
11
15
  }
12
- /** What `mount` returns. */
13
- export interface MountedScene {
14
- /** Resolves once the scene's data has loaded and it is drawn; rejects if loading failed. */
16
+ /** What `mount` returns: the viewer handle plus `ready` and `unmount`. */
17
+ export interface MountedScene extends ViewerHandle {
18
+ /** Resolves once the scene's data has loaded, it is drawn and the host link is attached, so `timeUtcMs`, `rate`, `view` and every set call work from then on. Rejects with its own error if loading failed, and with `SceneError` `not-mounted` if `unmount` came first; it never stays pending. */
15
19
  readonly ready: Promise<void>;
16
20
  /** Removes the scene, its canvas and its listeners from the page. Safe to call twice. */
17
21
  unmount(): void;
18
- /** The viewer's time in Unix milliseconds UTC; undefined until `ready` has resolved and after `unmount`. */
19
- readonly time: number | undefined;
20
- /** The playback speed (simulated seconds per real second); undefined like `time`. */
21
- readonly rate: number | undefined;
22
- /** The id of the view showing; undefined until `ready` has resolved, after `unmount`, and in a scene without views. */
23
- readonly view: string | undefined;
24
- /** Moves the viewer to `time` (ISO text, a `Date` or Unix milliseconds). Outside the timeline throws `bad-time`; before `ready` or after `unmount` throws `missing-data`. */
25
- setTime(time: TimeInput): void;
26
- /** Sets the playback speed to one of the speeds the timeline offers (`setTimeline({ rates })`); any other number throws `bad-timeline`. `"auto"` gives the speed back to the scene's `setTimeline({ pacing })` (throws `bad-timeline` when it has none). Before `ready` or after `unmount` throws `missing-data`. */
27
- setRate(rate: number | "auto"): void;
28
- /** Switches to the view with this id (`setViews`). An unknown id, or a scene without views, throws `bad-view`; before `ready` or after `unmount` throws `missing-data`. `onChange` hears it with `cause: "host"`. */
29
- setView(id: string): void;
30
- /** Calls `listener` on every change (see `MountOptions.onChange`); returns the function that stops it. No callbacks arrive after `unmount`. */
31
- onChange(listener: (change: ViewerChange) => void): () => void;
32
22
  }
33
23
  /**
34
24
  * Draws `scene` into `element` with the full viewer. The caller writes no React. The element needs a size.
@@ -38,7 +28,7 @@ export interface MountedScene {
38
28
  * const mounted = mount(document.getElementById("app")!, scene);
39
29
  * await mounted.ready; // drawn
40
30
  * mounted.setTime("2026-08-12T21:00:00Z"); // the viewer moves there; outside the timeline throws bad-time
41
- * mounted.onChange(({ time, rate }) => console.log(new Date(time).toISOString(), rate));
31
+ * mounted.onChange(({ timeUtcMs, rate }) => console.log(new Date(timeUtcMs).toISOString(), rate));
42
32
  * mounted.unmount(); // removes it again
43
33
  */
44
34
  export declare function mount(element: HTMLElement, scene: Scene, options?: MountOptions): MountedScene;
package/src/api/mount.js CHANGED
@@ -2,8 +2,10 @@ import { createElement } from "react";
2
2
  import { createRoot } from "react-dom/client";
3
3
  import "../app/style.css";
4
4
  import { App } from "../app/App.js";
5
+ import { makeContainingBlock } from "./containingBlock.js";
5
6
  import { SceneError } from "./errors.js";
6
7
  import { prepareScene } from "./prepared.js";
8
+ import { viewerHandleOf } from "./viewerHandle.js";
7
9
  import { ViewerLink } from "./viewerLink.js";
8
10
  /**
9
11
  * Draws `scene` into `element` with the full viewer. The caller writes no React. The element needs a size.
@@ -13,7 +15,7 @@ import { ViewerLink } from "./viewerLink.js";
13
15
  * const mounted = mount(document.getElementById("app")!, scene);
14
16
  * await mounted.ready; // drawn
15
17
  * mounted.setTime("2026-08-12T21:00:00Z"); // the viewer moves there; outside the timeline throws bad-time
16
- * mounted.onChange(({ time, rate }) => console.log(new Date(time).toISOString(), rate));
18
+ * mounted.onChange(({ timeUtcMs, rate }) => console.log(new Date(timeUtcMs).toISOString(), rate));
17
19
  * mounted.unmount(); // removes it again
18
20
  */
19
21
  export function mount(element, scene, options = {}) {
@@ -21,31 +23,43 @@ export function mount(element, scene, options = {}) {
21
23
  throw new SceneError("bad-element", "mount: the first argument must be an element of the page");
22
24
  const { definition, ready: loaded } = prepareScene(scene, options.data);
23
25
  // Its own stacking context, so the viewer's z-index values cannot rise above the host page's overlays.
26
+ const isolation = element.style.isolation;
24
27
  element.style.isolation = "isolate";
28
+ // The viewer's root fills this element (position: absolute; inset: 0), so the element is its containing block; the viewer no longer styles the host's #app.
29
+ const restoreBlock = makeContainingBlock(element);
25
30
  const root = createRoot(element);
26
31
  let open = true;
27
32
  const link = new ViewerLink();
28
33
  if (options.onChange !== undefined)
29
34
  link.onChange(options.onChange);
30
- const ready = loaded.then(() => {
31
- if (open)
32
- root.render(createElement(App, { definition, writeTitle: false, host: link }));
35
+ // Resolves once the viewer has attached its clock (its effect runs after the render), so every handle call works straight after `await ready`.
36
+ const attached = loaded.then(() => {
37
+ if (!open)
38
+ throw new SceneError("not-mounted", "mount: unmounted before the viewer was drawn");
39
+ root.render(createElement(App, { definition, writeTitle: false, address: options.address === true, developerTools: options.developerTools === true, host: link }));
40
+ return link.whenAttached();
33
41
  });
34
- return {
42
+ // Only the expected "taken down early" rejection (`not-mounted`) is marked handled, so a host that never awaits `ready` is not sent an unhandled rejection for it;
43
+ // any other rejection (a failed load) stays unhandled until someone awaits `ready`, as before. Whoever awaits `ready` hears either error.
44
+ const ready = new Promise((resolve, reject) => {
45
+ attached.then(resolve, (error) => {
46
+ reject(error);
47
+ if (error instanceof SceneError && error.code === "not-mounted")
48
+ ready.catch(() => undefined);
49
+ });
50
+ });
51
+ // The shared handle is the prototype (a spread would copy its getters' values once); `ready` and `unmount` are this handle's own.
52
+ return Object.assign(Object.create(viewerHandleOf(link)), {
35
53
  ready,
36
- get time() { return link.time; },
37
- get rate() { return link.rate; },
38
- get view() { return link.view; },
39
- setView: (id) => link.setView(id),
40
- setTime: (time) => link.setTime(time),
41
- setRate: (rate) => link.setRate(rate),
42
- onChange: (listener) => link.onChange(listener),
43
54
  unmount() {
44
55
  if (!open)
45
56
  return;
46
57
  open = false;
47
58
  link.close();
48
59
  root.unmount();
60
+ // The host element goes back to the inline isolation, position and overflow it had before `mount`.
61
+ restoreBlock();
62
+ element.style.isolation = isolation;
49
63
  },
50
- };
64
+ });
51
65
  }
@@ -1,8 +1,10 @@
1
1
  import { createElement } from "react";
2
2
  import { createRoot } from "react-dom/client";
3
3
  import { App } from "../app/App.node.js";
4
+ import { makeContainingBlock } from "./containingBlock.js";
4
5
  import { SceneError } from "./errors.js";
5
6
  import { prepareScene } from "./prepared.js";
7
+ import { viewerHandleOf } from "./viewerHandle.js";
6
8
  import { ViewerLink } from "./viewerLink.js";
7
9
  /**
8
10
  * Draws `scene` into `element` with the full viewer. The caller writes no React. The element needs a size.
@@ -12,7 +14,7 @@ import { ViewerLink } from "./viewerLink.js";
12
14
  * const mounted = mount(document.getElementById("app")!, scene);
13
15
  * await mounted.ready; // drawn
14
16
  * mounted.setTime("2026-08-12T21:00:00Z"); // the viewer moves there; outside the timeline throws bad-time
15
- * mounted.onChange(({ time, rate }) => console.log(new Date(time).toISOString(), rate));
17
+ * mounted.onChange(({ timeUtcMs, rate }) => console.log(new Date(timeUtcMs).toISOString(), rate));
16
18
  * mounted.unmount(); // removes it again
17
19
  */
18
20
  export function mount(element, scene, options = {}) {
@@ -20,31 +22,43 @@ export function mount(element, scene, options = {}) {
20
22
  throw new SceneError("bad-element", "mount: the first argument must be an element of the page");
21
23
  const { definition, ready: loaded } = prepareScene(scene, options.data);
22
24
  // Its own stacking context, so the viewer's z-index values cannot rise above the host page's overlays.
25
+ const isolation = element.style.isolation;
23
26
  element.style.isolation = "isolate";
27
+ // The viewer's root fills this element (position: absolute; inset: 0), so the element is its containing block; the viewer no longer styles the host's #app.
28
+ const restoreBlock = makeContainingBlock(element);
24
29
  const root = createRoot(element);
25
30
  let open = true;
26
31
  const link = new ViewerLink();
27
32
  if (options.onChange !== undefined)
28
33
  link.onChange(options.onChange);
29
- const ready = loaded.then(() => {
30
- if (open)
31
- root.render(createElement(App, { definition, writeTitle: false, host: link }));
34
+ // Resolves once the viewer has attached its clock (its effect runs after the render), so every handle call works straight after `await ready`.
35
+ const attached = loaded.then(() => {
36
+ if (!open)
37
+ throw new SceneError("not-mounted", "mount: unmounted before the viewer was drawn");
38
+ root.render(createElement(App, { definition, writeTitle: false, address: options.address === true, developerTools: options.developerTools === true, host: link }));
39
+ return link.whenAttached();
32
40
  });
33
- return {
41
+ // Only the expected "taken down early" rejection (`not-mounted`) is marked handled, so a host that never awaits `ready` is not sent an unhandled rejection for it;
42
+ // any other rejection (a failed load) stays unhandled until someone awaits `ready`, as before. Whoever awaits `ready` hears either error.
43
+ const ready = new Promise((resolve, reject) => {
44
+ attached.then(resolve, (error) => {
45
+ reject(error);
46
+ if (error instanceof SceneError && error.code === "not-mounted")
47
+ ready.catch(() => undefined);
48
+ });
49
+ });
50
+ // The shared handle is the prototype (a spread would copy its getters' values once); `ready` and `unmount` are this handle's own.
51
+ return Object.assign(Object.create(viewerHandleOf(link)), {
34
52
  ready,
35
- get time() { return link.time; },
36
- get rate() { return link.rate; },
37
- get view() { return link.view; },
38
- setView: (id) => link.setView(id),
39
- setTime: (time) => link.setTime(time),
40
- setRate: (rate) => link.setRate(rate),
41
- onChange: (listener) => link.onChange(listener),
42
53
  unmount() {
43
54
  if (!open)
44
55
  return;
45
56
  open = false;
46
57
  link.close();
47
58
  root.unmount();
59
+ // The host element goes back to the inline isolation, position and overflow it had before `mount`.
60
+ restoreBlock();
61
+ element.style.isolation = isolation;
48
62
  },
49
- };
63
+ });
50
64
  }
@@ -40,7 +40,7 @@ export function planPathProvenance(id, spans, boundsUtcMs) {
40
40
  export function planLineStretches(id, stretches, boundsUtcMs) {
41
41
  return planSpans(id, "lineFixedTo", stretches, boundsUtcMs, (stretch) => {
42
42
  if (typeof stretch.body !== "string" || stretch.body === "")
43
- throw new Error("body must be a body id");
43
+ throw new SceneError("bad-trajectory", "body must be a body id");
44
44
  return { body: stretch.body };
45
45
  });
46
46
  }
@@ -0,0 +1,25 @@
1
+ /** One option of the picker (`Scene.setPicker`). */
2
+ export interface PickerOptionInput {
3
+ /** What the host hears when a visitor presses the option; unique among the options. */
4
+ readonly value: string;
5
+ /** The words on the button. */
6
+ readonly label: string;
7
+ }
8
+ /** A choice an app offers in the viewer's top bar and phone drawer (`Scene.setPicker`). The viewer only reports a press; it never navigates, reads or writes the page address, or keeps a time. */
9
+ export interface PickerInput {
10
+ /** Names the choice; the buttons carry it as `data-switch-param`. It has no other meaning to the viewer. */
11
+ readonly id: string;
12
+ /** The accessible name of the group of buttons. */
13
+ readonly label: string;
14
+ /** The buttons, in order. Fewer than two: no control is drawn. */
15
+ readonly options: readonly PickerOptionInput[];
16
+ /** The option pressed when the viewer opens; one of the options' values. */
17
+ readonly value: string;
18
+ }
19
+ /** What a host is told when a visitor presses an option other than the pressed one (`ViewerHandle.onPick`, the `onPick` prop of `AstraeusScene`). */
20
+ export interface PickChange {
21
+ /** The `id` of the picker. */
22
+ readonly picker: string;
23
+ /** The `value` of the option pressed. The pressed option does not move until the host calls `setPick` (or mounts a new scene). */
24
+ readonly value: string;
25
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,72 @@
1
+ import type { BodyId } from "../core/body.js";
2
+ import { type ScalePolicy } from "../core/scalePolicy.js";
3
+ import { type BodyCatalogue } from "../assets/catalogue.js";
4
+ import { type ElementsBodyRecord } from "../core/elementsBody.js";
5
+ import type { CompositionPath } from "../assets/compositions.js";
6
+ import type { ExperienceDefinition, PathLayer } from "../app/experienceDefinition.js";
7
+ import type { ExperienceObject } from "../shell/experience.js";
8
+ import type { EccentricSampling } from "../core/sunCentredSources.js";
9
+ import { type BodyRef } from "./bodies.js";
10
+ import type { DataSource } from "./data.js";
11
+ import type { AddBodyOptions, OrbitLapInput, ReadoutInput } from "./scene.js";
12
+ import { type Provenance } from "../core/provenance.js";
13
+ import { type SceneBodyRead } from "./sceneReads.js";
14
+ type Shape = Pick<AddBodyOptions, "enlarge" | "showLabel">;
15
+ /** The camera facts the label rule reads. */
16
+ export interface LabelCamera {
17
+ readonly fitted: string | undefined;
18
+ readonly reachEarthRadii: number | undefined;
19
+ }
20
+ /** What a `Scene` has planned for its bodies: the bodies, their options and the scene's catalogue. */
21
+ export declare class BodyPlan {
22
+ #private;
23
+ readonly bodies: Map<string, BodyRef>;
24
+ readonly orbits: Set<string>;
25
+ readonly own: Map<string, EccentricSampling>;
26
+ readonly labelReaches: Map<string, number>;
27
+ readonly shape: Map<string, Shape>;
28
+ readonly notes: Map<string, string>;
29
+ readonly readouts: Map<string, readonly ReadoutInput[]>;
30
+ readonly laps: Map<string, OrbitLapInput>;
31
+ readonly cards: Map<string, Pick<AddBodyOptions, "facts" | "labelPriority" | "listed" | "sources">>;
32
+ readonly looks: Map<string, Pick<AddBodyOptions, "color" | "knownLimitations">>;
33
+ catalogue: BodyCatalogue;
34
+ /** `taken` says whether the scene already holds an id; `firstBody` runs when the scene's first body arrives (it is a built-in one). */
35
+ constructor(taken: (id: string) => boolean, firstBody: (id: BodyId) => void);
36
+ addBody(body: BodyRef | BodyId, input: AddBodyOptions): void;
37
+ addFromElements(input: ElementsBodyRecord, inputOptions: AddBodyOptions): void;
38
+ /** A body's position provenance as its card shows it: the catalogue's, with the sources `addBody` added after its own. */
39
+ provenanceOf(id: BodyId): Provenance;
40
+ /** The data packages the added bodies need that `data` does not provide. */
41
+ missingData(data: readonly DataSource[]): readonly string[];
42
+ /** Throws `missing-data` naming the bodies whose data package was not passed. */
43
+ checkData(data: readonly DataSource[]): void;
44
+ /** The engine's own orbit loops (the Moon's and Io's) the scene asked for. */
45
+ moonPaths(): readonly CompositionPath[];
46
+ /** The bodies that asked for a Sun-orbit line, checked: the Sun must be in the scene and the line's id free. */
47
+ sunOrbitIds(ids: readonly BodyId[]): readonly BodyId[];
48
+ /** One Sun-orbit line: one full turn from the opening time (an own body from its periapsis). Reads planet positions, so the planet series must be loaded. */
49
+ sunPath(id: BodyId, openUtcMs: number): PathLayer;
50
+ /** The Sun-orbit lines that can be drawn now: `loaded` (the planet series are in) draws all of them, else none (they are drawn in `prepare`). */
51
+ earlySunPaths(orbitIds: readonly BodyId[], openUtcMs: number, loaded: boolean): PathLayer[];
52
+ /** Whether the scene is centred on the Sun. */
53
+ checkSunCentred(ids: readonly BodyId[]): boolean;
54
+ checkSolarSystemScale(scale: ScalePolicy, sunCentred: boolean): void;
55
+ /** Whether a Sun-centred scene enlarges a body, which the viewer's solar-system scale draws. */
56
+ enlargedInSun(sunCentred: boolean): boolean;
57
+ /** The bodies in the order added, as the public list states them. */
58
+ reads(): readonly SceneBodyRead[];
59
+ /**
60
+ * The scale choices offered: the opening one first, then the other unless the caller offered one alone. A Sun-centred scene with an enlarged body (`addBody(x, { enlarge })`)
61
+ * offers `solarSystemScale` (true distances, the named bodies enlarged) in place of the readable scale it would offer second, since the readable scale does not enlarge.
62
+ */
63
+ scaleChoices(scale: ScalePolicy, only: boolean): readonly string[];
64
+ visualOverrides(): Pick<ExperienceDefinition, "visualOverrides">;
65
+ /** How far a label shows, for bodies and paths alike: the item's own `labelReachEarthRadii` if given, else the shared rule: a Sun-centred scene, or one that fits the zoom-out to an orbit (`fitOrbit`, whose limit changes with the canvas), sets no limit; otherwise the camera reach, at least 500. */
66
+ labelReach(id: string, sunCentred: boolean, camera: LabelCamera): {
67
+ readonly labelMaxDistance?: number;
68
+ };
69
+ /** The shell item of a body: from the catalogue, with the scene's own words, look and label setting. Label reach is `labelReachEarthRadii`. */
70
+ bodyObject(body: BodyRef, ids: readonly BodyId[], sunCentred: boolean, camera: LabelCamera): ExperienceObject;
71
+ }
72
+ export {};