npm - @hyperframes/studio - Versions diffs - 0.6.0 → 0.6.1 - Mend

@hyperframes/studio 0.6.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (58) hide show

package/dist/assets/hyperframes-player-CzwFysqv.js +418 -0
package/dist/assets/index-hYc4aP7M.js +117 -0
package/dist/index.html +1 -1
package/package.json +4 -4
package/src/App.tsx +2 -13
package/src/captions/components/CaptionOverlay.tsx +13 -246
package/src/captions/components/CaptionOverlayUtils.ts +221 -0
package/src/components/StudioPreviewArea.tsx +6 -2
package/src/components/editor/DomEditOverlay.tsx +88 -1007
package/src/components/editor/EaseCurveEditor.tsx +221 -0
package/src/components/editor/FileTree.tsx +13 -621
package/src/components/editor/FileTreeIcons.tsx +128 -0
package/src/components/editor/FileTreeNodes.tsx +496 -0
package/src/components/editor/MotionPanel.tsx +16 -390
package/src/components/editor/MotionPanelFields.tsx +185 -0
package/src/components/editor/domEditOverlayGeometry.ts +211 -0
package/src/components/editor/domEditOverlayGestures.ts +138 -0
package/src/components/editor/domEditOverlayStartGesture.ts +155 -0
package/src/components/editor/domEditing.ts +44 -1150
package/src/components/editor/domEditingAgentPrompt.ts +97 -0
package/src/components/editor/domEditingDom.ts +266 -0
package/src/components/editor/domEditingElement.ts +329 -0
package/src/components/editor/domEditingLayers.ts +460 -0
package/src/components/editor/domEditingTypes.ts +125 -0
package/src/components/editor/manualEdits.ts +84 -1081
package/src/components/editor/manualEditsDom.ts +436 -0
package/src/components/editor/manualEditsParsing.ts +280 -0
package/src/components/editor/manualEditsSnapshot.ts +333 -0
package/src/components/editor/manualEditsTypes.ts +141 -0
package/src/components/editor/studioMotion.ts +47 -434
package/src/components/editor/studioMotionOps.ts +299 -0
package/src/components/editor/studioMotionTypes.ts +168 -0
package/src/components/editor/useDomEditOverlayGestures.ts +393 -0
package/src/components/editor/useDomEditOverlayRects.ts +207 -0
package/src/components/nle/NLELayout.tsx +60 -144
package/src/components/nle/useCompositionStack.ts +126 -0
package/src/hooks/useToast.ts +20 -0
package/src/player/components/Timeline.tsx +189 -1418
package/src/player/components/TimelineCanvas.tsx +434 -0
package/src/player/components/TimelineEmptyState.tsx +102 -0
package/src/player/components/TimelineRuler.tsx +90 -0
package/src/player/components/timelineIcons.tsx +49 -0
package/src/player/components/timelineLayout.ts +215 -0
package/src/player/components/timelineUtils.ts +211 -0
package/src/player/components/useTimelineClipDrag.ts +388 -0
package/src/player/components/useTimelinePlayhead.ts +200 -0
package/src/player/components/useTimelineRangeSelection.ts +135 -0
package/src/player/hooks/usePlaybackKeyboard.ts +171 -0
package/src/player/hooks/useTimelinePlayer.ts +69 -1372
package/src/player/hooks/useTimelineSyncCallbacks.ts +288 -0
package/src/player/lib/playbackAdapter.ts +145 -0
package/src/player/lib/playbackShortcuts.ts +68 -0
package/src/player/lib/playbackTypes.ts +60 -0
package/src/player/lib/timelineDOM.ts +373 -0
package/src/player/lib/timelineElementHelpers.ts +303 -0
package/src/player/lib/timelineIframeHelpers.ts +269 -0
package/dist/assets/hyperframes-player-DOFETgjy.js +0 -418
package/dist/assets/index-DUqUmaoH.js +0 -117

