astraeus 0.8.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 (42) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +21 -5
  3. package/data/ephemerides/planets/planets.json +1 -1
  4. package/package.json +1 -1
  5. package/src/api/errors.d.ts +2 -0
  6. package/src/api/viewerHandle.d.ts +8 -2
  7. package/src/api/viewerHandle.js +1 -0
  8. package/src/api/viewerLink.d.ts +1 -0
  9. package/src/api/viewerLink.js +8 -2
  10. package/src/api/viewerSelection.d.ts +6 -1
  11. package/src/api/viewerSelection.js +15 -0
  12. package/src/api/views.d.ts +3 -1
  13. package/src/api/views.js +5 -1
  14. package/src/app/App.js +24 -4
  15. package/src/app/App.node.js +24 -4
  16. package/src/app/AstraeusScene.d.ts +2 -0
  17. package/src/app/sceneCamera.d.ts +2 -0
  18. package/src/app/sceneCamera.js +2 -1
  19. package/src/app/viewerPort.d.ts +2 -0
  20. package/src/app/views.d.ts +2 -0
  21. package/src/core/astronomyAdapter.d.ts +1 -1
  22. package/src/core/astronomyAdapter.js +3 -3
  23. package/src/core/bodies/index.js +13 -12
  24. package/src/core/bodies/jupiter.js +1 -1
  25. package/src/core/bodies/mars.js +1 -1
  26. package/src/core/bodies/mercury.js +1 -1
  27. package/src/core/bodies/outerPlanets.d.ts +2 -3
  28. package/src/core/bodies/outerPlanets.js +4 -13
  29. package/src/core/bodies/planetMoons.d.ts +0 -2
  30. package/src/core/bodies/planetMoons.js +1 -18
  31. package/src/core/bodies/planetRecords.d.ts +8 -2
  32. package/src/core/bodies/planetRecords.js +13 -5
  33. package/src/core/bodies/planetTrajectory.d.ts +21 -4
  34. package/src/core/bodies/planetTrajectory.js +28 -4
  35. package/src/core/bodies/venus.js +1 -1
  36. package/src/core/planetModels.d.ts +1 -1
  37. package/src/core/planetModels.js +1 -1
  38. package/src/core/planetSeries.d.ts +2 -2
  39. package/src/core/planetSeries.js +1 -1
  40. package/src/shell/AstraeusShell.d.ts +13 -1
  41. package/src/shell/AstraeusShell.js +33 -3
  42. package/src/shell/AstraeusShell.node.js +33 -3
@@ -4,5 +4,11 @@ import type { TimeBounds } from "../trajectory.js";
4
4
  export declare const PLANET_VALIDATED_UTC: TimeBounds;
5
5
  export declare const IAU_REPORT = "Archinal et al., Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements: 2015, Celestial Mechanics and Dynamical Astronomy 130, article 22 (2018), as transcribed in NAIF pck00011.tpc (2022-12-27)";
6
6
  export declare const ROTATION_LIMITATION = "Orientation is the IAU pole direction (linear in time) and prime meridian (linear in time) only; the report's periodic nutation and libration terms are left out, and TT stands in for TDB.";
7
- /** Position provenance shared by the four VSOP87A planets; `measured` is the sample maximum quoted from docs/ASTRONOMY_VALIDATION.md. */
8
- export declare function planetEphemeris(label: string, measured: string, extraLimitations?: readonly string[]): EphemerisRecord;
7
+ /** The date the Horizons states behind the planet series were retrieved (O-063 T-290). */
8
+ export declare const PLANET_SERIES_RETRIEVED = "2026-11-10";
9
+ /**
10
+ * Position provenance shared by the planets (O-063 T-290): the series is the planet's system barycentre as JPL Horizons reports the planet, and a
11
+ * planet with a moon system adds its own offset from that barycentre from its moon package when that is loaded. `body` names the Horizons
12
+ * target, `centreSource` how Horizons places it, `measured` the figures against Horizons, `withoutPackage` what changes without the package.
13
+ */
14
+ export declare function planetEphemeris(label: string, body: string, centreSource: string, measured: string, withoutPackage?: string): EphemerisRecord;
@@ -3,17 +3,25 @@ import { createProvenance } from "../provenance.js";
3
3
  export const PLANET_VALIDATED_UTC = Object.freeze({ startUtcMs: Date.UTC(1969, 6, 21), endUtcMs: Date.UTC(2030, 5, 1) });
