astraeus 0.4.0 → 0.5.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 (78) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +64 -10
  3. package/data/ephemerides/planets/planets.json +1 -1
  4. package/package.json +1 -1
  5. package/src/api/AstraeusScene.d.ts +9 -1
  6. package/src/api/AstraeusScene.js +26 -4
  7. package/src/api/AstraeusScene.node.js +26 -4
  8. package/src/api/data.js +11 -1
  9. package/src/api/errors.d.ts +1 -1
  10. package/src/api/index.d.ts +2 -1
  11. package/src/api/mount.d.ts +16 -0
  12. package/src/api/mount.js +13 -1
  13. package/src/api/mount.node.js +13 -1
  14. package/src/api/pathProvenance.d.ts +10 -0
  15. package/src/api/pathProvenance.js +34 -0
  16. package/src/api/scene.d.ts +7 -1
  17. package/src/api/scene.js +103 -14
  18. package/src/api/story.d.ts +41 -1
  19. package/src/api/story.js +63 -1
  20. package/src/api/sunOrbit.d.ts +3 -3
  21. package/src/api/sunOrbit.js +92 -24
  22. package/src/api/viewerLink.d.ts +40 -0
  23. package/src/api/viewerLink.js +86 -0
  24. package/src/app/App.d.ts +4 -1
  25. package/src/app/App.js +42 -6
  26. package/src/app/App.node.js +42 -6
  27. package/src/app/AstraeusScene.d.ts +7 -0
  28. package/src/app/BodySetView.js +3 -2
  29. package/src/app/KeplerPoints.d.ts +1 -1
  30. package/src/app/KeplerPoints.js +3 -2
  31. package/src/app/PointsView.js +3 -2
  32. package/src/app/TrackedBodyView.js +3 -2
  33. package/src/app/bodyDraw.js +3 -2
  34. package/src/app/dotMaterial.d.ts +11 -0
  35. package/src/app/dotMaterial.js +38 -0
  36. package/src/app/experienceDefinition.d.ts +12 -0
  37. package/src/app/mission.d.ts +1 -1
  38. package/src/app/mission.js +1 -1
  39. package/src/app/openClock.d.ts +1 -1
  40. package/src/app/openClock.js +3 -0
  41. package/src/app/sceneContentsHooks.js +2 -1
  42. package/src/app/sceneFrame.d.ts +2 -2
  43. package/src/app/sceneFrame.js +6 -1
  44. package/src/app/sceneFraming.d.ts +1 -1
  45. package/src/app/sceneFraming.js +9 -3
  46. package/src/app/viewerPort.d.ts +33 -0
  47. package/src/app/viewerPort.js +1 -0
  48. package/src/core/bodies/io.js +1 -1
  49. package/src/core/bodies/jupiterMoons.d.ts +1 -1
  50. package/src/core/bodies/jupiterMoons.js +6 -6
  51. package/src/core/bodies/moonSystem.d.ts +15 -1
  52. package/src/core/bodies/moonSystem.js +58 -7
  53. package/src/core/bodies/outerPlanets.js +1 -1
  54. package/src/core/bodies/planetMoons.js +10 -10
  55. package/src/core/chebyshevEphemeris.d.ts +7 -1
  56. package/src/core/chebyshevEphemeris.js +24 -7
  57. package/src/core/clock.d.ts +8 -0
  58. package/src/core/clock.js +14 -0
  59. package/src/core/pacing.d.ts +24 -0
  60. package/src/core/pacing.js +35 -0
  61. package/src/core/planetModels.d.ts +4 -1
  62. package/src/core/planetModels.js +6 -1
  63. package/src/core/planetSeries.d.ts +3 -0
  64. package/src/core/planetSeries.js +8 -1
  65. package/src/core/timeWindow.d.ts +2 -0
  66. package/src/core/timeWindow.js +4 -3
  67. package/src/shell/AstraeusShell.d.ts +6 -2
  68. package/src/shell/AstraeusShell.js +3 -3
  69. package/src/shell/AstraeusShell.node.js +3 -3
  70. package/src/shell/TimelineBar.d.ts +4 -2
  71. package/src/shell/TimelineBar.js +15 -6
  72. package/src/shell/TimelineBar.node.js +15 -6
  73. package/src/shell/experience.d.ts +3 -1
  74. package/src/shell/infoModel.js +5 -4
  75. package/src/shell/timelineModel.d.ts +2 -3
  76. package/src/shell/timelineModel.js +3 -11
  77. package/src/synthetic/syntheticJourneyScene.d.ts +9 -0
  78. package/src/synthetic/syntheticJourneyScene.js +75 -0
@@ -1,7 +1,7 @@
1
1
  import { type BodyCatalogue } from "../assets/catalogue.js";
2
2
  import type { BodyId } from "../core/body.js";
3
3
  import type { ScalePolicy } from "../core/scalePolicy.js";
4
- import type { CameraReach } from "./experienceDefinition.js";
4
+ import { type CameraReach } from "./experienceDefinition.js";
5
5
  /** A tracked body is a point: the camera may come very close and is framed in Earth radii. */
6
6
  export declare const TRACKED_MIN_DISTANCE = 0.002;
7
7
  export declare const TRACKED_DEFAULT_DISTANCE = 0.3;
@@ -1,5 +1,6 @@
1
1
  // Scene framing: default distances and fit rules for tracked bodies, groups and bare scenes.
2
2
  import { catalogue } from "../assets/catalogue.js";
3
+ import { DEFAULT_CAMERA_FAR } from "./experienceDefinition.js";
3
4
  /** A tracked body is a point: the camera may come very close and is framed in Earth radii. */
4
5
  export const TRACKED_MIN_DISTANCE = 0.002;
5
6
  export const TRACKED_DEFAULT_DISTANCE = 0.3;
@@ -52,14 +53,19 @@ export function fitReach(farthestUnits, aspect, fovDeg = CAMERA_FOV_DEG) {
52
53
  }
53
54
  /** The declared reach as the viewer applies it now: a fitting reach becomes a farthest zoom-out and far plane for the canvas shape `aspect` (width over height); any other is returned as is. */
54
55
  export function liveReach(declared, policy, aspect) {
55
- if (declared.fitOrbit === undefined)
56
- return declared;
56
+ if (declared.fitOrbit === undefined) {
57
+ if (declared.cover === undefined || declared.maxFocusDistance !== undefined)
58
+ return declared;
59
+ // I-114: a path past the planets widens the default zoom-out and far plane so it fits whole; the default is never narrowed.
60
+ const minFocusDistance = fitReach(scaleLength(policy, declared.cover.farthestKm()), aspect > 0 ? aspect : 1);
61
+ return { ...declared, minFocusDistance, far: Math.max(declared.far ?? DEFAULT_CAMERA_FAR, minFocusDistance * FAR_PER_REACH) };
62
+ }
57
63
  const maxFocusDistance = fitReach(scaleLength(policy, declared.fitOrbit.farthestKm()), aspect > 0 ? aspect : 1);
58
64
  return { maxFocusDistance, far: maxFocusDistance * FAR_PER_REACH };
59
65
  }
