@hyperframes/studio 0.7.60 → 0.7.62

package/src/hooks/useRazorSplit.ts

@@ -1,15 +1,10 @@
 import { useCallback, useRef } from "react";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
-import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
-import { getTimelineElementLabel, collectHtmlIds } from "../utils/studioHelpers";
+import { getTimelineElementLabel } from "../utils/studioHelpers";
 import { trackStudioRazorSplit } from "../telemetry/events";
-import {
-  canSplitElementAt,
-  selectSplittableElements,
-  buildPatchTarget,
-  readFileContent,
-} from "../utils/timelineElementSplit";
+import { canSplitElementAt, selectSplittableElements } from "../utils/timelineElementSplit";
+import { buildAtomicCutIntents, runAtomicCutTransaction } from "../utils/razorSplitTransaction";
 import type { RecordEditInput } from "./timelineEditingHelpers";
 
 interface UseRazorSplitOptions {
@@ -21,246 +16,10 @@ interface UseRazorSplitOptions {
   recordEdit: (input: RecordEditInput) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   reloadPreview: () => void;
-  /**
-   * Resync the in-memory SDK session after the server-side split write (the
-   * split-element / split-gsap endpoints write the file directly, so the SDK's
-   * linkedom doc is now stale). This reload is read-only; the split endpoint owns
-   * the final on-disk bytes and history baseline. Every other server-side-write
-   * timeline path (move / resize / delete / drop / visibility) also resyncs.
-   */
   forceReloadSdkSession?: () => void;
   isRecordingRef?: React.RefObject<boolean>;
 }
 
-function generateSplitId(existingIds: string[], baseId: string): string {
-  let newId = `${baseId}-split`;
-  let suffix = 2;
-  while (existingIds.includes(newId)) {
-    newId = `${baseId}-split-${suffix++}`;
-  }
-  return newId;
-}
-
-async function splitHtmlElement(
-  projectId: string,
-  targetPath: string,
-  patchTarget: NonNullable<ReturnType<typeof buildPatchTarget>>,
-  splitTime: number,
-  newId: string,
-  elementStart: number,
-  elementDuration: number,
-): Promise<{ ok: boolean; changed?: boolean; content?: string; version: string }> {
-  const response = await fetch(
-    `/api/projects/${projectId}/file-mutations/split-element/${encodeURIComponent(targetPath)}`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        target: patchTarget,
-        splitTime,
-        newId,
-        elementStart,
-        elementDuration,
-      }),
-    },
-  );
-  if (!response.ok) throw new Error("Split request failed");
-  const data = (await response.json()) as {
-    ok: boolean;
-    changed?: boolean;
-    content?: string;
-    version?: string;
-  };
-  const version = data.version ?? response.headers.get("etag");
-  if (!version) throw new Error("Split response did not include a content version");
-  return { ...data, version };
-}
-
-// fallow-ignore-next-line complexity
-async function splitGsapAnimations(
-  projectId: string,
-  targetPath: string,
-  originalId: string,
-  newId: string,
-  splitTime: number,
-  elementStart: number,
-  elementDuration: number,
-): Promise<{ content: string | null; version?: string; skippedSelectors?: string[] }> {
-  const response = await fetch(
-    `/api/projects/${projectId}/gsap-mutations/${encodeURIComponent(targetPath)}`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        type: "split-animations",
-        originalId,
-        newId,
-        splitTime,
-        elementStart,
-        elementDuration,
-      }),
-    },
-  );
-  if (!response.ok) {
-    const errorBody = (await response.json().catch(() => null)) as { error?: string } | null;
-    if (errorBody?.error === "no GSAP script found in file") {
-      return { content: null };
-    }
-    throw new Error(errorBody?.error ?? `GSAP animation split failed (${response.status})`);
-  }
-  const data = (await response.json()) as {
-    ok?: boolean;
-    after?: string;
-    version?: string;
-    skippedSelectors?: string[];
-  };
-  return {
-    content: data.ok && data.after ? data.after : null,
-    version: data.version ?? response.headers.get("etag") ?? undefined,
-    skippedSelectors: data.skippedSelectors,
-  };
-}
-
-function getOriginalContent(originals: ReadonlyMap<string, string>, path: string): string {
-  const original = originals.get(path);
-  if (original === undefined) {
-    throw new Error(`Missing original contents for ${path}`);
-  }
-  return original;
-}
-
-async function restoreFilesToOriginal(
-  originals: ReadonlyMap<string, string>,
-  snapshots: ReadonlyMap<string, { before: string; after: string }>,
-  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
-): Promise<void> {
-  for (const [path, snapshot] of snapshots) {
-    await writeProjectFile(path, getOriginalContent(originals, path), snapshot.after);
-  }
-}
-
-async function readOriginalFiles(
-  pid: string,
-  elements: TimelineElement[],
-  activeCompPath: string | null,
-): Promise<Map<string, string>> {
-  const originals = new Map<string, string>();
-  for (const element of elements) {
-    const path = element.sourceFile || activeCompPath || "index.html";
-    if (!originals.has(path)) {
-      originals.set(path, await readFileContent(pid, path));
-    }
-  }
-  return originals;
-}
-
-async function splitElementsAtTime(
-  pid: string,
-  elements: TimelineElement[],
-  splitTime: number,
-  activeCompPath: string | null,
-  originals: ReadonlyMap<string, string>,
-  snapshots: Map<string, { before: string; after: string }>,
-  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
-  observeProjectFileVersion?: (path: string, version: string | null) => void,
-): Promise<number> {
-  let count = 0;
-  for (const element of elements) {
-    const result = await executeSplit(
-      pid,
-      element,
-      splitTime,
-      activeCompPath,
-      writeProjectFile,
-      observeProjectFileVersion,
-    );
-    if (!result.changed) continue;
-    snapshots.set(result.targetPath, {
-      before: getOriginalContent(originals, result.targetPath),
-      after: result.patchedContent,
-    });
-    await writeProjectFile(result.targetPath, result.patchedContent, result.patchedContent);
-    count++;
-  }
-  return count;
-}
-
-// fallow-ignore-next-line complexity
-async function executeSplit(
-  pid: string,
-  element: TimelineElement,
-  splitTime: number,
-  activeCompPath: string | null,
-  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
-  observeProjectFileVersion?: (path: string, version: string | null) => void,
-): Promise<{
-  targetPath: string;
-  originalContent: string;
-  patchedContent: string;
-  changed: boolean;
-  skippedSelectors?: string[];
-}> {
-  const patchTarget = buildPatchTarget(element);
-  if (!patchTarget) throw new Error("Clip is missing a patchable target.");
-
-  const targetPath = element.sourceFile || activeCompPath || "index.html";
-  const originalContent = await readFileContent(pid, targetPath);
-  const newId = generateSplitId(collectHtmlIds(originalContent), element.domId || "clip");
-
-  // An expanded sub-comp child arrives in MASTER-timeline coordinates — both its
-  // `start` and the incoming `splitTime` are offset by the host's master start
-  // (expandedParentStart) — but its `sourceFile` is the sub-comp, whose clips are
-  // authored in LOCAL time. Rebase both onto local time before the server patches
-  // the file, exactly as TimelinePane.handleSplitElement does for non-razor edits.
-  // Root-level clips (no expandedParentStart) are already local, so pass through.
-  const basis = element.expandedParentStart;
-  const localSplitTime = basis === undefined ? splitTime : Math.max(0, splitTime - basis);
-  const localElementStart = basis === undefined ? element.start : element.start - basis;
-
-  const splitResult = await splitHtmlElement(
-    pid,
-    targetPath,
-    patchTarget,
-    localSplitTime,
-    newId,
-    localElementStart,
-    element.duration,
-  );
-  if (!splitResult.ok) throw new Error("Failed to split clip.");
-  if (!splitResult.changed) {
-    return { targetPath, originalContent, patchedContent: originalContent, changed: false };
-  }
-  observeProjectFileVersion?.(targetPath, splitResult.version);
-
-  let patchedContent =
-    typeof splitResult.content === "string" ? splitResult.content : originalContent;
-
-  let skippedSelectors: string[] | undefined;
-  if (element.domId) {
-    try {
-      const gsapResult = await splitGsapAnimations(
-        pid,
-        targetPath,
-        element.domId,
-        newId,
-        localSplitTime,
-        localElementStart,
-        element.duration,
-      );
-      if (gsapResult.content) patchedContent = gsapResult.content;
-      if (gsapResult.version) observeProjectFileVersion?.(targetPath, gsapResult.version);
-      if (gsapResult.skippedSelectors?.length) skippedSelectors = gsapResult.skippedSelectors;
-    } catch (gsapError) {
-      // GSAP mutation failed — the HTML split already wrote to disk.
-      // Restore the original content to avoid a corrupt half-split state.
-      await writeProjectFile(targetPath, originalContent, patchedContent);
-      throw gsapError;
-    }
-  }
-
-  return { targetPath, originalContent, patchedContent, changed: true, skippedSelectors };
-}
-
 export function useRazorSplit({
   projectId,
   activeCompPath,
@@ -276,140 +35,109 @@ export function useRazorSplit({
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
 
+  const synchronize = useCallback(() => {
+    let failure: unknown;
+    try {
+      forceReloadSdkSession?.();
+    } catch (error) {
+      failure = error;
+    }
+    try {
+      reloadPreview();
+    } catch (error) {
+      failure ??= error;
+    }
+    if (failure) throw failure;
+  }, [forceReloadSdkSession, reloadPreview]);
+
+  const runCut = useCallback(
+    async (elements: readonly TimelineElement[], splitTime: number, mode: "single" | "all") => {
+      const pid = projectIdRef.current;
+      if (!pid || elements.length === 0) return;
+      const intents = buildAtomicCutIntents(elements, splitTime, activeCompPath);
+      const requestedCount = intents.reduce((count, file) => count + file.targets.length, 0);
+      const label =
+        mode === "single"
+          ? "Split timeline clip"
+          : `Split ${requestedCount} clips at ${splitTime.toFixed(2)}s`;
+
+      // Server writes arrive through the watcher before React can refresh. Keep
+      // the existing short self-write window active for this owned transaction.
+      domEditSaveTimestampRef.current = Date.now();
+      const result = await runAtomicCutTransaction({
+        projectId: pid,
+        intents,
+        label,
+        writeProjectFile,
+        recordEdit,
+        observeProjectFileVersion,
+        synchronize,
+      });
+      trackStudioRazorSplit({ mode, count: result.splitCount });
+      if (result.syncFailed) {
+        showToast(
+          "Cut was saved, but Studio could not refresh it. Reload the preview to resynchronize.",
+          "error",
+        );
+      }
+      if (result.skippedSelectors.length > 0) {
+        showToast(
+          `Some animations use non-ID selectors (${result.skippedSelectors.join(", ")}) and were not retargeted`,
+          "info",
+        );
+      }
+      return result;
+    },
+    [
+      activeCompPath,
+      domEditSaveTimestampRef,
+      observeProjectFileVersion,
+      recordEdit,
+      showToast,
+      synchronize,
+      writeProjectFile,
+    ],
+  );
+
   const handleRazorSplit = useCallback(
-    // fallow-ignore-next-line complexity
     async (element: TimelineElement, splitTime: number) => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");
         return;
       }
-
-      const pid = projectIdRef.current;
-      if (!pid || !canSplitElementAt(element, splitTime)) return;
-
+      if (!canSplitElementAt(element, splitTime)) return;
       try {
-        const { targetPath, originalContent, patchedContent, changed, skippedSelectors } =
-          await executeSplit(
-            pid,
-            element,
-            splitTime,
-            activeCompPath,
-            writeProjectFile,
-            observeProjectFileVersion,
-          );
-
-        if (!changed) {
-          showToast("Failed to split clip — playhead may be outside the clip", "error");
-          return;
-        }
-
-        domEditSaveTimestampRef.current = Date.now();
-        await saveProjectFilesWithHistory({
-          projectId: pid,
-          label: "Split timeline clip",
-          kind: "timeline",
-          files: { [targetPath]: patchedContent },
-          readFile: async () => originalContent,
-          writeFile: writeProjectFile,
-          recordEdit,
-        });
-
-        // Server writes bypass the SDK session, so reopen it before refreshing
-        // the preview. The split response already owns the final persisted bytes.
-        forceReloadSdkSession?.();
-        reloadPreview();
-        trackStudioRazorSplit({ mode: "single", count: 1 });
+        const result = await runCut([element], splitTime, "single");
+        if (!result) return;
+        if (result.syncFailed) return;
         showToast(`Split ${getTimelineElementLabel(element)} at ${splitTime.toFixed(2)}s`, "info");
-        if (skippedSelectors?.length) {
-          showToast(
-            `Some animations use non-ID selectors (${skippedSelectors.join(", ")}) and were not retargeted`,
-            "info",
-          );
-        }
       } catch (error) {
         const message = error instanceof Error ? error.message : "Failed to split timeline clip";
         showToast(message, "error");
       }
     },
-    [
-      activeCompPath,
-      recordEdit,
-      showToast,
-      writeProjectFile,
-      observeProjectFileVersion,
-      domEditSaveTimestampRef,
-      reloadPreview,
-      forceReloadSdkSession,
-      isRecordingRef,
-    ],
+    [isRecordingRef, runCut, showToast],
   );
 
   const handleRazorSplitAll = useCallback(
-    // fallow-ignore-next-line complexity
     async (splitTime: number) => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");
         return;
       }
-
-      const pid = projectIdRef.current;
-      if (!pid) return;
-      const { elements } = usePlayerStore.getState();
-      const splittable = selectSplittableElements(elements, splitTime);
+      const splittable = selectSplittableElements(usePlayerStore.getState().elements, splitTime);
       if (splittable.length === 0) return;
-
-      let originals = new Map<string, string>();
-      const finalSnapshots = new Map<string, { before: string; after: string }>();
       try {
-        originals = await readOriginalFiles(pid, splittable, activeCompPath);
-        const splitCount = await splitElementsAtTime(
-          pid,
-          splittable,
-          splitTime,
-          activeCompPath,
-          originals,
-          finalSnapshots,
-          writeProjectFile,
-          observeProjectFileVersion,
-        );
-        if (splitCount === 0) return;
-
-        domEditSaveTimestampRef.current = Date.now();
-        await recordEdit({
-          label: `Split ${splitCount} clips at ${splitTime.toFixed(2)}s`,
-          kind: "timeline",
-          files: Object.fromEntries(finalSnapshots),
-        });
-
-        // Resync the stale SDK doc after the batched server write (see the
-        // single-split path above for why this precedes the reload).
-        forceReloadSdkSession?.();
-        reloadPreview();
-        trackStudioRazorSplit({ mode: "all", count: splitCount });
-        showToast(`Split ${splitCount} clips at ${splitTime.toFixed(2)}s`, "info");
+        const result = await runCut(splittable, splitTime, "all");
+        if (!result) return;
+        if (result.syncFailed) return;
+        showToast(`Split ${result.splitCount} clips at ${splitTime.toFixed(2)}s`, "info");
       } catch (error) {
-        // Best-effort rollback — a failing restore write must not swallow the
-        // original error's toast, which is what tells the user the split failed.
-        try {
-          await restoreFilesToOriginal(originals, finalSnapshots, writeProjectFile);
-        } catch {
-          /* leave disk as-is; the original failure is reported below */
-        }
         const message = error instanceof Error ? error.message : "Failed to split clips";
         showToast(message, "error");
       }
     },
-    [
-      activeCompPath,
-      recordEdit,
-      showToast,
-      writeProjectFile,
-      observeProjectFileVersion,
-      domEditSaveTimestampRef,
-      reloadPreview,
-      forceReloadSdkSession,
-      isRecordingRef,
-    ],
+    [isRecordingRef, runCut, showToast],
   );
 
   return { handleRazorSplit, handleRazorSplitAll };

