@hyperframes/studio 0.8.54 → 0.8.56

package/src/components/editor/useDomEditNudge.ts

@@ -167,6 +167,15 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
   const commitSessionRef = useRef(commitSession);
   commitSessionRef.current = commitSession;
 
+  useEffect(() => {
+    if (params.allowCanvasMovement || !sessionRef.current) return;
+    const session = sessionRef.current;
+    sessionRef.current = null;
+    if (session.timer) clearTimeout(session.timer);
+    restoreManualOffsetDragMembers(session.members);
+    endManualOffsetDragMembers(session.members);
+  }, [params.allowCanvasMovement]);
+
   // Build drag members for the current target set — the same member snapshot a
   // pointer drag starts from (startGesture / startGroupDrag), so the nudge
   // commit converts offsets → GSAP x/y with identical math.

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -532,6 +532,10 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       restoreGestureOverlayRect(g);
     }
     if (g?.mode === "rotation" && sel) {
+      applyRotationDraftViaGsap(
+        sel.element,
+        g.actualRotation - (Number.parseFloat(g.initialRotation.studioRotation) || 0),
+      );
       restoreStudioRotation(sel.element, g.initialRotation);
       endStudioManualEditGesture(sel.element, g.manualEditDragToken);
     }

package/src/components/editor/useOffCanvasIndicators.ts

@@ -0,0 +1,50 @@
+import { useEffect, useRef, useState, type RefObject } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
+import type { DomEditCompositionRect } from "./useDomEditCompositionRect";
+import { type OffCanvasRect } from "./OffCanvasIndicators";
+import { startOffCanvasIndicatorRefresh } from "./offCanvasIndicatorRefresh";
+
+export function useOffCanvasIndicators({
+  iframeRef,
+  overlayRef,
+  compRectRef,
+  activeCompositionPathRef,
+  activeCompositionPath,
+}: {
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  overlayRef: RefObject<HTMLDivElement | null>;
+  compRectRef: React.MutableRefObject<DomEditCompositionRect>;
+  activeCompositionPathRef: React.MutableRefObject<string | null>;
+  activeCompositionPath: string | null;
+}): {
+  offCanvasRects: OffCanvasRect[];
+  offCanvasElementsRef: React.MutableRefObject<Map<string, HTMLElement>>;
+} {
+  const offCanvasElementsRef = useRef<Map<string, HTMLElement>>(new Map());
+  const [offCanvasRects, setOffCanvasRects] = useState<OffCanvasRect[]>([]);
+  const offCanvasDirtyRef = useRef(true);
+  const offCanvasSigRef = useRef("");
+  const offCanvasObserverRef = useRef<MutationObserver | null>(null);
+  const offCanvasObservedDocRef = useRef<Document | null>(null);
+
+  useMountEffect(() =>
+    startOffCanvasIndicatorRefresh({
+      iframeRef,
+      overlayRef,
+      compRectRef,
+      activeCompositionPathRef,
+      dirtyRef: offCanvasDirtyRef,
+      sigRef: offCanvasSigRef,
+      observerRef: offCanvasObserverRef,
+      observedDocRef: offCanvasObservedDocRef,
+      elementsRef: offCanvasElementsRef,
+      setRects: setOffCanvasRects,
+    }),
+  );
+
+  useEffect(() => {
+    offCanvasDirtyRef.current = true;
+  }, [activeCompositionPath]);
+
+  return { offCanvasRects, offCanvasElementsRef };
+}

package/src/components/nle/PreviewOverlays.topologyLens.test.tsx

@@ -3,21 +3,13 @@
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { getPreviewState, iframeRef } from "./PreviewOverlaysTestMocks";
 import { PreviewOverlays } from "./PreviewOverlays";
 
