astraeus 0.8.0 → 0.9.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 (144) hide show
  1. package/CHANGELOG.md +80 -0
  2. package/README.md +46 -17
  3. package/data/ephemerides/planets/planets.json +1 -1
  4. package/package.json +1 -1
  5. package/src/api/AstraeusScene.d.ts +1 -1
  6. package/src/api/AstraeusScene.js +4 -1
  7. package/src/api/AstraeusScene.node.js +4 -1
  8. package/src/api/assembleScene.d.ts +2 -0
  9. package/src/api/assembleScene.js +27 -5
  10. package/src/api/cameraRequest.d.ts +15 -0
  11. package/src/api/cameraRequest.js +89 -0
  12. package/src/api/errors.d.ts +10 -0
  13. package/src/api/index.d.ts +6 -3
  14. package/src/api/look.d.ts +49 -0
  15. package/src/api/lookInput.d.ts +1 -1
  16. package/src/api/lookInput.js +6 -1
  17. package/src/api/planCamera.d.ts +35 -7
  18. package/src/api/planCamera.js +94 -11
  19. package/src/api/planSkyFigures.d.ts +22 -0
  20. package/src/api/planSkyFigures.js +145 -0
  21. package/src/api/planStory.d.ts +2 -2
  22. package/src/api/planStory.js +14 -9
  23. package/src/api/planViews.js +1 -1
  24. package/src/api/scene.d.ts +17 -4
  25. package/src/api/scene.js +23 -5
  26. package/src/api/sceneReads.d.ts +21 -2
  27. package/src/api/skyFigureInput.d.ts +45 -0
  28. package/src/api/skyFigureInput.js +1 -0
  29. package/src/api/skyTraceInput.d.ts +33 -0
  30. package/src/api/skyTraceInput.js +45 -0
  31. package/src/api/story.d.ts +12 -3
  32. package/src/api/story.js +44 -1
  33. package/src/api/viewerCamera.d.ts +4 -3
  34. package/src/api/viewerCamera.js +10 -32
  35. package/src/api/viewerHandle.d.ts +34 -5
  36. package/src/api/viewerHandle.js +7 -0
  37. package/src/api/viewerLink.d.ts +50 -4
  38. package/src/api/viewerLink.js +33 -2
  39. package/src/api/viewerPanels.d.ts +26 -0
  40. package/src/api/viewerPanels.js +42 -0
  41. package/src/api/viewerSelection.d.ts +6 -1
  42. package/src/api/viewerSelection.js +15 -0
  43. package/src/api/views.d.ts +3 -1
  44. package/src/api/views.js +5 -1
  45. package/src/app/App.js +118 -16
  46. package/src/app/App.node.js +118 -16
  47. package/src/app/AstraeusScene.d.ts +22 -5
  48. package/src/app/AstraeusScene.js +3 -3
  49. package/src/app/CameraController.d.ts +17 -0
  50. package/src/app/CameraController.js +34 -9
  51. package/src/app/DeveloperSettings.d.ts +11 -3
  52. package/src/app/DeveloperSettings.js +13 -3
  53. package/src/app/SceneLabels.d.ts +20 -2
  54. package/src/app/SceneLabels.js +46 -6
  55. package/src/app/SkyFiguresView.d.ts +56 -0
  56. package/src/app/SkyFiguresView.js +242 -0
  57. package/src/app/StoryMarkers.d.ts +2 -2
  58. package/src/app/StoryMarkers.js +2 -2
  59. package/src/app/displaySwitches.d.ts +13 -3
  60. package/src/app/displaySwitches.js +17 -3
  61. package/src/app/experienceDefinition.d.ts +9 -3
  62. package/src/app/experienceDefinition.js +4 -2
  63. package/src/app/labelStyle.d.ts +17 -0
  64. package/src/app/labelStyle.js +13 -0
  65. package/src/app/liveLook.js +8 -0
  66. package/src/app/look.d.ts +9 -5
  67. package/src/app/look.js +11 -0
  68. package/src/app/lookOut.d.ts +32 -0
  69. package/src/app/lookOut.js +50 -0
  70. package/src/app/sceneCamera.d.ts +7 -3
  71. package/src/app/sceneCamera.js +68 -4
  72. package/src/app/sceneContentsHooks.d.ts +2 -1
  73. package/src/app/sceneContentsHooks.js +3 -2
  74. package/src/app/sceneFrame.d.ts +10 -1
  75. package/src/app/sceneFrame.js +45 -10
  76. package/src/app/sceneFraming.d.ts +7 -0
  77. package/src/app/sceneFraming.js +12 -0
  78. package/src/app/sceneHooks.d.ts +2 -0
  79. package/src/app/sceneHooks.js +4 -1
  80. package/src/app/scenePicking.d.ts +20 -0
  81. package/src/app/scenePicking.js +49 -0
  82. package/src/app/scenePointer.d.ts +3 -1
  83. package/src/app/scenePointer.js +3 -2
  84. package/src/app/skyFigures.d.ts +73 -0
  85. package/src/app/skyFigures.js +50 -0
  86. package/src/app/style.css +2 -1
  87. package/src/app/viewHiding.d.ts +2 -0
  88. package/src/app/viewHiding.js +7 -1
  89. package/src/app/viewLink.d.ts +8 -8
  90. package/src/app/viewLink.js +24 -4
  91. package/src/app/viewerPort.d.ts +32 -3
  92. package/src/app/views.d.ts +2 -0
  93. package/src/assets/sky.d.ts +13 -4
  94. package/src/assets/sky.js +33 -8
  95. package/src/assets/stars/hyg-v42-naked-eye.json +1 -1
  96. package/src/core/astronomyAdapter.d.ts +1 -1
  97. package/src/core/astronomyAdapter.js +3 -3
  98. package/src/core/bodies/index.js +13 -12
  99. package/src/core/bodies/jupiter.js +1 -1
  100. package/src/core/bodies/mars.js +1 -1
  101. package/src/core/bodies/mercury.js +1 -1
  102. package/src/core/bodies/moonSystem.js +1 -15
  103. package/src/core/bodies/outerPlanets.d.ts +2 -3
  104. package/src/core/bodies/outerPlanets.js +4 -13
  105. package/src/core/bodies/planetMoons.d.ts +0 -2
  106. package/src/core/bodies/planetMoons.js +1 -18
  107. package/src/core/bodies/planetRecords.d.ts +8 -2
  108. package/src/core/bodies/planetRecords.js +13 -5
  109. package/src/core/bodies/planetTrajectory.d.ts +21 -4
  110. package/src/core/bodies/planetTrajectory.js +28 -4
  111. package/src/core/bodies/venus.js +1 -1
  112. package/src/core/lookValues.d.ts +9 -0
  113. package/src/core/lookValues.js +24 -0
  114. package/src/core/planetModels.d.ts +1 -1
  115. package/src/core/planetModels.js +1 -1
  116. package/src/core/planetSeries.d.ts +2 -2
  117. package/src/core/planetSeries.js +1 -1
  118. package/src/core/readBytes.d.ts +1 -0
  119. package/src/core/readBytes.js +15 -0
  120. package/src/core/skyTrace.d.ts +49 -0
  121. package/src/core/skyTrace.js +39 -0
  122. package/src/core/startView.d.ts +39 -0
  123. package/src/core/startView.js +56 -0
  124. package/src/core/storyPanels.d.ts +51 -3
  125. package/src/core/storyPanels.js +52 -12
  126. package/src/shell/AstraeusShell.d.ts +27 -6
  127. package/src/shell/AstraeusShell.js +104 -18
  128. package/src/shell/AstraeusShell.node.js +104 -18
  129. package/src/shell/ObjectControls.js +11 -8
  130. package/src/shell/StoryPanelView.d.ts +12 -3
  131. package/src/shell/StoryPanelView.js +2 -2
  132. package/src/shell/experience.d.ts +24 -0
  133. package/src/shell/experience.js +4 -1
  134. package/src/shell/infoModel.js +9 -1
  135. package/src/shell/objectModel.d.ts +6 -2
  136. package/src/shell/objectModel.js +10 -1
  137. package/src/shell/phone.css +1 -1
  138. package/src/shell/storyPanels.d.ts +1 -1
  139. package/src/shell/storyPanels.js +1 -1
  140. package/src/shell/style.css +9 -1
  141. package/src/shell/topBarIcons.d.ts +1 -0
  142. package/src/shell/topBarIcons.js +1 -0
  143. package/src/shell/useStoryPanels.d.ts +9 -6
  144. package/src/shell/useStoryPanels.js +10 -6
