@hyperframes/studio 0.7.46 → 0.7.47

package/src/hooks/useTimelineGroupEditing.ts

@@ -0,0 +1,370 @@
+import { useCallback, type MutableRefObject, type RefObject } from "react";
+import type { Composition } from "@hyperframes/sdk";
+import type { TimelineElement } from "../player";
+import { sdkTimingBatchPersist } from "../utils/sdkCutover";
+import {
+  buildTimelineMoveTimingPatch,
+  buildTimelineResizeTimingPatch,
+  extendRootDurationIfNeeded,
+  finishTimelineTimingFallback,
+  foldGsapMutationIntoHistory,
+  formatTimelineAttributeNumber,
+  patchIframeDomTiming,
+  persistTimelineBatchEdit,
+  readFileContent,
+  scaleGsapPositions,
+  shiftGsapPositions,
+  type PersistTimelineBatchChange,
+  type RecordEditInput,
+} from "./timelineEditingHelpers";
+
+export interface TimelineGroupMoveChange {
+  element: TimelineElement;
+  start: number;
+}
+
+export interface TimelineGroupResizeChange {
+  element: TimelineElement;
+  start: number;
+  duration: number;
+  playbackStart?: number;
+}
+
+export interface TimelineGroupCommitOptions {
+  beforeTiming?: Promise<void>;
+  coalesceKey?: string;
+}
+
+interface UseTimelineGroupEditingOptions {
+  activeCompPath: string | null;
+  domEditSaveTimestampRef: MutableRefObject<number>;
+  editQueueRef: MutableRefObject<Promise<unknown>>;
+  forceReloadSdkSession?: () => void;
+  isRecordingRef?: RefObject<boolean>;
+  pendingTimelineEditPathRef: MutableRefObject<Set<string>>;
+  previewIframeRef: RefObject<HTMLIFrameElement | null>;
+  projectIdRef: MutableRefObject<string | null>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  reloadPreview: () => void;
+  sdkSession?: Composition | null;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+}
+
+function targetPathFor(element: TimelineElement, activeCompPath: string | null): string {
+  return element.sourceFile || activeCompPath || "index.html";
+}
+
+function allChangesSharePath(
+  changes: readonly { element: TimelineElement }[],
+  activeCompPath: string | null,
+): string | null {
+  const firstPath = changes[0] ? targetPathFor(changes[0].element, activeCompPath) : null;
+  if (!firstPath) return null;
+  return changes.every((change) => targetPathFor(change.element, activeCompPath) === firstPath)
+    ? firstPath
+    : null;
+}
+
+function moveCoalesceKey(changes: readonly TimelineGroupMoveChange[]): string {
+  return `timeline-group-move:${changes.map((change) => change.element.hfId ?? change.element.id).join(",")}`;
+}
+
+function resizeCoalesceKey(changes: readonly TimelineGroupResizeChange[]): string {
+  return `timeline-group-resize:${changes.map((change) => change.element.hfId ?? change.element.id).join(",")}`;
+}
+
+function resizeHasPlaybackStartAdjustment(change: TimelineGroupResizeChange): boolean {
+  return (
+    change.playbackStart != null ||
+    (change.start !== change.element.start && change.element.playbackStart != null)
+  );
+}
+
+export function useTimelineGroupEditing({
+  activeCompPath,
+  domEditSaveTimestampRef,
+  editQueueRef,
+  forceReloadSdkSession,
+  isRecordingRef,
+  pendingTimelineEditPathRef,
+  previewIframeRef,
+  projectIdRef,
+  recordEdit,
+  reloadPreview,
+  sdkSession,
+  showToast,
+  writeProjectFile,
+}: UseTimelineGroupEditingOptions) {
+  const enqueueGroupOperation = useCallback(
+    (label: string, operation: (projectId: string) => Promise<void>): Promise<void> => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return Promise.reject(new Error(`${label}: blocked while recording`));
+      }
+      const projectId = projectIdRef.current;
+      if (!projectId) return Promise.reject(new Error(`${label}: no active project`));
+      const run = editQueueRef.current.then(() => operation(projectId));
+      // Keep the shared edit queue from wedging on a rejection, but return the raw
+      // (rejecting) promise so the gesture owner can roll back on a real failure.
+      editQueueRef.current = run.then(
+        () => undefined,
+        (error) => {
+          console.error(`[Timeline] Failed to persist: ${label}`, error);
+        },
+      );
+      return run;
+    },
+    [editQueueRef, isRecordingRef, projectIdRef, showToast],
+  );
+
+  const persistServerBatch = useCallback(
+    async (
+      projectId: string,
+      label: string,
+      batchChanges: PersistTimelineBatchChange[],
+      coalesceKey: string,
+    ) => {
+      await persistTimelineBatchEdit({
+        projectId,
+        activeCompPath,
+        label,
+        changes: batchChanges,
+        writeProjectFile,
+        recordEdit,
+        domEditSaveTimestampRef,
+        pendingTimelineEditPathRef,
+        coalesceKey,
+      });
+      forceReloadSdkSession?.();
+    },
+    [
+      activeCompPath,
+      domEditSaveTimestampRef,
+      forceReloadSdkSession,
+      pendingTimelineEditPathRef,
+      recordEdit,
+      writeProjectFile,
+    ],
+  );
+
+  const handleTimelineGroupMove = useCallback(
+    (changes: TimelineGroupMoveChange[], options?: TimelineGroupCommitOptions) => {
+      if (changes.length === 0) return Promise.resolve();
+      for (const change of changes) {
+        patchIframeDomTiming(previewIframeRef.current, change.element, [
+          ["data-start", formatTimelineAttributeNumber(change.start)],
+        ]);
+      }
+
+      const maxEnd = Math.max(...changes.map((change) => change.start + change.element.duration));
+      const needsExtension = extendRootDurationIfNeeded(maxEnd);
+      const coalesceKey = options?.coalesceKey ?? moveCoalesceKey(changes);
+      return enqueueGroupOperation("Move timeline clips", async (projectId) => {
+        await options?.beforeTiming;
+        const sharedPath = allChangesSharePath(changes, activeCompPath);
+        const sdkChanges = changes.map((change) =>
+          change.element.hfId
+            ? { hfId: change.element.hfId, timingUpdate: { start: change.start } }
+            : null,
+        );
+        const canUseSdk =
+          !needsExtension && sharedPath !== null && sdkChanges.every((change) => change !== null);
+        if (canUseSdk) {
+          const handled = await sdkTimingBatchPersist(
+            sdkChanges.filter((change): change is NonNullable<typeof change> => change !== null),
+            sharedPath,
+            sdkSession,
+            {
+              editHistory: { recordEdit },
+              writeProjectFile,
+              reloadPreview,
+              domEditSaveTimestampRef,
+              compositionPath: activeCompPath,
+              readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
+            },
+            { label: "Move timeline clips", coalesceKey },
+          );
+          if (handled) return;
+        }
+
+        await persistServerBatch(
+          projectId,
+          "Move timeline clips",
+          changes.map((change) => ({
+            element: change.element,
+            buildPatches: (original, target) =>
+              buildTimelineMoveTimingPatch(original, target, change.start, change.element.duration),
+          })),
+          coalesceKey,
+        );
+        await finishTimelineTimingFallback({
+          iframe: previewIframeRef.current,
+          needsExtension,
+          rootDurationSeconds: maxEnd,
+          reloadPreview,
+          gsapMutation: () =>
+            foldGsapMutationIntoHistory({
+              projectId,
+              paths: changes.map((change) => targetPathFor(change.element, activeCompPath)),
+              label: "Move timeline clips",
+              coalesceKey,
+              recordEdit,
+              gsapMutation: async () => {
+                let mutated = false;
+                for (const change of changes) {
+                  const delta = change.start - change.element.start;
+                  const domId = change.element.domId;
+                  if (delta === 0 || !domId) continue;
+                  const status = await shiftGsapPositions(
+                    projectId,
+                    targetPathFor(change.element, activeCompPath),
+                    domId,
+                    delta,
+                  );
+                  mutated = mutated || status.mutated;
+                }
+                return { mutated };
+              },
+            }),
+          onGsapError: (err) => console.error("[Timeline] Failed to shift GSAP positions", err),
+        });
+      });
+    },
+    [
+      activeCompPath,
+      domEditSaveTimestampRef,
+      enqueueGroupOperation,
+      persistServerBatch,
+      previewIframeRef,
+      projectIdRef,
+      recordEdit,
+      reloadPreview,
+      sdkSession,
+      writeProjectFile,
+    ],
+  );
+
+  const handleTimelineGroupResize = useCallback(
+    (changes: TimelineGroupResizeChange[], options?: TimelineGroupCommitOptions) => {
+      if (changes.length === 0) return Promise.resolve();
+      for (const change of changes) {
+        const liveAttrs: Array<[string, string]> = [
+          ["data-start", formatTimelineAttributeNumber(change.start)],
+          ["data-duration", formatTimelineAttributeNumber(change.duration)],
+        ];
+        if (change.playbackStart != null) {
+          const liveAttr =
+            change.element.playbackStartAttr === "playback-start"
+              ? "data-playback-start"
+              : "data-media-start";
+          liveAttrs.push([liveAttr, formatTimelineAttributeNumber(change.playbackStart)]);
+        }
+        patchIframeDomTiming(previewIframeRef.current, change.element, liveAttrs);
+      }
+
+      const maxEnd = Math.max(...changes.map((change) => change.start + change.duration));
+      const needsExtension = extendRootDurationIfNeeded(maxEnd);
+      const coalesceKey = options?.coalesceKey ?? resizeCoalesceKey(changes);
+      return enqueueGroupOperation("Resize timeline clips", async (projectId) => {
+        await options?.beforeTiming;
+        const sharedPath = allChangesSharePath(changes, activeCompPath);
+        const sdkChanges = changes.map((change) =>
+          change.element.hfId
+            ? {
+                hfId: change.element.hfId,
+                timingUpdate: { start: change.start, duration: change.duration },
+              }
+            : null,
+        );
+        const canUseSdk =
+          !needsExtension &&
+          sharedPath !== null &&
+          changes.every((change) => !resizeHasPlaybackStartAdjustment(change)) &&
+          sdkChanges.every((change) => change !== null);
+        if (canUseSdk) {
+          const handled = await sdkTimingBatchPersist(
+            sdkChanges.filter((change): change is NonNullable<typeof change> => change !== null),
+            sharedPath,
+            sdkSession,
+            {
+              editHistory: { recordEdit },
+              writeProjectFile,
+              reloadPreview,
+              domEditSaveTimestampRef,
+              compositionPath: activeCompPath,
+              readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
+            },
+            { label: "Resize timeline clips", coalesceKey },
+          );
+          if (handled) return;
+        }
+
+        await persistServerBatch(
+          projectId,
+          "Resize timeline clips",
+          changes.map((change) => ({
+            element: change.element,
+            buildPatches: (original, target) =>
+              buildTimelineResizeTimingPatch(original, target, change.element, {
+                start: change.start,
+                duration: change.duration,
+                playbackStart: change.playbackStart,
+              }),
+          })),
+          coalesceKey,
+        );
+        await finishTimelineTimingFallback({
+          iframe: previewIframeRef.current,
+          needsExtension,
+          rootDurationSeconds: maxEnd,
+          reloadPreview,
+          gsapMutation: () =>
+            foldGsapMutationIntoHistory({
+              projectId,
+              paths: changes.map((change) => targetPathFor(change.element, activeCompPath)),
+              label: "Resize timeline clips",
+              coalesceKey,
+              recordEdit,
+              gsapMutation: async () => {
+                let mutated = false;
+                for (const change of changes) {
+                  const domId = change.element.domId;
+                  const timingChanged =
+                    change.start !== change.element.start ||
+                    change.duration !== change.element.duration;
+                  if (!timingChanged || !domId) continue;
+                  const status = await scaleGsapPositions(
+                    projectId,
+                    targetPathFor(change.element, activeCompPath),
+                    domId,
+                    change.element.start,
+                    change.element.duration,
+                    change.start,
+                    change.duration,
+                  );
+                  mutated = mutated || status.mutated;
+                }
+                return { mutated };
+              },
+            }),
+          onGsapError: (err) => console.error("[Timeline] Failed to scale GSAP positions", err),
+        });
+      });
+    },
+    [
+      activeCompPath,
+      domEditSaveTimestampRef,
+      enqueueGroupOperation,
+      persistServerBatch,
+      previewIframeRef,
+      projectIdRef,
+      recordEdit,
+      reloadPreview,
+      sdkSession,
+      writeProjectFile,
+    ],
+  );
+
+  return { handleTimelineGroupMove, handleTimelineGroupResize };
+}

