@hyperframes/studio 0.8.111 → 0.8.112

package/src/player/components/TimelineClip.filmstrip.test.tsx

@@ -0,0 +1,156 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { compile } from "tailwindcss";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { loadStylesheet, STYLES_DIR } from "../../styles/styleSources";
+import { cleanupMounted, trackedRoot } from "../../components/ui/mountHost.testHelpers";
+import { TimelineClip } from "./TimelineClip";
+import { renderClipChildren } from "./timelineClipChildren";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+
+let css: string;
+
+beforeAll(async () => {
+  css = (
+    await compile('@import "tailwindcss";\n@import "./theme.css";\n@import "./components.css";', {
+      base: STYLES_DIR,
+      loadStylesheet: async (id, base) => loadStylesheet(id, base),
+    })
+  ).build(["absolute", "inset-0", "overflow-hidden"]);
+});
+
+afterEach(() => {
+  cleanupMounted();
+  usePlayerStore.getState().setLintFindingsByElement(new Map());
+  document.body.innerHTML = "";
+});
+
+function render(tag: string, overrides: Partial<TimelineElement> = {}, picture = true) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = trackedRoot(host);
+  const element: TimelineElement = {
+    id: "clip",
+    label: "City",
+    tag,
+    start: 0,
+    duration: 1,
+    track: 0,
+    ...overrides,
+  };
+  const renderContent = picture ? () => <img alt="" /> : undefined;
+  act(() => {
+    root.render(
+      <TimelineClip
+        el={element}
+        pps={200}
+        clipY={0}
+        clipHeight={42}
+        isSelected
+        isHovered={false}
+        hasCustomContent={picture}
+        capabilities={{ canMove: true, canTrimStart: true, canTrimEnd: true }}
+        isComposition={false}
+        onHoverStart={vi.fn()}
+        onHoverEnd={vi.fn()}
+        onClick={vi.fn()}
+        onDoubleClick={vi.fn()}
+      >
+        {renderClipChildren(
+          element,
+          { clip: "#222", label: "#fff", accent: "#fff" },
+          renderContent,
+          undefined,
+        )}
+      </TimelineClip>,
+    );
+  });
+  return host;
+}
+
+describe("Filmstrip clips", () => {
+  it.each(["video", "img"])("reserves a 15px name band above %s pictures", (tag) => {
+    const host = render(tag);
+    const name = host.querySelector(".timeline-clip__name");
+    const picture = host.querySelector(".timeline-clip__content");
+    expect(name?.textContent).toBe("City");
+    expect(picture).not.toBeNull();
+    expect(picture?.querySelector("img")).not.toBeNull();
+    expect(css).toMatch(/--timeline-clip-band-height:\s*15px;/);
+    expect(css).toMatch(
+      /\.timeline-clip:not\(\.is-audio\) \.timeline-clip__label\s*\{[^}]*height:\s*var\(--timeline-clip-band-height\)/,
+    );
+    expect(css).toMatch(
+      /\.timeline-clip:not\(\.is-audio\) \.timeline-clip__content\s*\{[^}]*top:\s*var\(--timeline-clip-band-height\);[^}]*border-top-left-radius:\s*0;/,
+    );
+  });
+
+  it("keeps applied-state badges above the opaque name band", () => {
+    const host = render("video", { hasAudio: true, volume: 1.8 });
+    expect(host.querySelector('[data-badge="volume"]')?.textContent).toBe("180%");
+    const badges = host.querySelector('[data-testid="clip-badges"]');
+    expect(badges?.classList.contains("z-[31]")).toBe(true);
+    expect(badges?.classList.contains("max-w-[calc(100%-12px)]")).toBe(true);
+    expect(badges?.classList.contains("overflow-hidden")).toBe(true);
+    expect(badges?.parentElement?.classList.contains("timeline-clip__label")).toBe(true);
+    expect(css).toMatch(
+      /\.timeline-clip:not\(\.is-audio\) \.timeline-clip__name\s*\{[^}]*flex:\s*1;[^}]*min-width:\s*0;[^}]*overflow:\s*hidden;/,
+    );
+    expect(css).toMatch(
+      /\.timeline-clip:not\(\.is-audio\) \.timeline-clip__label\s*\{[^}]*z-index:\s*auto;/,
+    );
+  });
+
+  it("keeps fallback lint warnings clear of the name band and menu badge", () => {
+    usePlayerStore
+      .getState()
+      .setLintFindingsByElement(new Map([["clip", { count: 1, messages: ["Lint warning"] }]]));
+    const host = render("div", { duration: 0.3 }, false);
+    const name = host.querySelector(".timeline-clip__name");
+    const warning = host.querySelector<HTMLElement>('[title="Lint warning"]');
+    expect(warning).not.toBeNull();
+    expect(warning?.style.bottom).toBe("7px");
+    expect(warning?.style.top).toBe("");
+    expect(css).toMatch(/\.timeline-clip__timecode\s*\{[^}]*right:\s*16px;/);
+    expect(
+      (name?.compareDocumentPosition(warning!) ?? 0) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+    expect(css).toMatch(
+      /\.timeline-clip:not\(\.is-audio\) \.timeline-clip__label\s*\{[^}]*z-index:\s*auto;/,
+    );
+  });
+
+  it.each([0.02, 0.295])(
+    "keeps the name band without badge targets on a narrow visual clip (%ss)",
+    (duration) => {
+      const host = render("video", { duration, hasAudio: true, volume: 1.8 });
+      expect(host.querySelector(".timeline-clip__name")?.textContent).toBe("City");
+      expect(host.querySelector('[data-testid="clip-badges"]')).toBeNull();
+      expect(css).toMatch(/padding:\s*0 min\(6px,\s*25%\);/);
+      expect(css).toMatch(/padding-left:\s*min\(8px,\s*25%\);/);
+    },
+  );
+
+  it("lets audio keep its full-height content and pill radius", () => {
+    const host = render("audio");
+    const clip = host.querySelector(".timeline-clip");
+    const picture = host.querySelector(".timeline-clip__content");
+    expect(clip?.classList.contains("is-audio")).toBe(true);
+    expect(picture?.classList.contains("inset-0")).toBe(true);
+    expect(css).toMatch(/--timeline-clip-audio-radius:\s*21px;/);
+    expect(clip instanceof HTMLElement && clip.style.borderRadius).toBe(
+      "var(--timeline-clip-audio-radius)",
+    );
+  });
+
+  it("exports a single 1px selection ring around a 12px visual clip", () => {
+    const clip = render("video").querySelector(".timeline-clip");
+    expect(clip?.classList.contains("is-selected")).toBe(true);
+    expect(css).toMatch(/--timeline-clip-radius:\s*12px;/);
+    expect(css).toMatch(
+      /\.timeline-clip\.is-selected,\s*\.timeline-clip\[data-active\]\.is-selected\s*\{[^}]*outline:\s*1px solid var\(--timeline-clip-selection\);[^}]*outline-offset:\s*0;/,
+    );
+    expect(css).toMatch(/\.timeline-clip:not\(\.is-audio\)\s*\{\s*border-width:\s*0;/);
+  });
+});

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