package/dist/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>HyperFrames Studio</title>
-    <script type="module" crossorigin src="/assets/index-DUqUmaoH.js"></script>
+    <script type="module" crossorigin src="/assets/index-hYc4aP7M.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-D1JDq7Gg.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "",
   "repository": {
     "type": "git",
@@ -32,8 +32,8 @@
     "@phosphor-icons/react": "^2.1.10",
     "codemirror": "^6.0.1",
     "motion": "^12.38.0",
-    "@hyperframes/core": "0.6.0",
-    "@hyperframes/player": "0.6.0"
+    "@hyperframes/player": "0.6.1",
+    "@hyperframes/core": "0.6.1"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -47,7 +47,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.6.0"
+    "@hyperframes/producer": "0.6.1"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx CHANGED Viewed

@@ -19,6 +19,7 @@ import { useConsoleErrorCapture } from "./hooks/useConsoleErrorCapture";
 import { useFrameCapture } from "./hooks/useFrameCapture";
 import { useLintModal } from "./hooks/useLintModal";
 import { useCompositionDimensions } from "./hooks/useCompositionDimensions";
+import { useToast } from "./hooks/useToast";
 import { buildProjectHash, parseProjectIdFromHash } from "./utils/projectRouting";
 import {
   STUDIO_INSPECTOR_PANELS_ENABLED,
@@ -27,7 +28,6 @@ import {
 import { getStudioMotionForSelection } from "./components/editor/studioMotion";
 import { getTimelineElementKey, isTimelineElementActiveAtTime } from "./utils/timelineInspector";
 import type { DomEditSelection } from "./components/editor/domEditing";
-import type { AppToast } from "./utils/studioHelpers";
 import { AskAgentModal } from "./components/AskAgentModal";
 import { StudioHeader } from "./components/StudioHeader";
 import { StudioLeftSidebar } from "./components/StudioLeftSidebar";
@@ -102,18 +102,7 @@ export function StudioApp() {
   const [timelineVisible, setTimelineVisible] = useState(true);
   const toggleTimelineVisibility = useCallback(() => setTimelineVisible((v) => !v), []);
-  const [appToast, setAppToast] = useState<AppToast | null>(null);
-  const toastTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const showToast = useCallback((message: string, tone: AppToast["tone"] = "error") => {
-    if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
-    setAppToast({ message, tone });
-    toastTimerRef.current = setTimeout(() => setAppToast(null), 4000);
-  }, []);
-  useMountEffect(() => () => {
-    if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
-  });
+  const { appToast, showToast } = useToast();
   const panelLayout = usePanelLayout();
   const editHistory = usePersistentEditHistory({ projectId });
   const domEditSaveTimestampRef = useRef(0);

package/src/captions/components/CaptionOverlay.tsx CHANGED Viewed

@@ -2,257 +2,31 @@ import { memo, useState, useCallback, useRef } from "react";
 import { useCaptionStore } from "../store";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { shouldHandleCaptionNudgeKey } from "../keyboard";
+import {
+  readWordBoxes,
+  getWordEl,
+  readGsapTransform,
+  getOrCreateWrapper,
+  writeTransform,
+  computeTransformStyle,
+  type WordBox,
+} from "./CaptionOverlayUtils";
 interface CaptionOverlayProps {
   iframeRef: React.RefObject<HTMLIFrameElement | null>;
 }
-interface WordBox {
-  segmentId: string;
-  groupId: string;
-  groupIndex: number;
-  wordIndex: number;
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
-function readWordBoxes(
-  iframe: HTMLIFrameElement,
-  model: {
-    groupOrder: string[];
-    groups: Map<string, { segmentIds: string[] }>;
-  },
-  overlayEl: HTMLElement,
-): WordBox[] {
-  let doc: Document | null = null;
-  let win: Window | null = null;
-  try {
-    doc = iframe.contentDocument;
-    win = iframe.contentWindow;
-  } catch {
-    return [];
-  }
-  if (!doc || !win) return [];
-  const iframeDisplayRect = iframe.getBoundingClientRect();
-  const overlayRect = overlayEl.getBoundingClientRect();
-  // The iframe renders at native resolution (e.g. 1920x1080) but is
-  // CSS-scaled to fit the viewport. getBoundingClientRect() on elements
-  // inside the iframe returns coordinates in the iframe's native space.
-  // Multiply by cssScale to convert to parent window coordinates.
-  const nativeW = parseFloat(iframe.style.width) || iframeDisplayRect.width;
-  const cssScale = iframeDisplayRect.width / nativeW;
-  const offsetX = iframeDisplayRect.left - overlayRect.left;
-  const offsetY = iframeDisplayRect.top - overlayRect.top;
-  const groupEls = doc.querySelectorAll<HTMLElement>(".caption-group");
-  const boxes: WordBox[] = [];
-  for (let gi = 0; gi < model.groupOrder.length; gi++) {
-    const groupId = model.groupOrder[gi];
-    const group = model.groups.get(groupId);
-    if (!group) continue;
-    const groupEl = groupEls[gi] as HTMLElement | undefined;
-    if (!groupEl) continue;
-    const computed = win.getComputedStyle(groupEl);
-    if (parseFloat(computed.opacity) <= 0.01 || computed.visibility === "hidden") continue;
-    // Find word elements — handles both per-word spans (generator output)
-    // and grouped text nodes (existing caption templates that use
-    // el.textContent = line.text instead of individual word spans).
-    const resolvedWordEls: HTMLElement[] = [];
-    for (const child of groupEl.children) {
-      const c = child as HTMLElement;
-      if (c.dataset.captionWrapper === "true") {
-        const inner = c.querySelector<HTMLElement>(":scope > span");
-        if (inner) resolvedWordEls.push(inner);
-      } else if (c.tagName === "SPAN") {
-        resolvedWordEls.push(c);
-      }
-    }
-    // Fallback: if no word spans found but group has text content,
-    // the template uses grouped text. Wrap each word in a span so
-    // the overlay can target them individually.
-    if (resolvedWordEls.length === 0 && groupEl.textContent?.trim()) {
-      const textNode = groupEl.childNodes[0];
-      if (textNode && textNode.nodeType === Node.TEXT_NODE) {
-        const words = (textNode.textContent || "").split(/\s+/).filter(Boolean);
-        const frag = doc.createDocumentFragment();
-        for (const word of words) {
-          const span = doc.createElement("span");
-          span.textContent = word + " ";
-          span.style.display = "inline";
-          frag.appendChild(span);
-          resolvedWordEls.push(span);
-        }
-        groupEl.replaceChild(frag, textNode);
-      } else {
-        // Single span child with all text (e.g. vignelli template)
-        const singleSpan = groupEl.querySelector<HTMLElement>(":scope > span");
-        if (singleSpan && singleSpan.textContent?.trim()) {
-          const words = singleSpan.textContent.split(/\s+/).filter(Boolean);
-          const frag = doc.createDocumentFragment();
-          for (const word of words) {
-            const span = doc.createElement("span");
-            span.textContent = word + " ";
-            span.style.display = "inline";
-            frag.appendChild(span);
-            resolvedWordEls.push(span);
-          }
-          singleSpan.replaceWith(frag);
-        }
-      }
-    }
-    for (let wi = 0; wi < group.segmentIds.length; wi++) {
-      const segId = group.segmentIds[wi];
-      const wordEl = resolvedWordEls[wi] as HTMLElement | undefined;
-      if (!wordEl) continue;
-      const rect = wordEl.getBoundingClientRect();
-      boxes.push({
-        segmentId: segId,
-        groupId,
-        groupIndex: gi,
-        wordIndex: wi,
-        x: rect.left * cssScale + offsetX,
-        y: rect.top * cssScale + offsetY,
-        width: rect.width * cssScale,
-        height: rect.height * cssScale,
-      });
-    }
-  }
-  return boxes;
-}
-function getWordEl(
-  iframe: HTMLIFrameElement,
-  groupIndex: number,
-  wordIndex: number,
-): HTMLElement | null {
-  let doc: Document | null = null;
-  try {
-    doc = iframe.contentDocument;
-  } catch {
-    return null;
-  }
-  if (!doc) return null;
-  const groupEl = doc.querySelectorAll<HTMLElement>(".caption-group")[groupIndex];
-  if (!groupEl) return null;
-  // Find word spans — they may be direct children or inside wrapper spans.
-  // Word spans have class "word" or an id starting with "w".
-  // Wrappers have data-caption-wrapper="true".
-  const wordEls: HTMLElement[] = [];
-  for (const child of groupEl.children) {
-    const el = child as HTMLElement;
-    if (el.dataset.captionWrapper === "true") {
-      // Wrapped word — get the inner span
-      const inner = el.querySelector<HTMLElement>(":scope > span");
-      if (inner) wordEls.push(inner);
-    } else if (el.tagName === "SPAN") {
-      wordEls.push(el);
-    }
-  }
-  return wordEls[wordIndex] ?? null;
-}
-/**
- * Read GSAP's internal transform state for an element.
- * GSAP stores transforms in its own cache, not in el.style.transform.
- */
-function readGsapTransform(
-  el: HTMLElement,
-  iframeWin: Window,
-): { x: number; y: number; scale: number; rotation: number } {
-  const gsap = (
-    iframeWin as unknown as { gsap?: { getProperty?: (el: HTMLElement, prop: string) => number } }
-  ).gsap;
-  if (gsap && gsap.getProperty) {
-    return {
-      x: gsap.getProperty(el, "x") || 0,
-      y: gsap.getProperty(el, "y") || 0,
-      scale: gsap.getProperty(el, "scale") || 1,
-      rotation: gsap.getProperty(el, "rotation") || 0,
-    };
-  }
-  // Fallback: parse from style
-  const t = el.style.transform || "";
-  const scaleMatch = t.match(/scale\(([^)]+)\)/);
-  const rotMatch = t.match(/rotate\(([^)]+)deg\)/);
-  const txyMatch = t.match(/translate\(([^,]+)px,\s*([^)]+)px\)/);
-  return {
-    x: txyMatch ? parseFloat(txyMatch[1]) : 0,
-    y: txyMatch ? parseFloat(txyMatch[2]) : 0,
-    scale: scaleMatch ? parseFloat(scaleMatch[1]) : 1,
-    rotation: rotMatch ? parseFloat(rotMatch[1]) : 0,
-  };
-}
-/**
- * Get or create an inline-block wrapper span around a word element.
- * Transforms are applied to the wrapper so the word's GSAP animations are preserved.
- */
-function getOrCreateWrapper(el: HTMLElement): HTMLElement {
-  // If el IS a wrapper, return it
-  if (el.dataset.captionWrapper === "true") return el;
-  // If el's parent is a wrapper, return the parent
-  const parent = el.parentElement;
-  if (parent && parent.dataset.captionWrapper === "true") return parent;
-  // Create new wrapper
-  const doc = el.ownerDocument;
-  const wrapper = doc.createElement("span");
-  wrapper.style.display = "inline-block";
-  wrapper.dataset.captionWrapper = "true";
-  el.parentNode?.insertBefore(wrapper, el);
-  wrapper.appendChild(el);
-  return wrapper;
-}
-/**
- * Write transform values to a wrapper span around the word element.
- * The word keeps its GSAP animations; the wrapper handles editor transforms.
- */
-function writeTransform(
-  el: HTMLElement,
-  iframeWin: Window,
-  x: number,
-  y: number,
-  scale: number,
-  rotation: number,
-) {
-  const wrapper = getOrCreateWrapper(el);
-  const gsap = (
-    iframeWin as unknown as {
-      gsap?: { set?: (el: HTMLElement, props: Record<string, number>) => void };
-    }
-  ).gsap;
-  if (gsap && gsap.set) {
-    gsap.set(wrapper, { x, y, scale, rotation });
-  } else {
-    wrapper.style.transform = `translate(${x.toFixed(1)}px, ${y.toFixed(1)}px) rotate(${rotation.toFixed(1)}deg) scale(${scale.toFixed(3)})`;
-  }
-}
+const HANDLE = 8;
+const ROTATION_OFFSET = 20; // px above the selection box
-/** Sync canvas state back to the Zustand store so the property panel reflects it.
- *  Only writes non-default values to avoid creating spurious overrides. */
+/** Sync canvas state back to the Zustand store so the property panel reflects it. */
 function syncToStore(segmentId: string, el: HTMLElement, iframeWin: Window) {
-  const wrapper = getOrCreateWrapper(el);
-  const { x, y, scale, rotation } = readGsapTransform(wrapper, iframeWin);
-  const style: Record<string, number> = {};
-  if (Math.abs(x) > 0.5) style.x = x;
-  if (Math.abs(y) > 0.5) style.y = y;
-  if (Math.abs(scale - 1) > 0.001) {
-    style.scaleX = scale;
-    style.scaleY = scale;
-  }
-  if (Math.abs(rotation) > 0.1) style.rotation = rotation;
+  const style = computeTransformStyle(el, iframeWin);
   if (Object.keys(style).length > 0) {
     useCaptionStore.getState().updateSegmentStyle(segmentId, style);
   }
 }
-const HANDLE = 8;
-const ROTATION_OFFSET = 20; // px above the selection box
 export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: CaptionOverlayProps) {
   const isEditMode = useCaptionStore((s) => s.isEditMode);
   const model = useCaptionStore((s) => s.model);
@@ -311,7 +85,6 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
       const overlay = overlayRef.current;
       if (!iframe || !m || !overlay) return;
       const next = readWordBoxes(iframe, m, overlay);
-      // Skip state update if nothing changed (avoids re-render every 66ms)
       if (
         next.length === prevBoxes.length &&
         next.every(
@@ -342,7 +115,6 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
       if (!iframe || !win) return;
       for (const segId of sel) {
-        // Find group/word index for this segment
         for (let gi = 0; gi < m.groupOrder.length; gi++) {
           const group = m.groups.get(m.groupOrder[gi]);
           if (!group) continue;
@@ -459,7 +231,6 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
     [iframeRef],
   );
-  /** Get iframe contentWindow, needed for gsap calls */
   const getIframeWin = useCallback((): Window | null => {
     try {
       return iframeRef.current?.contentWindow ?? null;
@@ -482,8 +253,6 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
         const dy = (e.clientY - i.startMY) / cssScale;
         writeTransform(i.wordEl, win, i.origTX + dx, i.origTY + dy, i.origScale, i.origRotation);
       } else if (i.type === "scale") {
-        // Use distance from box center so dragging outward from ANY corner
-        // increases scale (not just right-side handles).
         const cx = i.startMX - i.startDxFromCenter;
         const startDist = Math.abs(i.startDxFromCenter);
         const currentDist = Math.abs(e.clientX - cx);
@@ -491,8 +260,6 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
         const newScale = Math.max(0.1, i.origScale * factor);
         writeTransform(i.wordEl, win, i.origTX, i.origTY, newScale, i.origRotation);
       } else if (i.type === "rotate") {
-        // Horizontal drag maps to rotation: right = clockwise, left = counter-clockwise.
-        // 200px of horizontal movement = 90 degrees.
         const dx = e.clientX - i.startMX;
         const delta = (dx / 200) * 90;
         writeTransform(i.wordEl, win, i.origTX, i.origTY, i.origScale, i.origRotation + delta);

package/src/captions/components/CaptionOverlayUtils.ts ADDED Viewed

@@ -0,0 +1,221 @@
+// DOM helpers for CaptionOverlay — word box reading, transform I/O, wrapper management
+export interface WordBox {
+  segmentId: string;
+  groupId: string;
+  groupIndex: number;
+  wordIndex: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+export function readWordBoxes(
+  iframe: HTMLIFrameElement,
+  model: {
+    groupOrder: string[];
+    groups: Map<string, { segmentIds: string[] }>;
+  },
+  overlayEl: HTMLElement,
+): WordBox[] {
+  let doc: Document | null = null;
+  let win: Window | null = null;
+  try {
+    doc = iframe.contentDocument;
+    win = iframe.contentWindow;
+  } catch {
+    return [];
+  }
+  if (!doc || !win) return [];
+  const iframeDisplayRect = iframe.getBoundingClientRect();
+  const overlayRect = overlayEl.getBoundingClientRect();
+  const nativeW = parseFloat(iframe.style.width) || iframeDisplayRect.width;
+  const cssScale = iframeDisplayRect.width / nativeW;
+  const offsetX = iframeDisplayRect.left - overlayRect.left;
+  const offsetY = iframeDisplayRect.top - overlayRect.top;
+  const groupEls = doc.querySelectorAll<HTMLElement>(".caption-group");
+  const boxes: WordBox[] = [];
+  for (let gi = 0; gi < model.groupOrder.length; gi++) {
+    const groupId = model.groupOrder[gi];
+    const group = model.groups.get(groupId);
+    if (!group) continue;
+    const groupEl = groupEls[gi] as HTMLElement | undefined;
+    if (!groupEl) continue;
+    const computed = win.getComputedStyle(groupEl);
+    if (parseFloat(computed.opacity) <= 0.01 || computed.visibility === "hidden") continue;
+    const resolvedWordEls: HTMLElement[] = [];
+    for (const child of groupEl.children) {
+      const c = child as HTMLElement;
+      if (c.dataset.captionWrapper === "true") {
+        const inner = c.querySelector<HTMLElement>(":scope > span");
+        if (inner) resolvedWordEls.push(inner);
+      } else if (c.tagName === "SPAN") {
+        resolvedWordEls.push(c);
+      }
+    }
+    if (resolvedWordEls.length === 0 && groupEl.textContent?.trim()) {
+      const textNode = groupEl.childNodes[0];
+      if (textNode && textNode.nodeType === Node.TEXT_NODE) {
+        const words = (textNode.textContent || "").split(/\s+/).filter(Boolean);
+        const frag = doc.createDocumentFragment();
+        for (const word of words) {
+          const span = doc.createElement("span");
+          span.textContent = word + " ";
+          span.style.display = "inline";
+          frag.appendChild(span);
+          resolvedWordEls.push(span);
+        }
+        groupEl.replaceChild(frag, textNode);
+      } else {
+        const singleSpan = groupEl.querySelector<HTMLElement>(":scope > span");
+        if (singleSpan && singleSpan.textContent?.trim()) {
+          const words = singleSpan.textContent.split(/\s+/).filter(Boolean);
+          const frag = doc.createDocumentFragment();
+          for (const word of words) {
+            const span = doc.createElement("span");
+            span.textContent = word + " ";
+            span.style.display = "inline";
+            frag.appendChild(span);
+            resolvedWordEls.push(span);
+          }
+          singleSpan.replaceWith(frag);
+        }
+      }
+    }
+    for (let wi = 0; wi < group.segmentIds.length; wi++) {
+      const segId = group.segmentIds[wi];
+      const wordEl = resolvedWordEls[wi] as HTMLElement | undefined;
+      if (!wordEl) continue;
+      const rect = wordEl.getBoundingClientRect();
+      boxes.push({
+        segmentId: segId,
+        groupId,
+        groupIndex: gi,
+        wordIndex: wi,
+        x: rect.left * cssScale + offsetX,
+        y: rect.top * cssScale + offsetY,
+        width: rect.width * cssScale,
+        height: rect.height * cssScale,
+      });
+    }
+  }
+  return boxes;
+}
+export function getWordEl(
+  iframe: HTMLIFrameElement,
+  groupIndex: number,
+  wordIndex: number,
+): HTMLElement | null {
+  let doc: Document | null = null;
+  try {
+    doc = iframe.contentDocument;
+  } catch {
+    return null;
+  }
+  if (!doc) return null;
+  const groupEl = doc.querySelectorAll<HTMLElement>(".caption-group")[groupIndex];
+  if (!groupEl) return null;
+  const wordEls: HTMLElement[] = [];
+  for (const child of groupEl.children) {
+    const el = child as HTMLElement;
+    if (el.dataset.captionWrapper === "true") {
+      const inner = el.querySelector<HTMLElement>(":scope > span");
+      if (inner) wordEls.push(inner);
+    } else if (el.tagName === "SPAN") {
+      wordEls.push(el);
+    }
+  }
+  return wordEls[wordIndex] ?? null;
+}
+/**
+ * Read GSAP's internal transform state for an element.
+ * GSAP stores transforms in its own cache, not in el.style.transform.
+ */
+export function readGsapTransform(
+  el: HTMLElement,
+  iframeWin: Window,
+): { x: number; y: number; scale: number; rotation: number } {
+  const gsap = (
+    iframeWin as unknown as { gsap?: { getProperty?: (el: HTMLElement, prop: string) => number } }
+  ).gsap;
+  if (gsap && gsap.getProperty) {
+    return {
+      x: gsap.getProperty(el, "x") || 0,
+      y: gsap.getProperty(el, "y") || 0,
+      scale: gsap.getProperty(el, "scale") || 1,
+      rotation: gsap.getProperty(el, "rotation") || 0,
+    };
+  }
+  const t = el.style.transform || "";
+  const scaleMatch = t.match(/scale\(([^)]+)\)/);
+  const rotMatch = t.match(/rotate\(([^)]+)deg\)/);
+  const txyMatch = t.match(/translate\(([^,]+)px,\s*([^)]+)px\)/);
+  return {
+    x: txyMatch ? parseFloat(txyMatch[1]) : 0,
+    y: txyMatch ? parseFloat(txyMatch[2]) : 0,
+    scale: scaleMatch ? parseFloat(scaleMatch[1]) : 1,
+    rotation: rotMatch ? parseFloat(rotMatch[1]) : 0,
+  };
+}
+/**
+ * Get or create an inline-block wrapper span around a word element.
+ * Transforms are applied to the wrapper so the word's GSAP animations are preserved.
+ */
+export function getOrCreateWrapper(el: HTMLElement): HTMLElement {
+  if (el.dataset.captionWrapper === "true") return el;
+  const parent = el.parentElement;
+  if (parent && parent.dataset.captionWrapper === "true") return parent;
+  const doc = el.ownerDocument;
+  const wrapper = doc.createElement("span");
+  wrapper.style.display = "inline-block";
+  wrapper.dataset.captionWrapper = "true";
+  el.parentNode?.insertBefore(wrapper, el);
+  wrapper.appendChild(el);
+  return wrapper;
+}
+/**
+ * Write transform values to a wrapper span around the word element.
+ */
+export function writeTransform(
+  el: HTMLElement,
+  iframeWin: Window,
+  x: number,
+  y: number,
+  scale: number,
+  rotation: number,
+) {
+  const wrapper = getOrCreateWrapper(el);
+  const gsap = (
+    iframeWin as unknown as {
+      gsap?: { set?: (el: HTMLElement, props: Record<string, number>) => void };
+    }
+  ).gsap;
+  if (gsap && gsap.set) {
+    gsap.set(wrapper, { x, y, scale, rotation });
+  } else {
+    wrapper.style.transform = `translate(${x.toFixed(1)}px, ${y.toFixed(1)}px) rotate(${rotation.toFixed(1)}deg) scale(${scale.toFixed(3)})`;
+  }
+}
+/** Compute style deltas from the current wrapper transform — used by syncToStore in the overlay. */
+export function computeTransformStyle(el: HTMLElement, iframeWin: Window): Record<string, number> {
+  const wrapper = getOrCreateWrapper(el);
+  const { x, y, scale, rotation } = readGsapTransform(wrapper, iframeWin);
+  const style: Record<string, number> = {};
+  if (Math.abs(x) > 0.5) style.x = x;
+  if (Math.abs(y) > 0.5) style.y = y;
+  if (Math.abs(scale - 1) > 0.001) {
+    style.scaleX = scale;
+    style.scaleY = scale;
+  }
+  if (Math.abs(rotation) > 0.1) style.rotation = rotation;
+  return style;
+}

package/src/components/StudioPreviewArea.tsx CHANGED Viewed

@@ -108,8 +108,12 @@ export function StudioPreviewArea({
         onCompositionChange={(compPath) => {
           // Sync activeCompPath when user drills down via timeline double-click
           // or navigates back via breadcrumb — keeps sidebar + thumbnails in sync.
-          setActiveCompPath(compPath);
-          refreshPreviewDocumentVersion();
+          // Guard against no-op updates to prevent circular refresh cascades
+          // between activeCompPath → compositionStack → onCompositionChange.
+          if (compPath !== activeCompPath) {
+            setActiveCompPath(compPath);
+            refreshPreviewDocumentVersion();
+          }
         }}
         onIframeRef={handlePreviewIframeRef}
         previewOverlay={