astraeus 0.8.1 → 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 (121) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +28 -15
  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 +27 -5
  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/planCamera.d.ts +35 -7
  17. package/src/api/planCamera.js +94 -11
  18. package/src/api/planSkyFigures.d.ts +22 -0
  19. package/src/api/planSkyFigures.js +145 -0
  20. package/src/api/planStory.d.ts +2 -2
  21. package/src/api/planStory.js +14 -9
  22. package/src/api/planViews.js +1 -1
  23. package/src/api/scene.d.ts +17 -4
  24. package/src/api/scene.js +23 -5
  25. package/src/api/sceneReads.d.ts +21 -2
  26. package/src/api/skyFigureInput.d.ts +45 -0
  27. package/src/api/skyFigureInput.js +1 -0
  28. package/src/api/skyTraceInput.d.ts +33 -0
  29. package/src/api/skyTraceInput.js +45 -0
  30. package/src/api/story.d.ts +12 -3
  31. package/src/api/story.js +44 -1
  32. package/src/api/viewerCamera.d.ts +4 -3
  33. package/src/api/viewerCamera.js +10 -32
  34. package/src/api/viewerHandle.d.ts +27 -4
  35. package/src/api/viewerHandle.js +6 -0
  36. package/src/api/viewerLink.d.ts +49 -4
  37. package/src/api/viewerLink.js +25 -0
  38. package/src/api/viewerPanels.d.ts +26 -0
  39. package/src/api/viewerPanels.js +42 -0
  40. package/src/api/viewerSelection.d.ts +1 -1
  41. package/src/api/viewerSelection.js +3 -3
  42. package/src/app/App.js +100 -18
  43. package/src/app/App.node.js +100 -18
  44. package/src/app/AstraeusScene.d.ts +20 -5
  45. package/src/app/AstraeusScene.js +3 -3
  46. package/src/app/CameraController.d.ts +17 -0
  47. package/src/app/CameraController.js +34 -9
  48. package/src/app/DeveloperSettings.d.ts +11 -3
  49. package/src/app/DeveloperSettings.js +13 -3
  50. package/src/app/SceneLabels.d.ts +20 -2
  51. package/src/app/SceneLabels.js +46 -6
  52. package/src/app/SkyFiguresView.d.ts +56 -0
  53. package/src/app/SkyFiguresView.js +242 -0
  54. package/src/app/StoryMarkers.d.ts +2 -2
  55. package/src/app/StoryMarkers.js +2 -2
  56. package/src/app/displaySwitches.d.ts +13 -3
  57. package/src/app/displaySwitches.js +17 -3
  58. package/src/app/experienceDefinition.d.ts +9 -3
  59. package/src/app/experienceDefinition.js +4 -2
  60. package/src/app/labelStyle.d.ts +17 -0
  61. package/src/app/labelStyle.js +13 -0
  62. package/src/app/liveLook.js +8 -0
  63. package/src/app/look.d.ts +9 -5
  64. package/src/app/look.js +11 -0
  65. package/src/app/lookOut.d.ts +32 -0
  66. package/src/app/lookOut.js +50 -0
  67. package/src/app/sceneCamera.d.ts +5 -3
  68. package/src/app/sceneCamera.js +66 -3
  69. package/src/app/sceneContentsHooks.d.ts +2 -1
  70. package/src/app/sceneContentsHooks.js +3 -2
  71. package/src/app/sceneFrame.d.ts +10 -1
  72. package/src/app/sceneFrame.js +45 -10
  73. package/src/app/sceneFraming.d.ts +7 -0
  74. package/src/app/sceneFraming.js +12 -0
  75. package/src/app/sceneHooks.d.ts +2 -0
  76. package/src/app/sceneHooks.js +4 -1
  77. package/src/app/scenePicking.d.ts +20 -0
  78. package/src/app/scenePicking.js +49 -0
  79. package/src/app/scenePointer.d.ts +3 -1
  80. package/src/app/scenePointer.js +3 -2
  81. package/src/app/skyFigures.d.ts +73 -0
  82. package/src/app/skyFigures.js +50 -0
  83. package/src/app/style.css +2 -1
  84. package/src/app/viewHiding.d.ts +2 -0
  85. package/src/app/viewHiding.js +7 -1
  86. package/src/app/viewLink.d.ts +8 -8
  87. package/src/app/viewLink.js +24 -4
  88. package/src/app/viewerPort.d.ts +30 -3
  89. package/src/assets/sky.d.ts +13 -4
  90. package/src/assets/sky.js +33 -8
  91. package/src/assets/stars/hyg-v42-naked-eye.json +1 -1
  92. package/src/core/bodies/moonSystem.js +1 -15
  93. package/src/core/lookValues.d.ts +9 -0
  94. package/src/core/lookValues.js +24 -0
  95. package/src/core/readBytes.d.ts +1 -0
  96. package/src/core/readBytes.js +15 -0
  97. package/src/core/skyTrace.d.ts +49 -0
  98. package/src/core/skyTrace.js +39 -0
  99. package/src/core/startView.d.ts +39 -0
  100. package/src/core/startView.js +56 -0
  101. package/src/core/storyPanels.d.ts +51 -3
  102. package/src/core/storyPanels.js +52 -12
  103. package/src/shell/AstraeusShell.d.ts +15 -6
  104. package/src/shell/AstraeusShell.js +76 -20
  105. package/src/shell/AstraeusShell.node.js +76 -20
  106. package/src/shell/ObjectControls.js +11 -8
  107. package/src/shell/StoryPanelView.d.ts +12 -3
  108. package/src/shell/StoryPanelView.js +2 -2
  109. package/src/shell/experience.d.ts +24 -0
  110. package/src/shell/experience.js +4 -1
  111. package/src/shell/infoModel.js +9 -1
  112. package/src/shell/objectModel.d.ts +6 -2
  113. package/src/shell/objectModel.js +10 -1
  114. package/src/shell/phone.css +1 -1
  115. package/src/shell/storyPanels.d.ts +1 -1
  116. package/src/shell/storyPanels.js +1 -1
  117. package/src/shell/style.css +9 -1
  118. package/src/shell/topBarIcons.d.ts +1 -0
  119. package/src/shell/topBarIcons.js +1 -0
  120. package/src/shell/useStoryPanels.d.ts +9 -6
  121. package/src/shell/useStoryPanels.js +10 -6
package/src/app/App.js CHANGED
@@ -4,6 +4,7 @@ import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
4
4
  import { viewUpFromSearch, viewUpVector } from "./viewUp.js";
5
5
  import { activeEventZones, applyPacing, startPaceEase } from "../core/pacing.js";
6
6
  import { openClock } from "./openClock.js";
7
+ import { createProvenance } from "../core/provenance.js";
7
8
  import { pickerSwitch } from "./listSwitch.js";
8
9
  import { createSolarSystemScale } from "../core/scalePolicy.js";
9
10
  import { bodySetsOf, cameraReachOf, catalogueOf, compositionOf, experienceWithGroups, groupsOf, initialObjectIdOf, mountedBodiesOf, pageTitleOf, scaleChoiceIdsOf, sceneCenterOf, sunCentredOf, trackedBodiesOf, visualOverridesOf } from "./experienceDefinition.js";
@@ -30,7 +31,10 @@ import { loadStarCatalogue } from "../assets/sky.js";
30
31
  import { withSkyObject } from "./skyModel.js";
31
32
  import { ORBIT_LOOK_LIMITS, resolveOrbitLook } from "../assets/orbitLook.js";
32
33
  import { DEFAULT_BODY_SET_LOOK } from "./bodySet.js";
33
- import { displaySwitchItems, hostReachable, orbitStart } from "./displaySwitches.js";
34
+ import { displaySwitchItems, hostReachable, orbitStart, skyLineStart } from "./displaySwitches.js";
35
+ import { TRACE_FADE_SECONDS } from "../core/skyTrace.js";
36
+ import { aimAtFigure, DEFAULT_SKY_LINES, prefersReducedMotion, skyColoursOf, skyFadeInSecondsOf } from "./skyFigures.js";
37
+ import { labelStyleOf } from "./labelStyle.js";
34
38
  import { experienceInView, hiddenByView, viewById } from "./viewHiding.js";
35
39
  import { baseGlowOf, glowLookOf, markerSettingsOf } from "./bodyDraw.js";
36
40
  import { resolveLook } from "./look.js";
@@ -57,6 +61,14 @@ export function loopFromSearch(search, fallback) {
57
61
  return value === "on" ? true : value === "off" ? false : fallback;
58
62
  }
