@hyperframes/studio 0.7.56 → 0.7.57

package/src/components/editor/useZOrderCrossedFlash.tsx

@@ -0,0 +1,68 @@
+/**
+ * Z-order "show your work" flash: after a bring-forward / send-backward, the
+ * sibling that was stepped over gets a brief (600ms) highlight so the action
+ * is legible even when the visual change is subtle.
+ *
+ * Drawn in the STUDIO's own overlay layer above the preview iframe — nothing
+ * is written into the iframe DOM or the composition, so a concurrent preview
+ * reload can never leave a stuck highlight; the timeout merely clears
+ * studio-local state. The crossed element is resolved by the context menu
+ * (resolveCrossedNeighbor) from the same pre-mutation render order as the
+ * z patches; z-index writes don't move layout, so measuring its rect after
+ * the commit applied live styles is still accurate.
+ */
+import { useCallback, useEffect, useRef, useState, type RefObject } from "react";
+import { toVisibleOverlayRect, type OverlayRect } from "./domEditOverlayGeometry";
+
+const Z_ORDER_CROSSED_FLASH_MS = 600;
+
+interface UseZOrderCrossedFlashParams {
+  overlayRef: RefObject<HTMLDivElement | null>;
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+}
+
+export function useZOrderCrossedFlash({ overlayRef, iframeRef }: UseZOrderCrossedFlashParams): {
+  zOrderFlashRect: OverlayRect | null;
+  handleZOrderCrossed: (crossed: HTMLElement) => void;
+} {
+  const [zOrderFlashRect, setZOrderFlashRect] = useState<OverlayRect | null>(null);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(
+    () => () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    },
+    [],
+  );
+
+  const handleZOrderCrossed = useCallback(
+    (crossed: HTMLElement) => {
+      const overlayEl = overlayRef.current;
+      const iframe = iframeRef.current;
+      if (!overlayEl || !iframe) return;
+      const rect = toVisibleOverlayRect(overlayEl, iframe, crossed);
+      if (!rect || rect.width <= 0 || rect.height <= 0) return;
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      setZOrderFlashRect(rect);
+      timeoutRef.current = setTimeout(() => {
+        timeoutRef.current = null;
+        setZOrderFlashRect(null);
+      }, Z_ORDER_CROSSED_FLASH_MS);
+    },
+    [overlayRef, iframeRef],
+  );
+
+  return { zOrderFlashRect, handleZOrderCrossed };
+}
+
+/** The flash chrome itself — a pulsing accent outline over the crossed sibling. */
+export function ZOrderCrossedFlash({ rect }: { rect: OverlayRect | null }) {
+  if (!rect) return null;
+  return (
+    <div
+      aria-hidden="true"
+      data-dom-edit-z-flash="true"
+      className="pointer-events-none absolute rounded-md border-2 border-studio-accent shadow-[0_0_0_2px_rgba(60,230,172,0.35)] animate-pulse"
+      style={{ left: rect.left, top: rect.top, width: rect.width, height: rect.height }}
+    />
+  );
+}

package/src/components/nle/AssetPreviewOverlay.test.tsx

