astraeus 0.9.1 → 0.9.3

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 (74) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/README.md +22 -15
  3. package/package.json +1 -1
  4. package/src/api/assembleScene.js +4 -4
  5. package/src/api/errors.d.ts +1 -1
  6. package/src/api/group.d.ts +12 -9
  7. package/src/api/group.js +26 -5
  8. package/src/api/index.d.ts +2 -2
  9. package/src/api/look.d.ts +14 -0
  10. package/src/api/lookInput.d.ts +1 -1
  11. package/src/api/lookInput.js +6 -2
  12. package/src/api/planCamera.d.ts +19 -2
  13. package/src/api/planCamera.js +45 -6
  14. package/src/api/planPaths.js +2 -2
  15. package/src/api/planStory.d.ts +3 -1
  16. package/src/api/planStory.js +5 -0
  17. package/src/api/planTimeline.d.ts +1 -1
  18. package/src/api/planTimeline.js +10 -1
  19. package/src/api/planViews.d.ts +3 -1
  20. package/src/api/planViews.js +4 -0
  21. package/src/api/scene.d.ts +11 -5
  22. package/src/api/scene.js +16 -2
  23. package/src/api/sceneReads.d.ts +32 -2
  24. package/src/api/story.d.ts +9 -2
  25. package/src/api/story.js +10 -3
  26. package/src/api/switches.d.ts +1 -0
  27. package/src/api/switches.js +3 -1
  28. package/src/api/time.d.ts +1 -1
  29. package/src/api/time.js +4 -1
  30. package/src/app/App.js +26 -6
  31. package/src/app/App.node.js +26 -6
  32. package/src/app/AstraeusScene.d.ts +8 -1
  33. package/src/app/CameraController.d.ts +2 -0
  34. package/src/app/CameraController.js +11 -1
  35. package/src/app/SkyFiguresView.d.ts +2 -2
  36. package/src/app/SkyFiguresView.js +25 -14
  37. package/src/app/displaySwitches.d.ts +2 -0
  38. package/src/app/displaySwitches.js +1 -1
  39. package/src/app/liveLook.d.ts +4 -1
  40. package/src/app/liveLook.js +29 -1
  41. package/src/app/look.d.ts +5 -0
  42. package/src/app/look.js +8 -2
  43. package/src/app/sceneCamera.js +14 -2
  44. package/src/app/sceneContentsHooks.js +1 -1
  45. package/src/app/sceneFrame.js +2 -2
  46. package/src/app/scenePointer.d.ts +5 -1
  47. package/src/app/scenePointer.js +8 -3
  48. package/src/app/timeLook.d.ts +7 -0
  49. package/src/app/timeLook.js +8 -0
  50. package/src/core/clock.js +2 -1
  51. package/src/core/listedOrbitGroup.d.ts +24 -10
  52. package/src/core/listedOrbitGroup.js +65 -13
  53. package/src/core/lookValues.d.ts +13 -0
  54. package/src/core/lookValues.js +39 -0
  55. package/src/core/state.d.ts +2 -0
  56. package/src/core/state.js +5 -1
  57. package/src/core/storyPanels.d.ts +8 -4
  58. package/src/core/storyPanels.js +17 -5
  59. package/src/shell/AstraeusShell.d.ts +5 -1
  60. package/src/shell/AstraeusShell.js +15 -8
  61. package/src/shell/AstraeusShell.node.js +15 -8
  62. package/src/shell/ObjectControls.js +1 -1
  63. package/src/shell/TimelineBar.d.ts +6 -2
  64. package/src/shell/TimelineBar.js +17 -12
  65. package/src/shell/TimelineBar.node.js +17 -12
  66. package/src/shell/experience.d.ts +2 -0
  67. package/src/shell/infoModel.d.ts +2 -1
  68. package/src/shell/infoModel.js +10 -10
  69. package/src/shell/storyPanels.d.ts +19 -1
  70. package/src/shell/storyPanels.js +34 -2
  71. package/src/shell/timelineModel.d.ts +11 -0
  72. package/src/shell/timelineModel.js +28 -0
  73. package/src/shell/useStoryPanels.d.ts +4 -0
  74. package/src/shell/useStoryPanels.js +27 -6
@@ -42,7 +42,7 @@ export function initialObjectId(experience, timeUtcMs) {
42
42
  }
43
43
  /** The story-panel settings the experience carries itself, used when the app gives none live. */
44
44
  function ownStorySettings(storySet) {
45
- return { autoOpen: storySet?.autoOpen ?? false, pauseSeconds: storySet?.pauseSeconds ?? 0 };
45
+ return { autoOpen: storySet?.autoOpen ?? false, pauseSeconds: storySet?.pauseSeconds ?? 0, ...(storySet?.closeAfterSeconds === undefined ? {} : { closeAfterSeconds: storySet.closeAfterSeconds }) };
46
46
  }
47
47
  /** The timeline bar, or nothing when the experience says it has no timeline. */
48
48
  function ShellTimeline({ hidden, ...bar }) {
@@ -117,17 +117,17 @@ function objectLabelOr(experience, objectId, fallback) {
117
117
  return experience.objects.find((object) => object.id === objectId)?.label ?? skyFigureById(experience, objectId)?.label ?? fallback;
118
118
  }
119
119
  /** The information panel's content and, for an object, its live measurements. */
120
- function infoContent(experience, info, selectedObjectId, timeUtcMs, metricsFor) {
120
+ function infoContent(experience, info, selectedObjectId, timeUtcMs, metricsFor, timeLook) {
121
121
  const view = info === null
122
122
  ? null
123
- : infoView(experience, info.kind === "object" ? { kind: "object", id: selectedObjectId } : info, timeUtcMs);
123
+ : infoView(experience, info.kind === "object" ? { kind: "object", id: selectedObjectId } : info, timeUtcMs, timeLook);
124
124
  const metrics = view?.target.kind === "object" && metricsFor !== undefined && skyFigureById(experience, view.target.id) === undefined ? metricsFor(view.target.id, timeUtcMs) : [];
125
125
  return { view, metrics };
126
126
  }
127
127
  /** The moon families load on demand: only an experience with `moonFamilies` draws them (I-089). */
128
128
  const MoonFamilyPanel = lazy(() => import("./MoonFamilyPanel.js").then((module) => ({ default: module.MoonFamilyPanel })));
129
129
  /** Canvas-first layout shared by astronomy experiences. Scene and diagnostics stay app-owned. */
130
- export function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onTurnToFigure, onCameraHold, onTimeShown, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout = DEFAULT_PHONE_LAYOUT, labelStyle, highlightedFamily = null, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }) {
130
+ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloperModeChange, onTogglePlayback, onRateChange, paceAuto, onSeek, onCameraRequest, onTurnToFigure, onCameraHold, onTimeShown, hostCameraSet, storySeekNote, onSelectionChange, scaleId, onScaleChange, scaleChoices, switcher, displaySwitches, viewChoice, viewCamera, metricsFor, developerTools, storyPanelSettings, timelineGlow, phoneLayout = DEFAULT_PHONE_LAYOUT, labelStyle, timeLook, highlightedFamily = null, onHighlightFamily, onSetPlaying, panelRequest, onOpenPanelChange, featureRequest, onOpenFeatureChange, pickRequest, selectRequest, onSelectRequestApplied, children, }) {
131
131
  const infoPanelId = `${useId()}-info-panel`;
132
132
  const [selectedObjectId, setSelectedObjectId] = useState(() => initialObjectId(experience, snapshot.timeUtcMs));
133
133
  const phone = usePhone();
@@ -279,11 +279,18 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
279
279
  setInfo({ kind: "object" });
280
280
  };
281
281
  /** An object tapped or clicked in the scene: the picker's focus; on a wide screen it also opens the card, on a phone it does not (T-138). A tapped body-set member that is no listed object just flies there. */
