@hyperframes/studio 0.8.78 → 0.8.80

package/src/hooks/timelineEditPermission.ts

@@ -6,26 +6,68 @@ export type TimelineEditPermission = true | { blocked: true; reason: string };
 
 export type CanEditTimelineElement = (element: TimelineElement) => TimelineEditPermission;
 
+/** What an effect save did: landed, refused before writing, or failed while writing. */
+export type TimelineEditOutcome =
+  | { status: "saved" }
+  | { status: "refused" | "failed"; reason: string };
+
+/** The project to save into, or why the save stops before it writes. */
+export function projectForTimelineSave(
+  isRecording: boolean | undefined,
+  projectId: string | null,
+  showToast: (message: string, tone?: "error" | "info") => void,
+): string | TimelineEditOutcome {
+  if (isRecording) {
+    showToast("Cannot edit timeline while recording", "error");
+    return { status: "refused", reason: "Cannot edit timeline while recording" };
+  }
+  return projectId ?? failedTimelineSave("No project is open", showToast);
+}
+
+export function failedTimelineSave(
+  reason: string,
+  showToast: (message: string, tone?: "error" | "info") => void,
+): TimelineEditOutcome {
+  showToast(reason);
+  return { status: "failed", reason };
+}
+
+function timelineEditRefusal(
+  canEdit: CanEditTimelineElement | undefined,
+  targets: readonly TimelineElement[],
+): string | null {
+  for (const element of targets) {
+    const verdict = canEdit?.(element) ?? true;
+    if (verdict !== true) return verdict.reason;
+  }
+  return null;
+}
+
 /**
- * Refuses a write when any target element is blocked, toasting the host's
- * reason. Absent `canEdit` never refuses, so Studio itself is unchanged.
+ * The host's reason to refuse a write when any target element is blocked, toasted,
+ * or null. Absent `canEdit` never refuses, so Studio itself is unchanged.
  */
-export function useTimelineEditGate(
+export function useTimelineEditRefusal(
   canEdit: CanEditTimelineElement | undefined,
   showToast: (message: string, tone?: "error" | "info") => void,
 ) {
   return useCallback(
-    (targets: readonly TimelineElement[]): boolean => {
-      if (!canEdit) return true;
-      for (const element of targets) {
-        const verdict = canEdit(element);
-        if (verdict !== true) {
-          showToast(verdict.reason, "error");
-          return false;
-        }
-      }
-      return true;
+    (targets: readonly TimelineElement[]): string | null => {
+      const reason = timelineEditRefusal(canEdit, targets);
+      if (reason !== null) showToast(reason, "error");
+      return reason;
     },
     [canEdit, showToast],
   );
 }
+
+export function useTimelineEditGate(
+  canEdit: CanEditTimelineElement | undefined,
+  showToast: (message: string, tone?: "error" | "info") => void,
+) {
+  const refuse = useTimelineEditRefusal(canEdit, showToast);
+  return useCallback(
+    (targets: readonly TimelineElement[]): boolean => refuse(targets) === null,
+    [refuse],
+  );
+}

package/src/hooks/timelineEditingHelpers.test.ts

@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   applyTimelineStackingReorder,
   buildTimelineMoveTimingPatch,
+  buildTimelineResizeTimingPatch,
   deleteSelectedKeyframes,
   extendRootDurationIfNeeded,
   patchIframeDomTiming,
@@ -230,6 +231,19 @@ describe("extendRootDurationIfNeeded", () => {
   });
 });
 
