@hyperframes/studio 0.6.0 → 0.6.2

package/src/player/hooks/useTimelinePlayer.ts

@@ -1,897 +1,47 @@
 import { useRef, useCallback } from "react";
 import { usePlayerStore, liveTime, type TimelineElement } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import { stepFrameTime, STUDIO_PREVIEW_FPS } from "../lib/time";
-import { useCaptionStore } from "../../captions/store";
-
-export interface PlaybackAdapter {
-  play: () => void;
-  pause: () => void;
-  seek: (time: number) => void;
-  getTime: () => number;
-  getDuration: () => number;
-  isPlaying: () => boolean;
-}
-
-type RuntimePlaybackAdapter = PlaybackAdapter & {
-  renderSeek?: (time: number) => void;
-};
-
-interface StaticSeekPlaybackClock {
-  now: () => number;
-  requestAnimationFrame: (callback: FrameRequestCallback) => number;
-  cancelAnimationFrame: (handle: number) => void;
-}
-
-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;
-}
-
-interface ClipManifest {
-  clips: ClipManifestClip[];
-  scenes: Array<{ id: string; label: string; start: number; duration: number }>;
-  durationInFrames: number;
-}
-
-type IframeWindow = Window & {
-  __player?: RuntimePlaybackAdapter;
-  __timeline?: TimelineLike;
-  __timelines?: Record<string, TimelineLike>;
-  __clipManifest?: ClipManifest;
-};
-
-function isFinitePositive(value: number): boolean {
-  return Number.isFinite(value) && value > 0;
-}
-
-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;
-}
-
-function readDurationAttribute(el: Element | null | undefined): number {
-  if (!el) return 0;
-  const duration =
-    Number.parseFloat(el.getAttribute("data-duration") ?? "") ||
-    Number.parseFloat(el.getAttribute("data-hf-authored-duration") ?? "");
-  return isFinitePositive(duration) ? duration : 0;
-}
-
-export function readTimelineDurationFromDocument(doc: Document | null | undefined): number {
-  if (!doc) return 0;
-  const rootDuration = readDurationAttribute(doc.querySelector("[data-composition-id]"));
-  if (rootDuration > 0) return rootDuration;
-
-  let maxEnd = 0;
-  for (const node of Array.from(doc.querySelectorAll("[data-start]"))) {
-    const start = Number.parseFloat(node.getAttribute("data-start") ?? "");
-    const duration = readDurationAttribute(node);
-    if (!Number.isFinite(start) || start < 0 || duration <= 0) continue;
-    maxEnd = Math.max(maxEnd, start + duration);
-  }
-  return maxEnd;
-}
-
-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;
-  }
-}
-
-function getDefaultStaticSeekPlaybackClock(win: Window): StaticSeekPlaybackClock {
-  return {
-    now: () => win.performance.now(),
-    requestAnimationFrame: (callback) => win.requestAnimationFrame(callback),
-    cancelAnimationFrame: (handle) => win.cancelAnimationFrame(handle),
-  };
-}
-
-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,
-  };
-}
-
-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(),
-  };
-}
-
-function resolveMediaElement(el: Element): HTMLMediaElement | HTMLImageElement | null {
-  const win = el.ownerDocument.defaultView ?? window;
-  const MediaElementCtor = win.HTMLMediaElement ?? globalThis.HTMLMediaElement;
-  const ImageElementCtor = win.HTMLImageElement ?? globalThis.HTMLImageElement;
-  if (el instanceof MediaElementCtor || el instanceof ImageElementCtor) return el;
-  const candidate = el.querySelector("video, audio, img");
-  return candidate instanceof MediaElementCtor || candidate instanceof ImageElementCtor
-    ? candidate
-    : null;
-}
-
-function applyMediaMetadataFromElement(entry: TimelineElement, el: Element): void {
-  const mediaStartAttr = el.getAttribute("data-playback-start")
-    ? "playback-start"
-    : el.getAttribute("data-media-start")
-      ? "media-start"
-      : undefined;
-  const mediaStartValue =
-    el.getAttribute("data-playback-start") ?? el.getAttribute("data-media-start");
-  if (mediaStartValue != null) {
-    const playbackStart = parseFloat(mediaStartValue);
-    if (Number.isFinite(playbackStart)) entry.playbackStart = playbackStart;
-  }
-  if (mediaStartAttr) entry.playbackStartAttr = mediaStartAttr;
-
-  const mediaEl = resolveMediaElement(el);
-  if (!mediaEl) return;
-
-  entry.tag = mediaEl.tagName.toLowerCase();
-  const src = mediaEl.getAttribute("src");
-  if (src) entry.src = src;
-
-  const win = mediaEl.ownerDocument.defaultView ?? window;
-  const MediaElementCtor = win.HTMLMediaElement ?? globalThis.HTMLMediaElement;
-  if (typeof MediaElementCtor === "undefined" || !(mediaEl instanceof MediaElementCtor)) return;
-
-  const sourceDurationAttr =
-    el.getAttribute("data-source-duration") ?? mediaEl.getAttribute("data-source-duration");
-  const sourceDuration = sourceDurationAttr ? parseFloat(sourceDurationAttr) : mediaEl.duration;
-  if (Number.isFinite(sourceDuration) && sourceDuration > 0) {
-    entry.sourceDuration = sourceDuration;
-  }
-
-  const playbackRate = mediaEl.defaultPlaybackRate;
-  if (Number.isFinite(playbackRate) && playbackRate > 0) {
-    entry.playbackRate = playbackRate;
-  }
-}
-
-const SHUTTLE_SPEEDS = [1, 2, 4] as const;
-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
-  );
-}
-
-function getTimelineElementDisplayLabel(input: {
-  id?: string | null;
-  label?: string | null;
-  tag?: string | null;
-}): string {
-  const label = input.label?.trim();
-  if (label) return label;
-  const id = input.id?.trim();
-  if (id) return id;
-  const tag = input.tag?.trim().toLowerCase();
-  return tag ? `${tag} clip` : "Timeline clip";
-}
-
-const IMPLICIT_TIMELINE_LAYER_SKIP_TAGS = new Set([
-  "base",
-  "link",
-  "meta",
-  "noscript",
-  "script",
-  "style",
-  "template",
-]);
-
-function humanizeTimelineIdentifier(value: string): string {
-  return value
-    .trim()
-    .replace(/[_-]+/g, " ")
-    .replace(/\s+/g, " ")
-    .replace(/\b\w/g, (match) => match.toUpperCase());
-}
-
-function getImplicitTimelineLayerLabel(el: HTMLElement): string {
-  const explicitLabel =
-    el.getAttribute("data-timeline-label") ??
-    el.getAttribute("data-label") ??
-    el.getAttribute("aria-label");
-  if (explicitLabel?.trim()) return explicitLabel.trim();
-  if (el.id.trim()) return humanizeTimelineIdentifier(el.id);
-  const classes = el.className.split(/\s+/).filter(Boolean);
-  const className = classes.find((value) => value !== "clip") ?? classes[0];
-  if (className) return humanizeTimelineIdentifier(className);
-  return getTimelineElementDisplayLabel({ tag: el.tagName });
-}
-
-function isImplicitTimelineLayerCandidate(root: Element, el: Element): el is HTMLElement {
-  if (!isHtmlElement(el)) return false;
-  if (el.parentElement !== root) return false;
-  const tagName = el.tagName.toLowerCase();
-  if (IMPLICIT_TIMELINE_LAYER_SKIP_TAGS.has(tagName)) return false;
-  if (el.hasAttribute("data-start") || el.hasAttribute("data-track-index")) return false;
-  return Boolean(getTimelineElementSelector(el));
-}
-
-export function createImplicitTimelineLayersFromDOM(
-  doc: Document,
-  rootDuration: number,
-  existingElements: readonly TimelineElement[] = [],
-): TimelineElement[] {
-  if (!Number.isFinite(rootDuration) || rootDuration <= 0) return [];
-  const rootComp = doc.querySelector("[data-composition-id]");
-  if (!rootComp) return [];
-
-  const existingKeys = new Set(existingElements.map(getTimelineElementIdentity));
-  const maxTrack = existingElements.reduce(
-    (max, element) => Math.max(max, Number.isFinite(element.track) ? element.track : 0),
-    -1,
-  );
-  const layers: TimelineElement[] = [];
-
-  for (const child of Array.from(rootComp.children)) {
-    if (!isImplicitTimelineLayerCandidate(rootComp, child)) continue;
-
-    const selector = getTimelineElementSelector(child);
-    if (!selector) continue;
-    const selectorIndex = getTimelineElementSelectorIndex(doc, child, selector);
-    const sourceFile = getTimelineElementSourceFile(child);
-    const label = getImplicitTimelineLayerLabel(child);
-    const identity = buildTimelineElementIdentity({
-      preferredId: child.id || null,
-      label,
-      fallbackIndex: existingElements.length + layers.length,
-      domId: child.id || undefined,
-      selector,
-      selectorIndex,
-      sourceFile,
-    });
-    if (existingKeys.has(identity.key) || existingKeys.has(identity.id)) continue;
-
-    layers.push({
-      domId: child.id || undefined,
-      duration: rootDuration,
-      id: identity.id,
-      key: identity.key,
-      label,
-      selector,
-      selectorIndex,
-      sourceFile,
-      start: 0,
-      tag: child.tagName.toLowerCase(),
-      timingSource: "implicit",
-      track: maxTrack + 1 + layers.length,
-    });
-  }
-
-  return layers;
-}
-
-/**
- * Parse [data-start] elements from a Document into TimelineElement[].
- * Shared helper — used by onIframeLoad fallback, handleMessage, and enrichMissingCompositions.
- */
-export function parseTimelineFromDOM(doc: Document, rootDuration: number): TimelineElement[] {
-  const rootComp = doc.querySelector("[data-composition-id]");
-  const nodes = doc.querySelectorAll("[data-start]");
-  const els: TimelineElement[] = [];
-  let trackCounter = 0;
-
-  nodes.forEach((node) => {
-    if (node === rootComp) return;
-    const el = node as HTMLElement;
-    const startStr = el.getAttribute("data-start");
-    if (startStr == null) return;
-    const start = parseFloat(startStr);
-    if (isNaN(start)) return;
-    if (Number.isFinite(rootDuration) && rootDuration > 0 && start >= rootDuration) return;
-
-    const tagLower = el.tagName.toLowerCase();
-    let dur = 0;
-    const durStr = el.getAttribute("data-duration");
-    if (durStr != null) dur = parseFloat(durStr);
-    if (isNaN(dur) || dur <= 0) dur = Math.max(0, rootDuration - start);
-    if (Number.isFinite(rootDuration) && rootDuration > 0) {
-      dur = Math.min(dur, Math.max(0, rootDuration - start));
-    }
-    if (!Number.isFinite(dur) || dur <= 0) return;
-
-    const trackStr = el.getAttribute("data-track-index");
-    const track = trackStr != null ? parseInt(trackStr, 10) : trackCounter++;
-    const compId = el.getAttribute("data-composition-id");
-    const selector = getTimelineElementSelector(el);
-    const sourceFile = getTimelineElementSourceFile(el);
-    const selectorIndex = getTimelineElementSelectorIndex(doc, el, selector);
-    const label = getTimelineElementDisplayLabel({
-      id: el.id || compId || null,
-      label: el.getAttribute("data-timeline-label") ?? el.getAttribute("data-label"),
-      tag: tagLower,
-    });
-    const identity = buildTimelineElementIdentity({
-      preferredId: el.id || compId || null,
-      label,
-      fallbackIndex: els.length,
-      domId: el.id || undefined,
-      selector,
-      selectorIndex,
-      sourceFile,
-    });
-    const entry: TimelineElement = {
-      id: identity.id,
-      label,
-      key: identity.key,
-      tag: tagLower,
-      start,
-      duration: dur,
-      track: isNaN(track) ? 0 : track,
-      domId: el.id || undefined,
-      selector,
-      selectorIndex,
-      sourceFile,
-      timingSource: "authored",
-    };
-
-    const mediaEl = resolveMediaElement(el);
-    if (mediaEl) {
-      if (mediaEl.tagName === "IMG") {
-        entry.tag = "img";
-      }
-      const src = mediaEl.getAttribute("src");
-      if (src) entry.src = src;
-      const vol = el.getAttribute("data-volume") ?? mediaEl.getAttribute("data-volume");
-      if (vol) entry.volume = parseFloat(vol);
-      applyMediaMetadataFromElement(entry, el);
-    }
-
-    // Sub-compositions
-    const compSrc =
-      el.getAttribute("data-composition-src") || el.getAttribute("data-composition-file");
-    if (compSrc) {
-      entry.compositionSrc = compSrc;
-    } else if (compId && compId !== rootComp?.getAttribute("data-composition-id")) {
-      // Inline composition — expose inner video for thumbnails
-      const innerVideo = el.querySelector("video[src]");
-      if (innerVideo) {
-        entry.src = innerVideo.getAttribute("src") || undefined;
-        entry.tag = "video";
-      }
-    }
-
-    els.push(entry);
-  });
-
-  return [...els, ...createImplicitTimelineLayersFromDOM(doc, rootDuration, els)];
-}
-
-function isHtmlElement(el: Element): el is HTMLElement {
-  const HtmlElementCtor = el.ownerDocument.defaultView?.HTMLElement ?? globalThis.HTMLElement;
-  return typeof HtmlElementCtor !== "undefined" && el instanceof HtmlElementCtor;
-}
-
-export function getTimelineElementSelector(el: Element): string | undefined {
-  if (isHtmlElement(el) && el.id) return `#${el.id}`;
-  const compId = el.getAttribute("data-composition-id");
-  if (compId) return `[data-composition-id="${compId}"]`;
-  if (isHtmlElement(el)) {
-    const classes = el.className.split(/\s+/).filter(Boolean);
-    const firstClass = classes.find((className) => className !== "clip") ?? classes[0];
-    if (firstClass) return `.${firstClass}`;
-  }
-  return undefined;
-}
-
-function getTimelineElementSourceFile(el: Element): string | undefined {
-  const ownerRoot = el.parentElement?.closest("[data-composition-id]");
-  return (
-    ownerRoot?.getAttribute("data-composition-file") ??
-    ownerRoot?.getAttribute("data-composition-src") ??
-    undefined
-  );
-}
-
-function getTimelineElementSelectorIndex(
-  doc: Document,
-  el: Element,
-  selector: string | undefined,
-): number | undefined {
-  if (!selector || selector.startsWith("#") || selector.startsWith("[data-composition-id=")) {
-    return undefined;
-  }
-
-  try {
-    const matches = Array.from(doc.querySelectorAll(selector));
-    const matchIndex = matches.indexOf(el);
-    return matchIndex >= 0 ? matchIndex : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function buildTimelineElementKey(params: {
-  id: string;
-  fallbackIndex: number;
-  domId?: string;
-  selector?: string;
-  selectorIndex?: number;
-  sourceFile?: string;
-}): string {
-  const scope = params.sourceFile ?? "index.html";
-  if (params.domId) return `${scope}#${params.domId}`;
-  if (params.selector) return `${scope}:${params.selector}:${params.selectorIndex ?? 0}`;
-  return `${scope}:${params.id}:${params.fallbackIndex}`;
-}
-function buildTimelineElementIdentity(params: {
-  preferredId?: string | null;
-  label: string;
-  fallbackIndex: number;
-  domId?: string;
-  selector?: string;
-  selectorIndex?: number;
-  sourceFile?: string;
-}): { id: string; key: string } {
-  const id =
-    params.preferredId?.trim() ||
-    buildTimelineElementKey({
-      id: params.label,
-      fallbackIndex: params.fallbackIndex,
-      domId: params.domId,
-      selector: params.selector,
-      selectorIndex: params.selectorIndex,
-      sourceFile: params.sourceFile,
-    });
-  const key = buildTimelineElementKey({
-    id,
-    fallbackIndex: params.fallbackIndex,
-    domId: params.domId,
-    selector: params.selector,
-    selectorIndex: params.selectorIndex,
-    sourceFile: params.sourceFile,
-  });
-  return { id, key };
-}
-
-function getTimelineElementIdentity(element: TimelineElement): string {
-  return element.key ?? element.id;
-}
-
-function getTimelineDomNodes(doc: Document): Element[] {
-  const rootComp = doc.querySelector("[data-composition-id]");
-  return Array.from(doc.querySelectorAll("[data-start]")).filter((node) => node !== rootComp);
-}
-
-function numbersNearlyEqual(a: number, b: number): boolean {
-  return Math.abs(a - b) < 0.001;
-}
-
-function nodeMatchesManifestClip(node: Element, clip: ClipManifestClip): boolean {
-  const tagName = clip.tagName?.toLowerCase();
-  if (tagName && node.tagName.toLowerCase() !== tagName) return false;
-
-  const start = Number.parseFloat(node.getAttribute("data-start") ?? "");
-  if (Number.isFinite(start) && !numbersNearlyEqual(start, clip.start)) return false;
-
-  const duration = Number.parseFloat(node.getAttribute("data-duration") ?? "");
-  if (Number.isFinite(duration) && !numbersNearlyEqual(duration, clip.duration)) return false;
-
-  const track = Number.parseInt(node.getAttribute("data-track-index") ?? "", 10);
-  if (Number.isFinite(track) && track !== clip.track) return false;
-
-  return true;
-}
-
-export function findTimelineDomNodeForClip(
-  doc: Document,
-  clip: ClipManifestClip,
-  fallbackIndex: number,
-  usedNodes = new Set<Element>(),
-): Element | null {
-  const byIdentity = clip.id ? findTimelineDomNode(doc, clip.id) : null;
-  if (byIdentity && !usedNodes.has(byIdentity)) return byIdentity;
-
-  const candidates = getTimelineDomNodes(doc).filter((node) => !usedNodes.has(node));
-  const exact = candidates.find((node) => nodeMatchesManifestClip(node, clip));
-  if (exact) return exact;
-
-  return candidates[fallbackIndex] ?? null;
-}
-
-export function createTimelineElementFromManifestClip(params: {
-  clip: ClipManifestClip;
-  fallbackIndex: number;
-  doc?: Document | null;
-  hostEl?: Element | null;
-}): TimelineElement {
-  const { clip, fallbackIndex, doc } = params;
-  let hostEl = params.hostEl ?? null;
-  const label = getTimelineElementDisplayLabel({
-    id: clip.id,
-    label: clip.label,
-    tag: clip.tagName || clip.kind,
-  });
-
-  let domId: string | undefined;
-  let selector: string | undefined;
-  let selectorIndex: number | undefined;
-  let sourceFile: string | undefined;
-
-  if (hostEl) {
-    domId = hostEl.id || undefined;
-    selector = getTimelineElementSelector(hostEl);
-    selectorIndex =
-      doc && selector ? getTimelineElementSelectorIndex(doc, hostEl, selector) : undefined;
-    sourceFile = getTimelineElementSourceFile(hostEl);
-  }
-
-  const identity = buildTimelineElementIdentity({
-    preferredId: clip.id,
-    label,
-    fallbackIndex,
-    domId,
-    selector,
-    selectorIndex,
-    sourceFile,
-  });
-  const entry: TimelineElement = {
-    id: identity.id,
-    label,
-    key: identity.key,
-    tag: clip.tagName || clip.kind,
-    start: clip.start,
-    duration: clip.duration,
-    track: clip.track,
-    domId,
-    selector,
-    selectorIndex,
-    sourceFile,
-  };
-
-  if (hostEl) {
-    applyMediaMetadataFromElement(entry, hostEl);
-  }
-  if (clip.assetUrl) entry.src = clip.assetUrl;
-  if (clip.kind === "composition" && clip.compositionId) {
-    let resolvedSrc = clip.compositionSrc;
-    if (!resolvedSrc) {
-      hostEl = doc?.querySelector(`[data-composition-id="${clip.compositionId}"]`) ?? hostEl;
-      resolvedSrc =
-        hostEl?.getAttribute("data-composition-src") ??
-        hostEl?.getAttribute("data-composition-file") ??
-        null;
-    }
-    if (resolvedSrc) {
-      entry.compositionSrc = resolvedSrc;
-    } else if (hostEl) {
-      const innerVideo = hostEl.querySelector("video[src]");
-      if (innerVideo) {
-        entry.src = innerVideo.getAttribute("src") || undefined;
-        entry.tag = "video";
-      }
-    }
-    if (hostEl) {
-      entry.domId = hostEl.id || undefined;
-      entry.selector = getTimelineElementSelector(hostEl);
-      entry.selectorIndex =
-        doc && entry.selector
-          ? getTimelineElementSelectorIndex(doc, hostEl, entry.selector)
-          : undefined;
-      entry.sourceFile = getTimelineElementSourceFile(hostEl);
-      const nextIdentity = buildTimelineElementIdentity({
-        preferredId: clip.id,
-        label,
-        fallbackIndex,
-        domId: entry.domId,
-        selector: entry.selector,
-        selectorIndex: entry.selectorIndex,
-        sourceFile: entry.sourceFile,
-      });
-      entry.id = nextIdentity.id;
-      entry.key = nextIdentity.key;
-    }
-  }
-
-  return entry;
-}
-
-function findTimelineDomNode(doc: Document, id: string): Element | null {
-  return (
-    doc.getElementById(id) ??
-    doc.querySelector(`[data-composition-id="${id}"]`) ??
-    doc.querySelector(`.${id}`) ??
-    null
-  );
-}
-
-export function resolveStandaloneRootCompositionSrc(iframeSrc: string): string | undefined {
-  const compPathMatch = iframeSrc.match(/\/preview\/comp\/(.+?)(?:\?|$)/);
-  return compPathMatch ? decodeURIComponent(compPathMatch[1]) : undefined;
-}
-
-export function buildStandaloneRootTimelineElement(params: {
-  compositionId: string;
-  tagName: string;
-  rootDuration: number;
-  iframeSrc: string;
-  selector?: string;
-  selectorIndex?: number;
-}): TimelineElement | null {
-  if (!Number.isFinite(params.rootDuration) || params.rootDuration <= 0) return null;
-
-  const compositionSrc = resolveStandaloneRootCompositionSrc(params.iframeSrc);
-
-  return {
-    id: params.compositionId,
-    label: getTimelineElementDisplayLabel({
-      id: params.compositionId,
-      tag: params.tagName,
-    }),
-    key: buildTimelineElementKey({
-      id: params.compositionId,
-      fallbackIndex: 0,
-      selector: params.selector,
-      selectorIndex: params.selectorIndex,
-      sourceFile: compositionSrc,
-    }),
-    tag: params.tagName.toLowerCase() || "div",
-    start: 0,
-    duration: params.rootDuration,
-    track: 0,
-    compositionSrc,
-    selector: params.selector,
-    selectorIndex: params.selectorIndex,
-    sourceFile: compositionSrc,
-  };
-}
-function normalizePreviewViewport(doc: Document, win: Window): void {
-  if (doc.documentElement) {
-    doc.documentElement.style.overflow = "hidden";
-    doc.documentElement.style.margin = "0";
-  }
-  if (doc.body) {
-    doc.body.style.overflow = "hidden";
-    doc.body.style.margin = "0";
-  }
-  win.scrollTo({ top: 0, left: 0, behavior: "auto" });
-}
-
-function autoHealMissingCompositionIds(doc: Document): void {
-  const compositionIdRe = /data-composition-id=["']([^"']+)["']/gi;
-  const referencedIds = new Set<string>();
-  const scopedNodes = Array.from(doc.querySelectorAll("style, script"));
-  for (const node of scopedNodes) {
-    const text = node.textContent || "";
-    if (!text) continue;
-    let match: RegExpExecArray | null;
-    while ((match = compositionIdRe.exec(text)) !== null) {
-      const id = (match[1] || "").trim();
-      if (id) referencedIds.add(id);
-    }
-  }
-
-  if (referencedIds.size === 0) return;
-
-  const existingIds = new Set<string>();
-  const existingNodes = Array.from(doc.querySelectorAll<HTMLElement>("[data-composition-id]"));
-  for (const node of existingNodes) {
-    const id = node.getAttribute("data-composition-id");
-    if (id) existingIds.add(id);
-  }
-
-  for (const compId of referencedIds) {
-    if (compId === "root" || existingIds.has(compId)) continue;
-    const host =
-      doc.getElementById(`${compId}-layer`) ||
-      doc.getElementById(`${compId}-comp`) ||
-      doc.getElementById(compId);
-    if (!host) continue;
-    if (!host.getAttribute("data-composition-id")) {
-      host.setAttribute("data-composition-id", compId);
-    }
-  }
-}
-
-function unmutePreviewMedia(iframe: HTMLIFrameElement | null): void {
-  if (!iframe) return;
-  try {
-    iframe.contentWindow?.postMessage(
-      { source: "hf-parent", type: "control", action: "set-muted", muted: false },
-      "*",
-    );
-  } catch (err) {
-    console.warn("[useTimelinePlayer] Failed to unmute preview media", err);
-  }
-}
-
-/**
- * Resolve the underlying iframe from any host element. Supports:
- * - Direct `<iframe>` element (most common — studio's own `Player.tsx`)
- * - Custom elements (e.g. `<hyperframes-player>`) whose shadow DOM contains an iframe
- * - Wrapper elements whose light DOM contains a descendant iframe
- *
- * Exported so web-component consumers can pre-resolve the iframe before
- * assigning it to `iframeRef` returned by `useTimelinePlayer`. Returns `null`
- * when the element has no associated iframe yet.
- *
- * @example
- * ```tsx
- * const { iframeRef } = useTimelinePlayer();
- * const playerElRef = useRef<HyperframesPlayer>(null);
- *
- * useEffect(() => {
- *   iframeRef.current = resolveIframe(playerElRef.current);
- * }, [iframeRef]);
- * ```
- */
-export function resolveIframe(el: Element | null): HTMLIFrameElement | null {
-  if (!el) return null;
-  if (el instanceof HTMLIFrameElement) return el;
-  return el.shadowRoot?.querySelector("iframe") ?? el.querySelector("iframe") ?? null;
-}
-
-export function mergeTimelineElementsPreservingDowngrades(
-  currentElements: TimelineElement[],
-  nextElements: TimelineElement[],
-  currentDuration: number,
-  nextDuration: number,
-): TimelineElement[] {
-  const safeCurrentDuration = Number.isFinite(currentDuration) ? currentDuration : 0;
-  const safeNextDuration = Number.isFinite(nextDuration) ? nextDuration : 0;
-
-  if (
-    currentElements.length === 0 ||
-    nextElements.length >= currentElements.length ||
-    safeNextDuration > safeCurrentDuration
-  ) {
-    return nextElements;
-  }
-
-  const nextIdentities = new Set(nextElements.map(getTimelineElementIdentity));
-  const preserved = currentElements.filter(
-    (element) => !nextIdentities.has(getTimelineElementIdentity(element)),
-  );
-  if (preserved.length === 0) return nextElements;
-  return [...nextElements, ...preserved];
-}
+import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
+import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
+
+// Re-export public API consumed by tests and external modules.
+// All of these were previously defined in this file; they now live in focused
+// sub-modules but are re-exported here so existing import sites don't change.
+export type { PlaybackAdapter, ClipManifestClip } from "../lib/playbackTypes";
+export { createStaticSeekPlaybackAdapter } from "../lib/playbackAdapter";
+export {
+  getTimelineElementSelector,
+  readTimelineDurationFromDocument,
+  parseTimelineFromDOM,
+  createTimelineElementFromManifestClip,
+  findTimelineDomNodeForClip,
+  buildStandaloneRootTimelineElement,
+  mergeTimelineElementsPreservingDowngrades,
+  resolveStandaloneRootCompositionSrc,
+  resolveIframe,
+} from "../lib/timelineDOM";
+export {
+  shouldIgnorePlaybackShortcutEvent,
+  shouldIgnorePlaybackShortcutTarget,
+} from "../lib/playbackShortcuts";
+
+import type { PlaybackAdapter, RuntimePlaybackAdapter, IframeWindow } from "../lib/playbackTypes";
+import {
+  getAdapterDuration,
+  wrapTimeline,
+  createStaticSeekPlaybackAdapter,
+  getDefaultStaticSeekPlaybackClock,
+} from "../lib/playbackAdapter";
+import {
+  readTimelineDurationFromDocument,
+  mergeTimelineElementsPreservingDowngrades,
+  parseTimelineFromDOM,
+} from "../lib/timelineDOM";
+import { unmutePreviewMedia } from "../lib/timelineIframeHelpers";
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
 
 export function useTimelinePlayer() {
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
@@ -902,10 +52,7 @@ export function useTimelinePlayer() {
   const reverseRafRef = useRef<number>(0);
   const shuttleDirectionRef = useRef<"forward" | "backward" | null>(null);
   const shuttleSpeedIndexRef = useRef(0);
-  const pressedCodesRef = useRef(new Set<string>());
   const iframeShortcutCleanupRef = useRef<(() => void) | null>(null);
-  const playbackKeyDownRef = useRef<(e: KeyboardEvent) => void>(() => {});
-  const playbackKeyUpRef = useRef<(e: KeyboardEvent) => void>(() => {});
   const lastTimelineMessageRef = useRef<number>(0);
   const staticSeekAdapterRef = useRef<{
     player: RuntimePlaybackAdapter;
@@ -1162,14 +309,6 @@ export function useTimelinePlayer() {
     stopRAFLoop();
   }, [getAdapter, setCurrentTime, setIsPlaying, stopRAFLoop, stopReverseLoop]);
 
-  const togglePlay = useCallback(() => {
-    if (usePlayerStore.getState().isPlaying) {
-      pause();
-    } else {
-      play();
-    }
-  }, [play, pause]);
-
   const seek = useCallback(
     (time: number) => {
       stopReverseLoop();
@@ -1181,7 +320,6 @@ export function useTimelinePlayer() {
       liveTime.notify(nextTime); // Direct DOM updates (playhead, timecode, progress) — no re-render
       setCurrentTime(nextTime); // sync store so Split/Delete have accurate time
       stopRAFLoop();
-      // Only update store if state actually changes (avoids unnecessary re-renders)
       if (usePlayerStore.getState().isPlaying) setIsPlaying(false);
       shuttleDirectionRef.current = null;
       shuttleSpeedIndexRef.current = 0;
@@ -1189,463 +327,34 @@ export function useTimelinePlayer() {
     [getAdapter, setCurrentTime, setIsPlaying, stopRAFLoop, stopReverseLoop],
   );
 
-  const stepFrames = useCallback(
-    (deltaFrames: number) => {
-      const adapter = getAdapter();
-      const currentTime = adapter?.getTime() ?? usePlayerStore.getState().currentTime;
-      seek(stepFrameTime(currentTime, deltaFrames, STUDIO_PREVIEW_FPS));
-    },
-    [getAdapter, seek],
-  );
-
-  const shuttle = useCallback(
-    (direction: "forward" | "backward") => {
-      if (shuttleDirectionRef.current === direction) {
-        shuttleSpeedIndexRef.current = Math.min(
-          shuttleSpeedIndexRef.current + 1,
-          SHUTTLE_SPEEDS.length - 1,
-        );
-      } else {
-        shuttleSpeedIndexRef.current = 0;
-      }
-      const speed = SHUTTLE_SPEEDS[shuttleSpeedIndexRef.current];
-      usePlayerStore.getState().setPlaybackRate(speed);
-      if (direction === "forward") {
-        play();
-      } else {
-        playBackward(speed);
-      }
-    },
-    [play, playBackward],
-  );
-
-  const handlePlaybackKeyDown = useCallback(
-    (e: KeyboardEvent) => {
-      if (e.defaultPrevented) return;
-      const captionState = useCaptionStore.getState();
-      if (
-        shouldIgnorePlaybackShortcutEvent(e, {
-          isCaptionEditMode: captionState.isEditMode,
-          selectedCaptionSegmentCount: captionState.selectedSegmentIds.size,
-        })
-      ) {
-        return;
-      }
-      pressedCodesRef.current.add(e.code);
-      if (e.code === "Space") {
-        e.preventDefault();
-        togglePlay();
-        return;
-      }
-      if (e.code === "ArrowLeft") {
-        e.preventDefault();
-        stepFrames(e.shiftKey ? -10 : -1);
-        return;
-      }
-      if (e.code === "ArrowRight") {
-        e.preventDefault();
-        stepFrames(e.shiftKey ? 10 : 1);
-        return;
-      }
-      if (e.repeat) return;
-      if (e.code === "KeyK") {
-        e.preventDefault();
-        pause();
-        return;
-      }
-      if (e.code === "KeyJ") {
-        e.preventDefault();
-        if (pressedCodesRef.current.has("KeyK")) {
-          stepFrames(-1);
-          return;
-        }
-        shuttle("backward");
-        return;
-      }
-      if (e.code === "KeyL") {
-        e.preventDefault();
-        if (pressedCodesRef.current.has("KeyK")) {
-          stepFrames(1);
-          return;
-        }
-        shuttle("forward");
-      }
-    },
-    [pause, shuttle, stepFrames, togglePlay],
-  );
-
-  const handlePlaybackKeyUp = useCallback((e: KeyboardEvent) => {
-    pressedCodesRef.current.delete(e.code);
-  }, []);
-  playbackKeyDownRef.current = handlePlaybackKeyDown;
-  playbackKeyUpRef.current = handlePlaybackKeyUp;
-
-  const attachIframeShortcutListeners = useCallback(() => {
-    iframeShortcutCleanupRef.current?.();
-    iframeShortcutCleanupRef.current = null;
-
-    const iframeWin = iframeRef.current?.contentWindow;
-    const iframeDoc = iframeRef.current?.contentDocument;
-    if (!iframeWin && !iframeDoc) return;
-
-    const handleIframeKeyDown = (e: KeyboardEvent) => playbackKeyDownRef.current(e);
-    const handleIframeKeyUp = (e: KeyboardEvent) => playbackKeyUpRef.current(e);
-    iframeWin?.addEventListener("keydown", handleIframeKeyDown, true);
-    iframeWin?.addEventListener("keyup", handleIframeKeyUp, true);
-    iframeDoc?.addEventListener("keydown", handleIframeKeyDown, true);
-    iframeDoc?.addEventListener("keyup", handleIframeKeyUp, true);
-    iframeShortcutCleanupRef.current = () => {
-      iframeWin?.removeEventListener("keydown", handleIframeKeyDown, true);
-      iframeWin?.removeEventListener("keyup", handleIframeKeyUp, true);
-      iframeDoc?.removeEventListener("keydown", handleIframeKeyDown, true);
-      iframeDoc?.removeEventListener("keyup", handleIframeKeyUp, true);
-    };
-  }, []);
-
-  // 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);
-      }
-    },
-    [syncTimelineElements],
-  );
-
-  /**
-   * Scan the iframe DOM for composition hosts missing from the current
-   * timeline elements and add them.  The CDN runtime often fails to resolve
-   * element-reference starts (`data-start="intro"`) so composition hosts
-   * are silently dropped from `__clipManifest`.  This pass reads the DOM +
-   * GSAP timeline registry directly to fill the gaps.
-   */
-  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 existingIds = new Set(currentEls.map((e) => e.id));
-      const rootComp = doc.querySelector("[data-composition-id]");
-      const rootCompId = rootComp?.getAttribute("data-composition-id");
-      // Use [data-composition-id][data-start] — the composition loader strips
-      // data-composition-src after loading, so we can't rely on it.
-      const hosts = doc.querySelectorAll("[data-composition-id][data-start]");
-      const missing: TimelineElement[] = [];
-
-      hosts.forEach((host) => {
-        const el = host as HTMLElement;
-        const compId = el.getAttribute("data-composition-id");
-        if (!compId || compId === rootCompId) return;
-        if (existingIds.has(el.id) || existingIds.has(compId)) return;
-
-        // Resolve start: numeric or element-reference
-        const startAttr = el.getAttribute("data-start") ?? "0";
-        let start = parseFloat(startAttr);
-        if (isNaN(start)) {
-          const ref =
-            doc.getElementById(startAttr) ||
-            doc.querySelector(`[data-composition-id="${startAttr}"]`);
-          if (ref) {
-            const refStartAttr = ref.getAttribute("data-start") ?? "0";
-            let refStart = parseFloat(refStartAttr);
-            // Recursively resolve one level of reference for the ref's own start
-            if (isNaN(refStart)) {
-              const refRef =
-                doc.getElementById(refStartAttr) ||
-                doc.querySelector(`[data-composition-id="${refStartAttr}"]`);
-              const rrStart = parseFloat(refRef?.getAttribute("data-start") ?? "0") || 0;
-              const rrCompId = refRef?.getAttribute("data-composition-id");
-              const rrDur =
-                parseFloat(refRef?.getAttribute("data-duration") ?? "") ||
-                (rrCompId
-                  ? ((
-                      iframeWin.__timelines?.[rrCompId] as TimelineLike | undefined
-                    )?.duration?.() ?? 0)
-                  : 0);
-              refStart = rrStart + rrDur;
-            }
-            const refCompId = ref.getAttribute("data-composition-id");
-            const refDur =
-              parseFloat(ref.getAttribute("data-duration") ?? "") ||
-              (refCompId
-                ? ((iframeWin.__timelines?.[refCompId] as TimelineLike | undefined)?.duration?.() ??
-                  0)
-                : 0);
-            start = refStart + refDur;
-          } else {
-            start = 0;
-          }
-        }
-
-        // Resolve duration from data-duration or GSAP timeline
-        let dur = parseFloat(el.getAttribute("data-duration") ?? "");
-        if (isNaN(dur) || dur <= 0) {
-          dur = (iframeWin.__timelines?.[compId] as TimelineLike | undefined)?.duration?.() ?? 0;
-        }
-        if (!Number.isFinite(dur) || dur <= 0) return;
-        if (!Number.isFinite(start)) start = 0;
-        const rootDuration = usePlayerStore.getState().duration;
-        if (Number.isFinite(rootDuration) && rootDuration > 0) {
-          if (start >= rootDuration) return;
-          dur = Math.min(dur, Math.max(0, rootDuration - start));
-          if (dur <= 0) return;
-        }
-
-        const trackStr = el.getAttribute("data-track-index");
-        const track = trackStr != null ? parseInt(trackStr, 10) : 0;
-        const compSrc =
-          el.getAttribute("data-composition-src") || el.getAttribute("data-composition-file");
-        const selector = getTimelineElementSelector(el);
-        const sourceFile = getTimelineElementSourceFile(el);
-        const selectorIndex = getTimelineElementSelectorIndex(doc, el, selector);
-        const label = getTimelineElementDisplayLabel({
-          id: el.id || compId || null,
-          label: el.getAttribute("data-timeline-label") ?? el.getAttribute("data-label"),
-          tag: el.tagName,
-        });
-        const identity = buildTimelineElementIdentity({
-          preferredId: el.id || compId || null,
-          label,
-          fallbackIndex: missing.length,
-          domId: el.id || undefined,
-          selector,
-          selectorIndex,
-          sourceFile,
-        });
-        const entry: TimelineElement = {
-          id: identity.id,
-          label,
-          key: identity.key,
-          tag: el.tagName.toLowerCase(),
-          start,
-          duration: dur,
-          track: isNaN(track) ? 0 : track,
-          domId: el.id || undefined,
-          selector,
-          selectorIndex,
-          sourceFile,
-        };
-        if (compSrc) {
-          entry.compositionSrc = compSrc;
-        } else {
-          // Inline composition — expose inner video for thumbnails
-          const innerVideo = el.querySelector("video[src]");
-          if (innerVideo) {
-            entry.src = innerVideo.getAttribute("src") || undefined;
-            entry.tag = "video";
-          }
-        }
-        missing.push(entry);
-      });
-
-      // Patch existing elements that are missing compositionSrc
-      let patched = false;
-      const updatedEls = currentEls.map((existing) => {
-        if (existing.compositionSrc) return existing;
-        // Find the matching DOM host by element id or composition id
-        const host =
-          doc.getElementById(existing.id) ??
-          doc.querySelector(`[data-composition-id="${existing.id}"]`);
-        if (!host) return existing;
-        const compSrc =
-          host.getAttribute("data-composition-src") || host.getAttribute("data-composition-file");
-        if (compSrc) {
-          patched = true;
-          return { ...existing, compositionSrc: compSrc };
-        }
-        return existing;
-      });
-
-      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);
-    }
-  }, [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,
-  ]);
-
-  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. Use a short-lived message
-    // listener that fires initializeAdapter on the first signal.
-    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);
+  const { playbackKeyDownRef, playbackKeyUpRef, attachIframeShortcutListeners, togglePlay } =
+    usePlaybackKeyboard({
+      iframeRef,
+      shuttleDirectionRef,
+      shuttleSpeedIndexRef,
+      iframeShortcutCleanupRef,
+      getAdapter,
+      play,
+      playBackward,
+      pause,
+      seek,
+    });
 