60
66
  /** Zoom limits per focus kind; a declared reach replaces only the farthest distance. */
61
67
  export function focusLimits(focus, frame, policy, declared) {
62
- const max = declared.maxFocusDistance ?? Math.max(30, frame.span * 3.5);
68
+ const max = declared.maxFocusDistance ?? Math.max(30, frame.span * 3.5, declared.minFocusDistance ?? 0);
63
69
  const member = frame.memberRadius?.(focus) ?? null;
64
70
  if (member !== null)
65
71
  return { min: Math.max(MEMBER_MIN_DISTANCE, member * BODY_MIN_FACTOR), max };
@@ -0,0 +1,33 @@
1
+ import type { TimeBounds } from "../core/trajectory.js";
2
+ /** The one clock's reading as a host sees it. */
3
+ export interface ViewerState {
4
+ readonly timeUtcMs: number;
5
+ /** Simulated seconds per real second. */
6
+ readonly rate: number;
7
+ readonly playing: boolean;
8
+ /** Only in a scene with pacing: true while pacing sets the rate, false once a visitor or the host has picked a speed. */
9
+ readonly auto?: boolean;
10
+ }
11
+ /** Who moved the clock: the clock running (`playback`), a person at the controls (`visitor`) or the host page (`host`). */
12
+ export type ViewerChangeCause = "playback" | "visitor" | "host";
13
+ /** What a mounted viewer lets the host do to its one clock. Seeking and rate changes go through the viewer's own handlers, so there is no second clock. */
14
+ export interface ViewerControl {
15
+ readonly window: TimeBounds;
16
+ /** The speeds the timeline offers. */
17
+ readonly rates: readonly number[];
18
+ read(): ViewerState;
19
+ seek(timeUtcMs: number): void;
20
+ /** True: the scene has pacing, so `"auto"` is a valid choice. */
21
+ readonly paced: boolean;
22
+ /** A number is a chosen speed; `"auto"` gives the rate back to the scene's pacing. */
23
+ setRate(rate: number | "auto"): void;
24
+ }
25
+ /** The viewer's side of the host link; the public API supplies the implementation (`ViewerLink`). */
26
+ export interface ViewerPort {
27
+ /** The viewer hands over its clock controls when it opens. */
28
+ attach(control: ViewerControl): void;
29
+ /** The viewer is going away: the controls are no longer valid. */
30
+ detach(): void;
31
+ /** The viewer reports the clock's current reading; the link tells the host only when it differs from the last one. */
32
+ publish(state: ViewerState, cause: ViewerChangeCause): void;
33
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -111,7 +111,7 @@ export const IO = Object.freeze({
111
111
  accuracy: "Mean radius 1821.49 km and GM 5959.9155 km^3/s^2 as printed in the Horizons header; Io is drawn as a sphere.",
112
112
  notes: "Gravitational parameter in km^3/s^2.",
113
113
  }),
114
- position: fittedMoonPosition("Io", 0.0994),
114
+ position: fittedMoonPosition("Io", 0.1924, JUPITER_MOON_FIT_SPAN),
115
115
  validUtc: JUPITER_MOON_FIT_SPAN,
116
116
  orientationLimitations: Object.freeze([IO_TIDAL_LOCK_LIMITATION]),
117
117
  }),