package/src/hooks/useSlideshowTabState.test.ts

@@ -0,0 +1,96 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { useSlideshowTabState } from "./useSlideshowTabState";
+import type { RightPanelTab } from "../utils/studioHelpers";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const SLIDESHOW_HTML = `<html><body><script type="application/hyperframes-slideshow+json">{"slides":[]}</script></body></html>`;
+const PLAIN_HTML = `<html><body><div id="title">hi</div></body></html>`;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+function renderHook(params: {
+  editingFileContent: string | null | undefined;
+  rightPanelTab: RightPanelTab;
+}) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const setRightPanelTabCalls: RightPanelTab[] = [];
+  let current: ReturnType<typeof useSlideshowTabState> | null = null;
+
+  function Harness() {
+    current = useSlideshowTabState({
+      editingFileContent: params.editingFileContent,
+      previewIframeRef: { current: null },
+      refreshKey: 0,
+      rightPanelTab: params.rightPanelTab,
+      setRightPanelTab: (tab) => setRightPanelTabCalls.push(tab),
+    });
+    return null;
+  }
+
+  act(() => {
+    root.render(React.createElement(Harness));
+  });
+
+  return {
+    getState: (): ReturnType<typeof useSlideshowTabState> => {
+      if (!current) throw new Error("useSlideshowTabState did not render");
+      return current;
+    },
+    setRightPanelTabCalls,
+    unmount: () => act(() => root.unmount()),
+  };
+}
+
+describe("useSlideshowTabState", () => {
+  it("detects a slideshow composition via the JSON island", () => {
+    const harness = renderHook({ editingFileContent: SLIDESHOW_HTML, rightPanelTab: "design" });
+    expect(harness.getState().isSlideshowComposition).toBe(true);
+    harness.unmount();
+  });
+
+  it("reports false for a plain (non-slideshow) composition", () => {
+    const harness = renderHook({ editingFileContent: PLAIN_HTML, rightPanelTab: "design" });
+    expect(harness.getState().isSlideshowComposition).toBe(false);
+    harness.unmount();
+  });
+
+  it("reports false when there is no editing file yet", () => {
+    const harness = renderHook({ editingFileContent: undefined, rightPanelTab: "design" });
+    expect(harness.getState().isSlideshowComposition).toBe(false);
+    harness.unmount();
+  });
+
+  it("still detects a malformed island — presence-only, not full manifest validation", () => {
+    const malformed = `<html><body><script type="application/hyperframes-slideshow+json">{not valid json</script></body></html>`;
+    const harness = renderHook({ editingFileContent: malformed, rightPanelTab: "design" });
+    expect(harness.getState().isSlideshowComposition).toBe(true);
+    harness.unmount();
+  });
+
+  it("bounces rightPanelTab off 'slideshow' to 'renders' on a non-slideshow composition", () => {
+    const harness = renderHook({ editingFileContent: PLAIN_HTML, rightPanelTab: "slideshow" });
+    expect(harness.setRightPanelTabCalls).toEqual(["renders"]);
+    harness.unmount();
+  });
+
+  it("does not bounce when the composition is a slideshow", () => {
+    const harness = renderHook({ editingFileContent: SLIDESHOW_HTML, rightPanelTab: "slideshow" });
+    expect(harness.setRightPanelTabCalls).toEqual([]);
+    harness.unmount();
+  });
+
+  it("does not bounce a tab other than 'slideshow'", () => {
+    const harness = renderHook({ editingFileContent: PLAIN_HTML, rightPanelTab: "renders" });
+    expect(harness.setRightPanelTabCalls).toEqual([]);
+    harness.unmount();
+  });
+});

