Skip to content

Commit 8666720

Browse files
feat(studio): trimming a clip shows the snap guide and the frame at the dragged edge (#4163)
* feat(studio): trimming a clip shows the snap guide and the frame at the dragged edge * fix(studio): guide and preview stay correct under group trim and beat snaps Independent review found: the group-trim guide and preview seek read the raw single-clip snap even when a member clamp moved the rendered edge; a beat-snapped trim never drew a guide because the beat highlight still read the old move-only draggedClip prop; the 1/30 frame lead duplicated STUDIO_PREVIEW_FPS. * fix(studio): a trim never changes play state and never snaps to the playhead Both are regressions from the guide/preview seek this branch adds: the preview and restore seeks now carry keepPlaying, so seek() only resumes playback if it was already running; the playhead is dropped from the trim snap set since the dragged edge drives its own preview seek, so snapping to it was circular. Neighbour clip edges and beats remain valid targets. * fix(studio): releasing a trim while playing no longer rewinds the playhead * refactor(studio): share trim-with-seeking-playhead setup in resize tests
1 parent a944662 commit 8666720

12 files changed

Lines changed: 310 additions & 45 deletions

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,7 @@ export const Timeline = memo(function Timeline({
233233
onResizeElement: pinnedOnResizeElement,
234234
onResizeElements: pinnedOnResizeElements,
235235
onBlockedEditAttempt,
236+
onSeek,
236237
setShowPopover,
237238
setRangeSelectionRef,
238239
readZIndex: zSyncEnabled ? readClipZIndex : undefined,

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

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ import type { TimelineLaneBaseProps } from "./timelineLaneProps";
2424
import type { TimelineLaneGapStrips } from "./useTimelineGapHighlights";
2525
import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
2626
import { TimelineGestureOverlay } from "./TimelineGestureOverlay";
27+
import { resolveSnapGuide } from "./timelineSnapping";
2728

2829
interface TimelineCanvasProps extends TimelineLaneBaseProps {
2930
major: number[];
@@ -48,7 +49,8 @@ interface TimelineCanvasProps extends TimelineLaneBaseProps {
4849
const DROP_PREVIEW_SECONDS = 3;
4950

5051
export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvasProps) {
51-
const { draggedClip, scrollRef, selectedElementIds, displayTrackOrder } = props;
52+
const { draggedClip, resizingClip, scrollRef, selectedElementIds, displayTrackOrder } = props;
53+
const snapGuide = resolveSnapGuide(draggedClip, resizingClip);
5254
const draggedRowIndex =
5355
draggedClip?.started === true ? displayTrackOrder.indexOf(draggedClip.previewTrack) : -1;
5456
const dropTrackIndex = props.dropPreview
@@ -120,6 +122,7 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
120122

121123
<TimelineLanes
122124
{...props}
125+
snapGuide={snapGuide}
123126
draggedElement={draggedElement}
124127
multiDragPreview={multiDragPreview}
125128
onToggleTrackHidden={onToggleTrackHidden}
@@ -222,18 +225,18 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
222225
/>
223226
)}
224227

225-
{/* Snap guide for non-beat targets during clip drag */}
226-
{draggedClip?.started && draggedClip.snapTime != null && draggedClip.snapType !== "beat" && (
228+
{/* Snap guide for non-beat targets during a clip move or trim */}
229+
{snapGuide && snapGuide.type !== "beat" && (
227230
<div
228231
className="absolute pointer-events-none"
229232
style={{
230-
left: props.contentOrigin + draggedClip.snapTime * props.pps,
233+
left: props.contentOrigin + snapGuide.time * props.pps,
231234
top: RULER_H,
232235
bottom: 0,
233236
width: 1,
234-
background: draggedClip.snapType === "playhead" ? "#3CE6AC" : "rgba(255,255,255,0.6)",
237+
background: snapGuide.type === "playhead" ? "#3CE6AC" : "rgba(255,255,255,0.6)",
235238
boxShadow:
236-
draggedClip.snapType === "playhead"
239+
snapGuide.type === "playhead"
237240
? "0 0 6px rgba(60,230,172,0.5)"
238241
: "0 0 6px rgba(255,255,255,0.4)",
239242
zIndex: 60,

‎packages/studio/src/player/components/TimelineLanes.test.tsx‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ interface RenderLanesOptions {
7272
onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
7373
hoveredClip?: string | null;
7474
renderClipContent?: React.ComponentProps<typeof TimelineLanes>["renderClipContent"];
75+
snapGuide?: { time: number; type: "beat" | "clip-edge" | "playhead" } | null;
7576
}
7677

7778
function renderLanes(options: RenderLanesOptions = {}): {
@@ -141,6 +142,7 @@ function renderLanes(options: RenderLanesOptions = {}): {
141142
renderClipContent={next.renderClipContent}
142143
draggedClip={next.draggedClip ?? null}
143144
draggedElement={null}
145+
snapGuide={next.snapGuide ?? null}
144146
multiDragPreview={next.multiDragPreview ?? null}
145147
blockedClipRef={createRef<BlockedClipState | null>()}
146148
suppressClickRef={{ current: false }}
@@ -179,6 +181,36 @@ function visibilityLabels(host: HTMLElement): (string | null)[] {
179181
);
180182
}
181183

184+
/** The beat guide's own highlight div, keyed by the green glow every other beat lacks. */
185+
function beatHighlight(host: HTMLElement): HTMLElement | undefined {
186+
return Array.from(host.querySelectorAll("div")).find((div) =>
187+
(div.style.boxShadow ?? "").includes("34,197,94"),
188+
);
189+
}
190+
191+
describe("TimelineLanes beat guide", () => {
192+
it("draws the beat highlight from snapGuide, not from the stale draggedClip prop", () => {
193+
const view = renderLanes({
194+
elements: [element("clip-a", TRACK_A)],
195+
snapGuide: { time: 1.5, type: "beat" },
196+
});
197+
198+
expect(beatHighlight(view.host)?.style.left).toBe("150px");
199+
act(() => view.root.unmount());
200+
});
201+
202+
it("clears the highlight once the trim it belonged to ends", () => {
203+
const view = renderLanes({
204+
elements: [element("clip-a", TRACK_A)],
205+
snapGuide: { time: 1.5, type: "beat" },
206+
});
207+
view.rerender({ elements: [element("clip-a", TRACK_A)], snapGuide: null });
208+
209+
expect(beatHighlight(view.host)).toBeUndefined();
210+
act(() => view.root.unmount());
211+
});
212+
});
213+
182214
describe("TimelineLanes track numbering", () => {
183215
// Screen readers literally announced "Hide track 0.16666666666666666".
184216
it("numbers tracks contiguously from 1 regardless of the fractional sort keys", () => {

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

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ export function TimelineLanes({
5959
hoveredClip,
6060
draggedClip,
6161
draggedElement,
62+
snapGuide,
6263
multiDragPreview,
6364
blockedClipRef,
6465
suppressClickRef,
@@ -331,11 +332,7 @@ export function TimelineLanes({
331332
beatTimes={beatAnalysis?.beatTimes}
332333
beatStrengths={beatAnalysis?.beatStrengths}
333334
pps={pps}
334-
highlightTime={
335-
draggedClip?.started && draggedClip.snapType === "beat"
336-
? draggedClip.snapTime
337-
: null
338-
}
335+
highlightTime={snapGuide?.type === "beat" ? snapGuide.time : null}
339336
renderTimeRange={rowsVirtualized ? renderTimeRange : undefined}
340337
/>
341338
{/* Beat dots on the active track (the one holding the selection),

‎packages/studio/src/player/components/TimelineTypes.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ export interface TimelineClipRenderContext {
1212
export interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverrides {
1313
/** Project-scoped reset boundary; soft source refreshes retain the same epoch. */
1414
sessionEpoch?: number;
15-
onSeek?: (time: number) => void;
15+
/** keepPlaying: true preserves the current play state across the seek. */
16+
onSeek?: (time: number, options?: { keepPlaying?: boolean }) => void;
1617
onDrillDown?: (element: TimelineElement) => void;
1718
renderClipContent?: (
1819
element: TimelineElement,

‎packages/studio/src/player/components/timelineClipDragPreview.ts‎

Lines changed: 51 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import {
1212
snapMoveToTargets,
1313
snapTimelineTime,
1414
type TimelineSnapTarget,
15+
type TimelineSnapType,
1516
} from "./timelineSnapping";
1617
import { resolveInsertRow, resolveZoneDropPlacement } from "./timelineCollision";
1718
import {
@@ -21,11 +22,13 @@ import {
2122
import { clampGroupMoveDelta } from "./timelineMultiDragPreview";
2223
import type { DraggedClipState, ResizingClipState } from "./timelineClipDragTypes";
2324
import { resolveDragLandingStart } from "./timelineDragLanding";
25+
import { STUDIO_PREVIEW_FPS } from "../lib/time";
2426

2527
/** Snap-target builder closure supplied by the hook (closes over refs + store). */
2628
type BuildSnapTargets = (
2729
excludeElementKey: string | null,
2830
includeBeats: boolean,
31+
includePlayhead?: boolean,
2932
) => TimelineSnapTarget[];
3033

3134
export interface DragPreviewContext {
@@ -223,6 +226,14 @@ export function computeDragPreview(
223226
};
224227
}
225228

229+
/** One frame: the last visible frame of a clip sits just before its end time. */
230+
const TRIM_END_FRAME_LEAD_S = 1 / STUDIO_PREVIEW_FPS;
231+
232+
/** The composition time whose frame a trim shows: the edge being dragged. */
233+
export function trimPreviewTime(edge: "start" | "end", start: number, duration: number): number {
234+
return edge === "start" ? start : Math.max(start, start + duration - TRIM_END_FRAME_LEAD_S);
235+
}
236+
226237
export interface ResizePreviewContext {
227238
scroll: HTMLDivElement | null;
228239
pps: number;
@@ -234,6 +245,9 @@ export interface ResizePreviewResult {
234245
previewStart: number;
235246
previewDuration: number;
236247
previewPlaybackStart?: number;
248+
/** The target the trimmed edge snapped to; null when the edge is free. */
249+
snapTime: number | null;
250+
snapType: TimelineSnapType | null;
237251
}
238252

239253
/** Compute the trim preview for a pointer x (pure — the hook applies the state). */
@@ -287,28 +301,31 @@ export function computeResizePreview(
287301
effectiveClientX,
288302
);
289303

290-
// Snap edge to unified targets (beats + clip edges + playhead) when available.
291-
// The snap must stay inside the same limits resolveTimelineResize enforces, or
292-
// it would push the edge past the available source media / composition end.
293-
// The music track defines the beats, so it must not snap to them — but it
294-
// still snaps to the playhead and other clip edges.
304+
// Snap to beats and clip edges, never the playhead (the dragged edge drives
305+
// its own preview seek, so that would be circular). Stay inside the same
306+
// limits resolveTimelineResize enforces. The music track defines the
307+
// beats, so it must not snap to them, but still snaps to clip edges.
295308
const trimTargets = buildSnapTargets(
296309
resize.element.key ?? resize.element.id,
297310
!isMusicTrack(resize.element),
311+
false,
298312
);
313+
let snap: TimelineSnapTarget | null = null;
299314
if (trimTargets.length > 0) {
300315
const snapSecs = TIMELINE_SNAP_PX / Math.max(pps, 1);
301316
if (resize.edge === "end") {
302317
const edgeTime = nextResize.start + nextResize.duration;
303-
const snapped = snapTimelineTime(edgeTime, trimTargets, snapSecs).time;
318+
const { time: snapped, target } = snapTimelineTime(edgeTime, trimTargets, snapSecs);
304319
// Stay within [start+minDuration, maxEnd] so the snap can't create a
305320
// degenerate clip or run past the source/composition limit.
306321
const snappedDuration = Math.round((snapped - nextResize.start) * 1000) / 1000;
307-
if (snapped !== edgeTime && snapped <= maxEnd + 1e-6 && snappedDuration >= 0.05) {
308-
nextResize = { ...nextResize, duration: snappedDuration };
322+
if (target && snapped <= maxEnd + 1e-6 && snappedDuration >= 0.05) {
323+
// An edge already on the target still owns the guide; only move it when off.
324+
if (snapped !== edgeTime) nextResize = { ...nextResize, duration: snappedDuration };
325+
snap = target;
309326
}
310327
} else {
311-
const snapped = snapTimelineTime(nextResize.start, trimTargets, snapSecs).time;
328+
const { time: snapped, target } = snapTimelineTime(nextResize.start, trimTargets, snapSecs);
312329
const delta = nextResize.start - snapped; // >0 when snapping left
313330
// Leftward snap reveals more source; cap so playbackStart can't go < 0.
314331
const maxLeftDelta =
@@ -318,22 +335,20 @@ export function computeResizePreview(
318335
// Also require the resulting duration to stay >= minDuration so a rightward
319336
// snap (delta < 0) can't collapse the clip to zero/negative.
320337
const snappedDuration = Math.round((nextResize.duration + delta) * 1000) / 1000;
321-
if (
322-
snapped !== nextResize.start &&
323-
snapped >= 0 &&
324-
delta <= maxLeftDelta + 1e-6 &&
325-
snappedDuration >= 0.05
326-
) {
327-
nextResize = {
328-
...nextResize,
329-
start: snapped,
330-
duration: snappedDuration,
331-
playbackStart:
332-
nextResize.playbackStart != null
333-
? Math.round(Math.max(0, nextResize.playbackStart - delta * playbackRate) * 1000) /
334-
1000
335-
: undefined,
336-
};
338+
if (target && snapped >= 0 && delta <= maxLeftDelta + 1e-6 && snappedDuration >= 0.05) {
339+
if (snapped !== nextResize.start) {
340+
nextResize = {
341+
...nextResize,
342+
start: snapped,
343+
duration: snappedDuration,
344+
playbackStart:
345+
nextResize.playbackStart != null
346+
? Math.round(Math.max(0, nextResize.playbackStart - delta * playbackRate) * 1000) /
347+
1000
348+
: undefined,
349+
};
350+
}
351+
snap = target;
337352
}
338353
}
339354
}
@@ -343,6 +358,8 @@ export function computeResizePreview(
343358
previewStart: nextResize.start,
344359
previewDuration: nextResize.duration,
345360
previewPlaybackStart: nextResize.playbackStart,
361+
snapTime: snap?.time ?? null,
362+
snapType: snap?.type ?? null,
346363
};
347364
}
348365

@@ -359,11 +376,18 @@ export function previewGroupResize(
359376
) => void,
360377
): void {
361378
const grabbedChange = applyTimelineGroupResizePreview(session, next);
379+
const previewStart = grabbedChange?.start ?? next.previewStart;
380+
const previewDuration = grabbedChange?.duration ?? next.previewDuration;
381+
// A member clamp can pull the grabbed edge off the raw snap target; then no guide.
382+
const edgeTime = session.edge === "end" ? previewStart + previewDuration : previewStart;
383+
const stillSnapped = next.snapTime != null && Math.abs(edgeTime - next.snapTime) < 1e-3;
362384
setResizeState({
363385
originScrollLeft: next.originScrollLeft,
364-
previewStart: grabbedChange?.start ?? next.previewStart,
365-
previewDuration: grabbedChange?.duration ?? next.previewDuration,
386+
previewStart,
387+
previewDuration,
366388
previewPlaybackStart: grabbedChange?.playbackStart ?? next.previewPlaybackStart,
389+
snapTime: stillSnapped ? next.snapTime : null,
390+
snapType: stillSnapped ? next.snapType : null,
367391
groupPreview: session.changes,
368392
});
369393
}

‎packages/studio/src/player/components/timelineClipDragTypes.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,9 @@ export interface ResizingClipState {
5757
previewStart: number;
5858
previewDuration: number;
5959
previewPlaybackStart?: number;
60+
/** Snap target the trimmed edge landed on, for the guide highlight. */
61+
snapTime?: number | null;
62+
snapType?: TimelineSnapType | null;
6063
/** Coordinator-owned group projection; canonical elements change only on commit. */
6164
groupPreview?: readonly {
6265
key: string;

‎packages/studio/src/player/components/timelineLaneProps.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import type { TrackVisualStyle } from "./timelineIcons";
88
import type { DraggedClipState, ResizingClipState, BlockedClipState } from "./useTimelineClipDrag";
99
import type { TimelineClipIndex, TimelineTimeRange } from "../lib/timelineClipIndex";
1010
import type { TimelineRowGeometry } from "./timelineLayout";
11+
import type { TimelineSnapTarget } from "./timelineSnapping";
1112
import type { TimelineVirtualRow } from "./useTimelineVirtualRows";
1213
import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
1314
import type { TimelineEditCallbacks } from "./timelineCallbacks";
@@ -112,6 +113,8 @@ export interface TimelineLaneBaseProps {
112113
export interface TimelineLanesProps extends TimelineLaneBaseProps {
113114
/** Live-derived by TimelineCanvas from {@link TimelineLaneBaseProps.draggedClip}. */
114115
draggedElement: TimelineElement | null;
116+
/** Live move or trim snap target, resolved once by TimelineCanvas. */
117+
snapGuide: TimelineSnapTarget | null;
115118
multiDragPreview: MultiDragPreviewInput | null;
116119
onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
117120
onTogglePropertyGroupKeyframe: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];

‎packages/studio/src/player/components/timelineSnapping.test.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import {
44
collectTimelineSnapTargets,
55
snapMoveToTargets,
66
snapTimelineTime,
7+
resolveSnapGuide,
78
} from "./timelineSnapping";
89

910
describe("collectTimelineSnapTargets", () => {
@@ -26,6 +27,18 @@ describe("collectTimelineSnapTargets", () => {
2627
expect(targets).toContainEqual({ time: 0.5, type: "beat" });
2728
});
2829

30+
it("omits the playhead when includePlayhead is false, for a trim", () => {
31+
const targets = collectTimelineSnapTargets({
32+
elements,
33+
playheadTime: 7.25,
34+
beatTimes: [0.5],
35+
includePlayhead: false,
36+
});
37+
expect(targets.some((t) => t.type === "playhead")).toBe(false);
38+
expect(targets).toContainEqual({ time: 2, type: "clip-edge" });
39+
expect(targets).toContainEqual({ time: 0.5, type: "beat" });
40+
});
41+
2942
it("excludes the dragged element's own edges", () => {
3043
const targets = collectTimelineSnapTargets({
3144
elements,
@@ -132,3 +145,17 @@ describe("snapMoveToTargets", () => {
132145
expect(r.snapTime).toBeNull();
133146
});
134147
});
148+
149+
describe("resolveSnapGuide", () => {
150+
it("prefers a started move, falls back to a trim, and is null when neither snapped", () => {
151+
const move = { started: true, snapTime: 2, snapType: "playhead" as const };
152+
const trim = { snapTime: 5, snapType: "clip-edge" as const };
153+
expect(resolveSnapGuide(move, trim)).toEqual({ time: 2, type: "playhead" });
154+
expect(resolveSnapGuide({ ...move, started: false }, trim)).toEqual({
155+
time: 5,
156+
type: "clip-edge",
157+
});
158+
expect(resolveSnapGuide(null, { snapTime: null, snapType: null })).toBeNull();
159+
expect(resolveSnapGuide(null, null)).toBeNull();
160+
});
161+
});

0 commit comments

Comments
 (0)