@hyperframes/studio 0.7.54 → 0.7.56

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -4,7 +4,6 @@
  * Owns: onPointerMove, onPointerUp, clearPointerState.
  * startGesture and startGroupDrag live in domEditOverlayStartGesture.ts.
  */
-import { setElementGsapPosition } from "../../utils/elementGsap";
 import type { RefObject } from "react";
 import { type DomEditSelection } from "./domEditing";
 import {
@@ -30,36 +29,29 @@ import {
 import {
   type GroupOverlayItem,
   type OverlayRect,
+  orientedOverlayRect,
   resolveDomEditGroupOverlayRect,
-  toOverlayRect,
 } from "./domEditOverlayGeometry";
 import {
   BLOCKED_MOVE_THRESHOLD_PX,
   type GestureKind,
   type GestureState,
   type GroupGestureState,
+  type ResizeHandle,
   type UseDomEditOverlayGesturesOptions,
+  ROTATED_SNAP_BYPASS_DEGREES,
   hasDomEditRotationChanged,
-  resolveDomEditResizeGesture,
   resolveDomEditRotationGesture,
 } from "./domEditOverlayGestures";
+import { resolveCenterResizeSize } from "./domEditResizeLocal";
+import { resolveResizeDraftRect } from "./resizeDraft";
 import {
   startGesture as _startGesture,
   startGroupDrag as _startGroupDrag,
 } from "./domEditOverlayStartGesture";
 import { hugRectForElement } from "./domEditOverlayCrop";
-import {
-  resolveSnapAdjustment,
-  resolveResizeSnapAdjustment,
-  resolveEquidistanceGuides,
-  SNAP_THRESHOLD_PX,
-} from "./snapEngine";
-/** Undo the resize draft's anchor pin: snap GSAP x/y back to the gesture base. */
-function restoreResizeAnchorPin(element: HTMLElement, g: GestureState): void {
-  const anchor = g.resizeAnchor;
-  if (!anchor || (anchor.pinX === 0 && anchor.pinY === 0)) return;
-  setElementGsapPosition(element, anchor.baseGsapX, anchor.baseGsapY);
-}
+import { resolveSnapAdjustment, resolveEquidistanceGuides, SNAP_THRESHOLD_PX } from "./snapEngine";
+import { logResize, logResizeMove, logResizeSettle } from "../../utils/resizeDebug";
 
 export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGesturesOptions) {
   const setDraftOverlayRect = (next: OverlayRect) => {
@@ -73,6 +65,10 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       height: g.originHeight,
       editScaleX: g.editScaleX,
       editScaleY: g.editScaleY,
+      // Every draft rect must carry the element's rotation: the rotation wrapper
+      // renders rotate(overlayRect.angle), so an omitted angle straightens the
+      // chrome for the duration of the draft (the "straightens while moving" bug).
+      angle: g.actualRotation,
     });
   };
   const setDraftGroupOverlayItems = (next: GroupOverlayItem[]) => {
@@ -88,7 +84,11 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
   const startGesture = (
     kind: GestureKind,
     e: React.PointerEvent<HTMLElement>,
-    options?: { selection?: DomEditSelection; rect?: OverlayRect | null },
+    options?: {
+      selection?: DomEditSelection;
+      rect?: OverlayRect | null;
+      resizeHandle?: ResizeHandle;
+    },
   ) => _startGesture(kind, e, opts, options);
 
   // fallow-ignore-next-line complexity
@@ -183,8 +183,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         actualAngle: g.actualRotation,
         snap: e.shiftKey,
       });
