astraeus 0.7.0 → 0.8.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 (271) hide show
  1. package/CHANGELOG.md +176 -0
  2. package/README.md +185 -37
  3. package/package.json +5 -4
  4. package/src/api/AstraeusScene.d.ts +21 -5
  5. package/src/api/AstraeusScene.js +34 -10
  6. package/src/api/AstraeusScene.node.js +34 -10
  7. package/src/api/assembleScene.d.ts +36 -0
  8. package/src/api/assembleScene.js +175 -0
  9. package/src/api/bodySetChecks.d.ts +10 -0
  10. package/src/api/bodySetChecks.js +117 -0
  11. package/src/api/bodySetInput.d.ts +81 -0
  12. package/src/api/bodySetInput.js +1 -0
  13. package/src/api/containingBlock.d.ts +6 -0
  14. package/src/api/containingBlock.js +16 -0
  15. package/src/api/data.d.ts +17 -5
  16. package/src/api/data.js +28 -10
  17. package/src/api/definitionOf.d.ts +16 -0
  18. package/src/api/definitionOf.js +20 -0
  19. package/src/api/errors.d.ts +61 -1
  20. package/src/api/frozenCopy.d.ts +6 -0
  21. package/src/api/frozenCopy.js +26 -0
  22. package/src/api/group.d.ts +8 -2
  23. package/src/api/group.js +24 -5
  24. package/src/api/index.d.ts +18 -7
  25. package/src/api/index.js +2 -2
  26. package/src/api/index.node.js +2 -2
  27. package/src/api/listeners.d.ts +5 -0
  28. package/src/api/listeners.js +25 -0
  29. package/src/api/look.d.ts +47 -0
  30. package/src/api/look.js +1 -0
  31. package/src/api/lookInput.d.ts +3 -0
  32. package/src/api/lookInput.js +41 -0
  33. package/src/api/moonPanelInput.d.ts +60 -0
  34. package/src/api/moonPanelInput.js +1 -0
  35. package/src/api/mount.d.ts +9 -19
  36. package/src/api/mount.js +27 -13
  37. package/src/api/mount.node.js +27 -13
  38. package/src/api/pathProvenance.js +1 -1
  39. package/src/api/pickerInput.d.ts +25 -0
  40. package/src/api/pickerInput.js +1 -0
  41. package/src/api/planBodies.d.ts +72 -0
  42. package/src/api/planBodies.js +300 -0
  43. package/src/api/planBodySets.d.ts +68 -0
  44. package/src/api/planBodySets.js +234 -0
  45. package/src/api/planCamera.d.ts +83 -0
  46. package/src/api/planCamera.js +184 -0
  47. package/src/api/planGroups.d.ts +36 -0
  48. package/src/api/planGroups.js +103 -0
  49. package/src/api/planMoonPanel.d.ts +19 -0
  50. package/src/api/planMoonPanel.js +104 -0
  51. package/src/api/planPaths.d.ts +40 -0
  52. package/src/api/planPaths.js +212 -0
  53. package/src/api/planPicker.d.ts +12 -0
  54. package/src/api/planPicker.js +40 -0
  55. package/src/api/planPlaces.d.ts +16 -0
  56. package/src/api/planPlaces.js +99 -0
  57. package/src/api/planStory.d.ts +26 -0
  58. package/src/api/planStory.js +66 -0
  59. package/src/api/planTimeline.d.ts +27 -0
  60. package/src/api/planTimeline.js +68 -0
  61. package/src/api/planViews.d.ts +25 -0
  62. package/src/api/planViews.js +35 -0
  63. package/src/api/prepared.js +4 -1
  64. package/src/api/renamedInputs.d.ts +15 -0
  65. package/src/api/renamedInputs.js +39 -0
  66. package/src/api/scene.d.ts +162 -68
  67. package/src/api/scene.js +247 -793
  68. package/src/api/sceneFreeze.d.ts +4 -0
  69. package/src/api/sceneFreeze.js +10 -0
  70. package/src/api/sceneReads.d.ts +171 -0
  71. package/src/api/sceneReads.js +6 -0
  72. package/src/api/story.d.ts +49 -19
  73. package/src/api/story.js +54 -22
  74. package/src/api/sunOrbit.js +9 -11
  75. package/src/api/time.d.ts +2 -1
  76. package/src/api/time.js +2 -1
  77. package/src/api/viewerCamera.d.ts +22 -0
  78. package/src/api/viewerCamera.js +84 -0
  79. package/src/api/viewerClock.d.ts +30 -0
  80. package/src/api/viewerClock.js +85 -0
  81. package/src/api/viewerFirstDraw.d.ts +14 -0
  82. package/src/api/viewerFirstDraw.js +26 -0
  83. package/src/api/viewerHandle.d.ts +79 -0
  84. package/src/api/viewerHandle.js +31 -0
  85. package/src/api/viewerLink.d.ts +87 -15
  86. package/src/api/viewerLink.js +111 -75
  87. package/src/api/viewerLooks.d.ts +19 -0
  88. package/src/api/viewerLooks.js +37 -0
  89. package/src/api/viewerPicker.d.ts +22 -0
  90. package/src/api/viewerPicker.js +49 -0
  91. package/src/api/viewerSelection.d.ts +25 -0
  92. package/src/api/viewerSelection.js +31 -0
  93. package/src/api/viewerViews.d.ts +10 -0
  94. package/src/api/viewerViews.js +18 -0
  95. package/src/api/viewerZones.d.ts +20 -0
  96. package/src/api/viewerZones.js +47 -0
  97. package/src/api/views.d.ts +4 -5
  98. package/src/api/views.js +7 -5
  99. package/src/app/App.d.ts +5 -3
  100. package/src/app/App.js +191 -82
  101. package/src/app/App.node.js +191 -82
  102. package/src/app/AstraeusScene.d.ts +16 -2
  103. package/src/app/AstraeusScene.js +4 -4
  104. package/src/app/BodyView.d.ts +4 -1
  105. package/src/app/BodyView.js +2 -2
  106. package/src/app/CameraController.d.ts +6 -0
  107. package/src/app/DeveloperSettings.d.ts +1 -4
  108. package/src/app/DeveloperSettings.js +6 -10
  109. package/src/app/FeatureMarkers.d.ts +4 -3
  110. package/src/app/FeatureMarkers.js +8 -13
  111. package/src/app/FrameRateSection.js +2 -1
  112. package/src/app/OrbitSetView.js +1 -1
  113. package/src/app/SettingControls.d.ts +11 -3
  114. package/src/app/SettingControls.js +10 -2
  115. package/src/app/SkyView.d.ts +3 -10
  116. package/src/app/SkyView.js +6 -28
  117. package/src/app/address.d.ts +16 -0
  118. package/src/app/address.js +31 -0
  119. package/src/app/bodyDraw.d.ts +10 -7
  120. package/src/app/bodyDraw.js +12 -32
  121. package/src/app/bodyMetrics.js +2 -2
  122. package/src/app/bodySet.d.ts +4 -20
  123. package/src/app/bodySet.js +5 -16
  124. package/src/app/debugReadout.js +1 -1
  125. package/src/app/displaySwitches.d.ts +4 -0
  126. package/src/app/displaySwitches.js +6 -0
  127. package/src/app/experienceDefinition.d.ts +11 -23
  128. package/src/app/listSwitch.d.ts +8 -14
  129. package/src/app/listSwitch.js +3 -10
  130. package/src/app/liveLook.d.ts +39 -0
  131. package/src/app/liveLook.js +66 -0
  132. package/src/app/look.d.ts +36 -0
  133. package/src/app/look.js +61 -0
  134. package/src/app/mission.d.ts +1 -1
  135. package/src/app/mission.js +1 -1
  136. package/src/app/openClock.d.ts +3 -2
  137. package/src/app/openClock.js +3 -3
  138. package/src/app/sceneCamera.js +9 -0
  139. package/src/app/sceneFrame.d.ts +4 -4
  140. package/src/app/sceneFrame.js +13 -8
  141. package/src/app/sceneHooks.js +3 -2
  142. package/src/app/style.css +114 -139
  143. package/src/app/trackedMetrics.d.ts +10 -3
  144. package/src/app/trackedMetrics.js +22 -11
  145. package/src/app/viewLink.d.ts +10 -32
  146. package/src/app/viewLink.js +10 -49
  147. package/src/app/viewerPort.d.ts +50 -0
  148. package/src/app/views.d.ts +1 -0
  149. package/src/assets/bodies/galileanMoons.js +1 -2
  150. package/src/assets/bodies/io.js +2 -2
  151. package/src/assets/bodies/listedMoons.d.ts +1 -1
  152. package/src/assets/bodies/listedMoons.js +2 -3
  153. package/src/assets/bodies/planetSystemMaps.js +2 -3
  154. package/src/assets/bodies/venus.js +2 -6
  155. package/src/assets/catalogue.js +1 -2
  156. package/src/assets/licence.d.ts +3 -3
  157. package/src/assets/licence.js +3 -3
  158. package/src/assets/pictures.d.ts +15 -12
  159. package/src/assets/pictures.js +24 -20
  160. package/src/assets/sky.d.ts +6 -5
  161. package/src/assets/sky.js +6 -9
  162. package/src/assets/visual.d.ts +4 -0
  163. package/src/core/bodies/index.d.ts +0 -4
  164. package/src/core/bodies/index.js +1 -6
  165. package/src/core/bodies/jupiterData.d.ts +0 -1
  166. package/src/core/bodies/jupiterData.js +2 -5
  167. package/src/core/bodies/moonSystem.d.ts +1 -1
  168. package/src/core/bodies/moonSystem.js +102 -55
  169. package/src/core/bodies/outerPlanetRingData.js +2 -2
  170. package/src/core/bodies/planetTrajectory.js +1 -1
  171. package/src/core/bodySetFamilies.d.ts +20 -0
  172. package/src/core/bodySetFamilies.js +14 -0
  173. package/src/core/chebyshevEphemeris.js +1 -1
  174. package/src/core/elementsBody.d.ts +8 -4
  175. package/src/core/elementsBody.js +32 -11
  176. package/src/core/elementsGroup.d.ts +27 -0
  177. package/src/core/elementsGroup.js +85 -0
  178. package/src/core/events.d.ts +2 -0
  179. package/src/core/events.js +2 -0
  180. package/src/core/illumination.js +1 -1
  181. package/src/core/listedOrbitGroup.d.ts +2 -0
  182. package/src/core/listedOrbitGroup.js +11 -7
  183. package/src/core/moonListText.d.ts +6 -0
  184. package/src/core/moonListText.js +19 -0
  185. package/src/core/moonTrajectory.js +1 -1
  186. package/src/core/pacing.d.ts +38 -3
  187. package/src/core/pacing.js +55 -4
  188. package/src/core/planetModels.js +2 -2
  189. package/src/core/planetSeries.d.ts +8 -0
  190. package/src/core/planetSeries.js +16 -2
  191. package/src/core/pointGroup.js +1 -1
  192. package/src/core/provenance.d.ts +2 -1
  193. package/src/core/provenance.js +2 -2
  194. package/src/core/referenceCenters.js +5 -5
  195. package/src/core/sampledTrajectory.js +1 -1
  196. package/src/core/scalePolicy.d.ts +1 -0
  197. package/src/core/startView.d.ts +19 -0
  198. package/src/core/startView.js +28 -0
  199. package/src/core/state.d.ts +6 -2
  200. package/src/core/state.js +3 -3
  201. package/src/core/storyPanels.d.ts +63 -0
  202. package/src/core/storyPanels.js +111 -0
  203. package/src/core/sunCentredSources.d.ts +4 -0
  204. package/src/core/sunCentredSources.js +9 -2
  205. package/src/core/timeInput.d.ts +4 -0
  206. package/src/core/timeInput.js +4 -0
  207. package/src/shell/AstraeusShell.d.ts +5 -1
  208. package/src/shell/AstraeusShell.js +20 -11
  209. package/src/shell/AstraeusShell.node.js +20 -11
  210. package/src/shell/Collapsible.d.ts +4 -3
  211. package/src/shell/Collapsible.js +5 -5
  212. package/src/shell/ControlsDrawer.d.ts +1 -1
  213. package/src/shell/ControlsDrawer.js +3 -1
  214. package/src/shell/DisplaySwitches.js +2 -1
  215. package/src/shell/InfoPanel.d.ts +3 -1
  216. package/src/shell/InfoPanel.js +5 -4
  217. package/src/shell/MoonFamilyPanel.js +1 -1
  218. package/src/shell/ObjectControls.d.ts +3 -1
  219. package/src/shell/ObjectControls.js +2 -2
  220. package/src/shell/Sources.d.ts +5 -3
  221. package/src/shell/Sources.js +5 -5
  222. package/src/shell/StoryPanelView.d.ts +4 -3
  223. package/src/shell/StoryPanelView.js +8 -6
  224. package/src/shell/SwitchControl.d.ts +5 -11
  225. package/src/shell/SwitchControl.js +2 -20
  226. package/src/shell/TimelineBar.css +81 -81
  227. package/src/shell/TimelineBar.d.ts +5 -2
  228. package/src/shell/TimelineBar.js +9 -8
  229. package/src/shell/TimelineBar.node.js +9 -8
  230. package/src/shell/TopBar.css +22 -22
  231. package/src/shell/TopBar.d.ts +5 -1
  232. package/src/shell/TopBar.js +2 -2
  233. package/src/shell/TopBar.node.js +2 -2
  234. package/src/shell/bootLoader.d.ts +4 -10
  235. package/src/shell/bootLoader.js +6 -52
  236. package/src/shell/embedded.css +18 -18
  237. package/src/shell/experience.d.ts +1 -1
  238. package/src/shell/moonFamilies.d.ts +2 -6
  239. package/src/shell/moonFamilies.js +2 -18
  240. package/src/shell/phone.css +58 -58
  241. package/src/shell/storyPanels.d.ts +2 -53
  242. package/src/shell/storyPanels.js +1 -106
  243. package/src/shell/style.css +153 -134
  244. package/src/shell/useDrawers.d.ts +3 -2
  245. package/src/shell/useDrawers.js +4 -3
  246. package/src/shell/viewerKeys.d.ts +8 -0
  247. package/src/shell/viewerKeys.js +16 -0
  248. package/src/synthetic/syntheticDefinition.js +20 -24
  249. package/src/synthetic/syntheticJourneyScene.js +3 -3
  250. package/src/synthetic/syntheticProbeDefinition.js +2 -1
  251. package/src/synthetic/syntheticViewsDefinition.d.ts +0 -3
  252. package/src/synthetic/syntheticViewsDefinition.js +10 -16
  253. package/data/moons/jupiter.json +0 -3333
  254. package/data/moons/neptune.json +0 -555
  255. package/data/moons/pluto.json +0 -205
  256. package/data/moons/saturn.json +0 -8267
  257. package/data/moons/uranus.json +0 -887
  258. package/src/app/addressNavigation.d.ts +0 -17
  259. package/src/app/addressNavigation.js +0 -16
  260. package/src/assets/bodies/jupiterMoonCatalogue.d.ts +0 -3
  261. package/src/assets/bodies/jupiterMoonCatalogue.js +0 -4
  262. package/src/assets/bodies/outerPlanetCatalogues.d.ts +0 -7
  263. package/src/assets/bodies/outerPlanetCatalogues.js +0 -8
  264. package/src/assets/bodies/swiftTuttle.d.ts +0 -12
  265. package/src/assets/bodies/swiftTuttle.js +0 -13
  266. package/src/assets/moonCatalogue.d.ts +0 -49
  267. package/src/assets/moonCatalogue.js +0 -80
  268. package/src/core/bodies/outerPlanetData.d.ts +0 -4
  269. package/src/core/bodies/outerPlanetData.js +0 -13
  270. package/src/core/bodies/swiftTuttle.d.ts +0 -46
  271. package/src/core/bodies/swiftTuttle.js +0 -106
