@hyperframes/studio 0.8.54 → 0.8.56

package/src/hooks/useDomEditWiring.ts

@@ -109,46 +109,46 @@ export interface UseDomEditWiringParams {
 }
 
 // fallow-ignore-next-line complexity
-export function useDomEditWiring({
-  // fallow-ignore-next-line code-duplication
-  projectId,
-  activeCompPath,
-  domEditSelection,
-  domEditSelectionRef,
-  domEditGroupSelectionsRef,
-  refreshDomEditGroupSelectionsFromPreview,
-  previewIframeRef,
-  previewIframe,
-  captionEditMode,
-  refreshKey,
-  gsapCacheVersion,
-  bumpGsapCache,
-  showToast,
-  refreshPreviewDocumentVersion,
-  syncPreviewHotkeys,
-  applyStudioManualEditsToPreviewRef,
-  applyDomSelection,
-  buildDomSelectionFromTarget,
-  openSourceForSelection,
-  updateGsapProperty,
-  updateGsapMeta,
-  deleteGsapAnimation,
-  deleteAllForSelector,
-  addGsapAnimation,
-  addGsapProperty,
-  removeGsapProperty,
-  updateGsapFromProperty,
-  addGsapFromProperty,
-  removeGsapFromProperty,
-  addKeyframe,
-  addKeyframeBatch,
-  removeKeyframe,
-  moveKeyframe,
-  resizeKeyframedTween,
-  convertToKeyframes,
-  removeAllKeyframes,
-  handleDomManualEditsReset,
-}: UseDomEditWiringParams) {
+export function useDomEditWiring(params: UseDomEditWiringParams) {
+  const {
+    projectId,
+    activeCompPath,
+    domEditSelection,
+    domEditSelectionRef,
+    domEditGroupSelectionsRef,
+    refreshDomEditGroupSelectionsFromPreview,
+    previewIframeRef,
+    previewIframe,
+    captionEditMode,
+    refreshKey,
+    gsapCacheVersion,
+    bumpGsapCache,
+    showToast,
+    refreshPreviewDocumentVersion,
+    syncPreviewHotkeys,
+    applyStudioManualEditsToPreviewRef,
+    applyDomSelection,
+    buildDomSelectionFromTarget,
+    openSourceForSelection,
+    updateGsapProperty,
+    updateGsapMeta,
+    deleteGsapAnimation,
+    deleteAllForSelector,
+    addGsapAnimation,
+    addGsapProperty,
+    removeGsapProperty,
+    updateGsapFromProperty,
+    addGsapFromProperty,
+    removeGsapFromProperty,
+    addKeyframe,
+    addKeyframeBatch,
+    removeKeyframe,
+    moveKeyframe,
+    resizeKeyframedTween,
+    convertToKeyframes,
+    removeAllKeyframes,
+    handleDomManualEditsReset,
+  } = params;
   // ── Click-to-source navigation ──
 
   const onClickToSource = useCallback(

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -12,10 +12,30 @@ import {
   readStudioPathOffset,
   readStudioRotation,
 } from "../components/editor/manualEdits";
-import { useDomGeometryCommits } from "./useDomGeometryCommits";
+import { useDomGeometryCommits, type UseDomGeometryCommitsParams } from "./useDomGeometryCommits";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
+function mountCommits(
+  commitPositionPatchToHtml: UseDomGeometryCommitsParams["commitPositionPatchToHtml"],
+  readOnlyPreview = false,
+) {
+  let commits: ReturnType<typeof useDomGeometryCommits> | null = null;
+  function Probe() {
+    commits = useDomGeometryCommits({
+      previewIframeRef: { current: null },
+      showToast: vi.fn(),
+      commitPositionPatchToHtml,
+      readOnlyPreview,
+    });
+    return null;
+  }
+  const host = document.createElement("div");
+  const root = createRoot(host);
+  act(() => root.render(<Probe />));
+  return { commits: () => commits!, unmount: () => act(() => root.unmount()) };
+}
+
 describe("useDomGeometryCommits rollback", () => {
   it("restores every optimistic geometry mutation when persistence rejects", async () => {
     const element = document.createElement("div");
@@ -30,7 +50,9 @@ describe("useDomGeometryCommits rollback", () => {
       element,
     } as unknown as DomEditSelection;
     const failure = new Error("save failed");
-    const commitPositionPatchToHtml = vi.fn().mockRejectedValue(failure);
+    const commitPositionPatchToHtml = vi
+      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
+      .mockRejectedValue(failure);
     let commits: ReturnType<typeof useDomGeometryCommits> | null = null;
     const host = document.createElement("div");
     const root = createRoot(host);
@@ -40,6 +62,7 @@ describe("useDomGeometryCommits rollback", () => {
         previewIframeRef: { current: null },
         showToast: vi.fn(),
         commitPositionPatchToHtml,
+        readOnlyPreview: false,
       });
       return null;
     }
@@ -60,3 +83,63 @@ describe("useDomGeometryCommits rollback", () => {
     act(() => root.unmount());
   });
 });
+
+describe("useDomGeometryCommits read-only preview", () => {
+  const selectionOn = (element: HTMLElement) =>
+    ({ id: element.id, selector: `#${element.id}`, element }) as unknown as DomEditSelection;
+
+  it("refuses a manual offset commit: no write, no history entry", async () => {
+    const element = document.createElement("div");
+    element.id = "ro-offset";
+    document.body.append(element);
+    applyStudioPathOffset(element, { x: 1, y: 2 });
+    const commitPositionPatchToHtml =
+      vi.fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>();
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml, true);
+    await commits().handleDomPathOffsetCommit(selectionOn(element), { x: 99, y: 99 });
+    expect(readStudioPathOffset(element)).toEqual({ x: 1, y: 2 });
+    expect(commitPositionPatchToHtml).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("refuses a manual box-size commit: no write, no history entry", async () => {
+    const element = document.createElement("div");
+    element.id = "ro-size";
+    document.body.append(element);
+    applyStudioBoxSize(element, { width: 10, height: 20 });
+    const commitPositionPatchToHtml =
+      vi.fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>();
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml, true);
+    await commits().handleDomBoxSizeCommit(selectionOn(element), { width: 999, height: 999 });
+    expect(readStudioBoxSize(element)).toEqual({ width: 10, height: 20 });
+    expect(commitPositionPatchToHtml).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("refuses a manual rotation commit: no write, no history entry", async () => {
+    const element = document.createElement("div");
+    element.id = "ro-rotate";
+    document.body.append(element);
+    applyStudioRotation(element, { angle: 5 });
+    const commitPositionPatchToHtml =
+      vi.fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>();
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml, true);
+    await commits().handleDomRotationCommit(selectionOn(element), { angle: 350 });
+    expect(readStudioRotation(element)).toEqual({ angle: 5 });
+    expect(commitPositionPatchToHtml).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("still commits an offset with the flag off", async () => {
+    const element = document.createElement("div");
+    element.id = "rw-offset";
+    document.body.append(element);
+    const commitPositionPatchToHtml = vi
+      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
+      .mockResolvedValue(undefined);
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml);
+    await commits().handleDomPathOffsetCommit(selectionOn(element), { x: 5, y: 6 });
+    expect(commitPositionPatchToHtml).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+});

package/src/hooks/useDomGeometryCommits.ts

@@ -28,9 +28,20 @@ import { isElementGsapTargeted } from "./gsapTargetCache";
 const GSAP_CSS_FALLBACK_BLOCKED_MESSAGE =
   "This element is GSAP-animated — dragging via CSS would corrupt keyframes";
 
+function rejectGsapCssFallback(
+  selection: DomEditSelection,
+  previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>,
+  showToast: (message: string, tone?: "error" | "info") => void,
+): Promise<never> | null {
+  if (!isElementGsapTargeted(previewIframeRef.current, selection.element)) return null;
+  const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
+  showToast(error.message, "error");
+  return Promise.reject(error);
+}
+
 // ── Hook ──
 
-interface UseDomGeometryCommitsParams {
+export interface UseDomGeometryCommitsParams {
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
   commitPositionPatchToHtml: (
@@ -38,25 +49,24 @@ interface UseDomGeometryCommitsParams {
     patches: PatchOperation[],
     options: { label: string; coalesceKey: string; skipRefresh?: boolean },
   ) => Promise<void>;
+  readOnlyPreview: boolean;
 }
 
 export function useDomGeometryCommits({
   previewIframeRef,
   showToast,
   commitPositionPatchToHtml,
+  readOnlyPreview,
 }: UseDomGeometryCommitsParams) {
   const handleDomPathOffsetCommit = useCallback(
     (selection: DomEditSelection, next: { x: number; y: number }) => {
+      if (readOnlyPreview) return Promise.resolve();
       // ponytail: GSAP-targeted elements are blocked (no SDK position-in-script op); CSS-path
       // elements fall through to commitPositionPatchToHtml → persistDomEditOperations →
       // onTrySdkPersist and are already SDK-cut-over as setStyle/setAttribute (§3.3 done).
       // Upgrade path for GSAP: add a moveElementGsap SDK op in a separate SDK PR.
-      const gsapTargeted = isElementGsapTargeted(previewIframeRef.current, selection.element);
-      if (gsapTargeted) {
-        const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
-        showToast(error.message, "error");
-        return Promise.reject(error);
-      }
+      const gsapFallback = rejectGsapCssFallback(selection, previewIframeRef, showToast);
+      if (gsapFallback) return gsapFallback;
       const before = captureStudioPathOffset(selection.element);
       applyStudioPathOffset(selection.element, next);
       return commitPositionPatchToHtml(selection, buildPathOffsetPatches(selection.element), {
@@ -67,7 +77,7 @@ export function useDomGeometryCommits({
         throw error;
       });
     },
-    [commitPositionPatchToHtml, previewIframeRef, showToast],
+    [commitPositionPatchToHtml, previewIframeRef, showToast, readOnlyPreview],
   );
 
   const handleDomBoxSizeCommit = useCallback(
@@ -76,11 +86,9 @@ export function useDomGeometryCommits({
       next: { width: number; height: number },
       offset?: { x: number; y: number },
     ) => {
-      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
-        const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
-        showToast(error.message, "error");
-        return Promise.reject(error);
-      }
+      if (readOnlyPreview) return Promise.resolve();
+      const gsapFallback = rejectGsapCssFallback(selection, previewIframeRef, showToast);
+      if (gsapFallback) return gsapFallback;
       const beforeSize = captureStudioBoxSize(selection.element);
       const beforeOffset = offset ? captureStudioPathOffset(selection.element) : null;
       applyStudioBoxSize(selection.element, next);
@@ -104,16 +112,14 @@ export function useDomGeometryCommits({
         throw error;
       });
     },
-    [commitPositionPatchToHtml, previewIframeRef, showToast],
+    [commitPositionPatchToHtml, previewIframeRef, showToast, readOnlyPreview],
   );
 
   const handleDomRotationCommit = useCallback(
     (selection: DomEditSelection, next: { angle: number }) => {
-      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
-        const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
-        showToast(error.message, "error");
-        return Promise.reject(error);
-      }
+      if (readOnlyPreview) return Promise.resolve();
+      const gsapFallback = rejectGsapCssFallback(selection, previewIframeRef, showToast);
+      if (gsapFallback) return gsapFallback;
       const before = captureStudioRotation(selection.element);
       applyStudioRotation(selection.element, next);
       return commitPositionPatchToHtml(selection, buildRotationPatches(selection.element), {
@@ -124,7 +130,7 @@ export function useDomGeometryCommits({
         throw error;
       });
     },
-    [commitPositionPatchToHtml, previewIframeRef, showToast],
+    [commitPositionPatchToHtml, previewIframeRef, showToast, readOnlyPreview],
   );
 
   const handleDomManualEditsReset = useCallback(

package/src/hooks/useGestureCommit.test.tsx

@@ -107,6 +107,7 @@ describe("useGestureCommit", () => {
         previewIframeRef: { current: iframe },
         showToast: vi.fn(),
         isGestureRecordingRef: { current: false },
+        readOnlyPreview: false,
       });
       return null;
     }
@@ -127,4 +128,32 @@ describe("useGestureCommit", () => {
     expect(options[1]).toEqual(expect.objectContaining({ coalesceMs: Infinity, softReload: true }));
     expect(options[1]).not.toHaveProperty("skipReload");
   });
+
+  it("does not start a recording while the preview is read-only", () => {
+    const element = document.createElement("div");
+    const commitMutation = vi.fn(async () => {});
+    const captured: { hook: ReturnType<typeof useGestureCommit> | null } = { hook: null };
+    function Probe() {
+      captured.hook = useGestureCommit({
+        domEditSessionRef: {
+          current: {
+            domEditSelection: makeSelection(element),
+            selectedGsapAnimations: [],
+            commitMutation,
+          },
+        },
+        previewIframeRef: { current: document.createElement("iframe") },
+        showToast: vi.fn(),
+        isGestureRecordingRef: { current: false },
+        readOnlyPreview: true,
+      });
+      return null;
+    }
+    const root = mountReactHarness(<Probe />);
+    cleanup = () => act(() => root.unmount());
+
+    act(() => captured.hook?.handleToggleRecording());
+    expect(gestureRecording.startRecording).not.toHaveBeenCalled();
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
 });

package/src/hooks/useGestureCommit.ts

@@ -87,6 +87,7 @@ interface UseGestureCommitParams {
   previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
   isGestureRecordingRef: React.MutableRefObject<boolean>;
+  readOnlyPreview: boolean;
 }
 
 export interface UseGestureCommitResult {
@@ -101,6 +102,7 @@ export function useGestureCommit({
   previewIframeRef,
   showToast,
   isGestureRecordingRef,
+  readOnlyPreview,
 }: UseGestureCommitParams): UseGestureCommitResult {
   const gestureRecording = useGestureRecording();
   const [gestureState, setGestureState] = useState<"idle" | "recording">("idle");
@@ -115,6 +117,20 @@ export function useGestureCommit({
   // Unmount: clear auto-stop interval
   useEffect(() => () => clearInterval(recordingAutoStopRef.current), []);
 
+  const cancelRecording = useCallback(() => {
+    clearInterval(recordingAutoStopRef.current);
+    gestureRecording.stopRecording();
+    gestureRecording.clearSamples();
+    gestureStateRef.current = "idle";
+    isGestureRecordingRef.current = false;
+    capturedSelectionRef.current = null;
+    setGestureState("idle");
+  }, [gestureRecording, isGestureRecordingRef]);
+
+  useEffect(() => {
+    if (readOnlyPreview && gestureStateRef.current === "recording") cancelRecording();
+  }, [cancelRecording, readOnlyPreview]);
+
   // fallow-ignore-next-line complexity
   const stopAndCommitRecording = useCallback(async () => {
     clearInterval(recordingAutoStopRef.current);
@@ -335,9 +351,14 @@ export function useGestureCommit({
   // fallow-ignore-next-line complexity
   const handleToggleRecording = useCallback(() => {
     if (gestureStateRef.current === "recording") {
+      if (readOnlyPreview) {
+        cancelRecording();
+        return;
+      }
       void stopAndCommitRecording();
       return;
     }
+    if (readOnlyPreview) return;
     const sel = domEditSessionRef.current.domEditSelection;
     if (!sel) {
       showToast("Select an element first", "error");
@@ -373,9 +394,11 @@ export function useGestureCommit({
     gestureRecording,
     showToast,
     stopAndCommitRecording,
+    cancelRecording,
     previewIframeRef,
     domEditSessionRef,
     isGestureRecordingRef,
+    readOnlyPreview,
   ]);
 
   return { gestureState, gestureRecording, handleToggleRecording };

package/src/hooks/useInlineTextEdit.test.tsx

@@ -3,6 +3,7 @@
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { PreviewReadOnlyProvider } from "../components/editor/previewReadOnlyContext";
 import { useInlineTextEdit, type InlineTextEditControls } from "./useInlineTextEdit";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -20,7 +21,7 @@ function heading(text = "Motion Playground"): HTMLElement {
   return element;
 }
 
-function mount(onCommit = vi.fn(), onPause = vi.fn()) {
+function mount(onCommit = vi.fn(), onPause = vi.fn(), readOnly = false) {
   const controls: { current: InlineTextEditControls | null } = { current: null };
   function Probe() {
     controls.current = useInlineTextEdit({ onCommit, onPause });
@@ -29,7 +30,13 @@ function mount(onCommit = vi.fn(), onPause = vi.fn()) {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
-  act(() => root.render(<Probe />));
+  act(() =>
+    root.render(
+      <PreviewReadOnlyProvider readOnly={readOnly}>
+        <Probe />
+      </PreviewReadOnlyProvider>,
+    ),
+  );
   return { controls: () => controls.current!, root, onCommit, onPause };
 }
 
@@ -552,4 +559,18 @@ describe("useInlineTextEdit with styled runs", () => {
     expect(insertText).toHaveBeenCalledWith("insertText", false, "plain words");
     act(() => root.unmount());
   });
+
+  it("refuses to open an edit while the preview is read-only", () => {
+    const element = heading();
+    const { controls, root, onCommit, onPause } = mount(vi.fn(), vi.fn(), true);
+    let opened = true;
+    act(() => {
+      opened = controls().start(element);
+    });
+    expect(opened).toBe(false);
+    expect(element.hasAttribute("contenteditable")).toBe(false);
+    expect(onPause).not.toHaveBeenCalled();
+    expect(onCommit).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
 });

package/src/hooks/useInlineTextEdit.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { sanitizeRichTextChildren } from "@hyperframes/core/rich-text-sanitize";
+import { usePreviewReadOnly } from "../components/editor/previewReadOnlyContext";
 
 /**
  * Editing an element's text where it sits, in the composition itself.
@@ -89,6 +90,7 @@ export function useInlineTextEdit({
   /** Stop playback, so the element is not animating under the caret. */
   onPause?: () => void;
 }): InlineTextEditControls {
+  const readOnly = usePreviewReadOnly();
   const [session, setSession] = useState<InlineTextEditSession | null>(null);
   // The teardown reads this rather than the state, so an exit path that runs
   // before React re-renders still sees the element it has to clean up.
@@ -123,7 +125,7 @@ export function useInlineTextEdit({
 
   const start = useCallback(
     (element: HTMLElement, caretAt?: { x: number; y: number }): boolean => {
-      if (openRef.current) return false;
+      if (openRef.current || readOnly) return false;
 
       const open = {
         element,
@@ -156,7 +158,7 @@ export function useInlineTextEdit({
       framesRef.current = raf ?? null;
       return true;
     },
-    [onPause],
+    [onPause, readOnly],
   );
 
   const commit = useCallback(() => {
@@ -179,6 +181,13 @@ export function useInlineTextEdit({
     teardown();
   }, [teardown]);
 
+  // Read-only can be enabled while an edit is already open. Close that
+  // session as a cancellation so the preview cannot keep committing through
+  // the now-disabled editing surface.
+  useEffect(() => {
+    if (readOnly && openRef.current) cancel();
+  }, [cancel, readOnly]);
+
   // The keys belong to the element, not to the document: the element lives in
   // the preview's own document, so a listener on Studio's would never see them.
   useEffect(() => {

package/src/hooks/useTimelineAssetDropOps.test.tsx

@@ -103,7 +103,7 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
     expect(usePlayerStore.getState().selectedElementId).toBe("index.html#clip");
   });
 
-  it("measures the insert row against the visible rows, not clips the timeline hides", async () => {
+  it("measures the insert row against every manifest timeline row", async () => {
     const clip = (id: string, track: number): TimelineElement => ({
       id,
       key: id,
@@ -123,7 +123,6 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
       }),
       "</main>",
     ].join("\n");
-    usePlayerStore.getState().setTopLevelIds(new Set(["a", "b"]));
     const writeProjectFile = vi.fn().mockResolvedValue(undefined);
     const getDrop = renderDropHook(source, writeProjectFile, [
       clip("a", 0),
@@ -136,8 +135,8 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
     });
 
     const [, written] = writeProjectFile.mock.calls[0] as [string, string];
-    expect(written).toContain('id="b" data-start="0" data-track-index="2"');
-    expect(written).toContain('id="hidden" data-start="0" data-track-index="1"');
+    expect(written).toContain('id="b" data-start="0" data-track-index="3"');
+    expect(written).toContain('id="hidden" data-start="0" data-track-index="2"');
     expect(written).toMatch(/<video id="clip"[^>]*data-track-index="1"/);
   });
 

package/src/hooks/useTimelineAssetDropOps.ts

@@ -25,8 +25,6 @@ import { commitTimelineCompositionInsertion } from "../utils/timelineComposition
 import { extendRootDurationInSource } from "../utils/rootDuration";
 import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
 import { selectAndRevealTimelineElement } from "../player/components/timelineDropReveal";
-import { selectTimelineRowElements } from "../player/hooks/useTimelineRowElements";
-import { usePlayerStore } from "../player/store/playerStore";
 
 /** The first uploaded file opens the new track (if asked); the rest land on the lane it landed on. */
 function fileDropPlacement(
@@ -127,10 +125,7 @@ export function useTimelineAssetDropOps({
         const { source: sourceWithRoom, track } = resolveDropTrack({
           source: originalContent,
           // insertRow counts the rows the timeline shows, so plan against those.
-          elements: selectTimelineRowElements(
-            relevantElements,
-            usePlayerStore.getState().topLevelIds,
-          ),
+          elements: relevantElements,
           placement,
           dropped: {
             id: newId,

package/src/hooks/useTimelineEditing.test.tsx

@@ -1561,21 +1561,24 @@ describe("useTimelineEditing: canEdit gate", () => {
     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.
+  it("resolves toggle-track-hidden against the store-owned timeline rows", async () => {
+    // The visibility hook reads the single store-owned row source. The editing
+    // guard must receive that same source so a blocked row cannot fall through
+    // to the write path.
     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 () => {});
+    const canEdit = vi.fn((element: TimelineElement) =>
+      element.id === "clip" ? { blocked: true as const, reason: "Reserved by an agent" } : true,
+    );
     let hook: ReturnType<typeof useTimelineEditing> | null = null;
     function Harness() {
       hook = useTimelineEditing({
         projectId: "p1",
         activeCompPath: "index.html",
-        timelineElements: [], // deliberately does not contain `clip`
+        timelineElements: [clip],
         showToast,
         writeProjectFile,
         recordEdit: vi.fn(),
@@ -1583,8 +1586,7 @@ describe("useTimelineEditing: canEdit gate", () => {
         previewIframeRef: { current: iframe },
         pendingTimelineEditPathRef: { current: new Set<string>() },
         uploadProjectFiles: vi.fn(),
-        canEdit: (element) =>
-          element.id === "clip" ? { blocked: true, reason: "Reserved by an agent" } : true,
+        canEdit,
       });
       return null;
     }
@@ -1596,6 +1598,7 @@ describe("useTimelineEditing: canEdit gate", () => {
       await flushAsyncWork();
     });
 
+    expect(canEdit).toHaveBeenCalledWith(clip);
     expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
     expect(writeProjectFile).not.toHaveBeenCalled();
     unmount();

package/src/hooks/useTimelineEditing.ts

@@ -25,7 +25,6 @@ import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
 import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
 import { useSetElementAttribute } from "./timelineElementFxAttribute";
 import { useTimelineDeleteOps } from "./useTimelineDeleteOps";
-import { useTimelineRowElements } from "../player/hooks/useTimelineRowElements";
 import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
 import { useAudioGroupCarveAssignment } from "./timelineAudioGroupCreate";
 import {
@@ -77,10 +76,6 @@ export function useTimelineEditing({
   const checkEditable = useTimelineEditGate(canEdit, showToast);
   const checkEditableRef = useRef(checkEditable);
   checkEditableRef.current = checkEditable;
-  // Same expanded-row source the hide handlers themselves resolve against
-  // (timelineTrackVisibility.ts) — a virtual sub-comp child's track/key
-  // only exists here, not in the raw store list canEdit would otherwise miss.
-  const timelineRowElements = useTimelineRowElements();
   const guardedRef = useRef(new WeakMap<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
@@ -514,14 +509,14 @@ export function useTimelineEditing({
     handleTimelineElementResize: track(guard((element) => [element], handleTimelineElementResize)),
     handleToggleTrackHidden: track(
       guard(
-        (trackIndex) => timelineRowElements.filter((el) => el.track === trackIndex),
+        (trackIndex) => timelineElements.filter((el) => el.track === trackIndex),
         handleToggleTrackHidden,
       ),
     ),
     handleToggleElementHidden: track(
       guard((elementKey) => {
         const keys = new Set(Array.isArray(elementKey) ? elementKey : [elementKey]);
-        return timelineRowElements.filter((el) => keys.has(el.key ?? el.id));
+        return timelineElements.filter((el) => keys.has(el.key ?? el.id));
       }, handleToggleElementHidden),
     ),
     handleAutoGroupCarveSources: track(handleAutoGroupCarveSources),