Skip to content

Write HTML. Render video. Built for agents.

fix(studio): trimming keeps the playhead still; clips snap to the ruler grid (#4986)

Miguel Ángel7859c0f0037a
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4a979d6b22..37cdea751c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -848,6 +848,8 @@ jobs:
packages/studio/data/projects/studio-open
cp -R packages/studio/tests/e2e/fixtures/fade-handles \
packages/studio/data/projects/fade-handles
+ cp -R packages/studio/tests/e2e/fixtures/timeline-trim-snap \
+ packages/studio/data/projects/timeline-trim-snap
cp -R packages/studio/tests/e2e/fixtures/inline-text-caret \
packages/studio/data/projects/inline-text-caret
cp -R packages/studio/tests/e2e/fixtures/undo-socket-pool \
@@ -960,7 +962,7 @@ jobs:
node packages/studio/tests/e2e/perf-ratchet.mjs check \
packages/studio/tests/e2e/perf-ceilings.json studio-open /tmp/studio-open-counts.json \
/tmp/base-perf-ceilings.json
- - name: Check fade handles, render selects and thumbnail connection release
+ - name: Check fade handles, render selects, thumbnail connection release and trim snapping
if: success() || failure()
run: |
set -euo pipefail
@@ -983,6 +985,8 @@ jobs:
node packages/studio/tests/e2e/render-selects.mjs || rc=1
STUDIO_URL="http://localhost:5316/" \
node packages/studio/tests/e2e/thumbnail-save.mjs || rc=1
+ STUDIO_URL="http://localhost:5316/#project/timeline-trim-snap" \
+ node packages/studio/tests/e2e/timeline-trim-snap.mjs || rc=1
exit "$rc"
- name: Measure the caret of a text edited in place
if: success() || failure()
diff --git a/packages/studio/src/player/components/TimelineClipFades.tsx b/packages/studio/src/player/components/TimelineClipFades.tsx
index f82596e6fd..2d35771eec 100644
--- a/packages/studio/src/player/components/TimelineClipFades.tsx
+++ b/packages/studio/src/player/components/TimelineClipFades.tsx
@@ -48,6 +48,7 @@ const SNAP_LABEL: Record<TimelineSnapType, string> = {
playhead: "playhead",
"clip-edge": "clip edge",
beat: "beat",
+ grid: "grid line",
};
export type ClipFadeShape = AudioFades & { duration: number };
diff --git a/packages/studio/src/player/components/timelineClipDragPreview.test.ts b/packages/studio/src/player/components/timelineClipDragPreview.test.ts
index b149eba3dc..d68f2fc672 100644
--- a/packages/studio/src/player/components/timelineClipDragPreview.test.ts
+++ b/packages/studio/src/player/components/timelineClipDragPreview.test.ts
@@ -3,6 +3,7 @@ import type { TimelineElement } from "../store/playerStore";
import {
computeDragPreview,
computeResizePreview,
+ guideIfSaved,
getTimelineDragOverlayPosition,
type DragPreviewContext,
} from "./timelineClipDragPreview";
@@ -293,6 +294,52 @@ describe("computeDragPreview — a clip landing on an empty main track keeps its
});
});
+describe("guideIfSaved — a guide only where the clip saves", () => {
+ const grid = { time: 3.25, type: "grid" as const };
+
+ it("drops the guide when start and duration round apart from the target", () => {
+ // 1440 px/s: 1.125s + 2.125s saves as 1.13s + 2.13s, 14px past the 3.25s guide.
+ const el = clip("a", 0, 1.125, 2, 0, "div");
+ expect(guideIfSaved(el, { start: 1.125, duration: 2.125 }, grid, 1440)).toBeNull();
+ });
+
+ it("drops the guide when a nested clip's local start rounds off it", () => {
+ const el = { ...clip("a", 0, 2, 1, 0, "div"), parentCompositionStart: 1 / 30 };
+ const target = { time: 2.1, type: "playhead" as const };
+ expect(guideIfSaved(el, { start: 2.1, duration: 1 }, target, 1440)).toBeNull();
+ });
+
+ it("keeps the guide when the saved edge is on it", () => {
+ const el = clip("a", 0, 1, 2, 0, "div");
+ expect(guideIfSaved(el, { start: 1, duration: 2.25 }, grid, 1440)).toBe(grid);
+ });
+
+ it("judges a move by the duration it keeps, not a rounded one", () => {
+ // A 31/30 s clip moved so its end meets 3.25s saves its start at 2.22s and ends 4.8px past.
+ const el = clip("a", 0, 1, 31 / 30, 0, "div");
+ const edge = { time: 3.25, type: "clip-edge" as const };
+ expect(guideIfSaved(el, { start: 2.217 }, edge, 1440)).toBeNull();
+ });
+
+ it("draws no guide for a move whose saved start misses the target", () => {
+ const nested = { ...moodboard, parentCompositionStart: 1 / 30 };
+ const { drag } = horizontalDrag(nested, 0.5, 0);
+ const context = {
+ ...ctx(),
+ pps: 1440,
+ buildSnapTargets: () => [{ time: 21, type: "playhead" as const }],
+ };
+ const next = computeDragPreview(
+ drag,
+ drag.originClientX + 2 * 1440,
+ drag.originClientY,
+ context,
+ );
+ expect(next.previewStart).toBe(21);
+ expect(next.snapTime).toBeNull();
+ });
+});
+
describe("computeResizePreview — composition source continuity", () => {
it("seeds a legacy composition offset and advances it at playback rate", () => {
const element = {
@@ -320,6 +367,27 @@ describe("computeResizePreview — composition source continuity", () => {
});
});
+ it("draws no guide when the trimmed start cannot save onto the target", () => {
+ // 1440 px/s: a playhead on frame 31 (1.033s) saves a start of 1.03s, 4px off the guide.
+ const result = computeResizePreview(
+ {
+ element: clip("a", 0, 1, 2, 0, "div"),
+ edge: "start",
+ originClientX: 0,
+ previewStart: 1,
+ previewDuration: 2,
+ started: true,
+ },
+ 48,
+ {
+ scroll: fakeScroll(),
+ pps: 1440,
+ buildSnapTargets: () => [{ time: 1.033, type: "playhead" }],
+ },
+ );
+ expect(result).toMatchObject({ previewStart: 1.03, snapTime: null, snapType: null });
+ });
+
it("does not let a tail snap shrink a clip below the drag's minimum duration", () => {
const result = computeResizePreview(
{
diff --git a/packages/studio/src/player/components/timelineClipDragPreview.ts b/packages/studio/src/player/components/timelineClipDragPreview.ts
index d6e6693e8d..0842c98eea 100644
--- a/packages/studio/src/player/components/timelineClipDragPreview.ts
+++ b/packages/studio/src/player/components/timelineClipDragPreview.ts
@@ -5,7 +5,7 @@ import {
resolveTimelineMinDuration,
} from "./timelineGroupEditing";
import type { TimelineElement } from "../store/playerStore";
-import { clampToHostStart } from "../store/timelineElement";
+import { clampToHostStart, savedClipEdges } from "../store/timelineElement";
import {
CLIP_Y,
TRACK_H,
@@ -34,7 +34,6 @@ import { heldAudioShiftRange, heldPartnerVideoBounds } from "./audioClipLink";
type BuildSnapTargets = (
excludeElementKey: string | null,
includeBeats: boolean,
- includePlayhead?: boolean,
) => TimelineSnapTarget[];
export interface DragPreviewContext {
@@ -56,6 +55,8 @@ export interface DragPreviewContext {
* on demand from `elements`, so the result is identical either way.
*/
audioTracks?: ReadonlySet<number>;
+ /** Seconds between the ruler's lines; 0 or absent when snapping is off. */
+ gridStep?: number;
}
export function createKeyboardClipDrag(
@@ -248,6 +249,7 @@ export function computeDragPreview(
// Relaxed clamp: allow the snapped start past the content, up to the
// rendered extent (see dragMaxStart) — the composition grows on commit.
dragMaxStart + drag.element.duration,
+ ctx.gridStep,
);
// A group moves rigidly: the grabbed clip stops where any mover would cross its host's start.
const group = resolveGroupDrag(drag, ctx);
@@ -266,6 +268,11 @@ export function computeDragPreview(
return { ...drag, started: true };
}
const { track: previewTrack, insertRow } = placement;
+ const target =
+ placement.start === snap.start && snap.snapTime !== null && snap.snapType !== null
+ ? { time: snap.snapTime, type: snap.snapType }
+ : null;
+ const guide = guideIfSaved(drag.element, { start: snap.start }, target, pps);
return {
...drag,
started: true,
@@ -277,11 +284,24 @@ export function computeDragPreview(
// tell a deliberate vertical lane change from a horizontal drag.
desiredTrack: nextMove.track,
insertRow,
- snapTime: placement.start === snap.start ? snap.snapTime : null,
- snapType: placement.start === snap.start ? snap.snapType : null,
+ snapTime: guide?.time ?? null,
+ snapType: guide?.type ?? null,
};
}
+/** A snap's guide, kept only when the clip's edge as its file will save it is within a pixel of it. */
+export function guideIfSaved(
+ element: TimelineElement,
+ clip: { start: number; duration?: number },
+ target: TimelineSnapTarget | null,
+ pps: number,
+): TimelineSnapTarget | null {
+ if (!target) return null;
+ const saved = savedClipEdges(element, clip.start, clip.duration);
+ const off = Math.min(Math.abs(saved.start - target.time), Math.abs(saved.end - target.time));
+ return off * pps < 1 ? target : null;
+}
+
/** One frame: the last visible frame of a clip sits just before its end time. */
const TRIM_END_FRAME_LEAD_S = 1 / STUDIO_PREVIEW_FPS;
@@ -296,6 +316,8 @@ export interface ResizePreviewContext {
buildSnapTargets: BuildSnapTargets;
elements?: readonly TimelineElement[];
gestureKeys?: ReadonlySet<string>;
+ /** Seconds between the ruler's lines; 0 or absent when snapping is off. */
+ gridStep?: number;
}
export interface ResizePreviewResult {
@@ -362,21 +384,19 @@ export function computeResizePreview(
effectiveClientX,
);
- // Snap to beats and clip edges, never the playhead (the dragged edge drives
- // its own preview seek, so that would be circular). Stay inside the same
- // limits resolveTimelineResize enforces. The music track defines the
- // beats, so it must not snap to them, but still snaps to clip edges.
+ // Snap within the same limits resolveTimelineResize enforces. The music
+ // track defines the beats, so it must not snap to them.
const trimTargets = buildSnapTargets(
resize.element.key ?? resize.element.id,
!isMusicTrack(resize.element),
- false,
);
+ const gridStep = ctx.gridStep ?? 0;
let snap: TimelineSnapTarget | null = null;
- if (trimTargets.length > 0) {
+ if (trimTargets.length > 0 || gridStep > 0) {
const snapSecs = TIMELINE_SNAP_PX / Math.max(pps, 1);
if (resize.edge === "end") {
const edgeTime = nextResize.start + nextResize.duration;
- const { time: snapped, target } = snapTimelineTime(edgeTime, trimTargets, snapSecs);
+ const { time: snapped, target } = snapTimelineTime(edgeTime, trimTargets, snapSecs, gridStep);
// Stay within [start+minDuration, maxEnd] so the snap can't create a
// degenerate clip or run past the source/composition limit.
const snappedDuration = Math.round((snapped - nextResize.start) * 1000) / 1000;
@@ -387,16 +407,21 @@ export function computeResizePreview(
) {
// An edge already on the target still owns the guide; only move it when off.
if (snapped !== edgeTime) nextResize = { ...nextResize, duration: snappedDuration };
- snap = target;
+ snap = guideIfSaved(resize.element, nextResize, target, pps);
}
} else {
- const { time: snapped, target } = snapTimelineTime(nextResize.start, trimTargets, snapSecs);
+ const { time: snapped, target } = snapTimelineTime(
+ nextResize.start,
+ trimTargets,
+ snapSecs,
+ gridStep,
+ );
const clip = { ...nextResize, playbackRate: resize.element.playbackRate };
const delta = snapped - nextResize.start;
const bounds = clipStartTrimDeltaBounds(clip, minStart, resolveTimelineMinDuration());
if (target && delta >= bounds.minDelta - 1e-6 && delta <= bounds.maxDelta + 1e-6) {
if (snapped !== nextResize.start) nextResize = applyClipStartTrimDelta(clip, delta);
- snap = target;
+ snap = guideIfSaved(resize.element, nextResize, target, pps);
}
}
}
diff --git a/packages/studio/src/player/components/timelineLayout.test.ts b/packages/studio/src/player/components/timelineLayout.test.ts
index 04c54ccd03..14f4d525e2 100644
--- a/packages/studio/src/player/components/timelineLayout.test.ts
+++ b/packages/studio/src/player/components/timelineLayout.test.ts
@@ -18,7 +18,11 @@ import {
resolveTimelineAssetDrop,
getTimelineBeatEntries,
} from "./timelineLayout";
-import { generateTicks, getTimelineMajorTickInterval } from "./timelineRulerGeometry";
+import {
+ generateTicks,
+ getTimelineGridStep,
+ getTimelineMajorTickInterval,
+} from "./timelineRulerGeometry";
import { resolveInsertRow } from "./timelineCollision";
import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
@@ -42,6 +46,25 @@ describe("horizontal timeline window", () => {
expect(ticks.major.length + ticks.minor.length).toBeLessThan(100);
});
+ it("spaces the snap grid exactly like the ruler's drawn lines at each zoom", () => {
+ for (const [pps, fps] of [
+ [100, undefined],
+ [12, undefined],
+ [900, undefined],
+ [100, 30],
+ [3, 30],
+ ] as const) {
+ const { major, minor } = generateTicks(60, pps, fps);
+ const lines = [...major, ...minor].sort((a, b) => a - b);
+ expect(getTimelineGridStep(60, pps, fps)).toBeCloseTo(lines[1]! - lines[0]!, 6);
+ }
+ });
+
+ it("has no snap grid where the ruler draws no lines", () => {
+ expect(generateTicks(20_000, 100)).toEqual({ major: [], minor: [] });
+ expect(getTimelineGridStep(20_000, 100)).toBe(0);
+ });
+
it("slices beat records with original strength indexes and unions a pinned beat", () => {
expect(
getTimelineBeatEntries(
diff --git a/packages/studio/src/player/components/timelineRulerGeometry.ts b/packages/studio/src/player/components/timelineRulerGeometry.ts
index b70cc87109..0e819a8e0b 100644
--- a/packages/studio/src/player/components/timelineRulerGeometry.ts
+++ b/packages/studio/src/player/components/timelineRulerGeometry.ts
@@ -1,4 +1,5 @@
-import { formatTime } from "../lib/time";
+import { formatTime, STUDIO_PREVIEW_FPS } from "../lib/time";
+import type { TimelineTimeDisplayMode } from "../../utils/studioUiPreferences";
import type { TimelineTimeRange } from "../lib/timelineClipIndex";
// fallow-ignore-next-line complexity
@@ -87,6 +88,27 @@ function appendMinorTicks(
}
}
+function tickSpacing(duration: number, pixelsPerSecond?: number, frameRate?: number) {
+ const majorInterval = getTimelineMajorTickInterval(duration, pixelsPerSecond, frameRate);
+ const subdivisions = getMinorSubdivisions(majorInterval, pixelsPerSecond, frameRate);
+ return { majorInterval, subdivisions };
+}
+
+export function rulerFrameRate(mode: TimelineTimeDisplayMode): number | undefined {
+ return mode === "frame" ? STUDIO_PREVIEW_FPS : undefined;
+}
+
+/** Seconds between neighbouring ruler lines (minor ticks when drawn, else major): the snap grid. */
+export function getTimelineGridStep(
+ duration: number,
+ pixelsPerSecond?: number,
+ frameRate?: number,
+): number {
+ if (!isSupportedTickDuration(duration)) return 0;
+ const { majorInterval, subdivisions } = tickSpacing(duration, pixelsPerSecond, frameRate);
+ return subdivisions > 0 ? majorInterval / subdivisions : majorInterval;
+}
+
export function generateTicks(
duration: number,
pixelsPerSecond?: number,
@@ -94,8 +116,7 @@ export function generateTicks(
range?: TimelineTimeRange,
): { major: number[]; minor: number[] } {
if (!isSupportedTickDuration(duration)) return { major: [], minor: [] };
- const majorInterval = getTimelineMajorTickInterval(duration, pixelsPerSecond, frameRate);
- const subdivisions = getMinorSubdivisions(majorInterval, pixelsPerSecond, frameRate);
+ const { majorInterval, subdivisions } = tickSpacing(duration, pixelsPerSecond, frameRate);
const minorInterval = subdivisions > 0 ? majorInterval / subdivisions : 0;
const major: number[] = [];
const minor: number[] = [];
diff --git a/packages/studio/src/player/components/timelineSnapping.test.ts b/packages/studio/src/player/components/timelineSnapping.test.ts
index 1d881ff1fb..45c74f58f6 100644
--- a/packages/studio/src/player/components/timelineSnapping.test.ts
+++ b/packages/studio/src/player/components/timelineSnapping.test.ts
@@ -27,18 +27,6 @@ describe("collectTimelineSnapTargets", () => {
expect(targets).toContainEqual({ time: 0.5, type: "beat" });
});
- it("omits the playhead when includePlayhead is false, for a trim", () => {
- const targets = collectTimelineSnapTargets({
- elements,
- playheadTime: 7.25,
- beatTimes: [0.5],
- includePlayhead: false,
- });
- expect(targets.some((t) => t.type === "playhead")).toBe(false);
- expect(targets).toContainEqual({ time: 2, type: "clip-edge" });
- expect(targets).toContainEqual({ time: 0.5, type: "beat" });
- });
-
it("excludes the dragged element's own edges", () => {
const targets = collectTimelineSnapTargets({
elements,
@@ -90,6 +78,35 @@ describe("snapTimelineTime", () => {
it("returns input unchanged when nothing is within threshold", () => {
expect(snapTimelineTime(6, targets, 0.1)).toEqual({ time: 6, target: null });
});
+
+ it("snaps to the nearest ruler line when no target is in range", () => {
+ expect(snapTimelineTime(6.27, targets, 0.08, 0.25)).toEqual({
+ time: 6.25,
+ target: { time: 6.25, type: "grid" },
+ });
+ expect(snapTimelineTime(6.37, targets, 0.08, 0.25)).toEqual({ time: 6.37, target: null });
+ });
+
+ it("prefers a target in range over a nearer ruler line", () => {
+ expect(snapTimelineTime(5.24, targets, 0.08, 0.25).target).toEqual({
+ time: 5.3,
+ type: "playhead",
+ });
+ });
+
+ it("snaps a line at its saved centisecond, and not at all when that is a pixel or more off", () => {
+ // 187.5 px/s: 4.625s saves as 4.63s, under a pixel away, so the guide sits where the clip lands.
+ expect(snapTimelineTime(4.627, [], 8 / 187.5, 0.125).target).toEqual({
+ time: 4.63,
+ type: "grid",
+ });
+ // 1440 px/s: 1.025s would save 7px off its line, so the line does not snap.
+ expect(snapTimelineTime(1.026, [], 8 / 1440, 0.025)).toEqual({ time: 1.026, target: null });
+ });
+
+ it("lands on whole frames for a frame-spaced grid", () => {
+ expect(snapTimelineTime(1.01, [], 0.08, 1 / 30).time).toBe(1);
+ });
});
describe("snapMoveToTargets", () => {
@@ -120,6 +137,20 @@ describe("snapMoveToTargets", () => {
expect(snapMoveToTargets(5.5, 2, targets, 1000, 60).snapTime).toBeNull();
});
+ it("snaps a clip edge to the ruler grid when no target is near", () => {
+ expect(snapMoveToTargets(1.02, 2, [], 100, 60, 0.25)).toEqual({
+ start: 1,
+ snapTime: 1,
+ snapType: "grid",
+ });
+ });
+
+ it("prefers the edge on a real target over the other edge nearer a ruler line", () => {
+ // start 2.99 is 1px from the 3s line; the end 4.94 is 6px from the playhead at 5
+ const r = snapMoveToTargets(2.99, 1.95, targets, 100, 60, 0.25);
+ expect(r).toEqual({ start: 3.05, snapTime: 5, snapType: "playhead" });
+ });
+
it("TIMELINE_SNAP_PX matches the historical beat-snap threshold", () => {
expect(TIMELINE_SNAP_PX).toBe(8);
});
diff --git a/packages/studio/src/player/components/timelineSnapping.ts b/packages/studio/src/player/components/timelineSnapping.ts
index 8f11ab67e1..702c52f1a4 100644
--- a/packages/studio/src/player/components/timelineSnapping.ts
+++ b/packages/studio/src/player/components/timelineSnapping.ts
@@ -1,6 +1,7 @@
import type { TimelineElement } from "../store/playerStore";
+import { roundToCenti } from "../../utils/rounding";
-export type TimelineSnapType = "beat" | "playhead" | "clip-edge";
+export type TimelineSnapType = "beat" | "playhead" | "clip-edge" | "grid";
export interface TimelineSnapTarget {
time: number;
@@ -24,6 +25,7 @@ const TYPE_PRIORITY: Record<TimelineSnapType, number> = {
playhead: 0,
"clip-edge": 1,
beat: 2,
+ grid: 3,
};
export function collectTimelineSnapTargets(input: {
@@ -31,8 +33,6 @@ export function collectTimelineSnapTargets(input: {
playheadTime: number | null;
beatTimes: readonly number[];
excludeElementKey?: string | null;
- /** A trim excludes the playhead: the dragged edge drives it, so snapping to it is circular. */
- includePlayhead?: boolean;
}): TimelineSnapTarget[] {
const byTime = new Map<number, TimelineSnapTarget>();
const add = (time: number, type: TimelineSnapType) => {
@@ -50,16 +50,30 @@ export function collectTimelineSnapTargets(input: {
add(el.start, "clip-edge");
add(el.start + el.duration, "clip-edge");
}
- if (input.playheadTime != null && input.includePlayhead !== false)
- add(input.playheadTime, "playhead");
+ if (input.playheadTime != null) add(input.playheadTime, "playhead");
return Array.from(byTime.values()).sort((a, b) => a.time - b.time);
}
+/** Nearest ruler line in range, at its saved centisecond, and only within a pixel of it. */
+function nearestGridLine(
+ time: number,
+ gridStep: number,
+ thresholdSecs: number,
+): TimelineSnapTarget | null {
+ if (!(gridStep > 0)) return null;
+ const line = Math.round(time / gridStep) * gridStep;
+ const saved = roundToCenti(line);
+ const pixelsPerSecond = TIMELINE_SNAP_PX / thresholdSecs;
+ if (Math.abs(saved - line) * pixelsPerSecond >= 1) return null;
+ return Math.abs(saved - time) < thresholdSecs ? { time: saved, type: "grid" } : null;
+}
+
export function snapTimelineTime(
time: number,
targets: readonly TimelineSnapTarget[],
thresholdSecs: number,
+ gridStep = 0,
): { time: number; target: TimelineSnapTarget | null } {
let best: TimelineSnapTarget | null = null;
let bestDist = thresholdSecs;
@@ -73,6 +87,7 @@ export function snapTimelineTime(
best = target;
}
}
+ best ??= nearestGridLine(time, gridStep, thresholdSecs);
return best ? { time: best.time, target: best } : { time, target: null };
}
@@ -88,23 +103,26 @@ export function snapMoveToTargets(
targets: readonly TimelineSnapTarget[],
pixelsPerSecond: number,
timelineDuration: number,
+ gridStep = 0,
): { start: number; snapTime: number | null; snapType: TimelineSnapType | null } {
- if (targets.length === 0) return { start, snapTime: null, snapType: null };
+ if (targets.length === 0 && !(gridStep > 0)) return { start, snapTime: null, snapType: null };
const thresholdSecs = TIMELINE_SNAP_PX / Math.max(pixelsPerSecond, 1);
- const startSnap = snapTimelineTime(start, targets, thresholdSecs);
- const endSnap = snapTimelineTime(start + duration, targets, thresholdSecs);
- const startMoved = startSnap.target !== null;
- const endMoved = endSnap.target !== null;
+ const startSnap = snapTimelineTime(start, targets, thresholdSecs, gridStep);
+ const endSnap = snapTimelineTime(start + duration, targets, thresholdSecs, gridStep);
+ // The nearer edge wins, but a grid line only when neither edge has a real target.
+ const rank = (snap: typeof startSnap, edgeTime: number) =>
+ snap.target === null
+ ? Infinity
+ : Math.abs(snap.time - edgeTime) + (snap.target.type === "grid" ? thresholdSecs : 0);
+ const startRank = rank(startSnap, start);
+ const endRank = rank(endSnap, start + duration);
let candidate = start;
let target: TimelineSnapTarget | null = null;
- if (
- startMoved &&
- (!endMoved || Math.abs(startSnap.time - start) <= Math.abs(endSnap.time - (start + duration)))
- ) {
+ if (startRank !== Infinity && startRank <= endRank) {
candidate = startSnap.time;
target = startSnap.target;
- } else if (endMoved) {
+ } else if (endRank !== Infinity) {
candidate = endSnap.time - duration;
target = endSnap.target;
}
diff --git a/packages/studio/src/player/components/useTimelineClipDrag.resize.test.tsx b/packages/studio/src/player/components/useTimelineClipDrag.resize.test.tsx
index 2aa3718dd1..882302903a 100644
--- a/packages/studio/src/player/components/useTimelineClipDrag.resize.test.tsx
+++ b/packages/studio/src/player/components/useTimelineClipDrag.resize.test.tsx
@@ -4,6 +4,7 @@ import React, { act } from "react";
import { afterEach, describe, expect, it, vi } from "vitest";
import type { TimelineElement } from "../store/playerStore";
import { usePlayerStore } from "../store/playerStore";
+import { usePreviewFrameStore } from "../store/previewFrameStore";
import type { BlockedClipState, DraggedClipState, ResizingClipState } from "./useTimelineClipDrag";
import { useTimelineClipDrag } from "./useTimelineClipDrag";
import { mountReactHarness } from "../../hooks/domSelectionTestHarness";
@@ -26,6 +27,7 @@ function el(id: string, over: Partial<TimelineElement> = {}): TimelineElement {
afterEach(() => {
document.body.innerHTML = "";
usePlayerStore.getState().reset();
+ usePreviewFrameStore.setState({ time: null });
});
function renderResizeHarness(
@@ -34,7 +36,6 @@ function renderResizeHarness(
options: {
wireGroupResize?: boolean;
snap?: boolean;
- onSeek?: (time: number, seekOptions?: { keepPlaying?: boolean }) => void;
} = {},
) {
usePlayerStore.getState().setElements(elements);
@@ -65,7 +66,6 @@ function renderResizeHarness(
onMoveElement,
onBlockedEditAttempt,
onResizeElements: options.wireGroupResize === false ? undefined : onResizeElements,
- onSeek: options.onSeek,
setShowPopover: vi.fn(),
setRangeSelectionRef: { current: vi.fn() },
sessionEpoch,
@@ -451,16 +451,7 @@ describe("useTimelineClipDrag — multi-select group resize (restored)", () => {
});
describe("useTimelineClipDrag — trim guide and preview frame", () => {
- /** Playhead at 1.25s that follows preview seeks; clip a's end edge grabbed and dragged once. */
- function trimEndWithSeekingPlayhead(state: { isPlaying?: boolean } = {}) {
- usePlayerStore.setState({ currentTime: 1.25, ...state });
- const onSeek = vi.fn((t: number) => usePlayerStore.setState({ currentTime: t }));
- const a = el("a", { start: 1, duration: 2 });
- const h = renderResizeHarness([a], [], { onSeek });
- h.startResize(a, "end");
- h.movePointer(50);
- return { onSeek, h };
- }
+ const previewFrame = () => usePreviewFrameStore.getState().time;
/** Clip a (0-2s) with neighbour b starting at 5s, snapping on, a's end edge grabbed. */
function trimAEndBesideB() {
@@ -487,45 +478,78 @@ describe("useTimelineClipDrag — trim guide and preview frame", () => {
it("publishes no snap target when the trimmed edge is free", () => {
const h = trimAEndBesideB();
- h.movePointer(150);
+ h.movePointer(162); // 3.62s: 12px from the 3.5s ruler line, 13px from 3.75s
expect(h.getResizingClip()).toMatchObject({ snapTime: null, snapType: null });
h.unmount();
});
- it("never snaps a trimmed edge to the playhead — the edge drives its own seek", () => {
- usePlayerStore.setState({ currentTime: 5 }); // no clip edge or beat nearby, only the playhead
+ it("snaps a trimmed edge to the playhead, which stays where it was", () => {
+ usePlayerStore.setState({ currentTime: 5.1 }); // off the ruler grid; no clip edge or beat nearby
const a = el("a", { start: 0, duration: 2 });
const h = renderResizeHarness([a], [], { snap: true });
h.startResize(a, "end");
- h.movePointer(296); // a's end lands at 4.96s, 4px from the playhead
+ h.movePointer(306); // a's end lands at 5.06s, 4px from the playhead
+ expect(h.getResizingClip()).toMatchObject({
+ snapTime: 5.1,
+ snapType: "playhead",
+ previewDuration: 5.1,
+ });
+ expect(usePlayerStore.getState().currentTime).toBe(5.1);
+ h.unmount();
+ });
+
+ it("snaps a trimmed edge to the ruler's grid line when no clip edge is near", () => {
+ const h = trimAEndBesideB();
+ h.movePointer(152); // 3.52s, 2px from the 3.5s line (0.25s apart at 100px/s)
expect(h.getResizingClip()).toMatchObject({
- snapTime: null,
- snapType: null,
- previewDuration: 4.96,
+ snapTime: 3.5,
+ snapType: "grid",
+ previewDuration: 3.5,
});
h.unmount();
});
- it("shows the frame at the dragged edge, then puts the playhead back on release", async () => {
+ it("does not snap to the grid with the magnet off", () => {
+ const a = el("a", { start: 0, duration: 2 });
+ const h = renderResizeHarness([a], []);
+ h.startResize(a, "end");
+ h.movePointer(152);
+ expect(h.getResizingClip()).toMatchObject({ snapTime: null, previewDuration: 3.52 });
+ h.unmount();
+ });
+
+ it("shows the dragged edge's frame without moving the playhead, and drops it on release", async () => {
usePlayerStore.setState({ currentTime: 1.25 });
- const onSeek = vi.fn();
const a = el("a", { start: 1, duration: 2 });
- const h = renderResizeHarness([a], [], { onSeek });
+ const h = renderResizeHarness([a], []);
h.startResize(a, "end");
h.movePointer(50);
- expect(onSeek).toHaveBeenLastCalledWith(3.5 - 1 / 30, { keepPlaying: true, follow: false });
+ expect(previewFrame()).toBeCloseTo(3.5 - 1 / 30, 6);
+ h.movePointer(120);
+ expect(usePlayerStore.getState().currentTime).toBe(1.25);
await h.dropPointer();
- expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true, follow: false });
+ expect(previewFrame()).toBeNull();
+ expect(usePlayerStore.getState().currentTime).toBe(1.25);
+ h.unmount();
+ });
+
+ it("drops the preview frame when the trim is cancelled", () => {
+ const a = el("a", { start: 1, duration: 2 });
+ const h = renderResizeHarness([a], []);
+ h.startResize(a, "end");
+ h.movePointer(50);
+ expect(previewFrame()).not.toBeNull();
+ h.pressEscape();
+ expect(previewFrame()).toBeNull();
h.unmount();
});
it("previews the new in-point when the start edge is trimmed", () => {
- const onSeek = vi.fn();
const a = el("a", { start: 1, duration: 2 });
- const h = renderResizeHarness([a], [], { onSeek });
+ const h = renderResizeHarness([a], []);
h.startResize(a, "start");
h.movePointer(50);
- expect(onSeek).toHaveBeenLastCalledWith(1.5, { keepPlaying: true, follow: false });
+ expect(previewFrame()).toBe(1.5);
h.unmount();
});
@@ -540,41 +564,17 @@ describe("useTimelineClipDrag — trim guide and preview frame", () => {
h.unmount();
});
- it("restores the playhead it had before the first preview seek, not a seeked time", async () => {
- const { onSeek, h } = trimEndWithSeekingPlayhead();
- h.movePointer(80);
- h.movePointer(120);
- await h.dropPointer();
- expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true, follow: false });
- h.unmount();
- });
-
- it("leaves the playhead where playback is when a trim is released while playing", async () => {
- const { onSeek, h } = trimEndWithSeekingPlayhead({ isPlaying: true });
- h.movePointer(120);
- const callsBeforeRelease = onSeek.mock.calls.length;
- await h.dropPointer();
- expect(onSeek).toHaveBeenCalledTimes(callsBeforeRelease);
- expect(onSeek).not.toHaveBeenCalledWith(1.25, expect.anything());
- usePlayerStore.setState({ isPlaying: false });
- h.unmount();
- });
-
- it("draws no guide and seeks to the rendered edge when a group member clamps the trim", () => {
- const onSeek = vi.fn();
+ it("draws no guide and previews the rendered edge when a group member clamps the trim", () => {
const a = el("a", { start: 0, duration: 4 });
const b = el("b", { start: 0, duration: 1 });
const c = el("c", { start: 2, duration: 1 });
- const h = renderResizeHarness([a, b, c], ["a", "b"], { snap: true, onSeek });
+ const h = renderResizeHarness([a, b, c], ["a", "b"], { snap: true });
h.startResize(a, "end");
h.movePointer(-198); // a's raw end 2.02s snaps to c at 2s; b clamps the shared delta
const clip = h.getResizingClip()!;
expect(clip.previewStart + clip.previewDuration).toBeCloseTo(3.1, 3);
expect(clip).toMatchObject({ snapTime: null, snapType: null });
- expect(onSeek).toHaveBeenLastCalledWith(expect.closeTo(3.1 - 1 / 30, 3), {
- keepPlaying: true,
- follow: false,
- });
+ expect(previewFrame()).toBeCloseTo(3.1 - 1 / 30, 3);
h.unmount();
});
});
diff --git a/packages/studio/src/player/components/useTimelineClipDrag.ts b/packages/studio/src/player/components/useTimelineClipDrag.ts
index 3ae3516c87..48025b730e 100644
--- a/packages/studio/src/player/components/useTimelineClipDrag.ts
+++ b/packages/studio/src/player/components/useTimelineClipDrag.ts
@@ -12,6 +12,8 @@ import {
type TimelineGroupResizeSession,
} from "./timelineGroupEditing";
import { collectTimelineSnapTargets, type TimelineSnapTarget } from "./timelineSnapping";
+import { getTimelineGridStep, rulerFrameRate } from "./timelineRulerGeometry";
+import { setPreviewFrame } from "../store/previewFrameStore";
import type { StackingPatch } from "./timelineStackingSync";
import type { TimelineEditCallbacks } from "./timelineCallbacks";
import {
@@ -76,8 +78,6 @@ interface UseTimelineClipDragInput {
onResizeElements?: NonNullable<TimelineEditCallbacks["onResizeElements"]>;
onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedClipState["intent"]) => void;
onLinkEdit?: TimelineEditCallbacks["onLinkEdit"];
- /** Seeks the preview; a trim shows the frame at its dragged edge. */
- onSeek?: (time: number, options?: { keepPlaying?: boolean; follow?: boolean }) => void;
setShowPopover: (show: boolean) => void;
/** Stable ref to the range selection setter — wired after mount to break circular dependency. */
setRangeSelectionRef: React.RefObject<((sel: null) => void) | null>;
@@ -108,7 +108,6 @@ export function useTimelineClipDrag({
onResizeElements,
onBlockedEditAttempt,
onLinkEdit,
- onSeek,
setShowPopover,
setRangeSelectionRef,
readZIndex,
@@ -165,15 +164,11 @@ export function useTimelineClipDrag({
const dragAudioTracksRef = useRef<ReadonlySet<number> | null>(null);
const buildSnapTargets = useCallback(
- (
- excludeElementKey: string | null,
- includeBeats: boolean,
- includePlayhead = true,
- ): TimelineSnapTarget[] => {
+ (excludeElementKey: string | null, includeBeats: boolean): TimelineSnapTarget[] => {
// Magnet off ⇒ no targets and no scan; do NOT cache so a mid-gesture toggle
// back on starts scanning immediately (preserves the existing skip).
if (!snapContextRef.current.enabled) return [];
- const cacheKey = `${excludeElementKey ?? ""}|${includeBeats ? 1 : 0}|${includePlayhead ? 1 : 0}`;
+ const cacheKey = `${excludeElementKey ?? ""}|${includeBeats ? 1 : 0}`;
const cached = snapTargetsCacheRef.current.get(cacheKey);
if (cached) return cached;
const targets = collectTimelineSnapTargets({
@@ -181,13 +176,18 @@ export function useTimelineClipDrag({
playheadTime: usePlayerStore.getState().currentTime,
beatTimes: includeBeats ? snapContextRef.current.beatTimes : [],
excludeElementKey,
- includePlayhead,
});
snapTargetsCacheRef.current.set(cacheKey, targets);
return targets;
},
[],
);
+ // The ruler's line spacing at the current zoom; 0 with the magnet off, like the targets.
+ const snapGridStep = useCallback(() => {
+ if (!snapContextRef.current.enabled) return 0;
+ const frameRate = rulerFrameRate(usePlayerStore.getState().timeDisplayMode);
+ return getTimelineGridStep(durationRef.current, ppsRef.current, frameRate);
+ }, [durationRef, ppsRef]);
const [draggedClip, setDraggedClipState] = useState<DraggedClipState | null>(null);
const draggedClipRef = useRef<DraggedClipState | null>(null);
@@ -285,10 +285,6 @@ export function useTimelineClipDrag({
onResizeElementRef.current = onResizeElement;
const onResizeElementsRef = useRef(onResizeElements);
onResizeElementsRef.current = onResizeElements;
- const onSeekRef = useRef(onSeek);
- onSeekRef.current = onSeek;
- // Playhead time before the first trim preview seek; restored when the gesture ends.
- const trimSeekOriginRef = useRef<number | null>(null);
const readZIndexRef = useRef(readZIndex);
readZIndexRef.current = readZIndex;
const onStackingPatchesRef = useRef(onStackingPatches);
@@ -325,6 +321,7 @@ export function useTimelineClipDrag({
selectedKeys: gestureSelectedKeysRef.current,
buildSnapTargets,
audioTracks: dragAudioTracksRef.current,
+ gridStep: snapGridStep(),
});
},
[
@@ -335,6 +332,7 @@ export function useTimelineClipDrag({
trackInsertLayoutRef,
rowGeometryRef,
buildSnapTargets,
+ snapGridStep,
],
);
@@ -349,15 +347,11 @@ export function useTimelineClipDrag({
buildSnapTargets,
elements: elementsRef.current,
gestureKeys: gestureSelectedKeysRef.current,
+ gridStep: snapGridStep(),
});
- trimSeekOriginRef.current ??= usePlayerStore.getState().currentTime;
const setResizeState = (v: ResizePreviewResult) => {
- // A trim never changes the play state: keepPlaying lets seek() decide,
- // and it only resumes playback if it was already playing.
- onSeekRef.current?.(trimPreviewTime(resize.edge, v.previewStart, v.previewDuration), {
- keepPlaying: true,
- follow: false,
- });
+ // The preview shows the dragged edge's frame; the playhead stays where it was.
+ setPreviewFrame(trimPreviewTime(resize.edge, v.previewStart, v.previewDuration));
publishResizingClip(
resizingClipRef.current ? { ...resizingClipRef.current, started: true, ...v } : null,
);
@@ -393,7 +387,7 @@ export function useTimelineClipDrag({
}
previewGroupResize(session, next, setResizeState);
},
- [scrollRef, ppsRef, buildSnapTargets, publishResizingClip],
+ [scrollRef, ppsRef, buildSnapTargets, snapGridStep, publishResizingClip],
);
const applyResizePointerRef = useRef(applyResizePointer);
applyResizePointerRef.current = applyResizePointer;
@@ -404,13 +398,7 @@ export function useTimelineClipDrag({
cancelAnimationFrame(clipDragScrollRaf.current);
clipDragScrollRaf.current = 0;
}
- if (trimSeekOriginRef.current != null) {
- // Paused: put the playhead back. Playing: leave it, a backward jump would rewind live playback.
- if (!usePlayerStore.getState().isPlaying) {
- onSeekRef.current?.(trimSeekOriginRef.current, { keepPlaying: true, follow: false });
- }
- trimSeekOriginRef.current = null;
- }
+ setPreviewFrame(null);
// Gesture teardown: drop frozen caches so the next gesture reads fresh state.
snapTargetsCacheRef.current.clear();
dragAudioTracksRef.current = null;
diff --git a/packages/studio/src/player/components/useTimelineProviderState.tsx b/packages/studio/src/player/components/useTimelineProviderState.tsx
index 954a30df8b..5bef3ac338 100644
--- a/packages/studio/src/player/components/useTimelineProviderState.tsx
+++ b/packages/studio/src/player/components/useTimelineProviderState.tsx
@@ -223,7 +223,6 @@ export function useTimelineProviderState({
onResizeElements: pinnedOnResizeElements,
onBlockedEditAttempt: oneShotEdits.onBlockedEditAttempt,
onLinkEdit: oneShotEdits.onLinkEdit,
- onSeek,
setShowPopover,
setRangeSelectionRef,
readZIndex: zSyncEnabled ? readClipZIndex : undefined,
diff --git a/packages/studio/src/player/components/useTimelineTicks.ts b/packages/studio/src/player/components/useTimelineTicks.ts
index dca634bd4a..8129929244 100644
--- a/packages/studio/src/player/components/useTimelineTicks.ts
+++ b/packages/studio/src/player/components/useTimelineTicks.ts
@@ -1,8 +1,11 @@
import { useMemo } from "react";
-import { STUDIO_PREVIEW_FPS } from "../lib/time";
import type { TimelineTimeDisplayMode } from "../../utils/studioUiPreferences";
import type { TimelineTimeRange } from "../lib/timelineClipIndex";
-import { generateTicks, getTimelineMajorTickInterval } from "./timelineRulerGeometry";
+import {
+ generateTicks,
+ getTimelineMajorTickInterval,
+ rulerFrameRate,
+} from "./timelineRulerGeometry";
export function useTimelineTicks(
duration: number,
@@ -10,7 +13,7 @@ export function useTimelineTicks(
timeDisplayMode: TimelineTimeDisplayMode,
renderTimeRange?: TimelineTimeRange,
) {
- const frameRate = timeDisplayMode === "frame" ? STUDIO_PREVIEW_FPS : undefined;
+ const frameRate = rulerFrameRate(timeDisplayMode);
const ticks = useMemo(
() => generateTicks(duration, pixelsPerSecond, frameRate, renderTimeRange),
[duration, frameRate, pixelsPerSecond, renderTimeRange],
diff --git a/packages/studio/src/player/hooks/timelinePlayerTestHarness.ts b/packages/studio/src/player/hooks/timelinePlayerTestHarness.ts
index 17b643f043..edfe23733b 100644
--- a/packages/studio/src/player/hooks/timelinePlayerTestHarness.ts
+++ b/packages/studio/src/player/hooks/timelinePlayerTestHarness.ts
@@ -5,12 +5,14 @@ import { createRoot } from "react-dom/client";
import { vi } from "vitest";
import { useTimelinePlayer, type UseTimelinePlayerOptions } from "./useTimelinePlayer";
import { usePlayerStore } from "../store/playerStore";
+import { setPreviewFrame } from "../store/previewFrameStore";
export type TimelinePlayerApi = ReturnType<typeof useTimelinePlayer>;
export function resetPlayerStore() {
usePlayerStore.getState().reset();
usePlayerStore.setState({ requestedSeekTime: null });
+ setPreviewFrame(null);
}
function TimelinePlayerHarness({
diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts b/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts
index effd4eb106..500b2a895f 100644
--- a/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts
+++ b/packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts
@@ -12,6 +12,7 @@ import {
resetPlayerStore,
} from "./timelinePlayerTestHarness";
import { liveTime, usePlayerStore } from "../store/playerStore";
+import { setPreviewFrame } from "../store/previewFrameStore";
import { setTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFixture";
globalThis.IS_REACT_ACT_ENVIRONMENT = true;
@@ -350,6 +351,71 @@ describe("useTimelinePlayer seek keepPlaying option (#834)", () => {
});
});
+describe("useTimelinePlayer preview frame (a trim's dragged edge)", () => {
+ function previewFrame(time: number | null) {
+ act(() => setPreviewFrame(time));
+ }
+
+ it("shows the frame without moving the playhead, then puts the playhead's frame back", () => {
+ const { api, root, adapter } = renderAttachedTimelinePlayer();
+ seekWithAct(api, 1.25);
+ const seeks = liveTime.seekCount();
+ previewFrame(3.4);
+ expect(adapter.getTime()).toBe(3.4);
+ expect(usePlayerStore.getState().currentTime).toBe(1.25);
+ expect(liveTime.latest()).toBe(1.25);
+ previewFrame(null);
+ expect(adapter.getTime()).toBe(1.25);
+ expect(liveTime.seekCount()).toBe(seeks);
+ unmountWithAct(root);
+ });
+
+ it("keeps the playhead's time when paused, played or reloaded over the frame", () => {
+ const { getApi, root } = renderTimelinePlayerHarness();
+ attachIframeWindow(getApi(), makeAdapterWindow().win);
+ seekWithAct(getApi(), 1.25);
+ previewFrame(3.4);
+ act(() => getApi().pause());
+ expect(usePlayerStore.getState().currentTime).toBe(1.25);
+ act(() => getApi().refreshPlayer());
+ const gen = getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+ const shadow = makeFakeIframe(makeAdapterWindow().win);
+ shadow.src = "http://localhost/api/projects/demo/preview?_t=1";
+ act(() => {
+ getApi().setShadowIframeNode(shadow);
+ getApi().onShadowIframeLoad(gen);
+ getApi().onShadowReadyChange(gen, true);
+ });
+ expect(getApi().iframeRef.current).toBe(shadow);
+ expect(usePlayerStore.getState().currentTime).toBe(1.25);
+ previewFrame(3.5);
+ const live = (shadow.contentWindow as unknown as { __player: { getTime(): number } }).__player;
+ expect(live.getTime()).toBe(3.5);
+ act(() => getApi().play());
+ expect(live.getTime()).toBe(1.25);
+ unmountWithAct(root);
+ });
+
+ it("plays from the in-point when play rewinds from the end over the frame", () => {
+ const { api, root, adapter } = renderAttachedTimelinePlayer();
+ seekWithAct(api, 30);
+ act(() => usePlayerStore.setState({ inPoint: 3 }));
+ previewFrame(12);
+ act(() => api.play());
+ expect(adapter.getTime()).toBe(3);
+ unmountWithAct(root);
+ });
+
+ it("leaves live playback alone", () => {
+ const { api, root, adapter } = renderAttachedTimelinePlayer();
+ seekWithAct(api, 2);
+ setStorePlaying();
+ previewFrame(5);
+ expect(adapter.getTime()).toBe(2);
+ unmountWithAct(root);
+ });
+});
+
describe("useTimelinePlayer RAF loop wrap-around", () => {
type SeekCall = { time: number; options?: { keepPlaying?: boolean } };
diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.ts b/packages/studio/src/player/hooks/useTimelinePlayer.ts
index 597d1c03eb..bdb2fb62b8 100644
--- a/packages/studio/src/player/hooks/useTimelinePlayer.ts
+++ b/packages/studio/src/player/hooks/useTimelinePlayer.ts
@@ -5,6 +5,8 @@ import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
import { useShadowPreviewReload } from "./useShadowPreviewReload";
import { resolvePlaybackAdapter } from "./playbackAdapterResolution";
+import { subscribePreviewFrame, transportAdapter } from "../store/previewFrameStore";
+import { clampToDuration } from "../lib/time";
import { useTimelinePlayerLoop } from "./useTimelinePlayerLoop";
import { logReload } from "../../utils/reloadDebug";
@@ -148,10 +150,11 @@ export function useTimelinePlayer({
const iframe = overrideIframe !== undefined ? overrideIframe : iframeRef.current;
const win = iframe?.contentWindow as IframeWindow | null;
if (!iframe || !win) return null;
- return resolvePlaybackAdapter(iframe, win, {
+ const adapter = resolvePlaybackAdapter(iframe, win, {
cache: staticSeekAdapterRef,
warned: staticSeekWarnedRef,
});
+ return transportAdapter(adapter);
} catch {
return null;
}
@@ -301,7 +304,7 @@ export function useTimelinePlayer({
return false;
}
const duration = Math.max(0, adapter.getDuration());
- const nextTime = Math.max(0, duration > 0 ? Math.min(duration, time) : time);
+ const nextTime = clampToDuration(time, duration);
const keepPlaying = options?.keepPlaying === true;
const shouldResumeAfterSeek = shouldResumeForwardPlaybackAfterSeek({
keepPlaying,
@@ -366,6 +369,7 @@ export function useTimelinePlayer({
}
});
}, [seek, play, pause]);
+ useEffect(() => subscribePreviewFrame(getAdapter), [getAdapter]);
const { playbackKeyDownRef, playbackKeyUpRef, attachIframeShortcutListeners, togglePlay } =
usePlaybackKeyboard({
iframeRef,
diff --git a/packages/studio/src/player/lib/time.ts b/packages/studio/src/player/lib/time.ts
index 6795de056d..87febe432a 100644
--- a/packages/studio/src/player/lib/time.ts
+++ b/packages/studio/src/player/lib/time.ts
@@ -1,5 +1,8 @@
export const STUDIO_PREVIEW_FPS = 30;
+export const clampToDuration = (time: number, duration: number) =>
+ Math.max(0, duration > 0 ? Math.min(duration, time) : time);
+
export function formatTime(time: number): string {
if (!Number.isFinite(time) || time < 0) return "00:00";
const mins = Math.floor(time / 60);
diff --git a/packages/studio/src/player/store/previewFrameStore.ts b/packages/studio/src/player/store/previewFrameStore.ts
new file mode 100644
index 0000000000..f693e4f9ad
--- /dev/null
+++ b/packages/studio/src/player/store/previewFrameStore.ts
@@ -0,0 +1,48 @@
+import { create } from "zustand";
+import type { PlaybackAdapter } from "../lib/playbackTypes";
+import { clampToDuration } from "../lib/time";
+import { usePlayerStore } from "./playerStore";
+
+/** A frame the preview shows without moving the playhead (a trim's dragged edge); null shows the playhead's. */
+export const usePreviewFrameStore = create<{ time: number | null }>(() => ({ time: null }));
+
+export const setPreviewFrame = (time: number | null) => usePreviewFrameStore.setState({ time });
+
+// A trim's edge frame is on screen, not the transport's time: pause, play and a reload's
+// hand-over read the playhead's time, and play starts from it unless the caller seeked first.
+function showingPreviewFrame(adapter: PlaybackAdapter): PlaybackAdapter {
+ let seeked = false;
+ const time = () => (seeked ? adapter.getTime() : usePlayerStore.getState().currentTime);
+ return {
+ play: () => {
+ adapter.seek(time());
+ adapter.play();
+ },
+ pause: () => adapter.pause(),
+ seek: (t, options) => {
+ seeked = true;
+ adapter.seek(t, options);
+ },
+ getTime: time,
+ getDuration: () => adapter.getDuration(),
+ isPlaying: () => adapter.isPlaying(),
+ };
+}
+
+/** The adapter as the transport must see it while a paused preview frame is on screen. */
+export function transportAdapter(adapter: PlaybackAdapter | null): PlaybackAdapter | null {
+ const showing = usePreviewFrameStore.getState().time !== null;
+ return adapter && showing && !usePlayerStore.getState().isPlaying
+ ? showingPreviewFrame(adapter)
+ : adapter;
+}
+
+/** Puts each preview frame on screen while paused, and the playhead's frame back when it clears. */
+export function subscribePreviewFrame(getAdapter: () => PlaybackAdapter | null): () => void {
+ return usePreviewFrameStore.subscribe((state, prev) => {
+ if (state.time === prev.time || usePlayerStore.getState().isPlaying) return;
+ const adapter = getAdapter();
+ const time = state.time ?? usePlayerStore.getState().currentTime;
+ adapter?.seek(clampToDuration(time, adapter.getDuration()));
+ });
+}
diff --git a/packages/studio/src/player/store/timelineElement.ts b/packages/studio/src/player/store/timelineElement.ts
index 71920d900e..459dd08025 100644
--- a/packages/studio/src/player/store/timelineElement.ts
+++ b/packages/studio/src/player/store/timelineElement.ts
@@ -8,6 +8,7 @@
*/
import type { ClipManifestClip } from "../lib/playbackTypes";
+import { roundToCenti } from "../../utils/rounding";
export interface TimelineElement {
id: string;
@@ -112,9 +113,20 @@ type RowClock = Pick<
TimelineElement,
"start" | "parentCompositionStart" | "authoredStartIsMasterTime"
>;
+type SavedClip = RowClock & Pick<TimelineElement, "duration">;
const authoredOffset = (element: RowClock) =>
element.authoredStartIsMasterTime ? 0 : (element.parentCompositionStart ?? 0);
+/**
+ * Where a clip's edges sit once saved: its file stores the local start to the centisecond, and the
+ * duration too when a resize writes it; a move keeps the authored duration.
+ */
+export function savedClipEdges(element: SavedClip, start: number, resizedDuration?: number) {
+ const savedStart = authoredOffset(element) + roundToCenti(toAuthoredStart(element, start));
+ const duration = resizedDuration === undefined ? element.duration : roundToCenti(resizedDuration);
+ return { start: savedStart, end: savedStart + duration };
+}
+
/** The earliest master start this row can take: its host's start, or its own if already earlier. */
export function clampToHostStart(element: RowClock, masterTime: number): number {
return Math.max(Math.min(authoredOffset(element), element.start), masterTime);
diff --git a/packages/studio/tests/e2e/fixtures/timeline-trim-snap/hyperframes.json b/packages/studio/tests/e2e/fixtures/timeline-trim-snap/hyperframes.json
new file mode 100644
index 0000000000..c4816b5eaa
--- /dev/null
+++ b/packages/studio/tests/e2e/fixtures/timeline-trim-snap/hyperframes.json
@@ -0,0 +1,8 @@
+{
+ "$schema": "https://hyperframes.heygen.com/schema/hyperframes.json",
+ "paths": {
+ "blocks": "compositions",
+ "components": "compositions/components",
+ "assets": "assets"
+ }
+}
diff --git a/packages/studio/tests/e2e/fixtures/timeline-trim-snap/index.html b/packages/studio/tests/e2e/fixtures/timeline-trim-snap/index.html
new file mode 100644
index 0000000000..7685837e01
--- /dev/null
+++ b/packages/studio/tests/e2e/fixtures/timeline-trim-snap/index.html
@@ -0,0 +1,44 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=1920, height=1080" />
+ <style>
+ .card {
+ position: absolute;
+ inset: 0;
+ display: grid;
+ place-items: center;
+ font: 700 160px sans-serif;
+ color: #fff;
+ }
+ #card-a {
+ background: #2563eb;
+ }
+ #card-b {
+ background: #db2777;
+ inset: 30% 30%;
+ font-size: 96px;
+ }
+ </style>
+ </head>
+ <body>
+ <!-- card-a gets its end edge trimmed; card-b gets dragged onto a ruler line. -->
+ <div
+ id="root"
+ data-composition-id="main"
+ data-start="0"
+ data-duration="6"
+ data-width="1920"
+ data-height="1080"
+ data-no-timeline
+ >
+ <div id="card-a" class="clip card" data-start="0.5" data-duration="2" data-track-index="0">
+ A
+ </div>
+ <div id="card-b" class="clip card" data-start="3.1" data-duration="1" data-track-index="1">
+ B
+ </div>
+ </div>
+ </body>
+</html>
diff --git a/packages/studio/tests/e2e/timeline-trim-snap.mjs b/packages/studio/tests/e2e/timeline-trim-snap.mjs
new file mode 100644
index 0000000000..540ba22bf1
--- /dev/null
+++ b/packages/studio/tests/e2e/timeline-trim-snap.mjs
@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// Trimming a clip's edge must leave the playhead where it was paused, and a dragged clip must
+// land on a ruler line when no other snap target is near. Needs real pointer events and layout.
+import { launchStudioChrome } from "./chrome-executable.mjs";
+
+const STUDIO_URL = process.env.STUDIO_URL;
+const OUT_DIR = process.env.OUT_DIR;
+const PLAYHEAD_TOLERANCE_PX = 1.5;
+// Studio saves clip times to the centisecond, so a line between two centiseconds saves beside it.
+const SAVED_TIME_STEP_S = 0.01;
+const DROP_PAST_LINE_PX = 6;
+
+if (!STUDIO_URL) {
+ console.error("STUDIO_URL is required and must point at the timeline-trim-snap fixture");
+ process.exit(2);
+}
+const clipSelector = (id) => `.timeline-clip[data-el-id$="${id}"]`;
+const { browser } = await launchStudioChrome();
+const failures = [];
+const evidence = {};
+try {
+ const page = await browser.newPage();
+ await page.setViewport({ width: 1440, height: 900 });
+ await page.goto(STUDIO_URL, { waitUntil: "domcontentloaded" });
+ await page.waitForSelector(clipSelector("card-b"), { timeout: 60_000 });
+ await page.waitForSelector("[data-timeline-playhead-layer] > *", { timeout: 30_000 });
+
+ const frames = () =>
+ page.evaluate(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))));
+ const box = (selector) =>
+ page.$eval(selector, (el) => {
+ const r = el.getBoundingClientRect();
+ return { x: r.x, y: r.y, width: r.width, height: r.height };
+ });
+ const playheadX = () =>
+ page.$eval("[data-timeline-playhead-layer] > *", (el) => {
+ const r = el.getBoundingClientRect();
+ return r.x + r.width / 2;
+ });
+ const clipTimes = (id) =>
+ page.$eval(clipSelector(id), (el) => ({
+ start: Number(el.dataset.clipStart),
+ end: Number(el.dataset.clipEnd),
+ }));
+ // Screen x of every ruler line (beat lines excluded).
+ const rulerLines = () =>
+ page.$$eval('[data-timeline-grid-cell="major"], [data-timeline-grid-cell="minor"]', (cells) =>
+ cells.map((c) => c.getBoundingClientRect().x + 0.5).sort((a, b) => a - b),
+ );
+ // Seconds-to-pixels map from the two clips' left edges (a clip's width carries its own inset).
+ const timeMap = async () => {
+ const [a, b] = [await clipTimes("card-a"), await clipTimes("card-b")];
+ const [ax, bx] = [(await box(clipSelector("card-a"))).x, (await box(clipSelector("card-b"))).x];
+ const pps = (bx - ax) / (b.start - a.start);
+ return { pps, originX: ax - a.start * pps };
+ };
+ const a0 = await clipTimes("card-a");
+ const aBox = await box(clipSelector("card-a"));
+ const { pps, originX } = await timeMap();
+
+ // Pause the playhead at 1.2 s with a ruler click.
+ const ruler = await box("[data-timeline-grid-cell]");
+ await page.mouse.click(originX + 1.2 * pps, ruler.y + 6);
+ await frames();
+ const restX = await playheadX();
+ evidence.playheadRestS = (restX - originX) / pps;
+
+ // Trim a's end edge 70 px right; the handle mounts on hover.
+ const edgeX = aBox.x + aBox.width - 3;
+ const midY = aBox.y + aBox.height / 2;
+ await page.mouse.move(edgeX - 20, midY);
+ await page.mouse.move(edgeX, midY);
+ await page.waitForFunction(
+ (sel) =>
+ [...document.querySelectorAll(`${sel} div`)].some((d) => d.style.cursor === "col-resize"),
+ { timeout: 10_000 },
+ clipSelector("card-a"),
+ );
+ await page.mouse.down();
+ for (const dx of [10, 30, 50, 70]) {
+ await page.mouse.move(edgeX + dx, midY);
+ await frames();
+ }
+ const duringX = await playheadX();
+ if (OUT_DIR) await page.screenshot({ path: `${OUT_DIR}/during-trim.png` });
+ await page.mouse.up();
+ await page.waitForFunction(
+ (sel, end) => Number(document.querySelector(sel)?.dataset.clipEnd) !== end,
+ { timeout: 10_000 },
+ clipSelector("card-a"),
+ a0.end,
+ );
+ await frames();
+ const after = await timeMap();
+ const afterS = ((await playheadX()) - after.originX) / after.pps;
+ evidence.trim = {
+ endBefore: a0.end,
+ endAfter: (await clipTimes("card-a")).end,
+ playheadDuringS: (duringX - originX) / pps,
+ playheadAfterS: afterS,
+ ppsBefore: pps,
+ ppsAfter: after.pps,
+ };
+ if (Math.abs(duringX - restX) > PLAYHEAD_TOLERANCE_PX) {
+ failures.push(`playhead moved ${(duringX - restX).toFixed(1)}px during the trim`);
+ }
+ if (Math.abs(afterS - evidence.playheadRestS) * after.pps > PLAYHEAD_TOLERANCE_PX) {
+ failures.push(`playhead moved from ${evidence.playheadRestS}s to ${afterS}s after the trim`);
+ }
+
+ // Drag b so its start sits 6 px past the ruler line nearest 4.6 s, clear of every other target.
+ const b0 = await clipTimes("card-b");
+ const bBox = await box(clipSelector("card-b"));
+ const nearest = (lines, x) =>
+ lines.reduce((best, l) => (Math.abs(l - x) < Math.abs(best - x) ? l : best));
+ const line = nearest(await rulerLines(), after.originX + 4.6 * after.pps);
+ const grabX = bBox.x + bBox.width / 2;
+ const grabY = bBox.y + bBox.height / 2;
+ const dropDx = line + DROP_PAST_LINE_PX - bBox.x;
+ await page.mouse.move(grabX, grabY);
+ await page.mouse.down();
+ for (const part of [0.25, 0.5, 0.75, 1]) {
+ await page.mouse.move(grabX + dropDx * part, grabY);
+ await frames();
+ }
+ await page.mouse.up();
+ await page.waitForFunction(
+ (sel, start) => Number(document.querySelector(sel)?.dataset.clipStart) !== start,
+ { timeout: 10_000 },
+ clipSelector("card-b"),
+ b0.start,
+ );
+ await frames();
+ // Re-read both in the settled layout: a save can re-fit the timeline's zoom.
+ const settled = await timeMap();
+ const bx = (await box(clipSelector("card-b"))).x;
+ const offLinePx = bx - nearest(await rulerLines(), bx);
+ const allowedPx = PLAYHEAD_TOLERANCE_PX + (SAVED_TIME_STEP_S / 2) * settled.pps;
+ evidence.grid = {
+ startBefore: b0.start,
+ startAfter: (await clipTimes("card-b")).start,
+ droppedPastLinePx: DROP_PAST_LINE_PX,
+ landedOffLinePx: offLinePx,
+ allowedPx,
+ };
+ if (OUT_DIR) await page.screenshot({ path: `${OUT_DIR}/after-grid-drag.png` });
+ if (Math.abs(offLinePx) > allowedPx) {
+ failures.push(`clip b landed ${offLinePx.toFixed(1)}px off the nearest ruler line`);
+ }
+} finally {
+ await browser.close();
+}
+console.log(JSON.stringify({ evidence, failures }, null, 2));
+if (failures.length > 0) process.exit(1);