@hyperframes/studio 0.8.46 → 0.8.48

package/src/hooks/useAppHotkeys.ts

@@ -1,21 +1,23 @@
 import { useCallback, useEffect, useRef } from "react";
-import { automationOwnsKey } from "./useAutomationSelectionKeyboard";
 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_MOTION_PATH } from "../components/editor/studioMotion";
 import { isTypingTarget } from "../utils/typingTarget";
-import { isEditableTarget } from "../utils/timelineDiscovery";
 import { useCaptionStore } from "../captions/store";
 import {
   applyCaptionModelToIframe,
   isCaptionPreviewVisible,
 } from "../captions/components/CaptionOverlayUtils";
 import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
-import { canSplitElement } from "../utils/timelineElementSplit";
-import { trackStudioEvent } from "../utils/studioTelemetry";
 import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
+import {
+  type HotkeyCallbacks,
+  dispatchModifierKey,
+  dispatchPlainKey,
+  handleUndoRedoKey,
+} from "./appHotkeysDispatch";
 
 function iframeContentWindow(iframe: HTMLIFrameElement | null): Window | null {
   try {
@@ -40,22 +42,6 @@ function safeRemoveListener(t: EventTarget | null, type: string, h: EventListene
   }
 }
 
-// fallow-ignore-next-line complexity
-function handleUndoRedoKey(event: KeyboardEvent, onUndo: () => void, onRedo: () => void): boolean {
-  const key = event.key.toLowerCase();
-  if (key === "z" && !event.shiftKey) {
-    event.preventDefault();
-    onUndo();
-    return true;
-  }
-  if ((key === "z" && event.shiftKey) || (event.ctrlKey && !event.metaKey && key === "y")) {
-    event.preventDefault();
-    onRedo();
-    return true;
-  }
-  return false;
-}
-
 // Beat edits live in an in-memory stack interleaved with file history by
 // timestamp. Undo steps to the NEWER op (beatAt >= fileAt); redo replays the
 // inverse, stepping to the OLDER op (beatAt <= fileAt). Returns true when it
@@ -146,225 +132,6 @@ interface UseAppHotkeysParams {
   forceReloadSdkSession?: () => void;
 }
 
-// ── Extracted keydown dispatch (pure function, no hooks) ──
-
-interface HotkeyCallbacks {
-  handleTimelineElementsDelete: (elements: TimelineElement[]) => Promise<void>;
-  handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void>;
-  handleDomEditElementDelete: (
-    selection: DomEditSelection,
-    options?: { expandGroup?: boolean },
-  ) => Promise<void>;
-  handleUndo: () => Promise<void>;
-  handleRedo: () => Promise<void>;
-  handleCopy: () => boolean;
-  handlePaste: () => Promise<void>;
-  handleCut: () => Promise<boolean>;
-  onResetKeyframes: () => boolean;
-  onDeleteSelectedKeyframes: () => void;
-  onToggleRecording?: () => void;
-  onGroupSelection?: () => void;
-  onUngroupSelection?: () => void;
-  leftSidebarRef: React.RefObject<LeftSidebarHandle | null>;
-  domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
-  showToast: (message: string, tone?: "error" | "info") => void;
-}
-
-/** Exported for tests, like dispatchPlainKey below: lets the Cmd+C/Cmd+V
- *  arbitration between an automation range and the clip clipboard be asserted
- *  without standing up the whole hook. */
-export function dispatchModifierKey(
-  event: KeyboardEvent,
-  key: string,
-  cb: HotkeyCallbacks,
-): boolean {
-  if (
-    !shouldIgnoreHistoryShortcut(event.target) &&
-    handleUndoRedoKey(
-      event,
-      () => {
-        trackStudioEvent("keyboard_shortcut", { action: "undo" });
-        void cb.handleUndo();
-      },
-      () => {
-        trackStudioEvent("keyboard_shortcut", { action: "redo" });
-        void cb.handleRedo();
-      },
-    )
-  )
-    return true;
-
-  if (event.key === "1") {
-    event.preventDefault();
-    trackStudioEvent("keyboard_shortcut", { action: "tab_compositions" });
-    cb.leftSidebarRef.current?.selectTab("compositions");
-    return true;
-  }
-  if (event.key === "2") {
-    event.preventDefault();
-    trackStudioEvent("keyboard_shortcut", { action: "tab_assets" });
-    cb.leftSidebarRef.current?.selectTab("assets");
-    return true;
-  }
-
-  if (key === "g" && !event.altKey && !isTypingTarget(event.target)) {
-    event.preventDefault();
-    if (event.shiftKey) cb.onUngroupSelection?.();
-    else cb.onGroupSelection?.();
-    return true;
-  }
-
-  if (!event.shiftKey && !event.altKey && !isEditableTarget(event.target)) {
-    // An active automation range owns Cmd+C/Cmd+V, the same way it owns Delete
-    // below. This listener is on window/capture and runs before
-    // useAutomationSelectionKeyboard's document/capture handler, so without
-    // this the clip clipboard also claimed the key: Cmd+V duplicated the clip
-    // while the automation paste wrote the same file, and Cmd+C armed both
-    // clipboards and toasted "Copied clip". Return without preventDefault so
-    // the downstream handler still sees the key.
-    if (automationOwnsKey(event)) return true;
-    if (key === "c") {
-      if (cb.handleCopy()) {
-        event.preventDefault();
-        trackStudioEvent("keyboard_shortcut", { action: "copy" });
-      }
-      return true;
-    }
-    if (key === "v") {
-      event.preventDefault();
-      trackStudioEvent("keyboard_shortcut", { action: "paste" });
-      void cb.handlePaste();
-      return true;
-    }
-    if (key === "x") {
-      if (usePlayerStore.getState().selectedElementId || cb.domEditSelectionRef.current) {
-        event.preventDefault();
-        trackStudioEvent("keyboard_shortcut", { action: "cut" });
-        void cb.handleCut();
-      }
-      return true;
-    }
-  }
-  return false;
-}
-
-// fallow-ignore-next-line complexity
-/** Exported for tests: the unmodified-key half of the dispatcher, so the
- *  Delete arbitration between keyframes, an automation range and the clip can
- *  be asserted without standing up the whole hook. */
-export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks): void {
-  if (key === "f" && !event.shiftKey && !event.altKey) {
-    event.preventDefault();
-    if (document.fullscreenElement) void document.exitFullscreen();
-    else
-      document.querySelector<HTMLElement>("[data-studio-fullscreen-target]")?.requestFullscreen();
-    return;
-  }
-
-  if (event.key === "s" && !event.altKey) {
-    // Reserve bare `s` for Split even when the current selection cannot split,
-    // so secondary listeners do not reinterpret the same key as Snap toggle.
-    event.preventDefault();
-    const { selectedElementId, elements, currentTime } = usePlayerStore.getState();
-    if (selectedElementId) {
-      const el = elements.find((e) => (e.key ?? e.id) === selectedElementId);
-      if (
-        el &&
-        canSplitElement(el) &&
-        currentTime > el.start &&
-        currentTime < el.start + el.duration
-      ) {
-        void cb.handleTimelineElementSplit(el, currentTime);
-        return;
-      }
-      // Expanded sub-comp children carry a qualified `sourceFile#id` selection
-      // that isn't in the raw `elements` list, so the s-key can't resolve them.
-      // Nudge toward the razor tool instead of failing silently.
-      if (!el && selectedElementId.includes("#")) {
-        cb.showToast("Use the razor tool (B) to split clips inside a sub-composition", "info");
-        return;
-      }
-    }
-  }
-
-  if (key === "b" && !event.shiftKey && !event.altKey) {
-    event.preventDefault();
-    const { activeTool, setActiveTool } = usePlayerStore.getState();
-    setActiveTool(activeTool === "razor" ? "select" : "razor");
-    return;
-  }
-
-  if (key === "v" && !event.shiftKey && !event.altKey) {
-    event.preventDefault();
-    usePlayerStore.getState().setActiveTool("select");
-    return;
-  }
-
-  if (event.key === "Escape") {
-    const { activeTool, selectedElementId, setActiveTool, setSelectedElementId } =
-      usePlayerStore.getState();
-    if (activeTool === "razor") {
-      if (selectedElementId) setSelectedElementId(null);
-      else setActiveTool("select");
-      event.preventDefault();
-      return;
-    }
-  }
-
-  if ((event.key === "Delete" || event.key === "Backspace") && !event.altKey) {
-    if (usePlayerStore.getState().selectedKeyframes.size > 0) {
-      cb.onDeleteSelectedKeyframes();
-      usePlayerStore.getState().clearSelectedKeyframes();
-      event.preventDefault();
-      return;
-    }
-    // An active automation range owns Delete: useAutomationSelectionKeyboard
-    // empties the range in place, pinning the anchors. Fall through WITHOUT
-    // preventDefault so that document-level handler still sees the key — this
-    // listener is on window/capture, so it runs first and everything below
-    // would otherwise win. Without this the press reaches the clip delete
-    // below and destroys the whole clip the lane belongs to.
-    if (usePlayerStore.getState().automationSelection) return;
-    if (event.key === "Backspace") {
-      const { selectedElementId, keyframeCache } = usePlayerStore.getState();
-      if (selectedElementId && keyframeCache.has(selectedElementId) && cb.onResetKeyframes()) {
-        event.preventDefault();
-        return;
-      }
-    }
-    // The canvas selection is what the user actually drew a marquee around, so
-    // it owns Delete whenever it holds something. The timeline mirror of that
-    // selection is derived and lossy — a member with no timeline row of its own
-    // is dropped from it — so deleting through the timeline removed the handful
-    // of clips it knew about and left every other selected element behind,
-    // still drawn as selected. The timeline path stays as the fallback for rows
-    // with no canvas node to select (audio, a comp that is not the active one).
-    const domSel = cb.domEditSelectionRef.current;
-    if (domSel) {
-      event.preventDefault();
-      // The whole marquee group, not just the primary the ref holds.
-      void cb.handleDomEditElementDelete(domSel, { expandGroup: true });
-      return;
-    }
-    // Takes the WHOLE selection: `find` returned the first match, so selecting
-    // every clip and pressing Delete removed exactly one of them.
-    const { selectedElementId, selectedElementIds, elements } = usePlayerStore.getState();
-    const selectionKeys = new Set(selectedElementIds);
-    if (selectedElementId) selectionKeys.add(selectedElementId);
-    const selected = elements.filter((e) => selectionKeys.has(e.key ?? e.id));
-    if (selected.length > 0) {
-      event.preventDefault();
-      void cb.handleTimelineElementsDelete(selected);
-    }
-    return;
-  }
-
-  if (event.key === "r" && !event.shiftKey && !event.altKey && cb.onToggleRecording) {
-    event.preventDefault();
-    cb.onToggleRecording();
-  }
-}
-
 // ── Hook ──
 
 export function useAppHotkeys({

package/src/hooks/useAutoOpenRootComposition.test.tsx

@@ -0,0 +1,151 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useAutoOpenRootComposition } from "./useAutoOpenRootComposition";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+type Props = {
+  projectId: string | null;
+  activeCompPath: string | null;
+  activeCompPathHydrated: boolean;
+  masterCompPath: string | null;
+  onSelectComposition: (comp: string) => void;
+};
+
+let root: Root | null = null;
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  root = null;
+  document.body.innerHTML = "";
+});
+
+function Harness(props: Props) {
+  useAutoOpenRootComposition(props);
+  return null;
+}
+
+function renderHarness(props: Props) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  let current = props;
+
+  act(() => {
+    root?.render(<Harness {...current} />);
+  });
+
+  return {
+    rerender: (next: Partial<Props>) => {
+      current = { ...current, ...next };
+      act(() => {
+        root?.render(<Harness {...current} />);
+      });
+    },
+  };
+}
+
+describe("useAutoOpenRootComposition", () => {
+  it("opens the master composition once hydration settles on no selection", () => {
+    const onSelectComposition = vi.fn();
+    renderHarness({
+      projectId: "demo",
+      activeCompPath: null,
+      activeCompPathHydrated: true,
+      masterCompPath: "index.html",
+      onSelectComposition,
+    });
+
+    expect(onSelectComposition).toHaveBeenCalledExactlyOnceWith("index.html");
+  });
+
+  it("waits for the file tree before opening anything", () => {
+    const onSelectComposition = vi.fn();
+    const { rerender } = renderHarness({
+      projectId: "demo",
+      activeCompPath: null,
+      activeCompPathHydrated: true,
+      masterCompPath: null,
+      onSelectComposition,
+    });
+
+    expect(onSelectComposition).not.toHaveBeenCalled();
+
+    rerender({ masterCompPath: "index.html" });
+    expect(onSelectComposition).toHaveBeenCalledExactlyOnceWith("index.html");
+  });
+
+  it("never auto-opens once a URL-hydrated selection is already active", () => {
+    const onSelectComposition = vi.fn();
+    renderHarness({
+      projectId: "demo",
+      activeCompPath: "hero.html",
+      activeCompPathHydrated: true,
+      masterCompPath: "index.html",
+      onSelectComposition,
+    });
+
+    expect(onSelectComposition).not.toHaveBeenCalled();
+  });
+
+  it("does not auto-open before hydration has settled", () => {
+    const onSelectComposition = vi.fn();
+    const { rerender } = renderHarness({
+      projectId: "demo",
+      activeCompPath: null,
+      activeCompPathHydrated: false,
+      masterCompPath: "index.html",
+      onSelectComposition,
+    });
+
+    expect(onSelectComposition).not.toHaveBeenCalled();
+
+    rerender({ activeCompPathHydrated: true });
+    expect(onSelectComposition).toHaveBeenCalledExactlyOnceWith("index.html");
+  });
+
+  it("fires only once even if the selection is cleared back to null later", () => {
+    const onSelectComposition = vi.fn();
+    const { rerender } = renderHarness({
+      projectId: "demo",
+      activeCompPath: null,
+      activeCompPathHydrated: true,
+      masterCompPath: "index.html",
+      onSelectComposition,
+    });
+    expect(onSelectComposition).toHaveBeenCalledTimes(1);
+
+    rerender({ activeCompPath: "index.html" });
+    rerender({ activeCompPath: null });
+    expect(onSelectComposition).toHaveBeenCalledTimes(1);
+  });
+
+  it("auto-opens again for a different project after already settling for the first one", () => {
+    const onSelectComposition = vi.fn();
+    const { rerender } = renderHarness({
+      projectId: "project-a",
+      activeCompPath: null,
+      activeCompPathHydrated: true,
+      masterCompPath: "index.html",
+      onSelectComposition,
+    });
+    expect(onSelectComposition).toHaveBeenCalledExactlyOnceWith("index.html");
+
+    // This hook's OWN decision logic, given activeCompPath/masterCompPath already reset for
+    // the new project (by whatever reset the caller wires up — see
+    // useResetSelectionOnProjectSwitch.test.tsx for that end-to-end case with real state).
+    rerender({
+      projectId: "project-b",
+      activeCompPath: null,
+      masterCompPath: null,
+    });
+    expect(onSelectComposition).toHaveBeenCalledTimes(1);
+
+    rerender({ masterCompPath: "hero.html" });
+    expect(onSelectComposition).toHaveBeenCalledTimes(2);
+    expect(onSelectComposition).toHaveBeenLastCalledWith("hero.html");
+  });
+});

