@hyperframes/studio 0.8.55 → 0.8.56

package/src/hooks/useAppHotkeys.test.ts

@@ -1,7 +1,8 @@
 // @vitest-environment happy-dom
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { dispatchModifierKey, dispatchPlainKey } from "./appHotkeysDispatch";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { dispatchModifierKey, dispatchPlainKey, type HotkeyCallbacks } from "./appHotkeysDispatch";
 import { usePlayerStore } from "../player/store/playerStore";
+import type { DomEditSelection } from "../components/editor/domEditing";
 import { clearAutomationClipboard, copyRange } from "../player/components/automationClipboard";
 import { VOLUME_RANGE } from "@hyperframes/core/audio-automation";
 import type { TimelineElement } from "../player/store/timelineElement";
@@ -19,7 +20,7 @@ const bgmElement: TimelineElement = {
 /** Every callback dispatchPlainKey can reach, so a test can assert which one
  *  a key resolved to. Unannotated on purpose: the parameter type is not
  *  exported, and structural inference checks it at the call site. */
-function callbacks() {
+function callbacks(overrides: Partial<HotkeyCallbacks> = {}) {
   return {
     handleTimelineElementDelete: vi.fn(async () => {}),
     handleTimelineElementsDelete: vi.fn(async () => {}),
@@ -30,10 +31,15 @@ function callbacks() {
     handleCopy: vi.fn(() => false),
     handlePaste: vi.fn(async () => {}),
     handleCut: vi.fn(async () => false),
+    handleDuplicate: vi.fn(async () => false),
+    onGroupSelection: vi.fn(),
+    onUngroupSelection: vi.fn(),
     onResetKeyframes: vi.fn(() => true),
     onDeleteSelectedKeyframes: vi.fn(),
     showToast: vi.fn(),
     domEditSelectionRef: { current: null },
+    readOnlyPreview: false,
+    ...overrides,
   };
 }
 
@@ -298,3 +304,65 @@ describe('dispatchPlainKey — "A" returns to select while the razor is armed',
     expect(e.defaultPrevented).toBe(false);
   });
 });
