@hyperframes/studio 0.8.55 → 0.8.57

package/src/hooks/appHotkeysDispatch.ts

@@ -54,6 +54,11 @@ export interface HotkeyCallbacks {
   onUngroupSelection?: () => void;
   domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
+  readOnlyPreview: boolean;
+}
+
+function timelineOwnsKey(event: KeyboardEvent): boolean {
+  return event.target instanceof Element && event.target.closest("[data-studio-timeline]") !== null;
 }
 
 /** Exported for tests, like dispatchPlainKey below: lets the Cmd+C/Cmd+V
@@ -95,6 +100,7 @@ export function dispatchModifierKey(
 
   if (key === "g" && !event.altKey && !isTypingTarget(event.target)) {
     event.preventDefault();
+    if (cb.readOnlyPreview) return true;
     if (event.shiftKey) cb.onUngroupSelection?.();
     else cb.onGroupSelection?.();
     return true;
@@ -113,6 +119,12 @@ export function dispatchModifierKey(
       }
       return true;
     }
+    const previewOwnsMutation =
+      cb.readOnlyPreview && cb.domEditSelectionRef.current !== null && !timelineOwnsKey(event);
+    if (previewOwnsMutation && ["v", "x", "d"].includes(key)) {
+      event.preventDefault();
+      return true;
+    }
     if (key === "v") {
       event.preventDefault();
       trackStudioEvent("keyboard_shortcut", { action: "paste" });
@@ -158,6 +170,7 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
     // Reserve bare `s` for Split even when the current selection cannot split,
     // so secondary listeners do not reinterpret the same key as Snap toggle.
     event.preventDefault();
+    if (cb.readOnlyPreview) return;
     const { selectedElementId, elements, currentTime } = usePlayerStore.getState();
     if (selectedElementId) {
       const el = elements.find((e) => (e.key ?? e.id) === selectedElementId);
@@ -240,8 +253,10 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
     // the timeline left other selected elements behind. Timeline stays as the
     // fallback for rows with no canvas node (audio, an inactive comp).
     const domSel = cb.domEditSelectionRef.current;
-    if (domSel) {
+    const timelineOwnsDelete = timelineOwnsKey(event);
+    if (domSel && !timelineOwnsDelete) {
       event.preventDefault();
+      if (cb.readOnlyPreview) return;
       // The whole marquee group, not just the primary the ref holds.
       void cb.handleDomEditElementDelete(domSel, { expandGroup: true });
       return;

package/src/hooks/newTweenTargetHooks.test.tsx

@@ -196,6 +196,7 @@ function renderGestureCommit(
       previewIframeRef: { current: document.createElement("iframe") },
       showToast: vi.fn(),
       isGestureRecordingRef: { current: false },
+      readOnlyPreview: false,
     });
     toggle = handleToggleRecording;
     return null;

package/src/hooks/timelineAudioGroupCreate.ts

@@ -8,7 +8,6 @@
 
 import { useCallback } from "react";
 import { usePlayerStore, type TimelineElement } from "../player";
-import { useTimelineRowElements } from "../player/hooks/useTimelineRowElements";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import { HF_AUDIO_GROUP_ATTR, HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
 import { runtimeAudioId } from "../player/lib/timelineElementHelpers";
@@ -286,7 +285,7 @@ export function useAudioGroupCarveAssignment({
   groupId: string,
   groupLabel?: string,
 ) => Promise<void> {
-  const expandedElements = useTimelineRowElements();
+  const timelineElements = usePlayerStore((state) => state.elements);
   return useCallback(
     async (clipIds: readonly string[], groupId: string, groupLabel?: string) => {
       if (isRecordingRef?.current) {
@@ -299,7 +298,7 @@ export function useAudioGroupCarveAssignment({
       // timeline's group-pointer button) name clips the way the document does,
       // because that is the only space `resolveAudioGroups` reads back.
       const wanted = new Set(clipIds);
-      const elements = expandedElements.filter((item) => {
+      const elements = timelineElements.filter((item) => {
         const domId = runtimeAudioId(item);
         return domId !== null && wanted.has(domId);
       });
@@ -340,7 +339,7 @@ export function useAudioGroupCarveAssignment({
     },
     [
       activeCompPath,
-      expandedElements,
+      timelineElements,
       previewIframeRef,
       writeProjectFile,
       recordEdit,

package/src/hooks/timelineTrackVisibility.ts

@@ -1,7 +1,6 @@
 import { useCallback } from "react";
 import { usePlayerStore, type TimelineElement } from "../player";
 import { reseekPreviewAtTime } from "../player/hooks/timelineSyncHydration";
-import { useTimelineRowElements } from "../player/hooks/useTimelineRowElements";
 import { applySoftReloadFinalization } from "../utils/gsapSoftReload";
 import {
   timelineTrackOrder,
@@ -295,7 +294,7 @@ export function useTimelineTrackVisibilityEditing({
   // virtual sub-comp children carry their own (display.track + idx) track numbers,
   // so filtering the raw store list by a virtual track number would hide the wrong
   // outer-scene sibling sharing that index.
-  const expandedElements = useTimelineRowElements();
+  const timelineElements = usePlayerStore((state) => state.elements);
   return useCallback(
     async (track: number, hidden: boolean, displayNumber?: number | null) => {
       if (isRecordingRef?.current) {
@@ -308,7 +307,7 @@ export function useTimelineTrackVisibilityEditing({
         await toggleTimelineTrackHidden({
           projectId: pid,
           activeCompPath,
-          timelineElements: expandedElements,
+          timelineElements,
           track,
           hidden,
           displayNumber,
@@ -327,7 +326,7 @@ export function useTimelineTrackVisibilityEditing({
     },
     [
       activeCompPath,
-      expandedElements,
+      timelineElements,
       previewIframeRef,
       writeProjectFile,
       recordEdit,
@@ -354,7 +353,7 @@ export function useTimelineElementVisibilityEditing({
   elementKey: string | readonly string[],
   hidden: boolean,
 ) => Promise<void> {
-  const expandedElements = useTimelineRowElements();
+  const timelineElements = usePlayerStore((state) => state.elements);
   return useCallback(
     async (elementKey: string | readonly string[], hidden: boolean) => {
       if (isRecordingRef?.current) {
@@ -364,7 +363,7 @@ export function useTimelineElementVisibilityEditing({
       const pid = projectIdRef.current;
       if (!pid) return;
       const keys = typeof elementKey === "string" ? [elementKey] : elementKey;
-      if (!expandedElements.some((item) => keys.includes(item.key ?? item.id))) {
+      if (!timelineElements.some((item) => keys.includes(item.key ?? item.id))) {
         showToast("This element is inside a sub-composition and has no timeline row to hide.");
         return;
       }
@@ -372,7 +371,7 @@ export function useTimelineElementVisibilityEditing({
         await toggleTimelineElementHidden({
           projectId: pid,
           activeCompPath,
-          timelineElements: expandedElements,
+          timelineElements,
           elementKey,
           hidden,
           previewIframe: previewIframeRef.current,
@@ -390,7 +389,7 @@ export function useTimelineElementVisibilityEditing({
     },
     [
       activeCompPath,
-      expandedElements,
+      timelineElements,
       previewIframeRef,
       writeProjectFile,
       recordEdit,

package/src/hooks/useAppHotkeys.test.ts

@@ -1,7 +1,8 @@
 // @vitest-environment happy-dom
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { dispatchModifierKey, dispatchPlainKey } from "./appHotkeysDispatch";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { dispatchModifierKey, dispatchPlainKey, type HotkeyCallbacks } from "./appHotkeysDispatch";
 import { usePlayerStore } from "../player/store/playerStore";
+import type { DomEditSelection } from "../components/editor/domEditing";
 import { clearAutomationClipboard, copyRange } from "../player/components/automationClipboard";
 import { VOLUME_RANGE } from "@hyperframes/core/audio-automation";
 import type { TimelineElement } from "../player/store/timelineElement";
@@ -19,7 +20,7 @@ const bgmElement: TimelineElement = {
 /** Every callback dispatchPlainKey can reach, so a test can assert which one
  *  a key resolved to. Unannotated on purpose: the parameter type is not
  *  exported, and structural inference checks it at the call site. */
