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
package/src/app/App.js CHANGED
@@ -3,7 +3,9 @@ import { Suspense, useCallback, useEffect, useMemo, useRef, useState, useSyncExt
3
3
  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
+ import { frameTime } from "./sceneFrame.js";
6
7
  import { openClock } from "./openClock.js";
8
+ import { createProvenance } from "../core/provenance.js";
7
9
  import { pickerSwitch } from "./listSwitch.js";
8
10
  import { createSolarSystemScale } from "../core/scalePolicy.js";
9
11
  import { bodySetsOf, cameraReachOf, catalogueOf, compositionOf, experienceWithGroups, groupsOf, initialObjectIdOf, mountedBodiesOf, pageTitleOf, scaleChoiceIdsOf, sceneCenterOf, sunCentredOf, trackedBodiesOf, visualOverridesOf } from "./experienceDefinition.js";
@@ -30,8 +32,12 @@ import { loadStarCatalogue } from "../assets/sky.js";
30
32
  import { withSkyObject } from "./skyModel.js";
31
33
  import { ORBIT_LOOK_LIMITS, resolveOrbitLook } from "../assets/orbitLook.js";
32
34
  import { DEFAULT_BODY_SET_LOOK } from "./bodySet.js";
33
- import { displaySwitchItems, hostReachable, orbitStart } from "./displaySwitches.js";
34
- import { experienceInView, hiddenByView, viewById } from "./viewHiding.js";
35
+ import { displaySwitchItems, hostReachable, orbitStart, skyLineStart } from "./displaySwitches.js";
36
+ import { TRACE_FADE_SECONDS } from "../core/skyTrace.js";
37
+ import { aimAtFigure, DEFAULT_SKY_LINES, prefersReducedMotion, skyColoursOf, skyFadeInSecondsOf } from "./skyFigures.js";
38
+ import { labelStyleOf } from "./labelStyle.js";
39
+ import { experienceInView, hiddenByView, hiddenWithShownSpans, viewById } from "./viewHiding.js";
40
+ import { cameraIdsOf } from "../core/storyPanels.js";
35
41
  import { baseGlowOf, glowLookOf, markerSettingsOf } from "./bodyDraw.js";
36
42
  import { resolveLook } from "./look.js";
37
43
  import { applyLook, desktopPicturesOf, lookReadOf, presentationOf, skySettingsOf } from "./liveLook.js";
@@ -57,6 +63,14 @@ export function loopFromSearch(search, fallback) {
57
63
  return value === "on" ? true : value === "off" ? false : fallback;
58
64
  }
59
65
  /** 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). */
66
+ const NO_CARD_PROVENANCE = createProvenance({ sourceType: "illustrative", sources: ["Supplied by the caller"], accuracy: "As supplied; the engine makes no claim.", notes: "" });
67
+ /** The sky figures as the host link reads them: each drawn figure with its card words (`experience.skyFigures`). */
68
+ function skyFigureReads(layers, cards) {
69
+ return layers.map(({ id, label, kind }) => {
70
+ 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
71
+ 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 }) });
72
+ });
73
+ }
60
74
  function startViewId(definition, search) {
61
75
  const asked = showFromSearch(search);
62
76
  const known = asked !== undefined && definition.views?.views.some((view) => view.id === asked) === true;
@@ -113,6 +127,7 @@ function buildRuntime(definition, search) {
113
127
  trackedBodies: trackedBodiesOf(definition),
114
128
  groups: groupsOf(definition),
115
129
  bodySets: bodySetsOf(definition),
130
+ skyFigures: definition.skyFigures ?? [],
116
131
  ...sunCentredOf(definition),
117
132
  cameraReach: cameraReachOf(definition),
118
133
  look,
@@ -133,17 +148,22 @@ function showsDisplayControls(definition, runtime, skyVisible, orbitPathCount, s
133
148
  return orbitPathCount > 0 || runtime.trackedBodies.length > 0 || skyVisible || storyMarkerCount > 0 || (definition.experience.storyPanels?.panels.length ?? 0) > 0
134
149
  || runtime.bodies.some((id) => runtime.catalogue.get(id).visual.kind === "sphere");
135
150
  }
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`. */
151
+ /**
152
+ * 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`.
153
+ * 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.
154
+ */
137
155
  function openingCamera(definition, runtime, search) {
138
156
  const start = viewFromSearch(search) ?? definition.startView;
139
157
  if (start !== undefined)
140
- return start;
158
+ return "kind" in start ? undefined : start;
141
159
  const opening = createOrbitCameraState(START_CAMERA_DISTANCE, runtime.sceneCenter);
142
160
  return viewFromAngles(opening.focus, opening.azimuth, opening.elevation, opening.distance);
143
161
  }
144
162
  /** The scene's live controls at mount: the address overrides the experience's own start values. */
145
163
  function initialSceneControls(definition, runtime, experience, startScale, glowBase, storyMarkers, suppliedPolicies, search) {
146
- const startView = viewFromSearch(search) ?? definition.startView;
164
+ // 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.
165
+ const opening = definition.startView;
166
+ const startView = viewFromSearch(search) ?? (opening !== undefined && "kind" in opening ? aimAtFigure(opening, runtime.skyFigures) : opening);
147
167
  return {
148
168
  policy: scalePolicyFor(startScale, suppliedPolicies),
149
169
  cameraRequest: null,
@@ -152,6 +172,11 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
152
172
  ...(definition.pacing === undefined ? {} : { paceAuto: true, pace: { shown: shownEventsOf(definition, startViewId(definition, search)) } }),
153
173
  up: viewUpVector(startViewUp(definition, search)),
154
174
  showMilkyWay: runtime.sky.milkyWay,
175
+ skyLines: skyLineStart(definition.displaySwitches, DEFAULT_SKY_LINES),
176
+ skyColours: skyColoursOf(runtime.look),
177
+ skyTraces: [],
178
+ skyFadeInSeconds: skyFadeInSecondsOf(runtime.look),
179
+ labelStyle: labelStyleOf(runtime.look),
155
180
  skyVisible: runtime.sky.visible,
156
181
  bodyMarker: markerSettingsOf(runtime.look),
157
182
  ...(glowBase === null ? {} : { glowLook: glowLookOf(runtime.look, glowBase) }),
@@ -230,7 +255,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
230
255
  const metricsFor = useMemo(() => definition.createMetrics(experienceRuntime), [definition, experienceRuntime]);
231
256
  const glowBase = useMemo(() => baseGlowOf(runtime.bodies.map((id) => runtime.catalogue.get(id))), [runtime]);
232
257
  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]);
258
+ 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
259
  const controls = useRef(initialSceneControls(definition, runtime, experience, startScale, glowBase, storyMarkerSpecs, suppliedPolicies, search));
235
260
  const readout = useRef(null);
236
261
  const [clockSnapshot, setClockSnapshot] = useState(() => runtime.clock.snapshot());
@@ -239,6 +264,9 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
239
264
  const [timelineGlow, setTimelineGlow] = useState(DEFAULT_TIMELINE_GLOW);
240
265
  const [phoneLayout, setPhoneLayout] = useState(DEFAULT_PHONE_LAYOUT);
241
266
  const [anchorLabels, setAnchorLabels] = useState(controls.current.showAnchorLabels);
267
+ const [skyLinesShown, setSkyLinesShown] = useState(controls.current.skyLines);
268
+ const [skyColoursShown, setSkyColoursShown] = useState(controls.current.skyColours);
269
+ const [labelStyleShown, setLabelStyleShown] = useState(controls.current.labelStyle);
242
270
  const [glowShown, setGlowShown] = useState(copyOfGlow(controls.current.glowLook));
243
271
  const orbitPaths = orbitPathsOf(runtime);
244
272
  const orbitDefault = useMemo(() => resolveOrbitLook(orbitPaths[0]?.look), [orbitPaths]);
@@ -285,15 +313,31 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
285
313
  const [viewNow, setViewNow] = useState(null);
286
314
  const [viewLink, setViewLink] = useState(null);
287
315
  const [fills, setFills] = useState([]);
316
+ /** The ids the camera's last request named (a preset, a host `setCamera`, a story panel's camera): the one rule below holds the camera when one of them stops being shown. */
317
+ const cameraNamed = useRef([]);
318
+ const noteCameraIds = (request) => { const { bodies, toward } = cameraIdsOf(request); cameraNamed.current = toward === undefined ? bodies : [...bodies, toward]; };
288
319
  const updateCameraRequest = useCallback((request) => {
289
- controls.current.cameraRequest = request;
290
- }, []);
291
- const holdCamera = useCallback(() => { controls.current.cameraRequest = { kind: "hold" }; }, []);
320
+ noteCameraIds(request);
321
+ controls.current.cameraRequest = aimAtFigure(request, runtime.skyFigures);
322
+ }, [runtime]);
323
+ const turnToFigure = useCallback((id) => {
324
+ const now = controls.current.viewReadout;
325
+ if (now !== undefined && "lookOut" in now)
326
+ updateCameraRequest({ kind: "lookOut", body: now.lookOut, direction: id });
327
+ }, [updateCameraRequest]);
328
+ const holdCamera = useCallback(() => { cameraNamed.current = []; controls.current.cameraRequest = { kind: "hold" }; }, []);
329
+ /** O-071 (I-175): whatever named the camera's target, once that object is not shown at `timeUtcMs` the camera keeps its pose and stops following (`shownAt`, via `hiddenWithShownSpans`). */
330
+ const holdCameraOffShown = useCallback((timeUtcMs) => {
331
+ if (cameraNamed.current.length === 0)
332
+ return;
333
+ const out = hiddenWithShownSpans(undefined, experience.objects, timeUtcMs)?.objects;
334
+ if (out !== undefined && cameraNamed.current.some((id) => out.has(id)))
335
+ holdCamera();
336
+ }, [experience, holdCamera]);
292
337
  const requestPanel = useCallback((id) => setPanelRequest((previous) => ({ id, serial: (previous?.serial ?? 0) + 1 })), []);
