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
@@ -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.node.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.node.js";
15
- import { availableObjectById, findCameraPreset, firstAvailableObject, focusPresetFor, isObjectAvailable } from "./objectModel.js";
18
+ import { availableObjectById, findCameraPreset, firstAvailableObject, focusPresetFor, isObjectAvailable, skyFigureById } from "./objectModel.js";
16
19
  /** Keeps `--timeline-space` at the distance from the screen's bottom to the top of the timeline bar, so a phone sheet can sit above it. */
17
20
  function useTimelineSpace(root, phone) {
18
21
  useEffect(() => {
@@ -31,8 +34,9 @@ function useTimelineSpace(root, phone) {
31
34
  /** The object selected when the shell opens: the first one available at the clock time, else the first listed. */
32
35
  export function initialObjectId(experience, timeUtcMs) {
33
36
  const start = experience.cameraPresets.find((preset) => preset.id === experience.startCameraPresetId)?.request;
34
- if (start !== undefined && start.kind !== "overview" && experience.objects.some((object) => object.id === start.target))
35
- return start.target;
37
+ const startId = start === undefined ? undefined : requestObjectId(start);
38
+ if (startId !== undefined && experience.objects.some((object) => object.id === startId))
39
+ return startId;
36
40
  return firstAvailableObject(experience, timeUtcMs)?.id ?? experience.objects[0]?.id ?? "";
37
41
  }
38
42
  /** The story-panel settings the experience carries itself, used when the app gives none live. */
@@ -57,6 +61,11 @@ function MoonsSheet({ planetLabel, open, onToggle, onClose, children }) {
57
61
  onClose(); }, children: children })] }));
58
62
  }
59
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, isFigure) {
66
+ // A selected sky figure is never lost: it has no availability and no view hides it.
67
+ return !clearedByHost && !isFigure && (selected === undefined || !isObjectAvailable(selected, timeUtcMs));
68
+ }
60
69
  function serialOf(request) {
61
70
  return request?.serial;
62
71
  }
