@hyperframes/studio 0.7.54 → 0.7.56

package/src/player/components/TimelineOverlays.tsx

@@ -0,0 +1,122 @@
+import type { KeyframeCacheEntry, TimelineElement } from "../store/playerStore";
+import type { TimelineTheme } from "./timelineTheme";
+import type { TimelineRangeSelection } from "./timelineEditing";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
+import { EditPopover } from "./EditModal";
+import {
+  KeyframeDiamondContextMenu,
+  type KeyframeDiamondContextMenuState,
+} from "./KeyframeDiamondContextMenu";
+import { ClipContextMenu } from "./ClipContextMenu";
+import { TimelineShortcutHint } from "./TimelineShortcutHint";
+
+interface ClipContextMenuState {
+  x: number;
+  y: number;
+  element: TimelineElement;
+}
+
+interface TimelineOverlaysProps {
+  theme: TimelineTheme;
+  showShortcutHint: boolean;
+  showPopover: boolean;
+  rangeSelection: TimelineRangeSelection | null;
+  setShowPopover: (value: boolean) => void;
+  setRangeSelection: (value: TimelineRangeSelection | null) => void;
+  kfContextMenu: KeyframeDiamondContextMenuState | null;
+  setKfContextMenu: (value: KeyframeDiamondContextMenuState | null) => void;
+  onDeleteKeyframe: TimelineEditCallbacks["onDeleteKeyframe"];
+  onDeleteAllKeyframes: TimelineEditCallbacks["onDeleteAllKeyframes"];
+  onChangeKeyframeEase: TimelineEditCallbacks["onChangeKeyframeEase"];
+  onMoveKeyframeToPlayhead: TimelineEditCallbacks["onMoveKeyframeToPlayhead"];
+  keyframeCache: Map<string, KeyframeCacheEntry>;
+  clipContextMenu: ClipContextMenuState | null;
+  setClipContextMenu: (value: ClipContextMenuState | null) => void;
+  currentTime: number;
+  onSplitElement: TimelineEditCallbacks["onSplitElement"];
+  pinZoomBeforeEdit: () => void;
+  onDeleteElement?: (element: TimelineElement) => Promise<void> | void;
+}
+
+// The timeline's floating overlays, rendered as siblings above the scroll area:
+// the shortcut hint, the range-edit popover, the keyframe-diamond context menu,
+// and the clip context menu.
+export function TimelineOverlays({
+  theme,
+  showShortcutHint,
+  showPopover,
+  rangeSelection,
+  setShowPopover,
+  setRangeSelection,
+  kfContextMenu,
+  setKfContextMenu,
+  onDeleteKeyframe,
+  onDeleteAllKeyframes,
+  onChangeKeyframeEase,
+  onMoveKeyframeToPlayhead,
+  keyframeCache,
+  clipContextMenu,
+  setClipContextMenu,
+  currentTime,
+  onSplitElement,
+  pinZoomBeforeEdit,
+  onDeleteElement,
+}: TimelineOverlaysProps) {
+  return (
+    <>
+      {showShortcutHint && !showPopover && !rangeSelection && (
+        <TimelineShortcutHint theme={theme} />
+      )}
+
+      {showPopover && rangeSelection && (
+        <EditPopover
+          rangeStart={rangeSelection.start}
+          rangeEnd={rangeSelection.end}
+          anchorX={rangeSelection.anchorX}
+          anchorY={rangeSelection.anchorY}
+          onClose={() => {
+            setShowPopover(false);
+            setRangeSelection(null);
+          }}
+        />
+      )}
+
+      {kfContextMenu && (
+        <KeyframeDiamondContextMenu
+          state={kfContextMenu}
+          onClose={() => setKfContextMenu(null)}
+          onDelete={(elId, pct) => onDeleteKeyframe?.(elId, pct)}
+          onDeleteAll={(elId) => onDeleteAllKeyframes?.(elId)}
+          onChangeEase={(elId, pct, ease) => onChangeKeyframeEase?.(elId, pct, ease)}
+          onMoveToPlayhead={
+            onMoveKeyframeToPlayhead
+              ? (elId, pct) => onMoveKeyframeToPlayhead(elId, pct)
+              : undefined
+          }
+          onCopyProperties={(elId, pct) => {
+            const kfData = keyframeCache.get(elId);
+            const kf = kfData?.keyframes.find((k) => k.percentage === pct);
+            if (kf) {
+              void navigator.clipboard.writeText(JSON.stringify(kf.properties, null, 2));
+            }
+          }}
+        />
+      )}
+
+      {clipContextMenu && (
+        <ClipContextMenu
+          x={clipContextMenu.x}
+          y={clipContextMenu.y}
+          element={clipContextMenu.element}
+          currentTime={currentTime}
+          onClose={() => setClipContextMenu(null)}
+          onSplit={(el, time) => onSplitElement?.(el, time)}
+          onDelete={(el) => {
+            pinZoomBeforeEdit();
+            onDeleteElement?.(el);
+          }}
+        />
+      )}
+    </>
+  );
+}

