Skip to content

Write HTML. Render video. Built for agents.

17.5 KB
Raw Blame
/**
 * The pure half of the timeline's preview sync: reading a runtime clip manifest
 * and a live preview DOM into `TimelineElement`s, and the steps that hydrate a
 * freshly-loaded adapter.
 *
 * Split out of `useTimelineSyncCallbacks.ts`, which held all of this inline
 * inside `processTimelineMessage` and `initializeAdapter` and stood at 642 lines
 * against the studio's 600-line cap. Every function here takes what it needs as
 * an argument, so each is callable — and readable — on its own.
 */

import { createTimelineDomNodeResolver, findClipElementById } from "../lib/timelineElementHelpers";
import { usePlayerStore } from "../store/playerStore";
import type { TimelineElement, DomClipChild, SubCompositionHostState } from "../store/playerStore";
import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
import { LOOP_INFLATED_TIMELINE_SECONDS } from "@hyperframes/core/runtime/composition-length";
import type { ClipTree } from "@hyperframes/core/runtime/clipTree";
import { HF_AUDIO_GROUP_ATTR } from "@hyperframes/core/audio-groups";
import { groupInfoFor } from "../lib/timelineGroupInfo";
import type { PlaybackAdapter, ClipManifestClip, IframeWindow } from "../lib/playbackTypes";
import {
  buildStandaloneRootTimelineElement,
  createTimelineElementFromManifestClip,
  getTimelineElementSelector,
  parseTimelineFromDOM,
} from "../lib/timelineDOM";
import {
  autoHealMissingCompositionIds,
  normalizePreviewViewport,
} from "../lib/timelineIframeHelpers";
import { inspectStudioRuntimeMessage } from "../lib/runtimeProtocol";

/** Reject non-finite, non-positive, and absurdly large (loop-inflated) values. */
export function sanitizeDurationSeconds(value: number): number {
  return Number.isFinite(value) && value > 0 && value < LOOP_INFLATED_TIMELINE_SECONDS ? value : 0;
}

/**
 * A sub-comp child's audio-group membership, read off its live element.
 *
 * Captured during the DOM walk because that walk holds the only reference to
 * the element. A sub-composition that declares both a group and its members
 * keeps those members out of the flat store entirely, so an expanded child has
 * no flat twin to inherit membership from later — without this, a group defined
 * inside a sub-composition produced no group row at all.
 */
function readChildAudioGroupState(child: Element): Partial<DomClipChild> {
  const audioGroup = child.getAttribute(HF_AUDIO_GROUP_ATTR);
  if (!audioGroup) return {};
  const info = groupInfoFor(child.ownerDocument, audioGroup);
  return {
    audioGroup,
    audioGroupLabel: info.label,
    audioGroupVolume: info.volume,
    audioGroupHidden: info.hidden,
    ...(info.fxChain ? { audioGroupFxChain: info.fxChain } : {}),
    ...(info.automation ? { audioGroupAutomation: info.automation } : {}),
  };
}

/**
 * The runtime's clip tree as a child-id -> parent-id map.
 *
 * Empty when the tree is absent (cross-origin, or the runtime has not published
 * it yet), which the caller treats the same as "no nesting".
 */
export function clipTreeParentMap(win: Window | null): Map<string, string> {
  const parentMap = new Map<string, string>();
  const clipTree = (win as (Window & { __clipTree?: ClipTree }) | null)?.__clipTree;
  if (!clipTree) return parentMap;
  const walk = (nodes: ClipTree["roots"]) => {
    for (const node of nodes) {
      if (node.id && node.parentId) parentMap.set(node.id, node.parentId);
      if (node.children.length > 0) walk(node.children);
    }
  };
  walk(clipTree.roots);
  return parentMap;
}

/**
 * One sub-composition host's id'd descendants, as timeline-expandable rows.
 *
 * Descends through id-less structural wrappers (the inlined sub-comp body) and
 * one level into groups for drill-in. Also records each child's parent in
 * `parentMap`, which it mutates: the walk is the only place both ends of the
 * link are in hand.
 */
function collectHostDomChildren(
  hostId: string,
  parentEl: Element,
  parentId: string,
  parentMap: Map<string, string>,
  out: DomClipChild[],
): void {
  for (const child of Array.from(parentEl.children)) {
    if (!child.id) {
      collectHostDomChildren(hostId, child, parentId, parentMap, out); // id-less wrapper
      continue;
    }
    const isGroup = child.hasAttribute("data-hf-group");
    out.push({
      id: child.id,
      parentId,
      hostId,
      label: isGroup ? child.getAttribute("data-hf-group") || child.id : child.id,
      stackingContextId: resolveCssStackingContextId(child),
      ...readChildAudioGroupState(child),
    });
    parentMap.set(child.id, parentId);
    if (isGroup) collectHostDomChildren(hostId, child, child.id, parentMap, out);
  }
}

