@hyperframes/studio 0.8.92 → 0.8.94

package/src/components/editor/DomEditSelectionChrome.tsx

@@ -1,6 +1,10 @@
 import type { RefObject } from "react";
 import { type DomEditSelection } from "./domEditing";
-import type { GroupOverlayItem, OverlayRect } from "./domEditOverlayGeometry";
+import {
+  type GroupOverlayItem,
+  type OverlayRect,
+  RESIZE_HANDLE_HIT_PX,
+} from "./domEditOverlayGeometry";
 import type { ResizeHandle } from "./domEditOverlayGestures";
 import type { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
 import { DomEditCropHandles } from "./DomEditCropHandles";
@@ -23,10 +27,6 @@ const RESIZE_HANDLE_DEFS: Array<{
   { handle: "se", cursor: "nwse-resize", x: "right", y: "bottom" },
 ];
 
-// Visible dot is 9px; the pointer target is a 16px invisible square centered
-// on the corner so click targets don't shrink with the smaller dot.
-const RESIZE_HANDLE_HIT_PX = 16;
-
 type CropInset = { top: number; right: number; bottom: number; left: number };
 const NO_CROP_INSET: CropInset = { top: 0, right: 0, bottom: 0, left: 0 };
 
@@ -59,6 +59,7 @@ interface DomEditGroupChromeProps {
   groupOverlayItems: GroupOverlayItem[];
   groupBounds: OverlayRect;
   allowCanvasMovement: boolean;
+  allowBodyDrag: boolean;
   groupCanMove: boolean;
   gestures: GestureHandlers;
   onBoxMouseDown: (e: React.MouseEvent) => void;
@@ -71,6 +72,7 @@ export function DomEditGroupChrome({
   groupOverlayItems,
   groupBounds,
   allowCanvasMovement,
+  allowBodyDrag,
   groupCanMove,
   gestures,
   onBoxMouseDown,
@@ -100,10 +102,10 @@ export function DomEditGroupChrome({
           top: groupBounds.top,
           width: groupBounds.width,
           height: groupBounds.height,
-          cursor: canManipulate && groupCanMove ? "move" : "default",
+          cursor: !allowBodyDrag ? undefined : canManipulate && groupCanMove ? "move" : "default",
         }}
         onPointerDown={(e) => {
-          if (!canManipulate || e.shiftKey) return;
+          if (!canManipulate || e.shiftKey || !allowBodyDrag) return;
           gestures.startGroupDrag(e);
         }}
         onMouseDown={onBoxMouseDown}
@@ -117,6 +119,7 @@ interface DomEditSelectionChromeProps {
   selection: DomEditSelection;
   overlayRect: OverlayRect;
   allowCanvasMovement: boolean;
+  allowBodyDrag: boolean;
   cropOutlineInsetPx?: { top: number; right: number; bottom: number; left: number };
   boxRef: RefObject<HTMLDivElement | null>;
   boxChromeClass: string;
@@ -145,6 +148,7 @@ export function DomEditSelectionChrome({
   selection,
   overlayRect,
   allowCanvasMovement,
+  allowBodyDrag,
   cropOutlineInsetPx,
   boxRef,
   boxChromeClass,
@@ -197,8 +201,11 @@ export function DomEditSelectionChrome({
             width: overlayRect.width,
             height: overlayRect.height,
             clipPath: boxClipPath,
-            cursor:
-              canManipulate && selection.capabilities.canApplyManualOffset ? "move" : "default",
+            cursor: !allowBodyDrag
+              ? undefined
+              : canManipulate && selection.capabilities.canApplyManualOffset
+                ? "move"
+                : "default",
           }}
           onPointerDown={(e) => {
             // A second press opens the element's text for editing, and must be
@@ -211,7 +218,7 @@ export function DomEditSelectionChrome({
               e.stopPropagation();
               return;
             }
-            if (!canManipulate || e.shiftKey) return;
+            if (!allowBodyDrag || !canManipulate || e.shiftKey) return;
             if (selection.capabilities.canApplyManualOffset) {
               gestures.startGesture("drag", e);
               return;

package/src/components/editor/PreviewOverlayProvider.test.tsx

@@ -5,6 +5,7 @@ import { createRoot } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { GridOverlay } from "./GridOverlay";
 import { PreviewOverlayProvider } from "./PreviewOverlayProvider";
+import { SnapToolbar } from "./SnapToolbar";
 import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
 import { usePlayerStore } from "../../player/store/playerStore";
 
@@ -92,4 +93,22 @@ describe("PreviewOverlayProvider", () => {
 
     expect(usePreviewIframeStore.getState().iframe).toBe(ownerIframe);
   });
+
+  it("lets presses reach the preview beneath it, except on children that opt in", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(
+        <PreviewOverlayProvider iframe={null}>
+          <SnapToolbar />
+        </PreviewOverlayProvider>,
+      );
+    });
+
+    const layer = host.firstElementChild;
+    expect(layer?.classList.contains("pointer-events-none")).toBe(true);
+    expect(layer?.firstElementChild?.classList.contains("pointer-events-auto")).toBe(true);
+    act(() => root.unmount());
+  });
 });

package/src/components/editor/PreviewOverlayProvider.tsx

@@ -71,7 +71,7 @@ export function PreviewOverlayProvider({ iframe, children }: PreviewOverlayProvi
 
   return (
     <PreviewOverlayContext.Provider value={contextValue}>
-      <div ref={overlayRef} className="absolute inset-0">
+      <div ref={overlayRef} className="pointer-events-none absolute inset-0">
         {children}
       </div>
     </PreviewOverlayContext.Provider>

package/src/components/editor/SnapToolbar.tsx

@@ -65,7 +65,7 @@ export const SnapToolbar = memo(function SnapToolbar() {
 
   return (
     <div
-      className="absolute top-2 right-2 z-50 flex items-center gap-1"
+      className="pointer-events-auto absolute top-2 right-2 z-50 flex items-center gap-1"
       onPointerDown={(e) => e.stopPropagation()}
     >
       {motionPathCreateAvailable && (

package/src/components/editor/domEditOverlayGeometry.ts

@@ -9,6 +9,8 @@ import { hugRectForElement } from "./domEditOverlayCrop";
 import { composeElementTransform, type PlanarTransformOps } from "./domEditOverlayTransform";
 import { type OverlayMeasurePass, readThroughPass } from "./domEditOverlayMeasurePass";
 
+export const RESIZE_HANDLE_HIT_PX = 16;
+
 export interface OverlayRect {
   left: number;
   top: number;

package/src/components/nle/PreviewOverlays.tsx

@@ -90,7 +90,7 @@ export function PreviewOverlays({
         <TopologyLens iframeRef={previewIframeRef} activeCompositionPath={activeCompPath} />
         <CaptionOverlay iframeRef={previewIframeRef} />
         {/* Mode indicator + explicit exit */}
-        <div className="absolute top-2 left-1/2 -translate-x-1/2 z-60 flex items-center gap-2 rounded-full border border-studio-accent/40 bg-black/70 px-2.5 py-1">
+        <div className="pointer-events-auto absolute top-2 left-1/2 -translate-x-1/2 z-60 flex items-center gap-2 rounded-full border border-studio-accent/40 bg-black/70 px-2.5 py-1">
           <span className="h-1.5 w-1.5 rounded-full bg-studio-accent" aria-hidden="true" />
           <span className="text-2xs text-neutral-200">Editing captions</span>
           <button
@@ -104,7 +104,7 @@ export function PreviewOverlays({
         {captionSyncError && (
           <div
             role="alert"
-            className="absolute top-10 left-1/2 -translate-x-1/2 z-60 flex items-center gap-2 rounded-full border border-red-500/50 bg-red-950/90 px-2.5 py-1"
+            className="pointer-events-auto absolute top-10 left-1/2 -translate-x-1/2 z-60 flex items-center gap-2 rounded-full border border-red-500/50 bg-red-950/90 px-2.5 py-1"
           >
             <span className="text-2xs text-red-200">{captionSyncError}</span>
             <button
@@ -152,7 +152,7 @@ export function PreviewOverlays({
         <button
           type="button"
           onClick={enterCaptionMode}
-          className="absolute top-2 left-1/2 -translate-x-1/2 z-60 rounded-full border border-neutral-700 bg-black/60 px-2.5 py-1 text-2xs text-neutral-300 transition-colors hover:border-studio-accent/50 hover:text-studio-accent focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-studio-accent"
+          className="pointer-events-auto absolute top-2 left-1/2 -translate-x-1/2 z-60 rounded-full border border-neutral-700 bg-black/60 px-2.5 py-1 text-2xs text-neutral-300 transition-colors hover:border-studio-accent/50 hover:text-studio-accent focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-studio-accent"
         >
           Edit captions
         </button>

package/src/hooks/gsapResizeIntercept.test.ts

@@ -521,3 +521,43 @@ it("does not move a statically positioned element when a scale resize lands", as
   // And the live element ends on the drop point, not a drag away from it.
   expect(el.getBoundingClientRect().x).toBeCloseTo(603.3, 0);
 });
+
+function titleSelection(): DomEditSelection {
+  const el = document.createElement("h1");
+  el.id = "title";
+  document.body.append(el);
+  return { id: "title", selector: "#title", element: el } as DomEditSelection;
+}
+
+it("writes a plain size on an element whose only tween is a fade", async () => {
+  const fade = {
+    id: "#title-to-0-visual",
+    targetSelector: "#title",
+    propertyGroup: "visual",
+    method: "to",
+    properties: { opacity: 0.5 },
+    position: 0,
+    resolvedStart: 0,
+    duration: 10,
+  } as unknown as GsapAnimation;
+  const commitMutation = vi.fn();
+
+  const handled = await tryGsapResizeIntercept(
+    titleSelection(),
+    { width: 424, height: 237 },
+    [fade],
+    null,
+    commitMutation,
+  );
+
+  expect(handled).toMatchObject({ status: "persisted" });
+  const mutations = commitMutation.mock.calls.map((call) => call[1] as { type: string });
+  expect(mutations.filter((m) => /keyframe/i.test(m.type))).toEqual([]);
+  expect(mutations).toContainEqual({
+    type: "add",
+    targetSelector: "#title",
+    method: "set",
+    position: 0,
+    properties: { width: 424, height: 237 },
+  });
+});

package/src/hooks/gsapResizeIntercept.ts

@@ -148,12 +148,16 @@ export async function tryGsapResizeIntercept(
         ? (anim ?? findSizeSetAnimation(workingAnimations, sel, selection.element))
         : findSizeSetAnimation(workingAnimations, sel, selection.element);
 
-    // If the element is animated (has a real tween, not just a static size
-    // hold), keyframe the size at the playhead so other keyframes keep theirs —
-    // instead of a global set that resizes every frame.
+    // Keyframe the size only when a real tween already animates it, as move and
+    // rotate do; a fade or a slide on the element gets a plain size.
     if (resizeGroup === "size") {
       const animatedTween = pickClosestToPlayhead(
-        workingAnimations.filter((a) => !isInstantHold(a) && resolveTweenDuration(a) > 0),
+        workingAnimations.filter(
+          (a) =>
+            !isInstantHold(a) &&
+            resolveTweenDuration(a) > 0 &&
+            animationWritesAnyProperty(a, resizeProperties),
+        ),
       );
       if (animatedTween) {
         logResize("intercept-route", { route: "keyframed-size", tweenId: animatedTween.id });

package/src/index.ts

@@ -6,6 +6,8 @@ export { EditorShell } from "./components/EditorShell";
 export type { EditorShellProps } from "./components/EditorShell";
 export { NLEPreview } from "./components/nle/NLEPreview";
 export { DEFAULT_SHORTCUT_SECTIONS } from "./player/components/studioShortcuts";
+export { ShortcutsButton } from "./player/components/ShortcutsPanel";
+export type { ShortcutsButtonProps } from "./player/components/ShortcutsPanel";
 export type { ShortcutHint, ShortcutSection } from "./player/components/studioShortcuts";
 export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";
 export type { CompositionLevel } from "./components/nle/CompositionBreadcrumb";
@@ -49,6 +51,8 @@ export {
 } from "./player/components/TimelineParts";
 export { TimelineProvider, useTimelineContext } from "./player/components/TimelineProvider";
 export type { TimelineTheme } from "./player/components/timelineTheme";
+export { TRACK_H } from "./player/components/timelineLayout";
+export type { TimelineTrackPadding } from "./player/components/timelineLayout";
 
 // Clip content thumbnails: used by a host rendering its own timeline lane.
 export { AudioWaveform } from "./player/components/AudioWaveform";

package/src/player/components/PlayerControls.tsx

@@ -6,7 +6,7 @@ import { liveTime, usePlayerStore } from "../store/playerStore";
 import { trackStudioEvent } from "../../utils/studioTelemetry";
 import { Tooltip } from "../../components/ui";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import { ShortcutsPanel } from "./ShortcutsPanel";
+import { ShortcutsButton } from "./ShortcutsPanel";
 import type { ShortcutSection } from "./studioShortcuts";
 import { SpeedMenu } from "./SpeedMenu";
 import { VolumeControl } from "./VolumeControl";
@@ -185,10 +185,6 @@ export const PlayerControls = memo(function PlayerControls({
   const setAudioMuted = usePlayerStore.getState().setAudioMuted;
   const setAudioVolume = usePlayerStore.getState().setAudioVolume;
   const setLoopEnabled = usePlayerStore.getState().setLoopEnabled;
-  const inPoint = usePlayerStore((s) => s.inPoint);
-  const outPoint = usePlayerStore((s) => s.outPoint);
-  const setInPoint = usePlayerStore.getState().setInPoint;
-  const setOutPoint = usePlayerStore.getState().setOutPoint;
   const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
   const setTimeDisplayMode = usePlayerStore.getState().setTimeDisplayMode;
 
@@ -288,16 +284,7 @@ export const PlayerControls = memo(function PlayerControls({
           {onToggleFullscreen && (
             <FullscreenButton isFullscreen={isFullscreen} onToggleFullscreen={onToggleFullscreen} />
           )}
-          <ShortcutsPanel
-            disabled={disabled}
-            duration={duration}
-            inPoint={inPoint}
-            outPoint={outPoint}
-            setInPoint={setInPoint}
-            setOutPoint={setOutPoint}
-            onSeek={onSeek}
-            sections={shortcutSections}
-          />
+          <ShortcutsButton disabled={disabled} onSeek={onSeek} sections={shortcutSections} />
         </div>
       </div>
     </div>

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

@@ -2,10 +2,11 @@
 
 import React, { act, Profiler } from "react";
 import { describe, expect, it, vi } from "vitest";
-import { ShortcutsPanel } from "./ShortcutsPanel";
+import { ShortcutsButton, ShortcutsPanel } from "./ShortcutsPanel";
 import { PlayerControls } from "./PlayerControls";
 import { DEFAULT_SHORTCUT_SECTIONS, type ShortcutSection } from "./studioShortcuts";
 import { createHappyDomRootHarness } from "./testRootHarness";
+import { usePlayerStore } from "../store/playerStore";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -200,4 +201,35 @@ describe("ShortcutsPanel", () => {
     expect(errors.mock.calls.flat().join(" ")).not.toMatch(/same key/);
     errors.mockRestore();
   });
+
+  it("renders standalone for a host toolbar, reading the player store", () => {
+    const { duration, inPoint, requestSeek: storeSeek } = usePlayerStore.getState();
+    const requestSeek = vi.fn();
+    usePlayerStore.setState({ duration: 10, inPoint: 2, requestSeek });
+    try {
+      const host = document.createElement("div");
+      document.body.append(host);
+      act(() => {
+        mount(host).render(<ShortcutsButton sections={[{ title: "Host", hints: [] }]} />);
+      });
+      openPanel(host.querySelector<HTMLButtonElement>('button[aria-label="Shortcuts and tools"]')!);
+      expect(host.textContent).toContain("Host");
+      expect(host.textContent).toContain("00:02");
+
+      const input = host.querySelector<HTMLInputElement>('input[aria-label="Jump to frame"]')!;
+      act(() => {
+        Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!.call(
+          input,
+          "30",
+        );
+        input.dispatchEvent(new Event("input", { bubbles: true }));
+      });
+      act(() => {
+        input.form!.dispatchEvent(new Event("submit", { bubbles: true, cancelable: true }));
+      });
+      expect(requestSeek).toHaveBeenCalledWith(1);
+    } finally {
+      usePlayerStore.setState({ duration, inPoint, requestSeek: storeSeek });
+    }
+  });
 });

package/src/player/components/ShortcutsPanel.tsx

@@ -2,6 +2,7 @@ import { useState, useCallback, useEffect, useId, useRef, memo } from "react";
 import { formatTime, frameToSeconds } from "../lib/time";
 import { Tooltip } from "../../components/ui";
 import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
+import { usePlayerStore } from "../store/playerStore";
 import { DEFAULT_SHORTCUT_SECTIONS, type ShortcutSection } from "./studioShortcuts";
 
 interface ShortcutsPanelProps {
@@ -262,3 +263,28 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
     </div>
   );
 });
+
+export interface ShortcutsButtonProps {
+  sections?: readonly ShortcutSection[];
+  disabled?: boolean;
+  onSeek?: (time: number) => void;
+}
+
+export function ShortcutsButton({ sections, disabled = false, onSeek }: ShortcutsButtonProps) {
+  const duration = usePlayerStore((s) => s.duration);
+  const inPoint = usePlayerStore((s) => s.inPoint);
+  const outPoint = usePlayerStore((s) => s.outPoint);
+  const { setInPoint, setOutPoint, requestSeek } = usePlayerStore.getState();
+  return (
+    <ShortcutsPanel
+      disabled={disabled}
+      duration={duration}
+      inPoint={inPoint}
+      outPoint={outPoint}
+      setInPoint={setInPoint}
+      setOutPoint={setOutPoint}
+      onSeek={onSeek ?? requestSeek}
+      sections={sections}
+    />
+  );
+}

package/src/player/components/Timeline.trackPadding.test.tsx

@@ -0,0 +1,157 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Timeline } from "./Timeline";
+import { installTimelineMountEnv } from "./timelineMountTestEnv";
+import { usePlayerStore } from "../store/playerStore";
+import { CLIP_Y, RULER_H, TRACK_H, TRACKS_BOTTOM_PAD, TRACKS_TOP_PAD } from "./timelineLayout";
+import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
+import type { TimelineProps } from "./TimelineTypes";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+installTimelineMountEnv();
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+async function mountCanvas(trackPadding?: TimelineProps["trackPadding"]) {
+  usePlayerStore.setState({
+    duration: 10,
+    currentTime: 0,
+    timelineReady: true,
+    gsapAnimations: new Map(),
+    elements: [{ id: "card", label: "Card", tag: "div", start: 0, duration: 4, track: 0 }],
+  });
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  await act(async () => root.render(<Timeline trackPadding={trackPadding} />));
+  const canvas = Array.from(host.querySelectorAll<HTMLElement>("div.relative")).find(
+    (el) => el.style.height && el.style.width,
+  );
+  const height = canvas?.style.height;
+  const firstRowTop = host.querySelector<HTMLElement>('[data-timeline-row="0"]')?.style.top;
+  act(() => root.unmount());
+  return { height, firstRowTop };
+}
+
+describe("Timeline trackPadding", () => {
+  it("keeps Studio's pads by default", async () => {
+    expect(await mountCanvas()).toEqual({
+      height: `${RULER_H + TRACKS_TOP_PAD + TRACK_H + TRACKS_BOTTOM_PAD}px`,
+      firstRowTop: `${RULER_H + TRACKS_TOP_PAD}px`,
+    });
+  });
+
+  it("places the first row and sizes the canvas from the host's pads", async () => {
+    expect(await mountCanvas({ top: 0, bottom: TRACK_H })).toEqual({
+      height: `${RULER_H + 2 * TRACK_H}px`,
+      firstRowTop: `${RULER_H}px`,
+    });
+  });
+
+  // With no top pad, y = 96 is the middle of row 1; any reader still on the default pad sees row 0.
+  const ROW1_MID = RULER_H + TRACK_H + TRACK_H / 2;
+  const hostPads = { top: 0, bottom: TRACK_H };
+
+  async function mountThreeTracks(props: TimelineProps = {}) {
+    usePlayerStore.setState({
+      duration: 10,
+      currentTime: 0,
+      timelineReady: true,
+      gsapAnimations: new Map(),
+      selectedElementId: null,
+      selectedElementIds: new Set(),
+      elements: [0, 1, 2].map((track) => ({
+        id: `c${track}`,
+        key: `c${track}`,
+        domId: `c${track}`,
+        tag: "div",
+        start: 0,
+        duration: 2,
+        track,
+      })),
+    });
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    await act(async () => root.render(<Timeline trackPadding={hostPads} {...props} />));
+    const viewport = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]")!;
+    return { host, root, viewport };
+  }
+
+  const top = (el: Element | null | undefined) => (el as HTMLElement | null)?.style.top;
+
+  it("draws the gap strip, drop preview and insert line, and drops, on the host's rows", async () => {
+    const onAssetDrop = vi.fn();
+    const { host, root, viewport } = await mountThreeTracks({ onAssetDrop });
+    act(() => usePlayerStore.getState().setSelectedElementId("c1"));
+    expect(top(host.querySelector('[style*="--timeline-accent-faint"]'))).toBe(
+      `${RULER_H + TRACK_H + CLIP_Y}px`,
+    );
+
+    const drag = (type: string, clientY: number) => {
+      const event = new Event(type, { bubbles: true, cancelable: true });
+      Object.defineProperties(event, {
+        clientX: { value: 400 },
+        clientY: { value: clientY },
+        dataTransfer: {
+          value: {
+            types: [TIMELINE_ASSET_MIME],
+            files: [],
+            dropEffect: "none",
+            getData: (mime: string) => (mime === TIMELINE_ASSET_MIME ? '{"path":"a.png"}' : ""),
+          },
+        },
+      });
+      act(() => void viewport.dispatchEvent(event));
+    };
+    drag("dragover", ROW1_MID);
+    expect(top(host.querySelector('[data-testid="timeline-drop-preview"]'))).toBe(
+      `${RULER_H + TRACK_H + CLIP_Y}px`,
+    );
+    drag("dragover", RULER_H / 2);
+    expect(top(host.querySelector('[data-testid="timeline-insert-line"]'))).toBe(
+      `${RULER_H - 0.5}px`,
+    );
+    drag("drop", ROW1_MID);
+    expect(onAssetDrop).toHaveBeenCalledWith("a.png", expect.objectContaining({ track: 1 }));
+    act(() => root.unmount());
+  });
+
+  it("drags a clip onto the host's rows and opens a new track in the bottom pad", async () => {
+    const { host, root } = await mountThreeTracks({
+      onMoveElement: vi.fn(),
+      onResizeElement: vi.fn(),
+    });
+    const pointer = (target: EventTarget, type: string, clientY: number) =>
+      act(
+        () =>
+          void target.dispatchEvent(
+            new PointerEvent(type, {
+              bubbles: true,
+              button: 0,
+              pointerId: 1,
+              clientX: 400,
+              clientY,
+            }),
+          ),
+      );
+    const clip = host.querySelector('[data-clip][data-el-id="c0"]')!;
+    pointer(clip, "pointerdown", RULER_H + TRACK_H / 2);
+    pointer(window, "pointermove", ROW1_MID);
+    const ghost = Array.from(
+      host.querySelectorAll<HTMLElement>(".absolute.pointer-events-none"),
+    ).find((el) => el.style.zIndex === "30" && !el.dataset.testid);
+    expect(top(ghost)).toBe(`${RULER_H + TRACK_H + CLIP_Y}px`);
+    pointer(window, "pointermove", RULER_H + 3 * TRACK_H + TRACK_H / 2);
+    expect(top(host.querySelector('[data-testid="timeline-insert-line"]'))).toBe(
+      `${RULER_H + 3 * TRACK_H - 0.5}px`,
+    );
+    act(() => root.unmount());
+  });
+});

package/src/player/components/TimelineCanvas.tsx

@@ -2,16 +2,7 @@ import { memo } from "react";
 import { TimelineRulerPart } from "./TimelineRulerPart";
 import { PlayheadIndicator } from "./PlayheadIndicator";
 import { TimelinePlayheadLayer } from "./TimelinePlayheadLayer";
-import {
-  RULER_H,
-  CLIP_Y,
-  TRACKS_TOP_PAD,
-  TRACKS_BOTTOM_PAD,
-  TRACK_H,
-  PLAYHEAD_HEAD_W,
-  getTimelineRowTop,
-  getTimelineRowHeight,
-} from "./timelineLayout";
+import { RULER_H, CLIP_Y, TRACK_H, PLAYHEAD_HEAD_W, getTimelineRowHeight } from "./timelineLayout";
 import { getTimelinePlayheadTransform } from "./timelinePlayheadTransform";
 import { TimelineLanes } from "./TimelineLanes";
 import { TimelineGestureOverlay } from "./TimelineGestureOverlay";
@@ -49,8 +40,11 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
       <TimelineRulerPart />
 
       {/* Breathing room between the sticky ruler and the first track lane — the
-          top half of the CapCut-style padding (see TRACKS_TOP_PAD). */}
-      <div aria-hidden="true" style={{ height: props.rowsVirtualized ? 0 : TRACKS_TOP_PAD }} />
+          top half of the CapCut-style padding (see TimelineRowGeometry.padding). */}
+      <div
+        aria-hidden="true"
+        style={{ height: props.rowsVirtualized ? 0 : props.rowGeometry.padding.top }}
+      />
 
       <TimelineLanes
         {...props}
@@ -67,10 +61,13 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
         onRazorSplitAll={props.onRazorSplitAll}
       />
 
-      {/* Breathing room below the last track lane (~1.5 track heights) — a real
+      {/* Breathing room below the last track lane (1.5 tracks by default) — a real
           scrollable surface, so a clip can be dragged into the void to create a
-          new bottom track comfortably (see TRACKS_BOTTOM_PAD / getTimelineCanvasHeight). */}
-      <div aria-hidden="true" style={{ height: props.rowsVirtualized ? 0 : TRACKS_BOTTOM_PAD }} />
+          new bottom track comfortably (see TimelineRowGeometry.padding / canvasHeight). */}
+      <div
+        aria-hidden="true"
+        style={{ height: props.rowsVirtualized ? 0 : props.rowGeometry.padding.bottom }}
+      />
 
       {/* 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
@@ -91,7 +88,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
             key={`gap-${strip.kind}-${strip.track}-${gap.start}`}
             className="pointer-events-none absolute"
             style={{
-              top: getTimelineRowTop(rowIndex, props.rowHeights) + CLIP_Y,
+              top: props.rowGeometry.getRowTop(rowIndex) + CLIP_Y,
               left: props.contentOrigin + gap.start * props.pps,
               width: Math.max((gap.end - gap.start) * props.pps, 2),
               height: TRACK_H - CLIP_Y * 2,
@@ -109,7 +106,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
         <div
           className="absolute pointer-events-none"
           style={{
-            top: getTimelineRowTop(draggedRowIndex, props.rowHeights) + CLIP_Y,
+            top: props.rowGeometry.getRowTop(draggedRowIndex) + CLIP_Y,
             left: props.contentOrigin + draggedClip.previewStart * props.pps,
             width: Math.max(draggedClip.element.duration * props.pps, 4),
             height: draggedClipHeight,
@@ -129,7 +126,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
           data-testid="timeline-drop-preview"
           className="absolute pointer-events-none"
           style={{
-            top: getTimelineRowTop(dropRowIndex, props.rowHeights) + CLIP_Y,
+            top: props.rowGeometry.getRowTop(dropRowIndex) + CLIP_Y,
             left: props.contentOrigin + props.dropPreview.start * props.pps,
             width: DROP_PREVIEW_SECONDS * props.pps,
             height: TRACK_H - CLIP_Y * 2,
@@ -148,7 +145,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
           data-testid="timeline-insert-line"
           className="absolute pointer-events-none"
           style={{
-            top: getTimelineRowTop(insertLineRow, props.rowHeights) - 0.5,
+            top: props.rowGeometry.getRowTop(insertLineRow) - 0.5,
             left: props.contentOrigin,
             width: props.trackContentWidth,
             height: 1,

package/src/player/components/TimelineTypes.ts

@@ -3,6 +3,7 @@ import type { TimelineElement } from "../store/playerStore";
 import type { TimelineTimeRange } from "../store/rangeSelectionSlice";
 import type { TimelineDropCallbacks } from "./timelineCallbacks";
 import type { TimelineTheme } from "./timelineTheme";
+import type { TimelineTrackPadding } from "./timelineLayout";
 import type { TimelineEditOverrides } from "./useResolvedTimelineEditCallbacks";
 import type { TimelineStackingSyncProps } from "./useTimelineStackingSync";
 
@@ -35,4 +36,5 @@ export interface TimelineProps
   theme?: Partial<TimelineTheme>;
   showAudioEffects?: boolean;
   showKeyframes?: boolean;
+  trackPadding?: TimelineTrackPadding;
 }