Skip to content

Commit 2de3ca5

Browse files
fix(player): the interactive playback clock absorbs a main-thread stall instead of skipping past it (#4053)
* fix(player): the interactive playback clock absorbs a main-thread stall instead of skipping past it TransportClock's monotonic time is a bare wall-clock read with no protection against a long gap between reads. On a composition whose first real paint blocks the main thread for several seconds, nothing reads the clock during that time; the next read reported the whole gap as elapsed playback, so the composition jumped forward instead of continuing from where it froze. A gap over 500ms is now treated as a stall and corrected to a 33ms advance instead of reported whole, matching GSAP's own ticker default. The correction lives inside now() itself so every reader benefits, since this clock is read every real frame by more than one driver. Render/export capture is unaffected: it always pauses and seeks to an exact time rather than playing, so the correction never engages there. * chore(player): drop internal tracker references from stall-policy comments * fix(player): stop the stall correction from corrupting the clock while audio is authoritative An independent review found that the previous commit's correction ran unconditionally on every read, including while an attached audio source was providing the time. Audio keeps playing through a JS-thread stall, so a gap between reads there is not a stall — but the correction still shifted the clock's internal reference point, and that corruption only surfaced later, on an unrelated read, once the clock fell back to monotonic timing (audio pausing or buffering). The correction now runs only in the monotonic branch, after audio has had its chance to answer. Added a regression test that fails against the previous placement and passes against this one. * fix(player): keep the stall correction's read timestamp fresh through an audio-authoritative stretch A second independent review found the previous commit's fix was incomplete: it stopped a stall correction from firing while audio was answering a read, but the internal timestamp it compares against only moved on monotonic reads. Any monotonic read from before audio took over stayed the comparison point for as long as audio kept answering, so the whole audio-authoritative stretch read as one giant stall the moment audio dropped out again — reproducing the exact corruption the previous commit set out to fix, through a different door. The same gap also meant a real, non-stalled audio outage got smoothed away to almost nothing instead of advancing normally. The read timestamp now moves on every read, audio-answered or not; only the correction itself stays scoped to the monotonic branch. Two regression tests reproduce both failure modes and pass here; both were confirmed to fail against the prior placement. * fix(player): stop comparing a monotonic read against a timestamp audio made meaningless A third review found the previous commit's fix was still incomplete: keeping the read timestamp fresh during audio-authoritative reads stops it going stale, but a real gap with no reads at all — the main thread genuinely frozen while an attached audio element kept playing on its own, unaffected by JS scheduling — still read as a stall the moment audio next failed to answer, discarding real elapsed time that audio had been correctly tracking the whole way. An audio-answered read now clears the timestamp instead of stamping it, the same as a seek. The next monotonic read then starts from `_playStartMs`, which nothing but a genuine discontinuity (play, seek, rate change, detach) ever touches — an anchor that already reconstructs real elapsed time correctly on its own, without needing the correction to reason about a comparison point it has no way to make meaningful once audio was involved. A stall between two purely monotonic reads, with no audio in between, is unaffected and still corrected exactly as before. Two regression tests cover the transition: a real unread gap while audio was tracking correctly must not be discarded, and a sustained audio outage must still advance at real speed rather than being smoothed to nothing. Both were confirmed to fail against the prior commit's placement. * chore(core): trim clock comments
1 parent 82f4926 commit 2de3ca5

4 files changed

Lines changed: 277 additions & 8 deletions

File tree

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
import { describe, it, expect } from "vitest";
2+
import { TransportClock } from "./clock";
3+
4+
// Stall policy for TransportClock's interactive playback — see the PR body.
5+
6+
function createClock(opts?: ConstructorParameters<typeof TransportClock>[0]) {
7+
let ms = 0;
8+
const clock = new TransportClock({ nowMs: () => ms, ...opts });
9+
const advance = (deltaMs: number) => {
10+
ms += deltaMs;
11+
};
12+
return { clock, advance };
13+
}
14+
15+
describe("TransportClock stall policy — interactive playback", () => {
16+
it("a gap under the 500ms threshold advances exactly, unsmoothed", () => {
17+
const { clock, advance } = createClock();
18+
clock.play();
19+
advance(16); // one ordinary frame at 60fps
20+
expect(clock.now()).toBeCloseTo(0.016, 10);
21+
advance(480); // still under threshold
22+
expect(clock.now()).toBeCloseTo(0.496, 10);
23+
});
24+
25+
it("blocking the thread for 4.6s (the measured frost-sequence-camera-orbit stall) advances by at most the adjusted lag, not the whole gap", () => {
26+
const { clock, advance } = createClock();
27+
clock.play();
28+
advance(16);
29+
const before = clock.now(); // establishes the read baseline the stall is measured against
30+
advance(4600); // the rAF loop never got a chance to run during this
31+
const after = clock.now(); // the first read after the stall is what applies the correction
32+
expect(after - before).toBeCloseTo(0.033, 10);
33+
expect(after - before).toBeLessThan(4.6);
34+
});
35+
36+
it("a stall this severe (8s, the measured WebKit-engine case) is still corrected, not just the smaller 4.6s one", () => {
37+
const { clock, advance } = createClock();
38+
clock.play();
39+
advance(16);
40+
const before = clock.now();
41+
advance(8000);
42+
expect(clock.now() - before).toBeCloseTo(0.033, 10);
43+
});
44+
45+
it("playback continues advancing normally after a stall — the correction does not stick the clock", () => {
46+
const { clock, advance } = createClock();
47+
clock.play();
48+
advance(16);
49+
clock.now(); // read baseline, so the next gap is actually measured as a stall
50+
advance(4600); // stall
51+
const afterStall = clock.now();
52+
advance(16); // one more ordinary frame
53+
expect(clock.now() - afterStall).toBeCloseTo(0.016, 10);
54+
});
55+
56+
it("many reads within the same real frame do not each get treated as a separate stall window", () => {
57+
const { clock, advance } = createClock();
58+
clock.play();
59+
advance(16);
60+
// Several callers read `now()` within the same real frame (state sync,
61+
// media sync, audio timing, plus a second driver like the parent-tick
62+
// bridge) — none of those back-to-back reads should see each other as a
63+
// gap.
64+
const a = clock.now();
65+
const b = clock.now();
66+
const c = clock.now();
67+
expect(a).toBe(b);
68+
expect(b).toBe(c);
69+
advance(4600); // a real stall before the next frame's reads
70+
expect(clock.now() - a).toBeCloseTo(0.033, 10);
71+
});
72+
73+
it("a second reader (simulating the parent-tick bridge) is protected by the same correction, with no wiring of its own", () => {
74+
const { clock, advance } = createClock();
75+
clock.play();
76+
// Two independent "drivers" reading the same clock, exactly as
77+
// packages/core/src/runtime/init.ts's transportTick and
78+
// packages/player/src/hyperframes-player.ts's parent-tick bridge do —
79+
// neither is a distinguished caller; both just call now().
80+
const driverA = () => clock.now();
81+
const driverB = () => clock.now();
82+
advance(16);
83+
driverA();
84+
advance(4600); // stall, discovered by whichever driver reads first
85+
const readByB = driverB(); // the OTHER driver — not the one that established the baseline
86+
expect(readByB).toBeCloseTo(0.049, 10); // 0.016 + 0.033, corrected regardless of who asks
87+
});
88+
89+
it("a long gap between reads while audio is authoritative does not corrupt the later monotonic fallback", () => {
90+
const { clock, advance } = createClock({ duration: 30 });
91+
const audioEl = { currentTime: 2, paused: false } as HTMLMediaElement;
92+
clock.play();
93+
clock.attachAudioSource({ el: audioEl, compositionStart: 0, mediaStart: 0 });
94+
expect(clock.now()).toBe(2); // audio-authoritative, correct
95+
advance(5000); // audio itself doesn't stall; nothing here reads the monotonic side
96+
audioEl.currentTime = 5;
97+
expect(clock.now()).toBe(5); // still audio-authoritative, still correct
98+
// Audio becomes unavailable without a formal detachAudioSource() call —
99+
// now() falls through to monotonic within the same read.
100+
Object.assign(audioEl, { paused: true });
101+
// First monotonic-branch read: must not be held back by the 5s audio gap.
102+
// A corrupted `_playStartMs` would report ~33ms instead of the true ~5s.
103+
expect(clock.now()).toBeCloseTo(5, 2);
104+
});
105+
106+
it("a monotonic read before audio takes over does not go stale across the whole audio-authoritative stretch", () => {
107+
const { clock, advance } = createClock({ duration: 30 });
108+
const audioEl = { currentTime: 0, paused: true } as HTMLMediaElement;
109+
clock.play();
110+
clock.attachAudioSource({ el: audioEl, compositionStart: 0, mediaStart: 0 });
111+
expect(clock.now()).toBeCloseTo(0, 5); // audio not ready yet, falls to monotonic
112+
advance(10); // audio starts an instant later
113+
Object.assign(audioEl, { paused: false, currentTime: 0.01 });
114+
expect(clock.now()).toBeCloseTo(0.01, 2); // now audio-authoritative
115+
advance(10_000); // ten real seconds pass, entirely under audio's own clock
116+
audioEl.currentTime = 10.01;
117+
expect(clock.now()).toBe(10.01); // still audio-authoritative, still correct
118+
Object.assign(audioEl, { paused: true }); // audio drops out, no detachAudioSource()
119+
// The stale pre-audio read must not be what this gets compared against:
120+
// ~10.01s of real time genuinely passed and none of it was a stall.
121+
expect(clock.now()).toBeCloseTo(10.01, 1);
122+
});
123+
124+
it("real elapsed time during a sustained audio outage advances normally, not smoothed away as a stall", () => {
125+
const { clock, advance } = createClock({ duration: 30 });
126+
const audioEl = { currentTime: 0, paused: true } as HTMLMediaElement;
127+
clock.play();
128+
clock.attachAudioSource({ el: audioEl, compositionStart: 0, mediaStart: 0 });
129+
// Audio stays unavailable (buffering) for two real seconds, polled at a
130+
// normal frame cadence — no JS-thread stall anywhere in this window.
131+
let reported = clock.now();
132+
for (let frame = 0; frame < 120; frame++) {
133+
advance(16.666);
134+
reported = clock.now();
135+
}
136+
expect(reported).toBeCloseTo(2, 1);
137+
});
138+
139+
it("a real unread gap while audio was tracking correctly is not mistaken for a stall once audio drops", () => {
140+
const { clock, advance } = createClock({ duration: 30 });
141+
const audioEl = { currentTime: 0, paused: false } as HTMLMediaElement;
142+
clock.play();
143+
clock.attachAudioSource({ el: audioEl, compositionStart: 0, mediaStart: 0 });
144+
expect(clock.now()).toBe(0);
145+
advance(100);
146+
audioEl.currentTime = 0.1;
147+
expect(clock.now()).toBeCloseTo(0.1, 5); // audio-authoritative, last confirmed position
148+
// Nothing reads the clock for 5 real seconds — audio itself was still
149+
// playing the whole time (native audio isn't gated by JS scheduling),
150+
// there was no render stall here, and the composition should read as
151+
// if 5s of real playback happened, not ~33ms of corrected "stall".
152+
advance(5000);
153+
Object.assign(audioEl, { paused: true }); // audio becomes unavailable right as reads resume
154+
expect(clock.now()).toBeCloseTo(5.1, 1);
155+
});
156+
157+
it("a long real gap while genuinely paused is not a stall — resuming play() does not inherit it", () => {
158+
const { clock, advance } = createClock();
159+
clock.play();
160+
advance(16);
161+
clock.pause();
162+
advance(10_000); // ten real seconds paused — a user just left the tab
163+
clock.play();
164+
advance(16);
165+
expect(clock.now()).toBeCloseTo(0.032, 10);
166+
});
167+
168+
it("seeking right after a corrected stall does not inherit or re-trigger the correction", () => {
169+
const { clock, advance } = createClock({ duration: 30 });
170+
clock.play();
171+
advance(16);
172+
clock.now(); // read baseline
173+
advance(4600); // stall
174+
expect(clock.now()).toBeCloseTo(0.049, 10); // this read is what applies the correction
175+
clock.seek(10); // an explicit user scrub — must override cleanly
176+
expect(clock.now()).toBe(10); // the seek's target, not something the stall's math leaked into
177+
advance(16); // ordinary next frame after the seek
178+
expect(clock.now()).toBeCloseTo(10.016, 10);
179+
});
180+
181+
it("a rate change right after a corrected stall applies the new rate from the corrected point, not the raw gap", () => {
182+
const { clock, advance } = createClock();
183+
clock.play();
184+
advance(16);
185+
clock.now(); // read baseline
186+
advance(4600); // stall; setRate below is what next reads the clock
187+
clock.setRate(2);
188+
// setRate reads now() before switching rate, which is where the 4.6s gap
189+
// gets corrected to the 33ms adjusted lag: 0.016 + 0.033 = 0.049.
190+
advance(16); // one more frame, now at the new 2x rate
191+
expect(clock.now()).toBeCloseTo(0.049 + 0.032, 5);
192+
});
193+
});
194+
195+
describe("TransportClock stall policy — render/export capture is untouched", () => {
196+
// packages/producer's `renderSeek` (init.ts) always pauses then seeks; never plays.
197+
it("a seek while paused reports exactly the seeked time, regardless of any elapsed wall time before it", () => {
198+
const { clock, advance } = createClock({ duration: 30 });
199+
clock.seek(1 / 30);
200+
expect(clock.now()).toBe(1 / 30);
201+
advance(60_000); // an arbitrarily long real gap between two render frames
202+
clock.seek(2 / 30);
203+
expect(clock.now()).toBe(2 / 30);
204+
});
205+
206+
it("a full frame-by-frame render pass, each frame preceded by a large real-time gap, advances exactly — never smoothed", () => {
207+
const { clock, advance } = createClock({ duration: 1 });
208+
const fps = 30;
209+
for (let frame = 0; frame <= fps; frame++) {
210+
advance(5000); // rendering one frame is slow in wall-clock terms; irrelevant to the result
211+
const target = Math.min(frame / fps, 1);
212+
clock.seek(target);
213+
expect(clock.now()).toBe(target);
214+
}
215+
});
216+
217+
it("isPlaying() is false throughout a render pass — the stall policy's gate is provably never open", () => {
218+
const { clock, advance } = createClock({ duration: 1 });
219+
for (let frame = 0; frame <= 30; frame++) {
220+
advance(1000);
221+
clock.seek(frame / 30);
222+
expect(clock.isPlaying()).toBe(false);
223+
}
224+
});
225+
});

‎packages/core/src/runtime/clock.test.ts‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,14 @@ function createClock(opts?: ConstructorParameters<typeof TransportClock>[0]) {
1010
return { clock, advance, getMs: () => ms };
1111
}
1212

13+
/** Advances `totalMs` in sub-threshold steps, reading `now()` each time (see clock.ts's stall policy). */
14+
function advancePolled(clock: TransportClock, advance: (deltaMs: number) => void, totalMs: number) {
15+
for (let remaining = totalMs; remaining > 0; remaining -= 250) {
16+
advance(Math.min(250, remaining));
17+
clock.now();
18+
}
19+
}
20+
1321
describe("TransportClock", () => {
1422
describe("initial state", () => {
1523
it("starts paused at time 0", () => {
@@ -108,8 +116,8 @@ describe("TransportClock", () => {
108116
clock.seek(10);
109117
expect(clock.isPlaying()).toBe(true);
110118
expect(clock.now()).toBe(10);
111-
advance(1000);
112-
expect(clock.now()).toBe(11);
119+
advancePolled(clock, advance, 1000);
120+
expect(clock.now()).toBeCloseTo(11, 5);
113121
});
114122

115123
it("clamps to 0", () => {
@@ -235,8 +243,8 @@ describe("TransportClock", () => {
235243
advance(5000);
236244
clock.seek(0);
237245
expect(clock.now()).toBe(0);
238-
advance(1000);
239-
expect(clock.now()).toBe(1);
246+
advancePolled(clock, advance, 1000);
247+
expect(clock.now()).toBeCloseTo(1, 5);
240248
});
241249
});
242250

@@ -288,7 +296,7 @@ describe("TransportClock", () => {
288296
expect(clock.now()).toBe(5);
289297
clock.detachAudioSource();
290298
expect(clock.now()).toBeCloseTo(5, 1);
291-
advance(1000);
299+
advancePolled(clock, advance, 1000);
292300
expect(clock.now()).toBeCloseTo(6, 1);
293301
expect(clock.getSource()).toBe("monotonic");
294302
});

‎packages/core/src/runtime/clock.ts‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,19 @@ export type AudioClockSource =
1616
currentTimeSeconds: number;
1717
};
1818

19+
/** GSAP's own `lagSmoothing` default — see the PR body for why this clock needs its own copy. */
20+
const STALL_THRESHOLD_MS = 500;
21+
const STALL_ADJUSTED_LAG_MS = 33;
22+
1923
export class TransportClock {
2024
private _baseTime = 0;
2125
private _playStartMs: number | null = null;
2226
private _rate = 1;
2327
private _duration = Infinity;
2428
private _nowMs: () => number;
2529
private _audioSource: AudioClockSource | null = null;
30+
/** Wall-clock time of the last `now()` read while playing; null while paused. */
31+
private _lastReadMs: number | null = null;
2632

2733
constructor(opts?: {
2834
initialTime?: number;
@@ -39,8 +45,10 @@ export class TransportClock {
3945
now(): number {
4046
if (this._playStartMs === null) return this._baseTime;
4147

42-
// Audio-master: when an audio source is attached, derive time
43-
// from it. Drift is impossible because audio IS the clock.
48+
// Audio-master: drift is impossible because audio IS the clock. Clearing
49+
// `_lastReadMs` (not stamping it) means the next monotonic read starts
50+
// fresh from `_playStartMs` instead of a timestamp audio just made
51+
// meaningless — see the PR body.
4452
if (this._audioSource) {
4553
let audioTime: number | null = null;
4654
if ("currentTimeSeconds" in this._audioSource) {
@@ -55,6 +63,7 @@ export class TransportClock {
5563
}
5664
}
5765
if (audioTime !== null) {
66+
this._lastReadMs = null;
5867
if (Number.isFinite(this._duration) && audioTime >= this._duration) {
5968
return this._duration;
6069
}
@@ -63,6 +72,7 @@ export class TransportClock {
6372
}
6473

6574
// Monotonic fallback
75+
this._applyStallCorrection();
6676
const elapsed = (this._nowMs() - this._playStartMs) / 1000;
6777
const t = this._baseTime + elapsed * this._rate;
6878
if (Number.isFinite(this._duration) && t >= this._duration) {
@@ -71,10 +81,28 @@ export class TransportClock {
7181
return Math.max(0, t);
7282
}
7383

84+
/** Folds a >500ms gap since the last read into `_playStartMs` so it's never reported as played time. */
85+
private _applyStallCorrection(): void {
86+
if (this._playStartMs === null) return;
87+
const nowMs = this._nowMs();
88+
if (this._lastReadMs !== null) {
89+
const gapMs = nowMs - this._lastReadMs;
90+
if (gapMs > STALL_THRESHOLD_MS) {
91+
this._playStartMs += gapMs - STALL_ADJUSTED_LAG_MS;
92+
}
93+
}
94+
this._lastReadMs = nowMs;
95+
}
96+
7497
play(): boolean {
7598
if (this._playStartMs !== null) return false;
7699
if (Number.isFinite(this._duration) && this._baseTime >= this._duration) return false;
77100
this._playStartMs = this._nowMs();
101+
// Not a stall: the gap since the clock was last read (possibly a long
102+
// paused idle) says nothing about lost playback time, since none was
103+
// playing. `_applyStallCorrection` treats null as "nothing to compare
104+
// against yet" and starts the window fresh from the next read.
105+
this._lastReadMs = null;
78106
return true;
79107
}
80108

@@ -92,6 +120,9 @@ export class TransportClock {
92120
this._baseTime = clamped;
93121
if (this._playStartMs !== null) {
94122
this._playStartMs = this._nowMs();
123+
// Same reasoning as `play()`: the seek itself, not any elapsed gap
124+
// since the last read, is why the reported time is moving now.
125+
this._lastReadMs = null;
95126
}
96127
}
97128

@@ -104,6 +135,7 @@ export class TransportClock {
104135
if (this._playStartMs !== null) {
105136
this._baseTime = this.now();
106137
this._playStartMs = this._nowMs();
138+
this._lastReadMs = null;
107139
}
108140
this._rate = safe;
109141
}
@@ -131,6 +163,9 @@ export class TransportClock {
131163
if (this._audioSource && this._playStartMs !== null) {
132164
this._baseTime = this.now();
133165
this._playStartMs = this._nowMs();
166+
// Falling back to monotonic timing fresh, same reasoning as `play()`:
167+
// any gap while audio was the time source is not a monotonic stall.
168+
this._lastReadMs = null;
134169
}
135170
this._audioSource = null;
136171
}

‎packages/core/src/runtime/init.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2532,7 +2532,8 @@ describe("initSandboxRuntimeModular", () => {
25322532
expect(player).toBeDefined();
25332533

25342534
player?.play();
2535-
raf.step(1_000);
2535+
// Sub-threshold steps: the stall policy treats one big unread jump as a stall.
2536+
for (let steps = 0; steps < 4; steps++) raf.step(250);
25362537

25372538
expect(player?.isPlaying()).toBe(true);
25382539
expect(player?.getTime()).toBeCloseTo(1, 1);

0 commit comments

Comments
 (0)