@hyperframes/studio 0.7.56 → 0.7.57

package/src/hooks/useDomEditCommits.test.tsx

@@ -265,7 +265,7 @@ describe("useDomEditCommits z-index reorder persistence", () => {
     document.body.replaceChildren();
   });
 
-  it("persists an N-element reorder with one batch POST, one undo entry, and one reload", async () => {
+  it("persists an N-element reorder with one batch POST, one undo entry, and NO iframe reload", async () => {
     const original =
       '<div id="a" style="z-index: 1"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 3"></div>';
     const after =
@@ -338,12 +338,103 @@ describe("useDomEditCommits z-index reorder persistence", () => {
         coalesceKey: "z-reorder:test",
         files: { "index.html": { before: original, after } },
       });
+      // FIX: a z-only reorder must NOT remount the preview iframe ("the blink").
+      // The live DOM + store already hold the final state and the server matched
+      // every style-only patch, so the reload is provably redundant.
+      expect(rendered.reloadPreview).not.toHaveBeenCalled();
+    } finally {
+      rendered.cleanup();
+    }
+  });
+
+  it("falls back to reloading when the server response omits matched[]", async () => {
+    // Without a matched[] confirmation the persist can't be proven in sync with
+    // the live DOM — the skip-reload path must not engage.
+    const original = '<div id="a" style="z-index: 1"></div>';
+    const after = '<div id="a" style="z-index: 2"></div>';
+    const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
+      const url = requestUrl(input);
+      if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: original });
+      if (url.includes("/file-mutations/patch-elements-batch/")) {
+        return jsonResponse({ ok: true, changed: true, content: after });
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const { iframe, element } = createPreviewElement();
+    element.id = "a";
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      await act(async () => {
+        await rendered.hook.handleDomZIndexReorderCommit([
+          { element, zIndex: 2, id: "a", sourceFile: "index.html" },
+        ]);
+      });
+
+      expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
       expect(rendered.reloadPreview).toHaveBeenCalledTimes(1);
     } finally {
       rendered.cleanup();
     }
   });
 