package/src/hooks/useSlideshowTabState.ts

@@ -0,0 +1,61 @@
+import { useEffect, useMemo, type MutableRefObject } from "react";
+import { SLIDESHOW_ISLAND_TYPE, slideshowIslandRegex } from "@hyperframes/core/slideshow";
+import type { SceneInfo } from "../components/panels/SlideshowPanel";
+import type { IframeWindow } from "../player/lib/playbackTypes";
+import type { RightPanelTab } from "../utils/studioHelpers";
+
+/**
+ * Derives whether the currently-edited composition is a slideshow (carries
+ * the slideshow JSON island — the same definitive marker the CLI's `present`
+ * command requires; it refuses to run without one) and the live scene list
+ * for the Slideshow panel, and bounces `rightPanelTab` off "slideshow" the
+ * moment it stops applying (e.g. the user switches to a non-slideshow file
+ * while that tab was open) so the panel never shows a dangling active tab
+ * whose button is no longer even rendered.
+ *
+ * Extracted from StudioRightPanel to keep that file under the 600-LOC gate.
+ */
+export function useSlideshowTabState(params: {
+  editingFileContent: string | null | undefined;
+  previewIframeRef: MutableRefObject<HTMLIFrameElement | null>;
+  refreshKey: number;
+  rightPanelTab: RightPanelTab;
+  setRightPanelTab: (tab: RightPanelTab) => void;
+}): { isSlideshowComposition: boolean; slideshowScenes: SceneInfo[] } {
+  const { editingFileContent, previewIframeRef, refreshKey, rightPanelTab, setRightPanelTab } =
+    params;
+
+  // Presence-only (not full manifest validation): a malformed island should
+  // still surface the Slideshow tab so the user can see/fix it, rather than
+  // making the whole panel disappear. The plain substring check short-circuits
+  // the regex scan on every non-slideshow file (the common case) without
+  // paying for a full-content RegExp pass.
+  const isSlideshowComposition = useMemo(() => {
+    if (!editingFileContent || !editingFileContent.includes(SLIDESHOW_ISLAND_TYPE)) return false;
+    return slideshowIslandRegex("i").test(editingFileContent);
+  }, [editingFileContent]);
+
+  // Derive scene list from the live clip manifest in the preview iframe.
+  const slideshowScenes = useMemo<SceneInfo[]>(() => {
+    try {
+      const win = previewIframeRef.current?.contentWindow as IframeWindow | null;
+      return (win?.__clipManifest?.scenes ?? []).map((s) => ({
+        id: s.id,
+        label: s.label,
+        start: s.start,
+        duration: s.duration,
+      }));
+    } catch {
+      return [];
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [previewIframeRef, rightPanelTab, refreshKey]);
+
+  useEffect(() => {
+    if (rightPanelTab === "slideshow" && !isSlideshowComposition) {
+      setRightPanelTab("renders");
+    }
+  }, [rightPanelTab, isSlideshowComposition, setRightPanelTab]);
+
+  return { isSlideshowComposition, slideshowScenes };
+}

package/src/hooks/useTimelineAddAtPlayhead.ts

@@ -0,0 +1,15 @@
+import { useCallback } from "react";
+import { usePlayerStore } from "../player";
+
+type AddAtPlacement = (path: string, placement: { start: number; track: number }) => unknown;
+
+export function useTimelineAddAtPlayhead(addAsset: AddAtPlacement, addComposition: AddAtPlacement) {
+  const placement = () => ({ start: usePlayerStore.getState().currentTime, track: 0 });
+  return {
+    addAssetAtPlayhead: useCallback((path: string) => addAsset(path, placement()), [addAsset]),
+    addCompositionAtPlayhead: useCallback(
+      (path: string) => addComposition(path, placement()),
+      [addComposition],
+    ),
+  };
+}