@hyperframes/studio 0.7.55 → 0.7.56

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,
@@ -90,12 +91,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 +213,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 +434,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 +461,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()));

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/index.ts

@@ -6,11 +6,12 @@ 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";
+export type { SelectElementOptions, TimelineElement } from "./store/playerStore";
 
 // Utils
 export { formatTime } from "./lib/time";

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

@@ -3,26 +3,26 @@ import { formatFrameTime, frameToSeconds, secondsToFrame, stepFrameTime, formatT
 
 describe("formatTime", () => {
   it("formats zero seconds", () => {
-    expect(formatTime(0)).toBe("0:00");
+    expect(formatTime(0)).toBe("00:00");
   });
 
   // fallow-ignore-next-line code-duplication
   it("formats seconds less than a minute", () => {
-    expect(formatTime(5)).toBe("0:05");
-    expect(formatTime(30)).toBe("0:30");
-    expect(formatTime(59)).toBe("0:59");
+    expect(formatTime(5)).toBe("00:05");
+    expect(formatTime(30)).toBe("00:30");
+    expect(formatTime(59)).toBe("00:59");
   });
 
   it("formats exact minutes", () => {
-    expect(formatTime(60)).toBe("1:00");
-    expect(formatTime(120)).toBe("2:00");
+    expect(formatTime(60)).toBe("01:00");
+    expect(formatTime(120)).toBe("02:00");
     expect(formatTime(600)).toBe("10:00");
   });
 
   it("formats minutes and seconds", () => {
-    expect(formatTime(65)).toBe("1:05");
-    expect(formatTime(90)).toBe("1:30");
-    expect(formatTime(125)).toBe("2:05");
+    expect(formatTime(65)).toBe("01:05");
+    expect(formatTime(90)).toBe("01:30");
+    expect(formatTime(125)).toBe("02:05");
   });
 
   it("formats large values (over an hour)", () => {
@@ -32,28 +32,28 @@ describe("formatTime", () => {
   });
 
   it("floors fractional seconds", () => {
-    expect(formatTime(0.9)).toBe("0:00");
-    expect(formatTime(1.5)).toBe("0:01");
-    expect(formatTime(59.99)).toBe("0:59");
-    expect(formatTime(60.5)).toBe("1:00");
+    expect(formatTime(0.9)).toBe("00:00");
+    expect(formatTime(1.5)).toBe("00:01");
+    expect(formatTime(59.99)).toBe("00:59");
+    expect(formatTime(60.5)).toBe("01:00");
   });
 
-  it("pads single-digit seconds with leading zero", () => {
-    expect(formatTime(1)).toBe("0:01");
-    expect(formatTime(61)).toBe("1:01");
+  it("pads single-digit minutes and seconds with leading zeros", () => {
+    expect(formatTime(1)).toBe("00:01");
+    expect(formatTime(61)).toBe("01:01");
     expect(formatTime(609)).toBe("10:09");
   });
 
   it("guards against negative values", () => {
-    expect(formatTime(-1)).toBe("0:00");
+    expect(formatTime(-1)).toBe("00:00");
   });
 
   it("guards against NaN", () => {
-    expect(formatTime(NaN)).toBe("0:00");
+    expect(formatTime(NaN)).toBe("00:00");
   });
 
   it("guards against Infinity", () => {
-    expect(formatTime(Infinity)).toBe("0:00");
+    expect(formatTime(Infinity)).toBe("00:00");
   });
 });
 

package/src/player/lib/time.ts

@@ -1,10 +1,14 @@
 export const STUDIO_PREVIEW_FPS = 30;
 
 export function formatTime(time: number): string {
-  if (!Number.isFinite(time) || time < 0) return "0:00";
+  if (!Number.isFinite(time) || time < 0) return "00:00";
   const mins = Math.floor(time / 60);
   const secs = Math.floor(time % 60);
-  return `${mins}:${secs.toString().padStart(2, "0")}`;
+  // Zero-pad minutes as well as seconds so every readout is a stable-width
+  // MM:SS (e.g. "00:44", not "0:44"). Minutes past 99 keep their extra digits
+  // ("120:00"); an hours-style H:MM:SS grouping is applied by callers that need
+  // it (see formatTimelineTickLabel), never here.
+  return `${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
 }
 
 export function secondsToFrame(time: number, fps = STUDIO_PREVIEW_FPS): number {

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

@@ -4,8 +4,13 @@ import {
   createTimelineElementFromManifestClip,
   parseTimelineFromDOM,
   createImplicitTimelineLayersFromDOM,
-  buildStandaloneRootTimelineElement,
+  mergeTimelineElementsPreservingDowngrades,
 } from "./timelineDOM";
+import type { TimelineElement } from "../store/playerStore";
+
+function el(id: string, extra: Partial<TimelineElement> = {}): TimelineElement {
+  return { id, tag: "img", start: 0, duration: 5, track: 0, ...extra };
+}
 
 function makeDoc(html: string): Document {
   const d = document.implementation.createHTMLDocument();
@@ -13,29 +18,6 @@ function makeDoc(html: string): Document {
   return d;
 }
 
-function makeLiveDoc(html: string): Document {
-  document.head.innerHTML = "";
-  document.body.innerHTML = html;
-  return document;
-}
-
-function mockComputedZIndex(doc: Document, zIndexById: ReadonlyMap<string, string>): void {
-  const win = doc.defaultView;
-  if (!win) throw new Error("Expected document window");
-  const original = win.getComputedStyle.bind(win);
-  Object.defineProperty(win, "getComputedStyle", {
-    configurable: true,
-    value: (element: Element, pseudoElt?: string | null) => {
-      const style = original(element, pseudoElt);
-      const zIndex = zIndexById.get(element.id);
-      if (zIndex != null) {
-        Object.defineProperty(style, "zIndex", { configurable: true, value: zIndex });
-      }
-      return style;
-    },
-  });
-}
-
 describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
   it("harvests hfId from a data-start element that has data-hf-id", () => {
     const doc = makeDoc(`
@@ -126,58 +108,6 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
 
     expect(element.hidden).toBe(true);
   });
-
-  it("captures the effective z-index from the live element, not the runtime inline-only value", () => {
-    // The runtime reports inline-only z-index (0 for CSS-rule authored z-index),
-    // which must NOT override the live element's effective z-index — otherwise
-    // the timeline collapses every CSS-styled clip to a z=0 tie and mis-orders.
-    const doc = makeDoc(`
-      <div data-composition-id="root">
-        <div id="hero" class="clip" data-start="0" data-duration="5" style="z-index: 30"></div>
-      </div>
-    `);
-    const hostEl = doc.getElementById("hero");
-
-    const element = createTimelineElementFromManifestClip({
-      clip: {
-        id: "hero",
-        label: "Hero",
-        kind: "element",
-        tagName: "div",
-        start: 0,
-        duration: 5,
-        track: 0,
-        zIndex: 0,
-        compositionId: null,
-        parentCompositionId: null,
-        compositionSrc: null,
-        assetUrl: null,
-      },
-      fallbackIndex: 0,
-      doc,
-      hostEl,
-    });
-
-    expect(element.zIndex).toBe(30);
-    expect(element.hasExplicitZIndex).toBe(true);
-  });
-
-  it("marks parsed inline, CSS-rule, and auto z-index authorship accurately", () => {
-    const doc = makeLiveDoc(`
-      <div data-composition-id="root">
-        <div id="inline" class="clip" data-start="0" data-duration="2" style="z-index: 3"></div>
-        <div id="rule" class="clip" data-start="0" data-duration="2"></div>
-        <div id="auto" class="clip" data-start="0" data-duration="2"></div>
-      </div>
-    `);
-    mockComputedZIndex(doc, new Map([["rule", "12"]]));
-
-    const elements = parseTimelineFromDOM(doc, 10);
-
-    expect(elements.find((el) => el.id === "inline")?.hasExplicitZIndex).toBe(true);
-    expect(elements.find((el) => el.id === "rule")?.hasExplicitZIndex).toBe(true);
-    expect(elements.find((el) => el.id === "auto")?.hasExplicitZIndex).toBe(false);
-  });
 });
 
 describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
@@ -211,31 +141,28 @@ describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
 
     expect(layers).toEqual([]);
   });