package/src/hooks/useAutoOpenRootComposition.ts

@@ -0,0 +1,33 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * Opens the root composition once hydration settles with no selection, at most once per `projectId`.
+ * Caller must call `useResetSelectionOnProjectSwitch` on a project switch, or a stale selection reads as open.
+ */
+export function useAutoOpenRootComposition({
+  projectId,
+  activeCompPath,
+  activeCompPathHydrated,
+  masterCompPath,
+  onSelectComposition,
+}: {
+  projectId: string | null;
+  activeCompPath: string | null;
+  activeCompPathHydrated: boolean;
+  masterCompPath: string | null;
+  onSelectComposition: (comp: string) => void;
+}): void {
+  const settledForProjectRef = useRef<string | null | undefined>(undefined);
+
+  useEffect(() => {
+    if (settledForProjectRef.current === projectId) return;
+    if (!activeCompPathHydrated) return;
+    if (activeCompPath !== null) {
+      settledForProjectRef.current = projectId; // a URL-hydrated selection is already open
+      return;
+    }
+    if (!masterCompPath) return; // file tree not loaded yet, or no composition at all
+    settledForProjectRef.current = projectId;
+    onSelectComposition(masterCompPath);
+  }, [projectId, activeCompPath, activeCompPathHydrated, masterCompPath, onSelectComposition]);
+}

