@hyperframes/studio 0.7.76 → 0.7.78

package/src/player/components/KeyframeDiamondContextMenu.test.tsx

@@ -0,0 +1,69 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import {
+  KeyframeDiamondContextMenu,
+  type KeyframeDiamondContextMenuState,
+} from "./KeyframeDiamondContextMenu";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const element = { id: "box", start: 0, duration: 2, track: 0 } as unknown as TimelineElement;
+
+const state: KeyframeDiamondContextMenuState = {
+  x: 10,
+  y: 10,
+  element,
+  elementId: "box",
+  percentage: 50,
+  tweenPercentage: 25,
+  propertyGroup: "position",
+  animationId: "box-to-1-position",
+};
+
+function clickMenuItem(label: string, props: Partial<Record<string, unknown>>) {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  const root = createRoot(host);
+  act(() =>
+    root.render(
+      <KeyframeDiamondContextMenu
+        state={state}
+        onClose={() => {}}
+        onDelete={vi.fn()}
+        onDeleteAll={vi.fn()}
+        {...props}
+      />,
+    ),
+  );
+  const button = Array.from(document.body.querySelectorAll("button")).find(
+    (candidate) => candidate.textContent === label,
+  );
+  act(() => button?.click());
+  act(() => root.unmount());
+  host.remove();
+}
+
+describe("KeyframeDiamondContextMenu", () => {
+  // Two animations can carry a keyframe at the same clip percentage. Dropping the
+  // property group / tween percentage / animation id here sends the mutation back
+  // to first-match-by-percentage, which retimes or deletes the wrong tween.
+  it("hands every action the full keyframe identity, not just the percentage", () => {
+    const onDelete = vi.fn();
+    const onMoveToPlayhead = vi.fn();
+
+    clickMenuItem("Delete Keyframe", { onDelete });
+    clickMenuItem("Move to Playhead", { onMoveToPlayhead });
+
+    const target = {
+      percentage: 50,
+      tweenPercentage: 25,
+      propertyGroup: "position",
+      animationId: "box-to-1-position",
+    };
+    expect(onDelete).toHaveBeenCalledWith("box", target);
+    expect(onMoveToPlayhead).toHaveBeenCalledWith(element, target);
+  });
+});

package/src/player/components/KeyframeDiamondContextMenu.tsx

@@ -1,25 +1,28 @@
 import { memo } from "react";
 import { createPortal } from "react-dom";
 import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
