@hyperframes/studio 0.7.39 → 0.7.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.39",
+  "version": "0.7.40",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.39",
-    "@hyperframes/parsers": "0.7.39",
-    "@hyperframes/sdk": "0.7.39",
-    "@hyperframes/player": "0.7.39",
-    "@hyperframes/studio-server": "0.7.39"
+    "@hyperframes/parsers": "0.7.40",
+    "@hyperframes/studio-server": "0.7.40",
+    "@hyperframes/sdk": "0.7.40",
+    "@hyperframes/core": "0.7.40",
+    "@hyperframes/player": "0.7.40"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.39"
+    "@hyperframes/producer": "0.7.40"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -360,7 +360,6 @@ export function StudioApp() {
     resetErrors: resetConsoleErrors,
   } = useConsoleErrorCapture(previewIframe);
   const dragOverlay = useDragOverlay(fileManager.handleImportFiles);
-  // Gesture recording
   const handleToggleRecordingRef = useRef<() => void>(() => {});
   const domEditSessionRef = useRef(domEditSession);
   domEditSessionRef.current = domEditSession;
@@ -531,6 +530,7 @@ export function StudioApp() {
                       handleTimelineFileDrop={timelineEditing.handleTimelineFileDrop}
                       handleTimelineElementMove={timelineEditing.handleTimelineElementMove}
                       handleTimelineElementResize={timelineEditing.handleTimelineElementResize}
+                      handleToggleTrackHidden={timelineEditing.handleToggleTrackHidden}
                       handleBlockedTimelineEdit={timelineEditing.handleBlockedTimelineEdit}
                       handleTimelineElementSplit={timelineEditing.handleTimelineElementSplit}
                       handleRazorSplit={timelineEditing.handleRazorSplit}
@@ -572,6 +572,7 @@ export function StudioApp() {
                         domEditSaveTimestampRef={domEditSaveTimestampRef}
                         recordEdit={editHistory.recordEdit}
                         {...cropModeProps}
+                        onToggleElementHidden={timelineEditing.handleToggleElementHidden}
                       />
                     )}
                   </div>

package/src/components/StudioPreviewArea.tsx

@@ -58,6 +58,7 @@ export interface StudioPreviewAreaProps {
     element: TimelineElement,
     updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
   ) => Promise<void> | void;
+  handleToggleTrackHidden: (track: number, hidden: boolean) => Promise<void> | void;
   handleBlockedTimelineEdit: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   handleRazorSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
