@hyperframes/studio 0.8.108 → 0.8.109

package/src/hooks/useGsapScriptCommits.test.tsx

@@ -10,13 +10,16 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 const patchRuntimeTweenInPlace = vi.fn<(...args: unknown[]) => boolean>();
 const applySoftReload = vi.fn<(...args: unknown[]) => string>();
 const trackStudioEvent = vi.fn();
+const readNestedFiles = vi.fn<(...args: unknown[]) => unknown>(() => null);
 
 vi.mock("./gsapRuntimePatch", () => ({
   patchRuntimeTweenInPlace: (...args: unknown[]) => patchRuntimeTweenInPlace(...args),
 }));
-vi.mock("../utils/gsapSoftReload", () => ({
+vi.mock("../utils/gsapSoftReload", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../utils/gsapSoftReload")>()),
   applySoftReload: (...args: unknown[]) => applySoftReload(...args),
   extractGsapScriptText: () => "",
+  readNestedFiles: (...args: unknown[]) => readNestedFiles(...args),
 }));
 vi.mock("../utils/studioTelemetry", () => ({
   trackStudioEvent: (...args: unknown[]) => trackStudioEvent(...args),
@@ -364,6 +367,7 @@ let cleanup: (() => void) | null = null;
 function renderCommitHook(
   options: {
     writeProjectFile?: (path: string, content: string) => Promise<void>;
+    iframe?: HTMLIFrameElement;
   } = {},
 ) {
   const reloadPreview = vi.fn();
@@ -378,7 +382,7 @@ function renderCommitHook(
     captured.api = useGsapScriptCommits({
       projectIdRef: { current: "proj-1" },
       activeCompPath: "index.html",
-      previewIframeRef: { current: FAKE_IFRAME },
+      previewIframeRef: { current: options.iframe ?? FAKE_IFRAME },
       editHistory: { recordEdit },
       reloadPreview,
       onCacheInvalidate,
@@ -578,6 +582,7 @@ describe("runCommit — instantPatch wiring", () => {
     patchRuntimeTweenInPlace.mockReset();
     applySoftReload.mockReset();
     trackStudioEvent.mockReset();
+    readNestedFiles.mockReset().mockReturnValue(null);
   });
   afterEach(() => {
     cleanup?.();
@@ -585,6 +590,83 @@ describe("runCommit — instantPatch wiring", () => {
     vi.unstubAllGlobals();
   });
 
+  const NESTED_SCRIPT = 'window.__timelines["root"] = tl;';
+  const SUB = `<template><div data-composition-id="sub"><div id="nwid" style="left: 40px"></div></div></template>`;
+
+  // A preview whose top-level timeline tweens an element written in a nested composition file.
+  function nestedPreview(): HTMLIFrameElement {
+    const doc = document.implementation.createHTMLDocument("");
+    doc.body.innerHTML = `<div data-composition-id="root"><div data-composition-file="compositions/sub.html"><div id="nwid"></div></div></div>`;
+    const nwid = doc.getElementById("nwid")!;
+    const tween = { targets: () => [nwid], vars: { width: 400 } };
+    return {
+      contentDocument: doc,
+      contentWindow: { __timelines: { root: { getChildren: () => [tween] } } },
+    } as unknown as HTMLIFrameElement;
+  }
+
+  // The mutation endpoint answers the commit; the files endpoint serves the nested file, or fails.
+  function mockServer(fileOk: boolean): ReturnType<typeof vi.fn> {
+    const body = {
+      ok: true,
+      changed: true,
+      before: "BEFORE",
+      after: "AFTER",
+      scriptText: NESTED_SCRIPT,
+    };
+    const fetch = vi.fn(async (url: string) =>
+      url.includes("/files/")
+        ? ({ ok: fileOk, json: async () => ({ content: SUB }) } as unknown as Response)
+        : ({ ok: true, json: async () => body } as unknown as Response),
+    );
+    vi.stubGlobal("fetch", fetch);
+    return fetch;
+  }
+
+  async function useRealNestedRead() {
+    const actual =
+      await vi.importActual<typeof import("../utils/gsapSoftReload")>("../utils/gsapSoftReload");
+    readNestedFiles.mockImplementation((...args) =>
+      actual.readNestedFiles(...(args as Parameters<typeof actual.readNestedFiles>)),
+    );
+  }
+
+  it("hands the soft reload the nested composition file it read for a reset element", async () => {
+    await useRealNestedRead();
+    applySoftReload.mockReturnValue("applied");
+    const fetch = mockServer(true);
+    const deps = renderCommitHook({ iframe: nestedPreview() });
+
+    await act(async () => {
+      await deps.api.commitMutation(selection, { x: 10 }, { label: "drag", softReload: true });
+    });
+
+    expect(fetch).toHaveBeenCalledWith(expect.stringContaining("/files/compositions%2Fsub.html"));
+    expect(applySoftReload).toHaveBeenCalledWith(
+      expect.anything(),
+      NESTED_SCRIPT,
+      expect.objectContaining({ nestedFiles: new Map([["compositions/sub.html", SUB]]) }),
+    );
+  });
+
+  it("reloads the preview in full when that nested file cannot be read", async () => {
+    await useRealNestedRead();
+    applySoftReload.mockReturnValue("cannot-soft-reload");
+    mockServer(false);
+    const deps = renderCommitHook({ iframe: nestedPreview() });
+
+    await act(async () => {
+      await deps.api.commitMutation(selection, { x: 10 }, { label: "drag", softReload: true });
+    });
+
+    expect(applySoftReload).toHaveBeenCalledWith(
+      expect.anything(),
+      NESTED_SCRIPT,
+      expect.objectContaining({ nestedFiles: null }),
+    );
+    expect(deps.reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
   it("instantPatch succeeds: persists, invalidates cache, NO reload", async () => {
     patchRuntimeTweenInPlace.mockReturnValue(true);
     mockFetchResult();

package/src/hooks/useGsapScriptCommits.ts

@@ -3,7 +3,12 @@ import { findUnsafeMutationValues } from "@hyperframes/core/studio-api/finite-mu
 import { readProjectFileContent as readSharedProjectFileContent } from "../utils/studioFileHistory";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
-import { applySoftReload, extractGsapScriptText } from "../utils/gsapSoftReload";
+import {
+  applySoftReload,
+  extractGsapScriptText,
+  readNestedFiles,
+  settleNestedReads,
+} from "../utils/gsapSoftReload";
 import type { SoftReloadResult } from "../utils/gsapSoftReload";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { serializeStudioFileMutation } from "../utils/studioFileMutationCoordinator";
@@ -142,9 +147,10 @@ function refreshMutationPreview(
   options: CommitMutationOptions,
   reloadPreview: () => void,
   onCacheInvalidate: () => void,
+  nestedFiles?: Map<string, string> | null,
 ): void {
   options.beforeReload?.();
-  applyPreviewSync(iframe, result, options, reloadPreview);
+  applyPreviewSync(iframe, result, options, reloadPreview, nestedFiles);
   onCacheInvalidate();
 }
 
@@ -168,6 +174,7 @@ function syncCommittedGsapMutation({
   forceReloadSdkSession,
   reloadPreview,
   onCacheInvalidate,
+  nestedFiles,
 }: {
   iframe: HTMLIFrameElement | null;
   selection: DomEditSelection;
@@ -179,6 +186,7 @@ function syncCommittedGsapMutation({
   forceReloadSdkSession?: () => void;
   reloadPreview: () => void;
   onCacheInvalidate: () => void;
+  nestedFiles?: Map<string, string> | null;
 }): void {
   if (result.after != null) onFileContentChanged?.(targetPath, result.after);
   // Server wrote the file; the in-memory SDK doc is now stale. Resync it so a
@@ -196,7 +204,7 @@ function syncCommittedGsapMutation({
       iframe?.contentDocument,
     );
   }
-  refreshMutationPreview(iframe, result, options, reloadPreview, onCacheInvalidate);
+  refreshMutationPreview(iframe, result, options, reloadPreview, onCacheInvalidate, nestedFiles);
 }
 
 /**
@@ -219,6 +227,7 @@ function softReloadOrEscalate(
   reloadPreview: () => void,
   origin: "preview_sync" | "sdk_refresh",
   authoredHtml?: string,
+  nestedFiles?: Map<string, string> | null,
 ): void {
   // Seek the rebuilt timeline to the studio's own authoritative scrub position,
   // not the iframe's raw `__player.getTime()` — see the comment in
@@ -228,6 +237,7 @@ function softReloadOrEscalate(
     onAsyncFailure: reloadPreview,
     currentTimeOverride: currentTime,
     authoredHtml,
+    nestedFiles,
   });
   if (result === "applied") return;
   trackStudioEvent("gsap_soft_reload_outcome", {
@@ -252,6 +262,7 @@ export function applyPreviewSync(
   result: MutationResult,
   options: CommitMutationOptions,
   reloadPreview: () => void,
+  nestedFiles?: Map<string, string> | null,
 ): void {
   const patches = instantPatchesFor(options);
   let needsFallback = options.previewFallbackLatch?.pending === true;
@@ -297,6 +308,7 @@ export function applyPreviewSync(
       reloadPreview,
       "preview_sync",
       result.after ?? undefined,
+      nestedFiles,
     );
   } else {
     reloadPreview();
@@ -349,6 +361,13 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       return;
     }
     await recordMutationEdit(targetPath, result, options);
+    const nestedFiles = await settleNestedReads(
+      result.scriptText
+        ? readNestedFiles(previewIframeRef.current, result.scriptText, (path) =>
+            readSharedProjectFileContent(projectId, path),
+          )
+        : null,
+    );
     // The durable mutation belongs to the project captured when it was queued.
     // A later project must never receive its file state or preview refresh.
     if (!isActiveCommitTarget(projectIdRef, activeCompPathRef, projectId, compositionPath)) return;
@@ -363,6 +382,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       forceReloadSdkSession,
       reloadPreview,
       onCacheInvalidate,
+      nestedFiles,
     });
   }, [projectIdRef, previewIframeRef, reloadPreview, onCacheInvalidate, onFileContentChanged, forceReloadSdkSession, recordMutationEdit]);
 

package/src/hooks/usePreviewPersistence.history.test.tsx

@@ -45,3 +45,79 @@ describe("undo that reloads the preview", () => {
     expect([player.elements, player.timelineReady]).toEqual([clips, true]);
   });
 });
+
+describe("undo that re-runs the top-level script over an element of a nested composition", () => {
+  const script = (width: number) =>
+    `var tl = gsap.timeline({ paused: true }); tl.to("#nwid", { width: ${width} }); window.__timelines["root"] = tl;`;
+  const page = (width: number) =>
+    `<html><body><div id="root" data-composition-id="root"></div><script>${script(width)}</script></body></html>`;
+  const SUB = `<template><div data-composition-id="sub"><div id="nwid" data-hf-id="hf-n" style="left: 40px"></div></div></template>`;
+
+  // The live preview: the top-level timeline tweened the nested element's width inline.
+  function nestedPreview() {
+    const doc = document.implementation.createHTMLDocument("");
+    doc.body.innerHTML =
+      `<div id="root" data-composition-id="root"><div data-composition-file="compositions/sub.html">` +
+      `<div id="nwid" data-hf-id="hf-n" style="left: 40px; width: 337px"></div></div></div>` +
+      `<script>${script(400)}</script>`;
+    const nwid = doc.getElementById("nwid")!;
+    const contentWindow = {
+      gsap: { timeline: vi.fn(), set: vi.fn() },
+      __hfForceTimelineRebind: vi.fn(),
+      __timelines: {
+        root: {
+          kill: vi.fn(),
+          getChildren: () => [{ targets: () => [nwid], vars: { width: 400 } }],
+        },
+      } as Record<string, unknown>,
+      __player: { getTime: () => 1, seek: vi.fn() },
+      __hfStudioManualEditsApply: vi.fn(),
+    };
+    return {
+      iframe: { contentWindow, contentDocument: doc } as unknown as HTMLIFrameElement,
+      nwid,
+    };
+  }
+
+  async function undo(fileOk: boolean) {
+    const { iframe, nwid } = nestedPreview();
+    const reloadPreview = vi.fn();
+    const fetch = vi.fn(async () => ({ ok: fileOk, json: async () => ({ content: SUB }) }));
+    vi.stubGlobal("fetch", fetch);
+    usePlayerStore.getState().beginTimelineSession("p1");
+    let sync: ReturnType<typeof usePreviewPersistence>["syncHistoryPreviewAfterApply"] | null =
+      null;
+    function Harness() {
+      sync = usePreviewPersistence({
+        showToast: () => {},
+        readOptionalProjectFile: async () => "",
+        writeProjectFile: async () => {},
+        recordEdit: async () => {},
+        previewIframeRef: { current: iframe },
+        activeCompPathRef: { current: "index.html" },
+        reloadPreview,
+      }).syncHistoryPreviewAfterApply;
+      return null;
+    }
+    mountReactHarness(<Harness />);
+    const files = { "index.html": { previous: page(400), restored: page(450) } };
+    await act(async () => sync!({ paths: Object.keys(files), files }));
+    vi.unstubAllGlobals();
+    return { nwid, reloadPreview, fetch };
+  }
+
+  it("restores the element from its own composition file", async () => {
+    const { nwid, reloadPreview, fetch } = await undo(true);
+
+    expect(fetch).toHaveBeenCalledWith(expect.stringContaining("/files/compositions%2Fsub.html"));
+    expect(reloadPreview).not.toHaveBeenCalled();
+    expect(nwid.getAttribute("style")).toBe("left: 40px;");
+  });
+
+  it("reloads the preview in full when that file cannot be read", async () => {
+    const { nwid, reloadPreview } = await undo(false);
+
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    expect(nwid.getAttribute("style")).toBe("left: 40px; width: 337px");
+  });
+});

package/src/hooks/usePreviewPersistence.ts

@@ -14,9 +14,12 @@ import {
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import {
   applyUndoRestoreToPreview,
+  readUndoNestedFiles,
   showRestoreInPlace,
   type RestoreFiles,
 } from "../utils/gsapUndoRestore";
+import { settleNestedReads } from "../utils/gsapSoftReload";
+import { readProjectFileContent } from "../utils/studioFileHistory";
 import { usePlayerStore } from "../player";
 import { syncStoredAutomationFromPreview } from "../player/lib/automationStoreSync";
 
@@ -204,12 +207,24 @@ export function usePreviewPersistence({
       // attributes onto the live DOM and re-runs the timeline at the SAME playhead,
       // falling back to reloadPreview for anything structural (split/delete undo),
       // multi-file, sub-comp, or a permanent soft-reload failure.
+      const projectId = usePlayerStore.getState().timelineProjectId;
+      const nestedFiles = await settleNestedReads(
+        projectId
+          ? readUndoNestedFiles(
+              previewIframeRef.current,
+              activeCompPathRef.current,
+              restore.files,
+              (path) => readProjectFileContent(projectId, path),
+            )
+          : null,
+      );
       const strategy = applyUndoRestoreToPreview(
         previewIframeRef.current,
         activeCompPathRef.current,
         restore.files,
         usePlayerStore.getState().currentTime,
         reloadPreview,
+        nestedFiles,
       );
       if (strategy === "full") {
         usePlayerStore.getState().setSelectedElementId(null);

package/src/hooks/useRazorSplit.test.tsx

@@ -95,3 +95,51 @@ describe("useRazorSplit mutation versions", () => {
     container.remove();
   });
 });
+
+describe("useRazorSplit linked clips", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("splits every member of a linked pair in one cut", async () => {
+    const { usePlayerStore } = await import("../player");
+    const clip = (id: string, tag: string): TimelineElement => ({
+      id,
+      domId: id,
+      tag,
+      start: 0,
+      duration: 4,
+      track: tag === "audio" ? 1 : 0,
+      link: "lk-1",
+    });
+    const video = clip("talk", "video");
+    usePlayerStore.getState().setElements([video, clip("talk-audio", "audio")]);
+    const bodies: string[] = [];
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input, init) => {
+      const url = String(input);
+      if (url.includes("/files/")) return jsonResponse({ content: "", version: '"v0"' });
+      bodies.push(String(init?.body ?? ""));
+      return jsonResponse({ error: "stop" }, 409);
+    });
+    let split: ((element: TimelineElement, splitTime: number) => Promise<void>) | undefined;
+    const root = createRoot(document.body.appendChild(document.createElement("div")));
+    function Harness() {
+      split = useRazorSplit({
+        projectId: "p1",
+        activeCompPath: "index.html",
+        showToast: vi.fn(),
+        writeProjectFile: vi.fn(),
+        recordEdit: vi.fn(),
+        reloadPreview: vi.fn(),
+      }).handleRazorSplit;
+      return null;
+    }
+    await act(async () => root.render(React.createElement(Harness)));
+    await act(async () => {
+      await split?.(video, 2);
+    });
+    const targets = JSON.parse(bodies[0] ?? "{}").files[0].targets.map(
+      (cut: { originalId: string }) => cut.originalId,
+    );
+    expect(targets).toEqual(["talk", "talk-audio"]);
+    act(() => root.unmount());
+  });
+});

package/src/hooks/useRazorSplit.ts

@@ -4,6 +4,8 @@ import { usePlayerStore } from "../player";
 import { getTimelineElementLabel } from "../utils/studioHelpers";
 import { trackStudioRazorSplit } from "../telemetry/events";
 import { canSplitElementAt, selectSplittableElements } from "../utils/timelineElementSplit";
+import { linkedMembersOf } from "../player/components/audioClipLink";
+import { isLinkedSelectionOn } from "../utils/linkedClipPreferences";
 import { buildAtomicCutIntents, runAtomicCutTransaction } from "../utils/razorSplitTransaction";
 import type { RecordEditInput } from "./timelineEditingHelpers";
 import { useFreezeFrame } from "./useFreezeFrame";
@@ -103,7 +105,16 @@ export function useRazorSplit({
       }
       if (!canSplitElementAt(element, splitTime)) return;
       try {
-        const result = await runCut([element], splitTime, "single");
+        const members = linkedMembersOf(
+          element,
+          usePlayerStore.getState().elements,
+          isLinkedSelectionOn(),
+        );
+        const result = await runCut(
+          members.filter((member) => canSplitElementAt(member, splitTime)),
+          splitTime,
+          "single",
+        );
         if (!result) return;
         if (result.syncFailed) return;
         showToast(`Split ${getTimelineElementLabel(element)} at ${splitTime.toFixed(2)}s`, "info");

package/src/hooks/useRenderClipContent.test.ts

@@ -196,7 +196,7 @@ describe("useRenderClipContent", () => {
     }
   });
 
-  it("marks audio linked when a video clip uses the same file, and muted when hidden", () => {
+  it("marks hidden audio muted and leaves the link to the chain badge", () => {
     usePlayerStore.setState({
       thumbnailMode: "hidden",
       elements: [
@@ -217,11 +217,12 @@ describe("useRenderClipContent", () => {
       duration: 4,
       track: 1,
       src: "assets/clip.mp4",
+      link: "lk-1",
       hidden: true,
     });
-    expect(isValidElement<{ linked: boolean; muted: boolean }>(linked)).toBe(true);
-    if (isValidElement<{ linked: boolean; muted: boolean }>(linked)) {
-      expect(linked.props.linked).toBe(true);
+    expect(isValidElement<{ linked?: boolean; muted: boolean }>(linked)).toBe(true);
+    if (isValidElement<{ linked?: boolean; muted: boolean }>(linked)) {
+      expect(linked.props.linked).toBeUndefined();
       expect(linked.props.muted).toBe(true);
     }
   });
@@ -249,6 +250,7 @@ describe("useRenderClipContent", () => {
     expect(isValidElement<{ waveformUrl: string }>(waveform) && waveform.props.waveformUrl).toBe(
       "/api/projects/my-project/waveform/talk.mp4",
     );
+    expect(isValidElement<{ labelInset?: number }>(waveform) && waveform.props.labelInset).toBe(0);
   });
 
   it("keeps a muted or silent video to thumbnails only", () => {

package/src/hooks/useRenderClipContent.ts

@@ -63,6 +63,7 @@ function renderAudioClip(
   labelColor: string,
   context: TimelineClipRenderContext,
   elements: readonly TimelineElement[],
+  labelInset?: number,
 ): ReactNode {
   const audioUrl = resolveMediaPreviewUrl(el.src ?? "", pid, window.location.origin);
   const srcRelative = resolvePreviewRelative(audioUrl, pid, window.location.origin);
@@ -84,6 +85,7 @@ function renderAudioClip(
     projectId: pid,
     sessionEpoch,
     priority: context.priority,
+    labelInset,
     ...audioPillFlags(el, elements),
   });
   return createElement(
@@ -103,10 +105,10 @@ function renderAudioClip(
 function withSoundStrip(
   el: TimelineElement,
   thumbnail: ReactNode,
-  waveform: () => ReactNode,
+  waveform: (labelInset: number) => ReactNode,
 ): ReactNode {
   if (el.tag !== "video" || !clipHasSound(el)) return thumbnail;
-  return createElement(AudibleVideoClipContent, { thumbnail, waveform: waveform() });
+  return createElement(AudibleVideoClipContent, { thumbnail, waveform: waveform(0) });
 }
 
 export interface UseRenderClipContentOptions {
@@ -141,7 +143,8 @@ export function useRenderClipContent({
 
       // Thumbnail generation disabled (perf) -> plain clip bars. Audio still shows
       // its waveform (cheap, not a frame thumbnail). Toggle: timeline toolbar.
-      const waveform = () => renderAudioClip(el, pid, sessionEpoch, style.label, context, elements);
+      const waveform = (labelInset?: number) =>
+        renderAudioClip(el, pid, sessionEpoch, style.label, context, elements, labelInset);
       if (effectiveMode === "hidden") {
         return rendersWaveform(el) ? waveform() : withSoundStrip(el, null, waveform);
       }

package/src/hooks/useTimelineDeleteOps.ts

@@ -10,6 +10,7 @@ import { studioWriteHeaders } from "../utils/studioFileVersion";
 import { getTimelineElementLabel } from "../utils/studioHelpers";
 import { buildPatchTarget, removeIframeTimelineElements } from "./timelineEditingHelpers";
 import { captureDurationRollback } from "./timelineTimingSync";
+import { setLinkInSource } from "../components/editor/mediaLinkEdits";
 import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
 import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";
 import {
@@ -60,6 +61,11 @@ interface UseTimelineDeleteOpsOptions {
 // timelineGapCommit.ts.
 let deleteGestureSeq = 0;
 
+function unlinkInSource(source: string, survivors: readonly TimelineElement[]): string {
+  const targets = survivors.map(buildPatchTarget).filter((target) => target !== null);
+  return targets.length > 0 ? setLinkInSource(source, targets, null) : source;
+}
+
 export function useTimelineDeleteOps({
   projectIdRef,
   activeCompPath,
@@ -80,7 +86,7 @@ export function useTimelineDeleteOps({
   // fallow-ignore-next-line complexity
   const handleTimelineElementsDelete = useCallback(
     // fallow-ignore-next-line complexity
-    async (selection: TimelineElement[]) => {
+    async (selection: TimelineElement[], alsoUnlink: readonly TimelineElement[] = []) => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");
         return;
@@ -150,9 +156,9 @@ export function useTimelineDeleteOps({
               // Shrink to the furthest remaining clip end, read from the post-removal source:
               // store durations are runtime-truncated.
               const deleteContentEnd = furthestClipEndFromSource(removedContent);
-              const patchedContent = setCompositionDurationToContent(
-                removedContent,
-                deleteContentEnd,
+              const patchedContent = unlinkInSource(
+                setCompositionDurationToContent(removedContent, deleteContentEnd),
+                alsoUnlink,
               );
               // Optimistically reflect the shrunk length in the readout/seek bar,
               // rolling it back if the persist below fails (see captureDurationRollback).

package/src/hooks/useTimelineEditGuard.ts

@@ -0,0 +1,54 @@
+import { useCallback, useRef } from "react";
+import type { TimelineElement } from "../player";
+import { useTimelineEditRefusal } from "./timelineEditPermission";
+
+type GuardedTimelineHandler = (...args: never[]) => Promise<unknown>;
+type GuardedTimelineResolver = (...args: never[]) => readonly TimelineElement[];
+type GuardedTimelineRefusal = (reason: string, ...args: never[]) => unknown;
+
+interface GuardedTimelineEntry {
+  resolveTargets: GuardedTimelineResolver;
+  onRefused?: GuardedTimelineRefusal;
+  wrapped: GuardedTimelineHandler;
+}
+
+export function useTimelineEditGuard(
+  canEdit: Parameters<typeof useTimelineEditRefusal>[0],
+  showToast: Parameters<typeof useTimelineEditRefusal>[1],
+) {
+  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<unknown>>(
+      resolveTargets: (...args: Parameters<H>) => readonly TimelineElement[],
+      fn: H,
+      onRefused?: (reason: string, ...args: Parameters<H>) => Awaited<ReturnType<H>>,
+    ): H => {
+      const key = fn as unknown as GuardedTimelineHandler;
+      const cached = guardedRef.current.get(key);
+      if (cached) {
+        cached.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
+        cached.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
+        return cached.wrapped as H;
+      }
+      const entry = {} as GuardedTimelineEntry;
+      entry.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
+      entry.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
+      entry.wrapped = ((...args: Parameters<H>) => {
+        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);
+      return entry.wrapped as H;
+    },
+    [],
+  );
+  return guard;
+}