astraeus 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +39 -6
  3. package/package.json +9 -6
  4. package/src/api/AstraeusScene.d.ts +27 -0
  5. package/src/api/AstraeusScene.js +38 -0
  6. package/src/api/activity.d.ts +50 -0
  7. package/src/api/activity.js +62 -0
  8. package/src/api/bodies.d.ts +24 -0
  9. package/src/api/bodies.js +24 -0
  10. package/src/api/errors.d.ts +1 -1
  11. package/src/api/group.d.ts +83 -0
  12. package/src/api/group.js +121 -0
  13. package/src/api/index.d.ts +5 -1
  14. package/src/api/index.js +2 -1
  15. package/src/api/mount.d.ts +10 -1
  16. package/src/api/mount.js +12 -3
  17. package/src/api/prepared.d.ts +10 -0
  18. package/src/api/prepared.js +5 -0
  19. package/src/api/scene.d.ts +121 -8
  20. package/src/api/scene.js +464 -57
  21. package/src/api/story.d.ts +63 -0
  22. package/src/api/story.js +52 -0
  23. package/src/api/sunOrbit.d.ts +14 -0
  24. package/src/api/sunOrbit.js +61 -0
  25. package/src/api/switches.d.ts +14 -0
  26. package/src/api/switches.js +19 -0
  27. package/src/api/time.d.ts +4 -0
  28. package/src/api/time.js +8 -0
  29. package/src/app/App.js +35 -17
  30. package/src/app/AstraeusScene.d.ts +1 -1
  31. package/src/app/DebugOverlay.d.ts +3 -52
  32. package/src/app/DebugOverlay.js +2 -29
  33. package/src/app/PanelLoadBoundary.d.ts +18 -0
  34. package/src/app/PanelLoadBoundary.js +17 -0
  35. package/src/app/debugReadout.d.ts +53 -0
  36. package/src/app/debugReadout.js +30 -0
  37. package/src/app/developerPanels.d.ts +6 -0
  38. package/src/app/developerPanels.js +11 -0
  39. package/src/app/displaySwitches.d.ts +54 -0
  40. package/src/app/displaySwitches.js +48 -0
  41. package/src/app/experienceDefinition.d.ts +5 -1
  42. package/src/app/listSwitch.d.ts +16 -0
  43. package/src/{experiences/showers/showerChoice.js → app/listSwitch.js} +1 -9
  44. package/src/app/metricReadouts.d.ts +1 -1
  45. package/src/app/metricReadouts.js +1 -1
  46. package/src/app/openClock.d.ts +7 -0
  47. package/src/app/openClock.js +14 -0
  48. package/src/app/sceneContentsHooks.d.ts +3 -3
  49. package/src/app/sceneDebug.d.ts +1 -1
  50. package/src/app/sceneDebug.js +1 -1
  51. package/src/app/skyModel.js +2 -0
  52. package/src/app/trackedMetrics.d.ts +53 -0
  53. package/src/{experiences/apollo11/spacecraftMetrics.js → app/trackedMetrics.js} +40 -56
  54. package/src/assets/licence.d.ts +1 -0
  55. package/src/core/bodies/index.d.ts +3 -0
  56. package/src/core/bodies/index.js +3 -1
  57. package/src/core/planetSeries.d.ts +2 -0
  58. package/src/core/planetSeries.js +4 -0
  59. package/src/core/provenance.d.ts +2 -1
  60. package/src/core/scalePolicy.d.ts +3 -0
  61. package/src/core/scalePolicy.js +2 -0
  62. package/src/core/state.d.ts +1 -0
  63. package/src/shell/AstraeusShell.d.ts +4 -1
  64. package/src/shell/AstraeusShell.js +7 -3
  65. package/src/shell/DisplaySwitches.d.ts +16 -0
  66. package/src/shell/DisplaySwitches.js +31 -0
  67. package/src/shell/TimelineBar.css +4 -0
  68. package/src/shell/TopBar.css +20 -0
  69. package/src/shell/TopBar.d.ts +4 -1
  70. package/src/shell/TopBar.js +3 -2
  71. package/src/shell/experience.d.ts +2 -0
  72. package/src/shell/phone.css +3 -0
  73. package/src/shell/topBarIcons.d.ts +1 -0
  74. package/src/shell/topBarIcons.js +1 -0
  75. package/src/synthetic/syntheticDefinition.js +3 -3
  76. package/src/experiences/apollo11/spacecraftMetrics.d.ts +0 -34
  77. package/src/experiences/showers/showerChoice.d.ts +0 -25
