@hyperframes/studio 0.5.7 → 0.6.0-alpha.10

package/src/player/components/Timeline.tsx

@@ -28,6 +28,11 @@ import {
 } from "./timelineTheme";
 import { getPinchTimelineZoomPercent, getTimelinePixelsPerSecond } from "./timelineZoom";
 import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
+import {
+  canInspectTimelineElement,
+  getTimelineElementKey,
+  isAudioTimelineElement,
+} from "../../utils/timelineInspector";
 
 /* ── Layout ─────────────────────────────────────────────────────── */
 const GUTTER = 32;
@@ -35,7 +40,7 @@ const TRACK_H = 72;
 const RULER_H = 24;
 const CLIP_Y = 3; // vertical inset inside track
 const CLIP_HANDLE_W = 18;
-const TIMELINE_SCROLL_BUFFER = 24;
+const TIMELINE_SCROLL_BUFFER = 20;
 
 interface TrackVisualStyle extends TimelineTrackStyle {
   icon: ReactNode;
@@ -216,6 +221,14 @@ export function getTimelineCanvasHeight(trackCount: number): number {
   return RULER_H + Math.max(0, trackCount) * TRACK_H + TIMELINE_SCROLL_BUFFER;
 }
 
+export function shouldShowTimelineShortcutHint(
+  scrollHeight: number,
+  clientHeight: number,
+): boolean {
+  if (!Number.isFinite(scrollHeight) || !Number.isFinite(clientHeight)) return true;
+  return scrollHeight - clientHeight <= 1;
+}
+
 export function shouldHandleTimelineDeleteKey(input: {
   key: string;
   metaKey?: boolean;
@@ -279,7 +292,6 @@ export function resolveTimelineAssetDrop(
     track: getDefaultDroppedTrack(input.trackOrder, rowIndex),
   };
 }
-
 /* ── Component ──────────────────────────────────────────────────── */
 interface TimelineProps {
   /** Called when user seeks via ruler/track click or playhead drag */
@@ -322,6 +334,13 @@ interface TimelineProps {
     element: import("../store/playerStore").TimelineElement,
     intent: BlockedTimelineEditIntent,
   ) => void;
+  onSelectElement?: (element: import("../store/playerStore").TimelineElement | null) => void;
+  onInspectElement?: (element: import("../store/playerStore").TimelineElement) => void;
+  inspectedElementId?: string | null;
+  layerChildCounts?: ReadonlyMap<string, number>;
+  thumbnailedElementIds?: ReadonlySet<string>;
+  onToggleElementThumbnail?: (element: import("../store/playerStore").TimelineElement) => void;
+  disabled?: boolean;
   theme?: Partial<TimelineTheme>;
 }
 
@@ -369,6 +388,13 @@ export const Timeline = memo(function Timeline({
   onMoveElement,
   onResizeElement,
   onBlockedEditAttempt,
+  onSelectElement,
+  onInspectElement,
+  inspectedElementId,
+  layerChildCounts,
+  thumbnailedElementIds,
+  onToggleElementThumbnail,
+  disabled = false,
   theme: themeOverrides,
 }: TimelineProps = {}) {
   const theme = useMemo(() => ({ ...defaultTimelineTheme, ...themeOverrides }), [themeOverrides]);
@@ -388,6 +414,8 @@ export const Timeline = memo(function Timeline({
   const scrollRef = useRef<HTMLDivElement>(null);
   const [hoveredClip, setHoveredClip] = useState<string | null>(null);
   const isDragging = useRef(false);
+  const disabledRef = useRef(disabled);
+  disabledRef.current = disabled;
   const shiftClickClipRef = useRef<{
     element: TimelineElement;
     anchorX: number;
@@ -418,7 +446,6 @@ export const Timeline = memo(function Timeline({
   const resizingClipRef = useRef<ResizingClipState | null>(null);
   resizingClipRef.current = resizingClip;
   const blockedClipRef = useRef<BlockedClipState | null>(null);
-  const deleteInFlightRef = useRef(false);
   const onMoveElementRef = useRef(onMoveElement);
   onMoveElementRef.current = onMoveElement;
   const onResizeElementRef = useRef(onResizeElement);
@@ -427,32 +454,66 @@ export const Timeline = memo(function Timeline({
   onDeleteElementRef.current = onDeleteElement;
   const suppressClickRef = useRef(false);
   const [showPopover, setShowPopover] = useState(false);
+  const [showShortcutHint, setShowShortcutHint] = useState(true);
   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]);
 
   // Callback ref: sets up ResizeObserver when the DOM element actually mounts.
   // useMountEffect can't work here because the component returns null on first
   // render (timelineReady=false), so containerRef.current is null when the
   // effect fires and the ResizeObserver is never created.
-  const setContainerRef = useCallback((el: HTMLDivElement | null) => {
-    if (roRef.current) {
-      roRef.current.disconnect();
-      roRef.current = null;
-    }
-    containerRef.current = el;
-    if (!el) return;
-    setViewportWidth(el.clientWidth);
-    roRef.current = new ResizeObserver(([entry]) => {
-      setViewportWidth(entry.contentRect.width);
-    });
-    roRef.current.observe(el);
-  }, []);
+  const setContainerRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      if (roRef.current) {
+        roRef.current.disconnect();
+        roRef.current = null;
+      }
+      containerRef.current = el;
+      if (!el) return;
+      setViewportWidth(el.clientWidth);
+      scheduleShortcutHintVisibilitySync();
+      roRef.current = new ResizeObserver(([entry]) => {
+        setViewportWidth(entry.contentRect.width);
+        scheduleShortcutHintVisibilitySync();
+      });
+      roRef.current.observe(el);
+    },
+    [scheduleShortcutHintVisibilitySync],
+  );
 
   // Clean up ResizeObserver on unmount
   useMountEffect(() => () => {
     roRef.current?.disconnect();
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
   });
 
+  useEffect(() => {
+    if (!disabled) return;
+    stopClipDragAutoScrollRef.current();
+    isDragging.current = false;
+    isRangeSelecting.current = false;
+    blockedClipRef.current = null;
+    setDraggedClip(null);
+    setResizingClip(null);
+    setRangeSelection(null);
+    setShowPopover(false);
+    setIsDragOver(false);
+  }, [disabled]);
+
   // Effective duration: max of store duration and the furthest element end.
   // processTimelineMessage updates elements but not duration, so elements can
   // extend beyond the store's duration — this ensures fit mode shows everything.
@@ -495,6 +556,7 @@ export const Timeline = memo(function Timeline({
     }
     return [...trackOrder, draggedClip.previewTrack].sort((a, b) => a - b);
   }, [draggedClip, trackOrder]);
+  const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
   const selectedElement = useMemo(
     () => elements.find((element) => (element.key ?? element.id) === selectedElementId) ?? null,
     [elements, selectedElementId],
@@ -544,7 +606,6 @@ export const Timeline = memo(function Timeline({
     );
     previousZoomModeRef.current = zoomMode;
   }, [zoomMode]);
-
   useMountEffect(() => {
     const unsub = liveTime.subscribe((t) => {
       const dur = durationRef.current;
@@ -679,6 +740,7 @@ export const Timeline = memo(function Timeline({
 
   const seekFromX = useCallback(
     (clientX: number) => {
+      if (disabledRef.current) return;
       const el = scrollRef.current;
       if (!el || effectiveDuration <= 0) return;
       const rect = el.getBoundingClientRect();
@@ -736,6 +798,7 @@ export const Timeline = memo(function Timeline({
     };
 
     const handleWindowPointerMove = (e: PointerEvent) => {
+      if (disabledRef.current) return;
       const drag = draggedClipRef.current;
       const resize = resizingClipRef.current;
       const blocked = blockedClipRef.current;
@@ -820,6 +883,7 @@ export const Timeline = memo(function Timeline({
 
     const handleWindowPointerUp = () => {
       stopClipDragAutoScrollRef.current();
+      if (disabledRef.current) return;
       const resize = resizingClipRef.current;
       if (resize) {
         resizingClipRef.current = null;
@@ -911,30 +975,24 @@ export const Timeline = memo(function Timeline({
     };
   });
 
-  useMountEffect(() => {
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (!shouldHandleTimelineDeleteKey(event)) return;
-      const selected = selectedElementRef.current;
-      const onDelete = onDeleteElementRef.current;
-      if (!selected || !onDelete || deleteInFlightRef.current) return;
-      event.preventDefault();
-      deleteInFlightRef.current = true;
-      suppressClickRef.current = true;
+  const prevSelectedRef = useRef(selectedElementRef.current);
+  // eslint-disable-next-line no-restricted-syntax, react-hooks/exhaustive-deps
+  useEffect(() => {
+    const prev = prevSelectedRef.current;
+    const curr = selectedElementRef.current;
+    prevSelectedRef.current = curr;
+    if (prev && !curr) {
       setShowPopover(false);
       setRangeSelection(null);
-      Promise.resolve(onDelete(selected)).finally(() => {
-        deleteInFlightRef.current = false;
-        requestAnimationFrame(() => {
-          suppressClickRef.current = false;
-        });
-      });
-    };
-    window.addEventListener("keydown", handleKeyDown);
-    return () => window.removeEventListener("keydown", handleKeyDown);
+    }
   });
 
   const handlePointerDown = useCallback(
     (e: React.PointerEvent) => {
+      if (disabledRef.current) {
+        e.preventDefault();
+        return;
+      }
       if (e.button !== 0) return;
 
       // Shift+click starts range selection — even on clips
@@ -966,6 +1024,7 @@ export const Timeline = memo(function Timeline({
   );
   const handlePointerMove = useCallback(
     (e: React.PointerEvent) => {
+      if (disabledRef.current) return;
       if (isRangeSelecting.current) {
         const rect = scrollRef.current?.getBoundingClientRect();
         if (rect) {
@@ -1012,6 +1071,10 @@ export const Timeline = memo(function Timeline({
   );
   const majorTickInterval =
     major.length >= 2 ? Math.max(0.25, major[1] - major[0]) : effectiveDuration;
+  useEffect(() => {
+    syncShortcutHintVisibility();
+  }, [syncShortcutHintVisibility, timelineReady, elements.length, totalH]);
+
   const getPreviewElement = useCallback(
     (element: TimelineElement): TimelineElement => {
       if (
@@ -1032,6 +1095,7 @@ export const Timeline = memo(function Timeline({
 
   const [isDragOver, setIsDragOver] = useState(false);
   const handleAssetDragOver = useCallback((e: React.DragEvent) => {
+    if (disabledRef.current) return;
     const hasFiles = e.dataTransfer.files.length > 0;
     const hasAsset = Array.from(e.dataTransfer.types).includes(TIMELINE_ASSET_MIME);
     if (!hasFiles && !hasAsset) return;
@@ -1046,6 +1110,7 @@ export const Timeline = memo(function Timeline({
     (e: React.DragEvent) => {
       e.preventDefault();
       setIsDragOver(false);
+      if (disabledRef.current) return;
       if (onFileDrop && e.dataTransfer.files.length > 0) {
         const scroll = scrollRef.current;
         const rect = scroll?.getBoundingClientRect();
@@ -1102,6 +1167,7 @@ export const Timeline = memo(function Timeline({
 
   const handlePinchWheel = useCallback(
     (e: WheelEvent) => {
+      if (disabledRef.current) return;
       if (!e.ctrlKey) return;
       const scroll = scrollRef.current;
       if (!scroll || durationRef.current <= 0 || fitPpsRef.current <= 0 || ppsRef.current <= 0) {
@@ -1157,6 +1223,7 @@ export const Timeline = memo(function Timeline({
         className={`h-full border-t bg-[#0a0a0b] flex flex-col select-none transition-colors duration-150 ${
           isDragOver ? "border-studio-accent/50 bg-studio-accent/[0.03]" : "border-neutral-800/50"
         }`}
+        aria-disabled={disabled || undefined}
         onDragOver={handleAssetDragOver}
         onDragLeave={() => setIsDragOver(false)}
         onDrop={handleAssetDrop}
@@ -1239,7 +1306,6 @@ export const Timeline = memo(function Timeline({
     );
   }
 
-  const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
   const draggedElement = draggedClip?.element ?? null;
   const activeDraggedElement =
     draggedClip?.started === true && draggedElement
@@ -1313,7 +1379,14 @@ export const Timeline = memo(function Timeline({
     <div
       ref={setContainerRef}
       aria-label="Timeline"
-      className={`border-t select-none h-full overflow-hidden ${shiftHeld ? "cursor-crosshair" : "cursor-default"}`}
+      aria-disabled={disabled || undefined}
+      className={`relative border-t select-none h-full overflow-hidden transition-opacity ${
+        disabled
+          ? "cursor-not-allowed opacity-45"
+          : shiftHeld
+            ? "cursor-crosshair"
+            : "cursor-default"
+      }`}
       style={{
         touchAction: "pan-x pan-y",
         background: theme.shellBackground,
@@ -1451,6 +1524,14 @@ export const Timeline = memo(function Timeline({
                     const elementKey = el.key ?? el.id;
                     const capabilities = getTimelineEditCapabilities(el);
                     const isSelected = selectedElementId === elementKey;
+                    const canInspectClip = canInspectTimelineElement(el);
+                    const isInspectorActive =
+                      canInspectClip && inspectedElementId === getTimelineElementKey(el);
+                    const childCount = canInspectClip
+                      ? (layerChildCounts?.get(elementKey) ?? 0)
+                      : 0;
+                    const isThumbnailActive = thumbnailedElementIds?.has(elementKey) ?? false;
+                    const thumbnailLabel = isAudioTimelineElement(el) ? "waveform" : "thumbnail";
                     const isComposition = !!el.compositionSrc;
                     const clipKey = `${elementKey}-${i}`;
                     const isHovered = hoveredClip === clipKey;
@@ -1474,8 +1555,32 @@ export const Timeline = memo(function Timeline({
                         theme={theme}
                         trackStyle={clipStyle}
                         isComposition={isComposition}
+                        isInspectorActive={isInspectorActive}
+                        isThumbnailActive={isThumbnailActive}
+                        thumbnailLabel={thumbnailLabel}
+                        childCount={childCount}
                         onHoverStart={() => setHoveredClip(clipKey)}
                         onHoverEnd={() => setHoveredClip(null)}
+                        onInspectorClick={
+                          canInspectClip && onInspectElement
+                            ? (e) => {
+                                e.stopPropagation();
+                                if (suppressClickRef.current) return;
+                                setSelectedElementId(elementKey);
+                                onSelectElement?.(el);
+                                onInspectElement(el);
+                              }
+                            : undefined
+                        }
+                        onThumbnailClick={
+                          onToggleElementThumbnail && canInspectClip
+                            ? (e) => {
+                                e.stopPropagation();
+                                if (suppressClickRef.current) return;
+                                onToggleElementThumbnail(el);
+                              }
+                            : undefined
+                        }
                         onResizeStart={(edge, e) => {
                           if (e.button !== 0 || e.shiftKey || !onResizeElement) return;
                           if (edge === "start" && !capabilities.canTrimStart) return;
@@ -1548,7 +1653,9 @@ export const Timeline = memo(function Timeline({
                         onClick={(e) => {
                           e.stopPropagation();
                           if (suppressClickRef.current) return;
-                          setSelectedElementId(isSelected ? null : elementKey);
+                          const nextElement = isSelected ? null : el;
+                          setSelectedElementId(nextElement ? elementKey : null);
+                          onSelectElement?.(nextElement);
                         }}
                         onDoubleClick={(e) => {
                           e.stopPropagation();
@@ -1652,8 +1759,8 @@ export const Timeline = memo(function Timeline({
         </div>
       </div>
 
-      {/* Keyboard shortcut hint — always visible */}
-      {!showPopover && !rangeSelection && (
+      {/* Keyboard shortcut hint */}
+      {showShortcutHint && !showPopover && !rangeSelection && (
         <div className="absolute bottom-2 right-3 pointer-events-none z-20">
           <div
             className="flex items-center gap-1.5 px-2 py-1 rounded-md border"

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

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import { getTimelineClipControlPresentation } from "./TimelineClip";
+
+describe("getTimelineClipControlPresentation", () => {
+  it("collapses persistent controls for compact clips until the clip is interactive", () => {
+    expect(
+      getTimelineClipControlPresentation({
+        widthPx: 42,
+        isHovered: false,
+        isSelected: false,
+        isInspectorActive: false,
+        isThumbnailActive: false,
+        isDragging: false,
+      }),
+    ).toMatchObject({
+      compact: true,
+      showControls: false,
+    });
+  });
+
+  it("shows compact controls when the clip is hovered, selected, or active", () => {
+    expect(
+      getTimelineClipControlPresentation({
+        widthPx: 42,
+        isHovered: true,
+        isSelected: false,
+        isInspectorActive: false,
+        isThumbnailActive: false,
+        isDragging: false,
+      }),
+    ).toMatchObject({
+      compact: true,
+      showControls: true,
+    });
+
+    expect(
+      getTimelineClipControlPresentation({
+        widthPx: 42,
+        isHovered: false,
+        isSelected: false,
+        isInspectorActive: true,
+        isThumbnailActive: false,
+        isDragging: false,
+      }).showControls,
+    ).toBe(true);
+  });
+
+  it("keeps controls visible on wide clips", () => {
+    expect(
+      getTimelineClipControlPresentation({
+        widthPx: 120,
+        isHovered: false,
+        isSelected: false,
+        isInspectorActive: false,
+        isThumbnailActive: false,
+        isDragging: false,
+      }),
+    ).toMatchObject({
+      compact: false,
+      showControls: true,
+    });
+  });
+
+  it("treats medium-width clips as compact so dense tracks do not turn into icon grids", () => {
+    expect(
+      getTimelineClipControlPresentation({
+        widthPx: 96,
+        isHovered: false,
+        isSelected: false,
+        isInspectorActive: false,
+        isThumbnailActive: false,
+        isDragging: false,
+      }),
+    ).toMatchObject({
+      compact: true,
+      showControls: false,
+    });
+  });
+
+  it("hides controls while dragging", () => {
+    expect(
+      getTimelineClipControlPresentation({
+        widthPx: 120,
+        isHovered: true,
+        isSelected: true,
+        isInspectorActive: true,
+        isThumbnailActive: true,
+        isDragging: true,
+      }).showControls,
+    ).toBe(false);
+  });
+});