astraeus 0.9.1 → 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 (70) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +20 -13
  3. package/package.json +1 -1
  4. package/src/api/assembleScene.js +4 -4
  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/planCamera.d.ts +19 -2
  11. package/src/api/planCamera.js +45 -6
  12. package/src/api/planPaths.js +2 -2
  13. package/src/api/planStory.d.ts +3 -1
  14. package/src/api/planStory.js +5 -0
  15. package/src/api/planTimeline.d.ts +1 -1
  16. package/src/api/planTimeline.js +10 -1
  17. package/src/api/planViews.d.ts +3 -1
  18. package/src/api/planViews.js +4 -0
  19. package/src/api/scene.d.ts +11 -5
  20. package/src/api/scene.js +16 -2
  21. package/src/api/sceneReads.d.ts +31 -1
  22. package/src/api/story.d.ts +9 -2
  23. package/src/api/story.js +10 -3
  24. package/src/api/switches.d.ts +1 -0
  25. package/src/api/switches.js +3 -1
  26. package/src/api/time.d.ts +1 -1
  27. package/src/api/time.js +4 -1
  28. package/src/app/App.js +26 -6
  29. package/src/app/App.node.js +26 -6
  30. package/src/app/AstraeusScene.d.ts +8 -1
  31. package/src/app/CameraController.d.ts +2 -0
  32. package/src/app/CameraController.js +11 -1
  33. package/src/app/SkyFiguresView.d.ts +2 -2
  34. package/src/app/SkyFiguresView.js +25 -14
  35. package/src/app/displaySwitches.d.ts +2 -0
  36. package/src/app/displaySwitches.js +1 -1
  37. package/src/app/liveLook.d.ts +4 -1
  38. package/src/app/liveLook.js +29 -1
  39. package/src/app/look.d.ts +5 -0
  40. package/src/app/look.js +8 -2
  41. package/src/app/sceneCamera.js +14 -2
  42. package/src/app/sceneContentsHooks.js +1 -1
  43. package/src/app/sceneFrame.js +2 -2
  44. package/src/app/scenePointer.d.ts +5 -1
  45. package/src/app/scenePointer.js +8 -3
  46. package/src/app/timeLook.d.ts +7 -0
  47. package/src/app/timeLook.js +8 -0
  48. package/src/core/clock.js +2 -1
  49. package/src/core/lookValues.d.ts +13 -0
  50. package/src/core/lookValues.js +39 -0
  51. package/src/core/state.d.ts +2 -0
  52. package/src/core/state.js +5 -1
  53. package/src/core/storyPanels.d.ts +8 -4
  54. package/src/core/storyPanels.js +17 -5
  55. package/src/shell/AstraeusShell.d.ts +5 -1
  56. package/src/shell/AstraeusShell.js +15 -8
  57. package/src/shell/AstraeusShell.node.js +15 -8
  58. package/src/shell/ObjectControls.js +1 -1
  59. package/src/shell/TimelineBar.d.ts +6 -2
  60. package/src/shell/TimelineBar.js +17 -12
  61. package/src/shell/TimelineBar.node.js +17 -12
  62. package/src/shell/experience.d.ts +2 -0
  63. package/src/shell/infoModel.d.ts +2 -1
  64. package/src/shell/infoModel.js +10 -10
  65. package/src/shell/storyPanels.d.ts +19 -1
  66. package/src/shell/storyPanels.js +34 -2
  67. package/src/shell/timelineModel.d.ts +11 -0
  68. package/src/shell/timelineModel.js +28 -0
  69. package/src/shell/useStoryPanels.d.ts +4 -0
  70. package/src/shell/useStoryPanels.js +27 -6
@@ -2,7 +2,7 @@ import type { TimelineEvent } from "../core/events.js";
2
2
  import type { TimeBounds } from "../core/trajectory.js";
3
3
  import type { ExperienceDefinition } from "../app/experienceDefinition.js";
4
4
  import { type TimeInput } from "./time.js";
5
- import type { SceneTimelineRead } from "./sceneReads.js";
5
+ import { type SceneTimelineRead } from "./sceneReads.js";
6
6
  import { type TimelineInput, type TimelineSetting } from "./story.js";
