@hyperframes/studio 0.8.90 → 0.8.92

package/src/player/components/useTimelinePlayhead.ts

@@ -12,6 +12,22 @@ import {
 import { getTimelinePlayheadTransform } from "./timelinePlayheadTransform";
 import { applyTimelineHorizontalAutoScrollStep } from "./timelineEditing";
 
+function revealPlayheadScrollLeft(
+  scroll: HTMLDivElement,
+  playheadX: number,
+  contentOrigin: number,
+  from = scroll.scrollLeft,
+): number {
+  if (playheadX >= from + contentOrigin && playheadX <= from + scroll.clientWidth) return from;
+  return getTimelinePlaybackFollowScrollLeft({
+    playheadX,
+    currentScrollLeft: from,
+    viewportWidth: scroll.clientWidth,
+    contentOrigin,
+    maxScrollLeft: scroll.scrollWidth - scroll.clientWidth,
+  });
+}
+
 interface UseTimelinePlayheadInput {
   playheadRef: React.RefObject<HTMLDivElement | null>;
   scrollRef: React.RefObject<HTMLDivElement | null>;
@@ -58,10 +74,13 @@ export function useTimelinePlayhead({
 }: UseTimelinePlayheadInput) {
   const dragScrollRaf = useRef(0);
   const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
-  // Center-anchored magnify: keep the time at the viewport center fixed when
-  // the zoom level (pps) changes via the toolbar / slider. The pinch handler
-  // anchors at the cursor instead, so it opts out via `skipCenterAnchorRef`.
+  // A toolbar zoom keeps the playhead in place; a resize keeps the centre, or 00:00 at the start.
+  // The pinch handler anchors at the cursor instead, so it opts out via `skipCenterAnchorRef`.
   const previousAnchorPpsRef = useRef(pps);
+  const userZoomCount = usePlayerStore((s) => s.userZoomCount);
+  const previousZoomCountRef = useRef(userZoomCount);
+  const lastLiveTimeRef = useRef(usePlayerStore.getState().currentTime);
+  const lastSeekCountRef = useRef(liveTime.seekCount());
   const skipCenterAnchorRef = useRef(false);
   const contentOriginRef = useRef(contentOrigin);
   contentOriginRef.current = contentOrigin;
@@ -70,15 +89,22 @@ export function useTimelinePlayhead({
     const scroll = scrollRef.current;
     const prevPps = previousAnchorPpsRef.current;
     previousAnchorPpsRef.current = pps;
+    const prevZoomCount = previousZoomCountRef.current;
+    previousZoomCountRef.current = userZoomCount;
     // Always consume the skip flag, even when pps didn't change — otherwise a
     // pinch that produced no pps change (already at the zoom clamp) would strand
     // it true and the next toolbar zoom would wrongly skip center-anchoring.
     const skip = skipCenterAnchorRef.current;
     skipCenterAnchorRef.current = false;
-    // A view at the start stays there: a resize or a host zoom must not hide 00:00.
-    if (!scroll || pps === prevPps || skip || scroll.scrollLeft < 1) return;
+    if (!scroll || pps === prevPps || skip) return;
+    const zoomed = userZoomCount !== prevZoomCount;
+    if (!zoomed && scroll.scrollLeft < 1) return;
+    const time = Math.max(0, lastLiveTimeRef.current);
+    const playheadX = contentOrigin + time * prevPps;
+    const onScreen =
+      revealPlayheadScrollLeft(scroll, playheadX, contentOrigin) === scroll.scrollLeft;
     const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
-      pointerX: scroll.clientWidth / 2,
+      pointerX: zoomed && onScreen ? playheadX - scroll.scrollLeft : scroll.clientWidth / 2,
       currentScrollLeft: scroll.scrollLeft,
       contentOrigin,
       currentPixelsPerSecond: prevPps,
@@ -86,8 +112,11 @@ export function useTimelinePlayhead({
       duration: durationRef.current,
     });
     const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
-    scroll.scrollLeft = Math.max(0, Math.min(maxScrollLeft, nextScrollLeft));
-  }, [pps, scrollRef, durationRef, contentOrigin]);
+    const anchored = Math.max(0, Math.min(maxScrollLeft, nextScrollLeft));
+    scroll.scrollLeft = zoomed
+      ? revealPlayheadScrollLeft(scroll, contentOrigin + time * pps, contentOrigin, anchored)
+      : anchored;
+  }, [pps, userZoomCount, scrollRef, durationRef, contentOrigin]);
 
   const syncPlayheadPosition = useCallback(
     (time: number) => {
@@ -127,7 +156,6 @@ export function useTimelinePlayhead({
   }, [zoomMode, scrollRef]);
 
   useMountEffect(() => {
-    let lastLiveTime = usePlayerStore.getState().currentTime;
     const place = (t: number, atRest: boolean) => {
       if (!playheadRef.current || durationRef.current <= 0) return false;
       playheadRef.current.style.transform = getTimelinePlayheadTransform(
@@ -138,29 +166,30 @@ export function useTimelinePlayhead({
       );
       return true;
     };
+    const dragging = () => isDragging.current || usePlayerStore.getState().beatDragging;
     const unsubPlaying = usePlayerStore.subscribe((state, prev) => {
-      if (prev.isPlaying && !state.isPlaying) place(lastLiveTime, true);
+      if (prev.isPlaying && !state.isPlaying) place(lastLiveTimeRef.current, true);
     });
+    lastSeekCountRef.current = liveTime.seekCount();
     const unsub = liveTime.subscribe((t) => {
-      lastLiveTime = t;
-      if (!place(t, !usePlayerStore.getState().isPlaying)) return;
+      const sought = liveTime.seekCount() !== lastSeekCountRef.current;
+      lastSeekCountRef.current = liveTime.seekCount();
+      lastLiveTimeRef.current = t;
+      const playing = usePlayerStore.getState().isPlaying;
+      if (!place(t, !playing)) return;
       const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
       const scroll = scrollRef.current;
-      if (
-        !scroll ||
-        !usePlayerStore.getState().isPlaying ||
-        isDragging.current ||
-        zoomModeRef.current === "fit"
-      ) {
-        return;
-      }
-      const nextScrollLeft = getTimelinePlaybackFollowScrollLeft({
-        playheadX,
-        currentScrollLeft: scroll.scrollLeft,
-        viewportWidth: scroll.clientWidth,
-        contentOrigin: contentOriginRef.current,
-        maxScrollLeft: scroll.scrollWidth - scroll.clientWidth,
-      });
+      // Paused, only a seek scrolls: a reload's republish, frame-rounded, must not undo a person's scroll.
+      if (!scroll || dragging() || zoomModeRef.current === "fit" || (!playing && !sought)) return;
+      const nextScrollLeft = playing
+        ? getTimelinePlaybackFollowScrollLeft({
+            playheadX,
+            currentScrollLeft: scroll.scrollLeft,
+            viewportWidth: scroll.clientWidth,
+            contentOrigin: contentOriginRef.current,
+            maxScrollLeft: scroll.scrollWidth - scroll.clientWidth,
+          })
+        : revealPlayheadScrollLeft(scroll, playheadX, contentOriginRef.current);
       if (Math.abs(nextScrollLeft - scroll.scrollLeft) >= 0.5) {
         scroll.scrollLeft = nextScrollLeft;
       }

package/src/player/components/useTimelineProviderState.tsx

@@ -1,6 +1,6 @@
 import { useRef, useMemo, useCallback, useState } from "react";
 import { useAdjustedBeatAnalysis, useMusicBeatAnalysis } from "../../hooks/useMusicBeatAnalysis";
-import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
 import { useTimelineZoom } from "./useTimelineZoom";
@@ -8,18 +8,14 @@ import { useTimelineAssetDrop } from "./timelineDragDrop";
 import { type KeyframeDiamondContextMenuState } from "./KeyframeDiamondContextMenu";
 import { useTimelineClipDrag } from "./useTimelineClipDrag";
 import type { ClipContextMenuState, TimelineContextValue } from "./TimelineProvider";
-import {
-  buildTimelineMeta,
-  resolveMultiDragPreview,
-  resolveResizingElementIds,
-  shouldIgnoreTimelinePointerDown,
-} from "./timelineProviderStateBuilders";
+import { buildTimelineShellMeta } from "./timelineShellMeta";
+import { useTimelineDragPreviewState } from "./useTimelineDragPreviewState";
 import { useTimelineOverlaysState } from "./useTimelineOverlaysState";
 import { useTimelineEditPinning } from "./useTimelineEditPinning";
 import { useTimelineStackingSync } from "./useTimelineStackingSync";
 import { useTimelineGeometry } from "./useTimelineGeometry";
 import { useAutoExpandKeyframedClips } from "./useAutoExpandKeyframedClips";
-import { GUTTER, LABEL_COL_W } from "./timelineLayout";
+import { GUTTER } from "./timelineLayout";
 import { useTimelineLabelColumn } from "./useTimelineLabelColumn";
 import { useTimelineKeyframeData } from "./useTimelineKeyframeData";
 import { useTimelineScrollViewport } from "./useTimelineScrollViewport";
@@ -33,9 +29,9 @@ import {
 } from "./useTimelineTrackLayout";
 import { useTimelineKeyframeHandlers } from "./useTimelineKeyframeHandlers";
 import { useTimelineGapHighlights } from "./useTimelineGapHighlights";
-import { TimelineRazorGuideOverlay, useTimelineRazorInteraction } from "./TimelineRazorInteraction";
+import { useTimelineRazorInteraction } from "./TimelineRazorInteraction";
 import { useTimelinePerformanceTelemetry } from "./useTimelinePerformanceTelemetry";
-import { getEffectiveTimelineDuration, getTimelinePreviewElement } from "./timelineViewModel";
+import { getEffectiveTimelineDuration } from "./timelineViewModel";
 import { useTimelineShiftModifier } from "./useTimelineShiftModifier";
 import { useTimelineTicks } from "./useTimelineTicks";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
@@ -44,7 +40,6 @@ import { useTimelineActiveClips } from "./useTimelineActiveClips";
 import { useTimelineLaneMoveRefresh } from "./useTimelineLaneMoveRefresh";
 import { useTimelineLogicalFocus } from "./useTimelineLogicalFocus";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
-import { resolveSnapGuide } from "./timelineSnapping";
 export function useTimelineProviderState({
   onSeek,
   onDrillDown,
@@ -107,8 +102,7 @@ export function useTimelineProviderState({
   const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
   const focusedEaseSegment = usePlayerStore((s) => s.focusedEaseSegment);
   const { gsapAnimations, keyframeCache } = useTimelineKeyframeData(showKeyframes);
-  const namedAnimations = usePlayerStore((s) => s.gsapAnimations);
-  const { labelMode, contentOrigin } = useTimelineLabelColumn(namedAnimations, timelineElements);
+  const { labelMode, contentOrigin } = useTimelineLabelColumn(gsapAnimations, timelineElements);
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatDragging = usePlayerStore((s) => s.beatDragging);
@@ -223,7 +217,8 @@ export function useTimelineProviderState({
     sessionEpoch,
   });
   const displayLayout = useTimelineDisplayLayout(draggedClip, trackOrder, rowGeometry);
-  const resizingElementIds = resolveResizingElementIds(resizingClip);
+  const { resizingElementIds, getPreviewElement, draggedElement, multiDragPreview, snapGuide } =
+    useTimelineDragPreviewState(draggedClip, resizingClip, selectedElementIds, timelineElements);
   const { recordTimelineScroll } = useTimelinePerformanceTelemetry({
     totalClipCount: timelineElements.length,
     totalRowCount: displayLayout.displayTrackOrder.length,
@@ -422,12 +417,6 @@ export function useTimelineProviderState({
     timeDisplayMode,
     timelineFocus.rowVirtualizationActive ? renderTimeRange : undefined,
   );
-  const getPreviewElement = useCallback(
-    (element: TimelineElement): TimelineElement => getTimelinePreviewElement(element, resizingClip),
-    [resizingClip],
-  );
-  const draggedElement = draggedClip?.element ?? null;
-  const multiDragPreview = resolveMultiDragPreview(draggedClip, selectedElementIds);
   const canvasProps = {
     major,
     minor,
@@ -502,7 +491,7 @@ export function useTimelineProviderState({
     onMoveElement,
     beatDragging,
     draggedElement,
-    snapGuide: resolveSnapGuide(draggedClip, resizingClip),
+    snapGuide,
     multiDragPreview,
     onToggleTrackHidden: editContext.onToggleTrackHidden,
     onTogglePropertyGroupKeyframe: editContext.onTogglePropertyGroupKeyframe,
@@ -520,60 +509,34 @@ export function useTimelineProviderState({
       )),
     [holdNewClipContent, renderClipContent],
   );
-  const timelineMeta = buildTimelineMeta({
-    emptyState: {
-      isDragOver: assetDrop.isDragOver,
-      onFileDrop: !!onFileDrop,
+  const timelineMeta = buildTimelineShellMeta({
+    isDragOver: assetDrop.isDragOver,
+    hasFileDrop: !!onFileDrop,
+    drop: {
       onDragOver: assetDrop.handleAssetDragOver,
       onDragLeave: assetDrop.handleAssetDragLeave,
       onDrop: assetDrop.handleAssetDrop,
     },
-    container: {
-      ref: setContainerRef,
-      "aria-label": "Timeline track view",
-      "data-timeline-element-count": timelineElements.length,
-      isDragOver: assetDrop.isDragOver,
-      activeTool,
-      shiftHeld,
-      accentClass: "ring-1 ring-inset ring-studio-accent/60",
-      onMouseMove: updateRazorGuide,
-      onMouseLeave: clearRazorGuide,
-      style: {
-        touchAction: "pan-x pan-y",
-        background: theme.shellBackground,
-        borderColor: theme.shellBorder,
-      },
-    },
-    viewport: {
-      ref: setScrollRef,
-      tabIndex: -1,
-      labelMode,
-      zoomMode,
-      onScroll: (e) => {
-        lastScrollLeftRef.current = e.currentTarget.scrollLeft;
-        recordTimelineScroll(e.currentTarget);
-        syncScrollViewport(e.currentTarget, true);
-      },
-      ...timelineFocus.timelineFocusProps,
-      onDragOver: assetDrop.handleAssetDragOver,
-      onDragLeave: assetDrop.handleAssetDragLeave,
-      onDrop: assetDrop.handleAssetDrop,
-      onPointerDown: (e) => {
-        if (shouldIgnoreTimelinePointerDown(e.target)) return;
-        if (splitAllAtPointer(e)) return;
-        handlePointerDown(e);
-      },
+    pointer: {
+      onPointerDown: handlePointerDown,
       onPointerMove: handlePointerMove,
       onPointerUp: handlePointerUp,
       onPointerCancel: handlePointerCancel,
-      onLostPointerCapture: handlePointerCancel,
     },
+    setContainerRef,
+    setScrollRef,
+    focusProps: timelineFocus.timelineFocusProps,
     elementCount: timelineElements.length,
-    labelColumnWidth: LABEL_COL_W,
-    razorGuide:
-      activeTool === "razor" && razorGuideX !== null ? (
-        <TimelineRazorGuideOverlay x={razorGuideX} />
-      ) : null,
+    activeTool,
+    shiftHeld,
+    labelMode,
+    contentOrigin,
+    zoomMode,
+    theme,
+    razor: { razorGuideX, updateRazorGuide, clearRazorGuide, splitAllAtPointer },
+    lastScrollLeftRef,
+    recordTimelineScroll,
+    syncScrollViewport,
   });
   const contextValue: TimelineContextValue = {
     state: {

package/src/player/components/useTimelineZoom.ts

@@ -1,4 +1,5 @@
 // fallow-ignore-file dead-code
+import { useCallback } from "react";
 import { usePlayerStore, type ZoomMode } from "../store/playerStore";
 
 export interface TimelineZoomState {
@@ -13,6 +14,13 @@ export function useTimelineZoom(): TimelineZoomState {
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
   const setZoomMode = usePlayerStore((s) => s.setZoomMode);
-  const setManualZoomPercent = usePlayerStore((s) => s.setManualZoomPercent);
+  const setStorePercent = usePlayerStore((s) => s.setManualZoomPercent);
+  const setManualZoomPercent = useCallback(
+    (percent: number) => {
+      usePlayerStore.setState((s) => ({ userZoomCount: s.userZoomCount + 1 }));
+      setStorePercent(percent);
+    },
+    [setStorePercent],
+  );
   return { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent };
 }

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

@@ -6,6 +6,8 @@ import type { useTimelinePlayer } from "./useTimelinePlayer";
 import {
   attachIframeAdapter,
   attachIframeWindow,
+  makeAdapterWindow,
+  makeFakeIframe,
   renderTimelinePlayerHarness,
   resetPlayerStore,
 } from "./timelinePlayerTestHarness";
@@ -263,6 +265,48 @@ describe("useTimelinePlayer audio controls (#835)", () => {
 });
 
 describe("useTimelinePlayer seek keepPlaying option (#834)", () => {
+  it("publishes a seek as a person's seek, so a paused timeline follows it", () => {
+    const { root, api } = renderAttachedTimelinePlayer();
+    const before = liveTime.seekCount();
+    seekWithAct(api, 5);
+    expect(liveTime.seekCount()).toBe(before + 1);
+    expect(liveTime.latest()).toBe(5);
+    unmountWithAct(root);
+  });
+
+  it("does not count a reload's hand-over as a person's seek", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    act(() => {
+      getApi().iframeRef.current = makeFakeIframe(makeAdapterWindow().win);
+      getApi().onIframeLoad();
+    });
+    seekWithAct(getApi(), 7);
+    act(() => getApi().refreshPlayer());
+    const seeks = liveTime.seekCount();
+    const gen = getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+    const shadow = makeFakeIframe(makeAdapterWindow().win);
+    shadow.src = "http://localhost/api/projects/demo/preview?_t=1";
+    act(() => {
+      getApi().setShadowIframeNode(shadow);
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(getApi().iframeRef.current).toBe(shadow);
+    expect(liveTime.latest()).toBe(7);
+    expect(liveTime.seekCount()).toBe(seeks);
+    unmountWithAct(root);
+  });
+
+  it("does not count the audition's return to the paused time as a person's seek", () => {
+    const { api, root } = renderAttachedTimelinePlayer();
+    seekWithAct(api, 4);
+    const seeks = liveTime.seekCount();
+    act(() => usePlayerStore.getState().requestPlayback(false, 2));
+    expect(liveTime.latest()).toBe(2);
+    expect(liveTime.seekCount()).toBe(seeks);
+    unmountWithAct(root);
+  });
+
   it("default seek() clears isPlaying when the store reports playing", () => {
     const { api, root } = renderAttachedTimelinePlayer();
     setStorePlaying();

package/src/player/hooks/useTimelinePlayer.ts

@@ -47,6 +47,9 @@ export interface UseTimelinePlayerOptions {
   onPreviewReloadFailed?: (message: string) => void;
 }
 
+const publishSeek = (time: number, options?: { follow?: boolean }) =>
+  options?.follow === false ? liveTime.notify(time) : liveTime.notifySeek(time);
+
 export function useTimelinePlayer({
   onShadowPromoted,
   onPreviewReloadFailed,
@@ -276,7 +279,7 @@ export function useTimelinePlayer({
     stopRAFLoop();
   }, [getAdapter, setCurrentTime, setIsPlaying, stopRAFLoop, stopReverseLoop]);
   const seek = useCallback(
-    (time: number, options?: { keepPlaying?: boolean }) => {
+    (time: number, options?: { keepPlaying?: boolean; follow?: boolean }) => {
       const wasReverseShuttle = shuttleDirectionRef.current === "backward";
       stopReverseLoop();
       const adapter = getAdapter();
@@ -295,7 +298,7 @@ export function useTimelinePlayer({
         nextTime,
       });
       adapter.seek(nextTime, options);
-      liveTime.notify(nextTime); // Direct DOM updates (playhead, timecode, progress) — no re-render
+      publishSeek(nextTime, options); // Direct DOM updates (playhead, timecode, progress) — no re-render
       setCurrentTime(nextTime); // sync store so Split/Delete have accurate time
       if (!shouldResumeAfterSeek && !keepPlaying) scrubMusicAtSeek(iframeRef.current, nextTime);
       if (shouldResumeAfterSeek) {
@@ -344,7 +347,7 @@ export function useTimelinePlayer({
         if (request.playing) play();
         else {
           pause();
-          if (request.returnTo !== null) seek(request.returnTo);
+          if (request.returnTo !== null) seek(request.returnTo, { follow: false });
         }
         usePlayerStore.getState().clearPlaybackRequest();
       }
@@ -409,7 +412,7 @@ export function useTimelinePlayer({
     onReloadFailed: onPreviewReloadFailed,
     handOverPlayback: (time, playing) => {
       // keepPlaying: move the playhead without the paused-seek audio scrub.
-      seek(time, { keepPlaying: true });
+      seek(time, { keepPlaying: true, follow: false });
       const adapter = getAdapter();
       // An edit that cut the film short of the live time stops it at the new end, as playback does.
       if (playing && adapter && adapter.getTime() < adapter.getDuration()) play();

package/src/player/lib/timelineDOM.test.ts

@@ -7,6 +7,8 @@ import {
   mergeTimelineElementsPreservingDowngrades,
 } from "./timelineDOM";
 import { isTimelineIgnoredElement } from "./timelineElementHelpers";
+import { clipTimingStart, resolveClipTimingBasis } from "../../hooks/gsapShared";
+import { toAuthoredStart } from "../store/timelineElement";
 import { computeResizePreview } from "../components/timelineClipDragPreview";
 import type { TimelineElement } from "../store/playerStore";
 import {
@@ -25,6 +27,83 @@ function makeDoc(html: string): Document {
   return d;
 }
 
+describe("parseTimelineFromDOM — nested master time", () => {
+  it("adds every enclosing host's start to a clip inside a sub-composition", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="main" data-start="0" data-duration="20">
+        <div id="intro" data-composition-id="intro" data-start="2" data-duration="10">
+          <div data-composition-id="intro">
+            <div id="logo" data-composition-id="logo" data-start="3" data-duration="5">
+              <div data-composition-id="logo">
+                <div id="badge" class="clip" data-start="1" data-duration="2"></div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    `);
+    const starts = parseTimelineFromDOM(doc, 20).map((e) => [
+      e.domId,
+      e.start,
+      e.parentCompositionStart,
+    ]);
+    expect(starts).toEqual([
+      ["intro", 2, 0],
+      ["logo", 5, 2],
+      ["badge", 6, 5],
+    ]);
+  });
+
+  it("places a clip inside a referenced scene after the scene's authored length", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="main" data-start="0" data-duration="20">
+        <div id="s1" data-composition-id="s1" data-start="0" data-hf-authored-duration="8"></div>
+        <div id="s2" data-composition-id="s2" data-start="s1 + 1" data-duration="6">
+          <div data-composition-id="s2">
+            <div id="c" class="clip" data-start="1" data-duration="2"></div>
+          </div>
+        </div>
+      </div>
+    `);
+    const timelines = { s1: { duration: () => 6 } } as never;
+    const c = parseTimelineFromDOM(doc, 20, timelines).find((e) => e.domId === "c");
+    expect(c?.start).toBe(10);
+  });
+});
+
+describe("parseTimelineFromDOM — nested rows' keyframe basis", () => {
+  const doc = () =>
+    makeDoc(`
+      <div data-composition-id="main" data-start="0" data-duration="20">
+        <div id="intro" data-composition-id="intro" data-start="2" data-duration="10">
+          <div data-composition-id="intro">
+            <video id="vo" data-start="7" data-duration="2" data-hf-media-start-basis="global"></video>
+            <div id="logo" data-composition-id="logo" data-start="3" data-duration="5">
+              <div data-composition-id="logo">
+                <div id="badge" class="clip" data-start="1" data-duration="2"></div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    `);
+
+  it("measures diamonds and keyframe percentages against the local tween clock", () => {
+    const rows = parseTimelineFromDOM(doc(), 20);
+    const basis = (id: string) => resolveClipTimingBasis(id, "index.html", rows, []).elStart;
+    const at = (id: string) => rows.find((e) => e.domId === id)!;
+    expect([clipTimingStart(at("logo")), basis("logo")]).toEqual([3, 3]);
+    expect([clipTimingStart(at("badge")), basis("badge")]).toEqual([1, 1]);
+  });
+
+  it("keys a legacy root-time video on its host's clock but writes its start as master time", () => {
+    const vo = parseTimelineFromDOM(doc(), 20).find((e) => e.domId === "vo")!;
+    expect(vo.start).toBe(7);
+    expect(clipTimingStart(vo)).toBe(5);
+    expect(toAuthoredStart(vo, 8)).toBe(8);
+  });
+});
+
 describe("parseTimelineFromDOM — media in-point", () => {
   it("reads a negative in-point as 0, as the runtime does, so a head trim keeps the clip", () => {
     const doc = makeDoc(`

package/src/player/lib/timelineDOM.ts

@@ -12,6 +12,7 @@ import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip, IframeWindow, TimelineLike } from "./playbackTypes";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import { readClipTiming } from "@hyperframes/core/composition-contract";
+import { createRuntimeStartTimeResolver } from "@hyperframes/core/runtime/start-resolver";
 import { groupInfoFor } from "./timelineGroupInfo";
 import { transitionLabelsForDocument } from "./timelineTransitionMetadata";
 import {
@@ -228,10 +229,13 @@ export function parseTimelineFromDOM(
   const nodes = doc.querySelectorAll("[data-start]");
   const els: TimelineElement[] = [];
   let trackCounter = 0;
-  const transitionLabels = transitionLabelsForDocument(
-    doc,
-    timelines ?? (doc.defaultView as IframeWindow | null)?.__timelines,
-  );
+  const timelineRegistry = timelines ?? (doc.defaultView as IframeWindow | null)?.__timelines;
+  const transitionLabels = transitionLabelsForDocument(doc, timelineRegistry);
+  const masterStart = createRuntimeStartTimeResolver({
+    timelineRegistry,
+    includeAuthoredTimingAttrs: true,
+    documentRef: doc,
+  });
 
   // fallow-ignore-next-line complexity
   nodes.forEach((node) => {
@@ -239,11 +243,14 @@ export function parseTimelineFromDOM(
     if (isTimelineIgnoredElement(node)) return;
     const el = node as HTMLElement;
     const timing = readClipTiming(el);
-    const start = timing.start;
-    if (start == null) return;
+    if (timing.start == null) return;
+    const tagLower = el.tagName.toLowerCase();
+    const start =
+      tagLower === "video" || tagLower === "audio"
+        ? masterStart.resolveMediaStartForElement(el)
+        : masterStart.resolveStartForElement(el);
     if (Number.isFinite(rootDuration) && rootDuration > 0 && start >= rootDuration) return;
 
-    const tagLower = el.tagName.toLowerCase();
     let dur = timing.duration ?? 0;
     if (dur <= 0) dur = Math.max(0, rootDuration - start);
     if (Number.isFinite(rootDuration) && rootDuration > 0) {
@@ -287,6 +294,8 @@ export function parseTimelineFromDOM(
               : "element",
       tag: tagLower,
       start,
+      parentCompositionStart: masterStart.resolveHostStartForElement(el),
+      ...(masterStart.isRootGlobalMediaStartForElement(el) && { authoredStartIsMasterTime: true }),
       duration: dur,
       track,
       domId: el.id || undefined,

package/src/player/lib/timelineIframeHelpers.test.ts

@@ -103,6 +103,42 @@ describe("buildMissingCompositionElements — hfId (R7)", () => {
   });
 });
 
+describe("buildMissingCompositionElements — nested master time", () => {
+  it("places hosts two and three levels deep at their master time", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="main" data-start="0" data-duration="20">
+        <div id="intro" data-composition-id="intro" data-start="2" data-duration="10">
+          <div data-composition-id="intro">
+            <div id="logo" data-composition-id="logo" data-start="3" data-duration="5">
+              <div data-composition-id="logo">
+                <div id="badge" data-composition-id="badge" data-start="1" data-duration="2"></div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    `);
+    const { missing } = buildMissingCompositionElements(doc, window as IframeWindow, [], 20);
+    expect(missing.map((e) => [e.domId, e.start, e.duration, e.parentCompositionStart])).toEqual([
+      ["intro", 2, 10, 0],
+      ["logo", 5, 5, 2],
+      ["badge", 6, 2, 5],
+    ]);
+  });
+
+  it("starts a host after a referenced scene's authored length", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="main" data-start="0" data-duration="20">
+        <div id="s1" data-composition-id="s1" data-start="0" data-hf-authored-duration="8"></div>
+        <div id="s2" data-composition-id="s2" data-start="s1 + 1" data-duration="4"></div>
+      </div>
+    `);
+    const win = { __timelines: { s1: { duration: () => 6 } } } as unknown as IframeWindow;
+    const { missing } = buildMissingCompositionElements(doc, win, [], 20);
+    expect(missing.find((e) => e.domId === "s2")?.start).toBe(9);
+  });
+});
+
 describe("setPreviewMediaVolume", () => {
   it("sends a clamped runtime volume to a direct preview iframe", () => {
     const iframe = document.createElement("iframe");