59
63
  /** The scene view showing at the start: `?show=<id>` when it names one of the scene's views, else the scene's own `start` (an unknown id is not an error). */
64
+ const NO_CARD_PROVENANCE = createProvenance({ sourceType: "illustrative", sources: ["Supplied by the caller"], accuracy: "As supplied; the engine makes no claim.", notes: "" });
65
+ /** The sky figures as the host link reads them: each drawn figure with its card words (`experience.skyFigures`). */
66
+ function skyFigureReads(layers, cards) {
67
+ return layers.map(({ id, label, kind }) => {
68
+ const card = cards?.find((candidate) => candidate.id === id); // a hand-written definition may draw a figure with no card: it then reads as listed, with the default provenance
69
+ return Object.freeze({ id, label, kind, listed: card?.listed ?? true, provenance: card?.provenance ?? NO_CARD_PROVENANCE, ...(card?.description === undefined ? {} : { description: card.description }), ...(card?.facts === undefined ? {} : { facts: card.facts }) });
70
+ });
71
+ }
60
72
  function startViewId(definition, search) {
61
73
  const asked = showFromSearch(search);
62
74
  const known = asked !== undefined && definition.views?.views.some((view) => view.id === asked) === true;
@@ -113,6 +125,7 @@ function buildRuntime(definition, search) {
113
125
  trackedBodies: trackedBodiesOf(definition),
114
126
  groups: groupsOf(definition),
115
127
  bodySets: bodySetsOf(definition),
128
+ skyFigures: definition.skyFigures ?? [],
116
129
  ...sunCentredOf(definition),
117
130
  cameraReach: cameraReachOf(definition),
118
131
  look,
@@ -133,17 +146,22 @@ function showsDisplayControls(definition, runtime, skyVisible, orbitPathCount, s
133
146
  return orbitPathCount > 0 || runtime.trackedBodies.length > 0 || skyVisible || storyMarkerCount > 0 || (definition.experience.storyPanels?.panels.length ?? 0) > 0
134
147
  || runtime.bodies.some((id) => runtime.catalogue.get(id).visual.kind === "sphere");
135
148
  }
136
- /** The camera as the scene opens it (the start view, else its default framing): what a host reads before the scene's first frame writes `viewReadout`. */
149
+ /**
150
+ * The camera as the scene opens it (the start view, else its default framing): what a host reads before the scene's first frame writes `viewReadout`.
151
+ * Undefined for a look-out toward an id: its direction is known only once the first frame resolves it, and a guess would be a false reading.
152
+ */
137
153
  function openingCamera(definition, runtime, search) {
138
154
  const start = viewFromSearch(search) ?? definition.startView;
139
155
  if (start !== undefined)
140
- return start;
156
+ return "kind" in start ? undefined : start;
141
157
  const opening = createOrbitCameraState(START_CAMERA_DISTANCE, runtime.sceneCenter);
142
158
  return viewFromAngles(opening.focus, opening.azimuth, opening.elevation, opening.distance);
143
159
  }
144
160
  /** The scene's live controls at mount: the address overrides the experience's own start values. */
145
161
  function initialSceneControls(definition, runtime, experience, startScale, glowBase, storyMarkers, suppliedPolicies, search) {
146
- const startView = viewFromSearch(search) ?? definition.startView;
162
+ // A look-out toward an id is aimed as a `setCamera` one is: a sky figure becomes its label point here, an object is turned toward on the first frame.
163
+ const opening = definition.startView;
164
+ const startView = viewFromSearch(search) ?? (opening !== undefined && "kind" in opening ? aimAtFigure(opening, runtime.skyFigures) : opening);
147
165
  return {
148
166
  policy: scalePolicyFor(startScale, suppliedPolicies),
149
167
  cameraRequest: null,
@@ -152,6 +170,11 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
152
170
  ...(definition.pacing === undefined ? {} : { paceAuto: true, pace: { shown: shownEventsOf(definition, startViewId(definition, search)) } }),
153
171
  up: viewUpVector(startViewUp(definition, search)),
154
172
  showMilkyWay: runtime.sky.milkyWay,
173
+ skyLines: skyLineStart(definition.displaySwitches, DEFAULT_SKY_LINES),
174
+ skyColours: skyColoursOf(runtime.look),
175
+ skyTraces: [],
176
+ skyFadeInSeconds: skyFadeInSecondsOf(runtime.look),
177
+ labelStyle: labelStyleOf(runtime.look),
155
178
  skyVisible: runtime.sky.visible,
156
179
  bodyMarker: markerSettingsOf(runtime.look),
157
180
  ...(glowBase === null ? {} : { glowLook: glowLookOf(runtime.look, glowBase) }),
@@ -230,7 +253,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
230
253
  const metricsFor = useMemo(() => definition.createMetrics(experienceRuntime), [definition, experienceRuntime]);
231
254
  const glowBase = useMemo(() => baseGlowOf(runtime.bodies.map((id) => runtime.catalogue.get(id))), [runtime]);
232
255
  const storySet = definition.experience.storyPanels;
233
- const storyMarkerSpecs = useMemo(() => (storySet?.panels ?? []).flatMap((panel) => (panel.objectId === undefined ? [] : [{ panelId: panel.id, objectId: panel.objectId, title: panel.title, timeUtcMs: panel.timeUtcMs }])), [storySet]);
256
+ const storyMarkerSpecs = useMemo(() => [...(storySet?.panels ?? []), ...(storySet?.steps ?? [])].flatMap((panel) => (panel.objectId === undefined ? [] : [{ panelId: panel.id, objectId: panel.objectId, title: panel.title, ..."timeUtcMs" in panel ? { timeUtcMs: panel.timeUtcMs } : {} }])), [storySet]);
234
257
  const controls = useRef(initialSceneControls(definition, runtime, experience, startScale, glowBase, storyMarkerSpecs, suppliedPolicies, search));
235
258
  const readout = useRef(null);
236
259
  const [clockSnapshot, setClockSnapshot] = useState(() => runtime.clock.snapshot());
@@ -239,6 +262,9 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
239
262
  const [timelineGlow, setTimelineGlow] = useState(DEFAULT_TIMELINE_GLOW);
240
263
  const [phoneLayout, setPhoneLayout] = useState(DEFAULT_PHONE_LAYOUT);
241
264
  const [anchorLabels, setAnchorLabels] = useState(controls.current.showAnchorLabels);
265
+ const [skyLinesShown, setSkyLinesShown] = useState(controls.current.skyLines);
266
+ const [skyColoursShown, setSkyColoursShown] = useState(controls.current.skyColours);
267
+ const [labelStyleShown, setLabelStyleShown] = useState(controls.current.labelStyle);
242
268
  const [glowShown, setGlowShown] = useState(copyOfGlow(controls.current.glowLook));
243
269
  const orbitPaths = orbitPathsOf(runtime);
244
270
  const orbitDefault = useMemo(() => resolveOrbitLook(orbitPaths[0]?.look), [orbitPaths]);
@@ -286,14 +312,18 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
286
312
  const [viewLink, setViewLink] = useState(null);
287
313
  const [fills, setFills] = useState([]);
288
314
  const updateCameraRequest = useCallback((request) => {
289
- controls.current.cameraRequest = request;
290
- }, []);
315
+ controls.current.cameraRequest = aimAtFigure(request, runtime.skyFigures);
316
+ }, [runtime]);
317
+ const turnToFigure = useCallback((id) => {
318
+ const now = controls.current.viewReadout;
319
+ if (now !== undefined && "lookOut" in now)
320
+ updateCameraRequest({ kind: "lookOut", body: now.lookOut, direction: id });
321
+ }, [updateCameraRequest]);
291
322
  const holdCamera = useCallback(() => { controls.current.cameraRequest = { kind: "hold" }; }, []);
292
323
  const requestPanel = useCallback((id) => setPanelRequest((previous) => ({ id, serial: (previous?.serial ?? 0) + 1 })), []);
293
324
  const requestPick = useCallback((id) => setPickRequest((previous) => ({ id, serial: (previous?.serial ?? 0) + 1 })), []);
294
325
  const requestFeature = useCallback((key) => setFeatureRequest((previous) => ({ key, serial: (previous?.serial ?? 0) + 1 })), []);
295
326
  const markOpenFeature = useCallback((key) => { controls.current.openFeatureKey = key; }, []);
296
- const markOpenPanel = useCallback((id) => { controls.current.openStoryPanelId = id; }, []);
297
327
  const setPlaying = useCallback((playing) => {
298
328
  if (playing)
299
329
  runtime.clock.play();
@@ -336,6 +366,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
336
366
  ...(runtime.eventZones === undefined ? {} : { zones: activeEventZones(runtime.eventZones, shownEventsOf(definition, viewRef.current), snapshot.timeUtcMs) }),
337
367
  ...(definition.views === undefined ? {} : { view: viewRef.current }),
338
368
  ...(controls.current.selectedObjectId === "" ? {} : { selected: controls.current.selectedObjectId }),
369
+ ...(controls.current.openStoryPanelId == null ? {} : { panel: controls.current.openStoryPanelId }),
339
370
  };
340
371
  }, [runtime, definition]);
341
372
  // A selection that changes is told to the host at once (the shell calls this for a menu choice, a pick and a view switch that drops the object); the opening selection and any before the host is attached wait for the attach reading.
@@ -346,12 +377,23 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
346
377
  // The host's `setSelected` not yet applied by the shell (id "" clears); the shell applies it after its own view-switch choices, so the host call is the last word.
347
378
  const hostSelect = useRef(null);
348
379
  const [selectRequest, setSelectRequest] = useState(null);
349
- const hostSetSelected = useCallback((id) => {
380
+ /** `quiet`: a story panel's select, which follows the visitor-tap rule for the card (the shell decides: wide screens open it, phones do not); a host call opens it always. */
381
+ const selectWith = useCallback((id, quiet) => {
350
382
  hostSelect.current = id ?? "";
351
383
  controls.current.selectedObjectId = id ?? ""; // `read()` shows it at once
352
- setSelectRequest((previous) => ({ id: id ?? "", serial: (previous?.serial ?? 0) + 1 }));
384
+ setSelectRequest((previous) => ({ id: id ?? "", serial: (previous?.serial ?? 0) + 1, ...(quiet ? { quiet } : {}) }));
353
385
  }, []);
386
+ const hostSetSelected = useCallback((id) => selectWith(id, false), [selectWith]);
354
387
  const hostSelectApplied = useCallback(() => { hostSelect.current = null; }, []);
388
+ const hostSetPanel = useCallback((id) => {
389
+ controls.current.openStoryPanelId = id ?? null; // `read()` shows it at once
390
+ setPanelRequest((previous) => ({ id: id ?? "", serial: (previous?.serial ?? 0) + 1, host: true }));
391
+ }, []);
392
+ const panelIds = useCallback(() => {
393
+ const set = definition.experience.storyPanels;
394
+ const hidden = controls.current.viewHidden?.panels;
395
+ return [...(set?.panels ?? []), ...(set?.steps ?? [])].map(({ id }) => id).filter((id) => hidden === undefined || !hidden.has(id));
396
+ }, [definition]);
355
397
  const updateSelectedObject = useCallback((objectId, origin) => {
356
398
  if (hostSelect.current !== null)
357
399
  return; // a host `setSelected` is waiting for the shell: the shell's older choice must not undo it (the host-call order rule)
@@ -415,23 +457,57 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
415
457
  }, [experience]);
416
458
  const opening = useMemo(() => openingCamera(definition, runtime, search), []); // eslint-disable-line react-hooks/exhaustive-deps
417
459
  const readCamera = useCallback(() => {
418
- return { ...(controls.current.viewReadout ?? opening) };
460
+ const view = controls.current.viewReadout ?? opening;
461
+ return view === undefined ? undefined : { ...view };
419
462
  }, [opening]);
420
463
  // A host camera call is the last word: it is also kept in `hostCameraRequest`, so the opening view (first frame) and a view's own camera rule (shell) yield to it.
421
- const setCamera = useCallback((request) => { controls.current.cameraRequest = controls.current.hostCameraRequest = request; }, []);
464
+ const setCamera = useCallback((request) => { controls.current.cameraRequest = controls.current.hostCameraRequest = aimAtFigure(request, runtime.skyFigures); }, [runtime]);
422
465
  const hostCameraSet = useCallback(() => controls.current.hostCameraRequest != null, []);
423
466
  const hostScales = useMemo(() => scaleChoiceIds ?? SCALE_CHOICES.map((choice) => choice.id), [scaleChoiceIds]);
424
467
  const hostSetLook = useCallback((look) => live.current?.setLook(look), []);
425
468
  const hostSetScale = useCallback((id) => live.current?.setScale(id), []);
469
+ const hostClearSkyTrace = useCallback((id, seconds) => { controls.current.skyTraces.push({ id, seconds, reduced: prefersReducedMotion() }); }, []);
470
+ const hostTraceSkyFigure = useCallback((id, seconds, after) => { controls.current.skyTraces.push({ id, seconds, after, reduced: prefersReducedMotion() }); }, []);
426
471
  const hostSetSwitch = useCallback((id, on) => live.current?.setSwitch(id, on), []);
472
+ /** The figure the open story panel traced when it opened; it is cleared (default fade) when the panel is left. */
473
+ const panelTrace = useRef(null);
474
+ /** The panel whose actions were last applied (a host `setPanel` shows its panel at once, so `openStoryPanelId` cannot say whether the shell has opened it yet). */
475
+ const actedPanel = useRef(null);
476
+ /** The shell's open panel changed (a visitor, a host call already shown, playback crossing a panel, or a view switch dropping it); a change is told to the host, the opening panel is read at attach. */
477
+ const markOpenPanel = useCallback((id, cause) => {
478
+ const changed = (controls.current.openStoryPanelId ?? null) !== id;
479
+ controls.current.openStoryPanelId = id;
480
+ if (changed && hostAttached.current)
481
+ host?.publishPanel(stateNow(), cause);
482
+ if (actedPanel.current === id)
483
+ return;
484
+ actedPanel.current = id;
485
+ // Leaving a panel clears the trace it started; what a host or visitor did since is left as it is.
486
+ if (panelTrace.current !== null)
487
+ hostClearSkyTrace(panelTrace.current, TRACE_FADE_SECONDS);
488
+ panelTrace.current = null;
489
+ const set = definition.experience.storyPanels;
490
+ const panel = id === null ? undefined : [...(set?.panels ?? []), ...(set?.steps ?? [])].find((candidate) => candidate.id === id);
491
+ if (panel === undefined)
492
+ return;
493
+ // The panel's actions go through the host calls, in this order: camera, select, trace.
494
+ if (panel.camera !== undefined)
495
+ setCamera(panel.camera);
496
+ if (panel.select === true && panel.objectId !== undefined)
497
+ selectWith(panel.objectId, true);
498
+ if (panel.trace !== undefined && panel.objectId !== undefined) {
499
+ hostTraceSkyFigure(panel.objectId, panel.trace.seconds, panel.trace.after);
500
+ panelTrace.current = panel.objectId;
501
+ }
502
+ }, [host, stateNow, definition, setCamera, selectWith, hostTraceSkyFigure, hostClearSkyTrace]);
427
503
  useEffect(() => {
428
504
  if (host === undefined)
429
505
  return undefined;
430
506
  hostAttached.current = true;
431
507
  shownKey.current = null; // the presentation is read afresh after each attach
432
- host.attach({ ...(definition.picker === undefined ? {} : { picker: { id: definition.picker.id, values: definition.picker.options.map((option) => option.value), start: definition.picker.value } }), window: runtime.loopWindow, events: experience.events, rates: definition.experience.rates, paced: runtime.pacing !== undefined, read: stateNow, seek: hostSeekTo, setRate: changeRate, playable: definition.experience.hideTimeline !== true, setPlaying: hostSetPlaying, views: viewIds, setView: chooseView, cameraTargets, readCamera, setCamera, setSelected: hostSetSelected, scales: hostScales, setScale: hostSetScale, setLook: hostSetLook, setSwitch: hostSetSwitch });
508
+ host.attach({ ...(definition.picker === undefined ? {} : { picker: { id: definition.picker.id, values: definition.picker.options.map((option) => option.value), start: definition.picker.value } }), window: runtime.loopWindow, skyFigures: skyFigureReads(runtime.skyFigures, experience.skyFigures), events: experience.events, rates: definition.experience.rates, paced: runtime.pacing !== undefined, read: stateNow, seek: hostSeekTo, setRate: changeRate, playable: definition.experience.hideTimeline !== true, setPlaying: hostSetPlaying, views: viewIds, setView: chooseView, cameraTargets, readCamera, setCamera, setSelected: hostSetSelected, panels: panelIds, setPanel: hostSetPanel, scales: hostScales, setScale: hostSetScale, setLook: hostSetLook, setSwitch: hostSetSwitch, traceSkyFigure: hostTraceSkyFigure, clearSkyTrace: hostClearSkyTrace });
433
509
  return () => { hostAttached.current = false; host.detach(); };
434
- }, [host, runtime, definition, hostSeekTo, changeRate, viewIds, chooseView, cameraTargets, readCamera, setCamera, hostSetSelected, experience, hostSetPlaying, hostScales, hostSetScale, hostSetLook, hostSetSwitch]);
510
+ }, [host, runtime, definition, hostSeekTo, changeRate, viewIds, chooseView, cameraTargets, readCamera, setCamera, hostSetSelected, panelIds, hostSetPanel, experience, hostSetPlaying, hostScales, hostSetScale, hostSetLook, hostSetSwitch, hostTraceSkyFigure, hostClearSkyTrace]);
435
511
  useEffect(() => {
436
512
  if (!developerMode)
437
513
  return undefined;
@@ -472,6 +548,10 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
472
548
  settings: definition.displaySwitches,
473
549
  orbit: { present: orbitPaths.length > 0, look: { ...orbitDefault, ...controls.current.orbitLook }, set: setOrbit },
474
550
  moons: { present: bodySets.length > 0, look: controls.current.bodySetLook ?? DEFAULT_BODY_SET_LOOK, set: changeSetLook },
551
+ skyLines: {
552
+ figures: runtime.skyFigures.some(({ kind }) => kind === "figure"), boundaries: runtime.skyFigures.some(({ kind }) => kind === "boundary"), on: controls.current.skyLines,
553
+ set: (key, on) => { controls.current.skyLines = { ...controls.current.skyLines, [key]: on }; setSkyLinesShown(controls.current.skyLines); },
554
+ },
475
555
  sky: { present: controls.current.skyVisible !== false, on: controls.current.showMilkyWay, set: (on) => { controls.current.showMilkyWay = on; setMilkyWayOn(on); } },
476
556
  labels: {
477
557
  objectIds: experience.objects.map((object) => object.id), hidden: controls.current.hiddenLabels ?? hiddenLabels,
@@ -491,6 +571,8 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
491
571
  setGlowShown({ ...controls.current.glowLook });
492
572
  setMarkerPx(read.markerSwapRadiusPx);
493
573
  setLoadFade(read.loadFadeSeconds);
574
+ setSkyColoursShown(controls.current.skyColours);
575
+ setLabelStyleShown(controls.current.labelStyle);
494
576
  },
495
577
  setScale: updateScale,
496
578
  items: () => displaySwitchItems({ ...bindingsNow(), settings: hostReachable(definition.displaySwitches) }),
@@ -505,7 +587,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
505
587
  shownKey.current = key;
506
588
  if (changed)
507
589
  host?.publish(state, "visitor");
508
- }, [host, stateNow, scale, skyVisible, starBrightness, milkyWayBrightness, milkyWayOn, glowShown, markerPx, loadFade, orbitShown, setLook, hiddenLabels, anchorLabels]);
590
+ }, [host, stateNow, scale, skyVisible, starBrightness, milkyWayBrightness, milkyWayOn, glowShown, markerPx, loadFade, orbitShown, setLook, hiddenLabels, anchorLabels, skyLinesShown, skyColoursShown, labelStyleShown]);
509
591
  const hasStoryPanels = (storySet?.panels.length ?? 0) > 0;
