@hyperframes/studio 0.6.0 → 0.6.2

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -0,0 +1,288 @@
+/**
+ * React callbacks for synchronising the player store from iframe runtime data.
+ *
+ * Covers four related concerns:
+ *  - processTimelineMessage  — turn a clip-manifest postMessage into TimelineElements
+ *  - enrichMissingCompositions — fill gaps the manifest misses (element-ref starts)
+ *  - initializeAdapter        — called after iframe load: seek, set duration, read elements
+ *  - onIframeLoad             — orchestrates initializeAdapter with a message-based fallback
+ */
+
+import { useCallback } from "react";
+import { usePlayerStore } from "../store/playerStore";
+import type { TimelineElement } from "../store/playerStore";
+import type { PlaybackAdapter, ClipManifestClip, IframeWindow } from "../lib/playbackTypes";
+import {
+  parseTimelineFromDOM,
+  createTimelineElementFromManifestClip,
+  findTimelineDomNodeForClip,
+  createImplicitTimelineLayersFromDOM,
+  buildStandaloneRootTimelineElement,
+  mergeTimelineElementsPreservingDowngrades,
+  getTimelineElementSelector,
+} from "../lib/timelineDOM";
+import {
+  normalizePreviewViewport,
+  autoHealMissingCompositionIds,
+  unmutePreviewMedia,
+  buildMissingCompositionElements,
+} from "../lib/timelineIframeHelpers";
+import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
+
+interface UseTimelineSyncCallbacksParams {
+  iframeRef: React.RefObject<HTMLIFrameElement | null>;
+  probeIntervalRef: React.MutableRefObject<ReturnType<typeof setInterval> | undefined>;
+  pendingSeekRef: React.MutableRefObject<number | null>;
+  isRefreshingRef: React.MutableRefObject<boolean>;
+  getAdapter: () => PlaybackAdapter | null;
+  syncTimelineElements: (elements: TimelineElement[], nextDuration?: number) => void;
+  setDuration: (v: number) => void;
+  setCurrentTime: (v: number) => void;
+  setTimelineReady: (v: boolean) => void;
+  setIsPlaying: (v: boolean) => void;
+  attachIframeShortcutListeners: () => void;
+}
+
+export function useTimelineSyncCallbacks({
+  iframeRef,
+  probeIntervalRef,
+  pendingSeekRef,
+  isRefreshingRef,
+  getAdapter,
+  syncTimelineElements,
+  setDuration,
+  setCurrentTime,
+  setTimelineReady,
+  setIsPlaying,
+  attachIframeShortcutListeners,
+}: UseTimelineSyncCallbacksParams) {
+  // Convert a runtime timeline message (from iframe postMessage) into TimelineElements
+  const processTimelineMessage = useCallback(
+    (data: {
+      clips: ClipManifestClip[];
+      durationInFrames: number;
+      scenes?: Array<{ id: string; label: string; start: number; duration: number }>;
+    }) => {
+      if (!data.clips || data.clips.length === 0) {
+        return;
+      }
+
+      // Show root-level clips: no parentCompositionId, OR parent is a "phantom wrapper"
+      const clipCompositionIds = new Set(data.clips.map((c) => c.compositionId).filter(Boolean));
+      const filtered = data.clips.filter(
+        (clip) => !clip.parentCompositionId || !clipCompositionIds.has(clip.parentCompositionId),
+      );
+      let iframeDoc: Document | null = null;
+      try {
+        iframeDoc = iframeRef.current?.contentDocument ?? null;
+      } catch {
+        iframeDoc = null;
+      }
+      const usedHostEls = new Set<Element>();
+      const els: TimelineElement[] = filtered.map((clip, index) => {
+        const hostEl = iframeDoc
+          ? findTimelineDomNodeForClip(iframeDoc, clip, index, usedHostEls)
+          : null;
+        if (hostEl) usedHostEls.add(hostEl);
+        return createTimelineElementFromManifestClip({
+          clip,
+          fallbackIndex: index,
+          doc: iframeDoc,
+          hostEl,
+        });
+      });
+      const rawDuration = data.durationInFrames / 30;
+      // 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.
+      const newDuration = Number.isFinite(rawDuration) && rawDuration < 7200 ? rawDuration : 0;
+      const effectiveDuration = newDuration > 0 ? newDuration : usePlayerStore.getState().duration;
+      const clampedEls =
+        effectiveDuration > 0
+          ? els
+              .filter((element) => element.start < effectiveDuration)
+              .map((element) => ({
+                ...element,
+                duration: Math.min(element.duration, effectiveDuration - element.start),
+              }))
+              .filter((element) => element.duration > 0)
+          : els;
+      const timelineEls =
+        iframeDoc && effectiveDuration > 0
+          ? [
+              ...clampedEls,
+              ...createImplicitTimelineLayersFromDOM(iframeDoc, effectiveDuration, clampedEls),
+            ]
+          : clampedEls;
+      if (timelineEls.length > 0) {
+        syncTimelineElements(timelineEls, newDuration > 0 ? newDuration : undefined);
+      }
+    },
+    [iframeRef, syncTimelineElements],
+  );
+
+  const enrichMissingCompositions = useCallback(() => {
+    try {
+      const iframe = iframeRef.current;
+      const doc = iframe?.contentDocument;
+      const iframeWin = iframe?.contentWindow as IframeWindow | null;
+      if (!doc || !iframeWin) return;
+
+      const currentEls = usePlayerStore.getState().elements;
+      const rootDuration = usePlayerStore.getState().duration;
+      const { missing, updatedEls, patched } = buildMissingCompositionElements(
+        doc,
+        iframeWin,
+        currentEls,
+        rootDuration,
+      );
+
+      if (missing.length > 0 || patched) {
+        // Dedup: ensure no missing element duplicates an existing one
+        const finalIds = new Set(updatedEls.map((e) => e.id));
+        const dedupedMissing = missing.filter((m) => !finalIds.has(m.id));
+        syncTimelineElements([...updatedEls, ...dedupedMissing]);
+      }
+    } catch (err) {
+      console.warn("[useTimelinePlayer] enrichMissingCompositions failed", err);
+    }
+  }, [iframeRef, syncTimelineElements]);
+
+  const initializeAdapter = useCallback(() => {
+    const adapter = getAdapter();
+    if (!adapter || adapter.getDuration() <= 0) return false;
+
+    adapter.pause();
+    const seekTo = pendingSeekRef.current;
+    pendingSeekRef.current = null;
+    const startTime = seekTo != null ? Math.min(seekTo, adapter.getDuration()) : 0;
+
+    adapter.seek(startTime);
+    const adapterDur = adapter.getDuration();
+    if (
+      Number.isFinite(adapterDur) &&
+      adapterDur > 0 &&
+      adapterDur < 7200 &&
+      adapterDur !== usePlayerStore.getState().duration
+    ) {
+      setDuration(adapterDur);
+    }
+    setCurrentTime(startTime);
+    if (!isRefreshingRef.current) {
+      setTimelineReady(true);
+    }
+    isRefreshingRef.current = false;
+    setIsPlaying(false);
+
+    try {
+      const iframe = iframeRef.current;
+      const doc = iframe?.contentDocument;
+      const iframeWin = iframe?.contentWindow as IframeWindow | null;
+      if (doc && iframeWin) {
+        normalizePreviewViewport(doc, iframeWin);
+        autoHealMissingCompositionIds(doc);
+        attachIframeShortcutListeners();
+      }
+
+      const manifest = iframeWin?.__clipManifest;
+      if (manifest && manifest.clips.length > 0) {
+        processTimelineMessage(manifest);
+      }
+      enrichMissingCompositions();
+
+      if (usePlayerStore.getState().elements.length === 0 && doc) {
+        const els = parseTimelineFromDOM(doc, adapter.getDuration());
+        if (els.length > 0) syncTimelineElements(els);
+      }
+      if (usePlayerStore.getState().elements.length === 0 && doc) {
+        const rootComp = doc.querySelector("[data-composition-id]");
+        const rootDuration = adapter.getDuration();
+        if (rootComp && rootDuration > 0) {
+          const fallbackElement = buildStandaloneRootTimelineElement({
+            compositionId: rootComp.getAttribute("data-composition-id") || "composition",
+            tagName: (rootComp as HTMLElement).tagName || "div",
+            rootDuration,
+            iframeSrc: iframe?.src || "",
+            selector: getTimelineElementSelector(rootComp),
+          });
+          if (fallbackElement) syncTimelineElements([fallbackElement]);
+        }
+      }
+    } catch (err) {
+      console.warn("[useTimelinePlayer] Could not read timeline elements from iframe", err);
+    }
+    return true;
+  }, [
+    getAdapter,
+    setDuration,
+    setCurrentTime,
+    setTimelineReady,
+    setIsPlaying,
+    processTimelineMessage,
+    enrichMissingCompositions,
+    syncTimelineElements,
+    attachIframeShortcutListeners,
+    iframeRef,
+    isRefreshingRef,
+    pendingSeekRef,
+  ]);
+
+  const onIframeLoad = useCallback(() => {
+    unmutePreviewMedia(iframeRef.current);
+    if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+
+    // Fast path: adapter already available (in-place reloads, cached compositions)
+    if (initializeAdapter()) return;
+
+    // The runtime posts "state" or "timeline" messages once ready.
+    // Listen for those instead of polling.
+    const iframe = iframeRef.current;
+    let settled = false;
+
+    const trySettle = () => {
+      if (settled) return;
+      if (initializeAdapter()) {
+        settled = true;
+        window.removeEventListener("message", onMessage);
+        if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+      }
+    };
+
+    const onMessage = (e: MessageEvent) => {
+      if (e.source && iframe && e.source !== iframe.contentWindow) return;
+      const data = e.data;
+      if (data?.source === "hf-preview" && (data?.type === "state" || data?.type === "timeline")) {
+        trySettle();
+      }
+    };
+    window.addEventListener("message", onMessage);
+
+    // Safety net: if no message arrives within 5s, try one last time then give up.
+    probeIntervalRef.current = setTimeout(() => {
+      if (!settled) {
+        trySettle();
+        if (!settled) {
+          console.warn("[useTimelinePlayer] Runtime did not signal readiness within 5s");
+        }
+      }
+      window.removeEventListener("message", onMessage);
+    }, 5000) as unknown as ReturnType<typeof setInterval>;
+  }, [initializeAdapter, iframeRef, probeIntervalRef]);
+
+  // Stable refs so mount-effect closures always call the latest version
+  const processTimelineMessageRef = { current: processTimelineMessage };
+  const enrichMissingCompositionsRef = { current: enrichMissingCompositions };
+
+  return {
+    processTimelineMessage,
+    processTimelineMessageRef,
+    enrichMissingCompositions,
+    enrichMissingCompositionsRef,
+    initializeAdapter,
+    onIframeLoad,
+  };
+}
+
+// Re-export the merge helper so the hook can use it via this module (avoids
+// adding another import line to the already-large useTimelinePlayer.ts).
+export { mergeTimelineElementsPreservingDowngrades, getTimelineElementIdentity };

