@hyperframes/studio 0.7.55 → 0.7.56

package/src/hooks/useRazorSplit.test.ts

@@ -0,0 +1,269 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../player";
+import { usePlayerStore } from "../player";
+import { useRazorSplit } from "./useRazorSplit";
+import { createPersistentEditHistoryStore } from "./usePersistentEditHistory";
+import { createEmptyEditHistory } from "../utils/editHistory";
+import type { EditHistoryStorageAdapter } from "../utils/editHistoryStorage";
+import { createSplitFetchMock, mountProbe } from "./useRazorSplit.testHelpers";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const ROOT_FILE = "index.html";
+const SUBCOMP_FILE = "scenes/intro.html";
+
+// A root-level clip lives in index.html and is authored in local time already.
+const rootElement: TimelineElement = {
+  id: "root-clip",
+  tag: "div",
+  start: 0,
+  duration: 10,
+  track: 0,
+  domId: "root-clip",
+  sourceFile: ROOT_FILE,
+  timingSource: "authored",
+};
+
+// An expanded sub-comp child: `start` is in MASTER coordinates (offset by the
+// host's master start), `sourceFile` is the sub-comp, and `expandedParentStart`
+// is that host master start. Its authored time in the file is start - basis.
+const expandedChild: TimelineElement = {
+  id: "child-clip",
+  tag: "div",
+  start: 2,
+  duration: 6,
+  track: 1,
+  domId: "child-clip",
+  sourceFile: SUBCOMP_FILE,
+  timingSource: "authored",
+  expandedParentStart: 2,
+};
+
+interface SplitRequest {
+  path: string;
+  splitTime: number;
+  elementStart: number;
+  elementDuration: number;
+}
+
+type SingleSplit = (element: TimelineElement, splitTime: number) => Promise<void>;
+type SplitAll = (splitTime: number) => Promise<void>;
+
+interface Harness {
+  splitRequests: SplitRequest[];
+  singleRef: { current: SingleSplit | undefined };
+  allRef: { current: SplitAll | undefined };
+  root: ReturnType<typeof mountProbe>;
+}
+
+function mountRazorSplit(): Harness {
+  const disk: Record<string, string> = {
+    [ROOT_FILE]: `<div class="clip" id="root-clip" data-start="0" data-duration="10"></div>`,
+    [SUBCOMP_FILE]: `<div class="clip" id="child-clip" data-start="0" data-duration="6"></div>`,
+  };
+  const splitRequests: SplitRequest[] = [];
+
+  const fetchMock = createSplitFetchMock(disk, (path, body) => {
+    splitRequests.push({
+      path,
+      splitTime: body.splitTime,
+      elementStart: body.elementStart,
+      elementDuration: body.elementDuration,
+    });
+  });
+  vi.stubGlobal("fetch", fetchMock);
+
+  const singleRef: { current: SingleSplit | undefined } = { current: undefined };
+  const allRef: { current: SplitAll | undefined } = { current: undefined };
+
+  function Component() {
+    const { handleRazorSplit, handleRazorSplitAll } = useRazorSplit({
+      projectId: "p1",
+      activeCompPath: ROOT_FILE,
+      showToast: () => {},
+      writeProjectFile: async (path, content) => {
+        disk[path] = content;
+      },
+      recordEdit: async () => {},
+      domEditSaveTimestampRef: { current: 0 },
+      reloadPreview: () => {},
+    });
+    singleRef.current = handleRazorSplit;
+    allRef.current = handleRazorSplitAll;
+    return null;
+  }
+
+  const root = mountProbe(Component);
+  return { splitRequests, singleRef, allRef, root };
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.setState({ elements: [] });
+  vi.unstubAllGlobals();
+});
+
+describe("useRazorSplit — sub-comp coordinate rebasing", () => {
+  let harness: Harness;
+  beforeEach(() => {
+    harness = mountRazorSplit();
+  });
+  afterEach(() => {
+    act(() => harness.root.unmount());
+  });
+
+  it("rebases an expanded sub-comp child split into the sub-comp's local time", async () => {
+    // Master split time T = 5; host starts at 2, so local time is 3.
+    await act(async () => {
+      await harness.singleRef.current!(expandedChild, 5);
+    });
+
+    expect(harness.splitRequests).toHaveLength(1);
+    const req = harness.splitRequests[0];
+    expect(req.path).toBe(SUBCOMP_FILE);
+    expect(req.splitTime).toBe(3); // 5 - expandedParentStart(2), NOT 5
+    expect(req.elementStart).toBe(0); // 2 - 2, NOT the master start 2
+    expect(req.elementDuration).toBe(6);
+  });
+
+  it("leaves a root-level clip's coordinates unchanged", async () => {
+    // Master split time T = 4; no expandedParentStart, so nothing is rebased.
+    await act(async () => {
+      await harness.singleRef.current!(rootElement, 4);
+    });
+
+    expect(harness.splitRequests).toHaveLength(1);
+    const req = harness.splitRequests[0];
+    expect(req.path).toBe(ROOT_FILE);
+    expect(req.splitTime).toBe(4);
+    expect(req.elementStart).toBe(0);
+    expect(req.elementDuration).toBe(10);
+  });
+
+  it("rebases each element individually in a mixed razor-split-all gesture", async () => {
+    usePlayerStore.setState({ elements: [rootElement, expandedChild] });
+
+    // Master split time T = 3 lies inside both clips.
+    await act(async () => {
+      await harness.allRef.current!(3);
+    });
+
+    expect(harness.splitRequests).toHaveLength(2);
+    const rootReq = harness.splitRequests.find((r) => r.path === ROOT_FILE)!;
+    const childReq = harness.splitRequests.find((r) => r.path === SUBCOMP_FILE)!;
+
+    // Root clip: already local — master coordinates pass through untouched.
+    expect(rootReq.splitTime).toBe(3);
+    expect(rootReq.elementStart).toBe(0);
+
+    // Expanded child: rebased by its OWN expandedParentStart, not the root's.
+    expect(childReq.splitTime).toBe(1); // 3 - 2
+    expect(childReq.elementStart).toBe(0); // 2 - 2
+  });
+});
+
+// ── Bug 1: split must resync the SDK session so undo isn't refused ────────────
+
+const memoryStorage = (): EditHistoryStorageAdapter => {
+  const store = new Map<string, string>();
+  return {
+    load: async (k) => store.get(k) ?? null,
+    save: async (k, v) => {
+      store.set(k, v);
+    },
+  } as unknown as EditHistoryStorageAdapter;
+};
+
+interface UndoHarness {
+  singleRef: { current: SingleSplit | undefined };
+  disk: Record<string, string>;
+  store: ReturnType<typeof createPersistentEditHistoryStore>;
+  forceReloadSdkSession: ReturnType<typeof vi.fn>;
+  root: ReturnType<typeof mountProbe>;
+}
+
+function mountRazorSplitWithHistory(): UndoHarness {
+  const disk: Record<string, string> = {
+    [ROOT_FILE]: `<div class="clip" id="root-clip" data-start="0" data-duration="10"></div>`,
+  };
+  const store = createPersistentEditHistoryStore({
+    projectId: "p1",
+    storage: memoryStorage(),
+    initialState: createEmptyEditHistory(),
+    now: () => Date.now(),
+    onChange: () => {},
+  });
+  const forceReloadSdkSession = vi.fn();
+
+  const fetchMock = createSplitFetchMock(disk);
+  vi.stubGlobal("fetch", fetchMock);
+
+  const singleRef: { current: SingleSplit | undefined } = { current: undefined };
+  function Component() {
+    const { handleRazorSplit } = useRazorSplit({
+      projectId: "p1",
+      activeCompPath: ROOT_FILE,
+      showToast: () => {},
+      writeProjectFile: async (path, content) => {
+        disk[path] = content;
+      },
+      recordEdit: (input) => store.recordEdit(input),
+      domEditSaveTimestampRef: { current: 0 },
+      reloadPreview: () => {},
+      forceReloadSdkSession,
+    });
+    singleRef.current = handleRazorSplit;
+    return null;
+  }
+  const root = mountProbe(Component);
+  return { singleRef, disk, store, forceReloadSdkSession, root };
+}
+
+describe("useRazorSplit — undo integrity after split (Bug 1)", () => {
+  let h: UndoHarness;
+  beforeEach(() => {
+    h = mountRazorSplitWithHistory();
+  });
+  afterEach(() => {
+    act(() => h.root.unmount());
+  });
+
+  const readFile = () => ({
+    readFile: async (p: string) => h.disk[p],
+    writeFile: async (p: string, c: string) => {
+      h.disk[p] = c;
+    },
+  });
+
+  it("resyncs the SDK session after a split (matches every other server-write path)", async () => {
+    await act(async () => {
+      await h.singleRef.current!(rootElement, 4);
+    });
+    expect(h.forceReloadSdkSession).toHaveBeenCalledTimes(1);
+  });
+
+  it("applies undo after a split without an external-change refusal", async () => {
+    await act(async () => {
+      await h.singleRef.current!(rootElement, 4);
+    });
+    const result = await h.store.undo(readFile());
+    expect(result.ok).toBe(true);
+    expect(result.reason).toBeUndefined();
+    // The file is restored to its pre-split bytes.
+    expect(h.disk[ROOT_FILE]).not.toContain("<!--split-->");
+  });
+
+  it("still trips the guard when the file is edited externally after a split", async () => {
+    await act(async () => {
+      await h.singleRef.current!(rootElement, 4);
+    });
+    // Simulate the user editing the file in their own editor after the split.
+    h.disk[ROOT_FILE] = `${h.disk[ROOT_FILE]}<!--hand-edit-->`;
+    const result = await h.store.undo(readFile());
+    expect(result.ok).toBe(false);
+    expect(result.reason).toBe("content-mismatch");
+  });
+});