package/src/hooks/useDomEditCommits.ts

@@ -456,20 +456,19 @@ export function useDomEditCommits({
 
   // ── Element lifecycle (delete, z-index reorder) ──
 
-  const { handleDomEditElementDelete, handleDomEditElementsDelete, handleDomZIndexReorderCommit } =
-    useElementLifecycleOps({
-      activeCompPath,
-      showToast,
-      writeProjectFile,
-      editHistory,
-      projectIdRef,
-      reloadPreview,
-      clearDomSelection,
-      onTrySdkDelete,
-      onReorderShadow,
-      forceReloadSdkSession,
-      commitDomEditPatchBatches,
-    });
+  const { handleDomEditElementsDelete, handleDomZIndexReorderCommit } = useElementLifecycleOps({
+    activeCompPath,
+    showToast,
+    writeProjectFile,
+    editHistory,
+    projectIdRef,
+    reloadPreview,
+    clearDomSelection,
+    onTrySdkDelete,
+    onReorderShadow,
+    forceReloadSdkSession,
+    commitDomEditPatchBatches,
+  });
 
   return {
     resolveImportedFontAsset,
@@ -491,7 +490,6 @@ export function useDomEditCommits({
     handleDomBoxSizeCommit,
     handleDomRotationCommit,
     handleDomManualEditsReset,
-    handleDomEditElementDelete,
     handleDomEditElementsDelete,
     handleDomZIndexReorderCommit,
   };

package/src/hooks/useDomEditSession.test.tsx

@@ -6,6 +6,7 @@ import { shouldUseSdkCutover } from "../utils/sdkCutover";
 import type { PatchOperation } from "../utils/sourcePatcher";
 import type { Composition } from "@hyperframes/sdk";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import type { TimelineElement } from "../player";
 import type { UseDomEditSessionParams } from "./useDomEditSession";
 
 const styleOp = (property: string, value: string): PatchOperation => ({
@@ -97,6 +98,7 @@ function createSessionParams(
     syncPreviewHotkeys: vi.fn(),
     reloadPreview: vi.fn(),
     setRefreshKey: vi.fn(),
+    handleTimelineElementsDelete: vi.fn(),
     ...overrides,
   };
 }
@@ -105,6 +107,7 @@ vi.mock("../utils/sdkResolverShadow", () => ({
   runResolverShadow: vi.fn(),
   recordResolverParity: (...args: unknown[]) => recordResolverParity(...args),
 }));
+const handleDomEditElementsDeleteMock = vi.fn(async () => ({ ok: true }) as const);
 vi.mock("./useDomEditCommits", () => ({
   useDomEditCommits: (params: { onReorderShadow?: (targets: string[]) => void }) => {
     capturedOnReorderShadow.fn = params.onReorderShadow;
@@ -120,7 +123,7 @@ vi.mock("./useDomEditCommits", () => ({
       handleDomRemoveTextField: vi.fn(),
       handleDomBoxSizeCommit: vi.fn(),
       handleDomManualEditsReset: vi.fn(),
-      handleDomEditElementDelete: vi.fn(),
+      handleDomEditElementsDelete: handleDomEditElementsDeleteMock,
       handleDomZIndexReorderCommit: vi.fn(),
     };
   },
@@ -461,3 +464,89 @@ describe("handleGroupSelection with audio in the selection", () => {
     expect(groupSelectionSpy).toHaveBeenCalledTimes(1);
   });
 });
+
+// ── Delete routing: a timeline row goes through the timeline's own delete op ──
+
+describe("handleDomEditElementDelete routing", () => {
+  const domSel = (id: string): DomEditSelection =>
+    ({
+      id,
+      element: document.createElement("div"),
+      sourceFile: "index.html",
+    }) as unknown as DomEditSelection;
+
+  async function deleteViaSession(
+    selection: DomEditSelection,
+    timelineElements: TimelineElement[],
+    options?: { expandGroup?: boolean; group?: DomEditSelection[] },
+  ) {
+    const { useDomEditSession } = await import("./useDomEditSession");
+    handleDomEditElementsDeleteMock.mockClear();
+    domEditGroupSelectionsRef.current = options?.group ?? [];
+    const handleTimelineElementsDelete = vi.fn(async () => {});
+    const captured: {
+      fn?: (selection: DomEditSelection, options?: { expandGroup?: boolean }) => Promise<void>;
+    } = {};
+    function Probe() {
+      captured.fn = useDomEditSession(
+        createSessionParams({ timelineElements, handleTimelineElementsDelete }),
+      ).handleDomEditElementDelete;
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(<Probe />));
+    await act(async () => captured.fn?.(selection, { expandGroup: options?.expandGroup }));
+    act(() => root.unmount());
+    domEditGroupSelectionsRef.current = [];
+    return { handleTimelineElementsDelete };
+  }
+
+  it("hands a selection that IS a timeline row to the timeline delete op, not the REST path", async () => {
+    const clip = {
+      id: "clip-a",
+      domId: "clip-a",
+      sourceFile: "index.html",
+      tag: "video",
+      start: 0,
+      duration: 2,
+      track: 0,
+    } as TimelineElement;
+    const { handleTimelineElementsDelete } = await deleteViaSession(domSel("clip-a"), [clip]);
+    expect(handleTimelineElementsDelete).toHaveBeenCalledWith([clip]);
+    expect(handleDomEditElementsDeleteMock).not.toHaveBeenCalled();
+  });
+
+  it("falls through to the REST path for a selection with no timeline row of its own", async () => {
+    const { handleTimelineElementsDelete } = await deleteViaSession(domSel("nested-child"), []);
+    expect(handleTimelineElementsDelete).not.toHaveBeenCalled();
+    expect(handleDomEditElementsDeleteMock).toHaveBeenCalledWith([domSel("nested-child")]);
+  });
+
+  it("expands a multi-member marquee group to the timeline op when every member resolves", async () => {
+    const clipA = {
+      id: "clip-a",
+      domId: "clip-a",
+      sourceFile: "index.html",
+      tag: "video",
+      start: 0,
+      duration: 2,
+      track: 0,
+    } as TimelineElement;
+    const clipB = {
+      id: "clip-b",
+      domId: "clip-b",
+      sourceFile: "index.html",
+      tag: "video",
+      start: 2,
+      duration: 2,
+      track: 0,
+    } as TimelineElement;
+    const group = [domSel("clip-a"), domSel("clip-b")];
+    const { handleTimelineElementsDelete } = await deleteViaSession(group[0], [clipA, clipB], {
+      expandGroup: true,
+      group,
+    });
+    expect(handleTimelineElementsDelete).toHaveBeenCalledWith([clipA, clipB]);
+    expect(handleDomEditElementsDeleteMock).not.toHaveBeenCalled();
+  });
+});