astraeus 0.8.1 → 0.9.1

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 (131) hide show
  1. package/CHANGELOG.md +85 -0
  2. package/README.md +104 -31
  3. package/package.json +1 -1
  4. package/src/api/AstraeusScene.d.ts +1 -1
  5. package/src/api/AstraeusScene.js +4 -1
  6. package/src/api/AstraeusScene.node.js +4 -1
  7. package/src/api/assembleScene.d.ts +2 -0
  8. package/src/api/assembleScene.js +28 -6
  9. package/src/api/cameraRequest.d.ts +15 -0
  10. package/src/api/cameraRequest.js +89 -0
  11. package/src/api/errors.d.ts +9 -1
  12. package/src/api/index.d.ts +6 -3
  13. package/src/api/look.d.ts +49 -0
  14. package/src/api/lookInput.d.ts +1 -1
  15. package/src/api/lookInput.js +6 -1
  16. package/src/api/planBodies.d.ts +2 -1
  17. package/src/api/planBodies.js +6 -1
  18. package/src/api/planCamera.d.ts +35 -7
  19. package/src/api/planCamera.js +94 -11
  20. package/src/api/planPaths.d.ts +2 -0
  21. package/src/api/planPaths.js +14 -9
  22. package/src/api/planSkyFigures.d.ts +22 -0
  23. package/src/api/planSkyFigures.js +145 -0
  24. package/src/api/planStory.d.ts +2 -2
  25. package/src/api/planStory.js +14 -9
  26. package/src/api/planViews.js +1 -1
  27. package/src/api/providerPathTimes.d.ts +10 -0
  28. package/src/api/providerPathTimes.js +109 -0
  29. package/src/api/scene.d.ts +23 -4
  30. package/src/api/scene.js +23 -5
  31. package/src/api/sceneReads.d.ts +21 -2
  32. package/src/api/shownDuring.d.ts +12 -0
  33. package/src/api/shownDuring.js +30 -0
  34. package/src/api/skyFigureInput.d.ts +45 -0
  35. package/src/api/skyFigureInput.js +1 -0
  36. package/src/api/skyTraceInput.d.ts +33 -0
  37. package/src/api/skyTraceInput.js +45 -0
  38. package/src/api/story.d.ts +13 -4
  39. package/src/api/story.js +45 -2
  40. package/src/api/viewerCamera.d.ts +4 -3
  41. package/src/api/viewerCamera.js +10 -32
  42. package/src/api/viewerHandle.d.ts +27 -4
  43. package/src/api/viewerHandle.js +6 -0
  44. package/src/api/viewerLink.d.ts +49 -4
  45. package/src/api/viewerLink.js +25 -0
  46. package/src/api/viewerPanels.d.ts +26 -0
  47. package/src/api/viewerPanels.js +42 -0
  48. package/src/api/viewerSelection.d.ts +1 -1
  49. package/src/api/viewerSelection.js +3 -3
  50. package/src/app/App.js +129 -30
  51. package/src/app/App.node.js +129 -30
  52. package/src/app/AstraeusScene.d.ts +20 -5
  53. package/src/app/AstraeusScene.js +3 -3
  54. package/src/app/CameraController.d.ts +19 -1
  55. package/src/app/CameraController.js +38 -11
  56. package/src/app/DeveloperSettings.d.ts +11 -3
  57. package/src/app/DeveloperSettings.js +13 -3
  58. package/src/app/SceneLabels.d.ts +20 -2
  59. package/src/app/SceneLabels.js +46 -6
  60. package/src/app/SkyFiguresView.d.ts +56 -0
  61. package/src/app/SkyFiguresView.js +242 -0
  62. package/src/app/StoryMarkers.d.ts +2 -2
  63. package/src/app/StoryMarkers.js +2 -2
  64. package/src/app/displaySwitches.d.ts +13 -3
  65. package/src/app/displaySwitches.js +17 -3
  66. package/src/app/experienceDefinition.d.ts +9 -3
  67. package/src/app/experienceDefinition.js +4 -2
  68. package/src/app/labelStyle.d.ts +17 -0
  69. package/src/app/labelStyle.js +13 -0
  70. package/src/app/liveLook.js +8 -0
  71. package/src/app/look.d.ts +9 -5
  72. package/src/app/look.js +11 -0
  73. package/src/app/lookOut.d.ts +32 -0
  74. package/src/app/lookOut.js +50 -0
  75. package/src/app/sceneCamera.d.ts +5 -3
  76. package/src/app/sceneCamera.js +66 -3
  77. package/src/app/sceneContentsHooks.d.ts +2 -1
  78. package/src/app/sceneContentsHooks.js +3 -2
  79. package/src/app/sceneFrame.d.ts +22 -4
  80. package/src/app/sceneFrame.js +67 -22
  81. package/src/app/sceneFraming.d.ts +7 -0
  82. package/src/app/sceneFraming.js +12 -0
  83. package/src/app/sceneHooks.d.ts +2 -0
  84. package/src/app/sceneHooks.js +4 -1
  85. package/src/app/scenePicking.d.ts +20 -0
  86. package/src/app/scenePicking.js +49 -0
  87. package/src/app/scenePointer.d.ts +3 -1
  88. package/src/app/scenePointer.js +3 -2
  89. package/src/app/skyFigures.d.ts +73 -0
  90. package/src/app/skyFigures.js +50 -0
  91. package/src/app/style.css +2 -1
  92. package/src/app/viewHiding.d.ts +10 -1
  93. package/src/app/viewHiding.js +30 -1
  94. package/src/app/viewLink.d.ts +8 -8
  95. package/src/app/viewLink.js +24 -4
  96. package/src/app/viewerPort.d.ts +30 -3
  97. package/src/assets/sky.d.ts +13 -4
  98. package/src/assets/sky.js +33 -8
  99. package/src/assets/stars/hyg-v42-naked-eye.json +1 -1
  100. package/src/core/bodies/moonSystem.js +1 -15
  101. package/src/core/lookValues.d.ts +9 -0
  102. package/src/core/lookValues.js +24 -0
  103. package/src/core/pacing.d.ts +38 -6
  104. package/src/core/pacing.js +141 -21
  105. package/src/core/readBytes.d.ts +1 -0
  106. package/src/core/readBytes.js +15 -0
  107. package/src/core/skyTrace.d.ts +49 -0
  108. package/src/core/skyTrace.js +39 -0
  109. package/src/core/startView.d.ts +39 -0
  110. package/src/core/startView.js +56 -0
  111. package/src/core/storyPanels.d.ts +51 -3
  112. package/src/core/storyPanels.js +52 -12
  113. package/src/shell/AstraeusShell.d.ts +17 -6
  114. package/src/shell/AstraeusShell.js +100 -26
  115. package/src/shell/AstraeusShell.node.js +100 -26
  116. package/src/shell/ObjectControls.js +11 -8
  117. package/src/shell/StoryPanelView.d.ts +12 -3
  118. package/src/shell/StoryPanelView.js +2 -2
  119. package/src/shell/experience.d.ts +31 -0
  120. package/src/shell/experience.js +4 -1
  121. package/src/shell/infoModel.js +9 -1
  122. package/src/shell/objectModel.d.ts +9 -4
  123. package/src/shell/objectModel.js +16 -5
  124. package/src/shell/phone.css +1 -1
  125. package/src/shell/storyPanels.d.ts +1 -1
  126. package/src/shell/storyPanels.js +1 -1
  127. package/src/shell/style.css +9 -1
  128. package/src/shell/topBarIcons.d.ts +1 -0
  129. package/src/shell/topBarIcons.js +1 -0
  130. package/src/shell/useStoryPanels.d.ts +9 -6
  131. package/src/shell/useStoryPanels.js +10 -6
