@hyperframes/studio 0.7.55 → 0.7.57

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -14,7 +14,7 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeBridge";
 import type { SetPatchProps } from "./gsapRuntimePatch";
-import { selectorFromSelection, computeElementPercentage } from "./gsapShared";
+import { selectorFromSelection, computeElementPercentage, isInstantHold } from "./gsapShared";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
 import { roundTo3 } from "../utils/rounding";
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
@@ -161,8 +161,8 @@ async function commitSetProps(
 /**
  * Static element (no keyframes on ANY of its tweens): persist the 3D props as a
  * `tl.set` — NEVER keyframes. Mirrors manual drag / resize / rotate, which `tl.set`
- * a static element instead of animating it. Updates an existing `set` in place, or
- * creates a dedicated `set` at position 0 when the element has none.
+ * a static element instead of animating it. Updates an existing same-group static
+ * hold in place, or creates a dedicated `set` at position 0 when the element has none.
  */
 async function commitStaticSet(
   selection: DomEditSelection,
@@ -172,12 +172,12 @@ async function commitStaticSet(
   commit: Commit,
 ): Promise<void> {
   if (!selector) return;
-  // One commit per PROPERTY GROUP, each into a set that owns that group — never a
-  // flat `to`/`from`, and never a foreign-group set (a width edit used to merge
-  // into the element's position set, producing a mixed set the split machinery
-  // exists to prevent). Within a group everything batches into ONE commit: a
-  // set's id is group-derived, so a per-prop loop would shift the id mid-way and
-  // 404 the next update.
+  // One commit per PROPERTY GROUP, each into a static write that owns that group —
+  // never a live tween, and never a foreign-group write (a width edit used to
+  // merge into the element's position set, producing a mixed write the split
+  // machinery exists to prevent). Within a group everything batches into ONE
+  // commit: a write's id is group-derived, so a per-prop loop would shift the id
+  // mid-way and 404 the next update.
   const byGroup = new Map<string, [string, number | string][]>();
   for (const entry of propEntries) {
     const group = classifyPropertyGroup(entry[0]);
@@ -185,24 +185,24 @@ async function commitStaticSet(
     batch.push(entry);
     byGroup.set(group, batch);
   }
-  const sets = animations.filter((a) => a.method === "set" && a.targetSelector === selector);
+  const staticWrites = animations.filter((a) => isInstantHold(a) && a.targetSelector === selector);
   // Resolve every group's target BEFORE committing anything, and coalesce
-  // groups that land on the SAME set into one commit: the `sets` snapshot is
-  // captured once, so if two groups resolved to one legacy mixed set, a first
+  // groups that land on the SAME write into one commit: the snapshot is captured
+  // once, so if two groups resolved to one legacy mixed write, a first
   // commit could re-shape it server-side and leave the second chasing a stale
   // id (404 on legacy pre-split files).
-  const byTargetSet = new Map<GsapAnimation, [string, number | string][]>();
+  const byTargetWrite = new Map<GsapAnimation, [string, number | string][]>();
   const newSetBatches: [string, number | string][][] = [];
   for (const [group, batch] of byGroup) {
-    const existingSet = findGroupOwningSet(sets, group);
-    if (existingSet) {
-      byTargetSet.set(existingSet, [...(byTargetSet.get(existingSet) ?? []), ...batch]);
+    const existingWrite = findGroupOwningStaticWrite(staticWrites, group);
+    if (existingWrite) {
+      byTargetWrite.set(existingWrite, [...(byTargetWrite.get(existingWrite) ?? []), ...batch]);
     } else {
       newSetBatches.push(batch);
     }
   }
-  for (const [targetSet, batch] of byTargetSet) {
-    await commitSetProps(selection, targetSet, batch, selector, animations, commit);
+  for (const [targetWrite, batch] of byTargetWrite) {
+    await commitSetProps(selection, targetWrite, batch, selector, animations, commit);
   }
   // Fresh adds don't reshape existing sets, so their ids can't go stale.
   for (const batch of newSetBatches) {
@@ -211,14 +211,19 @@ async function commitStaticSet(
 }
 
 /**
- * The set that owns a property group: one already dedicated to the group wins;
- * else a mixed set that already carries a property of the group (merging
- * same-group values there beats spawning a second writer for the channel).
+ * The static write that owns a property group: one already dedicated to the
+ * group wins; else a mixed write that already carries a property of the group
+ * (merging same-group values there beats spawning a second writer for the channel).
  */
-function findGroupOwningSet(sets: GsapAnimation[], group: string): GsapAnimation | undefined {
+function findGroupOwningStaticWrite(
+  staticWrites: GsapAnimation[],
+  group: string,
+): GsapAnimation | undefined {
   return (
-    sets.find((a) => a.propertyGroup === group) ??
-    sets.find((a) => Object.keys(a.properties).some((k) => classifyPropertyGroup(k) === group))
+    staticWrites.find((a) => a.propertyGroup === group) ??
+    staticWrites.find((a) =>
+      Object.keys(a.properties).some((k) => classifyPropertyGroup(k) === group),
+    )
   );
 }
 
@@ -445,8 +450,8 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
         }
 
         // Existing static hold on a NON-animated element — merge the props into the
-        // `set` in place (maybeAutoKeyframeSet no-ops when nothing else is keyframed).
-        if (anim?.method === "set") {
+        // same write (maybeAutoKeyframeSet no-ops when nothing else is keyframed).
+        if (anim && isInstantHold(anim)) {
           await commitSetProps(
             selection,
             anim,

package/src/hooks/useAppHotkeys.ts

@@ -4,7 +4,7 @@ import type { TimelineElement } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import type { LeftSidebarHandle } from "../components/sidebar/LeftSidebar";
 import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
-import { shouldHandleTimelineToggleHotkey, isEditableTarget } from "../utils/timelineDiscovery";
+import { isEditableTarget } from "../utils/timelineDiscovery";
 import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
 import { canSplitElement } from "../utils/timelineElementSplit";
 import { STUDIO_RAZOR_TOOL_ENABLED } from "../components/editor/manualEditingAvailability";
@@ -81,6 +81,8 @@ interface HistoryResult {
   reason?: string;
   label?: string;
   paths?: string[];
+  /** Per-file restored/previous content, used to soft-apply the preview. */
+  files?: Record<string, { previous: string; restored: string }>;
 }
 interface HistoryFileCallbacks {
   readFile: (path: string) => Promise<string>;
@@ -96,7 +98,6 @@ interface EditHistoryHandle {
 }
 
 interface UseAppHotkeysParams {
-  toggleTimelineVisibility: () => void;
   handleTimelineElementDelete: (element: TimelineElement) => Promise<void>;
   handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void>;
   handleDomEditElementDelete: (selection: DomEditSelection) => Promise<void>;
@@ -108,7 +109,10 @@ interface UseAppHotkeysParams {
   writeProjectFile: (path: string, content: string) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   showToast: (message: string, tone?: "error" | "info") => void;
-  syncHistoryPreviewAfterApply: (paths: string[] | undefined) => Promise<void>;
+  syncHistoryPreviewAfterApply: (restore: {
+    paths?: string[];
+    files?: Record<string, { previous: string; restored: string }>;
+  }) => Promise<void>;
   waitForPendingDomEditSaves: () => Promise<void>;
   leftSidebarRef: React.RefObject<LeftSidebarHandle | null>;
   handleCopy: () => boolean;
@@ -135,7 +139,6 @@ interface UseAppHotkeysParams {
 // ── Extracted keydown dispatch (pure function, no hooks) ──
 
 interface HotkeyCallbacks {
-  toggleTimelineVisibility: () => void;
   handleTimelineElementDelete: (element: TimelineElement) => Promise<void>;
   handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void>;
   handleDomEditElementDelete: (selection: DomEditSelection) => Promise<void>;
@@ -291,9 +294,14 @@ function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks
         return;
       }
     }
-    const { selectedElementId, elements } = usePlayerStore.getState();
-    if (selectedElementId) {
-      const el = elements.find((e) => (e.key ?? e.id) === selectedElementId);
+    // Delete acts on the primary selection OR the marquee multi-selection —
+    // the delete handler expands a clip that is part of the multi-selection
+    // into an atomic delete of the whole selection (single undo).
+    const { selectedElementId, selectedElementIds, elements } = usePlayerStore.getState();
+    const selectionKeys = new Set(selectedElementIds);
+    if (selectedElementId) selectionKeys.add(selectedElementId);
+    if (selectionKeys.size > 0) {
+      const el = elements.find((e) => selectionKeys.has(e.key ?? e.id));
       if (el) {
         event.preventDefault();
         void cb.handleTimelineElementDelete(el);
@@ -317,7 +325,6 @@ function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks
 // ── Hook ──
 
 export function useAppHotkeys({
-  toggleTimelineVisibility,
   handleTimelineElementDelete,
   handleTimelineElementSplit,
   handleDomEditElementDelete,
@@ -346,15 +353,6 @@ export function useAppHotkeys({
   const previewHotkeyWindowRef = useRef<Window | null>(null);
   const previewHistoryCleanupRef = useRef<(() => void) | null>(null);
 
-  const handleTimelineToggleHotkey = useCallback(
-    (event: KeyboardEvent) => {
-      if (!shouldHandleTimelineToggleHotkey(event)) return;
-      event.preventDefault();
-      toggleTimelineVisibility();
-    },
-    [toggleTimelineVisibility],
-  );
-
   // ── Undo / Redo ──
 
   const readHistoryFile = useCallback(
@@ -397,7 +395,7 @@ export function useAppHotkeys({
         if (activeCompPath && result.paths?.includes(activeCompPath)) {
           forceReloadSdkSession?.();
         }
-        await syncHistoryPreviewAfterApply(result.paths);
+        await syncHistoryPreviewAfterApply({ paths: result.paths, files: result.files });
         showToast(`${direction === "undo" ? "Undid" : "Redid"} ${result.label}`, "info");
       }
     },
@@ -421,7 +419,6 @@ export function useAppHotkeys({
 
   const cbRef = useRef<HotkeyCallbacks>(null!);
   cbRef.current = {
-    toggleTimelineVisibility,
     handleTimelineElementDelete,
     handleTimelineElementSplit,
     handleDomEditElementDelete,
@@ -444,11 +441,6 @@ export function useAppHotkeys({
 
   const handleAppKeyDown = useCallback((event: KeyboardEvent) => {
     const cb = cbRef.current;
-    if (shouldHandleTimelineToggleHotkey(event)) {
-      event.preventDefault();
-      cb.toggleTimelineVisibility();
-      return;
-    }
     const key = event.key.toLowerCase();
     if (event.metaKey || event.ctrlKey) {
       dispatchModifierKey(event, key, cb);
@@ -537,6 +529,5 @@ export function useAppHotkeys({
     handleRedo,
     syncPreviewTimelineHotkey,
     syncPreviewHistoryHotkey,
-    handleTimelineToggleHotkey,
   };
 }

package/src/hooks/useBlockHandlers.ts

@@ -2,7 +2,7 @@
  * Block drop/add handlers for the Studio.
  * Extracted from App.tsx to keep file sizes under the 600-line limit.
  */
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
 import { addBlockToProject } from "../utils/blockInstaller";
@@ -83,17 +83,41 @@ export function useBlockHandlers({
     ],
   );
 
+  // Block installs hit the server and end in a full preview reload; without a
+  // guard, repeat drops while one is in flight stack duplicate installs.
+  const installingBlockRef = useRef(false);
+  const runBlockInstall = useCallback(
+    async <T>(blockName: string, install: () => Promise<T>): Promise<T | null> => {
+      if (installingBlockRef.current) {
+        blockCtx.showToast("A block is already installing — one moment…", "info");
+        return null;
+      }
+      installingBlockRef.current = true;
+      blockCtx.showToast(`Adding ${blockName}…`, "info");
+      try {
+        return await install();
+      } finally {
+        installingBlockRef.current = false;
+      }
+    },
+    [blockCtx],
+  );
+
   const handleAddBlock = useCallback(
     (blockName: string) => {
       if (!projectId) return;
+      // fallow-ignore-next-line complexity
       void (async () => {
-        const result = await addBlockToProject({
-          projectId,
-          blockName,
-          ...blockCtx,
-          previewIframe: previewIframeRef.current,
-          currentTime: usePlayerStore.getState().currentTime,
-        });
+        const result = await runBlockInstall(blockName, () =>
+          addBlockToProject({
+            projectId,
+            blockName,
+            ...blockCtx,
+            previewIframe: previewIframeRef.current,
+            currentTime: usePlayerStore.getState().currentTime,
+          }),
+        );
+        if (result === null) return;
         const params = result?.block.type === "hyperframes:block" ? result.block.params : undefined;
         if (params?.length) {
           setActiveBlockParams({
@@ -107,37 +131,41 @@ export function useBlockHandlers({
         }
       })();
     },
-    [projectId, blockCtx, previewIframeRef, setRightCollapsed, setRightPanelTab],
+    [projectId, blockCtx, previewIframeRef, runBlockInstall, setRightCollapsed, setRightPanelTab],
   );
 
   const handleTimelineBlockDrop = useCallback(
     (blockName: string, placement: { start: number; track: number }) => {
       if (!projectId) return;
-      void addBlockToProject({
-        projectId,
-        blockName,
-        placement,
-        ...blockCtx,
-        previewIframe: previewIframeRef.current,
-        currentTime: usePlayerStore.getState().currentTime,
-      });
+      void runBlockInstall(blockName, () =>
+        addBlockToProject({
+          projectId,
+          blockName,
+          placement,
+          ...blockCtx,
+          previewIframe: previewIframeRef.current,
+          currentTime: usePlayerStore.getState().currentTime,
+        }),
+      );
     },
-    [projectId, blockCtx, previewIframeRef],
+    [projectId, blockCtx, previewIframeRef, runBlockInstall],
   );
 
   const handlePreviewBlockDrop = useCallback(
     (blockName: string, position: { left: number; top: number }) => {
       if (!projectId) return;
-      void addBlockToProject({
-        projectId,
-        blockName,
-        visualPosition: position,
-        ...blockCtx,
-        previewIframe: previewIframeRef.current,
-        currentTime: usePlayerStore.getState().currentTime,
-      });
+      void runBlockInstall(blockName, () =>
+        addBlockToProject({
+          projectId,
+          blockName,
+          visualPosition: position,
+          ...blockCtx,
+          previewIframe: previewIframeRef.current,
+          currentTime: usePlayerStore.getState().currentTime,
+        }),
+      );
     },
-    [projectId, blockCtx, previewIframeRef],
+    [projectId, blockCtx, previewIframeRef, runBlockInstall],
   );
 
   return {

package/src/hooks/useCaptionDetection.ts

@@ -1,5 +1,6 @@
 import { useEffect } from "react";
 import { useCaptionStore } from "../captions/store";
+import { acceptStudioRuntimeMessage } from "../player/lib/runtimeProtocol";
 import { useCaptionSync } from "../captions/hooks/useCaptionSync";
 import { parseCaptionComposition } from "../captions/parser";
 
@@ -111,6 +112,7 @@ export function useCaptionDetection({
     const handleMessage = (e: MessageEvent) => {
       const data = e.data;
       if (data?.source === "hf-preview" && (data?.type === "state" || data?.type === "timeline")) {
+        if (!acceptStudioRuntimeMessage(data)) return;
         tryActivateCaptions();
       }
     };

package/src/hooks/useCompositionDimensions.ts

@@ -1,6 +1,33 @@
 import { useState } from "react";
 import { useMountEffect } from "./useMountEffect";
 import type { CompositionDimensions } from "../components/renders/RenderQueue";
+import { acceptStudioRuntimeMessage } from "../player/lib/runtimeProtocol";
+
+function readCompositionSizeMessage(data: unknown): CompositionDimensions | null {
+  if (!isStageSizeMessage(data)) return null;
+  const message = data;
+  if (!acceptStudioRuntimeMessage(message)) return null;
+  return readPositiveDimensions(message.width, message.height);
+}
+
+function isStageSizeMessage(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object") return false;
+  if (value === null) return false;
+  const message = value as Record<string, unknown>;
+  return message.source === "hf-preview" && message.type === "stage-size";
+}
+
+function readPositiveNumber(value: unknown): number | null {
+  if (typeof value !== "number") return null;
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+function readPositiveDimensions(width: unknown, height: unknown): CompositionDimensions | null {
+  const parsedWidth = readPositiveNumber(width);
+  const parsedHeight = readPositiveNumber(height);
+  if (parsedWidth === null || parsedHeight === null) return null;
+  return { width: parsedWidth, height: parsedHeight };
+}
 
 export function useCompositionDimensions() {
   const [compositionDimensions, setCompositionDimensions] = useState<CompositionDimensions | null>(
@@ -9,12 +36,12 @@ export function useCompositionDimensions() {
 
   useMountEffect(() => {
     const handleMessage = (e: MessageEvent) => {
-      const data = e.data;
-      if (data?.source !== "hf-preview" || data?.type !== "stage-size") return;
-      const { width, height } = data as { width: number; height: number };
-      if (!(width > 0) || !(height > 0)) return;
+      const dimensions = readCompositionSizeMessage(e.data);
+      if (!dimensions) return;
       setCompositionDimensions((prev) =>
-        prev && prev.width === width && prev.height === height ? prev : { width, height },
+        prev && prev.width === dimensions.width && prev.height === dimensions.height
+          ? prev
+          : dimensions,
       );
     };
     window.addEventListener("message", handleMessage);

package/src/hooks/useContextMenuDismiss.ts

@@ -1,26 +1,50 @@
 import { useCallback, useEffect, useRef, type RefObject } from "react";
 
 /**
- * Shared dismiss logic for context menus: closes on outside click or Escape.
- * Returns a ref to attach to the menu container element.
+ * Shared dismiss logic for context menus: closes on ANY pointerdown outside the
+ * menu (mouse, pen, or touch), or Escape.
+ *
+ * Two failure modes this guards against, both seen in the canvas editor:
+ *
+ * 1. The menu lives inside DomEditOverlay, whose own pointer handlers call
+ *    `event.stopPropagation()` on several branches (marquee start, shift-select).
+ *    A bubble-phase `mousedown`/`pointerdown` listener on `document` never fires
+ *    for those events — the overlay eats them first — so the menu stayed open.
+ *    Listening in the CAPTURE phase runs this dismiss BEFORE any bubble-phase
+ *    stopPropagation, so an outside press always closes the menu.
+ *
+ * 2. `mousedown` alone misses pointer/touch-only gestures. `pointerdown` is the
+ *    superset (fires for mouse, pen, and touch) and is exactly the event the
+ *    overlay itself acts on, so hooking it here dismisses on the same press that
+ *    starts a canvas gesture — no second click required.
  */
 export function useContextMenuDismiss(onClose: () => void): RefObject<HTMLDivElement | null> {
   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;
+    (e: PointerEvent | MouseEvent | KeyboardEvent) => {
+      if (e instanceof KeyboardEvent) {
+        if (e.key === "Escape") onClose();
+        return;
+      }
+      // Any press inside the menu is a menu interaction — leave it open (the
+      // item's own handler will close it after acting).
+      if (menuRef.current?.contains(e.target as Node)) return;
       onClose();
     },
     [onClose],
   );
 
   useEffect(() => {
-    document.addEventListener("mousedown", dismiss);
+    // Capture phase so overlay/iframe-side handlers that stopPropagation on the
+    // bubble phase can't swallow the dismiss. `pointerdown` covers mouse + touch
+    // + pen; keep `mousedown` too for any synthetic-mouse path that skips it.
+    document.addEventListener("pointerdown", dismiss, true);
+    document.addEventListener("mousedown", dismiss, true);
     document.addEventListener("keydown", dismiss);
     return () => {
-      document.removeEventListener("mousedown", dismiss);
+      document.removeEventListener("pointerdown", dismiss, true);
+      document.removeEventListener("mousedown", dismiss, true);
       document.removeEventListener("keydown", dismiss);
     };
   }, [dismiss]);