@hyperframes/studio 0.8.139 → 0.8.140

package/src/player/components/AudioWaveform.tsx

@@ -1,7 +1,7 @@
-import { memo, useCallback, useContext, useEffect, useMemo, useRef } from "react";
+import { memo, useCallback, useContext, useEffect, useMemo, useRef, useState } 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);
@@ -157,6 +158,32 @@ async function decodeWaveformPeaks(url: string, signal: AbortSignal): Promise<nu
 }
 
 /** Bounded waveform subscriber; cache, cancellation and dedupe live in one scheduler. */
+const NEAR_SCREEN: IntersectionObserverInit & { scrollMargin: string } = {
+  rootMargin: "50% 100%",
+  scrollMargin: "50% 100%",
+};
+const nearScreenListeners = new Map<Element, (near: boolean) => void>();
+let nearScreen: IntersectionObserver | null = null;
+
+function useNearScreen(element: Element | null): boolean {
+  const [near, setNear] = useState(() => typeof IntersectionObserver === "undefined");
+  useEffect(() => {
+    if (!element || typeof IntersectionObserver === "undefined") return;
+    nearScreen ??= new IntersectionObserver(
+      (entries) =>
+        entries.forEach((entry) => nearScreenListeners.get(entry.target)?.(entry.isIntersecting)),
+      NEAR_SCREEN,
+    );
+    nearScreenListeners.set(element, setNear);
+    nearScreen.observe(element);
+    return () => {
+      nearScreenListeners.delete(element);
+      nearScreen?.unobserve(element);
+    };
+  }, [element]);
+  return near;
+}
+
 export const AudioWaveform = memo(function AudioWaveform({
   audioUrl,
   waveformUrl,
@@ -170,9 +197,8 @@ export const AudioWaveform = memo(function AudioWaveform({
   muted = false,
   labelInset = 16,
 }: AudioWaveformProps) {
-  const rootRef = useRef<HTMLDivElement | null>(null);
+  const [root, setRoot] = useState<HTMLDivElement | null>(null);
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
-  const observerRef = useRef<ResizeObserver | null>(null);
   const cacheKey = waveformUrl ?? audioUrl;
   const request = useMemo(
     () => ({
@@ -197,23 +223,31 @@ 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]);
+  const near = useNearScreen(root);
+  useEffect(() => {
+    if (near) draw();
+  }, [draw, near, strip.width, strip.height]);
 
   useEffect(() => {
     const root = document.documentElement;
@@ -225,23 +259,45 @@ export const AudioWaveform = memo(function AudioWaveform({
     return () => observer.disconnect();
   }, [draw]);
 
-  useMountEffect(() => () => observerRef.current?.disconnect());
-
   useEffect(() => {
-    const clip = rootRef.current?.closest(".timeline-clip");
+    const clip = root?.closest(".timeline-clip");
     if (!(clip instanceof HTMLElement)) return;
     if (muted) clip.setAttribute("data-audio-muted", "true");
     else clip.removeAttribute("data-audio-muted");
     return () => clip.removeAttribute("data-audio-muted");
-  }, [muted]);
+  }, [muted, root]);
 
   return (
-    <div ref={rootRef} className="absolute inset-0">
-      <div className="absolute inset-0 overflow-hidden" style={{ zIndex: WAVEFORM_LAYER_Z }}>
+    <div ref={setRoot} className="absolute inset-0">
+      <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

package/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());
+});

package/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`);

package/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:

package/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",

package/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 },

package/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.

package/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>
+  );
 }

package/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>

package/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"

package/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);