astraeus 0.6.0 → 0.7.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 (60) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +31 -8
  3. package/package.json +1 -1
  4. package/src/api/AstraeusScene.d.ts +4 -2
  5. package/src/api/AstraeusScene.js +13 -10
  6. package/src/api/AstraeusScene.node.js +13 -10
  7. package/src/api/errors.d.ts +1 -1
  8. package/src/api/index.d.ts +1 -0
  9. package/src/api/mount.d.ts +5 -1
  10. package/src/api/mount.js +2 -0
  11. package/src/api/mount.node.js +2 -0
  12. package/src/api/pathProvenance.d.ts +15 -6
  13. package/src/api/pathProvenance.js +23 -11
  14. package/src/api/scene.d.ts +18 -1
  15. package/src/api/scene.js +88 -10
  16. package/src/api/sphereOfInfluence.d.ts +20 -0
  17. package/src/api/sphereOfInfluence.js +48 -0
  18. package/src/api/viewerLink.d.ts +7 -1
  19. package/src/api/viewerLink.js +13 -2
  20. package/src/api/views.d.ts +42 -0
  21. package/src/api/views.js +80 -0
  22. package/src/app/App.js +32 -5
  23. package/src/app/App.node.js +32 -5
  24. package/src/app/AstraeusScene.d.ts +3 -0
  25. package/src/app/CameraController.d.ts +6 -0
  26. package/src/app/CameraController.js +3 -1
  27. package/src/app/StoryMarkers.d.ts +4 -1
  28. package/src/app/StoryMarkers.js +3 -2
  29. package/src/app/TrackedBodyView.d.ts +1 -1
  30. package/src/app/TrackedBodyView.js +20 -11
  31. package/src/app/experienceDefinition.d.ts +3 -0
  32. package/src/app/mission.d.ts +15 -2
  33. package/src/app/mission.js +15 -0
  34. package/src/app/sceneCamera.d.ts +2 -0
  35. package/src/app/sceneCamera.js +14 -0
  36. package/src/app/sceneFrame.d.ts +2 -0
  37. package/src/app/sceneFrame.js +42 -6
  38. package/src/app/viewHiding.d.ts +13 -0
  39. package/src/app/viewHiding.js +37 -0
  40. package/src/app/viewerPort.d.ts +6 -0
  41. package/src/app/views.d.ts +31 -0
  42. package/src/app/views.js +2 -0
  43. package/src/shell/AstraeusShell.d.ts +12 -2
  44. package/src/shell/AstraeusShell.js +42 -4
  45. package/src/shell/AstraeusShell.node.js +42 -4
  46. package/src/shell/DisplaySwitches.d.ts +18 -1
  47. package/src/shell/DisplaySwitches.js +18 -5
  48. package/src/shell/TimelineBar.css +18 -0
  49. package/src/shell/TimelineBar.js +29 -4
  50. package/src/shell/TimelineBar.node.js +29 -4
  51. package/src/shell/TopBar.d.ts +4 -2
  52. package/src/shell/TopBar.js +3 -3
  53. package/src/shell/TopBar.node.js +3 -3
  54. package/src/shell/timelineModel.d.ts +13 -0
  55. package/src/shell/timelineModel.js +25 -0
  56. package/src/shell/viewCamera.d.ts +4 -0
  57. package/src/shell/viewCamera.js +13 -0
  58. package/src/synthetic/syntheticJourneyScene.js +11 -1
  59. package/src/synthetic/syntheticViewsDefinition.d.ts +6 -0
  60. package/src/synthetic/syntheticViewsDefinition.js +44 -0