282
- const pickObject = (id) => {
282
+ const pickObject = (id, keepSky = false) => {
283
283
  const object = availableObjectById(experience, id, snapshot.timeUtcMs);
284
284
  if (skyFigureById(experience, id) !== undefined) {
285
285
  selectFigure(id, pickOpensInfo(phone));
286
286
  }
287
+ else if (object !== undefined && keepSky) {
288
+ // A tap from a look-out camera: select it and stay in the sky (owner, 2026-11-15); the menu's Focus and Follow still fly there.
289
+ setSelectedObjectId(object.id);
290
+ onSelectionChange(object.id, "visitor");
291
+ if (pickOpensInfo(phone))
292
+ setInfo({ kind: "object" });
293
+ }
287
294
  else if (object !== undefined) {
288
295
  activatePreset(focusPresetFor(experience, object));
289
296
  if (pickOpensInfo(phone))
@@ -295,7 +302,7 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
295
302
  const requestedPickSerial = serialOf(pickRequest);
296
303
  useEffect(() => {
297
304
  if (pickRequest !== null && pickRequest !== undefined)
298
- pickObject(pickRequest.id);
305
+ pickObject(pickRequest.id, pickRequest.keepSky === true);
299
306
  // Only a new request flies; the handler reads the current time and experience.
300
307
  // eslint-disable-next-line react-hooks/exhaustive-deps
301
308
  }, [requestedPickSerial]);
@@ -364,7 +371,7 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
364
371
  if (info?.kind === "window")
365
372
  setInfo({ kind: "window", id: window.id });
366
373
  };
367
- const { view, metrics } = infoContent(experience, info, selectedObjectId, snapshot.timeUtcMs, metricsFor);
374
+ const { view, metrics } = infoContent(experience, info, selectedObjectId, snapshot.timeUtcMs, metricsFor, timeLook);
368
375
  // On a wide screen the moons sheet and the information panel share the left column under the toolbar: opening one closes the other.
369
376
  const toggleMoons = () => {
370
377
  if (!moonsOpen)
@@ -376,5 +383,5 @@ export function AstraeusShell({ experience, snapshot, developerMode, onDeveloper
376
383
  const selectedLabel = objectLabelOr(experience, selectedObjectId, "Controls");
377
384
  const topBar = (_jsx(TopBar, { experience: experience, timeUtcMs: snapshot.timeUtcMs, selectedObjectId: selectedObjectId, activePresetId: activePresetId, onSelectObject: selectObject, onCameraPreset: activatePreset, infoOpen: info?.kind === "object", onToggleInfo: () => setInfo(info?.kind === "object" ? null : { kind: "object" }), infoPanelId: infoPanelId, scaleId: scaleId, onScaleChange: onScaleChange, scaleChoices: scaleChoices, switcher: switcher, displaySwitches: displaySwitches, viewChoice: viewChoice }));
378
385
  const moonPanel = experience.moonFamilies === undefined ? null : (_jsx(PanelLoadBoundary, { message: "The moon list could not load. Reload the page to try again.", children: _jsx(Suspense, { fallback: null, children: _jsx(MoonFamilyPanel, { list: experience.moonFamilies, highlightedFamily: highlightedFamily, onHighlight: (id) => onHighlightFamily?.(id), onSelectMoon: chooseMoon }) }) }));
379
- return (_jsxs("main", { className: "astraeus-shell", ref: root, "data-phone": phone, "data-timeline-hidden": experience.hideTimeline === true, "data-embedded": embedded, style: { ...phoneLayoutStyle(phoneLayout), ...labelStyleVars(labelStyle) }, children: [_jsx("div", { className: "shell-canvas", children: children }), phone && _jsxs(ControlsDrawer, { label: selectedLabel, open: controlsOpen, onOpenChange: openControls, swipeThresholdPx: phoneLayout.swipeThresholdPx, children: [topBar, moonPanel] }), _jsxs("div", { className: "shell-top", children: [!phone && topBar, !phone && moonPanel !== null && _jsx(MoonsSheet, { planetLabel: experience.moonFamilies?.planetLabel, open: moonsOpen, onToggle: toggleMoons, onClose: () => setMoonsOpen(false), children: moonPanel }), view !== null && _jsx(InfoPanel, { view: view, metrics: metrics, onClose: () => setInfo(null), id: infoPanelId })] }), story.openPanel !== null && (_jsx(StoryPanelView, { panel: story.openPanel, holding: story.holding, onClose: closePanel, onContinue: story.continuePlayback, step: stepNav })), _jsx(DeveloperDrawer, { developerMode: developerMode, onDeveloperModeChange: onDeveloperModeChange, children: developerTools }), _jsx(ShellTimeline, { hidden: experience.hideTimeline === true, experience: experience, snapshot: snapshot, onTogglePlayback: onTogglePlayback, onRateChange: onRateChange, paceAuto: paceAuto, onSeek: seek, panels: storyPanels, openPanelId: openPanelId, onPanelOpen: openPanelFromTimeline, onEventSeek: seekToEvent, onEventInfo: (event) => setInfo({ kind: "event", id: event.id }), onWindowSeek: seekToWindow, onWindowInfo: (window) => setInfo({ kind: "window", id: window.id }), glowLook: timelineGlow, infoPanelId: infoPanelId, drawer: phone ? { open: timelineOpen, onOpenChange: openTimeline, swipeThresholdPx: phoneLayout.swipeThresholdPx } : undefined })] }));
386
+ return (_jsxs("main", { className: "astraeus-shell", ref: root, "data-phone": phone, "data-timeline-hidden": experience.hideTimeline === true, "data-embedded": embedded, style: { ...phoneLayoutStyle(phoneLayout), ...labelStyleVars(labelStyle) }, children: [_jsx("div", { className: "shell-canvas", children: children }), phone && _jsxs(ControlsDrawer, { label: selectedLabel, open: controlsOpen, onOpenChange: openControls, swipeThresholdPx: phoneLayout.swipeThresholdPx, children: [topBar, moonPanel] }), _jsxs("div", { className: "shell-top", children: [!phone && topBar, !phone && moonPanel !== null && _jsx(MoonsSheet, { planetLabel: experience.moonFamilies?.planetLabel, open: moonsOpen, onToggle: toggleMoons, onClose: () => setMoonsOpen(false), children: moonPanel }), view !== null && _jsx(InfoPanel, { view: view, metrics: metrics, onClose: () => setInfo(null), id: infoPanelId })] }), story.openPanel !== null && (_jsx(StoryPanelView, { panel: story.openPanel, holding: story.holding, onClose: closePanel, onContinue: story.continuePlayback, step: stepNav })), _jsx(DeveloperDrawer, { developerMode: developerMode, onDeveloperModeChange: onDeveloperModeChange, children: developerTools }), _jsx(ShellTimeline, { hidden: experience.hideTimeline === true, experience: experience, snapshot: snapshot, timeLook: timeLook, onTogglePlayback: onTogglePlayback, onRateChange: onRateChange, paceAuto: paceAuto, onSeek: seek, panels: storyPanels, openPanelId: openPanelId, onPanelOpen: openPanelFromTimeline, onEventSeek: seekToEvent, onEventInfo: (event) => setInfo({ kind: "event", id: event.id }), onWindowSeek: seekToWindow, onWindowInfo: (window) => setInfo({ kind: "window", id: window.id }), glowLook: timelineGlow, infoPanelId: infoPanelId, drawer: phone ? { open: timelineOpen, onOpenChange: openTimeline, swipeThresholdPx: phoneLayout.swipeThresholdPx } : undefined })] }));
380
387
  }
@@ -7,7 +7,7 @@ export function ObjectControls({ experience, timeUtcMs, selectedObjectId, active
7
7
  const selectedAvailable = selected !== undefined && isObjectAvailable(selected, timeUtcMs);
8
8
  const infoLabel = selected?.label ?? selectedFigure?.label;
9
9
  const overview = findCameraPreset(experience, "overview");
10
- const focus = selected === undefined ? undefined : focusPresetFor(experience, selected);
10
+ const focus = selected === undefined ? undefined : experience.focusListed === true ? findCameraPreset(experience, "focus", selected.id) : focusPresetFor(experience, selected);
11
11
  const follow = selected === undefined ? undefined : findCameraPreset(experience, "follow", selected.id);
12
12
  const lookOut = selected === undefined ? undefined : findCameraPreset(experience, "lookOut", selected.id);
13
13
  const related = selected === undefined ? [] : relatedObjects(experience, selected.id);
@@ -1,6 +1,7 @@
1
1
  import type { ClockSnapshot } from "../core/clock.js";
2
2
  import type { TimelineEvent } from "../core/events.js";
3
3
  import type { TimelineWindow } from "../core/timeWindow.js";
4
+ import { type TimeLook } from "./timelineModel.js";
4
5
  import { type TimelineGlowLook } from "./timelineGlow.js";
5
6
  import type { ExperienceConfig } from "./experience.js";
6
7
  import type { StoryPanel } from "./storyPanels.js";
@@ -27,6 +28,8 @@ interface Props {
27
28
  readonly onWindowInfo: (window: TimelineWindow) => void;
28
29
  /** How the activity glow looks (live settings); absent: the defaults. */
29
30
  readonly glowLook?: TimelineGlowLook;
31
+ /** The zone and precision every time reads in (the look `time`). Default UTC to the second. */
32
+ readonly timeLook?: TimeLook;
30
33
  /** On a phone the timeline has a drawer (speed slider, events) under its two lines; absent: the larger-screen bar. */
31
34
  readonly drawer?: {
32
35
  readonly open: boolean;
@@ -36,10 +39,11 @@ interface Props {
36
39
  /** The id of the information panel the event buttons open, made once per viewer by the shell. */
37
40
  readonly infoPanelId: string;
38
41
  }
39
- export declare function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChange, paceAuto, onSeek, panels, openPanelId, onPanelOpen, onEventSeek, onEventInfo, onWindowSeek, onWindowInfo, glowLook, drawer, infoPanelId }: Props): import("react").JSX.Element;
42
+ export declare function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChange, paceAuto, onSeek, panels, openPanelId, onPanelOpen, onEventSeek, onEventInfo, onWindowSeek, onWindowInfo, glowLook, timeLook: timeLookProp, drawer, infoPanelId }: Props): import("react").JSX.Element;
40
43
  interface ExpandedProps {
41
44
  readonly experience: ExperienceConfig;
42
45
  readonly snapshot: ClockSnapshot;
46
+ readonly timeLook?: TimeLook;
43
47
  readonly onEventSeek: (event: TimelineEvent) => void;
44
48
  readonly onEventInfo: (event: TimelineEvent) => void;
45
49
  readonly onWindowInfo: (window: TimelineWindow) => void;
@@ -49,5 +53,5 @@ interface ExpandedProps {
49
53
  * The timeline's expanded content: "Just happened / Up next / Inside" and the full event list.
50
54
  * On larger screens it opens from the Events button; the phone drawer shows the same content when expanded.
51
55
  */
52
- export declare function TimelineExpanded({ experience, snapshot, onEventSeek, onEventInfo, onWindowInfo, infoPanelId }: ExpandedProps): import("react").JSX.Element;
56
+ export declare function TimelineExpanded({ experience, snapshot, timeLook, onEventSeek, onEventInfo, onWindowInfo, infoPanelId }: ExpandedProps): import("react").JSX.Element;
53
57
  export {};
@@ -1,6 +1,6 @@
1
1
  import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { useEffect, useId, useMemo, useRef, useState } from "react";
3
- import { eventContextAt, formatUtcTimestamp, formatWindowRate, navigationStops, windowContextAt, timePositionPercent, speedsOf, TIMELINE_STEP_MS, clampToBounds, formatRateCompact, formatRate, groupMarkers } from "./timelineModel.js";
3
+ import { DEFAULT_TIME_LOOK, withDefaultTime, eventContextAt, formatTime, formatUtcTimestamp, formatWindowRate, navigationStops, windowContextAt, timePositionPercent, speedsOf, TIMELINE_STEP_MS, clampToBounds, formatRateCompact, formatRate, groupMarkers } from "./timelineModel.js";
4
4
  import { activityAt, DEFAULT_TIMELINE_GLOW, glowDescription, glowGradient, glowProfile, glowTooltip } from "./timelineGlow.js";
5
5
  import { Label } from "./Label.js";
6
6
  import { useDrawerSwipe } from "./useDrawerSwipe.js";
@@ -13,13 +13,18 @@ function autoLabel(showRate, rate) {
13
13
  function SpeedMenu({ speeds, rate, paceAuto, compact, onRateChange }) {
14
14
  return (_jsxs("label", { className: "timeline-speed", children: [_jsx("span", { children: "Playback rate" }), _jsxs("select", { "aria-label": "Playback speed", title: "Playback speed", value: paceAuto === true ? "auto" : rate, onChange: (event) => onRateChange(event.target.value === "auto" ? "auto" : Number(event.target.value)), children: [paceAuto !== undefined && _jsx("option", { value: "auto", children: autoLabel(paceAuto && !compact, rate) }), speeds.map((speed) => _jsx("option", { value: speed.rate, children: compact ? formatRateCompact(speed.rate) : speed.label }, speed.rate))] })] }));
15
15
  }
16
+ /** The timestamp as the narrow bar shows it: UTC ISO text without its seconds and `T`; a zone's text as it is. */
17
+ function shortTimestamp(timestamp, timeLook) {
18
+ return timeLook.zone === "UTC" ? timestamp.slice(0, 16).replace("T", " ") : timestamp;
19
+ }
16
20
  /** The seek slider's spoken value: the time, with the activity window and its rate when one is running. */
17
- function seekValueText(timeUtcMs, activityNow) {
21
+ function seekValueText(timeUtcMs, activityNow, timeLook) {
18
22
  if (activityNow === null || activityNow.window.rate === undefined)
19
- return formatUtcTimestamp(timeUtcMs);
20
- return `${formatUtcTimestamp(timeUtcMs)}, ${activityNow.window.label}: ${formatWindowRate(activityNow.rate, activityNow.window.rate.unit)}`;
23
+ return formatTime(timeUtcMs, timeLook);
24
+ return `${formatTime(timeUtcMs, timeLook)}, ${activityNow.window.label}: ${formatWindowRate(activityNow.rate, activityNow.window.rate.unit)}`;
21
25
  }
22
- export function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChange, paceAuto, onSeek, panels = [], openPanelId = null, onPanelOpen, onEventSeek, onEventInfo, onWindowSeek, onWindowInfo, glowLook = DEFAULT_TIMELINE_GLOW, drawer, infoPanelId }) {
26
+ export function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChange, paceAuto, onSeek, panels = [], openPanelId = null, onPanelOpen, onEventSeek, onEventInfo, onWindowSeek, onWindowInfo, glowLook = DEFAULT_TIMELINE_GLOW, timeLook: timeLookProp, drawer, infoPanelId }) {
27
+ const timeLook = withDefaultTime(timeLookProp);
23
28
  const drawerId = `${useId()}-timeline-drawer`;
24
29
  const windows = experience.windows ?? [];
25
30
  const profile = useMemo(() => glowProfile(windows, experience.window), [windows, experience.window]);
@@ -28,7 +33,7 @@ export function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChan
28
33
  const [hoverTitle, setHoverTitle] = useState(null);
29
34
  const playedPercent = timePositionPercent(clampToBounds(snapshot.timeUtcMs, experience.window), experience.window);
30
35
  const activityNow = activityAt(windows, snapshot.timeUtcMs);
31
- const valueText = seekValueText(snapshot.timeUtcMs, activityNow);
36
+ const valueText = seekValueText(snapshot.timeUtcMs, activityNow, timeLook);
32
37
  const moveOnTrack = (event) => {
33
38
  if (profile === null)
34
39
  return;
@@ -46,7 +51,7 @@ export function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChan
46
51
  };
47
52
  const stopLabel = (direction, stop) => windows.length === 0 || stop === null ? `${direction} event` : `${direction}: ${stop.label}`;
48
53
  const speeds = speedsOf(experience.rates);
49
- const timestamp = formatUtcTimestamp(snapshot.timeUtcMs);
54
+ const timestamp = formatTime(snapshot.timeUtcMs, timeLook);
50
55
  const handle = useDrawerSwipe({
51
56
  thresholdPx: drawer?.swipeThresholdPx ?? 0,
52
57
  onTap: () => drawer?.onOpenChange(!drawer.open),
@@ -86,12 +91,12 @@ export function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChan
86
91
  }, children: [_jsx("span", { className: "timeline-glow-ahead" }), _jsx("span", { className: "timeline-glow-played", children: _jsx("span", { className: "timeline-glow-line" }) })] }), _jsx("div", { className: "timeline-markers", ref: markersRef, "aria-label": "Timeline event markers", children: groups.map((group) => group.members.length === 1
87
92
  ? renderMarker(group.members[0], group.positionPercent)
88
93
  : (_jsxs("div", { className: "timeline-marker-group", "data-align": group.positionPercent < 25 ? "start" : group.positionPercent > 75 ? "end" : "middle", style: { left: `${group.positionPercent}%` }, onKeyDown: (event) => { if (event.key === "Escape")
89
- setOpenGroup(null); }, children: [_jsx("button", { type: "button", className: "timeline-marker timeline-group-toggle", "aria-expanded": openGroup === group.members[0].key, "aria-label": `${group.members.length} markers close together: show list`, title: `${group.members.length} markers`, onClick: () => setOpenGroup((open) => (open === group.members[0].key ? null : group.members[0].key)), children: _jsx("span", { className: "timeline-group-count", children: group.members.length }) }), openGroup === group.members[0].key && (_jsx("ul", { className: "timeline-group-list", "aria-label": "Markers close together", children: group.members.map((member) => (_jsx("li", { children: _jsx("button", { type: "button", className: "timeline-group-item", "aria-label": member.ariaLabel, "data-time-utc-ms": member.timeUtcMs, "data-panel-id": member.kind === "panel" ? member.key : undefined, onClick: () => { member.activate(); setOpenGroup(null); }, children: member.text }) }, member.key))) }))] }, `group-${group.members[0].key}`))) }), _jsx("input", { type: "range", "aria-label": "Seek timeline", "aria-valuetext": valueText, min: experience.window.startUtcMs, max: experience.window.endUtcMs, step: TIMELINE_STEP_MS, value: clampToBounds(snapshot.timeUtcMs, experience.window), onChange: (event) => onSeek(Number(event.target.value)) })] }), _jsxs("div", { className: "timeline-bounds", "aria-hidden": "true", children: [_jsx("time", { dateTime: formatUtcTimestamp(experience.window.startUtcMs), children: formatUtcTimestamp(experience.window.startUtcMs).slice(0, 10) }), _jsx("time", { dateTime: formatUtcTimestamp(experience.window.endUtcMs), children: formatUtcTimestamp(experience.window.endUtcMs).slice(0, 10) })] })] }));
94
+ setOpenGroup(null); }, children: [_jsx("button", { type: "button", className: "timeline-marker timeline-group-toggle", "aria-expanded": openGroup === group.members[0].key, "aria-label": `${group.members.length} markers close together: show list`, title: `${group.members.length} markers`, onClick: () => setOpenGroup((open) => (open === group.members[0].key ? null : group.members[0].key)), children: _jsx("span", { className: "timeline-group-count", children: group.members.length }) }), openGroup === group.members[0].key && (_jsx("ul", { className: "timeline-group-list", "aria-label": "Markers close together", children: group.members.map((member) => (_jsx("li", { children: _jsx("button", { type: "button", className: "timeline-group-item", "aria-label": member.ariaLabel, "data-time-utc-ms": member.timeUtcMs, "data-panel-id": member.kind === "panel" ? member.key : undefined, onClick: () => { member.activate(); setOpenGroup(null); }, children: member.text }) }, member.key))) }))] }, `group-${group.members[0].key}`))) }), _jsx("input", { type: "range", "aria-label": "Seek timeline", "aria-valuetext": valueText, min: experience.window.startUtcMs, max: experience.window.endUtcMs, step: TIMELINE_STEP_MS, value: clampToBounds(snapshot.timeUtcMs, experience.window), onChange: (event) => onSeek(Number(event.target.value)) })] }), _jsxs("div", { className: "timeline-bounds", "aria-hidden": "true", children: [_jsx("time", { dateTime: formatUtcTimestamp(experience.window.startUtcMs), children: formatTime(experience.window.startUtcMs, { ...timeLook, precision: "day" }) }), _jsx("time", { dateTime: formatUtcTimestamp(experience.window.endUtcMs), children: formatTime(experience.window.endUtcMs, { ...timeLook, precision: "day" }) })] })] }));
90
95
  return (_jsxs("section", { className: "timeline-bar", "aria-label": "Timeline controls", "data-drawer-open": drawer?.open, children: [drawer !== undefined && (_jsx("button", { type: "button", className: "drawer-handle drawer-handle-top ui-bare", "aria-label": "Timeline drawer", "aria-expanded": drawer.open, "aria-controls": drawerId, ...handle, children: _jsx("span", {}) })), _jsxs("div", { className: "timeline-main-row", children: [_jsxs("div", { className: "timeline-transport", children: [_jsx("button", { type: "button", className: "timeline-play ui-icon ui-accent", title: snapshot.playing ? "Pause" : "Play", onClick: onTogglePlayback, "aria-label": snapshot.playing ? "Pause playback" : "Play playback", children: snapshot.playing ? _jsx(Symbol, { path: "M7 5h3.5v14H7zM13.5 5H17v14h-3.5z" }) : _jsx(Symbol, { path: "M7 5v14l12-7z" }) }), _jsx("button", { type: "button", className: "timeline-previous ui-icon ui-ghost", "aria-label": stopLabel("Previous", navigation.previous), title: stopLabel("Previous", navigation.previous), disabled: navigation.previous === null, onClick: () => { if (navigation.previous !== null)
91
96
  goToStop(navigation.previous); }, children: _jsx(Symbol, { path: "M6 5h2v14H6zM19 5v14L9 12z" }) }), _jsx("button", { type: "button", className: "timeline-next ui-icon ui-ghost", "aria-label": stopLabel("Next", navigation.next), title: stopLabel("Next", navigation.next), disabled: navigation.next === null, onClick: () => { if (navigation.next !== null)
92
- goToStop(navigation.next); }, children: _jsx(Symbol, { path: "M16 5h2v14h-2zM5 5v14l10-7z" }) })] }), _jsxs("time", { className: "timeline-time", dateTime: timestamp, "aria-label": timestamp, children: [_jsx("span", { className: "timeline-time-full", children: timestamp }), _jsx("span", { className: "timeline-time-short", "aria-hidden": "true", children: timestamp.slice(0, 16).replace("T", " ") })] }), _jsx(SpeedMenu, { speeds: speeds, rate: snapshot.rate, paceAuto: paceAuto, compact: drawer !== undefined, onRateChange: onRateChange }), scrubber, drawer === undefined && (_jsxs("details", { className: "timeline-event-list", children: [_jsxs("summary", { className: "ui-button", title: "Events: what just happened, what is next, and the full list", children: ["Events ", _jsxs("span", { children: ["(", experience.events.length, ")"] })] }), _jsx(TimelineExpanded, { experience: experience, snapshot: snapshot, onEventSeek: onEventSeek, onEventInfo: onEventInfo, onWindowInfo: onWindowInfo, infoPanelId: infoPanelId })] }))] }), drawer !== undefined && (_jsx("div", { id: drawerId, className: "timeline-drawer", role: "region", "aria-label": "Timeline details", "data-open": drawer.open, onClick: (event) => { const closer = event.target.closest("[data-closes-drawer]"); if (closer !== null && closer.tagName !== "SELECT")
97
+ goToStop(navigation.next); }, children: _jsx(Symbol, { path: "M16 5h2v14h-2zM5 5v14l10-7z" }) })] }), _jsxs("time", { className: "timeline-time", dateTime: formatUtcTimestamp(snapshot.timeUtcMs), "aria-label": timestamp, children: [_jsx("span", { className: "timeline-time-full", children: timestamp }), _jsx("span", { className: "timeline-time-short", "aria-hidden": "true", children: shortTimestamp(timestamp, timeLook) })] }), _jsx(SpeedMenu, { speeds: speeds, rate: snapshot.rate, paceAuto: paceAuto, compact: drawer !== undefined, onRateChange: onRateChange }), scrubber, drawer === undefined && (_jsxs("details", { className: "timeline-event-list", children: [_jsxs("summary", { className: "ui-button", title: "Events: what just happened, what is next, and the full list", children: ["Events ", _jsxs("span", { children: ["(", experience.events.length, ")"] })] }), _jsx(TimelineExpanded, { experience: experience, snapshot: snapshot, timeLook: timeLook, onEventSeek: onEventSeek, onEventInfo: onEventInfo, onWindowInfo: onWindowInfo, infoPanelId: infoPanelId })] }))] }), drawer !== undefined && (_jsx("div", { id: drawerId, className: "timeline-drawer", role: "region", "aria-label": "Timeline details", "data-open": drawer.open, onClick: (event) => { const closer = event.target.closest("[data-closes-drawer]"); if (closer !== null && closer.tagName !== "SELECT")
93
98
  drawer.onOpenChange(false); }, children: _jsxs("div", { className: "timeline-drawer-body", children: [_jsxs("div", { className: "timeline-speed-slider", children: [_jsx("span", { "aria-hidden": "true", children: "Playback speed" }), _jsx("input", { type: "range", "aria-label": "Speed slider", "aria-valuetext": speedText, min: 0, max: speeds.length - 1, step: 1, value: speedIndex, onChange: (event) => { const next = speeds[Number(event.target.value)]; if (next !== undefined)
94
- onRateChange(next.rate); } }), _jsx("output", { children: speedText })] }), _jsx(TimelineExpanded, { experience: experience, snapshot: snapshot, onEventSeek: onEventSeek, onEventInfo: onEventInfo, onWindowInfo: onWindowInfo, infoPanelId: infoPanelId })] }) }))] }));
99
+ onRateChange(next.rate); } }), _jsx("output", { children: speedText })] }), _jsx(TimelineExpanded, { experience: experience, snapshot: snapshot, timeLook: timeLook, onEventSeek: onEventSeek, onEventInfo: onEventInfo, onWindowInfo: onWindowInfo, infoPanelId: infoPanelId })] }) }))] }));
95
100
  }
