@hyperframes/studio 0.7.56 → 0.7.58

package/src/player/components/useTimelineRevealClip.ts

@@ -0,0 +1,56 @@
+/**
+ * Consumes playerStore.clipRevealRequest: when another surface (the sidebar
+ * asset card / audio row) asks for a clip to be revealed, smooth-scroll the
+ * timeline's scroll container so that clip is visible — horizontally to its
+ * time and vertically to its lane.
+ *
+ * The request is consumed (cleared) whether or not the clip node is found, so
+ * a stale request can never replay a scroll later. Respects zoom mode: in
+ * "fit" the timeline disables horizontal scrolling (overflow-x-hidden), so
+ * only the vertical axis is scrolled there.
+ */
+import { useEffect } from "react";
+import { usePlayerStore } from "../store/playerStore";
+import { GUTTER, RULER_H } from "./timelineLayout";
+import { computeRevealScroll } from "./timelineRevealScroll";
+
+export function useTimelineRevealClip(scrollRef: React.RefObject<HTMLDivElement | null>): void {
+  const revealRequest = usePlayerStore((s) => s.clipRevealRequest);
+
+  useEffect(() => {
+    if (!revealRequest) return;
+    // Consume the request first — reveal is one-shot, even when the clip node
+    // isn't currently rendered (e.g. drilled into a different composition).
+    usePlayerStore.getState().clearClipRevealRequest();
+
+    const container = scrollRef.current;
+    if (!container) return;
+    const clip = container.querySelector(`[data-el-id="${CSS.escape(revealRequest.elementId)}"]`);
+    if (!(clip instanceof HTMLElement)) return;
+
+    const containerRect = container.getBoundingClientRect();
+    const clipRect = clip.getBoundingClientRect();
+    const clipLeft = clipRect.left - containerRect.left + container.scrollLeft;
+    const clipTop = clipRect.top - containerRect.top + container.scrollTop;
+
+    const target = computeRevealScroll({
+      scrollLeft: container.scrollLeft,
+      scrollTop: container.scrollTop,
+      viewportWidth: container.clientWidth,
+      viewportHeight: container.clientHeight,
+      clipLeft,
+      clipRight: clipLeft + clipRect.width,
+      clipTop,
+      clipBottom: clipTop + clipRect.height,
+      stickyLeft: GUTTER,
+      stickyTop: RULER_H,
+      allowHorizontal: usePlayerStore.getState().zoomMode === "manual",
+    });
+    if (target.left === null && target.top === null) return;
+    container.scrollTo({
+      left: target.left ?? container.scrollLeft,
+      top: target.top ?? container.scrollTop,
+      behavior: "smooth",
+    });
+  }, [revealRequest, scrollRef]);
+}

package/src/player/components/useTimelineScrollViewport.ts

