nucleus-core-ts 0.10.257 → 0.10.259
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/.build-ok +1 -1
- package/dist/fe/components/Replay/_components/ReplayChapters/index.js +12 -0
- package/dist/fe/components/Replay/_components/ReplayCursor/index.js +5 -1
- package/dist/fe/components/Replay/_components/ReplayPlayer/ReplayView.js +2 -0
- package/dist/fe/components/Replay/_components/ReplayStage/index.js +4 -3
- package/dist/fe/components/Replay/_components/ReplayStage/types.d.ts +3 -0
- package/dist/fe/components/Replay/_hooks/useCameraPan.js +8 -5
- package/dist/fe/components/Replay/_hooks/useStageScale.js +11 -4
- package/dist/fe/components/Replay/_store/replayStore.js +8 -0
- package/dist/fe/components/Replay/_types/frame.d.ts +40 -0
- package/dist/fe/components/Replay/_types/frame.js +1 -0
- package/dist/fe/components/Replay/_types/index.d.ts +1 -0
- package/dist/fe/components/Replay/_types/index.js +1 -0
- package/dist/fe/components/Replay/_types/player.d.ts +9 -0
- package/dist/fe/components/Replay/_utils/chapterRow.d.ts +8 -0
- package/dist/fe/components/Replay/_utils/chapterRow.js +17 -0
- package/dist/fe/components/Replay/_utils/controller.js +13 -4
- package/dist/fe/components/Replay/_utils/controllerReports.d.ts +2 -1
- package/dist/fe/components/Replay/_utils/controllerReports.js +8 -1
- package/dist/fe/components/Replay/_utils/cursorMotion.d.ts +16 -2
- package/dist/fe/components/Replay/_utils/cursorMotion.js +42 -8
- package/dist/fe/components/Replay/_utils/frameBridge.d.ts +1 -40
- package/dist/fe/components/Replay/_utils/frameBridge.js +71 -29
- package/dist/fe/components/Replay/_utils/frameFocus.d.ts +8 -0
- package/dist/fe/components/Replay/_utils/frameFocus.js +15 -0
- package/dist/fe/components/Replay/_utils/frameHold.d.ts +11 -0
- package/dist/fe/components/Replay/_utils/frameHold.js +24 -0
- package/dist/fe/components/Replay/_utils/framePrelude.d.ts +26 -0
- package/dist/fe/components/Replay/_utils/framePrelude.js +37 -0
- package/dist/fe/components/Replay/_utils/replayProgress.d.ts +2 -0
- package/dist/fe/components/Replay/_utils/replayProgress.js +4 -0
- package/dist/fe/components/Replay/_utils/stageViewport.d.ts +17 -10
- package/dist/fe/components/Replay/_utils/stageViewport.js +18 -12
- package/dist/src/Client/Replay/channel/channel.d.ts +9 -0
- package/dist/src/Client/Replay/channel/channel.js +15 -2
- package/dist/src/Client/Replay/driver/input.js +9 -3
- package/dist/src/Client/Replay/timeline/timeline.d.ts +5 -0
- package/dist/src/Client/Replay/timeline/timeline.js +8 -0
- package/package.json +1 -1
package/dist/.build-ok
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.10.
|
|
1
|
+
0.10.259
|
|
@@ -1,9 +1,20 @@
|
|
|
1
1
|
'use client';
|
|
2
2
|
import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
3
|
+
import { useEffect, useEffectEvent, useRef } from 'react';
|
|
4
|
+
import { revealInRow } from '../../_utils/chapterRow';
|
|
3
5
|
import { REPLAY_COPY } from '../../_utils/copy';
|
|
4
6
|
import { pickLocalized } from '../../_utils/frameUrl';
|
|
5
7
|
import { chapterMinutes, chapterProgress } from '../../_utils/replayProgress';
|
|
6
8
|
/** The chapters as a list: each one seeks to its start; the current one is marked and shows how far the playhead is in it. */ export function ReplayChapters({ chapters, locale, chapterId, playhead, onSeek }) {
|
|
9
|
+
const row = useRef(null);
|
|
10
|
+
// The row scrolls sideways: the current chapter is brought into it, and only it (never the page).
|
|
11
|
+
const reveal = useEffectEvent(()=>{
|
|
12
|
+
const item = row.current?.querySelector('[aria-current="step"]');
|
|
13
|
+
if (row.current && item) revealInRow(row.current, item);
|
|
14
|
+
});
|
|
15
|
+
useEffect(()=>reveal(), [
|
|
16
|
+
chapterId
|
|
17
|
+
]);
|
|
7
18
|
return /*#__PURE__*/ _jsxs("nav", {
|
|
8
19
|
className: "nc-replay__chapters",
|
|
9
20
|
"aria-label": REPLAY_COPY.chapters,
|
|
@@ -14,6 +25,7 @@ import { chapterMinutes, chapterProgress } from '../../_utils/replayProgress';
|
|
|
14
25
|
children: REPLAY_COPY.chapters
|
|
15
26
|
}),
|
|
16
27
|
/*#__PURE__*/ _jsx("ol", {
|
|
28
|
+
ref: row,
|
|
17
29
|
className: "nc-replay__chapter-list",
|
|
18
30
|
children: chapters.map((chapter, i)=>{
|
|
19
31
|
const current = chapter.id === chapterId;
|
|
@@ -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
|
}
|
|
@@ -54,6 +54,7 @@ import { ReplayStage } from '../ReplayStage';
|
|
|
54
54
|
className: `nc-replay${className ? ` ${className}` : ''}`,
|
|
55
55
|
"data-theme": theme,
|
|
56
56
|
"data-replay-status": status,
|
|
57
|
+
"data-replay-skipped": state.skipped.length,
|
|
57
58
|
children: [
|
|
58
59
|
/*#__PURE__*/ _jsx("style", {
|
|
59
60
|
children: REPLAY_CSS
|
|
@@ -65,6 +66,7 @@ import { ReplayStage } from '../ReplayStage';
|
|
|
65
66
|
frameRef: player.frameRef,
|
|
66
67
|
cursor: state.cursor,
|
|
67
68
|
rate: state.rate,
|
|
69
|
+
chapterId: state.chapterId,
|
|
68
70
|
onArrive: player.cursorArrived,
|
|
69
71
|
loading: status === 'loading',
|
|
70
72
|
children: overlay
|
|
@@ -5,6 +5,7 @@ import { useCameraPan } from '../../_hooks/useCameraPan';
|
|
|
5
5
|
import { useStageScale } from '../../_hooks/useStageScale';
|
|
6
6
|
import { REPLAY_COPY } from '../../_utils/copy';
|
|
7
7
|
import { pickLocalized } from '../../_utils/frameUrl';
|
|
8
|
+
import { effectiveRate } from '../../_utils/replayProgress';
|
|
8
9
|
import { cameraOffset, cameraShot, restingFocus, stageViewport } from '../../_utils/stageViewport';
|
|
9
10
|
import { ReplayCursorLayer } from '../ReplayCursor';
|
|
10
11
|
import { ReplayVeil } from './ReplayVeil';
|
|
@@ -17,8 +18,8 @@ import { ReplayVeil } from './ReplayVeil';
|
|
|
17
18
|
* it show what happens. The cursor layer shares the world's box and the frame's scale, so a point of the frame lands
|
|
18
19
|
* on the same spot of the layer.
|
|
19
20
|
*/ export function ReplayStage(props) {
|
|
20
|
-
const { manifest, locale, frameSrc, frameRef, cursor, rate, onArrive, loading, children } = props;
|
|
21
|
-
const frame = stageViewport(
|
|
21
|
+
const { manifest, locale, frameSrc, frameRef, cursor, rate, chapterId, onArrive, loading, children } = props;
|
|
22
|
+
const frame = stageViewport();
|
|
22
23
|
const fit = useStageScale(frame);
|
|
23
24
|
const [whole, setWhole] = useState(false);
|
|
24
25
|
const world = useRef(null);
|
|
@@ -103,7 +104,7 @@ import { ReplayVeil } from './ReplayVeil';
|
|
|
103
104
|
/*#__PURE__*/ _jsx(ReplayCursorLayer, {
|
|
104
105
|
cursor: cursor,
|
|
105
106
|
scale: scale,
|
|
106
|
-
rate: rate,
|
|
107
|
+
rate: effectiveRate(manifest, chapterId, rate),
|
|
107
108
|
onArrive: onArrive
|
|
108
109
|
})
|
|
109
110
|
]
|
|
@@ -9,7 +9,10 @@ export interface ReplayStageProps {
|
|
|
9
9
|
/** Where the player finds the frame's window. */
|
|
10
10
|
frameRef: RefObject<HTMLIFrameElement | null>;
|
|
11
11
|
cursor: ReplayCursor | null;
|
|
12
|
+
/** The visitor's speed. */
|
|
12
13
|
rate: number;
|
|
14
|
+
/** The chapter on screen; its own pace multiplies `rate` for the cursor, as it does for the frame's clock. */
|
|
15
|
+
chapterId: string | null;
|
|
13
16
|
onArrive: (mark: number) => void;
|
|
14
17
|
/** Shows the loading veil over the frame. */
|
|
15
18
|
loading: boolean;
|
|
@@ -13,11 +13,14 @@ gsap.registerPlugin(useGSAP);
|
|
|
13
13
|
x: 0,
|
|
14
14
|
y: 0
|
|
15
15
|
};
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
16
|
+
// A jump must end any glide still under way, or the glide would carry the world on past it.
|
|
17
|
+
if (reduced || !on) {
|
|
18
|
+
gsap.killTweensOf(el);
|
|
19
|
+
gsap.set(el, {
|
|
20
|
+
x: to.x,
|
|
21
|
+
y: to.y
|
|
22
|
+
});
|
|
23
|
+
} else gsap.to(el, {
|
|
21
24
|
x: to.x,
|
|
22
25
|
y: to.y,
|
|
23
26
|
duration: 0.7,
|
|
@@ -3,13 +3,14 @@ import { useEffect, useEffectEvent, useRef, useState } from 'react';
|
|
|
3
3
|
import { CAMERA_BELOW_WIDTH, fitFrame } from '../_utils/stageViewport';
|
|
4
4
|
const FIT_HEIGHT_QUERY = '(min-width:1024px)';
|
|
5
5
|
const FIT_GAP = 4;
|
|
6
|
-
/** The height left for the frame: the window minus everything else of the player, minus the host's own offset. */ function roomHeight(box) {
|
|
6
|
+
/** The height left for the frame (0: not limited here): the window minus everything else of the player, minus the host's own offset. */ function roomHeight(box) {
|
|
7
7
|
if (typeof window === 'undefined' || !window.matchMedia(FIT_HEIGHT_QUERY).matches) return 0;
|
|
8
8
|
const root = box.closest('.nc-replay');
|
|
9
9
|
const view = box.firstElementChild;
|
|
10
10
|
if (!root || !(view instanceof HTMLElement)) return 0;
|
|
11
11
|
const offset = Number.parseFloat(getComputedStyle(root).getPropertyValue('--replay-fit-offset')) || 0;
|
|
12
|
-
|
|
12
|
+
// At least 1: 0 means "not limited" to `fitFrame`, and a window with no room left must still be floored, not unbounded.
|
|
13
|
+
return Math.max(1, window.innerHeight - (root.offsetHeight - view.offsetHeight) - offset - FIT_GAP);
|
|
13
14
|
}
|
|
14
15
|
/**
|
|
15
16
|
* The scale that fits `frame` into the element the returned ref points at: by width everywhere, and from 1024 px up
|
|
@@ -21,12 +22,18 @@ const FIT_GAP = 4;
|
|
|
21
22
|
width: 0,
|
|
22
23
|
height: 0
|
|
23
24
|
});
|
|
25
|
+
const last = useRef(room);
|
|
24
26
|
const measure = useEffectEvent(()=>{
|
|
25
27
|
const box = boxRef.current;
|
|
26
|
-
if (box)
|
|
28
|
+
if (!box) return;
|
|
29
|
+
const next = {
|
|
27
30
|
width: box.clientWidth,
|
|
28
31
|
height: roomHeight(box)
|
|
29
|
-
}
|
|
32
|
+
};
|
|
33
|
+
// Only a changed value is set: the fit resizes the view, which the observer sees, which measures again.
|
|
34
|
+
if (last.current.width === next.width && last.current.height === next.height) return;
|
|
35
|
+
last.current = next;
|
|
36
|
+
setRoom(next);
|
|
30
37
|
});
|
|
31
38
|
useEffect(()=>{
|
|
32
39
|
const box = boxRef.current;
|
|
@@ -11,6 +11,7 @@ export const initialReplayState = {
|
|
|
11
11
|
locale: 'en',
|
|
12
12
|
cursor: null,
|
|
13
13
|
unanswered: [],
|
|
14
|
+
skipped: [],
|
|
14
15
|
failure: null
|
|
15
16
|
};
|
|
16
17
|
/** The store's methods as creators over a plain state object, so tests can run them without React. */ export const replayMethodCreators = {
|
|
@@ -18,6 +19,7 @@ export const initialReplayState = {
|
|
|
18
19
|
Object.assign(s, {
|
|
19
20
|
...initialReplayState,
|
|
20
21
|
unanswered: [],
|
|
22
|
+
skipped: [],
|
|
21
23
|
locale: s.locale
|
|
22
24
|
});
|
|
23
25
|
},
|
|
@@ -59,6 +61,12 @@ export const initialReplayState = {
|
|
|
59
61
|
key
|
|
60
62
|
];
|
|
61
63
|
},
|
|
64
|
+
reportSkipped: (s)=>(skip)=>{
|
|
65
|
+
s.skipped = [
|
|
66
|
+
...s.skipped,
|
|
67
|
+
skip
|
|
68
|
+
];
|
|
69
|
+
},
|
|
62
70
|
fail: (s)=>(failure)=>{
|
|
63
71
|
s.failure = failure;
|
|
64
72
|
s.status = 'failed';
|
|
@@ -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 { };
|
|
@@ -17,6 +17,12 @@ export interface ReplayCursor {
|
|
|
17
17
|
box: PointBox;
|
|
18
18
|
arrived: boolean;
|
|
19
19
|
}
|
|
20
|
+
/** An action the tape played on without: the player never stops for it, the page can read the list. */
|
|
21
|
+
export interface ReplaySkip {
|
|
22
|
+
stepId: string;
|
|
23
|
+
actionIndex: number;
|
|
24
|
+
reason: FailureReason;
|
|
25
|
+
}
|
|
20
26
|
export type ReplayPlayerState = {
|
|
21
27
|
status: ReplayStatus;
|
|
22
28
|
manifest: ReplayManifest | null;
|
|
@@ -30,6 +36,8 @@ export type ReplayPlayerState = {
|
|
|
30
36
|
cursor: ReplayCursor | null;
|
|
31
37
|
/** Endpoint keys the recording could not answer, each once: the audit wants none. */
|
|
32
38
|
unanswered: string[];
|
|
39
|
+
/** Every action skipped so far (a public tour keeps playing); `skipped.length` is the diagnostic count. */
|
|
40
|
+
skipped: ReplaySkip[];
|
|
33
41
|
failure: ReplayFailure | null;
|
|
34
42
|
};
|
|
35
43
|
export type ReplayPlayerMethods = {
|
|
@@ -44,6 +52,7 @@ export type ReplayPlayerMethods = {
|
|
|
44
52
|
setLocale: (locale: string) => void;
|
|
45
53
|
setCursor: (cursor: ReplayCursor | null) => void;
|
|
46
54
|
reportUnanswered: (key: string) => void;
|
|
55
|
+
reportSkipped: (skip: ReplaySkip) => void;
|
|
47
56
|
fail: (failure: ReplayFailure) => void;
|
|
48
57
|
clearFailure: () => void;
|
|
49
58
|
};
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `scrollLeft` that brings an item fully into a horizontally scrolling row, moving as little as possible: the row
|
|
3
|
+
* stays where it is when the item is already inside, and a row that cannot scroll that far is clamped by the browser.
|
|
4
|
+
* All four numbers are in the row's own scrolled pixels (the item's left edge counts from the row's content start).
|
|
5
|
+
*/
|
|
6
|
+
export declare function scrollLeftToReveal(current: number, viewWidth: number, itemLeft: number, itemWidth: number): number;
|
|
7
|
+
/** Scrolls `row` (never the page) so `item` is inside it. Returns the new `scrollLeft`. */
|
|
8
|
+
export declare function revealInRow(row: HTMLElement, item: HTMLElement): number;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `scrollLeft` that brings an item fully into a horizontally scrolling row, moving as little as possible: the row
|
|
3
|
+
* stays where it is when the item is already inside, and a row that cannot scroll that far is clamped by the browser.
|
|
4
|
+
* All four numbers are in the row's own scrolled pixels (the item's left edge counts from the row's content start).
|
|
5
|
+
*/ export function scrollLeftToReveal(current, viewWidth, itemLeft, itemWidth) {
|
|
6
|
+
if (itemLeft < current) return Math.max(0, itemLeft);
|
|
7
|
+
if (itemLeft + itemWidth > current + viewWidth) return Math.max(0, itemLeft + itemWidth - viewWidth);
|
|
8
|
+
return current;
|
|
9
|
+
}
|
|
10
|
+
/** Scrolls `row` (never the page) so `item` is inside it. Returns the new `scrollLeft`. */ export function revealInRow(row, item) {
|
|
11
|
+
const rowBox = row.getBoundingClientRect();
|
|
12
|
+
const itemBox = item.getBoundingClientRect();
|
|
13
|
+
const left = itemBox.left - rowBox.left + row.scrollLeft;
|
|
14
|
+
const next = scrollLeftToReveal(row.scrollLeft, row.clientWidth, left, itemBox.width);
|
|
15
|
+
if (next !== row.scrollLeft) row.scrollLeft = next;
|
|
16
|
+
return next;
|
|
17
|
+
}
|
|
@@ -75,8 +75,12 @@ const realClock = {
|
|
|
75
75
|
stopPlaying: ()=>{
|
|
76
76
|
wants.playing = false;
|
|
77
77
|
},
|
|
78
|
-
onReady: (recordingId)=>{
|
|
78
|
+
onReady: (recordingId, preparing)=>{
|
|
79
79
|
if (recordingId !== store.manifest?.id) return;
|
|
80
|
+
if (preparing) {
|
|
81
|
+
if (!ready) armGiveUp(); // alive but not ready: the wait starts over, play and seek stay queued
|
|
82
|
+
return;
|
|
83
|
+
}
|
|
80
84
|
const first = !ready;
|
|
81
85
|
ready = true;
|
|
82
86
|
if (first) store.setStatus(wants.playing ? 'playing' : 'ready');
|
|
@@ -98,13 +102,18 @@ const realClock = {
|
|
|
98
102
|
if (message && !disposed) handle(message);
|
|
99
103
|
};
|
|
100
104
|
listen.addEventListener('message', onMessage);
|
|
101
|
-
|
|
102
|
-
|
|
105
|
+
let giveUp = null;
|
|
106
|
+
function armGiveUp() {
|
|
107
|
+
if (giveUp !== null) cancel(giveUp);
|
|
108
|
+
giveUp = after(options.readyTimeoutMs ?? READY_TIMEOUT_MS, ()=>{
|
|
103
109
|
if (!ready) failWith('frame_timeout', null);
|
|
104
110
|
});
|
|
111
|
+
}
|
|
112
|
+
const awaitFrame = ()=>{
|
|
113
|
+
armGiveUp();
|
|
105
114
|
const ask = ()=>{
|
|
106
115
|
if (ready || disposed) {
|
|
107
|
-
cancel(giveUp);
|
|
116
|
+
if (giveUp !== null) cancel(giveUp);
|
|
108
117
|
return;
|
|
109
118
|
}
|
|
110
119
|
send((e)=>({
|
|
@@ -5,7 +5,8 @@ export interface ReportDeps {
|
|
|
5
5
|
store: ReplayStoreApi;
|
|
6
6
|
send: SendToFrame;
|
|
7
7
|
/** The frame announced itself for this recording. */
|
|
8
|
-
|
|
8
|
+
/** `preparing`: the frame heard the hello but is still rebuilding its start state; it is not ready to play. */
|
|
9
|
+
onReady: (recordingId: string, preparing: boolean) => void;
|
|
9
10
|
isReady: () => boolean;
|
|
10
11
|
/** The visitor's intent to play ends with the run (failure, end). */
|
|
11
12
|
stopPlaying: () => void;
|
|
@@ -26,7 +26,7 @@ function chapterAt(manifest, at) {
|
|
|
26
26
|
return (message)=>{
|
|
27
27
|
const manifest = store.manifest;
|
|
28
28
|
if (message.type === 'ready') {
|
|
29
|
-
deps.onReady(message.recordingId);
|
|
29
|
+
deps.onReady(message.recordingId, message.preparing === true);
|
|
30
30
|
return;
|
|
31
31
|
}
|
|
32
32
|
if (!manifest || !deps.isReady()) return;
|
|
@@ -61,6 +61,13 @@ function chapterAt(manifest, at) {
|
|
|
61
61
|
case 'tick':
|
|
62
62
|
onTick(manifest, message.at, message.playing);
|
|
63
63
|
break;
|
|
64
|
+
case 'skipped':
|
|
65
|
+
store.reportSkipped({
|
|
66
|
+
stepId: message.stepId,
|
|
67
|
+
actionIndex: message.actionIndex,
|
|
68
|
+
reason: message.reason
|
|
69
|
+
});
|
|
70
|
+
break;
|
|
64
71
|
case 'unanswered':
|
|
65
72
|
store.reportUnanswered(message.key);
|
|
66
73
|
break;
|
|
@@ -16,8 +16,20 @@ export interface CursorTarget {
|
|
|
16
16
|
height: number;
|
|
17
17
|
};
|
|
18
18
|
}
|
|
19
|
-
/** The
|
|
20
|
-
export
|
|
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
|
|
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
|
|
17
|
-
y
|
|
18
|
-
width
|
|
19
|
-
height
|
|
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,43 +1,4 @@
|
|
|
1
|
-
import
|
|
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
|
-
* 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
|
-
}
|
|
1
|
+
import type { ReplayFrameHandle, ReplayFrameOptions } from '../_types';
|
|
41
2
|
/**
|
|
42
3
|
* The frame side of a replay: answers the parent's hello, forwards play, pause, rate and seek to the timeline, runs
|
|
43
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,33 +18,40 @@ const MAX_KEY_LENGTH = 200;
|
|
|
15
18
|
].sort((a, b)=>a.at - b.at);
|
|
16
19
|
let generation = 0;
|
|
17
20
|
let abortWait = ()=>{};
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
let
|
|
21
|
-
|
|
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 rebuilt: ticks stop, only the hello is answered (`preparing`).
|
|
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
|
};
|
|
34
28
|
const announce = ()=>send((e)=>({
|
|
35
29
|
...e,
|
|
36
30
|
type: 'ready',
|
|
37
|
-
recordingId: manifest.id
|
|
31
|
+
recordingId: manifest.id,
|
|
32
|
+
...preluding ? {
|
|
33
|
+
preparing: true
|
|
34
|
+
} : {}
|
|
35
|
+
}));
|
|
36
|
+
const reportSkip = (stepId, actionIndex, reason)=>{
|
|
37
|
+
win.console?.warn(`[replay] step ${stepId} action ${actionIndex} skipped: ${reason}`);
|
|
38
|
+
send((e)=>({
|
|
39
|
+
...e,
|
|
40
|
+
type: 'skipped',
|
|
41
|
+
stepId,
|
|
42
|
+
actionIndex,
|
|
43
|
+
reason
|
|
38
44
|
}));
|
|
39
|
-
|
|
45
|
+
};
|
|
46
|
+
const tick = ()=>{
|
|
47
|
+
if (!preluding) send((e)=>({
|
|
40
48
|
...e,
|
|
41
49
|
type: 'tick',
|
|
42
50
|
at: timeline.now(),
|
|
43
51
|
playing: timeline.isPlaying()
|
|
44
52
|
}));
|
|
53
|
+
};
|
|
54
|
+
const settle = options.settle ?? (()=>new Promise((resolve)=>void win.setTimeout(resolve, 0)));
|
|
45
55
|
const pointer = createFramePoints({
|
|
46
56
|
setTimeout: (run, ms)=>win.setTimeout(run, ms),
|
|
47
57
|
clearTimeout: (id)=>win.clearTimeout(id),
|
|
@@ -75,12 +85,12 @@ const MAX_KEY_LENGTH = 200;
|
|
|
75
85
|
targetTimeoutMs: options.targetTimeoutMs,
|
|
76
86
|
visible: options.visible,
|
|
77
87
|
onPoint: (box)=>pointer.point(step.id, box),
|
|
78
|
-
settle
|
|
88
|
+
settle,
|
|
79
89
|
navigate: options.navigate,
|
|
80
90
|
waitForFrame: options.waitForFrame,
|
|
81
91
|
waitUntil: (at)=>timeline.waitUntil(at),
|
|
82
|
-
hold,
|
|
83
|
-
onSkip: options.skipFailedSteps === false ? undefined : ({ actionIndex, reason })=>
|
|
92
|
+
hold: clock.hold,
|
|
93
|
+
onSkip: options.skipFailedSteps === false ? undefined : ({ actionIndex, reason })=>reportSkip(step.id, actionIndex, reason)
|
|
84
94
|
});
|
|
85
95
|
if (gen !== generation) return false;
|
|
86
96
|
if (result.ok) {
|
|
@@ -132,17 +142,18 @@ const MAX_KEY_LENGTH = 200;
|
|
|
132
142
|
nonce: options.nonce
|
|
133
143
|
});
|
|
134
144
|
if (!message) return;
|
|
145
|
+
// The hello is answered even while preluding (so the parent knows the frame is alive); the rest waits.
|
|
146
|
+
if (message.type === 'hello') {
|
|
147
|
+
announce();
|
|
148
|
+
return;
|
|
149
|
+
}
|
|
150
|
+
if (preluding) return;
|
|
135
151
|
switch(message.type){
|
|
136
|
-
case 'hello':
|
|
137
|
-
announce();
|
|
138
|
-
break;
|
|
139
152
|
case 'play':
|
|
140
|
-
|
|
141
|
-
else timeline.play();
|
|
153
|
+
clock.play();
|
|
142
154
|
break;
|
|
143
155
|
case 'pause':
|
|
144
|
-
|
|
145
|
-
timeline.pause();
|
|
156
|
+
clock.pause();
|
|
146
157
|
break;
|
|
147
158
|
case 'rate':
|
|
148
159
|
timeline.setRate(message.rate);
|
|
@@ -155,6 +166,7 @@ const MAX_KEY_LENGTH = 200;
|
|
|
155
166
|
break;
|
|
156
167
|
}
|
|
157
168
|
};
|
|
169
|
+
const showFocus = hideDriverFocus(win);
|
|
158
170
|
win.addEventListener('message', onMessage);
|
|
159
171
|
const ticker = win.setInterval(tick, options.tickMs ?? TICK_MS);
|
|
160
172
|
const unsubscribe = timeline.subscribe(tick);
|
|
@@ -166,16 +178,46 @@ const MAX_KEY_LENGTH = 200;
|
|
|
166
178
|
}));
|
|
167
179
|
});
|
|
168
180
|
const start = manifest.chapters.find((chapter)=>chapter.id === options.startChapter);
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
181
|
+
const begin = ()=>{
|
|
182
|
+
if (start) timeline.seekChapter(start.id);
|
|
183
|
+
const first = steps.findIndex((step)=>step.at >= (start?.from ?? 0));
|
|
184
|
+
if (first >= 0) void runFrom(first, generation);
|
|
185
|
+
announce();
|
|
186
|
+
};
|
|
187
|
+
const earlier = start ? steps.filter((step)=>step.at < start.from) : [];
|
|
188
|
+
if (start && earlier.some((step)=>step.actions.length > 0)) {
|
|
189
|
+
preluding = true;
|
|
190
|
+
const { navigate, visible, targetTimeoutMs } = options;
|
|
191
|
+
const attribute = manifest.targetAttribute;
|
|
192
|
+
void runPrelude({
|
|
193
|
+
...{
|
|
194
|
+
win,
|
|
195
|
+
attribute,
|
|
196
|
+
timeline,
|
|
197
|
+
steps: earlier,
|
|
198
|
+
until: start.from
|
|
199
|
+
},
|
|
200
|
+
...{
|
|
201
|
+
navigate,
|
|
202
|
+
visible,
|
|
203
|
+
targetTimeoutMs,
|
|
204
|
+
settle,
|
|
205
|
+
cancelled: ()=>stopped
|
|
206
|
+
},
|
|
207
|
+
onSkip: options.skipFailedSteps === false ? undefined : reportSkip
|
|
208
|
+
}).then(()=>{
|
|
209
|
+
preluding = false;
|
|
210
|
+
if (!stopped) begin();
|
|
211
|
+
});
|
|
212
|
+
} else begin();
|
|
173
213
|
return {
|
|
174
214
|
stop () {
|
|
215
|
+
stopped = true;
|
|
175
216
|
generation += 1;
|
|
176
217
|
abortWait();
|
|
177
218
|
pointer.releaseAll();
|
|
178
219
|
win.removeEventListener('message', onMessage);
|
|
220
|
+
showFocus();
|
|
179
221
|
win.clearInterval(ticker);
|
|
180
222
|
unsubscribe();
|
|
181
223
|
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,26 @@
|
|
|
1
|
+
import { type FailureReason, 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
|
+
/** Told of a step the prelude dropped (its target never appeared); `actionIndex` is the action that failed. */
|
|
15
|
+
onSkip?: (stepId: string, actionIndex: number, reason: FailureReason) => void;
|
|
16
|
+
/** True once the frame was stopped: the prelude ends at the next action. */
|
|
17
|
+
cancelled: () => boolean;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Rebuilds the product's state at a chapter start. A frame that starts at chapter N (a seek reloads it there) has
|
|
21
|
+
* none of what the earlier chapters' steps did: the conversation was never opened, the workspace never chosen. So
|
|
22
|
+
* every earlier step's state-changing actions run again at once, with no cursor, no typing delay and no waiting: the
|
|
23
|
+
* paused playhead jumps to each step's time (the recorded answers and stream frames due by then arrive on the way)
|
|
24
|
+
* and a wait inside a step becomes a jump. A step that does not apply (its target never appears) is skipped, not fatal.
|
|
25
|
+
*/
|
|
26
|
+
export declare function runPrelude(options: FramePreludeOptions): Promise<void>;
|
|
@@ -0,0 +1,37 @@
|
|
|
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
|
+
const result = 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
|
+
if (!result.ok) options.onSkip?.(step.id, result.actionIndex, result.reason);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import type { Ms, ReplayChapter, ReplayManifest } from '../../../../src/Client/Replay';
|
|
2
2
|
/** How far the playhead is through a chapter, 0 to 1. */
|
|
3
3
|
export declare function chapterProgress(chapter: ReplayChapter, playhead: Ms): number;
|
|
4
|
+
/** The speed the drawn cursor moves at: the visitor's speed times the current chapter's own pace, as the frame's clock runs. */
|
|
5
|
+
export declare function effectiveRate(manifest: ReplayManifest, chapterId: string | null, visitorRate: number): number;
|
|
4
6
|
/** The 1-based position of a step among the recording's steps, or null when there is no current step. */
|
|
5
7
|
export declare function stepPosition(manifest: ReplayManifest, stepId: string | null): {
|
|
6
8
|
index: number;
|
|
@@ -3,6 +3,10 @@
|
|
|
3
3
|
if (span <= 0) return playhead >= chapter.to ? 1 : 0;
|
|
4
4
|
return Math.min(1, Math.max(0, (playhead - chapter.from) / span));
|
|
5
5
|
}
|
|
6
|
+
/** The speed the drawn cursor moves at: the visitor's speed times the current chapter's own pace, as the frame's clock runs. */ export function effectiveRate(manifest, chapterId, visitorRate) {
|
|
7
|
+
const chapter = manifest.chapters.find((item)=>item.id === chapterId) ?? manifest.chapters[0];
|
|
8
|
+
return visitorRate * (chapter?.rate ?? 1);
|
|
9
|
+
}
|
|
6
10
|
/** The 1-based position of a step among the recording's steps, or null when there is no current step. */ export function stepPosition(manifest, stepId) {
|
|
7
11
|
if (stepId === null) return null;
|
|
8
12
|
const at = manifest.steps.findIndex((step)=>step.id === stepId);
|
|
@@ -1,18 +1,22 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
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
|
|
12
|
-
*
|
|
13
|
-
*
|
|
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(
|
|
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 {
|
|
@@ -22,10 +26,13 @@ export interface FrameFit {
|
|
|
22
26
|
width: number;
|
|
23
27
|
height: number;
|
|
24
28
|
}
|
|
29
|
+
/** The smallest scale the height fit may shrink the frame to: below it the text is unreadable, so the page scrolls instead. */
|
|
30
|
+
export declare const MIN_FIT_SCALE = 0.35;
|
|
25
31
|
/**
|
|
26
32
|
* The scale that keeps the whole frame visible: the smaller of the width fit and the height fit. `availableHeight` is
|
|
27
|
-
* the height left for the frame
|
|
28
|
-
*
|
|
33
|
+
* the height left for the frame: 0 (or not a number) means the height is not limited and the width fit is used, e.g. a
|
|
34
|
+
* phone, where the page scrolls. A room that is too small (negative, or under `MIN_FIT_SCALE` of the frame) is raised to
|
|
35
|
+
* that floor, so the frame never collapses. The result is letterboxed by the caller and never wider than the box.
|
|
29
36
|
*/
|
|
30
37
|
export declare function fitFrame(boxWidth: number, availableHeight: number, frame: StageViewport): FrameFit;
|
|
31
38
|
/** The stage width under which the whole frame would be an unreadable thumbnail, so a camera follows the action. */
|
|
@@ -1,27 +1,33 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
3
|
-
|
|
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
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*/ export function stageViewport(
|
|
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
|
-
|
|
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) {
|
|
16
19
|
return boxWidth > 0 && frameWidth > 0 ? boxWidth / frameWidth : 1;
|
|
17
20
|
}
|
|
21
|
+
/** The smallest scale the height fit may shrink the frame to: below it the text is unreadable, so the page scrolls instead. */ export const MIN_FIT_SCALE = 0.35;
|
|
18
22
|
/**
|
|
19
23
|
* The scale that keeps the whole frame visible: the smaller of the width fit and the height fit. `availableHeight` is
|
|
20
|
-
* the height left for the frame
|
|
21
|
-
*
|
|
24
|
+
* the height left for the frame: 0 (or not a number) means the height is not limited and the width fit is used, e.g. a
|
|
25
|
+
* phone, where the page scrolls. A room that is too small (negative, or under `MIN_FIT_SCALE` of the frame) is raised to
|
|
26
|
+
* that floor, so the frame never collapses. The result is letterboxed by the caller and never wider than the box.
|
|
22
27
|
*/ export function fitFrame(boxWidth, availableHeight, frame) {
|
|
23
28
|
const byWidth = fitScale(boxWidth, frame.width);
|
|
24
|
-
const
|
|
29
|
+
const limited = Number.isFinite(availableHeight) && availableHeight !== 0 && frame.height > 0;
|
|
30
|
+
const byHeight = limited ? Math.max(availableHeight, frame.height * MIN_FIT_SCALE) / frame.height : Number.POSITIVE_INFINITY;
|
|
25
31
|
const scale = Math.min(byWidth, byHeight);
|
|
26
32
|
return {
|
|
27
33
|
scale,
|
|
@@ -59,6 +59,7 @@ export type ParentMessage = Static<typeof ParentMessageSchema>;
|
|
|
59
59
|
export declare const FrameMessageSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
|
|
60
60
|
type: import("@sinclair/typebox").TLiteral<"ready">;
|
|
61
61
|
recordingId: import("@sinclair/typebox").TString;
|
|
62
|
+
preparing: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
|
|
62
63
|
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
63
64
|
version: import("@sinclair/typebox").TLiteral<1>;
|
|
64
65
|
nonce: import("@sinclair/typebox").TString;
|
|
@@ -104,6 +105,14 @@ export declare const FrameMessageSchema: import("@sinclair/typebox").TUnion<[imp
|
|
|
104
105
|
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
105
106
|
version: import("@sinclair/typebox").TLiteral<1>;
|
|
106
107
|
nonce: import("@sinclair/typebox").TString;
|
|
108
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
109
|
+
type: import("@sinclair/typebox").TLiteral<"skipped">;
|
|
110
|
+
stepId: import("@sinclair/typebox").TString;
|
|
111
|
+
actionIndex: import("@sinclair/typebox").TInteger;
|
|
112
|
+
reason: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"target_timeout">, import("@sinclair/typebox").TLiteral<"target_unsupported">, import("@sinclair/typebox").TLiteral<"option_not_found">, import("@sinclair/typebox").TLiteral<"navigate_failed">, import("@sinclair/typebox").TLiteral<"action_error">, import("@sinclair/typebox").TLiteral<"step_unknown">]>;
|
|
113
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
114
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
115
|
+
nonce: import("@sinclair/typebox").TString;
|
|
107
116
|
}>, import("@sinclair/typebox").TObject<{
|
|
108
117
|
type: import("@sinclair/typebox").TLiteral<"unanswered">;
|
|
109
118
|
key: import("@sinclair/typebox").TString;
|
|
@@ -78,10 +78,11 @@ const strict = {
|
|
|
78
78
|
}, strict)
|
|
79
79
|
]);
|
|
80
80
|
/** What the frame sends to the embedding page. */ export const FrameMessageSchema = Type.Union([
|
|
81
|
-
Type.Object({
|
|
81
|
+
/** `preparing` means the frame is still rebuilding the state before its start chapter: it heard the hello, play waits. */ Type.Object({
|
|
82
82
|
...envelope,
|
|
83
83
|
type: Type.Literal('ready'),
|
|
84
|
-
recordingId: id
|
|
84
|
+
recordingId: id,
|
|
85
|
+
preparing: Type.Optional(Type.Boolean())
|
|
85
86
|
}, strict),
|
|
86
87
|
Type.Object({
|
|
87
88
|
...envelope,
|
|
@@ -117,6 +118,18 @@ const strict = {
|
|
|
117
118
|
at: ms,
|
|
118
119
|
playing: Type.Boolean()
|
|
119
120
|
}, strict),
|
|
121
|
+
/**
|
|
122
|
+
* An action the tape played on without (`skipFailedSteps`): the target never appeared, a choice was missing or the
|
|
123
|
+
* action threw. `actionIndex` is -1 when a prelude dropped the whole step. The player counts them.
|
|
124
|
+
*/ Type.Object({
|
|
125
|
+
...envelope,
|
|
126
|
+
type: Type.Literal('skipped'),
|
|
127
|
+
stepId: id,
|
|
128
|
+
actionIndex: Type.Integer({
|
|
129
|
+
minimum: -1
|
|
130
|
+
}),
|
|
131
|
+
reason: FailureReasonSchema
|
|
132
|
+
}, strict),
|
|
120
133
|
/** A call no recorded answer covered (`replay_unanswered`): the audit fails on any. */ Type.Object({
|
|
121
134
|
...envelope,
|
|
122
135
|
type: Type.Literal('unanswered'),
|
|
@@ -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,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.
|
|
3
|
+
"version": "0.10.259",
|
|
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",
|