@hyperframes/studio 0.8.55 → 0.8.57

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

@@ -0,0 +1,90 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { GridOverlay } from "./GridOverlay";
+import { PreviewOverlayProvider } from "./PreviewOverlayProvider";
+import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  window.localStorage.clear();
+  usePreviewIframeStore.getState().setIframe(null);
+});
+
+function compositionFrame() {
+  const iframe = document.createElement("iframe");
+  iframe.getBoundingClientRect = () => new DOMRect(12, 18, 640, 360);
+  const root = iframe.contentDocument?.createElement("div");
+  root?.setAttribute("data-composition-id", "main");
+  root?.setAttribute("data-width", "1280");
+  root?.setAttribute("data-height", "720");
+  if (root) iframe.contentDocument?.body.append(root);
+  document.body.append(iframe);
+  return iframe;
+}
+
+describe("PreviewOverlayProvider", () => {
+  it("derives grid geometry after the iframe prop becomes available", async () => {
+    window.localStorage.setItem(
+      "hf-studio-ui-preferences",
+      JSON.stringify({ gridVisible: true, gridSpacing: 20 }),
+    );
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    act(() => {
+      root.render(
+        <PreviewOverlayProvider iframe={null}>
+          <GridOverlay />
+        </PreviewOverlayProvider>,
+      );
+    });
+    expect(host.querySelector('[aria-hidden="true"]')).not.toBeNull();
+
+    const iframe = compositionFrame();
+    act(() => {
+      root.render(
+        <PreviewOverlayProvider iframe={iframe}>
+          <GridOverlay />
+        </PreviewOverlayProvider>,
+      );
+    });
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 400));
+    });
+
+    const grid = host.querySelector<HTMLElement>('[aria-hidden="true"]');
+    expect([grid?.style.left, grid?.style.top, grid?.style.width, grid?.style.height]).toEqual([
+      "12px",
+      "18px",
+      "640px",
+      "360px",
+    ]);
+    expect(grid?.style.backgroundSize).toBe("20px 20px");
+    act(() => root.unmount());
+  });
+
+  it("does not clear an iframe store entry owned elsewhere on unmount", () => {
+    const ownerIframe = compositionFrame();
+    usePreviewIframeStore.getState().setIframe(ownerIframe);
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    act(() => {
+      root.render(
+        <PreviewOverlayProvider iframe={null}>
+          <GridOverlay />
+        </PreviewOverlayProvider>,
+      );
+    });
+    act(() => root.unmount());
+
+    expect(usePreviewIframeStore.getState().iframe).toBe(ownerIframe);
+  });
+});

package/src/components/editor/PreviewOverlayProvider.tsx

