@hyperframes/studio 0.6.0-alpha.9 → 0.6.0

package/src/contexts/PanelLayoutContext.tsx

@@ -0,0 +1,68 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import type { usePanelLayout } from "../hooks/usePanelLayout";
+
+type PanelLayoutValue = ReturnType<typeof usePanelLayout>;
+
+const PanelLayoutContext = createContext<PanelLayoutValue | null>(null);
+
+export function usePanelLayoutContext(): PanelLayoutValue {
+  const ctx = useContext(PanelLayoutContext);
+  if (!ctx) throw new Error("usePanelLayoutContext must be used within PanelLayoutProvider");
+  return ctx;
+}
+
+export function PanelLayoutProvider({
+  value: {
+    leftWidth,
+    setLeftWidth,
+    rightWidth,
+    leftCollapsed,
+    setLeftCollapsed,
+    rightCollapsed,
+    setRightCollapsed,
+    rightPanelTab,
+    setRightPanelTab,
+    toggleLeftSidebar,
+    handlePanelResizeStart,
+    handlePanelResizeMove,
+    handlePanelResizeEnd,
+  },
+  children,
+}: {
+  value: PanelLayoutValue;
+  children: ReactNode;
+}) {
+  const stable = useMemo<PanelLayoutValue>(
+    () => ({
+      leftWidth,
+      setLeftWidth,
+      rightWidth,
+      leftCollapsed,
+      setLeftCollapsed,
+      rightCollapsed,
+      setRightCollapsed,
+      rightPanelTab,
+      setRightPanelTab,
+      toggleLeftSidebar,
+      handlePanelResizeStart,
+      handlePanelResizeMove,
+      handlePanelResizeEnd,
+    }),
+    [
+      leftWidth,
+      setLeftWidth,
+      rightWidth,
+      leftCollapsed,
+      setLeftCollapsed,
+      rightCollapsed,
+      setRightCollapsed,
+      rightPanelTab,
+      setRightPanelTab,
+      toggleLeftSidebar,
+      handlePanelResizeStart,
+      handlePanelResizeMove,
+      handlePanelResizeEnd,
+    ],
+  );
+  return <PanelLayoutContext value={stable}>{children}</PanelLayoutContext>;
+}

package/src/contexts/StudioContext.tsx

