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/src/api/scene.js CHANGED
@@ -1,6 +1,10 @@
1
1
  import { createProvenance } from "../core/provenance.js";
2
2
  import { SampledTrajectory } from "../core/sampledTrajectory.js";
3
- import { readableScale, trueScale } from "../core/scalePolicy.js";
3
+ import { readableScale, solarSystemScale, trueScale } from "../core/scalePolicy.js";
4
+ import { createState } from "../core/state.js";
5
+ import { createOrbTwoBodyAdapter } from "../core/twoBodyAdapter.js";
6
+ import { createStateResolver } from "../core/stateResolver.js";
7
+ import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
4
8
  import { loadPlanetSeries, planetSeriesLoaded } from "../core/planetSeries.js";
5
9
  import { catalogue as builtInCatalogue, extendCatalogue, rootBodyId } from "../assets/catalogue.js";
6
10
  import { buildElementsBody, ElementsBodyError, parseElementsBodyRecord } from "../core/elementsBody.js";
@@ -10,34 +14,37 @@ import { bodyMetrics } from "../app/bodyMetrics.js";
10
14
  import { needsPlanetSeries } from "../app/planetNeeds.js";
11
15
  import { catalogueItem } from "../app/catalogueItem.js";
12
16
  import { createReadoutMetrics } from "../app/trackedMetrics.js";
13
- import { circlesTheSun, sunOrbitIdOf, sunOrbitLayer } from "./sunOrbit.js";
14
- import { readyMade } from "./bodies.js";
17
+ import { circlesTheSun, farthestSunDistanceKm, sunOrbitIdOf, sunOrbitLayer } from "./sunOrbit.js";
18
+ import { FALLBACK_SCENE_CENTRE, readyMade } from "./bodies.js";
15
19
  import { installData } from "./data.js";
16
20
  import { planActivity, rateMetricOf } from "./activity.js";
17
21
  import { buildGroupLayer, planGroup } from "./group.js";
18
22
  import { SceneError } from "./errors.js";
19
23
  import { toUtcMs } from "./time.js";
20
24
  import { switchesOf } from "./switches.js";
21
- import { eventsOf, panelsOf, timelineOf } from "./story.js";
25
+ import { eventProvenanceOf, eventsOf, panelsOf, timelineOf } from "./story.js";
22
26
  export { toUtcMs } from "./time.js";
23
- /** The orbits the engine can draw: the parent the line is measured from, and the span one lap covers. */
27
+ /** The orbits the engine can draw: the span one lap covers (the parent the line is measured from is the body's catalogue parent). */
24
28
  const ORBITS = {
25
- moon: { parent: "earth", path: { spanMs: SIDEREAL_MONTH_MS } },
26
- io: { parent: "jupiter", path: { spanMs: IO_PERIOD_DAYS * 86_400_000, look: { endFadeOn: false } } },
29
+ moon: { path: { spanMs: SIDEREAL_MONTH_MS } },
30
+ io: { path: { spanMs: IO_PERIOD_DAYS * 86_400_000, look: { endFadeOn: false } } },
27
31
  };
28
32
  const DEFAULT_COLOR = "#ffd27a";
29
33
  const DAY_MS = 86_400_000;
30
34
  const PROVIDER_PATH_SAMPLES = 128;
31
- const SCALES = [trueScale, readableScale];
35
+ const SCALES = [trueScale, readableScale, solarSystemScale];
32
36
  /** The scene's camera: what it opens on. */
