@hyperframes/studio 0.6.97 → 0.6.98

package/src/contexts/StudioContext.tsx

@@ -2,18 +2,12 @@ import { createContext, useContext, useMemo, type ReactNode } from "react";
 import type { TimelineElement } from "../player";
 import type { CompositionDimensions } from "../components/renders/RenderQueue";
 
-export interface StudioContextValue {
+export interface StudioShellValue {
   projectId: string;
   activeCompPath: string | null;
   setActiveCompPath: (path: string | null) => void;
   showToast: (message: string, tone?: "error" | "info") => void;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
-  captionEditMode: boolean;
-  compositionLoading: boolean;
-  refreshKey: number;
-  setRefreshKey: React.Dispatch<React.SetStateAction<number>>;
-  timelineElements: TimelineElement[];
-  isPlaying: boolean;
   editHistory: {
     canUndo: boolean;
     canRedo: boolean;
@@ -32,24 +26,49 @@ export interface StudioContextValue {
   compositionDimensions: CompositionDimensions | null;
   waitForPendingDomEditSaves: () => Promise<void>;
   handlePreviewIframeRef: (iframe: HTMLIFrameElement | null) => void;
-  refreshPreviewDocumentVersion: () => void;
   timelineVisible: boolean;
   toggleTimelineVisibility: () => void;
 }
 
-const StudioContext = createContext<StudioContextValue | null>(null);
+export interface StudioPlaybackValue {
+  captionEditMode: boolean;
+  compositionLoading: boolean;
+  refreshKey: number;
+  setRefreshKey: React.Dispatch<React.SetStateAction<number>>;
+  timelineElements: TimelineElement[];
+  isPlaying: boolean;
+  refreshPreviewDocumentVersion: () => void;
+}
+
+export type StudioContextValue = StudioShellValue & StudioPlaybackValue;
 
-export function useStudioContext(): StudioContextValue {
-  const ctx = useContext(StudioContext);
-  if (!ctx) throw new Error("useStudioContext must be used within StudioProvider");
+const StudioShellContext = createContext<StudioShellValue | null>(null);
+const StudioPlaybackContext = createContext<StudioPlaybackValue | null>(null);
+
+export function useStudioShellContext(): StudioShellValue {
+  const ctx = useContext(StudioShellContext);
+  if (!ctx) throw new Error("useStudioShellContext must be used within StudioShellProvider");
   return ctx;
 }
 
-export function StudioProvider({
+export function useStudioPlaybackContext(): StudioPlaybackValue {
+  const ctx = useContext(StudioPlaybackContext);
+  if (!ctx) throw new Error("useStudioPlaybackContext must be used within StudioPlaybackProvider");
+  return ctx;
+}
+
+/** @deprecated Use useStudioShellContext and/or useStudioPlaybackContext instead. */
+export function useStudioContext(): StudioContextValue {
+  const shell = useStudioShellContext();
+  const playback = useStudioPlaybackContext();
+  return useMemo(() => ({ ...shell, ...playback }), [shell, playback]);
+}
+
+export function StudioShellProvider({
   value,
   children,
 }: {
-  value: StudioContextValue;
+  value: StudioShellValue;
   children: ReactNode;
 }) {
   const {
@@ -58,12 +77,6 @@ export function StudioProvider({
     setActiveCompPath,
     showToast,
     previewIframeRef,
-    captionEditMode,
-    compositionLoading,
-    refreshKey,
-    setRefreshKey,
-    timelineElements,
-    isPlaying,
     editHistory,
     handleUndo,
     handleRedo,
@@ -71,24 +84,17 @@ export function StudioProvider({
     compositionDimensions,
     waitForPendingDomEditSaves,
     handlePreviewIframeRef,
-    refreshPreviewDocumentVersion,
     timelineVisible,
     toggleTimelineVisibility,
   } = value;
 
-  const stable = useMemo<StudioContextValue>(
+  const stable = useMemo<StudioShellValue>(
     () => ({
       projectId,
       activeCompPath,
       setActiveCompPath,
       showToast,
       previewIframeRef,
-      captionEditMode,
-      compositionLoading,
-      refreshKey,
-      setRefreshKey,
-      timelineElements,
-      isPlaying,
       editHistory,
       handleUndo,
       handleRedo,
@@ -96,36 +102,80 @@ export function StudioProvider({
       compositionDimensions,
       waitForPendingDomEditSaves,
       handlePreviewIframeRef,
-      refreshPreviewDocumentVersion,
       timelineVisible,
       toggleTimelineVisibility,
     }),
-    // Representative subset of deps that actually change — stable callbacks
-    // (showToast, setActiveCompPath, etc.) are included for correctness but
-    // won't trigger re-renders on their own.
     [
       projectId,
       activeCompPath,
-      captionEditMode,
-      compositionLoading,
-      refreshKey,
-      isPlaying,
       compositionDimensions,
       timelineVisible,
       editHistory,
-      timelineElements,
       renderQueue,
       setActiveCompPath,
       showToast,
       previewIframeRef,
-      setRefreshKey,
       handleUndo,
       handleRedo,
       waitForPendingDomEditSaves,
       handlePreviewIframeRef,
-      refreshPreviewDocumentVersion,
       toggleTimelineVisibility,
     ],
   );
-  return <StudioContext value={stable}>{children}</StudioContext>;
+  return <StudioShellContext value={stable}>{children}</StudioShellContext>;
+}
+
+export function StudioPlaybackProvider({
+  value,
+  children,
+}: {
+  value: StudioPlaybackValue;
+  children: ReactNode;
+}) {
+  const {
+    captionEditMode,
+    compositionLoading,
+    refreshKey,
+    setRefreshKey,
+    timelineElements,
+    isPlaying,
+    refreshPreviewDocumentVersion,
+  } = value;
+
+  const stable = useMemo<StudioPlaybackValue>(
+    () => ({
+      captionEditMode,
+      compositionLoading,
+      refreshKey,
+      setRefreshKey,
+      timelineElements,
+      isPlaying,
+      refreshPreviewDocumentVersion,
+    }),
+    [
+      captionEditMode,
+      compositionLoading,
+      refreshKey,
+      timelineElements,
+      isPlaying,
+      setRefreshKey,
+      refreshPreviewDocumentVersion,
+    ],
+  );
+  return <StudioPlaybackContext value={stable}>{children}</StudioPlaybackContext>;
+}
+
+/** @deprecated Use StudioShellProvider and StudioPlaybackProvider instead. */
+export function StudioProvider({
+  value,
+  children,
+}: {
+  value: StudioContextValue;
+  children: ReactNode;
+}) {
+  return (
+    <StudioShellProvider value={value}>
+      <StudioPlaybackProvider value={value}>{children}</StudioPlaybackProvider>
+    </StudioShellProvider>
+  );
 }

package/src/contexts/TimelineEditContext.tsx

@@ -0,0 +1,47 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import type { TimelineEditCallbacks } from "../player/components/timelineCallbacks";
+
+const TimelineEditContext = createContext<TimelineEditCallbacks | null>(null);
+
+export function useTimelineEditContext(): TimelineEditCallbacks {
+  const ctx = useContext(TimelineEditContext);
+  if (!ctx) throw new Error("useTimelineEditContext must be used within TimelineEditProvider");
+  return ctx;
+}
+
+/**
+ * Optional access — returns an empty object when outside a provider.
+ * Useful in components that can render both inside and outside the NLE.
+ */
+export function useTimelineEditContextOptional(): TimelineEditCallbacks {
+  return useContext(TimelineEditContext) ?? {};
+}
+
+export function TimelineEditProvider({
+  value,
+  children,
+}: {
+  value: TimelineEditCallbacks;
+  children: ReactNode;
+}) {
+  const memoized = useMemo(
+    () => value,
+    // Each callback is a stable reference from the parent — memoize the bag
+    // so consumers don't re-render when unrelated parent state changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      value.onMoveElement,
+      value.onResizeElement,
+      value.onBlockedEditAttempt,
+      value.onSplitElement,
+      value.onRazorSplit,
+      value.onRazorSplitAll,
+      value.onDeleteKeyframe,
+      value.onDeleteAllKeyframes,
+      value.onChangeKeyframeEase,
+      value.onMoveKeyframe,
+      value.onToggleKeyframeAtPlayhead,
+    ],
+  );
+  return <TimelineEditContext.Provider value={memoized}>{children}</TimelineEditContext.Provider>;
+}

package/src/hooks/domEditCommitTypes.ts

@@ -0,0 +1,14 @@
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { PatchOperation } from "../utils/sourcePatcher";
+
+export type PersistDomEditOperations = (
+  selection: DomEditSelection,
+  operations: PatchOperation[],
+  options?: {
+    label?: string;
+    coalesceKey?: string;
+    skipRefresh?: boolean;
+    prepareContent?: (html: string, sourceFile: string) => string;
+    shouldSave?: () => boolean;
+  },
+) => Promise<void>;

package/src/hooks/gsapDragCommit.ts

@@ -6,11 +6,9 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeKeyframes";
-import {
-  absoluteToPercentage,
-  resolveTweenStart,
-  resolveTweenDuration,
-} from "../utils/globalTimeCompiler";
+import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
+import { roundTo3 } from "../utils/rounding";
+import { computeElementPercentage } from "./gsapShared";
 export interface GsapDragCommitCallbacks {
   commitMutation: (
     selection: DomEditSelection,
@@ -26,25 +24,12 @@ export interface GsapDragCommitCallbacks {
   fetchAnimations?: () => Promise<GsapAnimation[]>;
 }
 
-// ── Percentage computation ─────────────────────────────────────────────────
-
+// Re-export for backward compatibility with existing imports.
 export function computeCurrentPercentage(
   selection: DomEditSelection,
   animation?: GsapAnimation,
 ): number {
-  const currentTime = usePlayerStore.getState().currentTime;
-  if (animation) {
-    const start = resolveTweenStart(animation);
-    const duration = resolveTweenDuration(animation);
-    if (start !== null) {
-      return absoluteToPercentage(currentTime, start, duration);
-    }
-  }
-  const elStart = Number.parseFloat(selection.dataAttributes?.start ?? "0") || 0;
-  const elDuration = Number.parseFloat(selection.dataAttributes?.duration ?? "1") || 1;
-  return elDuration > 0
-    ? Math.max(0, Math.min(100, Math.round(((currentTime - elStart) / elDuration) * 1000) / 10))
-    : 0;
+  return computeElementPercentage(usePlayerStore.getState().currentTime, selection, animation);
 }
 
 // ── Dynamic keyframe materialization ──────────────────────────────────────
@@ -133,8 +118,8 @@ async function extendTweenAndAddKeyframe(
       type: "replace-with-keyframes",
       animationId: anim.id,
       targetSelector: anim.targetSelector,
-      position: Math.round(newStart * 1000) / 1000,
-      duration: Math.round(newDuration * 1000) / 1000,
+      position: roundTo3(newStart),
+      duration: roundTo3(newDuration),
       keyframes: remappedKfs,
     },
     { label: `Move layer (extended keyframe)`, softReload: true, beforeReload },
@@ -330,8 +315,8 @@ export async function commitGsapPositionFromDrag(
         {
           type: "add-with-keyframes",
           targetSelector: anim.targetSelector,
-          position: Math.round(newStart * 1000) / 1000,
-          duration: Math.round(newDuration * 1000) / 1000,
+          position: roundTo3(newStart),
+          duration: roundTo3(newDuration),
           keyframes,
         },
         { label: "Move layer (from extended)", softReload: true, beforeReload: restoreOffset },

package/src/hooks/gsapKeyframeCacheHelpers.ts

@@ -4,6 +4,7 @@
  */
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore, type KeyframeCacheEntry } from "../player/store/playerStore";
+import { toAbsoluteTime } from "./gsapShared";
 
 export function updateKeyframeCacheFromParsed(
   animations: GsapAnimation[],
@@ -29,7 +30,7 @@ export function updateKeyframeCacheFromParsed(
     const elStart = timelineEl?.start ?? 0;
     const elDuration = timelineEl?.duration ?? 1;
     const clipKeyframes = anim.keyframes.keyframes.map((kf) => {
-      const absTime = tweenPos + (kf.percentage / 100) * tweenDur;
+      const absTime = toAbsoluteTime(tweenPos, tweenDur, kf.percentage);
       const clipPct =
         elDuration > 0 ? Math.round(((absTime - elStart) / elDuration) * 1000) / 10 : kf.percentage;
       return {

package/src/hooks/gsapKeyframeCommit.ts

@@ -1,18 +1,8 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { absoluteToPercentageForAnimation, findTweenAtTime } from "../utils/globalTimeCompiler";
-
-const PROPERTY_DEFAULTS: Record<string, number> = {
-  opacity: 1,
-  x: 0,
-  y: 0,
-  scale: 1,
-  scaleX: 1,
-  scaleY: 1,
-  rotation: 0,
-  width: 100,
-  height: 100,
-};
+import { PROPERTY_DEFAULTS, selectorFromSelection } from "./gsapShared";
+import { roundToCenti } from "../utils/rounding";
 
 type CommitFn = (
   selection: DomEditSelection,
@@ -32,7 +22,7 @@ export async function commitKeyframeAtTimeImpl(
   properties: Record<string, number | string>,
   commitMutation: CommitFn,
 ): Promise<void> {
-  const selector = selection.id ? `#${selection.id}` : selection.selector;
+  const selector = selectorFromSelection(selection);
   if (!selector) return;
 
   const tween = findTweenAtTime(absoluteTime, animations, selector);
@@ -64,7 +54,7 @@ export async function commitKeyframeAtTimeImpl(
         backfillDefaults,
       },
       {
-        label: `Add keyframe at ${Math.round(absoluteTime * 100) / 100}s`,
+        label: `Add keyframe at ${roundToCenti(absoluteTime)}s`,
         coalesceKey: `keyframe:${tween.id}:${pct}`,
         softReload: true,
       },
@@ -84,7 +74,7 @@ export async function commitKeyframeAtTimeImpl(
         ],
       },
       {
-        label: `New animation at ${Math.round(absoluteTime * 100) / 100}s`,
+        label: `New animation at ${roundToCenti(absoluteTime)}s`,
         softReload: true,
       },
     );

package/src/hooks/gsapRuntimeBridge.ts

@@ -20,37 +20,20 @@ import {
 } from "./gsapDragCommit";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
 import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
+import { getIframeGsap, queryIframeElement, selectorFromSelection } from "./gsapShared";
+import { roundTo3 } from "../utils/rounding";
 
 // ── Runtime reads ──────────────────────────────────────────────────────────
 
-interface IframeGsap {
-  getProperty: (el: Element, prop: string) => number;
-}
-
 // fallow-ignore-next-line complexity
 function readGsapPositionFromIframe(
   iframe: HTMLIFrameElement | null,
   elementSelector: string,
 ): { x: number; y: number } | null {
-  if (!iframe?.contentWindow) return null;
-
-  let gsap: IframeGsap | undefined;
-  try {
-    gsap = (iframe.contentWindow as unknown as { gsap?: IframeGsap }).gsap;
-  } catch {
-    return null;
-  }
-  if (!gsap?.getProperty) return null;
-
-  let doc: Document | null = null;
-  try {
-    doc = iframe.contentDocument;
-  } catch {
-    return null;
-  }
-  if (!doc) return null;
+  const gsap = getIframeGsap(iframe);
+  if (!gsap) return null;
 
-  const element = doc.querySelector(elementSelector);
+  const element = queryIframeElement(iframe, elementSelector);
   if (!element) return null;
 
   const x = Number(gsap.getProperty(element, "x")) || 0;
@@ -99,12 +82,6 @@ function findGsapPositionAnimation(
 
 // ── Selector resolution ────────────────────────────────────────────────────
 
-function selectorForSelection(selection: DomEditSelection): string | null {
-  if (selection.id) return `#${selection.id}`;
-  if (selection.selector) return selection.selector;
-  return null;
-}
-
 // ── Property-group tween resolution ───────────────────────────────────────
 
 /**
@@ -193,7 +170,7 @@ export async function tryGsapDragIntercept(
   commitMutation: GsapDragCommitCallbacks["commitMutation"],
   fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
 ): Promise<boolean> {
-  const selector = selectorForSelection(selection);
+  const selector = selectorFromSelection(selection);
   if (!selector) return false;
 
   // Resolve the position-group tween, splitting legacy mixed tweens if needed.
@@ -284,15 +261,15 @@ export async function tryGsapResizeIntercept(
     const elDuration = Number.parseFloat(selection.dataAttributes?.duration ?? "5") || 5;
     const ct = usePlayerStore.getState().currentTime;
     const pct = elDuration > 0 ? Math.round(((ct - elStart) / elDuration) * 1000) / 10 : 0;
-    const sel = selectorForSelection(selection);
+    const sel = selectorFromSelection(selection);
     if (!sel) return false;
     await commitMutation(
       selection,
       {
         type: "add-with-keyframes",
         targetSelector: sel,
-        position: Math.round(elStart * 1000) / 1000,
-        duration: Math.round(elDuration * 1000) / 1000,
+        position: roundTo3(elStart),
+        duration: roundTo3(elDuration),
         keyframes: [
           {
             percentage: Math.max(0, Math.min(100, pct)),
@@ -310,7 +287,7 @@ export async function tryGsapResizeIntercept(
   if (activeKeyframePct != null) setActiveKeyframePct(null);
   const coalesceKey = `gsap:resize:${anim.id}`;
 
-  const selector = selectorForSelection(selection);
+  const selector = selectorFromSelection(selection);
   const runtimeProps = selector ? readAllAnimatedProperties(iframe, selector, anim) : {};
 
   let resizeProps: Record<string, number>;
@@ -320,7 +297,7 @@ export async function tryGsapResizeIntercept(
     // saved by the draft system before it ran.
     const origW = Number.parseFloat(el?.getAttribute("data-hf-studio-original-width") ?? "");
     const cssW = Number.isFinite(origW) && origW > 0 ? origW : 200;
-    const newScale = Math.round((size.width / cssW) * 1000) / 1000;
+    const newScale = roundTo3(size.width / cssW);
     resizeProps = { scale: newScale };
   } else {
     resizeProps = {
@@ -395,8 +372,8 @@ export async function tryGsapResizeIntercept(
         type: "replace-with-keyframes",
         animationId: anim.id,
         targetSelector: anim.targetSelector,
-        position: Math.round(newStart * 1000) / 1000,
-        duration: Math.round(newDuration * 1000) / 1000,
+        position: roundTo3(newStart),
+        duration: roundTo3(newDuration),
         keyframes: remapped,
       },
       { label: `Resize (extended to ${ct.toFixed(2)}s)`, softReload: true, coalesceKey },
@@ -455,25 +432,14 @@ export async function tryGsapRotationIntercept(
   }
   if (!anim) return false;
 
-  const selector = selectorForSelection(selection);
+  const selector = selectorFromSelection(selection);
   if (!selector) return false;
 
   let gsapRotation = 0;
-  if (iframe?.contentWindow) {
-    try {
-      const gsap = (
-        iframe.contentWindow as unknown as {
-          gsap?: { getProperty: (el: Element, prop: string) => number };
-        }
-      ).gsap;
-      const doc = iframe.contentDocument;
-      const el = doc?.querySelector(selector);
-      if (gsap?.getProperty && el) {
-        gsapRotation = Number(gsap.getProperty(el, "rotation")) || 0;
-      }
-    } catch {
-      /* cross-origin guard */
-    }
+  const gsap = getIframeGsap(iframe);
+  const rotEl = gsap ? queryIframeElement(iframe, selector) : null;
+  if (gsap && rotEl) {
+    gsapRotation = Number(gsap.getProperty(rotEl, "rotation")) || 0;
   }
 
   const pct = computeCurrentPercentage(selection, anim);

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -3,6 +3,8 @@
  * Used to discover dynamic keyframes that the AST parser can't resolve
  * (loops, variables, computed selectors).
  */
+import { parsePercentageKeyframes } from "./gsapShared";
+import { roundTo3 } from "../utils/rounding";
 
 interface RuntimeTween {
   targets?: () => Element[];
@@ -66,33 +68,8 @@ export function readRuntimeKeyframes(
     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 };
-    }
+    const parsed = parsePercentageKeyframes(vars.keyframes as Record<string, unknown>);
+    if (parsed) return parsed;
   }
   return null;
 }
@@ -133,38 +110,12 @@ export function scanAllRuntimeKeyframes(iframe: HTMLIFrameElement | null): Map<
       const vars = tween.vars;
 
       if (vars.keyframes && typeof vars.keyframes === "object") {
-        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) {
-          keyframes.sort((a, b) => a.percentage - b.percentage);
+        const parsed = parsePercentageKeyframes(vars.keyframes as Record<string, unknown>);
+        if (parsed) {
           for (const target of tween.targets()) {
             const id = (target as HTMLElement).id;
             if (id && !result.has(id)) {
-              result.set(id, { keyframes, easeEach });
+              result.set(id, parsed);
             }
           }
           continue;
@@ -195,7 +146,7 @@ export function scanAllRuntimeKeyframes(iframe: HTMLIFrameElement | null): Map<
       ]);
       for (const [k, v] of Object.entries(vars)) {
         if (skip.has(k)) continue;
-        if (typeof v === "number") properties[k] = Math.round(v * 1000) / 1000;
+        if (typeof v === "number") properties[k] = roundTo3(v);
         else if (typeof v === "string") properties[k] = v;
       }
       if (Object.keys(properties).length === 0) continue;