@hyperframes/studio 0.8.53 → 0.8.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.53",
+  "version": "0.8.55",
   "description": "",
   "repository": {
     "type": "git",
@@ -51,11 +51,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.53",
-    "@hyperframes/sdk": "0.8.53",
-    "@hyperframes/player": "0.8.53",
-    "@hyperframes/parsers": "0.8.53",
-    "@hyperframes/studio-server": "0.8.53"
+    "@hyperframes/core": "0.8.55",
+    "@hyperframes/sdk": "0.8.55",
+    "@hyperframes/parsers": "0.8.55",
+    "@hyperframes/studio-server": "0.8.55",
+    "@hyperframes/player": "0.8.55"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -71,7 +71,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.53"
+    "@hyperframes/producer": "0.8.55"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/nle/TimelinePane.tsx

@@ -1,6 +1,6 @@
 import { useCallback, type ReactNode } from "react";
 import { Timeline } from "../../player";
-import type { TimelineElement } from "../../player";
+import type { TimelineElement, TimelineTimeRange } from "../../player";
 import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
 import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
 import { trackStudioExpandedClipEdit } from "../../telemetry/events";
@@ -77,6 +77,9 @@ export interface TimelinePaneProps {
   timelineToolbar?: ReactNode;
   /** Slot rendered below the timeline tracks */
   timelineFooter?: ReactNode;
+  /** Slot for a host's own overlay spanning the whole timeline area (e.g. a draft/ghost
+   *  clip), positioned absolutely the same way PreviewPane's previewOverlay is. */
+  timelineOverlay?: ReactNode;
   /** Custom clip content renderer for timeline (thumbnails, waveforms, etc.) */
   renderClipContent?: (
     element: TimelineElement,
@@ -101,6 +104,7 @@ export interface TimelinePaneProps {
   ) => Promise<void> | void;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   onSelectTimelineElement?: (element: TimelineElement | null) => void;
+  onRangeSelect?: (range: TimelineTimeRange | null) => void;
   /** Copy/paste/duplicate act on the store's own selection, not a passed
    *  element, so unlike onDeleteElement they need no composition-basis wrapper. */
   onCopyClip?: () => boolean;
@@ -113,6 +117,7 @@ export interface TimelinePaneProps {
 export function TimelinePane({
   timelineToolbar,
   timelineFooter,
+  timelineOverlay,
   renderClipContent,
   onFileDrop,
   onDeleteElement,
@@ -121,6 +126,7 @@ export function TimelinePane({
   onCompositionDrop,
   onBlockedEditAttempt,
   onSelectTimelineElement,
+  onRangeSelect,
   onCopyClip,
   onPasteClip,
   onDuplicateClip,
@@ -278,6 +284,7 @@ export function TimelinePane({
           onBlockedEditAttempt={onBlockedEditAttempt}
           onSplitElement={handleSplitElement}
           onSelectElement={onSelectTimelineElement}
+          onRangeSelect={onRangeSelect}
           onCopyClip={onCopyClip}
           onPasteClip={onPasteClip}
           onDuplicateClip={onDuplicateClip}
@@ -285,6 +292,9 @@ export function TimelinePane({
         />
       </div>
       {timelineFooter && <div className="shrink-0">{timelineFooter}</div>}
+      {timelineOverlay && (
+        <div className="pointer-events-none absolute inset-0 z-20">{timelineOverlay}</div>
+      )}
       {timelineDisabled && (
         <div
           className="absolute inset-0 z-30 cursor-not-allowed bg-black/18 flex items-center justify-center"

package/src/hooks/gsapDragCommit.ts

@@ -135,7 +135,7 @@ export async function materializeIfDynamic(
   void iframe;
   void commitMutation;
   void selection;
-  throw new GsapEditBlockedError("source-uneditable");
+  throw new GsapEditBlockedError("source-uneditable", "geometry-unresolved-source");
 }
 
 // ── Drag → GSAP position math ──────────────────────────────────────────────

package/src/hooks/gsapEditOutcome.test.ts

@@ -0,0 +1,115 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { describe, expect, it } from "vitest";
+import { buildStudioSaveFailureProperties } from "../utils/studioSaveDiagnostics";
+import {
+  GsapEditBlockedError,
+  assertGsapEditPersisted,
+  directEditOutcomeForProperties,
+} from "./gsapEditOutcome";
+
+function blockDetailFor(error: unknown): unknown {
+  return buildStudioSaveFailureProperties({ source: "gsap_commit", error }).block_detail;
+}
+
+/** Minimal animation that writes `x`, so the editability check actually runs. */
+function animation(overrides: Partial<GsapAnimation> = {}): GsapAnimation {
+  return {
+    id: "a1",
+    targetSelector: "#box",
+    method: "to",
+    position: 0,
+    properties: { x: 100 },
+    ...overrides,
+  } as GsapAnimation;
+}
+
+const POSITION = new Set(["x"]);
+
+describe("a blocked GSAP edit names which of the nine causes it hit", () => {
+  // The three causes inside assertGsapAnimationDirectlyEditable share one
+  // message, so only the detail distinguishes them. Asserted through the
+  // exported wrapper because that is the path a real edit takes — and the
+  // wrapper used to rebuild the outcome from `reason` alone, dropping it.
+  it("reports a runtime-dynamic provenance", () => {
+    const outcome = directEditOutcomeForProperties(
+      [animation({ provenance: { kind: "runtime-dynamic" } })],
+      POSITION,
+    );
+    expect(outcome).toEqual({
+      status: "blocked",
+      reason: "source-uneditable",
+      detail: "provenance-runtime-dynamic",
+    });
+  });
+
+  it("reports unresolved keyframes separately from provenance", () => {
+    const outcome = directEditOutcomeForProperties(
+      [animation({ hasUnresolvedKeyframes: true })],
+      POSITION,
+    );
+    expect(outcome).toEqual({
+      status: "blocked",
+      reason: "source-uneditable",
+      detail: "unresolved-keyframes",
+    });
+  });
+
+  it("reports an unresolved selector separately from provenance", () => {
+    const outcome = directEditOutcomeForProperties(
+      [animation({ hasUnresolvedSelector: true })],
+      POSITION,
+    );
+    expect(outcome).toEqual({
+      status: "blocked",
+      reason: "source-uneditable",
+      detail: "unresolved-selector",
+    });
+  });
+
+  it("still routes a helper or loop to unroll, which has its own message", () => {
+    const outcome = directEditOutcomeForProperties(
+      [animation({ provenance: { kind: "loop" } })],
+      POSITION,
+    );
+    expect(outcome).toEqual({ status: "blocked", reason: "unroll-required", detail: undefined });
+  });
+
+  it("leaves a literal tween editable", () => {
+    expect(directEditOutcomeForProperties([animation()], POSITION)).toEqual({
+      status: "persisted",
+    });
+  });
+
+  it("carries the detail through a returned outcome, not just a thrown one", () => {
+    // gsapRuntimeBridge returns blocked outcomes rather than throwing.
+    expect(() =>
+      assertGsapEditPersisted({
+        status: "blocked",
+        reason: "source-uneditable",
+        detail: "no-position-tween",
+      }),
+    ).toThrow(
+      expect.objectContaining({ name: "GsapEditBlockedError", detail: "no-position-tween" }),
+    );
+  });
+
+  it("surfaces the detail on the telemetry payload", () => {
+    expect(
+      blockDetailFor(
+        new GsapEditBlockedError("source-uneditable", "live-rotation-no-source-tween"),
+      ),
+    ).toBe("live-rotation-no-source-tween");
+  });
+
+  it("omits the detail for a block that has no specific cause", () => {
+    expect(blockDetailFor(new GsapEditBlockedError("no-selector"))).toBeUndefined();
+  });
+
+  it("ignores a detail-shaped field on an error that is not a block", () => {
+    // Guards the name check: any error can carry a `detail`, and reporting a
+    // save failure's detail as a block cause would be a silent mislabel.
+    const impostor = Object.assign(new Error("network down"), { detail: "unresolved-selector" });
+    expect(blockDetailFor(impostor)).toBeUndefined();
+    expect(blockDetailFor("not an error")).toBeUndefined();
+  });
+});

package/src/hooks/gsapEditOutcome.ts

@@ -2,6 +2,27 @@ import { editabilityForProvenance, type GsapAnimation } from "@hyperframes/core/
 
 export type GsapEditBlockReason = "no-selector" | "unroll-required" | "source-uneditable";
 
+/**
+ * Which of the nine situations produced a block. The user-facing `reason` stays
+ * coarse — three messages — but "source-uneditable" alone covers nine distinct
+ * causes, and `edit_blocked` telemetry could not tell them apart. That matters
+ * because the copy ("This animation is computed at runtime") is only literally
+ * true for `provenance-runtime-dynamic`; the others are parser or source-match
+ * limits, where the animation may well be plain authored source.
+ *
+ * Telemetry only. Nothing branches on it.
+ */
+export type GsapEditBlockDetail =
+  | "provenance-runtime-dynamic"
+  | "unresolved-keyframes"
+  | "unresolved-selector"
+  | "geometry-unresolved-source"
+  | "live-position-no-source-tween"
+  | "no-position-tween"
+  | "live-rotation-no-source-tween"
+  | "live-resize-no-source-tween"
+  | "zero-duration-tween";
+
 export type GsapEditOutcome =
   | {
       status: "persisted";
@@ -22,7 +43,7 @@ export type GsapEditOutcome =
        */
       ownsDragOffset?: boolean;
     }
-  | { status: "blocked"; reason: GsapEditBlockReason };
+  | { status: "blocked"; reason: GsapEditBlockReason; detail?: GsapEditBlockDetail };
 
 const COPY: Record<GsapEditBlockReason, string> = {
   "no-selector": "This layer needs a stable selector before Studio can save the edit.",
@@ -32,25 +53,32 @@ const COPY: Record<GsapEditBlockReason, string> = {
 };
 
 export class GsapEditBlockedError extends Error {
-  constructor(readonly reason: GsapEditBlockReason) {
+  constructor(
+    readonly reason: GsapEditBlockReason,
+    readonly detail?: GsapEditBlockDetail,
+  ) {
     super(COPY[reason]);
     this.name = "GsapEditBlockedError";
   }
 }
 
 export function assertGsapEditPersisted(outcome: GsapEditOutcome): void {
-  if (outcome.status === "blocked") throw new GsapEditBlockedError(outcome.reason);
+  if (outcome.status === "blocked") throw new GsapEditBlockedError(outcome.reason, outcome.detail);
 }
 
 function assertGsapAnimationDirectlyEditable(animation: GsapAnimation): void {
   const editability = editabilityForProvenance(animation.provenance);
   if (editability === "unroll") throw new GsapEditBlockedError("unroll-required");
-  if (
-    editability === "source" ||
-    animation.hasUnresolvedKeyframes ||
-    animation.hasUnresolvedSelector
-  ) {
-    throw new GsapEditBlockedError("source-uneditable");
+  // Same message for all three, but they are different problems: only the first
+  // is genuinely a runtime-computed value.
+  if (editability === "source") {
+    throw new GsapEditBlockedError("source-uneditable", "provenance-runtime-dynamic");
+  }
+  if (animation.hasUnresolvedKeyframes) {
+    throw new GsapEditBlockedError("source-uneditable", "unresolved-keyframes");
+  }
+  if (animation.hasUnresolvedSelector) {
+    throw new GsapEditBlockedError("source-uneditable", "unresolved-selector");
   }
 }
 
@@ -84,7 +112,8 @@ export function directEditOutcomeForProperties(
     }
     return { status: "persisted" };
   } catch (error) {
-    if (isGsapEditBlockedError(error)) return { status: "blocked", reason: error.reason };
+    if (isGsapEditBlockedError(error))
+      return { status: "blocked", reason: error.reason, detail: error.detail };
     throw error;
   }
 }

package/src/hooks/gsapResizeIntercept.test.ts

@@ -180,11 +180,15 @@ it("reuses the ownership parse instead of fetching a resolved size group twice",
   );
 });
 
-it("blocks when runtime size motion exists but the authored tween cannot be resolved", async () => {
+function makeBoxSelection(): { el: HTMLElement; selection: DomEditSelection } {
   const el = document.createElement("div");
   el.id = "box";
   document.body.append(el);
-  const selection = { id: "box", selector: "#box", element: el } as DomEditSelection;
+  return { el, selection: { id: "box", selector: "#box", element: el } as DomEditSelection };
+}
+
+it("blocks when runtime size motion exists but the authored tween cannot be resolved", async () => {
+  const { el, selection } = makeBoxSelection();
   const liveSizeTween = {
     targets: () => [el],
     vars: { width: 300, duration: 1 },
@@ -199,7 +203,42 @@ it("blocks when runtime size motion exists but the authored tween cannot be reso
 
   await expect(
     tryGsapResizeIntercept(selection, { width: 344, height: 344 }, [], iframe, commitMutation),
-  ).resolves.toEqual({ status: "blocked", reason: "source-uneditable" });
+  ).resolves.toEqual({
+    status: "blocked",
+    reason: "source-uneditable",
+    detail: "live-resize-no-source-tween",
+  });
+  expect(commitMutation).not.toHaveBeenCalled();
+});
+
+it("blocks a tween with no positive duration instead of committing into it", async () => {
+  const { selection } = makeBoxSelection();
+  // A zero-duration `from` is not an instant hold (those are `set`/`to`), so it
+  // reaches the duration check: a resize has no timeline position to land on.
+  const zeroDurationTween = {
+    id: "#box-size",
+    targetSelector: "#box",
+    propertyGroup: "size",
+    method: "from",
+    position: 0,
+    duration: 0,
+    properties: { width: 150, height: 150 },
+  } as unknown as GsapAnimation;
+  const commitMutation = vi.fn();
+
+  await expect(
+    tryGsapResizeIntercept(
+      selection,
+      { width: 344, height: 344 },
+      [zeroDurationTween],
+      null,
+      commitMutation,
+    ),
+  ).resolves.toEqual({
+    status: "blocked",
+    reason: "source-uneditable",
+    detail: "zero-duration-tween",
+  });
   expect(commitMutation).not.toHaveBeenCalled();
 });
 

package/src/hooks/gsapResizeIntercept.ts

@@ -137,7 +137,12 @@ export async function tryGsapResizeIntercept(
     ? hasNonHoldTweenForElement(iframe, liveSelector, undefined, [...resizeProperties])
     : false;
   if (!anim && hasLiveResizeTween) {
-    return { status: "blocked", reason: "source-uneditable" };
+    // Third twin of the position/rotation cases: a live tween with no source match.
+    return {
+      status: "blocked",
+      reason: "source-uneditable",
+      detail: "live-resize-no-source-tween",
+    };
   }
   logResize("intercept-enter", {
     hasScaleGroup,
@@ -194,7 +199,12 @@ export async function tryGsapResizeIntercept(
   }
 
   const tweenDuration = resolveTweenDuration(anim);
-  if (tweenDuration <= 0) return { status: "blocked", reason: "source-uneditable" };
+  if (tweenDuration <= 0) {
+    // The tween exists in source but has no positive duration, so there is no
+    // timeline position at which a resize could land — a different cause from
+    // the live-tween-without-a-source-match cases above.
+    return { status: "blocked", reason: "source-uneditable", detail: "zero-duration-tween" };
+  }
 
   const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
   const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);

package/src/hooks/gsapRuntimeBridge.test.ts

@@ -94,7 +94,11 @@ describe("tryGsapDragIntercept — stale-parse guard (no resurrection after dele
       vi.fn().mockResolvedValue([]),
     );
 
-    expect(result).toEqual({ status: "blocked", reason: "source-uneditable" });
+    expect(result).toEqual({
+      status: "blocked",
+      reason: "source-uneditable",
+      detail: "live-position-no-source-tween",
+    });
     expect(commitMutation).not.toHaveBeenCalled();
   });
 
@@ -354,7 +358,11 @@ describe("tryGsapRotationIntercept — instant holds", () => {
         fakeIframe("puck-b", [liveRotation]),
         commitMutation,
       ),
-    ).resolves.toEqual({ status: "blocked", reason: "source-uneditable" });
+    ).resolves.toEqual({
+      status: "blocked",
+      reason: "source-uneditable",
+      detail: "live-rotation-no-source-tween",
+    });
     expect(commitMutation).not.toHaveBeenCalled();
   });
 

package/src/hooks/gsapRuntimeBridge.ts

@@ -156,7 +156,13 @@ async function preflightGsapDragIntercept(
   const hasLivePosition = hasNonHoldTweenForElement(iframe, selector, undefined, POSITION_CHANNELS);
 
   if (hasLivePosition && !posAnim) {
-    return { status: "blocked", reason: "source-uneditable" };
+    // GSAP is visibly moving this element but the parser found no position
+    // tween for it — a source-match gap, not necessarily computed source.
+    return {
+      status: "blocked",
+      reason: "source-uneditable",
+      detail: "live-position-no-source-tween",
+    };
   }
   if (!posAnim && !writeTargetSelector(selection)) {
     return { status: "blocked", reason: "no-selector" };
@@ -268,7 +274,7 @@ export async function tryGsapDragIntercept(
   }
 
   if (!posAnim) {
-    return { status: "blocked", reason: "source-uneditable" };
+    return { status: "blocked", reason: "source-uneditable", detail: "no-position-tween" };
   }
 
   // Verify the anim ID is still valid in the current file. The React-state
@@ -353,7 +359,12 @@ export async function tryGsapRotationIntercept(
     ? hasNonHoldTweenForElement(iframe, liveSelector, undefined, ROTATION_CHANNELS)
     : false;
   if (!anim && hasLiveRotationTween) {
-    return { status: "blocked", reason: "source-uneditable" };
+    // Rotation twin of the position case above: live tween, no source match.
+    return {
+      status: "blocked",
+      reason: "source-uneditable",
+      detail: "live-rotation-no-source-tween",
+    };
   }
 
   // `angle` is the ABSOLUTE target rotation resolved by the gesture (gsap base +

package/src/hooks/timelineAudioGroupCreate.ts

@@ -28,6 +28,19 @@ import {
   type UseTimelineElementVisibilityEditingInput,
 } from "./timelineTrackVisibility";
 
+interface AudioGroupCarveInput extends UseTimelineElementVisibilityEditingInput {
+  checkEditable?: (elements: readonly TimelineElement[]) => boolean;
+}
+
+function assertAudioGroupEditable(
+  checkEditable: AudioGroupCarveInput["checkEditable"],
+  elements: readonly TimelineElement[],
+): void {
+  if (checkEditable && !checkEditable(elements)) {
+    throw new Error("Timeline edit blocked");
+  }
+}
+
 /**
  * Assign (or restore) `data-audio-group` across a set of members.
  *
@@ -267,7 +280,8 @@ export function useAudioGroupCarveAssignment({
   previewIframeRef,
   pendingTimelineEditPathRef,
   isRecordingRef,
-}: UseTimelineElementVisibilityEditingInput): (
+  checkEditable,
+}: AudioGroupCarveInput): (
   clipIds: readonly string[],
   groupId: string,
   groupLabel?: string,
@@ -289,6 +303,7 @@ export function useAudioGroupCarveAssignment({
         const domId = runtimeAudioId(item);
         return domId !== null && wanted.has(domId);
       });
+      if (elements.length === wanted.size) assertAudioGroupEditable(checkEditable, elements);
       try {
         // Loud, not silent: an unresolved id used to leave `elements` short,
         // `createAudioGroupAndAssignMembers` returning early with no write, and
@@ -333,6 +348,7 @@ export function useAudioGroupCarveAssignment({
       isRecordingRef,
       showToast,
       projectIdRef,
+      checkEditable,
     ],
   );
 }

package/src/hooks/timelineAudioGroupVolume.ts

@@ -1,4 +1,4 @@
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
 import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
 import { usePlayerStore } from "../player";
@@ -29,6 +29,10 @@ function patchLiveGroupAttribute(
   invalidateGroupInfoCache(iframe?.contentDocument);
 }
 
+function audioGroupAttributeLiveKey(groupId: string, attr: string): string {
+  return `${groupId}\0${attr}`;
+}
+
 /**
  * `data-volume` exactly as core reads it (`readAudioGroupVolume`): an absent or
  * empty attribute is UNITY, not zero.
@@ -210,9 +214,16 @@ export function useSetAudioGroupAttribute({
 }: UseTimelineElementVisibilityEditingInput): {
   setLive: (groupId: string, attr: string, value: string | null) => void;
   setQuiet: (groupId: string, attr: string, value: string | null, label: string) => Promise<void>;
+  revertLive: (groupId: string, attr: string) => void;
 } {
+  const liveBeforeRef = useRef(new Map<string, string | null>());
   const setLive = useCallback(
     (groupId: string, attr: string, value: string | null) => {
+      const key = audioGroupAttributeLiveKey(groupId, attr);
+      const target = previewIframeRef.current?.contentDocument?.getElementById(groupId);
+      if (!liveBeforeRef.current.has(key)) {
+        liveBeforeRef.current.set(key, target?.getAttribute(attr) ?? null);
+      }
       patchLiveGroupAttribute(previewIframeRef.current, groupId, attr, value);
       // Live too, not just on commit: a fader drag is `setLive` per frame and
       // `setQuiet` once on release, so without this the strip's own readout
@@ -221,6 +232,26 @@ export function useSetAudioGroupAttribute({
     },
     [previewIframeRef],
   );
+  const revertLive = useCallback(
+    (groupId: string, attr: string) => {
+      const key = audioGroupAttributeLiveKey(groupId, attr);
+      if (!liveBeforeRef.current.has(key)) return;
+      patchLiveGroupAttribute(
+        previewIframeRef.current,
+        groupId,
+        attr,
+        liveBeforeRef.current.get(key) ?? null,
+      );
+      syncStoredGroupAttribute(
+        groupId,
+        attr,
+        previewIframeRef.current?.contentDocument?.getElementById(groupId)?.getAttribute(attr) ??
+          null,
+      );
+      liveBeforeRef.current.delete(key);
+    },
+    [previewIframeRef],
+  );
   const setQuiet = useCallback(
     async (groupId: string, attr: string, value: string | null, label: string) => {
       if (isRecordingRef?.current) {
@@ -242,6 +273,7 @@ export function useSetAudioGroupAttribute({
           recordEdit,
           pendingTimelineEditPathRef,
         });
+        liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
         syncStoredGroupAttribute(groupId, attr, value);
       } catch (error) {
         // `persistElementAttribute` leaves the live DOM at the previous value
@@ -257,6 +289,7 @@ export function useSetAudioGroupAttribute({
         console.error("[Timeline] Failed to set group attribute", error);
         const message = error instanceof Error ? error.message : "Failed to update group";
         showToast(message);
+        liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
       }
     },
     [
@@ -270,5 +303,5 @@ export function useSetAudioGroupAttribute({
       projectIdRef,
     ],
   );
-  return { setLive, setQuiet };
+  return { setLive, setQuiet, revertLive };
 }

package/src/hooks/timelineEditPermission.ts

@@ -0,0 +1,31 @@
+import { useCallback } from "react";
+import type { TimelineElement } from "../player";
+
+/** A host's verdict on one element: editable, or blocked with a reason to show. */
+export type TimelineEditPermission = true | { blocked: true; reason: string };
+
+export type CanEditTimelineElement = (element: TimelineElement) => TimelineEditPermission;
+
+/**
+ * Refuses a write when any target element is blocked, toasting the host's
+ * reason. Absent `canEdit` never refuses, so Studio itself is unchanged.
+ */
+export function useTimelineEditGate(
+  canEdit: CanEditTimelineElement | undefined,
+  showToast: (message: string, tone?: "error" | "info") => void,
+) {
+  return useCallback(
+    (targets: readonly TimelineElement[]): boolean => {
+      if (!canEdit) return true;
+      for (const element of targets) {
+        const verdict = canEdit(element);
+        if (verdict !== true) {
+          showToast(verdict.reason, "error");
+          return false;
+        }
+      }
+      return true;
+    },
+    [canEdit, showToast],
+  );
+}