astraeus 0.8.1 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/CHANGELOG.md +85 -0
  2. package/README.md +104 -31
  3. package/package.json +1 -1
  4. package/src/api/AstraeusScene.d.ts +1 -1
  5. package/src/api/AstraeusScene.js +4 -1
  6. package/src/api/AstraeusScene.node.js +4 -1
  7. package/src/api/assembleScene.d.ts +2 -0
  8. package/src/api/assembleScene.js +28 -6
  9. package/src/api/cameraRequest.d.ts +15 -0
  10. package/src/api/cameraRequest.js +89 -0
  11. package/src/api/errors.d.ts +9 -1
  12. package/src/api/index.d.ts +6 -3
  13. package/src/api/look.d.ts +49 -0
  14. package/src/api/lookInput.d.ts +1 -1
  15. package/src/api/lookInput.js +6 -1
  16. package/src/api/planBodies.d.ts +2 -1
  17. package/src/api/planBodies.js +6 -1
  18. package/src/api/planCamera.d.ts +35 -7
  19. package/src/api/planCamera.js +94 -11
  20. package/src/api/planPaths.d.ts +2 -0
  21. package/src/api/planPaths.js +14 -9
  22. package/src/api/planSkyFigures.d.ts +22 -0
  23. package/src/api/planSkyFigures.js +145 -0
  24. package/src/api/planStory.d.ts +2 -2
  25. package/src/api/planStory.js +14 -9
  26. package/src/api/planViews.js +1 -1
  27. package/src/api/providerPathTimes.d.ts +10 -0
  28. package/src/api/providerPathTimes.js +109 -0
  29. package/src/api/scene.d.ts +23 -4
  30. package/src/api/scene.js +23 -5
  31. package/src/api/sceneReads.d.ts +21 -2
  32. package/src/api/shownDuring.d.ts +12 -0
  33. package/src/api/shownDuring.js +30 -0
  34. package/src/api/skyFigureInput.d.ts +45 -0
  35. package/src/api/skyFigureInput.js +1 -0
  36. package/src/api/skyTraceInput.d.ts +33 -0
  37. package/src/api/skyTraceInput.js +45 -0
  38. package/src/api/story.d.ts +13 -4
  39. package/src/api/story.js +45 -2
  40. package/src/api/viewerCamera.d.ts +4 -3
  41. package/src/api/viewerCamera.js +10 -32
  42. package/src/api/viewerHandle.d.ts +27 -4
  43. package/src/api/viewerHandle.js +6 -0
  44. package/src/api/viewerLink.d.ts +49 -4
  45. package/src/api/viewerLink.js +25 -0
  46. package/src/api/viewerPanels.d.ts +26 -0
  47. package/src/api/viewerPanels.js +42 -0
  48. package/src/api/viewerSelection.d.ts +1 -1
  49. package/src/api/viewerSelection.js +3 -3
  50. package/src/app/App.js +129 -30
  51. package/src/app/App.node.js +129 -30
  52. package/src/app/AstraeusScene.d.ts +20 -5
  53. package/src/app/AstraeusScene.js +3 -3
  54. package/src/app/CameraController.d.ts +19 -1
  55. package/src/app/CameraController.js +38 -11
  56. package/src/app/DeveloperSettings.d.ts +11 -3
  57. package/src/app/DeveloperSettings.js +13 -3
  58. package/src/app/SceneLabels.d.ts +20 -2
  59. package/src/app/SceneLabels.js +46 -6
  60. package/src/app/SkyFiguresView.d.ts +56 -0
  61. package/src/app/SkyFiguresView.js +242 -0
  62. package/src/app/StoryMarkers.d.ts +2 -2
  63. package/src/app/StoryMarkers.js +2 -2
  64. package/src/app/displaySwitches.d.ts +13 -3
  65. package/src/app/displaySwitches.js +17 -3
  66. package/src/app/experienceDefinition.d.ts +9 -3
  67. package/src/app/experienceDefinition.js +4 -2
  68. package/src/app/labelStyle.d.ts +17 -0
  69. package/src/app/labelStyle.js +13 -0
  70. package/src/app/liveLook.js +8 -0
  71. package/src/app/look.d.ts +9 -5
  72. package/src/app/look.js +11 -0
  73. package/src/app/lookOut.d.ts +32 -0
  74. package/src/app/lookOut.js +50 -0
  75. package/src/app/sceneCamera.d.ts +5 -3
  76. package/src/app/sceneCamera.js +66 -3
  77. package/src/app/sceneContentsHooks.d.ts +2 -1
  78. package/src/app/sceneContentsHooks.js +3 -2
  79. package/src/app/sceneFrame.d.ts +22 -4
  80. package/src/app/sceneFrame.js +67 -22
  81. package/src/app/sceneFraming.d.ts +7 -0
  82. package/src/app/sceneFraming.js +12 -0
  83. package/src/app/sceneHooks.d.ts +2 -0
  84. package/src/app/sceneHooks.js +4 -1
  85. package/src/app/scenePicking.d.ts +20 -0
  86. package/src/app/scenePicking.js +49 -0
  87. package/src/app/scenePointer.d.ts +3 -1
  88. package/src/app/scenePointer.js +3 -2
  89. package/src/app/skyFigures.d.ts +73 -0
  90. package/src/app/skyFigures.js +50 -0
  91. package/src/app/style.css +2 -1
  92. package/src/app/viewHiding.d.ts +10 -1
  93. package/src/app/viewHiding.js +30 -1
  94. package/src/app/viewLink.d.ts +8 -8
  95. package/src/app/viewLink.js +24 -4
  96. package/src/app/viewerPort.d.ts +30 -3
  97. package/src/assets/sky.d.ts +13 -4
  98. package/src/assets/sky.js +33 -8
  99. package/src/assets/stars/hyg-v42-naked-eye.json +1 -1
  100. package/src/core/bodies/moonSystem.js +1 -15
  101. package/src/core/lookValues.d.ts +9 -0
  102. package/src/core/lookValues.js +24 -0
  103. package/src/core/pacing.d.ts +38 -6
  104. package/src/core/pacing.js +141 -21
  105. package/src/core/readBytes.d.ts +1 -0
  106. package/src/core/readBytes.js +15 -0
  107. package/src/core/skyTrace.d.ts +49 -0
  108. package/src/core/skyTrace.js +39 -0
  109. package/src/core/startView.d.ts +39 -0
  110. package/src/core/startView.js +56 -0
  111. package/src/core/storyPanels.d.ts +51 -3
  112. package/src/core/storyPanels.js +52 -12
  113. package/src/shell/AstraeusShell.d.ts +17 -6
  114. package/src/shell/AstraeusShell.js +100 -26
  115. package/src/shell/AstraeusShell.node.js +100 -26
  116. package/src/shell/ObjectControls.js +11 -8
  117. package/src/shell/StoryPanelView.d.ts +12 -3
  118. package/src/shell/StoryPanelView.js +2 -2
  119. package/src/shell/experience.d.ts +31 -0
  120. package/src/shell/experience.js +4 -1
  121. package/src/shell/infoModel.js +9 -1
  122. package/src/shell/objectModel.d.ts +9 -4
  123. package/src/shell/objectModel.js +16 -5
  124. package/src/shell/phone.css +1 -1
  125. package/src/shell/storyPanels.d.ts +1 -1
  126. package/src/shell/storyPanels.js +1 -1
  127. package/src/shell/style.css +9 -1
  128. package/src/shell/topBarIcons.d.ts +1 -0
  129. package/src/shell/topBarIcons.js +1 -0
  130. package/src/shell/useStoryPanels.d.ts +9 -6
  131. package/src/shell/useStoryPanels.js +10 -6
