@hyperframes/studio 0.8.51 → 0.8.52

package/src/components/dock/dockTestHarness.ts

@@ -0,0 +1,11 @@
+import { createDockview, type DockviewApi } from "dockview-react";
+
+/** A real dockview mounted on a fresh host element, with empty panel bodies. */
+export function mountBareDockview(): { host: HTMLElement; api: DockviewApi } {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const api = createDockview(host, {
+    createComponent: () => ({ element: document.createElement("div"), init() {}, dispose() {} }),
+  });
+  return { host, api };
+}

package/src/components/editor/LayersPanel.test.ts

@@ -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"]);
+  });
+});

package/src/components/editor/LayersPanel.tsx

@@ -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) {

package/src/components/editor/PreviewGuides.tsx

@@ -8,7 +8,7 @@ interface PreviewGuidesProps {
 }
 
 const TICKS = Array.from({ length: 11 }, (_, i) => i * 10);
-const INK = "rgba(255,255,255,0.7)";
+const INK = "color-mix(in srgb, white 70%, transparent)";
 
 /** Ruler and safe-margin boxes drawn over the preview pane, never inside the composition. */
 export const PreviewGuides = memo(function PreviewGuides({ iframeRef }: PreviewGuidesProps) {

package/src/components/editor/TopologyLens.test.tsx

@@ -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 });
+  });
 });

package/src/components/editor/TopologyLens.tsx

@@ -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) {

package/src/components/editor/useColorGradingController.test.ts

@@ -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();
+  });
+});

package/src/components/editor/useColorGradingController.ts

@@ -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(
     () => () => {

package/src/components/editor/useColorGradingPreviews.test.ts

@@ -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();
+  });
+});

package/src/components/editor/useColorGradingPreviews.ts

@@ -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;

package/src/components/editor/usePreviewCompositionRect.test.tsx

@@ -0,0 +1,95 @@
+// @vitest-environment happy-dom
+
+import { act, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
+import {
+  usePreviewCompositionRect,
+  type PreviewCompositionRect,
+} from "./usePreviewCompositionRect";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  usePreviewIframeStore.getState().setIframe(null);
+  document.body.innerHTML = "";
+});
+
+function boxed<T extends HTMLElement>(el: T, box: [number, number, number, number]): T {
+  const [left, top, width, height] = box;
+  el.getBoundingClientRect = () => new DOMRect(left, top, width, height);
+  return el;
+}
+
+function mountProbe() {
+  let rect: PreviewCompositionRect | undefined;
+  function Probe() {
+    const ref = useRef<HTMLDivElement>(null);
+    rect = usePreviewCompositionRect(ref);
+    return (
+      <div
+        ref={(el) => {
+          ref.current = el;
+          if (el) boxed(el, [10, 20, 1000, 600]);
+        }}
+      />
+    );
+  }
+  const host = document.createElement("div");
+  document.body.append(host);
+  act(() => createRoot(host).render(<Probe />));
+  return () => rect;
+}
+
+function compositionFrame(box: [number, number, number, number], width: number, height: number) {
+  const iframe = boxed(document.createElement("iframe"), box);
+  document.body.append(iframe);
+  const root = iframe.contentDocument?.createElement("div");
+  root?.setAttribute("data-composition-id", "main");
+  root?.setAttribute("data-width", String(width));
+  root?.setAttribute("data-height", String(height));
+  if (root) iframe.contentDocument?.body.append(root);
+  return iframe;
+}
+
+const settle = () => new Promise((r) => setTimeout(r, 400));
+
+describe("usePreviewCompositionRect", () => {
+  it("reports the live preview iframe's box relative to the overlay, scaled to the composition", async () => {
+    const read = mountProbe();
+    const iframe = compositionFrame([110, 70, 960, 540], 1920, 1080);
+    await act(async () => {
+      usePreviewIframeStore.getState().setIframe(iframe);
+      await settle();
+    });
+    expect(read()).toEqual({
+      left: 100,
+      top: 50,
+      width: 960,
+      height: 540,
+      scaleX: 0.5,
+      scaleY: 0.5,
+    });
+  });
+
+  it("follows the iframe when a reload replaces it", async () => {
+    const read = mountProbe();
+    await act(async () => {
+      usePreviewIframeStore.getState().setIframe(compositionFrame([110, 70, 960, 540], 1920, 1080));
+      await settle();
+    });
+    await act(async () => {
+      usePreviewIframeStore.getState().setIframe(compositionFrame([60, 40, 500, 500], 1000, 1000));
+      await settle();
+    });
+    expect(read()).toEqual({
+      left: 50,
+      top: 20,
+      width: 500,
+      height: 500,
+      scaleX: 0.5,
+      scaleY: 0.5,
+    });
+  });
+});

