nucleus-core-ts 0.10.258 → 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 (24) 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/ReplayPlayer/ReplayView.js +2 -0
  4. package/dist/fe/components/Replay/_components/ReplayStage/index.js +3 -2
  5. package/dist/fe/components/Replay/_components/ReplayStage/types.d.ts +3 -0
  6. package/dist/fe/components/Replay/_hooks/useCameraPan.js +8 -5
  7. package/dist/fe/components/Replay/_hooks/useStageScale.js +11 -4
  8. package/dist/fe/components/Replay/_store/replayStore.js +8 -0
  9. package/dist/fe/components/Replay/_types/player.d.ts +9 -0
  10. package/dist/fe/components/Replay/_utils/chapterRow.d.ts +8 -0
  11. package/dist/fe/components/Replay/_utils/chapterRow.js +17 -0
  12. package/dist/fe/components/Replay/_utils/controller.js +13 -4
  13. package/dist/fe/components/Replay/_utils/controllerReports.d.ts +2 -1
  14. package/dist/fe/components/Replay/_utils/controllerReports.js +8 -1
  15. package/dist/fe/components/Replay/_utils/frameBridge.js +25 -8
  16. package/dist/fe/components/Replay/_utils/framePrelude.d.ts +3 -1
  17. package/dist/fe/components/Replay/_utils/framePrelude.js +2 -1
  18. package/dist/fe/components/Replay/_utils/replayProgress.d.ts +2 -0
  19. package/dist/fe/components/Replay/_utils/replayProgress.js +4 -0
  20. package/dist/fe/components/Replay/_utils/stageViewport.d.ts +5 -2
  21. package/dist/fe/components/Replay/_utils/stageViewport.js +6 -3
  22. package/dist/src/Client/Replay/channel/channel.d.ts +9 -0
  23. package/dist/src/Client/Replay/channel/channel.js +15 -2
  24. package/package.json +1 -1
package/dist/.build-ok CHANGED
@@ -1 +1 @@
1
- 0.10.258
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;
@@ -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,7 +18,7 @@ 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 { manifest, locale, frameSrc, frameRef, cursor, rate, chapterId, onArrive, loading, children } = props;
21
22
  const frame = stageViewport();
22
23
  const fit = useStageScale(frame);
23
24
  const [whole, setWhole] = useState(false);
@@ -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';
@@ -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;
@@ -19,7 +19,7 @@ const MAX_KEY_LENGTH = 200;
19
19
  let generation = 0;
20
20
  let abortWait = ()=>{};
21
21
  const clock = createFrameHold(timeline);
22
- // True while the state before the start chapter is being rebuilt: the parent hears nothing and its messages wait.
22
+ // True while the state before the start chapter is rebuilt: ticks stop, only the hello is answered (`preparing`).
23
23
  let preluding = false;
24
24
  let stopped = false;