@@ -3,6 +3,7 @@ import { ChebyshevEphemeris, parseEphemerisIndex } from "../chebyshevEphemeris.j
3
3
  import { iauOrientation } from "../iauRotation.js";
4
4
  import { periodAboutBalanceS } from "../orbitPeriod.js";
5
5
  import { NotLoadedError } from "../planetSeries.js";
6
+ import { fetchBytesOf } from "../readBytes.js";
6
7
  import { createProvenance } from "../provenance.js";
7
8
  import { assertUtcUnixMs, createState } from "../state.js";
8
9
  /** 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). */
@@ -53,21 +54,6 @@ const HISTORY_MARGIN = 1.05;
53
54
  const DECODE_SLICE_MS = 8;
54
55
  /** Half the time step (s) the orbit-derived tidal-lock orientation looks along the orbit, as Io's mean-element orientation did. */
55
56
  const ORIENTATION_STEP_S = 1800;
56
- /** Reads a `file:` address with Node's own module (found at run time, so a browser bundle never resolves it); Node's `fetch` does not serve `file:`. */
57
- async function readFileUrl(url) {
58
- const nodeFs = globalThis.process?.getBuiltinModule?.("node:fs/promises");
59
- if (nodeFs === undefined)
60
- throw new Error(`moon fit chunk ${url}: this runtime cannot read a file: address`);
61
- return new Uint8Array(await nodeFs.readFile(new URL(url)));
62
- }
63
- const fetchBytesOf = async (url) => {
64
- if (url.startsWith("file:"))
65
- return readFileUrl(url);
66
- const response = await fetch(url);
67
- if (!response.ok)
68
- throw new Error(`moon fit chunk ${url}: HTTP ${response.status}`);
69
- return new Uint8Array(await response.arrayBuffer());
70
- };
71
57
  export function createMoonSystem(config) {
72
58
  let installed = null;
73
59
  let loadIndex = config.loadIndex;
@@ -0,0 +1,9 @@
1
+ /** True for a hex colour, a comma-form `rgb()`, `rgba()`, `hsl()` or `hsla()` or a named colour. */
2
+ export declare function isCssColour(value: unknown): value is string;
3
+ /** True for a non-blank font family text (any CSS font-family list, or `inherit`). */
4
+ export declare function isFontFamily(value: unknown): value is string;
5
+ /** Label size range in pixels: small enough for a crowded sky, large enough to read on a phone. */
6
+ export declare const LABEL_SIZE_LIMITS: Readonly<{
7
+ min: 8;
8
+ max: 24;
9
+ }>;
@@ -0,0 +1,24 @@
1
+ // What a look may hold (O-065 T-296): whether a text is a CSS colour the viewer would take, checked here without a browser so a bad colour fails at `setLook` / `addSkyFigures` in Node too (API-04, API-05).
2
+ const NAMED = new Set(("aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan "
3
+ + "darkgoldenrod darkgray darkgreen darkgrey darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink "
4
+ + "deepskyblue dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray green greenyellow grey honeydew hotpink indianred indigo ivory khaki lavender lavenderblush "
5
+ + "lawngreen lemonchiffon lightblue lightcoral lightcyan lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen lightskyblue lightslategray lightslategrey lightsteelblue lightyellow "
6
+ + "lime limegreen linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin "
7
+ + "navajowhite navy oldlace olive olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum powderblue purple rebeccapurple red rosybrown royalblue "
8
+ + "saddlebrown salmon sandybrown seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen steelblue tan teal thistle tomato turquoise violet wheat white whitesmoke yellow yellowgreen").split(" "));
9
+ const HEX = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
10
+ // The comma forms only: the drawing library that paints the lines reads these (and hex and names), not the space-separated or newer colour functions.
11
+ const FUNCTION = /^(?:rgb|hsl)a?\(\s*[\d.]+%?\s*,\s*[\d.]+%?\s*,\s*[\d.]+%?\s*(?:,\s*[\d.]+%?\s*)?\)$/i;
12
+ /** True for a hex colour, a comma-form `rgb()`, `rgba()`, `hsl()` or `hsla()` or a named colour. */
13
+ export function isCssColour(value) {
14
+ if (typeof value !== "string")
15
+ return false;
16
+ const text = value.trim();
17
+ return HEX.test(text) || FUNCTION.test(text) || NAMED.has(text.toLowerCase());
18
+ }
19
+ /** True for a non-blank font family text (any CSS font-family list, or `inherit`). */
20
+ export function isFontFamily(value) {
21
+ return typeof value === "string" && value.trim() !== "" && !/[;{}]/.test(value);
22
+ }
23
+ /** Label size range in pixels: small enough for a crowded sky, large enough to read on a phone. */
24
+ export const LABEL_SIZE_LIMITS = Object.freeze({ min: 8, max: 24 });
@@ -32,15 +32,19 @@ export declare function zonesInView<Z extends EventZone>(zones: readonly Z[], sh
32
32
  * Span zones carry no event and never count. A pure function of its arguments.
33
33
  */
34
34
  export declare function activeEventZones(zones: readonly EventZone[], shown: ShownEvents, timeUtcMs: number): readonly string[];
35
- /** 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). */
35
+ /**
36
+ * A scene's pacing: the rate outside every zone and its zones. Faster spans (zones with no event) set the cruise over the base and the faster wins where they meet; slower spans and event rules ease down from the cruise, and where they overlap or their ramps meet the slowest
37
+ * speed any one of them alone would give wins, whatever order they are listed in.
38
+ */
36
39
  export interface Pacing {
37
40
  readonly baseRate: number;
38
41
  readonly zones: readonly PaceZone[];
39
42
  }
40
43
  /**
41
- * 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
42
- * (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
43
- * result is continuous too. A pure function of its arguments: nothing about the State changes.
44
+ * The playback rate at `timeUtcMs`, all blends in log space by the zone weight. The cruise is the base, raised to the fastest of what each span faster than the base gives alone (the faster wins where such spans meet).
45
+ * The rate is the slowest of the cruise and of what each slower span (rate at or under the base) and each event rule touching that time gives easing from the cruise toward its rate (the slowest wins where they meet; a piece
46
+ * whose blend is faster than the cruise changes nothing). Each term equals its underlying value where its weight is 0, so the rate is continuous at every zone and ramp edge, and it does not depend on the order of the zones.
47
+ * Untouched, it is exactly the base. A pure function of its arguments: nothing about the State changes.
44
48
  */
45
49
  export declare function pacedRate(pacing: Pacing, timeUtcMs: number, shown?: ShownEvents): number;
46
50
  /** How long, in real milliseconds, a change of the paced rate that comes from a view switch takes to ease in. */
@@ -50,10 +54,38 @@ export interface PaceView {
50
54
  shown?: ShownEvents;
51
55
  ease?: {
52
56
  readonly fromRate: number;
53
- readonly startMs: number;
57
+ readonly startMs: number; /** log(fromRate) - log(paced rate at the switch): the change the switch itself caused; set on first use. */
58
+ k0?: number;
59
+ };
60
+ /** Where `stepPacing` left the clock: its time and rate, and the real time it did so. Absent until the first step, and cleared by a seek or any other move of the clock the step did not make. */
61
+ last?: {
62
+ readonly timeUtcMs: number;
63
+ readonly rate: number;
64
+ readonly nowMs: number;
54
65
  };
55
66
  }
56
67
  /** Starts the ease from the clock's present rate; the next `applyPacing` calls blend from it to the paced rate over `PACE_EASE_MS`. */
57
68
  export declare function startPaceEase(view: PaceView, fromRate: number, nowMs: number): void;
58
- /** Sets the clock to the paced rate for its current time (skipped when it already runs at it); mid-ease it is the log-space blend from the ease's start rate. */
69
+ /** The ease's own change, fixed once at the switch (the first time it is read, at the switch's time): log(start rate) minus log(the new view's paced rate there). */
70
+ export declare function easeShift(view: PaceView, timeUtcMs: number, pacing: Pacing): number;
71
+ /** Sets the clock to the paced rate for its current time (skipped when it already runs at it); mid-ease the switch's own change decays over it: the paced shape times exp(k0 * (1 - weight)), so a zone reached during the ease still slows playback. */
59
72
  export declare function applyPacing(clock: SimulationClock, pacing: Pacing, view?: PaceView, nowMs?: number): void;
73
+ /** The most sub-steps one `pacedAdvance` call takes; real time left over after them is dropped, so a frame that long (a tab left hidden) slows the clock rather than skipping a zone. */
74
+ export declare const MAX_PACE_STEPS = 4096;
75
+ /** A view-switch ease as `pacedAdvance` reads it: the switch's own change k0 (see `easeShift`) and how far into its `PACE_EASE_MS` it already is, in real milliseconds, when the advance begins. */
76
+ export interface AdvanceEase {
77
+ readonly k0: number;
78
+ readonly elapsedMs: number;
79
+ }
80
+ /**
81
+ * The time `realElapsedMs` of real time after `fromUtcMs` when the clock runs at `pacedRate` throughout (`direction` -1 runs it backward): the rate is integrated, not read once, so a long frame still slows down
82
+ * through every zone and ramp it crosses. Each sub-step stops at the next zone or ramp edge, covers at most 1/32 of a ramp, and is timed by the trapezoid rule on the rates at its two ends (the far one a millisecond short).
83
+ * With an `ease` (a view switch changing the rate) the rate integrated is the eased one, and a sub-step also covers at most 1/32 of the ease's real time while it runs.
84
+ * At most `MAX_PACE_STEPS` sub-steps; the result is a whole millisecond. A pure function of its arguments.
85
+ */
86
+ export declare function pacedAdvance(pacing: Pacing, fromUtcMs: number, realElapsedMs: number, shown?: ShownEvents, direction?: 1 | -1, ease?: AdvanceEase): number;
87
+ /**
88
+ * One pacing step per frame: moves the clock from where the last step left it by `pacedAdvance` over the real time since, then sets the paced rate for the new time (`applyPacing`'s job). Falls back to `applyPacing`
89
+ * (one rate for the frame) on the first step, while paused, or when the clock was moved or re-rated since the last step. The clock is moved through its public `seek` and `setRate`.
90
+ */
91
+ export declare function stepPacing(clock: SimulationClock, pacing: Pacing, view: PaceView, nowMs?: number): void;
@@ -33,34 +33,59 @@ export function activeEventZones(zones, shown, timeUtcMs) {
33
33
  }
34
34
  return ids;
35
35
  }
36
- const slowestLast = new WeakMap();
37
- /** The zones fastest first, so the slowest is laid last and wins wherever zones meet, ramps included. Cached per zone list. */
38
- function inLayerOrder(zones) {
39
- let sorted = slowestLast.get(zones);
40
- if (sorted === undefined) {
41
- sorted = [...zones].sort((a, b) => b.rate - a.rate);
42
- slowestLast.set(zones, sorted);
36
+ const smooth = (x) => x * x * (3 - 2 * x);
37
+ const layered = new WeakMap();
38
+ function layersOf(zones) {
39
+ let layers = layered.get(zones);
40
+ if (layers === undefined) {
41
+ layers = { spans: zones.filter((zone) => zone.eventId === undefined), rules: zones.filter((zone) => zone.eventId !== undefined) };
42
+ layered.set(zones, layers);
43
43
  }
44
- return sorted;
44
+ return layers;
45
+ }
46
+ /** The weight of `zone` at `timeUtcMs`: 1 inside it, falling to 0 over its ramp (smoothstep). */
47
+ function zoneWeight(zone, timeUtcMs) {
48
+ const distance = timeUtcMs < zone.fromUtcMs ? zone.fromUtcMs - timeUtcMs : timeUtcMs > zone.toUtcMs ? timeUtcMs - zone.toUtcMs : 0;
49
+ return distance === 0 ? 1 : distance >= zone.rampMs ? 0 : smooth(1 - distance / zone.rampMs);
45
50
  }
46
- const smooth = (x) => x * x * (3 - 2 * x);
47
51
  /**
48
- * 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
49
- * (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
50
- * result is continuous too. A pure function of its arguments: nothing about the State changes.
52
+ * The playback rate at `timeUtcMs`, all blends in log space by the zone weight. The cruise is the base, raised to the fastest of what each span faster than the base gives alone (the faster wins where such spans meet).
53
+ * The rate is the slowest of the cruise and of what each slower span (rate at or under the base) and each event rule touching that time gives easing from the cruise toward its rate (the slowest wins where they meet; a piece
54
+ * whose blend is faster than the cruise changes nothing). Each term equals its underlying value where its weight is 0, so the rate is continuous at every zone and ramp edge, and it does not depend on the order of the zones.
55
+ * Untouched, it is exactly the base. A pure function of its arguments: nothing about the State changes.
51
56
  */
52
57
  export function pacedRate(pacing, timeUtcMs, shown) {
53
- let logRate = Math.log(pacing.baseRate);
58
+ const { spans, rules } = layersOf(pacing.zones);
59
+ const logBase = Math.log(pacing.baseRate);
54
60
  let touched = false;
55
- for (const zone of inLayerOrder(pacing.zones)) {
61
+ let logCruise = logBase;
62
+ for (const zone of spans) {
63
+ if (zone.rate <= pacing.baseRate)
64
+ continue;
65
+ const weight = zoneWeight(zone, timeUtcMs);
66
+ if (weight > 0) {
67
+ touched = true;
68
+ logCruise = Math.max(logCruise, logBase + (Math.log(zone.rate) - logBase) * weight);
69
+ }
70
+ }
71
+ let logRate = logCruise;
72
+ for (const zone of spans) {
73
+ if (zone.rate > pacing.baseRate)
74
+ continue;
75
+ const weight = zoneWeight(zone, timeUtcMs);
76
+ if (weight > 0) {
77
+ touched = true;
78
+ logRate = Math.min(logRate, logCruise + (Math.log(zone.rate) - logCruise) * weight);
79
+ }
80
+ }
81
+ for (const zone of rules) {
56
82
  if (!zoneInView(zone, shown))
57
83
  continue;
58
- const distance = timeUtcMs < zone.fromUtcMs ? zone.fromUtcMs - timeUtcMs : timeUtcMs > zone.toUtcMs ? timeUtcMs - zone.toUtcMs : 0;
59
- const weight = distance === 0 ? 1 : distance >= zone.rampMs ? 0 : smooth(1 - distance / zone.rampMs);
60
- if (weight > 0)
84
+ const weight = zoneWeight(zone, timeUtcMs);
85
+ if (weight > 0) {
61
86
  touched = true;
62
- if (weight > 0)
63
- logRate += (Math.log(zone.rate) - logRate) * weight;
87
+ logRate = Math.min(logRate, logCruise + (Math.log(zone.rate) - logCruise) * weight);
88
+ }
64
89
  }
65
90
  return touched ? Math.exp(logRate) : pacing.baseRate; // untouched: exactly the base, not its log round trip
66
91
  }
@@ -70,7 +95,13 @@ export const PACE_EASE_MS = 1000;
70
95
  export function startPaceEase(view, fromRate, nowMs) {
71
96
  view.ease = { fromRate, startMs: nowMs };
72
97
  }
73
- /** Sets the clock to the paced rate for its current time (skipped when it already runs at it); mid-ease it is the log-space blend from the ease's start rate. */
98
+ /** The ease's own change, fixed once at the switch (the first time it is read, at the switch's time): log(start rate) minus log(the new view's paced rate there). */
99
+ export function easeShift(view, timeUtcMs, pacing) {
100
+ const ease = view.ease;
101
+ ease.k0 ??= Math.log(ease.fromRate) - Math.log(pacedRate(pacing, timeUtcMs, view.shown));
102
+ return ease.k0;
103
+ }
104
+ /** Sets the clock to the paced rate for its current time (skipped when it already runs at it); mid-ease the switch's own change decays over it: the paced shape times exp(k0 * (1 - weight)), so a zone reached during the ease still slows playback. */
74
105
  export function applyPacing(clock, pacing, view, nowMs = performance.now()) {
75
106
  let rate = pacedRate(pacing, clock.now(), view?.shown);
76
107
  const ease = view?.ease;
@@ -79,8 +110,97 @@ export function applyPacing(clock, pacing, view, nowMs = performance.now()) {
79
110
  if (progress >= 1)
80
111
  delete view.ease;
81
112
  else if (progress >= 0)
82
- rate = Math.exp(Math.log(ease.fromRate) + (Math.log(rate) - Math.log(ease.fromRate)) * smooth(progress));
113
+ rate = Math.exp(Math.log(rate) + easeShift(view, clock.now(), pacing) * (1 - smooth(progress)));
83
114
  }
84
115
  if (rate !== clock.rate)
85
116
  clock.setRate(rate);
86
117
  }
118
+ /** The most sub-steps one `pacedAdvance` call takes; real time left over after them is dropped, so a frame that long (a tab left hidden) slows the clock rather than skipping a zone. */
119
+ export const MAX_PACE_STEPS = 4096;
120
+ /** A sub-step inside a ramp covers at most this part of the ramp's simulated length. */
121
+ const RAMP_STEP_FRACTION = 1 / 32;
122
+ /** The longest simulated distance a sub-step from `t` may cover in `direction`: to the next zone or ramp edge, and a fraction of the ramp while inside one. */
123
+ function stepCap(zones, t, direction) {
124
+ let cap = Infinity;
125
+ for (const zone of zones) {
126
+ const edges = [zone.fromUtcMs - zone.rampMs, zone.fromUtcMs, zone.toUtcMs, zone.toUtcMs + zone.rampMs];
127
+ for (const edge of edges) {
128
+ const distance = direction * (edge - t);
129
+ if (distance > 0)
130
+ cap = Math.min(cap, distance);
131
+ }
132
+ if (zone.rampMs > 0) {
133
+ for (const [lo, hi] of [[edges[0], edges[1]], [edges[2], edges[3]]]) {
134
+ const inside = direction === 1 ? t >= lo && t < hi : t > lo && t <= hi;
135
+ if (inside)
136
+ cap = Math.min(cap, zone.rampMs * RAMP_STEP_FRACTION);
137
+ }
138
+ }
139
+ }
140
+ return cap;
141
+ }
142
+ /** A sub-step inside a running ease covers at most this much real time, so the eased rate is read finely enough. */
143
+ const EASE_STEP_MS = PACE_EASE_MS / 32;
144
+ /** The rate the clock runs at: the paced rate at `t`, with the ease's decaying change laid over its shape while the ease runs (as `applyPacing` does), `usedMs` of real time into the advance. */
145
+ function advanceRate(pacing, t, shown, ease, usedMs) {
146
+ const rate = pacedRate(pacing, t, shown);
147
+ if (ease === undefined)
148
+ return rate;
149
+ const progress = (ease.elapsedMs + usedMs) / PACE_EASE_MS;
150
+ if (progress >= 1 || progress < 0)
151
+ return rate;
152
+ return Math.exp(Math.log(rate) + ease.k0 * (1 - smooth(progress)));
153
+ }
154
+ /**
155
+ * The time `realElapsedMs` of real time after `fromUtcMs` when the clock runs at `pacedRate` throughout (`direction` -1 runs it backward): the rate is integrated, not read once, so a long frame still slows down
156
+ * through every zone and ramp it crosses. Each sub-step stops at the next zone or ramp edge, covers at most 1/32 of a ramp, and is timed by the trapezoid rule on the rates at its two ends (the far one a millisecond short).
157
+ * With an `ease` (a view switch changing the rate) the rate integrated is the eased one, and a sub-step also covers at most 1/32 of the ease's real time while it runs.
158
+ * At most `MAX_PACE_STEPS` sub-steps; the result is a whole millisecond. A pure function of its arguments.
159
+ */
160
+ export function pacedAdvance(pacing, fromUtcMs, realElapsedMs, shown, direction = 1, ease) {
161
+ const zones = zonesInView(pacing.zones, shown);
162
+ let t = fromUtcMs;
163
+ let left = realElapsedMs;
164
+ for (let step = 0; step < MAX_PACE_STEPS && left > 0; step += 1) {
165
+ const used = realElapsedMs - left;
166
+ const easing = ease !== undefined && ease.elapsedMs + used >= 0 && ease.elapsedMs + used < PACE_EASE_MS;
167
+ const startRate = advanceRate(pacing, t, shown, ease, used);
168
+ const length = Math.min(stepCap(zones, t, direction), startRate * Math.min(left, easing ? EASE_STEP_MS : Infinity));
169
+ const end = t + direction * length;
170
+ const endUsed = used + Math.min(left, length / startRate); // the real time the step takes if the rate stayed as at its start
171
+ const endRate = advanceRate(pacing, end - direction * Math.min(1, length / 2), shown, ease, endUsed); // a millisecond short of the end, so a jump of rate at a hard edge is not read early
172
+ const needed = (length * (1 / startRate + 1 / endRate)) / 2; // trapezoid: real time is the mean of the reciprocal rates times the distance
173
+ if (needed <= left) {
174
+ t = end;
175
+ left -= needed;
176
+ }
177
+ else {
178
+ t += (direction * length * left) / needed;
179
+ left = 0;
180
+ }
181
+ }
182
+ return Math.round(t);
183
+ }
184
+ /** Real-time slack, in milliseconds, between the clock's own advance and the real time `stepPacing` measured before the move is taken as someone else's (a seek). */
185
+ const STEP_SLACK_MS = 5;
186
+ /**
187
+ * One pacing step per frame: moves the clock from where the last step left it by `pacedAdvance` over the real time since, then sets the paced rate for the new time (`applyPacing`'s job). Falls back to `applyPacing`
188
+ * (one rate for the frame) on the first step, while paused, or when the clock was moved or re-rated since the last step. The clock is moved through its public `seek` and `setRate`.
189
+ */
190
+ export function stepPacing(clock, pacing, view, nowMs = performance.now()) {
191
+ const last = view.last;
192
+ const realMs = last === undefined ? 0 : nowMs - last.nowMs;
193
+ const clockMs = last === undefined ? 0 : (clock.now() - last.timeUtcMs) / last.rate;
194
+ const continuous = last !== undefined && clock.playing && clock.rate === last.rate && realMs > 0 && Math.abs(clockMs - realMs) <= STEP_SLACK_MS + 2 / last.rate;
195
+ if (continuous) {
196
+ const ease = view.ease === undefined ? undefined : { k0: easeShift(view, last.timeUtcMs, pacing), elapsedMs: last.nowMs - view.ease.startMs };
197
+ const to = pacedAdvance(pacing, last.timeUtcMs, realMs, view.shown, 1, ease);
198
+ if (to !== clock.now())
199
+ clock.seek(to);
200
+ }
201
+ applyPacing(clock, pacing, view, nowMs);
202
+ if (clock.playing)
203
+ view.last = { timeUtcMs: clock.now(), rate: clock.rate, nowMs };
204
+ else
205
+ delete view.last;
206
+ }
@@ -0,0 +1 @@
1
+ export declare const fetchBytesOf: (url: string) => Promise<Uint8Array>;
@@ -0,0 +1,15 @@
1
+ /** Reads the bytes at a bundled address: a `file:` address with Node's own module (found at run time, so a browser bundle never resolves it; Node's `fetch` does not serve `file:`), anything else by `fetch`. One reader for every bundled file the engine loads (moon fit chunks, the star list). */
2
+ async function readFileUrl(url) {
3
+ const nodeFs = globalThis.process?.getBuiltinModule?.("node:fs/promises");
4
+ if (nodeFs === undefined)
5
+ throw new Error(`${url}: this runtime cannot read a file: address`);
6
+ return new Uint8Array(await nodeFs.readFile(new URL(url)));
7
+ }
8
+ export const fetchBytesOf = async (url) => {
9
+ if (url.startsWith("file:"))
10
+ return readFileUrl(url);
11
+ const response = await fetch(url);
12
+ if (!response.ok)
13
+ throw new Error(`${url}: HTTP ${response.status}`);
14
+ return new Uint8Array(await response.arrayBuffer());
15
+ };
@@ -0,0 +1,49 @@
1
+ /** What follows a trace: the traced lines stay, or fade away. (Removing a trace at any time is `clearSkyTrace`.) */
2
+ export type SkyTraceAfter = "stay" | "fade";
3
+ export declare const SKY_TRACE_AFTER: readonly SkyTraceAfter[];
4
+ /** How long a trace takes, in seconds, when the app does not say. */
5
+ export declare const DEFAULT_TRACE_SECONDS = 2;
6
+ /** The range of `durationSeconds` a trace accepts. */
7
+ export declare const TRACE_SECONDS_LIMITS: Readonly<{
8
+ min: 0.1;
9
+ max: 60;
10
+ }>;
11
+ /** How long a `fade` takes after the trace, in seconds. */
12
+ export declare const TRACE_FADE_SECONDS = 1;
13
+ /** How long sky lines and their names take to fade in when they appear, in seconds, when the look does not say (owner, T-306). */
14
+ export declare const DEFAULT_SKY_FADE_IN_SECONDS = 0.5;
15
+ /** The longest step one frame moves the fade-in on, in seconds, so a frame after an idle spell (the scene draws only when needed) does not skip the fade. */
16
+ export declare const SKY_FADE_IN_STEP_LIMIT = 0.1;
17
+ /** The share of a fade-in shown after one more step: `from` moved on by `deltaSeconds` (capped at `SKY_FADE_IN_STEP_LIMIT`) of `seconds`; 0 seconds shows it all at once. */
18
+ export declare function stepFadeIn(from: number, deltaSeconds: number, seconds: number): number;
19
+ /** One trace in progress. `reduced`: the person asked for less motion, so the whole figure shows at once. */
20
+ export interface SkyTraceRun {
21
+ readonly seconds: number;
22
+ readonly after: SkyTraceAfter;
23
+ readonly reduced: boolean;
24
+ /** Real seconds since the trace began. */
25
+ elapsed: number;
26
+ }
27
+ /** What one step of a trace says to draw. */
28
+ export interface SkyTraceFrame {
29
+ /** The share of the figure's segments drawn, 0 to 1 (segments in order, each growing from its first end). */
30
+ readonly drawn: number;
31
+ /** How far the lines have faded, 0 to 1 (0: the traced colour; 1: the faded colour, then gone). */
32
+ readonly fade: number;
33
+ /** True: the trace is over and its lines go (`clear`, or a finished `fade`). */
34
+ readonly done: boolean;
35
+ /** True: this step changed what is drawn, so the scene must draw this frame. */
36
+ readonly moving: boolean;
37
+ }
38
+ /** Moves a trace on by `deltaSeconds` of real time and says what to draw. A `stay` trace holds its drawn figure for good (until the app traces it again). */
39
+ export declare function stepTrace(run: SkyTraceRun, deltaSeconds: number): SkyTraceFrame;
40
+ /** A trace on its way out because the host asked to clear it: eases from the fade it had to 1 over `seconds` (0: gone this step). */
41
+ export interface SkyHideRun {
42
+ readonly seconds: number;
43
+ /** The fade the trace had when the request was taken, 0 to 1. */
44
+ readonly from: number;
45
+ /** Real seconds since the request was taken. */
46
+ elapsed: number;
47
+ }
48
+ /** Moves a hide on by `deltaSeconds` of real time; `drawn` is the share the trace had reached, which a hide holds. */
49
+ export declare function stepHide(run: SkyHideRun, deltaSeconds: number, drawn: number): SkyTraceFrame;
@@ -0,0 +1,39 @@
1
+ // How a sky-figure trace runs (O-065 T-297): pure arithmetic with no drawing, shared by the host call's checks (`src/api`) and the frame stage (`src/app`). Wall time only: the scene clock never enters.
2
+ export const SKY_TRACE_AFTER = Object.freeze(["stay", "fade"]);
3
+ /** How long a trace takes, in seconds, when the app does not say. */
4
+ export const DEFAULT_TRACE_SECONDS = 2;
5
+ /** The range of `durationSeconds` a trace accepts. */
6
+ export const TRACE_SECONDS_LIMITS = Object.freeze({ min: 0.1, max: 60 });
7
+ /** How long a `fade` takes after the trace, in seconds. */
8
+ export const TRACE_FADE_SECONDS = 1;
9
+ /** How long sky lines and their names take to fade in when they appear, in seconds, when the look does not say (owner, T-306). */
10
+ export const DEFAULT_SKY_FADE_IN_SECONDS = 0.5;
11
+ /** The longest step one frame moves the fade-in on, in seconds, so a frame after an idle spell (the scene draws only when needed) does not skip the fade. */
12
+ export const SKY_FADE_IN_STEP_LIMIT = 0.1;
13
+ /** The share of a fade-in shown after one more step: `from` moved on by `deltaSeconds` (capped at `SKY_FADE_IN_STEP_LIMIT`) of `seconds`; 0 seconds shows it all at once. */
14
+ export function stepFadeIn(from, deltaSeconds, seconds) {
15
+ if (seconds <= 0)
16
+ return 1;
17
+ return Math.min(1, from + Math.min(SKY_FADE_IN_STEP_LIMIT, Math.max(0, deltaSeconds)) / seconds);
18
+ }
19
+ /** Moves a trace on by `deltaSeconds` of real time and says what to draw. A `stay` trace holds its drawn figure for good (until the app traces it again). */
20
+ export function stepTrace(run, deltaSeconds) {
21
+ const unsettled = run.elapsed < run.seconds; // a `stay` trace changes only until it is fully drawn
22
+ run.elapsed += Math.max(0, deltaSeconds);
23
+ const drawn = run.reduced ? 1 : Math.min(1, run.elapsed / run.seconds);
24
+ if (run.elapsed < run.seconds)
25
+ return { drawn, fade: 0, done: false, moving: true };
26
+ if (run.after === "stay")
27
+ return { drawn: 1, fade: 0, done: false, moving: unsettled };
28
+ if (run.reduced)
29
+ return { drawn: 1, fade: 1, done: true, moving: true };
30
+ const fade = Math.min(1, (run.elapsed - run.seconds) / TRACE_FADE_SECONDS);
31
+ return { drawn: 1, fade, done: fade >= 1, moving: true };
32
+ }
33
+ /** Moves a hide on by `deltaSeconds` of real time; `drawn` is the share the trace had reached, which a hide holds. */
34
+ export function stepHide(run, deltaSeconds, drawn) {
35
+ run.elapsed += Math.max(0, deltaSeconds);
36
+ const share = run.seconds <= 0 ? 1 : Math.min(1, run.elapsed / run.seconds);
37
+ const fade = run.from + (1 - run.from) * share;
38
+ return { drawn, fade, done: share >= 1, moving: true };
39
+ }
@@ -17,3 +17,42 @@ export declare const MAX_ELEVATION_DEG = 89;
17
17
  export declare const wrapAzimuth: (deg: number) => number;
18
18
  /** Checks a view's fields, naming the offending one (`where` is its path, e.g. `look.startView`). Returns the view with the azimuth wrapped. */
19
19
  export declare function validateStartView(raw: unknown, where?: string): StartView;
20
+ /** The field of view a sky reading may carry, in degrees (a look-out camera's zoom). */
21
+ export declare const SKY_FOV_RANGE_DEG: {
22
+ readonly min: 5;
23
+ readonly max: 100;
24
+ };
25
+ /** The field of view a look-out opens at when none is given, in degrees. */
26
+ export declare const SKY_OPENING_FOV_DEG = 60;
27
+ /**
28
+ * A camera standing inside `lookOut` (a body's id) and looking out: `raDeg` and `decDeg` are where it points in J2000 equatorial degrees
29
+ * (right ascension 0 up to 360, declination within ±90), `fovDeg` the vertical field of view. Text and number checks only: no body is named here.
30
+ */
31
+ export interface SkyView {
32
+ readonly lookOut: string;
33
+ readonly raDeg: number;
34
+ readonly decDeg: number;
35
+ readonly fovDeg: number;
36
+ }
37
+ /** Either kind of camera reading: an orbit view (has `distance`) or a sky view (has `lookOut`). */
38
+ export type CameraView = StartView | SkyView;
39
+ /** True for a sky view: the one test that tells the two kinds apart. */
40
+ export declare function isSkyView(view: CameraView): view is SkyView;
41
+ /** The unit vector (J2000 equatorial axes) toward a right ascension and declination in degrees. */
42
+ export declare function eqjUnitVector(raDeg: number, decDeg: number): [number, number, number];
43
+ /** Checks a right ascension and declination, naming the offending field; returns the pair with the right ascension wrapped to 0 up to 360. */
44
+ export declare function validateSkyDirection(raDeg: unknown, decDeg: unknown, where: string): {
45
+ readonly raDeg: number;
46
+ readonly decDeg: number;
47
+ };
48
+ /** Checks a star-map position given as an object: exactly `raDeg` and `decDeg` (a half pair, an array or any other key is refused). Shared by `setCamera` and the opening `lookOut`. */
49
+ export declare function validateSkyPosition(raw: unknown, where: string): {
50
+ readonly raDeg: number;
51
+ readonly decDeg: number;
52
+ };
53
+ /** Checks a field of view in degrees against the range a look-out camera takes. */
54
+ export declare function validateSkyFov(fovDeg: unknown, where: string): number;
55
+ /** Checks a sky view's fields, naming the offending one. Returns the view with the right ascension wrapped. */
56
+ export declare function validateSkyView(raw: unknown, where?: string): SkyView;
57
+ /** Checks either kind of reading: one with `lookOut` is a sky view, anything else an orbit view. */
58
+ export declare function validateCameraView(raw: unknown, where?: string): CameraView;
@@ -26,3 +26,59 @@ export function validateStartView(raw, where = "startView") {
26
26
  throw new RangeError(`${where}.distance must be positive, got ${distance}`);
27
27
  return { focus: record.focus, azimuthDeg: wrapAzimuth(azimuthDeg), elevationDeg, distance };
28
28
  }
29
+ /** The field of view a sky reading may carry, in degrees (a look-out camera's zoom). */
30
+ export const SKY_FOV_RANGE_DEG = { min: 5, max: 100 };
31
+ /** The field of view a look-out opens at when none is given, in degrees. */
32
+ export const SKY_OPENING_FOV_DEG = 60;
33
+ /** True for a sky view: the one test that tells the two kinds apart. */
34
+ export function isSkyView(view) {
35
+ return "lookOut" in view;
36
+ }
37
+ /** The unit vector (J2000 equatorial axes) toward a right ascension and declination in degrees. */
38
+ export function eqjUnitVector(raDeg, decDeg) {
39
+ const [ra, dec] = [(raDeg * Math.PI) / 180, (decDeg * Math.PI) / 180];
40
+ return [Math.cos(dec) * Math.cos(ra), Math.cos(dec) * Math.sin(ra), Math.sin(dec)];
41
+ }
42
+ /** Checks a right ascension and declination, naming the offending field; returns the pair with the right ascension wrapped to 0 up to 360. */
43
+ export function validateSkyDirection(raDeg, decDeg, where) {
44
+ if (typeof raDeg !== "number" || !Number.isFinite(raDeg))
45
+ throw new RangeError(`${where}.raDeg must be a finite number, got ${String(raDeg)}`);
46
+ if (typeof decDeg !== "number" || !Number.isFinite(decDeg))
47
+ throw new RangeError(`${where}.decDeg must be a finite number, got ${String(decDeg)}`);
48
+ if (Math.abs(decDeg) > 90)
49
+ throw new RangeError(`${where}.decDeg must be within ±90, got ${decDeg}`);
50
+ return { raDeg: wrapAzimuth(raDeg), decDeg };
51
+ }
52
+ /** Checks a star-map position given as an object: exactly `raDeg` and `decDeg` (a half pair, an array or any other key is refused). Shared by `setCamera` and the opening `lookOut`. */
53
+ export function validateSkyPosition(raw, where) {
54
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw) || Object.keys(raw).some((key) => key !== "raDeg" && key !== "decDeg"))
55
+ throw new RangeError(`${where} must be { raDeg, decDeg }`);
56
+ const position = raw;
57
+ return validateSkyDirection(position.raDeg, position.decDeg, where);
58
+ }
59
+ /** Checks a field of view in degrees against the range a look-out camera takes. */
60
+ export function validateSkyFov(fovDeg, where) {
61
+ if (typeof fovDeg !== "number" || !(fovDeg >= SKY_FOV_RANGE_DEG.min && fovDeg <= SKY_FOV_RANGE_DEG.max)) {
62
+ throw new RangeError(`${where}.fovDeg must be a number from ${SKY_FOV_RANGE_DEG.min} to ${SKY_FOV_RANGE_DEG.max}, got ${String(fovDeg)}`);
63
+ }
64
+ return fovDeg;
65
+ }
66
+ /** Checks a sky view's fields, naming the offending one. Returns the view with the right ascension wrapped. */
67
+ export function validateSkyView(raw, where = "sky view") {
68
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw))
69
+ throw new RangeError(`${where} must be an object with lookOut, raDeg, decDeg and fovDeg`);
70
+ const record = raw;
71
+ for (const key of Object.keys(record)) {
72
+ if (!["lookOut", "raDeg", "decDeg", "fovDeg"].includes(key))
73
+ throw new RangeError(`${where}.${key} is not a sky view field`);
74
+ }
75
+ if (typeof record.lookOut !== "string" || record.lookOut === "")
76
+ throw new RangeError(`${where}.lookOut must be a non-empty id, got ${String(record.lookOut)}`);
77
+ const direction = validateSkyDirection(record.raDeg, record.decDeg, where);
78
+ return { lookOut: record.lookOut, ...direction, fovDeg: validateSkyFov(record.fovDeg, where) };
79
+ }
80
+ /** Checks either kind of reading: one with `lookOut` is a sky view, anything else an orbit view. */
81
+ export function validateCameraView(raw, where = "view") {
82
+ const isSky = typeof raw === "object" && raw !== null && "lookOut" in raw;
83
+ return isSky ? validateSkyView(raw, where) : validateStartView(raw, where);
84
+ }
@@ -1,7 +1,42 @@
1
1
  import { type Provenance } from "./provenance.js";