package/CHANGELOG.md CHANGED
@@ -2,6 +2,22 @@
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.7.0 (2026-11-01)
6
+
7
+ First download of the packed example (`npm run measure:example`): 1,652,632 bytes raw, 472,929 bytes gzip (code and styles loaded on first open).
8
+
9
+ A probe followed as one path, close timeline markers each reachable, the picture-pack moon list documented (O-050), and views of one scene switched inside the viewer (O-051), from the fourth round of findings sent back by the outside interplanetary probe app built on 0.6.0 (G-014).
10
+
11
+ - Views of one scene (O-051 T-218, I-124, API half), no existing call changes. New `Scene.setViews([{ id, label, paths?, bodies?, events?, panels?, camera? }], { place, start? })` names views, each listing the paths, bodies, events and story panels it shows; anything no view names shows in every view. `toDefinition` resolves each view's membership once into `definition.views`. A bad list, id, place, camera or start throws the new `bad-view` code. New exported types `ViewInput`, `ViewsOptions`, `ViewCameraInput`. The viewer does not switch views yet (next steps). A scene without views is unchanged.
12
+ - The viewer shows the view choice (O-051 T-219, I-124, viewer half): one button per view in the top bar, or a row each in the switch panel, and in the phone drawer, the opening view pressed. Choosing a view hides the other views' paths, bodies, labels, picking targets, timeline events, story panels and story markers at once, from one hidden-id set the frame reads; nothing is rebuilt, and time, speed and playing state carry over. An object the view hides is dropped from the object menu, and a selection or follow on it is dropped, with the camera handled by the per-view camera rule of the next entry. A scene without views is unchanged. The per-view camera rule and the host's `setView` follow in the next entry.
13
+ - Each view steers the camera and the host picks the view (O-051 T-220, I-124, camera and host half). When a switch takes away the object the camera follows or focuses on, the new view's `camera` rule decides: `"stay"` (default) holds the camera where it is (target fixed in the scene, pose kept), stops following and closes that object's card; `"start"` takes the scene's opening framing; `{ follow: id }` / `{ focus: id }` takes that framing. A followed object still in the view is left alone. New `MountedScene.view` and `setView(id)` (unknown id or no views: `bad-view`; before `ready` or after `unmount`: `missing-data`), `AstraeusScene` prop `view`, and `ViewerChange.view` (only in a scene with views; `cause` `visitor` for the buttons, `host` for `setView`). A scene without views is unchanged.
14
+ - Proof on the packed package (O-051 T-221, I-124): `npm run check:node-consumer` builds three views on two made-up probe paths and a shared body from the packed package and asserts the resolved views, `start`, camera rules and every `bad-view` fault; the made-up `synthetic-views` scene is switched by a visitor and by a host `setView` at 1280x720 and 375x667, and the "stay" rule holds the camera still while the clock runs, checked by `npm run check:browser`.
15
+ - `addTrajectory`'s `lineFixedTo` also takes a list of `{ start, end, body }` stretches (O-050 T-213, I-125): each stretch of the line is drawn against its own body, so a flyby (Sun-fixed cruise, planet-fixed encounter, Sun-fixed cruise) is one path with one menu entry and card. Same span rules as `provenanceSpans`; a fault throws `bad-trajectory` naming the index. A single body id behaves as before.
16
+ - `lineFixedTo: "auto"` (O-050 T-216, I-125): the stretches are picked from the path's own samples. Each sample is fixed to the innermost scene body whose sphere of influence (`a (m / M)^(2/5)`, GMs from the catalogue) holds the probe, else the scene centre, so any flyby or orbiter is one path without working out switch times. Resolved once at mount or `prepare`; a body without a catalogue GM is skipped.
17
+ - Close timeline markers stay reachable (O-050 T-214, I-126): events, story panels and window peaks that sit under 22 px apart on the measured track gather into one numbered mark whose list opens each member as a full-size button; nothing gathers until the track has a measured width.
18
+ - Proof on the packed package (O-050 T-217, I-125 to I-127): `npm run check:node-consumer` builds a listed-stretch path, a `"auto"` path and a Moon-orbit path and asserts one menu object per path and the resolved stretches; the made-up synthetic journey draws its traveller against the Sun, Jupiter and the Sun again and adds three moon passes within nine hours of Jupiter's, checked by `npm run check:browser` (the camera stays on the traveller across both stretch boundaries; each gathered marker opens its own event at 1280x720 and 375x667).
19
+ - First download of the packed example (`node tools/measure-example.mjs`, after `npm run build`): 1,652,632 bytes raw, 472,929 bytes gzip at release, against 1,638,245 raw and 468,717 gzip at 0.6.0 (+14,387 raw, +4,212 gzip: the stretch drawing, sphere-of-influence resolver and marker grouping, +5,956 raw and +1,752 gzip as measured after O-050; the views, the view choice, the hide stage and the camera hold add +8,387 raw and +2,426 gzip, measured after O-051 T-221; the I-129 repair adds +44 raw and +34 gzip).
20
+
5
21
  ## 0.6.0 (2026-11-01)
6
22
 
7
23
  First download of the packed example (`npm run measure:example`): 1,638,245 bytes raw, 468,717 bytes gzip (code and styles loaded on first open).
package/README.md CHANGED
@@ -67,7 +67,7 @@ scene.camera.fitOrbit(mars);
67
67
  mount(document.getElementById("app"), scene);
