Skip to content

Commit e5a0370

Browse files
feat(studio): transition seams blur and carry a badge (#4280)
* feat(studio): transition seams blur and carry a badge * fix(studio): keep labelled transitions on one row * fix(studio): render transition crossfade zone * fix(studio): gate seams on transition labels * fix(studio): bridge GSAP transition markers to clips * fix(studio): clear transition seam CI failures * fix(studio): register transition frame classes
1 parent 189bead commit e5a0370

19 files changed

Lines changed: 403 additions & 12 deletions

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

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ import { queryTimelineClipIndex } from "../lib/timelineClipIndex";
3232
import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
3333
import { timelineClipFocusId } from "./timelineNavigationIdentity";
3434
import { useTimelineKeyboardActor } from "./useTimelineKeyboardActor";
35+
import { deriveTimelineTransitionSeams } from "./timelineTransitionSeams";
36+
import { TimelineTransitionOverlays } from "./TimelineTransitionOverlays";
3537

3638
export function TimelineLanes({
3739
pps,
@@ -104,13 +106,15 @@ export function TimelineLanes({
104106
const { collapsedGroupIds, expandedLaneOwnerIds, toggleGroupExpanded, toggleLaneOwnerExpanded } =
105107
useTimelineGroupDisclosure();
106108
const automationLanes = useAutomationLanes();
109+
const allTransitionElements = useMemo(
110+
() => tracks.flatMap(([, elements]) => elements.map(getPreviewElement)),
111+
[getPreviewElement, tracks],
112+
);
107113
// A group's automation clock is COMPOSITION time (groups doc §1.3), so its
108114
// synthetic lane element spans the whole composition rather than a clip.
109115
const compositionDuration = usePlayerStore((s) => s.duration);
110116
useAutomationSelectionKeyboard({ lanes: automationLanes });
111117
const { logicalRowsByTrack, groupByAnchor } = useTimelineLaneRowIndexes(logicalRows, groups);
112-
// Which tracks are group MEMBERS, so their headers can render the level-2
113-
// nesting their `aria-level` already reports.
114118
const groupMemberTracks = useMemo(
115119
() => new Set(groups.flatMap((group) => group.memberTracks)),
116120
[groups],
@@ -197,11 +201,7 @@ export function TimelineLanes({
197201
const ts = trackStyles.get(trackNum) ?? getTrackStyle("");
198202
const isPendingTrack =
199203
draggedClip?.started === true && !trackOrder.includes(trackNum) && els.length === 0;
200-
// All lanes use the same uniform color — no alternating stripes.
201204
const rowBackground = theme.rowBackground;
202-
// The beat-dot strip occupies the top of this track's lane (active track,
203-
// or the music track when nothing is selected). When shown, keyframe
204-
// diamonds shrink + drop to the bottom half so they don't collide with it.
205205
const beatStripOnTrack = trackShowsBeatStrip(els, beatAnalysis?.beatTimes, {
206206
selectedElementId,
207207
isMusicTrack,
@@ -223,9 +223,10 @@ export function TimelineLanes({
223223
// property lanes are showing. Undefined means "fill the row", which is
224224
// right only while it is collapsed and the row is nothing but bar.
225225
const clipBarHeight = rowExpanded ? TRACK_H - 2 * CLIP_Y : undefined;
226-
// The clips whose envelopes this row draws, at their dragged positions.
227-
// Once per row, not once per clip in the map below.
228226
const automationElements = els.map(getPreviewElement);
227+
const transitionSeams = deriveTimelineTransitionSeams(allTransitionElements).filter(
228+
(seam) => seam.incoming.track === trackNum,
229+
);
229230
// Minted here because this is the only place that sees BOTH ends of
230231
// the disclosure: the caret in the sticky header and the diamond lanes
231232
// on the canvas. Keyed by display row, not by `trackNum`, which is a
@@ -553,6 +554,12 @@ export function TimelineLanes({
553554
);
554555
})
555556
}
557+
<TimelineTransitionOverlays
558+
seams={transitionSeams}
559+
pixelsPerSecond={pps}
560+
rowHeight={rowHeight}
561+
clipBarHeight={clipBarHeight}
562+
/>
556563
{/* The automation lanes belong to the ROW, so they are mounted
557564
here rather than under the active clip's property lanes.
558565
Hanging off that clip meant selecting a sibling moved the
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
import type { CSSProperties } from "react";
2+
3+
interface TimelineTransitionBadgeProps {
4+
centerPx: number;
5+
top: number;
6+
widthPx: number;
7+
outgoingSrc?: string;
8+
incomingSrc?: string;
9+
}
10+
11+
export function TimelineTransitionBadge({
12+
centerPx,
13+
top,
14+
widthPx,
15+
outgoingSrc,
16+
incomingSrc,
17+
}: TimelineTransitionBadgeProps) {
18+
const style = {
19+
left: centerPx,
20+
top,
21+
"--timeline-transition-zone-width": `${widthPx}px`,
22+
} as CSSProperties;
23+
return (
24+
<div className="timeline-transition" style={style} aria-hidden="true">
25+
<div className="timeline-transition__zone">
26+
<div
27+
className="timeline-transition__image timeline-transition__image--out"
28+
style={outgoingSrc ? { backgroundImage: `url("${outgoingSrc}")` } : undefined}
29+
/>
30+
<div
31+
className="timeline-transition__image timeline-transition__image--in"
32+
style={incomingSrc ? { backgroundImage: `url("${incomingSrc}")` } : undefined}
33+
/>
34+
</div>
35+
<div className="timeline-transition__badge">
36+
<svg viewBox="0 0 20 20" role="presentation">
37+
<defs>
38+
<filter id="timeline-transition-glyph-blur">
39+
<feGaussianBlur stdDeviation="0.55" />
40+
</filter>
41+
</defs>
42+
<path
43+
className="timeline-transition__frame timeline-transition__frame--out"
44+
d="M3 5h8v10H3z"
45+
/>
46+
<path
47+
className="timeline-transition__frame timeline-transition__frame--in"
48+
d="M9 5h8v10H9z"
49+
/>
50+
<path
51+
className="timeline-transition__intersection"
52+
d="M9 5h2v10H9z"
53+
filter="url(#timeline-transition-glyph-blur)"
54+
/>
55+
</svg>
56+
</div>
57+
</div>
58+
);
59+
}
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import { CLIP_Y } from "./timelineLayout";
2+
import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
3+
import type { TimelineTransitionSeam } from "./timelineTransitionSeams";
4+
import { TimelineTransitionBadge } from "./TimelineTransitionBadge";
5+
6+
interface TimelineTransitionOverlaysProps {
7+
seams: readonly TimelineTransitionSeam[];
8+
pixelsPerSecond: number;
9+
rowHeight: number;
10+
clipBarHeight?: number;
11+
}
12+
13+
export function TimelineTransitionOverlays({
14+
seams,
15+
pixelsPerSecond,
16+
rowHeight,
17+
clipBarHeight,
18+
}: TimelineTransitionOverlaysProps) {
19+
const top = CLIP_Y + (clipBarHeight ?? rowHeight - 2 * CLIP_Y) / 2;
20+
return seams.map((seam) => (
21+
<TimelineTransitionBadge
22+
key={`${getTimelineElementIdentity(seam.outgoing)}-${getTimelineElementIdentity(seam.incoming)}`}
23+
centerPx={seam.centerTime * pixelsPerSecond}
24+
top={top}
25+
widthPx={Math.min(Math.max(seam.duration * pixelsPerSecond, 24), 32)}
26+
outgoingSrc={seam.outgoing.src}
27+
incomingSrc={seam.incoming.src}
28+
/>
29+
));
30+
}

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@ export interface TimelineTheme {
3232
panelResizeActive: string;
3333
clipRadius: string;
3434
audioClipRadius: string;
35+
transitionZone: string;
36+
transitionBadge: string;
37+
transitionBadgeInk: string;
3538
}
3639

3740
const TRACK_STYLE: TimelineTrackStyle = {
@@ -69,6 +72,9 @@ export const defaultTimelineTheme: TimelineTheme = {
6972
panelResizeActive: "var(--timeline-resize-active)",
7073
clipRadius: "var(--timeline-clip-radius)",
7174
audioClipRadius: "var(--timeline-clip-audio-radius)",
75+
transitionZone: "var(--timeline-transition-zone)",
76+
transitionBadge: "var(--timeline-transition-badge)",
77+
transitionBadgeInk: "var(--timeline-transition-badge-ink)",
7278
};
7379

7480
export type ClipWidthLadder = "labeled" | "picture" | "frame";
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
import { describe, expect, it } from "vitest";
2+
import { deriveTimelineTransitionSeams } from "./timelineTransitionSeams";
3+
import type { TimelineElement } from "../store/playerStore";
4+
5+
const clip = (
6+
id: string,
7+
start: number,
8+
duration: number,
9+
track = 0,
10+
transitionLabel?: string,
11+
): TimelineElement => ({
12+
id,
13+
tag: "video",
14+
start,
15+
duration,
16+
track,
17+
transitionLabel,
18+
});
19+
20+
describe("deriveTimelineTransitionSeams", () => {
21+
it("finds a labelled transition and centers the seam in the shared time", () => {
22+
const label = "hf:transition:out:in:crossfade";
23+
const [seam] = deriveTimelineTransitionSeams([
24+
clip("in", 1.8, 2, 0, label),
25+
clip("out", 0, 2, 0, label),
26+
]);
27+
expect(seam?.outgoing).toEqual(clip("out", 0, 2, 0, label));
28+
expect(seam?.incoming).toEqual(clip("in", 1.8, 2, 0, label));
29+
expect(seam?.centerTime).toBeCloseTo(1.9);
30+
expect(seam?.duration).toBeCloseTo(0.2);
31+
});
32+
33+
it("does not badge an unlabelled overlap", () => {
34+
expect(deriveTimelineTransitionSeams([clip("out", 0, 2), clip("in", 1.8, 2)])).toEqual([]);
35+
});
36+
37+
it("does not badge a cross-track overlap", () => {
38+
const label = "hf:transition:out:in:crossfade";
39+
expect(
40+
deriveTimelineTransitionSeams([clip("out", 0, 2, 0, label), clip("in", 1.8, 2, 1, label)]),
41+
).toEqual([]);
42+
});
43+
44+
it("rejects crisp gaps and touching edges", () => {
45+
expect(deriveTimelineTransitionSeams([clip("a", 0, 2), clip("b", 2.04, 1)])).toEqual([]);
46+
expect(deriveTimelineTransitionSeams([clip("a", 0, 2), clip("b", 2, 1)])).toEqual([]);
47+
});
48+
});
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import type { TimelineElement } from "../store/playerStore";
2+
3+
export interface TimelineTransitionSeam {
4+
outgoing: TimelineElement;
5+
incoming: TimelineElement;
6+
centerTime: number;
7+
duration: number;
8+
}
9+
10+
export function isTransitionPair(a: TimelineElement, b: TimelineElement): boolean {
11+
return Boolean(a.transitionLabel && a.transitionLabel === b.transitionLabel);
12+
}
13+
14+
export function deriveTimelineTransitionSeams(
15+
elements: readonly TimelineElement[],
16+
): TimelineTransitionSeam[] {
17+
const sorted = [...elements].sort((left, right) => left.start - right.start);
18+
const seams: TimelineTransitionSeam[] = [];
19+
for (let index = 0; index < sorted.length - 1; index += 1) {
20+
const outgoing = sorted[index]!;
21+
const incoming = sorted[index + 1]!;
22+
if (outgoing.track !== incoming.track || !isTransitionPair(outgoing, incoming)) continue;
23+
const outgoingEnd = outgoing.start + outgoing.duration;
24+
const overlapStart = Math.max(outgoing.start, incoming.start);
25+
const overlapEnd = Math.min(outgoingEnd, incoming.start + incoming.duration);
26+
const duration = overlapEnd - overlapStart;
27+
if (duration <= 0) continue;
28+
seams.push({
29+
outgoing,
30+
incoming,
31+
centerTime: overlapStart + duration / 2,
32+
duration,
33+
});
34+
}
35+
return seams;
36+
}

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,24 @@ describe("normalizeToZones — CapCut-stable lanes follow the track-index (never
171171
});
172172

173173
describe("normalizeToZones — legacy overlap spill (display-only, deterministic)", () => {
174+
it("keeps a labelled transition pair on one row", () => {
175+
const transitionLabel = "hf:transition:outgoing:incoming:crossfade";
176+
const out = normalizeToZones([
177+
{ ...zClip("outgoing", 0, 2.5, 0, 0), transitionLabel },
178+
{ ...zClip("incoming", 2, 2.5, 0, 0), transitionLabel },
179+
]);
180+
expect(trackOf(out, "outgoing")).toBe(0);
181+
expect(trackOf(out, "incoming")).toBe(0);
182+
});
183+
184+
it("still splits an unlabelled overlap", () => {
185+
const out = normalizeToZones([
186+
zClip("outgoing", 0, 2.5, 0, 0),
187+
zClip("incoming", 2, 2.5, 0, 0),
188+
]);
189+
expect(trackOf(out, "outgoing")).not.toBe(trackOf(out, "incoming"));
190+
});
191+
174192
it("splits time-overlapping SAME-track clips onto adjacent sub-lanes (no visible overlap)", () => {
175193
// a [0,5), b [2,7) overlaps a, c [6,9) sequential — all authored on track 1.
176194
// The editor forbids per-track overlap, but a legacy file can carry it; the

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import type { TimelineElement } from "../store/playerStore";
22
import { isAudioTimelineElement } from "../../utils/timelineInspector";
3+
import { isTransitionPair } from "./timelineTransitionSeams";
34

45
/**
56
* Free-form vertical zones, top → bottom: visual, audio. Canvas layering is
@@ -66,7 +67,9 @@ function packTrackLanes(
6667
const ordered = [...clips].sort(byStableId);
6768
const lanes: TimelineElement[][] = [];
6869
for (const el of ordered) {
69-
let sub = lanes.findIndex((occ) => occ.every((o) => !overlaps(o, el)));
70+
let sub = lanes.findIndex((occ) =>
71+
occ.every((o) => !overlaps(o, el) || isTransitionPair(o, el)),
72+
);
7073
if (sub === -1) {
7174
sub = lanes.length;
7275
lanes.push([]);

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ export interface TimelineLike {
3232
time: () => number;
3333
duration: () => number;
3434
isActive: () => boolean;
35+
labels?: Record<string, number>;
36+
getLabels?: () => Record<string, number>;
3537
}
3638

3739
export interface ClipManifestClip extends RuntimeTimelineClipIdentity {

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
// @vitest-environment jsdom
22
import { describe, expect, it } from "vitest";
3+
import { gsap } from "gsap";
34
import {
45
createTimelineElementFromManifestClip,
56
parseTimelineFromDOM,
@@ -20,6 +21,33 @@ function makeDoc(html: string): Document {
2021
}
2122

2223
describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
24+
it("bridges a real GSAP transition marker onto both named clips", () => {
25+
document.body.innerHTML = `
26+
<div data-composition-id="root">
27+
<img data-hf-id="outgoing" data-start="0" data-duration="2.5" data-track-index="0" />
28+
<img data-hf-id="incoming" data-start="2" data-duration="2.5" data-track-index="0" />
29+
</div>
30+
`;
31+
const timeline = gsap.timeline({ paused: true });
32+
timeline.addLabel("hf:transition:outgoing:incoming:crossfade", 2);
33+
const runtimeWindow = window as Window & {
34+
__timelines?: Record<string, typeof timeline>;
35+
};
36+
runtimeWindow.__timelines = { main: timeline };
37+
38+
try {
39+
const elements = parseTimelineFromDOM(document, 5);
40+
expect(elements.map((element) => element.transitionLabel)).toEqual([
41+
"hf:transition:outgoing:incoming:crossfade",
42+
"hf:transition:outgoing:incoming:crossfade",
43+
]);
44+
} finally {
45+
delete runtimeWindow.__timelines;
46+
timeline.kill();
47+
document.body.innerHTML = "";
48+
}
49+
});
50+
2351
it("harvests hfId from a data-start element that has data-hf-id", () => {
2452
const doc = makeDoc(`
2553
<div data-composition-id="root">

0 commit comments

Comments
 (0)