@@ -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,12 @@ 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
+ /** Told the clock time as it moves, so the app can hold a camera whose target (named by a host or a story panel, not a preset) is no longer shown. */
36
+ readonly onTimeShown?: (timeUtcMs: number) => void;
33
37
  /** True when the host has set the camera since the last view switch: that call answers the switch, so the view's own camera rule does not replace it. */
34
38
  readonly hostCameraSet?: () => boolean;
35
39
  /** 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. */
@@ -62,6 +66,11 @@ interface Props {
62
66
  readonly timelineGlow?: TimelineGlowLook;
63
67
  /** The phone layout's live numbers (drawer heights, animation, swipe distance); absent: the defaults. */
64
68
  readonly phoneLayout?: PhoneLayoutSettings;
69
+ /** The font and size of every label (the look `labels`), carried to them as CSS variables on the root; absent: the stylesheet's own. */
70
+ readonly labelStyle?: {
71
+ readonly fontFamily: string;
72
+ readonly sizePx: number;
73
+ };
65
74
  /** The family of moons lit up in the scene now (the moon panel's choice), or null; the app draws it. */
66
75
  readonly highlightedFamily?: string | null;
67
76
  readonly onHighlightFamily?: (familyId: string | null) => void;
@@ -70,10 +79,11 @@ interface Props {
70
79
  /** Asks the shell to open a panel (a scene marker was pressed); a new `serial` asks again. */
71
80
  readonly panelRequest?: {
72
81
  readonly id: string;
73
- readonly serial: number;
82
+ readonly serial: number; /** True: the host's `setPanel` (id "" closes the open panel). */
83
+ readonly host?: boolean;
74
84
  } | null;
75
- /** Called when the open panel changes, so the app can mark its scene marker. */
76
- readonly onOpenPanelChange?: (panelId: string | null) => void;
85
+ /** Called when the open panel changes, with who changed it, so the app can mark its scene marker and tell the host. */
86
+ readonly onOpenPanelChange?: (panelId: string | null, cause: PanelCause) => void;
77
87
  /** Asks the shell to open a tagged place's information (a place marker was pressed); a new `serial` asks again. */
78
88
  readonly featureRequest?: {
79
89
  readonly key: string;
@@ -86,6 +96,7 @@ interface Props {
86
96
  readonly selectRequest?: {
87
97
  readonly id: string;
88
98
  readonly serial: number;
99
+ readonly quiet?: boolean;
89
100
  } | null;
90
101
  readonly onSelectRequestApplied?: () => void;
91
102
  readonly pickRequest?: {
@@ -95,5 +106,5 @@ interface Props {
95
106
  readonly children: ReactNode;
96
107
  }
97
108
  /** Canvas-first layout shared by astronomy experiences. Scene and diagnostics stay app-owned. */
98
- export declare function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onCameraHold, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout, highlightedFamily, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }: Props): import("react").JSX.Element;
109
+ export declare function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onTurnToFigure, onCameraHold, onTimeShown, 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;
99
110
  export {};
@@ -3,16 +3,20 @@ 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 { shownAt } from "../app/viewHiding.js";
19
+ import { availableObjectById, findCameraPreset, firstAvailableObject, focusPresetFor, isObjectAvailable, skyFigureById } from "./objectModel.js";
16
20
  import "./controls.css";
17
21
  import "./style.css";
18
22
  import "./phone.css";
@@ -35,8 +39,9 @@ function useTimelineSpace(root, phone) {
35
39
  /** The object selected when the shell opens: the first one available at the clock time, else the first listed. */
36
40
  export function initialObjectId(experience, timeUtcMs) {
37
41
  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;
42
+ const startId = start === undefined ? undefined : requestObjectId(start);
43
+ if (startId !== undefined && experience.objects.some((object) => object.id === startId))
44
+ return startId;
40
45
  return firstAvailableObject(experience, timeUtcMs)?.id ?? experience.objects[0]?.id ?? "";
41
46
  }
42
47
  /** The story-panel settings the experience carries itself, used when the app gives none live. */
@@ -62,8 +67,15 @@ function MoonsSheet({ planetLabel, open, onToggle, onClose, children }) {
62
67
  }
63
68
  /** The serial of a request that is asked again by sending a new one; absent request: undefined. */
64
69
  /** Whether the selection has been lost and a fallback must take its place: the object is gone or not available now, unless the host cleared the selection on purpose. */
65
- function selectionLost(selected, timeUtcMs, clearedByHost) {
66
- return !clearedByHost && (selected === undefined || !isObjectAvailable(selected, timeUtcMs));
70
+ function selectionLost(selected, timeUtcMs, clearedByHost, isFigure) {
71
+ // A selected sky figure is never lost: it has no availability and no view hides it.
72
+ return !clearedByHost && !isFigure && (selected === undefined || !isObjectAvailable(selected, timeUtcMs));
73
+ }
74
+ /** What a camera preset's object asks of the camera at `timeUtcMs`: "hold" when its shown time has ended or not begun (keep the pose), "overview" when it is gone or unavailable, else undefined. */
75
+ function cameraTargetLoss(target, timeUtcMs) {
76
+ if (target !== undefined && !shownAt(target, timeUtcMs))
77
+ return "hold";
78
+ return target === undefined || !isObjectAvailable(target, timeUtcMs) ? "overview" : undefined;
67
79
  }
68
80
  function serialOf(request) {
69
81
  return request?.serial;
@@ -82,21 +94,44 @@ function useViewSwitch(viewCamera) {
82
94
  function panelsOf(storySet) {
83
95
  return storySet?.panels ?? [];
84
96
  }
97
+ /** Back and Next for the open panel when it is a step: each is absent where there is no neighbour. */
98
+ function stepNavOf(panel, steps, open) {
99
+ if (panel === null || !("step" in panel))
100
+ return undefined;
101
+ const to = (by) => {
102
+ const neighbour = neighbourStep(steps, panel, by);
103
+ return neighbour === undefined ? undefined : () => open(neighbour.id);
104
+ };
105
+ return { number: panel.step, count: steps.length, onBack: to(-1), onNext: to(1) };
106
+ }
107
+ /** A request to open a panel (a marker press or the host's `setPanel`; id "" closes the open one), told with who made it. */
108
+ function applyPanelRequest(story, request) {
109
+ if (request === null || request === undefined)
110
+ return;
111
+ const by = request.host === true ? "host" : "visitor";
112
+ if (request.id === "")
113
+ story.close(by);
114
+ else
115
+ story.open(request.id, by);
116
+ }
117
+ function stepsOf(storySet) {
118
+ return storySet?.steps ?? [];
119
+ }
85
120
  function objectLabelOr(experience, objectId, fallback) {
86
- return experience.objects.find((object) => object.id === objectId)?.label ?? fallback;
121
+ return experience.objects.find((object) => object.id === objectId)?.label ?? skyFigureById(experience, objectId)?.label ?? fallback;
87
122
  }
88
123
  /** The information panel's content and, for an object, its live measurements. */
89
124
  function infoContent(experience, info, selectedObjectId, timeUtcMs, metricsFor) {
90
125
  const view = info === null
91
126
  ? null
92
127
  : infoView(experience, info.kind === "object" ? { kind: "object", id: selectedObjectId } : info, timeUtcMs);
93
- const metrics = view?.target.kind === "object" && metricsFor !== undefined ? metricsFor(view.target.id, timeUtcMs) : [];
128
+ const metrics = view?.target.kind === "object" && metricsFor !== undefined && skyFigureById(experience, view.target.id) === undefined ? metricsFor(view.target.id, timeUtcMs) : [];
94
129
  return { view, metrics };
95
130
  }
96
131
  /** The moon families load on demand: only an experience with `moonFamilies` draws them (I-089). */
97
132
  const MoonFamilyPanel = lazy(() => import("./MoonFamilyPanel.js").then((module) => ({ default: module.MoonFamilyPanel })));
98
133
  /** Canvas-first layout shared by astronomy experiences. Scene and diagnostics stay app-owned. */
99
- export function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onCameraHold, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout = DEFAULT_PHONE_LAYOUT, highlightedFamily = null, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }) {
134
+ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onTurnToFigure, onCameraHold, onTimeShown, 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, }) {
100
135
  const infoPanelId = `${useId()}-info-panel`;
101
136
  const [selectedObjectId, setSelectedObjectId] = useState(() => initialObjectId(experience, snapshot.timeUtcMs));
102
137
  const phone = usePhone();
@@ -116,17 +151,23 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
116
151
  const [info, setInfo] = useState(null);
117
152
  const storySet = experience.storyPanels;
118
153
  const storyPanels = panelsOf(storySet);
119
- const story = useStoryPanels(storyPanels, storyPanelSettings ?? ownStorySettings(storySet), snapshot, onSetPlaying);
154
+ const storySteps = stepsOf(storySet);
155
+ const story = useStoryPanels(storyPanels, storySteps, storyPanelSettings ?? ownStorySettings(storySet), snapshot, onSetPlaying);
120
156
  if (storySeekNote !== undefined)
121
157
  storySeekNote.current = story.noteSeek;
122
158
  useEffect(() => () => { if (storySeekNote !== undefined)
123
159
  storySeekNote.current = null; }, [storySeekNote]);
124
160
  const openPanelId = story.openPanel?.id ?? null;
125
- useEffect(() => { onOpenPanelChange?.(openPanelId); }, [onOpenPanelChange, openPanelId]);
161
+ const storyCause = story.cause;
162
+ // Only a change of the open panel is reported; the cause read then is the one that change came with.
163
+ const lastCause = useRef(storyCause);
164
+ lastCause.current = storyCause;
165
+ useEffect(() => { onOpenPanelChange?.(openPanelId, lastCause.current); }, [onOpenPanelChange, openPanelId]);
166
+ const closePanel = () => story.close();
167
+ const stepNav = stepNavOf(story.openPanel, storySteps, story.open);
126
168
  const requestedSerial = serialOf(panelRequest);
127
169
  useEffect(() => {
128
- if (panelRequest !== null && panelRequest !== undefined)
129
- story.open(panelRequest.id);
170
+ applyPanelRequest(story, panelRequest);
130
171
  // Only a new request opens a panel; the open function is stable.
131
172
  // eslint-disable-next-line react-hooks/exhaustive-deps
132
173
  }, [requestedSerial]);
@@ -160,7 +201,7 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
160
201
  if (selectedObjectId !== "")
161
202
  hostCleared.current = false;
162
203
  const selected = experience.objects.find((object) => object.id === selectedObjectId);
163
- if (selectionLost(selected, snapshot.timeUtcMs, hostCleared.current && selectedObjectId === "")) {
204
+ if (selectionLost(selected, snapshot.timeUtcMs, hostCleared.current && selectedObjectId === "", skyFigureById(experience, selectedObjectId) !== undefined)) {
164
205
  const fallbackId = firstAvailableObject(experience, snapshot.timeUtcMs)?.id ?? "";
165
206
  setSelectedObjectId(fallbackId);
166
207
  onSelectionChange(fallbackId, "move");
@@ -168,22 +209,19 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
168
209
  if (switchRule !== undefined && selected === undefined)
169
210
  setInfo((now) => (now?.kind === "object" ? null : now));
170
211
  }
212
+ onTimeShown?.(snapshot.timeUtcMs);
171
213
  const active = experience.cameraPresets.find((preset) => preset.id === activePresetId);
172
214
  const activeRequest = active?.request;
173
215
  if (switchRule?.rule === "start" && switchRule.framing?.always === true) {
174
216
  applyViewRule(switchRule); // opted in: the view's framing applies on every switch to it
175
217
  }
176
218
  else if (activeRequest !== undefined && activeRequest.kind !== "overview") {
177
- const target = experience.objects.find((object) => object.id === activeRequest.target);
219
+ const target = experience.objects.find((object) => object.id === requestObjectId(activeRequest));
178
220
  if (switchRule !== undefined && target === undefined) {
179
221
  applyViewRule(switchRule);
180
222
  }
181
- else if (target === undefined || !isObjectAvailable(target, snapshot.timeUtcMs)) {
182
- const overview = findCameraPreset(experience, "overview");
183
- if (overview !== undefined) {
184
- setActivePresetId(overview.id);
185
- onCameraRequest(overview.request);
186
- }
223
+ else {
224
+ loseCameraTarget(cameraTargetLoss(target, snapshot.timeUtcMs));
187
225
  }
188
226
  }
189
227
  // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -196,15 +234,31 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
196
234
  hostCleared.current = selectRequest.id === "";
197
235
  setSelectedObjectId(selectRequest.id);
198
236
  // As a visitor's menu choice does: the object's card opens (the camera is left alone); a clear closes it.
199
- setInfo((now) => (selectRequest.id === "" ? (now?.kind === "object" ? null : now) : { kind: "object" }));
237
+ // 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.
238
+ const opens = selectRequest.quiet === true ? pickOpensInfo(phone) : true;
239
+ setInfo((now) => (selectRequest.id === "" ? (now?.kind === "object" ? null : now) : opens ? { kind: "object" } : now));
200
240
  onSelectRequestApplied?.();
201
241
  // Only a new request applies.
202
242
  // eslint-disable-next-line react-hooks/exhaustive-deps
203
243
  }, [requestedSelectSerial]);
244
+ /** The camera's object is gone or not shown: "hold" keeps the pose and stops following (its shown time ended or has not begun, no jump); "overview" frames the overview. */
245
+ const loseCameraTarget = (loss) => {
246
+ if (loss === "hold") {
247
+ setActivePresetId(null);
248
+ onCameraHold?.();
249
+ }
250
+ else if (loss === "overview") {
251
+ const overview = findCameraPreset(experience, "overview");
252
+ if (overview !== undefined) {
253
+ setActivePresetId(overview.id);
254
+ onCameraRequest(overview.request);
255
+ }
256
+ }
257
+ };
204
258
  /** 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. */
205
259
  const applyViewRule = (rule) => {
206
260
  const asked = presetForViewRule(rule, experience);
207
- const target = asked === undefined || asked.request.kind === "overview" ? undefined : availableObjectById(experience, asked.request.target, snapshot.timeUtcMs);
261
+ const target = asked === undefined || asked.request.kind === "overview" ? undefined : availableObjectById(experience, requestObjectId(asked.request) ?? "", snapshot.timeUtcMs);
208
262
  // A framing whose object is not available now falls back to the overview, like any other lost target.
209
263
  const preset = asked !== undefined && asked.request.kind !== "overview" && target === undefined ? findCameraPreset(experience, "overview") : asked;
210
264
  if (target !== undefined) {
@@ -231,7 +285,10 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
231
285
  /** 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. */
232
286
  const pickObject = (id) => {
233
287
  const object = availableObjectById(experience, id, snapshot.timeUtcMs);
234
- if (object !== undefined) {
288
+ if (skyFigureById(experience, id) !== undefined) {
289
+ selectFigure(id, pickOpensInfo(phone));
290
+ }
291
+ else if (object !== undefined) {
235
292
  activatePreset(focusPresetFor(experience, object));
236
293
  if (pickOpensInfo(phone))
237
294
  setInfo({ kind: "object" });
@@ -246,7 +303,18 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
246
303
  // Only a new request flies; the handler reads the current time and experience.
247
304
  // eslint-disable-next-line react-hooks/exhaustive-deps
248
305
  }, [requestedPickSerial]);
306
+ /** 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. */
307
+ const selectFigure = (id, open) => {
308
+ setSelectedObjectId(id);
309
+ onSelectionChange(id, "visitor");
310
+ if (open)
311
+ setInfo({ kind: "object" });
312
+ };
249
313
  const selectObject = (id) => {
314
+ if (skyFigureById(experience, id) !== undefined) {
315
+ selectFigure(id, true);
316
+ return;
317
+ }
250
318
  const object = availableObjectById(experience, id, snapshot.timeUtcMs);
251
319
  if (object === undefined)
252
320
  return;
@@ -270,8 +338,9 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
270
338
  }
271
339
  };
272
340
  const activatePreset = (preset, atUtcMs = snapshot.timeUtcMs) => {
273
- if (preset.request.kind !== "overview") {
274
- const target = availableObjectById(experience, preset.request.target, atUtcMs);
341
+ const objectId = requestObjectId(preset.request);
342
+ if (objectId !== undefined) {
343
+ const target = availableObjectById(experience, objectId, atUtcMs);
275
344
  if (target === undefined)
276
345
  return;
277
346
  setSelectedObjectId(target.id);
@@ -286,6 +355,11 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
286
355
  const object = event.object === undefined ? undefined : availableObjectById(experience, event.object, event.timeUtcMs);
287
356
  if (object !== undefined)
288
357
  activatePreset(focusPresetFor(experience, object), event.timeUtcMs);
358
+ // A sky figure is selected (its card stays as it is) and turned toward only while the camera looks out.
359
+ else if (event.object !== undefined && skyFigureById(experience, event.object) !== undefined) {
360
+ selectFigure(event.object, false);
361
+ onTurnToFigure?.(event.object);
362
+ }
289
363
  if (info?.kind === "event")
290
364
  setInfo({ kind: "event", id: event.id });
291
365
  };
@@ -306,5 +380,5 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
306
380
  const selectedLabel = objectLabelOr(experience, selectedObjectId, "Controls");
307
381
  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 }));
308
382
  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 }) }) }));
309
- 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 })] }));
383
+ 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 })] }));
310
384
  }