@hyperframes/studio 0.8.55 → 0.8.57

package/src/components/ProjectUnreachableBanner.test.tsx

@@ -0,0 +1,113 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ProjectUnreachableBanner } from "./ProjectUnreachableBanner";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | null = null;
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  root = null;
+  document.body.replaceChildren();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+function stubProjects(projects: unknown): void {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => new Response(JSON.stringify({ projects }), { status: 200 })),
+  );
+}
+
+async function renderBanner(projectId: string): Promise<string> {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  await act(async () => {
+    root?.render(<ProjectUnreachableBanner projectId={projectId} />);
+  });
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+  return host.textContent ?? "";
+}
+
+describe("ProjectUnreachableBanner", () => {
+  // The production case: the CLI host serves exactly one project, and it is not
+  // this tab's. Naming both sides is the whole point — the user needs to know
+  // their project still exists and which one this Studio actually opened.
+  it("names both projects when this Studio serves a different one", async () => {
+    stubProjects([{ id: "out-video1", title: "out-video1" }]);
+    const text = await renderBanner("out-fb1");
+
+    expect(text).toContain("out-video1");
+    expect(text).toContain("out-fb1");
+    expect(text).toContain("This Studio is serving");
+    expect(text).not.toContain("renamed");
+  });
+
+  // With several projects a 404 cannot be told apart from a rename or a
+  // deletion, so the banner must not claim a cause. "Could be gone" is the
+  // honest ceiling, and it is a weaker claim than "is gone".
+  it("does not claim a cause when several projects are served", async () => {
+    stubProjects([
+      { id: "a", title: "a" },
+      { id: "b", title: "b" },
+    ]);
+    const text = await renderBanner("out-fb1");
+
+    expect(text).toContain("renamed, moved, or deleted");
+    expect(text).not.toContain("This Studio is serving");
+  });
+
+  // A server that answers with this tab's own project while the read 404s is
+  // not the stale-tab case, so the single-project wording would be false.
+  it("falls back to the general wording when the served project is this one", async () => {
+    stubProjects([{ id: "out-fb1", title: "out-fb1" }]);
+    const text = await renderBanner("out-fb1");
+
+    expect(text).toContain("renamed, moved, or deleted");
+    expect(text).not.toContain("This Studio is serving");
+  });
+
+  it("says nothing it cannot back up when the project list cannot be read", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("boom", { status: 500 })),
+    );
+    const text = await renderBanner("out-fb1");
+
+    expect(text).toContain("renamed, moved, or deleted");
+    expect(text).not.toContain("This Studio is serving");
+  });
+
+  it("renders nothing until the project list resolves", async () => {
+    let resolveList: ((value: Response) => void) | undefined;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        () =>
+          new Promise<Response>((resolve) => {
+            resolveList = resolve;
+          }),
+      ),
+    );
+    const host = document.createElement("div");
+    document.body.append(host);
+    root = createRoot(host);
+    await act(async () => {
+      root?.render(<ProjectUnreachableBanner projectId="out-fb1" />);
+    });
+    expect(host.textContent).toBe("");
+
+    await act(async () => {
+      resolveList?.(new Response(JSON.stringify({ projects: [{ id: "other" }] }), { status: 200 }));
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    expect(host.textContent).toContain("This Studio is serving");
+  });
+});

package/src/components/ProjectUnreachableBanner.tsx

