@hyperframes/studio 0.6.73 → 0.6.74

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -0,0 +1,170 @@
+/**
+ * Read GSAP keyframe data from the live runtime in the preview iframe.
+ * Used to discover dynamic keyframes that the AST parser can't resolve
+ * (loops, variables, computed selectors).
+ */
+
+interface RuntimeTween {
+  targets?: () => Element[];
+  vars?: Record<string, unknown>;
+  duration?: () => number;
+  startTime?: () => number;
+}
+
+interface RuntimeTimeline {
+  getChildren?: (deep: boolean) => RuntimeTween[];
+  duration?: () => number;
+}
+
+export function readRuntimeKeyframes(
+  iframe: HTMLIFrameElement | null,
+  selector: string,
+  compositionId?: string,
+): {
+  keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
+  easeEach?: string;
+} | null {
+  if (!iframe?.contentWindow) return null;
+
+  let timelines: Record<string, RuntimeTimeline | undefined> | undefined;
+  try {
+    timelines = (
+      iframe.contentWindow as unknown as { __timelines?: Record<string, RuntimeTimeline> }
+    ).__timelines;
+  } catch {
+    return null;
+  }
+  if (!timelines) return null;
+
+  const tlId = compositionId || Object.keys(timelines)[0];
+  if (!tlId) return null;
+  const timeline = timelines[tlId];
+  if (!timeline?.getChildren) return null;
+
+  let doc: Document | null = null;
+  try {
+    doc = iframe.contentDocument;
+  } catch {
+    return null;
+  }
+  if (!doc) return null;
+
+  const targetEl = doc.querySelector(selector);
+  if (!targetEl) return null;
+
+  for (const tween of timeline.getChildren(true)) {
+    if (!tween.targets || !tween.vars) continue;
+    let matches = false;
+    for (const t of tween.targets()) {
+      if (t === targetEl || (targetEl.id && t.id === targetEl.id)) {
+        matches = true;
+        break;
+      }
+    }
+    if (!matches) continue;
+
+    const vars = tween.vars;
+    if (!vars.keyframes || typeof vars.keyframes !== "object") continue;
+
+    const kfObj = vars.keyframes as Record<string, unknown>;
+    const result: Array<{ percentage: number; properties: Record<string, number | string> }> = [];
+    let easeEach: string | undefined;
+
+    for (const [key, val] of Object.entries(kfObj)) {
+      if (key === "easeEach") {
+        if (typeof val === "string") easeEach = val;
+        continue;
+      }
+      const pctMatch = key.match(/^(\d+(?:\.\d+)?)%$/);
+      if (!pctMatch || !val || typeof val !== "object") continue;
+      const percentage = parseFloat(pctMatch[1]);
+      const properties: Record<string, number | string> = {};
+      for (const [pk, pv] of Object.entries(val as Record<string, unknown>)) {
+        if (pk === "ease") continue;
+        if (typeof pv === "number") properties[pk] = Math.round(pv * 1000) / 1000;
+        else if (typeof pv === "string") properties[pk] = pv;
+      }
+      if (Object.keys(properties).length > 0) {
+        result.push({ percentage, properties });
+      }
+    }
+
+    if (result.length > 0) {
+      result.sort((a, b) => a.percentage - b.percentage);
+      return { keyframes: result, easeEach };
+    }
+  }
+  return null;
+}
+
+// fallow-ignore-next-line complexity
+export function scanAllRuntimeKeyframes(iframe: HTMLIFrameElement | null): Map<
+  string,
+  {
+    keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
+    easeEach?: string;
+  }
+> {
+  const result = new Map<
+    string,
+    {
+      keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
+      easeEach?: string;
+    }
+  >();
+  if (!iframe?.contentWindow) return result;
+
+  let timelines: Record<string, RuntimeTimeline | undefined> | undefined;
+  try {
+    timelines = (
+      iframe.contentWindow as unknown as { __timelines?: Record<string, RuntimeTimeline> }
+    ).__timelines;
+  } catch {
+    return result;
+  }
+  if (!timelines) return result;
+
+  for (const timeline of Object.values(timelines)) {
+    if (!timeline?.getChildren) continue;
+    for (const tween of timeline.getChildren(true)) {
+      if (!tween.targets || !tween.vars) continue;
+      const vars = tween.vars;
+      if (!vars.keyframes || typeof vars.keyframes !== "object") continue;
+
+      const kfObj = vars.keyframes as Record<string, unknown>;
+      const keyframes: Array<{ percentage: number; properties: Record<string, number | string> }> =
+        [];
+      let easeEach: string | undefined;
+
+      for (const [key, val] of Object.entries(kfObj)) {
+        if (key === "easeEach") {
+          if (typeof val === "string") easeEach = val;
+          continue;
+        }
+        const pctMatch = key.match(/^(\d+(?:\.\d+)?)%$/);
+        if (!pctMatch || !val || typeof val !== "object") continue;
+        const percentage = parseFloat(pctMatch[1]);
+        const properties: Record<string, number | string> = {};
+        for (const [pk, pv] of Object.entries(val as Record<string, unknown>)) {
+          if (pk === "ease") continue;
+          if (typeof pv === "number") properties[pk] = Math.round(pv * 1000) / 1000;
+          else if (typeof pv === "string") properties[pk] = pv;
+        }
+        if (Object.keys(properties).length > 0) {
+          keyframes.push({ percentage, properties });
+        }
+      }
+
+      if (keyframes.length === 0) continue;
+      keyframes.sort((a, b) => a.percentage - b.percentage);
+
+      for (const target of tween.targets()) {
+        const id = (target as HTMLElement).id;
+        if (id && !result.has(id)) {
+          result.set(id, { keyframes, easeEach });
+        }
+      }
+    }
+  }
+  return result;
+}

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -0,0 +1,131 @@
+/**
+ * Unified helper for committing any GSAP property value from the design panel.
+ *
+ * Handles three cases:
+ * 1. Animation with keyframes → add-keyframe at current percentage
+ * 2. Flat animation (no keyframes) → convert to keyframes, then add-keyframe
+ * 3. No animation → create tl.to(), convert to keyframes, then add-keyframe
+ */
+import { useCallback } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { usePlayerStore } from "../player/store/playerStore";
+import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeBridge";
+
+interface CommitAnimatedPropertyDeps {
+  selectedGsapAnimations: GsapAnimation[];
+  gsapCommitMutation:
+    | ((
+        selection: DomEditSelection,
+        mutation: Record<string, unknown>,
+        options: {
+          label: string;
+          coalesceKey?: string;
+          softReload?: boolean;
+          skipReload?: boolean;
+        },
+      ) => Promise<void>)
+    | null;
+  addGsapAnimation: (
+    selection: DomEditSelection,
+    method: "to" | "from" | "set" | "fromTo",
+    currentTime?: number,
+  ) => void;
+  convertToKeyframes: (selection: DomEditSelection, animId: string) => void;
+  previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
+  bumpGsapCache: () => void;
+}
+
+function computePercentage(selection: DomEditSelection): number {
+  const elStart = Number.parseFloat(selection.dataAttributes?.start ?? "0") || 0;
+  const elDuration = Number.parseFloat(selection.dataAttributes?.duration ?? "1") || 1;
+  const currentTime = usePlayerStore.getState().currentTime;
+  return elDuration > 0
+    ? Math.max(0, Math.min(100, Math.round(((currentTime - elStart) / elDuration) * 1000) / 10))
+    : 0;
+}
+
+function selectorFor(selection: DomEditSelection): string | null {
+  if (selection.id) return `#${selection.id}`;
+  if (selection.selector) return selection.selector;
+  return null;
+}
+
+export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
+  const {
+    selectedGsapAnimations,
+    gsapCommitMutation,
+    addGsapAnimation,
+    previewIframeRef,
+    bumpGsapCache,
+  } = deps;
+
+  const commitAnimatedProperty = useCallback(
+    async (
+      selection: DomEditSelection,
+      property: string,
+      value: number | string,
+    ): Promise<void> => {
+      if (!gsapCommitMutation) return;
+
+      const iframe = previewIframeRef.current;
+      const selector = selectorFor(selection);
+      const pct = computePercentage(selection);
+
+      let anim: GsapAnimation | undefined =
+        selectedGsapAnimations.find((a) => a.keyframes) ?? selectedGsapAnimations[0];
+
+      // Case 3: No animation — create one first
+      if (!anim) {
+        addGsapAnimation(selection, "to");
+        // The addGsapAnimation triggers a reload. We need to wait for the cache
+        // to update. Use a small delay then bump cache to re-fetch.
+        await new Promise((r) => setTimeout(r, 500));
+        bumpGsapCache();
+        // After creation, we can't proceed in this call — the animation isn't
+        // in our local state yet. The user's next edit will find it.
+        // For immediate feedback, trigger a convert-to-keyframes on the new animation.
+        return;
+      }
+
+      // Case 2: Flat animation — convert to keyframes first
+      if (!anim.keyframes) {
+        await gsapCommitMutation(
+          selection,
+          { type: "convert-to-keyframes", animationId: anim.id },
+          { label: "Convert to keyframes", skipReload: true },
+        );
+      }
+
+      // Read all currently animated properties from runtime for backfill
+      const runtimeProps = selector ? readAllAnimatedProperties(iframe, selector, anim) : {};
+
+      // Build the properties object: all runtime props + the new value
+      const properties: Record<string, number | string> = { ...runtimeProps };
+      properties[property] = value;
+
+      // Compute backfill defaults for properties not in existing keyframes
+      const backfillDefaults: Record<string, number | string> = { ...runtimeProps };
+      if (!(property in runtimeProps) && selector) {
+        const cssVal = readGsapProperty(iframe, selector, property);
+        if (cssVal != null) backfillDefaults[property] = cssVal;
+      }
+      backfillDefaults[property] = typeof value === "number" ? value : value;
+
+      await gsapCommitMutation(
+        selection,
+        {
+          type: "add-keyframe",
+          animationId: anim.id,
+          percentage: pct,
+          properties,
+          backfillDefaults,
+        },
+        { label: `Edit ${property} (keyframe ${pct}%)`, softReload: true },
+      );
+    },
+    [selectedGsapAnimations, gsapCommitMutation, addGsapAnimation, previewIframeRef, bumpGsapCache],
+  );
+
+  return commitAnimatedProperty;
+}

