@hyperframes/studio 0.8.54 → 0.8.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.54",
+  "version": "0.8.56",
   "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.54",
-    "@hyperframes/parsers": "0.8.54",
-    "@hyperframes/player": "0.8.54",
-    "@hyperframes/studio-server": "0.8.54",
-    "@hyperframes/sdk": "0.8.54"
+    "@hyperframes/player": "0.8.56",
+    "@hyperframes/sdk": "0.8.56",
+    "@hyperframes/core": "0.8.56",
+    "@hyperframes/studio-server": "0.8.56",
+    "@hyperframes/parsers": "0.8.56"
   },
   "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.54"
+    "@hyperframes/producer": "0.8.56"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -63,8 +63,16 @@ import { useTimelineAddAtPlayhead } from "./hooks/useTimelineAddAtPlayhead";
 import { readStudioUrlStateFromWindow, resolveMasterCompositionPath } from "./utils/studioUrlState";
 import { useActiveComposition } from "./hooks/useActiveComposition";
 const getTimelineSelectionSet = () => usePlayerStore.getState().selectedElementIds;
+
+export interface StudioAppProps {
+  /** Clicks still select and report; the preview cannot move, edit or delete anything. */
+  readOnlyPreview?: boolean;
+  /** Short text shown on disabled hand-edit controls while `readOnlyPreview` is set. */
+  readOnlyPreviewReason?: string;
+}
+
 // fallow-ignore-next-line complexity
-export function StudioApp() {
+export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: StudioAppProps = {}) {
   const { projectId, resolving, waitingForServer } = useServerConnection();
   const initialUrlStateRef = useRef(readStudioUrlStateFromWindow());
   useStudioSessionStart(projectId, resolving, waitingForServer);
@@ -252,6 +260,7 @@ export function StudioApp() {
     activeCompPath,
     forceReloadSdkSession: sdkHandle.forceReload,
     onToggleRecording: () => handleToggleRecordingRef.current(),
+    readOnlyPreview,
   });
   const domEditSession = useDomEditSession({
     projectId,
@@ -291,6 +300,7 @@ export function StudioApp() {
     publishSdkSession: sdkHandle.publish,
     forceReloadSdkSession: sdkHandle.forceReload,
     handleTimelineElementsDelete: timelineEditing.handleTimelineElementsDelete,
+    readOnlyPreview,
   });
   domEditSelectionBridgeRef.current = domEditSession.domEditSelection;
   handleDomZIndexReorderCommitRef.current = domEditSession.handleDomZIndexReorderCommit;
@@ -346,6 +356,7 @@ export function StudioApp() {
     previewIframeRef,
     showToast,
     isGestureRecordingRef,
+    readOnlyPreview,
   });
   handleToggleRecordingRef.current = handleToggleRecording;
   const canvasRectRef = useRef<DOMRect | null>(null);
@@ -465,6 +476,8 @@ export function StudioApp() {
                 )}
                 <ExternalFileConflictBanner coordinator={externalFileChanges} />
                 <EditorShell
