@hyperframes/studio 0.7.55 → 0.7.57

package/src/player/components/useTimelineStackingSync.ts

@@ -0,0 +1,94 @@
+import { useCallback, type RefObject } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import { useDomEditActionsContextOptional } from "../../contexts/DomEditContext";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { findElementForSelection } from "../../components/editor/domEditingElement";
+import { readEffectiveZIndex } from "../../components/editor/canvasContextMenuZOrder";
+import type { StackingPatch } from "./timelineStackingSync";
+
+interface UseTimelineStackingSyncInput {
+  expandedElementsRef: RefObject<TimelineElement[]>;
+}
+
+// Lane ↔ stacking unification (research/STAGE3-NEEDED-WIRING.md). Provision the
+// two deps commitDraggedClipMove accepts so a lane-change drag also patches the
+// edited clip's z-index. Both read the SAME preview iframe + z-order persist path
+// the canvas right-click menu / LayersPanel use, so a timeline lane move and a
+// menu z-edit produce one shared inline-style commit shape. Optional contexts:
+// outside the NLE (standalone <Timeline>) these are null ⇒ deps undefined ⇒ the
+// commit's z-sync is a no-op (backward compatible).
+export function useTimelineStackingSync({ expandedElementsRef }: UseTimelineStackingSyncInput) {
+  const domEditActions = useDomEditActionsContextOptional();
+  const shell = useStudioShellContextOptional();
+  const zSyncPreviewIframeRef = domEditActions?.previewIframeRef ?? null;
+  const handleDomZIndexReorderCommit = domEditActions?.handleDomZIndexReorderCommit;
+  const zSyncActiveCompPath = shell?.activeCompPath ?? null;
+
+  // Resolve a TimelineElement to its live iframe HTMLElement via the same
+  // hfId ?? id ?? selector[selectorIndex] resolver the timeline's DOM patches use.
+  const resolveIframeElement = useCallback(
+    (el: TimelineElement): HTMLElement | null => {
+      const doc = zSyncPreviewIframeRef?.current?.contentDocument ?? null;
+      if (!doc) return null;
+      return findElementForSelection(
+        doc,
+        {
+          hfId: el.hfId,
+          id: el.domId ?? el.id,
+          selector: el.selector,
+          selectorIndex: el.selectorIndex,
+          sourceFile: el.sourceFile,
+        },
+        zSyncActiveCompPath,
+      );
+    },
+    [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) : Number.NaN;
+    },
+    [resolveIframeElement],
+  );
+
+  const applyStackingPatches = useCallback(
+    (patches: StackingPatch[], coalesceKey?: string) => {
+      if (!handleDomZIndexReorderCommit) return;
+      const entries = patches.flatMap((p) => {
+        const el = expandedElementsRef.current.find((e) => (e.key ?? e.id) === p.key);
+        const node = el && resolveIframeElement(el);
+        if (!el || !node) return [];
+        return [
+          {
+            element: node,
+            zIndex: p.zIndex,
+            id: el.domId ?? el.id,
+            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,
+          },
+        ];
+      });
+      // 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.
+      if (entries.length) handleDomZIndexReorderCommit(entries, coalesceKey);
+    },
+    [handleDomZIndexReorderCommit, resolveIframeElement, zSyncActiveCompPath, expandedElementsRef],
+  );
+
+  // Engage the z-sync only when the persist path is present (inside the NLE).
+  const zSyncEnabled = Boolean(handleDomZIndexReorderCommit && zSyncPreviewIframeRef);
+
+  return { readClipZIndex, applyStackingPatches, zSyncEnabled };
+}

package/src/player/hooks/useExpandedTimelineElements.ts