@@ -74,21 +83,44 @@ function useViewSwitch(viewCamera) {
74
83
  function panelsOf(storySet) {
75
84
  return storySet?.panels ?? [];
76
85
  }
86
+ /** Back and Next for the open panel when it is a step: each is absent where there is no neighbour. */
87
+ function stepNavOf(panel, steps, open) {
88
+ if (panel === null || !("step" in panel))
89
+ return undefined;
90
+ const to = (by) => {
91
+ const neighbour = neighbourStep(steps, panel, by);
92
+ return neighbour === undefined ? undefined : () => open(neighbour.id);
93
+ };
94
+ return { number: panel.step, count: steps.length, onBack: to(-1), onNext: to(1) };
95
+ }
96
+ /** A request to open a panel (a marker press or the host's `setPanel`; id "" closes the open one), told with who made it. */
97
+ function applyPanelRequest(story, request) {
98
+ if (request === null || request === undefined)
99
+ return;
100
+ const by = request.host === true ? "host" : "visitor";
101
+ if (request.id === "")
102
+ story.close(by);
103
+ else
104
+ story.open(request.id, by);
105
+ }
106
+ function stepsOf(storySet) {
107
+ return storySet?.steps ?? [];
108
+ }
77
109
  function objectLabelOr(experience, objectId, fallback) {
78
- return experience.objects.find((object) => object.id === objectId)?.label ?? fallback;
110
+ return experience.objects.find((object) => object.id === objectId)?.label ?? skyFigureById(experience, objectId)?.label ?? fallback;
79
111
  }
80
112
  /** The information panel's content and, for an object, its live measurements. */
81
113
  function infoContent(experience, info, selectedObjectId, timeUtcMs, metricsFor) {
82
114
  const view = info === null
83
115
  ? null
84
116
  : infoView(experience, info.kind === "object" ? { kind: "object", id: selectedObjectId } : info, timeUtcMs);
85
- const metrics = view?.target.kind === "object" && metricsFor !== undefined ? metricsFor(view.target.id, timeUtcMs) : [];
117
+ const metrics = view?.target.kind === "object" && metricsFor !== undefined && skyFigureById(experience, view.target.id) === undefined ? metricsFor(view.target.id, timeUtcMs) : [];
86
118
  return { view, metrics };
87
119
  }
88
120
  /** The moon families load on demand: only an experience with `moonFamilies` draws them (I-089). */
89
121
  const MoonFamilyPanel = lazy(() => import("./MoonFamilyPanel.js").then((module) => ({ default: module.MoonFamilyPanel })));
90
122
  /** 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, }) {
123
+ 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, }) {
92
124
  const infoPanelId = `${useId()}-info-panel`;
93
125
  const [selectedObjectId, setSelectedObjectId] = useState(() => initialObjectId(experience, snapshot.timeUtcMs));
94
126
  const phone = usePhone();
@@ -108,13 +140,23 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
108
140
  const [info, setInfo] = useState(null);
109
141
  const storySet = experience.storyPanels;
110
142
  const storyPanels = panelsOf(storySet);
111
- const story = useStoryPanels(storyPanels, storyPanelSettings ?? ownStorySettings(storySet), snapshot, onSetPlaying);
143
+ const storySteps = stepsOf(storySet);
144
+ const story = useStoryPanels(storyPanels, storySteps, storyPanelSettings ?? ownStorySettings(storySet), snapshot, onSetPlaying);
145
+ if (storySeekNote !== undefined)
146
+ storySeekNote.current = story.noteSeek;
147
+ useEffect(() => () => { if (storySeekNote !== undefined)
148
+ storySeekNote.current = null; }, [storySeekNote]);
112
149
  const openPanelId = story.openPanel?.id ?? null;
113
- useEffect(() => { onOpenPanelChange?.(openPanelId); }, [onOpenPanelChange, openPanelId]);
150
+ const storyCause = story.cause;
151
+ // Only a change of the open panel is reported; the cause read then is the one that change came with.
152
+ const lastCause = useRef(storyCause);
153
+ lastCause.current = storyCause;
154
+ useEffect(() => { onOpenPanelChange?.(openPanelId, lastCause.current); }, [onOpenPanelChange, openPanelId]);
155
+ const closePanel = () => story.close();
156
+ const stepNav = stepNavOf(story.openPanel, storySteps, story.open);
114
157
  const requestedSerial = serialOf(panelRequest);
115
158
  useEffect(() => {
116
- if (panelRequest !== null && panelRequest !== undefined)
117
- story.open(panelRequest.id);
159
+ applyPanelRequest(story, panelRequest);
118
160
  // Only a new request opens a panel; the open function is stable.
119
161
  // eslint-disable-next-line react-hooks/exhaustive-deps
120
162
  }, [requestedSerial]);
@@ -139,12 +181,16 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
139
181
  useEffect(() => {
140
182
  onSelectionChange(selectedObjectId, "visitor");
141
183
  }, [onSelectionChange, selectedObjectId]);
184
+ /** The host cleared the selection: the fallback that picks the first available object stays off until something is selected again. */
185
+ const hostCleared = useRef(false);
142
186
  // A view switch is told from other changes of the experience by the view's id changing.
143
187
  const { viewId, takeSwitchRule } = useViewSwitch(viewCamera);
144
188
  useEffect(() => {
145
189
  const switchRule = takeSwitchRule();
190
+ if (selectedObjectId !== "")
191
+ hostCleared.current = false;
146
192
  const selected = experience.objects.find((object) => object.id === selectedObjectId);
147
- if (selected === undefined || !isObjectAvailable(selected, snapshot.timeUtcMs)) {
193
+ if (selectionLost(selected, snapshot.timeUtcMs, hostCleared.current && selectedObjectId === "", skyFigureById(experience, selectedObjectId) !== undefined)) {
148
194
  const fallbackId = firstAvailableObject(experience, snapshot.timeUtcMs)?.id ?? "";
149
195
  setSelectedObjectId(fallbackId);
150
196
  onSelectionChange(fallbackId, "move");
@@ -154,8 +200,11 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
154
200
  }
155
201
  const active = experience.cameraPresets.find((preset) => preset.id === activePresetId);
156
202
  const activeRequest = active?.request;
157
- if (activeRequest !== undefined && activeRequest.kind !== "overview") {
158
- const target = experience.objects.find((object) => object.id === activeRequest.target);
203
+ if (switchRule?.rule === "start" && switchRule.framing?.always === true) {
204
+ applyViewRule(switchRule); // opted in: the view's framing applies on every switch to it
205
+ }
206
+ else if (activeRequest !== undefined && activeRequest.kind !== "overview") {
207
+ const target = experience.objects.find((object) => object.id === requestObjectId(activeRequest));
159
208
  if (switchRule !== undefined && target === undefined) {
160
209
  applyViewRule(switchRule);
161
210
  }
@@ -169,10 +218,25 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
169
218
  }
170
219
  // eslint-disable-next-line react-hooks/exhaustive-deps
171
220
  }, [activePresetId, experience, onCameraRequest, onSelectionChange, selectedObjectId, snapshot.timeUtcMs, viewId]);
221
+ // 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.
222
+ const requestedSelectSerial = serialOf(selectRequest);
223
+ useEffect(() => {
224
+ if (selectRequest === null || selectRequest === undefined)
225
+ return;
226
+ hostCleared.current = selectRequest.id === "";
227
+ setSelectedObjectId(selectRequest.id);
228
+ // As a visitor's menu choice does: the object's card opens (the camera is left alone); a clear closes it.
229
+ // 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.
230
+ const opens = selectRequest.quiet === true ? pickOpensInfo(phone) : true;
231
+ setInfo((now) => (selectRequest.id === "" ? (now?.kind === "object" ? null : now) : opens ? { kind: "object" } : now));
232
+ onSelectRequestApplied?.();
233
+ // Only a new request applies.
234
+ // eslint-disable-next-line react-hooks/exhaustive-deps
235
+ }, [requestedSelectSerial]);
172
236
  /** 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
237
  const applyViewRule = (rule) => {
174
238
  const asked = presetForViewRule(rule, experience);
175
- const target = asked === undefined || asked.request.kind === "overview" ? undefined : availableObjectById(experience, asked.request.target, snapshot.timeUtcMs);
239
+ const target = asked === undefined || asked.request.kind === "overview" ? undefined : availableObjectById(experience, requestObjectId(asked.request) ?? "", snapshot.timeUtcMs);
176
240
  // A framing whose object is not available now falls back to the overview, like any other lost target.
177
241
  const preset = asked !== undefined && asked.request.kind !== "overview" && target === undefined ? findCameraPreset(experience, "overview") : asked;
178
242
  if (target !== undefined) {
@@ -180,6 +244,8 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
180
244
  onSelectionChange(target.id, "move"); // only the move-driven effect applies a view rule
181
245
  }
182
246
  setActivePresetId(preset?.id ?? null);
247
+ if (hostCameraSet?.() === true)
248
+ return; // a host camera call made since the switch answers it and wins over the rule
183
249
  if (preset !== undefined)
184
250
  onCameraRequest(preset.request);
185
251
  else
@@ -197,7 +263,10 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
197
263
  /** 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. */
198
264
  const pickObject = (id) => {
199
265
  const object = availableObjectById(experience, id, snapshot.timeUtcMs);
200
- if (object !== undefined) {
266
+ if (skyFigureById(experience, id) !== undefined) {
267
+ selectFigure(id, pickOpensInfo(phone));
268
+ }
269
+ else if (object !== undefined) {
201
270
  activatePreset(focusPresetFor(experience, object));
202
271
  if (pickOpensInfo(phone))
203
272
  setInfo({ kind: "object" });
@@ -212,7 +281,18 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
212
281
  // Only a new request flies; the handler reads the current time and experience.
213
282
  // eslint-disable-next-line react-hooks/exhaustive-deps
214
283
  }, [requestedPickSerial]);
284
+ /** 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. */
285
+ const selectFigure = (id, open) => {
286
+ setSelectedObjectId(id);
287
+ onSelectionChange(id, "visitor");
288
+ if (open)
289
+ setInfo({ kind: "object" });
290
+ };
215
291
  const selectObject = (id) => {
292
+ if (skyFigureById(experience, id) !== undefined) {
293
+ selectFigure(id, true);
294
+ return;
295
+ }
216
296
  const object = availableObjectById(experience, id, snapshot.timeUtcMs);
217
297
  if (object === undefined)
218
298
  return;
@@ -236,8 +316,9 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
236
316
  }
237
317
  };
238
318
  const activatePreset = (preset, atUtcMs = snapshot.timeUtcMs) => {
239
- if (preset.request.kind !== "overview") {
240
- const target = availableObjectById(experience, preset.request.target, atUtcMs);
319
+ const objectId = requestObjectId(preset.request);
320
+ if (objectId !== undefined) {
321
+ const target = availableObjectById(experience, objectId, atUtcMs);
241
322
  if (target === undefined)
242
323
  return;
243
324
  setSelectedObjectId(target.id);
@@ -252,6 +333,11 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
252
333
  const object = event.object === undefined ? undefined : availableObjectById(experience, event.object, event.timeUtcMs);
253
334
  if (object !== undefined)
254
335
  activatePreset(focusPresetFor(experience, object), event.timeUtcMs);
336
+ // A sky figure is selected (its card stays as it is) and turned toward only while the camera looks out.
337
+ else if (event.object !== undefined && skyFigureById(experience, event.object) !== undefined) {
338
+ selectFigure(event.object, false);
339
+ onTurnToFigure?.(event.object);
340
+ }
255
341
  if (info?.kind === "event")
256
342
  setInfo({ kind: "event", id: event.id });
257
343
  };
@@ -272,5 +358,5 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
272
358
  const selectedLabel = objectLabelOr(experience, selectedObjectId, "Controls");
273
359
  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 }));
274
360
  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 }) }) }));
