@hyperframes/studio 0.7.46 → 0.7.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.46",
+  "version": "0.7.47",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.46",
-    "@hyperframes/player": "0.7.46",
-    "@hyperframes/parsers": "0.7.46",
-    "@hyperframes/sdk": "0.7.46",
-    "@hyperframes/studio-server": "0.7.46"
+    "@hyperframes/player": "0.7.47",
+    "@hyperframes/core": "0.7.47",
+    "@hyperframes/studio-server": "0.7.47",
+    "@hyperframes/sdk": "0.7.47",
+    "@hyperframes/parsers": "0.7.47"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.46"
+    "@hyperframes/producer": "0.7.47"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -11,15 +11,17 @@ import { usePanelLayout } from "./hooks/usePanelLayout";
 import { useFileManager } from "./hooks/useFileManager";
 import { usePreviewPersistence } from "./hooks/usePreviewPersistence";
 import { useTimelineEditing } from "./hooks/useTimelineEditing";
+import type { TimelineZIndexReorderCommit } from "./hooks/useTimelineEditingTypes";
 import type { BlockPreviewInfo } from "./components/sidebar/BlocksTab";
 import { useDomEditSession } from "./hooks/useDomEditSession";
-import { useSdkSession } from "./hooks/useSdkSession";
 import { useSdkSelectionSync } from "./hooks/useSdkSelectionSync";
+import { useStudioSdkSessions } from "./hooks/useStudioSdkSessions";
+import { usePreviewDocumentVersion } from "./hooks/usePreviewDocumentVersion";
 import { useBlockHandlers } from "./hooks/useBlockHandlers";
 import { useAppHotkeys } from "./hooks/useAppHotkeys";
 import { useClipboard } from "./hooks/useClipboard";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "./utils/studioUiPreferences";
-import { selectedKeyframePercentagesForElement } from "./utils/keyframeSelection";
+import { deleteSelectedKeyframes } from "./hooks/timelineEditingHelpers";
 import { useCaptionDetection } from "./hooks/useCaptionDetection";
 import { useRenderClipContent } from "./hooks/useRenderClipContent";
 import { useConsoleErrorCapture } from "./hooks/useConsoleErrorCapture";
@@ -54,6 +56,7 @@ import { useServerConnection } from "./hooks/useServerConnection";
 import {
   normalizeStudioCompositionPath,
   readStudioUrlStateFromWindow,
+  resolveMasterCompositionPath,
 } from "./utils/studioUrlState";
 import { trackStudioSessionStart } from "./telemetry/events";
 import { hasFiredSessionStart, markSessionStartFired } from "./telemetry/config";
@@ -80,7 +83,7 @@ export function StudioApp() {
   const [previewIframe, setPreviewIframe] = useState<HTMLIFrameElement | null>(null);
   const [compositionLoading, setCompositionLoading] = useState(true);
   const [refreshKey, setRefreshKey] = useState(0);
-  const [previewDocumentVersion, setPreviewDocumentVersion] = useState(0);
+  const [previewDocumentVersion, refreshPreviewDocumentVersion] = usePreviewDocumentVersion();
   const [blockPreview, setBlockPreview] = useState<BlockPreviewInfo | null>(null);
   const previewIframeRef = useRef<HTMLIFrameElement | null>(null);
   const activeCompPathRef = useRef(activeCompPath);
@@ -105,22 +108,6 @@ export function StudioApp() {
         : 0;
     return Math.max(timelineDuration, maxEnd);
   }, [timelineDuration, timelineElements]);
-  const refreshTimersRef = useRef<number[]>([]);
-  const refreshPreviewDocumentVersion = useCallback(() => {
-    for (const id of refreshTimersRef.current) clearTimeout(id);
-    refreshTimersRef.current = [];
-    setPreviewDocumentVersion((v) => v + 1);
-    refreshTimersRef.current.push(
-      window.setTimeout(() => setPreviewDocumentVersion((v) => v + 1), 80),
-      window.setTimeout(() => setPreviewDocumentVersion((v) => v + 1), 300),
-    );
-  }, []);
-  useEffect(
-    () => () => {
-      for (const id of refreshTimersRef.current) clearTimeout(id);
-    },
-    [],
-  );
   const [timelineVisible, setTimelineVisible] = useState(
     () =>
       initialUrlStateRef.current.timelineVisible ??
@@ -140,6 +127,7 @@ export function StudioApp() {
   });
   const editHistory = usePersistentEditHistory({ projectId });
   const domEditSaveTimestampRef = useRef(0);
+  const handleDomZIndexReorderCommitRef = useRef<TimelineZIndexReorderCommit | null>(null);
   const pendingTimelineEditPathRef = useRef(new Set<string>());
   const isGestureRecordingRef = useRef(false);
   const reloadPreview = useCallback(() => setRefreshKey((k) => k + 1), []);
