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
@@ -3,6 +3,7 @@ import { ChebyshevEphemeris, parseEphemerisIndex } from "../chebyshevEphemeris.j
3
3
  import { iauOrientation } from "../iauRotation.js";
4
4
  import { periodAboutBalanceS } from "../orbitPeriod.js";
5
5
  import { NotLoadedError } from "../planetSeries.js";
6
+ import { fetchBytesOf } from "../readBytes.js";
6
7
  import { createProvenance } from "../provenance.js";
7
8
  import { assertUtcUnixMs, createState } from "../state.js";
8
9
  /** The span the committed fits cover (T-096, T-114: 2010-01-01 to 2030-01-01 TDB, chunked per calendar year; the same for every system). */
@@ -53,21 +54,6 @@ const HISTORY_MARGIN = 1.05;
53
54
  const DECODE_SLICE_MS = 8;
54
55
  /** Half the time step (s) the orbit-derived tidal-lock orientation looks along the orbit, as Io's mean-element orientation did. */
55
56
  const ORIENTATION_STEP_S = 1800;
56
- /** Reads a `file:` address with Node's own module (found at run time, so a browser bundle never resolves it); Node's `fetch` does not serve `file:`. */
57
- async function readFileUrl(url) {
58
- const nodeFs = globalThis.process?.getBuiltinModule?.("node:fs/promises");
59
- if (nodeFs === undefined)
60
- throw new Error(`moon fit chunk ${url}: this runtime cannot read a file: address`);
61
- return new Uint8Array(await nodeFs.readFile(new URL(url)));
62
- }
63
- const fetchBytesOf = async (url) => {
64
- if (url.startsWith("file:"))
65
- return readFileUrl(url);
66
- const response = await fetch(url);
67
- if (!response.ok)
68
- throw new Error(`moon fit chunk ${url}: HTTP ${response.status}`);
69
- return new Uint8Array(await response.arrayBuffer());
70
- };
71
57
  export function createMoonSystem(config) {
72
58
  let installed = null;
73
59
  let loadIndex = config.loadIndex;
@@ -0,0 +1,9 @@
1
+ /** True for a hex colour, a comma-form `rgb()`, `rgba()`, `hsl()` or `hsla()` or a named colour. */
2
+ export declare function isCssColour(value: unknown): value is string;
3
+ /** True for a non-blank font family text (any CSS font-family list, or `inherit`). */
4
+ export declare function isFontFamily(value: unknown): value is string;
5
+ /** Label size range in pixels: small enough for a crowded sky, large enough to read on a phone. */
6
+ export declare const LABEL_SIZE_LIMITS: Readonly<{
7
+ min: 8;
8
+ max: 24;
9
+ }>;
@@ -0,0 +1,24 @@
1
+ // What a look may hold (O-065 T-296): whether a text is a CSS colour the viewer would take, checked here without a browser so a bad colour fails at `setLook` / `addSkyFigures` in Node too (API-04, API-05).
2
+ const NAMED = new Set(("aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan "
3
+ + "darkgoldenrod darkgray darkgreen darkgrey darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink "
4
+ + "deepskyblue dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray green greenyellow grey honeydew hotpink indianred indigo ivory khaki lavender lavenderblush "
5
+ + "lawngreen lemonchiffon lightblue lightcoral lightcyan lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen lightskyblue lightslategray lightslategrey lightsteelblue lightyellow "
6
+ + "lime limegreen linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin "
7
+ + "navajowhite navy oldlace olive olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum powderblue purple rebeccapurple red rosybrown royalblue "
8
+ + "saddlebrown salmon sandybrown seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen steelblue tan teal thistle tomato turquoise violet wheat white whitesmoke yellow yellowgreen").split(" "));
9
+ const HEX = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
10
+ // The comma forms only: the drawing library that paints the lines reads these (and hex and names), not the space-separated or newer colour functions.
11
+ const FUNCTION = /^(?:rgb|hsl)a?\(\s*[\d.]+%?\s*,\s*[\d.]+%?\s*,\s*[\d.]+%?\s*(?:,\s*[\d.]+%?\s*)?\)$/i;
12
+ /** True for a hex colour, a comma-form `rgb()`, `rgba()`, `hsl()` or `hsla()` or a named colour. */
13
+ export function isCssColour(value) {
14
+ if (typeof value !== "string")
15
+ return false;
16
+ const text = value.trim();
17
+ return HEX.test(text) || FUNCTION.test(text) || NAMED.has(text.toLowerCase());
18
+ }
19
+ /** True for a non-blank font family text (any CSS font-family list, or `inherit`). */
20
+ export function isFontFamily(value) {
21
+ return typeof value === "string" && value.trim() !== "" && !/[;{}]/.test(value);
22
+ }
23
+ /** Label size range in pixels: small enough for a crowded sky, large enough to read on a phone. */
24
+ export const LABEL_SIZE_LIMITS = Object.freeze({ min: 8, max: 24 });
@@ -0,0 +1 @@
1
+ export declare const fetchBytesOf: (url: string) => Promise<Uint8Array>;
@@ -0,0 +1,15 @@
1
+ /** Reads the bytes at a bundled address: a `file:` address with Node's own module (found at run time, so a browser bundle never resolves it; Node's `fetch` does not serve `file:`), anything else by `fetch`. One reader for every bundled file the engine loads (moon fit chunks, the star list). */
2
+ async function readFileUrl(url) {
3
+ const nodeFs = globalThis.process?.getBuiltinModule?.("node:fs/promises");
4
+ if (nodeFs === undefined)
5
+ throw new Error(`${url}: this runtime cannot read a file: address`);
6
+ return new Uint8Array(await nodeFs.readFile(new URL(url)));
7
+ }
8
+ export const fetchBytesOf = async (url) => {
9
+ if (url.startsWith("file:"))
10
+ return readFileUrl(url);
11
+ const response = await fetch(url);
12
+ if (!response.ok)
13
+ throw new Error(`${url}: HTTP ${response.status}`);
14
+ return new Uint8Array(await response.arrayBuffer());
15
+ };
@@ -0,0 +1,49 @@
1
+ /** What follows a trace: the traced lines stay, or fade away. (Removing a trace at any time is `clearSkyTrace`.) */
2
+ export type SkyTraceAfter = "stay" | "fade";
3
+ export declare const SKY_TRACE_AFTER: readonly SkyTraceAfter[];
4
+ /** How long a trace takes, in seconds, when the app does not say. */
5
+ export declare const DEFAULT_TRACE_SECONDS = 2;
6
+ /** The range of `durationSeconds` a trace accepts. */
7
+ export declare const TRACE_SECONDS_LIMITS: Readonly<{
8
+ min: 0.1;
9
+ max: 60;
10
+ }>;
11
+ /** How long a `fade` takes after the trace, in seconds. */
12
+ export declare const TRACE_FADE_SECONDS = 1;
13
+ /** How long sky lines and their names take to fade in when they appear, in seconds, when the look does not say (owner, T-306). */
14
+ export declare const DEFAULT_SKY_FADE_IN_SECONDS = 0.5;
15
+ /** The longest step one frame moves the fade-in on, in seconds, so a frame after an idle spell (the scene draws only when needed) does not skip the fade. */
16
+ export declare const SKY_FADE_IN_STEP_LIMIT = 0.1;
17
+ /** The share of a fade-in shown after one more step: `from` moved on by `deltaSeconds` (capped at `SKY_FADE_IN_STEP_LIMIT`) of `seconds`; 0 seconds shows it all at once. */
18
+ export declare function stepFadeIn(from: number, deltaSeconds: number, seconds: number): number;
19
+ /** One trace in progress. `reduced`: the person asked for less motion, so the whole figure shows at once. */
20
+ export interface SkyTraceRun {
21
+ readonly seconds: number;
22
+ readonly after: SkyTraceAfter;
23
+ readonly reduced: boolean;
24
+ /** Real seconds since the trace began. */
25
+ elapsed: number;
26
+ }
27
+ /** What one step of a trace says to draw. */
28
+ export interface SkyTraceFrame {
29
+ /** The share of the figure's segments drawn, 0 to 1 (segments in order, each growing from its first end). */
30
+ readonly drawn: number;
31
+ /** How far the lines have faded, 0 to 1 (0: the traced colour; 1: the faded colour, then gone). */
32
+ readonly fade: number;
33
+ /** True: the trace is over and its lines go (`clear`, or a finished `fade`). */
34
+ readonly done: boolean;
35
+ /** True: this step changed what is drawn, so the scene must draw this frame. */
36
+ readonly moving: boolean;
37
+ }
38
+ /** Moves a trace on by `deltaSeconds` of real time and says what to draw. A `stay` trace holds its drawn figure for good (until the app traces it again). */
39
+ export declare function stepTrace(run: SkyTraceRun, deltaSeconds: number): SkyTraceFrame;
40
+ /** A trace on its way out because the host asked to clear it: eases from the fade it had to 1 over `seconds` (0: gone this step). */
41
+ export interface SkyHideRun {
42
+ readonly seconds: number;
43
+ /** The fade the trace had when the request was taken, 0 to 1. */
44
+ readonly from: number;
45
+ /** Real seconds since the request was taken. */
46
+ elapsed: number;
47
+ }
48
+ /** Moves a hide on by `deltaSeconds` of real time; `drawn` is the share the trace had reached, which a hide holds. */
49
+ export declare function stepHide(run: SkyHideRun, deltaSeconds: number, drawn: number): SkyTraceFrame;
@@ -0,0 +1,39 @@
1
+ // How a sky-figure trace runs (O-065 T-297): pure arithmetic with no drawing, shared by the host call's checks (`src/api`) and the frame stage (`src/app`). Wall time only: the scene clock never enters.
2
+ export const SKY_TRACE_AFTER = Object.freeze(["stay", "fade"]);
3
+ /** How long a trace takes, in seconds, when the app does not say. */
4
+ export const DEFAULT_TRACE_SECONDS = 2;
5
+ /** The range of `durationSeconds` a trace accepts. */
6
+ export const TRACE_SECONDS_LIMITS = Object.freeze({ min: 0.1, max: 60 });
7
+ /** How long a `fade` takes after the trace, in seconds. */
8
+ export const TRACE_FADE_SECONDS = 1;
9
+ /** How long sky lines and their names take to fade in when they appear, in seconds, when the look does not say (owner, T-306). */
10
+ export const DEFAULT_SKY_FADE_IN_SECONDS = 0.5;
11
+ /** The longest step one frame moves the fade-in on, in seconds, so a frame after an idle spell (the scene draws only when needed) does not skip the fade. */
12
+ export const SKY_FADE_IN_STEP_LIMIT = 0.1;
13
+ /** The share of a fade-in shown after one more step: `from` moved on by `deltaSeconds` (capped at `SKY_FADE_IN_STEP_LIMIT`) of `seconds`; 0 seconds shows it all at once. */
14
+ export function stepFadeIn(from, deltaSeconds, seconds) {
15
+ if (seconds <= 0)
16
+ return 1;
17
+ return Math.min(1, from + Math.min(SKY_FADE_IN_STEP_LIMIT, Math.max(0, deltaSeconds)) / seconds);
18
+ }
19
+ /** Moves a trace on by `deltaSeconds` of real time and says what to draw. A `stay` trace holds its drawn figure for good (until the app traces it again). */
20
+ export function stepTrace(run, deltaSeconds) {
21
+ const unsettled = run.elapsed < run.seconds; // a `stay` trace changes only until it is fully drawn
22
+ run.elapsed += Math.max(0, deltaSeconds);
23
+ const drawn = run.reduced ? 1 : Math.min(1, run.elapsed / run.seconds);
24
+ if (run.elapsed < run.seconds)
25
+ return { drawn, fade: 0, done: false, moving: true };
26
+ if (run.after === "stay")
27
+ return { drawn: 1, fade: 0, done: false, moving: unsettled };
28
+ if (run.reduced)
29
+ return { drawn: 1, fade: 1, done: true, moving: true };
30
+ const fade = Math.min(1, (run.elapsed - run.seconds) / TRACE_FADE_SECONDS);
31
+ return { drawn: 1, fade, done: fade >= 1, moving: true };
32
+ }
33
+ /** Moves a hide on by `deltaSeconds` of real time; `drawn` is the share the trace had reached, which a hide holds. */
34
+ export function stepHide(run, deltaSeconds, drawn) {
35
+ run.elapsed += Math.max(0, deltaSeconds);
36
+ const share = run.seconds <= 0 ? 1 : Math.min(1, run.elapsed / run.seconds);
37
+ const fade = run.from + (1 - run.from) * share;
38
+ return { drawn, fade, done: share >= 1, moving: true };
39
+ }
@@ -17,3 +17,42 @@ export declare const MAX_ELEVATION_DEG = 89;
17
17
  export declare const wrapAzimuth: (deg: number) => number;
18
18
  /** Checks a view's fields, naming the offending one (`where` is its path, e.g. `look.startView`). Returns the view with the azimuth wrapped. */
19
19
  export declare function validateStartView(raw: unknown, where?: string): StartView;
20
+ /** The field of view a sky reading may carry, in degrees (a look-out camera's zoom). */
21
+ export declare const SKY_FOV_RANGE_DEG: {
22
+ readonly min: 5;
23
+ readonly max: 100;
24
+ };
25
+ /** The field of view a look-out opens at when none is given, in degrees. */
26
+ export declare const SKY_OPENING_FOV_DEG = 60;
27
+ /**
28
+ * A camera standing inside `lookOut` (a body's id) and looking out: `raDeg` and `decDeg` are where it points in J2000 equatorial degrees
29
+ * (right ascension 0 up to 360, declination within ±90), `fovDeg` the vertical field of view. Text and number checks only: no body is named here.
30
+ */
31
+ export interface SkyView {
32
+ readonly lookOut: string;
33
+ readonly raDeg: number;
34
+ readonly decDeg: number;
35
+ readonly fovDeg: number;
36
+ }
37
+ /** Either kind of camera reading: an orbit view (has `distance`) or a sky view (has `lookOut`). */
38
+ export type CameraView = StartView | SkyView;
39
+ /** True for a sky view: the one test that tells the two kinds apart. */
40
+ export declare function isSkyView(view: CameraView): view is SkyView;
41
+ /** The unit vector (J2000 equatorial axes) toward a right ascension and declination in degrees. */
42
+ export declare function eqjUnitVector(raDeg: number, decDeg: number): [number, number, number];
43
+ /** Checks a right ascension and declination, naming the offending field; returns the pair with the right ascension wrapped to 0 up to 360. */
44
+ export declare function validateSkyDirection(raDeg: unknown, decDeg: unknown, where: string): {
45
+ readonly raDeg: number;
46
+ readonly decDeg: number;
47
+ };
48
+ /** Checks a star-map position given as an object: exactly `raDeg` and `decDeg` (a half pair, an array or any other key is refused). Shared by `setCamera` and the opening `lookOut`. */
49
+ export declare function validateSkyPosition(raw: unknown, where: string): {
50
+ readonly raDeg: number;
51
+ readonly decDeg: number;
52
+ };
53
+ /** Checks a field of view in degrees against the range a look-out camera takes. */
54
+ export declare function validateSkyFov(fovDeg: unknown, where: string): number;
55
+ /** Checks a sky view's fields, naming the offending one. Returns the view with the right ascension wrapped. */
56
+ export declare function validateSkyView(raw: unknown, where?: string): SkyView;
57
+ /** Checks either kind of reading: one with `lookOut` is a sky view, anything else an orbit view. */
58
+ export declare function validateCameraView(raw: unknown, where?: string): CameraView;
@@ -26,3 +26,59 @@ export function validateStartView(raw, where = "startView") {
26
26
  throw new RangeError(`${where}.distance must be positive, got ${distance}`);
27
27
  return { focus: record.focus, azimuthDeg: wrapAzimuth(azimuthDeg), elevationDeg, distance };
28
28
  }
29
+ /** The field of view a sky reading may carry, in degrees (a look-out camera's zoom). */
30
+ export const SKY_FOV_RANGE_DEG = { min: 5, max: 100 };
31
+ /** The field of view a look-out opens at when none is given, in degrees. */
32
+ export const SKY_OPENING_FOV_DEG = 60;
33
+ /** True for a sky view: the one test that tells the two kinds apart. */
34
+ export function isSkyView(view) {
35
+ return "lookOut" in view;
36
+ }
37
+ /** The unit vector (J2000 equatorial axes) toward a right ascension and declination in degrees. */
38
+ export function eqjUnitVector(raDeg, decDeg) {
39
+ const [ra, dec] = [(raDeg * Math.PI) / 180, (decDeg * Math.PI) / 180];
40
+ return [Math.cos(dec) * Math.cos(ra), Math.cos(dec) * Math.sin(ra), Math.sin(dec)];
41
+ }
42
+ /** Checks a right ascension and declination, naming the offending field; returns the pair with the right ascension wrapped to 0 up to 360. */
43
+ export function validateSkyDirection(raDeg, decDeg, where) {
44
+ if (typeof raDeg !== "number" || !Number.isFinite(raDeg))
45
+ throw new RangeError(`${where}.raDeg must be a finite number, got ${String(raDeg)}`);
46
+ if (typeof decDeg !== "number" || !Number.isFinite(decDeg))
47
+ throw new RangeError(`${where}.decDeg must be a finite number, got ${String(decDeg)}`);
48
+ if (Math.abs(decDeg) > 90)
49
+ throw new RangeError(`${where}.decDeg must be within ±90, got ${decDeg}`);
50
+ return { raDeg: wrapAzimuth(raDeg), decDeg };
51
+ }
52
+ /** Checks a star-map position given as an object: exactly `raDeg` and `decDeg` (a half pair, an array or any other key is refused). Shared by `setCamera` and the opening `lookOut`. */
53
+ export function validateSkyPosition(raw, where) {
54
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw) || Object.keys(raw).some((key) => key !== "raDeg" && key !== "decDeg"))
55
+ throw new RangeError(`${where} must be { raDeg, decDeg }`);
56
+ const position = raw;
57
+ return validateSkyDirection(position.raDeg, position.decDeg, where);
58
+ }
59
+ /** Checks a field of view in degrees against the range a look-out camera takes. */
60
+ export function validateSkyFov(fovDeg, where) {
61
+ if (typeof fovDeg !== "number" || !(fovDeg >= SKY_FOV_RANGE_DEG.min && fovDeg <= SKY_FOV_RANGE_DEG.max)) {
62
+ throw new RangeError(`${where}.fovDeg must be a number from ${SKY_FOV_RANGE_DEG.min} to ${SKY_FOV_RANGE_DEG.max}, got ${String(fovDeg)}`);
63
+ }
64
+ return fovDeg;
65
+ }
66
+ /** Checks a sky view's fields, naming the offending one. Returns the view with the right ascension wrapped. */
67
+ export function validateSkyView(raw, where = "sky view") {
68
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw))
69
+ throw new RangeError(`${where} must be an object with lookOut, raDeg, decDeg and fovDeg`);
70
+ const record = raw;
71
+ for (const key of Object.keys(record)) {
72
+ if (!["lookOut", "raDeg", "decDeg", "fovDeg"].includes(key))
73
+ throw new RangeError(`${where}.${key} is not a sky view field`);
74
+ }
75
+ if (typeof record.lookOut !== "string" || record.lookOut === "")
76
+ throw new RangeError(`${where}.lookOut must be a non-empty id, got ${String(record.lookOut)}`);
77
+ const direction = validateSkyDirection(record.raDeg, record.decDeg, where);
78
+ return { lookOut: record.lookOut, ...direction, fovDeg: validateSkyFov(record.fovDeg, where) };
79
+ }
80
+ /** Checks either kind of reading: one with `lookOut` is a sky view, anything else an orbit view. */
81
+ export function validateCameraView(raw, where = "view") {
82
+ const isSky = typeof raw === "object" && raw !== null && "lookOut" in raw;
83
+ return isSky ? validateSkyView(raw, where) : validateStartView(raw, where);
84
+ }
@@ -1,7 +1,42 @@
1
1
  import { type Provenance } from "./provenance.js";