@@ -0,0 +1,89 @@
+import { useEffect, useState } from "react";
+
+interface ServedProject {
+  id: string;
+  title?: string;
+}
+
+interface ProjectUnreachableBannerProps {
+  /** The project this tab was opened for and the server cannot resolve. */
+  projectId: string;
+}
+
+/**
+ * Shown when the running Studio cannot resolve this tab's project id.
+ *
+ * Why this exists: a tab whose project the server does not serve fails every
+ * read with a 404, so every edit silently takes the server path and nothing
+ * lands. The user sees a normal-looking editor that does not save. In the
+ * CLI-embedded host — the only host that reports telemetry, since
+ * `telemetry/policy.ts` suppresses Vite dev — the cause is almost always that
+ * this Studio is serving a *different* project: `hyperframes preview` reuses
+ * port 3002, so starting it on another folder takes the port from under an
+ * open tab, and the project it was pointed at is untouched on disk.
+ *
+ * The wording is deliberately narrower than "this project is gone". We can see
+ * which project this server serves; we cannot see why it does not serve this
+ * one, and nothing here is lost. See
+ * `docs/hyperframes/plans/sdk/2026-09-20-stale-project-id-remaining-doors-plan.md` §C.
+ */
+export function ProjectUnreachableBanner({ projectId }: ProjectUnreachableBannerProps) {
+  const [served, setServed] = useState<ServedProject[] | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    // A list we could not read is not evidence of anything, so a failed fetch
+    // leaves `served` empty and the banner falls back to the vague wording
+    // rather than claiming this Studio serves nothing.
+    fetch("/api/projects")
+      .then((res) => (res.ok ? res.json() : { projects: [] }))
+      .then((data: { projects?: ServedProject[] }) => {
+        if (!cancelled) setServed(data.projects ?? []);
+      })
+      .catch(() => {
+        if (!cancelled) setServed([]);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [projectId]);
+
+  // Withheld until the list arrives: which wording applies is a claim about
+  // what this server serves, and guessing it would flash the wrong one.
+  if (served === null) return null;
+
+  // Exactly one project served, and it is not this tab's. Under the CLI host
+  // that is the whole truth, and it names both sides. With several projects we
+  // cannot tell a rename from a deletion, so we do not pretend to.
+  const soleProject = served.length === 1 && served[0].id !== projectId ? served[0] : null;
+  const servedLabel = soleProject?.title ?? soleProject?.id;
+
+  return (
+    <div
+      role="alert"
+      className="hf-backdrop-in absolute left-1/2 top-14 z-92 flex max-w-[calc(100vw-32px)] -translate-x-1/2 items-center gap-3 rounded-md border border-amber-500/30 bg-amber-950/85 px-4 py-2 text-[12px] font-medium text-amber-100 shadow-lg shadow-black/30"
+    >
+      {soleProject ? (
+        <>
+          <span>
+            This Studio is serving <strong>{servedLabel}</strong>. This tab was opened for{" "}
+            <strong>{projectId}</strong>.
+          </span>
+          {/* Reloading re-runs the mount-time hash check, which rewrites the hash
+              to the project this server actually serves. That is the same
+              fallback a fresh load performs, so the button promises nothing
+              beyond what a reload already does. */}
+          <button
+            type="button"
+            onClick={() => window.location.reload()}
+            className="shrink-0 rounded-sm border border-amber-300/20 px-2 py-1 text-[11px] text-amber-100 transition-colors hover:bg-amber-400/10 active:scale-[0.98]"
+          >
+            Open {servedLabel}
+          </button>
+        </>
+      ) : (
+        <span>Couldn&apos;t open this project — it may have been renamed, moved, or deleted.</span>
+      )}
+    </div>
+  );
+}

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,24 +16,23 @@ 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";
-import { GridOverlay } from "./GridOverlay";
 import type { GestureRecordingState } from "./GestureRecordControl";
 import { DomEditGroupChrome, DomEditSelectionChrome } from "./DomEditSelectionChrome";
 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 {
@@ -84,8 +83,6 @@ interface DomEditOverlayProps {
   ) => Promise<void> | void;
   onRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void> | void;
   onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;
-  gridVisible?: boolean;
-  gridSpacing?: number;
   recordingState?: GestureRecordingState;
   onToggleRecording?: () => void;
   onMarqueeSelect?: (selections: DomEditSelection[], additive: boolean) => void;
@@ -125,8 +122,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onCanvasPointerLeave,
   onSelectionChange,
   onBlockedMove,
-  gridVisible = false,
-  gridSpacing = 50,
   onManualDragStart,
   onPathOffsetCommit,
   onGroupPathOffsetCommit,
@@ -137,6 +132,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 +216,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 +250,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 +532,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           selection={contextMenu.sel}
           onClose={closeContextMenu}
           onDelete={
-            onDeleteSelection
+            onDeleteSelection && !readOnly
               ? (sel) => {
                   closeContextMenu();
                   onDeleteSelection(sel);
@@ -566,7 +540,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
               : undefined
           }
           onApplyZIndex={
-            onApplyZIndex
+            onApplyZIndex && !readOnly
               ? (patches, action, crossed) => {
                   onApplyZIndex(contextMenu.sel, patches, action, crossed);
                 }
@@ -576,16 +550,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
         />
       )}
       <ZOrderCrossedFlash rect={zOrderFlashRect} />
-      <GridOverlay
-        visible={gridVisible}
-        spacing={gridSpacing}
-        scaleX={compRect.scaleX}
-        scaleY={compRect.scaleY}
-        compositionLeft={compRect.left}
-        compositionTop={compRect.top}
-        compositionWidth={compRect.width}
-        compositionHeight={compRect.height}
-      />
       <SnapGuideOverlay
         snapGuidesRef={snapGuidesRef}
         compositionLeft={compRect.left}

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

@@ -4,6 +4,7 @@ import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { expect, it, vi } from "vitest";
 import type { DomEditSelection } from "./domEditing";
+import "./domEditOverlayTestMocks";
 import { DomEditOverlay } from "./DomEditOverlay";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -33,21 +34,6 @@ vi.mock("./useDomEditOverlayRects", () => ({
   }),
 }));
 
