@hyperframes/studio 0.8.53 → 0.8.55

package/src/hooks/useTimelineDeleteOps.test.tsx

@@ -5,6 +5,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../player";
 import { applyRippleShifts, useTimelineDeleteOps } from "./useTimelineDeleteOps";
 import { installReactActEnvironment, mountReactHarness } from "./domSelectionTestHarness";
+import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
+import { flushStudioPendingEdits } from "../utils/studioPendingEdits";
 
 installReactActEnvironment();
 
@@ -117,3 +119,112 @@ describe("useTimelineDeleteOps: ripple undo label", () => {
     );
   });
 });
+
+// Regression: a delete's write can reach disk before its history entry is
+// recorded, so an Undo fired in that window found nothing to restore.
+// Fails without useTrackPendingTimelineEdit's wrap (see that file).
+describe("useTimelineDeleteOps: undo race", () => {
+  // data-composition-id (readRootCompositionDuration's key) plus a
+  // remove-element mock that actually drops hf-c: needed for a real diff.
+  const html = `<!DOCTYPE html><html data-composition-variables='[]'><body>
+<div data-hf-id="hf-stage" data-composition-id="main" data-duration="6">
+<div data-hf-id="hf-a" data-start="0" data-duration="2"></div>
+<div data-hf-id="hf-b" data-start="2" data-duration="2"></div>
+<div data-hf-id="hf-c" data-start="4" data-duration="2"></div>
+</div>
+</body></html>`;
+  const htmlAfterDeletingC = `<!DOCTYPE html><html data-composition-variables='[]'><body>
+<div data-hf-id="hf-stage" data-composition-id="main" data-duration="6">
+<div data-hf-id="hf-a" data-start="0" data-duration="2"></div>
+<div data-hf-id="hf-b" data-start="2" data-duration="2"></div>
+</div>
+</body></html>`;
+
+  beforeEach(() => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: RequestInfo | URL) => {
+        const url = String(input);
+        if (url.includes("/file-mutations/remove-element/")) {
+          return new Response(JSON.stringify({ changed: true, content: htmlAfterDeletingC }), {
+            status: 200,
+          });
+        }
+        return new Response(JSON.stringify({ content: html }), { status: 200 });
+      }),
+    );
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.unstubAllGlobals();
+  });
+
+  // A manually-resolved gate stands in for the delete's write landing — a
+  // real timer raced the fix's own microtasks unpredictably (verified: it
+  // kept passing even with the fix's tracking call deleted).
+  function deferred<T>() {
+    let resolve!: (value: T) => void;
+    const promise = new Promise<T>((r) => (resolve = r));
+    return { promise, resolve };
+  }
+
+  function mountRaceHarness() {
+    const elements = [el("hf-a", 0, 2), el("hf-b", 2, 2), el("hf-c", 4, 2)];
+    const gate = deferred<void>();
+    const recordEdit = vi.fn(() => gate.promise);
+    let tracked: ((elements: TimelineElement[]) => Promise<void>) | null = null;
+    function Harness() {
+      const track = useTrackPendingTimelineEdit();
+      const hook = useTimelineDeleteOps({
+        projectIdRef: { current: "test-project" },
+        activeCompPath: "index.html",
+        timelineElements: elements,
+        showToast: vi.fn(),
+        writeProjectFile: vi.fn().mockResolvedValue(undefined),
+        recordEdit,
+        reloadPreview: vi.fn(),
+        previewIframeRef: { current: null },
+        handleTimelineGroupMove: vi.fn().mockResolvedValue(undefined),
+      });
+      tracked = track(hook.handleTimelineElementsDelete);
+      return null;
+    }
+    mountReactHarness(<Harness />);
+    // Deletes the LAST clip (not the middle one): only this shrinks the
+    // composition's furthest-clip-end duration, so the write actually
+    // differs from the original content and recordEdit is reached — the
+    // middle clip's delete leaves duration unchanged and is a no-op write.
+    return { gate, recordEdit, deleteSelection: () => tracked!([elements[2]]) };
+  }
+
+  it("the pending-edit flush waits while the delete's history write is still landing", async () => {
+    const { gate, recordEdit, deleteSelection } = mountRaceHarness();
+    const order: string[] = [];
+    const deletePromise = deleteSelection().then(() => order.push("deleted"));
+    // Let the delete run up to (and call) recordEdit, which is now gated —
+    // this is the exact window a fast Undo used to race into.
+    await vi.waitFor(() => expect(recordEdit).toHaveBeenCalled());
+    // No React state changes happen inside the flush itself here (no
+    // pending-edit-flush listeners are registered in this harness), so it
+    // does not need act()'s wrapping — only awaiting the delete's own
+    // resolution below does.
+    const flushPromise = flushStudioPendingEdits().then(() => order.push("flushed"));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(order).toEqual([]);
+    gate.resolve();
+    await deletePromise;
+    await flushPromise;
+    expect(order).toEqual(["deleted", "flushed"]);
+  });
+
+  it("the pending-edit flush resolves immediately once the delete has already finished", async () => {
+    const { gate, deleteSelection } = mountRaceHarness();
+    gate.resolve();
+    await deleteSelection();
+    await act(async () => {
+      await flushStudioPendingEdits();
+    });
+  });
+});