275
- 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 })] }));
361
+ 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 })] }));
276
362
  }
@@ -1,18 +1,21 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { findCameraPreset, focusPresetFor, isObjectAvailable, listedObjects, relatedObjects } from "./objectModel.js";
3
- import { ButtonText, FocusIcon, FollowIcon, InfoIcon, OrbitIcon, OverviewIcon } from "./topBarIcons.js";
2
+ import { findCameraPreset, focusPresetFor, isObjectAvailable, listedFigures, listedObjects, relatedObjects, skyFigureById } from "./objectModel.js";
3
+ import { ButtonText, FocusIcon, LookOutIcon, FollowIcon, InfoIcon, OrbitIcon, OverviewIcon } from "./topBarIcons.js";
4
4
  export function ObjectControls({ experience, timeUtcMs, selectedObjectId, activePresetId, onSelectObject, onCameraPreset, infoOpen, onToggleInfo, infoPanelId, }) {
5
5
  const selected = experience.objects.find((object) => object.id === selectedObjectId);
6
+ const selectedFigure = skyFigureById(experience, selectedObjectId);
6
7
  const selectedAvailable = selected !== undefined && isObjectAvailable(selected, timeUtcMs);
8
+ const infoLabel = selected?.label ?? selectedFigure?.label;
7
9
  const overview = findCameraPreset(experience, "overview");
8
10
  const focus = selected === undefined ? undefined : focusPresetFor(experience, selected);
9
11
  const follow = selected === undefined ? undefined : findCameraPreset(experience, "follow", selected.id);
12
+ const lookOut = selected === undefined ? undefined : findCameraPreset(experience, "lookOut", selected.id);
10
13
  const related = selected === undefined ? [] : relatedObjects(experience, selected.id);
11
- const presetIcon = (preset) => preset.request.kind === "overview" ? _jsx(OverviewIcon, {}) : preset.request.kind === "follow" ? _jsx(FollowIcon, {}) : _jsx(FocusIcon, {});
12
- const presetText = (preset) => (preset.request.kind === "overview" ? "Overview" : preset.request.kind === "follow" ? "Follow" : "Focus");
14
+ const presetIcon = (preset) => preset.request.kind === "overview" ? _jsx(OverviewIcon, {}) : preset.request.kind === "follow" ? _jsx(FollowIcon, {}) : preset.request.kind === "lookOut" ? _jsx(LookOutIcon, {}) : _jsx(FocusIcon, {});
15
+ const presetText = (preset) => (preset.request.kind === "overview" ? "Overview" : preset.request.kind === "follow" ? "Follow" : preset.request.kind === "lookOut" ? "Look out" : "Focus");
13
16
  const renderPreset = (preset) => preset && (_jsxs("button", { type: "button", className: "top-bar-button ui-icon", "data-closes-drawer": "", "aria-label": preset.label, title: preset.label, "aria-pressed": activePresetId === preset.id, "data-camera-preset": preset.id, onClick: () => onCameraPreset(preset), disabled: preset.request.kind !== "overview" && !selectedAvailable, children: [presetIcon(preset), _jsx(ButtonText, { children: presetText(preset) })] }, preset.id));
14
- return (_jsxs("section", { className: "object-controls", "aria-label": "Object and camera controls", children: [_jsx("select", { className: "object-picker", "data-closes-drawer": "", "aria-label": "Select object", value: selectedObjectId, onChange: (event) => onSelectObject(event.target.value), children: listedObjects(experience, selectedObjectId).map((object) => {
15
- const available = isObjectAvailable(object, timeUtcMs);
16
- return (_jsxs("option", { value: object.id, disabled: !available, "data-available": available, "data-available-from": object.availability?.startUtcMs, "data-available-to": object.availability?.endUtcMs, children: [object.label, available ? "" : " (Unavailable)"] }, object.id));
17
- }) }), _jsxs("button", { type: "button", className: "top-bar-button ui-icon object-info-toggle", "data-closes-drawer": "", "aria-label": selected === undefined ? "Information" : `Information about ${selected.label}`, title: selected === undefined ? "Information" : `Information about ${selected.label}`, "aria-expanded": infoOpen, "aria-controls": infoPanelId, disabled: !selectedAvailable, onClick: onToggleInfo, children: [_jsx(InfoIcon, {}), _jsx(ButtonText, { children: "Info" })] }), _jsxs("div", { className: "object-camera-actions", children: [renderPreset(focus), renderPreset(follow), renderPreset(overview), related.map((object) => (_jsxs("button", { type: "button", className: "top-bar-button ui-icon object-related", "aria-label": object.label, title: object.label, "data-related-object": object.id, disabled: !isObjectAvailable(object, timeUtcMs), onClick: () => onSelectObject(object.id), children: [_jsx(OrbitIcon, {}), _jsx(ButtonText, { children: object.label })] }, object.id)))] })] }));
17
+ return (_jsxs("section", { className: "object-controls", "aria-label": "Object and camera controls", children: [_jsxs("select", { className: "object-picker", "data-closes-drawer": "", "aria-label": "Select object", value: selectedObjectId, onChange: (event) => onSelectObject(event.target.value), children: [listedObjects(experience, selectedObjectId).map((object) => {
18
+ const available = isObjectAvailable(object, timeUtcMs);
19
+ return (_jsxs("option", { value: object.id, disabled: !available, "data-available": available, "data-available-from": object.availability?.startUtcMs, "data-available-to": object.availability?.endUtcMs, children: [object.label, available ? "" : " (Unavailable)"] }, object.id));
20
+ }), listedFigures(experience, selectedObjectId).map((figure) => _jsx("option", { value: figure.id, "data-sky-figure": "", children: figure.label }, figure.id))] }), _jsxs("button", { type: "button", className: "top-bar-button ui-icon object-info-toggle", "data-closes-drawer": "", "aria-label": infoLabel === undefined ? "Information" : `Information about ${infoLabel}`, title: infoLabel === undefined ? "Information" : `Information about ${infoLabel}`, "aria-expanded": infoOpen, "aria-controls": infoPanelId, disabled: !selectedAvailable && selectedFigure === undefined, onClick: onToggleInfo, children: [_jsx(InfoIcon, {}), _jsx(ButtonText, { children: "Info" })] }), _jsxs("div", { className: "object-camera-actions", children: [renderPreset(focus), renderPreset(follow), renderPreset(lookOut), renderPreset(overview), related.map((object) => (_jsxs("button", { type: "button", className: "top-bar-button ui-icon object-related", "aria-label": object.label, title: object.label, "data-related-object": object.id, disabled: !isObjectAvailable(object, timeUtcMs), onClick: () => onSelectObject(object.id), children: [_jsx(OrbitIcon, {}), _jsx(ButtonText, { children: object.label })] }, object.id)))] })] }));
18
21
  }
