Skip to content

Replay your coding agent sessions as a map and a timeline

perf(viewer): stop re-rendering the explorer on every playback frame

rav4nnf3ee2ec0d909
diff --git a/viewer/src/core/playback.test.ts b/viewer/src/core/playback.test.ts
index cfef6a5..ccc4bb7 100644
--- a/viewer/src/core/playback.test.ts
+++ b/viewer/src/core/playback.test.ts
@@ -3,6 +3,7 @@ import {
MS_PER_EVENT,
SPEEDS,
initialPlayback,
+ playbackClock,
playbackReducer,
replayKeyAction,
type PlaybackAction,
@@ -15,6 +16,22 @@ const run = (s: PlaybackState, ...actions: PlaybackAction[]) =>
const loaded = (n = 100, start = 10) =>
playbackReducer(initialPlayback, { type: 'load', n, start });
+const clocked = (s: PlaybackState) => {
+ const c = {
+ state: s,
+ actions: [] as PlaybackAction[],
+ frames(...ts: number[]) {
+ ts.forEach(tick);
+ return c;
+ },
+ };
+ const tick = playbackClock(s.speedIdx, (a) => {
+ c.actions.push(a);
+ c.state = playbackReducer(c.state, a);
+ });
+ return c;
+};
+
describe('playbackReducer', () => {
it('loads paused and clamps the start', () => {
expect(loaded(5, 99).p).toBe(4);
@@ -58,27 +75,55 @@ describe('playbackReducer', () => {
expect(SPEEDS[s2.speedIdx]).toBe(1);
});
- it('ticks advance by elapsed time times speed', () => {
- let s = run(loaded(), { type: 'play' }); // 4x
- s = playbackReducer(s, { type: 'tick', dtMs: MS_PER_EVENT / 8 });
- expect(s.p).toBe(10); // 0.5 event accumulated
- s = playbackReducer(s, { type: 'tick', dtMs: MS_PER_EVENT / 8 });
- expect(s.p).toBe(11);
- s = playbackReducer(s, { type: 'tick', dtMs: MS_PER_EVENT });
- expect(s.p).toBe(15);
- });
-
it('stops at the last event', () => {
let s = run(loaded(20, 18), { type: 'play' });
- s = playbackReducer(s, { type: 'tick', dtMs: MS_PER_EVENT * 10 });
+ s = playbackReducer(s, { type: 'advance', by: 10 });
expect(s.p).toBe(19);
expect(s.playing).toBe(false);
- expect(playbackReducer(s, { type: 'tick', dtMs: 1000 })).toBe(s);
+ expect(playbackReducer(s, { type: 'advance', by: 1 })).toBe(s);
});
- it('ignores ticks while paused', () => {
+ it('ignores advances while paused', () => {
const s = loaded();
- expect(playbackReducer(s, { type: 'tick', dtMs: 1000 })).toBe(s);
+ expect(playbackReducer(s, { type: 'advance', by: 1 })).toBe(s);
+ });
+});
+
+describe('playbackClock', () => {
+ const playing = (n = 100, start = 10) =>
+ run(loaded(n, start), { type: 'play' });
+ const event4x = MS_PER_EVENT / 4;
+
+ it('a frame that completes no event leaves the state untouched', () => {
+ const s = playing();
+ const c = clocked(s).frames(1000, 1016.7, 1033.4);
+ expect(c.actions).toEqual([]);
+ expect(c.state).toBe(s);
+ });
+
+ it('a frame that completes one event advances by exactly one', () => {
+ const c = clocked(playing()).frames(1000, 1000 + event4x);
+ expect(c.actions).toEqual([{ type: 'advance', by: 1 }]);
+ expect(c.state.p).toBe(11);
+ });
+
+ it('carries the fraction of an event across frames', () => {
+ const c = clocked(playing()).frames(1000, 1000 + event4x / 2);
+ expect(c.state.p).toBe(10);
+ c.frames(1000 + event4x, 1000 + event4x * 5);
+ expect(c.state.p).toBe(15);
+ });
+
+ it('a long stalled frame counts as 250 ms, not as the stall', () => {
+ const c = clocked(playing(1000, 0)).frames(1000, 31_000);
+ expect(c.state.p).toBe(4);
+ expect(c.state.playing).toBe(true);
+ });
+
+ it('plays at the speed it was created with', () => {
+ const s = run(loaded(), { type: 'cycleSpeed' }, { type: 'play' });
+ expect(SPEEDS[s.speedIdx]).toBe(16);
+ expect(clocked(s).frames(1000, 1000 + MS_PER_EVENT).state.p).toBe(26);
});
});
diff --git a/viewer/src/core/playback.ts b/viewer/src/core/playback.ts
index d0b849d..e8efc9e 100644
--- a/viewer/src/core/playback.ts
+++ b/viewer/src/core/playback.ts
@@ -1,12 +1,14 @@
/**
- * Playback state machine for the Session Explorer. Pure: the rAF loop in
- * SessionExplorer feeds `tick` with elapsed milliseconds, everything else is a
- * user action. Unit-tested in `playback.test.ts`.
+ * Playback state machine for the Session Explorer. The reducer is pure:
+ * `playbackClock` feeds it `advance` from the rAF loop once a whole event is
+ * due, everything else is a user action. Unit-tested in `playback.test.ts`.
*/
export const SPEEDS = [1, 4, 16] as const;
/** ms of wall clock per event at 1x (the default pacing). */
export const MS_PER_EVENT = 220;
+/** A longer frame counts as this long: rAF stalls while the tab is hidden. */
+const MAX_FRAME_MS = 250;
export interface PlaybackState {
/** playhead: index of the current event */
@@ -15,8 +17,6 @@ export interface PlaybackState {
n: number;
playing: boolean;
speedIdx: number;
- /** fractional events accumulated between ticks */
- acc: number;
}
export type PlaybackAction =
@@ -27,14 +27,13 @@ export type PlaybackAction =
| { type: 'pause' }
| { type: 'toggle' }
| { type: 'cycleSpeed' }
- | { type: 'tick'; dtMs: number };
+ | { type: 'advance'; by: number };
export const initialPlayback: PlaybackState = {
p: 0,
n: 0,
playing: false,
speedIdx: 1,
- acc: 0,
};
const clamp = (i: number, n: number) => Math.max(0, Math.min(n - 1, i));
@@ -50,38 +49,50 @@ export function playbackReducer(
n: a.n,
p: a.n ? clamp(a.start, a.n) : 0,
playing: false,
- acc: 0,
};
case 'seek':
if (!s.n) return s;
- return { ...s, p: clamp(a.index, s.n), playing: false, acc: 0 };
+ return { ...s, p: clamp(a.index, s.n), playing: false };
case 'step':
if (!s.n) return s;
- return { ...s, p: clamp(s.p + a.delta, s.n), playing: false, acc: 0 };
+ return { ...s, p: clamp(s.p + a.delta, s.n), playing: false };
case 'play':
if (s.n < 2) return s;
// At the end, play restarts from the top.
- return { ...s, playing: true, acc: 0, p: s.p >= s.n - 1 ? 0 : s.p };
+ return { ...s, playing: true, p: s.p >= s.n - 1 ? 0 : s.p };
case 'pause':
- return s.playing ? { ...s, playing: false, acc: 0 } : s;
+ return s.playing ? { ...s, playing: false } : s;
case 'toggle':
return playbackReducer(s, { type: s.playing ? 'pause' : 'play' });
case 'cycleSpeed':
return { ...s, speedIdx: (s.speedIdx + 1) % SPEEDS.length };
- case 'tick': {
+ case 'advance': {
if (!s.playing) return s;
- const acc = s.acc + (a.dtMs * SPEEDS[s.speedIdx]) / MS_PER_EVENT;
- if (acc < 1) return { ...s, acc };
- const adv = Math.floor(acc);
- if (s.p >= s.n - 1) return { ...s, playing: false, acc: 0 };
- const p = clamp(s.p + adv, s.n);
- return { ...s, p, acc: acc - adv, playing: p < s.n - 1 };
+ const p = clamp(s.p + a.by, s.n);
+ return { ...s, p, playing: p < s.n - 1 };
}
default:
return s;
}
}
+export function playbackClock(
+ speedIdx: number,
+ dispatch: (a: PlaybackAction) => void
+) {
+ let last = 0;
+ let acc = 0;
+ return (t: number) => {
+ const dt = last ? Math.min(t - last, MAX_FRAME_MS) : 0;
+ last = t;
+ acc += (dt * SPEEDS[speedIdx]) / MS_PER_EVENT;
+ const by = Math.floor(acc);
+ if (!by) return;
+ acc -= by;
+ dispatch({ type: 'advance', by });
+ };
+}
+
/** What a key press in the replay region does (see its aria-label). */
export type ReplayKeyAction =
| { type: 'toggle' }
diff --git a/viewer/src/explorer/usePlaybackWindow.ts b/viewer/src/explorer/usePlaybackWindow.ts
index 8a7ee5d..e9072aa 100644
--- a/viewer/src/explorer/usePlaybackWindow.ts
+++ b/viewer/src/explorer/usePlaybackWindow.ts
@@ -6,7 +6,12 @@ import {
type KeyboardEvent,
} from 'react';
import type { SessionMap, SessionMapEvent } from '@/core/schema';
-import { initialPlayback, playbackReducer, replayKeyAction } from '@/core/playback';
+import {
+ initialPlayback,
+ playbackClock,
+ playbackReducer,
+ replayKeyAction,
+} from '@/core/playback';
import { MAP_RADIUS } from '@/core/mapGeometry';
import {
buildTree,
@@ -59,20 +64,17 @@ export function usePlaybackWindow(map: SessionMap) {
})
);
- // rAF loop while playing; the reducer turns elapsed ms into events.
useEffect(() => {
if (!pb.playing) return;
+ const tick = playbackClock(pb.speedIdx, dispatch);
let raf = 0;
- let last = 0;
const frame = (t: number) => {
- const dt = last ? t - last : 0;
- last = t;
- if (dt) dispatch({ type: 'tick', dtMs: dt });
+ tick(t);
raf = requestAnimationFrame(frame);
};
raf = requestAnimationFrame(frame);
return () => cancelAnimationFrame(raf);
- }, [pb.playing]);
+ }, [pb.playing, pb.speedIdx]);
const seek = useCallback(
(index: number) => dispatch({ type: 'seek', index }),