+                  readOnlyPreview={readOnlyPreview}
+                  readOnlyPreviewReason={readOnlyPreviewReason}
                   panels={
                     <>
                       <StudioLeftPanels

package/src/components/EditorShell.readOnlyHostMount.test.tsx

@@ -0,0 +1,116 @@
+// @vitest-environment happy-dom
+
+// A host that mounts EditorShell directly — no StudioApp, no App.tsx — must
+// still get its descendants gated purely from the readOnlyPreview prop.
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import "./EditorShellTestMocks";
+import { EditorShell } from "./EditorShell";
+import { usePreviewBlockDrop } from "./nle/usePreviewBlockDrop";
+import { TIMELINE_BLOCK_MIME } from "../utils/timelineAssetDrop";
+
+vi.mock("../hooks/useTimelineSelectionPreviewSync", () => ({
+  useTimelineSelectionPreviewSync: vi.fn(),
+}));
+vi.mock("./nle/PreviewOverlays", () => ({ PreviewOverlays: () => null }));
+
+// The real hook — this is the actual Tier-1 consumer a host relies on to gate
+// a drop onto the preview. Only PreviewPane's own DOM/player chrome is mocked.
+const stage = document.createElement("div");
+stage.getBoundingClientRect = () => ({ left: 0, top: 0, width: 100, height: 100 }) as DOMRect;
+const dropHandlers: { current: ReturnType<typeof usePreviewBlockDrop> | null } = { current: null };
+vi.mock("./nle/PreviewPane", () => ({
+  PreviewPane: (props: { onPreviewBlockDrop?: (name: string, pos: unknown) => void }) => {
+    dropHandlers.current = usePreviewBlockDrop({
+      stageRef: { current: stage },
+      compositionSize: { width: 1000, height: 1000 },
+      onBlockDrop: props.onPreviewBlockDrop,
+    });
+    return null;
+  },
+}));
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let root: ReturnType<typeof createRoot> | null = null;
+
+afterEach(() => {
+  if (root) act(() => root!.unmount());
+  root = null;
+  document.body.innerHTML = "";
+});
+
+function mountShellAlone(
+  readOnlyPreview: boolean,
+  onPreviewBlockDrop: (...args: unknown[]) => void,
+) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() =>
+    root!.render(
+      <EditorShell
+        panels={null}
+        timelineToolbar={null}
+        renderClipContent={() => null}
+        handleTimelineElementDelete={vi.fn()}
+        handleTimelineAssetDrop={vi.fn()}
+        handleTimelineFileDrop={vi.fn()}
+        handleTimelineElementMove={vi.fn()}
+        handleTimelineElementsMove={vi.fn()}
+        handleTimelineElementResize={vi.fn()}
+        handleTimelineGroupResize={vi.fn()}
+        handleToggleTrackHidden={vi.fn()}
+        setAudioGroupAttribute={{ setLive: vi.fn(), setQuiet: vi.fn() }}
+        handleBlockedTimelineEdit={vi.fn()}
+        handleTimelineElementSplit={vi.fn()}
+        handleRazorSplit={vi.fn()}
+        handleRazorSplitAll={vi.fn()}
+        onCopyClip={vi.fn(() => false)}
+        onPasteClip={vi.fn(async () => {})}
+        onDuplicateClip={vi.fn(async () => false)}
+        canPasteClip={vi.fn(() => false)}
+        setCompIdToSrc={vi.fn()}
+        setCompositionLoading={vi.fn()}
+        shouldShowMotionPath={false}
+        shouldShowSelectedDomBounds={false}
+        handlePreviewBlockDrop={onPreviewBlockDrop}
+        readOnlyPreview={readOnlyPreview}
+      />,
+    ),
+  );
+  return { host, root };
+}
+
+function dropEvent() {
+  return {
+    clientX: 50,
+    clientY: 50,
+    preventDefault: vi.fn(),
+    dataTransfer: {
+      types: [TIMELINE_BLOCK_MIME],
+      getData: () => JSON.stringify({ name: "lower-third" }),
+    },
+  };
+}
+
+describe("a host mounting EditorShell alone (no StudioApp, no App.tsx)", () => {
+  it("gates a Tier-1 descendant's drop handling purely from the prop", () => {
+    const onBlockDrop = vi.fn();
+    mountShellAlone(true, onBlockDrop);
+    const event = dropEvent();
+    act(() => dropHandlers.current!.handleDrop(event as never));
+    expect(onBlockDrop).not.toHaveBeenCalled();
+    expect(event.preventDefault).not.toHaveBeenCalled();
+  });
+
+  it("control: with the flag off, the same descendant still places a drop", () => {
+    const onBlockDrop = vi.fn();
+    mountShellAlone(false, onBlockDrop);
+    const event = dropEvent();
+    act(() => dropHandlers.current!.handleDrop(event as never));
+    expect(onBlockDrop).toHaveBeenCalledWith("lower-third", { left: 500, top: 500 });
+  });
+});

package/src/components/EditorShell.selectionSync.test.tsx

