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
package/src/api/scene.js CHANGED
@@ -23,6 +23,8 @@ import { buildTracked, pathReads } from "./planPaths.js";
23
23
  import { toUtcMs } from "./time.js";
24
24
  import { TimelinePlan } from "./planTimeline.js";
25
25
  import { ViewPlan } from "./planViews.js";
26
+ import { lookReadFrom } from "../app/liveLook.js";
27
+ import { resolveLook } from "../app/look.js";
26
28
  import { checkedLook } from "./lookInput.js";
27
29
  export { toUtcMs } from "./time.js";
28
30
  const DEFAULT_BODY_READOUTS = Object.freeze(["distance"]);
@@ -102,6 +104,18 @@ export class Scene {
102
104
  get activities() { return this.#groupPlan.activityReads(); }
103
105
  /** The timeline the scene opens with: its span and opening moment in UTC milliseconds (`windowStartUtcMs`, `windowEndUtcMs`, `openUtcMs`), the speeds offered (`rates`), the opening `rate` and whether playback wraps (`loop`). With no span or moment set and no path or activity, the span is a month about the moment of the read. A moment outside a span set with `setTimeline` throws `bad-timeline`, as `mount` would. */
104
106
  get timeline() { return this.#timeline.read(this.#spans()); }
107
+ /** The looks `setLook` set, defaults filled in: what `ViewerHandle.look` reads on a fresh mount. */
108
+ get look() {
109
+ const read = lookReadFrom(resolveLook(this.#look, ""), this.#viewPlan.switchesEntry(), [...this.#plan.bodies.keys()].map((id) => this.#plan.catalogue.get(id)));
110
+ for (const part of [read.sunGlow, read.skyLines, read.labels, read.time])
111
+ if (part !== undefined)
112
+ Object.freeze(part);
113
+ return Object.freeze(read);
114
+ }
115
+ /** The switches `setSwitches` placed, each `{ place, on, label? }`; an unnamed one is absent. Frozen. */
116
+ get switches() { return this.#viewPlan.switchReads(); }
117
+ /** How story panels play (`setStoryPanelPlayback`), defaults filled in. Frozen. */
118
+ get panelPlayback() { return this.#story.playbackRead(); }
105
119
  /** The spans of the paths and activities, which the timeline follows when nothing sets it. */
106
120
  #spans() {
107
121
  return [...[...this.#tracked.values()].map(({ body }) => body.trajectory.bounds), ...[...this.#groupPlan.activities.values()].map((activity) => activity.window)];
@@ -297,7 +311,7 @@ export class Scene {
297
311
  this.#story.addPanels(frozenCopy(panels));
298
312
  return this;
299
313
  }
300
- /** Sets how story panels play: `pauseSeconds` and `autoOpen` (see `StoryPanelPlaybackInput`). Replaces the whole setting, so a field left out returns to its default. A bad value throws `bad-panels`. */
314
+ /** Sets how story panels play: `pauseSeconds`, `autoOpen` and `closeAfterSeconds` (see `StoryPanelPlaybackInput`). Replaces the whole setting, so a field left out returns to its default. A bad value throws `bad-panels`. */
301
315
  setStoryPanelPlayback(playback) {
302
316
  this.#editable();
303
317
  this.#story.setPanelPlayback(frozenCopy(playback));
@@ -313,7 +327,7 @@ export class Scene {
313
327
  * Places the display switches: for each of `orbitLines` (orbit ring, trailing arc and moon orbits), `labels` (body and anchor labels) and `milkyWay` (the sky picture), `place` is
314
328
  * `"top-bar"` (a button in the bar), `"panel"` (a row in one switch panel opened from the bar) or `"developer"` (only in the Developer drawer, where every switch stays), and `on` is
315
329
  * whether it starts on (default on). A switch the scene has nothing for (orbit lines with no orbit drawn) shows nowhere. May be called more than once; later calls replace the same switch.
316
- * A bad switch name, place or `on` throws `bad-switch`.
330
+ * A bad switch name, place, `on` or `label` throws `bad-switch`.
317
331
  * @example
318
332
  * scene.setSwitches({ orbitLines: { place: "top-bar" }, labels: { place: "panel", on: false }, milkyWay: { place: "developer", on: false } });
319
333
  */
@@ -100,7 +100,7 @@ export interface SceneEventRead {
100
100
  readonly label: string;
101
101
  readonly timeUtcMs: number;
102
102
  readonly type?: string;
103
- /** The id of the body or path the event is about. */
103
+ /** The id of the body, path or sky figure the event is about. */
104
104
  readonly object?: string;
105
105
  /** The half-width of the event's own zone in simulated seconds (`withinSeconds` of `addEvents`); absent when it has none. */
106
106
  readonly withinSeconds?: number;
@@ -167,7 +167,37 @@ export interface SceneTimelineRead {
167
167
  readonly rate: number;
168
168
  /** Whether playback wraps from the end to the start. */
169
169
  readonly loop: boolean;
170
+ /** Opens playing. */
171
+ readonly playing: boolean;
172
+ /** The pacing `setTimeline` was given. */
173
+ readonly pacing?: readonly ScenePacingRead[];
170
174
  }
175
+ /** A placed switch (`setSwitches`), as `Scene.switches` reads it. */
176
+ export interface SceneSwitchRead {
177
+ readonly place: "top-bar" | "panel" | "developer";
178
+ readonly on: boolean;
179
+ readonly label?: string;
180
+ }
181
+ /** Panel playback, as `Scene.panelPlayback` reads it. */
182
+ export interface ScenePanelPlaybackRead {
183
+ readonly pauseSeconds: number;
184
+ readonly autoOpen: boolean;
185
+ readonly closeAfterSeconds?: number;
186
+ }
187
+ /** One piece of `setTimeline`'s `pacing`, as `Scene.timeline.pacing` reads it: UTC milliseconds, ramps filled in. */
188
+ export type ScenePacingRead = {
189
+ readonly spanStartUtcMs: number;
190
+ readonly spanEndUtcMs: number;
191
+ readonly rate: number;
192
+ readonly rampSeconds: number;
193
+ } | {
194
+ readonly near: {
195
+ readonly type: string;
196
+ readonly withinSeconds: number;
197
+ };
198
+ readonly rate: number;
199
+ readonly rampSeconds: number;
200
+ };
171
201
  /** A sky figure the scene holds (`addSkyFigures`), as `Scene.skyFigures` lists it (in the order added) and the viewer handle reads it. */
172
202
  export interface SceneSkyFigureRead {
173
203
  readonly id: string;
@@ -0,0 +1,12 @@
1
+ import type { ShownSpan } from "../shell/experience.js";
2
+ import { type TimeInput } from "./time.js";
3
+ /** Shown while `start <= t < end`; an absent end is unbounded, give at least one. Outside it nothing is drawn or pickable; `stateOf` is unchanged. */
4
+ export interface ShownDuringInput {
5
+ readonly start?: TimeInput;
6
+ readonly end?: TimeInput;
7
+ }
8
+ /**
9
+ * Checks a `shownDuring` input (API-04) and returns it in milliseconds (undefined when none is given). `call` is the public call's name, `code` its own error code
10
+ * (`bad-body` for `addBody` and `addBodyFromElements`, `bad-trajectory` for `addTrajectory`). Not an object, no end, a bad moment or an end not after the start throws.
11
+ */
12
+ export declare function planShownDuring(call: string, id: string, code: "bad-body" | "bad-trajectory", input: ShownDuringInput | undefined): ShownSpan | undefined;
@@ -0,0 +1,30 @@
1
+ import { SceneError } from "./errors.js";
2
+ import { toUtcMs } from "./time.js";
3
+ /**
4
+ * Checks a `shownDuring` input (API-04) and returns it in milliseconds (undefined when none is given). `call` is the public call's name, `code` its own error code
5
+ * (`bad-body` for `addBody` and `addBodyFromElements`, `bad-trajectory` for `addTrajectory`). Not an object, no end, a bad moment or an end not after the start throws.
6
+ */
7
+ export function planShownDuring(call, id, code, input) {
8
+ if (input === undefined)
9
+ return undefined;
10
+ const bad = (message) => new SceneError(code, `${call}("${id}"): shownDuring ${message}`);
11
+ if (typeof input !== "object" || input === null || Array.isArray(input))
12
+ throw bad("must be an object { start?, end? }");
13
+ if (input.start === undefined && input.end === undefined)
14
+ throw bad("needs a start, an end or both");
15
+ const moment = (field, time) => {
16
+ if (time === undefined)
17
+ return undefined;
18
+ try {
19
+ return toUtcMs(time, `${call}("${id}") shownDuring.${field}`);
20
+ }
21
+ catch (error) {
22
+ throw bad(`${field}: ${error instanceof Error ? error.message : String(error)}`);
23
+ }
24
+ };
25
+ const startUtcMs = moment("start", input.start);
26
+ const endUtcMs = moment("end", input.end);
27
+ if (startUtcMs !== undefined && endUtcMs !== undefined && endUtcMs <= startUtcMs)
28
+ throw bad("must end after it starts");
29
+ return { ...(startUtcMs === undefined ? {} : { startUtcMs }), ...(endUtcMs === undefined ? {} : { endUtcMs }) };
30
+ }
@@ -15,7 +15,7 @@ export interface EventInput {
15
15
  readonly type?: string;
16
16
  /** Where this event's time comes from. Shown with the event; an event without one shows the `provenance` of `addEvents`. Malformed: `addEvents` throws "bad-event" naming the event. */
17
17
  readonly provenance?: Provenance;
18
- /** The body, trajectory or sky figure (its id) this event is about. Go to this event seeks to its time and, for a body or trajectory, frames the object as `camera.focus` does; for a sky figure it seeks, selects it and turns toward it only while the camera looks out. Not in the scene when the scene is built (`mount`): "bad-event" naming the event and the id. Without one, Go to only seeks. */
18
+ /** The body, path or sky figure (its id) this event is about. Go to this event seeks to its time and, for a body or trajectory, frames the object as `camera.focus` does; for a sky figure it seeks, selects it and turns toward it only while the camera looks out. Not in the scene when the scene is built (`mount`): "bad-event" naming the event and the id. Without one, Go to only seeks. */
19
19
  readonly object?: string;
20
20
  /**
21
21
  * Gives the event a zone of its own: from `withinSeconds` before its time to `withinSeconds` after it (simulated seconds, positive and finite). A host hears entering and leaving it
@@ -38,8 +38,9 @@ export type TimelineInput = {
38
38
  readonly end: TimeInput;
39
39
  readonly rates?: readonly number[];
40
40
  readonly rate?: number; /** Playback that slows for encounters and speeds up for cruise: see `PacingInput`. */
41
- readonly pacing?: readonly PacingInput[]; /** True: while playing, reaching the end wraps to the start and plays on. The viewer can still seek and pause. Default false. Not available with `none: true`, where it is ignored. */
41
+ readonly pacing?: readonly PacingInput[]; /** True: while playing, reaching the end wraps to the start and plays on. Default false. Not available with `none: true`, where it is ignored. */
42
42
  readonly loop?: boolean;
43
+ readonly playing?: boolean;
43
44
  readonly none?: undefined;
44
45
  } | {
45
46
  readonly none: true;
@@ -84,6 +85,8 @@ export interface TimelineSetting {
84
85
  readonly rate?: number;
85
86
  /** Playback wraps from the end of the span to its start. */
86
87
  readonly loop?: boolean;
88
+ /** False: the clock opens paused. Absent: opens playing. */
89
+ readonly playing?: false;
87
90
  /** The checked pacing pieces (absent: none). */
88
91
  readonly pacing?: readonly PacingPiece[];
89
92
  /** No timeline bar. */
@@ -123,6 +126,8 @@ export interface StoryPanelInput {
123
126
  readonly select?: boolean;
124
127
  /** Traces the `object`, a sky figure. */
125
128
  readonly trace?: true | SkyTraceOptions;
129
+ /** Simulated seconds after `at` when forward playback closes this panel (above 0); overrides the playback setting. A seek, rewind or pause never closes it. Not for a step: that throws `bad-panels`. */
130
+ readonly closeAfterSeconds?: number;
126
131
  }
127
132
  /** The playback settings of a scene's story panels. */
128
133
  export interface StoryPanelPlaybackInput {
@@ -130,6 +135,8 @@ export interface StoryPanelPlaybackInput {
130
135
  readonly pauseSeconds?: number;
131
136
  /** Whether panels open by themselves as forward playback crosses them (default true). */
132
137
  readonly autoOpen?: boolean;
138
+ /** Simulated seconds after a moment panel's time when forward playback closes it (above 0; absent: panels close only when the visitor closes them). A panel's own `closeAfterSeconds` wins. */
139
+ readonly closeAfterSeconds?: number;
133
140
  }
134
141
  /** Throws "bad-event" naming the first event whose `object` is not among the scene's `objectIds`. */
135
142
  export declare function checkEventObjects(events: readonly TimelineEvent[], objectIds: ReadonlySet<string>): void;
@@ -146,7 +153,7 @@ export declare function panelPlaybackOf(input: StoryPanelPlaybackInput): PanelPl
146
153
  /** The story panels resolved against the scene's events, anchors, objects and window; a mistake becomes a `bad-panels` SceneError. */
147
154
  export declare function panelsOf(panels: readonly CheckedPanel[], playback: PanelPlayback, lookup: PanelLookup): StoryPanelSet;
148
155
  /**
149
- * The pacing the viewer runs, laid over the events: spans, then one zone per event of each rule's type. `pacedRate` lays the zones fastest first, so the slowest applicable piece wins wherever they meet, whatever contains what.
156
+ * The pacing the viewer runs, laid over the events: spans, then one zone per event of each rule's type. `pacedRate` lets faster spans set the cruise (the faster wins) and eases slower spans and event rules down from it (the slowest wins wherever they meet), whatever contains what.
150
157
  * A rule whose type has no event throws `bad-timeline` naming the piece (a mistyped type would otherwise slow nothing, silently).
151
158
  */
152
159
  export declare function pacingFor(setting: TimelineSetting, events: readonly TimelineEvent[], baseRate: number): Pacing | undefined;
package/src/api/story.js CHANGED
@@ -63,8 +63,7 @@ export function timelineOf(input) {
63
63
  throw bad("give an object such as { start, end } or { none: true }");
64
64
  if (input.rate !== undefined && !(Number.isFinite(input.rate) && input.rate !== 0))
65
65
  throw bad(`rate must be a finite, non-zero number, got ${String(input.rate)}`);
66
- if (input.loop !== undefined && typeof input.loop !== "boolean")
67
- throw bad("loop must be true or false");
66
+ const flags = timelineFlags(input, bad);
68
67
  if (input.none === true)
69
68
  return { none: true, ...(input.at === undefined ? {} : { atUtcMs: toUtcMs(input.at, "setTimeline at") }), ...(input.rate === undefined ? {} : { rate: input.rate }) };
70
69
  const window = { startUtcMs: toUtcMs(input.start, "setTimeline start"), endUtcMs: toUtcMs(input.end, "setTimeline end") };
@@ -75,7 +74,15 @@ export function timelineOf(input) {
75
74
  throw bad("rates must be a non-empty list of positive numbers");
76
75
  const pacing = pacingOf(input.pacing, bad);
77
76
  warnOfFastRates(window, input);
78
- return { none: false, window, ...(rates === undefined ? {} : { rates }), ...(pacing === undefined ? {} : { pacing }), ...(input.rate === undefined ? {} : { rate: input.rate }), ...(input.loop === true ? { loop: true } : {}) };
77
+ return { none: false, window, ...(rates === undefined ? {} : { rates }), ...(pacing === undefined ? {} : { pacing }), ...(input.rate === undefined ? {} : { rate: input.rate }), ...flags };
78
+ }
79
+ /** The checked `loop` and `playing` flags of a `setTimeline` argument: only a `true` loop and a `false` playing are kept (the defaults are false and true); a non-boolean throws. */
80
+ function timelineFlags(input, bad) {
81
+ const given = input;
82
+ for (const flag of ["loop", "playing"])
83
+ if (given[flag] !== undefined && typeof given[flag] !== "boolean")
84
+ throw bad(`${flag} must be true or false`);
85
+ return { ...(given.loop === true ? { loop: true } : {}), ...(given.playing === false ? { playing: false } : {}) };
79
86
  }
80
87
  /** Runs a core panel check, turning a `StoryPanelError` into a `bad-panels` SceneError that leads with `call`. */
81
88
  function panelCheck(call, check) {
@@ -186,7 +193,7 @@ function pacingOf(input, bad) {
186
193
  return pieces.length === 0 ? undefined : pieces;
187
194
  }
188
195
  /**
189
- * The pacing the viewer runs, laid over the events: spans, then one zone per event of each rule's type. `pacedRate` lays the zones fastest first, so the slowest applicable piece wins wherever they meet, whatever contains what.
196
+ * The pacing the viewer runs, laid over the events: spans, then one zone per event of each rule's type. `pacedRate` lets faster spans set the cruise (the faster wins) and eases slower spans and event rules down from it (the slowest wins wherever they meet), whatever contains what.
190
197
  * A rule whose type has no event throws `bad-timeline` naming the piece (a mistyped type would otherwise slow nothing, silently).
191
198
  */
192
199
  export function pacingFor(setting, events, baseRate) {
@@ -8,6 +8,7 @@ export type SwitchesInput = {
8
8
  readonly [id in DisplaySwitchId]?: {
9
9
  readonly place: DisplaySwitchPlace;
10
10
  readonly on?: boolean;
11
+ readonly label?: string;
11
12
  };
12
13
  };
13
14
  /** Checks a `setSwitches` argument against the switch names and places; returns the settings laid over the ones already set. */
@@ -13,7 +13,9 @@ export function switchesOf(input, known = {}) {
13
13
  throw bad(`${id}.place must be one of ${DISPLAY_SWITCH_PLACES.join(", ")}, got ${JSON.stringify(setting?.place)}`);
14
14
  if (setting.on !== undefined && typeof setting.on !== "boolean")
15
15
  throw bad(`${id}.on must be true or false, got ${JSON.stringify(setting.on)}`);
16
- settings[id] = { place: setting.place, ...(setting.on === undefined ? {} : { on: setting.on }) };
16
+ if (setting.label !== undefined && (typeof setting.label !== "string" || setting.label.trim() === ""))
17
+ throw bad(`${id}.label must be a non-empty text, got ${JSON.stringify(setting.label)}`);
18
+ settings[id] = { place: setting.place, ...(setting.on === undefined ? {} : { on: setting.on }), ...(setting.label === undefined ? {} : { label: setting.label.trim() }) };
17
19
  }
18
20
  return settings;
19
21
  }
package/src/api/time.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { type TimeInput } from "../core/timeInput.js";
2
2
  /** A moment: ISO text, a Date, or Unix milliseconds. */
3
3
  export type { TimeInput };
4
- /** Converts a moment to Unix milliseconds, or throws a `bad-time` SceneError naming it. */
4
+ /** Converts a moment to Unix milliseconds, or throws a `bad-time` SceneError naming it: not a moment, not a whole number of milliseconds (a fractional time is refused, never floored; I-177) or outside the Date range. */
5
5
  export declare function toUtcMs(time: TimeInput, what?: string): number;
package/src/api/time.js CHANGED
@@ -1,9 +1,12 @@
1
1
  import { SceneError } from "./errors.js";
2
+ import { isUtcUnixMs } from "../core/state.js";
2
3
  import { timeInputMs } from "../core/timeInput.js";
3
- /** Converts a moment to Unix milliseconds, or throws a `bad-time` SceneError naming it. */
4
+ /** Converts a moment to Unix milliseconds, or throws a `bad-time` SceneError naming it: not a moment, not a whole number of milliseconds (a fractional time is refused, never floored; I-177) or outside the Date range. */
4
5
  export function toUtcMs(time, what = "time") {
5
6
  const ms = timeInputMs(time);
6
7
  if (!Number.isFinite(ms))
7
8
  throw new SceneError("bad-time", `${what} "${String(time)}" is not a valid moment; use an ISO text such as "1969-07-20T20:17:40Z", a Date or Unix milliseconds`);
9
+ if (!isUtcUnixMs(ms))
10
+ throw new SceneError("bad-time", `${what} ${String(time)} must be a whole number of Unix milliseconds inside the Date range (a fractional or out-of-range time is refused, never rounded)`);
8
11
  return ms;
9
12
  }
package/src/app/App.js CHANGED
@@ -3,6 +3,7 @@ import { Suspense, useCallback, useEffect, useMemo, useRef, useState, useSyncExt
3
3
  import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
4
4
  import { viewUpFromSearch, viewUpVector } from "./viewUp.js";
5
5
  import { activeEventZones, applyPacing, startPaceEase } from "../core/pacing.js";
6
+ import { frameTime } from "./sceneFrame.js";
6
7
  import { openClock } from "./openClock.js";
7
8
  import { createProvenance } from "../core/provenance.js";
8
9
  import { pickerSwitch } from "./listSwitch.js";
@@ -35,7 +36,9 @@ import { displaySwitchItems, hostReachable, orbitStart, skyLineStart } from "./d
35
36
  import { TRACE_FADE_SECONDS } from "../core/skyTrace.js";
36
37
  import { aimAtFigure, DEFAULT_SKY_LINES, prefersReducedMotion, skyColoursOf, skyFadeInSecondsOf } from "./skyFigures.js";
37
38
  import { labelStyleOf } from "./labelStyle.js";
38
- import { experienceInView, hiddenByView, viewById } from "./viewHiding.js";
39
+ import { timeLookOf } from "./timeLook.js";
40
+ import { experienceInView, hiddenByView, hiddenWithShownSpans, viewById } from "./viewHiding.js";
41
+ import { cameraIdsOf } from "../core/storyPanels.js";
39
42
  import { baseGlowOf, glowLookOf, markerSettingsOf } from "./bodyDraw.js";
40
43
  import { resolveLook } from "./look.js";
41
44
  import { applyLook, desktopPicturesOf, lookReadOf, presentationOf, skySettingsOf } from "./liveLook.js";
@@ -102,6 +105,10 @@ function startViewUp(definition, search) {
102
105
  function storyStartOf(storySet) {
103
106
  return { autoOpen: storySet?.autoOpen ?? false, pauseSeconds: storySet?.pauseSeconds ?? 0 };
104
107
  }
108
+ /** The story-panel settings in force: the two the Developer drawer changes live, and the close span the scene set. */
109
+ function liveStorySettings(storySet, autoOpen, pauseSeconds) {
110
+ return { autoOpen, pauseSeconds, ...(storySet?.closeAfterSeconds === undefined ? {} : { closeAfterSeconds: storySet.closeAfterSeconds }) };
111
+ }
105
112
  /** Everything one mounted experience shares: clock, resolver, catalogue and the settings read from its definition and the address. */
106
113
  function buildRuntime(definition, search) {
107
114
  const adapter = createOrbAstronomyAdapter();
@@ -175,6 +182,8 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
175
182
  skyTraces: [],
176
183
  skyFadeInSeconds: skyFadeInSecondsOf(runtime.look),
177
184
  labelStyle: labelStyleOf(runtime.look),
185
+ timeLook: timeLookOf(runtime.look),
186
+ sheetMaxPercent: runtime.look.sheetMaxPercent ?? DEFAULT_PHONE_LAYOUT.sheetMaxPercent,
178
187
  skyVisible: runtime.sky.visible,
179
188
  bodyMarker: markerSettingsOf(runtime.look),
180
189
  ...(glowBase === null ? {} : { glowLook: glowLookOf(runtime.look, glowBase) }),
@@ -260,11 +269,15 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
260
269
  const [scale, setScale] = useState(startScale);
261
270
  const [developerMode, setDeveloperMode] = useState(false);
262
271
  const [timelineGlow, setTimelineGlow] = useState(DEFAULT_TIMELINE_GLOW);
263
- const [phoneLayout, setPhoneLayout] = useState(DEFAULT_PHONE_LAYOUT);
272
+ const [phoneLayoutOwn, setPhoneLayout] = useState(DEFAULT_PHONE_LAYOUT);
273
+ // The sheet cap is a look: the live controls hold it, so `setLook`, the handle's `look` and the Developer slider are one value (STYLE-07).
274
+ const [sheetShown, setSheetShown] = useState(controls.current.sheetMaxPercent);
275
+ const phoneLayout = { ...phoneLayoutOwn, sheetMaxPercent: sheetShown };
264
276
  const [anchorLabels, setAnchorLabels] = useState(controls.current.showAnchorLabels);
265
277
  const [skyLinesShown, setSkyLinesShown] = useState(controls.current.skyLines);
266
278
  const [skyColoursShown, setSkyColoursShown] = useState(controls.current.skyColours);
267
279
  const [labelStyleShown, setLabelStyleShown] = useState(controls.current.labelStyle);
280
+ const [timeLookShown, setTimeLookShown] = useState(controls.current.timeLook);
268
281
  const [glowShown, setGlowShown] = useState(copyOfGlow(controls.current.glowLook));
269
282
  const orbitPaths = orbitPathsOf(runtime);
270
283
  const orbitDefault = useMemo(() => resolveOrbitLook(orbitPaths[0]?.look), [orbitPaths]);
@@ -311,7 +324,11 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
311
324
  const [viewNow, setViewNow] = useState(null);
312
325
  const [viewLink, setViewLink] = useState(null);
313
326
  const [fills, setFills] = useState([]);
327
+ /** The ids the camera's last request named (a preset, a host `setCamera`, a story panel's camera): the one rule below holds the camera when one of them stops being shown. */
328
+ const cameraNamed = useRef([]);
329
+ const noteCameraIds = (request) => { const { bodies, toward } = cameraIdsOf(request); cameraNamed.current = toward === undefined ? bodies : [...bodies, toward]; };
314
330
  const updateCameraRequest = useCallback((request) => {
331
+ noteCameraIds(request);
315
332
  controls.current.cameraRequest = aimAtFigure(request, runtime.skyFigures);
316
333
  }, [runtime]);
317
334
  const turnToFigure = useCallback((id) => {
@@ -319,9 +336,17 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
319
336
  if (now !== undefined && "lookOut" in now)
320
337
  updateCameraRequest({ kind: "lookOut", body: now.lookOut, direction: id });
321
338
  }, [updateCameraRequest]);
322
- const holdCamera = useCallback(() => { controls.current.cameraRequest = { kind: "hold" }; }, []);
339
+ const holdCamera = useCallback(() => { cameraNamed.current = []; controls.current.cameraRequest = { kind: "hold" }; }, []);
340
+ /** O-071 (I-175): whatever named the camera's target, once that object is not shown at `timeUtcMs` the camera keeps its pose and stops following (`shownAt`, via `hiddenWithShownSpans`). */
341
+ const holdCameraOffShown = useCallback((timeUtcMs) => {
342
+ if (cameraNamed.current.length === 0)
343
+ return;
344
+ const out = hiddenWithShownSpans(undefined, experience.objects, timeUtcMs)?.objects;
345
+ if (out !== undefined && cameraNamed.current.some((id) => out.has(id)))
346
+ holdCamera();
347
+ }, [experience, holdCamera]);
323
348
  const requestPanel = useCallback((id) => setPanelRequest((previous) => ({ id, serial: (previous?.serial ?? 0) + 1 })), []);
324
- const requestPick = useCallback((id) => setPickRequest((previous) => ({ id, serial: (previous?.serial ?? 0) + 1 })), []);
349
+ const requestPick = useCallback((id, options) => setPickRequest((previous) => ({ id, serial: (previous?.serial ?? 0) + 1, ...(options?.keepSky === true ? { keepSky: true } : {}) })), []);
325
350
  const requestFeature = useCallback((key) => setFeatureRequest((previous) => ({ key, serial: (previous?.serial ?? 0) + 1 })), []);
326
351
  const markOpenFeature = useCallback((key) => { controls.current.openFeatureKey = key; }, []);
327
352
  const setPlaying = useCallback((playing) => {
@@ -404,13 +429,8 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
404
429
  }, [host, stateNow]);
405
430
  useEffect(() => {
406
431
  const id = window.setInterval(() => {
407
- // The readout wraps with the scene, so the shown time never rests past the end while looping.
408
- if (controls.current.loop === true)
409
- runtime.clock.wrapWithin(runtime.loopWindow);
410
- else if (runtime.stopAtWindow === true && runtime.loopWindow !== undefined)
411
- runtime.clock.stopWithin(runtime.loopWindow);
412
- if (controls.current.paceAuto === true && runtime.pacing !== undefined)
413
- applyPacing(runtime.clock, runtime.pacing, controls.current.pace);
432
+ // The readout wraps, stops and paces with the scene, so the shown time never rests past the end while looping and a host's playback reports follow the slow-downs.
433
+ frameTime(runtime, controls.current);
414
434
  setClockSnapshot(runtime.clock.snapshot());
415
435
  host?.publish(stateNow(), "playback");
416
436
  }, 100);
@@ -419,6 +439,8 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
419
439
  // The host reaches the one clock through the same seek and rate handlers a visitor's timeline uses.
420
440
  const seekTo = useCallback((timeUtcMs) => {
421
441
  runtime.clock.seek(timeUtcMs);
442
+ if (controls.current.pace !== undefined)
443
+ delete controls.current.pace.last; // the paced step starts again from the new time
422
444
  // A seek lands on the paced rate for the new time at once, not through a view-switch ease.
423
445
  if (controls.current.pace !== undefined) {
424
446
  delete controls.current.pace.ease;
@@ -450,18 +472,18 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
450
472
  }, [runtime]);
451
473
  // The same play handler the visitor's button reaches, so a host and a visitor share one clock.
452
474
  const hostSetPlaying = setPlaying;
453
- // The objects a host may point the camera at: those the showing view shows (read live, so a view switch is already counted).
475
+ // The objects a host may point the camera at: those the showing view shows and that are shown at the clock time (read live, so a view switch or a time move is already counted).
454
476
  const cameraTargets = useCallback(() => {
455
- const hidden = controls.current.viewHidden?.objects;
477
+ const hidden = hiddenWithShownSpans(controls.current.viewHidden, experience.objects, runtime.clock.snapshot().timeUtcMs)?.objects;
456
478
  return experience.objects.map(({ id }) => id).filter((id) => hidden === undefined || !hidden.has(id));
457
- }, [experience]);
479
+ }, [experience, runtime]);
458
480
  const opening = useMemo(() => openingCamera(definition, runtime, search), []); // eslint-disable-line react-hooks/exhaustive-deps
459
481
  const readCamera = useCallback(() => {
460
482
  const view = controls.current.viewReadout ?? opening;
461
483
  return view === undefined ? undefined : { ...view };
462
484
  }, [opening]);
463
485
  // A host camera call is the last word: it is also kept in `hostCameraRequest`, so the opening view (first frame) and a view's own camera rule (shell) yield to it.
464
- const setCamera = useCallback((request) => { controls.current.cameraRequest = controls.current.hostCameraRequest = aimAtFigure(request, runtime.skyFigures); }, [runtime]);
486
+ const setCamera = useCallback((request) => { noteCameraIds(request); controls.current.cameraRequest = controls.current.hostCameraRequest = aimAtFigure(request, runtime.skyFigures); }, [runtime]);
465
487
  const hostCameraSet = useCallback(() => controls.current.hostCameraRequest != null, []);
466
488
  const hostScales = useMemo(() => scaleChoiceIds ?? SCALE_CHOICES.map((choice) => choice.id), [scaleChoiceIds]);
467
489
  const hostSetLook = useCallback((look) => live.current?.setLook(look), []);
@@ -473,6 +495,12 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
473
495
  const panelTrace = useRef(null);
474
496
  /** The panel whose actions were last applied (a host `setPanel` shows its panel at once, so `openStoryPanelId` cannot say whether the shell has opened it yet). */
475
497
  const actedPanel = useRef(null);
498
+ /** Whether the objects a story panel's camera names are shown at the clock time; a request toward one outside its `shownDuring` span is refused as `setCamera` refuses it. */
499
+ const shownAtClock = useCallback((request) => {
500
+ const out = hiddenWithShownSpans(undefined, experience.objects, runtime.clock.snapshot().timeUtcMs)?.objects;
501
+ const { bodies, toward } = cameraIdsOf(request);
502
+ return out === undefined || ![...bodies, ...(toward === undefined ? [] : [toward])].some((id) => out.has(id));
503
+ }, [experience, runtime]);
476
504
  /** The shell's open panel changed (a visitor, a host call already shown, playback crossing a panel, or a view switch dropping it); a change is told to the host, the opening panel is read at attach. */
477
505
  const markOpenPanel = useCallback((id, cause) => {
478
506
  const changed = (controls.current.openStoryPanelId ?? null) !== id;
@@ -491,7 +519,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
491
519
  if (panel === undefined)
492
520
  return;
493
521
  // The panel's actions go through the host calls, in this order: camera, select, trace.
494
- if (panel.camera !== undefined)
522
+ if (panel.camera !== undefined && shownAtClock(panel.camera))
495
523
  setCamera(panel.camera);
496
524
  if (panel.select === true && panel.objectId !== undefined)
497
525
  selectWith(panel.objectId, true);
@@ -499,7 +527,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
499
527
  hostTraceSkyFigure(panel.objectId, panel.trace.seconds, panel.trace.after);
500
528
  panelTrace.current = panel.objectId;
501
529
  }
502
- }, [host, stateNow, definition, setCamera, selectWith, hostTraceSkyFigure, hostClearSkyTrace]);
530
+ }, [host, stateNow, definition, setCamera, shownAtClock, selectWith, hostTraceSkyFigure, hostClearSkyTrace]);
503
531
  useEffect(() => {
504
532
  if (host === undefined)
505
533
  return undefined;
@@ -573,6 +601,8 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
573
601
  setLoadFade(read.loadFadeSeconds);
574
602
  setSkyColoursShown(controls.current.skyColours);
575
603
  setLabelStyleShown(controls.current.labelStyle);
604
+ setTimeLookShown(controls.current.timeLook);
605
+ setSheetShown(read.sheetMaxPercent);
576
606
  },
577
607
  setScale: updateScale,
578
608
  items: () => displaySwitchItems({ ...bindingsNow(), settings: hostReachable(definition.displaySwitches) }),
@@ -587,7 +617,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
587
617
  shownKey.current = key;
588
618
  if (changed)
589
619
  host?.publish(state, "visitor");
590
- }, [host, stateNow, scale, skyVisible, starBrightness, milkyWayBrightness, milkyWayOn, glowShown, markerPx, loadFade, orbitShown, setLook, hiddenLabels, anchorLabels, skyLinesShown, skyColoursShown, labelStyleShown]);
620
+ }, [host, stateNow, scale, skyVisible, starBrightness, milkyWayBrightness, milkyWayOn, glowShown, markerPx, loadFade, orbitShown, setLook, hiddenLabels, anchorLabels, skyLinesShown, skyColoursShown, labelStyleShown, timeLookShown, sheetShown]);
591
621
  const hasStoryPanels = (storySet?.panels.length ?? 0) > 0;
592
622
  const showDisplay = showsDisplayControls(definition, runtime, skyVisible, orbitPaths.length, storyMarkerSpecs.length);
593
623
  // Orbit-line sliders: the first four stay in view, the rest sit in a nested "Fine-tune" fold (T-090).
@@ -649,7 +679,14 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
649
679
  ["timelineDrawerMaxPercent", "Timeline drawer height (% of screen)", "Phone timeline drawer height", "phone-timeline-height-value"],
650
680
  ["sheetMaxPercent", "Sheet height (% of screen)", "Phone sheet height", "phone-sheet-height-value"],
651
681
  ["swipeThresholdPx", "Swipe distance (px)", "Phone swipe distance", "phone-swipe-value"],
652
- ].map(([key, label, ariaLabel, testId]) => (_jsx(SettingSlider, { label: label, ariaLabel: ariaLabel, testId: testId, display: String(phoneLayout[key]), min: PHONE_LAYOUT_LIMITS[key].min, max: PHONE_LAYOUT_LIMITS[key].max, step: PHONE_LAYOUT_LIMITS[key].step, value: phoneLayout[key], onChange: (value) => setPhoneLayout({ ...phoneLayout, [key]: value }) }, key))), _jsx(SettingButtons, { children: _jsx("button", { onClick: () => setPhoneLayout(DEFAULT_PHONE_LAYOUT), children: "Reset phone layout" }) })] })),
682
+ ].map(([key, label, ariaLabel, testId]) => (_jsx(SettingSlider, { label: label, ariaLabel: ariaLabel, testId: testId, display: String(phoneLayout[key]), min: PHONE_LAYOUT_LIMITS[key].min, max: PHONE_LAYOUT_LIMITS[key].max, step: PHONE_LAYOUT_LIMITS[key].step, value: phoneLayout[key], onChange: (value) => {
683
+ if (key === "sheetMaxPercent") {
684
+ controls.current.sheetMaxPercent = value;
685
+ setSheetShown(value);
686
+ }
687
+ else
688
+ setPhoneLayout({ ...phoneLayoutOwn, [key]: value });
689
+ } }, key))), _jsx(SettingButtons, { children: _jsx("button", { onClick: () => { setPhoneLayout(DEFAULT_PHONE_LAYOUT); controls.current.sheetMaxPercent = DEFAULT_PHONE_LAYOUT.sheetMaxPercent; setSheetShown(DEFAULT_PHONE_LAYOUT.sheetMaxPercent); }, children: "Reset phone layout" }) })] })),
653
690
  },
654
691
  {
655
692
  id: "under-the-hood", title: "Under the hood",
@@ -658,7 +695,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
658
695
  ];
659
696
  const presentGroups = groups.filter((group) => group !== null);
660
697
  const drawer = (_jsx(PanelLoadBoundary, { children: _jsx(Suspense, { fallback: _jsx("p", { className: "developer-loading", role: "status", children: "Loading developer tools..." }), children: _jsxs("div", { className: "hud", children: [_jsxs("header", { className: "developer-heading", children: [_jsx("h2", { children: "Developer tools" }), _jsx("p", { children: "Live readouts, controls and diagnostics for this scene." })] }), presentGroups.map((group, index) => (_jsx(Collapsible, { fold: group.id, title: group.title, defaultOpen: index === 0, className: `dev-group${group.className === undefined ? "" : ` ${group.className}`}`, children: group.body }, group.id)))] }) }) }));
661
- return (_jsx(AstraeusShell, { experience: shellExperience, snapshot: clockSnapshot, paceAuto: runtime.pacing === undefined ? undefined : paceAuto, developerMode: developerMode, labelStyle: labelStyleShown, onDeveloperModeChange: setDeveloperMode, onTogglePlayback: () => {
698
+ return (_jsx(AstraeusShell, { experience: shellExperience, snapshot: clockSnapshot, paceAuto: runtime.pacing === undefined ? undefined : paceAuto, developerMode: developerMode, labelStyle: labelStyleShown, timeLook: timeLookShown, onDeveloperModeChange: setDeveloperMode, onTogglePlayback: () => {
662
699
  if (runtime.clock.playing)
663
700
  runtime.clock.pause();
664
701
  else
@@ -671,5 +708,5 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
671
708
  }, onSeek: (timeUtcMs) => {
672
709
  seekTo(timeUtcMs);
673
710
  host?.publish(stateNow(), "visitor");
674
- }, onCameraRequest: updateCameraRequest, onTurnToFigure: turnToFigure, onCameraHold: holdCamera, hostCameraSet: hostCameraSet, storySeekNote: storySeekNote, onSelectionChange: updateSelectedObject, scaleId: scale, onScaleChange: updateScale, scaleChoices: scaleChoices, switcher: definition.picker === undefined ? undefined : pickerSwitch(definition.picker, hostPick ?? definition.picker.value, choosePick), displaySwitches: displaySwitches, viewChoice: viewChoice, viewCamera: currentView === undefined ? undefined : { id: currentView.id, rule: currentView.camera }, metricsFor: metricsFor, developerTools: drawerWhen(developerTools, drawer), storyPanelSettings: { autoOpen: storyAutoOpen, pauseSeconds: storyPauseSeconds }, timelineGlow: timelineGlow, phoneLayout: phoneLayout, highlightedFamily: setLook.highlightFamily, onHighlightFamily: highlightFamily, onSetPlaying: setPlaying, panelRequest: panelRequest, onOpenPanelChange: markOpenPanel, featureRequest: featureRequest, pickRequest: pickRequest, selectRequest: selectRequest, onSelectRequestApplied: hostSelectApplied, onOpenFeatureChange: markOpenFeature, children: _jsx("div", { className: "canvas-host", children: _jsx(AstraeusScene, { runtime: runtime, controls: controls.current, readout: readout, scaleId: scale, onFirstDraw: host === undefined ? undefined : told }) }) }));
711
+ }, onCameraRequest: updateCameraRequest, onTurnToFigure: turnToFigure, onCameraHold: holdCamera, onTimeShown: holdCameraOffShown, hostCameraSet: hostCameraSet, storySeekNote: storySeekNote, onSelectionChange: updateSelectedObject, scaleId: scale, onScaleChange: updateScale, scaleChoices: scaleChoices, switcher: definition.picker === undefined ? undefined : pickerSwitch(definition.picker, hostPick ?? definition.picker.value, choosePick), displaySwitches: displaySwitches, viewChoice: viewChoice, viewCamera: currentView === undefined ? undefined : { id: currentView.id, rule: currentView.camera }, metricsFor: metricsFor, developerTools: drawerWhen(developerTools, drawer), storyPanelSettings: liveStorySettings(storySet, storyAutoOpen, storyPauseSeconds), timelineGlow: timelineGlow, phoneLayout: phoneLayout, highlightedFamily: setLook.highlightFamily, onHighlightFamily: highlightFamily, onSetPlaying: setPlaying, panelRequest: panelRequest, onOpenPanelChange: markOpenPanel, featureRequest: featureRequest, pickRequest: pickRequest, selectRequest: selectRequest, onSelectRequestApplied: hostSelectApplied, onOpenFeatureChange: markOpenFeature, children: _jsx("div", { className: "canvas-host", children: _jsx(AstraeusScene, { runtime: runtime, controls: controls.current, readout: readout, scaleId: scale, onFirstDraw: host === undefined ? undefined : told }) }) }));
675
712
  }