@@ -0,0 +1,135 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import type { TimelineElement } from "../player";
+import type { CompositionDimensions } from "../components/renders/RenderQueue";
+
+export interface StudioContextValue {
+  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: TimelineElement[];
+  isPlaying: boolean;
+  editHistory: {
+    canUndo: boolean;
+    canRedo: boolean;
+    undoLabel: string | undefined;
+    redoLabel: string | undefined;
+  };
+  handleUndo: () => Promise<void>;
+  handleRedo: () => Promise<void>;
+  renderQueue: {
+    jobs: unknown[];
+    isRendering: boolean;
+    deleteRender: (jobId: string) => void;
+    clearCompleted: () => void;
+    startRender: (options: unknown) => Promise<void>;
+  };
+  compositionDimensions: CompositionDimensions | null;
+  waitForPendingDomEditSaves: () => Promise<void>;
+  handlePreviewIframeRef: (iframe: HTMLIFrameElement | null) => void;
+  refreshPreviewDocumentVersion: () => void;
+  timelineVisible: boolean;
+  toggleTimelineVisibility: () => void;
+}
+
+const StudioContext = createContext<StudioContextValue | null>(null);
+
+export function useStudioContext(): StudioContextValue {
+  const ctx = useContext(StudioContext);
+  if (!ctx) throw new Error("useStudioContext must be used within StudioProvider");
+  return ctx;
+}
+
+export function StudioProvider({
+  value,
+  children,
+}: {
+  value: StudioContextValue;
+  children: ReactNode;
+}) {
+  const {
+    projectId,
+    activeCompPath,
+    setActiveCompPath,
+    showToast,
+    previewIframeRef,
+    captionEditMode,
+    compositionLoading,
+    refreshKey,
+    setRefreshKey,
+    currentTime,
+    timelineElements,
+    isPlaying,
+    editHistory,
+    handleUndo,
+    handleRedo,
+    renderQueue,
+    compositionDimensions,
+    waitForPendingDomEditSaves,
+    handlePreviewIframeRef,
+    refreshPreviewDocumentVersion,
+    timelineVisible,
+    toggleTimelineVisibility,
+  } = value;
+
+  const stable = useMemo<StudioContextValue>(
+    () => ({
+      projectId,
+      activeCompPath,
+      setActiveCompPath,
+      showToast,
+      previewIframeRef,
+      captionEditMode,
+      compositionLoading,
+      refreshKey,
+      setRefreshKey,
+      currentTime,
+      timelineElements,
+      isPlaying,
+      editHistory,
+      handleUndo,
+      handleRedo,
+      renderQueue,
+      compositionDimensions,
+      waitForPendingDomEditSaves,
+      handlePreviewIframeRef,
+      refreshPreviewDocumentVersion,
+      timelineVisible,
+      toggleTimelineVisibility,
+    }),
+    // Representative subset of deps that actually change — stable callbacks
+    // (showToast, setActiveCompPath, etc.) are included for correctness but
+    // won't trigger re-renders on their own.
+    [
+      projectId,
+      activeCompPath,
+      captionEditMode,
+      compositionLoading,
+      refreshKey,
+      currentTime,
+      isPlaying,
+      compositionDimensions,
+      timelineVisible,
+      editHistory,
+      timelineElements,
+      renderQueue,
+      setActiveCompPath,
+      showToast,
+      previewIframeRef,
+      setRefreshKey,
+      handleUndo,
+      handleRedo,
+      waitForPendingDomEditSaves,
+      handlePreviewIframeRef,
+      refreshPreviewDocumentVersion,
+      toggleTimelineVisibility,
+    ],
+  );
+  return <StudioContext value={stable}>{children}</StudioContext>;
+}

package/src/hooks/useAppHotkeys.ts

