@hyperframes/studio 0.8.51 → 0.8.52

package/src/hooks/useCaptionDetection.sender.test.tsx

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

package/src/hooks/useCaptionDetection.ts

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

package/src/hooks/useEditHistoryActions.test.tsx

@@ -0,0 +1,90 @@
+// @vitest-environment happy-dom
+
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
+import { useEditHistoryActions, type EditHistoryHandle } from "./useEditHistoryActions";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | null = null;
+afterEach(() => act(() => root?.unmount()));
+
+function mount(result: { ok: boolean; reason?: string; label?: string; paths?: string[] }) {
+  const editHistory = {
+    undo: vi.fn<EditHistoryHandle["undo"]>(async (cb) => {
+      if (result.ok) await cb.writeFile("index.html", "before");
+      return result;
+    }),
+    redo: vi.fn<EditHistoryHandle["redo"]>(async () => result),
+  };
+  const deps = {
+    editHistory,
+    readOptionalProjectFile: vi.fn(async () => ""),
+    readProjectFile: vi.fn(async () => ""),
+    writeProjectFile: vi.fn(async () => undefined),
+    showToast: vi.fn(),
+    syncHistoryPreviewAfterApply: vi.fn(async () => undefined),
+    waitForPendingDomEditSaves: vi.fn(async () => undefined),
+    onAfterUndoRedo: vi.fn(),
+    activeCompPath: "index.html",
+    forceReloadSdkSession: vi.fn(),
+  };
+  let actions!: ReturnType<typeof useEditHistoryActions>;
+  function Probe() {
+    actions = useEditHistoryActions(deps);
+    return null;
+  }
+  root = createRoot(document.createElement("div"));
+  act(() => root!.render(createElement(Probe)));
+  return { deps, actions };
+}
+
+describe("useEditHistoryActions", () => {
+  it("undo writes through the host writer, resyncs the preview and toasts the label", async () => {
+    const { deps, actions } = mount({ ok: true, label: "Move clip", paths: ["index.html"] });
+    await act(() => actions.undo());
+    expect(deps.waitForPendingDomEditSaves).toHaveBeenCalled();
+    expect(deps.writeProjectFile).toHaveBeenCalledWith("index.html", "before");
+    expect(deps.onAfterUndoRedo).toHaveBeenCalled();
+    expect(deps.forceReloadSdkSession).toHaveBeenCalled();
+    expect(deps.syncHistoryPreviewAfterApply).toHaveBeenCalled();
+    expect(deps.showToast).toHaveBeenCalledWith("Undid Move clip", "info");
+  });
+
+  it("redo reports the redone label and skips the SDK reload for other files", async () => {
+    const { deps, actions } = mount({ ok: true, label: "Split clip", paths: ["other.html"] });
+    await act(() => actions.redo());
+    expect(deps.forceReloadSdkSession).not.toHaveBeenCalled();
+    expect(deps.showToast).toHaveBeenCalledWith("Redid Split clip", "info");
+  });
+
+  it("explains a refused undo when the file changed on disk", async () => {
+    const { deps, actions } = mount({ ok: false, reason: "content-mismatch" });
+    await act(() => actions.undo());
+    expect(deps.showToast).toHaveBeenCalledWith(
+      "File changed outside Studio. Undo history was not applied.",
+      "info",
+    );
+    expect(deps.syncHistoryPreviewAfterApply).not.toHaveBeenCalled();
+  });
+
+  it("waits for pending saves first and reads the motion file through the optional reader", async () => {
+    const { deps, actions } = mount({ ok: true, label: "Move clip", paths: ["index.html"] });
+    const order: string[] = [];
+    deps.waitForPendingDomEditSaves.mockImplementation(async () => void order.push("wait"));
+    deps.editHistory.undo.mockImplementation(async (cb) => {
+      order.push("undo");
+      await cb.readFile(STUDIO_MOTION_PATH);
+      await cb.readFile("index.html");
+      await cb.serialize?.(["index.html"], async () => order.push("serialized"));
+      return { ok: true };
+    });
+    await act(() => actions.undo());
+    expect(order).toEqual(["wait", "undo", "serialized"]);
+    expect(deps.readOptionalProjectFile).toHaveBeenCalledWith(STUDIO_MOTION_PATH);
+    expect(deps.readProjectFile).toHaveBeenCalledWith("index.html");
+    expect(deps.readProjectFile).not.toHaveBeenCalledWith(STUDIO_MOTION_PATH);
+  });
+});

