@hyperframes/studio 0.8.59 → 0.8.61

package/src/player/components/timelineTheme.ts

@@ -27,14 +27,14 @@ export interface TimelineTheme {
   clipBorder: string;
   clipBorderHover: string;
   clipBorderActive: string;
-  clipShadow: string;
-  clipShadowHover: string;
-  clipShadowActive: string;
-  clipShadowDragging: string;
   handleColor: string;
   panelResizeSeam: string;
   panelResizeActive: string;
   clipRadius: string;
+  audioClipRadius: string;
+  transitionZone: string;
+  transitionBadge: string;
+  transitionBadgeInk: string;
 }
 
 const TRACK_STYLE: TimelineTrackStyle = {
@@ -67,18 +67,25 @@ export const defaultTimelineTheme: TimelineTheme = {
   clipBorder: "var(--timeline-clip-border)",
   clipBorderHover: "var(--timeline-clip-border-hover)",
   clipBorderActive: "var(--timeline-clip-border-active)",
-  // Shadows stay literal: a light host still wants a dark contact shadow, so
-  // these are not part of the surface/hairline/text/clip-colour theming ask.
-  clipShadow: "none",
-  clipShadowHover: "0 2px 8px rgba(0,0,0,0.2)",
-  clipShadowActive: "0 2px 8px rgba(0,0,0,0.2), 0 0 0 1px rgba(255,255,255,0.04)",
-  clipShadowDragging: "0 8px 24px rgba(0,0,0,0.4), 0 0 0 1px rgba(255,255,255,0.06)",
   handleColor: "var(--timeline-handle)",
   panelResizeSeam: "var(--timeline-resize-seam)",
   panelResizeActive: "var(--timeline-resize-active)",
-  clipRadius: "var(--radius-lg)",
+  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";
+
+/** Label chip from 60px. Under 24px the clip is one cropped frame. */
+export function clipWidthLadder(widthPx: number): ClipWidthLadder {
+  if (widthPx < 24) return "frame";
+  if (widthPx < 60) return "picture";
+  return "labeled";
+}
+
 export function getTimelineTrackStyle(_tag: string): TimelineTrackStyle {
   return TRACK_STYLE;
 }

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);
 }

package/src/player/lib/timelineTransitionMetadata.ts

@@ -0,0 +1,52 @@
+import type { TimelineLike } from "./playbackTypes";
+
+const TRANSITION_LABEL_PREFIX = "hf:transition:";
+
+type TimelineWithLabels = TimelineLike & {
+  labels?: Record<string, number>;
+  getLabels?: () => Record<string, number>;
+};
+
+function transitionParts(label: string): [string, string] | null {
+  if (!label.startsWith(TRANSITION_LABEL_PREFIX)) return null;
+  const parts = label.slice(TRANSITION_LABEL_PREFIX.length).split(":");
+  if (parts.length < 3 || !parts[0] || !parts[1]) return null;
+  return [parts[0], parts[1]];
+}
+
+function findTimedElement(doc: Document, markerId: string): Element | null {
+  for (const candidate of [markerId, `el-${markerId}`]) {
+    const byId = doc.getElementById(candidate);
+    if (byId?.hasAttribute("data-start")) return byId;
+  }
+  return (
+    Array.from(doc.querySelectorAll("[data-start]")).find(
+      (element) =>
+        element.getAttribute("data-hf-id") === markerId ||
+        element.getAttribute("data-composition-id") === markerId,
+    ) ?? null
+  );
+}
+
+export function transitionLabelsForDocument(
+  doc: Document,
+  timelines: Readonly<Record<string, TimelineLike>> | undefined,
+): ReadonlyMap<Element, string> {
+  const labels = new Map<Element, string>();
+  if (!timelines) return labels;
+
+  for (const timeline of Object.values(timelines) as TimelineWithLabels[]) {
+    const timelineLabels = timeline.getLabels?.() ?? timeline.labels ?? {};
+    for (const label of Object.keys(timelineLabels)) {
+      const pair = transitionParts(label);
+      if (!pair) continue;
+      const outgoing = findTimedElement(doc, pair[0]);
+      const incoming = findTimedElement(doc, pair[1]);
+      if (outgoing && incoming) {
+        labels.set(outgoing, label);
+        labels.set(incoming, label);
+      }
+    }
+  }
+  return labels;
+}

package/src/player/lib/timelineViewportBudgets.ts

