@hyperframes/studio 0.8.100 → 0.8.102

package/src/player/components/timelineDragDrop.test.tsx

@@ -4,7 +4,7 @@ import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi, type Mock } from "vitest";
 import { TIMELINE_ASSET_MIME, TIMELINE_BLOCK_MIME } from "../../utils/timelineAssetDrop";
-import { usePlayerStore } from "../store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { createTimelineRowGeometry } from "./timelineLayout";
 import { resolveDropInsertRow, useTimelineAssetDrop } from "./timelineDragDrop";
 import { getTimelineRowTop, TRACK_H } from "./timelineLayout";
@@ -39,10 +39,19 @@ function assetTransfer(payload: string): DropTransfer {
   };
 }
 
+// One far-off clip per lane, so a drop keeps its pointer time instead of an empty lane's 0.
+const FAR_CLIPS: TimelineElement[] = Array.from({ length: 100 }, (_, track) => ({
+  id: `far-${track}`,
+  tag: "div",
+  start: 900,
+  duration: 1,
+  track,
+}));
+
 function renderHarness(
   onAssetDrop: Mock,
   sessionEpoch = 1,
-  options: { onBlockDrop?: Mock; strict?: boolean } = {},
+  options: { onBlockDrop?: Mock; strict?: boolean; elements?: TimelineElement[] } = {},
 ) {
   const tracks = Array.from({ length: 100 }, (_, index) => index);
   const geometry = createTimelineRowGeometry(
@@ -60,6 +69,7 @@ function renderHarness(
       scrollRef: { current: scroll },
       ppsRef: { current: 40 },
       trackOrderRef: { current: tracks },
+      elementsRef: { current: options.elements ?? FAR_CLIPS },
       rowGeometryRef: { current: geometry },
       contentOrigin: 0,
       sessionEpoch: epoch,
@@ -149,8 +159,8 @@ describe("useTimelineAssetDrop", () => {
     });
 
     expect(onAssetDrop).toHaveBeenCalledTimes(1);
-    // pps=40, clientX=400 -> 10s at the pointer, not the playhead.
-    expect(onAssetDrop).toHaveBeenCalledWith("/media/hero.mp4", { start: 10, track: 100 });
+    // The appended lane is empty, so the drop starts at 0.
+    expect(onAssetDrop).toHaveBeenCalledWith("/media/hero.mp4", { start: 0, track: 100 });
     expect(view.api.isDragOver).toBe(false);
     act(() => view.root.unmount());
   });
@@ -256,6 +266,52 @@ describe("useTimelineAssetDrop", () => {
   });
 });
 