@@ -0,0 +1,11 @@
1
+ import { lazy } from "react";
2
+ function onDemand(name) {
3
+ const Lazy = lazy(() => import("./DeveloperSettings.js").then((module) => ({ default: module[name] })));
4
+ return Lazy;
5
+ }
6
+ export const StoryPanelSettings = onDemand("StoryPanelSettings");
7
+ export const MoonsAndRingsSettings = onDemand("MoonsAndRingsSettings");
8
+ export const SkyAndSunSettings = onDemand("SkyAndSunSettings");
9
+ export const LabelSettings = onDemand("LabelSettings");
10
+ export const ViewLinkReadout = onDemand("ViewLinkReadout");
11
+ export const UnderTheHoodSettings = onDemand("UnderTheHoodSettings");
@@ -0,0 +1,54 @@
1
+ import type { DisplaySwitchItem } from "../shell/DisplaySwitches.js";
2
+ import type { OrbitLook } from "../assets/orbitLook.js";
3
+ import type { BodySetLook } from "./bodySet.js";
4
+ /** The display switches a story can place. Each one drives the same state as its Developer-drawer buttons, so the two never disagree. */
5
+ export declare const DISPLAY_SWITCH_IDS: readonly ["orbitLines", "labels", "milkyWay"];
6
+ export type DisplaySwitchId = (typeof DISPLAY_SWITCH_IDS)[number];
7
+ /** Where a switch shows: a button in the top bar, a row in the story switch panel opened from the bar, or only in the Developer drawer (where every switch stays). */
8
+ export declare const DISPLAY_SWITCH_PLACES: readonly ["top-bar", "panel", "developer"];
9
+ export type DisplaySwitchPlace = (typeof DISPLAY_SWITCH_PLACES)[number];
10
+ /** One switch's placement, and whether it starts on (absent: the scene's own start, which is on). */
11
+ export interface DisplaySwitchSetting {
12
+ readonly place: DisplaySwitchPlace;
13
+ readonly on?: boolean;
14
+ }
15
+ export type DisplaySwitchSettings = Readonly<Partial<Record<DisplaySwitchId, DisplaySwitchSetting>>>;
16
+ export declare const DISPLAY_SWITCH_LABELS: Readonly<Record<DisplaySwitchId, string>>;
17
+ /** Orbit lines are on while the ring, the trailing arc or the moon orbits show: the Developer buttons for any of them keep the switch in step. */
18
+ export declare function orbitLinesOn(orbit: Pick<OrbitLook, "baseOn" | "arcOn"> | null, moonOrbitsOn: boolean | null): boolean;
19
+ /** Labels are on while anchor labels or any object's name shows. */
20
+ export declare function labelsOn(objectIds: readonly string[], hidden: ReadonlySet<string>, anchorLabels: boolean | null): boolean;
21
+ /** The orbit-line state a start of `on` leaves; undefined: the scene's own start (on). */
22
+ export declare function orbitStart(setting: DisplaySwitchSetting | undefined): {
23
+ readonly look: Pick<OrbitLook, "baseOn" | "arcOn">;
24
+ readonly moonOrbitsOn: false;
25
+ } | undefined;
26
+ /** The pieces of live state the switches read and write; the setters write the scene's controls and the Developer drawer's state together. */
27
+ export interface SwitchBindings {
28
+ readonly settings: DisplaySwitchSettings | undefined;
29
+ readonly orbit: {
30
+ readonly present: boolean;
31
+ readonly look: Pick<OrbitLook, "baseOn" | "arcOn">;
32
+ readonly set: (change: Partial<OrbitLook>) => void;
33
+ };
34
+ readonly moons: {
35
+ readonly present: boolean;
36
+ readonly look: Pick<BodySetLook, "orbitsOn">;
37
+ readonly set: (change: Partial<BodySetLook>) => void;
38
+ };
39
+ readonly sky: {
40
+ readonly present: boolean;
41
+ readonly on: boolean;
42
+ readonly set: (on: boolean) => void;
43
+ };
44
+ readonly labels: {
45
+ readonly objectIds: readonly string[];
46
+ readonly hidden: ReadonlySet<string>;
47
+ readonly setHidden: (hidden: ReadonlySet<string>) => void;
48
+ readonly anchorsPresent: boolean;
49
+ readonly anchors: boolean;
50
+ readonly setAnchors: (on: boolean) => void;
51
+ };
52
+ }
53
+ /** The switches to draw in the top bar and the switch panel: the placed ones the scene has something for, in the order orbit lines, labels, Milky Way. */
54
+ export declare function displaySwitchItems(bindings: SwitchBindings): readonly DisplaySwitchItem[];
@@ -0,0 +1,48 @@
1
+ /** The display switches a story can place. Each one drives the same state as its Developer-drawer buttons, so the two never disagree. */
2
+ export const DISPLAY_SWITCH_IDS = ["orbitLines", "labels", "milkyWay"];
3
+ /** Where a switch shows: a button in the top bar, a row in the story switch panel opened from the bar, or only in the Developer drawer (where every switch stays). */
4
+ export const DISPLAY_SWITCH_PLACES = ["top-bar", "panel", "developer"];
5
+ export const DISPLAY_SWITCH_LABELS = { orbitLines: "Orbit lines", labels: "Labels", milkyWay: "Milky Way" };
6
+ /** Orbit lines are on while the ring, the trailing arc or the moon orbits show: the Developer buttons for any of them keep the switch in step. */
7
+ export function orbitLinesOn(orbit, moonOrbitsOn) {
8
+ return (orbit !== null && (orbit.baseOn || orbit.arcOn)) || moonOrbitsOn === true;
9
+ }
10
+ /** Labels are on while anchor labels or any object's name shows. */
11
+ export function labelsOn(objectIds, hidden, anchorLabels) {
12
+ return anchorLabels === true || objectIds.some((id) => !hidden.has(id));
13
+ }
14
+ /** The orbit-line state a start of `on` leaves; undefined: the scene's own start (on). */
15
+ export function orbitStart(setting) {
16
+ return setting?.on === false ? { look: { baseOn: false, arcOn: false }, moonOrbitsOn: false } : undefined;
17
+ }
18
+ function setOrbitLines(bindings, on) {
19
+ if (bindings.orbit.present)
20
+ bindings.orbit.set({ baseOn: on, arcOn: on });
21
+ if (bindings.moons.present)
22
+ bindings.moons.set({ orbitsOn: on });
23
+ }
24
+ function setLabels(bindings, on) {
25
+ const { labels } = bindings;
26
+ labels.setHidden(on ? new Set() : new Set(labels.objectIds));
27
+ if (labels.anchorsPresent)
28
+ labels.setAnchors(on);
29
+ }
30
+ /** The switches to draw in the top bar and the switch panel: the placed ones the scene has something for, in the order orbit lines, labels, Milky Way. */
31
+ export function displaySwitchItems(bindings) {
32
+ const { settings } = bindings;
33
+ if (settings === undefined)
34
+ return [];
35
+ const orbitOn = orbitLinesOn(bindings.orbit.present ? bindings.orbit.look : null, bindings.moons.present ? bindings.moons.look.orbitsOn : null);
36
+ const labelsNow = labelsOn(bindings.labels.objectIds, bindings.labels.hidden, bindings.labels.anchorsPresent ? bindings.labels.anchors : null);
37
+ const state = {
38
+ orbitLines: { applies: bindings.orbit.present || bindings.moons.present, on: orbitOn, toggle: () => setOrbitLines(bindings, !orbitOn) },
39
+ labels: { applies: bindings.labels.objectIds.length > 0 || bindings.labels.anchorsPresent, on: labelsNow, toggle: () => setLabels(bindings, !labelsNow) },
40
+ milkyWay: { applies: bindings.sky.present, on: bindings.sky.on, toggle: () => bindings.sky.set(!bindings.sky.on) },
41
+ };
42
+ return DISPLAY_SWITCH_IDS.flatMap((id) => {
43
+ const place = settings[id]?.place;
44
+ if ((place !== "top-bar" && place !== "panel") || !state[id].applies)
45
+ return [];
46
+ return [{ id, label: DISPLAY_SWITCH_LABELS[id], place, on: state[id].on, onToggle: state[id].toggle }];
47
+ });
48
+ }
@@ -14,6 +14,7 @@ import { type ScaleId } from "../shell/scaleModel.js";
14
14
  import type { TrackedBody } from "./mission.js";
