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
@@ -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
  }
@@ -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`. */
@@ -33,14 +33,14 @@ function SceneContents({ runtime, controls, readout, layers, frameState }) {
33
33
  const orbit = useRef(createOrbitCameraState(START_CAMERA_DISTANCE, runtime.sceneCenter));
34
34
  const { placement, readoutPair, pairLabels, assets, bodyFamilies } = useSceneDerived(runtime, catalogue);
35
35
  const views = useSceneViews(runtime, gl);
36
- const { trackedViews, groupViews, compositionPaths, skyView, bodySetViews, orbitSetViews, sunCentredViews } = views;
36
+ const { trackedViews, groupViews, compositionPaths, skyView, skyFiguresView, bodySetViews, orbitSetViews, sunCentredViews } = views;
37
37
  useSkyStars(gl.domElement, skyView);
38
38
  useDrawWakes(gl.domElement, frameState);
39
39
  useReleaseSharedTextures();
40
- const layerRefs = useOverlayLayers(gl.domElement, controls, trackedViews, bodySetViews);
40
+ const layerRefs = useOverlayLayers(gl.domElement, controls, trackedViews, bodySetViews, skyFiguresView.labels);
41
41
  useScenePointer(gl.domElement, runtime, controls, catalogue, orbit, frameState);
42
42
  useSceneFrame(rootRef, { runtime, controls, readout, catalogue, origin, orbit, state: frameState, assets, bodyRefs, lightRefs, placement, views, layers: layerRefs, bodyFamilies, readoutPair, pairLabels });
43
- return (_jsxs("group", { ref: rootRef, children: [assets.map((asset) => (_jsx(SceneBody, { asset: asset, layer: layers.get(asset.definition.id), controls: controls, desktopTextures: runtime.desktopTextures === true, pictures: runtime.pictures, ringLookOf: ringLookOf, onParts: partsFor.get(asset.definition.id), groupRef: refFor(groupRefs.current, asset.definition.id), orientRef: refFor(orientRefs.current, asset.definition.id), lightRef: refFor(lightRefs.current, asset.definition.id) }, asset.definition.id))), skyView !== null && _jsx("primitive", { object: skyView.group }), compositionPaths.map((view) => _jsx("primitive", { object: view.group }, view.id)), trackedViews.map((view) => _jsx("primitive", { object: view.group }, view.body.id)), groupViews.map((view) => _jsx("primitive", { object: view.group }, view.id)), sunCentredViews.map((view) => _jsx("primitive", { object: view.group }, view.id)), bodySetViews.map((view) => _jsx("primitive", { object: view.group }, view.id)), orbitSetViews.map((view) => _jsx("primitive", { object: view.group }, view.id))] }));
43
+ return (_jsxs("group", { ref: rootRef, children: [assets.map((asset) => (_jsx(SceneBody, { asset: asset, layer: layers.get(asset.definition.id), controls: controls, desktopTextures: runtime.desktopTextures === true, pictures: runtime.pictures, ringLookOf: ringLookOf, onParts: partsFor.get(asset.definition.id), groupRef: refFor(groupRefs.current, asset.definition.id), orientRef: refFor(orientRefs.current, asset.definition.id), lightRef: refFor(lightRefs.current, asset.definition.id) }, asset.definition.id))), skyView !== null && _jsx("primitive", { object: skyView.group }), _jsx("primitive", { object: skyFiguresView.group }), compositionPaths.map((view) => _jsx("primitive", { object: view.group }, view.id)), trackedViews.map((view) => _jsx("primitive", { object: view.group }, view.body.id)), groupViews.map((view) => _jsx("primitive", { object: view.group }, view.id)), sunCentredViews.map((view) => _jsx("primitive", { object: view.group }, view.id)), bodySetViews.map((view) => _jsx("primitive", { object: view.group }, view.id)), orbitSetViews.map((view) => _jsx("primitive", { object: view.group }, view.id))] }));
44
44
  }
45
45
  /** One catalogued body: its view and, when its record has a light, the ambient and directional light on its layer. */
46
46
  function SceneBody({ asset, layer, controls, desktopTextures, pictures, ringLookOf, onParts, groupRef, orientRef, lightRef }) {
@@ -2,6 +2,7 @@ import { PerspectiveCamera } from "three";
2
2
  import type { FloatingOrigin } from "./floatingOrigin.js";
3
3
  import type { RenderVector } from "./renderCoordinates.js";
4
4
  import { type PickPointer } from "./scenePicking.js";
5
+ import { type LookOutState } from "./lookOut.js";
5
6
  import type { StartView } from "./viewLink.js";
6
7
  /** The id of a catalogued body, or of any tracked trajectory body, group or path. */
7
8
  export type FocusId = string;
@@ -16,11 +17,25 @@ export type CameraRequest = {
16
17
  | {
17
18
  readonly kind: "hold";
18
19
  }
20
+ /**
21
+ * Stands the camera at the centre of `body` looking out: the direction is a unit vector in EQJ or an object id to turn toward (absent: the direction already looked along, else right ascension 0, declination 0), and `fovDeg` (default: the current one, else 60) is the zoom.
22
+ * Camera-only. A focus, follow, overview or pose request puts the orbit camera back; a hold is ignored while looking out.
23
+ */
24
+ | {
25
+ readonly kind: "lookOut";
26
+ readonly body: FocusId;
27
+ readonly direction?: readonly [number, number, number] | FocusId;
28
+ readonly fovDeg?: number;
29
+ }
19
30
  /** Puts the camera back on a pose read earlier: it follows the pose's object and eases to its angles and distance (the offset is the object's own, so a moving object is followed from where it is now). */
20
31
  | {
21
32
  readonly kind: "pose";
22
33
  readonly view: StartView;
23
34
  };
35
+ /** A look-out request: what `setCamera`, a story panel camera and an opening look-out toward an id all run (`sceneCamera.ts` `applyLookOut`). */
36
+ export type LookOutRequest = Extract<CameraRequest, {
37
+ readonly kind: "lookOut";
38
+ }>;
24
39
  export interface OrbitCameraState {
25
40
  azimuth: number;
26
41
  targetAzimuth: number;
@@ -34,6 +49,8 @@ export interface OrbitCameraState {
34
49
  fixedPoint: [number, number, number] | null;
35
50
  /** Decaying offset that tweens the displayed target from the previous focus to the new one. */
36
51
  transition: [number, number, number];
52
+ /** Set while the camera stands inside `focus` looking out: the field of view, with azimuth and elevation as the look direction. Null is the orbit camera. */
53
+ lookOut: LookOutState | null;
37
54
  /** Scaled absolute camera/target positions (Float64, render axes) for the latest frame. */
38
55
  cameraAbsolute: [number, number, number];
39
56
  targetAbsolute: [number, number, number];
@@ -57,7 +74,8 @@ export declare function switchFocus(state: OrbitCameraState, focus: FocusId, new
57
74
  * Step 1 (before bodies are placed): computes the absolute target/camera in Float64 render axes
58
75
  * and rebases the floating origin when the target drifts away from it, so bodies and camera
59
76
  * always use the same origin within a frame. Scientific state is never read or written here.
77
+ * With `reducedMotion` the distance, angles and focus tween land on their targets in one frame.
60
78
  */
61
- export declare function resolveCamera(state: OrbitCameraState, focusAbsolute: RenderVector, origin: FloatingOrigin, deltaSeconds: number, rebaseThreshold: number, up?: RenderVector): void;
79
+ export declare function resolveCamera(state: OrbitCameraState, focusAbsolute: RenderVector, origin: FloatingOrigin, deltaSeconds: number, rebaseThreshold: number, up?: RenderVector, reducedMotion?: boolean): void;
62
80
  /** Step 2: writes the origin-relative camera pose and clipping planes. */
63
81
  export declare function poseCamera(camera: PerspectiveCamera, state: OrbitCameraState, focusRadius: number, origin: FloatingOrigin, far?: number, up?: RenderVector): void;
@@ -1,5 +1,7 @@
1
1
  import { TapTracker } from "./scenePicking.js";
2
2
  import { EQUATORIAL_UP, orbitBasis } from "./viewUp.js";
3
+ import { CAMERA_FOV_DEG } from "./sceneFraming.js";
4
+ import { directionAt, LOOK_OUT_NEAR, panLookOut, zoomLookOut } from "./lookOut.js";
3
5
  export function createOrbitCameraState(distance, focus) {
4
6
  return {
5
7
  azimuth: Math.PI * 1.2,
@@ -11,6 +13,7 @@ export function createOrbitCameraState(distance, focus) {
11
13
  focus,
12
14
  fixedPoint: null,
13
15
  transition: [0, 0, 0],
16
+ lookOut: null,
14
17
  cameraAbsolute: [0, 0, 0],
15
18
  targetAbsolute: [0, 0, 0],
16
19
  };
@@ -57,12 +60,16 @@ export function attachOrbitGestures(element, state, getLimits, onTap) {
57
60
  if (pointers.size >= 2) {
58
61
  const spread = pointerSpread(pointers);
59
62
  if (pinchDistance !== null) {
60
- state.distance = clampDistance(state.distance * Math.exp(-(spread - pinchDistance) * PINCH_SENSITIVITY), getLimits());
61
- cancelCameraTransition(state);
63
+ zoomBy(state, Math.exp(-(spread - pinchDistance) * PINCH_SENSITIVITY), getLimits());
62
64
  }
63
65
  pinchDistance = spread;
64
66
  return;
65
67
  }
68
+ if (state.lookOut !== null) {
69
+ panLookOut(state, state.lookOut.fovDeg, next.x - previous.x, next.y - previous.y, window.innerHeight);
70
+ cancelCameraTransition(state);
71
+ return;
72
+ }
66
73
  const sensitivity = event.pointerType === "touch" ? TOUCH_DRAG_SENSITIVITY : DRAG_SENSITIVITY;
67
74
  state.azimuth -= ((next.x - previous.x) / window.innerWidth) * Math.PI * 2 * sensitivity;
68
75
  state.elevation = Math.max(-MAX_ELEVATION, Math.min(MAX_ELEVATION, state.elevation + ((next.y - previous.y) / window.innerHeight) * Math.PI * sensitivity));
@@ -86,8 +93,7 @@ export function attachOrbitGestures(element, state, getLimits, onTap) {
86
93
  };
87
94
  const onWheel = (event) => {
88
95
  event.preventDefault();
89
- state.distance = clampDistance(state.distance * Math.exp(event.deltaY * WHEEL_SENSITIVITY), getLimits());
90
- cancelCameraTransition(state);
96
+ zoomBy(state, Math.exp(event.deltaY * WHEEL_SENSITIVITY), getLimits());
91
97
  };
92
98
  element.addEventListener("pointerdown", onPointerDown);
93
99
  element.addEventListener("pointermove", onPointerMove);
@@ -102,6 +108,14 @@ export function attachOrbitGestures(element, state, getLimits, onTap) {
102
108
  element.removeEventListener("wheel", onWheel);
103
109
  };
104
110
  }
111
+ /** A wheel or pinch step: the distance in orbit, the field of view while looking out. */
112
+ function zoomBy(state, factor, limits) {
113
+ if (state.lookOut !== null)
114
+ zoomLookOut(state.lookOut, factor);
115
+ else
116
+ state.distance = clampDistance(state.distance * factor, limits);
117
+ cancelCameraTransition(state);
118
+ }
105
119
  /** Stops any scripted framing while keeping the viewer's current manual pose. */
106
120
  export function cancelCameraTransition(state) {
107
121
  state.transition.fill(0);
@@ -126,9 +140,11 @@ export function switchFocus(state, focus, newTargetAbsolute) {
126
140
  * Step 1 (before bodies are placed): computes the absolute target/camera in Float64 render axes
127
141
  * and rebases the floating origin when the target drifts away from it, so bodies and camera
128
142
  * always use the same origin within a frame. Scientific state is never read or written here.
143
+ * With `reducedMotion` the distance, angles and focus tween land on their targets in one frame.
129
144
  */
130
- export function resolveCamera(state, focusAbsolute, origin, deltaSeconds, rebaseThreshold, up = EQUATORIAL_UP) {
131
- const decay = Math.exp(-TRANSITION_RATE_PER_S * deltaSeconds);
145
+ export function resolveCamera(state, focusAbsolute, origin, deltaSeconds, rebaseThreshold, up = EQUATORIAL_UP, reducedMotion = false) {
146
+ // Reduced motion: every eased move arrives within this frame (decay 0, blend 1).
147
+ const decay = reducedMotion ? 0 : Math.exp(-TRANSITION_RATE_PER_S * deltaSeconds);
132
148
  const blend = 1 - decay;
133
149
  state.distance += (state.targetDistance - state.distance) * blend;
134
150
  if (Math.abs(state.targetDistance - state.distance) < 1e-9)
@@ -141,14 +157,24 @@ export function resolveCamera(state, focusAbsolute, origin, deltaSeconds, rebase
141
157
  state.transition[i] = 0;
142
158
  state.targetAbsolute[i] = focusAbsolute[i] + state.transition[i];
143
159
  }
144
- const cosEl = Math.cos(state.elevation);
145
160
  const { east, south } = orbitBasis(up);
146
- const [sa, ca, se] = [Math.sin(state.azimuth), Math.cos(state.azimuth), Math.sin(state.elevation)];
147
- const offset = [0, 1, 2].map((k) => state.distance * (cosEl * (sa * east[k] + ca * south[k]) + se * up[k]));
161
+ const direction = directionAt(state.azimuth, state.elevation, east, south, up);
162
+ if (state.lookOut !== null) {
163
+ placeLookOut(state, focusAbsolute, direction);
164
+ origin.rebaseIfFar(state.cameraAbsolute, rebaseThreshold);
165
+ return;
166
+ }
148
167
  for (let i = 0; i < 3; i += 1)
149
- state.cameraAbsolute[i] = state.targetAbsolute[i] + offset[i];
168
+ state.cameraAbsolute[i] = state.targetAbsolute[i] + state.distance * direction[i];
150
169
  origin.rebaseIfFar(state.targetAbsolute, rebaseThreshold);
151
170
  }
171
+ /** Looking out: the camera is at the body's centre and its target one unit along the look direction (a point to aim at, not a place). */
172
+ function placeLookOut(state, bodyAbsolute, direction) {
173
+ for (let i = 0; i < 3; i += 1) {
174
+ state.cameraAbsolute[i] = bodyAbsolute[i];
175
+ state.targetAbsolute[i] = bodyAbsolute[i] + direction[i];
176
+ }
177
+ }
152
178
  function shortestAngleDelta(from, to) {
153
179
  return Math.atan2(Math.sin(to - from), Math.cos(to - from));
154
180
  }
@@ -159,7 +185,8 @@ export function poseCamera(camera, state, focusRadius, origin, far = 5_000, up =
159
185
  camera.position.set(cx, cy, cz);
160
186
  camera.up.set(up[0], up[1], up[2]);
161
187
  camera.lookAt(tx, ty, tz);
162
- camera.near = Math.max(1e-3, 0.1 * (state.distance - focusRadius));
188
+ camera.near = state.lookOut === null ? Math.max(1e-3, 0.1 * (state.distance - focusRadius)) : LOOK_OUT_NEAR;
189
+ camera.fov = state.lookOut?.fovDeg ?? CAMERA_FOV_DEG;
163
190
  camera.far = far;
164
191
  camera.updateProjectionMatrix();
165
192
  }
@@ -1,4 +1,6 @@
1
1
  import type { MutableRefObject } from "react";
2
+ import { type LabelStyle } from "./labelStyle.js";
3
+ import type { SkyColours } from "./skyFigures.js";
2
4
  import type { GlowLook } from "./bodyDraw.js";
3
5
  import { type BodySetLayer, type BodySetLook } from "./bodySet.js";
4
6
  import { type RingLook, type RingSystem } from "../assets/rings.js";
@@ -6,7 +8,7 @@ import type { SceneControls } from "./AstraeusScene.js";
6
8
  import { type DebugReadout } from "./DebugOverlay.js";
7
9
  import { type GroupFill } from "./FrameRateSection.js";
8
10
  import type { FrameSnapshot } from "./frameStats.js";
9
- import { type StartView } from "./viewLink.js";
11
+ import { type CameraView } from "./viewLink.js";
10
12
  import type { ViewUp } from "./viewUp.js";
11
13
  /** The Developer tools' settings bodies that App.tsx hands whole to its folds; each only reads its props and writes the scene's live controls. */
12
14
  type Controls = MutableRefObject<SceneControls>;
@@ -45,8 +47,14 @@ export declare function SkyAndSunSettings({ illuminateAll, setIlluminateAll, vis
45
47
  readonly milkyWayBrightness: number;
46
48
  readonly setMilkyWayBrightness: (value: number) => void;
47
49
  }): import("react").JSX.Element;
48
- export declare function LabelSettings({ controls, hoverBrightness, setHoverBrightness, labelToggles, trackedCount, anchorLabels, setAnchorLabels, hiddenLabels, setHiddenLabels }: {
50
+ export declare function LabelSettings({ controls, hoverBrightness, setHoverBrightness, labelToggles, trackedCount, anchorLabels, setAnchorLabels, hiddenLabels, setHiddenLabels, labelStyle, setLabelStyle, skyColours, setSkyColours, hasSky }: {
49
51
  readonly controls: Controls;
52
+ readonly labelStyle: LabelStyle;
53
+ readonly setLabelStyle: (style: LabelStyle) => void;
54
+ readonly skyColours: SkyColours;
55
+ readonly setSkyColours: (colours: SkyColours) => void;
56
+ /** Whether the sky is drawn, so its line colours have something to act on. */
57
+ readonly hasSky: boolean;
50
58
  readonly hoverBrightness: number;
51
59
  readonly setHoverBrightness: (value: number) => void;
52
60
  readonly labelToggles: readonly {
@@ -60,7 +68,7 @@ export declare function LabelSettings({ controls, hoverBrightness, setHoverBrigh
60
68
  readonly setHiddenLabels: (hidden: ReadonlySet<string>) => void;
61
69
  }): import("react").JSX.Element;
62
70
  export declare function ViewLinkReadout({ viewNow, viewLink, scale, upChoice }: {
63
- readonly viewNow: StartView | null;
71
+ readonly viewNow: CameraView | null;
64
72
  readonly viewLink: {
65
73
  readonly url: string;
66
74
  readonly copied: boolean;