+import type { TimelineElement } from "../store/playerStore";
+import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
 
 export interface KeyframeDiamondContextMenuState {
   x: number;
   y: number;
+  element: TimelineElement;
   elementId: string;
   percentage: number;
   tweenPercentage?: number;
+  propertyGroup?: string;
+  animationId?: string;
   currentEase?: string;
 }
 
 interface KeyframeDiamondContextMenuProps {
   state: KeyframeDiamondContextMenuState;
   onClose: () => void;
-  onDelete: (elementId: string, percentage: number) => void;
-  onDeleteAll: (elementId: string) => void;
-  onChangeEase?: (elementId: string, percentage: number, ease: string) => void;
-  onCopyProperties?: (elementId: string, percentage: number) => void;
+  onDelete: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
+  onDeleteAll: (element: TimelineElement) => void;
   /** Retime the keyframe to the current playhead, preserving its value + ease. */
-  onMoveToPlayhead?: (elementId: string, fromPercentage: number) => void;
+  onMoveToPlayhead?: (element: TimelineElement, keyframe: TimelineKeyframeTarget) => void;
 }
 
 export const KeyframeDiamondContextMenu = memo(function KeyframeDiamondContextMenu({
@@ -30,6 +33,14 @@ export const KeyframeDiamondContextMenu = memo(function KeyframeDiamondContextMe
   onMoveToPlayhead,
 }: KeyframeDiamondContextMenuProps) {
   const menuRef = useContextMenuDismiss(onClose);
+  // The clicked diamond's identity, built once: the menu's two mutating entries
+  // both act on it, and they must not disagree about which keyframe was clicked.
+  const keyframe: TimelineKeyframeTarget = {
+    percentage: state.percentage,
+    tweenPercentage: state.tweenPercentage,
+    propertyGroup: state.propertyGroup,
+    animationId: state.animationId,
+  };
 
   const menuWidth = 200;
   const menuHeight = onMoveToPlayhead ? 100 : 70;
@@ -51,7 +62,7 @@ export const KeyframeDiamondContextMenu = memo(function KeyframeDiamondContextMe
             // Pass clip-% — resolveKeyframeTarget keys the cache lookup on clip-%
             // and returns the tween-% for the mutation. Passing tween-% here would
             // miss the lookup on any tween whose window is shorter than the clip.
-            onMoveToPlayhead(state.elementId, state.percentage);
+            onMoveToPlayhead(state.element, keyframe);
             onClose();
           }}
         >
@@ -64,7 +75,7 @@ export const KeyframeDiamondContextMenu = memo(function KeyframeDiamondContextMe
         type="button"
         className="w-full flex items-center gap-2 px-3 py-1.5 text-xs text-red-400 hover:bg-neutral-800 cursor-pointer text-left"
         onClick={() => {
-          onDelete(state.elementId, state.percentage);
+          onDelete(state.elementId, keyframe);
           onClose();
         }}
       >
@@ -75,7 +86,7 @@ export const KeyframeDiamondContextMenu = memo(function KeyframeDiamondContextMe
         type="button"
         className="w-full flex items-center gap-2 px-3 py-1.5 text-xs text-red-400 hover:bg-neutral-800 cursor-pointer text-left"
         onClick={() => {
-          onDeleteAll(state.elementId);
+          onDeleteAll(state.element);
           onClose();
         }}
       >

package/src/player/components/LayerDisclosureRow.tsx

@@ -0,0 +1,76 @@
+import { CaretRight } from "@phosphor-icons/react";
+import type { TimelineElement } from "../store/playerStore";
+import { TRACK_H } from "./timelineLayout";
+import { TrackClipCount } from "./TrackClipCount";
+
+// Layer row (Figma order: disclosure ▸/▾, diamond, name) — the disclosure lives
+// here, not on the clip bar, and re-expands a collapsed layer.
+export function LayerDisclosureRow({
+  keyframeClip,
+  clipCount,
+  isExpanded,
+  gutterBackground,
+  columnWidth,
+  lanesId,
+  onToggleClipExpanded,
+  children,
+}: {
+  keyframeClip: TimelineElement;
+  clipCount: number;
+  isExpanded: boolean;
+  gutterBackground: string;
+  /** Same adaptive width the lane rows use: a narrowed header column must not
+   *  leave this row hanging over the clips it labels. */
+  columnWidth: number;
+  /** Id of the element holding the lanes this row's caret expands. */
+  lanesId: string;
+  onToggleClipExpanded: () => void;
+  /** Trailing controls that act on the LAYER (the visibility eye), not on a lane. */
+  children?: React.ReactNode;
+}) {
+  const name = keyframeClip.label ?? keyframeClip.domId ?? keyframeClip.id;
+  return (
+    <div
+      className="absolute left-0 top-0 flex items-center gap-1.5 overflow-hidden px-1.5 text-[11px]"
+      style={{
+        width: columnWidth,
+        height: TRACK_H,
+        color: "#ffffff",
+        background: gutterBackground,
+      }}
+    >
+      <button
+        type="button"
+        aria-expanded={isExpanded}
+        aria-controls={lanesId}
+        aria-label={`${isExpanded ? "Collapse" : "Expand"} ${name} keyframes`}
+        title={`${isExpanded ? "Collapse" : "Expand"} keyframe lanes`}
+        // h-6 w-6 = the 24x24 WCAG 2.2 minimum target. The caret glyph stays 11px;
+        // only the hit box grows.
+        className="flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-white/55 hover:text-white focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={(event) => {
+          event.stopPropagation();
+          onToggleClipExpanded();
+        }}
+      >
+        <CaretRight
+          size={11}
+          weight="bold"
+          aria-hidden="true"
+          style={{ transform: isExpanded ? "rotate(90deg)" : undefined }}
+        />
+      </button>
+      {/* Decorative: the disclosure button above already names the row's keyframe
+          state, and aria-label on a plain span is not exposed reliably anyway. */}
+      <span aria-hidden="true" className="shrink-0 text-[13px] leading-none text-white/40">
+        ◇
+      </span>
+      <span className="min-w-0 flex-1 truncate font-medium" title={name}>
+        {name}
+      </span>
+      <TrackClipCount clipCount={clipCount} />
+      {children}
+    </div>
+  );
+}

package/src/player/components/Player.test.ts

@@ -1,7 +1,146 @@
 // @vitest-environment happy-dom
 
-import { describe, expect, it } from "vitest";
-import { hasUnloadedAssets, shouldShowCompositionLoadingOverlay } from "./Player";
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  hasUnloadedAssets,
+  Player,
+  readPreviewErrorMessage,
+  shouldShowCompositionLoadingOverlay,
+} from "./Player";
+
+vi.mock("@hyperframes/player", () => ({}));
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let root: Root | null = null;
+let lifecycleLog: string[] = [];
+
+class TestHyperframesPlayer extends HTMLElement {
+  readonly iframeElement = document.createElement("iframe");
+
+  constructor() {
+    super();
+
+    const addIframeListener = this.iframeElement.addEventListener.bind(this.iframeElement);
+    this.iframeElement.addEventListener = ((type, listener, options) => {
+      lifecycleLog.push(`iframe:${type}`);
+      addIframeListener(type, listener, options);
+    }) as typeof this.iframeElement.addEventListener;
+
+    const addPlayerListener = this.addEventListener.bind(this);
+    this.addEventListener = ((type, listener, options) => {
+      lifecycleLog.push(`player:${type}`);
+      addPlayerListener(type, listener, options);
+    }) as typeof this.addEventListener;
+
+    const setPlayerAttribute = this.setAttribute.bind(this);
+    this.setAttribute = (name, value) => {
+      if (name === "src") lifecycleLog.push("src");
+      setPlayerAttribute(name, value);
+    };
+  }
+}
+
+if (!customElements.get("hyperframes-player")) {
+  customElements.define("hyperframes-player", TestHyperframesPlayer);
+}
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  root = null;
+  lifecycleLog = [];
+  document.body.innerHTML = "";
+});
+
+async function mountPlayer() {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  await act(async () => {
+    root?.render(
+      createElement(Player, {
+        directUrl: "/api/projects/demo/preview",
+        onLoad: vi.fn(),
+        suppressLoadingOverlay: true,
+      }),
+    );
+    await Promise.resolve();
+  });
+
+  const player = host.querySelector<TestHyperframesPlayer>("hyperframes-player");
+  if (!player) throw new Error("player did not mount");
+  return { host, player };
+}
+
+function createAudioIframe() {
+  const iframe = document.createElement("iframe");
+  document.body.appendChild(iframe);
+  const audio = iframe.contentDocument?.createElement("audio");
+  expect(audio).toBeDefined();
+  iframe.contentDocument?.body.appendChild(audio!);
+  return { audio: audio!, iframe };
+}
+
+describe("preview errors", () => {
+  it("reads the player probe error for the visible retry state", () => {
+    expect(
+      readPreviewErrorMessage(
+        new CustomEvent("error", {
+          detail: { message: "Composition timeline not found after 8s" },
+        }),
+      ),
+    ).toBe("Composition timeline not found after 8s");
+  });
+
+  it("falls back when the player emits an unstructured error", () => {
+    expect(readPreviewErrorMessage(new Event("error"))).toBe(
+      "The composition preview did not become ready.",
+    );
+  });
+
+  it("attaches lifecycle listeners before navigating the player", async () => {
+    await mountPlayer();
+    const srcIndex = lifecycleLog.indexOf("src");
+
+    expect(srcIndex).toBeGreaterThan(-1);
+    for (const listener of [
+      "iframe:load",
+      "player:click",
+      "player:shadertransitionstate",
+      "player:ready",
+      "player:error",
+    ]) {
+      expect(lifecycleLog.indexOf(listener)).toBeGreaterThan(-1);
+      expect(lifecycleLog.indexOf(listener)).toBeLessThan(srcIndex);
+    }
+  });
+
+  it("retries a failed preview with a fresh player URL", async () => {
+    const { host, player } = await mountPlayer();
+
+    act(() => {
+      player.dispatchEvent(
+        new CustomEvent("error", {
+          detail: { message: "Composition timeline not found after 8s" },
+        }),
+      );
+    });
+
+    expect(host.querySelector('[data-testid="composition-preview-error"]')).not.toBeNull();
+    const retry = Array.from(host.querySelectorAll("button")).find(
+      (button) => button.textContent === "Retry preview",
+    );
+    if (!retry) throw new Error("retry action did not render");
+
+    act(() => retry.click());
+
+    const retryUrl = new URL(player.getAttribute("src") ?? "", window.location.origin);
+    expect(retryUrl.searchParams.get("_hfStudioRetry")).toBe("1");
+    expect(host.querySelector('[data-testid="composition-preview-error"]')).toBeNull();
+  });
+});
 
 describe("composition loading overlay", () => {
   it("shows while the composition is loading", () => {
@@ -13,10 +152,7 @@ describe("composition loading overlay", () => {
   });
 
   it("keeps the asset overlay up while media is still buffering", () => {
-    const iframe = document.createElement("iframe");
-    document.body.appendChild(iframe);
-    const audio = iframe.contentDocument?.createElement("audio");
-    expect(audio).toBeDefined();
+    const { audio, iframe } = createAudioIframe();
     Object.defineProperty(audio, "readyState", {
       value: 0,
       configurable: true,
@@ -25,7 +161,6 @@ describe("composition loading overlay", () => {
       value: 2,
       configurable: true,
     });
-    iframe.contentDocument?.body.appendChild(audio!);
 
     expect(hasUnloadedAssets(iframe, false)).toBe(true);
 
@@ -33,10 +168,7 @@ describe("composition loading overlay", () => {
   });
 
   it("does not keep the asset overlay stuck on failed media sources", () => {
-    const iframe = document.createElement("iframe");
-    document.body.appendChild(iframe);
-    const audio = iframe.contentDocument?.createElement("audio");
-    expect(audio).toBeDefined();
+    const { audio, iframe } = createAudioIframe();
     Object.defineProperty(audio, "error", {
       value: { code: 4, message: "format error" },
       configurable: true,
@@ -49,7 +181,6 @@ describe("composition loading overlay", () => {
       value: 3,
       configurable: true,
     });
-    iframe.contentDocument?.body.appendChild(audio!);
 
     expect(hasUnloadedAssets(iframe, false)).toBe(false);
 

package/src/player/components/Player.tsx

@@ -38,11 +38,19 @@ function getShaderTransitionLoading(event: Event): boolean | null {
 }
 
 const COMPOSITION_LOADING_OVERLAY_DELAY_MS = 400;
+const DEFAULT_PREVIEW_ERROR = "The composition preview did not become ready.";
 
 export function shouldShowCompositionLoadingOverlay(compositionLoading: boolean): boolean {
   return compositionLoading;
 }
 
+export function readPreviewErrorMessage(event: Event): string {
+  if (!(event instanceof CustomEvent) || !isRecord(event.detail)) return DEFAULT_PREVIEW_ERROR;
+  return typeof event.detail.message === "string" && event.detail.message.trim()
+    ? event.detail.message
+    : DEFAULT_PREVIEW_ERROR;
+}
+
 function enableInteractiveIframe(player: HyperframesPlayerElement): void {
   const root = player.shadowRoot;
   if (!root) return;
@@ -122,12 +130,15 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
     const loadCountRef = useRef(0);
     const assetPollRef = useRef<ReturnType<typeof setInterval> | null>(null);
     const assetFadeRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const retryPreviewRef = useRef<(() => void) | null>(null);
+    const retryCountRef = useRef(0);
     const [assetsLoading, setAssetsLoading] = useState(false);
     const [assetOverlayVisible, setAssetOverlayVisible] = useState(false);
     const [assetOverlayFading, setAssetOverlayFading] = useState(false);
     const [shaderTransitionLoading, setShaderTransitionLoading] = useState(false);
     const [compositionLoading, setCompositionLoading] = useState(true);
     const [compositionOverlayDeferred, setCompositionOverlayDeferred] = useState(true);
+    const [previewError, setPreviewError] = useState<string | null>(null);
 
     // eslint-disable-next-line no-restricted-syntax
     useEffect(() => {
@@ -161,62 +172,32 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         );
         applyPreviewVariablesToUrl(srcUrl);
         const src = srcUrl.pathname + srcUrl.search;
-        player.setAttribute("shader-capture-scale", "1");
-        player.setAttribute("shader-loading", "player");
-        player.setAttribute("src", src);
-        player.setAttribute("width", String(portrait ? 1080 : 1920));
-        player.setAttribute("height", String(portrait ? 1920 : 1080));
-        player.style.width = "100%";
-        player.style.height = "100%";
-        player.style.display = "block";
-        player.style.background = "transparent";
-        container.appendChild(player);
-
-        // Inject pasteboard shadow: let the shadow around the canvas bleed
-        // into the surrounding pasteboard area (overflow: visible on the container)
-        // and add a subtle outline + drop-shadow so the canvas boundary reads
-        // against the gray pasteboard, consistent with professional editors.
-        if (player.shadowRoot) {
-          const pasteboardStyle = document.createElement("style");
-          pasteboardStyle.textContent =
-            ".hfp-container{overflow:visible}" +
-            ".hfp-iframe{box-shadow:0 0 0 1px rgba(255,255,255,0.08),0 4px 32px rgba(0,0,0,.7)}";
-          player.shadowRoot.appendChild(pasteboardStyle);
-        }
-
-        enableInteractiveIframe(player);
-
-        // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
+        const retryPreview = () => {
+          retryCountRef.current += 1;
+          const retryUrl = new URL(src, window.location.origin);
+          retryUrl.searchParams.set("_hfStudioRetry", String(retryCountRef.current));
+          setPreviewError(null);
+          setCompositionLoading(true);
+          player.setAttribute("src", retryUrl.pathname + retryUrl.search);
+        };
+        retryPreviewRef.current = retryPreview;
         const iframe = player.iframeElement;
-        if (typeof ref === "function") {
-          ref(iframe);
-        } else if (ref) {
-          (ref as React.MutableRefObject<HTMLIFrameElement | null>).current = iframe;
-        }
-
-        // Prevent the web component's built-in click-to-toggle behavior.
-        // The studio manages playback exclusively via useTimelinePlayer.
         const preventToggle = (e: Event) => e.stopImmediatePropagation();
-        player.addEventListener("click", preventToggle, { capture: true });
-
         const handleShaderTransitionState = (event: Event) => {
           const loading = getShaderTransitionLoading(event);
           if (loading !== null) setShaderTransitionLoading(loading);
         };
-        player.addEventListener("shadertransitionstate", handleShaderTransitionState);
-
         const handleReady = () => {
+          setPreviewError(null);
           setCompositionLoading(false);
         };
-        const handleError = () => {
+        const handleError = (event: Event) => {
+          setPreviewError(readPreviewErrorMessage(event));
           setCompositionLoading(false);
         };
-        player.addEventListener("ready", handleReady);
-        player.addEventListener("error", handleError);
-
-        // Forward the iframe's native load event to the studio's onIframeLoad.
         const handleLoad = () => {
           loadCountRef.current++;
+          setPreviewError(null);
           setShaderTransitionLoading(false);
           setCompositionLoading(true);
           // Reveal animation on reload (hot-reload, composition switch)
@@ -264,7 +245,47 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             setAssetsLoading(false);
           }
         };
+
+        // Attach lifecycle listeners before assigning src or connecting the
+        // custom element. A warm local iframe can otherwise finish before
+        // Studio observes its load and never initialize the timeline.
         iframe.addEventListener("load", handleLoad);
+        player.addEventListener("click", preventToggle, { capture: true });
+        player.addEventListener("shadertransitionstate", handleShaderTransitionState);
+        player.addEventListener("ready", handleReady);
+        player.addEventListener("error", handleError);
+
+        // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
+        if (typeof ref === "function") {
+          ref(iframe);
+        } else if (ref) {
+          (ref as React.MutableRefObject<HTMLIFrameElement | null>).current = iframe;
+        }
+
+        player.setAttribute("shader-capture-scale", "1");
+        player.setAttribute("shader-loading", "player");
+        player.setAttribute("width", String(portrait ? 1080 : 1920));
+        player.setAttribute("height", String(portrait ? 1920 : 1080));
+        player.style.width = "100%";
+        player.style.height = "100%";
+        player.style.display = "block";
+        player.style.background = "transparent";
+        player.setAttribute("src", src);
+        container.appendChild(player);
+
+        // Inject pasteboard shadow: let the shadow around the canvas bleed
+        // into the surrounding pasteboard area (overflow: visible on the container)
+        // and add a subtle outline + drop-shadow so the canvas boundary reads
+        // against the gray pasteboard, consistent with professional editors.
+        if (player.shadowRoot) {
+          const pasteboardStyle = document.createElement("style");
+          pasteboardStyle.textContent =
+            ".hfp-container{overflow:visible}" +
+            ".hfp-iframe{box-shadow:0 0 0 1px rgba(255,255,255,0.08),0 4px 32px rgba(0,0,0,.7)}";
+          player.shadowRoot.appendChild(pasteboardStyle);
+        }
+
+        enableInteractiveIframe(player);
 
         cleanup = () => {
           iframe.removeEventListener("load", handleLoad);
@@ -275,6 +296,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           if (assetPollRef.current) clearInterval(assetPollRef.current);
           assetPollRef.current = null;
           container.removeChild(player);
+          if (retryPreviewRef.current === retryPreview) retryPreviewRef.current = null;
           // Clear the forwarded ref only if it still points to THIS iframe.
           // During crossfade refreshes the retiring Player unmounts after the
           // new Player has already assigned its iframe to the same ref — blindly
@@ -381,6 +403,25 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             />
           </div>
         )}
+        {previewError && (
+          <div
+            className="absolute inset-0 z-40 flex items-center justify-center bg-black/90 px-6 text-center"
+            data-hyperframes-ignore=""
+            data-testid="composition-preview-error"
+          >
+            <div className="max-w-sm">
+              <p className="text-sm font-semibold text-white">Preview failed to load</p>
+              <p className="mt-1 text-xs text-neutral-400">{previewError}</p>
+              <button
+                type="button"
+                className="mt-4 rounded-md bg-white px-3 py-1.5 text-xs font-semibold text-black transition-colors hover:bg-neutral-200"
+                onClick={() => retryPreviewRef.current?.()}
+              >
+                Retry preview
+              </button>
+            </div>
+          </div>
+        )}
       </div>
     );
   },