nucleus-core-ts 0.10.256 → 0.10.258

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 (27) hide show
  1. package/dist/.build-ok +1 -1
  2. package/dist/fe/components/Replay/_components/ReplayControls/index.js +4 -3
  3. package/dist/fe/components/Replay/_components/ReplayCursor/index.js +5 -1
  4. package/dist/fe/components/Replay/_components/ReplayStage/index.js +1 -1
  5. package/dist/fe/components/Replay/_types/frame.d.ts +40 -0
  6. package/dist/fe/components/Replay/_types/frame.js +1 -0
  7. package/dist/fe/components/Replay/_types/index.d.ts +1 -0
  8. package/dist/fe/components/Replay/_types/index.js +1 -0
  9. package/dist/fe/components/Replay/_utils/copy.js +5 -5
  10. package/dist/fe/components/Replay/_utils/cursorMotion.d.ts +16 -2
  11. package/dist/fe/components/Replay/_utils/cursorMotion.js +42 -8
  12. package/dist/fe/components/Replay/_utils/frameBridge.d.ts +1 -34
  13. package/dist/fe/components/Replay/_utils/frameBridge.js +51 -25
  14. package/dist/fe/components/Replay/_utils/frameFocus.d.ts +8 -0
  15. package/dist/fe/components/Replay/_utils/frameFocus.js +15 -0
  16. package/dist/fe/components/Replay/_utils/frameHold.d.ts +11 -0
  17. package/dist/fe/components/Replay/_utils/frameHold.js +24 -0
  18. package/dist/fe/components/Replay/_utils/framePrelude.d.ts +24 -0
  19. package/dist/fe/components/Replay/_utils/framePrelude.js +36 -0
  20. package/dist/fe/components/Replay/_utils/stageViewport.d.ts +12 -8
  21. package/dist/fe/components/Replay/_utils/stageViewport.js +12 -9
  22. package/dist/src/Client/Replay/driver/input.js +9 -3
  23. package/dist/src/Client/Replay/driver/run.d.ts +12 -1
  24. package/dist/src/Client/Replay/driver/run.js +22 -6
  25. package/dist/src/Client/Replay/timeline/timeline.d.ts +5 -0
  26. package/dist/src/Client/Replay/timeline/timeline.js +8 -0
  27. package/package.json +1 -1