@@ -1,97 +1,133 @@
1
1
  import { SceneError } from "./errors.js";
2
- import { toUtcMs } from "./time.js";
2
+ import { ViewerLooks } from "./viewerLooks.js";
3
+ import { ViewerCamera } from "./viewerCamera.js";
4
+ import { ViewerClock } from "./viewerClock.js";
5
+ import { ViewerSelection } from "./viewerSelection.js";
6
+ import { ViewerFirstDraw } from "./viewerFirstDraw.js";
7
+ import { ViewerPicker } from "./viewerPicker.js";
8
+ import { ViewerViews } from "./viewerViews.js";
9
+ import { ViewerZones } from "./viewerZones.js";
3
10
  const NOT_OPEN = "the viewer is not drawn yet (or is gone); wait for `ready` first";
11
+ function newWait() {
12
+ const wait = { done: false };
13
+ wait.promise = new Promise((resolve, reject) => { wait.resolve = resolve; wait.reject = reject; });
14
+ wait.promise.catch(() => undefined); // a wait nobody holds when the link closes is not an unhandled rejection
15
+ return wait;
16
+ }
4
17
  /**
5
18
  * 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.
19
+ * its clock controls when it opens and detaches when it closes. The clock, views, camera, zones and selection are separate parts it delegates to.
7
20
  */