package/src/player/lib/playbackAdapter.ts

@@ -0,0 +1,145 @@
+/**
+ * Playback adapter utilities: factory for the static-seek adapter used when a
+ * composition exposes only a `renderSeek` / `seek` API (no native play/pause
+ * support), plus a thin wrapper that normalises GSAP-style `TimelineLike`
+ * objects to the `PlaybackAdapter` interface.
+ */
+
+import type {
+  PlaybackAdapter,
+  RuntimePlaybackAdapter,
+  StaticSeekPlaybackClock,
+  TimelineLike,
+} from "./playbackTypes";
+
+// ---------------------------------------------------------------------------
+// Pure numeric helpers
+// ---------------------------------------------------------------------------
+
+export function isFinitePositive(value: number): boolean {
+  return Number.isFinite(value) && value > 0;
+}
+
+export function clampTime(time: number, duration: number): number {
+  const safeDuration = Math.max(0, Number.isFinite(duration) ? duration : 0);
+  const safeTime = Math.max(0, Number.isFinite(time) ? time : 0);
+  return safeDuration > 0 ? Math.min(safeTime, safeDuration) : safeTime;
+}
+
+export function getAdapterDuration(adapter: PlaybackAdapter | null | undefined): number {
+  if (!adapter) return 0;
+  try {
+    const duration = Number(adapter.getDuration());
+    return isFinitePositive(duration) ? duration : 0;
+  } catch {
+    return 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Clock factory
+// ---------------------------------------------------------------------------
+
+export function getDefaultStaticSeekPlaybackClock(win: Window): StaticSeekPlaybackClock {
+  return {
+    now: () => win.performance.now(),
+    requestAnimationFrame: (callback) => win.requestAnimationFrame(callback),
+    cancelAnimationFrame: (handle) => win.cancelAnimationFrame(handle),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Static-seek adapter
+// ---------------------------------------------------------------------------
+
+/**
+ * Wraps a render-only player (exposes `renderSeek`/`seek` but no native
+ * play/pause) and drives playback via `requestAnimationFrame`.
+ */
+export function createStaticSeekPlaybackAdapter(
+  player: Pick<RuntimePlaybackAdapter, "getTime"> &
+    Partial<Pick<RuntimePlaybackAdapter, "renderSeek" | "seek">>,
+  duration: number,
+  clock: StaticSeekPlaybackClock,
+  getPlaybackRate: () => number = () => 1,
+): PlaybackAdapter {
+  const safeDuration = Math.max(0, Number.isFinite(duration) ? duration : 0);
+  let currentTime = clampTime(Number(player.getTime?.() ?? 0), safeDuration);
+  let playing = false;
+  let rafId = 0;
+  let playStartTime = currentTime;
+  let playStartNow = clock.now();
+
+  const renderSeek = (time: number) => {
+    currentTime = clampTime(time, safeDuration);
+    if (typeof player.renderSeek === "function") {
+      player.renderSeek(currentTime);
+      return;
+    }
+    player.seek?.(currentTime);
+  };
+
+  const stopTicker = () => {
+    if (rafId) {
+      clock.cancelAnimationFrame(rafId);
+      rafId = 0;
+    }
+  };
+
+  const tick: FrameRequestCallback = (now) => {
+    if (!playing) return;
+    const playbackRate = Math.max(0.1, Number(getPlaybackRate()) || 1);
+    const elapsed = ((now - playStartNow) / 1000) * playbackRate;
+    renderSeek(playStartTime + elapsed);
+    if (currentTime >= safeDuration) {
+      playing = false;
+      rafId = 0;
+      return;
+    }
+    rafId = clock.requestAnimationFrame(tick);
+  };
+
+  return {
+    play: () => {
+      if (playing || safeDuration <= 0) return;
+      if (currentTime >= safeDuration) renderSeek(0);
+      playing = true;
+      playStartTime = currentTime;
+      playStartNow = clock.now();
+      stopTicker();
+      rafId = clock.requestAnimationFrame(tick);
+    },
+    pause: () => {
+      playing = false;
+      stopTicker();
+    },
+    seek: (time) => {
+      renderSeek(time);
+      if (playing) {
+        playStartTime = currentTime;
+        playStartNow = clock.now();
+      }
+    },
+    getTime: () => currentTime,
+    getDuration: () => safeDuration,
+    isPlaying: () => playing,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// GSAP timeline wrapper
+// ---------------------------------------------------------------------------
+
+export function wrapTimeline(tl: TimelineLike): PlaybackAdapter {
+  return {
+    play: () => tl.play(),
+    pause: () => tl.pause(),
+    seek: (t) => {
+      tl.pause();
+      tl.seek(t);
+    },
+    getTime: () => tl.time(),
+    getDuration: () => tl.duration(),
+    isPlaying: () => tl.isActive(),
+  };
+}

package/src/player/lib/playbackShortcuts.ts

@@ -0,0 +1,68 @@
+/**
+ * Keyboard shortcut filtering logic for playback controls.
+ *
+ * Determines whether a keydown event should be handled as a playback shortcut
+ * or ignored (e.g. when focus is in an input field, or when caption edit mode
+ * is active and the user is navigating caption segments).
+ */
+
+const PLAYBACK_FRAME_STEP_CODES = new Set(["ArrowLeft", "ArrowRight"]);
+
+const PLAYBACK_SHORTCUT_IGNORED_SELECTOR = [
+  "input",
+  "textarea",
+  "select",
+  "button",
+  "a[href]",
+  "[contenteditable='true']",
+  "[role='button']",
+  "[role='checkbox']",
+  "[role='combobox']",
+  "[role='menuitem']",
+  "[role='radio']",
+  "[role='slider']",
+  "[role='spinbutton']",
+  "[role='switch']",
+  "[role='textbox']",
+].join(",");
+
+export function shouldIgnorePlaybackShortcutTarget(target: EventTarget | null): boolean {
+  if (!target || typeof target !== "object") return false;
+  const candidate = target as { closest?: unknown };
+  if (typeof candidate.closest !== "function") return false;
+  return (
+    (candidate.closest as (selector: string) => Element | null).call(
+      target,
+      PLAYBACK_SHORTCUT_IGNORED_SELECTOR,
+    ) !== null
+  );
+}
+
+interface PlaybackShortcutCaptionState {
+  isCaptionEditMode: boolean;
+  selectedCaptionSegmentCount: number;
+}
+
+type PlaybackShortcutEvent = Pick<
+  KeyboardEvent,
+  "altKey" | "ctrlKey" | "metaKey" | "code" | "target"
+>;
+
+export function shouldIgnorePlaybackShortcutEvent(
+  event: PlaybackShortcutEvent,
+  captionState: PlaybackShortcutCaptionState = {
+    isCaptionEditMode: false,
+    selectedCaptionSegmentCount: 0,
+  },
+): boolean {
+  if (event.metaKey || event.ctrlKey || event.altKey) return true;
+  if (shouldIgnorePlaybackShortcutTarget(event.target)) return true;
+  return (
+    PLAYBACK_FRAME_STEP_CODES.has(event.code) &&
+    captionState.isCaptionEditMode &&
+    captionState.selectedCaptionSegmentCount > 0
+  );
+}
+
+/** JKL shuttle speeds (×1, ×2, ×4). */
+export const SHUTTLE_SPEEDS = [1, 2, 4] as const;

package/src/player/lib/playbackTypes.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared type definitions for the timeline playback subsystem.
+ * Kept in a separate module so adapter, DOM, and hook modules can all import
+ * from here without creating circular dependencies.
+ */
+
+export interface PlaybackAdapter {
+  play: () => void;
+  pause: () => void;
+  seek: (time: number) => void;
+  getTime: () => number;
+  getDuration: () => number;
+  isPlaying: () => boolean;
+}
+
+export type RuntimePlaybackAdapter = PlaybackAdapter & {
+  renderSeek?: (time: number) => void;
+};
+
+export interface StaticSeekPlaybackClock {
+  now: () => number;
+  requestAnimationFrame: (callback: FrameRequestCallback) => number;
+  cancelAnimationFrame: (handle: number) => void;
+}
+
+export interface TimelineLike {
+  play: () => void;
+  pause: () => void;
+  seek: (time: number) => void;
+  time: () => number;
+  duration: () => number;
+  isActive: () => boolean;
+}
+
+export interface ClipManifestClip {
+  id: string | null;
+  label: string;
+  start: number;
+  duration: number;
+  track: number;
+  kind: "video" | "audio" | "image" | "element" | "composition";
+  tagName: string | null;
+  compositionId: string | null;
+  parentCompositionId: string | null;
+  compositionSrc: string | null;
+  assetUrl: string | null;
+}
+
+export interface ClipManifest {
+  clips: ClipManifestClip[];
+  scenes: Array<{ id: string; label: string; start: number; duration: number }>;
+  durationInFrames: number;
+}
+
+export type IframeWindow = Window & {
+  __player?: RuntimePlaybackAdapter;
+  __timeline?: TimelineLike;
+  __timelines?: Record<string, TimelineLike>;
+  __clipManifest?: ClipManifest;
+};