+  it("warns and reports telemetry for unmatched batch patches without throwing", async () => {
+    // The server reports per-patch matched[]: #b was not found in the source.
+    // The matched subset persisted, so the commit must complete (no rollback of
+    // applied state) while surfacing the partial failure. An unmatched target
+    // also means the live DOM shows z-order the disk lacks, so the skip-reload
+    // path must NOT engage — the reload reconverges the preview with disk.
+    const original = '<div id="a" style="z-index: 1"></div>';
+    const after = '<div id="a" style="z-index: 2"></div>';
+    const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
+      const url = requestUrl(input);
+      if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: original });
+      if (url.includes("/file-mutations/patch-elements-batch/")) {
+        return jsonResponse({ ok: true, changed: true, matched: [true, false], content: after });
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { iframe, element } = createPreviewElement(
+      '<div data-hf-id="hf-card"></div><div id="b"></div>',
+    );
+    element.id = "a";
+    const second = iframe.contentDocument!.getElementById("b")!;
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      await act(async () => {
+        await rendered.hook.handleDomZIndexReorderCommit([
+          { element, zIndex: 2, id: "a", sourceFile: "index.html" },
+          { element: second, zIndex: 1, id: "b", sourceFile: "index.html" },
+        ]);
+      });
+
+      // No throw: the applied live state stays, the matched subset is recorded.
+      expect(element.style.zIndex).toBe("2");
+      expect(second.style.zIndex).toBe("1");
+      expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
+      expect(rendered.reloadPreview).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("could not match 1 patch target(s) in index.html"),
+        "b",
+      );
+      expect(trackStudioEvent).toHaveBeenCalledWith(
+        "save_failure",
+        expect.objectContaining({
+          mutation_type: "z-reorder-unmatched",
+          file_path: "index.html",
+          error_message: expect.stringContaining("b"),
+        }),
+      );
+    } finally {
+      warnSpy.mockRestore();
+      rendered.cleanup();
+    }
+  });
+
   it("rolls back live state after a failed batch POST without a disk write-back", async () => {
     const original = '<div id="a" style="z-index: 7"></div><div id="b"></div>';
     const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {

package/src/hooks/useDomEditCommits.ts

@@ -61,6 +61,34 @@ interface RecordEditInput {
   files: Record<string, { before: string; after: string }>;
 }
 
+/** Human-readable identifier for a batch patch target (for the unmatched warning). */
+function describeBatchPatchTarget(patch: DomEditPatchBatch["patches"][number]): string {
+  return patch.target.id ?? patch.target.hfId ?? patch.target.selector ?? "(unaddressed)";
+}
+
+/**
+ * Surface server-reported unmatched patches. The matched subset already
+ * persisted, so this must NOT throw (a throw would roll back applied state) —
+ * warn and emit save-failure telemetry with a distinct reason instead.
+ */
+function reportUnmatchedBatchPatches(batch: DomEditPatchBatch, matched: boolean[]): void {
+  const unmatchedIds = batch.patches
+    .filter((_, index) => matched[index] === false)
+    .map(describeBatchPatchTarget);
+  if (unmatchedIds.length === 0) return;
+  console.warn(
+    `[studio] z-index reorder: server could not match ${unmatchedIds.length} patch target(s) in ` +
+      `${batch.sourceFile} (their z-order will revert on reload):`,
+    unmatchedIds.join(", "),
+  );
+  trackStudioSaveFailure({
+    source: "dom_edit",
+    error: new Error(`Batch patch target(s) unmatched: ${unmatchedIds.join(", ")}`),
+    filePath: batch.sourceFile,
+    mutationType: "z-reorder-unmatched",
+  });
+}
+
 async function patchElementBatch(projectId: string, batch: DomEditPatchBatch) {
   const before = await readProjectFileContent(projectId, batch.sourceFile);
   const response = await fetch(
@@ -77,16 +105,39 @@ async function patchElementBatch(projectId: string, batch: DomEditPatchBatch) {
   }
   const result = (await response.json()) as {
     changed?: boolean;
+    matched?: boolean[];
     content?: string;
   };
+  if (Array.isArray(result.matched)) reportUnmatchedBatchPatches(batch, result.matched);
   return {
     sourceFile: batch.sourceFile,
     changed: result.changed === true,
+    // Skip-reload safety: the persist is only provably in sync with the live
+    // DOM when the server confirmed EVERY patch target matched. A missing /
+    // short matched[] is treated as unknown (false) so the caller falls back
+    // to reloading rather than silently diverging from disk.
+    allMatched:
+      Array.isArray(result.matched) &&
+      result.matched.length === batch.patches.length &&
+      result.matched.every(Boolean),
     before,
     after: typeof result.content === "string" ? result.content : before,
   };
 }
 
+/**
+ * A batch is reload-skippable only when it is style-only: every operation is an
+ * `inline-style` write. The z-reorder commit applies those exact styles to the
+ * live iframe DOM synchronously, so persisting them adds nothing the preview
+ * doesn't already show. Any other op type (attribute / text-content / …) can
+ * have server-side semantics the live DOM hasn't mirrored — reload for those.
+ */
+function batchesAreInlineStyleOnly(batches: DomEditPatchBatch[]): boolean {
+  return batches.every((batch) =>
+    batch.patches.every((patch) => patch.operations.every((op) => op.type === "inline-style")),
+  );
+}
+
 export interface UseDomEditCommitsParams {
   activeCompPath: string | null;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
@@ -360,7 +411,18 @@ export function useDomEditCommits({
           files,
         });
         forceReloadSdkSession?.();
-        reloadPreview();
+        // A z-only reorder already applied its inline styles to the live iframe
+        // DOM (and the store) synchronously, so remounting the iframe here only
+        // produces a visible blink. Skip the reload when the caller asked for it
+        // AND the persist is provably in sync: style-only ops, every target
+        // matched. Any unmatched patch means the live DOM now shows state disk
+        // doesn't hold — reload so the preview reconverges. (The SSE/file-watcher
+        // reload is independently suppressed by domEditSaveTimestampRef above.)
+        const skipSafe =
+          options.skipReload === true &&
+          batchesAreInlineStyleOnly(batches) &&
+          results.every((result) => result.allMatched);
+        if (!skipSafe) reloadPreview();
       }).catch((error) => {
         const alreadyToasted =
           (error instanceof StudioSaveHttpError ||

package/src/hooks/useElementLifecycleOps.test.tsx

@@ -18,6 +18,7 @@ afterEach(() => {
 interface BatchOptions {
   label: string;
   coalesceKey: string;
+  skipReload?: boolean;
 }
 
 interface CapturedBatchCall {
@@ -36,6 +37,7 @@ type ReorderCommit = (
     key?: string;
   }>,
   coalesceKeyOverride?: string,
+  actionKind?: string,
 ) => Promise<void>;
 
 function renderReorderHook(
@@ -109,6 +111,25 @@ describe("useElementLifecycleOps — z-index reorder payload", () => {
     act(() => root.unmount());
   });
 
+  it("requests skipReload on every z-reorder persist (live DOM already final)", async () => {
+    // The commit applies the z-index (and any injected position) to the live
+    // iframe DOM and the store synchronously, so the persisted style-only patch
+    // adds nothing the preview doesn't already show — the batch commit is asked
+    // to skip the iframe remount. commitDomEditPatchBatches still falls back to
+    // reloading when the server can't confirm every patch target matched.
+    const el = document.createElement("div");
+    el.id = "clip-z";
+
+    const { captured, root } = await runReorderCommit(el, [
+      { element: el, zIndex: 4, id: "clip-z", sourceFile: "index.html" },
+    ]);
+
+    expect(captured).toHaveLength(1);
+    expect(captured[0]?.options.skipReload).toBe(true);
+
+    act(() => root.unmount());
+  });
+
   it("preserves a real id when the element has one", async () => {
     const el = document.createElement("video");
     el.id = "v-hero";
@@ -176,6 +197,150 @@ describe("useElementLifecycleOps — z-index reorder payload", () => {
     act(() => root.unmount());
   });
 
+  it("keeps distinct actions in distinct default coalesce keys", async () => {
+    const el = document.createElement("div");
+    el.id = "clip-a";
+    document.body.appendChild(el);
+    const captured: CapturedBatchCall[] = [];
+    let commit: ReorderCommit | undefined;
+    const root = renderReorderHook(captured, (fn) => (commit = fn));
+
+    await act(async () => {
+      await commit!(
+        [{ element: el, zIndex: 1, id: "clip-a", sourceFile: "index.html" }],
+        undefined,
+        "bring-forward",
+      );
+      await commit!(
+        [{ element: el, zIndex: 0, id: "clip-a", sourceFile: "index.html" }],
+        undefined,
+        "send-backward",
+      );
+    });
+
+    // Same element set, different actions — the keys must differ so the two
+    // edits never coalesce into one undo step within the coalesce window.
+    expect(captured).toHaveLength(2);
+    expect(captured[0]?.options.coalesceKey).toBe("z-reorder:bring-forward:clip-a");
+    expect(captured[1]?.options.coalesceKey).toBe("z-reorder:send-backward:clip-a");
+    act(() => root.unmount());
+  });
+
+  it("updates the store zIndex synchronously for entries that carry a store key", async () => {
+    const el = document.createElement("div");
+    el.id = "clip-a";
+    document.body.appendChild(el);
+    usePlayerStore.getState().setElements([
+      {
+        id: "clip-a",
+        key: "index.html#clip-a",
+        tag: "div",
+        start: 0,
+        duration: 1,
+        track: 0,
+        zIndex: 0,
+        hasExplicitZIndex: false,
+      },
+    ]);
+
+    let commit: ReorderCommit | undefined;
+    let resolveBatch: (() => void) | undefined;
+    function Harness() {
+      const { handleDomZIndexReorderCommit } = useElementLifecycleOps({
+        activeCompPath: "index.html",
+        showToast: vi.fn(),
+        writeProjectFile: vi.fn(async () => {}),
+        domEditSaveTimestampRef: { current: 0 },
+        editHistory: { recordEdit: vi.fn(async () => {}) },
+        projectIdRef: { current: null },
+        reloadPreview: vi.fn(),
+        clearDomSelection: vi.fn(),
+        // Persist stays pending so the assertion below can only be satisfied
+        // by the SYNCHRONOUS store update (the lane-sync path's requirement).
+        commitDomEditPatchBatches: () => new Promise((resolve) => (resolveBatch = resolve)),
+      });
+      commit = handleDomZIndexReorderCommit;
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+
+    let pending: Promise<void> | undefined;
+    act(() => {
+      pending = commit!([
+        {
+          element: el,
+          zIndex: 5,
+          id: "clip-a",
+          sourceFile: "index.html",
+          key: "index.html#clip-a",
+        },
+      ]);
+    });
+
+    expect(usePlayerStore.getState().elements[0]).toMatchObject({
+      zIndex: 5,
+      hasExplicitZIndex: true,
+    });
+
+    resolveBatch?.();
+    await act(async () => pending);
+    act(() => root.unmount());
+  });
+
+  // The canvas context-menu path: the menu no longer pre-applies styles, so the
+  // hook sees the PRISTINE element — prior styles are captured before any
+  // mutation and a failed persist restores them exactly (previously the menu's
+  // optimistic write made the "rollback" restore the already-mutated values,
+  // and the never-persisted position patch silently reverted on reload).
+  it("rolls back a static, inline-style-free element to pristine styles on failure", async () => {
+    const el = document.createElement("div");
+    el.id = "clip-a";
+    el.style.position = "static"; // happy-dom computes "" for unset position
+    document.body.appendChild(el);
+    const failure = new Error("persist failed");
+
+    let commit: ReorderCommit | undefined;
+    function Harness() {
+      const { handleDomZIndexReorderCommit } = useElementLifecycleOps({
+        activeCompPath: "index.html",
+        showToast: vi.fn(),
+        writeProjectFile: vi.fn(async () => {}),
+        domEditSaveTimestampRef: { current: 0 },
+        editHistory: { recordEdit: vi.fn(async () => {}) },
+        projectIdRef: { current: null },
+        reloadPreview: vi.fn(),
+        clearDomSelection: vi.fn(),
+        commitDomEditPatchBatches: vi.fn(async () => {
+          // The live styles were applied by the hook before persist ran.
+          expect(el.style.zIndex).toBe("2");
+          expect(el.style.position).toBe("relative");
+          throw failure;
+        }),
+      });
+      commit = handleDomZIndexReorderCommit;
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+
+    let rejection: unknown;
+    await act(async () => {
+      try {
+        await commit!(
+          [{ element: el, zIndex: 2, id: "clip-a", sourceFile: "index.html" }],
+          undefined,
+          "bring-forward",
+        );
+      } catch (error) {
+        rejection = error;
+      }
+    });
+
+    expect(rejection).toBe(failure);
+    expect(el.style.zIndex).toBe("");
+    expect(el.style.position).toBe("static");
+    act(() => root.unmount());
+  });
+
   it("rolls back only live and store state after an atomic reorder failure", async () => {
     const writeProjectFile = vi.fn(async () => {});
     const recordEdit = vi.fn(async () => {});

package/src/hooks/useElementLifecycleOps.ts

@@ -146,6 +146,7 @@ export function useElementLifecycleOps({
         key?: string;
       }>,
       gestureCoalesceKey?: string,
+      actionKind?: string,
     ) => {
       if (entries.length === 0) return Promise.resolve();
       // Resolver shadow (telemetry-only, decoupled from cutover): record whether
@@ -153,9 +154,13 @@ export function useElementLifecycleOps({
       onReorderShadow?.(
         entries.map((e) => readHfId(e.element)).filter((id): id is string => id != null),
       );
+      // The default key carries the action kind so two DIFFERENT actions on the
+      // same element set (e.g. "bring-forward" then "send-backward" within the
+      // coalesce window) never merge into one undo step. Callers that share a
+      // gesture (lane moves) pass an explicit gestureCoalesceKey instead.
       const coalesceKey =
         gestureCoalesceKey ??
-        `z-reorder:${entries.map((e) => e.id ?? e.selector ?? e.element.getAttribute("data-hf-id") ?? "el").join(":")}`;
+        `z-reorder:${actionKind ?? "reorder"}:${entries.map((e) => e.id ?? e.selector ?? e.element.getAttribute("data-hf-id") ?? "el").join(":")}`;
       const patchesBySourceFile = new Map<string, DomEditPatchBatch["patches"]>();
       const rollbacks: Array<() => void> = [];
       for (const entry of entries) {
@@ -212,12 +217,20 @@ export function useElementLifecycleOps({
       }));
       // Resolves once every source-file batch is persisted so a same-file timing write
       // can be ordered after it (see applyTimelineStackingReorder callers).
-      return commitDomEditPatchBatches(batches, { label: "Reorder layers", coalesceKey }).catch(
-        (error) => {
-          for (const rollback of rollbacks) rollback();
-          throw error;
-        },
-      );
+      //
+      // skipReload: the live iframe DOM and the player store already hold the
+      // final z state (applied synchronously above), and the persisted patch is
+      // inline-style-only — a full iframe remount would only blink the preview.
+      // commitDomEditPatchBatches still falls back to reloading whenever the
+      // server reports an unmatched patch target (live DOM ≠ disk).
+      return commitDomEditPatchBatches(batches, {
+        label: "Reorder layers",
+        coalesceKey,
+        skipReload: true,
+      }).catch((error) => {
+        for (const rollback of rollbacks) rollback();
+        throw error;
+      });
     },
     [commitDomEditPatchBatches, onReorderShadow],
   );

package/src/hooks/useElementPicker.ts

@@ -1,6 +1,10 @@
 import { useState, useCallback, useRef } from "react";
 import { useMountEffect } from "./useMountEffect";
 import { resolveSourceFile, applyPatch } from "../utils/sourcePatcher";
+import {
+  acceptStudioRuntimeMessage,
+  postRuntimeControlMessage,
+} from "../player/lib/runtimeProtocol";
 
 export interface PickedElement {
   id: string | null;
@@ -65,10 +69,7 @@ export function useElementPicker(
 
   const enablePick = useCallback(() => {
     try {
-      getActiveIframe()?.contentWindow?.postMessage(
-        { source: "hf-parent", type: "control", action: "enable-pick-mode" },
-        "*",
-      );
+      postRuntimeControlMessage(getActiveIframe()?.contentWindow, "enable-pick-mode");
       setIsPickMode(true);
     } catch {
       /* cross-origin */
@@ -77,10 +78,7 @@ export function useElementPicker(
 
   const disablePick = useCallback(() => {
     try {
-      getActiveIframe()?.contentWindow?.postMessage(
-        { source: "hf-parent", type: "control", action: "disable-pick-mode" },
-        "*",
-      );
+      postRuntimeControlMessage(getActiveIframe()?.contentWindow, "disable-pick-mode");
     } catch {
       /* cross-origin */
     }
@@ -96,6 +94,7 @@ export function useElementPicker(
     const handleMessage = (e: MessageEvent) => {
       const data = e.data;
       if (data?.source !== "hf-preview") return;
+      if (!acceptStudioRuntimeMessage(data)) return;
       // Accept events from either the primary iframe or the active override
       const activeIframe = getActiveIframe();
       if (!activeIframe) return;

package/src/hooks/useTimelineAssetDropOps.ts

@@ -0,0 +1,175 @@
+// Asset-drop handlers for the timeline: drop an existing project asset at a
+// placement, or upload dragged-in OS files and place them sequentially.
+// Extracted verbatim from useTimelineEditing.ts to keep it under the studio
+// 600-line cap.
+import { useCallback, type MutableRefObject, type RefObject } from "react";
+import type { TimelineElement } from "../player";
+import {
+  buildTimelineAssetId,
+  buildTimelineAssetInsertHtml,
+  buildTimelineFileDropPlacements,
+  fitTimelineAssetGeometry,
+  getTimelineAssetKind,
+  insertTimelineAssetIntoSource,
+  resolveTimelineAssetCompositionSize,
+  resolveTimelineAssetSrc,
+} from "../utils/timelineAssetDrop";
+import { generateId } from "../utils/generateId";
+import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
+import { collectHtmlIds, resolveDroppedAssetDuration } from "../utils/studioHelpers";
+import { formatTimelineAttributeNumber } from "./timelineEditingHelpers";
+import { readFileContent } from "./timelineTimingSync";
+
+interface UseTimelineAssetDropOpsOptions {
+  projectIdRef: MutableRefObject<string | null>;
+  activeCompPath: string | null;
+  timelineElements: TimelineElement[];
+  showToast: (message: string, tone?: "error" | "info") => void;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  domEditSaveTimestampRef: MutableRefObject<number>;
+  reloadPreview: () => void;
+  uploadProjectFiles: (files: Iterable<File>, dir?: string) => Promise<string[]>;
+  isRecordingRef?: RefObject<boolean>;
+  forceReloadSdkSession?: () => void;
+}
+
+export function useTimelineAssetDropOps({
+  projectIdRef,
+  activeCompPath,
+  timelineElements,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  reloadPreview,
+  uploadProjectFiles,
+  isRecordingRef,
+  forceReloadSdkSession,
+}: UseTimelineAssetDropOpsOptions) {
+  // fallow-ignore-next-line complexity
+  const handleTimelineAssetDrop = useCallback(
+    // fallow-ignore-next-line complexity
+    async (
+      assetPath: string,
+      placement: Pick<TimelineElement, "start" | "track">,
+      durationOverride?: number,
+    ) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      if (!pid) throw new Error("No active project");
+
+      const kind = getTimelineAssetKind(assetPath);
+      if (!kind) {
+        showToast("Only image, video, and audio assets can be dropped onto the timeline.");
+        return;
+      }
+
+      const targetPath = activeCompPath || "index.html";
+      try {
+        const originalContent = await readFileContent(pid, targetPath);
+
+        const normalizedStart = Number(formatTimelineAttributeNumber(placement.start));
+        const duration =
+          Number.isFinite(durationOverride) && durationOverride != null && durationOverride > 0
+            ? durationOverride
+            : await resolveDroppedAssetDuration(pid, assetPath, kind);
+        const normalizedDuration = Number(formatTimelineAttributeNumber(duration));
+        const newId = buildTimelineAssetId(assetPath, collectHtmlIds(originalContent));
+        const resolvedAssetSrc = resolveTimelineAssetSrc(targetPath, assetPath);
+
+        const resolvedTargetPath = targetPath || "index.html";
+        const relevantElements = timelineElements.filter(
+          (te) => (te.sourceFile || activeCompPath || "index.html") === resolvedTargetPath,
+        );
+        const newElementZIndex = Math.max(1, relevantElements.length + 1);
+
+        const patchedContent = insertTimelineAssetIntoSource(
+          originalContent,
+          buildTimelineAssetInsertHtml({
+            id: newId,
+            hfId: `hf-${generateId()}`,
+            assetPath: resolvedAssetSrc,
+            kind,
+            start: normalizedStart,
+            duration: normalizedDuration,
+            track: placement.track,
+            zIndex: newElementZIndex,
+            geometry: fitTimelineAssetGeometry(
+              null,
+              resolveTimelineAssetCompositionSize(originalContent),
+            ),
+          }),
+        );
+
+        domEditSaveTimestampRef.current = Date.now();
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Add timeline asset",
+          kind: "timeline",
+          files: { [targetPath]: patchedContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit,
+        });
+
+        forceReloadSdkSession?.();
+        reloadPreview();
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Failed to drop asset onto timeline";
+        showToast(message);
+      }
+    },
+    [
+      projectIdRef,
+      activeCompPath,
+      recordEdit,
+      showToast,
+      timelineElements,
+      writeProjectFile,
+      domEditSaveTimestampRef,
+      reloadPreview,
+      isRecordingRef,
+      forceReloadSdkSession,
+    ],
+  );
+
+  // fallow-ignore-next-line complexity
+  const handleTimelineFileDrop = useCallback(
+    // fallow-ignore-next-line complexity
+    async (files: File[], placement?: Pick<TimelineElement, "start" | "track">) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      const uploaded = await uploadProjectFiles(files);
+      if (uploaded.length === 0) return;
+      const durations: number[] = [];
+      for (const assetPath of uploaded) {
+        const kind = getTimelineAssetKind(assetPath);
+        const duration = kind ? await resolveDroppedAssetDuration(pid, assetPath, kind) : 0;
+        durations.push(Number(formatTimelineAttributeNumber(duration)));
+      }
+      const placements = buildTimelineFileDropPlacements(
+        placement ?? { start: 0, track: 0 },
+        durations,
+      );
+      for (const [index, assetPath] of uploaded.entries()) {
+        await handleTimelineAssetDrop(
+          assetPath,
+          placements[index] ?? placements[0],
+          durations[index],
+        );
+      }
+    },
+    [handleTimelineAssetDrop, projectIdRef, uploadProjectFiles, isRecordingRef, showToast],
+  );
+
+  return { handleTimelineAssetDrop, handleTimelineFileDrop };
+}