@@ -0,0 +1,73 @@
+import { useCallback, useEffect, useRef, useState, type RefObject } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
+import { shouldShowTimelineShortcutHint } from "./timelineLayout";
+
+/**
+ * The timeline scroll container's viewport plumbing — extracted verbatim from
+ * Timeline.tsx (600-line studio cap): the ResizeObserver-backed viewport width,
+ * the rAF-throttled shortcut-hint visibility sync, and the callback ref that
+ * wires both to the scroll element. `resyncShortcutHintOn` re-checks the hint
+ * whenever any of its values change (timeline readiness / element count /
+ * canvas height), matching the original effect.
+ */
+export function useTimelineScrollViewport(
+  scrollRef: RefObject<HTMLDivElement | null>,
+  resyncShortcutHintOn: ReadonlyArray<unknown>,
+): {
+  viewportWidth: number;
+  showShortcutHint: boolean;
+  setScrollRef: (el: HTMLDivElement | null) => void;
+} {
+  const [viewportWidth, setViewportWidth] = useState(0);
+  const [showShortcutHint, setShowShortcutHint] = useState(true);
+  const roRef = useRef<ResizeObserver | null>(null);
+  const shortcutHintRafRef = useRef(0);
+
+  const syncShortcutHintVisibility = useCallback(() => {
+    const scroll = scrollRef.current;
+    setShowShortcutHint(
+      scroll ? shouldShowTimelineShortcutHint(scroll.scrollHeight, scroll.clientHeight) : true,
+    );
+  }, [scrollRef]);
+
+  const scheduleShortcutHintVisibilitySync = useCallback(() => {
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
+    shortcutHintRafRef.current = requestAnimationFrame(() => {
+      shortcutHintRafRef.current = 0;
+      syncShortcutHintVisibility();
+    });
+  }, [syncShortcutHintVisibility]);
+
+  const setScrollRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      if (roRef.current) {
+        roRef.current.disconnect();
+        roRef.current = null;
+      }
+      scrollRef.current = el;
+      if (!el) return;
+
+      const syncScrollViewport = () => {
+        setViewportWidth(el.clientWidth);
+        scheduleShortcutHintVisibilitySync();
+      };
+
+      syncScrollViewport();
+      roRef.current = new ResizeObserver(syncScrollViewport);
+      roRef.current.observe(el);
+    },
+    [scrollRef, scheduleShortcutHintVisibilitySync],
+  );
+
+  useMountEffect(() => () => {
+    roRef.current?.disconnect();
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
+  });
+
+  useEffect(() => {
+    syncShortcutHintVisibility();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [syncShortcutHintVisibility, ...resyncShortcutHintOn]);
+
+  return { viewportWidth, showShortcutHint, setScrollRef };
+}

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

@@ -40,7 +40,6 @@ describe("useTimelineStackingSync", () => {
       start: 0,
       duration: 2,
       track: 0,
-      sourceFile: "nested.html",
     };
     let apply: ((patches: Array<{ key: string; zIndex: number }>, key?: string) => unknown) | null =
       null;
@@ -57,7 +56,17 @@ describe("useTimelineStackingSync", () => {
     });
 
     expect(commit).toHaveBeenCalledWith(
-      [expect.objectContaining({ element: node, zIndex: 8, sourceFile: "nested.html" })],
+      [
+        expect.objectContaining({
+          element: node,
+          zIndex: 8,
+          sourceFile: "nested.html",
+          // The patch's store key rides along so the commit updates the store
+          // zIndex synchronously on the lane-sync path (and rolls it back on
+          // failure) instead of waiting for a preview reload.
+          key: "a",
+        }),
+      ],
       "clip-lane-move:7",
     );
     act(() => root.unmount());

package/src/player/components/useTimelineStackingSync.ts

@@ -37,7 +37,7 @@ export function useTimelineStackingSync({ expandedElementsRef }: UseTimelineStac
           id: el.domId ?? el.id,
           selector: el.selector,
           selectorIndex: el.selectorIndex,
-          sourceFile: el.sourceFile,
+          sourceFile: el.sourceFile ?? zSyncActiveCompPath ?? "index.html",
         },
         zSyncActiveCompPath,
       );
@@ -45,17 +45,23 @@ export function useTimelineStackingSync({ expandedElementsRef }: UseTimelineStac
     [zSyncPreviewIframeRef, zSyncActiveCompPath],
   );
 