25
25
  const send = (build)=>{
@@ -28,8 +28,21 @@ const MAX_KEY_LENGTH = 200;
28
28
  const announce = ()=>send((e)=>({
29
29
  ...e,
30
30
  type: 'ready',
31
- recordingId: manifest.id
31
+ recordingId: manifest.id,
32
+ ...preluding ? {
33
+ preparing: true
34
+ } : {}
32
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
44
+ }));
45
+ };
33
46
  const tick = ()=>{
34
47
  if (!preluding) send((e)=>({
35
48
  ...e,
@@ -77,7 +90,7 @@ const MAX_KEY_LENGTH = 200;
77
90
  waitForFrame: options.waitForFrame,
78
91
  waitUntil: (at)=>timeline.waitUntil(at),
79
92
  hold: clock.hold,
80
- onSkip: options.skipFailedSteps === false ? undefined : ({ actionIndex, reason })=>win.console?.warn(`[replay] step ${step.id} action ${actionIndex} skipped: ${reason}`)
93
+ onSkip: options.skipFailedSteps === false ? undefined : ({ actionIndex, reason })=>reportSkip(step.id, actionIndex, reason)
81
94
  });
82
95
  if (gen !== generation) return false;
83
96
  if (result.ok) {
@@ -128,11 +141,14 @@ const MAX_KEY_LENGTH = 200;
128
141
  peer: options.parent,
129
142
  nonce: options.nonce
130
143
  });
131
- if (!message || preluding) return;
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;
132
151
  switch(message.type){
133
- case 'hello':
134
- announce();
135
- break;
136
152
  case 'play':
137
153
  clock.play();
138
154
  break;
@@ -187,7 +203,8 @@ const MAX_KEY_LENGTH = 200;
187
203
  targetTimeoutMs,
188
204
  settle,
189
205
  cancelled: ()=>stopped
190
- }
206
+ },
207
+ onSkip: options.skipFailedSteps === false ? undefined : reportSkip
191
208
  }).then(()=>{
192
209
  preluding = false;
193
210
  if (!stopped) begin();
@@ -1,4 +1,4 @@
1
- import { type Ms, type ReplayStep, type Timeline, type VisibleCheck, type Win } from '../../../../src/Client/Replay';
1
+ import { type FailureReason, type Ms, type ReplayStep, type Timeline, type VisibleCheck, type Win } from '../../../../src/Client/Replay';
2
2
  export interface FramePreludeOptions {
3
3
  win: Win;
4
4
  attribute: string;
@@ -11,6 +11,8 @@ export interface FramePreludeOptions {
11
11
  visible?: VisibleCheck;
12
12
  targetTimeoutMs?: number;
13
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;
14
16
  /** True once the frame was stopped: the prelude ends at the next action. */
15
17
  cancelled: () => boolean;
16
18
  }
@@ -17,7 +17,7 @@ import { runStep } from '../../../../src/Client/Replay';
17
17
  const actions = step.actions.filter(changesState);
18
18
  if (actions.length === 0) continue;
19
19
  timeline.jumpTo(Math.min(step.at, options.until));
20
- await runStep({
20
+ const result = await runStep({
21
21
  ...step,
22
22
  actions
23
23
  }, {
@@ -32,5 +32,6 @@ import { runStep } from '../../../../src/Client/Replay';
32
32
  waitForFrame: async ()=>{},
33
33
  waitUntil: async (at)=>timeline.jumpTo(Math.min(at, options.until))
34
34
  });
35
+ if (!result.ok) options.onSkip?.(step.id, result.actionIndex, result.reason);
35
36
  }
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);
@@ -26,10 +26,13 @@ export interface FrameFit {
26
26
  width: number;
27
27
  height: number;
28
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;
29
31
  /**
30
32
  * The scale that keeps the whole frame visible: the smaller of the width fit and the height fit. `availableHeight` is
31
- * the height left for the frame (0 or less means the height is not limited, e.g. a phone, where the page scrolls).
32
- * 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.
33
36
  */
34
37
  export declare function fitFrame(boxWidth: number, availableHeight: number, frame: StageViewport): FrameFit;
35
38
  /** The stage width under which the whole frame would be an unreadable thumbnail, so a camera follows the action. */
@@ -18,13 +18,16 @@
18
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) {
19
19
  return boxWidth > 0 && frameWidth > 0 ? boxWidth / frameWidth : 1;
20
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;
21
22
  /**
22
23
  * The scale that keeps the whole frame visible: the smaller of the width fit and the height fit. `availableHeight` is
23
- * the height left for the frame (0 or less means the height is not limited, e.g. a phone, where the page scrolls).
24
- * 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.
25
27
  */ export function fitFrame(boxWidth, availableHeight, frame) {
26
28
  const byWidth = fitScale(boxWidth, frame.width);
27
- 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;
28
31
  const scale = Math.min(byWidth, byHeight);
29
32
  return {
30
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'),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nucleus-core-ts",
3
- "version": "0.10.258",
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",