astraeus 0.2.0 → 0.4.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 (75) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +72 -9
  3. package/package.json +2 -1
  4. package/src/api/AstraeusScene.js +1 -1
  5. package/src/api/AstraeusScene.node.js +37 -0
  6. package/src/api/activity.d.ts +1 -1
  7. package/src/api/activity.js +1 -1
  8. package/src/api/bodies.d.ts +2 -0
  9. package/src/api/bodies.js +2 -0
  10. package/src/api/group.d.ts +7 -1
  11. package/src/api/index.d.ts +2 -1
  12. package/src/api/index.js +2 -1
  13. package/src/api/index.node.js +8 -0
  14. package/src/api/mount.js +3 -1
  15. package/src/api/mount.node.js +36 -0
  16. package/src/api/scene.d.ts +51 -10
  17. package/src/api/scene.js +216 -55
  18. package/src/api/story.d.ts +8 -2
  19. package/src/api/story.js +11 -0
  20. package/src/api/sunOrbit.d.ts +6 -0
  21. package/src/api/sunOrbit.js +24 -0
  22. package/src/app/App.d.ts +6 -2
  23. package/src/app/App.js +8 -4
  24. package/src/app/App.node.js +401 -0
  25. package/src/app/PanelLoadBoundary.d.ts +2 -1
  26. package/src/app/PanelLoadBoundary.js +2 -2
  27. package/src/app/SceneLabels.d.ts +2 -0
  28. package/src/app/SceneLabels.js +5 -1
  29. package/src/app/SkyView.d.ts +3 -3
  30. package/src/app/SkyView.js +19 -10
  31. package/src/app/TrackedBodyView.d.ts +9 -3
  32. package/src/app/TrackedBodyView.js +52 -13
  33. package/src/app/experienceDefinition.d.ts +8 -0
  34. package/src/app/mission.d.ts +2 -0
  35. package/src/app/pathRules.d.ts +7 -3
  36. package/src/app/pathRules.js +9 -5
  37. package/src/app/sceneContentsHooks.js +2 -2
  38. package/src/app/sceneDebug.d.ts +4 -2
  39. package/src/app/sceneFrame.js +5 -4
  40. package/src/app/sceneFraming.d.ts +13 -0
  41. package/src/app/sceneFraming.js +22 -0
  42. package/src/app/skyModel.js +1 -1
  43. package/src/assets/pictures.d.ts +1 -1
  44. package/src/assets/sky.d.ts +4 -4
  45. package/src/assets/sky.js +12 -13
  46. package/src/core/bodies/io.js +1 -1
  47. package/src/core/bodies/jupiterData.js +2 -2
  48. package/src/core/bodies/jupiterMoons.js +8 -12
  49. package/src/core/bodies/moon.d.ts +8 -0
  50. package/src/core/bodies/moon.js +28 -5
  51. package/src/core/bodies/outerPlanetData.js +7 -7
  52. package/src/core/bodies/planetMoons.js +18 -27
  53. package/src/core/bodies/swiftTuttle.js +2 -0
  54. package/src/core/elementsBody.d.ts +2 -0
  55. package/src/core/elementsBody.js +3 -0
  56. package/src/core/moonTrajectory.js +3 -5
  57. package/src/core/planetModels.js +1 -1
  58. package/src/core/provenance.d.ts +6 -2
  59. package/src/core/provenance.js +3 -1
  60. package/src/core/scalePolicy.d.ts +2 -0
  61. package/src/core/scalePolicy.js +2 -0
  62. package/src/shell/AstraeusShell.js +5 -3
  63. package/src/shell/AstraeusShell.node.js +225 -0
  64. package/src/shell/DisplaySwitches.js +1 -1
  65. package/src/shell/StoryPanelView.js +3 -1
  66. package/src/shell/TimelineBar.node.js +75 -0
  67. package/src/shell/TopBar.node.js +14 -0
  68. package/src/shell/experience.d.ts +2 -0
  69. package/src/shell/infoModel.js +3 -1
  70. package/src/shell/phone.css +1 -1
  71. package/src/shell/useDrawers.js +1 -1
  72. package/src/shell/useZoomThrough.d.ts +7 -0
  73. package/src/shell/useZoomThrough.js +51 -0
  74. package/src/synthetic/syntheticProbeDefinition.d.ts +5 -0
  75. package/src/synthetic/syntheticProbeDefinition.js +38 -0
