astraeus 0.8.1 → 0.9.0

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 (121) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +28 -15
  3. package/package.json +1 -1
  4. package/src/api/AstraeusScene.d.ts +1 -1
  5. package/src/api/AstraeusScene.js +4 -1
  6. package/src/api/AstraeusScene.node.js +4 -1
  7. package/src/api/assembleScene.d.ts +2 -0
  8. package/src/api/assembleScene.js +27 -5
  9. package/src/api/cameraRequest.d.ts +15 -0
  10. package/src/api/cameraRequest.js +89 -0
  11. package/src/api/errors.d.ts +9 -1
  12. package/src/api/index.d.ts +6 -3
  13. package/src/api/look.d.ts +49 -0
  14. package/src/api/lookInput.d.ts +1 -1
  15. package/src/api/lookInput.js +6 -1
  16. package/src/api/planCamera.d.ts +35 -7
  17. package/src/api/planCamera.js +94 -11
  18. package/src/api/planSkyFigures.d.ts +22 -0
  19. package/src/api/planSkyFigures.js +145 -0
  20. package/src/api/planStory.d.ts +2 -2
  21. package/src/api/planStory.js +14 -9
  22. package/src/api/planViews.js +1 -1
  23. package/src/api/scene.d.ts +17 -4
  24. package/src/api/scene.js +23 -5
  25. package/src/api/sceneReads.d.ts +21 -2
  26. package/src/api/skyFigureInput.d.ts +45 -0
  27. package/src/api/skyFigureInput.js +1 -0
  28. package/src/api/skyTraceInput.d.ts +33 -0
  29. package/src/api/skyTraceInput.js +45 -0
  30. package/src/api/story.d.ts +12 -3
  31. package/src/api/story.js +44 -1
  32. package/src/api/viewerCamera.d.ts +4 -3
  33. package/src/api/viewerCamera.js +10 -32
  34. package/src/api/viewerHandle.d.ts +27 -4
  35. package/src/api/viewerHandle.js +6 -0
  36. package/src/api/viewerLink.d.ts +49 -4
  37. package/src/api/viewerLink.js +25 -0
  38. package/src/api/viewerPanels.d.ts +26 -0
  39. package/src/api/viewerPanels.js +42 -0
  40. package/src/api/viewerSelection.d.ts +1 -1
  41. package/src/api/viewerSelection.js +3 -3
  42. package/src/app/App.js +100 -18
  43. package/src/app/App.node.js +100 -18
  44. package/src/app/AstraeusScene.d.ts +20 -5
  45. package/src/app/AstraeusScene.js +3 -3
  46. package/src/app/CameraController.d.ts +17 -0
  47. package/src/app/CameraController.js +34 -9
  48. package/src/app/DeveloperSettings.d.ts +11 -3
  49. package/src/app/DeveloperSettings.js +13 -3
  50. package/src/app/SceneLabels.d.ts +20 -2
  51. package/src/app/SceneLabels.js +46 -6
  52. package/src/app/SkyFiguresView.d.ts +56 -0
  53. package/src/app/SkyFiguresView.js +242 -0
  54. package/src/app/StoryMarkers.d.ts +2 -2
  55. package/src/app/StoryMarkers.js +2 -2
  56. package/src/app/displaySwitches.d.ts +13 -3
  57. package/src/app/displaySwitches.js +17 -3
  58. package/src/app/experienceDefinition.d.ts +9 -3
  59. package/src/app/experienceDefinition.js +4 -2
  60. package/src/app/labelStyle.d.ts +17 -0
  61. package/src/app/labelStyle.js +13 -0
  62. package/src/app/liveLook.js +8 -0
  63. package/src/app/look.d.ts +9 -5
  64. package/src/app/look.js +11 -0
  65. package/src/app/lookOut.d.ts +32 -0
  66. package/src/app/lookOut.js +50 -0
  67. package/src/app/sceneCamera.d.ts +5 -3
  68. package/src/app/sceneCamera.js +66 -3
  69. package/src/app/sceneContentsHooks.d.ts +2 -1
  70. package/src/app/sceneContentsHooks.js +3 -2
  71. package/src/app/sceneFrame.d.ts +10 -1
  72. package/src/app/sceneFrame.js +45 -10
  73. package/src/app/sceneFraming.d.ts +7 -0
  74. package/src/app/sceneFraming.js +12 -0
  75. package/src/app/sceneHooks.d.ts +2 -0
  76. package/src/app/sceneHooks.js +4 -1
  77. package/src/app/scenePicking.d.ts +20 -0
  78. package/src/app/scenePicking.js +49 -0
  79. package/src/app/scenePointer.d.ts +3 -1
  80. package/src/app/scenePointer.js +3 -2
  81. package/src/app/skyFigures.d.ts +73 -0
  82. package/src/app/skyFigures.js +50 -0
  83. package/src/app/style.css +2 -1
  84. package/src/app/viewHiding.d.ts +2 -0
  85. package/src/app/viewHiding.js +7 -1
  86. package/src/app/viewLink.d.ts +8 -8
  87. package/src/app/viewLink.js +24 -4
  88. package/src/app/viewerPort.d.ts +30 -3
  89. package/src/assets/sky.d.ts +13 -4
  90. package/src/assets/sky.js +33 -8
  91. package/src/assets/stars/hyg-v42-naked-eye.json +1 -1
  92. package/src/core/bodies/moonSystem.js +1 -15
  93. package/src/core/lookValues.d.ts +9 -0
  94. package/src/core/lookValues.js +24 -0
  95. package/src/core/readBytes.d.ts +1 -0
  96. package/src/core/readBytes.js +15 -0
  97. package/src/core/skyTrace.d.ts +49 -0
  98. package/src/core/skyTrace.js +39 -0
  99. package/src/core/startView.d.ts +39 -0
  100. package/src/core/startView.js +56 -0
  101. package/src/core/storyPanels.d.ts +51 -3
  102. package/src/core/storyPanels.js +52 -12
  103. package/src/shell/AstraeusShell.d.ts +15 -6
  104. package/src/shell/AstraeusShell.js +76 -20
  105. package/src/shell/AstraeusShell.node.js +76 -20
  106. package/src/shell/ObjectControls.js +11 -8
  107. package/src/shell/StoryPanelView.d.ts +12 -3
  108. package/src/shell/StoryPanelView.js +2 -2
  109. package/src/shell/experience.d.ts +24 -0
  110. package/src/shell/experience.js +4 -1
  111. package/src/shell/infoModel.js +9 -1
  112. package/src/shell/objectModel.d.ts +6 -2
  113. package/src/shell/objectModel.js +10 -1
  114. package/src/shell/phone.css +1 -1
  115. package/src/shell/storyPanels.d.ts +1 -1
  116. package/src/shell/storyPanels.js +1 -1
  117. package/src/shell/style.css +9 -1
  118. package/src/shell/topBarIcons.d.ts +1 -0
  119. package/src/shell/topBarIcons.js +1 -0
  120. package/src/shell/useStoryPanels.d.ts +9 -6
  121. package/src/shell/useStoryPanels.js +10 -6