510
592
  const showDisplay = showsDisplayControls(definition, runtime, skyVisible, orbitPaths.length, storyMarkerSpecs.length);
511
593
  // Orbit-line sliders: the first four stay in view, the rest sit in a nested "Fine-tune" fold (T-090).
@@ -557,7 +639,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
557
639
  },
558
640
  {
559
641
  id: "labels", title: "Labels",
560
- body: (_jsx(LabelSettings, { controls: controls, hoverBrightness: hoverBrightness, setHoverBrightness: setHoverBrightness, labelToggles: labelToggles, trackedCount: runtime.trackedBodies.length, anchorLabels: anchorLabels, setAnchorLabels: setAnchorLabels, hiddenLabels: hiddenLabels, setHiddenLabels: setHiddenLabels })),
642
+ body: (_jsx(LabelSettings, { controls: controls, hoverBrightness: hoverBrightness, setHoverBrightness: setHoverBrightness, labelToggles: labelToggles, trackedCount: runtime.trackedBodies.length, anchorLabels: anchorLabels, setAnchorLabels: setAnchorLabels, hiddenLabels: hiddenLabels, setHiddenLabels: setHiddenLabels, labelStyle: labelStyleShown, setLabelStyle: setLabelStyleShown, skyColours: skyColoursShown, setSkyColours: setSkyColoursShown, hasSky: skyVisible })),
561
643
  },