@@ -85,6 +86,7 @@ export function StudioPreviewArea({
   handleTimelineFileDrop,
   handleTimelineElementMove,
   handleTimelineElementResize,
+  handleToggleTrackHidden,
   handleBlockedTimelineEdit,
   handleTimelineElementSplit,
   handleRazorSplit,
@@ -165,6 +167,7 @@ export function StudioPreviewArea({
   // diamond reports a clip-% but the script ops key on the tween-%. Prefers the
   // anim in the keyframe's property group, falling back to the first keyframed one.
   const resolveKeyframeTarget = useCallback(
+    // fallow-ignore-next-line complexity
     (pct: number): { animId: string; tweenPct: number } | null => {
       const cached = usePlayerStore.getState().keyframeCache.get(domEditSelection?.id ?? "");
       const kf = cached?.keyframes.find((k) => Math.abs(k.percentage - pct) < 0.2);
@@ -182,6 +185,7 @@ export function StudioPreviewArea({
     () => ({
       onMoveElement: handleTimelineElementMove,
       onResizeElement: handleTimelineElementResize,
+      onToggleTrackHidden: handleToggleTrackHidden,
       onBlockedEditAttempt: handleBlockedTimelineEdit,
       onSplitElement: handleTimelineElementSplit,
       onRazorSplit: handleRazorSplit,
@@ -210,6 +214,7 @@ export function StudioPreviewArea({
       // drop past the boundary (last keyframe past the end, first before the start)
       // resizes the tween — position/duration grow so the dragged keyframe lands at
       // the drop while every other keyframe keeps its absolute time (value+ease too).
+      // fallow-ignore-next-line complexity
       onMoveKeyframe: (_elId: string, fromClipPct: number, toClipPct: number) => {
         const target = resolveKeyframeTarget(fromClipPct);
         const sel = domEditSelection;
@@ -280,6 +285,7 @@ export function StudioPreviewArea({
     [
       handleTimelineElementMove,
       handleTimelineElementResize,
+      handleToggleTrackHidden,
       handleBlockedTimelineEdit,
       handleTimelineElementSplit,
       handleRazorSplit,

package/src/components/StudioRightPanel.tsx

@@ -62,6 +62,7 @@ export interface StudioRightPanelProps {
     kind: EditHistoryKind;
     files: Record<string, { before: string; after: string }>;
   }) => Promise<void>;
+  onToggleElementHidden?: (elementKey: string, hidden: boolean) => Promise<void> | void;
 }
 
 // fallow-ignore-next-line complexity
@@ -78,6 +79,7 @@ export function StudioRightPanel({
   reloadPreview,
   domEditSaveTimestampRef,
   recordEdit,
+  onToggleElementHidden,
 }: StudioRightPanelProps) {
   const {
     rightWidth,
@@ -350,6 +352,7 @@ export function StudioRightPanel({
       multiSelectCount={domEditGroupSelections.length}
       copiedAgentPrompt={copiedAgentPrompt}
       onClearSelection={clearDomSelection}
+      onToggleElementHidden={onToggleElementHidden}
       onUngroup={handleUngroupSelection}
       onSetStyle={handleDomStyleCommit}
       onSetAttribute={handleDomAttributeCommit}

package/src/components/editor/DomEditOverlay.tsx

@@ -3,9 +3,7 @@ import { type DomEditSelection } from "./domEditing";
 import type { PreviewMouseDownOptions } from "../../hooks/usePreviewInteraction";
 import { useMarqueeGestures } from "./marqueeCommit";
 import { MarqueeOverlay } from "./MarqueeOverlay";
-import { groupAwareOverlayRect, resolveDomEditGroupOverlayRect } from "./domEditOverlayGeometry";
-import { collectDomEditLayerItems } from "./domEditingLayers";
-import { isElementComputedVisible } from "./domEditingElement";
+import { resolveDomEditGroupOverlayRect } from "./domEditOverlayGeometry";
 import {
   type BlockedMoveState,
   type DomEditGroupPathOffsetCommit,
@@ -26,6 +24,8 @@ import { hugRectForElement } from "./domEditOverlayCrop";
 import { useCropOverlay } from "../../hooks/useCropMode";
 import { readDomEditSelectionShapeStyles, resolveBoxChromeClass } from "./domEditOverlayShape";
 import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
+import { useMountEffect } from "../../hooks/useMountEffect";
+import { startOffCanvasIndicatorRefresh } from "./offCanvasIndicatorRefresh";
 
 // Re-exports for external consumers — preserving existing import paths.
 export {
@@ -173,6 +173,8 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   });
 
   const compRect = useDomEditCompositionRect({ iframeRef, overlayRef });
+  const compRectRef = useRef(compRect);
+  compRectRef.current = compRect;
 
   const { hasCropInsets, cropOutlineInsetPx } = useCropOverlay({
     selection,
@@ -189,51 +191,35 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   // outside the composition bounds so users can find them.
   const offCanvasElementsRef = useRef<Map<string, HTMLElement>>(new Map());
   const [offCanvasRects, setOffCanvasRects] = useState<OffCanvasRect[]>([]);
-  // fallow-ignore-next-line complexity
+  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(() => {
-    const iframe = iframeRef.current;
-    const overlay = overlayRef.current;
-    if (!iframe || !overlay || compRect.width <= 0) {
-      setOffCanvasRects([]);
-      return;
-    }
-    const doc = iframe.contentDocument;
-    if (!doc) return;
-    const root = doc.querySelector<HTMLElement>("[data-composition-id]") ?? doc.body;
-    const acp = activeCompositionPath ?? "index.html";
-    const items = collectDomEditLayerItems(root, {
-      activeCompositionPath: acp,
-      isMasterView: !acp || acp === "index.html",
-    });
-    const rects: typeof offCanvasRects = [];
-    const elMap = new Map<string, HTMLElement>();
-    for (const item of items) {
-      if (!isElementComputedVisible(item.element)) continue;
-      // Groups use their members' union (where they actually render), so a group
-      // whose members sit inside the canvas isn't flagged off-canvas by a stale
-      // wrapper box. Crop-hug the result so an inset crop that keeps the visible
-      // part on-canvas doesn't flag the element either.
-      const base = groupAwareOverlayRect(overlay, iframe, item.element);
-      const r = base ? { ...base, ...hugRectForElement(base, item.element) } : null;
-      if (!r) continue;
-      // Any edge crossing the composition border → gray-zone indicator (the
-      // in-canvas portion is clipped away below, so only the sliver shows).
-      const extendsOutsideComp =
-        r.left < compRect.left ||
-        r.left + r.width > compRect.left + compRect.width ||
-        r.top < compRect.top ||
-        r.top + r.height > compRect.top + compRect.height;
-      if (extendsOutsideComp) {
-        rects.push({ key: item.key, left: r.left, top: r.top, width: r.width, height: r.height });
-        elMap.set(item.key, item.element);
-      }
-    }
-    offCanvasElementsRef.current = elMap;
-    setOffCanvasRects(rects);
-    // Positions depend on layout, not selection — the selected-element
-    // suppression is a render-time filter, so selection/groupSelections stay
-    // out of the deps to avoid re-walking geometry on each selection change.
-  }, [iframeRef, compRect, activeCompositionPath]);
+    offCanvasDirtyRef.current = true;
+  }, [activeCompositionPath]);
 
   const gestures = createDomEditOverlayGestureHandlers({
     overlayRef,

package/src/components/editor/PropertyPanel.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../../player";
 import {
   buildInsetClipPathSides,
   buildStrokeStyleUpdates,
@@ -11,6 +12,7 @@ import {
   parseInsetClipPathSides,
   setCssFilterFunctionPx,
 } from "./PropertyPanel";
+import { isSelectedElementHidden } from "./propertyPanelHelpers";
 
 describe("PropertyPanel style helpers", () => {
   it("normalizes bounded pixel values without accepting incompatible units", () => {
@@ -113,3 +115,26 @@ describe("PropertyPanel style helpers", () => {
     expect(buildStrokeStyleUpdates("solid", "4px")).toEqual([["border-style", "solid"]]);
   });
 });
+
+describe("isSelectedElementHidden", () => {
+  it("reads hidden state by selected timeline id or key", () => {
+    const elements: TimelineElement[] = [
+      { id: "visible", tag: "div", start: 0, duration: 1, track: 0 },
+      { id: "hidden", tag: "div", start: 0, duration: 1, track: 0, hidden: true },
+      {
+        id: "keyed-hidden",
+        key: "scene.html:#keyed-hidden",
+        tag: "div",
+        start: 0,
+        duration: 1,
+        track: 0,
+        hidden: true,
+      },
+    ];
+
+    expect(isSelectedElementHidden(elements, null)).toBe(false);
+    expect(isSelectedElementHidden(elements, "visible")).toBe(false);
+    expect(isSelectedElementHidden(elements, "hidden")).toBe(true);
+    expect(isSelectedElementHidden(elements, "scene.html:#keyed-hidden")).toBe(true);
+  });
+});

package/src/components/editor/PropertyPanel.tsx

@@ -1,5 +1,6 @@
 import { memo, useEffect, useMemo, useRef, useState } from "react";
 import { Move } from "../../icons/SystemIcons";
+import { Eye, EyeSlash } from "@phosphor-icons/react";
 import { InspectorHeaderActions } from "./InspectorHeaderActions";
 import { useStudioShellContext } from "../../contexts/StudioContext";
 import { readStudioBoxSize, readStudioPathOffset, readStudioRotation } from "./manualEdits";
@@ -10,6 +11,7 @@ import {
   RESPONSIVE_GRID,
   readGsapRuntimeValuesForPanel,
   readGsapBorderRadiusForPanel,
+  isSelectedElementHidden,
 } from "./propertyPanelHelpers";
 import { MetricField, Section } from "./propertyPanelPrimitives";
 import { createTransformCommitHandlers } from "./propertyPanelTransformCommit";
@@ -67,6 +69,7 @@ export const PropertyPanel = memo(function PropertyPanel({
   onAddTextField,
   onRemoveTextField,
   onAskAgent: _onAskAgent,
+  onToggleElementHidden,
   onImportAssets,
   fontAssets = [],
   onImportFonts,
@@ -106,6 +109,10 @@ export const PropertyPanel = memo(function PropertyPanel({
   const clipboardTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
   const storeTime = usePlayerStore((s) => s.currentTime);
   const isPlaying = usePlayerStore((s) => s.isPlaying);
+  const timelineElements = usePlayerStore((s) => s.elements);
+  const selectedElementId = usePlayerStore((s) => s.selectedElementId);
+  const selectedElementHidden = isSelectedElementHidden(timelineElements, selectedElementId);
+  const visibilityToggleLabel = selectedElementHidden ? "Show element" : "Hide element";
   const liveTimeRef = useRef(storeTime);
   const [, forceRender] = useState(0);
   useEffect(() => {
@@ -288,13 +295,32 @@ export const PropertyPanel = memo(function PropertyPanel({
             </div>
             <div className="mt-0.5 truncate text-[11px] text-neutral-500">{sourceLabel}</div>
           </div>
-          <InspectorHeaderActions
-            element={element}
-            copied={clipboardCopied}
-            onCopy={handleCopyElementInfo}
-            onClear={onClearSelection}
-            onUngroup={onUngroup}
-          />
+          <div className="flex items-center gap-1">
+            {selectedElementId && onToggleElementHidden && (
+              <button
+                type="button"
+                aria-label={visibilityToggleLabel}
+                title={visibilityToggleLabel}
+                onClick={() => {
+                  void onToggleElementHidden(selectedElementId, !selectedElementHidden);
+                }}
+                className="flex h-6 w-6 items-center justify-center rounded text-neutral-500 transition-colors hover:bg-neutral-800 hover:text-neutral-300"
+              >
+                {selectedElementHidden ? (
+                  <EyeSlash size={13} weight="bold" aria-hidden="true" />
+                ) : (
+                  <Eye size={13} weight="bold" aria-hidden="true" />
+                )}
+              </button>
+            )}
+            <InspectorHeaderActions
+              element={element}
+              copied={clipboardCopied}
+              onCopy={handleCopyElementInfo}
+              onClear={onClearSelection}
+              onUngroup={onUngroup}
+            />
+          </div>
         </div>
       </div>
       <div className="flex-1 overflow-y-auto">

package/src/components/editor/domEditingElement.ts

@@ -28,6 +28,7 @@ export function isElementComputedVisible(el: HTMLElement): boolean {
 
 const VISUAL_LEAF_TAGS = new Set(["img", "video", "canvas", "svg", "audio"]);
 
+// fallow-ignore-next-line complexity
 function hasVisualPresence(el: HTMLElement): boolean {
   const win = el.ownerDocument.defaultView;
   if (!win) return false;
@@ -236,9 +237,13 @@ export function isLargeRasterDomEditSelection(
 
 // ─── Element finders ──────────────────────────────────────────────────────────
 
+type FindElementSelection = Pick<DomEditSelection, "id" | "hfId" | "selector" | "selectorIndex"> & {
+  sourceFile?: string;
+};
+
 export function findElementForSelection(
   doc: Document,
-  selection: Pick<DomEditSelection, "id" | "hfId" | "selector" | "selectorIndex" | "sourceFile">,
+  selection: FindElementSelection,
   activeCompositionPath: string | null = null,
 ): HTMLElement | null {
   if (selection.hfId) {
@@ -259,6 +264,7 @@ export function findElementForSelection(
 
   if (!selection.selector) return null;
 
+  // fallow-ignore-next-line code-duplication
   if (selection.selector.startsWith(".") && selection.selectorIndex != null) {
     const matches = querySelectorAllSafely(doc, selection.selector).filter(
       (candidate): candidate is HTMLElement =>
@@ -270,6 +276,7 @@ export function findElementForSelection(
     return matches[selection.selectorIndex] ?? null;
   }
 
+  // fallow-ignore-next-line code-duplication
   const matches = querySelectorAllSafely(doc, selection.selector).filter(
     (candidate): candidate is HTMLElement =>
       isHtmlElement(candidate) &&

package/src/components/editor/manualEditsDom.ts

@@ -33,6 +33,7 @@ import {
 import { roundRotationAngle } from "./manualEditsParsing";
 import { applyStudioMotionFromDom } from "./studioMotion";
 import { gsapAnimatesProperty } from "./gsapAnimatesProperty";
+import { splitTopLevelWhitespace } from "./manualEditsStyleHelpers";
 
 /* ── Gesture tracking ─────────────────────────────────────────────── */
 let studioManualEditGestureId = 0;
@@ -162,24 +163,6 @@ export function restoreInlineDisplay(element: HTMLElement): void {
 }
 
 /* ── Translate helpers ────────────────────────────────────────────── */
-function splitTopLevelWhitespace(value: string): string[] {
-  const parts: string[] = [];
-  let depth = 0;
-  let current = "";
-  for (const char of value.trim()) {
-    if (char === "(") depth += 1;
-    if (char === ")") depth = Math.max(0, depth - 1);
-    if (/\s/.test(char) && depth === 0) {
-      if (current) parts.push(current);
-      current = "";
-    } else {
-      current += char;
-    }
-  }
-  if (current) parts.push(current);
-  return parts;
-}
-
 function composeTranslateValue(element: HTMLElement, x: string, y: string): string {
   const original = element.getAttribute(STUDIO_ORIGINAL_TRANSLATE_ATTR)?.trim();
   if (!original || original === "none") return `${x} ${y}`;

package/src/components/editor/manualEditsStyleHelpers.ts

@@ -0,0 +1,18 @@
+export function splitTopLevelWhitespace(value: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  // fallow-ignore-next-line code-duplication
+  let current = "";
+  for (const char of value.trim()) {
+    if (char === "(") depth += 1;
+    if (char === ")") depth = Math.max(0, depth - 1);
+    if (/\s/.test(char) && depth === 0) {
+      if (current) parts.push(current);
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  if (current) parts.push(current);
+  return parts;
+}

package/src/components/editor/offCanvasIndicatorGeometry.ts

@@ -0,0 +1,74 @@
+import type React from "react";
+import type { OffCanvasRect } from "./OffCanvasIndicators";
+import { hugRectForElement } from "./domEditOverlayCrop";
+import { groupAwareOverlayRect } from "./domEditOverlayGeometry";
+import { isElementComputedVisible } from "./domEditingElement";
+import { collectDomEditLayerItems } from "./domEditingLayers";
+
+function rounded(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function offCanvasSignature(rects: OffCanvasRect[]): string {
+  return rects
+    .map(
+      (rect) =>
+        `${rect.key}:${rounded(rect.left)},${rounded(rect.top)},${rounded(rect.width)},${rounded(rect.height)}`,
+    )
+    .join("|");
+}
+
+// fallow-ignore-next-line complexity
+export function recomputeOffCanvasIndicators(
+  iframe: HTMLIFrameElement,
+  overlay: HTMLDivElement,
+  doc: Document | null | undefined,
+  comp: { left: number; top: number; width: number; height: number },
+  activeCompositionPath: string | null,
+  sigRef: React.MutableRefObject<string>,
+  elementsRef: React.MutableRefObject<Map<string, HTMLElement>>,
+  setRects: (rects: OffCanvasRect[]) => void,
+): void {
+  if (comp.width <= 0 || !doc) {
+    sigRef.current = "";
+    elementsRef.current = new Map();
+    setRects([]);
+    return;
+  }
+
+  const root = doc.querySelector<HTMLElement>("[data-composition-id]") ?? doc.body;
+  const acp = activeCompositionPath ?? "index.html";
+  const items = collectDomEditLayerItems(root, {
+    activeCompositionPath: acp,
+    isMasterView: !acp || acp === "index.html",
+  });
+  const rects: OffCanvasRect[] = [];
+  const elMap = new Map<string, HTMLElement>();
+  for (const item of items) {
+    if (!isElementComputedVisible(item.element)) continue;
+    // Groups use their members' union (where they actually render), so a group
+    // whose members sit inside the canvas isn't flagged off-canvas by a stale
+    // wrapper box. Crop-hug the result so an inset crop that keeps the visible
+    // part on-canvas doesn't flag the element either.
+    const base = groupAwareOverlayRect(overlay, iframe, item.element);
+    const r = base ? { ...base, ...hugRectForElement(base, item.element) } : null;
+    if (!r) continue;
+    // Any edge crossing the composition border → gray-zone indicator (the
+    // in-canvas portion is clipped away below, so only the sliver shows).
+    const extendsOutsideComp =
+      r.left < comp.left ||
+      r.left + r.width > comp.left + comp.width ||
+      r.top < comp.top ||
+      r.top + r.height > comp.top + comp.height;
+    if (extendsOutsideComp) {
+      rects.push({ key: item.key, left: r.left, top: r.top, width: r.width, height: r.height });
+      elMap.set(item.key, item.element);
+    }
+  }
+
+  const nextSig = offCanvasSignature(rects);
+  if (nextSig === sigRef.current) return;
+  sigRef.current = nextSig;
+  elementsRef.current = elMap;
+  setRects(rects);
+}

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

@@ -0,0 +1,154 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { describe, expect, it } from "vitest";
+import { DomEditOverlay } from "./DomEditOverlay";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+const INDICATOR = '[aria-label="Select off-canvas element index.html:headline:0"]';
+
+function domRect(left: number, top: number, width: number, height: number): DOMRect {
+  return {
+    left,
+    top,
+    right: left + width,
+    bottom: top + height,
+    width,
+    height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  };
+}
+
+async function flushAnimationFrames(): Promise<void> {
+  await new Promise<void>((resolve) => {
+    requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+  });
+}
+
+interface OverlayHarness {
+  host: HTMLElement;
+  movedElement: HTMLElement;
+  cleanup: () => void;
+}
+
+// Mount DomEditOverlay over an iframe whose #headline sits at `initialLeft`, with a
+// getBoundingClientRect stub that reads the element's live inline geometry (so a
+// style mutation moves it) and reports the composition/overlay as 800x450 at origin.
+function mountOverlayWithHeadline(initialLeft: number): OverlayHarness {
+  const originalGetBoundingClientRect = Element.prototype.getBoundingClientRect;
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root: Root = createRoot(host);
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const doc = iframe.contentDocument;
+  if (!doc) throw new Error("Expected iframe content document");
+
+  doc.body.innerHTML = `
+    <div data-composition-id="root" data-width="800" data-height="450">
+      <div id="headline" style="position:absolute; left:${initialLeft}px; top:40px; width:100px; height:40px;">Headline</div>
+    </div>
+  `;
+  const movedElement = doc.getElementById("headline");
+  if (!movedElement) throw new Error("Expected test element");
+
+  Element.prototype.getBoundingClientRect = function (): DOMRect {
+    if (this === movedElement) {
+      return domRect(
+        Number.parseFloat(movedElement.style.left),
+        Number.parseFloat(movedElement.style.top),
+        Number.parseFloat(movedElement.style.width),
+        Number.parseFloat(movedElement.style.height),
+      );
+    }
+    return domRect(0, 0, 800, 450);
+  };
+
+  act(() => {
+    root.render(
+      <DomEditOverlay
+        iframeRef={{ current: iframe }}
+        activeCompositionPath={null}
+        selection={null}
+        hoverSelection={null}
+        groupSelections={[]}
+        onCanvasMouseDown={() => {}}
+        onCanvasPointerMove={() => Promise.resolve(null)}
+        onCanvasPointerLeave={() => {}}
+        onSelectionChange={() => {}}
+        onBlockedMove={() => {}}
+        onPathOffsetCommit={() => {}}
+        onGroupPathOffsetCommit={() => {}}
+        onBoxSizeCommit={() => {}}
+        onRotationCommit={() => {}}
+      />,
+    );
+  });
+
+  return {
+    host,
+    movedElement,
+    cleanup: () => {
+      act(() => root.unmount());
+      Element.prototype.getBoundingClientRect = originalGetBoundingClientRect;
+      iframe.remove();
+      host.remove();
+    },
+  };
+}
+
+describe("off-canvas indicator refresh", () => {
+  it("removes the indicator when an off-canvas element moves in-canvas (off->on)", async () => {
+    const h = mountOverlayWithHeadline(760);
+    try {
+      await act(async () => {
+        await flushAnimationFrames();
+      });
+      expect(h.host.querySelector(INDICATOR)).toBeTruthy();
+
+      act(() => {
+        h.movedElement.style.left = "120px";
+      });
+      await act(async () => {
+        await Promise.resolve();
+        await flushAnimationFrames();
+      });
+
+      expect(h.host.querySelector(INDICATOR)).toBeNull();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  it("tracks the indicator to the new position when it stays off-canvas (off->off)", async () => {
+    const h = mountOverlayWithHeadline(760);
+    try {
+      await act(async () => {
+        await flushAnimationFrames();
+      });
+      const before = h.host.querySelector(INDICATOR);
+      expect(before).toBeTruthy();
+      const leftBefore = (before!.parentElement as HTMLElement).style.left;
+
+      // Move further off-canvas (still outside the 800px-wide composition).
+      act(() => {
+        h.movedElement.style.left = "1200px";
+      });
+      await act(async () => {
+        await Promise.resolve();
+        await flushAnimationFrames();
+      });
+
+      const after = h.host.querySelector(INDICATOR);
+      expect(after).toBeTruthy();
+      const leftAfter = (after!.parentElement as HTMLElement).style.left;
+      expect(leftAfter).not.toEqual(leftBefore);
+    } finally {
+      h.cleanup();
+    }
+  });
+});