astraeus 0.8.1 → 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 (121) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +28 -15
  3. package/package.json +1 -1
  4. package/src/api/AstraeusScene.d.ts +1 -1
  5. package/src/api/AstraeusScene.js +4 -1
  6. package/src/api/AstraeusScene.node.js +4 -1
  7. package/src/api/assembleScene.d.ts +2 -0
  8. package/src/api/assembleScene.js +27 -5
  9. package/src/api/cameraRequest.d.ts +15 -0
  10. package/src/api/cameraRequest.js +89 -0
  11. package/src/api/errors.d.ts +9 -1
  12. package/src/api/index.d.ts +6 -3
  13. package/src/api/look.d.ts +49 -0
  14. package/src/api/lookInput.d.ts +1 -1
  15. package/src/api/lookInput.js +6 -1
  16. package/src/api/planCamera.d.ts +35 -7
  17. package/src/api/planCamera.js +94 -11
  18. package/src/api/planSkyFigures.d.ts +22 -0
  19. package/src/api/planSkyFigures.js +145 -0
  20. package/src/api/planStory.d.ts +2 -2
  21. package/src/api/planStory.js +14 -9
  22. package/src/api/planViews.js +1 -1
  23. package/src/api/scene.d.ts +17 -4
  24. package/src/api/scene.js +23 -5
  25. package/src/api/sceneReads.d.ts +21 -2
  26. package/src/api/skyFigureInput.d.ts +45 -0
  27. package/src/api/skyFigureInput.js +1 -0
  28. package/src/api/skyTraceInput.d.ts +33 -0
  29. package/src/api/skyTraceInput.js +45 -0
  30. package/src/api/story.d.ts +12 -3
  31. package/src/api/story.js +44 -1
  32. package/src/api/viewerCamera.d.ts +4 -3
  33. package/src/api/viewerCamera.js +10 -32
  34. package/src/api/viewerHandle.d.ts +27 -4
  35. package/src/api/viewerHandle.js +6 -0
  36. package/src/api/viewerLink.d.ts +49 -4
  37. package/src/api/viewerLink.js +25 -0
  38. package/src/api/viewerPanels.d.ts +26 -0
  39. package/src/api/viewerPanels.js +42 -0
  40. package/src/api/viewerSelection.d.ts +1 -1
  41. package/src/api/viewerSelection.js +3 -3
  42. package/src/app/App.js +100 -18
  43. package/src/app/App.node.js +100 -18
  44. package/src/app/AstraeusScene.d.ts +20 -5
  45. package/src/app/AstraeusScene.js +3 -3
  46. package/src/app/CameraController.d.ts +17 -0
  47. package/src/app/CameraController.js +34 -9
  48. package/src/app/DeveloperSettings.d.ts +11 -3
  49. package/src/app/DeveloperSettings.js +13 -3
  50. package/src/app/SceneLabels.d.ts +20 -2
  51. package/src/app/SceneLabels.js +46 -6
  52. package/src/app/SkyFiguresView.d.ts +56 -0
  53. package/src/app/SkyFiguresView.js +242 -0
  54. package/src/app/StoryMarkers.d.ts +2 -2
  55. package/src/app/StoryMarkers.js +2 -2
  56. package/src/app/displaySwitches.d.ts +13 -3
  57. package/src/app/displaySwitches.js +17 -3
  58. package/src/app/experienceDefinition.d.ts +9 -3
  59. package/src/app/experienceDefinition.js +4 -2
  60. package/src/app/labelStyle.d.ts +17 -0
  61. package/src/app/labelStyle.js +13 -0
  62. package/src/app/liveLook.js +8 -0
  63. package/src/app/look.d.ts +9 -5
  64. package/src/app/look.js +11 -0
  65. package/src/app/lookOut.d.ts +32 -0
  66. package/src/app/lookOut.js +50 -0
  67. package/src/app/sceneCamera.d.ts +5 -3
  68. package/src/app/sceneCamera.js +66 -3
  69. package/src/app/sceneContentsHooks.d.ts +2 -1
  70. package/src/app/sceneContentsHooks.js +3 -2
  71. package/src/app/sceneFrame.d.ts +10 -1
  72. package/src/app/sceneFrame.js +45 -10
  73. package/src/app/sceneFraming.d.ts +7 -0
  74. package/src/app/sceneFraming.js +12 -0
  75. package/src/app/sceneHooks.d.ts +2 -0
  76. package/src/app/sceneHooks.js +4 -1
  77. package/src/app/scenePicking.d.ts +20 -0
  78. package/src/app/scenePicking.js +49 -0
  79. package/src/app/scenePointer.d.ts +3 -1
  80. package/src/app/scenePointer.js +3 -2
  81. package/src/app/skyFigures.d.ts +73 -0
  82. package/src/app/skyFigures.js +50 -0
  83. package/src/app/style.css +2 -1
  84. package/src/app/viewHiding.d.ts +2 -0
  85. package/src/app/viewHiding.js +7 -1
  86. package/src/app/viewLink.d.ts +8 -8
  87. package/src/app/viewLink.js +24 -4
  88. package/src/app/viewerPort.d.ts +30 -3
  89. package/src/assets/sky.d.ts +13 -4
  90. package/src/assets/sky.js +33 -8
  91. package/src/assets/stars/hyg-v42-naked-eye.json +1 -1
  92. package/src/core/bodies/moonSystem.js +1 -15
  93. package/src/core/lookValues.d.ts +9 -0
  94. package/src/core/lookValues.js +24 -0
  95. package/src/core/readBytes.d.ts +1 -0
  96. package/src/core/readBytes.js +15 -0
  97. package/src/core/skyTrace.d.ts +49 -0
  98. package/src/core/skyTrace.js +39 -0
  99. package/src/core/startView.d.ts +39 -0
  100. package/src/core/startView.js +56 -0
  101. package/src/core/storyPanels.d.ts +51 -3
  102. package/src/core/storyPanels.js +52 -12
  103. package/src/shell/AstraeusShell.d.ts +15 -6
  104. package/src/shell/AstraeusShell.js +76 -20
  105. package/src/shell/AstraeusShell.node.js +76 -20
  106. package/src/shell/ObjectControls.js +11 -8
  107. package/src/shell/StoryPanelView.d.ts +12 -3
  108. package/src/shell/StoryPanelView.js +2 -2
  109. package/src/shell/experience.d.ts +24 -0
  110. package/src/shell/experience.js +4 -1
  111. package/src/shell/infoModel.js +9 -1
  112. package/src/shell/objectModel.d.ts +6 -2
  113. package/src/shell/objectModel.js +10 -1
  114. package/src/shell/phone.css +1 -1
  115. package/src/shell/storyPanels.d.ts +1 -1
  116. package/src/shell/storyPanels.js +1 -1
  117. package/src/shell/style.css +9 -1
  118. package/src/shell/topBarIcons.d.ts +1 -0
  119. package/src/shell/topBarIcons.js +1 -0
  120. package/src/shell/useStoryPanels.d.ts +9 -6
  121. package/src/shell/useStoryPanels.js +10 -6
package/CHANGELOG.md CHANGED
@@ -2,6 +2,73 @@
2
2
 
