@hyperframes/studio 0.8.60 → 0.8.61

package/src/player/components/VideoThumbnail.tsx

@@ -1,9 +1,17 @@
 import { memo, useCallback, useMemo, useRef, useState } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { useThumbnailLease } from "../../hooks/useThumbnailLease";
-import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
+import {
+  createThumbnailKey,
+  type ThumbnailPriority,
+  type ThumbnailSnapshot,
+} from "../lib/thumbnailScheduler";
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
-import { computeThumbnailStrip, THUMBNAIL_CLIP_HEIGHT } from "./thumbnailUtils";
+import {
+  computeThumbnailStrip,
+  quantizeThumbnailFrameCount,
+  THUMBNAIL_CLIP_HEIGHT,
+} from "./thumbnailUtils";
 
 interface VideoThumbnailProps {
   videoSrc: string;
@@ -15,7 +23,58 @@ interface VideoThumbnailProps {
   projectId?: string;
   sessionEpoch?: number;
   priority?: ThumbnailPriority;
-  rich?: boolean;
+}
+
+function createVideoThumbnailRequest(
+  props: Pick<VideoThumbnailProps, "videoSrc" | "sourceStart" | "sourceRangeDuration"> &
+    Required<Pick<VideoThumbnailProps, "duration" | "projectId" | "sessionEpoch" | "priority">>,
+  frameCount: number,
+  rich: boolean,
+) {
+  const {
+    videoSrc,
+    sourceStart,
+    sourceRangeDuration,
+    duration,
+    projectId,
+    sessionEpoch,
+    priority,
+  } = props;
+  return {
+    key: createThumbnailKey({
+      kind: "video",
+      source: videoSrc,
+      start: sourceStart,
+      duration: sourceRangeDuration ?? duration,
+      frames: frameCount,
+    }),
+    projectId,
+    sessionEpoch,
+    kind: "video" as const,
+    priority,
+    rich,
+    load: (signal: AbortSignal) =>
+      decodeVideoThumbnail(
+        {
+          source: videoSrc,
+          sourceStart,
+          sourceRangeDuration: sourceRangeDuration ?? duration,
+          frameCount,
+          fit: "cover",
+        },
+        signal,
+      ),
+  };
+}
+
+function selectThumbnailSnapshot(
+  poster: ThumbnailSnapshot,
+  rich: ThumbnailSnapshot,
+): ThumbnailSnapshot {
+  if (rich.status === "ready") return rich;
+  if (poster.status === "ready") return poster;
+  if (rich.status === "loading" || poster.status === "loading") return { status: "loading" };
+  return poster;
 }
 
 /** Sparse, bounded video frames supplied by the shared thumbnail scheduler. */
@@ -29,39 +88,36 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   projectId = videoSrc,
   sessionEpoch = 0,
   priority = "visible",
-  rich = false,
 }: VideoThumbnailProps) {
   const [containerWidth, setContainerWidth] = useState(0);
   const observerRef = useRef<ResizeObserver | null>(null);
-  const request = useMemo(
+  const requestFrameCount = quantizeThumbnailFrameCount(
+    computeThumbnailStrip(containerWidth, 16 / 9).frameCount,
+  );
+  const requestProps = useMemo(
     () => ({
-      key: createThumbnailKey({
-        kind: "video",
-        source: videoSrc,
-        start: sourceStart,
-        duration: sourceRangeDuration ?? duration,
-        frames: rich ? 6 : 1,
-      }),
+      videoSrc,
+      sourceStart,
+      sourceRangeDuration,
+      duration,
       projectId,
       sessionEpoch,
-      kind: "video" as const,
       priority,
-      rich,
-      load: (signal: AbortSignal) =>
-        decodeVideoThumbnail(
-          {
-            source: videoSrc,
-            sourceStart,
-            sourceRangeDuration: sourceRangeDuration ?? duration,
-            frameCount: rich ? 6 : 1,
-            fit: "cover",
-          },
-          signal,
-        ),
     }),
-    [duration, priority, projectId, rich, sessionEpoch, sourceRangeDuration, sourceStart, videoSrc],
+    [duration, priority, projectId, sessionEpoch, sourceRangeDuration, sourceStart, videoSrc],
+  );
+  const posterRequest = useMemo(
+    () => createVideoThumbnailRequest(requestProps, 1, false),
+    [requestProps],
+  );
+  const richRequest = useMemo(
+    () => createVideoThumbnailRequest(requestProps, requestFrameCount, true),
+    [requestFrameCount, requestProps],
   );
-  const snapshot = useThumbnailLease(request);
+  const measured = containerWidth > 0;
+  const posterSnapshot = useThumbnailLease(measured ? posterRequest : null);
+  const richSnapshot = useThumbnailLease(measured && requestFrameCount > 1 ? richRequest : null);
+  const snapshot = selectThumbnailSnapshot(posterSnapshot, richSnapshot);
   const value = snapshot.status === "ready" ? snapshot.value : null;
   const urls =
     value?.kind === "filmstrip" ? value.urls : value?.kind === "image" ? [value.url] : [];

package/src/player/components/audioClipLink.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { audioPillFlags, isLinkedVideoAudio } from "./audioClipLink";
+
+const audio = { id: "bed", tag: "audio", src: "assets/City Ride.mp4?v=2" };
+
+describe("isLinkedVideoAudio", () => {
+  it("links an audio pill to a video of the same file", () => {
+    expect(
+      isLinkedVideoAudio(audio, [
+        audio,
+        { id: "picture", tag: "video", src: "/preview/assets/city ride.mp4" },
+      ]),
+    ).toBe(true);
+  });
+
+  it("greys a hidden clip and a muted group without dropping the link", () => {
+    expect(audioPillFlags({ ...audio, hidden: true }, [])).toEqual({
+      muted: true,
+      linked: false,
+    });
+    expect(audioPillFlags({ ...audio, audioGroupHidden: true }, [])).toEqual({
+      muted: true,
+      linked: false,
+    });
+  });
+
+  it("leaves a standalone audio file unlinked", () => {
+    expect(
+      isLinkedVideoAudio({ id: "vo", tag: "audio", src: "assets/voice.wav" }, [
+        { id: "picture", tag: "video", src: "assets/city.mp4" },
+      ]),
+    ).toBe(false);
+  });
+});

package/src/player/components/audioClipLink.ts

@@ -0,0 +1,33 @@
+import type { TimelineElement } from "../store/timelineElement";
+
+function mediaFileKey(src: string | undefined): string | null {
+  if (!src) return null;
+  const path = src.split(/[?#]/, 1)[0] ?? "";
+  const segment = path.split(/[/\\]/).pop()?.trim().toLowerCase() ?? "";
+  return segment.length > 0 ? segment : null;
+}
+
+export function audioPillFlags(
+  audio: Pick<TimelineElement, "id" | "tag" | "src" | "hidden" | "audioGroupHidden">,
+  elements: readonly Pick<TimelineElement, "id" | "tag" | "src">[],
+): { muted: boolean; linked: boolean } {
+  return {
+    muted: audio.hidden === true || audio.audioGroupHidden === true,
+    linked: isLinkedVideoAudio(audio, elements),
+  };
+}
+
+/** An audio pill whose file is also a video clip on this timeline. */
+export function isLinkedVideoAudio(
+  audio: Pick<TimelineElement, "id" | "tag" | "src">,
+  elements: readonly Pick<TimelineElement, "id" | "tag" | "src">[],
+): boolean {
+  if (audio.tag.trim().toLowerCase() !== "audio") return false;
+  const key = mediaFileKey(audio.src);
+  if (!key) return false;
+  return elements.some((element) => {
+    if (element.id === audio.id) return false;
+    if (element.tag.trim().toLowerCase() !== "video") return false;
+    return mediaFileKey(element.src) === key;
+  });
+}

package/src/player/components/audioWaveformPeaks.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { decimatePeaks, loudnessToOpacity } from "./audioWaveformPeaks";
+
+describe("loudnessToOpacity", () => {
+  it("maps silence to the floor and the file peak to fully opaque", () => {
+    expect(loudnessToOpacity(0)).toBe(0.64);
+    expect(loudnessToOpacity(1)).toBe(1);
+    expect(loudnessToOpacity(0.5)).toBeCloseTo(0.82, 5);
+  });
+
+  it("clamps out-of-range and non-finite peaks to the same floor or ceiling", () => {
+    expect(loudnessToOpacity(-0.2)).toBe(0.64);
+    expect(loudnessToOpacity(4)).toBe(1);
+    expect(loudnessToOpacity(Number.NaN)).toBe(0.64);
+  });
+});
+
+describe("decimatePeaks", () => {
+  it("keeps a transient that a single sample in the bucket would miss", () => {
+    const peaks = [0, 0, 0, 1, 0, 0, 0, 0];
+    expect(decimatePeaks(peaks, 0, 1, 2)).toEqual([1, 0]);
+  });
+
+  it("windows to the trimmed source slice", () => {
+    expect(decimatePeaks([0.1, 0.2, 0.9, 0.3], 0.5, 1, 1)).toEqual([0.9]);
+  });
+
+  it("returns no bars when there is nothing to draw", () => {
+    expect(decimatePeaks([], 0, 1, 4)).toEqual([]);
+    expect(decimatePeaks([0.5], 0, 1, 0)).toEqual([]);
+  });
+});

package/src/player/components/audioWaveformPeaks.ts

@@ -0,0 +1,46 @@
+/** Quietest bar that still clears the timeline contrast gate on the 70% pill. */
+const LOUDNESS_OPACITY_FLOOR = 0.64;
+
+const LOUDNESS_OPACITY_SPAN = 1 - LOUDNESS_OPACITY_FLOOR;
+
+/** Peak is 0–1 against the file's own maximum. Hotter peaks paint more opaque. */
+export function loudnessToOpacity(peak: number): number {
+  if (!Number.isFinite(peak)) return LOUDNESS_OPACITY_FLOOR;
+  const clamped = Math.min(1, Math.max(0, peak));
+  return LOUDNESS_OPACITY_FLOOR + LOUDNESS_OPACITY_SPAN * clamped;
+}
+
+/**
+ * Max-in-bucket over the trimmed peak window, one value per bar.
+ * A point sample drops a transient that sits between bar columns.
+ */
+export function decimatePeaks(
+  peaks: readonly number[],
+  startFraction: number,
+  endFraction: number,
+  barCount: number,
+): number[] {
+  if (barCount <= 0 || peaks.length === 0) return [];
+  const startFractionClamped = Math.min(1, Math.max(0, startFraction));
+  const endFractionClamped = Math.min(1, Math.max(startFractionClamped, endFraction));
+  const start = Math.floor(startFractionClamped * peaks.length);
+  const endIndex = Math.ceil(endFractionClamped * peaks.length);
+  const end = Math.max(start + 1, Math.min(peaks.length, endIndex));
+  const span = end - start;
+  const bars: number[] = [];
+  for (let index = 0; index < barCount; index++) {
+    let from = start + Math.floor((index * span) / barCount);
+    let to = start + Math.floor(((index + 1) * span) / barCount);
+    if (to <= from) {
+      from = Math.min(from, end - 1);
+      to = from + 1;
+    }
+    let max = 0;
+    for (let cursor = from; cursor < to; cursor++) {
+      const value = peaks[cursor] ?? 0;
+      if (value > max) max = value;
+    }
+    bars.push(max);
+  }
+  return bars;
+}

package/src/player/components/thumbnailUtils.test.ts

@@ -3,6 +3,7 @@ import {
   computeThumbnailStrip,
   encodePreviewPath,
   resolveMediaPreviewUrl,
+  quantizeThumbnailFrameCount,
   THUMBNAIL_CLIP_HEIGHT,
 } from "./thumbnailUtils";
 
@@ -19,6 +20,10 @@ describe("computeThumbnailStrip", () => {
     expect(frameCount * frameW).toBeGreaterThanOrEqual(500);
   });
 
+  it("paints tiles across the full clip past the shared visible-frame budget", () => {
+    expect(computeThumbnailStrip(14_400, 16 / 9).frameCount).toBeGreaterThan(33);
+  });
+
   it("returns one tile when the container width is unknown", () => {
     expect(computeThumbnailStrip(0, 16 / 9).frameCount).toBe(1);
     expect(computeThumbnailStrip(-10, 16 / 9).frameCount).toBe(1);
@@ -50,6 +55,18 @@ describe("computeThumbnailStrip", () => {
   });
 });
 
+describe("quantizeThumbnailFrameCount", () => {
+  it("uses doubling buckets and never exceeds the 4K geometry ceiling", () => {
+    expect(quantizeThumbnailFrameCount(5)).toBe(8);
+    expect(quantizeThumbnailFrameCount(32)).toBe(32);
+    expect(quantizeThumbnailFrameCount(34)).toBe(33);
+  });
+
+  it("caps decode requests at the shared visible-frame budget", () => {
+    expect(quantizeThumbnailFrameCount(124)).toBe(33);
+  });
+});
+
 describe("resolveMediaPreviewUrl", () => {
   it("reroutes same-origin root media resolved by the preview iframe", () => {
     expect(

package/src/player/components/thumbnailUtils.ts

@@ -1,4 +1,5 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
+import { MAX_VISIBLE_THUMBNAIL_FRAMES } from "../lib/timelineViewportBudgets";
 /** Rendered height of a timeline-clip thumbnail strip, in CSS px. */
 export const THUMBNAIL_CLIP_HEIGHT = 66;
 
@@ -9,6 +10,12 @@ export interface ThumbnailStripLayout {
   frameCount: number;
 }
 
+/** Quantize request identities so a pixel-by-pixel resize does not thrash the cache. */
+export function quantizeThumbnailFrameCount(frameCount: number): number {
+  const safeCount = Math.max(1, Number.isFinite(frameCount) ? Math.ceil(frameCount) : 1);
+  return Math.min(MAX_VISIBLE_THUMBNAIL_FRAMES, 2 ** Math.ceil(Math.log2(safeCount)));
+}
+
 /**
  * Measure an image without mounting it in React's DOM. The scheduler owns the
  * abort signal, so an unmounted clip cannot leave Blink retaining a pending

package/src/player/components/timelineTheme.ts

@@ -32,6 +32,9 @@ export interface TimelineTheme {
   panelResizeActive: string;
   clipRadius: string;
   audioClipRadius: string;
+  transitionZone: string;
+  transitionBadge: string;
+  transitionBadgeInk: string;
 }
 
 const TRACK_STYLE: TimelineTrackStyle = {
@@ -69,6 +72,9 @@ export const defaultTimelineTheme: TimelineTheme = {
   panelResizeActive: "var(--timeline-resize-active)",
   clipRadius: "var(--timeline-clip-radius)",
   audioClipRadius: "var(--timeline-clip-audio-radius)",
+  transitionZone: "var(--timeline-transition-zone)",
+  transitionBadge: "var(--timeline-transition-badge)",
+  transitionBadgeInk: "var(--timeline-transition-badge-ink)",
 };
 
 export type ClipWidthLadder = "labeled" | "picture" | "frame";

package/src/player/components/timelineTransitionSeams.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { deriveTimelineTransitionSeams } from "./timelineTransitionSeams";
+import type { TimelineElement } from "../store/playerStore";
+
+const clip = (
+  id: string,
+  start: number,
+  duration: number,
+  track = 0,
+  transitionLabel?: string,
+): TimelineElement => ({
+  id,
+  tag: "video",
+  start,
+  duration,
+  track,
+  transitionLabel,
+});
+
+describe("deriveTimelineTransitionSeams", () => {
+  it("finds a labelled transition and centers the seam in the shared time", () => {
+    const label = "hf:transition:out:in:crossfade";
+    const [seam] = deriveTimelineTransitionSeams([
+      clip("in", 1.8, 2, 0, label),
+      clip("out", 0, 2, 0, label),
+    ]);
+    expect(seam?.outgoing).toEqual(clip("out", 0, 2, 0, label));
+    expect(seam?.incoming).toEqual(clip("in", 1.8, 2, 0, label));
+    expect(seam?.centerTime).toBeCloseTo(1.9);
+    expect(seam?.duration).toBeCloseTo(0.2);
+  });
+
+  it("does not badge an unlabelled overlap", () => {
+    expect(deriveTimelineTransitionSeams([clip("out", 0, 2), clip("in", 1.8, 2)])).toEqual([]);
+  });
+
+  it("does not badge a cross-track overlap", () => {
+    const label = "hf:transition:out:in:crossfade";
+    expect(
+      deriveTimelineTransitionSeams([clip("out", 0, 2, 0, label), clip("in", 1.8, 2, 1, label)]),
+    ).toEqual([]);
+  });
+
+  it("rejects crisp gaps and touching edges", () => {
+    expect(deriveTimelineTransitionSeams([clip("a", 0, 2), clip("b", 2.04, 1)])).toEqual([]);
+    expect(deriveTimelineTransitionSeams([clip("a", 0, 2), clip("b", 2, 1)])).toEqual([]);
+  });
+});

package/src/player/components/timelineTransitionSeams.ts

@@ -0,0 +1,36 @@
+import type { TimelineElement } from "../store/playerStore";
+
+export interface TimelineTransitionSeam {
+  outgoing: TimelineElement;
+  incoming: TimelineElement;
+  centerTime: number;
+  duration: number;
+}
+
+export function isTransitionPair(a: TimelineElement, b: TimelineElement): boolean {
+  return Boolean(a.transitionLabel && a.transitionLabel === b.transitionLabel);
+}
+
+export function deriveTimelineTransitionSeams(
+  elements: readonly TimelineElement[],
+): TimelineTransitionSeam[] {
+  const sorted = [...elements].sort((left, right) => left.start - right.start);
+  const seams: TimelineTransitionSeam[] = [];
+  for (let index = 0; index < sorted.length - 1; index += 1) {
+    const outgoing = sorted[index]!;
+    const incoming = sorted[index + 1]!;
+    if (outgoing.track !== incoming.track || !isTransitionPair(outgoing, incoming)) continue;
+    const outgoingEnd = outgoing.start + outgoing.duration;
+    const overlapStart = Math.max(outgoing.start, incoming.start);
+    const overlapEnd = Math.min(outgoingEnd, incoming.start + incoming.duration);
+    const duration = overlapEnd - overlapStart;
+    if (duration <= 0) continue;
+    seams.push({
+      outgoing,
+      incoming,
+      centerTime: overlapStart + duration / 2,
+      duration,
+    });
+  }
+  return seams;
+}

package/src/player/components/timelineZones.test.ts

@@ -171,6 +171,24 @@ describe("normalizeToZones — CapCut-stable lanes follow the track-index (never
 });
 
 describe("normalizeToZones — legacy overlap spill (display-only, deterministic)", () => {
+  it("keeps a labelled transition pair on one row", () => {
+    const transitionLabel = "hf:transition:outgoing:incoming:crossfade";
+    const out = normalizeToZones([
+      { ...zClip("outgoing", 0, 2.5, 0, 0), transitionLabel },
+      { ...zClip("incoming", 2, 2.5, 0, 0), transitionLabel },
+    ]);
+    expect(trackOf(out, "outgoing")).toBe(0);
+    expect(trackOf(out, "incoming")).toBe(0);
+  });
+
+  it("still splits an unlabelled overlap", () => {
+    const out = normalizeToZones([
+      zClip("outgoing", 0, 2.5, 0, 0),
+      zClip("incoming", 2, 2.5, 0, 0),
+    ]);
+    expect(trackOf(out, "outgoing")).not.toBe(trackOf(out, "incoming"));
+  });
+
   it("splits time-overlapping SAME-track clips onto adjacent sub-lanes (no visible overlap)", () => {
     // a [0,5), b [2,7) overlaps a, c [6,9) sequential — all authored on track 1.
     // The editor forbids per-track overlap, but a legacy file can carry it; the

package/src/player/components/timelineZones.ts

@@ -1,5 +1,6 @@
 import type { TimelineElement } from "../store/playerStore";
 import { isAudioTimelineElement } from "../../utils/timelineInspector";
+import { isTransitionPair } from "./timelineTransitionSeams";
 
 /**
  * Free-form vertical zones, top → bottom: visual, audio. Canvas layering is
@@ -66,7 +67,9 @@ function packTrackLanes(
   const ordered = [...clips].sort(byStableId);
   const lanes: TimelineElement[][] = [];
   for (const el of ordered) {
-    let sub = lanes.findIndex((occ) => occ.every((o) => !overlaps(o, el)));
+    let sub = lanes.findIndex((occ) =>
+      occ.every((o) => !overlaps(o, el) || isTransitionPair(o, el)),
+    );
     if (sub === -1) {
       sub = lanes.length;
       lanes.push([]);

package/src/player/lib/playbackTypes.ts

@@ -32,6 +32,8 @@ export interface TimelineLike {
   time: () => number;
   duration: () => number;
   isActive: () => boolean;
+  labels?: Record<string, number>;
+  getLabels?: () => Record<string, number>;
 }
 
 export interface ClipManifestClip extends RuntimeTimelineClipIdentity {

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

@@ -1,5 +1,6 @@
 // @vitest-environment jsdom
 import { describe, expect, it } from "vitest";
+import { gsap } from "gsap";
 import {
   createTimelineElementFromManifestClip,
   parseTimelineFromDOM,
@@ -20,6 +21,33 @@ function makeDoc(html: string): Document {
 }
 
 describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
+  it("bridges a real GSAP transition marker onto both named clips", () => {
+    document.body.innerHTML = `
+      <div data-composition-id="root">
+        <img data-hf-id="outgoing" data-start="0" data-duration="2.5" data-track-index="0" />
+        <img data-hf-id="incoming" data-start="2" data-duration="2.5" data-track-index="0" />
+      </div>
+    `;
+    const timeline = gsap.timeline({ paused: true });
+    timeline.addLabel("hf:transition:outgoing:incoming:crossfade", 2);
+    const runtimeWindow = window as Window & {
+      __timelines?: Record<string, typeof timeline>;
+    };
+    runtimeWindow.__timelines = { main: timeline };
+
+    try {
+      const elements = parseTimelineFromDOM(document, 5);
+      expect(elements.map((element) => element.transitionLabel)).toEqual([
+        "hf:transition:outgoing:incoming:crossfade",
+        "hf:transition:outgoing:incoming:crossfade",
+      ]);
+    } finally {
+      delete runtimeWindow.__timelines;
+      timeline.kill();
+      document.body.innerHTML = "";
+    }
+  });
+
   it("harvests hfId from a data-start element that has data-hf-id", () => {
     const doc = makeDoc(`
       <div data-composition-id="root">

package/src/player/lib/timelineDOM.ts

@@ -9,10 +9,11 @@
  */
 
 import type { TimelineElement } from "../store/playerStore";
-import type { ClipManifestClip } from "./playbackTypes";
+import type { ClipManifestClip, IframeWindow, TimelineLike } from "./playbackTypes";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import { readClipTiming } from "@hyperframes/core/composition-contract";
 import { groupInfoFor } from "./timelineGroupInfo";
+import { transitionLabelsForDocument } from "./timelineTransitionMetadata";
 import {
   resolveMediaElement,
   applyMediaMetadataFromElement,
@@ -75,6 +76,9 @@ export function createTimelineElementFromManifestClip(params: {
 }): TimelineElement {
   const { clip, fallbackIndex, doc } = params;
   let hostEl = params.hostEl ?? null;
+  const transitionLabels = doc
+    ? transitionLabelsForDocument(doc, (doc.defaultView as IframeWindow | null)?.__timelines)
+    : new Map<Element, string>();
   const label = getTimelineElementDisplayLabel({
     id: clip.id,
     label: clip.label,
@@ -108,6 +112,10 @@ export function createTimelineElementFromManifestClip(params: {
   const entry: TimelineElement = {
     id: identity.id,
     label,
+    transitionLabel:
+      (hostEl && transitionLabels.get(hostEl)) ||
+      hostEl?.getAttribute("data-transition-label") ||
+      undefined,
     key: identity.key,
     kind: clip.kind,
     tag: resolveClipTag(clip),
@@ -134,6 +142,10 @@ export function createTimelineElementFromManifestClip(params: {
 
   if (hostEl) {
     applyMediaMetadataFromElement(entry, hostEl);
+    if (!entry.src) {
+      const rawSrc = hostEl.getAttribute("src");
+      if (rawSrc) entry.src = new URL(rawSrc, hostEl.baseURI).href;
+    }
     if (hostEl.hasAttribute("data-hidden")) entry.hidden = true;
     const timelineRole = hostEl.getAttribute("data-timeline-role");
     if (timelineRole) entry.timelineRole = timelineRole;
@@ -205,11 +217,19 @@ export function createTimelineElementFromManifestClip(params: {
  * 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[] {
+export function parseTimelineFromDOM(
+  doc: Document,
+  rootDuration: number,
+  timelines?: Readonly<Record<string, TimelineLike>>,
+): TimelineElement[] {
   const rootComp = doc.querySelector("[data-composition-id]");
   const nodes = doc.querySelectorAll("[data-start]");
   const els: TimelineElement[] = [];
   let trackCounter = 0;
+  const transitionLabels = transitionLabelsForDocument(
+    doc,
+    timelines ?? (doc.defaultView as IframeWindow | null)?.__timelines,
+  );
 
   // fallow-ignore-next-line complexity
   nodes.forEach((node) => {
@@ -252,6 +272,8 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
     const entry: TimelineElement = {
       id: identity.id,
       label,
+      transitionLabel:
+        transitionLabels.get(el) ?? el.getAttribute("data-transition-label") ?? undefined,
       key: identity.key,
       kind:
         compId && compId !== rootComp?.getAttribute("data-composition-id")

package/src/player/lib/timelineIframeHelpers.ts

@@ -22,6 +22,7 @@ import {
   readTimelineElementZIndex,
 } from "./timelineElementHelpers";
 import { postRuntimeControlMessage } from "./runtimeProtocol";
+import { transitionLabelsForDocument } from "./timelineTransitionMetadata";
 
 // ---------------------------------------------------------------------------
 // Viewport / DOM normalisation
@@ -414,6 +415,7 @@ function buildMissingCompositionEntry(params: {
 }): TimelineElement | null {
   const { doc, iframeWin, element, compositionId, rootDuration, fallbackIndex, resolveEnd } =
     params;
+  const transitionLabels = transitionLabelsForDocument(doc, iframeWin.__timelines);
   const timing = readClipTiming(element, {
     resolveReferenceEnd: (refId) => resolveEnd(refId, new Set([compositionId])),
   });
@@ -447,6 +449,8 @@ function buildMissingCompositionEntry(params: {
   const entry: TimelineElement = {
     id: identity.id,
     label,
+    transitionLabel:
+      transitionLabels.get(element) ?? element.getAttribute("data-transition-label") ?? undefined,
     key: identity.key,
     tag: element.tagName.toLowerCase(),
     start: window.start,
@@ -459,6 +463,9 @@ function buildMissingCompositionEntry(params: {
     selectorIndex,
     sourceFile,
     zIndex: readTimelineElementZIndex(element),
+    src: optionalNonEmpty(element.getAttribute("src"))
+      ? new URL(element.getAttribute("src")!, element.baseURI).href
+      : undefined,
   };
   return attachCompositionSource(entry, element, compositionSrc);
 }