@hyperframes/studio 0.6.97 → 0.6.99

package/src/hooks/useGsapTweenCache.ts

@@ -3,6 +3,7 @@ import type { GsapAnimation, GsapKeyframesData, ParsedGsap } from "@hyperframes/
 import type { GsapPercentageKeyframe } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore } from "../player/store/playerStore";
 import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeBridge";
+import { PROPERTY_DEFAULTS, toAbsoluteTime } from "./gsapShared";
 
 function deduplicateKeyframes(keyframes: GsapPercentageKeyframe[]): GsapPercentageKeyframe[] {
   const byPct = new Map<number, GsapPercentageKeyframe>();
@@ -18,16 +19,6 @@ function deduplicateKeyframes(keyframes: GsapPercentageKeyframe[]): GsapPercenta
   return Array.from(byPct.values()).sort((a, b) => a.percentage - b.percentage);
 }
 
-const PROPERTY_DEFAULTS: Record<string, number> = {
-  opacity: 1,
-  x: 0,
-  y: 0,
-  scale: 1,
-  scaleX: 1,
-  scaleY: 1,
-  rotation: 0,
-};
-
 function synthesizeFlatTweenKeyframes(anim: GsapAnimation): GsapKeyframesData | null {
   if (anim.method === "set") {
     return {
@@ -133,12 +124,18 @@ export function useGsapAnimationsForElement(
   const [multipleTimelines, setMultipleTimelines] = useState(false);
   const [unsupportedTimelinePattern, setUnsupportedTimelinePattern] = useState(false);
   const lastFetchKeyRef = useRef("");
+  const retryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   useEffect(() => {
     const fetchKey = `${projectId}:${sourceFile}:${version}`;
     if (fetchKey === lastFetchKeyRef.current) return;
     lastFetchKeyRef.current = fetchKey;
 
+    if (retryTimerRef.current) {
+      clearTimeout(retryTimerRef.current);
+      retryTimerRef.current = null;
+    }
+
     if (!projectId) {
       setAllAnimations([]);
       setMultipleTimelines(false);
@@ -158,26 +155,30 @@ export function useGsapAnimationsForElement(
       setAllAnimations(parsed.animations);
       setMultipleTimelines(parsed.multipleTimelines === true);
       setUnsupportedTimelinePattern(parsed.unsupportedTimelinePattern === true);
+
+      // Retry once if initial fetch returned 0 animations — handles
+      // cold-load race where the sourceFile isn't resolved yet.
+      if (parsed.animations.length === 0 && target) {
+        retryTimerRef.current = setTimeout(() => {
+          if (cancelled) return;
+          fetchParsedAnimations(projectId, sourceFile).then((retryParsed) => {
+            if (cancelled) return;
+            if (retryParsed && retryParsed.animations.length > 0) {
+              setAllAnimations(retryParsed.animations);
+            }
+          });
+        }, 800);
+      }
     });
 
     return () => {
       cancelled = true;
+      if (retryTimerRef.current) {
+        clearTimeout(retryTimerRef.current);
+        retryTimerRef.current = null;
+      }
     };
-  }, [projectId, sourceFile, version]);
-
-  // Retry fetch if we have a target but no animations — handles cold-load race
-  // where the initial fetch runs before the drilled-down sourceFile is resolved
-  useEffect(() => {
-    if (!projectId || !target || allAnimations.length > 0) return;
-    const timer = setTimeout(() => {
-      fetchParsedAnimations(projectId, sourceFile).then((parsed) => {
-        if (parsed && parsed.animations.length > 0) {
-          setAllAnimations(parsed.animations);
-        }
-      });
-    }, 800);
-    return () => clearTimeout(timer);
-  }, [projectId, sourceFile, target, allAnimations.length]);
+  }, [projectId, sourceFile, version, target]);
 
   const targetId = target?.id ?? null;
   const targetSelector = target?.selector ?? null;
@@ -281,10 +282,12 @@ export function useGsapAnimationsForElement(
         anim.resolvedStart ?? (typeof anim.position === "number" ? anim.position : 0);
       const tweenDur = anim.duration ?? elDuration;
       for (const k of kf.keyframes) {
-        const absTime = tweenPos + (k.percentage / 100) * tweenDur;
+        const absTime = toAbsoluteTime(tweenPos, tweenDur, k.percentage);
+        // 0.001% precision (was 0.1%) so a beat-snapped keyframe centers exactly
+        // on the beat dot, which is rendered at the true beat time.
         const clipPct =
           elDuration > 0
-            ? Math.round(((absTime - elStart) / elDuration) * 1000) / 10
+            ? Math.round(((absTime - elStart) / elDuration) * 100000) / 1000
             : k.percentage;
         allKeyframes.push({
           ...k,
@@ -379,10 +382,13 @@ export function usePopulateKeyframeCacheForFile(
         const elStart = timelineEl?.start ?? 0;
         const elDuration = timelineEl?.duration ?? 1;
         const clipKeyframes = kfData.keyframes.map((kf) => {
-          const absTime = tweenPos + (kf.percentage / 100) * tweenDur;
+          const absTime = toAbsoluteTime(tweenPos, tweenDur, kf.percentage);
+          // 0.001% precision (matching useGsapAnimationsForElement above) so a
+          // beat-snapped keyframe centers exactly on the beat dot and the two
+          // caches agree on a keyframe's percentage.
           const clipPct =
             elDuration > 0
-              ? Math.round(((absTime - elStart) / elDuration) * 1000) / 10
+              ? Math.round(((absTime - elStart) / elDuration) * 100000) / 1000
               : kf.percentage;
           return {
             ...kf,

package/src/hooks/useLintModal.ts

@@ -1,5 +1,6 @@
 import { useState, useCallback, useEffect, useRef, useMemo } from "react";
 import type { LintFinding } from "../components/LintModal";
+import { usePlayerStore } from "../player";
 
 interface RawFinding {
   severity?: string;
@@ -95,6 +96,12 @@ export function useLintModal(projectId: string | null, refreshKey?: number) {
   const findingsByElement = useMemo(() => groupFindings((f) => f.elementId), [groupFindings]);
   const findingsByFile = useMemo(() => groupFindings((f) => f.file), [groupFindings]);
 
+  // Sync lint findings directly to the player store — eliminates the
+  // mirroring useEffect that was previously in App.tsx.
+  useEffect(() => {
+    usePlayerStore.getState().setLintFindingsByElement(findingsByElement);
+  }, [findingsByElement]);
+
   return {
     lintModal,
     linting,

package/src/hooks/useMusicBeatAnalysis.ts

@@ -0,0 +1,152 @@
+import { useEffect, useMemo, useRef } from "react";
+import { usePlayerStore } from "../player/store/playerStore";
+import { isMusicTrack } from "../utils/timelineInspector";
+import { analyzeMusicFromUrl } from "@hyperframes/core/beats";
+import { useFileManagerContext } from "../contexts/FileManagerContext";
+import { mergeUserBeats } from "../utils/beatEditing";
+import {
+  audioRelPathForSrc,
+  beatFilePathForSrc,
+  serializeBeats,
+  parseBeats,
+} from "@hyperframes/core/beats";
+
+// Module-level cache so the same URL isn't re-decoded/analyzed on re-mount.
+// Capped so decoded PCM buffers don't accumulate unbounded across a session.
+const analysisCache = new Map<string, ReturnType<typeof analyzeMusicFromUrl>>();
+const MAX_ANALYSIS_CACHE = 4;
+
+const PERSIST_DEBOUNCE_MS = 350;
+
+function cacheAnalysis(url: string, promise: ReturnType<typeof analyzeMusicFromUrl>): void {
+  analysisCache.set(url, promise);
+  while (analysisCache.size > MAX_ANALYSIS_CACHE) {
+    const oldest = analysisCache.keys().next().value;
+    if (oldest === undefined) break;
+    analysisCache.delete(oldest);
+  }
+}
+
+type ProjectIo = { readOptionalProjectFile: (p: string) => Promise<string> };
+
+/**
+ * Resolve the effective beat list for a track: a saved file with real beats
+ * wins; otherwise the detected beats are used (and `hasFile` is false so the
+ * caller seeds a new file). An empty saved file is ignored so detection retries.
+ */
+async function resolveBeats(
+  beatPath: string | null,
+  detected: { times: number[]; strengths: number[] },
+  io: ProjectIo,
+): Promise<{ times: number[]; strengths: number[]; hasFile: boolean }> {
+  if (!beatPath) return { ...detected, hasFile: false };
+  try {
+    const content = await io.readOptionalProjectFile(beatPath);
+    const parsed = content ? parseBeats(content) : null;
+    if (parsed && parsed.times.length > 0) {
+      return { times: parsed.times, strengths: parsed.strengths, hasFile: true };
+    }
+  } catch {
+    /* fall back to detected beats */
+  }
+  return { ...detected, hasFile: false };
+}
+
+export function useMusicBeatAnalysis(): void {
+  const elements = usePlayerStore((s) => s.elements);
+  const setBeatAnalysis = usePlayerStore((s) => s.setBeatAnalysis);
+  const setBeatEdits = usePlayerStore((s) => s.setBeatEdits);
+  const setBeatPersist = usePlayerStore((s) => s.setBeatPersist);
+  const resetBeatHistory = usePlayerStore((s) => s.resetBeatHistory);
+  const { readOptionalProjectFile, writeProjectFile } = useFileManagerContext();
+
+  // File IO via ref so the effects only re-run when the track changes.
+  const ioRef = useRef({ readOptionalProjectFile, writeProjectFile });
+  ioRef.current = { readOptionalProjectFile, writeProjectFile };
+
+  const musicSrc = useMemo(() => {
+    const el = elements.find((e) => isMusicTrack(e));
+    return el?.src ?? null;
+  }, [elements]);
+
+  // ── Load: decode for strength data, then use the saved beat file if present,
+  //    otherwise seed it from detection. Resets edits + history on track change. ──
+  useEffect(() => {
+    if (!musicSrc) {
+      setBeatAnalysis(null);
+      setBeatEdits(null);
+      resetBeatHistory();
+      return;
+    }
+    let cancelled = false;
+
+    let promise = analysisCache.get(musicSrc);
+    if (!promise) {
+      promise = analyzeMusicFromUrl(musicSrc);
+      cacheAnalysis(musicSrc, promise);
+    }
+
+    const beatPath = beatFilePathForSrc(musicSrc);
+    promise
+      .then(async (analysis) => {
+        const detected = { times: analysis.beatTimes, strengths: analysis.beatStrengths };
+        const { times, strengths, hasFile } = await resolveBeats(beatPath, detected, ioRef.current);
+        if (cancelled) return;
+        setBeatEdits(null);
+        resetBeatHistory();
+        setBeatAnalysis({ ...analysis, beatTimes: times, beatStrengths: strengths });
+        // Seed a missing file through the SAME debounced writer the edits use, so
+        // the initial write can't race a near-simultaneous edit's persist.
+        if (beatPath && !hasFile && times.length > 0) usePlayerStore.getState().beatPersist?.();
+      })
+      .catch(() => {
+        if (cancelled) return;
+        setBeatAnalysis(null);
+        analysisCache.delete(musicSrc);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [musicSrc, setBeatAnalysis, setBeatEdits, resetBeatHistory]);
+
+  // ── Persist: register a debounced writer fired by every beat edit/undo/redo.
+  //    Flushes any pending write on cleanup so the last edit is never lost. ──
+  useEffect(() => {
+    const beatPath = beatFilePathForSrc(musicSrc);
+    if (!musicSrc || !beatPath) {
+      setBeatPersist(null);
+      return;
+    }
+    const audio = audioRelPathForSrc(musicSrc) ?? "audio";
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let pending: string | null = null;
+
+    const flush = () => {
+      if (pending === null) return;
+      const content = pending;
+      pending = null;
+      void ioRef.current.writeProjectFile(beatPath, content).catch(() => {});
+    };
+
+    const persist = () => {
+      const s = usePlayerStore.getState();
+      const a = s.beatAnalysis;
+      if (!a) return;
+      const merged = mergeUserBeats(a.beatTimes, a.beatStrengths, s.beatEdits, musicSrc);
+      pending = serializeBeats(merged.times, merged.strengths, audio);
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = null;
+        flush();
+      }, PERSIST_DEBOUNCE_MS);
+    };
+
+    setBeatPersist(persist);
+    return () => {
+      if (timer) clearTimeout(timer);
+      flush(); // write the last pending edit before tearing down
+      setBeatPersist(null);
+    };
+  }, [musicSrc, setBeatPersist]);
+}

package/src/hooks/useRazorSplit.ts

@@ -9,7 +9,7 @@ import {
   readFileContent,
   isSplitTimeWithinBounds,
 } from "../utils/timelineElementSplit";
-import type { RecordEditInput } from "./useTimelineEditing";
+import type { RecordEditInput } from "./timelineEditingHelpers";
 
 interface UseRazorSplitOptions {
   projectId: string | null;

package/src/hooks/useRenderClipContent.ts

@@ -22,6 +22,49 @@ export function normalizeCompositionSrc(
   return compSrc;
 }
 
+/** Resolve a media src to its project-relative preview path, or null. */
+function resolvePreviewRelative(src: string | undefined, pid: string): string | null {
+  if (!src) return null;
+  if (!src.startsWith("http")) return src;
+  const base = `/api/projects/${pid}/preview/`;
+  const idx = src.indexOf(base);
+  return idx !== -1 ? decodeURIComponent(src.slice(idx + base.length)) : null;
+}
+
+/**
+ * The trimmed source slice as start/end fractions (0–1) of the source, so the
+ * waveform can window its peaks to the clip edges. Undefined when the source
+ * length is unknown (renders full).
+ */
+function trimFractions(el: TimelineElement): { start?: number; end?: number } {
+  const sourceDur = el.sourceDuration;
+  if (sourceDur == null || sourceDur <= 0) return {};
+  const mediaStart = el.playbackStart ?? 0;
+  const rate = el.playbackRate ?? 1;
+  const start = Math.max(0, Math.min(1, mediaStart / sourceDur));
+  const end = Math.max(start, Math.min(1, (mediaStart + el.duration * rate) / sourceDur));
+  return { start, end };
+}
+
+/**
+ * Build the waveform element for an audio clip, windowing the rendered peaks to
+ * the trimmed source slice so the bars track the clip edges.
+ */
+function renderAudioClip(el: TimelineElement, pid: string, labelColor: string): ReactNode {
+  const srcRelative = resolvePreviewRelative(el.src, pid);
+  const audioUrl = srcRelative ? `/api/projects/${pid}/preview/${srcRelative}` : (el.src ?? "");
+  const waveformUrl = srcRelative ? `/api/projects/${pid}/waveform/${srcRelative}` : undefined;
+  const { start, end } = trimFractions(el);
+  return createElement(AudioWaveform, {
+    audioUrl,
+    waveformUrl,
+    label: getTimelineElementLabel(el),
+    labelColor,
+    trimStartFraction: start,
+    trimEndFraction: end,
+  });
+}
+
 interface UseRenderClipContentOptions {
   projectIdRef: { current: string | null };
   compIdToSrc: Map<string, string>;
@@ -36,6 +79,8 @@ export function useRenderClipContent({
   effectiveTimelineDuration,
 }: UseRenderClipContentOptions) {
   return useCallback(
+    // Pre-existing clip-content dispatcher; reduced by extracting renderAudioClip.
+    // fallow-ignore-next-line complexity
     (el: TimelineElement, style: { clip: string; label: string }): ReactNode => {
       const pid = projectIdRef.current;
       if (!pid) return null;
@@ -88,27 +133,7 @@ export function useRenderClipContent({
 
       // Audio clips — waveform visualization
       if (el.tag === "audio") {
-        const previewBase = `/api/projects/${pid}/preview/`;
-        const previewIdx = el.src?.startsWith("http") ? el.src.indexOf(previewBase) : -1;
-        const srcRelative = el.src
-          ? previewIdx !== -1
-            ? decodeURIComponent(el.src.slice(previewIdx + previewBase.length))
-            : el.src.startsWith("http")
-              ? null
-              : el.src
-          : null;
-        const audioUrl = srcRelative
-          ? `/api/projects/${pid}/preview/${srcRelative}`
-          : (el.src ?? "");
-        const waveformUrl = srcRelative
-          ? `/api/projects/${pid}/waveform/${srcRelative}`
-          : undefined;
-        return createElement(AudioWaveform, {
-          audioUrl,
-          waveformUrl,
-          label: getTimelineElementLabel(el),
-          labelColor: style.label,
-        });
+        return renderAudioClip(el, pid, style.label);
       }
 
       if ((el.tag === "video" || el.tag === "img") && el.src) {

package/src/hooks/useTimelineEditing.ts

@@ -26,6 +26,8 @@ import {
   readFileContent,
   applyPatchByTarget,
   formatTimelineAttributeNumber,
+  shiftGsapPositions,
+  scaleGsapPositions,
 } from "./timelineEditingHelpers";
 import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
 
@@ -122,6 +124,8 @@ export function useTimelineEditing({
         ["data-start", formatTimelineAttributeNumber(updates.start)],
         ["data-track-index", String(updates.track)],
       ]);
+      const delta = updates.start - element.start;
+      const filePath = element.sourceFile || activeCompPath || "index.html";
       return enqueueEdit(element, "Move timeline clip", (original, target) => {
         let patched = applyPatchByTarget(original, target, {
           type: "attribute",
@@ -133,9 +137,16 @@ export function useTimelineEditing({
           property: "track-index",
           value: String(updates.track),
         });
+      }).then(() => {
+        const pid = projectIdRef.current;
+        if (delta !== 0 && element.domId && pid) {
+          return shiftGsapPositions(pid, filePath, element.domId, delta)
+            .then(() => reloadPreview())
+            .catch((err) => console.error("[Timeline] Failed to shift GSAP positions", err));
+        }
       });
     },
-    [previewIframeRef, enqueueEdit],
+    [previewIframeRef, enqueueEdit, activeCompPath, reloadPreview],
   );
 
   const handleTimelineElementResize = useCallback(
@@ -143,10 +154,21 @@ export function useTimelineEditing({
       element: TimelineElement,
       updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
     ) => {
-      patchIframeDomTiming(previewIframeRef.current, element, [
+      const liveAttrs: Array<[string, string]> = [
         ["data-start", formatTimelineAttributeNumber(updates.start)],
         ["data-duration", formatTimelineAttributeNumber(updates.duration)],
-      ]);
+      ];
+      if (updates.playbackStart != null) {
+        const liveAttr =
+          element.playbackStartAttr === "playback-start"
+            ? "data-playback-start"
+            : "data-media-start";
+        liveAttrs.push([liveAttr, formatTimelineAttributeNumber(updates.playbackStart)]);
+      }
+      patchIframeDomTiming(previewIframeRef.current, element, liveAttrs);
+      const filePath = element.sourceFile || activeCompPath || "index.html";
+      const timingChanged =
+        updates.start !== element.start || updates.duration !== element.duration;
       return enqueueEdit(element, "Resize timeline clip", (original, target) => {
         const pbs = resolveResizePlaybackStart(original, target, element, updates);
         let patched = applyPatchByTarget(original, target, {
@@ -167,12 +189,30 @@ export function useTimelineEditing({
           });
         }
         return patched;
+      }).then(() => {
+        const pid = projectIdRef.current;
+        if (timingChanged && element.domId && pid) {
+          return scaleGsapPositions(
+            pid,
+            filePath,
+            element.domId,
+            element.start,
+            element.duration,
+            updates.start,
+            updates.duration,
+          )
+            .then(() => reloadPreview())
+            .catch((err) => console.error("[Timeline] Failed to scale GSAP positions", err));
+        }
+        return reloadPreview();
       });
     },
-    [previewIframeRef, enqueueEdit],
+    [previewIframeRef, enqueueEdit, activeCompPath, reloadPreview],
   );
 
   const handleTimelineElementDelete = useCallback(
+    // Pre-existing handler complexity, unchanged by this PR.
+    // fallow-ignore-next-line complexity
     async (element: TimelineElement) => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");
@@ -247,6 +287,8 @@ export function useTimelineEditing({
   );
 
   const handleTimelineAssetDrop = useCallback(
+    // Pre-existing handler complexity, unchanged by this PR.
+    // fallow-ignore-next-line complexity
     async (
       assetPath: string,
       placement: Pick<TimelineElement, "start" | "track">,
@@ -329,6 +371,8 @@ export function useTimelineEditing({
   );
 
   const handleTimelineFileDrop = useCallback(
+    // Pre-existing handler complexity, unchanged by this PR.
+    // fallow-ignore-next-line complexity
     async (files: File[], placement?: Pick<TimelineElement, "start" | "track">) => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");

package/src/player/components/AudioWaveform.tsx

@@ -5,6 +5,17 @@ interface AudioWaveformProps {
   waveformUrl?: string;
   label: string;
   labelColor: string;
+  /**
+   * Fraction (0–1) of the source the clip starts at, after the media-start
+   * trim. Defaults to 0 (no front trim).
+   */
+  trimStartFraction?: number;
+  /**
+   * Fraction (0–1) of the source the clip ends at. Defaults to 1 (no tail
+   * trim). Together these window the rendered peaks to the trimmed slice so the
+   * waveform tracks the clip edges instead of squeezing the whole file in.
+   */
+  trimEndFraction?: number;
 }
 
 const BAR_W = 2;
@@ -62,6 +73,8 @@ export const AudioWaveform = memo(function AudioWaveform({
   waveformUrl,
   label,
   labelColor,
+  trimStartFraction,
+  trimEndFraction,
 }: AudioWaveformProps) {
   const containerRef = useRef<HTMLDivElement | null>(null);
   const barsRef = useRef<HTMLDivElement | null>(null);
@@ -116,20 +129,32 @@ export const AudioWaveform = memo(function AudioWaveform({
     const barsEl = barsRef.current;
     if (!container || !barsEl || !peaks) return;
 
+    // Window the peaks to the trimmed slice [start, end) of the source so the
+    // bars track the clip edges. Clamp to a valid, non-empty range.
+    const winStart = Math.max(0, Math.min(1, trimStartFraction ?? 0));
+    const winEnd = Math.max(winStart, Math.min(1, trimEndFraction ?? 1));
+    const lo = Math.floor(winStart * peaks.length);
+    const hi = Math.max(lo + 1, Math.ceil(winEnd * peaks.length));
+    const span = hi - lo;
+
+    // Fill the full (possibly zoomed) clip width with STEP-spaced bars, resampling
+    // the windowed peaks across them — upsampling (repeating peaks) when the clip
+    // is wider than the slice has samples, so the waveform stretches with zoom
+    // instead of stopping partway across.
     const w = container.clientWidth || 400;
-    const barCount = Math.min(Math.floor(w / STEP), peaks.length);
+    const barCount = Math.max(0, Math.floor(w / STEP));
 
     let html = "";
     for (let i = 0; i < barCount; i++) {
-      // Map bar index to peak index (resample)
-      const peakIdx = Math.floor((i / barCount) * peaks.length);
+      // Map bar index to peak index within the windowed range (resample)
+      const peakIdx = lo + Math.min(span - 1, Math.floor((i / barCount) * span));
       const amp = peaks[peakIdx] ?? 0;
       const pct = Math.max(3, Math.round(amp * 100));
       const opacity = (0.45 + amp * 0.4).toFixed(2);
       html += `<div style="position:absolute;bottom:0;left:${i * STEP}px;width:${BAR_W}px;height:${pct}%;background:rgba(75,163,210,${opacity})"></div>`;
     }
     barsEl.innerHTML = html;
-  }, [peaks]);
+  }, [peaks, trimStartFraction, trimEndFraction]);
 
   // Observe container size and redraw
   const setContainerRef = useCallback(