@@ -0,0 +1,106 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { usePlayerStore } from "../../player/store/playerStore";
+import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
+import { AssetPreviewOverlay } from "./AssetPreviewOverlay";
+
+(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.innerHTML = "";
+  usePlayerStore.getState().reset();
+  // reset() does not cover the out-of-loop seek request; clear it explicitly
+  // so a pending-seek test can't leak into the next one.
+  usePlayerStore.getState().clearSeekRequest();
+  useAssetPreviewStore.getState().clearPreviewAsset();
+});
+
+function mountOverlay(): void {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() => {
+    root?.render(<AssetPreviewOverlay />);
+  });
+}
+
+describe("AssetPreviewOverlay playback dismissal", () => {
+  it("dismisses immediately when opened while playback is ALREADY running", () => {
+    // The RAF playback loop bypasses the store, so no post-open store change
+    // will arrive — the dismiss check must be level-triggered, not edge-triggered.
+    usePlayerStore.setState({ isPlaying: true });
+    mountOverlay();
+
+    act(() => {
+      useAssetPreviewStore.getState().setPreviewAsset("assets/clip.mp3", "p1");
+    });
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBeNull();
+    expect(document.querySelector('[role="dialog"]')).toBeNull();
+  });
+
+  it("dismisses immediately when opened while a seek is ALREADY in flight", () => {
+    // A pending out-of-loop seek (requestedSeekTime set, not yet consumed) may
+    // produce no further store change before currentTime settles — the on-open
+    // check must evaluate the full shared dismiss predicate, not just isPlaying.
+    usePlayerStore.setState({ isPlaying: false, requestedSeekTime: 3.2 });
+    mountOverlay();
+
+    act(() => {
+      useAssetPreviewStore.getState().setPreviewAsset("assets/clip.mp3", "p1");
+    });
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBeNull();
+    expect(document.querySelector('[role="dialog"]')).toBeNull();
+  });
+
+  it("stays open when the playhead is idle", () => {
+    mountOverlay();
+
+    act(() => {
+      useAssetPreviewStore.getState().setPreviewAsset("assets/clip.mp3", "p1");
+    });
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBe("assets/clip.mp3");
+    expect(document.querySelector('[role="dialog"]')).not.toBeNull();
+  });
+
+  it("still dismisses when playback starts AFTER the preview opened", () => {
+    mountOverlay();
+
+    act(() => {
+      useAssetPreviewStore.getState().setPreviewAsset("assets/clip.mp3", "p1");
+    });
+    expect(useAssetPreviewStore.getState().previewAsset).toBe("assets/clip.mp3");
+
+    act(() => {
+      usePlayerStore.setState({ isPlaying: true });
+    });
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBeNull();
+  });
+
+  it("still dismisses when the playhead is scrubbed after opening", () => {
+    usePlayerStore.setState({ currentTime: 2 });
+    mountOverlay();
+
+    act(() => {
+      useAssetPreviewStore.getState().setPreviewAsset("assets/clip.mp3", "p1");
+    });
+
+    act(() => {
+      usePlayerStore.setState({ currentTime: 4.5 });
+    });
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBeNull();
+  });
+});

package/src/components/nle/AssetPreviewOverlay.tsx

@@ -2,15 +2,20 @@
  * 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.
+ * timeline. Displays the media (image / video / audio) as a compact floating
+ * card over the canvas — the canvas stays visible behind a barely-tinted
+ * click-catcher — without modifying the composition (no undo entry, no file
+ * mutation).
  *
- * Dismiss: X button, Escape key, or click on the scrim.
+ * Dismiss: X button, Escape key, click outside the card, or any playhead
+ * activity (starting playback / seeking) — the canvas refocuses.
  * 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 { usePlayerStore } from "../../player/store/playerStore";
