nucleus-core-ts 0.10.263 → 0.10.264

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 (26) hide show
  1. package/dist/.build-ok +1 -1
  2. package/dist/fe/components/Replay/_components/ReplayCaption/index.d.ts +1 -1
  3. package/dist/fe/components/Replay/_components/ReplayCaption/index.js +2 -2
  4. package/dist/fe/components/Replay/_components/ReplayCaption/types.d.ts +3 -1
  5. package/dist/fe/components/Replay/_components/ReplayPlayer/ReplayView.d.ts +2 -2
  6. package/dist/fe/components/Replay/_components/ReplayPlayer/ReplayView.js +9 -4
  7. package/dist/fe/components/Replay/_components/ReplayPlayer/types.d.ts +2 -0
  8. package/dist/fe/components/Replay/_hooks/index.d.ts +1 -0
  9. package/dist/fe/components/Replay/_hooks/index.js +1 -0
  10. package/dist/fe/components/Replay/_hooks/useEndCardDelay.d.ts +7 -0
  11. package/dist/fe/components/Replay/_hooks/useEndCardDelay.js +23 -0
  12. package/dist/fe/components/Replay/_store/replayStore.js +5 -1
  13. package/dist/fe/components/Replay/_types/player.d.ts +4 -1
  14. package/dist/fe/components/Replay/_utils/controller.js +25 -36
  15. package/dist/fe/components/Replay/_utils/controllerHandshake.d.ts +21 -0
  16. package/dist/fe/components/Replay/_utils/controllerHandshake.js +29 -0
  17. package/dist/fe/components/Replay/_utils/controllerReports.d.ts +3 -0
  18. package/dist/fe/components/Replay/_utils/controllerReports.js +4 -1
  19. package/dist/fe/components/Replay/_utils/controllerSeek.d.ts +30 -0
  20. package/dist/fe/components/Replay/_utils/controllerSeek.js +60 -0
  21. package/dist/fe/components/Replay/_utils/frameBridge.js +9 -2
  22. package/dist/fe/components/Replay/_utils/frameHold.d.ts +11 -2
  23. package/dist/fe/components/Replay/_utils/frameHold.js +9 -2
  24. package/dist/src/Client/Replay/channel/channel.d.ts +7 -0
  25. package/dist/src/Client/Replay/channel/channel.js +11 -0
  26. package/package.json +1 -1
package/dist/.build-ok CHANGED
@@ -1 +1 @@
1
- 0.10.263
1
+ 0.10.264
@@ -1,3 +1,3 @@
1
1
  import type { ReplayCaptionProps } from './types';
2
2
  /** The current step's caption and its position; the player's live region, so a screen reader hears each step. */
3
- export declare function ReplayCaption({ text, stepId, position, loading }: ReplayCaptionProps): import("react/jsx-runtime").JSX.Element;
3
+ export declare function ReplayCaption({ text, stepId, position, loading, fallback }: ReplayCaptionProps): import("react/jsx-runtime").JSX.Element;
@@ -6,7 +6,7 @@ import { useEffectEvent, useRef } from 'react';
6
6
  import { useReducedMotion } from '../../../DemoFilm/_hooks/useReducedMotion';
7
7
  import { REPLAY_COPY } from '../../_utils/copy';
8
8
  gsap.registerPlugin(useGSAP);
