@hyperframes/studio 0.7.55 → 0.7.57

package/src/hooks/timelineEditingHelpers.ts

@@ -1,17 +1,20 @@
 import { type TimelineElement, usePlayerStore } from "../player/store/playerStore";
-import { applyPatchByTarget, readAttributeByTarget } from "../utils/sourcePatcher";
+import { applyPatchByTarget, findTagByTarget, readAttributeByTarget } from "../utils/sourcePatcher";
 import {
   formatTimelineAttributeNumber,
   type TimelineStackingReorderIntent,
 } from "../player/components/timelineEditing";
 import { getElementZIndex } from "../player/lib/layerOrdering";
-import { getTimelineElementIdentity } from "../player/lib/timelineElementHelpers";
-import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
-import { selectedKeyframePercentagesForElement } from "../utils/keyframeSelection";
-import type { EditHistoryKind } from "../utils/editHistory";
+import {
+  furthestClipEndFromSource,
+  getTimelineElementIdentity,
+} from "../player/lib/timelineElementHelpers";
+import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
 import type { TimelineZIndexReorderCommit } from "./useTimelineEditingTypes";
-import { extendRootDurationInSource } from "../utils/rootDuration";
-
+import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
+import { readFileContent } from "./timelineTimingSync";
+export { deleteSelectedKeyframes } from "./deleteSelectedKeyframes";
+export { readFileContent };
 function isHTMLElement(element: Element | null): element is HTMLElement {
   if (!element) return false;
   // Use the element's OWN realm's HTMLElement: timeline clips live in the preview
@@ -20,7 +23,6 @@ function isHTMLElement(element: Element | null): element is HTMLElement {
   const Ctor = element.ownerDocument?.defaultView?.HTMLElement ?? globalThis.HTMLElement;
   return element instanceof Ctor;
 }
-
 /**
  * Resolve a timeline vertical move to a z-index stacking reorder and commit it
  * through the shared layers-panel reorder path. Reads live sibling z-index from
@@ -38,13 +40,12 @@ export function applyTimelineStackingReorder(input: {
   iframe: HTMLIFrameElement | null;
   activeCompPath: string | null;
   commit: TimelineZIndexReorderCommit | null | undefined;
+  coalesceKey?: string;
 }): Promise<void> {
   // Audio has no visual stacking; a vertical drag on it must never write z-index.
   if (input.element.tag === "audio") return Promise.resolve();
-
   const intent = input.stackingReorder ?? null;
   if (intent == null || intent.zIndexChanges.length === 0) return Promise.resolve();
-
   // Resolve each change's live element from the change's OWN locator (the intent
   // is self-contained), falling back to the top-level element list. Sub-comp
   // children aren't in `timelineElements`, so a list-only lookup would miss them.
@@ -67,7 +68,6 @@ export function applyTimelineStackingReorder(input: {
     sourceFile: string;
     key: string;
   }> = [];
-
   for (const change of intent.zIndexChanges) {
     const sibling = siblingByKey.get(change.key);
     const domId = change.domId ?? sibling?.domId;
@@ -86,48 +86,17 @@ export function applyTimelineStackingReorder(input: {
       key: change.key,
     });
   }
-
   if (commitEntries.length === 0) return Promise.resolve();
-  return input.commit?.(commitEntries) ?? Promise.resolve();
-}
-
-/**
- * Remove the keyframes currently selected in the player store from the active
- * element's GSAP animation. Reads selection lazily so it stays correct when
- * invoked from a ref callback. Extracted from StudioApp to keep it under the
- * studio 600-LOC cap.
- */
-export function deleteSelectedKeyframes(session: {
-  selectedGsapAnimations: readonly { id: string; keyframes?: unknown }[];
-  handleGsapRemoveKeyframe: (animId: string, pct: number) => void;
-}): void {
-  const { selectedKeyframes, selectedElementId } = usePlayerStore.getState();
-  const animation = session.selectedGsapAnimations.find((anim) => anim.keyframes);
-  if (!animation) return;
-  // Only the active element's keyframes; a stale cross-element selection must not delete here.
-  for (const pct of selectedKeyframePercentagesForElement(selectedKeyframes, selectedElementId)) {
-    session.handleGsapRemoveKeyframe(animation.id, pct);
-  }
+  return input.commit?.(commitEntries, input.coalesceKey) ?? Promise.resolve();
 }
-
 export function extendRootDurationIfNeeded(newEnd: number): boolean {
   const store = usePlayerStore.getState();
   if (newEnd <= store.duration) return false;
   store.setDuration(newEnd);
   return true;
 }
-
 // ── Types ──
-
-export interface RecordEditInput {
-  label: string;
-  kind: EditHistoryKind;
-  coalesceKey?: string;
-  /** Per-entry coalesce window override (ms); lets a slow follow-up still merge. */
-  coalesceMs?: number;
-  files: Record<string, { before: string; after: string }>;
-}
-
+export type { RecordEditInput } from "../utils/studioFileHistory";
 export function buildPatchTarget(element: {
   domId?: string;
   hfId?: string;
@@ -150,9 +119,7 @@ export function buildPatchTarget(element: {
   }
   return null;
 }
-
 export type PatchTarget = NonNullable<ReturnType<typeof buildPatchTarget>>;
-
 // The runtime re-reads data-start/data-duration from the DOM on each sync tick
 // (packages/core/src/runtime/init.ts:1324-1368), so attribute mutations here are
 // picked up automatically on the next frame without a rebind call.
@@ -172,7 +139,6 @@ export function findTimelineElementInIframe(
     return null;
   }
 }
-
 export function patchIframeDomTiming(
   iframe: HTMLIFrameElement | null,
   element: TimelineElement,
@@ -186,24 +152,6 @@ export function patchIframeDomTiming(
     // Cross-origin or mid-navigation — file save is enqueued; iframe patch is best-effort.
   }
 }
-
-function postRootDurationToPreview(
-  iframe: HTMLIFrameElement | null,
-  durationSeconds: number,
-): void {
-  const duration = Number(durationSeconds);
-  if (!Number.isFinite(duration) || duration <= 0) return;
-  iframe?.contentWindow?.postMessage(
-    {
-      source: "hf-parent",
-      type: "control",
-      action: "set-root-duration",
-      durationSeconds: duration,
-    },
-    "*",
-  );
-}
-
 // fallow-ignore-next-line complexity
 function resolveResizePlaybackStart(
   original: string,
@@ -236,13 +184,32 @@ export function buildTimelineMoveTimingPatch(
   target: PatchTarget,
   start: number,
   duration: number,
+  track?: number,
 ): string {
-  const patched = applyPatchByTarget(original, target, {
+  if (!Number.isFinite(start) || !Number.isFinite(duration)) {
+    console.warn(
+      `[Timeline] buildTimelineMoveTimingPatch: non-finite timing (start=${start}, duration=${duration}) — patch skipped`,
+    );
+    return original;
+  }
+  let patched = applyPatchByTarget(original, target, {
     type: "attribute",
     property: "start",
     value: formatTimelineAttributeNumber(start),
   });
-  return extendRootDurationInSource(patched, start + duration);
+  if (track != null && Number.isFinite(track)) {
+    patched = applyPatchByTarget(patched, target, {
+      type: "attribute",
+      property: "track-index",
+      value: formatTimelineAttributeNumber(track),
+    });
+  }
+  // Content-driven duration: sync data-duration to the furthest clip end read
+  // from the PATCHED SOURCE (raw data-duration), so it grows if a clip moved
+  // past the end and shrinks if the furthest clip moved left. Measured from the
+  // source, NOT the store — store durations are runtime-truncated to the current
+  // comp length, which would ratchet the duration down every move.
+  return setCompositionDurationToContent(patched, furthestClipEndFromSource(patched));
 }
 
 export function buildTimelineResizeTimingPatch(
@@ -269,7 +236,10 @@ export function buildTimelineResizeTimingPatch(
       value: formatTimelineAttributeNumber(pbs.value),
     });
   }
-  return extendRootDurationInSource(patched, updates.start + updates.duration);
+  // Content-driven duration from the PATCHED SOURCE (raw data-duration) —
+  // grows/shrinks to the furthest clip end. Not from the store, whose
+  // durations are runtime-truncated.
+  return setCompositionDurationToContent(patched, furthestClipEndFromSource(patched));
 }
 
 export interface PersistTimelineEditInput {
@@ -349,13 +319,24 @@ export async function persistTimelineBatchEdit(
     }
 
     const current = patchedByPath.get(targetPath) ?? original;
-    const patched = change.buildPatches(current, patchTarget);
-    if (patched === current) {
+    // Resolve the target FIRST: byte-identical output below is only a legit
+    // no-op when the member actually resolved in the source. A mistargeted
+    // member (stale id/selector) must fail loudly like the single-edit path,
+    // not be silently dropped as "already at target".
+    if (!findTagByTarget(current, patchTarget)) {
       throw new Error(`Unable to patch timeline element ${change.element.id} in ${targetPath}`);
     }
+    const patched = change.buildPatches(current, patchTarget);
+    // The target resolved, so a member whose attributes already hold the target
+    // values patches to the identical string — e.g. a track-insert renumber
+    // where one clip's lane is already correct. That is a legitimate no-op:
+    // skip it instead of aborting (and rolling back) the whole batch.
+    if (patched === current) continue;
     patchedByPath.set(targetPath, patched);
   }
 
+  if (patchedByPath.size === 0) return;
+
   const files = Object.fromEntries(patchedByPath);
   for (const targetPath of Object.keys(files)) {
     input.pendingTimelineEditPathRef.current.add(targetPath);
@@ -374,226 +355,6 @@ export async function persistTimelineBatchEdit(
   input.domEditSaveTimestampRef.current = Date.now();
 }
 
-export async function readFileContent(projectId: string, targetPath: string): Promise<string> {
-  if (targetPath.includes("\0") || targetPath.includes("..")) {
-    throw new Error(`Unsafe path: ${targetPath}`);
-  }
-  const response = await fetch(
-    `/api/projects/${projectId}/files/${encodeURIComponent(targetPath)}`,
-  );
-  if (!response.ok) {
-    throw new Error(`Failed to read ${targetPath}`);
-  }
-  const data = (await response.json()) as { content?: string };
-  if (typeof data.content !== "string") {
-    throw new Error(`Missing file contents for ${targetPath}`);
-  }
-  return data.content;
-}
-
-export type GsapMutationStatus = { mutated: boolean };
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-function readMutationStatus(value: unknown): GsapMutationStatus {
-  if (!isRecord(value)) return { mutated: false };
-  return { mutated: value.mutated === true || value.changed === true };
-}
-
-function readMutationError(value: unknown, fallback: string): string {
-  if (isRecord(value) && typeof value.error === "string") return value.error;
-  return fallback;
-}
-
-export async function finishTimelineTimingFallback(input: {
-  iframe: HTMLIFrameElement | null;
-  needsExtension: boolean;
-  rootDurationSeconds: number;
-  reloadPreview: () => void;
-  gsapMutation?: () => Promise<GsapMutationStatus>;
-  onGsapError: (error: unknown) => void;
-}): Promise<void> {
-  let gsapMutated = false;
-  if (input.gsapMutation) {
-    try {
-      gsapMutated = (await input.gsapMutation()).mutated;
-    } catch (error) {
-      input.onGsapError(error);
-      return;
-    }
-  }
-  if (input.needsExtension) {
-    postRootDurationToPreview(input.iframe, input.rootDurationSeconds);
-    if (gsapMutated) input.reloadPreview();
-    return;
-  }
-  input.reloadPreview();
-}
-
-// Coalesce window for folding a GSAP mutation into the preceding timing edit; only has to
-// outlast one GSAP server round-trip, never a real second edit.
-const GSAP_HISTORY_COALESCE_MS = 10_000;
-
-/**
- * A server GSAP rewrite mutates the same file the timing patch just wrote, but AFTER the
- * timing edit was recorded, leaving the recorded `after` stale so an undo hits a hash
- * conflict. This snapshots every touched file, runs the mutation, then records a follow-up
- * edit under the same coalesceKey with a window wide enough to survive the GSAP round-trip,
- * folding both writes into one undo step. Returns the mutation status for caller reloads.
- */
-export async function foldGsapMutationIntoHistory(input: {
-  projectId: string;
-  paths: string[];
-  label: string;
-  coalesceKey?: string;
-  recordEdit: (edit: RecordEditInput) => Promise<void>;
-  gsapMutation: () => Promise<GsapMutationStatus>;
-}): Promise<GsapMutationStatus> {
-  const uniquePaths = [...new Set(input.paths)];
-  const before = new Map<string, string>();
-  for (const path of uniquePaths) {
-    before.set(path, await readFileContent(input.projectId, path));
-  }
-  const status = await input.gsapMutation();
-  if (status.mutated) {
-    const files: Record<string, { before: string; after: string }> = {};
-    for (const path of uniquePaths) {
-      const priorContent = before.get(path);
-      const finalContent = await readFileContent(input.projectId, path);
-      if (priorContent !== undefined && finalContent !== priorContent) {
-        files[path] = { before: priorContent, after: finalContent };
-      }
-    }
-    if (Object.keys(files).length > 0) {
-      await input.recordEdit({
-        label: input.label,
-        kind: "timeline",
-        coalesceKey: input.coalesceKey,
-        coalesceMs: GSAP_HISTORY_COALESCE_MS,
-        files,
-      });
-    }
-  }
-  return status;
-}
-
-/**
- * Shift all GSAP animation positions targeting a given element by a time delta.
- * Calls the server-side GSAP mutation endpoint which uses the AST-based parser.
- */
-export async function shiftGsapPositions(
-  projectId: string,
-  filePath: string,
-  elementId: string,
-  delta: number,
-): Promise<GsapMutationStatus> {
-  if (delta === 0 || !elementId) return { mutated: false };
-  const res = await fetch(
-    `/api/projects/${projectId}/gsap-mutations/${encodeURIComponent(filePath)}`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        type: "shift-positions",
-        targetSelector: `#${elementId}`,
-        delta,
-      }),
-    },
-  );
-  if (!res.ok) {
-    const err = await res.json().catch(() => null);
-    throw new Error(readMutationError(err, "shift-positions failed"));
-  }
-  return readMutationStatus(await res.json().catch(() => null));
-}
-
-export async function scaleGsapPositions(
-  projectId: string,
-  filePath: string,
-  elementId: string,
-  oldStart: number,
-  oldDuration: number,
-  newStart: number,
-  newDuration: number,
-): Promise<GsapMutationStatus> {
-  if (!elementId || oldDuration <= 0 || newDuration <= 0) return { mutated: false };
-  if (oldStart === newStart && oldDuration === newDuration) return { mutated: false };
-  const res = await fetch(
-    `/api/projects/${projectId}/gsap-mutations/${encodeURIComponent(filePath)}`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        type: "scale-positions",
-        targetSelector: `#${elementId}`,
-        oldStart,
-        oldDuration,
-        newStart,
-        newDuration,
-      }),
-    },
-  );
-  if (!res.ok) {
-    const err = await res.json().catch(() => null);
-    throw new Error(readMutationError(err, "scale-positions failed"));
-  }
-  return readMutationStatus(await res.json().catch(() => null));
-}
-
-/** Single-clip move GSAP shift, folded into the timing edit's history entry (see above). */
-export function foldedShiftGsapMutation(input: {
-  projectId: string;
-  targetPath: string;
-  domId: string;
-  delta: number;
-  label: string;
-  coalesceKey?: string;
-  recordEdit: (edit: RecordEditInput) => Promise<void>;
-}): () => Promise<GsapMutationStatus> {
-  return () =>
-    foldGsapMutationIntoHistory({
-      projectId: input.projectId,
-      paths: [input.targetPath],
-      label: input.label,
-      coalesceKey: input.coalesceKey,
-      recordEdit: input.recordEdit,
-      gsapMutation: () =>
-        shiftGsapPositions(input.projectId, input.targetPath, input.domId, input.delta),
-    });
-}
-
-/** Single-clip resize GSAP scale, folded into the timing edit's history entry (see above). */
-export function foldedScaleGsapMutation(input: {
-  projectId: string;
-  targetPath: string;
-  domId: string;
-  from: { start: number; duration: number };
-  to: { start: number; duration: number };
-  label: string;
-  coalesceKey?: string;
-  recordEdit: (edit: RecordEditInput) => Promise<void>;
-}): () => Promise<GsapMutationStatus> {
-  return () =>
-    foldGsapMutationIntoHistory({
-      projectId: input.projectId,
-      paths: [input.targetPath],
-      label: input.label,
-      coalesceKey: input.coalesceKey,
-      recordEdit: input.recordEdit,
-      gsapMutation: () =>
-        scaleGsapPositions(
-          input.projectId,
-          input.targetPath,
-          input.domId,
-          input.from.start,
-          input.from.duration,
-          input.to.start,
-          input.to.duration,
-        ),
-    });
-}
-
-// Re-export applyPatchByTarget for use in the hook (avoids double import in callers)
 export { applyPatchByTarget, formatTimelineAttributeNumber };