package/src/components/editor/usePreviewCompositionRect.ts

@@ -0,0 +1,21 @@
+import { useMemo, type RefObject } from "react";
+import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
+import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
+
+export type { DomEditCompositionRect as PreviewCompositionRect } from "./useDomEditCompositionRect";
+
+/**
+ * Where the composition sits inside `overlayRef`, in overlay pixels, plus the scale from
+ * composition units to pixels. Follows the live preview iframe across reloads.
+ */
+export function usePreviewCompositionRect(overlayRef: RefObject<HTMLDivElement | null>) {
+  const iframeRef = useMemo<RefObject<HTMLIFrameElement | null>>(
+    () => ({
+      get current() {
+        return usePreviewIframeStore.getState().iframe;
+      },
+    }),
+    [],
+  );
+  return useDomEditCompositionRect({ iframeRef, overlayRef });
+}

package/src/components/nle/NLEPreview.tsx

@@ -442,7 +442,7 @@ export const NLEPreview = memo(function NLEPreview({
     <div className="flex flex-col h-full min-h-0">
       <div
         ref={viewportRef}
-        className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-hidden focus:ring-1 focus:ring-studio-accent/40 bg-neutral-950"
+        className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-hidden focus:ring-1 focus:ring-studio-accent/40 bg-[var(--studio-preview-bg,var(--color-neutral-950))]"
         tabIndex={0}
         aria-label="Composition preview"
       >

package/src/components/nle/PreviewPane.tsx

@@ -110,7 +110,7 @@ export function PreviewPane({
       ref={containerRef}
       // Panel chrome (rounded border) is dropped in fullscreen so the preview
       // fills the screen edge-to-edge.
-      className={`flex-1 min-h-0 flex flex-col overflow-hidden bg-neutral-950 ${
+      className={`flex-1 min-h-0 flex flex-col overflow-hidden bg-[var(--studio-preview-bg,var(--color-neutral-950))] ${
         isFullscreen ? "" : "rounded-lg border border-neutral-800/50"
       }`}
       data-studio-fullscreen-target=""

package/src/components/pointerTargetSize.test.tsx

@@ -6,6 +6,14 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { CompositionsTab } from "./sidebar/CompositionsTab";
 import { TimelineToolbar } from "./TimelineToolbar";
 
+vi.mock("../contexts/StudioContext", () => ({
+  useStudioShellContext: () => ({
+    editHistory: { canUndo: false, canRedo: false },
+    handleUndo: vi.fn(),
+    handleRedo: vi.fn(),
+  }),
+}));
+
 // WCAG 2.2 (2.5.8) requires a 24x24 CSS pixel pointer target. happy-dom has no
 // CSS engine, so getBoundingClientRect() is 0x0 for everything here and the size
 // itself cannot be measured — these assert the utility classes that PRODUCE the

package/src/components/renders/RenderQueue.tsx

@@ -22,7 +22,7 @@ type StartRenderHandler = (
   fps: 24 | 30 | 60,
 ) => void | Promise<void>;
 
-interface RenderQueueProps {
+export interface RenderQueueProps {
   jobs: RenderJob[];
   projectId: string;
   onDelete: (jobId: string) => void;

package/src/components/timelineToolbarStyles.ts

@@ -0,0 +1,5 @@
+// CapCut-flat icon buttons: a transparent 28px hit area with a subtle hover wash.
+export const flatBtn = "flex h-7 w-7 items-center justify-center rounded-md transition-colors";
+export const flatIdle = `${flatBtn} text-neutral-400 hover:bg-white/6 hover:text-neutral-200 active:scale-[0.98]`;
+export const flatActive = `${flatBtn} bg-white/8 text-neutral-100 active:scale-[0.98]`;
+export const flatDisabled = `${flatBtn} text-neutral-700 cursor-not-allowed`;