@@ -0,0 +1,86 @@
+import { createContext, useContext, useRef, useState, type ReactNode, type RefObject } from "react";
+import {
+  usePreviewCompositionRect,
+  type PreviewCompositionRect,
+} from "./usePreviewCompositionRect";
+import { usePreviewGuidesStore } from "./previewGuidesStore";
+import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
+import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
+
+export interface PreviewSnapPreferences {
+  snapEnabled: boolean;
+  gridVisible: boolean;
+  gridSpacing: number;
+  snapToGrid: boolean;
+}
+
+interface PreviewOverlayContextValue {
+  state: {
+    snapPrefs: PreviewSnapPreferences;
+    rulerVisible: boolean;
+    safeMarginsVisible: boolean;
+    iframeRef: RefObject<HTMLIFrameElement | null>;
+    compositionRect: PreviewCompositionRect;
+  };
+  actions: {
+    setSnapPrefs: (patch: Partial<PreviewSnapPreferences>) => void;
+    toggleRulers: () => void;
+    toggleSafeMargins: () => void;
+  };
+}
+
+const PreviewOverlayContext = createContext<PreviewOverlayContextValue | null>(null);
+
+function readSnapPrefs(): PreviewSnapPreferences {
+  const prefs = readStudioUiPreferences();
+  return {
+    snapEnabled: prefs.snapEnabled ?? true,
+    gridVisible: prefs.gridVisible ?? false,
+    gridSpacing: prefs.gridSpacing ?? 50,
+    snapToGrid: prefs.snapToGrid ?? false,
+  };
+}
+
+export interface PreviewOverlayProviderProps {
+  iframe?: HTMLIFrameElement | null;
+  children: ReactNode;
+}
+
+export function PreviewOverlayProvider({ iframe, children }: PreviewOverlayProviderProps) {
+  const overlayRef = useRef<HTMLDivElement | null>(null);
+  const [snapPrefs, setSnapPrefs] = useState(readSnapPrefs);
+  const rulerVisible = usePreviewGuidesStore((state) => state.rulerVisible);
+  const safeMarginsVisible = usePreviewGuidesStore((state) => state.safeMarginsVisible);
+  const liveIframe = useLivePreviewIframe();
+  const resolvedIframe = iframe ?? liveIframe;
+  const iframeRef = useRef<HTMLIFrameElement | null>(resolvedIframe);
+  iframeRef.current = resolvedIframe;
+  const compositionRect = usePreviewCompositionRect(overlayRef, resolvedIframe);
+
+  const contextValue: PreviewOverlayContextValue = {
+    state: { snapPrefs, rulerVisible, safeMarginsVisible, iframeRef, compositionRect },
+    actions: {
+      setSnapPrefs: (patch) => {
+        writeStudioUiPreferences(patch);
+        setSnapPrefs((current) => ({ ...current, ...patch }));
+      },
+      toggleRulers: () => usePreviewGuidesStore.getState().toggle("rulerVisible"),
+      toggleSafeMargins: () => usePreviewGuidesStore.getState().toggle("safeMarginsVisible"),
+    },
+  };
+
+  return (
+    <PreviewOverlayContext.Provider value={contextValue}>
+      <div ref={overlayRef} className="absolute inset-0">
+        {children}
+      </div>
+    </PreviewOverlayContext.Provider>
+  );
+}
+
+export function usePreviewOverlayContext(): PreviewOverlayContextValue {
+  const context = useContext(PreviewOverlayContext);
+  if (!context)
+    throw new Error("usePreviewOverlayContext must be used within PreviewOverlayProvider");
+  return context;
+}

package/src/components/editor/PropertyPanel.deselect.test.tsx

@@ -0,0 +1,71 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import { PropertyPanel } from "./PropertyPanel";
+import type { PropertyPanelProps } from "./propertyPanelHelpers";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+vi.mock("../../contexts/StudioContext", async () => {
+  const actual = await vi.importActual<typeof import("../../contexts/StudioContext")>(
+    "../../contexts/StudioContext",
+  );
+  return { ...actual, useStudioShellContext: () => ({ showToast: vi.fn() }) };
+});
+
+function selectedElement(): NonNullable<PropertyPanelProps["element"]> {
+  return {
+    element: document.createElement("div"),
+    id: "el",
+    selector: "#el",
+    label: "El",
+    tagName: "div",
+    sourceFile: "index.html",
+    compositionPath: "index.html",
+    isCompositionHost: false,
+    isInsideLockedComposition: false,
+    boundingBox: { x: 0, y: 0, width: 10, height: 10 },
+    textContent: "",
+    dataAttributes: {},
+    inlineStyles: {},
+    computedStyles: {},
+    textFields: [],
+    capabilities: {
+      canSelect: true,
+      canEditStyles: true,
+      canCrop: true,
+      canMove: true,
+      canResize: true,
+      canApplyManualOffset: true,
+      canApplyManualSize: true,
+      canApplyManualRotation: true,
+    },
+  };
+}
+
+describe("PropertyPanel deselect", () => {
+  it("re-renders to the empty state on deselect without a hooks-order crash", () => {
+    const props = {
+      element: selectedElement(),
+      assets: [],
+      onSetStyle: vi.fn(),
+      onSetText: vi.fn(),
+      onSetAttributeLive: vi.fn(),
+      onClearSelection: vi.fn(),
+    } as unknown as PropertyPanelProps;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => root.render(<PropertyPanel {...props} />));
+
+    // A same-instance re-render with no element — Escape, clicking empty canvas,
+    // or "Clear selection" — must not change which hooks ran.
+    expect(() => {
+      act(() => root.render(<PropertyPanel {...props} element={null} />));
+    }).not.toThrow();
+
+    act(() => root.unmount());
+  });
+});

