@hyperframes/studio 0.7.54 → 0.7.56

package/src/hooks/useRazorSplit.ts

@@ -20,6 +20,14 @@ 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>;
 }
 
@@ -101,6 +109,62 @@ async function splitGsapAnimations(
   };
 }
 
+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>,
+  paths: Iterable<string>,
+  writeProjectFile: (path: string, content: string) => Promise<void>,
+): Promise<void> {
+  for (const path of paths) {
+    await writeProjectFile(path, getOriginalContent(originals, path));
+  }
+}
+
+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) => Promise<void>,
+): Promise<number> {
+  let count = 0;
+  for (const element of elements) {
+    const result = await executeSplit(pid, element, splitTime, activeCompPath, writeProjectFile);
+    if (!result.changed) continue;
+    snapshots.set(result.targetPath, {
+      before: getOriginalContent(originals, result.targetPath),
+      after: result.patchedContent,
+    });
+    await writeProjectFile(result.targetPath, result.patchedContent);
+    count++;
+  }
+  return count;
+}
+
 // fallow-ignore-next-line complexity
 async function executeSplit(
   pid: string,
@@ -122,13 +186,23 @@ async function executeSplit(
   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,
-    splitTime,
+    localSplitTime,
     newId,
-    element.start,
+    localElementStart,
     element.duration,
   );
   if (!splitResult.ok) throw new Error("Failed to split clip.");
@@ -147,8 +221,8 @@ async function executeSplit(
         targetPath,
         element.domId,
         newId,
-        splitTime,
-        element.start,
+        localSplitTime,
+        localElementStart,
         element.duration,
       );
       if (gsapResult.content) patchedContent = gsapResult.content;
@@ -172,6 +246,7 @@ export function useRazorSplit({
   recordEdit,
   domEditSaveTimestampRef,
   reloadPreview,
+  forceReloadSdkSession,
   isRecordingRef,
 }: UseRazorSplitOptions) {
   const projectIdRef = useRef(projectId);
@@ -208,6 +283,9 @@ export function useRazorSplit({
           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 });
         showToast(`Split ${getTimelineElementLabel(element)} at ${splitTime.toFixed(2)}s`, "info");
@@ -229,6 +307,7 @@ export function useRazorSplit({
       writeProjectFile,
       domEditSaveTimestampRef,
       reloadPreview,
+      forceReloadSdkSession,
       isRecordingRef,
     ],
   );
@@ -247,51 +326,42 @@ export function useRazorSplit({
       const splittable = selectSplittableElements(elements, splitTime);
       if (splittable.length === 0) return;
 
+      let originals = new Map<string, string>();
+      const finalSnapshots = new Map<string, { before: string; after: string }>();
       try {
-        const originals = new Map<string, string>();
-        for (const el of splittable) {
-          const path = el.sourceFile || activeCompPath || "index.html";
-          if (!originals.has(path)) {
-            originals.set(path, await readFileContent(pid, path));
-          }
-        }
-
-        let splitCount = 0;
-        const finalContent = new Map<string, string>();
-
-        for (const element of splittable) {
-          const result = await executeSplit(
-            pid,
-            element,
-            splitTime,
-            activeCompPath,
-            writeProjectFile,
-          );
-          if (result.changed) {
-            finalContent.set(result.targetPath, result.patchedContent);
-            await writeProjectFile(result.targetPath, result.patchedContent);
-            splitCount++;
-          }
-        }
-
+        originals = await readOriginalFiles(pid, splittable, activeCompPath);
+        const splitCount = await splitElementsAtTime(
+          pid,
+          splittable,
+          splitTime,
+          activeCompPath,
+          originals,
+          finalSnapshots,
+          writeProjectFile,
+        );
         if (splitCount === 0) return;
 
         domEditSaveTimestampRef.current = Date.now();
         await recordEdit({
           label: `Split ${splitCount} clips at ${splitTime.toFixed(2)}s`,
           kind: "timeline",
-          files: Object.fromEntries(
-            [...finalContent].map(([path, after]) => [
-              path,
-              { before: originals.get(path) ?? "", after },
-            ]),
-          ),
+          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");
       } 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.keys(), 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");
       }
@@ -303,6 +373,7 @@ export function useRazorSplit({
       writeProjectFile,
       domEditSaveTimestampRef,
       reloadPreview,
+      forceReloadSdkSession,
       isRecordingRef,
     ],
   );

package/src/hooks/useRenderClipContent.ts

@@ -3,6 +3,8 @@ import { createElement } from "react";
 import { CompositionThumbnail, VideoThumbnail } from "../player";
 import type { TimelineElement } from "../player";
 import { AudioWaveform } from "../player/components/AudioWaveform";
+import { ImageThumbnail } from "../player/components/ImageThumbnail";
+import { encodePreviewPath, resolveMediaPreviewUrl } from "../player/components/thumbnailUtils";
 
 export function normalizeCompositionSrc(
   compSrc: string,
@@ -51,8 +53,16 @@ function trimFractions(el: TimelineElement): { start?: number; end?: number } {
  */
 function renderAudioClip(el: TimelineElement, pid: string, labelColor: string): ReactNode {
   const srcRelative = resolvePreviewRelative(el.src, pid);
-  const audioUrl = srcRelative ? `/api/projects/${pid}/preview/${srcRelative}` : (el.src ?? "");
-  const waveformUrl = srcRelative ? `/api/projects/${pid}/waveform/${srcRelative}` : undefined;
+  // Encode each path segment (spaces, parens, U+202F, unicode) so the URL matches
+  // what the assets panel loads — a raw segment 404s. resolvePreviewRelative
+  // returns the DECODED path, so it must be re-encoded here.
+  const encodedRelative = srcRelative ? encodePreviewPath(srcRelative) : null;
+  const audioUrl = encodedRelative
+    ? `/api/projects/${pid}/preview/${encodedRelative}`
+    : (el.src ?? "");
+  const waveformUrl = encodedRelative
+    ? `/api/projects/${pid}/waveform/${encodedRelative}`
+    : undefined;
   const { start, end } = trimFractions(el);
   return createElement(AudioWaveform, {
     audioUrl,
@@ -100,7 +110,7 @@ export function useRenderClipContent({
       // instead of capturing the master at a time when the comp is fading in.
       if (compSrc) {
         return createElement(CompositionThumbnail, {
-          previewUrl: `/api/projects/${pid}/preview/comp/${compSrc}`,
+          previewUrl: `/api/projects/${pid}/preview/comp/${encodePreviewPath(compSrc)}`,
           label: "",
           labelColor: style.label,
 
@@ -138,9 +148,17 @@ export function useRenderClipContent({
         !/(backdrop|background|overlay|scrim|mask)/i.test(el.id);
 
       if ((el.tag === "video" || el.tag === "img") && el.src) {
-        const mediaSrc = el.src.startsWith("http")
-          ? el.src
-          : `/api/projects/${pid}/preview/${el.src}`;
+        const mediaSrc = resolveMediaPreviewUrl(el.src, pid);
+        // Still images can't be decoded by VideoThumbnail's <video> extractor
+        // (the error event fires and the shimmer never resolves) — render the
+        // image itself as the strip.
+        if (el.tag === "img") {
+          return createElement(ImageThumbnail, {
+            imageSrc: mediaSrc,
+            label: "",
+            labelColor: style.label,
+          });
+        }
         return createElement(VideoThumbnail, {
           videoSrc: mediaSrc,
           label: "",

package/src/hooks/useStudioContextValue.ts

@@ -2,6 +2,8 @@ import { useCallback, useMemo, useRef, useState, type DragEvent } from "react";
 import { STUDIO_INSPECTOR_PANELS_ENABLED } from "../components/editor/manualEditingAvailability";
 import type { StudioContextValue } from "../contexts/StudioContext";
 import type { RightInspectorPanes } from "../utils/studioHelpers";
+import type { TimelineFileDropHandler } from "./useTimelineEditingTypes";
+import { usePlayerStore } from "../player";
 
 interface StudioContextInput {
   projectId: string;
@@ -34,8 +36,6 @@ interface StudioContextInput {
   waitForPendingDomEditSaves: () => Promise<void>;
   handlePreviewIframeRef: (iframe: HTMLIFrameElement | null) => void;
   refreshPreviewDocumentVersion: () => void;
-  timelineVisible: boolean;
-  toggleTimelineVisibility: () => void;
 }
 
 // fallow-ignore-next-line complexity
@@ -61,8 +61,6 @@ export function buildStudioContextValue(input: StudioContextInput): StudioContex
     waitForPendingDomEditSaves: input.waitForPendingDomEditSaves,
     handlePreviewIframeRef: input.handlePreviewIframeRef,
     refreshPreviewDocumentVersion: input.refreshPreviewDocumentVersion,
-    timelineVisible: input.timelineVisible,
-    toggleTimelineVisibility: input.toggleTimelineVisibility,
   };
 }
 
@@ -108,7 +106,7 @@ export function useInspectorState(
 }
 
 // fallow-ignore-next-line complexity
-export function useDragOverlay(onImportFiles: (files: FileList) => void) {
+function useDragOverlay(onImportFiles: (files: FileList) => void) {
   const [active, setActive] = useState(false);
   const counterRef = useRef(0);
   const onDragOver = useCallback((e: DragEvent) => {
@@ -137,3 +135,15 @@ export function useDragOverlay(onImportFiles: (files: FileList) => void) {
   );
   return { active, onDragOver, onDragEnter, onDragLeave, onDrop };
 }
+
+/** Global OS file drop: imports and places at the playhead position. */
+export function useGlobalFileDrop(handleTimelineFileDrop: TimelineFileDropHandler) {
+  const onDrop = useCallback(
+    (files: FileList) => {
+      const start = usePlayerStore.getState().currentTime;
+      void handleTimelineFileDrop(Array.from(files), { start, track: 0 });
+    },
+    [handleTimelineFileDrop],
+  );
+  return useDragOverlay(onDrop);
+}

package/src/hooks/useStudioUrlState.ts

@@ -20,7 +20,6 @@ interface UseStudioUrlStateParams {
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
   rightPanelTab: RightPanelTab;
   rightCollapsed: boolean;
-  timelineVisible: boolean;
   activeCompPathHydrated: boolean;
   domEditSelection: DomEditSelection | null;
   buildDomSelectionFromTarget: (
@@ -66,7 +65,6 @@ export function useStudioUrlState({
   previewIframeRef,
   rightPanelTab,
   rightCollapsed,
-  timelineVisible,
   activeCompPathHydrated,
   domEditSelection,
   buildDomSelectionFromTarget,
@@ -91,12 +89,12 @@ export function useStudioUrlState({
       currentTime: stableTimeRef.current,
       rightPanelTab,
       rightCollapsed,
-      timelineVisible,
+      timelineVisible: null,
       selection: hydratedSelectionRef.current
         ? toPersistedSelection(domEditSelection)
         : pendingSelectionRef.current,
     }),
-    [activeCompPath, domEditSelection, rightCollapsed, rightPanelTab, timelineVisible],
+    [activeCompPath, domEditSelection, rightCollapsed, rightPanelTab],
   );
 
   // Resolve a URL selection to a live element and apply it. Shared by the initial

package/src/hooks/useTimelineEditing.test.tsx

@@ -159,7 +159,7 @@ type TimelineRecordEdit = NonNullable<
 function renderTimelineEditingHookWithLifecycle(input: {
   timelineElements: TimelineElement[];
   iframe: HTMLIFrameElement;
-  commitPositionPatchToHtml: ReturnType<typeof vi.fn<(...args: unknown[]) => Promise<void>>>;
+  commitDomEditPatchBatches: ReturnType<typeof vi.fn<(...args: unknown[]) => Promise<void>>>;
 }): {
   move: ReturnType<typeof useTimelineEditing>["handleTimelineElementMove"];
   unmount: () => void;
@@ -176,7 +176,7 @@ function renderTimelineEditingHookWithLifecycle(input: {
       projectIdRef: { current: "p1" },
       reloadPreview: vi.fn(),
       clearDomSelection: vi.fn(),
-      commitPositionPatchToHtml: input.commitPositionPatchToHtml,
+      commitDomEditPatchBatches: input.commitDomEditPatchBatches,
     });
     const commitRef = useRef(lifecycle.handleDomZIndexReorderCommit);
     commitRef.current = lifecycle.handleDomZIndexReorderCommit;
@@ -481,11 +481,11 @@ describe("useTimelineEditing timeline z-index reorder", () => {
     ]);
     const front = timelineElement({ id: "front", track: 0, zIndex: 0 });
     const back = timelineElement({ id: "back", track: 1, zIndex: 0 });
-    const commitPositionPatchToHtml = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    const commitDomEditPatchBatches = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
     const { move, unmount } = renderTimelineEditingHookWithLifecycle({
       timelineElements: [front, back],
       iframe,
-      commitPositionPatchToHtml,
+      commitDomEditPatchBatches,
     });
 
     await act(async () => {
@@ -501,8 +501,11 @@ describe("useTimelineEditing timeline z-index reorder", () => {
       await flushAsyncWork();
     });
 
-    expect(commitPositionPatchToHtml).toHaveBeenCalled();
-    expect(commitPositionPatchToHtml.mock.calls[0]![1]).toEqual([
+    expect(commitDomEditPatchBatches).toHaveBeenCalled();
+    const batch = commitDomEditPatchBatches.mock.calls[0]![0] as Array<{
+      patches: Array<{ operations: unknown[] }>;
+    }>;
+    expect(batch[0]?.patches[0]?.operations).toEqual([
       { type: "inline-style", property: "z-index", value: "2" },
       { type: "inline-style", property: "position", value: "relative" },
     ]);
@@ -522,14 +525,13 @@ describe("useTimelineEditing timeline z-index reorder", () => {
       { ...back, hasExplicitZIndex: false },
     ]);
     const saveError = new Error("save failed");
-    const commitPositionPatchToHtml = vi
+    const commitDomEditPatchBatches = vi
       .fn<(...args: unknown[]) => Promise<void>>()
-      .mockResolvedValueOnce(undefined)
       .mockRejectedValueOnce(saveError);
     const { move, unmount } = renderTimelineEditingHookWithLifecycle({
       timelineElements: [front, back],
       iframe,
-      commitPositionPatchToHtml,
+      commitDomEditPatchBatches,
     });
     const doc = iframe.contentDocument;
     if (!doc) throw new Error("Expected iframe document");
@@ -576,29 +578,24 @@ describe("useTimelineEditing timeline z-index reorder", () => {
     unmount();
   });
 
-  it("waits for every lifecycle z-index save before resolving a reorder", async () => {
+  it("waits for the lifecycle z-index batch before resolving a reorder", async () => {
     const iframe = createPreviewIframe([
       { id: "front", track: 0, style: "position: relative; z-index: 1" },
       { id: "back", track: 1, style: "position: relative; z-index: 0" },
     ]);
     const front = timelineElement({ id: "front", track: 0, zIndex: 1 });
     const back = timelineElement({ id: "back", track: 1, zIndex: 0 });
-    let releaseFirst!: () => void;
-    let releaseSecond!: () => void;
-    const firstSave = new Promise<void>((resolve) => {
-      releaseFirst = resolve;
+    let releaseBatch!: () => void;
+    const batchSave = new Promise<void>((resolve) => {
+      releaseBatch = resolve;
     });
-    const secondSave = new Promise<void>((resolve) => {
-      releaseSecond = resolve;
-    });
-    const commitPositionPatchToHtml = vi
+    const commitDomEditPatchBatches = vi
       .fn<(...args: unknown[]) => Promise<void>>()
-      .mockReturnValueOnce(firstSave)
-      .mockReturnValueOnce(secondSave);
+      .mockReturnValueOnce(batchSave);
     const { move, unmount } = renderTimelineEditingHookWithLifecycle({
       timelineElements: [front, back],
       iframe,
-      commitPositionPatchToHtml,
+      commitDomEditPatchBatches,
     });
     let settled = false;
 
@@ -621,17 +618,11 @@ describe("useTimelineEditing timeline z-index reorder", () => {
       await flushAsyncWork();
     });
 
-    expect(commitPositionPatchToHtml).toHaveBeenCalledTimes(2);
-    expect(settled).toBe(false);
-
-    await act(async () => {
-      releaseFirst();
-      await flushAsyncWork();
-    });
+    expect(commitDomEditPatchBatches).toHaveBeenCalledTimes(1);
     expect(settled).toBe(false);
 
     await act(async () => {
-      releaseSecond();
+      releaseBatch();
       await movePromise;
       await flushAsyncWork();
     });

package/src/hooks/useTimelineEditingTypes.ts

@@ -22,6 +22,7 @@ export type TimelineZIndexReorderCommit = (
     sourceFile: string;
     key?: string;
   }>,
+  coalesceKey?: string,
 ) => Promise<void>;
 
 export interface UseTimelineEditingOptions {
@@ -43,3 +44,8 @@ export interface UseTimelineEditingOptions {
   forceReloadSdkSession?: () => void;
   handleDomZIndexReorderCommitRef?: MutableRefObject<TimelineZIndexReorderCommit | null>;
 }
+
+export type TimelineFileDropHandler = (
+  files: File[],
+  placement?: { start: number; track: number },
+) => Promise<void>;

package/src/hooks/useTimelineGroupEditing.ts

@@ -21,6 +21,7 @@ import {
 export interface TimelineGroupMoveChange {
   element: TimelineElement;
   start: number;
+  track?: number;
 }
 
 export interface TimelineGroupResizeChange {
@@ -152,9 +153,13 @@ export function useTimelineGroupEditing({
     (changes: TimelineGroupMoveChange[], options?: TimelineGroupCommitOptions) => {
       if (changes.length === 0) return Promise.resolve();
       for (const change of changes) {
-        patchIframeDomTiming(previewIframeRef.current, change.element, [
+        const attrs: Array<[string, string]> = [
           ["data-start", formatTimelineAttributeNumber(change.start)],
-        ]);
+        ];
+        if (change.track != null) {
+          attrs.push(["data-track-index", formatTimelineAttributeNumber(change.track)]);
+        }
+        patchIframeDomTiming(previewIframeRef.current, change.element, attrs);
       }
 
       const maxEnd = Math.max(...changes.map((change) => change.start + change.element.duration));
@@ -169,7 +174,10 @@ export function useTimelineGroupEditing({
             : null,
         );
         const canUseSdk =
-          !needsExtension && sharedPath !== null && sdkChanges.every((change) => change !== null);
+          !needsExtension &&
+          sharedPath !== null &&
+          changes.every((change) => change.track == null) &&
+          sdkChanges.every((change) => change !== null);
         if (canUseSdk) {
           const handled = await sdkTimingBatchPersist(
             sdkChanges.filter((change): change is NonNullable<typeof change> => change !== null),
@@ -194,7 +202,13 @@ export function useTimelineGroupEditing({
           changes.map((change) => ({
             element: change.element,
             buildPatches: (original, target) =>
-              buildTimelineMoveTimingPatch(original, target, change.start, change.element.duration),
+              buildTimelineMoveTimingPatch(
+                original,
+                target,
+                change.start,
+                change.element.duration,
+                change.track,
+              ),
           })),
           coalesceKey,
         );

package/src/index.ts

@@ -1,5 +1,5 @@
 // NLE Layout
-export { NLELayout } from "./components/nle/NLELayout";
+export { EditorShell } from "./components/EditorShell";
 export { NLEPreview } from "./components/nle/NLEPreview";
 export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";
 export type { CompositionLevel } from "./components/nle/CompositionBreadcrumb";