package/CHANGELOG.md CHANGED
@@ -2,6 +2,50 @@
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.4.0 (2026-10-31)
6
+
7
+ First download of the packed example (`npm run measure:example`): 1,594,919 bytes raw, 453,695 bytes gzip (code and styles loaded on first open).
8
+
9
+ A recorded path can now cross the solar system (O-046, G-013), from findings sent back by an outside Voyager app built on 0.3.0.
10
+
11
+ - `addTrajectory` says which frame its positions use (I-097): equatorial J2000 (EQJ) about `center`, as before. A new `plane: "ecliptic-j2000"` option takes ecliptic vectors as JPL Horizons publishes them and rotates them to EQJ once on the way in (samples and provider states), so drawing, `stateOf` and readouts agree. A bad `plane` throws `bad-trajectory`.
12
+ - A path can cross the solar system (O-046). `addTrajectory` is now accepted in a Sun-centred scene (it threw `bad-trajectory`), and a new `lineFixedTo` option names the body the path's line is drawn against at each sample's own time (default the scene centre; `"sun"` for a probe). A `lineFixedTo` body the finished scene does not hold throws `bad-trajectory`. Paths in Earth-centred scenes draw as before.
13
+ - Behaviour change (O-046): `addTrajectory`'s `center` now defaults to the scene's centre (its first body) instead of always `"earth"`. Scenes whose first body is Earth (Apollo 11, the hello example) are unchanged; a scene whose first body is neither Earth nor the Sun now reads its paths' positions from that body, so add `center: "earth"` to keep the old reading. A path added before any body follows the first body added; with no catalogued first body the default stays Earth. Found when a made-up probe given from the Sun missed Earth by a wide margin in a Sun-first scene.
14
+ - `solarSystemScale` is exported beside `trueScale` and `readableScale`, and `setScale` accepts it (I-098), so a Sun-centred scene with an enlarged body can open on the Solar system view. In any other scene `toDefinition` throws `bad-scale`.
15
+ - Example and check (O-046 T-193): the README shows a made-up Sun-centred probe path ("A probe across the solar system"); the repository's dev site opens a fuller made-up one at `?experience=synthetic-probe` (not in public builds). A provider path's `orientation` is not rotated by `plane` (documented limit).
16
+ - A path's own name shows (I-100). Its label was limited to 4 scaled units from the camera, so it never showed at a normal view; it now has the same reach as a body's label (none in a Sun-centred or fitted scene, otherwise the camera reach, at least 500) and follows the `labels` switch. In Earth-centred scenes a path's label now shows as far out as a body's; give it `labelReach` to keep a shorter reach (Apollo 11 keeps 4).
17
+ - New `labelReach` option on `addBody` and `addTrajectory`: a positive number (the camera's `distance` units) that limits how far from the camera that label shows, replacing the shared rule for that item; a bad value throws `bad-body` / `bad-trajectory`. Apollo 11 sets `labelReach: 4` on its paths so they behave as before.
18
+ - Wording only (O-046): the `addActivity` error for a missing unit now suggests `"events per hour"` instead of `"meteors per hour"` (the engine names no shower, ARCH-06); the doc comment's example changed the same way.
19
+ - Labels (I-108): as before, the label of the selected object (the one `camera.follow` or `camera.lookAt` opens on) always wins a collision with another label, so follow a path to keep its name shown on a small screen; other labels keep their priority order (bodies before paths). A scene's labels also stay hidden until the first layout places them, so none shows unplaced for a moment after load.
20
+
21
+ ## 0.3.0 (2026-10-29)
22
+
23
+ First download of the packed example (`npm run measure:example`): 1,592,336 bytes raw, 453,513 bytes gzip (code and styles loaded on first open).
24
+
25
+ - The Milky Way is a new picture (I-026), no API change. The sky's Milky Way band is now the starless Gaia EDR3 render by Kevinmloch (CC BY-SA 4.0, 3840x1920), softer against the catalogue stars; it replaces the two ESO halves. The picture ships in `astraeus-data` (see its changelog) and is dimmed in the viewer; `milkyWayBrightness` still scales it, and it stays off by default.
26
+
27
+ - Answers for sites (O-045). `Scene.stateOf(id, time)` now answers for every body in the scene (ready-made bodies, moons, elements bodies), not only `addTrajectory` paths; they answer at any date, only a path refuses a moment outside it (`bad-time`), and a planet answers once the planet series are loaded (`missing-data` before). Its unknown-body message now reads "no body or trajectory with that id". New `Scene.provenanceOf(id)` returns the body's `Provenance`, which gains optional `accuracyClass` and `maxErrorFraction`: built-in Swift-Tuttle's is measured (0.00857); an elements body's is the limit of its class (0.01 approximate, 0.05 indicative), an upper bound and not a measured figure. New root exports: `APPROXIMATE_LIMIT_FRACTION`, `INDICATIVE_LIMIT_FRACTION`, `classifyPositionError` and `parseElementsBodyRecord`.
28
+
29
+ - Fit the zoom-out to an orbit (O-045). New `camera.fitOrbit(body)` sets the farthest zoom-out so the body's whole orbit fits the canvas from any direction, and re-fits when the canvas changes shape; the far plane is 2.5 times the reach. `setReach` and `fitOrbit` set the same limit, the later call wins. The opening view is unchanged except that it is clamped to the limit like any other. Labels are not limited in a fitted scene. `SceneError` `bad-camera` for a body that does not circle the Sun.
30
+
31
+ - Event labels (O-045). New provenance source type `"modelled"` (shown as "Modelled"). `addEvents` events take their own `provenance`, which wins over the batch's. Batch and per-event provenance are now validated: a malformed one throws `bad-event` (the batch one was not checked before). A group's info card shows "illustrative" as its source type, with the elements' type in the accuracy sentence (documented).
32
+
33
+ - Visible change (O-045). A body added with `addBodyFromElements` now has a live "Distance from Sun" row on its info card, and in the Geminids demo the Sun's card also lists "Distance to Phaethon".
34
+
35
+ - A better guest in a host page (O-044). `mount` and `AstraeusScene` no longer change `document.title`. The viewer's Escape handlers (story panel, phone drawer, switch panel) ignore a keydown the host already stopped with `preventDefault()`. The mount element and the `AstraeusScene` wrapper get `isolation: isolate`, so the viewer's `z-index` values (0 to 9) stay inside it; a `style` you pass to `AstraeusScene` can override it, and `mount` does not restore the element's old `isolation` on `unmount`.
36
+
37
+ - Node loading (O-044), no API change. The package's JSON imports now carry `with { type: "json" }`, and the root export has a `node` condition (order: types, node, import) that points at copies without the stylesheet import, so Node and Vitest's Node environment import `astraeus` with no inline setting. Bundlers keep the normal build. jsdom and happy-dom Vitest environments also take the `node` condition, so they do not load the viewer's CSS.
38
+
39
+ - Default time (O-044). A scene with no `setTime`, no `setTimeline` window and no trajectory now opens on the current time with a window of a month around it. This includes `setTimeline({ none: true })` with no `at`, which opens on the current time too (new in O-044; it was not changed in O-045).
40
+
41
+ - Phone story panel (O-044). On a phone, a wheel or two-finger pinch over an open story sheet zooms the scene behind it (the sheet has `touch-action: pan-y`).
42
+
43
+ - Documentation (O-044). The README says who needs `astraeus/style.css`, why a plain-JavaScript page still needs React, how story panels open and pause, that `camera.setReach(d)` also sets the far plane to 2.5 times `d`, and how to reload on `vite:preloadError`; `addStoryPanels`, `StoryPanelsInput` and `setReach` doc comments say the same.
44
+
45
+ - The Moon now shows libration (I-091), no API change. Its orientation was a plain tidal lock; it is now the IAU mean-Earth rotation model with its libration terms (Archinal et al. 2009 report, as saved in NAIF pck00011), so the Moon nods and sways by up to about 8 degrees as it does in the sky. Against JPL Horizons at seven dates from 1969 to 2050 the sub-Earth point and pole agree within 0.01 degrees (about 0.3 km on the surface); a surface place can no longer sit up to 8 degrees (254 km at Apollo 11's touchdown) from its true spot. Moon-surface features and mesh textures move accordingly.
46
+
47
+ - Documentation only: `addGroup` states that a `center` that is not a catalogued body throws `unknown-body` (a catalogued one missing from the scene throws `bad-group`), and `setTimeline` states that `loop` is ignored with `{ none: true }` or without a timeline. No behaviour changes.
48
+
5
49
  ## 0.2.0
6
50
 
7
51
  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).
package/README.md CHANGED
@@ -12,7 +12,11 @@ npm install astraeus react react-dom @react-three/fiber three
12
12
 
13
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
14
 
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.
15
+ A plain-JavaScript page still needs React: `mount` draws the viewer with React and `@react-three/fiber` inside, so all four peers must be installed even if your own code never touches React.
16
+
17
+ `mount` loads the viewer's stylesheet itself. If you use the `AstraeusScene` component instead, add `import "astraeus/style.css";` once in your app.
18
+
19
+ 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)`; drawing needs a bundler and a browser, so do not load it from a bare `<script type="module">`. Node and Vitest can import it for scene definitions and tests (see "Loading in your build and in tests").
16
20
 
17
21
  ## A scene in about 20 lines
18
22
 
@@ -38,6 +42,33 @@ mount(document.getElementById("app"), scene);
38
42
 
39
43
  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`.