562
644
  !showDisplay ? null : {
563
645
  id: "phone-layout", title: "Phone layout",
@@ -576,7 +658,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
576
658
  ];
577
659
  const presentGroups = groups.filter((group) => group !== null);
578
660
  const drawer = (_jsx(PanelLoadBoundary, { children: _jsx(Suspense, { fallback: _jsx("p", { className: "developer-loading", role: "status", children: "Loading developer tools..." }), children: _jsxs("div", { className: "hud", children: [_jsxs("header", { className: "developer-heading", children: [_jsx("h2", { children: "Developer tools" }), _jsx("p", { children: "Live readouts, controls and diagnostics for this scene." })] }), presentGroups.map((group, index) => (_jsx(Collapsible, { fold: group.id, title: group.title, defaultOpen: index === 0, className: `dev-group${group.className === undefined ? "" : ` ${group.className}`}`, children: group.body }, group.id)))] }) }) }));
579
- return (_jsx(AstraeusShell, { experience: shellExperience, snapshot: clockSnapshot, paceAuto: runtime.pacing === undefined ? undefined : paceAuto, developerMode: developerMode, onDeveloperModeChange: setDeveloperMode, onTogglePlayback: () => {
661
+ return (_jsx(AstraeusShell, { experience: shellExperience, snapshot: clockSnapshot, paceAuto: runtime.pacing === undefined ? undefined : paceAuto, developerMode: developerMode, labelStyle: labelStyleShown, onDeveloperModeChange: setDeveloperMode, onTogglePlayback: () => {
580
662
  if (runtime.clock.playing)
581
663
  runtime.clock.pause();
582
664
  else
@@ -589,5 +671,5 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
589
671
  }, onSeek: (timeUtcMs) => {
590
672
  seekTo(timeUtcMs);
591
673
  host?.publish(stateNow(), "visitor");
592
- }, onCameraRequest: updateCameraRequest, onCameraHold: holdCamera, hostCameraSet: hostCameraSet, storySeekNote: storySeekNote, onSelectionChange: updateSelectedObject, scaleId: scale, onScaleChange: updateScale, scaleChoices: scaleChoices, switcher: definition.picker === undefined ? undefined : pickerSwitch(definition.picker, hostPick ?? definition.picker.value, choosePick), displaySwitches: displaySwitches, viewChoice: viewChoice, viewCamera: currentView === undefined ? undefined : { id: currentView.id, rule: currentView.camera }, metricsFor: metricsFor, developerTools: drawerWhen(developerTools, drawer), storyPanelSettings: { autoOpen: storyAutoOpen, pauseSeconds: storyPauseSeconds }, timelineGlow: timelineGlow, phoneLayout: phoneLayout, highlightedFamily: setLook.highlightFamily, onHighlightFamily: highlightFamily, onSetPlaying: setPlaying, panelRequest: panelRequest, onOpenPanelChange: markOpenPanel, featureRequest: featureRequest, pickRequest: pickRequest, selectRequest: selectRequest, onSelectRequestApplied: hostSelectApplied, onOpenFeatureChange: markOpenFeature, children: _jsx("div", { className: "canvas-host", children: _jsx(AstraeusScene, { runtime: runtime, controls: controls.current, readout: readout, scaleId: scale, onFirstDraw: host === undefined ? undefined : told }) }) }));
674
+ }, onCameraRequest: updateCameraRequest, onTurnToFigure: turnToFigure, onCameraHold: holdCamera, hostCameraSet: hostCameraSet, storySeekNote: storySeekNote, onSelectionChange: updateSelectedObject, scaleId: scale, onScaleChange: updateScale, scaleChoices: scaleChoices, switcher: definition.picker === undefined ? undefined : pickerSwitch(definition.picker, hostPick ?? definition.picker.value, choosePick), displaySwitches: displaySwitches, viewChoice: viewChoice, viewCamera: currentView === undefined ? undefined : { id: currentView.id, rule: currentView.camera }, metricsFor: metricsFor, developerTools: drawerWhen(developerTools, drawer), storyPanelSettings: { autoOpen: storyAutoOpen, pauseSeconds: storyPauseSeconds }, timelineGlow: timelineGlow, phoneLayout: phoneLayout, highlightedFamily: setLook.highlightFamily, onHighlightFamily: highlightFamily, onSetPlaying: setPlaying, panelRequest: panelRequest, onOpenPanelChange: markOpenPanel, featureRequest: featureRequest, pickRequest: pickRequest, selectRequest: selectRequest, onSelectRequestApplied: hostSelectApplied, onOpenFeatureChange: markOpenFeature, children: _jsx("div", { className: "canvas-host", children: _jsx(AstraeusScene, { runtime: runtime, controls: controls.current, readout: readout, scaleId: scale, onFirstDraw: host === undefined ? undefined : told }) }) }));
593
675
  }