+describe("useTimelineAssetDrop start", () => {
+  function dropAt(elements: TimelineElement[], clientX: number) {
+    const onAssetDrop = vi.fn();
+    const view = renderHarness(onAssetDrop, 1, { elements });
+    const transfer = assetTransfer(JSON.stringify({ path: "assets/a.mp4" }));
+    act(() => view.api.handleAssetDragOver(dragEvent(transfer, clientX, ROW0_MID_Y)));
+    const preview = view.api.dropPreview;
+    act(() => view.api.handleAssetDrop(dragEvent(transfer, clientX, ROW0_MID_Y)));
+    act(() => view.root.unmount());
+    return { preview, committed: onAssetDrop.mock.calls[0]?.[1] };
+  }
+
+  it("starts a drop on an empty timeline at 0, in the preview and the commit", () => {
+    // pps=40, clientX=80 -> 2s at the pointer.
+    const { preview, committed } = dropAt([], 80);
+    expect(preview).toEqual({ start: 0, track: 0 });
+    expect(committed).toEqual(preview);
+  });
+
+  it("starts a drop on an empty lane at 0 while other lanes hold clips", () => {
+    const { committed } = dropAt([{ id: "c", tag: "div", start: 0, duration: 5, track: 1 }], 80);
+    expect(committed).toEqual({ start: 0, track: 0 });
+  });
+
+  it("snaps a drop within TIMELINE_SNAP_PX of a clip edge onto that edge", () => {
+    const lane: TimelineElement[] = [{ id: "c", tag: "div", start: 0, duration: 5, track: 0 }];
+    // The clip ends at x=200; 6 px past it is 5.15s, inside the 8 px radius.
+    const { preview, committed } = dropAt(lane, 206);
+    expect(preview).toEqual({ start: 5, track: 0 });
+    expect(committed).toEqual(preview);
+    // 12 px past it is outside the radius and keeps the pointer time.
+    expect(dropAt(lane, 212).committed).toEqual({ start: 5.3, track: 0 });
+  });
+
+  it("keeps the pointer time with the magnet off, and still starts an empty lane at 0", () => {
+    usePlayerStore.getState().setTimelineSnapEnabled(false);
+    try {
+      const lane: TimelineElement[] = [{ id: "c", tag: "div", start: 0, duration: 5, track: 0 }];
+      expect(dropAt(lane, 206).committed).toEqual({ start: 5.15, track: 0 });
+      expect(dropAt([], 80).committed).toEqual({ start: 0, track: 0 });
+    } finally {
+      usePlayerStore.getState().setTimelineSnapEnabled(true);
+    }
+  });
+});
+
 describe("resolveDropInsertRow", () => {
   const rows = [TRACK_H, TRACK_H, TRACK_H];
   it("stays on the row at the boundary between two rows", () => {
@@ -302,7 +358,7 @@ describe("useTimelineAssetDrop new-track drops", () => {
     expect(onAssetDrop).toHaveBeenCalledWith(
       "assets/a.png",
       expect.objectContaining({
-        start: 10,
+        start: 0,
         insertRow: 0,
         trackOrder: Array.from({ length: 100 }, (_, index) => index),
       }),

package/src/player/components/timelineDragDrop.ts

@@ -10,6 +10,8 @@ import {
   type TimelineRowGeometry,
 } from "./timelineLayout";
 import { resolveInsertRow } from "./timelineCollision";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { collectTimelineSnapTargets, snapTimelineTime, TIMELINE_SNAP_PX } from "./timelineSnapping";
 import type { TimelineDropCallbacks, TimelineDropPlacement } from "./timelineCallbacks";
 import {
   applyTimelineAutoScrollStep,
@@ -20,6 +22,7 @@ interface UseTimelineAssetDropOptions extends TimelineDropCallbacks {
   scrollRef: RefObject<HTMLDivElement | null>;
   ppsRef: RefObject<number>;
   trackOrderRef: RefObject<number[]>;
+  elementsRef: RefObject<readonly TimelineElement[]>;
   rowGeometryRef: RefObject<TimelineRowGeometry>;
   contentOrigin: number;
   sessionEpoch: number;
@@ -65,20 +68,36 @@ export function resolveDropInsertRow(
   return resolveInsertRow(rowFloat, trackCount);
 }
 
+function alignDropStart(
+  placement: TimelineDropPlacement,
+  elements: readonly TimelineElement[],
+  pixelsPerSecond: number,
+): TimelineDropPlacement {
+  const laneHasClips =
+    placement.insertRow == null && elements.some((el) => el.track === placement.track);
+  if (!laneHasClips) return { ...placement, start: 0 };
+  if (!usePlayerStore.getState().timelineSnapEnabled) return placement;
+  const targets = collectTimelineSnapTargets({ elements, playheadTime: null, beatTimes: [] });
+  const threshold = TIMELINE_SNAP_PX / Math.max(pixelsPerSecond, 1);
+  return { ...placement, start: snapTimelineTime(placement.start, targets, threshold).time };
+}
+
 function placeDrop(
   geometry: Parameters<typeof resolveTimelineAssetDrop>[0],
+  elements: readonly TimelineElement[],
   clientX: number,
   clientY: number,
   // Blocks and compositions are written by their own installers, which only take a track.
   canInsertTrack: boolean,
 ): TimelineDropPlacement {
   const placement = resolveTimelineAssetDrop(geometry, clientX, clientY);
-  if (!canInsertTrack) return placement;
   const contentY = clientY - geometry.rectTop + geometry.scrollTop;
-  const insertRow = resolveDropInsertRow(contentY, geometry.rowHeights, geometry.trackOrder.length);
-  return insertRow == null
-    ? placement
-    : { ...placement, insertRow, trackOrder: geometry.trackOrder };
+  const insertRow = canInsertTrack
+    ? resolveDropInsertRow(contentY, geometry.rowHeights, geometry.trackOrder.length)
+    : null;
+  const aimed =
+    insertRow == null ? placement : { ...placement, insertRow, trackOrder: geometry.trackOrder };
+  return alignDropStart(aimed, elements, geometry.pixelsPerSecond);
 }
 
 function invokeDropCallback(callback: () => Promise<void> | void): void {
@@ -118,14 +137,15 @@ function applyTypedJsonDrop(
 }
 
 /**
- * Dropping an asset/file/block/composition onto the timeline places it on the row
- * and at the time it was dropped on; an asset moves to that row's nearest free time.
+ * Dropping an asset/file/block/composition places it on the row at 0 on an empty lane, else at
+ * the pointer snapped to a near clip edge; an asset moves to that row's nearest free time.
  * Supersedes the prior playhead decision (#2291); see useAddAssetAtPlayhead.
  */
 export function useTimelineAssetDrop({
   scrollRef,
   ppsRef,
   trackOrderRef,
+  elementsRef,
   rowGeometryRef,
   contentOrigin,
   onFileDrop,
@@ -197,12 +217,13 @@ export function useTimelineAssetDrop({
           rowHeights: rowGeometryRef.current.rowHeights,
           trackOrder: trackOrderRef.current,
         },
+        elementsRef.current,
         clientX,
         clientY,
         canInsertTrack,
       );
     },
-    [scrollRef, ppsRef, trackOrderRef, rowGeometryRef, contentOrigin],
+    [scrollRef, ppsRef, trackOrderRef, elementsRef, rowGeometryRef, contentOrigin],
   );
 
   const handleAssetDragOver = useCallback(

package/src/player/components/useTimelineProviderState.tsx

@@ -229,6 +229,7 @@ export function useTimelineProviderState({
     scrollRef,
     ppsRef,
     trackOrderRef,
+    elementsRef: timelineElementsRef,
     rowGeometryRef,
     contentOrigin,
     onFileDrop: pinnedOnFileDrop,

package/src/utils/domEditSaveQueue.ts

@@ -20,6 +20,7 @@ interface DomEditSaveQueueOptions {
 export interface DomEditSaveQueue {
   enqueue: <T>(save: () => Promise<T>) => Promise<T>;
   waitForIdle: () => Promise<DomEditSaveDrainResult>;
+  isIdle: () => boolean;
   reset: () => void;
   destroy: () => void;
 }
@@ -39,6 +40,7 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
   const failureThreshold = options.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;
 
   let tail = Promise.resolve();
+  let queuedCount = 0;
   let consecutiveFailures = 0;
   let breakerOpen = false;
   let drainError: unknown = null;
@@ -81,6 +83,7 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
   return {
     enqueue(save) {
       if (breakerOpen) return Promise.reject(new DomEditSaveQueueOpenError());
+      queuedCount += 1;
       const queued = tail
         .catch(() => undefined)
         .then(() => {
@@ -88,8 +91,8 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
           return run(save);
         });
       tail = queued.then(
-        () => undefined,
-        () => undefined,
+        () => void (queuedCount -= 1),
+        () => void (queuedCount -= 1),
       );
       return queued;
     },
@@ -103,6 +106,8 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
       return { status: "clean" };
     },
 
+    isIdle: () => queuedCount === 0,
+
     reset,
 
     destroy() {

package/src/utils/gsapSoftReload.ts

@@ -91,7 +91,7 @@ function isGsapScript(text: string): boolean {
   );
 }
 
-export function findGsapScriptElements(doc: Document): HTMLScriptElement[] {
+export function findGsapScriptElements(doc: ParentNode): HTMLScriptElement[] {
   const results: HTMLScriptElement[] = [];
   const scripts = doc.querySelectorAll<HTMLScriptElement>("script:not([src])");
   for (const script of scripts) {

package/src/utils/gsapUndoRestore.test.ts

@@ -366,6 +366,52 @@ describe("applyUndoRestoreToPreview", () => {
     expect(meta.content).toBe(content);
   });
 
+  const SUB = "compositions/sub.html";
+  const sub = (style: string, rootAttrs = "") =>
+    `<template id="sub-template"><div data-hf-id="hf-root" id="sub" data-composition-id="sub"${rootAttrs}><div ${style} data-hf-id="hf-t" id="target"></div></div></template>`;
+  const host = (style: string) =>
+    `<div data-composition-file="${SUB}" data-hf-id="hf-host"><div data-hf-inner-root="true" data-hf-authored-id="sub" data-hf-id="hf-root"><div data-hf-id="hf-t" id="target" ${style}></div></div></div>`;
+
+  it("restores a sub-composition file in place, on every host that inlines it", () => {
+    const { iframe, doc } = buildLiveIframe(
+      host(`style="clip-path: inset(0px 40px 0px 0px);"`) +
+        host(`style="clip-path: inset(0px 40px 0px 0px);"`),
+    );
+    const reloadPreview = vi.fn();
+    const files = {
+      [SUB]: { previous: sub(`style="clip-path: inset(0px 40px 0px 0px)"`), restored: sub("") },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("soft");
+    expect(reloadPreview).not.toHaveBeenCalled();
+    const targets = [...doc.querySelectorAll('[data-hf-id="hf-t"]')];
+    expect(targets.map((el) => el.getAttribute("style"))).toEqual([null, null]);
+  });
+
+  it("full-reloads a sub-composition restore that changes the file's own root", () => {
+    const { iframe } = buildLiveIframe(host(""));
+    const reloadPreview = vi.fn();
+    const files = { [SUB]: { previous: sub("", ' data-width="10"'), restored: sub("") } };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
+  it("full-reloads a sub-composition restore whose file has a GSAP script", () => {
+    const { iframe, doc } = buildLiveIframe(host(`style="clip-path: inset(0px 40px 0px 0px);"`));
+    const reloadPreview = vi.fn();
+    const script = `<script>gsap.timeline().to("#target", { x: 10 });</script>`;
+    const scripted = (style: string) =>
+      sub(style).replace("</div></template>", `${script}</div></template>`);
+    const files = {
+      [SUB]: {
+        previous: scripted(`style="clip-path: inset(0px 40px 0px 0px)"`),
+        restored: scripted(""),
+      },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    expect(doc.querySelector('[data-hf-id="hf-t"]')?.getAttribute("style")).toContain("clip-path");
+  });
+
   it("full-reloads when the restore touches a sub-comp, not the active comp", () => {
     const { iframe } = buildLiveIframe(`<div id="a">t</div>`);
     const reloadPreview = vi.fn();