/**
 * Every sub-composition's internal elements, across the whole manifest.
 *
 * Those elements (group wrappers + their children) carry no `data-start`, so the
 * clip tree and the manifest never enumerate them. Surfacing them studio-side
 * as DOM children + parent links is what lets the timeline expand a
 * sub-comp/group row; the manifest stays lean (timed clips only).
 */
export function collectSubCompositionDomChildren(
  iframeDoc: Document | null,
  clips: readonly ClipManifestClip[],
  parentMap: Map<string, string>,
): DomClipChild[] {
  const out: DomClipChild[] = [];
  if (!iframeDoc) return out;
  for (const clip of clips) {
    if (clip.kind !== "composition" || !clip.id) continue;
    const hostEl = findClipElementById(iframeDoc, clip);
    if (!hostEl) continue;
    const innerRoot = hostEl.querySelector("[data-hf-inner-root]") ?? hostEl;
    collectHostDomChildren(clip.id, innerRoot, clip.id, parentMap, out);
  }
  return out;
}

/** The host-element `data-*` state one element carries, or null when it has none. */
function readSubCompositionHostState(el: Element): SubCompositionHostState | null {
  const state: SubCompositionHostState = {};
  if (el.hasAttribute("data-hidden")) state.hidden = true;
  if (el.hasAttribute("data-timeline-locked")) state.timelineLocked = true;
  const timelineRole = el.getAttribute("data-timeline-role");
  if (timelineRole) state.timelineRole = timelineRole;
  const fxChain = el.getAttribute("data-fx-chain");
  if (fxChain) state.fxChain = fxChain;
  const automation = el.getAttribute("data-automation");
  if (automation) state.automation = automation;
  return Object.keys(state).length > 0 ? state : null;
}

/**
 * Host-element state for every id'd element inside every sub-composition.
 *
 * This walk exists because nothing else in the pipeline can see these
 * attributes. A clip whose parent composition is itself in the manifest is
 * filtered out before the flat store is built, so an expanded child has no twin
 * to inherit from, and the manifest carries timing rather than attributes.
 *
 * Deliberately separate from {@link collectSubCompositionDomChildren}: that walk
 * defines which rows exist and writes `parentMap`, and it stops at the first
 * id'd descendant. Scene footage commonly sits one level below an id'd region
 * wrapper, so it is never reached there. This one descends the whole subtree and
 * touches neither rows nor parentage.
 */
export function collectSubCompositionHostState(
  iframeDoc: Document | null,
  clips: readonly ClipManifestClip[],
): Map<string, SubCompositionHostState> {
  const out = new Map<string, SubCompositionHostState>();
  if (!iframeDoc) return out;
  for (const clip of clips) {
    if (clip.kind !== "composition" || !clip.id) continue;
    const hostEl = findClipElementById(iframeDoc, clip);
    if (!hostEl) continue;
    for (const el of Array.from(hostEl.querySelectorAll("[id]"))) {
      const state = readSubCompositionHostState(el);
      if (state) out.set(el.id, state);
    }
  }
  return out;
}

/** An iframe's document, or null when reading it throws (cross-origin, or the
 *  frame is mid-navigation). */
export function safeContentDocument(iframe: HTMLIFrameElement | null): Document | null {
  try {
    return iframe?.contentDocument ?? null;
  } catch {
    return null;
  }
}

/**
 * The manifest's root clips as TimelineElements, each bound to the live DOM node
 * it was authored as. The pass-scoped resolver makes the binding one-to-one: two clips with
 * the same shape must not both claim the same element.
 */
export function buildTimelineElementsFromClips(
  clips: readonly ClipManifestClip[],
  iframeDoc: Document | null,
): TimelineElement[] {
  const resolveHost = iframeDoc ? createTimelineDomNodeResolver(iframeDoc) : null;
  return clips.map((clip, index) => {
    const hostEl = resolveHost?.(clip, index) ?? null;
    return createTimelineElementFromManifestClip({
      clip,
      fallbackIndex: index,
      doc: iframeDoc,
      hostEl,
    });
  });
}