package/src/hooks/useRazorSplit.testHelpers.ts

@@ -0,0 +1,64 @@
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { vi } from "vitest";
+
+export interface SplitBody {
+  splitTime: number;
+  elementStart: number;
+  elementDuration: number;
+}
+
+function decodePathFromUrl(url: string, marker: string): string {
+  const encoded = url.slice(url.indexOf(marker) + marker.length);
+  return decodeURIComponent(encoded);
+}
+
+/**
+ * Fetch mock shared by both harnesses: GSAP mutations 400 (no script in fixtures),
+ * split-element writes a `<!--split-->` marker so `changed` is true, and file reads
+ * echo the in-memory `disk`. `onSplit` (when set) records each split request's body.
+ */
+export function createSplitFetchMock(
+  disk: Record<string, string>,
+  onSplit?: (path: string, body: SplitBody) => void,
+) {
+  return vi.fn(async (url: string, init?: RequestInit) => {
+    const u = String(url);
+    if (u.includes("/gsap-mutations/")) {
+      // No GSAP script in the fixtures — mirror the server's 400 response.
+      return new Response(JSON.stringify({ error: "no GSAP script found in file" }), {
+        status: 400,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+    if (u.includes("/file-mutations/split-element/")) {
+      const path = decodePathFromUrl(u, "/file-mutations/split-element/");
+      onSplit?.(path, JSON.parse(String(init?.body)) as SplitBody);
+      // Return content that differs from the original so `changed` is true.
+      const after = `${disk[path]}<!--split-->`;
+      disk[path] = after; // server writes the split to disk
+      return new Response(JSON.stringify({ ok: true, changed: true, content: after }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+    if (u.includes("/files/")) {
+      const path = decodePathFromUrl(u, "/files/").replace(/\?.*$/, "");
+      return new Response(JSON.stringify({ content: disk[path] ?? "" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+    void init;
+    throw new Error(`unexpected fetch: ${u}`);
+  });
+}
+
+/** Mount a render-only probe component into a fresh host and return its root. */
+export function mountProbe(Component: React.ComponentType): ReturnType<typeof createRoot> {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => root.render(React.createElement(Component)));
+  return root;
+}

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