33
37
  export class SceneCamera {
34
38
  #target;
35
39
  #following = false;
36
40
  #view = {};
37
41
  #reach;
42
+ #fit;
38
43
  #has;
39
- constructor(has) {
44
+ #circlesSun;
45
+ constructor(has, circlesSun) {
40
46
  this.#has = has;
47
+ this.#circlesSun = circlesSun;
41
48
  }
42
49
  /** Opens framed on a body or trajectory already added to the scene and already following it (the viewer's Follow button shows as pressed). */
43
50
  follow(id, view = {}) {
@@ -59,14 +66,38 @@ export class SceneCamera {
59
66
  }
60
67
  /**
61
68
  * 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`.
69
+ * 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.
62
70
  * 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.
71
+ * `setReach` and `fitOrbit` set the same limit, so the later call wins and replaces the earlier one.
63
72
  */
64
73
  setReach(distance) {
65
74
  if (!(typeof distance === "number" && Number.isFinite(distance) && distance > 0))
66
75
  throw new SceneError("bad-camera", `camera.setReach: distance must be a finite number above 0, got ${String(distance)}`);
67
76
  this.#reach = distance;
77
+ this.#fit = undefined;
68
78
  return this;
69
79
  }
80
+ /**
81
+ * 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
82
+ * 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
83
+ * 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
84
+ * 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
85
+ * same limit, so the later call wins and replaces the earlier one.
86
+ * @example
87
+ * scene.camera.fitOrbit("c-2025-a1");
88
+ */
89
+ fitOrbit(body) {
90
+ const id = typeof body === "string" ? body : body.id;
91
+ if (!this.#has(id))
92
+ throw new SceneError("unknown-body", `camera.fitOrbit("${id}"): no body or trajectory with that id has been added to the scene`);
93
+ if (!this.#circlesSun(id))
94
+ throw new SceneError("bad-camera", `camera.fitOrbit("${id}"): "${id}" is not a body that circles the Sun (a planet, a comet or one added with addBodyFromElements)`);
95
+ this.#fit = id;
96
+ this.#reach = undefined;
97
+ return this;
98
+ }
99
+ /** The body `fitOrbit` fits the zoom-out to, if any. */
100
+ get fitted() { return this.#fit; }
70
101
  /** The farthest zoom-out set with `setReach`, if any. */
71
102
  get reach() { return this.#reach; }
72
103
  get target() { return this.#target; }
@@ -88,24 +119,29 @@ export class Scene {
88
119
  camera;
89
120
  #bodies = new Map();
90
121
  #tracked = new Map();
122
+ /** Paths added without a `center`: they follow the scene's first body, so one added before any body is rebuilt when the first body arrives. */
123
+ #defaulted = new Map();
91
124
  #groups = new Map();
92
125
  #activities = new Map();
93
126
  #orbits = new Set();
94
127
  #own = new Map();
128
+ #labelReaches = new Map();
95
129
  #shape = new Map();
96
130
  #catalogue = builtInCatalogue;
97
131
  #notes = new Map();
98
132
  #looks = new Map();
133
+ #sources = new Map();
99
134
  #timeUtcMs;
100
135
  #scale = trueScale;
101
136
  #scaleOnly = false;
102
137
  #events = [];
103
138
  #eventProvenance;
139
+ #eventOwnProvenance = new Map();
104
140
  #panels;
105
141
  #timeline;
106
142
  #switches;
107
143
  constructor() {
108
- this.camera = new SceneCamera((id) => this.#taken(id));
144
+ this.camera = new SceneCamera((id) => this.#taken(id), (id) => this.#bodies.has(id) && circlesTheSun(this.#catalogue, id));
109
145
  }
110
146
  /** Adds a catalogued body: a ready-made one (`earth`, `moon`, ...) or its id. The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line. */
111
147
  addBody(body, options = {}) {
@@ -146,6 +182,8 @@ export class Scene {
146
182
  if (this.#taken(id))
147
183
  throw new SceneError("duplicate-id", `${call}("${id}"): already in the scene`);
148
184
  checkBodyLook(id, options);
185
+ if (options.labelReach !== undefined)
186
+ this.#labelReaches.set(id, options.labelReach);
149
187
  if (options.orbit === true)
150
188
  this.#orbits.add(id);
151
189
  if (options.color !== undefined || options.knownLimitations !== undefined)
@@ -155,6 +193,9 @@ export class Scene {
155
193
  if (options.description !== undefined)
156
194
  this.#notes.set(id, options.description);
157
195
  this.#bodies.set(id, ref);
196
+ if (this.#bodies.size === 1 && builtInCatalogue.has(id))
197
+ for (const input of this.#defaulted.values())
198
+ this.#buildTracked(input, id);
158
199
  }
159
200
  /** Adds a path to follow and draw, from sampled states or a provider with `stateAt(time)`. */
160
201
  addTrajectory(input) {
@@ -163,15 +204,33 @@ export class Scene {
163
204
  throw new SceneError("bad-trajectory", "addTrajectory: the trajectory needs a non-empty id");
164
205
  if (this.#taken(id))
165
206
  throw new SceneError("duplicate-id", `addTrajectory("${id}"): that id is already in the scene`);
166
- const center = input.center ?? "earth";
207
+ this.#buildTracked(input, input.center ?? this.#sceneCentre());
208
+ if (input.center === undefined)
209
+ this.#defaulted.set(id, input);
210
+ return this;
211
+ }
212
+ /** The scene's centre: its first body when that is a built-in one, else Earth (the default of a path added before any body; `#register` re-reads it when the first body arrives). */
213
+ #sceneCentre() {
214
+ const first = this.#bodies.keys().next();
215
+ return first.done === true || !builtInCatalogue.has(first.value) ? FALLBACK_SCENE_CENTRE : first.value;
216
+ }
217
+ /** Validates and stores one path about `center`. */
218
+ #buildTracked(input, center) {
219
+ const id = input.id;
167
220
  if (!builtInCatalogue.has(center))
168
221
  throw new SceneError("unknown-body", `addTrajectory("${id}"): centre "${center}" is not a catalogued body`);
169
222
  const provenance = input.provenance ?? createProvenance({ sourceType: "illustrative", sources: ["Supplied by the caller"], accuracy: "As supplied; the engine makes no claim.", notes: "Positions were passed to addTrajectory." });
170
- const common = { id, label: input.label ?? id, color: input.color ?? DEFAULT_COLOR, anchorTimesUtcMs: [], provenance };
223
+ const common = { id, label: input.label ?? id, color: input.color ?? DEFAULT_COLOR, anchorTimesUtcMs: [], provenance, ...(input.lineFixedTo === undefined ? {} : { lineFixedTo: input.lineFixedTo }) };
171
224
  const readouts = readoutsOf(id, input.readouts);
172
- const body = "samples" in input ? sampledBody(common, input, center) : providerBody(common, input);
225
+ if (input.labelReach !== undefined) {
226
+ checkLabelReach(input.labelReach, new SceneError("bad-trajectory", `addTrajectory("${id}"): labelReach ${String(input.labelReach)} must be a positive finite number`));
227
+ this.#labelReaches.set(id, input.labelReach);
228
+ }
229
+ if (input.plane !== undefined && input.plane !== "EQJ" && input.plane !== "ecliptic-j2000")
230
+ throw new SceneError("bad-trajectory", `addTrajectory("${id}"): plane "${String(input.plane)}" must be "EQJ" or "ecliptic-j2000"`);
231
+ const toEqj = input.plane === "ecliptic-j2000" ? createOrbTwoBodyAdapter().eclipticJ2000ToEqjMatrix() : null;
232
+ const body = "samples" in input ? sampledBody(common, input, center, toEqj) : providerBody(common, input, toEqj);
173
233
  this.#tracked.set(id, { center, body: withAnchors(body, input.anchors), readouts, ...(input.description === undefined ? {} : { description: input.description }), ...(input.knownLimitations === undefined ? {} : { knownLimitations: input.knownLimitations }) });
174
- return this;
175
234
  }
176
235
  /** Whether a body, path or group already has this id. */
177
236
  #taken(id) {
@@ -179,7 +238,7 @@ export class Scene {
179
238
  }
180
239
  /**
181
240
  * 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.
182
- * 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`.
241
+ * 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`.
183
242
  * @example
184
243
  * scene.addGroup({ id: "ring", orbits: [{ id: "a", semiMajorAxisKm: 90_000, eccentricity: 0.1, inclinationDeg: 5, raanDeg: 40, argumentOfPeriapsisDeg: 70 }], color: "#9de3a8" });
185
244
  */
@@ -208,27 +267,35 @@ export class Scene {
208
267
  this.#timeUtcMs = toUtcMs(time, "setTime");
209
268
  return this;
210
269
  }
211
- /** 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. */
270
+ /** 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. */
212
271
  setScale(scale, options = {}) {
213
272
  if (!SCALES.some((known) => known.id === scale?.id))
214
- throw new SceneError("bad-scale", `setScale: "${String(scale?.id)}" is not a scale; use trueScale or readableScale`);
273
+ throw new SceneError("bad-scale", `setScale: "${String(scale?.id)}" is not a scale; use trueScale, readableScale or solarSystemScale`);
215
274
  this.#scale = scale;
216
275
  this.#scaleOnly = options.only === true;
217
276
  return this;
218
277
  }
219
- /** 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. */
278
+ /** 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". */
220
279
  addEvents(events, options = {}) {
221
- this.#events = eventsOf(events, this.#events);
222
- if (options.provenance !== undefined)
223
- this.#eventProvenance = options.provenance;
280
+ const merged = eventsOf(events, this.#events);
281
+ const own = events.flatMap((event) => event.provenance === undefined ? [] : [[event.id, eventProvenanceOf(event.provenance, event.id)]]);
282
+ const batch = options.provenance === undefined ? undefined : eventProvenanceOf(options.provenance);
283
+ this.#events = merged;
284
+ for (const [id, provenance] of own)
285
+ this.#eventOwnProvenance.set(id, provenance);
286
+ if (batch !== undefined)
287
+ this.#eventProvenance = batch;
224
288
  return this;
225
289
  }
226
- /** 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. */
290
+ /**
291
+ * 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
292
+ * (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.
293
+ */
227
294
  addStoryPanels(panels) {
228
295
  this.#panels = panels;
229
296
  return this;
230
297
  }
231
- /** 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. */
298
+ /** 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. */
232
299
  setTimeline(timeline) {
233
300
  this.#timeline = timelineOf(timeline);
234
301
  return this;
@@ -245,16 +312,55 @@ export class Scene {
245
312
  this.#switches = switchesOf(switches, this.#switches);
246
313
  return this;
247
314
  }
248
- /** 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. */
315
+ /**
316
+ * 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;
317
+ * 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
318
+ * 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
319
+ * `addTrajectory` path throws `bad-time`. A planet before the planet series have loaded (they load at mount) throws `missing-data`.
320
+ * @example
321
+ * const sunDistanceKm = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm);
322
+ */
249
323
  stateOf(id, time) {
250
324
  const entry = this.#tracked.get(id);
251
- if (entry === undefined)
252
- throw new SceneError("unknown-body", `stateOf("${id}"): no trajectory with that id has been added to the scene`);
325
+ if (entry === undefined && !this.#bodies.has(id))
326
+ throw new SceneError("unknown-body", `stateOf("${id}"): no body or trajectory with that id has been added to the scene`);
253
327
  const timeUtcMs = toUtcMs(time, `stateOf("${id}") time`);
254
- const { startUtcMs, endUtcMs } = entry.body.trajectory.bounds;
255
- if (timeUtcMs < startUtcMs || timeUtcMs > endUtcMs)
256
- throw new SceneError("bad-time", `stateOf("${id}"): ${new Date(timeUtcMs).toISOString()} is outside the path (${new Date(startUtcMs).toISOString()} to ${new Date(endUtcMs).toISOString()})`);
257
- return entry.body.trajectory.stateAt(timeUtcMs, entry.center);
328
+ const trajectory = entry?.body.trajectory ?? this.#catalogueSource(id);
329
+ const bounds = trajectory?.bounds;
330
+ if (bounds !== undefined && (timeUtcMs < bounds.startUtcMs || timeUtcMs > bounds.endUtcMs))
331
+ throw new SceneError("bad-time", `stateOf("${id}"): ${new Date(timeUtcMs).toISOString()} is outside the ${entry === undefined ? "body's data" : "path"} (${new Date(bounds.startUtcMs).toISOString()} to ${new Date(bounds.endUtcMs).toISOString()})`);
332
+ if (trajectory === undefined)
333
+ return this.#sunState(id, timeUtcMs);
334
+ try {
335
+ return trajectory.stateAt(timeUtcMs, entry?.center ?? this.#catalogue.get(id).definition.parentId);
336
+ }
337
+ catch (error) {
338
+ if (entry === undefined && error instanceof Error && error.message.startsWith("the planet series are not loaded"))
339
+ throw new SceneError("missing-data", `stateOf("${id}"): ${error.message}`);
340
+ throw error;
341
+ }
342
+ }
343
+ /** 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`. */
344
+ provenanceOf(id) {
345
+ const entry = this.#tracked.get(id);
346
+ if (entry !== undefined)
347
+ return entry.body.provenance; // addTrajectory always sets one
348
+ if (!this.#bodies.has(id))
349
+ throw new SceneError("unknown-body", `provenanceOf("${id}"): no body or trajectory with that id has been added to the scene`);
350
+ return this.#catalogue.get(id).definition.accuracy.position;
351
+ }
352
+ /** A catalogued body's state source, the one the viewer draws from, made once per scene; none for the root (the Sun). */
353
+ #catalogueSource(id) {
354
+ const binding = this.#catalogue.sources().find((source) => source.body === id);
355
+ if (binding === undefined)
356
+ return undefined;
357
+ const made = this.#sources.get(id) ?? binding.create(createOrbAstronomyAdapter());
358
+ this.#sources.set(id, made);
359
+ return made;
360
+ }
361
+ /** The root body is at the origin of itself and at rest. */
362
+ #sunState(id, timeUtcMs) {
363
+ return createStateResolver(this.#catalogue.definitions(), this.#catalogue.sources(), createOrbAstronomyAdapter()).stateOf(id, timeUtcMs, id);
258
364
  }
259
365
  /** The story panels, resolved against this scene's events, anchors, objects and timeline span. */
260
366
  #storyPanels(window) {
@@ -287,6 +393,10 @@ export class Scene {
287
393
  #earlySunPaths(orbitIds, openUtcMs) {
288
394
  return planetSeriesLoaded() ? orbitIds.map((id) => this.#sunPath(id, openUtcMs)) : [];
289
395
  }
396
+ #checkSolarSystemScale(sunCentred) {
397
+ if (this.#scale.id === solarSystemScale.id && !this.#enlargedInSun(sunCentred))
398
+ throw new SceneError("bad-scale", "setScale: the Solar system scale needs a Sun-centred scene with an enlarged body (addBody(x, { enlarge }))");
399
+ }
290
400
  /** Whether a Sun-centred scene enlarges a body, which the viewer's solar-system scale draws. */
291
401
  #enlargedInSun(sunCentred) {
292
402
  return sunCentred && [...this.#shape.values()].some((shape) => shape.enlarge !== undefined);
@@ -324,23 +434,35 @@ export class Scene {
324
434
  #moonPaths() {
325
435
  return [...this.#orbits].filter((id) => ORBITS[id] !== undefined).map((id) => {
326
436
  const orbit = ORBITS[id];
327
- if (!this.#bodies.has(orbit.parent))
328
- throw new SceneError("no-orbit", `addBody("${id}", { orbit: true }): the orbit is drawn about ${orbit.parent}, which has not been added to the scene`);
437
+ const parent = this.#catalogue.get(id).definition.parentId;
438
+ if (parent === undefined || !this.#bodies.has(parent))
439
+ throw new SceneError("no-orbit", `addBody("${id}", { orbit: true }): the orbit is drawn about ${parent}, which has not been added to the scene`);
329
440
  return { body: id, ...orbit.path };
330
441
  });
331
442
  }
332
- /** Whether the scene is centred on the Sun; such a scene cannot hold a tracked path. */
443
+ /** Whether the scene is centred on the Sun. */
333
444
  #checkSunCentred(ids) {
334
- const sunCentred = ids[0] === rootBodyId(this.#catalogue);
335
- if (sunCentred && this.#tracked.size > 0)
336
- throw new SceneError("bad-trajectory", `addTrajectory("${[...this.#tracked.keys()][0]}"): a scene centred on the Sun cannot hold a tracked path yet; centre the scene on Earth or another body`);
337
- return sunCentred;
445
+ return ids[0] === rootBodyId(this.#catalogue);
338
446
  }
339
- /** The shell item of a body: from the catalogue, with the scene's own words, look and label setting. A Sun-centred scene sets no label reach. */
447
+ /** How far a label shows, for bodies and paths alike: the item's own `labelReach` if given, else the shared rule: a Sun-centred scene, or one that fits the zoom-out to an orbit (`fitOrbit`, whose limit changes with the canvas), sets no limit; otherwise the camera reach, at least 500. */
448
+ #labelReach(id, sunCentred) {
449
+ const own = this.#labelReaches.get(id);
450
+ if (own !== undefined)
451
+ return { labelMaxDistance: own };
452
+ return sunCentred || this.camera.fitted !== undefined ? {} : { labelMaxDistance: Math.max(500, this.camera.reach ?? 0) };
453
+ }
454
+ /** The shell item of a body: from the catalogue, with the scene's own words, look and label setting. Label reach is `#labelReach`. */
340
455
  #bodyObject(body, ids, sunCentred) {
341
- const own = { labelPriority: 100 - ids.indexOf(body.id), ...(sunCentred ? {} : { labelMaxDistance: Math.max(500, this.camera.reach ?? 0) }), ...(this.#shape.get(body.id)?.showLabel === undefined ? {} : { showLabel: this.#shape.get(body.id).showLabel }), ...(this.#notes.has(body.id) ? { description: this.#notes.get(body.id) } : {}), ...this.#looks.get(body.id) };
456
+ const own = { labelPriority: 100 - ids.indexOf(body.id), ...this.#labelReach(body.id, sunCentred), ...(this.#shape.get(body.id)?.showLabel === undefined ? {} : { showLabel: this.#shape.get(body.id).showLabel }), ...(this.#notes.has(body.id) ? { description: this.#notes.get(body.id) } : {}), ...this.#looks.get(body.id) };
342
457
  return { ...catalogueItem(body.id, own, this.#catalogue), label: body.label };
343
458
  }
459
+ /** The event provenance entries of the experience: the batch's, and each event's own. */
460
+ #eventProvenanceEntries() {
461
+ return {
462
+ ...(this.#eventProvenance === undefined ? {} : { eventProvenance: this.#eventProvenance }),
463
+ ...(this.#eventOwnProvenance.size === 0 ? {} : { eventProvenanceById: Object.fromEntries(this.#eventOwnProvenance) }),
464
+ };
465
+ }
344
466
  /** The bodies that asked for a Sun-orbit line, checked: the Sun must be in the scene and the line's id free. */
345
467
  #sunOrbitIds(ids) {
346
468
  return [...this.#orbits].filter((id) => ORBITS[id] === undefined).map((id) => {
@@ -351,6 +473,14 @@ export class Scene {
351
473
  return id;
352
474
  });
353
475
  }
476
+ /** The fitted body's farthest Sun distance, read once when the viewer first needs it (a planet's reads the planet series, loaded by then); undefined when no orbit is fitted. */
477
+ #fitFarthestKm(openUtcMs) {
478
+ const id = this.camera.fitted;
479
+ if (id === undefined)
480
+ return undefined;
481
+ let km;
482
+ return () => (km ??= farthestSunDistanceKm(this.#catalogue, id, openUtcMs, this.#own.get(id)));
483
+ }
354
484
  /** One Sun-orbit line: one full turn from the opening time (an own body from its periapsis). Reads planet positions, so the planet series must be loaded. */
355
485
  #sunPath(id, openUtcMs) {
356
486
  const layer = sunOrbitLayer(this.#catalogue, id, openUtcMs, this.#looks.get(id)?.color ?? "", this.#own.get(id));
@@ -358,8 +488,11 @@ export class Scene {
358
488
  throw new SceneError("no-orbit", `addBody("${id}", { orbit: true }): "${id}" completes no turn within a dozen years and the catalogue does not know its period; add it with addBodyFromElements to draw its whole orbit`);
359
489
  return layer;
360
490
  }
361
- /** A readout names a body the scene must hold, so it can be measured against. */
491
+ /** A readout, or the body the line is fixed to, names a body the scene must hold. */
362
492
  #checkReadouts(entry, ids) {
493
+ const fixed = entry.body.lineFixedTo;
494
+ if (fixed !== undefined && !ids.includes(fixed))
495
+ throw new SceneError("bad-trajectory", `addTrajectory("${entry.body.id}"): lineFixedTo names "${fixed}", which has not been added to the scene`);
363
496
  for (const spec of entry.readouts) {
364
497
  const named = readoutBody(spec);
365
498
  if (named !== undefined && !ids.includes(named))
@@ -381,6 +514,7 @@ export class Scene {
381
514
  const ids = [...this.#bodies.keys()];
382
515
  const paths = this.#moonPaths();
383
516
  const sunCentred = this.#checkSunCentred(ids);
517
+ this.#checkSolarSystemScale(sunCentred);
384
518
  for (const entry of this.#tracked.values())
385
519
  this.#checkReadouts(entry, ids);
386
520
  const tracked = [...this.#tracked.values()].map((entry) => entry.body);
@@ -398,16 +532,17 @@ export class Scene {
398
532
  const late = (plan) => !seriesIn && plan.input.clump !== undefined;
399
533
  const layers = [...this.#groupLayers(ids, window, startUtcMs, (plan) => !late(plan))];
400
534
  const labelled = [...this.#bodies.values(), ...tracked, ...[...this.#groups.values()]].map(({ id, label }) => ({ id, label }));
535
+ const catalogue = this.#catalogue;
401
536
  const definition = {
402
537
  experience: {
403
538
  objects: [
404
539
  ...[...this.#bodies.values()].map((body) => this.#bodyObject(body, ids, sunCentred)),
405
- ...[...this.#tracked.values()].map(({ body, description, knownLimitations }) => ({ id: body.id, label: body.label, color: body.color, availability: body.trajectory.bounds, labelPriority: 80, labelMaxDistance: 4, provenance: body.provenance, ...(description === undefined ? {} : { description }), ...(knownLimitations === undefined ? {} : { knownLimitations }) })),
540
+ ...[...this.#tracked.values()].map(({ body, description, knownLimitations }) => ({ id: body.id, label: body.label, color: body.color, availability: body.trajectory.bounds, labelPriority: 80, ...this.#labelReach(body.id, sunCentred), provenance: body.provenance, ...(description === undefined ? {} : { description }), ...(knownLimitations === undefined ? {} : { knownLimitations }) })),
406
541
  ],
407
542
  cameraPresets: cameraPresetsOf(labelled),
408
543
  ...(target === undefined ? {} : { startCameraPresetId: `${this.camera.following ? "follow" : "focus"}-${target}` }),
409
544
  events: this.#events,
410
- ...(this.#eventProvenance === undefined ? {} : { eventProvenance: this.#eventProvenance }),
545
+ ...this.#eventProvenanceEntries(),
411
546
  ...(storyPanels === undefined ? {} : { storyPanels }),
412
547
  ...(timeline?.none === true ? { hideTimeline: true } : {}),
413
548
  window,
@@ -422,11 +557,11 @@ export class Scene {
422
557
  composition: createComposition(this.#catalogue, { id: "scene", bodies: ids, defaultCenter: ids[0], ...(paths.length === 0 ? {} : { paths }) }),
423
558
  scaleChoices: scaleChoicesOf(this.#scale, this.#scaleOnly, this.#enlargedInSun(sunCentred)),
424
559
  ...(this.#switches === undefined ? {} : { displaySwitches: this.#switches }),
425
- ...viewEntries(timeline, this.camera),
560
+ ...viewEntries(timeline, this.camera, this.#fitFarthestKm(startUtcMs)),
426
561
  ...(target === undefined ? {} : { startView: { focus: target, azimuthDeg: view.azimuthDeg ?? 0, elevationDeg: view.elevationDeg ?? 30, distance: view.distance ?? 40 } }),
427
562
  trackedBodies: tracked,
428
563
  createMetrics: ({ resolver }) => {
429
- const catalogued = bodyMetrics(resolver, ids, ["distance"]);
564
+ const catalogued = bodyMetrics(resolver, ids, ["distance"], catalogue);
430
565
  const readouts = createReadoutMetrics([...this.#tracked.values()].map(({ body, readouts: specs }) => ({ body, readouts: specs })), resolver);
431
566
  return (objectId, timeUtcMs) => (this.#groups.has(objectId) ? this.#groupMetrics(objectId, timeUtcMs) : this.#tracked.has(objectId) ? readouts(objectId, timeUtcMs) : catalogued(objectId, timeUtcMs));
432
567
  },
@@ -444,11 +579,12 @@ export class Scene {
444
579
  }
445
580
  }
446
581
  /** The playback and camera settings the scene asked for: looping, the farthest zoom-out and the ecliptic up. */
447
- function viewEntries(timeline, camera) {
582
+ function viewEntries(timeline, camera, farthestKm) {
448
583
  const { reach, view, target } = camera;
449
584
  return {
450
585
  ...(timeline?.loop === true ? { loop: true } : {}),
451
586
  ...(reach === undefined ? {} : { camera: { maxFocusDistance: reach, far: reach * 2.5 } }),
587
+ ...(farthestKm === undefined ? {} : { camera: { fitOrbit: { farthestKm } } }),
452
588
  ...(view.up === undefined || target === undefined ? {} : { viewUp: view.up }),
453
589
  };
454
590
  }
@@ -489,11 +625,13 @@ function cameraPresetsOf(objects) {
489
625
  /** The timeline span and the moment the clock opens at; a moment outside a span the caller set is a `bad-timeline`. */
490
626
  function spanOf(timeline, timeUtcMs, tracked) {
491
627
  const setTime = (timeline?.none === true ? timeline.atUtcMs : undefined) ?? timeUtcMs;
492
- const window = timeline?.window ?? windowOf(tracked, setTime);
628
+ // With nothing setting a span or a moment, the month window is centred on now and the clock opens at now (not at the window's start).
629
+ const now = setTime === undefined && timeline?.window === undefined && tracked.length === 0 ? Date.now() : undefined;
630
+ const window = timeline?.window ?? windowOf(tracked, setTime ?? now);
493
631
  if (timeline?.window !== undefined && setTime !== undefined && (setTime < window.startUtcMs || setTime > window.endUtcMs)) {
494
632
  throw new SceneError("bad-timeline", `setTime ${new Date(setTime).toISOString()} is outside the timeline (${new Date(window.startUtcMs).toISOString()} to ${new Date(window.endUtcMs).toISOString()})`);
495
633
  }
496
- return { window, startUtcMs: setTime ?? window.startUtcMs };
634
+ return { window, startUtcMs: setTime ?? now ?? window.startUtcMs };
497
635
  }
498
636
  /** The clock's opening: 60 times real time unless set; with no timeline and no rate, frozen. */
499
637
  function clockOf(timeline, startUtcMs) {
@@ -501,14 +639,24 @@ function clockOf(timeline, startUtcMs) {
501
639
  }
502
640
  /**
503
641
  * The scale choices offered: the opening one first, then the other unless the caller offered one alone. A Sun-centred scene with an enlarged body (`addBody(x, { enlarge })`)
504
- * offers the viewer's "solar-system" scale (true distances, the named bodies enlarged) in place of the readable scale it would offer second, since the readable scale does not enlarge.
642
+ * offers `solarSystemScale` (true distances, the named bodies enlarged) in place of the readable scale it would offer second, since the readable scale does not enlarge.
505
643
  */
506
644
  function scaleChoicesOf(scale, only, enlarged) {
507
- const second = SCALES.filter((other) => other.id !== scale.id).map((other) => (enlarged && other.id === readableScale.id ? "solar-system" : other.id));
508
- return only ? [scale.id] : [scale.id, ...second];
645
+ const offered = [trueScale, enlarged ? solarSystemScale : readableScale];
646
+ const second = scale.id === readableScale.id ? [trueScale] : offered.filter((other) => other.id !== scale.id);
647
+ return only ? [scale.id] : [scale.id, ...second.map((other) => other.id)];
509
648
  }
510
- function sampledBody(common, input, center) {
511
- const samples = input.samples.map((sample, index) => ({ ...sample, timeUtcMs: toUtcMs(sample.time, `addTrajectory("${common.id}") sample ${index} time`) }));
649
+ /** Rotates a vector by a row-major 3x3 matrix; a missing matrix leaves it as it is. Input that is not three numbers passes through for the State checks to refuse. */
650
+ function rotated(matrix, v) {
651
+ if (matrix === null || v === undefined || v.length !== 3)
652
+ return v;
653
+ return [0, 1, 2].map((row) => matrix[3 * row] * v[0] + matrix[3 * row + 1] * v[1] + matrix[3 * row + 2] * v[2]);
654
+ }
655
+ function sampledBody(common, input, center, toEqj) {
656
+ const samples = input.samples.map((sample, index) => {
657
+ const velocityKmS = rotated(toEqj, sample.velocityKmS);
658
+ return { positionKm: rotated(toEqj, sample.positionKm), ...(velocityKmS === undefined ? {} : { velocityKmS }), timeUtcMs: toUtcMs(sample.time, `addTrajectory("${common.id}") sample ${index} time`) };
659
+ });
512
660
  try {
513
661
  const trajectory = new SampledTrajectory({ body: common.id, center, samples });
514
662
  return { ...common, trajectory, pathTimesUtcMs: samples.map((sample) => sample.timeUtcMs) };
@@ -519,16 +667,22 @@ function sampledBody(common, input, center) {
519
667
  throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): ${error instanceof Error ? error.message : String(error)}`);
520
668
  }
521
669
  }
522
- function providerBody(common, input) {
670
+ function providerBody(common, input, toEqj) {
523
671
  if (typeof input.provider?.stateAt !== "function")
524
672
  throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): provider needs a stateAt(time) function`);
525
673
  const bounds = { startUtcMs: toUtcMs(input.bounds?.start, `addTrajectory("${common.id}") bounds.start`), endUtcMs: toUtcMs(input.bounds?.end, `addTrajectory("${common.id}") bounds.end`) };
526
674
  if (bounds.endUtcMs <= bounds.startUtcMs)
527
675
  throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): bounds must end after they start`);
528
- const trajectory = { body: common.id, bounds, stateAt: (timeUtcMs, center) => input.provider.stateAt(timeUtcMs, center) };
676
+ const trajectory = { body: common.id, bounds, stateAt: (timeUtcMs, center) => rotatedState(toEqj, input.provider.stateAt(timeUtcMs, center)) };
529
677
  const step = (bounds.endUtcMs - bounds.startUtcMs) / (PROVIDER_PATH_SAMPLES - 1);
530
678
  return { ...common, trajectory, pathTimesUtcMs: Array.from({ length: PROVIDER_PATH_SAMPLES }, (_, index) => bounds.startUtcMs + index * step) };
531
679
  }
680
+ /** A provider's State with its position and velocity rotated into EQJ; unchanged for EQJ input. */
681
+ function rotatedState(matrix, state) {
682
+ if (matrix === null)
683
+ return state;
684
+ return createState({ body: state.body, center: state.center, timeUtcMs: state.timeUtcMs, positionKm: rotated(matrix, state.positionKm), ...(state.velocityKmS === undefined ? {} : { velocityKmS: rotated(matrix, state.velocityKmS) }), orientation: state.orientation });
685
+ }
532
686
  /** The timeline span: the union of the trajectories' and activities' spans, else a month about the chosen time (or about now). */
533
687
  function windowOf(tracked, timeUtcMs) {
534
688
  if (tracked.length > 0) {
@@ -540,8 +694,15 @@ function windowOf(tracked, timeUtcMs) {
540
694
  const centre = timeUtcMs ?? Date.now();
541
695
  return { startUtcMs: centre - 15 * DAY_MS, endUtcMs: centre + 15 * DAY_MS };
542
696
  }
543
- /** Checks the colour and known limits given to `addBody`. */
697
+ /** Throws `error` unless `reach` is a positive finite number. */
698
+ function checkLabelReach(reach, error) {
699
+ if (!(typeof reach === "number" && Number.isFinite(reach) && reach > 0))
700
+ throw error;
701
+ }
702
+ /** Checks the colour, known limits and label reach given to `addBody`. */
544
703
  function checkBodyLook(id, options) {
704
+ if (options.labelReach !== undefined)
705
+ checkLabelReach(options.labelReach, new SceneError("bad-body", `addBody("${id}"): labelReach ${String(options.labelReach)} must be a positive finite number`));
545
706
  if (options.enlarge !== undefined && !(typeof options.enlarge === "number" && Number.isFinite(options.enlarge) && options.enlarge >= 1))
546
707
  throw new SceneError("bad-body", `addBody("${id}"): enlarge ${String(options.enlarge)} must be a number of at least 1`);
547
708
  if (options.showLabel !== undefined && typeof options.showLabel !== "boolean")
@@ -1,5 +1,5 @@
1
1
  import { type TimelineEvent } from "../core/events.js";
2
- import type { Provenance } from "../core/provenance.js";
2
+ import { type Provenance } from "../core/provenance.js";
3
3
  import type { TimeBounds } from "../core/trajectory.js";
4
4
  import { type PanelLookup, type StoryPanelSet } from "../shell/storyPanels.js";
5
5
  import { type TimeInput } from "./time.js";
@@ -10,6 +10,8 @@ export interface EventInput {
10
10
  readonly time: TimeInput;
11
11
  /** A free word the timeline may group by, such as "launch". */
12
12
  readonly type?: string;
13
+ /** Where this event's time comes from. Shown with the event; an event without one shows the `provenance` of `addEvents`. Malformed: `addEvents` throws "bad-event" naming the event. */
14
+ readonly provenance?: Provenance;
13
15
  }
14
16
  /** Options of `addEvents`. */
15
17
  export interface AddEventsOptions {
@@ -25,7 +27,7 @@ export type TimelineInput = {
25
27
  readonly start: TimeInput;
26
28
  readonly end: TimeInput;
27
29
  readonly rates?: readonly number[];
28
- readonly rate?: number; /** True: while playing, reaching the end wraps to the start and plays on. The viewer can still seek and pause. Default false. */
30
+ readonly rate?: number; /** True: while playing, reaching the end wraps to the start and plays on. The viewer can still seek and pause. Default false. Not available with `none: true`, where it is ignored. */
29
31
  readonly loop?: boolean;
30
32
  readonly none?: undefined;
31
33
  } | {
@@ -51,10 +53,14 @@ export interface TimelineSetting {
51
53
  * body or path of the scene; these are checked when the scene is turned into a definition (mount), and a mistake throws `bad-panels` naming the panel and field.
52
54
  */
53
55
  export interface StoryPanelsInput {
56
+ /** Seconds playback holds when a panel opens by itself (0 to 20, default 6; 0 never pauses). Playback then restarts, unless the visitor pressed Play during the hold, which ends it at once. */
54
57
  readonly pauseSeconds?: number;
58
+ /** Whether panels open by themselves as forward playback crosses them (default true). */
55
59
  readonly autoOpen?: boolean;
56
60
  readonly panels: readonly unknown[];
57
61
  }
62
+ /** Checks a provenance given to `addEvents` (for the whole batch, or for the event `eventId`) and returns it frozen; throws "bad-event" when malformed. */
63
+ export declare function eventProvenanceOf(value: unknown, eventId?: string): Provenance;
58
64
  /** The events merged with `inputs`, sorted by time; each needs a distinct non-empty id and label and a valid moment. */
59
65
  export declare function eventsOf(inputs: readonly EventInput[], known: readonly TimelineEvent[]): readonly TimelineEvent[];
60
66
  /** Checks a `setTimeline` argument and converts its moments. */
package/src/api/story.js CHANGED
@@ -1,7 +1,18 @@
1
1
  import { createEvents } from "../core/events.js";
2
+ import { createProvenance } from "../core/provenance.js";
2
3
  import { parseStoryPanels, StoryPanelError } from "../shell/storyPanels.js";
3
4
  import { SceneError } from "./errors.js";
4
5
  import { toUtcMs } from "./time.js";
6
+ /** Checks a provenance given to `addEvents` (for the whole batch, or for the event `eventId`) and returns it frozen; throws "bad-event" when malformed. */
7
+ export function eventProvenanceOf(value, eventId) {
8
+ const where = eventId === undefined ? "addEvents: provenance" : `addEvents: event "${eventId}" provenance`;
9
+ try {
10
+ return createProvenance(value);
11
+ }
12
+ catch (error) {
13
+ throw new SceneError("bad-event", `${where} is malformed (${error instanceof Error ? error.message : String(error)})`);
14
+ }
15
+ }
5
16
  /** The events merged with `inputs`, sorted by time; each needs a distinct non-empty id and label and a valid moment. */
6
17
  export function eventsOf(inputs, known) {
7
18
  if (!Array.isArray(inputs))
@@ -12,3 +12,9 @@ export declare function circlesTheSun(catalogue: BodyCatalogue, id: BodyId): boo
12
12
  * the body completes no turn within the search (a comet's century-long orbit given without elements).
13
13
  */
14
14
  export declare function sunOrbitLayer(catalogue: BodyCatalogue, id: BodyId, startUtcMs: number, color: string, given?: EccentricSampling): PathLayer | undefined;
15
+ /**
16
+ * The farthest a body that circles the Sun gets from it, in km: a(1+e) when the period and eccentricity are known (published elements or the
17
+ * catalogue's comet sampling; a from Kepler's third law about the Sun), else the largest Sun distance over one full turn of its own state source.
18
+ * A planet's source reads the planet series, so those must be loaded. Throws `no-orbit` for a body that completes no turn in the search.
19
+ */
20
+ export declare function farthestSunDistanceKm(catalogue: BodyCatalogue, id: BodyId, startUtcMs: number, given?: EccentricSampling): number;