astraeus 0.1.1 → 0.2.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 (77) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +39 -6
  3. package/package.json +9 -6
  4. package/src/api/AstraeusScene.d.ts +27 -0
  5. package/src/api/AstraeusScene.js +38 -0
  6. package/src/api/activity.d.ts +50 -0
  7. package/src/api/activity.js +62 -0
  8. package/src/api/bodies.d.ts +24 -0
  9. package/src/api/bodies.js +24 -0
  10. package/src/api/errors.d.ts +1 -1
  11. package/src/api/group.d.ts +83 -0
  12. package/src/api/group.js +121 -0
  13. package/src/api/index.d.ts +5 -1
  14. package/src/api/index.js +2 -1
  15. package/src/api/mount.d.ts +10 -1
  16. package/src/api/mount.js +12 -3
  17. package/src/api/prepared.d.ts +10 -0
  18. package/src/api/prepared.js +5 -0
  19. package/src/api/scene.d.ts +121 -8
  20. package/src/api/scene.js +464 -57
  21. package/src/api/story.d.ts +63 -0
  22. package/src/api/story.js +52 -0
  23. package/src/api/sunOrbit.d.ts +14 -0
  24. package/src/api/sunOrbit.js +61 -0
  25. package/src/api/switches.d.ts +14 -0
  26. package/src/api/switches.js +19 -0
  27. package/src/api/time.d.ts +4 -0
  28. package/src/api/time.js +8 -0
  29. package/src/app/App.js +35 -17
  30. package/src/app/AstraeusScene.d.ts +1 -1
  31. package/src/app/DebugOverlay.d.ts +3 -52
  32. package/src/app/DebugOverlay.js +2 -29
  33. package/src/app/PanelLoadBoundary.d.ts +18 -0
  34. package/src/app/PanelLoadBoundary.js +17 -0
  35. package/src/app/debugReadout.d.ts +53 -0
  36. package/src/app/debugReadout.js +30 -0
  37. package/src/app/developerPanels.d.ts +6 -0
  38. package/src/app/developerPanels.js +11 -0
  39. package/src/app/displaySwitches.d.ts +54 -0
  40. package/src/app/displaySwitches.js +48 -0
  41. package/src/app/experienceDefinition.d.ts +5 -1
  42. package/src/app/listSwitch.d.ts +16 -0
  43. package/src/{experiences/showers/showerChoice.js → app/listSwitch.js} +1 -9
  44. package/src/app/metricReadouts.d.ts +1 -1
  45. package/src/app/metricReadouts.js +1 -1
  46. package/src/app/openClock.d.ts +7 -0
  47. package/src/app/openClock.js +14 -0
  48. package/src/app/sceneContentsHooks.d.ts +3 -3
  49. package/src/app/sceneDebug.d.ts +1 -1
  50. package/src/app/sceneDebug.js +1 -1
  51. package/src/app/skyModel.js +2 -0
  52. package/src/app/trackedMetrics.d.ts +53 -0
  53. package/src/{experiences/apollo11/spacecraftMetrics.js → app/trackedMetrics.js} +40 -56
  54. package/src/assets/licence.d.ts +1 -0
  55. package/src/core/bodies/index.d.ts +3 -0
  56. package/src/core/bodies/index.js +3 -1
  57. package/src/core/planetSeries.d.ts +2 -0
  58. package/src/core/planetSeries.js +4 -0
  59. package/src/core/provenance.d.ts +2 -1
  60. package/src/core/scalePolicy.d.ts +3 -0
  61. package/src/core/scalePolicy.js +2 -0
  62. package/src/core/state.d.ts +1 -0
  63. package/src/shell/AstraeusShell.d.ts +4 -1
  64. package/src/shell/AstraeusShell.js +7 -3
  65. package/src/shell/DisplaySwitches.d.ts +16 -0
  66. package/src/shell/DisplaySwitches.js +31 -0
  67. package/src/shell/TimelineBar.css +4 -0
  68. package/src/shell/TopBar.css +20 -0
  69. package/src/shell/TopBar.d.ts +4 -1
  70. package/src/shell/TopBar.js +3 -2
  71. package/src/shell/experience.d.ts +2 -0
  72. package/src/shell/phone.css +3 -0
  73. package/src/shell/topBarIcons.d.ts +1 -0
  74. package/src/shell/topBarIcons.js +1 -0
  75. package/src/synthetic/syntheticDefinition.js +3 -3
  76. package/src/experiences/apollo11/spacecraftMetrics.d.ts +0 -34
  77. package/src/experiences/showers/showerChoice.d.ts +0 -25