/**
 * Drop elements that start past the composition's end and trim the ones that
 * straddle it. A non-positive duration means "not known yet" — pass through
 * untouched rather than clamping everything to nothing.
 */
/** Commits the manifest elements, including none. An empty manifest carries a 1s floor, not a duration. */
export function syncManifestTimeline(
  els: readonly TimelineElement[],
  manifestDuration: number,
  storeDuration: number,
  sync: (els: TimelineElement[], duration?: number) => void,
): void {
  const hasDuration = manifestDuration > 0 && els.length > 0;
  sync(
    clampElementsToDuration(els, hasDuration ? manifestDuration : storeDuration),
    hasDuration ? manifestDuration : undefined,
  );
}

function clampElementsToDuration(
  els: readonly TimelineElement[],
  effectiveDuration: number,
): TimelineElement[] {
  if (effectiveDuration <= 0) return [...els];
  return els
    .filter((element) => element.start < effectiveDuration)
    .map((element) => ({
      ...element,
      duration: Math.min(element.duration, effectiveDuration - element.start),
    }))
    .filter((element) => element.duration > 0);
}

/**
 * Seek a freshly-loaded adapter to the playhead the session should resume at,
 * and return it.
 *
 * Honors a seek requested before the adapter was ready. It may sit in either
 * place: `pendingSeekRef` if the store subscription was mounted when requestSeek
 * fired, or only in the store's `requestedSeekTime` if it fired earlier still
 * (deep-link hydration runs before the player subscription mounts, so the
 * request never reaches pendingSeekRef). Reconciling with the store here is what
 * makes a deep-linked `?t=` land instead of starting at 0.
 *
 * The double seek forces a REAL render, not a no-op. After a post-edit reload the
 * freshly rebuilt GSAP timeline can already report being at `startTime`
 * internally (the reload restores the same playhead), so a single
 * `adapter.seek(startTime)` is a GSAP no-op — `tl.seek(t)` at the current time
 * doesn't re-evaluate. That's why a just-dropped clip stayed invisible until the
 * user nudged the playhead: its element's state was never applied at the restore
 * position. Seeking to a DIFFERENT guard value first (a hair off, or 0 when
 * startTime is already ~0) guarantees the follow-up seek crosses a time boundary
 * and re-renders every clip — including the new one.
 */
export function resolveReloadSeekTime(input: {
  pendingSeek: number | null;
  requestedSeek: number | null;
  storeCurrentTime: number;
  duration: number;
}): number {
  const target = input.pendingSeek ?? input.requestedSeek ?? input.storeCurrentTime;
  if (!Number.isFinite(target) || target <= 0) return 0;
  // Only clamp to duration when it's a usable positive number. A non-finite or
  // non-positive duration (e.g. the adapter reports NaN mid-reload) would turn
  // Math.min(target, NaN) into NaN and seek(NaN); return the guarded target
  // unclamped instead so the playhead lands at the intended position.
  if (!Number.isFinite(input.duration) || input.duration <= 0) return target;
  return Math.min(target, input.duration);
}

type SeekablePreview = Pick<PlaybackAdapter, "seek">;

/** Re-run the current frame even when the runtime already reports that time. */
export function reseekPreviewAtTime(preview: SeekablePreview, time: number): void {
  const target = Number.isFinite(time) && time > 0 ? time : 0;
  preview.seek(target > 0.001 ? Math.max(0, target - 0.001) : 0.001);
  preview.seek(target);
}

export function seekAdapterToRestorePoint(
  adapter: PlaybackAdapter,
  pendingSeekRef: { current: number | null },
): number {
  const storeSeek = usePlayerStore.getState().requestedSeekTime;
  const startTime = resolveReloadSeekTime({
    pendingSeek: pendingSeekRef.current,
    requestedSeek: storeSeek,
    storeCurrentTime: usePlayerStore.getState().currentTime,
    duration: adapter.getDuration(),
  });
  pendingSeekRef.current = null;
  if (storeSeek != null) usePlayerStore.getState().clearSeekRequest();
  reseekPreviewAtTime(adapter, startTime);
  return startTime;
}

/** Push the adapter's own duration into the store, ignoring the values
 *  `sanitizeDurationSeconds` rejects and a value already in place. */
export function syncAdapterDuration(
  adapter: PlaybackAdapter,
  setDuration: (d: number) => void,
): void {
  const adapterDur = sanitizeDurationSeconds(adapter.getDuration());
  if (adapterDur > 0 && adapterDur !== usePlayerStore.getState().duration) {
    setDuration(adapterDur);
  }
}