@@ -127,7 +127,7 @@ describe("TimelineClip", () => {
       element: { id: "hero", label: "Hero", tag: "div", start: 1, duration: 1, track: 0 },
     });
 
-    expect(host.querySelector(".timeline-clip__label")?.textContent).toBe("Hero");
+    expect(host.querySelector(".timeline-clip__name")?.textContent).toBe("Hero");
     expect(host.querySelector(".timeline-clip__timecode")).toBeNull();
 
     act(() => root.unmount());
@@ -145,7 +145,7 @@ describe("TimelineClip", () => {
         playbackRate: 1.5,
       },
     });
-    expect(fast.host.querySelector(".timeline-clip__label")?.textContent).toBe("Hero [150%]");
+    expect(fast.host.querySelector(".timeline-clip__name")?.textContent).toBe("Hero [150%]");
     act(() => fast.root.unmount());
     const automation = JSON.stringify({
       version: 1,
@@ -170,18 +170,18 @@ describe("TimelineClip", () => {
         automation,
       },
     });
-    expect(ramp.host.querySelector(".timeline-clip__label")?.textContent).toBe("Hero [ramp]");
+    expect(ramp.host.querySelector(".timeline-clip__name")?.textContent).toBe("Hero [ramp]");
     act(() => ramp.root.unmount());
   });
 
