@hyperframes/studio 0.8.6 → 0.8.7

package/package.json

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

package/src/App.tsx

@@ -1,4 +1,4 @@
-import { useState, useCallback, useRef, useMemo, useEffect, useLayoutEffect } from "react";
+import { useState, useCallback, useRef, useMemo, useLayoutEffect } from "react";
 import type { LeftSidebarHandle, SidebarTab } from "./components/sidebar/LeftSidebar";
 import { useRenderQueue } from "./components/renders/useRenderQueue";
 import { usePlayerStore } from "./player";
@@ -37,6 +37,8 @@ import { useCompositionDimensions } from "./hooks/useCompositionDimensions";
 import { useToast } from "./hooks/useToast";
 import { useCompositionContentLoader } from "./hooks/useCompositionContentLoader";
 import { useStudioUrlState } from "./hooks/useStudioUrlState";
+import { useEffectiveTimelineDuration } from "./hooks/useEffectiveTimelineDuration";
+import { useAudioSoloBridge } from "./hooks/useAudioSoloBridge";
 import {
   buildStudioContextValue,
   useGlobalFileDrop,
@@ -60,11 +62,8 @@ import { StudioSplash } from "./components/StudioSplash";
 import { useServerConnection } from "./hooks/useServerConnection";
 import { useStudioSessionStart } from "./hooks/useStudioSessionStart";
 import { useTimelineAddAtPlayhead } from "./hooks/useTimelineAddAtPlayhead";
-import {
-  normalizeStudioCompositionPath,
-  readStudioUrlStateFromWindow,
-  resolveMasterCompositionPath,
-} from "./utils/studioUrlState";
+import { readStudioUrlStateFromWindow, resolveMasterCompositionPath } from "./utils/studioUrlState";
+import { useHydrateActiveCompPathFromUrl } from "./hooks/useHydrateActiveCompPathFromUrl";
 const getTimelineSelectionSet = () => usePlayerStore.getState().selectedElementIds;
 // fallow-ignore-next-line complexity
 export function StudioApp() {
@@ -83,6 +82,7 @@ export function StudioApp() {
   const [previewDocumentVersion, refreshPreviewDocumentVersion] = usePreviewDocumentVersion();
   const [blockPreview, setBlockPreview] = useState<BlockPreviewInfo | null>(null);
   const previewIframeRef = useRef<HTMLIFrameElement | null>(null);
+  useAudioSoloBridge(previewIframeRef);
   const activeCompPathRef = useRef(activeCompPath);
   activeCompPathRef.current = activeCompPath;
   const leftSidebarRef = useRef<LeftSidebarHandle>(null);
@@ -95,13 +95,10 @@ export function StudioApp() {
   const setTimelineSelectionSet = usePlayerStore((s) => s.setSelectedElementIds);
   const timelineDuration = usePlayerStore((s) => s.duration);
   const isPlaying = usePlayerStore((s) => s.isPlaying);
-  const effectiveTimelineDuration = useMemo(() => {
-    const maxEnd =
-      timelineElements.length > 0
-        ? Math.max(...timelineElements.map((el) => el.start + el.duration))
-        : 0;
-    return Math.max(timelineDuration, maxEnd);
-  }, [timelineDuration, timelineElements]);
+  const effectiveTimelineDuration = useEffectiveTimelineDuration(
+    timelineDuration,
+    timelineElements,
+  );
   const { toasts, showToast, dismissToast } = useToast();
   const panelLayout = usePanelLayout({
     rightCollapsed: initialUrlStateRef.current.rightCollapsed,
@@ -129,16 +126,14 @@ export function StudioApp() {
     activeCompPath,
     masterCompPath,
   );
-  useEffect(() => {
-    if (activeCompPathHydrated) return;
-    if (!fileManager.fileTreeLoaded) return;
-    const nextCompPath = normalizeStudioCompositionPath(
-      initialUrlStateRef.current.activeCompPath,
-      fileManager.fileTree,
-    );
-    setActiveCompPath((current) => (current === nextCompPath ? current : nextCompPath));
-    setActiveCompPathHydrated(true);
-  }, [activeCompPathHydrated, fileManager.fileTree, fileManager.fileTreeLoaded]);
+  useHydrateActiveCompPathFromUrl({
+    hydrated: activeCompPathHydrated,
+    fileTreeLoaded: fileManager.fileTreeLoaded,
+    fileTree: fileManager.fileTree,
+    initialUrlStateRef,
+    setActiveCompPath,
+    setHydrated: setActiveCompPathHydrated,
+  });
   const previewPersistence = usePreviewPersistence({
     showToast,
     readOptionalProjectFile: fileManager.readOptionalProjectFile,
@@ -532,6 +527,7 @@ export function StudioApp() {
                           domEditSaveTimestampRef={domEditSaveTimestampRef}
                           recordEdit={editHistory.recordEdit}
                           onToggleElementHidden={timelineEditing.handleToggleElementHidden}
+                          onAutoGroupCarveSources={timelineEditing.handleAutoGroupCarveSources}
                           onAddMediaOverlay={handleAddMediaOverlay}
                         />
                       )
@@ -549,6 +545,9 @@ export function StudioApp() {
                     handleTimelineElementResize={timelineEditing.handleTimelineElementResize}
                     handleTimelineGroupResize={timelineEditing.handleTimelineGroupResize}
                     handleToggleTrackHidden={timelineEditing.handleToggleTrackHidden}
+                    setAudioGroupAttribute={timelineEditing.setAudioGroupAttribute}
+                    handleGroupClips={timelineEditing.handleAutoGroupCarveSources}
+                    setElementFxAttribute={timelineEditing.setElementFxAttribute}
                     handleBlockedTimelineEdit={timelineEditing.handleBlockedTimelineEdit}
                     handleTimelineElementSplit={timelineEditing.handleTimelineElementSplit}
                     handleRazorSplit={timelineEditing.handleRazorSplit}

package/src/captions/components/CaptionAnimationPanel.tsx

@@ -61,7 +61,13 @@ const EASE_PRESETS = [
   "bounce.out",
 ];
 
-import { Section, Row, inputCls } from "./shared";
+import { Section, Row, inputCls, NumberField } from "./shared";
+
+// Animation edits currently mutate only the in-memory model: they are not
+// applied to the preview and not serialized by buildOverrides, so tuning them
+// would be editing blind. Controls stay visible (so the capability is
+// discoverable) but disabled until the apply/persist pipeline exists.
+const ANIMATION_PIPELINE_WIRED = false;
 
 // ---------------------------------------------------------------------------
 // Animation phase controls
@@ -72,6 +78,7 @@ interface AnimationPhaseProps {
   presets: string[];
   animation: CaptionAnimation | null;
   showIntensity?: boolean;
+  disabled?: boolean;
   onChange: (update: Partial<CaptionAnimation>) => void;
 }
 
@@ -80,6 +87,7 @@ function AnimationPhase({
   presets,
   animation,
   showIntensity,
+  disabled,
   onChange,
 }: AnimationPhaseProps) {
   const preset = animation?.preset ?? "none";
@@ -93,6 +101,8 @@ function AnimationPhase({
       <Row label="Preset">
         <select
           value={preset}
+          disabled={disabled}
+          aria-label={`${label} preset`}
           onChange={(e) => onChange({ preset: e.target.value })}
           className={inputCls}
         >
@@ -105,20 +115,22 @@ function AnimationPhase({
       </Row>
 
       <Row label="Duration">
-        <input
-          type="number"
+        <NumberField
           value={duration}
           step={0.05}
           min={0}
           max={2}
-          onChange={(e) => onChange({ duration: Number(e.target.value) })}
-          className={inputCls}
+          disabled={disabled}
+          ariaLabel={`${label} duration`}
+          onCommit={(v) => onChange({ duration: v })}
         />
       </Row>
 
       <Row label="Ease">
         <select
           value={ease}
+          disabled={disabled}
+          aria-label={`${label} ease`}
           onChange={(e) => onChange({ ease: e.target.value })}
           className={inputCls}
         >
@@ -131,14 +143,14 @@ function AnimationPhase({
       </Row>
 
       <Row label="Stagger">
-        <input
-          type="number"
+        <NumberField
           value={stagger}
           step={0.02}
           min={0}
           max={0.5}
-          onChange={(e) => onChange({ stagger: Number(e.target.value) })}
-          className={inputCls}
+          disabled={disabled}
+          ariaLabel={`${label} stagger`}
+          onCommit={(v) => onChange({ stagger: v })}
         />
       </Row>
 
@@ -151,8 +163,13 @@ function AnimationPhase({
               max={1}
               step={0.01}
               value={intensity}
-              onChange={(e) => onChange({ intensity: Number(e.target.value) })}
-              className="flex-1 accent-studio-accent"
+              disabled={disabled}
+              aria-label={`${label} intensity`}
+              onChange={(e) => {
+                const v = Number(e.target.value);
+                if (Number.isFinite(v)) onChange({ intensity: v });
+              }}
+              className="flex-1 accent-studio-accent disabled:opacity-40"
             />
             <span className="text-2xs text-neutral-400 font-mono w-8 text-right flex-shrink-0">
               {intensity.toFixed(2)}
@@ -222,19 +239,31 @@ export const CaptionAnimationPanel = memo(function CaptionAnimationPanel() {
   if (!group || !resolvedGroupId || !animation) {
     return (
       <div className="flex items-center justify-center h-full px-4 text-center">
-        <p className="text-xs text-neutral-500">Select a caption group to edit animations</p>
+        <p className="text-xs text-neutral-500">Select a caption word to edit animations</p>
       </div>
     );
   }
 
+  const gated = !ANIMATION_PIPELINE_WIRED;
+
   return (
     <div className="flex flex-col h-full min-h-0">
+      {gated && (
+        <div className="flex-shrink-0 mx-3 mt-2 px-2 py-1.5 rounded border border-amber-500/30 bg-amber-500/10">
+          <p className="text-2xs text-amber-300/90 leading-snug">
+            Animation editing isn&apos;t applied to playback or saved yet, so these controls are
+            disabled.
+          </p>
+        </div>
+      )}
+
       {/* Scrollable content */}
       <div className="flex-1 overflow-y-auto px-3 py-2">
         <AnimationPhase
           label="Entrance"
           presets={ENTRANCE_PRESETS}
           animation={animation.entrance}
+          disabled={gated}
           onChange={handleEntranceChange}
         />
 
@@ -243,6 +272,7 @@ export const CaptionAnimationPanel = memo(function CaptionAnimationPanel() {
           presets={HIGHLIGHT_PRESETS}
           animation={animation.highlight}
           showIntensity
+          disabled={gated}
           onChange={handleHighlightChange}
         />
 
@@ -250,6 +280,7 @@ export const CaptionAnimationPanel = memo(function CaptionAnimationPanel() {
           label="Exit"
           presets={EXIT_PRESETS}
           animation={animation.exit}
+          disabled={gated}
           onChange={handleExitChange}
         />
       </div>
@@ -259,7 +290,9 @@ export const CaptionAnimationPanel = memo(function CaptionAnimationPanel() {
         <button
           type="button"
           onClick={handleApplyToAll}
-          className="w-full py-1.5 rounded border border-neutral-700 text-2xs text-neutral-300 hover:border-studio-accent/50 hover:text-studio-accent transition-colors"
+          disabled={gated}
+          title={gated ? "Disabled until animation editing is applied to playback" : undefined}
+          className="w-full py-1.5 rounded border border-neutral-700 text-2xs text-neutral-300 hover:border-studio-accent/50 hover:text-studio-accent transition-colors disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:border-neutral-700 disabled:hover:text-neutral-300"
         >
           Apply to all groups
         </button>

package/src/captions/components/CaptionOverlay.tsx

@@ -1,7 +1,8 @@
 import { memo, useState, useCallback, useRef } from "react";
 import { useCaptionStore } from "../store";
+import { usePlayerStore } from "../../player";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import { shouldHandleCaptionNudgeKey } from "../keyboard";
+import { shouldHandleCaptionNudgeKey, isEditableEventTarget } from "../keyboard";
 import {
   readWordBoxes,
   getWordEl,
@@ -9,6 +10,7 @@ import {
   getOrCreateWrapper,
   writeTransform,
   computeTransformStyle,
+  registerCaptionIframe,
   type WordBox,
 } from "./CaptionOverlayUtils";
 
@@ -16,7 +18,8 @@ interface CaptionOverlayProps {
   iframeRef: React.RefObject<HTMLIFrameElement | null>;
 }
 
-const HANDLE = 8;
+const HANDLE = 8; // visual size of a handle dot
+const HANDLE_HIT = 24; // pointer target size (invisible padding around the dot)
 const ROTATION_OFFSET = 20; // px above the selection box
 
 /** Sync canvas state back to the Zustand store so the property panel reflects it. */
@@ -38,6 +41,8 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
   const overlayRef = useRef<HTMLDivElement>(null);
   const modelRef = useRef(model);
   modelRef.current = model;
+  // Set by the mount effect; lets Escape handling cancel an in-flight drag.
+  const cancelDragRef = useRef<(() => boolean) | null>(null);
 
   // Interaction mode — only one active at a time
   const interactionRef = useRef<
@@ -78,8 +83,14 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
 
   useMountEffect(() => {
     if (!isEditMode) return;
+
+    // Let undo/redo (useAppHotkeys) reapply restored models to this iframe.
+    const unregisterIframe = registerCaptionIframe(iframeRef);
+
     let prevBoxes: WordBox[] = [];
+    let rafId: number | null = null;
     const tick = () => {
+      rafId = null;
       const iframe = iframeRef.current;
       const m = modelRef.current;
       const overlay = overlayRef.current;
@@ -95,15 +106,98 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
       prevBoxes = next;
       setWordBoxes(next);
     };
-    const id = setInterval(tick, 66);
+    // Coalesce bursts of triggers (player store updates, resize) into one
+    // layout read per frame — replaces the old unconditional 66ms polling.
+    const scheduleTick = () => {
+      if (rafId === null) rafId = requestAnimationFrame(tick);
+    };
+
+    // Event sources: player state changes (seek/scrub/select), preview
+    // messages, element resize, window resize.
+    const unsubPlayer = usePlayerStore.subscribe(scheduleTick);
+    const handleMessage = (e: MessageEvent) => {
+      const data = e.data;
+      if (data?.source === "hf-preview") scheduleTick();
+    };
+    window.addEventListener("message", handleMessage);
+    window.addEventListener("resize", scheduleTick);
+    const resizeObserver = new ResizeObserver(scheduleTick);
+    if (iframeRef.current) resizeObserver.observe(iframeRef.current);
+    if (overlayRef.current) resizeObserver.observe(overlayRef.current);
+
+    // During playback caption groups animate continuously — a light interval
+    // is the only reliable driver, but it runs ONLY while playing.
+    let playInterval: ReturnType<typeof setInterval> | null = null;
+    const syncPlaybackInterval = () => {
+      const playing = usePlayerStore.getState().isPlaying;
+      if (playing && playInterval === null) {
+        playInterval = setInterval(scheduleTick, 66);
+      } else if (!playing && playInterval !== null) {
+        clearInterval(playInterval);
+        playInterval = null;
+      }
+    };
+    const unsubPlayback = usePlayerStore.subscribe(syncPlaybackInterval);
+    syncPlaybackInterval();
     tick();
 
-    // Arrow key nudge for selected words
+    const getWin = (): Window | null => {
+      try {
+        return iframeRef.current?.contentWindow ?? null;
+      } catch {
+        return null;
+      }
+    };
+
+    const cancelActiveDrag = (): boolean => {
+      const i = interactionRef.current;
+      if (!i) return false;
+      const win = getWin();
+      if (win) {
+        // Restore the pre-drag transform instead of committing the partial one.
+        writeTransform(i.wordEl, win, i.origTX, i.origTY, i.origScale, i.origRotation);
+      }
+      interactionRef.current = null;
+      return true;
+    };
+    cancelDragRef.current = cancelActiveDrag;
+
     const handleKeyDown = (e: KeyboardEvent) => {
-      const { selectedSegmentIds: sel, model: m } = useCaptionStore.getState();
+      const store = useCaptionStore.getState();
+      const { selectedSegmentIds: sel, model: m } = store;
+
+      // Escape: cancel an in-flight drag first, else clear the selection.
+      if (e.key === "Escape") {
+        if (cancelActiveDrag()) {
+          e.preventDefault();
+          scheduleTick();
+          return;
+        }
+        if (sel.size > 0) {
+          e.preventDefault();
+          store.clearSelection();
+        }
+        return;
+      }
+
+      // ⌘A / Ctrl+A selects every caption word (unless typing in a field).
+      if (
+        (e.metaKey || e.ctrlKey) &&
+        e.key.toLowerCase() === "a" &&
+        !e.shiftKey &&
+        !e.altKey &&
+        !isEditableEventTarget(e.target)
+      ) {
+        e.preventDefault();
+        store.selectAll();
+        return;
+      }
+
       if (sel.size === 0 || !m) return;
       const arrow = e.key;
-      if (!shouldHandleCaptionNudgeKey(e)) return;
+      // Pass the event target so arrows inside inputs keep their native
+      // behavior instead of nudging the canvas word.
+      if (!shouldHandleCaptionNudgeKey(e, e.target)) return;
 
       e.preventDefault();
       const step = e.shiftKey ? 10 : 1;
@@ -129,12 +223,21 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
           break;
         }
       }
+      scheduleTick();
     };
 
     window.addEventListener("keydown", handleKeyDown);
     return () => {
-      clearInterval(id);
+      unregisterIframe();
+      unsubPlayer();
+      unsubPlayback();
+      if (playInterval !== null) clearInterval(playInterval);
+      if (rafId !== null) cancelAnimationFrame(rafId);
+      resizeObserver.disconnect();
+      window.removeEventListener("message", handleMessage);
+      window.removeEventListener("resize", scheduleTick);
       window.removeEventListener("keydown", handleKeyDown);
+      cancelDragRef.current = null;
     };
   });
 
@@ -297,6 +400,13 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
       onPointerUp={handlePointerUp}
       onLostPointerCapture={handlePointerUp}
     >
+      {wordBoxes.length === 0 && model && model.segments.size > 0 && (
+        <div className="absolute inset-x-0 top-3 flex justify-center pointer-events-none">
+          <span className="px-2.5 py-1 rounded-full bg-black/60 border border-neutral-700 text-2xs text-neutral-300">
+            No captions visible at this frame — scrub to a caption, or select one in the track below
+          </span>
+        </div>
+      )}
       {wordBoxes.map((box) => {
         const isSelected = selectedSegmentIds.has(box.segmentId);
         return (
@@ -325,23 +435,33 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
           >
             {isSelected && (
               <>
-                {/* Rotation handle — circle above the box */}
+                {/* Rotation handle — 24px hit area around an 8px dot */}
                 <div
                   style={{
                     position: "absolute",
                     left: "50%",
-                    top: -ROTATION_OFFSET - HANDLE,
-                    marginLeft: -HANDLE / 2,
-                    width: HANDLE,
-                    height: HANDLE,
-                    borderRadius: "50%",
-                    backgroundColor: "var(--hf-accent, #3CE6AC)",
-                    border: "1px solid rgba(0,0,0,0.5)",
+                    top: -ROTATION_OFFSET - HANDLE / 2 - HANDLE_HIT / 2,
+                    marginLeft: -HANDLE_HIT / 2,
+                    width: HANDLE_HIT,
+                    height: HANDLE_HIT,
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
                     cursor: "grab",
                     touchAction: "none",
                   }}
                   onPointerDown={(e) => startRotate(box, e)}
-                />
+                >
+                  <div
+                    style={{
+                      width: HANDLE,
+                      height: HANDLE,
+                      borderRadius: "50%",
+                      backgroundColor: "var(--hf-accent, #3CE6AC)",
+                      border: "1px solid rgba(0,0,0,0.5)",
+                    }}
+                  />
+                </div>
                 {/* Line from box to rotation handle */}
                 <div
                   style={{
@@ -356,29 +476,52 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
                     pointerEvents: "none",
                   }}
                 />
-                {/* Scale handles — four corners */}
+                {/* Scale handles — four corners, 24px hit areas around 8px dots */}
                 {[
-                  { right: -HANDLE / 2, bottom: -HANDLE / 2, cursor: "nwse-resize" },
-                  { left: -HANDLE / 2, top: -HANDLE / 2, cursor: "nwse-resize" },
-                  { right: -HANDLE / 2, top: -HANDLE / 2, cursor: "nesw-resize" },
-                  { left: -HANDLE / 2, bottom: -HANDLE / 2, cursor: "nesw-resize" },
-                ].map((pos, idx) => (
+                  {
+                    corner: { right: -HANDLE_HIT / 2, bottom: -HANDLE_HIT / 2 },
+                    cursor: "nwse-resize",
+                  },
+                  {
+                    corner: { left: -HANDLE_HIT / 2, top: -HANDLE_HIT / 2 },
+                    cursor: "nwse-resize",
+                  },
+                  {
+                    corner: { right: -HANDLE_HIT / 2, top: -HANDLE_HIT / 2 },
+                    cursor: "nesw-resize",
+                  },
+                  {
+                    corner: { left: -HANDLE_HIT / 2, bottom: -HANDLE_HIT / 2 },
+                    cursor: "nesw-resize",
+                  },
+                ].map(({ corner, cursor }, idx) => (
                   <div
                     key={idx}
                     style={{
                       position: "absolute",
-                      ...pos,
-                      width: HANDLE,
-                      height: HANDLE,
-                      backgroundColor: "var(--hf-accent, #3CE6AC)",
-                      border: "1px solid rgba(0,0,0,0.5)",
-                      borderRadius: 2,
+                      ...corner,
+                      width: HANDLE_HIT,
+                      height: HANDLE_HIT,
+                      display: "flex",
+                      alignItems: "center",
+                      justifyContent: "center",
+                      cursor,
                       touchAction: "none",
                     }}
                     onPointerDown={(e) =>
                       startScale(box.groupIndex, box.wordIndex, box.segmentId, e)
                     }
-                  />
+                  >
+                    <div
+                      style={{
+                        width: HANDLE,
+                        height: HANDLE,
+                        backgroundColor: "var(--hf-accent, #3CE6AC)",
+                        border: "1px solid rgba(0,0,0,0.5)",
+                        borderRadius: 2,
+                      }}
+                    />
+                  </div>
                 ))}
               </>
             )}

package/src/captions/components/CaptionOverlayUtils.ts

@@ -205,6 +205,60 @@ export function writeTransform(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Iframe registry — lets non-component code (undo/redo in useAppHotkeys)
+// reapply a restored model's transforms to the live preview.
+// ---------------------------------------------------------------------------
+
+let registeredIframe: React.RefObject<HTMLIFrameElement | null> | null = null;
+
+export function registerCaptionIframe(ref: React.RefObject<HTMLIFrameElement | null>): () => void {
+  registeredIframe = ref;
+  return () => {
+    if (registeredIframe === ref) registeredIframe = null;
+  };
+}
+
+/**
+ * True when the caption preview iframe is mounted AND visible. The caption
+ * store's isEditMode stays true while the preview is merely hidden (e.g.
+ * storyboard view), so hotkeys must not route ⌘Z to the caption stack unless
+ * the user can actually see the captions the undo would change.
+ */
+export function isCaptionPreviewVisible(): boolean {
+  const iframe = registeredIframe?.current;
+  return Boolean(iframe?.isConnected && iframe.offsetParent !== null);
+}
+
+/** Reapply every segment's transform from a (restored) model to the preview DOM. */
+export function applyCaptionModelToIframe(model: {
+  groupOrder: string[];
+  groups: Map<string, { segmentIds: string[] }>;
+  segments: Map<string, { style: { x?: number; y?: number; scaleX?: number; rotation?: number } }>;
+}): void {
+  const iframe = registeredIframe?.current;
+  if (!iframe) return;
+  let win: Window | null = null;
+  try {
+    win = iframe.contentWindow;
+  } catch {
+    return;
+  }
+  if (!win) return;
+  for (let gi = 0; gi < model.groupOrder.length; gi++) {
+    const group = model.groups.get(model.groupOrder[gi]);
+    if (!group) continue;
+    for (let wi = 0; wi < group.segmentIds.length; wi++) {
+      const seg = model.segments.get(group.segmentIds[wi]);
+      if (!seg) continue;
+      const wordEl = getWordEl(iframe, gi, wi);
+      if (!wordEl) continue;
+      const s = seg.style;
+      writeTransform(wordEl, win, s.x ?? 0, s.y ?? 0, s.scaleX ?? 1, s.rotation ?? 0);
+    }
+  }
+}
+
 /** 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);