2
+ import type { StartView } from "./startView.js";
3
+ import type { SkyTraceAfter } from "./skyTrace.js";
2
4
  import type { TimeBounds } from "./trajectory.js";
5
+ /** A camera request a panel makes when it opens (checked): the same shapes the scene camera takes. A look-out `direction` that is absent keeps the direction already looked along (else right ascension 0, declination 0). */
6
+ export type PanelCameraRequest = {
7
+ readonly kind: "focus" | "follow";
8
+ readonly target: string;
9
+ } | {
10
+ readonly kind: "overview";
11
+ } | {
12
+ readonly kind: "hold";
13
+ } | {
14
+ readonly kind: "lookOut";
15
+ readonly body: string;
16
+ readonly direction?: readonly [number, number, number] | string;
17
+ readonly fovDeg?: number;
18
+ } | {
19
+ readonly kind: "pose";
20
+ readonly view: StartView;
21
+ };
22
+ /** What a panel does when it opens, in this order: the camera turns, its object is selected, its object's sky figure is traced. */
23
+ export interface PanelActions {
24
+ readonly camera?: PanelCameraRequest;
25
+ /** True: select the panel's `object`. */
26
+ readonly select?: true;
27
+ /** Trace the panel's `object`, a sky figure, this way. */
28
+ readonly trace?: {
29
+ readonly seconds: number;
30
+ readonly after: SkyTraceAfter;
31
+ };
32
+ }
33
+ /** The ids a camera request names: the bodies it points at, and the id a look-out turns toward (a body or a sky figure). */
34
+ export declare function cameraIdsOf(request: PanelCameraRequest): {
35
+ readonly bodies: readonly string[];
36
+ readonly toward?: string;
37
+ };
3
38
  /** One short story panel, resolved to a UTC time. */