3
3
  Versions follow [semantic versioning](https://semver.org). While the version starts with `0.`, the public API (the names exported from `astraeus`) may still change between minor versions; each change is listed here.
4
4
 
5
+ ## 0.9.0 (2026-11-11)
6
+
7
+ Look out at the sky, draw and trace any figure on it, tap it for a card, and tell a story in steps that turns to it and traces it (G-018). The new optional package `astraeus-data-constellations` supplies all 88 IAU constellations. Additions only, apart from one type-level change for apps that read the camera (`CameraPose` is now `OrbitPose | SkyPose`, see "Look out from a body" below). Every `astraeus-data*` package now peers on `astraeus` `>=0.9.0 <0.10.0`.
8
+
9
+ First download of the packed example (`npm run measure:example`): 1,759,084 bytes raw, 505,483 bytes gzip (code and styles loaded on first open), against 1,720,047 raw and 493,478 gzip at 0.8.1.
10
+
11
+ Star-end sky figures load in Node (I-167): `scene.load()` now reads the engine's bundled star list through the same reader as the moon fit chunks (a `file:` address through `node:fs`, anything else by `fetch`), so a headless app with figures whose ends name stars (`{ star: HIP }`, for example from `astraeus-data-constellations`) no longer gets `missing-data`. No call shape changed.
12
+
13
+ `setTimeline` warns on a rate in the wrong unit (I-163): `rate` and `rates` are simulated seconds per real second, and when `rate` or an offered rate would cross the whole span in under one real second (for example `rate: 86_400_000`, a day in milliseconds, over 120 days) it calls `console.warn` naming the unit and the value. It never throws, since a short span at a fast rate can be meant. No call shape or error code changed.
14
+
15
+ New package `astraeus-data-constellations` (G-018, O-067, first build step): the 88 IAU constellations' stick figures, J2000 boundary outlines and names as plain data (`loadFigures`, `loadBoundaries`, `loadNames`, `loadProvenance`, and the same JSON under `exports`). Figures and boundaries are CC BY-SA 4.0 (Stellarium team; IAU and Sky & Telescope origin), names CC BY 4.0 (IAU), code MIT. Additions only; the engine itself is unchanged, and its public lock gains only the new package's exports.
16
+
17
+ Sky lines fade in (G-018, O-067, owner look at the last step): sky figures, outlines and the two reference circles, with their names, now fade in over half a second when the viewer opens and each time their switch turns on, instead of appearing at once. New look `skyFadeInSeconds` (0 to 3, default 0.5; 0 shows them at once; `setLook` only, no address parameter), read back as `LookRead.skyFadeInSeconds`. A person who asked for less motion sees them at once. Figures shown only when traced still appear by their trace, and now look it: while a selected figure is being traced, the trace grows in the `skyLines.selected` colour instead of the whole highlighted figure showing over it at once, and a hidden-until-traced figure's name fades in over the first half of its trace. Additions only; no existing call shape or error code changed.
18
+
19
+ New example `examples/hello-sky` (G-018, O-067, last step): looks out from Earth and tells Orion's story in three steps with the new constellations package on the plain `mount` path, built from the packed tarballs like the other examples (not published). The `constellations()` helper loads the outline file only when `outlines` is true. No engine change.
20
+
21
+ Story actions (G-018, O-066, third step): a story panel can turn the camera, select its object and trace its sky figure when it opens, and an event can name a sky figure. Additions only; no existing call shape or error code changed.
22
+
23
+ - `StoryPanelInput` gains `camera` (anything `setCamera` takes), `select` (true: select the panel's `object`; as for a visitor's tap, the card opens on a wide screen and not on a phone, where it would cover the panel's buttons; `setSelected` still opens it always) and `trace` (`true` or `SkyTraceOptions`: trace the panel's `object`, which must be a sky figure). They apply when the panel opens, whoever opens it, in the order camera, select, trace, through the same paths as `setCamera`, `setSelected` and `traceSkyFigure`. Leaving the panel clears the trace it started over the default fade; the camera and selection are left. A bad shape throws `bad-panels` at `addStoryPanels`, a name the scene lacks at `check` and `mount`. A panel's `object` may name a sky figure.
24
+ - A look-out `direction` (`setCamera`'s `LookOutTarget`, and a panel's `camera`) may name a sky figure: the camera turns toward its label point. An id that is neither an object nor a sky figure still throws `bad-camera`. A panel's look-out without a `direction` keeps the one already looked along.
25
+ - `EventInput.object` may name a sky figure: Go to seeks and selects it, and turns toward it only while the camera looks out. A name that is neither throws `bad-event`.
26
+
27
+ Story steps (G-018, O-066, second step): story panels can be steps with Back and Next, and a host can open a panel and hear which is open. Additions only; no existing call shape or error code changed (a panel with no `at`, which threw `bad-panels` before, is now a step).
28
+
29
+ - `StoryPanelInput.at` is optional. A panel without it is a step: steps keep the order added across `addStoryPanels` calls, never open from playback, and show Back and Next (and "Step n of m") on the panel; panels with `at` behave as before. With steps and no moment panel the first step is open when the viewer opens, with or without a timeline; otherwise a step opens from its `object`'s marker or `setPanel`.
30
+ - `scene.panels` lists the moment panels by time, then the steps in the order added; `ScenePanelRead.timeUtcMs` is absent on a step.
31
+ - New on the `mount` handle and `AstraeusScene`: `handle.panel` (the open panel id), `handle.setPanel(id | undefined)` (open one by id, or close the open one; an id the showing view does not show throws `bad-panels`) and `handle.onPanel(listener)` (`{ panel?, timeUtcMs, cause }`, with `cause` `visitor`, `host` or `playback`; new type `PanelChange`).
32
+
33
+ Selecting sky figures (G-018, O-066, first step): a visitor can tap a sky figure and see its card. Additions only; no existing call shape or error code changed.
34
+
35
+ - `SkyFigureInput` gains `description`, `facts` (`CardFactInput[]`), `sources`, `provenance` and `listed`, as `addBody` and `addTrajectory` take them (`listed` and the provenance default as there; a bad one throws `bad-sky-figure`). `scene.skyFigures` and `handle.skyFigures` read `listed`, `provenance`, `description` and `facts` too.
36
+ - A tap on a figure's shown name, or within 16 px of one of its drawn lines, selects it (never inside an outline; a body hit wins; a figure that is not drawn is not tappable). `handle.setSelected(id)`, `handle.selected`, `onSelect` and the `AstraeusScene` equivalents take a sky figure id; the object menu lists figures that are `listed`; the card shows in the same info panel as a body's.
37
+ - The selected figure's lines and name take the new look `skyLines.selected` (default `#ffffff`), changeable with `setLook` and in the Developer drawer.
38
+
39
+ Sky figures (G-018, O-065, first step): an app can draw named figures and outlines on the sky, like the stars, and switch the ecliptic and the celestial equator on. Additions only; no existing call shape or error code changed.
40
+
41
+ - `scene.addSkyFigures(figures)`: each figure is `{ id, label, kind?, segments?, points?, labelAt? }`. A `"figure"` (the default) has `segments`, pairs of ends, an end being `{ star: <Hipparcos number> }` or `{ raDeg, decDeg }`; a `"boundary"` has `points`, a closed loop of at least three positions. Drawn at infinity in the J2000 equatorial frame, above the Sun's glow, from the orbit camera and from a look-out view; each has a label in the viewer's one name layout. New types `SkyFigureInput`, `SkyFigureEnd`, `SceneSkyFigureRead`.
42
+ - Four new display switches for `setSwitches` (and `handle.setSwitch`): `skyFigures` (starts on), `skyBoundaries`, `ecliptic` and `celestialEquator` (start off). The ecliptic uses the engine's own J2000 obliquity.
43
+ - Reads: `scene.skyFigures` and `handle.skyFigures` (`{ id, label, kind }` each) on the `mount` handle and on `AstraeusScene`.
44
+ - Two error codes: `bad-sky-figure` (a malformed figure; none of the call is added) and `unknown-star` (a star number not in the star list; found when the scene is built, because the star list loads then). A star list that cannot be read throws `missing-data` at that point. A repeated id throws `duplicate-id`. Colours are fixed defaults in this step.
45
+
46
+ Sky looks (G-018, O-065, second step): the colours of the sky lines and the label font and size are looks. Additions only; no existing call shape or error code changed.
47
+
48
+ - `LookInput` and `LookRead` gain `skyLines` (`figure`, `label`, `boundary`, `ecliptic`, `equator`, `traced`, `faded`: CSS colour texts; defaults `#8fb4ff`, `#cfe0ff`, `#5f7a9c`, `#e0b25a`, `#7fd1b9`, `#ffd166`, `#44546d`) and `labels` (`fontFamily`, default `inherit`; `sizePx`, 8 to 24, default 12). `setLook` and `handle.setLook` change them live, and the Developer drawer (Labels) shows a size slider, a font field and a colour input for each line colour. The label font and size apply to every label in the viewer (bodies, paths, sky figures, anchor labels); the defaults keep today's look. A colour the viewer cannot read, an empty font or a size out of range throws `bad-look`. These looks have no page address parameter. New types `SkyLinesLook` and `LabelsLook`.
49
+ - `SkyFigureInput` gains `color`, `labelColor`, `labelFont` and `labelSizePx`, the figure's own look over the looks above; a bad one throws `bad-sky-figure`. The sky figure names now take the single `skyLines.label` colour by default (the first step used the line colour).
50
+
51
+ Hidden until traced (G-018, O-065): a figure can start hidden and appear only when traced. Addition only; the default is today's behaviour.
52
+
53
+ - `SkyFigureInput` gains `shown?: "always" | "whenTraced"` (default `"always"`). A `"whenTraced"` figure draws neither lines nor label until `traceSkyFigure` starts a trace of it; the trace draws its lines in order and shows its label, then `after` keeps them (`"stay"`), or fades both away (`"fade"`); `clearSkyTrace` removes both at any time; tracing again starts from nothing. The figure's switch still hides everything when off. Any other `shown` value throws `bad-sky-figure`.
54
+
55
+ Tracing figures (G-018, O-065, third step): an app can ask the viewer to draw a sky figure line by line. Additions only; no existing call shape or error code changed.
56
+
57
+ - `handle.traceSkyFigure(id, { durationSeconds?, after? })` on the `mount` handle and on `AstraeusScene`: draws the figure's segments in order, each growing from its first end, over `durationSeconds` (0.1 to 60, default 2) in the `skyLines.traced` colour, then `after` (`"stay"` default, or `"fade"` to the `skyLines.faded` colour and away over a second). It runs only when the app asks, on real time (pause and speed of the scene clock do not change it); calling again restarts it; it follows the figure's switch. With `prefers-reduced-motion: reduce` the whole figure shows at once.
58
+ - `handle.clearSkyTrace(id, { durationSeconds? })` on both embedding paths: removes a figure's trace at any time (running, after `"stay"`, or during a `"fade"`), easing it out over `durationSeconds` (0 to 60, default 1; 0 at once). A `whenTraced` figure is hidden, an always-shown one loses only the trace highlight; a figure with no trace is left alone; unknown id throws `unknown-sky-figure`, bad options `bad-sky-trace`.
59
+ - Two error codes: `unknown-sky-figure` (an id the viewer does not draw) and `bad-sky-trace` (bad options, `durationSeconds` out of range, or an `after` other than `"stay"` or `"fade"`). Exported types: `SkyTraceOptions` and `SkyClearOptions`.
60
+
61
+ Look out from a body (G-018, O-064): the camera can stand at a body's centre and turn to look around the sky. The public camera API and the camera menu entry are in; the sky figures come in a later step.
62
+
63
+ **Type-level change for apps that read the camera.** The camera reading, `CameraPose` (what `camera` reads and `onCameraChange` and `setStartView` carry), is now one of two kinds: an `OrbitPose` (today's `{ focus, azimuthDeg, elevationDeg, distance }`, unchanged) or a `SkyPose` `{ lookOut, raDeg, decDeg, fovDeg }` (the body stood in, where it points in J2000 equatorial degrees, the vertical field of view in degrees, 5 to 100). An orbit camera still reads as an orbit pose, so a scene that never looks out sees no change at run time, but TypeScript no longer lets an app read `pose.distance` or `pose.focus` without narrowing. The one-line check an app that reads `distance` needs: `if ("lookOut" in pose) { /* sky pose */ } else { /* orbit pose: pose.distance */ }` (a sky pose has no `focus` and no `distance`; an orbit pose has no `lookOut`). Both kinds are plain data: keep one and hand it to `setCamera`, or to `scene.camera.setStartView`, to restore it.
64
+
65
+ - `setCamera({ lookOut: id, direction?, fovDeg? })` stands inside the body `id` (a body the showing view shows) looking out. `direction` is `{ raDeg, decDeg }` (J2000 equatorial degrees; the right ascension wraps, the declination is within ±90) or the id of an object to turn toward; omitted, the camera keeps the direction it already looks along, else right ascension 0, declination 0. `fovDeg` (5 to 100; omitted: the current one, else 60) is the zoom. A sky pose read from `camera` is also a valid argument. An unknown or hidden body or object, a direction or field of view out of range, or a malformed shape throws `bad-camera` at the call. Focus, Follow, Overview or an orbit pose returns to the orbit camera. The visitor drags to pan and wheels or pinches to change the field of view.
66
+ - `scene.camera.lookOut(body, { direction?, fovDeg? })` opens the scene looking out (a body not added throws `unknown-body`; a half or misspelt direction, an unknown key or a non-object look throws `bad-camera` at the call); `scene.camera.setStartView` takes a sky pose; the last opening call wins.
67
+ - `scene.camera.lookOut` takes the same `direction` forms as `setCamera`, checked by the same rule (I-168, I-169): `{ raDeg, decDeg }`, or the id of an object or sky figure to turn toward, such as `scene.camera.lookOut("earth", { direction: "Leo", fovDeg: 80 })` or `{ direction: "moon" }`; the `direction` type widens to `SkyDirection | string`. A figure may be added before or after the call. An id that is neither an object the opening view shows nor a sky figure throws `bad-camera` naming it when the scene is built, worded as `setCamera`'s. The viewer turns toward an id on its first frame by the same steps as `setCamera`, so until then there is no pose: `scene.camera.pose` is undefined after such a call and `handle.camera` reads undefined before the first frame. No other public surface changes.
68
+ - The share link carries a sky pose as `?view=body,raDeg,decDeg,fovDeg,sky` (a fifth part tells it from an orbit view's four); a malformed one is refused as a malformed orbit view is.
69
+ - `scene.camera.setLookOutChoices(ids)` lists the bodies whose "Look out from <body>" entry the camera menu offers, beside Focus and Follow on the bar and the phone drawer (default none; a body not added throws `unknown-body`). The entry looks toward right ascension 0, declination 0 at the default field of view; Focus, Follow and Overview return to the orbit camera.
70
+ - New exported types: `OrbitPose`, `SkyPose`, `SkyDirection`, `LookOutTarget`. `CameraTarget` gains `LookOutTarget`; `CameraPose` becomes `OrbitPose | SkyPose`. No ecliptic-longitude input: an app converts to right ascension and declination itself.
71
+
5
72
  ## 0.8.1 (2026-11-10)
6
73
 
7
74
  First download of the packed example (`npm run measure:example`): 1,720,047 bytes raw, 493,478 bytes gzip (code and styles loaded on first open), against 1,716,429 raw and 492,249 gzip at 0.8.0 (+3,618 raw, +1,229 gzip, the new host calls). The planet data is a lazy chunk and not part of that total.
package/README.md CHANGED
@@ -86,22 +86,25 @@ The full reference, generated from the types and doc comments, is at <https://as
86
86
  | `scene.addBodySet({ id, families, members, provenance, center?, bodies?, centerGmKm3S2?, balancePoint?, orbitHistoryMs? })` | Many small bodies about one centre as one batch of dots, each selectable with an info card, with orbit lines coloured by family. `families` is one to sixteen of `{ id, label, color?, brightness? }` (colour a CSS hex colour, default the palette in family order; `brightness` the orbit-line multiplier, default 1). A member is `{ id, family, label?, radiusKm?, elements?, description?, facts?, provenance?, knownLimitations?, listed? }`: with no `elements` it is a listed moon of `center` (`listedMoons(planet)`; its positions come through `data`, as for `addBody`, and its label and radius default to the list's); with `elements` (`semiMajorAxisKm`, `eccentricity`, `inclinationDeg`, `raanDeg`, `argumentOfPeriapsisDeg`, `trueAnomalyDeg`, `time?`, `plane?`) it is a made-up member on two-body motion and needs `label` and `radiusKm`. A set is one kind or the other. `center` is a body in the scene (default the scene's first); `centerGmKm3S2` sizes each orbit line to one lap (default the centre's moon system, else its catalogue record; neither is `bad-body-set`). `bodies` are bodies added with `addBody` that belong to a family: their orbit lines take its colour, and one with no `orbit` of its own, if it is a listed moon of `center`, gets its line in this batch. `balancePoint` (`{ body, gmKm3S2 }`, a member or such a body) draws the lines about the balance point of the centre and that body (default the centre's moon system's own when its body is drawn here). `orbitHistoryMs` loads positions that long before the window so a line can reach back (default 0). Members are not in the Object menu unless `listed: true`. `stateOf` and `provenanceOf` accept member ids; story panels may name them; a view cannot name a set or a member. A repeated id throws `duplicate-id`; a mistake throws `bad-body-set`. |
87
87
  | `scene.setMoonPanel({ label, families, featuredFamily?, listSource?, listDate? })` | The sliding panel of a planet's moons by family. `label` is the name in the heading ("<label>'s moons"). `families` is `{ id, label, description, moons }` each, where a moon is `{ id, named? }`: a body (`addBody`) or a body-set member (`addBodySet`) of the scene, checked when the scene is built; its label comes from there, and `named: false` folds a provisional designation under "+N unnamed". A moon that is a body gets the picture the viewer's `data` brings for it (the packages' `pictures`); a dot gets none. `featuredFamily` is the family id listed first with pictures. `listSource` and `listDate` (a moment, kept as its day) say where and when the list was taken. Replaces any earlier panel. A malformed panel, or a moon the scene does not hold, throws `bad-moon-panel`. |
88
88
  | `scene.setPicker({ id, label, options, value })` | A choice in the viewer's top bar and phone drawer: one button per option `{ value, label }` (values unique), the option with `value` pressed when the viewer opens, `label` the accessible name of the group and `id` carried on the buttons as `data-switch-param`. Fewer than two options draw nothing. Replaces any earlier picker. A press only tells the host (`handle.onPick`, the `onPick` prop): the viewer never navigates, reads or writes the page address, or keeps a time, and the pressed button does not move until the host calls `handle.setPick` or mounts a new scene. A malformed picker, or a `value` that is not an option, throws `bad-picker`. |
89
+ | `scene.addSkyFigures(figures)` | Figures and outlines drawn on the sky at infinity, like the stars (J2000 equatorial frame, presentation only), each with a label. Each is `{ id, label, kind?, segments?, points?, labelAt?, shown?, color?, labelColor?, labelFont?, labelSizePx?, description?, facts?, sources?, provenance?, listed? }`. A `"figure"` (the default `kind`) has `segments`, a non-empty list of `[end, end]` pairs, an end being `{ star: <Hipparcos number> }` (a star of the engine's star list, magnitude 6.5 or brighter) or `{ raDeg, decDeg }`; a `"boundary"` has `points`, a closed loop of at least three `{ raDeg, decDeg }` (the last joins the first). `labelAt` is `{ raDeg, decDeg }`; without it the label stands at the mean direction of the ends. Lines draw above the Sun's glow, from the orbit camera and from a look-out view; the labels join the viewer's one name layout and give way to body names. The switches `skyFigures` (on) and `skyBoundaries` (off) show each kind, and `ecliptic` and `celestialEquator` (both off) draw the two reference circles (`setSwitches`). `id` must be new among the scene's bodies, paths, groups, body sets and sky figures (`duplicate-id`, also for a repeat inside one call); a malformed figure throws `bad-sky-figure` and adds none of the call. A star number not in the star list throws `unknown-star` when the scene is built (`mount`, `prepare`; the list loads then, not at this call); a star list that cannot be read throws `missing-data` then. `color` and `labelColor` (CSS colours), `labelFont` (a CSS font-family text) and `labelSizePx` (8 to 24) are the figure's own line colour and label look, over the looks `skyLines` and `labels`; a bad one throws `bad-sky-figure`. `shown` is `"always"` (the default) or `"whenTraced"`: a `"whenTraced"` figure draws nothing (lines or label) until `traceSkyFigure` starts a trace of it (below); any other value throws `bad-sky-figure`. The card fields work as for `addBody` and `addTrajectory`: `description` (a non-empty text), `facts` (`{ label, value }` pairs), `sources` (texts added after the provenance's own), `provenance` (default illustrative, "Supplied by the caller") and `listed` (default true; false leaves the figure out of the object menu until it is selected); a bad one throws `bad-sky-figure`. A visitor selects a figure by tapping its name or within 16 px of one of its lines (never inside an outline); a body hit wins over a figure; a figure that is not drawn (its switch off, or `"whenTraced"` with no trace showing) cannot be tapped. The selected figure's lines and name take the look `skyLines.selected` and its card opens as a body's does. Read the result from `scene.skyFigures`. |
89
90
  | `scene.addPlaces(body, { categories, places, provenance, knownLimitations? })` | The tagged surface places of one body, drawn as markers on it and opened in the information panel. `categories` are `{ key, label, color }` (a CSS hex colour); `places` are `{ id, name, kind, category, latitudeDeg, longitudeDeg, description, details? }` (`id` unique within the body, `kind` shown as the place's kind such as "Crater", an unknown `category` draws white, longitude east-positive as the marker draws it, coordinates kept exactly as given, `details` card facts). `provenance` is shown with every place (PROV-01). The body must be in the scene when it is built; a second call for one body throws `duplicate-id`; a mistake throws `bad-places`. The place lists of 24 bodies ship as data in `astraeus-data` (`astraeus-data/bodies/<body>/{features,categories,map,overview}.json`, with `catalogue.json`); an app converts them to this input. |
90
91
  | `scene.addGroup({ id, orbits, plane, label?, center?, color?, dotSizePx?, referenceTime?, seed?, clump?, refillAfterMs?, refillSliceMs?, provenance?, description?, knownLimitations? })` | A list of orbits drawn as one group of dots: `orbits` is `[{ id, semiMajorAxisKm, eccentricity, inclinationDeg, raanDeg, argumentOfPeriapsisDeg, time? }]` (bound orbits, ids distinct), measured about `center` (default the scene's centre; it must be in the scene) in `plane`, which you must give (`"ecliptic-j2000"` or `"EQJ"`; a group without one throws `bad-group`). One colour (`color`, a hex colour), dot size (`dotSizePx`), menu item, info card, provenance and known limits. Where each dot sits along its orbit is a drawing choice, marked illustrative: an even spread shuffled by `seed`, fixed at `referenceTime` (default the opening time), then two-body motion. `clump: { near, fraction, widthDeg }` draws a share of the dots near a body's place along its orbit (a model; the body must be in the scene and not the centre; it may be one added with `addBodyFromElements` before the group). `refillAfterMs` is how often the dots are placed again; `refillSliceMs` (0 or more) is how much of a frame may go on computing the next fill ahead of time. The group's card shows "illustrative" as its source type, with the elements' own type in the accuracy sentence. The id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be a panel's `object`. A mistake throws `bad-group`. |
91
92
  | `scene.setTime(time)` | The moment the scene opens at. |
92
93
  | `scene.setScale(trueScale \| readableScale \| solarSystemScale, { only? })` | The opening scale; the viewer can switch to the other unless `{ only: true }` offers that scale alone. `solarSystemScale` (true distances, enlarged bodies drawn larger) needs a Sun-centred scene with an enlarged body, else `bad-scale`; such a scene offers it second in place of `readableScale`. |
93
94
  | `scene.addEvents(events, { provenance? })` | Timed events on the timeline: `[{ id, label, time, type?, provenance?, object?, withinSeconds? }]`; it appends, and a repeated id, in one call or across calls, throws `duplicate-id`. `withinSeconds` (positive, finite, simulated seconds) gives the event its own zone, `time ± withinSeconds`, that a host hears with `onEventZone` and `eventZones` with or without pacing; a pacing `near` rule uses it in place of its own `withinSeconds` for that event. A bad value throws `bad-event` naming the event. `object` is the id of a body or trajectory in the scene the event is about: the timeline's Go to (and Previous/Next) seeks to the event and frames that object as `camera.focus` does (it is selected and Focus shows pressed); an event without one only seeks. An `object` the scene lacks throws `bad-event` naming the event and the id when the scene is built. `provenance` says where the times come from; an event's own `provenance` wins over the batch's. A provenance `sourceType` is `ephemeris`, `observed`, `reconstructed`, `modelled` or `illustrative`; `modelled` is shown as "Modelled". Batch and per-event provenance are checked: a malformed one throws `bad-event`. May be called more than once. |
94
- | `scene.addStoryPanels(list)` | Appends story panels that open as playback reaches them: `[{ id, at: { time } \| { event } \| { anchor }, title, body, details?, provenance, object? }]`. `at.time` is any moment (ISO text, a `Date` or Unix milliseconds). `provenance` is `{ sourceType, sources, accuracy, notes }`: the badge shows the word for `sourceType`, and `sources`, `accuracy` and `notes` show in the panel's folded section. `sources` is never empty and `accuracy` is never blank; where a source states none, say so. A bad shape throws `bad-panels` at the call, naming the panel and field; a repeated id throws `duplicate-id`. The events, anchors and objects a panel names may be added later, so they are checked at `check` and `mount`, which throw `bad-panels`. |
95
+ | `scene.addStoryPanels(list)` | Appends story panels: those with `at` open as playback reaches them; those without are steps (below): `[{ id, at?: { time } \| { event } \| { anchor }, title, body, details?, provenance, object?, camera?, select?, trace? }]`. `at.time` is any moment (ISO text, a `Date` or Unix milliseconds). `provenance` is `{ sourceType, sources, accuracy, notes }`: the badge shows the word for `sourceType`, and `sources`, `accuracy` and `notes` show in the panel's folded section. `sources` is never empty and `accuracy` is never blank; where a source states none, say so. A bad shape throws `bad-panels` at the call, naming the panel and field; a repeated id throws `duplicate-id`. The events, anchors and objects a panel names may be added later, so they are checked at `check` and `mount`, which throw `bad-panels`. A panel with no `at` is a step: steps keep the order added (across calls), never open from playback, and show Back and Next on the panel (Back is disabled on the first step, Next on the last). With steps and no moment panel the first step is open when the viewer opens, with or without a timeline (`setTimeline({ none: true })`); beside moment panels a step opens from its `object`'s marker or the host's `setPanel`. A panel's `object` may name a sky figure (it has no marker). Whenever a panel opens (by time, as a step, by the host or by a visitor) its actions apply, in this order, through the same paths as the host calls: `camera` (any target `setCamera` takes, checked as it checks; a look-out `direction` may name a sky figure, and without a `direction` the one already looked along is kept), `select: true` (selects the panel's `object`; needs an `object`; the card follows a visitor's tap, not `setSelected`: it opens on a wide screen and not on a phone, where it would cover the panel's Back and Next) and `trace` (`true` or options as `traceSkyFigure` takes; traces the panel's `object`, which must be a sky figure). Leaving the panel (another opens, or it closes) clears the trace it started with `clearSkyTrace`'s default fade; the camera and selection are left as they are, and so is anything the host or a visitor did in between. A bad shape throws `bad-panels` naming the panel and field, at the call; a name the scene lacks, at `check` and `mount`. |
95
96
  | `scene.setStoryPanelPlayback({ pauseSeconds?, autoOpen? })` | How story panels play: the seconds playback holds when a panel opens by itself (0 to 20, default 6; 0 never pauses) and whether panels open by themselves (default true). Replaces the whole setting; a bad value throws `bad-panels`. |
96
- | `scene.setTimeline({ start, end, rates?, rate?, loop?, pacing? })` | The timeline's span, the playback speeds offered (simulated seconds per real second) and the one it opens at. `{ none: true, at?, rate? }` draws no timeline bar: time is frozen at `at`, or runs on at `rate`. The speed menu shows exactly the `rates` you give (ascending), and no others; without `rates` it offers 1 minute, 1 hour and 1 day per second. `pacing` slows playback for encounters and speeds it up for cruise, see "Paced playback" below. With a timeline bar and no `loop`, playback stops on the timeline's end instead of running past it. |
97
+ | `scene.setTimeline({ start, end, rates?, rate?, loop?, pacing? })` | The timeline's span, the playback speeds offered (simulated seconds per real second) and the one it opens at. When `rate` or an offered rate would cross the whole span in under one real second (as `rate: 86_400_000`, a day in milliseconds, does over 120 days), `setTimeline` warns on the console naming the unit and the value, since the number is probably in milliseconds; it does not throw. `{ none: true, at?, rate? }` draws no timeline bar: time is frozen at `at`, or runs on at `rate`. The speed menu shows exactly the `rates` you give (ascending), and no others; without `rates` it offers 1 minute, 1 hour and 1 day per second. `pacing` slows playback for encounters and speeds it up for cruise, see "Paced playback" below. With a timeline bar and no `loop`, playback stops on the timeline's end instead of running past it. |
97
98
  | `scene.addActivity({ id, label, unit, start, end, samples, peak?, provenance?, type?, peakLabel? })` | A period of activity on the timeline: a rate curve `samples: [{ time, value }]` (at least two, sorted, inside `start` to `end`; straight lines between) that the timeline glows by, with an optional `peak` mark and `provenance: [{ start, end, provenance }]` for where each stretch comes from. A group's `readouts: [{ kind: "rate", activity? }]` shows the live rate (unavailable outside the period) against the peak on its card. Without `setTimeline` the timeline spans the activities. A repeated id throws `duplicate-id`; a bad curve, peak or source throws `bad-activity`; a rate readout with no activity is `bad-readout`. |
98
99
  | `scene.camera.setReach(distance, { farEarthRadii? })` | How far the viewer can zoom out, in Earth radii; the far plane (where drawing stops) is 2.5 times it unless `farEarthRadii` (a finite number of at least `distance`, in Earth radii) sets it; labels reach as far, a path's own name (at its marker, switched by `labels`) included. A bad value throws `bad-camera`. Without `setReach` or `fitOrbit`, a Sun-centred scene with a path about the Sun widens its farthest zoom-out to fit that path whole (twice its farthest Sun distance, for the live canvas shape), so a path out to 170 AU can be seen entire. The object the scene opens on (`camera.follow` or `camera.focus`) is selected, and a selected object's label wins every label collision: it is never the one hidden because it overlaps another. Other labels keep their priority order. `camera.follow` and `camera.focus` take `up: "ecliptic"` (default `"equatorial"`) to orbit about the ecliptic's pole; any other value throws `bad-camera`. `setTimeline` takes `loop: true` so playback wraps from the end to the start. |
99
- | `scene.camera.setStartView(pose)` | Opens at a pose `{ focus, azimuthDeg, elevationDeg, distance }` (what `handle.camera` reads; distance in Earth radii) with no camera button pressed, so Focus does not show as pressed and choosing another body moves the camera as it would without a start. `focus` must be a body or path already added (`unknown-body`); a bad angle or distance throws `bad-camera`. The last of `follow`, `focus` and `setStartView` wins. Default: none. |
100
+ | `scene.camera.setStartView(pose)` | Opens at a pose (what `handle.camera` reads, either kind: an orbit pose `{ focus, azimuthDeg, elevationDeg, distance }`, distance in Earth radii, or a sky pose `{ lookOut, raDeg, decDeg, fovDeg }`) with no camera button pressed, so Focus does not show as pressed and choosing another body moves the camera as it would without a start. `focus` or `lookOut` must be a body or path already added (`unknown-body`); a bad angle, distance or field of view throws `bad-camera`. The last of `follow`, `focus`, `lookOut` and `setStartView` wins. Default: none. |
101
+ | `scene.camera.lookOut(body, { direction?, fovDeg? })` | Opens standing inside a body (at its centre) and looking out, with no camera button pressed. `direction` takes the same forms as `setCamera`'s look-out, checked by the same rule: a star-map position `{ raDeg, decDeg }` (J2000 equatorial degrees; default right ascension 0, declination 0), or the id of an object or sky figure to turn toward (an object the opening view shows, or a figure added before or after this call); `fovDeg` is the vertical field of view in degrees (5 to 100; default 60). The body must be already added (`unknown-body`); a direction or field of view out of range, a malformed direction, an unknown key, or a `look` that is not an object throws `bad-camera` at the call; an id that names nothing the opening view can turn toward throws `bad-camera` naming it when the scene is built. With a position it is the same as `setStartView` with a sky pose. With an id the viewer turns toward it on its first frame as `setCamera` does, so until then there is no pose: `scene.camera.pose` is undefined and `handle.camera` reads undefined before the first frame. The body stood in is not drawn while looking out. `scene.camera.lookOut("earth", { direction: { raDeg: 83.6, decDeg: 22 }, fovDeg: 40 })`, `scene.camera.lookOut("earth", { direction: "Leo", fovDeg: 80 })` |
100
102
  | `scene.camera.setFollowChoices(ids)` | Which objects offer a Follow button in the camera menu, by body or id already added (`unknown-body`); the others offer Focus only, and an empty list offers Follow on none. Default: every body, path and group. An opening `camera.follow` of an object not in the list throws `bad-camera` when the scene is built. |
103
+ | `scene.camera.setLookOutChoices(ids)` | Which bodies offer a "Look out from" entry in the camera menu (O-064 T-293), by body or id already added (`unknown-body`; a non-list is `bad-camera`). The entry sits with Focus and Follow on the bar and the phone drawer and stands inside the body looking toward right ascension 0, declination 0; Focus, Follow, Overview or an orbit `setCamera` leaves the sky view. Default: none. The opening `camera.lookOut` does not need the body listed. `scene.camera.setLookOutChoices(["earth", "mars"])` |
101
104
  | `scene.setBodyReadouts(kinds)` | Which rows a body's info card shows, in order: `"distance"`, `"phase"`, `"coordinates"`; replaces the earlier choice. Default `["distance"]`. A body whose `addBody` gave its own `readouts` keeps those. An unknown kind throws `bad-readout`. |
102
105
  | `scene.camera.fitOrbit(body)` | Sets the farthest zoom-out so the whole orbit of a body that circles the Sun (a planet, or a comet or asteroid from `addBodyFromElements`, already added) fits the canvas from any view direction: 1.1 times its farthest Sun distance over the sine of the narrower half field of view. The fit follows the live canvas shape (a phone turning, a window resizing) and the far plane is 2.5 times the reach. The opening view is not moved, except that it is clamped to the limit like any other. Labels are not limited in a fitted scene. It and `setReach` set the same limit; the later call wins. A body that does not circle the Sun throws `bad-camera`; one not in the scene, `unknown-body`. `scene.camera.fitOrbit("c-2025-a1")` |
103
- | `scene.setLook({ starBrightness?, milkyWay?, milkyWayBrightness?, skyVisible?, sunGlow?: { sizePx?, brightness?, scale? }, markerSwapRadiusPx?, featureMinBodyPx?, loadFadeSeconds?, desktopPictures? })` | The looks, presentation settings that change how the scene is drawn and never where anything is; each is optional and keeps its default when not named (the call replaces the whole look). Ranges and defaults: star and Milky Way brightness 0 to 2 (1); `milkyWay` and `skyVisible` true or false (Milky Way off, sky shown); `sunGlow.sizePx` 0 to 400 (the Sun record's 72), `sunGlow.brightness` 0 to 2 (1), `sunGlow.scale` 1 to 6 (2.5); `markerSwapRadiusPx` 0 to 100 (3), the screen radius under which a sphere is drawn as a dot; `featureMinBodyPx` 0 to 2000 (60); `loadFadeSeconds` 0 to 3 (0.6); `desktopPictures` true or false (false) lets a body with a larger desktop picture use it on a wide screen, read when the viewer is built, so a later `setLook` neither swaps pictures nor changes what `look` reads. A page address parameter (table below) overrides the look it names when `address` is on. An unknown look or a value out of range throws `bad-look`. |
104
- | `scene.setSwitches({ orbitLines?, labels?, milkyWay? })` | Where each display switch shows: `{ place: "top-bar" \| "panel" \| "developer", on? }`. A top-bar switch is a button in the bar, a panel switch is a row in one switch panel opened from the bar, and a developer switch is only in the Developer drawer (where every switch stays), so it shows only when the viewer was built with `developerTools` on; with it off there is no drawer and the switch is simply not shown. `orbitLines` is the orbit ring, trailing arc and moon orbits; `labels` is body and anchor labels; `milkyWay` is the sky picture. `on` is the starting state (default on). Nothing placed: the bar is as before. A bad name, place or `on` throws `bad-switch`. |
106
+ | `scene.setLook({ starBrightness?, milkyWay?, milkyWayBrightness?, skyVisible?, sunGlow?: { sizePx?, brightness?, scale? }, markerSwapRadiusPx?, featureMinBodyPx?, loadFadeSeconds?, skyFadeInSeconds?, desktopPictures?, skyLines?: { figure?, label?, boundary?, ecliptic?, equator?, traced?, faded?, selected? }, labels?: { fontFamily?, sizePx? } })` | The looks, presentation settings that change how the scene is drawn and never where anything is; each is optional and keeps its default when not named (the call replaces the whole look). Ranges and defaults: star and Milky Way brightness 0 to 2 (1); `milkyWay` and `skyVisible` true or false (Milky Way off, sky shown); `sunGlow.sizePx` 0 to 400 (the Sun record's 72), `sunGlow.brightness` 0 to 2 (1), `sunGlow.scale` 1 to 6 (2.5); `markerSwapRadiusPx` 0 to 100 (3), the screen radius under which a sphere is drawn as a dot; `featureMinBodyPx` 0 to 2000 (60); `loadFadeSeconds` 0 to 3 (0.6); `skyFadeInSeconds` 0 to 3 (0.5), how long sky figures, outlines and the reference circles, with their names, take to fade in when the viewer opens and each time their switch turns on (0 shows them at once, as does a visitor's reduced-motion setting; a figure shown only when traced appears by its trace), with no page address parameter; `desktopPictures` true or false (false) lets a body with a larger desktop picture use it on a wide screen, read when the viewer is built, so a later `setLook` neither swaps pictures nor changes what `look` reads. `skyLines` sets the colours of the sky lines and their names as CSS colour texts (hex, a name, or comma-form `rgb()`/`rgba()`/`hsl()`/`hsla()`): `figure` `"#8fb4ff"`, `label` `"#cfe0ff"` (the names), `boundary` `"#5f7a9c"`, `ecliptic` `"#e0b25a"`, `equator` `"#7fd1b9"`, `traced` `"#ffd166"` and `faded` `"#44546d"` (the last two are for the lines a trace draws, in a later step); `labels` sets the font (`fontFamily`, a CSS font-family text, default `"inherit"`, the page's own) and size (`sizePx`, 8 to 24, default 12) of every label in the viewer (bodies, paths, sky figures and anchors), so the defaults keep the labels as they were; a sky figure may set its own. A colour the viewer cannot read, an empty font or a size out of range throws `bad-look`. `skyLines` and `labels` have no page address parameter: they are set here, with `handle.setLook` and in the Developer drawer only. A page address parameter (table below) overrides the look it names when `address` is on. An unknown look or a value out of range throws `bad-look`. |
107
+ | `scene.setSwitches({ orbitLines?, labels?, milkyWay?, skyFigures?, skyBoundaries?, ecliptic?, celestialEquator? })` | Where each display switch shows: `{ place: "top-bar" \| "panel" \| "developer", on? }`. A top-bar switch is a button in the bar, a panel switch is a row in one switch panel opened from the bar, and a developer switch is only in the Developer drawer (where every switch stays), so it shows only when the viewer was built with `developerTools` on; with it off there is no drawer and the switch is simply not shown. `orbitLines` is the orbit ring, trailing arc and moon orbits; `labels` is body and anchor labels; `milkyWay` is the sky picture; `skyFigures` and `skyBoundaries` are the figures and the outlines of `addSkyFigures` (a switch the scene has no figure of shows nowhere); `ecliptic` and `celestialEquator` are the two reference circles of the sky. `on` is the starting state (default on, except `skyBoundaries`, `ecliptic` and `celestialEquator`, which start off). Nothing placed: the bar is as before. A bad name, place or `on` throws `bad-switch`. |
105
108
  | `scene.setViews(views, { place, start? })` | Names views of one scene: each `{ id, label, objects?, events?, panels?, camera? }` lists the `addBody`, `addGroup` and `addTrajectory` ids (`objects`), `addEvents` ids and `addStoryPanels` ids it shows. Anything no view names shows in every view; anything named shows only in the views that name it. `place` is `"top-bar"` or `"panel"`; `start` is the opening view (default the first). `camera` is `"stay"` (default), `"start"` or `{ follow: id }` / `{ focus: id }` (the object must be in the view). The rule applies only when switching to the view takes away the object the camera follows or focuses on: `"stay"` holds the camera where it is (its target fixed in the scene, so it does not move on with the hidden object), stops following and closes that object's card; `"start"` takes the scene's opening framing; `{ follow: id }` / `{ focus: id }` follows or focuses that object. A followed object still in the new view leaves the camera alone, unless the framing opts in: `{ follow: id, always: true }` / `{ focus: id, always: true }` applies it on every switch to the view, also when the camera follows an object both views show (a host's own `setCamera` made after the switch still wins over it). Read and set the view from `mount` or `AstraeusScene` ("Views from the host page"). Presentation only: State is unchanged. An empty list, a repeated id, a bad place, camera or `start` throws `bad-view` at the call (`always` must be `true` when given); an unknown id or a camera target the view hides throws `bad-view` when the scene is built. |
106
109
  | `scene.stateOf(id, time)` | The state of any body in the scene at a moment, for figures a story quotes. `positionKm` is always there; `velocityKmS` (km/s) only where the body's source gives one, so check it before use: a path from `addTrajectory` whose samples or provider carry velocities, and a moon from fitted data (Io); planets, Earth, the Sun and elements bodies give position only. Bodies: a path from `addTrajectory` (about its centre, in EQJ axes whatever `plane` it was given in), or a ready-made body, moon or elements body (about its parent). Ready-made and elements bodies answer at any date; only a moment outside an `addTrajectory` path throws `bad-time`. A planet's or fitted moon's data loads with `await scene.load({ data })` (or at `mount`, once `ready` resolves); before that it throws `missing-data`. `const au = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm) / 149597870.7;` |
107
110
  | `scene.load({ data? })` | Loads what `stateOf` and `provenanceOf` need, without a viewer: the planet series and, for each moon the scene holds, the chunks its data package provides for the scene's window. Pass the same `data` as `mount`. Rejects with `missing-data` (a body needs a package not passed) or `out-of-span`; harmless to call twice, allowed on a mounted scene, and a later `mount` re-uses what it loaded. Works in plain Node. `await scene.load({ data: [jupiterData] });` |
@@ -113,16 +116,17 @@ The full reference, generated from the types and doc comments, is at <https://as
113
116
  | `scene.moonPanel` | `{ count, summary }` of the moon panel, or `undefined` before `setMoonPanel`; `summary` reads like "115 moons in the JPL Horizons list of 18 October 2026". |
114
117
  | `scene.picker` | The picker as set (`{ id, label, options, value }`, frozen), or `undefined` before `setPicker`. |
115
118
  | `scene.places` | `{ body, count }` per `addPlaces`, in the order added; a fresh frozen list on every read. |
119
+ | `scene.skyFigures` | `{ id, label, kind, listed, provenance, description?, facts? }` per `addSkyFigures` figure, in the order added; a fresh frozen list on every read. |
116
120
  | `scene.groups` | `{ id, label, count, center, plane, provenance, description, knownLimitations }` per `addGroup`: `provenance`, `description` and `knownLimitations` are what the group's card shows (always illustrative, with the engine's placement and motion limits). |
117
121
  | `scene.activities` | `{ id, label, unit, windowStartUtcMs, windowEndUtcMs, peak: { label, value, timeUtcMs? }, samples: [{ timeUtcMs, value }], provenance?: [{ stretchStartUtcMs, stretchEndUtcMs, provenance }], type? }` per `addActivity`, in the order added; a fresh frozen copy. `peak.value` is the highest sample when no peak moment was given. |
118
122
  | `scene.events` | `{ id, label, timeUtcMs, type?, object?, withinSeconds?, provenance? }` per `addEvents`, sorted by time; `provenance` is the event's own, else the batch's. |
119
- | `scene.panels` | `{ id, timeUtcMs, title, body, details, provenance, object? }` per `addStoryPanels`, sorted by time, the times resolved as `mount` resolves them (a bad panel throws `bad-panels`). |
123
+ | `scene.panels` | `{ id, timeUtcMs?, title, body, details, provenance, object? }` per `addStoryPanels` (the actions are not read): the moment panels sorted by time, the times resolved as `mount` resolves them, then the steps (no `timeUtcMs`) in the order added (a bad panel throws `bad-panels`). |
120
124
  | `scene.views` | `{ startId, place, items: [{ id, label, objects, events, panels }] }` as named with `setViews`; undefined when none were named. `objects`, `events` and `panels` are the ids each view shows, as the viewer resolves them: what the view names plus whatever no view names (shared bodies show in every view). Fresh frozen lists on every read. The ids are checked as `mount` checks them, so an unknown one throws `bad-view`. |
121
125
  | `scene.scales` | The scale choices the viewer will offer, in order, as ids (`"true-scale"`, `"readable-scale"`, `"solar-system"`); the first is the opening scale. |
122
126
  | `scene.timeline` | `{ windowStartUtcMs, windowEndUtcMs, openUtcMs, rates, rate, loop }`: the span and opening moment in UTC milliseconds, the speeds offered, the opening speed and whether playback wraps. With nothing setting a span or moment and no path or activity, the span is a month about the moment of the read. Planet orbit lines and the far plane answer from `scene.bodies[].orbit` and `scene.camera.farEarthRadii` (when none was given, the far plane is 2.5 times `scene.camera.reachEarthRadii`). |
123
127
  | `scene.camera.follow(id, { azimuthDeg?, elevationDeg?, distance? })` | Opens framed on a body or trajectory already added, and already following it. `distance` is in Earth radii. |
124
128
  | `scene.camera.focus(id, { azimuthDeg?, elevationDeg?, distance? })` | The same opening view without following. The last of `follow` and `focus` wins. The viewer's camera menu gets a Focus and a Follow entry for every body and path. |
125
- | `mount(element, scene, { data?, onChange?, address?, developerTools? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), timeUtcMs, rate, playing, view, camera, eventZones, selected, look, scale, switches, pick, setTime(t), setRate(r), setPlaying(p), setView(id), setCamera(target), setSelected(id), setLook(look), setScale(id), setSwitch(id), setPick(value), onChange(fn), onEventZone(fn), onSelect(fn), onCameraChange(fn), onFirstDraw(fn), onPick(fn) }`. `data` is a list of data packages (below); `address` is off by default (see "Page address"); `developerTools` is off by default (the cog and the Developer drawer are not drawn, and the drawer's code is never fetched; the demo site turns it on); the time and speed members are described under "Reading and setting the time". |
129
+ | `mount(element, scene, { data?, onChange?, address?, developerTools? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), timeUtcMs, rate, playing, view, camera, eventZones, selected, panel, look, scale, switches, skyFigures, pick, setTime(t), setRate(r), setPlaying(p), setView(id), setCamera(target), setSelected(id), setPanel(id), setLook(look), setScale(id), setSwitch(id), traceSkyFigure(id), clearSkyTrace(id), setPick(value), onChange(fn), onEventZone(fn), onSelect(fn), onPanel(fn), onCameraChange(fn), onFirstDraw(fn), onPick(fn) }`. `data` is a list of data packages (below); `address` is off by default (see "Page address"); `developerTools` is off by default (the cog and the Developer drawer are not drawn, and the drawer's code is never fetched; the demo site turns it on); the time and speed members are described under "Reading and setting the time". |
126
130
  | `<AstraeusScene scene data? ref? onReady? onError? time? rate? view? camera? onChange? onEventZone? onPick? onFirstDraw? address? developerTools? className? style? />` | The same viewer as a React component (below). |
127
131
  | `SceneError` | Thrown for bad input. `error.code` is one of the documented `SceneErrorCode` values (for example `unknown-body`, `bad-time`, `missing-data`, `no-orbit`) and the message says what to do. |
128
132
 
@@ -165,20 +169,24 @@ The viewer has one clock (and, with `setViews`, one current view: rows below). A
165
169
  | `handle.setTime(time)` | Moves the viewer to `time` (ISO text, a `Date` or milliseconds). Outside the timeline throws `bad-time`. It counts as a seek for story panels, as the visitor's slider does: moving across a panel's time opens nothing by itself. Before `ready` or after `unmount` throws `not-mounted`. |
166
170
  | `handle.setRate(rate)` | Sets the speed to one the timeline offers (`setTimeline({ rates })`). Any other number throws `bad-timeline`: the speed menu always shows what is running, so a custom speed is refused, not added. `handle.setRate("auto")` hands the speed back to the scene's pacing (below); without pacing it throws `bad-timeline`. |
167
171
  | `handle.playing` and `handle.setPlaying(playing)` | `playing` reads whether the viewer is playing (undefined before `ready` and after `unmount`). `setPlaying(true)` or `setPlaying(false)` plays or pauses through the same handler as the visitor's play button; `onChange` hears it with `cause: "host"` and the new `playing`. A non-boolean, or a scene with `setTimeline({ none: true })` (no play control for a visitor either), throws `bad-timeline`. |
168
- | `handle.look`, `handle.setLook(look)` | `look` reads the looks in force with every one filled in (`starBrightness`, `milkyWay`, `milkyWayBrightness`, `skyVisible`, `sunGlow?` as `{ sizePx, brightness, scale }`, `markerSwapRadiusPx`, `featureMinBodyPx`, `loadFadeSeconds`, `desktopPictures`), whoever set them: the scene's `setLook`, the page address, your `setLook` or a visitor in the Developer drawer. `setLook(look)` replaces the whole look (a look not named takes its default) and is checked as `Scene.setLook` checks it (`bad-look`); a live `setLook` wins over the same look in the page address, which only starts the viewer. Presentation only. `look` is `undefined` until `ready` and after `unmount`; `setLook` before `ready` or after `unmount` throws `not-mounted`. |
172
+ | `handle.look`, `handle.setLook(look)` | `look` reads the looks in force with every one filled in (`starBrightness`, `milkyWay`, `milkyWayBrightness`, `skyVisible`, `sunGlow?` as `{ sizePx, brightness, scale }`, `markerSwapRadiusPx`, `featureMinBodyPx`, `loadFadeSeconds`, `skyFadeInSeconds`, `desktopPictures`, `skyLines` and `labels` as filled-in objects), whoever set them: the scene's `setLook`, the page address, your `setLook` or a visitor in the Developer drawer. `setLook(look)` replaces the whole look (a look not named takes its default) and is checked as `Scene.setLook` checks it (`bad-look`); a live `setLook` wins over the same look in the page address, which only starts the viewer. Presentation only. `look` is `undefined` until `ready` and after `unmount`; `setLook` before `ready` or after `unmount` throws `not-mounted`. |
169
173
  | `handle.onFirstDraw(fn)` or `<AstraeusScene onFirstDraw />` | `fn()` once when the scene's first frame has been drawn (not `ready`, which resolves a moment earlier, when the clock attaches), for fading your own loading cover; returns a function that stops it. A listener added after that frame is called at once. A rebuild with a new `scene` draws a new first frame and calls the listeners still added again (the React prop is called again). A listener that throws is reported to the page (`reportError`) and does not stop the next; nothing arrives after `unmount`. |
170
174
  | `handle.pick`, `handle.setPick(value)`, `handle.onPick(fn)` or `<AstraeusScene onPick />` | `pick` reads the value of the pressed option of the scene's picker (`undefined` until `ready`, after `unmount`, and without a picker). `setPick(value)` moves the pressed option and does nothing else (no signal); a scene without a picker, or an unknown value, throws `bad-picker`; before `ready` or after `unmount`, `not-mounted`. `fn({ picker, value })` is called when a visitor presses an option other than the pressed one; the pressed option stays where it was until the host calls `setPick` (or builds a new scene). To keep the clock across a choice, read `handle.timeUtcMs` inside `fn`, build the next scene and call `setTime` on it once ready. Returns a function that stops it. A listener that throws is reported to the page (`reportError`) and does not stop the next; nothing arrives after `unmount`. |
171
175
  | `handle.scale`, `handle.setScale(id)` | The id of the scale showing, and a switch to one of `scene.scales` as if a visitor pressed the scale button; any other id throws `bad-scale`. |
172
- | `handle.switches`, `handle.setSwitch(id, on)` | The display switches the scene placed with `setSwitches` (`orbitLines`, `labels`, `milkyWay`; wherever it placed them) that have something to act on, each `true` (on) or `false`; `{}` when it placed none. `setSwitch` turns one on or off as the visitor's button does; an id the scene did not place, or a non-boolean, throws `bad-switch`. |
176
+ | `handle.switches`, `handle.setSwitch(id, on)` | The display switches the scene placed with `setSwitches` (`orbitLines`, `labels`, `milkyWay`, `skyFigures`, `skyBoundaries`, `ecliptic`, `celestialEquator`; wherever it placed them) that have something to act on, each `true` (on) or `false`; `{}` when it placed none. `setSwitch` turns one on or off as the visitor's button does; an id the scene did not place, or a non-boolean, throws `bad-switch`. |
177
+ | `handle.skyFigures` | The sky figures the viewer draws (`scene.addSkyFigures`), `{ id, label, kind, listed, provenance, description?, facts? }` each, in the order added; `[]` when the scene added none; undefined before `ready` and after `unmount`. |
178
+ | `handle.traceSkyFigure(id, { durationSeconds?, after? })` | Draws the sky figure `id` (one of `handle.skyFigures`) line by line: its segments in the order added, each growing from its first end, over `durationSeconds` (0.1 to 60, default 2) in the look's `skyLines.traced` colour. Then `after` decides: `"stay"` (default) keeps the traced lines until the figure is traced again, `"fade"` eases them to `skyLines.faded` over a second and removes them (`clearSkyTrace` removes a trace at any time). The trace is drawn over the figure (for a figure with `shown: "whenTraced"` the trace is the whole drawing: lines growing in order, the label appearing when the trace starts; `"stay"` keeps both, `"fade"` dims both to nothing over the second, `clearSkyTrace` removes both, and a new trace starts again from nothing) and follows its switch (`skyFigures` or `skyBoundaries`): with the switch off it runs unseen. It runs on real time, so pausing or changing the speed of the scene clock does not change it, and it starts only when the app asks (no trace is timed by the scene clock). Calling again restarts it. With `prefers-reduced-motion: reduce` the whole figure shows at once, stays for `durationSeconds`, and then `after` applies (a `fade` ends at once). An id the viewer does not draw throws `unknown-sky-figure`; bad options throw `bad-sky-trace`; before `ready` or after `unmount`, `not-mounted`. Like every host call it lands in call order. |
173
179
  | `handle.onChange(fn)` or `mount(..., { onChange })` | `fn({ timeUtcMs, rate, playing, view?, scale, look, switches?, cause })` on every change (`view` only in a scene with views; `switches` only in a scene that placed some); returns a function that stops it. `cause` is `playback` (the clock ran on; about ten calls a second while playing), `visitor` (someone used the timeline, the view choice, the scale, a display switch or the Developer drawer) or `host` (your own `setTime`, `setRate`, `setPlaying`, `setView`, `setScale`, `setSwitch` or `setLook`). Nothing arrives after `unmount`. |
174
180
  | `<AstraeusScene ref onReady />` | The `ref` and the `onReady(handle)` argument are the handle above (`timeUtcMs`, `rate`, `playing`, `view`, `camera`, `eventZones`, `selected`, the `set` calls, `onChange`, `onEventZone`, `onSelect`, `onCameraChange`): `onReady={(handle) => handle.setTime(...)}` or `ref.current` after it. |
175
181
  | `<AstraeusScene time rate onChange />` | `time` and `rate` are applied once the viewer is drawn and again whenever their value changes (a new `Date` of the same moment does not seek again); they are not controlled values, so read the live time from `onChange`. A bad one goes to `onError`. |
182
+ | `handle.clearSkyTrace(id, { durationSeconds? })` | Removes the trace of the sky figure `id` at any time: while it runs, after `"stay"`, or during a `"fade"`. The traced lines ease out over `durationSeconds` (0 to 60, default 1, the time a `"fade"` takes; 0 removes them at once), keeping the part drawn so far. A figure with `shown: "whenTraced"` is then hidden (lines and label); an always-shown figure only loses the trace highlight. A figure with no trace is left alone (no error), and a new trace starts from nothing. With `prefers-reduced-motion: reduce` the trace goes at once. An id the viewer does not draw throws `unknown-sky-figure`; bad options throw `bad-sky-trace`; before `ready` or after `unmount`, `not-mounted`. Like every host call it lands in call order. |
183
+ | `handle.panel`, `handle.setPanel(id)`, `handle.onPanel(fn)` | The id of the open story panel or step (undefined when none), opening another by id (or `undefined` to close the open one), and `onPanel({ panel?, timeUtcMs, cause })` when it changes (`panel` absent when it closed; `cause` is `visitor` for Close, Back, Next, a marker or the timeline, `host` for `setPanel` or a drop by the host's `setView`, `playback` for a moment panel that opened by itself). The panel the viewer opens with is read, not reported. An id the showing view does not show, or a non-string, throws `bad-panels`; before `ready` or after `unmount`, `not-mounted`. Calls land in order. |
176
184
  | `handle.selected`, `handle.setSelected(id)` | The id of the selected object, and a choice of another (or `undefined` to clear): see "Selection" below. An id the showing view does not show throws `bad-selection`; before `ready` or after `unmount`, `not-mounted`. `onSelect` hears it with `cause: "host"`. |
177
185
  | `handle.view`, `handle.setView(id)` | The id of the view showing (`setViews`), and a switch to another, as if a visitor pressed its button: the same camera rule applies. `view` is `undefined` until `ready`, after `unmount`, and in a scene without views. `setView` with an unknown id, or on a scene without views, throws `bad-view`; before `ready` or after `unmount`, `not-mounted`. `onChange` hears it with `cause: "host"` (a visitor's own choice is `"visitor"`). |
178
186
  | `<AstraeusScene view />` | Switches to that view once drawn and whenever it changes; not a controlled value (a visitor can switch too), so read the live view from `onChange`. An unknown id goes to `onError` as `bad-view`. |
179
- | `handle.setCamera(target)` | Points the camera, through the same request path a view's camera rule uses; it eases there. `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, and a pose from `handle.camera` puts the camera back (below). The object must be one the showing view shows: an unknown or hidden id, or a malformed argument, throws `bad-camera`; before `ready` or after `unmount`, `not-mounted`. |
180
- | `handle.camera` | The camera now as a plain value `{ focus, azimuthDeg, elevationDeg, distance }` (the pose a copied view link carries: the object's id, angles about the up direction in degrees to 0.01, distance in Earth radii to five figures). Safe to keep, store or `JSON.stringify`. `undefined` until `ready` and after `unmount`; from `ready` on it is always defined (before the scene's first frame it is the opening pose, the scene's start view or default framing). `setCamera(handle.camera)` after the visitor has moved the camera puts it back at the same angles and distance from the same object, within the rounding; the offset is the object's own, so an object that moved meanwhile is followed from where it is now. A camera held in place by a view's `"stay"` rule reads as its last object, which is not where it looks. |
181
- | `<AstraeusScene camera />` | `{ follow: id }`, `{ focus: id }` or a pose, applied once drawn and whenever its value changes (a new object with the same target, or a pose with its keys in another order, does not apply again); not a controlled value. A bad one goes to `onError` as `bad-camera`. |
187
+ | `handle.setCamera(target)` | Points the camera, through the same request path a view's camera rule uses; it eases there. `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, `{ lookOut: id, direction?, fovDeg? }` stands inside the body looking out (`direction` is `{ raDeg, decDeg }`, J2000 equatorial degrees, or the id of an object or sky figure to turn toward; omitted, it keeps the direction already looked along, else right ascension 0, declination 0; `fovDeg` is 5 to 100 degrees, omitted keeps the current one, else 60; Focus, Follow, Overview or an orbit pose return to the orbit camera), and a pose from `handle.camera` (either kind) puts the camera back (below). Every id must be an object the showing view shows: an unknown or hidden id (the body, or the object to turn toward), a direction or field of view out of range, or a malformed argument, throws `bad-camera`; before `ready` or after `unmount`, `not-mounted`. |
188
+ | `handle.camera` | The camera now as a plain value of one of two kinds, a `CameraPose`, which is an `OrbitPose` or a `SkyPose`. Tell them apart with `"lookOut" in pose` (a sky pose has no `distance`): an app that reads `pose.distance` must first check `if ("lookOut" in pose) { /* sky pose: lookOut, raDeg, decDeg, fovDeg */ } else { /* orbit pose */ }`. While the camera orbits an object it is the orbit pose `{ focus, azimuthDeg, elevationDeg, distance }`; while it stands inside a body looking out it is the sky pose `{ lookOut, raDeg, decDeg, fovDeg }` (the body's id; where it points in J2000 equatorial degrees, right ascension 0 up to 360 and declination within ±90, rounded to 0.01; the vertical field of view in degrees, 5 to 100) and the copied view link carries it as `?view=body,raDeg,decDeg,fovDeg,sky`. For an orbit pose (the pose a copied view link carries: the object's id, angles about the up direction in degrees to 0.01, distance in Earth radii to five figures). Safe to keep, store or `JSON.stringify`. `undefined` until `ready` and after `unmount`; from `ready` on it is defined (before the scene's first frame it is the opening pose, the scene's start view or default framing), except that an opening `lookOut` toward an object or sky figure id reads `undefined` until the first frame has turned toward it. `setCamera(handle.camera)` after the visitor has moved the camera puts it back at the same angles and distance from the same object, within the rounding; the offset is the object's own, so an object that moved meanwhile is followed from where it is now. A camera held in place by a view's `"stay"` rule reads as its last object, which is not where it looks. |
189
+ | `<AstraeusScene camera />` | `{ follow: id }`, `{ focus: id }`, `{ lookOut: id, direction?, fovDeg? }` or a pose (either kind), applied once drawn and whenever its value changes (a new object with the same target, or a pose with its keys in another order, does not apply again); not a controlled value. A bad one goes to `onError` as `bad-camera`. |
182
190
 
183
191
  ```ts
184
192
  const mounted = mount(el, scene);
@@ -225,11 +233,11 @@ Speeds ease between pieces in log space over `rampSeconds` simulated seconds (de
225
233
 
226
234
  In a scene with views (`setViews`), an event rule slows playback only near the events the showing view has (an event no view names is in every view); spans apply in every view. A switch that changes the paced speed eases to the new one in log space over about a second, while seeking lands on the paced speed at once. A scene without views paces exactly as before.
227
235
 
228
- Selection: `mounted.selected` reads the id of the object whose information the viewer has open (undefined before `ready`, after `unmount`, and when nothing is selected), and `mounted.onSelect(listener)` calls `listener({ object?, timeUtcMs, cause })` when it changes: `object` is the new id (absent when the selection was dropped and nothing took its place), `cause` is `visitor` for the object menu, a click or a time, speed or view the visitor chose, `host` for `setSelected` and for a drop caused by the host's own `setTime`, `setRate`, `setPlaying` or `setView`, and `playback` for a drop caused by the clock running (for example past the end of a path's samples); a drop names the same cause `onChange` gave the move that caused it. The selection the viewer opens with is read, not reported. `mounted.setSelected(id)` selects an object the showing view shows, or clears the selection with `undefined`: `selected` reads it at once and `onSelect` hears it with `cause: "host"` (nothing is reported when the selection is already that). An unknown or hidden id, an empty or non-string id throws `bad-selection`; before `ready` or after `unmount`, `not-mounted`. It follows the order rule: made straight after `await ready`, or inside an `onChange` report of a view switch, it holds over the view's own framing. It selects as the object menu does, minus the camera: the object's card opens and the camera stays (`setCamera` points it); a clear closes the card. A selection cleared by the host stays cleared until someone selects again. `onSelect` returns the function that stops it; nothing arrives after `unmount`.
236
+ Selection: `mounted.selected` reads the id of the object whose information the viewer has open (undefined before `ready`, after `unmount`, and when nothing is selected), and `mounted.onSelect(listener)` calls `listener({ object?, timeUtcMs, cause })` when it changes: `object` is the new id (absent when the selection was dropped and nothing took its place), `cause` is `visitor` for the object menu, a click or a time, speed or view the visitor chose, `host` for `setSelected` and for a drop caused by the host's own `setTime`, `setRate`, `setPlaying` or `setView`, and `playback` for a drop caused by the clock running (for example past the end of a path's samples); a drop names the same cause `onChange` gave the move that caused it. The selection the viewer opens with is read, not reported. `mounted.setSelected(id)` selects an object the showing view shows, or a sky figure (an id in `skyFigures`; its card opens), or clears the selection with `undefined`: `selected` reads it at once and `onSelect` hears it with `cause: "host"` (nothing is reported when the selection is already that). An unknown or hidden id, an empty or non-string id throws `bad-selection`; before `ready` or after `unmount`, `not-mounted`. It follows the order rule: made straight after `await ready`, or inside an `onChange` report of a view switch, it holds over the view's own framing. It selects as the object menu does, minus the camera: the object's card opens and the camera stays (`setCamera` points it); a clear closes the card. A selection cleared by the host stays cleared until someone selects again. `onSelect` returns the function that stops it; nothing arrives after `unmount`.
229
237
 
230
238
  The mount handle's members live on its prototype (the same builder serves the React `ref`), so spreading it (`{ ...handle }`) or `Object.keys(handle)` shows only `ready` and `unmount`. Read and call members by name (`handle.timeUtcMs`, `handle.setTime(...)`, or destructure them); they are all there.
231
239
 
232
- Camera: `mounted.onCameraChange(listener)` calls `listener(pose)` with the camera as a plain value (`{ focus, azimuthDeg, elevationDeg, distance }`, what `mounted.camera` reads) when it changes: a visitor's drag, zoom or pick, a view's camera rule, or your own `setCamera` (it reports as the camera eases, then stops when the pose settles). At most about ten reports a second; an unchanged pose reports nothing, and a camera following a moving object at a fixed pose reports nothing. The opening pose is read from `camera`, not reported. It returns the function that stops it; nothing arrives after `unmount`; a listener that throws is reported to the page and does not stop the others.
240
+ Camera: `mounted.onCameraChange(listener)` calls `listener(pose)` with the camera as a plain value (an orbit pose `{ focus, azimuthDeg, elevationDeg, distance }` or a sky pose `{ lookOut, raDeg, decDeg, fovDeg }`, what `mounted.camera` reads; check `"lookOut" in pose` before reading `distance`) when it changes: a visitor's drag, zoom or pick, a view's camera rule, or your own `setCamera` (it reports as the camera eases, then stops when the pose settles). At most about ten reports a second; an unchanged pose reports nothing, and a camera following a moving object at a fixed pose reports nothing. The opening pose is read from `camera`, not reported. It returns the function that stops it; nothing arrives after `unmount`; a listener that throws is reported to the page and does not stop the others.
233
241
 
234
242
  An event has one zone, as wide as its widest pacing rule: when several rules match the same event the event is in its zone while playback is inside any of them (the rules' stretches are centred on the event, so the widest one), and `onEventZone` reports it once, not once per rule. An event's own `withinSeconds` replaces each rule's width for that event.
235
243
 
@@ -350,10 +358,14 @@ Every call that refuses its input throws a `SceneError`, a `RangeError` with a s
350
358
  | `bad-moon-panel` | The moon panel (`setMoonPanel`) is malformed, or names a moon the scene does not hold. |
351
359
  | `bad-picker` | The picker (`setPicker`, `setPick`) is malformed, or a pick names an option it does not have. |
352
360
  | `bad-places` | A body's places (`addPlaces`) are malformed, or name a body the scene does not hold. |
361
+ | `bad-sky-figure` | A sky figure (`addSkyFigures`) is malformed: its id, label, kind, segments, points or label position. |
362
+ | `unknown-sky-figure` | `traceSkyFigure` or `clearSkyTrace` was given a figure id the viewer does not draw (see `handle.skyFigures`). |
363
+ | `bad-sky-trace` | `traceSkyFigure` was given options that are not `{ durationSeconds?, after? }`, a `durationSeconds` outside 0.1 to 60, or an `after` other than `stay` or `fade`; or `clearSkyTrace` was given options that are not `{ durationSeconds? }` or a `durationSeconds` outside 0 to 60. |
364
+ | `unknown-star` | A sky figure names a star whose Hipparcos number is not in the engine's star list (stars of magnitude 6.5 or brighter). Found when the scene is built, as the star list loads then. |
353
365
  | `bad-activity` | An activity curve is malformed. |
354
366
  | `bad-camera` | A camera call or pose is malformed, or names an object the view cannot show. |
355
367
  | `bad-view` | A scene view is malformed, repeated, or not one of the scene's views. |
356
- | `bad-selection` | `setSelected` was given something other than an id of an object the showing view shows, or `undefined`. |
368
+ | `bad-selection` | `setSelected` was given something other than an id of an object the showing view shows, a sky figure, or `undefined`. |
357
369
  | `bad-look` | A look (`setLook`) is unknown or out of its range. |
358
370
  | `renamed` | An input field was given under a name it no longer has; the message names the old field and its replacement. |
359
371
  <!-- error-table:end -->
@@ -380,6 +392,7 @@ The engine alone draws the Sun, Earth, Moon and the eight planets with their pic
380
392
  |---|---|---|
381
393
  | `astraeus-data` | Moon pictures (Io to Charon), the 8k Venus map, the Milky Way | about 39 MB |
382
394
  | `astraeus-data-jupiter`, `-saturn`, `-uranus`, `-neptune`, `-mars`, `-pluto` | Moon positions for that planet's system | 1.5 to 53 MB each (Saturn 53, Uranus 41, Jupiter 31, Neptune 19, Mars 5, Pluto 1.5) |
395
+ | `astraeus-data-constellations` | The 88 IAU constellations as sky figures and boundary outlines, ready for `scene.addSkyFigures(await constellations("all"))` | under 0.1 MB |
383
396
 
384
397
  Years each package covers: the main moons and the planet reach back to 1950 in `astraeus-data-jupiter` (Io, Europa, Ganymede, Callisto), `-saturn` (Mimas, Enceladus, Tethys, Dione, Rhea, Titan, Hyperion, Iapetus, Phoebe), `-uranus` (Miranda, Ariel, Umbriel, Titania, Oberon) and `-neptune` (Triton, Nereid), 1950 to 2030; every other moon, and all of `-mars` and `-pluto`, covers 2010 to 2030. A scene whose timeline reaches outside a body's years fails once at mount with `SceneError` code `out-of-span`.
385
398
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "astraeus",
3
- "version": "0.8.1",
3
+ "version": "0.9.0",
4
4
  "description": "A 3D solar system engine for the browser: place bodies and recorded paths in a scene, mount it, and get time controls, camera, scale choice and body info. Planet positions and the main pictures included.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -23,7 +23,7 @@ export interface AstraeusSceneProps {
23
23
  readonly rate?: number | "auto";
24
24
  /** Switches to this view (an id from `setViews`) once drawn, and again whenever it changes. Not a controlled value: a visitor can switch too, and the view showing arrives through `onChange`. An unknown id, or a scene without views, reports `bad-view` to `onError`. */
25
25
  readonly view?: string;
26
- /** Points the camera once drawn, and whenever the target changes by value (a new object with the same target does not re-apply): `{ follow: id }`, `{ focus: id }` or a pose read from a `mount` handle. Not a controlled value: a visitor can move the camera afterwards. A bad one reports `bad-camera` to `onError`. */
26
+ /** Points the camera once drawn, and whenever the target changes by value (a new object with the same target does not re-apply): `{ follow: id }`, `{ focus: id }`, `{ lookOut: id, direction?, fovDeg? }` or a pose (either kind) read from a `mount` handle. Not a controlled value: a visitor can move the camera afterwards. A bad one reports `bad-camera` to `onError`. */
27
27
  readonly camera?: CameraTarget;
28
28
  /** Called whenever the viewer's time, speed, playing state or view changes: playback running, a visitor using the timeline or the view choice, or the `time` / `rate` / `view` props. About ten times a second while playing. */
29
29
  readonly onChange?: (change: ViewerChange) => void;
@@ -9,7 +9,10 @@ import { ViewerLink } from "./viewerLink.js";
9
9
  const FILL = { width: "100%", height: "100%" };
10
10
  const asError = (cause) => (cause instanceof Error ? cause : new Error(String(cause)));
11
11
  /** A camera target as text by value: keys in sorted order, so the same pose with its keys in another order is the same key. */
12
- const cameraValueKey = (camera) => JSON.stringify(Object.entries(camera).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
12
+ const cameraValueKey = (camera) => {
13
+ const sorted = (value) => (typeof value !== "object" || value === null ? value : Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([key, inner]) => [key, sorted(inner)])));
14
+ return JSON.stringify(Object.entries(sorted(camera)));
15
+ };
13
16
  /**
14
17
  * The full viewer `mount` draws, as a React component: `<AstraeusScene scene={scene} data={[...]} />`. Waits for the scene's data, then draws; cleans up on unmount.
15
18
  * @example
@@ -8,7 +8,10 @@ import { ViewerLink } from "./viewerLink.js";
8
8
  const FILL = { width: "100%", height: "100%" };
9
9
  const asError = (cause) => (cause instanceof Error ? cause : new Error(String(cause)));
10
10
  /** A camera target as text by value: keys in sorted order, so the same pose with its keys in another order is the same key. */
11
- const cameraValueKey = (camera) => JSON.stringify(Object.entries(camera).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
11
+ const cameraValueKey = (camera) => {
12
+ const sorted = (value) => (typeof value !== "object" || value === null ? value : Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([key, inner]) => [key, sorted(inner)])));
13
+ return JSON.stringify(Object.entries(sorted(camera)));
14
+ };
12
15
  /**
13
16
  * The full viewer `mount` draws, as a React component: `<AstraeusScene scene={scene} data={[...]} />`. Waits for the scene's data, then draws; cleans up on unmount.
14
17
  * @example
@@ -14,6 +14,7 @@ import { type Tracked } from "./planPaths.js";
14
14
  import type { StoryPlan } from "./planStory.js";
15
15
  import type { TimelinePlan } from "./planTimeline.js";
16
16
  import type { ViewPlan } from "./planViews.js";
17
+ import type { SkyFigurePlan } from "./planSkyFigures.js";
17
18
  /** What a `Scene` hands the assembler: the planners it has filled, its camera and its scale choice. Internal; never exported from the package. */
18
19
  export interface ScenePlanners {
19
20
  readonly plan: BodyPlan;
@@ -26,6 +27,7 @@ export interface ScenePlanners {
26
27
  readonly story: StoryPlan;
27
28
  readonly timeline: TimelinePlan;
28
29
  readonly viewPlan: ViewPlan;
30
+ readonly skyFigures: SkyFigurePlan;
29
31
  readonly camera: SceneCamera;
30
32
  readonly scale: ScalePolicy;
31
33
  readonly scaleOnly: boolean;
@@ -8,9 +8,10 @@ import { needsPlanetSeries } from "../app/planetNeeds.js";
8
8
  import { createReadoutMetrics } from "../app/trackedMetrics.js";
9
9
  import { checkDataSources, installData } from "./data.js";
10
10
  import { SceneError } from "./errors.js";
11
- import { cameraPresetsOf, fitFarthestKm, startPresetEntry, startViewEntry, viewEntries } from "./planCamera.js";
11
+ import { cameraPresetsOf, checkOpeningLook, fitFarthestKm, startPresetEntry, startViewEntry, viewEntries } from "./planCamera.js";
12
12
  import { groupLayersEntry, lateGroups } from "./planGroups.js";
13
13
  import { autoPaths, checkNamedReadouts, checkReadouts, pathCover } from "./planPaths.js";
14
+ import { loadStarCatalogue, starIdsOf } from "../assets/sky.js";
14
15
  /** The `out-of-span` error naming the planets when the scene's window reaches outside the years the planet series cover (the series are loaded); undefined otherwise. */
15
16
  function planetSpanError(ids, window) {
16
17
  const planets = ids.filter(isPlanetId);
@@ -61,7 +62,7 @@ function deferredRead(ids, window, fault, fallback, read) {
61
62
  }
62
63
  /** The app's plug-in contract for a scene's planners. Throws if the scene is empty or a body needs a data package not passed in `data`. */
63
64
  export function assembleScene(parts, data) {
64
- const { plan, groupPlan, bodySets, moonPanel, places, story, timeline: timelinePlan, viewPlan, camera, tracked: trackedMap } = parts;
65
+ const { plan, groupPlan, bodySets, moonPanel, places, story, timeline: timelinePlan, viewPlan, camera, tracked: trackedMap, skyFigures } = parts;
65
66
  if (plan.bodies.size === 0)
66
67
  throw new SceneError("empty-scene", "the scene has no bodies; call addBody before mount");
67
68
  checkDataSources(data);
@@ -89,7 +90,7 @@ export function assembleScene(parts, data) {
89
90
  const fit = deferredRead(ids, window, fault, undefined, () => fitFarthestKm(camera, plan.catalogue, plan.own, startUtcMs));
90
91
  // The lines read planet positions; when the planet series are not loaded yet (a consumer's mount), they are drawn in `prepare`, once the series are in. The viewer draws only after `prepare` resolves.
91
92
  const sunPaths = deferredRead(ids, window, fault, [], () => plan.earlySunPaths(sunOrbitIds, startUtcMs, planetSeriesLoaded()));
92
- const storyPanels = story.panels(window, trackedMap.values(), [...plan.bodies.keys(), ...trackedMap.keys(), ...groupPlan.groups.keys(), ...bodySets.memberIds()]);
93
+ const storyPanels = story.panels(window, trackedMap.values(), [...plan.bodies.keys(), ...trackedMap.keys(), ...groupPlan.groups.keys(), ...bodySets.memberIds()], [...skyFigures.figures.keys()]);
93
94
  groupPlan.check(ids);
94
95
  bodySets.check({ ids, catalogue: plan.catalogue, orbits: plan.orbits });
95
96
  // A clump near a body reads its position; with the planet series not loaded yet, those groups are built in `prepare` (the viewer draws only after it resolves).
@@ -101,7 +102,7 @@ export function assembleScene(parts, data) {
101
102
  const catalogue = plan.catalogue;
102
103
  if (camera.following && camera.target !== undefined && camera.followChoices !== undefined && !camera.followChoices.includes(camera.target))
103
104
  throw new SceneError("bad-camera", `camera.follow("${camera.target}"): the opening view follows "${camera.target}", which camera.setFollowChoices does not list`);
104
- story.checkObjects(new Set(labelled.map(({ id }) => id)));
105
+ story.checkObjects(new Set([...labelled.map(({ id }) => id), ...skyFigures.figures.keys()]));
105
106
  const objects = [
106
107
  ...[...plan.bodies.values()].map((body) => plan.bodyObject(body, ids, sunCentred, camera)),
107
108
  ...[...trackedMap.values()].map(({ body, description, knownLimitations, provenanceSpans }) => ({ id: body.id, label: body.label, color: body.color, availability: body.trajectory.bounds, labelPriority: 80, ...plan.labelReach(body.id, sunCentred, camera), provenance: body.provenance, ...(provenanceSpans === undefined ? {} : { provenanceSpans }), ...(description === undefined ? {} : { description }), ...(knownLimitations === undefined ? {} : { knownLimitations }) })),
@@ -110,14 +111,16 @@ export function assembleScene(parts, data) {
110
111
  const pictures = mergePictures(data.map((source) => source.pictures));
111
112
  const members = new Set(bodySets.memberIds());
112
113
  const moonFamilies = moonPanel.list(new Map(objects.filter(({ id }) => plan.bodies.has(id) || members.has(id)).map(({ id, label }) => [id, label])), new Set(ids), plan.catalogue, (picture) => pictures[picture]?.url);
114
+ const figures = skyFigureLayers(skyFigures);
113
115
  const bodyFeatures = places.featureSets(new Map(objects.map(({ id, label }) => [id, label])));
114
116
  const definition = {
115
117
  experience: {
116
118
  objects,
117
- cameraPresets: cameraPresetsOf(labelled, camera.followChoices),
119
+ cameraPresets: cameraPresetsOf(labelled, camera.followChoices, camera.lookOutChoices),
118
120
  ...startPresetEntry(camera),
119
121
  ...(moonFamilies === undefined ? {} : { moonFamilies }),
120
122
  ...(bodyFeatures.length === 0 ? {} : { bodyFeatures }),
123
+ ...(skyFigures.figures.size === 0 ? {} : { skyFigures: skyFigures.cards() }),
121
124
  events: story.events,
122
125
  ...story.provenanceEntries(),
123
126
  ...(storyPanels === undefined ? {} : { storyPanels }),
@@ -131,6 +134,7 @@ export function assembleScene(parts, data) {
131
134
  ...groupLayersEntry(layers, groupPlan.groups.size > 0, sunOrbitIds.length > 0),
132
135
  ...(sunOrbitIds.length === 0 ? {} : { paths: sunPaths }),
133
136
  ...(setLayers.length === 0 ? {} : { bodySets: setLayers }),
137
+ ...figures.entry,
134
138
  ...(plan.catalogue === builtInCatalogue ? {} : { catalogue: plan.catalogue }),
135
139
  ...plan.visualOverrides(),
136
140
  // The viewer draws only the pictures of the packages passed to it (T-252); nothing is shared between viewers.
@@ -164,8 +168,10 @@ export function assembleScene(parts, data) {
164
168
  if (fit !== undefined)
165
169
  planetRead(ids, window, () => fit.settle());
166
170
  await installData(data, ids, window, catalogue, bodySets.load());
171
+ await figures.settle();
167
172
  },
168
173
  };
174
+ checkOpeningLook(camera, definition, groupPlan.groups.keys(), skyFigures.figures.keys());
169
175
  return definition;
170
176
  }
171
177
  /** The viewer's own pictures (those of the packages passed to it); absent when no package brings any. */
@@ -173,3 +179,19 @@ function picturesEntry(data) {
173
179
  const pictures = mergePictures(data.map((source) => source.pictures));
174
180
  return Object.keys(pictures).length === 0 ? {} : { pictures };
175
181
  }
182
+ /** The sky figures' drawable layers: placed now when no end names a star, else by `settle` (in `prepare`), once the star list has loaded (the viewer draws only after `prepare` resolves). */
183
+ function skyFigureLayers(plan) {
184
+ const layers = plan.needsStars ? [] : [...plan.layers(new Map())];
185
+ return {
186
+ entry: plan.figures.size === 0 ? {} : { skyFigures: layers },
187
+ settle: async () => { if (plan.needsStars && layers.length === 0)
188
+ layers.push(...plan.layers(await starsOf())); },
189
+ };
190
+ }
191
+ /** The star list's stars by Hipparcos number, for placing figures that name stars; the list unreadable throws `missing-data`. */
192
+ async function starsOf() {
193
+ const loaded = await loadStarCatalogue();
194
+ if (loaded === null)
195
+ throw new SceneError("missing-data", "a sky figure names a star, but the engine's star list could not be read; check that the star file is served with the app, or place the figure by { raDeg, decDeg }");
196
+ return starIdsOf(loaded);
197
+ }
@@ -0,0 +1,15 @@
1
+ import type { CameraRequest } from "../app/CameraController.js";
2
+ import type { CameraPose } from "./viewerLink.js";
3
+ /**
4
+ * Checks the shape of a camera target (what `setCamera` takes) and turns it into the request the scene camera runs; a malformed one throws `bad-camera` leading with `call`.
5
+ * It does not look at the scene: which ids exist is the caller's check. A look-out target without a direction takes the one `now` looks along while looking out, else right ascension 0, declination 0;
6
+ * with `keepDirection` it is left out of the request instead, and the camera keeps its own when the request runs (a story panel's camera, decided as it opens).
7
+ */
8
+ export declare function cameraRequestOf(target: unknown, call: string, now: CameraPose | undefined, keepDirection?: boolean): CameraRequest;
9
+ /**
10
+ * Checks the ids a camera request names against what the viewer can turn toward: each body or object must be one of `shown` (the objects the view named by `view` shows),
11
+ * and a look-out direction id one of those or of `figures` (the scene's sky figures). Throws `bad-camera` leading with `call`. `setCamera` runs it as it is called; the opening look-out runs `checkToward` when the scene is built.
12
+ */
13
+ export declare function checkCameraIds(request: CameraRequest, call: string, shown: readonly string[], figures: readonly string[], view?: string): void;
14
+ /** The look-out direction id half of `checkCameraIds`: `toward` must be an object `view` shows or a sky figure, else `bad-camera` naming it. */
15
+ export declare function checkToward(toward: string, call: string, shown: readonly string[], figures: readonly string[], view?: string): void;
@@ -0,0 +1,89 @@
1
+ import { cameraIdsOf } from "../core/storyPanels.js";
2
+ import { eqjUnitVector, validateSkyDirection, validateSkyFov, validateSkyPosition, validateStartView } from "../core/startView.js";
3
+ import { SceneError } from "./errors.js";
4
+ /**
5
+ * Checks the shape of a camera target (what `setCamera` takes) and turns it into the request the scene camera runs; a malformed one throws `bad-camera` leading with `call`.
6
+ * It does not look at the scene: which ids exist is the caller's check. A look-out target without a direction takes the one `now` looks along while looking out, else right ascension 0, declination 0;
7
+ * with `keepDirection` it is left out of the request instead, and the camera keeps its own when the request runs (a story panel's camera, decided as it opens).
8
+ */
9
+ export function cameraRequestOf(target, call, now, keepDirection = false) {
10
+ const bad = (why) => new SceneError("bad-camera", `${call}: ${why}; give { follow: id }, { focus: id }, { lookOut: id, direction?, fovDeg? } or a pose from camera`);
11
+ if (typeof target !== "object" || target === null || Array.isArray(target))
12
+ throw bad(`${String(target)} is not an object`);
13
+ const record = target;
14
+ if ("lookOut" in record)
15
+ return lookOutOf(record, now, keepDirection, bad);
16
+ // A pose names its object with `focus` too; its angle and distance fields tell it from `{ focus: id }`.
17
+ const isPose = ["azimuthDeg", "elevationDeg", "distance"].some((key) => key in record) || !("follow" in record || "focus" in record);
18
+ const named = ["follow", "focus"].filter((key) => key in record);
19
+ if (isPose) {
20
+ try {
21
+ return { kind: "pose", view: validateStartView(record, "pose") };
22
+ }
23
+ catch (cause) {
24
+ throw bad(cause instanceof Error ? cause.message : "a malformed pose");
25
+ }
26
+ }
27
+ const id = record[named[0]];
28
+ if (named.length > 1 || Object.keys(record).length > 1 || typeof id !== "string" || id === "")
29
+ throw bad("the target must be exactly one of follow or focus, naming a non-empty id");
30
+ return { kind: named[0], target: id };
31
+ }
32
+ /**
33
+ * Checks the ids a camera request names against what the viewer can turn toward: each body or object must be one of `shown` (the objects the view named by `view` shows),
34
+ * and a look-out direction id one of those or of `figures` (the scene's sky figures). Throws `bad-camera` leading with `call`. `setCamera` runs it as it is called; the opening look-out runs `checkToward` when the scene is built.
35
+ */
36
+ export function checkCameraIds(request, call, shown, figures, view = "the showing view") {
37
+ const { bodies, toward } = cameraIdsOf(request);
38
+ for (const id of bodies)
39
+ if (!shown.includes(id))
40
+ throw new SceneError("bad-camera", `${call}: "${id}" is not an object ${view} shows (${shown.join(", ")})`);
41
+ if (toward !== undefined)
42
+ checkToward(toward, call, shown, figures, view);
43
+ }
44
+ /** The look-out direction id half of `checkCameraIds`: `toward` must be an object `view` shows or a sky figure, else `bad-camera` naming it. */
45
+ export function checkToward(toward, call, shown, figures, view = "the showing view") {
46
+ if (!shown.includes(toward) && !figures.includes(toward))
47
+ throw new SceneError("bad-camera", `${call}: "${toward}" is neither an object ${view} shows (${shown.join(", ")}) nor a sky figure the viewer draws (${figures.join(", ") || "none added"})`);
48
+ }
49
+ /** A look-out target or a sky pose: the body, a direction (`direction`, or `raDeg` and `decDeg` together), and a field of view. */
50
+ function lookOutOf(record, now, keepDirection, bad) {
51
+ const body = record.lookOut;
52
+ if (typeof body !== "string" || body === "")
53
+ throw bad("lookOut must name a non-empty body id");
54
+ for (const key of Object.keys(record))
55
+ if (!["lookOut", "direction", "fovDeg", "raDeg", "decDeg"].includes(key))
56
+ throw bad(`${key} is not a look-out field`);
57
+ try {
58
+ const fovDeg = record.fovDeg === undefined ? undefined : validateSkyFov(record.fovDeg, "lookOut");
59
+ const direction = lookDirection(record, body, now, keepDirection, bad);
60
+ return { kind: "lookOut", body, ...(direction === undefined ? {} : { direction }), ...(fovDeg === undefined ? {} : { fovDeg }) };
61
+ }
62
+ catch (cause) {
63
+ throw cause instanceof RangeError ? bad(cause.message) : cause;
64
+ }
65
+ }
66
+ /** The look direction a look-out target names: `raDeg` and `decDeg` together (a sky pose), `direction` as a position or an object id, else the one already looked along (else right ascension 0, declination 0). Throws a `bad-camera` SceneError (or a RangeError from the range checks, which the caller turns into one). */
67
+ function lookDirection(record, body, now, keepDirection, bad) {
68
+ const flat = "raDeg" in record || "decDeg" in record;
69
+ const given = record.direction;
70
+ if (flat && given !== undefined)
71
+ throw bad("give direction or raDeg and decDeg, not both");
72
+ if (flat)
73
+ return pointOf(record.raDeg, record.decDeg, "lookOut");
74
+ if (typeof given === "string") {
75
+ if (given === "" || given === body)
76
+ throw bad("direction must name an object other than the body looked out from");
77
+ return given;
78
+ }
79
+ if (given === undefined && keepDirection)
80
+ return undefined;
81
+ if (given === undefined)
82
+ return now !== undefined && "lookOut" in now ? pointOf(now.raDeg, now.decDeg, "lookOut") : pointOf(0, 0, "lookOut");
83
+ const position = validateSkyPosition(given, "direction");
84
+ return eqjUnitVector(position.raDeg, position.decDeg);
85
+ }
86
+ const pointOf = (raDeg, decDeg, where) => {
87
+ const checked = validateSkyDirection(raDeg, decDeg, where);
88
+ return eqjUnitVector(checked.raDeg, checked.decDeg);
89
+ };