@hyperframes/studio 0.6.73 → 0.6.75

package/src/hooks/useGsapSelectionHandlers.ts

@@ -0,0 +1,202 @@
+import { useCallback } from "react";
+import type { DomEditSelection } from "../components/editor/domEditing";
+
+/**
+ * Thin useCallback wrappers that guard on `domEditSelection` before
+ * delegating to the underlying GSAP script-commit functions. Extracted
+ * from useDomEditSession to keep that file under the 600-line limit.
+ */
+// fallow-ignore-next-line complexity
+export function useGsapSelectionHandlers({
+  domEditSelection,
+  updateGsapProperty,
+  updateGsapMeta,
+  deleteGsapAnimation,
+  addGsapAnimation,
+  addGsapProperty,
+  removeGsapProperty,
+  updateGsapFromProperty,
+  addGsapFromProperty,
+  removeGsapFromProperty,
+  addKeyframe,
+  removeKeyframe,
+  convertToKeyframes,
+  removeAllKeyframes,
+  currentTime,
+  handleDomManualEditsReset,
+  selectedGsapAnimations,
+}: {
+  domEditSelection: DomEditSelection | null;
+  updateGsapProperty: (
+    sel: DomEditSelection,
+    animId: string,
+    prop: string,
+    value: number | string,
+  ) => void;
+  updateGsapMeta: (
+    sel: DomEditSelection,
+    animId: string,
+    updates: { duration?: number; ease?: string; position?: number },
+  ) => void;
+  deleteGsapAnimation: (sel: DomEditSelection, animId: string) => void;
+  addGsapAnimation: (
+    sel: DomEditSelection,
+    method: "to" | "from" | "set" | "fromTo",
+    time: number,
+  ) => void;
+  addGsapProperty: (sel: DomEditSelection, animId: string, prop: string) => void;
+  removeGsapProperty: (sel: DomEditSelection, animId: string, prop: string) => void;
+  updateGsapFromProperty: (
+    sel: DomEditSelection,
+    animId: string,
+    prop: string,
+    value: number | string,
+  ) => void;
+  addGsapFromProperty: (sel: DomEditSelection, animId: string, prop: string) => void;
+  removeGsapFromProperty: (sel: DomEditSelection, animId: string, prop: string) => void;
+  addKeyframe: (
+    sel: DomEditSelection,
+    animId: string,
+    percentage: number,
+    property: string,
+    value: number | string,
+  ) => void;
+  removeKeyframe: (sel: DomEditSelection, animId: string, percentage: number) => void;
+  convertToKeyframes: (sel: DomEditSelection, animId: string) => void;
+  removeAllKeyframes: (sel: DomEditSelection, animId: string) => void;
+  currentTime: number;
+  handleDomManualEditsReset: (sel: DomEditSelection) => void;
+  selectedGsapAnimations: { id: string; keyframes?: unknown }[];
+}) {
+  const handleGsapUpdateProperty = useCallback(
+    (animId: string, prop: string, value: number | string) => {
+      if (!domEditSelection) return;
+      updateGsapProperty(domEditSelection, animId, prop, value);
+    },
+    [domEditSelection, updateGsapProperty],
+  );
+
+  const handleGsapUpdateMeta = useCallback(
+    (animId: string, updates: { duration?: number; ease?: string; position?: number }) => {
+      if (!domEditSelection) return;
+      updateGsapMeta(domEditSelection, animId, updates);
+    },
+    [domEditSelection, updateGsapMeta],
+  );
+
+  const handleGsapDeleteAnimation = useCallback(
+    (animId: string) => {
+      if (!domEditSelection) return;
+      deleteGsapAnimation(domEditSelection, animId);
+    },
+    [domEditSelection, deleteGsapAnimation],
+  );
+
+  const handleGsapAddAnimation = useCallback(
+    (method: "to" | "from" | "set" | "fromTo") => {
+      if (!domEditSelection) return;
+      addGsapAnimation(domEditSelection, method, currentTime);
+      if (domEditSelection.element.hasAttribute("data-hf-studio-path-offset")) {
+        handleDomManualEditsReset(domEditSelection);
+      }
+    },
+    [domEditSelection, addGsapAnimation, currentTime, handleDomManualEditsReset],
+  );
+
+  const handleGsapAddProperty = useCallback(
+    (animId: string, prop: string) => {
+      if (!domEditSelection) return;
+      addGsapProperty(domEditSelection, animId, prop);
+    },
+    [domEditSelection, addGsapProperty],
+  );
+
+  const handleGsapRemoveProperty = useCallback(
+    (animId: string, prop: string) => {
+      if (!domEditSelection) return;
+      removeGsapProperty(domEditSelection, animId, prop);
+    },
+    [domEditSelection, removeGsapProperty],
+  );
+
+  const handleGsapUpdateFromProperty = useCallback(
+    (animId: string, prop: string, value: number | string) => {
+      if (!domEditSelection) return;
+      updateGsapFromProperty(domEditSelection, animId, prop, value);
+    },
+    [domEditSelection, updateGsapFromProperty],
+  );
+
+  const handleGsapAddFromProperty = useCallback(
+    (animId: string, prop: string) => {
+      if (!domEditSelection) return;
+      addGsapFromProperty(domEditSelection, animId, prop);
+    },
+    [domEditSelection, addGsapFromProperty],
+  );
+
+  const handleGsapRemoveFromProperty = useCallback(
+    (animId: string, prop: string) => {
+      if (!domEditSelection) return;
+      removeGsapFromProperty(domEditSelection, animId, prop);
+    },
+    [domEditSelection, removeGsapFromProperty],
+  );
+
+  const handleGsapAddKeyframe = useCallback(
+    (animId: string, percentage: number, property: string, value: number | string) => {
+      if (!domEditSelection) return;
+      addKeyframe(domEditSelection, animId, percentage, property, value);
+    },
+    [domEditSelection, addKeyframe],
+  );
+
+  const handleGsapRemoveKeyframe = useCallback(
+    (animId: string, percentage: number) => {
+      if (!domEditSelection) return;
+      removeKeyframe(domEditSelection, animId, percentage);
+    },
+    [domEditSelection, removeKeyframe],
+  );
+
+  const handleGsapConvertToKeyframes = useCallback(
+    (animId: string) => {
+      if (!domEditSelection) return;
+      convertToKeyframes(domEditSelection, animId);
+    },
+    [domEditSelection, convertToKeyframes],
+  );
+
+  const handleGsapRemoveAllKeyframes = useCallback(
+    (animId: string) => {
+      if (!domEditSelection) return;
+      removeAllKeyframes(domEditSelection, animId);
+    },
+    [domEditSelection, removeAllKeyframes],
+  );
+
+  const handleResetSelectedElementKeyframes = useCallback((): boolean => {
+    if (!domEditSelection) return false;
+    const withKeyframes = selectedGsapAnimations.find((a) => a.keyframes);
+    if (!withKeyframes) return false;
+    removeAllKeyframes(domEditSelection, withKeyframes.id);
+    return true;
+  }, [domEditSelection, selectedGsapAnimations, removeAllKeyframes]);
+
+  return {
+    handleGsapUpdateProperty,
+    handleGsapUpdateMeta,
+    handleGsapDeleteAnimation,
+    handleGsapAddAnimation,
+    handleGsapAddProperty,
+    handleGsapRemoveProperty,
+    handleGsapUpdateFromProperty,
+    handleGsapAddFromProperty,
+    handleGsapRemoveFromProperty,
+    handleGsapAddKeyframe,
+    handleGsapRemoveKeyframe,
+    handleGsapConvertToKeyframes,
+    handleGsapRemoveAllKeyframes,
+    handleResetSelectedElementKeyframes,
+  };
+}