@@ -4,6 +4,7 @@ import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
4
4
  import { viewUpFromSearch, viewUpVector } from "./viewUp.js";
5
5
  import { activeEventZones, applyPacing, startPaceEase } from "../core/pacing.js";
6
6
  import { openClock } from "./openClock.js";
7
+ import { createProvenance } from "../core/provenance.js";
7
8
  import { pickerSwitch } from "./listSwitch.js";
8
9
  import { createSolarSystemScale } from "../core/scalePolicy.js";
9
10
  import { bodySetsOf, cameraReachOf, catalogueOf, compositionOf, experienceWithGroups, groupsOf, initialObjectIdOf, mountedBodiesOf, pageTitleOf, scaleChoiceIdsOf, sceneCenterOf, sunCentredOf, trackedBodiesOf, visualOverridesOf } from "./experienceDefinition.js";
@@ -30,7 +31,10 @@ import { loadStarCatalogue } from "../assets/sky.js";
30
31
  import { withSkyObject } from "./skyModel.js";
31
32
  import { ORBIT_LOOK_LIMITS, resolveOrbitLook } from "../assets/orbitLook.js";
32
33
  import { DEFAULT_BODY_SET_LOOK } from "./bodySet.js";
33
- import { displaySwitchItems, hostReachable, orbitStart } from "./displaySwitches.js";
34
+ import { displaySwitchItems, hostReachable, orbitStart, skyLineStart } from "./displaySwitches.js";
35
+ import { TRACE_FADE_SECONDS } from "../core/skyTrace.js";
36
+ import { aimAtFigure, DEFAULT_SKY_LINES, prefersReducedMotion, skyColoursOf, skyFadeInSecondsOf } from "./skyFigures.js";
37
+ import { labelStyleOf } from "./labelStyle.js";
34
38
  import { experienceInView, hiddenByView, viewById } from "./viewHiding.js";
35
39
  import { baseGlowOf, glowLookOf, markerSettingsOf } from "./bodyDraw.js";
36
40
  import { resolveLook } from "./look.js";
@@ -57,6 +61,14 @@ export function loopFromSearch(search, fallback) {
57
61
  return value === "on" ? true : value === "off" ? false : fallback;
58
62
  }
59
63
  /** The scene view showing at the start: `?show=<id>` when it names one of the scene's views, else the scene's own `start` (an unknown id is not an error). */