293
338
  const requestPick = useCallback((id) => setPickRequest((previous) => ({ id, serial: (previous?.serial ?? 0) + 1 })), []);
294
339
  const requestFeature = useCallback((key) => setFeatureRequest((previous) => ({ key, serial: (previous?.serial ?? 0) + 1 })), []);
295
340
  const markOpenFeature = useCallback((key) => { controls.current.openFeatureKey = key; }, []);
296
- const markOpenPanel = useCallback((id) => { controls.current.openStoryPanelId = id; }, []);
297
341
  const setPlaying = useCallback((playing) => {
298
342
  if (playing)
299
343
  runtime.clock.play();
@@ -336,6 +380,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
336
380
  ...(runtime.eventZones === undefined ? {} : { zones: activeEventZones(runtime.eventZones, shownEventsOf(definition, viewRef.current), snapshot.timeUtcMs) }),
337
381
  ...(definition.views === undefined ? {} : { view: viewRef.current }),
338
382
  ...(controls.current.selectedObjectId === "" ? {} : { selected: controls.current.selectedObjectId }),
383
+ ...(controls.current.openStoryPanelId == null ? {} : { panel: controls.current.openStoryPanelId }),
339
384
  };
340
385
  }, [runtime, definition]);
341
386
  // 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 +391,23 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
