Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(studio): export timeline row order and fade handle boxes, readable fx badge (#4904)
Miguel Ángel05145bf73c6a
diff --git a/packages/studio/src/components/nle/useCanvasZOrderTimelineMirror.ts b/packages/studio/src/components/nle/useCanvasZOrderTimelineMirror.tsindex eb8b87831d..7d104ba9e3 100644--- a/packages/studio/src/components/nle/useCanvasZOrderTimelineMirror.ts+++ b/packages/studio/src/components/nle/useCanvasZOrderTimelineMirror.ts@@ -2,13 +2,13 @@ import { useCallback, useRef } from "react";import { usePlayerStore } from "../../player";import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";import {- displayTrackOrder,resolveRepositionLaneMove,resolveZMirrorLaneMove,type ZMirrorAction,type ZMirrorLaneMove,} from "../../player/components/timelineZMirror";import type { TimelineElement } from "../../player/store/playerStore";+import { timelineTrackOrder } from "../../player/components/timelineTrackDisplay";import { commitZMirrorLaneMove } from "../../player/components/timelineClipDragCommit";import { deriveTimelineStoreKey } from "../../player/lib/timelineElementHelpers";import { buildStableSelector, getSelectorIndex } from "../editor/domEditingDom";@@ -156,7 +156,7 @@ function useMirrorLaneMoveCommit(): (move,{elements: els,- trackOrder: displayTrackOrder(els),+ trackOrder: timelineTrackOrder(els),updateElement: (key, updates) => usePlayerStore.getState().updateElement(key, updates),onMoveElements,// NO readZIndex / onStackingPatches: see the hook doc — the lane→zdiff --git a/packages/studio/src/index.ts b/packages/studio/src/index.tsindex c6ee950fae..ed1b257ae6 100644--- a/packages/studio/src/index.ts+++ b/packages/studio/src/index.ts@@ -62,6 +62,13 @@ export { TimelineProvider, useTimelineContext } from "./player/components/Timeliexport type { TimelineTheme } from "./player/components/timelineTheme";export { TRACK_H } from "./player/components/timelineLayout";export type { TimelineTrackPadding } from "./player/components/timelineLayout";+export { displayTrackOrder } from "./player/components/useTimelineTrackDerivations";+export { fadeHandleBoxes } from "./player/components/timelineClipFadeGeometry";+export type {+ FadeEdge,+ FadeHandleBox,+ FadeHandleClipBox,+} from "./player/components/timelineClipFadeGeometry";// Clip content thumbnails: used by a host rendering its own timeline lane.export { AudioWaveform } from "./player/components/AudioWaveform";diff --git a/packages/studio/src/player/components/ClipBadges.tsx b/packages/studio/src/player/components/ClipBadges.tsxindex e8192668ae..69a8980307 100644--- a/packages/studio/src/player/components/ClipBadges.tsx+++ b/packages/studio/src/player/components/ClipBadges.tsx@@ -24,7 +24,7 @@ function SpeakerGlyph({ muted }: { muted: boolean }) {const BADGE_CLASS ="timeline-clip__badge inline-flex items-center gap-0.5 rounded-[3px] border bg-black/55 px-1 text-[9px] leading-[14px] whitespace-nowrap";const FX_ON = "border-white/40 text-white font-semibold";-const FX_OFF = "border-white/10 text-white/35";+const FX_OFF = "border-white/10 text-white/60";/** Premiere's fx badge — grey with no effects, white with any; hover lists them, click opens the clip menu. */export const ClipBadges = memo(function ClipBadges({diff --git a/packages/studio/src/player/components/TimelineClipFades.tsx b/packages/studio/src/player/components/TimelineClipFades.tsxindex c6c82a5884..f82596e6fd 100644--- a/packages/studio/src/player/components/TimelineClipFades.tsx+++ b/packages/studio/src/player/components/TimelineClipFades.tsx@@ -20,7 +20,14 @@ import { usePlayerStore, type TimelineElement } from "../store/playerStore";import { Tooltip } from "../../components/ui";import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";import { releasedOutsideWindow } from "./timelinePointerRelease";-import { CLIP_TRIM_HIT_PX } from "./timelineTheme";+import {+ FADE_TAB_CENTER_IN_HIT,+ FADE_TAB_WIDTH,+ fadeHandleBoxes,+ type FadeEdge,+ type FadeHandleBox,+ type FadeHandleClipBox,+} from "./timelineClipFadeGeometry";import {collectTimelineSnapTargets,snapTimelineTime,@@ -29,14 +36,9 @@ import {type TimelineSnapType,} from "./timelineSnapping";-type FadeEdge = "in" | "out";type FadeDraft = { edge: FadeEdge; seconds: number } | null;-const TAB_WIDTH = 4;const TAB_HEIGHT = 15;-const HANDLE_HIT = 24;-const TAB_INSET = 7;-const TAB_CENTER_IN_HIT = 8;const HANDLE_Z_ABOVE_CLIP_CONTENT = 30;const SUPPRESS_CLIP_NATIVE_TITLE = "";/** Pixels of pointer travel before a press on the handle counts as a drag. */@@ -103,12 +105,6 @@ function keyedFadeSeconds(key: string, shift: boolean, current: number, limit: nreturn FADE_KEYS[key]?.(current, shift ? 1 : 0.1, limit) ?? null;}-function topEdgeY(x: number, widthPx: number, heightPx: number, radiusPx: number): number {- const r = Math.min(radiusPx, widthPx / 2, heightPx / 2);- const d = x < r ? r - x : x > widthPx - r ? x - (widthPx - r) : 0;- return d > 0 ? r - Math.sqrt(Math.max(0, r * r - d * d)) : 0;-}-/** Slim tabs at each fade's end that drag `data-fade-in` / `data-fade-out`. */// fallow-ignore-next-line complexityexport function TimelineClipFades({@@ -136,12 +132,12 @@ export function TimelineClipFades({const visible =fades.fadeIn > 0 || fades.fadeOut > 0 || showHandles || dragging !== null || focused !== null;const rootRef = useRef<HTMLDivElement | null>(null);- const [clipBox, setClipBox] = useState<{- height: number;- width: number;- radius: number;- toolsLeft: number | null;- }>({ height: 0, width: 0, radius: 0, toolsLeft: null });+ const [clipBox, setClipBox] = useState<FadeHandleClipBox>({+ height: 0,+ width: 0,+ radius: 0,+ toolsLeft: null,+ });useLayoutEffect(() => {const root = rootRef.current;const clip = root?.parentElement;@@ -348,46 +344,25 @@ export function TimelineClipFades({const handlesVisible = showHandles || dragging !== null || focused !== null;if (!visible) return null;- const clipWidth = clipBox.toolsLeft === null ? widthPx : clipBox.width;- const edgeInset = clipBox.toolsLeft === null ? 0 : CLIP_TRIM_HIT_PX;- // Reserve FX horizontally so fades keep their top-edge lane above compact keyframe centres.- const rightEdge =- clipBox.toolsLeft === null ? clipWidth : Math.min(clipWidth - edgeInset, clipBox.toolsLeft);- const hitWidth = Math.min(HANDLE_HIT, (rightEdge - edgeInset) / 2);- const tabX = (edge: FadeEdge) => {- const knee = edge === "in" ? inPx : clipWidth - outPx;- const tabInset = edgeInset === 0 ? TAB_INSET : TAB_WIDTH;- const inset = Math.min(tabInset, (rightEdge - edgeInset) / 2);- return Math.min(rightEdge - inset, Math.max(edgeInset + inset, knee));- };- const boxLeft = (x: number) =>- Math.min(rightEdge - hitWidth, Math.max(edgeInset, x - hitWidth / 2));- const [inX, outX] = [tabX("in"), tabX("out")];- const mid = (inX + outX) / 2;// A handle with no 0.01 s step to move is not drawn, unless in use: its twin owns the spot.const drawn = (edge: FadeEdge) =>currentSeconds(edge) > 0 ||Math.round(limitFor(edge) * 100) >= 1 ||dragging === edge ||focused === edge;- const overlap = drawn("in") && drawn("out") && boxLeft(inX) + hitWidth > boxLeft(outX);- const handleGeometry = (edge: FadeEdge) => {- const x = edge === "in" ? inX : outX;- const [left, right] = !overlap- ? [boxLeft(x), boxLeft(x) + hitWidth]- : edge === "in"- ? [Math.max(edgeInset, mid - hitWidth), mid]- : [mid, Math.min(rightEdge, mid + hitWidth)];- const edgeY = topEdgeY(x, clipWidth, clipBox.height, clipBox.radius);- const top = edgeY + 1 - TAB_CENTER_IN_HIT;- return { left, width: right - left, tabLeft: x - left, top };- };- const handleStyle = (geometry: { left: number; top: number; width: number }): CSSProperties => ({+ const handleBoxes = fadeHandleBoxes({+ widthPx,+ inPx,+ outPx,+ clipBox,+ drawn: { in: drawn("in"), out: drawn("out") },+ });+ const handleStyle = (geometry: FadeHandleBox): CSSProperties => ({position: "absolute",top: geometry.top,left: geometry.left,width: geometry.width,- height: HANDLE_HIT,+ height: geometry.height,cursor: "ew-resize",opacity: handlesVisible ? 1 : 0,pointerEvents: handlesVisible && canEdit ? "auto" : "none",@@ -440,7 +415,7 @@ export function TimelineClipFades({)}{canEdit &&(["in", "out"] as const).filter(drawn).map((edge) => {- const geometry = handleGeometry(edge);+ const geometry = handleBoxes[edge];return (<FadeHandlekey={edge}@@ -451,7 +426,7 @@ export function TimelineClipFades({snapLabel={dragging === edge && snapType ? SNAP_LABEL[snapType] : null}style={handleStyle(geometry)}tabLeft={geometry.tabLeft}- tabTop={TAB_CENTER_IN_HIT - TAB_HEIGHT / 2}+ tabTop={FADE_TAB_CENTER_IN_HIT - TAB_HEIGHT / 2}focusable={focusable}dragging={dragging === edge}onPointerDown={onHandlePointerDown(edge)}@@ -583,9 +558,9 @@ function FadeHandle({aria-hidden="true"className="timeline-fade-tab"style={{- left: tabLeft - TAB_WIDTH / 2,+ left: tabLeft - FADE_TAB_WIDTH / 2,top: tabTop,- width: TAB_WIDTH,+ width: FADE_TAB_WIDTH,height: TAB_HEIGHT,pointerEvents: "none",}}diff --git a/packages/studio/src/player/components/timelineClipFadeGeometry.test.ts b/packages/studio/src/player/components/timelineClipFadeGeometry.test.tsnew file mode 100644index 0000000000..8330011dc3--- /dev/null+++ b/packages/studio/src/player/components/timelineClipFadeGeometry.test.ts@@ -0,0 +1,29 @@+import { describe, expect, it } from "vitest";+import { fadeHandleBoxes } from "./timelineClipFadeGeometry";++const flatClip = (width: number) => ({ width, height: 30, radius: 0, toolsLeft: null });++describe("fadeHandleBoxes", () => {+ it("centres each handle on its fade's end", () => {+ const boxes = fadeHandleBoxes({+ widthPx: 1000,+ inPx: 100,+ outPx: 200,+ clipBox: flatClip(1000),+ drawn: { in: true, out: true },+ });+ expect(boxes.in).toEqual({ left: 88, width: 24, height: 24, tabLeft: 12, top: -7 });+ expect(boxes.out).toEqual({ left: 788, width: 24, height: 24, tabLeft: 12, top: -7 });+ });++ it("splits two overlapping handles at the midpoint between their tabs", () => {+ const input = { widthPx: 100, inPx: 45, outPx: 45, clipBox: flatClip(100) };+ const boxes = fadeHandleBoxes({ ...input, drawn: { in: true, out: true } });+ expect(boxes.in).toMatchObject({ left: 26, width: 24, tabLeft: 19 });+ expect(boxes.out).toMatchObject({ left: 50, width: 24, tabLeft: 5 });++ // With its twin hidden, a handle keeps its full centred box.+ const alone = fadeHandleBoxes({ ...input, drawn: { in: true, out: false } });+ expect(alone.in).toMatchObject({ left: 33, width: 24 });+ });+});diff --git a/packages/studio/src/player/components/timelineClipFadeGeometry.ts b/packages/studio/src/player/components/timelineClipFadeGeometry.tsnew file mode 100644index 0000000000..59f5a4707c--- /dev/null+++ b/packages/studio/src/player/components/timelineClipFadeGeometry.ts@@ -0,0 +1,74 @@+import { CLIP_TRIM_HIT_PX } from "./timelineTheme";++export type FadeEdge = "in" | "out";++export const FADE_TAB_WIDTH = 4;+const FADE_HANDLE_HIT = 24;+export const FADE_TAB_CENTER_IN_HIT = 8;+const TAB_INSET = 7;++/** The clip as drawn; `toolsLeft` is where its FX badge starts, null when it has none. */+export interface FadeHandleClipBox {+ width: number;+ height: number;+ radius: number;+ toolsLeft: number | null;+}++/** A fade handle's hit box in px from the clip's top left; `tabLeft` is its tab's centre within it. */+export interface FadeHandleBox {+ left: number;+ width: number;+ height: number;+ tabLeft: number;+ top: number;+}++function topEdgeY(x: number, widthPx: number, heightPx: number, radiusPx: number): number {+ const r = Math.min(radiusPx, widthPx / 2, heightPx / 2);+ const d = x < r ? r - x : x > widthPx - r ? x - (widthPx - r) : 0;+ return d > 0 ? r - Math.sqrt(Math.max(0, r * r - d * d)) : 0;+}++/**+ * Where the fade handles sit on a clip `widthPx` wide: each centred on its fade's end, inside the+ * clip and left of its tools; two drawn handles that would overlap split at the midpoint.+ */+export function fadeHandleBoxes(input: {+ widthPx: number;+ inPx: number;+ outPx: number;+ clipBox: FadeHandleClipBox;+ drawn: Record<FadeEdge, boolean>;+}): Record<FadeEdge, FadeHandleBox> {+ const { widthPx, inPx, outPx, clipBox, drawn } = input;+ const clipWidth = clipBox.toolsLeft === null ? widthPx : clipBox.width;+ const edgeInset = clipBox.toolsLeft === null ? 0 : CLIP_TRIM_HIT_PX;+ // Reserve FX horizontally so fades keep their top-edge lane above compact keyframe centres.+ const rightEdge =+ clipBox.toolsLeft === null ? clipWidth : Math.min(clipWidth - edgeInset, clipBox.toolsLeft);+ const hitWidth = Math.min(FADE_HANDLE_HIT, (rightEdge - edgeInset) / 2);+ const tabX = (edge: FadeEdge) => {+ const knee = edge === "in" ? inPx : clipWidth - outPx;+ const tabInset = edgeInset === 0 ? TAB_INSET : FADE_TAB_WIDTH;+ const inset = Math.min(tabInset, (rightEdge - edgeInset) / 2);+ return Math.min(rightEdge - inset, Math.max(edgeInset + inset, knee));+ };+ const boxLeft = (x: number) =>+ Math.min(rightEdge - hitWidth, Math.max(edgeInset, x - hitWidth / 2));+ const [inX, outX] = [tabX("in"), tabX("out")];+ const mid = (inX + outX) / 2;+ const overlap = drawn.in && drawn.out && boxLeft(inX) + hitWidth > boxLeft(outX);+ const box = (edge: FadeEdge): FadeHandleBox => {+ const x = edge === "in" ? inX : outX;+ const [left, right] = !overlap+ ? [boxLeft(x), boxLeft(x) + hitWidth]+ : edge === "in"+ ? [Math.max(edgeInset, mid - hitWidth), mid]+ : [mid, Math.min(rightEdge, mid + hitWidth)];+ const edgeY = topEdgeY(x, clipWidth, clipBox.height, clipBox.radius);+ const top = edgeY + 1 - FADE_TAB_CENTER_IN_HIT;+ return { left, width: right - left, height: FADE_HANDLE_HIT, tabLeft: x - left, top };+ };+ return { in: box("in"), out: box("out") };+}diff --git a/packages/studio/src/player/components/timelineTrackDisplay.ts b/packages/studio/src/player/components/timelineTrackDisplay.tsindex 5cb9947963..45289b9d72 100644--- a/packages/studio/src/player/components/timelineTrackDisplay.ts+++ b/packages/studio/src/player/components/timelineTrackDisplay.ts@@ -6,7 +6,7 @@* routes through here; the raw key stays in callbacks and lookups only.*/-/** Ascending distinct track keys, the row order the timeline renders in. */+/** Ascending distinct track keys; the drawn rows also group audio (`displayTrackOrder`). */export function timelineTrackOrder(elements: readonly { track: number }[]): number[] {return [...new Set(elements.map((element) => element.track))].sort((a, b) => a - b);}diff --git a/packages/studio/src/player/components/timelineZMirror.ts b/packages/studio/src/player/components/timelineZMirror.tsindex 76f81e0337..acdf656a9f 100644--- a/packages/studio/src/player/components/timelineZMirror.ts+++ b/packages/studio/src/player/components/timelineZMirror.ts@@ -3,6 +3,7 @@ import { classifyZone } from "./timelineZones";import { isLaneFree, timeRangesOverlap } from "./timelineCollision";import { authoredTrackForLane, sameSourceFile } from "./timelineAuthoredTrack";import { samePaintScope } from "./timelineStackingSync";+import { timelineTrackOrder } from "./timelineTrackDisplay";/*** Mirror a canvas z-order action (Bring to Front / Bring Forward / Send Backward /@@ -111,13 +112,6 @@ function expandedChildAllowedLanes();}-/** Ascending unique display lanes of `elements` — identical to how Timeline.tsx- * builds `trackOrder`, so `insertRow` indexes the same boundary space. Exported- * so the mirror wiring can hand commitZMirrorLaneMove the matching trackOrder. */-export function displayTrackOrder(elements: TimelineElement[]): number[] {- return [...new Set(elements.map((el) => el.track))].sort((a, b) => a - b);-}-/*** Resolve the timeline lane move that mirrors a z-order action on `element`.* Returns null when no timeline mirror applies: audio / zero-length clips, no@@ -146,8 +140,8 @@ export function resolveZMirrorLaneMove(input: ZMirrorInput): ZMirrorLaneMove {const referenceLane = resolveReferenceLane(input, overlapSet, up);if (referenceLane == null) return null;- const order = displayTrackOrder(elements);- const visualLanes = displayTrackOrder(elements.filter((el) => classifyZone(el) === "visual"));+ const order = timelineTrackOrder(elements);+ const visualLanes = timelineTrackOrder(elements.filter((el) => classifyZone(el) === "visual"));const refIdx = visualLanes.indexOf(referenceLane);if (refIdx === -1) return null; // reference is not a visual lane — no mirror@@ -251,8 +245,8 @@ export function resolveRepositionLaneMove(input: ZRepositionInput): ZMirrorLaneM}if (aboveLane == null && belowLane == null) return null;- const order = displayTrackOrder(elements);- const visualLanes = displayTrackOrder(elements.filter((el) => classifyZone(el) === "visual"));+ const order = timelineTrackOrder(elements);+ const visualLanes = timelineTrackOrder(elements.filter((el) => classifyZone(el) === "visual"));const allowedLanes = expandedChildAllowedLanes(element, elements);const args = {elements,diff --git a/packages/studio/src/player/components/useTimelineTrackDerivations.test.ts b/packages/studio/src/player/components/useTimelineTrackDerivations.test.tsindex 62f1c2c85a..d03c4fdf64 100644--- a/packages/studio/src/player/components/useTimelineTrackDerivations.test.ts+++ b/packages/studio/src/player/components/useTimelineTrackDerivations.test.ts@@ -15,7 +15,7 @@ import React, { act } from "react";import { createRoot } from "react-dom/client";import { afterEach, describe, expect, it } from "vitest";import { usePlayerStore, type TimelineElement } from "../store/playerStore";-import { useTimelineTrackDerivations } from "./useTimelineTrackDerivations";+import { displayTrackOrder, useTimelineTrackDerivations } from "./useTimelineTrackDerivations";globalThis.IS_REACT_ACT_ENVIRONMENT = true;@@ -100,4 +100,17 @@ describe("useTimelineTrackDerivations", () => {const { groups } = derive([clip("sfx-1", 0, { audioGroup: "sfx" })]);expect(groups[0]).toMatchObject({ id: "sfx", label: "sfx", volume: 1, hidden: false });});++ it("gives hosts the drawn row order, members left out while their group is collapsed", () => {+ const elements = [+ clip("vo-1", 0, { audioGroup: "voiceover" }),+ clip("music", 1),+ clip("vo-2", 2, { audioGroup: "voiceover" }),+ ];+ expect(displayTrackOrder(elements, new Set())).toEqual(derive(elements).trackOrder);++ usePlayerStore.setState({ collapsedGroupIds: new Set(["voiceover"]) });+ expect(derive(elements).trackOrder).toEqual([-0.5, 1]);+ expect(displayTrackOrder(elements, new Set(["voiceover"]))).toEqual([-0.5, 1]);+ });});diff --git a/packages/studio/src/player/components/useTimelineTrackDerivations.ts b/packages/studio/src/player/components/useTimelineTrackDerivations.tsindex 1c8b83208d..ee4a1ac93e 100644--- a/packages/studio/src/player/components/useTimelineTrackDerivations.ts+++ b/packages/studio/src/player/components/useTimelineTrackDerivations.ts@@ -170,12 +170,38 @@ function groupTimelineTracks(return { tracks, groups, trackGroupOf };}+/** The timeline's rows top to bottom, as drawn: tracks by number, each audio group's anchor+ * row with its members under it. */+function timelineDisplayTracks(+ elements: readonly TimelineElement[],+ collapsedGroupIds: ReadonlySet<string>,+) {+ const byTrack = new Map<number, TimelineElement[]>();+ for (const el of elements) {+ const list = byTrack.get(el.track) ?? [];+ list.push(el);+ byTrack.set(el.track, list);+ }+ const rawTracks = Array.from(byTrack.entries()).sort(([a], [b]) => a - b);+ const grouped = groupTimelineTracks(rawTracks, collapsedGroupIds);+ return { ...grouped, trackOrder: grouped.tracks.map(([trackNum]) => trackNum) };+}++/**+ * The track number of each timeline row, top to bottom: pass the player store's `elements` and+ * `collapsedGroupIds`. A group's anchor row is its first member's track minus 0.5.+ */+export function displayTrackOrder(+ elements: readonly TimelineElement[],+ collapsedGroupIds: ReadonlySet<string>,+): number[] {+ return timelineDisplayTracks(elements, collapsedGroupIds).trackOrder;+}+/*** Per-render track derivations Timeline.tsx feeds the canvas/lanes: the lane →* clip grouping (`tracks`, group-aware order), per-lane visual styles, the- * matching `trackOrder`, and audio-group membership. Extracted from- * Timeline.tsx as a cohesive unit (600-line studio cap); each memo keys on the- * expanded display element set exactly as before.+ * matching `trackOrder`, and audio-group membership.*/export function useTimelineTrackDerivations(expandedElements: TimelineElement[]): {tracks: [number, TimelineElement[]][];@@ -184,20 +210,10 @@ export function useTimelineTrackDerivations(expandedElements: TimelineElement[])groups: TimelineTrackGroupInfo[];trackGroupOf: Map<number, TimelineTrackGroupInfo>;} {- const rawTracks = useMemo(() => {- const map = new Map<number, TimelineElement[]>();- for (const el of expandedElements) {- const list = map.get(el.track) ?? [];- list.push(el);- map.set(el.track, list);- }- return Array.from(map.entries()).sort(([a], [b]) => a - b);- }, [expandedElements]);-const collapsedGroupIds = usePlayerStore((s) => s.collapsedGroupIds);- const { tracks, groups, trackGroupOf } = useMemo(- () => groupTimelineTracks(rawTracks, collapsedGroupIds),- [rawTracks, collapsedGroupIds],+ const { tracks, groups, trackGroupOf, trackOrder } = useMemo(+ () => timelineDisplayTracks(expandedElements, collapsedGroupIds),+ [expandedElements, collapsedGroupIds],);const trackStyles = useMemo(() => {@@ -208,7 +224,5 @@ export function useTimelineTrackDerivations(expandedElements: TimelineElement[])return map;}, [tracks]);- const trackOrder = useMemo(() => tracks.map(([trackNum]) => trackNum), [tracks]);-return { tracks, trackStyles, trackOrder, groups, trackGroupOf };}