astraeus 0.4.0 → 0.5.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 (78) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +64 -10
  3. package/data/ephemerides/planets/planets.json +1 -1
  4. package/package.json +1 -1
  5. package/src/api/AstraeusScene.d.ts +9 -1
  6. package/src/api/AstraeusScene.js +26 -4
  7. package/src/api/AstraeusScene.node.js +26 -4
  8. package/src/api/data.js +11 -1
  9. package/src/api/errors.d.ts +1 -1
  10. package/src/api/index.d.ts +2 -1
  11. package/src/api/mount.d.ts +16 -0
  12. package/src/api/mount.js +13 -1
  13. package/src/api/mount.node.js +13 -1
  14. package/src/api/pathProvenance.d.ts +10 -0
  15. package/src/api/pathProvenance.js +34 -0
  16. package/src/api/scene.d.ts +7 -1
  17. package/src/api/scene.js +103 -14
  18. package/src/api/story.d.ts +41 -1
  19. package/src/api/story.js +63 -1
  20. package/src/api/sunOrbit.d.ts +3 -3
  21. package/src/api/sunOrbit.js +92 -24
  22. package/src/api/viewerLink.d.ts +40 -0
  23. package/src/api/viewerLink.js +86 -0
  24. package/src/app/App.d.ts +4 -1
  25. package/src/app/App.js +42 -6
  26. package/src/app/App.node.js +42 -6
  27. package/src/app/AstraeusScene.d.ts +7 -0
  28. package/src/app/BodySetView.js +3 -2
  29. package/src/app/KeplerPoints.d.ts +1 -1
  30. package/src/app/KeplerPoints.js +3 -2
  31. package/src/app/PointsView.js +3 -2
  32. package/src/app/TrackedBodyView.js +3 -2
  33. package/src/app/bodyDraw.js +3 -2
  34. package/src/app/dotMaterial.d.ts +11 -0
  35. package/src/app/dotMaterial.js +38 -0
  36. package/src/app/experienceDefinition.d.ts +12 -0
  37. package/src/app/mission.d.ts +1 -1
  38. package/src/app/mission.js +1 -1
  39. package/src/app/openClock.d.ts +1 -1
  40. package/src/app/openClock.js +3 -0
  41. package/src/app/sceneContentsHooks.js +2 -1
  42. package/src/app/sceneFrame.d.ts +2 -2
  43. package/src/app/sceneFrame.js +6 -1
  44. package/src/app/sceneFraming.d.ts +1 -1
  45. package/src/app/sceneFraming.js +9 -3
  46. package/src/app/viewerPort.d.ts +33 -0
  47. package/src/app/viewerPort.js +1 -0
  48. package/src/core/bodies/io.js +1 -1
  49. package/src/core/bodies/jupiterMoons.d.ts +1 -1
  50. package/src/core/bodies/jupiterMoons.js +6 -6
  51. package/src/core/bodies/moonSystem.d.ts +15 -1
  52. package/src/core/bodies/moonSystem.js +58 -7
  53. package/src/core/bodies/outerPlanets.js +1 -1
  54. package/src/core/bodies/planetMoons.js +10 -10
  55. package/src/core/chebyshevEphemeris.d.ts +7 -1
  56. package/src/core/chebyshevEphemeris.js +24 -7
  57. package/src/core/clock.d.ts +8 -0
  58. package/src/core/clock.js +14 -0
  59. package/src/core/pacing.d.ts +24 -0
  60. package/src/core/pacing.js +35 -0
  61. package/src/core/planetModels.d.ts +4 -1
  62. package/src/core/planetModels.js +6 -1
  63. package/src/core/planetSeries.d.ts +3 -0
  64. package/src/core/planetSeries.js +8 -1
  65. package/src/core/timeWindow.d.ts +2 -0
  66. package/src/core/timeWindow.js +4 -3
  67. package/src/shell/AstraeusShell.d.ts +6 -2
  68. package/src/shell/AstraeusShell.js +3 -3
  69. package/src/shell/AstraeusShell.node.js +3 -3
  70. package/src/shell/TimelineBar.d.ts +4 -2
  71. package/src/shell/TimelineBar.js +15 -6
  72. package/src/shell/TimelineBar.node.js +15 -6
  73. package/src/shell/experience.d.ts +3 -1
  74. package/src/shell/infoModel.js +5 -4
  75. package/src/shell/timelineModel.d.ts +2 -3
  76. package/src/shell/timelineModel.js +3 -11
  77. package/src/synthetic/syntheticJourneyScene.d.ts +9 -0
  78. package/src/synthetic/syntheticJourneyScene.js +75 -0
