Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.ymlindex 4a979d6b22..37cdea751c 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -848,6 +848,8 @@ jobs:packages/studio/data/projects/studio-opencp -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-snapcp -R packages/studio/tests/e2e/fixtures/inline-text-caret \packages/studio/data/projects/inline-text-caretcp -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 snappingif: success() || failure()run: |set -euo pipefail@@ -983,6 +985,8 @@ jobs:node packages/studio/tests/e2e/render-selects.mjs || rc=1STUDIO_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=1exit "$rc"- name: Measure the caret of a text edited in placeif: success() || failure()diff --git a/packages/studio/src/player/components/TimelineClipFades.tsx b/packages/studio/src/player/components/TimelineClipFades.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.75sexpect(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 nearbyconst 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 deltaconst 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.tsindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.jsonnew file mode 100644index 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.htmlnew file mode 100644index 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.mjsnew file mode 100644index 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);