package/src/hooks/useAppHotkeys.ts

@@ -62,6 +62,7 @@ interface EditHistoryHandle {
 interface UseAppHotkeysParams {
   toggleTimelineVisibility: () => void;
   handleTimelineElementDelete: (element: TimelineElement) => Promise<void>;
+  handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void>;
   handleDomEditElementDelete: (selection: DomEditSelection) => Promise<void>;
   domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
   clearDomSelectionRef: React.MutableRefObject<() => void>;
@@ -77,6 +78,9 @@ interface UseAppHotkeysParams {
   handleCopy: () => boolean;
   handlePaste: () => Promise<void>;
   handleCut: () => Promise<boolean>;
+  onResetKeyframes: () => boolean;
+  onDeleteSelectedKeyframes: () => void;
+  onAfterUndoRedo?: () => void;
 }
 
 // ── Hook ──
@@ -84,6 +88,7 @@ interface UseAppHotkeysParams {
 export function useAppHotkeys({
   toggleTimelineVisibility,
   handleTimelineElementDelete,
+  handleTimelineElementSplit,
   handleDomEditElementDelete,
   domEditSelectionRef,
   editHistory,
@@ -98,6 +103,9 @@ export function useAppHotkeys({
   handleCopy,
   handlePaste,
   handleCut,
+  onResetKeyframes,
+  onDeleteSelectedKeyframes,
+  onAfterUndoRedo,
 }: UseAppHotkeysParams) {
   const previewHotkeyWindowRef = useRef<Window | null>(null);
   const handleAppKeyDownRef = useRef<((event: KeyboardEvent) => void) | undefined>(undefined);
@@ -144,6 +152,7 @@ export function useAppHotkeys({
       return;
     }
     if (result.ok && result.label) {
+      onAfterUndoRedo?.();
       await syncHistoryPreviewAfterApply(result.paths);
       showToast(`Undid ${result.label}`, "info");
     }
@@ -154,6 +163,7 @@ export function useAppHotkeys({
     syncHistoryPreviewAfterApply,
     waitForPendingDomEditSaves,
     writeHistoryProjectFile,
+    onAfterUndoRedo,
   ]);
 
   const handleRedo = useCallback(async () => {
@@ -167,6 +177,7 @@ export function useAppHotkeys({
       return;
     }
     if (result.ok && result.label) {
+      onAfterUndoRedo?.();
       await syncHistoryPreviewAfterApply(result.paths);
       showToast(`Redid ${result.label}`, "info");
     }
@@ -177,6 +188,7 @@ export function useAppHotkeys({
     syncHistoryPreviewAfterApply,
     waitForPendingDomEditSaves,
     writeHistoryProjectFile,
+    onAfterUndoRedo,
   ]);
 
   // ── Stable refs for the consolidated keydown handler ──
@@ -185,6 +197,8 @@ export function useAppHotkeys({
   handleToggleRef.current = handleTimelineToggleHotkey;
   const handleDeleteRef = useRef(handleTimelineElementDelete);
   handleDeleteRef.current = handleTimelineElementDelete;
+  const handleSplitRef = useRef(handleTimelineElementSplit);
+  handleSplitRef.current = handleTimelineElementSplit;
   const handleDomEditDeleteRef = useRef(handleDomEditElementDelete);
   handleDomEditDeleteRef.current = handleDomEditElementDelete;
   const handleUndoRef = useRef(handleUndo);
@@ -197,6 +211,10 @@ export function useAppHotkeys({
   handlePasteRef.current = handlePaste;
   const handleCutRef = useRef(handleCut);
   handleCutRef.current = handleCut;
+  const onResetKeyframesRef = useRef(onResetKeyframes);
+  onResetKeyframesRef.current = onResetKeyframes;
+  const onDeleteSelectedKeyframesRef = useRef(onDeleteSelectedKeyframes);
+  onDeleteSelectedKeyframesRef.current = onDeleteSelectedKeyframes;
 
   // ── Consolidated keydown handler ──
 
@@ -292,7 +310,31 @@ export function useAppHotkeys({
       return;
     }
 
-    // Delete / Backspace — remove selected element (timeline clip or preview selection)
+    // S — split selected clip at playhead
+    if (
+      event.key === "s" &&
+      !event.metaKey &&
+      !event.ctrlKey &&
+      !event.altKey &&
+      !isEditableTarget(event.target)
+    ) {
+      const { selectedElementId, elements, currentTime } = usePlayerStore.getState();
+      if (selectedElementId) {
+        const element = elements.find((el) => (el.key ?? el.id) === selectedElementId);
+        if (
+          element &&
+          ["video", "audio", "img"].includes(element.tag) &&
+          currentTime > element.start &&
+          currentTime < element.start + element.duration
+        ) {
+          event.preventDefault();
+          void handleSplitRef.current(element, currentTime);
+          return;
+        }
+      }
+    }
+
+    // Delete / Backspace — remove selected keyframes > reset keyframes > remove element
     if (
       (event.key === "Delete" || event.key === "Backspace") &&
       !event.metaKey &&
@@ -300,6 +342,26 @@ export function useAppHotkeys({
       !event.altKey &&
       !isEditableTarget(event.target)
     ) {
+      // Priority: selected keyframes take precedence over clip deletion
+      const { selectedKeyframes } = usePlayerStore.getState();
+      if (selectedKeyframes.size > 0) {
+        onDeleteSelectedKeyframesRef.current();
+        usePlayerStore.getState().clearSelectedKeyframes();
+        event.preventDefault();
+        return;
+      }
+
+      // Backspace: try resetting keyframes first; fall through to delete if none found
+      if (event.key === "Backspace") {
+        const { selectedElementId, keyframeCache } = usePlayerStore.getState();
+        if (selectedElementId && keyframeCache.has(selectedElementId)) {
+          if (onResetKeyframesRef.current()) {
+            event.preventDefault();
+            return;
+          }
+        }
+      }
+
       const { selectedElementId, elements } = usePlayerStore.getState();
       if (selectedElementId) {
         const element = elements.find((el) => (el.key ?? el.id) === selectedElementId);

package/src/hooks/useDomEditCommits.ts

@@ -35,6 +35,37 @@ import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditO
 import type { EditHistoryKind } from "../utils/editHistory";
 import { useDomEditTextCommits } from "./useDomEditTextCommits";
 
+// ── Helpers ──
+
+type TimelineLike = { getChildren?: (nested: boolean) => Array<{ targets?: () => Element[] }> };
+
+function isElementGsapTargeted(iframe: HTMLIFrameElement | null, element: HTMLElement): boolean {
+  if (!iframe?.contentWindow) return false;
+  let timelines: Record<string, TimelineLike> | undefined;
+  try {
+    timelines = (iframe.contentWindow as Window & { __timelines?: Record<string, TimelineLike> })
+      .__timelines;
+  } catch {
+    return false;
+  }
+  if (!timelines) return false;
+  const id = element.id;
+  for (const tl of Object.values(timelines)) {
+    if (!tl?.getChildren) continue;
+    try {
+      for (const child of tl.getChildren(true)) {
+        if (!child.targets) continue;
+        for (const t of child.targets()) {
+          if (t === element || (id && t.id === id)) return true;
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
+
 // ── Types ──
 
 interface RecordEditInput {
@@ -290,12 +321,13 @@ export function useDomEditCommits({
   const handleDomPathOffsetCommit = useCallback(
     (selection: DomEditSelection, next: { x: number; y: number }) => {
       applyStudioPathOffset(selection.element, next);
+      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) return;
       commitPositionPatchToHtml(selection, buildPathOffsetPatches(selection.element), {
         label: "Move layer",
         coalesceKey: `path-offset:${getDomEditTargetKey(selection)}`,
       });
     },
-    [commitPositionPatchToHtml],
+    [commitPositionPatchToHtml, previewIframeRef],
   );
 
   const handleDomGroupPathOffsetCommit = useCallback(
@@ -307,35 +339,38 @@ export function useDomEditCommits({
         .join(":");
       for (const { selection, next } of updates) {
         applyStudioPathOffset(selection.element, next);
+        if (isElementGsapTargeted(previewIframeRef.current, selection.element)) continue;
         commitPositionPatchToHtml(selection, buildPathOffsetPatches(selection.element), {
           label: `Move ${updates.length} layers`,
           coalesceKey: `group-path-offset:${coalesceKey}`,
         });
       }
     },
-    [commitPositionPatchToHtml],
+    [commitPositionPatchToHtml, previewIframeRef],
   );
 
   const handleDomBoxSizeCommit = useCallback(
     (selection: DomEditSelection, next: { width: number; height: number }) => {
       applyStudioBoxSize(selection.element, next);
+      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) return;
       commitPositionPatchToHtml(selection, buildBoxSizePatches(selection.element), {
         label: "Resize layer box",
         coalesceKey: `box-size:${getDomEditTargetKey(selection)}`,
       });
     },
-    [commitPositionPatchToHtml],
+    [commitPositionPatchToHtml, previewIframeRef],
   );
 
   const handleDomRotationCommit = useCallback(
     (selection: DomEditSelection, next: { angle: number }) => {
       applyStudioRotation(selection.element, next);
+      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) return;
       commitPositionPatchToHtml(selection, buildRotationPatches(selection.element), {
         label: "Rotate layer",
         coalesceKey: `rotation:${getDomEditTargetKey(selection)}`,
       });
     },
-    [commitPositionPatchToHtml],
+    [commitPositionPatchToHtml, previewIframeRef],
   );
 
   const handleDomManualEditsReset = useCallback(