astraeus 0.9.1 → 0.9.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +22 -0
- package/README.md +20 -13
- package/package.json +1 -1
- package/src/api/assembleScene.js +4 -4
- package/src/api/errors.d.ts +1 -1
- package/src/api/index.d.ts +2 -2
- package/src/api/look.d.ts +14 -0
- package/src/api/lookInput.d.ts +1 -1
- package/src/api/lookInput.js +6 -2
- package/src/api/planCamera.d.ts +19 -2
- package/src/api/planCamera.js +45 -6
- package/src/api/planPaths.js +2 -2
- package/src/api/planStory.d.ts +3 -1
- package/src/api/planStory.js +5 -0
- package/src/api/planTimeline.d.ts +1 -1
- package/src/api/planTimeline.js +10 -1
- package/src/api/planViews.d.ts +3 -1
- package/src/api/planViews.js +4 -0
- package/src/api/scene.d.ts +11 -5
- package/src/api/scene.js +16 -2
- package/src/api/sceneReads.d.ts +31 -1
- package/src/api/story.d.ts +9 -2
- package/src/api/story.js +10 -3
- package/src/api/switches.d.ts +1 -0
- package/src/api/switches.js +3 -1
- package/src/api/time.d.ts +1 -1
- package/src/api/time.js +4 -1
- package/src/app/App.js +26 -6
- package/src/app/App.node.js +26 -6
- package/src/app/AstraeusScene.d.ts +8 -1
- package/src/app/CameraController.d.ts +2 -0
- package/src/app/CameraController.js +11 -1
- package/src/app/SkyFiguresView.d.ts +2 -2
- package/src/app/SkyFiguresView.js +25 -14
- package/src/app/displaySwitches.d.ts +2 -0
- package/src/app/displaySwitches.js +1 -1
- package/src/app/liveLook.d.ts +4 -1
- package/src/app/liveLook.js +29 -1
- package/src/app/look.d.ts +5 -0
- package/src/app/look.js +8 -2
- package/src/app/sceneCamera.js +14 -2
- package/src/app/sceneContentsHooks.js +1 -1
- package/src/app/sceneFrame.js +2 -2
- package/src/app/scenePointer.d.ts +5 -1
- package/src/app/scenePointer.js +8 -3
- package/src/app/timeLook.d.ts +7 -0
- package/src/app/timeLook.js +8 -0
- package/src/core/clock.js +2 -1
- package/src/core/lookValues.d.ts +13 -0
- package/src/core/lookValues.js +39 -0
- package/src/core/state.d.ts +2 -0
- package/src/core/state.js +5 -1
- package/src/core/storyPanels.d.ts +8 -4
- package/src/core/storyPanels.js +17 -5
- package/src/shell/AstraeusShell.d.ts +5 -1
- package/src/shell/AstraeusShell.js +15 -8
- package/src/shell/AstraeusShell.node.js +15 -8
- package/src/shell/ObjectControls.js +1 -1
- package/src/shell/TimelineBar.d.ts +6 -2
- package/src/shell/TimelineBar.js +17 -12
- package/src/shell/TimelineBar.node.js +17 -12
- package/src/shell/experience.d.ts +2 -0
- package/src/shell/infoModel.d.ts +2 -1
- package/src/shell/infoModel.js +10 -10
- package/src/shell/storyPanels.d.ts +19 -1
- package/src/shell/storyPanels.js +34 -2
- package/src/shell/timelineModel.d.ts +11 -0
- package/src/shell/timelineModel.js +28 -0
- package/src/shell/useStoryPanels.d.ts +4 -0
- package/src/shell/useStoryPanels.js +27 -6
package/src/shell/storyPanels.js
CHANGED
|
@@ -8,22 +8,54 @@ export function panelsCrossed(panels, previousMs, currentMs) {
|
|
|
8
8
|
return [];
|
|
9
9
|
return panels.filter((panel) => panel.timeUtcMs > previousMs && panel.timeUtcMs <= currentMs);
|
|
10
10
|
}
|
|
11
|
+
/** A moment panel's close moment (`timeUtcMs` plus its span: the panel's own `closeAfterSeconds`, else the playback's), or null when it has no span and never closes. */
|
|
12
|
+
export function panelCloseMs(panel, playbackSpan) {
|
|
13
|
+
const span = panel.closeAfterSeconds ?? playbackSpan;
|
|
14
|
+
return span === undefined ? null : panel.timeUtcMs + span * 1000;
|
|
15
|
+
}
|
|
16
|
+
/** Whether a panel opening with the clock at `atMs` is one the close applies to: the clock is still before its close moment (or it has none). A panel opened at or past its close moment stays open until closed. */
|
|
17
|
+
export function panelArmedAt(panel, playbackSpan, atMs) {
|
|
18
|
+
const closeMs = panelCloseMs(panel, playbackSpan);
|
|
19
|
+
return closeMs === null || atMs < closeMs;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Whether an open moment panel closes on this tick: it is `armed` (it opened while the clock was before its close moment), the clock moves forward (`previousMs < currentMs`, playing or just stopped after playing)
|
|
23
|
+
* and ends at or past the close moment. It is a state test, not a crossing, so a span shorter than one frame still closes on a later tick; the caller never asks on the tick that opened the panel.
|
|
24
|
+
* With no span it never closes; a seek, a rewind, a pause or no movement closes nothing.
|
|
25
|
+
*/
|
|
26
|
+
export function panelSpanPassed(panel, playbackSpan, previousMs, currentMs, moving, armed = true) {
|
|
27
|
+
const closeMs = panelCloseMs(panel, playbackSpan);
|
|
28
|
+
if (closeMs === null || !armed || !moving || !(currentMs > previousMs))
|
|
29
|
+
return false;
|
|
30
|
+
return currentMs >= closeMs;
|
|
31
|
+
}
|
|
11
32
|
/**
|
|
12
33
|
* Decides, tick by tick, whether playback has just carried the clock across a panel. It remembers the last time it saw;
|
|
13
34
|
* `rebase` moves that memory when a person seeks, so a jump is never read as playback and opens nothing.
|
|
14
35
|
*/
|
|
15
36
|
export class CrossingTracker {
|
|
16
37
|
#previousMs;
|
|
38
|
+
#wasPlaying = false;
|
|
17
39
|
constructor(startMs) {
|
|
18
40
|
this.#previousMs = startMs;
|
|
19
41
|
}
|
|
42
|
+
/** Whether the next tick counts as playback (the clock was playing on the last one); with `previousMs`, what `panelSpanPassed` needs before `advance` moves them. */
|
|
43
|
+
get wasPlaying() { return this.#wasPlaying; }
|
|
44
|
+
get previousMs() { return this.#previousMs; }
|
|
45
|
+
/** The clock as the panel logic knows it: rebased by a seek, moved on by every tick. A panel's arming reads this, so one opened right after a jump counts the clock it jumped to. */
|
|
46
|
+
get timeUtcMs() { return this.#previousMs; }
|
|
20
47
|
rebase(timeUtcMs) {
|
|
21
48
|
this.#previousMs = timeUtcMs;
|
|
49
|
+
this.#wasPlaying = false;
|
|
22
50
|
}
|
|
23
|
-
/**
|
|
51
|
+
/**
|
|
52
|
+
* The newest panel crossed since the last tick, or null: nothing crossed, the clock is not playing, or auto-open is off.
|
|
53
|
+
* A tick that finds the clock stopped but saw it playing on the last tick counts as playback too, so a stop on the timeline's end opens the panel there.
|
|
54
|
+
*/
|
|
24
55
|
advance(panels, timeUtcMs, playing, autoOpen) {
|
|
25
|
-
const crossed = autoOpen && playing ? panelsCrossed(panels, this.#previousMs, timeUtcMs) : [];
|
|
56
|
+
const crossed = autoOpen && (playing || this.#wasPlaying) ? panelsCrossed(panels, this.#previousMs, timeUtcMs) : [];
|
|
26
57
|
this.#previousMs = timeUtcMs;
|
|
58
|
+
this.#wasPlaying = playing;
|
|
27
59
|
return crossed[crossed.length - 1] ?? null;
|
|
28
60
|
}
|
|
29
61
|
}
|
|
@@ -32,6 +32,17 @@ export declare function eventNavigationTargets(events: readonly TimelineEvent[],
|
|
|
32
32
|
export declare function clampToBounds(timeUtcMs: number, bounds: TimeBounds): number;
|
|
33
33
|
export declare function eventPositionPercent(event: TimelineEvent, bounds: TimeBounds): number;
|
|
34
34
|
export declare function formatUtcTimestamp(timeUtcMs: number): string;
|
|
35
|
+
/** How the viewer's times read (the look `time`): a zone (`"UTC"`, `"local"` or an IANA name) and a precision. */
|
|
36
|
+
export interface TimeLook {
|
|
37
|
+
readonly zone: string;
|
|
38
|
+
readonly precision: "day" | "minute" | "second";
|
|
39
|
+
}
|
|
40
|
+
/** Today's time look: ISO text in UTC to the second. */
|
|
41
|
+
export declare const DEFAULT_TIME_LOOK: Readonly<TimeLook>;
|
|
42
|
+
/** The time look, or the default when none is given. */
|
|
43
|
+
export declare function withDefaultTime(look: TimeLook | undefined): TimeLook;
|
|
44
|
+
/** A moment as the viewer's reader sees it (the look `time`): in UTC, ISO text (`2026-11-15T04:37:12Z`, `2026-11-15T04:37Z`, `2026-11-15`; to the second it is `formatUtcTimestamp`); in the visitor's or a named zone, the visitor's language style with the zone's short name. The one formatter for every visitor-facing time; `<time dateTime>`, the Developer drawer and the page address stay `formatUtcTimestamp`. */
|
|
45
|
+
export declare function formatTime(timeUtcMs: number, look?: TimeLook): string;
|
|
35
46
|
/** A time's position on the timeline, clamped to 0–100. */
|
|
36
47
|
export declare function timePositionPercent(timeUtcMs: number, bounds: TimeBounds): number;
|
|
37
48
|
/** The window's own highest sampled rate with its unit, spoken the way the readout speaks it ("48 passes per hour"); null without a rate. */
|
|
@@ -92,6 +92,34 @@ export function eventPositionPercent(event, bounds) {
|
|
|
92
92
|
export function formatUtcTimestamp(timeUtcMs) {
|
|
93
93
|
return new Date(timeUtcMs).toISOString().replace(".000Z", "Z");
|
|
94
94
|
}
|
|
95
|
+
/** Today's time look: ISO text in UTC to the second. */
|
|
96
|
+
export const DEFAULT_TIME_LOOK = Object.freeze({ zone: "UTC", precision: "second" });
|
|
97
|
+
/** The time look, or the default when none is given. */
|
|
98
|
+
export function withDefaultTime(look) {
|
|
99
|
+
return look ?? DEFAULT_TIME_LOOK;
|
|
100
|
+
}
|
|
101
|
+
const zoneFormats = new Map();
|
|
102
|
+
function zoneFormat(look) {
|
|
103
|
+
const key = `${look.zone}|${look.precision}`;
|
|
104
|
+
let format = zoneFormats.get(key);
|
|
105
|
+
if (format === undefined) {
|
|
106
|
+
const date = { day: "numeric", month: "short", year: "numeric" };
|
|
107
|
+
const clock = look.precision === "day" ? {} : { hour: "numeric", minute: "2-digit", ...(look.precision === "second" ? { second: "2-digit" } : {}), timeZoneName: "short" };
|
|
108
|
+
format = new Intl.DateTimeFormat(undefined, { ...date, ...clock, ...(look.zone === "local" ? {} : { timeZone: look.zone }) });
|
|
109
|
+
zoneFormats.set(key, format);
|
|
110
|
+
}
|
|
111
|
+
return format;
|
|
112
|
+
}
|
|
113
|
+
/** A moment as the viewer's reader sees it (the look `time`): in UTC, ISO text (`2026-11-15T04:37:12Z`, `2026-11-15T04:37Z`, `2026-11-15`; to the second it is `formatUtcTimestamp`); in the visitor's or a named zone, the visitor's language style with the zone's short name. The one formatter for every visitor-facing time; `<time dateTime>`, the Developer drawer and the page address stay `formatUtcTimestamp`. */
|
|
114
|
+
export function formatTime(timeUtcMs, look = DEFAULT_TIME_LOOK) {
|
|
115
|
+
if (look.zone === "UTC") {
|
|
116
|
+
if (look.precision === "second")
|
|
117
|
+
return formatUtcTimestamp(timeUtcMs);
|
|
118
|
+
const iso = new Date(timeUtcMs).toISOString();
|
|
119
|
+
return look.precision === "day" ? iso.slice(0, 10) : `${iso.slice(0, 16)}Z`;
|
|
120
|
+
}
|
|
121
|
+
return zoneFormat(look).format(timeUtcMs);
|
|
122
|
+
}
|
|
95
123
|
/** A time's position on the timeline, clamped to 0–100. */
|
|
96
124
|
export function timePositionPercent(timeUtcMs, bounds) {
|
|
97
125
|
const span = bounds.endUtcMs - bounds.startUtcMs;
|
|
@@ -3,12 +3,16 @@ import { type StoryPanel, type StoryStep } from "./storyPanels.js";
|
|
|
3
3
|
export interface StoryPanelSettings {
|
|
4
4
|
readonly autoOpen: boolean;
|
|
5
5
|
readonly pauseSeconds: number;
|
|
6
|
+
/** Simulated seconds after an open moment panel's time at which forward playback closes it (a panel's own span wins); absent: never. */
|
|
7
|
+
readonly closeAfterSeconds?: number;
|
|
6
8
|
}
|
|
7
9
|
/** Who opened or closed the panel: the visitor, the host, playback crossing a panel, or a move (a view switch dropped it; the link names whatever last moved the view). */
|
|
8
10
|
export type PanelCause = "visitor" | "host" | "playback" | "move";
|
|
9
11
|
/**
|
|
10
12
|
* Which story panel is open and whether playback is held for it. A panel opens by itself only when forward playback
|
|
11
13
|
* carries the clock across its time; a seek (slider, Previous, Next, a link) re-bases the crossing check and opens nothing.
|
|
14
|
+
* An open moment panel closes by itself on the first forward-playing tick after it opened whose clock ends at or past its time plus its span (`closeAfterSeconds`), if it opened while the clock was before that moment
|
|
15
|
+
* (a panel opened at or past it stays open until closed); a seek, rewind or pause never closes it.
|
|
12
16
|
* Only one panel is open at a time: the newest replaces the one before. A step never opens from playback; with steps and no moment panel the first step is open at the start.
|
|
13
17
|
*/
|
|
14
18
|
export declare function useStoryPanels(panels: readonly StoryPanel[], steps: readonly StoryStep[], settings: StoryPanelSettings, snapshot: ClockSnapshot, setPlaying: ((playing: boolean) => void) | undefined): {
|
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
import { useCallback, useEffect, useRef, useState } from "react";
|
|
2
|
-
import { CrossingTracker } from "./storyPanels.js";
|
|
2
|
+
import { CrossingTracker, panelArmedAt, panelSpanPassed } from "./storyPanels.js";
|
|
3
3
|
/**
|
|
4
4
|
* Which story panel is open and whether playback is held for it. A panel opens by itself only when forward playback
|
|
5
5
|
* carries the clock across its time; a seek (slider, Previous, Next, a link) re-bases the crossing check and opens nothing.
|
|
6
|
+
* An open moment panel closes by itself on the first forward-playing tick after it opened whose clock ends at or past its time plus its span (`closeAfterSeconds`), if it opened while the clock was before that moment
|
|
7
|
+
* (a panel opened at or past it stays open until closed); a seek, rewind or pause never closes it.
|
|
6
8
|
* Only one panel is open at a time: the newest replaces the one before. A step never opens from playback; with steps and no moment panel the first step is open at the start.
|
|
7
9
|
*/
|
|
8
10
|
export function useStoryPanels(panels, steps, settings, snapshot, setPlaying) {
|
|
@@ -10,14 +12,24 @@ export function useStoryPanels(panels, steps, settings, snapshot, setPlaying) {
|
|
|
10
12
|
const cause = useRef("visitor");
|
|
11
13
|
const [holding, setHolding] = useState(false);
|
|
12
14
|
const tracker = useRef(new CrossingTracker(snapshot.timeUtcMs));
|
|
13
|
-
|
|
14
|
-
|
|
15
|
+
/** The panel the close applies to: the one that opened while the clock was before its close moment (null: none open, or one opened at or past it). */
|
|
16
|
+
const armedId = useRef(null);
|
|
17
|
+
const latest = useRef({ panels, settings, snapshot, setPlaying, holding, openId });
|
|
18
|
+
latest.current = { panels, settings, snapshot, setPlaying, holding, openId };
|
|
15
19
|
useEffect(() => {
|
|
16
|
-
const { panels: list, settings: now, snapshot: shot, setPlaying: control } = latest.current;
|
|
20
|
+
const { panels: list, settings: now, snapshot: shot, setPlaying: control, openId: shownId } = latest.current;
|
|
21
|
+
const shown = list.find((panel) => panel.id === shownId);
|
|
22
|
+
const spanPassed = shown !== undefined && armedId.current === shown.id && panelSpanPassed(shown, now.closeAfterSeconds, tracker.current.previousMs, shot.timeUtcMs, shot.playing || tracker.current.wasPlaying);
|
|
17
23
|
const newest = tracker.current.advance(list, shot.timeUtcMs, shot.playing, now.autoOpen);
|
|
18
|
-
if (newest === null)
|
|
24
|
+
if (newest === null) {
|
|
25
|
+
if (spanPassed) {
|
|
26
|
+
cause.current = "playback";
|
|
27
|
+
setOpenId(null);
|
|
28
|
+
}
|
|
19
29
|
return;
|
|
30
|
+
}
|
|
20
31
|
cause.current = "playback";
|
|
32
|
+
armedId.current = newest.id;
|
|
21
33
|
setOpenId(newest.id);
|
|
22
34
|
if (now.pauseSeconds > 0 && control !== undefined) {
|
|
23
35
|
control(false);
|
|
@@ -40,9 +52,18 @@ export function useStoryPanels(panels, steps, settings, snapshot, setPlaying) {
|
|
|
40
52
|
}, [holding, openId, settings.pauseSeconds]);
|
|
41
53
|
const noteSeek = useCallback((timeUtcMs) => {
|
|
42
54
|
tracker.current.rebase(timeUtcMs);
|
|
55
|
+
const { panels: list, settings: now, openId: shownId } = latest.current;
|
|
56
|
+
const shown = list.find((panel) => panel.id === shownId);
|
|
57
|
+
armedId.current = shown !== undefined && panelArmedAt(shown, now.closeAfterSeconds, timeUtcMs) ? shown.id : null;
|
|
43
58
|
setHolding(false);
|
|
44
59
|
}, []);
|
|
45
|
-
const open = useCallback((id, by = "visitor") => {
|
|
60
|
+
const open = useCallback((id, by = "visitor") => {
|
|
61
|
+
const { panels: list, settings: now } = latest.current;
|
|
62
|
+
const target = list.find((panel) => panel.id === id);
|
|
63
|
+
armedId.current = target !== undefined && panelArmedAt(target, now.closeAfterSeconds, tracker.current.timeUtcMs) ? id : null;
|
|
64
|
+
cause.current = by;
|
|
65
|
+
setOpenId(id);
|
|
66
|
+
}, []);
|
|
46
67
|
const close = useCallback((by = "visitor") => {
|
|
47
68
|
cause.current = by;
|
|
48
69
|
setOpenId(null);
|