68
68
  ```
69
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`, and a made-up 1977-to-170-AU journey past Jupiter and Saturn (moons at their dates, paced playback, provenance by stretch) at `?experience=synthetic-journey`.
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 (`lineFixedTo: "auto"` picks the Sun or a planet for each stretch from the path's own samples, or give a list such as `[{ start, end, body: "earth" }]`); `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`, and a made-up 1977-to-170-AU journey past Jupiter and Saturn (moons at their dates, paced playback, provenance by stretch) at `?experience=synthetic-journey`.
71
71
 
72
72
  ## The public API
73
73
 
@@ -76,8 +76,8 @@ The full reference, generated from the types and doc comments, is at <https://as
76
76
  | Call | What it does |
77
77
  |---|---|
78
78
  | `new Scene()` | An empty scene. Every method below returns the scene, so calls chain. |
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; every moon in the moon lists is also taken by its id (`addBody("miranda")` with `astraeus-data-uranus` passed to `mount`) as a grey sphere at its mean radius, and `listedMoons(planet?)` names them with the data package each needs (`requires`). The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line: any catalogued moon with a period in its data (every listed moon but those the list gives no period for, and `moon`, `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`) about its planet, one lap of that period (the planet must be in the scene; `phobos`, `deimos` and any moon with no period throw `no-orbit`), or, with `sun` in the scene, one turn round the Sun of any body that circles it (the planets, Earth's year, a body from `addBodyFromElements`), from the opening time: one full turn of the body's own positions where they cover a whole turn, else (Uranus and Neptune, whose turn outlasts the planet series) the two-body ellipse osculating at the opening time, which the info card says; anything else throws `no-orbit`. `camera.fitOrbit` follows the same rule. `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`. Jupiter, Saturn, Uranus and Neptune are drawn with their rings (bands at the NASA NSSDC ring fact sheet radii) whenever you add them; Mercury, Venus, Earth, Mars and Pluto have none. |
80
- | `scene.addTrajectory({ id, label?, color?, center?, plane?, lineFixedTo?, labelReach?, samples, provenance?, provenanceSpans?, 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. `provenanceSpans` (a list of `{ start, end, provenance }`, sorted, not overlapping, inside the path) gives each stretch its own provenance, shown with the path as time moves (as an activity's `provenance`); where no span covers the time, `provenance` (or the illustrative default) shows; a fault throws `bad-trajectory` naming the index. |
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; every moon in the moon lists is also taken by its id (`addBody("miranda")` with `astraeus-data-uranus` passed to `mount`) as a grey sphere at its mean radius, and `listedMoons(planet?)` names them with the data package each needs (`requires`). Moons with pictures: Io, Europa, Ganymede, Callisto, Mimas, Enceladus, Tethys, Dione, Rhea, Titan, Iapetus, Triton and Charon. Every other listed moon, among them Uranus's Miranda, Ariel, Umbriel, Titania and Oberon, draws flat-coloured with this package loaded. The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line: any catalogued moon with a period in its data (every listed moon but those the list gives no period for, and `moon`, `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`) about its planet, one lap of that period (the planet must be in the scene; `phobos`, `deimos` and any moon with no period throw `no-orbit`), or, with `sun` in the scene, one turn round the Sun of any body that circles it (the planets, Earth's year, a body from `addBodyFromElements`), from the opening time: one full turn of the body's own positions where they cover a whole turn, else (Uranus and Neptune, whose turn outlasts the planet series) the two-body ellipse osculating at the opening time, which the info card says; anything else throws `no-orbit`. `camera.fitOrbit` follows the same rule. `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`. Jupiter, Saturn, Uranus and Neptune are drawn with their rings (bands at the NASA NSSDC ring fact sheet radii) whenever you add them; Mercury, Venus, Earth, Mars and Pluto have none. |
80
+ | `scene.addTrajectory({ id, label?, color?, center?, plane?, lineFixedTo?, labelReach?, samples, provenance?, provenanceSpans?, 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`; a list of `{ start, end, body }` (sorted, not overlapping, inside the path, times as in `provenanceSpans`) draws each stretch against its own body, so a flyby (Sun-fixed cruise, planet-fixed encounter, Sun-fixed cruise) is one path with one menu entry and card, time outside every stretch is drawn against the scene centre, and a fault throws `bad-trajectory` naming the index; `lineFixedTo: "auto"` builds that list from the path's own samples, once, when the planet series are in: each sample is fixed to the innermost body in the scene whose sphere of influence (`a (m / M)^(2/5)`, `a` its distance from its parent, GMs from the catalogue; the Sun holds everything) holds the probe, else the scene centre, consecutive samples on one body merging; a body with no catalogue GM (the built-in comet, every moon added only by id) is skipped, and `"auto"` is not usable as a body id; `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. `provenanceSpans` (a list of `{ start, end, provenance }`, sorted, not overlapping, inside the path) gives each stretch its own provenance, shown with the path as time moves (as an activity's `provenance`); where no span covers the time, `provenance` (or the illustrative default) shows; a fault throws `bad-trajectory` naming the index. |
81
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
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`. |
83
83
  | `scene.setTime(time)` | The moment the scene opens at. |
@@ -89,12 +89,13 @@ The full reference, generated from the types and doc comments, is at <https://as
89
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`. Without `setReach` or `fitOrbit`, a Sun-centred scene with a path about the Sun widens its farthest zoom-out to fit that path whole (twice its farthest Sun distance, for the live canvas shape), so a path out to 170 AU can be seen entire. The object the scene opens on (`camera.follow` or `camera.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
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")` |
91
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`. |
92
+ | `scene.setViews(views, { place, start? })` | Names views of one scene: each `{ id, label, paths?, bodies?, events?, panels?, camera? }` lists the `addTrajectory` ids, `addBody`/`addGroup` ids, `addEvents` ids and `addStoryPanels` ids it shows. Anything no view names shows in every view; anything named shows only in the views that name it. `place` is `"top-bar"` or `"panel"`; `start` is the opening view (default the first). `camera` is `"stay"` (default), `"start"` or `{ follow: id }` / `{ focus: id }` (the object must be in the view). The rule applies only when switching to the view takes away the object the camera follows or focuses on: `"stay"` holds the camera where it is (its target fixed in the scene, so it does not move on with the hidden object), stops following and closes that object's card; `"start"` takes the scene's opening framing; `{ follow: id }` / `{ focus: id }` follows or focuses that object. A followed object still in the new view leaves the camera alone. Read and set the view from `mount` or `AstraeusScene` ("Views from the host page"). Presentation only: State is unchanged. An empty list, a repeated id, a bad place, camera or `start` throws `bad-view` at the call; an unknown id or a camera target the view hides throws `bad-view` when the scene is built. |
92
93
  | `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
94
  | `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. |
94
95
  | `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. |
95
96
  | `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. |
96
- | `mount(element, scene, { data?, onChange? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), time, rate, setTime(t), setRate(r), onChange(fn) }`. `data` is a list of data packages (below); the time and speed members are described under "Reading and setting the time". |
97
- | `<AstraeusScene scene data? onReady? onError? time? rate? onChange? />` | The same viewer as a React component (below). |
97
+ | `mount(element, scene, { data?, onChange? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), time, rate, view, setTime(t), setRate(r), setView(id), onChange(fn) }`. `data` is a list of data packages (below); the time and speed members are described under "Reading and setting the time". |
98
+ | `<AstraeusScene scene data? onReady? onError? time? rate? view? onChange? />` | The same viewer as a React component (below). |
98
99
  | `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. |
99
100
 
100
101
  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):
@@ -127,15 +128,17 @@ Props: `scene`, `data` (as for `mount`), `onReady`, `onError` (a bad scene or fa
127
128
 
128
129
  ## Reading and setting the time
129
130
 
130
- The viewer has one clock. A host page reads it, moves it and hears about changes, from the `mount` handle or from `AstraeusScene` props. Time is Unix milliseconds UTC; speed is simulated seconds per real second.
131
+ The viewer has one clock (and, with `setViews`, one current view: rows below). A host page reads it, moves it and hears about changes, from the `mount` handle or from `AstraeusScene` props. Time is Unix milliseconds UTC; speed is simulated seconds per real second.
131
132
 
132
133
  | Name | What it does |
133
134
  |------|--------------|
134
135
  | `handle.time`, `handle.rate` | The clock now. `undefined` until `ready` has resolved and after `unmount`. |
135
136
  | `handle.setTime(time)` | Moves the viewer to `time` (ISO text, a `Date` or milliseconds). Outside the timeline throws `bad-time`. Before `ready` or after `unmount` throws `missing-data`. |
136
137
  | `handle.setRate(rate)` | Sets the speed to one the timeline offers (`setTimeline({ rates })`). Any other number throws `bad-timeline`: the speed menu always shows what is running, so a custom speed is refused, not added. `handle.setRate("auto")` hands the speed back to the scene's pacing (below); without pacing it throws `bad-timeline`. |
137
- | `handle.onChange(fn)` or `mount(..., { onChange })` | `fn({ time, rate, playing, cause })` on every change; returns a function that stops it. `cause` is `playback` (the clock ran on; about ten calls a second while playing), `visitor` (someone used the timeline) or `host` (your own `setTime` or `setRate`). Nothing arrives after `unmount`. |
138
+ | `handle.onChange(fn)` or `mount(..., { onChange })` | `fn({ time, rate, playing, view?, cause })` on every change (`view` only in a scene with views); returns a function that stops it. `cause` is `playback` (the clock ran on; about ten calls a second while playing), `visitor` (someone used the timeline) or `host` (your own `setTime`, `setRate` or `setView`). Nothing arrives after `unmount`. |
138
139
  | `<AstraeusScene time rate onChange />` | `time` and `rate` are applied once the viewer is drawn and again whenever their value changes (a new `Date` of the same moment does not seek again); they are not controlled values, so read the live time from `onChange`. A bad one goes to `onError`. |
140
+ | `handle.view`, `handle.setView(id)` | The id of the view showing (`setViews`), and a switch to another, as if a visitor pressed its button: the same camera rule applies. `view` is `undefined` until `ready`, after `unmount`, and in a scene without views. `setView` with an unknown id, or on a scene without views, throws `bad-view`; before `ready` or after `unmount`, `missing-data`. `onChange` hears it with `cause: "host"` (a visitor's own choice is `"visitor"`). |
141
+ | `<AstraeusScene view />` | Switches to that view once drawn and whenever it changes; not a controlled value (a visitor can switch too), so read the live view from `onChange`. An unknown id goes to `onError` as `bad-view`. |
139
142
 
140
143
  ```ts
141
144
  const mounted = mount(el, scene);
@@ -149,6 +152,26 @@ const stop = mounted.onChange(({ time, cause }) => {
149
152
 
150
153
  The speed menu shows exactly the `rates` the scene gives (`setTimeline({ rates })`) and no others.
151
154
 
155
+ ### Views of one scene
156
+
157
+ Two probes, one shared Earth, three views that keep the clock, the speed and the camera's distance when you switch (the Object list, timeline events, story panels, markers and paths follow the chosen view):
158
+
159
+ ```ts
160
+ const scene = new Scene()
161
+ .addBody(earth)
162
+ .addTrajectory({ id: "probe-a", label: "Probe A", samples: samplesA })
163
+ .addTrajectory({ id: "probe-b", label: "Probe B", samples: samplesB })
164
+ .addEvents([{ id: "a-burn", label: "A burn", time: t0 + HOUR }, { id: "b-burn", label: "B burn", time: t0 + 2 * HOUR }])
165
+ .setViews([
166
+ { id: "a", label: "Probe A", paths: ["probe-a"], events: ["a-burn"], camera: "stay" }, // the camera holds where it is
167
+ { id: "b", label: "Probe B", paths: ["probe-b"], events: ["b-burn"], camera: { follow: "probe-b" } },
168
+ { id: "both", label: "Both", paths: ["probe-a", "probe-b"], events: ["a-burn", "b-burn"] },
169
+ ], { place: "top-bar" });
170
+ const mounted = mount(el, scene);
171
+ await mounted.ready;
172
+ mounted.setView("b"); // as if the visitor pressed Probe B; onChange hears cause "host"
173
+ ```
174
+
152
175
  ### Paced playback
153
176
 
154
177
  A long journey wants fast cruising and slow encounters. `setTimeline` takes `pacing`, a list of pieces; outside every piece playback runs at the timeline's `rate`.
@@ -197,7 +220,7 @@ window.addEventListener("vite:preloadError", () => window.location.reload());
197
220
 
198
221
  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.
199
222
 
200
- First download: the packed `examples/hello-scene` loads 1,638,245 bytes (468,717 gzip) of code and styles, measured at this commit on first open (`npm run measure:example`; pictures and data files are not counted).
223
+ First download: the packed `examples/hello-scene` loads 1,652,632 bytes (472,929 gzip) of code and styles, measured at this commit on first open (`npm run measure:example`; pictures and data files are not counted).
201
224
 
202
225
  ## What `astraeus-data` adds
203
226
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "astraeus",
3
- "version": "0.6.0",
3
+ "version": "0.7.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",
@@ -17,7 +17,9 @@ export interface AstraeusSceneProps {
17
17
  readonly time?: TimeInput;
18
18
  /** Sets the playback speed once drawn and whenever it changes; must be one of the speeds the timeline offers (or `"auto"`, to hand it back to the scene's pacing), else `bad-timeline` goes to `onError`. */
19
19
  readonly rate?: number | "auto";
20
- /** Called whenever the viewer's time, speed or playing state changes: playback running, a visitor using the timeline, or the `time` / `rate` props. About ten times a second while playing. */
20
+ /** Switches to this view (an id from `setViews`) once drawn, and again whenever it changes. Not a controlled value: a visitor can switch too, and the view showing arrives through `onChange`. An unknown id, or a scene without views, reports `bad-view` to `onError`. */
21
+ readonly view?: string;
22
+ /** Called whenever the viewer's time, speed, playing state or view changes: playback running, a visitor using the timeline or the view choice, or the `time` / `rate` / `view` props. About ten times a second while playing. */
21
23
  readonly onChange?: (change: ViewerChange) => void;
22
24
  /** Class for the wrapper element, which fills its parent's width and height unless `style` says otherwise. */
23
25
  readonly className?: string;
@@ -32,4 +34,4 @@ export interface AstraeusSceneProps {
32
34
  * return <div style={{ height: "100vh" }}><AstraeusScene scene={scene} onError={console.error} /></div>;
33
35
  * }
34
36
  */
35
- export declare function AstraeusScene({ scene, data, onReady, onError, time, rate, onChange, className, style }: AstraeusSceneProps): ReactElement;
37
+ export declare function AstraeusScene({ scene, data, onReady, onError, time, rate, view, onChange, className, style }: AstraeusSceneProps): ReactElement;
@@ -14,7 +14,7 @@ const asError = (cause) => (cause instanceof Error ? cause : new Error(String(ca
14
14
  * return <div style={{ height: "100vh" }}><AstraeusScene scene={scene} onError={console.error} /></div>;
15
15
  * }
16
16
  */
17
- export function AstraeusScene({ scene, data, onReady, onError, time, rate, onChange, className, style }) {
17
+ export function AstraeusScene({ scene, data, onReady, onError, time, rate, view, onChange, className, style }) {
18
18
  const [definition, setDefinition] = useState();
19
19
  // The latest data and callbacks, read when the scene is built, so a new array or arrow function each render does not rebuild it.
20
20
  const latest = useRef({ data, onReady, onError, onChange });
@@ -26,20 +26,23 @@ export function AstraeusScene({ scene, data, onReady, onError, time, rate, onCha
26
26
  }, [link]);
27
27
  // A Date made fresh each render must not seek again, so the moment is compared by value.
28
28
  const timeKey = time instanceof Date ? time.getTime() : time;
29
- // After the viewer is drawn (its own effects have attached the clock by now), the props take effect.
30
- useEffect(() => {
31
- if (definition === undefined)
32
- return;
29
+ // After the viewer is drawn (its own effects have attached the clock by now), each prop takes effect on its own: once when drawn,
30
+ // then only when that prop changes, so a host change to one never overrides a visitor's later choice of another control.
31
+ const apply = (set) => {
33
32
  try {
34
- if (timeKey !== undefined)
35
- link.setTime(timeKey);
36
- if (rate !== undefined)
37
- link.setRate(rate);
33
+ set();
38
34
  }
39
35
  catch (cause) {
40
36
  latest.current.onError?.(asError(cause));
41
37
  }
42
- }, [definition, link, timeKey, rate]);
38
+ };
39
+ const drawn = definition !== undefined;
40
+ useEffect(() => { if (drawn && timeKey !== undefined)
41
+ apply(() => link.setTime(timeKey)); }, [drawn, link, timeKey]); // eslint-disable-line react-hooks/exhaustive-deps
42
+ useEffect(() => { if (drawn && rate !== undefined)
43
+ apply(() => link.setRate(rate)); }, [drawn, link, rate]); // eslint-disable-line react-hooks/exhaustive-deps
44
+ useEffect(() => { if (drawn && view !== undefined)
45
+ apply(() => link.setView(view)); }, [drawn, link, view]); // eslint-disable-line react-hooks/exhaustive-deps
43
46
  useEffect(() => {
44
47
  let open = true;
45
48
  setDefinition(undefined);
@@ -13,7 +13,7 @@ const asError = (cause) => (cause instanceof Error ? cause : new Error(String(ca
13
13
  * return <div style={{ height: "100vh" }}><AstraeusScene scene={scene} onError={console.error} /></div>;
14
14
  * }
15
15
  */
16
- export function AstraeusScene({ scene, data, onReady, onError, time, rate, onChange, className, style }) {
16
+ export function AstraeusScene({ scene, data, onReady, onError, time, rate, view, onChange, className, style }) {
17
17
  const [definition, setDefinition] = useState();
18
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
19
  const latest = useRef({ data, onReady, onError, onChange });
@@ -25,20 +25,23 @@ export function AstraeusScene({ scene, data, onReady, onError, time, rate, onCha
25
25
  }, [link]);
26
26
  // A Date made fresh each render must not seek again, so the moment is compared by value.
27
27
  const timeKey = time instanceof Date ? time.getTime() : time;
28
- // After the viewer is drawn (its own effects have attached the clock by now), the props take effect.
29
- useEffect(() => {
30
- if (definition === undefined)
31
- return;
28
+ // After the viewer is drawn (its own effects have attached the clock by now), each prop takes effect on its own: once when drawn,
29
+ // then only when that prop changes, so a host change to one never overrides a visitor's later choice of another control.
30
+ const apply = (set) => {
32
31
  try {
33
- if (timeKey !== undefined)
34
- link.setTime(timeKey);
35
- if (rate !== undefined)
36
- link.setRate(rate);
32
+ set();
37
33
  }
38
34
  catch (cause) {
39
35
  latest.current.onError?.(asError(cause));
40
36
  }
41
- }, [definition, link, timeKey, rate]);
37
+ };
38
+ const drawn = definition !== undefined;
39
+ useEffect(() => { if (drawn && timeKey !== undefined)
40
+ apply(() => link.setTime(timeKey)); }, [drawn, link, timeKey]); // eslint-disable-line react-hooks/exhaustive-deps
41
+ useEffect(() => { if (drawn && rate !== undefined)
42
+ apply(() => link.setRate(rate)); }, [drawn, link, rate]); // eslint-disable-line react-hooks/exhaustive-deps
43
+ useEffect(() => { if (drawn && view !== undefined)
44
+ apply(() => link.setView(view)); }, [drawn, link, view]); // eslint-disable-line react-hooks/exhaustive-deps
42
45
  useEffect(() => {
43
46
  let open = true;
44
47
  setDefinition(undefined);
@@ -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" | "out-of-span" | "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";
2
+ export type SceneErrorCode = "unknown-body" | "duplicate-id" | "bad-time" | "bad-trajectory" | "bad-scale" | "missing-data" | "out-of-span" | "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" | "bad-view";
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;
@@ -1,6 +1,7 @@
1
1
  export { Scene, SceneCamera, type AddBodyOptions, type AnchorInput, type ReadoutInput, type DataSource, type MoonPositions, type FollowView, type GroupInput, type GroupOrbitInput, type GroupClumpInput, type GroupReadoutInput, type ActivityInput, type ActivitySampleInput, type ActivitySourceInput, type ElementsBodyRecord, type TimeInput, type TrajectoryInput, type TrajectorySampleInput } from "./scene.js";
2
2
  export { type EventInput, type AddEventsOptions, type TimelineInput, type PacingInput, type StoryPanelsInput } from "./story.js";
3
3
  export { type SwitchesInput } from "./switches.js";
4
+ export { type ViewsOptions, type ViewInput, type ViewCameraInput } from "./views.js";
4
5
  export { mount, type MountOptions, type MountedScene } from "./mount.js";
5
6
  export { AstraeusScene, type AstraeusSceneProps } from "./AstraeusScene.js";
6
7
  export { type ViewerChange, type RateSource } from "./viewerLink.js";
@@ -6,7 +6,7 @@ import { type ViewerChange } from "./viewerLink.js";
6
6
  export interface MountOptions {
7
7
  /** Data packages the scene's bodies need, such as moon pictures or positions; nothing is looked up behind the caller's back. */
8
8
  readonly data?: readonly DataSource[];
9
- /** Called whenever the viewer's time, speed or playing state changes: playback running, a visitor using the timeline, or the host's own `setTime` / `setRate`. About ten times a second while playing. */
9
+ /** Called whenever the viewer's time, speed or playing state changes: playback running, a visitor using the timeline, or the host's own `setTime` / `setRate` / `setView`. About ten times a second while playing. */
10
10
  readonly onChange?: (change: ViewerChange) => void;
11
11
  }
12
12
  /** What `mount` returns. */
@@ -19,10 +19,14 @@ export interface MountedScene {
19
19
  readonly time: number | undefined;
20
20
  /** The playback speed (simulated seconds per real second); undefined like `time`. */
21
21
  readonly rate: number | undefined;
22
+ /** The id of the view showing; undefined until `ready` has resolved, after `unmount`, and in a scene without views. */
23
+ readonly view: string | undefined;
22
24
  /** Moves the viewer to `time` (ISO text, a `Date` or Unix milliseconds). Outside the timeline throws `bad-time`; before `ready` or after `unmount` throws `missing-data`. */
23
25
  setTime(time: TimeInput): void;
24
26
  /** Sets the playback speed to one of the speeds the timeline offers (`setTimeline({ rates })`); any other number throws `bad-timeline`. `"auto"` gives the speed back to the scene's `setTimeline({ pacing })` (throws `bad-timeline` when it has none). Before `ready` or after `unmount` throws `missing-data`. */
25
27
  setRate(rate: number | "auto"): void;
28
+ /** Switches to the view with this id (`setViews`). An unknown id, or a scene without views, throws `bad-view`; before `ready` or after `unmount` throws `missing-data`. `onChange` hears it with `cause: "host"`. */
29
+ setView(id: string): void;
26
30
  /** Calls `listener` on every change (see `MountOptions.onChange`); returns the function that stops it. No callbacks arrive after `unmount`. */
27
31
  onChange(listener: (change: ViewerChange) => void): () => void;
28
32
  }
package/src/api/mount.js CHANGED
@@ -35,6 +35,8 @@ export function mount(element, scene, options = {}) {
35
35
  ready,
36
36
  get time() { return link.time; },
37
37
  get rate() { return link.rate; },
38
+ get view() { return link.view; },
39
+ setView: (id) => link.setView(id),
38
40
  setTime: (time) => link.setTime(time),
39
41
  setRate: (rate) => link.setRate(rate),
40
42
  onChange: (listener) => link.onChange(listener),
@@ -34,6 +34,8 @@ export function mount(element, scene, options = {}) {
34
34
  ready,
35
35
  get time() { return link.time; },
36
36
  get rate() { return link.rate; },
37
+ get view() { return link.view; },
38
+ setView: (id) => link.setView(id),
37
39
  setTime: (time) => link.setTime(time),
38
40
  setRate: (rate) => link.setRate(rate),
39
41
  onChange: (listener) => link.onChange(listener),
@@ -1,10 +1,19 @@
1
1
  import type { WindowProvenanceSpan } from "../core/timeWindow.js";
2
2
  import type { ActivitySourceInput } from "./activity.js";
3
- /**
4
- * Checks a path's provenance by time span (the same `{ start, end, provenance }` shape as an activity's) and returns it in milliseconds.
5
- * Spans are sorted, do not overlap and lie inside the path's bounds; any fault is a `bad-trajectory` naming the path and the span's index.
6
- */
7
- export declare function planPathProvenance(id: string, spans: readonly ActivitySourceInput[], boundsUtcMs: {
3
+ import { type TimeInput } from "./time.js";
4
+ import type { LineStretch } from "../app/mission.js";
5
+ interface Bounds {
8
6
  readonly startUtcMs: number;
9
7
  readonly endUtcMs: number;
10
- }): readonly WindowProvenanceSpan[];
8
+ }
9
+ /** Checks a path's provenance by time span (the same `{ start, end, provenance }` shape as an activity's) and returns it in milliseconds. */
10
+ export declare function planPathProvenance(id: string, spans: readonly ActivitySourceInput[], boundsUtcMs: Bounds): readonly WindowProvenanceSpan[];
11
+ /** One stretch of a path's line and the body it is drawn against, as the caller gives it. */
12
+ export interface LineStretchInput {
13
+ readonly start: TimeInput;
14
+ readonly end: TimeInput;
15
+ readonly body: string;
16
+ }
17
+ /** Checks a path's `lineFixedTo` list (same span rules as `provenanceSpans`) and returns it in milliseconds. */
18
+ export declare function planLineStretches(id: string, stretches: readonly LineStretchInput[], boundsUtcMs: Bounds): readonly LineStretch[];
19
+ export {};
@@ -2,33 +2,45 @@ import { createProvenance } from "../core/provenance.js";
2
2
  import { SceneError } from "./errors.js";
3
3
  import { toUtcMs } from "./time.js";
4
4
  /**
5
- * Checks a path's provenance by time span (the same `{ start, end, provenance }` shape as an activity's) and returns it in milliseconds.
6
- * Spans are sorted, do not overlap and lie inside the path's bounds; any fault is a `bad-trajectory` naming the path and the span's index.
5
+ * The shared plan for a path's time-span lists (`provenanceSpans`, `lineFixedTo`): each span's `start` and `end` are read to milliseconds, `read` builds the item from the span,
6
+ * and the list must be sorted, not overlap and lie inside `bounds`. Any fault is a `bad-trajectory` naming the path, the field and the index.
7
7
  */
8
- export function planPathProvenance(id, spans, boundsUtcMs) {
9
- const bad = (index, message) => new SceneError("bad-trajectory", `addTrajectory("${id}"): provenanceSpans[${index}] ${message}`);
8
+ function planSpans(id, field, spans, bounds, read) {
9
+ const bad = (index, message) => new SceneError("bad-trajectory", `addTrajectory("${id}"): ${field}[${index}] ${message}`);
10
10
  if (!Array.isArray(spans))
11
- throw new SceneError("bad-trajectory", `addTrajectory("${id}"): provenanceSpans must be a list`);
11
+ throw new SceneError("bad-trajectory", `addTrajectory("${id}"): ${field} must be a list`);
12
12
  let previousEnd = -Infinity;
13
13
  return spans.map((span, index) => {
14
14
  let startUtcMs;
15
15
  let endUtcMs;
16
- let provenance;
16
+ let item;
17
17
  try {
18
- startUtcMs = toUtcMs(span?.start, `addTrajectory("${id}") provenanceSpans[${index}] start`);
19
- endUtcMs = toUtcMs(span?.end, `addTrajectory("${id}") provenanceSpans[${index}] end`);
20
- provenance = createProvenance(span?.provenance);
18
+ startUtcMs = toUtcMs(span?.start, `addTrajectory("${id}") ${field}[${index}] start`);
19
+ endUtcMs = toUtcMs(span?.end, `addTrajectory("${id}") ${field}[${index}] end`);
20
+ item = read(span);
21
21
  }
22
22
  catch (error) {
23
23
  throw bad(index, error instanceof Error ? error.message : String(error));
24
24
  }
25
25
  if (endUtcMs <= startUtcMs)
26
26
  throw bad(index, "must end after it starts");
27
- if (startUtcMs < boundsUtcMs.startUtcMs || endUtcMs > boundsUtcMs.endUtcMs)
27
+ if (startUtcMs < bounds.startUtcMs || endUtcMs > bounds.endUtcMs)
28
28
  throw bad(index, "lies outside the path");
29
29
  if (startUtcMs < previousEnd)
30
30
  throw bad(index, "overlaps or is out of order; spans must be sorted and not overlap");
31
31
  previousEnd = endUtcMs;
32
- return { startUtcMs, endUtcMs, provenance };
32
+ return { ...item, startUtcMs, endUtcMs };
33
+ });
34
+ }
35
+ /** Checks a path's provenance by time span (the same `{ start, end, provenance }` shape as an activity's) and returns it in milliseconds. */
36
+ export function planPathProvenance(id, spans, boundsUtcMs) {
37
+ return planSpans(id, "provenanceSpans", spans, boundsUtcMs, (span) => ({ provenance: createProvenance(span?.provenance) }));
38
+ }
39
+ /** Checks a path's `lineFixedTo` list (same span rules as `provenanceSpans`) and returns it in milliseconds. */
40
+ export function planLineStretches(id, stretches, boundsUtcMs) {
41
+ return planSpans(id, "lineFixedTo", stretches, boundsUtcMs, (stretch) => {
42
+ if (typeof stretch.body !== "string" || stretch.body === "")
43
+ throw new Error("body must be a body id");
44
+ return { body: stretch.body };
33
45
  });
34
46
  }
@@ -1,6 +1,7 @@
1
1
  import type { BodyId } from "../core/body.js";
2
2
  import { type Provenance } from "../core/provenance.js";
3
3
  import type { ActivitySourceInput } from "./activity.js";
4
+ import { type LineStretchInput } from "./pathProvenance.js";
4
5
  import { type ScalePolicy } from "../core/scalePolicy.js";
5
6
  import { type State } from "../core/state.js";
6
7
  import { type ElementsBodyRecord } from "../core/elementsBody.js";
@@ -14,6 +15,7 @@ export type { ActivityInput, ActivitySampleInput, ActivitySourceInput } from "./
14
15
  export type { DataSource, MoonPositions } from "./data.js";
15
16
  import { type TimeInput } from "./time.js";
16
17
  import { type SwitchesInput } from "./switches.js";
18
+ import { type ViewInput, type ViewsOptions } from "./views.js";
17
19
  import { type AddEventsOptions, type EventInput, type StoryPanelsInput, type TimelineInput } from "./story.js";
18
20
  export { toUtcMs, type TimeInput } from "./time.js";
19
21
  export type { ElementsBodyRecord } from "../core/elementsBody.js";
@@ -74,9 +76,14 @@ interface TrajectoryBase {
74
76
  /**
75
77
  * 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
76
78
  * 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.
79
+ * A list of `{ start, end, body }` (times as `provenanceSpans`) draws each stretch against its own body, so a flyby is one path: Sun-fixed cruise, planet-fixed encounter, Sun-fixed cruise.
80
+ * Sorted, not overlapping, inside the path's span; time outside every stretch is drawn against the scene centre. A fault throws `bad-trajectory` naming the index.
81
+ * `"auto"` builds that list from the path's own samples: each sample is fixed to the innermost body in the scene whose sphere of influence (`a (m / M)^(2/5)`, `a` the body's distance from its parent,
82
+ * GMs from the catalogue) holds the probe (a root body such as the Sun holds everything), else the scene centre; consecutive samples on one body merge. Resolved once when the planet series are in
83
+ * (at mount, or in `prepare`), never per frame. A body with no catalogue GM (most moons) is skipped. "auto" is reserved, so no body may carry that id.
77
84
  * Throws `bad-trajectory` at build if the scene does not hold the body.
78
85
  */
79
- readonly lineFixedTo?: BodyId;
86
+ readonly lineFixedTo?: BodyId | "auto" | readonly LineStretchInput[];
80
87
  /**
81
88
  * The frame the positions and velocities are given in, about `center`: "EQJ" (equatorial J2000, the default) or "ecliptic-j2000" (the vectors JPL Horizons
82
89
  * 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`.
@@ -218,6 +225,16 @@ export declare class Scene {
218
225
  * scene.setSwitches({ orbitLines: { place: "top-bar" }, labels: { place: "panel", on: false }, milkyWay: { place: "developer", on: false } });
219
226
  */
220
227
  setSwitches(switches: SwitchesInput): this;
228
+ /**
229
+ * Names views of this one scene, each listing what it shows: `paths` (ids of `addTrajectory`), `bodies` (ids of `addBody` or `addGroup`), `events` (ids of `addEvents`) and `panels` (ids of `addStoryPanels`).
230
+ * Anything no view names shows in every view (shared bodies such as the planets); anything a view names shows only in the views that name it. `place` is `"top-bar"` or `"panel"` (as for `setSwitches`);
231
+ * `start` is the opening view (default the first). `camera` says what happens when the followed or focused object is not in the view switched to: `"stay"` (default), `"start"` (the scene's start) or
232
+ * `{ follow: id }` / `{ focus: id }` (that framing; the object must be in the view). Presentation only: State is unchanged and a hidden object keeps its state. May be called again; the later call replaces the views.
233
+ * An empty list, a repeated view id, a bad place or camera, or a `start` that is not a view throws `bad-view` here; an id the scene does not hold, or a camera target the view does not show, throws `bad-view` when the scene is built (`mount`), so the call may come before or after the objects.
234
+ * @example
235
+ * scene.setViews([{ id: "a", label: "Probe A", paths: ["probe-a"] }, { id: "b", label: "Probe B", paths: ["probe-b"] }, { id: "both", label: "Both" }], { place: "top-bar" });
236
+ */
237
+ setViews(views: readonly ViewInput[], options: ViewsOptions): this;
221
238
  /**
222
239
  * 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;
223
240
  * 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