-(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+const previewState = getPreviewState();
 
-const previewState = vi.hoisted(() => ({ captionEditMode: false }));
-const iframeRef = { current: null as HTMLIFrameElement | null };
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
-vi.mock("../../contexts/StudioContext", () => ({
-  useStudioShellContext: () => ({ activeCompPath: "index.html", previewIframeRef: iframeRef }),
-  useStudioPlaybackContext: () => ({
-    captionEditMode: previewState.captionEditMode,
-    compositionLoading: false,
-    isPlaying: false,
-  }),
-}));
 vi.mock("../../contexts/DomEditContext", () => ({
   useDomEditSelectionContext: () => ({
     domEditHoverSelection: null,
@@ -41,30 +33,7 @@ vi.mock("../../contexts/DomEditContext", () => ({
     handleDomZIndexReorderCommit: vi.fn(),
   }),
 }));
-vi.mock("../../captions/store", () => {
-  const state = {
-    model: null,
-    dismissed: false,
-    syncError: null,
-    clearSelection: vi.fn(),
-    setDismissed: vi.fn(),
-    setEditMode: vi.fn(),
-    setSyncError: vi.fn(),
-  };
-  return {
-    useCaptionStore: Object.assign(
-      (selector: (value: typeof state) => unknown) => selector(state),
-      { getState: () => state },
-    ),
-  };
-});
-vi.mock("../../hooks/useCompositionDimensions", () => ({
-  useCompositionDimensions: () => null,
-}));
-vi.mock("../../utils/studioUiPreferences", () => ({ readStudioUiPreferences: () => ({}) }));
-vi.mock("./useCanvasZOrderTimelineMirror", () => ({
-  useCanvasZOrderTimelineMirror: () => vi.fn(),
-}));
+
 vi.mock("../editor/TopologyLens", async () => {
   const { createElement } = await import("react");
   return {

package/src/components/nle/PreviewOverlays.tsx

@@ -5,6 +5,7 @@ import { DomEditOverlay } from "../editor/DomEditOverlay";
 import { TopologyLens } from "../editor/TopologyLens";
 import { MotionPathOverlay } from "../editor/MotionPathOverlay";
 import { SnapToolbar } from "../editor/SnapToolbar";
+import { usePreviewReadOnly } from "../editor/previewReadOnlyContext";
 import { useCompositionDimensions } from "../../hooks/useCompositionDimensions";
 import { useStudioPlaybackContext, useStudioShellContext } from "../../contexts/StudioContext";
 import {
@@ -140,6 +141,8 @@ export function PreviewOverlays({
   const { activeCompPath, previewIframeRef } = useStudioShellContext();
   const { captionEditMode, compositionLoading, isPlaying } = useStudioPlaybackContext();
   const compositionDimensions = useCompositionDimensions(previewIframeRef);
+  const readOnly = usePreviewReadOnly();
+  const previewCaptionEditMode = captionEditMode && !readOnly;
 
   // Caption edit mode is entered automatically when captions are detected;
   // these give the author an explicit way OUT (and back in). Without them the
@@ -216,7 +219,7 @@ export function PreviewOverlays({
     );
   }
 
-  if (captionEditMode) {
+  if (previewCaptionEditMode) {
     return (
       <>
         <TopologyLens iframeRef={previewIframeRef} activeCompositionPath={activeCompPath} />
@@ -267,7 +270,9 @@ export function PreviewOverlays({
         iframeRef={previewIframeRef}
         activeCompositionPath={activeCompPath}
         hoverSelection={
-          !captionEditMode && !compositionLoading && !isPlaying ? domEditHoverSelection : null
+          !previewCaptionEditMode && !compositionLoading && !isPlaying
+            ? domEditHoverSelection
+            : null
         }
         selection={shouldShowSelectedDomBounds ? domEditSelection : null}
         groupSelections={shouldShowSelectedDomBounds ? domEditGroupSelections : []}
@@ -327,12 +332,14 @@ export function PreviewOverlays({
         onMarqueeSelect={applyMarqueeSelection}
       />
       <SnapToolbar onSnapChange={setSnapPrefs} />
-      <MotionPathOverlay
-        iframeRef={previewIframeRef}
-        selection={shouldShowMotionPath ? domEditSelection : null}
-        compositionSize={compositionDimensions}
-        isPlaying={isPlaying}
-      />
+      {!readOnly && (
+        <MotionPathOverlay
+          iframeRef={previewIframeRef}
+          selection={shouldShowMotionPath ? domEditSelection : null}
+          compositionSize={compositionDimensions}
+          isPlaying={isPlaying}
+        />
+      )}
       {gestureOverlay}
       {captionModelPresent && captionDismissed && (
         <button

package/src/components/nle/PreviewOverlaysTestMocks.ts

@@ -0,0 +1,40 @@
+import { vi } from "vitest";
+
+const previewState = vi.hoisted(() => ({ captionEditMode: false }));
+export function getPreviewState() {
+  return previewState;
+}
+export const iframeRef = { current: null as HTMLIFrameElement | null };
+
+vi.mock("../../contexts/StudioContext", () => ({
+  useStudioShellContext: () => ({ activeCompPath: "index.html", previewIframeRef: iframeRef }),
+  useStudioPlaybackContext: () => ({
+    captionEditMode: previewState.captionEditMode,
+    compositionLoading: false,
+    isPlaying: false,
+  }),
+}));
+vi.mock("../../captions/store", () => {
+  const state = {
+    model: null,
+    dismissed: false,
+    syncError: null,
+    clearSelection: vi.fn(),
+    setDismissed: vi.fn(),
+    setEditMode: vi.fn(),
+    setSyncError: vi.fn(),
+  };
+  return {
+    useCaptionStore: Object.assign(
+      (selector: (value: typeof state) => unknown) => selector(state),
+      { getState: () => state },
+    ),
+  };
+});
+vi.mock("../../hooks/useCompositionDimensions", () => ({
+  useCompositionDimensions: () => null,
+}));
+vi.mock("../../utils/studioUiPreferences", () => ({ readStudioUiPreferences: () => ({}) }));
+vi.mock("./useCanvasZOrderTimelineMirror", () => ({
+  useCanvasZOrderTimelineMirror: () => vi.fn(),
+}));

package/src/components/nle/TimelinePane.tsx

@@ -255,7 +255,11 @@ export function TimelinePane({
   );
 
   return (
-    <div className="relative flex h-full flex-col" aria-disabled={timelineDisabled || undefined}>
+    <div
+      className="relative flex h-full flex-col"
+      data-studio-timeline="true"
+      aria-disabled={timelineDisabled || undefined}
+    >
       <div
         className="flex flex-col flex-1 min-h-0 overflow-hidden rounded-lg border border-neutral-800/50 bg-neutral-950"
         onDoubleClick={(e) => {

package/src/components/nle/previewReadOnly.test.tsx

@@ -0,0 +1,128 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { getPreviewState, iframeRef } from "./PreviewOverlaysTestMocks";
+import { PreviewOverlays } from "./PreviewOverlays";
+import { usePreviewBlockDrop } from "./usePreviewBlockDrop";
+import { PreviewReadOnlyProvider } from "../editor/previewReadOnlyContext";
+import { TIMELINE_BLOCK_MIME } from "../../utils/timelineAssetDrop";
+
+const previewState = getPreviewState();
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+vi.mock("../../contexts/DomEditContext", () => ({
+  useDomEditSelectionContext: () => ({
+    domEditHoverSelection: null,
+    domEditSelection: null,
+    domEditGroupSelections: [],
+  }),
+  useDomEditActionsContext: () => ({}),
+}));
+vi.mock("../editor/TopologyLens", () => ({ TopologyLens: () => null }));
+vi.mock("../../captions/components/CaptionOverlay", () => ({
+  CaptionOverlay: () => <i data-testid="caption-overlay" />,
+}));
+vi.mock("../editor/DomEditOverlay", () => ({
+  DomEditOverlay: () => <i data-testid="dom-edit-overlay" />,
+}));
+vi.mock("../editor/MotionPathOverlay", () => ({
+  MotionPathOverlay: () => <i data-testid="motion-path" />,
+}));
+vi.mock("../editor/SnapToolbar", () => ({ SnapToolbar: () => null }));
+
+let root: Root;
+let host: HTMLDivElement;
+
+function mount(node: React.ReactNode, readOnly = false): void {
+  host = document.createElement("div");
+  iframeRef.current = document.createElement("iframe");
+  document.body.append(host, iframeRef.current);
+  root = createRoot(host);
+  act(() =>
+    root.render(<PreviewReadOnlyProvider readOnly={readOnly}>{node}</PreviewReadOnlyProvider>),
+  );
+}
+
+afterEach(() => {
+  act(() => root.unmount());
+  previewState.captionEditMode = false;
+  document.body.replaceChildren();
+});
+
+const overlays = () => (
+  <PreviewOverlays shouldShowMotionPath={true} shouldShowSelectedDomBounds={true} />
+);
+const has = (id: string) => host.querySelector(`[data-testid="${id}"]`) !== null;
+
+describe("PreviewOverlays with the preview read-only", () => {
+  it("control: with the flag off the motion path can be edited", () => {
+    mount(overlays());
+    expect(has("motion-path")).toBe(true);
+  });
+
+  it("does not mount the motion path editor", () => {
+    mount(overlays(), true);
+    expect(has("motion-path")).toBe(false);
+    expect(has("dom-edit-overlay")).toBe(true);
+  });
+
+  it("control: with the flag off caption mode mounts the caption editor", () => {
+    previewState.captionEditMode = true;
+    mount(overlays());
+    expect(has("caption-overlay")).toBe(true);
+  });
+
+  it("does not mount the caption editor, and selection stays on the canvas overlay", () => {
+    previewState.captionEditMode = true;
+    mount(overlays(), true);
+    expect(has("caption-overlay")).toBe(false);
+    expect(has("dom-edit-overlay")).toBe(true);
+  });
+});
+
+describe("usePreviewBlockDrop with the preview read-only", () => {
+  function dropOnPreview(
+    onBlockDrop: (name: string, pos: { left: number; top: number }) => void,
+    readOnly = false,
+  ) {
+    const stage = document.createElement("div");
+    stage.getBoundingClientRect = () => ({ left: 0, top: 0, width: 100, height: 100 }) as DOMRect;
+    let handlers: ReturnType<typeof usePreviewBlockDrop> | null = null;
+    function Probe() {
+      handlers = usePreviewBlockDrop({
+        stageRef: { current: stage },
+        compositionSize: { width: 1000, height: 1000 },
+        onBlockDrop,
+      });
+      return null;
+    }
+    mount(<Probe />, readOnly);
+    const event = {
+      clientX: 50,
+      clientY: 50,
+      preventDefault: vi.fn(),
+      dataTransfer: {
+        types: [TIMELINE_BLOCK_MIME],
+        getData: () => JSON.stringify({ name: "lower-third" }),
+      },
+    };
+    act(() => handlers!.handleDrop(event as never));
+    return event;
+  }
+
+  it("control: with the flag off a dropped block is placed", () => {
+    const onBlockDrop = vi.fn();
+    dropOnPreview(onBlockDrop);
+    expect(onBlockDrop).toHaveBeenCalledWith("lower-third", { left: 500, top: 500 });
+  });
+
+  it("does not place a dropped block", () => {
+    const onBlockDrop = vi.fn();
+    const event = dropOnPreview(onBlockDrop, true);
+    expect(onBlockDrop).not.toHaveBeenCalled();
+    expect(event.preventDefault).not.toHaveBeenCalled();
+  });
+});

package/src/components/nle/useCanvasZOrderTimelineMirror.test.tsx

@@ -24,7 +24,7 @@ import {
 afterEach(() => {
   document.body.innerHTML = "";
   // Wrapped in act: mounted harnesses subscribe to the store via
-  // useTimelineRowElements, so the reset re-renders them.
+  // the store timeline elements, so the reset re-renders them.
   act(() => usePlayerStore.getState().setElements([]));
 });
 

package/src/components/nle/useCanvasZOrderTimelineMirror.ts

@@ -1,6 +1,5 @@
 import { useCallback, useRef } from "react";
 import { usePlayerStore } from "../../player";
-import { useTimelineRowElements } from "../../player/hooks/useTimelineRowElements";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import {
   displayTrackOrder,
@@ -41,10 +40,8 @@ export interface MirrorZOrderInput {
  * commitZMirrorLaneMove) — the shared key is unique per gesture
  * (zReorderCoalesceKey's gesture seq), so the fold stays gesture-scoped.
  *
- * Element source: `useTimelineRowElements()` — the same expanded display
- * set the Timeline renders and the resolver expects (post-normalizeToZones
- * lanes, expanded sub-comp children on their synthetic rows). No new expansion
- * is built here.
+ * Element source: the store's timeline elements, the same set the Timeline
+ * renders and the resolver expects. No alternate row expansion is built here.
  *
  * The mirror persists through the SAME machinery as a timeline lane drag
  * (commitZMirrorLaneMove → persistMoveEdits → onMoveElements, with expanded
@@ -141,7 +138,7 @@ function useMirrorLaneMoveCommit(): (
   coalesceKey: string,
   resolveMove: (element: TimelineElement, elements: TimelineElement[]) => ZMirrorLaneMove,
 ) => Promise<boolean> {
-  const elements = useTimelineRowElements();
+  const elements = usePlayerStore((state) => state.elements);
   const elementsRef = useRef(elements);
   elementsRef.current = elements;
   const { onMoveElements } = useTimelineEditContextOptional();

package/src/components/nle/usePreviewBlockDrop.ts

@@ -1,5 +1,6 @@
 import { useCallback, useRef, useState, type RefObject } from "react";
 import { TIMELINE_BLOCK_MIME } from "../../utils/timelineAssetDrop";
+import { usePreviewReadOnly } from "../editor/previewReadOnlyContext";
 
 interface UsePreviewBlockDropOptions {
   portrait?: boolean;
@@ -67,8 +68,9 @@ export function usePreviewBlockDrop({
   portrait,
   compositionSize,
   stageRef,
-  onBlockDrop,
+  onBlockDrop: onBlockDropProp,
 }: UsePreviewBlockDropOptions) {
+  const onBlockDrop = usePreviewReadOnly() ? undefined : onBlockDropProp;
   const [isDragOver, setIsDragOver] = useState(false);
   // dragenter/dragleave fire for every internal element boundary; a depth
   // counter keeps the drop indicator steady instead of flickering.

package/src/hooks/appHotkeysDispatch.ts

@@ -54,6 +54,11 @@ export interface HotkeyCallbacks {
   onUngroupSelection?: () => void;
   domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
+  readOnlyPreview: boolean;
+}
+
+function timelineOwnsKey(event: KeyboardEvent): boolean {
+  return event.target instanceof Element && event.target.closest("[data-studio-timeline]") !== null;
 }
 
 /** Exported for tests, like dispatchPlainKey below: lets the Cmd+C/Cmd+V
@@ -95,6 +100,7 @@ export function dispatchModifierKey(
 
   if (key === "g" && !event.altKey && !isTypingTarget(event.target)) {
     event.preventDefault();
+    if (cb.readOnlyPreview) return true;
     if (event.shiftKey) cb.onUngroupSelection?.();
     else cb.onGroupSelection?.();
     return true;
@@ -113,6 +119,12 @@ export function dispatchModifierKey(
       }
       return true;
     }
+    const previewOwnsMutation =
+      cb.readOnlyPreview && cb.domEditSelectionRef.current !== null && !timelineOwnsKey(event);
+    if (previewOwnsMutation && ["v", "x", "d"].includes(key)) {
+      event.preventDefault();
+      return true;
+    }
     if (key === "v") {
       event.preventDefault();
       trackStudioEvent("keyboard_shortcut", { action: "paste" });
@@ -158,6 +170,7 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
     // Reserve bare `s` for Split even when the current selection cannot split,
     // so secondary listeners do not reinterpret the same key as Snap toggle.
     event.preventDefault();
+    if (cb.readOnlyPreview) return;
     const { selectedElementId, elements, currentTime } = usePlayerStore.getState();
     if (selectedElementId) {
       const el = elements.find((e) => (e.key ?? e.id) === selectedElementId);
@@ -240,8 +253,10 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
     // the timeline left other selected elements behind. Timeline stays as the
     // fallback for rows with no canvas node (audio, an inactive comp).
     const domSel = cb.domEditSelectionRef.current;
-    if (domSel) {
+    const timelineOwnsDelete = timelineOwnsKey(event);
+    if (domSel && !timelineOwnsDelete) {
       event.preventDefault();
+      if (cb.readOnlyPreview) return;
       // The whole marquee group, not just the primary the ref holds.
       void cb.handleDomEditElementDelete(domSel, { expandGroup: true });
       return;

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();
+  });
+});