Merge pull request #2068 from heygen-com/worktree-fix-timeline-zindex-reorder

feat(studio): lane-model timeline — vertical drag restacks via z-index
This commit is contained in:
Miguel Ángel
2026-07-09 17:37:46 -04:00
committed by GitHub
59 changed files with 4510 additions and 628 deletions
+8
View File
@@ -16,6 +16,7 @@ function createMockDeps() {
onSetPlaybackRate: vi.fn(),
onSetColorGrading: vi.fn(),
onSetColorGradingCompare: vi.fn(),
onSetRootDuration: vi.fn(),
onEnablePickMode: vi.fn(),
onDisablePickMode: vi.fn(),
};
@@ -155,6 +156,13 @@ describe("installRuntimeControlBridge", () => {
expect(deps.onSetPlaybackRate).toHaveBeenCalledWith(1);
});
it("dispatches set-root-duration command with numeric seconds", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-root-duration", { durationSeconds: "18.5" }));
expect(deps.onSetRootDuration).toHaveBeenCalledWith(18.5);
});
it("dispatches set-color-grading command with target and grading payload", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
+2
View File
@@ -14,6 +14,7 @@ type BridgeDeps = {
onSetNativeMediaSyncDisabled: (disabled: boolean) => void;
onSetWebAudioMediaDisabled: (disabled: boolean) => void;
onSetPlaybackRate: (rate: number) => void;
onSetRootDuration: (durationSeconds: number) => void;
onSetColorGrading: (target: HfColorGradingTarget | string | null, grading: unknown) => void;
onSetColorGradingCompare: (
target: HfColorGradingTarget | string | null,
@@ -53,6 +54,7 @@ const CONTROL_HANDLERS: Record<string, ControlHandler> = {
"set-web-audio-media-disabled": (data, deps) =>
deps.onSetWebAudioMediaDisabled(Boolean(data.disabled)),
"set-playback-rate": (data, deps) => deps.onSetPlaybackRate(Number(data.playbackRate ?? 1)),
"set-root-duration": (data, deps) => deps.onSetRootDuration(Number(data.durationSeconds ?? 0)),
"set-color-grading": (data, deps) =>
deps.onSetColorGrading(data.target ?? null, data.grading ?? null),
"set-color-grading-compare": (data, deps) =>
+26
View File
@@ -1857,6 +1857,7 @@ export function initSandboxRuntimeModular(): void {
// transport tick. A plain count misses same-count swaps (one sub-comp unloads
// as another loads), so the signature keys on id+tag in document order.
let clipTreeSignature = "";
let liveRootDurationOverrideSeconds = 0;
const computeClipTreeSignature = (): string => {
let sig = "";
for (const el of document.querySelectorAll("[data-start]")) {
@@ -1909,6 +1910,30 @@ export function initSandboxRuntimeModular(): void {
scheduleRootStageLayoutDiagnostics();
};
const finitePositiveDuration = (value: number): number =>
Number.isFinite(value) && value > 0 ? value : 0;
const growRootDurationLive = (durationSeconds: number) => {
const nextDuration = finitePositiveDuration(Number(durationSeconds));
if (nextDuration <= 0) return;
const rootEl = resolveRootCompositionElement();
const rootAttrDuration = finitePositiveDuration(
Number.parseFloat(rootEl?.getAttribute("data-duration") ?? ""),
);
const currentDuration = Math.max(
liveRootDurationOverrideSeconds,
finitePositiveDuration(clock.getDuration()),
rootAttrDuration,
);
if (nextDuration <= currentDuration) return;
liveRootDurationOverrideSeconds = nextDuration;
rootEl?.setAttribute("data-duration", String(nextDuration));
clock.setDuration(nextDuration);
postTimeline();
postState(true);
};
const runAdapters = (method: "discover" | "pause" | "play", timeSeconds = 0) => {
for (const adapter of state.deterministicAdapters) {
try {
@@ -2202,6 +2227,7 @@ export function initSandboxRuntimeModular(): void {
if (state.transportClock) state.transportClock.setRate(state.playbackRate);
applyWebAudioRate();
},
onSetRootDuration: growRootDurationLive,
onSetColorGrading: (target, grading) => {
colorGrading.setGrading(target, grading);
},
@@ -57,9 +57,76 @@ describe("collectRuntimeTimelinePayload", () => {
expect(result.clips[0].id).toBe("text-1");
expect(result.clips[0].start).toBe(1);
expect(result.clips[0].duration).toBe(3);
expect(result.clips[0].track).toBe(0);
expect(result.clips[0].kind).toBe("element");
});
it("parses inline z-index for timeline clips", () => {
const root = document.createElement("div");
root.setAttribute("data-composition-id", "main");
root.setAttribute("data-duration", "10");
document.body.appendChild(root);
const clip = document.createElement("div");
clip.id = "layered";
clip.style.zIndex = "11";
clip.setAttribute("data-start", "0");
clip.setAttribute("data-duration", "4");
root.appendChild(clip);
const result = collectRuntimeTimelinePayload(defaultParams);
expect(result.clips[0].zIndex).toBe(11);
});
it("uses zero z-index sentinel when a timeline clip has no inline z-index", () => {
const root = document.createElement("div");
root.setAttribute("data-composition-id", "main");
root.setAttribute("data-duration", "10");
document.body.appendChild(root);
const clip = document.createElement("div");
clip.id = "auto-layer";
clip.setAttribute("data-start", "0");
clip.setAttribute("data-duration", "4");
root.appendChild(clip);
const result = collectRuntimeTimelinePayload(defaultParams);
expect(result.clips[0].zIndex).toBe(0);
});
it("assigns stacking context ids from root and nearest sub-composition", () => {
const root = document.createElement("div");
root.setAttribute("data-composition-id", "main");
root.setAttribute("data-duration", "10");
document.body.appendChild(root);
const rootClip = document.createElement("div");
rootClip.id = "root-layer";
rootClip.setAttribute("data-start", "0");
rootClip.setAttribute("data-duration", "5");
root.appendChild(rootClip);
const scene = document.createElement("div");
scene.id = "scene-host";
scene.setAttribute("data-composition-id", "scene");
scene.setAttribute("data-start", "0");
scene.setAttribute("data-duration", "5");
root.appendChild(scene);
const nestedClip = document.createElement("div");
nestedClip.id = "nested-layer";
nestedClip.setAttribute("data-start", "0");
nestedClip.setAttribute("data-duration", "2");
scene.appendChild(nestedClip);
const result = collectRuntimeTimelinePayload(defaultParams);
const rootLayer = result.clips.find((clip) => clip.id === "root-layer");
const nestedLayer = result.clips.find((clip) => clip.id === "nested-layer");
expect(rootLayer?.stackingContextId).toBe("main");
expect(nestedLayer?.stackingContextId).toBe("scene");
});
it("identifies video clips by tag", () => {
const root = document.createElement("div");
root.setAttribute("data-composition-id", "main");
+19
View File
@@ -32,6 +32,19 @@ function parseElementEndAttr(element: Element): number | null {
);
}
function readInlineZIndex(element: Element): number {
try {
const inline = (element as HTMLElement).style?.zIndex;
if (inline && inline !== "auto") {
const parsed = parseInt(inline, 10);
if (Number.isFinite(parsed)) return parsed;
}
return 0;
} catch {
return 0;
}
}
function maxDefinedNumber(...values: Array<number | null>): number | null {
const finite = values.filter((value): value is number => Number.isFinite(value ?? null));
if (finite.length === 0) return null;
@@ -434,6 +447,8 @@ export function collectRuntimeTimelinePayload(params: {
node.getAttribute("data-track-index") ?? node.getAttribute("data-track") ?? String(i),
10,
) || 0,
zIndex: readInlineZIndex(node),
stackingContextId: compositionContext.parentCompositionId ?? rootCompositionId,
kind,
tagName: tag,
compositionId: node.getAttribute("data-composition-id"),
@@ -545,6 +560,8 @@ export function collectRuntimeTimelinePayload(params: {
el.getAttribute("data-track-index") ?? el.getAttribute("data-track") ?? "",
10,
) || gsapTrack,
zIndex: readInlineZIndex(el),
stackingContextId: rootCompositionIdForGsap,
kind: "element",
tagName: el.tagName.toLowerCase(),
compositionId: el.getAttribute("data-composition-id"),
@@ -602,6 +619,8 @@ export function collectRuntimeTimelinePayload(params: {
el.getAttribute("data-track-index") ?? el.getAttribute("data-track") ?? "",
10,
) || overlayTrack,
zIndex: readInlineZIndex(el),
stackingContextId: rootCompositionIdForGsap,
kind: "element",
tagName: tag,
compositionId: el.getAttribute("data-composition-id"),
+4
View File
@@ -18,6 +18,7 @@ export type RuntimeBridgeControlAction =
| "set-media-output-muted"
| "set-native-media-sync-disabled"
| "set-web-audio-media-disabled"
| "set-root-duration"
| "stop-media"
| "flash-elements";
@@ -28,6 +29,7 @@ export type RuntimeBridgeControlMessage = {
frame?: number;
muted?: boolean;
volume?: number;
durationSeconds?: number;
disabled?: boolean;
playbackRate?: number;
target?: HfColorGradingTarget | string | null;
@@ -51,6 +53,8 @@ export type RuntimeTimelineClip = {
start: number;
duration: number;
track: number;
zIndex: number;
stackingContextId: string | null;
kind: "video" | "audio" | "image" | "element" | "composition";
tagName: string | null;
compositionId: string | null;
@@ -227,18 +227,46 @@ tl.fromTo("#box", { opacity: 0, x: -50 }, { opacity: 1, x: 0, duration: 1.5, eas
});
const result = (await res.json()) as {
ok: boolean;
mutated?: boolean;
after: string;
parsed: { animations: Array<{ fromProperties?: Record<string, number | string> }> };
};
expect(res.status).toBe(200);
expect(result.ok).toBe(true);
expect(result.mutated).toBe(true);
expect(result.after).toContain("opacity: 0.2");
expect(result.parsed.animations[0].fromProperties?.opacity).toBe(0.2);
// x unchanged
expect(result.parsed.animations[0].fromProperties?.x).toBe(-50);
});
it("reports no GSAP mutation when shifting positions in a file with no GSAP script", async () => {
const projectDir = createProjectDir();
const app = new Hono();
registerFileRoutes(app, createAdapter(projectDir));
const res = await app.request("http://localhost/projects/demo/gsap-mutations/index.html", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
type: "shift-positions",
targetSelector: "#box",
delta: 1,
}),
});
const result = (await res.json()) as {
ok?: boolean;
changed?: boolean;
mutated?: boolean;
};
expect(res.status).toBe(200);
expect(result.ok).toBe(true);
expect(result.changed).toBe(false);
expect(result.mutated).toBe(false);
});
it("consolidate-position-writes leaves exactly one position write per selector", async () => {
const projectDir = createProjectDir();
const CORRUPTED = `<!DOCTYPE html><html><body><script data-hyperframes-gsap>
@@ -2046,6 +2046,19 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
}
block = extractGsapScriptBlock(html);
}
if (!block && (body.type === "shift-positions" || body.type === "scale-positions")) {
return c.json({
ok: true,
changed: false,
mutated: false,
parsed: { animations: [], timelineVar: "tl", preamble: "", postamble: "" },
before: html,
after: html,
scriptText: "",
path: res.filePath,
backupPath: null,
});
}
if (!block) {
return c.json({ error: "no GSAP script found in file" }, 400);
}
@@ -2081,6 +2094,7 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
const responsePayload: Record<string, unknown> = {
ok: true,
changed,
mutated: changed,
parsed: freshParsed,
before: html,
after: newHtml,
+7 -10
View File
@@ -11,6 +11,7 @@ import { usePanelLayout } from "./hooks/usePanelLayout";
import { useFileManager } from "./hooks/useFileManager";
import { usePreviewPersistence } from "./hooks/usePreviewPersistence";
import { useTimelineEditing } from "./hooks/useTimelineEditing";
import type { TimelineZIndexReorderCommit } from "./hooks/useTimelineEditingTypes";
import type { BlockPreviewInfo } from "./components/sidebar/BlocksTab";
import { useDomEditSession } from "./hooks/useDomEditSession";
import { useSdkSelectionSync } from "./hooks/useSdkSelectionSync";
@@ -20,7 +21,7 @@ import { useBlockHandlers } from "./hooks/useBlockHandlers";
import { useAppHotkeys } from "./hooks/useAppHotkeys";
import { useClipboard } from "./hooks/useClipboard";
import { readStudioUiPreferences, writeStudioUiPreferences } from "./utils/studioUiPreferences";
import { selectedKeyframePercentagesForElement } from "./utils/keyframeSelection";
import { deleteSelectedKeyframes } from "./hooks/timelineEditingHelpers";
import { useCaptionDetection } from "./hooks/useCaptionDetection";
import { useRenderClipContent } from "./hooks/useRenderClipContent";
import { useConsoleErrorCapture } from "./hooks/useConsoleErrorCapture";
@@ -126,6 +127,7 @@ export function StudioApp() {
});
const editHistory = usePersistentEditHistory({ projectId });
const domEditSaveTimestampRef = useRef(0);
const handleDomZIndexReorderCommitRef = useRef<TimelineZIndexReorderCommit | null>(null);
const pendingTimelineEditPathRef = useRef(new Set<string>());
const isGestureRecordingRef = useRef(false);
const reloadPreview = useCallback(() => setRefreshKey((k) => k + 1), []);
@@ -183,6 +185,7 @@ export function StudioApp() {
isRecordingRef: isGestureRecordingRef,
sdkSession: editFlowSdkSession,
forceReloadSdkSession: sdkHandle.forceReload,
handleDomZIndexReorderCommitRef,
});
const {
activeBlockParams,
@@ -301,19 +304,12 @@ export function StudioApp() {
forceReloadSdkSession: sdkHandle.forceReload,
});
domEditSelectionBridgeRef.current = domEditSession.domEditSelection;
handleDomZIndexReorderCommitRef.current = domEditSession.handleDomZIndexReorderCommit;
clearDomSelectionRef.current = domEditSession.clearDomSelection;
handleDomEditElementDeleteRef.current = domEditSession.handleDomEditElementDelete;
resetKeyframesRef.current = domEditSession.handleResetSelectedElementKeyframes;
invalidateGsapCacheRef.current = domEditSession.invalidateGsapCache;
deleteSelectedKeyframesRef.current = () => {
const { selectedKeyframes, selectedElementId } = usePlayerStore.getState();
const a = domEditSession.selectedGsapAnimations.find((x) => x.keyframes);
if (!a) return;
// Only the active element's keyframes; a stale cross-element selection must not delete here.
for (const p of selectedKeyframePercentagesForElement(selectedKeyframes, selectedElementId)) {
domEditSession.handleGsapRemoveKeyframe(a.id, p);
}
};
deleteSelectedKeyframesRef.current = () => deleteSelectedKeyframes(domEditSession);
useSdkSelectionSync(
editFlowSdkSession,
domEditSession.domEditSelection,
@@ -524,6 +520,7 @@ export function StudioApp() {
handleTimelineElementMove={timelineEditing.handleTimelineElementMove}
handleTimelineElementResize={timelineEditing.handleTimelineElementResize}
handleToggleTrackHidden={timelineEditing.handleToggleTrackHidden}
handleToggleElementHidden={timelineEditing.handleToggleElementHidden}
handleBlockedTimelineEdit={timelineEditing.handleBlockedTimelineEdit}
handleTimelineElementSplit={timelineEditing.handleTimelineElementSplit}
handleRazorSplit={timelineEditing.handleRazorSplit}
@@ -59,6 +59,7 @@ export interface StudioPreviewAreaProps {
updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
) => Promise<void> | void;
handleToggleTrackHidden: (track: number, hidden: boolean) => Promise<void> | void;
handleToggleElementHidden: (elementKey: string, hidden: boolean) => Promise<void> | void;
handleBlockedTimelineEdit: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
handleRazorSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
@@ -85,6 +86,7 @@ export function StudioPreviewArea({
handleTimelineElementMove,
handleTimelineElementResize,
handleToggleTrackHidden,
handleToggleElementHidden,
handleBlockedTimelineEdit,
handleTimelineElementSplit,
handleRazorSplit,
@@ -182,6 +184,7 @@ export function StudioPreviewArea({
onMoveElement: handleTimelineElementMove,
onResizeElement: handleTimelineElementResize,
onToggleTrackHidden: handleToggleTrackHidden,
onToggleElementHidden: handleToggleElementHidden,
onBlockedEditAttempt: handleBlockedTimelineEdit,
onSplitElement: handleTimelineElementSplit,
onRazorSplit: handleRazorSplit,
@@ -282,6 +285,7 @@ export function StudioPreviewArea({
handleTimelineElementMove,
handleTimelineElementResize,
handleToggleTrackHidden,
handleToggleElementHidden,
handleBlockedTimelineEdit,
handleTimelineElementSplit,
handleRazorSplit,
@@ -14,6 +14,7 @@ import {
} from "../../utils/studioHelpers";
import { Layers } from "../../icons/SystemIcons";
import { useLayerDrag, isLayerDraggable, type LayerReorderEvent } from "./useLayerDrag";
import { computeReorderZValues, getElementZIndex } from "../../player/lib/layerOrdering";
const TAG_ICONS: Record<string, string> = {
video: "Vi",
@@ -228,9 +229,7 @@ export const LayersPanel = memo(function LayersPanel() {
reordered.splice(toIndex, 0, moved);
const existingValues = siblingLayers.map((l) => getElementZIndex(l.element));
const sorted = [...existingValues].sort((a, b) => b - a);
const hasDupes = sorted.some((v, i) => i > 0 && v === sorted[i - 1]);
const zValues = hasDupes ? reordered.map((_, i) => reordered.length - i) : sorted;
const zValues = computeReorderZValues(existingValues, fromIndex, toIndex);
const entries = reordered.map((layer, i) => ({
element: layer.element,
@@ -388,25 +387,6 @@ export const LayersPanel = memo(function LayersPanel() {
// ── Pure helpers ──────────────────────────────────────────────────────
// fallow-ignore-next-line complexity
function getElementZIndex(element: HTMLElement): number {
try {
const inline = element.style?.zIndex;
if (inline && inline !== "auto") {
const parsed = parseInt(inline, 10);
if (Number.isFinite(parsed)) return parsed;
}
const win = element.ownerDocument?.defaultView;
if (!win) return 0;
const value = win.getComputedStyle(element).zIndex;
if (value === "auto" || value === "") return 0;
const parsed = parseInt(value, 10);
return Number.isFinite(parsed) ? parsed : 0;
} catch {
return 0;
}
}
// fallow-ignore-next-line complexity
export function sortLayersByZIndex(layers: DomEditLayerItem[]): DomEditLayerItem[] {
if (layers.length <= 1) return layers;
@@ -33,6 +33,7 @@ export function TimelineEditProvider({
value.onMoveElement,
value.onResizeElement,
value.onToggleTrackHidden,
value.onToggleElementHidden,
value.onBlockedEditAttempt,
value.onSplitElement,
value.onRazorSplit,
@@ -0,0 +1,104 @@
// @vitest-environment jsdom
import { afterEach, describe, expect, it, vi } from "vitest";
import { applyTimelineStackingReorder, extendRootDurationIfNeeded } from "./timelineEditingHelpers";
import type { TimelineElement } from "../player/store/playerStore";
import { usePlayerStore } from "../player/store/playerStore";
afterEach(() => {
usePlayerStore.getState().reset();
});
function makeIframeWith(html: string): HTMLIFrameElement {
const iframe = document.createElement("iframe");
document.body.append(iframe);
const doc = iframe.contentDocument;
if (!doc) throw new Error("expected iframe document");
doc.body.innerHTML = html;
return iframe;
}
function el(input: Partial<TimelineElement> & { id: string; tag: string }): TimelineElement {
return {
label: input.id,
start: 0,
duration: 5,
track: 0,
zIndex: 0,
hasExplicitZIndex: false,
stackingContextId: null,
...input,
};
}
describe("applyTimelineStackingReorder", () => {
it("commits via the change's own locator even when the element is not in timelineElements", () => {
// Sub-comp children live in the preview iframe but NOT in the top-level
// timelineElements list — the intent must be self-contained.
const iframe = makeIframeWith(`<div id="chip" style="z-index: 1"></div>`);
const commit = vi.fn<(entries: unknown[]) => void>();
applyTimelineStackingReorder({
element: el({ id: "chip", tag: "div" }),
stackingReorder: {
contextKey: "scene",
placement: { type: "above", layerId: "layer:scene:x" },
zIndexChanges: [
{
key: "scenes/scene.html#chip",
zIndex: 5,
domId: "chip",
sourceFile: "scenes/scene.html",
},
],
},
timelineElements: [], // element intentionally absent from the top-level list
iframe,
activeCompPath: "index.html",
commit,
});
expect(commit).toHaveBeenCalledTimes(1);
const entries = commit.mock.calls[0]![0] as Array<{
zIndex: number;
id?: string;
sourceFile: string;
}>;
expect(entries).toHaveLength(1);
expect(entries[0]!.zIndex).toBe(5);
expect(entries[0]!.id).toBe("chip");
expect(entries[0]!.sourceFile).toBe("scenes/scene.html");
});
it("never commits when the dragged clip is audio", () => {
const iframe = makeIframeWith(`<audio id="track"></audio>`);
const commit = vi.fn<(entries: unknown[]) => void>();
applyTimelineStackingReorder({
element: el({ id: "track", tag: "audio" }),
stackingReorder: {
contextKey: "main",
placement: { type: "above", layerId: "layer:main:x" },
zIndexChanges: [{ key: "track", zIndex: 5, domId: "track" }],
},
timelineElements: [],
iframe,
activeCompPath: "index.html",
commit,
});
expect(commit).not.toHaveBeenCalled();
});
});
describe("extendRootDurationIfNeeded", () => {
it("extends the player duration only when the new end is larger", () => {
usePlayerStore.getState().setDuration(4);
expect(extendRootDurationIfNeeded(5)).toBe(true);
expect(usePlayerStore.getState().duration).toBe(5);
expect(extendRootDurationIfNeeded(5)).toBe(false);
expect(extendRootDurationIfNeeded(3)).toBe(false);
expect(usePlayerStore.getState().duration).toBe(5);
});
});
@@ -1,8 +1,121 @@
import type { TimelineElement } from "../player/store/playerStore";
import { type TimelineElement, usePlayerStore } from "../player/store/playerStore";
import { applyPatchByTarget, readAttributeByTarget } from "../utils/sourcePatcher";
import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
import {
formatTimelineAttributeNumber,
type TimelineStackingReorderIntent,
} from "../player/components/timelineEditing";
import { getElementZIndex } from "../player/lib/layerOrdering";
import { getTimelineElementIdentity } from "../player/lib/timelineElementHelpers";
import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
import { selectedKeyframePercentagesForElement } from "../utils/keyframeSelection";
import type { EditHistoryKind } from "../utils/editHistory";
import type { TimelineZIndexReorderCommit } from "./useTimelineEditingTypes";
import { extendRootDurationInSource } from "../utils/rootDuration";
function isHTMLElement(element: Element | null): element is HTMLElement {
if (!element) return false;
// Use the element's OWN realm's HTMLElement: timeline clips live in the preview
// iframe, and cross-realm `element instanceof HTMLElement` (main window) is
// always false — which silently dropped every timeline z-index commit.
const Ctor = element.ownerDocument?.defaultView?.HTMLElement ?? globalThis.HTMLElement;
return element instanceof Ctor;
}
/**
* Resolve a timeline vertical move to a z-index stacking reorder and commit it
* through the shared layers-panel reorder path. Reads live sibling z-index from
* the preview DOM, remaps with the dup-preserving reorder math, and writes only
* z-index (never data-track-index). No-op when the move isn't a reorder, the
* dragged clip is audio (no visual layer to restack), or the live siblings can't
* be resolved. Extracted from StudioApp's timeline hook to keep it under the
* studio 600-LOC cap.
*/
// fallow-ignore-next-line complexity
export function applyTimelineStackingReorder(input: {
element: TimelineElement;
stackingReorder: TimelineStackingReorderIntent | null | undefined;
timelineElements: readonly TimelineElement[];
iframe: HTMLIFrameElement | null;
activeCompPath: string | null;
commit: TimelineZIndexReorderCommit | null | undefined;
}): Promise<void> {
// Audio has no visual stacking; a vertical drag on it must never write z-index.
if (input.element.tag === "audio") return Promise.resolve();
const intent = input.stackingReorder ?? null;
if (intent == null || intent.zIndexChanges.length === 0) return Promise.resolve();
// Resolve each change's live element from the change's OWN locator (the intent
// is self-contained), falling back to the top-level element list. Sub-comp
// children aren't in `timelineElements`, so a list-only lookup would miss them.
const siblingByKey = new Map(
input.timelineElements.map((el) => [getTimelineElementIdentity(el), el]),
);
const doc = input.iframe?.contentDocument ?? null;
const findLive = (domId?: string, selector?: string, selectorIndex?: number): Element | null => {
if (!doc) return null;
if (domId) return doc.getElementById(domId);
if (selector) return doc.querySelectorAll(selector)[selectorIndex ?? 0] ?? null;
return null;
};
const commitEntries: Array<{
element: HTMLElement;
zIndex: number;
id?: string;
selector?: string;
selectorIndex?: number;
sourceFile: string;
key: string;
}> = [];
for (const change of intent.zIndexChanges) {
const sibling = siblingByKey.get(change.key);
const domId = change.domId ?? sibling?.domId;
const selector = change.selector ?? sibling?.selector;
const selectorIndex = change.selectorIndex ?? sibling?.selectorIndex;
const element = findLive(domId, selector, selectorIndex);
if (!isHTMLElement(element)) return Promise.resolve();
if (getElementZIndex(element) === change.zIndex) continue;
commitEntries.push({
element,
zIndex: change.zIndex,
id: domId ?? sibling?.id ?? change.key,
selector,
selectorIndex,
sourceFile: change.sourceFile ?? sibling?.sourceFile ?? input.activeCompPath ?? "index.html",
key: change.key,
});
}
if (commitEntries.length === 0) return Promise.resolve();
return input.commit?.(commitEntries) ?? Promise.resolve();
}
/**
* Remove the keyframes currently selected in the player store from the active
* element's GSAP animation. Reads selection lazily so it stays correct when
* invoked from a ref callback. Extracted from StudioApp to keep it under the
* studio 600-LOC cap.
*/
export function deleteSelectedKeyframes(session: {
selectedGsapAnimations: readonly { id: string; keyframes?: unknown }[];
handleGsapRemoveKeyframe: (animId: string, pct: number) => void;
}): void {
const { selectedKeyframes, selectedElementId } = usePlayerStore.getState();
const animation = session.selectedGsapAnimations.find((anim) => anim.keyframes);
if (!animation) return;
// Only the active element's keyframes; a stale cross-element selection must not delete here.
for (const pct of selectedKeyframePercentagesForElement(selectedKeyframes, selectedElementId)) {
session.handleGsapRemoveKeyframe(animation.id, pct);
}
}
export function extendRootDurationIfNeeded(newEnd: number): boolean {
const store = usePlayerStore.getState();
if (newEnd <= store.duration) return false;
store.setDuration(newEnd);
return true;
}
// ── Types ──
@@ -72,8 +185,25 @@ export function patchIframeDomTiming(
}
}
function postRootDurationToPreview(
iframe: HTMLIFrameElement | null,
durationSeconds: number,
): void {
const duration = Number(durationSeconds);
if (!Number.isFinite(duration) || duration <= 0) return;
iframe?.contentWindow?.postMessage(
{
source: "hf-parent",
type: "control",
action: "set-root-duration",
durationSeconds: duration,
},
"*",
);
}
// fallow-ignore-next-line complexity
export function resolveResizePlaybackStart(
function resolveResizePlaybackStart(
original: string,
target: PatchTarget,
element: TimelineElement,
@@ -99,6 +229,47 @@ export function resolveResizePlaybackStart(
};
}
export function buildTimelineMoveTimingPatch(
original: string,
target: PatchTarget,
start: number,
duration: number,
): string {
const patched = applyPatchByTarget(original, target, {
type: "attribute",
property: "start",
value: formatTimelineAttributeNumber(start),
});
return extendRootDurationInSource(patched, start + duration);
}
export function buildTimelineResizeTimingPatch(
original: string,
target: PatchTarget,
element: TimelineElement,
updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
): string {
const pbs = resolveResizePlaybackStart(original, target, element, updates);
let patched = applyPatchByTarget(original, target, {
type: "attribute",
property: "start",
value: formatTimelineAttributeNumber(updates.start),
});
patched = applyPatchByTarget(patched, target, {
type: "attribute",
property: "duration",
value: formatTimelineAttributeNumber(updates.duration),
});
if (pbs) {
patched = applyPatchByTarget(patched, target, {
type: "attribute",
property: pbs.attrName,
value: formatTimelineAttributeNumber(pbs.value),
});
}
return extendRootDurationInSource(patched, updates.start + updates.duration);
}
export interface PersistTimelineEditInput {
projectId: string;
element: TimelineElement;
@@ -158,6 +329,47 @@ export async function readFileContent(projectId: string, targetPath: string): Pr
return data.content;
}
export type GsapMutationStatus = { mutated: boolean };
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null;
}
function readMutationStatus(value: unknown): GsapMutationStatus {
if (!isRecord(value)) return { mutated: false };
return { mutated: value.mutated === true || value.changed === true };
}
function readMutationError(value: unknown, fallback: string): string {
if (isRecord(value) && typeof value.error === "string") return value.error;
return fallback;
}
export async function finishTimelineTimingFallback(input: {
iframe: HTMLIFrameElement | null;
needsExtension: boolean;
rootDurationSeconds: number;
reloadPreview: () => void;
gsapMutation?: () => Promise<GsapMutationStatus>;
onGsapError: (error: unknown) => void;
}): Promise<void> {
let gsapMutated = false;
if (input.gsapMutation) {
try {
gsapMutated = (await input.gsapMutation()).mutated;
} catch (error) {
input.onGsapError(error);
return;
}
}
if (input.needsExtension) {
postRootDurationToPreview(input.iframe, input.rootDurationSeconds);
if (gsapMutated) input.reloadPreview();
return;
}
input.reloadPreview();
}
/**
* Shift all GSAP animation positions targeting a given element by a time delta.
* Calls the server-side GSAP mutation endpoint which uses the AST-based parser.
@@ -167,8 +379,8 @@ export async function shiftGsapPositions(
filePath: string,
elementId: string,
delta: number,
): Promise<void> {
if (delta === 0 || !elementId) return;
): Promise<GsapMutationStatus> {
if (delta === 0 || !elementId) return { mutated: false };
const res = await fetch(
`/api/projects/${projectId}/gsap-mutations/${encodeURIComponent(filePath)}`,
{
@@ -183,8 +395,9 @@ export async function shiftGsapPositions(
);
if (!res.ok) {
const err = await res.json().catch(() => null);
throw new Error((err as { error?: string })?.error ?? "shift-positions failed");
throw new Error(readMutationError(err, "shift-positions failed"));
}
return readMutationStatus(await res.json().catch(() => null));
}
export async function scaleGsapPositions(
@@ -195,9 +408,9 @@ export async function scaleGsapPositions(
oldDuration: number,
newStart: number,
newDuration: number,
): Promise<void> {
if (!elementId || oldDuration <= 0 || newDuration <= 0) return;
if (oldStart === newStart && oldDuration === newDuration) return;
): Promise<GsapMutationStatus> {
if (!elementId || oldDuration <= 0 || newDuration <= 0) return { mutated: false };
if (oldStart === newStart && oldDuration === newDuration) return { mutated: false };
const res = await fetch(
`/api/projects/${projectId}/gsap-mutations/${encodeURIComponent(filePath)}`,
{
@@ -215,8 +428,9 @@ export async function scaleGsapPositions(
);
if (!res.ok) {
const err = await res.json().catch(() => null);
throw new Error((err as { error?: string })?.error ?? "scale-positions failed");
throw new Error(readMutationError(err, "scale-positions failed"));
}
return readMutationStatus(await res.json().catch(() => null));
}
// Re-export applyPatchByTarget for use in the hook (avoids double import in callers)
@@ -160,6 +160,7 @@ export function useElementLifecycleOps({
// persistDomEditOperations → onTrySdkPersist, so it is already SDK-cut-over as setStyle.
// No SDK reorder/reparent op exists; DOM sibling order stays server-authoritative if ever needed.
const handleDomZIndexReorderCommit = useCallback(
// fallow-ignore-next-line complexity
(
entries: Array<{
element: HTMLElement;
@@ -168,17 +169,26 @@ export function useElementLifecycleOps({
selector?: string;
selectorIndex?: number;
sourceFile: string;
key?: string;
}>,
) => {
if (entries.length === 0) return;
if (entries.length === 0) return Promise.resolve();
// Resolver shadow (telemetry-only, decoupled from cutover): record whether
// the SDK resolves each reordered element — the reorderElements op's targets.
onReorderShadow?.(
entries.map((e) => readHfId(e.element)).filter((id): id is string => id != null),
);
const coalesceKey = `z-reorder:${entries.map((e) => e.id ?? e.selector ?? e.element.getAttribute("data-hf-id") ?? "el").join(":")}`;
const saves: Array<Promise<void>> = [];
const rollbacks: Array<() => void> = [];
for (let i = 0; i < entries.length; i++) {
const entry = entries[i];
const priorZIndex = entry.element.style.zIndex;
const priorPosition = entry.element.style.position;
const priorStoreEntry = entry.key
? usePlayerStore.getState().elements.find((el) => (el.key ?? el.id) === entry.key)
: undefined;
let positionChanged = false;
entry.element.style.zIndex = String(entry.zIndex);
const patches: Array<{ type: "inline-style"; property: string; value: string }> = [
{ type: "inline-style", property: "z-index", value: String(entry.zIndex) },
@@ -187,28 +197,58 @@ export function useElementLifecycleOps({
const win = entry.element.ownerDocument?.defaultView;
if (win && win.getComputedStyle(entry.element).position === "static") {
entry.element.style.position = "relative";
positionChanged = true;
patches.push({ type: "inline-style", property: "position", value: "relative" });
}
} catch {
/* cross-origin or detached — skip */
}
void commitPositionPatchToHtml(
{
element: entry.element,
id: entry.id ?? null,
hfId: readHfId(entry.element),
selector: entry.selector,
selectorIndex: entry.selectorIndex,
sourceFile: entry.sourceFile,
} as unknown as DomEditSelection,
patches,
{
label: "Reorder layers",
coalesceKey,
skipRefresh: i < entries.length - 1,
},
).catch(() => undefined);
if (entry.key) {
usePlayerStore
.getState()
.updateElement(entry.key, { zIndex: entry.zIndex, hasExplicitZIndex: true });
}
rollbacks.push(() => {
entry.element.style.zIndex = priorZIndex;
if (positionChanged) entry.element.style.position = priorPosition;
if (entry.key && priorStoreEntry) {
usePlayerStore.getState().updateElement(entry.key, {
zIndex: priorStoreEntry.zIndex,
hasExplicitZIndex: priorStoreEntry.hasExplicitZIndex,
});
}
});
saves.push(
commitPositionPatchToHtml(
{
element: entry.element,
id: entry.id ?? null,
hfId: readHfId(entry.element),
selector: entry.selector,
selectorIndex: entry.selectorIndex,
sourceFile: entry.sourceFile,
} as unknown as DomEditSelection,
patches,
{
label: "Reorder layers",
coalesceKey,
skipRefresh: i < entries.length - 1,
},
),
);
}
// Resolves once every z-index patch is persisted so a same-file timing write
// can be ordered after it (see applyTimelineStackingReorder callers).
return Promise.allSettled(saves).then((settled) => {
const rejected = settled.find(
(result): result is PromiseRejectedResult => result.status === "rejected",
);
if (rejected) {
for (const rollback of rollbacks) rollback();
return Promise.reject(rejected.reason);
}
return undefined;
});
},
[commitPositionPatchToHtml, onReorderShadow],
);
@@ -0,0 +1,742 @@
// @vitest-environment happy-dom
import React, { act, useRef } from "react";
import { createRoot } from "react-dom/client";
import { openComposition } from "@hyperframes/sdk";
import { afterEach, describe, expect, it, vi } from "vitest";
import { usePlayerStore, type TimelineElement } from "../player";
import { useElementLifecycleOps } from "./useElementLifecycleOps";
import { useTimelineEditing } from "./useTimelineEditing";
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
type ZIndexEntry = {
element: HTMLElement;
zIndex: number;
id?: string;
selector?: string;
selectorIndex?: number;
sourceFile: string;
};
afterEach(() => {
document.body.innerHTML = "";
usePlayerStore.getState().reset();
vi.restoreAllMocks();
vi.unstubAllGlobals();
});
function createPreviewIframe(
clips: Array<{
id: string;
track: number;
style?: string;
}> = [
{ id: "front", track: 0 },
{ id: "back", track: 1 },
],
): HTMLIFrameElement {
const iframe = document.createElement("iframe");
document.body.append(iframe);
const doc = iframe.contentDocument;
if (!doc) throw new Error("Expected iframe document");
doc.body.innerHTML = clips
.map(
(clip) =>
`<div id="${clip.id}" data-start="0" data-duration="2" data-track-index="${clip.track}"${
clip.style ? ` style="${clip.style}"` : ""
}></div>`,
)
.join("\n");
return iframe;
}
function timelineElement(input: {
id: string;
track: number;
zIndex: number;
tag?: string;
}): TimelineElement {
return {
id: input.id,
domId: input.id,
hfId: `hf-${input.id}`,
tag: input.tag ?? "div",
start: 0,
duration: 2,
track: input.track,
zIndex: input.zIndex,
stackingContextId: "root",
parentCompositionId: null,
compositionAncestors: ["root"],
sourceFile: "index.html",
timingSource: "authored",
};
}
function renderTimelineEditingHook(input: {
timelineElements: TimelineElement[];
iframe: HTMLIFrameElement;
onZIndexCommit: (entries: ZIndexEntry[]) => Promise<void>;
projectId?: string | null;
writeProjectFile?: (path: string, content: string) => Promise<void>;
recordEdit?: (input: {
label: string;
kind: string;
coalesceKey?: string;
files: Record<string, { before: string; after: string }>;
}) => Promise<void>;
reloadPreview?: () => void;
sdkSession?: Awaited<ReturnType<typeof openComposition>> | null;
forceReloadSdkSession?: () => void;
}): {
move: ReturnType<typeof useTimelineEditing>["handleTimelineElementMove"];
resize: ReturnType<typeof useTimelineEditing>["handleTimelineElementResize"];
unmount: () => void;
} {
let move: ReturnType<typeof useTimelineEditing>["handleTimelineElementMove"] | null = null;
let resize: ReturnType<typeof useTimelineEditing>["handleTimelineElementResize"] | null = null;
function Harness() {
const commitRef = useRef(input.onZIndexCommit);
commitRef.current = input.onZIndexCommit;
const hook = useTimelineEditing({
projectId: input.projectId ?? null,
activeCompPath: "index.html",
timelineElements: input.timelineElements,
showToast: vi.fn(),
writeProjectFile: input.writeProjectFile ?? vi.fn(),
recordEdit: input.recordEdit ?? vi.fn(),
domEditSaveTimestampRef: { current: 0 },
reloadPreview: input.reloadPreview ?? vi.fn(),
previewIframeRef: { current: input.iframe },
pendingTimelineEditPathRef: { current: new Set<string>() },
uploadProjectFiles: vi.fn(),
sdkSession: input.sdkSession,
forceReloadSdkSession: input.forceReloadSdkSession,
handleDomZIndexReorderCommitRef: commitRef,
});
move = hook.handleTimelineElementMove;
resize = hook.handleTimelineElementResize;
return null;
}
const host = document.createElement("div");
document.body.append(host);
const root = createRoot(host);
act(() => {
root.render(<Harness />);
});
if (!move) throw new Error("Expected hook to expose move handler");
if (!resize) throw new Error("Expected hook to expose resize handler");
return {
move,
resize,
unmount: () => {
act(() => root.unmount());
},
};
}
function renderTimelineEditingHookWithLifecycle(input: {
timelineElements: TimelineElement[];
iframe: HTMLIFrameElement;
commitPositionPatchToHtml: ReturnType<typeof vi.fn<(...args: unknown[]) => Promise<void>>>;
}): {
move: ReturnType<typeof useTimelineEditing>["handleTimelineElementMove"];
unmount: () => void;
} {
let move: ReturnType<typeof useTimelineEditing>["handleTimelineElementMove"] | null = null;
function Harness() {
const lifecycle = useElementLifecycleOps({
activeCompPath: "index.html",
showToast: vi.fn(),
writeProjectFile: vi.fn(),
domEditSaveTimestampRef: { current: 0 },
editHistory: { recordEdit: vi.fn() },
projectIdRef: { current: "p1" },
reloadPreview: vi.fn(),
clearDomSelection: vi.fn(),
commitPositionPatchToHtml: input.commitPositionPatchToHtml,
});
const commitRef = useRef(lifecycle.handleDomZIndexReorderCommit);
commitRef.current = lifecycle.handleDomZIndexReorderCommit;
const hook = useTimelineEditing({
projectId: null,
activeCompPath: "index.html",
timelineElements: input.timelineElements,
showToast: vi.fn(),
writeProjectFile: vi.fn(),
recordEdit: vi.fn(),
domEditSaveTimestampRef: { current: 0 },
reloadPreview: vi.fn(),
previewIframeRef: { current: input.iframe },
pendingTimelineEditPathRef: { current: new Set<string>() },
uploadProjectFiles: vi.fn(),
handleDomZIndexReorderCommitRef: commitRef,
});
move = hook.handleTimelineElementMove;
return null;
}
const host = document.createElement("div");
document.body.append(host);
const root = createRoot(host);
act(() => {
root.render(<Harness />);
});
if (!move) throw new Error("Expected hook to expose move handler");
return {
move,
unmount: () => {
act(() => root.unmount());
},
};
}
function jsonResponse(body: unknown): Response {
return new Response(JSON.stringify(body), {
status: 200,
headers: { "content-type": "application/json" },
});
}
function requestUrl(input: Parameters<typeof fetch>[0]): string {
if (typeof input === "string") return input;
if (input instanceof URL) return input.toString();
return input.url;
}
async function flushAsyncWork(): Promise<void> {
for (let i = 0; i < 8; i += 1) {
await Promise.resolve();
}
}
describe("useTimelineEditing timeline z-index reorder", () => {
it("extends root duration through the fallback path when an SDK-backed move passes the end", async () => {
const source = [
`<div data-composition-id="main" data-duration="4">`,
` <div id="clip" data-hf-id="hf-clip" data-start="0" data-duration="2"></div>`,
`</div>`,
].join("\n");
const iframe = createPreviewIframe([{ id: "clip", track: 0 }]);
const clip = timelineElement({ id: "clip", track: 0, zIndex: 0 });
const sdkSession = await openComposition(source);
const setTimingSpy = vi.spyOn(sdkSession, "setTiming");
const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
const recordEdit = vi.fn(async () => {});
const forceReloadSdkSession = vi.fn();
const reloadPreview = vi.fn();
const iframeWindow = iframe.contentWindow;
if (!iframeWindow) throw new Error("Expected iframe window");
const postMessageSpy = vi.spyOn(iframeWindow, "postMessage");
vi.stubGlobal(
"fetch",
vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
const url = requestUrl(input);
if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: source });
if (url.includes("/api/projects/p1/gsap-mutations/")) {
return jsonResponse({ ok: true, mutated: false });
}
throw new Error(`Unexpected fetch: ${url}`);
}),
);
usePlayerStore.getState().setDuration(4);
const { move, unmount } = renderTimelineEditingHook({
timelineElements: [clip],
iframe,
onZIndexCommit: vi.fn().mockResolvedValue(undefined),
projectId: "p1",
writeProjectFile,
recordEdit,
sdkSession,
forceReloadSdkSession,
reloadPreview,
});
await act(async () => {
await move(clip, { start: 3, track: clip.track });
});
expect(setTimingSpy).not.toHaveBeenCalled();
expect(writeProjectFile.mock.calls[0]![1]).toContain(
'data-composition-id="main" data-duration="5"',
);
expect(writeProjectFile.mock.calls[0]![1]).toContain('data-start="3"');
expect(usePlayerStore.getState().duration).toBe(5);
expect(forceReloadSdkSession).toHaveBeenCalledTimes(1);
expect(reloadPreview).not.toHaveBeenCalled();
expect(postMessageSpy).toHaveBeenCalledWith(
{
source: "hf-parent",
type: "control",
action: "set-root-duration",
durationSeconds: 5,
},
"*",
);
unmount();
});
it("extends root duration through the fallback path when an SDK-backed resize passes the end", async () => {
const source = [
`<div data-composition-id="main" data-duration="4">`,
` <div id="clip" data-hf-id="hf-clip" data-start="0" data-duration="2"></div>`,
`</div>`,
].join("\n");
const iframe = createPreviewIframe([{ id: "clip", track: 0 }]);
const clip = timelineElement({ id: "clip", track: 0, zIndex: 0 });
const sdkSession = await openComposition(source);
const setTimingSpy = vi.spyOn(sdkSession, "setTiming");
const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
const recordEdit = vi.fn(async () => {});
const forceReloadSdkSession = vi.fn();
const reloadPreview = vi.fn();
const iframeWindow = iframe.contentWindow;
if (!iframeWindow) throw new Error("Expected iframe window");
const postMessageSpy = vi.spyOn(iframeWindow, "postMessage");
vi.stubGlobal(
"fetch",
vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
const url = requestUrl(input);
if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: source });
if (url.includes("/api/projects/p1/gsap-mutations/")) {
return jsonResponse({ ok: true, mutated: false });
}
throw new Error(`Unexpected fetch: ${url}`);
}),
);
usePlayerStore.getState().setDuration(4);
const { resize, unmount } = renderTimelineEditingHook({
timelineElements: [clip],
iframe,
onZIndexCommit: vi.fn().mockResolvedValue(undefined),
projectId: "p1",
writeProjectFile,
recordEdit,
sdkSession,
forceReloadSdkSession,
reloadPreview,
});
await act(async () => {
await resize(clip, { start: 0, duration: 5, playbackStart: undefined });
});
expect(setTimingSpy).not.toHaveBeenCalled();
expect(writeProjectFile.mock.calls[0]![1]).toContain(
'data-composition-id="main" data-duration="5"',
);
expect(writeProjectFile.mock.calls[0]![1]).toContain('data-duration="5"></div>');
expect(usePlayerStore.getState().duration).toBe(5);
expect(forceReloadSdkSession).toHaveBeenCalledTimes(1);
expect(reloadPreview).not.toHaveBeenCalled();
expect(postMessageSpy).toHaveBeenCalledWith(
{
source: "hf-parent",
type: "control",
action: "set-root-duration",
durationSeconds: 5,
},
"*",
);
unmount();
});
it("routes a vertical drag through the shared z-index commit without writing track-index", async () => {
const iframe = createPreviewIframe([
{ id: "front", track: 0, style: "position: relative; z-index: 10" },
{ id: "back", track: 2, style: "position: relative; z-index: 1" },
]);
const front = timelineElement({ id: "front", track: 0, zIndex: 10 });
const back = timelineElement({ id: "back", track: 2, zIndex: 1 });
const commit = vi.fn<(entries: ZIndexEntry[]) => Promise<void>>().mockResolvedValue(undefined);
const { move, unmount } = renderTimelineEditingHook({
timelineElements: [front, back],
iframe,
onZIndexCommit: commit,
});
await act(async () => {
await move(back, {
start: back.start,
track: back.track,
stackingReorder: {
contextKey: "root",
placement: { type: "onto", layerId: "layer-front" },
zIndexChanges: [{ key: "back", zIndex: 10 }],
},
});
});
const doc = iframe.contentDocument;
if (!doc) throw new Error("Expected iframe document");
expect(commit).toHaveBeenCalledTimes(1);
expect(commit.mock.calls[0]![0].map((entry) => [entry.id, entry.zIndex])).toEqual([
["back", 10],
]);
expect(doc.getElementById("back")?.getAttribute("data-track-index")).toBe("2");
unmount();
});
it("never writes z-index when the dragged clip is audio (no visual layer)", async () => {
const iframe = createPreviewIframe([
{ id: "front", track: 0 },
{ id: "music", track: 1 },
]);
const front = timelineElement({ id: "front", track: 0, zIndex: 0 });
const music = timelineElement({ id: "music", track: 1, zIndex: 0, tag: "audio" });
const commit = vi.fn<(entries: ZIndexEntry[]) => Promise<void>>().mockResolvedValue(undefined);
const { move, unmount } = renderTimelineEditingHook({
timelineElements: [front, music],
iframe,
onZIndexCommit: commit,
});
await act(async () => {
await move(music, {
start: music.start,
track: music.track,
stackingReorder: {
contextKey: "root",
placement: { type: "onto", layerId: "layer-front" },
zIndexChanges: [{ key: "music", zIndex: 2 }],
},
});
});
expect(commit).not.toHaveBeenCalled();
unmount();
});
it("commits only the minimum z-index changes resolved by the timeline drag", async () => {
const iframe = createPreviewIframe([
{ id: "front", track: 0, style: "position: relative; z-index: 2" },
{ id: "back", track: 1, style: "position: relative; z-index: 1" },
{ id: "dragged", track: 2, style: "position: relative; z-index: 0" },
]);
const front = timelineElement({ id: "front", track: 0, zIndex: 2 });
const back = timelineElement({ id: "back", track: 1, zIndex: 1 });
const dragged = timelineElement({ id: "dragged", track: 2, zIndex: 0 });
const commit = vi.fn<(entries: ZIndexEntry[]) => Promise<void>>().mockResolvedValue(undefined);
const { move, unmount } = renderTimelineEditingHook({
timelineElements: [front, back, dragged],
iframe,
onZIndexCommit: commit,
});
await act(async () => {
await move(dragged, {
start: dragged.start,
track: dragged.track,
stackingReorder: {
contextKey: "root",
placement: { type: "between", beforeLayerId: "front", afterLayerId: "back" },
zIndexChanges: [
{ key: "dragged", zIndex: 2 },
{ key: "front", zIndex: 3 },
],
},
});
});
expect(commit.mock.calls[0]![0].map((entry) => [entry.id, entry.zIndex])).toEqual([
["dragged", 2],
["front", 3],
]);
unmount();
});
it("uses the shared lifecycle commit so static clips receive position relative", async () => {
const iframe = createPreviewIframe([
{ id: "front", track: 0, style: "position: static" },
{ id: "back", track: 1, style: "position: static" },
]);
const front = timelineElement({ id: "front", track: 0, zIndex: 0 });
const back = timelineElement({ id: "back", track: 1, zIndex: 0 });
const commitPositionPatchToHtml = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
const { move, unmount } = renderTimelineEditingHookWithLifecycle({
timelineElements: [front, back],
iframe,
commitPositionPatchToHtml,
});
await act(async () => {
await move(back, {
start: back.start,
track: back.track,
stackingReorder: {
contextKey: "root",
placement: { type: "above", layerId: "front" },
zIndexChanges: [{ key: "back", zIndex: 2 }],
},
});
await flushAsyncWork();
});
expect(commitPositionPatchToHtml).toHaveBeenCalled();
expect(commitPositionPatchToHtml.mock.calls[0]![1]).toEqual([
{ type: "inline-style", property: "z-index", value: "2" },
{ type: "inline-style", property: "position", value: "relative" },
]);
unmount();
});
it("rejects and rolls back DOM and store z-index changes when a reorder save fails", async () => {
const iframe = createPreviewIframe([
{ id: "front", track: 0, style: "position: relative; z-index: 7" },
{ id: "back", track: 1, style: "position: static" },
]);
const front = timelineElement({ id: "front", track: 0, zIndex: 7 });
const back = timelineElement({ id: "back", track: 1, zIndex: 0 });
usePlayerStore.getState().setElements([
{ ...front, hasExplicitZIndex: true },
{ ...back, hasExplicitZIndex: false },
]);
const saveError = new Error("save failed");
const commitPositionPatchToHtml = vi
.fn<(...args: unknown[]) => Promise<void>>()
.mockResolvedValueOnce(undefined)
.mockRejectedValueOnce(saveError);
const { move, unmount } = renderTimelineEditingHookWithLifecycle({
timelineElements: [front, back],
iframe,
commitPositionPatchToHtml,
});
const doc = iframe.contentDocument;
if (!doc) throw new Error("Expected iframe document");
const frontElement = doc.getElementById("front") as HTMLElement | null;
const backElement = doc.getElementById("back") as HTMLElement | null;
if (!frontElement || !backElement) throw new Error("Expected reordered elements");
let rejection: unknown;
await act(async () => {
try {
await move(back, {
start: back.start,
track: back.track,
stackingReorder: {
contextKey: "root",
placement: { type: "above", layerId: "front" },
zIndexChanges: [
{ key: "front", zIndex: 2 },
{ key: "back", zIndex: 5 },
],
},
});
} catch (error) {
rejection = error;
}
await flushAsyncWork();
});
expect(rejection).toBe(saveError);
expect(frontElement.style.zIndex).toBe("7");
expect(frontElement.style.position).toBe("relative");
expect(backElement.style.zIndex).toBe("");
expect(backElement.style.position).toBe("static");
const storeEntries = usePlayerStore.getState().elements;
expect(storeEntries.find((entry) => entry.id === "front")).toMatchObject({
zIndex: 7,
hasExplicitZIndex: true,
});
expect(storeEntries.find((entry) => entry.id === "back")).toMatchObject({
zIndex: 0,
hasExplicitZIndex: false,
});
unmount();
});
it("waits for every lifecycle z-index save before resolving a reorder", async () => {
const iframe = createPreviewIframe([
{ id: "front", track: 0, style: "position: relative; z-index: 1" },
{ id: "back", track: 1, style: "position: relative; z-index: 0" },
]);
const front = timelineElement({ id: "front", track: 0, zIndex: 1 });
const back = timelineElement({ id: "back", track: 1, zIndex: 0 });
let releaseFirst!: () => void;
let releaseSecond!: () => void;
const firstSave = new Promise<void>((resolve) => {
releaseFirst = resolve;
});
const secondSave = new Promise<void>((resolve) => {
releaseSecond = resolve;
});
const commitPositionPatchToHtml = vi
.fn<(...args: unknown[]) => Promise<void>>()
.mockReturnValueOnce(firstSave)
.mockReturnValueOnce(secondSave);
const { move, unmount } = renderTimelineEditingHookWithLifecycle({
timelineElements: [front, back],
iframe,
commitPositionPatchToHtml,
});
let settled = false;
let movePromise!: Promise<void>;
await act(async () => {
movePromise = move(back, {
start: back.start,
track: back.track,
stackingReorder: {
contextKey: "root",
placement: { type: "above", layerId: "front" },
zIndexChanges: [
{ key: "front", zIndex: 2 },
{ key: "back", zIndex: 3 },
],
},
}).then(() => {
settled = true;
});
await flushAsyncWork();
});
expect(commitPositionPatchToHtml).toHaveBeenCalledTimes(2);
expect(settled).toBe(false);
await act(async () => {
releaseFirst();
await flushAsyncWork();
});
expect(settled).toBe(false);
await act(async () => {
releaseSecond();
await movePromise;
await flushAsyncWork();
});
expect(settled).toBe(true);
unmount();
});
it("keeps horizontal-only drag on the timing and GSAP shift path without z-index writes", async () => {
const iframe = createPreviewIframe([{ id: "clip", track: 0 }]);
const clip = timelineElement({ id: "clip", track: 0, zIndex: 0 });
const commit = vi.fn<(entries: ZIndexEntry[]) => Promise<void>>().mockResolvedValue(undefined);
const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
const recordEdit = vi.fn(async () => {});
const reloadPreview = vi.fn();
const fetchMock = vi.fn(
async (
input: Parameters<typeof fetch>[0],
_init?: Parameters<typeof fetch>[1],
): Promise<Response> => {
const url = requestUrl(input);
if (url.includes("/api/projects/p1/files/")) {
return jsonResponse({
content: '<div id="clip" data-start="0" data-track-index="0"></div>',
});
}
if (url.includes("/api/projects/p1/gsap-mutations/")) {
return jsonResponse({ ok: true });
}
throw new Error(`Unexpected fetch: ${url}`);
},
);
vi.stubGlobal("fetch", fetchMock);
const { move, unmount } = renderTimelineEditingHook({
timelineElements: [clip],
iframe,
onZIndexCommit: commit,
projectId: "p1",
writeProjectFile,
recordEdit,
reloadPreview,
});
await act(async () => {
await move(clip, { start: 1.25, track: clip.track });
});
const doc = iframe.contentDocument;
if (!doc) throw new Error("Expected iframe document");
expect(doc.getElementById("clip")?.getAttribute("data-start")).toBe("1.25");
expect(doc.getElementById("clip")?.getAttribute("data-track-index")).toBe("0");
expect(commit).not.toHaveBeenCalled();
expect(writeProjectFile.mock.calls[0]![1]).toContain('data-start="1.25"');
expect(writeProjectFile.mock.calls[0]![1]).toContain('data-track-index="0"');
expect(writeProjectFile.mock.calls[0]![1]).not.toContain("z-index");
expect(
fetchMock.mock.calls.some((call) => requestUrl(call[0]).includes("gsap-mutations")),
).toBe(true);
unmount();
});
it("orders the timing write after the z-index commit so a diagonal drag can't clobber the restack", async () => {
const iframe = createPreviewIframe([
{ id: "clip", track: 0, style: "position: relative; z-index: 0" },
]);
const clip = timelineElement({ id: "clip", track: 0, zIndex: 0 });
// Gate the z-index commit so we can observe whether the timing write waits.
let releaseCommit!: () => void;
const commitGate = new Promise<void>((resolve) => {
releaseCommit = resolve;
});
const commit = vi.fn<(entries: ZIndexEntry[]) => Promise<void>>().mockReturnValue(commitGate);
const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
const url = requestUrl(input);
if (url.includes("/api/projects/p1/files/")) {
return jsonResponse({
content: '<div id="clip" data-start="0" data-track-index="0"></div>',
});
}
if (url.includes("/api/projects/p1/gsap-mutations/")) return jsonResponse({ ok: true });
throw new Error(`Unexpected fetch: ${url}`);
});
vi.stubGlobal("fetch", fetchMock);
const { move, unmount } = renderTimelineEditingHook({
timelineElements: [clip],
iframe,
onZIndexCommit: commit,
projectId: "p1",
writeProjectFile,
recordEdit: vi.fn(async () => {}),
});
// Diagonal drag: both a time move (start change) and a restack (z-index change).
let movePromise!: Promise<unknown>;
await act(async () => {
movePromise = move(clip, {
start: 1.25,
track: clip.track,
stackingReorder: {
contextKey: "root",
placement: { type: "onto", layerId: "layer-clip" },
zIndexChanges: [{ key: "clip", zIndex: 5 }],
},
});
await flushAsyncWork();
});
// The z-index commit is in flight but gated; the full-file timing write must
// not have run yet, or it would overwrite the file without the z-index change.
expect(commit).toHaveBeenCalledTimes(1);
expect(writeProjectFile).not.toHaveBeenCalled();
// Release the z-index commit → the timing write now proceeds, on top of it.
await act(async () => {
releaseCommit();
await movePromise;
await flushAsyncWork();
});
expect(writeProjectFile).toHaveBeenCalled();
unmount();
});
});
+102 -87
View File
@@ -21,17 +21,21 @@ import {
resolveDroppedAssetDuration,
} from "../utils/studioHelpers";
import {
applyTimelineStackingReorder,
buildPatchTarget,
patchIframeDomTiming,
resolveResizePlaybackStart,
persistTimelineEdit,
readFileContent,
applyPatchByTarget,
formatTimelineAttributeNumber,
shiftGsapPositions,
scaleGsapPositions,
finishTimelineTimingFallback,
extendRootDurationIfNeeded,
buildTimelineMoveTimingPatch,
buildTimelineResizeTimingPatch,
} from "./timelineEditingHelpers";
import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
import type { TimelineStackingReorderIntent } from "../player/components/timelineEditing";
import {
useTimelineElementVisibilityEditing,
useTimelineTrackVisibilityEditing,
@@ -39,6 +43,10 @@ import {
import { sdkTimingPersist } from "../utils/sdkCutover";
import type { UseTimelineEditingOptions } from "./useTimelineEditingTypes";
type TimelineMoveUpdates = Pick<TimelineElement, "start" | "track"> & {
stackingReorder?: TimelineStackingReorderIntent | null;
};
// ── Hook ──
export function useTimelineEditing({
@@ -56,6 +64,7 @@ export function useTimelineEditing({
isRecordingRef,
sdkSession,
forceReloadSdkSession,
handleDomZIndexReorderCommitRef,
}: UseTimelineEditingOptions) {
const projectIdRef = useRef(projectId);
projectIdRef.current = projectId;
@@ -115,64 +124,80 @@ export function useTimelineEditing({
// fallow-ignore-next-line complexity
const handleTimelineElementMove = useCallback(
// fallow-ignore-next-line complexity
(element: TimelineElement, updates: Pick<TimelineElement, "start" | "track">) => {
patchIframeDomTiming(previewIframeRef.current, element, [
["data-start", formatTimelineAttributeNumber(updates.start)],
["data-track-index", String(updates.track)],
]);
(element: TimelineElement, updates: TimelineMoveUpdates) => {
const targetPath = element.sourceFile || activeCompPath || "index.html";
const startChanged = updates.start !== element.start;
if (startChanged) {
patchIframeDomTiming(previewIframeRef.current, element, [
["data-start", formatTimelineAttributeNumber(updates.start)],
]);
}
const reorderDone = applyTimelineStackingReorder({
element,
stackingReorder: updates.stackingReorder,
timelineElements,
iframe: previewIframeRef.current,
activeCompPath,
commit: handleDomZIndexReorderCommitRef?.current,
});
if (!startChanged) return reorderDone;
const buildMovePatches: PersistTimelineEditInput["buildPatches"] = (original, target) => {
let patched = applyPatchByTarget(original, target, {
type: "attribute",
property: "start",
value: formatTimelineAttributeNumber(updates.start),
});
return applyPatchByTarget(patched, target, {
type: "attribute",
property: "track-index",
value: String(updates.track),
});
return buildTimelineMoveTimingPatch(original, target, updates.start, element.duration);
};
// Server-path fallback (no SDK session): persist the attr patch, then
// shift GSAP tween positions on the server and reload the preview — the
// SDK path folds both into setTiming, but the fallback must do them
// explicitly or the clip moves while its GSAP tweens stay put + the
// preview never refreshes. coalesceKey mirrors the SDK branch so undo
// granularity is identical on either path.
// shift GSAP tween positions on the server. Extending edits can keep the
// iframe live unless a GSAP source rewrite needs a fresh run.
const coalesceKey = `timeline-move:${element.hfId ?? element.id}`;
const moveFallback = () =>
enqueueEdit(element, "Move timeline clip", buildMovePatches, coalesceKey).then(() => {
const pid = projectIdRef.current;
const delta = updates.start - element.start;
if (delta !== 0 && element.domId && pid) {
return shiftGsapPositions(pid, targetPath, element.domId, delta)
.then(() => reloadPreview())
.catch((err) => console.error("[Timeline] Failed to shift GSAP positions", err));
}
return reloadPreview();
});
if (sdkSession && element.hfId) {
return sdkTimingPersist(
element.hfId,
targetPath,
{ start: updates.start, trackIndex: updates.track },
sdkSession,
{
editHistory: { recordEdit },
writeProjectFile,
const domId = element.domId;
return finishTimelineTimingFallback({
iframe: previewIframeRef.current,
needsExtension,
rootDurationSeconds: updates.start + element.duration,
reloadPreview,
domEditSaveTimestampRef,
compositionPath: activeCompPath,
// Capture on-disk bytes as the undo `before` so undoing a timing move
// restores the file verbatim, not a normalized full-DOM re-emit.
readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
},
{ label: "Move timeline clip", coalesceKey },
).then((handled) => {
if (!handled) return moveFallback();
gsapMutation:
delta !== 0 && domId && pid
? () => shiftGsapPositions(pid, targetPath, domId, delta)
: undefined,
onGsapError: (err) => console.error("[Timeline] Failed to shift GSAP positions", err),
});
});
}
return moveFallback();
const needsExtension = extendRootDurationIfNeeded(updates.start + element.duration);
// The z-index reorder above and this timing write target the same file on
// separate save queues, and the timing write is a full-file overwrite. Order
// it after the reorder so it reads disk with the z-index already applied and
// can't clobber it — one ordered writer per gesture (diagonal move+restack).
return reorderDone.then(() => {
if (sdkSession && element.hfId && !needsExtension) {
return sdkTimingPersist(
element.hfId,
targetPath,
{ start: updates.start },
sdkSession,
{
editHistory: { recordEdit },
writeProjectFile,
reloadPreview,
domEditSaveTimestampRef,
compositionPath: activeCompPath,
// Capture on-disk bytes as the undo `before` so undoing a timing move
// restores the file verbatim, not a normalized full-DOM re-emit.
readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
},
{ label: "Move timeline clip", coalesceKey },
).then((handled) => {
if (!handled) return moveFallback();
});
}
return moveFallback();
});
},
[
previewIframeRef,
@@ -183,6 +208,8 @@ export function useTimelineEditing({
writeProjectFile,
reloadPreview,
domEditSaveTimestampRef,
timelineElements,
handleDomZIndexReorderCommitRef,
],
);
@@ -210,25 +237,7 @@ export function useTimelineEditing({
patchIframeDomTiming(previewIframeRef.current, element, liveAttrs);
const targetPath = element.sourceFile || activeCompPath || "index.html";
const buildResizePatches: PersistTimelineEditInput["buildPatches"] = (original, target) => {
const pbs = resolveResizePlaybackStart(original, target, element, updates);
let patched = applyPatchByTarget(original, target, {
type: "attribute",
property: "start",
value: formatTimelineAttributeNumber(updates.start),
});
patched = applyPatchByTarget(patched, target, {
type: "attribute",
property: "duration",
value: formatTimelineAttributeNumber(updates.duration),
});
if (pbs) {
patched = applyPatchByTarget(patched, target, {
type: "attribute",
property: pbs.attrName,
value: formatTimelineAttributeNumber(pbs.value),
});
}
return patched;
return buildTimelineResizeTimingPatch(original, target, element, updates);
};
// SDK path: skip when a playback-start adjustment is needed (setTiming has no pbs field).
// The second clause fires because trimming the start of a clip that has a
@@ -238,32 +247,38 @@ export function useTimelineEditing({
updates.playbackStart != null ||
(updates.start !== element.start && element.playbackStart != null);
// Server-path fallback: after persisting the attr patch, scale GSAP tween
// positions/durations on the server and reload the preview. The SDK path
// folds both into setTiming; the fallback must do them explicitly or the
// clip resizes while its GSAP tweens keep their old timing + the preview
// never refreshes. coalesceKey mirrors the SDK branch for undo parity.
// positions/durations on the server. Extending edits can keep the iframe
// live unless a GSAP source rewrite needs a fresh run.
const coalesceKey = `timeline-resize:${element.hfId ?? element.id}`;
const timingChanged =
updates.start !== element.start || updates.duration !== element.duration;
const needsExtension = extendRootDurationIfNeeded(updates.start + updates.duration);
const resizeFallback = () =>
enqueueEdit(element, "Resize timeline clip", buildResizePatches, coalesceKey).then(() => {
const pid = projectIdRef.current;
if (timingChanged && element.domId && pid) {
return scaleGsapPositions(
pid,
targetPath,
element.domId,
element.start,
element.duration,
updates.start,
updates.duration,
)
.then(() => reloadPreview())
.catch((err) => console.error("[Timeline] Failed to scale GSAP positions", err));
}
return reloadPreview();
const domId = element.domId;
return finishTimelineTimingFallback({
iframe: previewIframeRef.current,
needsExtension,
rootDurationSeconds: updates.start + updates.duration,
reloadPreview,
gsapMutation:
timingChanged && domId && pid
? () =>
scaleGsapPositions(
pid,
targetPath,
domId,
element.start,
element.duration,
updates.start,
updates.duration,
)
: undefined,
onGsapError: (err) => console.error("[Timeline] Failed to scale GSAP positions", err),
});
});
if (sdkSession && element.hfId && !hasPbsAdjustment) {
if (sdkSession && element.hfId && !hasPbsAdjustment && !needsExtension) {
return sdkTimingPersist(
element.hfId,
targetPath,
@@ -10,6 +10,20 @@ interface RecordEditInput {
files: Record<string, { before: string; after: string }>;
}
// Resolves once the z-index patches are persisted, so a caller that also writes
// the same file (e.g. a timing move) can order its write after this one.
export type TimelineZIndexReorderCommit = (
entries: Array<{
element: HTMLElement;
zIndex: number;
id?: string;
selector?: string;
selectorIndex?: number;
sourceFile: string;
key?: string;
}>,
) => Promise<void>;
export interface UseTimelineEditingOptions {
projectId: string | null;
activeCompPath: string | null;
@@ -27,4 +41,5 @@ export interface UseTimelineEditingOptions {
sdkSession?: Composition | null;
/** Resync the SDK session after a server-authoritative timeline write. */
forceReloadSdkSession?: () => void;
handleDomZIndexReorderCommitRef?: MutableRefObject<TimelineZIndexReorderCommit | null>;
}
@@ -28,13 +28,17 @@ export const BeatBackgroundLines = memo(function BeatBackgroundLines({
beatTimes: number[] | undefined;
beatStrengths: number[] | undefined;
pps: number;
/** Beat time a dragged clip will snap to — drawn as a bright neon line. */
/** Snap guide time — drawn as a bright line even when it is not a beat. */
highlightTime?: number | null;
}) {
if (!beatTimes || beatsTooDense(beatTimes, pps)) return null;
const visibleBeatTimes = beatTimes && !beatsTooDense(beatTimes, pps) ? beatTimes : null;
const highlightIsBeat =
highlightTime != null &&
visibleBeatTimes?.some((t) => Math.abs(t - highlightTime) < 1e-3) === true;
if (!visibleBeatTimes && highlightTime == null) return null;
return (
<div className="absolute inset-0 pointer-events-none" style={{ zIndex: 0 }}>
{beatTimes.map((t, i) => {
{visibleBeatTimes?.map((t, i) => {
const isHighlight = highlightTime != null && Math.abs(t - highlightTime) < 1e-3;
const strength = Math.pow(Math.min(1, beatStrengths?.[i] ?? 0.5), 2.2);
const opacity = isHighlight ? 1 : 0.06 + strength * 0.16;
@@ -52,6 +56,18 @@ export const BeatBackgroundLines = memo(function BeatBackgroundLines({
/>
);
})}
{highlightTime != null && !highlightIsBeat && (
<div
className="absolute top-0 bottom-0"
style={{
left: highlightTime * pps,
width: 2,
background: "rgba(34,197,94,1)",
boxShadow: "0 0 6px rgba(34,197,94,0.9)",
zIndex: 1,
}}
/>
)}
</div>
);
});
@@ -117,6 +117,10 @@ describe("Timeline provider boundary", () => {
);
});
// Flush passive effects (ResizeObserver-driven layout) so the gutter row is
// mounted before we query it.
act(() => {});
const button = host.querySelector<HTMLButtonElement>('button[aria-label="Show track 0"]');
expect(button).not.toBeNull();
if (!button) throw new Error("Expected a track visibility toggle");
@@ -23,11 +23,15 @@ import {
import { useTimelineClipDrag } from "./useTimelineClipDrag";
import { ClipContextMenu } from "./ClipContextMenu";
import { TimelineShortcutHint } from "./TimelineShortcutHint";
import { buildStackingTimelineLayers, insertPreviewTrackOrder } from "./timelineTrackOrder";
import { getTimelineLayerGroupHeaderTotalHeight } from "./TimelineLayerGroupHeader";
import {
GUTTER,
generateTicks,
generateVisibleTicks,
getTimelineCanvasHeight,
shouldShowTimelineShortcutHint,
computeTimelineBasisDuration,
computeTimelineEffectiveDuration,
} from "./timelineLayout";
import { useResolvedTimelineEditCallbacks } from "./useResolvedTimelineEditCallbacks";
import type { TimelineProps } from "./TimelineTypes";
@@ -178,39 +182,29 @@ export const Timeline = memo(function Timeline({
if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
});
const effectiveDuration = useMemo(() => {
const safeDur = Number.isFinite(duration) ? duration : 0;
if (rawElements.length === 0) return safeDur;
const maxEnd = Math.max(...rawElements.map((el) => el.start + el.duration));
const result = Math.max(safeDur, maxEnd);
return Number.isFinite(result) ? result : safeDur;
}, [rawElements, duration]);
const tracks = useMemo(() => {
const map = new Map<number, typeof expandedElements>();
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 tracks = useMemo(
() => buildStackingTimelineLayers(expandedElements).rows,
[expandedElements],
);
const trackStyles = useMemo(() => {
const map = new Map<number, TrackVisualStyle>();
for (const [trackNum, els] of tracks) {
map.set(trackNum, getTrackStyle(els[0]?.tag ?? ""));
const map = new Map<string, TrackVisualStyle>();
for (const layer of tracks) {
map.set(layer.id, getTrackStyle(layer.elements[0]?.tag ?? ""));
}
return map;
}, [tracks]);
const trackOrder = useMemo(() => tracks.map(([trackNum]) => trackNum), [tracks]);
const trackOrder = useMemo(() => tracks.map((layer) => layer.id), [tracks]);
const trackOrderRef = useRef(trackOrder);
trackOrderRef.current = trackOrder;
const timelineLayersRef = useRef(tracks);
timelineLayersRef.current = tracks;
const expandedElementsRef = useRef(expandedElements);
expandedElementsRef.current = expandedElements;
const ppsRef = useRef(100);
const durationRef = useRef(effectiveDuration);
durationRef.current = effectiveDuration;
const durationRef = useRef(Number.isFinite(duration) ? duration : 0);
// Stable ref so useTimelineClipDrag can clear rangeSelection without circular dep
const setRangeSelectionRef = useRef<((sel: null) => void) | null>(null);
@@ -226,8 +220,9 @@ export const Timeline = memo(function Timeline({
} = useTimelineClipDrag({
scrollRef,
ppsRef,
durationRef,
trackOrderRef,
timelineLayersRef,
timelineElementsRef: expandedElementsRef,
onMoveElement,
onResizeElement,
onBlockedEditAttempt,
@@ -235,17 +230,42 @@ export const Timeline = memo(function Timeline({
setRangeSelectionRef,
});
// basis drives the zoom (committed); effective adds the live preview (see timelineLayout).
const basisDuration = useMemo(
() =>
computeTimelineBasisDuration(
duration,
rawElements.map((el) => el.start + el.duration),
),
[rawElements, duration],
);
const effectiveDuration = useMemo(
() =>
computeTimelineEffectiveDuration(basisDuration, [
draggedClip?.started ? draggedClip.previewStart + draggedClip.element.duration : null,
resizingClip?.started ? resizingClip.previewStart + resizingClip.previewDuration : null,
]),
[basisDuration, draggedClip, resizingClip],
);
durationRef.current = effectiveDuration;
const displayTrackOrder = useMemo(() => {
if (
!draggedClip?.started ||
trackOrder.length === 0 ||
trackOrder.includes(draggedClip.previewTrack)
trackOrder.includes(draggedClip.previewLayerId)
)
return trackOrder;
return [...trackOrder, draggedClip.previewTrack].sort((a, b) => a - b);
return insertPreviewTrackOrder(
trackOrder,
draggedClip.previewLayerId,
draggedClip.previewLayerIndex,
);
}, [draggedClip, trackOrder]);
const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
const totalH =
getTimelineCanvasHeight(displayTrackOrder.length) +
getTimelineLayerGroupHeaderTotalHeight(displayTrackOrder, tracks);
const keyframeCache = usePlayerStore((s) => s.keyframeCache);
const selectedKeyframes = usePlayerStore((s) => s.selectedKeyframes);
const toggleSelectedKeyframe = usePlayerStore((s) => s.toggleSelectedKeyframe);
@@ -258,9 +278,10 @@ export const Timeline = memo(function Timeline({
const selectedElementRef = useRef<TimelineElement | null>(selectedElement);
selectedElementRef.current = selectedElement;
// Fit to basisDuration, not effectiveDuration, so a live drag can't rezoom.
const fitPps =
viewportWidth > GUTTER && effectiveDuration > 0
? (viewportWidth - GUTTER - 2) / effectiveDuration
viewportWidth > GUTTER && basisDuration > 0
? (viewportWidth - GUTTER - 2) / basisDuration
: 100;
const pps = getTimelinePixelsPerSecond(fitPps, zoomMode, manualZoomPercent);
ppsRef.current = pps;
@@ -341,8 +362,8 @@ export const Timeline = memo(function Timeline({
});
const { major, minor } = useMemo(
() => generateTicks(effectiveDuration, pps),
[effectiveDuration, pps],
() => generateVisibleTicks(effectiveDuration, pps, viewportWidth, GUTTER),
[effectiveDuration, pps, viewportWidth],
);
const majorTickInterval = major.length >= 2 ? major[1] - major[0] : effectiveDuration;
@@ -373,6 +394,7 @@ export const Timeline = memo(function Timeline({
ppsRef,
durationRef,
trackOrderRef,
timelineLayersRef,
onFileDrop,
onAssetDrop,
onBlockDrop,
@@ -1,5 +1,4 @@
import { memo, type ReactNode } from "react";
import { Eye, EyeSlash } from "@phosphor-icons/react";
import { Fragment, memo, type ReactNode } from "react";
import { BeatStrip, BeatBackgroundLines } from "./BeatStrip";
import { TimelineClip } from "./TimelineClip";
import { TimelineClipDiamonds } from "./TimelineClipDiamonds";
@@ -20,10 +19,19 @@ import {
} from "../store/playerStore";
import type { DraggedClipState, ResizingClipState, BlockedClipState } from "./useTimelineClipDrag";
import type { TrackVisualStyle } from "./timelineIcons";
import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrder";
import { STUDIO_KEYFRAMES_ENABLED } from "../../components/editor/manualEditingAvailability";
import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
import { isMusicTrack } from "../../utils/timelineInspector";
import { TimelineLayerGutter } from "./TimelineLayerGutter";
import {
shouldShowTimelineLayerGroupHeader,
TimelineLayerGroupHeader,
} from "./TimelineLayerGroupHeader";
import { resolveTimelineDropIndicator } from "./timelineDropIndicator";
import { TimelineDropInsertionLine } from "./TimelineDropInsertionLine";
import { TimelineDragGhost } from "./TimelineDragGhost";
function ClipLintDot({ element }: { element: TimelineElement }) {
const lint = usePlayerStore((s) => s.lintFindingsByElement.get(element.key ?? element.id));
@@ -47,10 +55,10 @@ interface TimelineCanvasProps {
majorTickInterval: number;
rangeSelection: TimelineRangeSelection | null;
theme: TimelineTheme;
displayTrackOrder: number[];
trackOrder: number[];
tracks: [number, TimelineElement[]][];
trackStyles: Map<number, TrackVisualStyle>;
displayTrackOrder: TimelineLayerId[];
trackOrder: TimelineLayerId[];
tracks: StackingTimelineLayer[];
trackStyles: Map<TimelineLayerId, TrackVisualStyle>;
selectedElementId: string | null;
hoveredClip: string | null;
draggedClip: DraggedClipState | null;
@@ -112,7 +120,7 @@ export const TimelineCanvas = memo(function TimelineCanvas({
selectedElementId,
hoveredClip,
draggedClip,
resizingClip: _resizingClip,
resizingClip,
blockedClipRef,
suppressClickRef,
scrollRef,
@@ -141,9 +149,20 @@ export const TimelineCanvas = memo(function TimelineCanvas({
onContextMenuClip,
beatAnalysis,
}: TimelineCanvasProps) {
const { onResizeElement, onMoveElement, onToggleTrackHidden, onRazorSplit, onRazorSplitAll } =
useTimelineEditContextOptional();
const {
onResizeElement,
onMoveElement,
onToggleTrackHidden,
onToggleElementHidden,
onRazorSplit,
onRazorSplitAll,
} = useTimelineEditContextOptional();
const beatDragging = usePlayerStore((s) => s.beatDragging);
const activeSnapGuideTime = draggedClip?.started
? (draggedClip.snapBeatTime ?? draggedClip.snapGuideTime)
: resizingClip?.started
? resizingClip.snapGuideTime
: null;
const draggedElement = draggedClip?.element ?? null;
const activeDraggedElement =
draggedClip?.started === true && draggedElement
@@ -181,9 +200,16 @@ export const TimelineCanvas = memo(function TimelineCanvas({
)}
</>
);
const activeDropPlacement =
draggedClip?.started === true ? (draggedClip.previewStackingReorder?.placement ?? null) : null;
return (
<div className="relative" style={{ height: totalH, width: GUTTER + trackContentWidth }}>
// minWidth:100% makes the lanes and ruler fill the panel when the composition
// is narrower than the viewport (zoomed out); content stays in time coords.
<div
className="relative"
style={{ height: totalH, width: GUTTER + trackContentWidth, minWidth: "100%" }}
>
<TimelineRuler
major={major}
minor={minor}
@@ -198,13 +224,35 @@ export const TimelineCanvas = memo(function TimelineCanvas({
{
// fallow-ignore-next-line complexity
displayTrackOrder.map((trackNum) => {
const els = tracks.find(([t]) => t === trackNum)?.[1] ?? [];
const ts = trackStyles.get(trackNum) ?? getTrackStyle("");
displayTrackOrder.map((layerId, rowIndex) => {
const layer = tracks.find((item) => item.id === layerId) ?? null;
const previousLayerId = displayTrackOrder[rowIndex - 1];
const previousLayer = previousLayerId
? (tracks.find((item) => item.id === previousLayerId) ?? null)
: null;
const els = layer?.elements ?? [];
const ts = trackStyles.get(layerId) ?? getTrackStyle("");
const isAudioLayer = layer?.kind === "audio";
const isFirstAudioLayer = isAudioLayer && previousLayer?.kind !== "audio";
const isPendingTrack =
draggedClip?.started === true && !trackOrder.includes(trackNum) && els.length === 0;
draggedClip?.started === true && !trackOrder.includes(layerId) && els.length === 0;
const baseRowBackground = rowIndex % 2 === 0 ? theme.rowBackground : "#0D0E12";
const dropIndicator = resolveTimelineDropIndicator({
placement: activeDropPlacement,
layerId,
layerOrder: displayTrackOrder,
});
const rowBackground =
displayTrackOrder.indexOf(trackNum) % 2 === 0 ? theme.rowBackground : "#0D0E12";
dropIndicator?.kind === "onto"
? theme.clipBackgroundActive
: isAudioLayer
? `linear-gradient(90deg, ${theme.gutterBackground} 0, ${baseRowBackground} 74px)`
: baseRowBackground;
const showGroupHeader = shouldShowTimelineLayerGroupHeader(
layer?.contextKey ?? "",
previousLayer?.contextKey ?? "",
);
const rowTrack = layer?.placementTrack ?? els[0]?.track ?? 0;
// The beat-dot strip occupies the top of this track's lane (active track,
// or the music track when nothing is selected). When shown, keyframe
// diamonds shrink + drop to the bottom half so they don't collide with it.
@@ -215,300 +263,301 @@ export const TimelineCanvas = memo(function TimelineCanvas({
: els.some(isMusicTrack));
const isTrackHidden = els.length > 0 && els.every((element) => element.hidden === true);
return (
<div
key={trackNum}
className="relative flex"
style={{
height: TRACK_H,
background: rowBackground,
borderBottom: `1px solid ${theme.rowBorder}`,
}}
>
<div
className="sticky left-0 z-[12] flex-shrink-0 flex items-center justify-center"
style={{
width: GUTTER,
background: theme.gutterBackground,
borderRight: `1px solid ${theme.gutterBorder}`,
}}
>
<button
type="button"
aria-label={isTrackHidden ? `Show track ${trackNum}` : `Hide track ${trackNum}`}
title={isTrackHidden ? `Show track ${trackNum}` : `Hide track ${trackNum}`}
className={`flex h-6 w-6 items-center justify-center rounded border-0 bg-transparent p-0 transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-[-1px] focus-visible:outline-[#3CE6AC] ${
isTrackHidden
? "text-[#3CE6AC] hover:text-white"
: "text-white/35 hover:text-white/75"
}`}
onPointerDown={(e) => {
e.stopPropagation();
}}
onClick={(e) => {
e.stopPropagation();
void onToggleTrackHidden?.(trackNum, !isTrackHidden);
}}
>
{isTrackHidden ? (
<EyeSlash size={14} weight="bold" aria-hidden="true" />
) : (
<Eye size={14} weight="bold" aria-hidden="true" />
)}
</button>
</div>
<div
style={{
width: trackContentWidth,
opacity: isTrackHidden ? 0.35 : 1,
transition: "opacity 120ms ease",
}}
className="relative"
>
{/* Faint beat lines in every track's background (behind the clips);
the active move-snap target is highlighted. */}
<BeatBackgroundLines
beatTimes={beatAnalysis?.beatTimes}
beatStrengths={beatAnalysis?.beatStrengths}
pps={pps}
highlightTime={draggedClip?.started ? draggedClip.snapBeatTime : null}
<Fragment key={layerId}>
{showGroupHeader && layer && (
<TimelineLayerGroupHeader
contextKey={layer.contextKey}
trackContentWidth={trackContentWidth}
theme={theme}
accentColor={ts.accent}
/>
{/* Beat dots on the active track (the one holding the selection),
falling back to the music track when nothing is selected. */}
{beatStripOnTrack && (
<BeatStrip
)}
<div
className="relative flex"
style={{
height: TRACK_H,
background: rowBackground,
borderTop: isFirstAudioLayer ? `2px solid ${theme.rulerBorder}` : undefined,
borderBottom: `1px solid ${theme.rowBorder}`,
boxShadow:
dropIndicator?.kind === "onto" ? `inset 0 0 0 1px ${ts.accent}` : undefined,
}}
>
<TimelineLayerGutter
isAudio={isAudioLayer}
isTrackHidden={isTrackHidden}
rowTrack={rowTrack}
theme={theme}
onToggleHidden={() => {
if (onToggleElementHidden && els.length > 0) {
for (const element of els) {
void onToggleElementHidden(element.key ?? element.id, !isTrackHidden);
}
return;
}
void onToggleTrackHidden?.(rowTrack, !isTrackHidden);
}}
/>
<div
style={{
width: trackContentWidth,
opacity: isTrackHidden ? 0.35 : 1,
transition: "opacity 120ms ease",
}}
className="relative"
>
{layer?.contextKey && (
<span
className="absolute bottom-0 top-0 pointer-events-none"
style={{
left: 0,
width: 2,
background: ts.accent,
opacity: 0.45,
zIndex: 2,
}}
/>
)}
{dropIndicator?.kind === "line" && (
<TimelineDropInsertionLine edge={dropIndicator.edge} accentColor={ts.accent} />
)}
{/* Faint beat lines in every track's background (behind the clips);
the active snap target is highlighted. */}
<BeatBackgroundLines
beatTimes={beatAnalysis?.beatTimes}
beatStrengths={beatAnalysis?.beatStrengths}
pps={pps}
highlightTime={activeSnapGuideTime}
/>
)}
{isPendingTrack && (
<div
className="absolute inset-0 flex items-center"
style={{
paddingLeft: 16,
color: ts.label,
fontSize: 11,
letterSpacing: "0.06em",
textTransform: "uppercase",
opacity: 0.5,
}}
>
New track
</div>
)}
{
// fallow-ignore-next-line complexity
els.map((el) => {
const clipStyle = getTrackStyle(el.tag);
const elementKey = el.key ?? el.id;
const capabilities = getTimelineEditCapabilities(el);
const isSelected = selectedElementId === elementKey;
const isComposition = !!el.compositionSrc;
// elementKey (el.key ?? el.id) is already unique per clip; do NOT
// fold in the map index, or a splice/reorder remounts every clip
// at/after the change (DOM flash, drag interruption).
const clipKey = elementKey;
const isDraggingClip =
draggedClip?.started === true &&
(draggedElement?.key ?? draggedElement?.id) === elementKey;
if (isDraggingClip) return null;
const previewElement = getPreviewElement(el);
return (
<TimelineClip
key={clipKey}
onContextMenu={(e: React.MouseEvent) => {
e.preventDefault();
onContextMenuClip?.(e, el);
}}
el={previewElement}
pps={pps}
clipY={CLIP_Y}
isSelected={isSelected}
isHovered={hoveredClip === clipKey}
isDragging={false}
hasCustomContent={!!renderClipContent}
capabilities={capabilities}
theme={theme}
isComposition={isComposition}
onHoverStart={() => setHoveredClip(clipKey)}
onHoverEnd={() => setHoveredClip(null)}
onResizeStart={(edge, e) => {
if (e.button !== 0 || e.shiftKey || !onResizeElement) return;
if (edge === "start" && !capabilities.canTrimStart) return;
if (edge === "end" && !capabilities.canTrimEnd) return;
e.stopPropagation();
blockedClipRef.current = null;
setShowPopover(false);
setRangeSelection(null);
setResizingClip({
element: el,
edge,
originClientX: e.clientX,
previewStart: el.start,
previewDuration: el.duration,
previewPlaybackStart: el.playbackStart,
started: false,
});
}}
onPointerDown={
// fallow-ignore-next-line complexity
(e) => {
if (e.button !== 0) return;
if (usePlayerStore.getState().activeTool === "razor") return;
if (e.shiftKey) {
shiftClickClipRef.current = {
element: el,
anchorX: e.clientX,
anchorY: e.clientY,
};
return;
}
const target = e.currentTarget as HTMLElement;
const rect = target.getBoundingClientRect();
const blockedIntent = resolveBlockedTimelineEditIntent({
width: rect.width,
offsetX: e.clientX - rect.left,
handleWidth: CLIP_HANDLE_W,
capabilities,
});
if (
blockedIntent &&
((blockedIntent === "move" && onMoveElement) ||
(blockedIntent !== "move" && onResizeElement))
) {
blockedClipRef.current = {
element: el,
intent: blockedIntent,
originClientX: e.clientX,
originClientY: e.clientY,
started: false,
};
return;
}
if (!onMoveElement || !capabilities.canMove) return;
{/* Beat dots on the active track (the one holding the selection),
falling back to the music track when nothing is selected. */}
{beatStripOnTrack && (
<BeatStrip
beatTimes={beatAnalysis?.beatTimes}
beatStrengths={beatAnalysis?.beatStrengths}
pps={pps}
/>
)}
{isPendingTrack && (
<div
className="absolute inset-0 flex items-center"
style={{
paddingLeft: 16,
color: ts.label,
fontSize: 11,
letterSpacing: 0,
textTransform: "uppercase",
opacity: 0.5,
}}
>
New track
</div>
)}
{
// fallow-ignore-next-line complexity
els.map((el) => {
const clipStyle = getTrackStyle(el.tag);
const elementKey = el.key ?? el.id;
const capabilities = getTimelineEditCapabilities(el);
const isSelected = selectedElementId === elementKey;
const isComposition = !!el.compositionSrc;
// elementKey (el.key ?? el.id) is already unique per clip; do NOT
// fold in the map index, or a splice/reorder remounts every clip
// at/after the change (DOM flash, drag interruption).
const clipKey = elementKey;
const isDraggingClip =
draggedClip?.started === true &&
(draggedElement?.key ?? draggedElement?.id) === elementKey;
if (isDraggingClip) return null;
const previewElement = getPreviewElement(el);
return (
<TimelineClip
key={clipKey}
onContextMenu={(e: React.MouseEvent) => {
e.preventDefault();
onContextMenuClip?.(e, el);
}}
el={previewElement}
pps={pps}
clipY={CLIP_Y}
isSelected={isSelected}
isHovered={hoveredClip === clipKey}
isDragging={false}
hasCustomContent={!!renderClipContent}
capabilities={capabilities}
theme={theme}
isComposition={isComposition}
onHoverStart={() => setHoveredClip(clipKey)}
onHoverEnd={() => setHoveredClip(null)}
onResizeStart={(edge, e) => {
if (e.button !== 0 || e.shiftKey || !onResizeElement) return;
if (edge === "start" && !capabilities.canTrimStart) return;
if (edge === "end" && !capabilities.canTrimEnd) return;
e.stopPropagation();
blockedClipRef.current = null;
setShowPopover(false);
setRangeSelection(null);
setDraggedClip({
setResizingClip({
element: el,
edge,
originClientX: e.clientX,
originClientY: e.clientY,
originScrollLeft: scrollRef.current?.scrollLeft ?? 0,
originScrollTop: scrollRef.current?.scrollTop ?? 0,
pointerClientX: e.clientX,
pointerClientY: e.clientY,
pointerOffsetX: e.clientX - rect.left,
pointerOffsetY: e.clientY - rect.top,
previewStart: el.start,
previewTrack: el.track,
snapBeatTime: null,
previewDuration: el.duration,
previewPlaybackStart: el.playbackStart,
snapGuideTime: null,
snapGuideKind: null,
started: false,
});
syncClipDragAutoScroll(e.clientX, e.clientY);
}
}
onClick={(e) => {
e.stopPropagation();
if (suppressClickRef.current) return;
const { activeTool } = usePlayerStore.getState();
if (activeTool === "razor" && onRazorSplit) {
const clipRect = (
e.currentTarget as HTMLElement
).getBoundingClientRect();
const clickOffsetX = e.clientX - clipRect.left;
const splitTime = previewElement.start + clickOffsetX / pps;
const clampedTime = Math.max(
previewElement.start + SPLIT_BOUNDARY_EPSILON_S,
Math.min(
previewElement.start +
previewElement.duration -
SPLIT_BOUNDARY_EPSILON_S,
splitTime,
),
);
if (e.shiftKey && onRazorSplitAll) {
onRazorSplitAll(clampedTime);
} else {
onRazorSplit(el, clampedTime);
}}
onPointerDown={
// fallow-ignore-next-line complexity
(e) => {
if (e.button !== 0) return;
if (usePlayerStore.getState().activeTool === "razor") return;
if (e.shiftKey) {
shiftClickClipRef.current = {
element: el,
anchorX: e.clientX,
anchorY: e.clientY,
};
return;
}
const target = e.currentTarget as HTMLElement;
const rect = target.getBoundingClientRect();
const blockedIntent = resolveBlockedTimelineEditIntent({
width: rect.width,
offsetX: e.clientX - rect.left,
handleWidth: CLIP_HANDLE_W,
capabilities,
});
if (
blockedIntent &&
((blockedIntent === "move" && onMoveElement) ||
(blockedIntent !== "move" && onResizeElement))
) {
blockedClipRef.current = {
element: el,
intent: blockedIntent,
originClientX: e.clientX,
originClientY: e.clientY,
started: false,
};
return;
}
if (!onMoveElement || !capabilities.canMove) return;
blockedClipRef.current = null;
setShowPopover(false);
setRangeSelection(null);
setDraggedClip({
element: el,
originClientX: e.clientX,
originClientY: e.clientY,
originScrollLeft: scrollRef.current?.scrollLeft ?? 0,
originScrollTop: scrollRef.current?.scrollTop ?? 0,
pointerClientX: e.clientX,
pointerClientY: e.clientY,
pointerOffsetX: e.clientX - rect.left,
pointerOffsetY: e.clientY - rect.top,
previewStart: el.start,
previewTrack: el.track,
previewLayerId: layerId,
previewLayerIndex: rowIndex,
previewStackingReorder: null,
snapBeatTime: null,
snapGuideTime: null,
snapGuideKind: null,
started: false,
});
syncClipDragAutoScroll(e.clientX, e.clientY);
}
return;
}
const nextElement = isSelected ? null : el;
setSelectedElementId(nextElement ? elementKey : null);
onSelectElement?.(nextElement);
}}
onDoubleClick={(e) => {
e.stopPropagation();
if (suppressClickRef.current) return;
if (isComposition && onDrillDown) onDrillDown(el);
}}
>
{renderClipChildren(previewElement, clipStyle)}
{STUDIO_KEYFRAMES_ENABLED && keyframeCache?.get(elementKey) && (
<TimelineClipDiamonds
keyframesData={keyframeCache.get(elementKey)!}
clipWidthPx={Math.max(previewElement.duration * pps, 4)}
clipHeightPx={TRACK_H - 2 * CLIP_Y}
beatsActive={beatStripOnTrack}
accentColor={clipStyle.accent}
isSelected={isSelected}
currentPercentage={
previewElement.duration > 0
? ((currentTime - previewElement.start) / previewElement.duration) *
100
: 0
onClick={(e) => {
e.stopPropagation();
if (suppressClickRef.current) return;
const { activeTool } = usePlayerStore.getState();
if (activeTool === "razor" && onRazorSplit) {
const clipRect = (
e.currentTarget as HTMLElement
).getBoundingClientRect();
const clickOffsetX = e.clientX - clipRect.left;
const splitTime = previewElement.start + clickOffsetX / pps;
const clampedTime = Math.max(
previewElement.start + SPLIT_BOUNDARY_EPSILON_S,
Math.min(
previewElement.start +
previewElement.duration -
SPLIT_BOUNDARY_EPSILON_S,
splitTime,
),
);
if (e.shiftKey && onRazorSplitAll) {
onRazorSplitAll(clampedTime);
} else {
onRazorSplit(el, clampedTime);
}
return;
}
elementId={elementKey}
selectedKeyframes={selectedKeyframes}
onClickKeyframe={(pct) => onClickKeyframe?.(previewElement, pct)}
onShiftClickKeyframe={onShiftClickKeyframe}
onContextMenuKeyframe={onContextMenuKeyframe}
onMoveKeyframe={onMoveKeyframe}
suppressClickRef={suppressClickRef}
/>
)}
</TimelineClip>
);
})
}
const nextElement = isSelected ? null : el;
setSelectedElementId(nextElement ? elementKey : null);
onSelectElement?.(nextElement);
}}
onDoubleClick={(e) => {
e.stopPropagation();
if (suppressClickRef.current) return;
if (isComposition && onDrillDown) onDrillDown(el);
}}
>
{renderClipChildren(previewElement, clipStyle)}
{STUDIO_KEYFRAMES_ENABLED && keyframeCache?.get(elementKey) && (
<TimelineClipDiamonds
keyframesData={keyframeCache.get(elementKey)!}
clipWidthPx={Math.max(previewElement.duration * pps, 4)}
clipHeightPx={TRACK_H - 2 * CLIP_Y}
beatsActive={beatStripOnTrack}
beatTimes={beatAnalysis?.beatTimes}
clipStart={previewElement.start}
clipDurationSeconds={previewElement.duration}
pixelsPerSecond={pps}
accentColor={clipStyle.accent}
isSelected={isSelected}
currentPercentage={
previewElement.duration > 0
? ((currentTime - previewElement.start) /
previewElement.duration) *
100
: 0
}
elementId={elementKey}
selectedKeyframes={selectedKeyframes}
onClickKeyframe={(pct) => onClickKeyframe?.(previewElement, pct)}
onShiftClickKeyframe={onShiftClickKeyframe}
onContextMenuKeyframe={onContextMenuKeyframe}
onMoveKeyframe={onMoveKeyframe}
suppressClickRef={suppressClickRef}
/>
)}
</TimelineClip>
);
})
}
</div>
</div>
</div>
</Fragment>
);
})
}
{/* Drag ghost */}
{activeDraggedElement && activeDraggedPosition && (
<div
className="absolute pointer-events-none"
style={{
top: activeDraggedPosition.top,
left: activeDraggedPosition.left,
width: Math.max(activeDraggedElement.duration * pps, 4),
height: TRACK_H - CLIP_Y * 2,
zIndex: 40,
}}
<TimelineDragGhost
element={activeDraggedElement}
position={activeDraggedPosition}
pps={pps}
selectedElementId={selectedElementId}
hasCustomContent={!!renderClipContent}
theme={theme}
>
<TimelineClip
el={{ ...activeDraggedElement, start: 0 }}
pps={pps}
clipY={0}
isSelected={selectedElementId === (activeDraggedElement.key ?? activeDraggedElement.id)}
isHovered={false}
isDragging={true}
hasCustomContent={!!renderClipContent}
capabilities={getTimelineEditCapabilities(activeDraggedElement)}
theme={theme}
isComposition={!!activeDraggedElement.compositionSrc}
onHoverStart={() => {}}
onHoverEnd={() => {}}
onResizeStart={() => {}}
onClick={() => {}}
onDoubleClick={() => {}}
>
{renderClipChildren(activeDraggedElement, getTrackStyle(activeDraggedElement.tag))}
</TimelineClip>
</div>
{renderClipChildren(activeDraggedElement, getTrackStyle(activeDraggedElement.tag))}
</TimelineDragGhost>
)}
{/* Range highlight */}
@@ -1,10 +1,12 @@
import { memo, useRef, useState } from "react";
import { BEAT_BAND_H } from "./BeatStrip";
import {
clampToNeighbors,
KEYFRAME_DRAG_THRESHOLD_PX,
previewClipPct,
resolveKeyframeDrag,
} from "../../components/editor/keyframeDrag";
import { snapKeyframePctToBeat } from "./timelineEditing";
interface KeyframeEntry {
percentage: number;
@@ -28,6 +30,14 @@ interface TimelineClipDiamondsProps {
/** Beat-dot strip is shown on this track → shrink diamonds + drop them into
* the bottom half so they clear the strip at the top. */
beatsActive?: boolean;
/** Composition-time beat positions (same source the beat strip renders from).
* When present and `beatsActive`, a dragged keyframe snaps to the nearest beat. */
beatTimes?: number[];
/** Clip start / duration (seconds) + pixels-per-second, needed to map a
* dragged keyframe's clip-% to composition time for beat snapping. */
clipStart?: number;
clipDurationSeconds?: number;
pixelsPerSecond?: number;
accentColor: string;
isSelected: boolean;
currentPercentage: number;
@@ -71,6 +81,10 @@ export const TimelineClipDiamonds = memo(function TimelineClipDiamonds({
clipWidthPx,
clipHeightPx,
beatsActive,
beatTimes,
clipStart = 0,
clipDurationSeconds = 0,
pixelsPerSecond = 1,
accentColor,
isSelected,
currentPercentage,
@@ -121,6 +135,20 @@ export const TimelineClipDiamonds = memo(function TimelineClipDiamonds({
const baseOpacity = isSelected ? 0.4 : 0.25;
const canDrag = isSelected && !!onMoveKeyframe;
// Snap a dragged keyframe's clip-% to the nearest beat (within ~8px), then
// re-clamp to neighbours so the snap can't cross a sibling keyframe. No-op
// when the beat strip isn't active for this track or no beats are loaded.
const snapClipPctToBeat = (clipPct: number, draggedIndex: number): number => {
if (!beatsActive || !beatTimes || beatTimes.length === 0) return clipPct;
const snapped = snapKeyframePctToBeat(
{ start: clipStart, duration: clipDurationSeconds },
clipPct,
beatTimes,
pixelsPerSecond,
);
return clampToNeighbors(snapped, sortedClipPcts, draggedIndex);
};
return (
<div
className="absolute inset-0"
@@ -195,14 +223,17 @@ export const TimelineClipDiamonds = memo(function TimelineClipDiamonds({
if (d.moved) {
setPreview({
kfKey,
clipPct: previewClipPct({
pointerDownX: d.startX,
pointerMoveX: e.clientX,
clipWidthPx,
draggedClipPct: d.fromClipPct,
draggedIndex: i,
sortedClipPcts,
}),
clipPct: snapClipPctToBeat(
previewClipPct({
pointerDownX: d.startX,
pointerMoveX: e.clientX,
clipWidthPx,
draggedClipPct: d.fromClipPct,
draggedIndex: i,
sortedClipPcts,
}),
i,
),
});
}
};
@@ -238,7 +269,7 @@ export const TimelineClipDiamonds = memo(function TimelineClipDiamonds({
if (e.shiftKey) onShiftClickKeyframe?.(elementId, kf.percentage);
else onClickKeyframe?.(kf.percentage);
} else if (res.kind === "move" && res.toClipPct != null) {
onMoveKeyframe?.(elementId, d.fromClipPct, res.toClipPct);
onMoveKeyframe?.(elementId, d.fromClipPct, snapClipPctToBeat(res.toClipPct, i));
// A retime still targeted this exact diamond — park/select it at its
// new position, same as a plain click, or a drag that actually moved
// something looks identical to one that silently did nothing.
@@ -0,0 +1,59 @@
import type { ReactNode } from "react";
import { TimelineClip } from "./TimelineClip";
import { getTimelineEditCapabilities } from "./timelineEditing";
import { CLIP_Y, TRACK_H } from "./timelineLayout";
import type { TimelineTheme } from "./timelineTheme";
import type { TimelineElement } from "../store/playerStore";
interface TimelineDragGhostProps {
element: TimelineElement;
position: { left: number; top: number };
pps: number;
selectedElementId: string | null;
hasCustomContent: boolean;
theme: TimelineTheme;
children: ReactNode;
}
export function TimelineDragGhost({
element,
position,
pps,
selectedElementId,
hasCustomContent,
theme,
children,
}: TimelineDragGhostProps) {
return (
<div
className="absolute pointer-events-none"
style={{
top: position.top,
left: position.left,
width: Math.max(element.duration * pps, 4),
height: TRACK_H - CLIP_Y * 2,
zIndex: 40,
}}
>
<TimelineClip
el={{ ...element, start: 0 }}
pps={pps}
clipY={0}
isSelected={selectedElementId === (element.key ?? element.id)}
isHovered={false}
isDragging={true}
hasCustomContent={hasCustomContent}
capabilities={getTimelineEditCapabilities(element)}
theme={theme}
isComposition={!!element.compositionSrc}
onHoverStart={() => {}}
onHoverEnd={() => {}}
onResizeStart={() => {}}
onClick={() => {}}
onDoubleClick={() => {}}
>
{children}
</TimelineClip>
</div>
);
}
@@ -0,0 +1,32 @@
interface TimelineDropInsertionLineProps {
edge: "top" | "bottom";
accentColor: string;
}
export function TimelineDropInsertionLine({ edge, accentColor }: TimelineDropInsertionLineProps) {
return (
<div
className="absolute left-0 right-0 pointer-events-none"
style={{
top: edge === "top" ? -1 : undefined,
bottom: edge === "bottom" ? -1 : undefined,
height: 2,
background: accentColor,
boxShadow: `0 0 8px ${accentColor}`,
zIndex: 30,
}}
>
<span
className="absolute rounded-full"
style={{
left: 0,
top: -3,
width: 8,
height: 8,
background: accentColor,
boxShadow: `0 0 8px ${accentColor}`,
}}
/>
</div>
);
}
@@ -0,0 +1,97 @@
import type { TimelineTheme } from "./timelineTheme";
import { GUTTER } from "./timelineLayout";
import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrder";
const TIMELINE_LAYER_GROUP_HEADER_H = 18;
export function shouldShowTimelineLayerGroupHeader(
contextKey: string,
previousContextKey: string,
): boolean {
return contextKey !== "" && contextKey !== previousContextKey;
}
export function getTimelineLayerGroupHeaderTotalHeight(
layerOrder: readonly TimelineLayerId[],
layers: readonly StackingTimelineLayer[],
): number {
const layerById = new Map<TimelineLayerId, StackingTimelineLayer>();
for (const layer of layers) layerById.set(layer.id, layer);
let previousContextKey = "";
let count = 0;
for (const layerId of layerOrder) {
const contextKey = layerById.get(layerId)?.contextKey ?? "";
if (shouldShowTimelineLayerGroupHeader(contextKey, previousContextKey)) count += 1;
previousContextKey = contextKey;
}
return count * TIMELINE_LAYER_GROUP_HEADER_H;
}
interface TimelineLayerGroupHeaderProps {
contextKey: string;
trackContentWidth: number;
theme: TimelineTheme;
accentColor: string;
}
export function TimelineLayerGroupHeader({
contextKey,
trackContentWidth,
theme,
accentColor,
}: TimelineLayerGroupHeaderProps) {
return (
<div
className="relative"
style={{
height: TIMELINE_LAYER_GROUP_HEADER_H,
// Fill the full canvas width (min 100% of the panel) so the context
// header spans the timeline at any zoom; minWidth preserves the intrinsic
// composition width when zoomed in and scrolling.
width: "100%",
minWidth: GUTTER + trackContentWidth,
background: theme.gutterBackground,
borderBottom: `1px solid ${theme.rowBorder}`,
}}
>
<div
className="sticky left-0 z-[13] flex h-full items-center"
style={{
width: Math.min(GUTTER + 220, GUTTER + trackContentWidth),
background: theme.gutterBackground,
}}
>
<div
className="relative h-full flex-shrink-0"
style={{
width: GUTTER,
borderRight: `1px solid ${theme.gutterBorder}`,
}}
>
<span
className="absolute bottom-0 top-0"
style={{
left: 8,
width: 2,
background: accentColor,
opacity: 0.72,
}}
/>
</div>
<div className="min-w-0 px-2">
<span
className="block truncate font-mono uppercase leading-none"
style={{
color: theme.textSecondary,
fontSize: 10,
letterSpacing: 0,
}}
>
Inside: {contextKey}
</span>
</div>
</div>
</div>
);
}
@@ -0,0 +1,61 @@
import { Eye, EyeSlash } from "@phosphor-icons/react";
import { Music } from "../../icons/SystemIcons";
import type { TimelineTheme } from "./timelineTheme";
import { GUTTER } from "./timelineLayout";
interface TimelineLayerGutterProps {
isAudio: boolean;
isTrackHidden: boolean;
rowTrack: number;
theme: TimelineTheme;
onToggleHidden: () => void;
}
export function TimelineLayerGutter({
isAudio,
isTrackHidden,
rowTrack,
theme,
onToggleHidden,
}: TimelineLayerGutterProps) {
return (
<div
className="sticky left-0 z-[12] flex-shrink-0 flex flex-col items-center justify-center gap-0.5"
style={{
width: GUTTER,
background: theme.gutterBackground,
borderRight: `1px solid ${theme.gutterBorder}`,
}}
>
{isAudio && (
<Music
size={12}
weight="fill"
aria-hidden="true"
style={{ color: theme.textSecondary, opacity: 0.7 }}
/>
)}
<button
type="button"
aria-label={isTrackHidden ? `Show track ${rowTrack}` : `Hide track ${rowTrack}`}
title={isTrackHidden ? `Show track ${rowTrack}` : `Hide track ${rowTrack}`}
className={`flex h-6 w-6 items-center justify-center rounded border-0 bg-transparent p-0 transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-[-1px] focus-visible:outline-[#3CE6AC] ${
isTrackHidden ? "text-[#3CE6AC] hover:text-white" : "text-white/35 hover:text-white/75"
}`}
onPointerDown={(e) => {
e.stopPropagation();
}}
onClick={(e) => {
e.stopPropagation();
onToggleHidden();
}}
>
{isTrackHidden ? (
<EyeSlash size={14} weight="bold" aria-hidden="true" />
) : (
<Eye size={14} weight="bold" aria-hidden="true" />
)}
</button>
</div>
);
}
@@ -79,13 +79,15 @@ export const TimelineRuler = memo(function TimelineRuler({
})}
</svg>
{/* Ruler */}
{/* Ruler. The bar fills the full panel width (canvas is min 100% wide);
calc(100% - GUTTER) equals trackContentWidth when zoomed in and extends
past the content when zoomed out. Ticks stay at composition coordinates. */}
<div
className="relative overflow-hidden"
style={{
height: RULER_H,
marginLeft: GUTTER,
width: trackContentWidth,
width: `calc(100% - ${GUTTER}px)`,
background: theme.gutterBackground,
borderBottom: `1px solid ${theme.rulerBorder}`,
}}
@@ -1,7 +1,7 @@
// fallow-ignore-file code-duplication
// fallow-ignore-file dead-code
import type { TimelineElement } from "../store/playerStore";
import type { BlockedTimelineEditIntent } from "./timelineEditing";
import type { BlockedTimelineEditIntent, TimelineStackingReorderIntent } from "./timelineEditing";
/**
* Shared callback signatures for timeline editing operations.
@@ -26,13 +26,16 @@ export interface TimelineDropCallbacks {
export interface TimelineEditCallbacks {
onMoveElement?: (
element: TimelineElement,
updates: Pick<TimelineElement, "start" | "track">,
updates: Pick<TimelineElement, "start" | "track"> & {
stackingReorder?: TimelineStackingReorderIntent | null;
},
) => Promise<void> | void;
onResizeElement?: (
element: TimelineElement,
updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
) => Promise<void> | void;
onToggleTrackHidden?: (track: number, hidden: boolean) => Promise<void> | void;
onToggleElementHidden?: (elementKey: string, hidden: boolean) => Promise<void> | void;
onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
onSplitElement?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
@@ -2,12 +2,14 @@ import { useCallback, useState, type RefObject } from "react";
import { TIMELINE_ASSET_MIME, TIMELINE_BLOCK_MIME } from "../../utils/timelineAssetDrop";
import { TRACK_H, resolveTimelineAssetDrop } from "./timelineLayout";
import type { TimelineDropCallbacks } from "./timelineCallbacks";
import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrder";
interface UseTimelineAssetDropOptions extends TimelineDropCallbacks {
scrollRef: RefObject<HTMLDivElement | null>;
ppsRef: RefObject<number>;
durationRef: RefObject<number>;
trackOrderRef: RefObject<number[]>;
trackOrderRef: RefObject<TimelineLayerId[]>;
timelineLayersRef: RefObject<StackingTimelineLayer[]>;
}
export function useTimelineAssetDrop({
@@ -15,6 +17,7 @@ export function useTimelineAssetDrop({
ppsRef,
durationRef,
trackOrderRef,
timelineLayersRef,
onFileDrop,
onAssetDrop,
onBlockDrop,
@@ -39,6 +42,10 @@ export function useTimelineAssetDrop({
setIsDragOver(false);
const scroll = scrollRef.current;
const rect = scroll?.getBoundingClientRect();
const layerById = new Map(timelineLayersRef.current.map((layer) => [layer.id, layer]));
const trackOrder = trackOrderRef.current
.map((id) => layerById.get(id)?.placementTrack)
.filter((track): track is number => track != null);
const dropInput = {
rectLeft: rect?.left ?? 0,
rectTop: rect?.top ?? 0,
@@ -47,7 +54,7 @@ export function useTimelineAssetDrop({
pixelsPerSecond: ppsRef.current,
duration: durationRef.current,
trackHeight: TRACK_H,
trackOrder: trackOrderRef.current,
trackOrder,
};
if (onFileDrop && e.dataTransfer.files.length > 0) {
void onFileDrop(
@@ -84,7 +91,16 @@ export function useTimelineAssetDrop({
}
}
},
[onAssetDrop, onBlockDrop, onFileDrop, scrollRef, ppsRef, durationRef, trackOrderRef],
[
onAssetDrop,
onBlockDrop,
onFileDrop,
scrollRef,
ppsRef,
durationRef,
trackOrderRef,
timelineLayersRef,
],
);
return { isDragOver, setIsDragOver, handleAssetDragOver, handleAssetDrop };
@@ -0,0 +1,48 @@
import { describe, expect, it } from "vitest";
import type { TimelineLayerDropPlacement } from "./timelineStacking";
import { resolveTimelineDropIndicator } from "./timelineDropIndicator";
const layerOrder = ["front", "middle", "back"];
describe("resolveTimelineDropIndicator", () => {
it("highlights only the row targeted by an onto placement", () => {
const placement: TimelineLayerDropPlacement = { type: "onto", layerId: "middle" };
expect(resolveTimelineDropIndicator({ placement, layerId: "front", layerOrder })).toBeNull();
expect(resolveTimelineDropIndicator({ placement, layerId: "middle", layerOrder })).toEqual({
kind: "onto",
});
});
it("renders a single insertion line at the bottom edge of the before row", () => {
const placement: TimelineLayerDropPlacement = {
type: "between",
beforeLayerId: "front",
afterLayerId: "middle",
};
expect(resolveTimelineDropIndicator({ placement, layerId: "front", layerOrder })).toEqual({
kind: "line",
edge: "bottom",
});
expect(resolveTimelineDropIndicator({ placement, layerId: "middle", layerOrder })).toBeNull();
});
it("renders above placements on the target row top edge", () => {
const placement: TimelineLayerDropPlacement = { type: "above", layerId: "front" };
expect(resolveTimelineDropIndicator({ placement, layerId: "front", layerOrder })).toEqual({
kind: "line",
edge: "top",
});
});
it("renders below placements on the target row bottom edge", () => {
const placement: TimelineLayerDropPlacement = { type: "below", layerId: "back" };
expect(resolveTimelineDropIndicator({ placement, layerId: "back", layerOrder })).toEqual({
kind: "line",
edge: "bottom",
});
});
});
@@ -0,0 +1,33 @@
import type { TimelineLayerDropPlacement } from "./timelineStacking";
import type { TimelineLayerId } from "./timelineTrackOrder";
export type TimelineDropIndicator = { kind: "onto" } | { kind: "line"; edge: "top" | "bottom" };
interface ResolveTimelineDropIndicatorInput {
placement: TimelineLayerDropPlacement | null;
layerId: TimelineLayerId;
layerOrder: readonly TimelineLayerId[];
}
export function resolveTimelineDropIndicator({
placement,
layerId,
layerOrder,
}: ResolveTimelineDropIndicatorInput): TimelineDropIndicator | null {
if (!placement || !layerOrder.includes(layerId)) return null;
switch (placement.type) {
case "onto":
return placement.layerId === layerId ? { kind: "onto" } : null;
case "between":
if (placement.beforeLayerId === layerId) return { kind: "line", edge: "bottom" };
if (!layerOrder.includes(placement.beforeLayerId) && placement.afterLayerId === layerId) {
return { kind: "line", edge: "top" };
}
return null;
case "above":
return placement.layerId === layerId ? { kind: "line", edge: "top" } : null;
case "below":
return placement.layerId === layerId ? { kind: "line", edge: "bottom" } : null;
}
}
@@ -10,8 +10,10 @@ import {
resolveTimelineAutoScroll,
resolveTimelineMove,
resolveTimelineResize,
snapKeyframePctToBeat,
type TimelinePromptElement,
} from "./timelineEditing";
import { buildStackingTimelineLayers } from "./timelineTrackOrder";
describe("resolveTimelineMove", () => {
it("moves timing based on horizontal drag and snaps to centiseconds", () => {
@@ -155,6 +157,67 @@ describe("resolveTimelineMove", () => {
),
).toEqual({ start: 2, track: 2 });
});
it("snaps conflicting vertical stacking movement to a new lane without changing data-track-index", () => {
const stackingElements = [
{
id: "root-front",
tag: "div",
start: 0,
duration: 2,
track: 0,
zIndex: 2,
hasExplicitZIndex: true,
stackingContextId: "root",
parentCompositionId: null,
compositionAncestors: ["root"],
},
{
id: "root-back",
tag: "div",
start: 0,
duration: 2,
track: 1,
zIndex: 1,
hasExplicitZIndex: true,
stackingContextId: "root",
parentCompositionId: null,
compositionAncestors: ["root"],
},
];
const layers = buildStackingTimelineLayers(stackingElements).rows;
const result = resolveTimelineMove(
{
start: 0,
track: 1,
duration: 2,
originClientX: 0,
originClientY: 0,
pixelsPerSecond: 100,
trackHeight: 72,
maxStart: 8,
trackOrder: [0, 1],
layerOrder: layers.map((layer) => layer.id),
timelineLayers: layers,
stackingElement: stackingElements[1],
stackingElements,
},
0,
-72,
);
expect(result).toEqual({
start: 0,
track: 1,
previewLayerId: `preview:root-back:above:${layers[0]!.id}`,
previewLayerIndex: 0,
stackingReorder: {
contextKey: "root",
placement: { type: "above", layerId: layers[0]!.id },
zIndexChanges: [{ key: "root-back", zIndex: 3 }],
},
});
});
});
describe("hasPatchableTimelineTarget", () => {
@@ -613,3 +676,34 @@ describe("buildPromptCopyText", () => {
);
});
});
describe("snapKeyframePctToBeat", () => {
// el spans 0–10s, so clip-% maps to composition time as pct * 0.1s.
// At pps=100 the snap window is 8 / 100 = 0.08s.
const el = { start: 0, duration: 10 };
const beats = [2, 5, 8];
it("snaps a keyframe within ~8px of a beat exactly onto it", () => {
// pct 50.5 → 5.05s, 0.05s from the beat at 5s (inside 0.08s window) → 50%.
expect(snapKeyframePctToBeat(el, 50.5, beats, 100)).toBe(50);
});
it("leaves a keyframe unchanged when no beat is within the window", () => {
// pct 55 → 5.5s, 0.5s from the nearest beat → free.
expect(snapKeyframePctToBeat(el, 55, beats, 100)).toBe(55);
});
it("is a no-op when there are no beats", () => {
expect(snapKeyframePctToBeat(el, 50.5, [], 100)).toBe(50.5);
expect(snapKeyframePctToBeat(el, 50.5, undefined, 100)).toBe(50.5);
});
it("is a no-op for a zero-duration clip", () => {
expect(snapKeyframePctToBeat({ start: 0, duration: 0 }, 50.5, beats, 100)).toBe(50.5);
});
it("widens the snap window as zoom (pps) decreases", () => {
// pct 53 → 5.3s, 0.3s from the beat at 5s. At pps=20 the window is 0.4s → snaps to 50%.
expect(snapKeyframePctToBeat(el, 53, beats, 20)).toBe(50);
});
});
@@ -1,5 +1,13 @@
import { formatTime } from "../lib/time";
import { roundToCenti } from "../../utils/rounding";
import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrder";
import { resolveTimelineLayerStackingMove } from "./timelineLayerDrag";
import type { TimelineStackingElement, TimelineStackingReorderIntent } from "./timelineStacking";
export {
type TimelineStackingElement,
type TimelineStackingReorderIntent,
} from "./timelineStacking";
const roundToCentiseconds = roundToCenti;
@@ -25,6 +33,12 @@ export interface TimelineMoveInput {
trackHeight: number;
maxStart: number;
trackOrder: number[];
layerOrder?: TimelineLayerId[];
timelineLayers?: StackingTimelineLayer[];
/** When provided, vertical movement is resolved as a z-index stacking reorder
* within `stackingElement`'s context instead of a raw track change. */
stackingElement?: TimelineStackingElement;
stackingElements?: TimelineStackingElement[];
}
export interface TimelineResizeInput {
@@ -73,7 +87,13 @@ export function resolveTimelineMove(
input: TimelineMoveInput,
clientX: number,
clientY: number,
): { start: number; track: number } {
): {
start: number;
track: number;
previewLayerId?: TimelineLayerId;
previewLayerIndex?: number;
stackingReorder?: TimelineStackingReorderIntent | null;
} {
const scrollDeltaX = (input.currentScrollLeft ?? 0) - (input.originScrollLeft ?? 0);
const scrollDeltaY = (input.currentScrollTop ?? 0) - (input.originScrollTop ?? 0);
const deltaTime =
@@ -81,6 +101,36 @@ export function resolveTimelineMove(
const trackDeltaRaw =
(clientY - input.originClientY + scrollDeltaY) / Math.max(input.trackHeight, 1);
const deltaTrack = Math.round(trackDeltaRaw);
const nextStart = clamp(
roundToCentiseconds(input.start + deltaTime),
0,
Math.max(0, input.maxStart),
);
// Stacking mode: the two axes never fight. Horizontal movement writes time
// (nextStart); vertical movement writes z-index. Lane/overlap resolution
// uses the clip's authored time span, NOT the dragged start — otherwise a
// diagonal drag that drifts the clip out of overlap silently flips the
// placement from "restack" to "join lane" and cancels the reorder.
if (input.stackingElement) {
const layerMove =
input.timelineLayers && input.layerOrder
? resolveTimelineLayerStackingMove({
element: { ...input.stackingElement, duration: input.duration },
layers: input.timelineLayers,
layerOrder: input.layerOrder,
trackDeltaRaw,
})
: null;
return {
start: nextStart,
track: input.track,
previewLayerId: layerMove?.previewLayerId,
previewLayerIndex: layerMove?.previewLayerIndex,
stackingReorder: layerMove?.stackingReorder ?? null,
};
}
const currentTrackIndex = Math.max(0, input.trackOrder.indexOf(input.track));
const desiredTrackIndex = currentTrackIndex + deltaTrack;
const nextTrackIndex = clamp(desiredTrackIndex, 0, Math.max(0, input.trackOrder.length - 1));
@@ -106,7 +156,7 @@ export function resolveTimelineMove(
}
return {
start: clamp(roundToCentiseconds(input.start + deltaTime), 0, Math.max(0, input.maxStart)),
start: nextStart,
track: nextTrack,
};
}
@@ -0,0 +1,200 @@
import { describe, expect, it } from "vitest";
import type { TimelineElement } from "../store/playerStore";
import type { StackingTimelineLayer } from "./timelineTrackOrder";
import {
resolveTimelineLayerStackingMove,
resolveTimelineLayerZIndexChanges,
} from "./timelineLayerDrag";
function element(input: {
id: string;
zIndex: number;
tag?: string;
start?: number;
duration?: number;
}): TimelineElement {
return {
id: input.id,
tag: input.tag ?? "div",
start: input.start ?? 0,
duration: input.duration ?? 1,
track: 0,
zIndex: input.zIndex,
hasExplicitZIndex: true,
stackingContextId: "root",
parentCompositionId: null,
compositionAncestors: ["root"],
};
}
function layer(
id: string,
zIndex: number,
elements: TimelineElement[] = [element({ id, zIndex })],
): StackingTimelineLayer {
return {
id,
kind: "visual",
contextKey: "root",
zIndex,
placementTrack: 0,
elements,
};
}
describe("resolveTimelineLayerZIndexChanges", () => {
it("joins an existing lane by assigning the dragged clip that lane's z-index", () => {
const dragged = element({ id: "dragged", zIndex: 1, start: 2, duration: 1 });
const front = element({ id: "front", zIndex: 10, start: 0, duration: 1 });
expect(
resolveTimelineLayerZIndexChanges({
element: dragged,
layers: [layer("front", 10, [front]), layer("back", 1)],
placement: { type: "onto", layerId: "front" },
})?.zIndexChanges,
).toEqual([{ key: "dragged", zIndex: 10 }]);
});
it("rejects an onto-lane join when the dragged clip would overlap that lane", () => {
const dragged = element({ id: "dragged", zIndex: 1, start: 0.5, duration: 1 });
const front = element({ id: "front", zIndex: 10, start: 0, duration: 1 });
expect(
resolveTimelineLayerZIndexChanges({
element: dragged,
layers: [layer("front", 10, [front]), layer("back", 1)],
placement: { type: "onto", layerId: "front" },
}),
).toBeNull();
});
it("interpolates a new integer z-index strictly between neighboring layers", () => {
const dragged = element({ id: "dragged", zIndex: 1 });
expect(
resolveTimelineLayerZIndexChanges({
element: dragged,
layers: [layer("front", 10), layer("back", 4)],
placement: { type: "between", beforeLayerId: "front", afterLayerId: "back" },
})?.zIndexChanges,
).toEqual([{ key: "dragged", zIndex: 7 }]);
});
it("renumbers the minimum sibling set when adjacent layers leave no integer gap", () => {
const dragged = element({ id: "dragged", zIndex: 0 });
expect(
resolveTimelineLayerZIndexChanges({
element: dragged,
layers: [layer("front", 2), layer("back", 1), layer("lower", 0)],
placement: { type: "between", beforeLayerId: "front", afterLayerId: "back" },
})?.zIndexChanges,
).toEqual([
{ key: "dragged", zIndex: 2 },
{ key: "front", zIndex: 3 },
]);
});
it("assigns new extreme z-index values above the top and below the bottom layer", () => {
const dragged = element({ id: "dragged", zIndex: 0 });
const layers = [layer("front", 10), layer("back", -2)];
expect(
resolveTimelineLayerZIndexChanges({
element: dragged,
layers,
placement: { type: "above", layerId: "front" },
})?.zIndexChanges,
).toEqual([{ key: "dragged", zIndex: 11 }]);
expect(
resolveTimelineLayerZIndexChanges({
element: dragged,
layers,
placement: { type: "below", layerId: "back" },
})?.zIndexChanges,
).toEqual([{ key: "dragged", zIndex: -3 }]);
});
it("does not resolve stacking z-index changes for audio clips", () => {
expect(
resolveTimelineLayerZIndexChanges({
element: element({ id: "music", zIndex: 0, tag: "audio" }),
layers: [layer("front", 10)],
placement: { type: "onto", layerId: "front" },
}),
).toBeNull();
});
});
describe("resolveTimelineLayerStackingMove", () => {
it("places an upward onto-lane drop above the overlapping target lane", () => {
const front = element({ id: "front", zIndex: 10, start: 0, duration: 2 });
const dragged = element({ id: "dragged", zIndex: 1, start: 0.5, duration: 1 });
const layers = [layer("front", 10, [front]), layer("dragged", 1, [dragged])];
expect(
resolveTimelineLayerStackingMove({
element: dragged,
layers,
layerOrder: layers.map((item) => item.id),
trackDeltaRaw: -0.8,
}),
).toEqual({
previewLayerId: "preview:dragged:above:front",
previewLayerIndex: 0,
stackingReorder: {
contextKey: "root",
placement: { type: "above", layerId: "front" },
zIndexChanges: [{ key: "dragged", zIndex: 11 }],
},
});
});
it("places a downward onto-lane drop below the overlapping target lane", () => {
const dragged = element({ id: "dragged", zIndex: 10, start: 0.5, duration: 1 });
const back = element({ id: "back", zIndex: 1, start: 0, duration: 2 });
const layers = [layer("dragged", 10, [dragged]), layer("back", 1, [back])];
expect(
resolveTimelineLayerStackingMove({
element: dragged,
layers,
layerOrder: layers.map((item) => item.id),
trackDeltaRaw: 0.8,
}),
).toEqual({
previewLayerId: "preview:dragged:below:back",
previewLayerIndex: 2,
stackingReorder: {
contextKey: "root",
placement: { type: "below", layerId: "back" },
zIndexChanges: [{ key: "dragged", zIndex: 0 }],
},
});
});
it("keeps a non-overlapping onto-lane drop joined to the target lane", () => {
const front = element({ id: "front", zIndex: 10, start: 0, duration: 1 });
const dragged = element({ id: "dragged", zIndex: 1, start: 2, duration: 1 });
const layers = [layer("front", 10, [front]), layer("dragged", 1, [dragged])];
expect(
resolveTimelineLayerStackingMove({
element: dragged,
layers,
layerOrder: layers.map((item) => item.id),
trackDeltaRaw: -0.8,
}),
).toEqual({
previewLayerId: "front",
previewLayerIndex: 0,
stackingReorder: {
contextKey: "root",
placement: { type: "onto", layerId: "front" },
zIndexChanges: [{ key: "dragged", zIndex: 10 }],
},
});
});
});
@@ -0,0 +1,383 @@
import { resolveStackingContextKey } from "../lib/layerOrdering";
import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
import {
timelineElementsOverlap,
type StackingTimelineLayer,
type TimelineLayerId,
} from "./timelineTrackOrder";
import {
toStackingOrderItem,
type TimelineLayerDropPlacement,
type TimelineStackingElement,
type TimelineStackingReorderIntent,
type TimelineStackingZIndexChange,
} from "./timelineStacking";
const ONTO_ROW_THRESHOLD = 0.35;
export interface TimelineLayerStackingMoveResolution {
previewLayerId: TimelineLayerId;
previewLayerIndex: number;
stackingReorder: TimelineStackingReorderIntent | null;
}
function isAudioElement(element: TimelineStackingElement): boolean {
return element.tag?.toLowerCase() === "audio";
}
function layerContainsElement(layer: StackingTimelineLayer, key: string): boolean {
return layer.elements.some((element) => getTimelineElementIdentity(element) === key);
}
function layerConflictsWithElement(
layer: StackingTimelineLayer,
element: TimelineStackingElement,
draggedKey: string,
): boolean {
return layer.elements.some(
(candidate) =>
getTimelineElementIdentity(candidate) !== draggedKey &&
timelineElementsOverlap(candidate, element),
);
}
function addElementChange(
changes: TimelineStackingZIndexChange[],
element: TimelineStackingElement,
zIndex: number,
): void {
if ((element.zIndex ?? 0) === zIndex) return;
changes.push({
key: getTimelineElementIdentity(element),
zIndex,
domId: element.domId,
selector: element.selector,
selectorIndex: element.selectorIndex,
sourceFile: element.sourceFile,
});
}
function addLayerChanges(
changes: TimelineStackingZIndexChange[],
layer: StackingTimelineLayer,
zIndex: number,
excludedKey: string,
): number {
let count = 0;
for (const element of layer.elements) {
const key = getTimelineElementIdentity(element);
if (key === excludedKey) continue;
const before = changes.length;
addElementChange(changes, element, zIndex);
if (changes.length > before) count += 1;
}
return count;
}
function getContextLayers(
layers: readonly StackingTimelineLayer[],
contextKey: string,
): StackingTimelineLayer[] {
return layers.filter((layer) => layer.kind === "visual" && layer.contextKey === contextKey);
}
function findLayer(
layers: readonly StackingTimelineLayer[],
id: string,
): StackingTimelineLayer | null {
return layers.find((layer) => layer.id === id) ?? null;
}
function resolvePlacementZIndexChanges(input: {
element: TimelineStackingElement;
targetZIndex: number;
}): TimelineStackingZIndexChange[] {
const changes: TimelineStackingZIndexChange[] = [];
addElementChange(changes, input.element, input.targetZIndex);
return changes;
}
function buildPushUpCandidate(input: {
element: TimelineStackingElement;
layers: readonly StackingTimelineLayer[];
beforeIndex: number;
bottomZIndex: number;
}): { changes: TimelineStackingZIndexChange[]; siblingChanges: number } {
const draggedKey = getTimelineElementIdentity(input.element);
const draggedZIndex = input.bottomZIndex + 1;
const changes = resolvePlacementZIndexChanges({
element: input.element,
targetZIndex: draggedZIndex,
});
let siblingChanges = 0;
let requiredZIndex = draggedZIndex + 1;
for (let index = input.beforeIndex; index >= 0; index -= 1) {
const layer = input.layers[index];
if (!layer) continue;
const nextZIndex = layer.zIndex >= requiredZIndex ? layer.zIndex : requiredZIndex;
siblingChanges += addLayerChanges(changes, layer, nextZIndex, draggedKey);
requiredZIndex = nextZIndex + 1;
}
return { changes, siblingChanges };
}
function buildPushDownCandidate(input: {
element: TimelineStackingElement;
layers: readonly StackingTimelineLayer[];
afterIndex: number;
topZIndex: number;
}): { changes: TimelineStackingZIndexChange[]; siblingChanges: number } {
const draggedKey = getTimelineElementIdentity(input.element);
const draggedZIndex = input.topZIndex - 1;
const changes = resolvePlacementZIndexChanges({
element: input.element,
targetZIndex: draggedZIndex,
});
let siblingChanges = 0;
let requiredZIndex = draggedZIndex - 1;
for (let index = input.afterIndex; index < input.layers.length; index += 1) {
const layer = input.layers[index];
if (!layer) continue;
const nextZIndex = layer.zIndex <= requiredZIndex ? layer.zIndex : requiredZIndex;
siblingChanges += addLayerChanges(changes, layer, nextZIndex, draggedKey);
requiredZIndex = nextZIndex - 1;
}
return { changes, siblingChanges };
}
function resolveBetweenChanges(input: {
element: TimelineStackingElement;
layers: readonly StackingTimelineLayer[];
beforeLayer: StackingTimelineLayer;
afterLayer: StackingTimelineLayer;
}): TimelineStackingZIndexChange[] {
const topZIndex = input.beforeLayer.zIndex;
const bottomZIndex = input.afterLayer.zIndex;
if (topZIndex - bottomZIndex > 1) {
return resolvePlacementZIndexChanges({
element: input.element,
targetZIndex: Math.floor((topZIndex + bottomZIndex) / 2),
});
}
const beforeIndex = input.layers.findIndex((layer) => layer.id === input.beforeLayer.id);
const afterIndex = input.layers.findIndex((layer) => layer.id === input.afterLayer.id);
const pushUp = buildPushUpCandidate({
element: input.element,
layers: input.layers,
beforeIndex,
bottomZIndex,
});
const pushDown = buildPushDownCandidate({
element: input.element,
layers: input.layers,
afterIndex,
topZIndex,
});
return pushUp.siblingChanges <= pushDown.siblingChanges ? pushUp.changes : pushDown.changes;
}
function resolveOntoChanges(input: {
element: TimelineStackingElement;
layers: readonly StackingTimelineLayer[];
layerId: string;
}): TimelineStackingZIndexChange[] | null {
const target = findLayer(input.layers, input.layerId);
if (!target) return null;
if (layerConflictsWithElement(target, input.element, getTimelineElementIdentity(input.element))) {
return null;
}
return resolvePlacementZIndexChanges({
element: input.element,
targetZIndex: target.zIndex,
});
}
function resolveEdgeChanges(input: {
element: TimelineStackingElement;
layers: readonly StackingTimelineLayer[];
layerId: string;
offset: number;
}): TimelineStackingZIndexChange[] | null {
const target = findLayer(input.layers, input.layerId);
if (!target) return null;
return resolvePlacementZIndexChanges({
element: input.element,
targetZIndex: target.zIndex + input.offset,
});
}
function resolvePlacementChanges(input: {
element: TimelineStackingElement;
layers: readonly StackingTimelineLayer[];
placement: TimelineLayerDropPlacement;
}): TimelineStackingZIndexChange[] | null {
switch (input.placement.type) {
case "onto":
return resolveOntoChanges({
element: input.element,
layers: input.layers,
layerId: input.placement.layerId,
});
case "above":
return resolveEdgeChanges({
element: input.element,
layers: input.layers,
layerId: input.placement.layerId,
offset: 1,
});
case "below":
return resolveEdgeChanges({
element: input.element,
layers: input.layers,
layerId: input.placement.layerId,
offset: -1,
});
case "between": {
const beforeLayer = findLayer(input.layers, input.placement.beforeLayerId);
const afterLayer = findLayer(input.layers, input.placement.afterLayerId);
return beforeLayer && afterLayer
? resolveBetweenChanges({
element: input.element,
layers: input.layers,
beforeLayer,
afterLayer,
})
: null;
}
}
}
export function resolveTimelineLayerZIndexChanges(input: {
element: TimelineStackingElement;
layers: readonly StackingTimelineLayer[];
placement: TimelineLayerDropPlacement;
}): TimelineStackingReorderIntent | null {
if (isAudioElement(input.element)) return null;
const contextKey = resolveStackingContextKey(toStackingOrderItem(input.element));
const layers = getContextLayers(input.layers, contextKey);
const changes = resolvePlacementChanges({
element: input.element,
layers,
placement: input.placement,
});
return changes && changes.length > 0
? { contextKey, placement: input.placement, zIndexChanges: changes }
: null;
}
// fallow-ignore-next-line complexity
function resolveDragPlacement(
layers: readonly StackingTimelineLayer[],
targetPosition: number,
): TimelineLayerDropPlacement | null {
const first = layers[0];
const last = layers[layers.length - 1];
if (!first || !last) return null;
if (targetPosition < -ONTO_ROW_THRESHOLD) return { type: "above", layerId: first.id };
if (targetPosition > layers.length - 1 + ONTO_ROW_THRESHOLD) {
return { type: "below", layerId: last.id };
}
const nearestIndex = Math.round(targetPosition);
const nearest = layers[nearestIndex];
if (nearest && Math.abs(targetPosition - nearestIndex) <= ONTO_ROW_THRESHOLD) {
return { type: "onto", layerId: nearest.id };
}
const insertionIndex = Math.max(0, Math.min(layers.length, Math.ceil(targetPosition)));
if (insertionIndex <= 0) return { type: "above", layerId: first.id };
if (insertionIndex >= layers.length) return { type: "below", layerId: last.id };
const before = layers[insertionIndex - 1];
const after = layers[insertionIndex];
return before && after
? { type: "between", beforeLayerId: before.id, afterLayerId: after.id }
: null;
}
function resolveLaneAwareDragPlacement(input: {
layers: readonly StackingTimelineLayer[];
element: TimelineStackingElement;
draggedKey: string;
placement: TimelineLayerDropPlacement;
targetPosition: number;
currentIndex: number;
}): TimelineLayerDropPlacement | null {
if (input.placement.type !== "onto") return input.placement;
const target = findLayer(input.layers, input.placement.layerId);
if (!target) return null;
if (!layerConflictsWithElement(target, input.element, input.draggedKey)) return input.placement;
if (input.targetPosition < input.currentIndex) {
return { type: "above", layerId: target.id };
}
if (input.targetPosition > input.currentIndex) {
return { type: "below", layerId: target.id };
}
return input.placement;
}
function getPreviewLayerId(
draggedKey: string,
placement: TimelineLayerDropPlacement,
): TimelineLayerId {
if (placement.type === "onto") return placement.layerId;
if (placement.type === "between") {
return `preview:${draggedKey}:between:${placement.beforeLayerId}:${placement.afterLayerId}`;
}
return `preview:${draggedKey}:${placement.type}:${placement.layerId}`;
}
function getPreviewLayerIndex(
layerOrder: readonly TimelineLayerId[],
placement: TimelineLayerDropPlacement,
): number {
if (placement.type === "onto") return Math.max(0, layerOrder.indexOf(placement.layerId));
if (placement.type === "between") {
return Math.max(0, layerOrder.indexOf(placement.afterLayerId));
}
const targetIndex = Math.max(0, layerOrder.indexOf(placement.layerId));
return placement.type === "above" ? targetIndex : targetIndex + 1;
}
export function resolveTimelineLayerStackingMove(input: {
element: TimelineStackingElement;
layers: readonly StackingTimelineLayer[];
layerOrder: readonly TimelineLayerId[];
trackDeltaRaw: number;
}): TimelineLayerStackingMoveResolution | null {
if (isAudioElement(input.element)) return null;
const contextKey = resolveStackingContextKey(toStackingOrderItem(input.element));
const layerById = new Map(input.layers.map((layer) => [layer.id, layer]));
const contextLayers = input.layerOrder
.map((id) => layerById.get(id) ?? null)
.filter(
(layer): layer is StackingTimelineLayer =>
layer != null && layer.kind === "visual" && layer.contextKey === contextKey,
);
const draggedKey = getTimelineElementIdentity(input.element);
const currentIndex = contextLayers.findIndex((layer) => layerContainsElement(layer, draggedKey));
if (currentIndex < 0) return null;
const targetPosition = currentIndex + input.trackDeltaRaw;
const rawPlacement = resolveDragPlacement(contextLayers, targetPosition);
if (!rawPlacement) return null;
const placement = resolveLaneAwareDragPlacement({
layers: contextLayers,
element: input.element,
draggedKey,
placement: rawPlacement,
targetPosition,
currentIndex,
});
if (!placement) return null;
return {
previewLayerId: getPreviewLayerId(draggedKey, placement),
previewLayerIndex: getPreviewLayerIndex(input.layerOrder, placement),
stackingReorder: resolveTimelineLayerZIndexChanges({
element: input.element,
layers: contextLayers,
placement,
}),
};
}
@@ -0,0 +1,34 @@
import { describe, expect, it } from "vitest";
import { computeTimelineBasisDuration, computeTimelineEffectiveDuration } from "./timelineLayout";
describe("computeTimelineBasisDuration", () => {
it("uses the root duration when it exceeds every clip end", () => {
expect(computeTimelineBasisDuration(12, [4, 6, 9])).toBe(12);
});
it("grows to the furthest committed clip end past the root duration", () => {
expect(computeTimelineBasisDuration(12, [4, 18, 9])).toBe(18);
});
it("falls back to the root duration with no clips / non-finite ends", () => {
expect(computeTimelineBasisDuration(10, [])).toBe(10);
expect(computeTimelineBasisDuration(Number.NaN, [])).toBe(0);
});
});
describe("computeTimelineEffectiveDuration", () => {
it("returns the basis when there is no active preview", () => {
expect(computeTimelineEffectiveDuration(12, [null, null])).toBe(12);
});
it("extends to a drag/resize preview end beyond the basis", () => {
expect(computeTimelineEffectiveDuration(12, [20, null])).toBe(20);
expect(computeTimelineEffectiveDuration(12, [null, 16])).toBe(16);
});
it("never shrinks below the basis for a preview inside the current length", () => {
// The invariant behind the jump fix: the basis (which drives zoom) is
// independent of the preview, and a smaller preview end can't reduce it.
expect(computeTimelineEffectiveDuration(12, [8])).toBe(12);
});
});
@@ -9,6 +9,37 @@ export const CLIP_Y = 3;
export const CLIP_HANDLE_W = 18;
const TIMELINE_SCROLL_BUFFER = 20;
/* ── Timeline duration ─────────────────────────────────────────────── */
// Committed timeline length: root duration or the furthest committed clip end,
// with NO live drag/resize preview. This drives the zoom (fit-to-width pps) so
// the pixels-per-second mapping stays fixed while you drag — otherwise a clip
// dragged past the end grows the duration, shrinks pps, and jumps under the
// pointer (a positive-feedback loop). The zoom re-fits once on drop.
export function computeTimelineBasisDuration(
rootDuration: number,
clipEnds: readonly number[],
): number {
const safeDur = Number.isFinite(rootDuration) ? rootDuration : 0;
if (clipEnds.length === 0) return safeDur;
const maxEnd = Math.max(safeDur, ...clipEnds);
return Number.isFinite(maxEnd) ? maxEnd : safeDur;
}
// Displayed length: the basis plus any active drag/resize preview end, so the
// ruler and track width grow to follow a clip dragged past the current end
// (with the zoom held fixed, the extra length becomes scrollable content).
export function computeTimelineEffectiveDuration(
basisDuration: number,
previewEnds: readonly (number | null)[],
): number {
let maxEnd = basisDuration;
for (const end of previewEnds) {
if (end != null && Number.isFinite(end)) maxEnd = Math.max(maxEnd, end);
}
return maxEnd;
}
/* ── Tick generation ──────────────────────────────────────────────── */
function getMajorTickInterval(duration: number, pixelsPerSecond?: number): number {
const zoomIntervals = [0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600];
@@ -56,6 +87,22 @@ export function generateTicks(
return { major, minor };
}
/**
* Ticks spanning the full visible ruler width, not just the composition, so a
* zoomed-out ruler stays filled with labels instead of ending mid-panel. The
* major/minor interval is driven by pixelsPerSecond (pixel spacing), so widening
* the range keeps spacing identical — it only adds ticks past the content end.
*/
export function generateVisibleTicks(
effectiveDuration: number,
pixelsPerSecond: number,
viewportWidth: number,
gutter: number,
): { major: number[]; minor: number[] } {
const visible = viewportWidth > gutter ? (viewportWidth - gutter) / pixelsPerSecond : 0;
return generateTicks(Math.max(effectiveDuration, visible), pixelsPerSecond);
}
export function formatTimelineTickLabel(time: number, duration: number, majorInterval: number) {
if (!Number.isFinite(time)) return "0:00";
const safeTime = Math.max(0, time);
@@ -0,0 +1,121 @@
import { describe, expect, it } from "vitest";
import type { TimelineElement } from "../store/playerStore";
import {
buildTimelineSnapTargets,
snapEdgesToTargets,
snapResizeEdgeToTargets,
} from "./timelineSnapTargets";
function timelineElement(input: {
id: string;
key?: string;
start: number;
duration: number;
}): TimelineElement {
return {
id: input.id,
key: input.key,
tag: "div",
start: input.start,
duration: input.duration,
track: 0,
};
}
describe("buildTimelineSnapTargets", () => {
it("excludes the dragged clip's own edges", () => {
const dragged = timelineElement({
id: "dragged-id",
key: "dragged-key",
start: 1,
duration: 2,
});
const other = timelineElement({ id: "other", start: 4, duration: 2 });
const targets = buildTimelineSnapTargets({
elements: [dragged, other],
draggedKey: "dragged-key",
playhead: 8,
compDuration: 10,
beats: [1.5],
});
const times = targets.map((target) => target.time);
expect(times).not.toContain(1);
expect(times).not.toContain(3);
expect(times).toContain(4);
expect(times).toContain(6);
});
it("dedupes near-equal times from different sources", () => {
const dragged = timelineElement({ id: "dragged", start: 2, duration: 2 });
const other = timelineElement({ id: "other", start: 0.0004, duration: 10 });
const targets = buildTimelineSnapTargets({
elements: [dragged, other],
draggedKey: "dragged",
playhead: 5,
compDuration: 10,
beats: [0.0002, 10.0002],
});
expect(targets.filter((target) => Math.abs(target.time) < 0.001)).toHaveLength(1);
expect(targets.filter((target) => Math.abs(target.time - 10) < 0.001)).toHaveLength(1);
});
});
describe("snapEdgesToTargets", () => {
it("snaps the start edge to another clip's end", () => {
const snap = snapEdgesToTargets(3.95, 2, [{ time: 4, kind: "edge" }], 100);
expect(snap).toEqual({ start: 4, snapTime: 4, snapKind: "edge" });
});
it("snaps the end edge to another clip's start", () => {
const snap = snapEdgesToTargets(2.96, 2, [{ time: 5, kind: "edge" }], 100);
expect(snap).toEqual({ start: 3, snapTime: 5, snapKind: "edge" });
});
it("snaps to the playhead", () => {
const snap = snapEdgesToTargets(2.94, 1, [{ time: 3, kind: "playhead" }], 100);
expect(snap).toEqual({ start: 3, snapTime: 3, snapKind: "playhead" });
});
it("snaps the start edge to the lower composition bound", () => {
const snap = snapEdgesToTargets(0.04, 1, [{ time: 0, kind: "bound" }], 100);
expect(snap).toEqual({ start: 0, snapTime: 0, snapKind: "bound" });
});
it("snaps the end edge to the upper composition bound", () => {
const snap = snapEdgesToTargets(7.96, 2, [{ time: 10, kind: "bound" }], 100);
expect(snap).toEqual({ start: 8, snapTime: 10, snapKind: "bound" });
});
it("does not snap when targets are beyond the pixel threshold", () => {
const snap = snapEdgesToTargets(3.9, 1, [{ time: 4, kind: "edge" }], 100);
expect(snap).toEqual({ start: 3.9, snapTime: null, snapKind: null });
});
});
describe("snapResizeEdgeToTargets", () => {
it("does not apply end-edge snaps past maxEnd or below minDuration", () => {
expect(
snapResizeEdgeToTargets("end", 4, 2.95, [{ time: 7.01, kind: "edge" }], 100, {
minDuration: 0.05,
maxEnd: 7,
}),
).toEqual({ start: 4, duration: 2.95, snapTime: null, snapKind: null });
expect(
snapResizeEdgeToTargets("end", 4, 0.1, [{ time: 4.03, kind: "edge" }], 100, {
minDuration: 0.05,
maxEnd: 10,
}),
).toEqual({ start: 4, duration: 0.1, snapTime: null, snapKind: null });
});
});
@@ -0,0 +1,163 @@
import type { TimelineElement } from "../store/playerStore";
export type TimelineSnapKind = "beat" | "edge" | "playhead" | "bound";
export interface TimelineSnapTarget {
time: number;
kind: TimelineSnapKind;
}
interface NearestSnap {
target: TimelineSnapTarget;
distance: number;
}
const SNAP_PX = 8;
const DEDUPE_EPSILON_SECONDS = 0.001;
const ROUND_FACTOR = 1000;
const KIND_PRIORITY: Record<TimelineSnapKind, number> = {
bound: 0,
playhead: 1,
edge: 2,
beat: 3,
};
function roundToMillis(value: number): number {
return Math.round(value * ROUND_FACTOR) / ROUND_FACTOR;
}
function addTarget(targets: TimelineSnapTarget[], candidate: TimelineSnapTarget) {
if (!Number.isFinite(candidate.time)) return;
const existingIndex = targets.findIndex(
(target) => Math.abs(target.time - candidate.time) < DEDUPE_EPSILON_SECONDS,
);
if (existingIndex === -1) {
targets.push(candidate);
return;
}
const existing = targets[existingIndex];
if (!existing || KIND_PRIORITY[candidate.kind] >= KIND_PRIORITY[existing.kind]) return;
targets[existingIndex] = candidate;
}
export function buildTimelineSnapTargets(input: {
elements: TimelineElement[];
draggedKey: string;
playhead: number;
compDuration: number;
beats: number[];
}): TimelineSnapTarget[] {
const targets: TimelineSnapTarget[] = [];
addTarget(targets, { time: 0, kind: "bound" });
addTarget(targets, { time: Math.max(0, input.compDuration), kind: "bound" });
addTarget(targets, { time: Math.max(0, input.playhead), kind: "playhead" });
for (const element of input.elements) {
const elementKey = element.key ?? element.id;
if (elementKey === input.draggedKey || element.id === input.draggedKey) continue;
addTarget(targets, { time: element.start, kind: "edge" });
addTarget(targets, { time: element.start + element.duration, kind: "edge" });
}
for (const beat of input.beats) {
addTarget(targets, { time: beat, kind: "beat" });
}
return targets.sort((a, b) => a.time - b.time || KIND_PRIORITY[a.kind] - KIND_PRIORITY[b.kind]);
}
function nearestSnap(
time: number,
targets: TimelineSnapTarget[],
thresholdSeconds: number,
): NearestSnap | null {
let best: NearestSnap | null = null;
let bestDistance = thresholdSeconds;
for (const target of targets) {
if (target.time === time) continue;
const distance = Math.abs(target.time - time);
if (distance < bestDistance) {
bestDistance = distance;
best = { target, distance };
}
}
return best;
}
export function snapEdgesToTargets(
start: number,
duration: number,
targets: TimelineSnapTarget[],
pixelsPerSecond: number,
options?: { maxStart?: number },
): { start: number; snapTime: number | null; snapKind: TimelineSnapKind | null } {
const thresholdSeconds = SNAP_PX / Math.max(pixelsPerSecond, 1);
const startSnap = nearestSnap(start, targets, thresholdSeconds);
const endSnap = nearestSnap(start + duration, targets, thresholdSeconds);
let candidate = start;
let snapTarget: TimelineSnapTarget | null = null;
if (startSnap && (!endSnap || startSnap.distance <= endSnap.distance)) {
candidate = startSnap.target.time;
snapTarget = startSnap.target;
} else if (endSnap) {
candidate = endSnap.target.time - duration;
snapTarget = endSnap.target;
}
const maxStart = options?.maxStart ?? Number.POSITIVE_INFINITY;
const upperStart = Number.isFinite(maxStart) ? Math.max(0, maxStart) : Number.POSITIVE_INFINITY;
const clamped = Math.max(0, Math.min(upperStart, roundToMillis(candidate)));
if (snapTarget && Math.abs(clamped - candidate) > 1e-6) {
return { start: clamped, snapTime: null, snapKind: null };
}
return {
start: clamped,
snapTime: snapTarget?.time ?? null,
snapKind: snapTarget?.kind ?? null,
};
}
export function snapResizeEdgeToTargets(
edge: "start" | "end",
start: number,
duration: number,
targets: TimelineSnapTarget[],
pixelsPerSecond: number,
limits: { minDuration: number; maxEnd: number; maxLeftDelta?: number },
): { start: number; duration: number; snapTime: number | null; snapKind: TimelineSnapKind | null } {
const thresholdSeconds = SNAP_PX / Math.max(pixelsPerSecond, 1);
if (edge === "end") {
const snap = nearestSnap(start + duration, targets, thresholdSeconds);
if (!snap) return { start, duration, snapTime: null, snapKind: null };
const snappedDuration = roundToMillis(snap.target.time - start);
if (snap.target.time > limits.maxEnd + 1e-6 || snappedDuration < limits.minDuration) {
return { start, duration, snapTime: null, snapKind: null };
}
return {
start,
duration: snappedDuration,
snapTime: snap.target.time,
snapKind: snap.target.kind,
};
}
const snap = nearestSnap(start, targets, thresholdSeconds);
if (!snap) return { start, duration, snapTime: null, snapKind: null };
const snappedStart = roundToMillis(snap.target.time);
const delta = start - snappedStart;
const snappedDuration = roundToMillis(duration + delta);
const maxLeftDelta = limits.maxLeftDelta ?? Number.POSITIVE_INFINITY;
if (snappedStart < 0 || delta > maxLeftDelta + 1e-6 || snappedDuration < limits.minDuration) {
return { start, duration, snapTime: null, snapKind: null };
}
return {
start: snappedStart,
duration: snappedDuration,
snapTime: snap.target.time,
snapKind: snap.target.kind,
};
}
@@ -0,0 +1,62 @@
import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
export interface TimelineStackingElement {
id: string;
key?: string;
tag?: string;
start: number;
duration: number;
track: number;
zIndex?: number;
stackingContextId?: string | null;
parentCompositionId?: string | null;
compositionAncestors?: string[];
// Locator for resolving the live element at commit time (sub-comp children
// aren't in the top-level element list, so the reorder intent must be
// self-contained rather than re-looked-up by identity).
domId?: string;
selector?: string;
selectorIndex?: number;
sourceFile?: string;
}
export interface TimelineStackingOrderItem {
key: string;
track: number;
zIndex: number;
stackingContextId: string | null;
parentCompositionId: string | null;
compositionAncestors: readonly string[];
}
export type TimelineLayerDropPlacement =
| { type: "onto"; layerId: string }
| { type: "between"; beforeLayerId: string; afterLayerId: string }
| { type: "above"; layerId: string }
| { type: "below"; layerId: string };
export interface TimelineStackingZIndexChange {
key: string;
zIndex: number;
domId?: string;
selector?: string;
selectorIndex?: number;
sourceFile?: string;
}
export interface TimelineStackingReorderIntent {
contextKey: string;
placement: TimelineLayerDropPlacement;
zIndexChanges: TimelineStackingZIndexChange[];
}
export function toStackingOrderItem(element: TimelineStackingElement): TimelineStackingOrderItem {
return {
key: getTimelineElementIdentity(element),
track: element.track,
zIndex: element.zIndex ?? 0,
stackingContextId: element.stackingContextId ?? null,
parentCompositionId: element.parentCompositionId ?? null,
compositionAncestors: element.compositionAncestors ?? [],
};
}
@@ -0,0 +1,144 @@
import { describe, expect, it } from "vitest";
import type { TimelineElement } from "../store/playerStore";
import { buildStackingTimelineLayers, insertPreviewTrackOrder } from "./timelineTrackOrder";
// fallow-ignore-next-line complexity
function rowElement(input: {
id: string;
track?: number;
zIndex?: number;
hasExplicitZIndex?: boolean;
start?: number;
duration?: number;
tag?: string;
stackingContextId?: string | null;
parentCompositionId?: string | null;
compositionAncestors?: string[];
}): TimelineElement {
return {
id: input.id,
tag: input.tag ?? "div",
start: input.start ?? 0,
duration: input.duration ?? 1,
track: input.track ?? 0,
zIndex: input.zIndex ?? 0,
hasExplicitZIndex: input.hasExplicitZIndex ?? true,
stackingContextId: input.stackingContextId ?? "root",
parentCompositionId: input.parentCompositionId ?? null,
compositionAncestors: input.compositionAncestors ?? ["root"],
};
}
function rowIds(rows: readonly { elements: readonly TimelineElement[] }[]): string[][] {
return rows.map((row) => row.elements.map((element) => element.id));
}
describe("buildStackingTimelineLayers", () => {
it("splits non-overlapping clips into separate lanes when their z-index differs", () => {
// A lane is a z-band: differing z must land on different rows even when the
// clips don't overlap in time, so a vertical (z) restack actually moves the
// clip's row. Rows are ordered by descending z.
const result = buildStackingTimelineLayers([
rowElement({ id: "back", zIndex: 1, start: 0, duration: 1 }),
rowElement({ id: "front", zIndex: 10, start: 1, duration: 1 }),
]);
expect(rowIds(result.visualLayers)).toEqual([["front"], ["back"]]);
expect(result.visualLayers[0]?.zIndex).toBe(10);
});
it("packs non-overlapping clips into one lane when they share a z-index", () => {
const result = buildStackingTimelineLayers([
rowElement({ id: "back", zIndex: 5, start: 0, duration: 1 }),
rowElement({ id: "front", zIndex: 5, start: 1, duration: 1 }),
]);
expect(rowIds(result.visualLayers)).toEqual([["back", "front"]]);
expect(result.visualLayers[0]?.zIndex).toBe(5);
});
it("splits clips into separate lanes when they overlap in time", () => {
const result = buildStackingTimelineLayers([
rowElement({ id: "front", zIndex: 10, start: 0, duration: 2 }),
rowElement({ id: "back", zIndex: 1, start: 1, duration: 2 }),
]);
expect(rowIds(result.visualLayers)).toEqual([["front"], ["back"]]);
});
it("uses DOM order to break stacking ties before lane packing", () => {
const result = buildStackingTimelineLayers([
rowElement({ id: "first", track: 2, zIndex: 5, start: 0, duration: 2 }),
rowElement({ id: "second", track: 0, zIndex: 5, start: 1, duration: 2 }),
]);
expect(rowIds(result.visualLayers)).toEqual([["first"], ["second"]]);
});
it("packs auto-z clips by time instead of forcing one row per clip", () => {
const result = buildStackingTimelineLayers([
rowElement({ id: "a", zIndex: 0, hasExplicitZIndex: false, start: 0, duration: 1 }),
rowElement({ id: "b", zIndex: 0, hasExplicitZIndex: false, start: 1, duration: 1 }),
]);
expect(rowIds(result.visualLayers)).toEqual([["a", "b"]]);
});
it("does not merge equal z-index clips across stacking contexts", () => {
const result = buildStackingTimelineLayers([
rowElement({ id: "root", zIndex: 4, start: 0, duration: 1 }),
rowElement({
id: "nested",
zIndex: 4,
start: 1,
duration: 1,
stackingContextId: "scene",
parentCompositionId: "scene",
compositionAncestors: ["root", "scene"],
}),
]);
expect(rowIds(result.visualLayers)).toEqual([["root"], ["nested"]]);
});
it("returns audio clips as separate bottom rows without merging them into z layers", () => {
const result = buildStackingTimelineLayers([
rowElement({ id: "front", zIndex: 10 }),
rowElement({ id: "music-a", tag: "audio", track: 4 }),
rowElement({ id: "music-b", tag: "audio", track: 2 }),
]);
expect(rowIds(result.visualLayers)).toEqual([["front"]]);
expect(rowIds(result.audioLayers)).toEqual([["music-a"], ["music-b"]]);
expect(rowIds(result.rows)).toEqual([["front"], ["music-a"], ["music-b"]]);
});
it("orders rows by descending z-index with auto-z clips ranked at computed zero", () => {
const result = buildStackingTimelineLayers([
rowElement({ id: "auto-a", zIndex: 0, hasExplicitZIndex: false }),
rowElement({ id: "back", zIndex: -1 }),
rowElement({ id: "front", zIndex: 10 }),
rowElement({ id: "auto-b", zIndex: 0, hasExplicitZIndex: false }),
]);
expect(rowIds(result.visualLayers)).toEqual([["front"], ["auto-a"], ["auto-b"], ["back"]]);
});
it("keeps a row key stable when a clip's z-index changes but membership does not", () => {
const before = buildStackingTimelineLayers([rowElement({ id: "hero", zIndex: 1 })]);
const after = buildStackingTimelineLayers([rowElement({ id: "hero", zIndex: 20 })]);
expect(after.visualLayers[0]?.id).toBe(before.visualLayers[0]?.id);
});
});
describe("insertPreviewTrackOrder", () => {
it("inserts preview layer ids by target row index", () => {
expect(insertPreviewTrackOrder(["a", "b", "c"], "preview", 1)).toEqual([
"a",
"preview",
"b",
"c",
]);
});
});
@@ -0,0 +1,173 @@
import { type TimelineElement } from "../store/playerStore";
import { resolveContextOrder, resolveStackingContextKey } from "../lib/layerOrdering";
import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
import { toStackingOrderItem, type TimelineStackingOrderItem } from "./timelineStacking";
export type TimelineLayerId = string;
export interface StackingTimelineLayer {
id: TimelineLayerId;
kind: "visual" | "audio";
contextKey: string;
zIndex: number;
placementTrack: number;
elements: TimelineElement[];
}
export interface StackingTimelineLayerGroups {
visualLayers: StackingTimelineLayer[];
audioLayers: StackingTimelineLayer[];
rows: StackingTimelineLayer[];
}
type TimelineLayerOrderItem = TimelineStackingOrderItem & {
start: number;
duration: number;
index: number;
element: TimelineElement;
};
type BuildLayer = Omit<StackingTimelineLayer, "id">;
function toTimelineLayerOrderItem(element: TimelineElement, index: number): TimelineLayerOrderItem {
return {
...toStackingOrderItem(element),
start: element.start,
duration: element.duration,
index,
element,
};
}
export function timelineElementsOverlap(
a: Pick<TimelineElement, "start" | "duration">,
b: Pick<TimelineElement, "start" | "duration">,
): boolean {
return a.start < b.start + b.duration && b.start < a.start + a.duration;
}
function compareLayerItems(a: TimelineLayerOrderItem, b: TimelineLayerOrderItem): number {
if (a.zIndex !== b.zIndex) return b.zIndex - a.zIndex;
return a.index - b.index;
}
function buildElementLayerId(
prefix: string,
contextKey: string,
element: TimelineElement,
): TimelineLayerId {
return `${prefix}:${contextKey}:${getTimelineElementIdentity(element)}`;
}
function buildLaneId(
prefix: string,
contextKey: string,
elements: TimelineElement[],
): TimelineLayerId {
const memberKey = elements.map(getTimelineElementIdentity).sort().join("|");
return `${prefix}:${contextKey}:${memberKey}`;
}
function getOrderedContextKeys(items: readonly TimelineLayerOrderItem[]): string[] {
const keys: string[] = [];
for (const item of resolveContextOrder(items)) {
const key = resolveStackingContextKey(item);
if (!keys.includes(key)) keys.push(key);
}
return keys;
}
function canJoinLayer(layer: BuildLayer, item: TimelineLayerOrderItem): boolean {
// A row IS a z-band: clips only share a lane when they carry the same z-index
// (and don't overlap in time). Without the z-index gate a non-overlapping clip
// greedily packs into the first time-compatible row — the topmost one — so a
// vertical restack changes z but the row never follows it.
return (
layer.contextKey === resolveStackingContextKey(item) &&
layer.zIndex === item.zIndex &&
layer.elements.every((element) => !timelineElementsOverlap(element, item.element))
);
}
function compareElementsByStart(a: TimelineElement, b: TimelineElement): number {
if (a.start !== b.start) return a.start - b.start;
return getTimelineElementIdentity(a).localeCompare(getTimelineElementIdentity(b));
}
function buildVisualLayerRows(items: readonly TimelineLayerOrderItem[]): StackingTimelineLayer[] {
const byContext = new Map<string, TimelineLayerOrderItem[]>();
for (const item of items) {
const key = resolveStackingContextKey(item);
const list = byContext.get(key);
if (list) list.push(item);
else byContext.set(key, [item]);
}
const rows: StackingTimelineLayer[] = [];
for (const contextKey of getOrderedContextKeys(items)) {
const contextRows: BuildLayer[] = [];
const contextItems = [...(byContext.get(contextKey) ?? [])].sort(compareLayerItems);
for (const item of contextItems) {
const existing = contextRows.find((row) => canJoinLayer(row, item));
if (existing) {
existing.elements.push(item.element);
existing.zIndex = Math.max(existing.zIndex, item.zIndex);
continue;
}
contextRows.push({
kind: "visual",
contextKey,
zIndex: item.zIndex,
placementTrack: item.element.track,
elements: [item.element],
});
}
rows.push(
...contextRows.map((row) => {
const elements = [...row.elements].sort(compareElementsByStart);
return {
...row,
id: buildLaneId("lane", contextKey, elements),
elements,
};
}),
);
}
return rows;
}
function buildAudioLayerRows(items: readonly TimelineLayerOrderItem[]): StackingTimelineLayer[] {
return items.map((item) => ({
id: buildElementLayerId("audio", resolveStackingContextKey(item), item.element),
kind: "audio",
contextKey: resolveStackingContextKey(item),
zIndex: item.zIndex,
placementTrack: item.element.track,
elements: [item.element],
}));
}
export function buildStackingTimelineLayers(
elements: readonly TimelineElement[],
): StackingTimelineLayerGroups {
const items = elements.map(toTimelineLayerOrderItem);
const visualItems = items.filter((item) => item.element.tag !== "audio");
const audioItems = items.filter((item) => item.element.tag === "audio");
const visualLayers = buildVisualLayerRows(visualItems);
const audioLayers = buildAudioLayerRows(audioItems);
return {
visualLayers,
audioLayers,
rows: [...visualLayers, ...audioLayers],
};
}
export function insertPreviewTrackOrder(
layerOrder: readonly TimelineLayerId[],
previewLayerId: TimelineLayerId,
previewIndex: number,
): TimelineLayerId[] {
if (layerOrder.includes(previewLayerId)) return [...layerOrder];
const index = Math.max(0, Math.min(layerOrder.length, Math.round(previewIndex)));
return [...layerOrder.slice(0, index), previewLayerId, ...layerOrder.slice(index)];
}
@@ -78,6 +78,26 @@ describe("updateTimelineActiveClipClasses", () => {
expect(previous).toEqual(new Set());
});
it("re-applies data-active to a fresh DOM node that stayed active across a re-render", () => {
// A clip that moves lanes on a reorder remounts as a new element. It stays
// in the previous active set, so the plain diff would skip it and leave the
// new node without data-active. syncAll must force the attribute on.
const container = document.createElement("div");
appendClip(container, "hero", "0", "5");
const previous = new Set<string>();
updateTimelineActiveClipClasses(container, previous, 2);
expect(previous).toEqual(new Set(["hero"]));
// Simulate a remount: replace the hero clip's DOM node (no data-active).
container.replaceChildren();
const heroReborn = appendClip(container, "hero", "0", "5");
expect(heroReborn.hasAttribute("data-active")).toBe(false);
// Diff-only would skip it (still active → unchanged); syncAll re-applies.
updateTimelineActiveClipClasses(container, previous, 2, true);
expect(heroReborn.hasAttribute("data-active")).toBe(true);
});
it("ignores clips with invalid timing data", () => {
const container = document.createElement("div");
const missingId = appendClip(container, "", "0", "2");
@@ -65,13 +65,23 @@ function setsMatch(left: Set<string>, right: Set<string>): boolean {
return true;
}
function applyActiveClipDiff(records: ActiveClipRecord[], previous: Set<string>, time: number) {
function applyActiveClipDiff(
records: ActiveClipRecord[],
previous: Set<string>,
time: number,
// Force every record's attribute to match its active state instead of only
// touching clips whose active-state changed. Required whenever `records` were
// freshly re-queried after a render: a clip that stayed active but got a new
// DOM node (e.g. moved lanes on a reorder) would otherwise be skipped by the
// diff and render without `data-active` despite still being at the playhead.
syncAll = false,
) {
const next = getActiveClipIds(records, time);
const changed = !setsMatch(previous, next);
for (const record of records) {
const wasActive = previous.has(record.id);
const isActive = next.has(record.id);
if (wasActive === isActive) continue;
if (!syncAll && wasActive === isActive) continue;
record.element.toggleAttribute("data-active", isActive);
}
previous.clear();
@@ -83,8 +93,9 @@ export function updateTimelineActiveClipClasses(
container: HTMLElement,
previous: Set<string>,
time: number,
syncAll = false,
) {
applyActiveClipDiff(collectTimelineClipRecords(container), previous, time);
applyActiveClipDiff(collectTimelineClipRecords(container), previous, time, syncAll);
}
export function useTimelineActiveClips({
@@ -107,7 +118,7 @@ export function useTimelineActiveClips({
}
recordsRef.current = collectTimelineClipRecords(scroll);
recordsByIdRef.current = indexClipRecordsById(recordsRef.current);
applyActiveClipDiff(recordsRef.current, previousActiveIdsRef.current, time);
applyActiveClipDiff(recordsRef.current, previousActiveIdsRef.current, time, true);
},
[scrollRef],
);
@@ -0,0 +1,233 @@
// @vitest-environment happy-dom
import React, { act } from "react";
import { createRoot } from "react-dom/client";
import { afterEach, describe, expect, it, vi } from "vitest";
import type { TimelineElement } from "../store/playerStore";
import { usePlayerStore } from "../store/playerStore";
import { TRACK_H } from "./timelineLayout";
import { buildStackingTimelineLayers } from "./timelineTrackOrder";
import type { DraggedClipState, ResizingClipState } from "./useTimelineClipDrag";
import { useTimelineClipDrag } from "./useTimelineClipDrag";
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
function timelineElement(input: {
id: string;
track: number;
zIndex: number;
start?: number;
duration?: number;
sourceDuration?: number;
}): TimelineElement {
return {
id: input.id,
domId: input.id,
tag: "div",
start: input.start ?? 0,
duration: input.duration ?? 2,
sourceDuration: input.sourceDuration,
track: input.track,
zIndex: input.zIndex,
stackingContextId: "root",
parentCompositionId: null,
compositionAncestors: ["root"],
sourceFile: "index.html",
timingSource: "authored",
};
}
afterEach(() => {
document.body.innerHTML = "";
usePlayerStore.getState().reset();
});
function renderDragHarness(elements: TimelineElement[]) {
const layers = buildStackingTimelineLayers(elements).rows;
const scroll = document.createElement("div");
document.body.append(scroll);
const onMoveElement = vi.fn();
const onResizeElement = vi.fn();
let setDraggedClip: ((state: DraggedClipState | null) => void) | null = null;
let setResizingClip: ((state: ResizingClipState | null) => void) | null = null;
function Harness() {
const hook = useTimelineClipDrag({
scrollRef: { current: scroll },
ppsRef: { current: 100 },
trackOrderRef: { current: layers.map((layer) => layer.id) },
timelineLayersRef: { current: layers },
timelineElementsRef: { current: elements },
onMoveElement,
onResizeElement,
onBlockedEditAttempt: vi.fn(),
setShowPopover: vi.fn(),
setRangeSelectionRef: { current: vi.fn() },
});
setDraggedClip = hook.setDraggedClip;
setResizingClip = hook.setResizingClip;
return null;
}
const host = document.createElement("div");
document.body.append(host);
const root = createRoot(host);
act(() => {
root.render(<Harness />);
});
if (!setDraggedClip) throw new Error("Expected drag setter");
if (!setResizingClip) throw new Error("Expected resize setter");
const applyDraggedClip: (state: DraggedClipState | null) => void = setDraggedClip;
const applyResizingClip: (state: ResizingClipState | null) => void = setResizingClip;
return {
layers,
onMoveElement,
onResizeElement,
startDrag(element: TimelineElement, layerIndex: number) {
act(() => {
applyDraggedClip({
element,
originClientX: 0,
originClientY: 0,
originScrollLeft: 0,
originScrollTop: 0,
pointerClientX: 0,
pointerClientY: 0,
pointerOffsetX: 0,
pointerOffsetY: 0,
previewStart: element.start,
previewTrack: element.track,
previewLayerId: layers[layerIndex]!.id,
previewLayerIndex: layerIndex,
previewStackingReorder: null,
snapBeatTime: null,
snapGuideTime: null,
snapGuideKind: null,
started: false,
});
});
},
startResize(element: TimelineElement, edge: "start" | "end") {
act(() => {
applyResizingClip({
element,
edge,
originClientX: 0,
previewStart: element.start,
previewDuration: element.duration,
previewPlaybackStart: element.playbackStart,
snapGuideTime: null,
snapGuideKind: null,
started: false,
});
});
},
movePointer(clientX: number, clientY: number) {
act(() => {
window.dispatchEvent(
new MouseEvent("pointermove", {
bubbles: true,
clientX,
clientY,
}),
);
});
},
async dropPointer() {
await act(async () => {
window.dispatchEvent(new MouseEvent("pointerup", { bubbles: true }));
});
},
unmount() {
act(() => root.unmount());
},
};
}
describe("useTimelineClipDrag", () => {
it("allows moving a clip past the current composition duration", async () => {
const clip = timelineElement({ id: "clip", track: 0, zIndex: 1 });
const harness = renderDragHarness([clip]);
harness.startDrag(clip, 0);
harness.movePointer(1100, 0);
await harness.dropPointer();
expect(harness.onMoveElement).toHaveBeenCalledWith(
clip,
expect.objectContaining({ start: 11 }),
);
harness.unmount();
});
it("allows right-edge resize past the current composition duration", async () => {
const clip = timelineElement({ id: "clip", track: 0, zIndex: 1, start: 6, duration: 2 });
const harness = renderDragHarness([clip]);
harness.startResize(clip, "end");
harness.movePointer(400, 0);
await harness.dropPointer();
expect(harness.onResizeElement).toHaveBeenCalledWith(
clip,
expect.objectContaining({ start: 6, duration: 6 }),
);
harness.unmount();
});
it("passes a new-lane stacking intent when a vertical drag targets an overlapping lane", async () => {
const front = timelineElement({ id: "front", track: 0, zIndex: 3 });
const middle = timelineElement({ id: "middle", track: 1, zIndex: 2 });
const back = timelineElement({ id: "back", track: 2, zIndex: 1 });
const harness = renderDragHarness([front, middle, back]);
harness.startDrag(back, 2);
harness.movePointer(0, -2 * TRACK_H);
await harness.dropPointer();
expect(harness.onMoveElement).toHaveBeenCalledTimes(1);
expect(harness.onMoveElement.mock.calls[0]![1]).toMatchObject({
start: 0,
track: 2,
stackingReorder: {
contextKey: "root",
placement: { type: "above", layerId: harness.layers[0]!.id },
zIndexChanges: [{ key: "back", zIndex: 4 }],
},
});
harness.unmount();
});
it("resolves lane stacking from the authored time span, independent of horizontal drag", async () => {
const front = timelineElement({ id: "front", track: 0, zIndex: 3 });
const back = timelineElement({ id: "back", track: 1, zIndex: 1 });
back.start = 0;
front.start = 0;
const harness = renderDragHarness([front, back]);
// Drag up one row AND rightward in time. The horizontal drift moves the
// clip out of overlap, but the two axes never fight: the vertical restack
// is resolved from the authored (overlapping) span, so it still inserts
// above the target lane rather than silently joining it.
harness.startDrag(back, 1);
harness.movePointer(200, -TRACK_H);
await harness.dropPointer();
expect(harness.onMoveElement).toHaveBeenCalledTimes(1);
expect(harness.onMoveElement.mock.calls[0]![1]).toMatchObject({
start: 2,
track: 1,
stackingReorder: {
contextKey: "root",
placement: { type: "above", layerId: harness.layers[0]!.id },
zIndexChanges: [{ key: "back", zIndex: 4 }],
},
});
harness.unmount();
});
});
@@ -5,69 +5,23 @@ import {
resolveTimelineResize,
resolveTimelineAutoScroll,
type BlockedTimelineEditIntent,
type TimelineStackingReorderIntent,
} from "./timelineEditing";
import { usePlayerStore } from "../store/playerStore";
import type { TimelineElement } from "../store/playerStore";
import { TRACK_H } from "./timelineLayout";
import { isMusicTrack } from "../../utils/timelineInspector";
import { mergeUserBeats } from "../../utils/beatEditing";
import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrder";
import {
buildTimelineSnapTargets,
snapEdgesToTargets,
snapResizeEdgeToTargets,
type TimelineSnapKind,
} from "./timelineSnapTargets";
const BEAT_SNAP_PX = 8;
const EMPTY_BEAT_TIMES: number[] = [];
function snapToNearestBeat(time: number, beatTimes: number[], thresholdSecs: number): number {
let best = time;
let bestDist = thresholdSecs;
for (const bt of beatTimes) {
const d = Math.abs(bt - time);
if (d < bestDist) {
bestDist = d;
best = bt;
}
}
return best;
}
/**
* Snap a moved clip so whichever edge (start or end) is nearest a beat lands on
* it, keeping the duration fixed. Returns the (clamped) start plus the beat time
* it snapped to (for the grid-line highlight), or `beat: null` when no edge is
* within threshold.
*/
function snapMoveStartToBeat(
start: number,
duration: number,
beatTimes: number[],
pixelsPerSecond: number,
timelineDuration: number,
): { start: number; beat: number | null } {
if (beatTimes.length === 0) return { start, beat: null };
const snapSecs = BEAT_SNAP_PX / Math.max(pixelsPerSecond, 1);
const snappedStart = snapToNearestBeat(start, beatTimes, snapSecs);
const snappedEnd = snapToNearestBeat(start + duration, beatTimes, snapSecs);
const startMoved = snappedStart !== start;
const endMoved = snappedEnd !== start + duration;
let candidate = start;
let beat: number | null = null;
if (
startMoved &&
(!endMoved || Math.abs(snappedStart - start) <= Math.abs(snappedEnd - (start + duration)))
) {
candidate = snappedStart;
beat = snappedStart;
} else if (endMoved) {
candidate = snappedEnd - duration;
beat = snappedEnd;
}
const maxStart = Math.max(0, timelineDuration - duration);
const clamped = Math.max(0, Math.min(maxStart, Math.round(candidate * 1000) / 1000));
// If clamping pulled the clip off the snap target, drop the highlight.
if (beat != null && Math.abs(clamped - candidate) > 1e-6) beat = null;
return { start: clamped, beat };
}
/* ── Shared state types ─────────────────────────────────────────── */
export interface DraggedClipState {
element: TimelineElement;
@@ -81,8 +35,14 @@ export interface DraggedClipState {
pointerOffsetY: number;
previewStart: number;
previewTrack: number;
previewLayerId: TimelineLayerId;
previewLayerIndex: number;
/** Beat time the clip will snap to on drop, for the grid-line highlight. */
snapBeatTime: number | null;
snapGuideTime: number | null;
snapGuideKind: TimelineSnapKind | null;
/** Sibling-scoped z-index reorder intent resolved from the vertical drag. */
previewStackingReorder: TimelineStackingReorderIntent | null;
started: boolean;
}
@@ -93,6 +53,8 @@ export interface ResizingClipState {
previewStart: number;
previewDuration: number;
previewPlaybackStart?: number;
snapGuideTime: number | null;
snapGuideKind: TimelineSnapKind | null;
started: boolean;
}
@@ -108,11 +70,14 @@ export interface BlockedClipState {
interface UseTimelineClipDragInput {
scrollRef: React.RefObject<HTMLDivElement | null>;
ppsRef: React.RefObject<number>;
durationRef: React.RefObject<number>;
trackOrderRef: React.RefObject<number[]>;
trackOrderRef: React.RefObject<TimelineLayerId[]>;
timelineLayersRef: React.RefObject<StackingTimelineLayer[]>;
timelineElementsRef: React.RefObject<TimelineElement[]>;
onMoveElement?: (
element: TimelineElement,
updates: Pick<TimelineElement, "start" | "track">,
updates: Pick<TimelineElement, "start" | "track"> & {
stackingReorder?: TimelineStackingReorderIntent | null;
},
) => Promise<void> | void;
onResizeElement?: (
element: TimelineElement,
@@ -127,8 +92,9 @@ interface UseTimelineClipDragInput {
export function useTimelineClipDrag({
scrollRef,
ppsRef,
durationRef,
trackOrderRef,
timelineLayersRef,
timelineElementsRef,
onMoveElement,
onResizeElement,
onBlockedEditAttempt,
@@ -139,6 +105,8 @@ export function useTimelineClipDrag({
const rawBeatTimes = usePlayerStore((s) => s.beatAnalysis?.beatTimes ?? EMPTY_BEAT_TIMES);
const rawBeatStrengths = usePlayerStore((s) => s.beatAnalysis?.beatStrengths ?? EMPTY_BEAT_TIMES);
const beatEdits = usePlayerStore((s) => s.beatEdits);
const playhead = usePlayerStore((s) => s.currentTime);
const compositionDuration = usePlayerStore((s) => s.duration);
const musicStart = usePlayerStore((s) => s.elements.find(isMusicTrack)?.start ?? 0);
const musicPlaybackStart = usePlayerStore(
(s) => s.elements.find(isMusicTrack)?.playbackStart ?? 0,
@@ -166,6 +134,22 @@ export function useTimelineClipDrag({
const beatTimesRef = useRef<number[]>([]);
beatTimesRef.current = adjustedBeatTimes;
const playheadRef = useRef(0);
playheadRef.current = playhead;
const compositionDurationRef = useRef(0);
compositionDurationRef.current = compositionDuration;
const buildSnapTargets = useCallback(
(element: TimelineElement) =>
buildTimelineSnapTargets({
elements: timelineElementsRef.current,
draggedKey: element.key ?? element.id,
playhead: playheadRef.current,
compDuration: compositionDurationRef.current,
beats: isMusicTrack(element) ? EMPTY_BEAT_TIMES : beatTimesRef.current,
}),
[timelineElementsRef],
);
const [draggedClip, setDraggedClip] = useState<DraggedClipState | null>(null);
const draggedClipRef = useRef<DraggedClipState | null>(null);
@@ -202,22 +186,23 @@ export function useTimelineClipDrag({
currentScrollTop: scroll?.scrollTop ?? drag.originScrollTop,
pixelsPerSecond: ppsRef.current,
trackHeight: TRACK_H,
maxStart: Math.max(0, durationRef.current - drag.element.duration),
trackOrder: trackOrderRef.current,
maxStart: Number.POSITIVE_INFINITY,
trackOrder: timelineLayersRef.current.map((layer) => layer.placementTrack),
layerOrder: trackOrderRef.current,
timelineLayers: timelineLayersRef.current,
stackingElement: drag.element,
stackingElements: timelineElementsRef.current,
},
clientX,
clientY,
);
// The music track defines the beats, so it must not snap to itself.
const snap = isMusicTrack(drag.element)
? { start: nextMove.start, beat: null }
: snapMoveStartToBeat(
nextMove.start,
drag.element.duration,
beatTimesRef.current,
ppsRef.current,
durationRef.current,
);
const snap = snapEdgesToTargets(
nextMove.start,
drag.element.duration,
buildSnapTargets(drag.element),
ppsRef.current,
{ maxStart: Number.POSITIVE_INFINITY },
);
return {
...drag,
started: true,
@@ -225,10 +210,15 @@ export function useTimelineClipDrag({
pointerClientY: clientY,
previewStart: snap.start,
previewTrack: nextMove.track,
snapBeatTime: snap.beat,
previewLayerId: nextMove.previewLayerId ?? drag.previewLayerId,
previewLayerIndex: nextMove.previewLayerIndex ?? drag.previewLayerIndex,
previewStackingReorder: nextMove.stackingReorder ?? null,
snapBeatTime: snap.snapKind === "beat" ? snap.snapTime : null,
snapGuideTime: snap.snapTime,
snapGuideKind: snap.snapKind,
};
},
[scrollRef, ppsRef, durationRef, trackOrderRef],
[scrollRef, ppsRef, trackOrderRef, timelineLayersRef, timelineElementsRef, buildSnapTargets],
);
const stopClipDragAutoScroll = useCallback(() => {
@@ -299,6 +289,7 @@ export function useTimelineClipDrag({
});
};
// fallow-ignore-next-line complexity
const handleWindowPointerMove = (e: PointerEvent) => {
const drag = draggedClipRef.current;
const resize = resizingClipRef.current;
@@ -322,7 +313,7 @@ export function useTimelineClipDrag({
const normalizedTag = resize.element.tag.toLowerCase();
const canSeedPlaybackStart = normalizedTag === "audio" || normalizedTag === "video";
const playbackRate = Math.max(resize.element.playbackRate ?? 1, 0.1);
const maxEnd = Math.min(durationRef.current, resize.element.start + sourceRemaining);
const maxEnd = resize.element.start + sourceRemaining;
let nextResize = resolveTimelineResize(
{
start: resize.element.start,
@@ -341,51 +332,32 @@ export function useTimelineClipDrag({
e.clientX,
);
// Snap edge to beat grid when beat analysis is available. The snap must
// stay inside the same limits resolveTimelineResize enforces, or it would
// push the edge past the available source media / composition end.
// The music track defines the beats, so it must not snap to itself.
const beatTimes = beatTimesRef.current;
if (beatTimes.length > 0 && !isMusicTrack(resize.element)) {
const snapSecs = BEAT_SNAP_PX / Math.max(ppsRef.current, 1);
if (resize.edge === "end") {
const edgeTime = nextResize.start + nextResize.duration;
const snapped = snapToNearestBeat(edgeTime, beatTimes, snapSecs);
// 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;
if (snapped !== edgeTime && snapped <= maxEnd + 1e-6 && snappedDuration >= 0.05) {
nextResize = { ...nextResize, duration: snappedDuration };
}
} else {
const snapped = snapToNearestBeat(nextResize.start, beatTimes, snapSecs);
const delta = nextResize.start - snapped; // >0 when snapping left
// Leftward snap reveals more source; cap so playbackStart can't go < 0.
const maxLeftDelta =
nextResize.playbackStart != null
const snap = snapResizeEdgeToTargets(
resize.edge,
nextResize.start,
nextResize.duration,
buildSnapTargets(resize.element),
ppsRef.current,
{
minDuration: 0.05,
maxEnd,
maxLeftDelta:
resize.edge === "start" && nextResize.playbackStart != null
? nextResize.playbackStart / playbackRate
: Number.POSITIVE_INFINITY;
// Also require the resulting duration to stay >= minDuration so a
// rightward snap (delta < 0) can't collapse the clip to zero/negative.
const snappedDuration = Math.round((nextResize.duration + delta) * 1000) / 1000;
if (
snapped !== nextResize.start &&
snapped >= 0 &&
delta <= maxLeftDelta + 1e-6 &&
snappedDuration >= 0.05
) {
nextResize = {
...nextResize,
start: snapped,
duration: snappedDuration,
playbackStart:
nextResize.playbackStart != null
? Math.round(
Math.max(0, nextResize.playbackStart - delta * playbackRate) * 1000,
) / 1000
: undefined,
};
}
: Number.POSITIVE_INFINITY,
},
);
if (snap.snapTime != null) {
const unsnappedStart = nextResize.start;
nextResize = { ...nextResize, start: snap.start, duration: snap.duration };
if (resize.edge === "start" && nextResize.playbackStart != null) {
const delta = unsnappedStart - snap.start;
nextResize = {
...nextResize,
playbackStart:
Math.round(Math.max(0, nextResize.playbackStart - delta * playbackRate) * 1000) /
1000,
};
}
}
@@ -397,6 +369,8 @@ export function useTimelineClipDrag({
previewStart: nextResize.start,
previewDuration: nextResize.duration,
previewPlaybackStart: nextResize.playbackStart,
snapGuideTime: snap.snapTime,
snapGuideKind: snap.snapKind,
}
: prev,
);
@@ -434,6 +408,7 @@ export function useTimelineClipDrag({
syncClipDragAutoScrollRef.current(e.clientX, e.clientY);
};
// fallow-ignore-next-line complexity
const handleWindowPointerUp = () => {
stopClipDragAutoScrollRef.current();
@@ -492,24 +467,24 @@ export function useTimelineClipDrag({
suppressClickRef.current = true;
clearSuppressedClick();
const hasChanged =
drag.previewStart !== drag.element.start || drag.previewTrack !== drag.element.track;
const hasStackingReorder =
drag.previewStackingReorder != null && drag.previewStackingReorder.zIndexChanges.length > 0;
const hasChanged = drag.previewStart !== drag.element.start || hasStackingReorder;
if (!hasChanged) return;
updateElement(drag.element.key ?? drag.element.id, {
start: drag.previewStart,
track: drag.previewTrack,
});
Promise.resolve(
onMoveElementRef.current?.(drag.element, {
start: drag.previewStart,
track: drag.previewTrack,
track: drag.element.track,
stackingReorder: drag.previewStackingReorder,
}),
).catch((error) => {
updateElement(drag.element.key ?? drag.element.id, {
start: drag.element.start,
track: drag.element.track,
});
console.error("[Timeline] Failed to persist clip move", error);
});
@@ -192,9 +192,12 @@ function domSiblingClips(
start: host.start,
duration: host.duration,
track: host.track,
zIndex: 0,
stackingContextId: host.stackingContextId ?? host.domId ?? host.id ?? null,
kind: "element",
tagName: null,
compositionId: null,
compositionAncestors: host.compositionAncestors ?? [],
parentCompositionId: host.id ?? null,
compositionSrc: host.compositionSrc ?? null,
assetUrl: null,
@@ -243,7 +243,10 @@ describe("buildStandaloneRootTimelineElement", () => {
iframeSrc: "http://127.0.0.1:4173/api/projects/demo/preview/comp/scenes/hero.html?_t=123",
selector: '[data-composition-id="hero"]',
}),
).toEqual({
// toMatchObject (not toEqual): asserts the selector/source metadata this
// test is about, without re-pinning the full element shape (stacking
// metadata like hasExplicitZIndex is covered in timelineDOM.test.ts).
).toMatchObject({
id: "hero",
label: "hero",
key: 'scenes/hero.html:[data-composition-id="hero"]:0',
@@ -0,0 +1,77 @@
// @vitest-environment jsdom
import { describe, expect, it } from "vitest";
import { computeReorderZValues, getElementZIndex, resolveContextOrder } from "./layerOrdering";
function makeElement(zIndex?: string): HTMLElement {
const element = document.createElement("div");
if (zIndex != null) element.style.zIndex = zIndex;
document.body.appendChild(element);
return element;
}
describe("getElementZIndex", () => {
it("returns inline z-index when present", () => {
expect(getElementZIndex(makeElement("7"))).toBe(7);
});
it("falls back to computed style when inline z-index is not usable", () => {
const element = makeElement();
element.className = "computed-z";
const style = document.createElement("style");
style.textContent = ".computed-z { position: relative; z-index: 12; }";
document.head.appendChild(style);
expect(getElementZIndex(element)).toBe(12);
});
it("returns zero for auto or missing z-index", () => {
expect(getElementZIndex(makeElement())).toBe(0);
expect(getElementZIndex(makeElement("auto"))).toBe(0);
});
});
describe("computeReorderZValues", () => {
it("preserves distinct existing z-index values and remaps them onto the new order", () => {
expect(computeReorderZValues([1, 8, 3], 0, 2)).toEqual([8, 3, 1]);
});
it("renumbers an all-tied group to descending contiguous z-index values", () => {
expect(computeReorderZValues([0, 0, 0], 2, 0)).toEqual([3, 2, 1]);
});
it("renumbers the whole group when any existing z-index values are tied", () => {
expect(computeReorderZValues([5, 5, 1], 2, 0)).toEqual([3, 2, 1]);
});
});
describe("resolveContextOrder", () => {
it("sorts a flat sibling group by z-index descending then original order", () => {
const ordered = resolveContextOrder([
{ id: "a", zIndex: 2, parentCompositionId: null, compositionAncestors: ["root"] },
{ id: "b", zIndex: 5, parentCompositionId: null, compositionAncestors: ["root"] },
{ id: "c", zIndex: 5, parentCompositionId: null, compositionAncestors: ["root"] },
]);
expect(ordered.map((item) => item.id)).toEqual(["b", "c", "a"]);
});
it("keeps distinct stacking contexts from interleaving", () => {
const ordered = resolveContextOrder([
{ id: "root-low", zIndex: 1, parentCompositionId: null, compositionAncestors: ["root"] },
{
id: "nested-high",
zIndex: 100,
parentCompositionId: "scene",
compositionAncestors: ["root", "scene"],
},
{ id: "root-top", zIndex: 2, parentCompositionId: null, compositionAncestors: ["root"] },
]);
expect(ordered.map((item) => item.id)).toEqual(["root-top", "root-low", "nested-high"]);
});
it("returns an empty list for empty input", () => {
expect(resolveContextOrder([])).toEqual([]);
});
});
@@ -0,0 +1,98 @@
export interface StackingContextDescriptor {
parentCompositionId: string | null;
compositionAncestors: readonly string[];
stackingContextId?: string | null;
}
export interface ContextOrderItem extends StackingContextDescriptor {
zIndex: number;
}
// fallow-ignore-next-line complexity
export function getElementZIndex(element: HTMLElement): number {
try {
const inline = element.style?.zIndex;
if (inline && inline !== "auto") {
const parsed = parseInt(inline, 10);
if (Number.isFinite(parsed)) return parsed;
}
const win = element.ownerDocument?.defaultView;
if (!win) return 0;
const value = win.getComputedStyle(element).zIndex;
if (value === "auto" || value === "") return 0;
const parsed = parseInt(value, 10);
return Number.isFinite(parsed) ? parsed : 0;
} catch {
return 0;
}
}
// fallow-ignore-next-line complexity
export function hasExplicitZIndex(element: HTMLElement): boolean {
try {
const inline = element.style?.zIndex;
if (inline) return inline !== "auto";
const win = element.ownerDocument?.defaultView;
if (!win) return false;
const value = win.getComputedStyle(element).zIndex;
return value !== "auto" && value !== "";
} catch {
return false;
}
}
export function computeReorderZValues(
existingValues: readonly number[],
fromIndex: number,
toIndex: number,
): number[] {
const reordered = [...existingValues];
const [moved] = reordered.splice(fromIndex, 1);
reordered.splice(toIndex, 0, moved);
const sorted = [...existingValues].sort((a, b) => b - a);
const hasDupes = sorted.some((v, i) => i > 0 && v === sorted[i - 1]);
return hasDupes ? reordered.map((_, i) => reordered.length - i) : sorted;
}
export function resolveStackingContextKey(item: StackingContextDescriptor): string {
return item.stackingContextId ?? item.parentCompositionId ?? item.compositionAncestors[0] ?? "";
}
function resolveStackingContextDepth(item: StackingContextDescriptor): number {
const contextKey = resolveStackingContextKey(item);
if (!contextKey) return 0;
const index = item.compositionAncestors.indexOf(contextKey);
return index >= 0 ? index : 0;
}
export function resolveContextOrder<T extends ContextOrderItem>(items: readonly T[]): T[] {
if (items.length === 0) return [];
const groups = new Map<
string,
{ firstIndex: number; depth: number; entries: Array<{ item: T; index: number }> }
>();
items.forEach((item, index) => {
const key = resolveStackingContextKey(item);
const group = groups.get(key);
if (group) {
group.entries.push({ item, index });
return;
}
groups.set(key, {
firstIndex: index,
depth: resolveStackingContextDepth(item),
entries: [{ item, index }],
});
});
return [...groups.values()]
.sort((a, b) => a.depth - b.depth || a.firstIndex - b.firstIndex)
.flatMap((group) =>
group.entries
.sort((a, b) => b.item.zIndex - a.item.zIndex || a.index - b.index)
.map((entry) => entry.item),
);
}
@@ -38,9 +38,12 @@ export interface ClipManifestClip {
start: number;
duration: number;
track: number;
zIndex?: number;
stackingContextId?: string | null;
kind: "video" | "audio" | "image" | "element" | "composition";
tagName: string | null;
compositionId: string | null;
compositionAncestors?: string[];
parentCompositionId: string | null;
compositionSrc: string | null;
assetUrl: string | null;
@@ -4,6 +4,7 @@ import {
createTimelineElementFromManifestClip,
parseTimelineFromDOM,
createImplicitTimelineLayersFromDOM,
buildStandaloneRootTimelineElement,
} from "./timelineDOM";
function makeDoc(html: string): Document {
@@ -12,6 +13,29 @@ function makeDoc(html: string): Document {
return d;
}
function makeLiveDoc(html: string): Document {
document.head.innerHTML = "";
document.body.innerHTML = html;
return document;
}
function mockComputedZIndex(doc: Document, zIndexById: ReadonlyMap<string, string>): void {
const win = doc.defaultView;
if (!win) throw new Error("Expected document window");
const original = win.getComputedStyle.bind(win);
Object.defineProperty(win, "getComputedStyle", {
configurable: true,
value: (element: Element, pseudoElt?: string | null) => {
const style = original(element, pseudoElt);
const zIndex = zIndexById.get(element.id);
if (zIndex != null) {
Object.defineProperty(style, "zIndex", { configurable: true, value: zIndex });
}
return style;
},
});
}
describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
it("harvests hfId from a data-start element that has data-hf-id", () => {
const doc = makeDoc(`
@@ -102,6 +126,58 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
expect(element.hidden).toBe(true);
});
it("captures the effective z-index from the live element, not the runtime inline-only value", () => {
// The runtime reports inline-only z-index (0 for CSS-rule authored z-index),
// which must NOT override the live element's effective z-index — otherwise
// the timeline collapses every CSS-styled clip to a z=0 tie and mis-orders.
const doc = makeDoc(`
<div data-composition-id="root">
<div id="hero" class="clip" data-start="0" data-duration="5" style="z-index: 30"></div>
</div>
`);
const hostEl = doc.getElementById("hero");
const element = createTimelineElementFromManifestClip({
clip: {
id: "hero",
label: "Hero",
kind: "element",
tagName: "div",
start: 0,
duration: 5,
track: 0,
zIndex: 0,
compositionId: null,
parentCompositionId: null,
compositionSrc: null,
assetUrl: null,
},
fallbackIndex: 0,
doc,
hostEl,
});
expect(element.zIndex).toBe(30);
expect(element.hasExplicitZIndex).toBe(true);
});
it("marks parsed inline, CSS-rule, and auto z-index authorship accurately", () => {
const doc = makeLiveDoc(`
<div data-composition-id="root">
<div id="inline" class="clip" data-start="0" data-duration="2" style="z-index: 3"></div>
<div id="rule" class="clip" data-start="0" data-duration="2"></div>
<div id="auto" class="clip" data-start="0" data-duration="2"></div>
</div>
`);
mockComputedZIndex(doc, new Map([["rule", "12"]]));
const elements = parseTimelineFromDOM(doc, 10);
expect(elements.find((el) => el.id === "inline")?.hasExplicitZIndex).toBe(true);
expect(elements.find((el) => el.id === "rule")?.hasExplicitZIndex).toBe(true);
expect(elements.find((el) => el.id === "auto")?.hasExplicitZIndex).toBe(false);
});
});
describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
@@ -135,4 +211,31 @@ describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
expect(layers).toEqual([]);
});
it("marks implicit layer CSS z-index authorship from computed style", () => {
const doc = makeLiveDoc(`
<div data-composition-id="root">
<div id="layer" class="clip"></div>
</div>
`);
mockComputedZIndex(doc, new Map([["layer", "8"]]));
const layers = createImplicitTimelineLayersFromDOM(doc, 10);
expect(layers[0]?.zIndex).toBe(8);
expect(layers[0]?.hasExplicitZIndex).toBe(true);
});
});
describe("buildStandaloneRootTimelineElement", () => {
it("marks the standalone root as auto z-index", () => {
const root = buildStandaloneRootTimelineElement({
compositionId: "root",
tagName: "div",
rootDuration: 10,
iframeSrc: "/preview/comp/index.html",
});
expect(root?.hasExplicitZIndex).toBe(false);
});
});
@@ -10,6 +10,7 @@
import type { TimelineElement } from "../store/playerStore";
import type { ClipManifestClip } from "./playbackTypes";
import { getElementZIndex, hasExplicitZIndex } from "./layerOrdering";
import {
resolveMediaElement,
applyMediaMetadataFromElement,
@@ -65,6 +66,49 @@ function resolveClipTag(clip: ClipManifestClip): string {
return clip.tagName || clip.kind || "div";
}
function resolveDomCompositionContext(
element: Element,
root: Element | null,
): {
parentCompositionId: string | null;
compositionAncestors: string[];
stackingContextId: string | null;
} {
const ancestors: string[] = [];
let parentCompositionId: string | null = null;
let cursor = element.parentElement;
while (cursor) {
const compositionId = cursor.getAttribute("data-composition-id");
if (compositionId) {
ancestors.push(compositionId);
if (!parentCompositionId && cursor !== root) {
parentCompositionId = compositionId;
}
}
cursor = cursor.parentElement;
}
const compositionAncestors = ancestors.reverse();
return {
parentCompositionId,
compositionAncestors,
stackingContextId: parentCompositionId ?? compositionAncestors[0] ?? null,
};
}
function isHTMLElement(element: Element | null): element is HTMLElement {
if (!element) return false;
const HtmlElementCtor = element.ownerDocument.defaultView?.HTMLElement ?? globalThis.HTMLElement;
return typeof HtmlElementCtor !== "undefined" && element instanceof HtmlElementCtor;
}
function getTimelineElementZIndex(element: Element | null): number | undefined {
return isHTMLElement(element) ? getElementZIndex(element) : undefined;
}
function getTimelineElementHasExplicitZIndex(element: Element | null): boolean {
return isHTMLElement(element) ? hasExplicitZIndex(element) : false;
}
// fallow-ignore-next-line complexity
export function createTimelineElementFromManifestClip(params: {
clip: ClipManifestClip;
@@ -86,6 +130,14 @@ export function createTimelineElementFromManifestClip(params: {
let sourceFile: string | undefined;
let hfId: string | undefined;
const domContext = hostEl
? resolveDomCompositionContext(hostEl, doc?.querySelector("[data-composition-id]") ?? null)
: null;
const compositionAncestors = clip.compositionAncestors ?? domContext?.compositionAncestors;
const parentCompositionId = clip.parentCompositionId ?? domContext?.parentCompositionId;
const stackingContextId =
clip.stackingContextId ?? parentCompositionId ?? compositionAncestors?.[0] ?? null;
if (hostEl) {
domId = hostEl.id || undefined;
hfId = hostEl.getAttribute("data-hf-id") || undefined;
@@ -112,6 +164,15 @@ export function createTimelineElementFromManifestClip(params: {
start: clip.start,
duration: clip.duration,
track: clip.track,
// Prefer the effective (computed) z-index read from the live element — the
// same read the reorder commit uses — so CSS-rule z-index (not just inline)
// is captured. clip.zIndex from the runtime is inline-only (0 for CSS rules),
// so it can only serve as a fallback when the element isn't live.
zIndex: getTimelineElementZIndex(hostEl) ?? clip.zIndex ?? 0,
hasExplicitZIndex: getTimelineElementHasExplicitZIndex(hostEl),
stackingContextId,
parentCompositionId,
compositionAncestors,
domId,
hfId,
selector,
@@ -146,6 +207,8 @@ export function createTimelineElementFromManifestClip(params: {
}
}
if (hostEl) {
entry.zIndex = getTimelineElementZIndex(hostEl) ?? entry.zIndex;
entry.hasExplicitZIndex = getTimelineElementHasExplicitZIndex(hostEl);
entry.domId = hostEl.id || undefined;
entry.hfId = hostEl.getAttribute("data-hf-id") || undefined;
entry.selector = getTimelineElementSelector(hostEl);
@@ -206,6 +269,7 @@ export function createImplicitTimelineLayersFromDOM(
});
if (existingKeys.has(identity.key) || existingKeys.has(identity.id)) continue;
const compositionContext = resolveDomCompositionContext(child, rootComp);
layers.push({
domId: child.id || undefined,
hfId: child.getAttribute("data-hf-id") || undefined,
@@ -217,6 +281,11 @@ export function createImplicitTimelineLayersFromDOM(
selectorIndex,
sourceFile,
start: 0,
zIndex: getTimelineElementZIndex(child),
hasExplicitZIndex: getTimelineElementHasExplicitZIndex(child),
stackingContextId: compositionContext.stackingContextId,
parentCompositionId: compositionContext.parentCompositionId,
compositionAncestors: compositionContext.compositionAncestors,
tag: child.tagName.toLowerCase(),
timingSource: "implicit",
track: maxTrack + 1 + layers.length,
@@ -278,6 +347,7 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
selectorIndex,
sourceFile,
});
const compositionContext = resolveDomCompositionContext(el, rootComp);
const entry: TimelineElement = {
id: identity.id,
label,
@@ -286,6 +356,11 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
start,
duration: dur,
track: isNaN(track) ? 0 : track,
zIndex: getTimelineElementZIndex(el),
hasExplicitZIndex: getTimelineElementHasExplicitZIndex(el),
stackingContextId: compositionContext.stackingContextId,
parentCompositionId: compositionContext.parentCompositionId,
compositionAncestors: compositionContext.compositionAncestors,
domId: el.id || undefined,
hfId: el.getAttribute("data-hf-id") || undefined,
selector,
@@ -406,6 +481,11 @@ export function buildStandaloneRootTimelineElement(params: {
start: 0,
duration: params.rootDuration,
track: 0,
zIndex: 0,
hasExplicitZIndex: false,
stackingContextId: params.compositionId,
parentCompositionId: null,
compositionAncestors: [params.compositionId],
compositionSrc,
selector: params.selector,
selectorIndex: params.selectorIndex,
@@ -245,7 +245,7 @@ export function buildTimelineElementIdentity(params: {
return { id, key };
}
export function getTimelineElementIdentity(element: TimelineElement): string {
export function getTimelineElementIdentity(element: { key?: string | null; id: string }): string {
return element.key ?? element.id;
}
@@ -28,6 +28,16 @@ export interface TimelineElement {
start: number;
duration: number;
track: number;
/** Resolved z-index for stacking-aware timeline ordering. */
zIndex?: number;
/** True when the effective z-index was authored inline or through CSS, not auto. */
hasExplicitZIndex?: boolean;
/** Stacking context this element belongs to; root clips use the root composition id. */
stackingContextId?: string | null;
/** Nearest parent composition context, matching RuntimeTimelineClip. */
parentCompositionId?: string | null;
/** Composition ancestry from root to nearest parent, matching RuntimeTimelineClip. */
compositionAncestors?: string[];
domId?: string;
/** Stable `data-hf-id` attribute value — used as primary patch target when present */
hfId?: string;
@@ -135,7 +145,10 @@ interface PlayerState {
updateElement: (
elementId: string,
updates: Partial<
Pick<TimelineElement, "start" | "duration" | "track" | "playbackStart" | "hidden">
Pick<
TimelineElement,
"start" | "duration" | "track" | "zIndex" | "hasExplicitZIndex" | "playbackStart" | "hidden"
>
>,
) => void;
setZoomMode: (mode: ZoomMode) => void;
+2 -14
View File
@@ -8,6 +8,7 @@ import { collectHtmlIds } from "./studioHelpers";
import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
import { saveProjectFilesWithHistory } from "./studioFileHistory";
import type { EditHistoryKind } from "./editHistory";
import { extendRootDurationInSource } from "./rootDuration";
function getMaxZIndexFromIframe(iframe: HTMLIFrameElement | null): number {
try {
@@ -163,20 +164,7 @@ export async function addBlockToProject(
].join("\n");
let patchedContent = insertTimelineAssetIntoSource(originalContent, subCompHtml);
const newEnd = start + duration;
const rootDurMatch = patchedContent.match(
/(<[^>]*data-composition-id="[^"]*"[^>]*data-duration=")([^"]*)(")/,
);
if (rootDurMatch) {
const rootDur = parseFloat(rootDurMatch[2]!);
if (newEnd > rootDur) {
patchedContent = patchedContent.replace(
rootDurMatch[0],
`${rootDurMatch[1]}${formatTimelineAttributeNumber(newEnd)}${rootDurMatch[3]}`,
);
}
}
patchedContent = extendRootDurationInSource(patchedContent, start + duration);
await saveProjectFilesWithHistory({
projectId,
@@ -0,0 +1,34 @@
import { describe, expect, it } from "vitest";
import { extendRootDurationInSource } from "./rootDuration";
describe("extendRootDurationInSource", () => {
it("extends data-duration when the new end is bigger than the root duration", () => {
const source = [
`<div data-composition-id="main" data-duration="4">`,
` <section id="clip" data-start="2" data-duration="3"></section>`,
`</div>`,
].join("\n");
expect(extendRootDurationInSource(source, 5.25)).toContain(
`data-composition-id="main" data-duration="5.25"`,
);
});
it("does nothing when the new end is smaller than or equal to the root duration", () => {
const source = `<div data-composition-id="main" data-duration="6"></div>`;
expect(extendRootDurationInSource(source, 5)).toBe(source);
expect(extendRootDurationInSource(source, 6)).toBe(source);
});
it("leaves non-root data-duration attributes untouched by the extension", () => {
const source = [
`<div data-duration="3"></div>`,
`<div data-composition-id="main" data-duration="4"></div>`,
].join("\n");
const patched = extendRootDurationInSource(source, 7);
expect(patched).toContain(`<div data-duration="3"></div>`);
expect(patched).toContain(`<div data-composition-id="main" data-duration="7"></div>`);
});
});
+17
View File
@@ -0,0 +1,17 @@
import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
export function extendRootDurationInSource(source: string, newEnd: number): string {
const rootDurMatch = source.match(
/(<[^>]*data-composition-id="[^"]*"[^>]*data-duration=")([^"]*)(")/,
);
if (rootDurMatch) {
const rootDur = parseFloat(rootDurMatch[2]!);
if (newEnd > rootDur) {
return source.replace(
rootDurMatch[0],
`${rootDurMatch[1]}${formatTimelineAttributeNumber(newEnd)}${rootDurMatch[3]}`,
);
}
}
return source;
}