2
+ import type { StartView } from "./startView.js";
3
+ import type { SkyTraceAfter } from "./skyTrace.js";
2
4
  import type { TimeBounds } from "./trajectory.js";
5
+ /** A camera request a panel makes when it opens (checked): the same shapes the scene camera takes. A look-out `direction` that is absent keeps the direction already looked along (else right ascension 0, declination 0). */
6
+ export type PanelCameraRequest = {
7
+ readonly kind: "focus" | "follow";
8
+ readonly target: string;
9
+ } | {
10
+ readonly kind: "overview";
11
+ } | {
12
+ readonly kind: "hold";
13
+ } | {
14
+ readonly kind: "lookOut";
15
+ readonly body: string;
16
+ readonly direction?: readonly [number, number, number] | string;
17
+ readonly fovDeg?: number;
18
+ } | {
19
+ readonly kind: "pose";
20
+ readonly view: StartView;
21
+ };
22
+ /** What a panel does when it opens, in this order: the camera turns, its object is selected, its object's sky figure is traced. */
23
+ export interface PanelActions {
24
+ readonly camera?: PanelCameraRequest;
25
+ /** True: select the panel's `object`. */
26
+ readonly select?: true;
27
+ /** Trace the panel's `object`, a sky figure, this way. */
28
+ readonly trace?: {
29
+ readonly seconds: number;
30
+ readonly after: SkyTraceAfter;
31
+ };
32
+ }
33
+ /** The ids a camera request names: the bodies it points at, and the id a look-out turns toward (a body or a sky figure). */
34
+ export declare function cameraIdsOf(request: PanelCameraRequest): {
35
+ readonly bodies: readonly string[];
36
+ readonly toward?: string;
37
+ };
3
38
  /** One short story panel, resolved to a UTC time. */
