@hyperframes/studio 0.8.49 → 0.8.51

package/src/player/components/useTimelineClipDrag.resize.test.tsx

@@ -31,10 +31,14 @@ afterEach(() => {
 function renderResizeHarness(
   elements: TimelineElement[],
   selected: string[],
-  options: { wireGroupResize?: boolean } = {},
+  options: {
+    wireGroupResize?: boolean;
+    snap?: boolean;
+    onSeek?: (time: number, seekOptions?: { keepPlaying?: boolean }) => void;
+  } = {},
 ) {
   usePlayerStore.getState().setElements(elements);
-  usePlayerStore.setState({ timelineSnapEnabled: false });
+  usePlayerStore.setState({ timelineSnapEnabled: options.snap === true });
   usePlayerStore.getState().setSelectedElementIds(new Set(selected));
 
   const scroll = document.createElement("div");
@@ -61,6 +65,7 @@ function renderResizeHarness(
       onMoveElement,
       onBlockedEditAttempt,
       onResizeElements: options.wireGroupResize === false ? undefined : onResizeElements,
+      onSeek: options.onSeek,
       setShowPopover: vi.fn(),
       setRangeSelectionRef: { current: vi.fn() },
       sessionEpoch,
@@ -92,6 +97,9 @@ function renderResizeHarness(
     getResizeProjection() {
       return resizingClip?.groupPreview ?? [];
     },
+    getResizingClip() {
+      return resizingClip;
+    },
     getBlockedClip() {
       return blockedClipRef?.current ?? null;
     },
@@ -441,3 +449,129 @@ describe("useTimelineClipDrag — multi-select group resize (restored)", () => {
     h.unmount();
   });
 });
+
+describe("useTimelineClipDrag — trim guide and preview frame", () => {
+  /** Playhead at 1.25s that follows preview seeks; clip a's end edge grabbed and dragged once. */
+  function trimEndWithSeekingPlayhead(state: { isPlaying?: boolean } = {}) {
+    usePlayerStore.setState({ currentTime: 1.25, ...state });
+    const onSeek = vi.fn((t: number) => usePlayerStore.setState({ currentTime: t }));
+    const a = el("a", { start: 1, duration: 2 });
+    const h = renderResizeHarness([a], [], { onSeek });
+    h.startResize(a, "end");
+    h.movePointer(50);
+    return { onSeek, h };
+  }
+
+  /** Clip a (0-2s) with neighbour b starting at 5s, snapping on, a's end edge grabbed. */
+  function trimAEndBesideB() {
+    const a = el("a", { start: 0, duration: 2 });
+    const b = el("b", { start: 5, duration: 2 });
+    const h = renderResizeHarness([a, b], [], { snap: true });
+    h.startResize(a, "end");
+    return h;
+  }
+
+  it("publishes the snap target while a trimmed edge is on a neighbour edge", () => {
+    const h = trimAEndBesideB();
+    h.movePointer(296); // a's end lands at 4.96s, 4px from b's start
+    expect(h.getResizingClip()).toMatchObject({ snapTime: 5, snapType: "clip-edge" });
+    h.unmount();
+  });
+
+  it("keeps the guide when the trimmed edge sits exactly on the neighbour edge", () => {
+    const h = trimAEndBesideB();
+    h.movePointer(300);
+    expect(h.getResizingClip()).toMatchObject({ snapTime: 5, previewDuration: 5 });
+    h.unmount();
+  });
+
+  it("publishes no snap target when the trimmed edge is free", () => {
+    const h = trimAEndBesideB();
+    h.movePointer(150);
+    expect(h.getResizingClip()).toMatchObject({ snapTime: null, snapType: null });
+    h.unmount();
+  });
+
+  it("never snaps a trimmed edge to the playhead — the edge drives its own seek", () => {
+    usePlayerStore.setState({ currentTime: 5 }); // no clip edge or beat nearby, only the playhead
+    const a = el("a", { start: 0, duration: 2 });
+    const h = renderResizeHarness([a], [], { snap: true });
+    h.startResize(a, "end");
+    h.movePointer(296); // a's end lands at 4.96s, 4px from the playhead
+    expect(h.getResizingClip()).toMatchObject({
+      snapTime: null,
+      snapType: null,
+      previewDuration: 4.96,
+    });
+    h.unmount();
+  });
+
+  it("shows the frame at the dragged edge, then puts the playhead back on release", async () => {
+    usePlayerStore.setState({ currentTime: 1.25 });
+    const onSeek = vi.fn();
+    const a = el("a", { start: 1, duration: 2 });
+    const h = renderResizeHarness([a], [], { onSeek });
+    h.startResize(a, "end");
+    h.movePointer(50);
+    expect(onSeek).toHaveBeenLastCalledWith(3.5 - 1 / 30, { keepPlaying: true });
+    await h.dropPointer();
+    expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true });
+    h.unmount();
+  });
+
+  it("previews the new in-point when the start edge is trimmed", () => {
+    const onSeek = vi.fn();
+    const a = el("a", { start: 1, duration: 2 });
+    const h = renderResizeHarness([a], [], { onSeek });
+    h.startResize(a, "start");
+    h.movePointer(50);
+    expect(onSeek).toHaveBeenLastCalledWith(1.5, { keepPlaying: true });
+    h.unmount();
+  });
+
+  it("publishes the guide when the start edge snaps to a neighbour's end", () => {
+    // playbackStart leaves source to reveal when the in-point moves left.
+    const a = el("a", { start: 3, duration: 2, playbackStart: 5 });
+    const b = el("b", { start: 0, duration: 2 });
+    const h = renderResizeHarness([a, b], [], { snap: true });
+    h.startResize(a, "start");
+    h.movePointer(-96); // a's start lands at 2.04s, 4px from b's end
+    expect(h.getResizingClip()).toMatchObject({ snapTime: 2, previewStart: 2 });
+    h.unmount();
+  });
+
+  it("restores the playhead it had before the first preview seek, not a seeked time", async () => {
+    const { onSeek, h } = trimEndWithSeekingPlayhead();
+    h.movePointer(80);
+    h.movePointer(120);
+    await h.dropPointer();
+    expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true });
+    h.unmount();
+  });
+
+  it("leaves the playhead where playback is when a trim is released while playing", async () => {
+    const { onSeek, h } = trimEndWithSeekingPlayhead({ isPlaying: true });
+    h.movePointer(120);
+    const callsBeforeRelease = onSeek.mock.calls.length;
+    await h.dropPointer();
+    expect(onSeek).toHaveBeenCalledTimes(callsBeforeRelease);
+    expect(onSeek).not.toHaveBeenCalledWith(1.25, expect.anything());
+    usePlayerStore.setState({ isPlaying: false });
+    h.unmount();
+  });
+
+  it("draws no guide and seeks to the rendered edge when a group member clamps the trim", () => {
+    const onSeek = vi.fn();
+    const a = el("a", { start: 0, duration: 4 });
+    const b = el("b", { start: 0, duration: 1 });
+    const c = el("c", { start: 2, duration: 1 });
+    const h = renderResizeHarness([a, b, c], ["a", "b"], { snap: true, onSeek });
+    h.startResize(a, "end");
+    h.movePointer(-198); // a's raw end 2.02s snaps to c at 2s; b clamps the shared delta
+    const clip = h.getResizingClip()!;
+    expect(clip.previewStart + clip.previewDuration).toBeCloseTo(3.1, 3);
+    expect(clip).toMatchObject({ snapTime: null, snapType: null });
+    expect(onSeek).toHaveBeenLastCalledWith(expect.closeTo(3.1 - 1 / 30, 3), { keepPlaying: true });
+    h.unmount();
+  });
+});