7
7
  /** What a `Scene` has planned for its timeline: the opening time, the timeline setting, and from them the span, clock, rates and pacing. */
8
8
  export declare class TimelinePlan {
@@ -1,8 +1,15 @@
1
1
  import { SceneError } from "./errors.js";
2
2
  import { toUtcMs } from "./time.js";
3
+ import { frozenList } from "./sceneReads.js";
3
4
  import { eventZonesOf } from "../core/pacing.js";
4
5
  import { pacingFor, timelineOf } from "./story.js";
5
6
  const DAY_MS = 86_400_000;
7
+ /** A checked pacing piece as the public read states it (seconds and UTC milliseconds). */
8
+ function pacingReadOf(piece) {
9
+ return "fromUtcMs" in piece
10
+ ? { spanStartUtcMs: piece.fromUtcMs, spanEndUtcMs: piece.toUtcMs, rate: piece.rate, rampSeconds: piece.rampMs / 1000 }
11
+ : { near: Object.freeze({ type: piece.type, withinSeconds: piece.withinMs / 1000 }), rate: piece.rate, rampSeconds: piece.rampMs / 1000 };
12
+ }
6
13
  /** What a `Scene` has planned for its timeline: the opening time, the timeline setting, and from them the span, clock, rates and pacing. */
7
14
  export class TimelinePlan {
8
15
  #timeUtcMs;
@@ -40,12 +47,14 @@ export class TimelinePlan {
40
47
  rates: Object.freeze([...this.rates()]),
41
48
  rate: this.clock(startUtcMs).rate,
42
49
  loop: this.setting?.none !== true && this.setting?.loop === true,
50
+ playing: this.clock(startUtcMs).playing !== false,
51
+ ...(this.setting?.pacing === undefined ? {} : { pacing: frozenList(this.setting.pacing.map(pacingReadOf)) }),
43
52
  });
44
53
  }
45
54
  /** The clock's opening: 60 times real time unless set; with no timeline and no rate, frozen. */
46
55
  clock(startUtcMs) {
47
56
  const timeline = this.setting;
48
- return { startUtcMs, rate: timeline?.rate ?? 60, ...(timeline?.none === true && timeline.rate === undefined ? { playing: false } : {}) };
57
+ return { startUtcMs, rate: timeline?.rate ?? 60, ...(timeline?.playing === false || (timeline?.none === true && timeline.rate === undefined) ? { playing: false } : {}) };
49
58
  }
50
59
  /** The pacing the timeline asked for, laid over the scene's events; a rule naming an event type with no events throws `bad-timeline`. */