+  // NaN (NOT 0) when the element can't be resolved in the preview iframe — a
+  // nested / unmounted sub-comp node, or one outside the active file. Fabricating
+  // z=0 would enter computeStackingPatches as a real overlapping neighbour at the
+  // z-floor and skew the boundary math; a non-finite value tells it to EXCLUDE this
+  // clip instead. NaN (rather than null) keeps the return assignable to the
+  // `(el) => number` reader contract the drag hook / commit deps declare.
   const readClipZIndex = useCallback(
     (el: TimelineElement): number => {
       const node = resolveIframeElement(el);
-      return node ? readEffectiveZIndex(node) : 0;
+      return node ? readEffectiveZIndex(node) : Number.NaN;
     },
     [resolveIframeElement],
   );
 
   const applyStackingPatches = useCallback(
     (patches: StackingPatch[], coalesceKey?: string) => {
-      if (!handleDomZIndexReorderCommit) return;
+      if (!handleDomZIndexReorderCommit) return Promise.resolve();
       const entries = patches.flatMap((p) => {
         const el = expandedElementsRef.current.find((e) => (e.key ?? e.id) === p.key);
         const node = el && resolveIframeElement(el);
@@ -68,10 +74,17 @@ export function useTimelineStackingSync({ expandedElementsRef }: UseTimelineStac
             selector: el.selector,
             selectorIndex: el.selectorIndex,
             sourceFile: el.sourceFile ?? zSyncActiveCompPath ?? "index.html",
+            // The store key: lets the commit update the store's zIndex
+            // synchronously (and roll it back on failure).
+            key: p.key,
           },
         ];
       });
-      if (entries.length) return handleDomZIndexReorderCommit(entries, coalesceKey);
+      // Forward the drag-commit's shared coalesce key so the z-reorder history
+      // entry merges with the lane change's move entry into one undo step.
+      return entries.length
+        ? handleDomZIndexReorderCommit(entries, coalesceKey).then(() => undefined)
+        : Promise.resolve();
     },
     [handleDomZIndexReorderCommit, resolveIframeElement, zSyncActiveCompPath, expandedElementsRef],
   );

package/src/player/components/useTimelineTrackDerivations.ts

@@ -0,0 +1,38 @@
+import { useMemo } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import { getTrackStyle, type TrackVisualStyle } from "./timelineIcons";
+
+/**
+ * Per-render track derivations Timeline.tsx feeds the canvas/lanes: the lane →
+ * clip grouping (`tracks`, ascending), per-lane visual styles, the ascending
+ * `trackOrder`, and the z-override badge set. Extracted from Timeline.tsx as a
+ * cohesive unit (600-line studio cap); each memo keys on the expanded display
+ * element set exactly as before.
+ */
+export function useTimelineTrackDerivations(expandedElements: TimelineElement[]): {
+  tracks: [number, TimelineElement[]][];
+  trackStyles: Map<number, TrackVisualStyle>;
+  trackOrder: number[];
+} {
+  const tracks = useMemo(() => {
+    const map = new Map<number, TimelineElement[]>();
+    for (const el of expandedElements) {
+      const list = map.get(el.track) ?? [];
+      list.push(el);
+      map.set(el.track, list);
+    }
+    return Array.from(map.entries()).sort(([a], [b]) => a - b);
+  }, [expandedElements]);
+
+  const trackStyles = useMemo(() => {
+    const map = new Map<number, TrackVisualStyle>();
+    for (const [trackNum, els] of tracks) {
+      map.set(trackNum, getTrackStyle(els[0]?.tag ?? ""));
+    }
+    return map;
+  }, [tracks]);
+
+  const trackOrder = useMemo(() => tracks.map(([trackNum]) => trackNum), [tracks]);
+
+  return { tracks, trackStyles, trackOrder };
+}

package/src/player/components/useTrackGapMenu.ts