9
- /** The current step's caption and its position; the player's live region, so a screen reader hears each step. */ export function ReplayCaption({ text, stepId, position, loading }) {
9
+ /** The current step's caption and its position; the player's live region, so a screen reader hears each step. */ export function ReplayCaption({ text, stepId, position, loading, fallback }) {
10
10
  const reduced = useReducedMotion();
11
11
  const body = useRef(null);
12
12
  const enter = useEffectEvent(()=>{
@@ -42,7 +42,7 @@ gsap.registerPlugin(useGSAP);
42
42
  /*#__PURE__*/ _jsx("p", {
43
43
  ref: body,
44
44
  className: "nc-replay__text",
45
- children: text || (loading ? REPLAY_COPY.loadingChapter : REPLAY_COPY.idle)
45
+ children: text || (loading ? REPLAY_COPY.loadingChapter : fallback || REPLAY_COPY.idle)
46
46
  })
47
47
  ]
48
48
  });
@@ -3,8 +3,10 @@ export interface ReplayCaptionProps {
3
3
  text: string;
4
4
  /** Identifies the step so the caption animates when it changes. */
5
5
  stepId: string | null;
6
- /** Playing but no step has started yet (a chapter was just opened): show that, not the idle line. */
6
+ /** A seek is rebuilding the frame: the only time the caption says a chapter is loading. */
7
7
  loading: boolean;
8
+ /** What to say when no step caption is on screen: the current chapter's title; null before play, for the idle line. */
9
+ fallback: string | null;
8
10
  /** 1-based position among the recording's steps; null before the first step. */
9
11
  position: {
10
12
  index: number;
@@ -1,10 +1,10 @@
1
1
  import type { ReplayPlayer } from '../../_types';
2
2
  import type { ReplayPlayerProps } from './types';
3
- interface ReplayViewProps extends Pick<ReplayPlayerProps, 'theme' | 'onContinue' | 'continueLabel' | 'className'> {
3
+ interface ReplayViewProps extends Pick<ReplayPlayerProps, 'theme' | 'onContinue' | 'continueLabel' | 'className' | 'endCardDelayMs'> {
4
4
  player: ReplayPlayer;
5
5
  /** Start over with a fresh manifest request (a failure before the manifest loaded). */
6
6
  onReload: () => void;
7
7
  }
8
8
  /** The player's screen for one state of a `ReplayPlayer`: skeleton, stage with captions and controls, failure, end. */
9
- export declare function ReplayView({ player, theme, onContinue, continueLabel, className, onReload }: ReplayViewProps): import("react/jsx-runtime").JSX.Element;
9
+ export declare function ReplayView(props: ReplayViewProps): import("react/jsx-runtime").JSX.Element;
10
10
  export {};
@@ -1,5 +1,6 @@
1
1
  'use client';
2
2
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
+ import { END_CARD_DELAY_MS, useEndCardDelay } from '../../_hooks/useEndCardDelay';
3
4
  import { REPLAY_CSS } from '../../_utils/replayCss';
4
5
  import { manifestLocales, stepPosition } from '../../_utils/replayProgress';
5
6
  import { pickLocalized } from '../../_utils/frameUrl';
@@ -10,9 +11,11 @@ import { ReplayEnded } from '../ReplayEnded';
10
11
  import { ReplayFailureCard } from '../ReplayFailure';
11
12
  import { ReplaySkeleton } from '../ReplaySkeleton';
12
13
  import { ReplayStage } from '../ReplayStage';
13
- /** The player's screen for one state of a `ReplayPlayer`: skeleton, stage with captions and controls, failure, end. */ export function ReplayView({ player, theme, onContinue, continueLabel, className, onReload }) {
14
+ /** The player's screen for one state of a `ReplayPlayer`: skeleton, stage with captions and controls, failure, end. */ export function ReplayView(props) {
15
+ const { player, theme, onContinue, continueLabel, className, onReload } = props;
14
16
  const { state } = player;
15
17
  const { manifest, status, failure, locale } = state;
18
+ const showEnd = useEndCardDelay(status === 'ended', props.endCardDelayMs ?? END_CARD_DELAY_MS);
16
19
  if (manifest === null) {
17
20
  if (failure === null) return /*#__PURE__*/ _jsx(ReplaySkeleton, {});
18
21
  return /*#__PURE__*/ _jsxs("div", {
@@ -38,10 +41,11 @@ import { ReplayStage } from '../ReplayStage';
38
41
  });
39
42
  }
40
43
  const first = manifest.chapters[0];
44
+ const chapter = manifest.chapters.find((item)=>item.id === state.chapterId);
41
45
  const overlay = status === 'failed' && failure ? /*#__PURE__*/ _jsx(ReplayFailureCard, {
42
46
  reason: failure.reason,
43
47
  onRetry: player.play
44
- }) : status === 'ended' ? /*#__PURE__*/ _jsx(ReplayEnded, {
48
+ }) : showEnd ? /*#__PURE__*/ _jsx(ReplayEnded, {
45
49
  onWatchAgain: restart,
46
50
  onContinue: onContinue,
47
51
  continueLabel: continueLabel
@@ -68,14 +72,15 @@ import { ReplayStage } from '../ReplayStage';
68
72
  rate: state.rate,
69
73
  chapterId: state.chapterId,
70
74
  onArrive: player.cursorArrived,
71
- loading: status === 'loading',
75
+ loading: status === 'loading' || state.preparing,
72
76
  children: overlay
73
77
  }),
74
78
  /*#__PURE__*/ _jsx(ReplayCaption, {
75
79
  text: pickLocalized(state.caption, locale),
76
80
  stepId: state.stepId,
77
81
  position: stepPosition(manifest, state.stepId),
78
- loading: status === 'playing'
82
+ loading: state.preparing,
83
+ fallback: status === 'ready' ? null : pickLocalized(chapter?.title ?? null, locale)
79
84
  }),
80
85
  /*#__PURE__*/ _jsx(ReplayControls, {
81
86
  status: status,
@@ -6,4 +6,6 @@ export interface ReplayPlayerProps extends ReplayPlayerOptions {
6
6
  onContinue?: () => void;
7
7
  continueLabel?: string;
8
8
  className?: string;
9
+ /** How long the last screen stays undimmed before the end card covers it; default 4000, 0 shows the card at once. */
10
+ endCardDelayMs?: number;
9
11
  }
@@ -1,3 +1,4 @@
1
1
  export * from './useReplayPlayer';
2
2
  export * from './useShimmer';
3
3
  export * from './useStageScale';
4
+ export * from './useEndCardDelay';
@@ -1,3 +1,4 @@
1
1
  export * from './useReplayPlayer';
2
2
  export * from './useShimmer';
3
3
  export * from './useStageScale';
4
+ export * from './useEndCardDelay';
@@ -0,0 +1,7 @@
1
+ /** How long the last screen of the tour stays undimmed before the end card covers it. */
2
+ export declare const END_CARD_DELAY_MS = 4000;
3
+ /**
4
+ * True once the tour has been over for `delayMs`. A tour that ends on the delivered product should let the visitor
5
+ * look at it: the card dims the stage, so it waits. With no delay it shows at once.
6
+ */
7
+ export declare function useEndCardDelay(ended: boolean, delayMs: number): boolean;
@@ -0,0 +1,23 @@
1
+ 'use client';
2
+ import { useEffect, useEffectEvent, useState } from 'react';
3
+ /** How long the last screen of the tour stays undimmed before the end card covers it. */ export const END_CARD_DELAY_MS = 4000;
4
+ /**
5
+ * True once the tour has been over for `delayMs`. A tour that ends on the delivered product should let the visitor
6
+ * look at it: the card dims the stage, so it waits. With no delay it shows at once.
7
+ */ export function useEndCardDelay(ended, delayMs) {
8
+ const [elapsed, setElapsed] = useState(false);
9
+ const arm = useEffectEvent(()=>{
10
+ if (!ended || delayMs <= 0) return undefined;
11
+ const id = setTimeout(()=>setElapsed(true), delayMs);
12
+ // Reset on the way out so a second ending (watch again, then the end) waits again instead of showing at once.
13
+ return ()=>{
14
+ clearTimeout(id);
15
+ setElapsed(false);
16
+ };
17
+ });
18
+ useEffect(()=>arm(), [
19
+ ended,
20
+ delayMs
21
+ ]);
22
+ return ended && (delayMs <= 0 || elapsed);
23
+ }
@@ -12,7 +12,8 @@ export const initialReplayState = {
12
12
  cursor: null,
13
13
  unanswered: [],
14
14
  skipped: [],
15
- failure: null
15
+ failure: null,
16
+ preparing: false
16
17
  };
17
18
  /** The store's methods as creators over a plain state object, so tests can run them without React. */ export const replayMethodCreators = {
18
19
  reset: (s)=>()=>{
@@ -74,6 +75,9 @@ export const initialReplayState = {
74
75
  },
75
76
  clearFailure: (s)=>()=>{
76
77
  s.failure = null;
78
+ },
79
+ setPreparing: (s)=>(preparing)=>{
80
+ s.preparing = preparing;
77
81
  }
78
82
  };
79
83
  /**
@@ -39,6 +39,8 @@ export type ReplayPlayerState = {
39
39
  /** Every action skipped so far (a public tour keeps playing); `skipped.length` is the diagnostic count. */
40
40
  skipped: ReplaySkip[];
41
41
  failure: ReplayFailure | null;
42
+ /** A seek is in flight: the frame is being rebuilt at the target chapter and must not be shown half-built. */
43
+ preparing: boolean;
42
44
  };
43
45
  export type ReplayPlayerMethods = {
44
46
  reset: () => void;
@@ -55,6 +57,7 @@ export type ReplayPlayerMethods = {
55
57
  reportSkipped: (skip: ReplaySkip) => void;
56
58
  fail: (failure: ReplayFailure) => void;
57
59
  clearFailure: () => void;
60
+ setPreparing: (preparing: boolean) => void;
58
61
  };
59
62
  /** What the controller reads and writes; the h-state store satisfies it, and so can a plain object in a test. */
60
63
  export type ReplayStoreApi = ReplayPlayerState & ReplayPlayerMethods;
@@ -84,7 +87,7 @@ export interface ReplayControllerOptions {
84
87
  };
85
88
  fetch?: (url: string) => Promise<Response>;
86
89
  listenWindow?: ReplayListenTarget;
87
- /** Real ms to wait for the frame's `ready` before failing; default 20000. */
90
+ /** Real ms to wait for the frame's `ready` before failing; default 20000. Also bounds a seek that reloads the frame. */
88
91
  readyTimeoutMs?: number;
89
92
  }
90
93
  export interface ReplayController {
@@ -1,7 +1,7 @@
1
1
  import { createNonce, envelopeFor, parseManifest, readFrameMessage, sendMessage } from '../../../../src/Client/Replay';
2
2
  import { createReportHandler, enterChapter } from './controllerReports';
3
- const HELLO_INTERVAL_MS = 500;
4
- const READY_TIMEOUT_MS = 20000;
3
+ import { createHandshake, READY_TIMEOUT_MS } from './controllerHandshake';
4
+ import { createSeekGate } from './controllerSeek';
5
5
  const MAX_RATE = 64;
6
6
  const realClock = {
7
7
  setTimeout: (run, ms)=>Number(setTimeout(run, ms)),
@@ -51,12 +51,8 @@ const realClock = {
51
51
  };
52
52
  const flush = ()=>{
53
53
  const seekAt = wants.seekAt;
54
- if (seekAt !== null) send((e)=>({
55
- ...e,
56
- type: 'seek',
57
- at: seekAt
58
- }));
59
54
  wants.seekAt = null;
55
+ if (seekAt !== null) seek.request(seekAt);
60
56
  const rate = wants.rate;
61
57
  if (rate !== null) send((e)=>({
62
58
  ...e,
@@ -68,9 +64,27 @@ const realClock = {
68
64
  type: 'play'
69
65
  }));
70
66
  };
67
+ const handshake = createHandshake({
68
+ after,
69
+ cancel,
70
+ send,
71
+ isReady: ()=>ready,
72
+ isDisposed: ()=>disposed,
73
+ readyTimeoutMs: options.readyTimeoutMs,
74
+ onTimeout: ()=>failWith('frame_timeout', null)
75
+ });
76
+ const seek = createSeekGate({
77
+ store,
78
+ send,
79
+ after,
80
+ cancel,
81
+ reloadTimeoutMs: options.readyTimeoutMs ?? READY_TIMEOUT_MS,
82
+ onStuck: ()=>failWith('frame_timeout', null)
83
+ });
71
84
  const handle = createReportHandler({
72
85
  store,
73
86
  send,
87
+ seek,
74
88
  isReady: ()=>ready,
75
89
  stopPlaying: ()=>{
76
90
  wants.playing = false;
@@ -78,11 +92,12 @@ const realClock = {
78
92
  onReady: (recordingId, preparing)=>{
79
93
  if (recordingId !== store.manifest?.id) return;
80
94
  if (preparing) {
81
- if (!ready) armGiveUp(); // alive but not ready: the wait starts over, play and seek stay queued
95
+ if (!ready) handshake.rearm(); // alive but not ready: the wait starts over, play and seek stay queued
82
96
  return;
83
97
  }
84
98
  const first = !ready;
85
99
  ready = true;
100
+ seek.frameReady();
86
101
  if (first) store.setStatus(wants.playing ? 'playing' : 'ready');
87
102
  else store.clearStep();
88
103
  flush();
@@ -102,28 +117,6 @@ const realClock = {
102
117
  if (message && !disposed) handle(message);
103
118
  };
104
119
  listen.addEventListener('message', onMessage);
105
- let giveUp = null;
106
- function armGiveUp() {
107
- if (giveUp !== null) cancel(giveUp);
108
- giveUp = after(options.readyTimeoutMs ?? READY_TIMEOUT_MS, ()=>{
109
- if (!ready) failWith('frame_timeout', null);
110
- });
111
- }
112
- const awaitFrame = ()=>{
113
- armGiveUp();
114
- const ask = ()=>{
115
- if (ready || disposed) {
116
- if (giveUp !== null) cancel(giveUp);
117
- return;
118
- }
119
- send((e)=>({
120
- ...e,
121
- type: 'hello'
122
- }));
123
- after(HELLO_INTERVAL_MS, ask);
124
- };
125
- ask();
126
- };
127
120
  const boot = async ()=>{
128
121
  const response = await load(options.manifestUrl).catch(()=>null);
129
122
  if (disposed) return;
@@ -138,7 +131,7 @@ const realClock = {
138
131
  return;
139
132
  }
140
133
  store.setManifest(parsed.value);
141
- awaitFrame();
134
+ handshake.begin();
142
135
  };
143
136
  void boot();
144
137
  const seekChapter = (chapterId)=>{
@@ -155,11 +148,7 @@ const realClock = {
155
148
  wants.seekAt = chapter.from;
156
149
  return;
157
150
  }
158
- send((e)=>({
159
- ...e,
160
- type: 'seek',
161
- at: chapter.from
162
- }));
151
+ seek.request(chapter.from);
163
152
  if (store.status === 'ended' || store.status === 'failed') store.setStatus('paused');
164
153
  };
165
154
  return {
@@ -0,0 +1,21 @@
1
+ import type { envelopeFor, ParentMessage } from '../../../../src/Client/Replay';
2
+ export declare const READY_TIMEOUT_MS = 20000;
3
+ export interface HandshakeDeps {
4
+ after: (ms: number, run: () => void) => number;
5
+ cancel: (id: number) => void;
6
+ send: (build: (envelope: ReturnType<typeof envelopeFor>) => ParentMessage) => void;
7
+ isReady: () => boolean;
8
+ isDisposed: () => boolean;
9
+ /** Real ms to wait for the frame's `ready` before giving up; default 20000. */
10
+ readyTimeoutMs?: number;
11
+ /** The frame never became ready. */
12
+ onTimeout: () => void;
13
+ }
14
+ export interface Handshake {
15
+ /** Starts saying hello until the frame is ready, with the give-up timer running. */
16
+ begin: () => void;
17
+ /** The frame is alive but still preparing: the wait for `ready` starts over. */
18
+ rearm: () => void;
19
+ }
20
+ /** The hello loop and its give-up timer: the frame's first announcement may reach no listener yet. */
21
+ export declare function createHandshake(deps: HandshakeDeps): Handshake;
@@ -0,0 +1,29 @@
1
+ const HELLO_INTERVAL_MS = 500;
2
+ export const READY_TIMEOUT_MS = 20000;
3
+ /** The hello loop and its give-up timer: the frame's first announcement may reach no listener yet. */ export function createHandshake(deps) {
4
+ let giveUp = null;
5
+ const rearm = ()=>{
6
+ if (giveUp !== null) deps.cancel(giveUp);
7
+ giveUp = deps.after(deps.readyTimeoutMs ?? READY_TIMEOUT_MS, ()=>{
8
+ if (!deps.isReady()) deps.onTimeout();
9
+ });
10
+ };
11
+ const ask = ()=>{
12
+ if (deps.isReady() || deps.isDisposed()) {
13
+ if (giveUp !== null) deps.cancel(giveUp);
14
+ return;
15
+ }
16
+ deps.send((e)=>({
17
+ ...e,
18
+ type: 'hello'
19
+ }));
20
+ deps.after(HELLO_INTERVAL_MS, ask);
21
+ };
22
+ return {
23
+ begin () {
24
+ rearm();
25
+ ask();
26
+ },
27
+ rearm
28
+ };
29
+ }
@@ -1,9 +1,12 @@
1
1
  import type { envelopeFor, FrameMessage, ParentMessage, ReplayChapter } from '../../../../src/Client/Replay';
2
2
  import type { ReplayStoreApi } from '../_types';
3
+ import type { SeekGate } from './controllerSeek';
3
4
  export type SendToFrame = (build: (envelope: ReturnType<typeof envelopeFor>) => ParentMessage) => void;
4
5
  export interface ReportDeps {
5
6
  store: ReplayStoreApi;
6
7
  send: SendToFrame;
8
+ /** Ticks before the frame acknowledged a seek are stale; `seeked` ends that window. */
9
+ seek: SeekGate;
7
10
  /** The frame announced itself for this recording. */
8
11
  /** `preparing`: the frame heard the hello but is still rebuilding its start state; it is not ready to play. */
9
12
  onReady: (recordingId: string, preparing: boolean) => void;
@@ -58,8 +58,11 @@ function chapterAt(manifest, at) {
58
58
  actionIndex: message.actionIndex
59
59
  });
60
60
  break;
61
+ case 'seeked':
62
+ deps.seek.acknowledged(message.reloading);
63
+ break;
61
64
  case 'tick':
62
- onTick(manifest, message.at, message.playing);
65
+ if (!deps.seek.isStale()) onTick(manifest, message.at, message.playing);
63
66
  break;
64
67
  case 'skipped':
65
68
  store.reportSkipped({
@@ -0,0 +1,30 @@
1
+ import type { ReplayStoreApi } from '../_types';
2
+ import type { SendToFrame } from './controllerReports';
3
+ export interface SeekGateDeps {
4
+ store: ReplayStoreApi;
5
+ send: SendToFrame;
6
+ after: (ms: number, run: () => void) => number;
7
+ cancel: (id: number) => void;
8
+ /** How long a reloading frame may take to report `ready` again before the player gives up on it. */
9
+ reloadTimeoutMs: number;
10
+ /** The reloaded frame never came back. */
11
+ onStuck: () => void;
12
+ }
13
+ export interface SeekGate {
14
+ /** Sends the seek and veils the stage until the target is reached. */
15
+ request: (at: number) => void;
16
+ /** The frame took the seek (`seeked`); `reloading` keeps the veil up until its next `ready`. */
17
+ acknowledged: (reloading: boolean) => void;
18
+ /** A frame reported ready: whatever seek was in flight is done. */
19
+ frameReady: () => void;
20
+ /** True between the seek and its acknowledgement: ticks in that window predate the seek. */
21
+ isStale: () => boolean;
22
+ }
23
+ /**
24
+ * Tracks every seek in flight. Seeking re-runs the earlier steps (`runPrelude`) inside the visible frame, and the frame
25
+ * has ticks queued from before the seek; both show up as a flash of rebuilding screen and, at the end of the tour, as
26
+ * a stale `ended` that outlives a restart. So the store says `preparing` from the seek until the frame is back.
27
+ * Two quick chapter clicks are two seeks and, on a reloading frame, two `ready`s: one shared flag let the first
28
+ * `ready` lift the veil while the second reload was still rebuilding, so the counts (acks owed, reloads owed) decide.
29
+ */
30
+ export declare function createSeekGate(deps: SeekGateDeps): SeekGate;
@@ -0,0 +1,60 @@
1
+ /** A frame that never acknowledges a seek (an older bridge) must not leave the stage veiled and the ticks muted for good. */ const ACK_TIMEOUT_MS = 3000;
2
+ /**
3
+ * Tracks every seek in flight. Seeking re-runs the earlier steps (`runPrelude`) inside the visible frame, and the frame
4
+ * has ticks queued from before the seek; both show up as a flash of rebuilding screen and, at the end of the tour, as
5
+ * a stale `ended` that outlives a restart. So the store says `preparing` from the seek until the frame is back.
6
+ * Two quick chapter clicks are two seeks and, on a reloading frame, two `ready`s: one shared flag let the first
7
+ * `ready` lift the veil while the second reload was still rebuilding, so the counts (acks owed, reloads owed) decide.
8
+ */ export function createSeekGate(deps) {
9
+ const { store } = deps;
10
+ let acksOwed = 0;
11
+ let readiesOwed = 0;
12
+ let guard = null;
13
+ const clearGuard = ()=>{
14
+ if (guard !== null) deps.cancel(guard);
15
+ guard = null;
16
+ };
17
+ const done = ()=>{
18
+ acksOwed = 0;
19
+ readiesOwed = 0;
20
+ clearGuard();
21
+ store.setPreparing(false);
22
+ };
23
+ const armReloadGuard = ()=>{
24
+ clearGuard();
25
+ guard = deps.after(deps.reloadTimeoutMs, ()=>{
26
+ const wasPreparing = store.preparing;
27
+ done();
28
+ if (wasPreparing) deps.onStuck();
29
+ });
30
+ };
31
+ return {
32
+ request (at) {
33
+ acksOwed += 1;
34
+ store.setPreparing(true);
35
+ clearGuard();
36
+ guard = deps.after(ACK_TIMEOUT_MS, done);
37
+ deps.send((e)=>({
38
+ ...e,
39
+ type: 'seek',
40
+ at
41
+ }));
42
+ },
43
+ acknowledged (reloading) {
44
+ // An ack after the new frame's `ready` (or after the timeout) is about a seek that is already over.
45
+ if (acksOwed === 0) return;
46
+ acksOwed -= 1;
47
+ if (reloading) readiesOwed += 1;
48
+ if (acksOwed === 0 && readiesOwed === 0) return done();
49
+ if (readiesOwed > 0) armReloadGuard();
50
+ },
51
+ frameReady () {
52
+ // A `ready` that beats its ack (no reload owed yet) closes whatever was in flight, as before.
53
+ if (readiesOwed === 0) return done();
54
+ readiesOwed -= 1;
55
+ if (acksOwed === 0 && readiesOwed === 0) return done();
56
+ armReloadGuard();
57
+ },
58
+ isStale: ()=>acksOwed > 0
59
+ };
60
+ }
@@ -18,7 +18,7 @@ const MAX_KEY_LENGTH = 200;
18
18
  ].sort((a, b)=>a.at - b.at);
19
19
  let generation = 0;
20
20
  let abortWait = ()=>{};
21
- const clock = createFrameHold(timeline);
21
+ const clock = createFrameHold(timeline, ()=>tick());
22
22
  // True while the state before the start chapter is rebuilt: ticks stop, only the hello is answered (`preparing`).
23
23
  let preluding = false;
24
24
  let stopped = false;
@@ -48,7 +48,7 @@ const MAX_KEY_LENGTH = 200;
48
48
  ...e,
49
49
  type: 'tick',
50
50
  at: timeline.now(),
51
- playing: timeline.isPlaying()
51
+ playing: clock.isPlaying()
52
52
  }));
53
53
  };
54
54
  const settle = options.settle ?? (()=>new Promise((resolve)=>void win.setTimeout(resolve, 0)));
@@ -130,6 +130,13 @@ const MAX_KEY_LENGTH = 200;
130
130
  if (!chapter) return;
131
131
  restartAt(chapter);
132
132
  options.onSeek?.(chapter);
133
+ const reloading = options.onSeek !== undefined;
134
+ send((e)=>({
135
+ ...e,
136
+ type: 'seeked',
137
+ at: chapter.from,
138
+ reloading
139
+ }));
133
140
  };
134
141
  const onMessage = (event)=>{
135
142
  const message = readParentMessage({
@@ -6,6 +6,15 @@ export interface FrameHold {
6
6
  play: () => void;
7
7
  /** The parent pressed pause: the release no longer plays. */
8
8
  pause: () => void;
9
+ /**
10
+ * What the visitor asked for: true while a hold has the timeline paused for a pointer action and plays it again
11
+ * after. `timeline.isPlaying()` is false for that whole span, so ticks reporting it flipped the button to Play
12
+ * in the middle of a running tour.
13
+ */
14
+ isPlaying: () => boolean;
9
15
  }
10
- /** A hold pauses the clock for an action and plays it again after, unless the visitor paused meanwhile. */
11
- export declare function createFrameHold(timeline: Timeline): FrameHold;
16
+ /**
17
+ * A hold pauses the clock for an action and plays it again after, unless the visitor paused meanwhile.
18
+ * `intentChanged` runs when the visitor's play or pause changes what the clock is meant to do.
19
+ */
20
+ export declare function createFrameHold(timeline: Timeline, intentChanged?: () => void): FrameHold;
@@ -1,4 +1,7 @@
1
- /** A hold pauses the clock for an action and plays it again after, unless the visitor paused meanwhile. */ export function createFrameHold(timeline) {
1
+ /**
2
+ * A hold pauses the clock for an action and plays it again after, unless the visitor paused meanwhile.
3
+ * `intentChanged` runs when the visitor's play or pause changes what the clock is meant to do.
4
+ */ export function createFrameHold(timeline, intentChanged = ()=>{}) {
2
5
  let held = false;
3
6
  let resumeAfterHold = false;
4
7
  return {
@@ -15,10 +18,14 @@
15
18
  play () {
16
19
  if (held) resumeAfterHold = true;
17
20
  else timeline.play();
21
+ // Inside a hold the timeline does not move, so nothing else would tell the parent the intent changed.
22
+ intentChanged();
18
23
  },
19
24
  pause () {
20
25
  resumeAfterHold = false;
21
26
  timeline.pause();
22
- }
27
+ intentChanged();
28
+ },
29
+ isPlaying: ()=>held ? resumeAfterHold : timeline.isPlaying()
23
30
  };
24
31
  }
@@ -113,6 +113,13 @@ export declare const FrameMessageSchema: import("@sinclair/typebox").TUnion<[imp
113
113
  channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
114
114
  version: import("@sinclair/typebox").TLiteral<1>;
115
115
  nonce: import("@sinclair/typebox").TString;
116
+ }>, import("@sinclair/typebox").TObject<{
117
+ type: import("@sinclair/typebox").TLiteral<"seeked">;
118
+ at: import("@sinclair/typebox").TNumber;
119
+ reloading: import("@sinclair/typebox").TBoolean;
120
+ channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
121
+ version: import("@sinclair/typebox").TLiteral<1>;
122
+ nonce: import("@sinclair/typebox").TString;
116
123
  }>, import("@sinclair/typebox").TObject<{
117
124
  type: import("@sinclair/typebox").TLiteral<"unanswered">;
118
125
  key: import("@sinclair/typebox").TString;
@@ -130,6 +130,17 @@ const strict = {
130
130
  }),
131
131
  reason: FailureReasonSchema
132
132
  }, strict),
133
+ /**
134
+ * The frame took a seek: its timeline is at `at` now and every tick after this one is post-seek. Ticks queued
135
+ * before it are stale (a tick from the end of the tour, after a seek to chapter 1, re-opened "That is the whole tour").
136
+ * `reloading` is true when the app reloads the frame for the chapter (`onSeek`), so the stage stays veiled until
137
+ * the new frame reports `ready`; false when the frame already shows the chapter.
138
+ */ Type.Object({
139
+ ...envelope,
140
+ type: Type.Literal('seeked'),
141
+ at: ms,
142
+ reloading: Type.Boolean()
143
+ }, strict),
133
144
  /** A call no recorded answer covered (`replay_unanswered`): the audit fails on any. */ Type.Object({
134
145
  ...envelope,
135
146
  type: Type.Literal('unanswered'),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nucleus-core-ts",
3
- "version": "0.10.263",
3
+ "version": "0.10.264",
4
4
  "description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
5
5
  "author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
6
6
  "license": "SEE LICENSE IN LICENSE",