4
- export interface StoryPanel {
39
+ export interface StoryPanel extends PanelActions {
5
40
  readonly id: string;
6
41
  readonly timeUtcMs: number;
7
42
  readonly title: string;
@@ -14,9 +49,17 @@ export interface StoryPanel {
14
49
  /** A shell object this panel is about; the scene draws a marker on it that reopens the panel. */
15
50
  readonly objectId?: string;
16
51
  }
52
+ /** A story step: a panel with no moment, shown in the order added with Back and Next. */
53
+ export type StoryStep = Omit<StoryPanel, "timeUtcMs"> & {
54
+ /** The step's place among the steps, counting from 1 in the order added. */
55
+ readonly step: number;
56
+ };
17
57
  /** The panels an experience offers, with the defaults of the two settings that govern them. */
18
58
  export interface StoryPanelSet {
59
+ /** The moment panels, sorted by time. */
19
60
  readonly panels: readonly StoryPanel[];
61
+ /** The steps, in the order added; absent or empty when there are none. */
62
+ readonly steps?: readonly StoryStep[];
20
63
  /** How long playback holds when a panel opens by itself, in seconds (0 never pauses). */
21
64
  readonly pauseSeconds: number;
22
65
  /** Whether panels open by themselves as forward playback reaches them. */
@@ -29,7 +72,8 @@ export type PanelPlayback = Pick<StoryPanelSet, "pauseSeconds" | "autoOpen">;
29
72
  export declare const DEFAULT_PANEL_PLAYBACK: PanelPlayback;
30
73
  /** A panel whose own shape is sound and whose moment is converted. What it names (an event, an anchor, an object) is left for `resolveStoryPanels`, because those may be added later. */
31
74
  export interface CheckedPanel extends Omit<StoryPanel, "timeUtcMs" | "objectId"> {
32
- readonly at: {
75
+ /** Absent: a step. */
76
+ readonly at?: {
33
77
  readonly timeUtcMs: number;
34
78
  } | {
35
79
  readonly event: string;
@@ -48,6 +92,8 @@ export interface PanelLookup {
48
92
  readonly anchors?: ReadonlyMap<string, number>;
49
93
  /** Ids a panel's `object` may name. Absent: any id is accepted. */
50
94
  readonly objectIds?: readonly string[];
95
+ /** The sky figures' ids: a panel's `object` may name one, and a look-out camera may turn toward one. Absent: none. */
96
+ readonly figureIds?: readonly string[];
51
97
  /** When given, every panel must fall inside it. */
52
98
  readonly window?: TimeBounds;
53
99
  }
@@ -59,5 +105,7 @@ export declare class StoryPanelError extends Error {
59
105
  export declare function checkStoryPanel(raw: unknown, index: number): CheckedPanel;
60
106
  /** Checks the two playback settings; a setting left out takes its default, so the result is the whole setting. */
61
107
  export declare function checkPanelPlayback(raw: unknown): PanelPlayback;
62
- /** Resolves each checked panel's time and links against the scene as built. Panels come back sorted by time. */
108
+ /** Resolves each checked panel's time and links against the scene as built. Moment panels come back sorted by time; steps (no `at`) in the order given, numbered from 1. */
63
109
  export declare function resolveStoryPanels(panels: readonly CheckedPanel[], playback: PanelPlayback, lookup: PanelLookup): StoryPanelSet;
110
+ /** The step Back or Next opens from `step`: the one `by` places along (-1 or 1), or undefined at either end. */
111
+ export declare function neighbourStep(steps: readonly StoryStep[], step: StoryStep, by: -1 | 1): StoryStep | undefined;