package/src/components/editor/PropertyPanel.tsx

@@ -37,6 +37,7 @@ import { GestureRecordPanelButton } from "./GestureRecordControl";
 import { PropertyPanelEmptyState } from "./PropertyPanelEmptyState";
 import { DesignPanelInputProvider } from "../../contexts/DesignPanelInputContext";
 import { isAudioDomElement } from "../../utils/timelineInspector";
+import { useManualEditDisabledFlags } from "./previewReadOnlyContext";
 
 // Re-export helpers that external consumers import from this module
 export {
@@ -175,6 +176,9 @@ export const PropertyPanel = memo(function PropertyPanel(props: PropertyPanelPro
     scale: 1,
     transformPerspective: 0,
   };
+  // Unconditional like the hooks above: must not sit behind the `!element` return below.
+  const { manualOffsetEditingDisabled, manualSizeEditingDisabled, manualRotationEditingDisabled } =
+    useManualEditDisabledFlags(element?.capabilities);
 
   if (!element) {
     return (
@@ -189,9 +193,6 @@ export const PropertyPanel = memo(function PropertyPanel(props: PropertyPanelPro
     );
   }
 
-  const manualOffsetEditingDisabled = !element.capabilities.canApplyManualOffset;
-  const manualSizeEditingDisabled = !element.capabilities.canApplyManualSize;
-  const manualRotationEditingDisabled = !element.capabilities.canApplyManualRotation;
   const sourceLabel = element.id ? `#${element.id}` : (element.selector ?? "");
   // Capabilities are already resolved on the selection; recompute only sections,
   // feeding the live GSAP tween count (arrives on the gsapAnimations prop, not the

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

@@ -7,6 +7,7 @@ import { useAppHotkeys } from "../../hooks/useAppHotkeys";
 import { usePlayerStore } from "../../player/store/playerStore";
 import type { DomEditSelection } from "./domEditing";
 import { SnapToolbar } from "./SnapToolbar";
+import { PreviewOverlayProvider } from "./PreviewOverlayProvider";
 import { usePreviewGuidesStore } from "./previewGuidesStore";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -17,14 +18,18 @@ afterEach(() => {
   usePlayerStore.getState().reset();
 });
 
-function renderToolbar(onSnapChange = vi.fn()) {
+function renderToolbar() {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
   act(() => {
-    root.render(<SnapToolbar onSnapChange={onSnapChange} />);
+    root.render(
+      <PreviewOverlayProvider>
+        <SnapToolbar />
+      </PreviewOverlayProvider>,
+    );
   });
-  return { root, onSnapChange };
+  return { root };
 }
 
 function AppHotkeyHarness() {
@@ -54,12 +59,13 @@ function AppHotkeyHarness() {
     handleDuplicate: vi.fn(async () => false),
     onResetKeyframes: vi.fn(() => false),
     onDeleteSelectedKeyframes: vi.fn(),
+    readOnlyPreview: false,
   });
 
   return null;
 }
 
-function renderToolbarWithAppHotkeys(onSnapChange = vi.fn()) {
+function renderToolbarWithAppHotkeys() {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
@@ -67,16 +73,18 @@ function renderToolbarWithAppHotkeys(onSnapChange = vi.fn()) {
     root.render(
       <>
         <AppHotkeyHarness />
-        <SnapToolbar onSnapChange={onSnapChange} />
+        <PreviewOverlayProvider>
+          <SnapToolbar />
+        </PreviewOverlayProvider>
       </>,
     );
   });
-  return { root, onSnapChange };
+  return { root };
 }
 
 describe("SnapToolbar keyboard shortcuts", () => {
   it("toggles snap on an unclaimed S keypress", () => {
-    const { root, onSnapChange } = renderToolbar();
+    const { root } = renderToolbar();
 
     act(() => {
       document.dispatchEvent(
@@ -84,12 +92,14 @@ describe("SnapToolbar keyboard shortcuts", () => {
       );
     });
 
-    expect(onSnapChange).toHaveBeenCalledWith(expect.objectContaining({ snapEnabled: false }));
+    expect(
+      JSON.parse(window.localStorage.getItem("hf-studio-ui-preferences") ?? "{}").snapEnabled,
+    ).toBe(false);
     act(() => root.unmount());
   });
 
   it("does not toggle snap when another handler already prevented S", () => {
-    const { root, onSnapChange } = renderToolbar();
+    const { root } = renderToolbar();
     const event = new KeyboardEvent("keydown", {
       key: "s",
       bubbles: true,
@@ -101,12 +111,14 @@ describe("SnapToolbar keyboard shortcuts", () => {
       document.dispatchEvent(event);
     });
 
-    expect(onSnapChange).not.toHaveBeenCalled();
+    expect(
+      JSON.parse(window.localStorage.getItem("hf-studio-ui-preferences") ?? "{}").snapEnabled,
+    ).not.toBe(false);
     act(() => root.unmount());
   });
 
   it("does not toggle snap when the app split shortcut claims S without a selected clip", () => {
-    const { root, onSnapChange } = renderToolbarWithAppHotkeys();
+    const { root } = renderToolbarWithAppHotkeys();
 
     act(() => {
       document.dispatchEvent(
@@ -114,7 +126,9 @@ describe("SnapToolbar keyboard shortcuts", () => {
       );
     });
 
-    expect(onSnapChange).not.toHaveBeenCalled();
+    expect(
+      JSON.parse(window.localStorage.getItem("hf-studio-ui-preferences") ?? "{}").snapEnabled,
+    ).not.toBe(false);
     act(() => root.unmount());
   });
 });

package/src/components/editor/SnapToolbar.tsx

@@ -1,59 +1,26 @@
 import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { MagnetStraight, GridFour, Path, Ruler, FrameCorners } from "@phosphor-icons/react";
-import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 import { usePlayerStore } from "../../player/store/playerStore";
-import { usePreviewGuidesStore } from "./previewGuidesStore";
-
-const SNAP_DEFAULTS = {
-  snapEnabled: true,
-  gridVisible: false,
-  gridSpacing: 50,
-  snapToGrid: false,
-};
-
-// fallow-ignore-next-line complexity
-function readSnapPrefs() {
-  const prefs = readStudioUiPreferences();
-  return {
-    snapEnabled: prefs.snapEnabled ?? SNAP_DEFAULTS.snapEnabled,
-    gridVisible: prefs.gridVisible ?? SNAP_DEFAULTS.gridVisible,
-    gridSpacing: prefs.gridSpacing ?? SNAP_DEFAULTS.gridSpacing,
-    snapToGrid: prefs.snapToGrid ?? SNAP_DEFAULTS.snapToGrid,
-  };
-}
-
-interface SnapToolbarProps {
-  onSnapChange?: (prefs: {
-    snapEnabled: boolean;
-    gridVisible: boolean;
-    gridSpacing: number;
-    snapToGrid: boolean;
-  }) => void;
-}
+import { usePreviewOverlayContext } from "./PreviewOverlayProvider";
 
 // fallow-ignore-next-line complexity
-export const SnapToolbar = memo(function SnapToolbar({ onSnapChange }: SnapToolbarProps) {
-  const [prefs, setPrefs] = useState(readSnapPrefs);
+export const SnapToolbar = memo(function SnapToolbar() {
   const [gridPopoverOpen, setGridPopoverOpen] = useState(false);
+  const { state, actions } = usePreviewOverlayContext();
+  const { snapPrefs: prefs, rulerVisible, safeMarginsVisible } = state;
   // Motion-path "set destination" toggle — shown only when the selected element
   // can take a path; arms a single canvas click to place it (MotionPathOverlay).
   const motionPathCreateAvailable = usePlayerStore((s) => s.motionPathCreateAvailable);
   const motionPathArmed = usePlayerStore((s) => s.motionPathArmed);
   const setMotionPathArmed = usePlayerStore((s) => s.setMotionPathArmed);
-  const guides = usePreviewGuidesStore();
   const popoverRef = useRef<HTMLDivElement>(null);
   const gridButtonRef = useRef<HTMLButtonElement>(null);
 
   const updatePrefs = useCallback(
     (patch: Partial<typeof prefs>) => {
-      setPrefs((prev) => {
-        const next = { ...prev, ...patch };
-        writeStudioUiPreferences(patch);
-        onSnapChange?.(next);
-        return next;
-      });
+      actions.setSnapPrefs(patch);
     },
-    [onSnapChange],
+    [actions],
   );
 
   const toggleSnap = useCallback(() => {
@@ -74,16 +41,16 @@ export const SnapToolbar = memo(function SnapToolbar({ onSnapChange }: SnapToolb
       if (t instanceof HTMLIFrameElement) return;
       if (e.key === "s" && !e.metaKey && !e.ctrlKey && !e.altKey) {
         e.preventDefault();
-        updatePrefs({ snapEnabled: !readSnapPrefs().snapEnabled });
+        updatePrefs({ snapEnabled: !prefs.snapEnabled });
       }
       if (e.key === "g" && !e.metaKey && !e.ctrlKey && !e.altKey) {
         e.preventDefault();
-        updatePrefs({ gridVisible: !readSnapPrefs().gridVisible });
+        updatePrefs({ gridVisible: !prefs.gridVisible });
       }
     };
     document.addEventListener("keydown", handleKeyDown);
     return () => document.removeEventListener("keydown", handleKeyDown);
-  }, [updatePrefs]);
+  }, [prefs.gridVisible, prefs.snapEnabled, updatePrefs]);
 
   useEffect(() => {
     if (!gridPopoverOpen) return;
@@ -123,23 +90,27 @@ export const SnapToolbar = memo(function SnapToolbar({ onSnapChange }: SnapToolb
           ["rulerVisible", "Ruler", Ruler],
           ["safeMarginsVisible", "Safe margins", FrameCorners],
         ] as const
-      ).map(([key, label, Icon]) => (
-        <button
-          key={key}
-          type="button"
-          className={`rounded-md p-1.5 transition-colors active:scale-[0.95] ${
-            guides[key]
-              ? "bg-studio-accent/20 text-studio-accent"
-              : "bg-black/40 text-white/60 hover:bg-black/60 hover:text-white/80"
-          }`}
-          onClick={() => guides.toggle(key)}
-          title={`${label} ${guides[key] ? "on" : "off"}`}
-          aria-label={`Toggle ${label.toLowerCase()}`}
-          aria-pressed={guides[key]}
-        >
-          <Icon size={16} weight={guides[key] ? "fill" : "regular"} />
-        </button>
-      ))}
+      ).map(([key, label, Icon]) => {
+        const visible = key === "rulerVisible" ? rulerVisible : safeMarginsVisible;
+        const toggle = key === "rulerVisible" ? actions.toggleRulers : actions.toggleSafeMargins;
+        return (
+          <button
+            key={key}
+            type="button"
+            className={`rounded-md p-1.5 transition-colors active:scale-[0.95] ${
+              visible
+                ? "bg-studio-accent/20 text-studio-accent"
+                : "bg-black/40 text-white/60 hover:bg-black/60 hover:text-white/80"
+            }`}
+            onClick={toggle}
+            title={`${label} ${visible ? "on" : "off"}`}
+            aria-label={`Toggle ${label.toLowerCase()}`}
+            aria-pressed={visible}
+          >
+            <Icon size={16} weight={visible ? "fill" : "regular"} />
+          </button>
+        );
+      })}
       <button
         type="button"
         className={`rounded-md p-1.5 transition-colors active:scale-[0.95] ${

package/src/components/editor/domEditOverlayTestMocks.ts

@@ -0,0 +1,16 @@
+import { vi } from "vitest";
+
+vi.mock("./useDomEditCompositionRect", () => ({
+  useDomEditCompositionRect: () => ({
+    left: 0,
+    top: 0,
+    width: 800,
+    height: 450,
+    scaleX: 1,
+    scaleY: 1,
+  }),
+}));
+
+vi.mock("./offCanvasIndicatorRefresh", () => ({
+  startOffCanvasIndicatorRefresh: () => () => undefined,
+}));