@@ -31,14 +31,14 @@ export class StoryPlan {
31
31
  checkEventObjects(this.events, ids);
32
32
  }
33
33
  /** The story panels, resolved against this scene's events, the anchors of its paths, its objects and timeline span. */
34
- panels(window, tracked, objectIds) {
34
+ panels(window, tracked, objectIds, figureIds) {
35
35
  if (this.#panels === undefined)
36
36
  return undefined;
37
37
  const anchors = new Map();
38
38
  for (const { body } of tracked)
39
39
  body.anchorLabels?.forEach((label, index) => { if (!anchors.has(label))
40
40
  anchors.set(label, body.anchorTimesUtcMs[index]); });
41
- return panelsOf(this.#panels, this.#playback, { events: this.events, anchors, objectIds, window });
41
+ return panelsOf(this.#panels, this.#playback, { events: this.events, anchors, objectIds, figureIds, window });
42
42
  }
43
43
  /** The events sorted by time, each with its own provenance, else the batch's. */
44
44
  eventReads() {
@@ -48,13 +48,18 @@ export class StoryPlan {
48
48
  }));
49
49
  }
50
50
  /** The story panels as the public list states them (resolved as `panels` resolves them); empty when none were added. */
51
- panelReads(window, tracked, objectIds) {
52
- const set = this.panels(window, tracked, objectIds);
53
- return frozenList((set?.panels ?? []).map(({ id, timeUtcMs, title, body, details, provenance, objectId }) => ({
54
- id, timeUtcMs, title, provenance,
55
- body: Object.freeze([...body]), details: Object.freeze([...details]),
56
- ...(objectId === undefined ? {} : { object: objectId }),
57
- })));
51
+ panelReads(window, tracked, objectIds, figureIds) {
52
+ const set = this.panels(window, tracked, objectIds, figureIds);
53
+ const listed = [...(set?.panels ?? []), ...(set?.steps ?? [])];
54
+ return frozenList(listed.map((panel) => {
55
+ const { id, title, body, details, provenance, objectId } = panel;
56
+ return {
57
+ id, title, provenance,
58
+ ..."timeUtcMs" in panel ? { timeUtcMs: panel.timeUtcMs } : {},
59
+ body: Object.freeze([...body]), details: Object.freeze([...details]),
60
+ ...(objectId === undefined ? {} : { object: objectId }),
61
+ };
62
+ }));
58
63
  }
59
64
  /** The event provenance entries of the experience: the batch's, and each event's own. */
60
65
  provenanceEntries() {
@@ -30,6 +30,6 @@ export class ViewPlan {
30
30
  viewsEntry(scene, storyPanels) {
31
31
  if (this.#views === undefined)
32
32
  return {};
33
- return { views: resolveViews(this.#views, { objects: scene.objects, events: scene.events, panels: storyPanels?.panels.map(({ id }) => id) ?? [] }) };
33
+ return { views: resolveViews(this.#views, { objects: scene.objects, events: scene.events, panels: [...(storyPanels?.panels ?? []), ...(storyPanels?.steps ?? [])].map(({ id }) => id) }) };
34
34
  }
35
35
  }
@@ -13,11 +13,12 @@ export type { GroupInput, GroupOrbitInput, GroupClumpInput, GroupReadoutInput }
13
13
  export type { ActivityInput, ActivitySampleInput, ActivitySourceInput } from "./activity.js";
14
14
  export type { DataSource, MoonPositions, MoonIndex } from "./data.js";
15
15
  import type { PickerInput } from "./pickerInput.js";
16
+ import type { SkyFigureInput } from "./skyFigureInput.js";
16
17
  import type { MoonPanelInput, PlacesInput } from "./moonPanelInput.js";
17
18
  import type { BodySetInput } from "./bodySetInput.js";
18
19
  import { SceneCamera } from "./planCamera.js";
19
- import type { SceneActivityRead, SceneBodyRead, SceneBodySetRead, SceneEventRead, SceneGroupRead, SceneMoonPanelRead, ScenePanelRead, ScenePlacesRead, ScenePathRead, SceneTimelineRead, SceneViewsRead } from "./sceneReads.js";
20
- export type { SceneActivityRead, SceneBodyRead, SceneBodySetRead, SceneEventRead, SceneGroupRead, SceneMoonPanelRead, ScenePanelRead, ScenePlacesRead, ScenePathRead, SceneTimelineRead, SceneViewRead, SceneViewsRead } from "./sceneReads.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";
21
22
  export type { SceneCamera } from "./planCamera.js";
22
23
  import { type TimeInput } from "./time.js";
23
24
  import type { SwitchesInput } from "./switches.js";
@@ -193,9 +194,11 @@ export declare class Scene {
193
194
  get moonPanel(): SceneMoonPanelRead | undefined;
194
195
  /** The bodies that hold tagged places (`addPlaces`), in the order added, with how many each holds. A fresh frozen list on every read. */
195
196
  get places(): readonly ScenePlacesRead[];
197
+ /** The sky figures the scene holds (`addSkyFigures`), in the order added: id, label and kind. A fresh frozen list on every read. */
198
+ get skyFigures(): readonly SceneSkyFigureRead[];
196
199
  /** The events the scene holds (`addEvents`), sorted by time: id, label, `timeUtcMs`, type, object and provenance (the event's own, else the batch's). A fresh frozen list on every read. */
197
200
  get events(): readonly SceneEventRead[];
198
- /** The story panels (`addStoryPanels`), sorted by time with their times resolved against the events, path anchors and timeline as `mount` resolves them; empty when none were added. A bad panel throws `bad-panels`, as `mount` would. A fresh frozen list on every read. */
201
+ /** The story panels (`addStoryPanels`): moment panels by time (times resolved), then the steps (no `at`) in the order added against the events, path anchors and timeline as `mount` resolves them; empty when none were added. A bad panel throws `bad-panels`, as `mount` would. A fresh frozen list on every read. */
199
202
  get panels(): readonly ScenePanelRead[];
200
203
  /** The views the scene names (`setViews`): the id of the opening view (`startId`), where the choice shows and each view's id, label and the `objects`, `events` and `panels` it shows (ids, as the viewer resolves them: what the view names plus whatever no view names); undefined when none were named. Checks the ids as `mount` does, so a bad one throws `bad-view`. A fresh frozen object on every read. */
201
204
  get views(): SceneViewsRead | undefined;
@@ -250,6 +253,16 @@ export declare class Scene {
250
253
  * scene.setPicker({ id: "world", label: "World", options: [{ value: "tarn", label: "Tarn" }, { value: "mere", label: "Mere" }], value: "tarn" });
251
254
  */
252
255
  setPicker(input: PickerInput): this;
256
+ /**
257
+ * Adds figures and outlines drawn on the sky at infinity, like the stars (J2000 equatorial frame; presentation only), each with a label. A figure (`kind: "figure"`, the default) has `segments`, pairs of ends, an end being
258
+ * `{ star: <Hipparcos number> }` (a star of magnitude 6.5 or brighter in the star list) or `{ raDeg, decDeg }`; a boundary (`kind: "boundary"`) has `points`, a closed loop of at least three positions. `labelAt` places the label
259
+ * (default: the mean direction of the ends). They draw above the Sun's glow, from the orbit camera and from a look-out view; the switches `skyFigures` (on) and `skyBoundaries` (off) show each kind (`setSwitches`).
260
+ * A malformed figure throws `bad-sky-figure` and adds none of the call; a repeated id (in the call, or in the scene) throws `duplicate-id`. A star number not in the star list throws `unknown-star` when the scene is built (`mount`, `prepare`),
261
+ * because the star list loads then; a star list that cannot be read throws `missing-data` then. Read the result from `scene.skyFigures`.
262
+ * @example
263
+ * scene.addSkyFigures([{ id: "kite", label: "The Kite", segments: [[{ raDeg: 10, decDeg: 20 }, { raDeg: 14, decDeg: 26 }], [{ raDeg: 14, decDeg: 26 }, { star: 11767 }]] }]);
264
+ */
265
+ addSkyFigures(figures: readonly SkyFigureInput[]): this;
253
266
  /**
254
267
  * Adds the tagged places of one body, drawn as markers on it and opened in the information panel: categories (key, label, colour), places (id, name, kind, category, latitude and longitude in degrees as given,
255
268
  * description and optional details) and the provenance shown with each. The body must be in the scene when it is built. A second call for one body throws `duplicate-id`; a malformed list throws `bad-places`.
@@ -289,7 +302,7 @@ export declare class Scene {
289
302
  /** Adds timed events to the timeline, each with an id, a label and a moment; `provenance` says where the times come from and is shown with every event that has none of its own (`EventInput.provenance`). May be called more than once; it appends. A repeated id, in one call or across calls, throws `duplicate-id`; a malformed event or provenance throws "bad-event". */
290
303
  addEvents(events: readonly EventInput[], options?: AddEventsOptions): this;
291
304
  /**
292
- * Appends story panels that open as playback reaches them. A panel opens only when forward playback crosses its time, so one at the opening instant never opens by itself
305
+ * Appends story panels: those with `at` open as playback reaches them; those without are steps with Back and Next. A panel opens only when forward playback crosses its time, so one at the opening instant never opens by itself
293
306
  * (a panel with an `object` still has its marker on that object). `at.time` is any moment inside the timeline, in any year. A bad shape throws `bad-panels` here, naming the panel and field, and a repeated id `duplicate-id`.
294
307
  * 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.
295
308
  */
package/src/api/scene.js CHANGED
@@ -13,6 +13,7 @@ import { BodySetPlan } from "./planBodySets.js";
13
13
  import { MoonPanelPlan } from "./planMoonPanel.js";
14
14
  import { PickerPlan } from "./planPicker.js";
15
15
  import { PlacesPlan } from "./planPlaces.js";
16
+ import { SkyFigurePlan } from "./planSkyFigures.js";
16
17
  import { assembleScene } from "./assembleScene.js";
17
18
  import { SceneCamera } from "./planCamera.js";
18
19
  import { definitionOf, registerDefinition, registerMissingData } from "./definitionOf.js";
@@ -48,6 +49,7 @@ export class Scene {
48
49
  #bodySets = new BodySetPlan(() => this.#plan.catalogue, (id) => this.#taken(id));
49
50
  #moonPanel = new MoonPanelPlan();
50
51
  #places = new PlacesPlan();
52
+ #skyFigures = new SkyFigurePlan((id) => this.#taken(id));
51
53
  #picker = new PickerPlan();
52
54
  #story = new StoryPlan();
53
55
  #timeline = new TimelinePlan();
@@ -81,12 +83,14 @@ export class Scene {
81
83
  get moonPanel() { return this.#moonPanel.read(); }
82
84
  /** The bodies that hold tagged places (`addPlaces`), in the order added, with how many each holds. A fresh frozen list on every read. */
83
85
  get places() { return this.#places.reads(); }
86
+ /** The sky figures the scene holds (`addSkyFigures`), in the order added: id, label and kind. A fresh frozen list on every read. */
87
+ get skyFigures() { return this.#skyFigures.reads(); }
84
88
  /** The events the scene holds (`addEvents`), sorted by time: id, label, `timeUtcMs`, type, object and provenance (the event's own, else the batch's). A fresh frozen list on every read. */
85
89
  get events() { return this.#story.eventReads(); }
86
- /** The story panels (`addStoryPanels`), sorted by time with their times resolved against the events, path anchors and timeline as `mount` resolves them; empty when none were added. A bad panel throws `bad-panels`, as `mount` would. A fresh frozen list on every read. */
90
+ /** The story panels (`addStoryPanels`): moment panels by time (times resolved), then the steps (no `at`) in the order added against the events, path anchors and timeline as `mount` resolves them; empty when none were added. A bad panel throws `bad-panels`, as `mount` would. A fresh frozen list on every read. */
87
91
  get panels() {
88
92
  const { window } = this.#timelineSpan();
89
- return this.#story.panelReads(window, this.#tracked.values(), [...this.#plan.bodies.keys(), ...this.#tracked.keys(), ...this.#groupPlan.groups.keys(), ...this.#bodySets.memberIds()]);
93
+ return this.#story.panelReads(window, this.#tracked.values(), [...this.#plan.bodies.keys(), ...this.#tracked.keys(), ...this.#groupPlan.groups.keys(), ...this.#bodySets.memberIds()], [...this.#skyFigures.figures.keys()]);
90
94
  }
91
95
  /** The views the scene names (`setViews`): the id of the opening view (`startId`), where the choice shows and each view's id, label and the `objects`, `events` and `panels` it shows (ids, as the viewer resolves them: what the view names plus whatever no view names); undefined when none were named. Checks the ids as `mount` does, so a bad one throws `bad-view`. A fresh frozen object on every read. */
92
96
  get views() {
@@ -149,7 +153,7 @@ export class Scene {
149
153
  }
150
154
  /** Whether a body, path or group already has this id. */
151
155
  #taken(id) {
152
- return this.#plan.bodies.has(id) || this.#tracked.has(id) || this.#groupPlan.groups.has(id) || this.#bodySets.has(id);
156
+ return this.#plan.bodies.has(id) || this.#tracked.has(id) || this.#groupPlan.groups.has(id) || this.#bodySets.has(id) || this.#skyFigures.has(id);
153
157
  }
154
158
  /**
155
159
  * Adds a group of listed orbits drawn as one set of dots (one colour and dot size, one menu item and info card), with an optional clump near a body.
@@ -199,6 +203,20 @@ export class Scene {
199
203
  this.#picker.set(input);
200
204
  return this;
201
205
  }
206
+ /**
207
+ * Adds figures and outlines drawn on the sky at infinity, like the stars (J2000 equatorial frame; presentation only), each with a label. A figure (`kind: "figure"`, the default) has `segments`, pairs of ends, an end being
208
+ * `{ star: <Hipparcos number> }` (a star of magnitude 6.5 or brighter in the star list) or `{ raDeg, decDeg }`; a boundary (`kind: "boundary"`) has `points`, a closed loop of at least three positions. `labelAt` places the label
209
+ * (default: the mean direction of the ends). They draw above the Sun's glow, from the orbit camera and from a look-out view; the switches `skyFigures` (on) and `skyBoundaries` (off) show each kind (`setSwitches`).
210
+ * A malformed figure throws `bad-sky-figure` and adds none of the call; a repeated id (in the call, or in the scene) throws `duplicate-id`. A star number not in the star list throws `unknown-star` when the scene is built (`mount`, `prepare`),
211
+ * because the star list loads then; a star list that cannot be read throws `missing-data` then. Read the result from `scene.skyFigures`.
212
+ * @example
213
+ * scene.addSkyFigures([{ id: "kite", label: "The Kite", segments: [[{ raDeg: 10, decDeg: 20 }, { raDeg: 14, decDeg: 26 }], [{ raDeg: 14, decDeg: 26 }, { star: 11767 }]] }]);
214
+ */
215
+ addSkyFigures(figures) {
216
+ this.#editable();
217
+ this.#skyFigures.add(figures);
218
+ return this;
219
+ }
202
220
  /**
203
221
  * Adds the tagged places of one body, drawn as markers on it and opened in the information panel: categories (key, label, colour), places (id, name, kind, category, latitude and longitude in degrees as given,
204
222
  * description and optional details) and the provenance shown with each. The body must be in the scene when it is built. A second call for one body throws `duplicate-id`; a malformed list throws `bad-places`.
@@ -270,7 +288,7 @@ export class Scene {
270
288
  return this;
271
289
  }
272
290
  /**
273
- * Appends story panels that open as playback reaches them. A panel opens only when forward playback crosses its time, so one at the opening instant never opens by itself
291
+ * Appends story panels: those with `at` open as playback reaches them; those without are steps with Back and Next. A panel opens only when forward playback crosses its time, so one at the opening instant never opens by itself
274
292
  * (a panel with an `object` still has its marker on that object). `at.time` is any moment inside the timeline, in any year. A bad shape throws `bad-panels` here, naming the panel and field, and a repeated id `duplicate-id`.
275
293
  * 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.
276
294
  */
@@ -402,6 +420,6 @@ export class Scene {
402
420
  }
403
421
  /** The app's plug-in contract for this scene (`assembleScene.ts`), reached through `definitionOf`. Throws if the scene is empty or a body needs a data package not passed in `data`. */
404
422
  #definition(data) {
405
- return assembleScene({ plan: this.#plan, tracked: this.#tracked, groupPlan: this.#groupPlan, bodySets: this.#bodySets, moonPanel: this.#moonPanel, picker: this.#picker, places: this.#places, story: this.#story, timeline: this.#timeline, viewPlan: this.#viewPlan, camera: this.camera, scale: this.#scale, scaleOnly: this.#scaleOnly, look: this.#look, bodyReadouts: this.#bodyReadouts }, data);
423
+ return assembleScene({ plan: this.#plan, tracked: this.#tracked, groupPlan: this.#groupPlan, bodySets: this.#bodySets, moonPanel: this.#moonPanel, picker: this.#picker, places: this.#places, story: this.#story, timeline: this.#timeline, viewPlan: this.#viewPlan, skyFigures: this.#skyFigures, camera: this.camera, scale: this.#scale, scaleOnly: this.#scaleOnly, look: this.#look, bodyReadouts: this.#bodyReadouts }, data);
406
424
  }
407
425
  }
@@ -107,10 +107,11 @@ export interface SceneEventRead {
107
107
  /** Where the event's time comes from: its own, else the batch's; absent when neither was given. */
108
108
  readonly provenance?: Provenance;
109
109
  }
110
- /** A story panel the scene holds (`addStoryPanels`), as `Scene.panels` lists it (sorted by time, the times resolved). */
110
+ /** A story panel the scene holds (`addStoryPanels`), as `Scene.panels` lists it (moment panels by time, then steps in the order added). */
111
111
  export interface ScenePanelRead {
112
112
  readonly id: string;
113
- readonly timeUtcMs: number;
113
+ /** The panel's moment (Unix milliseconds UTC); absent on a step. */
114
+ readonly timeUtcMs?: number;
114
115
  readonly title: string;
115
116
  /** Paragraphs, in order. */
116
117
  readonly body: readonly string[];
@@ -167,5 +168,23 @@ export interface SceneTimelineRead {
167
168
  /** Whether playback wraps from the end to the start. */
168
169
  readonly loop: boolean;
169
170
  }
171
+ /** A sky figure the scene holds (`addSkyFigures`), as `Scene.skyFigures` lists it (in the order added) and the viewer handle reads it. */
172
+ export interface SceneSkyFigureRead {
173
+ readonly id: string;
174
+ readonly label: string;
175
+ /** `"figure"` (lines between stars) or `"boundary"` (a closed outline). */
176
+ readonly kind: "figure" | "boundary";
177
+ /** The words on its info card: the `description` given to `addSkyFigures`, else absent. */
178
+ readonly description?: string;
179
+ /** The facts on its info card, as given (`facts`); absent when none were given. */
180
+ readonly facts?: readonly {
181
+ readonly label: string;
182
+ readonly value: string;
183
+ }[];
184
+ /** Whether the object menu offers it (`listed`); true unless `addSkyFigures` said false. */
185
+ readonly listed: boolean;
186
+ /** The provenance its card shows: the one given (default illustrative, supplied by the caller) with `sources` added. */
187
+ readonly provenance: Provenance;
188
+ }
170
189
  /** Freezes a list and each of its items, and returns it. */
171
190
  export declare function frozenList<T extends object>(items: readonly T[]): readonly T[];
@@ -0,0 +1,45 @@
1
+ import type { Provenance } from "../core/provenance.js";
2
+ import type { CardFactInput } from "./scene.js";
3
+ import type { SkyDirection } from "./viewerLink.js";
4
+ /** One end of a figure's line: a catalogue star by its Hipparcos number (`{ star: 11767 }`), or a star-map position (`{ raDeg, decDeg }`, J2000 degrees). */
5
+ export type SkyFigureEnd = {
6
+ readonly star: number;
7
+ } | SkyDirection;
8
+ /**
9
+ * A figure or an outline drawn on the sky at infinity, as `Scene.addSkyFigures` takes it. A `"figure"` (the default) has `segments`, each a pair of ends; a `"boundary"` has `points`, a closed loop of at least three positions
10
+ * (the last joins the first). `labelAt` places the label; without it the label stands at the mean direction of the ends.
11
+ */
12
+ export interface SkyFigureInput {
13
+ /** Unique among the scene's bodies, paths, groups, body sets and sky figures. */
14
+ readonly id: string;
15
+ /** The name drawn on the sky. */
16
+ readonly label: string;
17
+ /** `"figure"` (the default, drawn from `segments`) or `"boundary"` (drawn from `points`). The display switches `skyFigures` and `skyBoundaries` act on one kind each. */
18
+ readonly kind?: "figure" | "boundary";
19
+ /** The lines of a figure: pairs of ends. Required for a figure, refused for a boundary. */
20
+ readonly segments?: readonly (readonly [SkyFigureEnd, SkyFigureEnd])[];
21
+ /** The corners of a boundary, in order. Required for a boundary, refused for a figure. */
22
+ readonly points?: readonly SkyDirection[];
23
+ /** Where the label stands. */
24
+ readonly labelAt?: SkyDirection;
25
+ /** `"always"` (the default): the figure is drawn whenever its switch is on. `"whenTraced"`: nothing of it (lines or label) is drawn until `traceSkyFigure` starts a trace of it; the trace then draws its lines and shows its label, and `after` decides whether they stay or fade (`clearSkyTrace` removes them at any time). */
26
+ readonly shown?: "always" | "whenTraced";
27
+ /** This figure's line colour, a CSS colour text; default: the look's `skyLines.figure` or `skyLines.boundary`. */
28
+ readonly color?: string;
29
+ /** This figure's label colour, a CSS colour text; default: the look's `skyLines.label`. */
30
+ readonly labelColor?: string;
31
+ /** This figure's label font, a CSS font-family text; default: the look's `labels.fontFamily`. */
32
+ readonly labelFont?: string;
33
+ /** This figure's label size in pixels, 8 to 24; default: the look's `labels.sizePx`. */
34
+ readonly labelSizePx?: number;
35
+ /** One or two plain sentences for the figure's info card (shown when a visitor taps it or picks it from the object menu). None by default. */
36
+ readonly description?: string;
37
+ /** Labelled facts for the card, in order, as for `addBody`: both texts non-empty. None by default. */
38
+ readonly facts?: readonly CardFactInput[];
39
+ /** Sources added to the card's provenance after its own, each a non-empty text. None by default. */
40
+ readonly sources?: readonly string[];
41
+ /** Where the figure's drawn lines come from, shown on the card. Default: illustrative, supplied by the caller (as for `addTrajectory`). */
42
+ readonly provenance?: Provenance;
43
+ /** False leaves the figure out of the viewer's object menu (default true, as for `addBody`); it stays tappable and the menu shows it while it is the selected one. */
44
+ readonly listed?: boolean;
45
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,33 @@
1
+ import { type SkyTraceAfter } from "../core/skyTrace.js";
2
+ /** What `handle.traceSkyFigure` takes besides the figure's id. */
3
+ export interface SkyTraceOptions {
4
+ /** How long the trace takes, in real seconds, 0.1 to 60 (default 2). The segments are drawn in the order they were added, each growing from its first end, each for an equal share of the time. Real time: pausing or changing the scene clock does not change it. */
5
+ readonly durationSeconds?: number;
6
+ /** What follows: `"stay"` (the default) keeps the traced lines in the look's `skyLines.traced` colour until the figure is traced again or `clearSkyTrace` removes them; `"fade"` eases them to `skyLines.faded` over a second and removes them. */
7
+ readonly after?: "stay" | "fade";
8
+ }
9
+ /** What `handle.clearSkyTrace` takes besides the figure's id. */
10
+ export interface SkyClearOptions {
11
+ /** How long the trace takes to fade away, in real seconds, 0 to 60 (default 1, the time a `fade` takes); 0 removes it at once. */
12
+ readonly durationSeconds?: number;
13
+ }
14
+ /** A checked clear request: the figure and how long its trace takes to go. */
15
+ export interface CheckedClear {
16
+ readonly id: string;
17
+ readonly seconds: number;
18
+ }
19
+ /** A checked trace request: the figure and what to do with it. */
20
+ export interface CheckedTrace {
21
+ readonly id: string;
22
+ readonly seconds: number;
23
+ readonly after: SkyTraceAfter;
24
+ }
25
+ /** Checks the options of a trace (`traceSkyFigure`'s, or a story panel's `trace`) and fills the defaults; throws `bad-sky-trace`. */
26
+ export declare function traceOptionsOf(options: unknown, verb?: string): {
27
+ readonly seconds: number;
28
+ readonly after: SkyTraceAfter;
29
+ };
30
+ /** Checks a trace request against the figures the viewer draws; throws `unknown-sky-figure` (the id) or `bad-sky-trace` (the options). */
31
+ export declare function checkedTrace(id: unknown, options: unknown, known: readonly string[]): CheckedTrace;
32
+ /** Checks a clear request as `checkedTrace` checks a trace; `durationSeconds` may be 0 (at once). */
33
+ export declare function checkedClear(id: unknown, options: unknown, known: readonly string[]): CheckedClear;
@@ -0,0 +1,45 @@
1
+ import { SceneError } from "./errors.js";
2
+ import { DEFAULT_TRACE_SECONDS, SKY_TRACE_AFTER, TRACE_FADE_SECONDS, TRACE_SECONDS_LIMITS } from "../core/skyTrace.js";
3
+ const bad = (message, verb = "traceSkyFigure") => new SceneError("bad-sky-trace", `${verb}: ${message}`);
4
+ /** Throws `unknown-sky-figure` unless `id` is one of the figures the viewer draws. */
5
+ function knownFigure(id, known, verb) {
6
+ if (typeof id !== "string" || !known.includes(id)) {
7
+ throw new SceneError("unknown-sky-figure", `${verb}: ${typeof id === "string" ? `"${id}"` : String(id)} is not a sky figure this viewer draws (${known.length === 0 ? "the scene added none; add them with addSkyFigures" : known.join(", ")})`);
8
+ }
9
+ }
10
+ /** The options object of a call as a record, or throws `bad-sky-trace` when it is neither an object nor nothing, or has a key outside `allowed`. */
11
+ function optionsOf(options, allowed, verb) {
12
+ if (options !== undefined && (typeof options !== "object" || options === null || Array.isArray(options)))
13
+ throw bad(`expected an options object or nothing, got ${String(options)}`, verb);
14
+ const given = (options ?? {});
15
+ for (const key of Object.keys(given))
16
+ if (!allowed.includes(key))
17
+ throw bad(`"${key}" is not an option (${allowed.join(", ")})`, verb);
18
+ return given;
19
+ }
20
+ /** Checks the options of a trace (`traceSkyFigure`'s, or a story panel's `trace`) and fills the defaults; throws `bad-sky-trace`. */
21
+ export function traceOptionsOf(options, verb = "traceSkyFigure") {
22
+ const given = optionsOf(options, ["durationSeconds", "after"], verb);
23
+ const seconds = given.durationSeconds ?? DEFAULT_TRACE_SECONDS;
24
+ const { min, max } = TRACE_SECONDS_LIMITS;
25
+ if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < min || seconds > max)
26
+ throw bad(`durationSeconds must be a number from ${min} to ${max}, got ${String(seconds)}`, verb);
27
+ const after = given.after ?? "stay";
28
+ if (!SKY_TRACE_AFTER.includes(after))
29
+ throw bad(`after must be one of ${SKY_TRACE_AFTER.join(", ")}, got ${String(after)}`, verb);
30
+ return { seconds, after: after };
31
+ }
32
+ /** Checks a trace request against the figures the viewer draws; throws `unknown-sky-figure` (the id) or `bad-sky-trace` (the options). */
33
+ export function checkedTrace(id, options, known) {
34
+ knownFigure(id, known, "traceSkyFigure");
35
+ return { id, ...traceOptionsOf(options) };
36
+ }
37
+ /** Checks a clear request as `checkedTrace` checks a trace; `durationSeconds` may be 0 (at once). */
38
+ export function checkedClear(id, options, known) {
39
+ knownFigure(id, known, "clearSkyTrace");
40
+ const given = optionsOf(options, ["durationSeconds"], "clearSkyTrace");
41
+ const seconds = given.durationSeconds ?? TRACE_FADE_SECONDS;
42
+ if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < 0 || seconds > TRACE_SECONDS_LIMITS.max)
43
+ throw bad(`durationSeconds must be a number from 0 to ${TRACE_SECONDS_LIMITS.max}, got ${String(seconds)}`, "clearSkyTrace");
44
+ return { id, seconds };
45
+ }
@@ -3,6 +3,8 @@ import { type Pacing } from "../core/pacing.js";
3
3
  import { type Provenance } from "../core/provenance.js";
4
4
  import type { TimeBounds } from "../core/trajectory.js";
5
5
  import { type CheckedPanel, type PanelLookup, type PanelPlayback, type StoryPanelSet } from "../core/storyPanels.js";
6
+ import { type SkyTraceOptions } from "./skyTraceInput.js";
7
+ import type { CameraTarget } from "./viewerLink.js";
6
8
  import { type TimeInput } from "./time.js";
7
9
  /** A timed event: a labelled moment on the timeline. The id is unique among the scene's events: a repeat throws `duplicate-id`. */
8
10
  export interface EventInput {
@@ -13,7 +15,7 @@ export interface EventInput {
13
15
  readonly type?: string;
14
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. */
15
17
  readonly provenance?: Provenance;
16
- /** The body or trajectory (its id) this event is about. Go to this event seeks to its time and frames the object as `camera.focus` does. 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, 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. */
17
19
  readonly object?: string;
18
20
  /**
19
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
@@ -104,7 +106,8 @@ export type StoryPanelAt = {
104
106
  export interface StoryPanelInput {
105
107
  /** Unique among the scene's panels: a repeat throws `duplicate-id`. */
106
108
  readonly id: string;
107
- readonly at: StoryPanelAt;
109
+ /** When the panel opens. Left out, it is a step: steps keep the order added, never open from playback, and show Back and Next. */
110
+ readonly at?: StoryPanelAt;
108
111
  readonly title: string;
109
112
  /** Paragraphs, in order; one text is one paragraph. */
110
113
  readonly body: string | readonly string[];
@@ -112,8 +115,14 @@ export interface StoryPanelInput {
112
115
  readonly details?: string | readonly string[];
113
116
  /** Where the panel's facts come from. The badge shows the word for `sourceType`; `sources`, `accuracy` and `notes` show in the panel's folded section. `sources` is never empty and `accuracy` is never blank: where a source states none, say so. */
114
117
  readonly provenance: Provenance;
115
- /** The id of a body or path the panel is about; it gets a marker that reopens the panel. */
118
+ /** The id of a body, path or sky figure the panel is about; a body or path gets a marker that reopens the panel. */
116
119
  readonly object?: string;
120
+ /** Turns the camera when the panel opens (anything `setCamera` takes). */
121
+ readonly camera?: CameraTarget;
122
+ /** True: selects the `object`. */
123
+ readonly select?: boolean;
124
+ /** Traces the `object`, a sky figure. */
125
+ readonly trace?: true | SkyTraceOptions;
117
126
  }
118
127
  /** The playback settings of a scene's story panels. */
119
128
  export interface StoryPanelPlaybackInput {
package/src/api/story.js CHANGED
@@ -3,6 +3,8 @@ import { zoneAround } from "../core/pacing.js";
3
3
  import { createProvenance } from "../core/provenance.js";
4
4
  import { checkPanelPlayback, checkStoryPanel, resolveStoryPanels, StoryPanelError } from "../core/storyPanels.js";
5
5
  import { SceneError } from "./errors.js";
6
+ import { cameraRequestOf } from "./cameraRequest.js";
7
+ import { traceOptionsOf } from "./skyTraceInput.js";
6
8
  import { rejectRenamed } from "./renamedInputs.js";
7
9
  import { toUtcMs } from "./time.js";
8
10
  /** Throws "bad-event" naming the first event whose `object` is not among the scene's `objectIds`. */
@@ -44,6 +46,16 @@ export function eventsOf(inputs, known) {
44
46
  });
45
47
  return createEvents([...known, ...added].sort((a, b) => a.timeUtcMs - b.timeUtcMs));
46
48
  }
49
+ /** A rate that crosses the whole span in under this many real seconds is probably a unit mistake (milliseconds given for seconds). */
50
+ const MIN_CROSSING_REAL_SECONDS = 1;
51
+ /** Warns (never throws: a short span at a fast rate can be meant) when a `rate` or an offered rate crosses the whole timeline span in under a real second; I-163. */
52
+ function warnOfFastRates(window, input) {
53
+ const spanSeconds = (window.endUtcMs - window.startUtcMs) / 1000;
54
+ const fast = [...new Set([...(input.rates ?? []), ...(input.rate === undefined ? [] : [input.rate])].filter((rate) => spanSeconds / Math.abs(rate) < MIN_CROSSING_REAL_SECONDS))];
55
+ if (fast.length === 0)
56
+ return;
57
+ console.warn(`setTimeline: rate ${fast.join(", ")} is in simulated seconds per real second and would cross the whole ${spanSeconds}-second span in under a real second; if the value is in milliseconds (for example DAY_MS), divide it by 1000`);
58
+ }
47
59
  /** Checks a `setTimeline` argument and converts its moments. */
48
60
  export function timelineOf(input) {
49
61
  const bad = (message) => new SceneError("bad-timeline", `setTimeline: ${message}`);
@@ -62,6 +74,7 @@ export function timelineOf(input) {
62
74
  if (rates !== undefined && (!Array.isArray(rates) || rates.length === 0 || !rates.every((rate) => Number.isFinite(rate) && rate > 0)))
63
75
  throw bad("rates must be a non-empty list of positive numbers");
64
76
  const pacing = pacingOf(input.pacing, bad);
77
+ warnOfFastRates(window, input);
65
78
  return { none: false, window, ...(rates === undefined ? {} : { rates }), ...(pacing === undefined ? {} : { pacing }), ...(input.rate === undefined ? {} : { rate: input.rate }), ...(input.loop === true ? { loop: true } : {}) };
66
79
  }
67
80
  /** Runs a core panel check, turning a `StoryPanelError` into a `bad-panels` SceneError that leads with `call`. */
@@ -86,13 +99,43 @@ export function panelBatchOf(inputs, known) {
86
99
  const where = `addStoryPanels: story panel ${typeof named === "string" ? named : `#${index + 1}`}`;
87
100
  rejectRenamed("StoryPanelInput", input, where);
88
101
  rejectRenamed("StoryPanelAt", input?.at, `${where} at`);
89
- const panel = panelCheck("addStoryPanels", () => checkStoryPanel(input, index));
102
+ const checked = panelCheck("addStoryPanels", () => checkStoryPanel(input, index));
103
+ const panel = { ...checked, ...panelActionsOf(input, checked.id, checked.object) };
90
104
  if (ids.has(panel.id))
91
105
  throw new SceneError("duplicate-id", `${where}: that id is already in the scene's panels`);
92
106
  ids.add(panel.id);
93
107
  return panel;
94
108
  });
95
109
  }
110
+ /** The actions of a panel (`camera`, `select`, `trace`), checked in shape; a mistake throws `bad-panels` naming the panel and field. What they name is checked when the scene is built. */
111
+ function panelActionsOf(input, id, object) {
112
+ const bad = (field, why) => new SceneError("bad-panels", `addStoryPanels: story panel ${id}: ${field} ${why}`);
113
+ let camera;
114
+ if (input.camera !== undefined) {
115
+ try {
116
+ camera = cameraRequestOf(input.camera, "camera", undefined, true);
117
+ }
118
+ catch (error) {
119
+ throw bad("camera", `is not a camera target (${error instanceof Error ? error.message : String(error)})`);
120
+ }
121
+ }
122
+ if (input.select !== undefined && typeof input.select !== "boolean")
123
+ throw bad("select", "must be true or false");
124
+ if (input.select === true && object === undefined)
125
+ throw bad("select", "needs an object to select");
126
+ let trace;
127
+ if (input.trace !== undefined && input.trace !== false) {
128
+ if (object === undefined)
129
+ throw bad("trace", "needs an object that names a sky figure");
130
+ try {
131
+ trace = traceOptionsOf(input.trace === true ? undefined : input.trace);
132
+ }
133
+ catch (error) {
134
+ throw bad("trace", `is not true or trace options (${error instanceof Error ? error.message : String(error)})`);
135
+ }
136
+ }
137
+ return { ...(camera === undefined ? {} : { camera }), ...(input.select === true ? { select: true } : {}), ...(trace === undefined ? {} : { trace }) };
138
+ }
96
139
  /** Checks a `setStoryPanelPlayback` argument; a mistake throws `bad-panels`. */
97
140
  export function panelPlaybackOf(input) {
98
141
  return panelCheck("setStoryPanelPlayback", () => checkPanelPlayback(input));
@@ -11,11 +11,12 @@ export declare class ViewerCamera {
11
11
  onCameraChange(listener: (camera: CameraPose) => void): () => void;
12
12
  /** A viewer publish (its tick, or a host or visitor action): reports the pose when it differs from the last one. */
13
13
  publish(): void;
14
- /** The camera pose, or undefined before the viewer is drawn and after it is gone; before its first frame it is the opening camera. */
14
+ /** The camera pose, or undefined before the viewer is drawn and after it is gone; before its first frame it is the opening camera, or undefined when the opening look-out turns toward an id (resolved on that frame). */
15
15
  get camera(): CameraPose | undefined;
16
16
  /**
17
- * Points the camera: `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, a pose (from `camera`) puts the camera back where it was read,
18
- * relative to its object. The id must be an object the showing view shows; an unknown or hidden id, or a malformed argument, throws `bad-camera`.
17
+ * Points the camera: `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, `{ lookOut: id, direction?, fovDeg? }` stands inside a body looking out,
18
+ * a pose (from `camera`, either kind) puts the camera back where it was read (an orbit pose relative to its object).
19
+ * Every id must be an object the showing view shows (a look-out `direction` may name a sky figure too); an unknown or hidden id, a direction or field of view out of range, or a malformed argument, throws `bad-camera`.
19
20
  * Before the viewer is drawn or after it is gone, `not-mounted`. The move eases in as a view's camera rule does.
20
21
  */
21
22
  setCamera(target: CameraTarget): void;
@@ -1,8 +1,9 @@
1
- import { validateStartView } from "../core/startView.js";
2
- import { SceneError } from "./errors.js";
1
+ import { cameraRequestOf, checkCameraIds } from "./cameraRequest.js";
3
2
  import { callListeners } from "./listeners.js";
4
3
  /** The shortest time between two reports, a little under the viewer's 100 ms tick so a tick is never skipped. */
5
4
  const MIN_GAP_MS = 80;
5
+ /** Whether two readings say the same: both orbit or both sky, with every field equal (a reading's keys always come in one order). */
6
+ const samePose = (a, b) => JSON.stringify(a) === JSON.stringify(b);
6
7
  /** The host link's camera: the pose read and `setCamera`, with its request check. */
7
8
  export class ViewerCamera {
8
9
  access;
@@ -35,7 +36,7 @@ export class ViewerCamera {
35
36
  this.#last = pose;
36
37
  return;
37
38
  } // the first frame's pose is the opening one
38
- if (pose.focus === last.focus && pose.azimuthDeg === last.azimuthDeg && pose.elevationDeg === last.elevationDeg && pose.distance === last.distance)
39
+ if (samePose(pose, last))
39
40
  return;
40
41
  const now = performance.now();
41
42
  if (now - this.#reportedAt < MIN_GAP_MS)
@@ -44,41 +45,18 @@ export class ViewerCamera {
44
45
  this.#reportedAt = now;
45
46
  callListeners(this.#listeners, pose);
46
47
  }
47
- /** The camera pose, or undefined before the viewer is drawn and after it is gone; before its first frame it is the opening camera. */
48
+ /** The camera pose, or undefined before the viewer is drawn and after it is gone; before its first frame it is the opening camera, or undefined when the opening look-out turns toward an id (resolved on that frame). */
48
49
  get camera() { return this.access.control()?.readCamera(); }
49
50
  /**
50
- * Points the camera: `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, a pose (from `camera`) puts the camera back where it was read,
51
- * relative to its object. The id must be an object the showing view shows; an unknown or hidden id, or a malformed argument, throws `bad-camera`.
51
+ * Points the camera: `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, `{ lookOut: id, direction?, fovDeg? }` stands inside a body looking out,
52
+ * a pose (from `camera`, either kind) puts the camera back where it was read (an orbit pose relative to its object).
53
+ * Every id must be an object the showing view shows (a look-out `direction` may name a sky figure too); an unknown or hidden id, a direction or field of view out of range, or a malformed argument, throws `bad-camera`.
52
54
  * Before the viewer is drawn or after it is gone, `not-mounted`. The move eases in as a view's camera rule does.
53
55
  */
54
56
  setCamera(target) {
55
57
  const control = this.access.open("setCamera");
56
- const request = this.#request(target);
57
- const id = request.kind === "pose" ? request.view.focus : request.kind === "overview" || request.kind === "hold" ? "" : request.target;
58
- if (!control.cameraTargets().includes(id)) {
59
- throw new SceneError("bad-camera", `setCamera: "${id}" is not an object the showing view shows (${control.cameraTargets().join(", ")})`);
60
- }
58
+ const request = cameraRequestOf(target, "setCamera", this.camera);
59
+ checkCameraIds(request, "setCamera", control.cameraTargets(), (control.skyFigures ?? []).map(({ id }) => id));
61
60
  control.setCamera(request);
62
61
  }
63
- #request(target) {
64
- const bad = (why) => new SceneError("bad-camera", `setCamera: ${why}; give { follow: id }, { focus: id } or a pose from camera`);
65
- if (typeof target !== "object" || target === null || Array.isArray(target))
66
- throw bad(`${String(target)} is not an object`);
67
- const record = target;
68
- // A pose names its object with `focus` too; its angle and distance fields tell it from `{ focus: id }`.
69
- const isPose = ["azimuthDeg", "elevationDeg", "distance"].some((key) => key in record) || !("follow" in record || "focus" in record);
70
- const named = ["follow", "focus"].filter((key) => key in record);
71
- if (isPose) {
72
- try {
73
- return { kind: "pose", view: validateStartView(record, "pose") };
74
- }
75
- catch (cause) {
76
- throw bad(cause instanceof Error ? cause.message : "a malformed pose");
77
- }
78
- }
79
- const id = record[named[0]];
80
- if (named.length > 1 || Object.keys(record).length > 1 || typeof id !== "string" || id === "")
81
- throw bad("the target must be exactly one of follow or focus, naming a non-empty id");
82
- return { kind: named[0], target: id };
83
- }
84
62
  }