4
- export interface StoryPanel {
39
+ export interface StoryPanel extends PanelActions {
5
40
  readonly id: string;
6
41
  readonly timeUtcMs: number;
7
42
  readonly title: string;
@@ -14,9 +49,17 @@ export interface StoryPanel {
14
49
  /** A shell object this panel is about; the scene draws a marker on it that reopens the panel. */
15
50
  readonly objectId?: string;
16
51
  }
52
+ /** A story step: a panel with no moment, shown in the order added with Back and Next. */
53
+ export type StoryStep = Omit<StoryPanel, "timeUtcMs"> & {
54
+ /** The step's place among the steps, counting from 1 in the order added. */
55
+ readonly step: number;
56
+ };
17
57
  /** The panels an experience offers, with the defaults of the two settings that govern them. */
18
58
  export interface StoryPanelSet {
59
+ /** The moment panels, sorted by time. */
19
60
  readonly panels: readonly StoryPanel[];
61
+ /** The steps, in the order added; absent or empty when there are none. */
62
+ readonly steps?: readonly StoryStep[];
20
63
  /** How long playback holds when a panel opens by itself, in seconds (0 never pauses). */
21
64
  readonly pauseSeconds: number;
22
65
  /** Whether panels open by themselves as forward playback reaches them. */
@@ -29,7 +72,8 @@ export type PanelPlayback = Pick<StoryPanelSet, "pauseSeconds" | "autoOpen">;
29
72
  export declare const DEFAULT_PANEL_PLAYBACK: PanelPlayback;
30
73
  /** A panel whose own shape is sound and whose moment is converted. What it names (an event, an anchor, an object) is left for `resolveStoryPanels`, because those may be added later. */
31
74
  export interface CheckedPanel extends Omit<StoryPanel, "timeUtcMs" | "objectId"> {
32
- readonly at: {
75
+ /** Absent: a step. */
76
+ readonly at?: {
33
77
  readonly timeUtcMs: number;
34
78
  } | {
35
79
  readonly event: string;
@@ -48,6 +92,8 @@ export interface PanelLookup {
48
92
  readonly anchors?: ReadonlyMap<string, number>;
49
93
  /** Ids a panel's `object` may name. Absent: any id is accepted. */
50
94
  readonly objectIds?: readonly string[];
95
+ /** The sky figures' ids: a panel's `object` may name one, and a look-out camera may turn toward one. Absent: none. */
96
+ readonly figureIds?: readonly string[];
51
97
  /** When given, every panel must fall inside it. */
52
98
  readonly window?: TimeBounds;
53
99
  }
@@ -59,5 +105,7 @@ export declare class StoryPanelError extends Error {
59
105
  export declare function checkStoryPanel(raw: unknown, index: number): CheckedPanel;
60
106
  /** Checks the two playback settings; a setting left out takes its default, so the result is the whole setting. */
61
107
  export declare function checkPanelPlayback(raw: unknown): PanelPlayback;
62
- /** Resolves each checked panel's time and links against the scene as built. Panels come back sorted by time. */
108
+ /** Resolves each checked panel's time and links against the scene as built. Moment panels come back sorted by time; steps (no `at`) in the order given, numbered from 1. */
63
109
  export declare function resolveStoryPanels(panels: readonly CheckedPanel[], playback: PanelPlayback, lookup: PanelLookup): StoryPanelSet;
110
+ /** The step Back or Next opens from `step`: the one `by` places along (-1 or 1), or undefined at either end. */
111
+ export declare function neighbourStep(steps: readonly StoryStep[], step: StoryStep, by: -1 | 1): StoryStep | undefined;
@@ -1,5 +1,15 @@
1
1
  import { createProvenance, PROVENANCE_SOURCE_TYPES } from "./provenance.js";
2
2
  import { timeInputMs } from "./timeInput.js";
3
+ /** The ids a camera request names: the bodies it points at, and the id a look-out turns toward (a body or a sky figure). */
4
+ export function cameraIdsOf(request) {
5
+ switch (request.kind) {
6
+ case "focus":
7
+ case "follow": return { bodies: [request.target] };
8
+ case "pose": return { bodies: [request.view.focus] };
9
+ case "lookOut": return typeof request.direction === "string" ? { bodies: [request.body], toward: request.direction } : { bodies: [request.body] };
10
+ default: return { bodies: [] };
11
+ }
12
+ }
3
13
  export const DEFAULT_PANEL_PAUSE_SECONDS = 6;
4
14
  export const MAX_PANEL_PAUSE_SECONDS = 20;
5
15
  export const DEFAULT_PANEL_PLAYBACK = Object.freeze({ pauseSeconds: DEFAULT_PANEL_PAUSE_SECONDS, autoOpen: true });
@@ -23,8 +33,10 @@ function lines(panel, field, value) {
23
33
  return list.map((line, index) => text(panel, `${field}[${index}]`, line));
24
34
  }
25
35
  function atOf(panel, at) {
36
+ if (at === undefined)
37
+ return undefined;
26
38
  if (!isRecord(at))
27
- throw new StoryPanelError(panel, "at", "must name a time: { time }, { event } or { anchor }");
39
+ throw new StoryPanelError(panel, "at", "must name a time ({ time }, { event } or { anchor }), or be left out for a step");
28
40
  const keys = ["time", "event", "anchor"].filter((key) => at[key] !== undefined);
29
41
  if (keys.length !== 1)
30
42
  throw new StoryPanelError(panel, "at", "must give exactly one of time, event or anchor");
@@ -56,9 +68,10 @@ export function checkStoryPanel(raw, index) {
56
68
  throw new StoryPanelError(`#${index + 1}`, "entry", "must be an object");
57
69
  const id = text(`#${index + 1}`, "id", raw.id);
58
70
  const object = raw.object === undefined ? undefined : text(id, "object", raw.object);
71
+ const at = atOf(id, raw.at);
59
72
  return {
60
73
  id,
61
- at: atOf(id, raw.at),
74
+ ...(at === undefined ? {} : { at }),
62
75
  title: text(id, "title", raw.title),
63
76
  body: lines(id, "body", raw.body),
64
77
  details: raw.details === undefined ? [] : lines(id, "details", raw.details),
@@ -79,7 +92,7 @@ export function checkPanelPlayback(raw) {
79
92
  throw new StoryPanelError("settings", "autoOpen", "must be true or false");
80
93
  return { pauseSeconds, autoOpen };
81
94
  }
82
- function timeOf({ id, at }, lookup) {
95
+ function timeOf(id, at, lookup) {
83
96
  if ("timeUtcMs" in at)
84
97
  return at.timeUtcMs;
85
98
  if ("event" in at) {
@@ -93,19 +106,46 @@ function timeOf({ id, at }, lookup) {
93
106
  throw new StoryPanelError(id, "at.anchor", `names "${at.anchor}", which the experience's anchors lack`);
94
107
  return anchor;
95
108
  }
109
+ function checkLinks({ id, object, camera, trace }, lookup) {
110
+ const figures = lookup.figureIds ?? [];
111
+ if (object !== undefined && lookup.objectIds !== undefined && !lookup.objectIds.includes(object) && !figures.includes(object)) {
112
+ throw new StoryPanelError(id, "object", `names "${object}", which the experience lacks`);
113
+ }
114
+ if (trace !== undefined && (object === undefined || !figures.includes(object))) {
115
+ throw new StoryPanelError(id, "trace", `needs an object that names a sky figure${object === undefined ? "" : `; "${object}" is not one`}`);
116
+ }
117
+ if (camera === undefined || lookup.objectIds === undefined)
118
+ return;
119
+ const { bodies, toward } = cameraIdsOf(camera);
120
+ for (const body of bodies)
121
+ if (!lookup.objectIds.includes(body))
122
+ throw new StoryPanelError(id, "camera", `names "${body}", which is not an object the experience shows`);
123
+ if (toward !== undefined && !lookup.objectIds.includes(toward) && !figures.includes(toward))
124
+ throw new StoryPanelError(id, "camera", `turns toward "${toward}", which is neither an object nor a sky figure the experience has`);
125
+ }
126
+ /** The actions a panel carries, in the order they apply. */
127
+ const actionsOf = ({ camera, select, trace }) => ({ ...(camera === undefined ? {} : { camera }), ...(select === undefined ? {} : { select }), ...(trace === undefined ? {} : { trace }) });
96
128
  function resolvePanel(panel, lookup) {
97
- const { id, title, body, details, provenance, object } = panel;
98
- const timeUtcMs = timeOf(panel, lookup);
129
+ const { id, at, title, body, details, provenance, object } = panel;
130
+ const timeUtcMs = timeOf(id, at, lookup);
99
131
  if (lookup.window !== undefined && (timeUtcMs < lookup.window.startUtcMs || timeUtcMs > lookup.window.endUtcMs)) {
100
132
  throw new StoryPanelError(id, "at", "falls outside the timeline window");
101
133
  }
102
- if (object !== undefined && lookup.objectIds !== undefined && !lookup.objectIds.includes(object)) {
103
- throw new StoryPanelError(id, "object", `names "${object}", which the experience lacks`);
104
- }
105
- return { id, timeUtcMs, title, body, details, provenance, ...(object === undefined ? {} : { objectId: object }) };
134
+ checkLinks(panel, lookup);
135
+ return { id, timeUtcMs, title, body, details, provenance, ...(object === undefined ? {} : { objectId: object }), ...actionsOf(panel) };
106
136
  }
107
- /** Resolves each checked panel's time and links against the scene as built. Panels come back sorted by time. */
137
+ function resolveStep(panel, lookup, step) {
138
+ const { id, title, body, details, provenance, object } = panel;
139
+ checkLinks(panel, lookup);
140
+ return { id, step, title, body, details, provenance, ...(object === undefined ? {} : { objectId: object }), ...actionsOf(panel) };
141
+ }
142
+ /** Resolves each checked panel's time and links against the scene as built. Moment panels come back sorted by time; steps (no `at`) in the order given, numbered from 1. */
108
143
  export function resolveStoryPanels(panels, playback, lookup) {
109
- const resolved = panels.map((panel) => resolvePanel(panel, lookup));
110
- return { panels: resolved.sort((a, b) => a.timeUtcMs - b.timeUtcMs), ...playback };
144
+ const moments = panels.flatMap((panel) => (panel.at === undefined ? [] : [resolvePanel({ ...panel, at: panel.at }, lookup)]));
145
+ const steps = panels.filter((panel) => panel.at === undefined).map((panel, index) => resolveStep(panel, lookup, index + 1));
146
+ return { panels: moments.sort((a, b) => a.timeUtcMs - b.timeUtcMs), ...(steps.length === 0 ? {} : { steps }), ...playback };
147
+ }
148
+ /** The step Back or Next opens from `step`: the one `by` places along (-1 or 1), or undefined at either end. */
149
+ export function neighbourStep(steps, step, by) {
150
+ return steps.find((candidate) => candidate.step === step.step + by);
111
151
  }
@@ -1,8 +1,8 @@
1
1
  import { type ReactNode } from "react";
2
2
  import type { ClockSnapshot } from "../core/clock.js";
3
- import { type StoryPanelSettings } from "./useStoryPanels.js";
3
+ import { type PanelCause, type StoryPanelSettings } from "./useStoryPanels.js";
4
4
  import type { TimelineGlowLook } from "./timelineGlow.js";
5
- import type { ExperienceCameraPreset, ExperienceConfig } from "./experience.js";
5
+ import { type ExperienceCameraPreset, type ExperienceConfig } from "./experience.js";
6
6
  import type { Metric } from "./metrics.js";
7
7
  import { type PhoneLayoutSettings } from "./phoneLayout.js";
8
8
  import type { DisplaySwitchItem, ViewChoice } from "./DisplaySwitches.js";
@@ -28,6 +28,8 @@ interface Props {
28
28
  readonly paceAuto?: boolean | undefined;
29
29
  readonly onSeek: (timeUtcMs: number) => void;
30
30
  readonly onCameraRequest: (request: ExperienceCameraPreset["request"]) => void;
31
+ /** Turns the camera toward a sky figure, only while it looks out (an event naming a figure: Go to); the app decides, so an orbiting camera is left alone. */
32
+ readonly onTurnToFigure?: (id: string) => void;
31
33
  /** Holds the camera where it is, its target fixed in the scene (a view's `stay` rule); a later camera request replaces it. */
32
34
  readonly onCameraHold?: () => void;
33
35
  /** True when the host has set the camera since the last view switch: that call answers the switch, so the view's own camera rule does not replace it. */
@@ -62,6 +64,11 @@ interface Props {
62
64
  readonly timelineGlow?: TimelineGlowLook;
63
65
  /** The phone layout's live numbers (drawer heights, animation, swipe distance); absent: the defaults. */
64
66
  readonly phoneLayout?: PhoneLayoutSettings;
67
+ /** The font and size of every label (the look `labels`), carried to them as CSS variables on the root; absent: the stylesheet's own. */
68
+ readonly labelStyle?: {
69
+ readonly fontFamily: string;
70
+ readonly sizePx: number;
71
+ };
65
72
  /** The family of moons lit up in the scene now (the moon panel's choice), or null; the app draws it. */
66
73
  readonly highlightedFamily?: string | null;
67
74
  readonly onHighlightFamily?: (familyId: string | null) => void;
@@ -70,10 +77,11 @@ interface Props {
70
77
  /** Asks the shell to open a panel (a scene marker was pressed); a new `serial` asks again. */
71
78
  readonly panelRequest?: {
72
79
  readonly id: string;
73
- readonly serial: number;
80
+ readonly serial: number; /** True: the host's `setPanel` (id "" closes the open panel). */
81
+ readonly host?: boolean;
74
82
  } | null;
75
- /** Called when the open panel changes, so the app can mark its scene marker. */
76
- readonly onOpenPanelChange?: (panelId: string | null) => void;
83
+ /** Called when the open panel changes, with who changed it, so the app can mark its scene marker and tell the host. */
84
+ readonly onOpenPanelChange?: (panelId: string | null, cause: PanelCause) => void;
77
85
  /** Asks the shell to open a tagged place's information (a place marker was pressed); a new `serial` asks again. */
78
86
  readonly featureRequest?: {
79
87
  readonly key: string;
@@ -86,6 +94,7 @@ interface Props {
86
94
  readonly selectRequest?: {
87
95
  readonly id: string;
88
96
  readonly serial: number;
97
+ readonly quiet?: boolean;
89
98
  } | null;
90
99
  readonly onSelectRequestApplied?: () => void;
91
100
  readonly pickRequest?: {
@@ -95,5 +104,5 @@ interface Props {
95
104
  readonly children: ReactNode;
96
105
  }
97
106
  /** Canvas-first layout shared by astronomy experiences. Scene and diagnostics stay app-owned. */
98
- export declare function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onCameraHold, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout, highlightedFamily, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }: Props): import("react").JSX.Element;
107
+ export declare function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onTurnToFigure, onCameraHold, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout, labelStyle, highlightedFamily, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }: Props): import("react").JSX.Element;
99
108
  export {};