@hyperframes/studio 0.5.0-alpha.11 → 0.5.0-alpha.13

package/src/player/hooks/useTimelinePlayer.ts

@@ -64,9 +64,12 @@ function wrapTimeline(tl: TimelineLike): PlaybackAdapter {
 }
 
 function resolveMediaElement(el: Element): HTMLMediaElement | HTMLImageElement | null {
-  if (el instanceof HTMLMediaElement || el instanceof HTMLImageElement) return el;
+  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 HTMLMediaElement || candidate instanceof HTMLImageElement
+  return candidate instanceof MediaElementCtor || candidate instanceof ImageElementCtor
     ? candidate
     : null;
 }
@@ -92,7 +95,9 @@ function applyMediaMetadataFromElement(entry: TimelineElement, el: Element): voi
   const src = mediaEl.getAttribute("src");
   if (src) entry.src = src;
 
-  if (!(mediaEl instanceof HTMLMediaElement)) return;
+  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");
@@ -165,11 +170,24 @@ export function shouldIgnorePlaybackShortcutEvent(
   );
 }
 
+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";
+}
+
 /**
  * Parse [data-start] elements from a Document into TimelineElement[].
  * Shared helper — used by onIframeLoad fallback, handleMessage, and enrichMissingCompositions.
  */
-function parseTimelineFromDOM(doc: Document, rootDuration: number): TimelineElement[] {
+export function parseTimelineFromDOM(doc: Document, rootDuration: number): TimelineElement[] {
   const rootComp = doc.querySelector("[data-composition-id]");
   const nodes = doc.querySelectorAll("[data-start]");
   const els: TimelineElement[] = [];
@@ -200,17 +218,24 @@ function parseTimelineFromDOM(doc: Document, rootDuration: number): TimelineElem
     const selector = getTimelineElementSelector(el);
     const sourceFile = getTimelineElementSourceFile(el);
     const selectorIndex = getTimelineElementSelectorIndex(doc, el, selector);
-    const id = el.id || compId || el.className?.split(" ")[0] || tagLower;
+    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,
-      key: buildTimelineElementKey({
-        id,
-        fallbackIndex: els.length,
-        domId: el.id || undefined,
-        selector,
-        selectorIndex,
-        sourceFile,
-      }),
+      id: identity.id,
+      label,
+      key: identity.key,
       tag: tagLower,
       start,
       duration: dur,
@@ -310,6 +335,39 @@ function buildTimelineElementKey(params: {
   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]");
@@ -352,6 +410,103 @@ export function findTimelineDomNodeForClip(
   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) ??
@@ -380,6 +535,10 @@ export function buildStandaloneRootTimelineElement(params: {
 
   return {
     id: params.compositionId,
+    label: getTimelineElementDisplayLabel({
+      id: params.compositionId,
+      tag: params.tagName,
+    }),
     key: buildTimelineElementKey({
       id: params.compositionId,
       fallbackIndex: 0,
@@ -500,8 +659,10 @@ export function mergeTimelineElementsPreservingDowngrades(
     return nextElements;
   }
 
-  const nextIds = new Set(nextElements.map((element) => element.id));
-  const preserved = currentElements.filter((element) => !nextIds.has(element.id));
+  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];
 }
@@ -876,72 +1037,16 @@ export function useTimelinePlayer() {
       }
       const usedHostEls = new Set<Element>();
       const els: TimelineElement[] = filtered.map((clip, index) => {
-        let hostEl = iframeDoc
+        const hostEl = iframeDoc
           ? findTimelineDomNodeForClip(iframeDoc, clip, index, usedHostEls)
           : null;
         if (hostEl) usedHostEls.add(hostEl);
-        const id = clip.id || clip.label || clip.tagName || "element";
-        const entry: TimelineElement = {
-          id,
-          tag: clip.tagName || clip.kind,
-          start: clip.start,
-          duration: clip.duration,
-          track: clip.track,
-        };
-        if (hostEl) {
-          entry.domId = hostEl.id || undefined;
-          entry.selector = getTimelineElementSelector(hostEl);
-          entry.selectorIndex =
-            iframeDoc && entry.selector
-              ? getTimelineElementSelectorIndex(iframeDoc, hostEl, entry.selector)
-              : undefined;
-          entry.sourceFile = getTimelineElementSourceFile(hostEl);
-          applyMediaMetadataFromElement(entry, hostEl);
-        }
-        if (clip.assetUrl) entry.src = clip.assetUrl;
-        if (clip.kind === "composition" && clip.compositionId) {
-          // The bundler renames data-composition-src to data-composition-file
-          // after inlining, so the clip manifest may not have compositionSrc.
-          // Fall back to reading data-composition-file from the DOM.
-          let resolvedSrc = clip.compositionSrc;
-          if (!resolvedSrc) {
-            hostEl =
-              iframeDoc?.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) {
-            // Inline composition (no external file) — expose inner video for thumbnails
-            const innerVideo = hostEl.querySelector("video[src]");
-            if (innerVideo) {
-              entry.src = innerVideo.getAttribute("src") || undefined;
-              entry.tag = "video";
-            }
-          }
-          if (hostEl) {
-            const iframeDoc = iframeRef.current?.contentDocument;
-            entry.domId = hostEl.id || undefined;
-            entry.selector = getTimelineElementSelector(hostEl);
-            entry.selectorIndex =
-              iframeDoc && entry.selector
-                ? getTimelineElementSelectorIndex(iframeDoc, hostEl, entry.selector)
-                : undefined;
-            entry.sourceFile = getTimelineElementSourceFile(hostEl);
-          }
-        }
-        entry.key = buildTimelineElementKey({
-          id,
+        return createTimelineElementFromManifestClip({
+          clip,
           fallbackIndex: index,
-          domId: entry.domId,
-          selector: entry.selector,
-          selectorIndex: entry.selectorIndex,
-          sourceFile: entry.sourceFile,
+          doc: iframeDoc,
+          hostEl,
         });
-        return entry;
       });
       const rawDuration = data.durationInFrames / 30;
       // Clamp non-finite or absurdly large durations — the runtime can emit
@@ -1055,17 +1160,24 @@ export function useTimelinePlayer() {
         const selector = getTimelineElementSelector(el);
         const sourceFile = getTimelineElementSourceFile(el);
         const selectorIndex = getTimelineElementSelectorIndex(doc, el, selector);
-        const id = el.id || compId;
+        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,
-          key: buildTimelineElementKey({
-            id,
-            fallbackIndex: missing.length,
-            domId: el.id || undefined,
-            selector,
-            selectorIndex,
-            sourceFile,
-          }),
+          id: identity.id,
+          label,
+          key: identity.key,
           tag: el.tagName.toLowerCase(),
           start,
           duration: dur,

package/src/player/store/playerStore.ts

@@ -2,6 +2,7 @@ import { create } from "zustand";
 
 export interface TimelineElement {
   id: string;
+  label?: string;
   key?: string;
   tag: string;
   start: number;