@@ -0,0 +1,86 @@
1
+ import { SceneError } from "./errors.js";
2
+ import { toUtcMs } from "./time.js";
3
+ const NOT_OPEN = "the viewer is not drawn yet (or is gone); wait for `ready` first";
4
+ /**
5
+ * Joins a host page to a mounted viewer's one clock: reads, sets and change callbacks. Created by `mount` and `AstraeusScene`; the viewer attaches
6
+ * its clock controls when it opens and detaches when it closes.
7
+ */
8
+ export class ViewerLink {
9
+ #control;
10
+ #last;
11
+ #rateSource = "scene";
12
+ #listeners = new Set();
13
+ attach(control) {
14
+ this.#control = control;
15
+ this.#last = control.read();
16
+ this.#rateSource = "scene";
17
+ }
18
+ detach() {
19
+ this.#control = undefined;
20
+ this.#last = undefined;
21
+ }
22
+ /** Stops all callbacks for good (the host unmounted). */
23
+ close() {
24
+ this.detach();
25
+ this.#listeners.clear();
26
+ }
27
+ get rateSource() { return this.#rateSource; }
28
+ /** The viewer's time (Unix milliseconds UTC), or undefined before it is drawn or after it is gone. */
29
+ get time() { return this.#control?.read().timeUtcMs; }
30
+ get rate() { return this.#control?.read().rate; }
31
+ get playing() { return this.#control?.read().playing; }
32
+ setTime(time) {
33
+ const control = this.#open("setTime");
34
+ const timeUtcMs = toUtcMs(time, "setTime");
35
+ const { startUtcMs, endUtcMs } = control.window;
36
+ if (timeUtcMs < startUtcMs || timeUtcMs > endUtcMs) {
37
+ throw new SceneError("bad-time", `setTime: ${new Date(timeUtcMs).toISOString()} is outside the timeline (${new Date(startUtcMs).toISOString()} to ${new Date(endUtcMs).toISOString()})`);
38
+ }
39
+ control.seek(timeUtcMs);
40
+ this.publish(control.read(), "host");
41
+ }
42
+ /**
43
+ * Only a speed the timeline offers is taken, so the speed picker always shows what is running; any other number throws `bad-timeline`.
44
+ * `"auto"` hands the rate back to the scene's pacing (`setTimeline({ pacing })`) and throws `bad-timeline` when the scene has none. The in-between speeds pacing
45
+ * runs at are never set through here; they arrive in `onChange` and `rate`.
46
+ */
47
+ setRate(rate) {
48
+ const control = this.#open("setRate");
49
+ if (rate === "auto") {
50
+ if (!control.paced)
51
+ throw new SceneError("bad-timeline", "setRate: \"auto\" needs a scene with pacing; give setTimeline({ pacing })");
52
+ control.setRate("auto");
53
+ this.#rateSource = "scene";
54
+ this.publish(control.read(), "host");
55
+ return;
56
+ }
57
+ if (!control.rates.includes(rate))
58
+ throw new SceneError("bad-timeline", `setRate: ${String(rate)} is not one of the offered speeds (${control.rates.join(", ")}); offer it with setTimeline({ rates })`);
59
+ control.setRate(rate);
60
+ this.#rateSource = "chosen";
61
+ this.publish(control.read(), "host");
62
+ }
63
+ /** Calls `listener` whenever the time, speed or playing state changes; returns the function that stops it. */
64
+ onChange(listener) {
65
+ this.#listeners.add(listener);
66
+ return () => { this.#listeners.delete(listener); };
67
+ }
68
+ publish(state, cause) {
69
+ const last = this.#last;
70
+ if (last !== undefined && last.timeUtcMs === state.timeUtcMs && last.rate === state.rate && last.playing === state.playing && last.auto === state.auto)
71
+ return;
72
+ if (state.auto !== undefined)
73
+ this.#rateSource = state.auto ? "scene" : "chosen";
74
+ else if (cause === "visitor" && last !== undefined && last.rate !== state.rate)
75
+ this.#rateSource = "chosen";
76
+ this.#last = state;
77
+ const change = { time: state.timeUtcMs, rate: state.rate, playing: state.playing, cause };
78
+ for (const listener of [...this.#listeners])
79
+ listener(change);
80
+ }
81
+ #open(what) {
82
+ if (this.#control === undefined)
83
+ throw new SceneError("missing-data", `${what}: ${NOT_OPEN}`);
84
+ return this.#control;
85
+ }
86
+ }
package/src/app/App.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { ViewerPort } from "./viewerPort.js";
1
2
  import { type ExperienceDefinition } from "./experienceDefinition.js";
2
3
  /** The labels switched off at the start: objects that set `showLabel: false`, then `?labels=<id>:on|off,...` over them. */
3
4
  export declare function hiddenLabelsFrom(search: string, objects: readonly {
@@ -9,9 +10,11 @@ export declare function loopFromSearch(search: string, fallback: boolean): boole
9
10
  /**
10
11
  * `onOpenAddress`: the entry's way to open a switch's address in place; without it a switch navigates the page.
11
12
  * `writeTitle`: whether the page heading is set to the experience's name (default true); `mount` and `AstraeusScene` pass false so a host page keeps its own title.
13
+ * `host`: the link a host page reads and sets the one clock through (time, speed) and hears its changes from; every change goes through the same handlers as the timeline's own controls.
12
14
  */
13
- export declare function App({ definition, onOpenAddress, writeTitle }: {
15
+ export declare function App({ definition, onOpenAddress, writeTitle, host }: {
14
16
  readonly definition: ExperienceDefinition;
15
17
  readonly onOpenAddress?: (address: string) => void;
16
18
  readonly writeTitle?: boolean;
19
+ readonly host?: ViewerPort;
17
20
  }): import("react").JSX.Element;
package/src/app/App.js CHANGED
@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
2
2
  import { Suspense, useCallback, useEffect, useMemo, useRef, useState } from "react";
3
3
  import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
4
4
  import { viewUpFromSearch, viewUpVector } from "./viewUp.js";
5
+ import { applyPacing } from "../core/pacing.js";
5
6
  import { openClock } from "./openClock.js";
6
7
  import { createSolarSystemScale } from "../core/scalePolicy.js";
7
8
  import { bodySetsOf, cameraReachOf, catalogueOf, compositionOf, experienceWithGroups, groupsOf, initialObjectIdOf, mountedBodiesOf, pageTitleOf, scaleChoiceIdsOf, sceneCenterOf, sunCentredOf, trackedBodiesOf, visualOverridesOf } from "./experienceDefinition.js";
@@ -106,6 +107,8 @@ function buildRuntime(definition) {
106
107
  cameraReach: cameraReachOf(definition),
107
108
  sky: skySettingsOf(definition),
108
109
  loopWindow: definition.experience.window,
110
+ ...(definition.experience.hideTimeline === true ? {} : { stopAtWindow: true }),
111
+ ...(definition.pacing === undefined ? {} : { pacing: definition.pacing }),
109
112
  up: viewUpVector(startViewUp(definition)),
110
113
  };
111
114
  }
@@ -123,6 +126,7 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
123
126
  cameraRequest: null,
124
127
  showAnchorLabels: labelStart(definition) === true && runtime.trackedBodies.length > 0,
125
128
  loop: loopFromSearch(search, definition.loop === true),
129
+ ...(definition.pacing === undefined ? {} : { paceAuto: true }),
126
130
  up: viewUpVector(startViewUp(definition)),
127
131
  showMilkyWay: runtime.sky.milkyWay,
128
132
  bodyMarker: markerSettingsFromSearch(search),
@@ -145,8 +149,9 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
145
149
  /**
146
150
  * `onOpenAddress`: the entry's way to open a switch's address in place; without it a switch navigates the page.
147
151
  * `writeTitle`: whether the page heading is set to the experience's name (default true); `mount` and `AstraeusScene` pass false so a host page keeps its own title.
152
+ * `host`: the link a host page reads and sets the one clock through (time, speed) and hears its changes from; every change goes through the same handlers as the timeline's own controls.
148
153
  */
149
- export function App({ definition, onOpenAddress, writeTitle = true }) {
154
+ export function App({ definition, onOpenAddress, writeTitle = true, host }) {
150
155
  // The page heading names the experience once it is open; app.html says only "Astraeus" until then.
151
156
  useEffect(() => {
152
157
  if (writeTitle)
@@ -261,15 +266,45 @@ export function App({ definition, onOpenAddress, writeTitle = true }) {
261
266
  controls.current.policy = scalePolicyFor(id, suppliedPolicies);
262
267
  setScale(id);
263
268
  }, [suppliedPolicies]);
269
+ const stateNow = useCallback(() => ({ ...runtime.clock.snapshot(), ...(runtime.pacing === undefined ? {} : { auto: controls.current.paceAuto === true }) }), [runtime]);
264
270
  useEffect(() => {
265
271
  const id = window.setInterval(() => {
266
272
  // The readout wraps with the scene, so the shown time never rests past the end while looping.
267
273
  if (controls.current.loop === true)
268
274
  runtime.clock.wrapWithin(runtime.loopWindow);
275
+ else if (runtime.stopAtWindow === true && runtime.loopWindow !== undefined)
276
+ runtime.clock.stopWithin(runtime.loopWindow);
277
+ if (controls.current.paceAuto === true && runtime.pacing !== undefined)
278
+ applyPacing(runtime.clock, runtime.pacing);
269
279
  setClockSnapshot(runtime.clock.snapshot());
280
+ host?.publish(stateNow(), "playback");
270
281
  }, 100);
271
282
  return () => window.clearInterval(id);
283
+ }, [runtime, host, stateNow]);
284
+ // The host reaches the one clock through the same seek and rate handlers a visitor's timeline uses.
285
+ const seekTo = useCallback((timeUtcMs) => {
286
+ runtime.clock.seek(timeUtcMs);
287
+ setClockSnapshot(runtime.clock.snapshot());
288
+ }, [runtime]);
289
+ // A speed picked by the visitor or the host takes over from pacing; "auto" gives the rate back to it.
290
+ const [paceAuto, setPaceAuto] = useState(controls.current.paceAuto === true);
291
+ const changeRate = useCallback((rate) => {
292
+ if (rate === "auto") {
293
+ if (runtime.pacing !== undefined)
294
+ applyPacing(runtime.clock, runtime.pacing);
295
+ }
296
+ else
297
+ runtime.clock.setRate(rate);
298
+ controls.current.paceAuto = rate === "auto";
299
+ setPaceAuto(rate === "auto");
300
+ setClockSnapshot(runtime.clock.snapshot());
272
301
  }, [runtime]);
302
+ useEffect(() => {
303
+ if (host === undefined)
304
+ return undefined;
305
+ host.attach({ window: runtime.loopWindow, rates: definition.experience.rates, paced: runtime.pacing !== undefined, read: stateNow, seek: seekTo, setRate: changeRate });
306
+ return () => host.detach();
307
+ }, [host, runtime, definition, seekTo, changeRate]);
273
308
  useEffect(() => {
274
309
  if (!developerMode)
275
310
  return undefined;
@@ -385,17 +420,18 @@ export function App({ definition, onOpenAddress, writeTitle = true }) {
385
420
  ];
386
421
  const presentGroups = groups.filter((group) => group !== null);
387
422
  const developerTools = (_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, { id: group.id, title: group.title, defaultOpen: index === 0, className: `dev-group${group.className === undefined ? "" : ` ${group.className}`}`, children: group.body }, group.id)))] }) }) }));
388
- return (_jsx(AstraeusShell, { experience: shellExperience, snapshot: clockSnapshot, developerMode: developerMode, onDeveloperModeChange: setDeveloperMode, onTogglePlayback: () => {
423
+ return (_jsx(AstraeusShell, { experience: shellExperience, snapshot: clockSnapshot, paceAuto: runtime.pacing === undefined ? undefined : paceAuto, developerMode: developerMode, onDeveloperModeChange: setDeveloperMode, onTogglePlayback: () => {
389
424
  if (runtime.clock.playing)
390
425
  runtime.clock.pause();
391
426
  else
392
427
  runtime.clock.play();
393
428
  setClockSnapshot(runtime.clock.snapshot());
429
+ host?.publish(stateNow(), "visitor");
394
430
  }, onRateChange: (rate) => {
395
- runtime.clock.setRate(rate);
396
- setClockSnapshot(runtime.clock.snapshot());
431
+ changeRate(rate);
432
+ host?.publish(stateNow(), "visitor");
397
433
  }, onSeek: (timeUtcMs) => {
398
- runtime.clock.seek(timeUtcMs);
399
- setClockSnapshot(runtime.clock.snapshot());
434
+ seekTo(timeUtcMs);
435
+ host?.publish(stateNow(), "visitor");
400
436
  }, onCameraRequest: updateCameraRequest, onSelectionChange: updateSelectedObject, scaleId: scale, onScaleChange: updateScale, scaleChoices: scaleChoices, switcher: switcherOf(definition, runtime, onOpenAddress), displaySwitches: displaySwitches, metricsFor: metricsFor, developerTools: developerTools, 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 }) }) }));
401
437
  }
@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
2
2
  import { Suspense, useCallback, useEffect, useMemo, useRef, useState } from "react";
3
3
  import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
4
4
  import { viewUpFromSearch, viewUpVector } from "./viewUp.js";
5
+ import { applyPacing } from "../core/pacing.js";
5
6
  import { openClock } from "./openClock.js";
6
7
  import { createSolarSystemScale } from "../core/scalePolicy.js";
7
8
  import { bodySetsOf, cameraReachOf, catalogueOf, compositionOf, experienceWithGroups, groupsOf, initialObjectIdOf, mountedBodiesOf, pageTitleOf, scaleChoiceIdsOf, sceneCenterOf, sunCentredOf, trackedBodiesOf, visualOverridesOf } from "./experienceDefinition.js";
@@ -106,6 +107,8 @@ function buildRuntime(definition) {
106
107
  cameraReach: cameraReachOf(definition),
107
108
  sky: skySettingsOf(definition),
108
109
  loopWindow: definition.experience.window,
110
+ ...(definition.experience.hideTimeline === true ? {} : { stopAtWindow: true }),
111
+ ...(definition.pacing === undefined ? {} : { pacing: definition.pacing }),
109
112
  up: viewUpVector(startViewUp(definition)),
110
113
  };
111
114
  }
@@ -123,6 +126,7 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
123
126
  cameraRequest: null,
124
127
  showAnchorLabels: labelStart(definition) === true && runtime.trackedBodies.length > 0,
125
128
  loop: loopFromSearch(search, definition.loop === true),
129
+ ...(definition.pacing === undefined ? {} : { paceAuto: true }),
126
130
  up: viewUpVector(startViewUp(definition)),
127
131
  showMilkyWay: runtime.sky.milkyWay,
128
132
  bodyMarker: markerSettingsFromSearch(search),
@@ -145,8 +149,9 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
145
149
  /**
146
150
  * `onOpenAddress`: the entry's way to open a switch's address in place; without it a switch navigates the page.
147
151
  * `writeTitle`: whether the page heading is set to the experience's name (default true); `mount` and `AstraeusScene` pass false so a host page keeps its own title.
152
+ * `host`: the link a host page reads and sets the one clock through (time, speed) and hears its changes from; every change goes through the same handlers as the timeline's own controls.
148
153
  */
149
- export function App({ definition, onOpenAddress, writeTitle = true }) {
154
+ export function App({ definition, onOpenAddress, writeTitle = true, host }) {
150
155
  // The page heading names the experience once it is open; app.html says only "Astraeus" until then.
151
156
  useEffect(() => {
152
157
  if (writeTitle)
@@ -261,15 +266,45 @@ export function App({ definition, onOpenAddress, writeTitle = true }) {
261
266
  controls.current.policy = scalePolicyFor(id, suppliedPolicies);
262
267
  setScale(id);
263
268
  }, [suppliedPolicies]);
269
+ const stateNow = useCallback(() => ({ ...runtime.clock.snapshot(), ...(runtime.pacing === undefined ? {} : { auto: controls.current.paceAuto === true }) }), [runtime]);
264
270
  useEffect(() => {
265
271
  const id = window.setInterval(() => {
266
272
  // The readout wraps with the scene, so the shown time never rests past the end while looping.
267
273
  if (controls.current.loop === true)
268
274
  runtime.clock.wrapWithin(runtime.loopWindow);
275
+ else if (runtime.stopAtWindow === true && runtime.loopWindow !== undefined)
276
+ runtime.clock.stopWithin(runtime.loopWindow);
277
+ if (controls.current.paceAuto === true && runtime.pacing !== undefined)
278
+ applyPacing(runtime.clock, runtime.pacing);
269
279
  setClockSnapshot(runtime.clock.snapshot());
280
+ host?.publish(stateNow(), "playback");
270
281
  }, 100);
271
282
  return () => window.clearInterval(id);
283
+ }, [runtime, host, stateNow]);
284
+ // The host reaches the one clock through the same seek and rate handlers a visitor's timeline uses.
285
+ const seekTo = useCallback((timeUtcMs) => {
286
+ runtime.clock.seek(timeUtcMs);
287
+ setClockSnapshot(runtime.clock.snapshot());
288
+ }, [runtime]);
289
+ // A speed picked by the visitor or the host takes over from pacing; "auto" gives the rate back to it.
290
+ const [paceAuto, setPaceAuto] = useState(controls.current.paceAuto === true);
291
+ const changeRate = useCallback((rate) => {
292
+ if (rate === "auto") {
293
+ if (runtime.pacing !== undefined)
294
+ applyPacing(runtime.clock, runtime.pacing);
295
+ }
296
+ else
297
+ runtime.clock.setRate(rate);
298
+ controls.current.paceAuto = rate === "auto";
299
+ setPaceAuto(rate === "auto");
300
+ setClockSnapshot(runtime.clock.snapshot());
272
301
  }, [runtime]);
302
+ useEffect(() => {
303
+ if (host === undefined)
304
+ return undefined;
305
+ host.attach({ window: runtime.loopWindow, rates: definition.experience.rates, paced: runtime.pacing !== undefined, read: stateNow, seek: seekTo, setRate: changeRate });
306
+ return () => host.detach();
307
+ }, [host, runtime, definition, seekTo, changeRate]);
273
308
  useEffect(() => {
274
309
  if (!developerMode)
275
310
  return undefined;
@@ -385,17 +420,18 @@ export function App({ definition, onOpenAddress, writeTitle = true }) {
385
420
  ];
386
421
  const presentGroups = groups.filter((group) => group !== null);
387
422
  const developerTools = (_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, { id: group.id, title: group.title, defaultOpen: index === 0, className: `dev-group${group.className === undefined ? "" : ` ${group.className}`}`, children: group.body }, group.id)))] }) }) }));
