@hyperframes/studio 0.8.55 → 0.8.57

package/src/components/editor/previewReadOnly.overlay.test.tsx

@@ -0,0 +1,260 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { makeSelection } from "../../hooks/domSelectionTestHarness";
+import { CANVAS_NUDGE_COMMIT_DEBOUNCE_MS } from "./domEditNudge";
+import { __resetForTests } from "../../utils/canvasNudgeGate";
+import { PreviewReadOnlyProvider } from "./previewReadOnlyContext";
+import "./domEditOverlayTestMocks";
+import { DomEditOverlay } from "./DomEditOverlay";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const RECT = { left: 100, top: 100, width: 200, height: 100, editScaleX: 1, editScaleY: 1 };
+const layout = vi.hoisted(() => ({ group: [] as unknown[] }));
+
+vi.mock("./useDomEditOverlayRects", () => ({
+  useDomEditOverlayRects: () => ({
+    overlayRect: { left: 100, top: 100, width: 200, height: 100, editScaleX: 1, editScaleY: 1 },
+    overlayRectRef: {
+      current: { left: 100, top: 100, width: 200, height: 100, editScaleX: 1, editScaleY: 1 },
+    },
+    setOverlayRect: () => undefined,
+    hoverRect: null,
+    groupOverlayItems: layout.group,
+    groupOverlayItemsRef: { current: layout.group },
+    setGroupOverlayItems: () => undefined,
+    childRects: [],
+  }),
+}));
+const BOX = '[data-dom-edit-selection-box="true"]';
+let root: Root;
+let host: HTMLElement;
+
+function textElement(id: string): HTMLElement {
+  const element = document.createElement("h1");
+  element.id = id;
+  element.textContent = "Title";
+  document.body.append(element);
+  return element;
+}
+
+function fixture(
+  overrides: Partial<React.ComponentProps<typeof DomEditOverlay>> = {},
+  readOnly = false,
+) {
+  const spies = {
+    onCanvasMouseDown: vi.fn(),
+    onSelectionChange: vi.fn(),
+    onManualDragStart: vi.fn(),
+    onBlockedMove: vi.fn(),
+    onPathOffsetCommit: vi.fn(),
+    onGroupPathOffsetCommit: vi.fn(),
+    onBoxSizeCommit: vi.fn(),
+    onRotationCommit: vi.fn(),
+    onStyleCommit: vi.fn(),
+    onDeleteSelection: vi.fn(),
+    onApplyZIndex: vi.fn(),
+  };
+  const selection = makeSelection("Title", textElement("title"));
+  selection.capabilities.canApplyManualRotation = true;
+  selection.textFields = [{ key: "text", label: "Text", value: "Title" }] as never;
+  const props = {
+    iframeRef: { current: document.createElement("iframe") },
+    activeCompositionPath: null,
+    selection,
+    hoverSelection: null,
+    onCanvasPointerMove: () => Promise.resolve(selection),
+    onCanvasPointerLeave: () => undefined,
+    ...spies,
+    ...overrides,
+  };
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() =>
+    root.render(
+      <PreviewReadOnlyProvider readOnly={readOnly}>
+        <DomEditOverlay {...props} />
+      </PreviewReadOnlyProvider>,
+    ),
+  );
+  return { spies, selection, overlay: host.firstElementChild as HTMLElement };
+}
+
+const fire = (target: Element, type: string, init: MouseEventInit = {}) => {
+  const event = new MouseEvent(type, { bubbles: true, cancelable: true, button: 0, ...init });
+  act(() => {
+    target.dispatchEvent(event);
+  });
+  return event;
+};
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  __resetForTests();
+  HTMLElement.prototype.setPointerCapture = () => undefined;
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  document.body.innerHTML = "";
+  layout.group = [];
+  vi.useRealTimers();
+});
+
+describe("DomEditOverlay with the preview read-only", () => {
+  it("control: with the flag off a press on the box starts a move", () => {
+    const { spies, overlay } = fixture();
+    fire(overlay.querySelector(BOX)!, "pointerdown");
+    expect(spies.onManualDragStart).toHaveBeenCalledTimes(1);
+  });
+
+  it("refuses to start a move from the selection box", () => {
+    const { spies, overlay } = fixture({}, true);
+    const box = overlay.querySelector(BOX)!;
+    fire(box, "pointerdown");
+    fire(box, "pointermove", { clientX: 40 });
+    fire(box, "pointerup");
+    expect(spies.onManualDragStart).not.toHaveBeenCalled();
+    expect(spies.onBlockedMove).not.toHaveBeenCalled();
+    expect(spies.onPathOffsetCommit).not.toHaveBeenCalled();
+  });
+
+  it("offers no resize dots, and none can start a resize", () => {
+    const off = fixture();
+    expect(off.overlay.querySelectorAll("div.h-4.w-4")).toHaveLength(4);
+    act(() => root.unmount());
+    document.body.innerHTML = "";
+    const { spies, overlay } = fixture({}, true);
+    expect(overlay.querySelectorAll("div.h-4.w-4")).toHaveLength(0);
+    expect(spies.onBoxSizeCommit).not.toHaveBeenCalled();
+  });
+
+  it("offers no rotate handle", () => {
+    const off = fixture();
+    expect(off.overlay.querySelector('[aria-label="Rotate selection"]')).not.toBeNull();
+    act(() => root.unmount());
+    document.body.innerHTML = "";
+    const { spies, overlay } = fixture({}, true);
+    expect(overlay.querySelector('[aria-label="Rotate selection"]')).toBeNull();
+    expect(spies.onRotationCommit).not.toHaveBeenCalled();
+  });
+
+  it("offers no crop handles, so clip-path is never committed", () => {
+    const off = fixture();
+    expect(off.overlay.querySelector("[data-dom-edit-crop-frame]")).not.toBeNull();
+    act(() => root.unmount());
+    document.body.innerHTML = "";
+    const { spies, overlay } = fixture({}, true);
+    expect(overlay.querySelector("[data-dom-edit-crop-frame]")).toBeNull();
+    expect(spies.onStyleCommit).not.toHaveBeenCalled();
+  });
+
+  it("does not drag a multi-selection", () => {
+    const members = ["a", "b"].map((id) => {
+      const selection = makeSelection(id, textElement(id));
+      return { key: id, selection, element: selection.element, rect: RECT };
+    });
+    layout.group = members;
+    const { spies, overlay } = fixture(
+      {
+        selection: null,
+        groupSelections: members.map((m) => m.selection),
+      },
+      true,
+    );
+    fire(overlay.querySelector(BOX)!, "pointerdown");
+    expect(spies.onManualDragStart).not.toHaveBeenCalled();
+    expect(spies.onGroupPathOffsetCommit).not.toHaveBeenCalled();
+  });
+
+  const nudge = () => {
+    const event = new KeyboardEvent("keydown", {
+      key: "ArrowRight",
+      bubbles: true,
+      cancelable: true,
+    });
+    act(() => {
+      window.dispatchEvent(event);
+      vi.advanceTimersByTime(CANVAS_NUDGE_COMMIT_DEBOUNCE_MS + 10);
+    });
+    return event;
+  };
+
+  it("control: with the flag off an arrow key nudges", () => {
+    const { spies } = fixture();
+    expect(nudge().defaultPrevented).toBe(true);
+    expect(spies.onPathOffsetCommit).toHaveBeenCalledTimes(1);
+  });
+
+  it("neither nudges on an arrow key nor swallows it", () => {
+    const { spies } = fixture({}, true);
+    expect(nudge().defaultPrevented).toBe(false);
+    expect(spies.onPathOffsetCommit).not.toHaveBeenCalled();
+  });
+
+  const pressEnter = (overlay: HTMLElement) =>
+    act(() => {
+      overlay.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }),
+      );
+    });
+
+  it("control: with the flag off Enter opens the text for editing", () => {
+    const { selection, overlay } = fixture();
+    pressEnter(overlay);
+    expect(selection.element.hasAttribute("contenteditable")).toBe(true);
+  });
+
+  it("does not open text for editing on Enter", () => {
+    const { selection, overlay } = fixture({}, true);
+    pressEnter(overlay);
+    expect(selection.element.hasAttribute("contenteditable")).toBe(false);
+  });
+
+  const rightClick = async (overlay: HTMLElement) => {
+    await act(async () => {
+      overlay.dispatchEvent(
+        new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 5, clientY: 5 }),
+      );
+    });
+  };
+
+  it("control: with the flag off right-click offers delete and z-order", async () => {
+    const { overlay } = fixture();
+    await rightClick(overlay);
+    expect(document.body.textContent).toContain("Delete");
+  });
+
+  it("offers no delete or z-order on right-click when read-only", async () => {
+    // Same fixture as the control test above (a real, already-selected element) so the
+    // context menu actually opens; `selection: null` here would close it via
+    // useCanvasContextMenuState's own deselect effect, before read-only ever mattered.
+    const { spies, overlay } = fixture({}, true);
+    await rightClick(overlay);
+    expect(document.body.textContent).not.toContain("Delete");
+    expect(spies.onDeleteSelection).not.toHaveBeenCalled();
+    expect(spies.onApplyZIndex).not.toHaveBeenCalled();
+  });
+
+  it("still selects and reports to the host on right-click of an unselected element", async () => {
+    const { spies, overlay } = fixture({ selection: null }, true);
+    await rightClick(overlay);
+    expect(spies.onSelectionChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("still selects and reports to the host on a click", () => {
+    const { spies, overlay } = fixture({ selection: null }, true);
+    fire(overlay, "mousedown");
+    expect(spies.onCanvasMouseDown).toHaveBeenCalledTimes(1);
+  });
+
+  it("still selects on a click of the selection box", () => {
+    const { spies, overlay } = fixture({}, true);
+    fire(overlay.querySelector(BOX)!, "click");
+    expect(spies.onCanvasMouseDown).toHaveBeenCalledTimes(1);
+  });
+});

package/src/components/editor/previewReadOnlyContext.tsx

@@ -0,0 +1,59 @@
+import { useContext, useMemo, type ReactNode } from "react";
+import { createStableContext } from "../../utils/hmrStableContext";
+
+interface PreviewReadOnlyValue {
+  readOnly: boolean;
+  reason: string;
+}
+
+const DEFAULT_REASON = "Preview is read-only.";
+
+// Real default (not a throwing required-provider context): most existing
+// mounts render with no wrapper at all and must stay editable, exactly as today.
+const PreviewReadOnlyContext = createStableContext<PreviewReadOnlyValue>("PreviewReadOnlyContext", {
+  readOnly: false,
+  reason: DEFAULT_REASON,
+});
+
+export function PreviewReadOnlyProvider({
+  readOnly,
+  reason,
+  children,
+}: {
+  readOnly: boolean;
+  reason?: string;
+  children: ReactNode;
+}) {
+  const value = useMemo(() => ({ readOnly, reason: reason ?? DEFAULT_REASON }), [readOnly, reason]);
+  return <PreviewReadOnlyContext value={value}>{children}</PreviewReadOnlyContext>;
+}
+
+export function usePreviewReadOnly(): boolean {
+  return useContext(PreviewReadOnlyContext).readOnly;
+}
+
+/** Short host-supplied text for why a hand-edit control is disabled. */
+export function usePreviewReadOnlyReason(): string {
+  return useContext(PreviewReadOnlyContext).reason;
+}
+
+interface ManualEditCapabilities {
+  canApplyManualOffset: boolean;
+  canApplyManualSize: boolean;
+  canApplyManualRotation: boolean;
+}
+
+/**
+ * The manual X/Y/W/H/rotation fields' disabled state: capability, or preview read-only.
+ * Call unconditionally, even with no selection — `capabilities` may be null/undefined.
+ */
+export function useManualEditDisabledFlags(
+  capabilities: ManualEditCapabilities | null | undefined,
+) {
+  const { readOnly } = useContext(PreviewReadOnlyContext);
+  return {
+    manualOffsetEditingDisabled: !capabilities?.canApplyManualOffset || readOnly,
+    manualSizeEditingDisabled: !capabilities?.canApplyManualSize || readOnly,
+    manualRotationEditingDisabled: !capabilities?.canApplyManualRotation || readOnly,
+  };
+}

package/src/components/editor/propertyPanelFlatLayoutSection.tsx

@@ -5,6 +5,7 @@ import { formatPxMetricValue } from "./propertyPanelHelpers";
 import { resolveValueTier } from "./propertyPanelValueTier";
 import { PropertyPanel3dTransform } from "./propertyPanel3dTransform";
 import type { DomEditSelection } from "./domEditingTypes";
+import { usePreviewReadOnly, usePreviewReadOnlyReason } from "./previewReadOnlyContext";
 
 type KeyframeEntry = Array<{
   percentage: number;
@@ -119,6 +120,9 @@ export function LayoutGeometryRows({
   onRemoveKeyframe,
   onConvertToKeyframes,
 }: GeometryRowsProps) {
+  const readOnlyPreview = usePreviewReadOnly();
+  const readOnlyPreviewReason = usePreviewReadOnlyReason();
+  const readOnlyTooltip = readOnlyPreview ? readOnlyPreviewReason : undefined;
   const gutterProps = {
     element,
     gsapAnimId,
@@ -137,6 +141,7 @@ export function LayoutGeometryRows({
         value={formatPxMetricValue(displayX)}
         tier={displayX === 0 ? "default" : "explicitCustom"}
         disabled={manualOffsetEditingDisabled}
+        tooltip={readOnlyTooltip}
         onCommit={(next) => commitManualOffset("x", next)}
         suffix={<KeyframeGutter property="x" displayValue={displayX} {...gutterProps} />}
       />
@@ -145,6 +150,7 @@ export function LayoutGeometryRows({
         value={formatPxMetricValue(displayY)}
         tier={displayY === 0 ? "default" : "explicitCustom"}
         disabled={manualOffsetEditingDisabled}
+        tooltip={readOnlyTooltip}
         onCommit={(next) => commitManualOffset("y", next)}
         suffix={<KeyframeGutter property="y" displayValue={displayY} {...gutterProps} />}
       />
@@ -153,6 +159,7 @@ export function LayoutGeometryRows({
         value={formatPxMetricValue(displayW)}
         tier="default"
         disabled={manualSizeEditingDisabled}
+        tooltip={readOnlyTooltip}
         onCommit={(next) => commitManualSize("width", next)}
         suffix={<KeyframeGutter property="width" displayValue={displayW} {...gutterProps} />}
       />
@@ -161,6 +168,7 @@ export function LayoutGeometryRows({
         value={formatPxMetricValue(displayH)}
         tier="default"
         disabled={manualSizeEditingDisabled}
+        tooltip={readOnlyTooltip}
         onCommit={(next) => commitManualSize("height", next)}
         suffix={<KeyframeGutter property="height" displayValue={displayH} {...gutterProps} />}
       />
@@ -169,6 +177,7 @@ export function LayoutGeometryRows({
         value={`${displayR}°`}
         tier="default"
         disabled={manualRotationEditingDisabled}
+        tooltip={readOnlyTooltip}
         onCommit={(next) => commitManualRotation(next.replace("°", ""))}
         suffix={<KeyframeGutter property="rotation" displayValue={displayR} {...gutterProps} />}
       />

package/src/components/editor/propertyPanelFlatMediaSection.test.tsx

@@ -250,8 +250,8 @@ describe("FlatMediaSection — volume/rate/media-start", () => {
       rateTrack.dispatchEvent(new MouseEvent("pointerdown", { bubbles: true, clientX: 100 }));
       rateTrack.dispatchEvent(new MouseEvent("pointerup", { bubbles: true, clientX: 100 }));
     });
-    // min=25, max=300, ratio=1.0 -> raw=300 -> commit(300) -> 300/100=3 -> "3"
-    expect(onSetAttribute).toHaveBeenCalledWith("playback-rate", "3");
+    // the speed slider is log-scaled 0.1x..10x, so the far end of the track is 10x
+    expect(onSetAttribute).toHaveBeenCalledWith("playback-rate", "10");
     act(() => root.unmount());
   });
 

package/src/components/editor/propertyPanelFlatMediaSection.tsx

@@ -13,6 +13,10 @@ import {
 import { FlatSelectRow, FlatSlider } from "./propertyPanelFlatPrimitives";
 import { FlatToggle } from "./propertyPanelFlatToggle";
 import { AutomationToggle } from "./propertyPanelFxControls";
+import { RATE_RANGE } from "@hyperframes/core/audio-automation";
+import { type SpeedPresetId } from "@hyperframes/core/speed-ramp";
+import { SPEED_PRESET_OPTIONS, type RateBinding } from "./useVolumeAutomation";
+import { fromUnit, toUnit } from "../../player/components/automationLaneGeometry";
 import {
   AUDIO_GAIN_FADER_MAX,
   AUDIO_GAIN_FADER_MIN,
@@ -36,6 +40,7 @@ export function FlatMediaSection({
   onRemoveVolumeAutomation,
   onCommitVolumeAt,
   automatedVolumeValue,
+  rate,
 }: {
   projectDir: string | null;
   element: DomEditSelection;
@@ -49,6 +54,8 @@ export function FlatMediaSection({
   onRemoveVolumeAutomation?: () => void;
   onCommitVolumeAt?: (v: number) => void;
   automatedVolumeValue?: number;
+  /** Speed lane binding and presets; absent outside the Studio panel. */
+  rate?: RateBinding;
   onRemoveBackground?: (
     inputPath: string,
     options: {
@@ -77,7 +84,9 @@ export function FlatMediaSection({
     Number.parseFloat(
       element.dataAttributes["media-start"] ?? element.dataAttributes["playback-start"] ?? "0",
     ) || 0;
-  const playbackRate = Number.parseFloat(element.dataAttributes["playback-rate"] ?? "1") || 1;
+  const constantRate = Number.parseFloat(element.dataAttributes["playback-rate"] ?? "1") || 1;
+  const playbackRate =
+    rate?.automated && rate.automatedValue !== undefined ? rate.automatedValue : constantRate;
   const sourceDuration =
     Number.parseFloat(element.dataAttributes["source-duration"] ?? "") ||
     (el as HTMLMediaElement).duration ||
@@ -259,17 +268,42 @@ export function FlatMediaSection({
               }
             />
           </div>
-          <FlatSlider
-            label="Rate"
-            value={playbackRate * 100}
-            min={25}
-            max={300}
-            tier={playbackRate === 1 ? "default" : "explicitCustom"}
-            displayValue={`${formatNumericValue(playbackRate)}x`}
-            onCommit={(next) =>
-              void onSetAttribute("playback-rate", formatNumericValue(next / 100))
-            }
-          />
+          <div className="flex items-center gap-1">
+            <div className="min-w-0 flex-1">
+              <FlatSlider
+                label="Speed"
+                value={Math.round(toUnit(RATE_RANGE, playbackRate) * 1000)}
+                min={0}
+                max={1000}
+                tier={playbackRate === 1 ? "default" : "explicitCustom"}
+                displayValue={`${formatNumericValue(playbackRate)}x`}
+                onCommit={(next) => {
+                  const speed = fromUnit(RATE_RANGE, next / 1000);
+                  if (rate?.automated) {
+                    rate.onCommitAt(speed);
+                  } else {
+                    void onSetAttribute("playback-rate", formatNumericValue(speed));
+                  }
+                }}
+              />
+            </div>
+            <AutomationToggle
+              paramKey="rate"
+              label="Speed"
+              automated={Boolean(rate?.automated)}
+              onAutomate={rate ? () => rate.onAutomate() : undefined}
+              onRemoveAutomation={rate ? () => rate.onRemoveAutomation() : undefined}
+            />
+          </div>
+          {rate?.canApplyPreset && (
+            <FlatSelectRow
+              label="Speed preset"
+              value=""
+              options={[{ value: "", label: "Choose…" }, ...SPEED_PRESET_OPTIONS]}
+              tier="default"
+              onChange={(id) => id && rate.onApplyPreset(id as SpeedPresetId)}
+            />
+          )}
           <FlatSlider
             label="Media start"
             value={Math.round(mediaStart * 100)}

package/src/components/editor/propertyPanelFlatPrimitives.tsx

@@ -19,6 +19,7 @@ export function FlatRow({
   value,
   tier,
   disabled,
+  tooltip,
   liveCommit,
   suffix,
   dropdown,
@@ -30,6 +31,8 @@ export function FlatRow({
   value: string;
   tier: PropertyValueTier;
   disabled?: boolean;
+  /** Shown as a title attribute, e.g. why the row is disabled. */
+  tooltip?: string;
   liveCommit?: boolean;
   suffix?: ReactNode;
   /** Renders a trailing 10px caret-down, for select-backed rows. */
@@ -40,7 +43,7 @@ export function FlatRow({
 }) {
   const track = useTrackDesignInput();
   return (
-    <div className="group flex min-h-[30px] items-center justify-between gap-3">
+    <div className="group flex min-h-[30px] items-center justify-between gap-3" title={tooltip}>
       <span className={`text-[11px] ${VALUE_TIER_LABEL_CLASS[tier]}`}>{label}</span>
       <span className="flex min-w-0 shrink-0 items-center gap-1.5">
         <span

package/src/components/editor/propertyPanelInputCoverage.test.tsx

@@ -459,12 +459,7 @@ function representativeElement() {
 describe("classic PropertyPanel input coverage", () => {
   it("emits only named, known-section events across body inputs and header/footer chrome", async () => {
     vi.resetModules();
-    vi.doMock("./manualEditingAvailability", async () => {
-      const actual = await vi.importActual<typeof import("./manualEditingAvailability")>(
-        "./manualEditingAvailability",
-      );
-      return { ...actual, STUDIO_FLAT_INSPECTOR_ENABLED: false };
-    });
+    vi.doMock("./manualEditingAvailability", () => ({ STUDIO_FLAT_INSPECTOR_ENABLED: false }));
     const { PropertyPanel } = await import("./PropertyPanel");
     const host = render(
       <PropertyPanel
@@ -524,18 +519,13 @@ describe("classic PropertyPanel input coverage", () => {
     expect(sections.has("header")).toBe(true);
     expect(sections.has("footer")).toBe(true);
     expect(sections.size).toBeGreaterThan(2);
-  });
+  }, 15000);
 });
 
 describe("flat PropertyPanel input coverage", () => {
   it("emits only named flat events from known sections for every visible layout input", async () => {
     vi.resetModules();
-    vi.doMock("./manualEditingAvailability", async () => {
-      const actual = await vi.importActual<typeof import("./manualEditingAvailability")>(
-        "./manualEditingAvailability",
-      );
-      return { ...actual, STUDIO_FLAT_INSPECTOR_ENABLED: true };
-    });
+    vi.doMock("./manualEditingAvailability", () => ({ STUDIO_FLAT_INSPECTOR_ENABLED: true }));
     const { PropertyPanel } = await import("./PropertyPanel");
     const host = render(
       <PropertyPanel

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