@hyperframes/studio 0.6.59 → 0.6.61

package/src/hooks/useStudioContextValue.ts

@@ -0,0 +1,138 @@
+import { useCallback, useMemo, useRef, useState, type DragEvent } from "react";
+import {
+  STUDIO_INSPECTOR_PANELS_ENABLED,
+  STUDIO_MOTION_PANEL_ENABLED,
+} from "../components/editor/manualEditingAvailability";
+import { readStudioMotionFromElement } from "../components/editor/studioMotion";
+import type { StudioContextValue } from "../contexts/StudioContext";
+import type { DomEditSelection } from "../components/editor/domEditing";
+
+interface StudioContextInput {
+  projectId: string;
+  activeCompPath: string | null;
+  setActiveCompPath: (path: string | null) => void;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
+  captionEditMode: boolean;
+  compositionLoading: boolean;
+  refreshKey: number;
+  setRefreshKey: React.Dispatch<React.SetStateAction<number>>;
+  currentTime: number;
+  timelineElements: StudioContextValue["timelineElements"];
+  isPlaying: boolean;
+  editHistory: { canUndo: boolean; canRedo: boolean; undoLabel: string; redoLabel: string };
+  handleUndo: StudioContextValue["handleUndo"];
+  handleRedo: StudioContextValue["handleRedo"];
+  renderQueue: {
+    jobs: unknown[];
+    isRendering: boolean;
+    deleteRender: (id: string) => void;
+    clearCompleted: () => void;
+    startRender: (options: unknown) => Promise<void>;
+  };
+  compositionDimensions: { width: number; height: number } | null;
+  waitForPendingDomEditSaves: () => Promise<void>;
+  handlePreviewIframeRef: (iframe: HTMLIFrameElement | null) => void;
+  refreshPreviewDocumentVersion: () => void;
+  timelineVisible: boolean;
+  toggleTimelineVisibility: () => void;
+}
+
+// fallow-ignore-next-line complexity
+export function buildStudioContextValue(input: StudioContextInput): StudioContextValue {
+  return {
+    projectId: input.projectId,
+    activeCompPath: input.activeCompPath,
+    setActiveCompPath: input.setActiveCompPath,
+    showToast: input.showToast,
+    previewIframeRef: input.previewIframeRef,
+    captionEditMode: input.captionEditMode,
+    compositionLoading: input.compositionLoading,
+    refreshKey: input.refreshKey,
+    setRefreshKey: input.setRefreshKey,
+    currentTime: input.currentTime,
+    timelineElements: input.timelineElements,
+    isPlaying: input.isPlaying,
+    editHistory: input.editHistory,
+    handleUndo: input.handleUndo,
+    handleRedo: input.handleRedo,
+    renderQueue: input.renderQueue,
+    compositionDimensions: input.compositionDimensions,
+    waitForPendingDomEditSaves: input.waitForPendingDomEditSaves,
+    handlePreviewIframeRef: input.handlePreviewIframeRef,
+    refreshPreviewDocumentVersion: input.refreshPreviewDocumentVersion,
+    timelineVisible: input.timelineVisible,
+    toggleTimelineVisibility: input.toggleTimelineVisibility,
+  };
+}
+
+export interface InspectorState {
+  selectedStudioMotion: ReturnType<typeof readStudioMotionFromElement> | null;
+  layersPanelActive: boolean;
+  designPanelActive: boolean;
+  motionPanelActive: boolean;
+  inspectorPanelActive: boolean;
+  inspectorButtonActive: boolean;
+  shouldShowSelectedDomBounds: boolean;
+}
+
+export function useInspectorState(
+  rightPanelTab: string,
+  rightCollapsed: boolean,
+  isPlaying: boolean,
+  domEditSelection: DomEditSelection | null,
+): InspectorState {
+  // fallow-ignore-next-line complexity
+  return useMemo(() => {
+    const selectedStudioMotion =
+      STUDIO_INSPECTOR_PANELS_ENABLED && domEditSelection
+        ? readStudioMotionFromElement(domEditSelection.element)
+        : null;
+    const layersPanelActive = STUDIO_INSPECTOR_PANELS_ENABLED && rightPanelTab === "layers";
+    const designPanelActive = STUDIO_INSPECTOR_PANELS_ENABLED && rightPanelTab === "design";
+    const motionPanelActive =
+      STUDIO_INSPECTOR_PANELS_ENABLED && STUDIO_MOTION_PANEL_ENABLED && rightPanelTab === "motion";
+    const inspectorPanelActive = layersPanelActive || designPanelActive || motionPanelActive;
+    return {
+      selectedStudioMotion,
+      layersPanelActive,
+      designPanelActive,
+      motionPanelActive,
+      inspectorPanelActive,
+      inspectorButtonActive:
+        STUDIO_INSPECTOR_PANELS_ENABLED && !rightCollapsed && inspectorPanelActive,
+      shouldShowSelectedDomBounds: inspectorPanelActive && !rightCollapsed && !isPlaying,
+    };
+  }, [rightPanelTab, rightCollapsed, isPlaying, domEditSelection]);
+}
+
+// fallow-ignore-next-line complexity
+export function useDragOverlay(onImportFiles: (files: FileList) => void) {
+  const [active, setActive] = useState(false);
+  const counterRef = useRef(0);
+  const onDragOver = useCallback((e: DragEvent) => {
+    if (!e.dataTransfer.types.includes("Files")) return;
+    e.preventDefault();
+  }, []);
+  const onDragEnter = useCallback((e: DragEvent) => {
+    if (!e.dataTransfer.types.includes("Files")) return;
+    e.preventDefault();
+    counterRef.current++;
+    setActive(true);
+  }, []);
+  const onDragLeave = useCallback(() => {
+    counterRef.current--;
+    if (counterRef.current === 0) setActive(false);
+  }, []);
+  const onDrop = useCallback(
+    (e: DragEvent) => {
+      counterRef.current = 0;
+      setActive(false);
+      if (e.defaultPrevented) return;
+      e.preventDefault();
+      if (e.dataTransfer.files.length) onImportFiles(e.dataTransfer.files);
+    },
+    [onImportFiles],
+  );
+  return { active, onDragOver, onDragEnter, onDragLeave, onDrop };
+}