package/src/player/components/VideoThumbnail.test.tsx

@@ -0,0 +1,152 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { VideoThumbnail } from "./VideoThumbnail";
+
+Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
+  configurable: true,
+  value: true,
+});
+
+// Fire "intersecting" immediately on observe so the extraction effect runs.
+class MockIntersectionObserver {
+  private cb: IntersectionObserverCallback;
+  constructor(cb: IntersectionObserverCallback) {
+    this.cb = cb;
+  }
+  observe() {
+    this.cb(
+      [{ isIntersecting: true } as IntersectionObserverEntry],
+      this as unknown as IntersectionObserver,
+    );
+  }
+  disconnect() {}
+  unobserve() {}
+  takeRecords(): IntersectionObserverEntry[] {
+    return [];
+  }
+}
+
+class MockResizeObserver {
+  observe() {}
+  disconnect() {}
+  unobserve() {}
+}
+
+const originalIO = globalThis.IntersectionObserver;
+const originalRO = globalThis.ResizeObserver;
+
+let host: HTMLDivElement;
+let root: Root | null = null;
+let createdVideos: HTMLVideoElement[];
+
+beforeEach(() => {
+  globalThis.IntersectionObserver =
+    MockIntersectionObserver as unknown as typeof IntersectionObserver;
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+
+  createdVideos = [];
+  const origCreate = document.createElement.bind(document);
+  vi.spyOn(document, "createElement").mockImplementation((tag: string) => {
+    const el = origCreate(tag);
+    if (tag === "video") createdVideos.push(el as HTMLVideoElement);
+    return el;
+  });
+
+  // happy-dom's <video>/<canvas> don't decode media; stub the seam the
+  // extractor depends on so the effect can run deterministically.
+  vi.spyOn(HTMLMediaElement.prototype, "load").mockImplementation(() => {});
+  vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue({
+    drawImage: () => {},
+  } as unknown as CanvasRenderingContext2D);
+
+  host = document.createElement("div");
+  document.body.append(host);
+});
+
+afterEach(() => {
+  act(() => root?.unmount());
+  root = null;
+  vi.restoreAllMocks();
+  globalThis.IntersectionObserver = originalIO;
+  globalThis.ResizeObserver = originalRO;
+  document.body.innerHTML = "";
+});
+
+function render(videoSrc: string) {
+  root = createRoot(host);
+  act(() => {
+    root!.render(React.createElement(VideoThumbnail, { videoSrc, label: "", labelColor: "#fff" }));
+  });
+}
+
+function lastVideo(): HTMLVideoElement {
+  const v = createdVideos.at(-1);
+  expect(v).toBeDefined();
+  return v!;
+}
+
+describe("VideoThumbnail — tainted-canvas fallback", () => {
+  it("stops the extractor and drops the shimmer when toDataURL throws a SecurityError", () => {
+    vi.spyOn(HTMLCanvasElement.prototype, "toDataURL").mockImplementation(() => {
+      throw new DOMException("Tainted canvases may not be exported.", "SecurityError");
+    });
+
+    render("https://cdn.example.com/no-cors.mp4");
+
+    // The effect ran once visible → a hidden <video> was created.
+    const video = lastVideo();
+
+    act(() => {
+      video.dispatchEvent(new Event("loadedmetadata"));
+    });
+    act(() => {
+      video.dispatchEvent(new Event("seeked"));
+    });
+
+    // No frame captured, and crucially the shimmer is gone (not spinning
+    // forever) — the clip falls back to its plain background.
+    expect(host.querySelectorAll("img").length).toBe(0);
+    expect(host.querySelector(".animate-pulse")).toBeNull();
+  });
+
+  it("drops the shimmer when a no-CORS load fires the video error event (0 frames) (#2214)", () => {
+    render("https://cdn.example.com/no-cors.mp4");
+    // Before the load resolves, the shimmer placeholder is up.
+    expect(host.querySelector(".animate-pulse")).not.toBeNull();
+
+    const video = lastVideo();
+    // crossOrigin="anonymous" against a CORS-less server fails the load outright —
+    // the error listener fires instead of loadedmetadata/seeked, so no frame is
+    // ever captured. The shimmer must stop rather than spin forever.
+    act(() => {
+      video.dispatchEvent(new Event("error"));
+    });
+
+    expect(host.querySelectorAll("img").length).toBe(0);
+    expect(host.querySelector(".animate-pulse")).toBeNull();
+  });
+
+  it("keeps streaming frames while the shimmer is up until a frame arrives", () => {
+    vi.spyOn(HTMLCanvasElement.prototype, "toDataURL").mockReturnValue(
+      "data:image/jpeg;base64,AAAA",
+    );
+
+    render("/api/projects/p/preview/assets/clip.mp4");
+    // Before any seek resolves, the shimmer placeholder is shown.
+    expect(host.querySelector(".animate-pulse")).not.toBeNull();
+
+    const video = lastVideo();
+    act(() => {
+      video.dispatchEvent(new Event("loadedmetadata"));
+    });
+    act(() => {
+      video.dispatchEvent(new Event("seeked"));
+    });
+
+    // A frame was captured, so tiles render and the shimmer clears.
+    expect(host.querySelectorAll("img").length).toBeGreaterThanOrEqual(1);
+    expect(host.querySelector(".animate-pulse")).toBeNull();
+  });
+});

