@hyperframes/studio 0.5.0-alpha.9 → 0.5.0

package/src/player/hooks/useTimelinePlayer.ts

@@ -1,7 +1,7 @@
 import { useRef, useCallback } from "react";
 import { usePlayerStore, liveTime, type TimelineElement } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import { frameToSeconds, STUDIO_PREVIEW_FPS } from "../lib/time";
+import { stepFrameTime, STUDIO_PREVIEW_FPS } from "../lib/time";
 import { useCaptionStore } from "../../captions/store";
 
 interface PlaybackAdapter {
@@ -22,7 +22,7 @@ interface TimelineLike {
   isActive: () => boolean;
 }
 
-export interface ClipManifestClip {
+interface ClipManifestClip {
   id: string | null;
   label: string;
   start: number;
@@ -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,
@@ -311,6 +336,40 @@ function buildTimelineElementKey(params: {
   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);
@@ -352,6 +411,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 +536,10 @@ export function buildStandaloneRootTimelineElement(params: {
 
   return {
     id: params.compositionId,
+    label: getTimelineElementDisplayLabel({
+      id: params.compositionId,
+      tag: params.tagName,
+    }),
     key: buildTimelineElementKey({
       id: params.compositionId,
       fallbackIndex: 0,
@@ -397,6 +557,7 @@ export function buildStandaloneRootTimelineElement(params: {
     sourceFile: compositionSrc,
   };
 }
+
 function normalizePreviewViewport(doc: Document, win: Window): void {
   if (doc.documentElement) {
     doc.documentElement.style.overflow = "hidden";
@@ -500,8 +661,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];
 }
@@ -743,7 +906,7 @@ export function useTimelinePlayer() {
     (deltaFrames: number) => {
       const adapter = getAdapter();
       const currentTime = adapter?.getTime() ?? usePlayerStore.getState().currentTime;
-      seek(currentTime + frameToSeconds(deltaFrames, STUDIO_PREVIEW_FPS));
+      seek(stepFrameTime(currentTime, deltaFrames, STUDIO_PREVIEW_FPS));
     },
     [getAdapter, seek],
   );
@@ -876,72 +1039,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 +1162,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,
@@ -1237,9 +1351,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;
@@ -1348,6 +1459,8 @@ export function useTimelinePlayer() {
       stopRAFLoop();
       stopReverseLoop();
       if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+      // Don't reset() on cleanup — preserve timeline elements across iframe refreshes
+      // to prevent blink. New data will replace old when the iframe reloads.
     };
   });
 

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { formatFrameTime, frameToSeconds, secondsToFrame, formatTime } from "./time";
+import { formatFrameTime, frameToSeconds, secondsToFrame, stepFrameTime, formatTime } from "./time";
 
 describe("formatTime", () => {
   it("formats zero seconds", () => {
@@ -72,4 +72,14 @@ describe("frame helpers", () => {
   it("formats current and total frame display", () => {
     expect(formatFrameTime(1, 5)).toBe("30f / 150f");
   });
+
+  it("steps from a truncated runtime time by integer frame index", () => {
+    expect(stepFrameTime(0.0333333, 1)).toBe(2 / 30);
+    expect(stepFrameTime(0.0666666, 1)).toBe(3 / 30);
+    expect(stepFrameTime(0.0666666, -1)).toBe(1 / 30);
+  });
+
+  it("clamps frame stepping at zero", () => {
+    expect(stepFrameTime(0, -1)).toBe(0);
+  });
 });

package/src/player/lib/time.ts

@@ -19,6 +19,12 @@ export function frameToSeconds(frame: number, fps = STUDIO_PREVIEW_FPS): number
   return frame / fps;
 }
 
+export function stepFrameTime(time: number, deltaFrames: number, fps = STUDIO_PREVIEW_FPS): number {
+  const currentFrame = secondsToFrame(time, fps);
+  const nextFrame = Math.max(0, currentFrame + deltaFrames);
+  return frameToSeconds(nextFrame, fps);
+}
+
 export function formatFrameTime(time: number, duration: number, fps = STUDIO_PREVIEW_FPS): string {
   const currentFrame = secondsToFrame(time, fps);
   const totalFrames = secondsToFrame(duration, fps);

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;

package/src/styles/studio.css

@@ -49,3 +49,115 @@ body {
 .cm-editor.cm-focused {
   outline: none;
 }
+
+/*
+ * HyperFrames brand loader. Shared by preview overlays that need a calm,
+ * branded loading state instead of a generic spinner.
+ */
+.hf-loader {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.75rem;
+  width: min(34rem, 100%);
+  padding: 1.5rem;
+  box-sizing: border-box;
+  text-align: center;
+  cursor: default;
+  user-select: none;
+  -webkit-user-select: none;
+  -webkit-user-drag: none;
+}
+
+.hf-frame {
+  display: grid;
+  place-items: center;
+  width: 100%;
+  height: 100%;
+  min-height: 12rem;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  background: rgba(0, 0, 0, 0.52);
+}
+
+.hf-loader-mark-frame {
+  display: grid;
+  place-items: center;
+  overflow: visible;
+  transform-origin: 50% 50%;
+  user-select: none;
+  -webkit-user-select: none;
+  -webkit-user-drag: none;
+}
+
+.hf-loader-mark {
+  display: block;
+  overflow: visible;
+  filter: drop-shadow(0 0 7px rgba(79, 219, 94, 0.2));
+  user-select: none;
+  -webkit-user-select: none;
+  -webkit-user-drag: none;
+}
+
+.hf-loader-title {
+  font-family:
+    Inter,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
+  font-size: 1rem;
+  font-weight: 600;
+  letter-spacing: 0;
+  color: var(--hf-heading, #f4f4f5);
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hf-loader-detail {
+  max-width: 32rem;
+  min-height: 2.5rem;
+  overflow: hidden;
+  color: var(--hf-text-secondary, rgba(244, 244, 245, 0.68));
+  font-family:
+    Inter,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
+  font-size: 0.82rem;
+  line-height: 1.6;
+}
+
+.hf-loader-mono {
+  width: min(36rem, 100%);
+  min-height: 1.5rem;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--hf-text-tertiary, rgba(244, 244, 245, 0.46));
+  font-family: "IBM Plex Mono", "SF Mono", "Fira Code", monospace;
+  font-size: 0.75rem;
+  letter-spacing: 0;
+  font-variant-numeric: tabular-nums;
+}
+
+.hf-loader-progress {
+  width: min(18rem, 72vw);
+  height: 0.375rem;
+  overflow: hidden;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.1);
+}
+
+.hf-loader-progress__fill {
+  width: 100%;
+  height: 100%;
+  transform: scaleX(0);
+  transform-origin: left center;
+  border-radius: inherit;
+  background: linear-gradient(90deg, #06e3fa, #4fdb5e);
+  transition: transform 160ms ease;
+}

package/src/utils/frameCapture.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildFrameCaptureFilename, buildFrameCaptureUrl } from "./frameCapture";
+
+describe("frame capture utilities", () => {
+  it("builds a PNG capture URL for the master composition", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-04-29T12:00:00Z"));
+
+    expect(
+      buildFrameCaptureUrl({
+        projectId: "demo project",
+        compositionPath: null,
+        currentTime: 1.23456,
+        origin: "http://localhost:5194",
+      }),
+    ).toBe(
+      "http://localhost:5194/api/projects/demo%20project/thumbnail/index.html?t=1.235&format=png&v=1777464000000",
+    );
+
+    vi.useRealTimers();
+  });
+
+  it("builds a safe filename from a nested composition path", () => {
+    expect(buildFrameCaptureFilename("compositions/intro.html", 2.5)).toBe("intro-2-500s.png");
+  });
+});

package/src/utils/frameCapture.ts

@@ -0,0 +1,40 @@
+import { buildProjectApiPath } from "./projectRouting";
+
+export interface FrameCaptureRequest {
+  projectId: string;
+  compositionPath: string | null;
+  currentTime: number;
+  origin?: string;
+}
+
+function normalizeCompositionPath(compositionPath: string | null): string {
+  return compositionPath && compositionPath !== "master" ? compositionPath : "index.html";
+}
+
+export function buildFrameCaptureUrl({
+  projectId,
+  compositionPath,
+  currentTime,
+  origin = window.location.origin,
+}: FrameCaptureRequest): string {
+  const compPath = normalizeCompositionPath(compositionPath);
+  const url = new URL(
+    buildProjectApiPath(projectId, `/thumbnail/${encodeURIComponent(compPath)}`),
+    origin,
+  );
+  url.searchParams.set("t", Math.max(0, currentTime).toFixed(3));
+  url.searchParams.set("format", "png");
+  url.searchParams.set("v", String(Date.now()));
+  return url.toString();
+}
+
+export function buildFrameCaptureFilename(compositionPath: string | null, currentTime: number) {
+  const compPath = normalizeCompositionPath(compositionPath);
+  const base =
+    compPath
+      .split("/")
+      .pop()
+      ?.replace(/\.html$/i, "") || "frame";
+  const frameTime = Math.max(0, currentTime).toFixed(3).replace(".", "-");
+  return `${base}-${frameTime}s.png`;
+}

package/src/utils/mediaTypes.ts

@@ -1,7 +1,7 @@
 export const IMAGE_EXT = /\.(jpg|jpeg|png|gif|webp|svg|ico)$/i;
 export const VIDEO_EXT = /\.(mp4|webm|mov)$/i;
 export const AUDIO_EXT = /\.(mp3|wav|ogg|m4a|aac)$/i;
-export const FONT_EXT = /\.(woff|woff2|ttf|ttc|otf|eot)$/i;
+export const FONT_EXT = /\.(woff|woff2|ttf|otf|eot)$/i;
 export const MEDIA_EXT = /\.(mp4|webm|mov|mp3|wav|ogg|m4a|aac|jpg|jpeg|png|gif|webp|svg|ico)$/i;
 
 export function isMediaFile(path: string): boolean {