+describe("buildTimelineResizeTimingPatch", () => {
+  it("moves a source-only in-point by the caller's own start change", () => {
+    const source = `<div id="root"><video id="a" class="clip" data-start="5" data-duration="3" data-media-start="0.337"></video></div>`;
+    const element = el({ id: "a", tag: "video", domId: "a", start: 5, duration: 3 });
+    const patched = buildTimelineResizeTimingPatch(source, { id: "a" }, element, {
+      start: 3,
+      duration: 5,
+      playbackStart: undefined,
+    });
+    expect(patched).toContain('data-media-start="0"');
+  });
+});
+
 describe("persistTimelineBatchEdit", () => {
   const SOURCE = `<div id="root"><video id="a" class="clip" data-start="1" data-track-index="0"></video><video id="b" class="clip" data-start="2" data-track-index="1"></video></div>`;
 
@@ -452,6 +466,7 @@ describe("persistElementAttribute", () => {
         writeProjectFile,
         recordEdit: vi.fn(),
         pendingTimelineEditPathRef: { current: new Set() },
+        onFileRead: vi.fn(),
         patchLive,
       }),
     ).rejects.toThrow("Unable to patch element in index.html");
@@ -495,6 +510,7 @@ describe("persistElementAttribute — unwind value", () => {
         writeProjectFile,
         recordEdit: vi.fn(),
         pendingTimelineEditPathRef: { current: new Set() },
+        onFileRead: vi.fn(),
         // The live DOM is ALREADY at the new value when the commit runs — that
         // is what `setLive` does on every drag frame.
         patchLive: (v) => patched.push(v),

package/src/hooks/timelineEditingHelpers.ts

@@ -8,6 +8,7 @@ import {
 } from "../utils/sourcePatcher";
 import {
   formatTimelineAttributeNumber,
+  formatTimelineMediaOffset,
   type TimelineStackingReorderIntent,
 } from "../player/components/timelineEditing";
 import { getElementZIndex } from "../player/lib/layerOrdering";
@@ -15,7 +16,12 @@ import {
   furthestClipEndFromSource,
   getTimelineElementIdentity,
 } from "../player/lib/timelineElementHelpers";
-import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
+import {
+  saveProjectFilesWithHistory,
+  writeProjectFilesWithHistoryInQueue,
+  type RecordEditInput,
+} from "../utils/studioFileHistory";
+import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
 import type { TimelineZIndexReorderCommit } from "./useTimelineEditingTypes";
 import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
 import { readFileContent } from "./timelineTimingSync";
@@ -279,7 +285,7 @@ export function buildTimelineResizeTimingPatch(
     patched = applyPatchByTarget(patched, target, {
       type: "attribute",
       property: pbs.attrName,
-      value: formatTimelineAttributeNumber(pbs.value),
+      value: formatTimelineMediaOffset(pbs.value),
     });
   }
   // Content-driven duration from the PATCHED SOURCE (raw data-duration) —
@@ -396,7 +402,32 @@ export async function persistTimelineBatchEdit(
   });
 }
 
-export { applyPatchByTarget, formatTimelineAttributeNumber };
+/** What the file holds for `attr` once queued writes to it land; undefined when unreadable. */
+export async function readSavedAttribute(
+  projectId: string | null,
+  targetPath: string,
+  patchTarget: PatchTarget | null,
+  attr: string,
+  writeFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
+): Promise<string | null | undefined> {
+  if (!projectId || !patchTarget) return undefined;
+  const html = await serializeStudioFileMutations(writeFile, [targetPath], () =>
+    readFileContent(projectId, targetPath),
+  ).catch(() => null);
+  return html === null ? undefined : readTargetAttribute(html, patchTarget, attr);
+}
+
+/** What `html` holds for `attr` on the target; undefined when the target is not in it. */
+export function readTargetAttribute(
+  html: string,
+  patchTarget: PatchTarget,
+  attr: string,
+): string | null | undefined {
+  if (readTagSnippetByTarget(html, patchTarget) === undefined) return undefined;
+  return readAttributeByTarget(html, patchTarget, attr) ?? null;
+}
+
+export { applyPatchByTarget, formatTimelineAttributeNumber, formatTimelineMediaOffset };
 
 export { patchDocumentRootDuration } from "./timelineEditingGsap";
 
@@ -412,6 +443,8 @@ export interface PersistElementAttributeInput {
   pendingTimelineEditPathRef: { current: Set<string> };
   /** Write the attribute directly on the live preview DOM node. */
   patchLive: (value: string | null) => void;
+  /** What the file held for the attribute, read inside the queue before this write. */
+  onFileRead: (value: string | null) => void;
 }
 
 /**
@@ -433,47 +466,40 @@ export async function persistElementAttribute({
   recordEdit,
   pendingTimelineEditPathRef,
   patchLive,
+  onFileRead,
 }: PersistElementAttributeInput): Promise<string[]> {
-  // Resolve the target BEFORE patching the live DOM. The optimistic patch used
-  // to run first, and only the save was wrapped in the unwind — so an
-  // unresolvable target threw with the live preview (and, through the callers'
-  // catch, the store mirrored off it) holding a value that never reached disk.
-  // The write then read as successful until a reload dropped it.
-  const before = await readFileContent(projectId, targetPath);
-  if (readTagSnippetByTarget(before, patchTarget) === undefined) {
-    throw new Error(`Unable to patch element in ${targetPath}`);
-  }
-  // The unwind value comes from the FILE, not from `readLive()`.
-  //
-  // Every live-write caller patches the DOM before committing — a fader drag is
-  // `setLive` per frame, hovering a preset auditions the whole chain — so by the
-  // time this runs the live DOM already holds the in-progress value. Reading it
-  // here made `previousValue === value`, so the unwind below was a no-op, and
-  // `setQuiet`'s catch (which deliberately re-mirrors the store from the live
-  // DOM) then mirrored that same never-saved value. The group audibly had the
-  // preset, the panel agreed, and a reload dropped it — the failure class the
-  // target check above was added to close, still open on the live-write path.
-  const previousValue = readAttributeByTarget(before, patchTarget, attr) ?? null;
-  patchLive(value);
+  // Joins the file's mutation queue before reading, so saves land in the order they start
+  // and each patches what the save before it wrote. Resolve the target before patching
+  // the live DOM, so an unresolvable target never leaves an unsaved preview.
+  return serializeStudioFileMutations(writeProjectFile, [targetPath], async () => {
+    const before = await readFileContent(projectId, targetPath);
+    if (readTagSnippetByTarget(before, patchTarget) === undefined) {
+      throw new Error(`Unable to patch element in ${targetPath}`);
+    }
+    // Unwind to the file's value: live writers already patched the DOM, so `readLive()`
+    // would equal `value` and a failed save would keep a never-saved preview.
+    const previousValue = readAttributeByTarget(before, patchTarget, attr) ?? null;
+    onFileRead(previousValue);
+    patchLive(value);
 
-  const operation: PatchOperation = { type: "attribute", property: attr, value };
-  const patched = applyPatchByTarget(before, patchTarget, operation);
+    const operation: PatchOperation = { type: "attribute", property: attr, value };
+    const patched = applyPatchByTarget(before, patchTarget, operation);
 
-  pendingTimelineEditPathRef.current.add(targetPath);
-  try {
-    const changedPaths = await saveProjectFilesWithHistory({
-      projectId,
-      label,
-      files: { [targetPath]: patched },
-      readFile: async (path) => (path === targetPath ? before : readFileContent(projectId, path)),
-      writeFile: writeProjectFile,
-      recordEdit,
-    });
-    return changedPaths;
-  } catch (error) {
-    // The optimistic live write already ran; unwind it on a save failure so
-    // the preview doesn't show a value that never reached disk.
-    patchLive(previousValue);
-    throw error;
-  }
+    pendingTimelineEditPathRef.current.add(targetPath);
+    try {
+      return await writeProjectFilesWithHistoryInQueue({
+        projectId,
+        label,
+        files: { [targetPath]: patched },
+        readFile: async (path) => (path === targetPath ? before : readFileContent(projectId, path)),
+        writeFile: writeProjectFile,
+        recordEdit,
+      });
+    } catch (error) {
+      // The optimistic live write already ran; unwind it on a save failure so
+      // the preview doesn't show a value that never reached disk.
+      patchLive(previousValue);
+      throw error;
+    }
+  });
 }

package/src/hooks/timelineElementFxAttribute.ts

@@ -7,17 +7,25 @@
  * shared core `setAudioGroupAttribute` also uses.
  */
 
-import { useCallback, useRef } from "react";
+import { useCallback } from "react";
 import type { TimelineElement } from "../player";
 import {
   buildPatchTarget,
   findTimelineElementInIframe,
   persistElementAttribute,
+  readSavedAttribute,
 } from "./timelineEditingHelpers";
+import { useLiveLanes, type LiveLaneRestore, type LiveLaneSource } from "./liveLanes";
 import type {
   MutableRef,
   UseTimelineElementVisibilityEditingInput,
 } from "./timelineTrackVisibility";
+import {
+  failedTimelineSave,
+  projectForTimelineSave,
+  type TimelineEditOutcome,
+} from "./timelineEditPermission";
+import { syncStoredElementAttribute } from "../player/lib/automationStoreSync";
 
 function patchLiveElementAttribute(
   iframe: HTMLIFrameElement | null,
@@ -40,6 +48,22 @@ function elementAttributeLiveKey(
   return `${element.sourceFile || activeCompPath || "index.html"}\0${element.key ?? element.domId ?? element.id}\0${attr}`;
 }
 
+function elementSaveTarget(element: TimelineElement, activeCompPath: string | null) {
+  return {
+    targetPath: element.sourceFile || activeCompPath || "index.html",
+    patchTarget: buildPatchTarget(element),
+  };
+}
+
+function elementLiveSource(
+  element: TimelineElement,
+  activeCompPath: string | null,
+  attr: string,
+): LiveLaneSource {
+  const { targetPath, patchTarget } = elementSaveTarget(element, activeCompPath);
+  return { path: targetPath, target: patchTarget, attr };
+}
+
 interface SetElementAttributeInput {
   projectId: string;
   activeCompPath: string | null;
@@ -47,7 +71,8 @@ interface SetElementAttributeInput {
   attr: string;
   value: string | null;
   label: string;
-  previewIframe: HTMLIFrameElement | null;
+  patchLive: (value: string | null) => void;
+  onFileRead: (value: string | null) => void;
   writeProjectFile: (path: string, content: string) => Promise<void>;
   recordEdit: Parameters<typeof persistElementAttribute>[0]["recordEdit"];
   pendingTimelineEditPathRef: MutableRef<Set<string>>;
@@ -60,14 +85,14 @@ async function setElementAttribute({
   attr,
   value,
   label,
-  previewIframe,
+  patchLive,
+  onFileRead,
   writeProjectFile,
   recordEdit,
   pendingTimelineEditPathRef,
-}: SetElementAttributeInput): Promise<string[]> {
-  const targetPath = element.sourceFile || activeCompPath || "index.html";
-  const patchTarget = buildPatchTarget(element);
-  if (!patchTarget) return [];
+}: SetElementAttributeInput): Promise<string[] | null> {
+  const { targetPath, patchTarget } = elementSaveTarget(element, activeCompPath);
+  if (!patchTarget) return null;
 
   return persistElementAttribute({
     projectId,
@@ -79,7 +104,8 @@ async function setElementAttribute({
     writeProjectFile,
     recordEdit,
     pendingTimelineEditPathRef,
-    patchLive: (v) => patchLiveElementAttribute(previewIframe, element, attr, v, activeCompPath),
+    patchLive,
+    onFileRead,
   });
 }
 
@@ -99,68 +125,94 @@ export function useSetElementAttribute({
     attr: string,
     value: string | null,
     label: string,
-  ) => Promise<void>;
+  ) => Promise<TimelineEditOutcome>;
   revertLive: (element: TimelineElement, attr: string) => void;
+  restoreLive: (restore: LiveLaneRestore) => void;
 } {
-  const liveBeforeRef = useRef(new Map<string, string | null>());
+  const liveLanes = useLiveLanes(projectIdRef, activeCompPath);
   const setLive = useCallback(
     (element: TimelineElement, attr: string, value: string | null) => {
       const key = elementAttributeLiveKey(element, activeCompPath, attr);
       const target = findTimelineElementInIframe(previewIframeRef.current, element, activeCompPath);
-      if (!liveBeforeRef.current.has(key)) {
-        liveBeforeRef.current.set(key, target?.getAttribute(attr) ?? null);
-      }
+      liveLanes.preview(
+        key,
+        () => target?.getAttribute(attr) ?? null,
+        elementLiveSource(element, activeCompPath, attr),
+      );
       patchLiveElementAttribute(previewIframeRef.current, element, attr, value, activeCompPath);
     },
+    [liveLanes, previewIframeRef, activeCompPath],
+  );
+  const laneApply = useCallback(
+    (element: TimelineElement, attr: string) => ({
+      preview: (value: string | null) =>
+        patchLiveElementAttribute(previewIframeRef.current, element, attr, value, activeCompPath),
+      store: (value: string | null) => syncStoredElementAttribute(element, attr, value),
+    }),
     [previewIframeRef, activeCompPath],
   );
+  const claimLive = useCallback(
+    (element: TimelineElement, attr: string) =>
+      liveLanes.claim(
+        elementAttributeLiveKey(element, activeCompPath, attr),
+        laneApply(element, attr),
+        elementLiveSource(element, activeCompPath, attr),
+      ),
+    [liveLanes, laneApply, activeCompPath],
+  );
   const revertLive = useCallback(
-    (element: TimelineElement, attr: string) => {
-      const key = elementAttributeLiveKey(element, activeCompPath, attr);
-      if (!liveBeforeRef.current.has(key)) return;
-      patchLiveElementAttribute(
-        previewIframeRef.current,
-        element,
-        attr,
-        liveBeforeRef.current.get(key) ?? null,
-        activeCompPath,
-      );
-      liveBeforeRef.current.delete(key);
-    },
-    [previewIframeRef, activeCompPath],
+    (element: TimelineElement, attr: string) =>
+      liveLanes.revert(
+        elementAttributeLiveKey(element, activeCompPath, attr),
+        laneApply(element, attr),
+      ),
+    [liveLanes, laneApply, activeCompPath],
   );
   const setQuiet = useCallback(
-    async (element: TimelineElement, attr: string, value: string | null, label: string) => {
-      if (isRecordingRef?.current) {
-        showToast("Cannot edit timeline while recording", "error");
-        return;
-      }
-      const pid = projectIdRef.current;
-      if (!pid) return;
+    async (
+      element: TimelineElement,
+      attr: string,
+      value: string | null,
+      label: string,
+    ): Promise<TimelineEditOutcome> => {
+      const project = projectIdRef.current;
+      const pid = projectForTimelineSave(isRecordingRef?.current, project, showToast);
+      const live = claimLive(element, attr);
+      const unsaved = async (outcome: TimelineEditOutcome): Promise<TimelineEditOutcome> => {
+        const { targetPath, patchTarget } = elementSaveTarget(element, activeCompPath);
+        live.settle(
+          await readSavedAttribute(project, targetPath, patchTarget, attr, writeProjectFile),
+        );
+        return outcome;
+      };
+      if (typeof pid !== "string") return unsaved(pid);
       try {
-        await setElementAttribute({
+        const written = await setElementAttribute({
           projectId: pid,
           activeCompPath,
           element,
           attr,
           value,
           label,
-          previewIframe: previewIframeRef.current,
+          patchLive: live.preview,
+          onFileRead: live.read,
           writeProjectFile,
           recordEdit,
           pendingTimelineEditPathRef,
         });
-        liveBeforeRef.current.delete(elementAttributeLiveKey(element, activeCompPath, attr));
+        if (!written)
+          return unsaved(failedTimelineSave("This clip has no id to save it by", showToast));
+        live.settle(value);
+        return { status: "saved" };
       } catch (error) {
         console.error("[Timeline] Failed to set element attribute", error);
         const message = error instanceof Error ? error.message : "Failed to update effect";
-        showToast(message);
-        liveBeforeRef.current.delete(elementAttributeLiveKey(element, activeCompPath, attr));
+        return unsaved(failedTimelineSave(message, showToast));
       }
     },
     [
+      claimLive,
       activeCompPath,
-      previewIframeRef,
       writeProjectFile,
       recordEdit,
       pendingTimelineEditPathRef,
@@ -169,5 +221,5 @@ export function useSetElementAttribute({
       projectIdRef,
     ],
   );
-  return { setLive, setQuiet, revertLive };
+  return { setLive, setQuiet, revertLive, restoreLive: liveLanes.restore };
 }

package/src/hooks/useAppHotkeys.ts

@@ -93,7 +93,7 @@ interface UseAppHotkeysParams {
   handleDuplicate: () => Promise<boolean>;
   onResetKeyframes: () => boolean;
   onDeleteSelectedKeyframes: () => void;
-  onAfterUndoRedo?: () => void;
+  onAfterUndoRedo?: UseEditHistoryActionsOptions["onAfterUndoRedo"];
   onToggleRecording?: () => void;
   /** Group the current multi-selection into a data-hf-group wrapper (⌘G). */
   onGroupSelection?: () => void;