@@ -49,6 +49,7 @@ export interface TimelineViewportBudgets {
 
 const MEBIBYTE = 1024 * 1024;
 const DAY_MS = 24 * 60 * 60 * 1000;
+export const MAX_VISIBLE_THUMBNAIL_FRAMES = Math.ceil(3840 / (66 * (16 / 9))); // 4K timeline width / tallest 16:9 tile.
 
 /**
  * The sole default budget owner for timeline viewport and media virtualization.
@@ -66,7 +67,7 @@ export const TIMELINE_VIEWPORT_BUDGETS: Readonly<TimelineViewportBudgets> = Obje
   posterMaxPhysicalWidth: 240,
   posterMaxPhysicalHeight: 135,
   posterDprCap: 1.5,
-  richPreviewFrameCount: 6,
+  richPreviewFrameCount: MAX_VISIBLE_THUMBNAIL_FRAMES,
   concurrentVideoDecodes: 2,
   concurrentMetadataJobs: 4,
   concurrentCompositionFetches: 2,

package/src/player/store/timelineElement.ts

@@ -12,6 +12,7 @@ import type { ClipManifestClip } from "../lib/playbackTypes";
 export interface TimelineElement {
   id: string;
   label?: string;
+  transitionLabel?: string;
   key?: string;
   kind?: ClipManifestClip["kind"];
   tag: string;

package/src/styles/hex-baseline.json

@@ -1,5 +1,5 @@
 {
-  "total": 385,
+  "total": 297,
   "files": {
     "packages/studio/src/captions/components/CaptionOverlay.tsx": 5,
     "packages/studio/src/captions/components/CaptionTimeline.tsx": 11,
@@ -49,35 +49,16 @@
     "packages/studio/src/components/sidebar/AudioRow.tsx": 2,
     "packages/studio/src/components/ui/HyperframesMark.tsx": 4,
     "packages/studio/src/hooks/useInlineTextEdit.ts": 1,
-    "packages/studio/src/player/components/AudioWaveform.tsx": 6,
+    "packages/studio/src/player/components/AudioWaveform.tsx": 2,
     "packages/studio/src/player/components/BeatStrip.tsx": 6,
     "packages/studio/src/player/components/CompositionThumbnail.tsx": 2,
-    "packages/studio/src/player/components/ImageThumbnail.tsx": 6,
-    "packages/studio/src/player/components/LayerDisclosureRow.tsx": 3,
     "packages/studio/src/player/components/Player.tsx": 2,
     "packages/studio/src/player/components/PlayerControls.tsx": 1,
-    "packages/studio/src/player/components/PlayheadIndicator.tsx": 3,
     "packages/studio/src/player/components/ShortcutsPanel.tsx": 7,
     "packages/studio/src/player/components/SpeedMenu.tsx": 2,
-    "packages/studio/src/player/components/TimelineAutomationLane.tsx": 4,
-    "packages/studio/src/player/components/TimelineCanvas.tsx": 13,
-    "packages/studio/src/player/components/TimelineClipDiamonds.tsx": 2,
-    "packages/studio/src/player/components/TimelineDiamondConnectors.tsx": 2,
-    "packages/studio/src/player/components/TimelineEmptyState.tsx": 1,
-    "packages/studio/src/player/components/TimelineFxButton.tsx": 8,
-    "packages/studio/src/player/components/TimelineGroupHeader.tsx": 6,
-    "packages/studio/src/player/components/TimelineGroupLaneLabels.tsx": 1,
-    "packages/studio/src/player/components/TimelineGroupRow.tsx": 1,
-    "packages/studio/src/player/components/TimelineRazorInteraction.tsx": 1,
-    "packages/studio/src/player/components/TimelineRuler.tsx": 1,
-    "packages/studio/src/player/components/TimelineShortcutHint.tsx": 2,
-    "packages/studio/src/player/components/TimelineTrackHeader.tsx": 2,
-    "packages/studio/src/player/components/TimelineTrackPlainHeader.tsx": 2,
-    "packages/studio/src/player/components/VideoThumbnail.tsx": 6,
-    "packages/studio/src/player/components/timelineTheme.ts": 5,
     "packages/studio/src/player/components/trackHeaderLabelRows.tsx": 6,
-    "packages/studio/src/styles/studio.css": 63,
     "packages/studio/src/telemetry/client.ts": 1,
+    "packages/studio/src/styles/studio.css": 48,
     "packages/studio/src/webmcp/webmcpTestUtils.ts": 1
   }
 }