@hyperframes/studio 0.7.56 → 0.7.58

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

package/src/player/components/TimelineRuler.tsx

@@ -1,6 +1,8 @@
 import { memo } from "react";
 import type { TimelineTheme } from "./timelineTheme";
-import { GUTTER, RULER_H, formatTimelineTickLabel } from "./timelineLayout";
+import { GUTTER, RULER_H, TRACKS_LEFT_PAD, formatTimelineTickLabel } from "./timelineLayout";
+import { usePlayerStore } from "../store/playerStore";
+import { secondsToFrame } from "../lib/time";
 import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
 
 interface TimelineRulerProps {
@@ -26,6 +28,7 @@ export const TimelineRuler = memo(function TimelineRuler({
   theme,
   beatAnalysis,
 }: TimelineRulerProps) {
+  const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
   const beatTimes = beatAnalysis?.beatTimes ?? [];
   const beatStrengths = beatAnalysis?.beatStrengths ?? [];
 
@@ -38,27 +41,13 @@ export const TimelineRuler = memo(function TimelineRuler({
 
   return (
     <>
-      {/* Grid lines (major ticks + beat lines) — behind the tracks (background).
-          Opaque track rows hide them; only the beat dots show on tracks. */}
+      {/* Background SVG — beat lines only; major-tick gridlines removed so only
+          the ruler's own small ticks mark intervals (no full-height lines). */}
       <svg
         className="absolute pointer-events-none"
-        style={{ left: GUTTER, width: trackContentWidth, zIndex: 0 }}
+        style={{ left: GUTTER + TRACKS_LEFT_PAD, width: trackContentWidth, zIndex: 0 }}
         height={totalH}
       >
-        {major.map((t) => {
-          const x = t * pps;
-          return (
-            <line
-              key={`g-${t}`}
-              x1={x}
-              y1={RULER_H}
-              x2={x}
-              y2={totalH}
-              stroke={theme.tickMinor}
-              strokeWidth="1"
-            />
-          );
-        })}
         {showBeats &&
           beatTimes.map((t, i) => {
             const x = t * pps;
@@ -79,41 +68,75 @@ export const TimelineRuler = memo(function TimelineRuler({
           })}
       </svg>
 
-      {/* Ruler. The bar fills the full panel width (canvas is min 100% wide);
-          calc(100% - GUTTER) equals trackContentWidth when zoomed in and extends
-          past the content when zoomed out. Ticks stay at composition coordinates. */}
+      {/* Ruler — sticky so the timestamps stay visible while the tracks scroll
+          vertically. Opaque background (plus the gutter corner block) so clips
+          scrolling underneath don't bleed through; z-index sits above the track
+          rows and drag overlays but below the playhead (z 100). */}
       <div
-        className="relative overflow-hidden"
+        className="sticky top-0 flex"
         style={{
           height: RULER_H,
-          marginLeft: GUTTER,
-          width: `calc(100% - ${GUTTER}px)`,
-          background: theme.gutterBackground,
-          borderBottom: `1px solid ${theme.rulerBorder}`,
+          width: GUTTER + TRACKS_LEFT_PAD + trackContentWidth,
+          zIndex: 70,
         }}
       >
-        {minor.map((t) => (
-          <div key={`m-${t}`} className="absolute bottom-0" style={{ left: t * pps }}>
-            <div className="w-px h-2" style={{ background: theme.tickMinor }} />
-          </div>
-        ))}
+        <div
+          className="sticky left-0 z-[12] flex-shrink-0"
+          style={{
+            width: GUTTER,
+            // Ruler corner uses the panel surface — same as the ruler strip
+            // itself, and NO right border: the ruler band stays completely
+            // clean until 00:00 (the header-boundary line belongs to the track
+            // rows below, not the ruler).
+            background: theme.shellBackground,
+          }}
+        />
+        {/* Left breathing pad — scrolls with the content, so 00:00 starts a
+            beat right of the gutter (see TRACKS_LEFT_PAD). */}
+        <div
+          aria-hidden="true"
+          className="flex-shrink-0"
+          style={{ width: TRACKS_LEFT_PAD, background: theme.shellBackground }}
+        />
+        <div
+          className="relative overflow-hidden"
+          style={{
+            height: RULER_H,
+            width: trackContentWidth,
+            // Ruler background = panel surface (#0A0A0B) — no bottom border,
+            // no tick lines (CapCut-style clean ruler, labels only).
+            background: theme.shellBackground,
+          }}
+        >
+          {/* Each 1px tick line is shifted -0.5px so its CENTER sits exactly on
+              t * pps — matching the playhead line, which is also centered on
+              GUTTER + t * pps (see getTimelinePlayheadLeft). Without the shift
+              a tick spans [x, x+1) and its center is half a pixel right. */}
+          {minor.map((t) => (
+            <div key={`m-${t}`} className="absolute bottom-0" style={{ left: t * pps - 0.5 }}>
+              <div className="w-px h-2" style={{ background: theme.tickMinor }} />
+            </div>
+          ))}
 
-        {major.map((t) => (
-          <div key={`M-${t}`} className="absolute top-0" style={{ left: t * pps }}>
-            <span
-              className="absolute font-mono tabular-nums leading-none whitespace-nowrap"
-              style={{
-                color: theme.tickText,
-                left: 5,
-                top: 5,
-                fontSize: 10,
-              }}
-            >
-              {formatTimelineTickLabel(t, effectiveDuration, majorTickInterval)}
-            </span>
-            <div className="w-px" style={{ height: RULER_H, background: theme.tickMajor }} />
-          </div>
-        ))}
+          {major.map((t) => (
+            <div key={`M-${t}`} className="absolute top-0" style={{ left: t * pps - 0.5 }}>
+              <span
+                className="absolute font-mono tabular-nums leading-none whitespace-nowrap"
+                style={{
+                  color: theme.tickText,
+                  left: 5,
+                  top: 5,
+                  fontSize: 10,
+                }}
+              >
+                {timeDisplayMode === "frame"
+                  ? secondsToFrame(t)
+                  : formatTimelineTickLabel(t, effectiveDuration, majorTickInterval)}
+              </span>
+              <div className="w-px" style={{ height: RULER_H, background: theme.tickMajor }} />
+            </div>
+          ))}
+        </div>
       </div>
     </>
   );

package/src/player/components/TrackGapContextMenu.tsx

@@ -0,0 +1,116 @@
+import { memo } from "react";
+import { createPortal } from "react-dom";
+import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
+
+interface TrackGapContextMenuProps {
+  x: number;
+  y: number;
+  /** Width (seconds) of the gap under the pointer, or null when no clip exists to the right. */
+  gapWidth: number | null;
+  /** "Close gap" actionable: a gap exists AND every clip that must shift is movable. */
+  canCloseGap: boolean;
+  /** "Close all gaps" actionable: the lane has gaps AND every shifting clip is movable. */
+  canCloseAllGaps: boolean;
+  /** The lane has at least one gap (distinguishes the two disabled reasons). */
+  hasAnyGaps: boolean;
+  onClose: () => void;
+  onCloseGap: () => void;
+  onCloseAllGaps: () => void;
+  /** Hover state for the gap-strip highlight overlay (null = nothing hovered).
+   *  Only reported for ACTIONABLE rows — a disabled row closes nothing, so
+   *  highlighting from it would promise an action that can't happen. */
+  onHoverAction: (action: "close-gap" | "close-all" | null) => void;
+}
+
+/**
+ * Context menu for right-clicking EMPTY space on a timeline lane
+ * (CapCut/Premiere-style). Offers "Close gap" (collapse the clicked gap by
+ * shifting the following clips on that lane left) and "Close all gaps"
+ * (compact the whole lane contiguous from 0). Both rows are ALWAYS present —
+ * an inapplicable action dims with a tooltip explaining why, rather than
+ * vanishing into a one-item menu. Hovering an actionable row highlights the
+ * gap strip(s) it would close (via onHoverAction → TimelineCanvas overlay).
+ * Styling mirrors ClipContextMenu.
+ */
+export const TrackGapContextMenu = memo(function TrackGapContextMenu({
+  x,
+  y,
+  gapWidth,
+  canCloseGap,
+  canCloseAllGaps,
+  hasAnyGaps,
+  onClose,
+  onCloseGap,
+  onCloseAllGaps,
+  onHoverAction,
+}: TrackGapContextMenuProps) {
+  const menuRef = useContextMenuDismiss(onClose);
+
+  const menuWidth = 200;
+  const menuHeight = 68;
+  const overflowY = y + menuHeight - window.innerHeight;
+  const adjustedX = x + menuWidth > window.innerWidth ? x - menuWidth : x;
+  const adjustedY = overflowY > 0 ? y - overflowY - 8 : y;
+
+  const itemClass = (enabled: boolean) =>
+    `w-full flex items-center justify-between px-3 py-1.5 text-xs text-left ${
+      enabled
+        ? "text-neutral-300 hover:bg-neutral-800 cursor-pointer"
+        : "text-neutral-600 cursor-not-allowed"
+    }`;
+
+  // Disabled reasons: no gap under the pointer beats the lock reason — a
+  // pointer not on a gap has nothing to close regardless of movability.
+  const closeGapTitle = canCloseGap
+    ? undefined
+    : gapWidth == null
+      ? "No gap here"
+      : "A clip on this track can't be moved";
+  const closeAllTitle = canCloseAllGaps
+    ? undefined
+    : hasAnyGaps
+      ? "A clip on this track can't be moved"
+      : "No gaps on this track";
+
+  return createPortal(
+    <div
+      ref={menuRef}
+      className="fixed z-50 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"
+      style={{ left: adjustedX, top: adjustedY }}
+      onPointerLeave={() => onHoverAction(null)}
+    >
+      <button
+        type="button"
+        className={itemClass(canCloseGap)}
+        disabled={!canCloseGap}
+        title={closeGapTitle}
+        onPointerEnter={() => onHoverAction(canCloseGap ? "close-gap" : null)}
+        onClick={() => {
+          if (!canCloseGap) return;
+          onCloseGap();
+          onClose();
+        }}
+      >
+        <span>Close gap</span>
+        {gapWidth != null && (
+          <span className="text-neutral-500 text-[10px] ml-3">{gapWidth.toFixed(2)}s</span>
+        )}
+      </button>
+      <button
+        type="button"
+        className={itemClass(canCloseAllGaps)}
+        disabled={!canCloseAllGaps}
+        title={closeAllTitle}
+        onPointerEnter={() => onHoverAction(canCloseAllGaps ? "close-all" : null)}
+        onClick={() => {
+          if (!canCloseAllGaps) return;
+          onCloseAllGaps();
+          onClose();
+        }}
+      >
+        <span>Close all gaps</span>
+      </button>
+    </div>,
+    document.body,
+  );
+});

package/src/player/components/timelineCallbacks.ts

@@ -31,11 +31,14 @@ export interface TimelineEditCallbacks {
   ) => Promise<void> | void;
   /** Atomic multi-clip move (single undo) for main-track ripple + track-insert.
    *  `coalesceKey` (drag-commit gesture id) merges the move history entry with a
-   *  lane change's follow-up z-reorder entry into one undo step. */
+   *  lane change's follow-up z-reorder entry into one undo step; `coalesceMs`
+   *  widens that entry's fold window when a server round-trip separates the
+   *  gesture's records (per-gesture-unique keys keep the fold gesture-scoped). */
   onMoveElements?: (
     edits: Array<{ element: TimelineElement; updates: Pick<TimelineElement, "start" | "track"> }>,
     coalesceKey?: string,
     operation?: TimelineMoveOperation,
+    coalesceMs?: number,
   ) => Promise<void> | void;
   onResizeElement?: (
     element: TimelineElement,