@@ -0,0 +1,326 @@
+import { useCallback, useEffect, useRef } from "react";
+import { usePlayerStore } from "../player";
+import type { TimelineElement } from "../player";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { LeftSidebarHandle } from "../components/sidebar/LeftSidebar";
+import { STUDIO_MANUAL_EDITS_PATH } from "../components/editor/manualEdits";
+import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
+import { shouldHandleTimelineToggleHotkey, isEditableTarget } from "../utils/timelineDiscovery";
+import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
+
+// ── Types ──
+
+interface EditHistoryHandle {
+  undo: (callbacks: {
+    readFile: (path: string) => Promise<string>;
+    writeFile: (path: string, content: string) => Promise<void>;
+  }) => Promise<{
+    ok: boolean;
+    reason?: string;
+    label?: string;
+    paths?: string[];
+  }>;
+  redo: (callbacks: {
+    readFile: (path: string) => Promise<string>;
+    writeFile: (path: string, content: string) => Promise<void>;
+  }) => Promise<{
+    ok: boolean;
+    reason?: string;
+    label?: string;
+    paths?: string[];
+  }>;
+}
+
+interface UseAppHotkeysParams {
+  toggleTimelineVisibility: () => void;
+  handleTimelineElementDelete: (element: TimelineElement) => Promise<void>;
+  handleDomEditElementDelete: (selection: DomEditSelection) => Promise<void>;
+  domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
+  clearDomSelectionRef: React.MutableRefObject<() => void>;
+  editHistory: EditHistoryHandle;
+  readOptionalProjectFile: (path: string) => Promise<string>;
+  readProjectFile: (path: string) => Promise<string>;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  domEditSaveTimestampRef: React.MutableRefObject<number>;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  syncHistoryPreviewAfterApply: (paths: string[] | undefined) => Promise<void>;
+  waitForPendingDomEditSaves: () => Promise<void>;
+  leftSidebarRef: React.RefObject<LeftSidebarHandle | null>;
+}
+
+// ── Hook ──
+
+export function useAppHotkeys({
+  toggleTimelineVisibility,
+  handleTimelineElementDelete,
+  handleDomEditElementDelete,
+  domEditSelectionRef,
+  clearDomSelectionRef,
+  editHistory,
+  readOptionalProjectFile,
+  readProjectFile,
+  writeProjectFile,
+  domEditSaveTimestampRef,
+  showToast,
+  syncHistoryPreviewAfterApply,
+  waitForPendingDomEditSaves,
+  leftSidebarRef,
+}: UseAppHotkeysParams) {
+  const previewHotkeyWindowRef = useRef<Window | null>(null);
+  const handleAppKeyDownRef = useRef<((event: KeyboardEvent) => void) | undefined>(undefined);
+  const previewHistoryHotkeyCleanupRef = useRef<(() => void) | null>(null);
+
+  // ── Timeline toggle hotkey ──
+
+  const handleTimelineToggleHotkey = useCallback(
+    (event: KeyboardEvent) => {
+      if (!shouldHandleTimelineToggleHotkey(event)) return;
+      event.preventDefault();
+      toggleTimelineVisibility();
+    },
+    [toggleTimelineVisibility],
+  );
+
+  // ── History file read/write helpers ──
+
+  const readHistoryProjectFile = useCallback(
+    async (path: string): Promise<string> => {
+      return path === STUDIO_MANUAL_EDITS_PATH || path === STUDIO_MOTION_PATH
+        ? readOptionalProjectFile(path)
+        : readProjectFile(path);
+    },
+    [readOptionalProjectFile, readProjectFile],
+  );
+
+  const writeHistoryProjectFile = useCallback(
+    async (path: string, content: string): Promise<void> => {
+      domEditSaveTimestampRef.current = Date.now();
+      await writeProjectFile(path, content);
+    },
+    [domEditSaveTimestampRef, writeProjectFile],
+  );
+
+  // ── Undo / Redo ──
+
+  const handleUndo = useCallback(async () => {
+    await waitForPendingDomEditSaves();
+    const result = await editHistory.undo({
+      readFile: readHistoryProjectFile,
+      writeFile: writeHistoryProjectFile,
+    });
+    if (!result.ok && result.reason === "content-mismatch") {
+      showToast("File changed outside Studio. Undo history was not applied.", "info");
+      return;
+    }
+    if (result.ok && result.label) {
+      clearDomSelectionRef.current();
+      await syncHistoryPreviewAfterApply(result.paths);
+      showToast(`Undid ${result.label}`, "info");
+    }
+  }, [
+    clearDomSelectionRef,
+    editHistory,
+    readHistoryProjectFile,
+    showToast,
+    syncHistoryPreviewAfterApply,
+    waitForPendingDomEditSaves,
+    writeHistoryProjectFile,
+  ]);
+
+  const handleRedo = useCallback(async () => {
+    await waitForPendingDomEditSaves();
+    const result = await editHistory.redo({
+      readFile: readHistoryProjectFile,
+      writeFile: writeHistoryProjectFile,
+    });
+    if (!result.ok && result.reason === "content-mismatch") {
+      showToast("File changed outside Studio. Redo history was not applied.", "info");
+      return;
+    }
+    if (result.ok && result.label) {
+      clearDomSelectionRef.current();
+      await syncHistoryPreviewAfterApply(result.paths);
+      showToast(`Redid ${result.label}`, "info");
+    }
+  }, [
+    clearDomSelectionRef,
+    editHistory,
+    readHistoryProjectFile,
+    showToast,
+    syncHistoryPreviewAfterApply,
+    waitForPendingDomEditSaves,
+    writeHistoryProjectFile,
+  ]);
+
+  // ── Stable refs for the consolidated keydown handler ──
+
+  const handleToggleRef = useRef(handleTimelineToggleHotkey);
+  handleToggleRef.current = handleTimelineToggleHotkey;
+  const handleDeleteRef = useRef(handleTimelineElementDelete);
+  handleDeleteRef.current = handleTimelineElementDelete;
+  const handleDomEditDeleteRef = useRef(handleDomEditElementDelete);
+  handleDomEditDeleteRef.current = handleDomEditElementDelete;
+  const handleUndoRef = useRef(handleUndo);
+  handleUndoRef.current = handleUndo;
+  const handleRedoRef = useRef(handleRedo);
+  handleRedoRef.current = handleRedo;
+
+  // ── Consolidated keydown handler ──
+
+  handleAppKeyDownRef.current = (event: KeyboardEvent) => {
+    // Shift+T — toggle timeline
+    handleToggleRef.current(event);
+
+    // Cmd/Ctrl+Z — undo, Cmd/Ctrl+Shift+Z or Ctrl+Y — redo
+    if (event.metaKey || event.ctrlKey) {
+      if (!shouldIgnoreHistoryShortcut(event.target)) {
+        const key = event.key.toLowerCase();
+        if (key === "z" && !event.shiftKey) {
+          event.preventDefault();
+          void handleUndoRef.current();
+          return;
+        }
+        if ((key === "z" && event.shiftKey) || (event.ctrlKey && !event.metaKey && key === "y")) {
+          event.preventDefault();
+          void handleRedoRef.current();
+          return;
+        }
+      }
+
+      // Cmd/Ctrl+1 — sidebar: Compositions tab
+      if (event.key === "1") {
+        event.preventDefault();
+        leftSidebarRef.current?.selectTab("compositions");
+        return;
+      }
+
+      // Cmd/Ctrl+2 — sidebar: Assets tab
+      if (event.key === "2") {
+        event.preventDefault();
+        leftSidebarRef.current?.selectTab("assets");
+        return;
+      }
+    }
+
+    // Delete / Backspace — remove selected element (timeline clip or preview selection)
+    if (
+      (event.key === "Delete" || event.key === "Backspace") &&
+      !event.metaKey &&
+      !event.ctrlKey &&
+      !event.altKey &&
+      !isEditableTarget(event.target)
+    ) {
+      const { selectedElementId, elements } = usePlayerStore.getState();
+      if (selectedElementId) {
+        const element = elements.find((el) => (el.key ?? el.id) === selectedElementId);
+        if (element) {
+          event.preventDefault();
+          void handleDeleteRef.current(element);
+          return;
+        }
+      }
+      const domSelection = domEditSelectionRef.current;
+      if (domSelection) {
+        event.preventDefault();
+        void handleDomEditDeleteRef.current(domSelection);
+      }
+    }
+  };
+
+  // ── Window keydown listener ──
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    function handleAppKeyDown(event: KeyboardEvent) {
+      handleAppKeyDownRef.current?.(event);
+    }
+    window.addEventListener("keydown", handleAppKeyDown, true);
+    return () => window.removeEventListener("keydown", handleAppKeyDown, true);
+  }, []);
+
+  // ── Preview iframe keydown forwarding ──
+
+  const previewAppKeyDownHandler = useCallback((event: KeyboardEvent) => {
+    handleAppKeyDownRef.current?.(event);
+  }, []);
+
+  const syncPreviewTimelineHotkey = useCallback(
+    (iframe: HTMLIFrameElement | null) => {
+      const nextWindow = iframe?.contentWindow ?? null;
+      if (previewHotkeyWindowRef.current === nextWindow) return;
+      if (previewHotkeyWindowRef.current) {
+        previewHotkeyWindowRef.current.removeEventListener("keydown", previewAppKeyDownHandler);
+      }
+      previewHotkeyWindowRef.current = nextWindow;
+      nextWindow?.addEventListener("keydown", previewAppKeyDownHandler, true);
+    },
+    [previewAppKeyDownHandler],
+  );
+
+  useEffect(
+    () => () => {
+      if (previewHotkeyWindowRef.current) {
+        previewHotkeyWindowRef.current.removeEventListener("keydown", previewAppKeyDownHandler);
+        previewHotkeyWindowRef.current = null;
+      }
+    },
+    [previewAppKeyDownHandler],
+  );
+
+  // ── History hotkey for iframe forwarding ──
+
+  const handleHistoryHotkey = useCallback((event: KeyboardEvent) => {
+    if (!(event.metaKey || event.ctrlKey)) return;
+    if (shouldIgnoreHistoryShortcut(event.target)) return;
+    const key = event.key.toLowerCase();
+    if (key === "z" && !event.shiftKey) {
+      event.preventDefault();
+      void handleUndoRef.current();
+      return;
+    }
+    if ((key === "z" && event.shiftKey) || (event.ctrlKey && !event.metaKey && key === "y")) {
+      event.preventDefault();
+      void handleRedoRef.current();
+    }
+  }, []);
+
+  const syncPreviewHistoryHotkey = useCallback(
+    (iframe: HTMLIFrameElement | null) => {
+      previewHistoryHotkeyCleanupRef.current?.();
+      previewHistoryHotkeyCleanupRef.current = null;
+
+      const win = iframe?.contentWindow ?? null;
+      let doc: Document | null = null;
+      try {
+        doc = iframe?.contentDocument ?? null;
+      } catch {
+        doc = null;
+      }
+      if (!win && !doc) return;
+
+      win?.addEventListener("keydown", handleHistoryHotkey, true);
+      doc?.addEventListener("keydown", handleHistoryHotkey, true);
+      previewHistoryHotkeyCleanupRef.current = () => {
+        win?.removeEventListener("keydown", handleHistoryHotkey, true);
+        doc?.removeEventListener("keydown", handleHistoryHotkey, true);
+      };
+    },
+    [handleHistoryHotkey],
+  );
+
+  useEffect(
+    () => () => {
+      previewHistoryHotkeyCleanupRef.current?.();
+      previewHistoryHotkeyCleanupRef.current = null;
+    },
+    [],
+  );
+
+  return {
+    handleUndo,
+    handleRedo,
+    syncPreviewTimelineHotkey,
+    syncPreviewHistoryHotkey,
+    handleTimelineToggleHotkey,
+  };
+}

