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/look.d.ts CHANGED
@@ -33,6 +33,13 @@ export interface LabelsLook {
33
33
  /** Text size in pixels, 8 to 24. Default 12. */
34
34
  readonly sizePx?: number;
35
35
  }
36
+ /** The zone and precision of the viewer's times. */
37
+ export interface TimeLook {
38
+ /** `"UTC"` (default, ISO text), `"local"` (the visitor's zone) or an IANA name such as `"Australia/Sydney"`; else `bad-look`. */
39
+ readonly zone?: string;
40
+ /** `"day"`, `"minute"` or `"second"` (default). */
41
+ readonly precision?: "day" | "minute" | "second";
42
+ }
36
43
  /** The looks a scene may set with `Scene.setLook`: presentation settings that change how the scene is drawn, never where anything is. Each is optional and keeps its default when absent. */
37
44
  export interface LookInput {
38
45
  /** Brightness of the catalogue stars, 0 to 2; 1 is the baseline star curve and 0 hides them in effect. Default 1. */
@@ -59,6 +66,10 @@ export interface LookInput {
59
66
  readonly skyLines?: SkyLinesLook;
60
67
  /** The font and size of every label. Default: the page's font at 12 pixels, as before. */
61
68
  readonly labels?: LabelsLook;
69
+ /** How times read in the clock bar, event list and cards. Default UTC to the second. */
70
+ readonly time?: TimeLook;
71
+ /** The tallest a phone's information or story sheet grows, as a percent of the screen height, 30 to 85. Default 50. Has no page address parameter; the Developer drawer's "Sheet height" slider is this same value. */
72
+ readonly sheetMaxPercent?: number;
62
73
  }
63
74
  /** The looks a running viewer shows, every one filled in (`ViewerHandle.look`): the scene's `setLook`, the page address and the Developer drawer laid over the defaults. `sunGlow` is absent in a scene without the Sun. */
64
75
  export interface LookRead {
@@ -93,4 +104,7 @@ export interface LookRead {
93
104
  readonly fontFamily: string;
94
105
  readonly sizePx: number;
95
106
  };
107
+ readonly time: Required<TimeLook>;
108
+ /** The phone sheet's height cap in force, a percent of the screen height (30 to 85). */
109
+ readonly sheetMaxPercent: number;
96
110
  }
@@ -1,3 +1,3 @@
1
1
  import type { LookInput } from "./look.js";
2
- /** Checks a `setLook` argument: an object of known looks, each a finite number in its range, a boolean, a CSS colour or a font-family text as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
2
+ /** Checks a `setLook` argument: an object of known looks, each a finite number in its range, a boolean, a CSS colour, a font-family text, a time zone or one of a few names as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
3
3
  export declare function checkedLook(input: LookInput): LookInput;
@@ -1,8 +1,8 @@
1
- import { isCssColour, isFontFamily } from "../core/lookValues.js";
1
+ import { isCssColour, isFontFamily, isTimeZone } from "../core/lookValues.js";
2
2
  import { LOOK_FIELDS, lookName, lookValue, lookWith } from "../app/look.js";
3
3
  import { SceneError } from "./errors.js";
4
4
  const TOP_LEVEL = [...new Set(LOOK_FIELDS.map(({ path }) => path[0]))];
5
- /** Checks a `setLook` argument: an object of known looks, each a finite number in its range, a boolean, a CSS colour or a font-family text as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
5
+ /** Checks a `setLook` argument: an object of known looks, each a finite number in its range, a boolean, a CSS colour, a font-family text, a time zone or one of a few names as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
6
6
  export function checkedLook(input) {
7
7
  const bad = (message) => new SceneError("bad-look", `setLook: ${message}`);
8
8
  const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -40,6 +40,10 @@ function valueProblem(field, value) {
40
40
  return typeof value === "number" && Number.isFinite(value) && value >= spec.min && value <= spec.max ? null : `must be a number from ${spec.min} to ${spec.max}`;
41
41
  if (spec.kind === "colour")
42
42
  return isCssColour(value) ? null : "must be a CSS colour such as \"#8fb4ff\" or \"rgb(143, 180, 255)\"";
43
+ if (spec.kind === "zone")
44
+ return isTimeZone(value) ? null : "must be \"UTC\", \"local\" or an IANA zone name such as \"Australia/Sydney\"";
45
+ if (spec.kind === "choice")
46
+ return typeof value === "string" && spec.values.includes(value) ? null : `must be one of ${spec.values.map((v) => JSON.stringify(v)).join(", ")}`;
43
47
  if (spec.kind === "font")
44
48
  return isFontFamily(value) ? null : "must be a non-empty CSS font-family text";
45
49
  return typeof value === "boolean" ? null : "must be true or false";
@@ -4,7 +4,7 @@ import { type BodyCatalogue } from "../assets/catalogue.js";
4
4
  import { type ElementsBodyRecord } from "../core/elementsBody.js";
5
5
  import type { CompositionPath } from "../assets/compositions.js";
6
6
  import type { ExperienceDefinition, PathLayer } from "../app/experienceDefinition.js";
7
- import type { ExperienceObject } from "../shell/experience.js";
7
+ import type { ExperienceObject, ShownSpan } from "../shell/experience.js";
8
8
  import type { EccentricSampling } from "../core/sunCentredSources.js";
9
9
  import { type BodyRef } from "./bodies.js";
10
10
  import type { DataSource } from "./data.js";
@@ -30,6 +30,7 @@ export declare class BodyPlan {
30
30
  readonly laps: Map<string, OrbitLapInput>;
31
31
  readonly cards: Map<string, Pick<AddBodyOptions, "facts" | "labelPriority" | "listed" | "sources">>;
32
32
  readonly looks: Map<string, Pick<AddBodyOptions, "color" | "knownLimitations">>;
33
+ readonly shown: Map<string, ShownSpan>;
33
34
  catalogue: BodyCatalogue;
34
35
  /** `taken` says whether the scene already holds an id; `firstBody` runs when the scene's first body arrives (it is a built-in one). */
35
36
  constructor(taken: (id: string) => boolean, firstBody: (id: BodyId) => void);
@@ -1,6 +1,7 @@
1
1
  import { readableScale, solarSystemScale, trueScale } from "../core/scalePolicy.js";
2
2
  import { catalogue as builtInCatalogue, extendCatalogue, extendCatalogueWithMoons, rootBodyId } from "../assets/catalogue.js";
3
3
  import { buildElementsBody, ElementsBodyError, parseElementsBodyRecord } from "../core/elementsBody.js";
4
+ import { planShownDuring } from "./shownDuring.js";
4
5
  import { catalogueItem } from "../app/catalogueItem.js";
5
6
  import { circlesTheSun, sunOrbitIdOf, sunOrbitLayer } from "./sunOrbit.js";
6
7
  import { listedMoonBodyOf } from "../core/bodies/listedMoonBodies.js";
@@ -99,6 +100,7 @@ export class BodyPlan {
99
100
  laps = new Map();
100
101
  cards = new Map();
101
102
  looks = new Map();
103
+ shown = new Map();
102
104
  catalogue = builtInCatalogue;
103
105
  #taken;
104
106
  #firstBody;
@@ -191,7 +193,10 @@ export class BodyPlan {
191
193
  if (this.#taken(id))
192
194
  throw new SceneError("duplicate-id", `${call}("${id}"): already in the scene`);
193
195
  checkBodyLook(id, options);
196
+ const shown = planShownDuring(call, id, "bad-body", options.shownDuring);
194
197
  this.#remember(call, id, options);
198
+ if (shown !== undefined)
199
+ this.shown.set(id, shown);
195
200
  this.bodies.set(id, ref);
196
201
  if (this.bodies.size === 1 && builtInCatalogue.has(id))
197
202
  this.#firstBody(id);
@@ -294,7 +299,7 @@ export class BodyPlan {
294
299
  const card = this.cards.get(body.id);
295
300
  const sources = card?.sources;
296
301
  const base = this.catalogue.get(body.id).definition.accuracy.position;
297
- const own = { labelPriority: card?.labelPriority ?? 100 - ids.indexOf(body.id), ...(card?.listed === undefined ? {} : { listed: card.listed }), ...(card?.facts === undefined ? {} : { facts: card.facts }), ...(sources === undefined ? {} : { provenance: withSources(base, sources) }), ...this.labelReach(body.id, sunCentred, camera), ...(this.shape.get(body.id)?.showLabel === undefined ? {} : { showLabel: this.shape.get(body.id).showLabel }), ...(this.notes.has(body.id) ? { description: this.notes.get(body.id) } : {}), ...this.looks.get(body.id) };
302
+ const own = { labelPriority: card?.labelPriority ?? 100 - ids.indexOf(body.id), ...(card?.listed === undefined ? {} : { listed: card.listed }), ...(card?.facts === undefined ? {} : { facts: card.facts }), ...(sources === undefined ? {} : { provenance: withSources(base, sources) }), ...this.labelReach(body.id, sunCentred, camera), ...(this.shape.get(body.id)?.showLabel === undefined ? {} : { showLabel: this.shape.get(body.id).showLabel }), ...(this.notes.has(body.id) ? { description: this.notes.get(body.id) } : {}), ...(this.shown.has(body.id) ? { shownDuring: this.shown.get(body.id) } : {}), ...this.looks.get(body.id) };
298
303
  return { ...catalogueItem(body.id, own, this.catalogue), label: body.label };
299
304
  }
300
305
  }
@@ -6,6 +6,10 @@ import type { BodyRef } from "./bodies.js";
6
6
  import type { FollowView } from "./scene.js";
7
7
  import type { CameraPose, SkyDirection } from "./viewerLink.js";
8
8
  import type { TimelineSetting } from "./story.js";
9
+ /** Every camera button choice the scene made: `focus` and `follow` list objects (undefined: every one), `lookOut` the bodies, `overview` whether Overview shows. */
10
+ export declare function cameraChoicesOf(camera: SceneCamera): CameraChoices & {
11
+ readonly overview: boolean;
12
+ };
9
13
  /** The scene's camera: what it opens on. */
10
14
  export declare class SceneCamera {
11
15
  #private;
@@ -43,6 +47,10 @@ export declare class SceneCamera {
43
47
  * scene.camera.setFollowChoices(["moon"]);
44
48
  */
45
49
  setFollowChoices(ids: readonly (BodyRef | BodyId)[]): this;
50
+ /** The objects offering Focus, as `setFollowChoices`. */
51
+ setFocusChoices(ids: readonly (BodyRef | BodyId)[]): this;
52
+ /** Whether Overview shows (default true). */
53
+ setOverview(on: boolean): this;
46
54
  /**
47
55
  * Chooses the bodies whose "Look out from" entry the camera menu offers, by body, id or path already added to the scene (else `unknown-body`); the entry stands inside the body and looks out, and any other camera entry leaves it.
48
56
  * Default: none. An empty list offers none. The opening view is separate: `lookOut` opens looking out whether or not the body is listed.
@@ -86,6 +94,8 @@ export declare class SceneCamera {
86
94
  get following(): boolean;
87
95
  get view(): FollowView;
88
96
  }
97
+ /** Refuses an opening `follow` or `focus` of an object the scene's `setFollowChoices` or `setFocusChoices` leaves out. Called when the scene is built. */
98
+ export declare function checkOpeningChoices(camera: SceneCamera): void;
89
99
  /**
90
100
  * Refuses an opening look-out toward an id `setCamera` would refuse on the opening view (`checkToward`, the same check and wording): the direction must name an object the opening view shows or a sky figure.
91
101
  * Called when the scene is built, after every figure is in.
@@ -104,8 +114,15 @@ export declare function startPresetEntry(camera: SceneCamera): {
104
114
  export declare function startViewEntry(camera: SceneCamera): Pick<ExperienceDefinition, "startView">;
105
115
  /** The playback and camera settings the scene asked for: looping, the farthest zoom-out and the ecliptic up. */
106
116
  export declare function viewEntries(timeline: TimelineSetting | undefined, camera: SceneCamera, farthestKm: (() => number) | undefined, cover: (() => number) | undefined): Pick<ExperienceDefinition, "loop" | "camera" | "viewUp">;
107
- /** The camera menu: Overview, Focus for every body and path, Follow for every one unless `setFollowChoices` named fewer, and "Look out from" for the bodies `setLookOutChoices` listed (the look is toward right ascension 0, declination 0 until the visitor turns). */
117
+ /** Which camera buttons the menu offers: `focus` and `follow` list the objects (undefined: every one), `lookOut` the bodies (none by default), `overview` whether Overview shows (default true). */
118
+ export interface CameraChoices {
119
+ readonly focus?: readonly string[];
120
+ readonly follow?: readonly string[];
121
+ readonly lookOut?: readonly string[];
122
+ readonly overview?: boolean;
123
+ }
124
+ /** The camera menu: Overview unless `setOverview(false)`, Focus and Follow for every body and path unless `setFocusChoices` or `setFollowChoices` named fewer, and "Look out from" for the bodies `setLookOutChoices` listed (the look is toward right ascension 0, declination 0 until the visitor turns). */
108
125
  export declare function cameraPresetsOf(objects: readonly {
109
126
  readonly id: string;
110
127
  readonly label: string;
111
- }[], followChoices?: readonly string[], lookOutChoices?: readonly string[]): ExperienceDefinition["experience"]["cameraPresets"];
128
+ }[], choices?: CameraChoices): ExperienceDefinition["experience"]["cameraPresets"];
@@ -7,6 +7,14 @@ import { farthestSunDistanceKm } from "./sunOrbit.js";
7
7
  import { planetSeriesLoaded } from "../core/planetSeries.js";
8
8
  /** Each camera's opening look-out toward an id, kept out of the public class: the request the viewer runs on its first frame, as it runs a `setCamera` one. */
9
9
  const towardIds = new WeakMap();
10
+ /** Each camera's Focus choices and Overview flag (`setFocusChoices`, `setOverview`), kept out of the public class: the assembler reads them with `cameraChoicesOf`. */
11
+ const choices = new WeakMap();
12
+ const offered = (camera) => { let own = choices.get(camera); if (own === undefined)
13
+ choices.set(camera, (own = { overview: true })); return own; };
14
+ /** Every camera button choice the scene made: `focus` and `follow` list objects (undefined: every one), `lookOut` the bodies, `overview` whether Overview shows. */
15
+ export function cameraChoicesOf(camera) {
16
+ return { focus: offered(camera).focus, follow: camera.followChoices, lookOut: camera.lookOutChoices, overview: offered(camera).overview };
17
+ }
10
18
  /** The scene's camera: what it opens on. */
11
19
  export class SceneCamera {
12
20
  #target;
@@ -129,6 +137,26 @@ export class SceneCamera {
129
137
  this.#followIds = Object.freeze([...new Set(named)]);
130
138
  return this;
131
139
  }
140
+ /** The objects offering Focus, as `setFollowChoices`. */
141
+ setFocusChoices(ids) {
142
+ this.#editable();
143
+ if (!Array.isArray(ids))
144
+ throw new SceneError("bad-camera", "camera.setFocusChoices: give a list of bodies or ids");
145
+ const named = ids.map((item) => (typeof item === "string" ? item : item?.id));
146
+ for (const id of named)
147
+ if (typeof id !== "string" || !this.#has(id))
148
+ throw new SceneError("unknown-body", `camera.setFocusChoices("${String(id)}"): no body or trajectory with that id has been added to the scene`);
149
+ offered(this).focus = Object.freeze([...new Set(named)]);
150
+ return this;
151
+ }
152
+ /** Whether Overview shows (default true). */
153
+ setOverview(on) {
154
+ this.#editable();
155
+ if (typeof on !== "boolean")
156
+ throw new SceneError("bad-camera", `camera.setOverview: give true or false, got ${JSON.stringify(on)}`);
157
+ offered(this).overview = on;
158
+ return this;
159
+ }
132
160
  /**
133
161
  * Chooses the bodies whose "Look out from" entry the camera menu offers, by body, id or path already added to the scene (else `unknown-body`); the entry stands inside the body and looks out, and any other camera entry leaves it.
134
162
  * Default: none. An empty list offers none. The opening view is separate: `lookOut` opens looking out whether or not the body is listed.
@@ -202,6 +230,16 @@ export class SceneCamera {
202
230
  get following() { return this.#following; }
203
231
  get view() { return this.#view; }
204
232
  }
233
+ /** Refuses an opening `follow` or `focus` of an object the scene's `setFollowChoices` or `setFocusChoices` leaves out. Called when the scene is built. */
234
+ export function checkOpeningChoices(camera) {
235
+ const { target, following } = camera;
236
+ if (target === undefined)
237
+ return;
238
+ const own = cameraChoicesOf(camera);
239
+ const [call, listed, setter] = following ? ["follow", own.follow, "setFollowChoices"] : ["focus", own.focus, "setFocusChoices"];
240
+ if (listed !== undefined && !listed.includes(target))
241
+ throw new SceneError("bad-camera", `camera.${call}("${target}"): the opening view ${call === "follow" ? "follows" : "focuses"} "${target}", which camera.${setter} does not list`);
242
+ }
205
243
  /**
206
244
  * Refuses an opening look-out toward an id `setCamera` would refuse on the opening view (`checkToward`, the same check and wording): the direction must name an object the opening view shows or a sky figure.
207
245
  * Called when the scene is built, after every figure is in.
@@ -254,14 +292,15 @@ export function viewEntries(timeline, camera, farthestKm, cover) {
254
292
  ...(view.up === undefined || target === undefined ? {} : { viewUp: view.up }),
255
293
  };
256
294
  }
257
- /** The camera menu: Overview, Focus for every body and path, Follow for every one unless `setFollowChoices` named fewer, and "Look out from" for the bodies `setLookOutChoices` listed (the look is toward right ascension 0, declination 0 until the visitor turns). */
258
- export function cameraPresetsOf(objects, followChoices, lookOutChoices = []) {
295
+ /** The camera menu: Overview unless `setOverview(false)`, Focus and Follow for every body and path unless `setFocusChoices` or `setFollowChoices` named fewer, and "Look out from" for the bodies `setLookOutChoices` listed (the look is toward right ascension 0, declination 0 until the visitor turns). */
296
+ export function cameraPresetsOf(objects, choices = {}) {
297
+ const { focus, follow, lookOut = [], overview = true } = choices;
259
298
  return [
260
- { id: "overview", label: "Overview", request: { kind: "overview" } },
299
+ ...(overview ? [{ id: "overview", label: "Overview", request: { kind: "overview" } }] : []),
261
300
  ...objects.flatMap(({ id, label }) => [
262
- { id: `focus-${id}`, label: `Focus ${label}`, request: { kind: "focus", target: id } },
263
- ...(followChoices === undefined || followChoices.includes(id) ? [{ id: `follow-${id}`, label: `Follow ${label}`, request: { kind: "follow", target: id } }] : []),
264
- ...(lookOutChoices.includes(id) ? [{ id: `lookout-${id}`, label: `Look out from ${label}`, request: { kind: "lookOut", body: id, direction: eqjUnitVector(0, 0) } }] : []),
301
+ ...(focus === undefined || focus.includes(id) ? [{ id: `focus-${id}`, label: `Focus ${label}`, request: { kind: "focus", target: id } }] : []),
302
+ ...(follow === undefined || follow.includes(id) ? [{ id: `follow-${id}`, label: `Follow ${label}`, request: { kind: "follow", target: id } }] : []),
303
+ ...(lookOut.includes(id) ? [{ id: `lookout-${id}`, label: `Look out from ${label}`, request: { kind: "lookOut", body: id, direction: eqjUnitVector(0, 0) } }] : []),
265
304
  ]),
266
305
  ];
267
306
  }
@@ -3,6 +3,7 @@ import type { WindowProvenanceSpan } from "../core/timeWindow.js";
3
3
  import { type BodyCatalogue } from "../assets/catalogue.js";
4
4
  import { type TrackedBody } from "../app/mission.js";
5
5
  import { SceneError } from "./errors.js";
6
+ import type { ShownSpan } from "../shell/experience.js";
6
7
  import type { ReadoutInput, TrajectoryInput } from "./scene.js";
7
8
  import { type ScenePathRead } from "./sceneReads.js";
8
9
  export interface Tracked {
@@ -13,6 +14,7 @@ export interface Tracked {
13
14
  readonly description?: string;
14
15
  readonly knownLimitations?: readonly string[];
15
16
  readonly provenanceSpans?: readonly WindowProvenanceSpan[];
17
+ readonly shownDuring?: ShownSpan;
16
18
  readonly readouts: readonly ReadoutInput[];
17
19
  }
18
20
  /** The paths in the order added, as the public list states them. */
@@ -7,14 +7,15 @@ import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
7
7
  import { planetSeriesLoaded } from "../core/planetSeries.js";
8
8
  import { catalogue as builtInCatalogue } from "../assets/catalogue.js";
9
9
  import { lineBodies } from "../app/mission.js";
10
+ import { providerPathTimes } from "./providerPathTimes.js";
10
11
  import { planLineStretches, planPathProvenance } from "./pathProvenance.js";
11
12
  import { influenceStretches, sphereOfInfluenceKm } from "./sphereOfInfluence.js";
12
13
  import { SceneError } from "./errors.js";
13
14
  import { rejectRenamed } from "./renamedInputs.js";
14
15
  import { toUtcMs } from "./time.js";
16
+ import { planShownDuring } from "./shownDuring.js";
15
17
  import { frozenList } from "./sceneReads.js";
16
18
  const DEFAULT_COLOR = "#ffd27a";
17
- const PROVIDER_PATH_SAMPLES = 128;
18
19
  /** Samples along a path when its farthest distance is read for the default zoom-out. */
19
20
  const PATH_COVER_SAMPLES = 400;
20
21
  /** The paths in the order added, as the public list states them. */
@@ -37,13 +38,14 @@ export function buildTracked(input, center, labelReaches) {
37
38
  if (input.plane !== undefined && input.plane !== "EQJ" && input.plane !== "ecliptic-j2000")
38
39
  throw new SceneError("bad-trajectory", `addTrajectory("${id}"): plane "${String(input.plane)}" must be "EQJ" or "ecliptic-j2000"`);
39
40
  const toEqj = input.plane === "ecliptic-j2000" ? createOrbTwoBodyAdapter().eclipticJ2000ToEqjMatrix() : null;
40
- const body = "samples" in input ? sampledBody(common, input, center, toEqj) : providerBody(common, input, toEqj);
41
+ const body = "samples" in input ? sampledBody(common, input, center, toEqj) : providerBody(common, input, center, toEqj);
41
42
  const span = { startUtcMs: body.trajectory.bounds.startUtcMs, endUtcMs: body.trajectory.bounds.endUtcMs };
42
43
  const provenanceSpans = input.provenanceSpans === undefined ? undefined : planPathProvenance(id, input.provenanceSpans, span);
44
+ const shownDuring = planShownDuring("addTrajectory", id, "bad-trajectory", input.shownDuring);
43
45
  checkLineFixedToType(id, input.lineFixedTo);
44
46
  const auto = input.lineFixedTo === "auto";
45
47
  const lineFixedTo = typeof input.lineFixedTo === "object" ? planLineStretches(id, input.lineFixedTo, span) : auto ? undefined : input.lineFixedTo;
46
- return { center, ...(auto ? { auto: true } : {}), body: withAnchors(lineFixedTo === undefined ? body : { ...body, lineFixedTo }, input.anchors), readouts, ...(provenanceSpans === undefined ? {} : { provenanceSpans }), ...(input.description === undefined ? {} : { description: input.description }), ...(input.knownLimitations === undefined ? {} : { knownLimitations: input.knownLimitations }) };
48
+ return { center, ...(auto ? { auto: true } : {}), body: withAnchors(lineFixedTo === undefined ? body : { ...body, lineFixedTo }, input.anchors), readouts, ...(provenanceSpans === undefined ? {} : { provenanceSpans }), ...(shownDuring === undefined ? {} : { shownDuring }), ...(input.description === undefined ? {} : { description: input.description }), ...(input.knownLimitations === undefined ? {} : { knownLimitations: input.knownLimitations }) };
47
49
  }
48
50
  /** Rotates a vector by a row-major 3x3 matrix; a missing matrix leaves it as it is. Input that is not three numbers passes through for the State checks to refuse. */
49
51
  function rotated(matrix, v) {
@@ -71,16 +73,19 @@ function checkLineFixedToType(id, value) {
71
73
  if (value !== undefined && typeof value !== "string" && typeof value !== "object")
72
74
  throw new SceneError("bad-trajectory", `addTrajectory("${id}"): lineFixedTo ${String(value)} must be a body id, "auto" or a list of stretches`);
73
75
  }
74
- function providerBody(common, input, toEqj) {
76
+ function providerBody(common, input, center, toEqj) {
75
77
  if (typeof input.provider?.stateAt !== "function")
76
78
  throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): provider needs a stateAt(time) function`);
77
79
  const bounds = { startUtcMs: toUtcMs(input.bounds?.start, `addTrajectory("${common.id}") bounds.start`), endUtcMs: toUtcMs(input.bounds?.end, `addTrajectory("${common.id}") bounds.end`) };
78
80
  if (bounds.endUtcMs <= bounds.startUtcMs)
79
81
  throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): bounds must end after they start`);
80
- const trajectory = { body: common.id, bounds, stateAt: (timeUtcMs, center) => rotatedState(toEqj, input.provider.stateAt(timeUtcMs, center)) };
81
- // Whole milliseconds, because the state resolver refuses a fractional time (the line is placed against another body at these times).
82
- const step = (bounds.endUtcMs - bounds.startUtcMs) / (PROVIDER_PATH_SAMPLES - 1);
83
- return { ...common, trajectory, pathTimesUtcMs: Array.from({ length: PROVIDER_PATH_SAMPLES }, (_, index) => Math.round(bounds.startUtcMs + index * step)) };
82
+ const trajectory = { body: common.id, bounds, stateAt: (timeUtcMs, center) => {
83
+ // Every call reaches the host here (`stateOf`, line planning, reach, sampling): a provider only ever sees whole milliseconds (I-177).
84
+ toUtcMs(timeUtcMs, `addTrajectory("${common.id}") provider time`);
85
+ return rotatedState(toEqj, input.provider.stateAt(timeUtcMs, center));
86
+ } };
87
+ // Whole milliseconds, because the state resolver refuses a fractional time (the line is placed against another body at these times). The 128 even moments gain more where the path bends or the body moves fast, as seen from `center`.
88
+ return { ...common, trajectory, pathTimesUtcMs: providerPathTimes(bounds.startUtcMs, bounds.endUtcMs, (t) => trajectory.stateAt(t, center).positionKm) };
84
89
  }
85
90
  /** A provider's State with its position and velocity rotated into EQJ; unchanged for EQJ input. */
86
91
  function rotatedState(matrix, state) {
@@ -4,7 +4,7 @@ import { type StoryPanelSet } from "../core/storyPanels.js";
4
4
  import type { ExperienceConfig } from "../shell/experience.js";
5
5
  import { type AddEventsOptions, type EventInput, type StoryPanelInput, type StoryPanelPlaybackInput } from "./story.js";
6
6
  import type { Tracked } from "./planPaths.js";
7
- import { type SceneEventRead, type ScenePanelRead } from "./sceneReads.js";
7
+ import { type SceneEventRead, type ScenePanelPlaybackRead, type ScenePanelRead } from "./sceneReads.js";
8
8
  /** What a `Scene` has planned for its story layer: events, where their times come from, and story panels. */
9
9
  export declare class StoryPlan {
10
10
  #private;
@@ -13,6 +13,8 @@ export declare class StoryPlan {
13
13
  /** Appends a batch; one that fails its checks adds nothing. */
14
14
  addPanels(panels: readonly StoryPanelInput[]): void;
15
15
  setPanelPlayback(playback: StoryPanelPlaybackInput): void;
16
+ /** How panels play, as the public read states it. */
17
+ playbackRead(): ScenePanelPlaybackRead;
16
18
  /** The events name only objects the scene holds. */
17
19
  checkObjects(ids: ReadonlySet<string>): void;
18
20
  /** The story panels, resolved against this scene's events, the anchors of its paths, its objects and timeline span. */
@@ -26,6 +26,11 @@ export class StoryPlan {
26
26
  setPanelPlayback(playback) {
27
27
  this.#playback = panelPlaybackOf(playback);
28
28
  }
29
+ /** How panels play, as the public read states it. */
30
+ playbackRead() {
31
+ const { pauseSeconds, autoOpen, closeAfterSeconds } = this.#playback;
32
+ return Object.freeze({ pauseSeconds, autoOpen, ...(closeAfterSeconds === undefined ? {} : { closeAfterSeconds }) });
33
+ }
29
34
  /** The events name only objects the scene holds. */
30
35
  checkObjects(ids) {
31
36
  checkEventObjects(this.events, ids);
@@ -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;
@@ -0,0 +1,10 @@
1
+ /** The moments a provider path's line is drawn at: 128 even ones plus extra ones where the line bends or the body moves fast, as seen from the path's centre (O-070). */
2
+ /** Even moments every path starts from. */
3
+ export declare const PROVIDER_SEED_SAMPLES = 128;
4
+ /** Most moments a provider path is drawn at. */
5
+ export declare const PROVIDER_MAX_SAMPLES = 4096;
6
+ /**
7
+ * Strictly increasing whole-millisecond moments from `startUtcMs` to `endUtcMs`: the 128 even ones (the first and last are the bounds), then midpoints of the intervals that bend
8
+ * or speed up most, until none is over the limits or there are 4,096. `positionAt` gives the body's position about the path's centre; if it throws or gives no position, the even moments stand alone.
9
+ */
10
+ export declare function providerPathTimes(startUtcMs: number, endUtcMs: number, positionAt: (timeUtcMs: number) => ArrayLike<number>): number[];
@@ -0,0 +1,109 @@
1
+ /** The moments a provider path's line is drawn at: 128 even ones plus extra ones where the line bends or the body moves fast, as seen from the path's centre (O-070). */
2
+ /** Even moments every path starts from. */
3
+ export const PROVIDER_SEED_SAMPLES = 128;
4
+ /** Most moments a provider path is drawn at. */
5
+ export const PROVIDER_MAX_SAMPLES = 4096;
6
+ /** An interval is split while the body sweeps more than this angle about the centre between its ends. */
7
+ const MAX_SWEEP_RAD = (3 * Math.PI) / 180;
8
+ /** An interval is split while its true midpoint lies farther than this fraction of its distance from the centre from the chord's midpoint (the body speeding up or slowing down shows here too). */
9
+ const MAX_CHORD_ERROR = 0.0025;
10
+ /** The position as three finite numbers, or null when the provider gave something else. */
11
+ const read = (positionAt, timeUtcMs) => {
12
+ const p = positionAt(timeUtcMs);
13
+ return p?.length === 3 && Number.isFinite(p[0]) && Number.isFinite(p[1]) && Number.isFinite(p[2]) ? [p[0], p[1], p[2]] : null;
14
+ };
15
+ /** The interval's score. */
16
+ function scored(a, b, pa, pb, positionAt) {
17
+ const mid = Math.floor((a + b) / 2);
18
+ const pm = read(positionAt, mid);
19
+ if (pm === null)
20
+ return { a, b, pa, pb, mid, pm: pa, score: 0 };
21
+ const w = (mid - a) / (b - a);
22
+ const na = Math.hypot(...pa);
23
+ const nb = Math.hypot(...pb);
24
+ const dot = pa[0] * pb[0] + pa[1] * pb[1] + pa[2] * pb[2];
25
+ const sweep = Math.acos(Math.max(-1, Math.min(1, dot / (na * nb))));
26
+ const chord = Math.hypot(pm[0] - (pa[0] + w * (pb[0] - pa[0])), pm[1] - (pa[1] + w * (pb[1] - pa[1])), pm[2] - (pa[2] + w * (pb[2] - pa[2])));
27
+ const reach = Math.max(Math.hypot(...pm), Math.min(na, nb));
28
+ const score = Math.max(sweep / MAX_SWEEP_RAD, chord / (MAX_CHORD_ERROR * reach));
29
+ return { a, b, pa, pb, mid, pm, score: Number.isFinite(score) ? score : 0 };
30
+ }
31
+ /** Max-heap on score; ties go to the earlier interval, so the result is the same every time. */
32
+ class Worst {
33
+ #items = [];
34
+ get size() {
35
+ return this.#items.length;
36
+ }
37
+ #before(i, j) {
38
+ const x = this.#items[i];
39
+ const y = this.#items[j];
40
+ return x.score > y.score || (x.score === y.score && x.a < y.a);
41
+ }
42
+ #swap(i, j) {
43
+ [this.#items[i], this.#items[j]] = [this.#items[j], this.#items[i]];
44
+ }
45
+ push(item) {
46
+ this.#items.push(item);
47
+ for (let i = this.#items.length - 1; i > 0;) {
48
+ const parent = (i - 1) >> 1;
49
+ if (!this.#before(i, parent))
50
+ break;
51
+ this.#swap(i, parent);
52
+ i = parent;
53
+ }
54
+ }
55
+ pop() {
56
+ const top = this.#items[0];
57
+ const last = this.#items.pop();
58
+ if (this.#items.length > 0) {
59
+ this.#items[0] = last;
60
+ for (let i = 0;;) {
61
+ let best = i;
62
+ for (const child of [2 * i + 1, 2 * i + 2])
63
+ if (child < this.#items.length && this.#before(child, best))
64
+ best = child;
65
+ if (best === i)
66
+ break;
67
+ this.#swap(i, best);
68
+ i = best;
69
+ }
70
+ }
71
+ return top;
72
+ }
73
+ }
74
+ /**
75
+ * Strictly increasing whole-millisecond moments from `startUtcMs` to `endUtcMs`: the 128 even ones (the first and last are the bounds), then midpoints of the intervals that bend
76
+ * or speed up most, until none is over the limits or there are 4,096. `positionAt` gives the body's position about the path's centre; if it throws or gives no position, the even moments stand alone.
77
+ */
78
+ export function providerPathTimes(startUtcMs, endUtcMs, positionAt) {
79
+ const step = (endUtcMs - startUtcMs) / (PROVIDER_SEED_SAMPLES - 1);
80
+ const seeds = [...new Set(Array.from({ length: PROVIDER_SEED_SAMPLES }, (_, index) => Math.round(startUtcMs + index * step)))];
81
+ try {
82
+ return refined(seeds, positionAt);
83
+ }
84
+ catch {
85
+ return seeds; // a provider that cannot answer yet (its data is not loaded) keeps the even moments
86
+ }
87
+ }
88
+ function refined(seeds, positionAt) {
89
+ const found = seeds.map((t) => read(positionAt, t));
90
+ const positions = found.filter((p) => p !== null);
91
+ if (positions.length < seeds.length)
92
+ return [...seeds]; // a position the provider does not give: the fault is named when the line is drawn
93
+ const heap = new Worst();
94
+ for (let i = 1; i < seeds.length; i += 1)
95
+ if (seeds[i] - seeds[i - 1] >= 2)
96
+ heap.push(scored(seeds[i - 1], seeds[i], positions[i - 1], positions[i], positionAt));
97
+ const times = new Set(seeds);
98
+ while (heap.size > 0 && times.size < PROVIDER_MAX_SAMPLES) {
99
+ const worst = heap.pop();
100
+ if (worst.score <= 1)
101
+ break;
102
+ times.add(worst.mid);
103
+ for (const [a, b, pa, pb] of [[worst.a, worst.mid, worst.pa, worst.pm], [worst.mid, worst.b, worst.pm, worst.pb]]) {
104
+ if (b - a >= 2)
105
+ heap.push(scored(a, b, pa, pb, positionAt));
106
+ }
107
+ }
108
+ return [...times].sort((x, y) => x - y);
109
+ }
@@ -17,12 +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
+ import type { ShownDuringInput } from "./shownDuring.js";
25
+ export type { ShownDuringInput } from "./shownDuring.js";
24
26
  import type { SwitchesInput } from "./switches.js";
25
- import type { LookInput } from "./look.js";
27
+ import type { LookInput, LookRead } from "./look.js";
26
28
  import type { ViewInput, ViewsOptions } from "./views.js";
27
29
  import { type AddEventsOptions, type EventInput, type StoryPanelInput, type StoryPanelPlaybackInput, type TimelineInput } from "./story.js";
28
30
  export { toUtcMs, type TimeInput } from "./time.js";
@@ -41,6 +43,8 @@ export interface AddBodyOptions {
41
43
  readonly showLabel?: boolean;
42
44
  /** How far from the camera the body's label shows, in the camera's `distance` units (Earth radii, as `camera.setReach`); a positive finite number. When absent the scene's shared rule applies: no limit in a Sun-centred or fitted scene, else the camera reach (at least 500). */
43
45
  readonly labelReachEarthRadii?: number;
46
+ /** Shows the body only within a span (`ShownDuringInput`). */
47
+ readonly shownDuring?: ShownDuringInput;
44
48
  /** One or two plain sentences for the body's info card. */
45
49
  readonly description?: string;
46
50
  /** The body's colour on its info card and label, as a CSS hex colour such as "#9fd8ff"; the catalogue's own when absent. A bad value throws `bad-body`. */
@@ -132,6 +136,8 @@ export interface TrajectoryBase {
132
136
  * Sorted, not overlapping, inside the path's span; a fault throws `bad-trajectory` naming the index. Where no span covers the time, `provenance` (or the illustrative default) shows.
133
137
  */
134
138
  readonly provenanceSpans?: readonly ActivitySourceInput[];
139
+ /** Shows the path only within a span (`ShownDuringInput`). */
140
+ readonly shownDuring?: ShownDuringInput;
135
141
  /** One or two plain sentences for the path's info card. */
136
142
  readonly description?: string;
137
143
  /** Published limits of the data, shown with the provenance. */
@@ -208,6 +214,12 @@ export declare class Scene {
208
214
  get activities(): readonly SceneActivityRead[];
209
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. */
210
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;
211
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. */
212
224
  addBody(body: BodyRef | BodyId, options?: AddBodyOptions): this;
213
225
  /**
@@ -307,7 +319,7 @@ export declare class Scene {
307
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.
308
320
  */
309
321
  addStoryPanels(panels: readonly StoryPanelInput[]): this;
310
- /** 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`. */
311
323
  setStoryPanelPlayback(playback: StoryPanelPlaybackInput): this;
312
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. */
313
325
  setTimeline(timeline: TimelineInput): this;
@@ -315,7 +327,7 @@ export declare class Scene {
315
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
316
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
317
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.
318
- * A bad switch name, place or `on` throws `bad-switch`.
330
+ * A bad switch name, place, `on` or `label` throws `bad-switch`.
319
331
  * @example
320
332
  * scene.setSwitches({ orbitLines: { place: "top-bar" }, labels: { place: "panel", on: false }, milkyWay: { place: "developer", on: false } });
321
333
  */