96
101
  /** A 24x24 filled symbol; the button around it carries the accessible name and tooltip. */
97
102
  function Symbol({ path }) {
@@ -101,11 +106,11 @@ function Symbol({ path }) {
101
106
  * The timeline's expanded content: "Just happened / Up next / Inside" and the full event list.
102
107
  * On larger screens it opens from the Events button; the phone drawer shows the same content when expanded.
103
108
  */
104
- export function TimelineExpanded({ experience, snapshot, onEventSeek, onEventInfo, onWindowInfo, infoPanelId }) {
109
+ export function TimelineExpanded({ experience, snapshot, timeLook = DEFAULT_TIME_LOOK, onEventSeek, onEventInfo, onWindowInfo, infoPanelId }) {
105
110
  const context = eventContextAt(experience.events, snapshot.timeUtcMs);
106
111
  const inside = windowContextAt(experience.windows ?? [], snapshot.timeUtcMs);
107
112
  return (_jsxs("div", { className: "timeline-expanded", children: [_jsxs("div", { className: "timeline-event-context", "aria-label": "Event context", children: [context.current === null
108
113
  ? _jsxs("span", { children: [_jsx("strong", { children: "Just happened:" }), " No event yet"] })
109
114
  : (_jsxs("button", { type: "button", className: "timeline-event-current ui-row", "data-closes-drawer": "", "aria-label": `Information about ${context.current.label}`, "aria-controls": infoPanelId, onClick: () => { if (context.current !== null)
110
- onEventInfo(context.current); }, children: [_jsx("strong", { children: "Just happened:" }), " ", context.current.label, " ", _jsx("span", { "aria-hidden": "true", children: "\u24D8" })] })), _jsxs("span", { children: [_jsx("strong", { children: "Up next:" }), " ", context.next?.label ?? "No upcoming event"] }), inside.map(({ window, rate }) => (_jsxs("button", { type: "button", className: "timeline-event-current timeline-window-current ui-row", "data-closes-drawer": "", "aria-label": `Information about ${window.label}`, "aria-controls": infoPanelId, onClick: () => onWindowInfo(window), children: [_jsx("strong", { children: "Inside:" }), " ", window.label, rate !== null && window.rate !== undefined && _jsxs(_Fragment, { children: [" \u2014 ", formatWindowRate(rate, window.rate.unit)] }), " ", _jsx("span", { "aria-hidden": "true", children: "\u24D8" })] }, window.id)))] }), _jsx("ol", { children: experience.events.map((event) => (_jsx("li", { children: _jsxs("button", { type: "button", className: "ui-row", "data-closes-drawer": "", "aria-current": context.current?.id === event.id ? "time" : undefined, onClick: () => { onEventSeek(event); onEventInfo(event); }, children: [_jsx("time", { dateTime: formatUtcTimestamp(event.timeUtcMs), children: formatUtcTimestamp(event.timeUtcMs) }), _jsx("span", { children: event.label })] }) }, event.id))) })] }));
115
+ onEventInfo(context.current); }, children: [_jsx("strong", { children: "Just happened:" }), " ", context.current.label, " ", _jsx("span", { "aria-hidden": "true", children: "\u24D8" })] })), _jsxs("span", { children: [_jsx("strong", { children: "Up next:" }), " ", context.next?.label ?? "No upcoming event"] }), inside.map(({ window, rate }) => (_jsxs("button", { type: "button", className: "timeline-event-current timeline-window-current ui-row", "data-closes-drawer": "", "aria-label": `Information about ${window.label}`, "aria-controls": infoPanelId, onClick: () => onWindowInfo(window), children: [_jsx("strong", { children: "Inside:" }), " ", window.label, rate !== null && window.rate !== undefined && _jsxs(_Fragment, { children: [" \u2014 ", formatWindowRate(rate, window.rate.unit)] }), " ", _jsx("span", { "aria-hidden": "true", children: "\u24D8" })] }, window.id)))] }), _jsx("ol", { children: experience.events.map((event) => (_jsx("li", { children: _jsxs("button", { type: "button", className: "ui-row", "data-closes-drawer": "", "aria-current": context.current?.id === event.id ? "time" : undefined, onClick: () => { onEventSeek(event); onEventInfo(event); }, children: [_jsx("time", { dateTime: formatUtcTimestamp(event.timeUtcMs), children: formatTime(event.timeUtcMs, timeLook) }), _jsx("span", { children: event.label })] }) }, event.id))) })] }));
111
116
  }