4
4
  export const IAU_REPORT = "Archinal et al., Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements: 2015, Celestial Mechanics and Dynamical Astronomy 130, article 22 (2018), as transcribed in NAIF pck00011.tpc (2022-12-27)";
5
5
  export const ROTATION_LIMITATION = "Orientation is the IAU pole direction (linear in time) and prime meridian (linear in time) only; the report's periodic nutation and libration terms are left out, and TT stands in for TDB.";
6
- /** Position provenance shared by the four VSOP87A planets; `measured` is the sample maximum quoted from docs/ASTRONOMY_VALIDATION.md. */
7
- export function planetEphemeris(label, measured, extraLimitations = []) {
6
+ /** The date the Horizons states behind the planet series were retrieved (O-063 T-290). */
7
+ export const PLANET_SERIES_RETRIEVED = "2026-11-10";
8
+ /** Before 1972 the engine and Horizons label the same instant differently; measured 1950 to 1971 against Horizons (tests/planetAccuracyFlybys.test.ts). */
9
+ const PRE_1972_LIMITATION = "Before 1972 a date is read on the engine's smooth TT - UTC, while Horizons labels times in UT1 (to 1962) and in UTC's rubber seconds (to 1972): the same label can be up to 0.7 s apart, so a planet can sit up to that much travel away from Horizons' position for that label (measured 1950 to 1971: Mercury 34.5 km, Venus 24.3, Mars 16.8, Jupiter 8.5, Saturn 6.2, Uranus 4.7, Neptune 3.5).";
10
+ /**
11
+ * Position provenance shared by the planets (O-063 T-290): the series is the planet's system barycentre as JPL Horizons reports the planet, and a
12
+ * planet with a moon system adds its own offset from that barycentre from its moon package when that is loaded. `body` names the Horizons
13
+ * target, `centreSource` how Horizons places it, `measured` the figures against Horizons, `withoutPackage` what changes without the package.
14
+ */
15
+ export function planetEphemeris(label, body, centreSource, measured, withoutPackage) {
8
16
  return {
9
17
  provenance: createProvenance({
10
18
  sourceType: "ephemeris",
11
19
  sources: [
12
- "@lizard-isana/orb 3.1.1 VSOP87A full series (Bretagnon and Francou 1988), heliocentric ecliptic J2000, converted to Earth-equatorial J2000",
20
+ `JPL Horizons API 1.2 (https://ssd.jpl.nasa.gov/api/horizons.api), ${label} (${body}) about the Sun's centre (CENTER=500@10)${withoutPackage === undefined ? "" : " and about its system barycentre"}, VECTORS geometric ICRF km TDB, 6-hourly 1950 to 2046, retrieved ${PLANET_SERIES_RETRIEVED}: ${centreSource}; the system barycentre fitted as piecewise Chebyshev series within 1 km (tools/import/planet-fits.mjs). US Government work, credit NASA/JPL-Caltech Solar System Dynamics`,
13
21
  ],
14
- accuracy: `${label} position was compared with JPL Horizons (DE441) at six dates from 1969 to 2030: ${measured}. Sample maxima, not a bound for every date.`,
22
+ accuracy: measured,
15
23
  notes: "Geometric position about the Sun's centre; no light-time or aberration.",
16
24
  }),
17
- knownLimitations: ["No velocity is modelled for planets, so they have no speed readout.", ...extraLimitations],
25
+ knownLimitations: ["No velocity is modelled for planets, so they have no speed readout.", ...(withoutPackage === undefined ? [] : [withoutPackage]), PRE_1972_LIMITATION],
18
26
  };
19
27
  }
@@ -1,10 +1,27 @@
1
1
  import type { AstronomyAdapter, PlanetId } from "../astronomyAdapter.js";
2
+ import type { StateSourceBinding } from "../body.js";
3
+ import type { ChebyshevEphemeris } from "../chebyshevEphemeris.js";
2
4
  import { type IauRotationElements } from "../iauRotation.js";
3
5
  import type { Trajectory } from "../trajectory.js";
4
6
  /**
5
- * A planet in its one native centre, the Sun: VSOP87A position and IAU-rotation orientation from the adapter's time scale.
6
- * No velocity is modelled (a State carries none from this source), so a planet has no speed readout.
7
- * `offsetKm`, when given and not null at a time, is added to the series position: Pluto's own offset from its system's barycentre (the series
8
- * is the barycentre), available only once its system's fits are loaded.
7
+ * A planet in its one native centre, the Sun: the planet series position (the system barycentre, from JPL Horizons) and IAU-rotation orientation
8
+ * from the adapter's time scale. No velocity is modelled (a State carries none from this source), so a planet has no speed readout.
9
+ * `offsetKm`, when given and not null at a time, is added to the series position: the planet's own offset from its system's barycentre,
10
+ * available only once its moon system's fits are loaded.
9
11
  */
10
12
  export declare function createPlanetSunTrajectory(planet: PlanetId, rotation: IauRotationElements, adapter: AstronomyAdapter, offsetKm?: (timeUtcMs: number) => ArrayLike<number> | null): Trajectory;
13
+ /** The part of a moon system the planet binding reads: whether a set is installed, and the set. */
14
+ export interface BarycentreOffsetSource {
15
+ isLoaded(): boolean;
16
+ ephemeris(): ChebyshevEphemeris;
17
+ }
18
+ /**
19
+ * The planet's own offset from its system barycentre at `timeUtcMs`, from its moon system's centre series, or null while the system is not loaded
20
+ * or the time lies outside the loaded chunks (the planet then stays at the barycentre, which its position record says).
21
+ */
22
+ export declare function barycentreOffsetKm(system: BarycentreOffsetSource): (timeUtcMs: number) => ArrayLike<number> | null;
23
+ /**
24
+ * The one planet binding (O-063 T-290; Pluto's since O-033 T-116): the planet series gives the system barycentre, and a planet with a moon system
25
+ * adds its own offset from that barycentre once the system's fits are loaded. Mercury and Venus have no moon system: barycentre and centre agree.
26
+ */
27
+ export declare function planetBinding(planet: PlanetId, rotation: IauRotationElements, system?: BarycentreOffsetSource): StateSourceBinding;
@@ -1,10 +1,10 @@
1
1
  import { iauOrientation } from "../iauRotation.js";
2
2
  import { assertUtcUnixMs, createState, EQJ } from "../state.js";
3
3
  /**
4
- * A planet in its one native centre, the Sun: VSOP87A position and IAU-rotation orientation from the adapter's time scale.
5
- * No velocity is modelled (a State carries none from this source), so a planet has no speed readout.
6
- * `offsetKm`, when given and not null at a time, is added to the series position: Pluto's own offset from its system's barycentre (the series
7
- * is the barycentre), available only once its system's fits are loaded.
4
+ * A planet in its one native centre, the Sun: the planet series position (the system barycentre, from JPL Horizons) and IAU-rotation orientation
5
+ * from the adapter's time scale. No velocity is modelled (a State carries none from this source), so a planet has no speed readout.
6
+ * `offsetKm`, when given and not null at a time, is added to the series position: the planet's own offset from its system's barycentre,
7
+ * available only once its moon system's fits are loaded.
8
8
  */
9
9
  export function createPlanetSunTrajectory(planet, rotation, adapter, offsetKm) {
10
10
  return Object.freeze({
@@ -29,3 +29,27 @@ export function createPlanetSunTrajectory(planet, rotation, adapter, offsetKm) {
29
29
  },
30
30
  });
31
31
  }
32
+ /**
33
+ * The planet's own offset from its system barycentre at `timeUtcMs`, from its moon system's centre series, or null while the system is not loaded
34
+ * or the time lies outside the loaded chunks (the planet then stays at the barycentre, which its position record says).
35
+ */
36
+ export function barycentreOffsetKm(system) {
37
+ return (timeUtcMs) => {
38
+ if (!system.isLoaded())
39
+ return null;
40
+ try {
41
+ return system.ephemeris().centreOffsetKm(timeUtcMs);
42
+ }
43
+ catch {
44
+ return null;
45
+ }
46
+ };
47
+ }
48
+ /**
49
+ * The one planet binding (O-063 T-290; Pluto's since O-033 T-116): the planet series gives the system barycentre, and a planet with a moon system
50
+ * adds its own offset from that barycentre once the system's fits are loaded. Mercury and Venus have no moon system: barycentre and centre agree.
51
+ */
52
+ export function planetBinding(planet, rotation, system) {
53
+ const offsetKm = system === undefined ? undefined : barycentreOffsetKm(system);
54
+ return Object.freeze({ body: planet, create: (adapter) => createPlanetSunTrajectory(planet, rotation, adapter, offsetKm) });
55
+ }
@@ -1,6 +1,6 @@
1
1
  import { createProvenance } from "../provenance.js";
2
2
  import { IAU_REPORT, PLANET_VALIDATED_UTC, planetEphemeris, ROTATION_LIMITATION } from "./planetRecords.js";
3
- export const VENUS_EPHEMERIS = planetEphemeris("Venus", "at most 50 km (0.10 arcsec) from Horizons");
3
+ export const VENUS_EPHEMERIS = planetEphemeris("Venus", "299", "DE441 (Venus has no moons: its barycentre, 2, is the planet)", "Within 0.6 km of Horizons' Venus on 2 January of each year 1972 to 2044 (O-063 T-290); the fit is within 0.75 km of Horizons at independent dates 1950 to 2045.");
4
4
  /** Venus pole and prime meridian from the IAU 2015 report: degrees, pole per Julian century, W per day, from J2000 TDB. */
5
5
  export const VENUS_ROTATION = Object.freeze({
6
6
  poleRaDeg: [272.76, 0],
@@ -4,7 +4,7 @@ import type { TimeBounds } from "./trajectory.js";
4
4
  export declare function planetSeriesSpan(): TimeBounds;
5
5
  /**
6
6
  * The planet models from the stored curve fits (`data/ephemerides/planets/`, O-025 T-101): heliocentric ecliptic-J2000 positions as piecewise
7
- * Chebyshev series in TT, refitted from Orb's full VSOP87A series within 1 km (Pluto: fitted to Horizons states; tools/import/planet-fits.mjs). UTC to TT uses the table stored
7
+ * Chebyshev series in TT of each planet's system barycentre as JPL Horizons reports the planet, within 1 km (O-063 T-290; tools/import/planet-fits.mjs). UTC to TT uses the table stored
8
8
  * beside them. Dates outside the fitted span (1950 to 2045) throw rather than extrapolate. Only planetSeries.ts imports this, lazily.
9
9
  */
10
10
  export declare function createPlanetModels(): PlanetModels;
@@ -32,7 +32,7 @@ export function planetSeriesSpan() {
32
32
  }
33
33
  /**
34
34
  * The planet models from the stored curve fits (`data/ephemerides/planets/`, O-025 T-101): heliocentric ecliptic-J2000 positions as piecewise
35
- * Chebyshev series in TT, refitted from Orb's full VSOP87A series within 1 km (Pluto: fitted to Horizons states; tools/import/planet-fits.mjs). UTC to TT uses the table stored
35
+ * Chebyshev series in TT of each planet's system barycentre as JPL Horizons reports the planet, within 1 km (O-063 T-290; tools/import/planet-fits.mjs). UTC to TT uses the table stored
36
36
  * beside them. Dates outside the fitted span (1950 to 2045) throw rather than extrapolate. Only planetSeries.ts imports this, lazily.
37
37
  */
38
38
  export function createPlanetModels() {
@@ -11,7 +11,7 @@ export declare class PlanetFitsUncoveredError extends RangeError {
11
11
  export type PlanetId = "mercury" | "venus" | "mars" | "jupiter" | "saturn" | "uranus" | "neptune" | "pluto";
12
12
  export declare const PLANET_IDS: readonly PlanetId[];
13
13
  export declare function isPlanetId(id: string): id is PlanetId;
14
- /** One planet's heliocentric ecliptic-J2000 model (curve fits of VSOP87A), as the astronomy adapter reads it. */
14
+ /** One planet's heliocentric ecliptic-J2000 model (curve fits of its system barycentre from JPL Horizons), as the astronomy adapter reads it. */
15
15
  export interface PlanetModel {
16
16
  xyz(date: Date): {
17
17
  readonly x: number;
@@ -25,7 +25,7 @@ export type PlanetModels = {
25
25
  readonly [P in PlanetId]: PlanetModel;
26
26
  };
27
27
  /**
28
- * Builds the planet models, once, from the stored curve fits of the full VSOP87A series (Pluto: of JPL Horizons states) (O-025 T-101, O-033 T-114; the library's compact
28
+ * Builds the planet models, once, from the stored curve fits of JPL Horizons states (O-025 T-101, O-033 T-114, O-063 T-290; before O-063 the full VSOP87A series; the library's compact
29
29
  * default tables are off by tens of thousands of km, docs/ASTRONOMY_VALIDATION.md, and its full series were about 0.8 MB of code).
30
30
  * The fits are a separate chunk fetched only when a mounted composition contains a planet; an experience without one never
31
31
  * downloads them (I-022).
@@ -20,7 +20,7 @@ let loading;
20
20
  let models;
21
21
  let span;
22
22
  /**
23
- * Builds the planet models, once, from the stored curve fits of the full VSOP87A series (Pluto: of JPL Horizons states) (O-025 T-101, O-033 T-114; the library's compact
23
+ * Builds the planet models, once, from the stored curve fits of JPL Horizons states (O-025 T-101, O-033 T-114, O-063 T-290; before O-063 the full VSOP87A series; the library's compact
24
24
  * default tables are off by tens of thousands of km, docs/ASTRONOMY_VALIDATION.md, and its full series were about 0.8 MB of code).
25
25
  * The fits are a separate chunk fetched only when a mounted composition contains a planet; an experience without one never
26
26
  * downloads them (I-022).
@@ -30,6 +30,12 @@ interface Props {
30
30
  readonly onCameraRequest: (request: ExperienceCameraPreset["request"]) => void;
31
31
  /** Holds the camera where it is, its target fixed in the scene (a view's `stay` rule); a later camera request replaces it. */
32
32
  readonly onCameraHold?: () => void;
33
+ /** True when the host has set the camera since the last view switch: that call answers the switch, so the view's own camera rule does not replace it. */
34
+ readonly hostCameraSet?: () => boolean;
35
+ /** Filled with the shell's story seek note, so a host's time jump re-bases the panel crossing check exactly as a visitor's seek does. */
36
+ readonly storySeekNote?: {
37
+ current: ((timeUtcMs: number) => void) | null;
38
+ };
33
39
  /** `origin` is required so a new selection path must say who chose: "visitor" (a menu choice, pick, preset or marker) or "move" (time or the view moved and the selection followed). */
34
40
  readonly onSelectionChange: (objectId: string, origin: SelectionOrigin) => void;
35
41
  readonly scaleId: ScaleId;
@@ -76,6 +82,12 @@ interface Props {
76
82
  /** Called with the key of the place whose information is open, or null, so the app can mark its scene marker. */
77
83
  readonly onOpenFeatureChange?: (key: string | null) => void;
78
84
  /** Asks the shell to fly to an object a tap or click picked in the scene (focus only, no information); a new `serial` asks again. */
85
+ /** A host `setSelected` (id "" clears the selection), applied after the shell's own view-switch choices so the host's call is the last word; `onSelectRequestApplied` tells the app it has been. */
86
+ readonly selectRequest?: {
87
+ readonly id: string;
88
+ readonly serial: number;
89
+ } | null;
90
+ readonly onSelectRequestApplied?: () => void;
79
91
  readonly pickRequest?: {
80
92
  readonly id: string;
81
93
  readonly serial: number;
@@ -83,5 +95,5 @@ interface Props {
83
95
  readonly children: ReactNode;
84
96
  }
85
97
  /** Canvas-first layout shared by astronomy experiences. Scene and diagnostics stay app-owned. */
86
- export declare function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onCameraHold, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout, highlightedFamily, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, children, }: Props): import("react").JSX.Element;
98
+ export declare function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onCameraHold, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout, highlightedFamily, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }: Props): import("react").JSX.Element;
87
99
  export {};
@@ -61,6 +61,10 @@ function MoonsSheet({ planetLabel, open, onToggle, onClose, children }) {
61
61
  onClose(); }, children: children })] }));