51
60
  pacing(events) {
@@ -2,13 +2,15 @@ import type { DisplaySwitchSettings } from "../app/displaySwitches.js";
2
2
  import type { ViewSettings } from "../app/views.js";
3
3
  import type { StoryPanelSet } from "../core/storyPanels.js";
4
4
  import { type SwitchesInput } from "./switches.js";
5
- import type { SceneViewsRead } from "./sceneReads.js";
5
+ import type { SceneSwitchRead, SceneViewsRead } from "./sceneReads.js";
6
6
  import { type ViewInput, type ViewScope, type ViewsOptions } from "./views.js";
7
7
  /** What a `Scene` has planned for its presentation: the display switches and the named views. */
8
8
  export declare class ViewPlan {
9
9
  #private;
10
10
  setSwitches(switches: SwitchesInput): void;
11
11
  setViews(views: readonly ViewInput[], options: ViewsOptions): void;
12
+ /** The switches `setSwitches` placed, as the public read states them (`on` filled in); an unnamed switch is absent. */
13
+ switchReads(): Readonly<Record<string, SceneSwitchRead>>;
12
14
  /** The views as the public read states them, each with the objects, events and panels it shows (the lists the viewer uses, resolved against the finished scene); absent when none were named. `scope` is asked for only when views were named. */
13
15
  read(scope: () => ViewScope): SceneViewsRead | undefined;
14
16
  /** The `displaySwitches` entry of the definition (absent when none were placed). */
@@ -11,6 +11,10 @@ export class ViewPlan {
11
11
  setViews(views, options) {
12
12
  this.#views = viewsOf(views, options);
13
13
  }
14
+ /** The switches `setSwitches` placed, as the public read states them (`on` filled in); an unnamed switch is absent. */
15
+ switchReads() {
16
+ return Object.freeze(Object.fromEntries(Object.entries(this.#switches ?? {}).map(([id, { place, on, label }]) => [id, Object.freeze({ place, on: on ?? true, ...(label === undefined ? {} : { label }) })])));
17
+ }
14
18
  /** The views as the public read states them, each with the objects, events and panels it shows (the lists the viewer uses, resolved against the finished scene); absent when none were named. `scope` is asked for only when views were named. */
15
19
  read(scope) {
16
20
  const plan = this.#views;
@@ -17,14 +17,14 @@ import type { SkyFigureInput } from "./skyFigureInput.js";
17
17
  import type { MoonPanelInput, PlacesInput } from "./moonPanelInput.js";
18
18
  import type { BodySetInput } from "./bodySetInput.js";
19
19
  import { SceneCamera } from "./planCamera.js";
20
- import type { SceneActivityRead, SceneBodyRead, SceneBodySetRead, SceneEventRead, SceneGroupRead, SceneMoonPanelRead, ScenePanelRead, ScenePlacesRead, ScenePathRead, SceneSkyFigureRead, SceneTimelineRead, SceneViewsRead } from "./sceneReads.js";
21
- export type { SceneActivityRead, SceneBodyRead, SceneBodySetRead, SceneEventRead, SceneGroupRead, SceneMoonPanelRead, ScenePanelRead, ScenePlacesRead, ScenePathRead, SceneSkyFigureRead, SceneTimelineRead, SceneViewRead, SceneViewsRead } from "./sceneReads.js";
20
+ import type { SceneActivityRead, SceneBodyRead, SceneBodySetRead, SceneEventRead, SceneGroupRead, SceneMoonPanelRead, ScenePanelPlaybackRead, ScenePanelRead, ScenePlacesRead, ScenePathRead, SceneSkyFigureRead, SceneSwitchRead, SceneTimelineRead, SceneViewsRead } from "./sceneReads.js";
21
+ export type { SceneActivityRead, SceneBodyRead, SceneBodySetRead, SceneEventRead, SceneGroupRead, SceneMoonPanelRead, ScenePacingRead, ScenePanelPlaybackRead, ScenePanelRead, ScenePlacesRead, ScenePathRead, SceneSkyFigureRead, SceneSwitchRead, SceneTimelineRead, SceneViewRead, SceneViewsRead } from "./sceneReads.js";
22
22
  export type { SceneCamera } from "./planCamera.js";
23
23
  import { type TimeInput } from "./time.js";
24
24
  import type { ShownDuringInput } from "./shownDuring.js";
25
25
  export type { ShownDuringInput } from "./shownDuring.js";
26
26
  import type { SwitchesInput } from "./switches.js";
27
- import type { LookInput } from "./look.js";
27
+ import type { LookInput, LookRead } from "./look.js";
28
28
  import type { ViewInput, ViewsOptions } from "./views.js";
29
29
  import { type AddEventsOptions, type EventInput, type StoryPanelInput, type StoryPanelPlaybackInput, type TimelineInput } from "./story.js";
30
30
  export { toUtcMs, type TimeInput } from "./time.js";
@@ -214,6 +214,12 @@ export declare class Scene {
214
214
  get activities(): readonly SceneActivityRead[];
215
215
  /** 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. */
216
216
  get timeline(): SceneTimelineRead;
217
+ /** The looks `setLook` set, defaults filled in: what `ViewerHandle.look` reads on a fresh mount. */
218
+ get look(): LookRead;
219
+ /** The switches `setSwitches` placed, each `{ place, on, label? }`; an unnamed one is absent. Frozen. */
220
+ get switches(): Readonly<Record<string, SceneSwitchRead>>;
221
+ /** How story panels play (`setStoryPanelPlayback`), defaults filled in. Frozen. */
222
+ get panelPlayback(): ScenePanelPlaybackRead;
217
223
  /** Adds a catalogued body: a ready-made one (`earth`, `moon`, ...) or its id. The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line. */
218
224
  addBody(body: BodyRef | BodyId, options?: AddBodyOptions): this;
219
225
  /**
@@ -313,7 +319,7 @@ export declare class Scene {
313
319
  * Panel times may name events (`addEvents`) and path anchors, and `object` a body or path; these may be added later, so they are checked when the scene is built (`check`, `mount`), and a mistake throws `bad-panels` naming the panel and field.
314
320
  */
315
321
  addStoryPanels(panels: readonly StoryPanelInput[]): this;
316
- /** 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`. */
322
+ /** 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`. */
317
323
  setStoryPanelPlayback(playback: StoryPanelPlaybackInput): this;
318
324
  /** Sets the timeline: its span (`start`, `end`), the speeds offered (`rates`), the speed it opens at (`rate`), `pacing` (playback that slows for encounters and speeds up for cruise: spans `{ start, end, rate }` and event rules `{ near: { type, withinSeconds }, rate }`, easing between speeds; a speed the visitor or host picks wins until `setRate("auto")`; see `PacingInput`) and whether playback wraps from the end to the start (`loop`; ignored with `{ none: true }`, which has no span to wrap, and when `setTimeline` is not called), or `{ none: true }` for no timeline bar, with time frozen at `at` or running at `rate`. Without this call the span follows the paths and the speeds are 1 minute, 1 hour and 1 day per second. */
319
325
  setTimeline(timeline: TimelineInput): this;
@@ -321,7 +327,7 @@ export declare class Scene {
321
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
322
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
323
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.
324
- * A bad switch name, place or `on` throws `bad-switch`.
330
+ * A bad switch name, place, `on` or `label` throws `bad-switch`.
325
331
  * @example
326
332
  * scene.setSwitches({ orbitLines: { place: "top-bar" }, labels: { place: "panel", on: false }, milkyWay: { place: "developer", on: false } });
327
333
  */
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;
@@ -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;
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) {
@@ -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
@@ -36,6 +36,7 @@ import { displaySwitchItems, hostReachable, orbitStart, skyLineStart } from "./d
36
36
  import { TRACE_FADE_SECONDS } from "../core/skyTrace.js";
37
37
  import { aimAtFigure, DEFAULT_SKY_LINES, prefersReducedMotion, skyColoursOf, skyFadeInSecondsOf } from "./skyFigures.js";
38
38
  import { labelStyleOf } from "./labelStyle.js";
39
+ import { timeLookOf } from "./timeLook.js";
39
40
  import { experienceInView, hiddenByView, hiddenWithShownSpans, viewById } from "./viewHiding.js";
40
41
  import { cameraIdsOf } from "../core/storyPanels.js";
41
42
  import { baseGlowOf, glowLookOf, markerSettingsOf } from "./bodyDraw.js";
@@ -104,6 +105,10 @@ function startViewUp(definition, search) {
104
105
  function storyStartOf(storySet) {
105
106
  return { autoOpen: storySet?.autoOpen ?? false, pauseSeconds: storySet?.pauseSeconds ?? 0 };
106
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
+ }
107
112
  /** Everything one mounted experience shares: clock, resolver, catalogue and the settings read from its definition and the address. */
108
113
  function buildRuntime(definition, search) {
109
114
  const adapter = createOrbAstronomyAdapter();
@@ -177,6 +182,8 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
177
182
  skyTraces: [],
178
183
  skyFadeInSeconds: skyFadeInSecondsOf(runtime.look),
179
184
  labelStyle: labelStyleOf(runtime.look),
185
+ timeLook: timeLookOf(runtime.look),
186
+ sheetMaxPercent: runtime.look.sheetMaxPercent ?? DEFAULT_PHONE_LAYOUT.sheetMaxPercent,
180
187
  skyVisible: runtime.sky.visible,
181
188
  bodyMarker: markerSettingsOf(runtime.look),
182
189
  ...(glowBase === null ? {} : { glowLook: glowLookOf(runtime.look, glowBase) }),
@@ -262,11 +269,15 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
262
269
  const [scale, setScale] = useState(startScale);
263
270
  const [developerMode, setDeveloperMode] = useState(false);
264
271
  const [timelineGlow, setTimelineGlow] = useState(DEFAULT_TIMELINE_GLOW);
265
- 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 };
266
276
  const [anchorLabels, setAnchorLabels] = useState(controls.current.showAnchorLabels);
267
277
  const [skyLinesShown, setSkyLinesShown] = useState(controls.current.skyLines);
268
278
  const [skyColoursShown, setSkyColoursShown] = useState(controls.current.skyColours);
269
279
  const [labelStyleShown, setLabelStyleShown] = useState(controls.current.labelStyle);
280
+ const [timeLookShown, setTimeLookShown] = useState(controls.current.timeLook);
270
281
  const [glowShown, setGlowShown] = useState(copyOfGlow(controls.current.glowLook));
271
282
  const orbitPaths = orbitPathsOf(runtime);
272
283
  const orbitDefault = useMemo(() => resolveOrbitLook(orbitPaths[0]?.look), [orbitPaths]);
@@ -335,7 +346,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
335
346
  holdCamera();
336
347
  }, [experience, holdCamera]);
337
348
  const requestPanel = useCallback((id) => setPanelRequest((previous) => ({ id, serial: (previous?.serial ?? 0) + 1 })), []);
338
- 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 } : {}) })), []);
339
350
  const requestFeature = useCallback((key) => setFeatureRequest((previous) => ({ key, serial: (previous?.serial ?? 0) + 1 })), []);
340
351
  const markOpenFeature = useCallback((key) => { controls.current.openFeatureKey = key; }, []);
341
352
  const setPlaying = useCallback((playing) => {
@@ -590,6 +601,8 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
590
601
  setLoadFade(read.loadFadeSeconds);
591
602
  setSkyColoursShown(controls.current.skyColours);
592
603
  setLabelStyleShown(controls.current.labelStyle);
604
+ setTimeLookShown(controls.current.timeLook);
605
+ setSheetShown(read.sheetMaxPercent);
593
606
  },
594
607
  setScale: updateScale,
595
608
  items: () => displaySwitchItems({ ...bindingsNow(), settings: hostReachable(definition.displaySwitches) }),
@@ -604,7 +617,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
604
617
  shownKey.current = key;
605
618
  if (changed)
606
619
  host?.publish(state, "visitor");
607
- }, [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]);
608
621
  const hasStoryPanels = (storySet?.panels.length ?? 0) > 0;
609
622
  const showDisplay = showsDisplayControls(definition, runtime, skyVisible, orbitPaths.length, storyMarkerSpecs.length);
610
623
  // Orbit-line sliders: the first four stay in view, the rest sit in a nested "Fine-tune" fold (T-090).
@@ -666,7 +679,14 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
666
679
  ["timelineDrawerMaxPercent", "Timeline drawer height (% of screen)", "Phone timeline drawer height", "phone-timeline-height-value"],
667
680
  ["sheetMaxPercent", "Sheet height (% of screen)", "Phone sheet height", "phone-sheet-height-value"],
668
681
  ["swipeThresholdPx", "Swipe distance (px)", "Phone swipe distance", "phone-swipe-value"],
669
- ].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" }) })] })),
670
690
  },