package/src/utils/gsapSoftReload.test.ts

@@ -0,0 +1,104 @@
+// @vitest-environment happy-dom
+
+import { describe, it, expect, vi } from "vitest";
+import { applySoftReload } from "./gsapSoftReload";
+
+const SCRIPT_TEXT = `
+window.__timelines = window.__timelines || {};
+const tl = gsap.timeline({ paused: true });
+tl.to("#box", { opacity: 0.8 });
+window.__timelines["root"] = tl;
+`;
+
+function buildMockIframe(overrides: Record<string, unknown> = {}) {
+  const scriptEl = document.createElement("script");
+  scriptEl.textContent =
+    'const tl = gsap.timeline({ paused: true }); tl.to("#box", { opacity: 0.5 });';
+  const container = document.createElement("div");
+  container.appendChild(scriptEl);
+
+  const mockTimeline = { kill: vi.fn(), pause: vi.fn() };
+  const contentWindow = {
+    gsap: { timeline: vi.fn() },
+    __hfForceTimelineRebind: vi.fn(),
+    __timelines: { root: mockTimeline } as Record<string, typeof mockTimeline>,
+    __player: { getTime: () => 2.0, seek: vi.fn() },
+    __hfStudioManualEditsApply: vi.fn(),
+    __hfSuppressSceneMutations: undefined as undefined | (<T>(fn: () => T) => T),
+    ...overrides,
+  };
+
+  const contentDocument = {
+    querySelectorAll: (sel: string) => (sel === "script:not([src])" ? [scriptEl] : []),
+    createElement: (tag: string) => document.createElement(tag),
+    body: container,
+  };
+
+  return {
+    iframe: { contentWindow, contentDocument } as unknown as HTMLIFrameElement,
+    contentWindow,
+    mockTimeline,
+  };
+}
+
+describe("applySoftReload", () => {
+  it("returns false when iframe is null", () => {
+    expect(applySoftReload(null, SCRIPT_TEXT)).toBe(false);
+  });
+
+  it("returns false when scriptText is empty", () => {
+    const { iframe } = buildMockIframe();
+    expect(applySoftReload(iframe, "")).toBe(false);
+  });
+
+  it("returns false when gsap is not on iframe window", () => {
+    const { iframe } = buildMockIframe({ gsap: undefined });
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe(false);
+  });
+
+  it("returns false when __hfForceTimelineRebind is missing", () => {
+    const { iframe } = buildMockIframe({ __hfForceTimelineRebind: undefined });
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe(false);
+  });
+
+  it("kills existing timelines, rebinds, and re-seeks on success", () => {
+    const { iframe, contentWindow, mockTimeline } = buildMockIframe();
+    const result = applySoftReload(iframe, SCRIPT_TEXT);
+    expect(result).toBe(true);
+    expect(mockTimeline.kill).toHaveBeenCalled();
+    expect(contentWindow.__hfForceTimelineRebind).toHaveBeenCalled();
+    expect(contentWindow.__player.seek).toHaveBeenCalledWith(2.0);
+    expect(contentWindow.__hfStudioManualEditsApply).toHaveBeenCalled();
+  });
+
+  it("wraps execution in __hfSuppressSceneMutations when available", () => {
+    let suppressionCalled = false;
+    const { iframe } = buildMockIframe({
+      __hfSuppressSceneMutations: <T>(fn: () => T): T => {
+        suppressionCalled = true;
+        return fn();
+      },
+    });
+    const result = applySoftReload(iframe, SCRIPT_TEXT);
+    expect(result).toBe(true);
+    expect(suppressionCalled).toBe(true);
+  });
+
+  it("returns false when multiple GSAP scripts exist (ambiguous)", () => {
+    const script1 = document.createElement("script");
+    script1.textContent = "const tl = gsap.timeline({ paused: true });";
+    const script2 = document.createElement("script");
+    script2.textContent = 'tl.to("#other", { x: 10 });';
+    const container = document.createElement("div");
+    container.appendChild(script1);
+    container.appendChild(script2);
+
+    const { iframe } = buildMockIframe();
+    (iframe as unknown as { contentDocument: unknown }).contentDocument = {
+      querySelectorAll: (sel: string) => (sel === "script:not([src])" ? [script1, script2] : []),
+      createElement: (tag: string) => document.createElement(tag),
+      body: container,
+    };
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe(false);
+  });
+});

