@hyperframes/studio 0.7.55 → 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

@@ -0,0 +1,171 @@
+/**
+ * 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) 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, 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 {
+  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-[40vh] rounded object-contain" />
+    );
+  }
+  if (kind === "video") {
+    return (
+      <video
+        src={serveUrl}
+        controls
+        autoPlay
+        muted
+        playsInline
+        className="max-w-full max-h-[40vh] rounded"
+      />
+    );
+  }
+  return (
+    <div className="flex flex-col items-center gap-3 px-6 py-4">
+      <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]);
+
+  // 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);
+  const name = basename(previewAsset);
+
+  return (
+    <div
+      className="absolute inset-0 z-50 flex flex-col items-center justify-center bg-black/20"
+      onClick={clearPreviewAsset}
+      role="dialog"
+      aria-label={`Preview: ${name}`}
+    >
+      {/* Floating preview card — compact, canvas stays visible around it */}
+      <div
+        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 */}
+        <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();
+  });
+});