Skip to content

Write HTML. Render video. Built for agents.

perf(studio): smooth timeline zoom on long projects (#5109)

Miguel Ángeleee0c5101c00
diff --git a/packages/studio/src/components/TimelineToolbar.test.tsx b/packages/studio/src/components/TimelineToolbar.test.tsx
index a120f34ace..b35d299c4b 100644
--- a/packages/studio/src/components/TimelineToolbar.test.tsx
+++ b/packages/studio/src/components/TimelineToolbar.test.tsx
@@ -2,7 +2,7 @@
import React, { act } from "react";
import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
import { usePlayerStore } from "../player/store/playerStore";
import { makeSelection } from "../hooks/domSelectionTestHarness";
@@ -11,6 +11,7 @@ import { readStudioUiPreferences } from "../utils/studioUiPreferences";
import { dispatchPlainKey, type HotkeyCallbacks } from "../hooks/appHotkeysDispatch";
import { AudioMeterStrip } from "./nle/AudioMeterStrip";
import { TimelineToolbar } from "./TimelineToolbar";
+import { registerTimelineZoomViewport } from "../player/components/timelineZoomInput";
vi.mock("../contexts/StudioContext", () => ({
useStudioShellContextOptional: () => ({
@@ -239,6 +240,81 @@ describe("TimelineToolbar snap key", () => {
});
describe("TimelineToolbar Fit", () => {
+ // A zoom lands on the next frame; these tests step frames instead of waiting for them.
+ beforeEach(() => {
+ vi.useFakeTimers({
+ toFake: [
+ "requestAnimationFrame",
+ "cancelAnimationFrame",
+ "setTimeout",
+ "clearTimeout",
+ "performance",
+ ],
+ });
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ /** A mounted timeline for the zoom to preview on: 1080px wide, 32px of headers. */
+ function mountTimelineViewport() {
+ const scroll = document.createElement("div");
+ Object.defineProperties(scroll, {
+ clientWidth: { value: 1080 },
+ // At Fit the content is as wide as the view.
+ scrollWidth: { value: 1080 },
+ scrollLeft: { value: 0, writable: true },
+ });
+ usePlayerStore.setState({
+ zoomMode: "fit",
+ manualZoomPercent: 100,
+ timelineFitPps: 10,
+ timelinePps: 10,
+ });
+ return registerTimelineZoomViewport({ scroll, contentOrigin: 32 });
+ }
+
+ it("moves the slider and its readout with a zoom while it is previewed", () => {
+ const unregister = mountTimelineViewport();
+ const { host, root } = renderToolbar();
+ const slider = host.querySelector<HTMLInputElement>('input[aria-label="Timeline zoom"]')!;
+ const before = slider.value;
+ act(() => {
+ Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!.call(
+ slider,
+ String(Number(before) + 5),
+ );
+ slider.dispatchEvent(new Event("input", { bubbles: true }));
+ });
+ act(() => vi.advanceTimersToNextFrame());
+ // Not laid out yet: the store still holds Fit, but the toolbar shows the zoom on screen.
+ expect(usePlayerStore.getState().zoomMode).toBe("fit");
+ expect(slider.value).not.toBe(before);
+ expect(host.querySelector('[aria-label="Timeline zoom level"]')?.textContent).not.toBe("Fit");
+ act(() => root.unmount());
+ act(() => unregister());
+ });
+
+ it("keeps Fit when it is picked while a zoom waits to be laid out", () => {
+ const unregister = mountTimelineViewport();
+ const { host, root } = renderToolbar();
+ act(() =>
+ host
+ .querySelector('button[aria-label="Zoom in"]')
+ ?.dispatchEvent(new MouseEvent("click", { bubbles: true })),
+ );
+
+ act(() =>
+ host
+ .querySelector('button[aria-label="Fit timeline to width"]')
+ ?.dispatchEvent(new MouseEvent("click", { bubbles: true })),
+ );
+ act(() => vi.advanceTimersByTime(1000));
+ expect(usePlayerStore.getState().zoomMode).toBe("fit");
+ act(() => root.unmount());
+ act(() => unregister());
+ });
+
it("shows Fit as a named icon and says whether fit is on", () => {
const { host, root } = renderToolbar();
const fit = () => host.querySelector('button[aria-label="Fit timeline to width"]');
@@ -251,6 +327,7 @@ describe("TimelineToolbar Fit", () => {
.querySelector('button[aria-label="Zoom in"]')
?.dispatchEvent(new MouseEvent("click", { bubbles: true })),
);
+ act(() => vi.advanceTimersToNextFrame());
expect(fit()?.getAttribute("aria-pressed")).toBe("false");
act(() => root.unmount());
});
@@ -263,6 +340,7 @@ describe("TimelineToolbar Fit", () => {
.querySelector('button[aria-label="Zoom in"]')
?.dispatchEvent(new MouseEvent("click", { bubbles: true })),
);
+ act(() => vi.advanceTimersToNextFrame());
expect(usePlayerStore.getState().userZoomCount).toBe(before + 1);
act(() => root.unmount());
});
diff --git a/packages/studio/src/components/TimelineToolbar.tsx b/packages/studio/src/components/TimelineToolbar.tsx
index f4d0a18d1d..3cfd925803 100644
--- a/packages/studio/src/components/TimelineToolbar.tsx
+++ b/packages/studio/src/components/TimelineToolbar.tsx
@@ -14,12 +14,14 @@ import {
import { computeElementPercentage, playsNear } from "../hooks/gsapShared";
import { useKeyframeKeyboard } from "../hooks/useKeyframeKeyboard";
import {
- getNextTimelineZoomPercent,
- getTimelineZoomPercent,
timelineZoomPercentToSlider,
timelineSliderToZoomPercent,
} from "../player/components/timelineZoom";
import { useTimelineZoom } from "../player/components/useTimelineZoom";
+import {
+ useShownTimelineZoomPercent,
+ zoomTimelineStep,
+} from "../player/components/timelineZoomInput";
import { usePlayerStore, type TimelineElement } from "../player";
import { Tooltip } from "./ui";
import { AudioMetersIcon } from "./icons/AudioMetersIcon";
@@ -170,17 +172,13 @@ export const TimelineToolbar = memo(function TimelineToolbar({
// Subscribe so the add-beat button reacts to playhead movement and analysis load.
const currentTime = usePlayerStore((s) => s.currentTime);
const beatAnalysisReady = usePlayerStore((s) => s.beatAnalysis !== null);
- // Subscribe (not getState) so the split button enables/disables the moment
- // the selection changes, not only on the next playhead tick.
+ // Subscribed, so the split button follows the selection, not only playhead ticks.
const selectedElementId = usePlayerStore((s) => s.selectedElementId);
const elements = usePlayerStore((s) => s.elements);
const timelineFitPps = usePlayerStore((s) => s.timelineFitPps);
- const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();
- const displayedTimelineZoomPercent = getTimelineZoomPercent(
- zoomMode,
- manualZoomPercent,
- timelineFitPps,
- );
+ const { zoomMode, setZoomMode, setManualZoomPercent } = useTimelineZoom();
+ const displayedTimelineZoomPercent = useShownTimelineZoomPercent();
+ const showsFit = zoomMode === "fit" && displayedTimelineZoomPercent === 100;
const {
state: keyframeState,
isMotionPath: keyframeIsMotionPath,
@@ -215,8 +213,6 @@ export const TimelineToolbar = memo(function TimelineToolbar({
}, []);
return (
- // The "TIMELINE" label is dropped for CapCut-like density — the pane's
- // position (tracks right below) makes it self-evident.
<div className="border-b border-neutral-800/60">
<div className="flex items-center justify-between px-2 py-0.5">
<div className="flex items-center gap-0.5">
@@ -510,12 +506,7 @@ export const TimelineToolbar = memo(function TimelineToolbar({
<button
type="button"
aria-label="Zoom out"
- onClick={() => {
- setZoomMode("manual");
- setManualZoomPercent(
- getNextTimelineZoomPercent("out", zoomMode, manualZoomPercent, timelineFitPps),
- );
- }}
+ onClick={() => zoomTimelineStep("out")}
className={flatIdle}
>
<MagnifyingGlassMinus size={16} aria-hidden="true" />
@@ -528,12 +519,11 @@ export const TimelineToolbar = memo(function TimelineToolbar({
value={timelineZoomPercentToSlider(displayedTimelineZoomPercent, timelineFitPps)}
title={`${displayedTimelineZoomPercent}%`}
aria-label="Timeline zoom"
- onChange={(e) => {
- setZoomMode("manual");
+ onChange={(e) =>
setManualZoomPercent(
timelineSliderToZoomPercent(Number(e.target.value), timelineFitPps),
- );
- }}
+ )
+ }
// h-6 on the input is the 24x24 WCAG 2.2 (2.5.8) target: the visible
// track stays 2px and the thumb 10px, only the pointer box grows.
className="mx-1 h-6 w-[96px] cursor-pointer appearance-none bg-transparent [&::-webkit-slider-runnable-track]:h-[2px] [&::-webkit-slider-runnable-track]:rounded-full [&::-webkit-slider-runnable-track]:bg-neutral-700 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-[10px] [&::-webkit-slider-thumb]:h-[10px] [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-text-0 [&::-webkit-slider-thumb]:-mt-1 [&::-webkit-slider-thumb]:shadow-[0_0_0_2px_#0a0a0a,0_1px_3px_rgba(0,0,0,0.5)] [&::-webkit-slider-thumb]:cursor-grab [&::-webkit-slider-thumb:active]:cursor-grabbing"
@@ -542,12 +532,7 @@ export const TimelineToolbar = memo(function TimelineToolbar({
<button
type="button"
aria-label="Zoom in"
- onClick={() => {
- setZoomMode("manual");
- setManualZoomPercent(
- getNextTimelineZoomPercent("in", zoomMode, manualZoomPercent, timelineFitPps),
- );
- }}
+ onClick={() => zoomTimelineStep("in")}
className={flatIdle}
>
<MagnifyingGlassPlus size={16} aria-hidden="true" />
@@ -558,7 +543,7 @@ export const TimelineToolbar = memo(function TimelineToolbar({
className="ml-1 w-[38px] text-right font-mono text-[11px] tabular-nums text-neutral-500 select-none"
aria-label="Timeline zoom level"
>
- {zoomMode === "fit" ? "Fit" : `${displayedTimelineZoomPercent}%`}
+ {showsFit ? "Fit" : `${displayedTimelineZoomPercent}%`}
</span>
</div>
</div>
diff --git a/packages/studio/src/hooks/useThumbnailStripSize.test.tsx b/packages/studio/src/hooks/useThumbnailStripSize.test.tsx
index 5c6709c519..0e81d61a3d 100644
--- a/packages/studio/src/hooks/useThumbnailStripSize.test.tsx
+++ b/packages/studio/src/hooks/useThumbnailStripSize.test.tsx
@@ -7,6 +7,15 @@ import { NearScreenIntersectionObserver } from "./intersectionObserverTestUtils"
import { MockResizeObserver, reportResize } from "./resizeObserverTestUtils";
import { useThumbnailStripSize } from "./useThumbnailStripSize";
+const zoom = vi.hoisted(() => ({ previewing: false, listeners: new Set<() => void>() }));
+vi.mock("../player/components/timelineZoomInput", () => ({
+ isTimelineZoomPreviewing: () => zoom.previewing,
+ subscribeTimelineZoomPreview: (listener: () => void) => {
+ zoom.listeners.add(listener);
+ return () => zoom.listeners.delete(listener);
+ },
+}));
+
Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
it("does not re-render the strip when the observer reports the size it already holds", () => {
@@ -48,6 +57,62 @@ it("does not re-render the strip when the observer reports the size it already h
}
});
+it("measures a strip once a zoom preview ends, not while the preview scales it", () => {
+ const originalResizeObserver = globalThis.ResizeObserver;
+ globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+ const host = document.createElement("div");
+ document.body.append(host);
+ let width = 300;
+ Object.defineProperty(host, "clientWidth", { configurable: true, get: () => width });
+ Object.defineProperty(host, "clientHeight", { configurable: true, value: 40 });
+ const root = createRoot(host);
+ function Harness() {
+ const [size, ref] = useThumbnailStripSize();
+ return <div ref={ref}>{`${size.width}x${size.height}`}</div>;
+ }
+ try {
+ act(() => root.render(<Harness />));
+ zoom.previewing = true;
+ width = 600;
+ act(() => reportResize(600, 40));
+ expect(host.textContent).toBe("300x40");
+ zoom.previewing = false;
+ act(() => zoom.listeners.forEach((listener) => listener()));
+ expect(host.textContent).toBe("600x40");
+ } finally {
+ zoom.previewing = false;
+ act(() => root.unmount());
+ host.remove();
+ globalThis.ResizeObserver = originalResizeObserver;
+ }
+});
+
+it("measures again each time a preview is laid out, though nothing was read during it", () => {
+ const originalResizeObserver = globalThis.ResizeObserver;
+ globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+ const host = document.createElement("div");
+ document.body.append(host);
+ let width = 300;
+ Object.defineProperty(host, "clientWidth", { configurable: true, get: () => width });
+ Object.defineProperty(host, "clientHeight", { configurable: true, value: 40 });
+ const root = createRoot(host);
+ function Harness() {
+ const [size, ref] = useThumbnailStripSize();
+ return <div ref={ref}>{`${size.width}x${size.height}`}</div>;
+ }
+ try {
+ act(() => root.render(<Harness />));
+ // A zoom-out lays its target out mid-ease; the resize is reported only later.
+ width = 600;
+ act(() => zoom.listeners.forEach((listener) => listener()));
+ expect(host.textContent).toBe("600x40");
+ } finally {
+ act(() => root.unmount());
+ host.remove();
+ globalThis.ResizeObserver = originalResizeObserver;
+ }
+});
+
describe("on a scroll", () => {
const originalResizeObserver = globalThis.ResizeObserver;
const originalIntersectionObserver = globalThis.IntersectionObserver;
diff --git a/packages/studio/src/hooks/useThumbnailStripSize.ts b/packages/studio/src/hooks/useThumbnailStripSize.ts
index d000c90ea9..ba44f4faa9 100644
--- a/packages/studio/src/hooks/useThumbnailStripSize.ts
+++ b/packages/studio/src/hooks/useThumbnailStripSize.ts
@@ -1,5 +1,9 @@
import { useCallback, useState } from "react";
import { flushSync } from "react-dom";
+import {
+ isTimelineZoomPreviewing,
+ subscribeTimelineZoomPreview,
+} from "../player/components/timelineZoomInput";
export interface StripSize {
width: number;
@@ -24,7 +28,6 @@ const GAP_WARNING: IntersectionObserverInit & { scrollMargin: string } = {
scrollMargin: `0px ${IN_VIEW_CHUNK_PX / 2}px`,
};
-// A short strip keeps every tile, as before, so only long clips do work on a scroll.
const SHORT_STRIP_MAX_PX = 8 * IN_VIEW_CHUNK_PX;
const isShort = (width: number) => width <= SHORT_STRIP_MAX_PX;
@@ -62,6 +65,7 @@ let shared: {
resize: ResizeObserver;
presence: IntersectionObserver | null;
gaps: IntersectionObserver | null;
+ stopZoomWatch: () => void;
} | null = null;
const offsetOf = (scroller: Element | null) =>
@@ -97,8 +101,23 @@ const read = (target: Element, strip: Strip) => {
const commit = (updates: (readonly [Apply, Partial<StripSize>])[]) =>
flushSync(() => updates.forEach(([apply, patch]) => apply(patch)));
+// A zoom preview scales the strips: reads wait, and each preview's layout re-measures them all.
+const remeasureAfterPreview = () => {
+ if (isTimelineZoomPreviewing()) return;
+ commit(
+ [...strips].map(
+ ([target, strip]) =>
+ [
+ strip.apply,
+ { width: target.clientWidth, height: target.clientHeight, ...read(target, strip) },
+ ] as const,
+ ),
+ );
+};
+
const refresh = () => {
frame = 0;
+ if (isTimelineZoomPreviewing()) return;
const offsetsNow = new Map<Element | null, { x: number; y: number }>();
const updates: (readonly [Apply, Partial<StripSize>])[] = [];
for (const [target, strip] of strips) {
@@ -122,6 +141,7 @@ const scheduleRefresh = () => {
};
const measure = (entries: { target: Element; size?: { width: number; height: number } }[]) =>
+ isTimelineZoomPreviewing() ||
commit(
entries.flatMap(({ target, size }) => {
const strip = strips.get(target);
@@ -153,6 +173,7 @@ function acquire() {
gaps: observeIntersections(
(entries) => entries.some((entry) => entry.isIntersecting) && scheduleRefresh(),
),
+ stopZoomWatch: subscribeTimelineZoomPreview(remeasureAfterPreview),
};
window.addEventListener("scroll", scheduleRefresh, { capture: true, passive: true });
}
@@ -164,6 +185,7 @@ function release() {
shared?.resize.disconnect();
shared?.presence?.disconnect();
shared?.gaps?.disconnect();
+ shared?.stopZoomWatch();
shared = null;
window.removeEventListener("scroll", scheduleRefresh, { capture: true });
cancelAnimationFrame(frame);
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index 009f8ed09a..519317c784 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -63,6 +63,7 @@ export {
export { TimelineProvider, useTimelineContext } from "./player/components/TimelineProvider";
export type { TimelineTheme } from "./player/components/timelineTheme";
export { TRACK_H } from "./player/components/timelineLayout";
+export { currentTimelineRange, zoomTimelineToRange } from "./player/components/timelineZoomInput";
export type { TimelineTrackPadding } from "./player/components/timelineLayout";
export { displayTrackOrder } from "./player/components/useTimelineTrackDerivations";
export { fadeHandleBoxes } from "./player/components/timelineClipFadeGeometry";
diff --git a/packages/studio/src/player/components/AudioWaveform.test.tsx b/packages/studio/src/player/components/AudioWaveform.test.tsx
index 89f6a8e813..1652e04b9a 100644
--- a/packages/studio/src/player/components/AudioWaveform.test.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.test.tsx
@@ -11,15 +11,74 @@ vi.mock("../../hooks/useThumbnailLease", () => ({
useThumbnailLease: leaseSpy,
}));
+const EMPTY_STRIP = { width: 0, height: 0, inViewStart: 0, inViewEnd: 0 };
+const watchGap = vi.hoisted(() => vi.fn());
+const strip = vi.hoisted(() => ({
+ size: { width: 0, height: 0, inViewStart: 0, inViewEnd: 0 },
+ listeners: new Set<() => void>(),
+}));
+// The strip hook's own tests cover scrolls and moves; here it reports what the test sets.
+vi.mock("../../hooks/useThumbnailStripSize", async () => {
+ const { useSyncExternalStore } = await import("react");
+ const subscribe = (listener: () => void) => {
+ strip.listeners.add(listener);
+ return () => strip.listeners.delete(listener);
+ };
+ return {
+ useThumbnailStripSize: () => [
+ useSyncExternalStore(subscribe, () => strip.size),
+ () => {},
+ watchGap,
+ ],
+ };
+});
+
+const setStrip = (size: typeof EMPTY_STRIP) =>
+ act(() => {
+ strip.size = size;
+ strip.listeners.forEach((listener) => listener());
+ });
+
import { AudioWaveform, drawWaveformCanvas } from "./AudioWaveform";
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+const mounted: Array<ReturnType<typeof createRoot>> = [];
+
afterEach(() => {
- leaseSpy.mockClear();
+ act(() => mounted.splice(0).forEach((root) => root.unmount()));
+ vi.restoreAllMocks();
+ vi.useRealTimers();
+ leaseSpy.mockReset();
+ leaseSpy.mockImplementation(() => ({ status: "loading" as const }));
+ strip.size = EMPTY_STRIP;
+ watchGap.mockClear();
document.body.innerHTML = "";
});
+/** Renders a ready waveform for a two-peak sound into `parent`. */
+function renderReadyWaveform(parent: HTMLElement = document.body) {
+ // One snapshot, as the lease returns, so a re-render alone does not redraw.
+ const ready = { status: "ready", value: { kind: "waveform", peaks: [0.5, 1] } } as never;
+ leaseSpy.mockImplementation(() => ready);
+ const host = document.createElement("div");
+ parent.append(host);
+ const root = createRoot(host);
+ mounted.push(root);
+ act(() => {
+ root.render(
+ <AudioWaveform
+ audioUrl="/media/voice.wav"
+ label=""
+ labelColor="#fff"
+ projectId="project-a"
+ sessionEpoch={1}
+ priority="visible"
+ />,
+ );
+ });
+}
+
/** A 6 x 20 canvas whose 2D context records every fill as [style, x, y, width, height]. */
function recordingCanvas() {
const fills: Array<[string, number, number, number, number]> = [];
@@ -51,6 +110,58 @@ describe("AudioWaveform", () => {
]);
});
+ it("draws only the span of the clip it is given", () => {
+ const { canvas, fills } = recordingCanvas();
+ // The clip's second half holds the loud peak only.
+ drawWaveformCanvas(canvas, [0.25, 1], false, 0, 1, null, { from: 0.5, to: 1 });
+ const bars = fills.filter(([, , y, , height]) => !(y === 18 && height === 2));
+ expect(bars.map(([, , y, , height]) => [y, height])).toEqual([
+ [0, 20],
+ [0, 20],
+ ]);
+ });
+
+ it("draws only the stretch of a long clip near the screen, and follows it as the clip moves", () => {
+ vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null);
+ setStrip({ width: 10_000, height: 40, inViewStart: 2048, inViewEnd: 4096 });
+ renderReadyWaveform();
+ const canvas = document.querySelector("canvas")!;
+ const placed = () => [parseFloat(canvas.style.left), parseFloat(canvas.style.width)];
+ expect(placed()[0]).toBeCloseTo(20.48);
+ expect(placed()[1]).toBeCloseTo(20.48);
+ // A move or scroll carries the clip: the hook reports a new stretch and the bars follow.
+ setStrip({ width: 10_000, height: 40, inViewStart: 4096, inViewEnd: 6144 });
+ expect(placed()[0]).toBeCloseTo(40.96);
+ expect(placed()[1]).toBeCloseTo(20.48);
+ });
+
+ it("watches no ends of a clip drawn whole", () => {
+ setStrip({ width: 1000, height: 40, inViewStart: 0, inViewEnd: 1000 });
+ renderReadyWaveform();
+ expect(watchGap.mock.calls.filter(([gap]) => gap)).toEqual([]);
+ });
+
+ it("redraws a short clip, drawn whole, when a zoom changes its width", () => {
+ const getContext = vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null);
+ setStrip({ width: 1000, height: 40, inViewStart: 0, inViewEnd: 1000 });
+ renderReadyWaveform();
+ const drawn = getContext.mock.calls.length;
+ setStrip({ width: 2000, height: 40, inViewStart: 0, inViewEnd: 2000 });
+ expect(getContext.mock.calls.length).toBe(drawn + 1);
+ });
+
+ it("watches both undrawn ends of a long clip, so a move without a scroll re-measures it", () => {
+ setStrip({ width: 10_000, height: 40, inViewStart: 2048, inViewEnd: 4096 });
+ renderReadyWaveform();
+ const gaps = [
+ ...new Set(watchGap.mock.calls.map(([gap]) => gap).filter(Boolean)),
+ ] as HTMLElement[];
+ expect(gaps.map((gap) => [gap.style.width, gap.style.left])).toEqual([
+ ["20.48%", ""],
+ ["", "40.96%"],
+ ]);
+ });
+
it("shrinks each bar to the fade's gain and keeps the cut-away part as a ghost", () => {
const { canvas, fills } = recordingCanvas();
// A 1 s fade-in on a 2 s clip: the first bar's centre (0.5 s) plays at half gain.
diff --git a/packages/studio/src/player/components/AudioWaveform.tsx b/packages/studio/src/player/components/AudioWaveform.tsx
index 043f381be2..d7e226ba1b 100644
--- a/packages/studio/src/player/components/AudioWaveform.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.tsx
@@ -1,7 +1,7 @@
import { memo, useCallback, useContext, useEffect, useMemo, useRef } from "react";
import { fadeGain } from "@hyperframes/core/audio-fade";
-import { useMountEffect } from "../../hooks/useMountEffect";
import { useThumbnailLease } from "../../hooks/useThumbnailLease";
+import { useThumbnailStripSize } from "../../hooks/useThumbnailStripSize";
import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
import { decimatePeaks, loudnessToOpacity } from "./audioWaveformPeaks";
import { ClipFadesContext, type ClipFadeShape } from "./TimelineClipFades";
@@ -30,6 +30,8 @@ export const WAVEFORM_LAYER_Z = 10;
type BarGeometry = { x: number; width: number; height: number; gain: number };
+type ClipSpan = { from: number; to: number };
+const WHOLE_CLIP: ClipSpan = { from: 0, to: 1 };
function paintWaveformBars(
context: CanvasRenderingContext2D,
bars: readonly BarGeometry[],
@@ -61,6 +63,7 @@ export function drawWaveformCanvas(
trimStartFraction: number,
trimEndFraction: number,
fades: ClipFadeShape | null = null,
+ span: ClipSpan = WHOLE_CLIP,
) {
const width = Math.max(1, canvas.clientWidth);
const height = Math.max(1, canvas.clientHeight);
@@ -71,19 +74,20 @@ export function drawWaveformCanvas(
if (!context) return;
context.scale(scale, scale);
context.clearRect(0, 0, width, height);
+ const trim = trimEndFraction - trimStartFraction;
const amplitudes = decimatePeaks(
peaks,
- trimStartFraction,
- trimEndFraction,
+ trimStartFraction + trim * span.from,
+ trimStartFraction + trim * span.to,
Math.max(1, Math.ceil(width / BAR_STEP)),
);
+ const clipFraction = (index: number) =>
+ span.from + ((index + 0.5) / amplitudes.length) * (span.to - span.from);
const bars = amplitudes.map((amplitude, index) => ({
x: (index * width) / amplitudes.length,
width: Math.max(1, width / amplitudes.length),
height: Math.max(3, amplitude * height),
- gain: fades
- ? fadeGain(((index + 0.5) / amplitudes.length) * fades.duration, fades.duration, fades)
- : 1,
+ gain: fades ? fadeGain(clipFraction(index) * fades.duration, fades.duration, fades) : 1,
}));
const channelToken = muted ? "--timeline-waveform-muted-rgb" : "--timeline-waveform-bar-rgb";
const waveformBarRgb = getComputedStyle(canvas).getPropertyValue(channelToken);
@@ -115,11 +119,8 @@ async function loadWaveform(
waveformUrl: string | undefined,
signal: AbortSignal,
): Promise<number[]> {
- // Failures propagate. Synthesised peaks are worse than an honest gap: an
- // author trims and beat-aligns against this waveform, and a plausible
- // fabrication is indistinguishable from the real thing while being wrong.
- // The scheduler caches the failure (metadataFailureTtlMs) so the degraded
- // state neither refetch-loops nor pins itself past a transient error.
+ // Failures propagate: authors trim and beat-align against this, so made-up peaks beat no gap.
+ // The scheduler caches the failure (metadataFailureTtlMs): no refetch loop, no stuck state.
return waveformUrl
? await fetchWaveformPeaks(waveformUrl, signal)
: await decodeWaveformPeaks(audioUrl, signal);
@@ -172,7 +173,6 @@ export const AudioWaveform = memo(function AudioWaveform({
}: AudioWaveformProps) {
const rootRef = useRef<HTMLDivElement | null>(null);
const canvasRef = useRef<HTMLCanvasElement | null>(null);
- const observerRef = useRef<ResizeObserver | null>(null);
const cacheKey = waveformUrl ?? audioUrl;
const request = useMemo(
() => ({
@@ -197,23 +197,28 @@ export const AudioWaveform = memo(function AudioWaveform({
snapshot.status === "ready" && snapshot.value.kind === "waveform" ? snapshot.value.peaks : null;
const fades = useContext(ClipFadesContext);
+ const [strip, setStripRef, watchGap] = useThumbnailStripSize();
+ const from = strip.width > 0 ? strip.inViewStart / strip.width : 0;
+ const to = strip.width > 0 ? strip.inViewEnd / strip.width : 1;
const draw = useCallback(() => {
const canvas = canvasRef.current;
if (!canvas || !peaks) return;
- drawWaveformCanvas(canvas, peaks, muted, trimStartFraction ?? 0, trimEndFraction ?? 1, fades);
- }, [fades, muted, peaks, trimEndFraction, trimStartFraction]);
-
- const setCanvasRef = useCallback(
- (canvas: HTMLCanvasElement | null) => {
- observerRef.current?.disconnect();
- canvasRef.current = canvas;
- if (!canvas) return;
- draw();
- observerRef.current = new ResizeObserver(draw);
- observerRef.current.observe(canvas);
- },
- [draw],
- );
+ const span = { from, to };
+ // Placed in fractions of the clip, so a zoom preview stretches the drawn bars with time.
+ canvas.style.left = `${span.from * 100}%`;
+ canvas.style.width = `${(span.to - span.from) * 100}%`;
+ if (span.to <= span.from) return;
+ drawWaveformCanvas(
+ canvas,
+ peaks,
+ muted,
+ trimStartFraction ?? 0,
+ trimEndFraction ?? 1,
+ fades,
+ span,
+ );
+ }, [fades, from, muted, peaks, to, trimEndFraction, trimStartFraction]);
+ useEffect(draw, [draw, strip.width, strip.height]);
useEffect(() => {
const root = document.documentElement;
@@ -225,8 +230,6 @@ export const AudioWaveform = memo(function AudioWaveform({
return () => observer.disconnect();
}, [draw]);
- useMountEffect(() => () => observerRef.current?.disconnect());
-
useEffect(() => {
const clip = rootRef.current?.closest(".timeline-clip");
if (!(clip instanceof HTMLElement)) return;
@@ -237,11 +240,35 @@ export const AudioWaveform = memo(function AudioWaveform({
return (
<div ref={rootRef} className="absolute inset-0">
- <div className="absolute inset-0 overflow-hidden" style={{ zIndex: WAVEFORM_LAYER_Z }}>
+ <div
+ ref={setStripRef}
+ className="absolute inset-0 overflow-hidden"
+ style={{ zIndex: WAVEFORM_LAYER_Z }}
+ >
+ {/* The undrawn ends: one coming near the screen, as a move carries the clip, re-measures. */}
+ {from > 0 && (
+ <div
+ ref={watchGap}
+ className="pointer-events-none absolute inset-y-0 left-0"
+ style={{ width: `${from * 100}%` }}
+ />
+ )}
+ {to < 1 && (
+ <div
+ ref={watchGap}
+ className="pointer-events-none absolute inset-y-0 right-0"
+ style={{ left: `${to * 100}%` }}
+ />
+ )}
<canvas
- ref={setCanvasRef}
- className="absolute inset-x-0 bottom-0 w-full"
- style={{ top: labelInset, height: `calc(100% - ${labelInset}px)` }}
+ ref={canvasRef}
+ className="absolute bottom-0"
+ style={{
+ left: 0,
+ width: "100%",
+ top: labelInset,
+ height: `calc(100% - ${labelInset}px)`,
+ }}
/>
{snapshot.status === "loading" && (
<div
diff --git a/packages/studio/src/player/components/Timeline.scrollRest.test.tsx b/packages/studio/src/player/components/Timeline.scrollRest.test.tsx
new file mode 100644
index 0000000000..78f0645ecd
--- /dev/null
+++ b/packages/studio/src/player/components/Timeline.scrollRest.test.tsx
@@ -0,0 +1,22 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, expect, it } from "vitest";
+import { mountThreeTrackTimeline } from "./timelineMountFixtures";
+import { installTimelineMountEnv } from "./timelineMountTestEnv";
+import { isTimelineMoving } from "./timelineMotion";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+installTimelineMountEnv();
+
+afterEach(() => {
+ document.body.innerHTML = "";
+});
+
+it("keeps the timeline at rest through a scroll, as playback follow makes every frame", async () => {
+ const { root, viewport } = await mountThreeTrackTimeline();
+ act(() => viewport.dispatchEvent(new Event("scroll")));
+ expect(isTimelineMoving()).toBe(false);
+ act(() => root.unmount());
+});
diff --git a/packages/studio/src/player/components/Timeline.test.ts b/packages/studio/src/player/components/Timeline.test.ts
index d8702d8a64..6c532c6b25 100644
--- a/packages/studio/src/player/components/Timeline.test.ts
+++ b/packages/studio/src/player/components/Timeline.test.ts
@@ -208,7 +208,9 @@ describe("Timeline provider boundary", () => {
renderTimelineGeometry("clip-1");
expect(trackHeader.style.width).toBe(`${GUTTER + TRACKS_LEFT_PAD}px`);
- expect(clip.style.left).toBe("1000px");
+ // 10 s at 100 px/s: 1000% of a one-second layer 100px wide.
+ expect(clip.style.left).toBe("1000%");
+ expect((clip.closest("[data-timeline-time-layer]") as HTMLElement).style.width).toBe("100px");
expect(clip.style.height).toBe("");
expect(clip.style.bottom).toBe(`${CLIP_Y}px`);
expect(rulerOrigin.style.width).toBe(`${GUTTER + TRACKS_LEFT_PAD}px`);
diff --git a/packages/studio/src/player/components/TimelineCanvas.tsx b/packages/studio/src/player/components/TimelineCanvas.tsx
index 923844a59b..3929162034 100644
--- a/packages/studio/src/player/components/TimelineCanvas.tsx
+++ b/packages/studio/src/player/components/TimelineCanvas.tsx
@@ -116,6 +116,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
return visibleIntervals.map((gap) => (
<div
key={`gap-${strip.kind}-${strip.track}-${gap.start}`}
+ data-timeline-zoom-scale={-gap.start * props.pps}
className="pointer-events-none absolute"
style={{
top: props.rowGeometry.getRowTop(rowIndex) + CLIP_Y,
@@ -246,6 +247,9 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
{/* Range highlight */}
{props.rangeSelection && (
<div
+ data-timeline-zoom-scale={
+ -Math.min(props.rangeSelection.start, props.rangeSelection.end) * props.pps
+ }
className="absolute pointer-events-none"
style={{
left:
diff --git a/packages/studio/src/player/components/TimelineClip.tsx b/packages/studio/src/player/components/TimelineClip.tsx
index 29aed434a9..c63a3c41e7 100644
--- a/packages/studio/src/player/components/TimelineClip.tsx
+++ b/packages/studio/src/player/components/TimelineClip.tsx
@@ -17,6 +17,7 @@ import { linkLabelColor } from "./linkLabelColor";
import { OutOfSyncBadge } from "./OutOfSyncBadge";
import { clipSpeedSuffix } from "./clipToolAttrs";
import { ClipPeakTooltip } from "./ClipPeakTooltip";
+import { timeLayerPercent } from "./TimelineTimeLayer";
interface TimelineClipProps {
el: TimelineElement;
@@ -44,6 +45,20 @@ interface TimelineClipProps {
children?: ReactNode;
}
+const HANDLES_MIN_PX = 32;
+
+const CLIP_MIN_WIDTH_PX = 4;
+export const clipWidthPx = (el: TimelineElement, pps: number) =>
+ Math.max(el.duration * pps, CLIP_MIN_WIDTH_PX);
+
+/** Zoom-dependent drawing as one value: width tier and trim fit, or the scale while fades show. */
+export function clipZoomKey(el: TimelineElement, pps: number, interacting: boolean) {
+ const fadesLive = interacting || (el.fadeIn ?? 0) > 0 || (el.fadeOut ?? 0) > 0;
+ if (fadesLive) return pps;
+ const widthPx = clipWidthPx(el, pps);
+ return `${clipWidthLadder(widthPx)}${widthPx >= HANDLES_MIN_PX ? "+handles" : ""}`;
+}
+
// fallow-ignore-next-line complexity
export const TimelineClip = memo(function TimelineClip({
el,
@@ -70,13 +85,12 @@ export const TimelineClip = memo(function TimelineClip({
onContextMenu,
children,
}: TimelineClipProps) {
- const leftPx = el.start * pps;
- const widthPx = Math.max(el.duration * pps, 4);
+ const widthPx = clipWidthPx(el, pps);
const handleOpacity = getClipHandleOpacity({ isHovered, isSelected, isDragging });
const displayLabel = `${el.label || el.id || el.tag}${clipSpeedSuffix(el.playbackRate, el.automation)}`;
const isAudioClip = isAudioTimelineElement(el);
const ladder = clipWidthLadder(widthPx);
- const showHandles = handleOpacity > 0.01 && (widthPx >= 32 || isSelected);
+ const showHandles = handleOpacity > 0.01 && (widthPx >= HANDLES_MIN_PX || isSelected);
const showLabel = !isAudioClip || ladder === "labeled";
const showDefaultText = !hasCustomContent && ladder === "labeled";
const startLabel = el.start.toFixed(1);
@@ -111,14 +125,14 @@ export const TimelineClip = memo(function TimelineClip({
.filter((className) => className.length > 0)
.join(" ");
const style: CSSProperties = {
- left: leftPx,
- width: widthPx,
+ left: timeLayerPercent(el.start),
+ width: timeLayerPercent(el.duration),
+ minWidth: CLIP_MIN_WIDTH_PX,
top: clipY,
...(clipHeight === undefined ? { bottom: clipY } : { height: clipHeight }),
borderRadius: isAudioClip ? theme.audioClipRadius : theme.clipRadius,
...themeVariables,
zIndex: isDragging ? 20 : isSelected ? 10 : isHovered ? 5 : 1,
- // Regular cursor over clips (CapCut-style, user preference) — no grab hand.
cursor: "default",
appearance: "none",
color: "inherit",
diff --git a/packages/studio/src/player/components/TimelineClipFades.test.tsx b/packages/studio/src/player/components/TimelineClipFades.test.tsx
index 37936b3d97..8137d465e2 100644
--- a/packages/studio/src/player/components/TimelineClipFades.test.tsx
+++ b/packages/studio/src/player/components/TimelineClipFades.test.tsx
@@ -129,6 +129,17 @@ describe("TimelineClipFades", () => {
act(() => root.unmount());
});
+ it("measures the clip only while its handles show, so a zoom step forces no layout", () => {
+ const measure = vi.spyOn(window, "getComputedStyle");
+ const { rerender } = render(clip, { showHandles: false });
+ rerender({ ...clip, duration: 11 });
+ expect(measure).not.toHaveBeenCalled();
+ act(() => mounted[0]?.unmount());
+ render(clip, { showHandles: true });
+ expect(measure).toHaveBeenCalled();
+ measure.mockRestore();
+ });
+
it("renders nothing for a clip without fades when the handles are hidden", () => {
const { host, root } = render(
{ ...clip, fadeIn: undefined, fadeOut: undefined },
diff --git a/packages/studio/src/player/components/TimelineClipFades.tsx b/packages/studio/src/player/components/TimelineClipFades.tsx
index 2d35771eec..6dc23dd9c1 100644
--- a/packages/studio/src/player/components/TimelineClipFades.tsx
+++ b/packages/studio/src/player/components/TimelineClipFades.tsx
@@ -139,10 +139,12 @@ export function TimelineClipFades({
radius: 0,
toolsLeft: null,
});
+ const handlesVisible = showHandles || dragging !== null || focused !== null;
+ // Measured only while the handles show: a zoom step must not force a layout per clip.
useLayoutEffect(() => {
const root = rootRef.current;
const clip = root?.parentElement;
- if (!root || !clip) return;
+ if (!handlesVisible || !root || !clip) return;
const radius = parseFloat(getComputedStyle(clip).borderTopLeftRadius) || 0;
const { clientHeight: height, clientWidth: width } = root;
const fx = clip.querySelector('[data-badge="fx"]');
@@ -157,7 +159,7 @@ export function TimelineClipFades({
? box
: { height, width, radius, toolsLeft },
);
- }, [widthPx, visible]);
+ }, [widthPx, handlesVisible]);
const gesture = useRef<{
edge: FadeEdge;
@@ -205,7 +207,6 @@ export function TimelineClipFades({
const g = gesture.current;
if (!g) return 0;
const deltaSeconds = (clientX - g.originClientX) / Math.max(pps, 1e-6);
- // Fade-in grows to the right, fade-out grows to the left.
const raw = g.edge === "in" ? g.originSeconds + deltaSeconds : g.originSeconds - deltaSeconds;
const limit = dragLimit(g);
const clamped = Math.min(limit, Math.max(0, raw));
@@ -342,7 +343,6 @@ export function TimelineClipFades({
const showIn = fades.fadeIn > 0;
const showOut = fades.fadeOut > 0;
- const handlesVisible = showHandles || dragging !== null || focused !== null;
if (!visible) return null;
// A handle with no 0.01 s step to move is not drawn, unless in use: its twin owns the spot.
diff --git a/packages/studio/src/player/components/TimelineClipJoins.tsx b/packages/studio/src/player/components/TimelineClipJoins.tsx
index 623a667c36..c3e86823ac 100644
--- a/packages/studio/src/player/components/TimelineClipJoins.tsx
+++ b/packages/studio/src/player/components/TimelineClipJoins.tsx
@@ -1,6 +1,7 @@
import { CLIP_Y } from "./timelineLayout";
import { sortedLaneClips, TRACK_GAP_EPSILON_S } from "./timelineGaps";
import type { TimelineElement } from "../store/playerStore";
+import { TimelineTimeLayer, timeLayerPercent } from "./TimelineTimeLayer";
/** Times where one clip on a row ends exactly where the next begins. */
export function deriveTimelineClipJoins(elements: readonly TimelineElement[]): number[] {
@@ -31,22 +32,26 @@ export function TimelineClipJoins({
color,
}: TimelineClipJoinsProps) {
const height = clipBarHeight ?? rowHeight - 2 * CLIP_Y;
- return deriveTimelineClipJoins(elements).map((time) => (
- <div
- key={time}
- data-timeline-clip-join=""
- aria-hidden="true"
- className="absolute pointer-events-none"
- style={{
- left: time * pixelsPerSecond,
- top: CLIP_Y,
- width: 1,
- height,
- transform: "translateX(-50%)",
- background: color,
- // Over an idle or hovered clip, under the diamonds (6) and a selected clip (10).
- zIndex: 5,
- }}
- />
- ));
+ return (
+ <TimelineTimeLayer pixelsPerSecond={pixelsPerSecond}>
+ {deriveTimelineClipJoins(elements).map((time) => (
+ <div
+ key={time}
+ data-timeline-clip-join=""
+ aria-hidden="true"
+ className="absolute pointer-events-none"
+ style={{
+ left: timeLayerPercent(time),
+ top: CLIP_Y,
+ width: 1,
+ height,
+ transform: "translateX(-50%)",
+ background: color,
+ // Over an idle or hovered clip, under the diamonds (6) and a selected clip (10).
+ zIndex: 5,
+ }}
+ />
+ ))}
+ </TimelineTimeLayer>
+ );
}
diff --git a/packages/studio/src/player/components/TimelineGestureOverlay.tsx b/packages/studio/src/player/components/TimelineGestureOverlay.tsx
index bb1b89a2f3..1e957f771c 100644
--- a/packages/studio/src/player/components/TimelineGestureOverlay.tsx
+++ b/packages/studio/src/player/components/TimelineGestureOverlay.tsx
@@ -10,6 +10,7 @@ import type { DraggedClipState } from "./timelineClipDragTypes";
import type { TrackVisualStyle } from "./timelineIcons";
import { isTimelineClipActive } from "./useTimelineActiveClips";
import type { TimelineProps } from "./TimelineTypes";
+import { TimelineTimeLayer } from "./TimelineTimeLayer";
interface TimelineGestureOverlayProps {
drag: DraggedClipState | null;
@@ -103,33 +104,35 @@ export const TimelineGestureOverlay = memo(function TimelineGestureOverlay({
+ New track<span className="sr-only">, before track {insertRow + 1}</span>
</span>
)}
- <TimelineClip
- el={{ ...element, start: 0 }}
- pps={pixelsPerSecond}
- clipY={0}
- isSelected={selectedElementId === (element.key ?? element.id)}
- isHovered={false}
- isDragging
- isGestureActor
- isActive={isTimelineClipActive(element, currentTime)}
- hasCustomContent={!!renderClipContent}
- capabilities={getTimelineEditCapabilities(element)}
- theme={theme}
- isComposition={!!element.compositionSrc}
- onHoverStart={() => {}}
- onHoverEnd={() => {}}
- onResizeStart={() => {}}
- onClick={() => {}}
- onDoubleClick={() => {}}
- >
- {renderClipChildren(
- element,
- getTrackStyle(element.tag),
- renderClipContent,
- renderClipOverlay,
- { priority: "interaction", rich: false },
- )}
- </TimelineClip>
+ <TimelineTimeLayer pixelsPerSecond={pixelsPerSecond}>
+ <TimelineClip
+ el={{ ...element, start: 0 }}
+ pps={pixelsPerSecond}
+ clipY={0}
+ isSelected={selectedElementId === (element.key ?? element.id)}
+ isHovered={false}
+ isDragging
+ isGestureActor
+ isActive={isTimelineClipActive(element, currentTime)}
+ hasCustomContent={!!renderClipContent}
+ capabilities={getTimelineEditCapabilities(element)}
+ theme={theme}
+ isComposition={!!element.compositionSrc}
+ onHoverStart={() => {}}
+ onHoverEnd={() => {}}
+ onResizeStart={() => {}}
+ onClick={() => {}}
+ onDoubleClick={() => {}}
+ >
+ {renderClipChildren(
+ element,
+ getTrackStyle(element.tag),
+ renderClipContent,
+ renderClipOverlay,
+ { priority: "interaction", rich: false },
+ )}
+ </TimelineClip>
+ </TimelineTimeLayer>
</div>
)}
</div>
diff --git a/packages/studio/src/player/components/TimelineGroupRow.tsx b/packages/studio/src/player/components/TimelineGroupRow.tsx
index 3ed097eed0..a12bef8dfb 100644
--- a/packages/studio/src/player/components/TimelineGroupRow.tsx
+++ b/packages/studio/src/player/components/TimelineGroupRow.tsx
@@ -201,6 +201,7 @@ export function TimelineGroupRow({
// from x=0.
<div
role="gridcell"
+ data-timeline-zoom-scale=""
aria-colindex={2}
style={{ width: trackContentWidth, marginLeft: contentGutter }}
className="relative"
diff --git a/packages/studio/src/player/components/TimelineLaneClip.tsx b/packages/studio/src/player/components/TimelineLaneClip.tsx
new file mode 100644
index 0000000000..81f55b44d6
--- /dev/null
+++ b/packages/studio/src/player/components/TimelineLaneClip.tsx
@@ -0,0 +1,127 @@
+import { memo, type CSSProperties, type RefObject } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import type { ThumbnailPriority } from "../lib/thumbnailScheduler";
+import { TimelineClip, clipZoomKey } from "./TimelineClip";
+import { createClipGestureHandlers, type ClipGestureDeps } from "./timelineClipGestureHandlers";
+import { renderClipChildren } from "./timelineClipChildren";
+import type { TimelineEditCapabilities } from "./timelineEditCapabilities";
+import type { TrackVisualStyle } from "./timelineIcons";
+import { CLIP_Y } from "./timelineLayout";
+import type { TimelineTheme } from "./timelineTheme";
+import type { TimelineProps } from "./TimelineTypes";
+
+/** The lane's callbacks as of its last render, read when a clip is pressed rather than drawn. */
+export interface TimelineLaneClipActions {
+ gestures: ClipGestureDeps;
+ setHoveredClip(key: string | null): void;
+ onContextMenuClip?: (e: React.MouseEvent, element: TimelineElement) => void;
+ onDrillDown?: (element: TimelineElement) => void;
+}
+
+interface TimelineLaneClipProps {
+ el: TimelineElement;
+ previewElement: TimelineElement;
+ elementKey: string;
+ capabilities: TimelineEditCapabilities;
+ pps: number;
+ passengerStyle?: CSSProperties;
+ clipBarHeight?: number;
+ isSelected: boolean;
+ isHovered: boolean;
+ isActive: boolean;
+ tabIndex: 0 | -1;
+ priority: ThumbnailPriority;
+ rich: boolean;
+ theme: TimelineTheme;
+ clipStyle: TrackVisualStyle;
+ renderClipContent: TimelineProps["renderClipContent"];
+ renderClipOverlay: TimelineProps["renderClipOverlay"];
+ actions: RefObject<TimelineLaneClipActions>;
+}
+
+const sameCapabilities = (a: TimelineEditCapabilities, b: TimelineEditCapabilities) =>
+ a.canMove === b.canMove &&
+ a.canTrimStart === b.canTrimStart &&
+ a.canTrimEnd === b.canTrimEnd &&
+ a.readOnly === b.readOnly;
+
+const zoomKey = (p: TimelineLaneClipProps) =>
+ clipZoomKey(p.previewElement, p.pps, p.isSelected || p.isHovered);
+
+/** A zoom step re-renders only the clips whose drawing it changes. */
+function sameClip(prev: TimelineLaneClipProps, next: TimelineLaneClipProps): boolean {
+ for (const key of Object.keys(next) as (keyof TimelineLaneClipProps)[]) {
+ if (key === "pps" || key === "capabilities" || prev[key] === next[key]) continue;
+ return false;
+ }
+ return sameCapabilities(prev.capabilities, next.capabilities) && zoomKey(prev) === zoomKey(next);
+}
+
+/** One clip bar in a lane; its handlers read the lane's current callbacks when pressed. */
+export const TimelineLaneClip = memo(function TimelineLaneClip({
+ el,
+ previewElement,
+ elementKey,
+ capabilities,
+ pps,
+ passengerStyle,
+ clipBarHeight,
+ isSelected,
+ isHovered,
+ isActive,
+ tabIndex,
+ priority,
+ rich,
+ theme,
+ clipStyle,
+ renderClipContent,
+ renderClipOverlay,
+ actions,
+}: TimelineLaneClipProps) {
+ const gestures = () =>
+ createClipGestureHandlers(
+ el,
+ elementKey,
+ previewElement,
+ capabilities,
+ actions.current.gestures,
+ );
+ const isComposition = !!el.compositionSrc;
+ return (
+ <TimelineClip
+ onContextMenu={(e: React.MouseEvent) => {
+ e.preventDefault();
+ actions.current.onContextMenuClip?.(e, el);
+ }}
+ el={previewElement}
+ pps={pps}
+ passengerStyle={passengerStyle}
+ clipY={CLIP_Y}
+ clipHeight={clipBarHeight}
+ isSelected={isSelected}
+ isHovered={isHovered}
+ isDragging={false}
+ isActive={isActive}
+ hasCustomContent={!!renderClipContent}
+ capabilities={capabilities}
+ theme={theme}
+ isComposition={isComposition}
+ tabIndex={tabIndex}
+ onHoverStart={() => actions.current.setHoveredClip(elementKey)}
+ onHoverEnd={() => actions.current.setHoveredClip(null)}
+ onResizeStart={(edge, e) => gestures().onResizeStart(edge, e)}
+ onPointerDown={(e) => gestures().onPointerDown(e)}
+ onClick={(e) => gestures().onClick(e)}
+ onDoubleClick={(e) => {
+ e.stopPropagation();
+ if (actions.current.gestures.suppressClickRef.current) return;
+ if (isComposition) actions.current.onDrillDown?.(el);
+ }}
+ >
+ {renderClipChildren(previewElement, clipStyle, renderClipContent, renderClipOverlay, {
+ priority,
+ rich,
+ })}
+ </TimelineClip>
+ );
+}, sameClip);
diff --git a/packages/studio/src/player/components/TimelineLanes.test.tsx b/packages/studio/src/player/components/TimelineLanes.test.tsx
index deab4d5721..9fadb5506c 100644
--- a/packages/studio/src/player/components/TimelineLanes.test.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.test.tsx
@@ -89,8 +89,11 @@ interface RenderLanesOptions {
renderClipContent?: React.ComponentProps<typeof TimelineLanes>["renderClipContent"];
snapGuide?: { time: number; type: "beat" | "clip-edge" | "playhead" } | null;
withoutSelectHandler?: boolean;
+ pps?: number;
}
+const lanePps = (options: RenderLanesOptions) => options.pps ?? 100;
+
const selectHandlerFor = (
options: RenderLanesOptions,
handler: (element: TimelineElement | null) => void,
@@ -102,12 +105,14 @@ function renderLanes(options: RenderLanesOptions = {}): {
rerender: (next: RenderLanesOptions) => void;
setSelectedElementId: ReturnType<typeof vi.fn>;
onSelectElement: ReturnType<typeof vi.fn>;
+ onRazorSplit: ReturnType<typeof vi.fn>;
} {
const host = document.createElement("div");
document.body.append(host);
const root = createRoot(host);
const setSelectedElementId = vi.fn();
const onSelectElement = vi.fn();
+ const onRazorSplit = vi.fn();
const render = (next: RenderLanesOptions) => {
const elements = next.elements ?? [element("clip-a", TRACK_A)];
const gsapAnimations = next.animations ?? new Map<string, GsapAnimation[]>();
@@ -124,7 +129,7 @@ function renderLanes(options: RenderLanesOptions = {}): {
usePlayerStore.setState({ expandedClipIds: new Set(next.expandedClipIds ?? []) });
root.render(
<TimelineLanes
- pps={100}
+ pps={lanePps(next)}
contentOrigin={232}
contentGutter={32}
trackContentWidth={800}
@@ -186,14 +191,14 @@ function renderLanes(options: RenderLanesOptions = {}): {
onResizeElement={vi.fn()}
onMoveElement={vi.fn()}
onSelectElement={selectHandlerFor(next, onSelectElement)}
- onRazorSplit={vi.fn()}
+ onRazorSplit={onRazorSplit}
onRazorSplitAll={vi.fn()}
/>,
);
});
};
render(options);
- return { host, root, rerender: render, setSelectedElementId, onSelectElement };
+ return { host, root, rerender: render, setSelectedElementId, onSelectElement, onRazorSplit };
}
function visibilityLabels(host: HTMLElement): (string | null)[] {
@@ -586,12 +591,18 @@ describe("TimelineLanes clip joins", () => {
const joins = view.host.querySelectorAll<HTMLElement>("[data-timeline-clip-join]");
expect(joins).toHaveLength(1);
- expect(joins[0]?.style.left).toBe("200px");
+ // Both sit in one-second layers 100px wide: 200% is 200px, at the 2 s join.
+ const layerWidth = (el: Element | null | undefined) =>
+ (el?.closest("[data-timeline-time-layer]") as HTMLElement | null)?.style.width;
+ expect(joins[0]?.style.left).toBe("200%");
+ expect(layerWidth(joins[0])).toBe("100px");
expect(joins[0]?.style.width).toBe("1px");
expect(joins[0]?.style.background).toBe(defaultTimelineTheme.rowBackground);
const clipB = view.host.querySelector<HTMLElement>('[data-el-id="clip-b"]');
- expect(clipB?.style.left).toBe("200px");
- expect(clipB?.style.width).toBe("150px");
+ expect(clipB?.style.left).toBe("200%");
+ expect(clipB?.style.width).toBe("150%");
+ expect(clipB?.style.minWidth).toBe("4px");
+ expect(layerWidth(clipB)).toBe("100px");
act(() => view.root.unmount());
});
@@ -624,3 +635,37 @@ describe("TimelineLanes transition seams", () => {
act(() => view.root.unmount());
});
});
+
+describe("TimelineLanes clips during a zoom", () => {
+ afterEach(() => {
+ usePlayerStore.setState({ activeTool: "select" });
+ });
+
+ it("leaves a clip unrendered by a zoom step that does not change what it draws", () => {
+ const renderClipContent = vi.fn(() => null);
+ const clip = { ...element("clip-a", TRACK_A), start: 0, duration: 2 };
+ const view = renderLanes({ elements: [clip], renderClipContent, pps: 100 });
+ const drawn = renderClipContent.mock.calls.length;
+ // 200px to 220px: still a labelled clip with handles.
+ view.rerender({ elements: [clip], renderClipContent, pps: 110 });
+ expect(renderClipContent.mock.calls.length).toBe(drawn);
+ // 40px: the clip drops its label, so it draws again.
+ view.rerender({ elements: [clip], renderClipContent, pps: 20 });
+ expect(renderClipContent.mock.calls.length).toBeGreaterThan(drawn);
+ act(() => view.root.unmount());
+ });
+
+ it("splits with the razor at the time under the pointer at the current zoom", () => {
+ usePlayerStore.setState({ activeTool: "razor" });
+ const clip = { ...element("clip-a", TRACK_A), start: 0, duration: 2 };
+ const view = renderLanes({ elements: [clip], pps: 100 });
+ view.rerender({ elements: [clip], pps: 105 });
+ act(() => {
+ view.host
+ .querySelector('[data-el-id="clip-a"]')
+ ?.dispatchEvent(new MouseEvent("click", { bubbles: true, clientX: 105 }));
+ });
+ expect(view.onRazorSplit).toHaveBeenCalledWith(expect.objectContaining({ id: "clip-a" }), 1);
+ act(() => view.root.unmount());
+ });
+});
diff --git a/packages/studio/src/player/components/TimelineLanes.tsx b/packages/studio/src/player/components/TimelineLanes.tsx
index b9a22f610f..a02fa648c1 100644
--- a/packages/studio/src/player/components/TimelineLanes.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.tsx
@@ -1,6 +1,6 @@
-import { Fragment, useId, useMemo, type CSSProperties } from "react";
+import { Fragment, useId, useMemo, useRef, type CSSProperties } from "react";
import { BeatStrip, BeatBackgroundLines } from "./BeatStrip";
-import { TimelineClip } from "./TimelineClip";
+import { TimelineLaneClip, type TimelineLaneClipActions } from "./TimelineLaneClip";
import { TimelineCompactDiamonds } from "./TimelineCompactDiamonds";
import { TimelinePropertyLanes } from "./TimelinePropertyLanes";
import { TimelineAutomationLaneSlot } from "./TimelineAutomationLaneSlot";
@@ -10,6 +10,8 @@ import { TimelineTrackHeader } from "./TimelineTrackHeader";
import { TimelineGroupRow } from "./TimelineGroupRow";
import { useTimelineLaneRowIndexes, useTimelineGroupDisclosure } from "./useTimelineLaneRowIndexes";
import { useTimelineClipDisclosure } from "./useTimelineClipDisclosure";
+import { TimelineTimeLayer } from "./TimelineTimeLayer";
+import { clipWidthPx } from "./TimelineClip";
import {
isTrackRowExpanded,
resolveTrackKeyframeClip,
@@ -24,8 +26,7 @@ import { isMultiDragPassenger, multiDragPassengerOffsetPx } from "./timelineMult
import { useTimelineMultiDragActorWindows } from "./useTimelineMultiDragActorWindows";
import type { TimelineLanesProps } from "./timelineLaneProps";
import { isAudioTimelineElement, isMusicTrack } from "../../utils/timelineInspector";
-import { createClipGestureHandlers } from "./timelineClipGestureHandlers";
-import { renderClipChildren, resolveClipRenderContext } from "./timelineClipChildren";
+import { resolveClipRenderContext } from "./timelineClipChildren";
import { TimelineTrackRow } from "./TimelineTrackRow";
import { isTimelineClipActive } from "./useTimelineActiveClips";
import { queryTimelineClipIndex } from "../lib/timelineClipIndex";
@@ -143,6 +144,28 @@ export function TimelineLanes({
onToggleRow: (row) => row.elementId && toggleClipExpandedTracked(row.elementId),
onDrillDown,
});
+ const clipActions = useRef<TimelineLaneClipActions>(null!);
+ clipActions.current = {
+ gestures: {
+ pps,
+ onResizeElement,
+ onMoveElement,
+ onRazorSplit,
+ onRazorSplitAll,
+ blockedClipRef,
+ suppressClickRef,
+ scrollRef,
+ setShowPopover,
+ setRangeSelection,
+ setResizingClip,
+ setDraggedClip,
+ setSelectedElementId,
+ onSelectElement,
+ },
+ setHoveredClip,
+ onContextMenuClip,
+ onDrillDown,
+ };
return (
<div
role="treegrid"
@@ -330,6 +353,7 @@ export function TimelineLanes({
<div
role="gridcell"
aria-colindex={2}
+ data-timeline-zoom-scale=""
style={{
width: trackContentWidth,
marginLeft: contentGutter, // room for a 0% diamond left of t=0
@@ -368,181 +392,145 @@ export function TimelineLanes({
renderTimeRange={rowsVirtualized ? renderTimeRange : undefined}
/>
)}
- {
- // fallow-ignore-next-line complexity
- renderElements.map((el) => {
- const clipStyle = getTrackStyle(el.tag);
- const elementKey = getTimelineElementIdentity(el);
- // Only the track's active keyframe clip shows expanded lanes;
- // other clips (incl. siblings on a shared track) show compact
- // diamonds on their own bar instead.
- const isTrackKeyframeClip = elementKey === keyframeClipKey;
- const showsLanes = isTrackKeyframeClip && rowExpanded;
- const capabilities = getClipCapabilities(el);
- const isSelected =
- selectedElementId === elementKey || selectedElementIds.has(elementKey);
- const isComposition = !!el.compositionSrc;
- // Element identity stays stable across clip splices and reorders.
- const clipKey = elementKey;
- const isDraggingClip =
- draggedClip?.started === true &&
- draggedElement != null &&
- getTimelineElementIdentity(draggedElement) === elementKey;
- if (isDraggingClip) return null;
- const previewElement = getPreviewElement(el);
- const renderContext = resolveClipRenderContext(
- previewElement,
- visibleTimeRange,
- isSelected || hoveredClip === clipKey || pinnedClipIdentities.has(clipKey),
- );
- // Passenger of a live multi-drag: preserve the formation without changing
- // the passenger's timeline data until the owning drag commits.
- const isPassenger =
- multiDragPreview != null && isMultiDragPassenger(clipKey, multiDragPreview);
- const passengerStyle = isPassenger
- ? passengerStyleAt(multiDragPassengerOffsetPx(clipKey, pps, multiDragPreview))
- : undefined;
- const clipGestures = createClipGestureHandlers(
- el,
- elementKey,
- previewElement,
- capabilities,
- {
- pps,
- onResizeElement,
- onMoveElement,
- onRazorSplit,
- onRazorSplitAll,
- blockedClipRef,
- suppressClickRef,
- scrollRef,
- setShowPopover,
- setRangeSelection,
- setResizingClip,
- setDraggedClip,
- setSelectedElementId,
- onSelectElement,
- },
- );
- const clip = (
- <TimelineClip
- key={clipKey}
- onContextMenu={(e: React.MouseEvent) => {
- e.preventDefault();
- onContextMenuClip?.(e, el);
- }}
- el={previewElement}
- pps={pps}
- passengerStyle={passengerStyle}
- clipY={CLIP_Y}
- clipHeight={clipBarHeight}
- isSelected={isSelected}
- isHovered={hoveredClip === clipKey}
- isDragging={false}
- isActive={isTimelineClipActive(previewElement, currentTime)}
- hasCustomContent={!!renderClipContent}
- capabilities={capabilities}
- theme={theme}
- isComposition={isComposition}
- tabIndex={
- keyboard.rovingTargetId === timelineClipFocusId(elementKey) ? 0 : -1
- }
- onHoverStart={() => setHoveredClip(clipKey)}
- onHoverEnd={() => setHoveredClip(null)}
- onResizeStart={clipGestures.onResizeStart}
- onPointerDown={clipGestures.onPointerDown}
- onClick={clipGestures.onClick}
- onDoubleClick={(e) => {
- e.stopPropagation();
- if (suppressClickRef.current) return;
- if (isComposition && onDrillDown) onDrillDown(el);
- }}
- >
- {renderClipChildren(
- previewElement,
- clipStyle,
- renderClipContent,
- renderClipOverlay,
- renderContext,
- )}
- </TimelineClip>
- );
- const compactKeyframes = keyframeCache?.get(elementKey);
- const compactDiamonds = !showsLanes && compactKeyframes && (
- <TimelineCompactDiamonds
- key={`${clipKey}-diamonds`}
- element={previewElement}
- elementId={elementKey}
- keyframesData={compactKeyframes}
- pixelsPerSecond={pps}
- rowHeight={rowHeight}
- beatsActive={beatStripOnTrack}
- accentColor={clipStyle.accent}
- isSelected={isSelected}
- passengerStyle={passengerStyle}
- currentTime={currentTime}
- selectedKeyframes={selectedKeyframes}
- rovingTargetId={keyboard.rovingTargetId}
- onClickKeyframe={onClickKeyframe}
- onShiftClickKeyframe={onShiftClickKeyframe}
- onContextMenuKeyframe={onContextMenuKeyframe}
- onMoveKeyframe={onMoveKeyframe}
- onSelectSegment={onSelectSegment}
- suppressClickRef={suppressClickRef}
- />
- );
- // Keep this shell mounted while collapsed so aria-controls stays valid
- // and multi-drag cannot remount the subtree mid-gesture.
- const propertyLanes = isTrackKeyframeClip && (
- <TimelinePropertyLanes
- key={`${clipKey}-property-lanes`}
- id={lanesId}
- animations={showsLanes ? (gsapAnimations.get(elementKey) ?? []) : []}
- // clipTimingStart, not the raw start: an expanded sub-comp
- // child's start is host-absolute while its tweens are
- // local to its own file.
- clipStart={clipTimingStart(previewElement)}
- clipDuration={previewElement.duration}
- clipLeftPx={previewElement.start * pps}
- clipWidthPx={Math.max(previewElement.duration * pps, 4)}
- passengerStyle={passengerStyle}
- accentColor={clipStyle.accent}
- isSelected={isSelected}
- currentPercentage={
- previewElement.duration > 0
- ? ((currentTime - previewElement.start) / previewElement.duration) * 100
- : 0
- }
- elementId={elementKey}
- selectedKeyframes={selectedKeyframes}
- rovingTargetId={keyboard.rovingTargetId}
- onSelectSegment={(target) => onSelectSegment?.(elementKey, target)}
- onClickKeyframe={(target) => onClickKeyframe?.(previewElement, target)}
- onShiftClickKeyframe={(target) =>
- onShiftClickKeyframe?.(elementKey, target)
- }
- onContextMenuKeyframe={(e, target) =>
- onContextMenuKeyframe?.(e, elementKey, target)
- }
- onMoveKeyframe={(target, toClipPercentage) =>
- onMoveKeyframe?.(elementKey, target, toClipPercentage) ??
- Promise.resolve(false)
- }
- suppressClickRef={suppressClickRef}
- />
- );
+ <TimelineTimeLayer pixelsPerSecond={pps}>
+ {
+ // fallow-ignore-next-line complexity
+ renderElements.map((el) => {
+ const clipStyle = getTrackStyle(el.tag);
+ const elementKey = getTimelineElementIdentity(el);
+ // Only the track's active keyframe clip shows expanded lanes;
+ // other clips (incl. siblings on a shared track) show compact
+ // diamonds on their own bar instead.
+ const isTrackKeyframeClip = elementKey === keyframeClipKey;
+ const showsLanes = isTrackKeyframeClip && rowExpanded;
+ const capabilities = getClipCapabilities(el);
+ const isSelected =
+ selectedElementId === elementKey || selectedElementIds.has(elementKey);
+ // Element identity stays stable across clip splices and reorders.
+ const clipKey = elementKey;
+ const isDraggingClip =
+ draggedClip?.started === true &&
+ draggedElement != null &&
+ getTimelineElementIdentity(draggedElement) === elementKey;
+ if (isDraggingClip) return null;
+ const previewElement = getPreviewElement(el);
+ const renderContext = resolveClipRenderContext(
+ previewElement,
+ visibleTimeRange,
+ isSelected || hoveredClip === clipKey || pinnedClipIdentities.has(clipKey),
+ );
+ // Passenger of a live multi-drag: preserve the formation without changing
+ // the passenger's timeline data until the owning drag commits.
+ const isPassenger =
+ multiDragPreview != null && isMultiDragPassenger(clipKey, multiDragPreview);
+ const passengerStyle = isPassenger
+ ? passengerStyleAt(
+ multiDragPassengerOffsetPx(clipKey, pps, multiDragPreview),
+ )
+ : undefined;
+ const clip = (
+ <TimelineLaneClip
+ key={clipKey}
+ el={el}
+ previewElement={previewElement}
+ elementKey={elementKey}
+ capabilities={capabilities}
+ pps={pps}
+ passengerStyle={passengerStyle}
+ clipBarHeight={clipBarHeight}
+ isSelected={isSelected}
+ isHovered={hoveredClip === clipKey}
+ isActive={isTimelineClipActive(previewElement, currentTime)}
+ tabIndex={
+ keyboard.rovingTargetId === timelineClipFocusId(elementKey) ? 0 : -1
+ }
+ priority={renderContext.priority}
+ rich={renderContext.rich}
+ theme={theme}
+ clipStyle={clipStyle}
+ renderClipContent={renderClipContent}
+ renderClipOverlay={renderClipOverlay}
+ actions={clipActions}
+ />
+ );
+ const compactKeyframes = keyframeCache?.get(elementKey);
+ const compactDiamonds = !showsLanes && compactKeyframes && (
+ <TimelineCompactDiamonds
+ key={`${clipKey}-diamonds`}
+ element={previewElement}
+ elementId={elementKey}
+ keyframesData={compactKeyframes}
+ pixelsPerSecond={pps}
+ rowHeight={rowHeight}
+ beatsActive={beatStripOnTrack}
+ accentColor={clipStyle.accent}
+ isSelected={isSelected}
+ passengerStyle={passengerStyle}
+ currentTime={currentTime}
+ selectedKeyframes={selectedKeyframes}
+ rovingTargetId={keyboard.rovingTargetId}
+ onClickKeyframe={onClickKeyframe}
+ onShiftClickKeyframe={onShiftClickKeyframe}
+ onContextMenuKeyframe={onContextMenuKeyframe}
+ onMoveKeyframe={onMoveKeyframe}
+ onSelectSegment={onSelectSegment}
+ suppressClickRef={suppressClickRef}
+ />
+ );
+ // Keep this shell mounted while collapsed so aria-controls stays valid
+ // and multi-drag cannot remount the subtree mid-gesture.
+ const propertyLanes = isTrackKeyframeClip && (
+ <TimelinePropertyLanes
+ key={`${clipKey}-property-lanes`}
+ id={lanesId}
+ animations={showsLanes ? (gsapAnimations.get(elementKey) ?? []) : []}
+ // clipTimingStart, not the raw start: an expanded sub-comp
+ // child's start is host-absolute while its tweens are
+ // local to its own file.
+ clipStart={clipTimingStart(previewElement)}
+ clipDuration={previewElement.duration}
+ clipLeftPx={previewElement.start * pps}
+ clipWidthPx={clipWidthPx(previewElement, pps)}
+ passengerStyle={passengerStyle}
+ accentColor={clipStyle.accent}
+ isSelected={isSelected}
+ currentPercentage={
+ previewElement.duration > 0
+ ? ((currentTime - previewElement.start) / previewElement.duration) *
+ 100
+ : 0
+ }
+ elementId={elementKey}
+ selectedKeyframes={selectedKeyframes}
+ rovingTargetId={keyboard.rovingTargetId}
+ onSelectSegment={(target) => onSelectSegment?.(elementKey, target)}
+ onClickKeyframe={(target) => onClickKeyframe?.(previewElement, target)}
+ onShiftClickKeyframe={(target) =>
+ onShiftClickKeyframe?.(elementKey, target)
+ }
+ onContextMenuKeyframe={(e, target) =>
+ onContextMenuKeyframe?.(e, elementKey, target)
+ }
+ onMoveKeyframe={(target, toClipPercentage) =>
+ onMoveKeyframe?.(elementKey, target, toClipPercentage) ??
+ Promise.resolve(false)
+ }
+ suppressClickRef={suppressClickRef}
+ />
+ );
- // No wrapper node per clip, and the same Fragment whether or not it rides a
- // drag, so joining or leaving one restyles it, never remounts it.
- return (
- <Fragment key={clipKey}>
- {clip}
- {compactDiamonds}
- {propertyLanes}
- </Fragment>
- );
- })
- }
+ // No wrapper node per clip, and the same Fragment whether or not it rides a
+ // drag, so joining or leaving one restyles it, never remounts it.
+ return (
+ <Fragment key={clipKey}>
+ {clip}
+ {compactDiamonds}
+ {propertyLanes}
+ </Fragment>
+ );
+ })
+ }
+ </TimelineTimeLayer>
<TimelineTransitionOverlays
seams={transitionSeamsByTrack.get(trackNum) ?? []}
rowElements={draggedClip?.started ? [] : automationElements}
diff --git a/packages/studio/src/player/components/TimelineRuler.tsx b/packages/studio/src/player/components/TimelineRuler.tsx
index 0f2a7bcd71..5d944c5c8d 100644
--- a/packages/studio/src/player/components/TimelineRuler.tsx
+++ b/packages/studio/src/player/components/TimelineRuler.tsx
@@ -107,6 +107,7 @@ export const TimelineRuler = memo(function TimelineRuler({
{/* Background SVG — beat lines only; major-tick gridlines removed so only
the ruler's own small ticks mark intervals (no full-height lines). */}
<svg
+ data-timeline-zoom-scale=""
className="absolute pointer-events-none"
style={{ left: contentOrigin, width: trackContentWidth, zIndex: 0 }}
height={totalH}
@@ -152,6 +153,7 @@ export const TimelineRuler = memo(function TimelineRuler({
{/* Breathing pad before 00:00 is folded into contentOrigin (see
Timeline.tsx: GUTTER + TRACKS_LEFT_PAD), so no separate pad div. */}
<div
+ data-timeline-zoom-scale=""
className="relative overflow-hidden"
style={{
height: RULER_H,
diff --git a/packages/studio/src/player/components/TimelineTimeLayer.tsx b/packages/studio/src/player/components/TimelineTimeLayer.tsx
new file mode 100644
index 0000000000..8c417aef92
--- /dev/null
+++ b/packages/studio/src/player/components/TimelineTimeLayer.tsx
@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+
+/**
+ * A box one second wide at the current zoom. What sits in it places itself in percent of it
+ * (`left: start * 100%`), so a zoom step rewrites this one width and no clip's style changes.
+ */
+export function TimelineTimeLayer({
+ pixelsPerSecond,
+ children,
+}: {
+ pixelsPerSecond: number;
+ children: ReactNode;
+}) {
+ return (
+ <div
+ data-timeline-time-layer=""
+ className="absolute inset-y-0 left-0"
+ style={{ width: pixelsPerSecond }}
+ >
+ {children}
+ </div>
+ );
+}
+
+export const timeLayerPercent = (seconds: number) => `${seconds * 100}%`;
diff --git a/packages/studio/src/player/components/VideoThumbnail.test.tsx b/packages/studio/src/player/components/VideoThumbnail.test.tsx
index 4dcd72ca15..3f1801f438 100644
--- a/packages/studio/src/player/components/VideoThumbnail.test.tsx
+++ b/packages/studio/src/player/components/VideoThumbnail.test.tsx
@@ -6,6 +6,7 @@ import { thumbnailScheduler } from "../lib/thumbnailScheduler";
import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
import { createHappyDomRootHarness } from "./testRootHarness";
import { VideoThumbnail } from "./VideoThumbnail";
+import { markTimelineMotion } from "./timelineMotion";
vi.mock("../lib/thumbnailVideoDecoder", () => ({ decodeVideoThumbnail: vi.fn() }));
@@ -249,3 +250,49 @@ describe("VideoThumbnail", () => {
expect(host.querySelector("img")).toBeNull();
});
});
+
+describe("VideoThumbnail during a zoom", () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+ vi.mocked(decodeVideoThumbnail).mockResolvedValue({
+ value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 },
+ weight: 256,
+ });
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ const rest = () =>
+ act(async () => {
+ vi.runOnlyPendingTimers();
+ await Promise.resolve();
+ });
+
+ it("decodes a clip that scrolls in mid-zoom only once the timeline rests", async () => {
+ markTimelineMotion();
+ await render(440);
+ expect(decodeVideoThumbnail).not.toHaveBeenCalled();
+ await rest();
+ expect(decodeVideoThumbnail).toHaveBeenCalledWith(
+ expect.objectContaining({ frameCount: 1 }),
+ expect.any(AbortSignal),
+ );
+ });
+
+ it("keeps its filmstrip while the zoom resizes it, and decodes the new width at rest", async () => {
+ await render(440);
+ vi.mocked(decodeVideoThumbnail).mockClear();
+ await act(async () => {
+ markTimelineMotion();
+ reportResize(880, 40);
+ await Promise.resolve();
+ });
+ expect(decodeVideoThumbnail).not.toHaveBeenCalled();
+ await rest();
+ expect(decodeVideoThumbnail).toHaveBeenCalledWith(
+ expect.objectContaining({ frameCount: 16 }),
+ expect.any(AbortSignal),
+ );
+ });
+});
diff --git a/packages/studio/src/player/components/VideoThumbnail.tsx b/packages/studio/src/player/components/VideoThumbnail.tsx
index 9d42c11421..a5e00b8a4b 100644
--- a/packages/studio/src/player/components/VideoThumbnail.tsx
+++ b/packages/studio/src/player/components/VideoThumbnail.tsx
@@ -9,6 +9,7 @@ import {
import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
import { ThumbnailTiles } from "./ThumbnailTiles";
import { computeThumbnailStrip, quantizeThumbnailFrameCount } from "./thumbnailUtils";
+import { useValueAtRest } from "./timelineMotion";
interface VideoThumbnailProps {
videoSrc: string;
@@ -87,8 +88,10 @@ export const VideoThumbnail = memo(function VideoThumbnail({
priority = "visible",
}: VideoThumbnailProps) {
const [container, setContainerRef, watchGap] = useThumbnailStripSize();
- const requestFrameCount = quantizeThumbnailFrameCount(
- computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
+ const requestFrameCount = useValueAtRest(
+ quantizeThumbnailFrameCount(
+ computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
+ ),
);
const requestProps = useMemo(
() => ({
@@ -110,7 +113,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
() => createVideoThumbnailRequest(requestProps, requestFrameCount, true),
[requestFrameCount, requestProps],
);
- const measured = container.width > 0;
+ const measured = useValueAtRest(container.width > 0);
const posterSnapshot = useThumbnailLease(measured ? posterRequest : null);
const richSnapshot = useThumbnailLease(measured && requestFrameCount > 1 ? richRequest : null);
const snapshot = selectThumbnailSnapshot(posterSnapshot, richSnapshot);
diff --git a/packages/studio/src/player/components/timelineLayout.test.ts b/packages/studio/src/player/components/timelineLayout.test.ts
index 14f4d525e2..3a5c11c041 100644
--- a/packages/studio/src/player/components/timelineLayout.test.ts
+++ b/packages/studio/src/player/components/timelineLayout.test.ts
@@ -27,13 +27,13 @@ import { resolveInsertRow } from "./timelineCollision";
import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
describe("horizontal timeline window", () => {
- it("adds the shared quarter-viewport overscan on each side and clamps to duration", () => {
+ it("adds the shared half-viewport overscan on each side and clamps to duration", () => {
expect(getTimelineRenderTimeRange({ scrollLeft: 300, clientWidth: 500 }, 100, 200, 20)).toEqual(
- { start: 0, end: 7.25 },
+ { start: 0, end: 8.5 },
);
expect(
getTimelineRenderTimeRange({ scrollLeft: 1_900, clientWidth: 500 }, 100, 200, 20),
- ).toEqual({ start: 15.75, end: 20 });
+ ).toEqual({ start: 14.5, end: 20 });
});
it("generates globally aligned ticks directly inside the bounded window", () => {
diff --git a/packages/studio/src/player/components/timelineMotion.ts b/packages/studio/src/player/components/timelineMotion.ts
new file mode 100644
index 0000000000..2fda7a3b52
--- /dev/null
+++ b/packages/studio/src/player/components/timelineMotion.ts
@@ -0,0 +1,42 @@
+import { useState, useSyncExternalStore } from "react";
+
+/** How long the timeline must go without a zoom step to count as at rest. */
+export const TIMELINE_REST_MS = 150;
+
+let moving = false;
+let restTimer: ReturnType<typeof setTimeout> | null = null;
+const listeners = new Set<() => void>();
+
+const emit = () => listeners.forEach((listener) => listener());
+
+/** A zoom step: work that only matters at rest (redraws, decodes) waits for the zoom to end. */
+export function markTimelineMotion(): void {
+ if (!moving) {
+ moving = true;
+ emit();
+ }
+ if (restTimer) clearTimeout(restTimer);
+ restTimer = setTimeout(() => {
+ restTimer = null;
+ moving = false;
+ emit();
+ }, TIMELINE_REST_MS);
+}
+
+export function isTimelineMoving(): boolean {
+ return moving;
+}
+
+export function subscribeTimelineMotion(listener: () => void): () => void {
+ listeners.add(listener);
+ return () => listeners.delete(listener);
+}
+
+/** `value` at rest; while the timeline moves, the value it had when it last rested. */
+export function useValueAtRest<T>(value: T): T {
+ // Re-renders only when a zoom starts and when it rests.
+ const moving = useSyncExternalStore(subscribeTimelineMotion, isTimelineMoving, () => false);
+ const [held, setHeld] = useState(value);
+ if (!moving && !Object.is(held, value)) setHeld(value);
+ return moving ? held : value;
+}
diff --git a/packages/studio/src/player/components/timelineZoomInput.test.ts b/packages/studio/src/player/components/timelineZoomInput.test.ts
new file mode 100644
index 0000000000..f7ee6c8fa9
--- /dev/null
+++ b/packages/studio/src/player/components/timelineZoomInput.test.ts
@@ -0,0 +1,438 @@
+// @vitest-environment happy-dom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import { isTimelineMoving, subscribeTimelineMotion } from "./timelineMotion";
+import {
+ cancelTimelineZoom,
+ isTimelineZoomPreviewing,
+ subscribeTimelineZoomPreview,
+ redrawTimelineZoomPreview,
+ currentTimelineRange,
+ currentTimelineZoomPercent,
+ settleTimelineZoom,
+ timelineTimeAtX,
+ requestTimelineZoom,
+ registerTimelineZoomViewport,
+ takeTimelineZoomAnchor,
+ timelineZoomMapping,
+ zoomTimelineStep,
+ zoomTimelineToRange,
+} from "./timelineZoomInput";
+
+beforeEach(() => {
+ vi.useFakeTimers({
+ toFake: [
+ "requestAnimationFrame",
+ "cancelAnimationFrame",
+ "setTimeout",
+ "clearTimeout",
+ "performance",
+ ],
+ });
+ usePlayerStore.setState({
+ zoomMode: "fit",
+ manualZoomPercent: 100,
+ timelineFitPps: 10,
+ timelinePps: 10,
+ userZoomCount: 0,
+ currentTime: 0,
+ duration: 0,
+ });
+});
+afterEach(() => {
+ // Run out any ease, preview and rest, so the next test starts with nothing scheduled.
+ for (let i = 0; i < 40; i++) vi.advanceTimersToNextFrame();
+ unregisterViewport();
+ takeTimelineZoomAnchor();
+ vi.useRealTimers();
+});
+
+let unregisterViewport = () => {};
+
+/** A 1080px timeline viewport with 32px of track headers, holding one scaled row. */
+function viewport(scrollLeft = 0, scrollWidth = 20_000) {
+ const scroll = document.createElement("div");
+ Object.defineProperties(scroll, {
+ clientWidth: { value: 1080 },
+ scrollWidth: { value: scrollWidth },
+ scrollLeft: { value: scrollLeft, writable: true },
+ });
+ const row = scroll.appendChild(document.createElement("div"));
+ row.setAttribute("data-timeline-zoom-scale", "");
+ unregisterViewport = registerTimelineZoomViewport({ scroll, contentOrigin: 32 });
+ return { scroll, row };
+}
+
+/** Where `time` lands on screen once the committed zoom is laid out. */
+const laidOutX = (time: number) => {
+ const anchor = takeTimelineZoomAnchor();
+ return anchor && anchor.x + (time - anchor.time) * usePlayerStore.getState().timelinePps;
+};
+
+describe("requestTimelineZoom", () => {
+ it("scales the drawn rows during a gesture and lays the zoom out once it rests", () => {
+ const { row } = viewport();
+ const writes = vi.fn();
+ const unsubscribe = usePlayerStore.subscribe(writes);
+ requestTimelineZoom(120, { time: 4, x: 100 });
+ requestTimelineZoom(150, { time: 4, x: 100 });
+ vi.advanceTimersToNextFrame();
+ expect(writes).not.toHaveBeenCalled();
+ expect(currentTimelineZoomPercent()).toBe(150);
+ // 4 s stays at 100px: 32 + 4 * 15 - left = 100, left = -8 clamps to 0, translated by 0.
+ expect(row.style.transform).toBe("translateX(0px) scaleX(1.5)");
+ vi.advanceTimersByTime(150);
+ unsubscribe();
+ expect(writes).toHaveBeenCalledTimes(1);
+ expect(usePlayerStore.getState()).toMatchObject({
+ zoomMode: "manual",
+ manualZoomPercent: 150,
+ timelinePps: 15,
+ userZoomCount: 1,
+ });
+ expect(row.style.transform).toBe("");
+ });
+
+ it("keeps the time under the pointer while previewing, then lays it out there", () => {
+ usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 400, timelinePps: 40 });
+ const { scroll, row } = viewport(400);
+ // 432px in: (400 + 432 - 32) / 40 = 20 s.
+ requestTimelineZoom(600, { time: 20, x: 432 });
+ vi.advanceTimersToNextFrame();
+ const mapping = timelineZoomMapping(40, 32);
+ expect(mapping.pps).toBe(60);
+ expect(mapping.contentOrigin + 20 * mapping.pps - scroll.scrollLeft).toBeCloseTo(432);
+ expect(row.style.transform).toContain("scaleX(1.5)");
+ vi.advanceTimersByTime(150);
+ expect(laidOutX(20)).toBeCloseTo(432);
+ });
+
+ it("never previews a scroll the laid-out zoom cannot reach, zooming in from below Fit", () => {
+ usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 50, timelinePps: 5 });
+ viewport();
+ // 90 s sits 482px in at 5 px/s. At 110% the content is 32 + 1046 * 1.1 wide,
+ // so the view can scroll at most 102.6px.
+ requestTimelineZoom(110, { time: 90, x: 482 });
+ expect(timelineTimeAtX(32)! * 11).toBeLessThanOrEqual(102.6 + 1e-6);
+ });
+
+ it("lays a zoom-out about the left edge out at once, before it shows unmounted time", () => {
+ usePlayerStore.setState({ duration: 1000 });
+ viewport();
+ // Mounted to (1080 - 32 + 540) / 10 = 158.8 s; at 5 px/s the view reaches 209.6 s.
+ requestTimelineZoom(50, { time: 0, x: 32 });
+ vi.advanceTimersToNextFrame();
+ expect(usePlayerStore.getState().timelinePps).toBe(5);
+ });
+
+ it("previews a zoom-out about the middle that stays within what is mounted", () => {
+ usePlayerStore.setState({
+ duration: 100,
+ zoomMode: "manual",
+ manualZoomPercent: 1000,
+ timelinePps: 100,
+ });
+ viewport(5000);
+ // Mounted 44.28..65.88 s; at 60 px/s about 55.24 s the view shows 46.5..63.97 s.
+ requestTimelineZoom(600, { time: 55.24, x: 556 });
+ vi.advanceTimersToNextFrame();
+ expect(usePlayerStore.getState().timelinePps).toBe(100);
+ });
+
+ it("lays out a zoom-out before it shows past the window ruler ticks are drawn in", () => {
+ // 50 s of clips in content 1996 s wide: ticks are drawn to 157 s, a view and a half in.
+ usePlayerStore.setState({ duration: 50 });
+ viewport();
+ requestTimelineZoom(60, { time: 0, x: 32 });
+ vi.advanceTimersToNextFrame();
+ expect(usePlayerStore.getState().timelinePps).toBe(6);
+ });
+
+ it("lays a zoom-out out at once before it shows past where the ruler is drawn", () => {
+ // 50 s of clips at Fit: the ruler and lanes are drawn to the viewport's edge, 104.8 s.
+ usePlayerStore.setState({ duration: 50 });
+ viewport(0, 1080);
+ requestTimelineZoom(50, { time: 0, x: 32 });
+ vi.advanceTimersToNextFrame();
+ expect(usePlayerStore.getState().timelinePps).toBe(5);
+ });
+
+ it("previews a zoom-out at the content's end without laying out each frame", () => {
+ // At 330% the content is 32 + 1046 * 3.3 = 3483.8px, reported whole as 3483; the view is
+ // scrolled to its end, and a zoom-out lands that end a fraction of a pixel past it.
+ usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 330, timelinePps: 33 });
+ viewport(2403, 3483);
+ requestTimelineZoom(300, { time: 100, x: 800 });
+ vi.advanceTimersToNextFrame();
+ expect(usePlayerStore.getState().timelinePps).toBe(33);
+ });
+
+ it("keeps previewing through a scroll, and scales the rows the scroll mounted", async () => {
+ const { scroll } = viewport();
+ requestTimelineZoom(150);
+ vi.advanceTimersToNextFrame();
+ // React mounts the row after the scroll's redraw frame; it is scaled before it paints.
+ redrawTimelineZoomPreview();
+ vi.advanceTimersToNextFrame();
+ const mountedRow = document.createElement("div");
+ mountedRow.setAttribute("data-timeline-zoom-scale", "");
+ scroll.appendChild(document.createElement("div")).appendChild(mountedRow);
+ await Promise.resolve();
+ expect(usePlayerStore.getState().timelinePps).toBe(10);
+ expect(mountedRow.style.transform).toContain("scaleX(1.5)");
+ });
+
+ it("lays a pending zoom out at once when settled, as a press does", () => {
+ viewport();
+ requestTimelineZoom(150);
+ settleTimelineZoom();
+ expect(usePlayerStore.getState().timelinePps).toBe(15);
+ });
+
+ it("tells listeners when a pending zoom is dropped", () => {
+ viewport();
+ requestTimelineZoom(150);
+ vi.advanceTimersToNextFrame();
+ let shownAfterDrop: boolean | null = null;
+ const unsubscribe = subscribeTimelineZoomPreview(() => {
+ shownAfterDrop = isTimelineZoomPreviewing();
+ });
+ cancelTimelineZoom();
+ unsubscribe();
+ expect(shownAfterDrop).toBe(false);
+ });
+
+ it("drops a pending zoom when cancelled, as Fit does", () => {
+ const { row } = viewport();
+ requestTimelineZoom(150);
+ vi.advanceTimersToNextFrame();
+ cancelTimelineZoom();
+ vi.advanceTimersByTime(300);
+ expect(usePlayerStore.getState().timelinePps).toBe(10);
+ expect(row.style.transform).toBe("");
+ });
+
+ it("lays the zoom out before the timeline counts as at rest", () => {
+ viewport();
+ let ppsAtRest = 0;
+ const unsubscribe = subscribeTimelineMotion(() => {
+ if (!isTimelineMoving()) ppsAtRest = usePlayerStore.getState().timelinePps;
+ });
+ requestTimelineZoom(150);
+ vi.advanceTimersToNextFrame();
+ vi.advanceTimersByTime(200);
+ unsubscribe();
+ expect(ppsAtRest).toBe(15);
+ });
+
+ it("keeps a pending zoom when the timeline registers again, as a re-render does", async () => {
+ const { scroll } = viewport();
+ requestTimelineZoom(150);
+ unregisterViewport();
+ unregisterViewport = registerTimelineZoomViewport({ scroll, contentOrigin: 32 });
+ await Promise.resolve();
+ vi.advanceTimersByTime(200);
+ expect(usePlayerStore.getState().timelinePps).toBe(15);
+ });
+
+ it("keeps a newer timeline's registration when an older one unmounts", () => {
+ const unregisterOlder = registerTimelineZoomViewport({
+ scroll: document.createElement("div"),
+ contentOrigin: 32,
+ });
+ viewport();
+ unregisterOlder();
+ expect(currentTimelineRange()).not.toBeNull();
+ });
+
+ it("lays the zoom out mid-gesture once the preview has scaled too far", () => {
+ viewport();
+ requestTimelineZoom(300);
+ vi.advanceTimersToNextFrame();
+ expect(usePlayerStore.getState().timelinePps).toBe(10);
+ requestTimelineZoom(500);
+ vi.advanceTimersToNextFrame();
+ expect(usePlayerStore.getState().timelinePps).toBe(50);
+ });
+});
+
+describe("zoomTimelineToRange", () => {
+ it("fills the width with the range and puts its start at the left margin", () => {
+ viewport();
+ void zoomTimelineToRange(40, 90, { smooth: false });
+ // Laid out on the next frame, never inside the caller's own render or effect.
+ expect(usePlayerStore.getState().timelinePps).toBe(10);
+ vi.advanceTimersToNextFrame();
+ // 1080 - (32 + 24) - 24 = 1000px for 50s is 20 pps.
+ expect(usePlayerStore.getState().timelinePps).toBeCloseTo(20);
+ expect(laidOutX(40)).toBeCloseTo(56);
+ });
+
+ it("eases there over several frames and ends exactly on the range", () => {
+ viewport();
+ void zoomTimelineToRange(10, 20);
+ vi.advanceTimersToNextFrame();
+ vi.advanceTimersToNextFrame();
+ expect(currentTimelineZoomPercent()).toBeGreaterThan(100);
+ expect(currentTimelineZoomPercent()).toBeLessThan(1000);
+ for (let i = 0; i < 30; i++) vi.advanceTimersToNextFrame();
+ expect(usePlayerStore.getState().timelinePps).toBeCloseTo(100);
+ expect(laidOutX(10)).toBeCloseTo(56);
+ });
+
+ it("stops easing when a person zooms during it, and says it was cancelled", async () => {
+ viewport();
+ const result = zoomTimelineToRange(10, 20);
+ vi.advanceTimersToNextFrame();
+ vi.advanceTimersToNextFrame();
+ requestTimelineZoom(150);
+ for (let i = 0; i < 30; i++) vi.advanceTimersToNextFrame();
+ expect(usePlayerStore.getState().manualZoomPercent).toBe(150);
+ await expect(result).resolves.toBe("cancelled");
+ });
+
+ it("resolves done once the range is laid out, without counting as a person's zoom", async () => {
+ const { row } = viewport();
+ let settled: string | null = null;
+ void zoomTimelineToRange(10, 20).then((r) => (settled = r));
+ for (let i = 0; i < 30 && settled === null; i++) {
+ vi.advanceTimersToNextFrame();
+ await Promise.resolve();
+ }
+ expect(settled).toBe("done");
+ expect(usePlayerStore.getState().timelinePps).toBeCloseTo(100);
+ expect(usePlayerStore.getState().userZoomCount).toBe(0);
+ expect(row.style.transform).toBe("");
+ });
+
+ it("leaves a newer zoom alone when an older one's signal aborts", async () => {
+ viewport();
+ const abort = new AbortController();
+ const older = zoomTimelineToRange(10, 20, { signal: abort.signal });
+ const newer = zoomTimelineToRange(30, 40);
+ abort.abort();
+ for (let i = 0; i < 30; i++) vi.advanceTimersToNextFrame();
+ await expect(older).resolves.toBe("cancelled");
+ await expect(newer).resolves.toBe("done");
+ });
+
+ it("cancels when the caller aborts", async () => {
+ viewport();
+ const abort = new AbortController();
+ const result = zoomTimelineToRange(10, 20, { signal: abort.signal });
+ vi.advanceTimersToNextFrame();
+ abort.abort();
+ await expect(result).resolves.toBe("cancelled");
+ });
+});
+
+describe("currentTimelineRange", () => {
+ it("reads back the range zoomTimelineToRange filled", () => {
+ viewport();
+ void zoomTimelineToRange(40, 90, { smooth: false });
+ vi.advanceTimersToNextFrame();
+ const range = currentTimelineRange()!;
+ expect(range.start).toBeCloseTo(40);
+ expect(range.end).toBeCloseTo(90);
+ });
+
+ it("reads the range a gesture shows before it is laid out", () => {
+ viewport();
+ requestTimelineZoom(150, { time: 0, x: 32 });
+ const range = currentTimelineRange()!;
+ // 1000px between the margins at 15 px/s, from 24px in.
+ expect(range.start).toBeCloseTo(24 / 15);
+ expect(range.end - range.start).toBeCloseTo(1000 / 15);
+ });
+
+ it("is null with no timeline mounted", () => {
+ expect(currentTimelineRange()).toBeNull();
+ });
+});
+
+describe("zoomTimelineStep", () => {
+ const run = () => {
+ for (let i = 0; i < 30; i++) vi.advanceTimersToNextFrame();
+ };
+
+ it("counts as a person's zoom", () => {
+ viewport();
+ zoomTimelineStep("in");
+ run();
+ expect(usePlayerStore.getState().userZoomCount).toBeGreaterThan(0);
+ });
+
+ it("doubles the scale and keeps an on-screen playhead where it is", () => {
+ usePlayerStore.setState({ currentTime: 40 });
+ viewport();
+ // At 10 pps the playhead sits at 32 + 400 = 432px.
+ zoomTimelineStep("in");
+ run();
+ expect(usePlayerStore.getState().timelinePps).toBeCloseTo(20);
+ expect(laidOutX(40)).toBeCloseTo(432);
+ });
+
+ it("lays a zoom-out step out once, at its start, then eases by scaling", () => {
+ usePlayerStore.setState({
+ currentTime: 110,
+ duration: 1000,
+ zoomMode: "manual",
+ manualZoomPercent: 400,
+ timelinePps: 40,
+ });
+ // 100..126 s on screen at 40 px/s, the playhead at 110 s among it.
+ const { row } = viewport(4000);
+ const laidOut: number[] = [];
+ const unsubscribe = usePlayerStore.subscribe((s, prev) => {
+ if (s.timelinePps !== prev.timelinePps) laidOut.push(s.timelinePps);
+ });
+ zoomTimelineStep("out");
+ // Laid out in the first frame, never inside the caller (a host's effect, a click).
+ expect(laidOut).toEqual([]);
+ vi.advanceTimersToNextFrame();
+ expect(laidOut).toEqual([20]);
+ // Near the old view, drawn in the first frame by scaling the new layout up.
+ expect(Number(/scaleX\(([\d.]+)\)/.exec(row.style.transform)?.[1])).toBeGreaterThan(1.5);
+ run();
+ unsubscribe();
+ expect(laidOut).toEqual([20]);
+ // Counted once as the person's zoom: the end of the ease writes nothing more.
+ expect(usePlayerStore.getState().userZoomCount).toBe(1);
+ });
+
+ it("eases a zoom-out that pans away without laying its target out first", () => {
+ // 100..126 s on screen at 40 px/s; the playhead at 0 s is off screen, so the new view
+ // (centred on it) does not hold the old one.
+ usePlayerStore.setState({
+ duration: 1000,
+ zoomMode: "manual",
+ manualZoomPercent: 400,
+ timelinePps: 40,
+ });
+ viewport(4000);
+ const laidOut: number[] = [];
+ const unsubscribe = usePlayerStore.subscribe((s, prev) => {
+ if (s.timelinePps !== prev.timelinePps) laidOut.push(s.timelinePps);
+ });
+ zoomTimelineStep("out");
+ vi.advanceTimersToNextFrame();
+ unsubscribe();
+ expect(laidOut[0]).not.toBe(20);
+ });
+
+ it("centres an off-screen playhead", () => {
+ usePlayerStore.setState({
+ currentTime: 60,
+ zoomMode: "manual",
+ manualZoomPercent: 400,
+ timelinePps: 40,
+ });
+ // 0..26.2 s on screen at 40 px/s.
+ viewport();
+ zoomTimelineStep("in");
+ run();
+ // The range's middle, 56 + 1000 / 2, is the playhead.
+ expect(laidOutX(60)).toBeCloseTo(556);
+ });
+});
diff --git a/packages/studio/src/player/components/timelineZoomInput.ts b/packages/studio/src/player/components/timelineZoomInput.ts
new file mode 100644
index 0000000000..a2e82866f0
--- /dev/null
+++ b/packages/studio/src/player/components/timelineZoomInput.ts
@@ -0,0 +1,456 @@
+import { useSyncExternalStore } from "react";
+import { flushSync } from "react-dom";
+import type { TimelineTimeRange } from "../lib/timelineClipIndex";
+import { usePlayerStore } from "../store/playerStore";
+import { markTimelineMotion, TIMELINE_REST_MS } from "./timelineMotion";
+import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
+import {
+ clampTimelineZoomPercent,
+ getNextTimelineZoomPercent,
+ getTimelinePixelsPerSecond,
+ getTimelineZoomPercent,
+} from "./timelineZoom";
+
+/** Where a zoom holds its place: `time` stays `x` px from the viewport's left edge. */
+export interface TimelineZoomAnchor {
+ time: number;
+ x: number;
+}
+
+/** The mounted timeline's scroll viewport, which every zoom measures and previews against. */
+export interface TimelineZoomViewport {
+ scroll: HTMLDivElement;
+ contentOrigin: number;
+}
+
+/** How an eased zoom ended: it reached its range, or a person's zoom or the caller stopped it. */
+export type TimelineZoomResult = "done" | "cancelled";
+
+/**
+ * A zoom drawn by scaling what is already laid out, on the compositor, until it is committed.
+ * `shift` is the scrollLeft minus the scrollLeft the zoom will have: the translate that places it.
+ */
+interface ZoomPreview {
+ percent: number;
+ pps: number;
+ shift: number;
+ basePps: number;
+ /** The times laid out (clips mounted, ruler drawn) when it began; past them it shows gaps. */
+ drawn: TimelineTimeRange;
+ byPerson: boolean;
+}
+
+const RANGE_MARGIN_PX = 24;
+const SMOOTH_ZOOM_MS = 220;
+/** Past this the scaled-up preview turns soft. */
+const MAX_PREVIEW_SCALE = 4;
+/** Rounding at a drawn edge (whole-pixel content width, the fit track's 2px) is not a gap. */
+const EDGE_SLACK_PX = 2;
+const SCALED = "[data-timeline-zoom-scale]";
+
+let viewport: TimelineZoomViewport | null = null;
+/** While a preview shows, scales rows and strips React mounts into the timeline before they paint. */
+let mounts: MutationObserver | null = null;
+let preview: ZoomPreview | null = null;
+let frame = 0;
+let restTimer: ReturnType<typeof setTimeout> | null = null;
+let anchorForCommit: TimelineZoomAnchor | null = null;
+let animation = 0;
+let easingTo: number | null = null;
+let resolveEase: ((result: TimelineZoomResult) => void) | null = null;
+const previewListeners = new Set<() => void>();
+
+export function currentTimelineZoomPercent(): number {
+ if (preview) return preview.percent;
+ const s = usePlayerStore.getState();
+ return getTimelineZoomPercent(s.zoomMode, s.manualZoomPercent, s.timelineFitPps);
+}
+
+/** The scale the timeline shows and the scrollLeft that scale would have. */
+function shown(scroll: HTMLDivElement): { pps: number; left: number } {
+ if (preview) return { pps: preview.pps, left: scroll.scrollLeft - preview.shift };
+ return { pps: usePlayerStore.getState().timelinePps, left: scroll.scrollLeft };
+}
+
+/** The time under `x` px from the timeline viewport's left edge, as it is drawn now. */
+export function timelineTimeAtX(x: number): number | null {
+ if (!viewport) return null;
+ const { pps, left } = shown(viewport.scroll);
+ return pps > 0 ? (left + x - viewport.contentOrigin) / pps : null;
+}
+
+/** The scale and time-zero position to place something at a time by, while a zoom is previewed. */
+export function timelineZoomMapping(pps: number, contentOrigin: number) {
+ return preview
+ ? { pps: preview.pps, contentOrigin: contentOrigin + preview.shift }
+ : { pps, contentOrigin };
+}
+
+/** Whether a zoom is drawn scaled right now, so boxes read off the page are scaled too. */
+export const isTimelineZoomPreviewing = (): boolean => preview !== null;
+
+/** Called each frame a zoom preview moves, and once when it is laid out or dropped. */
+export function subscribeTimelineZoomPreview(listener: () => void): () => void {
+ previewListeners.add(listener);
+ return () => previewListeners.delete(listener);
+}
+
+const subscribeShownZoom = (listener: () => void) => {
+ const unsubscribePreview = subscribeTimelineZoomPreview(listener);
+ const unsubscribeStore = usePlayerStore.subscribe(listener);
+ return () => {
+ unsubscribePreview();
+ unsubscribeStore();
+ };
+};
+
+/** The zoom percent the timeline shows, kept current through a preview. */
+export function useShownTimelineZoomPercent(): number {
+ return useSyncExternalStore(subscribeShownZoom, currentTimelineZoomPercent);
+}
+
+function writeZoom(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
+ anchorForCommit = anchor;
+ usePlayerStore.setState((s) => {
+ const clamped = clampTimelineZoomPercent(percent, s.timelineFitPps);
+ return {
+ zoomMode: "manual",
+ manualZoomPercent: clamped,
+ // Only a person's zoom counts: the timeline and its host read it as the person taking over.
+ userZoomCount: s.userZoomCount + (byPerson ? 1 : 0),
+ timelinePps: getTimelinePixelsPerSecond(s.timelineFitPps, "manual", clamped),
+ };
+ });
+}
+
+const emitPreview = () => previewListeners.forEach((listener) => listener());
+
+/** Stops the pending preview frame, rest timer and mount watch. */
+function cancelPending() {
+ mounts?.disconnect();
+ mounts = null;
+ if (restTimer) clearTimeout(restTimer);
+ restTimer = null;
+ cancelAnimationFrame(frame);
+ frame = 0;
+}
+
+function clearScaled(scroll: HTMLElement) {
+ scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
+ el.style.transform = "";
+ el.style.transformOrigin = "";
+ el.style.willChange = "";
+ });
+}
+
+/** Whether the preview shows time outside what was mounted, or is scaled up too far. */
+function previewNeedsLayout(p: ZoomPreview, scroll: HTMLDivElement, contentOrigin: number) {
+ if (p.pps / p.basePps > MAX_PREVIEW_SCALE) return true;
+ const left = scroll.scrollLeft - p.shift;
+ const start = left / p.pps;
+ const end = (left + scroll.clientWidth - contentOrigin) / p.pps;
+ const slack = EDGE_SLACK_PX / p.pps;
+ return start < p.drawn.start - slack || end > p.drawn.end + slack;
+}
+
+/** The times laid out now: the render window clips, ruler ticks and beat lines are drawn in. */
+function drawnRange(scroll: HTMLDivElement, pps: number, contentOrigin: number): TimelineTimeRange {
+ const contentEnd = (scroll.scrollWidth - contentOrigin) / pps;
+ return getTimelineRenderTimeRange(scroll, pps, contentOrigin, contentEnd);
+}
+
+function scalePreview(scroll: HTMLElement) {
+ if (!preview) return;
+ const transform = `translateX(${preview.shift}px) scaleX(${preview.pps / preview.basePps})`;
+ scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
+ // The attribute's value is where time zero sits in the element, when not at its left edge.
+ el.style.transformOrigin = `${el.dataset.timelineZoomScale || 0}px 0`;
+ el.style.willChange = "transform";
+ el.style.transform = transform;
+ });
+}
+
+const holdsScaled = (node: Node) =>
+ node instanceof Element && (node.matches(SCALED) || node.querySelector(SCALED) !== null);
+
+function watchMounts(scroll: HTMLElement): MutationObserver {
+ const observer = new MutationObserver((records) => {
+ if (records.some((record) => [...record.addedNodes].some(holdsScaled))) scalePreview(scroll);
+ });
+ observer.observe(scroll, { childList: true, subtree: true });
+ return observer;
+}
+
+function drawPreview() {
+ cancelAnimationFrame(frame);
+ frame = 0;
+ const view = viewport;
+ if (!preview || !view) return;
+ if (previewNeedsLayout(preview, view.scroll, view.contentOrigin)) {
+ commitPreview();
+ return;
+ }
+ scalePreview(view.scroll);
+ mounts ??= watchMounts(view.scroll);
+ emitPreview();
+}
+
+/** Lays the previewed zoom out for real and drops the scaling in the same frame. */
+function commitPreview() {
+ cancelPending();
+ const view = viewport;
+ const done = preview;
+ if (!view || !done) return;
+ const left = view.scroll.scrollLeft - done.shift;
+ // Ending at the scale already laid out (an eased zoom-out) needs a scroll, not a layout.
+ if (done.pps !== done.basePps) {
+ flushSync(() =>
+ writeZoom(done.percent, { time: left / done.pps, x: view.contentOrigin }, done.byPerson),
+ );
+ }
+ preview = null;
+ if (Math.abs(view.scroll.scrollLeft - left) >= 0.5) view.scroll.scrollLeft = left;
+ clearScaled(view.scroll);
+ emitPreview();
+}
+
+/** The playhead's place if on screen, else the middle with the playhead brought to it. */
+function defaultAnchor(view: TimelineZoomViewport, pps: number, left: number): TimelineZoomAnchor {
+ const { currentTime } = usePlayerStore.getState();
+ const x = view.contentOrigin + currentTime * pps - left;
+ const onScreen = x >= view.contentOrigin && x <= view.scroll.clientWidth;
+ return {
+ time: currentTime,
+ x: onScreen ? x : (view.contentOrigin + view.scroll.clientWidth) / 2,
+ };
+}
+
+function request(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
+ const view = viewport;
+ const fitPps = usePlayerStore.getState().timelineFitPps;
+ if (!view || !(fitPps > 0)) {
+ writeZoom(percent, anchor, byPerson);
+ return;
+ }
+ const clamped = clampTimelineZoomPercent(percent, fitPps);
+ const pps = getTimelinePixelsPerSecond(fitPps, "manual", clamped);
+ const { scroll, contentOrigin } = view;
+ const now = shown(scroll);
+ const at = anchor ?? defaultAnchor(view, now.pps, now.left);
+ preview ??= {
+ percent: clamped,
+ pps,
+ shift: 0,
+ basePps: now.pps,
+ drawn: drawnRange(scroll, now.pps, contentOrigin),
+ byPerson,
+ };
+ // The content's width at this scale: the fit track (getTimelineFitPps), never narrower.
+ const fitTrack = scroll.clientWidth - contentOrigin - 2;
+ const width = contentOrigin + fitTrack * Math.max(1, pps / fitPps);
+ const maxLeft = Math.max(0, width - scroll.clientWidth);
+ const left = Math.max(0, Math.min(maxLeft, at.time * pps + contentOrigin - at.x));
+ preview.percent = clamped;
+ preview.pps = pps;
+ preview.shift = scroll.scrollLeft - left;
+ preview.byPerson ||= byPerson;
+ if (!frame) frame = requestAnimationFrame(drawPreview);
+ if (restTimer) clearTimeout(restTimer);
+ restTimer = setTimeout(commitPreview, TIMELINE_REST_MS);
+ // After the commit timer of the same delay, so the zoom is laid out before the timeline rests.
+ markTimelineMotion();
+}
+
+/** A person's zoom input: previewed each frame, laid out once it rests. */
+export function requestTimelineZoom(percent: number, anchor: TimelineZoomAnchor | null = null) {
+ stopEase();
+ request(percent, anchor, true);
+}
+
+/** Lays out a pending zoom now, so a press meets the real layout. */
+export function settleTimelineZoom(): void {
+ if (preview) commitPreview();
+}
+
+/** After a scroll: scales what it mounted, or lays the zoom out if it shows past what is drawn. */
+export function redrawTimelineZoomPreview(): void {
+ if (preview && !frame) frame = requestAnimationFrame(drawPreview);
+}
+
+/** Drops any pending or easing zoom without laying it out, as Fit does. */
+export function cancelTimelineZoom(): void {
+ stopEase();
+ dropPreview();
+}
+
+function dropPreview() {
+ cancelPending();
+ if (!preview) return;
+ if (viewport) clearScaled(viewport.scroll);
+ preview = null;
+ emitPreview();
+}
+
+function stopEase(result: TimelineZoomResult = "cancelled") {
+ cancelAnimationFrame(animation);
+ animation = 0;
+ easingTo = null;
+ const done = resolveEase;
+ resolveEase = null;
+ done?.(result);
+}
+
+/** The anchor of the zoom being committed; read once by the timeline as it lays the zoom out. */
+export function takeTimelineZoomAnchor(): TimelineZoomAnchor | null {
+ const anchor = anchorForCommit;
+ anchorForCommit = null;
+ return anchor;
+}
+
+export function registerTimelineZoomViewport(next: TimelineZoomViewport): () => void {
+ viewport = next;
+ return () => {
+ // Another timeline mounted since keeps its registration.
+ if (viewport !== next) return;
+ viewport = null;
+ // A re-render registers again in the same commit; only a real unmount drops the zoom.
+ queueMicrotask(() => {
+ if (!viewport) cancelTimelineZoom();
+ });
+ };
+}
+
+const reducedMotion = () =>
+ typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+/** The stretch a range zoom fills: from `x` px in, `width` px wide, inside the margins. */
+function rangeBox(view: TimelineZoomViewport): { x: number; width: number } {
+ const x = view.contentOrigin + RANGE_MARGIN_PX;
+ return { x, width: Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX) };
+}
+
+/** The seconds the timeline shows between its margins: what zoomTimelineToRange would fill. */
+export function currentTimelineRange(): { start: number; end: number } | null {
+ const view = viewport;
+ const pps = view ? shown(view.scroll).pps : 0;
+ if (!view || !(pps > 0)) return null;
+ const { x, width } = rangeBox(view);
+ const start = timelineTimeAtX(x)!;
+ return { start, end: start + width / pps };
+}
+
+/**
+ * Zooms and scrolls so `start`..`end` (seconds) fills the timeline, eased unless `smooth` is false
+ * or motion is reduced. Resolves on landing; "cancelled" on a person's zoom, abort, or a newer one.
+ */
+export function zoomTimelineToRange(
+ start: number,
+ end: number,
+ options: { smooth?: boolean; signal?: AbortSignal } = {},
+): Promise<TimelineZoomResult> {
+ return easeToRange(start, end, options, false);
+}
+
+function easeToRange(
+ start: number,
+ end: number,
+ { smooth = true, signal }: { smooth?: boolean; signal?: AbortSignal },
+ byPerson: boolean,
+): Promise<TimelineZoomResult> {
+ const view = viewport;
+ const fitPps = usePlayerStore.getState().timelineFitPps;
+ stopEase();
+ if (!view || !(end > start) || !(fitPps > 0) || signal?.aborted)
+ return Promise.resolve("cancelled");
+ let resolveThis: (result: TimelineZoomResult) => void = () => {};
+ const result = new Promise<TimelineZoomResult>((resolve) => (resolveThis = resolve));
+ resolveEase = resolveThis;
+ signal?.addEventListener("abort", () => resolveEase === resolveThis && stopEase(), {
+ once: true,
+ });
+ const { x, width } = rangeBox(view);
+ const toPercent = clampTimelineZoomPercent((width / (end - start) / fitPps) * 100, fitPps);
+ const finish = () => {
+ commitPreview();
+ stopEase("done");
+ };
+ if (!smooth || reducedMotion()) {
+ request(toPercent, { time: start, x }, byPerson);
+ // Laid out next frame, never inside a caller's render or effect.
+ animation = requestAnimationFrame(finish);
+ return result;
+ }
+ easeZoom(view, fitPps, toPercent, { time: start, x }, byPerson, finish);
+ return result;
+}
+
+/** Eases from the zoom shown now to `toPercent`, landing `to.time` at `to.x`, then `finish`es. */
+function easeZoom(
+ view: TimelineZoomViewport,
+ fitPps: number,
+ toPercent: number,
+ to: TimelineZoomAnchor,
+ byPerson: boolean,
+ finish: () => void,
+) {
+ const { time: start, x } = to;
+ const fromPercent = currentTimelineZoomPercent();
+ const from = shown(view.scroll);
+ const toPps = getTimelinePixelsPerSecond(fitPps, "manual", toPercent);
+ const fromStart = timelineTimeAtX(x)!;
+ const old = currentTimelineRange()!;
+ // The one point both views put at the same place on screen; zooming about it, in log space,
+ // moves every frame straight from the old view to the new. Equal scales are a plain scroll.
+ const shift = from.pps === toPps ? null : (start - fromStart) / (1 / from.pps - 1 / toPps);
+ const anchorAt = (k: number): TimelineZoomAnchor =>
+ shift === null
+ ? { time: fromStart + (start - fromStart) * k, x }
+ : { time: fromStart + shift / from.pps, x: x + shift };
+ // Zooming out to a view that holds the old one: lay the target out once, in the first frame,
+ // and ease by scaling it down from the old view, instead of laying out again partway.
+ const holdsOld =
+ old.start >= start && old.end <= start + (old.end - old.start) * (from.pps / toPps);
+ let layoutFirst = toPps < from.pps && from.pps / toPps <= MAX_PREVIEW_SCALE && holdsOld;
+ const began = performance.now();
+ easingTo = toPercent;
+ const step = (now: number) => {
+ if (layoutFirst) {
+ layoutFirst = false;
+ request(toPercent, to, byPerson);
+ commitPreview();
+ }
+ const t = Math.min(1, Math.max(0, (now - began) / SMOOTH_ZOOM_MS));
+ const k = 1 - (1 - t) ** 3;
+ request(fromPercent * (toPercent / fromPercent) ** k, anchorAt(k), byPerson);
+ // Drawn in this frame, not the next: the first one would otherwise paint a laid-out zoom-out bare.
+ drawPreview();
+ if (t < 1) animation = requestAnimationFrame(step);
+ else finish();
+ };
+ animation = requestAnimationFrame(step);
+}
+
+/**
+ * A zoom button: twice or half the scale, eased, keeping the playhead where it is on screen,
+ * or centring it when it is off screen.
+ */
+export function zoomTimelineStep(direction: "in" | "out"): void {
+ const fitPps = usePlayerStore.getState().timelineFitPps;
+ const nextPercent = getNextTimelineZoomPercent(
+ direction,
+ "manual",
+ easingTo ?? currentTimelineZoomPercent(),
+ fitPps,
+ );
+ const view = viewport;
+ if (!view || !(fitPps > 0)) {
+ requestTimelineZoom(nextPercent);
+ return;
+ }
+ const { x, width } = rangeBox(view);
+ const nextPps = getTimelinePixelsPerSecond(fitPps, "manual", nextPercent);
+ const now = shown(view.scroll);
+ const at = defaultAnchor(view, now.pps, now.left);
+ const start = at.time - (at.x - x) / nextPps;
+ void easeToRange(start, start + width / nextPps, {}, true);
+}
diff --git a/packages/studio/src/player/components/useTimelineGeometry.ts b/packages/studio/src/player/components/useTimelineGeometry.ts
index 19ed8d181e..ba4f1cd28c 100644
--- a/packages/studio/src/player/components/useTimelineGeometry.ts
+++ b/packages/studio/src/player/components/useTimelineGeometry.ts
@@ -77,8 +77,6 @@ export function useTimelineGeometry({
const displayDuration = pps > 0 ? displayContentWidth / pps : effectiveDuration;
const zoomModeRef = useRef(zoomMode);
zoomModeRef.current = zoomMode;
- const manualZoomPercentRef = useRef(manualZoomPercent);
- manualZoomPercentRef.current = manualZoomPercent;
fitPpsRef.current = fitPps;
// Restore the horizontal scroll offset after an edit re-derives the elements
@@ -133,6 +131,5 @@ export function useTimelineGeometry({
displayDuration,
clipStateVersion: expandedElements,
zoomModeRef,
- manualZoomPercentRef,
};
}
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
index 33dcde8973..528f3fb43a 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
+++ b/packages/studio/src/player/components/useTimelinePlayhead.test.tsx
@@ -2,7 +2,7 @@
import { act, useRef } from "react";
import { createRoot, type Root } from "react-dom/client";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
import { useTimelinePlayhead } from "./useTimelinePlayhead";
@@ -22,20 +22,16 @@ function scrollBox(scrollLeft: number) {
}
interface HarnessProps {
- pps: number;
+ /** Omitted: the scale the store publishes, as the timeline reads it. */
+ pps?: number;
scroll: HTMLDivElement;
- percent?: number;
dragging?: boolean;
zoomMode?: ZoomMode;
}
-function Harness({
- pps,
- scroll,
- percent = 100,
- dragging = false,
- zoomMode = "manual",
-}: HarnessProps) {
+function Harness({ pps: fixedPps, scroll, dragging = false, zoomMode = "manual" }: HarnessProps) {
+ const storePps = usePlayerStore((s) => s.timelinePps);
+ const pps = fixedPps ?? storePps;
const scrollRef = useRef(scroll);
const durationRef = useRef(60);
useTimelinePlayhead({
@@ -46,17 +42,13 @@ function Harness({
isDragging: { current: dragging },
currentTime: 0,
zoomMode,
- manualZoomPercent: percent,
zoomModeRef: { current: zoomMode },
- manualZoomPercentRef: { current: percent },
fitPps: pps,
fitPpsRef: { current: pps },
effectiveDuration: 60,
pps,
timelineReady: true,
elementsLength: 1,
- setZoomMode: () => {},
- setManualZoomPercent: () => {},
contentOrigin: ORIGIN,
});
return null;
@@ -115,13 +107,13 @@ describe("useTimelinePlayhead zoom anchor", () => {
usePlayerStore.setState({ currentTime: 6 });
const scroll = scrollBox(400);
const before = onScreenX(scroll, 6, 100);
- mount({ pps: 100, scroll, percent: 100 })({ pps: 200, percent: 200 }, true);
+ mount({ pps: 100, scroll })({ pps: 200 }, true);
expect(onScreenX(scroll, 6, 200)).toBeCloseTo(before);
});
it("stays at 00:00 when a zoom is set with the playhead at 0, as a zoom restored on open is", () => {
const scroll = scrollBox(0);
- mount({ pps: 100, scroll, percent: 100 })({ pps: 250, percent: 250 }, true);
+ mount({ pps: 100, scroll })({ pps: 250 }, true);
expect(scroll.scrollLeft).toBe(0);
});
@@ -137,7 +129,7 @@ describe("useTimelinePlayhead zoom anchor", () => {
it("brings an off-screen playhead into view when the toolbar zooms", () => {
usePlayerStore.setState({ currentTime: 30 });
const scroll = scrollBox(0);
- mount({ pps: 100, scroll, percent: 100 })({ pps: 200, percent: 200 }, true);
+ mount({ pps: 100, scroll })({ pps: 200 }, true);
expectVisible(scroll, 30, 200);
});
});
@@ -146,28 +138,21 @@ describe("useTimelinePlayhead zoom anchor, percent written by Studio itself", ()
it("keeps 00:00 when the window resizes after an edit pinned the zoom", () => {
usePlayerStore.setState({ currentTime: 6 });
const scroll = scrollBox(0);
- const update = mount({ pps: 100, scroll, percent: 200 });
- update({ percent: 100 });
- update({ pps: 130, percent: 100 });
+ const update = mount({ pps: 100, scroll });
+ update({});
+ update({ pps: 130 });
expect(scroll.scrollLeft).toBe(0);
});
it("leaves an off-screen playhead alone when a length change re-pins the zoom", () => {
usePlayerStore.setState({ currentTime: 30 });
const scroll = scrollBox(400);
- const update = mount({ pps: 100, scroll, percent: 150 });
- update({ pps: 90, percent: 150 });
- update({ pps: 101, percent: 168 });
+ const update = mount({ pps: 100, scroll });
+ update({ pps: 90 });
+ update({ pps: 101 });
const x = onScreenX(scroll, 30, 101);
expect(x > 800 || x < ORIGIN).toBe(true);
});
-
- it("anchors a person's zoom that lands on the percent already stored", () => {
- usePlayerStore.setState({ currentTime: 30 });
- const scroll = scrollBox(0);
- mount({ pps: 100, scroll, percent: 200 })({ pps: 200, percent: 200 }, true);
- expectVisible(scroll, 30, 200);
- });
});
describe("useTimelinePlayhead follow while paused", () => {
@@ -252,3 +237,85 @@ describe("useTimelinePlayhead follow while paused", () => {
expect(scroll.scrollLeft).toBe(0);
});
});
+
+describe("useTimelinePlayhead wheel zoom", () => {
+ beforeEach(() => {
+ vi.useFakeTimers({
+ toFake: ["requestAnimationFrame", "cancelAnimationFrame", "setTimeout", "clearTimeout"],
+ });
+ usePlayerStore.setState({
+ zoomMode: "manual",
+ manualZoomPercent: 100,
+ timelineFitPps: 100,
+ timelinePps: 100,
+ });
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ /** A wheel step 432px in, previewed for one frame. */
+ const previewWheel = (scroll: HTMLDivElement, init: WheelEventInit) =>
+ act(() => {
+ const event = new WheelEvent("wheel", { deltaY: -50, cancelable: true, ...init });
+ // happy-dom's WheelEvent drops the MouseEvent fields of its init.
+ Object.defineProperties(event, {
+ clientX: { value: 432 },
+ ctrlKey: { value: Boolean(init.ctrlKey) },
+ metaKey: { value: Boolean(init.metaKey) },
+ });
+ scroll.dispatchEvent(event);
+ vi.advanceTimersToNextFrame();
+ });
+
+ /** A wheel step, then the rest at which its zoom is laid out. */
+ const wheel = (scroll: HTMLDivElement, init: WheelEventInit) => {
+ previewWheel(scroll, init);
+ act(() => vi.advanceTimersByTime(200));
+ };
+
+ it("zooms on Cmd+wheel as on a pinch, and leaves a plain wheel to scroll", () => {
+ const scroll = scrollBox(0);
+ mount({ scroll });
+ wheel(scroll, {});
+ expect(usePlayerStore.getState().manualZoomPercent).toBe(100);
+ wheel(scroll, { metaKey: true });
+ expect(usePlayerStore.getState().manualZoomPercent).toBeGreaterThan(100);
+ });
+
+ it("keeps previewing a pinch through a scroll, laying it out only at rest", () => {
+ const scroll = scrollBox(0);
+ mount({ scroll });
+ previewWheel(scroll, { ctrlKey: true });
+ act(() => {
+ scroll.dispatchEvent(new Event("scroll"));
+ vi.advanceTimersToNextFrame();
+ });
+ expect(usePlayerStore.getState().timelinePps).toBe(100);
+ act(() => vi.advanceTimersByTime(200));
+ expect(usePlayerStore.getState().timelinePps).toBeGreaterThan(100);
+ });
+
+ it("lays a pending pinch out at once when the timeline is pressed", () => {
+ const scroll = scrollBox(0);
+ mount({ scroll });
+ previewWheel(scroll, { ctrlKey: true });
+ expect(usePlayerStore.getState().timelinePps).toBe(100);
+ act(() => {
+ scroll.dispatchEvent(new Event("pointerdown"));
+ });
+ expect(usePlayerStore.getState().timelinePps).toBeGreaterThan(100);
+ });
+
+ it("keeps the time under the pointer in place as a pinch lays out", () => {
+ // Zoomed to 150%, so a 300px scroll is one the content allows.
+ usePlayerStore.setState({ manualZoomPercent: 150, timelinePps: 150 });
+ const scroll = scrollBox(300);
+ mount({ scroll });
+ // Pointer 432px in: (300 + 432 - 32) / 150 s sits there before and after.
+ wheel(scroll, { ctrlKey: true });
+ const pps = usePlayerStore.getState().timelinePps;
+ expect(pps).toBeGreaterThan(150);
+ expect(ORIGIN + (700 / 150) * pps - scroll.scrollLeft).toBeCloseTo(432);
+ });
+});
diff --git a/packages/studio/src/player/components/useTimelinePlayhead.ts b/packages/studio/src/player/components/useTimelinePlayhead.ts
index 1770400112..6310fb537e 100644
--- a/packages/studio/src/player/components/useTimelinePlayhead.ts
+++ b/packages/studio/src/player/components/useTimelinePlayhead.ts
@@ -2,6 +2,17 @@ import { useRef, useCallback, useEffect, useLayoutEffect } from "react";
import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
import { useMountEffect } from "../../hooks/useMountEffect";
import { getPinchTimelineZoomPercent } from "./timelineZoom";
+import {
+ currentTimelineZoomPercent,
+ requestTimelineZoom,
+ registerTimelineZoomViewport,
+ redrawTimelineZoomPreview,
+ settleTimelineZoom,
+ subscribeTimelineZoomPreview,
+ takeTimelineZoomAnchor,
+ timelineTimeAtX,
+ timelineZoomMapping,
+} from "./timelineZoomInput";
import {
getTimelinePlaybackFollowScrollLeft,
getTimelineScrubTime,
@@ -36,17 +47,13 @@ interface UseTimelinePlayheadInput {
isDragging: React.RefObject<boolean>;
currentTime: number;
zoomMode: ZoomMode;
- manualZoomPercent: number;
zoomModeRef: React.RefObject<ZoomMode>;
- manualZoomPercentRef: React.RefObject<number>;
fitPps: number;
fitPpsRef: React.RefObject<number>;
effectiveDuration: number;
pps: number;
timelineReady: boolean;
elementsLength: number;
- setZoomMode: (mode: ZoomMode) => void;
- setManualZoomPercent: (percent: number) => void;
onSeek?: (time: number) => void;
contentOrigin: number;
}
@@ -60,28 +67,23 @@ export function useTimelinePlayhead({
currentTime,
zoomMode,
zoomModeRef,
- manualZoomPercentRef,
fitPps: _fitPps,
fitPpsRef,
effectiveDuration,
pps,
timelineReady,
elementsLength,
- setZoomMode,
- setManualZoomPercent,
onSeek,
contentOrigin,
}: UseTimelinePlayheadInput) {
const dragScrollRaf = useRef(0);
const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
- // A toolbar zoom keeps the playhead in place; a resize keeps the centre, or 00:00 at the start.
- // The pinch handler anchors at the cursor instead, so it opts out via `skipCenterAnchorRef`.
+ // A zoom keeps its anchor (pinch: pointer, else playhead) in place; a resize keeps the centre.
const previousAnchorPpsRef = useRef(pps);
const userZoomCount = usePlayerStore((s) => s.userZoomCount);
const previousZoomCountRef = useRef(userZoomCount);
const lastLiveTimeRef = useRef(usePlayerStore.getState().currentTime);
const lastSeekCountRef = useRef(liveTime.seekCount());
- const skipCenterAnchorRef = useRef(false);
const contentOriginRef = useRef(contentOrigin);
contentOriginRef.current = contentOrigin;
@@ -91,12 +93,15 @@ export function useTimelinePlayhead({
previousAnchorPpsRef.current = pps;
const prevZoomCount = previousZoomCountRef.current;
previousZoomCountRef.current = userZoomCount;
- // Always consume the skip flag, even when pps didn't change — otherwise a
- // pinch that produced no pps change (already at the zoom clamp) would strand
- // it true and the next toolbar zoom would wrongly skip center-anchoring.
- const skip = skipCenterAnchorRef.current;
- skipCenterAnchorRef.current = false;
- if (!scroll || pps === prevPps || skip) return;
+ // Consumed even when pps didn't change (at the clamp), so it never lingers for a later zoom.
+ const anchor = takeTimelineZoomAnchor();
+ if (!scroll || pps === prevPps) return;
+ if (anchor) {
+ const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
+ const left = anchor.time * pps + contentOrigin - anchor.x;
+ scroll.scrollLeft = Math.max(0, Math.min(maxScrollLeft, left));
+ return;
+ }
const zoomed = userZoomCount !== prevZoomCount;
if (!zoomed && scroll.scrollLeft < 1) return;
const time = Math.max(0, lastLiveTimeRef.current);
@@ -121,10 +126,11 @@ export function useTimelinePlayhead({
const syncPlayheadPosition = useCallback(
(time: number) => {
if (!playheadRef.current || durationRef.current <= 0) return;
+ const at = timelineZoomMapping(ppsRef.current, contentOrigin);
playheadRef.current.style.transform = getTimelinePlayheadTransform(
time,
- ppsRef.current,
- contentOrigin,
+ at.pps,
+ at.contentOrigin,
!usePlayerStore.getState().isPlaying,
);
},
@@ -158,14 +164,18 @@ export function useTimelinePlayhead({
useMountEffect(() => {
const place = (t: number, atRest: boolean) => {
if (!playheadRef.current || durationRef.current <= 0) return false;
+ const at = timelineZoomMapping(ppsRef.current, contentOriginRef.current);
playheadRef.current.style.transform = getTimelinePlayheadTransform(
t,
- ppsRef.current,
- contentOriginRef.current,
+ at.pps,
+ at.contentOrigin,
atRest,
);
return true;
};
+ const unsubPreview = subscribeTimelineZoomPreview(() =>
+ place(lastLiveTimeRef.current, !usePlayerStore.getState().isPlaying),
+ );
const dragging = () => isDragging.current || usePlayerStore.getState().beatDragging;
const unsubPlaying = usePlayerStore.subscribe((state, prev) => {
if (prev.isPlaying && !state.isPlaying) place(lastLiveTimeRef.current, true);
@@ -177,7 +187,8 @@ export function useTimelinePlayhead({
lastLiveTimeRef.current = t;
const playing = usePlayerStore.getState().isPlaying;
if (!place(t, !playing)) return;
- const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
+ const at = timelineZoomMapping(ppsRef.current, contentOriginRef.current);
+ const playheadX = at.contentOrigin + Math.max(0, t) * at.pps;
const scroll = scrollRef.current;
// Paused, only a seek scrolls: a reload's republish, frame-rounded, must not undo a person's scroll.
if (!scroll || dragging() || zoomModeRef.current === "fit" || (!playing && !sought)) return;
@@ -197,6 +208,7 @@ export function useTimelinePlayhead({
return () => {
unsub();
unsubPlaying();
+ unsubPreview();
};
});
@@ -237,62 +249,44 @@ export function useTimelinePlayhead({
[scrollRef, isDragging, zoomModeRef, seekFromX],
);
+ // Trackpad pinch arrives as ctrl+wheel; Cmd+wheel zooms too, as Mac editors do.
const handlePinchWheel = useCallback(
(e: WheelEvent) => {
- if (!e.ctrlKey) return;
+ if (!e.ctrlKey && !e.metaKey) return;
const scroll = scrollRef.current;
if (!scroll || durationRef.current <= 0 || fitPpsRef.current <= 0 || ppsRef.current <= 0)
return;
e.preventDefault();
e.stopPropagation();
- const rect = scroll.getBoundingClientRect();
- const nextZoomPercent = getPinchTimelineZoomPercent(
- e.deltaY,
- zoomModeRef.current,
- manualZoomPercentRef.current,
- fitPpsRef.current,
+ const x = e.clientX - scroll.getBoundingClientRect().left;
+ requestTimelineZoom(
+ getPinchTimelineZoomPercent(
+ e.deltaY,
+ "manual",
+ currentTimelineZoomPercent(),
+ fitPpsRef.current,
+ ),
+ { time: Math.max(0, timelineTimeAtX(x) ?? 0), x },
);
- if (nextZoomPercent === manualZoomPercentRef.current && zoomModeRef.current === "manual")
- return;
- const nextPps = fitPpsRef.current * (nextZoomPercent / 100);
- const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
- pointerX: e.clientX - rect.left,
- currentScrollLeft: scroll.scrollLeft,
- contentOrigin,
- currentPixelsPerSecond: ppsRef.current,
- nextPixelsPerSecond: nextPps,
- duration: durationRef.current,
- });
- // Pinch anchors at the cursor (below), so skip the center-anchor effect.
- skipCenterAnchorRef.current = true;
- setZoomMode("manual");
- setManualZoomPercent(nextZoomPercent);
- requestAnimationFrame(() => {
- const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
- scroll.scrollLeft = Math.min(maxScrollLeft, nextScrollLeft);
- });
},
- [
- scrollRef,
- durationRef,
- fitPpsRef,
- ppsRef,
- zoomModeRef,
- manualZoomPercentRef,
- setManualZoomPercent,
- setZoomMode,
- contentOrigin,
- ],
+ [scrollRef, durationRef, fitPpsRef, ppsRef],
);
useEffect(() => {
const scroll = scrollRef.current;
if (!scroll) return;
scroll.addEventListener("wheel", handlePinchWheel, { passive: false, capture: true });
+ // A press meets the zoom it sees, not the one still waiting to be laid out.
+ scroll.addEventListener("pointerdown", settleTimelineZoom, { capture: true });
+ scroll.addEventListener("scroll", redrawTimelineZoomPreview, { passive: true });
+ const unregisterZoomViewport = registerTimelineZoomViewport({ scroll, contentOrigin });
return () => {
scroll.removeEventListener("wheel", handlePinchWheel, { capture: true });
+ scroll.removeEventListener("pointerdown", settleTimelineZoom, { capture: true });
+ scroll.removeEventListener("scroll", redrawTimelineZoomPreview);
+ unregisterZoomViewport();
};
- }, [handlePinchWheel, scrollRef, timelineReady, elementsLength]);
+ }, [handlePinchWheel, scrollRef, timelineReady, elementsLength, contentOrigin]);
return { seekFromX, autoScrollDuringDrag, dragScrollRaf };
}
diff --git a/packages/studio/src/player/components/useTimelineProviderState.tsx b/packages/studio/src/player/components/useTimelineProviderState.tsx
index 5bef3ac338..96c441381a 100644
--- a/packages/studio/src/player/components/useTimelineProviderState.tsx
+++ b/packages/studio/src/player/components/useTimelineProviderState.tsx
@@ -131,7 +131,7 @@ export function useTimelineProviderState({
const timelineSessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
const sessionEpoch = sessionEpochProp ?? timelineSessionEpoch;
const setFocusedEaseSegment = usePlayerStore((s) => s.setFocusedEaseSegment);
- const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();
+ const { zoomMode, manualZoomPercent } = useTimelineZoom();
const playheadRef = useRef<HTMLDivElement>(null);
const containerRef = useRef<HTMLDivElement>(null);
const scrollRef = useRef<HTMLDivElement>(null);
@@ -258,22 +258,21 @@ export function useTimelineProviderState({
timelineElements.length,
displayLayout.totalH,
]);
- const { pps, fitPps, displayContentWidth, displayDuration, zoomModeRef, manualZoomPercentRef } =
- useTimelineGeometry({
- viewportWidth: viewport.clientWidth,
- effectiveDuration,
- zoomMode,
- manualZoomPercent,
- ppsRef,
- fitPpsRef,
- draggedClip,
- resizingClip,
- expandedElements: timelineElements,
- isDragging,
- scrollRef,
- lastScrollLeftRef,
- contentOrigin,
- });
+ const { pps, fitPps, displayContentWidth, displayDuration, zoomModeRef } = useTimelineGeometry({
+ viewportWidth: viewport.clientWidth,
+ effectiveDuration,
+ zoomMode,
+ manualZoomPercent,
+ ppsRef,
+ fitPpsRef,
+ draggedClip,
+ resizingClip,
+ expandedElements: timelineElements,
+ isDragging,
+ scrollRef,
+ lastScrollLeftRef,
+ contentOrigin,
+ });
const timelineFocus = useTimelineLogicalFocus({
scrollRef,
tracks,
@@ -342,17 +341,13 @@ export function useTimelineProviderState({
isDragging,
currentTime,
zoomMode,
- manualZoomPercent,
zoomModeRef,
- manualZoomPercentRef,
fitPps,
fitPpsRef,
effectiveDuration,
pps,
timelineReady,
elementsLength: timelineElements.length,
- setZoomMode,
- setManualZoomPercent,
onSeek,
contentOrigin,
});
diff --git a/packages/studio/src/player/components/useTimelineZoom.ts b/packages/studio/src/player/components/useTimelineZoom.ts
index f452e5af9f..2a35d99661 100644
--- a/packages/studio/src/player/components/useTimelineZoom.ts
+++ b/packages/studio/src/player/components/useTimelineZoom.ts
@@ -1,6 +1,6 @@
// fallow-ignore-file dead-code
-import { useCallback } from "react";
import { usePlayerStore, type ZoomMode } from "../store/playerStore";
+import { cancelTimelineZoom, requestTimelineZoom } from "./timelineZoomInput";
export interface TimelineZoomState {
zoomMode: ZoomMode;
@@ -9,18 +9,13 @@ export interface TimelineZoomState {
setManualZoomPercent: (percent: number) => void;
}
-/** Shared zoom-related store selectors used by Timeline and TimelineToolbar. */
export function useTimelineZoom(): TimelineZoomState {
const zoomMode = usePlayerStore((s) => s.zoomMode);
const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
- const setZoomMode = usePlayerStore((s) => s.setZoomMode);
- const setStorePercent = usePlayerStore((s) => s.setManualZoomPercent);
- const setManualZoomPercent = useCallback(
- (percent: number) => {
- usePlayerStore.setState((s) => ({ userZoomCount: s.userZoomCount + 1 }));
- setStorePercent(percent);
- },
- [setStorePercent],
- );
- return { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent };
+ const setStoreZoomMode = usePlayerStore((s) => s.setZoomMode);
+ const setZoomMode = (mode: ZoomMode) => {
+ cancelTimelineZoom();
+ setStoreZoomMode(mode);
+ };
+ return { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent: requestTimelineZoom };
}
diff --git a/packages/studio/src/player/lib/timelineViewportBudgets.test.ts b/packages/studio/src/player/lib/timelineViewportBudgets.test.ts
index 3c8a56496c..9972db441c 100644
--- a/packages/studio/src/player/lib/timelineViewportBudgets.test.ts
+++ b/packages/studio/src/player/lib/timelineViewportBudgets.test.ts
@@ -9,7 +9,7 @@ describe("timeline viewport budgets", () => {
expect(TIMELINE_VIEWPORT_BUDGETS).toMatchObject({
directScrollSafetyPx: 8_000_000,
rowOverscanPerSide: 2,
- timeOverscanViewportRatio: 0.25,
+ timeOverscanViewportRatio: 0.5,
maxMountedRows: 64,
maxMountedClipRoots: 512,
maxMountedClipRootsPerRow: 128,
diff --git a/packages/studio/src/player/lib/timelineViewportBudgets.ts b/packages/studio/src/player/lib/timelineViewportBudgets.ts
index 4e4c2e3e1c..d51ac9baec 100644
--- a/packages/studio/src/player/lib/timelineViewportBudgets.ts
+++ b/packages/studio/src/player/lib/timelineViewportBudgets.ts
@@ -61,7 +61,7 @@ export const MAX_VISIBLE_THUMBNAIL_FRAMES = Math.ceil(3840 / (66 * (16 / 9))); /
export const TIMELINE_VIEWPORT_BUDGETS: Readonly<TimelineViewportBudgets> = Object.freeze({
directScrollSafetyPx: 8_000_000,
rowOverscanPerSide: 2,
- timeOverscanViewportRatio: 0.25,
+ timeOverscanViewportRatio: 0.5,
maxMountedRows: 64,
maxMountedClipRoots: 512,
maxMountedClipRootsPerRow: 128,