package/src/utils/gsapSoftReload.ts

@@ -0,0 +1,89 @@
+type IframeWindow = Window & {
+  __timelines?: Record<string, { kill?: () => void; pause?: () => void }>;
+  __player?: { getTime?: () => number; seek?: (t: number) => void };
+  __hfForceTimelineRebind?: () => void;
+  __hfSuppressSceneMutations?: <T>(fn: () => T) => T;
+  __hfStudioManualEditsApply?: () => void;
+  gsap?: { timeline?: (...args: unknown[]) => unknown };
+};
+
+function isGsapScript(text: string): boolean {
+  return (
+    text.includes("gsap.timeline") ||
+    text.includes("__timelines") ||
+    text.includes(".to(") ||
+    text.includes(".set(")
+  );
+}
+
+function findGsapScriptElements(doc: Document): HTMLScriptElement[] {
+  const results: HTMLScriptElement[] = [];
+  const scripts = doc.querySelectorAll<HTMLScriptElement>("script:not([src])");
+  for (const script of scripts) {
+    if (isGsapScript(script.textContent || "")) results.push(script);
+  }
+  return results;
+}
+
+/**
+ * Replace the GSAP script in the live iframe without reloading. This preserves
+ * the WebGL context and shader transition cache.
+ *
+ * Scoped to root-document GSAP scripts only — scripts inside `<template>`
+ * elements (sub-compositions) are not visible to `querySelectorAll` and will
+ * fall back to a full iframe reload.
+ *
+ * Returns false (triggering a full reload fallback) when:
+ * - The iframe or GSAP runtime isn't available
+ * - Multiple GSAP scripts are found (ambiguous which to replace)
+ * - No matching GSAP script element exists in the live DOM
+ */
+export function applySoftReload(iframe: HTMLIFrameElement | null, scriptText: string): boolean {
+  if (!iframe || !scriptText) return false;
+
+  const win = iframe.contentWindow as IframeWindow | null;
+  const doc = iframe.contentDocument;
+  if (!win || !doc) return false;
+  if (!win.gsap || !win.__hfForceTimelineRebind) return false;
+
+  const gsapScripts = findGsapScriptElements(doc);
+  if (gsapScripts.length !== 1) return false;
+  const oldScriptEl = gsapScripts[0]!;
+
+  const currentTime = win.__player?.getTime?.() ?? 0;
+
+  const doReload = () => {
+    const timelines = win.__timelines;
+    if (timelines) {
+      for (const key of Object.keys(timelines)) {
+        try {
+          timelines[key]?.kill?.();
+        } catch {}
+        delete timelines[key];
+      }
+    }
+
+    oldScriptEl.remove();
+    const newScript = doc.createElement("script");
+    // IIFE prevents const/let redeclaration errors across consecutive edits.
+    // Top-level declarations are scoped to the IIFE; window.* assignments
+    // (e.g. window.__timelines["root"] = tl) still reach the global scope.
+    newScript.textContent = `(function(){${scriptText}\n})();`;
+    doc.body.appendChild(newScript);
+
+    win.__hfForceTimelineRebind?.();
+    win.__player?.seek?.(currentTime);
+    win.__hfStudioManualEditsApply?.();
+  };
+
+  try {
+    if (win.__hfSuppressSceneMutations) {
+      win.__hfSuppressSceneMutations(doReload);
+    } else {
+      doReload();
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/studioPreviewHelpers.ts

@@ -3,6 +3,7 @@ import { resolveVisualDomEditSelectionTarget } from "../components/editor/domEdi
 import {
   getDomLayerPatchTarget,
   isElementComputedVisible,
+  resolveAllVisualDomEditTargets,
 } from "../components/editor/domEditingElement";
 import { getEventTargetElement } from "./studioHelpers";
 
@@ -58,6 +59,7 @@ function removePointerEventsOverride(style: HTMLStyleElement | null): void {
   }
 }
 
+// fallow-ignore-next-line complexity
 export function getPreviewTargetFromPointer(
   iframe: HTMLIFrameElement,
   clientX: number,
@@ -98,6 +100,42 @@ export function getPreviewTargetFromPointer(
   }
 }
 
+/** Returns all independently-selectable elements at the pointer (topmost first). */
+export function getAllPreviewTargetsFromPointer(
+  iframe: HTMLIFrameElement,
+  clientX: number,
+  clientY: number,
+  activeCompositionPath: string | null,
+): HTMLElement[] {
+  let doc: Document | null = null;
+  let win: Window | null = null;
+  try {
+    doc = iframe.contentDocument;
+    win = iframe.contentWindow;
+  } catch {
+    return [];
+  }
+  if (!doc || !win) return [];
+
+  const localPointer = resolvePreviewLocalPointer(iframe, doc, win, clientX, clientY);
+  if (!localPointer) return [];
+
+  const overrideStyle = forcePointerEventsAuto(doc);
+  try {
+    if (typeof doc.elementsFromPoint === "function") {
+      return resolveAllVisualDomEditTargets(doc.elementsFromPoint(localPointer.x, localPointer.y), {
+        activeCompositionPath,
+      });
+    }
+    const fallback = getEventTargetElement(doc.elementFromPoint(localPointer.x, localPointer.y));
+    if (!fallback || !getDomLayerPatchTarget(fallback, activeCompositionPath)) return [];
+    if (!isElementComputedVisible(fallback)) return [];
+    return [fallback];
+  } finally {
+    removePointerEventsOverride(overrideStyle);
+  }
+}
+
 function objectLike(value: unknown): object | null {
   return value && (typeof value === "object" || typeof value === "function") ? value : null;
 }