fix(studio): preview consumers read the live iframe from one shared owner

This commit is contained in:
Miguel Angel Simon Sierra
2026-09-19 11:42:10 -04:00
parent ff078accda
commit 762cb609df
14 changed files with 393 additions and 13 deletions
+3 -2
View File
@@ -1,3 +1,4 @@
import { useLivePreviewIframe, usePreviewIframeStore } from "./player/store/previewIframeStore";
import { buildProjectApiPath } from "./utils/projectRouting";
import { useState, useCallback, useRef, useMemo, useLayoutEffect } from "react";
import type { LeftSidebarHandle, SidebarTab } from "./components/sidebar/LeftSidebar";
@@ -68,7 +69,7 @@ export function StudioApp() {
const initialUrlStateRef = useRef(readStudioUrlStateFromWindow());
useStudioSessionStart(projectId, resolving, waitingForServer);
const [compIdToSrc, setCompIdToSrc] = useState<Map<string, string>>(new Map());
const [previewIframe, setPreviewIframe] = useState<HTMLIFrameElement | null>(null);
const previewIframe = useLivePreviewIframe();
const [compositionLoading, setCompositionLoading] = useState(true);
const [refreshKey, setRefreshKey] = useState(0);
const [previewDocumentVersion, refreshPreviewDocumentVersion] = usePreviewDocumentVersion();
@@ -359,7 +360,7 @@ export function StudioApp() {
const handlePreviewIframeRef = useCallback(
(iframe: HTMLIFrameElement | null) => {
previewIframeRef.current = iframe;
setPreviewIframe(iframe);
usePreviewIframeStore.getState().setIframe(iframe);
appHotkeys.syncPreviewHotkeys(iframe);
resetConsoleErrors();
refreshPreviewDocumentVersion();
@@ -4,6 +4,7 @@ import { createRoot } from "react-dom/client";
import { expect, it, vi } from "vitest";
import { CaptionOverlay } from "./CaptionOverlay";
import { useCaptionStore } from "../store";
import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
@@ -45,3 +46,54 @@ it("only schedules caption layout for messages from its preview", () => {
vi.unstubAllGlobals();
}
});
it("observes and accepts messages from the promoted iframe, not the old one", () => {
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 schedule = vi.fn(() => 1);
const observed: Element[] = [];
vi.stubGlobal("requestAnimationFrame", schedule);
vi.stubGlobal("cancelAnimationFrame", vi.fn());
vi.stubGlobal(
"ResizeObserver",
class {
observe(el: Element) {
observed.push(el);
}
disconnect() {}
},
);
useCaptionStore.getState().setEditMode(true);
const send = (source: MessageEventSource | null) =>
act(() => {
window.dispatchEvent(new MessageEvent("message", { source, data: { source: "hf-preview" } }));
});
try {
act(() => usePreviewIframeStore.getState().setIframe(a));
act(() => root.render(<CaptionOverlay iframeRef={ref} />));
expect(observed).toContain(a);
expect(observed).not.toContain(b);
act(() => {
ref.current = b;
usePreviewIframeStore.getState().setIframe(b);
});
expect(observed).toContain(b);
schedule.mockClear();
send(a.contentWindow);
expect(schedule).not.toHaveBeenCalled();
send(b.contentWindow);
expect(schedule).toHaveBeenCalledOnce();
} finally {
act(() => root.unmount());
usePreviewIframeStore.setState({ iframe: null });
useCaptionStore.getState().reset();
host.remove();
a.remove();
b.remove();
vi.unstubAllGlobals();
}
});
@@ -1,7 +1,7 @@
import { memo, useState, useCallback, useRef } from "react";
import { memo, useEffect, useState, useCallback, useRef } from "react";
import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
import { useCaptionStore } from "../store";
import { usePlayerStore } from "../../player";
import { useMountEffect } from "../../hooks/useMountEffect";
import { shouldHandleCaptionNudgeKey, isEditableEventTarget } from "../keyboard";
import {
readWordBoxes,
@@ -32,6 +32,7 @@ function syncToStore(segmentId: string, el: HTMLElement, iframeWin: Window) {
export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: CaptionOverlayProps) {
const isEditMode = useCaptionStore((s) => s.isEditMode);
const livePreviewIframe = useLivePreviewIframe();
const model = useCaptionStore((s) => s.model);
const selectedSegmentIds = useCaptionStore((s) => s.selectedSegmentIds);
const selectSegment = useCaptionStore((s) => s.selectSegment);
@@ -81,7 +82,9 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
| null
>(null);
useMountEffect(() => {
// The observer and message filter bind to the live iframe element, which a promoted reload replaces.
// eslint-disable-next-line no-restricted-syntax
useEffect(() => {
if (!isEditMode) return;
// Let undo/redo (useAppHotkeys) reapply restored models to this iframe.
@@ -240,7 +243,8 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
window.removeEventListener("keydown", handleKeyDown);
cancelDragRef.current = null;
};
});
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [livePreviewIframe]);
const getCssScale = useCallback(() => {
const iframe = iframeRef.current;
@@ -1,12 +1,55 @@
// @vitest-environment happy-dom
import { createElement, act } from "react";
import { createRoot, type Root } from "react-dom/client";
import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
import { Window } from "happy-dom";
import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
import type { DomEditLayerItem } from "./domEditingTypes";
import { createRafThrottle, sortLayersByZIndex } from "./LayersPanel";
import { createRafThrottle, LayersPanel, sortLayersByZIndex } from "./LayersPanel";
import { isLayerDraggable } from "./useLayerDrag";
import { liveTime } from "../../player";
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
const mocks = vi.hoisted(() => ({
previewIframeRef: { current: null } as { current: unknown },
collect: vi.fn(),
setActiveGroupElement: vi.fn(),
showToast: vi.fn(),
}));
vi.mock("../../contexts/StudioContext", () => ({
useStudioShellContext: () => ({
previewIframeRef: mocks.previewIframeRef,
activeCompPath: "index.html",
showToast: mocks.showToast,
}),
useStudioPlaybackContext: () => ({
refreshKey: 0,
compositionLoading: true,
timelineElements: [],
isPlaying: false,
}),
}));
vi.mock("../../contexts/DomEditContext", () => ({
useDomEditContext: () => ({
domEditSelection: null,
activeGroupElement: null,
applyDomSelection: vi.fn(),
updateDomEditHoverSelection: vi.fn(),
handleDomZIndexReorderCommit: vi.fn(),
setActiveGroupElement: mocks.setActiveGroupElement,
}),
}));
vi.mock("../nle/useCanvasZOrderTimelineMirror", () => ({
useLayerReorderTimelineMirror: () => vi.fn(),
}));
vi.mock("./domEditing", async (importOriginal) => ({
...(await importOriginal<typeof import("./domEditing")>()),
collectDomEditLayerItems: mocks.collect,
}));
function makeLayer(
overrides: Partial<DomEditLayerItem> & { zIndex?: string; locked?: boolean },
): DomEditLayerItem {
@@ -197,3 +240,56 @@ describe("liveTime subscribe / unsubscribe (LayersPanel scrub contract)", () =>
unsubscribe();
});
});
describe("LayersPanel preview promotion", () => {
let root: Root;
let host: HTMLDivElement;
function makeIframe(compId: string): HTMLIFrameElement {
const iframe = document.createElement("iframe");
const doc = new Window().document;
doc.body.innerHTML = `<div data-composition-id="${compId}"></div>`;
Object.defineProperty(iframe, "contentDocument", { value: doc });
return iframe;
}
const collectedRootIds = () =>
mocks.collect.mock.calls.map((call) => (call[0] as HTMLElement).dataset.compositionId);
beforeEach(() => {
mocks.collect.mockReset().mockReturnValue([]);
host = document.createElement("div");
document.body.append(host);
root = createRoot(host);
});
afterEach(() => {
act(() => root.unmount());
host.remove();
usePreviewIframeStore.setState({ iframe: null });
});
it("recollects layers from the promoted document's load, not the replaced one", () => {
const a = makeIframe("a");
const b = makeIframe("b");
mocks.previewIframeRef.current = a;
usePreviewIframeStore.setState({ iframe: a });
act(() => root.render(createElement(LayersPanel)));
act(() => {
mocks.previewIframeRef.current = b;
usePreviewIframeStore.getState().setIframe(b);
});
mocks.collect.mockClear();
act(() => {
a.dispatchEvent(new Event("load"));
});
expect(mocks.collect).not.toHaveBeenCalled();
act(() => {
b.dispatchEvent(new Event("load"));
});
expect(collectedRootIds()).toEqual(["b"]);
});
});
@@ -1,3 +1,4 @@
import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
import { memo, useState, useCallback, useEffect, useRef } from "react";
import {
collectDomEditLayerItems,
@@ -122,6 +123,7 @@ export const LayersPanel = memo(function LayersPanel() {
const isMasterView = !activeCompPath || activeCompPath === "index.html";
const livePreviewIframe = useLivePreviewIframe();
const collectLayers = useCallback(() => {
const iframe = previewIframeRef.current;
if (!iframe) return;
@@ -152,7 +154,7 @@ export const LayersPanel = memo(function LayersPanel() {
useEffect(() => {
collectLayers();
}, [collectLayers, refreshKey, zEditVersion]);
}, [collectLayers, refreshKey, zEditVersion, livePreviewIframe]);
useEffect(() => {
const iframe = previewIframeRef.current;
@@ -163,7 +165,7 @@ export const LayersPanel = memo(function LayersPanel() {
};
iframe.addEventListener("load", handleLoad);
return () => iframe.removeEventListener("load", handleLoad);
}, [previewIframeRef, collectLayers]);
}, [previewIframeRef, livePreviewIframe, collectLayers]);
useEffect(() => {
if (!compositionLoading) {
@@ -4,6 +4,7 @@ import React, { act } from "react";
import { createRoot, type Root } from "react-dom/client";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { studioEditLifecycle, type StudioWriteResult } from "../../webmcp/writeCoordinator";
import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
import { TopologyLens } from "./TopologyLens";
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -291,4 +292,31 @@ describe("TopologyLens", () => {
expect(vi.getTimerCount()).toBe(0);
expect(studioEditLifecycle.getSnapshot()).toEqual({ phase: "idle" });
});
it("dismisses on the promoted iframe's load, not the replaced one", () => {
const a = document.createElement("iframe");
const b = document.createElement("iframe");
document.body.append(a, b);
const ref = { current: a as HTMLIFrameElement | null };
usePreviewIframeStore.setState({ iframe: a });
window.matchMedia = matchMedia(false);
host = document.createElement("div");
document.body.append(host);
root = createRoot(host);
act(() => {
root?.render(<TopologyLens iframeRef={ref} activeCompositionPath="index.html" />);
});
begin();
act(() => {
ref.current = b;
usePreviewIframeStore.getState().setIframe(b);
});
act(() => a.dispatchEvent(new Event("load")));
expect(host.querySelector('[data-topology-lens="hidden"]')).toBeNull();
act(() => b.dispatchEvent(new Event("load")));
expect(host.querySelector('[data-topology-lens="hidden"]')).not.toBeNull();
usePreviewIframeStore.setState({ iframe: null });
});
});
@@ -1,3 +1,4 @@
import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
import {
useEffect,
useLayoutEffect,
@@ -113,13 +114,14 @@ export function TopologyLens({ iframeRef, activeCompositionPath }: TopologyLensP
setMeasured(geometry ? { callId, geometry } : null);
}, [activeCompositionPath, callId, handle, iframeRef, phase]);
const livePreviewIframe = useLivePreviewIframe();
useEffect(() => {
const iframe = iframeRef.current;
if (!iframe || !callId) return;
const dismiss = () => studioEditLifecycle.dismiss(callId);
iframe.addEventListener("load", dismiss);
return () => iframe.removeEventListener("load", dismiss);
}, [callId, iframeRef]);
}, [callId, iframeRef, livePreviewIframe]);
useEffect(() => {
if (pendingUnmountDismissRef.current !== null) {
@@ -4,6 +4,8 @@ import React, { act } from "react";
import { createRoot } from "react-dom/client";
import { afterEach, describe, expect, it, vi } from "vitest";
import { normalizeHfColorGrading } from "@hyperframes/core/color-grading";
import { runtimeProtocolMetadata } from "@hyperframes/core/runtime/protocol";
import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
import { useColorGradingController } from "./useColorGradingController";
import type { DomEditSelection } from "./domEditing";
@@ -22,6 +24,7 @@ function cleanStudioGrading() {
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
afterEach(() => {
usePreviewIframeStore.setState({ iframe: null });
document.body.innerHTML = "";
});
@@ -737,3 +740,38 @@ describe("useColorGradingController", () => {
vi.unstubAllGlobals();
});
});
describe("useColorGradingController after the preview iframe is replaced", () => {
it("replays the grade to the new iframe on its ready message and ignores the old one", () => {
vi.useFakeTimers();
const a = createPreviewFrame();
const b = createPreviewFrame();
const ref = { current: a.iframe as HTMLIFrameElement | null };
usePreviewIframeStore.getState().setIframe(a.iframe);
const initialElement = makeElement({
dataAttributes: { "color-grading": JSON.stringify({ preset: "bright-pop", intensity: 1 }) },
});
const { root } = renderHook(vi.fn(), initialElement, ref);
act(() => vi.advanceTimersByTime(100));
const postToA = vi.spyOn(a.contentWindow, "postMessage");
const postToB = vi.spyOn(b.contentWindow, "postMessage");
act(() => {
ref.current = b.iframe;
usePreviewIframeStore.getState().setIframe(b.iframe);
});
const ready = { source: "hf-preview", type: "ready", ...runtimeProtocolMetadata(30) };
act(() => {
window.dispatchEvent(new MessageEvent("message", { data: ready, source: a.contentWindow }));
});
expect(colorGradingMessages(postToB.mock.calls)).toHaveLength(0);
act(() => {
window.dispatchEvent(new MessageEvent("message", { data: ready, source: b.contentWindow }));
});
expect(colorGradingMessages(postToB.mock.calls)).toHaveLength(1);
expect(postToA).not.toHaveBeenCalled();
act(() => root.unmount());
vi.useRealTimers();
});
});
@@ -1,3 +1,4 @@
import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";
import {
HF_COLOR_GRADING_ATTR,
@@ -430,6 +431,7 @@ export function useColorGradingController({
[previewIframeRef, target],
);
const livePreviewIframe = useLivePreviewIframe();
useEffect(() => {
const iframe = previewIframeRef?.current;
if (!iframe) return;
@@ -455,7 +457,13 @@ export function useColorGradingController({
window.removeEventListener("message", onMessage);
window.clearTimeout(timer);
};
}, [postColorGrading, postCompare, previewIframeRef, scheduleRuntimeStatusRefresh]);
}, [
postColorGrading,
postCompare,
previewIframeRef,
scheduleRuntimeStatusRefresh,
livePreviewIframe,
]);
useEffect(
() => () => {
@@ -0,0 +1,76 @@
// @vitest-environment happy-dom
import React, { act } from "react";
import { createRoot } from "react-dom/client";
import { afterEach, describe, expect, it, vi } from "vitest";
import { normalizeHfColorGrading } from "@hyperframes/core/color-grading";
import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
import { useColorGradingPreviews } from "./useColorGradingPreviews";
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
afterEach(() => {
usePreviewIframeStore.setState({ iframe: null });
document.body.innerHTML = "";
});
function createFrame() {
return document.body.appendChild(document.createElement("iframe"));
}
function installRenderer(iframe: HTMLIFrameElement) {
const renderPreviews = vi.fn().mockResolvedValue({
width: 160,
height: 90,
images: [{ id: "bright-pop", dataUrl: "data:image/png;base64,x" }],
});
(iframe.contentWindow as unknown as { __hf: unknown }).__hf = {
colorGrading: { renderPreviews },
};
return renderPreviews;
}
describe("useColorGradingPreviews after the preview iframe is replaced", () => {
it("requests preset previews from the new iframe's runtime", async () => {
vi.useFakeTimers();
const a = createFrame();
const b = createFrame();
const renderOnB = installRenderer(b);
const ref = { current: a as HTMLIFrameElement | null };
usePreviewIframeStore.getState().setIframe(a);
const grading = normalizeHfColorGrading({ preset: "neutral" });
if (!grading) throw new Error("expected neutral grading");
const gradingRef = { current: grading };
const target = { selector: "#v" } as never;
const postColorGrading = vi.fn();
let requestPresetPreviews: () => void = () => {};
function Host() {
requestPresetPreviews = useColorGradingPreviews({
grading,
gradingRef,
identityKey: "k",
target,
previewIframeRef: ref,
postColorGrading,
}).requestPresetPreviews;
return null;
}
const root = createRoot(document.body.appendChild(document.createElement("div")));
act(() => root.render(React.createElement(Host)));
act(() => requestPresetPreviews());
act(() => vi.advanceTimersByTime(0));
act(() => {
ref.current = b;
usePreviewIframeStore.getState().setIframe(b);
});
act(() => vi.advanceTimersByTime(0));
await act(async () => {
await Promise.resolve();
});
expect(renderOnB).toHaveBeenCalled();
act(() => root.unmount());
vi.useRealTimers();
});
});
@@ -1,3 +1,4 @@
import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
import { useCallback, useEffect, useRef, useState, type RefObject } from "react";
import {
HF_COLOR_GRADING_ACTIVE_EFFECT_KEYS,
@@ -155,6 +156,7 @@ export function useColorGradingPreviews({
}
const previews = state.identityKey === identityKey ? state.previews : emptyPreviews();
const livePreviewIframe = useLivePreviewIframe();
useEffect(() => {
if (!request) return;
const { kind } = request;
@@ -245,7 +247,15 @@ export function useColorGradingPreviews({
iframe.removeEventListener("load", attempt);
window.removeEventListener("message", onMessage);
};
}, [grading.effects, grading.lut, grading.palette, previewIframeRef, request, target]);
}, [
grading.effects,
grading.lut,
grading.palette,
previewIframeRef,
livePreviewIframe,
request,
target,
]);
const stopAnimatedPreview = useCallback(() => {
const session = animatedRef.current;
@@ -3,6 +3,7 @@ import { act } from "react";
import { createRoot } from "react-dom/client";
import { expect, it, vi } from "vitest";
import { useCaptionDetection } from "./useCaptionDetection";
import { usePreviewIframeStore } from "../player/store/previewIframeStore";
Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
@@ -52,3 +53,48 @@ it("does not let a foreign window trigger caption activation", () => {
vi.unstubAllGlobals();
}
});
it("re-runs caption activation on 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 fetchMock = vi.fn(() => new Promise<Response>(() => {}));
vi.stubGlobal("fetch", fetchMock);
const params = {
projectId: "demo",
activeCompPath: "captions.html",
compIdToSrc: new Map<string, string>(),
captionEditMode: false,
captionHasSelection: false,
previewIframeRef: ref,
captionSync: { save: vi.fn(), loadOverrides: vi.fn(async () => {}) },
setRightCollapsed: vi.fn(),
};
function Harness() {
useCaptionDetection(params);
return null;
}
try {
act(() => usePreviewIframeStore.getState().setIframe(a));
act(() => root.render(<Harness />));
const group = b.contentDocument!.createElement("div");
group.className = "caption-group";
b.contentDocument!.body.append(group);
expect(fetchMock).not.toHaveBeenCalled();
act(() => {
ref.current = b;
usePreviewIframeStore.getState().setIframe(b);
});
expect(fetchMock).toHaveBeenCalledOnce();
} finally {
act(() => root.unmount());
usePreviewIframeStore.setState({ iframe: null });
host.remove();
a.remove();
b.remove();
vi.unstubAllGlobals();
}
});
@@ -1,3 +1,4 @@
import { useLivePreviewIframe } from "../player/store/previewIframeStore";
import { buildProjectApiPath } from "../utils/projectRouting";
import { useEffect, useRef } from "react";
import { useCaptionStore } from "../captions/store";
@@ -26,6 +27,7 @@ export function useCaptionDetection({
captionSync,
setRightCollapsed,
}: UseCaptionDetectionParams) {
const livePreviewIframe = useLivePreviewIframe();
// Switching compositions must drop the previous comp's caption state — a
// stale model + full-canvas overlay otherwise blocks normal element editing
// on the new composition (and edit mode could never be exited).
@@ -145,7 +147,7 @@ export function useCaptionDetection({
return () => {
window.removeEventListener("message", handleMessage);
};
}, [activeCompPath, projectId, compIdToSrc, captionSync, previewIframeRef]);
}, [activeCompPath, projectId, compIdToSrc, captionSync, previewIframeRef, livePreviewIframe]);
// eslint-disable-next-line no-restricted-syntax
useEffect(() => {
@@ -0,0 +1,15 @@
import { create } from "zustand";
interface PreviewIframeState {
iframe: HTMLIFrameElement | null;
setIframe: (iframe: HTMLIFrameElement | null) => void;
}
/** The one owner of "the live preview iframe element"; a promoted reload replaces it. */
export const usePreviewIframeStore = create<PreviewIframeState>((set) => ({
iframe: null,
setIframe: (iframe) => set({ iframe }),
}));
/** Subscribe an effect to the live iframe by listing the result in its dependencies. */
export const useLivePreviewIframe = () => usePreviewIframeStore((s) => s.iframe);