package/src/hooks/useAskAgentModal.ts

@@ -0,0 +1,162 @@
+import { useState, useCallback, useRef, useEffect } from "react";
+import { copyTextToClipboard } from "../utils/clipboard";
+import { readTagSnippetByTarget } from "../utils/sourcePatcher";
+import { toProjectAbsolutePath, type AgentModalAnchorPoint } from "../utils/studioHelpers";
+import { buildElementAgentPrompt, type DomEditSelection } from "../components/editor/domEditing";
+
+// ── Types ──
+
+export interface UseAskAgentModalParams {
+  projectId: string | null;
+  activeCompPath: string | null;
+  projectDir: string | null;
+  projectIdRef: React.MutableRefObject<string | null>;
+  currentTime: number;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
+  domEditSelection: DomEditSelection | null;
+}
+
+// ── Hook ──
+
+export function useAskAgentModal({
+  activeCompPath,
+  projectDir,
+  projectIdRef,
+  currentTime,
+  showToast,
+  domEditSelectionRef,
+  domEditSelection,
+}: UseAskAgentModalParams) {
+  // ── State ──
+
+  const [agentPromptTagSnippet, setAgentPromptTagSnippet] = useState<string | undefined>();
+  const [agentPromptSelectionContext, setAgentPromptSelectionContext] = useState<
+    string | undefined
+  >();
+  const [agentModalAnchorPoint, setAgentModalAnchorPoint] = useState<AgentModalAnchorPoint | null>(
+    null,
+  );
+  const [copiedAgentPrompt, setCopiedAgentPrompt] = useState(false);
+  const [agentModalOpen, setAgentModalOpen] = useState(false);
+
+  // ── Refs ──
+
+  const copiedAgentTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // ── Callbacks ──
+
+  const preloadAgentPromptSnippet = useCallback(
+    async (selection: DomEditSelection) => {
+      const pid = projectIdRef.current;
+      if (!pid) return;
+
+      const targetPath = selection.sourceFile || activeCompPath || "index.html";
+      try {
+        const response = await fetch(
+          `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
+        );
+        if (!response.ok) return;
+
+        const data = (await response.json()) as { content?: string };
+        const html = data.content;
+        const tagSnippet =
+          typeof html === "string" ? readTagSnippetByTarget(html, selection) : undefined;
+
+        setAgentPromptTagSnippet((current) => {
+          if (domEditSelectionRef.current !== selection) return current;
+          return tagSnippet;
+        });
+      } catch {
+        // Runtime outerHTML is still available as a synchronous copy fallback.
+      }
+    },
+    [activeCompPath, domEditSelectionRef, projectIdRef],
+  );
+
+  const handleAskAgent = useCallback(() => {
+    if (!domEditSelection) return;
+    setAgentPromptTagSnippet(undefined);
+    setAgentPromptSelectionContext(undefined);
+    setAgentModalAnchorPoint(null);
+    void preloadAgentPromptSnippet(domEditSelection);
+    setAgentModalOpen(true);
+  }, [domEditSelection, preloadAgentPromptSnippet]);
+
+  const handleAgentModalSubmit = useCallback(
+    async (userInstruction: string) => {
+      if (!domEditSelection) return;
+
+      const targetPath = domEditSelection.sourceFile || activeCompPath || "index.html";
+      const tagSnippet = agentPromptTagSnippet ?? domEditSelection.element.outerHTML;
+      const prompt = buildElementAgentPrompt({
+        selection: domEditSelection,
+        currentTime,
+        tagSnippet,
+        selectionContext: agentPromptSelectionContext,
+        userInstruction,
+        sourceFilePath: toProjectAbsolutePath(projectDir, targetPath),
+      });
+
+      const copied = await copyTextToClipboard(prompt);
+      if (!copied) {
+        showToast("Could not copy prompt to clipboard.", "error");
+        return;
+      }
+
+      setAgentModalOpen(false);
+      setAgentPromptSelectionContext(undefined);
+      setAgentModalAnchorPoint(null);
+      if (copiedAgentTimerRef.current) clearTimeout(copiedAgentTimerRef.current);
+      setCopiedAgentPrompt(true);
+      copiedAgentTimerRef.current = setTimeout(() => setCopiedAgentPrompt(false), 1600);
+    },
+    [
+      activeCompPath,
+      agentPromptSelectionContext,
+      agentPromptTagSnippet,
+      currentTime,
+      domEditSelection,
+      projectDir,
+      showToast,
+    ],
+  );
+
+  // ── Effects ──
+
+  // Clear agent-prompt state when selection changes
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    setAgentPromptTagSnippet(undefined);
+    setAgentPromptSelectionContext(undefined);
+    setAgentModalAnchorPoint(null);
+    setCopiedAgentPrompt(false);
+  }, [domEditSelection]);
+
+  // Cleanup copiedAgentTimerRef
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(
+    () => () => {
+      if (copiedAgentTimerRef.current) clearTimeout(copiedAgentTimerRef.current);
+    },
+    [],
+  );
+
+  return {
+    // State
+    agentModalOpen,
+    agentModalAnchorPoint,
+    copiedAgentPrompt,
+    agentPromptSelectionContext,
+
+    // Setters (consumed by handlePreviewCanvasMouseDown and other callers)
+    setAgentModalOpen,
+    setAgentPromptSelectionContext,
+    setAgentModalAnchorPoint,
+
+    // Callbacks
+    preloadAgentPromptSnippet,
+    handleAskAgent,
+    handleAgentModalSubmit,
+  };
+}