package/src/hooks/useTimelineEditing.test.tsx

@@ -1,7 +1,7 @@
 // fallow-ignore-file code-duplication
 // @vitest-environment happy-dom
 
-import React, { act, useRef } from "react";
+import React, { act, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 import { openComposition } from "@hyperframes/sdk";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -122,12 +122,16 @@ 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"];
+  handleAutoGroupCarveSources: ReturnType<typeof useTimelineEditing>["handleAutoGroupCarveSources"];
+  setAudioGroupAttribute: ReturnType<typeof useTimelineEditing>["setAudioGroupAttribute"];
   unmount: () => void;
 } {
   let move: ReturnType<typeof useTimelineEditing>["handleTimelineElementMove"] | null = null;
@@ -135,6 +139,14 @@ 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;
+  let handleAutoGroupCarveSources:
+    | ReturnType<typeof useTimelineEditing>["handleAutoGroupCarveSources"]
+    | null = null;
+  let setAudioGroupAttribute:
+    | ReturnType<typeof useTimelineEditing>["setAudioGroupAttribute"]
+    | null = null;
 
   function Harness() {
     const commitRef = useRef(input.onZIndexCommit);
@@ -155,12 +167,16 @@ 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;
+    handleAutoGroupCarveSources = hook.handleAutoGroupCarveSources;
+    setAudioGroupAttribute = hook.setAudioGroupAttribute;
     return null;
   }
 
@@ -170,7 +186,20 @@ 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");
+  if (!handleAutoGroupCarveSources) throw new Error("Expected hook to expose group handler");
+  if (!setAudioGroupAttribute) throw new Error("Expected hook to expose audio group handler");
+  return {
+    move,
+    resize,
+    groupMove,
+    groupResize,
+    del,
+    elementsDelete,
+    handleAutoGroupCarveSources,
+    setAudioGroupAttribute,
+    unmount,
+  };
 }
 
 type TimelineRecordEdit = NonNullable<