package/src/player/components/useTimelineClipDrag.ts

@@ -17,6 +17,7 @@ import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import {
   computeDragPreview,
   computeResizePreview,
+  trimPreviewTime,
   previewGroupResize,
   type ResizePreviewResult,
 } from "./timelineClipDragPreview";
@@ -64,6 +65,8 @@ interface UseTimelineClipDragInput {
   ) => Promise<void> | void;
   onResizeElements?: NonNullable<TimelineEditCallbacks["onResizeElements"]>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedClipState["intent"]) => void;
+  /** Seeks the preview; a trim shows the frame at its dragged edge. */
+  onSeek?: (time: number, options?: { keepPlaying?: boolean }) => void;
   setShowPopover: (show: boolean) => void;
   /** Stable ref to the range selection setter — wired after mount to break circular dependency. */
   setRangeSelectionRef: React.RefObject<((sel: null) => void) | null>;
@@ -92,6 +95,7 @@ export function useTimelineClipDrag({
   onResizeElement,
   onResizeElements,
   onBlockedEditAttempt,
+  onSeek,
   setShowPopover,
   setRangeSelectionRef,
   readZIndex,
@@ -149,11 +153,15 @@ export function useTimelineClipDrag({
   const dragAudioTracksRef = useRef<ReadonlySet<number> | null>(null);
 
   const buildSnapTargets = useCallback(
-    (excludeElementKey: string | null, includeBeats: boolean): TimelineSnapTarget[] => {
+    (
+      excludeElementKey: string | null,
+      includeBeats: boolean,
+      includePlayhead = true,
+    ): TimelineSnapTarget[] => {
       // Magnet off ⇒ no targets and no scan; do NOT cache so a mid-gesture toggle
       // back on starts scanning immediately (preserves the existing skip).
       if (!snapContextRef.current.enabled) return [];
-      const cacheKey = `${excludeElementKey ?? ""}|${includeBeats ? 1 : 0}`;
+      const cacheKey = `${excludeElementKey ?? ""}|${includeBeats ? 1 : 0}|${includePlayhead ? 1 : 0}`;
       const cached = snapTargetsCacheRef.current.get(cacheKey);
       if (cached) return cached;
       const targets = collectTimelineSnapTargets({
@@ -161,6 +169,7 @@ export function useTimelineClipDrag({
         playheadTime: usePlayerStore.getState().currentTime,
         beatTimes: includeBeats ? snapContextRef.current.beatTimes : [],
         excludeElementKey,
+        includePlayhead,
       });
       snapTargetsCacheRef.current.set(cacheKey, targets);
       return targets;
@@ -244,6 +253,10 @@ export function useTimelineClipDrag({
   onResizeElementRef.current = onResizeElement;
   const onResizeElementsRef = useRef(onResizeElements);
   onResizeElementsRef.current = onResizeElements;
+  const onSeekRef = useRef(onSeek);
+  onSeekRef.current = onSeek;
+  // Playhead time before the first trim preview seek; restored when the gesture ends.
+  const trimSeekOriginRef = useRef<number | null>(null);
   const readZIndexRef = useRef(readZIndex);
   readZIndexRef.current = readZIndex;
   const onStackingPatchesRef = useRef(onStackingPatches);
@@ -292,10 +305,17 @@ export function useTimelineClipDrag({
         pps: ppsRef.current,
         buildSnapTargets,
       });
-      const setResizeState = (v: ResizePreviewResult) =>
+      trimSeekOriginRef.current ??= usePlayerStore.getState().currentTime;
+      const setResizeState = (v: ResizePreviewResult) => {
+        // A trim never changes the play state: keepPlaying lets seek() decide,
+        // and it only resumes playback if it was already playing.
+        onSeekRef.current?.(trimPreviewTime(resize.edge, v.previewStart, v.previewDuration), {
+          keepPlaying: true,
+        });
         publishResizingClip(
           resizingClipRef.current ? { ...resizingClipRef.current, started: true, ...v } : null,
         );
+      };
 
       // Group resize: a capability-clean multi-selection resizes rigidly by one
       // shared, member-clamped delta (legacy main 36413da7f). The grabbed clip
@@ -338,6 +358,13 @@ export function useTimelineClipDrag({
       cancelAnimationFrame(clipDragScrollRaf.current);
       clipDragScrollRaf.current = 0;
     }
+    if (trimSeekOriginRef.current != null) {
+      // Paused: put the playhead back. Playing: leave it, a backward jump would rewind live playback.
+      if (!usePlayerStore.getState().isPlaying) {
+        onSeekRef.current?.(trimSeekOriginRef.current, { keepPlaying: true });
+      }
+      trimSeekOriginRef.current = null;
+    }
     // Gesture teardown: drop frozen caches so the next gesture reads fresh state.
     snapTargetsCacheRef.current.clear();
     dragAudioTracksRef.current = null;

package/src/player/components/useTimelineTrackDerivations.ts

@@ -98,7 +98,7 @@ function buildGroupInfo(
     id: groupId,
     label: membership.labelByGroup.get(groupId) ?? groupId,
     // Exactly x.5, which sub-composition child rows are now kept strictly below
-    // (`useExpandedTimelineElements`) — they used to be able to land here and
+    // (`useTimelineRowElements`) — they used to be able to land here and
     // collide, duplicating the group header.
     anchorKey: (memberTracks[0] ?? fallbackTrackNum) - 0.5,
     memberTracks,

package/src/player/hooks/timelineDomBinding.test.ts

@@ -73,9 +73,6 @@ describe("live DOM manifest hydration", () => {
       canTrimEnd: true,
     });
     expect(getTimelineEditCapabilities({ ...input, timelineLocked: true }).canMove).toBe(false);
-    expect(getTimelineEditCapabilities({ ...input, timingSource: "implicit" }).canTrimEnd).toBe(
-      false,
-    );
   });
   it("uses at most one fallback candidate snapshot per hydration pass", () => {
     const doc = documentWith(

package/src/player/hooks/timelineSyncHydration.test.ts

@@ -3,6 +3,7 @@
 import { describe, expect, it } from "vitest";
 import {
   collectSubCompositionDomChildren,
+  collectTopLevelElementIds,
   collectSubCompositionHostState,
 } from "./timelineSyncHydration";
 import type { ClipManifestClip } from "../lib/playbackTypes";
@@ -94,3 +95,20 @@ describe("collectSubCompositionHostState", () => {
     expect(state.size).toBe(0);
   });
 });
+
+describe("collectTopLevelElementIds", () => {
+  const docOf = (html: string) => new DOMParser().parseFromString(html, "text/html");
+
+  it("names the sub-composition host and a timed element, not what is nested inside them", () => {
+    const doc = docOf(`<div data-composition-id="root">
+      <div id="wrap"><div id="a" data-start="0" data-duration="2"><div id="inner" data-start="0"></div></div></div>
+      <div id="scene" data-composition-id="scene" data-composition-src="scene.html"><div id="box" data-start="0"></div></div>
+    </div>`);
+    expect([...collectTopLevelElementIds(doc)!].sort()).toEqual(["a", "scene"]);
+  });
+
+  it("is null when the document has no composition root", () => {
+    expect(collectTopLevelElementIds(docOf("<p>hi</p>"))).toBeNull();
+    expect(collectTopLevelElementIds(null)).toBeNull();
+  });
+});

package/src/player/hooks/timelineSyncHydration.ts

@@ -14,12 +14,12 @@ import { usePlayerStore } from "../store/playerStore";
 import type { TimelineElement, DomClipChild, SubCompositionHostState } from "../store/playerStore";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import type { ClipTree } from "@hyperframes/core/runtime/clipTree";
+import { topLevelElements, type StructureNode } from "@hyperframes/parsers/top-level-elements";
 import { HF_AUDIO_GROUP_ATTR } from "@hyperframes/core/audio-groups";
 import { groupInfoFor } from "../lib/timelineGroupInfo";
 import type { PlaybackAdapter, ClipManifestClip, IframeWindow } from "../lib/playbackTypes";
 import {
   buildStandaloneRootTimelineElement,
-  createImplicitTimelineLayersFromDOM,
   createTimelineElementFromManifestClip,
   getTimelineElementSelector,
   parseTimelineFromDOM,
@@ -137,6 +137,28 @@ export function collectSubCompositionDomChildren(
   return out;
 }
 
+interface DomStructureNode extends StructureNode<DomStructureNode> {
+  id: string;
+}
+
+function toStructureNode(el: Element): DomStructureNode {
+  const attrs: Record<string, string> = {};
+  for (const attr of Array.from(el.attributes)) attrs[attr.name] = attr.value;
+  return {
+    tag: el.tagName,
+    attrs,
+    id: el.id,
+    children: Array.from(el.children).map(toStructureNode),
+  };
+}
+
+/** DOM ids of the timeline's rows, by the definition the structure lint shares; null when there is no readable root. */
+export function collectTopLevelElementIds(doc: Document | null): Set<string> | null {
+  const root = doc?.querySelector("[data-composition-id]");
+  if (!root) return null;
+  return new Set(topLevelElements(toStructureNode(root)).flatMap((n) => (n.id ? [n.id] : [])));
+}
+
 /** The host-element `data-*` state one element carries, or null when it has none. */
 function readSubCompositionHostState(el: Element): SubCompositionHostState | null {
   const state: SubCompositionHostState = {};
@@ -214,28 +236,25 @@ export function buildTimelineElementsFromClips(
   });
 }
 
-/**
- * The clamped manifest elements plus the layers that exist only in the DOM.
- * Both halves need the same resolved duration, which is why they land together.
- */
-export function withImplicitDomLayers(
-  els: readonly TimelineElement[],
-  iframeDoc: Document | null,
-  effectiveDuration: number,
-): TimelineElement[] {
-  const clamped = clampElementsToDuration(els, effectiveDuration);
-  if (!iframeDoc || effectiveDuration <= 0) return clamped;
-  return [
-    ...clamped,
-    ...createImplicitTimelineLayersFromDOM(iframeDoc, effectiveDuration, clamped),
-  ];
-}
-
 /**
  * Drop elements that start past the composition's end and trim the ones that
  * straddle it. A non-positive duration means "not known yet" — pass through
  * untouched rather than clamping everything to nothing.
  */
+/** Commits the manifest elements, including none. An empty manifest carries a 1s floor, not a duration. */
+export function syncManifestTimeline(
+  els: readonly TimelineElement[],
+  manifestDuration: number,
+  storeDuration: number,
+  sync: (els: TimelineElement[], duration?: number) => void,
+): void {
+  const hasDuration = manifestDuration > 0 && els.length > 0;
+  sync(
+    clampElementsToDuration(els, hasDuration ? manifestDuration : storeDuration),
+    hasDuration ? manifestDuration : undefined,
+  );
+}
+
 function clampElementsToDuration(
   els: readonly TimelineElement[],
   effectiveDuration: number,

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

@@ -330,34 +330,17 @@ describe("findTimelineDomNodeForClip", () => {
 });
 
 describe("anonymous timeline identity", () => {
-  it("adds root-level untimed DOM layers as implicit full-duration layers", () => {
+  it("does not invent rows for root-level untimed wrappers", () => {
     const doc = createDocument(`
       <div data-composition-id="compare" data-start="0" data-duration="18">
-        <link rel="stylesheet" href="styles.css" />
-        <div class="scene-shell">
-          <div class="topline">Title</div>
-        </div>
+        <div class="scene-shell"><div class="topline">Title</div></div>
         <video id="main-video" class="clip main-video" data-start="0" data-duration="18" data-track-index="1"></video>
-        <script></script>
       </div>
     `);
 
     const elements = parseTimelineFromDOM(doc, 18);
 
-    expect(elements).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          duration: 18,
-          label: "Scene Shell",
-          selector: ".scene-shell",
-          start: 0,
-          tag: "div",
-          timingSource: "implicit",
-        }),
-      ]),
-    );
-    expect(elements.find((element) => element.tag === "link")).toBeUndefined();
-    expect(elements.find((element) => element.tag === "script")).toBeUndefined();
+    expect(elements.map((element) => element.tag)).toEqual(["video"]);
   });
 
   it("keeps fallback-parsed anonymous clips distinct when labels match", () => {

package/src/player/hooks/useTimelineRowElements.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { selectTimelineRowElements } from "./useTimelineRowElements";
+
+const el = (id: string, domId?: string): TimelineElement => ({
+  id,
+  domId,
+  start: 0,
+  duration: 1,
+  track: 0,
+  tag: "div",
+});
+
+describe("selectTimelineRowElements", () => {
+  it("drops an element the shared definition does not call top-level", () => {
+    const rows = selectTimelineRowElements([el("a", "a"), el("b", "b")], new Set(["a"]));
+    expect(rows.map((r) => r.id)).toEqual(["a"]);
+  });
+
+  it("keeps everything until the document has been read", () => {
+    const all = [el("a", "a"), el("b", "b")];
+    expect(selectTimelineRowElements(all, null)).toBe(all);
+  });
+
+  it("keeps an element with no DOM id", () => {
+    expect(selectTimelineRowElements([el("k")], new Set())).toHaveLength(1);
+  });
+});

package/src/player/hooks/useTimelineRowElements.ts

@@ -0,0 +1,17 @@
+import { useMemo } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+
+/** Rows are the ids `topLevelElements` names, as the lint does; id-less ones are kept. */
+export function selectTimelineRowElements(
+  elements: TimelineElement[],
+  topLevelIds: ReadonlySet<string> | null,
+): TimelineElement[] {
+  if (!topLevelIds) return elements;
+  return elements.filter((el) => el.domId === undefined || topLevelIds.has(el.domId));
+}
+
+export function useTimelineRowElements(): TimelineElement[] {
+  const elements = usePlayerStore((s) => s.elements);
+  const topLevelIds = usePlayerStore((s) => s.topLevelIds);
+  return useMemo(() => selectTimelineRowElements(elements, topLevelIds), [elements, topLevelIds]);
+}

package/src/player/hooks/useTimelineSyncCallbacks.emptyManifest.test.tsx

@@ -0,0 +1,41 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("processTimelineMessage with an empty manifest", () => {
+  it("commits zero rows without adopting the runtime 1s floor as the duration", () => {
+    const sync = vi.fn<(els: TimelineElement[], duration?: number) => void>();
+    let processTimelineMessage: ReturnType<
+      typeof useTimelineSyncCallbacks
+    >["processTimelineMessage"];
+    function Harness() {
+      ({ processTimelineMessage } = useTimelineSyncCallbacks({
+        iframeRef: { current: null },
+        probeIntervalRef: { current: undefined },
+        pendingSeekRef: { current: null },
+        isRefreshingRef: { current: false },
+        getAdapter: () => null,
+        syncTimelineElements: sync,
+        setDuration: () => {},
+        setCurrentTime: () => {},
+        requestTimelineReady: () => {},
+        setIsPlaying: () => {},
+        attachIframeShortcutListeners: () => {},
+        applyPreviewAudioState: () => {},
+      }));
+      return null;
+    }
+    const host = document.createElement("div");
+    act(() => createRoot(host).render(<Harness />));
+
+    processTimelineMessage!({ clips: [], durationInFrames: 30 });
+
+    expect(sync).toHaveBeenCalledWith([], undefined);
+  });
+});

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -17,7 +17,9 @@ import { buildMissingCompositionElements } from "../lib/timelineIframeHelpers";
 import { acceptedRuntimeMessageFps } from "../lib/runtimeProtocol";
 import {
   buildTimelineElementsFromClips,
+  syncManifestTimeline,
   clipTreeParentMap,
+  collectTopLevelElementIds,
   collectSubCompositionDomChildren,
   collectSubCompositionHostState,
   hydrateTimelineFromPreview,
@@ -26,7 +28,6 @@ import {
   sanitizeDurationSeconds,
   seekAdapterToRestorePoint,
   syncAdapterDuration,
-  withImplicitDomLayers,
   type RuntimeTimelineMessage,
 } from "./timelineSyncHydration";
 
@@ -114,9 +115,7 @@ export function useTimelineSyncCallbacks({
   // Convert a runtime timeline message (from iframe postMessage) into TimelineElements
   const processTimelineMessage = useCallback(
     (data: RuntimeTimelineMessage) => {
-      if (!data.clips || data.clips.length === 0) {
-        return;
-      }
+      if (!data.clips) return;
 
       usePlayerStore.getState().setClipManifest(data.clips);
 
@@ -131,11 +130,13 @@ export function useTimelineSyncCallbacks({
         const parentMap = clipTreeParentMap(iframeRef.current?.contentWindow ?? null);
         const domClipChildren = collectSubCompositionDomChildren(iframeDoc, data.clips, parentMap);
         usePlayerStore.getState().setClipParentMap(parentMap);
+        usePlayerStore.getState().setTopLevelIds(collectTopLevelElementIds(iframeDoc));
         usePlayerStore.getState().setDomClipChildren(domClipChildren);
         usePlayerStore
           .getState()
           .setSubCompositionHostState(collectSubCompositionHostState(iframeDoc, data.clips));
       } catch {
+        usePlayerStore.getState().setTopLevelIds(null);
         // cross-origin or __clipTree not available — maps stay empty
       }
 
@@ -150,14 +151,12 @@ export function useTimelineSyncCallbacks({
         manifestDurationSeconds: data.durationInFrames / acceptedRuntimeMessageFps(data),
         authoredRootDurationSeconds: readTimelineDurationFromDocument(iframeDoc),
       });
-      const timelineEls = withImplicitDomLayers(
+      syncManifestTimeline(
         els,
-        iframeDoc,
-        newDuration > 0 ? newDuration : usePlayerStore.getState().duration,
+        newDuration,
+        usePlayerStore.getState().duration,
+        syncTimelineElements,
       );
-      if (timelineEls.length > 0) {
-        syncTimelineElements(timelineEls, newDuration > 0 ? newDuration : undefined);
-      }
     },
     [iframeRef, syncTimelineElements],
   );

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

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/timelineElement";
+import { describeClips, formatTimelineBlock } from "./describeClips";
+
+function audio(id: string, start: number, duration: number, extra: Partial<TimelineElement> = {}) {
+  return {
+    id,
+    domId: id,
+    tag: "audio",
+    kind: "audio",
+    start,
+    duration,
+    track: 0,
+    ...extra,
+  } satisfies TimelineElement;
+}
+
+// Shaped like claude-paper-launch: two voiceovers, clicks, and dozens of keystroke sounds, each on its own track.
+function paperLaunchClips(): TimelineElement[] {
+  const clips = [
+    audio("vo", 29.6, 2.17, { src: "voiceover.mp3", authoredTrack: 8, volume: 0.009772 }),
+    audio("sfx-click-0", 1.6, 0.07, { src: "click.mp3", authoredTrack: 100, volume: 0.85 }),
+    audio("sfx-type-0", 7.8, 0.57, { src: "typenew.mp3", authoredTrack: 187, volume: 0.2 }),
+  ];
+  for (let i = 1; i <= 84; i++) {
+    clips.push(audio(`sfx-extra-${i}`, 8 + i * 0.1, 0.5, { authoredTrack: 200 + i, volume: 0.2 }));
+  }
+  return clips;
+}
+
+describe("formatTimelineBlock", () => {
+  it("lists every audio clip with its start and volume", () => {
+    const block = formatTimelineBlock(paperLaunchClips());
+    const audioLines = block.split("\n").filter((line) => line.startsWith("- audio "));
+    expect(audioLines).toHaveLength(87);
+    expect(
+      audioLines.every((line) => /start=[\d.]+/.test(line) && /volume=[\d.]+/.test(line)),
+    ).toBe(true);
+    expect(block).toContain(
+      '- audio "sfx-click-0" src=click.mp3 start=1.6 duration=0.07 end=1.67 track=100 volume=0.85',
+    );
+    expect(block).toContain(
+      '- audio "vo" src=voiceover.mp3 start=29.6 duration=2.17 end=31.77 track=8 volume=0.01',
+    );
+  });
+
+  it("orders clips by start time", () => {
+    const lines = formatTimelineBlock(paperLaunchClips()).split("\n");
+    expect(lines[1]).toContain('"sfx-click-0"');
+  });
+
+  it("prints volume automation points, rate and group", () => {
+    const block = formatTimelineBlock([
+      audio("bed", 8, 20, {
+        automation:
+          '{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":0.1},{"t":10,"v":0.5}]}]}',
+        playbackRate: 0.5,
+        audioGroup: "music",
+        timelineRole: "music",
+      }),
+    ]);
+    expect(block).toContain("rate=0.5 group=music role=music volume-lane=[0:0.1, 10:0.5]");
+  });
+
+  it("prints volume 0 and a project-relative src, and omits rate at normal speed", () => {
+    const block = formatTimelineBlock([
+      audio("mute", 0, 1, {
+        src: "http://localhost:5190/api/projects/p1/preview/assets/a.mp3",
+        volume: 0,
+        playbackRate: 1,
+      }),
+    ]);
+    expect(block).toContain(
+      '- audio "mute" src=assets/a.mp3 start=0 duration=1 end=1 track=0 volume=0',
+    );
+    expect(block).not.toContain("rate=");
+  });
+
+  it("is empty for an empty timeline and caps long ones", () => {
+    expect(formatTimelineBlock([])).toBe("");
+    const many = Array.from({ length: 250 }, (_, i) => audio(`a${i}`, i, 1));
+    expect(formatTimelineBlock(many)).toContain("(50 more clips not listed)");
+  });
+});
+
+describe("describeClips", () => {
+  it("keeps 'not authored' distinct from zero for volume and rate", () => {
+    const [plain, silent] = describeClips([
+      audio("a", 0, 1),
+      audio("b", 1, 1, { volume: 0, playbackRate: 0 }),
+    ]);
+    expect([plain?.volume, plain?.playbackRate]).toEqual([null, null]);
+    expect([silent?.volume, silent?.playbackRate]).toEqual([0, 0]);
+  });
+});