@hyperframes/studio 0.8.104 → 0.8.106

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -13,6 +13,9 @@ import {
   readStudioRotation,
 } from "../components/editor/manualEdits";
 import { useDomGeometryCommits, type UseDomGeometryCommitsParams } from "./useDomGeometryCommits";
+import { reapplyPositionEditsAfterSeek } from "../components/editor/manualEdits";
+import { writeTranslatePx } from "../components/editor/plainTranslate";
+import { applyPatch } from "../utils/sourcePatcher";
 import { DomEditCropHandles } from "../components/editor/DomEditCropHandles";
 import { withInlineLayoutBox } from "./domSelectionTestHarness";
 
@@ -25,7 +28,6 @@ function mountCommits(
   let commits: ReturnType<typeof useDomGeometryCommits> | null = null;
   function Probe() {
     commits = useDomGeometryCommits({
-      previewIframeRef: { current: null },
       showToast: vi.fn(),
       commitPositionPatchToHtml,
       readOnlyPreview,
@@ -61,7 +63,6 @@ describe("useDomGeometryCommits rollback", () => {
 
     function Probe() {
       commits = useDomGeometryCommits({
-        previewIframeRef: { current: null },
         showToast: vi.fn(),
         commitPositionPatchToHtml,
         readOnlyPreview: false,
@@ -70,9 +71,6 @@ describe("useDomGeometryCommits rollback", () => {
     }
 
     act(() => root.render(<Probe />));
-    await expect(commits!.handleDomPathOffsetCommit(selection, { x: 50, y: 60 })).rejects.toBe(
-      failure,
-    );
     await expect(
       commits!.handleDomBoxSizeCommit(selection, { width: 200, height: 160 }, { x: 30, y: 40 }),
     ).rejects.toBe(failure);
@@ -90,20 +88,6 @@ describe("useDomGeometryCommits read-only preview", () => {
   const selectionOn = (element: HTMLElement) =>
     ({ id: element.id, selector: `#${element.id}`, element }) as unknown as DomEditSelection;
 
-  it("refuses a manual offset commit: no write, no history entry", async () => {
-    const element = document.createElement("div");
-    element.id = "ro-offset";
-    document.body.append(element);
-    applyStudioPathOffset(element, { x: 1, y: 2 });
-    const commitPositionPatchToHtml =
-      vi.fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>();
-    const { commits, unmount } = mountCommits(commitPositionPatchToHtml, true);
-    await commits().handleDomPathOffsetCommit(selectionOn(element), { x: 99, y: 99 });
-    expect(readStudioPathOffset(element)).toEqual({ x: 1, y: 2 });
-    expect(commitPositionPatchToHtml).not.toHaveBeenCalled();
-    unmount();
-  });
-
   it("refuses a manual box-size commit: no write, no history entry", async () => {
     const element = document.createElement("div");
     element.id = "ro-size";
@@ -131,19 +115,6 @@ describe("useDomGeometryCommits read-only preview", () => {
     expect(commitPositionPatchToHtml).not.toHaveBeenCalled();
     unmount();
   });
-
-  it("still commits an offset with the flag off", async () => {
-    const element = document.createElement("div");
-    element.id = "rw-offset";
-    document.body.append(element);
-    const commitPositionPatchToHtml = vi
-      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
-      .mockResolvedValue(undefined);
-    const { commits, unmount } = mountCommits(commitPositionPatchToHtml);
-    await commits().handleDomPathOffsetCommit(selectionOn(element), { x: 5, y: 6 });
-    expect(commitPositionPatchToHtml).toHaveBeenCalledTimes(1);
-    unmount();
-  });
 });
 
 describe("useDomGeometryCommits element position offset", () => {
@@ -230,6 +201,180 @@ describe("useDomGeometryCommits resize rollback", () => {
   });
 });
 
+describe("a plain move of an element an older Studio moved by its offset vars", () => {
+  function legacyMoved() {
+    const element = document.createElement("div");
+    element.id = "legacy";
+    element.style.setProperty("translate", "10px 5px");
+    document.body.append(element);
+    applyStudioPathOffset(element, { x: 40, y: 30 });
+    const selection = { id: "legacy", selector: "#legacy", element } as unknown as DomEditSelection;
+    return { element, selection };
+  }
+  const legacyEnds = [
+    { type: "inline-style", property: "--hf-studio-offset-x", value: null },
+    { type: "inline-style", property: "--hf-studio-offset-y", value: null },
+    { type: "attribute", property: "data-hf-studio-path-offset", value: null },
+  ];
+  const keptMarks = [
+    "data-hf-studio-original-inline-translate",
+    "data-hf-studio-original-translate",
+  ];
+  const studioMarks = (el: HTMLElement) =>
+    el
+      .getAttributeNames()
+      .filter((name) => name.startsWith("data-hf-studio"))
+      .sort();
+
+  it("saves the move as its translate, ends the old offset, and a seek keeps it", async () => {
+    const { element, selection } = legacyMoved();
+    const commitPositionPatchToHtml = vi
+      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
+      .mockResolvedValue(undefined);
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml);
+
+    await commits().stageElementPositionOffset(selection, { x: 140, y: 30 }, true).save();
+    reapplyPositionEditsAfterSeek(document);
+
+    expect(element.style.getPropertyValue("translate")).toBe("140px 30px");
+    expect(commitPositionPatchToHtml.mock.calls[0]![1]).toEqual([
+      { type: "inline-style", property: "translate", value: "140px 30px" },
+      {
+        type: "attribute",
+        property: "data-hf-studio-original-inline-translate",
+        value: "10px 5px",
+      },
+      ...legacyEnds,
+    ]);
+    expect(studioMarks(element)).toEqual(keptMarks);
+    unmount();
+  });
+
+  it("resizes with the anchor as its translate, ends the old offset, and a seek keeps it", async () => {
+    const { element, selection } = legacyMoved();
+    const commit = vi
+      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
+      .mockResolvedValue(undefined);
+    const { commits, unmount } = mountCommits(commit);
+
+    await commits().handleDomBoxSizeCommit(selection, { width: 80, height: 60 }, { x: 60, y: 40 });
+    reapplyPositionEditsAfterSeek(document);
+
+    expect(element.style.getPropertyValue("translate")).toBe("60px 40px");
+    expect(commit.mock.calls[0]![1]).toEqual(expect.arrayContaining(legacyEnds));
+    expect(studioMarks(element)).toEqual(expect.arrayContaining(keptMarks));
+    expect(element.hasAttribute("data-hf-studio-path-offset")).toBe(false);
+    unmount();
+  });
+
+  it.each(["move", "resize"])(
+    "puts the old offset back whole when the %s save fails",
+    async (kind) => {
+      const { element, selection } = legacyMoved();
+      const translate = element.style.getPropertyValue("translate");
+      const { commits, unmount } = mountCommits(
+        vi.fn().mockRejectedValue(new Error("save failed")),
+      );
+
+      const save =
+        kind === "move"
+          ? commits().stageElementPositionOffset(selection, { x: 140, y: 30 }, true).save()
+          : commits().handleDomBoxSizeCommit(
+              selection,
+              { width: 80, height: 60 },
+              { x: 60, y: 40 },
+            );
+      await expect(save).rejects.toThrow();
+      expect(element.style.getPropertyValue("translate")).toBe(translate);
+      expect(element.hasAttribute("data-hf-studio-path-offset")).toBe(true);
+      expect(readStudioPathOffset(element)).toEqual({ x: 40, y: 30 });
+      unmount();
+    },
+  );
+});
+
+describe("Reset after a plain move puts the author's translate back", () => {
+  function authoredLayer(translate: string | null, legacy = false) {
+    const element = document.createElement("div");
+    element.id = "layer";
+    if (translate) element.style.setProperty("translate", translate);
+    document.body.append(element);
+    if (legacy) applyStudioPathOffset(element, { x: 40, y: 30 });
+    const project = { file: element.outerHTML, history: [] as string[] };
+    const commit = vi.fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>(
+      async (_selection, patches) => {
+        project.history.push(project.file);
+        project.file = patches.reduce((html, op) => applyPatch(html, "layer", op), project.file);
+      },
+    );
+    const selection = { id: "layer", selector: "#layer", element } as unknown as DomEditSelection;
+    return { element, selection, project, ...mountCommits(commit) };
+  }
+  const saved = (html: string) =>
+    new DOMParser().parseFromString(html, "text/html").getElementById("layer")!;
+  const studioLeftovers = (el: Element) => [
+    ...el.getAttributeNames().filter((name) => name.startsWith("data-hf-studio")),
+    ...((el as HTMLElement).style.cssText.match(/--hf-studio-[\w-]+/g) ?? []),
+  ];
+
+  it("restores an older Studio's layer to its authored 50% 10px, in the file and live", async () => {
+    const { element, selection, project, commits, unmount } = authoredLayer("50% 10px", true);
+
+    await commits().stageElementPositionOffset(selection, { x: 140, y: 30 }, true).save();
+    await commits().handleDomManualEditsReset(selection);
+
+    expect(saved(project.file).style.getPropertyValue("translate")).toBe("50% 10px");
+    expect(element.style.getPropertyValue("translate")).toBe("50% 10px");
+    expect(studioLeftovers(saved(project.file))).toEqual([]);
+    expect(studioLeftovers(element)).toEqual([]);
+    unmount();
+  });
+
+  it("restores the authored 12px 4px after a drag and a second move", async () => {
+    const { element, selection, project, commits, unmount } = authoredLayer("12px 4px");
+
+    writeTranslatePx(element, { x: 90, y: 0 });
+    await commits().stageElementPositionOffset(selection, { x: 140, y: 30 }, true).save();
+    await commits().stageElementPositionOffset(selection, { x: 200, y: 50 }, true).save();
+    await commits().handleDomManualEditsReset(selection);
+
+    expect(saved(project.file).style.getPropertyValue("translate")).toBe("12px 4px");
+    expect(element.style.getPropertyValue("translate")).toBe("12px 4px");
+    expect(studioLeftovers(saved(project.file))).toEqual([]);
+    unmount();
+  });
+
+  it("removes the translate of a layer that had none, in the file and live", async () => {
+    const { element, selection, project, commits, unmount } = authoredLayer(null);
+
+    await commits().stageElementPositionOffset(selection, { x: 140, y: 30 }, true).save();
+    await commits().handleDomManualEditsReset(selection);
+
+    expect(saved(project.file).style.getPropertyValue("translate")).toBe("");
+    expect(element.style.getPropertyValue("translate")).toBe("");
+    expect(studioLeftovers(saved(project.file))).toEqual([]);
+    unmount();
+  });
+
+  it("undo of the Reset brings the move back, and Reset still restores the author's", async () => {
+    const { selection, project, commits, unmount } = authoredLayer("12px 4px");
+
+    await commits().stageElementPositionOffset(selection, { x: 140, y: 30 }, true).save();
+    const moved = project.file;
+    await commits().handleDomManualEditsReset(selection);
+    project.file = project.history.pop()!;
+    expect(project.file).toBe(moved);
+
+    const reloaded = saved(project.file) as HTMLElement;
+    document.body.append(reloaded);
+    expect(reloaded.style.getPropertyValue("translate")).toBe("140px 30px");
+    await commits().handleDomManualEditsReset({ ...selection, element: reloaded });
+    expect(saved(project.file).style.getPropertyValue("translate")).toBe("12px 4px");
+    expect(reloaded.style.getPropertyValue("translate")).toBe("12px 4px");
+    unmount();
+  });
+});
+
 describe("useDomGeometryCommits resize of a cropped element", () => {
   it("saves the crop scaled per axis with the box in the resize's own commit", async () => {
     const element = withInlineLayoutBox(document.createElement("div"));

package/src/hooks/useDomGeometryCommits.ts

@@ -2,7 +2,6 @@ import type { RotationCommit } from "../components/editor/rotationDraft";
 import { useCallback } from "react";
 import { getDomEditTargetKey, type DomEditSelection } from "../components/editor/domEditing";
 import {
-  applyStudioPathOffset,
   applyStudioBoxSize,
   captureStudioPathOffset,
   captureStudioBoxSize,
@@ -17,35 +16,18 @@ import {
 import { stageElementOffset } from "./elementOffsetStager";
 import { savePlainRotation } from "./plainRotation";
 import { prepareCropResize } from "../components/editor/cropResize";
-import { translatePatch, writeTranslatePx } from "../components/editor/plainTranslate";
+import { writePlainMove } from "../components/editor/plainTranslate";
 import {
-  buildPathOffsetPatches,
   buildBoxSizePatches,
   buildClearPathOffsetPatches,
   buildClearBoxSizePatches,
   buildClearRotationPatches,
 } from "../components/editor/manualEditsDomPatches";
 import type { PatchOperation } from "../utils/sourcePatcher";
-import { isElementGsapTargeted } from "./gsapTargetCache";
-
-const GSAP_CSS_FALLBACK_BLOCKED_MESSAGE =
-  "This element is GSAP-animated — dragging via CSS would corrupt keyframes";
-
-function rejectGsapCssFallback(
-  selection: DomEditSelection,
-  previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>,
-  showToast: (message: string, tone?: "error" | "info") => void,
-): Promise<never> | null {
-  if (!isElementGsapTargeted(previewIframeRef.current, selection.element)) return null;
-  const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
-  showToast(error.message, "error");
-  return Promise.reject(error);
-}
 
 // ── Hook ──
 
 export interface UseDomGeometryCommitsParams {
-  previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
   commitPositionPatchToHtml: (
     selection: DomEditSelection,
@@ -56,7 +38,6 @@ export interface UseDomGeometryCommitsParams {
 }
 
 export function useDomGeometryCommits({
-  previewIframeRef,
   showToast,
   commitPositionPatchToHtml,
   readOnlyPreview,
@@ -78,28 +59,6 @@ export function useDomGeometryCommits({
     [commitPositionPatchToHtml, readOnlyPreview, showToast],
   );
 
-  const handleDomPathOffsetCommit = useCallback(
-    (selection: DomEditSelection, next: { x: number; y: number }) => {
-      if (readOnlyPreview) return Promise.resolve();
-      // ponytail: GSAP-targeted elements are blocked (no SDK position-in-script op); CSS-path
-      // elements fall through to commitPositionPatchToHtml → persistDomEditOperations →
-      // onTrySdkPersist and are already SDK-cut-over as setStyle/setAttribute (§3.3 done).
-      // Upgrade path for GSAP: add a moveElementGsap SDK op in a separate SDK PR.
-      const gsapFallback = rejectGsapCssFallback(selection, previewIframeRef, showToast);
-      if (gsapFallback) return gsapFallback;
-      const before = captureStudioPathOffset(selection.element);
-      applyStudioPathOffset(selection.element, next);
-      return commitPositionPatchToHtml(selection, buildPathOffsetPatches(selection.element), {
-        label: "Move layer",
-        coalesceKey: `path-offset:${getDomEditTargetKey(selection)}`,
-      }).catch((error) => {
-        restoreStudioPathOffset(selection.element, before);
-        throw error;
-      });
-    },
-    [commitPositionPatchToHtml, previewIframeRef, showToast, readOnlyPreview],
-  );
-
   const handleDomBoxSizeCommit = useCallback(
     (
       selection: DomEditSelection,
@@ -110,7 +69,7 @@ export function useDomGeometryCommits({
       if (readOnlyPreview) return Promise.resolve();
       const element = selection.element;
       const beforeSize = captureStudioBoxSize(element);
-      const beforeTranslate = element.style.getPropertyValue("translate");
+      const beforeOffset = captureStudioPathOffset(element);
       const stageCrop = prepareCropResize(element);
       applyStudioBoxSize(element, next);
       const crop = stageCrop();
@@ -118,16 +77,13 @@ export function useDomGeometryCommits({
       // (as a move writes it) that keeps the centre planted.
       const patches = buildBoxSizePatches(element);
       if (crop) patches.push(crop.patch);
-      if (offset) {
-        writeTranslatePx(element, offset);
-        patches.push(translatePatch(offset));
-      }
+      if (offset) patches.push(...writePlainMove(element, offset));
       return commitPositionPatchToHtml(selection, patches, {
         label: "Resize layer box",
         coalesceKey: `box-size:${getDomEditTargetKey(selection)}`,
       }).catch((error) => {
         restoreStudioBoxSize(element, beforeSize);
-        if (offset) element.style.setProperty("translate", beforeTranslate);
+        if (offset) restoreStudioPathOffset(element, beforeOffset);
         crop?.revert();
         restore?.();
         throw error;
@@ -173,7 +129,6 @@ export function useDomGeometryCommits({
 
   return {
     stageElementPositionOffset,
-    handleDomPathOffsetCommit,
     handleDomBoxSizeCommit,
     handleDomRotationCommit,
     handleDomManualEditsReset,

package/src/hooks/useGsapTweenCache.ts

@@ -336,8 +336,7 @@ export function usePopulateKeyframeCacheForFile(
     // fallow-ignore-next-line complexity
     const tryRuntimeScan = () => {
       if (runtimeScanDoneRef.current === `kf-cache:${projectId}:${sf}:${version}`) return true;
-      const iframe =
-        iframeRef?.current ?? document.querySelector<HTMLIFrameElement>("iframe[src*='/preview/']");
+      const iframe = iframeRef?.current;
       if (!iframe) return false;
       // Clip dims per element so the scan converts tween-relative keyframes to
       // clip-relative (matching the static path) instead of timeline-relative.

package/src/hooks/useInlineTextEdit.ts

@@ -1,6 +1,12 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { sanitizeRichTextChildren } from "@hyperframes/core/rich-text-sanitize";
 import { usePreviewReadOnly } from "../components/editor/previewReadOnlyContext";
+import { trackStudioPendingEdit } from "../utils/studioPendingEdits";
+import {
+  beginStudioManualEditGesture,
+  endStudioManualEditGesture,
+  noteStudioManualEditSave,
+} from "../components/editor/manualEditsDom";
 
 /**
  * Editing an element's text where it sits, in the composition itself.
@@ -43,6 +49,8 @@ export interface InlineTextEditSession {
   outline: string;
   /** The element's own outline offset, restored with the outline. */
   outlineOffset: string;
+  /** Holds the preview on screen while the edit is open. */
+  gesture?: string;
 }
 
 /** The live markup to persist and the session snapshot to restore on failure. */
@@ -86,7 +94,7 @@ export function useInlineTextEdit({
   onPause,
 }: {
   /** Where the edited text goes. The caller owns persistence. */
-  onCommit: (commit: InlineTextEditCommit) => void;
+  onCommit: (commit: InlineTextEditCommit) => unknown;
   /** Stop playback, so the element is not animating under the caret. */
   onPause?: () => void;
 }): InlineTextEditControls {
@@ -106,6 +114,7 @@ export function useInlineTextEdit({
       framesRef.current = null;
     }
     openRef.current = null;
+    endStudioManualEditGesture(open.element, open.gesture);
     setSession(null);
     // An element removed from the document mid-session is not an error, it is
     // just nothing left to clean up.
@@ -132,6 +141,7 @@ export function useInlineTextEdit({
         original: element.innerHTML,
         outline: element.style.outline,
         outlineOffset: element.style.outlineOffset,
+        gesture: beginStudioManualEditGesture(element),
       };
       // Drawn on the element itself, not in Studio's overlay above it. This is
       // the only mark that says the caret is in the TEXT rather than the
@@ -168,10 +178,14 @@ export function useInlineTextEdit({
     // saved rather than something the server will quietly cut down.
     sanitizeRichTextChildren(open.element);
     const html = open.element.innerHTML;
+    // Counted and pending before the edit closes, so a reload waits for the save, not the mark.
+    let save: (saving: unknown) => void = () => {};
+    trackStudioPendingEdit(new Promise((resolve) => (save = resolve)));
+    noteStudioManualEditSave(open.element);
     teardown();
     // After teardown, so the commit path's own resync does not fight an
     // element that is still editable.
-    onCommit({ element: open.element, html, previousHtml: open.original });
+    save(onCommit({ element: open.element, html, previousHtml: open.original }));
   }, [onCommit, teardown]);
 
   const cancel = useCallback(() => {

package/src/hooks/useLivePreviewIframe.ts

@@ -0,0 +1,18 @@
+import { useEffect, useRef, useState } from "react";
+import { onPreviewPromoted } from "../player/sceneSwap";
+
+/** The one source for which preview is on screen: the host's iframe, then each reload promoted in its place. */
+export function useLivePreviewIframe(host: HTMLIFrameElement | null): HTMLIFrameElement | null {
+  const [promoted, setPromoted] = useState<{ host: HTMLIFrameElement; live: HTMLIFrameElement }>();
+  const live = host && promoted?.host === host ? promoted.live : host;
+  const liveRef = useRef(live);
+  liveRef.current = live;
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!host) return;
+    return onPreviewPromoted(host.ownerDocument, ({ retired, live: next }) => {
+      if (retired === liveRef.current) setPromoted({ host, live: next });
+    });
+  }, [host]);
+  return live;
+}

package/src/hooks/usePreviewPersistence.history.test.tsx

@@ -0,0 +1,47 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../player/store/playerStore";
+import type { TimelineElement } from "../player/store/timelineElement";
+import { mountReactHarness } from "./domSelectionTestHarness";
+import { usePreviewPersistence } from "./usePreviewPersistence";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+});
+
+describe("undo that reloads the preview", () => {
+  it("keeps the timeline's clips until the reloaded preview reports its own", async () => {
+    const clips = [{ id: "a" }, { id: "b" }] as unknown as TimelineElement[];
+    usePlayerStore.getState().setElements(clips);
+    usePlayerStore.getState().setTimelineReady(true);
+    const reloadPreview = vi.fn();
+    let sync: ReturnType<typeof usePreviewPersistence>["syncHistoryPreviewAfterApply"] | null =
+      null;
+    function Harness() {
+      sync = usePreviewPersistence({
+        showToast: () => {},
+        readOptionalProjectFile: async () => "",
+        writeProjectFile: async () => {},
+        recordEdit: async () => {},
+        previewIframeRef: { current: null },
+        activeCompPathRef: { current: "index.html" },
+        reloadPreview,
+      }).syncHistoryPreviewAfterApply;
+      return null;
+    }
+    mountReactHarness(<Harness />);
+
+    // A nested composition's undo is not the active file's, so it reloads the preview.
+    const files = { "compositions/sub.html": { previous: "<p>1</p>", restored: "<p>2</p>" } };
+    await act(async () => sync!({ paths: Object.keys(files), files }));
+
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    const player = usePlayerStore.getState();
+    expect([player.elements, player.timelineReady]).toEqual([clips, true]);
+  });
+});

package/src/hooks/usePreviewPersistence.ts

@@ -207,16 +207,13 @@ export function usePreviewPersistence({
         reloadPreview,
       );
       if (strategy === "full") {
-        const player = usePlayerStore.getState();
-        player.setElements([]);
-        player.setSelectedElementId(null);
-        player.setTimelineReady(false);
+        usePlayerStore.getState().setSelectedElementId(null);
         return;
       }
       // A soft restore patched the reverted attributes onto the live preview, but the
       // player store keeps its own copy and that copy is what the automation lanes
       // draw — so without this an undone envelope edit stayed invisible until a
-      // reload. The full path above clears the store and waits for discovery instead.
+      // reload. The full path above waits for the reloaded preview to report instead.
       syncStoredAutomationFromPreview(previewIframeRef.current?.contentDocument ?? null);
     },
     [previewIframeRef, activeCompPathRef, reloadPreview],

package/src/hooks/useRenderClipContent.ts

@@ -9,7 +9,7 @@ import {
 import type { TimelineElement } from "../player";
 import type { TimelineClipRenderContext } from "../player/components/TimelineTypes";
 import { audioPillFlags } from "../player/components/audioClipLink";
-import { AudioWaveform } from "../player/components/AudioWaveform";
+import { AudioWaveform, rendersWaveform } from "../player/components/AudioWaveform";
 import { ImageThumbnail } from "../player/components/ImageThumbnail";
 import { encodePreviewPath, resolveMediaPreviewUrl } from "../player/components/thumbnailUtils";
 import { usePlayerStore } from "../player/store/playerStore";
@@ -135,7 +135,7 @@ export function useRenderClipContent({
       // Thumbnail generation disabled (perf) -> plain clip bars. Audio still shows
       // its waveform (cheap, not a frame thumbnail). Toggle: timeline toolbar.
       if (effectiveMode === "hidden") {
-        return el.tag === "audio"
+        return rendersWaveform(el)
           ? renderAudioClip(el, pid, sessionEpoch, style.label, context, elements)
           : null;
       }
@@ -173,7 +173,7 @@ export function useRenderClipContent({
       // Audio clips — waveform visualization. Resolve these before the generic
       // activePreviewUrl thumbnail branch; audio rows need waveform data, not a
       // captured frame from the currently drilled composition preview.
-      if (el.tag === "audio") {
+      if (rendersWaveform(el)) {
         return renderAudioClip(el, pid, sessionEpoch, style.label, context, elements);
       }
 

package/src/index.ts

@@ -181,6 +181,8 @@ export type { UseClipboardOptions } from "./hooks/useClipboard";
 // DOM editing for a host outside EditorShell; the Commit hooks save without useDomEditSession.
 export { useDomEditSession } from "./hooks/useDomEditSession";
 export type { UseDomEditSessionParams } from "./hooks/useDomEditSession";
+export { useLivePreviewIframe } from "./hooks/useLivePreviewIframe";
+export type { PreviewPromotion } from "./player/sceneSwap";
 export { usePreviewPersistence } from "./hooks/usePreviewPersistence";
 export type { UsePreviewPersistenceParams } from "./hooks/usePreviewPersistence";
 export { DomEditProvider, useDomEditSelectionContext } from "./contexts/DomEditContext";

package/src/livePreviewIframeExport.test.tsx

@@ -0,0 +1,33 @@
+// @vitest-environment happy-dom
+// Reads the preview on screen the way a host app does: by package name.
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, expectTypeOf, it } from "vitest";
+import { useLivePreviewIframe, type PreviewPromotion } from "@hyperframes/studio";
+import {
+  makePreview,
+  mountPlayerWithPreview,
+  paintShadow,
+} from "./player/hooks/timelinePlayerTestHarness";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+it("gives a host the preview on screen after a real shadow reload is promoted", async () => {
+  expectTypeOf<PreviewPromotion>().toHaveProperty("live");
+  const host = makePreview("<h1>Title</h1>");
+  const player = mountPlayerWithPreview(host);
+  let live: HTMLIFrameElement | null = null;
+  function Probe() {
+    live = useLivePreviewIframe(host);
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  act(() => root.render(<Probe />));
+  act(() => player.getApi().refreshPlayer());
+  const shadow = makePreview("<h1>Title</h1>", "?_t=1");
+  await paintShadow(player.getApi, shadow);
+  expect(player.getApi().iframeRef.current).toBe(shadow);
+  expect(live).toBe(shadow);
+  act(() => root.unmount());
+  act(() => player.root.unmount());
+});

package/src/main.tsx

@@ -2,6 +2,7 @@ import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { IconContext } from "@phosphor-icons/react";
 import { StudioApp } from "./App";
+import { ShowThemeToggle } from "./components/ThemeToggle";
 import { StudioErrorBoundary } from "./components/StudioErrorBoundary";
 import { readIconTokens } from "./styles/iconTokens";
 import { trackStudioEvent } from "./utils/studioTelemetry";
@@ -128,7 +129,9 @@ createRoot(document.getElementById("root")!).render(
         Icons that pass their own size or weight still win. */}
     <IconContext.Provider value={readIconTokens()}>
       <StudioErrorBoundary>
-        <StudioApp />
+        <ShowThemeToggle.Provider value>
+          <StudioApp />
+        </ShowThemeToggle.Provider>
       </StudioErrorBoundary>
     </IconContext.Provider>
   </StrictMode>,