62
62
  }
63
63
  /** The serial of a request that is asked again by sending a new one; absent request: undefined. */
64
+ /** Whether the selection has been lost and a fallback must take its place: the object is gone or not available now, unless the host cleared the selection on purpose. */
65
+ function selectionLost(selected, timeUtcMs, clearedByHost) {
66
+ return !clearedByHost && (selected === undefined || !isObjectAvailable(selected, timeUtcMs));
67
+ }
64
68
  function serialOf(request) {
65
69
  return request?.serial;
66
70
  }
@@ -92,7 +96,7 @@ function infoContent(experience, info, selectedObjectId, timeUtcMs, metricsFor)
92
96
  /** The moon families load on demand: only an experience with `moonFamilies` draws them (I-089). */
93
97
  const MoonFamilyPanel = lazy(() => import("./MoonFamilyPanel.js").then((module) => ({ default: module.MoonFamilyPanel })));
94
98
  /** Canvas-first layout shared by astronomy experiences. Scene and diagnostics stay app-owned. */
95
- export function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onCameraHold, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout = DEFAULT_PHONE_LAYOUT, highlightedFamily = null, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, children, }) {
99
+ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onCameraHold, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout = DEFAULT_PHONE_LAYOUT, highlightedFamily = null, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }) {
96
100
  const infoPanelId = `${useId()}-info-panel`;
97
101
  const [selectedObjectId, setSelectedObjectId] = useState(() => initialObjectId(experience, snapshot.timeUtcMs));
98
102
  const phone = usePhone();
@@ -113,6 +117,10 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
113
117
  const storySet = experience.storyPanels;
114
118
  const storyPanels = panelsOf(storySet);
115
119
  const story = useStoryPanels(storyPanels, storyPanelSettings ?? ownStorySettings(storySet), snapshot, onSetPlaying);
120
+ if (storySeekNote !== undefined)
121
+ storySeekNote.current = story.noteSeek;
122
+ useEffect(() => () => { if (storySeekNote !== undefined)
123
+ storySeekNote.current = null; }, [storySeekNote]);
116
124
  const openPanelId = story.openPanel?.id ?? null;
117
125
  useEffect(() => { onOpenPanelChange?.(openPanelId); }, [onOpenPanelChange, openPanelId]);
118
126
  const requestedSerial = serialOf(panelRequest);
@@ -143,12 +151,16 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
143
151
  useEffect(() => {
144
152
  onSelectionChange(selectedObjectId, "visitor");
145
153
  }, [onSelectionChange, selectedObjectId]);
154
+ /** The host cleared the selection: the fallback that picks the first available object stays off until something is selected again. */
155
+ const hostCleared = useRef(false);
146
156
  // A view switch is told from other changes of the experience by the view's id changing.
147
157
  const { viewId, takeSwitchRule } = useViewSwitch(viewCamera);
148
158
  useEffect(() => {
149
159
  const switchRule = takeSwitchRule();
160
+ if (selectedObjectId !== "")
161
+ hostCleared.current = false;
150
162
  const selected = experience.objects.find((object) => object.id === selectedObjectId);
151
- if (selected === undefined || !isObjectAvailable(selected, snapshot.timeUtcMs)) {
163
+ if (selectionLost(selected, snapshot.timeUtcMs, hostCleared.current && selectedObjectId === "")) {
152
164
  const fallbackId = firstAvailableObject(experience, snapshot.timeUtcMs)?.id ?? "";
153
165
  setSelectedObjectId(fallbackId);
154
166
  onSelectionChange(fallbackId, "move");
@@ -158,7 +170,10 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
158
170
  }
159
171
  const active = experience.cameraPresets.find((preset) => preset.id === activePresetId);
160
172
  const activeRequest = active?.request;
161
- if (activeRequest !== undefined && activeRequest.kind !== "overview") {
173
+ if (switchRule?.rule === "start" && switchRule.framing?.always === true) {
174
+ applyViewRule(switchRule); // opted in: the view's framing applies on every switch to it
175
+ }
176
+ else if (activeRequest !== undefined && activeRequest.kind !== "overview") {
162
177
  const target = experience.objects.find((object) => object.id === activeRequest.target);
163
178
  if (switchRule !== undefined && target === undefined) {
164
179
  applyViewRule(switchRule);
@@ -173,6 +188,19 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
173
188
  }
174
189
  // eslint-disable-next-line react-hooks/exhaustive-deps
175
190
  }, [activePresetId, experience, onCameraRequest, onSelectionChange, selectedObjectId, snapshot.timeUtcMs, viewId]);
191
+ // A host `setSelected`: runs after the view-switch effect above in the same commit, so it wins over that effect's fallback or view rule.
192
+ const requestedSelectSerial = serialOf(selectRequest);
193
+ useEffect(() => {
194
+ if (selectRequest === null || selectRequest === undefined)
195
+ return;
196
+ hostCleared.current = selectRequest.id === "";
197
+ setSelectedObjectId(selectRequest.id);
198
+ // As a visitor's menu choice does: the object's card opens (the camera is left alone); a clear closes it.
199
+ setInfo((now) => (selectRequest.id === "" ? (now?.kind === "object" ? null : now) : { kind: "object" }));
200
+ onSelectRequestApplied?.();
201
+ // Only a new request applies.
202
+ // eslint-disable-next-line react-hooks/exhaustive-deps
203
+ }, [requestedSelectSerial]);
176
204
  /** The view's camera rule for a followed or focused object the new view does not show: `stay` keeps the pose and stops following; otherwise the rule's framing is requested. */
177
205
  const applyViewRule = (rule) => {
178
206
  const asked = presetForViewRule(rule, experience);
@@ -184,6 +212,8 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
184
212
  onSelectionChange(target.id, "move"); // only the move-driven effect applies a view rule
185
213
  }
186
214
  setActivePresetId(preset?.id ?? null);
215
+ if (hostCameraSet?.() === true)
216
+ return; // a host camera call made since the switch answers it and wins over the rule
187
217
  if (preset !== undefined)
188
218
  onCameraRequest(preset.request);
189
219
  else
@@ -57,6 +57,10 @@ function MoonsSheet({ planetLabel, open, onToggle, onClose, children }) {
57
57
  onClose(); }, children: children })] }));
