astraeus 0.2.0 → 0.3.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 (59) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/README.md +41 -5
  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/group.d.ts +7 -1
  7. package/src/api/index.d.ts +1 -0
  8. package/src/api/index.js +1 -0
  9. package/src/api/index.node.js +8 -0
  10. package/src/api/mount.js +3 -1
  11. package/src/api/mount.node.js +36 -0
  12. package/src/api/scene.d.ts +32 -6
  13. package/src/api/scene.js +123 -26
  14. package/src/api/story.d.ts +8 -2
  15. package/src/api/story.js +11 -0
  16. package/src/api/sunOrbit.d.ts +6 -0
  17. package/src/api/sunOrbit.js +24 -0
  18. package/src/app/App.d.ts +6 -2
  19. package/src/app/App.js +8 -4
  20. package/src/app/App.node.js +401 -0
  21. package/src/app/PanelLoadBoundary.d.ts +2 -1
  22. package/src/app/PanelLoadBoundary.js +2 -2
  23. package/src/app/SkyView.d.ts +3 -3
  24. package/src/app/SkyView.js +19 -10
  25. package/src/app/experienceDefinition.d.ts +8 -0
  26. package/src/app/sceneContentsHooks.js +2 -2
  27. package/src/app/sceneFrame.js +4 -3
  28. package/src/app/sceneFraming.d.ts +13 -0
  29. package/src/app/sceneFraming.js +22 -0
  30. package/src/app/skyModel.js +1 -1
  31. package/src/assets/pictures.d.ts +1 -1
  32. package/src/assets/sky.d.ts +4 -4
  33. package/src/assets/sky.js +12 -13
  34. package/src/core/bodies/io.js +1 -1
  35. package/src/core/bodies/jupiterData.js +2 -2
  36. package/src/core/bodies/jupiterMoons.js +8 -12
  37. package/src/core/bodies/moon.d.ts +8 -0
  38. package/src/core/bodies/moon.js +28 -5
  39. package/src/core/bodies/outerPlanetData.js +7 -7
  40. package/src/core/bodies/planetMoons.js +18 -27
  41. package/src/core/bodies/swiftTuttle.js +2 -0
  42. package/src/core/elementsBody.d.ts +2 -0
  43. package/src/core/elementsBody.js +3 -0
  44. package/src/core/moonTrajectory.js +3 -5
  45. package/src/core/planetModels.js +1 -1
  46. package/src/core/provenance.d.ts +6 -2
  47. package/src/core/provenance.js +3 -1
  48. package/src/shell/AstraeusShell.js +5 -3
  49. package/src/shell/AstraeusShell.node.js +225 -0
  50. package/src/shell/DisplaySwitches.js +1 -1
  51. package/src/shell/StoryPanelView.js +3 -1
  52. package/src/shell/TimelineBar.node.js +75 -0
  53. package/src/shell/TopBar.node.js +14 -0
  54. package/src/shell/experience.d.ts +2 -0
  55. package/src/shell/infoModel.js +3 -1
  56. package/src/shell/phone.css +1 -1
  57. package/src/shell/useDrawers.js +1 -1
  58. package/src/shell/useZoomThrough.d.ts +7 -0
  59. package/src/shell/useZoomThrough.js +51 -0
package/src/api/scene.js CHANGED
@@ -1,6 +1,8 @@
1
1
  import { createProvenance } from "../core/provenance.js";
2
2
  import { SampledTrajectory } from "../core/sampledTrajectory.js";
3
3
  import { readableScale, trueScale } from "../core/scalePolicy.js";
4
+ import { createStateResolver } from "../core/stateResolver.js";
5
+ import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
4
6
  import { loadPlanetSeries, planetSeriesLoaded } from "../core/planetSeries.js";
5
7
  import { catalogue as builtInCatalogue, extendCatalogue, rootBodyId } from "../assets/catalogue.js";
6
8
  import { buildElementsBody, ElementsBodyError, parseElementsBodyRecord } from "../core/elementsBody.js";
@@ -10,7 +12,7 @@ import { bodyMetrics } from "../app/bodyMetrics.js";
10
12
  import { needsPlanetSeries } from "../app/planetNeeds.js";