package/CHANGELOG.md CHANGED
@@ -2,6 +2,29 @@
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.2.0
6
+
7
+ The story layer: a scene can now carry your own bodies from orbit elements, orbit lines for any body circling the Sun, timed events, story panels, groups of many objects, an activity curve, display switches and a looping timeline, through `mount` or the new React component `AstraeusScene`. Every public name is documented at <https://astraeus.anipatke.com/api/>. Two changes can affect a 0.1 app: React, react-dom, `@react-three/fiber` and three are now peer dependencies (React 19 needed), and camera preset ids are now `focus-<id>` and `follow-<id>` (both below).
8
+
9
+ - Lighter first download (O-043), no API change. The Developer drawer's panels (settings, debug readout, frame-rate graph) are a separate file loaded only when the Developer switch is turned on: on the packed example the code loaded on first open went from 1,603,283 to 1,589,850 bytes (458,257 to 454,211 gzip). If that file cannot be fetched (offline, or a tab left open across a redeploy), the drawer says so and asks for a reload; the rest of the viewer keeps working.
10
+
11
+ - Gaps found rebuilding a shower (O-042 T-177), no existing call changes. A Sun-centred scene with an enlarged body (`addBody(x, { enlarge })`) now offers the viewer's "solar-system" scale (true distances, the named bodies enlarged) as its second scale choice in place of the readable scale, which does not enlarge; scenes without enlargement are unchanged. A Sun-centred scene with planets (orbit lines, or a group clumped near a planet) now works through `mount`, `AstraeusScene` and `prepareScene` without the caller loading the planet series: the lines and clumped groups are drawn once `prepare` has loaded them. `addGroup`'s `clump.near` accepts a body added with `addBodyFromElements`, and `addGroup` takes `refillSliceMs` (0 or more; `bad-group` otherwise).
12
+
13
+ - Activity, looping and view settings (O-042), no existing call changes. New `Scene.addActivity({ id, label, unit, start, end, samples, peak?, provenance?, ... })` gives the timeline a rate curve (the glow) with its peak and the source of each stretch; a group takes `readouts: [{ kind: "rate" }]` for a live rate bar on its card (unavailable outside the activity). `setTimeline` takes `loop: true`; `camera.follow` and `camera.lookAt` take `up: "ecliptic"`; new `camera.setReach(distance)` sets how far the viewer can zoom out (labels reach as far). New `SceneError` codes `bad-activity` and `bad-camera`; a rate readout naming no activity is `bad-readout`. New exported types `ActivityInput`, `ActivitySampleInput`, `ActivitySourceInput` and `GroupReadoutInput`.
14
+
15
+ - Sun-centred scenes (O-042), no existing call changes. `addBody(x, { orbit: true })` now also draws one full turn round the Sun of any body that circles it when `sun` is in the scene (planets, Earth's year; was `no-orbit` for all but the Moon and Io). New `Scene.addBodyFromElements(record, options?)` adds your own body from published orbit elements with their source and accuracy (`bad-element` names the bad field); `addBody` takes `enlarge` (planet drawn that many times larger in the readable scale; `bad-body` below 1) and `showLabel: false` (label starts off). A scene whose first body is the Sun sets no label reach, so labels do not fade when zoomed out, and refuses `addTrajectory` at `toDefinition` with `bad-trajectory`. New exported type `ElementsBodyRecord`.
16
+
17
+ - Groups of dots (O-042), no existing call changes. New `Scene.addGroup({ id, orbits, ... })` draws a list of orbits (each with its own id, shape and tilt) as one group of dots: one colour (`color`), dot size (`dotSizePx`), menu item, info card, provenance and known limits. The dots are placed along their orbits by an even spread shuffled by `seed`, optionally with a share clumped near a body (`clump: { near, fraction, widthDeg }`); `refillAfterMs` sets how often the dots are placed again. The group's id joins the camera menu (`focus-<id>`, `follow-<id>`) and can be named by a story panel's `object`. New `SceneError` code `bad-group` (empty list, bad or unbound orbit, bad colour or clump, a centre or clump body not in the scene); a repeated id is `duplicate-id`. New exported types `GroupInput`, `GroupOrbitInput` and `GroupClumpInput`. `examples/hello-scene` draws a made-up ring of 40 dots.
18
+
19
+ - Display switches (O-041), no existing call changes. New `Scene.setSwitches({ orbitLines?, labels?, milkyWay? })` places each switch on the top bar, in one switch panel opened from the bar, or only in the Developer drawer, and sets whether it starts on; a bad name, place or `on` throws `bad-switch`. Each placed switch drives the same state as its Developer-drawer buttons. New exported type `SwitchesInput`. With nothing placed the bar is unchanged. `examples/hello-scene` places two.
20
+
21
+ - Story calls (O-041). One visible change to existing behaviour: camera preset ids are now `focus-<id>` and `follow-<id>`, and the camera menu is built automatically, with a Focus and a Follow entry for every body and path; the Sky item is no longer listed in any object menu. `addTrajectory` takes `description`, `knownLimitations`, `anchors` (labelled dots where the data was published; a time outside the path throws `bad-anchor`) and `readouts` (info-card bars: `range`, `speed`, `distance`, `altitude`); `addBody` takes `description`, `color` (a hex colour for the info card and label) and `knownLimitations` (a list of non-empty texts shown with the provenance); a bad `color` or `knownLimitations` throws `bad-body`. New `Scene` methods: `addEvents` (timed events with optional `provenance`; `bad-event`), `addStoryPanels` (panels at a time, event or anchor; `bad-panels`), `setTimeline` (span, speeds, opening speed, or `{ none: true }` for no timeline; `bad-timeline`), `stateOf` (state of a path at a moment) and `camera.lookAt` (opening view without following). `setScale` takes `{ only: true }` to offer one scale. `examples/hello-scene` now uses all of them.
22
+
23
+ - An API reference page is published at <https://astraeus.anipatke.com/api/>, generated from the public types and doc comments; the package `homepage` points at it. Every export now has a doc comment (a test keeps it so). No change to the API.
24
+
25
+ - New export `AstraeusScene` (with its props type `AstraeusSceneProps`): a React component that draws the same viewer as `mount`, `<AstraeusScene scene={scene} data={[...]} onReady onError />`. It rebuilds when the `scene` prop changes and cleans up on unmount.
26
+ - Needs React 19 and `@react-three/fiber` 9.8.2 or later: `react`, `react-dom`, `@react-three/fiber` and `three` are now peer dependencies, not dependencies, so the host app's own copies are used and installed once. Install them beside `astraeus`. No change to the public API.
27
+
5
28
  ## 0.1.1
6
29
 
7
30
  No changes to the code, data or public API. The first version published by the GitHub release workflow, with npm provenance ("Built and signed on GitHub Actions").
package/README.md CHANGED
@@ -2,14 +2,16 @@
2
2
 
3
3
  A 3D solar system for the browser. Place bodies and recorded paths in a scene, mount it, and get time controls, camera, scale choice and body information, with no React and no 3D code of your own.
4
4
 
5
- > **0.1 preview.** The public API below is the promise: it is small on purpose and may still change between `0.x` versions, with every change listed in [CHANGELOG.md](./CHANGELOG.md). Anything not exported from `astraeus` is internal and may change or disappear in any release.
5
+ > **0.2 preview.** The public API below is the promise: it is small on purpose and may still change between `0.x` versions, with every change listed in [CHANGELOG.md](./CHANGELOG.md). Anything not exported from `astraeus` is internal and may change or disappear in any release.
6
6
 
7
7
  ## Install
8
8
 
9
9
  ```sh
10
- npm install astraeus
10
+ npm install astraeus react react-dom @react-three/fiber three
11
11
  ```
12
12
 
13
+ `react` (19), `react-dom` (19), `@react-three/fiber` (9.8.2 or later 9.x) and `three` (0.169 or later) are peer dependencies: your app's own copies are used, so install them beside `astraeus` (npm 7 and later installs missing peers for you).
14
+
13
15
  You need a bundler. These were each built and run with the packed packages (a scene with Saturn and Titan from `astraeus-data-saturn`): Vite 8, webpack 5 (5.112) and Parcel 2 (2.16, which needs `"@parcel/resolver-default": { "packageExports": true }` in your `package.json` so it reads the package `exports`). Others are untried. The package is plain ES modules that reference their pictures with `new URL(..., import.meta.url)`; loading it straight in Node or from a bare `<script type="module">` will not work.
14
16
 
15
17
  ## A scene in about 20 lines
@@ -34,23 +36,54 @@ scene.camera.follow("probe", { distance: 110 });
34
36
  mount(document.getElementById("app"), scene);
35
37
  ```
36
38
 
37
- The element needs a size (for example `height: 100%` all the way up). The probe's circle and the Moon's own orbit (tilted to it, because the circle lies in the reference frame's x-y plane) are both drawn. The finished app is in the repository at `examples/hello-scene`.
39
+ The element needs a size (for example `height: 100%` all the way up). The probe's circle and the Moon's own orbit (tilted to it, because the circle lies in the reference frame's x-y plane) are both drawn. The finished app, grown into a small made-up story with every call below, is in the repository at `examples/hello-scene`.
38
40
 
39
41
  ## The public API
40
42
 
43
+ The full reference, generated from the types and doc comments, is at <https://astraeus.anipatke.com/api/>. The table below is the short form.
44
+
41
45
  | Call | What it does |
42
46
  |---|---|
43
47
  | `new Scene()` | An empty scene. Every method below returns the scene, so calls chain. |
44
- | `scene.addBody(body, { orbit? })` | Adds a catalogued body: a ready-made one (`sun`, `mercury`, `venus`, `earth`, `moon`, `mars`, `jupiter`, `saturn`, `uranus`, `neptune`, `pluto`, and the moons `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`, `phobos`, `deimos`) or its id. The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line about its parent (the parent must be in the scene); in 0.1 only `moon` (about Earth) and `io` (about Jupiter) have one, others throw `no-orbit`. |
45
- | `scene.addTrajectory({ id, label?, color?, center?, samples })` | A recorded path. Each sample is `{ time, positionKm, velocityKmS? }` measured from `center` (default `"earth"`); `time` is ISO text, a `Date` or Unix milliseconds. Instead of `samples` you may give `provider` (an object with `stateAt(timeUtcMs)`) and `bounds: { start, end }`. |
48
+ | `scene.addBody(body, { orbit?, enlarge?, showLabel?, description?, color?, knownLimitations? })` | Adds a catalogued body: a ready-made one (`sun`, `mercury`, `venus`, `earth`, `moon`, `mars`, `jupiter`, `saturn`, `uranus`, `neptune`, `pluto`, and the moons `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`, `phobos`, `deimos`) or its id. The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line: `moon` about Earth and `io` about Jupiter (the parent must be in the scene), or, with `sun` in the scene, one full turn round the Sun of any body that circles it (the planets, Earth's year, a body from `addBodyFromElements`), from the opening time; anything else throws `no-orbit`. `enlarge` (a number of at least 1) draws the body that many times larger than life (in a Sun-centred scene the viewer then offers its "Solar system" scale, true distances with the named bodies enlarged, as the second scale in place of Readable); `showLabel: false` starts its label off. A scene whose first body is the Sun sets no label reach, so labels stay when zoomed out, and it cannot hold a tracked path (`addTrajectory`; `bad-trajectory`). `color` (a hex colour such as `"#9fd8ff"`) sets the colour on its info card and label; `knownLimitations` (a list of non-empty texts) replaces the catalogue's limits shown with its provenance; a bad value throws `bad-body`. |
49
+ | `scene.addTrajectory({ id, label?, color?, center?, samples, provenance?, description?, knownLimitations?, anchors?, readouts? })` | A recorded path. Each sample is `{ time, positionKm, velocityKmS? }` measured from `center` (default `"earth"`); `time` is ISO text, a `Date` or Unix milliseconds. Instead of `samples` you may give `provider` (an object with `stateAt(timeUtcMs)`) and `bounds: { start, end }`. `description` and `knownLimitations` (a list of sentences) go on its info card with `provenance`. `anchors: [{ id, time }]` draw labelled dots where the source published a point (the time must fall within the path). `readouts` are bars on the card, in order: `{ kind: "range", marker? }` (distance from the centre; `marker` names a body to mark), `{ kind: "speed" }`, `{ kind: "distance", to }` and `{ kind: "altitude", above }`; a named body must be in the scene. |
50
+ | `scene.addBodyFromElements(record, options?)` | Your own body that circles the Sun, from published orbit elements: `record` is `{ id, label, elements: { semiMajorAxisAu, eccentricity, inclinationDeg, ascendingNodeDeg, argumentOfPerihelionDeg, meanAnomalyDeg or perihelionJdTdb }, epoch: { jd, timeScale, ttMinusUtcSeconds? }, frame: "ecliptic-j2000", source: { name, url, solution, accessed }, radius?, accuracy: { classification, statement, validFromUtc, validToUtc, limitations }, marker?: { color, sizePx } }`. Drawn as a marker on unperturbed two-body motion about the Sun; the source, accuracy and limits show on its info card. `options` are `addBody`'s (`{ orbit: true }` draws its whole orbit from periapsis, smooth even for a sharp comet orbit). A bad record throws `bad-element` naming the field; a repeated id throws `duplicate-id`. |
51
+ | `scene.addGroup({ id, orbits, label?, center?, plane?, 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` (`"ecliptic-j2000"` default, or `"EQJ"`). 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 id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be a panel's `object`. A mistake throws `bad-group`. |
46
52
  | `scene.setTime(time)` | The moment the scene opens at. |
47
- | `scene.setScale(trueScale \| readableScale)` | The opening scale; the viewer can switch to the other. |
53
+ | `scene.setScale(trueScale \| readableScale, { only? })` | The opening scale; the viewer can switch to the other unless `{ only: true }` offers that scale alone. |
54
+ | `scene.addEvents(events, { provenance? })` | Timed events on the timeline: `[{ id, label, time, type? }]`, ids unique. `provenance` says where the times come from. May be called more than once. |
55
+ | `scene.addStoryPanels({ pauseSeconds?, autoOpen?, panels })` | Story panels that open as playback reaches them: `{ id, at: { utc } \| { event } \| { anchor }, title, body, details?, badge, sources, object? }`. `badge` is `observed`, `modelled` or `illustrative`; `sources` is never empty. A mistake throws `bad-panels` naming the panel and field. |
56
+ | `scene.setTimeline({ start, end, rates?, rate? })` | 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`. |
57
+ | `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 or a bad curve, peak or source throws `bad-activity`; a rate readout with no activity is `bad-readout`. |
58
+ | `scene.camera.setReach(distance)` | How far the viewer can zoom out, in Earth radii; labels reach as far. A bad value throws `bad-camera`. `camera.follow` and `camera.lookAt` 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. |
59
+ | `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). `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`. |
60
+ | `scene.stateOf(id, time)` | The state (position km, velocity km/s) of an added path at a moment, for figures a story quotes. |
48
61
  | `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. |
62
+ | `scene.camera.lookAt(id, { azimuthDeg?, elevationDeg?, distance? })` | The same opening view without following. The last of `follow` and `lookAt` wins. The viewer's camera menu gets a Focus and a Follow entry for every body and path. |
49
63
  | `mount(element, scene, { data? })` | Draws the scene with the full viewer. Returns `{ ready, unmount() }`. `data` is a list of data packages (below). |
64
+ | `<AstraeusScene scene data? onReady? onError? />` | The same viewer as a React component (below). |
50
65
  | `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. |
51
66
 
52
67
  Types (`State`, `Pictures`, `TextureRef`, `AssetLicence`, `DataSource`, `TrajectoryInput` and the like) are exported for TypeScript.
53
68
 
69
+ ## In a React app
70
+
71
+ `AstraeusScene` draws the same viewer as `mount`, as a component. It fills its parent, so give the parent a size:
72
+
73
+ ```jsx
74
+ import { Scene, earth, moon, AstraeusScene } from "astraeus";
75
+
76
+ const scene = new Scene().addBody(earth).addBody(moon, { orbit: true });
77
+
78
+ export const App = () => (
79
+ <div style={{ height: "100vh" }}>
80
+ <AstraeusScene scene={scene} data={[]} onReady={() => console.log("drawn")} onError={(error) => console.error(error)} />
81
+ </div>
82
+ );
83
+ ```
84
+
85
+ Props: `scene`, `data` (as for `mount`), `onReady`, `onError` (a bad scene or failed data load), `className` and `style` for the wrapper. Build the `Scene` once (outside the component or in `useMemo`): a new `Scene` object rebuilds the viewer. It needs React 19 and the peer dependencies (`react`, `react-dom`, `@react-three/fiber`, `three`). See `examples/hello-react` in the repository.
86
+
54
87
  ## What `astraeus-data` adds
55
88
 
56
89
  The engine alone draws the Sun, Earth, Moon and the eight planets with their pictures and positions for 2010 to 2030. Everything heavier is a separate, optional package you import and hand to `mount`, so you only download what you use. A moon-position package is thousands of small files; your build copies them as separate files and the page fetches only the ones for the time window on screen (each chunk URL ends `?no-inline`, so Vite does not paste them into your script):
package/package.json CHANGED
@@ -1,15 +1,17 @@
1
1
  {
2
2
  "name": "astraeus",
3
- "version": "0.1.1",
3
+ "version": "0.2.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",
7
7
  "dependencies": {
8
- "@lizard-isana/orb": "3.1.1",
9
- "@react-three/fiber": "^8.18.0",
10
- "react": "^18.3.1",
11
- "react-dom": "^18.3.1",
12
- "three": "^0.169.0"
8
+ "@lizard-isana/orb": "3.1.1"
9
+ },
10
+ "peerDependencies": {
11
+ "@react-three/fiber": ">=9.8.2 <10",
12
+ "react": ">=19 <19.4",
13
+ "react-dom": ">=19 <19.4",
14
+ "three": ">=0.169.0 <1"
13
15
  },
14
16
  "exports": {
15
17
  ".": {
@@ -21,6 +23,7 @@
21
23
  "sideEffects": [
22
24
  "**/*.css"
23
25
  ],
26
+ "homepage": "https://astraeus.anipatke.com/api/",
24
27
  "repository": {
25
28
  "type": "git",
26
29
  "url": "git+https://github.com/anipatke/Astraeus.git"
@@ -0,0 +1,27 @@
1
+ import { type CSSProperties, type ReactElement } from "react";
2
+ import "../app/style.css";
3
+ import type { DataSource, Scene } from "./scene.js";
4
+ /** Props of `AstraeusScene`. */
5
+ export interface AstraeusSceneProps {
6
+ /** The scene to draw. Passing a different `Scene` object rebuilds the viewer; changing the same object in place does not. */
7
+ readonly scene: Scene;
8
+ /** Data packages the scene's bodies need, such as moon pictures or positions. Read when the scene is built, so a new array alone does not rebuild. */
9
+ readonly data?: readonly DataSource[];
10
+ /** Called once the scene's data has loaded and it is drawn (again after each rebuild). */
11
+ readonly onReady?: () => void;
12
+ /** Called when the scene cannot be built (a `SceneError`) or its data fails to load. */
13
+ readonly onError?: (error: Error) => void;
14
+ /** Class for the wrapper element, which fills its parent's width and height unless `style` says otherwise. */
15
+ readonly className?: string;
16
+ /** Style for the wrapper element. */
17
+ readonly style?: CSSProperties;
18
+ }
19
+ /**
20
+ * 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.
21
+ * @example
22
+ * const scene = new Scene().addBody(earth).addBody(moon);
23
+ * export function App() {
24
+ * return <div style={{ height: "100vh" }}><AstraeusScene scene={scene} onError={console.error} /></div>;
25
+ * }
26
+ */
27
+ export declare function AstraeusScene({ scene, data, onReady, onError, className, style }: AstraeusSceneProps): ReactElement;
@@ -0,0 +1,38 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { useEffect, useRef, useState } from "react";
3
+ import "../app/style.css";
4
+ import { App } from "../app/App.js";
5
+ import { prepareScene } from "./prepared.js";
6
+ const FILL = { width: "100%", height: "100%" };
7
+ const asError = (cause) => (cause instanceof Error ? cause : new Error(String(cause)));
8
+ /**
9
+ * 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.
10
+ * @example
11
+ * const scene = new Scene().addBody(earth).addBody(moon);
12
+ * export function App() {
13
+ * return <div style={{ height: "100vh" }}><AstraeusScene scene={scene} onError={console.error} /></div>;
14
+ * }
15
+ */
16
+ export function AstraeusScene({ scene, data, onReady, onError, className, style }) {
17
+ const [definition, setDefinition] = useState();
18
+ // The latest data and callbacks, read when the scene is built, so a new array or arrow function each render does not rebuild it.
19
+ const latest = useRef({ data, onReady, onError });
20
+ latest.current = { data, onReady, onError };
21
+ useEffect(() => {
22
+ let open = true;
23
+ setDefinition(undefined);
24
+ try {
25
+ const prepared = prepareScene(scene, latest.current.data);
26
+ prepared.ready.then(() => { if (open) {
27
+ setDefinition(prepared.definition);
28
+ latest.current.onReady?.();
29
+ } }, (cause) => { if (open)
30
+ latest.current.onError?.(asError(cause)); });
31
+ }
32
+ catch (cause) {
33
+ latest.current.onError?.(asError(cause));
34
+ }
35
+ return () => { open = false; };
36
+ }, [scene]);
37
+ return _jsx("div", { className: className, style: { ...FILL, ...style }, children: definition ? _jsx(App, { definition: definition }) : null });
38
+ }
@@ -0,0 +1,50 @@
1
+ import { type Provenance } from "../core/provenance.js";
2
+ import { type TimelineWindow } from "../core/timeWindow.js";
3
+ import type { RateMetric } from "../shell/metrics.js";
4
+ import { type TimeInput } from "./time.js";
5
+ /** One point of an activity curve: a rate at a moment. Between points the rate is a straight line. */
6
+ export interface ActivitySampleInput {
7
+ readonly time: TimeInput;
8
+ /** How many per unit of time, never negative. */
9
+ readonly value: number;
10
+ }
11
+ /** Where a stretch of the curve comes from; stretches are sorted, do not overlap and lie inside the activity. */
12
+ export interface ActivitySourceInput {
13
+ readonly start: TimeInput;
14
+ readonly end: TimeInput;
15
+ readonly provenance: Provenance;
16
+ }
17
+ /**
18
+ * A period of activity on the timeline: a rate curve (the timeline glows brighter where the rate is higher) with an optional peak, and where each stretch of the curve comes from.
19
+ * The id is unique among the scene's activities and is what a group's `{ kind: "rate" }` readout can name.
20
+ */
21
+ export interface ActivityInput {
22
+ readonly id: string;
23
+ /** Name shown on the timeline and with the rate bar. */
24
+ readonly label: string;
25
+ /** What the rate counts, per unit of time, such as "meteors per hour". */
26
+ readonly unit: string;
27
+ /** The first and last moment of the activity. The curve's samples lie inside it, and the rate is unavailable outside it. */
28
+ readonly start: TimeInput;
29
+ readonly end: TimeInput;
30
+ /** The moment of the peak, marked on the timeline; inside the activity. */
31
+ readonly peak?: TimeInput;
32
+ /** At least two points, sorted by time, one per moment. */
33
+ readonly samples: readonly ActivitySampleInput[];
34
+ /** Where each stretch of the curve comes from, shown with the activity. Absent: no source is stated. */
35
+ readonly provenance?: readonly ActivitySourceInput[];
36
+ /** A free word the timeline may group by, such as "meteor-shower". */
37
+ readonly type?: string;
38
+ /** Name of the peak mark on the rate bar; "Peak" when absent. */
39
+ readonly peakLabel?: string;
40
+ }
41
+ /** A validated activity: the engine's window, and the peak the rate bar compares with. */
42
+ export interface PlannedActivity {
43
+ readonly window: TimelineWindow;
44
+ readonly peakValue: number;
45
+ readonly peakLabel: string;
46
+ }
47
+ /** Checks an activity and builds its window; any fault is a `bad-activity` naming the activity. */
48
+ export declare function planActivity(input: ActivityInput): PlannedActivity;
49
+ /** The live rate bar of an activity at a moment: the rate (unavailable outside the activity) against its peak. */
50
+ export declare function rateMetricOf(groupId: string, activity: PlannedActivity, timeUtcMs: number): RateMetric;
@@ -0,0 +1,62 @@
1
+ import { createProvenance } from "../core/provenance.js";
2
+ import { createWindows, rateAt } from "../core/timeWindow.js";
3
+ import { SceneError } from "./errors.js";
4
+ import { toUtcMs } from "./time.js";
5
+ const bad = (id, message) => new SceneError("bad-activity", `addActivity("${String(id)}"): ${message}`);
6
+ const isText = (value) => typeof value === "string" && value !== "";
7
+ /** Checks the plain fields and returns the id. */
8
+ function checkFields(input) {
9
+ const id = input?.id;
10
+ if (!isText(id))
11
+ throw bad(id, "the activity needs a non-empty id");
12
+ if (!isText(input.label))
13
+ throw bad(id, "the activity needs a non-empty label");
14
+ if (!isText(input.unit))
15
+ throw bad(id, "the activity needs a unit such as \"meteors per hour\"");
16
+ if (!Array.isArray(input.samples) || input.samples.length < 2)
17
+ throw bad(id, "the curve needs at least two samples");
18
+ if (input.peakLabel !== undefined && !isText(input.peakLabel))
19
+ throw bad(id, "peakLabel must be a non-empty text");
20
+ return id;
21
+ }
22
+ /** Checks an activity and builds its window; any fault is a `bad-activity` naming the activity. */
23
+ export function planActivity(input) {
24
+ const id = checkFields(input);
25
+ const moment = (time, what) => toUtcMs(time, `addActivity("${id}") ${what}`);
26
+ const samples = input.samples.map((sample, index) => ({ timeUtcMs: moment(sample?.time, `sample ${index} time`), value: sample?.value }));
27
+ try {
28
+ const peakUtcMs = input.peak === undefined ? undefined : moment(input.peak, "peak");
29
+ const [window] = createWindows([{
30
+ id,
31
+ label: input.label,
32
+ ...(input.type === undefined ? {} : { type: input.type }),
33
+ startUtcMs: moment(input.start, "start"),
34
+ endUtcMs: moment(input.end, "end"),
35
+ ...(peakUtcMs === undefined ? {} : { peakUtcMs }),
36
+ rate: { unit: input.unit, samples },
37
+ ...(input.provenance === undefined ? {} : { provenance: input.provenance.map((span, index) => ({ startUtcMs: moment(span?.start, `provenance ${index} start`), endUtcMs: moment(span?.end, `provenance ${index} end`), provenance: createProvenance(span?.provenance) })) }),
38
+ }]);
39
+ const atPeak = peakUtcMs === undefined ? null : rateAt(window, peakUtcMs);
40
+ return { window: window, peakValue: atPeak ?? Math.max(...samples.map((sample) => sample.value)), peakLabel: input.peakLabel ?? "Peak" };
41
+ }
42
+ catch (error) {
43
+ if (error instanceof SceneError)
44
+ throw error;
45
+ throw bad(id, error instanceof Error ? error.message : String(error));
46
+ }
47
+ }
48
+ /** The live rate bar of an activity at a moment: the rate (unavailable outside the activity) against its peak. */
49
+ export function rateMetricOf(groupId, activity, timeUtcMs) {
50
+ const { window } = activity;
51
+ return {
52
+ kind: "rate",
53
+ id: `${groupId}-rate`,
54
+ label: "Activity rate",
55
+ value: rateAt(window, timeUtcMs),
56
+ unit: window.rate?.unit ?? "",
57
+ digits: activity.peakValue >= 10 ? 0 : 1,
58
+ context: window.label,
59
+ unavailable: "outside the activity",
60
+ peak: { label: activity.peakLabel, value: activity.peakValue },
61
+ };
62
+ }
@@ -7,34 +7,58 @@ export interface BodyRef {
7
7
  }
8
8
  /** Ready-made bodies for `addBody`; the Sun, Earth, Moon and planets have their positions and pictures in the engine. */
9
9
  export declare const sun: BodyRef;
10
+ /** Mercury. */
10
11
  export declare const mercury: BodyRef;
12
+ /** Venus. */
11
13
  export declare const venus: BodyRef;
14
+ /** Earth. */
12
15
  export declare const earth: BodyRef;
16
+ /** Moon. */
13
17
  export declare const moon: BodyRef;
18
+ /** Mars. */
14
19
  export declare const mars: BodyRef;
20
+ /** Jupiter. */
15
21
  export declare const jupiter: BodyRef;
22
+ /** Saturn. */
16
23
  export declare const saturn: BodyRef;
24
+ /** Uranus. */
17
25
  export declare const uranus: BodyRef;
26
+ /** Neptune. */
18
27
  export declare const neptune: BodyRef;
28
+ /** Pluto. */
19
29
  export declare const pluto: BodyRef;
20
30
  /**
21
31
  * Moons need their planet's positions package (`astraeus-data-<planet>`, 120 MB of fits in all, split per planet) passed to `mount`; their maps come from
22
32
  * `astraeus-data` when it is passed too, and without it they are plain coloured spheres. They are not offered without the positions.
23
33
  */
24
34
  export declare const io: BodyRef;
35
+ /** Europa (needs `astraeus-data-jupiter`). */
25
36
  export declare const europa: BodyRef;
37
+ /** Ganymede (needs `astraeus-data-jupiter`). */
26
38
  export declare const ganymede: BodyRef;
39
+ /** Callisto (needs `astraeus-data-jupiter`). */
27
40
  export declare const callisto: BodyRef;
41
+ /** Mimas (needs `astraeus-data-saturn`). */
28
42
  export declare const mimas: BodyRef;
43
+ /** Enceladus (needs `astraeus-data-saturn`). */
29
44
  export declare const enceladus: BodyRef;
45
+ /** Tethys (needs `astraeus-data-saturn`). */
30
46
  export declare const tethys: BodyRef;
47
+ /** Dione (needs `astraeus-data-saturn`). */
31
48
  export declare const dione: BodyRef;
49
+ /** Rhea (needs `astraeus-data-saturn`). */
32
50
  export declare const rhea: BodyRef;
51
+ /** Titan (needs `astraeus-data-saturn`). */
33
52
  export declare const titan: BodyRef;
53
+ /** Iapetus (needs `astraeus-data-saturn`). */
34
54
  export declare const iapetus: BodyRef;
55
+ /** Triton (needs `astraeus-data-neptune`). */
35
56
  export declare const triton: BodyRef;
57
+ /** Charon (needs `astraeus-data-pluto`). */
36
58
  export declare const charon: BodyRef;
59
+ /** Phobos (needs `astraeus-data-mars`). */
37
60
  export declare const phobos: BodyRef;
61
+ /** Deimos (needs `astraeus-data-mars`). */
38
62
  export declare const deimos: BodyRef;
39
63
  /** The ready-made reference for a catalogued id, so `addBody("titan")` knows Titan needs `astraeus-data-saturn`. */
40
64
  export declare const readyMade: (id: BodyId) => BodyRef | undefined;
package/src/api/bodies.js CHANGED
@@ -1,34 +1,58 @@
1
1
  const ref = (id, label, requires) => Object.freeze({ id, label, ...(requires === undefined ? {} : { requires }) });
2
2
  /** Ready-made bodies for `addBody`; the Sun, Earth, Moon and planets have their positions and pictures in the engine. */
3
3
  export const sun = ref("sun", "Sun");
4
+ /** Mercury. */
4
5
  export const mercury = ref("mercury", "Mercury");
6
+ /** Venus. */
5
7
  export const venus = ref("venus", "Venus");
8
+ /** Earth. */
6
9
  export const earth = ref("earth", "Earth");
10
+ /** Moon. */
7
11
  export const moon = ref("moon", "Moon");
12
+ /** Mars. */
8
13
  export const mars = ref("mars", "Mars");
14
+ /** Jupiter. */
9
15
  export const jupiter = ref("jupiter", "Jupiter");
16
+ /** Saturn. */
10
17
  export const saturn = ref("saturn", "Saturn");
18
+ /** Uranus. */
11
19
  export const uranus = ref("uranus", "Uranus");
20
+ /** Neptune. */
12
21
  export const neptune = ref("neptune", "Neptune");
22
+ /** Pluto. */
13
23
  export const pluto = ref("pluto", "Pluto");
14
24
  /**
15
25
  * Moons need their planet's positions package (`astraeus-data-<planet>`, 120 MB of fits in all, split per planet) passed to `mount`; their maps come from
16
26
  * `astraeus-data` when it is passed too, and without it they are plain coloured spheres. They are not offered without the positions.
17
27
  */
18
28
  export const io = ref("io", "Io", "astraeus-data-jupiter");
29
+ /** Europa (needs `astraeus-data-jupiter`). */
19
30
  export const europa = ref("europa", "Europa", "astraeus-data-jupiter");
31
+ /** Ganymede (needs `astraeus-data-jupiter`). */
20
32
  export const ganymede = ref("ganymede", "Ganymede", "astraeus-data-jupiter");
33
+ /** Callisto (needs `astraeus-data-jupiter`). */
21
34
  export const callisto = ref("callisto", "Callisto", "astraeus-data-jupiter");
35
+ /** Mimas (needs `astraeus-data-saturn`). */
22
36
  export const mimas = ref("mimas", "Mimas", "astraeus-data-saturn");
37
+ /** Enceladus (needs `astraeus-data-saturn`). */
23
38
  export const enceladus = ref("enceladus", "Enceladus", "astraeus-data-saturn");
39
+ /** Tethys (needs `astraeus-data-saturn`). */
24
40
  export const tethys = ref("tethys", "Tethys", "astraeus-data-saturn");
41
+ /** Dione (needs `astraeus-data-saturn`). */
25
42
  export const dione = ref("dione", "Dione", "astraeus-data-saturn");
43
+ /** Rhea (needs `astraeus-data-saturn`). */
26
44
  export const rhea = ref("rhea", "Rhea", "astraeus-data-saturn");
45
+ /** Titan (needs `astraeus-data-saturn`). */
27
46
  export const titan = ref("titan", "Titan", "astraeus-data-saturn");
47
+ /** Iapetus (needs `astraeus-data-saturn`). */
28
48
  export const iapetus = ref("iapetus", "Iapetus", "astraeus-data-saturn");
49
+ /** Triton (needs `astraeus-data-neptune`). */
29
50
  export const triton = ref("triton", "Triton", "astraeus-data-neptune");
51
+ /** Charon (needs `astraeus-data-pluto`). */
30
52
  export const charon = ref("charon", "Charon", "astraeus-data-pluto");
53
+ /** Phobos (needs `astraeus-data-mars`). */
31
54
  export const phobos = ref("phobos", "Phobos", "astraeus-data-mars");
55
+ /** Deimos (needs `astraeus-data-mars`). */
32
56
  export const deimos = ref("deimos", "Deimos", "astraeus-data-mars");
33
57
  const READY_MADE = [sun, mercury, venus, earth, moon, mars, jupiter, saturn, uranus, neptune, pluto, io, europa, ganymede, callisto, mimas, enceladus, tethys, dione, rhea, titan, iapetus, triton, charon, phobos, deimos];
34
58
  /** The ready-made reference for a catalogued id, so `addBody("titan")` knows Titan needs `astraeus-data-saturn`. */
@@ -1,5 +1,5 @@
1
1
  /** Why a scene call was refused; `code` is stable so a caller can branch on it. */
2
- export type SceneErrorCode = "unknown-body" | "duplicate-id" | "bad-time" | "bad-trajectory" | "bad-scale" | "missing-data" | "empty-scene" | "bad-element" | "no-orbit";
2
+ export type SceneErrorCode = "unknown-body" | "duplicate-id" | "bad-time" | "bad-trajectory" | "bad-scale" | "missing-data" | "empty-scene" | "bad-element" | "no-orbit" | "bad-anchor" | "bad-readout" | "bad-event" | "bad-panels" | "bad-timeline" | "bad-switch" | "bad-body" | "bad-group" | "bad-activity" | "bad-camera";
3
3
  /** The one error the public API throws for bad input; the message names the offending value. */
4
4
  export declare class SceneError extends RangeError {
5
5
  readonly code: SceneErrorCode;
@@ -0,0 +1,83 @@
1
+ import type { BodyId } from "../core/body.js";
2
+ import { type Provenance } from "../core/provenance.js";
3
+ import type { TimeBounds } from "../core/trajectory.js";
4
+ import { type BodyCatalogue } from "../assets/catalogue.js";
5
+ import type { GroupLayer } from "../app/experienceDefinition.js";
6
+ import { type TimeInput } from "./time.js";
7
+ /** One listed orbit of a group: its own id (the record it came from) and its shape and orientation. Angles in degrees, length in km. The orbit carries no position along itself; the group chooses that. */
8
+ export interface GroupOrbitInput {
9
+ /** The orbit's own id, such as the record it was listed under; distinct within the group. */
10
+ readonly id: string;
11
+ readonly semiMajorAxisKm: number;
12
+ /** At least 0 and below 1: a bound orbit. */
13
+ readonly eccentricity: number;
14
+ readonly inclinationDeg: number;
15
+ readonly raanDeg: number;
16
+ readonly argumentOfPeriapsisDeg: number;
17
+ /** The moment the record was measured, kept with the record; it does not place the dot. Defaults to the group's reference time. */
18
+ readonly time?: TimeInput;
19
+ }
20
+ /** A stated share of the dots drawn near a body's position along its orbit: a model, not a measurement. */
21
+ export interface GroupClumpInput {
22
+ /** A body in the scene to clump near: a catalogued body or one added with `addBodyFromElements` (add it before the group). Only where it is along its orbit about the group's centre at the reference time is used. */
23
+ readonly near: BodyId;
24
+ /** Share of the dots, 0 to 1. */
25
+ readonly fraction: number;
26
+ /** Half-width of the clump in degrees along the orbit, above 0 and at most 180. */
27
+ readonly widthDeg: number;
28
+ }
29
+ /** A bar on a group's info card: `rate` is the live rate of an activity (`addActivity`; the scene's first when `activity` is absent) against its peak. */
30
+ export interface GroupReadoutInput {
31
+ readonly kind: "rate";
32
+ /** The id of an activity added with `addActivity`. */
33
+ readonly activity?: string;
34
+ }
35
+ /**
36
+ * A group of listed orbits drawn as one set of dots: one dot per orbit, on its own ellipse, one colour and dot size, one menu item and one info card.
37
+ * The group's id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be named by story panels. The orbits' shapes are as listed; where each dot sits
38
+ * along its orbit is a drawing choice (an even spread, shuffled by `seed`) and the info card says so.
39
+ */
40
+ export interface GroupInput {
41
+ /** The group's id: its menu item, camera target and panel `object`. Not shared with any body, path or other group. */
42
+ readonly id: string;
43
+ /** The listed orbits; at least one, ids distinct. */
44
+ readonly orbits: readonly GroupOrbitInput[];
45
+ /** Name on the menu and info card; the id when absent. */
46
+ readonly label?: string;
47
+ /** The body the orbits circle; the scene's centre (its first body) when absent. It must be in the scene. */
48
+ readonly center?: BodyId;
49
+ /** The plane the elements are given in: "ecliptic-j2000" (default) or "EQJ" (the equator of J2000). */
50
+ readonly plane?: "ecliptic-j2000" | "EQJ";
51
+ /** The dots' colour as a CSS hex colour such as "#9de3a8"; default "#9de3a8". */
52
+ readonly color?: string;
53
+ /** Dot size in screen pixels; default 2.5. */
54
+ readonly dotSizePx?: number;
55
+ /** The moment each orbit's dot is placed from (then it moves by two-body motion); the scene's opening time when absent. */
56
+ readonly referenceTime?: TimeInput;
57
+ /** A whole number from 0 to 4294967295 that shuffles which orbit takes which place along its orbit; the same seed gives the same picture. Default 0. */
58
+ readonly seed?: number;
59
+ /** Draws a share of the dots near a body's position along its orbit. */
60
+ readonly clump?: GroupClumpInput;
61
+ /** How often, in simulated milliseconds, the dots are placed again exactly; between fills the picture blends the two nearest. Presentation only. Default five minutes. */
62
+ readonly refillAfterMs?: number;
63
+ /** Milliseconds of each frame the dots layer may spend computing the next fill ahead of time, so a large group does not hitch; 0 or a positive number. 0 makes every fill whole in one frame. Presentation only. Default 8. */
64
+ readonly refillSliceMs?: number;
65
+ /** Where the orbit list came from. The group still marks the position along each orbit as illustrative. Defaults to an "as supplied" notice. */
66
+ readonly provenance?: Provenance;
67
+ /** One or two plain sentences for the info card; a count and placement sentence when absent. */
68
+ readonly description?: string;
69
+ /** Limits of the list, shown first on the info card; the group adds its own placement and motion limits. */
70
+ readonly knownLimitations?: readonly string[];
71
+ /** Bars for the info card, in order. Absent: none. */
72
+ readonly readouts?: readonly GroupReadoutInput[];
73
+ }
74
+ /** A validated group, built into a draw layer once the scene's centre and opening time are known. */
75
+ export interface PlannedGroup {
76
+ readonly id: string;
77
+ readonly label: string;
78
+ readonly input: GroupInput;
79
+ }
80
+ /** Checks what can be checked before the scene is complete; the centre, the clump body and the id clash with other things are checked at build. */
81
+ export declare function planGroup(input: GroupInput, catalogue?: BodyCatalogue): PlannedGroup;
82
+ /** Builds the draw layer: the listed-orbit group and its one shell item. `center` and `openUtcMs` come from the finished scene; a group error from the engine is renamed `bad-group`. */
83
+ export declare function buildGroupLayer(plan: PlannedGroup, catalogue: BodyCatalogue, center: BodyId, openUtcMs: number, window: TimeBounds): GroupLayer;