astraeus 0.6.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.
- package/CHANGELOG.md +192 -0
- package/README.md +205 -34
- package/package.json +5 -4
- package/src/api/AstraeusScene.d.ts +24 -6
- package/src/api/AstraeusScene.js +46 -19
- package/src/api/AstraeusScene.node.js +46 -19
- package/src/api/assembleScene.d.ts +36 -0
- package/src/api/assembleScene.js +175 -0
- package/src/api/bodySetChecks.d.ts +10 -0
- package/src/api/bodySetChecks.js +117 -0
- package/src/api/bodySetInput.d.ts +81 -0
- package/src/api/bodySetInput.js +1 -0
- package/src/api/containingBlock.d.ts +6 -0
- package/src/api/containingBlock.js +16 -0
- package/src/api/data.d.ts +17 -5
- package/src/api/data.js +28 -10
- package/src/api/definitionOf.d.ts +16 -0
- package/src/api/definitionOf.js +20 -0
- package/src/api/errors.d.ts +61 -1
- package/src/api/frozenCopy.d.ts +6 -0
- package/src/api/frozenCopy.js +26 -0
- package/src/api/group.d.ts +8 -2
- package/src/api/group.js +24 -5
- package/src/api/index.d.ts +19 -7
- package/src/api/index.js +2 -2
- package/src/api/index.node.js +2 -2
- package/src/api/listeners.d.ts +5 -0
- package/src/api/listeners.js +25 -0
- package/src/api/look.d.ts +47 -0
- package/src/api/look.js +1 -0
- package/src/api/lookInput.d.ts +3 -0
- package/src/api/lookInput.js +41 -0
- package/src/api/moonPanelInput.d.ts +60 -0
- package/src/api/moonPanelInput.js +1 -0
- package/src/api/mount.d.ts +10 -16
- package/src/api/mount.js +27 -11
- package/src/api/mount.node.js +27 -11
- package/src/api/pathProvenance.d.ts +15 -6
- package/src/api/pathProvenance.js +23 -11
- package/src/api/pickerInput.d.ts +25 -0
- package/src/api/pickerInput.js +1 -0
- package/src/api/planBodies.d.ts +72 -0
- package/src/api/planBodies.js +300 -0
- package/src/api/planBodySets.d.ts +68 -0
- package/src/api/planBodySets.js +234 -0
- package/src/api/planCamera.d.ts +83 -0
- package/src/api/planCamera.js +184 -0
- package/src/api/planGroups.d.ts +36 -0
- package/src/api/planGroups.js +103 -0
- package/src/api/planMoonPanel.d.ts +19 -0
- package/src/api/planMoonPanel.js +104 -0
- package/src/api/planPaths.d.ts +40 -0
- package/src/api/planPaths.js +212 -0
- package/src/api/planPicker.d.ts +12 -0
- package/src/api/planPicker.js +40 -0
- package/src/api/planPlaces.d.ts +16 -0
- package/src/api/planPlaces.js +99 -0
- package/src/api/planStory.d.ts +26 -0
- package/src/api/planStory.js +66 -0
- package/src/api/planTimeline.d.ts +27 -0
- package/src/api/planTimeline.js +68 -0
- package/src/api/planViews.d.ts +25 -0
- package/src/api/planViews.js +35 -0
- package/src/api/prepared.js +4 -1
- package/src/api/renamedInputs.d.ts +15 -0
- package/src/api/renamedInputs.js +39 -0
- package/src/api/scene.d.ts +176 -65
- package/src/api/scene.js +257 -725
- package/src/api/sceneFreeze.d.ts +4 -0
- package/src/api/sceneFreeze.js +10 -0
- package/src/api/sceneReads.d.ts +171 -0
- package/src/api/sceneReads.js +6 -0
- package/src/api/sphereOfInfluence.d.ts +20 -0
- package/src/api/sphereOfInfluence.js +48 -0
- package/src/api/story.d.ts +49 -19
- package/src/api/story.js +54 -22
- package/src/api/sunOrbit.js +9 -11
- package/src/api/time.d.ts +2 -1
- package/src/api/time.js +2 -1
- package/src/api/viewerCamera.d.ts +22 -0
- package/src/api/viewerCamera.js +84 -0
- package/src/api/viewerClock.d.ts +30 -0
- package/src/api/viewerClock.js +85 -0
- package/src/api/viewerFirstDraw.d.ts +14 -0
- package/src/api/viewerFirstDraw.js +26 -0
- package/src/api/viewerHandle.d.ts +79 -0
- package/src/api/viewerHandle.js +31 -0
- package/src/api/viewerLink.d.ts +91 -13
- package/src/api/viewerLink.js +111 -64
- package/src/api/viewerLooks.d.ts +19 -0
- package/src/api/viewerLooks.js +37 -0
- package/src/api/viewerPicker.d.ts +22 -0
- package/src/api/viewerPicker.js +49 -0
- package/src/api/viewerSelection.d.ts +25 -0
- package/src/api/viewerSelection.js +31 -0
- package/src/api/viewerViews.d.ts +10 -0
- package/src/api/viewerViews.js +18 -0
- package/src/api/viewerZones.d.ts +20 -0
- package/src/api/viewerZones.js +47 -0
- package/src/api/views.d.ts +41 -0
- package/src/api/views.js +82 -0
- package/src/app/App.d.ts +5 -3
- package/src/app/App.js +211 -75
- package/src/app/App.node.js +211 -75
- package/src/app/AstraeusScene.d.ts +19 -2
- package/src/app/AstraeusScene.js +4 -4
- package/src/app/BodyView.d.ts +4 -1
- package/src/app/BodyView.js +2 -2
- package/src/app/CameraController.d.ts +12 -0
- package/src/app/CameraController.js +3 -1
- package/src/app/DeveloperSettings.d.ts +1 -4
- package/src/app/DeveloperSettings.js +6 -10
- package/src/app/FeatureMarkers.d.ts +4 -3
- package/src/app/FeatureMarkers.js +8 -13
- package/src/app/FrameRateSection.js +2 -1
- package/src/app/OrbitSetView.js +1 -1
- package/src/app/SettingControls.d.ts +11 -3
- package/src/app/SettingControls.js +10 -2
- package/src/app/SkyView.d.ts +3 -10
- package/src/app/SkyView.js +6 -28
- package/src/app/StoryMarkers.d.ts +4 -1
- package/src/app/StoryMarkers.js +3 -2
- package/src/app/TrackedBodyView.d.ts +1 -1
- package/src/app/TrackedBodyView.js +20 -11
- package/src/app/address.d.ts +16 -0
- package/src/app/address.js +31 -0
- package/src/app/bodyDraw.d.ts +10 -7
- package/src/app/bodyDraw.js +12 -32
- package/src/app/bodyMetrics.js +2 -2
- package/src/app/bodySet.d.ts +4 -20
- package/src/app/bodySet.js +5 -16
- package/src/app/debugReadout.js +1 -1
- package/src/app/displaySwitches.d.ts +4 -0
- package/src/app/displaySwitches.js +6 -0
- package/src/app/experienceDefinition.d.ts +14 -23
- package/src/app/listSwitch.d.ts +8 -14
- package/src/app/listSwitch.js +3 -10
- package/src/app/liveLook.d.ts +39 -0
- package/src/app/liveLook.js +66 -0
- package/src/app/look.d.ts +36 -0
- package/src/app/look.js +61 -0
- package/src/app/mission.d.ts +16 -3
- package/src/app/mission.js +16 -1
- package/src/app/openClock.d.ts +3 -2
- package/src/app/openClock.js +3 -3
- package/src/app/sceneCamera.d.ts +2 -0
- package/src/app/sceneCamera.js +23 -0
- package/src/app/sceneFrame.d.ts +6 -4
- package/src/app/sceneFrame.js +55 -14
- package/src/app/sceneHooks.js +3 -2
- package/src/app/style.css +114 -139
- package/src/app/trackedMetrics.d.ts +10 -3
- package/src/app/trackedMetrics.js +22 -11
- package/src/app/viewHiding.d.ts +13 -0
- package/src/app/viewHiding.js +37 -0
- package/src/app/viewLink.d.ts +10 -32
- package/src/app/viewLink.js +10 -49
- package/src/app/viewerPort.d.ts +56 -0
- package/src/app/views.d.ts +32 -0
- package/src/app/views.js +2 -0
- package/src/assets/bodies/galileanMoons.js +1 -2
- package/src/assets/bodies/io.js +2 -2
- package/src/assets/bodies/listedMoons.d.ts +1 -1
- package/src/assets/bodies/listedMoons.js +2 -3
- package/src/assets/bodies/planetSystemMaps.js +2 -3
- package/src/assets/bodies/venus.js +2 -6
- package/src/assets/catalogue.js +1 -2
- package/src/assets/licence.d.ts +3 -3
- package/src/assets/licence.js +3 -3
- package/src/assets/pictures.d.ts +15 -12
- package/src/assets/pictures.js +24 -20
- package/src/assets/sky.d.ts +6 -5
- package/src/assets/sky.js +6 -9
- package/src/assets/visual.d.ts +4 -0
- package/src/core/bodies/index.d.ts +0 -4
- package/src/core/bodies/index.js +1 -6
- package/src/core/bodies/jupiterData.d.ts +0 -1
- package/src/core/bodies/jupiterData.js +2 -5
- package/src/core/bodies/moonSystem.d.ts +1 -1
- package/src/core/bodies/moonSystem.js +102 -55
- package/src/core/bodies/outerPlanetRingData.js +2 -2
- package/src/core/bodies/planetTrajectory.js +1 -1
- package/src/core/bodySetFamilies.d.ts +20 -0
- package/src/core/bodySetFamilies.js +14 -0
- package/src/core/chebyshevEphemeris.js +1 -1
- package/src/core/elementsBody.d.ts +8 -4
- package/src/core/elementsBody.js +32 -11
- package/src/core/elementsGroup.d.ts +27 -0
- package/src/core/elementsGroup.js +85 -0
- package/src/core/events.d.ts +2 -0
- package/src/core/events.js +2 -0
- package/src/core/illumination.js +1 -1
- package/src/core/listedOrbitGroup.d.ts +2 -0
- package/src/core/listedOrbitGroup.js +11 -7
- package/src/core/moonListText.d.ts +6 -0
- package/src/core/moonListText.js +19 -0
- package/src/core/moonTrajectory.js +1 -1
- package/src/core/pacing.d.ts +38 -3
- package/src/core/pacing.js +55 -4
- package/src/core/planetModels.js +2 -2
- package/src/core/planetSeries.d.ts +8 -0
- package/src/core/planetSeries.js +16 -2
- package/src/core/pointGroup.js +1 -1
- package/src/core/provenance.d.ts +2 -1
- package/src/core/provenance.js +2 -2
- package/src/core/referenceCenters.js +5 -5
- package/src/core/sampledTrajectory.js +1 -1
- package/src/core/scalePolicy.d.ts +1 -0
- package/src/core/startView.d.ts +19 -0
- package/src/core/startView.js +28 -0
- package/src/core/state.d.ts +6 -2
- package/src/core/state.js +3 -3
- package/src/core/storyPanels.d.ts +63 -0
- package/src/core/storyPanels.js +111 -0
- package/src/core/sunCentredSources.d.ts +4 -0
- package/src/core/sunCentredSources.js +9 -2
- package/src/core/timeInput.d.ts +4 -0
- package/src/core/timeInput.js +4 -0
- package/src/shell/AstraeusShell.d.ts +17 -3
- package/src/shell/AstraeusShell.js +60 -13
- package/src/shell/AstraeusShell.node.js +60 -13
- package/src/shell/Collapsible.d.ts +4 -3
- package/src/shell/Collapsible.js +5 -5
- package/src/shell/ControlsDrawer.d.ts +1 -1
- package/src/shell/ControlsDrawer.js +3 -1
- package/src/shell/DisplaySwitches.d.ts +18 -1
- package/src/shell/DisplaySwitches.js +20 -6
- package/src/shell/InfoPanel.d.ts +3 -1
- package/src/shell/InfoPanel.js +5 -4
- package/src/shell/MoonFamilyPanel.js +1 -1
- package/src/shell/ObjectControls.d.ts +3 -1
- package/src/shell/ObjectControls.js +2 -2
- package/src/shell/Sources.d.ts +5 -3
- package/src/shell/Sources.js +5 -5
- package/src/shell/StoryPanelView.d.ts +4 -3
- package/src/shell/StoryPanelView.js +8 -6
- package/src/shell/SwitchControl.d.ts +5 -11
- package/src/shell/SwitchControl.js +2 -20
- package/src/shell/TimelineBar.css +84 -66
- package/src/shell/TimelineBar.d.ts +5 -2
- package/src/shell/TimelineBar.js +37 -11
- package/src/shell/TimelineBar.node.js +37 -11
- package/src/shell/TopBar.css +22 -22
- package/src/shell/TopBar.d.ts +9 -3
- package/src/shell/TopBar.js +5 -5
- package/src/shell/TopBar.node.js +5 -5
- package/src/shell/bootLoader.d.ts +4 -10
- package/src/shell/bootLoader.js +6 -52
- package/src/shell/embedded.css +18 -18
- package/src/shell/experience.d.ts +1 -1
- package/src/shell/moonFamilies.d.ts +2 -6
- package/src/shell/moonFamilies.js +2 -18
- package/src/shell/phone.css +58 -58
- package/src/shell/storyPanels.d.ts +2 -53
- package/src/shell/storyPanels.js +1 -106
- package/src/shell/style.css +153 -134
- package/src/shell/timelineModel.d.ts +13 -0
- package/src/shell/timelineModel.js +25 -0
- package/src/shell/useDrawers.d.ts +3 -2
- package/src/shell/useDrawers.js +4 -3
- package/src/shell/viewCamera.d.ts +4 -0
- package/src/shell/viewCamera.js +13 -0
- package/src/shell/viewerKeys.d.ts +8 -0
- package/src/shell/viewerKeys.js +16 -0
- package/src/synthetic/syntheticDefinition.js +20 -24
- package/src/synthetic/syntheticJourneyScene.js +14 -4
- package/src/synthetic/syntheticProbeDefinition.js +2 -1
- package/src/synthetic/syntheticViewsDefinition.d.ts +3 -0
- package/src/synthetic/syntheticViewsDefinition.js +38 -0
- package/data/moons/jupiter.json +0 -3333
- package/data/moons/neptune.json +0 -555
- package/data/moons/pluto.json +0 -205
- package/data/moons/saturn.json +0 -8267
- package/data/moons/uranus.json +0 -887
- package/src/app/addressNavigation.d.ts +0 -17
- package/src/app/addressNavigation.js +0 -16
- package/src/assets/bodies/jupiterMoonCatalogue.d.ts +0 -3
- package/src/assets/bodies/jupiterMoonCatalogue.js +0 -4
- package/src/assets/bodies/outerPlanetCatalogues.d.ts +0 -7
- package/src/assets/bodies/outerPlanetCatalogues.js +0 -8
- package/src/assets/bodies/swiftTuttle.d.ts +0 -12
- package/src/assets/bodies/swiftTuttle.js +0 -13
- package/src/assets/moonCatalogue.d.ts +0 -49
- package/src/assets/moonCatalogue.js +0 -80
- package/src/core/bodies/outerPlanetData.d.ts +0 -4
- package/src/core/bodies/outerPlanetData.js +0 -13
- package/src/core/bodies/swiftTuttle.d.ts +0 -46
- package/src/core/bodies/swiftTuttle.js +0 -106
package/src/api/mount.d.ts
CHANGED
|
@@ -1,30 +1,24 @@
|
|
|
1
1
|
import "../app/style.css";
|
|
2
2
|
import type { DataSource, Scene } from "./scene.js";
|
|
3
|
-
import type
|
|
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 {
|
|
7
7
|
/** Data packages the scene's bodies need, such as moon pictures or positions; nothing is looked up behind the caller's back. */
|
|
8
8
|
readonly data?: readonly DataSource[];
|
|
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`. About ten times a second while playing. */
|
|
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
|
|
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
|
-
/** 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`. */
|
|
23
|
-
setTime(time: TimeInput): void;
|
|
24
|
-
/** 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`. */
|
|
25
|
-
setRate(rate: number | "auto"): void;
|
|
26
|
-
/** Calls `listener` on every change (see `MountOptions.onChange`); returns the function that stops it. No callbacks arrive after `unmount`. */
|
|
27
|
-
onChange(listener: (change: ViewerChange) => void): () => void;
|
|
28
22
|
}
|
|
29
23
|
/**
|
|
30
24
|
* Draws `scene` into `element` with the full viewer. The caller writes no React. The element needs a size.
|
|
@@ -34,7 +28,7 @@ export interface MountedScene {
|
|
|
34
28
|
* const mounted = mount(document.getElementById("app")!, scene);
|
|
35
29
|
* await mounted.ready; // drawn
|
|
36
30
|
* mounted.setTime("2026-08-12T21:00:00Z"); // the viewer moves there; outside the timeline throws bad-time
|
|
37
|
-
* mounted.onChange(({
|
|
31
|
+
* mounted.onChange(({ timeUtcMs, rate }) => console.log(new Date(timeUtcMs).toISOString(), rate));
|
|
38
32
|
* mounted.unmount(); // removes it again
|
|
39
33
|
*/
|
|
40
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(({
|
|
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,29 +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
|
-
|
|
31
|
-
|
|
32
|
-
|
|
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
|
-
|
|
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
|
-
setTime: (time) => link.setTime(time),
|
|
39
|
-
setRate: (rate) => link.setRate(rate),
|
|
40
|
-
onChange: (listener) => link.onChange(listener),
|
|
41
54
|
unmount() {
|
|
42
55
|
if (!open)
|
|
43
56
|
return;
|
|
44
57
|
open = false;
|
|
45
58
|
link.close();
|
|
46
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;
|
|
47
63
|
},
|
|
48
|
-
};
|
|
64
|
+
});
|
|
49
65
|
}
|
package/src/api/mount.node.js
CHANGED
|
@@ -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(({
|
|
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,29 +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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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
|
-
|
|
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
|
-
setTime: (time) => link.setTime(time),
|
|
38
|
-
setRate: (rate) => link.setRate(rate),
|
|
39
|
-
onChange: (listener) => link.onChange(listener),
|
|
40
53
|
unmount() {
|
|
41
54
|
if (!open)
|
|
42
55
|
return;
|
|
43
56
|
open = false;
|
|
44
57
|
link.close();
|
|
45
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;
|
|
46
62
|
},
|
|
47
|
-
};
|
|
63
|
+
});
|
|
48
64
|
}
|
|
@@ -1,10 +1,19 @@
|
|
|
1
1
|
import type { WindowProvenanceSpan } from "../core/timeWindow.js";
|
|
2
2
|
import type { ActivitySourceInput } from "./activity.js";
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
*/
|
|
7
|
-
export declare function planPathProvenance(id: string, spans: readonly ActivitySourceInput[], boundsUtcMs: {
|
|
3
|
+
import { type TimeInput } from "./time.js";
|
|
4
|
+
import type { LineStretch } from "../app/mission.js";
|
|
5
|
+
interface Bounds {
|
|
8
6
|
readonly startUtcMs: number;
|
|
9
7
|
readonly endUtcMs: number;
|
|
10
|
-
}
|
|
8
|
+
}
|
|
9
|
+
/** Checks a path's provenance by time span (the same `{ start, end, provenance }` shape as an activity's) and returns it in milliseconds. */
|
|
10
|
+
export declare function planPathProvenance(id: string, spans: readonly ActivitySourceInput[], boundsUtcMs: Bounds): readonly WindowProvenanceSpan[];
|
|
11
|
+
/** One stretch of a path's line and the body it is drawn against, as the caller gives it. */
|
|
12
|
+
export interface LineStretchInput {
|
|
13
|
+
readonly start: TimeInput;
|
|
14
|
+
readonly end: TimeInput;
|
|
15
|
+
readonly body: string;
|
|
16
|
+
}
|
|
17
|
+
/** Checks a path's `lineFixedTo` list (same span rules as `provenanceSpans`) and returns it in milliseconds. */
|
|
18
|
+
export declare function planLineStretches(id: string, stretches: readonly LineStretchInput[], boundsUtcMs: Bounds): readonly LineStretch[];
|
|
19
|
+
export {};
|
|
@@ -2,33 +2,45 @@ import { createProvenance } from "../core/provenance.js";
|
|
|
2
2
|
import { SceneError } from "./errors.js";
|
|
3
3
|
import { toUtcMs } from "./time.js";
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
5
|
+
* The shared plan for a path's time-span lists (`provenanceSpans`, `lineFixedTo`): each span's `start` and `end` are read to milliseconds, `read` builds the item from the span,
|
|
6
|
+
* and the list must be sorted, not overlap and lie inside `bounds`. Any fault is a `bad-trajectory` naming the path, the field and the index.
|
|
7
7
|
*/
|
|
8
|
-
|
|
9
|
-
const bad = (index, message) => new SceneError("bad-trajectory", `addTrajectory("${id}"):
|
|
8
|
+
function planSpans(id, field, spans, bounds, read) {
|
|
9
|
+
const bad = (index, message) => new SceneError("bad-trajectory", `addTrajectory("${id}"): ${field}[${index}] ${message}`);
|
|
10
10
|
if (!Array.isArray(spans))
|
|
11
|
-
throw new SceneError("bad-trajectory", `addTrajectory("${id}"):
|
|
11
|
+
throw new SceneError("bad-trajectory", `addTrajectory("${id}"): ${field} must be a list`);
|
|
12
12
|
let previousEnd = -Infinity;
|
|
13
13
|
return spans.map((span, index) => {
|
|
14
14
|
let startUtcMs;
|
|
15
15
|
let endUtcMs;
|
|
16
|
-
let
|
|
16
|
+
let item;
|
|
17
17
|
try {
|
|
18
|
-
startUtcMs = toUtcMs(span?.start, `addTrajectory("${id}")
|
|
19
|
-
endUtcMs = toUtcMs(span?.end, `addTrajectory("${id}")
|
|
20
|
-
|
|
18
|
+
startUtcMs = toUtcMs(span?.start, `addTrajectory("${id}") ${field}[${index}] start`);
|
|
19
|
+
endUtcMs = toUtcMs(span?.end, `addTrajectory("${id}") ${field}[${index}] end`);
|
|
20
|
+
item = read(span);
|
|
21
21
|
}
|
|
22
22
|
catch (error) {
|
|
23
23
|
throw bad(index, error instanceof Error ? error.message : String(error));
|
|
24
24
|
}
|
|
25
25
|
if (endUtcMs <= startUtcMs)
|
|
26
26
|
throw bad(index, "must end after it starts");
|
|
27
|
-
if (startUtcMs <
|
|
27
|
+
if (startUtcMs < bounds.startUtcMs || endUtcMs > bounds.endUtcMs)
|
|
28
28
|
throw bad(index, "lies outside the path");
|
|
29
29
|
if (startUtcMs < previousEnd)
|
|
30
30
|
throw bad(index, "overlaps or is out of order; spans must be sorted and not overlap");
|
|
31
31
|
previousEnd = endUtcMs;
|
|
32
|
-
return { startUtcMs, endUtcMs
|
|
32
|
+
return { ...item, startUtcMs, endUtcMs };
|
|
33
|
+
});
|
|
34
|
+
}
|
|
35
|
+
/** Checks a path's provenance by time span (the same `{ start, end, provenance }` shape as an activity's) and returns it in milliseconds. */
|
|
36
|
+
export function planPathProvenance(id, spans, boundsUtcMs) {
|
|
37
|
+
return planSpans(id, "provenanceSpans", spans, boundsUtcMs, (span) => ({ provenance: createProvenance(span?.provenance) }));
|
|
38
|
+
}
|
|
39
|
+
/** Checks a path's `lineFixedTo` list (same span rules as `provenanceSpans`) and returns it in milliseconds. */
|
|
40
|
+
export function planLineStretches(id, stretches, boundsUtcMs) {
|
|
41
|
+
return planSpans(id, "lineFixedTo", stretches, boundsUtcMs, (stretch) => {
|
|
42
|
+
if (typeof stretch.body !== "string" || stretch.body === "")
|
|
43
|
+
throw new SceneError("bad-trajectory", "body must be a body id");
|
|
44
|
+
return { body: stretch.body };
|
|
33
45
|
});
|
|
34
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 {};
|