@hyperframes/studio 0.7.57 → 0.7.59

package/src/player/components/Timeline.test.ts

@@ -25,6 +25,7 @@ import {
   PLAYHEAD_HEAD_W,
   RULER_H,
   TRACK_H,
+  TRACKS_LEFT_PAD,
   getTimelineDisplayContentWidth,
   getTimelineFitPps,
 } from "./timelineLayout";
@@ -152,7 +153,8 @@ describe("Timeline provider boundary", () => {
     });
 
     const row = button.parentElement?.parentElement;
-    const trackContent = row?.children.item(1);
+    // Row children: [sticky gutter, TRACKS_LEFT_PAD spacer, time-mapped content].
+    const trackContent = row?.children.item(2);
     expect(onToggleTrackHidden).toHaveBeenCalledWith(0, false);
     expect(trackContent).toBeInstanceOf(HTMLElement);
     if (!(trackContent instanceof HTMLElement)) {
@@ -454,27 +456,27 @@ describe("shouldAutoScrollTimeline", () => {
 });
 
 describe("getTimelineFitPps (min 60s extent + fit headroom)", () => {
-  const viewport = 632; // usable width = 632 - GUTTER - 2 = 598
+  const viewport = 632; // usable width = 632 - GUTTER - TRACKS_LEFT_PAD - 2
 
   it("computes fit pps against the 60s floor for short compositions", () => {
     // A 10s comp maps 60s onto the viewport → the comp takes ~1/6 of the width.
     // (10 * 1.2 = 12s of headroom-padded content is still under the 60s floor.)
     const pps = getTimelineFitPps(viewport, 10);
-    expect(pps).toBeCloseTo((viewport - GUTTER - 2) / MIN_TIMELINE_EXTENT_S);
-    expect(10 * pps).toBeCloseTo((viewport - GUTTER - 2) / 6);
+    expect(pps).toBeCloseTo((viewport - GUTTER - TRACKS_LEFT_PAD - 2) / MIN_TIMELINE_EXTENT_S);
+    expect(10 * pps).toBeCloseTo((viewport - GUTTER - TRACKS_LEFT_PAD - 2) / 6);
   });
 
   it("fits duration * FIT_ZOOM_HEADROOM (not the bare duration) for long compositions", () => {
     expect(getTimelineFitPps(viewport, 60)).toBeCloseTo(
-      (viewport - GUTTER - 2) / (60 * FIT_ZOOM_HEADROOM),
+      (viewport - GUTTER - TRACKS_LEFT_PAD - 2) / (60 * FIT_ZOOM_HEADROOM),
     );
     expect(getTimelineFitPps(viewport, 120)).toBeCloseTo(
-      (viewport - GUTTER - 2) / (120 * FIT_ZOOM_HEADROOM),
+      (viewport - GUTTER - TRACKS_LEFT_PAD - 2) / (120 * FIT_ZOOM_HEADROOM),
     );
   });
 
   it("leaves CapCut-style trailing headroom: the comp ends at 1/1.2 of the usable width", () => {
-    const usable = viewport - GUTTER - 2;
+    const usable = viewport - GUTTER - TRACKS_LEFT_PAD - 2;
     const pps = getTimelineFitPps(viewport, 120);
     // Composition content occupies usable/1.2 px; the remaining ~17% is empty
     // droppable ruler/lane surface past the end.
@@ -484,16 +486,16 @@ describe("getTimelineFitPps (min 60s extent + fit headroom)", () => {
 
   it("falls back to 100 pps before the viewport is measured", () => {
     expect(getTimelineFitPps(0, 10)).toBe(100);
-    expect(getTimelineFitPps(GUTTER, 10)).toBe(100);
+    expect(getTimelineFitPps(GUTTER + TRACKS_LEFT_PAD, 10)).toBe(100);
     expect(getTimelineFitPps(Number.NaN, 10)).toBe(100);
   });
 
   it("uses the floor for zero/invalid durations", () => {
     expect(getTimelineFitPps(viewport, 0)).toBeCloseTo(
-      (viewport - GUTTER - 2) / MIN_TIMELINE_EXTENT_S,
+      (viewport - GUTTER - TRACKS_LEFT_PAD - 2) / MIN_TIMELINE_EXTENT_S,
     );
     expect(getTimelineFitPps(viewport, Number.NaN)).toBeCloseTo(
-      (viewport - GUTTER - 2) / MIN_TIMELINE_EXTENT_S,
+      (viewport - GUTTER - TRACKS_LEFT_PAD - 2) / MIN_TIMELINE_EXTENT_S,
     );
   });
 });
@@ -509,7 +511,7 @@ describe("getTimelineDisplayContentWidth", () => {
   it("still fills the viewport when that is larger than the 60s floor", () => {
     expect(
       getTimelineDisplayContentWidth({ trackContentWidth: 200, viewportWidth: 2000, pps: 5 }),
-    ).toBe(2000 - GUTTER - 2);
+    ).toBe(2000 - GUTTER - TRACKS_LEFT_PAD - 2);
   });
 
   it("tracks a drag ghost past every other bound (drag-to-extend)", () => {
@@ -599,20 +601,28 @@ describe("getTimelineScrollLeftForZoomAnchor", () => {
 });
 
 describe("getTimelinePlayheadLeft", () => {
-  it("offsets the wrapper by half the head width so the line CENTER = GUTTER + t*pps", () => {
+  it("offsets the wrapper by half the head width so the line CENTER = GUTTER + TRACKS_LEFT_PAD + t*pps", () => {
     // Wrapper left + PLAYHEAD_HEAD_W/2 (where the 1px line is centered) must
-    // equal GUTTER + t*pps at any zoom.
-    expect(getTimelinePlayheadLeft(4, 20) + PLAYHEAD_HEAD_W / 2).toBe(GUTTER + 4 * 20);
-    expect(getTimelinePlayheadLeft(10, 7.5) + PLAYHEAD_HEAD_W / 2).toBe(GUTTER + 75);
+    // equal GUTTER + TRACKS_LEFT_PAD + t*pps at any zoom.
+    expect(getTimelinePlayheadLeft(4, 20) + PLAYHEAD_HEAD_W / 2).toBe(
+      GUTTER + TRACKS_LEFT_PAD + 4 * 20,
+    );
+    expect(getTimelinePlayheadLeft(10, 7.5) + PLAYHEAD_HEAD_W / 2).toBe(
+      GUTTER + TRACKS_LEFT_PAD + 75,
+    );
   });
 
-  it("centers the line exactly on the gutter (the 00:00 tick) at t = 0", () => {
-    expect(getTimelinePlayheadLeft(0, 20) + PLAYHEAD_HEAD_W / 2).toBe(GUTTER);
+  it("centers the line exactly on the left pad's end (the 00:00 tick) at t = 0", () => {
+    expect(getTimelinePlayheadLeft(0, 20) + PLAYHEAD_HEAD_W / 2).toBe(GUTTER + TRACKS_LEFT_PAD);
   });
 
   it("guards invalid input", () => {
-    expect(getTimelinePlayheadLeft(Number.NaN, 20)).toBe(GUTTER - PLAYHEAD_HEAD_W / 2);
-    expect(getTimelinePlayheadLeft(4, Number.NaN)).toBe(GUTTER - PLAYHEAD_HEAD_W / 2);
+    expect(getTimelinePlayheadLeft(Number.NaN, 20)).toBe(
+      GUTTER + TRACKS_LEFT_PAD - PLAYHEAD_HEAD_W / 2,
+    );
+    expect(getTimelinePlayheadLeft(4, Number.NaN)).toBe(
+      GUTTER + TRACKS_LEFT_PAD - PLAYHEAD_HEAD_W / 2,
+    );
   });
 });
 
@@ -681,7 +691,7 @@ describe("resolveTimelineAssetDrop", () => {
           trackHeight: 72,
           trackOrder: [0, 3, 7],
         },
-        432,
+        480, // rectLeft(100) + GUTTER + TRACKS_LEFT_PAD + 3s*100pps
         // clientY updated for TRACKS_TOP_PAD=72: rectTop(200) + RULER_H(24) +
         // TRACKS_TOP_PAD(72) + TRACK_H(48) + TRACK_H/2(24) = 368 → row 1 → track 3.
         368,
@@ -702,7 +712,7 @@ describe("resolveTimelineAssetDrop", () => {
           trackHeight: 72,
           trackOrder: [0, 3, 7],
         },
-        250,
+        250 + TRACKS_LEFT_PAD,
         600,
       ),
     ).toEqual({ start: 1.18, track: 8 });

package/src/player/components/Timeline.tsx

@@ -9,7 +9,7 @@ import { defaultTimelineTheme } from "./timelineTheme";
 import { useTimelineRangeSelection } from "./useTimelineRangeSelection";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
 import { useTimelineActiveClips } from "./useTimelineActiveClips";
-import { type TrackVisualStyle, getTrackStyle } from "./timelineIcons";
+import { getTrackStyle } from "./timelineIcons";
 import { useTimelineZoom } from "./useTimelineZoom";
 import { useTimelineAssetDrop } from "./timelineDragDrop";
 import { TimelineEmptyState } from "./TimelineEmptyState";
@@ -20,15 +20,14 @@ import { TimelineOverlays } from "./TimelineOverlays";
 import { useTimelineEditPinning } from "./useTimelineEditPinning";
 import { useTimelineStackingSync } from "./useTimelineStackingSync";
 import { useTimelineGeometry } from "./useTimelineGeometry";
-import {
-  GUTTER,
-  generateTicks,
-  getTimelineCanvasHeight,
-  shouldShowTimelineShortcutHint,
-} from "./timelineLayout";
+import { useTimelineTrackDerivations } from "./useTimelineTrackDerivations";
+import { GUTTER, TRACKS_LEFT_PAD, generateTicks, getTimelineCanvasHeight } from "./timelineLayout";
+import { useTimelineScrollViewport } from "./useTimelineScrollViewport";
 import { STUDIO_PREVIEW_FPS } from "../lib/time";
 import { useResolvedTimelineEditCallbacks } from "./useResolvedTimelineEditCallbacks";
 import type { TimelineProps } from "./TimelineTypes";
+import { useTrackGapMenu } from "./useTrackGapMenu";
+import { useTimelineGapHighlights } from "./useTimelineGapHighlights";
 
 // Re-export pure utilities so existing imports from "./Timeline" still resolve.
 export {
@@ -114,106 +113,41 @@ export const Timeline = memo(function Timeline({
   const [razorGuideX, setRazorGuideX] = useState<number | null>(null);
 
   useMountEffect(() => {
-    const down = (e: KeyboardEvent) => e.key === "Shift" && setShiftHeld(true);
-    const up = (e: KeyboardEvent) => e.key === "Shift" && setShiftHeld(false);
+    const key = (e: KeyboardEvent) => e.key === "Shift" && setShiftHeld(e.type === "keydown");
     const blur = () => setShiftHeld(false);
-    window.addEventListener("keydown", down);
-    window.addEventListener("keyup", up);
+    window.addEventListener("keydown", key);
+    window.addEventListener("keyup", key);
     window.addEventListener("blur", blur);
     return () => {
-      window.removeEventListener("keydown", down);
-      window.removeEventListener("keyup", up);
+      window.removeEventListener("keydown", key);
+      window.removeEventListener("keyup", key);
       window.removeEventListener("blur", blur);
     };
   });
 
   const [showPopover, setShowPopover] = useState(false);
-  const [showShortcutHint, setShowShortcutHint] = useState(true);
   const [kfContextMenu, setKfContextMenu] = useState<KeyframeDiamondContextMenuState | null>(null);
   const [clipContextMenu, setClipContextMenu] = useState<{
     x: number;
     y: number;
     element: TimelineElement;
   } | null>(null);
-  const [viewportWidth, setViewportWidth] = useState(0);
-  const roRef = useRef<ResizeObserver | null>(null);
-  const shortcutHintRafRef = useRef(0);
-
-  const syncShortcutHintVisibility = useCallback(() => {
-    const scroll = scrollRef.current;
-    setShowShortcutHint(
-      scroll ? shouldShowTimelineShortcutHint(scroll.scrollHeight, scroll.clientHeight) : true,
-    );
-  }, []);
-
-  const scheduleShortcutHintVisibilitySync = useCallback(() => {
-    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
-    shortcutHintRafRef.current = requestAnimationFrame(() => {
-      shortcutHintRafRef.current = 0;
-      syncShortcutHintVisibility();
-    });
-  }, [syncShortcutHintVisibility]);
 
   const setContainerRef = useCallback((el: HTMLDivElement | null) => {
     containerRef.current = el;
   }, []);
 
-  // Last horizontal scroll offset, RESTORED across the post-edit iframe reload (which clamps into
-  // a scroll jump); with the pinned zoom this keeps the user parked at the same spot after edits.
+  // Last horizontal scroll offset, restored across the post-edit iframe reload (pinned zoom).
   const lastScrollLeftRef = useRef(0);
-  const setScrollRef = useCallback(
-    (el: HTMLDivElement | null) => {
-      if (roRef.current) {
-        roRef.current.disconnect();
-        roRef.current = null;
-      }
-      scrollRef.current = el;
-      if (!el) return;
-
-      const syncScrollViewport = () => {
-        setViewportWidth(el.clientWidth);
-        scheduleShortcutHintVisibilitySync();
-      };
-
-      syncScrollViewport();
-      roRef.current = new ResizeObserver(syncScrollViewport);
-      roRef.current.observe(el);
-    },
-    [scheduleShortcutHintVisibilitySync],
-  );
-
-  useMountEffect(() => () => {
-    roRef.current?.disconnect();
-    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
-  });
 
   const effectiveDuration = useMemo(() => {
     const safeDur = Number.isFinite(duration) ? duration : 0;
     if (rawElements.length === 0) return safeDur;
-    const maxEnd = Math.max(...rawElements.map((el) => el.start + el.duration));
-    const result = Math.max(safeDur, maxEnd);
+    const result = Math.max(safeDur, ...rawElements.map((el) => el.start + el.duration));
     return Number.isFinite(result) ? result : safeDur;
   }, [rawElements, duration]);
 
-  const tracks = useMemo(() => {
-    const map = new Map<number, typeof expandedElements>();
-    for (const el of expandedElements) {
-      const list = map.get(el.track) ?? [];
-      list.push(el);
-      map.set(el.track, list);
-    }
-    return Array.from(map.entries()).sort(([a], [b]) => a - b);
-  }, [expandedElements]);
-
-  const trackStyles = useMemo(() => {
-    const map = new Map<number, TrackVisualStyle>();
-    for (const [trackNum, els] of tracks) {
-      map.set(trackNum, getTrackStyle(els[0]?.tag ?? ""));
-    }
-    return map;
-  }, [tracks]);
-
-  const trackOrder = useMemo(() => tracks.map(([trackNum]) => trackNum), [tracks]);
+  const { tracks, trackStyles, trackOrder } = useTimelineTrackDerivations(expandedElements);
   const trackOrderRef = useRef(trackOrder);
   trackOrderRef.current = trackOrder;
   const expandedElementsRef = useRef(expandedElements);
@@ -222,8 +156,7 @@ export const Timeline = memo(function Timeline({
   const ppsRef = useRef(100);
   const durationRef = useRef(effectiveDuration);
   durationRef.current = effectiveDuration;
-  // Declared here (used before the fitPps derivation below) so the edit-pin
-  // wrappers can close over it; `fitPpsRef.current` is refreshed each render.
+  // Declared before the fitPps derivation so the edit-pin wrappers can close over it.
   const fitPpsRef = useRef(100);
 
   const {
@@ -252,6 +185,22 @@ export const Timeline = memo(function Timeline({
     expandedElementsRef,
   });
 
+  const {
+    gapMenuModel,
+    gapHighlight,
+    setHoveredGapAction,
+    openGapMenu,
+    dismissGapMenu,
+    closeTrackGap,
+    closeAllTrackGaps,
+  } = useTrackGapMenu({
+    tracks,
+    expandedElementsRef,
+    trackOrderRef,
+    onMoveElement: pinnedOnMoveElement,
+    onMoveElements: pinnedOnMoveElements,
+  });
+
   const {
     draggedClip,
     setDraggedClip,
@@ -293,6 +242,11 @@ export const Timeline = memo(function Timeline({
   }, [draggedClip, trackOrder]);
 
   const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
+  const { viewportWidth, showShortcutHint, setScrollRef } = useTimelineScrollViewport(scrollRef, [
+    timelineReady,
+    expandedElements.length,
+    totalH,
+  ]);
   const keyframeCache = usePlayerStore((s) => s.keyframeCache);
   const selectedKeyframes = usePlayerStore((s) => s.selectedKeyframes);
   const toggleSelectedKeyframe = usePlayerStore((s) => s.toggleSelectedKeyframe);
@@ -328,6 +282,16 @@ export const Timeline = memo(function Timeline({
     lastScrollLeftRef,
   });
 
+  const laneGapStrips = useTimelineGapHighlights({
+    gapHighlight,
+    tracks,
+    selectedElementId,
+    selectedElementIds,
+    expandedElements,
+    dragActive: draggedClip?.started === true || resizingClip != null,
+    displayDuration,
+  });
+
   const { seekFromX, autoScrollDuringDrag, dragScrollRaf } = useTimelinePlayhead({
     playheadRef,
     scrollRef,
@@ -379,8 +343,7 @@ export const Timeline = memo(function Timeline({
     trackOrderRef,
     onSelectElement,
   });
-  // Wire setRangeSelection into the stable ref consumed by useTimelineClipDrag
-  setRangeSelectionRef.current = setRangeSelection;
+  setRangeSelectionRef.current = setRangeSelection; // stable ref consumed by useTimelineClipDrag
 
   const prevSelectedRef = useRef(selectedElementRef.current);
   // eslint-disable-next-line no-restricted-syntax, react-hooks/exhaustive-deps
@@ -402,10 +365,6 @@ export const Timeline = memo(function Timeline({
   );
   const majorTickInterval = major.length >= 2 ? major[1] - major[0] : effectiveDuration;
 
-  useEffect(() => {
-    syncShortcutHintVisibility();
-  }, [syncShortcutHintVisibility, timelineReady, expandedElements.length, totalH]);
-
   const getPreviewElement = useCallback(
     (element: TimelineElement): TimelineElement => {
       if (
@@ -459,8 +418,7 @@ export const Timeline = memo(function Timeline({
         tabIndex={-1}
         className={`${zoomMode === "fit" ? "overflow-x-hidden" : "overflow-x-auto"} overflow-y-auto h-full outline-none`}
         onScroll={(e) => {
-          // Remember the live offset so it can be restored across a post-edit reload.
-          lastScrollLeftRef.current = e.currentTarget.scrollLeft;
+          lastScrollLeftRef.current = e.currentTarget.scrollLeft; // restored across post-edit reload
         }}
         onDragOver={handleAssetDragOver}
         onDragLeave={() => clearDropPreview()}
@@ -468,7 +426,8 @@ export const Timeline = memo(function Timeline({
         onPointerDown={(e) => {
           if (activeTool === "razor" && e.shiftKey && e.button === 0 && scrollRef.current) {
             const rect = scrollRef.current.getBoundingClientRect();
-            const x = e.clientX - rect.left + scrollRef.current.scrollLeft - GUTTER;
+            const x =
+              e.clientX - rect.left + scrollRef.current.scrollLeft - GUTTER - TRACKS_LEFT_PAD;
             const splitTime = Math.max(0, x / pps);
             onRazorSplitAll?.(splitTime);
             return;
@@ -489,6 +448,7 @@ export const Timeline = memo(function Timeline({
           majorTickInterval={majorTickInterval}
           rangeSelection={rangeSelection}
           marqueeRect={marqueeRect}
+          laneGapStrips={laneGapStrips}
           theme={theme}
           displayTrackOrder={displayTrackOrder}
           trackOrder={trackOrder}
@@ -560,8 +520,14 @@ export const Timeline = memo(function Timeline({
             e.preventDefault();
             setSelectedElementId(el.key ?? el.id);
             onSelectElement?.(el);
+            dismissGapMenu();
             setClipContextMenu({ x: e.clientX, y: e.clientY, element: el });
           }}
+          onContextMenuLane={(e, track, time) => {
+            if (draggedClip?.started || resizingClip) return;
+            setClipContextMenu(null);
+            openGapMenu({ x: e.clientX, y: e.clientY, track, time });
+          }}
         />
         {activeTool === "razor" && razorGuideX !== null && (
           <div
@@ -594,6 +560,11 @@ export const Timeline = memo(function Timeline({
         onSplitElement={onSplitElement}
         pinZoomBeforeEdit={pinZoomBeforeEdit}
         onDeleteElement={_onDeleteElement}
+        gapContextMenu={gapMenuModel}
+        onDismissGapContextMenu={dismissGapMenu}
+        onCloseTrackGap={closeTrackGap}
+        onCloseAllTrackGaps={closeAllTrackGaps}
+        onHoverGapAction={setHoveredGapAction}
       />
     </div>
   );

package/src/player/components/TimelineCanvas.tsx

@@ -10,6 +10,7 @@ import {
   CLIP_Y,
   TRACKS_TOP_PAD,
   TRACKS_BOTTOM_PAD,
+  TRACKS_LEFT_PAD,
   PLAYHEAD_HEAD_W,
   getTimelinePlayheadLeft,
   getTimelineRowTop,
@@ -23,6 +24,7 @@ import { TimelineClip } from "./TimelineClip";
 import { TimelineLanes, type TimelineLaneBaseProps } from "./TimelineLanes";
 import { renderClipChildren } from "./timelineClipChildren";
 import { useTimelineRevealClip } from "./useTimelineRevealClip";
+import type { TimelineLaneGapStrips } from "./useTimelineGapHighlights";
 
 interface TimelineCanvasProps extends TimelineLaneBaseProps {
   major: number[];
@@ -37,6 +39,8 @@ interface TimelineCanvasProps extends TimelineLaneBaseProps {
   /** Playhead is being actively scrubbed — fills the grab-handle head. */
   isScrubbing: boolean;
   playheadRef: React.RefObject<HTMLDivElement | null>;
+  /** Gap strips: loud on gap-menu-row hover, quiet on the selected clip's lane. */
+  laneGapStrips: TimelineLaneGapStrips[];
 }
 
 export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvasProps) {
@@ -97,7 +101,7 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
   return (
     <div
       className="relative"
-      style={{ height: props.totalH, width: GUTTER + props.trackContentWidth }}
+      style={{ height: props.totalH, width: GUTTER + TRACKS_LEFT_PAD + props.trackContentWidth }}
     >
       <TimelineRuler
         major={props.major}
@@ -131,6 +135,31 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
           new bottom track comfortably (see TRACKS_BOTTOM_PAD / getTimelineCanvasHeight). */}
       <div aria-hidden="true" style={{ height: TRACKS_BOTTOM_PAD }} />
 
+      {/* Gap strips — loud dashed fill for the gap(s) a hovered "Close gap(s)"
+          menu row would collapse; a quiet tint for every gap on the selected
+          clip's lane. Geometry mirrors the drop placeholder (row top + clip
+          inset) so strips sit exactly where a clip body would. */}
+      {props.laneGapStrips.map((strip) => {
+        const rowIndex = displayTrackOrder.indexOf(strip.track);
+        if (rowIndex < 0) return null;
+        const loud = strip.kind === "hover";
+        return strip.intervals.map((gap) => (
+          <div
+            key={`gap-${strip.kind}-${strip.track}-${gap.start}`}
+            className="pointer-events-none absolute"
+            style={{
+              top: getTimelineRowTop(rowIndex) + CLIP_Y,
+              left: GUTTER + TRACKS_LEFT_PAD + gap.start * props.pps,
+              width: Math.max((gap.end - gap.start) * props.pps, 2),
+              height: TRACK_H - CLIP_Y * 2,
+              background: loud ? "rgba(60,230,172,0.18)" : "rgba(60,230,172,0.055)",
+              borderRadius: 4,
+              zIndex: 25,
+            }}
+          />
+        ));
+      })}
+
       {/* Drop placeholder — a clip-sized slot at the exact landing spot (target
           lane + snapped start), parallel to the ghost. Hidden in insert mode. */}
       {draggedClip?.started && draggedClip.insertRow == null && draggedRowIndex >= 0 && (
@@ -138,7 +167,7 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
           className="absolute pointer-events-none"
           style={{
             top: getTimelineRowTop(draggedRowIndex) + CLIP_Y,
-            left: GUTTER + draggedClip.previewStart * props.pps,
+            left: GUTTER + TRACKS_LEFT_PAD + draggedClip.previewStart * props.pps,
             width: Math.max(draggedClip.element.duration * props.pps, 4),
             height: TRACK_H - CLIP_Y * 2,
             border: "1px solid rgba(60,230,172,0.55)",
@@ -156,7 +185,7 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
           className="absolute pointer-events-none"
           style={{
             top: getTimelineRowTop(draggedClip.insertRow) - 0.5,
-            left: GUTTER,
+            left: GUTTER + TRACKS_LEFT_PAD,
             width: props.trackContentWidth,
             height: 1,
             background: "#3CE6AC",
@@ -171,7 +200,7 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
         <div
           className="absolute pointer-events-none"
           style={{
-            left: GUTTER + draggedClip.snapTime * props.pps,
+            left: GUTTER + TRACKS_LEFT_PAD + draggedClip.snapTime * props.pps,
             top: RULER_H,
             bottom: 0,
             width: 1,
@@ -251,7 +280,9 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
           className="absolute pointer-events-none"
           style={{
             left:
-              GUTTER + Math.min(props.rangeSelection.start, props.rangeSelection.end) * props.pps,
+              GUTTER +
+              TRACKS_LEFT_PAD +
+              Math.min(props.rangeSelection.start, props.rangeSelection.end) * props.pps,
             width: Math.abs(props.rangeSelection.end - props.rangeSelection.start) * props.pps,
             top: RULER_H,
             bottom: 0,

package/src/player/components/TimelineLanes.tsx

@@ -6,7 +6,7 @@ import { TimelineClipDiamonds } from "./TimelineClipDiamonds";
 import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
 import { getTimelineEditCapabilities, resolveBlockedTimelineEditIntent } from "./timelineEditing";
 import type { TimelineTheme } from "./timelineTheme";
-import { GUTTER, TRACK_H, CLIP_Y, CLIP_HANDLE_W } from "./timelineLayout";
+import { GUTTER, TRACK_H, TRACKS_LEFT_PAD, CLIP_Y, CLIP_HANDLE_W } from "./timelineLayout";
 import {
   usePlayerStore,
   type TimelineElement,
@@ -80,6 +80,12 @@ export interface TimelineLaneBaseProps {
     toClipPercentage: number,
   ) => void;
   onContextMenuClip?: (e: React.MouseEvent, element: TimelineElement) => void;
+  /**
+   * Right-click on EMPTY lane space (not on a clip — those preventDefault
+   * before this fires — not the gutter/ruler, not below the lanes). `time` is
+   * the timeline time (seconds) under the pointer on that lane.
+   */
+  onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
   beatAnalysis?: MusicBeatAnalysis | null;
 }
 
@@ -133,6 +139,7 @@ export function TimelineLanes({
   onContextMenuKeyframe,
   onMoveKeyframe,
   onContextMenuClip,
+  onContextMenuLane,
   beatAnalysis,
   onToggleTrackHidden,
   onResizeElement,
@@ -167,21 +174,14 @@ export function TimelineLanes({
           const isTrackHidden = els.length > 0 && els.every((element) => element.hidden === true);
           const isAudioTrack = els.length > 0 && els.some(isAudioTimelineElement);
           return (
-            <div
-              key={trackNum}
-              className="relative flex"
-              style={{
-                height: TRACK_H,
-                background: rowBackground,
-                borderBottom: `1px solid ${theme.rowBorder}`,
-              }}
-            >
+            <div key={trackNum} className="relative flex" style={{ height: TRACK_H }}>
               <div
                 className="sticky left-0 z-[12] flex-shrink-0 flex flex-col items-center justify-center gap-0.5"
                 style={{
                   width: GUTTER,
                   background: theme.gutterBackground,
                   borderRight: `1px solid ${theme.gutterBorder}`,
+                  borderBottom: `1px solid ${theme.rowBorder}`,
                 }}
               >
                 {isAudioTrack && (
@@ -211,13 +211,35 @@ export function TimelineLanes({
                   )}
                 </button>
               </div>
+              {/* Left breathing pad — empty lane surface before t=0, scrolling
+                  with the content (the horizontal TRACKS_TOP_PAD). Sits OUTSIDE
+                  the time-mapped content div so clip/beat/menu math stays
+                  content-relative (clip left = t·pps). */}
+              <div
+                aria-hidden="true"
+                className="flex-shrink-0"
+                style={{ width: TRACKS_LEFT_PAD }}
+              />
               <div
                 style={{
                   width: trackContentWidth,
+                  background: rowBackground,
+                  borderBottom: `1px solid ${theme.rowBorder}`,
                   opacity: isTrackHidden ? 0.35 : 1,
                   transition: "opacity 120ms ease",
                 }}
                 className="relative"
+                onContextMenu={(e: React.MouseEvent) => {
+                  // Clip / keyframe-diamond context menus preventDefault at the
+                  // target before this bubble handler runs — respect them so a
+                  // right-click on a clip never also opens the gap menu.
+                  if (e.defaultPrevented || !onContextMenuLane) return;
+                  const rect = e.currentTarget.getBoundingClientRect();
+                  const time = (e.clientX - rect.left) / pps;
+                  if (time < 0) return;
+                  e.preventDefault();
+                  onContextMenuLane(e, trackNum, time);
+                }}
               >
                 {/* Faint beat lines in every track's background (behind the clips);
                     the active move-snap target is highlighted. */}

package/src/player/components/TimelineOverlays.tsx

@@ -8,6 +8,7 @@ import {
   type KeyframeDiamondContextMenuState,
 } from "./KeyframeDiamondContextMenu";
 import { ClipContextMenu } from "./ClipContextMenu";
+import { TrackGapContextMenu } from "./TrackGapContextMenu";
 import { TimelineShortcutHint } from "./TimelineShortcutHint";
 
 interface ClipContextMenuState {
@@ -16,6 +17,16 @@ interface ClipContextMenuState {
   element: TimelineElement;
 }
 
+/** Resolved model for the empty-lane-space (track gap) context menu. */
+interface TrackGapContextMenuState {
+  x: number;
+  y: number;
+  gapWidth: number | null;
+  canCloseGap: boolean;
+  canCloseAllGaps: boolean;
+  hasAnyGaps: boolean;
+}
+
 interface TimelineOverlaysProps {
   theme: TimelineTheme;
   showShortcutHint: boolean;
@@ -36,6 +47,11 @@ interface TimelineOverlaysProps {
   onSplitElement: TimelineEditCallbacks["onSplitElement"];
   pinZoomBeforeEdit: () => void;
   onDeleteElement?: (element: TimelineElement) => Promise<void> | void;
+  gapContextMenu: TrackGapContextMenuState | null;
+  onDismissGapContextMenu: () => void;
+  onCloseTrackGap: () => void;
+  onCloseAllTrackGaps: () => void;
+  onHoverGapAction: (action: "close-gap" | "close-all" | null) => void;
 }
 
 // The timeline's floating overlays, rendered as siblings above the scroll area:
@@ -61,6 +77,11 @@ export function TimelineOverlays({
   onSplitElement,
   pinZoomBeforeEdit,
   onDeleteElement,
+  gapContextMenu,
+  onDismissGapContextMenu,
+  onCloseTrackGap,
+  onCloseAllTrackGaps,
+  onHoverGapAction,
 }: TimelineOverlaysProps) {
   return (
     <>
@@ -117,6 +138,21 @@ export function TimelineOverlays({
           }}
         />
       )}
+
+      {gapContextMenu && (
+        <TrackGapContextMenu
+          x={gapContextMenu.x}
+          y={gapContextMenu.y}
+          gapWidth={gapContextMenu.gapWidth}
+          canCloseGap={gapContextMenu.canCloseGap}
+          canCloseAllGaps={gapContextMenu.canCloseAllGaps}
+          hasAnyGaps={gapContextMenu.hasAnyGaps}
+          onClose={onDismissGapContextMenu}
+          onCloseGap={onCloseTrackGap}
+          onCloseAllGaps={onCloseAllTrackGaps}
+          onHoverAction={onHoverGapAction}
+        />
+      )}
     </>
   );
 }