package/src/hooks/useTimelineSelectionPreviewSync.test.tsx

@@ -0,0 +1,129 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../player";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { installReactActEnvironment, makeSelection } from "./domSelectionTestHarness";
+import { useTimelineSelectionPreviewSync } from "./useTimelineSelectionPreviewSync";
+
+installReactActEnvironment();
+
+interface HarnessProps {
+  selectedElementId: string | null;
+  selectedElementIds: Set<string>;
+  timelineElements: TimelineElement[];
+  domEditSelection: DomEditSelection | null;
+  domEditGroupSelections: DomEditSelection[];
+  buildDomSelectionForTimelineElement: (
+    element: TimelineElement,
+  ) => Promise<DomEditSelection | null>;
+  applyDomSelection: (
+    selection: DomEditSelection | null,
+    options?: { revealPanel?: boolean; additive?: boolean; preserveGroup?: boolean },
+  ) => void;
+  applyMarqueeSelection: (selections: DomEditSelection[], additive: boolean) => void;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+function renderHarness() {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+
+  function Harness(nextProps: HarnessProps) {
+    useTimelineSelectionPreviewSync({
+      ...nextProps,
+      activeCompPath: "index.html",
+    });
+    return null;
+  }
+
+  const rerender = async (nextProps: HarnessProps) => {
+    await act(async () => {
+      root.render(React.createElement(Harness, nextProps));
+      await Promise.resolve();
+    });
+  };
+
+  return {
+    rerender,
+    cleanup: () => {
+      act(() => root.unmount());
+      host.remove();
+    },
+  };
+}
+
+function makeSyncFixture() {
+  const firstElement = document.createElement("div");
+  firstElement.id = "clip-1";
+  const secondElement = document.createElement("div");
+  secondElement.id = "clip-2";
+  const firstSelection = makeSelection("First", firstElement);
+  const secondSelection = makeSelection("Second", secondElement);
+  const timelineElements: TimelineElement[] = [
+    { id: "clip-1", tag: "div", start: 0, duration: 1, track: 0 },
+    { id: "clip-2", tag: "div", start: 1, duration: 1, track: 1 },
+  ];
+  const selectionById = new Map([
+    ["clip-1", firstSelection],
+    ["clip-2", secondSelection],
+  ]);
+  return { firstSelection, secondSelection, timelineElements, selectionById };
+}
+
+describe("useTimelineSelectionPreviewSync", () => {
+  it("syncs a multi-id timeline selection into preview group selections", async () => {
+    const { firstSelection, secondSelection, timelineElements, selectionById } = makeSyncFixture();
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const buildDomSelectionForTimelineElement = vi.fn(async (element: TimelineElement) => {
+      return selectionById.get(element.id) ?? null;
+    });
+    const harness = renderHarness();
+
+    await harness.rerender({
+      selectedElementId: "clip-2",
+      selectedElementIds: new Set(["clip-1", "clip-2"]),
+      timelineElements,
+      domEditSelection: null,
+      domEditGroupSelections: [],
+      buildDomSelectionForTimelineElement,
+      applyDomSelection,
+      applyMarqueeSelection,
+    });
+
+    expect(applyMarqueeSelection).toHaveBeenCalledWith([secondSelection, firstSelection], false);
+    expect(applyDomSelection).not.toHaveBeenCalled();
+    harness.cleanup();
+  });
+
+  it("clears preview selection when the timeline selection set is empty", async () => {
+    const { firstSelection, timelineElements, selectionById } = makeSyncFixture();
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const harness = renderHarness();
+
+    await harness.rerender({
+      selectedElementId: null,
+      selectedElementIds: new Set(),
+      timelineElements,
+      domEditSelection: firstSelection,
+      domEditGroupSelections: [firstSelection],
+      buildDomSelectionForTimelineElement: vi.fn(async (element: TimelineElement) => {
+        return selectionById.get(element.id) ?? null;
+      }),
+      applyDomSelection,
+      applyMarqueeSelection,
+    });
+
+    expect(applyDomSelection).toHaveBeenCalledWith(null, { revealPanel: false });
+    expect(applyMarqueeSelection).not.toHaveBeenCalled();
+    harness.cleanup();
+  });
+});

package/src/hooks/useTimelineSelectionPreviewSync.ts

@@ -0,0 +1,130 @@
+import { useEffect, useMemo } from "react";
+import type { TimelineElement } from "../player";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { resolveTimelineIdForSelection } from "../utils/studioHelpers";
+
+interface UseTimelineSelectionPreviewSyncParams {
+  selectedElementId: string | null;
+  selectedElementIds: Set<string>;
+  timelineElements: TimelineElement[];
+  domEditSelection: DomEditSelection | null;
+  domEditGroupSelections: DomEditSelection[];
+  activeCompPath: string | null;
+  buildDomSelectionForTimelineElement: (
+    element: TimelineElement,
+  ) => Promise<DomEditSelection | null>;
+  applyDomSelection: (
+    selection: DomEditSelection | null,
+    options?: { revealPanel?: boolean; additive?: boolean; preserveGroup?: boolean },
+  ) => void;
+  applyMarqueeSelection: (selections: DomEditSelection[], additive: boolean) => void;
+}
+
+function orderSelectedIds(ids: Set<string>, anchor: string | null): string[] {
+  const ordered = [...ids];
+  if (!anchor || !ids.has(anchor)) return ordered;
+  return [anchor, ...ordered.filter((id) => id !== anchor)];
+}
+
+function selectionIdsMatch(
+  currentIds: string[],
+  selectedIds: string[],
+  currentAnchor: string | null,
+  wantedAnchor: string | null,
+): boolean {
+  // Compare as sets in BOTH directions: length equality misreads duplicates (two DOM
+  // children resolving to the same clip id) as a full match and skips mirroring the
+  // members that never made it into the preview.
+  const current = new Set(currentIds);
+  const selected = new Set(selectedIds);
+  if (current.size !== selected.size) return false;
+  for (const id of selected) {
+    if (!current.has(id)) return false;
+  }
+  // The primary/anchor must also agree, or a change of just the anchor within the
+  // same set would never re-sync the preview's primary selection.
+  return currentAnchor === wantedAnchor;
+}
+
+export function useTimelineSelectionPreviewSync({
+  selectedElementId,
+  selectedElementIds,
+  timelineElements,
+  domEditSelection,
+  domEditGroupSelections,
+  activeCompPath,
+  buildDomSelectionForTimelineElement,
+  applyDomSelection,
+  applyMarqueeSelection,
+}: UseTimelineSelectionPreviewSyncParams): void {
+  const selectedIds = useMemo(
+    () => orderSelectedIds(selectedElementIds, selectedElementId),
+    [selectedElementId, selectedElementIds],
+  );
+  const selectedKey = selectedIds.join("\0");
+
+  useEffect(() => {
+    const currentSelections =
+      domEditGroupSelections.length > 1
+        ? domEditGroupSelections
+        : domEditSelection
+          ? [domEditSelection]
+          : [];
+    const currentIds = currentSelections
+      .map((selection) =>
+        resolveTimelineIdForSelection(selection, timelineElements, activeCompPath),
+      )
+      .filter((id): id is string => Boolean(id));
+    const currentAnchor = domEditSelection
+      ? resolveTimelineIdForSelection(domEditSelection, timelineElements, activeCompPath)
+      : null;
+
+    if (selectedIds.length === 0) {
+      if (currentSelections.length > 0) applyDomSelection(null, { revealPanel: false });
+      return;
+    }
+    if (selectionIdsMatch(currentIds, selectedIds, currentAnchor, selectedElementId)) return;
+
+    let cancelled = false;
+    const syncSelection = async () => {
+      const selections: DomEditSelection[] = [];
+      let resolvableCount = 0;
+      for (const id of selectedIds) {
+        const element = timelineElements.find((item) => (item.key ?? item.id) === id);
+        if (!element) continue;
+        resolvableCount += 1;
+        const selection = await buildDomSelectionForTimelineElement(element);
+        if (selection) selections.push(selection);
+      }
+      if (cancelled) return;
+      // The store is the source of truth: applying a partial set would write that
+      // shrunk set back and silently drop the members whose DOM node was not ready.
+      // Bail instead; a later effect run (on timelineElements/DOM change) applies the
+      // full set once every resolvable member has a live node.
+      if (selections.length < resolvableCount) return;
+      if (selections.length === 0) {
+        applyDomSelection(null, { revealPanel: false });
+      } else if (selections.length === 1) {
+        applyDomSelection(selections[0], { revealPanel: false });
+      } else {
+        applyMarqueeSelection(selections, false);
+      }
+    };
+
+    void syncSelection();
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    activeCompPath,
+    applyDomSelection,
+    applyMarqueeSelection,
+    buildDomSelectionForTimelineElement,
+    domEditGroupSelections,
+    domEditSelection,
+    selectedElementId,
+    selectedIds,
+    selectedKey,
+    timelineElements,
+  ]);
+}

package/src/hooks/useVariablesPersist.ts

@@ -0,0 +1,61 @@
+import { useCallback } from "react";
+import type { Composition } from "@hyperframes/sdk";
+import { persistSdkSerialize } from "../utils/sdkCutover";
+import type { UseSlideshowPersistParams } from "./useSlideshowPersist";
+
+/** Same single-writer dependency set the slideshow persist path uses. */
+export type UseVariablesPersistParams = Omit<UseSlideshowPersistParams, "coalesceKey">;
+
+/**
+ * Persist a variable-schema edit: run `mutate` (SDK declaration/value ops)
+ * against the session, then write the serialized composition through the
+ * standard single-writer path (undo history + self-write echo suppression +
+ * preview reload). Mutations that end up changing nothing are skipped, so a
+ * no-op dispatch (e.g. declaring a duplicate id) never pollutes undo history.
+ */
+export function useVariablesPersist({
+  sdkSession,
+  activeCompPath,
+  readProjectFile,
+  writeProjectFile,
+  recordEdit,
+  reloadPreview,
+  domEditSaveTimestampRef,
+}: UseVariablesPersistParams): (
+  label: string,
+  mutate: (session: Composition) => void,
+) => Promise<boolean> {
+  return useCallback(
+    async (label: string, mutate: (session: Composition) => void) => {
+      if (!sdkSession) return false;
+      const path = activeCompPath ?? "index.html";
+      const originalContent = await readProjectFile(path);
+      mutate(sdkSession);
+      const after = sdkSession.serialize();
+      if (after === originalContent) return false;
+      await persistSdkSerialize(
+        after,
+        path,
+        originalContent,
+        {
+          editHistory: { recordEdit },
+          writeProjectFile,
+          reloadPreview,
+          domEditSaveTimestampRef,
+          compositionPath: activeCompPath,
+        },
+        { label },
+      );
+      return true;
+    },
+    [
+      sdkSession,
+      activeCompPath,
+      readProjectFile,
+      writeProjectFile,
+      recordEdit,
+      reloadPreview,
+      domEditSaveTimestampRef,
+    ],
+  );
+}