671
691
  {
672
692
  id: "under-the-hood", title: "Under the hood",
@@ -675,7 +695,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
675
695
  ];
676
696
  const presentGroups = groups.filter((group) => group !== null);
677
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)))] }) }) }));
678
- 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: () => {
679
699
  if (runtime.clock.playing)
680
700
  runtime.clock.pause();
681
701
  else
@@ -688,5 +708,5 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
688
708
  }, onSeek: (timeUtcMs) => {
689
709
  seekTo(timeUtcMs);
690
710
  host?.publish(stateNow(), "visitor");
691
- }, 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: { 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 }) }) }));
692
712
  }
@@ -36,6 +36,7 @@ import { displaySwitchItems, hostReachable, orbitStart, skyLineStart } from "./d
36
36
  import { TRACE_FADE_SECONDS } from "../core/skyTrace.js";
37
37
  import { aimAtFigure, DEFAULT_SKY_LINES, prefersReducedMotion, skyColoursOf, skyFadeInSecondsOf } from "./skyFigures.js";
38
38
  import { labelStyleOf } from "./labelStyle.js";
39
+ import { timeLookOf } from "./timeLook.js";
39
40
  import { experienceInView, hiddenByView, hiddenWithShownSpans, viewById } from "./viewHiding.js";
40
41
  import { cameraIdsOf } from "../core/storyPanels.js";