@@ -163,7 +163,14 @@ function buildChildElements(
       key,
       start: clamped.start,
       duration: clamped.duration,
+      // `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.
       track: display.track + result.length,
+      authoredTrack: base.authoredTrack,
+      stackingContextId: base.stackingContextId,
       expandedParentStart: editBasis.start,
       domId,
       selector,
@@ -192,12 +199,9 @@ function domSiblingClips(
         start: host.start,
         duration: host.duration,
         track: host.track,
-        zIndex: 0,
-        stackingContextId: host.stackingContextId ?? host.domId ?? host.id ?? null,
         kind: "element",
         tagName: null,
         compositionId: null,
-        compositionAncestors: host.compositionAncestors ?? [],
         parentCompositionId: host.id ?? null,
         compositionSrc: host.compositionSrc ?? null,
         assetUrl: null,

package/src/player/hooks/usePlaybackKeyboard.ts

@@ -9,6 +9,7 @@
 import { useRef, useCallback } from "react";
 import { useCaptionStore } from "../../captions/store";
 import { shouldIgnorePlaybackShortcutEvent, SHUTTLE_SPEEDS } from "../lib/playbackShortcuts";
+import { canvasNudgeKeysClaimed } from "../../utils/canvasNudgeGate";
 import { usePlayerStore } from "../store/playerStore";
 import { stepFrameTime, STUDIO_PREVIEW_FPS } from "../lib/time";
 import type { PlaybackAdapter } from "../lib/playbackTypes";
@@ -97,6 +98,10 @@ export function usePlaybackKeyboard({
         togglePlay();
         return;
       }
+      // A nudgeable canvas selection owns the arrow keys (DomEditOverlay moves
+      // the element); frame-stepping would double-handle the same keystroke.
+      const arrowStep = e.code === "ArrowLeft" || e.code === "ArrowRight";
+      if (arrowStep && canvasNudgeKeysClaimed()) return;
       if (e.code === "ArrowLeft") {
         e.preventDefault();
         stepFrames(e.shiftKey ? -10 : -1);

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",
       },
     ]);
   });

package/src/player/hooks/useTimelinePlayer.ts

@@ -3,6 +3,7 @@ import { usePlayerStore, liveTime, type TimelineElement } from "../store/playerS
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
 import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
+import { useTimelinePlayerLoop } from "./useTimelinePlayerLoop";
 
 export type { ClipManifestClip } from "../lib/playbackTypes";
 export { createStaticSeekPlaybackAdapter } from "../lib/playbackAdapter";