@@ -17,3 +17,42 @@ export declare const MAX_ELEVATION_DEG = 89;
17
17
  export declare const wrapAzimuth: (deg: number) => number;
18
18
  /** Checks a view's fields, naming the offending one (`where` is its path, e.g. `look.startView`). Returns the view with the azimuth wrapped. */
19
19
  export declare function validateStartView(raw: unknown, where?: string): StartView;
20
+ /** The field of view a sky reading may carry, in degrees (a look-out camera's zoom). */
21
+ export declare const SKY_FOV_RANGE_DEG: {
22
+ readonly min: 5;
23
+ readonly max: 100;
24
+ };
25
+ /** The field of view a look-out opens at when none is given, in degrees. */
26
+ export declare const SKY_OPENING_FOV_DEG = 60;
27
+ /**
28
+ * A camera standing inside `lookOut` (a body's id) and looking out: `raDeg` and `decDeg` are where it points in J2000 equatorial degrees
29
+ * (right ascension 0 up to 360, declination within ±90), `fovDeg` the vertical field of view. Text and number checks only: no body is named here.
30
+ */
31
+ export interface SkyView {
32
+ readonly lookOut: string;
33
+ readonly raDeg: number;
34
+ readonly decDeg: number;
35
+ readonly fovDeg: number;
36
+ }
37
+ /** Either kind of camera reading: an orbit view (has `distance`) or a sky view (has `lookOut`). */
38
+ export type CameraView = StartView | SkyView;
39
+ /** True for a sky view: the one test that tells the two kinds apart. */
40
+ export declare function isSkyView(view: CameraView): view is SkyView;
41
+ /** The unit vector (J2000 equatorial axes) toward a right ascension and declination in degrees. */
42
+ export declare function eqjUnitVector(raDeg: number, decDeg: number): [number, number, number];
43
+ /** Checks a right ascension and declination, naming the offending field; returns the pair with the right ascension wrapped to 0 up to 360. */
44
+ export declare function validateSkyDirection(raDeg: unknown, decDeg: unknown, where: string): {
45
+ readonly raDeg: number;
46
+ readonly decDeg: number;
47
+ };
48
+ /** Checks a star-map position given as an object: exactly `raDeg` and `decDeg` (a half pair, an array or any other key is refused). Shared by `setCamera` and the opening `lookOut`. */
49
+ export declare function validateSkyPosition(raw: unknown, where: string): {
50
+ readonly raDeg: number;
51
+ readonly decDeg: number;
52
+ };
53
+ /** Checks a field of view in degrees against the range a look-out camera takes. */
54
+ export declare function validateSkyFov(fovDeg: unknown, where: string): number;
55
+ /** Checks a sky view's fields, naming the offending one. Returns the view with the right ascension wrapped. */
56
+ export declare function validateSkyView(raw: unknown, where?: string): SkyView;
57
+ /** Checks either kind of reading: one with `lookOut` is a sky view, anything else an orbit view. */
58
+ export declare function validateCameraView(raw: unknown, where?: string): CameraView;
@@ -26,3 +26,59 @@ export function validateStartView(raw, where = "startView") {
26
26
  throw new RangeError(`${where}.distance must be positive, got ${distance}`);
27
27
  return { focus: record.focus, azimuthDeg: wrapAzimuth(azimuthDeg), elevationDeg, distance };
28
28
  }