346
391
  // 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
392
  const hostSelect = useRef(null);
348
393
  const [selectRequest, setSelectRequest] = useState(null);
349
- const hostSetSelected = useCallback((id) => {
394
+ /** `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. */
395
+ const selectWith = useCallback((id, quiet) => {
350
396
  hostSelect.current = id ?? "";
351
397
  controls.current.selectedObjectId = id ?? ""; // `read()` shows it at once
352
- setSelectRequest((previous) => ({ id: id ?? "", serial: (previous?.serial ?? 0) + 1 }));
398
+ setSelectRequest((previous) => ({ id: id ?? "", serial: (previous?.serial ?? 0) + 1, ...(quiet ? { quiet } : {}) }));
353
399
  }, []);
400
+ const hostSetSelected = useCallback((id) => selectWith(id, false), [selectWith]);
354
401
  const hostSelectApplied = useCallback(() => { hostSelect.current = null; }, []);
402
+ const hostSetPanel = useCallback((id) => {
403
+ controls.current.openStoryPanelId = id ?? null; // `read()` shows it at once
404
+ setPanelRequest((previous) => ({ id: id ?? "", serial: (previous?.serial ?? 0) + 1, host: true }));
405
+ }, []);
406
+ const panelIds = useCallback(() => {
407
+ const set = definition.experience.storyPanels;
408
+ const hidden = controls.current.viewHidden?.panels;
409
+ return [...(set?.panels ?? []), ...(set?.steps ?? [])].map(({ id }) => id).filter((id) => hidden === undefined || !hidden.has(id));
410
+ }, [definition]);
355
411
  const updateSelectedObject = useCallback((objectId, origin) => {
356
412
  if (hostSelect.current !== null)
357
413
  return; // a host `setSelected` is waiting for the shell: the shell's older choice must not undo it (the host-call order rule)
@@ -362,13 +418,8 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
362
418
  }, [host, stateNow]);
363
419
  useEffect(() => {
364
420
  const id = window.setInterval(() => {
365
- // The readout wraps with the scene, so the shown time never rests past the end while looping.
366
- if (controls.current.loop === true)
367
- runtime.clock.wrapWithin(runtime.loopWindow);
368
- else if (runtime.stopAtWindow === true && runtime.loopWindow !== undefined)
369
- runtime.clock.stopWithin(runtime.loopWindow);
370
- if (controls.current.paceAuto === true && runtime.pacing !== undefined)
371
- applyPacing(runtime.clock, runtime.pacing, controls.current.pace);
421
+ // The readout wraps, stops and paces with the scene, so the shown time never rests past the end while looping and a host's playback reports follow the slow-downs.
422
+ frameTime(runtime, controls.current);
372
423
  setClockSnapshot(runtime.clock.snapshot());
373
424
  host?.publish(stateNow(), "playback");
374
425
  }, 100);
@@ -377,6 +428,8 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
377
428
  // The host reaches the one clock through the same seek and rate handlers a visitor's timeline uses.
378
429
  const seekTo = useCallback((timeUtcMs) => {
379
430
  runtime.clock.seek(timeUtcMs);
431
+ if (controls.current.pace !== undefined)
432
+ delete controls.current.pace.last; // the paced step starts again from the new time
380
433
  // A seek lands on the paced rate for the new time at once, not through a view-switch ease.
381
434
  if (controls.current.pace !== undefined) {
382
435
  delete controls.current.pace.ease;
@@ -408,30 +461,70 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
408
461
  }, [runtime]);
409
462
  // The same play handler the visitor's button reaches, so a host and a visitor share one clock.
410
463
  const hostSetPlaying = setPlaying;
411
- // The objects a host may point the camera at: those the showing view shows (read live, so a view switch is already counted).
464
+ // The objects a host may point the camera at: those the showing view shows and that are shown at the clock time (read live, so a view switch or a time move is already counted).
412
465
  const cameraTargets = useCallback(() => {
413
- const hidden = controls.current.viewHidden?.objects;
466
+ const hidden = hiddenWithShownSpans(controls.current.viewHidden, experience.objects, runtime.clock.snapshot().timeUtcMs)?.objects;
414
467
  return experience.objects.map(({ id }) => id).filter((id) => hidden === undefined || !hidden.has(id));
415
- }, [experience]);
468
+ }, [experience, runtime]);
416
469
  const opening = useMemo(() => openingCamera(definition, runtime, search), []); // eslint-disable-line react-hooks/exhaustive-deps
417
470
  const readCamera = useCallback(() => {
418
- return { ...(controls.current.viewReadout ?? opening) };
471
+ const view = controls.current.viewReadout ?? opening;
472
+ return view === undefined ? undefined : { ...view };
419
473
  }, [opening]);
420
474
  // 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; }, []);
475
+ const setCamera = useCallback((request) => { noteCameraIds(request); controls.current.cameraRequest = controls.current.hostCameraRequest = aimAtFigure(request, runtime.skyFigures); }, [runtime]);
422
476
  const hostCameraSet = useCallback(() => controls.current.hostCameraRequest != null, []);
423
477
  const hostScales = useMemo(() => scaleChoiceIds ?? SCALE_CHOICES.map((choice) => choice.id), [scaleChoiceIds]);
424
478
  const hostSetLook = useCallback((look) => live.current?.setLook(look), []);
425
479
  const hostSetScale = useCallback((id) => live.current?.setScale(id), []);
480
+ const hostClearSkyTrace = useCallback((id, seconds) => { controls.current.skyTraces.push({ id, seconds, reduced: prefersReducedMotion() }); }, []);
481
+ const hostTraceSkyFigure = useCallback((id, seconds, after) => { controls.current.skyTraces.push({ id, seconds, after, reduced: prefersReducedMotion() }); }, []);
426
482
  const hostSetSwitch = useCallback((id, on) => live.current?.setSwitch(id, on), []);
483
+ /** The figure the open story panel traced when it opened; it is cleared (default fade) when the panel is left. */
484
+ const panelTrace = useRef(null);
485
+ /** 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). */
486
+ const actedPanel = useRef(null);
487
+ /** Whether the objects a story panel's camera names are shown at the clock time; a request toward one outside its `shownDuring` span is refused as `setCamera` refuses it. */
488
+ const shownAtClock = useCallback((request) => {
489
+ const out = hiddenWithShownSpans(undefined, experience.objects, runtime.clock.snapshot().timeUtcMs)?.objects;
490
+ const { bodies, toward } = cameraIdsOf(request);
491
+ return out === undefined || ![...bodies, ...(toward === undefined ? [] : [toward])].some((id) => out.has(id));
492
+ }, [experience, runtime]);
493
+ /** 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. */
494
+ const markOpenPanel = useCallback((id, cause) => {
495
+ const changed = (controls.current.openStoryPanelId ?? null) !== id;
496
+ controls.current.openStoryPanelId = id;
497
+ if (changed && hostAttached.current)
498
+ host?.publishPanel(stateNow(), cause);
499
+ if (actedPanel.current === id)
500
+ return;
501
+ actedPanel.current = id;
502
+ // Leaving a panel clears the trace it started; what a host or visitor did since is left as it is.
503
+ if (panelTrace.current !== null)
504
+ hostClearSkyTrace(panelTrace.current, TRACE_FADE_SECONDS);
505
+ panelTrace.current = null;
506
+ const set = definition.experience.storyPanels;
507
+ const panel = id === null ? undefined : [...(set?.panels ?? []), ...(set?.steps ?? [])].find((candidate) => candidate.id === id);
508
+ if (panel === undefined)
509
+ return;
510
+ // The panel's actions go through the host calls, in this order: camera, select, trace.
511
+ if (panel.camera !== undefined && shownAtClock(panel.camera))
512
+ setCamera(panel.camera);
513
+ if (panel.select === true && panel.objectId !== undefined)
514
+ selectWith(panel.objectId, true);
515
+ if (panel.trace !== undefined && panel.objectId !== undefined) {
516
+ hostTraceSkyFigure(panel.objectId, panel.trace.seconds, panel.trace.after);
517
+ panelTrace.current = panel.objectId;
518
+ }
519
+ }, [host, stateNow, definition, setCamera, shownAtClock, selectWith, hostTraceSkyFigure, hostClearSkyTrace]);
427
520
  useEffect(() => {
428
521
  if (host === undefined)
429
522
  return undefined;
430
523
  hostAttached.current = true;
431
524
  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 });
525
+ 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
526
  return () => { hostAttached.current = false; host.detach(); };
434
- }, [host, runtime, definition, hostSeekTo, changeRate, viewIds, chooseView, cameraTargets, readCamera, setCamera, hostSetSelected, experience, hostSetPlaying, hostScales, hostSetScale, hostSetLook, hostSetSwitch]);
527
+ }, [host, runtime, definition, hostSeekTo, changeRate, viewIds, chooseView, cameraTargets, readCamera, setCamera, hostSetSelected, panelIds, hostSetPanel, experience, hostSetPlaying, hostScales, hostSetScale, hostSetLook, hostSetSwitch, hostTraceSkyFigure, hostClearSkyTrace]);
435
528
  useEffect(() => {
436
529
  if (!developerMode)
437
530
  return undefined;
@@ -472,6 +565,10 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
472
565
  settings: definition.displaySwitches,
473
566
  orbit: { present: orbitPaths.length > 0, look: { ...orbitDefault, ...controls.current.orbitLook }, set: setOrbit },
474
567
  moons: { present: bodySets.length > 0, look: controls.current.bodySetLook ?? DEFAULT_BODY_SET_LOOK, set: changeSetLook },
568
+ skyLines: {
569
+ figures: runtime.skyFigures.some(({ kind }) => kind === "figure"), boundaries: runtime.skyFigures.some(({ kind }) => kind === "boundary"), on: controls.current.skyLines,
570
+ set: (key, on) => { controls.current.skyLines = { ...controls.current.skyLines, [key]: on }; setSkyLinesShown(controls.current.skyLines); },
571
+ },
475
572
  sky: { present: controls.current.skyVisible !== false, on: controls.current.showMilkyWay, set: (on) => { controls.current.showMilkyWay = on; setMilkyWayOn(on); } },
476
573
  labels: {
477
574
  objectIds: experience.objects.map((object) => object.id), hidden: controls.current.hiddenLabels ?? hiddenLabels,
@@ -491,6 +588,8 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
491
588
  setGlowShown({ ...controls.current.glowLook });
492
589
  setMarkerPx(read.markerSwapRadiusPx);
493
590
  setLoadFade(read.loadFadeSeconds);
591
+ setSkyColoursShown(controls.current.skyColours);
592
+ setLabelStyleShown(controls.current.labelStyle);
494
593
  },
495
594
  setScale: updateScale,
496
595
  items: () => displaySwitchItems({ ...bindingsNow(), settings: hostReachable(definition.displaySwitches) }),
@@ -505,7 +604,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
505
604
  shownKey.current = key;
506
605
  if (changed)
507
606
  host?.publish(state, "visitor");
508
- }, [host, stateNow, scale, skyVisible, starBrightness, milkyWayBrightness, milkyWayOn, glowShown, markerPx, loadFade, orbitShown, setLook, hiddenLabels, anchorLabels]);
607
+ }, [host, stateNow, scale, skyVisible, starBrightness, milkyWayBrightness, milkyWayOn, glowShown, markerPx, loadFade, orbitShown, setLook, hiddenLabels, anchorLabels, skyLinesShown, skyColoursShown, labelStyleShown]);
509
608
  const hasStoryPanels = (storySet?.panels.length ?? 0) > 0;