-      const draftViaGsap = applyRotationDraftViaGsap(sel.element, rotated.angle);
-      if (!draftViaGsap) {
+      if (!applyRotationDraftViaGsap(sel.element, rotated.angle)) {
         applyStudioRotationDraft(sel.element, rotated);
       }
       return;
@@ -192,7 +191,11 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
 
     if (g.kind === "drag") {
       const sc = g.snapContext;
-      if (sc?.snapEnabled && sc.targets.length > 0) {
+      // Bypass edge-snapping for rotated elements — the snap targets and the
+      // snapped rect are axis-aligned, so snapping a rotated box's AABB shifts it
+      // unpredictably. Rotation ~0 keeps snapping exactly as before.
+      const dragRotated = Math.abs(g.actualRotation) >= ROTATED_SNAP_BYPASS_DEGREES;
+      if (!dragRotated && sc?.snapEnabled && sc.targets.length > 0) {
         // Snap the element's VISIBLE (crop-hugged) edges, not the full bounds.
         const movingRect = hugRectForElement(
           {
@@ -246,6 +249,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         height: g.originHeight,
         editScaleX: g.editScaleX,
         editScaleY: g.editScaleY,
+        angle: g.actualRotation,
       });
       if (box) {
         box.style.left = `${nextBoxLeft}px`;
@@ -255,90 +259,49 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     } else {
       if (!box) return;
 
-      const sc = g.snapContext;
-      if (sc?.snapEnabled && sc.targets.length > 0) {
-        const movingRect = {
-          left: g.originLeft,
-          top: g.originTop,
-          width: g.originWidth,
-          height: g.originHeight,
-        };
-        const allTargets = sc.compositionTarget
-          ? [...sc.targets, sc.compositionTarget]
-          : sc.targets;
-        const snap = resolveResizeSnapAdjustment({
-          movingRect,
-          proposedDx: dx,
-          proposedDy: dy,
-          targets: allTargets,
-          gridEdges: sc.gridEdges ?? undefined,
-          threshold: SNAP_THRESHOLD_PX,
-          disabled: e.altKey,
-        });
-        dx = snap.dx;
-        dy = snap.dy;
-        opts.snapGuidesRef.current = { guides: snap.guides, spacingGuides: [] };
-      }
-
-      const nextSize = resolveDomEditResizeGesture({
-        originWidth: g.originWidth,
-        originHeight: g.originHeight,
-        actualWidth: g.actualWidth,
-        actualHeight: g.actualHeight,
-        scaleX: g.editScaleX,
-        scaleY: g.editScaleY,
-        contentScaleX: g.contentScaleX,
-        contentScaleY: g.contentScaleY,
-        dx,
-        dy,
-        uniform: e.shiftKey,
+      // CENTER-ANCHORED size (CapCut model): the element scales proportionally
+      // about its CENTER — the scale is the pointer's RADIAL distance from the
+      // element center now over its distance at gesture start. Rotation-invariant
+      // (a distance ignores the angle) and continuous, so all four corners behave
+      // identically and there is no per-axis projection or edge-snapping. Base size
+      // is the element-local px size at gesture start (actualWidth/Height,
+      // GSAP-scale-aware). Corner drag is ALWAYS proportional; there is no
+      // free-form stretch gesture. Edge-snapping is intentionally NOT applied:
+      // with center anchoring both edges move symmetrically, so the corner-anchored
+      // snap math no longer holds — CapCut does not edge-snap during scale either.
+      const nextSize = resolveCenterResizeSize({
+        baseWidth: g.actualWidth,
+        baseHeight: g.actualHeight,
+        pointer: { x: e.clientX, y: e.clientY },
+        pointerStart: { x: g.startX, y: g.startY },
+        centerStart: { x: g.centerX, y: g.centerY },
       });
       applyStudioBoxSizeDraft(sel.element, nextSize);
-      // Pin the gesture anchor (top-left): with a live scale transform, the CSS
-      // size change shifts the rendered box around the element center. Measure
-      // the drift of the gesture-start corner and counter it via GSAP x/y —
-      // accumulated onto the previous pin so the correction converges instead
-      // of oscillating. The release-time position compensation re-measures the
-      // drop, so the pin composes with the commit.
-      const anchor = g.resizeAnchor;
-      if (anchor) {
-        const pinned = sel.element.getBoundingClientRect();
-        const nextPinX = anchor.pinX + (anchor.anchorX - pinned.x);
-        const nextPinY = anchor.pinY + (anchor.anchorY - pinned.y);
-        if (
-          setElementGsapPosition(
-            sel.element,
-            anchor.baseGsapX + nextPinX,
-            anchor.baseGsapY + nextPinY,
-          )
-        ) {
-          anchor.pinX = nextPinX;
-          anchor.pinY = nextPinY;
-        }
-      }
-      // Re-read BCR after applying dimensions. For elements with a GSAP
-      // scale transform and centered transform-origin the visual top-left
-      // drifts and the visual size diverges from the raw CSS size, so BCR
-      // is the only accurate source for both.
+
       const overlayEl = opts.overlayRef.current;
       const iframe = opts.iframeRef.current;
-      const refreshed = overlayEl && iframe ? toOverlayRect(overlayEl, iframe, sel.element) : null;
-      const overlayLeft = refreshed ? refreshed.left : g.originLeft;
-      const overlayTop = refreshed ? refreshed.top : g.originTop;
-      const overlayWidth = refreshed ? refreshed.width : nextSize.overlayWidth;
-      const overlayHeight = refreshed ? refreshed.height : nextSize.overlayHeight;
-      box.style.left = `${overlayLeft}px`;
-      box.style.top = `${overlayTop}px`;
-      box.style.width = `${overlayWidth}px`;
-      box.style.height = `${overlayHeight}px`;
-      setDraftOverlayRect({
-        left: overlayLeft,
-        top: overlayTop,
-        width: overlayWidth,
-        height: overlayHeight,
-        editScaleX: g.editScaleX,
-        editScaleY: g.editScaleY,
+      const measureOrientedRect = () =>
+        overlayEl && iframe ? orientedOverlayRect(overlayEl, iframe, sel.element) : null;
+
+      const draftRect = resolveResizeDraftRect(
+        g,
+        sel.element,
+        overlayEl,
+        iframe,
+        measureOrientedRect,
+      );
+      logResizeMove({
+        pointer: { x: e.clientX, y: e.clientY },
+        nextSize,
+        anchor: g.lastResizeAnchor ?? null,
+        draftRect,
+        liveInlineStyle: sel.element.getAttribute("style"),
       });
+      box.style.left = `${draftRect.left}px`;
+      box.style.top = `${draftRect.top}px`;
+      box.style.width = `${draftRect.width}px`;
+      box.style.height = `${draftRect.height}px`;
+      setDraftOverlayRect(draftRect);
     }
   };
 
@@ -414,9 +377,12 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
 
     if (g.kind === "resize" && movedDistance < BLOCKED_MOVE_THRESHOLD_PX) {
-      restoreResizeAnchorPin(sel.element, g);
       restoreStudioBoxSize(sel.element, g.initialBoxSize);
-      endStudioManualEditGesture(sel.element, g.manualEditDragToken);
+      if (g.pathOffsetMember) {
+        restoreManualOffsetDragMembers([g.pathOffsetMember]);
+      } else {
+        endStudioManualEditGesture(sel.element, g.manualEditDragToken);
+      }
       if (box) {
         box.style.width = `${g.originWidth}px`;
         box.style.height = `${g.originHeight}px`;
@@ -444,8 +410,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
           restoreStudioRotation(sel.element, g.initialRotation);
         }
       };
-      const rotationChanged = hasDomEditRotationChanged(g.actualRotation, finalRotation.angle);
-      if (!rotationChanged) {
+      if (!hasDomEditRotationChanged(g.actualRotation, finalRotation.angle)) {
         restoreRotation();
         endStudioManualEditGesture(sel.element, g.manualEditDragToken);
         return;
@@ -464,10 +429,13 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
           )
             restoreRotation();
         })
-        .finally(() => {
-          endStudioManualEditGesture(sel.element, g.manualEditDragToken);
-        });
+        .finally(() => endStudioManualEditGesture(sel.element, g.manualEditDragToken));
     } else if (g.kind === "drag") {
+      // A moved drag (taps returned earlier) must not let the release click
+      // re-select whatever now sits under the pointer — dropping over a
+      // higher-z element should keep the dragged element selected, not select
+      // the drop target. Mirrors the resize branch below.
+      opts.suppressNextBoxClickRef.current = true;
       const dx = g.lastSnappedDx ?? e.clientX - g.startX;
       const dy = g.lastSnappedDy ?? e.clientY - g.startY;
       if (!g.pathOffsetMember) {
@@ -483,6 +451,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         height: g.originHeight,
         editScaleX: g.editScaleX,
         editScaleY: g.editScaleY,
+        angle: g.actualRotation,
       });
       if (box) {
         box.style.left = `${nextBoxLeft}px`;
@@ -505,18 +474,45 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       opts.suppressNextBoxClickRef.current = true;
       const finalSize = readStudioBoxSize(sel.element);
       applyStudioBoxSize(sel.element, finalSize);
-      void Promise.resolve(opts.onBoxSizeCommitRef.current(sel, finalSize))
+      // Anchored corner resize (NW/NE/SW) also moved the element to keep the
+      // center planted. Land the size AND the anchor offset in a SINGLE
+      // box-size commit (one persist, one undo entry). The prior two-commit
+      // sequence re-stamped the element from source after the size-only persist
+      // but before the offset persist landed — that one frame (new size, old
+      // offset) was the release "jump". SE has no anchor member → size only.
+      const member = g.pathOffsetMember;
+      const anchor = g.lastResizeAnchor;
+      const finalOffset =
+        member && anchor && (anchor.dx !== 0 || anchor.dy !== 0)
+          ? applyManualOffsetDragCommit(member, anchor.dx, anchor.dy)
+          : null;
+      logResize("release", {
+        finalSize,
+        anchor: anchor ?? null,
+        finalOffset: finalOffset ?? null,
+        hasMember: !!member,
+        inlineStyle: sel.element.getAttribute("style"),
+      });
+      const restore = () => {
+        if (
+          !g.manualEditDragToken ||
+          !isStudioManualEditGestureCurrent(sel.element, g.manualEditDragToken)
+        )
+          return;
+        restoreStudioBoxSize(sel.element, g.initialBoxSize);
+        if (finalOffset) restoreStudioPathOffset(sel.element, g.initialPathOffset);
+      };
+      void Promise.resolve(
+        opts.onBoxSizeCommitRef.current(sel, finalSize, finalOffset ?? undefined, restore),
+      )
         .catch((error) => {
           console.error("resize commit failed", error);
-          if (
-            g.manualEditDragToken &&
-            isStudioManualEditGestureCurrent(sel.element, g.manualEditDragToken)
-          ) {
-            restoreResizeAnchorPin(sel.element, g);
-            restoreStudioBoxSize(sel.element, g.initialBoxSize);
-          }
         })
-        .finally(() => endStudioManualEditGesture(sel.element, g.manualEditDragToken));
+        .finally(() => {
+          if (member) endManualOffsetDragMembers([member]);
+          else endStudioManualEditGesture(sel.element, g.manualEditDragToken);
+        });
+      logResizeSettle(sel.element, "post-release");
     }
   };
 
@@ -534,9 +530,12 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       restoreGestureOverlayRect(g);
     }
     if (g?.mode === "box-size" && sel) {
-      restoreResizeAnchorPin(sel.element, g);
       restoreStudioBoxSize(sel.element, g.initialBoxSize);
-      endStudioManualEditGesture(sel.element, g.manualEditDragToken);
+      if (g.pathOffsetMember) {
+        restoreManualOffsetDragMembers([g.pathOffsetMember]);
+      } else {
+        endStudioManualEditGesture(sel.element, g.manualEditDragToken);
+      }
       restoreGestureOverlayRect(g);
     }
     if (g?.mode === "rotation" && sel) {

package/src/components/editor/useDomEditOverlayRects.ts

@@ -13,6 +13,7 @@ import {
   groupOverlayItemsEqual,
   isElementVisibleForOverlay,
   groupAwareOverlayRect,
+  orientedGroupAwareOverlayRect,
   rectsEqual,
   resolveElementForOverlay,
   selectionCacheKey,
@@ -157,7 +158,13 @@ export function useDomEditOverlayRects({
         // backgroundless full-bleed scene above a subcomposition), which would wrongly
         // hide the selection box. Occlusion stays for hover, where a false hide is cheap.
         if (el && isElementVisibleForOverlay(el)) {
-          const nextRect = groupAwareOverlayRect(overlayEl, iframe, el);
+          // Groups render as an AABB union of their members (a group OBB is out of
+          // scope); a single element renders as an oriented box that co-rotates
+          // with its transform. orientedOverlayRect gates on rotation internally
+          // (a cheap per-call check) and only pays for the full corner-transform
+          // measurement when the element is actually rotated — this RAF loop runs
+          // every frame for any single selection, so that gate matters here most.
+          const nextRect = orientedGroupAwareOverlayRect(overlayEl, iframe, el);
           setOverlayRect(nextRect);
           const descendants = el.querySelectorAll("*");
           if (descendants.length > 0 && descendants.length <= 60) {
@@ -242,7 +249,7 @@ export function useDomEditOverlayRects({
         return;
       }
 
-      setHoverRect(groupAwareOverlayRect(overlayEl, iframe, hoverEl));
+      setHoverRect(orientedGroupAwareOverlayRect(overlayEl, iframe, hoverEl));
     };
 
     frame = requestAnimationFrame(update);

package/src/components/nle/AssetPreviewOverlay.tsx

@@ -0,0 +1,147 @@
+/**
+ * CapCut-style asset preview overlay rendered inside PreviewPane.
+ *
+ * Shown when the user clicks an asset card that has NOT yet been added to the
+ * timeline. Displays the media (image / video / audio) without modifying the
+ * composition — no undo entry, no file mutation.
+ *
+ * Dismiss: X button, Escape key, or click on the scrim.
+ * Switching to another not-added asset replaces the current preview.
+ */
+import { useEffect, useCallback } from "react";
+import { VIDEO_EXT, IMAGE_EXT } from "../../utils/mediaTypes";
+import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
+import { resolveMediaPreviewUrl } from "../../player/components/thumbnailUtils";
+
+function basename(path: string): string {
+  return path.split("/").pop() ?? path;
+}
+
+type AssetKind = "image" | "video" | "audio";
+
+function resolveAssetKind(path: string): AssetKind {
+  if (VIDEO_EXT.test(path)) return "video";
+  if (IMAGE_EXT.test(path)) return "image";
+  return "audio";
+}
+
+/** The media element for a previewed asset, chosen by kind. */
+function AssetPreviewMedia({
+  kind,
+  serveUrl,
+  name,
+}: {
+  kind: AssetKind;
+  serveUrl: string;
+  name: string;
+}) {
+  if (kind === "image") {
+    return (
+      <img
+        src={serveUrl}
+        alt={name}
+        className="max-w-full max-h-[70vh] rounded-md object-contain shadow-2xl"
+      />
+    );
+  }
+  if (kind === "video") {
+    return (
+      <video
+        src={serveUrl}
+        controls
+        autoPlay
+        muted
+        playsInline
+        className="max-w-full max-h-[70vh] rounded-md shadow-2xl"
+      />
+    );
+  }
+  return (
+    <div className="flex flex-col items-center gap-4 px-6 py-8 rounded-xl bg-neutral-900 border border-neutral-800">
+      <svg
+        width="40"
+        height="40"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        className="text-neutral-500"
+      >
+        <path d="M9 18V5l12-2v13" strokeLinecap="round" strokeLinejoin="round" />
+        <circle cx="6" cy="18" r="3" />
+        <circle cx="18" cy="16" r="3" />
+      </svg>
+      <audio src={serveUrl} controls className="w-64" />
+    </div>
+  );
+}
+
+export function AssetPreviewOverlay() {
+  const previewAsset = useAssetPreviewStore((s) => s.previewAsset);
+  const previewProjectId = useAssetPreviewStore((s) => s.previewProjectId);
+  const clearPreviewAsset = useAssetPreviewStore((s) => s.clearPreviewAsset);
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      if (e.key === "Escape") clearPreviewAsset();
+    },
+    [clearPreviewAsset],
+  );
+
+  useEffect(() => {
+    if (!previewAsset) return;
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [previewAsset, handleKeyDown]);
+
+  if (!previewAsset || !previewProjectId) return null;
+
+  const serveUrl = resolveMediaPreviewUrl(previewAsset, previewProjectId);
+  const name = basename(previewAsset);
+
+  return (
+    <div
+      className="absolute inset-0 z-50 flex flex-col items-center justify-center bg-black/80"
+      onClick={clearPreviewAsset}
+      role="dialog"
+      aria-label={`Preview: ${name}`}
+      aria-modal="true"
+    >
+      {/* Close button */}
+      <button
+        className="absolute top-3 right-3 w-7 h-7 rounded-full bg-neutral-800 hover:bg-neutral-700 text-neutral-300 hover:text-white flex items-center justify-center transition-colors z-10"
+        onClick={(e) => {
+          e.stopPropagation();
+          clearPreviewAsset();
+        }}
+        aria-label="Close preview"
+      >
+        <svg
+          width="12"
+          height="12"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+          strokeWidth="2.5"
+          fill="none"
+          strokeLinecap="round"
+        >
+          <line x1="18" y1="6" x2="6" y2="18" />
+          <line x1="6" y1="6" x2="18" y2="18" />
+        </svg>
+      </button>
+
+      {/* Media */}
+      <div
+        className="flex flex-col items-center gap-3 max-w-[90%] max-h-[85%]"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <AssetPreviewMedia kind={resolveAssetKind(previewAsset)} serveUrl={serveUrl} name={name} />
+
+        {/* Filename label */}
+        <span className="text-[12px] text-neutral-400 truncate max-w-full px-2 text-center">
+          {name}
+        </span>
+      </div>
+    </div>
+  );
+}

package/src/components/nle/NLEContext.test.ts

@@ -0,0 +1,144 @@
+// @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 { shouldDisableTimelineWhileCompositionLoading, NLEProvider } from "./NLEContext";
+import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
+import { installReactActEnvironment } from "../../hooks/domSelectionTestHarness";
+
+installReactActEnvironment();
+
+// Render NLEProvider into a fresh detached host and settle the mount effect.
+async function mountNleProvider(props: {
+  projectId: string;
+  refreshKey?: number;
+}): Promise<{ host: HTMLDivElement; root: Root }> {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  await renderNleProvider(root, props);
+  return { host, root };
+}
+
+// Re-render NLEProvider into an existing root and settle effects.
+async function renderNleProvider(
+  root: Root,
+  props: {
+    projectId: string;
+    refreshKey?: number;
+    onCompIdToSrcChange?: (map: Map<string, string>) => void;
+  },
+): Promise<void> {
+  await act(async () => {
+    root.render(React.createElement(NLEProvider, props, React.createElement("div")));
+    await Promise.resolve();
+  });
+}
+
+describe("timeline loading disable state", () => {
+  it("disables the timeline while the composition loading overlay is visible", () => {
+    expect(shouldDisableTimelineWhileCompositionLoading(true)).toBe(true);
+  });
+
+  it("reenables the timeline after composition loading finishes", () => {
+    expect(shouldDisableTimelineWhileCompositionLoading(false)).toBe(false);
+  });
+});
+
+describe("NLEProvider — asset preview scoping", () => {
+  beforeEach(() => {
+    // No project API in this unit test — stub fetch so the compIdToSrc mount
+    // effect's request rejects quietly instead of hitting the network.
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(() => Promise.reject(new Error("no network in tests"))),
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    useAssetPreviewStore.getState().clearPreviewAsset();
+  });
+
+  it("clears a stale cross-project asset preview when the active project changes", async () => {
+    const { host, root } = await mountNleProvider({ projectId: "project-a" });
+
+    useAssetPreviewStore.getState().setPreviewAsset("assets/photo.png", "project-a");
+    expect(useAssetPreviewStore.getState().previewAsset).toBe("assets/photo.png");
+
+    await renderNleProvider(root, { projectId: "project-b" });
+
+    // The overlay stays mounted across the project switch (EditorShell isn't
+    // keyed by projectId) — the store itself must be the thing that clears.
+    expect(useAssetPreviewStore.getState().previewAsset).toBeNull();
+    expect(useAssetPreviewStore.getState().previewProjectId).toBeNull();
+
+    act(() => root.unmount());
+    host.remove();
+  });
+
+  it("does not clear the preview on a re-render that keeps the same projectId", async () => {
+    const { host, root } = await mountNleProvider({ projectId: "project-a" });
+
+    useAssetPreviewStore.getState().setPreviewAsset("assets/photo.png", "project-a");
+
+    await renderNleProvider(root, { projectId: "project-a", refreshKey: 1 });
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBe("assets/photo.png");
+
+    act(() => root.unmount());
+    host.remove();
+  });
+});
+
+describe("NLEProvider — composition source-map scoping", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("clears the old map and ignores a late project-A response after switching to B", async () => {
+    let resolveA!: (response: Response) => void;
+    const fetchMock = vi.fn((url: string) => {
+      if (url.includes("project-a")) {
+        return new Promise<Response>((resolve) => {
+          resolveA = resolve;
+        });
+      }
+      return Promise.resolve({
+        ok: true,
+        json: async () => ({
+          content: '<div data-composition-id="b-comp" data-composition-src="compositions/b.html">',
+        }),
+      } as Response);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const observed: Array<Map<string, string>> = [];
+    const onChange = (map: Map<string, string>) => observed.push(new Map(map));
+    const { host, root } = await mountNleProvider({
+      projectId: "project-a",
+      onCompIdToSrcChange: onChange,
+    });
+
+    await renderNleProvider(root, {
+      projectId: "project-b",
+      onCompIdToSrcChange: onChange,
+    });
+    await act(async () => Promise.resolve());
+
+    expect(observed.filter((map) => map.size === 0)).toHaveLength(2);
+    expect(fetchMock).toHaveBeenCalledWith("/api/projects/project-b/files/index.html", {
+      signal: expect.any(AbortSignal),
+    });
+    expect(observed.at(-1)).toEqual(new Map([["b-comp", "compositions/b.html"]]));
+
+    resolveA({
+      ok: true,
+      json: async () => ({
+        content: '<div data-composition-id="a-comp" data-composition-src="compositions/a.html">',
+      }),
+    } as Response);
+    await act(async () => Promise.resolve());
+    expect(observed.at(-1)).toEqual(new Map([["b-comp", "compositions/b.html"]]));
+
+    act(() => root.unmount());
+    host.remove();
+  });
+});