@@ -1,6 +1,6 @@
1
1
  import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { useEffect, useId, useMemo, useRef, useState } from "react";
3
- import { eventContextAt, formatUtcTimestamp, formatWindowRate, navigationStops, windowContextAt, timePositionPercent, speedsOf, TIMELINE_STEP_MS, clampToBounds, formatRateCompact, formatRate, groupMarkers } from "./timelineModel.js";
3
+ import { DEFAULT_TIME_LOOK, withDefaultTime, eventContextAt, formatTime, formatUtcTimestamp, formatWindowRate, navigationStops, windowContextAt, timePositionPercent, speedsOf, TIMELINE_STEP_MS, clampToBounds, formatRateCompact, formatRate, groupMarkers } from "./timelineModel.js";
4
4
  import { activityAt, DEFAULT_TIMELINE_GLOW, glowDescription, glowGradient, glowProfile, glowTooltip } from "./timelineGlow.js";
5
5
  import { Label } from "./Label.js";
6
6
  import { useDrawerSwipe } from "./useDrawerSwipe.js";
@@ -12,13 +12,18 @@ function autoLabel(showRate, rate) {
12
12
  function SpeedMenu({ speeds, rate, paceAuto, compact, onRateChange }) {
13
13
  return (_jsxs("label", { className: "timeline-speed", children: [_jsx("span", { children: "Playback rate" }), _jsxs("select", { "aria-label": "Playback speed", title: "Playback speed", value: paceAuto === true ? "auto" : rate, onChange: (event) => onRateChange(event.target.value === "auto" ? "auto" : Number(event.target.value)), children: [paceAuto !== undefined && _jsx("option", { value: "auto", children: autoLabel(paceAuto && !compact, rate) }), speeds.map((speed) => _jsx("option", { value: speed.rate, children: compact ? formatRateCompact(speed.rate) : speed.label }, speed.rate))] })] }));
14
14
  }
15
+ /** The timestamp as the narrow bar shows it: UTC ISO text without its seconds and `T`; a zone's text as it is. */
16
+ function shortTimestamp(timestamp, timeLook) {
17
+ return timeLook.zone === "UTC" ? timestamp.slice(0, 16).replace("T", " ") : timestamp;
18
+ }
15
19
  /** The seek slider's spoken value: the time, with the activity window and its rate when one is running. */
16
- function seekValueText(timeUtcMs, activityNow) {
20
+ function seekValueText(timeUtcMs, activityNow, timeLook) {
17
21
  if (activityNow === null || activityNow.window.rate === undefined)
18
- return formatUtcTimestamp(timeUtcMs);
19
- return `${formatUtcTimestamp(timeUtcMs)}, ${activityNow.window.label}: ${formatWindowRate(activityNow.rate, activityNow.window.rate.unit)}`;
22
+ return formatTime(timeUtcMs, timeLook);
23
+ return `${formatTime(timeUtcMs, timeLook)}, ${activityNow.window.label}: ${formatWindowRate(activityNow.rate, activityNow.window.rate.unit)}`;
20
24
  }
21
- export function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChange, paceAuto, onSeek, panels = [], openPanelId = null, onPanelOpen, onEventSeek, onEventInfo, onWindowSeek, onWindowInfo, glowLook = DEFAULT_TIMELINE_GLOW, drawer, infoPanelId }) {
25
+ export function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChange, paceAuto, onSeek, panels = [], openPanelId = null, onPanelOpen, onEventSeek, onEventInfo, onWindowSeek, onWindowInfo, glowLook = DEFAULT_TIMELINE_GLOW, timeLook: timeLookProp, drawer, infoPanelId }) {
26
+ const timeLook = withDefaultTime(timeLookProp);
22
27
  const drawerId = `${useId()}-timeline-drawer`;
23
28
  const windows = experience.windows ?? [];
24
29
  const profile = useMemo(() => glowProfile(windows, experience.window), [windows, experience.window]);
@@ -27,7 +32,7 @@ export function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChan
27
32
  const [hoverTitle, setHoverTitle] = useState(null);
28
33
  const playedPercent = timePositionPercent(clampToBounds(snapshot.timeUtcMs, experience.window), experience.window);
29
34
  const activityNow = activityAt(windows, snapshot.timeUtcMs);
30
- const valueText = seekValueText(snapshot.timeUtcMs, activityNow);
35
+ const valueText = seekValueText(snapshot.timeUtcMs, activityNow, timeLook);
31
36
  const moveOnTrack = (event) => {
32
37
  if (profile === null)
33
38
  return;
@@ -45,7 +50,7 @@ export function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChan
45
50
  };
46
51
  const stopLabel = (direction, stop) => windows.length === 0 || stop === null ? `${direction} event` : `${direction}: ${stop.label}`;
47
52
  const speeds = speedsOf(experience.rates);
48
- const timestamp = formatUtcTimestamp(snapshot.timeUtcMs);
53
+ const timestamp = formatTime(snapshot.timeUtcMs, timeLook);
49
54
  const handle = useDrawerSwipe({
50
55
  thresholdPx: drawer?.swipeThresholdPx ?? 0,
51
56
  onTap: () => drawer?.onOpenChange(!drawer.open),
@@ -85,12 +90,12 @@ export function TimelineBar({ experience, snapshot, onTogglePlayback, onRateChan
85
90
  }, children: [_jsx("span", { className: "timeline-glow-ahead" }), _jsx("span", { className: "timeline-glow-played", children: _jsx("span", { className: "timeline-glow-line" }) })] }), _jsx("div", { className: "timeline-markers", ref: markersRef, "aria-label": "Timeline event markers", children: groups.map((group) => group.members.length === 1
86
91
  ? renderMarker(group.members[0], group.positionPercent)
87
92
  : (_jsxs("div", { className: "timeline-marker-group", "data-align": group.positionPercent < 25 ? "start" : group.positionPercent > 75 ? "end" : "middle", style: { left: `${group.positionPercent}%` }, onKeyDown: (event) => { if (event.key === "Escape")
88
- setOpenGroup(null); }, children: [_jsx("button", { type: "button", className: "timeline-marker timeline-group-toggle", "aria-expanded": openGroup === group.members[0].key, "aria-label": `${group.members.length} markers close together: show list`, title: `${group.members.length} markers`, onClick: () => setOpenGroup((open) => (open === group.members[0].key ? null : group.members[0].key)), children: _jsx("span", { className: "timeline-group-count", children: group.members.length }) }), openGroup === group.members[0].key && (_jsx("ul", { className: "timeline-group-list", "aria-label": "Markers close together", children: group.members.map((member) => (_jsx("li", { children: _jsx("button", { type: "button", className: "timeline-group-item", "aria-label": member.ariaLabel, "data-time-utc-ms": member.timeUtcMs, "data-panel-id": member.kind === "panel" ? member.key : undefined, onClick: () => { member.activate(); setOpenGroup(null); }, children: member.text }) }, member.key))) }))] }, `group-${group.members[0].key}`))) }), _jsx("input", { type: "range", "aria-label": "Seek timeline", "aria-valuetext": valueText, min: experience.window.startUtcMs, max: experience.window.endUtcMs, step: TIMELINE_STEP_MS, value: clampToBounds(snapshot.timeUtcMs, experience.window), onChange: (event) => onSeek(Number(event.target.value)) })] }), _jsxs("div", { className: "timeline-bounds", "aria-hidden": "true", children: [_jsx("time", { dateTime: formatUtcTimestamp(experience.window.startUtcMs), children: formatUtcTimestamp(experience.window.startUtcMs).slice(0, 10) }), _jsx("time", { dateTime: formatUtcTimestamp(experience.window.endUtcMs), children: formatUtcTimestamp(experience.window.endUtcMs).slice(0, 10) })] })] }));
93
+ setOpenGroup(null); }, children: [_jsx("button", { type: "button", className: "timeline-marker timeline-group-toggle", "aria-expanded": openGroup === group.members[0].key, "aria-label": `${group.members.length} markers close together: show list`, title: `${group.members.length} markers`, onClick: () => setOpenGroup((open) => (open === group.members[0].key ? null : group.members[0].key)), children: _jsx("span", { className: "timeline-group-count", children: group.members.length }) }), openGroup === group.members[0].key && (_jsx("ul", { className: "timeline-group-list", "aria-label": "Markers close together", children: group.members.map((member) => (_jsx("li", { children: _jsx("button", { type: "button", className: "timeline-group-item", "aria-label": member.ariaLabel, "data-time-utc-ms": member.timeUtcMs, "data-panel-id": member.kind === "panel" ? member.key : undefined, onClick: () => { member.activate(); setOpenGroup(null); }, children: member.text }) }, member.key))) }))] }, `group-${group.members[0].key}`))) }), _jsx("input", { type: "range", "aria-label": "Seek timeline", "aria-valuetext": valueText, min: experience.window.startUtcMs, max: experience.window.endUtcMs, step: TIMELINE_STEP_MS, value: clampToBounds(snapshot.timeUtcMs, experience.window), onChange: (event) => onSeek(Number(event.target.value)) })] }), _jsxs("div", { className: "timeline-bounds", "aria-hidden": "true", children: [_jsx("time", { dateTime: formatUtcTimestamp(experience.window.startUtcMs), children: formatTime(experience.window.startUtcMs, { ...timeLook, precision: "day" }) }), _jsx("time", { dateTime: formatUtcTimestamp(experience.window.endUtcMs), children: formatTime(experience.window.endUtcMs, { ...timeLook, precision: "day" }) })] })] }));
89
94
  return (_jsxs("section", { className: "timeline-bar", "aria-label": "Timeline controls", "data-drawer-open": drawer?.open, children: [drawer !== undefined && (_jsx("button", { type: "button", className: "drawer-handle drawer-handle-top ui-bare", "aria-label": "Timeline drawer", "aria-expanded": drawer.open, "aria-controls": drawerId, ...handle, children: _jsx("span", {}) })), _jsxs("div", { className: "timeline-main-row", children: [_jsxs("div", { className: "timeline-transport", children: [_jsx("button", { type: "button", className: "timeline-play ui-icon ui-accent", title: snapshot.playing ? "Pause" : "Play", onClick: onTogglePlayback, "aria-label": snapshot.playing ? "Pause playback" : "Play playback", children: snapshot.playing ? _jsx(Symbol, { path: "M7 5h3.5v14H7zM13.5 5H17v14h-3.5z" }) : _jsx(Symbol, { path: "M7 5v14l12-7z" }) }), _jsx("button", { type: "button", className: "timeline-previous ui-icon ui-ghost", "aria-label": stopLabel("Previous", navigation.previous), title: stopLabel("Previous", navigation.previous), disabled: navigation.previous === null, onClick: () => { if (navigation.previous !== null)
90
95
  goToStop(navigation.previous); }, children: _jsx(Symbol, { path: "M6 5h2v14H6zM19 5v14L9 12z" }) }), _jsx("button", { type: "button", className: "timeline-next ui-icon ui-ghost", "aria-label": stopLabel("Next", navigation.next), title: stopLabel("Next", navigation.next), disabled: navigation.next === null, onClick: () => { if (navigation.next !== null)
91
- goToStop(navigation.next); }, children: _jsx(Symbol, { path: "M16 5h2v14h-2zM5 5v14l10-7z" }) })] }), _jsxs("time", { className: "timeline-time", dateTime: timestamp, "aria-label": timestamp, children: [_jsx("span", { className: "timeline-time-full", children: timestamp }), _jsx("span", { className: "timeline-time-short", "aria-hidden": "true", children: timestamp.slice(0, 16).replace("T", " ") })] }), _jsx(SpeedMenu, { speeds: speeds, rate: snapshot.rate, paceAuto: paceAuto, compact: drawer !== undefined, onRateChange: onRateChange }), scrubber, drawer === undefined && (_jsxs("details", { className: "timeline-event-list", children: [_jsxs("summary", { className: "ui-button", title: "Events: what just happened, what is next, and the full list", children: ["Events ", _jsxs("span", { children: ["(", experience.events.length, ")"] })] }), _jsx(TimelineExpanded, { experience: experience, snapshot: snapshot, onEventSeek: onEventSeek, onEventInfo: onEventInfo, onWindowInfo: onWindowInfo, infoPanelId: infoPanelId })] }))] }), drawer !== undefined && (_jsx("div", { id: drawerId, className: "timeline-drawer", role: "region", "aria-label": "Timeline details", "data-open": drawer.open, onClick: (event) => { const closer = event.target.closest("[data-closes-drawer]"); if (closer !== null && closer.tagName !== "SELECT")
96
+ goToStop(navigation.next); }, children: _jsx(Symbol, { path: "M16 5h2v14h-2zM5 5v14l10-7z" }) })] }), _jsxs("time", { className: "timeline-time", dateTime: formatUtcTimestamp(snapshot.timeUtcMs), "aria-label": timestamp, children: [_jsx("span", { className: "timeline-time-full", children: timestamp }), _jsx("span", { className: "timeline-time-short", "aria-hidden": "true", children: shortTimestamp(timestamp, timeLook) })] }), _jsx(SpeedMenu, { speeds: speeds, rate: snapshot.rate, paceAuto: paceAuto, compact: drawer !== undefined, onRateChange: onRateChange }), scrubber, drawer === undefined && (_jsxs("details", { className: "timeline-event-list", children: [_jsxs("summary", { className: "ui-button", title: "Events: what just happened, what is next, and the full list", children: ["Events ", _jsxs("span", { children: ["(", experience.events.length, ")"] })] }), _jsx(TimelineExpanded, { experience: experience, snapshot: snapshot, timeLook: timeLook, onEventSeek: onEventSeek, onEventInfo: onEventInfo, onWindowInfo: onWindowInfo, infoPanelId: infoPanelId })] }))] }), drawer !== undefined && (_jsx("div", { id: drawerId, className: "timeline-drawer", role: "region", "aria-label": "Timeline details", "data-open": drawer.open, onClick: (event) => { const closer = event.target.closest("[data-closes-drawer]"); if (closer !== null && closer.tagName !== "SELECT")
92
97
  drawer.onOpenChange(false); }, children: _jsxs("div", { className: "timeline-drawer-body", children: [_jsxs("div", { className: "timeline-speed-slider", children: [_jsx("span", { "aria-hidden": "true", children: "Playback speed" }), _jsx("input", { type: "range", "aria-label": "Speed slider", "aria-valuetext": speedText, min: 0, max: speeds.length - 1, step: 1, value: speedIndex, onChange: (event) => { const next = speeds[Number(event.target.value)]; if (next !== undefined)
93
- onRateChange(next.rate); } }), _jsx("output", { children: speedText })] }), _jsx(TimelineExpanded, { experience: experience, snapshot: snapshot, onEventSeek: onEventSeek, onEventInfo: onEventInfo, onWindowInfo: onWindowInfo, infoPanelId: infoPanelId })] }) }))] }));
98
+ onRateChange(next.rate); } }), _jsx("output", { children: speedText })] }), _jsx(TimelineExpanded, { experience: experience, snapshot: snapshot, timeLook: timeLook, onEventSeek: onEventSeek, onEventInfo: onEventInfo, onWindowInfo: onWindowInfo, infoPanelId: infoPanelId })] }) }))] }));
94
99
  }