388
- return (_jsx(AstraeusShell, { experience: shellExperience, snapshot: clockSnapshot, developerMode: developerMode, onDeveloperModeChange: setDeveloperMode, onTogglePlayback: () => {
423
+ return (_jsx(AstraeusShell, { experience: shellExperience, snapshot: clockSnapshot, paceAuto: runtime.pacing === undefined ? undefined : paceAuto, developerMode: developerMode, onDeveloperModeChange: setDeveloperMode, onTogglePlayback: () => {
389
424
  if (runtime.clock.playing)
390
425
  runtime.clock.pause();
391
426
  else
392
427
  runtime.clock.play();
393
428
  setClockSnapshot(runtime.clock.snapshot());
429
+ host?.publish(stateNow(), "visitor");
394
430
  }, onRateChange: (rate) => {
395
- runtime.clock.setRate(rate);
396
- setClockSnapshot(runtime.clock.snapshot());
431
+ changeRate(rate);
432
+ host?.publish(stateNow(), "visitor");
397
433
  }, onSeek: (timeUtcMs) => {
398
- runtime.clock.seek(timeUtcMs);
399
- setClockSnapshot(runtime.clock.snapshot());
434
+ seekTo(timeUtcMs);
435
+ host?.publish(stateNow(), "visitor");
400
436
  }, onCameraRequest: updateCameraRequest, onSelectionChange: updateSelectedObject, scaleId: scale, onScaleChange: updateScale, scaleChoices: scaleChoices, switcher: switcherOf(definition, runtime, onOpenAddress), displaySwitches: displaySwitches, metricsFor: metricsFor, developerTools: developerTools, 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 }) }) }));
