astraeus 0.8.0 → 0.9.0

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