15
15
  import type { SkySettings } from "../assets/sky.js";
16
16
  import { type BodySetLayer } from "./bodySet.js";
17
+ import type { DisplaySwitchSettings } from "./displaySwitches.js";
17
18
  /** Generic scene parts an experience opts into. Nothing here names a mission. */
18
19
  export type SceneLayerId = "tracked-bodies" | "points" | "sun-centred";
19
20
  /** What the generic app owns and hands to the experience's factories. */
@@ -141,7 +142,8 @@ export interface ExperienceDefinition {
141
142
  readonly experience: ExperienceConfig;
142
143
  readonly clock: {
143
144
  readonly startUtcMs: number;
144
- readonly rate: number;
145
+ readonly rate: number; /** False leaves the clock paused at `startUtcMs` when the scene opens (default true: it plays). */
146
+ readonly playing?: boolean;
145
147
  };
146
148
  /** Layers the scene mounts, e.g. the tracked-body list. */
147
149
  readonly sceneLayers: readonly SceneLayerId[];
@@ -189,6 +191,8 @@ export interface ExperienceDefinition {
189
191
  }[];
190
192
  /** A choice between versions of this experience, shown in the top bar and the phone drawer: choosing one opens it again with `?param=value` (the camera view and time of the old address are dropped). Absent: none. */
191
193
  readonly switcher?: import("../shell/SwitchControl.js").ExperienceSwitch;
194
+ /** Where the orbit-lines, labels and Milky Way switches show (top bar, switch panel or the Developer drawer only) and whether each starts on. Absent: all in the Developer drawer, the scene's own start. The address (`?labels=`, `?sky=`) still overrides the start. */
195
+ readonly displaySwitches?: DisplaySwitchSettings;
192
196
  /** Which direction the camera treats as up (default "equatorial", celestial north; "ecliptic" orbits about the ecliptic pole so the planets' plane reads flat). */
193
197
  readonly viewUp?: import("./viewUp.js").ViewUp;
194
198
  /** The camera view to open on (focus id, azimuth and elevation in degrees, distance in scaled units). Absent: the usual opening. `?view=` overrides it. */
@@ -0,0 +1,16 @@
1
+ import type { ExperienceSwitch } from "../shell/SwitchControl.js";
2
+ /** One entry the experience can open: its settings file's name, its label, and its place in the switch (the lowest `order` is the default). */
3
+ export interface SwitchEntry {
4
+ readonly name: string;
5
+ readonly label: string;
6
+ readonly order: number;
7
+ }
8
+ /** The entry to open (the requested one when it exists, else `preferred`, else the first by `order`, then name) and the switch listing every entry. Undefined when there are none. */
9
+ export declare function chooseSwitch<T extends SwitchEntry>(entries: readonly T[], requested: string | null, switchOf: {
10
+ readonly label: string;
11
+ readonly param: string;
12
+ readonly keep?: readonly string[];
13
+ }, preferred?: string): {
14
+ readonly name: string;
15
+ readonly switcher: ExperienceSwitch;
16
+ } | undefined;
@@ -1,8 +1,4 @@
1
- /** The address parameter that names the shower (`?experience=showers&shower=<name>`). */
2
- export const SHOWER_PARAM = "shower";
3
- /** The label the switch carries as its accessible name. */
4
- export const SHOWER_SWITCH_LABEL = "Shower";
5
- /** The entry to open (the requested one when it exists, else `preferred`, else the first by `order`, then name) and the switch listing every entry. Undefined when there are none. Shared by the experiences that offer such a switch. */
1
+ /** The entry to open (the requested one when it exists, else `preferred`, else the first by `order`, then name) and the switch listing every entry. Undefined when there are none. */
6
2
  export function chooseSwitch(entries, requested, switchOf, preferred) {
7
3
  const sorted = [...entries].sort((a, b) => a.order - b.order || a.name.localeCompare(b.name));
8
4
  const chosen = sorted.find((entry) => entry.name === requested) ?? sorted.find((entry) => entry.name === preferred) ?? sorted[0];
@@ -13,7 +9,3 @@ export function chooseSwitch(entries, requested, switchOf, preferred) {
13
9
  switcher: { label: switchOf.label, param: switchOf.param, ...(switchOf.keep === undefined ? {} : { keep: switchOf.keep }), options: sorted.map((entry) => ({ label: entry.label, value: entry.name, active: entry === chosen })) },
14
10
  };
15
11
  }
16
- /** The shower to open (the requested one when it exists, else the first by `order`, then name) and the switch listing every shower. Undefined when there are no showers. */
17
- export function chooseShower(entries, requested) {
18
- return chooseSwitch(entries, requested, { label: SHOWER_SWITCH_LABEL, param: SHOWER_PARAM });
19
- }
@@ -1,6 +1,6 @@
1
1
  import type { TimelineEvent } from "../core/events.js";
2
2
  import type { Metric, ProgressMetric } from "../shell/metrics.js";
3
- import { type DebugReadout } from "./DebugOverlay.js";
3
+ import { type DebugReadout } from "./debugReadout.js";
4
4
  /** Elapsed time from the first to the last event, with every event as a milestone. */
5
5
  export declare function journeyProgressMetric(events: readonly TimelineEvent[], timeUtcMs: number, labels: {
6
6
  readonly start: string;
@@ -1,4 +1,4 @@
1
- import { EARTH_MOON_LABELS } from "./DebugOverlay.js";
1
+ import { EARTH_MOON_LABELS } from "./debugReadout.js";
2
2
  const HOUR_MS = 3_600_000;
3
3
  const centreName = (center) => `${center.charAt(0).toUpperCase()}${center.slice(1)} centre`;
4
4
  /** Elapsed time from the first to the last event, with every event as a milestone. */
@@ -0,0 +1,7 @@
1
+ import { SimulationClock } from "../core/clock.js";
2
+ import type { ExperienceDefinition } from "./experienceDefinition.js";
3
+ /**
4
+ * The clock a mounted experience opens with: at its start moment and rate (or at the moment a copied link carried), playing unless the definition says
5
+ * `clock.playing: false`, which leaves it frozen there.
6
+ */
7
+ export declare function openClock(definition: Pick<ExperienceDefinition, "clock">, linkedTimeUtcMs?: number): SimulationClock;
@@ -0,0 +1,14 @@
1
+ import { SimulationClock } from "../core/clock.js";
2
+ /**
3
+ * The clock a mounted experience opens with: at its start moment and rate (or at the moment a copied link carried), playing unless the definition says
4
+ * `clock.playing: false`, which leaves it frozen there.
5
+ */
6
+ export function openClock(definition, linkedTimeUtcMs) {
7
+ const clock = new SimulationClock(definition.clock.startUtcMs);
8
+ clock.setRate(definition.clock.rate);
9
+ if (linkedTimeUtcMs !== undefined)
10
+ clock.seek(linkedTimeUtcMs);
11
+ if (definition.clock.playing !== false)
12
+ clock.play();
13
+ return clock;
14
+ }
@@ -23,9 +23,9 @@ export declare function bodyIdOf(runtime: {
23
23
  export declare function refFor<T>(map: Map<BodyId, T>, id: BodyId): (node: T | null) => void;
24
24
  /** The mounted nodes of every body: groups, orientation nodes, lights and body parts, with one stable parts callback per body. */
25
25
  export declare function useBodyRefs(runtime: SceneRuntime): {
26
- groupRefs: import("react").MutableRefObject<Map<string, Group<import("three").Object3DEventMap>>>;
27
- orientRefs: import("react").MutableRefObject<Map<string, Group<import("three").Object3DEventMap>>>;
28
- lightRefs: import("react").MutableRefObject<Map<string, DirectionalLight>>;
26
+ groupRefs: import("react").RefObject<Map<string, Group<import("three").Object3DEventMap>>>;
27
+ orientRefs: import("react").RefObject<Map<string, Group<import("three").Object3DEventMap>>>;
28
+ lightRefs: import("react").RefObject<Map<string, DirectionalLight>>;
29
29
  partsFor: Map<string, (node: BodyParts | null) => void>;
30
30
  bodyRefs: BodyRefs;
31
31
  };
@@ -5,7 +5,7 @@ import type { StateResolver } from "../core/stateResolver.js";
5
5
  import type { Camera } from "three";
6
6
  import type { PathView } from "./PathView.js";
7
7
  import type { BodyScreenReadout } from "./sceneBodies.js";
8
- import { type DebugReadout } from "./DebugOverlay.js";
8
+ import { type DebugReadout } from "./debugReadout.js";
9
9
  import type { FloatingOrigin } from "./floatingOrigin.js";
10
10
  import type { FrameStats } from "./frameStats.js";
11
11
  import type { GroupFill } from "./FrameRateSection.js";
@@ -1,5 +1,5 @@
1
1
  import { rootBodyId } from "../assets/catalogue.js";
2
- import { buildDebugReadout } from "./DebugOverlay.js";
2
+ import { buildDebugReadout } from "./debugReadout.js";
3
3
  /** Sets one `data-` attribute on the canvas, only when it changed (the browser scripts read these). */
4
4
  export function setDatum(canvas, key, value) {
5
5
  if (canvas.dataset[key] !== value)
@@ -38,6 +38,8 @@ export function skyObject(status) {
38
38
  return {
39
39
  id: SKY_OBJECT_ID,
40
40
  label: "Sky",
41
+ // Drawn and still an object, but not offered in the object drop-downs (owner, 2026-10-24); its credits stay in NOTICE and on the home page.
42
+ listed: false,
41
43
  description: "Stars and the Milky Way, drawn at infinity behind the scene. The sky turns only with the camera; the scene centre, scale and followed object do not move it.",
42
44
  provenance,
43
45
  knownLimitations: [
@@ -0,0 +1,53 @@
1
+ import type { BodyId } from "../core/body.js";
2
+ import type { StateResolver } from "../core/stateResolver.js";
3
+ import { type BodyCatalogue } from "../assets/catalogue.js";
4
+ import type { CenteredPosition } from "../core/state.js";
5
+ import { type TrackedBody, type TrackedReadout } from "./mission.js";
6
+ import type { AltitudeMetric, DistanceMetric, Metric, MetricReference, RelativeDistanceMetric, SpeedMetric, UncertaintyMetric } from "../shell/metrics.js";
7
+ /**
8
+ * Highest speed at the body's NASA source anchors, the honest top of its speed gauge. Anchors rather
9
+ * than reconstructed samples, because a smoothed join can carry a known non-physical spike (I-008).
10
+ * Null when the body has no anchors or the trajectory carries no velocity.
11
+ */
12
+ export declare function peakAnchorSpeedKmS(body: TrackedBody): number | null;
13
+ /** A reference marker only when it is measured from the same centre and in the same frame as the value. */
14
+ export declare function referenceInSameFrame(label: string, row: Pick<TrackedReadout, "frame" | "center">, reference: CenteredPosition | null): MetricReference | null;
15
+ export declare function spacecraftRangeMetric(row: TrackedReadout, moon: MetricReference | null): DistanceMetric;
16
+ export declare function spacecraftSpeedMetric(row: TrackedReadout, peakKmS: number | null): SpeedMetric;
17
+ /** A body a path's readouts are measured against: its id, its name and its mean radius. */
18
+ export interface ReadoutTarget {
19
+ readonly id: string;
20
+ readonly label: string;
21
+ readonly radiusKm: number;
22
+ }
23
+ /** The target's state when it shares the path's centre and frame, otherwise null. */
24
+ export declare function inSameFrame(row: Pick<TrackedReadout, "frame" | "center">, state: CenteredPosition | null): CenteredPosition | null;
25
+ export declare const separationKm: (a: readonly number[], b: ArrayLike<number>) => number;
26
+ /** Centre-to-centre distance from the path to a body, drawn in that body's radii. */
27
+ export declare function pathDistanceMetric(row: TrackedReadout, target: ReadoutTarget, state: CenteredPosition | null): RelativeDistanceMetric;
28
+ /** Height above a body's mean radius (not terrain: on the surface the value can be negative); null when the body has no state in the path's frame. */
29
+ export declare function pathAltitudeMetric(row: TrackedReadout, target: ReadoutTarget, state: CenteredPosition | null): AltitudeMetric;
30
+ /** The data's own discrepancy for the segment at this time, compared with the vehicle's largest. */
31
+ export declare function spacecraftDiscrepancyMetric(body: TrackedBody, timeUtcMs: number): UncertaintyMetric;
32
+ /** One bar on a path's info card. */
33
+ export type ReadoutSpec = {
34
+ readonly kind: "range";
35
+ readonly marker?: BodyId;
36
+ } | {
37
+ readonly kind: "speed";
38
+ } | {
39
+ readonly kind: "distance";
40
+ readonly to: BodyId;
41
+ } | {
42
+ readonly kind: "altitude";
43
+ readonly above: BodyId;
44
+ };
45
+ export interface PathReadouts {
46
+ readonly body: TrackedBody;
47
+ readonly readouts: readonly ReadoutSpec[];
48
+ }
49
+ /**
50
+ * The info card's bars for paths that ask for readouts, from State only. Range is from the path's centre body; a named body is read from the
51
+ * resolver about that centre, so it shares the path's frame. A path outside its bounds and any other id have none.
52
+ */
53
+ export declare function createReadoutMetrics(paths: readonly PathReadouts[], resolver: StateResolver, source?: BodyCatalogue): (objectId: string, timeUtcMs: number) => readonly Metric[];
@@ -1,5 +1,5 @@
1
- import { EARTH, MOON } from "../../core/body.js";
2
- import { discrepancyAt, trackedReadouts } from "../../app/mission.js";
1
+ import { catalogue as builtInCatalogue } from "../assets/catalogue.js";
2
+ import { discrepancyAt, trackedReadouts } from "./mission.js";
3
3
  const centreName = (center) => `${center.charAt(0).toUpperCase()}${center.slice(1)} centre`;
4
4
  /**
5
5
  * Highest speed at the body's NASA source anchors, the honest top of its speed gauge. Anchors rather
@@ -47,62 +47,42 @@ export function spacecraftSpeedMetric(row, peakKmS) {
47
47
  ...(peakKmS === null ? {} : { range: { min: 0, max: peakKmS, basis: "peak at NASA source anchors", digits: 1 } }),
48
48
  };
49
49
  }
50
- /** The Moon's state when it shares the spacecraft's centre and frame, otherwise null. */
51
- function moonInSameFrame(row, moon) {
52
- return moon !== null && moon.center === row.center && moon.frame === row.frame ? moon : null;
50
+ /** The target's state when it shares the path's centre and frame, otherwise null. */
51
+ export function inSameFrame(row, state) {
52
+ return state !== null && state.center === row.center && state.frame === row.frame ? state : null;
53
53
  }
54
- const separationKm = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
55
- /** Centre-to-centre distance from the spacecraft to the Moon, drawn in Moon radii. */
56
- export function spacecraftMoonMetric(row, moon) {
57
- const same = moonInSameFrame(row, moon);
54
+ export const separationKm = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
55
+ /** Centre-to-centre distance from the path to a body, drawn in that body's radii. */
56
+ export function pathDistanceMetric(row, target, state) {
57
+ const same = inSameFrame(row, state);
58
58
  return {
59
59
  kind: "relative-distance",
60
- id: `${row.id}-to-moon`,
61
- label: "Distance to Moon",
60
+ id: `${row.id}-to-${target.id}`,
61
+ label: `Distance to ${target.label}`,
62
62
  value: same === null ? null : separationKm(row.positionKm, same.positionKm),
63
63
  unit: "km",
64
64
  digits: 0,
65
65
  from: row.label,
66
- to: "Moon",
67
- targetRadius: MOON.radiusKm,
66
+ to: target.label,
67
+ targetRadius: target.radiusKm,
68
68
  context: `centre to centre · ${row.frame}`,
69
- unavailable: "no Moon state in this frame",
69
+ unavailable: `no ${target.label} state in this frame`,
70
70
  };
71
71
  }
72
- /**
73
- * Height above the mean radius of whichever of Earth and the Moon is closer to the surface.
74
- * Mean radius, not terrain: on the lunar surface the value can be negative.
75
- */
76
- export function spacecraftAltitudeMetric(row, moon) {
77
- const aboveEarth = row.rangeFromEarthKm - EARTH.radiusKm;
78
- const same = moonInSameFrame(row, moon);
79
- const aboveMoon = same === null ? Infinity : separationKm(row.positionKm, same.positionKm) - MOON.radiusKm;
80
- const nearMoon = aboveMoon < aboveEarth;
72
+ /** Height above a body's mean radius (not terrain: on the surface the value can be negative); null when the body has no state in the path's frame. */
73
+ export function pathAltitudeMetric(row, target, state) {
74
+ const same = inSameFrame(row, state);
75
+ const away = same === null ? null : separationKm(row.positionKm, same.positionKm);
81
76
  return {
82
77
  kind: "altitude",
83
- id: `${row.id}-altitude`,
84
- label: "Altitude",
85
- value: nearMoon ? aboveMoon : aboveEarth,
78
+ id: `${row.id}-altitude-${target.id}`,
79
+ label: `Altitude above ${target.label}`,
80
+ value: away === null ? null : away - target.radiusKm,
86
81
  unit: "km",
87
82
  digits: 1,
88
- body: nearMoon ? "Moon" : "Earth",
83
+ body: target.label,
89
84
  datum: "mean radius",
90
- bodyRadius: nearMoon ? MOON.radiusKm : EARTH.radiusKm,
91
- };
92
- }
93
- export function spacecraftPositionMetric(row, moon) {
94
- const same = moonInSameFrame(row, moon);
95
- return {
96
- kind: "coordinates",
97
- id: `${row.id}-position`,
98
- label: "Position",
99
- system: "xyz",
100
- components: ["x", "y", "z"].map((label, index) => ({ label, value: row.positionKm[index], unit: "km", digits: 0 })),
101
- frame: row.frame,
102
- origin: centreName(row.center),
103
- planViews: {
104
- references: same === null ? [] : [{ label: "Moon", xyz: [same.positionKm[0], same.positionKm[1], same.positionKm[2]] }],
105
- },
85
+ bodyRadius: target.radiusKm,
106
86
  };
107
87
  }
108
88
  /** The data's own discrepancy for the segment at this time, compared with the vehicle's largest. */
@@ -121,22 +101,26 @@ export function spacecraftDiscrepancyMetric(body, timeUtcMs) {
121
101
  ...(published.length === 0 ? {} : { scale: { max: Math.max(...published), basis: "this vehicle's reconstruction" } }),
122
102
  };
123
103
  }
104
+ const targetOf = (id, source) => ({ id, label: source.get(id).definition.label, radiusKm: source.get(id).definition.radiusKm });
124
105
  /**
125
- * The info panel's range, speed and Moon-distance rows for one tracked body, from State only: scale policy and camera never
126
- * enter. A tracked body outside its bounds and any other id have none. The catalogued bodies' own rows are `bodyMetrics`'.
106
+ * The info card's bars for paths that ask for readouts, from State only. Range is from the path's centre body; a named body is read from the
107
+ * resolver about that centre, so it shares the path's frame. A path outside its bounds and any other id have none.
127
108
  */
128
- export function createTrackedMetrics({ bodies, moon }) {
129
- const peaks = new Map(bodies.map((body) => [body.id, peakAnchorSpeedKmS(body)]));
109
+ export function createReadoutMetrics(paths, resolver, source = builtInCatalogue) {
110
+ const peaks = new Map(paths.map(({ body }) => [body.id, peakAnchorSpeedKmS(body)]));
130
111
  return (objectId, timeUtcMs) => {
131
- const body = bodies.find((candidate) => candidate.id === objectId);
132
- const row = body === undefined ? undefined : trackedReadouts([body], timeUtcMs)[0];
133
- if (row === undefined)
112
+ const path = paths.find(({ body }) => body.id === objectId);
113
+ const row = path === undefined ? undefined : trackedReadouts([path.body], timeUtcMs)[0];
114
+ if (path === undefined || row === undefined)
134
115
  return [];
135
- const moonState = moon.stateAt(timeUtcMs);
136
- return [
137
- spacecraftRangeMetric(row, referenceInSameFrame("Moon now", row, moonState)),
138
- spacecraftSpeedMetric(row, peaks.get(row.id) ?? null),
139
- spacecraftMoonMetric(row, moonState),
140
- ];
116
+ const stateOf = (id) => (id === row.center ? { body: id, center: row.center, timeUtcMs, frame: row.frame, positionKm: new Float64Array(3) } : resolver.stateOf(id, timeUtcMs, row.center));
117
+ return path.readouts.map((spec) => {
118
+ switch (spec.kind) {
119
+ case "range": return spacecraftRangeMetric(row, spec.marker === undefined ? null : referenceInSameFrame(`${targetOf(spec.marker, source).label} now`, row, stateOf(spec.marker)));
120
+ case "speed": return spacecraftSpeedMetric(row, peaks.get(row.id) ?? null);
121
+ case "distance": return pathDistanceMetric(row, targetOf(spec.to, source), stateOf(spec.to));
122
+ case "altitude": return pathAltitudeMetric(row, targetOf(spec.above, source), stateOf(spec.above));
123
+ }
124
+ });
141
125
  };
142
126
  }
@@ -19,6 +19,7 @@ export interface LocalOnlyDeclaration {
19
19
  readonly reason: string;
20
20
  readonly publicReplacement: PublicReplacement;
21
21
  }
22
+ /** A picture the engine can wrap on a body: where it is, its size, and the rights to show it publicly. */
22
23
  export interface TextureRef {
23
24
  /** Bundler asset URL. */
24
25
  readonly url: string;
@@ -1,4 +1,5 @@
1
1
  import type { CelestialBodyDefinition, StateSourceBinding } from "../body.js";
2
+ import type { EccentricSampling } from "../sunCentredSources.js";
2
3
  export { EARTH, EARTH_EPHEMERIS } from "./earth.js";
3
4
  export { MOON, MOON_EPHEMERIS } from "./moon.js";
4
5
  export { SUN } from "./sun.js";
@@ -14,3 +15,5 @@ export { VENUS, VENUS_EPHEMERIS, VENUS_ROTATION } from "./venus.js";
14
15
  export declare const BUILT_IN_BODIES: readonly CelestialBodyDefinition[];
15
16
  /** One state source per non-root body; the Sun is the root and has none. */
16
17
  export declare const BUILT_IN_BINDINGS: readonly StateSourceBinding[];
18
+ /** Built-in bodies whose period and periapsis the catalogue knows (a comet's century-long orbit), so their whole orbit can be drawn from periapsis. */
19
+ export declare const BUILT_IN_SAMPLING: Readonly<Record<string, EccentricSampling>>;
@@ -11,7 +11,7 @@ import { MERCURY, MERCURY_ROTATION } from "./mercury.js";
11
11
  import { NEPTUNE, NEPTUNE_ROTATION, PLUTO, SATURN, SATURN_ROTATION, URANUS, URANUS_ROTATION } from "./outerPlanets.js";
12
12
  import { PLANET_MOON_BINDINGS, PLANET_MOON_DEFINITIONS, PLUTO_BINDING } from "./planetMoons.js";
13
13
  import { SUN } from "./sun.js";
14
- import { SWIFT_TUTTLE, SWIFT_TUTTLE_BINDING } from "./swiftTuttle.js";
14
+ import { SWIFT_TUTTLE, SWIFT_TUTTLE_BINDING, SWIFT_TUTTLE_SAMPLING } from "./swiftTuttle.js";
15
15
  import { VENUS, VENUS_ROTATION } from "./venus.js";
16
16
  export { EARTH, EARTH_EPHEMERIS } from "./earth.js";
17
17
  export { MOON, MOON_EPHEMERIS } from "./moon.js";
@@ -43,3 +43,5 @@ export const BUILT_IN_BINDINGS = Object.freeze([
43
43
  ...PLANET_MOON_BINDINGS,
44
44
  SWIFT_TUTTLE_BINDING,
45
45
  ]);
46
+ /** Built-in bodies whose period and periapsis the catalogue knows (a comet's century-long orbit), so their whole orbit can be drawn from periapsis. */
47
+ export const BUILT_IN_SAMPLING = Object.freeze({ [SWIFT_TUTTLE.id]: SWIFT_TUTTLE_SAMPLING });
@@ -22,5 +22,7 @@ export type PlanetModels = {
22
22
  * downloads them (I-022).
23
23
  */
24
24
  export declare function loadPlanetSeries(): Promise<void>;
25
+ /** Whether the planet series have finished loading. */
26
+ export declare function planetSeriesLoaded(): boolean;
25
27
  /** The loaded planet models; throws before `loadPlanetSeries()` resolved rather than falling back to the compact tables. */
26
28
  export declare function planetModels(): PlanetModels;
@@ -14,6 +14,10 @@ export function loadPlanetSeries() {
14
14
  loading ??= import("./planetModels.js").then((module) => { models = module.createPlanetModels(); });
15
15
  return loading;
16
16
  }
17
+ /** Whether the planet series have finished loading. */
18
+ export function planetSeriesLoaded() {
19
+ return models !== undefined;
20
+ }
17
21
  /** The loaded planet models; throws before `loadPlanetSeries()` resolved rather than falling back to the compact tables. */
18
22
  export function planetModels() {
19
23
  if (models === undefined)
@@ -1,5 +1,6 @@
1
+ /** What kind of source a path or body position comes from. */
1
2
  export type ProvenanceSourceType = "ephemeris" | "observed" | "reconstructed" | "illustrative";
2
- /** Where a Trajectory's samples came from and how far to trust them. Never affects State. */
3
+ /** 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. */
3
4
  export interface Provenance {
4
5
  readonly sourceType: ProvenanceSourceType;
5
6
  readonly sources: readonly string[];
@@ -1,4 +1,5 @@
1
1
  import { type BodyId } from "./body.js";
2
+ /** How kilometres become scene units: a position mapping and a radius mapping. `trueScale` and `readableScale` are the two the engine offers. */
2
3
  export interface ScalePolicy {
3
4
  /** Open: an application may supply policies beyond the engine's own three. */
4
5
  readonly id: string;
@@ -26,7 +27,9 @@ export declare class ReadableScalePolicy extends EarthRadiusScale {
26
27
  readonly id: "readable-scale";
27
28
  protected readonly distanceFactor = 0.1;
28
29
  }
30
+ /** Real proportions: distances and body sizes at the same scale, so planets are specks, as in space. */
29
31
  export declare const trueScale: ScalePolicy;
32
+ /** Distances shrunk to a tenth while body sizes are kept, so bodies are easier to see and pick. */
30
33
  export declare const readableScale: ScalePolicy;
31
34
  /** Per-body enlargement of drawn radii; distances stay exactly as True scale maps them. */
32
35
  export interface SolarSystemScaleOptions {
@@ -30,7 +30,9 @@ export class ReadableScalePolicy extends EarthRadiusScale {
30
30
  id = "readable-scale";
31
31
  distanceFactor = 0.1;
32
32
  }
33
+ /** Real proportions: distances and body sizes at the same scale, so planets are specks, as in space. */
33
34
  export const trueScale = Object.freeze(new TrueScalePolicy());
35
+ /** Distances shrunk to a tenth while body sizes are kept, so bodies are easier to see and pick. */
34
36
  export const readableScale = Object.freeze(new ReadableScalePolicy());
35
37
  function validateFactor(label, factor) {
36
38
  if (!Number.isFinite(factor) || factor < 1)
@@ -10,6 +10,7 @@ export interface CenteredPosition {
10
10
  readonly positionKm: Float64Array;
11
11
  readonly velocityKmS?: Float64Array;
12
12
  }
13
+ /** Where a body is at one moment, as the engine reports it: position (and velocity when known) in km about a centre, in the EQJ frame, with its attitude when modelled. */
13
14
  export interface State extends CenteredPosition {
14
15
  /** Body-fixed +X/+Y/+Z axes expressed in EQJ; null means this body's attitude is not modeled. */
15
16
  readonly orientation: Quaternion | null;
@@ -5,6 +5,7 @@ import type { TimelineGlowLook } from "./timelineGlow.js";
5
5
  import type { ExperienceCameraPreset, ExperienceConfig } from "./experience.js";
6
6
  import type { Metric } from "./metrics.js";
7
7
  import { type PhoneLayoutSettings } from "./phoneLayout.js";
8
+ import type { DisplaySwitchItem } from "./DisplaySwitches.js";
8
9
  import type { ExperienceSwitch } from "./SwitchControl.js";
9
10
  import type { ScaleChoice, ScaleId } from "./scaleModel.js";
10
11
  import "./controls.css";
@@ -26,6 +27,8 @@ interface Props {
26
27
  readonly scaleChoices?: readonly ScaleChoice[];
27
28
  /** A choice between versions of the experience (top bar and phone drawer); absent: none. */
28
29
  readonly switcher?: ExperienceSwitch;
30
+ /** Display switches a story placed in the top bar or its switch panel (also in the phone drawer); absent or empty: none. */
31
+ readonly displaySwitches?: readonly DisplaySwitchItem[];
29
32
  /** Live measurements for an object's info panel, from the app's own State; empty when it has none. */
30
33
  readonly metricsFor?: (objectId: string, timeUtcMs: number) => readonly Metric[];
31
34
  readonly developerTools?: ReactNode;
@@ -62,5 +65,5 @@ interface Props {
62
65
  readonly children: ReactNode;
63
66
  }
64
67
  /** Canvas-first layout shared by astronomy experiences. Scene and diagnostics stay app-owned. */
65
- export declare function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, onSeek, onCameraRequest, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout, highlightedFamily, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, children, }: Props): import("react").JSX.Element;
68
+ export declare function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, onSeek, onCameraRequest, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout, highlightedFamily, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, children, }: Props): import("react").JSX.Element;
66
69
  export {};