package/src/player/components/VideoThumbnail.tsx

@@ -1,5 +1,6 @@
 import { memo, useRef, useState, useCallback, useEffect } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
+import { computeThumbnailStrip, THUMBNAIL_CLIP_HEIGHT } from "./thumbnailUtils";
 
 interface VideoThumbnailProps {
   videoSrc: string;
@@ -8,7 +9,7 @@ interface VideoThumbnailProps {
   duration?: number;
 }
 
-const CLIP_HEIGHT = 66;
+const CLIP_HEIGHT = THUMBNAIL_CLIP_HEIGHT;
 const MAX_UNIQUE_FRAMES: number = 6;
 
 /**
@@ -25,6 +26,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   const [containerWidth, setContainerWidth] = useState(0);
   const [visible, setVisible] = useState(false);
   const [frames, setFrames] = useState<string[]>([]);
+  const [failed, setFailed] = useState(false);
   const [aspect, setAspect] = useState(16 / 9);
   const ioRef = useRef<IntersectionObserver | null>(null);
   const roRef = useRef<ResizeObserver | null>(null);
@@ -117,8 +119,22 @@ export const VideoThumbnail = memo(function VideoThumbnail({
 
     video.addEventListener("seeked", () => {
       if (cancelled) return;
-      ctx.drawImage(video, 0, 0, canvas.width, canvas.height);
-      const dataUrl = canvas.toDataURL("image/jpeg", 0.6);
+      let dataUrl: string;
+      try {
+        ctx.drawImage(video, 0, 0, canvas.width, canvas.height);
+        dataUrl = canvas.toDataURL("image/jpeg", 0.6);
+      } catch {
+        // An external http(s) video served without CORS headers taints the
+        // canvas, so toDataURL throws a SecurityError. Stop the extractor
+        // cleanly and fall back to the no-thumbnail rendering (plain clip
+        // background), matching ImageThumbnail's error path — otherwise the
+        // shimmer placeholder would spin forever.
+        cancelled = true;
+        setFailed(true);
+        video.src = "";
+        video.load();
+        return;
+      }
       // Stream each frame immediately
       setFrames((prev) => [...prev, dataUrl]);
       idx++;
@@ -126,7 +142,12 @@ export const VideoThumbnail = memo(function VideoThumbnail({
     });
 
     video.addEventListener("error", () => {
-      /* keep whatever frames we have */
+      // A no-CORS load fails outright (crossOrigin="anonymous" rejects a video
+      // served without CORS headers), firing this instead of the taint path in
+      // "seeked" — so 0 frames are ever extracted. Keep whatever frames we have,
+      // but mark failed so the shimmer placeholder stops spinning forever and we
+      // fall back to the plain clip background (#2214).
+      setFailed(true);
     });
 
     video.src = videoSrc;