11
13
  import { catalogueItem } from "../app/catalogueItem.js";
12
14
  import { createReadoutMetrics } from "../app/trackedMetrics.js";
13
- import { circlesTheSun, sunOrbitIdOf, sunOrbitLayer } from "./sunOrbit.js";
15
+ import { circlesTheSun, farthestSunDistanceKm, sunOrbitIdOf, sunOrbitLayer } from "./sunOrbit.js";
14
16
  import { readyMade } from "./bodies.js";
15
17
  import { installData } from "./data.js";
16
18
  import { planActivity, rateMetricOf } from "./activity.js";
@@ -18,7 +20,7 @@ import { buildGroupLayer, planGroup } from "./group.js";
18
20
  import { SceneError } from "./errors.js";
19
21
  import { toUtcMs } from "./time.js";
20
22
  import { switchesOf } from "./switches.js";
21
- import { eventsOf, panelsOf, timelineOf } from "./story.js";
23
+ import { eventProvenanceOf, eventsOf, panelsOf, timelineOf } from "./story.js";
22
24
  export { toUtcMs } from "./time.js";
23
25
  /** The orbits the engine can draw: the parent the line is measured from, and the span one lap covers. */
24
26
  const ORBITS = {
@@ -35,9 +37,12 @@ export class SceneCamera {
35
37
  #following = false;
36
38
  #view = {};
37
39
  #reach;
40
+ #fit;
38
41
  #has;
39
- constructor(has) {
42
+ #circlesSun;
43
+ constructor(has, circlesSun) {
40
44
  this.#has = has;
45
+ this.#circlesSun = circlesSun;
41
46
  }
42
47
  /** 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
48
  follow(id, view = {}) {
@@ -59,14 +64,38 @@ export class SceneCamera {
59
64
  }
60
65
  /**
61
66
  * 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`.
67
+ * 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
68
  * 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.
69
+ * `setReach` and `fitOrbit` set the same limit, so the later call wins and replaces the earlier one.
63
70
  */
64
71
  setReach(distance) {
65
72
  if (!(typeof distance === "number" && Number.isFinite(distance) && distance > 0))
66
73
  throw new SceneError("bad-camera", `camera.setReach: distance must be a finite number above 0, got ${String(distance)}`);
67
74
  this.#reach = distance;
75
+ this.#fit = undefined;
68
76
  return this;
69
77
  }
78
+ /**
79
+ * 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
80
+ * 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
81
+ * 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
82
+ * 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
83
+ * same limit, so the later call wins and replaces the earlier one.
84
+ * @example
85
+ * scene.camera.fitOrbit("c-2025-a1");
86
+ */
87
+ fitOrbit(body) {
88
+ const id = typeof body === "string" ? body : body.id;
89
+ if (!this.#has(id))
90
+ throw new SceneError("unknown-body", `camera.fitOrbit("${id}"): no body or trajectory with that id has been added to the scene`);
91
+ if (!this.#circlesSun(id))
92
+ 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)`);
93
+ this.#fit = id;
94
+ this.#reach = undefined;
95
+ return this;
96
+ }
97
+ /** The body `fitOrbit` fits the zoom-out to, if any. */
98
+ get fitted() { return this.#fit; }
70
99
  /** The farthest zoom-out set with `setReach`, if any. */
71
100
  get reach() { return this.#reach; }
72
101
  get target() { return this.#target; }
@@ -96,16 +125,18 @@ export class Scene {
96
125
  #catalogue = builtInCatalogue;
97
126
  #notes = new Map();
98
127
  #looks = new Map();
128
+ #sources = new Map();
99
129
  #timeUtcMs;
100
130
  #scale = trueScale;
101
131
  #scaleOnly = false;
102
132
  #events = [];
103
133
  #eventProvenance;
134
+ #eventOwnProvenance = new Map();
104
135
  #panels;
105
136
  #timeline;
106
137
  #switches;
107
138
  constructor() {
108
- this.camera = new SceneCamera((id) => this.#taken(id));
139
+ this.camera = new SceneCamera((id) => this.#taken(id), (id) => this.#bodies.has(id) && circlesTheSun(this.#catalogue, id));
109
140
  }
110
141
  /** 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
142
  addBody(body, options = {}) {
@@ -179,7 +210,7 @@ export class Scene {
179
210
  }
180
211
  /**
181
212
  * 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`.
213
+ * 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
214
  * @example
184
215
  * scene.addGroup({ id: "ring", orbits: [{ id: "a", semiMajorAxisKm: 90_000, eccentricity: 0.1, inclinationDeg: 5, raanDeg: 40, argumentOfPeriapsisDeg: 70 }], color: "#9de3a8" });
185
216
  */
@@ -216,19 +247,27 @@ export class Scene {
216
247
  this.#scaleOnly = options.only === true;
217
248
  return this;
218
249
  }
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. */
250
+ /** 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
251
  addEvents(events, options = {}) {
221
- this.#events = eventsOf(events, this.#events);
222
- if (options.provenance !== undefined)
223
- this.#eventProvenance = options.provenance;
252
+ const merged = eventsOf(events, this.#events);
253
+ const own = events.flatMap((event) => event.provenance === undefined ? [] : [[event.id, eventProvenanceOf(event.provenance, event.id)]]);
254
+ const batch = options.provenance === undefined ? undefined : eventProvenanceOf(options.provenance);
255
+ this.#events = merged;
256
+ for (const [id, provenance] of own)
257
+ this.#eventOwnProvenance.set(id, provenance);
258
+ if (batch !== undefined)
259
+ this.#eventProvenance = batch;
224
260
  return this;
225
261
  }
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. */
262
+ /**
263
+ * 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
264
+ * (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.
265
+ */
227
266
  addStoryPanels(panels) {
228
267
  this.#panels = panels;
229
268
  return this;
230
269
  }
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. */
270
+ /** 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
271
  setTimeline(timeline) {
233
272
  this.#timeline = timelineOf(timeline);
234
273
  return this;
@@ -245,16 +284,55 @@ export class Scene {
245
284
  this.#switches = switchesOf(switches, this.#switches);
246
285
  return this;
247
286
  }
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. */
287
+ /**
288
+ * 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;
289
+ * 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
290
+ * 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
291
+ * `addTrajectory` path throws `bad-time`. A planet before the planet series have loaded (they load at mount) throws `missing-data`.
292
+ * @example
293
+ * const sunDistanceKm = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm);
294
+ */
249
295
  stateOf(id, time) {
250
296
  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`);
297
+ if (entry === undefined && !this.#bodies.has(id))
298
+ throw new SceneError("unknown-body", `stateOf("${id}"): no body or trajectory with that id has been added to the scene`);
253
299
  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);
300
+ const trajectory = entry?.body.trajectory ?? this.#catalogueSource(id);
301
+ const bounds = trajectory?.bounds;
302
+ if (bounds !== undefined && (timeUtcMs < bounds.startUtcMs || timeUtcMs > bounds.endUtcMs))
303
+ 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()})`);
304
+ if (trajectory === undefined)
305
+ return this.#sunState(id, timeUtcMs);
306
+ try {
307
+ return trajectory.stateAt(timeUtcMs, entry?.center ?? this.#catalogue.get(id).definition.parentId);
308
+ }
309
+ catch (error) {
310
+ if (entry === undefined && error instanceof Error && error.message.startsWith("the planet series are not loaded"))
311
+ throw new SceneError("missing-data", `stateOf("${id}"): ${error.message}`);
312
+ throw error;
313
+ }
314
+ }
315
+ /** 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`. */
316
+ provenanceOf(id) {
317
+ const entry = this.#tracked.get(id);
318
+ if (entry !== undefined)
319
+ return entry.body.provenance; // addTrajectory always sets one
320
+ if (!this.#bodies.has(id))
321
+ throw new SceneError("unknown-body", `provenanceOf("${id}"): no body or trajectory with that id has been added to the scene`);
322
+ return this.#catalogue.get(id).definition.accuracy.position;
323
+ }
324
+ /** A catalogued body's state source, the one the viewer draws from, made once per scene; none for the root (the Sun). */
325
+ #catalogueSource(id) {
326
+ const binding = this.#catalogue.sources().find((source) => source.body === id);
327
+ if (binding === undefined)
328
+ return undefined;
329
+ const made = this.#sources.get(id) ?? binding.create(createOrbAstronomyAdapter());
330
+ this.#sources.set(id, made);
331
+ return made;
332
+ }
333
+ /** The root body is at the origin of itself and at rest. */
334
+ #sunState(id, timeUtcMs) {
335
+ return createStateResolver(this.#catalogue.definitions(), this.#catalogue.sources(), createOrbAstronomyAdapter()).stateOf(id, timeUtcMs, id);
258
336
  }
259
337
  /** The story panels, resolved against this scene's events, anchors, objects and timeline span. */
260
338
  #storyPanels(window) {
@@ -336,11 +414,18 @@ export class Scene {
336
414
  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
415
  return sunCentred;
338
416
  }
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. */
417
+ /** The shell item of a body: from the catalogue, with the scene's own words, look and label setting. A Sun-centred scene, or one that fits the zoom-out to an orbit (`fitOrbit`, whose limit changes with the canvas), sets no label limit, so labels stay shown at any distance. */
340
418
  #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) };
419
+ const own = { labelPriority: 100 - ids.indexOf(body.id), ...(sunCentred || this.camera.fitted !== undefined ? {} : { 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) };
342
420
  return { ...catalogueItem(body.id, own, this.#catalogue), label: body.label };
343
421
  }
422
+ /** The event provenance entries of the experience: the batch's, and each event's own. */
423
+ #eventProvenanceEntries() {
424
+ return {
425
+ ...(this.#eventProvenance === undefined ? {} : { eventProvenance: this.#eventProvenance }),
426
+ ...(this.#eventOwnProvenance.size === 0 ? {} : { eventProvenanceById: Object.fromEntries(this.#eventOwnProvenance) }),
427
+ };
428
+ }
344
429
  /** The bodies that asked for a Sun-orbit line, checked: the Sun must be in the scene and the line's id free. */
345
430
  #sunOrbitIds(ids) {
346
431
  return [...this.#orbits].filter((id) => ORBITS[id] === undefined).map((id) => {
@@ -351,6 +436,14 @@ export class Scene {
351
436
  return id;
352
437
  });
353
438
  }
439
+ /** 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. */
440
+ #fitFarthestKm(openUtcMs) {
441
+ const id = this.camera.fitted;
442
+ if (id === undefined)
443
+ return undefined;
444
+ let km;
445
+ return () => (km ??= farthestSunDistanceKm(this.#catalogue, id, openUtcMs, this.#own.get(id)));
446
+ }
354
447
  /** 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
448
  #sunPath(id, openUtcMs) {
356
449
  const layer = sunOrbitLayer(this.#catalogue, id, openUtcMs, this.#looks.get(id)?.color ?? "", this.#own.get(id));
@@ -398,6 +491,7 @@ export class Scene {
398
491
  const late = (plan) => !seriesIn && plan.input.clump !== undefined;
399
492
  const layers = [...this.#groupLayers(ids, window, startUtcMs, (plan) => !late(plan))];
400
493
  const labelled = [...this.#bodies.values(), ...tracked, ...[...this.#groups.values()]].map(({ id, label }) => ({ id, label }));
494
+ const catalogue = this.#catalogue;
401
495
  const definition = {
402
496
  experience: {
403
497
  objects: [
@@ -407,7 +501,7 @@ export class Scene {
407
501
  cameraPresets: cameraPresetsOf(labelled),
408
502
  ...(target === undefined ? {} : { startCameraPresetId: `${this.camera.following ? "follow" : "focus"}-${target}` }),
409
503
  events: this.#events,
410
- ...(this.#eventProvenance === undefined ? {} : { eventProvenance: this.#eventProvenance }),
504
+ ...this.#eventProvenanceEntries(),
411
505
  ...(storyPanels === undefined ? {} : { storyPanels }),
412
506
  ...(timeline?.none === true ? { hideTimeline: true } : {}),
413
507
  window,
@@ -422,11 +516,11 @@ export class Scene {
422
516
  composition: createComposition(this.#catalogue, { id: "scene", bodies: ids, defaultCenter: ids[0], ...(paths.length === 0 ? {} : { paths }) }),
423
517
  scaleChoices: scaleChoicesOf(this.#scale, this.#scaleOnly, this.#enlargedInSun(sunCentred)),
424
518
  ...(this.#switches === undefined ? {} : { displaySwitches: this.#switches }),
425
- ...viewEntries(timeline, this.camera),
519
+ ...viewEntries(timeline, this.camera, this.#fitFarthestKm(startUtcMs)),
426
520
  ...(target === undefined ? {} : { startView: { focus: target, azimuthDeg: view.azimuthDeg ?? 0, elevationDeg: view.elevationDeg ?? 30, distance: view.distance ?? 40 } }),
427
521
  trackedBodies: tracked,
428
522
  createMetrics: ({ resolver }) => {
429
- const catalogued = bodyMetrics(resolver, ids, ["distance"]);
523
+ const catalogued = bodyMetrics(resolver, ids, ["distance"], catalogue);
430
524
  const readouts = createReadoutMetrics([...this.#tracked.values()].map(({ body, readouts: specs }) => ({ body, readouts: specs })), resolver);
431
525
  return (objectId, timeUtcMs) => (this.#groups.has(objectId) ? this.#groupMetrics(objectId, timeUtcMs) : this.#tracked.has(objectId) ? readouts(objectId, timeUtcMs) : catalogued(objectId, timeUtcMs));
432
526
  },
@@ -444,11 +538,12 @@ export class Scene {
444
538
  }
445
539
  }
446
540
  /** The playback and camera settings the scene asked for: looping, the farthest zoom-out and the ecliptic up. */
447
- function viewEntries(timeline, camera) {
541
+ function viewEntries(timeline, camera, farthestKm) {
448
542
  const { reach, view, target } = camera;
449
543
  return {
450
544
  ...(timeline?.loop === true ? { loop: true } : {}),
451
545
  ...(reach === undefined ? {} : { camera: { maxFocusDistance: reach, far: reach * 2.5 } }),
546
+ ...(farthestKm === undefined ? {} : { camera: { fitOrbit: { farthestKm } } }),
452
547
  ...(view.up === undefined || target === undefined ? {} : { viewUp: view.up }),
453
548
  };
454
549
  }
@@ -489,11 +584,13 @@ function cameraPresetsOf(objects) {
489
584
  /** The timeline span and the moment the clock opens at; a moment outside a span the caller set is a `bad-timeline`. */
490
585
  function spanOf(timeline, timeUtcMs, tracked) {
491
586
  const setTime = (timeline?.none === true ? timeline.atUtcMs : undefined) ?? timeUtcMs;
492
- const window = timeline?.window ?? windowOf(tracked, setTime);
587
+ // 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).
588
+ const now = setTime === undefined && timeline?.window === undefined && tracked.length === 0 ? Date.now() : undefined;
589
+ const window = timeline?.window ?? windowOf(tracked, setTime ?? now);
493
590
  if (timeline?.window !== undefined && setTime !== undefined && (setTime < window.startUtcMs || setTime > window.endUtcMs)) {
494
591
  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
592
  }
496
- return { window, startUtcMs: setTime ?? window.startUtcMs };
593
+ return { window, startUtcMs: setTime ?? now ?? window.startUtcMs };
497
594
  }
498
595
  /** The clock's opening: 60 times real time unless set; with no timeline and no rate, frozen. */
499
596
  function clockOf(timeline, startUtcMs) {
@@ -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;
@@ -2,6 +2,7 @@ import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
2
2
  import { BUILT_IN_SAMPLING, EARTH_EPHEMERIS } from "../core/bodies/index.js";
3
3
  import { createEarthSunTrajectory, fullTurnSpanMs } from "../core/sunCentredSources.js";
4
4
  import { rootBodyId } from "../assets/catalogue.js";
5
+ import { SceneError } from "./errors.js";
5
6
  const DAY_MS = 86_400_000;
6
7
  /** The turn search walks in two-day steps; the longest orbit among the planets is a dozen years. */
7
8
  const TURN_STEP_MS = 2 * DAY_MS;
@@ -59,3 +60,26 @@ function turnSpan(source, startUtcMs) {
59
60
  throw error;
60
61
  }
61
62
  }
63
+ /**
64
+ * 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
65
+ * 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.
66
+ * 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.
67
+ */
68
+ export function farthestSunDistanceKm(catalogue, id, startUtcMs, given) {
69
+ const sampling = given ?? BUILT_IN_SAMPLING[id];
70
+ if (sampling !== undefined) {
71
+ const gm = catalogue.get(rootBodyId(catalogue)).definition.gmKm3S2;
72
+ const semiMajorKm = Math.cbrt(gm * (sampling.periodMs / 1000 / (2 * Math.PI)) ** 2);
73
+ return semiMajorKm * (1 + sampling.eccentricity);
74
+ }
75
+ const source = trajectoryOf(catalogue, id);
76
+ const span = turnSpan(source, startUtcMs);
77
+ if (span === undefined)
78
+ throw new SceneError("no-orbit", `camera.fitOrbit("${id}"): "${id}" completes no turn within a dozen years and the catalogue does not know its period; add it with addBodyFromElements`);
79
+ let farthest = 0;
80
+ for (let k = 0; k < TURN_SAMPLES; k += 1) {
81
+ const [x, y, z] = source.stateAt(Math.round(span.startUtcMs + ((span.endUtcMs - span.startUtcMs) * k) / (TURN_SAMPLES - 1)), rootBodyId(catalogue)).positionKm;
82
+ farthest = Math.max(farthest, Math.hypot(x, y, z));
83
+ }
84
+ return farthest;
85
+ }
package/src/app/App.d.ts CHANGED
@@ -6,8 +6,12 @@ export declare function hiddenLabelsFrom(search: string, objects: readonly {
6
6
  }[]): Set<string>;
7
7
  /** `?loop=on` or `?loop=off` overrides the experience's own looping setting. */
8
8
  export declare function loopFromSearch(search: string, fallback: boolean): boolean;
9
- /** `onOpenAddress`: the entry's way to open a switch's address in place; without it a switch navigates the page. */
10
- export declare function App({ definition, onOpenAddress }: {
9
+ /**
10
+ * `onOpenAddress`: the entry's way to open a switch's address in place; without it a switch navigates the page.
11
+ * `writeTitle`: whether the page heading is set to the experience's name (default true); `mount` and `AstraeusScene` pass false so a host page keeps its own title.
12
+ */
13
+ export declare function App({ definition, onOpenAddress, writeTitle }: {
11
14
  readonly definition: ExperienceDefinition;
12
15
  readonly onOpenAddress?: (address: string) => void;
16
+ readonly writeTitle?: boolean;
13
17
  }): import("react").JSX.Element;
package/src/app/App.js CHANGED
@@ -142,12 +142,16 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
142
142
  ...(startView === undefined ? {} : { startView }),
143
143
  };
144
144
  }
145
- /** `onOpenAddress`: the entry's way to open a switch's address in place; without it a switch navigates the page. */
146
- export function App({ definition, onOpenAddress }) {
145
+ /**
146
+ * `onOpenAddress`: the entry's way to open a switch's address in place; without it a switch navigates the page.
147
+ * `writeTitle`: whether the page heading is set to the experience's name (default true); `mount` and `AstraeusScene` pass false so a host page keeps its own title.
148
+ */
149
+ export function App({ definition, onOpenAddress, writeTitle = true }) {
147
150
  // The page heading names the experience once it is open; app.html says only "Astraeus" until then.
148
151
  useEffect(() => {
149
- document.title = pageTitleOf(definition);
150
- }, [definition]);
152
+ if (writeTitle)
153
+ document.title = pageTitleOf(definition);
154
+ }, [definition, writeTitle]);
151
155
  const runtime = useMemo(() => buildRuntime(definition), [definition]);
152
156
  const experienceRuntime = useMemo(() => ({ clock: runtime.clock, resolver: runtime.resolver, catalogue: runtime.catalogue }), [runtime]);
153
157
  // The choices offered, in the experience's order; the solar-system policy enlarges only the bodies the experience names.