+
+describe("hotkeys with the preview read-only", () => {
+  beforeEach(() => {
+    usePlayerStore.setState({ elements: [bgmElement], selectedElementId: null });
+  });
+
+  it("does not delete the selected element on Delete", () => {
+    const cb = callbacks({ readOnlyPreview: true });
+    cb.domEditSelectionRef.current = { id: "card" } as DomEditSelection;
+    dispatchPlainKey(press("Delete"), "delete", cb);
+    expect(cb.handleDomEditElementDelete).not.toHaveBeenCalled();
+    expect(cb.handleTimelineElementsDelete).not.toHaveBeenCalled();
+  });
+
+  it("does not split on s", () => {
+    usePlayerStore.setState({
+      currentTime: 3,
+      elements: [{ ...bgmElement, hfId: "hf-bgm" }],
+      selectedElementId: "bgm",
+    });
+    const cb = callbacks({ readOnlyPreview: true });
+    dispatchPlainKey(press("s"), "s", cb);
+    expect(cb.handleTimelineElementSplit).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["x", "handleCut"],
+    ["d", "handleDuplicate"],
+    ["v", "handlePaste"],
+    ["g", "onGroupSelection"],
+  ] as const)("does not run %s", (key, callback) => {
+    const cb = callbacks({ readOnlyPreview: true });
+    cb.domEditSelectionRef.current = { id: "card" } as DomEditSelection;
+    dispatchModifierKey(chord(key), key, cb);
+    expect(cb[callback]).not.toHaveBeenCalled();
+  });
+
+  it("still undoes, because history covers timeline edits", () => {
+    const cb = callbacks({ readOnlyPreview: true });
+    dispatchModifierKey(chord("z"), "z", cb);
+    expect(cb.handleUndo).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps timeline paste when the mirrored preview selection is not the owner", () => {
+    usePlayerStore.setState({ selectedElementId: "bgm" });
+    const cb = callbacks({ readOnlyPreview: true });
+    cb.domEditSelectionRef.current = { id: "card" } as DomEditSelection;
+    const event = chord("v");
+    const timeline = document.createElement("div");
+    timeline.dataset.studioTimeline = "true";
+    Object.defineProperty(event, "target", { value: timeline });
+    dispatchModifierKey(event, "v", cb);
+    expect(cb.handlePaste).toHaveBeenCalledTimes(1);
+  });
+
+  it("control: with the flag off Delete removes the selected element", () => {
+    const cb = callbacks();
+    cb.domEditSelectionRef.current = { id: "card" } as DomEditSelection;
+    dispatchPlainKey(press("Delete"), "delete", cb);
+    expect(cb.handleDomEditElementDelete).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useAppHotkeys.textEditing.test.tsx

@@ -93,6 +93,7 @@ function Harness() {
     handleDuplicate: vi.fn(async () => false),
     onResetKeyframes: vi.fn(() => false),
     onDeleteSelectedKeyframes: keyframeDelete,
+    readOnlyPreview: false,
   });
 
   return (

package/src/hooks/useAppHotkeys.ts

@@ -101,6 +101,8 @@ interface UseAppHotkeysParams {
   onUngroupSelection?: () => void;
   /** Active composition path — used to decide whether undo/redo must resync the SDK session. */
   activeCompPath?: string | null;
+  /** Clicks still select and report; the preview cannot move, edit or delete anything. */
+  readOnlyPreview: boolean;
   /**
    * Force-reload the SDK session after undo/redo reverts the active comp file,
    * bypassing the self-write suppress window. Without this, the suppress window
@@ -135,6 +137,7 @@ export function useAppHotkeys({
   onUngroupSelection,
   activeCompPath,
   forceReloadSdkSession,
+  readOnlyPreview,
 }: UseAppHotkeysParams) {
   const previewHistoryCleanupRef = useRef<(() => void) | null>(null);
 
@@ -203,6 +206,7 @@ export function useAppHotkeys({
     onUngroupSelection,
     domEditSelectionRef,
     showToast,
+    readOnlyPreview,
   };
 
   // ── Keydown dispatch ──

package/src/hooks/useDomEditCommits.test.tsx

@@ -230,6 +230,7 @@ function renderDomEditCommits(
       refreshDomEditSelectionFromPreview: vi.fn(),
       buildDomSelectionFromTarget: vi.fn(async () => null),
       onTrySdkPersist: options.onTrySdkPersist,
+      readOnlyPreview: false,
     });
     return null;
   }

package/src/hooks/useDomEditCommits.ts

@@ -89,6 +89,7 @@ export interface UseDomEditCommitsParams {
   ) => Promise<CutoverResult>;
   /** Resolver-shadow tripwire for z-index reorder targets (telemetry-only, decoupled from cutover). */
   onReorderShadow?: (targets: string[]) => void;
+  readOnlyPreview: boolean;
 }
 
 export function useDomEditCommits({
@@ -112,6 +113,7 @@ export function useDomEditCommits({
   onTrySdkPersist,
   onTrySdkDelete,
   onReorderShadow,
+  readOnlyPreview,
 }: UseDomEditCommitsParams) {
   const resolveImportedFontAsset = useCallback(
     (fontFamilyValue: string): ImportedFontAsset | null => {
@@ -452,6 +454,7 @@ export function useDomEditCommits({
     previewIframeRef,
     showToast,
     commitPositionPatchToHtml,
+    readOnlyPreview,
   });
 
   // ── Element lifecycle (delete, z-index reorder) ──

package/src/hooks/useDomEditSession.test.tsx

@@ -99,6 +99,7 @@ function createSessionParams(
     reloadPreview: vi.fn(),
     setRefreshKey: vi.fn(),
     handleTimelineElementsDelete: vi.fn(),
+    readOnlyPreview: false,
     ...overrides,
   };
 }

package/src/hooks/useDomEditSession.ts

@@ -58,6 +58,7 @@ export interface UseDomEditSessionParams extends DomEditTimelineParams {
   /** The timeline context menu's delete op — a canvas selection that IS a
    *  timeline row hands off here instead of the REST remove-elements path. */
   handleTimelineElementsDelete: (elements: TimelineElement[]) => Promise<void>;
+  readOnlyPreview: boolean;
 }
 
 export function useDomEditSession({
@@ -98,8 +99,10 @@ export function useDomEditSession({
   publishSdkSession,
   forceReloadSdkSession,
   handleTimelineElementsDelete,
+  readOnlyPreview,
 }: UseDomEditSessionParams) {
   const isMasterView = !activeCompPath || activeCompPath === "index.html";
+  const previewCaptionEditMode = captionEditMode && !readOnlyPreview;
   void _setRefreshKey;
   const {
     domEditSelection,
@@ -125,7 +128,7 @@ export function useDomEditSession({
     activeCompPath,
     isMasterView,
     compIdToSrc,
-    captionEditMode,
+    captionEditMode: previewCaptionEditMode,
     previewIframeRef,
     timelineElements,
     getTimelineSelectionSet,
@@ -247,6 +250,7 @@ export function useDomEditSession({
     refreshDomEditSelectionFromPreview,
     buildDomSelectionFromTarget,
     forceReloadSdkSession,
+    readOnlyPreview,
     onTrySdkPersist: sdkSession
       ? (selection, operations, originalContent, targetPath, options) => {
           // Decoupled tripwire, runs regardless of the cutover flag. originalContent lets
@@ -405,7 +409,6 @@ export function useDomEditSession({
     handleGsapRemoveAllKeyframes,
     handleResetSelectedElementKeyframes,
   } = useDomEditWiring({
-    // fallow-ignore-next-line code-duplication
     projectId,
     activeCompPath,
     domEditSelection,
@@ -414,7 +417,7 @@ export function useDomEditSession({
     refreshDomEditGroupSelectionsFromPreview,
     previewIframeRef,
     previewIframe,
-    captionEditMode,
+    captionEditMode: previewCaptionEditMode,
     refreshKey,
     gsapCacheVersion,
     bumpGsapCache,
@@ -451,7 +454,7 @@ export function useDomEditSession({
     handleBlockedDomMove,
     handleDomManualDragStart,
   } = usePreviewInteraction({
-    captionEditMode,
+    captionEditMode: previewCaptionEditMode,
     compositionLoading,
     previewIframeRef,
     showToast,

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 };