-    // Safety net: if no message arrives within 5s, try one last time then give up.
-    // This replaces the old 25×200ms polling loop with a single delayed check.
-    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]);
+  const { processTimelineMessageRef, enrichMissingCompositionsRef, onIframeLoad } =
+    useTimelineSyncCallbacks({
+      iframeRef,
+      probeIntervalRef,
+      pendingSeekRef,
+      isRefreshingRef,
+      getAdapter,
+      syncTimelineElements,
+      setDuration,
+      setCurrentTime,
+      setTimelineReady,
+      setIsPlaying,
+      attachIframeShortcutListeners,
+    });
 
-  /** Save the current playback time so the next onIframeLoad restores it. */
   const saveSeekPosition = useCallback(() => {
     const adapter = getAdapter();
     pendingSeekRef.current = adapter
@@ -1657,9 +366,6 @@ export function useTimelinePlayer() {
     setIsPlaying(false);
   }, [getAdapter, stopRAFLoop, setIsPlaying, stopReverseLoop]);
 
-  const togglePlayRef = useRef(togglePlay);
-  togglePlayRef.current = togglePlay;
-
   const refreshPlayer = useCallback(() => {
     const iframe = iframeRef.current;
     if (!iframe) return;
@@ -1674,10 +380,6 @@ export function useTimelinePlayer() {
 
   const getAdapterRef = useRef(getAdapter);
   getAdapterRef.current = getAdapter;
-  const processTimelineMessageRef = useRef(processTimelineMessage);
-  processTimelineMessageRef.current = processTimelineMessage;
-  const enrichMissingCompositionsRef = useRef(enrichMissingCompositions);
-  enrichMissingCompositionsRef.current = enrichMissingCompositions;
 
   useMountEffect(() => {
     const handleWindowKeyDown = (e: KeyboardEvent) => playbackKeyDownRef.current(e);
@@ -1693,9 +395,7 @@ export function useTimelinePlayer() {
       if (e.source && ourIframe && e.source !== ourIframe.contentWindow) {
         return;
       }
-      // Also handle the runtime's state message which includes timeline data
       if (data?.source === "hf-preview" && data?.type === "state") {
-        // State message means the runtime is alive — check for elements
         try {
           if (usePlayerStore.getState().elements.length === 0) {
             const iframeWin = ourIframe?.contentWindow as IframeWindow | null;
@@ -1707,8 +407,7 @@ export function useTimelinePlayer() {
           // Enrich only when the timeline has settled — skip during the window
           // right after a "timeline" message to avoid the enrichment adding
           // elements that fight with the manifest's authoritative element list,
-          // causing duration oscillation (the merge function alternates between
-          // REPLACE and PRESERVE when element counts fluctuate).
+          // causing duration oscillation.
           const msSinceTimeline = Date.now() - lastTimelineMessageRef.current;
           if (msSinceTimeline > 500) {
             enrichMissingCompositionsRef.current();
@@ -1720,9 +419,7 @@ export function useTimelinePlayer() {
       if (data?.source === "hf-preview" && data?.type === "timeline" && Array.isArray(data.clips)) {
         lastTimelineMessageRef.current = Date.now();
         processTimelineMessageRef.current(data);
-        // Fill in composition hosts the manifest missed (element-reference starts)
         enrichMissingCompositionsRef.current();
-        // If manifest produced 0 elements after filtering, try DOM fallback
         if (usePlayerStore.getState().elements.length === 0) {
           try {
             const doc = ourIframe?.contentDocument;
@@ -1743,7 +440,7 @@ export function useTimelinePlayer() {
       }
     };
 
-    // Pause video when tab loses focus (user switches away)
+    // Pause video when tab loses focus
     const handleVisibilityChange = () => {
       if (document.hidden && usePlayerStore.getState().isPlaying) {
         const adapter = getAdapterRef.current?.();