64
+ const NO_CARD_PROVENANCE = createProvenance({ sourceType: "illustrative", sources: ["Supplied by the caller"], accuracy: "As supplied; the engine makes no claim.", notes: "" });
65
+ /** The sky figures as the host link reads them: each drawn figure with its card words (`experience.skyFigures`). */
66
+ function skyFigureReads(layers, cards) {
67
+ return layers.map(({ id, label, kind }) => {
68
+ const card = cards?.find((candidate) => candidate.id === id); // a hand-written definition may draw a figure with no card: it then reads as listed, with the default provenance
69
+ return Object.freeze({ id, label, kind, listed: card?.listed ?? true, provenance: card?.provenance ?? NO_CARD_PROVENANCE, ...(card?.description === undefined ? {} : { description: card.description }), ...(card?.facts === undefined ? {} : { facts: card.facts }) });
70
+ });
71
+ }
60
72
  function startViewId(definition, search) {
61
73
  const asked = showFromSearch(search);
62
74
  const known = asked !== undefined && definition.views?.views.some((view) => view.id === asked) === true;
@@ -113,6 +125,7 @@ function buildRuntime(definition, search) {
113
125
  trackedBodies: trackedBodiesOf(definition),
114
126
  groups: groupsOf(definition),
115
127
  bodySets: bodySetsOf(definition),
128
+ skyFigures: definition.skyFigures ?? [],
116
129
  ...sunCentredOf(definition),
117
130
  cameraReach: cameraReachOf(definition),
118
131
  look,
@@ -133,17 +146,22 @@ function showsDisplayControls(definition, runtime, skyVisible, orbitPathCount, s
133
146
  return orbitPathCount > 0 || runtime.trackedBodies.length > 0 || skyVisible || storyMarkerCount > 0 || (definition.experience.storyPanels?.panels.length ?? 0) > 0
134
147
  || runtime.bodies.some((id) => runtime.catalogue.get(id).visual.kind === "sphere");
135
148
  }
136
- /** The camera as the scene opens it (the start view, else its default framing): what a host reads before the scene's first frame writes `viewReadout`. */
149
+ /**
150
+ * The camera as the scene opens it (the start view, else its default framing): what a host reads before the scene's first frame writes `viewReadout`.
151
+ * Undefined for a look-out toward an id: its direction is known only once the first frame resolves it, and a guess would be a false reading.
152
+ */
137
153
  function openingCamera(definition, runtime, search) {
138
154
  const start = viewFromSearch(search) ?? definition.startView;
139
155
  if (start !== undefined)
140
- return start;
156
+ return "kind" in start ? undefined : start;
141
157
  const opening = createOrbitCameraState(START_CAMERA_DISTANCE, runtime.sceneCenter);
142
158
  return viewFromAngles(opening.focus, opening.azimuth, opening.elevation, opening.distance);
143
159
  }
144
160
  /** The scene's live controls at mount: the address overrides the experience's own start values. */
145
161
  function initialSceneControls(definition, runtime, experience, startScale, glowBase, storyMarkers, suppliedPolicies, search) {
146
- const startView = viewFromSearch(search) ?? definition.startView;
162
+ // A look-out toward an id is aimed as a `setCamera` one is: a sky figure becomes its label point here, an object is turned toward on the first frame.
163
+ const opening = definition.startView;
164
+ const startView = viewFromSearch(search) ?? (opening !== undefined && "kind" in opening ? aimAtFigure(opening, runtime.skyFigures) : opening);
147
165
  return {
148
166
  policy: scalePolicyFor(startScale, suppliedPolicies),
149
167
  cameraRequest: null,
@@ -152,6 +170,11 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
152
170
  ...(definition.pacing === undefined ? {} : { paceAuto: true, pace: { shown: shownEventsOf(definition, startViewId(definition, search)) } }),
153
171
  up: viewUpVector(startViewUp(definition, search)),
154
172
  showMilkyWay: runtime.sky.milkyWay,
173
+ skyLines: skyLineStart(definition.displaySwitches, DEFAULT_SKY_LINES),
174
+ skyColours: skyColoursOf(runtime.look),
175
+ skyTraces: [],
176
+ skyFadeInSeconds: skyFadeInSecondsOf(runtime.look),
177
+ labelStyle: labelStyleOf(runtime.look),
155
178
  skyVisible: runtime.sky.visible,
156
179
  bodyMarker: markerSettingsOf(runtime.look),
157
180
  ...(glowBase === null ? {} : { glowLook: glowLookOf(runtime.look, glowBase) }),
@@ -230,7 +253,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
230
253
  const metricsFor = useMemo(() => definition.createMetrics(experienceRuntime), [definition, experienceRuntime]);
231
254
  const glowBase = useMemo(() => baseGlowOf(runtime.bodies.map((id) => runtime.catalogue.get(id))), [runtime]);
232
255
  const storySet = definition.experience.storyPanels;
233
- const storyMarkerSpecs = useMemo(() => (storySet?.panels ?? []).flatMap((panel) => (panel.objectId === undefined ? [] : [{ panelId: panel.id, objectId: panel.objectId, title: panel.title, timeUtcMs: panel.timeUtcMs }])), [storySet]);
256
+ const storyMarkerSpecs = useMemo(() => [...(storySet?.panels ?? []), ...(storySet?.steps ?? [])].flatMap((panel) => (panel.objectId === undefined ? [] : [{ panelId: panel.id, objectId: panel.objectId, title: panel.title, ..."timeUtcMs" in panel ? { timeUtcMs: panel.timeUtcMs } : {} }])), [storySet]);
234
257
  const controls = useRef(initialSceneControls(definition, runtime, experience, startScale, glowBase, storyMarkerSpecs, suppliedPolicies, search));
235
258
  const readout = useRef(null);
236
259
  const [clockSnapshot, setClockSnapshot] = useState(() => runtime.clock.snapshot());
@@ -239,6 +262,9 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
239
262
  const [timelineGlow, setTimelineGlow] = useState(DEFAULT_TIMELINE_GLOW);
240
263
  const [phoneLayout, setPhoneLayout] = useState(DEFAULT_PHONE_LAYOUT);
241
264
  const [anchorLabels, setAnchorLabels] = useState(controls.current.showAnchorLabels);
265
+ const [skyLinesShown, setSkyLinesShown] = useState(controls.current.skyLines);
266
+ const [skyColoursShown, setSkyColoursShown] = useState(controls.current.skyColours);
267
+ const [labelStyleShown, setLabelStyleShown] = useState(controls.current.labelStyle);
242
268
  const [glowShown, setGlowShown] = useState(copyOfGlow(controls.current.glowLook));
243
269
  const orbitPaths = orbitPathsOf(runtime);
244
270
  const orbitDefault = useMemo(() => resolveOrbitLook(orbitPaths[0]?.look), [orbitPaths]);
@@ -286,14 +312,18 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
286
312
  const [viewLink, setViewLink] = useState(null);
287
313
  const [fills, setFills] = useState([]);
288
314
  const updateCameraRequest = useCallback((request) => {
289
- controls.current.cameraRequest = request;
290
- }, []);
315
+ controls.current.cameraRequest = aimAtFigure(request, runtime.skyFigures);
316
+ }, [runtime]);
317
+ const turnToFigure = useCallback((id) => {
318
+ const now = controls.current.viewReadout;
319
+ if (now !== undefined && "lookOut" in now)
320
+ updateCameraRequest({ kind: "lookOut", body: now.lookOut, direction: id });
321
+ }, [updateCameraRequest]);
291
322
  const holdCamera = useCallback(() => { controls.current.cameraRequest = { kind: "hold" }; }, []);
292
323
  const requestPanel = useCallback((id) => setPanelRequest((previous) => ({ id, serial: (previous?.serial ?? 0) + 1 })), []);
293
324
  const requestPick = useCallback((id) => setPickRequest((previous) => ({ id, serial: (previous?.serial ?? 0) + 1 })), []);
294
325
  const requestFeature = useCallback((key) => setFeatureRequest((previous) => ({ key, serial: (previous?.serial ?? 0) + 1 })), []);
295
326
  const markOpenFeature = useCallback((key) => { controls.current.openFeatureKey = key; }, []);
296
- const markOpenPanel = useCallback((id) => { controls.current.openStoryPanelId = id; }, []);
297
327
  const setPlaying = useCallback((playing) => {
298
328
  if (playing)
299
329
  runtime.clock.play();
@@ -336,6 +366,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
336
366
  ...(runtime.eventZones === undefined ? {} : { zones: activeEventZones(runtime.eventZones, shownEventsOf(definition, viewRef.current), snapshot.timeUtcMs) }),
337
367
  ...(definition.views === undefined ? {} : { view: viewRef.current }),
338
368
  ...(controls.current.selectedObjectId === "" ? {} : { selected: controls.current.selectedObjectId }),
369
+ ...(controls.current.openStoryPanelId == null ? {} : { panel: controls.current.openStoryPanelId }),
339
370
  };
340
371
  }, [runtime, definition]);
341
372
  // A selection that changes is told to the host at once (the shell calls this for a menu choice, a pick and a view switch that drops the object); the opening selection and any before the host is attached wait for the attach reading.
@@ -346,12 +377,23 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
346
377
  // The host's `setSelected` not yet applied by the shell (id "" clears); the shell applies it after its own view-switch choices, so the host call is the last word.
347
378
  const hostSelect = useRef(null);
348
379
  const [selectRequest, setSelectRequest] = useState(null);
349
- const hostSetSelected = useCallback((id) => {
380
+ /** `quiet`: a story panel's select, which follows the visitor-tap rule for the card (the shell decides: wide screens open it, phones do not); a host call opens it always. */
381
+ const selectWith = useCallback((id, quiet) => {
350
382
  hostSelect.current = id ?? "";
351
383
  controls.current.selectedObjectId = id ?? ""; // `read()` shows it at once
352
- setSelectRequest((previous) => ({ id: id ?? "", serial: (previous?.serial ?? 0) + 1 }));
384
+ setSelectRequest((previous) => ({ id: id ?? "", serial: (previous?.serial ?? 0) + 1, ...(quiet ? { quiet } : {}) }));
353
385
  }, []);
386
+ const hostSetSelected = useCallback((id) => selectWith(id, false), [selectWith]);
354
387
  const hostSelectApplied = useCallback(() => { hostSelect.current = null; }, []);
388
+ const hostSetPanel = useCallback((id) => {
389
+ controls.current.openStoryPanelId = id ?? null; // `read()` shows it at once
390
+ setPanelRequest((previous) => ({ id: id ?? "", serial: (previous?.serial ?? 0) + 1, host: true }));
391
+ }, []);
392
+ const panelIds = useCallback(() => {
393
+ const set = definition.experience.storyPanels;
394
+ const hidden = controls.current.viewHidden?.panels;
395
+ return [...(set?.panels ?? []), ...(set?.steps ?? [])].map(({ id }) => id).filter((id) => hidden === undefined || !hidden.has(id));
396
+ }, [definition]);
355
397
  const updateSelectedObject = useCallback((objectId, origin) => {
356
398
  if (hostSelect.current !== null)
357
399
  return; // a host `setSelected` is waiting for the shell: the shell's older choice must not undo it (the host-call order rule)
@@ -415,23 +457,57 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
415
457
  }, [experience]);
416
458
  const opening = useMemo(() => openingCamera(definition, runtime, search), []); // eslint-disable-line react-hooks/exhaustive-deps
417
459
  const readCamera = useCallback(() => {
418
- return { ...(controls.current.viewReadout ?? opening) };
460
+ const view = controls.current.viewReadout ?? opening;
461
+ return view === undefined ? undefined : { ...view };
419
462
  }, [opening]);
420
463
  // A host camera call is the last word: it is also kept in `hostCameraRequest`, so the opening view (first frame) and a view's own camera rule (shell) yield to it.
421
- const setCamera = useCallback((request) => { controls.current.cameraRequest = controls.current.hostCameraRequest = request; }, []);
464
+ const setCamera = useCallback((request) => { controls.current.cameraRequest = controls.current.hostCameraRequest = aimAtFigure(request, runtime.skyFigures); }, [runtime]);
422
465
  const hostCameraSet = useCallback(() => controls.current.hostCameraRequest != null, []);
423
466
  const hostScales = useMemo(() => scaleChoiceIds ?? SCALE_CHOICES.map((choice) => choice.id), [scaleChoiceIds]);
424
467
  const hostSetLook = useCallback((look) => live.current?.setLook(look), []);
425
468
  const hostSetScale = useCallback((id) => live.current?.setScale(id), []);
469
+ const hostClearSkyTrace = useCallback((id, seconds) => { controls.current.skyTraces.push({ id, seconds, reduced: prefersReducedMotion() }); }, []);
470
+ const hostTraceSkyFigure = useCallback((id, seconds, after) => { controls.current.skyTraces.push({ id, seconds, after, reduced: prefersReducedMotion() }); }, []);
426
471
  const hostSetSwitch = useCallback((id, on) => live.current?.setSwitch(id, on), []);
472
+ /** The figure the open story panel traced when it opened; it is cleared (default fade) when the panel is left. */
473
+ const panelTrace = useRef(null);
474
+ /** The panel whose actions were last applied (a host `setPanel` shows its panel at once, so `openStoryPanelId` cannot say whether the shell has opened it yet). */
475
+ const actedPanel = useRef(null);
476
+ /** The shell's open panel changed (a visitor, a host call already shown, playback crossing a panel, or a view switch dropping it); a change is told to the host, the opening panel is read at attach. */
477
+ const markOpenPanel = useCallback((id, cause) => {
478
+ const changed = (controls.current.openStoryPanelId ?? null) !== id;
479
+ controls.current.openStoryPanelId = id;
480
+ if (changed && hostAttached.current)
481
+ host?.publishPanel(stateNow(), cause);
482
+ if (actedPanel.current === id)
483
+ return;
484
+ actedPanel.current = id;
485
+ // Leaving a panel clears the trace it started; what a host or visitor did since is left as it is.
486
+ if (panelTrace.current !== null)
487
+ hostClearSkyTrace(panelTrace.current, TRACE_FADE_SECONDS);
488
+ panelTrace.current = null;
489
+ const set = definition.experience.storyPanels;
490
+ const panel = id === null ? undefined : [...(set?.panels ?? []), ...(set?.steps ?? [])].find((candidate) => candidate.id === id);
491
+ if (panel === undefined)
492
+ return;
493
+ // The panel's actions go through the host calls, in this order: camera, select, trace.
494
+ if (panel.camera !== undefined)
495
+ setCamera(panel.camera);
496
+ if (panel.select === true && panel.objectId !== undefined)
497
+ selectWith(panel.objectId, true);
498
+ if (panel.trace !== undefined && panel.objectId !== undefined) {
499
+ hostTraceSkyFigure(panel.objectId, panel.trace.seconds, panel.trace.after);
500
+ panelTrace.current = panel.objectId;
501
+ }
502
+ }, [host, stateNow, definition, setCamera, selectWith, hostTraceSkyFigure, hostClearSkyTrace]);
427
503
  useEffect(() => {
428
504
  if (host === undefined)
429
505
  return undefined;
430
506
  hostAttached.current = true;
431
507
  shownKey.current = null; // the presentation is read afresh after each attach
432
- host.attach({ ...(definition.picker === undefined ? {} : { picker: { id: definition.picker.id, values: definition.picker.options.map((option) => option.value), start: definition.picker.value } }), window: runtime.loopWindow, events: experience.events, rates: definition.experience.rates, paced: runtime.pacing !== undefined, read: stateNow, seek: hostSeekTo, setRate: changeRate, playable: definition.experience.hideTimeline !== true, setPlaying: hostSetPlaying, views: viewIds, setView: chooseView, cameraTargets, readCamera, setCamera, setSelected: hostSetSelected, scales: hostScales, setScale: hostSetScale, setLook: hostSetLook, setSwitch: hostSetSwitch });
508
+ host.attach({ ...(definition.picker === undefined ? {} : { picker: { id: definition.picker.id, values: definition.picker.options.map((option) => option.value), start: definition.picker.value } }), window: runtime.loopWindow, skyFigures: skyFigureReads(runtime.skyFigures, experience.skyFigures), events: experience.events, rates: definition.experience.rates, paced: runtime.pacing !== undefined, read: stateNow, seek: hostSeekTo, setRate: changeRate, playable: definition.experience.hideTimeline !== true, setPlaying: hostSetPlaying, views: viewIds, setView: chooseView, cameraTargets, readCamera, setCamera, setSelected: hostSetSelected, panels: panelIds, setPanel: hostSetPanel, scales: hostScales, setScale: hostSetScale, setLook: hostSetLook, setSwitch: hostSetSwitch, traceSkyFigure: hostTraceSkyFigure, clearSkyTrace: hostClearSkyTrace });
433
509
  return () => { hostAttached.current = false; host.detach(); };
434
- }, [host, runtime, definition, hostSeekTo, changeRate, viewIds, chooseView, cameraTargets, readCamera, setCamera, hostSetSelected, experience, hostSetPlaying, hostScales, hostSetScale, hostSetLook, hostSetSwitch]);
510
+ }, [host, runtime, definition, hostSeekTo, changeRate, viewIds, chooseView, cameraTargets, readCamera, setCamera, hostSetSelected, panelIds, hostSetPanel, experience, hostSetPlaying, hostScales, hostSetScale, hostSetLook, hostSetSwitch, hostTraceSkyFigure, hostClearSkyTrace]);
435
511
  useEffect(() => {
436
512
  if (!developerMode)
437
513
  return undefined;
@@ -472,6 +548,10 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
472
548
  settings: definition.displaySwitches,
473
549
  orbit: { present: orbitPaths.length > 0, look: { ...orbitDefault, ...controls.current.orbitLook }, set: setOrbit },
474
550
  moons: { present: bodySets.length > 0, look: controls.current.bodySetLook ?? DEFAULT_BODY_SET_LOOK, set: changeSetLook },
551
+ skyLines: {
552
+ figures: runtime.skyFigures.some(({ kind }) => kind === "figure"), boundaries: runtime.skyFigures.some(({ kind }) => kind === "boundary"), on: controls.current.skyLines,
553
+ set: (key, on) => { controls.current.skyLines = { ...controls.current.skyLines, [key]: on }; setSkyLinesShown(controls.current.skyLines); },
554
+ },
475
555
  sky: { present: controls.current.skyVisible !== false, on: controls.current.showMilkyWay, set: (on) => { controls.current.showMilkyWay = on; setMilkyWayOn(on); } },
476
556
  labels: {
477
557
  objectIds: experience.objects.map((object) => object.id), hidden: controls.current.hiddenLabels ?? hiddenLabels,
@@ -491,6 +571,8 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
491
571
  setGlowShown({ ...controls.current.glowLook });
492
572
  setMarkerPx(read.markerSwapRadiusPx);
493
573
  setLoadFade(read.loadFadeSeconds);
574
+ setSkyColoursShown(controls.current.skyColours);
575
+ setLabelStyleShown(controls.current.labelStyle);
494
576
  },
495
577
  setScale: updateScale,
496
578
  items: () => displaySwitchItems({ ...bindingsNow(), settings: hostReachable(definition.displaySwitches) }),
@@ -505,7 +587,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
505
587
  shownKey.current = key;
506
588
  if (changed)
507
589
  host?.publish(state, "visitor");
508
- }, [host, stateNow, scale, skyVisible, starBrightness, milkyWayBrightness, milkyWayOn, glowShown, markerPx, loadFade, orbitShown, setLook, hiddenLabels, anchorLabels]);
590
+ }, [host, stateNow, scale, skyVisible, starBrightness, milkyWayBrightness, milkyWayOn, glowShown, markerPx, loadFade, orbitShown, setLook, hiddenLabels, anchorLabels, skyLinesShown, skyColoursShown, labelStyleShown]);
509
591
  const hasStoryPanels = (storySet?.panels.length ?? 0) > 0;