@@ -0,0 +1,155 @@
+import { useCallback, useMemo, useState, type MutableRefObject } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { DragCommitDeps } from "./timelineClipDragCommit";
+import {
+  laneGapFloor,
+  resolveAllGapIntervals,
+  resolveAllTrackGaps,
+  resolveCloseGapShifts,
+  resolveTrackGapAt,
+  type TrackGapInterval,
+} from "./timelineGaps";
+import {
+  canShiftTrackGapClips,
+  commitCloseAllTrackGaps,
+  commitCloseTrackGap,
+} from "./timelineGapCommit";
+
+/** Right-click anchor on EMPTY lane space: pointer position + clicked lane/time. */
+interface TrackGapMenuAnchor {
+  x: number;
+  y: number;
+  track: number;
+  time: number;
+}
+
+/** Gap strips to paint on one lane while a menu row is hovered. */
+export interface TrackGapHighlight {
+  track: number;
+  intervals: TrackGapInterval[];
+}
+
+/**
+ * Track-gap context menu (right-click on empty lane space) — state, the
+ * derived menu model, and the two commit actions. Extracted from Timeline.tsx
+ * as a cohesive unit (600-line studio cap); behavior identical.
+ *
+ * Only the ANCHOR (and the hovered row) is state; the menu model (gap under
+ * the pointer, compaction, movability) derives from live `tracks` so an open
+ * menu reflects concurrent edits. `gapHighlight` — the strips TimelineCanvas
+ * paints while "Close gap" / "Close all gaps" is hovered — derives the same
+ * way. Commits are ONE atomic batch each via the existing move-persist
+ * pipeline (see timelineGapCommit.ts).
+ */
+export function useTrackGapMenu({
+  tracks,
+  expandedElementsRef,
+  trackOrderRef,
+  onMoveElement,
+  onMoveElements,
+}: {
+  tracks: [number, TimelineElement[]][];
+  expandedElementsRef: MutableRefObject<TimelineElement[]>;
+  trackOrderRef: MutableRefObject<number[]>;
+  onMoveElement: DragCommitDeps["onMoveElement"];
+  onMoveElements: DragCommitDeps["onMoveElements"];
+}) {
+  const updateElement = usePlayerStore((s) => s.updateElement);
+  const [gapContextMenu, setGapContextMenu] = useState<TrackGapMenuAnchor | null>(null);
+  const [hoveredGapAction, setHoveredGapAction] = useState<"close-gap" | "close-all" | null>(null);
+
+  const gapMenuLaneElements = useMemo(
+    () => (gapContextMenu ? (tracks.find(([t]) => t === gapContextMenu.track)?.[1] ?? []) : null),
+    [gapContextMenu, tracks],
+  );
+  const gapMenuModel = useMemo(() => {
+    if (!gapContextMenu || !gapMenuLaneElements) return null;
+    const floor = laneGapFloor(gapMenuLaneElements);
+    const gap = resolveTrackGapAt(gapMenuLaneElements, gapContextMenu.time, undefined, floor);
+    const allShifts = resolveAllTrackGaps(gapMenuLaneElements, undefined, floor);
+    return {
+      x: gapContextMenu.x,
+      y: gapContextMenu.y,
+      gapWidth: gap ? gap.gapEnd - gap.gapStart : null,
+      canCloseGap:
+        gap != null &&
+        canShiftTrackGapClips(gapMenuLaneElements, resolveCloseGapShifts(gapMenuLaneElements, gap)),
+      hasAnyGaps: allShifts.length > 0,
+      canCloseAllGaps:
+        allShifts.length > 0 && canShiftTrackGapClips(gapMenuLaneElements, allShifts),
+    };
+  }, [gapContextMenu, gapMenuLaneElements]);
+
+  // The strips to paint while a menu row is hovered: the one gap under the
+  // pointer for "Close gap", every current gap (leading included) for
+  // "Close all gaps". Null when nothing is hovered / nothing would close.
+  const gapHighlight = useMemo<TrackGapHighlight | null>(() => {
+    if (!gapContextMenu || !gapMenuLaneElements || !hoveredGapAction) return null;
+    const floor = laneGapFloor(gapMenuLaneElements);
+    if (hoveredGapAction === "close-gap") {
+      const gap = resolveTrackGapAt(gapMenuLaneElements, gapContextMenu.time, undefined, floor);
+      if (!gap) return null;
+      return {
+        track: gapContextMenu.track,
+        intervals: [{ start: gap.gapStart, end: gap.gapEnd }],
+      };
+    }
+    const intervals = resolveAllGapIntervals(gapMenuLaneElements, undefined, floor);
+    return intervals.length > 0 ? { track: gapContextMenu.track, intervals } : null;
+  }, [gapContextMenu, gapMenuLaneElements, hoveredGapAction]);
+
+  const closeTrackGap = useCallback(() => {
+    if (!gapContextMenu || !gapMenuLaneElements) return;
+    commitCloseTrackGap(gapMenuLaneElements, gapContextMenu.time, {
+      elements: expandedElementsRef.current,
+      trackOrder: trackOrderRef.current,
+      updateElement,
+      onMoveElement,
+      onMoveElements,
+    });
+  }, [
+    gapContextMenu,
+    gapMenuLaneElements,
+    expandedElementsRef,
+    trackOrderRef,
+    updateElement,
+    onMoveElement,
+    onMoveElements,
+  ]);
+  const closeAllTrackGaps = useCallback(() => {
+    if (!gapMenuLaneElements) return;
+    commitCloseAllTrackGaps(gapMenuLaneElements, {
+      elements: expandedElementsRef.current,
+      trackOrder: trackOrderRef.current,
+      updateElement,
+      onMoveElement,
+      onMoveElements,
+    });
+  }, [
+    gapMenuLaneElements,
+    expandedElementsRef,
+    trackOrderRef,
+    updateElement,
+    onMoveElement,
+    onMoveElements,
+  ]);
+
+  const openGapMenu = useCallback((anchor: TrackGapMenuAnchor) => {
+    setHoveredGapAction(null);
+    setGapContextMenu(anchor);
+  }, []);
+  const dismissGapMenu = useCallback(() => {
+    setHoveredGapAction(null);
+    setGapContextMenu(null);
+  }, []);
+
+  return {
+    gapMenuModel,
+    gapHighlight,
+    setHoveredGapAction,
+    openGapMenu,
+    dismissGapMenu,
+    closeTrackGap,
+    closeAllTrackGaps,
+  };
+}

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