package/dist/.build-ok CHANGED
@@ -1 +1 @@
1
- 0.10.256
1
+ 0.10.258
@@ -12,7 +12,8 @@ const ICON = {
12
12
  /** Play or pause, restart, speed, and the language switch (only when the recording has more than one language). */ export function ReplayControls(props) {
13
13
  const { status, rate, locales, locale, onPlay, onPause, onRate, onLocale, onRestart } = props;
14
14
  const playing = status === 'playing';
15
- const idle = status === 'loading' || status === 'failed';
15
+ const idle = status === 'loading';
16
+ const noPlay = idle || status === 'failed';
16
17
  return /*#__PURE__*/ _jsxs("div", {
17
18
  className: "nc-replay__controls",
18
19
  role: "group",
@@ -23,7 +24,7 @@ const ICON = {
23
24
  type: "button",
24
25
  className: "nc-replay__btn",
25
26
  "data-primary": "",
26
- disabled: idle,
27
+ disabled: noPlay,
27
28
  onClick: playing ? onPause : onPlay,
28
29
  children: [
29
30
  /*#__PURE__*/ _jsx("svg", {
@@ -60,7 +61,7 @@ const ICON = {
60
61
  type: "button",
61
62
  className: "nc-replay__btn",
62
63
  "aria-pressed": rate === choice,
63
- disabled: idle,
64
+ disabled: noPlay,
64
65
  onClick: ()=>onRate(choice),
65
66
  children: rateLabel(choice)
66
67
  }, choice))
@@ -30,7 +30,10 @@ gsap.registerPlugin(useGSAP);
30
30
  });
31
31
  return;
32
32
  }
33
- const target = targetIn(cursor.box, scale);
33
+ const target = targetIn(cursor.box, scale, {
34
+ width: root.current?.clientWidth ?? 0,
35
+ height: root.current?.clientHeight ?? 0
36
+ });
34
37
  const els = {
35
38
  cursor: cursorEl,
36
39
  ring,
@@ -42,6 +45,7 @@ gsap.registerPlugin(useGSAP);
42
45
  from: last.current,
43
46
  rate,
44
47
  reduced: reduced || settled,
48
+ settled,
45
49
  onArrive: ()=>{
46
50
  if (!settled) onArrive(cursor.mark);
47
51
  }
@@ -18,7 +18,7 @@ import { ReplayVeil } from './ReplayVeil';
18
18
  * on the same spot of the layer.
19
19
  */ export function ReplayStage(props) {
20
20
  const { manifest, locale, frameSrc, frameRef, cursor, rate, onArrive, loading, children } = props;
21
- const frame = stageViewport(manifest.viewport);
21
+ const frame = stageViewport();
22
22
  const fit = useStageScale(frame);
23
23
  const [whole, setWhole] = useState(false);
24
24
  const world = useRef(null);
@@ -0,0 +1,40 @@
1
+ import type { ReplayChapter, ReplayManifest, Timeline, VisibleCheck, Win } from '../../../../src/Client/Replay';
2
+ import type { ReplayFrameTarget } from './player';
3
+ export interface ReplayFrameOptions {
4
+ /** The frame's own window: DOM for the driver, `message` events, timers. */
5
+ win: Win;
6
+ /** The embedding page's window: where messages go and the only source accepted. */
7
+ parent: ReplayFrameTarget;
8
+ origin: string;
9
+ /** The session nonce from the frame's URL (`readReplayNonce`). */
10
+ nonce: string;
11
+ manifest: ReplayManifest;
12
+ /** The realm's timeline: the one the clock, streams and `waitUntil` run on. */
13
+ timeline: Timeline;
14
+ /** Moves the product to a path of the app (its router); resolves true once it is there. */
15
+ navigate: (path: string) => Promise<boolean>;
16
+ /** Resolves when that frame of that stream has been delivered (the realm's streams own it). */
17
+ waitForFrame: (stream: string, seq: number) => Promise<void>;
18
+ /** Resolves when the page has settled between actions; defaults to one task. */
19
+ settle?: () => Promise<void>;
20
+ /** Subscribes to calls no recorded answer covered; the bridge reports each key to the parent. */
21
+ onUnanswered?: (listener: (key: string) => void) => () => void;
22
+ /** The parent asked for a chapter: the timeline already snapped; the app may reload the frame (`?chapter=`). */
23
+ onSeek?: (chapter: ReplayChapter) => void;
24
+ /** The chapter this frame was started at (`readReplayChapter`). */
25
+ startChapter?: string | null;
26
+ typingDelayMs?: number;
27
+ tickMs?: number;
28
+ pointTimeoutMs?: number;
29
+ targetTimeoutMs?: number;
30
+ visible?: VisibleCheck;
31
+ /**
32
+ * A step whose pointer action cannot be shown (the element is not on the screen) is skipped, logged to the console, and the
33
+ * tape plays on. Default true: a public page never stops its tour and never tells a visitor to contact the site owner.
34
+ * Set false to stop and report `step-failed` instead (a recorder's own check).
35
+ */
36
+ skipFailedSteps?: boolean;
37
+ }
38
+ export interface ReplayFrameHandle {
39
+ stop: () => void;
40
+ }
@@ -0,0 +1 @@
1
+ export { };
@@ -1 +1,2 @@
1
1
  export * from './player';
2
+ export * from './frame';
@@ -1 +1,2 @@
1
1
  export * from './player';
2
+ export * from './frame';
@@ -1,15 +1,15 @@
1
- const RETRY_OR_RERECORD = 'Try again from this chapter. If it repeats, the site owner has to record it again.';
1
+ const RETRY_OR_RERECORD = 'Try again from this chapter, or pick another chapter below.';
2
2
  const STOPPED = 'The walkthrough stopped at this step.';
3
3
  const FAILURES = {
4
4
  manifest_unreachable: {
5
5
  what: 'The recording could not be loaded.',
6
6
  means: 'There is nothing to play yet.',
7
- next: 'Check your connection and try again. If it keeps failing, the site owner has to republish the recording.'
7
+ next: 'Check your connection and try again. If it keeps failing, come back a little later.'
8
8
  },
9
9
  manifest_invalid: {
10
10
  what: 'The recording file is not in a format this player understands.',
11
11
  means: 'It cannot be played, and trying again will not change that.',
12
- next: 'The site owner has to record and publish it again.'
12
+ next: 'Reload the page. If it keeps failing, come back a little later.'
13
13
  },
14
14
  frame_timeout: {
15
15
  what: 'The product screen did not start in time.',
@@ -24,7 +24,7 @@ const FAILURES = {
24
24
  target_unsupported: {
25
25
  what: 'This step points at an element the player cannot operate.',
26
26
  means: STOPPED,
27
- next: 'The site owner has to record this step again.'
27
+ next: 'Try another chapter below, or reload the page.'
28
28
  },
29
29
  option_not_found: {
30
30
  what: 'A choice in this step is missing from the screen.',
@@ -44,7 +44,7 @@ const FAILURES = {
44
44
  step_unknown: {
45
45
  what: 'The recording refers to a step it does not contain.',
46
46
  means: 'It cannot be played to the end.',
47
- next: 'The site owner has to record and publish it again.'
47
+ next: 'Reload the page. If it keeps failing, come back a little later.'
48
48
  }
49
49
  };
50
50
  export function failureCopy(reason) {
@@ -16,8 +16,20 @@ export interface CursorTarget {
16
16
  height: number;
17
17
  };
18
18
  }
19
- /** The target's box scaled into the stage's pixels, with its centre. */
20
- export declare function targetIn(box: PointBox, scale: number): CursorTarget;
19
+ /** The drawn size of the view the ring lives in: a ring never leaves it, so the stage edge cannot clip it. */
20
+ export interface ViewBounds {
21
+ width: number;
22
+ height: number;
23
+ }
24
+ /** The box grown by the ring's gap, then pulled back inside the view (a target on the edge gets a ring that stops there). */
25
+ export declare function ringBox(box: {
26
+ x: number;
27
+ y: number;
28
+ width: number;
29
+ height: number;
30
+ }, bounds: ViewBounds | null): CursorTarget['box'];
31
+ /** The target's box scaled into the stage's pixels, with its centre and its ring box (kept inside `bounds`). */
32
+ export declare function targetIn(box: PointBox, scale: number, bounds?: ViewBounds | null): CursorTarget;
21
33
  /** How long a glide takes: longer for longer trips, shorter at a higher rate. */
22
34
  export declare function glideSeconds(distance: number, rate: number): number;
23
35
  export interface CursorMove {
@@ -29,6 +41,8 @@ export interface CursorMove {
29
41
  } | null;
30
42
  rate: number;
31
43
  reduced: boolean;
44
+ /** The press already happened (the stage was rescaled afterwards): the cursor is re-placed, the ring stays hidden. */
45
+ settled?: boolean;
32
46
  onArrive: () => void;
33
47
  }
34
48
  /**
@@ -3,8 +3,32 @@ const RING_GROW = 3;
3
3
  const GLIDE_MIN = 0.35;
4
4
  const GLIDE_MAX = 1.1;
5
5
  const REST = 0.18;
6
+ /** How long the ring stays after the click, and how long it takes to fade: it marks a press, not a place. */ const RING_HOLD = 0.7;
7
+ const RING_FADE = 0.35;
6
8
  const MIN_RATE = 0.25;
7
- /** The target's box scaled into the stage's pixels, with its centre. */ export function targetIn(box, scale) {
9
+ /** The box grown by the ring's gap, then pulled back inside the view (a target on the edge gets a ring that stops there). */ export function ringBox(box, bounds) {
10
+ const left = box.x - RING_GROW;
11
+ const top = box.y - RING_GROW;
12
+ const right = box.x + box.width + RING_GROW;
13
+ const bottom = box.y + box.height + RING_GROW;
14
+ if (!bounds || bounds.width <= 0 || bounds.height <= 0) {
15
+ return {
16
+ x: left,
17
+ y: top,
18
+ width: right - left,
19
+ height: bottom - top
20
+ };
21
+ }
22
+ const x = Math.max(0, left);
23
+ const y = Math.max(0, top);
24
+ return {
25
+ x,
26
+ y,
27
+ width: Math.max(0, Math.min(bounds.width, right) - x),
28
+ height: Math.max(0, Math.min(bounds.height, bottom) - y)
29
+ };
30
+ }
31
+ /** The target's box scaled into the stage's pixels, with its centre and its ring box (kept inside `bounds`). */ export function targetIn(box, scale, bounds = null) {
8
32
  const x = box.x * scale;
9
33
  const y = box.y * scale;
10
34
  const width = box.width * scale;
@@ -12,12 +36,12 @@ const MIN_RATE = 0.25;
12
36
  return {
13
37
  x: x + width / 2,
14
38
  y: y + height / 2,
15
- box: {
16
- x: x - RING_GROW,
17
- y: y - RING_GROW,
18
- width: width + RING_GROW * 2,
19
- height: height + RING_GROW * 2
20
- }
39
+ box: ringBox({
40
+ x,
41
+ y,
42
+ width,
43
+ height
44
+ }, bounds)
21
45
  };
22
46
  }
23
47
  /** How long a glide takes: longer for longer trips, shorter at a higher rate. */ export function glideSeconds(distance, rate) {
@@ -43,8 +67,13 @@ const MIN_RATE = 0.25;
43
67
  });
44
68
  gsap.set(els.ring, {
45
69
  ...target.box,
46
- opacity: 1
70
+ opacity: move.settled ? 0 : 1
47
71
  });
72
+ if (!move.settled) timeline.to(els.ring, {
73
+ opacity: 0,
74
+ duration: RING_FADE,
75
+ ease: 'power1.out'
76
+ }, RING_HOLD);
48
77
  move.onArrive();
49
78
  return timeline;
50
79
  }
@@ -94,5 +123,10 @@ const MIN_RATE = 0.25;
94
123
  duration: 0.6 / speed,
95
124
  ease: 'power2.out'
96
125
  }, seconds + REST);
126
+ timeline.to(els.ring, {
127
+ opacity: 0,
128
+ duration: RING_FADE,
129
+ ease: 'power1.out'
130
+ }, seconds + REST + RING_HOLD / speed);
97
131
  return timeline;
98
132
  }
@@ -1,37 +1,4 @@
1
- import { type ReplayChapter, type ReplayManifest, type Timeline, type VisibleCheck, type Win } from '../../../../src/Client/Replay';
2
- import type { ReplayFrameTarget } from '../_types';
3
- export interface ReplayFrameOptions {
4
- /** The frame's own window: DOM for the driver, `message` events, timers. */
5
- win: Win;
6
- /** The embedding page's window: where messages go and the only source accepted. */
7
- parent: ReplayFrameTarget;
8
- origin: string;
9
- /** The session nonce from the frame's URL (`readReplayNonce`). */
10
- nonce: string;
11
- manifest: ReplayManifest;
12
- /** The realm's timeline: the one the clock, streams and `waitUntil` run on. */
13
- timeline: Timeline;
14
- /** Moves the product to a path of the app (its router); resolves true once it is there. */
15
- navigate: (path: string) => Promise<boolean>;
16
- /** Resolves when that frame of that stream has been delivered (the realm's streams own it). */
17
- waitForFrame: (stream: string, seq: number) => Promise<void>;
18
- /** Resolves when the page has settled between actions; defaults to one task. */
19
- settle?: () => Promise<void>;
20
- /** Subscribes to calls no recorded answer covered; the bridge reports each key to the parent. */
21
- onUnanswered?: (listener: (key: string) => void) => () => void;
22
- /** The parent asked for a chapter: the timeline already snapped; the app may reload the frame (`?chapter=`). */
23
- onSeek?: (chapter: ReplayChapter) => void;
24
- /** The chapter this frame was started at (`readReplayChapter`). */
25
- startChapter?: string | null;
26
- typingDelayMs?: number;
27
- tickMs?: number;
28
- pointTimeoutMs?: number;
29
- targetTimeoutMs?: number;
30
- visible?: VisibleCheck;
31
- }
32
- export interface ReplayFrameHandle {
33
- stop: () => void;
34
- }
1
+ import type { ReplayFrameHandle, ReplayFrameOptions } from '../_types';
35
2
  /**
36
3
  * The frame side of a replay: answers the parent's hello, forwards play, pause, rate and seek to the timeline, runs
37
4
  * every step through the driver when the playhead reaches its `at`, and reports started, point, done, failed and
@@ -1,5 +1,8 @@
1
1
  import { envelopeFor, readParentMessage, runStep, sendMessage } from '../../../../src/Client/Replay';
2
+ import { hideDriverFocus } from './frameFocus';
3
+ import { createFrameHold } from './frameHold';
2
4
  import { createFramePoints } from './framePoints';
5
+ import { runPrelude } from './framePrelude';
3
6
  const TICK_MS = 250;
4
7
  const POINT_TIMEOUT_MS = 8000;
5
8
  const BASE_TYPING_DELAY_MS = 45;
@@ -15,19 +18,10 @@ const MAX_KEY_LENGTH = 200;
15
18
  ].sort((a, b)=>a.at - b.at);
16
19
  let generation = 0;
17
20
  let abortWait = ()=>{};
18
- // A hold pauses the clock for an action and plays it again after, unless the visitor paused meanwhile.
19
- let held = false;
20
- let resumeAfterHold = false;
21
- const hold = ()=>{
22
- if (held || !timeline.isPlaying()) return ()=>{};
23
- held = true;
24
- resumeAfterHold = true;
25
- timeline.pause();
26
- return ()=>{
27
- held = false;
28
- if (resumeAfterHold) timeline.play();
29
- };
30
- };
21
+ const clock = createFrameHold(timeline);
22
+ // True while the state before the start chapter is being rebuilt: the parent hears nothing and its messages wait.
23
+ let preluding = false;
24
+ let stopped = false;
31
25
  const send = (build)=>{
32
26
  sendMessage(options.parent, options.origin, build(envelopeFor(options.nonce)));
33
27
  };
@@ -36,12 +30,15 @@ const MAX_KEY_LENGTH = 200;
36
30
  type: 'ready',
37
31
  recordingId: manifest.id
38
32
  }));
39
- const tick = ()=>send((e)=>({
33
+ const tick = ()=>{
34
+ if (!preluding) send((e)=>({
40
35
  ...e,
41
36
  type: 'tick',
42
37
  at: timeline.now(),
43
38
  playing: timeline.isPlaying()
44
39
  }));
40
+ };
41
+ const settle = options.settle ?? (()=>new Promise((resolve)=>void win.setTimeout(resolve, 0)));
45
42
  const pointer = createFramePoints({
46
43
  setTimeout: (run, ms)=>win.setTimeout(run, ms),
47
44
  clearTimeout: (id)=>win.clearTimeout(id),
@@ -75,11 +72,12 @@ const MAX_KEY_LENGTH = 200;
75
72
  targetTimeoutMs: options.targetTimeoutMs,
76
73
  visible: options.visible,
77
74
  onPoint: (box)=>pointer.point(step.id, box),
78
- settle: options.settle ?? (()=>new Promise((resolve)=>void win.setTimeout(resolve, 0))),
75
+ settle,
79
76
  navigate: options.navigate,
80
77
  waitForFrame: options.waitForFrame,
81
78
  waitUntil: (at)=>timeline.waitUntil(at),
82
- hold
79
+ hold: clock.hold,
80
+ onSkip: options.skipFailedSteps === false ? undefined : ({ actionIndex, reason })=>win.console?.warn(`[replay] step ${step.id} action ${actionIndex} skipped: ${reason}`)
83
81
  });
84
82
  if (gen !== generation) return false;
85
83
  if (result.ok) {
@@ -130,18 +128,16 @@ const MAX_KEY_LENGTH = 200;
130
128
  peer: options.parent,
131
129
  nonce: options.nonce
132
130
  });
133
- if (!message) return;
131
+ if (!message || preluding) return;
134
132
  switch(message.type){
135
133
  case 'hello':
136
134
  announce();
137
135
  break;
138
136
  case 'play':
139
- if (held) resumeAfterHold = true;
140
- else timeline.play();
137
+ clock.play();
141
138
  break;
142
139
  case 'pause':
143
- resumeAfterHold = false;
144
- timeline.pause();
140
+ clock.pause();
145
141
  break;
146
142
  case 'rate':
147
143
  timeline.setRate(message.rate);
@@ -154,6 +150,7 @@ const MAX_KEY_LENGTH = 200;
154
150
  break;
155
151
  }
156
152
  };
153
+ const showFocus = hideDriverFocus(win);
157
154
  win.addEventListener('message', onMessage);
158
155
  const ticker = win.setInterval(tick, options.tickMs ?? TICK_MS);
159
156
  const unsubscribe = timeline.subscribe(tick);
@@ -165,16 +162,45 @@ const MAX_KEY_LENGTH = 200;
165
162
  }));
166
163
  });
167
164
  const start = manifest.chapters.find((chapter)=>chapter.id === options.startChapter);
168
- if (start) timeline.seekChapter(start.id);
169
- const first = steps.findIndex((step)=>step.at >= (start?.from ?? 0));
170
- if (first >= 0) void runFrom(first, generation);
171
- announce();
165
+ const begin = ()=>{
166
+ if (start) timeline.seekChapter(start.id);
167
+ const first = steps.findIndex((step)=>step.at >= (start?.from ?? 0));
168
+ if (first >= 0) void runFrom(first, generation);
169
+ announce();
170
+ };
171
+ const earlier = start ? steps.filter((step)=>step.at < start.from) : [];
172
+ if (start && earlier.some((step)=>step.actions.length > 0)) {
173
+ preluding = true;
174
+ const { navigate, visible, targetTimeoutMs } = options;
175
+ const attribute = manifest.targetAttribute;
176
+ void runPrelude({
177
+ ...{
178
+ win,
179
+ attribute,
180
+ timeline,
181
+ steps: earlier,
182
+ until: start.from
183
+ },
184
+ ...{
185
+ navigate,
186
+ visible,
187
+ targetTimeoutMs,
188
+ settle,
189
+ cancelled: ()=>stopped
190
+ }
191
+ }).then(()=>{
192
+ preluding = false;
193
+ if (!stopped) begin();
194
+ });
195
+ } else begin();
172
196
  return {
173
197
  stop () {
198
+ stopped = true;
174
199
  generation += 1;
175
200
  abortWait();
176
201
  pointer.releaseAll();
177
202
  win.removeEventListener('message', onMessage);
203
+ showFocus();
178
204
  win.clearInterval(ticker);
179
205
  unsubscribe();
180
206
  unanswered?.();
@@ -0,0 +1,8 @@
1
+ import type { Win } from '../../../../src/Client/Replay';
2
+ /**
3
+ * The driver focuses controls the way a visitor's click would, but nobody is there: the drawn cursor and ring already
4
+ * mark the control, and the product's own focus outline would be a second, offset ring over it. Hides the outline of
5
+ * the focused control for the frame's life; returns the undo. (A ring a product paints on a wrapper is the product's
6
+ * to drop while it runs inside a replay.)
7
+ */
8
+ export declare function hideDriverFocus(win: Win): () => void;
@@ -0,0 +1,15 @@
1
+ const GUARD_ID = 'nc-replay-focus-guard';
2
+ /**
3
+ * The driver focuses controls the way a visitor's click would, but nobody is there: the drawn cursor and ring already
4
+ * mark the control, and the product's own focus outline would be a second, offset ring over it. Hides the outline of
5
+ * the focused control for the frame's life; returns the undo. (A ring a product paints on a wrapper is the product's
6
+ * to drop while it runs inside a replay.)
7
+ */ export function hideDriverFocus(win) {
8
+ const existing = win.document.getElementById(GUARD_ID);
9
+ if (existing) return ()=>{};
10
+ const style = win.document.createElement('style');
11
+ style.id = GUARD_ID;
12
+ style.textContent = ':focus,:focus-visible{outline:none!important}';
13
+ win.document.head.append(style);
14
+ return ()=>style.remove();
15
+ }
@@ -0,0 +1,11 @@
1
+ import type { Timeline } from '../../../../src/Client/Replay';
2
+ export interface FrameHold {
3
+ /** Stops the clock while an action runs and returns the release; a no-op while the clock is not running. */
4
+ hold: () => () => void;
5
+ /** The parent pressed play: if a hold is open the release plays it, else the clock plays now. */
6
+ play: () => void;
7
+ /** The parent pressed pause: the release no longer plays. */
8
+ pause: () => void;
9
+ }
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;
@@ -0,0 +1,24 @@
1
+ /** A hold pauses the clock for an action and plays it again after, unless the visitor paused meanwhile. */ export function createFrameHold(timeline) {
2
+ let held = false;
3
+ let resumeAfterHold = false;
4
+ return {
5
+ hold () {
6
+ if (held || !timeline.isPlaying()) return ()=>{};
7
+ held = true;
8
+ resumeAfterHold = true;
9
+ timeline.pause();
10
+ return ()=>{
11
+ held = false;
12
+ if (resumeAfterHold) timeline.play();
13
+ };
14
+ },
15
+ play () {
16
+ if (held) resumeAfterHold = true;
17
+ else timeline.play();
18
+ },
19
+ pause () {
20
+ resumeAfterHold = false;
21
+ timeline.pause();
22
+ }
23
+ };
24
+ }
@@ -0,0 +1,24 @@
1
+ import { type Ms, type ReplayStep, type Timeline, type VisibleCheck, type Win } from '../../../../src/Client/Replay';
2
+ export interface FramePreludeOptions {
3
+ win: Win;
4
+ attribute: string;
5
+ timeline: Timeline;
6
+ /** Every step recorded before the chapter the frame starts at, in recorded order. */
7
+ steps: ReplayStep[];
8
+ /** The chapter's start: no step, wait or jump goes past it. */
9
+ until: Ms;
10
+ navigate: (path: string) => Promise<boolean>;
11
+ visible?: VisibleCheck;
12
+ targetTimeoutMs?: number;
13
+ settle: () => Promise<void>;
14
+ /** True once the frame was stopped: the prelude ends at the next action. */
15
+ cancelled: () => boolean;
16
+ }
17
+ /**
18
+ * Rebuilds the product's state at a chapter start. A frame that starts at chapter N (a seek reloads it there) has
19
+ * none of what the earlier chapters' steps did: the conversation was never opened, the workspace never chosen. So
20
+ * every earlier step's state-changing actions run again at once, with no cursor, no typing delay and no waiting: the
21
+ * paused playhead jumps to each step's time (the recorded answers and stream frames due by then arrive on the way)
22
+ * and a wait inside a step becomes a jump. A step that does not apply (its target never appears) is skipped, not fatal.
23
+ */
24
+ export declare function runPrelude(options: FramePreludeOptions): Promise<void>;
@@ -0,0 +1,36 @@
1
+ import { runStep } from '../../../../src/Client/Replay';
2
+ /** Waiting for a target longer than this in a prelude means the step does not apply here; the prelude moves on. */ const PRELUDE_TARGET_TIMEOUT_MS = 3000;
3
+ /** Actions that read or wait rather than change what the screen holds; a prelude leaves them out. */ function changesState(action) {
4
+ return action.kind !== 'scrollTo' && action.kind !== 'waitFor';
5
+ }
6
+ /**
7
+ * Rebuilds the product's state at a chapter start. A frame that starts at chapter N (a seek reloads it there) has
8
+ * none of what the earlier chapters' steps did: the conversation was never opened, the workspace never chosen. So
9
+ * every earlier step's state-changing actions run again at once, with no cursor, no typing delay and no waiting: the
10
+ * paused playhead jumps to each step's time (the recorded answers and stream frames due by then arrive on the way)
11
+ * and a wait inside a step becomes a jump. A step that does not apply (its target never appears) is skipped, not fatal.
12
+ */ export async function runPrelude(options) {
13
+ const { timeline } = options;
14
+ timeline.pause();
15
+ for (const step of options.steps){
16
+ if (options.cancelled()) return;
17
+ const actions = step.actions.filter(changesState);
18
+ if (actions.length === 0) continue;
19
+ timeline.jumpTo(Math.min(step.at, options.until));
20
+ await runStep({
21
+ ...step,
22
+ actions
23
+ }, {
24
+ win: options.win,
25
+ attribute: options.attribute,
26
+ typingDelayMs: 0,
27
+ targetTimeoutMs: Math.min(options.targetTimeoutMs ?? PRELUDE_TARGET_TIMEOUT_MS, PRELUDE_TARGET_TIMEOUT_MS),
28
+ visible: options.visible,
29
+ onPoint: ()=>{},
30
+ settle: options.settle,
31
+ navigate: options.navigate,
32
+ waitForFrame: async ()=>{},
33
+ waitUntil: async (at)=>timeline.jumpTo(Math.min(at, options.until))
34
+ });
35
+ }
36
+ }
@@ -1,18 +1,22 @@
1
- /** The virtual desktop viewport the product is rendered at: the recording is shown on its desktop layout. */
2
- export declare const MIN_STAGE_VIEWPORT: {
3
- readonly width: 1440;
4
- readonly height: 900;
1
+ /**
2
+ * The virtual desktop viewport the product is rendered at. 1280 x 800 is the smallest size the desktop layout of a
3
+ * product like ACE (a rail, a panel, a centre and a chat column) still fills: every drawn pixel is as large as the
4
+ * stage allows, so text stays readable (a 1440 or 2126 px frame at the same stage shows it 11 to 40 % smaller).
5
+ */
6
+ export declare const VIRTUAL_VIEWPORT: {
7
+ readonly width: 1280;
8
+ readonly height: 800;
5
9
  };
6
10
  export interface StageViewport {
7
11
  width: number;
8
12
  height: number;
9
13
  }
10
14
  /**
11
- * The size the frame is laid out at. A recording made in a narrow window (a phone layout, a half-screen) is still
12
- * shown on the desktop layout, so each side is at least the virtual desktop; a recording taken on a bigger screen keeps
13
- * its own size.
15
+ * The size the frame is laid out at: always the virtual desktop. What size the recording was made at does not matter
16
+ * (the product draws its own screens from the recorded answers, targets are found by anchor, not by position), so a
17
+ * recording made in a phone-sized or an ultra-wide window is shown the same, as large as the stage can show it.
14
18
  */
15
- export declare function stageViewport(recorded: StageViewport): StageViewport;
19
+ export declare function stageViewport(): StageViewport;
16
20
  /** The uniform scale that fits a frame of `frameWidth` px into a box `boxWidth` px wide; 1 until the box is measured. */
17
21
  export declare function fitScale(boxWidth: number, frameWidth: number): number;
18
22
  export interface FrameFit {
@@ -1,15 +1,18 @@
1
- /** The virtual desktop viewport the product is rendered at: the recording is shown on its desktop layout. */ export const MIN_STAGE_VIEWPORT = {
2
- width: 1440,
3
- height: 900
1
+ /**
2
+ * The virtual desktop viewport the product is rendered at. 1280 x 800 is the smallest size the desktop layout of a
3
+ * product like ACE (a rail, a panel, a centre and a chat column) still fills: every drawn pixel is as large as the
4
+ * stage allows, so text stays readable (a 1440 or 2126 px frame at the same stage shows it 11 to 40 % smaller).
5
+ */ export const VIRTUAL_VIEWPORT = {
6
+ width: 1280,
7
+ height: 800
4
8
  };
5
9
  /**
6
- * The size the frame is laid out at. A recording made in a narrow window (a phone layout, a half-screen) is still
7
- * shown on the desktop layout, so each side is at least the virtual desktop; a recording taken on a bigger screen keeps
8
- * its own size.
9
- */ export function stageViewport(recorded) {
10
+ * The size the frame is laid out at: always the virtual desktop. What size the recording was made at does not matter
11
+ * (the product draws its own screens from the recorded answers, targets are found by anchor, not by position), so a
12
+ * recording made in a phone-sized or an ultra-wide window is shown the same, as large as the stage can show it.
13
+ */ export function stageViewport() {
10
14
  return {
11
- width: Math.max(MIN_STAGE_VIEWPORT.width, Math.round(recorded.width)),
12
- height: Math.max(MIN_STAGE_VIEWPORT.height, Math.round(recorded.height))
15
+ ...VIRTUAL_VIEWPORT
13
16
  };
14
17
  }
15
18
  /** The uniform scale that fits a frame of `frameWidth` px into a box `boxWidth` px wide; 1 until the box is measured. */ export function fitScale(boxWidth, frameWidth) {
@@ -37,7 +37,9 @@ export function sleep(win, ms) {
37
37
  */ export async function typeInto(win, target, value, delayMs) {
38
38
  const control = controlWithin(target, (element)=>isTextControl(win, element));
39
39
  if (!control) return false;
40
- control.focus();
40
+ control.focus({
41
+ preventScroll: true
42
+ });
41
43
  if (!assign(win, control, '', null)) return false;
42
44
  if (delayMs <= 0) assign(win, control, value, value);
43
45
  else {
@@ -65,7 +67,9 @@ export function sleep(win, ms) {
65
67
  const pointer = typeof win.PointerEvent === 'function' ? win.PointerEvent : win.MouseEvent;
66
68
  element.dispatchEvent(new pointer('pointerdown', init));
67
69
  element.dispatchEvent(new win.MouseEvent('mousedown', init));
68
- if (element instanceof win.HTMLElement) element.focus();
70
+ if (element instanceof win.HTMLElement) element.focus({
71
+ preventScroll: true
72
+ });
69
73
  element.dispatchEvent(new pointer('pointerup', init));
70
74
  element.dispatchEvent(new win.MouseEvent('mouseup', init));
71
75
  if (element instanceof win.HTMLElement) element.click();
@@ -86,7 +90,9 @@ export function sleep(win, ms) {
86
90
  return true;
87
91
  }
88
92
  /** Key down and key up on the focused target; Enter in a text field submits its form, as a real keypress does. */ export function pressKey(win, target, key) {
89
- if (target instanceof win.HTMLElement) target.focus();
93
+ if (target instanceof win.HTMLElement) target.focus({
94
+ preventScroll: true
95
+ });
90
96
  const init = {
91
97
  key,
92
98
  bubbles: true,
@@ -24,6 +24,14 @@ export interface RunDeps {
24
24
  * those seconds (the server's answer to that very click) would otherwise take the control away first.
25
25
  */
26
26
  hold?: () => () => void;
27
+ /**
28
+ * Called when an action cannot be done on the screen (its target never appeared, a choice is missing, the action threw).
29
+ * When given, the step carries on with its next action instead of stopping: a public tour keeps playing without that pointer.
30
+ */
31
+ onSkip?: (skipped: {
32
+ actionIndex: number;
33
+ reason: FailureReason;
34
+ }) => void;
27
35
  }
28
36
  export type RunResult = {
29
37
  ok: true;
@@ -32,5 +40,8 @@ export type RunResult = {
32
40
  actionIndex: number;
33
41
  reason: FailureReason;
34
42
  };
35
- /** Runs a step's actions in order, settling after each, and stops at the first failure with its index and reason. */
43
+ /**
44
+ * Runs a step's actions in order, settling after each. A failure stops the step with its index and reason, unless
45
+ * `deps.onSkip` is set and the reason is skippable: then it is reported there and the next action runs.
46
+ */
36
47
  export declare function runStep(step: ReplayStep, deps: RunDeps): Promise<RunResult>;
@@ -53,7 +53,16 @@ async function runAction(deps, action) {
53
53
  return runTargeted(deps, action);
54
54
  }
55
55
  }
56
- /** Runs a step's actions in order, settling after each, and stops at the first failure with its index and reason. */ export async function runStep(step, deps) {
56
+ /** Reasons that mean "this pointer action cannot be shown"; the tape itself is fine, so a step may go on without it. */ const SKIPPABLE = [
57
+ 'target_timeout',
58
+ 'target_unsupported',
59
+ 'option_not_found',
60
+ 'action_error'
61
+ ];
62
+ /**
63
+ * Runs a step's actions in order, settling after each. A failure stops the step with its index and reason, unless
64
+ * `deps.onSkip` is set and the reason is skippable: then it is reported there and the next action runs.
65
+ */ export async function runStep(step, deps) {
57
66
  for (const [actionIndex, action] of step.actions.entries()){
58
67
  let reason;
59
68
  try {
@@ -61,11 +70,18 @@ async function runAction(deps, action) {
61
70
  } catch {
62
71
  reason = 'action_error';
63
72
  }
64
- if (reason !== null) return {
65
- ok: false,
66
- actionIndex,
67
- reason
68
- };
73
+ if (reason !== null) {
74
+ if (deps.onSkip === undefined || !SKIPPABLE.includes(reason)) return {
75
+ ok: false,
76
+ actionIndex,
77
+ reason
78
+ };
79
+ deps.onSkip({
80
+ actionIndex,
81
+ reason
82
+ });
83
+ continue;
84
+ }
69
85
  await deps.settle();
70
86
  }
71
87
  return {
@@ -24,6 +24,11 @@ export interface Timeline {
24
24
  isPlaying(): boolean;
25
25
  /** Chapter starts are the only seek points. Throws on an unknown id. */
26
26
  seekChapter(id: string): void;
27
+ /**
28
+ * Moves a PAUSED playhead to `ms` (clamped to the recording) and fires everything due on the way at once: the
29
+ * frame rebuilding the state before a chapter uses it to stand where the recorded person stood. Ignored while playing.
30
+ */
31
+ jumpTo(ms: Ms): void;
27
32
  now(): Ms;
28
33
  currentChapter(): string | null;
29
34
  subscribe(listener: TimelineListener): () => void;
@@ -135,6 +135,14 @@ export function createTimeline(options) {
135
135
  notify();
136
136
  advance();
137
137
  },
138
+ jumpTo (ms) {
139
+ if (playing || !Number.isFinite(ms)) return;
140
+ head = Math.min(Math.max(ms, 0), durationMs);
141
+ anchor = clock.now();
142
+ syncChapter(head);
143
+ notify();
144
+ advance();
145
+ },
138
146
  now,
139
147
  currentChapter: ()=>chapterId,
140
148
  subscribe (listener) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nucleus-core-ts",
3
- "version": "0.10.256",
3
+ "version": "0.10.258",
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",