@hyperframes/studio 0.8.78 → 0.8.79

package/src/hooks/useElementPicker.ts

@@ -1,10 +1,18 @@
 import { useState, useCallback, useRef } from "react";
 import { useMountEffect } from "./useMountEffect";
-import { resolveSourceFile, applyPatch } from "../utils/sourcePatcher";
+import {
+  resolveSourceFile,
+  applyPatch,
+  applyPatchByTarget,
+  findTagByTarget,
+  type PatchOperation,
+} from "../utils/sourcePatcher";
 import {
   acceptStudioRuntimeMessage,
   postRuntimeControlMessage,
 } from "../player/lib/runtimeProtocol";
+import { compositionPathOfPreviewUrl } from "../player/components/CompositionThumbnail";
+import { getSourceFileForElement } from "../components/editor/domEditingDom";
 
 export interface PickedElement {
   id: string | null;
@@ -91,6 +99,8 @@ export function useElementPicker(
 
   // Listen for picker messages from the iframe
   useMountEffect(() => {
+    // One guard per message field, then one branch per message type.
+    // fallow-ignore-next-line complexity
     const handleMessage = (e: MessageEvent) => {
       const data = e.data;
       if (data?.source !== "hf-preview") return;
@@ -101,40 +111,13 @@ export function useElementPicker(
       if (e.source !== activeIframe.contentWindow && e.source !== iframeRef.current?.contentWindow)
         return;
 
-      if (data.type === "element-picked") {
-        const el = data.elementInfo;
-        if (el) {
-          const styles = readComputedStyles(activeIframe, el.selector);
-          setPickedElement({
-            id: el.id ?? null,
-            tagName: el.tagName ?? "div",
-            selector: el.selector ?? "",
-            label: el.label ?? el.tagName ?? "Element",
-            boundingBox: el.boundingBox ?? { x: 0, y: 0, width: 0, height: 0 },
-            textContent: el.textContent ?? null,
-            src: el.src ?? null,
-            dataAttributes: el.dataAttributes ?? {},
-            computedStyles: styles,
-          });
-          setIsPickMode(false);
-        }
+      if (data.type === "element-picked" && data.elementInfo) {
+        setPickedElement(toPickedElement(data.elementInfo, activeIframe));
+        setIsPickMode(false);
       } else if (data.type === "element-pick-candidates") {
         // Multiple candidates at click point — pick the first one
         const el = data.candidates?.[data.selectedIndex ?? 0];
-        if (el) {
-          const styles = readComputedStyles(activeIframe, el.selector);
-          setPickedElement({
-            id: el.id ?? null,
-            tagName: el.tagName ?? "div",
-            selector: el.selector ?? "",
-            label: el.label ?? el.tagName ?? "Element",
-            boundingBox: el.boundingBox ?? { x: 0, y: 0, width: 0, height: 0 },
-            textContent: el.textContent ?? null,
-            src: el.src ?? null,
-            dataAttributes: el.dataAttributes ?? {},
-            computedStyles: styles,
-          });
-        }
+        if (el) setPickedElement(toPickedElement(el, activeIframe));
       }
 
       if (data.type === "pick-mode-cancelled") {
@@ -149,29 +132,26 @@ export function useElementPicker(
   // Ref for options to avoid stale closures in debounced callback
   const optionsRef = useRef(options);
   optionsRef.current = options;
+  const pendingWritesRef = useRef(new Map<string, PendingWrite>());
+  settlePendingWrites(pendingWritesRef.current, options?.workspaceFiles);
 
   // Sync immediately (not debounced) — save on every change for reliability
   const syncToSource = useCallback(
-    (
-      elementId: string,
-      selector: string,
-      op: {
-        type: "inline-style" | "attribute" | "text-content";
-        property: string;
-        value: string;
-      },
-    ) => {
+    (picked: PickedElement, live: HTMLElement, iframe: HTMLIFrameElement, op: PatchOperation) => {
       const opts = optionsRef.current;
-      if (!opts?.workspaceFiles || !opts.onSyncFiles || !elementId) return;
-      const files = opts.workspaceFiles;
-      const sourceFile = resolveSourceFile(elementId, selector, files);
-      if (!sourceFile || !files[sourceFile]) {
-        return;
-      }
-      const patched = applyPatch(files[sourceFile], elementId, op);
-      if (patched !== files[sourceFile]) {
-        opts.onSyncFiles({ [sourceFile]: patched });
-      }
+      if (!opts?.workspaceFiles || !opts.onSyncFiles) return;
+      // No id: the preview's hf-id names the element, in the file it was served from.
+      const hfId = live.getAttribute("data-hf-id");
+      const pending = pendingWritesRef.current;
+      const files = withPendingWrites(opts.workspaceFiles, pending);
+      const patch = picked.id
+        ? patchById(files, picked.id, picked.selector, op)
+        : hfId
+          ? patchByHfId(files, hfId, ownSourceFile(live, iframe), op)
+          : null;
+      if (!patch || patch.after === patch.before) return;
+      recordPendingWrite(pending, patch.path, opts.workspaceFiles[patch.path], patch.after);
+      opts.onSyncFiles({ [patch.path]: patch.after });
     },
     [],
   );
@@ -193,32 +173,11 @@ export function useElementPicker(
                 }
               : null,
           );
-          // Persist to source file
-          if (pickedElement.id) {
-            // ID-based patching — surgical edit of just the element's style
-            syncToSource(pickedElement.id, pickedElement.selector, {
-              type: "inline-style",
-              property: prop,
-              value,
-            });
-          } else {
-            // No ID — save the full composition HTML from the iframe
-            // This captures ALL inline style changes, not just the targeted one
-            try {
-              const fullHtml = activeIframe.contentDocument?.documentElement.outerHTML;
-              if (fullHtml && optionsRef.current?.onSyncFiles) {
-                // Determine which file this iframe represents
-                const src = activeIframe.getAttribute("src") ?? "";
-                const compMatch = src.match(/\/comp\/(.+?)(?:\?|$)/);
-                const filePath = compMatch ? compMatch[1] : "index.html";
-                optionsRef.current.onSyncFiles({
-                  [filePath]: `<!DOCTYPE html>\n<html>${fullHtml.replace(/<html[^>]*>/, "")}`,
-                });
-              }
-            } catch {
-              /* cross-origin */
-            }
-          }
+          syncToSource(pickedElement, el, activeIframe, {
+            type: "inline-style",
+            property: prop,
+            value,
+          });
         }
       } catch {
         /* cross-origin */
@@ -244,14 +203,11 @@ export function useElementPicker(
                 }
               : null,
           );
-          // Persist to source file immediately
-          if (pickedElement.id) {
-            syncToSource(pickedElement.id, pickedElement.selector, {
-              type: "attribute",
-              property: attr,
-              value,
-            });
-          }
+          syncToSource(pickedElement, el as HTMLElement, activeIframe, {
+            type: "attribute",
+            property: attr,
+            value,
+          });
         }
       } catch {
         /* cross-origin */
@@ -270,14 +226,11 @@ export function useElementPicker(
         if (el) {
           el.textContent = text;
           setPickedElement((prev) => (prev ? { ...prev, textContent: text } : null));
-          // Persist to source file
-          if (pickedElement.id) {
-            syncToSource(pickedElement.id, pickedElement.selector, {
-              type: "text-content",
-              property: "textContent",
-              value: text,
-            });
-          }
+          syncToSource(pickedElement, el as HTMLElement, activeIframe, {
+            type: "text-content",
+            property: "textContent",
+            value: text,
+          });
         }
       } catch {
         /* cross-origin */
@@ -305,6 +258,101 @@ export function useElementPicker(
   };
 }
 
+type PickedElementInfo = Partial<Omit<PickedElement, "computedStyles">>;
+
+// workspaceFiles lags this hook's own writes until the host rerenders.
+interface PendingWrite {
+  hostSource: string | undefined;
+  writes: string[];
+}
+
+function settlePendingWrites(
+  pending: Map<string, PendingWrite>,
+  files: Record<string, string> | undefined,
+): void {
+  for (const [path, write] of pending) {
+    const hostSource = files?.[path];
+    if (hostSource === write.hostSource) continue;
+    const caughtUpTo = hostSource === undefined ? -1 : write.writes.indexOf(hostSource);
+    if (caughtUpTo < 0 || caughtUpTo === write.writes.length - 1) {
+      pending.delete(path);
+    } else {
+      write.hostSource = hostSource;
+      write.writes = write.writes.slice(caughtUpTo + 1);
+    }
+  }
+}
+
+function withPendingWrites(
+  files: Record<string, string>,
+  pending: Map<string, PendingWrite>,
+): Record<string, string> {
+  const merged = { ...files };
+  for (const [path, write] of pending) merged[path] = write.writes.at(-1) ?? merged[path];
+  return merged;
+}
+
+function recordPendingWrite(
+  pending: Map<string, PendingWrite>,
+  path: string,
+  hostSource: string | undefined,
+  after: string,
+): void {
+  const write = pending.get(path) ?? { hostSource, writes: [] };
+  write.writes.push(after);
+  pending.set(path, write);
+}
+
+// A default per field of the runtime's element info.
+// fallow-ignore-next-line complexity
+function toPickedElement(el: PickedElementInfo, iframe: HTMLIFrameElement): PickedElement {
+  return {
+    id: el.id ?? null,
+    tagName: el.tagName ?? "div",
+    selector: el.selector ?? "",
+    label: el.label ?? el.tagName ?? "Element",
+    boundingBox: el.boundingBox ?? { x: 0, y: 0, width: 0, height: 0 },
+    textContent: el.textContent ?? null,
+    src: el.src ?? null,
+    dataAttributes: el.dataAttributes ?? {},
+    computedStyles: readComputedStyles(iframe, el.selector ?? ""),
+  };
+}
+
+interface SourcePatch {
+  path: string;
+  before: string;
+  after: string;
+}
+
+function patchById(
+  files: Record<string, string>,
+  id: string,
+  selector: string,
+  op: PatchOperation,
+): SourcePatch | null {
+  const path = resolveSourceFile(id, selector, files);
+  const before = path ? files[path] : undefined;
+  return path && before ? { path, before, after: applyPatch(before, id, op) } : null;
+}
+
+function ownSourceFile(live: HTMLElement, iframe: HTMLIFrameElement): string {
+  const previewed = compositionPathOfPreviewUrl(iframe.getAttribute("src") ?? "");
+  return getSourceFileForElement(live, previewed).sourceFile;
+}
+
+function patchByHfId(
+  files: Record<string, string>,
+  hfId: string,
+  ownFile: string,
+  op: PatchOperation,
+): SourcePatch | null {
+  const matches = Object.keys(files).filter((file) => findTagByTarget(files[file] ?? "", { hfId }));
+  const path = matches.includes(ownFile) ? ownFile : matches.length === 1 ? matches[0] : undefined;
+  const before = path ? files[path] : undefined;
+  return path && before ? { path, before, after: applyPatchByTarget(before, { hfId }, op) } : null;
+}
+
 /** Read a subset of computed styles from an element in the iframe */
 function readComputedStyles(iframe: HTMLIFrameElement, selector: string): Record<string, string> {
   const styles: Record<string, string> = {};

package/src/hooks/useFrameCapture.test.tsx

@@ -0,0 +1,67 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { liveTime, usePlayerStore } from "../player";
+import { useFrameCapture } from "./useFrameCapture";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let renders = 0;
+let capture: ReturnType<typeof useFrameCapture>;
+
+function Harness() {
+  renders += 1;
+  capture = useFrameCapture({
+    projectId: "p",
+    activeCompPath: null,
+    showToast: () => {},
+    waitForPendingDomEditSaves: async () => {},
+  });
+  return null;
+}
+
+const shownTime = () => new URL(capture.captureFrameHref).searchParams.get("t");
+
+let host: HTMLDivElement;
+let root: Root;
+
+beforeEach(async () => {
+  usePlayerStore.setState({ isPlaying: false, currentTime: 2 });
+  renders = 0;
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  await act(async () => root.render(React.createElement(Harness)));
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+  host.remove();
+});
+
+describe("useFrameCapture", () => {
+  it("does not re-render on playback frames", () => {
+    usePlayerStore.setState({ isPlaying: true });
+    const before = renders;
+    act(() => {
+      for (let i = 1; i <= 30; i++) liveTime.notify(2 + i / 60);
+    });
+    expect(renders).toBe(before);
+  });
+
+  it("points the capture at the live playhead while playing", () => {
+    usePlayerStore.setState({ isPlaying: true });
+    act(() => liveTime.notify(7.5));
+    act(() => capture.refreshCaptureFrameTime());
+    expect(shownTime()).toBe("7.500");
+  });
+
+  it("points the capture at the store time while paused", () => {
+    act(() => liveTime.notify(7.5));
+    usePlayerStore.setState({ isPlaying: false, currentTime: 3 });
+    act(() => capture.refreshCaptureFrameTime());
+    expect(shownTime()).toBe("3.000");
+  });
+});

package/src/hooks/useFrameCapture.ts

@@ -16,19 +16,28 @@ export function useFrameCapture({
   showToast,
   waitForPendingDomEditSaves,
 }: UseFrameCaptureParams) {
-  const [captureFrameTime, setCaptureFrameTime] = useState(0);
+  const [captureFrameTime, setCaptureFrameTime] = useState(
+    () => usePlayerStore.getState().currentTime,
+  );
   const [capturing, setCapturing] = useState(false);
   const capturingRef = useRef(false);
+  const livePlayheadRef = useRef(captureFrameTime);
 
-  useMountEffect(() => {
-    setCaptureFrameTime(usePlayerStore.getState().currentTime);
-    return liveTime.subscribe(setCaptureFrameTime);
-  });
+  useMountEffect(() =>
+    liveTime.subscribe((time) => {
+      livePlayheadRef.current = time;
+    }),
+  );
 
-  const refreshCaptureFrameTime = useCallback(() => {
-    setCaptureFrameTime(usePlayerStore.getState().currentTime);
+  const playheadTime = useCallback(() => {
+    const { isPlaying, currentTime } = usePlayerStore.getState();
+    return isPlaying ? livePlayheadRef.current : currentTime;
   }, []);
 
+  const refreshCaptureFrameTime = useCallback(() => {
+    setCaptureFrameTime(playheadTime());
+  }, [playheadTime]);
+
   const handleCaptureFrameClick = useCallback(
     async (event: MouseEvent<HTMLAnchorElement>) => {
       if (!projectId) return;
@@ -39,7 +48,7 @@ export function useFrameCapture({
       capturingRef.current = true;
       setCapturing(true);
       try {
-        const time = usePlayerStore.getState().currentTime;
+        const time = playheadTime();
         setCaptureFrameTime(time);
         await Promise.race([
           waitForPendingDomEditSaves(),
@@ -91,7 +100,7 @@ export function useFrameCapture({
         setCapturing(false);
       }
     },
-    [activeCompPath, projectId, showToast, waitForPendingDomEditSaves],
+    [activeCompPath, playheadTime, projectId, showToast, waitForPendingDomEditSaves],
   );
 
   const captureFrameHref = projectId

package/src/hooks/usePersistentEditHistory.test.ts

@@ -1,4 +1,5 @@
 // @vitest-environment happy-dom
+// fallow-ignore-file code-duplication
 import { act, createElement } from "react";
 import { createRoot } from "react-dom/client";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -103,8 +104,7 @@ it("a drag's edits under one key undo as one step, even before the drag goes idl
       }),
     );
   }
-  // The held drag is not in the history's list yet: only its own paths say what to read before the step.
-  expect(hook().undoLabel).toBeUndefined();
+  await vi.waitFor(() => expect(hook().undoLabel).toBe("Dragged Title"));
   const undone = await act(() => hook().undo({ readFile }));
   expect(undone).toMatchObject({
     ok: true,

package/src/hooks/usePersistentEditHistory.ts

@@ -120,11 +120,11 @@ function redoneAt(view: HistoryView): number | null {
   return view.entries.find((entry) => entry.id === undo?.undoes)?.endedAt ?? null;
 }
 
-/** Studio's undo over the server's project history: an edit claims what it wrote; Cmd+Z steps every writer's. */
+/** Studio's undo over the server's project history: an edit claims what it wrote; Cmd+Z steps the person's. */
 export function usePersistentEditHistory({ projectId }: UsePersistentEditHistoryOptions) {
   const [view, setView] = useState<HistoryView>(EMPTY);
   const [loaded, setLoaded] = useState(false);
-  // A coalescing claim stays on the server until its drag goes idle, so it is not in `view` yet.
+  // A coalescing claim the server just took, until `refresh()` brings its entry into `view`.
   const heldClaimRef = useRef<{ paths: string[]; at: number } | null>(null);
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;

package/src/hooks/useTimelineEditing.test.tsx

@@ -131,6 +131,7 @@ function renderTimelineEditingHook(input: {
   elementsDelete: ReturnType<typeof useTimelineEditing>["handleTimelineElementsDelete"];
   handleAutoGroupCarveSources: ReturnType<typeof useTimelineEditing>["handleAutoGroupCarveSources"];
   setAudioGroupAttribute: ReturnType<typeof useTimelineEditing>["setAudioGroupAttribute"];
+  setElementFxAttribute: ReturnType<typeof useTimelineEditing>["setElementFxAttribute"];
   unmount: () => void;
 } {
   let move: ReturnType<typeof useTimelineEditing>["handleTimelineElementMove"] | null = null;
@@ -146,6 +147,7 @@ function renderTimelineEditingHook(input: {
   let setAudioGroupAttribute:
     | ReturnType<typeof useTimelineEditing>["setAudioGroupAttribute"]
     | null = null;
+  let latest: ReturnType<typeof useTimelineEditing> | null = null;
 
   function Harness() {
     const commitRef = useRef(input.onZIndexCommit);
@@ -176,6 +178,7 @@ function renderTimelineEditingHook(input: {
     elementsDelete = hook.handleTimelineElementsDelete;
     handleAutoGroupCarveSources = hook.handleAutoGroupCarveSources;
     setAudioGroupAttribute = hook.setAudioGroupAttribute;
+    latest = hook;
     return null;
   }
 
@@ -197,6 +200,8 @@ function renderTimelineEditingHook(input: {
     elementsDelete,
     handleAutoGroupCarveSources,
     setAudioGroupAttribute,
+    setElementFxAttribute: (latest as unknown as ReturnType<typeof useTimelineEditing>)
+      .setElementFxAttribute,
     unmount,
   };
 }
@@ -1910,3 +1915,57 @@ describe("useTimelineEditing: handler identity is stable across renders", () =>
     unmount();
   });
 });
+
+describe("useTimelineEditing effect saves report what happened", () => {
+  const LOCKED = { blocked: true as const, reason: "Reserved by an agent" };
+
+  it("resolves a saved clip effect as saved", async () => {
+    const { clip, setElementFxAttribute, writeProjectFile, unmount } = setupSingleClipHarness();
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await setElementFxAttribute.setQuiet(clip, "data-hf-audio-fx", "echo", "Apply");
+    });
+    expect(outcome).toEqual({ status: "saved" });
+    expect(writeProjectFile).toHaveBeenCalled();
+    unmount();
+  });
+
+  it("resolves a clip effect on a locked clip as refused, with the host's reason", async () => {
+    const { clip, setElementFxAttribute, writeProjectFile, unmount } = setupSingleClipHarness({
+      canEdit: () => LOCKED,
+    });
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await setElementFxAttribute.setQuiet(clip, "data-hf-audio-fx", "echo", "Apply");
+    });
+    expect(outcome).toEqual({ status: "refused", reason: "Reserved by an agent" });
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("resolves a clip effect whose write fails as failed", async () => {
+    const { clip, setElementFxAttribute, writeProjectFile, unmount } = setupSingleClipHarness();
+    writeProjectFile.mockRejectedValue(new Error("disk full"));
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await setElementFxAttribute.setQuiet(clip, "data-hf-audio-fx", "echo", "Apply");
+    });
+    expect(outcome).toEqual({ status: "failed", reason: expect.stringContaining("disk full") });
+    unmount();
+  });
+
+  it("resolves a group audio effect on a locked group as refused", async () => {
+    const member = timelineElement({ id: "clip", track: 0, zIndex: 0 });
+    usePlayerStore.getState().setElements([{ ...member, audioGroup: "hf-group" }]);
+    const { setAudioGroupAttribute, writeProjectFile, unmount } = setupSingleClipHarness({
+      canEdit: () => LOCKED,
+    });
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await setAudioGroupAttribute.setQuiet("hf-group", "data-volume", "0.5", "Volume");
+    });
+    expect(outcome).toEqual({ status: "refused", reason: "Reserved by an agent" });
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    unmount();
+  });
+});

package/src/hooks/useTimelineEditing.ts

@@ -33,15 +33,19 @@ import {
 } from "./timelineTrackVisibility";
 import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
 import { useBlockedTimelineEditToast } from "./useBlockedTimelineEditToast";
-import { useTimelineEditGate } from "./timelineEditPermission";
+import {
+  useTimelineEditGate,
+  useTimelineEditRefusal,
+  type TimelineEditOutcome,
+} from "./timelineEditPermission";
 import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
 import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
 import type { TimelineMoveUpdates, UseTimelineEditingOptions } from "./useTimelineEditingTypes";
 import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
 
-type GuardedTimelineHandler = (...args: never[]) => Promise<void>;
+type GuardedTimelineHandler = (...args: never[]) => Promise<unknown>;
 type GuardedTimelineResolver = (...args: never[]) => readonly TimelineElement[];
-type GuardedTimelineRefusal = (...args: never[]) => void;
+type GuardedTimelineRefusal = (reason: string, ...args: never[]) => unknown;
 
 interface GuardedTimelineEntry {
   resolveTargets: GuardedTimelineResolver;
@@ -74,17 +78,18 @@ export function useTimelineEditing({
   const editQueueRef = useRef(Promise.resolve());
   const track = useTrackPendingTimelineEdit();
   const checkEditable = useTimelineEditGate(canEdit, showToast);
-  const checkEditableRef = useRef(checkEditable);
-  checkEditableRef.current = checkEditable;
+  const refuseEdit = useTimelineEditRefusal(canEdit, showToast);
+  const refuseEditRef = useRef(refuseEdit);
+  refuseEditRef.current = refuseEdit;
   const guardedRef = useRef(new WeakMap<GuardedTimelineHandler, GuardedTimelineEntry>());
   // 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>>(
+    <H extends (...args: never[]) => Promise<unknown>>(
       resolveTargets: (...args: Parameters<H>) => readonly TimelineElement[],
       fn: H,
-      onRefused?: (...args: Parameters<H>) => void,
+      onRefused?: (reason: string, ...args: Parameters<H>) => Awaited<ReturnType<H>>,
     ): H => {
       const key = fn as unknown as GuardedTimelineHandler;
       const cached = guardedRef.current.get(key);
@@ -97,10 +102,9 @@ export function useTimelineEditing({
       entry.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
       entry.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
       entry.wrapped = ((...args: Parameters<H>) => {
-        if (!checkEditableRef.current(entry.resolveTargets(...(args as never[])))) {
-          entry.onRefused?.(...(args as never[]));
-          return Promise.resolve();
-        }
+        const reason = refuseEditRef.current(entry.resolveTargets(...(args as never[])));
+        if (reason !== null)
+          return Promise.resolve(entry.onRefused?.(reason, ...(args as never[])));
         return fn(...args);
       }) as H as unknown as GuardedTimelineHandler;
       guardedRef.current.set(key, entry);
@@ -500,6 +504,25 @@ export function useTimelineEditing({
     forceReloadSdkSession,
   });
 
+  const refused = (reason: string): TimelineEditOutcome => ({ status: "refused", reason });
+  const audioGroupMembers = (groupId: string): TimelineElement[] => {
+    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];
+  };
+
   // 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.
@@ -526,27 +549,10 @@ export function useTimelineEditing({
       // (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,
-          (groupId, attr) => revertAudioGroupLive(groupId, attr),
-        ),
+        guard(audioGroupMembers, setAudioGroupAttribute.setQuiet, (reason, groupId, attr) => {
+          revertAudioGroupLive(groupId, attr);
+          return refused(reason);
+        }),
       ),
     },
     setElementFxAttribute: {
@@ -555,7 +561,10 @@ export function useTimelineEditing({
         guard(
           (element) => [element],
           setElementFxAttribute.setQuiet,
-          (element, attr) => revertElementFxLive(element, attr),
+          (reason, element, attr) => {
+            revertElementFxLive(element, attr);
+            return refused(reason);
+          },
         ),
       ),
     },

package/src/index.ts

@@ -162,6 +162,7 @@ export type { StudioPendingEditsDrainResult } from "./utils/studioPendingEdits";
 export type {
   CanEditTimelineElement,
   TimelineEditPermission,
+  TimelineEditOutcome,
 } from "./hooks/timelineEditPermission";
 export { useEditHistoryActions } from "./hooks/useEditHistoryActions";
 export type {