-vi.mock("./useDomEditCompositionRect", () => ({
-  useDomEditCompositionRect: () => ({
-    left: 0,
-    top: 0,
-    width: 800,
-    height: 450,
-    scaleX: 1,
-    scaleY: 1,
-  }),
-}));
-
-vi.mock("./offCanvasIndicatorRefresh", () => ({
-  startOffCanvasIndicatorRefresh: () => () => undefined,
-}));
-
 function renderHover(angle: number): string {
   hoverState.angle = angle;
   const host = document.createElement("div");

package/src/components/editor/DomEditSelectionChrome.tsx

@@ -6,6 +6,7 @@ import type { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGes
 import { DomEditCropHandles } from "./DomEditCropHandles";
 import { DomEditRotateHandle } from "./DomEditRotateHandle";
 import { resolveRotatedResizeCursor } from "./domEditResizeLocal";
+import { usePreviewReadOnly } from "./previewReadOnlyContext";
 
 // Corner resize handles, Canva-style: one per corner, diagonal cursors.
 // Corners scale about the element center; the translate keeps the center
@@ -75,6 +76,7 @@ export function DomEditGroupChrome({
   onBoxMouseDown,
   onBoxClick,
 }: DomEditGroupChromeProps) {
+  const canManipulate = allowCanvasMovement && !usePreviewReadOnly();
   return (
     <>
       {groupOverlayItems.map((item) => (
@@ -98,10 +100,10 @@ export function DomEditGroupChrome({
           top: groupBounds.top,
           width: groupBounds.width,
           height: groupBounds.height,
-          cursor: allowCanvasMovement && groupCanMove ? "move" : "default",
+          cursor: canManipulate && groupCanMove ? "move" : "default",
         }}
         onPointerDown={(e) => {
-          if (!allowCanvasMovement || !groupCanMove || e.shiftKey) return;
+          if (!canManipulate || !groupCanMove || e.shiftKey) return;
           gestures.startGroupDrag(e);
         }}
         onMouseDown={onBoxMouseDown}
@@ -164,6 +166,8 @@ export function DomEditSelectionChrome({
   // into: left interactive, it swallows every press, so the caret can never be
   // moved and characters can never be selected by dragging.
   const editing = inlineText?.editing ?? false;
+  const readOnly = usePreviewReadOnly();
+  const canManipulate = allowCanvasMovement && !readOnly;
 
   return (
     <>
@@ -174,7 +178,7 @@ export function DomEditSelectionChrome({
           transform: overlayRect.angle ? `rotate(${overlayRect.angle}deg)` : undefined,
         }}
       >
-        {allowCanvasMovement && !editing && selection.capabilities.canApplyManualRotation && (
+        {canManipulate && !editing && selection.capabilities.canApplyManualRotation && (
           <DomEditRotateHandle
             overlayRect={overlayRect}
             cropOutlineInsetPx={cropOutlineInsetPx}
@@ -196,9 +200,7 @@ export function DomEditSelectionChrome({
             height: overlayRect.height,
             clipPath: boxClipPath,
             cursor:
-              allowCanvasMovement && selection.capabilities.canApplyManualOffset
-                ? "move"
-                : "default",
+              canManipulate && selection.capabilities.canApplyManualOffset ? "move" : "default",
           }}
           onPointerDown={(e) => {
             // A second press opens the element's text for editing, and must be
@@ -211,7 +213,7 @@ export function DomEditSelectionChrome({
               e.stopPropagation();
               return;
             }
-            if (!allowCanvasMovement || e.shiftKey) return;
+            if (!canManipulate || e.shiftKey) return;
             if (selection.capabilities.canApplyManualOffset) {
               gestures.startGesture("drag", e);
               return;
@@ -245,7 +247,7 @@ export function DomEditSelectionChrome({
           children, so they paint strictly above the box border. Each handle
           is positioned relative to the overlay container using the
           overlayRect origin, matching the old child-relative offsets. */}
-        {allowCanvasMovement &&
+        {canManipulate &&
           !editing &&
           selection.capabilities.canApplyManualSize &&
           RESIZE_HANDLE_DEFS.map((def) =>
@@ -271,7 +273,7 @@ export function DomEditSelectionChrome({
       </div>
       {/* Crop owns its element-local oriented frame. Keep it outside the chrome's
           rotated plane or a rotated selection applies the angle twice. */}
-      {selection.capabilities.canCrop && !editing && groupSelectionCount <= 1 && (
+      {selection.capabilities.canCrop && !editing && !readOnly && groupSelectionCount <= 1 && (
         <DomEditCropHandles
           selection={selection}
           overlayRect={overlayRect}

package/src/components/editor/GridOverlay.tsx

@@ -1,28 +1,17 @@
-// fallow-ignore-file unused-file
 import { memo } from "react";
+import { usePreviewOverlayContext } from "./PreviewOverlayProvider";
 
-interface GridOverlayProps {
-  visible: boolean;
-  spacing: number;
-  scaleX: number;
-  scaleY: number;
-  compositionLeft: number;
-  compositionTop: number;
-  compositionWidth: number;
-  compositionHeight: number;
-}
-
-// fallow-ignore-next-line complexity
-export const GridOverlay = memo(function GridOverlay({
-  visible,
-  spacing,
-  scaleX,
-  scaleY,
-  compositionLeft,
-  compositionTop,
-  compositionWidth,
-  compositionHeight,
-}: GridOverlayProps) {
+export const GridOverlay = memo(function GridOverlay() {
+  const { state } = usePreviewOverlayContext();
+  const { gridVisible: visible, gridSpacing: spacing } = state.snapPrefs;
+  const {
+    scaleX,
+    scaleY,
+    left: compositionLeft,
+    top: compositionTop,
+    width: compositionWidth,
+    height: compositionHeight,
+  } = state.compositionRect;
   if (!visible || spacing <= 0) return null;
 
   const overlaySpacingX = spacing * scaleX;

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

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import { MotionPathOverlay } from "./MotionPathOverlay";
+import { usePlayerStore } from "../../player/store/playerStore";
+import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
+import type { DomEditSelection } from "./domEditing";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+vi.mock("../../contexts/DomEditContext", () => ({
+  useDomEditContext: () => ({ selectedGsapAnimations: [] }),
+}));
+vi.mock("./motionPathSelection", () => ({
+  selectorFor: () => "#box",
+  editableAnimationId: () => null,
+}));
+vi.mock("./useMotionPathData", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./useMotionPathData")>()),
+  useMotionPathData: () => ({
+    rect: null,
+    geometry: null,
+    geometryResolved: true,
+    visibleInPreview: true,
+    home: null,
+    pScale: 1,
+  }),
+}));
+
+it("re-evaluates set-destination availability when a reload swaps the live iframe", () => {
+  const host = document.createElement("div");
+  const before = document.createElement("iframe");
+  const after = document.createElement("iframe");
+  document.body.append(host, before, after);
+  Reflect.set(after.contentWindow as object, "MotionPathPlugin", {});
+  const ref = { current: before };
+  const root = createRoot(host);
+  const selection = { element: document.createElement("div") } as unknown as DomEditSelection;
+  try {
+    act(() => usePreviewIframeStore.getState().setIframe(before));
+    act(() =>
+      root.render(
+        <MotionPathOverlay
+          iframeRef={ref}
+          selection={selection}
+          compositionSize={{ width: 1920, height: 1080 }}
+          isPlaying={false}
+        />,
+      ),
+    );
+    expect(usePlayerStore.getState().motionPathCreateAvailable).toBe(false);
+
+    act(() => {
+      ref.current = after;
+      usePreviewIframeStore.getState().setIframe(after);
+    });
+    expect(usePlayerStore.getState().motionPathCreateAvailable).toBe(true);
+  } finally {
+    act(() => root.unmount());
+    usePreviewIframeStore.setState({ iframe: null });
+    host.remove();
+    before.remove();
+    after.remove();
+  }
+});

package/src/components/editor/MotionPathOverlay.tsx

@@ -3,6 +3,7 @@ import { memo, useEffect, useRef, useState, type RefObject } from "react";
 import type { DomEditSelection } from "./domEditing";
 import { useDomEditContext } from "../../contexts/DomEditContext";
 import { usePlayerStore } from "../../player/store/playerStore";
+import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
 import { parkPlayheadOnKeyframe } from "../../hooks/gsapDragCommit";
 import { commitWholePropertyOffset } from "../../hooks/gsapWholePropertyOffsetCommit";
 import { nearestPointOnPath, type MotionNodeRef } from "./motionPathGeometry";
@@ -141,7 +142,8 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
   // No one-element selector means the path could only be authored onto the
   // element's class siblings, so the toolbar toggle stays hidden instead of
   // arming a press that the effect below would silently drop.
-  const canCreate = createMode && !!createSelector && hasMotionPathPlugin(iframeRef.current);
+  const livePreviewIframe = useLivePreviewIframe();
+  const canCreate = createMode && !!createSelector && hasMotionPathPlugin(livePreviewIframe);
 
   // Publish whether the selected element can take a path so the preview toolbar
   // shows its "set destination" toggle. Drops to false when this overlay unmounts

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

@@ -4,6 +4,7 @@ import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { PreviewGuides } from "./PreviewGuides";
+import { PreviewOverlayProvider } from "./PreviewOverlayProvider";
 import { usePreviewGuidesStore } from "./previewGuidesStore";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -26,7 +27,11 @@ function render(rulerVisible: boolean, safeMarginsVisible: boolean) {
   const host = document.createElement("div");
   document.body.append(host);
   act(() => {
-    createRoot(host).render(<PreviewGuides iframeRef={{ current: null }} />);
+    createRoot(host).render(
+      <PreviewOverlayProvider>
+        <PreviewGuides />
+      </PreviewOverlayProvider>,
+    );
   });
   return host;
 }

package/src/components/editor/PreviewGuides.tsx

@@ -1,30 +1,28 @@
 import { memo, useRef, type RefObject } from "react";
 import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
-import { RULER_GUTTER_PX, usePreviewGuidesStore } from "./previewGuidesStore";
+import { RULER_GUTTER_PX } from "./previewGuidesStore";
 import { SAFE_BOX_PERCENTS, safeBoxInsetPercent } from "../../utils/previewSafeMargins";
-
-interface PreviewGuidesProps {
-  iframeRef: RefObject<HTMLIFrameElement | null>;
-}
+import { usePreviewOverlayContext } from "./PreviewOverlayProvider";
 
 const TICKS = Array.from({ length: 11 }, (_, i) => i * 10);
 const INK = "color-mix(in srgb, white 70%, transparent)";
 
 /** Ruler and safe-margin boxes drawn over the preview pane, never inside the composition. */
-export const PreviewGuides = memo(function PreviewGuides({ iframeRef }: PreviewGuidesProps) {
-  const rulerVisible = usePreviewGuidesStore((s) => s.rulerVisible);
-  const safeMarginsVisible = usePreviewGuidesStore((s) => s.safeMarginsVisible);
+export const PreviewGuides = memo(function PreviewGuides() {
+  const { state } = usePreviewOverlayContext();
+  const { rulerVisible, safeMarginsVisible } = state;
   if (!rulerVisible && !safeMarginsVisible) return null;
   return (
     <ActiveGuides
-      iframeRef={iframeRef}
+      iframeRef={state.iframeRef}
       rulerVisible={rulerVisible}
       safeMarginsVisible={safeMarginsVisible}
     />
   );
 });
 
-interface ActiveGuidesProps extends PreviewGuidesProps {
+interface ActiveGuidesProps {
+  iframeRef: RefObject<HTMLIFrameElement | null>;
   rulerVisible: boolean;
   safeMarginsVisible: boolean;
 }