/**
 * Last-resort timeline for a preview whose manifest produced nothing: parse the
 * DOM, and failing that stand the root composition up as a single element.
 * Without it a composition the runtime never enumerated shows an empty timeline
 * rather than one row spanning its own duration.
 */
function syncFallbackTimelineFromDom(
  doc: Document,
  iframe: HTMLIFrameElement | null,
  rootDuration: number,
  syncTimelineElements: (els: TimelineElement[], duration?: number) => void,
): void {
  const els = parseTimelineFromDOM(doc, rootDuration);
  if (els.length > 0) {
    syncTimelineElements(els);
    return;
  }
  const rootComp = doc.querySelector("[data-composition-id]");
  if (!rootComp || rootDuration <= 0) return;
  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]);
}

/** The runtime's timeline message, as the preview posts it. */
export interface RuntimeTimelineMessage {
  clips: ClipManifestClip[];
  durationInFrames: number;
  scenes?: Array<{ id: string; label: string; start: number; duration: number }>;
  protocolVersion?: unknown;
  capabilities?: unknown;
  fps?: unknown;
}

/** Whether a window message came from the preview iframe we are watching.
 *  A message with no `source` (jsdom, synthetic dispatch) is not rejected. */
function isFromPreviewFrame(e: MessageEvent, iframe: HTMLIFrameElement | null): boolean {
  if (!e.source || !iframe) return true;
  return e.source === iframe.contentWindow;
}

/**
 * Whether a message is a preview readiness signal this listener should act on.
 *
 * The main message handler owns protocol-error diagnostics. This readiness-only
 * listener mirrors its acceptance gate without dispatching a duplicate event: an
 * unsupported runtime must not make the iframe appear successfully settled.
 */
export function isPreviewReadinessMessage(
  e: MessageEvent,
  iframe: HTMLIFrameElement | null,
): boolean {
  if (!isFromPreviewFrame(e, iframe)) return false;
  const data = e.data;
  if (data?.source !== "hf-preview") return false;
  if (data?.type !== "state" && data?.type !== "timeline") return false;
  return inspectStudioRuntimeMessage(data).status !== "unsupported";
}

export interface HydrateTimelineFromPreviewInput {
  iframe: HTMLIFrameElement | null;
  adapter: PlaybackAdapter;
  processTimelineMessage: (manifest: RuntimeTimelineMessage) => void;
  enrichMissingCompositions: () => void;
  applyPreviewAudioState: () => void;
  attachIframeShortcutListeners: () => void;
  syncTimelineElements: (els: TimelineElement[], duration?: number) => void;
}

/**
 * Everything the timeline reads off a newly-loaded preview: viewport
 * normalisation, the runtime's own clip manifest, composition enrichment, audio
 * state, and the DOM fallbacks when none of that produced a row.
 *
 * Wrapped in one try, as it always was: any of these can throw on a
 * cross-origin or mid-navigation frame, and none of them is worth failing the
 * adapter's initialisation over.
 */
function normalizePreviewDom(
  doc: Document | null,
  iframeWin: IframeWindow | null,
  attachIframeShortcutListeners: () => void,
): void {
  if (!doc || !iframeWin) return;
  normalizePreviewViewport(doc, iframeWin);
  autoHealMissingCompositionIds(doc);
  attachIframeShortcutListeners();
}

/** Hand the runtime's own clip manifest to the timeline, if it published one. */
function applyRuntimeClipManifest(
  iframeWin: IframeWindow | null,
  processTimelineMessage: (manifest: RuntimeTimelineMessage) => void,
): void {
  const manifest = iframeWin?.__clipManifest;
  if (manifest && manifest.clips.length > 0) processTimelineMessage(manifest);
}

export function hydrateTimelineFromPreview(input: HydrateTimelineFromPreviewInput): void {
  const { iframe, adapter, syncTimelineElements } = input;
  try {
    const doc = safeContentDocument(iframe);
    const iframeWin = (iframe?.contentWindow as IframeWindow | null) ?? null;
    normalizePreviewDom(doc, iframeWin, input.attachIframeShortcutListeners);
    applyRuntimeClipManifest(iframeWin, input.processTimelineMessage);
    input.enrichMissingCompositions();
    input.applyPreviewAudioState();
    if (doc && usePlayerStore.getState().elements.length === 0) {
      syncFallbackTimelineFromDom(doc, iframe, adapter.getDuration(), syncTimelineElements);
    }
  } catch {
    // Cross-origin or mid-navigation preview — the adapter is still initialised.
  }
}