@@ -136,13 +157,13 @@ export const VideoThumbnail = memo(function VideoThumbnail({
       cancelled = true;
       extractingRef.current = false;
       setFrames([]);
+      setFailed(false);
       video.src = "";
       video.load();
     };
   }, [visible, videoSrc, duration]);
 
-  const frameW = Math.round(CLIP_HEIGHT * aspect);
-  const frameCount = containerWidth > 0 ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;
+  const { frameW, frameCount } = computeThumbnailStrip(containerWidth, aspect, CLIP_HEIGHT);
 
   return (
     <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">
@@ -168,7 +189,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
         </div>
       )}
 
-      {visible && frames.length === 0 && (
+      {visible && frames.length === 0 && !failed && (
         <div
           className="absolute inset-0 animate-pulse"
           style={{

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

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+import {
+  computeThumbnailStrip,
+  encodePreviewPath,
+  resolveMediaPreviewUrl,
+  THUMBNAIL_CLIP_HEIGHT,
+} from "./thumbnailUtils";
+
+describe("computeThumbnailStrip", () => {
+  it("sizes tiles by aspect ratio at the clip height", () => {
+    const { frameW } = computeThumbnailStrip(500, 16 / 9);
+    expect(frameW).toBe(Math.round(THUMBNAIL_CLIP_HEIGHT * (16 / 9)));
+  });
+
+  it("repeats tiles to cover the container width", () => {
+    const { frameW, frameCount } = computeThumbnailStrip(500, 1);
+    expect(frameW).toBe(THUMBNAIL_CLIP_HEIGHT);
+    expect(frameCount).toBe(Math.ceil(500 / THUMBNAIL_CLIP_HEIGHT));
+    expect(frameCount * frameW).toBeGreaterThanOrEqual(500);
+  });
+
+  it("returns one tile when the container width is unknown", () => {
+    expect(computeThumbnailStrip(0, 16 / 9).frameCount).toBe(1);
+    expect(computeThumbnailStrip(-10, 16 / 9).frameCount).toBe(1);
+  });
+
+  it("falls back to 16:9 for degenerate aspects", () => {
+    const expected = Math.round(THUMBNAIL_CLIP_HEIGHT * (16 / 9));
+    expect(computeThumbnailStrip(300, 0).frameW).toBe(expected);
+    expect(computeThumbnailStrip(300, -2).frameW).toBe(expected);
+    expect(computeThumbnailStrip(300, Number.NaN).frameW).toBe(expected);
+    expect(computeThumbnailStrip(300, Number.POSITIVE_INFINITY).frameW).toBe(expected);
+  });
+
+  it("never returns a zero-width tile (avoids divide-by-zero repeat counts)", () => {
+    const { frameW, frameCount } = computeThumbnailStrip(300, 0.001);
+    expect(frameW).toBeGreaterThanOrEqual(1);
+    expect(Number.isFinite(frameCount)).toBe(true);
+  });
+
+  it("honors a custom clip height", () => {
+    expect(computeThumbnailStrip(300, 2, 40).frameW).toBe(80);
+  });
+});
+
+describe("resolveMediaPreviewUrl", () => {
+  it("routes composition-relative paths through the project preview endpoint", () => {
+    expect(resolveMediaPreviewUrl("assets/image.png", "proj-1")).toBe(
+      "/api/projects/proj-1/preview/assets/image.png",
+    );
+  });
+
+  it("passes absolute http(s) URLs through untouched", () => {
+    expect(resolveMediaPreviewUrl("http://cdn.example.com/a.mp4", "proj-1")).toBe(
+      "http://cdn.example.com/a.mp4",
+    );
+    expect(resolveMediaPreviewUrl("https://cdn.example.com/a.png", "proj-1")).toBe(
+      "https://cdn.example.com/a.png",
+    );
+  });
+
+  it("percent-encodes spaces in filenames", () => {
+    expect(resolveMediaPreviewUrl("assets/my logo.png", "proj-1")).toBe(
+      "/api/projects/proj-1/preview/assets/my%20logo.png",
+    );
+  });
+
+  it("percent-encodes parentheses in filenames", () => {
+    expect(resolveMediaPreviewUrl("assets/heygen-symbol-blue-logo (2).svg", "proj-1")).toBe(
+      "/api/projects/proj-1/preview/assets/heygen-symbol-blue-logo%20(2).svg",
+    );
+  });
+
+  it("preserves slashes as path separators while encoding each segment", () => {
+    expect(resolveMediaPreviewUrl("sub dir/file (v2).mp4", "proj-2")).toBe(
+      "/api/projects/proj-2/preview/sub%20dir/file%20(v2).mp4",
+    );
+  });
+
+  it("percent-encodes unicode characters in filenames", () => {
+    expect(resolveMediaPreviewUrl("assets/café logo.png", "proj-1")).toBe(
+      "/api/projects/proj-1/preview/assets/caf%C3%A9%20logo.png",
+    );
+  });
+
+  it("leaves paths with no special characters unchanged", () => {
+    expect(resolveMediaPreviewUrl("assets/logo.svg", "proj-1")).toBe(
+      "/api/projects/proj-1/preview/assets/logo.svg",
+    );
+  });
+
+  it("percent-encodes a U+202F narrow no-break space (macOS screenshot artifact)", () => {
+    // "Screenshot … 2.16.30 PM.png" — the char between the time and PM is a
+    // narrow no-break space; it must encode to %E2%80%AF, not route raw (404).
+    expect(resolveMediaPreviewUrl("assets/Screenshot 2.16.30 PM.png", "proj-1")).toBe(
+      "/api/projects/proj-1/preview/assets/Screenshot%202.16.30%E2%80%AFPM.png",
+    );
+  });
+
+  it("passes data: URIs through untouched (never routes them through preview → HTTP 431)", () => {
+    const svg = "data:image/svg+xml;base64,PHN2Zz48L3N2Zz4=";
+    expect(resolveMediaPreviewUrl(svg, "proj-1")).toBe(svg);
+  });
+
+  it("passes blob: URLs through untouched", () => {
+    const blob = "blob:http://localhost:5190/2b3c-4d5e";
+    expect(resolveMediaPreviewUrl(blob, "proj-1")).toBe(blob);
+  });
+});
+
+// The shared encoder used by every timeline media-URL builder (filmstrip, audio
+// waveform, sub-composition preview) — must match the assets panel's per-segment
+// encoding so those paths stop 404ing on non-ASCII filenames.
+describe("encodePreviewPath", () => {
+  it("encodes spaces and parentheses per segment, preserving slashes", () => {
+    expect(encodePreviewPath("sub dir/file (v2).mp3")).toBe("sub%20dir/file%20(v2).mp3");
+  });
+
+  it("encodes a U+202F narrow no-break space to %E2%80%AF", () => {
+    expect(encodePreviewPath("assets/clip 2.mp3")).toBe("assets/clip%202.mp3");
+    expect(encodePreviewPath(`assets/clip${" "}2.mp3`)).toBe("assets/clip%E2%80%AF2.mp3");
+  });
+
+  it("leaves a plain path unchanged", () => {
+    expect(encodePreviewPath("assets/music.mp3")).toBe("assets/music.mp3");
+  });
+});

package/src/player/components/thumbnailUtils.ts

@@ -0,0 +1,54 @@
+/** Rendered height of a timeline-clip thumbnail strip, in CSS px. */
+export const THUMBNAIL_CLIP_HEIGHT = 66;
+
+export interface ThumbnailStripLayout {
+  /** Width of a single tile, in CSS px. */
+  frameW: number;
+  /** Number of tiles needed to fill the container. */
+  frameCount: number;
+}
+
+/**
+ * Compute the film-strip tile layout for a clip thumbnail: fixed-height tiles
+ * sized by the media's aspect ratio, repeated to fill the clip width.
+ * Degenerate aspects (0, negative, NaN, Infinity) fall back to 16:9.
+ */
+export function computeThumbnailStrip(
+  containerWidth: number,
+  aspect: number,
+  clipHeight: number = THUMBNAIL_CLIP_HEIGHT,
+): ThumbnailStripLayout {
+  const safeAspect = Number.isFinite(aspect) && aspect > 0 ? aspect : 16 / 9;
+  const frameW = Math.max(1, Math.round(clipHeight * safeAspect));
+  const frameCount = containerWidth > 0 ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;
+  return { frameW, frameCount };
+}
+
+/**
+ * Percent-encode each segment of a composition-relative media path so filenames
+ * containing spaces, parentheses, a U+202F narrow no-break space (the macOS
+ * screenshot artifact), or any other non-ASCII / URL-unsafe character yield a
+ * valid URL instead of a 404. Slashes are preserved as separators.
+ *
+ * Shared by every timeline media-URL builder (filmstrip thumbnails, audio
+ * waveform, sub-composition preview) so they encode identically to the assets
+ * panel — a raw segment 404s on the exact filenames the assets panel loads fine.
+ */
+export function encodePreviewPath(relativePath: string): string {
+  return relativePath.split("/").map(encodeURIComponent).join("/");
+}
+
+/**
+ * Resolve a timeline element's media src to a URL loadable from the studio
+ * (parent) document. Composition-relative paths (e.g. "assets/image.png") are
+ * routed through the project preview endpoint with each segment encoded.
+ *
+ * Already-loadable URLs pass through untouched: absolute http(s) URLs, plus
+ * `data:` and `blob:` URLs. Routing a `data:`/`blob:` URL through the preview
+ * endpoint would percent-encode the whole thing into a multi-KB path segment
+ * that the server rejects with HTTP 431 (Request Header Fields Too Large).
+ */
+export function resolveMediaPreviewUrl(src: string, projectId: string): string {
+  if (/^(?:https?:|data:|blob:)/i.test(src)) return src;
+  return `/api/projects/${projectId}/preview/${encodePreviewPath(src)}`;
+}

package/src/player/components/timelineCallbacks.ts

@@ -1,12 +1,8 @@
 // fallow-ignore-file code-duplication
 // fallow-ignore-file dead-code
 import type { TimelineElement } from "../store/playerStore";
-import type { BlockedTimelineEditIntent, TimelineStackingReorderIntent } from "./timelineEditing";
-import type {
-  TimelineGroupCommitOptions,
-  TimelineGroupMoveChange,
-  TimelineGroupResizeChange,
-} from "../../hooks/useTimelineGroupEditing";
+import type { TimelineMoveOperation } from "../../hooks/timelineMoveAdapter";
+import type { BlockedTimelineEditIntent } from "./timelineEditing";
 
 /**
  * Shared callback signatures for timeline editing operations.
@@ -31,26 +27,30 @@ export interface TimelineDropCallbacks {
 export interface TimelineEditCallbacks {
   onMoveElement?: (
     element: TimelineElement,
-    updates: Pick<TimelineElement, "start" | "track"> & {
-      stackingReorder?: TimelineStackingReorderIntent | null;
-    },
+    updates: Pick<TimelineElement, "start" | "track">,
+  ) => 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. */
+  onMoveElements?: (
+    edits: Array<{ element: TimelineElement; updates: Pick<TimelineElement, "start" | "track"> }>,
+    coalesceKey?: string,
+    operation?: TimelineMoveOperation,
   ) => Promise<void> | void;
   onResizeElement?: (
     element: TimelineElement,
     updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
   ) => Promise<void> | void;
-  onMoveElements?: (
-    changes: TimelineGroupMoveChange[],
-    options?: TimelineGroupCommitOptions,
-  ) => Promise<void> | void;
   onResizeElements?: (
-    changes: TimelineGroupResizeChange[],
-    options?: TimelineGroupCommitOptions,
+    changes: Array<{
+      element: TimelineElement;
+      start: number;
+      duration: number;
+      playbackStart?: number;
+    }>,
+    options?: { coalesceKey?: string },
   ) => Promise<void> | void;
-  onPreviewMoveElements?: (changes: TimelineGroupMoveChange[]) => void;
-  onPreviewResizeElements?: (changes: TimelineGroupResizeChange[]) => void;
   onToggleTrackHidden?: (track: number, hidden: boolean) => Promise<void> | void;
-  onToggleElementHidden?: (elementKey: string, hidden: boolean) => Promise<void> | void;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   onSplitElement?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;

package/src/player/components/timelineClipChildren.tsx

@@ -0,0 +1,39 @@
+import { type ReactNode } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { TrackVisualStyle } from "./timelineIcons";
+
+function ClipLintDot({ element }: { element: TimelineElement }) {
+  const lint = usePlayerStore((s) => s.lintFindingsByElement.get(element.key ?? element.id));
+  if (!lint || lint.count === 0) return null;
+  return (
+    <span
+      className="absolute w-1.5 h-1.5 rounded-full bg-amber-400"
+      style={{ top: 7, right: 7 }}
+      title={lint.messages.join("\n")}
+    />
+  );
+}
+
+export function renderClipChildren(
+  element: TimelineElement,
+  clipStyle: TrackVisualStyle,
+  renderClipContent:
+    | ((element: TimelineElement, style: { clip: string; label: string }) => ReactNode)
+    | undefined,
+  renderClipOverlay: ((element: TimelineElement) => ReactNode) | undefined,
+): ReactNode {
+  return (
+    <>
+      {renderClipOverlay?.(element)}
+      {!renderClipContent && <ClipLintDot element={element} />}
+      {renderClipContent && (
+        // borderRadius: inherit — the clip itself is overflow-visible (keyframe
+        // diamonds hang outside its bounds), so the thumbnail layer must clip
+        // itself to the clip's rounded corners or sharp corners poke out.
+        <div className="absolute inset-0 overflow-hidden" style={{ borderRadius: "inherit" }}>
+          {renderClipContent(element, clipStyle)}
+        </div>
+      )}
+    </>
+  );
+}