+import { shouldDismissAssetPreview } from "../../utils/assetPreviewDismiss";
 import { resolveMediaPreviewUrl } from "../../player/components/thumbnailUtils";
 
 function basename(path: string): string {
@@ -37,11 +42,7 @@ function AssetPreviewMedia({
 }) {
   if (kind === "image") {
     return (
-      <img
-        src={serveUrl}
-        alt={name}
-        className="max-w-full max-h-[70vh] rounded-md object-contain shadow-2xl"
-      />
+      <img src={serveUrl} alt={name} className="max-w-full max-h-[40vh] rounded object-contain" />
     );
   }
   if (kind === "video") {
@@ -52,12 +53,12 @@ function AssetPreviewMedia({
         autoPlay
         muted
         playsInline
-        className="max-w-full max-h-[70vh] rounded-md shadow-2xl"
+        className="max-w-full max-h-[40vh] rounded"
       />
     );
   }
   return (
-    <div className="flex flex-col items-center gap-4 px-6 py-8 rounded-xl bg-neutral-900 border border-neutral-800">
+    <div className="flex flex-col items-center gap-3 px-6 py-4">
       <svg
         width="40"
         height="40"
@@ -94,6 +95,30 @@ export function AssetPreviewOverlay() {
     return () => window.removeEventListener("keydown", handleKeyDown);
   }, [previewAsset, handleKeyDown]);
 
+  // The canvas refocuses on any playhead activity: starting playback or a
+  // seek/scrub away from where the playhead sat when the preview opened
+  // dismisses it. openedTime is captured per preview open (previewAsset dep),
+  // so a stale render can never dismiss against the wrong reference time.
+  useEffect(() => {
+    if (!previewAsset) return;
+    const opened = usePlayerStore.getState();
+    const openedTime = opened.currentTime;
+    // Level-triggered, not edge-triggered: a preview opened while playback is
+    // ALREADY running (the RAF loop bypasses the store) or while a seek is
+    // already in flight gets no store change to react to, so evaluate the
+    // current state once, through the same shared predicate the subscription
+    // uses. openedTime is this snapshot's own currentTime, so the
+    // time-diverged branch can't false-positive at open — only the
+    // isPlaying / requestedSeekTime branches can fire here.
+    if (shouldDismissAssetPreview(openedTime, opened)) {
+      clearPreviewAsset();
+      return;
+    }
+    return usePlayerStore.subscribe((state) => {
+      if (shouldDismissAssetPreview(openedTime, state)) clearPreviewAsset();
+    });
+  }, [previewAsset, clearPreviewAsset]);
+
   if (!previewAsset || !previewProjectId) return null;
 
   const serveUrl = resolveMediaPreviewUrl(previewAsset, previewProjectId);
@@ -101,40 +126,39 @@ export function AssetPreviewOverlay() {
 
   return (
     <div
-      className="absolute inset-0 z-50 flex flex-col items-center justify-center bg-black/80"
+      className="absolute inset-0 z-50 flex flex-col items-center justify-center bg-black/20"
       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 */}
+      {/* Floating preview card — compact, canvas stays visible around it */}
       <div
-        className="flex flex-col items-center gap-3 max-w-[90%] max-h-[85%]"
+        className="relative flex flex-col items-center gap-2 max-w-[58%] rounded-lg border border-neutral-800 bg-neutral-950/95 p-2 pt-8 shadow-2xl"
         onClick={(e) => e.stopPropagation()}
       >
+        {/* Close button */}
+        <button
+          className="absolute top-2 right-2 w-6 h-6 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>
+
         <AssetPreviewMedia kind={resolveAssetKind(previewAsset)} serveUrl={serveUrl} name={name} />
 
         {/* Filename label */}

package/src/components/nle/PreviewOverlays.tsx

@@ -18,6 +18,7 @@ import {
 import { readStudioUiPreferences } from "../../utils/studioUiPreferences";
 import { readHfId, type DomEditSelection } from "../editor/domEditing";
 import { buildStableSelector } from "../editor/domEditingDom";
+import { deriveTimelineStoreKey } from "../../player/lib/timelineElementHelpers";
 import type { BlockPreviewInfo } from "../sidebar/BlocksTab";
 import type { GestureRecordingState } from "../editor/GestureRecordControl";
 import type { ReactNode } from "react";
@@ -38,6 +39,8 @@ type ZIndexReorderEntry = {
   selector?: string;
   selectorIndex?: number;
   sourceFile: string;
+  /** Timeline store key — lets the commit update the store zIndex synchronously. */
+  key?: string;
 };
 
 /** Can this element be robustly re-targeted for a persisted z change? */
@@ -58,6 +61,12 @@ function selectedZIndexEntry(sel: DomEditSelection, zIndex: number): ZIndexReord
     selector: sel.selector,
     selectorIndex: sel.selectorIndex,
     sourceFile: sel.sourceFile,
+    key: deriveTimelineStoreKey({
+      domId: sel.id ?? undefined,
+      selector: sel.selector,
+      selectorIndex: sel.selectorIndex,
+      sourceFile: sel.sourceFile,
+    }),
   };
 }
 
@@ -75,7 +84,15 @@ function siblingZIndexEntry(
   const id = element.id || undefined;
   const selector = buildStableSelector(element);
   if (!canTargetZIndexElement(element, id, selector)) return null;
-  return { element, zIndex, id, selector, selectorIndex: undefined, sourceFile };
+  return {
+    element,
+    zIndex,
+    id,
+    selector,
+    selectorIndex: undefined,
+    sourceFile,
+    key: deriveTimelineStoreKey({ domId: id, selector, sourceFile }),
+  };
 }
 
 /** Short human-readable label for a dropped sibling, for the console warning below. */
@@ -88,14 +105,16 @@ function describeZIndexElement(element: HTMLElement): string {
 }
 
 // Resolve z-index patches into commit entries; a sibling with no stable
-// id/selector can't be written to source, so it is collected as a label for the
-// revert-on-reload warning instead.
-function resolveZIndexEntries(
+// id/selector can't be written to source, so it is returned as `dropped` for
+// the revert-on-reload warning (and a live-only style write, so the resolved
+// stacking order still renders coherently). Exported so tests can drive the
+// menu → commit path through the same wiring the app uses.
+export function resolveZIndexEntries(
   sel: DomEditSelection,
   patches: ReadonlyArray<{ element: HTMLElement; zIndex: number }>,
-): { entries: ZIndexReorderEntry[]; droppedLabels: string[] } {
+): { entries: ZIndexReorderEntry[]; dropped: Array<{ element: HTMLElement; zIndex: number }> } {
   const entries: ZIndexReorderEntry[] = [];
-  const droppedLabels: string[] = [];
+  const dropped: Array<{ element: HTMLElement; zIndex: number }> = [];
   for (const patch of patches) {
     if (patch.element === sel.element) {
       entries.push(selectedZIndexEntry(sel, patch.zIndex));
@@ -103,9 +122,9 @@ function resolveZIndexEntries(
     }
     const entry = siblingZIndexEntry(patch.element, patch.zIndex, sel.sourceFile);
     if (entry) entries.push(entry);
-    else droppedLabels.push(describeZIndexElement(patch.element));
+    else dropped.push(patch);
   }
-  return { entries, droppedLabels };
+  return { entries, dropped };
 }
 
 // fallow-ignore-next-line complexity
@@ -205,19 +224,20 @@ export function PreviewOverlays({
         onRotationCommit={handleDomRotationCommit}
         onStyleCommit={handleDomStyleCommit}
         onDeleteSelection={handleDomEditElementDelete}
-        onApplyZIndex={(sel, patches) => {
-          const { entries, droppedLabels } = resolveZIndexEntries(sel, patches);
-          if (droppedLabels.length > 0) {
-            // The optimistic z-index has already been applied live at this point —
-            // these siblings just won't be written to source, so they'll revert to
-            // their prior stacking order on the next reload with no other signal.
+        onApplyZIndex={(sel, patches, action) => {
+          const { entries, dropped } = resolveZIndexEntries(sel, patches);
+          if (dropped.length > 0) {
+            // These siblings can't be written to source. Apply their live z
+            // anyway so the resolved stacking order renders coherently — it
+            // just reverts to the prior order on the next reload.
+            for (const patch of dropped) patch.element.style.zIndex = String(patch.zIndex);
             console.warn(
               "[studio] z-index reorder: dropping sibling(s) with no stable id/selector " +
                 "(will revert on reload):",
-              droppedLabels.join(", "),
+              dropped.map((patch) => describeZIndexElement(patch.element)).join(", "),
             );
           }
-          if (entries.length > 0) handleDomZIndexReorderCommit(entries);
+          if (entries.length > 0) handleDomZIndexReorderCommit(entries, undefined, action);
         }}
         gridVisible={snapPrefs.gridVisible}
         gridSpacing={snapPrefs.gridSpacing}

package/src/components/sidebar/AssetCard.test.tsx

@@ -0,0 +1,106 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../../player/store/playerStore";
+import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
+import { AssetCard } from "./AssetCard";
+import { AudioRow } from "./AudioRow";
+
+(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.innerHTML = "";
+  usePlayerStore.getState().reset();
+  useAssetPreviewStore.getState().clearPreviewAsset();
+  vi.restoreAllMocks();
+});
+
+function mount(node: React.ReactElement): HTMLElement {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() => {
+    root?.render(node);
+  });
+  return host;
+}
+
+function clip(input: Partial<TimelineElement> & { id: string; src: string }): TimelineElement {
+  return { tag: "div", start: 0, duration: 5, track: 0, ...input };
+}
+
+/** Simulate a drag-free click: pointerdown + pointerup at the same point. */
+function clickCard(host: HTMLElement): void {
+  const card = host.querySelector('[draggable="true"]');
+  if (!card) throw new Error("Expected a draggable card root");
+  const PointerCtor = (window as { PointerEvent?: typeof MouseEvent }).PointerEvent ?? MouseEvent;
+  act(() => {
+    card.dispatchEvent(new PointerCtor("pointerdown", { bubbles: true, clientX: 5, clientY: 5 }));
+    card.dispatchEvent(new PointerCtor("pointerup", { bubbles: true, clientX: 5, clientY: 5 }));
+  });
+}
+
+describe("AssetCard click behavior", () => {
+  const cardProps = {
+    projectId: "p1",
+    onCopy: vi.fn(),
+    isCopied: false,
+  };
+
+  it("clears an open preview overlay when clicking an already-added asset (reveal branch)", () => {
+    usePlayerStore.getState().setElements([clip({ id: "img1", src: "assets/logo.png" })]);
+    // Preview overlay is open on ANOTHER asset — the reveal must dismiss it,
+    // or it stays stuck over the canvas while the timeline reveals the clip.
+    useAssetPreviewStore.getState().setPreviewAsset("assets/other.png", "p1");
+
+    const host = mount(<AssetCard {...cardProps} asset="assets/logo.png" used />);
+    clickCard(host);
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBeNull();
+    expect(usePlayerStore.getState().selectedElementId).toBe("img1");
+  });
+
+  it("opens the preview overlay for a not-yet-added asset", () => {
+    const host = mount(<AssetCard {...cardProps} asset="assets/logo.png" used={false} />);
+    clickCard(host);
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBe("assets/logo.png");
+    expect(useAssetPreviewStore.getState().previewProjectId).toBe("p1");
+  });
+});
+
+describe("AudioRow click behavior", () => {
+  const rowProps = {
+    projectId: "p1",
+    onCopy: vi.fn(),
+    isCopied: false,
+  };
+
+  it("clears an open preview overlay when clicking an already-added audio asset (reveal branch)", () => {
+    usePlayerStore
+      .getState()
+      .setElements([clip({ id: "bgm1", tag: "audio", src: "assets/bgm.mp3" })]);
+    useAssetPreviewStore.getState().setPreviewAsset("assets/other.mp3", "p1");
+
+    const host = mount(<AudioRow {...rowProps} asset="assets/bgm.mp3" used />);
+    clickCard(host);
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBeNull();
+    expect(usePlayerStore.getState().selectedElementId).toBe("bgm1");
+  });
+
+  it("opens the preview overlay for a not-yet-added audio asset", () => {
+    const host = mount(<AudioRow {...rowProps} asset="assets/bgm.mp3" used={false} />);
+    clickCard(host);
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBe("assets/bgm.mp3");
+  });
+});

package/src/components/sidebar/AssetCard.tsx

@@ -133,8 +133,10 @@ export function AssetCard({
   const pointerDownRef = useRef<{ x: number; y: number } | null>(null);
 
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
+  const requestClipReveal = usePlayerStore((s) => s.requestClipReveal);
   const elements = usePlayerStore((s) => s.elements);
   const setPreviewAsset = useAssetPreviewStore((s) => s.setPreviewAsset);
+  const clearPreviewAsset = useAssetPreviewStore((s) => s.clearPreviewAsset);
 
   const handlePointerDown = useCallback((e: React.PointerEvent) => {
     pointerDownRef.current = { x: e.clientX, y: e.clientY };
@@ -150,14 +152,29 @@ export function AssetCard({
       if (used) {
         const clip = findClipForAsset(elements, asset);
         if (clip) {
-          setSelectedElementId(clip.key ?? clip.id);
+          // Dismiss any open preview overlay (from another asset) — the reveal
+          // must not leave a stale preview card floating over the canvas.
+          clearPreviewAsset();
+          const clipKey = clip.key ?? clip.id;
+          setSelectedElementId(clipKey);
+          // Scroll the timeline so the selected clip is actually visible.
+          requestClipReveal(clipKey);
           return;
         }
       }
       // Not added (or no matching clip found) → preview overlay
       setPreviewAsset(asset, projectId);
     },
-    [used, elements, asset, projectId, setSelectedElementId, setPreviewAsset],
+    [
+      used,
+      elements,
+      asset,
+      projectId,
+      setSelectedElementId,
+      requestClipReveal,
+      setPreviewAsset,
+      clearPreviewAsset,
+    ],
   );
 
   return (

package/src/components/sidebar/AudioRow.tsx

@@ -43,8 +43,10 @@ export function AudioRow({
   // CapCut-style click behavior: drag-threshold gate.
   const pointerDownRef = useRef<{ x: number; y: number } | null>(null);
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
+  const requestClipReveal = usePlayerStore((s) => s.requestClipReveal);
   const elements = usePlayerStore((s) => s.elements);
   const setPreviewAsset = useAssetPreviewStore((s) => s.setPreviewAsset);
+  const clearPreviewAsset = useAssetPreviewStore((s) => s.clearPreviewAsset);
 
   const handlePointerDown = useCallback((e: React.PointerEvent) => {
     pointerDownRef.current = { x: e.clientX, y: e.clientY };
@@ -59,14 +61,29 @@ export function AudioRow({
       if (used) {
         const clip = findClipForAsset(elements, asset);
         if (clip) {
-          setSelectedElementId(clip.key ?? clip.id);
+          // Dismiss any open preview overlay (from another asset) — the reveal
+          // must not leave a stale preview card floating over the canvas.
+          clearPreviewAsset();
+          const clipKey = clip.key ?? clip.id;
+          setSelectedElementId(clipKey);
+          // Scroll the timeline so the selected clip is actually visible.
+          requestClipReveal(clipKey);
           return;
         }
       }
       // Not added → preview overlay (audio player)
       setPreviewAsset(asset, projectId);
     },
-    [used, elements, asset, projectId, setSelectedElementId, setPreviewAsset],
+    [
+      used,
+      elements,
+      asset,
+      projectId,
+      setSelectedElementId,
+      requestClipReveal,
+      setPreviewAsset,
+      clearPreviewAsset,
+    ],
   );
 
   useEffect(() => {

package/src/hooks/domEditCommitTypes.ts

@@ -8,7 +8,18 @@ export interface DomEditPatchBatch {
 
 export type CommitDomEditPatchBatches = (
   batches: DomEditPatchBatch[],
-  options: { label: string; coalesceKey: string },
+  options: {
+    label: string;
+    coalesceKey: string;
+    /**
+     * Request skipping the preview iframe reload after a successful persist.
+     * Only honored when the persist is provably in sync with the live DOM:
+     * every patch operation is inline-style-only AND the server matched every
+     * patch target. Any unmatched target (or a non-style op) falls back to the
+     * reload so the preview reconverges with disk. Default: always reload.
+     */
+    skipReload?: boolean;
+  },
 ) => Promise<void>;
 
 export type PersistDomEditOperations = (