@hyperframes/studio 0.8.92 → 0.8.94

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

@@ -247,6 +247,53 @@ describe("track-area breathing pad y-math", () => {
   });
 });
 
+describe("host track padding", () => {
+  const geometry = createTimelineRowGeometry([0, 1, 2], baseRows(3), { top: 0, bottom: TRACK_H });
+  // Row 1 with no top pad, but still row 0 if any reader keeps the default pad.
+  const yInRow1 = RULER_H + TRACK_H + 10;
+
+  it("moves the first row up and sizes the canvas from the host pads", () => {
+    expect(geometry.getRowTop(0)).toBe(RULER_H);
+    expect(getTimelineRowTop(1, geometry.rowHeights)).toBe(RULER_H + TRACK_H);
+    expect(getTimelineCanvasHeight(geometry.rowHeights)).toBe(RULER_H + 4 * TRACK_H);
+  });
+
+  it("maps a drag pointer y to the row under it", () => {
+    expect(Math.floor(geometry.getRowFromY(yInRow1))).toBe(1);
+    expect(Math.floor(getTimelineRowFromY(yInRow1, geometry.rowHeights))).toBe(1);
+  });
+
+  it("drops onto the row under the pointer, and a new track in the bottom pad", () => {
+    const drop = {
+      rectLeft: 0,
+      rectTop: 0,
+      scrollLeft: 0,
+      scrollTop: 0,
+      contentOrigin: GUTTER,
+      pixelsPerSecond: 100,
+      rowHeights: geometry.rowHeights,
+      trackOrder: [0, 1, 2],
+    };
+    expect(resolveTimelineAssetDrop(drop, GUTTER, yInRow1).track).toBe(1);
+    const inBottomPad = RULER_H + 3 * TRACK_H + TRACK_H / 2;
+    expect(resolveTimelineAssetDrop(drop, GUTTER, inBottomPad).track).toBe(3);
+  });
+
+  it("clamps a negative pad to 0 and replaces a non-finite one with the default", () => {
+    const odd = createTimelineRowGeometry([0], baseRows(1), { top: -20, bottom: Number.NaN });
+    expect(odd.padding).toEqual({ top: 0, bottom: TRACKS_BOTTOM_PAD });
+    expect(odd.getRowTop(0)).toBe(RULER_H);
+    expect(odd.canvasHeight).toBe(RULER_H + TRACK_H + TRACKS_BOTTOM_PAD);
+    const infinite = createTimelineRowGeometry([0], baseRows(1), { top: Infinity });
+    expect(infinite.padding.top).toBe(TRACKS_TOP_PAD);
+  });
+
+  it("keeps the default pads when a host passes none", () => {
+    const defaults = createTimelineRowGeometry([0], baseRows(1));
+    expect(defaults.padding).toEqual({ top: TRACKS_TOP_PAD, bottom: TRACKS_BOTTOM_PAD });
+  });
+});
+
 describe("getTimelineScrubTime", () => {
   const at = (clientX: number, duration = 10) =>
     getTimelineScrubTime({

package/src/player/components/timelineLayout.ts

@@ -55,9 +55,8 @@ export function getTimelineLaneTop(laneIndex: number): number {
   return TRACK_H + Math.max(0, Math.trunc(laneIndex)) * LANE_H;
 }
 /**
- * Breathing room INSIDE the scroll area (CapCut-style), threaded through every
- * track-row y computation via {@link getTimelineRowTop} — never inline a magic
- * offset; a track row's top is always ruler + top pad + cumulative row heights.
+ * Default breathing room INSIDE the scroll area (CapCut-style). A host overrides
+ * it per Timeline; rows always read TimelineRowGeometry.padding, never these.
  *
  * - TRACKS_TOP_PAD: empty space between the (sticky) ruler and the first track
  *   (~half a track height) so the first clip isn't jammed under the ruler.
@@ -66,6 +65,10 @@ export function getTimelineLaneTop(laneIndex: number): number {
  */
 export const TRACKS_TOP_PAD = 50;
 export const TRACKS_BOTTOM_PAD = Math.round(TRACK_H * 1.5);
+export interface TimelineTrackPadding {
+  top?: number;
+  bottom?: number;
+}
 /**
  * Breathing room LEFT of t=0 (CapCut-style), inside the scroll content — the
  * horizontal sibling of TRACKS_TOP_PAD: empty lane surface between the sticky
@@ -115,12 +118,17 @@ function validRowHeight(height: number | undefined): number {
   return height;
 }
 
+function validPad(pad: number | undefined, fallback: number): number {
+  return pad !== undefined && Number.isFinite(pad) ? Math.max(0, pad) : fallback;
+}
+
 export interface TimelineRowGeometry {
   readonly rowKeys: readonly number[];
   readonly rowHeights: readonly number[];
   /** Cumulative row boundaries, including the final bottom boundary. */
   readonly rowOffsets: readonly number[];
   readonly rowsHeight: number;
+  readonly padding: Readonly<Required<TimelineTrackPadding>>;
   readonly canvasHeight: number;
   getRowIndex(rowKey: number): number;
   getRowHeight(row: number): number;
@@ -141,7 +149,10 @@ const EMPTY_ROW_HEIGHTS: readonly number[] = Object.freeze([]);
 export function createTimelineRowGeometry(
   rowKeys: readonly number[],
   rowHeights: readonly number[],
+  padding: TimelineTrackPadding = {},
 ): TimelineRowGeometry {
+  const topPad = validPad(padding.top, TRACKS_TOP_PAD);
+  const bottomPad = validPad(padding.bottom, TRACKS_BOTTOM_PAD);
   const heights = Object.freeze(rowHeights.map(validRowHeight));
   const keys = Object.freeze(
     heights.map((_, row) => {
@@ -165,7 +176,7 @@ export function createTimelineRowGeometry(
     return (offsets[wholeRow] ?? 0) + (row - wholeRow) * getRowHeight(wholeRow);
   };
   const getRowFromY = (contentY: number) => {
-    const y = contentY - RULER_H - TRACKS_TOP_PAD;
+    const y = contentY - RULER_H - topPad;
     if (heights.length === 0) return y / TRACK_H;
     if (y < 0) return y / getRowHeight(0);
     const rowsHeight = offsets[heights.length] ?? 0;
@@ -188,10 +199,11 @@ export function createTimelineRowGeometry(
     rowHeights: heights,
     rowOffsets: offsets,
     rowsHeight: offsets.at(-1) ?? 0,
-    canvasHeight: RULER_H + TRACKS_TOP_PAD + (offsets.at(-1) ?? 0) + TRACKS_BOTTOM_PAD,
+    padding: Object.freeze({ top: topPad, bottom: bottomPad }),
+    canvasHeight: RULER_H + topPad + (offsets.at(-1) ?? 0) + bottomPad,
     getRowIndex: (rowKey) => rowIndexByKey.get(rowKey) ?? -1,
     getRowHeight,
-    getRowTop: (row) => RULER_H + TRACKS_TOP_PAD + getRowOffset(row),
+    getRowTop: (row) => RULER_H + topPad + getRowOffset(row),
     getRowFromY,
     getRowPositionFromY: (contentY) => {
       const rowFloat = getRowFromY(contentY);
@@ -204,7 +216,7 @@ export function createTimelineRowGeometry(
   return frozenGeometry;
 }
 
-/** Compatibility accessor; repeated calls for one height-array reuse one snapshot. */
+/** Compatibility accessor: a geometry's own rowHeights resolves back to it, pads included. */
 export function getTimelineRowGeometry(rowHeights: readonly number[]): TimelineRowGeometry {
   const cached = rowGeometryCache.get(rowHeights);
   if (cached) return cached;
@@ -228,10 +240,6 @@ export function getTimelineRowHeight(
   return validRowHeight(rowHeights[row]);
 }
 
-function getTimelineRowOffset(row: number, rowHeights: readonly number[]): number {
-  return getTimelineRowGeometry(rowHeights).getRowTop(row) - RULER_H - TRACKS_TOP_PAD;
-}
-
 /**
  * The y (content-space) of the top edge of track ROW index `row` (0 = first
  * displayed lane). The single source of truth for row->y: the ruler height plus
@@ -243,7 +251,7 @@ export function getTimelineRowTop(
   row: number,
   rowHeights: readonly number[] = EMPTY_ROW_HEIGHTS,
 ): number {
-  return RULER_H + TRACKS_TOP_PAD + getTimelineRowOffset(row, rowHeights);
+  return getTimelineRowGeometry(rowHeights).getRowTop(row);
 }
 
 /**
@@ -484,9 +492,8 @@ export function getTimelinePlaybackFollowScrollLeft(input: {
 }
 
 export function getTimelineCanvasHeight(rowHeights: readonly number[]): number {
-  // RULER_H + top pad + lanes + bottom pad. The old TIMELINE_SCROLL_BUFFER is
-  // subsumed by TRACKS_BOTTOM_PAD (which is larger), so the drag-into-void space
-  // below the last lane is real scrollable surface, not a hidden buffer.
+  // RULER_H + top pad + lanes + bottom pad, read from the geometry's padding.
+  // The drag-into-void space below the last lane is real scrollable surface.
   return getTimelineRowGeometry(rowHeights).canvasHeight;
 }
 

package/src/player/components/useTimelineProviderState.tsx

@@ -65,6 +65,7 @@ export function useTimelineProviderState({
   theme: themeOverrides,
   showAudioEffects = true,
   showKeyframes = true,
+  trackPadding,
   sessionEpoch = 0,
   previewIframeRef,
   onZIndexReorder,
@@ -143,6 +144,7 @@ export function useTimelineProviderState({
     gsapAnimations,
     selectedElementId,
     selectedElementIds,
+    trackPadding,
   );
   const timelineElementsRef = useRef(timelineElements);
   timelineElementsRef.current = timelineElements; // oxlint-disable-line react/refs -- event handlers read the latest elements

package/src/player/components/useTimelineTrackLayout.ts

@@ -10,6 +10,7 @@ import {
   TRACK_H,
   createTimelineRowGeometry,
   type TimelineRowGeometry,
+  type TimelineTrackPadding,
   trackHeights,
   type TimelineTrackHeightClip,
 } from "./timelineLayout";
@@ -164,7 +165,10 @@ function useTimelineRowHeights(
   selectedElementId: string | null,
   selectedElementIds: ReadonlySet<string>,
   groups: readonly TimelineTrackGroupInfo[],
+  trackPadding: TimelineTrackPadding | undefined,
 ) {
+  const padTop = trackPadding?.top;
+  const padBottom = trackPadding?.bottom;
   const expandedClipIds = usePlayerStore((s) => s.expandedClipIds);
   const expandedLaneOwnerIds = usePlayerStore((s) => s.expandedLaneOwnerIds);
   const { laneCounts, rowGeometry } = useMemo(() => {
@@ -207,9 +211,12 @@ function useTimelineRowHeights(
       rowGeometry: createTimelineRowGeometry(
         tracks.map(([track]) => track),
         rowHeights,
+        { top: padTop, bottom: padBottom },
       ),
     };
   }, [
+    padTop,
+    padBottom,
     expandedClipIds,
     expandedLaneOwnerIds,
     gsapAnimations,
@@ -233,6 +240,7 @@ export function useTimelineTrackLayout(
   gsapAnimations: Map<string, GsapAnimation[]>,
   selectedElementId: string | null,
   selectedElementIds: ReadonlySet<string>,
+  trackPadding?: TimelineTrackPadding,
 ) {
   const { tracks, trackStyles, trackOrder, groups, trackGroupOf } =
     useTimelineTrackDerivations(expandedElements);
@@ -244,6 +252,7 @@ export function useTimelineTrackLayout(
     selectedElementId,
     selectedElementIds,
     groups,
+    trackPadding,
   );
 
   return {
@@ -305,8 +314,8 @@ export function useTimelineDisplayLayout(
   const displayTrackOrder = useDisplayTrackOrder(draggedClip, trackOrder);
   const displayRowHeights = useDisplayRowHeights(displayTrackOrder, rowGeometry);
   const displayRowGeometry = useMemo(
-    () => createTimelineRowGeometry(displayTrackOrder, displayRowHeights),
-    [displayTrackOrder, displayRowHeights],
+    () => createTimelineRowGeometry(displayTrackOrder, displayRowHeights, rowGeometry.padding),
+    [displayTrackOrder, displayRowHeights, rowGeometry.padding],
   );
   return {
     displayTrackOrder,

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

@@ -171,4 +171,36 @@ describe("useTimelineVirtualRows", () => {
 
     act(() => root.unmount());
   });
+
+  it("offsets the mounted range by the geometry's own top pad", () => {
+    const keys = Array.from({ length: 1_000 }, (_, index) => index);
+    const topPad = 200 * 48;
+    const geometry = createTimelineRowGeometry(
+      keys,
+      keys.map(() => 48),
+      { top: topPad },
+    );
+    const scroll = createScrollElement(RULER_H + topPad + 300 * 48);
+    const scrollRef = { current: scroll };
+    let rows: ReturnType<typeof useTimelineVirtualRows> = [];
+
+    function Probe() {
+      rows = useTimelineVirtualRows({
+        enabled: true,
+        scrollRef,
+        viewport: viewport(scroll),
+        rowGeometry: geometry,
+        sessionEpoch: 1,
+        pinnedRowKeys: [],
+      });
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe)));
+    act(() => {});
+    expect(rows.some((row) => row.index === 300)).toBe(true);
+    expect(rows.some((row) => row.index === 500)).toBe(false);
+    act(() => root.unmount());
+  });
 });

package/src/player/components/useTimelineVirtualRows.ts

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, type RefObject } from "react";
 import { defaultRangeExtractor, useVirtualizer, type Range } from "@tanstack/react-virtual";
 import { TIMELINE_VIEWPORT_BUDGETS } from "../lib/timelineViewportBudgets";
 import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
-import { RULER_H, TRACKS_TOP_PAD, type TimelineRowGeometry } from "./timelineLayout";
+import { RULER_H, type TimelineRowGeometry } from "./timelineLayout";
 
 export interface TimelineVirtualRow {
   readonly index: number;
@@ -84,7 +84,7 @@ export function useTimelineVirtualRows({
     getItemKey,
     overscan: TIMELINE_VIEWPORT_BUDGETS.rowOverscanPerSide,
     rangeExtractor,
-    scrollMargin: RULER_H + TRACKS_TOP_PAD,
+    scrollMargin: RULER_H + rowGeometry.padding.top,
     initialRect: { width: viewport.clientWidth, height: viewport.clientHeight },
     initialOffset,
   });

package/src/player/hooks/useTimelinePlayer.seek.test.ts

@@ -353,7 +353,11 @@ describe("useTimelinePlayer seek keepPlaying option (#834)", () => {
 describe("useTimelinePlayer RAF loop wrap-around", () => {
   type SeekCall = { time: number; options?: { keepPlaying?: boolean } };
 
-  function attachInstrumentedAdapter(api: ReturnType<typeof useTimelinePlayer>, duration = 30) {
+  function attachInstrumentedAdapter(
+    api: ReturnType<typeof useTimelinePlayer>,
+    duration = 30,
+    hooks: object = {},
+  ) {
     let currentTime = 0;
     let playing = false;
     const seekCalls: SeekCall[] = [];
@@ -377,6 +381,7 @@ describe("useTimelinePlayer RAF loop wrap-around", () => {
     };
     attachIframeWindow(api, {
       __player: adapter,
+      __hf: hooks,
       postMessage: () => {},
       scrollTo: () => {},
       addEventListener: () => {},
@@ -446,6 +451,29 @@ describe("useTimelinePlayer RAF loop wrap-around", () => {
     }
   });
 
+  it("tells the preview where the loop wraps to while it plays, and that it stopped looping", () => {
+    const raf = installRafCapture();
+    try {
+      const { api, root } = renderTimelinePlayerHarness();
+      const setLoopStart = vi.fn();
+      const { adapter } = attachInstrumentedAdapter(api, 30, { setLoopStart });
+      act(() => {
+        usePlayerStore.getState().setInPoint(2);
+        usePlayerStore.getState().setOutPoint(5);
+        api.play();
+      });
+      adapter.setTime(3);
+      act(() => void raf.flushOne());
+      expect(setLoopStart).toHaveBeenLastCalledWith(2);
+      act(() => usePlayerStore.getState().setLoopEnabled(false));
+      act(() => void raf.flushOne());
+      expect(setLoopStart).toHaveBeenLastCalledWith(null);
+      unmountWithAct(root);
+    } finally {
+      raf.restore();
+    }
+  });
+
   it("does not seek and pauses cleanly when forward playback reaches the end without loop", () => {
     const raf = installRafCapture();
     try {

package/src/player/hooks/useTimelinePlayer.ts

@@ -152,12 +152,18 @@ export function useTimelinePlayer({
     [],
   );
 
+  const setLoopStart = useCallback((seconds: number | null) => {
+    try {
+      (iframeRef.current?.contentWindow as IframeWindow | null)?.__hf?.setLoopStart?.(seconds);
+    } catch {}
+  }, []);
   const { startRAFLoop, stopRAFLoop, stopReverseLoop } = useTimelinePlayerLoop({
     rafRef,
     reverseRafRef,
     getAdapter,
     setCurrentTime,
     setIsPlaying,
+    setLoopStart,
   });
 
   const applyPlaybackRate = useCallback((rate: number) => {

package/src/player/hooks/useTimelinePlayerLoop.ts

@@ -22,6 +22,7 @@ interface UseTimelinePlayerLoopParams {
   getAdapter: () => PlaybackAdapter | null;
   setCurrentTime: (v: number) => void;
   setIsPlaying: (v: boolean) => void;
+  setLoopStart: (seconds: number | null) => void;
 }
 
 interface UseTimelinePlayerLoopResult {
@@ -36,6 +37,7 @@ export function useTimelinePlayerLoop({
   getAdapter,
   setCurrentTime,
   setIsPlaying,
+  setLoopStart,
 }: UseTimelinePlayerLoopParams): UseTimelinePlayerLoopResult {
   const stopReverseLoop = useCallback(() => {
     cancelAnimationFrame(reverseRafRef.current);
@@ -55,8 +57,10 @@ export function useTimelinePlayerLoop({
         const rawLoopStart = inPoint !== null ? inPoint : 0;
         const loopEnd = rawLoopStart < rawLoopEnd ? rawLoopEnd : dur;
         const loopStart = rawLoopStart < rawLoopEnd ? rawLoopStart : 0;
+        const looping = usePlayerStore.getState().loopEnabled && dur > 0;
+        setLoopStart(looping ? loopStart : null);
         if (time >= loopEnd) {
-          if (usePlayerStore.getState().loopEnabled && dur > 0) {
+          if (looping) {
             // keepPlaying skips the adapter's implicit pause; play() below is then a no-op.
             adapter.seek(loopStart, { keepPlaying: true });
             liveTime.notify(loopStart);
@@ -75,7 +79,7 @@ export function useTimelinePlayerLoop({
       rafRef.current = requestAnimationFrame(tick);
     };
     rafRef.current = requestAnimationFrame(tick);
-  }, [rafRef, getAdapter, setCurrentTime, setIsPlaying]);
+  }, [rafRef, getAdapter, setCurrentTime, setIsPlaying, setLoopStart]);
 
   const stopRAFLoop = useCallback(() => {
     cancelAnimationFrame(rafRef.current);

package/src/player/lib/playbackTypes.ts

@@ -69,5 +69,6 @@ export type IframeWindow = Window & {
   __hf?: {
     leasePausedMedia?: (el: HTMLMediaElement) => void;
     releasePausedMedia?: (el: HTMLMediaElement) => void;
+    setLoopStart?: (seconds: number | null) => void;
   };
 };