41
42
  import { baseGlowOf, glowLookOf, markerSettingsOf } from "./bodyDraw.js";
@@ -104,6 +105,10 @@ function startViewUp(definition, search) {
104
105
  function storyStartOf(storySet) {
105
106
  return { autoOpen: storySet?.autoOpen ?? false, pauseSeconds: storySet?.pauseSeconds ?? 0 };
106
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
+ }
107
112
  /** Everything one mounted experience shares: clock, resolver, catalogue and the settings read from its definition and the address. */
108
113
  function buildRuntime(definition, search) {
109
114
  const adapter = createOrbAstronomyAdapter();
@@ -177,6 +182,8 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
177
182
  skyTraces: [],
178
183
  skyFadeInSeconds: skyFadeInSecondsOf(runtime.look),
179
184
  labelStyle: labelStyleOf(runtime.look),
185
+ timeLook: timeLookOf(runtime.look),
186
+ sheetMaxPercent: runtime.look.sheetMaxPercent ?? DEFAULT_PHONE_LAYOUT.sheetMaxPercent,
180
187
  skyVisible: runtime.sky.visible,
181
188
  bodyMarker: markerSettingsOf(runtime.look),
182
189
  ...(glowBase === null ? {} : { glowLook: glowLookOf(runtime.look, glowBase) }),
@@ -262,11 +269,15 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
262
269
  const [scale, setScale] = useState(startScale);
263
270
  const [developerMode, setDeveloperMode] = useState(false);
264
271
  const [timelineGlow, setTimelineGlow] = useState(DEFAULT_TIMELINE_GLOW);
265
- 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 };
266
276
  const [anchorLabels, setAnchorLabels] = useState(controls.current.showAnchorLabels);
267
277
  const [skyLinesShown, setSkyLinesShown] = useState(controls.current.skyLines);
268
278
  const [skyColoursShown, setSkyColoursShown] = useState(controls.current.skyColours);
269
279
  const [labelStyleShown, setLabelStyleShown] = useState(controls.current.labelStyle);
280
+ const [timeLookShown, setTimeLookShown] = useState(controls.current.timeLook);
270
281
  const [glowShown, setGlowShown] = useState(copyOfGlow(controls.current.glowLook));
271
282
  const orbitPaths = orbitPathsOf(runtime);
272
283
  const orbitDefault = useMemo(() => resolveOrbitLook(orbitPaths[0]?.look), [orbitPaths]);
@@ -335,7 +346,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
335
346
  holdCamera();
336
347
  }, [experience, holdCamera]);
