@hyperframes/studio 0.8.84 → 0.8.86

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

@@ -0,0 +1,65 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { Timeline } from "./Timeline";
+import { liveTime, usePlayerStore } from "../store/playerStore";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+class MockResizeObserver {
+  constructor(private readonly callback: ResizeObserverCallback) {}
+  observe(target: Element) {
+    this.callback([{ target } as ResizeObserverEntry], this as unknown as ResizeObserver);
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+const originalResizeObserver = globalThis.ResizeObserver;
+const originalClientWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "clientWidth");
+
+beforeAll(() => {
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  Object.defineProperty(HTMLElement.prototype, "clientWidth", {
+    configurable: true,
+    get: () => 900,
+  });
+});
+
+afterAll(() => {
+  globalThis.ResizeObserver = originalResizeObserver;
+  if (originalClientWidth)
+    Object.defineProperty(HTMLElement.prototype, "clientWidth", originalClientWidth);
+  document.body.innerHTML = "";
+});
+
+const clips = [{ id: "intro", tag: "div", start: 2, duration: 10, track: 0 }];
+const needle = (host: HTMLElement) =>
+  host.querySelector<HTMLElement>("[data-timeline-playhead-layer] > div")?.style.transform;
+
+describe("Timeline playhead across a composition switch", () => {
+  it("places the remounted playhead at the restored time", async () => {
+    usePlayerStore.setState({ duration: 20, currentTime: 0, timelineReady: true, elements: clips });
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    await act(async () => root.render(<Timeline />));
+    const atZero = needle(host);
+    await act(async () => usePlayerStore.getState().setCurrentTime(4));
+    const atFour = needle(host);
+    expect(atFour).not.toBe(atZero);
+
+    await act(async () => usePlayerStore.setState({ elements: [], timelineReady: false }));
+    await act(async () => usePlayerStore.getState().setCurrentTime(1.5));
+    await act(async () => {
+      usePlayerStore.getState().setCurrentTime(4);
+      liveTime.notify(4);
+    });
+    await act(async () => usePlayerStore.setState({ elements: clips, timelineReady: true }));
+
+    expect(needle(host)).toBe(atFour);
+    act(() => root.unmount());
+  });
+});

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

@@ -213,7 +213,9 @@ describe("Timeline provider boundary", () => {
         100,
       ).start,
     ).toBe(10);
-    expect(getTimelineFitPps(640, 11, GUTTER)).toBe(10.1);
+    expect(getTimelineFitPps(640, 11, GUTTER)).toBeCloseTo(
+      (640 - GUTTER - 2) / (11 * FIT_ZOOM_HEADROOM),
+    );
 
     act(() => root.unmount());
   });