58
58
  }
59
59
  /** The serial of a request that is asked again by sending a new one; absent request: undefined. */
60
+ /** Whether the selection has been lost and a fallback must take its place: the object is gone or not available now, unless the host cleared the selection on purpose. */
61
+ function selectionLost(selected, timeUtcMs, clearedByHost) {
62
+ return !clearedByHost && (selected === undefined || !isObjectAvailable(selected, timeUtcMs));
63
+ }
60
64
  function serialOf(request) {
61
65
  return request?.serial;
62
66
  }
@@ -88,7 +92,7 @@ function infoContent(experience, info, selectedObjectId, timeUtcMs, metricsFor)
88
92
  /** The moon families load on demand: only an experience with `moonFamilies` draws them (I-089). */
89
93
  const MoonFamilyPanel = lazy(() => import("./MoonFamilyPanel.js").then((module) => ({ default: module.MoonFamilyPanel })));
90
94
  /** Canvas-first layout shared by astronomy experiences. Scene and diagnostics stay app-owned. */
91
- export function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onCameraHold, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout = DEFAULT_PHONE_LAYOUT, highlightedFamily = null, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, children, }) {
95
+ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onCameraHold, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout = DEFAULT_PHONE_LAYOUT, highlightedFamily = null, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }) {
92
96
  const infoPanelId = `${useId()}-info-panel`;
93
97
  const [selectedObjectId, setSelectedObjectId] = useState(() => initialObjectId(experience, snapshot.timeUtcMs));
94
98
  const phone = usePhone();
@@ -109,6 +113,10 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
109
113
  const storySet = experience.storyPanels;
110
114
  const storyPanels = panelsOf(storySet);
111
115
  const story = useStoryPanels(storyPanels, storyPanelSettings ?? ownStorySettings(storySet), snapshot, onSetPlaying);
116
+ if (storySeekNote !== undefined)
117
+ storySeekNote.current = story.noteSeek;
118
+ useEffect(() => () => { if (storySeekNote !== undefined)
119
+ storySeekNote.current = null; }, [storySeekNote]);
112
120
  const openPanelId = story.openPanel?.id ?? null;
113
121
  useEffect(() => { onOpenPanelChange?.(openPanelId); }, [onOpenPanelChange, openPanelId]);
114
122
  const requestedSerial = serialOf(panelRequest);
@@ -139,12 +147,16 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
139
147
  useEffect(() => {
140
148
  onSelectionChange(selectedObjectId, "visitor");
141
149
  }, [onSelectionChange, selectedObjectId]);
150
+ /** The host cleared the selection: the fallback that picks the first available object stays off until something is selected again. */
151
+ const hostCleared = useRef(false);
142
152
  // A view switch is told from other changes of the experience by the view's id changing.
143
153
  const { viewId, takeSwitchRule } = useViewSwitch(viewCamera);
144
154
  useEffect(() => {
145
155
  const switchRule = takeSwitchRule();
156
+ if (selectedObjectId !== "")
157
+ hostCleared.current = false;
146
158
  const selected = experience.objects.find((object) => object.id === selectedObjectId);
147
- if (selected === undefined || !isObjectAvailable(selected, snapshot.timeUtcMs)) {
159
+ if (selectionLost(selected, snapshot.timeUtcMs, hostCleared.current && selectedObjectId === "")) {
148
160
  const fallbackId = firstAvailableObject(experience, snapshot.timeUtcMs)?.id ?? "";
149
161
  setSelectedObjectId(fallbackId);
150
162
  onSelectionChange(fallbackId, "move");
@@ -154,7 +166,10 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
154
166
  }
155
167
  const active = experience.cameraPresets.find((preset) => preset.id === activePresetId);
156
168
  const activeRequest = active?.request;
157
- if (activeRequest !== undefined && activeRequest.kind !== "overview") {
169
+ if (switchRule?.rule === "start" && switchRule.framing?.always === true) {
170
+ applyViewRule(switchRule); // opted in: the view's framing applies on every switch to it
171
+ }
172
+ else if (activeRequest !== undefined && activeRequest.kind !== "overview") {
158
173
  const target = experience.objects.find((object) => object.id === activeRequest.target);
159
174
  if (switchRule !== undefined && target === undefined) {
160
175
  applyViewRule(switchRule);
@@ -169,6 +184,19 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
169
184
  }
170
185
  // eslint-disable-next-line react-hooks/exhaustive-deps
171
186
  }, [activePresetId, experience, onCameraRequest, onSelectionChange, selectedObjectId, snapshot.timeUtcMs, viewId]);
187
+ // A host `setSelected`: runs after the view-switch effect above in the same commit, so it wins over that effect's fallback or view rule.
188
+ const requestedSelectSerial = serialOf(selectRequest);
189
+ useEffect(() => {
190
+ if (selectRequest === null || selectRequest === undefined)
191
+ return;
192
+ hostCleared.current = selectRequest.id === "";
193
+ setSelectedObjectId(selectRequest.id);
194
+ // As a visitor's menu choice does: the object's card opens (the camera is left alone); a clear closes it.
195
+ setInfo((now) => (selectRequest.id === "" ? (now?.kind === "object" ? null : now) : { kind: "object" }));
196
+ onSelectRequestApplied?.();
197
+ // Only a new request applies.
198
+ // eslint-disable-next-line react-hooks/exhaustive-deps
199
+ }, [requestedSelectSerial]);
172
200
  /** The view's camera rule for a followed or focused object the new view does not show: `stay` keeps the pose and stops following; otherwise the rule's framing is requested. */
173
201
  const applyViewRule = (rule) => {
174
202
  const asked = presetForViewRule(rule, experience);
@@ -180,6 +208,8 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
180
208
  onSelectionChange(target.id, "move"); // only the move-driven effect applies a view rule
181
209
  }
182
210
  setActivePresetId(preset?.id ?? null);
211
+ if (hostCameraSet?.() === true)
212
+ return; // a host camera call made since the switch answers it and wins over the rule
183
213
  if (preset !== undefined)
184
214
  onCameraRequest(preset.request);
185
215
  else