@@ -152,10 +152,34 @@ describe("buildExpandedElements", () => {
       ["pill-3", "group-1"],
     ]);
     const domClipChildren = [
-      { id: "group-1", parentId: "scene-host", hostId: "scene-host", label: "Group 1" },
-      { id: "pill-1", parentId: "group-1", hostId: "scene-host", label: "pill-1" },
-      { id: "pill-2", parentId: "group-1", hostId: "scene-host", label: "pill-2" },
-      { id: "pill-3", parentId: "group-1", hostId: "scene-host", label: "pill-3" },
+      {
+        id: "group-1",
+        parentId: "scene-host",
+        hostId: "scene-host",
+        label: "Group 1",
+        stackingContextId: "css:0",
+      },
+      {
+        id: "pill-1",
+        parentId: "group-1",
+        hostId: "scene-host",
+        label: "pill-1",
+        stackingContextId: "css:0.0",
+      },
+      {
+        id: "pill-2",
+        parentId: "group-1",
+        hostId: "scene-host",
+        label: "pill-2",
+        stackingContextId: "css:0.1",
+      },
+      {
+        id: "pill-3",
+        parentId: "group-1",
+        hostId: "scene-host",
+        label: "pill-3",
+        stackingContextId: "css:0.1",
+      },
     ];
 
     // Expanding pill-3's siblings: topLevel scene-host, immediate parent group-1.
@@ -173,6 +197,7 @@ describe("buildExpandedElements", () => {
     expect(pills[0]!.start).toBe(5);
     expect(pills[0]!.duration).toBe(6);
     expect(pills[0]!.sourceFile).toBe("scene.html");
+    expect(pills.map((pill) => pill.stackingContextId)).toEqual(["css:0.0", "css:0.1", "css:0.1"]);
     // The host row is replaced by its children.
     expect(out.some((e) => e.domId === "scene-host")).toBe(false);
   });
@@ -273,3 +298,41 @@ describe("resolveTimelineExpansionRawId", () => {
     ).toBe("caption");
   });
 });