@@ -313,7 +315,7 @@ describe("Timeline provider boundary", () => {
     expect(rulerX).toBe(LABEL_COL_W + GUTTER + 1000);
     expect(collapsedHeader.textContent).toContain("Outro");
     expect(getTimelineFitPps(640, 20, LABEL_COL_W + GUTTER)).toBeCloseTo(
-      (640 - (LABEL_COL_W + GUTTER) - 2) / MIN_TIMELINE_EXTENT_S,
+      (640 - (LABEL_COL_W + GUTTER) - 2) / (20 * FIT_ZOOM_HEADROOM),
     );
     expect(
       resolveTimelineAssetDrop(
@@ -948,15 +950,13 @@ describe("shouldAutoScrollTimeline", () => {
   });
 });
 
-describe("getTimelineFitPps (min 60s extent + fit headroom)", () => {
+describe("getTimelineFitPps (fit headroom, 60s floor only without a duration)", () => {
   const viewport = 632; // usable width = 632 - GUTTER - TRACKS_LEFT_PAD - 2
 
-  it("computes fit pps against the 60s floor for short compositions", () => {
-    // A 10s comp maps 60s onto the viewport → the comp takes ~1/6 of the width.
-    // (10 * 1.2 = 12s of headroom-padded content is still under the 60s floor.)
-    const pps = getTimelineFitPps(viewport, 10, GUTTER + TRACKS_LEFT_PAD);
-    expect(pps).toBeCloseTo((viewport - (GUTTER + TRACKS_LEFT_PAD) - 2) / MIN_TIMELINE_EXTENT_S);
-    expect(10 * pps).toBeCloseTo((viewport - (GUTTER + TRACKS_LEFT_PAD) - 2) / 6);
+  it("fits a short film to the width, not to a 60s ruler", () => {
+    const usable = viewport - (GUTTER + TRACKS_LEFT_PAD) - 2;
+    const pps = getTimelineFitPps(viewport, 17, GUTTER + TRACKS_LEFT_PAD);
+    expect(17 * pps).toBeCloseTo(usable / FIT_ZOOM_HEADROOM);
   });
 
   it("fits duration * FIT_ZOOM_HEADROOM (not the bare duration) for long compositions", () => {
@@ -1000,11 +1000,10 @@ describe("getTimelineFitPps (min 60s extent + fit headroom)", () => {
 });
 
 describe("getTimelineDisplayContentWidth", () => {
-  it("always spans at least MIN_TIMELINE_EXTENT_S seconds of content", () => {
-    // 10s of content at 20 pps = 200px; the floor keeps 60s (1200px) rendered.
+  it("spans MIN_TIMELINE_EXTENT_S seconds while the duration is unknown", () => {
     expect(
       getTimelineDisplayContentWidth({
-        trackContentWidth: 200,
+        effectiveDuration: 0,
         viewportWidth: 400,
         contentOrigin: GUTTER,
         pps: 20,
@@ -1012,10 +1011,24 @@ describe("getTimelineDisplayContentWidth", () => {
     ).toBe(MIN_TIMELINE_EXTENT_S * 20);
   });
 
-  it("still fills the viewport when that is larger than the 60s floor", () => {
+  it("renders a short film at fit exactly as wide as the viewport, so fit never scrolls", () => {
+    const viewport = 632;
+    const origin = GUTTER + TRACKS_LEFT_PAD;
+    const pps = getTimelineFitPps(viewport, 17, origin);
+    expect(
+      getTimelineDisplayContentWidth({
+        effectiveDuration: 17,
+        viewportWidth: viewport,
+        contentOrigin: origin,
+        pps,
+      }),
+    ).toBeCloseTo(viewport - origin - 2);
+  });
+
+  it("still fills the viewport when that is larger than the fit span", () => {
     expect(
       getTimelineDisplayContentWidth({
-        trackContentWidth: 200,
+        effectiveDuration: 40,
         viewportWidth: 2000,
         contentOrigin: GUTTER + TRACKS_LEFT_PAD,
         pps: 5,
@@ -1026,7 +1039,7 @@ describe("getTimelineDisplayContentWidth", () => {
   it("tracks a drag ghost past every other bound (drag-to-extend)", () => {
     expect(
       getTimelineDisplayContentWidth({
-        trackContentWidth: 500,
+        effectiveDuration: 100,
         viewportWidth: 400,
         contentOrigin: GUTTER,
         pps: 5,
@@ -1038,7 +1051,7 @@ describe("getTimelineDisplayContentWidth", () => {
   it("tracks a resize (trim) ghost past every other bound (trim-to-extend)", () => {
     expect(
       getTimelineDisplayContentWidth({
-        trackContentWidth: 500,
+        effectiveDuration: 100,
         viewportWidth: 400,
         contentOrigin: GUTTER,
         pps: 5,
@@ -1047,15 +1060,15 @@ describe("getTimelineDisplayContentWidth", () => {
     ).toBe(4200);
   });
 
-  it("keeps long content authoritative", () => {
+  it("keeps the fit headroom past the end when zoomed in", () => {
     expect(
       getTimelineDisplayContentWidth({
-        trackContentWidth: 9000,
+        effectiveDuration: 180,
         viewportWidth: 400,
         contentOrigin: GUTTER,
         pps: 50,
       }),
-    ).toBe(9000);
+    ).toBeCloseTo(180 * FIT_ZOOM_HEADROOM * 50);
   });
 });
 

package/src/player/components/TimelineLanes.tsx

@@ -134,9 +134,8 @@ export function TimelineLanes({
     focusedTargetId,
     rowGeometry,
     scrollRef,
-    onToggleRow: (row) => {
-      if (row.elementId) toggleClipExpandedTracked(row.elementId);
-    },
+    onToggleRow: (row) => row.elementId && toggleClipExpandedTracked(row.elementId),
+    onDrillDown,
   });
   return (
     <div

package/src/player/components/timelineKeyboardNavigation.ts

@@ -49,6 +49,7 @@ export interface TimelineLogicalItem {
   elementId: string;
   /** The item's time anchor. Clips use their midpoint; ease controls use the segment midpoint. */
   time: number;
+  element?: TimelineElement;
   keyframeTarget?: TimelineKeyframeTarget;
 }
 
@@ -113,6 +114,7 @@ function clipItems(rowId: string, elements: readonly TimelineElement[]): Timelin
         rowId,
         elementId: id,
         time: element.start + element.duration / 2,
+        element,
       };
     });
 }

package/src/player/components/timelineLayout.ts

@@ -281,57 +281,51 @@ export function getTimelineInsertBoundaryBand(rowHeight: number): number {
  * rendered width (see Timeline.tsx displayContentWidth).
  */
 export const DRAG_EXTEND_MARGIN_PX = 160;
-/**
- * The rendered timeline always spans at least this many seconds of ruler +
- * track lanes, even when the composition is shorter — the empty space on the
- * right is a real, drag/drop-enabled surface (clips can be moved into it; the
- * composition grows on commit, content-driven). In fit mode the fit pps is
- * derived against this floor, so a 10s comp renders as ~1/6 of the viewport
- * with 60s of ruler after it.
- */
+/** The span the timeline maps while the composition's duration is unknown or 0. */
 export const MIN_TIMELINE_EXTENT_S = 60;
 /**
  * Fit-mode headroom (CapCut-style): "fit" maps `duration * 1.2` — not the bare
  * duration — onto the viewport, so the composition ends at ~83% of the width
  * and the trailing ~17% stays empty ruler + droppable lane surface (room to
  * drag clips past the current end without first zooming out). Applied ONLY
- * inside {@link getTimelineFitPps}, the single fit-pps source, so the ruler,
- * lanes, playhead, marquee, and drag math all inherit it consistently. Manual
+ * inside {@link getTimelineFitSpan}, which fit pps and the drawn width share, so
+ * the ruler, lanes, playhead, marquee, and drag math inherit it. Manual
  * zoom percentages stay defined relative to this fit basis (100% == fit).
  */
 export const FIT_ZOOM_HEADROOM = 1.2;
 
 /* ── Tick generation ──────────────────────────────────────────────── */
 /* ── Width / duration derivation ──────────────────────────────────── */
+/** Seconds the timeline maps: the composition plus FIT_ZOOM_HEADROOM, or the floor while its duration is unknown. */
+function getTimelineFitSpan(effectiveDuration: number): number {
+  return Number.isFinite(effectiveDuration) && effectiveDuration > 0
+    ? effectiveDuration * FIT_ZOOM_HEADROOM
+    : MIN_TIMELINE_EXTENT_S;
+}
+
 /**
  * Fit-mode pixels-per-second: fill the viewport with the composition plus
  * FIT_ZOOM_HEADROOM trailing headroom (CapCut-style — the comp never slams
- * into the right edge), and never map fewer than MIN_TIMELINE_EXTENT_S
- * seconds onto it — a short comp takes a fraction of the width and the
- * remaining ruler runs to 1:00.
- * Manual zoom multiplies this base, so the floor only anchors the default.
+ * into the right edge). Manual zoom multiplies this base.
  */
 export function getTimelineFitPps(
   viewportWidth: number,
   effectiveDuration: number,
   contentOrigin: number,
 ): number {
-  const safeDuration =
-    Number.isFinite(effectiveDuration) && effectiveDuration > 0 ? effectiveDuration : 0;
-  const span = Math.max(safeDuration * FIT_ZOOM_HEADROOM, MIN_TIMELINE_EXTENT_S);
   if (!Number.isFinite(viewportWidth) || viewportWidth <= contentOrigin) return 100;
-  return (viewportWidth - contentOrigin - 2) / span;
+  return (viewportWidth - contentOrigin - 2) / getTimelineFitSpan(effectiveDuration);
 }
 
 /**
  * The rendered timeline extent in px. Always covers, whichever is largest:
- * the actual clip content, the visible viewport (no dead black after short
+ * the visible viewport (no dead black after short
  * content — CapCut-style), a live drag or resize ghost plus the auto-scroll
- * margin (drag/trim-to-extend), and the MIN_TIMELINE_EXTENT_S floor. Only the
+ * margin (drag/trim-to-extend), and the fit span at this zoom. Only the
  * RENDERED extent grows; clip positions/durations are untouched.
  */
 export function getTimelineDisplayContentWidth(input: {
-  trackContentWidth: number;
+  effectiveDuration: number;
   viewportWidth: number;
   contentOrigin: number;
   pps: number;
@@ -340,11 +334,10 @@ export function getTimelineDisplayContentWidth(input: {
 }): number {
   const safePps = Number.isFinite(input.pps) ? Math.max(input.pps, 0) : 0;
   return Math.max(
-    input.trackContentWidth,
     input.viewportWidth - input.contentOrigin - 2,
     input.dragGhostEndPx ?? 0,
     input.resizeGhostEndPx ?? 0,
-    MIN_TIMELINE_EXTENT_S * safePps,
+    getTimelineFitSpan(input.effectiveDuration) * safePps,
   );
 }
 

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

@@ -115,3 +115,108 @@ describe("useTimelineGeometry restore-scroll effect", () => {
     expect(scroll.scrollLeft).toBe(300);
   });
 });
+
+function ScaleProbe({
+  duration,
+  width = 1200,
+  clips = duration > 0,
+  seen,
+}: {
+  duration: number;
+  width?: number;
+  clips?: boolean;
+  seen: { pps: number; fitPps: number };
+}) {
+  const ppsRef = useRef(0);
+  const fitPpsRef = useRef(0);
+  const zoomMode = usePlayerStore((s) => s.zoomMode);
+  const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
+  const { pps, fitPps } = useTimelineGeometry({
+    viewportWidth: width,
+    effectiveDuration: duration,
+    zoomMode,
+    manualZoomPercent,
+    ppsRef,
+    fitPpsRef,
+    draggedClip: null,
+    resizingClip: null,
+    expandedElements: clips ? [{ ...element, start: 0, duration }] : [],
+    isDragging: useRef(false),
+    scrollRef: useRef<HTMLDivElement>(null),
+    lastScrollLeftRef: useRef(0),
+    contentOrigin: 32,
+  });
+  seen.pps = pps;
+  seen.fitPps = fitPps;
+  return null;
+}
+
+describe("useTimelineGeometry keeps the scale when only the length changes", () => {
+  const seen = { pps: 0, fitPps: 0 };
+  const renderAt = (duration: number, width?: number, clips?: boolean) =>
+    act(() =>
+      root.render(<ScaleProbe duration={duration} width={width} clips={clips} seen={seen} />),
+    );
+  const within = (pps: number) => Math.abs(seen.pps - pps) < seen.fitPps * 0.005;
+
+  it("keeps a short film's clips the same size when the first edit lengthens it", () => {
+    usePlayerStore.setState({ zoomMode: "fit", manualZoomPercent: 100 });
+    renderAt(17);
+    const before = seen.pps;
+    act(() => usePlayerStore.getState().pinTimelineZoom(seen.pps, seen.fitPps));
+    renderAt(25);
+    expect(seen.fitPps).toBeLessThan(before);
+    expect(within(before)).toBe(true);
+  });
+
+  it("keeps the scale in manual zoom when a later edit shortens the film", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 150 });
+    renderAt(17);
+    const before = seen.pps;
+    renderAt(12);
+    expect(seen.fitPps).toBeGreaterThan(before / 1.5);
+    expect(within(before)).toBe(true);
+  });
+
+  it("still scales with the fit width when the timeline is resized, and when the length first loads", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 150 });
+    renderAt(0);
+    renderAt(17);
+    expect(seen.pps).toBeCloseTo(seen.fitPps * 1.5);
+    renderAt(17, 900);
+    expect(seen.pps).toBeCloseTo(seen.fitPps * 1.5);
+  });
+
+  it("refits when another composition opens, which empties the clips first", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 150 });
+    renderAt(120);
+    renderAt(120, undefined, false);
+    renderAt(5);
+    expect(seen.pps).toBeCloseTo(seen.fitPps * 1.5);
+  });
+
+  it("refits after a project reset, which empties the clips and the length", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 150 });
+    renderAt(120);
+    renderAt(0);
+    renderAt(17);
+    expect(seen.pps).toBeCloseTo(seen.fitPps * 1.5);
+  });
+
+  it("keeps a lengthened film's scale near the maximum zoom", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 100_000 });
+    renderAt(17);
+    const before = seen.pps;
+    expect(before).toBeLessThan(seen.fitPps * 1000);
+    renderAt(25);
+    expect(within(before)).toBe(true);
+  });
+
+  it("leaves the manual zoom alone in fit mode", () => {
+    usePlayerStore.setState({ zoomMode: "fit", manualZoomPercent: 100 });
+    renderAt(17);
+    renderAt(25);
+    expect(seen.pps).toBe(seen.fitPps);
+    expect(usePlayerStore.getState().manualZoomPercent).toBe(100);
+  });
+});

package/src/player/components/useTimelineGeometry.ts

@@ -1,6 +1,6 @@
-import { useEffect, useRef, type RefObject } from "react";
+import { useEffect, useLayoutEffect, useRef, type RefObject } from "react";
 import { usePlayerStore, type TimelineElement, type ZoomMode } from "../store/playerStore";
-import { getTimelinePixelsPerSecond } from "./timelineZoom";
+import { computePinnedZoomPercent, getTimelinePixelsPerSecond } from "./timelineZoom";
 import {
   DRAG_EXTEND_MARGIN_PX,
   getTimelineDisplayContentWidth,
@@ -43,12 +43,9 @@ export function useTimelineGeometry({
   lastScrollLeftRef,
   contentOrigin,
 }: UseTimelineGeometryInput) {
-  // Fit pps maps at least MIN_TIMELINE_EXTENT_S onto the viewport, so short
-  // comps show a 60s ruler with usable empty space (see getTimelineFitPps).
   const fitPps = getTimelineFitPps(viewportWidth, effectiveDuration, contentOrigin);
   const pps = getTimelinePixelsPerSecond(fitPps, zoomMode, manualZoomPercent);
   ppsRef.current = pps;
-  const trackContentWidth = Math.max(0, effectiveDuration * pps);
   // Drag-to-extend: while a clip is dragged, keep the rendered extent a margin
   // past the ghost's end. Holding the pointer in the right edge zone then keeps
   // auto-scroll stepping (scrollWidth grows with the ghost), so the timeline
@@ -65,12 +62,12 @@ export function useTimelineGeometry({
   const resizeGhostEndPx = resizingClip?.started
     ? (resizingClip.previewStart + resizingClip.previewDuration) * pps + DRAG_EXTEND_MARGIN_PX
     : 0;
-  // The timeline canvas always fills at least the viewport width AND the
-  // MIN_TIMELINE_EXTENT_S floor: the ruler + empty track lanes keep going into
+  // The timeline canvas always fills at least the viewport width AND the fit
+  // span at this zoom: the ruler + empty track lanes keep going into
   // the space instead of leaving dead black — CapCut-style. Only the RENDERED
   // extent grows; clip positions/durations are untouched.
   const displayContentWidth = getTimelineDisplayContentWidth({
-    trackContentWidth,
+    effectiveDuration,
     viewportWidth,
     contentOrigin,
     pps,
@@ -108,8 +105,7 @@ export function useTimelineGeometry({
     return () => cancelAnimationFrame(raf);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [expandedElements, zoomMode]);
-  // Publish the live scale so edit handlers OUTSIDE <Timeline> (the keyboard-delete
-  // path) can pin the zoom via pinTimelineZoomToCurrent without threading geometry.
+  // Publish the live scale for readers outside <Timeline> (the toolbar's zoom controls).
   // In a useEffect (not the render body) so React-18 concurrent replay — Suspense
   // retry, transitions, StrictMode double-invoke — can't double-publish. The write is
   // idempotent (same pps/fitPps → same fields), so this is behavior-preserving; the
@@ -117,6 +113,18 @@ export function useTimelineGeometry({
   useEffect(() => {
     usePlayerStore.getState().setTimelineScale(pps, fitPps);
   }, [pps, fitPps]);
+  // In manual zoom a length change keeps the on-screen scale instead of rescaling every
+  // clip, whichever edit caused it. A composition switch empties the clips first, so it refits.
+  const hasClips = expandedElements.length > 0;
+  const lastScale = useRef({ effectiveDuration, pps, hasClips });
+  useLayoutEffect(() => {
+    const last = lastScale.current;
+    lastScale.current = { effectiveDuration, pps, hasClips };
+    if (zoomMode !== "manual" || !last.hasClips || !hasClips) return;
+    if (last.effectiveDuration === effectiveDuration) return;
+    // Before paint; the percent is clamped against the new fit, not the store's last published one.
+    usePlayerStore.setState({ manualZoomPercent: computePinnedZoomPercent(last.pps, fitPps) });
+  });
 
   return {
     pps,

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

@@ -3,7 +3,7 @@
 import React, { act, useRef } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { usePlayerStore } from "../store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { createTimelineRowGeometry } from "./timelineLayout";
 import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
 import { useTimelineKeyboardActor } from "./useTimelineKeyboardActor";
@@ -57,6 +57,7 @@ interface HarnessProps {
   logicalRows?: readonly TimelineLogicalRow[];
   rowHeights?: readonly number[];
   onToggleRow?: (target: TimelineLogicalRow) => void;
+  onDrillDown?: (element: TimelineElement) => void;
 }
 
 function Harness({
@@ -64,6 +65,7 @@ function Harness({
   logicalRows = rows,
   rowHeights = logicalRows.map(() => 48),
   onToggleRow = vi.fn(),
+  onDrillDown,
 }: HarnessProps) {
   const scrollRef = useRef<HTMLDivElement>(null);
   const keyboard = useTimelineKeyboardActor({
@@ -75,6 +77,7 @@ function Harness({
     ),
     scrollRef,
     onToggleRow,
+    onDrillDown,
   });
   return (
     <div ref={scrollRef} onFocus={keyboard.onFocus} onKeyDown={keyboard.onKeyDown}>
@@ -228,6 +231,26 @@ describe("useTimelineKeyboardActor", () => {
     act(() => root.unmount());
   });
 
+  it("drills into a composition clip on Enter and leaves a plain clip alone", () => {
+    const scene = { id: "scene", tag: "div", start: 0, duration: 2, track: 1 };
+    const withElements = rows.map((row, index) => ({
+      ...row,
+      items: row.items.map((item) => ({
+        ...item,
+        element: index === 0 ? { ...scene, compositionSrc: "scene.html" } : scene,
+      })),
+    }));
+    const onDrillDown = vi.fn();
+    const { host, root } = renderHarness({ logicalRows: withElements, onDrillDown });
+    const composition = host.querySelector<HTMLElement>('[data-timeline-focus-id="clip-1"]')!;
+    const plain = host.querySelector<HTMLElement>('[data-timeline-focus-id="clip-2"]')!;
+    expect(key(plain, "Enter").defaultPrevented).toBe(false);
+    expect(onDrillDown).not.toHaveBeenCalled();
+    expect(key(composition, "Enter").defaultPrevented).toBe(true);
+    expect(onDrillDown).toHaveBeenCalledWith(withElements[0]!.items[0]!.element);
+    act(() => root.unmount());
+  });
+
   it("collapses expanded rows and leaves native header controls to the browser", () => {
     const onToggleRow = vi.fn();
     const expandedRows = [{ ...rows[0]!, expanded: true }, ...rows.slice(1)];

package/src/player/components/useTimelineKeyboardActor.ts

@@ -1,5 +1,5 @@
 import { useCallback, useMemo, type FocusEvent, type KeyboardEvent, type RefObject } from "react";
-import { usePlayerStore } from "../store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { TimelineRowGeometry } from "./timelineLayout";
 import {
   isTimelineNavigationKey,
@@ -14,6 +14,7 @@ interface TimelineKeyboardActorInput {
   rowGeometry: TimelineRowGeometry;
   scrollRef: RefObject<HTMLDivElement | null>;
   onToggleRow: (target: TimelineLogicalRow) => void;
+  onDrillDown?: (element: TimelineElement) => void;
 }
 
 function eventTarget(event: FocusEvent | KeyboardEvent): HTMLElement | null {
@@ -70,6 +71,7 @@ export function useTimelineKeyboardActor({
   rowGeometry,
   scrollRef,
   onToggleRow,
+  onDrillDown,
 }: TimelineKeyboardActorInput) {
   const rovingTargetId =
     (focusedTargetId && locateTimelineLogicalTarget(logicalRows, focusedTargetId)?.target.id) ??
@@ -130,6 +132,12 @@ export function useTimelineKeyboardActor({
         openContextMenu(targetElement);
         return;
       }
+      const composition = located.target.kind === "clip" && located.target.element;
+      if (event.key === "Enter" && composition && composition.compositionSrc && onDrillDown) {
+        event.preventDefault();
+        onDrillDown(composition);
+        return;
+      }
       if (
         (event.key !== "Enter" && event.key !== " ") ||
         located.target.kind !== "row" ||
@@ -140,7 +148,7 @@ export function useTimelineKeyboardActor({
       event.preventDefault();
       onToggleRow(located.target);
     },
-    [logicalRowCountByTrack, logicalRows, onToggleRow, rowGeometry, scrollRef],
+    [logicalRowCountByTrack, logicalRows, onDrillDown, onToggleRow, rowGeometry, scrollRef],
   );
 
   return { rovingTargetId, onFocus, onKeyDown };

package/src/player/components/useTimelinePlayhead.ts

@@ -104,7 +104,7 @@ export function useTimelinePlayhead({
 
   useEffect(() => {
     syncPlayheadPosition(currentTime);
-  }, [currentTime, pps, syncPlayheadPosition]);
+  }, [currentTime, pps, syncPlayheadPosition, timelineReady, elementsLength]);
 
   useLayoutEffect(() => {
     const scroll = scrollRef.current;

package/src/player/store/liveTime.ts

@@ -1,9 +1,14 @@
 // ponytail: Playback RAF updates the playhead/time display without per-frame React renders.
 type TimeListener = (time: number) => void;
 const timeListeners = new Set<TimeListener>();
+let latestTime = 0;
 
 export const liveTime = {
-  notify: (time: number) => timeListeners.forEach((listener) => listener(time)),
+  notify: (time: number) => {
+    latestTime = time;
+    timeListeners.forEach((listener) => listener(time));
+  },
+  latest: () => latestTime,
   subscribe: (listener: TimeListener) => {
     timeListeners.add(listener);
     return () => timeListeners.delete(listener);