@@ -20,7 +20,7 @@ export declare const loadJupiterMoons: (load: MoonSystemLoad) => Promise<import(
20
20
  export declare const osculatingPeriodMs: (ephemeris: import("../chebyshevEphemeris.js").ChebyshevEphemeris, body: BodyId, timeUtcMs: number) => number;
21
21
  export declare const FITTED_MOON_TIDAL_LOCK: string;
22
22
  /** What every mapped Jupiter moon's record says about its position, with its own worst figure from T-096. */
23
- export declare const fittedMoonPosition: (label: string, worstM: number) => ReturnType<typeof import("../provenance.js").createProvenance>;
23
+ export declare const fittedMoonPosition: (label: string, worstM: number, span?: TimeBounds) => ReturnType<typeof import("../provenance.js").createProvenance>;
24
24
  /** The Galilean moons turn synchronously: their prime meridians are the IAU records saved with their orbits (`data/orbits/`), the one source. */
25
25
  export declare const IO_ROTATION: import("../iauRotation.js").IauRotationElements;
26
26
  export declare const EUROPA: import("../body.js").CelestialBodyDefinition;
@@ -1,12 +1,12 @@
1
1
  import { iauElementsFromRecord } from "../iauRotation.js";
2
2
  import { JUPITER } from "./jupiter.js";
3
- import { chunksNeeded, createMoonSystem, MOON_FIT_SPAN, moonFitSource } from "./moonSystem.js";
3
+ import { chunksNeeded, createMoonSystem, HISTORICAL_MOON_FIT_SPAN, moonFitSource } from "./moonSystem.js";
4
4
  import callistoOrbit from "../../../data/orbits/callisto.json" with { type: "json" };
5
5
  import europaOrbit from "../../../data/orbits/europa.json" with { type: "json" };
6
6
  import ganymedeOrbit from "../../../data/orbits/ganymede.json" with { type: "json" };
7
7
  import ioOrbit from "../../../data/orbits/io.json" with { type: "json" };
8
8
  /** The span the committed fits cover (T-096: 2010-01-01 to 2030-01-01 TDB, chunked per calendar year). */
9
- export const JUPITER_MOON_FIT_SPAN = MOON_FIT_SPAN;
9
+ export const JUPITER_MOON_FIT_SPAN = HISTORICAL_MOON_FIT_SPAN;
10
10
  export const JUPITER_MOON_FIT_SOURCE = moonFitSource("Jupiter");
11
11
  export const JUPITER_MOON_SYSTEM = createMoonSystem({
12
12
  centre: "jupiter",
@@ -27,10 +27,10 @@ export const FITTED_MOON_TIDAL_LOCK = JUPITER_MOON_SYSTEM.tidalLockNote;
27
27
  export const fittedMoonPosition = JUPITER_MOON_SYSTEM.position;
28
28
  /** The Galilean moons turn synchronously: their prime meridians are the IAU records saved with their orbits (`data/orbits/`), the one source. */
29
29
  export const IO_ROTATION = iauElementsFromRecord(ioOrbit.rotation);
30
- const jupiterMoon = (id, label, radiusKm, gmKm3S2, worstM, header) => JUPITER_MOON_SYSTEM.mappedMoon({ id, label, radiusKm, gmKm3S2, worstM, header });
31
- export const EUROPA = jupiterMoon("europa", "Europa", 1560.8, 3202.7121, 0.0755, "Mean radius (km) = 1560.8 +- 0.3, GM (km^3/s^2) = 3202.7121 +- 0.0054");
32
- export const GANYMEDE = jupiterMoon("ganymede", "Ganymede", 2631.2, 9887.8328, 0.0662, "Mean radius (km) = 2631.2 +- 1.7, GM (km^3/s^2) = 9887.8328 +- 0.0074");
33
- export const CALLISTO = jupiterMoon("callisto", "Callisto", 2410.3, 7179.2834, 0.0521, "Mean radius (km) = 2410.3 +- 1.5, GM (km^3/s^2) = 7179.2834 +- 0.0097");
30
+ const jupiterMoon = (id, label, radiusKm, gmKm3S2, worstM, header) => JUPITER_MOON_SYSTEM.mappedMoon({ id, label, radiusKm, gmKm3S2, worstM, header, span: HISTORICAL_MOON_FIT_SPAN });
31
+ export const EUROPA = jupiterMoon("europa", "Europa", 1560.8, 3202.7121, 0.163, "Mean radius (km) = 1560.8 +- 0.3, GM (km^3/s^2) = 3202.7121 +- 0.0054");
32
+ export const GANYMEDE = jupiterMoon("ganymede", "Ganymede", 2631.2, 9887.8328, 0.1206, "Mean radius (km) = 2631.2 +- 1.7, GM (km^3/s^2) = 9887.8328 +- 0.0074");
33
+ export const CALLISTO = jupiterMoon("callisto", "Callisto", 2410.3, 7179.2834, 0.0947, "Mean radius (km) = 2410.3 +- 1.5, GM (km^3/s^2) = 7179.2834 +- 0.0097");
34
34
  /** Io's binding is in `io.ts` with its definition; the three below are the same pattern. */
35
35
  export const IO_FITTED_BINDING = JUPITER_MOON_SYSTEM.binding("io", IO_ROTATION);
36
36
  export const MAPPED_MOON_BINDINGS = Object.freeze([
@@ -12,6 +12,18 @@ import { createProvenance } from "../provenance.js";
12
12
  import type { TimeBounds, Trajectory } from "../trajectory.js";
13
13
  /** The span the committed fits cover (T-096, T-114: 2010-01-01 to 2030-01-01 TDB, chunked per calendar year; the same for every system). */
14
14
  export declare const MOON_FIT_SPAN: TimeBounds;
15
+ /**
16
+ * The span of the main moons fitted back to 1950 (O-047 T-200). A mapped moon names which span its data holds with `MappedMoonFacts.span`;
17
+ * `tests/moonSpans.test.ts` compares every static span with the shipped index, so this is never a second source of truth that can drift.
18
+ */
19
+ export declare const HISTORICAL_MOON_FIT_SPAN: TimeBounds;
20
+ /** A scene's window reaches outside the years a loaded moon's positions cover (O-047 T-195): named once, at load, instead of a throw on every frame. */
21
+ export declare class MoonOutOfSpanError extends RangeError {
22
+ readonly body: BodyId;
23
+ readonly span: TimeBounds;
24
+ readonly window: TimeBounds;
25
+ constructor(body: BodyId, span: TimeBounds, window: TimeBounds);
26
+ }
15
27
  /** What a system needs to be loaded and described: its centre and where its index is (a dynamic import, so the index is its own chunk). */
16
28
  export interface MoonSystemConfig {
17
29
  readonly centre: BodyId;
@@ -77,7 +89,7 @@ export interface MoonSystem {
77
89
  }, rotation?: IauRotationElements): Trajectory;
78
90
  binding(body: BodyId, rotation?: IauRotationElements): StateSourceBinding;
79
91
  /** What a mapped moon's record says about its position, with its own worst figure from the fit check. */
80
- position(label: string, worstM: number): ReturnType<typeof createProvenance>;
92
+ position(label: string, worstM: number, span?: TimeBounds): ReturnType<typeof createProvenance>;
81
93
  /** The note said of every mapped moon whose face is held towards the centre. */
82
94
  readonly tidalLockNote: string;
83
95
  /** A mapped moon: sphere, tidal lock, valid for the fit span. */
@@ -90,6 +102,8 @@ export interface MappedMoonFacts {
90
102
  /** Absent when the source prints a mass only. */
91
103
  readonly gmKm3S2?: number;
92
104
  readonly worstM: number;
105
+ /** The years this moon's committed fits cover; absent means `MOON_FIT_SPAN`. */
106
+ readonly span?: TimeBounds;
93
107
  /** The physical-properties lines of the Horizons header the numbers are read from. */
94
108
  readonly header: string;
95
109
  /** Overrides the default dimensions sentence (a moon drawn at its mean radius that is not printed as one). */
@@ -6,6 +6,26 @@ import { createProvenance } from "../provenance.js";
6
6
  import { assertUtcUnixMs, createState } from "../state.js";
7
7
  /** The span the committed fits cover (T-096, T-114: 2010-01-01 to 2030-01-01 TDB, chunked per calendar year; the same for every system). */
8
8
  export const MOON_FIT_SPAN = Object.freeze({ startUtcMs: Date.UTC(2010, 0, 1, 0, 2), endUtcMs: Date.UTC(2029, 11, 31, 23, 58) });
9
+ /**
10
+ * The span of the main moons fitted back to 1950 (O-047 T-200). A mapped moon names which span its data holds with `MappedMoonFacts.span`;
11
+ * `tests/moonSpans.test.ts` compares every static span with the shipped index, so this is never a second source of truth that can drift.
12
+ */
13
+ export const HISTORICAL_MOON_FIT_SPAN = Object.freeze({ startUtcMs: Date.UTC(1950, 0, 1, 0, 2), endUtcMs: MOON_FIT_SPAN.endUtcMs });
14
+ const spanYears = (span) => `${new Date(span.startUtcMs + 300_000).getUTCFullYear()}-${new Date(span.endUtcMs + 300_000).getUTCFullYear()}`;
15
+ /** A scene's window reaches outside the years a loaded moon's positions cover (O-047 T-195): named once, at load, instead of a throw on every frame. */
16
+ export class MoonOutOfSpanError extends RangeError {
17
+ body;
18
+ span;
19
+ window;
20
+ constructor(body, span, window) {
21
+ const iso = (ms) => new Date(ms).toISOString().slice(0, 10);
22
+ super(`${body}'s positions cover ${iso(span.startUtcMs)} to ${iso(span.endUtcMs)}, but the scene runs ${iso(window.startUtcMs)} to ${iso(window.endUtcMs)}`);
23
+ this.name = "MoonOutOfSpanError";
24
+ this.body = body;
25
+ this.span = span;
26
+ this.window = window;
27
+ }
28
+ }
9
29
  /** The fit source every system cites: Horizons state vectors about the planet's system barycentre, fitted as piecewise Chebyshev series. */
10
30
  export const moonFitSource = (centreLabel) => `JPL Horizons API 1.2 (https://ssd.jpl.nasa.gov/api/horizons.api) state vectors about the ${centreLabel} system barycentre, ICRF, TDB, fitted as piecewise Chebyshev series; US Government work, credit NASA/JPL-Caltech Solar System Dynamics`;
11
31
  /** The chunk paths `load` needs, and a refusal naming any the build does not ship. */
@@ -16,6 +36,16 @@ export function chunksNeeded(ephemeris, load) {
16
36
  throw new Error(`the build does not ship the moon fit chunks this window needs: ${missing.slice(0, 5).join(", ")}${missing.length > 5 ? ` and ${missing.length - 5} more` : ""}`);
17
37
  return needed;
18
38
  }
39
+ /** Refuses a window that reaches outside the span any requested body's positions cover. */
40
+ function assertWithinSpan(set, request) {
41
+ for (const body of request.bodies) {
42
+ const span = set.boundsOf(body);
43
+ if (request.window.startUtcMs < span.startUtcMs || request.window.endUtcMs > span.endUtcMs)
44
+ throw new MoonOutOfSpanError(body, span, request.window);
45
+ }
46
+ }
47
+ /** How far past the window's end the loader also looks for shipped chunks (one chunk year; chunks the build does not ship are skipped). */
48
+ const AFTER_WINDOW_MS = 366 * 86_400_000;
19
49
  /** The fraction of one period of history loaded beyond the period itself (so a line of one period always has its samples). */
20
50
  const HISTORY_MARGIN = 1.05;
21
51
  /** A slice of decoding at most this long runs before the loader yields, so the page keeps painting (the boot loader animates). */
@@ -73,11 +103,11 @@ export function createMoonSystem(config) {
73
103
  return createState({ body, center: config.centre, timeUtcMs, positionKm: p, velocityKmS: v, orientation });
74
104
  },
75
105
  });
76
- const position = (label, worstM) => createProvenance({
106
+ const position = (label, worstM, span = MOON_FIT_SPAN) => createProvenance({
77
107
  sourceType: "ephemeris",
78
108
  sources: [config.fitSource],
79
- accuracy: `${label}'s position is JPL Horizons' (ephemeris ${config.ephemerisName}), reproduced by curve fits to within ${worstM} m at 1,001 checked dates 2010-2030. Horizons' own uncertainty is not stated in its output.`,
80
- notes: `Geometric position about ${config.centreLabel}'s centre; no light-time. Valid 2010-2030, the span of the committed fits.`,
109
+ accuracy: `${label}'s position is JPL Horizons' (ephemeris ${config.ephemerisName}), reproduced by curve fits to within ${worstM} m at independent checked dates over ${spanYears(span)}. Horizons' own uncertainty is not stated in its output.`,
110
+ notes: `Geometric position about ${config.centreLabel}'s centre; no light-time. Valid ${spanYears(span)}, the span of this body's committed fits.`,
81
111
  });
82
112
  return Object.freeze({
83
113
  config,
@@ -91,12 +121,20 @@ export function createMoonSystem(config) {
91
121
  loading = null;
92
122
  },
93
123
  load(request) {
94
- if (installed !== null)
124
+ if (installed !== null) {
125
+ try {
126
+ assertWithinSpan(installed, request);
127
+ }
128
+ catch (error) {
129
+ return Promise.reject(error);
130
+ }
95
131
  return Promise.resolve(installed);
132
+ }
96
133
  loading ??= (async () => {
97
134
  if (loadIndex === undefined)
98
135
  throw new Error(`${config.centreLabel}'s moon positions are not provided: pass the astraeus-data-${config.centre} package to mount (data: [...]), or call provideIndex`);
99
136
  const set = new ChebyshevEphemeris(parseEphemerisIndex(await loadIndex()));
137
+ assertWithinSpan(set, request);
100
138
  const needed = chunksNeeded(set, request);
101
139
  const fetchBytes = request.fetchBytes ?? fetchBytesOf;
102
140
  await decodeInto(set, needed, await Promise.all(needed.map(({ path }) => fetchBytes(request.chunkUrls[path]))));
@@ -106,7 +144,7 @@ export function createMoonSystem(config) {
106
144
  const extra = [];
107
145
  for (const body of request.history.bodies) {
108
146
  const lookback = Math.min(request.history.maxMs, HISTORY_MARGIN * osculatingPeriodMs(set, body, start));
109
- const from = Math.floor(Math.max(start - lookback, MOON_FIT_SPAN.startUtcMs));
147
+ const from = Math.floor(Math.max(start - lookback, set.boundsOf(body).startUtcMs));
110
148
  for (const chunk of set.chunksFor([body], from, start)) {
111
149
  if (loaded.has(chunk.path) || request.chunkUrls[chunk.path] === undefined)
112
150
  continue;
@@ -116,6 +154,19 @@ export function createMoonSystem(config) {
116
154
  }
117
155
  await decodeInto(set, extra, await Promise.all(extra.map(({ path }) => fetchBytes(request.chunkUrls[path]))));
118
156
  }
157
+ // A moon's orbit ring is centred on the clock, so at the window's last instant it reads ahead of it: also load the year after the window where the build ships it (never required).
158
+ const end = request.window.endUtcMs;
159
+ const after = [];
160
+ for (const body of request.bodies) {
161
+ const limit = set.boundsOf(body).endUtcMs;
162
+ if (limit <= end)
163
+ continue;
164
+ for (const chunk of set.chunksFor([body], end, Math.min(limit, end + AFTER_WINDOW_MS))) {
165
+ if (!needed.some(({ path }) => path === chunk.path) && request.chunkUrls[chunk.path] !== undefined && !after.some(({ path }) => path === chunk.path))
166
+ after.push(chunk);
167
+ }
168
+ }
169
+ await decodeInto(set, after, await Promise.all(after.map(({ path }) => fetchBytes(request.chunkUrls[path]))));
119
170
  installed = set;
120
171
  return set;
121
172
  })();
@@ -141,8 +192,8 @@ export function createMoonSystem(config) {
141
192
  accuracy: moon.dimensionsNote ?? `Mean radius ${moon.radiusKm} km and GM ${moon.gmKm3S2} km^3/s^2 as printed in the Horizons header; ${moon.label} is drawn as a sphere.`,
142
193
  notes: "Gravitational parameter in km^3/s^2.",
143
194
  }),
144
- position: position(moon.label, moon.worstM),
145
- validUtc: MOON_FIT_SPAN,
195
+ position: position(moon.label, moon.worstM, moon.span),
196
+ validUtc: moon.span ?? MOON_FIT_SPAN,
146
197
  orientationLimitations: Object.freeze([tidalLockNote]),
147
198
  }),
148
199
  });
@@ -38,7 +38,7 @@ export const PLUTO_EPHEMERIS = {
38
38
  provenance: createProvenance({
39
39
  sourceType: "ephemeris",
40
40
  sources: ["JPL Horizons API 1.2 (https://ssd.jpl.nasa.gov/api/horizons.api), COMMAND=9 (Pluto system barycentre) CENTER=500@10, VECTORS geometric ICRF km TDB, fetched 2026-10-20, fitted as piecewise Chebyshev series (tools/import/planet-fits.mjs); US Government work, credit NASA/JPL-Caltech Solar System Dynamics"],
41
- accuracy: "The system barycentre reproduces Horizons within 1 km at independent dates 1969 to 2045. Pluto's centre is that point plus its own offset from the system's fits (within a metre 2010 to 2030); with the system not loaded Pluto is drawn at the barycentre, up to about 2,100 km from its centre.",
41
+ accuracy: "The system barycentre reproduces Horizons within 1 km at independent dates 1950 to 2045. Pluto's centre is that point plus its own offset from the system's fits (within a metre 2010 to 2030); with the system not loaded Pluto is drawn at the barycentre, up to about 2,100 km from its centre.",
42
42
  notes: "Geometric position about the Sun's centre; no light-time or aberration.",
43
43
  }),
44
44
  knownLimitations: ["No velocity is modelled for planets, so they have no speed readout.", "Until Pluto's system fits are loaded Pluto sits at the system barycentre, up to about 2,100 km from its centre."],
@@ -1,7 +1,7 @@
1
1
  import { iauElementsFromRecord } from "../iauRotation.js";
2
2
  import { createPlanetSunTrajectory } from "./planetTrajectory.js";
3
3
  import { MARS } from "./mars.js";
4
- import { createMoonSystem, moonFitSource } from "./moonSystem.js";
4
+ import { createMoonSystem, HISTORICAL_MOON_FIT_SPAN, moonFitSource } from "./moonSystem.js";
5
5
  import { NEPTUNE, PLUTO, PLUTO_ROTATION, SATURN, URANUS } from "./outerPlanets.js";
6
6
  import charonOrbit from "../../../data/orbits/charon.json" with { type: "json" };
7
7
  import dioneOrbit from "../../../data/orbits/dione.json" with { type: "json" };
@@ -34,15 +34,15 @@ const marsMoon = (id, label, radiusKm, massKg, worstM, header) => MARS_MOON_SYST
34
34
  });
35
35
  export const PHOBOS = marsMoon("phobos", "Phobos", 11.08, 1.08e16, 0.0593, "Radius (km) = 13.1 x11.1 x9.3 Density (g cm^-3) = 1.90 +- 0.08; Mass (10^20 kg ) = 1.08 (10^-4)");
36
36
  export const DEIMOS = marsMoon("deimos", "Deimos", 6.2, 1.8e15, 0.5101, "Radius (km) = 7.8 x 6.0 x 5.1 Density (g cm^-3) = 1.76 +- 0.30; Mass (10^20 kg ) = 1.80 (10^-5)");
37
- const saturnMoon = (id, label, radiusKm, gmKm3S2, worstM, header) => SATURN_MOON_SYSTEM.mappedMoon({ id, label, radiusKm, gmKm3S2, worstM, header });
38
- export const MIMAS = saturnMoon("mimas", "Mimas", 198.8, 2.503489, 0.091, "Mean Radius (km) = 198.8 +- 1.5, GM (km^3/s^2) = 2.503489");
39
- export const ENCELADUS = saturnMoon("enceladus", "Enceladus", 252.3, 7.210367, 0.0874, "Mean Radius (km) = 252.3 +- 0.6, GM (km^3/s^2) = 7.210367");
40
- export const TETHYS = saturnMoon("tethys", "Tethys", 536.3, 41.21, 0.0865, "Mean Radius (km) = 536.3 +- 1.5, GM (km^3/s^2) = 41.21 +- 0.007");
41
- export const DIONE = saturnMoon("dione", "Dione", 562.5, 73.116, 0.0886, "Mean Radius (km) = 562.5 +- 5, GM (km^3/s^2) = 73.116 +- 0.02");
42
- export const RHEA = saturnMoon("rhea", "Rhea", 764.5, 153.94, 0.0725, "Mean Radius (km) = 764.5 +- 2, GM (km^3/s^2) = 153.94 +- 0.16");
43
- export const TITAN = saturnMoon("titan", "Titan", 2575.5, 8978.14, 0.55, "Mean Radius (km) = 2575.5 +- 2.0, GM (km^3/s^2) = 8978.14 +- 0.06");
44
- export const IAPETUS = saturnMoon("iapetus", "Iapetus", 734.5, 120.52, 0.0579, "Radius (km) = 734.5 +- 4.0, GM (km^3/s^2) = 120.52 +- 0.03");
45
- export const TRITON = NEPTUNE_MOON_SYSTEM.mappedMoon({ id: "triton", label: "Triton", radiusKm: 1352.6, gmKm3S2: 1428.495, worstM: 0.5121, header: "Mean radius (km) = 1352.6 +- 2.4, GM (km^3/s^2) = 1428.495 +- 0.62" });
37
+ const saturnMoon = (id, label, radiusKm, gmKm3S2, worstM, header) => SATURN_MOON_SYSTEM.mappedMoon({ id, label, radiusKm, gmKm3S2, worstM, header, span: HISTORICAL_MOON_FIT_SPAN });
38
+ export const MIMAS = saturnMoon("mimas", "Mimas", 198.8, 2.503489, 0.1777, "Mean Radius (km) = 198.8 +- 1.5, GM (km^3/s^2) = 2.503489");
39
+ export const ENCELADUS = saturnMoon("enceladus", "Enceladus", 252.3, 7.210367, 0.155, "Mean Radius (km) = 252.3 +- 0.6, GM (km^3/s^2) = 7.210367");
40
+ export const TETHYS = saturnMoon("tethys", "Tethys", 536.3, 41.21, 0.1733, "Mean Radius (km) = 536.3 +- 1.5, GM (km^3/s^2) = 41.21 +- 0.007");
41
+ export const DIONE = saturnMoon("dione", "Dione", 562.5, 73.116, 0.1322, "Mean Radius (km) = 562.5 +- 5, GM (km^3/s^2) = 73.116 +- 0.02");
42
+ export const RHEA = saturnMoon("rhea", "Rhea", 764.5, 153.94, 0.1271, "Mean Radius (km) = 764.5 +- 2, GM (km^3/s^2) = 153.94 +- 0.16");
43
+ export const TITAN = saturnMoon("titan", "Titan", 2575.5, 8978.14, 0.5305, "Mean Radius (km) = 2575.5 +- 2.0, GM (km^3/s^2) = 8978.14 +- 0.06");
44
+ export const IAPETUS = saturnMoon("iapetus", "Iapetus", 734.5, 120.52, 0.0715, "Radius (km) = 734.5 +- 4.0, GM (km^3/s^2) = 120.52 +- 0.03");
45
+ export const TRITON = NEPTUNE_MOON_SYSTEM.mappedMoon({ id: "triton", label: "Triton", radiusKm: 1352.6, gmKm3S2: 1428.495, worstM: 0.5118, span: HISTORICAL_MOON_FIT_SPAN, header: "Mean radius (km) = 1352.6 +- 2.4, GM (km^3/s^2) = 1428.495 +- 0.62" });
46
46
  export const CHARON = PLUTO_MOON_SYSTEM.mappedMoon({ id: "charon", label: "Charon", radiusKm: 606, gmKm3S2: 106.10, worstM: 0.6237, header: "GM (km^3/s^2) = 106.10 +- 0.3, Radius (km, IAU2015) = 606 +- 0.5" });
47
47
  /** The mapped moons by system, in the order the moon lists give them. */
48
48
  export const PLANET_MOON_DEFINITIONS = Object.freeze([PHOBOS, DEIMOS, MIMAS, ENCELADUS, TETHYS, DIONE, RHEA, TITAN, IAPETUS, TRITON, CHARON]);
@@ -27,6 +27,12 @@ export interface EphemerisBodyEntry {
27
27
  };
28
28
  readonly chunks: readonly EphemerisChunkEntry[];
29
29
  readonly provenance: Provenance;
30
+ /**
31
+ * The years this body's positions are claimed for, narrower than its chunks (UTC, from the body's `span: { fromUtc, toUtc }`). Absent: the chunks' extent
32
+ * applies, which is the set's span plus the fit's margin, as before. Either way the answered span is also limited by the centre's own. Bodies of one set
33
+ * may be fitted over different years: each one's chunks (and this) say which.
34
+ */
35
+ readonly span?: TimeBounds;
30
36
  }
31
37
  export interface EphemerisIndex {
32
38
  readonly format: typeof EPHEMERIS_INDEX_FORMAT;
@@ -64,7 +70,7 @@ export declare class ChebyshevEphemeris {
64
70
  }[];
65
71
  /** Hands in one chunk file's bytes; checked against the index entry. */
66
72
  addChunk(bodyId: BodyId, path: string, bytes: Uint8Array): void;
67
- /** The body's span in UTC, intersected with the centre's. */
73
+ /** The span this body can be asked for, in UTC: its chunks (and its own `span`, when it has one), the centre's, and the time-scale table's. */
68
74
  boundsOf(bodyId: BodyId): TimeBounds;
69
75
  /**
70
76
  * The earliest UTC time from which a body's centre-relative position can be asked for continuously up to `timeUtcMs` with the chunks
@@ -47,6 +47,19 @@ function text(value, where) {
47
47
  fail(`${where} must be a non-empty string`);
48
48
  return value;
49
49
  }
50
+ /** An optional `{ fromUtc, toUtc }` of ISO dates or date-times; absent is allowed, a malformed one is not. */
51
+ function parseSpan(raw, where) {
52
+ if (raw === undefined)
53
+ return undefined;
54
+ if (typeof raw !== "object" || raw === null)
55
+ fail(`${where} must be an object with fromUtc and toUtc`);
56
+ const { fromUtc, toUtc } = raw;
57
+ const startUtcMs = Date.parse(text(fromUtc, `${where}.fromUtc`));
58
+ const endUtcMs = Date.parse(text(toUtc, `${where}.toUtc`));
59
+ if (!Number.isFinite(startUtcMs) || !Number.isFinite(endUtcMs) || endUtcMs <= startUtcMs)
60
+ fail(`${where} must run from one valid date to a later one`);
61
+ return Object.freeze({ startUtcMs, endUtcMs });
62
+ }
50
63
  function parseBody(raw, index) {
51
64
  const where = `bodies[${index}]`;
52
65
  if (typeof raw !== "object" || raw === null)
@@ -89,7 +102,8 @@ function parseBody(raw, index) {
89
102
  catch (error) {
90
103
  fail(`${where}.provenance: ${error.message}`);
91
104
  }
92
- return { id: text(body.id, `${where}.id`), label: text(body.label, `${where}.label`), fit: { segmentSeconds, degree, quantumKm }, chunks, provenance };
105
+ const span = parseSpan(body.span, `${where}.span`);
106
+ return { id: text(body.id, `${where}.id`), label: text(body.label, `${where}.label`), fit: { segmentSeconds, degree, quantumKm }, chunks, provenance, ...(span === undefined ? {} : { span }) };
93
107
  }
94
108
  /** Validates an index read from JSON (STYLE-06: external data is checked here, once). */
95
109
  export function parseEphemerisIndex(raw) {
@@ -124,7 +138,7 @@ function utcMsForTdb(table, tdbS, inward) {
124
138
  let guess = J2000_NOON_UNIX_MS + tdbS * 1000;
125
139
  for (let pass = 0; pass < 3; pass += 1) {
126
140
  const tt = tdbS - tdbMinusTtSeconds(tdbS);
127
- guess = J2000_NOON_UNIX_MS + (tt - ttMinusUtcSeconds(table, Math.round(guess))) * 1000;
141
+ guess = J2000_NOON_UNIX_MS + (tt - ttMinusUtcSeconds(table, Math.min(table.validToUtcMs, Math.max(table.pieces[0].fromUtcMs, Math.round(guess))))) * 1000;
128
142
  }
129
143
  let ms = inward === "up" ? Math.ceil(guess) : Math.floor(guess);
130
144
  while (inward === "up" ? utcMsToTdbSeconds(table, ms) < tdbS : utcMsToTdbSeconds(table, ms) > tdbS)
@@ -140,10 +154,11 @@ export class ChebyshevEphemeris {
140
154
  this.index = index;
141
155
  for (const entry of index.bodies) {
142
156
  const last = entry.chunks[entry.chunks.length - 1];
157
+ const claimed = entry.span;
143
158
  this.#bodies.set(entry.id, {
144
159
  entry,
145
- startTdbS: entry.chunks[0].startTdbS,
146
- endTdbS: last.startTdbS + last.segmentCount * entry.fit.segmentSeconds,
160
+ startTdbS: claimed === undefined ? entry.chunks[0].startTdbS : Math.max(entry.chunks[0].startTdbS, utcMsToTdbSeconds(index.timeScale, claimed.startUtcMs)),
161
+ endTdbS: Math.min(last.startTdbS + last.segmentCount * entry.fit.segmentSeconds, claimed === undefined ? Infinity : utcMsToTdbSeconds(index.timeScale, claimed.endUtcMs)),
147
162
  chunks: entry.chunks.map(() => null),
148
163
  last: null,
149
164
  });
@@ -195,11 +210,13 @@ export class ChebyshevEphemeris {
195
210
  quantumKm: body.entry.fit.quantumKm,
196
211
  });
197
212
  }
198
- /** The body's span in UTC, intersected with the centre's. */
213
+ /** The span this body can be asked for, in UTC: its chunks (and its own `span`, when it has one), the centre's, and the time-scale table's. */
199
214
  boundsOf(bodyId) {
200
215
  const body = this.#body(bodyId);
201
- const start = Math.max(body.startTdbS, this.#centre.startTdbS);
202
- const end = Math.min(body.endTdbS, this.#centre.endTdbS);
216
+ // A chunk may run a little past the time-scale table (Pluto's last year ends a day after it): the table's own ends, less a second so the conversion back stays inside it, limit the answer.
217
+ const { timeScale } = this.index;
218
+ const start = Math.max(body.startTdbS, this.#centre.startTdbS, utcMsToTdbSeconds(timeScale, timeScale.pieces[0].fromUtcMs) + 1);
219
+ const end = Math.min(body.endTdbS, this.#centre.endTdbS, utcMsToTdbSeconds(timeScale, timeScale.validToUtcMs) - 1);
203
220
  return Object.freeze({
204
221
  startUtcMs: utcMsForTdb(this.index.timeScale, start, "up"),
205
222
  endUtcMs: utcMsForTdb(this.index.timeScale, end, "down"),
@@ -24,5 +24,13 @@ export declare class SimulationClock {
24
24
  readonly startUtcMs: number;
25
25
  readonly endUtcMs: number;
26
26
  }): boolean;
27
+ /**
28
+ * Playback that has run past the end of `window` (or before its start, at a negative rate) stops on that edge: the clock is moved to it and paused. Returns whether it stopped.
29
+ * Does nothing while paused, so a person who seeks outside the window is not moved. The playing counterpart of `wrapWithin`.
30
+ */
31
+ stopWithin(window: {
32
+ readonly startUtcMs: number;
33
+ readonly endUtcMs: number;
34
+ }): boolean;
27
35
  setRate(rate: number): void;
28
36
  }
package/src/core/clock.js CHANGED
@@ -71,6 +71,20 @@ export class SimulationClock {
71
71
  this.seek(Math.trunc(folded));
72
72
  return true;
73
73
  }
74
+ /**
75
+ * Playback that has run past the end of `window` (or before its start, at a negative rate) stops on that edge: the clock is moved to it and paused. Returns whether it stopped.
76
+ * Does nothing while paused, so a person who seeks outside the window is not moved. The playing counterpart of `wrapWithin`.
77
+ */
78
+ stopWithin(window) {
79
+ if (!this.#playing)
80
+ return false;
81
+ const now = this.now();
82
+ if (now >= window.startUtcMs && now <= window.endUtcMs)
83
+ return false;
84
+ this.seek(now > window.endUtcMs ? window.endUtcMs : window.startUtcMs);
85
+ this.pause();
86
+ return true;
87
+ }
74
88
  setRate(rate) {
75
89
  if (!Number.isFinite(rate) || rate === 0) {
76
90
  throw new RangeError("playback rate must be a finite, non-zero number");
@@ -0,0 +1,24 @@
1
+ import type { SimulationClock } from "./clock.js";
2
+ /**
3
+ * One stretch of the timeline with its own playback rate: full `rate` from `fromUtcMs` to `toUtcMs`, easing back to the surrounding rate over
4
+ * `rampMs` of simulated time on either side. The ramp is in simulated time, so the paced rate stays a pure function of the clock's time.
5
+ */
6
+ export interface PaceZone {
7
+ readonly fromUtcMs: number;
8
+ readonly toUtcMs: number;
9
+ readonly rate: number;
10
+ readonly rampMs: number;
11
+ }
12
+ /** A scene's pacing: the rate outside every zone and its zones. Where zones overlap the slowest wins whatever order they are listed in (`pacedRate` lays the fastest first and the slowest last). */
13
+ export interface Pacing {
14
+ readonly baseRate: number;
15
+ readonly zones: readonly PaceZone[];
16
+ }
17
+ /**
18
+ * The playback rate at `timeUtcMs`: the base rate, with each zone laid over it in turn, fastest first so the slowest wins where zones meet (order-independent). A zone's weight is 1 inside it and falls to 0 over its ramp
19
+ * (smoothstep); the rate blends in log space, so a jump of several orders of magnitude eases evenly. Every weight is continuous in time, so the
20
+ * result is continuous too. A pure function of its arguments: nothing about the State changes.
21
+ */
22
+ export declare function pacedRate(pacing: Pacing, timeUtcMs: number): number;
23
+ /** Sets the clock to the paced rate for its current time (skipped when it already runs at it). */
24
+ export declare function applyPacing(clock: SimulationClock, pacing: Pacing): void;
@@ -0,0 +1,35 @@
1
+ const slowestLast = new WeakMap();
2
+ /** The zones fastest first, so the slowest is laid last and wins wherever zones meet, ramps included. Cached per zone list. */
3
+ function inLayerOrder(zones) {
4
+ let sorted = slowestLast.get(zones);
5
+ if (sorted === undefined) {
6
+ sorted = [...zones].sort((a, b) => b.rate - a.rate);
7
+ slowestLast.set(zones, sorted);
8
+ }
9
+ return sorted;
10
+ }
11
+ const smooth = (x) => x * x * (3 - 2 * x);
12
+ /**
13
+ * The playback rate at `timeUtcMs`: the base rate, with each zone laid over it in turn, fastest first so the slowest wins where zones meet (order-independent). A zone's weight is 1 inside it and falls to 0 over its ramp
14
+ * (smoothstep); the rate blends in log space, so a jump of several orders of magnitude eases evenly. Every weight is continuous in time, so the
15
+ * result is continuous too. A pure function of its arguments: nothing about the State changes.
16
+ */
17
+ export function pacedRate(pacing, timeUtcMs) {
18
+ let logRate = Math.log(pacing.baseRate);
19
+ let touched = false;
20
+ for (const zone of inLayerOrder(pacing.zones)) {
21
+ const distance = timeUtcMs < zone.fromUtcMs ? zone.fromUtcMs - timeUtcMs : timeUtcMs > zone.toUtcMs ? timeUtcMs - zone.toUtcMs : 0;
22
+ const weight = distance === 0 ? 1 : distance >= zone.rampMs ? 0 : smooth(1 - distance / zone.rampMs);
23
+ if (weight > 0)
24
+ touched = true;
25
+ if (weight > 0)
26
+ logRate += (Math.log(zone.rate) - logRate) * weight;
27
+ }
28
+ return touched ? Math.exp(logRate) : pacing.baseRate; // untouched: exactly the base, not its log round trip
29
+ }
30
+ /** Sets the clock to the paced rate for its current time (skipped when it already runs at it). */
31
+ export function applyPacing(clock, pacing) {
32
+ const rate = pacedRate(pacing, clock.now());
33
+ if (rate !== clock.rate)
34
+ clock.setRate(rate);
35
+ }
@@ -1,7 +1,10 @@
1
1
  import { type PlanetModels } from "./planetSeries.js";
2
+ import type { TimeBounds } from "./trajectory.js";
3
+ /** The years the stored planet fits cover (UTC): from the time-scale table's first piece to where it ends, which the importer sets to the fitted span. */
4
+ export declare function planetSeriesSpan(): TimeBounds;
2
5
  /**
3
6
  * The planet models from the stored curve fits (`data/ephemerides/planets/`, O-025 T-101): heliocentric ecliptic-J2000 positions as piecewise
4
7
  * Chebyshev series in TT, refitted from Orb's full VSOP87A series within 1 km (Pluto: fitted to Horizons states; tools/import/planet-fits.mjs). UTC to TT uses the table stored
5
- * beside them. Dates outside the fitted span (1969 to 2045) throw rather than extrapolate. Only planetSeries.ts imports this, lazily.
8
+ * beside them. Dates outside the fitted span (1950 to 2045) throw rather than extrapolate. Only planetSeries.ts imports this, lazily.
6
9
  */
7
10
  export declare function createPlanetModels(): PlanetModels;
@@ -25,10 +25,15 @@ function planetModel(chunk, table) {
25
25
  },
26
26
  };
27
27
  }
28
+ /** The years the stored planet fits cover (UTC): from the time-scale table's first piece to where it ends, which the importer sets to the fitted span. */
29
+ export function planetSeriesSpan() {
30
+ const table = fits.timeScale;
31
+ return Object.freeze({ startUtcMs: table.pieces[0].fromUtcMs, endUtcMs: table.validToUtcMs });
32
+ }
28
33
  /**
29
34
  * The planet models from the stored curve fits (`data/ephemerides/planets/`, O-025 T-101): heliocentric ecliptic-J2000 positions as piecewise
30
35
  * Chebyshev series in TT, refitted from Orb's full VSOP87A series within 1 km (Pluto: fitted to Horizons states; tools/import/planet-fits.mjs). UTC to TT uses the table stored
31
- * beside them. Dates outside the fitted span (1969 to 2045) throw rather than extrapolate. Only planetSeries.ts imports this, lazily.
36
+ * beside them. Dates outside the fitted span (1950 to 2045) throw rather than extrapolate. Only planetSeries.ts imports this, lazily.
32
37
  */
33
38
  export function createPlanetModels() {
34
39
  const table = fits.timeScale;
@@ -1,3 +1,4 @@
1
+ import type { TimeBounds } from "./trajectory.js";
1
2
  /** Planets the astronomy adapter has a heliocentric model for (Saturn to Pluto added by O-033 T-114). */
2
3
  export type PlanetId = "mercury" | "venus" | "mars" | "jupiter" | "saturn" | "uranus" | "neptune" | "pluto";
3
4
  export declare const PLANET_IDS: readonly PlanetId[];
@@ -24,5 +25,7 @@ export type PlanetModels = {
24
25
  export declare function loadPlanetSeries(): Promise<void>;
25
26
  /** Whether the planet series have finished loading. */
26
27
  export declare function planetSeriesLoaded(): boolean;
28
+ /** The years the loaded planet series cover (UTC); throws before `loadPlanetSeries()` resolved. A date outside it throws rather than extrapolate. */
29
+ export declare function planetSeriesSpan(): TimeBounds;
27
30
  /** The loaded planet models; throws before `loadPlanetSeries()` resolved rather than falling back to the compact tables. */
28
31
  export declare function planetModels(): PlanetModels;
@@ -4,6 +4,7 @@ export function isPlanetId(id) {
4
4
  }
5
5
  let loading;
6
6
  let models;
7
+ let span;
7
8
  /**
8
9
  * Builds the planet models, once, from the stored curve fits of the full VSOP87A series (Pluto: of JPL Horizons states) (O-025 T-101, O-033 T-114; the library's compact
9
10
  * default tables are off by tens of thousands of km, docs/ASTRONOMY_VALIDATION.md, and its full series were about 0.8 MB of code).
@@ -11,13 +12,19 @@ let models;
11
12
  * downloads them (I-022).
12
13
  */
13
14
  export function loadPlanetSeries() {
14
- loading ??= import("./planetModels.js").then((module) => { models = module.createPlanetModels(); });
15
+ loading ??= import("./planetModels.js").then((module) => { models = module.createPlanetModels(); span = module.planetSeriesSpan(); });
15
16
  return loading;
16
17
  }
17
18
  /** Whether the planet series have finished loading. */
18
19
  export function planetSeriesLoaded() {
19
20
  return models !== undefined;
20
21
  }
22
+ /** The years the loaded planet series cover (UTC); throws before `loadPlanetSeries()` resolved. A date outside it throws rather than extrapolate. */
23
+ export function planetSeriesSpan() {
24
+ if (span === undefined)
25
+ throw new Error("the planet series are not loaded: await loadPlanetSeries() before asking their span");
26
+ return span;
27
+ }
21
28
  /** The loaded planet models; throws before `loadPlanetSeries()` resolved rather than falling back to the compact tables. */
22
29
  export function planetModels() {
23
30
  if (models === undefined)
@@ -31,3 +31,5 @@ export declare function createWindows(input: readonly TimelineWindow[]): readonl
31
31
  export declare function rateAt(window: TimelineWindow, timeUtcMs: number): number | null;
32
32
  /** The provenance span covering a time (a shared boundary belongs to the later span); null if none. */
33
33
  export declare function provenanceAt(window: TimelineWindow, timeUtcMs: number): Provenance | null;
34
+ /** The provenance of the span (sorted, not overlapping) covering a time; null if none. Windows and paths share it. */
35
+ export declare function spanProvenanceAt(spans: readonly WindowProvenanceSpan[], timeUtcMs: number): Provenance | null;