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
@@ -79,7 +79,7 @@ export function useOverlayLayers(canvas, controls, trackedViews, bodySetViews, s
79
79
  export function useScenePointer(canvas, runtime, controls, catalogue, orbit, state) {
80
80
  useEffect(() => {
81
81
  const limits = () => focusLimits(bodyIdOf(runtime, catalogue, orbit.current.focus) ?? orbit.current.focus, { centre: runtime.sceneCenter, span: state.current.spanScaled, bodies: catalogue }, controls.policy, liveReach(runtime.cameraReach, controls.policy, canvas.clientHeight > 0 ? canvas.clientWidth / canvas.clientHeight : 1));
82
- return attachScenePointer(canvas, orbit.current, state.current, limits, (id) => controls.onPickObject?.(id));
82
+ return attachScenePointer(canvas, orbit.current, state.current, limits, (id, options) => (options === undefined ? controls.onPickObject?.(id) : controls.onPickObject?.(id, options)));
83
83
  // eslint-disable-next-line react-hooks/exhaustive-deps
84
84
  }, [canvas, controls]);
85
85
  }
@@ -131,8 +131,11 @@ export interface CameraStep {
131
131
  export declare function viewUpOf(ctx: Pick<FrameContext, "runtime" | "controls">): RenderVector;
132
132
  /** A frame is drawn only once every body's group and orientation node is mounted. */
133
133
  export declare function bodiesMounted(runtime: SceneRuntime, refs: BodyRefs): boolean;
134
- /** Stage 0: the time of this frame; looping playback wraps inside its window first, and other playback stops on the window's edge (a scene with a timeline bar). */
135
- export declare function frameTime(runtime: SceneRuntime, controls: Pick<SceneControls, "loop" | "paceAuto" | "pace">): number;
134
+ /**
135
+ * Stage 0: the time of this frame. While pacing is in charge the clock is first stepped through the frame's real time under the paced rate (so no frame passes over a slow-down); looping playback then wraps inside its window,
136
+ * and other playback stops on the window's edge (a scene with a timeline bar). A wrap or stop lands on the paced rate for its new time at once.
137
+ */
138
+ export declare function frameTime(runtime: SceneRuntime, controls: Pick<SceneControls, "loop" | "paceAuto" | "pace">, nowMs?: number): number;
136
139
  /** Stage 1: brings every view to the time of the frame. Returns the live body-set look. */
137
140
  export declare function syncViews(ctx: FrameContext, t: number): BodySetLook;
138
141
  /** Stage 2: places the composition about the scene centre and keeps the camera's framing when the scale policy changed. */
@@ -149,12 +152,18 @@ export declare function placeSkyFigures(ctx: FrameContext): void;
149
152
  export declare function advanceSkyTraces(ctx: FrameContext): void;
150
153
  /** Stage 5: places every view about the floating origin and publishes the views' readouts. Returns the hover brightness gain. */
151
154
  export declare function placeViews(ctx: FrameContext, t: number, placed: PlacedScene, setLook: BodySetLook): number;
152
- /** What this frame hides: the view's hidden ids, and the body the camera stands inside while looking out (the one hidden-set path, read by the visibility, label and tap stages). */
153
- export declare function hiddenOf(ctx: Pick<FrameContext, "controls" | "orbit">): ViewHidden | undefined;
155
+ /** What this frame hides: the view's hidden ids, the objects not shown at clock time `t` (`shownDuring`; none when `t` is not given), and the body the camera stands inside while looking out (the one hidden-set path, read by the visibility, label and tap stages). */
156
+ export declare function hiddenOf(ctx: Pick<FrameContext, "controls" | "orbit">, t?: number): ViewHidden | undefined;
154
157
  /** Stage 5b: shows or hides each drawn group by the current view's hidden ids (bodies, paths, point groups, body sets). One set, read here; nothing is rebuilt. */
155
- export declare function applyViewVisibility(ctx: FrameContext): void;
158
+ export declare function applyViewVisibility(ctx: FrameContext, t?: number): void;
156
159
  /** A mounted body's drawn sphere and radius for the feature markers, or null when the body is not drawn as a sphere. */
157
160
  export declare function featureHostOf(assets: readonly BodyAsset[], parts: ReadonlyMap<BodyId, BodyParts>, id: string, policy: ScalePolicy): FeatureHost | null;
161
+ /** What the labels and taps see under the current view: the objects and body sets it shows, and the label-hidden ids with the view's own added. Allocates only when a view hides something. */
162
+ export declare function shownUnderView(ctx: FrameContext, t?: number): {
163
+ objects: readonly import("../shell/experience.js").ExperienceObject[];
164
+ bodySetViews: import("./BodySetView.js").BodySetView[];
165
+ hiddenLabels: Set<string> | undefined;
166
+ };
158
167
  /** Stage 6: updates the overlay layers (names, story and feature markers) and rebuilds what a tap or hover can pick. */
159
168
  export declare function updateOverlays(ctx: FrameContext, t: number, step: CameraStep, hoverGain: number): void;
160
169
  /** Stage 7: places each body's light and builds the frame readout the shell reads. */
@@ -1,6 +1,6 @@
1
1
  import { drawnRadii } from "./bodyDraw.js";
2
2
  import { DEFAULT_BODY_SET_LOOK, familyColorOf } from "./bodySet.js";
3
- import { applyPacing } from "../core/pacing.js";
3
+ import { applyPacing, stepPacing } from "../core/pacing.js";
4
4
  import { poseCamera, resolveCamera } from "./CameraController.js";
5
5
  import { DEFAULT_CAMERA_FAR } from "./experienceDefinition.js";
6
6
  import { DEFAULT_FEATURE_MIN_BODY_PX } from "./FeatureMarkers.js";
@@ -15,7 +15,7 @@ import { clampHoverBrightness, HOVER_BRIGHTNESS_DEFAULT, hoverTarget, pickCandid
15
15
  import { updateSky } from "./sceneSky.js";
16
16
  import { labelPositionOf } from "./sceneTargets.js";
17
17
  import { skyViewOf } from "./lookOut.js";
18
- import { hiddenWithLookOut } from "./viewHiding.js";
18
+ import { hiddenWithLookOut, hiddenWithShownSpans } from "./viewHiding.js";
19
19
  import { viewFromAngles } from "./viewLink.js";
20
20
  import { EQUATORIAL_UP } from "./viewUp.js";
21
21
  import { prefersReducedMotion } from "./skyFigures.js";
@@ -36,14 +36,24 @@ export function viewUpOf(ctx) {
36
36
  export function bodiesMounted(runtime, refs) {
37
37
  return runtime.bodies.every((id) => refs.groups.has(id) && refs.orients.has(id));
38
38
  }
39
- /** Stage 0: the time of this frame; looping playback wraps inside its window first, and other playback stops on the window's edge (a scene with a timeline bar). */
40
- export function frameTime(runtime, controls) {
39
+ /**
40
+ * Stage 0: the time of this frame. While pacing is in charge the clock is first stepped through the frame's real time under the paced rate (so no frame passes over a slow-down); looping playback then wraps inside its window,
41
+ * and other playback stops on the window's edge (a scene with a timeline bar). A wrap or stop lands on the paced rate for its new time at once.
42
+ */
43
+ export function frameTime(runtime, controls, nowMs = performance.now()) {
44
+ const paced = controls.paceAuto === true && runtime.pacing !== undefined;
45
+ if (paced && controls.pace !== undefined)
46
+ stepPacing(runtime.clock, runtime.pacing, controls.pace, nowMs);
47
+ let moved = false;
41
48
  if (controls.loop === true && runtime.loopWindow !== undefined)
42
- runtime.clock.wrapWithin(runtime.loopWindow);
49
+ moved = runtime.clock.wrapWithin(runtime.loopWindow);
43
50
  else if (runtime.stopAtWindow === true && runtime.loopWindow !== undefined)
44
- runtime.clock.stopWithin(runtime.loopWindow);
45
- if (controls.paceAuto === true && runtime.pacing !== undefined)
46
- applyPacing(runtime.clock, runtime.pacing, controls.pace);
51
+ moved = runtime.clock.stopWithin(runtime.loopWindow);
52
+ if (paced && (moved || controls.pace === undefined)) {
53
+ if (controls.pace !== undefined)
54
+ delete controls.pace.last;
55
+ applyPacing(runtime.clock, runtime.pacing, controls.pace, nowMs);
56
+ }
47
57
  return runtime.clock.now();
48
58
  }
49
59
  /** Stage 1: brings every view to the time of the frame. Returns the live body-set look. */
@@ -105,7 +115,7 @@ export function stepAndPoseCamera(ctx, t, placed) {
105
115
  const reach = liveReach(runtime.cameraReach, policy, camera.aspect);
106
116
  const focusBody = stepCameraTarget({ camState: orbit, controls, targets, frame, catalogue, reach, fovDeg: orbit.lookOut === null ? camera.fov : CAMERA_FOV_DEG, viewUp, firstFrame, previousUp: state.lastUp });
107
117
  state.lastUp = viewUp;
108
- resolveCamera(orbit, cameraTargetAbsolute(orbit, targets), ctx.origin, ctx.delta, REBASE_THRESHOLD, viewUp);
118
+ resolveCamera(orbit, cameraTargetAbsolute(orbit, targets), ctx.origin, ctx.delta, REBASE_THRESHOLD, viewUp, prefersReducedMotion());
109
119
  placeBodies(ctx.assets, placed.composed.states, ctx.bodyRefs, policy, ctx.origin);
110
120
  const baseFar = reach.far ?? DEFAULT_CAMERA_FAR;
111
121
  // Looking out, the camera stands at a body, so a far plane sized for orbit framing could cut off the Sun or any body beyond it: reach everything placed.
@@ -154,8 +164,8 @@ export function advanceSkyTraces(ctx) {
154
164
  for (const request of controls.skyTraces.splice(0)) {
155
165
  if ("after" in request)
156
166
  views.skyFiguresView.startTrace(request);
157
- else
158
- views.skyFiguresView.clearTrace(request);
167
+ else if (views.skyFiguresView.clearTrace(request))
168
+ state.wakes += 1;
159
169
  }
160
170
  if (views.skyFiguresView.advanceTraces(delta, controls.skyColours, controls.skyLines, controls.selectedObjectId))
161
171
  state.wakes += 1;
@@ -188,13 +198,13 @@ export function placeViews(ctx, t, placed, setLook) {
188
198
  publishPointsData(canvas, views.groupViews, camera, views.bodySetViews);
189
199
  return hoverGain;
190
200
  }
191
- /** What this frame hides: the view's hidden ids, and the body the camera stands inside while looking out (the one hidden-set path, read by the visibility, label and tap stages). */
192
- export function hiddenOf(ctx) {
193
- return hiddenWithLookOut(ctx.controls.viewHidden, ctx.orbit.lookOut === null ? null : ctx.orbit.focus);
201
+ /** What this frame hides: the view's hidden ids, the objects not shown at clock time `t` (`shownDuring`; none when `t` is not given), and the body the camera stands inside while looking out (the one hidden-set path, read by the visibility, label and tap stages). */
202
+ export function hiddenOf(ctx, t) {
203
+ return hiddenWithLookOut(hiddenWithShownSpans(ctx.controls.viewHidden, ctx.controls.labelObjects, t), ctx.orbit.lookOut === null ? null : ctx.orbit.focus);
194
204
  }
195
205
  /** Stage 5b: shows or hides each drawn group by the current view's hidden ids (bodies, paths, point groups, body sets). One set, read here; nothing is rebuilt. */
196
- export function applyViewVisibility(ctx) {
197
- const hidden = hiddenOf(ctx)?.objects;
206
+ export function applyViewVisibility(ctx, t) {
207
+ const hidden = hiddenOf(ctx, t)?.objects;
198
208
  const { views, bodyRefs } = ctx;
199
209
  const show = (id, group) => { group.visible = hidden?.has(id) !== true; };
200
210
  for (const [id, group] of bodyRefs.groups)
@@ -221,9 +231,9 @@ export function featureHostOf(assets, parts, id, policy) {
221
231
  return sphere === undefined || asset === undefined ? null : { sphere, radius: drawnRadii(asset.definition, policy).equatorial };
222
232
  }
223
233
  /** What the labels and taps see under the current view: the objects and body sets it shows, and the label-hidden ids with the view's own added. Allocates only when a view hides something. */
224
- function shownUnderView(ctx) {
234
+ export function shownUnderView(ctx, t) {
225
235
  const { controls, views } = ctx;
226
- const hidden = hiddenOf(ctx)?.objects;
236
+ const hidden = hiddenOf(ctx, t)?.objects;
227
237
  if (hidden === undefined || hidden.size === 0)
228
238
  return { objects: controls.labelObjects, bodySetViews: views.bodySetViews, hiddenLabels: controls.hiddenLabels };
229
239
  return {
@@ -239,7 +249,7 @@ export function updateOverlays(ctx, t, step, hoverGain) {
239
249
  publishBodyData(canvas, bodyScreens);
240
250
  layers.anchorLabels.current?.update(controls.showAnchorLabels, camera, size.width, size.height);
241
251
  const positionFor = (id) => labelPositionOf(step.targets, id);
242
- const shown = shownUnderView(ctx);
252
+ const shown = shownUnderView(ctx, t);
243
253
  layers.sceneLabels.current?.update(positionFor, camera, size.width, size.height, origin, controls.selectedObjectId, shown.hiddenLabels, { on: controls.skyLines, labelColor: controls.skyColours.label, selectedColor: controls.skyColours.selected, opacity: (id) => ctx.views.skyFiguresView.labelOpacity(id), distance: 0.5 * (camera.near + camera.far) });
244
254
  state.pickables = pickCandidatesOf({ objects: shown.objects, bodyIdFor: ctx.bodyIdFor, bodyScreens, widthPx: size.width, heightPx: size.height, labelRects: layers.sceneLabels.current?.shownRects, canvas, bodySetViews: shown.bodySetViews });
245
255
  // Sky figures are projected only when a tap asks, from this frame's camera and shown names (no per-frame work).
@@ -248,7 +258,7 @@ export function updateOverlays(ctx, t, step, hoverGain) {
248
258
  canvas.style.cursor = hover === null ? "" : "pointer";
249
259
  canvas.dataset.pickHover = hover ?? "";
250
260
  layers.sceneLabels.current?.setHover(hover, hoverGain);
251
- layers.storyMarkers.current?.update(positionFor, camera, size.width, size.height, origin, controls.openStoryPanelId ?? null, t, hiddenOf(ctx));
261
+ layers.storyMarkers.current?.update(positionFor, camera, size.width, size.height, origin, controls.openStoryPanelId ?? null, t, hiddenOf(ctx, t));
252
262
  const featureReadout = layers.featureMarkers.current?.update((id) => featureHostOf(ctx.assets, ctx.bodyRefs.parts, id, controls.policy), camera, camera.fov, size.width, size.height, controls.openFeatureKey ?? null, controls.featureMinBodyPx ?? DEFAULT_FEATURE_MIN_BODY_PX);
253
263
  if (featureReadout !== null && featureReadout !== undefined)
254
264
  canvas.dataset.featureMarkers = JSON.stringify(featureReadout);
@@ -346,7 +356,7 @@ export function runFrame(ctx) {
346
356
  publishCanvasReadouts(ctx);
347
357
  placeSkyFigures(ctx);
348
358
  advanceSkyTraces(ctx);
349
- applyViewVisibility(ctx);
359
+ applyViewVisibility(ctx, t);
350
360
  const hoverGain = placeViews(ctx, t, placed, setLook);
351
361
  updateOverlays(ctx, t, step, hoverGain);
352
362
  placeLightsAndReadout(ctx, t, placed);
@@ -1,5 +1,9 @@
1
1
  import { type DistanceLimits, type OrbitCameraState } from "./CameraController.js";
2
2
  import { type PickCandidate, type SkyPickFigure } from "./scenePicking.js";
3
+ /** `keepSky`: the tap came from a look-out camera, so the shell selects a body without flying away from the sky. */
4
+ export interface PickOptions {
5
+ readonly keepSky?: boolean;
6
+ }
3
7
  /** The slice of the frame state the pointer listeners read and write. */
4
8
  export interface PointerState {
5
9
  readonly pickables: readonly PickCandidate[];
@@ -14,4 +18,4 @@ export interface PointerState {
14
18
  * Wires orbit gestures, the mouse hover point and tap picking to the canvas. `state` is read live (the frame rebuilds `pickables`);
15
19
  * returns the detach function, which also clears the cursor and the hover readout.
16
20
  */
17
- export declare function attachScenePointer(canvas: HTMLCanvasElement, orbit: OrbitCameraState, state: PointerState, limits: () => DistanceLimits, onPickObject: ((id: string) => void) | undefined): () => void;
21
+ export declare function attachScenePointer(canvas: HTMLCanvasElement, orbit: OrbitCameraState, state: PointerState, limits: () => DistanceLimits, onPickObject: ((id: string, options?: PickOptions) => void) | undefined): () => void;
@@ -7,12 +7,17 @@ import { pickSkyFigure, pickTarget } from "./scenePicking.js";
7
7
  */
8
8
  export function attachScenePointer(canvas, orbit, state, limits, onPickObject) {
9
9
  const onTap = (x, y, pointer) => {
10
- // Bodies first: a body hit wins over any sky figure behind it.
11
- const id = pickTarget(state.pickables, x, y, pointer) ?? pickSkyFigure(state.skyFigures?.() ?? [], x, y);
10
+ // Orbiting, bodies first: a body hit wins over any sky figure behind it. Looking out the sky is the subject, so a figure's name or line wins and a body pick keeps the sky view.
11
+ const lookingOut = orbit.lookOut !== null;
12
+ const figure = () => pickSkyFigure(state.skyFigures?.() ?? [], x, y);
13
+ const id = lookingOut ? figure() ?? pickTarget(state.pickables, x, y, pointer) : pickTarget(state.pickables, x, y, pointer) ?? figure();
12
14
  if (id === null)
13
15
  return;
14
16
  canvas.dataset.pickTarget = id;
15
- onPickObject?.(id);
17
+ if (lookingOut)
18
+ onPickObject?.(id, { keepSky: true });
19
+ else
20
+ onPickObject?.(id);
16
21
  };
17
22
  const onHoverMove = (event) => {
18
23
  if (event.pointerType !== "mouse") {
@@ -0,0 +1,7 @@
1
+ import { DEFAULT_TIME_LOOK, type TimeLook } from "../shell/timelineModel.js";
2
+ export { DEFAULT_TIME_LOOK };
3
+ export type { TimeLook };
4
+ /** The time look in force: the look's `time`, every part not named at its default. */
5
+ export declare function timeLookOf(look: {
6
+ readonly time?: Partial<TimeLook>;
7
+ }): TimeLook;
@@ -0,0 +1,8 @@
1
+ // The zone and precision of the viewer's times: one look for every visitor-facing time (clock bar, slider text, bound dates, event list, event and window cards). It reaches them as a prop
2
+ // of the shell, with no address parameter, the way the label style does (T-316).
3
+ import { DEFAULT_TIME_LOOK } from "../shell/timelineModel.js";
4
+ export { DEFAULT_TIME_LOOK };
5
+ /** The time look in force: the look's `time`, every part not named at its default. */
6
+ export function timeLookOf(look) {
7
+ return { ...DEFAULT_TIME_LOOK, ...look.time };
8
+ }
@@ -1,4 +1,4 @@
1
- import type { ExperienceConfig } from "../shell/experience.js";
1
+ import type { ExperienceConfig, ExperienceObject } from "../shell/experience.js";
2
2
  import type { ResolvedView, ViewSettings } from "./views.js";
3
3
  /** The ids the current view hides: objects (bodies, paths, groups) and story panels. Empty sets: everything shows. */
4
4
  export interface ViewHidden {
@@ -13,3 +13,10 @@ export declare function hiddenByView(settings: ViewSettings | undefined, view: R
13
13
  export declare function experienceInView(experience: ExperienceConfig, settings: ViewSettings | undefined, view: ResolvedView | undefined): ExperienceConfig;
14
14
  /** `hidden` with the body the camera stands inside added while it looks out. The same object when nothing is added, so a normal frame allocates nothing. */
15
15
  export declare function hiddenWithLookOut(hidden: ViewHidden | undefined, body: string | null): ViewHidden | undefined;
16
+ /** Whether `object` is shown at `timeUtcMs`: `startUtcMs <= t < endUtcMs`, an absent end unbounded, no span always shown (`shownDuring`). The one rule, so an object that ends at T and one that starts at T never both show or both hide. */
17
+ export declare function shownAt(object: Pick<ExperienceObject, "shownDuring">, timeUtcMs: number): boolean;
18
+ /**
19
+ * `hidden` with every object not shown at `timeUtcMs` added, and what belongs to one (`partOf`: a body's orbit line) with it. The same object when no object has a span or
20
+ * every span shows, so a frame without `shownDuring` allocates nothing. The one place the time-aware hidden set is built; the frame's `hiddenOf` calls it.
21
+ */
22
+ export declare function hiddenWithShownSpans(hidden: ViewHidden | undefined, objects: readonly ExperienceObject[] | undefined, timeUtcMs: number | undefined): ViewHidden | undefined;
@@ -41,3 +41,26 @@ export function hiddenWithLookOut(hidden, body) {
41
41
  return hidden;
42
42
  return { objects: new Set([...(hidden?.objects ?? []), body]), panels: hidden?.panels ?? new Set() };
43
43
  }
44
+ /** Whether `object` is shown at `timeUtcMs`: `startUtcMs <= t < endUtcMs`, an absent end unbounded, no span always shown (`shownDuring`). The one rule, so an object that ends at T and one that starts at T never both show or both hide. */
45
+ export function shownAt(object, timeUtcMs) {
46
+ const span = object.shownDuring;
47
+ return span === undefined || ((span.startUtcMs === undefined || span.startUtcMs <= timeUtcMs) && (span.endUtcMs === undefined || timeUtcMs < span.endUtcMs));
48
+ }
49
+ /**
50
+ * `hidden` with every object not shown at `timeUtcMs` added, and what belongs to one (`partOf`: a body's orbit line) with it. The same object when no object has a span or
51
+ * every span shows, so a frame without `shownDuring` allocates nothing. The one place the time-aware hidden set is built; the frame's `hiddenOf` calls it.
52
+ */
53
+ export function hiddenWithShownSpans(hidden, objects, timeUtcMs) {
54
+ if (objects === undefined || timeUtcMs === undefined)
55
+ return hidden;
56
+ let ids;
57
+ for (const object of objects)
58
+ if (!shownAt(object, timeUtcMs))
59
+ (ids ??= new Set(hidden?.objects)).add(object.id);
60
+ if (ids === undefined)
61
+ return hidden;
62
+ for (const object of objects)
63
+ if (object.partOf !== undefined && ids.has(object.partOf))
64
+ ids.add(object.id);
65
+ return { objects: ids, panels: hidden?.panels ?? new Set() };
66
+ }
package/src/core/clock.js CHANGED
@@ -81,8 +81,9 @@ export class SimulationClock {
81
81
  const now = this.now();
82
82
  if (now >= window.startUtcMs && now <= window.endUtcMs)
83
83
  return false;
84
- this.seek(now > window.endUtcMs ? window.endUtcMs : window.startUtcMs);
84
+ // Pause first: a seek while playing re-anchors on a second monotonic read, so pausing after it would carry the time past the edge.
85
85
  this.pause();
86
+ this.seek(now > window.endUtcMs ? window.endUtcMs : window.startUtcMs);
86
87
  return true;
87
88
  }
88
89
  setRate(rate) {
@@ -1,5 +1,10 @@
1
1
  /** True for a hex colour, a comma-form `rgb()`, `rgba()`, `hsl()` or `hsla()` or a named colour. */
2
2
  export declare function isCssColour(value: unknown): value is string;
3
+ /** A CSS colour split into its opaque part (what the drawing library can take) and its alpha, 0 to 1 (1 for a colour with none): `#rrggbbaa`, `#rgba`, `rgba()` and `hsla()` carry one. The drawing library ignores an alpha in a colour, so a line multiplies it into its opacity. */
4
+ export declare function splitColourAlpha(colour: string): {
5
+ readonly colour: string;
6
+ readonly alpha: number;
7
+ };
3
8
  /** True for a non-blank font family text (any CSS font-family list, or `inherit`). */
4
9
  export declare function isFontFamily(value: unknown): value is string;
5
10
  /** Label size range in pixels: small enough for a crowded sky, large enough to read on a phone. */
@@ -7,3 +12,11 @@ export declare const LABEL_SIZE_LIMITS: Readonly<{
7
12
  min: 8;
8
13
  max: 24;
9
14
  }>;
15
+ /** The precisions a time can be shown to. */
16
+ export declare const TIME_PRECISIONS: readonly ["day", "minute", "second"];
17
+ /** How precisely a time reads: `"day"`, `"minute"` or `"second"`. */
18
+ export type TimePrecision = (typeof TIME_PRECISIONS)[number];
19
+ /** True for a time precision name. */
20
+ export declare function isTimePrecision(value: unknown): value is TimePrecision;
21
+ /** True for a zone the time look takes: `"UTC"`, `"local"` (the visitor's own) or an IANA name the runtime's `Intl` accepts. */
22
+ export declare function isTimeZone(value: unknown): value is string;
@@ -16,9 +16,48 @@ export function isCssColour(value) {
16
16
  const text = value.trim();
17
17
  return HEX.test(text) || FUNCTION.test(text) || NAMED.has(text.toLowerCase());
18
18
  }
19
+ const FUNCTION_PARTS = /^(rgb|hsl)a?\(\s*([\d.]+%?)\s*,\s*([\d.]+%?)\s*,\s*([\d.]+%?)\s*(?:,\s*([\d.]+%?)\s*)?\)$/i;
20
+ function alphaOf(text) {
21
+ if (text === undefined)
22
+ return 1;
23
+ const value = text.endsWith("%") ? Number.parseFloat(text) / 100 : Number.parseFloat(text);
24
+ return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 1;
25
+ }
26
+ /** A CSS colour split into its opaque part (what the drawing library can take) and its alpha, 0 to 1 (1 for a colour with none): `#rrggbbaa`, `#rgba`, `rgba()` and `hsla()` carry one. The drawing library ignores an alpha in a colour, so a line multiplies it into its opacity. */
27
+ export function splitColourAlpha(colour) {
28
+ const text = colour.trim();
29
+ if (/^#[0-9a-f]{4}$/i.test(text))
30
+ return { colour: `#${text[1]}${text[2]}${text[3]}`, alpha: Number.parseInt(text[4] + text[4], 16) / 255 };
31
+ if (/^#[0-9a-f]{8}$/i.test(text))
32
+ return { colour: text.slice(0, 7), alpha: Number.parseInt(text.slice(7), 16) / 255 };
33
+ const parts = FUNCTION_PARTS.exec(text);
34
+ if (parts === null || parts[5] === undefined)
35
+ return { colour: text, alpha: 1 };
36
+ return { colour: `${parts[1].toLowerCase()}(${parts[2]}, ${parts[3]}, ${parts[4]})`, alpha: alphaOf(parts[5]) };
37
+ }
19
38
  /** True for a non-blank font family text (any CSS font-family list, or `inherit`). */
20
39
  export function isFontFamily(value) {
21
40
  return typeof value === "string" && value.trim() !== "" && !/[;{}]/.test(value);
22
41
  }
23
42
  /** Label size range in pixels: small enough for a crowded sky, large enough to read on a phone. */
24
43
  export const LABEL_SIZE_LIMITS = Object.freeze({ min: 8, max: 24 });
44
+ /** The precisions a time can be shown to. */
45
+ export const TIME_PRECISIONS = Object.freeze(["day", "minute", "second"]);
46
+ /** True for a time precision name. */
47
+ export function isTimePrecision(value) {
48
+ return typeof value === "string" && TIME_PRECISIONS.includes(value);
49
+ }
50
+ /** True for a zone the time look takes: `"UTC"`, `"local"` (the visitor's own) or an IANA name the runtime's `Intl` accepts. */
51
+ export function isTimeZone(value) {
52
+ if (typeof value !== "string" || value.trim() === "")
53
+ return false;
54
+ if (value === "UTC" || value === "local")
55
+ return true;
56
+ try {
57
+ new Intl.DateTimeFormat(undefined, { timeZone: value });
58
+ return true;
59
+ }
60
+ catch {
61
+ return false;
62
+ }
63
+ }
@@ -32,15 +32,19 @@ export declare function zonesInView<Z extends EventZone>(zones: readonly Z[], sh
32
32
  * Span zones carry no event and never count. A pure function of its arguments.
33
33
  */
34
34
  export declare function activeEventZones(zones: readonly EventZone[], shown: ShownEvents, timeUtcMs: number): readonly string[];
35
- /** A scene's pacing: the rate outside every zone and its zones. Where zones overlap the slowest wins whatever order they are listed in (`pacedRate` lays the fastest first and the slowest last). */
35
+ /**
36
+ * A scene's pacing: the rate outside every zone and its zones. Faster spans (zones with no event) set the cruise over the base and the faster wins where they meet; slower spans and event rules ease down from the cruise, and where they overlap or their ramps meet the slowest
37
+ * speed any one of them alone would give wins, whatever order they are listed in.
38
+ */
36
39
  export interface Pacing {
37
40
  readonly baseRate: number;
38
41
  readonly zones: readonly PaceZone[];
39
42
  }
40
43
  /**
41
- * The playback rate at `timeUtcMs`: the base rate, with each zone laid over it in turn, fastest first so the slowest wins where zones meet (order-independent). A zone's weight is 1 inside it and falls to 0 over its ramp
42
- * (smoothstep); the rate blends in log space, so a jump of several orders of magnitude eases evenly. Every weight is continuous in time, so the
43
- * result is continuous too. A pure function of its arguments: nothing about the State changes.
44
+ * The playback rate at `timeUtcMs`, all blends in log space by the zone weight. The cruise is the base, raised to the fastest of what each span faster than the base gives alone (the faster wins where such spans meet).
45
+ * The rate is the slowest of the cruise and of what each slower span (rate at or under the base) and each event rule touching that time gives easing from the cruise toward its rate (the slowest wins where they meet; a piece
46
+ * whose blend is faster than the cruise changes nothing). Each term equals its underlying value where its weight is 0, so the rate is continuous at every zone and ramp edge, and it does not depend on the order of the zones.
47
+ * Untouched, it is exactly the base. A pure function of its arguments: nothing about the State changes.
44
48
  */
45
49
  export declare function pacedRate(pacing: Pacing, timeUtcMs: number, shown?: ShownEvents): number;
46
50
  /** How long, in real milliseconds, a change of the paced rate that comes from a view switch takes to ease in. */
@@ -50,10 +54,38 @@ export interface PaceView {
50
54
  shown?: ShownEvents;
51
55
  ease?: {
52
56
  readonly fromRate: number;
53
- readonly startMs: number;
57
+ readonly startMs: number; /** log(fromRate) - log(paced rate at the switch): the change the switch itself caused; set on first use. */
58
+ k0?: number;
59
+ };
60
+ /** Where `stepPacing` left the clock: its time and rate, and the real time it did so. Absent until the first step, and cleared by a seek or any other move of the clock the step did not make. */
61
+ last?: {
62
+ readonly timeUtcMs: number;
63
+ readonly rate: number;
64
+ readonly nowMs: number;
54
65
  };
55
66
  }
56
67
  /** Starts the ease from the clock's present rate; the next `applyPacing` calls blend from it to the paced rate over `PACE_EASE_MS`. */
57
68
  export declare function startPaceEase(view: PaceView, fromRate: number, nowMs: number): void;
58
- /** Sets the clock to the paced rate for its current time (skipped when it already runs at it); mid-ease it is the log-space blend from the ease's start rate. */
69
+ /** The ease's own change, fixed once at the switch (the first time it is read, at the switch's time): log(start rate) minus log(the new view's paced rate there). */
70
+ export declare function easeShift(view: PaceView, timeUtcMs: number, pacing: Pacing): number;
71
+ /** Sets the clock to the paced rate for its current time (skipped when it already runs at it); mid-ease the switch's own change decays over it: the paced shape times exp(k0 * (1 - weight)), so a zone reached during the ease still slows playback. */
59
72
  export declare function applyPacing(clock: SimulationClock, pacing: Pacing, view?: PaceView, nowMs?: number): void;
73
+ /** The most sub-steps one `pacedAdvance` call takes; real time left over after them is dropped, so a frame that long (a tab left hidden) slows the clock rather than skipping a zone. */
74
+ export declare const MAX_PACE_STEPS = 4096;
75
+ /** A view-switch ease as `pacedAdvance` reads it: the switch's own change k0 (see `easeShift`) and how far into its `PACE_EASE_MS` it already is, in real milliseconds, when the advance begins. */
76
+ export interface AdvanceEase {
77
+ readonly k0: number;
78
+ readonly elapsedMs: number;
79
+ }
80
+ /**
81
+ * The time `realElapsedMs` of real time after `fromUtcMs` when the clock runs at `pacedRate` throughout (`direction` -1 runs it backward): the rate is integrated, not read once, so a long frame still slows down
82
+ * through every zone and ramp it crosses. Each sub-step stops at the next zone or ramp edge, covers at most 1/32 of a ramp, and is timed by the trapezoid rule on the rates at its two ends (the far one a millisecond short).
83
+ * With an `ease` (a view switch changing the rate) the rate integrated is the eased one, and a sub-step also covers at most 1/32 of the ease's real time while it runs.
84
+ * At most `MAX_PACE_STEPS` sub-steps; the result is a whole millisecond. A pure function of its arguments.
85
+ */
86
+ export declare function pacedAdvance(pacing: Pacing, fromUtcMs: number, realElapsedMs: number, shown?: ShownEvents, direction?: 1 | -1, ease?: AdvanceEase): number;
87
+ /**
88
+ * One pacing step per frame: moves the clock from where the last step left it by `pacedAdvance` over the real time since, then sets the paced rate for the new time (`applyPacing`'s job). Falls back to `applyPacing`
89
+ * (one rate for the frame) on the first step, while paused, or when the clock was moved or re-rated since the last step. The clock is moved through its public `seek` and `setRate`.
90
+ */
91
+ export declare function stepPacing(clock: SimulationClock, pacing: Pacing, view: PaceView, nowMs?: number): void;