29
+ /** The field of view a sky reading may carry, in degrees (a look-out camera's zoom). */
30
+ export const SKY_FOV_RANGE_DEG = { min: 5, max: 100 };
31
+ /** The field of view a look-out opens at when none is given, in degrees. */
32
+ export const SKY_OPENING_FOV_DEG = 60;
33
+ /** True for a sky view: the one test that tells the two kinds apart. */
34
+ export function isSkyView(view) {
35
+ return "lookOut" in view;
36
+ }
37
+ /** The unit vector (J2000 equatorial axes) toward a right ascension and declination in degrees. */
38
+ export function eqjUnitVector(raDeg, decDeg) {
39
+ const [ra, dec] = [(raDeg * Math.PI) / 180, (decDeg * Math.PI) / 180];
40
+ return [Math.cos(dec) * Math.cos(ra), Math.cos(dec) * Math.sin(ra), Math.sin(dec)];
41
+ }
42
+ /** Checks a right ascension and declination, naming the offending field; returns the pair with the right ascension wrapped to 0 up to 360. */
43
+ export function validateSkyDirection(raDeg, decDeg, where) {
44
+ if (typeof raDeg !== "number" || !Number.isFinite(raDeg))
45
+ throw new RangeError(`${where}.raDeg must be a finite number, got ${String(raDeg)}`);
46
+ if (typeof decDeg !== "number" || !Number.isFinite(decDeg))
47
+ throw new RangeError(`${where}.decDeg must be a finite number, got ${String(decDeg)}`);
48
+ if (Math.abs(decDeg) > 90)
49
+ throw new RangeError(`${where}.decDeg must be within ±90, got ${decDeg}`);
50
+ return { raDeg: wrapAzimuth(raDeg), decDeg };
51
+ }
52
+ /** Checks a star-map position given as an object: exactly `raDeg` and `decDeg` (a half pair, an array or any other key is refused). Shared by `setCamera` and the opening `lookOut`. */
53
+ export function validateSkyPosition(raw, where) {
54
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw) || Object.keys(raw).some((key) => key !== "raDeg" && key !== "decDeg"))
55
+ throw new RangeError(`${where} must be { raDeg, decDeg }`);
56
+ const position = raw;
57
+ return validateSkyDirection(position.raDeg, position.decDeg, where);
58
+ }
59
+ /** Checks a field of view in degrees against the range a look-out camera takes. */
60
+ export function validateSkyFov(fovDeg, where) {
61
+ if (typeof fovDeg !== "number" || !(fovDeg >= SKY_FOV_RANGE_DEG.min && fovDeg <= SKY_FOV_RANGE_DEG.max)) {
62
+ throw new RangeError(`${where}.fovDeg must be a number from ${SKY_FOV_RANGE_DEG.min} to ${SKY_FOV_RANGE_DEG.max}, got ${String(fovDeg)}`);
63
+ }
64
+ return fovDeg;
65
+ }
66
+ /** Checks a sky view's fields, naming the offending one. Returns the view with the right ascension wrapped. */
67
+ export function validateSkyView(raw, where = "sky view") {
68
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw))
69
+ throw new RangeError(`${where} must be an object with lookOut, raDeg, decDeg and fovDeg`);
70
+ const record = raw;
71
+ for (const key of Object.keys(record)) {
72
+ if (!["lookOut", "raDeg", "decDeg", "fovDeg"].includes(key))
73
+ throw new RangeError(`${where}.${key} is not a sky view field`);
74
+ }
75
+ if (typeof record.lookOut !== "string" || record.lookOut === "")
76
+ throw new RangeError(`${where}.lookOut must be a non-empty id, got ${String(record.lookOut)}`);
77
+ const direction = validateSkyDirection(record.raDeg, record.decDeg, where);
78
+ return { lookOut: record.lookOut, ...direction, fovDeg: validateSkyFov(record.fovDeg, where) };
79
+ }
80
+ /** Checks either kind of reading: one with `lookOut` is a sky view, anything else an orbit view. */
81
+ export function validateCameraView(raw, where = "view") {
82
+ const isSky = typeof raw === "object" && raw !== null && "lookOut" in raw;
83
+ return isSky ? validateSkyView(raw, where) : validateStartView(raw, where);
84
+ }
@@ -1,7 +1,42 @@
1
1
  import { type Provenance } from "./provenance.js";
2
+ import type { StartView } from "./startView.js";
3
+ import type { SkyTraceAfter } from "./skyTrace.js";
2
4
  import type { TimeBounds } from "./trajectory.js";
5
+ /** A camera request a panel makes when it opens (checked): the same shapes the scene camera takes. A look-out `direction` that is absent keeps the direction already looked along (else right ascension 0, declination 0). */
6
+ export type PanelCameraRequest = {
7
+ readonly kind: "focus" | "follow";
8
+ readonly target: string;
9
+ } | {
10
+ readonly kind: "overview";
11
+ } | {
12
+ readonly kind: "hold";
13
+ } | {
14
+ readonly kind: "lookOut";
15
+ readonly body: string;
16
+ readonly direction?: readonly [number, number, number] | string;
17
+ readonly fovDeg?: number;
18
+ } | {
19
+ readonly kind: "pose";
20
+ readonly view: StartView;
21
+ };
22
+ /** What a panel does when it opens, in this order: the camera turns, its object is selected, its object's sky figure is traced. */
23
+ export interface PanelActions {
24
+ readonly camera?: PanelCameraRequest;
25
+ /** True: select the panel's `object`. */
26
+ readonly select?: true;
27
+ /** Trace the panel's `object`, a sky figure, this way. */
28
+ readonly trace?: {
29
+ readonly seconds: number;
30
+ readonly after: SkyTraceAfter;
31
+ };
32
+ }
33
+ /** The ids a camera request names: the bodies it points at, and the id a look-out turns toward (a body or a sky figure). */
34
+ export declare function cameraIdsOf(request: PanelCameraRequest): {
35
+ readonly bodies: readonly string[];
36
+ readonly toward?: string;
37
+ };
3
38
  /** One short story panel, resolved to a UTC time. */