40
44
 
45
+ ### A probe across the solar system
46
+
47
+ A recorded path can cross the solar system beside enlarged planets. This one is made up (an invented straight line that starts 0.6 AU from the Sun, inside Earth's orbit, and ends about 1.49 AU out, given in ecliptic axes; it is not aimed at any planet); the same calls take positions you downloaded from JPL Horizons.
48
+
49
+ ```js
50
+ import { Scene, earth, mars, mount, solarSystemScale, sun } from "astraeus";
51
+
52
+ const start = Date.parse("2026-01-01T00:00:00Z");
53
+ const DAY = 86_400_000;
54
+ const AU = 149_597_870.7;
55
+ // Ecliptic J2000 positions from the Sun, in km: a straight line from 0.6 AU to about 1.49 AU from the Sun over 200 days (x runs 0.6 to 1.1 AU, y 0 to 1.0 AU).
56
+ const samples = Array.from({ length: 11 }, (_, i) => ({ time: start + i * 20 * DAY, positionKm: [AU * (0.6 + 0.05 * i), AU * 0.1 * i, 0] }));
57
+
58
+ const scene = new Scene()
59
+ .addBody(sun)
60
+ .addBody(earth, { enlarge: 60 })
61
+ .addBody(mars, { enlarge: 60 })
62
+ .addTrajectory({ id: "probe", label: "Made-up probe", samples, plane: "ecliptic-j2000", lineFixedTo: "sun" })
63
+ .setTime(start)
64
+ .setScale(solarSystemScale);
65
+ scene.camera.fitOrbit(mars);
66
+
67
+ mount(document.getElementById("app"), scene);
68
+ ```
69
+
70
+ Positions are about the scene centre (here the Sun, the first body) unless `center` says otherwise. `lineFixedTo: "sun"` keeps the line still against the Sun while the planets move; `plane` turns the ecliptic vectors into the engine's equatorial frame once; `solarSystemScale` keeps the distances true and draws the named bodies larger; the probe's name shows at any distance in a Sun-centred scene. The repository's dev site opens a fuller version at `?experience=synthetic-probe`.
71
+
41
72
  ## The public API
42
73
 
43
74
  The full reference, generated from the types and doc comments, is at <https://astraeus.anipatke.com/api/>. The table below is the short form.
@@ -45,25 +76,35 @@ The full reference, generated from the types and doc comments, is at <https://as
45
76
  | Call | What it does |
46
77
  |---|---|
47
78
  | `new Scene()` | An empty scene. Every method below returns the scene, so calls chain. |
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`. |
79
+ | `scene.addBody(body, { orbit?, enlarge?, showLabel?, labelReach?, 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; `labelReach` (a positive number, in the camera's distance units) shows its label only within that distance of the camera, in place of the scene's shared rule. A scene whose first body is the Sun sets no label reach, so labels stay when zoomed out, and it can hold a path (`addTrajectory`, drawn with `lineFixedTo: "sun"`). `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`. |
80
+ | `scene.addTrajectory({ id, label?, color?, center?, plane?, lineFixedTo?, labelReach?, samples, provenance?, description?, knownLimitations?, anchors?, readouts? })` | A recorded path. Each sample is `{ time, positionKm, velocityKmS? }` measured from `center` (default: the scene's centre, its first body, so a Sun-first scene reads them from the Sun and an Earth-first one from Earth; Earth if no body is added) in equatorial J2000 (EQJ) axes; `plane: "ecliptic-j2000"` instead takes ecliptic J2000 vectors as JPL Horizons publishes them and rotates them to EQJ once on the way in (positions and velocities, from samples or a provider; a provider's `orientation` quaternion passes through unrotated, a known limit; any other `plane` throws `bad-trajectory`); `lineFixedTo` names the body the line is drawn against (default the scene centre): each sample is placed from that body at the sample's own time, then the line is carried to that body's place from the scene centre at the clock time, so `"sun"` fixes a probe's line to the Sun in any scene, Sun-centred ones included, and a body the scene does not hold throws `bad-trajectory`; `labelReach` (a positive number, in the camera's distance units) limits how far from the camera its name shows, in place of the scene's shared rule; a bad value throws `bad-trajectory`; `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. |
81
+ | `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, with a live "Distance from Sun" row. `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`. |
82
+ | `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 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`. |
52
83
  | `scene.setTime(time)` | The moment the scene opens at. |
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. |
84
+ | `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`. |
85
+ | `scene.addEvents(events, { provenance? })` | Timed events on the timeline: `[{ id, label, time, type?, provenance? }]`, ids unique. `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. |
55
86
  | `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
87
  | `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
88
  | `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. |
89
+ | `scene.camera.setReach(distance)` | How far the viewer can zoom out, in Earth radii; labels reach as far, a path's own name (at its marker, switched by `labels`) included. A bad value throws `bad-camera`. The object the scene opens on (`camera.follow` or `camera.lookAt`) 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.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. |
90
+ | `scene.camera.fitOrbit(body)` | Sets the farthest zoom-out so the whole orbit of a body that circles the Sun (a planet, the built-in comet, or one 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")` |
59
91
  | `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. |
92
+ | `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, built-in Swift-Tuttle 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 data lives in the planet series, so it answers only once they are loaded (at `mount`), else `missing-data`. `const au = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm) / 149597870.7;` |
93
+ | `scene.provenanceOf(id)` | Where a body's position comes from, as its info card shows it. Where a comparison with an independent ephemeris exists it carries `accuracyClass` and `maxErrorFraction`. For built-in Swift-Tuttle that fraction is measured (0.00857). For a body from `addBodyFromElements` it is the limit of its class (0.01 `approximate`, 0.05 `indicative`): an upper bound, not a measured figure. Other bodies carry neither field. |
61
94
  | `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
95
  | `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. |
63
96
  | `mount(element, scene, { data? })` | Draws the scene with the full viewer. Returns `{ ready, unmount() }`. `data` is a list of data packages (below). |
64
97
  | `<AstraeusScene scene data? onReady? onError? />` | The same viewer as a React component (below). |
65
98
  | `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. |
66
99
 
100
+ Checking accuracy and records without a scene: the class limits are root exports (`APPROXIMATE_LIMIT_FRACTION`, `INDICATIVE_LIMIT_FRACTION`), `classifyPositionError(maxFraction)` returns `"approximate"`, `"indicative"` or `null` (neither) for a measured largest error fraction, and `parseElementsBodyRecord(record)` validates an elements record (the same check `addBodyFromElements` makes, throwing `bad-element` naming the field):
101
+
102
+ ```js
103
+ import { classifyPositionError, parseElementsBodyRecord } from "astraeus";
104
+ const accuracyClass = classifyPositionError(0.004); // measured error / distance from the Sun
105
+ const record = parseElementsBodyRecord(myRecord);
106
+ ```
107
+
67
108
  Types (`State`, `Pictures`, `TextureRef`, `AssetLicence`, `DataSource`, `TrajectoryInput` and the like) are exported for TypeScript.
68
109
 
69
110
  ## In a React app
@@ -84,6 +125,28 @@ export const App = () => (
84
125
 
85
126
  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
127
 
128
+ ## Inside someone else's page
129
+
130
+ The viewer is built to sit in a host page without taking it over. It never changes `document.title`. It isolates its own layers (`isolation: isolate` on the element given to `mount` and on the `AstraeusScene` wrapper), so its `z-index` values (0 to 9) stay inside the viewer and cannot cover or sit under your page's layers; `mount` does not restore the element's old `isolation` on `unmount`. Its Escape handlers (story panel, phone drawer, switch panel) ignore a keydown your page already stopped with `preventDefault()`. It honours `prefers-reduced-motion`: the viewer's own animations and transitions are switched off.
131
+
132
+ A scene with no `setTime`, `setTimeline` or trajectory opens on the current time, with a window of a month around it.
133
+
134
+ Story panels (`addStoryPanels`): a panel opens only when forward playback crosses its time, so one at the opening instant never opens by itself. `at.utc` may be any instant inside the timeline, in any year. When a panel opens by itself, `pauseSeconds` (default 6) holds playback and then restarts it, unless the visitor pressed Play during the hold. On a phone, a wheel or pinch over an open story sheet zooms the scene behind it. `camera.setReach(d)` sets how far the camera can zoom out and also sets the far plane to 2.5 times `d`.
135
+
136
+ ## Loading in your build and in tests
137
+
138
+ `planetModels` (the planet series), the Developer drawer's panels and `MoonFamilyPanel` are separate files that your build loads later, on demand. After you redeploy, a tab left open may ask for a file name that no longer exists. In a Vite host, reload the page when that happens:
139
+
140
+ ```js
141
+ window.addEventListener("vite:preloadError", () => window.location.reload());
142
+ ```
143
+
144
+ (The Developer drawer also says when its file cannot be fetched and asks for a reload.)
145
+
146
+ For tests, the package has a `node` export condition: Node and Vitest's Node environment import a copy of the package without the stylesheet import, so `new Scene()...toDefinition()` works with no `test.server.deps.inline` setting. The jsdom and happy-dom Vitest environments also take the `node` condition, so the viewer's CSS is not loaded there; this does not matter for tests that check scene definitions or behaviour. Bundlers do not use the `node` condition and load the normal build.
147
+
148
+ First download: the packed `examples/hello-scene` loads 1,589,214 bytes (454,404 gzip) of code and styles, measured at this commit on first open (`npm run measure:example`; pictures and data files are not counted).
149
+
87
150
  ## What `astraeus-data` adds
88
151
 
89
152
  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,6 +1,6 @@
1
1
  {
2
2
  "name": "astraeus",
3
- "version": "0.2.0",
3
+ "version": "0.4.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",
@@ -16,6 +16,7 @@
16
16
  "exports": {
17
17
  ".": {
18
18
  "types": "./src/api/index.d.ts",
19
+ "node": "./src/api/index.node.js",
19
20
  "import": "./src/api/index.js"
20
21
  },
21
22
  "./style.css": "./src/app/style.css"
@@ -34,5 +34,5 @@ export function AstraeusScene({ scene, data, onReady, onError, className, style
34
34
  }
35
35
  return () => { open = false; };
36
36
  }, [scene]);
37
- return _jsx("div", { className: className, style: { ...FILL, ...style }, children: definition ? _jsx(App, { definition: definition }) : null });
37
+ return _jsx("div", { className: className, style: { ...FILL, isolation: "isolate", ...style }, children: definition ? _jsx(App, { definition: definition, writeTitle: false }) : null });
38
38
  }
@@ -0,0 +1,37 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { useEffect, useRef, useState } from "react";
3
+ import { App } from "../app/App.node.js";
4
+ import { prepareScene } from "./prepared.js";
5
+ const FILL = { width: "100%", height: "100%" };
6
+ const asError = (cause) => (cause instanceof Error ? cause : new Error(String(cause)));
7
+ /**
8
+ * 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.
9
+ * @example
10
+ * const scene = new Scene().addBody(earth).addBody(moon);
11
+ * export function App() {
12
+ * return <div style={{ height: "100vh" }}><AstraeusScene scene={scene} onError={console.error} /></div>;
13
+ * }
14
+ */
15
+ export function AstraeusScene({ scene, data, onReady, onError, className, style }) {
16
+ const [definition, setDefinition] = useState();
17
+ // The latest data and callbacks, read when the scene is built, so a new array or arrow function each render does not rebuild it.
18
+ const latest = useRef({ data, onReady, onError });
19
+ latest.current = { data, onReady, onError };
20
+ useEffect(() => {
21
+ let open = true;
22
+ setDefinition(undefined);
23
+ try {
24
+ const prepared = prepareScene(scene, latest.current.data);
25
+ prepared.ready.then(() => { if (open) {
26
+ setDefinition(prepared.definition);
27
+ latest.current.onReady?.();
28
+ } }, (cause) => { if (open)
29
+ latest.current.onError?.(asError(cause)); });
30
+ }
31
+ catch (cause) {
32
+ latest.current.onError?.(asError(cause));
33
+ }
34
+ return () => { open = false; };
35
+ }, [scene]);
36
+ return _jsx("div", { className: className, style: { ...FILL, isolation: "isolate", ...style }, children: definition ? _jsx(App, { definition: definition, writeTitle: false }) : null });
37
+ }
@@ -22,7 +22,7 @@ export interface ActivityInput {
22
22
  readonly id: string;
23
23
  /** Name shown on the timeline and with the rate bar. */
24
24
  readonly label: string;
25
- /** What the rate counts, per unit of time, such as "meteors per hour". */
25
+ /** What the rate counts, per unit of time, such as "events per hour". */
26
26
  readonly unit: string;
27
27
  /** The first and last moment of the activity. The curve's samples lie inside it, and the rate is unavailable outside it. */
28
28
  readonly start: TimeInput;
@@ -12,7 +12,7 @@ function checkFields(input) {
12
12
  if (!isText(input.label))
13
13
  throw bad(id, "the activity needs a non-empty label");
14
14
  if (!isText(input.unit))
15
- throw bad(id, "the activity needs a unit such as \"meteors per hour\"");
15
+ throw bad(id, "the activity needs a unit such as \"events per hour\"");
16
16
  if (!Array.isArray(input.samples) || input.samples.length < 2)
17
17
  throw bad(id, "the curve needs at least two samples");
18
18
  if (input.peakLabel !== undefined && !isText(input.peakLabel))
@@ -15,6 +15,8 @@ export declare const venus: BodyRef;
15
15
  export declare const earth: BodyRef;
16
16
  /** Moon. */
17
17
  export declare const moon: BodyRef;
18
+ /** The scene centre when a path is added before any body: Earth, the documented default (the only place the fallback is named; ARCH-06). */
19
+ export declare const FALLBACK_SCENE_CENTRE: BodyId;
18
20
  /** Mars. */
19
21
  export declare const mars: BodyRef;
20
22
  /** Jupiter. */
package/src/api/bodies.js CHANGED
@@ -9,6 +9,8 @@ export const venus = ref("venus", "Venus");
9
9
  export const earth = ref("earth", "Earth");
10
10
  /** Moon. */
11
11
  export const moon = ref("moon", "Moon");
12
+ /** The scene centre when a path is added before any body: Earth, the documented default (the only place the fallback is named; ARCH-06). */
13
+ export const FALLBACK_SCENE_CENTRE = earth.id;
12
14
  /** Mars. */
13
15
  export const mars = ref("mars", "Mars");
14
16
  /** Jupiter. */
@@ -62,7 +62,13 @@ export interface GroupInput {
62
62
  readonly refillAfterMs?: number;
63
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
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. */
65
+ /**
66
+ * Where the orbit list came from. The group's own card always shows `sourceType` "illustrative", because the position along each orbit is a drawing choice;
67
+ * the orbits' `sourceType` here is kept in the accuracy line as "Orbit elements are as listed (<sourceType>); the position along each orbit is illustrative."
68
+ * Your `sources` stay, and the group appends this note to your `notes`: "Each orbit's shape and orientation come from its record, but the records give no
69
+ * position along the orbit: that position is an even spread of mean anomaly at the reference time, a drawing choice (illustrative), advanced by unperturbed
70
+ * two-body motion about the centre." (plus a sentence naming the clump, when `clump` is set). Defaults to an "as supplied" notice.
71
+ */
66
72
  readonly provenance?: Provenance;
67
73
  /** One or two plain sentences for the info card; a count and placement sentence when absent. */
68
74
  readonly description?: string;
@@ -5,8 +5,9 @@ export { mount, type MountOptions, type MountedScene } from "./mount.js";
5
5
  export { AstraeusScene, type AstraeusSceneProps } from "./AstraeusScene.js";
6
6
  export { SceneError, type SceneErrorCode } from "./errors.js";
7
7
  export { 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, type BodyRef } from "./bodies.js";
8
- export { trueScale, readableScale, type ScalePolicy } from "../core/scalePolicy.js";
8
+ export { trueScale, readableScale, solarSystemScale, type ScalePolicy } from "../core/scalePolicy.js";
9
9
  export type { State } from "../core/state.js";
10
10
  export type { Provenance, ProvenanceSourceType } from "../core/provenance.js";
11
11
  export type { Pictures } from "../assets/pictures.js";
12
12
  export type { AssetLicence, TextureRef } from "../assets/licence.js";
13
+ export { APPROXIMATE_LIMIT_FRACTION, INDICATIVE_LIMIT_FRACTION, classifyPositionError, parseElementsBodyRecord, type AccuracyClassification } from "../core/elementsBody.js";
package/src/api/index.js CHANGED
@@ -4,4 +4,5 @@ export { mount } from "./mount.js";
4
4
  export { AstraeusScene } from "./AstraeusScene.js";
5
5
  export { SceneError } from "./errors.js";
6
6
  export { 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 } from "./bodies.js";
7
- export { trueScale, readableScale } from "../core/scalePolicy.js";
7
+ export { trueScale, readableScale, solarSystemScale } from "../core/scalePolicy.js";
8
+ export { APPROXIMATE_LIMIT_FRACTION, INDICATIVE_LIMIT_FRACTION, classifyPositionError, parseElementsBodyRecord } from "../core/elementsBody.js";
@@ -0,0 +1,8 @@
1
+ // The engine's public API (0.2 preview): everything not exported here is internal.
2
+ export { Scene, SceneCamera } from "./scene.js";
3
+ export { mount } from "./mount.node.js";
4
+ export { AstraeusScene } from "./AstraeusScene.node.js";
5
+ export { SceneError } from "./errors.js";
6
+ export { 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 } from "./bodies.js";
7
+ export { trueScale, readableScale, solarSystemScale } from "../core/scalePolicy.js";
8
+ export { APPROXIMATE_LIMIT_FRACTION, INDICATIVE_LIMIT_FRACTION, classifyPositionError, parseElementsBodyRecord } from "../core/elementsBody.js";
package/src/api/mount.js CHANGED
@@ -17,11 +17,13 @@ export function mount(element, scene, options = {}) {
17
17
  if (!(element instanceof Object) || typeof element.appendChild !== "function")
18
18
  throw new SceneError("bad-element", "mount: the first argument must be an element of the page");
19
19
  const { definition, ready: loaded } = prepareScene(scene, options.data);
20
+ // Its own stacking context, so the viewer's z-index values cannot rise above the host page's overlays.
21
+ element.style.isolation = "isolate";
20
22
  const root = createRoot(element);
21
23
  let open = true;
22
24
  const ready = loaded.then(() => {
23
25
  if (open)
24
- root.render(createElement(App, { definition }));
26
+ root.render(createElement(App, { definition, writeTitle: false }));
25
27
  });
26
28
  return {
27
29
  ready,
@@ -0,0 +1,36 @@
1
+ import { createElement } from "react";
2
+ import { createRoot } from "react-dom/client";
3
+ import { App } from "../app/App.node.js";
4
+ import { SceneError } from "./errors.js";
5
+ import { prepareScene } from "./prepared.js";
6
+ /**
7
+ * Draws `scene` into `element` with the full viewer. The caller writes no React. The element needs a size.
8
+ * @example
9
+ * import { Scene, earth, moon, mount } from "astraeus";
10
+ * const scene = new Scene().addBody(earth).addBody(moon, { orbit: true });
11
+ * const mounted = mount(document.getElementById("app")!, scene);
12
+ * await mounted.ready; // drawn
13
+ * mounted.unmount(); // removes it again
14
+ */
15
+ export function mount(element, scene, options = {}) {
16
+ if (!(element instanceof Object) || typeof element.appendChild !== "function")
17
+ throw new SceneError("bad-element", "mount: the first argument must be an element of the page");
18
+ const { definition, ready: loaded } = prepareScene(scene, options.data);
19
+ // Its own stacking context, so the viewer's z-index values cannot rise above the host page's overlays.
20
+ element.style.isolation = "isolate";
21
+ const root = createRoot(element);
22
+ let open = true;
23
+ const ready = loaded.then(() => {
24
+ if (open)
25
+ root.render(createElement(App, { definition, writeTitle: false }));
26
+ });
27
+ return {
28
+ ready,
29
+ unmount() {
30
+ if (!open)
31
+ return;
32
+ open = false;
33
+ root.unmount();
34
+ },
35
+ };
36
+ }
@@ -1,7 +1,7 @@
1
1
  import type { BodyId } from "../core/body.js";
2
2
  import { type Provenance } from "../core/provenance.js";
3
3
  import { type ScalePolicy } from "../core/scalePolicy.js";
4
- import type { State } from "../core/state.js";
4
+ import { type State } from "../core/state.js";
5
5
  import { type ElementsBodyRecord } from "../core/elementsBody.js";
6
6
  import type { ExperienceDefinition } from "../app/experienceDefinition.js";
7
7
  import { type BodyRef } from "./bodies.js";
@@ -27,6 +27,8 @@ export interface AddBodyOptions {
27
27
  readonly enlarge?: number;
28
28
  /** False starts the body's label off (the body stays in the menu and selectable; the viewer's labels switch can turn it on). Default true. */
29
29
  readonly showLabel?: boolean;
30
+ /** How far from the camera the body's label shows, in the camera's `distance` units (as `camera.setReach`); a positive finite number. When absent the scene's shared rule applies: no limit in a Sun-centred or fitted scene, else the camera reach (at least 500). */
31
+ readonly labelReach?: number;
30
32
  /** One or two plain sentences for the body's info card. */
31
33
  readonly description?: string;
32
34
  /** The body's colour on its info card and label, as a CSS hex colour such as "#9fd8ff"; the catalogue's own when absent. A bad value throws `bad-body`. */
@@ -56,7 +58,7 @@ export type ReadoutInput = {
56
58
  readonly kind: "altitude";
57
59
  readonly above: BodyId;
58
60
  };
59
- /** One sample of a recorded path: position in km (and optionally velocity in km/s) about the trajectory's centre. */
61
+ /** One sample of a recorded path: position in km (and optionally velocity in km/s) about the trajectory's centre, in equatorial J2000 (EQJ) axes unless the path says `plane: "ecliptic-j2000"`. */
60
62
  export interface TrajectorySampleInput {
61
63
  readonly time: TimeInput;
62
64
  readonly positionKm: ArrayLike<number>;
@@ -66,8 +68,21 @@ interface TrajectoryBase {
66
68
  readonly id: string;
67
69
  readonly label?: string;
68
70
  readonly color?: string;
69
- /** The body the positions are measured from; defaults to "earth". */
71
+ /** The body the positions are measured from; defaults to the scene's centre (its first body, whichever you add first; "earth" if none is a catalogued body). */
70
72
  readonly center?: BodyId;
73
+ /**
74
+ * The body the path's line is drawn against: each sample is placed from this body at the sample's own time, then the line is carried to
75
+ * this body's place from the scene centre at the clock time. Defaults to the scene centre; name the Sun for a probe crossing a Sun-centred scene.
76
+ * Throws `bad-trajectory` at build if the scene does not hold the body.
77
+ */
78
+ readonly lineFixedTo?: BodyId;
79
+ /**
80
+ * The frame the positions and velocities are given in, about `center`: "EQJ" (equatorial J2000, the default) or "ecliptic-j2000" (the vectors JPL Horizons
81
+ * publishes by default). Ecliptic input is rotated to EQJ once, as it is read, so drawing, `stateOf` and readouts all see EQJ. Any other value throws `bad-trajectory`.
82
+ */
83
+ readonly plane?: "EQJ" | "ecliptic-j2000";
84
+ /** How far from the camera the path's label shows, in the camera's `distance` units (as `camera.setReach`); a positive finite number. When absent the scene's shared rule applies: no limit in a Sun-centred or fitted scene, else the camera reach (at least 500). */
85
+ readonly labelReach?: number;
71
86
  readonly provenance?: Provenance;
72
87
  /** One or two plain sentences for the path's info card. */
73
88
  readonly description?: string;
@@ -101,16 +116,30 @@ export interface FollowView {
101
116
  /** The scene's camera: what it opens on. */
102
117
  export declare class SceneCamera {
103
118
  #private;
104
- constructor(has: (id: string) => boolean);
119
+ constructor(has: (id: string) => boolean, circlesSun: (id: string) => boolean);
105
120
  /** Opens framed on a body or trajectory already added to the scene and already following it (the viewer's Follow button shows as pressed). */
106
121
  follow(id: string, view?: FollowView): this;
107
122
  /** Opens framed on a body or trajectory already added to the scene, looking at it but not following it (the viewer's Focus button shows as pressed). The last of `follow` and `lookAt` wins. */
108
123
  lookAt(id: string, view?: FollowView): this;
109
124
  /**
110
125
  * Sets how far the viewer can zoom out from what they look at, in Earth radii (the scene's scaled unit); a finite number above 0, else `bad-camera`.
126
+ * Also sets the camera's far plane (where drawing stops) to 2.5 times `distance`, so what lies out to the reach is still drawn.
111
127
  * Labels reach as far: a body's label stays shown at any distance the camera can take. Without this call the camera frames the scene as before.
128
+ * `setReach` and `fitOrbit` set the same limit, so the later call wins and replaces the earlier one.
112
129
  */
113
130
  setReach(distance: number): this;
131
+ /**
132
+ * Sets the farthest zoom-out so the whole orbit of a body circling the Sun (a planet, a built-in comet or one from `addBodyFromElements`, already added to the scene) fits the canvas
133
+ * from any view direction: the orbit's farthest Sun distance divided by the sine of the narrower half field of view of the canvas (vertical 45 degrees, or horizontal from the
134
+ * canvas's width over height), with 10 percent to spare. The viewer fits again whenever the canvas changes shape, such as a phone turning or a window resizing; the far plane follows
135
+ * as for `setReach`. The opening view does not move. Any other body throws `bad-camera` naming it; an id not in the scene throws `unknown-body`. `setReach` and `fitOrbit` set the
136
+ * same limit, so the later call wins and replaces the earlier one.
137
+ * @example
138
+ * scene.camera.fitOrbit("c-2025-a1");
139
+ */
140
+ fitOrbit(body: BodyRef | BodyId): this;
141
+ /** The body `fitOrbit` fits the zoom-out to, if any. */
142
+ get fitted(): string | undefined;
114
143
  /** The farthest zoom-out set with `setReach`, if any. */
115
144
  get reach(): number | undefined;
116
145
  get target(): string | undefined;
@@ -147,7 +176,7 @@ export declare class Scene {
147
176
  addTrajectory(input: TrajectoryInput): this;
148
177
  /**
149
178
  * Adds a group of listed orbits drawn as one set of dots (one colour and dot size, one menu item and info card), with an optional clump near a body.
150
- * The orbits circle the scene's centre unless `center` names another body. A repeated id throws `duplicate-id`; an empty list, a bad orbit, colour, clump or centre throws `bad-group`.
179
+ * The orbits circle the scene's centre unless `center` names another body. A repeated id throws `duplicate-id`; an empty list, a bad orbit, colour or clump throws `bad-group`. A `center` that is not a catalogued body throws `unknown-body`; a catalogued one the finished scene does not hold throws `bad-group` from `toDefinition`.
151
180
  * @example
152
181
  * scene.addGroup({ id: "ring", orbits: [{ id: "a", semiMajorAxisKm: 90_000, eccentricity: 0.1, inclinationDeg: 5, raanDeg: 40, argumentOfPeriapsisDeg: 70 }], color: "#9de3a8" });
153
182
  */
@@ -161,15 +190,18 @@ export declare class Scene {
161
190
  addActivity(input: ActivityInput): this;
162
191
  /** Sets the moment the scene opens at. */
163
192
  setTime(time: TimeInput): this;
164
- /** Chooses the opening scale: `trueScale` or `readableScale`; the viewer can switch to the other (in a Sun-centred scene with an enlarged body, to the \"solar-system\" scale instead of the readable one), unless `{ only: true }` offers this scale alone. */
193
+ /** Chooses the opening scale: `trueScale`, `readableScale` or `solarSystemScale` (true distances, the enlarged bodies drawn larger; it needs a Sun-centred scene with an enlarged body, else the scene throws `bad-scale`); the viewer can switch to the other (in a Sun-centred scene with an enlarged body, the second choice is the Solar system scale instead of the readable one), unless `{ only: true }` offers this scale alone. */
165
194
  setScale(scale: ScalePolicy, options?: {
166
195
  readonly only?: boolean;
167
196
  }): this;
168
- /** Adds timed events to the timeline, each with an id, a label and a moment; `provenance` says where the times come from and is shown with every event. May be called more than once. */
197
+ /** Adds timed events to the timeline, each with an id, a label and a moment; `provenance` says where the times come from and is shown with every event that has none of its own (`EventInput.provenance`). May be called more than once. Malformed provenance throws "bad-event". */
169
198
  addEvents(events: readonly EventInput[], options?: AddEventsOptions): this;
170
- /** Adds story panels that open as playback reaches them. Their times may name events (`addEvents`) and path anchors, and `object` a body or path; these are checked when the scene is built (`mount`), and a mistake throws `bad-panels` naming the panel and field. */
199
+ /**
200
+ * Adds story panels that open as playback reaches them. A panel opens only when forward playback crosses its time, so one at the opening instant never opens by itself
201
+ * (a panel with an `object` still has its marker on that object). `at.utc` may be any instant inside the timeline, in any year. Their times may name events (`addEvents`) and path anchors, and `object` a body or path; these are checked when the scene is built (`mount`), and a mistake throws `bad-panels` naming the panel and field.
202
+ */
171
203
  addStoryPanels(panels: StoryPanelsInput): this;
172
- /** Sets the timeline: its span (`start`, `end`), the speeds offered (`rates`), the speed it opens at (`rate`) and whether playback wraps from the end to the start (`loop`), or `{ none: true }` for no timeline bar, with time frozen at `at` or running at `rate`. Without this call the span follows the paths and the speeds are 1 minute, 1 hour and 1 day per second. */
204
+ /** Sets the timeline: its span (`start`, `end`), the speeds offered (`rates`), the speed it opens at (`rate`) and whether playback wraps from the end to the start (`loop`; ignored with `{ none: true }`, which has no span to wrap, and when `setTimeline` is not called), or `{ none: true }` for no timeline bar, with time frozen at `at` or running at `rate`. Without this call the span follows the paths and the speeds are 1 minute, 1 hour and 1 day per second. */
173
205
  setTimeline(timeline: TimelineInput): this;
174
206
  /**
175
207
  * Places the display switches: for each of `orbitLines` (orbit ring, trailing arc and moon orbits), `labels` (body and anchor labels) and `milkyWay` (the sky picture), `place` is
@@ -180,8 +212,17 @@ export declare class Scene {
180
212
  * scene.setSwitches({ orbitLines: { place: "top-bar" }, labels: { place: "panel", on: false }, milkyWay: { place: "developer", on: false } });
181
213
  */
182
214
  setSwitches(switches: SwitchesInput): this;
183
- /** The state of a trajectory added with `addTrajectory` at a moment, about its centre body (position in km, velocity in km/s): for figures a story quotes, such as a peak speed. Throws `unknown-body` for any other id and `bad-time` for a moment outside the path. */
215
+ /**
216
+ * The state of a body in the scene at a moment (position in km always; velocity in km/s only where the body's source provides it), the same State the viewer draws: for a path added with `addTrajectory`, about its centre body;
217
+ * for a ready-made body or one from `addBodyFromElements`, about its parent (a planet about the Sun, a moon about its planet). Figures a story quotes, such as a distance from the Sun, come from here. `velocityKmS` is set only for a path whose
218
+ * samples or provider carry velocities and for a moon from fitted data (Io); planets, Earth, the Sun, the built-in comet and elements bodies give position only, so check it before use. An id the scene does not hold throws `unknown-body`. Ready-made and elements bodies answer at any date (they have no data cut-off); only a moment outside an
219
+ * `addTrajectory` path throws `bad-time`. A planet before the planet series have loaded (they load at mount) throws `missing-data`.
220
+ * @example
221
+ * const sunDistanceKm = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm);
222
+ */
184
223
  stateOf(id: string, time: TimeInput): State;
224
+ /** The Provenance of a body's position, as its info card shows it: for a ready-made or elements body the catalogue's position record, for a path the one passed to `addTrajectory`. Carries `accuracyClass` and `maxErrorFraction` where a comparison with an independent ephemeris exists. An id the scene does not hold throws `unknown-body`. */
225
+ provenanceOf(id: string): Provenance;
185
226
  /** The data packages the added bodies need that `data` does not provide. */
186
227
  missingData(data?: readonly DataSource[]): readonly string[];
187
228
  /** The app's plug-in contract for this scene. Throws if the scene is empty or a body needs a data package not passed in `data`. */