@hyperframes/studio 0.5.0-alpha.10 → 0.5.0-alpha.12

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 {
@@ -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];
 }
@@ -743,7 +904,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 +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/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/utils/editHistory.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildEditHistoryEntry,
+  canApplyEditHistoryEntry,
+  createEmptyEditHistory,
+  hashEditHistoryContent,
+  pushEditHistoryEntry,
+  redoEditHistory,
+  undoEditHistory,
+} from "./editHistory";
+
+describe("edit history", () => {
+  it("pushes changed file snapshots onto undo and clears redo", () => {
+    const state = createEmptyEditHistory();
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": {
+          before: '<div style="left: 0px"></div>',
+          after: '<div style="left: 20px"></div>',
+        },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+
+    const withUndo = pushEditHistoryEntry(state, entry);
+    const redoEntry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Redoable edit",
+      files: {
+        "index.html": {
+          before: '<div style="left: 20px"></div>',
+          after: '<div style="left: 40px"></div>',
+        },
+      },
+      now: 200,
+      id: "redo-entry",
+    });
+
+    const next = pushEditHistoryEntry(
+      {
+        ...withUndo,
+        redo: [redoEntry],
+      },
+      {
+        ...entry,
+        id: "entry-2",
+        label: "Resize layer",
+        createdAt: 300,
+      },
+    );
+
+    expect(withUndo.undo).toHaveLength(1);
+    expect(withUndo.redo).toHaveLength(0);
+    expect(next.undo.map((item) => item.label)).toEqual(["Move layer", "Resize layer"]);
+    expect(next.redo).toHaveLength(0);
+  });
+
+  it("undo returns before contents and moves entry to redo", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": { before: "before", after: "after" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const state = pushEditHistoryEntry(createEmptyEditHistory(), entry);
+
+    const result = undoEditHistory(state, { "index.html": hashEditHistoryContent("after") }, 200);
+
+    expect(result.ok).toBe(true);
+    expect(result.filesToWrite).toEqual({ "index.html": "before" });
+    expect(result.state.undo).toHaveLength(0);
+    expect(result.state.redo.map((item) => item.id)).toEqual(["entry-1"]);
+  });
+
+  it("redo returns after contents and moves entry to undo", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": { before: "before", after: "after" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const undone = undoEditHistory(
+      pushEditHistoryEntry(createEmptyEditHistory(), entry),
+      { "index.html": hashEditHistoryContent("after") },
+      200,
+    ).state;
+
+    const result = redoEditHistory(undone, { "index.html": hashEditHistoryContent("before") }, 300);
+
+    expect(result.ok).toBe(true);
+    expect(result.filesToWrite).toEqual({ "index.html": "after" });
+    expect(result.state.undo.map((item) => item.id)).toEqual(["entry-1"]);
+    expect(result.state.redo).toHaveLength(0);
+  });
+
+  it("blocks undo when current content hash does not match the recorded after hash", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": { before: "before", after: "after" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const state = pushEditHistoryEntry(createEmptyEditHistory(), entry);
+
+    const result = undoEditHistory(
+      state,
+      { "index.html": hashEditHistoryContent("external") },
+      200,
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.reason).toBe("content-mismatch");
+    expect(result.state).toBe(state);
+    expect(result.filesToWrite).toEqual({});
+  });
+
+  it("can validate all files in a multi-file entry before applying", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Update files",
+      files: {
+        "index.html": { before: "a", after: "b" },
+        "compositions/title.html": { before: "c", after: "d" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+
+    expect(
+      canApplyEditHistoryEntry(entry, "undo", {
+        "index.html": hashEditHistoryContent("b"),
+        "compositions/title.html": hashEditHistoryContent("d"),
+      }),
+    ).toEqual({ ok: true });
+    expect(
+      canApplyEditHistoryEntry(entry, "undo", {
+        "index.html": hashEditHistoryContent("b"),
+        "compositions/title.html": hashEditHistoryContent("external"),
+      }),
+    ).toEqual({ ok: false, reason: "content-mismatch", path: "compositions/title.html" });
+  });
+
+  it("prunes oldest undo entries when the limit is exceeded", () => {
+    let state = createEmptyEditHistory({ maxEntries: 2 });
+    for (let index = 1; index <= 3; index += 1) {
+      state = pushEditHistoryEntry(
+        state,
+        buildEditHistoryEntry({
+          projectId: "project-1",
+          label: `Edit ${index}`,
+          files: {
+            "index.html": { before: `${index - 1}`, after: `${index}` },
+          },
+          now: index,
+          id: `entry-${index}`,
+        }),
+        { maxEntries: 2 },
+      );
+    }
+
+    expect(state.undo.map((entry) => entry.id)).toEqual(["entry-2", "entry-3"]);
+  });
+
+  it("coalesces source editor edits for the same file inside the coalesce window", () => {
+    const first = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "a", after: "b" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const second = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "b", after: "c" },
+      },
+      now: 300,
+      id: "entry-2",
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), first),
+      second,
+      { coalesceMs: 1000 },
+    );
+
+    expect(state.undo).toHaveLength(1);
+    expect(state.undo[0].id).toBe("entry-2");
+    expect(state.undo[0].files["index.html"].before).toBe("a");
+    expect(state.undo[0].files["index.html"].after).toBe("c");
+  });
+
+  it("does not coalesce source editor edits outside the coalesce window", () => {
+    const first = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "a", after: "b" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const second = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "b", after: "c" },
+      },
+      now: 5000,
+      id: "entry-2",
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), first),
+      second,
+      { coalesceMs: 1000 },
+    );
+
+    expect(state.undo.map((entry) => entry.id)).toEqual(["entry-1", "entry-2"]);
+  });
+});