package/src/hooks/useEditHistoryActions.ts

@@ -0,0 +1,106 @@
+// fallow-ignore-file complexity
+import { useCallback, useMemo } from "react";
+import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
+import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
+
+interface HistoryResult {
+  ok: boolean;
+  reason?: string;
+  label?: string;
+  paths?: string[];
+  /** Per-file restored/previous content, used to soft-apply the preview. */
+  files?: Record<string, { previous: string; restored: string }>;
+}
+interface HistoryFileCallbacks {
+  readFile: (path: string) => Promise<string>;
+  writeFile: (path: string, content: string) => Promise<void>;
+  serialize?: <T>(paths: readonly string[], task: () => Promise<T>) => Promise<T>;
+}
+export interface EditHistoryHandle {
+  undo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;
+  redo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;
+  state: {
+    undo: ReadonlyArray<{ createdAt: number }>;
+    redo: ReadonlyArray<{ createdAt: number }>;
+  };
+}
+
+export interface UseEditHistoryActionsOptions {
+  editHistory: Pick<EditHistoryHandle, "undo" | "redo">;
+  readOptionalProjectFile: (path: string) => Promise<string>;
+  readProjectFile: (path: string) => Promise<string>;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  syncHistoryPreviewAfterApply: (restore: Pick<HistoryResult, "paths" | "files">) => Promise<void>;
+  waitForPendingDomEditSaves: () => Promise<void>;
+  onAfterUndoRedo?: () => void;
+  /** Active composition path — decides whether undo/redo must resync the SDK session. */
+  activeCompPath?: string | null;
+  /** Reloads the SDK session after a revert of the active comp, past the self-write suppress window. */
+  forceReloadSdkSession?: () => void;
+}
+
+/** Applies one persisted file-history step: the single owner of undo/redo over project files. */
+export function useEditHistoryActions({
+  editHistory,
+  readOptionalProjectFile,
+  readProjectFile,
+  writeProjectFile,
+  showToast,
+  syncHistoryPreviewAfterApply,
+  waitForPendingDomEditSaves,
+  onAfterUndoRedo,
+  activeCompPath,
+  forceReloadSdkSession,
+}: UseEditHistoryActionsOptions) {
+  const readHistoryFile = useCallback(
+    (path: string): Promise<string> =>
+      path === STUDIO_MOTION_PATH ? readOptionalProjectFile(path) : readProjectFile(path),
+    [readOptionalProjectFile, readProjectFile],
+  );
+  const serializeHistoryFiles = useCallback(
+    <T>(paths: readonly string[], task: () => Promise<T>) =>
+      serializeStudioFileMutations(writeProjectFile, paths, task),
+    [writeProjectFile],
+  );
+
+  const apply = useCallback(
+    async (direction: "undo" | "redo") => {
+      const [noun, verb] = direction === "undo" ? ["Undo", "Undid"] : ["Redo", "Redid"];
+      await waitForPendingDomEditSaves();
+      const result = await editHistory[direction]({
+        readFile: readHistoryFile,
+        writeFile: writeProjectFile,
+        serialize: serializeHistoryFiles,
+      });
+      if (!result.ok && result.reason === "content-mismatch") {
+        showToast(`File changed outside Studio. ${noun} history was not applied.`, "info");
+        return;
+      }
+      if (result.ok && result.label) {
+        onAfterUndoRedo?.();
+        if (activeCompPath && result.paths?.includes(activeCompPath)) {
+          forceReloadSdkSession?.();
+        }
+        await syncHistoryPreviewAfterApply({ paths: result.paths, files: result.files });
+        showToast(`${verb} ${result.label}`, "info");
+      }
+    },
+    [
+      editHistory,
+      readHistoryFile,
+      showToast,
+      syncHistoryPreviewAfterApply,
+      waitForPendingDomEditSaves,
+      writeProjectFile,
+      serializeHistoryFiles,
+      onAfterUndoRedo,
+      activeCompPath,
+      forceReloadSdkSession,
+    ],
+  );
+
+  const undo = useCallback(() => apply("undo"), [apply]);
+  const redo = useCallback(() => apply("redo"), [apply]);
+  return useMemo(() => ({ undo, redo }), [undo, redo]);
+}