@@ -3,54 +3,27 @@
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import "./EditorShellTestMocks";
 import { EditorShell } from "./EditorShell";
+import { usePreviewReadOnly } from "./editor/previewReadOnlyContext";
 
 const hookMocks = vi.hoisted(() => ({
   useTimelineSelectionPreviewSync: vi.fn(),
 }));
+const previewOverlaysProbe = vi.hoisted(() => ({ readOnly: null as boolean | null }));
 
 vi.mock("../hooks/useTimelineSelectionPreviewSync", () => hookMocks);
-vi.mock("../contexts/StudioContext", () => ({
-  useStudioPlaybackContext: () => ({
-    captionEditMode: false,
-    refreshKey: 0,
-    refreshPreviewDocumentVersion: vi.fn(),
-    timelineElements: [],
-  }),
-  useStudioShellContext: () => ({
-    projectId: "project-1",
-    activeCompPath: "index.html",
-    setActiveCompPath: vi.fn(),
-    handlePreviewIframeRef: vi.fn(),
-    showToast: vi.fn(),
-  }),
+vi.mock("./nle/PreviewPane", () => ({
+  // Renders its previewOverlay prop for real, so the mocked PreviewOverlays
+  // below (which reads the read-only context) actually mounts.
+  PreviewPane: (props: { previewOverlay?: React.ReactNode }) => props.previewOverlay ?? null,
 }));
-vi.mock("../contexts/DomEditContext", () => ({
-  useDomEditActionsContext: () => ({
-    handleTimelineElementSelect: vi.fn(),
-    buildDomSelectionForTimelineElement: vi.fn(),
-    applyDomSelection: vi.fn(),
-    applyMarqueeSelection: vi.fn(),
-  }),
-  useDomEditSelectionContext: () => ({
-    domEditSelection: null,
-    domEditGroupSelections: [],
-  }),
-}));
-vi.mock("./nle/NLEContext", () => ({
-  NLEProvider: ({ children }: { children: React.ReactNode }) => children,
-  useNLEContext: () => ({
-    compositionStack: [],
-    updateCompositionStack: vi.fn(),
-  }),
-}));
-vi.mock("./nle/useTimelineEditCallbacks", () => ({
-  useTimelineEditCallbacks: () => ({}),
+vi.mock("./nle/PreviewOverlays", () => ({
+  PreviewOverlays: () => {
+    previewOverlaysProbe.readOnly = usePreviewReadOnly();
+    return null;
+  },
 }));
-vi.mock("./nle/PreviewPane", () => ({ PreviewPane: () => null }));
-vi.mock("./nle/PreviewOverlays", () => ({ PreviewOverlays: () => null }));
-vi.mock("./nle/TimelinePane", () => ({ TimelinePane: () => null }));
-vi.mock("../captions/components/CaptionTimeline", () => ({ CaptionTimeline: () => null }));
 
 Object.assign(globalThis, {
   IS_REACT_ACT_ENVIRONMENT: true,
@@ -66,6 +39,36 @@ afterEach(() => {
   hookMocks.useTimelineSelectionPreviewSync.mockClear();
 });
 
+const shell = (readOnlyPreview?: boolean) => (
+  <EditorShell
+    panels={null}
+    timelineToolbar={null}
+    renderClipContent={() => null}
+    handleTimelineElementDelete={vi.fn()}
+    handleTimelineAssetDrop={vi.fn()}
+    handleTimelineFileDrop={vi.fn()}
+    handleTimelineElementMove={vi.fn()}
+    handleTimelineElementsMove={vi.fn()}
+    handleTimelineElementResize={vi.fn()}
+    handleTimelineGroupResize={vi.fn()}
+    handleToggleTrackHidden={vi.fn()}
+    setAudioGroupAttribute={{ setLive: vi.fn(), setQuiet: vi.fn() }}
+    handleBlockedTimelineEdit={vi.fn()}
+    handleTimelineElementSplit={vi.fn()}
+    handleRazorSplit={vi.fn()}
+    handleRazorSplitAll={vi.fn()}
+    onCopyClip={vi.fn(() => false)}
+    onPasteClip={vi.fn(async () => {})}
+    onDuplicateClip={vi.fn(async () => false)}
+    canPasteClip={vi.fn(() => false)}
+    setCompIdToSrc={vi.fn()}
+    setCompositionLoading={vi.fn()}
+    shouldShowMotionPath={false}
+    shouldShowSelectedDomBounds={false}
+    readOnlyPreview={readOnlyPreview}
+  />
+);
+
 describe("EditorShell timeline selection sync", () => {
   it("keeps the timeline store mirrored into the preview selection", () => {
     const host = document.createElement("div");
@@ -73,34 +76,7 @@ describe("EditorShell timeline selection sync", () => {
     const root = createRoot(host);
 
     act(() => {
-      root.render(
-        <EditorShell
-          panels={null}
-          timelineToolbar={null}
-          renderClipContent={() => null}
-          handleTimelineElementDelete={vi.fn()}
-          handleTimelineAssetDrop={vi.fn()}
-          handleTimelineFileDrop={vi.fn()}
-          handleTimelineElementMove={vi.fn()}
-          handleTimelineElementsMove={vi.fn()}
-          handleTimelineElementResize={vi.fn()}
-          handleTimelineGroupResize={vi.fn()}
-          handleToggleTrackHidden={vi.fn()}
-          setAudioGroupAttribute={{ setLive: vi.fn(), setQuiet: vi.fn() }}
-          handleBlockedTimelineEdit={vi.fn()}
-          handleTimelineElementSplit={vi.fn()}
-          handleRazorSplit={vi.fn()}
-          handleRazorSplitAll={vi.fn()}
-          onCopyClip={vi.fn(() => false)}
-          onPasteClip={vi.fn(async () => {})}
-          onDuplicateClip={vi.fn(async () => false)}
-          canPasteClip={vi.fn(() => false)}
-          setCompIdToSrc={vi.fn()}
-          setCompositionLoading={vi.fn()}
-          shouldShowMotionPath={false}
-          shouldShowSelectedDomBounds={false}
-        />,
-      );
+      root.render(shell());
     });
 
     expect(hookMocks.useTimelineSelectionPreviewSync).toHaveBeenCalledOnce();
@@ -115,4 +91,18 @@ describe("EditorShell timeline selection sync", () => {
 
     act(() => root.unmount());
   });
+
+  it("threads the read-only prop into descendants via context, and follows it across renders", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    act(() => root.render(shell(true)));
+    expect(previewOverlaysProbe.readOnly).toBe(true);
+    act(() => root.render(shell(false)));
+    expect(previewOverlaysProbe.readOnly).toBe(false);
+    act(() => root.render(shell(true)));
+    expect(previewOverlaysProbe.readOnly).toBe(true);
+    act(() => root.unmount());
+  });
 });

package/src/components/EditorShell.tsx

@@ -2,6 +2,7 @@ import { useCallback, type ReactNode } from "react";
 import { PreviewPane } from "./nle/PreviewPane";
 import { TimelinePane } from "./nle/TimelinePane";
 import { PreviewOverlays } from "./nle/PreviewOverlays";
+import { PreviewReadOnlyProvider } from "./editor/previewReadOnlyContext";
 import {
   useTimelineEditCallbacks,
   type TimelineEditCallbackDeps,
@@ -69,6 +70,10 @@ export interface EditorShellProps extends TimelineEditCallbackDeps {
    * fullscreen and during a block preview; below the selection overlay past z-index 10.
    */
   gestureOverlay?: ReactNode;
+  /** Clicks still select and report; the preview cannot move, edit or delete anything. */
+  readOnlyPreview?: boolean;
+  /** Short text shown on disabled hand-edit controls while `readOnlyPreview` is set. */
+  readOnlyPreviewReason?: string;
 }
 
 // The dockable shell: every panel lives in one Dock, arranged by the user's
@@ -109,6 +114,8 @@ export function EditorShell({
   onToggleRecording,
   blockPreview,
   gestureOverlay,
+  readOnlyPreview = false,
+  readOnlyPreviewReason,
 }: EditorShellProps) {
   const { projectId, activeCompPath, setActiveCompPath, handlePreviewIframeRef, showToast } =
     useStudioShellContext();
@@ -156,57 +163,59 @@ export function EditorShell({
   });
 
   return (
-    <div className="flex flex-col flex-1 min-h-0">
-      <TimelineEditProvider value={timelineEditCallbacks}>
-        <NLEProvider
-          projectId={projectId}
-          refreshKey={refreshKey}
-          activeCompositionPath={activeCompPath}
-          onIframeRef={handlePreviewIframeRef}
-          onCompIdToSrcChange={setCompIdToSrc}
-          onCompositionLoadingChange={setCompositionLoading}
-          onCompositionChange={(compPath) => {
-            // Sync activeCompPath when the user drills down via the timeline or
-            // navigates back — keeps sidebar + thumbnails in sync. Guard no-ops to
-            // avoid circular refresh cascades (activeCompPath → stack → onChange).
-            if (compPath !== activeCompPath) {
-              setActiveCompPath(compPath);
-              refreshPreviewDocumentVersion();
-            }
-          }}
-        >
-          <EditorShellBody
+    <PreviewReadOnlyProvider readOnly={readOnlyPreview} reason={readOnlyPreviewReason}>
+      <div className="flex flex-col flex-1 min-h-0">
+        <TimelineEditProvider value={timelineEditCallbacks}>
+          <NLEProvider
             projectId={projectId}
-            panels={panels}
-            captionEditMode={captionEditMode}
-            onSelectTimelineElement={handleTimelineElementSelect}
-            onPreviewBlockDrop={handlePreviewBlockDrop}
-            timelineToolbar={timelineToolbar}
-            renderClipContent={renderClipContent}
-            onFileDrop={handleTimelineFileDrop}
-            onAssetDrop={handleTimelineAssetDrop}
-            onBlockDrop={handleTimelineBlockDrop}
-            onCompositionDrop={handleTimelineCompositionDrop}
-            onDeleteElement={handleTimelineElementDelete}
-            onCopyClip={onCopyClip}
-            onPasteClip={onPasteClip}
-            onDuplicateClip={onDuplicateClip}
-            canPasteClip={canPasteClip}
-            previewOverlay={
-              <PreviewOverlays
-                shouldShowMotionPath={shouldShowMotionPath}
-                shouldShowSelectedDomBounds={shouldShowSelectedDomBounds}
-                blockPreview={blockPreview}
-                isGestureRecording={isGestureRecording}
-                recordingState={recordingState}
-                onToggleRecording={onToggleRecording}
-                gestureOverlay={gestureOverlay}
-              />
-            }
-          />
-        </NLEProvider>
-      </TimelineEditProvider>
-    </div>
+            refreshKey={refreshKey}
+            activeCompositionPath={activeCompPath}
+            onIframeRef={handlePreviewIframeRef}
+            onCompIdToSrcChange={setCompIdToSrc}
+            onCompositionLoadingChange={setCompositionLoading}
+            onCompositionChange={(compPath) => {
+              // Sync activeCompPath when the user drills down via the timeline or
+              // navigates back — keeps sidebar + thumbnails in sync. Guard no-ops to
+              // avoid circular refresh cascades (activeCompPath → stack → onChange).
+              if (compPath !== activeCompPath) {
+                setActiveCompPath(compPath);
+                refreshPreviewDocumentVersion();
+              }
+            }}
+          >
+            <EditorShellBody
+              projectId={projectId}
+              panels={panels}
+              captionEditMode={captionEditMode}
+              onSelectTimelineElement={handleTimelineElementSelect}
+              onPreviewBlockDrop={handlePreviewBlockDrop}
+              timelineToolbar={timelineToolbar}
+              renderClipContent={renderClipContent}
+              onFileDrop={handleTimelineFileDrop}
+              onAssetDrop={handleTimelineAssetDrop}
+              onBlockDrop={handleTimelineBlockDrop}
+              onCompositionDrop={handleTimelineCompositionDrop}
+              onDeleteElement={handleTimelineElementDelete}
+              onCopyClip={onCopyClip}
+              onPasteClip={onPasteClip}
+              onDuplicateClip={onDuplicateClip}
+              canPasteClip={canPasteClip}
+              previewOverlay={
+                <PreviewOverlays
+                  shouldShowMotionPath={shouldShowMotionPath}
+                  shouldShowSelectedDomBounds={shouldShowSelectedDomBounds}
+                  blockPreview={blockPreview}
+                  isGestureRecording={isGestureRecording}
+                  recordingState={recordingState}
+                  onToggleRecording={onToggleRecording}
+                  gestureOverlay={gestureOverlay}
+                />
+              }
+            />
+          </NLEProvider>
+        </TimelineEditProvider>
+      </div>
+    </PreviewReadOnlyProvider>
   );
 }
 

package/src/components/EditorShellTestMocks.ts

@@ -0,0 +1,46 @@
+import React from "react";
+import { vi } from "vitest";
+
+vi.mock("../contexts/StudioContext", () => ({
+  useStudioPlaybackContext: () => ({
+    captionEditMode: false,
+    refreshKey: 0,
+    refreshPreviewDocumentVersion: vi.fn(),
+    timelineElements: [],
+  }),
+  useStudioShellContext: () => ({
+    projectId: "project-1",
+    activeCompPath: "index.html",
+    setActiveCompPath: vi.fn(),
+    handlePreviewIframeRef: vi.fn(),
+    showToast: vi.fn(),
+  }),
+}));
+
+vi.mock("../contexts/DomEditContext", () => ({
+  useDomEditActionsContext: () => ({
+    handleTimelineElementSelect: vi.fn(),
+    buildDomSelectionForTimelineElement: vi.fn(),
+    applyDomSelection: vi.fn(),
+    applyMarqueeSelection: vi.fn(),
+  }),
+  useDomEditSelectionContext: () => ({
+    domEditSelection: null,
+    domEditGroupSelections: [],
+  }),
+}));
+
+vi.mock("./nle/NLEContext", () => ({
+  NLEProvider: ({ children }: { children: React.ReactNode }) => children,
+  useNLEContext: () => ({
+    compositionStack: [],
+    updateCompositionStack: vi.fn(),
+    containerRef: { current: null },
+  }),
+}));
+
+vi.mock("./nle/useTimelineEditCallbacks", () => ({
+  useTimelineEditCallbacks: () => ({}),
+}));
+vi.mock("./nle/TimelinePane", () => ({ TimelinePane: () => null }));
+vi.mock("../captions/components/CaptionTimeline", () => ({ CaptionTimeline: () => null }));

package/src/components/editor/DomEditOverlay.tsx

@@ -1,4 +1,4 @@
-import { memo, useEffect, useMemo, useRef, useState, type RefObject } from "react";
+import { memo, useEffect, useMemo, useRef, type RefObject } from "react";
 import { type DomEditSelection } from "./domEditing";
 import type { PreviewMouseDownOptions } from "../../hooks/usePreviewInteraction";
 import { useMarqueeGestures } from "./marqueeCommit";
@@ -16,7 +16,7 @@ import {
   resolveShiftClickCandidate,
 } from "./domEditOverlayGestures";
 import { useDomEditOverlayRects } from "./useDomEditOverlayRects";
-import { ChildRectOutlines, OffCanvasIndicators, type OffCanvasRect } from "./OffCanvasIndicators";
+import { ChildRectOutlines, OffCanvasIndicators } from "./OffCanvasIndicators";
 import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
 import { useDomEditNudge } from "./useDomEditNudge";
 import { SnapGuideOverlay, type SnapGuidesState } from "./SnapGuideOverlay";
@@ -27,13 +27,13 @@ import { hugRectForElement } from "./domEditOverlayCrop";
 import { useCropOverlay } from "../../hooks/useCropOverlay";
 import { readDomEditSelectionShapeStyles, resolveBoxChromeClass } from "./domEditOverlayShape";
 import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
-import { useMountEffect } from "../../hooks/useMountEffect";
-import { startOffCanvasIndicatorRefresh } from "./offCanvasIndicatorRefresh";
 import { CanvasContextMenu } from "./CanvasContextMenu";
 import { useInlineTextEditing } from "./useInlineTextEditing";
+import { usePreviewReadOnly } from "./previewReadOnlyContext";
 import type { ZOrderAction, ZOrderPatch } from "./canvasContextMenuZOrder";
 import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";
 import { logSelect } from "../../utils/selectDebug";
+import { useOffCanvasIndicators } from "./useOffCanvasIndicators";
 
 // Re-exports for external consumers — preserving existing import paths.
 export {
@@ -137,6 +137,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onDeleteSelection,
   onApplyZIndex,
 }: DomEditOverlayProps) {
+  const readOnly = usePreviewReadOnly();
   const overlayRef = useRef<HTMLDivElement | null>(null);
   const boxRef = useRef<HTMLDivElement | null>(null);
   const onMarqueeSelectRef = useRef(onMarqueeSelect);
@@ -220,39 +221,13 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   const boxClipPath = hasCropInsets ? undefined : selectionShapeStyles.clipPath;
   const boxChromeClass = resolveBoxChromeClass(Boolean(cropOutlineInsetPx), boxClipPath);
 
-  // Off-canvas element indicators — dashed outlines for elements positioned
-  // outside the composition bounds so users can find them.
-  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);
-
-  // Positions depend on live iframe layout, not selection — the selected-element
-  // suppression is a render-time filter, so selection/groupSelections stay out
-  // of the geometry walk.
-  useMountEffect(() =>
-    startOffCanvasIndicatorRefresh({
-      iframeRef,
-      overlayRef,
-      compRectRef,
-      activeCompositionPathRef,
-      dirtyRef: offCanvasDirtyRef,
-      sigRef: offCanvasSigRef,
-      observerRef: offCanvasObserverRef,
-      observedDocRef: offCanvasObservedDocRef,
-      elementsRef: offCanvasElementsRef,
-      setRects: setOffCanvasRects,
-    }),
-  );
-
-  // Switching compositions may not swap the iframe document (so the observer's
-  // doc-swap detection wouldn't fire) yet changes which elements are off-canvas.
-  // Force a recompute explicitly on comp change.
-  useEffect(() => {
-    offCanvasDirtyRef.current = true;
-  }, [activeCompositionPath]);
+  const { offCanvasRects, offCanvasElementsRef } = useOffCanvasIndicators({
+    iframeRef,
+    overlayRef,
+    compRectRef,
+    activeCompositionPathRef,
+    activeCompositionPath,
+  });
 
   const gestures = createDomEditOverlayGestureHandlers({
     overlayRef,
@@ -280,12 +255,16 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     snapGuidesRef,
   });
 
+  useEffect(() => {
+    if (readOnly) gestures.clearPointerState(selectionRef);
+  }, [gestures, readOnly, selectionRef]);
+
   // Arrow-key nudge (1px, Shift = 10px) — commits through the same
   // path-offset callbacks as a drag, one undo entry per key burst.
   const { flushNudge } = useDomEditNudge({
     selection,
     groupSelections,
-    allowCanvasMovement,
+    allowCanvasMovement: allowCanvasMovement && !readOnly,
     selectionRef,
     overlayRectRef,
     groupOverlayItemsRef,
@@ -558,7 +537,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           selection={contextMenu.sel}
           onClose={closeContextMenu}
           onDelete={
-            onDeleteSelection
+            onDeleteSelection && !readOnly
               ? (sel) => {
                   closeContextMenu();
                   onDeleteSelection(sel);
@@ -566,7 +545,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
               : undefined
           }
           onApplyZIndex={
-            onApplyZIndex
+            onApplyZIndex && !readOnly
               ? (patches, action, crossed) => {
                   onApplyZIndex(contextMenu.sel, patches, action, crossed);
                 }