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.
Files changed (39) hide show
  1. package/dist/.build-ok +1 -1
  2. package/dist/fe/components/Replay/_components/ReplayChapters/index.js +12 -0
  3. package/dist/fe/components/Replay/_components/ReplayCursor/index.js +5 -1
  4. package/dist/fe/components/Replay/_components/ReplayPlayer/ReplayView.js +2 -0
  5. package/dist/fe/components/Replay/_components/ReplayStage/index.js +4 -3
  6. package/dist/fe/components/Replay/_components/ReplayStage/types.d.ts +3 -0
  7. package/dist/fe/components/Replay/_hooks/useCameraPan.js +8 -5
  8. package/dist/fe/components/Replay/_hooks/useStageScale.js +11 -4
  9. package/dist/fe/components/Replay/_store/replayStore.js +8 -0
  10. package/dist/fe/components/Replay/_types/frame.d.ts +40 -0
  11. package/dist/fe/components/Replay/_types/frame.js +1 -0
  12. package/dist/fe/components/Replay/_types/index.d.ts +1 -0
  13. package/dist/fe/components/Replay/_types/index.js +1 -0
  14. package/dist/fe/components/Replay/_types/player.d.ts +9 -0
  15. package/dist/fe/components/Replay/_utils/chapterRow.d.ts +8 -0
  16. package/dist/fe/components/Replay/_utils/chapterRow.js +17 -0
  17. package/dist/fe/components/Replay/_utils/controller.js +13 -4
  18. package/dist/fe/components/Replay/_utils/controllerReports.d.ts +2 -1
  19. package/dist/fe/components/Replay/_utils/controllerReports.js +8 -1
  20. package/dist/fe/components/Replay/_utils/cursorMotion.d.ts +16 -2
  21. package/dist/fe/components/Replay/_utils/cursorMotion.js +42 -8
  22. package/dist/fe/components/Replay/_utils/frameBridge.d.ts +1 -40
  23. package/dist/fe/components/Replay/_utils/frameBridge.js +71 -29
  24. package/dist/fe/components/Replay/_utils/frameFocus.d.ts +8 -0
  25. package/dist/fe/components/Replay/_utils/frameFocus.js +15 -0
  26. package/dist/fe/components/Replay/_utils/frameHold.d.ts +11 -0
  27. package/dist/fe/components/Replay/_utils/frameHold.js +24 -0
  28. package/dist/fe/components/Replay/_utils/framePrelude.d.ts +26 -0
  29. package/dist/fe/components/Replay/_utils/framePrelude.js +37 -0
  30. package/dist/fe/components/Replay/_utils/replayProgress.d.ts +2 -0
  31. package/dist/fe/components/Replay/_utils/replayProgress.js +4 -0
  32. package/dist/fe/components/Replay/_utils/stageViewport.d.ts +17 -10
  33. package/dist/fe/components/Replay/_utils/stageViewport.js +18 -12
  34. package/dist/src/Client/Replay/channel/channel.d.ts +9 -0
  35. package/dist/src/Client/Replay/channel/channel.js +15 -2
  36. package/dist/src/Client/Replay/driver/input.js +9 -3
  37. package/dist/src/Client/Replay/timeline/timeline.d.ts +5 -0
  38. package/dist/src/Client/Replay/timeline/timeline.js +8 -0
  39. package/package.json +1 -1
package/dist/.build-ok CHANGED
@@ -1 +1 @@
1
- 0.10.257
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(manifest.viewport);
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
- if (reduced || !on) gsap.set(el, {
17
- x: to.x,
18
- y: to.y
19
- });
20
- else gsap.to(el, {
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
- return Math.max(0, window.innerHeight - (root.offsetHeight - view.offsetHeight) - offset - FIT_GAP);
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) setRoom({
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 { };
@@ -1 +1,2 @@
1
1
  export * from './player';
2
+ export * from './frame';
@@ -1 +1,2 @@
1
1
  export * from './player';
2
+ export * from './frame';
@@ -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
- const awaitFrame = ()=>{
102
- const giveUp = after(options.readyTimeoutMs ?? READY_TIMEOUT_MS, ()=>{
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
- onReady: (recordingId: string) => void;
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 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,43 +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
- * 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
- // 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 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
- const tick = ()=>send((e)=>({
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: options.settle ?? (()=>new Promise((resolve)=>void win.setTimeout(resolve, 0))),
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 })=>win.console?.warn(`[replay] step ${step.id} action ${actionIndex} skipped: ${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
- if (held) resumeAfterHold = true;
141
- else timeline.play();
153
+ clock.play();
142
154
  break;
143
155
  case 'pause':
144
- resumeAfterHold = false;
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
- if (start) timeline.seekChapter(start.id);
170
- const first = steps.findIndex((step)=>step.at >= (start?.from ?? 0));
171
- if (first >= 0) void runFrom(first, generation);
172
- announce();
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
- /** 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 {
@@ -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 (0 or less means the height is not limited, e.g. a phone, where the page scrolls).
28
- * The result is letterboxed by the caller: it is never wider than the box and never taller than the room.
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
- /** 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) {
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 (0 or less means the height is not limited, e.g. a phone, where the page scrolls).
21
- * The result is letterboxed by the caller: it is never wider than the box and never taller than the room.
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 byHeight = availableHeight > 0 && frame.height > 0 ? availableHeight / frame.height : Number.POSITIVE_INFINITY;
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.257",
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",