@@ -1,11 +1,20 @@
1
1
  import type { ProvenanceSourceType } from "../core/provenance.js";
2
- import type { StoryPanel } from "./storyPanels.js";
2
+ import type { StoryPanel, StoryStep } from "./storyPanels.js";
3
3
  /** A small pill saying how far to trust a panel's facts, after Planetary Explorer's Badge. */
4
4
  export declare function StoryBadge({ sourceType }: {
5
5
  readonly sourceType: ProvenanceSourceType;
6
6
  }): import("react").JSX.Element;
7
+ /** A step's place and its neighbours: `onBack` and `onNext` are absent at the first and last step. */
8
+ export interface StepNav {
9
+ readonly number: number;
10
+ readonly count: number;
11
+ readonly onBack?: (() => void) | undefined;
12
+ readonly onNext?: (() => void) | undefined;
13
+ }
7
14
  interface Props {
8
- readonly panel: StoryPanel;
15
+ readonly panel: StoryPanel | StoryStep;
16
+ /** Present when the panel is a step: shows "Step n of m", Back and Next. */
17
+ readonly step?: StepNav | undefined;
9
18
  /** True while playback is held for this panel; shows the Continue button. */
10
19
  readonly holding: boolean;
11
20
  readonly onClose: () => void;
@@ -15,5 +24,5 @@ interface Props {
15
24
  * One story panel: a side panel beside the scene on a wide screen, a bottom sheet with a grab handle on a phone
16
25
  * (the stylesheet chooses). Closing, Escape and a swipe down all dismiss it.
17
26
  */
18
- export declare function StoryPanelView({ panel, holding, onClose, onContinue }: Props): import("react").JSX.Element;
27
+ export declare function StoryPanelView({ panel, step, holding, onClose, onContinue }: Props): import("react").JSX.Element;
19
28
  export {};
@@ -13,7 +13,7 @@ export function StoryBadge({ sourceType }) {
13
13
  * One story panel: a side panel beside the scene on a wide screen, a bottom sheet with a grab handle on a phone
14
14
  * (the stylesheet chooses). Closing, Escape and a swipe down all dismiss it.
15
15
  */
16
- export function StoryPanelView({ panel, holding, onClose, onContinue }) {
16
+ export function StoryPanelView({ panel, step, holding, onClose, onContinue }) {
17
17
  const titleId = `${useId()}-title`;
18
18
  const sheet = useRef(null);
19
19
  useSwipeToDismiss(sheet, onClose);
@@ -24,5 +24,5 @@ export function StoryPanelView({ panel, holding, onClose, onContinue }) {
24
24
  document.addEventListener("keydown", onKey);
25
25
  return () => document.removeEventListener("keydown", onKey);
26
26
  }, [onClose]);
27
- return (_jsxs("aside", { className: "story-panel", ref: sheet, role: "dialog", "aria-modal": "false", "aria-labelledby": titleId, "data-panel-id": panel.id, children: [_jsx("div", { className: "sheet-handle", "aria-hidden": "true" }), _jsxs("header", { className: "story-panel-header", children: [_jsx(StoryBadge, { sourceType: panel.provenance.sourceType }), _jsx("button", { type: "button", className: "story-panel-close ui-icon", "aria-label": "Close story panel", onClick: onClose, children: "\u00D7" })] }), _jsx("h2", { id: titleId, children: panel.title }), _jsx("div", { className: "story-panel-body", children: panel.body.map((paragraph) => _jsx("p", { children: paragraph }, paragraph)) }), _jsx(Sources, { sources: panel.provenance.sources, details: panel.details, accuracy: panel.provenance.accuracy, notes: panel.provenance.notes }), holding && _jsx("button", { type: "button", className: "story-panel-continue ui-accent", onClick: onContinue, children: "Continue playback" })] }));
27
+ return (_jsxs("aside", { className: "story-panel", ref: sheet, role: "dialog", "aria-modal": "false", "aria-labelledby": titleId, "data-panel-id": panel.id, children: [_jsx("div", { className: "sheet-handle", "aria-hidden": "true" }), _jsxs("header", { className: "story-panel-header", children: [_jsx(StoryBadge, { sourceType: panel.provenance.sourceType }), _jsx("button", { type: "button", className: "story-panel-close ui-icon", "aria-label": "Close story panel", onClick: onClose, children: "\u00D7" })] }), _jsx("h2", { id: titleId, children: panel.title }), _jsx("div", { className: "story-panel-body", children: panel.body.map((paragraph) => _jsx("p", { children: paragraph }, paragraph)) }), _jsx(Sources, { sources: panel.provenance.sources, details: panel.details, accuracy: panel.provenance.accuracy, notes: panel.provenance.notes }), step !== undefined && (_jsxs("nav", { className: "story-panel-steps", "aria-label": "Story steps", children: [_jsx("button", { type: "button", className: "story-panel-back ui-icon", disabled: step.onBack === undefined, onClick: step.onBack, children: "Back" }), _jsxs("span", { className: "story-panel-step-count", children: ["Step ", step.number, " of ", step.count] }), _jsx("button", { type: "button", className: "story-panel-next ui-accent", disabled: step.onNext === undefined, onClick: step.onNext, children: "Next" })] })), holding && _jsx("button", { type: "button", className: "story-panel-continue ui-accent", onClick: onContinue, children: "Continue playback" })] }));
28
28
  }
@@ -46,13 +46,35 @@ export type ExperienceCameraRequest = {
46
46
  } | {
47
47
  readonly kind: "focus" | "follow";
48
48
  readonly target: string;
49
+ }
50
+ /** Stand inside `body` looking out: `direction` is a unit vector in the J2000 equatorial frame, or an object id to turn toward. */
51
+ | {
52
+ readonly kind: "lookOut";
53
+ readonly body: string;
54
+ readonly direction: readonly [number, number, number] | string;
55
+ readonly fovDeg?: number;
49
56
  };
57
+ /** The object a camera request frames or stands in: none for the overview. */
58
+ export declare function requestObjectId(request: ExperienceCameraRequest): string | undefined;
50
59
  export interface ExperienceCameraPreset {
51
60
  readonly id: string;
52
61
  readonly label: string;
53
62
  readonly request: ExperienceCameraRequest;
54
63
  }
55
64
  /** The labels and timeline data a reusable viewer shell needs from an experience. */
65
+ /** What the info card and object menu show for a sky figure (`Scene.addSkyFigures`); the figure's lines and name are drawn by the app, not by the shell. */
66
+ export interface SkyFigureCard {
67
+ readonly id: string;
68
+ readonly label: string;
69
+ readonly description?: string;
70
+ readonly facts?: readonly {
71
+ readonly label: string;
72
+ readonly value: string;
73
+ }[];
74
+ readonly provenance: Provenance;
75
+ /** False leaves it out of the object menu (the menu shows it while it is selected). */
76
+ readonly listed: boolean;
77
+ }
56
78
  export interface ExperienceConfig {
57
79
  readonly objects: readonly ExperienceObject[];
58
80
  readonly cameraPresets: readonly ExperienceCameraPreset[];
@@ -71,6 +93,8 @@ export interface ExperienceConfig {
71
93
  readonly moonFamilies?: MoonFamilyList;
72
94
  /** Tagged places on bodies (a body package's features): drawn as markers on the body and opened in the information panel. Omit for an experience with none. */
73
95
  readonly bodyFeatures?: readonly BodyFeatureSet[];
96
+ /** Sky figures a visitor can select (tap or object menu): their cards and menu flags. Omit for an experience with none. Ids are distinct from every object id. */
97
+ readonly skyFigures?: readonly SkyFigureCard[];
74
98
  /** Where the event times come from, shown with every event. */
75
99
  readonly eventProvenance?: Provenance;
76
100
  /** Provenance of single events by event id; an event listed here shows it instead of `eventProvenance`. */
@@ -1 +1,4 @@
1
- export {};
1
+ /** The object a camera request frames or stands in: none for the overview. */
2
+ export function requestObjectId(request) {
3
+ return request.kind === "overview" ? undefined : request.kind === "lookOut" ? request.body : request.target;
4
+ }
@@ -1,5 +1,6 @@
1
1
  import { provenanceAt, rateAt, spanProvenanceAt } from "../core/timeWindow.js";
2
2
  import { findFeature } from "./bodyFeatures.js";
3
+ import { skyFigureById } from "./objectModel.js";
3
4
  import { formatUtcTimestamp, formatWindowRate } from "./timelineModel.js";
4
5
  /** The badge text for each provenance status. The status is always written, never shown by colour alone. */
5
6
  export const PROVENANCE_STATUS = {
@@ -59,7 +60,7 @@ function featureInfo(experience, target) {
59
60
  function objectInfo(experience, target, timeUtcMs) {
60
61
  const object = experience.objects.find((candidate) => candidate.id === target.id);
61
62
  if (object === undefined)
62
- return null;
63
+ return skyFigureInfo(experience, target);
63
64
  const source = (timeUtcMs === undefined || object.provenanceSpans === undefined ? null : spanProvenanceAt(object.provenanceSpans, timeUtcMs)) ?? object.provenance;
64
65
  return {
65
66
  target,
@@ -81,3 +82,10 @@ function eventInfo(experience, target) {
81
82
  provenance: source === undefined ? null : provenanceView(source),
82
83
  };
83
84
  }
85
+ /** The card of a selected sky figure: the same card a body has (description, facts, provenance), with the kind as its subtitle. */
86
+ function skyFigureInfo(experience, target) {
87
+ const figure = skyFigureById(experience, target.id);
88
+ if (figure === undefined)
89
+ return null;
90
+ return { target, title: figure.label, ...(figure.description === undefined ? {} : { description: figure.description }), ...(figure.facts === undefined ? {} : { facts: figure.facts }), provenance: provenanceView(figure.provenance) };
91
+ }
@@ -1,5 +1,5 @@
1
- import type { ExperienceCameraPreset, ExperienceConfig, ExperienceObject } from "./experience.js";
2
- export type CameraMode = "overview" | "focus" | "follow";
1
+ import { type ExperienceCameraPreset, type ExperienceConfig, type ExperienceObject, type SkyFigureCard } from "./experience.js";
2
+ export type CameraMode = "overview" | "focus" | "follow" | "lookOut";
3
3
  export declare function isObjectAvailable(object: ExperienceObject, timeUtcMs: number): boolean;
4
4
  export declare function availableObjectById(experience: ExperienceConfig, id: string, timeUtcMs: number): ExperienceObject | undefined;
5
5
  export declare function firstAvailableObject(experience: ExperienceConfig, timeUtcMs: number): ExperienceObject | undefined;
@@ -16,3 +16,7 @@ export declare function findCameraPreset(experience: ExperienceConfig, mode: Cam
16
16
  export declare function listedObjects(experience: ExperienceConfig, selectedId: string): readonly ExperienceObject[];
17
17
  /** Unlisted objects that belong to `id` (an orbit line to its body), for the related buttons in the top bar. */
18
18
  export declare function relatedObjects(experience: ExperienceConfig, id: string): readonly ExperienceObject[];
19
+ /** The sky figure a selected id names, or undefined (object ids and figure ids never collide: the scene checks it). */
20
+ export declare function skyFigureById(experience: ExperienceConfig, id: string): SkyFigureCard | undefined;
21
+ /** The sky figures the Object list offers, under the rule objects follow (`listed`): the listed ones, and the selected one even when unlisted. */
22
+ export declare function listedFigures(experience: ExperienceConfig, selectedId: string): readonly SkyFigureCard[];
@@ -1,3 +1,4 @@
1
+ import { requestObjectId } from "./experience.js";
1
2
  export function isObjectAvailable(object, timeUtcMs) {
2
3
  const bounds = object.availability;
3
4
  return bounds === undefined || (timeUtcMs >= bounds.startUtcMs && timeUtcMs <= bounds.endUtcMs);
@@ -21,7 +22,7 @@ export function findCameraPreset(experience, mode, target) {
21
22
  const request = preset.request;
22
23
  if (request.kind === "overview")
23
24
  return mode === "overview";
24
- return request.kind === mode && request.target === target;
25
+ return request.kind === mode && requestObjectId(request) === target;
25
26
  });
26
27
  }
27
28
  /** The objects the Object list offers: the listed ones, and the selected one even when unlisted so the list never shows a blank. */
@@ -32,3 +33,11 @@ export function listedObjects(experience, selectedId) {
32
33
  export function relatedObjects(experience, id) {
33
34
  return experience.objects.filter((object) => object.listed === false && object.partOf === id);
34
35
  }
36
+ /** The sky figure a selected id names, or undefined (object ids and figure ids never collide: the scene checks it). */
37
+ export function skyFigureById(experience, id) {
38
+ return experience.skyFigures?.find((figure) => figure.id === id);
39
+ }
40
+ /** The sky figures the Object list offers, under the rule objects follow (`listed`): the listed ones, and the selected one even when unlisted. */
41
+ export function listedFigures(experience, selectedId) {
42
+ return (experience.skyFigures ?? []).filter((figure) => figure.listed || figure.id === selectedId);
43
+ }
@@ -172,7 +172,7 @@
172
172
  padding: 9px;
173
173
  }
174
174
  .astraeus-shell[data-phone="true"] .shell-top { top: 8px; left: 8px; width: calc(100vw - 16px); max-width: calc(100vw - 16px); max-height: none; }
175
- .astraeus-shell[data-phone="true"] .astraeus-label { font-size: 12px; }
175
+ .astraeus-shell[data-phone="true"] .astraeus-label { font-size: var(--label-size, 12px); }
176
176
 
177
177
  @media (prefers-reduced-motion: reduce) {
178
178
  .astraeus-shell .controls-drawer,
@@ -1,5 +1,5 @@
1
1
  import type { StoryPanel } from "../core/storyPanels.js";
2
- export { checkPanelPlayback, checkStoryPanel, DEFAULT_PANEL_PAUSE_SECONDS, MAX_PANEL_PAUSE_SECONDS, resolveStoryPanels, StoryPanelError, type PanelLookup, type StoryPanel, type StoryPanelSet, } from "../core/storyPanels.js";
2
+ export { checkPanelPlayback, checkStoryPanel, DEFAULT_PANEL_PAUSE_SECONDS, MAX_PANEL_PAUSE_SECONDS, resolveStoryPanels, StoryPanelError, type PanelLookup, type StoryPanel, type StoryPanelSet, type StoryStep, neighbourStep, } from "../core/storyPanels.js";
3
3
  /**
4
4
  * The panels forward playback just passed: those with `previousMs < time <= currentMs`, in time order.
5
5
  * A backward step or no movement crosses nothing, so loops and rewinds never open a panel.
@@ -1,4 +1,4 @@
1
- export { checkPanelPlayback, checkStoryPanel, DEFAULT_PANEL_PAUSE_SECONDS, MAX_PANEL_PAUSE_SECONDS, resolveStoryPanels, StoryPanelError, } from "../core/storyPanels.js";
1
+ export { checkPanelPlayback, checkStoryPanel, DEFAULT_PANEL_PAUSE_SECONDS, MAX_PANEL_PAUSE_SECONDS, resolveStoryPanels, StoryPanelError, neighbourStep, } from "../core/storyPanels.js";
2
2
  /**
3
3
  * The panels forward playback just passed: those with `previousMs < time <= currentMs`, in time order.
4
4
  * A backward step or no movement crosses nothing, so loops and rewinds never open a panel.
@@ -94,7 +94,8 @@
94
94
  border-radius: 5px;
95
95
  background: rgba(13, 13, 13, .84);
96
96
  color: var(--label-color, #f0e6da);
97
- font-size: 12px;
97
+ font-family: var(--label-font, inherit);
98
+ font-size: var(--label-size, 12px);
98
99
  line-height: 1.35;
99
100
  text-overflow: ellipsis;
100
101
  white-space: nowrap;
@@ -250,6 +251,13 @@
250
251
  .astraeus-shell .sources-section li + li { margin-top: 3px; }
251
252
  .astraeus-shell :where(.story-panel-close) { font-size: 20px; line-height: 1; }
252
253
  .astraeus-shell :where(.story-panel-continue) { align-self: flex-start; }
254
+ /* Touch targets: Close, Back, Next and Continue are at least 44 px each way, at 375x667 and 1280x720 alike. */
255
+ .astraeus-shell :where(.story-panel-close, .story-panel-back, .story-panel-next, .story-panel-continue) { min-width: 44px; min-height: 44px; }
256
+ /* Steps: Back and Next stay at the foot of the panel as it scrolls; the count between them shrinks and wraps before either button does. */
257
+ .astraeus-shell .story-panel-steps { position: sticky; bottom: -14px; display: flex; align-items: center; justify-content: space-between; gap: 8px; margin: 0 -14px -14px; padding: 6px 14px 14px; background: var(--ui-panel, rgba(13, 13, 13, .94)); }
258
+ .astraeus-shell .story-panel-step-count { flex: 1 1 auto; min-width: 0; text-align: center; color: var(--ui-subtle, #a99e94); font-size: 13px; overflow-wrap: anywhere; }
259
+ .astraeus-shell .story-panel-steps button { flex: 0 0 auto; }
260
+ .astraeus-shell .story-panel-steps button:disabled { opacity: .4; cursor: default; }
253
261
 
254
262
  /* The badge: monospace caps pill, tinted by how far to trust the facts. */
255
263
  .astraeus-shell .story-badge {
@@ -3,6 +3,7 @@ export declare const InfoIcon: () => import("react").JSX.Element;
3
3
  export declare const FocusIcon: () => import("react").JSX.Element;
4
4
  export declare const OverviewIcon: () => import("react").JSX.Element;
5
5
  export declare const FollowIcon: () => import("react").JSX.Element;
6
+ export declare const LookOutIcon: () => import("react").JSX.Element;
6
7
  export declare const OrbitIcon: () => import("react").JSX.Element;
7
8
  export declare const SwitchesIcon: () => import("react").JSX.Element;
8
9
  export declare const ScaleIcon: () => import("react").JSX.Element;
@@ -7,6 +7,7 @@ export const InfoIcon = () => _jsxs(Icon, { children: [_jsx("circle", { cx: "12"
7
7
  export const FocusIcon = () => _jsxs(Icon, { children: [_jsx("circle", { cx: "10.5", cy: "10.5", r: "6.5" }), _jsx("path", { d: "M15.5 15.5 21 21" })] });
8
8
  export const OverviewIcon = () => _jsx(Icon, { children: _jsx("path", { d: "M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5" }) });
9
9
  export const FollowIcon = () => _jsxs(Icon, { children: [_jsx("circle", { cx: "12", cy: "12", r: "4" }), _jsx("path", { d: "M12 3v4M12 17v4M3 12h4M17 12h4" })] });
10
+ export const LookOutIcon = () => _jsxs(Icon, { children: [_jsx("path", { d: "M3 17h18" }), _jsx("path", { d: "M12 14V5M8.5 8.5 12 5l3.5 3.5" })] });
10
11
  export const OrbitIcon = () => _jsxs(Icon, { children: [_jsx("ellipse", { cx: "12", cy: "12", rx: "9", ry: "5", transform: "rotate(-20 12 12)" }), _jsx("circle", { cx: "12", cy: "12", r: "1.4", fill: "currentColor" })] });
11
12
  export const SwitchesIcon = () => _jsxs(Icon, { children: [_jsx("path", { d: "M4 8h10M18 8h2M4 16h2M10 16h10" }), _jsx("circle", { cx: "16", cy: "8", r: "2" }), _jsx("circle", { cx: "8", cy: "16", r: "2" })] });
12
13
  export const ScaleIcon = () => _jsxs(Icon, { size: 16, children: [_jsx("circle", { cx: "7", cy: "12", r: "2.5" }), _jsx("circle", { cx: "16", cy: "12", r: "5.5" })] });
@@ -1,19 +1,22 @@
1
1
  import type { ClockSnapshot } from "../core/clock.js";
2
- import { type StoryPanel } from "./storyPanels.js";
2
+ import { type StoryPanel, type StoryStep } from "./storyPanels.js";
3
3
  export interface StoryPanelSettings {
4
4
  readonly autoOpen: boolean;
5
5
  readonly pauseSeconds: number;
6
6
  }
7
+ /** Who opened or closed the panel: the visitor, the host, playback crossing a panel, or a move (a view switch dropped it; the link names whatever last moved the view). */
8
+ export type PanelCause = "visitor" | "host" | "playback" | "move";
7
9
  /**
8
10
  * Which story panel is open and whether playback is held for it. A panel opens by itself only when forward playback
9
11
  * carries the clock across its time; a seek (slider, Previous, Next, a link) re-bases the crossing check and opens nothing.
10
- * Only one panel is open at a time: the newest replaces the one before.
12
+ * Only one panel is open at a time: the newest replaces the one before. A step never opens from playback; with steps and no moment panel the first step is open at the start.
11
13
  */
12
- export declare function useStoryPanels(panels: readonly StoryPanel[], settings: StoryPanelSettings, snapshot: ClockSnapshot, setPlaying: ((playing: boolean) => void) | undefined): {
13
- openPanel: StoryPanel | null;
14
+ export declare function useStoryPanels(panels: readonly StoryPanel[], steps: readonly StoryStep[], settings: StoryPanelSettings, snapshot: ClockSnapshot, setPlaying: ((playing: boolean) => void) | undefined): {
15
+ openPanel: StoryPanel | StoryStep | null;
14
16
  holding: boolean;
15
- open: (id: string) => void;
16
- close: () => void;
17
+ open: (id: string, by?: PanelCause) => void;
18
+ close: (by?: PanelCause) => void;
17
19
  continuePlayback: () => void;
18
20
  noteSeek: (timeUtcMs: number) => void;
21
+ cause: PanelCause;
19
22
  };
@@ -3,10 +3,11 @@ import { CrossingTracker } from "./storyPanels.js";
3
3
  /**
4
4
  * Which story panel is open and whether playback is held for it. A panel opens by itself only when forward playback
5
5
  * carries the clock across its time; a seek (slider, Previous, Next, a link) re-bases the crossing check and opens nothing.
6
- * Only one panel is open at a time: the newest replaces the one before.
6
+ * Only one panel is open at a time: the newest replaces the one before. A step never opens from playback; with steps and no moment panel the first step is open at the start.
7
7
  */
8
- export function useStoryPanels(panels, settings, snapshot, setPlaying) {
9
- const [openId, setOpenId] = useState(null);
8
+ export function useStoryPanels(panels, steps, settings, snapshot, setPlaying) {
9
+ const [openId, setOpenId] = useState(() => (panels.length === 0 ? steps[0]?.id ?? null : null));
10
+ const cause = useRef("visitor");
10
11
  const [holding, setHolding] = useState(false);
11
12
  const tracker = useRef(new CrossingTracker(snapshot.timeUtcMs));
12
13
  const latest = useRef({ panels, settings, snapshot, setPlaying, holding });
@@ -16,6 +17,7 @@ export function useStoryPanels(panels, settings, snapshot, setPlaying) {
16
17
  const newest = tracker.current.advance(list, shot.timeUtcMs, shot.playing, now.autoOpen);
17
18
  if (newest === null)
18
19
  return;
20
+ cause.current = "playback";
19
21
  setOpenId(newest.id);
20
22
  if (now.pauseSeconds > 0 && control !== undefined) {
21
23
  control(false);
@@ -40,8 +42,9 @@ export function useStoryPanels(panels, settings, snapshot, setPlaying) {
40
42
  tracker.current.rebase(timeUtcMs);
41
43
  setHolding(false);
42
44
  }, []);
43
- const open = useCallback((id) => setOpenId(id), []);
44
- const close = useCallback(() => {
45
+ const open = useCallback((id, by = "visitor") => { cause.current = by; setOpenId(id); }, []);
46
+ const close = useCallback((by = "visitor") => {
47
+ cause.current = by;
45
48
  setOpenId(null);
46
49
  if (latest.current.holding)
47
50
  latest.current.setPlaying?.(true);
@@ -51,5 +54,6 @@ export function useStoryPanels(panels, settings, snapshot, setPlaying) {
51
54
  setHolding(false);
52
55
  latest.current.setPlaying?.(true);
53
56
  }, []);
54
- return { openPanel: panels.find((panel) => panel.id === openId) ?? null, holding, open, close, continuePlayback, noteSeek };
57
+ const openPanel = panels.find((panel) => panel.id === openId) ?? steps.find((step) => step.id === openId) ?? null;
58
+ return { openPanel, holding, open, close, continuePlayback, noteSeek, cause: openPanel === null && openId !== null ? "move" : cause.current };
55
59
  }