@hyperframes/studio 0.6.26 → 0.6.28

package/src/hooks/useTimelineEditing.ts

@@ -38,6 +38,8 @@ interface UseTimelineEditingOptions {
   recordEdit: (input: RecordEditInput) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   reloadPreview: () => void;
+  previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
+  pendingTimelineEditPathRef: React.MutableRefObject<Set<string>>;
   uploadProjectFiles: (files: Iterable<File>, dir?: string) => Promise<string[]>;
 }
 
@@ -53,6 +55,97 @@ function buildPatchTarget(element: { domId?: string; selector?: string; selector
   return null;
 }
 
+// The runtime re-reads data-start/data-duration from the DOM on each sync tick
+// (packages/core/src/runtime/init.ts:1324-1368), so attribute mutations here are
+// picked up automatically on the next frame without a rebind call.
+function patchIframeDomTiming(
+  iframe: HTMLIFrameElement | null,
+  element: TimelineElement,
+  attrs: Array<[string, string]>,
+): void {
+  try {
+    const doc = iframe?.contentDocument;
+    if (!doc) return;
+    const el = element.domId
+      ? doc.getElementById(element.domId)
+      : element.selector
+        ? (doc.querySelectorAll(element.selector)[element.selectorIndex ?? 0] ?? null)
+        : null;
+    if (!el) return;
+    for (const [name, value] of attrs) el.setAttribute(name, value);
+  } catch {
+    // Cross-origin or mid-navigation — file save is enqueued; iframe patch is best-effort.
+  }
+}
+
+function resolveResizePlaybackStart(
+  original: string,
+  target: PatchTarget,
+  element: TimelineElement,
+  updates: Pick<TimelineElement, "start" | "playbackStart">,
+): { attrName: string; value: number } | null {
+  if (updates.playbackStart != null) {
+    const attrName =
+      element.playbackStartAttr === "playback-start" ? "playback-start" : "media-start";
+    return { attrName, value: updates.playbackStart };
+  }
+  const trimDelta = updates.start - element.start;
+  if (trimDelta === 0) return null;
+  const raw =
+    readAttributeByTarget(original, target, "playback-start") ??
+    readAttributeByTarget(original, target, "media-start");
+  const current = raw != null ? parseFloat(raw) : undefined;
+  if (current == null || !Number.isFinite(current)) return null;
+  const attrName =
+    element.playbackStartAttr === "playback-start" ? "playback-start" : "media-start";
+  return {
+    attrName,
+    value: Math.max(0, current + trimDelta * Math.max(element.playbackRate ?? 1, 0.1)),
+  };
+}
+
+type PatchTarget = NonNullable<ReturnType<typeof buildPatchTarget>>;
+
+interface PersistTimelineEditInput {
+  projectId: string;
+  element: TimelineElement;
+  activeCompPath: string | null;
+  label: string;
+  buildPatches: (original: string, target: PatchTarget) => string;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  domEditSaveTimestampRef: React.MutableRefObject<number>;
+  pendingTimelineEditPathRef: React.MutableRefObject<Set<string>>;
+}
+
+async function persistTimelineEdit(input: PersistTimelineEditInput): Promise<void> {
+  const targetPath = input.element.sourceFile || input.activeCompPath || "index.html";
+  const originalContent = await readFileContent(input.projectId, targetPath);
+
+  const patchTarget = buildPatchTarget(input.element);
+  if (!patchTarget) {
+    throw new Error(`Timeline element ${input.element.id} is missing a patchable target`);
+  }
+
+  const patchedContent = input.buildPatches(originalContent, patchTarget);
+  if (patchedContent === originalContent) {
+    throw new Error(`Unable to patch timeline element ${input.element.id} in ${targetPath}`);
+  }
+
+  input.pendingTimelineEditPathRef.current.add(targetPath);
+  input.domEditSaveTimestampRef.current = Date.now();
+  await saveProjectFilesWithHistory({
+    projectId: input.projectId,
+    label: input.label,
+    kind: "timeline",
+    files: { [targetPath]: patchedContent },
+    readFile: async () => originalContent,
+    writeFile: input.writeProjectFile,
+    recordEdit: input.recordEdit,
+  });
+  input.domEditSaveTimestampRef.current = Date.now();
+}
+
 async function readFileContent(projectId: string, targetPath: string): Promise<string> {
   const response = await fetch(
     `/api/projects/${projectId}/files/${encodeURIComponent(targetPath)}`,
@@ -78,127 +171,105 @@ export function useTimelineEditing({
   recordEdit,
   domEditSaveTimestampRef,
   reloadPreview,
+  previewIframeRef,
+  pendingTimelineEditPathRef,
   uploadProjectFiles,
 }: UseTimelineEditingOptions) {
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
 
+  const editQueueRef = useRef(Promise.resolve());
   const lastBlockedTimelineToastAtRef = useRef(0);
 
-  const handleTimelineElementMove = useCallback(
-    async (element: TimelineElement, updates: Pick<TimelineElement, "start" | "track">) => {
+  const enqueueEdit = useCallback(
+    (
+      element: TimelineElement,
+      label: string,
+      buildPatches: PersistTimelineEditInput["buildPatches"],
+    ): Promise<void> => {
       const pid = projectIdRef.current;
-      if (!pid) throw new Error("No active project");
-
-      const targetPath = element.sourceFile || activeCompPath || "index.html";
-      const originalContent = await readFileContent(pid, targetPath);
-
-      const patchTarget = buildPatchTarget(element);
-      if (!patchTarget) {
-        throw new Error(`Timeline element ${element.id} is missing a patchable target`);
-      }
-
-      let patchedContent = applyPatchByTarget(originalContent, patchTarget, {
-        type: "attribute",
-        property: "start",
-        value: formatTimelineAttributeNumber(updates.start),
-      });
-      patchedContent = applyPatchByTarget(patchedContent, patchTarget, {
-        type: "attribute",
-        property: "track-index",
-        value: String(updates.track),
+      if (!pid) return Promise.resolve();
+      const queued = editQueueRef.current.then(() =>
+        persistTimelineEdit({
+          projectId: pid,
+          element,
+          activeCompPath,
+          label,
+          buildPatches,
+          writeProjectFile,
+          recordEdit,
+          domEditSaveTimestampRef,
+          pendingTimelineEditPathRef,
+        }),
+      );
+      editQueueRef.current = queued.catch((error) => {
+        console.error(`[Timeline] Failed to persist: ${label}`, error);
       });
+      return queued;
+    },
+    [
+      activeCompPath,
+      recordEdit,
+      writeProjectFile,
+      domEditSaveTimestampRef,
+      pendingTimelineEditPathRef,
+    ],
+  );
 
-      if (patchedContent === originalContent) {
-        throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
-      }
-
-      domEditSaveTimestampRef.current = Date.now();
-      await saveProjectFilesWithHistory({
-        projectId: pid,
-        label: "Move timeline clip",
-        kind: "timeline",
-        files: { [targetPath]: patchedContent },
-        readFile: async () => originalContent,
-        writeFile: writeProjectFile,
-        recordEdit,
+  const handleTimelineElementMove = useCallback(
+    (element: TimelineElement, updates: Pick<TimelineElement, "start" | "track">) => {
+      patchIframeDomTiming(previewIframeRef.current, element, [
+        ["data-start", formatTimelineAttributeNumber(updates.start)],
+        ["data-track-index", String(updates.track)],
+      ]);
+      return enqueueEdit(element, "Move timeline clip", (original, target) => {
+        let patched = applyPatchByTarget(original, target, {
+          type: "attribute",
+          property: "start",
+          value: formatTimelineAttributeNumber(updates.start),
+        });
+        return applyPatchByTarget(patched, target, {
+          type: "attribute",
+          property: "track-index",
+          value: String(updates.track),
+        });
       });
-
-      reloadPreview();
     },
-    [activeCompPath, recordEdit, writeProjectFile, domEditSaveTimestampRef, reloadPreview],
+    [previewIframeRef, enqueueEdit],
   );
 
   const handleTimelineElementResize = useCallback(
-    async (
+    (
       element: TimelineElement,
       updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
     ) => {
-      const pid = projectIdRef.current;
-      if (!pid) throw new Error("No active project");
-
-      const targetPath = element.sourceFile || activeCompPath || "index.html";
-      const originalContent = await readFileContent(pid, targetPath);
-
-      const patchTarget = buildPatchTarget(element);
-      if (!patchTarget) {
-        throw new Error(`Timeline element ${element.id} is missing a patchable target`);
-      }
-
-      const playbackStartAttrName =
-        element.playbackStartAttr === "playback-start" ? "playback-start" : "media-start";
-      const currentPlaybackStartValue =
-        readAttributeByTarget(originalContent, patchTarget, "playback-start") ??
-        readAttributeByTarget(originalContent, patchTarget, "media-start");
-      const currentPlaybackStart =
-        currentPlaybackStartValue != null ? parseFloat(currentPlaybackStartValue) : undefined;
-      const trimDelta = updates.start - element.start;
-      const fallbackPlaybackStart =
-        updates.playbackStart == null &&
-        trimDelta !== 0 &&
-        Number.isFinite(currentPlaybackStart) &&
-        currentPlaybackStart != null
-          ? Math.max(0, currentPlaybackStart + trimDelta * Math.max(element.playbackRate ?? 1, 0.1))
-          : undefined;
-      const nextPlaybackStart = updates.playbackStart ?? fallbackPlaybackStart;
-
-      let patchedContent = originalContent;
-      patchedContent = applyPatchByTarget(patchedContent, patchTarget, {
-        type: "attribute",
-        property: "start",
-        value: formatTimelineAttributeNumber(updates.start),
-      });
-      patchedContent = applyPatchByTarget(patchedContent, patchTarget, {
-        type: "attribute",
-        property: "duration",
-        value: formatTimelineAttributeNumber(updates.duration),
-      });
-      if (nextPlaybackStart != null) {
-        patchedContent = applyPatchByTarget(patchedContent, patchTarget, {
+      patchIframeDomTiming(previewIframeRef.current, element, [
+        ["data-start", formatTimelineAttributeNumber(updates.start)],
+        ["data-duration", formatTimelineAttributeNumber(updates.duration)],
+      ]);
+      return enqueueEdit(element, "Resize timeline clip", (original, target) => {
+        const pbs = resolveResizePlaybackStart(original, target, element, updates);
+        let patched = applyPatchByTarget(original, target, {
           type: "attribute",
-          property: playbackStartAttrName,
-          value: formatTimelineAttributeNumber(nextPlaybackStart),
+          property: "start",
+          value: formatTimelineAttributeNumber(updates.start),
         });
-      }
-
-      if (patchedContent === originalContent) {
-        throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
-      }
-
-      domEditSaveTimestampRef.current = Date.now();
-      await saveProjectFilesWithHistory({
-        projectId: pid,
-        label: "Resize timeline clip",
-        kind: "timeline",
-        files: { [targetPath]: patchedContent },
-        readFile: async () => originalContent,
-        writeFile: writeProjectFile,
-        recordEdit,
+        patched = applyPatchByTarget(patched, target, {
+          type: "attribute",
+          property: "duration",
+          value: formatTimelineAttributeNumber(updates.duration),
+        });
+        if (pbs) {
+          patched = applyPatchByTarget(patched, target, {
+            type: "attribute",
+            property: pbs.attrName,
+            value: formatTimelineAttributeNumber(pbs.value),
+          });
+        }
+        return patched;
       });
-
-      reloadPreview();
     },
-    [activeCompPath, recordEdit, writeProjectFile, domEditSaveTimestampRef, reloadPreview],
+    [previewIframeRef, enqueueEdit],
   );
 
   const handleTimelineElementDelete = useCallback(

package/src/player/components/TimelineCanvas.tsx

@@ -252,6 +252,7 @@ export const TimelineCanvas = memo(function TimelineCanvas({
                     isHovered={hoveredClip === clipKey}
                     isDragging={false}
                     hasCustomContent={!!renderClipContent}
+                    capabilities={capabilities}
                     theme={theme}
                     trackStyle={clipStyle}
                     isComposition={isComposition}
@@ -369,6 +370,7 @@ export const TimelineCanvas = memo(function TimelineCanvas({
             isHovered={false}
             isDragging={true}
             hasCustomContent={!!renderClipContent}
+            capabilities={getTimelineEditCapabilities(activeDraggedElement)}
             theme={theme}
             trackStyle={getTrackStyle(activeDraggedElement.tag)}
             isComposition={!!activeDraggedElement.compositionSrc}

package/src/player/components/TimelineClip.tsx

@@ -3,7 +3,7 @@ import type { TimelineTrackStyle } from "./timelineTheme";
 import { memo, type ReactNode } from "react";
 import type { TimelineElement } from "../store/playerStore";
 import { defaultTimelineTheme, getClipHandleOpacity, type TimelineTheme } from "./timelineTheme";
-import { getTimelineEditCapabilities } from "./timelineEditing";
+import type { TimelineEditCapabilities } from "./timelineEditing";
 
 interface TimelineClipProps {
   el: TimelineElement;
@@ -13,6 +13,7 @@ interface TimelineClipProps {
   isHovered: boolean;
   isDragging?: boolean;
   hasCustomContent: boolean;
+  capabilities: TimelineEditCapabilities;
   theme?: TimelineTheme;
   trackStyle: TimelineTrackStyle;
   isComposition: boolean;
@@ -33,6 +34,7 @@ export const TimelineClip = memo(function TimelineClip({
   isHovered,
   isDragging = false,
   hasCustomContent,
+  capabilities,
   theme = defaultTimelineTheme,
   trackStyle,
   isComposition,
@@ -47,6 +49,7 @@ export const TimelineClip = memo(function TimelineClip({
   const leftPx = el.start * pps;
   const widthPx = Math.max(el.duration * pps, 4);
   const handleOpacity = getClipHandleOpacity({ isHovered, isSelected, isDragging });
+
   const borderColor = isSelected
     ? theme.clipBorderActive
     : isHovered
@@ -59,7 +62,6 @@ export const TimelineClip = memo(function TimelineClip({
       : isHovered
         ? theme.clipShadowHover
         : theme.clipShadow;
-  const capabilities = getTimelineEditCapabilities(el);
   const displayLabel = el.label || el.id || el.tag;
   const showHandles = handleOpacity > 0.01;
 

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

@@ -4,7 +4,6 @@ import {
   buildPromptCopyText,
   buildTimelineElementAgentPrompt,
   buildTimelineAgentPrompt,
-  canOffsetTrimClipStart,
   getTimelineEditCapabilities,
   hasPatchableTimelineTarget,
   resolveBlockedTimelineEditIntent,
@@ -158,42 +157,6 @@ describe("resolveTimelineMove", () => {
   });
 });
 
-describe("canOffsetTrimClipStart", () => {
-  it("allows front trim for clips that carry playback offset metadata", () => {
-    expect(
-      canOffsetTrimClipStart({
-        tag: "div",
-        playbackStartAttr: "media-start",
-      }),
-    ).toBe(true);
-  });
-
-  it("allows front trim for media clips with source duration metadata", () => {
-    expect(
-      canOffsetTrimClipStart({
-        tag: "video",
-        sourceDuration: 12,
-      }),
-    ).toBe(true);
-  });
-
-  it("allows front trim for plain audio clips even before media-start exists", () => {
-    expect(
-      canOffsetTrimClipStart({
-        tag: "audio",
-      }),
-    ).toBe(true);
-  });
-
-  it("blocks front trim for generic motion clips", () => {
-    expect(
-      canOffsetTrimClipStart({
-        tag: "section",
-      }),
-    ).toBe(false);
-  });
-});
-
 describe("hasPatchableTimelineTarget", () => {
   it("returns true when the clip has a DOM id", () => {
     expect(hasPatchableTimelineTarget({ domId: "hero-card" })).toBe(true);
@@ -224,7 +187,7 @@ describe("getTimelineEditCapabilities", () => {
     });
   });
 
-  it("allows moving generic motion clips while keeping trims blocked", () => {
+  it("allows full editing of generic motion clips with authored timing", () => {
     expect(
       getTimelineEditCapabilities({
         tag: "section",
@@ -233,8 +196,8 @@ describe("getTimelineEditCapabilities", () => {
       }),
     ).toEqual({
       canMove: true,
-      canTrimStart: false,
-      canTrimEnd: false,
+      canTrimStart: true,
+      canTrimEnd: true,
     });
   });
 
@@ -285,7 +248,7 @@ describe("getTimelineEditCapabilities", () => {
     });
   });
 
-  it("allows move and end trim for patchable composition hosts", () => {
+  it("allows full editing for patchable composition hosts", () => {
     expect(
       getTimelineEditCapabilities({
         tag: "div",
@@ -295,7 +258,22 @@ describe("getTimelineEditCapabilities", () => {
       }),
     ).toEqual({
       canMove: true,
-      canTrimStart: false,
+      canTrimStart: true,
+      canTrimEnd: true,
+    });
+  });
+
+  it("allows full editing of explicitly authored generic elements", () => {
+    expect(
+      getTimelineEditCapabilities({
+        tag: "div",
+        duration: 4,
+        selector: "#hero-card",
+        timingSource: "authored",
+      }),
+    ).toEqual({
+      canMove: true,
+      canTrimStart: true,
       canTrimEnd: true,
     });
   });
@@ -576,6 +554,40 @@ describe("resolveTimelineResize", () => {
       ),
     ).toEqual({ start: 0.8, duration: 3.2, playbackStart: 0 });
   });
+
+  it("trims generic element start without media offset", () => {
+    expect(
+      resolveTimelineResize(
+        {
+          start: 2,
+          duration: 4,
+          originClientX: 100,
+          pixelsPerSecond: 100,
+          minStart: 0,
+          maxEnd: 10,
+        },
+        "start",
+        200,
+      ),
+    ).toEqual({ start: 3, duration: 3, playbackStart: undefined });
+  });
+
+  it("extends generic element start leftward to time zero", () => {
+    expect(
+      resolveTimelineResize(
+        {
+          start: 1,
+          duration: 3,
+          originClientX: 100,
+          pixelsPerSecond: 100,
+          minStart: 0,
+          maxEnd: 10,
+        },
+        "start",
+        -200,
+      ),
+    ).toEqual({ start: 0, duration: 4, playbackStart: undefined });
+  });
 });
 
 describe("buildPromptCopyText", () => {

package/src/player/components/timelineEditing.ts

@@ -201,18 +201,6 @@ export function hasPatchableTimelineTarget(input: { domId?: string; selector?: s
   return Boolean(input.domId || input.selector);
 }
 
-export function canOffsetTrimClipStart(input: {
-  tag: string;
-  playbackStart?: number;
-  playbackStartAttr?: "media-start" | "playback-start";
-  sourceDuration?: number;
-}): boolean {
-  if (input.playbackStartAttr != null) return true;
-  if (input.playbackStart != null) return true;
-  const normalizedTag = input.tag.toLowerCase();
-  return ["video", "audio"].includes(normalizedTag);
-}
-
 export function getTimelineEditCapabilities(input: {
   tag: string;
   duration: number;
@@ -237,8 +225,8 @@ export function getTimelineEditCapabilities(input: {
   const hasDeterministicWindow = isDeterministicTimelineWindow(input);
   return {
     canMove: canPatch && (hasDeterministicWindow || hasFiniteDuration),
-    canTrimEnd: canPatch && hasFiniteDuration && hasDeterministicWindow,
-    canTrimStart: canPatch && hasFiniteDuration && canOffsetTrimClipStart(input),
+    canTrimEnd: canPatch && hasFiniteDuration,
+    canTrimStart: canPatch && hasFiniteDuration,
   };
 }
 

package/src/player/hooks/useTimelinePlayer.ts

@@ -7,7 +7,7 @@ import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
 // Re-export public API consumed by tests and external modules.
 // All of these were previously defined in this file; they now live in focused
 // sub-modules but are re-exported here so existing import sites don't change.
-export type { PlaybackAdapter, ClipManifestClip } from "../lib/playbackTypes";
+export type { ClipManifestClip } from "../lib/playbackTypes";
 export { createStaticSeekPlaybackAdapter } from "../lib/playbackAdapter";
 export {
   getTimelineElementSelector,
@@ -42,6 +42,7 @@ import {
   setPreviewPlaybackRate,
   shouldMutePreviewAudio,
 } from "../lib/timelineIframeHelpers";
+import { probeMediaUrl, getCachedProbe } from "../lib/mediaProbe";
 
 // ---------------------------------------------------------------------------
 // Hook
@@ -106,6 +107,32 @@ export function useTimelinePlayer() {
       if (!state.timelineReady) {
         setTimelineReady(true);
       }
+
+      // Asynchronously enrich media elements missing sourceDuration via mediabunny.
+      // The probe reads file headers only — no full decode — so this is cheap.
+      const needsProbe = mergedElements.filter(
+        (el) =>
+          el.src &&
+          el.sourceDuration == null &&
+          ["video", "audio"].includes(el.tag.toLowerCase()) &&
+          !getCachedProbe(el.src),
+      );
+      if (needsProbe.length > 0) {
+        void Promise.allSettled(
+          needsProbe.map(async (el) => {
+            const result = await probeMediaUrl(el.src!);
+            if (!result) return;
+            const key = el.key ?? el.id;
+            usePlayerStore.setState((state) => {
+              const idx = state.elements.findIndex((e) => (e.key ?? e.id) === key);
+              if (idx === -1 || state.elements[idx].sourceDuration != null) return {};
+              const patched = state.elements.slice();
+              patched[idx] = { ...state.elements[idx], sourceDuration: result.duration };
+              return { elements: patched };
+            });
+          }),
+        );
+      }
     },
     [setElements, setTimelineReady, setDuration],
   );

package/src/player/lib/mediaProbe.ts

@@ -0,0 +1,68 @@
+import { Input, UrlSource, ALL_FORMATS } from "mediabunny";
+
+export interface MediaProbeResult {
+  duration: number;
+  width?: number;
+  height?: number;
+  hasVideo: boolean;
+  hasAudio: boolean;
+}
+
+const cache = new Map<string, MediaProbeResult>();
+const inflight = new Map<string, Promise<MediaProbeResult | null>>();
+
+function normalizeUrl(url: string): string {
+  try {
+    return new URL(url, window.location.href).href;
+  } catch {
+    return url;
+  }
+}
+
+async function probeOne(url: string): Promise<MediaProbeResult | null> {
+  const input = new Input({
+    source: new UrlSource(url),
+    formats: ALL_FORMATS,
+  });
+  try {
+    const duration = await input.getDurationFromMetadata();
+    if (duration == null || !Number.isFinite(duration) || duration <= 0) return null;
+
+    const videoTrack = await input.getPrimaryVideoTrack();
+    const audioTracks = await input.getAudioTracks();
+
+    const result: MediaProbeResult = {
+      duration,
+      width: videoTrack?.displayWidth,
+      height: videoTrack?.displayHeight,
+      hasVideo: videoTrack != null,
+      hasAudio: audioTracks.length > 0,
+    };
+    return result;
+  } catch {
+    return null;
+  } finally {
+    input.dispose();
+  }
+}
+
+export function getCachedProbe(url: string): MediaProbeResult | undefined {
+  return cache.get(normalizeUrl(url));
+}
+
+export async function probeMediaUrl(url: string): Promise<MediaProbeResult | null> {
+  const key = normalizeUrl(url);
+  const cached = cache.get(key);
+  if (cached) return cached;
+
+  let pending = inflight.get(key);
+  if (pending) return pending;
+
+  pending = probeOne(key).then((result) => {
+    inflight.delete(key);
+    if (result) cache.set(key, result);
+    return result;
+  });
+  inflight.set(key, pending);
+  return pending;
+}