337
348
  const requestPanel = useCallback((id) => setPanelRequest((previous) => ({ id, serial: (previous?.serial ?? 0) + 1 })), []);
338
- 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 } : {}) })), []);
339
350
  const requestFeature = useCallback((key) => setFeatureRequest((previous) => ({ key, serial: (previous?.serial ?? 0) + 1 })), []);
340
351
  const markOpenFeature = useCallback((key) => { controls.current.openFeatureKey = key; }, []);
341
352
  const setPlaying = useCallback((playing) => {
@@ -590,6 +601,8 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
590
601
  setLoadFade(read.loadFadeSeconds);
591
602
  setSkyColoursShown(controls.current.skyColours);
592
603
  setLabelStyleShown(controls.current.labelStyle);
604
+ setTimeLookShown(controls.current.timeLook);
605
+ setSheetShown(read.sheetMaxPercent);
593
606
  },
594
607
  setScale: updateScale,
595
608
  items: () => displaySwitchItems({ ...bindingsNow(), settings: hostReachable(definition.displaySwitches) }),
@@ -604,7 +617,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
604
617
  shownKey.current = key;
605
618
  if (changed)
606
619
  host?.publish(state, "visitor");
607
- }, [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]);
608
621
  const hasStoryPanels = (storySet?.panels.length ?? 0) > 0;
609
622
  const showDisplay = showsDisplayControls(definition, runtime, skyVisible, orbitPaths.length, storyMarkerSpecs.length);
