@hyperframes/studio 0.8.51 → 0.8.53-desktop.0

package/src/hooks/useTimelineEditing.test.tsx

@@ -122,12 +122,14 @@ function renderTimelineEditingHook(input: {
   forceReloadSdkSession?: () => void;
   invalidateGsapCache?: () => void;
   showToast?: (message: string, kind?: string) => void;
+  canEdit?: NonNullable<Parameters<typeof useTimelineEditing>[0]["canEdit"]>;
 }): {
   move: ReturnType<typeof useTimelineEditing>["handleTimelineElementMove"];
   resize: ReturnType<typeof useTimelineEditing>["handleTimelineElementResize"];
   groupMove: ReturnType<typeof useTimelineEditing>["handleTimelineGroupMove"];
   groupResize: ReturnType<typeof useTimelineEditing>["handleTimelineGroupResize"];
   del: ReturnType<typeof useTimelineEditing>["handleTimelineElementDelete"];
+  elementsDelete: ReturnType<typeof useTimelineEditing>["handleTimelineElementsDelete"];
   unmount: () => void;
 } {
   let move: ReturnType<typeof useTimelineEditing>["handleTimelineElementMove"] | null = null;
@@ -135,6 +137,8 @@ function renderTimelineEditingHook(input: {
   let groupMove: ReturnType<typeof useTimelineEditing>["handleTimelineGroupMove"] | null = null;
   let groupResize: ReturnType<typeof useTimelineEditing>["handleTimelineGroupResize"] | null = null;
   let del: ReturnType<typeof useTimelineEditing>["handleTimelineElementDelete"] | null = null;
+  let elementsDelete: ReturnType<typeof useTimelineEditing>["handleTimelineElementsDelete"] | null =
+    null;
 
   function Harness() {
     const commitRef = useRef(input.onZIndexCommit);
@@ -155,12 +159,14 @@ function renderTimelineEditingHook(input: {
       forceReloadSdkSession: input.forceReloadSdkSession,
       invalidateGsapCache: input.invalidateGsapCache,
       handleDomZIndexReorderCommitRef: commitRef,
+      canEdit: input.canEdit,
     });
     move = hook.handleTimelineElementMove;
     resize = hook.handleTimelineElementResize;
     groupMove = hook.handleTimelineGroupMove;
     groupResize = hook.handleTimelineGroupResize;
     del = hook.handleTimelineElementDelete;
+    elementsDelete = hook.handleTimelineElementsDelete;
     return null;
   }
 
@@ -170,7 +176,8 @@ function renderTimelineEditingHook(input: {
   if (!groupMove) throw new Error("Expected hook to expose group move handler");
   if (!groupResize) throw new Error("Expected hook to expose group resize handler");
   if (!del) throw new Error("Expected hook to expose delete handler");
-  return { move, resize, groupMove, groupResize, del, unmount };
+  if (!elementsDelete) throw new Error("Expected hook to expose elements-delete handler");
+  return { move, resize, groupMove, groupResize, del, elementsDelete, unmount };
 }
 
 type TimelineRecordEdit = NonNullable<
@@ -289,6 +296,7 @@ function setupSingleClipHarness(options?: {
   source?: string;
   clipStyle?: string;
   onZIndexCommit?: (entries: ZIndexEntry[]) => Promise<void>;
+  canEdit?: NonNullable<Parameters<typeof useTimelineEditing>[0]["canEdit"]>;
 }) {
   const iframe = createPreviewIframe([{ id: "clip", track: 0, style: options?.clipStyle }]);
   const clip = timelineElement({ id: "clip", track: 0, zIndex: 0 });
@@ -300,16 +308,30 @@ function setupSingleClipHarness(options?: {
   const fetchMock = stubProjectFetch(
     options?.source ?? '<div id="clip" data-start="0" data-track-index="0"></div>',
   );
+  const recordEdit = vi.fn(async () => {});
+  const showToast = vi.fn();
   const hook = renderTimelineEditingHook({
     timelineElements: [clip],
     iframe,
     onZIndexCommit: commit,
     projectId: "p1",
     writeProjectFile,
-    recordEdit: vi.fn(async () => {}),
+    recordEdit,
     reloadPreview,
+    showToast,
+    canEdit: options?.canEdit,
   });
-  return { iframe, clip, commit, writeProjectFile, reloadPreview, fetchMock, ...hook };
+  return {
+    iframe,
+    clip,
+    commit,
+    writeProjectFile,
+    recordEdit,
+    showToast,
+    reloadPreview,
+    fetchMock,
+    ...hook,
+  };
 }
 
 const SDK_KEYFRAMED_SOURCE = [
@@ -1431,3 +1453,300 @@ describe("useTimelineEditing duration rollback on failed persist", () => {
     succeeding.unmount();
   });
 });
+
+// Blocked means no fetch write, no recordEdit, and the host's reason
+// toasted. Absent canEdit behaves exactly as before (asserted above).
+describe("useTimelineEditing: canEdit gate", () => {
+  it("refuses a move with the host's reason, writing nothing", async () => {
+    const { clip, move, writeProjectFile, recordEdit, showToast, unmount } = setupSingleClipHarness(
+      {
+        canEdit: () => ({ blocked: true, reason: "Reserved by an agent" }),
+      },
+    );
+
+    await act(async () => {
+      await move(clip, { start: 3, track: clip.track });
+      await flushAsyncWork();
+    });
+
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    expect(recordEdit).not.toHaveBeenCalled();
+    expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
+    unmount();
+  });
+
+  it("refuses a delete (single and multi) with nothing written", async () => {
+    const { clip, del, elementsDelete, writeProjectFile, recordEdit, unmount } =
+      setupSingleClipHarness({
+        canEdit: () => ({ blocked: true, reason: "Reserved by an agent" }),
+      });
+
+    await act(async () => {
+      await del(clip);
+      await elementsDelete([clip]);
+      await flushAsyncWork();
+    });
+
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    expect(recordEdit).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("resolves toggle-track-hidden against the expanded rows, not the raw timelineElements prop", async () => {
+    // Regression: canEdit must resolve against the expanded rows
+    // (timelineTrackVisibility.ts's own invariant), not the raw
+    // timelineElements prop — proven by making the two disagree below.
+    const iframe = createPreviewIframe([{ id: "clip", track: 0 }]);
+    const clip = timelineElement({ id: "clip", track: 0, zIndex: 0 });
+    usePlayerStore.getState().setElements([clip]);
+    const showToast = vi.fn();
+    const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    let hook: ReturnType<typeof useTimelineEditing> | null = null;
+    function Harness() {
+      hook = useTimelineEditing({
+        projectId: "p1",
+        activeCompPath: "index.html",
+        timelineElements: [], // deliberately does not contain `clip`
+        showToast,
+        writeProjectFile,
+        recordEdit: vi.fn(),
+        reloadPreview: vi.fn(),
+        previewIframeRef: { current: iframe },
+        pendingTimelineEditPathRef: { current: new Set<string>() },
+        uploadProjectFiles: vi.fn(),
+        canEdit: (element) =>
+          element.id === "clip" ? { blocked: true, reason: "Reserved by an agent" } : true,
+      });
+      return null;
+    }
+    const { unmount } = mountHarness(<Harness />);
+    if (!hook) throw new Error("Expected hook to mount");
+
+    await act(async () => {
+      await hook!.handleToggleTrackHidden(0, true);
+      await flushAsyncWork();
+    });
+
+    expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("lets an unblocked element through while a blocked one is refused", async () => {
+    const iframe = createPreviewIframe([
+      { id: "free", track: 0 },
+      { id: "locked", track: 1 },
+    ]);
+    const free = timelineElement({ id: "free", track: 0, zIndex: 0 });
+    const locked = timelineElement({ id: "locked", track: 1, zIndex: 0 });
+    const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    const recordEdit = vi.fn(async () => {});
+    stubProjectFetch(
+      '<div id="free" data-start="0" data-track-index="0"></div>' +
+        '<div id="locked" data-start="0" data-track-index="1"></div>',
+    );
+    const hook = renderTimelineEditingHook({
+      timelineElements: [free, locked],
+      iframe,
+      onZIndexCommit: vi.fn().mockResolvedValue(undefined),
+      projectId: "p1",
+      writeProjectFile,
+      recordEdit,
+      canEdit: (element) =>
+        element.id === "locked" ? { blocked: true, reason: "Reserved by an agent" } : true,
+    });
+
+    await act(async () => {
+      await hook.move(locked, { start: 3, track: locked.track });
+      await flushAsyncWork();
+    });
+    expect(writeProjectFile).not.toHaveBeenCalled();
+
+    await act(async () => {
+      await hook.move(free, { start: 3, track: free.track });
+      await flushAsyncWork();
+    });
+    expect(writeProjectFile).toHaveBeenCalled();
+    hook.unmount();
+  });
+
+  it("refuses razor-split-all when it would split a blocked clip, writing nothing", async () => {
+    const iframe = createPreviewIframe([{ id: "clip", track: 0 }]);
+    const clip = timelineElement({ id: "clip", track: 0, zIndex: 0, start: 0, duration: 2 });
+    usePlayerStore.getState().setElements([clip]);
+    const showToast = vi.fn();
+    const fetchMock = vi.fn(async () => {
+      throw new Error("must not be called: canEdit should have refused the split");
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    let hook: ReturnType<typeof useTimelineEditing> | null = null;
+    function Harness() {
+      hook = useTimelineEditing({
+        projectId: "p1",
+        activeCompPath: "index.html",
+        timelineElements: [clip],
+        showToast,
+        writeProjectFile: vi.fn(),
+        recordEdit: vi.fn(),
+        reloadPreview: vi.fn(),
+        previewIframeRef: { current: iframe },
+        pendingTimelineEditPathRef: { current: new Set<string>() },
+        uploadProjectFiles: vi.fn(),
+        canEdit: () => ({ blocked: true, reason: "Reserved by an agent" }),
+      });
+      return null;
+    }
+    const { unmount } = mountHarness(<Harness />);
+    if (!hook) throw new Error("Expected hook to mount");
+
+    await act(async () => {
+      await hook!.handleRazorSplitAll(1);
+      await flushAsyncWork();
+    });
+
+    expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
+    expect(fetchMock).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("refuses a blocked group's audio attribute write, writing nothing", async () => {
+    const iframe = createPreviewIframe([{ id: "member", track: 0 }]);
+    const member = timelineElement({ id: "member", track: 0, zIndex: 0 });
+    usePlayerStore.getState().setElements([{ ...member, audioGroup: "hf-group" }]);
+    const showToast = vi.fn();
+    const fetchMock = vi.fn(async () => {
+      throw new Error("must not be called: canEdit should have refused the write");
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    let hook: ReturnType<typeof useTimelineEditing> | null = null;
+    function Harness() {
+      hook = useTimelineEditing({
+        projectId: "p1",
+        activeCompPath: "index.html",
+        timelineElements: [member],
+        showToast,
+        writeProjectFile: vi.fn(),
+        recordEdit: vi.fn(),
+        reloadPreview: vi.fn(),
+        previewIframeRef: { current: iframe },
+        pendingTimelineEditPathRef: { current: new Set<string>() },
+        uploadProjectFiles: vi.fn(),
+        canEdit: (element) =>
+          element.id === "member" ? { blocked: true, reason: "Reserved by an agent" } : true,
+      });
+      return null;
+    }
+    const { unmount } = mountHarness(<Harness />);
+    if (!hook) throw new Error("Expected hook to mount");
+
+    await act(async () => {
+      await hook!.setAudioGroupAttribute.setQuiet("hf-group", "data-volume", "0.5", "Set volume");
+      await flushAsyncWork();
+    });
+
+    expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
+    expect(fetchMock).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("refuses a group write when its members live only inside a sub-composition", async () => {
+    // syncStoredGroupAttribute mirrors into domClipChildren for a group with
+    // no flat twin (timelineAudioGroupVolume.ts) — the resolver must check
+    // that array too, or a sub-comp-only group's write goes ungated.
+    const iframe = createPreviewIframe([]);
+    usePlayerStore.getState().setElements([]);
+    usePlayerStore.getState().setDomClipChildren([
+      {
+        id: "sub-member",
+        parentId: "host",
+        hostId: "host",
+        label: "Sub member",
+        stackingContextId: "root",
+        audioGroup: "hf-group",
+      },
+    ]);
+    const showToast = vi.fn();
+    const fetchMock = vi.fn(async () => {
+      throw new Error("must not be called: canEdit should have refused the write");
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    let hook: ReturnType<typeof useTimelineEditing> | null = null;
+    function Harness() {
+      hook = useTimelineEditing({
+        projectId: "p1",
+        activeCompPath: "index.html",
+        timelineElements: [],
+        showToast,
+        writeProjectFile: vi.fn(),
+        recordEdit: vi.fn(),
+        reloadPreview: vi.fn(),
+        previewIframeRef: { current: iframe },
+        pendingTimelineEditPathRef: { current: new Set<string>() },
+        uploadProjectFiles: vi.fn(),
+        canEdit: (element) =>
+          element.id === "sub-member" ? { blocked: true, reason: "Reserved by an agent" } : true,
+      });
+      return null;
+    }
+    const { unmount } = mountHarness(<Harness />);
+    if (!hook) throw new Error("Expected hook to mount");
+
+    await act(async () => {
+      await hook!.setAudioGroupAttribute.setQuiet("hf-group", "data-volume", "0.5", "Set volume");
+      await flushAsyncWork();
+    });
+
+    expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
+    expect(fetchMock).not.toHaveBeenCalled();
+    unmount();
+  });
+});
+
+// Regression: track()/guard() must return the same wrapped handler across
+// renders for the same fn, or a consumer using it as a memo/effect
+// dependency re-runs on every render for nothing.
+describe("useTimelineEditing: handler identity is stable across renders", () => {
+  it("returns the same handleTimelineElementMove reference on a re-render", () => {
+    const iframe = createPreviewIframe([{ id: "clip", track: 0 }]);
+    const clip = timelineElement({ id: "clip", track: 0, zIndex: 0 });
+    stubProjectFetch('<div id="clip" data-start="0" data-track-index="0"></div>');
+    // Every option below is hoisted (created once), matching a real caller's
+    // stable useCallback/selector inputs — a fresh vi.fn() per render would
+    // change handleTimelineElementMove's own identity regardless of the fix.
+    const timelineElements = [clip];
+    const showToast = vi.fn();
+    const writeProjectFile = vi.fn();
+    const recordEdit = vi.fn();
+    const reloadPreview = vi.fn();
+    const uploadProjectFiles = vi.fn();
+    const previewIframeRef = { current: iframe };
+    const pendingTimelineEditPathRef = { current: new Set<string>() };
+    const seen: unknown[] = [];
+    let bumpTick = 0;
+    let bump = () => {};
+    function Harness() {
+      const [, setTick] = React.useState(0);
+      bump = () => setTick((t) => t + 1);
+      bumpTick += 1;
+      const hook = useTimelineEditing({
+        projectId: "p1",
+        activeCompPath: "index.html",
+        timelineElements,
+        showToast,
+        writeProjectFile,
+        recordEdit,
+        reloadPreview,
+        previewIframeRef,
+        pendingTimelineEditPathRef,
+        uploadProjectFiles,
+      });
+      seen.push(hook.handleTimelineElementMove);
+      return null;
+    }
+    const { unmount } = mountHarness(<Harness />);
+    act(() => bump());
+    expect(bumpTick).toBeGreaterThan(1);
+    expect(seen[0]).toBe(seen[1]);
+    unmount();
+  });
+});

package/src/hooks/useTimelineEditing.ts

@@ -1,7 +1,9 @@
 // fallow-ignore-file complexity
 import { useCallback, useRef } from "react";
 import type { TimelineElement } from "../player";
+import { usePlayerStore } from "../player";
 import { useRazorSplit } from "./useRazorSplit";
+import { selectSplittableElements } from "../utils/timelineElementSplit";
 import { useTimelineAssetDropOps } from "./useTimelineAssetDropOps";
 import {
   applyTimelineStackingReorder,
@@ -23,6 +25,8 @@ import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
 import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
 import { useSetElementAttribute } from "./timelineElementFxAttribute";
 import { useTimelineDeleteOps } from "./useTimelineDeleteOps";
+import { useTimelineRowElements } from "../player/hooks/useTimelineRowElements";
+import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
 import { useAudioGroupCarveAssignment } from "./timelineAudioGroupCreate";
 import {
   useTimelineElementVisibilityEditing,
@@ -30,6 +34,7 @@ import {
 } from "./timelineTrackVisibility";
 import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
 import { useBlockedTimelineEditToast } from "./useBlockedTimelineEditToast";
+import { useTimelineEditGate } from "./timelineEditPermission";
 import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
 import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
 import type { TimelineMoveUpdates, UseTimelineEditingOptions } from "./useTimelineEditingTypes";
@@ -53,10 +58,38 @@ export function useTimelineEditing({
   forceReloadSdkSession,
   invalidateGsapCache,
   handleDomZIndexReorderCommitRef,
+  canEdit,
 }: UseTimelineEditingOptions) {
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
   const editQueueRef = useRef(Promise.resolve());
+  const track = useTrackPendingTimelineEdit();
+  const checkEditable = useTimelineEditGate(canEdit, showToast);
+  // Same expanded-row source the hide handlers themselves resolve against
+  // (timelineTrackVisibility.ts) — a virtual sub-comp child's track/key
+  // only exists here, not in the raw store list canEdit would otherwise miss.
+  const timelineRowElements = useTimelineRowElements();
+  const guardedRef = useRef(
+    new WeakMap<(...args: never[]) => Promise<void>, (...args: never[]) => Promise<void>>(),
+  );
+  // Refuses (no call, no write, no history entry) when any target is
+  // blocked; otherwise runs fn as before. Cached by fn identity — like
+  // track() — so a fresh closure here doesn't defeat track's own cache.
+  const guard = useCallback(
+    <H extends (...args: never[]) => Promise<void>>(
+      resolveTargets: (...args: Parameters<H>) => readonly TimelineElement[],
+      fn: H,
+    ): H => {
+      const key = fn as unknown as (...args: never[]) => Promise<void>;
+      const cached = guardedRef.current.get(key);
+      if (cached) return cached as H;
+      const wrapped = ((...args: Parameters<H>) =>
+        checkEditable(resolveTargets(...args)) ? fn(...args) : Promise.resolve()) as H;
+      guardedRef.current.set(key, wrapped as unknown as (...args: never[]) => Promise<void>);
+      return wrapped;
+    },
+    [checkEditable],
+  );
 
   const enqueueEdit = useCallback(
     (
@@ -445,23 +478,77 @@ export function useTimelineEditing({
     forceReloadSdkSession,
   });
 
+  // Every write-handler is tracked here, the one place all hand edits
+  // converge, so undo never races a write; canEdit gates the same point.
+  // Coverage boundary: see the PR body, not every kind resolves an element.
+  const trackedRazorSplit = track(guard((element) => [element], handleRazorSplit));
   return {
-    handleTimelineElementMove,
-    handleTimelineElementResize,
-    handleToggleTrackHidden,
-    handleToggleElementHidden,
-    handleAutoGroupCarveSources,
-    setAudioGroupAttribute,
-    setElementFxAttribute,
-    handleTimelineElementDelete,
-    handleTimelineElementsDelete,
-    handleTimelineElementSplit: handleRazorSplit,
-    handleRazorSplit,
-    handleRazorSplitAll,
-    handleTimelineAssetDrop,
-    handleTimelineFileDrop,
-    handleTimelineCompositionDrop,
+    handleTimelineElementMove: track(guard((element) => [element], handleTimelineElementMove)),
+    handleTimelineElementResize: track(guard((element) => [element], handleTimelineElementResize)),
+    handleToggleTrackHidden: track(
+      guard(
+        (trackIndex) => timelineRowElements.filter((el) => el.track === trackIndex),
+        handleToggleTrackHidden,
+      ),
+    ),
+    handleToggleElementHidden: track(
+      guard((elementKey) => {
+        const keys = new Set(Array.isArray(elementKey) ? elementKey : [elementKey]);
+        return timelineRowElements.filter((el) => keys.has(el.key ?? el.id));
+      }, handleToggleElementHidden),
+    ),
+    handleAutoGroupCarveSources: track(handleAutoGroupCarveSources),
+    setAudioGroupAttribute: {
+      ...setAudioGroupAttribute,
+      // Same two-array member lookup syncStoredGroupAttribute mirrors into
+      // (timelineAudioGroupVolume.ts): a sub-composition's group members have
+      // no flat twin, only a domClipChildren entry, so both are checked.
+      setQuiet: track(
+        guard((groupId) => {
+          const state = usePlayerStore.getState();
+          const flatMembers = state.elements.filter((el) => el.audioGroup === groupId);
+          const domMembers = state.domClipChildren
+            .filter((child) => child.audioGroup === groupId)
+            .map(
+              (child): TimelineElement => ({
+                id: child.id,
+                domId: child.id,
+                tag: "div",
+                start: 0,
+                duration: 0,
+                track: -1,
+              }),
+            );
+          return [...flatMembers, ...domMembers];
+        }, setAudioGroupAttribute.setQuiet),
+      ),
+    },
+    setElementFxAttribute: {
+      ...setElementFxAttribute,
+      setQuiet: track(guard((element) => [element], setElementFxAttribute.setQuiet)),
+    },
+    handleTimelineElementDelete: track(guard((element) => [element], handleTimelineElementDelete)),
+    handleTimelineElementsDelete: track(
+      guard((elements) => elements, handleTimelineElementsDelete),
+    ),
+    handleTimelineElementSplit: trackedRazorSplit,
+    handleRazorSplit: trackedRazorSplit,
+    // Same selection the handler itself splits (useRazorSplit.ts).
+    handleRazorSplitAll: track(
+      guard(
+        (splitTime) => selectSplittableElements(usePlayerStore.getState().elements, splitTime),
+        handleRazorSplitAll,
+      ),
+    ),
+    handleTimelineAssetDrop: track(handleTimelineAssetDrop),
+    handleTimelineFileDrop: track(handleTimelineFileDrop),
+    handleTimelineCompositionDrop: track(handleTimelineCompositionDrop),
     handleBlockedTimelineEdit,
-    ...groupEditing,
+    handleTimelineGroupMove: track(
+      guard((changes) => changes.map((c) => c.element), groupEditing.handleTimelineGroupMove),
+    ),
+    handleTimelineGroupResize: track(
+      guard((changes) => changes.map((c) => c.element), groupEditing.handleTimelineGroupResize),
+    ),
   };
 }

package/src/hooks/useTimelineEditingTypes.ts

@@ -4,6 +4,7 @@ import type { TimelineElement } from "../player";
 import type { TimelineStackingReorderIntent } from "../player/components/timelineEditing";
 import type { EditHistoryKind } from "../utils/editHistory";
 import type { PublishSdkSession } from "../utils/sdkCutover";
+import type { CanEditTimelineElement } from "./timelineEditPermission";
 
 interface RecordEditInput {
   label: string;
@@ -49,6 +50,8 @@ export interface UseTimelineEditingOptions {
   /** Reparse authored animations after a timing rewrite changes their positions. */
   invalidateGsapCache?: () => void;
   handleDomZIndexReorderCommitRef?: MutableRefObject<TimelineZIndexReorderCommit | null>;
+  /** Refuses a hand edit at the persist boundary when set; absent = Studio unchanged. */
+  canEdit?: CanEditTimelineElement;
 }
 
 export type TimelineFileDropHandler = (

package/src/hooks/useTrackPendingTimelineEdit.test.tsx

@@ -0,0 +1,62 @@
+// @vitest-environment happy-dom
+
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { flushStudioPendingEdits } from "../utils/studioPendingEdits";
+import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | null = null;
+afterEach(() => act(() => root?.unmount()));
+
+function mount() {
+  let track!: ReturnType<typeof useTrackPendingTimelineEdit>;
+  function Probe() {
+    track = useTrackPendingTimelineEdit();
+    return null;
+  }
+  root = createRoot(document.createElement("div"));
+  act(() => root!.render(createElement(Probe)));
+  return track;
+}
+
+const deferred = <T,>() => {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((r) => (resolve = r));
+  return { promise, resolve };
+};
+
+describe("useTrackPendingTimelineEdit", () => {
+  it("feeds Studio's shared pending-edit registry, so the app-wide flush waits for it", async () => {
+    const track = mount();
+    const gate = deferred<void>();
+    const order: string[] = [];
+    const tracked = track(() => gate.promise.then(() => order.push("edit-settled")));
+    const call = tracked();
+    const flushPromise = flushStudioPendingEdits().then(() => order.push("flushed"));
+    // Give the flush's own microtasks a turn: if tracking did nothing, it
+    // would already show "flushed" here, before the edit ever settles.
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(order).toEqual([]);
+    gate.resolve();
+    await call;
+    await flushPromise;
+    expect(order).toEqual(["edit-settled", "flushed"]);
+  });
+
+  it("returns the same wrapper for the same handler across calls", () => {
+    const track = mount();
+    const handler = () => Promise.resolve();
+    expect(track(handler)).toBe(track(handler));
+  });
+
+  it("returns a different wrapper for a different handler", () => {
+    const track = mount();
+    const a = () => Promise.resolve();
+    const b = () => Promise.resolve();
+    expect(track(a)).not.toBe(track(b));
+  });
+});

package/src/hooks/useTrackPendingTimelineEdit.ts

@@ -0,0 +1,22 @@
+import { useCallback, useRef } from "react";
+import { trackStudioPendingEdit } from "../utils/studioPendingEdits";
+
+type AsyncFn = (...args: never[]) => Promise<unknown>;
+
+// Tracks a hand-edit handler's write so undo/redo (already draining this
+// registry) waits for it. Same `fn` in, same wrapper out, so memoized deps stay stable.
+export function useTrackPendingTimelineEdit() {
+  const wrappedRef = useRef(new WeakMap<AsyncFn, AsyncFn>());
+  return useCallback(<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>) => {
+    const key = fn as unknown as AsyncFn;
+    const cached = wrappedRef.current.get(key);
+    if (cached) return cached as unknown as (...args: Args) => Promise<R>;
+    const wrapped = (...args: Args): Promise<R> => {
+      const result = fn(...args);
+      trackStudioPendingEdit(result);
+      return result;
+    };
+    wrappedRef.current.set(key, wrapped as unknown as AsyncFn);
+    return wrapped;
+  }, []);
+}