95
100
  /** A 24x24 filled symbol; the button around it carries the accessible name and tooltip. */
96
101
  function Symbol({ path }) {
@@ -100,11 +105,11 @@ function Symbol({ path }) {
100
105
  * The timeline's expanded content: "Just happened / Up next / Inside" and the full event list.
101
106
  * On larger screens it opens from the Events button; the phone drawer shows the same content when expanded.
102
107
  */
103
- export function TimelineExpanded({ experience, snapshot, onEventSeek, onEventInfo, onWindowInfo, infoPanelId }) {
108
+ export function TimelineExpanded({ experience, snapshot, timeLook = DEFAULT_TIME_LOOK, onEventSeek, onEventInfo, onWindowInfo, infoPanelId }) {
104
109
  const context = eventContextAt(experience.events, snapshot.timeUtcMs);
105
110
  const inside = windowContextAt(experience.windows ?? [], snapshot.timeUtcMs);
106
111
  return (_jsxs("div", { className: "timeline-expanded", children: [_jsxs("div", { className: "timeline-event-context", "aria-label": "Event context", children: [context.current === null
107
112
  ? _jsxs("span", { children: [_jsx("strong", { children: "Just happened:" }), " No event yet"] })
108
113
  : (_jsxs("button", { type: "button", className: "timeline-event-current ui-row", "data-closes-drawer": "", "aria-label": `Information about ${context.current.label}`, "aria-controls": infoPanelId, onClick: () => { if (context.current !== null)
109
- onEventInfo(context.current); }, children: [_jsx("strong", { children: "Just happened:" }), " ", context.current.label, " ", _jsx("span", { "aria-hidden": "true", children: "\u24D8" })] })), _jsxs("span", { children: [_jsx("strong", { children: "Up next:" }), " ", context.next?.label ?? "No upcoming event"] }), inside.map(({ window, rate }) => (_jsxs("button", { type: "button", className: "timeline-event-current timeline-window-current ui-row", "data-closes-drawer": "", "aria-label": `Information about ${window.label}`, "aria-controls": infoPanelId, onClick: () => onWindowInfo(window), children: [_jsx("strong", { children: "Inside:" }), " ", window.label, rate !== null && window.rate !== undefined && _jsxs(_Fragment, { children: [" \u2014 ", formatWindowRate(rate, window.rate.unit)] }), " ", _jsx("span", { "aria-hidden": "true", children: "\u24D8" })] }, window.id)))] }), _jsx("ol", { children: experience.events.map((event) => (_jsx("li", { children: _jsxs("button", { type: "button", className: "ui-row", "data-closes-drawer": "", "aria-current": context.current?.id === event.id ? "time" : undefined, onClick: () => { onEventSeek(event); onEventInfo(event); }, children: [_jsx("time", { dateTime: formatUtcTimestamp(event.timeUtcMs), children: formatUtcTimestamp(event.timeUtcMs) }), _jsx("span", { children: event.label })] }) }, event.id))) })] }));
114
+ onEventInfo(context.current); }, children: [_jsx("strong", { children: "Just happened:" }), " ", context.current.label, " ", _jsx("span", { "aria-hidden": "true", children: "\u24D8" })] })), _jsxs("span", { children: [_jsx("strong", { children: "Up next:" }), " ", context.next?.label ?? "No upcoming event"] }), inside.map(({ window, rate }) => (_jsxs("button", { type: "button", className: "timeline-event-current timeline-window-current ui-row", "data-closes-drawer": "", "aria-label": `Information about ${window.label}`, "aria-controls": infoPanelId, onClick: () => onWindowInfo(window), children: [_jsx("strong", { children: "Inside:" }), " ", window.label, rate !== null && window.rate !== undefined && _jsxs(_Fragment, { children: [" \u2014 ", formatWindowRate(rate, window.rate.unit)] }), " ", _jsx("span", { "aria-hidden": "true", children: "\u24D8" })] }, window.id)))] }), _jsx("ol", { children: experience.events.map((event) => (_jsx("li", { children: _jsxs("button", { type: "button", className: "ui-row", "data-closes-drawer": "", "aria-current": context.current?.id === event.id ? "time" : undefined, onClick: () => { onEventSeek(event); onEventInfo(event); }, children: [_jsx("time", { dateTime: formatUtcTimestamp(event.timeUtcMs), children: formatTime(event.timeUtcMs, timeLook) }), _jsx("span", { children: event.label })] }) }, event.id))) })] }));
110
115
  }