+
+describe("buildExpandedElements — collision-free synthetic rows (cross-file lane safety)", () => {
+  it("expanded children NEVER share a display track with an unrelated top-level clip", () => {
+    // The Deepwork regression: host on track 0 with two children used to put
+    // child #2 on integer track 1 — the same lane as index.html#foreign. Lane
+    // grouping merges purely by track number, so a gap-close on that "one"
+    // lane batch-persisted a foreign file's clip.
+    const elements = [
+      el({ id: "host", start: 0, duration: 20, track: 0, compositionSrc: "scene.html" }),
+      el({ id: "foreign", start: 20, duration: 5, track: 1 }),
+    ];
+    const manifest = [
+      clip({ id: "host", start: 0, duration: 20, compositionSrc: "scene.html" }),
+      clip({ id: "c1", start: 0, duration: 5 }),
+      clip({ id: "c2", start: 10, duration: 5 }),
+    ];
+    const parentMap = new Map([
+      ["c1", "host"],
+      ["c2", "host"],
+    ]);
+
+    const out = buildExpandedElements(elements, manifest, parentMap, "host", "host");
+    const foreign = out.find((e) => e.id === "foreign")!;
+    const children = out.filter((e) => e.domId === "c1" || e.domId === "c2");
+    expect(children).toHaveLength(2);
+    for (const child of children) {
+      // No lane sharing with the foreign clip…
+      expect(child.track).not.toBe(foreign.track);
+      // …and structurally impossible to collide with ANY normalized (integer)
+      // lane: synthetic rows are strict fractions under the host's lane.
+      expect(Number.isInteger(child.track)).toBe(false);
+      expect(child.track).toBeGreaterThan(0);
+      expect(child.track).toBeLessThan(1);
+    }
+    // Distinct ordered rows per child.
+    expect(children[0].track).not.toBe(children[1].track);
+  });
+});

package/src/player/hooks/useExpandedTimelineElements.ts

@@ -163,7 +163,24 @@ function buildChildElements(
       key,
       start: clamped.start,
       duration: clamped.duration,
-      track: display.track + result.length,
+      // `track` becomes a synthetic display row under the expanded host, but the
+      // factory-set `authoredTrack` (the child's data-track-index in ITS OWN
+      // file's coordinate space) and the runtime-computed `stackingContextId`
+      // must survive verbatim — lane persists and z-sync read them, they are
+      // never reconstructed from display lanes.
+      //
+      // COLLISION-FREE synthetic rows: the old `display.track + index` scheme
+      // could equal a REAL clip's integer lane (host on track 0 with two
+      // children puts child #2 on track 1 — where an unrelated top-level clip
+      // may live). Lane grouping merges purely by track number, so that
+      // collision fused clips from DIFFERENT source files into one display
+      // lane, and lane-scoped actions (gap close) then batch-persisted foreign
+      // clips. Fractions strictly between the host's lane and the next integer
+      // can never equal a normalized (integer) lane, while still rendering the
+      // children as their own ordered rows directly under the host.
+      track: display.track + (result.length + 1) / (siblings.length + 2),
+      authoredTrack: base.authoredTrack,
+      stackingContextId: base.stackingContextId,
       expandedParentStart: editBasis.start,
       domId,
       selector,
@@ -198,6 +215,7 @@ function domSiblingClips(
         parentCompositionId: host.id ?? null,
         compositionSrc: host.compositionSrc ?? null,
         assetUrl: null,
+        stackingContextId: c.stackingContextId,
       }),
     );
 }

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

@@ -153,6 +153,61 @@ describe("useTimelinePlayer seek hydration", () => {
     unmountWithAct(root);
     unsubscribe();
   });