-  it("drops the label chip under 60px even when the clip is selected", () => {
+  it("keeps the name band under 60px even when the clip is selected", () => {
     const { host, root } = renderClip({
       element: { id: "fx", label: "FX", tag: "div", start: 0, duration: 1, track: 0 },
       pps: 59,
       isSelected: true,
     });
 
-    expect(host.querySelector(".timeline-clip__label")).toBeNull();
+    expect(host.querySelector(".timeline-clip__name")?.textContent).toBe("FX");
     expect(host.querySelector(".timeline-clip__timecode")).toBeNull();
     expect(host.querySelector(".timeline-clip")?.getAttribute("data-ladder")).toBe("picture");
 
@@ -193,7 +193,7 @@ describe("TimelineClip", () => {
       element: { id: "wide", label: "City", tag: "video", start: 0, duration: 1, track: 0 },
       pps: 200,
     });
-    expect(labeled.host.querySelector(".timeline-clip__label")?.textContent).toBe("City");
+    expect(labeled.host.querySelector(".timeline-clip__name")?.textContent).toBe("City");
     expect(labeled.host.querySelector(".timeline-clip")?.getAttribute("data-ladder")).toBe(
       "labeled",
     );
@@ -207,7 +207,7 @@ describe("TimelineClip", () => {
       pps: 23,
       isSelected: true,
     });
-    expect(frame.host.querySelector(".timeline-clip__label")).toBeNull();
+    expect(frame.host.querySelector(".timeline-clip__name")?.textContent).toBe("City");
     expect(frame.host.querySelector(".timeline-clip")?.getAttribute("data-ladder")).toBe("frame");
     act(() => frame.root.unmount());
   });

package/src/player/components/TimelineClip.tsx

@@ -1,6 +1,7 @@
 import { memo, type CSSProperties, type ReactNode } from "react";
 import type { TimelineElement } from "../store/playerStore";
 import {
+  CLIP_TRIM_HIT_PX,
   clipWidthLadder,
   defaultTimelineTheme,
   getClipHandleOpacity,
@@ -70,9 +71,10 @@ export const TimelineClip = memo(function TimelineClip({
   const widthPx = Math.max(el.duration * pps, 4);
   const handleOpacity = getClipHandleOpacity({ isHovered, isSelected, isDragging });
   const displayLabel = `${el.label || el.id || el.tag}${clipSpeedSuffix(el.playbackRate, el.automation)}`;
+  const isAudioClip = isAudioTimelineElement(el);
   const ladder = clipWidthLadder(widthPx);
   const showHandles = handleOpacity > 0.01 && (widthPx >= 32 || isSelected);
-  const showLabel = ladder === "labeled";
+  const showLabel = !isAudioClip || ladder === "labeled";
   const showDefaultText = !hasCustomContent && ladder === "labeled";
   const startLabel = el.start.toFixed(1);
   const endLabel = (el.start + el.duration).toFixed(1);
@@ -88,9 +90,12 @@ export const TimelineClip = memo(function TimelineClip({
   } as CSSProperties;
   const linkColor = linkLabelColor(el.link);
   if (linkColor) Object.assign(themeVariables, { "--clip-link-color": linkColor });
-  const isAudioClip = isAudioTimelineElement(el);
   const hasFades = (isAudioClip || Boolean(el.hasAudio)) && !isGestureActor;
   const fade = useClipFadeDraft(el);
+  const badges =
+    ladder === "labeled" && !isGestureActor ? (
+      <ClipBadges el={el} onOpenMenu={onContextMenu} />
+    ) : null;
   const clipClassName = [
     "timeline-clip",
     "absolute",
@@ -136,12 +141,18 @@ export const TimelineClip = memo(function TimelineClip({
       tabIndex={isGestureActor ? undefined : tabIndex}
       aria-label={`${displayLabel}, ${startLabel} to ${endLabel} seconds`}
       aria-pressed={isGestureActor ? undefined : isSelected}
+      aria-keyshortcuts={isGestureActor || !capabilities.canMove ? undefined : "Space"}
+      aria-description={
+        isGestureActor || !capabilities.canMove
+          ? undefined
+          : "Space picks up. Up and Down choose a new track. Enter drops. Escape cancels."
+      }
       className={clipClassName}
       style={style}
       title={
         isComposition
           ? `${el.compositionSrc} • Double-click to open`
-          : `${displayLabel} • ${el.start.toFixed(1)}s – ${(el.start + el.duration).toFixed(1)}s`
+          : `${displayLabel} • ${startLabel}s – ${endLabel}s`
       }
       onPointerEnter={onHoverStart}
       onPointerLeave={onHoverEnd}
@@ -160,7 +171,7 @@ export const TimelineClip = memo(function TimelineClip({
             left: 0,
             top: 0,
             bottom: 0,
-            width: 14,
+            width: CLIP_TRIM_HIT_PX,
             cursor: "col-resize",
             zIndex: 4,
           }}
@@ -190,7 +201,7 @@ export const TimelineClip = memo(function TimelineClip({
             right: 0,
             top: 0,
             bottom: 0,
-            width: 14,
+            width: CLIP_TRIM_HIT_PX,
             cursor: "col-resize",
             zIndex: 4,
           }}
@@ -210,8 +221,13 @@ export const TimelineClip = memo(function TimelineClip({
           />
         </div>
       )}
-      {showLabel && <span className="timeline-clip__label">{displayLabel}</span>}
-      {showLabel && !isGestureActor && <ClipBadges el={el} onOpenMenu={onContextMenu} />}
+      {showLabel && (
+        <span className="timeline-clip__label">
+          <span className="timeline-clip__name">{displayLabel}</span>
+          {!isAudioClip && badges}
+        </span>
+      )}
+      {isAudioClip && badges}
       {!isGestureActor && el.syncOrigin && <OutOfSyncBadge el={el} />}
       {showDefaultText && (
         <span className="timeline-clip__timecode">

package/src/player/components/TimelineClipFades.tsx

@@ -20,6 +20,14 @@ import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { Tooltip } from "../../components/ui";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import { releasedOutsideWindow } from "./timelinePointerRelease";
+import {
+  FADE_TAB_CENTER_IN_HIT,
+  FADE_TAB_WIDTH,
+  fadeHandleBoxes,
+  type FadeEdge,
+  type FadeHandleBox,
+  type FadeHandleClipBox,
+} from "./timelineClipFadeGeometry";
 import {
   collectTimelineSnapTargets,
   snapTimelineTime,
@@ -28,14 +36,9 @@ import {
   type TimelineSnapType,
 } from "./timelineSnapping";
 
-type FadeEdge = "in" | "out";
 type FadeDraft = { edge: FadeEdge; seconds: number } | null;
 
-const TAB_WIDTH = 4;
 const TAB_HEIGHT = 15;
-const HANDLE_HIT = 24;
-const TAB_INSET = 7;
-const TAB_CENTER_IN_HIT = 8;
 const HANDLE_Z_ABOVE_CLIP_CONTENT = 30;
 const SUPPRESS_CLIP_NATIVE_TITLE = "";
 /** Pixels of pointer travel before a press on the handle counts as a drag. */
@@ -102,12 +105,6 @@ function keyedFadeSeconds(key: string, shift: boolean, current: number, limit: n
   return FADE_KEYS[key]?.(current, shift ? 1 : 0.1, limit) ?? null;
 }
 
-function topEdgeY(x: number, widthPx: number, heightPx: number, radiusPx: number): number {
-  const r = Math.min(radiusPx, widthPx / 2, heightPx / 2);
-  const d = x < r ? r - x : x > widthPx - r ? x - (widthPx - r) : 0;
-  return d > 0 ? r - Math.sqrt(Math.max(0, r * r - d * d)) : 0;
-}
-
 /** Slim tabs at each fade's end that drag `data-fade-in` / `data-fade-out`. */
 // fallow-ignore-next-line complexity
 export function TimelineClipFades({
@@ -135,14 +132,29 @@ export function TimelineClipFades({
   const visible =
     fades.fadeIn > 0 || fades.fadeOut > 0 || showHandles || dragging !== null || focused !== null;
   const rootRef = useRef<HTMLDivElement | null>(null);
-  const [clipBox, setClipBox] = useState({ height: 0, radius: 0 });
+  const [clipBox, setClipBox] = useState<FadeHandleClipBox>({
+    height: 0,
+    width: 0,
+    radius: 0,
+    toolsLeft: null,
+  });
   useLayoutEffect(() => {
-    const clip = rootRef.current?.parentElement;
-    if (!clip) return;
+    const root = rootRef.current;
+    const clip = root?.parentElement;
+    if (!root || !clip) return;
     const radius = parseFloat(getComputedStyle(clip).borderTopLeftRadius) || 0;
-    const height = clip.clientHeight;
+    const { clientHeight: height, clientWidth: width } = root;
+    const fx = clip.querySelector('[data-badge="fx"]');
+    const toolsLeft = fx
+      ? fx.getBoundingClientRect().left - root.getBoundingClientRect().left
+      : null;
     setClipBox((box) =>
-      box.height === height && box.radius === radius ? box : { height, radius },
+      box.height === height &&
+      box.width === width &&
+      box.radius === radius &&
+      box.toolsLeft === toolsLeft
+        ? box
+        : { height, width, radius, toolsLeft },
     );
   }, [widthPx, visible]);
 
@@ -332,39 +344,25 @@ export function TimelineClipFades({
   const handlesVisible = showHandles || dragging !== null || focused !== null;
   if (!visible) return null;
 
-  const hitWidth = Math.min(HANDLE_HIT, widthPx / 2);
-  const tabX = (edge: FadeEdge) => {
-    const knee = edge === "in" ? inPx : widthPx - outPx;
-    const inset = Math.min(TAB_INSET, widthPx / 2);
-    return Math.min(widthPx - inset, Math.max(inset, knee));
-  };
-  const boxLeft = (x: number) => Math.min(widthPx - hitWidth, Math.max(0, x - hitWidth / 2));
-  const [inX, outX] = [tabX("in"), tabX("out")];
-  const mid = (inX + outX) / 2;
   // A handle with no 0.01 s step to move is not drawn, unless in use: its twin owns the spot.
   const drawn = (edge: FadeEdge) =>
     currentSeconds(edge) > 0 ||
     Math.round(limitFor(edge) * 100) >= 1 ||
     dragging === edge ||
     focused === edge;
-  const overlap = drawn("in") && drawn("out") && boxLeft(inX) + hitWidth > boxLeft(outX);
-  const handleGeometry = (edge: FadeEdge) => {
-    const x = edge === "in" ? inX : outX;
-    // Boxes that would overlap meet at the midpoint between the two tabs.
-    const [left, right] = !overlap
-      ? [boxLeft(x), boxLeft(x) + hitWidth]
-      : edge === "in"
-        ? [Math.max(0, mid - hitWidth), mid]
-        : [mid, Math.min(widthPx, mid + hitWidth)];
-    const edgeY = topEdgeY(x, widthPx, clipBox.height, clipBox.radius);
-    return { left, width: right - left, tabLeft: x - left, top: edgeY + 1 - TAB_CENTER_IN_HIT };
-  };
-  const handleStyle = (geometry: { left: number; top: number; width: number }): CSSProperties => ({
+  const handleBoxes = fadeHandleBoxes({
+    widthPx,
+    inPx,
+    outPx,
+    clipBox,
+    drawn: { in: drawn("in"), out: drawn("out") },
+  });
+  const handleStyle = (geometry: FadeHandleBox): CSSProperties => ({
     position: "absolute",
     top: geometry.top,
     left: geometry.left,
     width: geometry.width,
-    height: HANDLE_HIT,
+    height: geometry.height,
     cursor: "ew-resize",
     opacity: handlesVisible ? 1 : 0,
     pointerEvents: handlesVisible && canEdit ? "auto" : "none",
@@ -417,7 +415,7 @@ export function TimelineClipFades({
       )}
       {canEdit &&
         (["in", "out"] as const).filter(drawn).map((edge) => {
-          const geometry = handleGeometry(edge);
+          const geometry = handleBoxes[edge];
           return (
             <FadeHandle
               key={edge}
@@ -428,7 +426,7 @@ export function TimelineClipFades({
               snapLabel={dragging === edge && snapType ? SNAP_LABEL[snapType] : null}
               style={handleStyle(geometry)}
               tabLeft={geometry.tabLeft}
-              tabTop={TAB_CENTER_IN_HIT - TAB_HEIGHT / 2}
+              tabTop={FADE_TAB_CENTER_IN_HIT - TAB_HEIGHT / 2}
               focusable={focusable}
               dragging={dragging === edge}
               onPointerDown={onHandlePointerDown(edge)}
@@ -560,9 +558,9 @@ function FadeHandle({
           aria-hidden="true"
           className="timeline-fade-tab"
           style={{
-            left: tabLeft - TAB_WIDTH / 2,
+            left: tabLeft - FADE_TAB_WIDTH / 2,
             top: tabTop,
-            width: TAB_WIDTH,
+            width: FADE_TAB_WIDTH,
             height: TAB_HEIGHT,
             pointerEvents: "none",
           }}

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

@@ -6,6 +6,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { TimelineGestureOverlay } from "./TimelineGestureOverlay";
 import type { DraggedClipState } from "./timelineClipDragTypes";
+import { createTimelineRowGeometry } from "./timelineLayout";
 import { getTrackStyle } from "./useTimelineTrackLayout";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
@@ -32,6 +33,40 @@ const drag: DraggedClipState = {
 afterEach(() => document.body.replaceChildren());
 
 describe("TimelineGestureOverlay", () => {
+  it("anchors an insert actor inside the opened seam at its drop time", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() =>
+      root.render(
+        <TimelineGestureOverlay
+          drag={{ ...drag, insertRow: 1 }}
+          scrollRef={{
+            current: {
+              scrollLeft: 0,
+              scrollTop: 0,
+              getBoundingClientRect: () => ({ left: 0, top: 0 }),
+            } as HTMLDivElement,
+          }}
+          pixelsPerSecond={100}
+          contentOrigin={232}
+          rowGeometry={createTimelineRowGeometry([0, -1, 1], [48, 48, 48], { top: 0 })}
+          rowHeight={42}
+          selectedElementId="hero"
+          currentTime={4}
+          theme={defaultTimelineTheme}
+          getTrackStyle={getTrackStyle}
+        />,
+      ),
+    );
+    const actor = host.querySelector<HTMLElement>("[data-timeline-gesture-actor]");
+    expect(actor?.style.left).toBe("632px");
+    expect(actor?.style.top).toBe("75px");
+    expect(host.querySelector("[data-timeline-new-track-label]")?.textContent).toContain(
+      "+ New track",
+    );
+    act(() => root.unmount());
+  });
   it("keeps the drag actor mounted without a source-row node", () => {
     const host = document.createElement("div");
     document.body.append(host);
@@ -47,6 +82,8 @@ describe("TimelineGestureOverlay", () => {
           drag={drag}
           scrollRef={{ current: scroll }}
           pixelsPerSecond={100}
+          contentOrigin={232}
+          rowGeometry={createTimelineRowGeometry([0, 1, 2], [48, 48, 48])}
           rowHeight={42}
           selectedElementId="hero"
           currentTime={4}
@@ -82,6 +119,8 @@ describe("TimelineGestureOverlay", () => {
             } as HTMLDivElement,
           }}
           pixelsPerSecond={100}
+          contentOrigin={232}
+          rowGeometry={createTimelineRowGeometry([0, 1, 2], [48, 48, 48])}
           rowHeight={42}
           selectedElementId="hero"
           currentTime={4}
@@ -109,6 +148,8 @@ describe("TimelineGestureOverlay", () => {
           drag={null}
           scrollRef={{ current: null }}
           pixelsPerSecond={100}
+          contentOrigin={232}
+          rowGeometry={createTimelineRowGeometry([0, 1, 2], [48, 48, 48])}
           rowHeight={42}
           selectedElementId={null}
           currentTime={0}

package/src/player/components/TimelineGestureOverlay.tsx

@@ -1,7 +1,7 @@
-import { memo, type ReactNode } from "react";
-import type { TimelineElement } from "../store/playerStore";
+import { memo } from "react";
 import type { TimelineTheme } from "./timelineTheme";
 import { getRenderedTimelineElement } from "./timelineTheme";
+import { CLIP_Y, type TimelineRowGeometry } from "./timelineLayout";
 import { TimelineClip } from "./TimelineClip";
 import { getTimelineEditCapabilities } from "./timelineEditing";
 import { renderClipChildren } from "./timelineClipChildren";
@@ -9,23 +9,21 @@ import { getTimelineDragOverlayPosition } from "./timelineClipDragPreview";
 import type { DraggedClipState } from "./timelineClipDragTypes";
 import type { TrackVisualStyle } from "./timelineIcons";
 import { isTimelineClipActive } from "./useTimelineActiveClips";
-import type { TimelineClipRenderContext } from "./TimelineTypes";
+import type { TimelineProps } from "./TimelineTypes";
 
 interface TimelineGestureOverlayProps {
   drag: DraggedClipState | null;
   scrollRef: React.RefObject<HTMLDivElement | null>;
   pixelsPerSecond: number;
   rowHeight: number;
+  contentOrigin: number;
+  rowGeometry: TimelineRowGeometry;
   selectedElementId: string | null;
   currentTime: number;
   theme: TimelineTheme;
   getTrackStyle: (tag: string) => TrackVisualStyle;
-  renderClipContent?: (
-    element: TimelineElement,
-    style: { clip: string; label: string },
-    context: TimelineClipRenderContext,
-  ) => ReactNode;
-  renderClipOverlay?: (element: TimelineElement) => ReactNode;
+  renderClipContent?: TimelineProps["renderClipContent"];
+  renderClipOverlay?: TimelineProps["renderClipOverlay"];
 }
 
 /** Stable canvas child that owns the live drag actor independently of source rows. */
@@ -34,6 +32,8 @@ export const TimelineGestureOverlay = memo(function TimelineGestureOverlay({
   scrollRef,
   pixelsPerSecond,
   rowHeight,
+  contentOrigin,
+  rowGeometry,
   selectedElementId,
   currentTime,
   theme,
@@ -41,30 +41,68 @@ export const TimelineGestureOverlay = memo(function TimelineGestureOverlay({
   renderClipContent,
   renderClipOverlay,
 }: TimelineGestureOverlayProps) {
-  const element =
-    drag?.started === true
-      ? getRenderedTimelineElement({
-          element: drag.element,
-          draggedElementId: drag.element.key ?? drag.element.id,
-          previewStart: drag.previewStart,
-          previewTrack: drag.previewTrack,
-        })
-      : null;
-  const position = drag ? getTimelineDragOverlayPosition(drag, scrollRef.current) : null;
+  if (!drag?.started)
+    return <div data-timeline-gesture-overlay className="absolute inset-0 pointer-events-none" />;
+  const element = getRenderedTimelineElement({
+    element: drag.element,
+    draggedElementId: drag.element.key ?? drag.element.id,
+    previewStart: drag.previewStart,
+    previewTrack: drag.previewTrack,
+  });
+  let position = getTimelineDragOverlayPosition(drag, scrollRef.current);
+  const insertRow = drag.insertRow;
+  if (insertRow !== null)
+    position = {
+      left: contentOrigin + drag.previewStart * pixelsPerSecond,
+      top: rowGeometry.getRowTop(insertRow) + CLIP_Y,
+    };
+  const clipWidth = Math.max(element.duration * pixelsPerSecond, 4);
+  const viewport = scrollRef.current;
+  let labelLeft = clipWidth + 10;
+  if (
+    position &&
+    viewport &&
+    position.left + labelLeft + 100 > viewport.scrollLeft + viewport.clientWidth
+  ) {
+    labelLeft = -100;
+    if (position.left + labelLeft < viewport.scrollLeft + contentOrigin)
+      labelLeft = Math.max(0, Math.min(clipWidth - 100, drag.pointerOffsetX));
+  }
   return (
     <div data-timeline-gesture-overlay className="absolute inset-0 pointer-events-none">
-      {element && position && (
+      {position && (
         <div
           data-timeline-gesture-actor={element.key ?? element.id}
           className="absolute"
           style={{
             top: position.top,
             left: position.left,
-            width: Math.max(element.duration * pixelsPerSecond, 4),
+            width: clipWidth,
             height: rowHeight,
             zIndex: 40,
           }}
         >
+          {insertRow !== null && (
+            <span
+              data-timeline-new-track-label
+              role="status"
+              className="absolute whitespace-nowrap"
+              style={{
+                left: labelLeft,
+                top: (rowHeight - 22) / 2,
+                height: 22,
+                padding: "2px 8px",
+                borderRadius: 999,
+                fontSize: 11,
+                color: "var(--timeline-accent)",
+                background: theme.rowBackground,
+                border: "1px solid var(--timeline-accent)",
+                zIndex: 25,
+              }}
+            >
+              + New track<span className="sr-only">, before track {insertRow + 1}</span>
+            </span>
+          )}
           <TimelineClip
             el={{ ...element, start: 0 }}
             pps={pixelsPerSecond}