@@ -85,6 +85,8 @@ export interface SkyFigureCard {
85
85
  export interface ExperienceConfig {
86
86
  readonly objects: readonly ExperienceObject[];
87
87
  readonly cameraPresets: readonly ExperienceCameraPreset[];
88
+ /** True: a Focus button shows only for an object with a focus preset (the scene chose its Focus choices); absent: every listed object has one. */
89
+ readonly focusListed?: boolean;
88
90
  /** The camera preset that is already in force when the shell opens (for example a Follow preset, so the scene starts following). Absent: none, as before. */
89
91
  readonly startCameraPresetId?: string;
90
92
  readonly events: readonly TimelineEvent[];
@@ -1,5 +1,6 @@
1
1
  import type { Provenance, ProvenanceSourceType } from "../core/provenance.js";
2
2
  import type { ExperienceConfig } from "./experience.js";
3
+ import { type TimeLook } from "./timelineModel.js";
3
4
  /** The badge text for each provenance status. The status is always written, never shown by colour alone. */
4
5
  export declare const PROVENANCE_STATUS: Readonly<Record<ProvenanceSourceType, string>>;
5
6
  export interface ProvenanceView extends Provenance {
@@ -40,4 +41,4 @@ export declare function provenanceView(provenance: Provenance, knownLimitations?
40
41
  * What the info panel shows for a configured object, event or window, or null when the id is not configured.
41
42
  * A window's rate and source depend on `timeUtcMs`, the clock.
42
43
  */
43
- export declare function infoView(experience: ExperienceConfig, target: InfoTarget, timeUtcMs?: number): InfoView | null;
44
+ export declare function infoView(experience: ExperienceConfig, target: InfoTarget, timeUtcMs?: number, timeLook?: TimeLook): InfoView | null;
@@ -1,7 +1,7 @@
1
1
  import { provenanceAt, rateAt, spanProvenanceAt } from "../core/timeWindow.js";
2
2
  import { findFeature } from "./bodyFeatures.js";
3
3
  import { skyFigureById } from "./objectModel.js";
4
- import { formatUtcTimestamp, formatWindowRate } from "./timelineModel.js";
4
+ import { DEFAULT_TIME_LOOK, formatTime, formatWindowRate } from "./timelineModel.js";
5
5
  /** The badge text for each provenance status. The status is always written, never shown by colour alone. */
6
6
  export const PROVENANCE_STATUS = {
7
7
  ephemeris: "Ephemeris",
@@ -17,27 +17,27 @@ export function provenanceView(provenance, knownLimitations = []) {
17
17
  * What the info panel shows for a configured object, event or window, or null when the id is not configured.
18
18
  * A window's rate and source depend on `timeUtcMs`, the clock.
19
19
  */
20
- export function infoView(experience, target, timeUtcMs) {
20
+ export function infoView(experience, target, timeUtcMs, timeLook = DEFAULT_TIME_LOOK) {
21
21
  if (target.kind === "window")
22
- return windowInfo(experience, target, timeUtcMs);
22
+ return windowInfo(experience, target, timeUtcMs, timeLook);
23
23
  if (target.kind === "feature")
24
24
  return featureInfo(experience, target);
25
25
  if (target.kind === "object")
26
26
  return objectInfo(experience, target, timeUtcMs);
27
- return eventInfo(experience, target);
27
+ return eventInfo(experience, target, timeLook);
28
28
  }
29
- function windowInfo(experience, target, timeUtcMs) {
29
+ function windowInfo(experience, target, timeUtcMs, timeLook) {
30
30
  const window = experience.windows?.find((candidate) => candidate.id === target.id);
31
31
  if (window === undefined)
32
32
  return null;
33
33
  const rate = timeUtcMs === undefined ? null : rateAt(window, timeUtcMs);
34
34
  const source = (timeUtcMs === undefined ? null : provenanceAt(window, timeUtcMs)) ?? experience.eventProvenance;
35
35
  const facts = [
36
- { label: "Starts", value: formatUtcTimestamp(window.startUtcMs) },
37
- { label: "Ends", value: formatUtcTimestamp(window.endUtcMs) },
36
+ { label: "Starts", value: formatTime(window.startUtcMs, timeLook) },
37
+ { label: "Ends", value: formatTime(window.endUtcMs, timeLook) },
38
38
  ];
39
39
  if (window.peakUtcMs !== undefined)
40
- facts.push({ label: "Peak", value: formatUtcTimestamp(window.peakUtcMs) });
40
+ facts.push({ label: "Peak", value: formatTime(window.peakUtcMs, timeLook) });
41
41
  if (window.rate !== undefined) {
42
42
  facts.push({ label: "Rate now", value: rate === null ? "Not available at this time" : formatWindowRate(rate, window.rate.unit) });
43
43
  }
@@ -70,7 +70,7 @@ function objectInfo(experience, target, timeUtcMs) {
70
70
  provenance: source === undefined ? null : provenanceView(source, object.knownLimitations),
71
71
  };
72
72
  }
73
- function eventInfo(experience, target) {
73
+ function eventInfo(experience, target, timeLook) {
74
74
  const event = experience.events.find((candidate) => candidate.id === target.id);
75
75
  if (event === undefined)
76
76
  return null;
@@ -78,7 +78,7 @@ function eventInfo(experience, target) {
78
78
  return {
79
79
  target,
80
80
  title: event.label,
81
- subtitle: formatUtcTimestamp(event.timeUtcMs),
81
+ subtitle: formatTime(event.timeUtcMs, timeLook),
82
82
  provenance: source === undefined ? null : provenanceView(source),
83
83
  };
84
84
  }
@@ -5,6 +5,16 @@ export { checkPanelPlayback, checkStoryPanel, DEFAULT_PANEL_PAUSE_SECONDS, MAX_P
5
5
  * A backward step or no movement crosses nothing, so loops and rewinds never open a panel.
6
6
  */
7
7
  export declare function panelsCrossed(panels: readonly StoryPanel[], previousMs: number, currentMs: number): readonly StoryPanel[];
8
+ /** 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. */
9
+ export declare function panelCloseMs(panel: Pick<StoryPanel, "timeUtcMs" | "closeAfterSeconds">, playbackSpan: number | undefined): number | null;
10
+ /** 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. */
11
+ export declare function panelArmedAt(panel: Pick<StoryPanel, "timeUtcMs" | "closeAfterSeconds">, playbackSpan: number | undefined, atMs: number): boolean;
12
+ /**
13
+ * 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)
14
+ * 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.
15
+ * With no span it never closes; a seek, a rewind, a pause or no movement closes nothing.
16
+ */
17
+ export declare function panelSpanPassed(panel: Pick<StoryPanel, "timeUtcMs" | "closeAfterSeconds">, playbackSpan: number | undefined, previousMs: number, currentMs: number, moving: boolean, armed?: boolean): boolean;
8
18
  /**
9
19
  * Decides, tick by tick, whether playback has just carried the clock across a panel. It remembers the last time it saw;
10
20
  * `rebase` moves that memory when a person seeks, so a jump is never read as playback and opens nothing.
@@ -12,7 +22,15 @@ export declare function panelsCrossed(panels: readonly StoryPanel[], previousMs:
12
22
  export declare class CrossingTracker {
13
23
  #private;
14
24
  constructor(startMs: number);
25
+ /** Whether the next tick counts as playback (the clock was playing on the last one); with `previousMs`, what `panelSpanPassed` needs before `advance` moves them. */
26
+ get wasPlaying(): boolean;
27
+ get previousMs(): number;
28
+ /** 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. */
29
+ get timeUtcMs(): number;
15
30
  rebase(timeUtcMs: number): void;
16
- /** The newest panel crossed since the last tick, or null: nothing crossed, the clock is not playing, or auto-open is off. */
31
+ /**
32
+ * The newest panel crossed since the last tick, or null: nothing crossed, the clock is not playing, or auto-open is off.
33
+ * 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.
34
+ */
17
35
  advance(panels: readonly StoryPanel[], timeUtcMs: number, playing: boolean, autoOpen: boolean): StoryPanel | null;
18
36
  }
@@ -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
- /** The newest panel crossed since the last tick, or null: nothing crossed, the clock is not playing, or auto-open is off. */
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): {