+
+  it("does not settle from an unsupported runtime protocol message", () => {
+    const { api, root } = renderTimelinePlayerHarness();
+    const iframe = document.createElement("iframe");
+    const iframeWindow = {
+      postMessage: vi.fn(),
+      scrollTo: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    } as Record<string, unknown>;
+    Object.defineProperty(iframe, "contentWindow", {
+      value: iframeWindow,
+      configurable: true,
+    });
+    Object.defineProperty(iframe, "contentDocument", {
+      value: document.implementation.createHTMLDocument("preview"),
+      configurable: true,
+    });
+
+    act(() => {
+      api.iframeRef.current = iframe;
+      api.onIframeLoad();
+    });
+    expect(usePlayerStore.getState().timelineReady).toBe(false);
+
+    iframeWindow.__player = {
+      play: vi.fn(),
+      pause: vi.fn(),
+      seek: vi.fn(),
+      getTime: () => 0,
+      getDuration: () => 30,
+      isPlaying: () => false,
+    };
+    act(() => {
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          source: iframeWindow as unknown as Window,
+          data: { source: "hf-preview", type: "state", protocolVersion: 999 },
+        }),
+      );
+    });
+    expect(usePlayerStore.getState().timelineReady).toBe(false);
+
+    act(() => {
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          source: iframeWindow as unknown as Window,
+          data: { source: "hf-preview", type: "state" },
+        }),
+      );
+    });
+    expect(usePlayerStore.getState().timelineReady).toBe(true);
+
+    unmountWithAct(root);
+  });
 });
 
 describe("useTimelinePlayer audio controls (#835)", () => {

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

@@ -437,12 +437,19 @@ describe("anonymous timeline identity", () => {
 });
 
 describe("mergeTimelineElementsPreservingDowngrades", () => {
-  it("preserves missing current elements when a shorter manifest arrives", () => {
+  it("preserves missing sub-composition elements when a shorter manifest arrives", () => {
     expect(
       mergeTimelineElementsPreservingDowngrades(
         [
           { id: "hero", tag: "div", start: 0, duration: 4, track: 0 },
-          { id: "cta", tag: "div", start: 4, duration: 2, track: 1 },
+          {
+            id: "cta",
+            tag: "div",
+            start: 4,
+            duration: 2,
+            track: 1,
+            compositionSrc: "scenes/cta.html",
+          },
         ],
         [{ id: "hero", tag: "div", start: 0, duration: 4, track: 0 }],
         8,
@@ -450,10 +457,31 @@ describe("mergeTimelineElementsPreservingDowngrades", () => {
       ),
     ).toEqual([
       { id: "hero", tag: "div", start: 0, duration: 4, track: 0 },
-      { id: "cta", tag: "div", start: 4, duration: 2, track: 1 },
+      {
+        id: "cta",
+        tag: "div",
+        start: 4,
+        duration: 2,
+        track: 1,
+        compositionSrc: "scenes/cta.html",
+      },
     ]);
   });
 
+  it("drops missing top-level elements so undo does not leave ghost clips", () => {
+    expect(
+      mergeTimelineElementsPreservingDowngrades(
+        [
+          { id: "hero", tag: "div", start: 0, duration: 4, track: 0 },
+          { id: "split-clone", tag: "div", start: 4, duration: 2, track: 1 },
+        ],
+        [{ id: "hero", tag: "div", start: 0, duration: 4, track: 0 }],
+        8,
+        8,
+      ),
+    ).toEqual([{ id: "hero", tag: "div", start: 0, duration: 4, track: 0 }]);
+  });
+
   it("accepts longer-duration or same-size updates as authoritative", () => {
     expect(
       mergeTimelineElementsPreservingDowngrades(
@@ -477,6 +505,7 @@ describe("mergeTimelineElementsPreservingDowngrades", () => {
             start: 0,
             duration: 3,
             track: 0,
+            compositionSrc: "scenes/cards.html",
           },
           {
             id: "Card",
@@ -486,6 +515,7 @@ describe("mergeTimelineElementsPreservingDowngrades", () => {
             start: 3,
             duration: 3,
             track: 1,
+            compositionSrc: "scenes/cards.html",
           },
         ],
         [
@@ -497,6 +527,7 @@ describe("mergeTimelineElementsPreservingDowngrades", () => {
             start: 0,
             duration: 3,
             track: 0,
+            compositionSrc: "scenes/cards.html",
           },
         ],
         8,
@@ -511,6 +542,7 @@ describe("mergeTimelineElementsPreservingDowngrades", () => {
         start: 0,
         duration: 3,
         track: 0,
+        compositionSrc: "scenes/cards.html",
       },
       {
         id: "Card",
@@ -520,6 +552,7 @@ describe("mergeTimelineElementsPreservingDowngrades", () => {
         start: 3,
         duration: 3,
         track: 1,
+        compositionSrc: "scenes/cards.html",
       },
     ]);
   });