-function callbacks() {
+function callbacks(overrides: Partial<HotkeyCallbacks> = {}) {
   return {
     handleTimelineElementDelete: vi.fn(async () => {}),
     handleTimelineElementsDelete: vi.fn(async () => {}),
@@ -30,10 +31,15 @@ function callbacks() {
     handleCopy: vi.fn(() => false),
     handlePaste: vi.fn(async () => {}),
     handleCut: vi.fn(async () => false),
+    handleDuplicate: vi.fn(async () => false),
+    onGroupSelection: vi.fn(),
+    onUngroupSelection: vi.fn(),
     onResetKeyframes: vi.fn(() => true),
     onDeleteSelectedKeyframes: vi.fn(),
     showToast: vi.fn(),
     domEditSelectionRef: { current: null },
+    readOnlyPreview: false,
+    ...overrides,
   };
 }
 
@@ -298,3 +304,65 @@ describe('dispatchPlainKey — "A" returns to select while the razor is armed',
     expect(e.defaultPrevented).toBe(false);
   });
 });
+
+describe("hotkeys with the preview read-only", () => {
+  beforeEach(() => {
+    usePlayerStore.setState({ elements: [bgmElement], selectedElementId: null });
+  });
+
+  it("does not delete the selected element on Delete", () => {
+    const cb = callbacks({ readOnlyPreview: true });
+    cb.domEditSelectionRef.current = { id: "card" } as DomEditSelection;
+    dispatchPlainKey(press("Delete"), "delete", cb);
+    expect(cb.handleDomEditElementDelete).not.toHaveBeenCalled();
+    expect(cb.handleTimelineElementsDelete).not.toHaveBeenCalled();
+  });
+
+  it("does not split on s", () => {
+    usePlayerStore.setState({
+      currentTime: 3,
+      elements: [{ ...bgmElement, hfId: "hf-bgm" }],
+      selectedElementId: "bgm",
+    });
+    const cb = callbacks({ readOnlyPreview: true });
+    dispatchPlainKey(press("s"), "s", cb);
+    expect(cb.handleTimelineElementSplit).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["x", "handleCut"],
+    ["d", "handleDuplicate"],
+    ["v", "handlePaste"],
+    ["g", "onGroupSelection"],
+  ] as const)("does not run %s", (key, callback) => {
+    const cb = callbacks({ readOnlyPreview: true });
+    cb.domEditSelectionRef.current = { id: "card" } as DomEditSelection;
+    dispatchModifierKey(chord(key), key, cb);
+    expect(cb[callback]).not.toHaveBeenCalled();
+  });
+
+  it("still undoes, because history covers timeline edits", () => {
+    const cb = callbacks({ readOnlyPreview: true });
+    dispatchModifierKey(chord("z"), "z", cb);
+    expect(cb.handleUndo).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps timeline paste when the mirrored preview selection is not the owner", () => {
+    usePlayerStore.setState({ selectedElementId: "bgm" });
+    const cb = callbacks({ readOnlyPreview: true });
+    cb.domEditSelectionRef.current = { id: "card" } as DomEditSelection;
+    const event = chord("v");
+    const timeline = document.createElement("div");
+    timeline.dataset.studioTimeline = "true";
+    Object.defineProperty(event, "target", { value: timeline });
+    dispatchModifierKey(event, "v", cb);
+    expect(cb.handlePaste).toHaveBeenCalledTimes(1);
+  });
+
+  it("control: with the flag off Delete removes the selected element", () => {
+    const cb = callbacks();
+    cb.domEditSelectionRef.current = { id: "card" } as DomEditSelection;
+    dispatchPlainKey(press("Delete"), "delete", cb);
+    expect(cb.handleDomEditElementDelete).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useAppHotkeys.textEditing.test.tsx

@@ -93,6 +93,7 @@ function Harness() {
     handleDuplicate: vi.fn(async () => false),
     onResetKeyframes: vi.fn(() => false),
     onDeleteSelectedKeyframes: keyframeDelete,
+    readOnlyPreview: false,
   });
 
   return (

package/src/hooks/useAppHotkeys.ts

@@ -101,6 +101,8 @@ interface UseAppHotkeysParams {
   onUngroupSelection?: () => void;
   /** Active composition path — used to decide whether undo/redo must resync the SDK session. */
   activeCompPath?: string | null;
+  /** Clicks still select and report; the preview cannot move, edit or delete anything. */
+  readOnlyPreview: boolean;
   /**
    * Force-reload the SDK session after undo/redo reverts the active comp file,
    * bypassing the self-write suppress window. Without this, the suppress window
@@ -135,6 +137,7 @@ export function useAppHotkeys({
   onUngroupSelection,
   activeCompPath,
   forceReloadSdkSession,
+  readOnlyPreview,
 }: UseAppHotkeysParams) {
   const previewHistoryCleanupRef = useRef<(() => void) | null>(null);
 
@@ -203,6 +206,7 @@ export function useAppHotkeys({
     onUngroupSelection,
     domEditSelectionRef,
     showToast,
+    readOnlyPreview,
   };
 
   // ── Keydown dispatch ──

package/src/hooks/useCompositionDimensions.test.tsx

@@ -3,6 +3,7 @@ import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { expect, it } from "vitest";
 import { useCompositionDimensions } from "./useCompositionDimensions";
+import { usePreviewIframeStore } from "../player/store/previewIframeStore";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
@@ -45,3 +46,40 @@ it("accepts only the current preview frame and rejects foreign or missing sender
     foreign.remove();
   }
 });
+
+it("re-reads the size from the promoted iframe's document", () => {
+  const host = document.createElement("div");
+  const a = document.createElement("iframe");
+  const b = document.createElement("iframe");
+  document.body.append(host, a, b);
+  const ref = { current: a };
+  const root = createRoot(host);
+  const setRoot = (frame: HTMLIFrameElement, width: number, height: number) => {
+    const el = frame.contentDocument!.createElement("div");
+    el.setAttribute("data-composition-id", "main");
+    el.setAttribute("data-width", String(width));
+    el.setAttribute("data-height", String(height));
+    frame.contentDocument!.body.append(el);
+  };
+  setRoot(a, 1920, 1080);
+  setRoot(b, 1080, 1920);
+  function Harness() {
+    return JSON.stringify(useCompositionDimensions(ref));
+  }
+  try {
+    act(() => usePreviewIframeStore.getState().setIframe(a));
+    act(() => root.render(<Harness />));
+    expect(host.textContent).toBe('{"width":1920,"height":1080}');
+    act(() => {
+      ref.current = b;
+      usePreviewIframeStore.getState().setIframe(b);
+    });
+    expect(host.textContent).toBe('{"width":1080,"height":1920}');
+  } finally {
+    act(() => root.unmount());
+    usePreviewIframeStore.setState({ iframe: null });
+    host.remove();
+    a.remove();
+    b.remove();
+  }
+});

package/src/hooks/useCompositionDimensions.ts

@@ -1,4 +1,6 @@
-import { useState, type RefObject } from "react";
+import { useEffect, useState, type RefObject } from "react";
+import { useLivePreviewIframe } from "../player/store/previewIframeStore";
+import { readPreviewCompositionSize } from "../utils/previewCompositionSize";
 import { useMountEffect } from "./useMountEffect";
 import type { CompositionDimensions } from "../components/renders/RenderQueue";
 import { acceptStudioRuntimeMessage } from "../player/lib/runtimeProtocol";
@@ -34,6 +36,20 @@ export function useCompositionDimensions(iframeRef: RefObject<HTMLIFrameElement
     null,
   );
 
+  const livePreviewIframe = useLivePreviewIframe();
+
+  // The runtime posts stage-size once per document, so a promoted reload's message was sent
+  // before this listener could accept it. The size is authored on the document: read it there.
+  useEffect(() => {
+    const dimensions = readPreviewCompositionSize(livePreviewIframe);
+    if (!dimensions) return;
+    setCompositionDimensions((prev) =>
+      prev && prev.width === dimensions.width && prev.height === dimensions.height
+        ? prev
+        : dimensions,
+    );
+  }, [livePreviewIframe]);
+
   useMountEffect(() => {
     const handleMessage = (e: MessageEvent) => {
       if (!e.source || e.source !== iframeRef.current?.contentWindow) return;

package/src/hooks/useDomEditAttributeCommits.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { resolveOptimisticAttributeValue } from "./useDomEditAttributeCommits";
+
+describe("resolveOptimisticAttributeValue", () => {
+  it("removes an HTML boolean attribute when the value is the literal string false", () => {
+    expect(resolveOptimisticAttributeValue("loop", "false")).toBeNull();
+    expect(resolveOptimisticAttributeValue("muted", "false")).toBeNull();
+  });
+
+  it("keeps the literal string false for a non-boolean attribute, matching what persist() writes", () => {
+    expect(resolveOptimisticAttributeValue("data-example", "false")).toBe("false");
+  });
+
+  it("always removes on null regardless of attribute", () => {
+    expect(resolveOptimisticAttributeValue("loop", null)).toBeNull();
+    expect(resolveOptimisticAttributeValue("data-example", null)).toBeNull();
+  });
+
+  it("passes any other value through unchanged", () => {
+    expect(resolveOptimisticAttributeValue("data-example", "true")).toBe("true");
+    expect(resolveOptimisticAttributeValue("loop", "true")).toBe("true");
+  });
+});

package/src/hooks/useDomEditAttributeCommits.ts

@@ -1,5 +1,5 @@
 import { useCallback, useRef } from "react";
-import type { PatchOperation } from "../utils/sourcePatcher";
+import { HTML_BOOLEAN_ATTRIBUTES, type PatchOperation } from "../utils/sourcePatcher";
 import {
   findElementForSelection,
   getDomEditTargetKey,
@@ -55,6 +55,14 @@ function resolveFullAttrName(attr: string, prefixData: boolean | undefined): str
   return prefixData && !attr.startsWith("data-") ? `data-${attr}` : attr;
 }
 
+// Matches sourcePatcher's own boolean handling: "false" means "remove" only
+// for HTML_BOOLEAN_ATTRIBUTES (loop, muted, ...), so the live preview node
+// ends up holding what persist() actually writes to disk.
+export function resolveOptimisticAttributeValue(attr: string, value: string | null): string | null {
+  if (value === null) return null;
+  return value === "false" && HTML_BOOLEAN_ATTRIBUTES.has(attr) ? null : value;
+}
+
 function setOrRemovePreviewAttribute(
   el: HTMLElement,
   fullAttr: string,
@@ -393,8 +401,11 @@ export function useDomEditAttributeCommits({
         },
         apply: () => {
           if (!editedElement) return;
-          const nextValue = value === null || value === "false" ? null : value;
-          setOrRemovePreviewAttribute(editedElement, attr, nextValue);
+          setOrRemovePreviewAttribute(
+            editedElement,
+            attr,
+            resolveOptimisticAttributeValue(attr, value),
+          );
         },
         persist: () =>
           persistDomEditOperations(domEditSelection, [op], {

package/src/hooks/useDomEditCommits.test.tsx

@@ -230,6 +230,7 @@ function renderDomEditCommits(
       refreshDomEditSelectionFromPreview: vi.fn(),
       buildDomSelectionFromTarget: vi.fn(async () => null),
       onTrySdkPersist: options.onTrySdkPersist,
+      readOnlyPreview: false,
     });
     return null;
   }

package/src/hooks/useDomEditCommits.ts

@@ -89,6 +89,7 @@ export interface UseDomEditCommitsParams {
   ) => Promise<CutoverResult>;
   /** Resolver-shadow tripwire for z-index reorder targets (telemetry-only, decoupled from cutover). */
   onReorderShadow?: (targets: string[]) => void;
+  readOnlyPreview: boolean;
 }
 
 export function useDomEditCommits({
@@ -112,6 +113,7 @@ export function useDomEditCommits({
   onTrySdkPersist,
   onTrySdkDelete,
   onReorderShadow,
+  readOnlyPreview,
 }: UseDomEditCommitsParams) {
   const resolveImportedFontAsset = useCallback(
     (fontFamilyValue: string): ImportedFontAsset | null => {
@@ -452,6 +454,7 @@ export function useDomEditCommits({
     previewIframeRef,
     showToast,
     commitPositionPatchToHtml,
+    readOnlyPreview,
   });
 
   // ── Element lifecycle (delete, z-index reorder) ──

package/src/hooks/useDomEditSession.test.tsx

@@ -99,6 +99,7 @@ function createSessionParams(
     reloadPreview: vi.fn(),
     setRefreshKey: vi.fn(),
     handleTimelineElementsDelete: vi.fn(),
+    readOnlyPreview: false,
     ...overrides,
   };
 }

package/src/hooks/useDomEditSession.ts

@@ -58,6 +58,7 @@ export interface UseDomEditSessionParams extends DomEditTimelineParams {
   /** The timeline context menu's delete op — a canvas selection that IS a
    *  timeline row hands off here instead of the REST remove-elements path. */
   handleTimelineElementsDelete: (elements: TimelineElement[]) => Promise<void>;
+  readOnlyPreview: boolean;
 }
 
 export function useDomEditSession({
@@ -98,8 +99,10 @@ export function useDomEditSession({
   publishSdkSession,
   forceReloadSdkSession,
   handleTimelineElementsDelete,
+  readOnlyPreview,
 }: UseDomEditSessionParams) {
   const isMasterView = !activeCompPath || activeCompPath === "index.html";
+  const previewCaptionEditMode = captionEditMode && !readOnlyPreview;
   void _setRefreshKey;
   const {
     domEditSelection,
@@ -125,7 +128,7 @@ export function useDomEditSession({
     activeCompPath,
     isMasterView,
     compIdToSrc,
-    captionEditMode,
+    captionEditMode: previewCaptionEditMode,
     previewIframeRef,
     timelineElements,
     getTimelineSelectionSet,
@@ -247,6 +250,7 @@ export function useDomEditSession({
     refreshDomEditSelectionFromPreview,
     buildDomSelectionFromTarget,
     forceReloadSdkSession,
+    readOnlyPreview,
     onTrySdkPersist: sdkSession
       ? (selection, operations, originalContent, targetPath, options) => {
           // Decoupled tripwire, runs regardless of the cutover flag. originalContent lets
@@ -405,7 +409,6 @@ export function useDomEditSession({
     handleGsapRemoveAllKeyframes,
     handleResetSelectedElementKeyframes,
   } = useDomEditWiring({
-    // fallow-ignore-next-line code-duplication
     projectId,
     activeCompPath,
     domEditSelection,
@@ -414,7 +417,7 @@ export function useDomEditSession({
     refreshDomEditGroupSelectionsFromPreview,
     previewIframeRef,
     previewIframe,
-    captionEditMode,
+    captionEditMode: previewCaptionEditMode,
     refreshKey,
     gsapCacheVersion,
     bumpGsapCache,
@@ -451,7 +454,7 @@ export function useDomEditSession({
     handleBlockedDomMove,
     handleDomManualDragStart,
   } = usePreviewInteraction({
-    captionEditMode,
+    captionEditMode: previewCaptionEditMode,
     compositionLoading,
     previewIframeRef,
     showToast,

package/src/hooks/useDomEditWiring.ts

@@ -109,46 +109,46 @@ export interface UseDomEditWiringParams {
 }
 
 // fallow-ignore-next-line complexity
-export function useDomEditWiring({
-  // fallow-ignore-next-line code-duplication
-  projectId,
-  activeCompPath,
-  domEditSelection,
-  domEditSelectionRef,
-  domEditGroupSelectionsRef,
-  refreshDomEditGroupSelectionsFromPreview,
-  previewIframeRef,
-  previewIframe,
-  captionEditMode,
-  refreshKey,
-  gsapCacheVersion,
-  bumpGsapCache,
-  showToast,
-  refreshPreviewDocumentVersion,
-  syncPreviewHotkeys,
-  applyStudioManualEditsToPreviewRef,
-  applyDomSelection,
-  buildDomSelectionFromTarget,
-  openSourceForSelection,
-  updateGsapProperty,
-  updateGsapMeta,
-  deleteGsapAnimation,
-  deleteAllForSelector,
-  addGsapAnimation,
-  addGsapProperty,
-  removeGsapProperty,
-  updateGsapFromProperty,
-  addGsapFromProperty,
-  removeGsapFromProperty,
-  addKeyframe,
-  addKeyframeBatch,
-  removeKeyframe,
-  moveKeyframe,
-  resizeKeyframedTween,
-  convertToKeyframes,
-  removeAllKeyframes,
-  handleDomManualEditsReset,
-}: UseDomEditWiringParams) {
+export function useDomEditWiring(params: UseDomEditWiringParams) {
+  const {
+    projectId,
+    activeCompPath,
+    domEditSelection,
+    domEditSelectionRef,
+    domEditGroupSelectionsRef,
+    refreshDomEditGroupSelectionsFromPreview,
+    previewIframeRef,
+    previewIframe,
+    captionEditMode,
+    refreshKey,
+    gsapCacheVersion,
+    bumpGsapCache,
+    showToast,
+    refreshPreviewDocumentVersion,
+    syncPreviewHotkeys,
+    applyStudioManualEditsToPreviewRef,
+    applyDomSelection,
+    buildDomSelectionFromTarget,
+    openSourceForSelection,
+    updateGsapProperty,
+    updateGsapMeta,
+    deleteGsapAnimation,
+    deleteAllForSelector,
+    addGsapAnimation,
+    addGsapProperty,
+    removeGsapProperty,
+    updateGsapFromProperty,
+    addGsapFromProperty,
+    removeGsapFromProperty,
+    addKeyframe,
+    addKeyframeBatch,
+    removeKeyframe,
+    moveKeyframe,
+    resizeKeyframedTween,
+    convertToKeyframes,
+    removeAllKeyframes,
+    handleDomManualEditsReset,
+  } = params;
   // ── Click-to-source navigation ──
 
   const onClickToSource = useCallback(