510
592
  const showDisplay = showsDisplayControls(definition, runtime, skyVisible, orbitPaths.length, storyMarkerSpecs.length);
511
593
  // Orbit-line sliders: the first four stay in view, the rest sit in a nested "Fine-tune" fold (T-090).
@@ -557,7 +639,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
557
639
  },
558
640
  {
559
641
  id: "labels", title: "Labels",
560
- body: (_jsx(LabelSettings, { controls: controls, hoverBrightness: hoverBrightness, setHoverBrightness: setHoverBrightness, labelToggles: labelToggles, trackedCount: runtime.trackedBodies.length, anchorLabels: anchorLabels, setAnchorLabels: setAnchorLabels, hiddenLabels: hiddenLabels, setHiddenLabels: setHiddenLabels })),
642
+ body: (_jsx(LabelSettings, { controls: controls, hoverBrightness: hoverBrightness, setHoverBrightness: setHoverBrightness, labelToggles: labelToggles, trackedCount: runtime.trackedBodies.length, anchorLabels: anchorLabels, setAnchorLabels: setAnchorLabels, hiddenLabels: hiddenLabels, setHiddenLabels: setHiddenLabels, labelStyle: labelStyleShown, setLabelStyle: setLabelStyleShown, skyColours: skyColoursShown, setSkyColours: setSkyColoursShown, hasSky: skyVisible })),
561
643
  },
562
644
  !showDisplay ? null : {
563
645
  id: "phone-layout", title: "Phone layout",
@@ -576,7 +658,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
576
658
  ];
577
659
  const presentGroups = groups.filter((group) => group !== null);
578
660
  const drawer = (_jsx(PanelLoadBoundary, { children: _jsx(Suspense, { fallback: _jsx("p", { className: "developer-loading", role: "status", children: "Loading developer tools..." }), children: _jsxs("div", { className: "hud", children: [_jsxs("header", { className: "developer-heading", children: [_jsx("h2", { children: "Developer tools" }), _jsx("p", { children: "Live readouts, controls and diagnostics for this scene." })] }), presentGroups.map((group, index) => (_jsx(Collapsible, { fold: group.id, title: group.title, defaultOpen: index === 0, className: `dev-group${group.className === undefined ? "" : ` ${group.className}`}`, children: group.body }, group.id)))] }) }) }));