+
+export { patchDocumentRootDuration } from "./timelineEditingGsap";

package/src/hooks/timelineMoveAdapter.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../player";
+import { persistTimelineMoveEditsAtomically } from "./timelineMoveAdapter";
+
+type MoveArgs = Parameters<typeof persistTimelineMoveEditsAtomically>;
+
+const element = (id: string, track: number): TimelineElement => ({
+  id,
+  key: id,
+  tag: "div",
+  start: 0,
+  duration: 2,
+  track,
+});
+
+const twoLaneEdits = (bTrack: number): MoveArgs[0] => [
+  { element: element("a", 0), updates: { start: 1, track: 1 } },
+  { element: element("b", bTrack), updates: { start: 3, track: 2 } },
+];
+
+const movedPair = (edits: MoveArgs[0]) => [
+  { element: edits[0].element, start: 1, track: 1 },
+  { element: edits[1].element, start: 3, track: 2 },
+];
+
+const runMove = async (edits: MoveArgs[0], coalesceKey: MoveArgs[1], intent: MoveArgs[2]) => {
+  const handleTimelineGroupMove = vi.fn().mockResolvedValue(undefined);
+  await persistTimelineMoveEditsAtomically(edits, coalesceKey, intent, {
+    handleTimelineGroupMove,
+  });
+  return handleTimelineGroupMove;
+};
+
+describe("persistTimelineMoveEditsAtomically", () => {
+  it("persists two vertical edits as one group with the gesture coalesce key", async () => {
+    const edits = twoLaneEdits(1);
+    const handleTimelineGroupMove = await runMove(edits, "clip-lane-move:7", "track-insert");
+    expect(handleTimelineGroupMove).toHaveBeenCalledTimes(1);
+    expect(handleTimelineGroupMove).toHaveBeenCalledWith(movedPair(edits), {
+      coalesceKey: "clip-lane-move:7",
+    });
+  });
+
+  it("omits track attrs for plain timing moves (keeps the SDK fast path eligible)", async () => {
+    const edit = { element: element("a", 0), updates: { start: 1, track: 0 } };
+    const handleTimelineGroupMove = await runMove([edit], undefined, "timing");
+    expect(handleTimelineGroupMove).toHaveBeenCalledWith([{ element: edit.element, start: 1 }], {
+      coalesceKey: undefined,
+    });
+  });
+
+  it("persists the track attr for a single lane reorder (stable track lanes)", async () => {
+    // Lane = authored data-track-index; a vertical move that never hits disk
+    // snaps back on the next normalize, so the lane change MUST persist.
+    const edit = { element: element("a", 0), updates: { start: 1, track: 1 } };
+    const handleTimelineGroupMove = await runMove([edit], "clip-lane-move:7", "lane-reorder");
+    expect(handleTimelineGroupMove).toHaveBeenCalledWith(
+      [{ element: edit.element, start: 1, track: 1 }],
+      { coalesceKey: "clip-lane-move:7" },
+    );
+  });
+
+  it("persists track attrs for a multi-selection lane drag (stable track lanes)", async () => {
+    const edits = twoLaneEdits(2);
+    const handleTimelineGroupMove = await runMove(edits, "clip-lane-move:7", "lane-reorder");
+    expect(handleTimelineGroupMove).toHaveBeenCalledWith(movedPair(edits), {
+      coalesceKey: "clip-lane-move:7",
+    });
+  });
+
+  it("rejects without retrying individual members when the atomic batch fails", async () => {
+    const failure = new Error("batch failed");
+    const handleTimelineGroupMove = vi.fn().mockRejectedValue(failure);
+    await expect(
+      persistTimelineMoveEditsAtomically(twoLaneEdits(1), "clip-lane-move:7", "track-insert", {
+        handleTimelineGroupMove,
+      }),
+    ).rejects.toBe(failure);
+    expect(handleTimelineGroupMove).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/timelineMoveAdapter.ts

@@ -0,0 +1,39 @@
+import type { TimelineElement } from "../player";
+import type {
+  TimelineGroupCommitOptions,
+  TimelineGroupMoveChange,
+} from "./useTimelineGroupEditing";
+
+interface MoveEdit {
+  element: TimelineElement;
+  updates: Pick<TimelineElement, "start" | "track">;
+}
+
+interface AtomicMoveDeps {
+  handleTimelineGroupMove: (
+    changes: TimelineGroupMoveChange[],
+    options?: TimelineGroupCommitOptions,
+  ) => Promise<void>;
+}
+
+export type TimelineMoveOperation = "timing" | "lane-reorder" | "track-insert";
+
+export function persistTimelineMoveEditsAtomically(
+  edits: MoveEdit[],
+  coalesceKey: string | undefined,
+  operation: TimelineMoveOperation,
+  deps: AtomicMoveDeps,
+): Promise<void> {
+  return deps.handleTimelineGroupMove(
+    edits.map(({ element, updates }) => ({
+      element,
+      start: updates.start,
+      // Stable track lanes: a lane is the authored data-track-index, so every
+      // vertical gesture (lane-reorder AND track-insert) must persist the track;
+      // z is paint order only and is synced separately. Plain horizontal moves
+      // ("timing") omit it so they stay eligible for the SDK fast path.
+      track: operation === "timing" ? undefined : updates.track,
+    })),
+    { coalesceKey },
+  );
+}