510
609
  const showDisplay = showsDisplayControls(definition, runtime, skyVisible, orbitPaths.length, storyMarkerSpecs.length);
511
610
  // Orbit-line sliders: the first four stay in view, the rest sit in a nested "Fine-tune" fold (T-090).
@@ -557,7 +656,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
557
656
  },
558
657
  {
559
658
  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 })),
659
+ 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
660
  },
562
661
  !showDisplay ? null : {
563
662
  id: "phone-layout", title: "Phone layout",
@@ -576,7 +675,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
576
675
  ];
577
676
  const presentGroups = groups.filter((group) => group !== null);
578
677
  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: () => {
678
+ return (_jsx(AstraeusShell, { experience: shellExperience, snapshot: clockSnapshot, paceAuto: runtime.pacing === undefined ? undefined : paceAuto, developerMode: developerMode, labelStyle: labelStyleShown, onDeveloperModeChange: setDeveloperMode, onTogglePlayback: () => {
580
679
  if (runtime.clock.playing)
581
680
  runtime.clock.pause();
582
681
  else
@@ -589,5 +688,5 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
589
688
  }, onSeek: (timeUtcMs) => {
590
689
  seekTo(timeUtcMs);
591
690
  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 }) }) }));
691
+ }, onCameraRequest: updateCameraRequest, onTurnToFigure: turnToFigure, onCameraHold: holdCamera, onTimeShown: holdCameraOffShown, 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
692
  }