@@ -15,7 +16,6 @@ export {
   parseTimelineFromDOM,
   readTimelineDurationFromDocument,
   resolveStandaloneRootCompositionSrc,
-  resolveIframe,
 } from "../lib/timelineDOM";
 export {
   shouldIgnorePlaybackShortcutEvent,
@@ -36,6 +36,7 @@ import {
   mergeTimelineElementsPreservingDowngrades,
   parseTimelineFromDOM,
 } from "../lib/timelineDOM";
+import { normalizeToZones } from "../components/timelineZones";
 import {
   setPreviewMediaMuted,
   setPreviewPlaybackRate,
@@ -45,6 +46,7 @@ import { scrubMusicAtSeek, stopScrubPreviewAudio } from "../lib/playbackScrub";
 import { applyCachedSourceDurations, probeMissingSourceDurations } from "../lib/mediaProbe";
 import { shouldResumeForwardPlaybackAfterSeek, shouldStopAfterSeek } from "../lib/playbackSeek";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
+import { acceptStudioRuntimeMessage } from "../lib/runtimeProtocol";
 
 /**
  * Whether the derived elements differ from the current ones in any field that
@@ -90,12 +92,17 @@ export function useTimelinePlayer() {
       // applyCachedSourceDurations re-applies the cached probe duration: re-derived
       // elements (e.g. after a clip move) can arrive without sourceDuration, which
       // otherwise makes trimmed waveforms lose their window.
-      const mergedElements = applyCachedSourceDurations(
-        mergeTimelineElementsPreservingDowngrades(
-          state.elements,
-          elements,
-          state.duration,
-          resolvedDuration,
+      // Enforced CapCut zoning (overlay → main → audio): normalize track indices
+      // on every discovery. Idempotent — already-zoned input is returned as-is, so
+      // drops persist zoned indices and reloads re-zone to the same (no drift).
+      const mergedElements = normalizeToZones(
+        applyCachedSourceDurations(
+          mergeTimelineElementsPreservingDowngrades(
+            state.elements,
+            elements,
+            state.duration,
+            resolvedDuration,
+          ),
         ),
       );
 
@@ -207,49 +214,14 @@ export function useTimelinePlayer() {
     }
   }, []);
 
-  const stopReverseLoop = useCallback(() => {
-    cancelAnimationFrame(reverseRafRef.current);
-  }, []);
-
-  const startRAFLoop = useCallback(() => {
-    // fallow-ignore-next-line complexity
-    const tick = () => {
-      const adapter = getAdapter();
-      if (adapter) {
-        const rawTime = adapter.getTime();
-        const dur = adapter.getDuration();
-        const time = dur > 0 ? Math.min(rawTime, dur) : rawTime;
-        liveTime.notify(time); // direct DOM updates, no React re-render
-        const { inPoint, outPoint } = usePlayerStore.getState();
-        const rawLoopEnd = outPoint !== null ? Math.min(outPoint, dur) : dur;
-        const rawLoopStart = inPoint !== null ? inPoint : 0;
-        const loopEnd = rawLoopStart < rawLoopEnd ? rawLoopEnd : dur;
-        const loopStart = rawLoopStart < rawLoopEnd ? rawLoopStart : 0;
-        if (time >= loopEnd) {
-          if (usePlayerStore.getState().loopEnabled && dur > 0) {
-            // keepPlaying skips the adapter's implicit pause; play() below is then a no-op.
-            adapter.seek(loopStart, { keepPlaying: true });
-            liveTime.notify(loopStart);
-            adapter.play();
-            setIsPlaying(true);
-            rafRef.current = requestAnimationFrame(tick);
-            return;
-          }
-          if (adapter.isPlaying()) adapter.pause();
-          setCurrentTime(time); // sync Zustand once at end
-          setIsPlaying(false);
-          cancelAnimationFrame(rafRef.current);
-          return;
-        }
-      }
-      rafRef.current = requestAnimationFrame(tick);
-    };
-    rafRef.current = requestAnimationFrame(tick);
-  }, [getAdapter, setCurrentTime, setIsPlaying]);
+  const { startRAFLoop, stopRAFLoop, stopReverseLoop } = useTimelinePlayerLoop({
+    rafRef,
+    reverseRafRef,
+    getAdapter,
+    setCurrentTime,
+    setIsPlaying,
+  });
 
-  const stopRAFLoop = useCallback(() => {
-    cancelAnimationFrame(rafRef.current);
-  }, []);
   const applyPlaybackRate = useCallback((rate: number) => {
     const iframe = iframeRef.current;
     if (!iframe) return;
@@ -463,10 +435,24 @@ export function useTimelinePlayer() {
       applyPreviewAudioState,
     });
   const saveSeekPosition = useCallback(() => {
-    const adapter = getAdapter();
-    pendingSeekRef.current = adapter
-      ? adapter.getTime()
-      : (usePlayerStore.getState().currentTime ?? 0);
+    // Never DEGRADE the saved position. Overlapping reloads (e.g. an external
+    // file drop = upload reload + insert reload back-to-back) call this while
+    // the iframe from the FIRST reload is mid-teardown: getAdapter() can still
+    // return that dying document's adapter, whose getTime() reads 0 — and the
+    // store's currentTime can lag the visual playhead. Overwriting the
+    // still-unconsumed pendingSeek with either value is exactly how the
+    // playhead used to end up at 0 after a Finder drop (verified live via a
+    // currentTime write-trace). So: while a refresh is already in flight and a
+    // save exists, keep it; otherwise trust the live adapter, then the store.
+    const refreshInFlight = isRefreshingRef.current && pendingSeekRef.current != null;
+    if (!refreshInFlight) {
+      const adapter = getAdapter();
+      if (adapter) {
+        pendingSeekRef.current = adapter.getTime();
+      } else if (pendingSeekRef.current == null) {
+        pendingSeekRef.current = usePlayerStore.getState().currentTime ?? 0;
+      }
+    }
     isRefreshingRef.current = true;
     stopRAFLoop();
     stopReverseLoop();
@@ -476,6 +462,16 @@ export function useTimelinePlayer() {
     const iframe = iframeRef.current;
     if (!iframe) return;
     saveSeekPosition();
+    // Hide the iframe across the full reload so the user never sees the reloading
+    // document's RAW DOM (every clip stacked and visible) in the window between the
+    // new document parsing and the runtime initializing + seeking. initializeAdapter
+    // reveals it again right after its restore seek renders the correct frame.
+    // Tradeoff: this shows the parent stage background (a brief "freeze"/blank, on
+    // the order of the reload time ~100-300ms) INSTEAD of the all-clips flash. A
+    // blank is far less jarring than a burst of every asset appearing at once.
+    // Only the FULL-reload edits (drops/inserts) hit this — timing edits now take
+    // the soft-reload path and never touch refreshPlayer.
+    iframe.style.visibility = "hidden";
     const src = iframe.src;
     const url = new URL(src, window.location.origin);
     url.searchParams.set("_t", String(Date.now()));
@@ -497,6 +493,9 @@ export function useTimelinePlayer() {
       if (e.source && ourIframe && e.source !== ourIframe.contentWindow) {
         return;
       }
+      if (data?.source === "hf-preview") {
+        if (!acceptStudioRuntimeMessage(data)) return;
+      }
       if (data?.source === "hf-preview" && data?.type === "state") {
         try {
           if (usePlayerStore.getState().elements.length === 0) {

package/src/player/hooks/useTimelinePlayerLoop.ts

@@ -0,0 +1,85 @@
+/**
+ * The forward playback loop for the timeline player.
+ *
+ * Owns the three requestAnimationFrame lifecycle callbacks that drive (and stop)
+ * playback:
+ *  - startRAFLoop     — the forward tick: advance liveTime, honour in/out loop
+ *                       points + loopEnabled, and pause + sync the store at the end.
+ *  - stopRAFLoop      — cancel the forward tick.
+ *  - stopReverseLoop  — cancel the reverse-shuttle tick (owned by the parent hook).
+ *
+ * Called unconditionally at the top level of useTimelinePlayer so its useCallback
+ * hooks run in a stable order; every dependency is passed in as an argument.
+ */
+
+import { useCallback } from "react";
+import { liveTime, usePlayerStore } from "../store/playerStore";
+import type { PlaybackAdapter } from "../lib/playbackTypes";
+
+interface UseTimelinePlayerLoopParams {
+  rafRef: React.MutableRefObject<number>;
+  reverseRafRef: React.MutableRefObject<number>;
+  getAdapter: () => PlaybackAdapter | null;
+  setCurrentTime: (v: number) => void;
+  setIsPlaying: (v: boolean) => void;
+}
+
+interface UseTimelinePlayerLoopResult {
+  startRAFLoop: () => void;
+  stopRAFLoop: () => void;
+  stopReverseLoop: () => void;
+}
+
+export function useTimelinePlayerLoop({
+  rafRef,
+  reverseRafRef,
+  getAdapter,
+  setCurrentTime,
+  setIsPlaying,
+}: UseTimelinePlayerLoopParams): UseTimelinePlayerLoopResult {
+  const stopReverseLoop = useCallback(() => {
+    cancelAnimationFrame(reverseRafRef.current);
+  }, [reverseRafRef]);
+
+  const startRAFLoop = useCallback(() => {
+    // fallow-ignore-next-line complexity
+    const tick = () => {
+      const adapter = getAdapter();
+      if (adapter) {
+        const rawTime = adapter.getTime();
+        const dur = adapter.getDuration();
+        const time = dur > 0 ? Math.min(rawTime, dur) : rawTime;
+        liveTime.notify(time); // direct DOM updates, no React re-render
+        const { inPoint, outPoint } = usePlayerStore.getState();
+        const rawLoopEnd = outPoint !== null ? Math.min(outPoint, dur) : dur;
+        const rawLoopStart = inPoint !== null ? inPoint : 0;
+        const loopEnd = rawLoopStart < rawLoopEnd ? rawLoopEnd : dur;
+        const loopStart = rawLoopStart < rawLoopEnd ? rawLoopStart : 0;
+        if (time >= loopEnd) {
+          if (usePlayerStore.getState().loopEnabled && dur > 0) {
+            // keepPlaying skips the adapter's implicit pause; play() below is then a no-op.
+            adapter.seek(loopStart, { keepPlaying: true });
+            liveTime.notify(loopStart);
+            adapter.play();
+            setIsPlaying(true);
+            rafRef.current = requestAnimationFrame(tick);
+            return;
+          }
+          if (adapter.isPlaying()) adapter.pause();
+          setCurrentTime(time); // sync Zustand once at end
+          setIsPlaying(false);
+          cancelAnimationFrame(rafRef.current);
+          return;
+        }
+      }
+      rafRef.current = requestAnimationFrame(tick);
+    };
+    rafRef.current = requestAnimationFrame(tick);
+  }, [rafRef, getAdapter, setCurrentTime, setIsPlaying]);
+
+  const stopRAFLoop = useCallback(() => {
+    cancelAnimationFrame(rafRef.current);
+  }, [rafRef]);
+
+  return { startRAFLoop, stopRAFLoop, stopReverseLoop };
+}

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -26,6 +26,7 @@ import {
   autoHealMissingCompositionIds,
   buildMissingCompositionElements,
 } from "../lib/timelineIframeHelpers";
+import { acceptedRuntimeMessageFps, inspectStudioRuntimeMessage } from "../lib/runtimeProtocol";
 
 interface UseTimelineSyncCallbacksParams {
   iframeRef: React.RefObject<HTMLIFrameElement | null>;
@@ -132,6 +133,9 @@ export function useTimelineSyncCallbacks({
       clips: ClipManifestClip[];
       durationInFrames: number;
       scenes?: Array<{ id: string; label: string; start: number; duration: number }>;
+      protocolVersion?: unknown;
+      capabilities?: unknown;
+      fps?: unknown;
     }) => {
       if (!data.clips || data.clips.length === 0) {
         return;
@@ -222,7 +226,7 @@ export function useTimelineSyncCallbacks({
           hostEl,
         });
       });
-      const rawDuration = data.durationInFrames / 30;
+      const rawDuration = data.durationInFrames / acceptedRuntimeMessageFps(data);
       // Clamp non-finite or absurdly large durations — the runtime can emit
       // Infinity when it detects a loop-inflated GSAP timeline without an
       // explicit data-duration on the root composition. Floor the manifest total
@@ -418,6 +422,10 @@ export function useTimelineSyncCallbacks({
       if (e.source && iframe && e.source !== iframe.contentWindow) return;
       const data = e.data;
       if (data?.source === "hf-preview" && (data?.type === "state" || data?.type === "timeline")) {
+        // The main message handler owns protocol-error diagnostics. This readiness-only
+        // listener mirrors its acceptance gate without dispatching a duplicate event:
+        // an unsupported runtime must not make the iframe appear successfully settled.
+        if (inspectStudioRuntimeMessage(data).status === "unsupported") return;
         trySettle();
       }
     };

package/src/player/index.ts

@@ -6,11 +6,14 @@ export { VideoThumbnail } from "./components/VideoThumbnail";
 export { CompositionThumbnail } from "./components/CompositionThumbnail";
 
 // Hooks
-export { useTimelinePlayer, resolveIframe } from "./hooks/useTimelinePlayer";
+export { useTimelinePlayer } from "./hooks/useTimelinePlayer";
+export { resolveIframe } from "./lib/timelineDOM";
 
 // Store
 export { usePlayerStore, liveTime } from "./store/playerStore";
-export type { TimelineElement, ZoomMode } from "./store/playerStore";
+// Public library surface; external consumers are invisible to the workspace analyzer.
+// fallow-ignore-next-line unused-exports
+export type { SelectElementOptions, TimelineElement, ZoomMode } from "./store/playerStore";
 
 // Utils
 export { formatTime } from "./lib/time";

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

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  acceptStudioRuntimeMessage,
+  acceptedRuntimeMessageFps,
+  createRuntimeControlMessage,
+  inspectStudioRuntimeMessage,
+  postRuntimeControlMessage,
+} from "./runtimeProtocol";
+
+describe("Studio runtime protocol", () => {
+  it("versions every control message and declares rational fps", () => {
+    expect(createRuntimeControlMessage("seek", { timeSeconds: 1.25 }, 60)).toEqual({
+      source: "hf-parent",
+      type: "control",
+      action: "seek",
+      protocolVersion: 1,
+      capabilities: ["seconds-time", "rational-fps", "seek-keep-playing"],
+      fps: { numerator: 60, denominator: 1 },
+      timeSeconds: 1.25,
+    });
+  });
+
+  it("posts the typed message to the target window", () => {
+    const target = { postMessage: vi.fn() };
+    postRuntimeControlMessage(target as unknown as Window, "pause");
+    expect(target.postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ action: "pause", protocolVersion: 1 }),
+      "*",
+    );
+  });
+
+  it("preserves legacy 30fps messages and rejects unknown majors", () => {
+    expect(inspectStudioRuntimeMessage({ source: "hf-preview" })).toEqual({
+      status: "legacy",
+      fps: 30,
+    });
+    expect(inspectStudioRuntimeMessage({ protocolVersion: 2 })).toMatchObject({
+      status: "unsupported",
+      code: "unsupported_protocol_version",
+    });
+  });
+
+  it("reads explicit fps for accepted timeline messages", () => {
+    const message = createRuntimeControlMessage("pause", {}, 60);
+    expect(acceptedRuntimeMessageFps(message)).toBe(60);
+    expect(acceptStudioRuntimeMessage(message)).toMatchObject({ status: "supported", fps: 60 });
+  });
+});