4
- export interface StoryPanel {
39
+ export interface StoryPanel extends PanelActions {
5
40
  readonly id: string;
6
41
  readonly timeUtcMs: number;
7
42
  readonly title: string;
@@ -14,9 +49,17 @@ export interface StoryPanel {
14
49
  /** A shell object this panel is about; the scene draws a marker on it that reopens the panel. */
15
50
  readonly objectId?: string;
16
51
  }
52
+ /** A story step: a panel with no moment, shown in the order added with Back and Next. */
53
+ export type StoryStep = Omit<StoryPanel, "timeUtcMs"> & {
54
+ /** The step's place among the steps, counting from 1 in the order added. */
55
+ readonly step: number;
56
+ };
17
57
  /** The panels an experience offers, with the defaults of the two settings that govern them. */
18
58
  export interface StoryPanelSet {
59
+ /** The moment panels, sorted by time. */
19
60
  readonly panels: readonly StoryPanel[];
61
+ /** The steps, in the order added; absent or empty when there are none. */
62
+ readonly steps?: readonly StoryStep[];
20
63
  /** How long playback holds when a panel opens by itself, in seconds (0 never pauses). */
21
64
  readonly pauseSeconds: number;
22
65
  /** Whether panels open by themselves as forward playback reaches them. */
@@ -29,7 +72,8 @@ export type PanelPlayback = Pick<StoryPanelSet, "pauseSeconds" | "autoOpen">;
29
72
  export declare const DEFAULT_PANEL_PLAYBACK: PanelPlayback;
30
73
  /** A panel whose own shape is sound and whose moment is converted. What it names (an event, an anchor, an object) is left for `resolveStoryPanels`, because those may be added later. */
31
74
  export interface CheckedPanel extends Omit<StoryPanel, "timeUtcMs" | "objectId"> {
32
- readonly at: {
75
+ /** Absent: a step. */
76
+ readonly at?: {
33
77
  readonly timeUtcMs: number;
34
78
  } | {
35
79
  readonly event: string;
@@ -48,6 +92,8 @@ export interface PanelLookup {
48
92
  readonly anchors?: ReadonlyMap<string, number>;
49
93
  /** Ids a panel's `object` may name. Absent: any id is accepted. */
50
94
  readonly objectIds?: readonly string[];
95
+ /** The sky figures' ids: a panel's `object` may name one, and a look-out camera may turn toward one. Absent: none. */
96
+ readonly figureIds?: readonly string[];
51
97
  /** When given, every panel must fall inside it. */
52
98
  readonly window?: TimeBounds;
53
99
  }
@@ -59,5 +105,7 @@ export declare class StoryPanelError extends Error {
59
105
  export declare function checkStoryPanel(raw: unknown, index: number): CheckedPanel;
60
106
  /** Checks the two playback settings; a setting left out takes its default, so the result is the whole setting. */
61
107
  export declare function checkPanelPlayback(raw: unknown): PanelPlayback;
62
- /** Resolves each checked panel's time and links against the scene as built. Panels come back sorted by time. */
108
+ /** Resolves each checked panel's time and links against the scene as built. Moment panels come back sorted by time; steps (no `at`) in the order given, numbered from 1. */
63
109
  export declare function resolveStoryPanels(panels: readonly CheckedPanel[], playback: PanelPlayback, lookup: PanelLookup): StoryPanelSet;
110
+ /** The step Back or Next opens from `step`: the one `by` places along (-1 or 1), or undefined at either end. */
111
+ export declare function neighbourStep(steps: readonly StoryStep[], step: StoryStep, by: -1 | 1): StoryStep | undefined;
@@ -1,5 +1,15 @@
1
1
  import { createProvenance, PROVENANCE_SOURCE_TYPES } from "./provenance.js";
2
2
  import { timeInputMs } from "./timeInput.js";
3
+ /** The ids a camera request names: the bodies it points at, and the id a look-out turns toward (a body or a sky figure). */
4
+ export function cameraIdsOf(request) {
5
+ switch (request.kind) {
6
+ case "focus":
7
+ case "follow": return { bodies: [request.target] };
8
+ case "pose": return { bodies: [request.view.focus] };
9
+ case "lookOut": return typeof request.direction === "string" ? { bodies: [request.body], toward: request.direction } : { bodies: [request.body] };
10
+ default: return { bodies: [] };
11
+ }
12
+ }
3
13
  export const DEFAULT_PANEL_PAUSE_SECONDS = 6;
4
14
  export const MAX_PANEL_PAUSE_SECONDS = 20;
5
15
  export const DEFAULT_PANEL_PLAYBACK = Object.freeze({ pauseSeconds: DEFAULT_PANEL_PAUSE_SECONDS, autoOpen: true });
@@ -23,8 +33,10 @@ function lines(panel, field, value) {
23
33
  return list.map((line, index) => text(panel, `${field}[${index}]`, line));
24
34
  }
25
35
  function atOf(panel, at) {
36
+ if (at === undefined)
37
+ return undefined;
26
38
  if (!isRecord(at))
27
- throw new StoryPanelError(panel, "at", "must name a time: { time }, { event } or { anchor }");
39
+ throw new StoryPanelError(panel, "at", "must name a time ({ time }, { event } or { anchor }), or be left out for a step");
28
40
  const keys = ["time", "event", "anchor"].filter((key) => at[key] !== undefined);
29
41
  if (keys.length !== 1)
30
42
  throw new StoryPanelError(panel, "at", "must give exactly one of time, event or anchor");
@@ -56,9 +68,10 @@ export function checkStoryPanel(raw, index) {
56
68
  throw new StoryPanelError(`#${index + 1}`, "entry", "must be an object");
57
69
  const id = text(`#${index + 1}`, "id", raw.id);
58
70
  const object = raw.object === undefined ? undefined : text(id, "object", raw.object);
71
+ const at = atOf(id, raw.at);
59
72
  return {
60
73
  id,
61
- at: atOf(id, raw.at),
74
+ ...(at === undefined ? {} : { at }),
62
75
  title: text(id, "title", raw.title),
63
76
  body: lines(id, "body", raw.body),
64
77
  details: raw.details === undefined ? [] : lines(id, "details", raw.details),
@@ -79,7 +92,7 @@ export function checkPanelPlayback(raw) {
79
92
  throw new StoryPanelError("settings", "autoOpen", "must be true or false");
80
93
  return { pauseSeconds, autoOpen };
81
94
  }
82
- function timeOf({ id, at }, lookup) {
95
+ function timeOf(id, at, lookup) {
83
96
  if ("timeUtcMs" in at)
84
97
  return at.timeUtcMs;
85
98
  if ("event" in at) {
@@ -93,19 +106,46 @@ function timeOf({ id, at }, lookup) {
93
106
  throw new StoryPanelError(id, "at.anchor", `names "${at.anchor}", which the experience's anchors lack`);
94
107
  return anchor;
95
108
  }
109
+ function checkLinks({ id, object, camera, trace }, lookup) {
110
+ const figures = lookup.figureIds ?? [];
111
+ if (object !== undefined && lookup.objectIds !== undefined && !lookup.objectIds.includes(object) && !figures.includes(object)) {
112
+ throw new StoryPanelError(id, "object", `names "${object}", which the experience lacks`);
113
+ }
114
+ if (trace !== undefined && (object === undefined || !figures.includes(object))) {
115
+ throw new StoryPanelError(id, "trace", `needs an object that names a sky figure${object === undefined ? "" : `; "${object}" is not one`}`);
116
+ }
117
+ if (camera === undefined || lookup.objectIds === undefined)
118
+ return;
119
+ const { bodies, toward } = cameraIdsOf(camera);
120
+ for (const body of bodies)
121
+ if (!lookup.objectIds.includes(body))
122
+ throw new StoryPanelError(id, "camera", `names "${body}", which is not an object the experience shows`);
123
+ if (toward !== undefined && !lookup.objectIds.includes(toward) && !figures.includes(toward))
124
+ throw new StoryPanelError(id, "camera", `turns toward "${toward}", which is neither an object nor a sky figure the experience has`);
125
+ }
126
+ /** The actions a panel carries, in the order they apply. */
127
+ const actionsOf = ({ camera, select, trace }) => ({ ...(camera === undefined ? {} : { camera }), ...(select === undefined ? {} : { select }), ...(trace === undefined ? {} : { trace }) });
96
128
  function resolvePanel(panel, lookup) {
97
- const { id, title, body, details, provenance, object } = panel;
98
- const timeUtcMs = timeOf(panel, lookup);
129
+ const { id, at, title, body, details, provenance, object } = panel;
130
+ const timeUtcMs = timeOf(id, at, lookup);
99
131
  if (lookup.window !== undefined && (timeUtcMs < lookup.window.startUtcMs || timeUtcMs > lookup.window.endUtcMs)) {
100
132
  throw new StoryPanelError(id, "at", "falls outside the timeline window");
101
133
  }
102
- if (object !== undefined && lookup.objectIds !== undefined && !lookup.objectIds.includes(object)) {
103
- throw new StoryPanelError(id, "object", `names "${object}", which the experience lacks`);
104
- }
105
- return { id, timeUtcMs, title, body, details, provenance, ...(object === undefined ? {} : { objectId: object }) };
134
+ checkLinks(panel, lookup);
135
+ return { id, timeUtcMs, title, body, details, provenance, ...(object === undefined ? {} : { objectId: object }), ...actionsOf(panel) };
106
136
  }
107
- /** Resolves each checked panel's time and links against the scene as built. Panels come back sorted by time. */
137
+ function resolveStep(panel, lookup, step) {
138
+ const { id, title, body, details, provenance, object } = panel;
139
+ checkLinks(panel, lookup);
140
+ return { id, step, title, body, details, provenance, ...(object === undefined ? {} : { objectId: object }), ...actionsOf(panel) };
141
+ }
142
+ /** Resolves each checked panel's time and links against the scene as built. Moment panels come back sorted by time; steps (no `at`) in the order given, numbered from 1. */
108
143
  export function resolveStoryPanels(panels, playback, lookup) {
109
- const resolved = panels.map((panel) => resolvePanel(panel, lookup));
110
- return { panels: resolved.sort((a, b) => a.timeUtcMs - b.timeUtcMs), ...playback };
144
+ const moments = panels.flatMap((panel) => (panel.at === undefined ? [] : [resolvePanel({ ...panel, at: panel.at }, lookup)]));
145
+ const steps = panels.filter((panel) => panel.at === undefined).map((panel, index) => resolveStep(panel, lookup, index + 1));
146
+ return { panels: moments.sort((a, b) => a.timeUtcMs - b.timeUtcMs), ...(steps.length === 0 ? {} : { steps }), ...playback };
147
+ }
148
+ /** The step Back or Next opens from `step`: the one `by` places along (-1 or 1), or undefined at either end. */
149
+ export function neighbourStep(steps, step, by) {
150
+ return steps.find((candidate) => candidate.step === step.step + by);
111
151
  }
@@ -1,8 +1,8 @@
1
1
  import { type ReactNode } from "react";
2
2
  import type { ClockSnapshot } from "../core/clock.js";
3
- import { type StoryPanelSettings } from "./useStoryPanels.js";
3
+ import { type PanelCause, type StoryPanelSettings } from "./useStoryPanels.js";
4
4
  import type { TimelineGlowLook } from "./timelineGlow.js";
5
- import type { ExperienceCameraPreset, ExperienceConfig } from "./experience.js";
5
+ import { type ExperienceCameraPreset, type ExperienceConfig } from "./experience.js";
6
6
  import type { Metric } from "./metrics.js";
7
7
  import { type PhoneLayoutSettings } from "./phoneLayout.js";
8
8
  import type { DisplaySwitchItem, ViewChoice } from "./DisplaySwitches.js";
@@ -28,8 +28,16 @@ interface Props {
28
28
  readonly paceAuto?: boolean | undefined;
29
29
  readonly onSeek: (timeUtcMs: number) => void;
30
30
  readonly onCameraRequest: (request: ExperienceCameraPreset["request"]) => void;
31
+ /** Turns the camera toward a sky figure, only while it looks out (an event naming a figure: Go to); the app decides, so an orbiting camera is left alone. */
32
+ readonly onTurnToFigure?: (id: string) => void;
31
33
  /** Holds the camera where it is, its target fixed in the scene (a view's `stay` rule); a later camera request replaces it. */
32
34
  readonly onCameraHold?: () => void;
35
+ /** 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. */
36
+ readonly hostCameraSet?: () => boolean;
37
+ /** 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. */
38
+ readonly storySeekNote?: {
39
+ current: ((timeUtcMs: number) => void) | null;
40
+ };
33
41
  /** `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
42
  readonly onSelectionChange: (objectId: string, origin: SelectionOrigin) => void;
35
43
  readonly scaleId: ScaleId;
@@ -56,6 +64,11 @@ interface Props {
56
64
  readonly timelineGlow?: TimelineGlowLook;
57
65
  /** The phone layout's live numbers (drawer heights, animation, swipe distance); absent: the defaults. */
58
66
  readonly phoneLayout?: PhoneLayoutSettings;
67
+ /** The font and size of every label (the look `labels`), carried to them as CSS variables on the root; absent: the stylesheet's own. */
68
+ readonly labelStyle?: {
69
+ readonly fontFamily: string;
70
+ readonly sizePx: number;
71
+ };
59
72
  /** The family of moons lit up in the scene now (the moon panel's choice), or null; the app draws it. */
60
73
  readonly highlightedFamily?: string | null;
61
74
  readonly onHighlightFamily?: (familyId: string | null) => void;
@@ -64,10 +77,11 @@ interface Props {
64
77
  /** Asks the shell to open a panel (a scene marker was pressed); a new `serial` asks again. */
65
78
  readonly panelRequest?: {
66
79
  readonly id: string;
67
- readonly serial: number;
80
+ readonly serial: number; /** True: the host's `setPanel` (id "" closes the open panel). */
81
+ readonly host?: boolean;
68
82
  } | null;
69
- /** Called when the open panel changes, so the app can mark its scene marker. */
70
- readonly onOpenPanelChange?: (panelId: string | null) => void;
83
+ /** Called when the open panel changes, with who changed it, so the app can mark its scene marker and tell the host. */
84
+ readonly onOpenPanelChange?: (panelId: string | null, cause: PanelCause) => void;
71
85
  /** Asks the shell to open a tagged place's information (a place marker was pressed); a new `serial` asks again. */
72
86
  readonly featureRequest?: {
73
87
  readonly key: string;
@@ -76,6 +90,13 @@ interface Props {
76
90
  /** Called with the key of the place whose information is open, or null, so the app can mark its scene marker. */
77
91
  readonly onOpenFeatureChange?: (key: string | null) => void;
78
92
  /** 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. */
93
+ /** 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. */
94
+ readonly selectRequest?: {
95
+ readonly id: string;
96
+ readonly serial: number;
97
+ readonly quiet?: boolean;
98
+ } | null;
99
+ readonly onSelectRequestApplied?: () => void;
79
100
  readonly pickRequest?: {
80
101
  readonly id: string;
81
102
  readonly serial: number;
@@ -83,5 +104,5 @@ interface Props {
83
104
  readonly children: ReactNode;
84
105
  }
85
106
  /** 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;
107
+ export declare function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onTurnToFigure, onCameraHold, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout, labelStyle, highlightedFamily, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }: Props): import("react").JSX.Element;
87
108
  export {};
@@ -3,16 +3,19 @@ import { lazy, Suspense, useEffect, useId, useRef, useState } from "react";
3
3
  import { StoryPanelView } from "./StoryPanelView.js";
4
4
  import { useDrawers } from "./useDrawers.js";
5
5
  import { useStoryPanels } from "./useStoryPanels.js";
6
+ import { neighbourStep } from "./storyPanels.js";
6
7
  import { TimelineBar } from "./TimelineBar.js";
8
+ import { requestObjectId } from "./experience.js";
7
9
  import { InfoPanel } from "./InfoPanel.js";
8
10
  import { infoView } from "./infoModel.js";
9
11
  import { PanelLoadBoundary } from "../app/PanelLoadBoundary.js";
10
12
  import { ControlsDrawer } from "./ControlsDrawer.js";
11
13
  import { isEmbedded } from "./embedded.js";
14
+ import { labelStyleVars } from "../app/labelStyle.js";
12
15
  import { DEFAULT_PHONE_LAYOUT, phoneLayoutStyle, pickOpensInfo, usePhone } from "./phoneLayout.js";
13
16
  import { presetForViewRule } from "./viewCamera.js";
14
17
  import { DeveloperToggle, TopBar } from "./TopBar.js";
15
- import { availableObjectById, findCameraPreset, firstAvailableObject, focusPresetFor, isObjectAvailable } from "./objectModel.js";
18
+ import { availableObjectById, findCameraPreset, firstAvailableObject, focusPresetFor, isObjectAvailable, skyFigureById } from "./objectModel.js";
16
19
  import "./controls.css";
17
20
  import "./style.css";
18
21
  import "./phone.css";
@@ -35,8 +38,9 @@ function useTimelineSpace(root, phone) {
35
38
  /** The object selected when the shell opens: the first one available at the clock time, else the first listed. */
36
39
  export function initialObjectId(experience, timeUtcMs) {
37
40
  const start = experience.cameraPresets.find((preset) => preset.id === experience.startCameraPresetId)?.request;
38
- if (start !== undefined && start.kind !== "overview" && experience.objects.some((object) => object.id === start.target))
39
- return start.target;
41
+ const startId = start === undefined ? undefined : requestObjectId(start);
42
+ if (startId !== undefined && experience.objects.some((object) => object.id === startId))
43
+ return startId;
40
44
  return firstAvailableObject(experience, timeUtcMs)?.id ?? experience.objects[0]?.id ?? "";
41
45
  }
42
46
  /** The story-panel settings the experience carries itself, used when the app gives none live. */
@@ -61,6 +65,11 @@ function MoonsSheet({ planetLabel, open, onToggle, onClose, children }) {
61
65
  onClose(); }, children: children })] }));
62
66
  }
63
67
  /** The serial of a request that is asked again by sending a new one; absent request: undefined. */
68
+ /** 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. */
69
+ function selectionLost(selected, timeUtcMs, clearedByHost, isFigure) {
70
+ // A selected sky figure is never lost: it has no availability and no view hides it.
71
+ return !clearedByHost && !isFigure && (selected === undefined || !isObjectAvailable(selected, timeUtcMs));
72
+ }
64
73
  function serialOf(request) {
65
74
  return request?.serial;
66
75
  }
@@ -78,21 +87,44 @@ function useViewSwitch(viewCamera) {
78
87
  function panelsOf(storySet) {
79
88
  return storySet?.panels ?? [];
80
89
  }
90
+ /** Back and Next for the open panel when it is a step: each is absent where there is no neighbour. */
91
+ function stepNavOf(panel, steps, open) {
92
+ if (panel === null || !("step" in panel))
93
+ return undefined;
94
+ const to = (by) => {
95
+ const neighbour = neighbourStep(steps, panel, by);
96
+ return neighbour === undefined ? undefined : () => open(neighbour.id);
97
+ };
98
+ return { number: panel.step, count: steps.length, onBack: to(-1), onNext: to(1) };
99
+ }
100
+ /** A request to open a panel (a marker press or the host's `setPanel`; id "" closes the open one), told with who made it. */
101
+ function applyPanelRequest(story, request) {
102
+ if (request === null || request === undefined)
103
+ return;
104
+ const by = request.host === true ? "host" : "visitor";
105
+ if (request.id === "")
106
+ story.close(by);
107
+ else
108
+ story.open(request.id, by);
109
+ }
110
+ function stepsOf(storySet) {
111
+ return storySet?.steps ?? [];
112
+ }
81
113
  function objectLabelOr(experience, objectId, fallback) {
82
- return experience.objects.find((object) => object.id === objectId)?.label ?? fallback;
114
+ return experience.objects.find((object) => object.id === objectId)?.label ?? skyFigureById(experience, objectId)?.label ?? fallback;
83
115
  }
84
116
  /** The information panel's content and, for an object, its live measurements. */
85
117
  function infoContent(experience, info, selectedObjectId, timeUtcMs, metricsFor) {
86
118
  const view = info === null
87
119
  ? null
88
120
  : infoView(experience, info.kind === "object" ? { kind: "object", id: selectedObjectId } : info, timeUtcMs);
89
- const metrics = view?.target.kind === "object" && metricsFor !== undefined ? metricsFor(view.target.id, timeUtcMs) : [];
121
+ const metrics = view?.target.kind === "object" && metricsFor !== undefined && skyFigureById(experience, view.target.id) === undefined ? metricsFor(view.target.id, timeUtcMs) : [];
90
122
  return { view, metrics };
91
123
  }
92
124
  /** The moon families load on demand: only an experience with `moonFamilies` draws them (I-089). */
93
125
  const MoonFamilyPanel = lazy(() => import("./MoonFamilyPanel.js").then((module) => ({ default: module.MoonFamilyPanel })));
94
126
  /** 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, }) {
127
+ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onTurnToFigure, onCameraHold, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout = DEFAULT_PHONE_LAYOUT, labelStyle, highlightedFamily = null, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }) {
96
128
  const infoPanelId = `${useId()}-info-panel`;
97
129
  const [selectedObjectId, setSelectedObjectId] = useState(() => initialObjectId(experience, snapshot.timeUtcMs));
98
130
  const phone = usePhone();
@@ -112,13 +144,23 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
112
144
  const [info, setInfo] = useState(null);
113
145
  const storySet = experience.storyPanels;
114
146
  const storyPanels = panelsOf(storySet);
115
- const story = useStoryPanels(storyPanels, storyPanelSettings ?? ownStorySettings(storySet), snapshot, onSetPlaying);
147
+ const storySteps = stepsOf(storySet);
148
+ const story = useStoryPanels(storyPanels, storySteps, storyPanelSettings ?? ownStorySettings(storySet), snapshot, onSetPlaying);
149
+ if (storySeekNote !== undefined)
150
+ storySeekNote.current = story.noteSeek;
151
+ useEffect(() => () => { if (storySeekNote !== undefined)
152
+ storySeekNote.current = null; }, [storySeekNote]);
116
153
  const openPanelId = story.openPanel?.id ?? null;
117
- useEffect(() => { onOpenPanelChange?.(openPanelId); }, [onOpenPanelChange, openPanelId]);
154
+ const storyCause = story.cause;
155
+ // Only a change of the open panel is reported; the cause read then is the one that change came with.
156
+ const lastCause = useRef(storyCause);
157
+ lastCause.current = storyCause;
158
+ useEffect(() => { onOpenPanelChange?.(openPanelId, lastCause.current); }, [onOpenPanelChange, openPanelId]);
159
+ const closePanel = () => story.close();
160
+ const stepNav = stepNavOf(story.openPanel, storySteps, story.open);
118
161
  const requestedSerial = serialOf(panelRequest);
119
162
  useEffect(() => {
120
- if (panelRequest !== null && panelRequest !== undefined)
121
- story.open(panelRequest.id);
163
+ applyPanelRequest(story, panelRequest);
122
164
  // Only a new request opens a panel; the open function is stable.
123
165
  // eslint-disable-next-line react-hooks/exhaustive-deps
124
166
  }, [requestedSerial]);
@@ -143,12 +185,16 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
143
185
  useEffect(() => {
144
186
  onSelectionChange(selectedObjectId, "visitor");
145
187
  }, [onSelectionChange, selectedObjectId]);
188
+ /** The host cleared the selection: the fallback that picks the first available object stays off until something is selected again. */
189
+ const hostCleared = useRef(false);
146
190
  // A view switch is told from other changes of the experience by the view's id changing.
147
191
  const { viewId, takeSwitchRule } = useViewSwitch(viewCamera);
148
192
  useEffect(() => {
149
193
  const switchRule = takeSwitchRule();
194
+ if (selectedObjectId !== "")
195
+ hostCleared.current = false;
150
196
  const selected = experience.objects.find((object) => object.id === selectedObjectId);
151
- if (selected === undefined || !isObjectAvailable(selected, snapshot.timeUtcMs)) {
197
+ if (selectionLost(selected, snapshot.timeUtcMs, hostCleared.current && selectedObjectId === "", skyFigureById(experience, selectedObjectId) !== undefined)) {
152
198
  const fallbackId = firstAvailableObject(experience, snapshot.timeUtcMs)?.id ?? "";
153
199
  setSelectedObjectId(fallbackId);
154
200
  onSelectionChange(fallbackId, "move");
@@ -158,8 +204,11 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
158
204
  }
159
205
  const active = experience.cameraPresets.find((preset) => preset.id === activePresetId);
160
206
  const activeRequest = active?.request;
161
- if (activeRequest !== undefined && activeRequest.kind !== "overview") {
162
- const target = experience.objects.find((object) => object.id === activeRequest.target);
207
+ if (switchRule?.rule === "start" && switchRule.framing?.always === true) {
208
+ applyViewRule(switchRule); // opted in: the view's framing applies on every switch to it
209
+ }
210
+ else if (activeRequest !== undefined && activeRequest.kind !== "overview") {
211
+ const target = experience.objects.find((object) => object.id === requestObjectId(activeRequest));
163
212
  if (switchRule !== undefined && target === undefined) {
164
213
  applyViewRule(switchRule);
165
214
  }
@@ -173,10 +222,25 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
173
222
  }
174
223
  // eslint-disable-next-line react-hooks/exhaustive-deps
175
224
  }, [activePresetId, experience, onCameraRequest, onSelectionChange, selectedObjectId, snapshot.timeUtcMs, viewId]);
225
+ // 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.
226
+ const requestedSelectSerial = serialOf(selectRequest);
227
+ useEffect(() => {
228
+ if (selectRequest === null || selectRequest === undefined)
229
+ return;
230
+ hostCleared.current = selectRequest.id === "";
231
+ setSelectedObjectId(selectRequest.id);
232
+ // As a visitor's menu choice does: the object's card opens (the camera is left alone); a clear closes it.
233
+ // A story panel's select (`quiet`) follows the visitor-tap rule: on a phone it selects without opening the card, which would cover the panel's Back and Next.
234
+ const opens = selectRequest.quiet === true ? pickOpensInfo(phone) : true;
235
+ setInfo((now) => (selectRequest.id === "" ? (now?.kind === "object" ? null : now) : opens ? { kind: "object" } : now));
236
+ onSelectRequestApplied?.();
237
+ // Only a new request applies.
238
+ // eslint-disable-next-line react-hooks/exhaustive-deps
239
+ }, [requestedSelectSerial]);
176
240
  /** 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
241
  const applyViewRule = (rule) => {
178
242
  const asked = presetForViewRule(rule, experience);
179
- const target = asked === undefined || asked.request.kind === "overview" ? undefined : availableObjectById(experience, asked.request.target, snapshot.timeUtcMs);
243
+ const target = asked === undefined || asked.request.kind === "overview" ? undefined : availableObjectById(experience, requestObjectId(asked.request) ?? "", snapshot.timeUtcMs);
180
244
  // A framing whose object is not available now falls back to the overview, like any other lost target.
181
245
  const preset = asked !== undefined && asked.request.kind !== "overview" && target === undefined ? findCameraPreset(experience, "overview") : asked;
182
246
  if (target !== undefined) {
@@ -184,6 +248,8 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
184
248
  onSelectionChange(target.id, "move"); // only the move-driven effect applies a view rule
185
249
  }
186
250
  setActivePresetId(preset?.id ?? null);
251
+ if (hostCameraSet?.() === true)
252
+ return; // a host camera call made since the switch answers it and wins over the rule
187
253
  if (preset !== undefined)
188
254
  onCameraRequest(preset.request);
189
255
  else
@@ -201,7 +267,10 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
201
267
  /** An object tapped or clicked in the scene: the picker's focus; on a wide screen it also opens the card, on a phone it does not (T-138). A tapped body-set member that is no listed object just flies there. */
202
268
  const pickObject = (id) => {
203
269
  const object = availableObjectById(experience, id, snapshot.timeUtcMs);
204
- if (object !== undefined) {
270
+ if (skyFigureById(experience, id) !== undefined) {
271
+ selectFigure(id, pickOpensInfo(phone));
272
+ }
273
+ else if (object !== undefined) {
205
274
  activatePreset(focusPresetFor(experience, object));
206
275
  if (pickOpensInfo(phone))
207
276
  setInfo({ kind: "object" });
@@ -216,7 +285,18 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
216
285
  // Only a new request flies; the handler reads the current time and experience.
217
286
  // eslint-disable-next-line react-hooks/exhaustive-deps
218
287
  }, [requestedPickSerial]);
288
+ /** A sky figure chosen in the object menu or tapped in the scene: it becomes the selection (the one selection path) and its card opens when `open`; the camera is left alone. */
289
+ const selectFigure = (id, open) => {
290
+ setSelectedObjectId(id);
291
+ onSelectionChange(id, "visitor");
292
+ if (open)
293
+ setInfo({ kind: "object" });
294
+ };
219
295
  const selectObject = (id) => {
296
+ if (skyFigureById(experience, id) !== undefined) {
297
+ selectFigure(id, true);
298
+ return;
299
+ }
220
300
  const object = availableObjectById(experience, id, snapshot.timeUtcMs);
221
301
  if (object === undefined)
222
302
  return;
@@ -240,8 +320,9 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
240
320
  }
241
321
  };
242
322
  const activatePreset = (preset, atUtcMs = snapshot.timeUtcMs) => {
243
- if (preset.request.kind !== "overview") {
244
- const target = availableObjectById(experience, preset.request.target, atUtcMs);
323
+ const objectId = requestObjectId(preset.request);
324
+ if (objectId !== undefined) {
325
+ const target = availableObjectById(experience, objectId, atUtcMs);
245
326
  if (target === undefined)
246
327
  return;
247
328
  setSelectedObjectId(target.id);
@@ -256,6 +337,11 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
256
337
  const object = event.object === undefined ? undefined : availableObjectById(experience, event.object, event.timeUtcMs);
257
338
  if (object !== undefined)
258
339
  activatePreset(focusPresetFor(experience, object), event.timeUtcMs);
340
+ // A sky figure is selected (its card stays as it is) and turned toward only while the camera looks out.
341
+ else if (event.object !== undefined && skyFigureById(experience, event.object) !== undefined) {
342
+ selectFigure(event.object, false);
343
+ onTurnToFigure?.(event.object);
344
+ }
259
345
  if (info?.kind === "event")
260
346
  setInfo({ kind: "event", id: event.id });
261
347
  };
@@ -276,5 +362,5 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
276
362
  const selectedLabel = objectLabelOr(experience, selectedObjectId, "Controls");
277
363
  const topBar = (_jsx(TopBar, { experience: experience, timeUtcMs: snapshot.timeUtcMs, selectedObjectId: selectedObjectId, activePresetId: activePresetId, onSelectObject: selectObject, onCameraPreset: activatePreset, infoOpen: info?.kind === "object", onToggleInfo: () => setInfo(info?.kind === "object" ? null : { kind: "object" }), infoPanelId: infoPanelId, scaleId: scaleId, onScaleChange: onScaleChange, scaleChoices: scaleChoices, switcher: switcher, displaySwitches: displaySwitches, viewChoice: viewChoice }));
278
364
  const moonPanel = experience.moonFamilies === undefined ? null : (_jsx(PanelLoadBoundary, { message: "The moon list could not load. Reload the page to try again.", children: _jsx(Suspense, { fallback: null, children: _jsx(MoonFamilyPanel, { list: experience.moonFamilies, highlightedFamily: highlightedFamily, onHighlight: (id) => onHighlightFamily?.(id), onSelectMoon: chooseMoon }) }) }));
279
- return (_jsxs("main", { className: "astraeus-shell", ref: root, "data-phone": phone, "data-timeline-hidden": experience.hideTimeline === true, "data-embedded": embedded, style: phoneLayoutStyle(phoneLayout), children: [_jsx("div", { className: "shell-canvas", children: children }), phone && _jsxs(ControlsDrawer, { label: selectedLabel, open: controlsOpen, onOpenChange: openControls, swipeThresholdPx: phoneLayout.swipeThresholdPx, children: [topBar, moonPanel] }), _jsxs("div", { className: "shell-top", children: [!phone && topBar, !phone && moonPanel !== null && _jsx(MoonsSheet, { planetLabel: experience.moonFamilies?.planetLabel, open: moonsOpen, onToggle: toggleMoons, onClose: () => setMoonsOpen(false), children: moonPanel }), view !== null && _jsx(InfoPanel, { view: view, metrics: metrics, onClose: () => setInfo(null), id: infoPanelId })] }), story.openPanel !== null && (_jsx(StoryPanelView, { panel: story.openPanel, holding: story.holding, onClose: story.close, onContinue: story.continuePlayback })), _jsx(DeveloperDrawer, { developerMode: developerMode, onDeveloperModeChange: onDeveloperModeChange, children: developerTools }), _jsx(ShellTimeline, { hidden: experience.hideTimeline === true, experience: experience, snapshot: snapshot, onTogglePlayback: onTogglePlayback, onRateChange: onRateChange, paceAuto: paceAuto, onSeek: seek, panels: storyPanels, openPanelId: openPanelId, onPanelOpen: openPanelFromTimeline, onEventSeek: seekToEvent, onEventInfo: (event) => setInfo({ kind: "event", id: event.id }), onWindowSeek: seekToWindow, onWindowInfo: (window) => setInfo({ kind: "window", id: window.id }), glowLook: timelineGlow, infoPanelId: infoPanelId, drawer: phone ? { open: timelineOpen, onOpenChange: openTimeline, swipeThresholdPx: phoneLayout.swipeThresholdPx } : undefined })] }));
365
+ return (_jsxs("main", { className: "astraeus-shell", ref: root, "data-phone": phone, "data-timeline-hidden": experience.hideTimeline === true, "data-embedded": embedded, style: { ...phoneLayoutStyle(phoneLayout), ...labelStyleVars(labelStyle) }, children: [_jsx("div", { className: "shell-canvas", children: children }), phone && _jsxs(ControlsDrawer, { label: selectedLabel, open: controlsOpen, onOpenChange: openControls, swipeThresholdPx: phoneLayout.swipeThresholdPx, children: [topBar, moonPanel] }), _jsxs("div", { className: "shell-top", children: [!phone && topBar, !phone && moonPanel !== null && _jsx(MoonsSheet, { planetLabel: experience.moonFamilies?.planetLabel, open: moonsOpen, onToggle: toggleMoons, onClose: () => setMoonsOpen(false), children: moonPanel }), view !== null && _jsx(InfoPanel, { view: view, metrics: metrics, onClose: () => setInfo(null), id: infoPanelId })] }), story.openPanel !== null && (_jsx(StoryPanelView, { panel: story.openPanel, holding: story.holding, onClose: closePanel, onContinue: story.continuePlayback, step: stepNav })), _jsx(DeveloperDrawer, { developerMode: developerMode, onDeveloperModeChange: onDeveloperModeChange, children: developerTools }), _jsx(ShellTimeline, { hidden: experience.hideTimeline === true, experience: experience, snapshot: snapshot, onTogglePlayback: onTogglePlayback, onRateChange: onRateChange, paceAuto: paceAuto, onSeek: seek, panels: storyPanels, openPanelId: openPanelId, onPanelOpen: openPanelFromTimeline, onEventSeek: seekToEvent, onEventInfo: (event) => setInfo({ kind: "event", id: event.id }), onWindowSeek: seekToWindow, onWindowInfo: (window) => setInfo({ kind: "window", id: window.id }), glowLook: timelineGlow, infoPanelId: infoPanelId, drawer: phone ? { open: timelineOpen, onOpenChange: openTimeline, swipeThresholdPx: phoneLayout.swipeThresholdPx } : undefined })] }));
280
366
  }