astraeus 0.9.0 → 0.9.2

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 (84) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +102 -35
  3. package/package.json +1 -1
  4. package/src/api/assembleScene.js +5 -5
  5. package/src/api/errors.d.ts +1 -1
  6. package/src/api/index.d.ts +2 -2
  7. package/src/api/look.d.ts +14 -0
  8. package/src/api/lookInput.d.ts +1 -1
  9. package/src/api/lookInput.js +6 -2
  10. package/src/api/planBodies.d.ts +2 -1
  11. package/src/api/planBodies.js +6 -1
  12. package/src/api/planCamera.d.ts +19 -2
  13. package/src/api/planCamera.js +45 -6
  14. package/src/api/planPaths.d.ts +2 -0
  15. package/src/api/planPaths.js +13 -8
  16. package/src/api/planStory.d.ts +3 -1
  17. package/src/api/planStory.js +5 -0
  18. package/src/api/planTimeline.d.ts +1 -1
  19. package/src/api/planTimeline.js +10 -1
  20. package/src/api/planViews.d.ts +3 -1
  21. package/src/api/planViews.js +4 -0
  22. package/src/api/providerPathTimes.d.ts +10 -0
  23. package/src/api/providerPathTimes.js +109 -0
  24. package/src/api/scene.d.ts +17 -5
  25. package/src/api/scene.js +16 -2
  26. package/src/api/sceneReads.d.ts +31 -1
  27. package/src/api/shownDuring.d.ts +12 -0
  28. package/src/api/shownDuring.js +30 -0
  29. package/src/api/story.d.ts +10 -3
  30. package/src/api/story.js +11 -4
  31. package/src/api/switches.d.ts +1 -0
  32. package/src/api/switches.js +3 -1
  33. package/src/api/time.d.ts +1 -1
  34. package/src/api/time.js +4 -1
  35. package/src/app/App.js +58 -21
  36. package/src/app/App.node.js +58 -21
  37. package/src/app/AstraeusScene.d.ts +8 -1
  38. package/src/app/CameraController.d.ts +4 -1
  39. package/src/app/CameraController.js +15 -3
  40. package/src/app/SkyFiguresView.d.ts +2 -2
  41. package/src/app/SkyFiguresView.js +25 -14
  42. package/src/app/displaySwitches.d.ts +2 -0
  43. package/src/app/displaySwitches.js +1 -1
  44. package/src/app/liveLook.d.ts +4 -1
  45. package/src/app/liveLook.js +29 -1
  46. package/src/app/look.d.ts +5 -0
  47. package/src/app/look.js +8 -2
  48. package/src/app/sceneCamera.js +14 -2
  49. package/src/app/sceneContentsHooks.js +1 -1
  50. package/src/app/sceneFrame.d.ts +14 -5
  51. package/src/app/sceneFrame.js +31 -21
  52. package/src/app/scenePointer.d.ts +5 -1
  53. package/src/app/scenePointer.js +8 -3
  54. package/src/app/timeLook.d.ts +7 -0
  55. package/src/app/timeLook.js +8 -0
  56. package/src/app/viewHiding.d.ts +8 -1
  57. package/src/app/viewHiding.js +23 -0
  58. package/src/core/clock.js +2 -1
  59. package/src/core/lookValues.d.ts +13 -0
  60. package/src/core/lookValues.js +39 -0
  61. package/src/core/pacing.d.ts +38 -6
  62. package/src/core/pacing.js +141 -21
  63. package/src/core/state.d.ts +2 -0
  64. package/src/core/state.js +5 -1
  65. package/src/core/storyPanels.d.ts +8 -4
  66. package/src/core/storyPanels.js +17 -5
  67. package/src/shell/AstraeusShell.d.ts +7 -1
  68. package/src/shell/AstraeusShell.js +39 -14
  69. package/src/shell/AstraeusShell.node.js +39 -14
  70. package/src/shell/ObjectControls.js +2 -2
  71. package/src/shell/TimelineBar.d.ts +6 -2
  72. package/src/shell/TimelineBar.js +17 -12
  73. package/src/shell/TimelineBar.node.js +17 -12
  74. package/src/shell/experience.d.ts +9 -0
  75. package/src/shell/infoModel.d.ts +2 -1
  76. package/src/shell/infoModel.js +10 -10
  77. package/src/shell/objectModel.d.ts +3 -2
  78. package/src/shell/objectModel.js +6 -4
  79. package/src/shell/storyPanels.d.ts +19 -1
  80. package/src/shell/storyPanels.js +34 -2
  81. package/src/shell/timelineModel.d.ts +11 -0
  82. package/src/shell/timelineModel.js +28 -0
  83. package/src/shell/useStoryPanels.d.ts +4 -0
  84. package/src/shell/useStoryPanels.js +27 -6