@@ -150,7 +138,16 @@ export function StudioApp() {
     domEditSaveTimestampRef,
     setRefreshKey,
   });
-  const sdkHandle = useSdkSession(projectId, activeCompPath, domEditSaveTimestampRef);
+  const masterCompPath = useMemo(
+    () => resolveMasterCompositionPath(fileManager.fileTree),
+    [fileManager.fileTree],
+  );
+  const { sdkHandle, editFlowSdkSession } = useStudioSdkSessions(
+    projectId,
+    activeCompPath,
+    domEditSaveTimestampRef,
+    masterCompPath,
+  );
   useEffect(() => {
     if (activeCompPathHydrated) return;
     if (!fileManager.fileTreeLoaded) return;
@@ -186,8 +183,9 @@ export function StudioApp() {
     pendingTimelineEditPathRef,
     uploadProjectFiles: fileManager.uploadProjectFiles,
     isRecordingRef: isGestureRecordingRef,
-    sdkSession: sdkHandle.session,
+    sdkSession: editFlowSdkSession,
     forceReloadSdkSession: sdkHandle.forceReload,
+    handleDomZIndexReorderCommitRef,
   });
   const {
     activeBlockParams,
@@ -302,25 +300,18 @@ export function StudioApp() {
     openSourceForSelection: fileManager.openSourceForSelection,
     selectSidebarTab: sidebarTabRef.current.select,
     getSidebarTab: sidebarTabRef.current.get,
-    sdkSession: sdkHandle.session,
+    sdkSession: editFlowSdkSession,
     forceReloadSdkSession: sdkHandle.forceReload,
   });
   domEditSelectionBridgeRef.current = domEditSession.domEditSelection;
+  handleDomZIndexReorderCommitRef.current = domEditSession.handleDomZIndexReorderCommit;
   clearDomSelectionRef.current = domEditSession.clearDomSelection;
   handleDomEditElementDeleteRef.current = domEditSession.handleDomEditElementDelete;
   resetKeyframesRef.current = domEditSession.handleResetSelectedElementKeyframes;
   invalidateGsapCacheRef.current = domEditSession.invalidateGsapCache;
-  deleteSelectedKeyframesRef.current = () => {
-    const { selectedKeyframes, selectedElementId } = usePlayerStore.getState();
-    const a = domEditSession.selectedGsapAnimations.find((x) => x.keyframes);
-    if (!a) return;
-    // Only the active element's keyframes; a stale cross-element selection must not delete here.
-    for (const p of selectedKeyframePercentagesForElement(selectedKeyframes, selectedElementId)) {
-      domEditSession.handleGsapRemoveKeyframe(a.id, p);
-    }
-  };
+  deleteSelectedKeyframesRef.current = () => deleteSelectedKeyframes(domEditSession);
   useSdkSelectionSync(
-    sdkHandle.session,
+    editFlowSdkSession,
     domEditSession.domEditSelection,
     domEditSession.domEditGroupSelections,
   );
@@ -528,7 +519,10 @@ export function StudioApp() {
                       handleTimelineFileDrop={timelineEditing.handleTimelineFileDrop}
                       handleTimelineElementMove={timelineEditing.handleTimelineElementMove}
                       handleTimelineElementResize={timelineEditing.handleTimelineElementResize}
+                      handleTimelineGroupMove={timelineEditing.handleTimelineGroupMove}
+                      handleTimelineGroupResize={timelineEditing.handleTimelineGroupResize}
                       handleToggleTrackHidden={timelineEditing.handleToggleTrackHidden}
+                      handleToggleElementHidden={timelineEditing.handleToggleElementHidden}
                       handleBlockedTimelineEdit={timelineEditing.handleBlockedTimelineEdit}
                       handleTimelineElementSplit={timelineEditing.handleTimelineElementSplit}
                       handleRazorSplit={timelineEditing.handleRazorSplit}

package/src/components/DesignPanelPromoteProvider.tsx

@@ -0,0 +1,45 @@
+/**
+ * Wires the Design panel's promote-to-variable context. Promote/bind operates
+ * on the file the selected element actually lives in — a sub-composition file
+ * when you select an element inside an inlined sub-comp, not the host. So we
+ * open (and persist to) an SDK session keyed on `selection.sourceFile`, not the
+ * host `activeCompPath`. Declaring a variable therefore lands in the sub-comp's
+ * own file, making it a knob on that reusable frame everywhere it is used. When
+ * nothing is selected (or the element is top-level) the target is the active
+ * composition, so behavior there is unchanged.
+ */
+
+import type { ReactNode } from "react";
+import type { DomEditSelection } from "./editor/domEditingTypes";
+import { useSdkSession } from "../hooks/useSdkSession";
+import { useVariablesPersist, type UseVariablesPersistParams } from "../hooks/useVariablesPersist";
+import { VariablePromoteProvider } from "../contexts/VariablePromoteContext";
+
+/** Persist wiring minus the target — this provider derives the target from the selection. */
+type PersistDeps = Omit<UseVariablesPersistParams, "sdkSession" | "activeCompPath">;
+
+export function DesignPanelPromoteProvider({
+  selection,
+  projectId,
+  activeCompPath,
+  children,
+  ...persistDeps
+}: PersistDeps & {
+  selection: DomEditSelection | null;
+  projectId: string | null;
+  activeCompPath: string | null;
+  children: ReactNode;
+}) {
+  const targetPath = selection?.sourceFile || activeCompPath || "index.html";
+  const handle = useSdkSession(projectId, targetPath, persistDeps.domEditSaveTimestampRef);
+  const persist = useVariablesPersist({
+    ...persistDeps,
+    sdkSession: handle.session,
+    activeCompPath: targetPath,
+  });
+  return (
+    <VariablePromoteProvider session={handle.session} selection={selection} persist={persist}>
+      {children}
+    </VariablePromoteProvider>
+  );
+}

package/src/components/PanelTabButton.tsx

@@ -0,0 +1,31 @@
+import { Tooltip } from "./ui";
+
+/** Tab-bar button for the right inspector panel header. */
+export function PanelTabButton({
+  label,
+  tooltip,
+  active,
+  onClick,
+}: {
+  label: string;
+  tooltip: string;
+  active: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <Tooltip label={tooltip} side="bottom">
+      <button
+        type="button"
+        onClick={onClick}
+        aria-pressed={active}
+        className={`h-8 rounded-xl px-3 text-[11px] font-medium transition-colors active:scale-[0.98] ${
+          active
+            ? "bg-neutral-800 text-white"
+            : "text-neutral-500 hover:bg-neutral-800/70 hover:text-neutral-200"
+        }`}
+      >
+        {label}
+      </button>
+    </Tooltip>
+  );
+}

package/src/components/StudioPreviewArea.tsx

@@ -25,6 +25,15 @@ import { TimelineEditProvider } from "../contexts/TimelineEditContext";
 import type { BlockPreviewInfo } from "./sidebar/BlocksTab";
 import { readStudioUiPreferences } from "../utils/studioUiPreferences";
 import type { GestureRecordingState } from "./editor/GestureRecordControl";
+import { useTimelineSelectionPreviewSync } from "../hooks/useTimelineSelectionPreviewSync";
+import type {
+  TimelineGroupMoveChange,
+  TimelineGroupResizeChange,
+} from "../hooks/useTimelineGroupEditing";
+import {
+  formatTimelineAttributeNumber,
+  patchIframeDomTiming,
+} from "../hooks/timelineEditingHelpers";
 
 export interface StudioPreviewAreaProps {
   timelineToolbar: ReactNode;
@@ -58,7 +67,10 @@ export interface StudioPreviewAreaProps {
     element: TimelineElement,
     updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
   ) => Promise<void> | void;
+  handleTimelineGroupMove: (changes: TimelineGroupMoveChange[]) => Promise<void> | void;
+  handleTimelineGroupResize: (changes: TimelineGroupResizeChange[]) => Promise<void> | void;
   handleToggleTrackHidden: (track: number, hidden: boolean) => Promise<void> | void;
+  handleToggleElementHidden: (elementKey: string, hidden: boolean) => Promise<void> | void;
   handleBlockedTimelineEdit: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   handleRazorSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
@@ -84,7 +96,10 @@ export function StudioPreviewArea({
   handleTimelineFileDrop,
   handleTimelineElementMove,
   handleTimelineElementResize,
+  handleTimelineGroupMove,
+  handleTimelineGroupResize,
   handleToggleTrackHidden,
+  handleToggleElementHidden,
   handleBlockedTimelineEdit,
   handleTimelineElementSplit,
   handleRazorSplit,
@@ -146,6 +161,9 @@ export function StudioPreviewArea({
     buildDomSelectionForTimelineElement,
     applyMarqueeSelection,
   } = useDomEditActionsContext();
+  const selectedElementId = usePlayerStore((s) => s.selectedElementId);
+  const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
+  const timelineElements = usePlayerStore((s) => s.elements);
 
   // fallow-ignore-next-line complexity
   const [snapPrefs, setSnapPrefs] = useState(() => {
@@ -158,6 +176,18 @@ export function StudioPreviewArea({
     };
   });
 
+  useTimelineSelectionPreviewSync({
+    selectedElementId,
+    selectedElementIds,
+    timelineElements,
+    domEditSelection,
+    domEditGroupSelections,
+    activeCompPath,
+    buildDomSelectionForTimelineElement,
+    applyDomSelection,
+    applyMarqueeSelection,
+  });
+
   // Resolve a timeline-diamond callback's clip-% to the keyframe's anim id + its
   // tween-relative percentage (shared by the delete/move keyframe callbacks): the
   // diamond reports a clip-% but the script ops key on the tween-%. Prefers the
@@ -176,19 +206,56 @@ export function StudioPreviewArea({
     [domEditSelection?.id, selectedGsapAnimations],
   );
 
+  const handleTimelineGroupMovePreview = useCallback(
+    (changes: TimelineGroupMoveChange[]) => {
+      for (const change of changes) {
+        patchIframeDomTiming(previewIframeRef.current, change.element, [
+          ["data-start", formatTimelineAttributeNumber(change.start)],
+        ]);
+      }
+    },
+    [previewIframeRef],
+  );
+
+  const handleTimelineGroupResizePreview = useCallback(
+    (changes: TimelineGroupResizeChange[]) => {
+      for (const change of changes) {
+        const attrs: Array<[string, string]> = [
+          ["data-start", formatTimelineAttributeNumber(change.start)],
+          ["data-duration", formatTimelineAttributeNumber(change.duration)],
+        ];
+        if (change.playbackStart != null) {
+          attrs.push([
+            change.element.playbackStartAttr === "playback-start"
+              ? "data-playback-start"
+              : "data-media-start",
+            formatTimelineAttributeNumber(change.playbackStart),
+          ]);
+        }
+        patchIframeDomTiming(previewIframeRef.current, change.element, attrs);
+      }
+    },
+    [previewIframeRef],
+  );
+
   // fallow-ignore-next-line complexity
   const timelineEditCallbacks = useMemo(
     () => ({
       onMoveElement: handleTimelineElementMove,
       onResizeElement: handleTimelineElementResize,
+      onMoveElements: handleTimelineGroupMove,
+      onResizeElements: handleTimelineGroupResize,
+      onPreviewMoveElements: handleTimelineGroupMovePreview,
+      onPreviewResizeElements: handleTimelineGroupResizePreview,
       onToggleTrackHidden: handleToggleTrackHidden,
+      onToggleElementHidden: handleToggleElementHidden,
       onBlockedEditAttempt: handleBlockedTimelineEdit,
       onSplitElement: handleTimelineElementSplit,
       onRazorSplit: handleRazorSplit,
       onRazorSplitAll: handleRazorSplitAll,
       onDeleteAllKeyframes: () => {
         // Hold the element where it is (collapse keyframes to a static set) rather
-        // than deleting the whole animation — deleting strands a stale GSAP base
+        // than deleting the whole animation, deleting strands a stale GSAP base
         // that the next drag adds to, flinging the element off-screen.
         const anim = selectedGsapAnimations.find((a) => a.keyframes);
         if (!anim) return;
@@ -208,7 +275,7 @@ export function StudioPreviewArea({
       // absolute time (via the clip's timing basis) and let resolveKeyframeRetime
       // decide: a drop inside the tween window is a plain move (re-key tween-%); a
       // drop past the boundary (last keyframe past the end, first before the start)
-      // resizes the tween — position/duration grow so the dragged keyframe lands at
+      // resizes the tween, position/duration grow so the dragged keyframe lands at
       // the drop while every other keyframe keeps its absolute time (value+ease too).
       // fallow-ignore-next-line complexity
       onMoveKeyframe: (_elId: string, fromClipPct: number, toClipPct: number) => {
@@ -281,7 +348,12 @@ export function StudioPreviewArea({
     [
       handleTimelineElementMove,
       handleTimelineElementResize,
+      handleTimelineGroupMove,
+      handleTimelineGroupMovePreview,
+      handleTimelineGroupResize,
+      handleTimelineGroupResizePreview,
       handleToggleTrackHidden,
+      handleToggleElementHidden,
       handleBlockedTimelineEdit,
       handleTimelineElementSplit,
       handleRazorSplit,
@@ -323,7 +395,7 @@ export function StudioPreviewArea({
             onCompositionLoadingChange={setCompositionLoading}
             onCompositionChange={(compPath) => {
               // Sync activeCompPath when user drills down via timeline double-click
-              // or navigates back via breadcrumb — keeps sidebar + thumbnails in sync.
+              // or navigates back via breadcrumb, keeps sidebar + thumbnails in sync.
               // Guard against no-op updates to prevent circular refresh cascades
               // between activeCompPath → compositionStack → onCompositionChange.
               if (compPath !== activeCompPath) {