610
623
  // Orbit-line sliders: the first four stay in view, the rest sit in a nested "Fine-tune" fold (T-090).
@@ -666,7 +679,14 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
666
679
  ["timelineDrawerMaxPercent", "Timeline drawer height (% of screen)", "Phone timeline drawer height", "phone-timeline-height-value"],
667
680
  ["sheetMaxPercent", "Sheet height (% of screen)", "Phone sheet height", "phone-sheet-height-value"],
668
681
  ["swipeThresholdPx", "Swipe distance (px)", "Phone swipe distance", "phone-swipe-value"],
669
- ].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" }) })] })),
670
690
  },
671
691
  {
672
692
  id: "under-the-hood", title: "Under the hood",
@@ -675,7 +695,7 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
675
695
  ];
676
696
  const presentGroups = groups.filter((group) => group !== null);
677
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)))] }) }) }));
678
- 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: () => {
679
699
  if (runtime.clock.playing)
680
700
  runtime.clock.pause();
681
701
  else
@@ -688,5 +708,5 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
688
708
  }, onSeek: (timeUtcMs) => {
689
709
  seekTo(timeUtcMs);
690
710
  host?.publish(stateNow(), "visitor");
691
- }, 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: { 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 }) }) }));
692
712
  }
@@ -19,6 +19,7 @@ import type { FrameStats } from "./frameStats.js";
19
19
  import type { GroupFill } from "./FrameRateSection.js";
20
20
  import { type BodySetLayer, type BodySetLook } from "./bodySet.js";
21
21
  import type { LabelStyle } from "./labelStyle.js";
22
+ import type { TimeLook } from "./timeLook.js";
22
23
  import type { SkyColours, SkyClearRequest, SkyFigureLayer, SkyLineSwitches, SkyTraceRequest } from "./skyFigures.js";
23
24
  import type { RingLook } from "../assets/rings.js";
24
25
  import type { Pictures } from "../assets/pictures.js";
@@ -96,6 +97,10 @@ export interface SceneControls {
96
97
  skyFadeInSeconds: number;
97
98
  /** Presentation only: the label font and size (the look `labels`; live). The viewer root carries it to every label as CSS variables. */
98
99
  labelStyle: LabelStyle;
100
+ /** Presentation only: the zone and precision of every visitor-facing time (the look `time`; live). */
101
+ timeLook: TimeLook;
102
+ /** Presentation only: the phone sheet's height cap, percent of the screen (the look `sheetMaxPercent`; live). The Developer drawer's slider and the look are this one value. */
103
+ sheetMaxPercent: number;
99
104
  /** Presentation only: when a sphere is too small to see it is drawn as a marker (see `drawsAsMarker`). */
100
105
  bodyMarker: BodyMarkerSettings;
101
106
  /** Presentation only: the live halo settings of a body whose record has a glow (the Sun). */
@@ -135,7 +140,9 @@ export interface SceneControls {
135
140
  /** The story panel now open, so its marker reads as pressed. */
136
141
  openStoryPanelId?: string | null;
137
142
  /** Called with an object's id when a tap or click lands on a body, a body-set member or a shown name. The shell flies to it like its picker does. */
138
- onPickObject?: (id: string) => void;
143
+ onPickObject?: (id: string, options?: {
144
+ readonly keepSky?: boolean;
145
+ }) => void;
139
146
  /** Tagged places on bodies (a body package's features); each gets a marker drawn on its body that opens the place's information. */
140
147
  readonly featureMarkers?: readonly FeatureMarkerSpec[];
141
148
  /** Called with the place's key when a feature marker is pressed. */
@@ -51,6 +51,8 @@ export interface OrbitCameraState {
51
51
  transition: [number, number, number];
52
52
  /** Set while the camera stands inside `focus` looking out: the field of view, with azimuth and elevation as the look direction. Null is the orbit camera. */
53
53
  lookOut: LookOutState | null;
54
+ /** A look-out field of view the camera is easing toward; null when none is pending (a visitor's zoom clears it). */
55
+ targetFovDeg: number | null;
54
56
  /** Scaled absolute camera/target positions (Float64, render axes) for the latest frame. */
55
57
  cameraAbsolute: [number, number, number];
56
58
  targetAbsolute: [number, number, number];