401
437
  }
@@ -1,4 +1,5 @@
1
1
  import type { SimulationClock } from "../core/clock.js";
2
+ import type { Pacing } from "../core/pacing.js";
2
3
  import type { BodyId } from "../core/body.js";
3
4
  import type { ScalePolicy } from "../core/scalePolicy.js";
4
5
  import type { StateResolver } from "../core/stateResolver.js";
@@ -27,7 +28,11 @@ export interface SceneRuntime {
27
28
  readonly startUtcMs: number;
28
29
  readonly endUtcMs: number;
29
30
  };
31
+ /** Playback stops on the edge of `loopWindow` when it runs past it (a scene with a timeline bar that does not loop); absent: the clock runs on. */
32
+ readonly stopAtWindow?: boolean;
30
33
  readonly clock: SimulationClock;
34
+ /** Paced playback (see `pacedRate`); absent: the clock keeps the rate it was given. */
35
+ readonly pacing?: Pacing;
31
36
  /** The one resolver every position in the scene comes from. */
32
37
  readonly resolver: StateResolver;
33
38
  /** The catalogue the bodies come from; absent means the built-in one. */
@@ -88,6 +93,8 @@ export interface SceneControls {
88
93
  illuminateAll: boolean;
89
94
  /** Looping playback is on (live; set from the experience, `?loop=` and Developer > Display settings). Needs `SceneRuntime.loopWindow`. */
90
95
  loop?: boolean;
96
+ /** Paced playback is in charge of the rate (live): true until a visitor or the host picks a speed, true again when they choose Auto. Meaningful with `SceneRuntime.pacing`. */
97
+ paceAuto?: boolean;
91
98
  /** The render-frame up vector now in force (live; Developer > Display settings). Absent: the runtime's own. Switching it re-poses the camera in place. */
92
99
  up?: RenderVector;
93
100
  /** Ids of objects whose label is switched off (live). Their objects stay listed and selectable. */
@@ -1,7 +1,8 @@
1
1
  // The members of a body set as one batch of dots (one draw call, like the showers' points) and one batch of balls (an instanced sphere,
2
2
  // one draw call). A dot has a pixel floor, so a member never vanishes; the ball is the member at its true size and is drawn with the depth
3
3
  // test, so once it is wider on screen than the dot it covers the dot (the dot sits at the ball's centre, behind its near surface).
4
- import { AmbientLight, BufferAttribute, BufferGeometry, Color, DirectionalLight, Group, InstancedBufferAttribute, InstancedMesh, Matrix4, MeshLambertMaterial, Points, PointsMaterial, SphereGeometry, Vector3, } from "three";
4
+ import { AmbientLight, BufferAttribute, BufferGeometry, Color, DirectionalLight, Group, InstancedBufferAttribute, InstancedMesh, Matrix4, MeshLambertMaterial, Points, SphereGeometry, Vector3, } from "three";
5
+ import { dotMaterial } from "./dotMaterial.js";
5
6
  import { projectedRadiusPx } from "./bodyDraw.js";
6
7
  import { bodyLightDirections } from "./lighting.js";
7
8
  import { eqjToRenderVector } from "./renderCoordinates.js";
@@ -47,7 +48,7 @@ export class BodySetView {
47
48
  // Each dot and ball carries its own colour, so a lit family can differ from the rest; the material colour stays white.
48
49
  this.#colours = new BufferAttribute(new Float32Array(3 * n), 3);
49
50
  geometry.setAttribute("color", this.#colours);
50
- this.#pointMaterial = new PointsMaterial({ size: 3, sizeAttenuation: false, depthWrite: true, vertexColors: true });
51
+ this.#pointMaterial = dotMaterial({ size: 3, sizeAttenuation: false, depthWrite: true, vertexColors: true });
51
52
  this.#points = new Points(geometry, this.#pointMaterial);
52
53
  this.#points.frustumCulled = false;
53
54
  this.#points.layers.set(TRACK_LAYER);
@@ -1,4 +1,4 @@
1
- import { Points, PointsMaterial } from "three";
1
+ import { Points, type PointsMaterial } from "three";
2
2
  import type { KeplerElements } from "../core/keplerElements.js";
3
3
  export declare class KeplerPoints {
4
4
  #private;
@@ -1,6 +1,7 @@
1
1
  // Purpose: the drawn dots of an orbit group that the graphics chip positions every frame from each member's ellipse (see keplerShader).
2
2
  // Uploads the per-member numbers once; each frame only a handful of uniforms change.
3
- import { BufferAttribute, BufferGeometry, Points, PointsMaterial, Vector3 } from "three";
3
+ import { BufferAttribute, BufferGeometry, Points, Vector3 } from "three";
4
+ import { dotMaterial } from "./dotMaterial.js";
4
5
  import { KEPLER_ATTRIBUTES_GLSL, KEPLER_BEGIN_VERTEX_GLSL, createKeplerAttributes, epochWindowSeconds, keplerGlsl, keplerLocalF32, setKeplerEpoch, } from "./keplerShader.js";
5
6
  import { TRACK_LAYER } from "./TrackedBodyView.js";
6
7
  /** Largest `n dt` the fastest member may accumulate either side of the epoch; keeps the 32-bit phase error under ~1e-7 of a turn. */
@@ -27,7 +28,7 @@ export class KeplerPoints {
27
28
  geometry.setAttribute("keplerQ", new BufferAttribute(this.#attributes.axisQ, 3));
28
29
  this.#shape = new BufferAttribute(this.#attributes.shape, 3);
29
30
  geometry.setAttribute("keplerShape", this.#shape);
30
- this.material = new PointsMaterial({ color, size: sizePx, sizeAttenuation: false, transparent: true, opacity: 0.9, depthWrite: false });
31
+ this.material = dotMaterial({ color, size: sizePx, sizeAttenuation: false, transparent: true, opacity: 0.9, depthWrite: false });
31
32
  this.material.onBeforeCompile = (shader) => this.#placeInVertexShader(shader);
32
33
  this.material.customProgramCacheKey = () => "astraeus-points-kepler";
33
34
  this.points = new Points(geometry, this.material);
@@ -1,4 +1,5 @@
1
- import { BufferAttribute, BufferGeometry, Group, Points, PointsMaterial, Vector3 } from "three";
1
+ import { BufferAttribute, BufferGeometry, Group, Points, Vector3 } from "three";
2
+ import { dotMaterial } from "./dotMaterial.js";
2
3
  import { fillKeplerRangeKm } from "../core/keplerElements.js";
3
4
  import { KeplerPoints } from "./KeplerPoints.js";
4
5
  import { eqjToRenderVector } from "./renderCoordinates.js";
@@ -102,7 +103,7 @@ export class PointsView {
102
103
  this.#to = new BufferAttribute(new Float32Array(3 * count), 3);
103
104
  geometry.setAttribute("position", this.#from);
104
105
  geometry.setAttribute("positionTo", this.#to);
105
- this.#material = new PointsMaterial({
106
+ this.#material = dotMaterial({
106
107
  color: layer.color,
107
108
  size: layer.pointSizePx ?? DEFAULT_POINT_SIZE_PX,
108
109
  sizeAttenuation: false,
@@ -1,4 +1,5 @@
1
- import { BufferAttribute, BufferGeometry, DataTexture, Group, Line, LineBasicMaterial, Mesh, MeshBasicMaterial, Points, PointsMaterial, RGBAFormat, SphereGeometry, Vector3, } from "three";
1
+ import { BufferAttribute, BufferGeometry, DataTexture, Group, Line, LineBasicMaterial, Mesh, MeshBasicMaterial, Points, RGBAFormat, SphereGeometry, Vector3, } from "three";
2
+ import { dotMaterial } from "./dotMaterial.js";
2
3
  import { anchorLabelsOf, markerRadiusUnits, sampleTrackedPositions, stateClampedToBounds, stateIfInBounds, travelledCount } from "./mission.js";
3
4
  import { mapPathKm, relativeTrailKm, shiftedBy } from "./pathRules.js";
4
5
  import { eqjToRenderVector } from "./renderCoordinates.js";
@@ -83,7 +84,7 @@ export class TrackedBodyView {
83
84
  this.#marker.layers.set(TRACK_LAYER);
84
85
  const anchorGeometry = new BufferGeometry();
85
86
  anchorGeometry.setAttribute("position", new BufferAttribute(new Float32Array(this.#anchorKm.length), 3));
86
- this.#anchors = new Points(anchorGeometry, new PointsMaterial({
87
+ this.#anchors = new Points(anchorGeometry, dotMaterial({
87
88
  color: "#f0e6da",
88
89
  map: anchorSpriteTexture(),
89
90
  size: 9,
@@ -1,4 +1,5 @@
1
- import { AdditiveBlending, BufferAttribute, BufferGeometry, CanvasTexture, Group, Points, PointsMaterial, Sprite, SpriteMaterial } from "three";
1
+ import { AdditiveBlending, BufferAttribute, BufferGeometry, CanvasTexture, Group, Points, Sprite, SpriteMaterial } from "three";
2
+ import { dotMaterial } from "./dotMaterial.js";
2
3
  import { textureUrlFor } from "../assets/licence.js";
3
4
  /**
4
5
  * A body with both an equatorial and a polar radius is a spheroid whose two radii are mapped independently, so
@@ -49,7 +50,7 @@ export function createMarker(asset, layer, override, fallbackPx) {
49
50
  const position = new BufferAttribute(new Float32Array(3), 3);
50
51
  const geometry = new BufferGeometry();
51
52
  geometry.setAttribute("position", position);
52
- const points = new Points(geometry, new PointsMaterial({ color, size: sizePx, sizeAttenuation: false, depthTest: false }));
53
+ const points = new Points(geometry, dotMaterial({ color, size: sizePx, sizeAttenuation: false, depthTest: false }));
53
54
  points.frustumCulled = false;
54
55
  points.layers.set(layer);
55
56
  const group = new Group();
@@ -0,0 +1,11 @@
1
+ import { PointsMaterial, type PointsMaterialParameters } from "three";
2
+ /** Frees the shared dot picture (an unmounted scene's renderer must not stay reachable through it); the next dot makes a new one. */
3
+ export declare function releaseDotTexture(): void;
4
+ /**
5
+ * The one way the engine makes a far-away dot (body marker, group dot, anchor): a round `PointsMaterial`.
6
+ * A map plus `alphaTest` rather than a fragment discard, because the group materials already patch the
7
+ * vertex shader through `onBeforeCompile` and the stock fragment chunks handle the map, opacity and
8
+ * vertex colours unchanged; the cutoff keeps the edge crisp at 2-4 px. Callers pass the same size and
9
+ * colour as before; only the shape differs. A caller's own `map` (the anchor ring) replaces the disc.
10
+ */
11
+ export declare function dotMaterial(parameters: PointsMaterialParameters): PointsMaterial;
@@ -0,0 +1,38 @@
1
+ import { DataTexture, PointsMaterial, RGBAFormat } from "three";
2
+ const DOT_TEXTURE_PX = 32;
3
+ let dotTexture = null;
4
+ /**
5
+ * A white disc with a one-pixel soft edge, built from pixels (no DOM needed). An untextured WebGL point
6
+ * is a square; sampled through `gl_PointCoord` this makes it a circle.
7
+ */
8
+ function roundDotTexture() {
9
+ if (dotTexture !== null)
10
+ return dotTexture;
11
+ const size = DOT_TEXTURE_PX;
12
+ const pixels = new Uint8Array(size * size * 4);
13
+ for (let y = 0; y < size; y += 1) {
14
+ for (let x = 0; x < size; x += 1) {
15
+ const r = Math.hypot(x + 0.5 - size / 2, y + 0.5 - size / 2);
16
+ const alpha = Math.min(1, Math.max(0, size / 2 - r));
17
+ pixels.set([255, 255, 255, Math.round(alpha * 255)], (y * size + x) * 4);
18
+ }
19
+ }
20
+ dotTexture = new DataTexture(pixels, size, size, RGBAFormat);
21
+ dotTexture.needsUpdate = true;
22
+ return dotTexture;
23
+ }
24
+ /** Frees the shared dot picture (an unmounted scene's renderer must not stay reachable through it); the next dot makes a new one. */
25
+ export function releaseDotTexture() {
26
+ dotTexture?.dispose();
27
+ dotTexture = null;
28
+ }
29
+ /**
30
+ * The one way the engine makes a far-away dot (body marker, group dot, anchor): a round `PointsMaterial`.
31
+ * A map plus `alphaTest` rather than a fragment discard, because the group materials already patch the
32
+ * vertex shader through `onBeforeCompile` and the stock fragment chunks handle the map, opacity and
33
+ * vertex colours unchanged; the cutoff keeps the edge crisp at 2-4 px. Callers pass the same size and
34
+ * colour as before; only the shape differs. A caller's own `map` (the anchor ring) replaces the disc.
35
+ */
36
+ export function dotMaterial(parameters) {
37
+ return new PointsMaterial({ map: roundDotTexture(), alphaTest: 0.4, ...parameters });
38
+ }
@@ -1,5 +1,6 @@
1
1
  import type { ReactNode } from "react";
2
2
  import type { SimulationClock } from "../core/clock.js";
3
+ import type { Pacing } from "../core/pacing.js";
3
4
  import type { StateResolver } from "../core/stateResolver.js";
4
5
  import type { PointGroup } from "../core/pointGroup.js";
5
6
  import type { TimeBounds, Trajectory } from "../core/trajectory.js";
@@ -137,6 +138,15 @@ export interface CameraReach {
137
138
  readonly fitOrbit?: {
138
139
  readonly farthestKm: () => number;
139
140
  };
141
+ /**
142
+ * The distance, in km, that the default zoom-out must cover for what no body's orbit speaks for (a path reaching past the planets, I-114): twice the path's farthest distance from the scene centre. When neither `maxFocusDistance` nor `fitOrbit` is declared the viewer
143
+ * widens the default zoom-out and the far plane so this distance fits the canvas whole; it never narrows the default (`minFocusDistance` below is the result, set live).
144
+ */
145
+ readonly cover?: {
146
+ readonly farthestKm: () => number;
147
+ };
148
+ /** Set live from `cover` (never declared): the zoom-out the default must at least reach, in scaled units. */
149
+ readonly minFocusDistance?: number;
140
150
  }
141
151
  /** The scene's far plane when an experience declares none. */
142
152
  export declare const DEFAULT_CAMERA_FAR = 5000;
@@ -153,6 +163,8 @@ export interface ExperienceDefinition {
153
163
  readonly rate: number; /** False leaves the clock paused at `startUtcMs` when the scene opens (default true: it plays). */
154
164
  readonly playing?: boolean;
155
165
  };
166
+ /** Playback that slows for encounters and speeds up for cruise (see `pacedRate`). Absent: the clock runs at the rate it opens with or the visitor picks. */
167
+ readonly pacing?: Pacing;
156
168
  /** Layers the scene mounts, e.g. the tracked-body list. */
157
169
  readonly sceneLayers: readonly SceneLayerId[];
158
170
  /** The catalogued bodies the scene draws, one view each. Absent: none, as in the bodiless fixture. */
@@ -65,7 +65,7 @@ export declare const MARKER_MIN_RADIUS_UNITS = 0.0001;
65
65
  export declare function markerRadiusUnits(cameraDistanceUnits: number): number;
66
66
  export declare function jumpToEvent(clock: SimulationClock, events: readonly TimelineEvent[], id: string): number;
67
67
  export type { PlaybackSpeed as Speed } from "../shell/timelineModel.js";
68
- export { formatRate, mergeSpeeds } from "../shell/timelineModel.js";
68
+ export { formatRate, speedsOf } from "../shell/timelineModel.js";
69
69
  export interface TrackedReadout {
70
70
  readonly id: string;
71
71
  readonly label: string;
@@ -58,7 +58,7 @@ export function jumpToEvent(clock, events, id) {
58
58
  clock.seek(event.timeUtcMs);
59
59
  return event.timeUtcMs;
60
60
  }
61
- export { formatRate, mergeSpeeds } from "../shell/timelineModel.js";
61
+ export { formatRate, speedsOf } from "../shell/timelineModel.js";
62
62
  /** Current-position rows for the bodies whose trajectories cover `timeUtcMs`; the rest are omitted. */
63
63
  export function trackedReadouts(bodies, timeUtcMs) {
64
64
  const rows = [];
@@ -4,4 +4,4 @@ import type { ExperienceDefinition } from "./experienceDefinition.js";
4
4
  * The clock a mounted experience opens with: at its start moment and rate (or at the moment a copied link carried), playing unless the definition says
5
5
  * `clock.playing: false`, which leaves it frozen there.
6
6
  */
7
- export declare function openClock(definition: Pick<ExperienceDefinition, "clock">, linkedTimeUtcMs?: number): SimulationClock;
7
+ export declare function openClock(definition: Pick<ExperienceDefinition, "clock" | "pacing">, linkedTimeUtcMs?: number): SimulationClock;
@@ -1,4 +1,5 @@
1
1
  import { SimulationClock } from "../core/clock.js";
2
+ import { pacedRate } from "../core/pacing.js";
2
3
  /**
3
4
  * The clock a mounted experience opens with: at its start moment and rate (or at the moment a copied link carried), playing unless the definition says
4
5
  * `clock.playing: false`, which leaves it frozen there.
@@ -8,6 +9,8 @@ export function openClock(definition, linkedTimeUtcMs) {
8
9
  clock.setRate(definition.clock.rate);
9
10
  if (linkedTimeUtcMs !== undefined)
10
11
  clock.seek(linkedTimeUtcMs);
12
+ if (definition.pacing !== undefined)
13
+ clock.setRate(pacedRate(definition.pacing, clock.now()));
11
14
  if (definition.clock.playing !== false)
12
15
  clock.play();
13
16
  return clock;
@@ -15,6 +15,7 @@ import { readoutPairOf } from "./sceneLayout.js";
15
15
  import { SceneLabelLayer } from "./SceneLabels.js";
16
16
  import { attachScenePointer } from "./scenePointer.js";
17
17
  import { StoryMarkerLayer } from "./StoryMarkers.js";
18
+ import { releaseDotTexture } from "./dotMaterial.js";
18
19
  import { releaseAnchorSprite } from "./TrackedBodyView.js";
19
20
  /** The catalogued body a focus or label id names: the Sun's shell item stands for the Sun body. */
20
21
  export function bodyIdOf(runtime, catalogue, id) {
@@ -99,7 +100,7 @@ export function useSceneFrame(rootRef, inputs) {
99
100
  * the pictures are disposed, which every renderer that drew them hears and forgets.
100
101
  */
101
102
  export function useReleaseSharedTextures() {
102
- useEffect(() => () => { releaseGlowTexture(); releaseAnchorSprite(); }, []);
103
+ useEffect(() => () => { releaseGlowTexture(); releaseAnchorSprite(); releaseDotTexture(); }, []);
103
104
  }
104
105
  /**
105
106
  * Wakes the draw rule for changes the scene cannot see in its own numbers: every load that starts, progresses, ends or fails (textures, the sky
@@ -128,8 +128,8 @@ export interface CameraStep {
128
128
  export declare function viewUpOf(ctx: Pick<FrameContext, "runtime" | "controls">): RenderVector;
129
129
  /** A frame is drawn only once every body's group and orientation node is mounted. */
130
130
  export declare function bodiesMounted(runtime: SceneRuntime, refs: BodyRefs): boolean;
131
- /** Stage 0: the time of this frame; looping playback wraps inside its window first. */
132
- export declare function frameTime(runtime: SceneRuntime, controls: Pick<SceneControls, "loop">): number;
131
+ /** Stage 0: the time of this frame; looping playback wraps inside its window first, and other playback stops on the window's edge (a scene with a timeline bar). */
132
+ export declare function frameTime(runtime: SceneRuntime, controls: Pick<SceneControls, "loop" | "paceAuto">): number;
133
133
  /** Stage 1: brings every view to the time of the frame. Returns the live body-set look. */
134
134
  export declare function syncViews(ctx: FrameContext, t: number): BodySetLook;
135
135
  /** Stage 2: places the composition about the scene centre and keeps the camera's framing when the scale policy changed. */
@@ -1,6 +1,7 @@
1
1
  import { bootShowing, hideBootLoader } from "../shell/bootLoader.js";
2
2
  import { drawnRadii } from "./bodyDraw.js";
3
3
  import { DEFAULT_BODY_SET_LOOK, familyColorOf } from "./bodySet.js";
4
+ import { applyPacing } from "../core/pacing.js";
4
5
  import { poseCamera, resolveCamera } from "./CameraController.js";
5
6
  import { DEFAULT_CAMERA_FAR } from "./experienceDefinition.js";
6
7
  import { DEFAULT_FEATURE_MIN_BODY_PX } from "./FeatureMarkers.js";
@@ -33,10 +34,14 @@ export function viewUpOf(ctx) {
33
34
  export function bodiesMounted(runtime, refs) {
34
35
  return runtime.bodies.every((id) => refs.groups.has(id) && refs.orients.has(id));
35
36
  }
36
- /** Stage 0: the time of this frame; looping playback wraps inside its window first. */
37
+ /** Stage 0: the time of this frame; looping playback wraps inside its window first, and other playback stops on the window's edge (a scene with a timeline bar). */
37
38
  export function frameTime(runtime, controls) {
38
39
  if (controls.loop === true && runtime.loopWindow !== undefined)
39
40
  runtime.clock.wrapWithin(runtime.loopWindow);
41
+ else if (runtime.stopAtWindow === true && runtime.loopWindow !== undefined)
42
+ runtime.clock.stopWithin(runtime.loopWindow);
43
+ if (controls.paceAuto === true && runtime.pacing !== undefined)
44
+ applyPacing(runtime.clock, runtime.pacing);
40
45
  return runtime.clock.now();
41
46
  }
42
47
  /** Stage 1: brings every view to the time of the frame. Returns the live body-set look. */