579
- return (_jsx(AstraeusShell, { experience: shellExperience, snapshot: clockSnapshot, paceAuto: runtime.pacing === undefined ? undefined : paceAuto, developerMode: developerMode, onDeveloperModeChange: setDeveloperMode, onTogglePlayback: () => {
661
+ return (_jsx(AstraeusShell, { experience: shellExperience, snapshot: clockSnapshot, paceAuto: runtime.pacing === undefined ? undefined : paceAuto, developerMode: developerMode, labelStyle: labelStyleShown, onDeveloperModeChange: setDeveloperMode, onTogglePlayback: () => {
580
662
  if (runtime.clock.playing)
581
663
  runtime.clock.pause();
582
664
  else
@@ -589,5 +671,5 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
589
671
  }, onSeek: (timeUtcMs) => {
590
672
  seekTo(timeUtcMs);
591
673
  host?.publish(stateNow(), "visitor");
592
- }, onCameraRequest: updateCameraRequest, onCameraHold: holdCamera, hostCameraSet: hostCameraSet, storySeekNote: storySeekNote, onSelectionChange: updateSelectedObject, scaleId: scale, onScaleChange: updateScale, scaleChoices: scaleChoices, switcher: definition.picker === undefined ? undefined : pickerSwitch(definition.picker, hostPick ?? definition.picker.value, choosePick), displaySwitches: displaySwitches, viewChoice: viewChoice, viewCamera: currentView === undefined ? undefined : { id: currentView.id, rule: currentView.camera }, metricsFor: metricsFor, developerTools: drawerWhen(developerTools, drawer), storyPanelSettings: { autoOpen: storyAutoOpen, pauseSeconds: storyPauseSeconds }, timelineGlow: timelineGlow, phoneLayout: phoneLayout, highlightedFamily: setLook.highlightFamily, onHighlightFamily: highlightFamily, onSetPlaying: setPlaying, panelRequest: panelRequest, onOpenPanelChange: markOpenPanel, featureRequest: featureRequest, pickRequest: pickRequest, selectRequest: selectRequest, onSelectRequestApplied: hostSelectApplied, onOpenFeatureChange: markOpenFeature, children: _jsx("div", { className: "canvas-host", children: _jsx(AstraeusScene, { runtime: runtime, controls: controls.current, readout: readout, scaleId: scale, onFirstDraw: host === undefined ? undefined : told }) }) }));
674
+ }, onCameraRequest: updateCameraRequest, onTurnToFigure: turnToFigure, onCameraHold: holdCamera, hostCameraSet: hostCameraSet, storySeekNote: storySeekNote, onSelectionChange: updateSelectedObject, scaleId: scale, onScaleChange: updateScale, scaleChoices: scaleChoices, switcher: definition.picker === undefined ? undefined : pickerSwitch(definition.picker, hostPick ?? definition.picker.value, choosePick), displaySwitches: displaySwitches, viewChoice: viewChoice, viewCamera: currentView === undefined ? undefined : { id: currentView.id, rule: currentView.camera }, metricsFor: metricsFor, developerTools: drawerWhen(developerTools, drawer), storyPanelSettings: { autoOpen: storyAutoOpen, pauseSeconds: storyPauseSeconds }, timelineGlow: timelineGlow, phoneLayout: phoneLayout, highlightedFamily: setLook.highlightFamily, onHighlightFamily: highlightFamily, onSetPlaying: setPlaying, panelRequest: panelRequest, onOpenPanelChange: markOpenPanel, featureRequest: featureRequest, pickRequest: pickRequest, selectRequest: selectRequest, onSelectRequestApplied: hostSelectApplied, onOpenFeatureChange: markOpenFeature, children: _jsx("div", { className: "canvas-host", children: _jsx(AstraeusScene, { runtime: runtime, controls: controls.current, readout: readout, scaleId: scale, onFirstDraw: host === undefined ? undefined : told }) }) }));
593
675
  }
@@ -13,10 +13,13 @@ import type { DebugReadout } from "./debugReadout.js";
13
13
  import { type CameraReach, type GroupLayer, type PathLayer, type SunBody, type VisualOverride } from "./experienceDefinition.js";
14
14
  import type { TrackedBody } from "./mission.js";
15
15
  import type { RenderVector } from "./renderCoordinates.js";
16
- import type { StartView } from "./viewLink.js";
16
+ import type { CameraView } from "./viewLink.js";
17
+ import type { OpeningView } from "./sceneCamera.js";
17
18
  import type { FrameStats } from "./frameStats.js";
18
19
  import type { GroupFill } from "./FrameRateSection.js";
19
20
  import { type BodySetLayer, type BodySetLook } from "./bodySet.js";
21
+ import type { LabelStyle } from "./labelStyle.js";
22
+ import type { SkyColours, SkyClearRequest, SkyFigureLayer, SkyLineSwitches, SkyTraceRequest } from "./skyFigures.js";
20
23
  import type { RingLook } from "../assets/rings.js";
21
24
  import type { Pictures } from "../assets/pictures.js";
22
25
  import { type StoryMarkerSpec } from "./StoryMarkers.js";
@@ -61,6 +64,8 @@ export interface SceneRuntime {
61
64
  readonly pictures?: Pictures;
62
65
  /** Paths the `sun-centred` layer draws; empty when the experience has none. */
63
66
  readonly paths?: readonly PathLayer[];
67
+ /** Figures and outlines drawn on the sky; empty when the experience has none. */
68
+ readonly skyFigures: readonly SkyFigureLayer[];
64
69
  /** The experience's declared camera reach; empty keeps the built-in limits. */
65
70
  readonly cameraReach: CameraReach;
66
71
  /** The sky behind the scene: whether it is drawn and how bright. Absent means no sky. `live`: the host may show a sky that starts hidden (`SceneControls.skyVisible`), so it is built either way. */
@@ -81,6 +86,16 @@ export interface SceneControls {
81
86
  showAnchorLabels: boolean;
82
87
  /** Presentation only: draw the Milky Way picture behind the stars (the stars are always drawn while the sky is). */
83
88
  showMilkyWay: boolean;
89
+ /** Presentation only: which kinds of sky line show (live, replaced on a switch). */
90
+ skyLines: SkyLineSwitches;
91
+ /** Presentation only: the colours of the sky lines and their labels (the look `skyLines`; live). */
92
+ skyColours: SkyColours;
93
+ /** Traces the host asked for, not yet started: the frame's `advanceSkyTraces` stage takes them in call order (the host link pushes, the frame empties it). */
94
+ skyTraces: (SkyTraceRequest | SkyClearRequest)[];
95
+ /** Presentation only: how long sky lines and their names fade in when they appear, in seconds (the look `skyFadeInSeconds`; live). */
96
+ skyFadeInSeconds: number;
97
+ /** Presentation only: the label font and size (the look `labels`; live). The viewer root carries it to every label as CSS variables. */
98
+ labelStyle: LabelStyle;
84
99
  /** Presentation only: when a sphere is too small to see it is drawn as a marker (see `drawsAsMarker`). */
85
100
  bodyMarker: BodyMarkerSettings;
86
101
  /** Presentation only: the live halo settings of a body whose record has a glow (the Sun). */
@@ -134,10 +149,10 @@ export interface SceneControls {
134
149
  frameStats: FrameStats | null;
135
150
  /** Each group's refill count, written by the scene while `frameStats` is set; read by the Developer tools poll. */
136
151
  readonly groupFills: GroupFill[];
137
- /** The view to open on (from `?view=` or the experience's `startView`). Used once, on the first frame; absent: today's opening. */
138
- startView?: StartView;
139
- /** The camera's current view, written every frame by the scene for "Copy view link". */
140
- viewReadout?: StartView;
152
+ /** The view to open on (from `?view=` or the experience's `startView`, a look-out toward an id as a request). Used once, on the first frame; absent: today's opening. */
153
+ startView?: OpeningView;
154
+ /** The camera's current view, written every frame by the scene for "Copy view link": an orbit view, or a sky view while looking out. */
155
+ viewReadout?: CameraView;
141
156
  /** How long the loading cover fades when the first frame is drawn (the address's `loadfade` when the address is on, else the saved setting). */
142
157
  loadFadeSeconds?: number;
143
158
  /** Whether wide screens draw the larger desktop pictures: set when the viewer is built, read back by `look`. */