@@ -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
+ }
@@ -28,6 +28,8 @@ export interface StateInput {
28
28
  readonly velocityKmS?: ArrayLike<number>;
29
29
  readonly orientation: Quaternion | null;
30
30
  }
31
+ /** True for a whole-millisecond JavaScript UTC Unix time inside the Date range. */
32
+ export declare function isUtcUnixMs(timeUtcMs: number): boolean;
31
33
  export declare function assertUtcUnixMs(timeUtcMs: number): void;
32
34
  export declare function createCenteredPosition(input: Omit<StateInput, "orientation">): CenteredPosition;
33
35
  /** Whether a body's definition says its State must carry a modelled orientation. */
package/src/core/state.js CHANGED
@@ -4,8 +4,12 @@ import { MOON } from "./bodies/moon.js";
4
4
  import { SUN } from "./bodies/sun.js";
5
5
  export const EQJ = "EQJ";
6
6
  const MAX_DATE_MS = 8.64e15;
7
+ /** True for a whole-millisecond JavaScript UTC Unix time inside the Date range. */
8
+ export function isUtcUnixMs(timeUtcMs) {
9
+ return Number.isSafeInteger(timeUtcMs) && Math.abs(timeUtcMs) <= MAX_DATE_MS;
10
+ }
7
11
  export function assertUtcUnixMs(timeUtcMs) {
8
- if (!Number.isSafeInteger(timeUtcMs) || Math.abs(timeUtcMs) > MAX_DATE_MS) {
12
+ if (!isUtcUnixMs(timeUtcMs)) {
9
13
  throw new RangeError("timeUtcMs must be an integer JavaScript UTC Unix-millisecond value");
10
14
  }
11
15
  }
@@ -48,9 +48,11 @@ export interface StoryPanel extends PanelActions {
48
48
  readonly provenance: Provenance;
49
49
  /** A shell object this panel is about; the scene draws a marker on it that reopens the panel. */
50
50
  readonly objectId?: string;
51
+ /** This panel's own span, in simulated seconds: forward playback closes it once the clock passes its time plus this. Overrides the playback setting; absent, the playback setting (or none) applies. */
52
+ readonly closeAfterSeconds?: number;
51
53
  }
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
+ /** A story step: a panel with no moment, shown in the order added with Back and Next. A step never closes by itself. */
55
+ export type StoryStep = Omit<StoryPanel, "timeUtcMs" | "closeAfterSeconds"> & {
54
56
  /** The step's place among the steps, counting from 1 in the order added. */
55
57
  readonly step: number;
56
58
  };
@@ -64,11 +66,13 @@ export interface StoryPanelSet {
64
66
  readonly pauseSeconds: number;
65
67
  /** Whether panels open by themselves as forward playback reaches them. */
66
68
  readonly autoOpen: boolean;
69
+ /** Simulated seconds after a moment panel's time at which forward playback closes it; absent: never (a panel's own span wins). */
70
+ readonly closeAfterSeconds?: number;
67
71
  }
68
72
  export declare const DEFAULT_PANEL_PAUSE_SECONDS = 6;
69
73
  export declare const MAX_PANEL_PAUSE_SECONDS = 20;
70
- /** The two playback settings of a scene's story panels. */
71
- export type PanelPlayback = Pick<StoryPanelSet, "pauseSeconds" | "autoOpen">;
74
+ /** The playback settings of a scene's story panels. */
75
+ export type PanelPlayback = Pick<StoryPanelSet, "pauseSeconds" | "autoOpen" | "closeAfterSeconds">;
72
76
  export declare const DEFAULT_PANEL_PLAYBACK: PanelPlayback;
73
77
  /** 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. */
74
78
  export interface CheckedPanel extends Omit<StoryPanel, "timeUtcMs" | "objectId"> {
@@ -1,4 +1,5 @@
1
1
  import { createProvenance, PROVENANCE_SOURCE_TYPES } from "./provenance.js";
2
+ import { isUtcUnixMs } from "./state.js";
2
3
  import { timeInputMs } from "./timeInput.js";
3
4
  /** 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). */
4
5
  export function cameraIdsOf(request) {
@@ -45,7 +46,7 @@ function atOf(panel, at) {
45
46
  if (keys[0] === "anchor")
46
47
  return { anchor: text(panel, "at.anchor", at.anchor) };
47
48
  const timeUtcMs = timeInputMs(at.time);
48
- if (!Number.isFinite(timeUtcMs))
49
+ if (!isUtcUnixMs(timeUtcMs))
49
50
  throw new StoryPanelError(panel, "at.time", `must be a valid moment (ISO text, a Date or Unix milliseconds), got ${JSON.stringify(at.time)}`);
50
51
  return { timeUtcMs };
51
52
  }
@@ -62,6 +63,12 @@ function provenanceOf(panel, value) {
62
63
  throw new StoryPanelError(panel, "provenance.notes", "must be text");
63
64
  return createProvenance(value);
64
65
  }
66
+ /** A close span: finite and above 0, in simulated seconds. */
67
+ function spanOf(panel, field, value) {
68
+ if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
69
+ throw new StoryPanelError(panel, field, `must be a number of seconds above 0, got ${JSON.stringify(value)}`);
70
+ return value;
71
+ }
65
72
  /** Checks the shape of one panel, the `index`th of the list it came in. Nothing here looks at the scene: links are `resolveStoryPanels`' job. */
66
73
  export function checkStoryPanel(raw, index) {
67
74
  if (!isRecord(raw))
@@ -69,6 +76,9 @@ export function checkStoryPanel(raw, index) {
69
76
  const id = text(`#${index + 1}`, "id", raw.id);
70
77
  const object = raw.object === undefined ? undefined : text(id, "object", raw.object);
71
78
  const at = atOf(id, raw.at);
79
+ if (at === undefined && raw.closeAfterSeconds !== undefined)
80
+ throw new StoryPanelError(id, "closeAfterSeconds", "is for a moment panel: a step never closes by itself");
81
+ const closeAfterSeconds = raw.closeAfterSeconds === undefined ? undefined : spanOf(id, "closeAfterSeconds", raw.closeAfterSeconds);
72
82
  return {
73
83
  id,
74
84
  ...(at === undefined ? {} : { at }),
@@ -77,12 +87,13 @@ export function checkStoryPanel(raw, index) {
77
87
  details: raw.details === undefined ? [] : lines(id, "details", raw.details),
78
88
  provenance: provenanceOf(id, raw.provenance),
79
89
  ...(object === undefined ? {} : { object }),
90
+ ...(closeAfterSeconds === undefined ? {} : { closeAfterSeconds }),
80
91
  };
81
92
  }
82
93
  /** Checks the two playback settings; a setting left out takes its default, so the result is the whole setting. */
83
94
  export function checkPanelPlayback(raw) {
84
95
  if (!isRecord(raw))
85
- throw new StoryPanelError("settings", "playback", "must be an object: { pauseSeconds?, autoOpen? }");
96
+ throw new StoryPanelError("settings", "playback", "must be an object: { pauseSeconds?, autoOpen?, closeAfterSeconds? }");
86
97
  const pauseSeconds = raw.pauseSeconds ?? DEFAULT_PANEL_PLAYBACK.pauseSeconds;
87
98
  if (typeof pauseSeconds !== "number" || !Number.isFinite(pauseSeconds) || pauseSeconds < 0 || pauseSeconds > MAX_PANEL_PAUSE_SECONDS) {
88
99
  throw new StoryPanelError("settings", "pauseSeconds", `must be between 0 and ${MAX_PANEL_PAUSE_SECONDS}, got ${JSON.stringify(pauseSeconds)}`);
@@ -90,7 +101,8 @@ export function checkPanelPlayback(raw) {
90
101
  const autoOpen = raw.autoOpen ?? DEFAULT_PANEL_PLAYBACK.autoOpen;
91
102
  if (typeof autoOpen !== "boolean")
92
103
  throw new StoryPanelError("settings", "autoOpen", "must be true or false");
93
- return { pauseSeconds, autoOpen };
104
+ const closeAfterSeconds = raw.closeAfterSeconds === undefined ? undefined : spanOf("settings", "closeAfterSeconds", raw.closeAfterSeconds);
105
+ return { pauseSeconds, autoOpen, ...(closeAfterSeconds === undefined ? {} : { closeAfterSeconds }) };
94
106
  }
95
107
  function timeOf(id, at, lookup) {
96
108
  if ("timeUtcMs" in at)
@@ -126,13 +138,13 @@ function checkLinks({ id, object, camera, trace }, lookup) {
126
138
  /** The actions a panel carries, in the order they apply. */
127
139
  const actionsOf = ({ camera, select, trace }) => ({ ...(camera === undefined ? {} : { camera }), ...(select === undefined ? {} : { select }), ...(trace === undefined ? {} : { trace }) });
128
140
  function resolvePanel(panel, lookup) {
129
- const { id, at, title, body, details, provenance, object } = panel;
141
+ const { id, at, title, body, details, provenance, object, closeAfterSeconds } = panel;
130
142
  const timeUtcMs = timeOf(id, at, lookup);
131
143
  if (lookup.window !== undefined && (timeUtcMs < lookup.window.startUtcMs || timeUtcMs > lookup.window.endUtcMs)) {
132
144
  throw new StoryPanelError(id, "at", "falls outside the timeline window");
133
145
  }
134
146
  checkLinks(panel, lookup);
135
- return { id, timeUtcMs, title, body, details, provenance, ...(object === undefined ? {} : { objectId: object }), ...actionsOf(panel) };
147
+ return { id, timeUtcMs, title, body, details, provenance, ...(object === undefined ? {} : { objectId: object }), ...(closeAfterSeconds === undefined ? {} : { closeAfterSeconds }), ...actionsOf(panel) };
136
148
  }
137
149
  function resolveStep(panel, lookup, step) {
138
150
  const { id, title, body, details, provenance, object } = panel;
@@ -3,6 +3,7 @@ import type { ClockSnapshot } from "../core/clock.js";
3
3
  import { type PanelCause, type StoryPanelSettings } from "./useStoryPanels.js";
4
4
  import type { TimelineGlowLook } from "./timelineGlow.js";
5
5
  import { type ExperienceCameraPreset, type ExperienceConfig } from "./experience.js";
6
+ import type { TimeLook } from "./timelineModel.js";
6
7
  import type { Metric } from "./metrics.js";
7
8
  import { type PhoneLayoutSettings } from "./phoneLayout.js";
8
9
  import type { DisplaySwitchItem, ViewChoice } from "./DisplaySwitches.js";
@@ -32,6 +33,8 @@ interface Props {
32
33
  readonly onTurnToFigure?: (id: string) => void;
33
34
  /** Holds the camera where it is, its target fixed in the scene (a view's `stay` rule); a later camera request replaces it. */
34
35
  readonly onCameraHold?: () => void;
36
+ /** Told the clock time as it moves, so the app can hold a camera whose target (named by a host or a story panel, not a preset) is no longer shown. */
37
+ readonly onTimeShown?: (timeUtcMs: number) => void;
35
38
  /** True when the host has set the camera since the last view switch: that call answers the switch, so the view's own camera rule does not replace it. */
36
39
  readonly hostCameraSet?: () => boolean;
37
40
  /** Filled with the shell's story seek note, so a host's time jump re-bases the panel crossing check exactly as a visitor's seek does. */
@@ -69,6 +72,8 @@ interface Props {
69
72
  readonly fontFamily: string;
70
73
  readonly sizePx: number;
71
74
  };
75
+ /** The zone and precision of every visitor-facing time (the look `time`); absent: UTC to the second. */
76
+ readonly timeLook?: TimeLook;
72
77
  /** The family of moons lit up in the scene now (the moon panel's choice), or null; the app draws it. */
73
78
  readonly highlightedFamily?: string | null;
74
79
  readonly onHighlightFamily?: (familyId: string | null) => void;
@@ -100,9 +105,10 @@ interface Props {
100
105
  readonly pickRequest?: {
101
106
  readonly id: string;
102
107
  readonly serial: number;
108
+ readonly keepSky?: boolean;
103
109
  } | null;
104
110
  readonly children: ReactNode;
105
111
  }
106
112
  /** Canvas-first layout shared by astronomy experiences. Scene and diagnostics stay app-owned. */
107
- export declare function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onTurnToFigure, onCameraHold, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout, labelStyle, highlightedFamily, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }: Props): import("react").JSX.Element;
113
+ export declare function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onTurnToFigure, onCameraHold, onTimeShown, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout, labelStyle, timeLook, highlightedFamily, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }: Props): import("react").JSX.Element;
108
114
  export {};
@@ -15,6 +15,7 @@ import { labelStyleVars } from "../app/labelStyle.js";
15
15
  import { DEFAULT_PHONE_LAYOUT, phoneLayoutStyle, pickOpensInfo, usePhone } from "./phoneLayout.js";
16
16
  import { presetForViewRule } from "./viewCamera.js";
17
17
  import { DeveloperToggle, TopBar } from "./TopBar.js";
18
+ import { shownAt } from "../app/viewHiding.js";
18
19
  import { availableObjectById, findCameraPreset, firstAvailableObject, focusPresetFor, isObjectAvailable, skyFigureById } from "./objectModel.js";
19
20
  import "./controls.css";
20
21
  import "./style.css";
@@ -45,7 +46,7 @@ export function initialObjectId(experience, timeUtcMs) {
45
46
  }
46
47
  /** The story-panel settings the experience carries itself, used when the app gives none live. */
47
48
  function ownStorySettings(storySet) {
48
- return { autoOpen: storySet?.autoOpen ?? false, pauseSeconds: storySet?.pauseSeconds ?? 0 };
49
+ return { autoOpen: storySet?.autoOpen ?? false, pauseSeconds: storySet?.pauseSeconds ?? 0, ...(storySet?.closeAfterSeconds === undefined ? {} : { closeAfterSeconds: storySet.closeAfterSeconds }) };
49
50
  }
50
51
  /** The timeline bar, or nothing when the experience says it has no timeline. */
51
52
  function ShellTimeline({ hidden, ...bar }) {
@@ -70,6 +71,12 @@ function selectionLost(selected, timeUtcMs, clearedByHost, isFigure) {
70
71
  // A selected sky figure is never lost: it has no availability and no view hides it.
71
72
  return !clearedByHost && !isFigure && (selected === undefined || !isObjectAvailable(selected, timeUtcMs));
72
73
  }
74
+ /** What a camera preset's object asks of the camera at `timeUtcMs`: "hold" when its shown time has ended or not begun (keep the pose), "overview" when it is gone or unavailable, else undefined. */
75
+ function cameraTargetLoss(target, timeUtcMs) {
76
+ if (target !== undefined && !shownAt(target, timeUtcMs))
77
+ return "hold";
78
+ return target === undefined || !isObjectAvailable(target, timeUtcMs) ? "overview" : undefined;
79
+ }
73
80
  function serialOf(request) {
74
81
  return request?.serial;
75
82
  }
@@ -114,17 +121,17 @@ function objectLabelOr(experience, objectId, fallback) {
114
121
  return experience.objects.find((object) => object.id === objectId)?.label ?? skyFigureById(experience, objectId)?.label ?? fallback;
115
122
  }
116
123
  /** The information panel's content and, for an object, its live measurements. */
117
- function infoContent(experience, info, selectedObjectId, timeUtcMs, metricsFor) {
124
+ function infoContent(experience, info, selectedObjectId, timeUtcMs, metricsFor, timeLook) {
118
125
  const view = info === null
119
126
  ? null
120
- : infoView(experience, info.kind === "object" ? { kind: "object", id: selectedObjectId } : info, timeUtcMs);
127
+ : infoView(experience, info.kind === "object" ? { kind: "object", id: selectedObjectId } : info, timeUtcMs, timeLook);
121
128
  const metrics = view?.target.kind === "object" && metricsFor !== undefined && skyFigureById(experience, view.target.id) === undefined ? metricsFor(view.target.id, timeUtcMs) : [];
122
129
  return { view, metrics };
123
130
  }
124
131
  /** The moon families load on demand: only an experience with `moonFamilies` draws them (I-089). */
125
132
  const MoonFamilyPanel = lazy(() => import("./MoonFamilyPanel.js").then((module) => ({ default: module.MoonFamilyPanel })));
126
133
  /** Canvas-first layout shared by astronomy experiences. Scene and diagnostics stay app-owned. */
127
- export function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onTurnToFigure, onCameraHold, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout = DEFAULT_PHONE_LAYOUT, labelStyle, highlightedFamily = null, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }) {
134
+ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onTurnToFigure, onCameraHold, onTimeShown, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout = DEFAULT_PHONE_LAYOUT, labelStyle, timeLook, highlightedFamily = null, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }) {
128
135
  const infoPanelId = `${useId()}-info-panel`;
129
136
  const [selectedObjectId, setSelectedObjectId] = useState(() => initialObjectId(experience, snapshot.timeUtcMs));
130
137
  const phone = usePhone();
@@ -202,6 +209,7 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
202
209
  if (switchRule !== undefined && selected === undefined)
203
210
  setInfo((now) => (now?.kind === "object" ? null : now));
204
211
  }
212
+ onTimeShown?.(snapshot.timeUtcMs);
205
213
  const active = experience.cameraPresets.find((preset) => preset.id === activePresetId);
206
214
  const activeRequest = active?.request;
207
215
  if (switchRule?.rule === "start" && switchRule.framing?.always === true) {
@@ -212,12 +220,8 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
212
220
  if (switchRule !== undefined && target === undefined) {
213
221
  applyViewRule(switchRule);
214
222
  }
215
- else if (target === undefined || !isObjectAvailable(target, snapshot.timeUtcMs)) {
216
- const overview = findCameraPreset(experience, "overview");
217
- if (overview !== undefined) {
218
- setActivePresetId(overview.id);
219
- onCameraRequest(overview.request);
220
- }
223
+ else {
224
+ loseCameraTarget(cameraTargetLoss(target, snapshot.timeUtcMs));
221
225
  }
222
226
  }
223
227
  // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -237,6 +241,20 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
237
241
  // Only a new request applies.
238
242
  // eslint-disable-next-line react-hooks/exhaustive-deps
239
243
  }, [requestedSelectSerial]);
244
+ /** The camera's object is gone or not shown: "hold" keeps the pose and stops following (its shown time ended or has not begun, no jump); "overview" frames the overview. */
245
+ const loseCameraTarget = (loss) => {
246
+ if (loss === "hold") {
247
+ setActivePresetId(null);
248
+ onCameraHold?.();
249
+ }
250
+ else if (loss === "overview") {
251
+ const overview = findCameraPreset(experience, "overview");
252
+ if (overview !== undefined) {
253
+ setActivePresetId(overview.id);
254
+ onCameraRequest(overview.request);
255
+ }
256
+ }
257
+ };
240
258
  /** The view's camera rule for a followed or focused object the new view does not show: `stay` keeps the pose and stops following; otherwise the rule's framing is requested. */
241
259
  const applyViewRule = (rule) => {
242
260
  const asked = presetForViewRule(rule, experience);
@@ -265,11 +283,18 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
265
283
  setInfo({ kind: "object" });
266
284
  };
267
285
  /** An object tapped or clicked in the scene: the picker's focus; on a wide screen it also opens the card, on a phone it does not (T-138). A tapped body-set member that is no listed object just flies there. */
268
- const pickObject = (id) => {
286
+ const pickObject = (id, keepSky = false) => {
269
287
  const object = availableObjectById(experience, id, snapshot.timeUtcMs);
270
288
  if (skyFigureById(experience, id) !== undefined) {
271
289
  selectFigure(id, pickOpensInfo(phone));
272
290
  }
291
+ else if (object !== undefined && keepSky) {
292
+ // A tap from a look-out camera: select it and stay in the sky (owner, 2026-11-15); the menu's Focus and Follow still fly there.
293
+ setSelectedObjectId(object.id);
294
+ onSelectionChange(object.id, "visitor");
295
+ if (pickOpensInfo(phone))
296
+ setInfo({ kind: "object" });
297
+ }
273
298
  else if (object !== undefined) {
274
299
  activatePreset(focusPresetFor(experience, object));
275
300
  if (pickOpensInfo(phone))
@@ -281,7 +306,7 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
281
306
  const requestedPickSerial = serialOf(pickRequest);
282
307
  useEffect(() => {
283
308
  if (pickRequest !== null && pickRequest !== undefined)
284
- pickObject(pickRequest.id);
309
+ pickObject(pickRequest.id, pickRequest.keepSky === true);
285
310
  // Only a new request flies; the handler reads the current time and experience.
286
311
  // eslint-disable-next-line react-hooks/exhaustive-deps
287
312
  }, [requestedPickSerial]);
@@ -350,7 +375,7 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
350
375
  if (info?.kind === "window")
351
376
  setInfo({ kind: "window", id: window.id });
352
377
  };
353
- const { view, metrics } = infoContent(experience, info, selectedObjectId, snapshot.timeUtcMs, metricsFor);
378
+ const { view, metrics } = infoContent(experience, info, selectedObjectId, snapshot.timeUtcMs, metricsFor, timeLook);
354
379
  // On a wide screen the moons sheet and the information panel share the left column under the toolbar: opening one closes the other.
355
380
  const toggleMoons = () => {
356
381
  if (!moonsOpen)
@@ -362,5 +387,5 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
362
387
  const selectedLabel = objectLabelOr(experience, selectedObjectId, "Controls");
363
388
  const topBar = (_jsx(TopBar, { experience: experience, timeUtcMs: snapshot.timeUtcMs, selectedObjectId: selectedObjectId, activePresetId: activePresetId, onSelectObject: selectObject, onCameraPreset: activatePreset, infoOpen: info?.kind === "object", onToggleInfo: () => setInfo(info?.kind === "object" ? null : { kind: "object" }), infoPanelId: infoPanelId, scaleId: scaleId, onScaleChange: onScaleChange, scaleChoices: scaleChoices, switcher: switcher, displaySwitches: displaySwitches, viewChoice: viewChoice }));
364
389
  const moonPanel = experience.moonFamilies === undefined ? null : (_jsx(PanelLoadBoundary, { message: "The moon list could not load. Reload the page to try again.", children: _jsx(Suspense, { fallback: null, children: _jsx(MoonFamilyPanel, { list: experience.moonFamilies, highlightedFamily: highlightedFamily, onHighlight: (id) => onHighlightFamily?.(id), onSelectMoon: chooseMoon }) }) }));
365
- return (_jsxs("main", { className: "astraeus-shell", ref: root, "data-phone": phone, "data-timeline-hidden": experience.hideTimeline === true, "data-embedded": embedded, style: { ...phoneLayoutStyle(phoneLayout), ...labelStyleVars(labelStyle) }, children: [_jsx("div", { className: "shell-canvas", children: children }), phone && _jsxs(ControlsDrawer, { label: selectedLabel, open: controlsOpen, onOpenChange: openControls, swipeThresholdPx: phoneLayout.swipeThresholdPx, children: [topBar, moonPanel] }), _jsxs("div", { className: "shell-top", children: [!phone && topBar, !phone && moonPanel !== null && _jsx(MoonsSheet, { planetLabel: experience.moonFamilies?.planetLabel, open: moonsOpen, onToggle: toggleMoons, onClose: () => setMoonsOpen(false), children: moonPanel }), view !== null && _jsx(InfoPanel, { view: view, metrics: metrics, onClose: () => setInfo(null), id: infoPanelId })] }), story.openPanel !== null && (_jsx(StoryPanelView, { panel: story.openPanel, holding: story.holding, onClose: closePanel, onContinue: story.continuePlayback, step: stepNav })), _jsx(DeveloperDrawer, { developerMode: developerMode, onDeveloperModeChange: onDeveloperModeChange, children: developerTools }), _jsx(ShellTimeline, { hidden: experience.hideTimeline === true, experience: experience, snapshot: snapshot, onTogglePlayback: onTogglePlayback, onRateChange: onRateChange, paceAuto: paceAuto, onSeek: seek, panels: storyPanels, openPanelId: openPanelId, onPanelOpen: openPanelFromTimeline, onEventSeek: seekToEvent, onEventInfo: (event) => setInfo({ kind: "event", id: event.id }), onWindowSeek: seekToWindow, onWindowInfo: (window) => setInfo({ kind: "window", id: window.id }), glowLook: timelineGlow, infoPanelId: infoPanelId, drawer: phone ? { open: timelineOpen, onOpenChange: openTimeline, swipeThresholdPx: phoneLayout.swipeThresholdPx } : undefined })] }));
390
+ return (_jsxs("main", { className: "astraeus-shell", ref: root, "data-phone": phone, "data-timeline-hidden": experience.hideTimeline === true, "data-embedded": embedded, style: { ...phoneLayoutStyle(phoneLayout), ...labelStyleVars(labelStyle) }, children: [_jsx("div", { className: "shell-canvas", children: children }), phone && _jsxs(ControlsDrawer, { label: selectedLabel, open: controlsOpen, onOpenChange: openControls, swipeThresholdPx: phoneLayout.swipeThresholdPx, children: [topBar, moonPanel] }), _jsxs("div", { className: "shell-top", children: [!phone && topBar, !phone && moonPanel !== null && _jsx(MoonsSheet, { planetLabel: experience.moonFamilies?.planetLabel, open: moonsOpen, onToggle: toggleMoons, onClose: () => setMoonsOpen(false), children: moonPanel }), view !== null && _jsx(InfoPanel, { view: view, metrics: metrics, onClose: () => setInfo(null), id: infoPanelId })] }), story.openPanel !== null && (_jsx(StoryPanelView, { panel: story.openPanel, holding: story.holding, onClose: closePanel, onContinue: story.continuePlayback, step: stepNav })), _jsx(DeveloperDrawer, { developerMode: developerMode, onDeveloperModeChange: onDeveloperModeChange, children: developerTools }), _jsx(ShellTimeline, { hidden: experience.hideTimeline === true, experience: experience, snapshot: snapshot, timeLook: timeLook, onTogglePlayback: onTogglePlayback, onRateChange: onRateChange, paceAuto: paceAuto, onSeek: seek, panels: storyPanels, openPanelId: openPanelId, onPanelOpen: openPanelFromTimeline, onEventSeek: seekToEvent, onEventInfo: (event) => setInfo({ kind: "event", id: event.id }), onWindowSeek: seekToWindow, onWindowInfo: (window) => setInfo({ kind: "window", id: window.id }), glowLook: timelineGlow, infoPanelId: infoPanelId, drawer: phone ? { open: timelineOpen, onOpenChange: openTimeline, swipeThresholdPx: phoneLayout.swipeThresholdPx } : undefined })] }));
366
391
  }