8
21
  export class ViewerLink {
9
22
  #control;
10
- #last;
11
- #rateSource = "scene";
12
- #listeners = new Set();
23
+ #access = {
24
+ control: () => this.#control,
25
+ open: (what) => {
26
+ if (this.#control === undefined)
27
+ throw new SceneError("not-mounted", `${what}: ${NOT_OPEN}`);
28
+ return this.#control;
29
+ },
30
+ };
31
+ #clock = new ViewerClock(this.#access);
32
+ #views = new ViewerViews(this.#access);
33
+ #camera = new ViewerCamera(this.#access);
34
+ #zones = new ViewerZones(this.#access);
35
+ #selection = new ViewerSelection(this.#access);
36
+ #looks = new ViewerLooks(this.#access);
37
+ #frame = new ViewerFirstDraw();
38
+ #picker = new ViewerPicker(this.#access);
39
+ #wait = newWait();
40
+ /** What last moved the clock or the view, as published; a selection dropped by time or the view names it. */
41
+ #mover = "playback";
42
+ #closed = false;
13
43
  attach(control) {
14
44
  this.#control = control;
15
- this.#last = control.read();
16
- this.#rateSource = "scene";
45
+ this.#clock.reset(control.read());
46
+ this.#selection.reset(control.read());
47
+ this.#mover = "playback";
48
+ this.#camera.reset();
49
+ this.#picker.reset(control);
50
+ this.#zones.reset(); // nothing is known to be active yet: the first publish reports every zone the time is already inside
51
+ this.#wait.done = true;
52
+ this.#wait.resolve();
17
53
  }
18
54
  detach() {
19
55
  this.#control = undefined;
20
- this.#last = undefined;
56
+ this.#clock.reset(undefined);
57
+ this.#selection.reset(undefined);
58
+ this.#mover = "playback";
59
+ this.#camera.reset();
60
+ this.#picker.reset(undefined);
61
+ this.#frame.reset();
62
+ if (this.#wait.done && !this.#closed)
63
+ this.#wait = newWait();
64
+ }
65
+ /** Takes a closed link back into use: a host effect that was cleaned up and replayed (React StrictMode) before the viewer drew. Waits for the next attach, never for the earlier one. */
66
+ reopen() {
67
+ if (!this.#closed)
68
+ return;
69
+ this.#closed = false;
70
+ this.#wait = newWait();
21
71
  }
22
72
  /** Stops all callbacks for good (the host unmounted). */
23
73
  close() {
74
+ this.#closed = true;
75
+ if (!this.#wait.done)
76
+ this.#wait.reject(new SceneError("not-mounted", "the viewer was unmounted before it was drawn"));
24
77
  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
- /** The id of the view showing; undefined before the viewer is drawn, after it is gone, and in a scene without views. */
33
- get view() { return this.#control?.read().view; }
34
- /** Switches to the view with this id. An id the scene does not name, or a scene without views, throws `bad-view`; before the viewer is drawn or after it is gone, `missing-data`. */
35
- setView(id) {
36
- const control = this.#open("setView");
37
- if (!control.views.includes(id)) {
38
- throw new SceneError("bad-view", control.views.length === 0 ? "setView: the scene has no views; name them with setViews" : `setView: "${String(id)}" is not one of the scene's views (${control.views.join(", ")})`);
39
- }
40
- control.setView(id);
41
- this.publish(control.read(), "host");
42
- }
43
- setTime(time) {
44
- const control = this.#open("setTime");
45
- const timeUtcMs = toUtcMs(time, "setTime");
46
- const { startUtcMs, endUtcMs } = control.window;
47
- if (timeUtcMs < startUtcMs || timeUtcMs > endUtcMs) {
48
- throw new SceneError("bad-time", `setTime: ${new Date(timeUtcMs).toISOString()} is outside the timeline (${new Date(startUtcMs).toISOString()} to ${new Date(endUtcMs).toISOString()})`);
49
- }
50
- control.seek(timeUtcMs);
51
- this.publish(control.read(), "host");
78
+ this.#clock.clearListeners();
79
+ this.#zones.clearListeners();
80
+ this.#selection.clearListeners();
81
+ this.#camera.clearListeners();
82
+ this.#frame.clearListeners();
83
+ this.#picker.clearListeners();
52
84
  }
53
85
  /**
54
- * Only a speed the timeline offers is taken, so the speed picker always shows what is running; any other number throws `bad-timeline`.
55
- * `"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
56
- * runs at are never set through here; they arrive in `onChange` and `rate`.
86
+ * Resolves once the viewer has attached its clock, so every read and call works from then on; at once when it already has. A `close` before it attached rejects it with
87
+ * `not-mounted` (a closed link is not usable); it never stays pending. A detach (the viewer rebuilt) arms a fresh wait.
57
88
  */
58
- setRate(rate) {
59
- const control = this.#open("setRate");
60
- if (rate === "auto") {
61
- if (!control.paced)
62
- throw new SceneError("bad-timeline", "setRate: \"auto\" needs a scene with pacing; give setTimeline({ pacing })");
63
- control.setRate("auto");
64
- this.#rateSource = "scene";
65
- this.publish(control.read(), "host");
66
- return;
67
- }
68
- if (!control.rates.includes(rate))
69
- throw new SceneError("bad-timeline", `setRate: ${String(rate)} is not one of the offered speeds (${control.rates.join(", ")}); offer it with setTimeline({ rates })`);
70
- control.setRate(rate);
71
- this.#rateSource = "chosen";
72
- this.publish(control.read(), "host");
73
- }
74
- /** Calls `listener` whenever the time, speed or playing state changes; returns the function that stops it. */
75
- onChange(listener) {
76
- this.#listeners.add(listener);
77
- return () => { this.#listeners.delete(listener); };
78
- }
89
+ whenAttached() { return this.#wait.promise; }
90
+ get rateSource() { return this.#clock.rateSource; }
91
+ get timeUtcMs() { return this.#clock.timeUtcMs; }
92
+ get rate() { return this.#clock.rate; }
93
+ get playing() { return this.#clock.playing; }
94
+ get eventZones() { return this.#zones.eventZones; }
95
+ get view() { return this.#views.view; }
96
+ get selected() { return this.#selection.selected; }
97
+ get camera() { return this.#camera.camera; }
98
+ get pick() { return this.#picker.pick; }
99
+ get look() { return this.#looks.look; }
100
+ get scale() { return this.#looks.scale; }
101
+ get switches() { return this.#looks.switches; }
102
+ // Each member below is documented where it is done: viewerClock, viewerViews, viewerCamera, viewerZones, viewerSelection.
103
+ setView(id) { this.#views.setView(id); this.#afterHost(); }
104
+ setTime(time) { this.#clock.setTime(time); this.#afterHost(); }
105
+ setRate(rate) { this.#clock.setRate(rate); this.#afterHost(); }
106
+ setPlaying(playing) { this.#clock.setPlaying(playing); this.#afterHost(); }
107
+ setCamera(target) { this.#camera.setCamera(target); }
108
+ setLook(look) { this.#looks.setLook(look); this.#afterHost(); }
109
+ setScale(id) { this.#looks.setScale(id); this.#afterHost(); }
110
+ setSwitch(id, on) { this.#looks.setSwitch(id, on); this.#afterHost(); }
111
+ onChange(listener) { return this.#clock.onChange(listener); }
112
+ onEventZone(listener) { return this.#zones.onEventZone(listener); }
113
+ setPick(value) { this.#picker.setPick(value); }
114
+ onPick(listener) { return this.#picker.onPick(listener); }
115
+ pickNow() { return this.#picker.pick; }
116
+ watchPick(watcher) { return this.#picker.watch(watcher); }
117
+ picked(value) { this.#picker.press(value); }
118
+ onFirstDraw(listener) { return this.#frame.onFirstDraw(listener); }
119
+ firstDraw() { this.#frame.publish(); }
120
+ onSelect(listener) { return this.#selection.onSelect(listener); }
121
+ onCameraChange(listener) { return this.#camera.onCameraChange(listener); }
79
122
  publish(state, cause) {
80
- const last = this.#last;
81
- if (last !== undefined && last.timeUtcMs === state.timeUtcMs && last.rate === state.rate && last.playing === state.playing && last.auto === state.auto && last.view === state.view)
82
- return;
83
- if (state.auto !== undefined)
84
- this.#rateSource = state.auto ? "scene" : "chosen";
85
- else if (cause === "visitor" && last !== undefined && last.rate !== state.rate)
86
- this.#rateSource = "chosen";
87
- this.#last = state;
88
- const change = { time: state.timeUtcMs, rate: state.rate, playing: state.playing, ...(state.view === undefined ? {} : { view: state.view }), cause };
89
- for (const listener of [...this.#listeners])
90
- listener(change);
91
- }
92
- #open(what) {
93
- if (this.#control === undefined)
94
- throw new SceneError("missing-data", `${what}: ${NOT_OPEN}`);
95
- return this.#control;
123
+ if (this.#clock.publish(state, cause))
124
+ this.#mover = cause;
125
+ this.#zones.publish(state, cause);
126
+ this.#selection.publish(state, cause);
127
+ this.#camera.publish();
96
128
  }
129
+ /** The selection changed. A drop by time or the view names whatever last moved them (`onChange` names the same), so the cause is never a second opinion. */
130
+ publishSelection(state, byMove) { this.#selection.publish(state, byMove ? this.#mover : "visitor"); }
131
+ /** A host call moved the clock or the view: report the control's reading, change then zones. */
132
+ #afterHost() { this.publish(this.#access.open("publish").read(), "host"); }
97
133
  }
@@ -0,0 +1,19 @@
1
+ import type { LookInput, LookRead } from "./look.js";
2
+ import type { LinkAccess } from "./viewerLink.js";
3
+ /** The host link's presentation: the looks, the scale and the display switches, their reads and their setters. */
4
+ export declare class ViewerLooks {
5
+ private readonly access;
6
+ constructor(access: LinkAccess);
7
+ /** The looks in force, every one filled in; undefined before the viewer is drawn and after it is gone. */
8
+ get look(): LookRead | undefined;
9
+ /** The id of the scale showing; undefined like `look`. */
10
+ get scale(): string | undefined;
11
+ /** The display switches the scene placed, each on or off (empty when it placed none); undefined like `look`. */
12
+ get switches(): Readonly<Record<string, boolean>> | undefined;
13
+ /** Sets the whole look, checked as `Scene.setLook` checks it (`bad-look`). */
14
+ setLook(look: LookInput): void;
15
+ /** Switches to one of the scales the viewer offers (`Scene.scales`); any other id throws `bad-scale`. */
16
+ setScale(id: string): void;
17
+ /** Turns a display switch the scene placed on or off; an id it did not place, or a non-boolean, throws `bad-switch`. */
18
+ setSwitch(id: string, on: boolean): void;
19
+ }
@@ -0,0 +1,37 @@
1
+ import { SceneError } from "./errors.js";
2
+ import { checkedLook } from "./lookInput.js";
3
+ /** The host link's presentation: the looks, the scale and the display switches, their reads and their setters. */
4
+ export class ViewerLooks {
5
+ access;
6
+ constructor(access) {
7
+ this.access = access;
8
+ }
9
+ /** The looks in force, every one filled in; undefined before the viewer is drawn and after it is gone. */
10
+ get look() { return this.access.control()?.read().look; }
11
+ /** The id of the scale showing; undefined like `look`. */
12
+ get scale() { return this.access.control()?.read().scale; }
13
+ /** The display switches the scene placed, each on or off (empty when it placed none); undefined like `look`. */
14
+ get switches() { return this.access.control()?.read().switches; }
15
+ /** Sets the whole look, checked as `Scene.setLook` checks it (`bad-look`). */
16
+ setLook(look) {
17
+ const control = this.access.open("setLook");
18
+ control.setLook(checkedLook(look));
19
+ }
20
+ /** Switches to one of the scales the viewer offers (`Scene.scales`); any other id throws `bad-scale`. */
21
+ setScale(id) {
22
+ const control = this.access.open("setScale");
23
+ if (!control.scales.includes(id))
24
+ throw new SceneError("bad-scale", `setScale: "${String(id)}" is not one of the scales this viewer offers (${control.scales.join(", ")})`);
25
+ control.setScale(id);
26
+ }
27
+ /** Turns a display switch the scene placed on or off; an id it did not place, or a non-boolean, throws `bad-switch`. */
28
+ setSwitch(id, on) {
29
+ const control = this.access.open("setSwitch");
30
+ const placed = Object.keys(control.read().switches);
31
+ if (!placed.includes(id))
32
+ throw new SceneError("bad-switch", placed.length === 0 ? "setSwitch: the scene placed no display switches; place them with setSwitches" : `setSwitch: "${String(id)}" is not a switch the scene placed (${placed.join(", ")})`);
33
+ if (typeof on !== "boolean")
34
+ throw new SceneError("bad-switch", `setSwitch: expected true or false, got ${String(on)}`);
35
+ control.setSwitch(id, on);
36
+ }
37
+ }
@@ -0,0 +1,22 @@
1
+ import type { PickChange } from "./pickerInput.js";
2
+ import type { LinkAccess } from "./viewerLink.js";
3
+ import type { ViewerControl } from "../app/viewerPort.js";
4
+ /** The host link's picker: the pressed option read and moved, and the `onPick` callbacks a visitor's press calls. The viewer draws the pressed option from here and moves nothing itself. */
5
+ export declare class ViewerPicker {
6
+ #private;
7
+ private readonly access;
8
+ constructor(access: LinkAccess);
9
+ /** The viewer attached (the scene's own starting option is pressed) or detached (nothing). */
10
+ reset(control: ViewerControl | undefined): void;
11
+ clearListeners(): void;
12
+ /** The value of the pressed option; undefined before the viewer is drawn, after it is gone and in a scene without a picker. */
13
+ get pick(): string | undefined;
14
+ /** The viewer redraws when the pressed option moves; returns the function that stops it. */
15
+ watch(watcher: () => void): () => void;
16
+ /** Moves the pressed option; no signal. A scene without a picker, or an unknown value, throws `bad-picker`. */
17
+ setPick(value: string): void;
18
+ /** Calls `listener` when a visitor presses an option other than the pressed one; returns the function that stops it. */
19
+ onPick(listener: (change: PickChange) => void): () => void;
20
+ /** A visitor pressed an option (the viewer only calls this for one that is not pressed). The pressed option stays where it is. */
21
+ press(value: string): void;
22
+ }
@@ -0,0 +1,49 @@
1
+ import { callListeners } from "./listeners.js";
2
+ import { SceneError } from "./errors.js";
3
+ /** The host link's picker: the pressed option read and moved, and the `onPick` callbacks a visitor's press calls. The viewer draws the pressed option from here and moves nothing itself. */
4
+ export class ViewerPicker {
5
+ access;
6
+ #listeners = new Set();
7
+ /** The viewer's own redraw callbacks (the pressed option moved). */
8
+ #watchers = new Set();
9
+ #pressed;
10
+ constructor(access) {
11
+ this.access = access;
12
+ }
13
+ /** The viewer attached (the scene's own starting option is pressed) or detached (nothing). */
14
+ reset(control) {
15
+ this.#pressed = control?.picker?.start;
16
+ this.#tell();
17
+ }
18
+ clearListeners() { this.#listeners.clear(); }
19
+ /** The value of the pressed option; undefined before the viewer is drawn, after it is gone and in a scene without a picker. */
20
+ get pick() { return this.#pressed; }
21
+ /** The viewer redraws when the pressed option moves; returns the function that stops it. */
22
+ watch(watcher) {
23
+ this.#watchers.add(watcher);
24
+ return () => { this.#watchers.delete(watcher); };
25
+ }
26
+ /** Moves the pressed option; no signal. A scene without a picker, or an unknown value, throws `bad-picker`. */
27
+ setPick(value) {
28
+ const picker = this.access.open("setPick").picker;
29
+ if (picker === undefined)
30
+ throw new SceneError("bad-picker", "setPick: the scene has no picker; call Scene.setPicker first");
31
+ if (!picker.values.includes(value))
32
+ throw new SceneError("bad-picker", `setPick: "${String(value)}" is not one of the picker's options (${picker.values.join(", ")})`);
33
+ this.#pressed = value;
34
+ this.#tell();
35
+ }
36
+ /** Calls `listener` when a visitor presses an option other than the pressed one; returns the function that stops it. */
37
+ onPick(listener) {
38
+ this.#listeners.add(listener);
39
+ return () => { this.#listeners.delete(listener); };
40
+ }
41
+ /** A visitor pressed an option (the viewer only calls this for one that is not pressed). The pressed option stays where it is. */
42
+ press(value) {
43
+ const picker = this.access.control()?.picker;
44
+ if (picker === undefined || value === this.#pressed)
45
+ return;
46
+ callListeners(this.#listeners, { picker: picker.id, value });
47
+ }
48
+ #tell() { callListeners(this.#watchers, undefined); }
49
+ }
@@ -0,0 +1,25 @@
1
+ import type { ViewerChangeCause, ViewerState } from "../app/viewerPort.js";
2
+ import type { LinkAccess } from "./viewerLink.js";
3
+ /** What a host is told when the viewer's selected object changes. */
4
+ export interface SelectionChange {
5
+ /** The id of the newly selected object; absent when the selection was dropped and nothing took its place. */
6
+ readonly object?: string;
7
+ /** The viewer's time at the report, Unix milliseconds UTC. */
8
+ readonly timeUtcMs: number;
9
+ /** `visitor`: the object menu, a click, or a clock or view change the visitor made; `host`: a host call (`setTime`, `setRate`, `setPlaying`, `setView`) moved the clock or view and the selection followed; `playback`: the clock running moved it. */
10
+ readonly cause: ViewerChangeCause;
11
+ }
12
+ /** The host link's selection: the selected object read and the `onSelect` callbacks. */
13
+ export declare class ViewerSelection {
14
+ #private;
15
+ private readonly access;
16
+ constructor(access: LinkAccess);
17
+ /** The viewer attached (its first reading: the opening selection is read, not reported) or detached (undefined). */
18
+ reset(first: ViewerState | undefined): void;
19
+ clearListeners(): void;
20
+ /** The id of the selected object; undefined before the viewer is drawn, after it is gone and when nothing is selected. */
21
+ get selected(): string | undefined;
22
+ /** Calls `listener` when the selected object changes; returns the function that stops it. */
23
+ onSelect(listener: (change: SelectionChange) => void): () => void;
24
+ publish(state: ViewerState, cause: ViewerChangeCause): void;
25
+ }
@@ -0,0 +1,31 @@
1
+ import { callListeners } from "./listeners.js";
2
+ /** The host link's selection: the selected object read and the `onSelect` callbacks. */
3
+ export class ViewerSelection {
4
+ access;
5
+ #listeners = new Set();
6
+ /** The selection last read or reported; meaningful only while `#known` (the viewer is attached). */
7
+ #last;
8
+ #known = false;
9
+ constructor(access) {
10
+ this.access = access;
11
+ }
12
+ /** The viewer attached (its first reading: the opening selection is read, not reported) or detached (undefined). */
13
+ reset(first) {
14
+ this.#known = first !== undefined;
15
+ this.#last = first?.selected;
16
+ }
17
+ clearListeners() { this.#listeners.clear(); }
18
+ /** The id of the selected object; undefined before the viewer is drawn, after it is gone and when nothing is selected. */
19
+ get selected() { return this.access.control()?.read().selected; }
20
+ /** Calls `listener` when the selected object changes; returns the function that stops it. */
21
+ onSelect(listener) {
22
+ this.#listeners.add(listener);
23
+ return () => { this.#listeners.delete(listener); };
24
+ }
25
+ publish(state, cause) {
26
+ if (!this.#known || state.selected === this.#last)
27
+ return;
28
+ this.#last = state.selected;
29
+ callListeners(this.#listeners, { ...(state.selected === undefined ? {} : { object: state.selected }), timeUtcMs: state.timeUtcMs, cause });
30
+ }
31
+ }
@@ -0,0 +1,10 @@
1
+ import type { LinkAccess } from "./viewerLink.js";
2
+ /** The host link's views: which one shows, and `setView`. */
3
+ export declare class ViewerViews {
4
+ private readonly access;
5
+ constructor(access: LinkAccess);
6
+ /** The id of the view showing; undefined before the viewer is drawn, after it is gone, and in a scene without views. */
7
+ get view(): string | undefined;
8
+ /** Switches to the view with this id. An id the scene does not name, or a scene without views, throws `bad-view`; before the viewer is drawn or after it is gone, `not-mounted`. */
9
+ setView(id: string): void;
10
+ }
@@ -0,0 +1,18 @@
1
+ import { SceneError } from "./errors.js";
2
+ /** The host link's views: which one shows, and `setView`. */
3
+ export class ViewerViews {
4
+ access;
5
+ constructor(access) {
6
+ this.access = access;
7
+ }
8
+ /** The id of the view showing; undefined before the viewer is drawn, after it is gone, and in a scene without views. */
9
+ get view() { return this.access.control()?.read().view; }
10
+ /** Switches to the view with this id. An id the scene does not name, or a scene without views, throws `bad-view`; before the viewer is drawn or after it is gone, `not-mounted`. */
11
+ setView(id) {
12
+ const control = this.access.open("setView");
13
+ if (!control.views.includes(id)) {
14
+ throw new SceneError("bad-view", control.views.length === 0 ? "setView: the scene has no views; name them with setViews" : `setView: "${String(id)}" is not one of the scene's views (${control.views.join(", ")})`);
15
+ }
16
+ control.setView(id);
17
+ }
18
+ }
@@ -0,0 +1,20 @@
1
+ import type { ViewerChangeCause, ViewerState } from "../app/viewerPort.js";
2
+ import type { EventZoneChange, LinkAccess } from "./viewerLink.js";
3
+ /** The host link's event zones: the zones holding the time now and the `onEventZone` callbacks. */
4
+ export declare class ViewerZones {
5
+ #private;
6
+ private readonly access;
7
+ constructor(access: LinkAccess);
8
+ /** The viewer attached: nothing is known to be active yet. */
9
+ reset(): void;
10
+ clearListeners(): void;
11
+ /** The ids of the events whose zone holds the time now (empty without event zones); undefined before the viewer is drawn and after it is gone. */
12
+ get eventZones(): readonly string[] | undefined;
13
+ /**
14
+ * Calls `listener` when playback enters or leaves the zone of an event the showing view has (`withinSeconds` of the event, or a `near` rule of `setTimeline({ pacing })`); returns the function that stops it.
15
+ * A zone the time is already inside when the viewer opens is reported as entered once, with the first report after `ready` (within a tenth of a second), so a listener added right after `await ready` hears it.
16
+ * A viewer rebuild (`AstraeusScene` given a new scene) starts over the same way.
17
+ */
18
+ onEventZone(listener: (change: EventZoneChange) => void): () => void;
19
+ publish(state: ViewerState, cause: ViewerChangeCause): void;
20
+ }
@@ -0,0 +1,47 @@
1
+ import { callListeners } from "./listeners.js";
2
+ /** The host link's event zones: the zones holding the time now and the `onEventZone` callbacks. */
3
+ export class ViewerZones {
4
+ access;
5
+ #listeners = new Set();
6
+ #active = [];
7
+ /** The view the last publish showed (`undefined` before the first publish and in a scene without views), to tell a view-caused zone change from a time-caused one. */
8
+ #view;
9
+ constructor(access) {
10
+ this.access = access;
11
+ }
12
+ /** The viewer attached: nothing is known to be active yet. */
13
+ reset() {
14
+ this.#view = undefined;
15
+ this.#active = [];
16
+ }
17
+ clearListeners() { this.#listeners.clear(); }
18
+ /** The ids of the events whose zone holds the time now (empty without event zones); undefined before the viewer is drawn and after it is gone. */
19
+ get eventZones() {
20
+ const control = this.access.control();
21
+ return control === undefined ? undefined : control.read().zones ?? [];
22
+ }
23
+ /**
24
+ * Calls `listener` when playback enters or leaves the zone of an event the showing view has (`withinSeconds` of the event, or a `near` rule of `setTimeline({ pacing })`); returns the function that stops it.
25
+ * A zone the time is already inside when the viewer opens is reported as entered once, with the first report after `ready` (within a tenth of a second), so a listener added right after `await ready` hears it.
26
+ * A viewer rebuild (`AstraeusScene` given a new scene) starts over the same way.
27
+ */
28
+ onEventZone(listener) {
29
+ this.#listeners.add(listener);
30
+ return () => { this.#listeners.delete(listener); };
31
+ }
32
+ publish(state, cause) {
33
+ const now = state.zones ?? [];
34
+ const before = this.#active;
35
+ const via = this.#view !== undefined && this.#view.view !== state.view ? "view" : "time";
36
+ this.#view = { view: state.view };
37
+ if (now.length === before.length && now.every((id, index) => id === before[index]))
38
+ return;
39
+ this.#active = now;
40
+ const reports = [...before.filter((id) => !now.includes(id)).map((id) => [id, false]), ...now.filter((id) => !before.includes(id)).map((id) => [id, true])];
41
+ for (const [id, entered] of reports) {
42
+ const event = this.access.control()?.events.find((candidate) => candidate.id === id);
43
+ const change = { event: id, ...(event?.type === undefined ? {} : { type: event.type }), ...(event?.object === undefined ? {} : { object: event.object }), entered, timeUtcMs: state.timeUtcMs, cause, via };
44
+ callListeners(this.#listeners, change);
45
+ }
46
+ }
47
+ }
@@ -5,12 +5,11 @@ export type ViewCameraInput = "stay" | "start" | {
5
5
  } | {
6
6
  readonly focus: string;
7
7
  };
8
- /** One named view. `paths` are `addTrajectory` ids, `bodies` are `addBody` or `addGroup` ids, `events` are `addEvents` ids and `panels` are `addStoryPanels` ids. */
8
+ /** One named view. `objects` are `addBody`, `addGroup` or `addTrajectory` ids, `events` are `addEvents` ids and `panels` are `addStoryPanels` ids. */
9
9
  export interface ViewInput {
10
10
  readonly id: string;
11
11
  readonly label: string;
12
- readonly paths?: readonly string[];
13
- readonly bodies?: readonly string[];
12
+ readonly objects?: readonly string[];
14
13
  readonly events?: readonly string[];
15
14
  readonly panels?: readonly string[];
16
15
  readonly camera?: ViewCameraInput;
@@ -28,8 +27,8 @@ export interface ViewsPlan {
28
27
  }
29
28
  /** What the finished scene holds, for `resolveViews`. */
30
29
  export interface ViewScope {
31
- readonly paths: readonly string[];
32
- readonly bodies: readonly string[];
30
+ /** Every body, group and path id of the scene. */
31
+ readonly objects: readonly string[];
33
32
  readonly events: readonly string[];
34
33
  readonly panels: readonly string[];
35
34
  }
package/src/api/views.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { VIEW_PLACES } from "../app/views.js";
2
2
  import { SceneError } from "./errors.js";
3
- const KINDS = ["paths", "bodies", "events", "panels"];
3
+ import { rejectRenamed } from "./renamedInputs.js";
4
+ const KINDS = ["objects", "events", "panels"];
4
5
  const bad = (message) => new SceneError("bad-view", `setViews: ${message}`);
5
6
  /** Checks the shape of a `setViews` call (list, ids, labels, place, start, camera form, id lists); the ids are checked when the scene is built. */
6
7
  export function viewsOf(input, options) {
@@ -22,6 +23,7 @@ export function viewsOf(input, options) {
22
23
  if (seen.has(view.id))
23
24
  throw bad(`view "${view.id}" appears twice`);
24
25
  seen.add(view.id);
26
+ rejectRenamed("ViewInput", view, `setViews: view "${view.id}"`);
25
27
  for (const kind of KINDS) {
26
28
  const ids = view[kind];
27
29
  if (ids !== undefined && (!Array.isArray(ids) || !ids.every((id) => typeof id === "string" && id !== "")))
@@ -53,9 +55,9 @@ function cameraOf(view) {
53
55
  * and for a camera target the view does not show.
54
56
  */
55
57
  export function resolveViews(plan, scope) {
56
- const known = { paths: new Set(scope.paths), bodies: new Set(scope.bodies), events: new Set(scope.events), panels: new Set(scope.panels) };
57
- const what = { paths: "a path (addTrajectory)", bodies: "a body or group", events: "an event (addEvents)", panels: "a story panel (addStoryPanels)" };
58
- const named = { paths: new Set(), bodies: new Set(), events: new Set(), panels: new Set() };
58
+ const known = { objects: new Set(scope.objects), events: new Set(scope.events), panels: new Set(scope.panels) };
59
+ const what = { objects: "a body, group or path (addBody, addGroup, addTrajectory)", events: "an event (addEvents)", panels: "a story panel (addStoryPanels)" };
60
+ const named = { objects: new Set(), events: new Set(), panels: new Set() };
59
61
  for (const view of plan.views) {
60
62
  for (const kind of KINDS) {
61
63
  for (const id of view[kind] ?? []) {
@@ -67,7 +69,7 @@ export function resolveViews(plan, scope) {
67
69
  }
68
70
  const shows = (view, kind, id) => !named[kind].has(id) || (view[kind] ?? []).includes(id);
69
71
  const views = plan.views.map((view) => {
70
- const objects = new Set([...scope.paths.filter((id) => shows(view, "paths", id)), ...scope.bodies.filter((id) => shows(view, "bodies", id))]);
72
+ const objects = new Set(scope.objects.filter((id) => shows(view, "objects", id)));
71
73
  const camera = cameraOf(view);
72
74
  if (camera.rule === "start" && camera.framing !== undefined) {
73
75
  const target = "follow" in camera.framing ? camera.framing.follow : camera.framing.focus;
package/src/app/App.d.ts CHANGED
@@ -8,13 +8,15 @@ export declare function hiddenLabelsFrom(search: string, objects: readonly {
8
8
  /** `?loop=on` or `?loop=off` overrides the experience's own looping setting. */
9
9
  export declare function loopFromSearch(search: string, fallback: boolean): boolean;
10
10
  /**
11
- * `onOpenAddress`: the entry's way to open a switch's address in place; without it a switch navigates the page.
12
11
  * `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.
12
+ * `developerTools`: whether the viewer shows the Developer toggle and drawer (default false; the drawer's code is fetched only when a visitor opens it, so off never fetches it; the demo site passes true).
13
+ * `address`: whether the viewer reads the page address (`view`, `t`, `scale`, `up`, `show`, `stars`, `milkyway`, `labels` and the other parameters in the README) and offers a copy-link button that writes it (default false: a host page's address is its own; the demo site passes true).
13
14
  * `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.
14
15
  */
15
- export declare function App({ definition, onOpenAddress, writeTitle, host }: {
16
+ export declare function App({ definition, writeTitle, address, developerTools, host }: {
16
17
  readonly definition: ExperienceDefinition;
17
- readonly onOpenAddress?: (address: string) => void;
18
18
  readonly writeTitle?: boolean;
19
+ readonly address?: boolean;
20
+ readonly developerTools?: boolean;
19
21
  readonly host?: ViewerPort;
20
22
  }): import("react").JSX.Element;