@@ -289,6 +318,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 +330,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 +1475,436 @@ 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("re-reads canEdit after the host changes its verdict", async () => {
+    const iframe = createPreviewIframe([{ id: "clip", track: 0 }]);
+    const clip = timelineElement({ id: "clip", track: 0, zIndex: 0 });
+    const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    const showToast = vi.fn();
+    const recordEdit = vi.fn(async () => {});
+    const pendingTimelineEditPathRef = { current: new Set<string>() };
+    const previewIframeRef = { current: iframe };
+    const uploadProjectFiles = vi.fn();
+    const reloadPreview = vi.fn();
+    let setBlocked = () => {};
+    let hook: ReturnType<typeof useTimelineEditing> | null = null;
+
+    function Harness() {
+      const [blocked, updateBlocked] = useState(false);
+      setBlocked = () => updateBlocked(true);
+      hook = useTimelineEditing({
+        projectId: "p1",
+        activeCompPath: "index.html",
+        timelineElements: [clip],
+        showToast,
+        writeProjectFile,
+        recordEdit,
+        reloadPreview,
+        previewIframeRef,
+        pendingTimelineEditPathRef,
+        uploadProjectFiles,
+        canEdit: () => (blocked ? { blocked: true, reason: "Reserved by an agent" } : true),
+      });
+      return null;
+    }
+
+    const { unmount } = mountHarness(<Harness />);
+    if (!hook) throw new Error("Expected hook to mount");
+    act(() => setBlocked());
+
+    await act(async () => {
+      await hook!.handleTimelineElementMove(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 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();
+  });
+
+  it("refuses auto-grouping before it patches existing clips", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const doc = iframe.contentDocument;
+    if (!doc) throw new Error("Expected iframe document");
+    doc.body.innerHTML =
+      '<audio id="voice-1" data-start="0" data-duration="5"></audio>' +
+      '<audio id="voice-2" data-start="5" data-duration="5"></audio>';
+    const voice1 = timelineElement({ id: "voice-1", tag: "audio", track: 0, zIndex: 0 });
+    const voice2 = timelineElement({ id: "voice-2", tag: "audio", track: 1, zIndex: 0 });
+    usePlayerStore.getState().setElements([voice1, voice2]);
+    const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    const recordEdit = vi.fn(async () => {});
+    const showToast = vi.fn();
+    const fetchMock = stubProjectFetch(
+      '<audio id="voice-1" data-start="0" data-duration="5"></audio>' +
+        '<audio id="voice-2" data-start="5" data-duration="5"></audio>',
+    );
+    const hook = renderTimelineEditingHook({
+      timelineElements: [voice1, voice2],
+      iframe,
+      onZIndexCommit: vi.fn().mockResolvedValue(undefined),
+      projectId: "p1",
+      writeProjectFile,
+      recordEdit,
+      showToast,
+      canEdit: (element) =>
+        element.id === "voice-2" ? { blocked: true, reason: "Reserved by an agent" } : true,
+    });
+
+    await expect(
+      hook.handleAutoGroupCarveSources(["voice-1", "voice-2"], "voiceover"),
+    ).rejects.toThrow("Timeline edit blocked");
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    expect(recordEdit).not.toHaveBeenCalled();
+    expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
+    expect(doc.getElementById("voice-1")?.getAttribute("data-audio-group")).toBeNull();
+    expect(doc.getElementById("voiceover")).toBeNull();
+    hook.unmount();
+  });
+
+  it("reverts an optimistic group live value when the commit is refused", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const doc = iframe.contentDocument;
+    if (!doc) throw new Error("Expected iframe document");
+    doc.body.innerHTML =
+      '<hf-audio-group id="voiceover" data-volume="1"></hf-audio-group>' +
+      '<audio id="voice-1" data-start="0" data-duration="5"></audio>';
+    const member = {
+      ...timelineElement({ id: "voice-1", tag: "audio", track: 0, zIndex: 0 }),
+      audioGroup: "voiceover",
+      audioGroupVolume: 1,
+    };
+    usePlayerStore.getState().setElements([member]);
+    const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    const recordEdit = vi.fn(async () => {});
+    const showToast = vi.fn();
+    const hook = renderTimelineEditingHook({
+      timelineElements: [member],
+      iframe,
+      onZIndexCommit: vi.fn().mockResolvedValue(undefined),
+      projectId: "p1",
+      writeProjectFile,
+      recordEdit,
+      showToast,
+      canEdit: () => ({ blocked: true, reason: "Reserved by an agent" }),
+    });
+
+    await act(async () => {
+      hook.setAudioGroupAttribute.setLive("voiceover", "data-volume", "0.4");
+    });
+    expect(doc.getElementById("voiceover")?.getAttribute("data-volume")).toBe("0.4");
+    expect(usePlayerStore.getState().elements[0]?.audioGroupVolume).toBe(0.4);
+
+    await act(async () => {
+      await hook.setAudioGroupAttribute.setQuiet("voiceover", "data-volume", "0.4", "Set volume");
+    });
+
+    expect(doc.getElementById("voiceover")?.getAttribute("data-volume")).toBe("1");
+    expect(usePlayerStore.getState().elements[0]?.audioGroupVolume).toBe(1);
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    expect(recordEdit).not.toHaveBeenCalled();
+    expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
+    hook.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();
+  });
+});