package/src/hooks/useGsapTweenCache.ts

@@ -1,5 +1,12 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState, useCallback } from "react";
 import type { GsapAnimation, ParsedGsap } from "@hyperframes/core/gsap-parser";
+import { usePlayerStore } from "../player/store/playerStore";
+import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeBridge";
+
+function extractIdFromSelector(selector: string): string | null {
+  const match = selector.match(/^#([\w-]+)/);
+  return match ? match[1] : null;
+}
 
 /** The selected element's identity for matching tweens to it. */
 export interface GsapElementTarget {
@@ -28,7 +35,7 @@ export function getAnimationsForElement(
   );
 }
 
-async function fetchParsedAnimations(
+export async function fetchParsedAnimations(
   projectId: string,
   sourceFile: string,
 ): Promise<ParsedGsap | null> {
@@ -47,6 +54,7 @@ export function useGsapAnimationsForElement(
   sourceFile: string,
   target: GsapElementTarget | null,
   version: number,
+  iframeRef?: React.RefObject<HTMLIFrameElement | null>,
 ): {
   animations: GsapAnimation[];
   multipleTimelines: boolean;
@@ -88,9 +96,23 @@ export function useGsapAnimationsForElement(
     };
   }, [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]);
+
   const targetId = target?.id ?? null;
   const targetSelector = target?.selector ?? null;
-  const animations = useMemo(
+  const rawAnimations = useMemo(
     () =>
       targetId || targetSelector
         ? getAnimationsForElement(allAnimations, { id: targetId, selector: targetSelector })
@@ -98,6 +120,76 @@ export function useGsapAnimationsForElement(
     [allAnimations, targetId, targetSelector],
   );
 
+  const animations = useMemo(() => {
+    const iframe = iframeRef?.current;
+    let result = rawAnimations;
+
+    // Enrich animations with unresolved keyframes from runtime
+    if (iframe) {
+      result = result.map((anim) => {
+        if (!anim.hasUnresolvedKeyframes || anim.keyframes) return anim;
+        const runtime = readRuntimeKeyframes(iframe, anim.targetSelector);
+        if (!runtime) return anim;
+        return {
+          ...anim,
+          keyframes: {
+            format: "percentage" as const,
+            keyframes: runtime.keyframes,
+            ...(runtime.easeEach ? { easeEach: runtime.easeEach } : {}),
+          },
+        };
+      });
+    }
+
+    // Match unresolved-selector animations from the parser to runtime tweens
+    // targeting this element. This handles fully dynamic code (loop with variable selector).
+    if (iframe && targetId && result.length === 0) {
+      const unresolvedAnims = allAnimations.filter((a) => a.hasUnresolvedSelector);
+      if (unresolvedAnims.length > 0) {
+        const runtimeData = readRuntimeKeyframes(iframe, `#${targetId}`);
+        if (runtimeData) {
+          const scanned = scanAllRuntimeKeyframes(iframe);
+          const runtimeEntry = scanned.get(targetId);
+          if (runtimeEntry) {
+            // Find which unresolved animation index matches this element
+            // by correlating parser order with runtime tween order
+            const runtimeIds = Array.from(scanned.keys());
+            const runtimeIndex = runtimeIds.indexOf(targetId);
+            const matchedAnim =
+              runtimeIndex >= 0 && runtimeIndex < unresolvedAnims.length
+                ? unresolvedAnims[runtimeIndex]
+                : unresolvedAnims[0];
+            if (matchedAnim) {
+              result = [
+                {
+                  ...matchedAnim,
+                  targetSelector: `#${targetId}`,
+                  keyframes: {
+                    format: "percentage" as const,
+                    keyframes: runtimeEntry.keyframes,
+                    ...(runtimeEntry.easeEach ? { easeEach: runtimeEntry.easeEach } : {}),
+                  },
+                },
+              ];
+            }
+          }
+        }
+      }
+    }
+
+    return result;
+  }, [rawAnimations, allAnimations, iframeRef, targetId]);
+
+  // Populate keyframe cache for the selected element.
+  // Key format must match timeline element keys: "sourceFile#domId".
+  const elementId = target?.id ?? null;
+  useEffect(() => {
+    if (!elementId) return;
+    const { setKeyframeCache } = usePlayerStore.getState();
+    const withKeyframes = animations.find((a) => a.keyframes);
+    setKeyframeCache(`${sourceFile}#${elementId}`, withKeyframes?.keyframes ?? undefined);
+  }, [elementId, sourceFile, animations]);
+
   return { animations, multipleTimelines, unsupportedTimelinePattern };
 }
 
@@ -106,3 +198,82 @@ export function useGsapCacheVersion() {
   const bump = useCallback(() => setVersion((v) => v + 1), []);
   return { version, bump };
 }
+
+/**
+ * Fetch GSAP animations for a file and populate the keyframe cache for all
+ * elements. Called from the Timeline component so diamonds show without
+ * requiring a selection.
+ */
+export function usePopulateKeyframeCacheForFile(
+  projectId: string | null,
+  sourceFile: string,
+  version: number,
+  iframeRef?: React.RefObject<HTMLIFrameElement | null>,
+): void {
+  const lastFetchKeyRef = useRef("");
+
+  const runtimeScanDoneRef = useRef("");
+
+  useEffect(() => {
+    const fetchKey = `kf-cache:${projectId}:${sourceFile}:${version}`;
+    if (fetchKey === lastFetchKeyRef.current) return;
+    lastFetchKeyRef.current = fetchKey;
+    runtimeScanDoneRef.current = "";
+    if (!projectId) return;
+
+    const sf = sourceFile;
+    fetchParsedAnimations(projectId, sf).then((parsed) => {
+      if (!parsed) return;
+      const { setKeyframeCache } = usePlayerStore.getState();
+      for (const anim of parsed.animations) {
+        const id = extractIdFromSelector(anim.targetSelector);
+        if (!id || !anim.keyframes) continue;
+        setKeyframeCache(`${sf}#${id}`, anim.keyframes);
+        if (sf !== "index.html") setKeyframeCache(`index.html#${id}`, anim.keyframes);
+      }
+      runtimeScanDoneRef.current = fetchKey;
+    });
+  }, [projectId, sourceFile, version]);
+
+  // Separate effect for runtime keyframe discovery — polls until the iframe
+  // has loaded GSAP timelines, independent of the AST fetch lifecycle.
+  useEffect(() => {
+    if (!projectId) return;
+    const sf = sourceFile;
+
+    let attempts = 0;
+    const maxAttempts = 10;
+
+    const tryRuntimeScan = () => {
+      if (runtimeScanDoneRef.current === `kf-cache:${projectId}:${sf}:${version}`) return true;
+      const iframe = iframeRef?.current;
+      if (!iframe) return false;
+      const scanned = scanAllRuntimeKeyframes(iframe);
+      if (scanned.size === 0) return false;
+      const { setKeyframeCache, keyframeCache } = usePlayerStore.getState();
+      for (const [id, data] of scanned) {
+        const cacheKey = `${sf}#${id}`;
+        const fallbackKey = `index.html#${id}`;
+        if (keyframeCache.has(cacheKey) || keyframeCache.has(fallbackKey)) continue;
+        const entry = {
+          format: "percentage" as const,
+          keyframes: data.keyframes,
+          ...(data.easeEach ? { easeEach: data.easeEach } : {}),
+        };
+        setKeyframeCache(cacheKey, entry);
+        if (sf !== "index.html") setKeyframeCache(fallbackKey, entry);
+      }
+      runtimeScanDoneRef.current = `kf-cache:${projectId}:${sf}:${version}`;
+      return true;
+    };
+
+    if (tryRuntimeScan()) return;
+
+    const interval = setInterval(() => {
+      attempts++;
+      if (tryRuntimeScan() || attempts >= maxAttempts) clearInterval(interval);
+    }, 500);
+
+    return () => clearInterval(interval);
+  }, [projectId, sourceFile, version, iframeRef]);
+}

package/src/hooks/useTimelineEditing.ts

@@ -466,10 +466,103 @@ export function useTimelineEditing({
     [showToast],
   );
 
+  const handleTimelineElementSplit = useCallback(
+    async (element: TimelineElement, splitTime: number) => {
+      const pid = projectIdRef.current;
+      if (!pid) return;
+
+      const splittableTags = new Set(["video", "audio", "img"]);
+      if (
+        element.timelineLocked ||
+        element.timingSource === "implicit" ||
+        element.compositionSrc ||
+        !splittableTags.has(element.tag) ||
+        !element.duration ||
+        !Number.isFinite(element.duration)
+      ) {
+        return;
+      }
+
+      if (splitTime <= element.start || splitTime >= element.start + element.duration) {
+        showToast("Playhead must be inside the clip to split.", "error");
+        return;
+      }
+
+      const patchTarget = buildPatchTarget(element);
+      if (!patchTarget) {
+        showToast("Clip is missing a patchable target.", "error");
+        return;
+      }
+
+      const targetPath = element.sourceFile || activeCompPath || "index.html";
+      try {
+        const originalContent = await readFileContent(pid, targetPath);
+        const existingIds = collectHtmlIds(originalContent);
+        const baseId = element.domId || "clip";
+        let newId = `${baseId}-split`;
+        let suffix = 2;
+        while (existingIds.includes(newId)) {
+          newId = `${baseId}-split-${suffix++}`;
+        }
+
+        const response = await fetch(
+          `/api/projects/${pid}/file-mutations/split-element/${encodeURIComponent(targetPath)}`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ target: patchTarget, splitTime, newId }),
+          },
+        );
+        if (!response.ok) {
+          throw new Error("Split request failed");
+        }
+
+        const data = (await response.json()) as {
+          ok?: boolean;
+          changed?: boolean;
+          content?: string;
+        };
+        if (!data.ok || !data.changed) {
+          showToast("Failed to split clip — playhead may be outside the clip.", "error");
+          return;
+        }
+
+        const patchedContent = typeof data.content === "string" ? data.content : originalContent;
+
+        domEditSaveTimestampRef.current = Date.now();
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Split timeline clip",
+          kind: "timeline",
+          files: { [targetPath]: patchedContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit,
+        });
+
+        reloadPreview();
+        const label = getTimelineElementLabel(element);
+        showToast(`Split ${label} at ${splitTime.toFixed(2)}s`, "info");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to split timeline clip";
+        showToast(message, "error");
+      }
+    },
+    [
+      activeCompPath,
+      recordEdit,
+      showToast,
+      writeProjectFile,
+      domEditSaveTimestampRef,
+      reloadPreview,
+    ],
+  );
+
   return {
     handleTimelineElementMove,
     handleTimelineElementResize,
     handleTimelineElementDelete,
+    handleTimelineElementSplit,
     handleTimelineAssetDrop,
     handleTimelineFileDrop,
     handleBlockedTimelineEdit,

package/src/icons/SystemIcons.tsx

@@ -20,6 +20,7 @@ import {
   Camera as PhCamera,
   ArrowClockwise,
   Gear,
+  Scissors as PhScissors,
 } from "@phosphor-icons/react";
 import type { Icon as PhosphorIcon, IconProps as PhosphorIconProps } from "@phosphor-icons/react";
 
@@ -55,3 +56,4 @@ export const RotateCcw = makeIcon(ArrowCounterClockwise);
 export const Camera = makeIcon(PhCamera);
 export const RotateCw = makeIcon(ArrowClockwise);
 export const Settings = makeIcon(Gear);
+export const Scissors = makeIcon(PhScissors);

package/src/player/components/ClipContextMenu.tsx

@@ -0,0 +1,99 @@
+import { memo, useCallback, useEffect, useRef } from "react";
+import type { TimelineElement } from "../store/playerStore";
+
+interface ClipContextMenuProps {
+  x: number;
+  y: number;
+  element: TimelineElement;
+  currentTime: number;
+  onClose: () => void;
+  onSplit: (element: TimelineElement, splitTime: number) => void;
+  onDelete: (element: TimelineElement) => void;
+}
+
+export const ClipContextMenu = memo(function ClipContextMenu({
+  x,
+  y,
+  element,
+  currentTime,
+  onClose,
+  onSplit,
+  onDelete,
+}: ClipContextMenuProps) {
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  const dismiss = useCallback(
+    (e: MouseEvent | KeyboardEvent) => {
+      if (e instanceof KeyboardEvent && e.key !== "Escape") return;
+      if (e instanceof MouseEvent && menuRef.current?.contains(e.target as Node)) return;
+      onClose();
+    },
+    [onClose],
+  );
+
+  useEffect(() => {
+    document.addEventListener("mousedown", dismiss);
+    document.addEventListener("keydown", dismiss);
+    return () => {
+      document.removeEventListener("mousedown", dismiss);
+      document.removeEventListener("keydown", dismiss);
+    };
+  }, [dismiss]);
+
+  const adjustedX = Math.min(x, window.innerWidth - 200);
+  const adjustedY = Math.min(y, window.innerHeight - 200);
+
+  const isSplittable = ["video", "audio", "img"].includes(element.tag);
+  const canSplit =
+    isSplittable && currentTime > element.start && currentTime < element.start + element.duration;
+
+  const splitLabel = !isSplittable
+    ? null
+    : canSplit
+      ? `Split at ${currentTime.toFixed(2)}s`
+      : "Split (move playhead inside clip)";
+
+  return (
+    <div
+      ref={menuRef}
+      className="fixed z-50 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"
+      style={{ left: adjustedX, top: adjustedY }}
+    >
+      {splitLabel && (
+        <>
+          <button
+            type="button"
+            className={`w-full flex items-center justify-between px-3 py-1.5 text-xs text-left ${
+              canSplit
+                ? "text-neutral-300 hover:bg-neutral-800 cursor-pointer"
+                : "text-neutral-600 cursor-not-allowed"
+            }`}
+            disabled={!canSplit}
+            onClick={() => {
+              if (canSplit) {
+                onSplit(element, currentTime);
+                onClose();
+              }
+            }}
+          >
+            <span>{splitLabel}</span>
+            <span className="text-neutral-500 text-[10px] ml-3">S</span>
+          </button>
+          <div className="my-1 border-t border-neutral-700/60" />
+        </>
+      )}
+
+      <button
+        type="button"
+        className="w-full flex items-center justify-between px-3 py-1.5 text-xs text-red-400 hover:bg-neutral-800 cursor-pointer text-left"
+        onClick={() => {
+          onDelete(element);
+          onClose();
+        }}
+      >
+        <span>Delete</span>
+        <span className="text-neutral-500 text-[10px] ml-3">⌫</span>
+      </button>
+    </div>
+  );
+});