+});
 
-  it("marks implicit layer CSS z-index authorship from computed style", () => {
-    const doc = makeLiveDoc(`
-      <div data-composition-id="root">
-        <div id="layer" class="clip"></div>
-      </div>
-    `);
-    mockComputedZIndex(doc, new Map([["layer", "8"]]));
-
-    const layers = createImplicitTimelineLayersFromDOM(doc, 10);
-
-    expect(layers[0]?.zIndex).toBe(8);
-    expect(layers[0]?.hasExplicitZIndex).toBe(true);
+describe("mergeTimelineElementsPreservingDowngrades — genuine removal vs transient downgrade", () => {
+  it("drops a removed TOP-LEVEL element (undo of a split) instead of ghosting it", () => {
+    const current = [el("a"), el("a-split")]; // post-split store: original + clone
+    const next = [el("a")]; // fresh scan of the reverted file: clone gone
+    const merged = mergeTimelineElementsPreservingDowngrades(current, next, 30, 30);
+    expect(merged.map((e) => e.id)).toEqual(["a"]);
   });
-});
 
-describe("buildStandaloneRootTimelineElement", () => {
-  it("marks the standalone root as auto z-index", () => {
-    const root = buildStandaloneRootTimelineElement({
-      compositionId: "root",
-      tagName: "div",
-      rootDuration: 10,
-      iframeSrc: "/preview/comp/index.html",
-    });
+  it("still preserves an enriched sub-composition child a bare re-scan drops", () => {
+    const current = [el("a"), el("sub-child", { compositionSrc: "sub.html" })];
+    const next = [el("a")]; // bare DOM scan misses the enriched sub-comp child
+    const merged = mergeTimelineElementsPreservingDowngrades(current, next, 30, 30);
+    expect(merged.map((e) => e.id).sort()).toEqual(["a", "sub-child"]);
+  });
 
-    expect(root?.hasExplicitZIndex).toBe(false);
+  it("trusts the fresh scan fully when it is not shorter", () => {
+    const current = [el("a"), el("b", { compositionSrc: "sub.html" })];
+    const next = [el("a"), el("c")];
+    expect(
+      mergeTimelineElementsPreservingDowngrades(current, next, 30, 30).map((e) => e.id),
+    ).toEqual(["a", "c"]);
   });
 });