@hyperframes/studio 0.8.74 → 0.8.76

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

@@ -8,11 +8,6 @@ import {
   type DragCommitDeps,
   type TimelineMoveEdit,
 } from "./timelineClipDragCommit";
-import {
-  buildEditHistoryEntry,
-  createEmptyEditHistory,
-  pushEditHistoryEntry,
-} from "../../utils/editHistory";
 import { normalizeToZones } from "./timelineZones";
 import { resolveZMirrorLaneMove } from "./timelineZMirror";
 import type { StackingPatch } from "./timelineStackingSync";
@@ -1151,48 +1146,21 @@ describe("commitDraggedClipMove", () => {
       return { onMoveElements, onStackingPatches };
     };
 
-    it("threads ONE shared coalesceKey to both the move persist and the z-sync, so the two records merge into a single undo entry", async () => {
+    it("threads ONE shared coalesceKey to both the move persist and the z-sync, so the server can fold them into a single undo entry", async () => {
       const { onMoveElements, onStackingPatches } = commitLaneChange(overlapping());
       await flushMicrotasks();
 
-      // Both sides receive the SAME non-empty gesture key (second arg).
+      // Both sides receive the SAME non-empty gesture key (second arg). That
+      // shared, non-empty coalesceKey is what lets the server
+      // (projectHistory.ts, "claim: a writer that records after writing")
+      // fold the "Move timeline clips" write and the "Reorder layers" z patch,
+      // both to the same file, into one undo entry — folding itself is the
+      // server's own tested behaviour, not re-proven here via a reducer.
       const moveKey = onMoveElements.mock.calls[0][1];
       const zKey = onStackingPatches.mock.calls[0][1];
       expect(typeof moveKey).toBe("string");
       expect(moveKey).not.toBe("");
       expect(zKey).toBe(moveKey);
-
-      // With that shared key, editHistory folds the two consecutive records (the
-      // "Move timeline clips" write + the "Reorder layers" z patch, same file,
-      // inside the coalesce window) into ONE undo entry spanning before→after.
-      const now = 1_000;
-      const moveEntry = buildEditHistoryEntry({
-        id: "m",
-        projectId: "p",
-        label: "Move timeline clips",
-        kind: "timeline",
-        coalesceKey: moveKey,
-        now,
-        files: { "index.html": { before: "<v0>", after: "<v1>" } },
-      });
-      const zEntry = buildEditHistoryEntry({
-        id: "z",
-        projectId: "p",
-        label: "Reorder layers",
-        kind: "timeline",
-        coalesceKey: zKey,
-        now: now + 50,
-        files: { "index.html": { before: "<v1>", after: "<v2>" } },
-      });
-      const state = pushEditHistoryEntry(
-        pushEditHistoryEntry(createEmptyEditHistory(), moveEntry),
-        zEntry,
-      );
-      expect(state.undo).toHaveLength(1);
-      expect(state.undo[0].files["index.html"]).toMatchObject({
-        before: "<v0>",
-        after: "<v2>",
-      });
     });
 
     it("distinct gestures get distinct keys (independent moves never cross-merge)", async () => {

package/src/player/components/useSettledScrollLeft.ts

@@ -0,0 +1,38 @@
+import { useCallback, useRef, useSyncExternalStore, type RefObject } from "react";
+import { TIMELINE_SCROLL_SETTLE_MS } from "./useTimelineScrollViewport";
+
+// The timeline viewport's scrollLeft once a scroll settles, or null while it is scrolling. Readers
+// re-render twice per gesture, never per frame: per-frame work cost 2-3x the viewport gate's budget
+// on a large unvirtualized timeline.
+export function useSettledScrollLeft(scrollRef: RefObject<HTMLDivElement | null>): number | null {
+  const scrollingRef = useRef(false);
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      const el = scrollRef.current;
+      let settle: ReturnType<typeof setTimeout> | undefined;
+      const onScroll = () => {
+        if (!scrollingRef.current) {
+          scrollingRef.current = true;
+          onChange();
+        }
+        clearTimeout(settle);
+        settle = setTimeout(() => {
+          scrollingRef.current = false;
+          onChange();
+        }, TIMELINE_SCROLL_SETTLE_MS);
+      };
+      el?.addEventListener("scroll", onScroll, { passive: true });
+      return () => {
+        clearTimeout(settle);
+        scrollingRef.current = false;
+        el?.removeEventListener("scroll", onScroll);
+      };
+    },
+    [scrollRef],
+  );
+  return useSyncExternalStore(
+    subscribe,
+    () => (scrollingRef.current ? null : (scrollRef.current?.scrollLeft ?? 0)),
+    () => null,
+  );
+}

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

@@ -47,6 +47,56 @@ describe("live DOM manifest hydration", () => {
       ).toHaveLength(2);
     }
   });
+  it("binds a root clip to its own element when a mounted sub-composition repeats its id", () => {
+    // The sub-composition's copy comes first in document order, so a bare id lookup finds it.
+    const doc = documentWith(
+      '<div id="strip" data-composition-id="strip" data-composition-src="compositions/strip.html" data-start="0" data-duration="4" data-track-index="1">' +
+        '<video id="frame-1" data-hf-id="hf-inner" data-start="0"></video></div>' +
+        '<video id="frame-1" data-hf-id="hf-root" data-start="6" data-duration="1" data-track-index="7"></video>',
+    );
+    const [element] = buildTimelineElementsFromClips(
+      [
+        clip({
+          id: "frame-1",
+          tagName: "video",
+          kind: "video",
+          start: 6,
+          duration: 1,
+          track: 7,
+          compositionAncestors: ["main"],
+        }),
+      ],
+      doc,
+    );
+    expect([element.hfId, element.sourceFile]).toEqual(["hf-root", undefined]);
+  });
+  it("keeps a unique id bound while its host's composition id is healed after the manifest", () => {
+    // The wrapper's data-composition-id arrived after the runtime recorded the clip's chain as ["main"].
+    const doc = documentWith(
+      '<div id="ho" data-hf-id="ho" data-start="0" data-duration="4"></div>' +
+        '<div id="hs-layer" data-composition-id="hs-comp">' +
+        '<div id="hs" data-hf-id="hs" data-start="0" data-duration="4"></div></div>',
+    );
+    const [element] = buildTimelineElementsFromClips(
+      [clip({ id: "hs", compositionAncestors: ["main"] })],
+      doc,
+    );
+    expect(element.hfId).toBe("hs");
+  });
+  it("binds an id-less host by its composition id over a lone id inside that sub-composition", () => {
+    const doc = documentWith(
+      '<div data-composition-id="card" data-composition-src="compositions/card.html" data-start="0" data-duration="4">' +
+        '<div data-hf-inner-root><div id="card" data-start="0" data-duration="4"></div></div></div>',
+    );
+    const host = doc.querySelector('[data-composition-src="compositions/card.html"]');
+    const card = clip({
+      id: "card",
+      kind: "composition",
+      compositionId: "card",
+      compositionAncestors: ["main"],
+    });
+    expect(findTimelineDomNodeForClip(doc, card, 0)).toBe(host);
+  });
   it("does not bind a cross-tag direct identity", () => {
     const doc = documentWith('<div id="collision" data-start="0" data-duration="4"></div>');
     expect(

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

@@ -43,7 +43,7 @@ function mountScene(): Document {
 
 // A composition clip is keyed by its ELEMENT id, not its `data-composition-id`
 // (the runtime's clip tree publishes `scene-2-slot`), so the collector resolves
-// the host with getElementById(clip.id) exactly as the sibling walk does.
+// the host by clip.id in the clip's own composition, exactly as the sibling walk does.
 const sceneClips = [clip({ id: "scene-2-slot", kind: "composition", compositionId: "scene-2" })];
 
 describe("collectSubCompositionHostState", () => {
@@ -83,6 +83,30 @@ describe("collectSubCompositionHostState", () => {
     expect(state.get("scene-2-video")?.hidden).toBe(true);
   });
 
+  it("reads its own host when an earlier sub-composition repeats the host's id", () => {
+    document.body.innerHTML = `
+      <main data-composition-id="main">
+        <div id="intro-slot" data-composition-id="intro" data-composition-src="intro.html">
+          <div data-hf-inner-root data-composition-id="intro">
+            <div id="scene-2-slot"><p id="intro-note" data-hidden></p></div>
+          </div>
+        </div>
+        <div id="scene-2-slot" data-composition-id="scene-2" data-composition-src="scene-2.html">
+          <div data-hf-inner-root><div id="scene-2-title" data-hidden></div></div>
+        </div>
+      </main>`;
+    const host = clip({
+      id: "scene-2-slot",
+      kind: "composition",
+      compositionId: "scene-2",
+      compositionAncestors: ["main"],
+    });
+
+    expect([...collectSubCompositionHostState(document, [host]).keys()]).toEqual(["scene-2-title"]);
+    const rows = collectSubCompositionDomChildren(document, [host], new Map());
+    expect(rows.map((child) => child.id)).toEqual(["scene-2-title"]);
+  });
+
   it("returns empty without a document, rather than throwing", () => {
     expect(collectSubCompositionHostState(null, sceneClips).size).toBe(0);
   });

package/src/player/hooks/timelineSyncHydration.ts

@@ -9,7 +9,7 @@
  * an argument, so each is callable — and readable — on its own.
  */
 
-import { createTimelineDomNodeResolver } from "../lib/timelineElementHelpers";
+import { createTimelineDomNodeResolver, findClipElementById } from "../lib/timelineElementHelpers";
 import { usePlayerStore } from "../store/playerStore";
 import type { TimelineElement, DomClipChild, SubCompositionHostState } from "../store/playerStore";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
@@ -128,7 +128,7 @@ export function collectSubCompositionDomChildren(
   if (!iframeDoc) return out;
   for (const clip of clips) {
     if (clip.kind !== "composition" || !clip.id) continue;
-    const hostEl = iframeDoc.getElementById(clip.id);
+    const hostEl = findClipElementById(iframeDoc, clip);
     if (!hostEl) continue;
     const innerRoot = hostEl.querySelector("[data-hf-inner-root]") ?? hostEl;
     collectHostDomChildren(clip.id, innerRoot, clip.id, parentMap, out);
@@ -172,7 +172,7 @@ export function collectSubCompositionHostState(
   if (!iframeDoc) return out;
   for (const clip of clips) {
     if (clip.kind !== "composition" || !clip.id) continue;
-    const hostEl = iframeDoc.getElementById(clip.id);
+    const hostEl = findClipElementById(iframeDoc, clip);
     if (!hostEl) continue;
     for (const el of Array.from(hostEl.querySelectorAll("[id]"))) {
       const state = readSubCompositionHostState(el);

package/src/player/hooks/useShadowPreviewReload.ts

@@ -14,6 +14,7 @@ import {
 } from "./useTimelineSyncCallbacks";
 import type { PlaybackAdapter } from "../lib/playbackTypes";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
+import { usePlayerStore } from "../store/playerStore";
 
 // One wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade
 // leaves about 6.5s for the document load and runtime boot. Nothing shorter may fail the swap.
@@ -35,6 +36,8 @@ type UseShadowPreviewReloadParams = Omit<
   onPromoted?: () => void;
   /** A shadow that never became ready was dropped; the live preview is unchanged. */
   onReloadFailed?: (message: string) => void;
+  /** Puts the promoted document at the live frame's time, playing if the live frame was. */
+  handOverPlayback: (time: number, playing: boolean) => void;
 };
 
 export function useShadowPreviewReload({
@@ -51,6 +54,7 @@ export function useShadowPreviewReload({
   applyPreviewAudioState,
   onPromoted,
   onReloadFailed,
+  handOverPlayback,
 }: UseShadowPreviewReloadParams) {
   const shadowIframeRef = useRef<HTMLIFrameElement | null>(null);
   const shadowProbeIntervalRef = useRef<ReturnType<typeof setInterval> | undefined>(undefined);
@@ -62,6 +66,8 @@ export function useShadowPreviewReload({
   onPromotedRef.current = onPromoted;
   const onReloadFailedRef = useRef(onReloadFailed);
   onReloadFailedRef.current = onReloadFailed;
+  const handOverPlaybackRef = useRef(handOverPlayback);
+  handOverPlaybackRef.current = handOverPlayback;
   const readyTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
   const budgetsSpentRef = useRef(0);
   // The shadow still owed a wait budget, so a hidden tab can resume it when it becomes visible.
@@ -102,6 +108,11 @@ export function useShadowPreviewReload({
       const ready = pending?.gen === gen && visuallyReadyGenRef.current === gen;
       if (!shadow || !pending || !ready || gen !== shadowGenRef.current) return;
       stopPendingShadow();
+      // The live frame kept playing, stopped at the end or was seeked while the shadow loaded.
+      const live = getAdapter();
+      const liveTime = live?.getTime();
+      const playing = usePlayerStore.getState().isPlaying;
+      live?.pause();
       // The store takes the new document's timeline only now that it is the one on screen.
       pending.commit();
       iframeRef.current = shadow;
@@ -109,10 +120,17 @@ export function useShadowPreviewReload({
       attachIframeShortcutListeners();
       applyPreviewAudioState();
       setPreviewSlots((prev) => planShadowPromotion(prev, gen));
+      if (liveTime != null) handOverPlaybackRef.current(liveTime, playing);
       onPromotedRef.current?.();
       thumbnailScheduler.setPreviewReloading(false);
     },
-    [stopPendingShadow, iframeRef, attachIframeShortcutListeners, applyPreviewAudioState],
+    [
+      stopPendingShadow,
+      getAdapter,
+      iframeRef,
+      attachIframeShortcutListeners,
+      applyPreviewAudioState,
+    ],
   );
 
   const getShadowAdapter = useCallback(() => getAdapter(shadowIframeRef.current), [getAdapter]);
@@ -201,6 +219,7 @@ export function useShadowPreviewReload({
     shadowIframeRef.current = null;
     isRefreshingRef.current = false;
     pendingSeekRef.current = null;
+    usePlayerStore.getState().setTimelineReady(false);
     setPreviewSlots(planShadowDiscard);
     thumbnailScheduler.setPreviewReloading(false);
   }, [stopPendingShadow, isRefreshingRef, pendingSeekRef]);

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

@@ -0,0 +1,120 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, expect, it, vi } from "vitest";
+import {
+  makeAdapterWindow,
+  makeFakeIframe,
+  renderTimelinePlayerHarness,
+  resetPlayerStore,
+} from "./timelinePlayerTestHarness";
+import { usePlayerStore } from "../store/playerStore";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  resetPlayerStore();
+});
+
+it("does not start playback before the timeline is ready, so iframe load cannot swallow it", () => {
+  const { api, root } = renderTimelinePlayerHarness();
+  const { adapter, win } = makeAdapterWindow();
+  // The runtime has booted (adapter exists) but the iframe's load event has not fired yet.
+  act(() => {
+    api.iframeRef.current = makeFakeIframe(win);
+  });
+
+  act(() => api.play());
+  expect(adapter.play).not.toHaveBeenCalled();
+  expect(usePlayerStore.getState().isPlaying).toBe(false);
+
+  act(() => {
+    api.onIframeLoad();
+    usePlayerStore.setState({ timelineReady: true });
+  });
+  act(() => api.play());
+  expect(adapter.play).toHaveBeenCalledTimes(1);
+  expect(usePlayerStore.getState().isPlaying).toBe(true);
+  act(() => root.unmount());
+});
+
+it("does not start playback while a switched-to composition's preview is still loading", () => {
+  const { api, root } = renderTimelinePlayerHarness();
+  act(() => {
+    api.iframeRef.current = makeFakeIframe(makeAdapterWindow().win);
+    api.onIframeLoad();
+    usePlayerStore.setState({ timelineReady: true });
+  });
+
+  // Drill into another composition: a fresh preview whose runtime is up but whose load step hasn't run.
+  const next = makeAdapterWindow();
+  act(() => {
+    api.resetPreviewSlots();
+    api.iframeRef.current = makeFakeIframe(next.win);
+  });
+  act(() => api.play());
+  expect(next.adapter.play).not.toHaveBeenCalled();
+  expect(usePlayerStore.getState().isPlaying).toBe(false);
+  act(() => root.unmount());
+});
+
+function postFromRuntime(win: object, data: Record<string, unknown>) {
+  act(() => {
+    window.dispatchEvent(
+      new MessageEvent("message", {
+        source: win as unknown as Window,
+        data: { source: "hf-preview", ...data },
+      }),
+    );
+  });
+}
+
+async function expectPlayStillOff() {
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  expect(usePlayerStore.getState().timelineReady).toBe(false);
+}
+
+// Duration 0: the adapter cannot enable Play itself, so only the message path can, after the load step.
+it.each([30, 0])(
+  "waits for the preview's load step before a timeline message enables Play (adapter duration %i)",
+  async (duration) => {
+    const { api, root } = renderTimelinePlayerHarness();
+    const { win } = makeAdapterWindow({ duration });
+    act(() => {
+      api.iframeRef.current = makeFakeIframe(win);
+    });
+    // The runtime reports its timeline before the document's load event, as a film with large images does.
+    const clip = { id: "clip", label: "Clip", start: 0, duration: 1, track: 0, kind: "element" };
+    postFromRuntime(win, { type: "timeline", clips: [clip], durationInFrames: 30, fps: 30 });
+    await expectPlayStillOff();
+
+    act(() => api.onIframeLoad());
+    await vi.waitFor(() => expect(usePlayerStore.getState().timelineReady).toBe(true));
+    act(() => root.unmount());
+  },
+);
+
+it("does not let the blank page's load step enable Play for the preview that replaces it", async () => {
+  const { api, root } = renderTimelinePlayerHarness();
+  // The iframe's first load is about:blank, before the runtime exists; its load step waits for runtime messages.
+  const iframe = makeFakeIframe({ ...makeAdapterWindow().win, __player: undefined });
+  act(() => {
+    api.iframeRef.current = iframe;
+    api.onIframeLoad();
+  });
+
+  // The same iframe navigates to the preview, whose runtime reports ready before its own load event.
+  const { win } = makeAdapterWindow();
+  Object.defineProperty(iframe, "contentWindow", { value: win, configurable: true });
+  Object.defineProperty(iframe, "contentDocument", {
+    value: document.implementation.createHTMLDocument("preview"),
+    configurable: true,
+  });
+  postFromRuntime(win, { type: "state" });
+  await expectPlayStillOff();
+
+  act(() => api.onIframeLoad());
+  await vi.waitFor(() => expect(usePlayerStore.getState().timelineReady).toBe(true));
+  act(() => root.unmount());
+});

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

@@ -224,6 +224,91 @@ describe("shadow reload readiness and failure", () => {
     unmount(root);
   });
 
+  it("keeps a playing film playing through a reload, from where the live frame had reached", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    const { adapter: liveAdapter, win } = makeAdapterWindow();
+    act(() => {
+      getApi().iframeRef.current = makeFakeIframe(win);
+      getApi().onIframeLoad();
+    });
+    usePlayerStore.setState({ timelineReady: true });
+    act(() => getApi().play());
+    liveAdapter.pause.mockClear();
+    liveAdapter.seek(4.2);
+
+    act(() => getApi().refreshPlayer());
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+    expect(liveAdapter.pause).not.toHaveBeenCalled();
+
+    liveAdapter.seek(5.5);
+    const gen = getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+    const shadow = makeShadowWithSpies();
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    expect(liveAdapter.pause).toHaveBeenCalled();
+    expect(shadow.adapter.getTime()).toBe(5.5);
+    expect(shadow.adapter.isPlaying()).toBe(true);
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+    unmount(root);
+  });
+
+  it("keeps where a film was paused while the reload loaded", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    const { adapter: liveAdapter, win } = makeAdapterWindow();
+    act(() => {
+      getApi().iframeRef.current = makeFakeIframe(win);
+      getApi().onIframeLoad();
+    });
+    usePlayerStore.setState({ timelineReady: true });
+    act(() => getApi().play());
+    liveAdapter.seek(4.2);
+    act(() => getApi().refreshPlayer());
+
+    liveAdapter.seek(7);
+    act(() => getApi().pause());
+    const gen = getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+    const shadow = makeShadowWithSpies();
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    expect(shadow.adapter.getTime()).toBe(7);
+    expect(shadow.adapter.isPlaying()).toBe(false);
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    unmount(root);
+  });
+
+  it("stops a playing film at the new end when the edit cut it short of the live time", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    const { adapter: liveAdapter, win } = makeAdapterWindow();
+    act(() => {
+      getApi().iframeRef.current = makeFakeIframe(win);
+      getApi().onIframeLoad();
+    });
+    usePlayerStore.setState({ timelineReady: true });
+    act(() => getApi().play());
+    act(() => getApi().refreshPlayer());
+
+    liveAdapter.seek(12);
+    const gen = getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+    const shorter = makeAdapterWindow({ duration: 10 });
+    act(() => {
+      getApi().setShadowIframeNode(makeFakeIframe(shorter.win));
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(shorter.adapter.getTime()).toBe(10);
+    expect(shorter.adapter.isPlaying()).toBe(false);
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    unmount(root);
+  });
+
   it("does not promote a shadow whose loader is still up, and promotes once it clears", () => {
     const { getApi, live, gen, root } = beginReload();
     const shadow = makeShadowWithSpies();

package/src/player/hooks/useTimelinePlayer.ts

@@ -180,6 +180,7 @@ export function useTimelinePlayer({
     applyPreviewAudioFlags(iframeRef.current, audioMuted, audioVolume);
   }, []);
   const play = useCallback(() => {
+    if (!usePlayerStore.getState().timelineReady) return;
     stopRAFLoop();
     stopReverseLoop();
     stopScrubPreviewAudio();
@@ -400,6 +401,13 @@ export function useTimelinePlayer({
     applyPreviewAudioState,
     onPromoted: onShadowPromoted,
     onReloadFailed: onPreviewReloadFailed,
+    handOverPlayback: (time, playing) => {
+      // keepPlaying: move the playhead without the paused-seek audio scrub.
+      seek(time, { keepPlaying: true });
+      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();
+    },
   });
 
   const saveSeekPosition = useCallback(() => {
@@ -422,17 +430,21 @@ export function useTimelinePlayer({
       }
     }
     isRefreshingRef.current = true;
-    stopRAFLoop();
+    // Forward playback runs on in the live frame; the promotion hands it to the new document.
+    const keepPlaying =
+      usePlayerStore.getState().isPlaying && shuttleDirectionRef.current !== "backward";
     stopReverseLoop();
+    if (keepPlaying) return true;
+    stopRAFLoop();
     setIsPlaying(false);
+    return false;
   }, [getAdapter, stopRAFLoop, setIsPlaying, stopReverseLoop]);
   const refreshPlayer = useCallback(() => {
     const iframe = iframeRef.current;
     if (!iframe) return;
     logReload("refreshPlayer", () => ({ stack: new Error("refreshPlayer").stack }));
-    saveSeekPosition();
     // The old iframe is no longer navigated away, so stop its playback (and audio) here.
-    getAdapter()?.pause();
+    if (!saveSeekPosition()) getAdapter()?.pause();
     // The live iframe is never hidden; the reload loads in a shadow and is promoted once painted.
     const src = iframe.src;
     const url = new URL(src, window.location.origin);

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -295,6 +295,8 @@ export function useTimelineSyncCallbacks({
 
   const onIframeLoad = useCallback(
     (context?: number) => {
+      const loadedDoc = safeContentDocument(iframeRef.current);
+      if (loadedDoc) usePlayerStore.getState().markPreviewLoadStep(loadedDoc);
       applyPreviewAudioState();
       if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
       stopWaitingRef.current?.();

package/src/player/lib/timelineElementHelpers.ts

@@ -428,14 +428,50 @@ function nodeMatchesManifestClip(node: Element, clip: ClipManifestClip): boolean
   });
 }
 
-function findTimelineDomNode(doc: Document, id: string): Element | null {
-  return (
-    doc.getElementById(id) ??
-    doc.querySelector(`[data-hf-id="${CSS.escape(id)}"]`) ??
-    doc.querySelector(`[data-composition-id="${CSS.escape(id)}"]`) ??
-    doc.querySelector(`.${CSS.escape(id)}`) ??
-    null
-  );
+/** Whether `node` sits in the composition the clip was read from, the chain the runtime records outermost first
+ * (`resolveNearestCompositionContext` in core's runtime/timeline.ts). A clip without that scope accepts any node. */
+function nodeInClipScope(node: Element, clip: ClipManifestClip): boolean {
+  const scope = clip.compositionAncestors;
+  if (!scope) return true;
+  const ids: string[] = [];
+  for (let cursor = node.parentElement; cursor; cursor = cursor.parentElement) {
+    const id = cursor.getAttribute("data-composition-id");
+    if (id) ids.unshift(id);
+  }
+  return ids.length === scope.length && ids.every((id, index) => id === scope[index]);
+}
+
+/** The first match in the clip's composition across `selectors`; a lone match stands only when none is in scope, as a
+ * healed host can stale the clip's chain for a pass. An id can repeat in a sub-composition earlier in the document. */
+function findInClipScope(
+  doc: Document,
+  clip: ClipManifestClip,
+  selectors: string[],
+): Element | null {
+  let lone: Element | null = null;
+  for (const selector of selectors) {
+    const nodes = Array.from(doc.querySelectorAll(selector));
+    const scoped = nodes.find((node) => nodeInClipScope(node, clip));
+    if (scoped) return scoped;
+    if (nodes.length === 1) lone ??= nodes[0];
+  }
+  return lone;
+}
+
+export function findClipElementById(doc: Document, clip: ClipManifestClip): Element | null {
+  if (!clip.id) return null;
+  const first = doc.getElementById(clip.id);
+  if (!first || nodeInClipScope(first, clip)) return first;
+  return findInClipScope(doc, clip, [`[id="${CSS.escape(clip.id)}"]`]);
+}
+
+function findTimelineDomNode(doc: Document, clip: ClipManifestClip): Element | null {
+  if (!clip.id) return null;
+  const first = doc.getElementById(clip.id);
+  if (first && nodeInClipScope(first, clip)) return first;
+  const id = CSS.escape(clip.id);
+  const byOtherKeys = [`[data-hf-id="${id}"]`, `[data-composition-id="${id}"]`, `.${id}`];
+  return findInClipScope(doc, clip, first ? [`[id="${id}"]`, ...byOtherKeys] : byOtherKeys);
 }
 
 export function findTimelineDomNodeForClip(
@@ -445,7 +481,7 @@ export function findTimelineDomNodeForClip(
   usedNodes = new Set<Element>(),
   getCandidates = () => getTimelineDomNodes(doc),
 ): Element | null {
-  const byIdentity = clip.id ? findTimelineDomNode(doc, clip.id) : null;
+  const byIdentity = findTimelineDomNode(doc, clip);
   if (byIdentity && !usedNodes.has(byIdentity) && nodeMatchesClipTag(byIdentity, clip))
     return byIdentity;