package/src/hooks/useServerConnection.hashProject.test.tsx

@@ -0,0 +1,94 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useServerConnection } from "./useServerConnection";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const captured: { projectId: string | null } = { projectId: null };
+
+function Probe() {
+  captured.projectId = useServerConnection().projectId;
+  return null;
+}
+
+async function flush(): Promise<void> {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+/**
+ * The hash project id outlives the project it names — a renamed folder, or a
+ * bookmark from a project that is gone. It used to be trusted unconditionally,
+ * so every later /api/projects/<id>/... request 404'd for the life of the tab,
+ * including the composition read that opens the SDK session. Telemetry after
+ * the read-reason split: 120 http_error/404 reads across 5 users in 24h.
+ */
+function stubFetch(projectRoute: { status: number } | "reject") {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      if (url === "/api/projects") {
+        return { ok: true, json: async () => ({ projects: [{ id: "real-project" }] }) } as Response;
+      }
+      if (projectRoute === "reject") throw new TypeError("Failed to fetch");
+      return { ok: projectRoute.status === 200, status: projectRoute.status } as Response;
+    }),
+  );
+}
+
+async function renderWithHash(hash: string) {
+  window.location.hash = hash;
+  const root = createRoot(document.createElement("div"));
+  await act(async () => root.render(<Probe />));
+  await flush();
+  return root;
+}
+
+describe("useServerConnection hash project id", () => {
+  beforeEach(() => {
+    captured.projectId = null;
+    window.location.hash = "";
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("keeps a hash id the server can resolve", async () => {
+    stubFetch({ status: 200 });
+    const root = await renderWithHash("#project/stale-or-not");
+
+    expect(captured.projectId).toBe("stale-or-not");
+    await act(async () => root.unmount());
+  });
+
+  it("falls back to the first project when the hash id is gone", async () => {
+    stubFetch({ status: 404 });
+    const root = await renderWithHash("#project/deleted-project");
+
+    expect(captured.projectId).toBe("real-project");
+    expect(window.location.hash).toContain("real-project");
+    await act(async () => root.unmount());
+  });
+
+  // The important one: a blip must not rewrite the user's hash out from under a
+  // project that is actually fine. Only a definite 404 is "missing".
+  it("keeps the hash id when the check itself fails", async () => {
+    stubFetch("reject");
+    const root = await renderWithHash("#project/unreachable-check");
+
+    expect(captured.projectId).toBe("unreachable-check");
+    await act(async () => root.unmount());
+  });
+
+  it("keeps the hash id on a non-404 error status", async () => {
+    stubFetch({ status: 500 });
+    const root = await renderWithHash("#project/server-erroring");
+
+    expect(captured.projectId).toBe("server-erroring");
+    await act(async () => root.unmount());
+  });
+});

package/src/hooks/useServerConnection.ts

@@ -18,6 +18,26 @@ interface ServerConnectionState {
  * Polls every 2 s until the server responds, then transitions automatically.
  * Cleans up pending timers on unmount so it is safe under React StrictMode.
  */
+/**
+ * Whether a hash-supplied project id still names something the server can
+ * resolve. Three answers, not two: a failed request must NOT be read as
+ * "missing", or one network blip would discard a perfectly good deep link.
+ *
+ * Resolved through `/api/projects/:id`, which calls the same
+ * `adapter.resolveProject` the file routes use. A match against the
+ * `/api/projects` list would be wrong twice over: that list omits session ids
+ * (which resolve fine) and skips project dirs without an `index.html`.
+ */
+async function resolveHashProject(id: string): Promise<"ok" | "missing" | "unknown"> {
+  try {
+    const res = await fetch(`/api/projects/${encodeURIComponent(id)}`);
+    if (res.ok) return "ok";
+    return res.status === 404 ? "missing" : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 export function useServerConnection(): ServerConnectionState {
   const [projectId, setProjectId] = useState<string | null>(null);
   const [resolving, setResolving] = useState(true);
@@ -39,21 +59,34 @@ export function useServerConnection(): ServerConnectionState {
     function tryConnect() {
       fetch("/api/projects")
         .then((r) => r.json())
-        .then((data) => {
+        .then(async (data) => {
           if (cancelled) return;
+          // A hash project id outlives the project it names — a renamed folder,
+          // or a bookmark from a project that is gone. Trusting it blindly made
+          // every later /api/projects/<id>/... request 404 for the life of the
+          // tab, including the composition read that opens the SDK session, so
+          // every edit fell back to the server path with nothing to show why.
+          // Telemetry after the read-reason split: 120 http_error/404 reads
+          // across 5 users in 24h, ~24 each, never recovering.
           if (hashProjectId) {
-            setProjectId(hashProjectId);
-            setWaitingForServer(false);
-          } else {
-            const first = (data.projects ?? [])[0];
-            if (first) {
-              setProjectId(first.id);
+            const state = await resolveHashProject(hashProjectId);
+            if (cancelled) return;
+            // "unknown" keeps the old behaviour: a transient failure must not
+            // rewrite the user's hash out from under a valid project.
+            if (state !== "missing") {
+              setProjectId(hashProjectId);
               setWaitingForServer(false);
-              window.location.hash = buildProjectHash(first.id);
-            } else {
-              scheduleRetry();
+              return;
             }
           }
+          const first = (data.projects ?? [])[0];
+          if (first) {
+            setProjectId(first.id);
+            setWaitingForServer(false);
+            window.location.hash = buildProjectHash(first.id);
+          } else {
+            scheduleRetry();
+          }
         })
         .catch(() => {
           if (!cancelled) scheduleRetry();

package/src/index.ts

@@ -1,5 +1,36 @@
+// UI primitives
+export { Button, buttonBase, buttonVariants } from "./components/ui/Button";
+export type { ButtonSize, ButtonVariant, PreviewState } from "./components/ui/Button";
+export { IconButton } from "./components/ui/IconButton";
+export { Tab, TabPanel, Tabs, TabsList } from "./components/ui/Tabs";
+export { Tooltip } from "./components/ui/Tooltip";
+export { cn } from "./components/ui/cn";
+export {
+  ContextMenu,
+  Menu,
+  MenuItem,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+  MenuShortcut,
+  popupSurface,
+} from "./components/ui/Menu";
+export type { MenuItemTone, PopupPreviewState } from "./components/ui/Menu";
+export { Popover } from "./components/ui/Popover";
+export { Input, fieldBase, fieldText } from "./components/ui/Input";
+export type { InputProps } from "./components/ui/Input";
+export { NumberField } from "./components/ui/NumberField";
+export type { NumberFieldProps } from "./components/ui/NumberField";
+export { Select } from "./components/ui/Select";
+export type { SelectOption, SelectProps } from "./components/ui/Select";
+export { Slider } from "./components/ui/Slider";
+export type { SliderProps } from "./components/ui/Slider";
+export { Toggle } from "./components/ui/Toggle";
+export type { ToggleProps } from "./components/ui/Toggle";
+
 // NLE Layout
 export { EditorShell } from "./components/EditorShell";
+export type { EditorShellProps } from "./components/EditorShell";
 export { NLEPreview } from "./components/nle/NLEPreview";
 export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";
 export type { CompositionLevel } from "./components/nle/CompositionBreadcrumb";
@@ -19,6 +50,10 @@ export {
 } from "./player";
 export type { TimelineElement } from "./player";
 
+// Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
+export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";
+export type { PreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";
+
 // Editor
 export { SourceEditor } from "./components/editor/SourceEditor";
 export { PropertyPanel } from "./components/editor/PropertyPanel";
@@ -37,6 +72,22 @@ export {
 } from "./components/editor/domEditingAgentPrompt";
 export type { AgentPromptElementInfo } from "./components/editor/domEditingAgentPrompt";
 
+// Render queue
+export { RenderQueue } from "./components/renders/RenderQueue";
+export type { RenderQueueProps, CompositionDimensions } from "./components/renders/RenderQueue";
+export { useRenderQueue } from "./components/renders/useRenderQueue";
+export type { FfmpegStatus } from "./components/renders/useFfmpegStatus";
+export type {
+  RenderJob,
+  ResolutionPreset,
+  StartRenderOptions,
+} from "./components/renders/useRenderQueue";
+export {
+  getPersistedRenderSettings,
+  persistRenderSettings,
+} from "./components/renders/renderSettings";
+export type { PersistedRenderSettings } from "./components/renders/renderSettings";
+
 // Hooks
 export { useElementPicker } from "./hooks/useElementPicker";
 export type { PickedElement } from "./hooks/useElementPicker";

package/src/player/components/AutomationSelectionMenu.tsx

@@ -29,7 +29,7 @@ export const AutomationSelectionMenu = memo(function AutomationSelectionMenu({
 }: AutomationSelectionMenuProps) {
   const menuRef = useContextMenuDismiss(onClose);
   const row =
-    "block w-full px-2 py-1 text-left text-[11px] text-panel-text-1 hover:bg-panel-bg-3 disabled:opacity-40";
+    "block w-full px-2 py-1 text-left text-[11px] text-panel-text-1 hover:bg-panel-hover disabled:opacity-40";
   // Same edge-clamping precedent as TrackGapContextMenu: without it a
   // right-click near the bottom/right of the timeline renders this menu
   // partially off-screen.

package/src/player/components/TimelineCanvas.tsx

@@ -179,8 +179,8 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
             left: props.contentOrigin + draggedClip.previewStart * props.pps,
             width: Math.max(draggedClip.element.duration * props.pps, 4),
             height: draggedClipHeight,
-            border: "1px solid rgba(60,230,172,0.55)",
-            background: "rgba(60,230,172,0.12)",
+            border: "1px solid color-mix(in srgb, var(--color-accent) 55%, transparent)",
+            background: "color-mix(in srgb, var(--color-accent) 12%, transparent)",
             borderRadius: 4,
             zIndex: 30,
           }}
@@ -199,8 +199,8 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
             left: props.contentOrigin + props.dropPreview.start * props.pps,
             width: DROP_PREVIEW_SECONDS * props.pps,
             height: TRACK_H - CLIP_Y * 2,
-            border: "1px solid rgba(60,230,172,0.55)",
-            background: "rgba(60,230,172,0.12)",
+            border: "1px solid color-mix(in srgb, var(--color-accent) 55%, transparent)",
+            background: "color-mix(in srgb, var(--color-accent) 12%, transparent)",
             borderRadius: 4,
             zIndex: 30,
           }}

package/src/player/components/TimelineClip.tsx

@@ -71,7 +71,6 @@ export const TimelineClip = memo(function TimelineClip({
     isSelected ? "is-selected" : "",
     isHovered ? "is-hovered" : "",
     isDragging ? "is-dragging" : "",
-    showDefaultText ? "" : "is-micro",
     isAudioTimelineElement(el) ? "is-audio" : "",
   ]
     .filter((className) => className.length > 0)

package/src/player/lib/playbackShortcuts.ts

@@ -17,6 +17,8 @@ const PLAYBACK_SHORTCUT_IGNORED_SELECTOR = [
   "[role='checkbox']",
   "[role='combobox']",
   "[role='menuitem']",
+  // Base UI's menu radio item is a `<div>`, so `button` above no longer catches it.
+  "[role='menuitemradio']",
   "[role='radio']",
   "[role='slider']",
   "[role='spinbutton']",

package/src/player/store/previewIframeStore.notify.test.tsx

@@ -0,0 +1,75 @@
+// @vitest-environment jsdom
+import { act, StrictMode, useCallback, useEffect, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it } from "vitest";
+import { useOwnPreviewIframe, usePreviewIframeStore } from "./previewIframeStore";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+// Mirrors NLEContext.tsx: a ref callback pushes the element on attach
+// (~L126, onIframeLoad) and a separate mount/dep effect re-pushes the SAME
+// ref value (~L304-306, deps include an unrelated counter like refreshKey).
+function Child({ tick }: { tick: number }) {
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const setIframe = usePreviewIframeStore((s) => s.setIframe);
+
+  const handleRef = useCallback(
+    (el: HTMLIFrameElement | null) => {
+      iframeRef.current = el;
+      setIframe(el);
+    },
+    [setIframe],
+  );
+
+  useEffect(() => {
+    setIframe(iframeRef.current);
+  }, [tick, setIframe]);
+
+  return <iframe ref={handleRef} />;
+}
+
+function Owner({ tick }: { tick: number }) {
+  useOwnPreviewIframe();
+  return <Child tick={tick} />;
+}
+
+it("does not notify raw subscribers for a repeated setIframe(sameValue)", () => {
+  let notifyCount = 0;
+  const unsubscribe = usePreviewIframeStore.subscribe(() => {
+    notifyCount += 1;
+  });
+
+  const container = document.createElement("div");
+  const root = createRoot(container);
+  act(() => {
+    root.render(
+      <StrictMode>
+        <Owner tick={0} />
+      </StrictMode>,
+    );
+  });
+  // A dep bump on the mount effect with the iframe DOM node unchanged -
+  // the shape NLEContext hits every time refreshKey moves without a new
+  // <iframe>.
+  act(() => {
+    root.render(
+      <StrictMode>
+        <Owner tick={1} />
+      </StrictMode>,
+    );
+  });
+
+  const iframe = usePreviewIframeStore.getState().iframe;
+  expect(iframe).not.toBeNull();
+
+  // 3 real Object.is-distinct transitions happen here: the ref-callback's
+  // null -> element attach, then StrictMode's mount-effect replay drives
+  // useOwnPreviewIframe's unmount cleanup (element -> null) and the
+  // re-run mount effect (null -> element) once each. Measured on the
+  // unfixed store: 7 (four of those are the SAME value re-pushed by the
+  // ref callback's own redundant effect run and the tick-bump update).
+  expect(notifyCount).toBe(3);
+
+  act(() => root.unmount());
+  unsubscribe();
+});

package/src/player/store/previewIframeStore.test.tsx

@@ -0,0 +1,29 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it } from "vitest";
+import { useOwnPreviewIframe, usePreviewIframeStore } from "./previewIframeStore";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+it("clears the store on owner unmount so a remount starts from null", () => {
+  const seen: Array<HTMLIFrameElement | null> = [];
+  const Owner = () => {
+    seen.push(useOwnPreviewIframe());
+    return null;
+  };
+  const iframe = document.createElement("iframe");
+  const first = createRoot(document.createElement("div"));
+  act(() => first.render(<Owner />));
+  act(() => usePreviewIframeStore.getState().setIframe(iframe));
+  expect(seen.at(-1)).toBe(iframe);
+
+  act(() => first.unmount());
+  expect(usePreviewIframeStore.getState().iframe).toBeNull();
+
+  seen.length = 0;
+  const second = createRoot(document.createElement("div"));
+  act(() => second.render(<Owner />));
+  expect(seen).toEqual([null]);
+  act(() => second.unmount());
+});