Skip to content

Commit 3f6907e

Browse files
fix: keep Studio frame stepping advancing (#573)
## Problem Closes #568. Studio preview-focused frame stepping could stop advancing after a couple of ArrowLeft/ArrowRight presses. The same integer-frame stepping path also affected the K-held J/L one-frame shuttle controls. ## What this fixes - Adds a shared `stepFrameTime` helper that advances by integer frame index instead of adding fractional seconds. - Uses that helper for preview-surface keyboard shortcuts and the focused seek slider. - Adds regression coverage for truncated runtime times like `0.0333333`, which previously stepped back onto the same frame. ## Root cause The runtime seek path quantizes requested times with `Math.floor(time * fps)`. Studio was deriving the next frame from the runtime's current seconds value, which can be a truncated decimal such as `0.0333333`. Adding `1 / 30` to that value can produce `1.999998...` frames, so floor-quantization lands back on the previous frame and repeated shortcuts appear to stop responding. ## Verification ### Local checks - `bun run --filter @hyperframes/core build:hyperframes-runtime` - `bun run --filter @hyperframes/studio test -- src/player/lib/time.test.ts src/player/hooks/useTimelinePlayer.test.ts src/player/components/PlayerControls.test.ts` - `bunx oxfmt --check packages/studio/src/player/lib/time.ts packages/studio/src/player/lib/time.test.ts packages/studio/src/player/hooks/useTimelinePlayer.ts packages/studio/src/player/components/PlayerControls.tsx` - `bunx oxlint packages/studio/src/player/lib/time.ts packages/studio/src/player/lib/time.test.ts packages/studio/src/player/hooks/useTimelinePlayer.ts packages/studio/src/player/components/PlayerControls.tsx` - `bun run --filter @hyperframes/studio typecheck` - `bun run --filter @hyperframes/studio build` - `git diff --check` - Lefthook pre-commit: lint, format, typecheck - Lefthook commit-msg: commitlint ### Browser verification - Created `/tmp/hf-studio-frame-step-repro` with a 10s GSAP animation. - Started Studio preview at `http://localhost:5191/#project/hf-studio-frame-step-repro`. - Used `agent-browser` to reproduce the original stuck behavior before the fix: repeated preview-focused `ArrowRight` keydowns were handled but runtime time stayed at `0.0333333`. - Used `agent-browser` after the fix to verify preview-focused `ArrowRight` advances 10 frames to `0.3333333`. - Used `agent-browser` to verify K-held L steps forward 5 frames to `0.1666667` and K-held J steps backward from 5 frames to `0`. - Used actual Safari 18.6 with System Events key presses to verify 10 and then 20 preview-focused ArrowRight presses continue advancing visually. ## Notes - Safari WebDriver was unavailable because Safari's "Allow remote automation" setting is disabled on this machine, so the Safari check used real Safari GUI key events instead. - Local proof artifacts are intentionally not committed: - `qa-artifacts/studio-frame-step-issue-568/chrome-after-10-arrow-right.png` - `qa-artifacts/studio-frame-step-issue-568/chrome-frame-step-flow.webm` - `qa-artifacts/studio-frame-step-issue-568/safari-after-10-arrow-right.png` - `qa-artifacts/studio-frame-step-issue-568/safari-after-20-arrow-right.png`
1 parent 22f0e6a commit 3f6907e

4 files changed

Lines changed: 22 additions & 6 deletions

File tree

‎packages/studio/src/player/components/PlayerControls.tsx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { useRef, useState, useCallback, useEffect, memo } from "react";
22
import { useMountEffect } from "../../hooks/useMountEffect";
3-
import { formatFrameTime, frameToSeconds, formatTime } from "../lib/time";
3+
import { formatFrameTime, frameToSeconds, stepFrameTime, formatTime } from "../lib/time";
44
import { usePlayerStore, liveTime } from "../store/playerStore";
55

66
const SPEED_OPTIONS = [0.25, 0.5, 1, 1.5, 2] as const;
@@ -208,10 +208,10 @@ export const PlayerControls = memo(function PlayerControls({
208208
const step = e.shiftKey ? 10 : 1;
209209
if (e.key === "ArrowLeft") {
210210
e.preventDefault();
211-
onSeek(Math.max(0, currentTimeRef.current - frameToSeconds(step)));
211+
onSeek(stepFrameTime(currentTimeRef.current, -step));
212212
} else if (e.key === "ArrowRight") {
213213
e.preventDefault();
214-
onSeek(Math.min(duration, currentTimeRef.current + frameToSeconds(step)));
214+
onSeek(Math.min(duration, stepFrameTime(currentTimeRef.current, step)));
215215
}
216216
},
217217
[timelineReady, duration, onSeek],

‎packages/studio/src/player/hooks/useTimelinePlayer.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { useRef, useCallback } from "react";
22
import { usePlayerStore, liveTime, type TimelineElement } from "../store/playerStore";
33
import { useMountEffect } from "../../hooks/useMountEffect";
4-
import { frameToSeconds, STUDIO_PREVIEW_FPS } from "../lib/time";
4+
import { stepFrameTime, STUDIO_PREVIEW_FPS } from "../lib/time";
55
import { useCaptionStore } from "../../captions/store";
66

77
interface PlaybackAdapter {
@@ -697,7 +697,7 @@ export function useTimelinePlayer() {
697697
(deltaFrames: number) => {
698698
const adapter = getAdapter();
699699
const currentTime = adapter?.getTime() ?? usePlayerStore.getState().currentTime;
700-
seek(currentTime + frameToSeconds(deltaFrames, STUDIO_PREVIEW_FPS));
700+
seek(stepFrameTime(currentTime, deltaFrames, STUDIO_PREVIEW_FPS));
701701
},
702702
[getAdapter, seek],
703703
);

‎packages/studio/src/player/lib/time.test.ts‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { describe, it, expect } from "vitest";
2-
import { formatFrameTime, frameToSeconds, secondsToFrame, formatTime } from "./time";
2+
import { formatFrameTime, frameToSeconds, secondsToFrame, stepFrameTime, formatTime } from "./time";
33

44
describe("formatTime", () => {
55
it("formats zero seconds", () => {
@@ -72,4 +72,14 @@ describe("frame helpers", () => {
7272
it("formats current and total frame display", () => {
7373
expect(formatFrameTime(1, 5)).toBe("30f / 150f");
7474
});
75+
76+
it("steps from a truncated runtime time by integer frame index", () => {
77+
expect(stepFrameTime(0.0333333, 1)).toBe(2 / 30);
78+
expect(stepFrameTime(0.0666666, 1)).toBe(3 / 30);
79+
expect(stepFrameTime(0.0666666, -1)).toBe(1 / 30);
80+
});
81+
82+
it("clamps frame stepping at zero", () => {
83+
expect(stepFrameTime(0, -1)).toBe(0);
84+
});
7585
});

‎packages/studio/src/player/lib/time.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,12 @@ export function frameToSeconds(frame: number, fps = STUDIO_PREVIEW_FPS): number
1919
return frame / fps;
2020
}
2121

22+
export function stepFrameTime(time: number, deltaFrames: number, fps = STUDIO_PREVIEW_FPS): number {
23+
const currentFrame = secondsToFrame(time, fps);
24+
const nextFrame = Math.max(0, currentFrame + deltaFrames);
25+
return frameToSeconds(nextFrame, fps);
26+
}
27+
2228
export function formatFrameTime(time: number, duration: number, fps = STUDIO_PREVIEW_FPS): string {
2329
const currentFrame = secondsToFrame(time, fps);
2430
const totalFrames = secondsToFrame(duration, fps);

0 commit comments

Comments
 (0)