@hyperframes/studio 0.5.7 → 0.6.0-alpha.10

package/src/player/components/Player.tsx

@@ -10,13 +10,19 @@ interface PlayerProps {
   projectId?: string;
   directUrl?: string;
   onLoad: () => void;
+  onCompositionLoadingChange?: (loading: boolean) => void;
   portrait?: boolean;
+  style?: React.CSSProperties;
+  suppressLoadingOverlay?: boolean;
 }
 
 interface HyperframesPlayerElement extends HTMLElement {
   iframeElement: HTMLIFrameElement;
 }
 
+const MEDIA_HAVE_FUTURE_DATA = 3;
+const MEDIA_NETWORK_NO_SOURCE = 3;
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
@@ -30,6 +36,26 @@ function getShaderTransitionLoading(event: Event): boolean | null {
   return state.loading === true && state.ready !== true;
 }
 
+export function shouldShowCompositionLoadingOverlay(compositionLoading: boolean): boolean {
+  return compositionLoading;
+}
+
+function enableInteractiveIframe(player: HyperframesPlayerElement): void {
+  const root = player.shadowRoot;
+  if (!root) return;
+
+  const container = root.querySelector<HTMLElement>(".hfp-container");
+  const iframe = root.querySelector<HTMLIFrameElement>(".hfp-iframe");
+
+  container?.style.setProperty("pointer-events", "auto");
+  iframe?.style.setProperty("pointer-events", "auto");
+}
+
+function isPreviewMediaElement(el: Element): el is HTMLMediaElement {
+  const tagName = el.tagName.toLowerCase();
+  return tagName === "video" || tagName === "audio";
+}
+
 // Assets are considered ready when every `<video>`/`<audio>` has enough data
 // to play through without buffering, and every registered Lottie animation has
 // finished loading.
@@ -38,14 +64,19 @@ function getShaderTransitionLoading(event: Event): boolean | null {
 // races so a brief access failure (e.g. an iframe that just swapped src)
 // doesn't flicker the overlay state — we keep showing whatever was most
 // recently true.
-function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): boolean {
+export function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): boolean {
   try {
     const win = iframe.contentWindow as unknown as (Window & { __hfLottie?: unknown[] }) | null;
     const doc = iframe.contentDocument;
     if (!win || !doc) return lastResult;
 
     for (const el of doc.querySelectorAll("video, audio")) {
-      if (el instanceof HTMLMediaElement && el.readyState < HTMLMediaElement.HAVE_FUTURE_DATA) {
+      if (
+        isPreviewMediaElement(el) &&
+        !el.error &&
+        el.networkState !== MEDIA_NETWORK_NO_SOURCE &&
+        el.readyState < MEDIA_HAVE_FUTURE_DATA
+      ) {
         return true;
       }
     }
@@ -72,7 +103,18 @@ function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): bool
  * timeline probing, and DOM inspection.
  */
 export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
-  ({ projectId, directUrl, onLoad, portrait }, ref) => {
+  (
+    {
+      projectId,
+      directUrl,
+      onLoad,
+      onCompositionLoadingChange,
+      portrait,
+      style,
+      suppressLoadingOverlay,
+    },
+    ref,
+  ) => {
     const containerRef = useRef<HTMLDivElement>(null);
     const loadCountRef = useRef(0);
     const assetPollRef = useRef<ReturnType<typeof setInterval> | null>(null);
@@ -81,6 +123,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
     const [assetOverlayVisible, setAssetOverlayVisible] = useState(false);
     const [assetOverlayFading, setAssetOverlayFading] = useState(false);
     const [shaderTransitionLoading, setShaderTransitionLoading] = useState(false);
+    const [compositionLoading, setCompositionLoading] = useState(true);
 
     useMountEffect(() => {
       const container = containerRef.current;
@@ -105,6 +148,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         player.style.height = "100%";
         player.style.display = "block";
         container.appendChild(player);
+        enableInteractiveIframe(player);
 
         // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
         const iframe = player.iframeElement;
@@ -125,10 +169,20 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         };
         player.addEventListener("shadertransitionstate", handleShaderTransitionState);
 
+        const handleReady = () => {
+          setCompositionLoading(false);
+        };
+        const handleError = () => {
+          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++;
           setShaderTransitionLoading(false);
+          setCompositionLoading(true);
           // Reveal animation on reload (hot-reload, composition switch)
           if (loadCountRef.current > 1) {
             container.classList.remove("preview-revealing");
@@ -179,6 +233,8 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           iframe.removeEventListener("load", handleLoad);
           player.removeEventListener("click", preventToggle, { capture: true });
           player.removeEventListener("shadertransitionstate", handleShaderTransitionState);
+          player.removeEventListener("ready", handleReady);
+          player.removeEventListener("error", handleError);
           if (assetPollRef.current) clearInterval(assetPollRef.current);
           assetPollRef.current = null;
           container.removeChild(player);
@@ -224,11 +280,38 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       };
     }, [assetsLoading]);
 
-    const showAssetOverlay = assetOverlayVisible && !shaderTransitionLoading;
+    const showCompositionOverlay =
+      !suppressLoadingOverlay && shouldShowCompositionLoadingOverlay(compositionLoading);
+    const showAssetOverlay =
+      assetOverlayVisible && !shaderTransitionLoading && !showCompositionOverlay;
+
+    useEffect(() => {
+      onCompositionLoadingChange?.(showCompositionOverlay || showAssetOverlay);
+    }, [onCompositionLoadingChange, showCompositionOverlay, showAssetOverlay]);
 
     return (
-      <div className="relative w-full h-full max-w-full max-h-full overflow-hidden bg-black flex items-center justify-center">
+      <div
+        className="relative w-full h-full max-w-full max-h-full overflow-hidden bg-black flex items-center justify-center"
+        style={style}
+      >
         <div ref={containerRef} className="w-full h-full" />
+        {showCompositionOverlay && (
+          <div
+            className="absolute inset-0 bg-black flex items-center justify-center z-30 select-none"
+            data-hyperframes-ignore=""
+            data-testid="composition-loading-overlay"
+            draggable={false}
+            onDragStart={(event) => event.preventDefault()}
+            onMouseDown={(event) => event.preventDefault()}
+            onPointerDown={(event) => event.preventDefault()}
+          >
+            <HyperframesLoader
+              title="Loading composition"
+              detail="Preparing the Studio preview."
+              size={56}
+            />
+          </div>
+        )}
         {showAssetOverlay && (
           <div
             className="absolute inset-0 bg-black flex items-center justify-center z-20 select-none"

package/src/player/components/PlayerControls.tsx

@@ -26,11 +26,13 @@ export function resolveSeekPercent(clientX: number, rectLeft: number, rectWidth:
 interface PlayerControlsProps {
   onTogglePlay: () => void;
   onSeek: (time: number) => void;
+  disabled?: boolean;
 }
 
 export const PlayerControls = memo(function PlayerControls({
   onTogglePlay,
   onSeek,
+  disabled = false,
 }: PlayerControlsProps) {
   // Subscribe to only the fields we render — each selector prevents cascading re-renders
   const isPlaying = usePlayerStore((s) => s.isPlaying);
@@ -57,6 +59,7 @@ export const PlayerControls = memo(function PlayerControls({
 
   const durationRef = useRef(duration);
   durationRef.current = duration;
+  const controlsDisabled = disabled || !timelineReady;
   useMountEffect(() => {
     const updateProgress = (t: number) => {
       currentTimeRef.current = t;
@@ -115,6 +118,7 @@ export const PlayerControls = memo(function PlayerControls({
 
   const seekFromClientX = useCallback(
     (clientX: number) => {
+      if (disabled) return;
       const bar = seekBarRef.current;
       if (!bar || duration <= 0) return;
       const rect = bar.getBoundingClientRect();
@@ -125,7 +129,7 @@ export const PlayerControls = memo(function PlayerControls({
       if (progressThumbRef.current) progressThumbRef.current.style.left = `${pct}%`;
       onSeek(percent * duration);
     },
-    [duration, onSeek],
+    [disabled, duration, onSeek],
   );
 
   const handlePointerDown = useCallback(
@@ -204,7 +208,7 @@ export const PlayerControls = memo(function PlayerControls({
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
-      if (!timelineReady || duration <= 0) return;
+      if (disabled || !timelineReady || duration <= 0) return;
       const step = e.shiftKey ? 10 : 1;
       if (e.key === "ArrowLeft") {
         e.preventDefault();
@@ -214,14 +218,15 @@ export const PlayerControls = memo(function PlayerControls({
         onSeek(Math.min(duration, stepFrameTime(currentTimeRef.current, step)));
       }
     },
-    [timelineReady, duration, onSeek],
+    [disabled, timelineReady, duration, onSeek],
   );
 
   const commitJumpFrame = useCallback(() => {
+    if (disabled) return;
     const frame = Number.parseInt(jumpFrame, 10);
     if (!Number.isFinite(frame) || duration <= 0) return;
     onSeek(Math.min(duration, frameToSeconds(Math.max(0, frame))));
-  }, [duration, jumpFrame, onSeek]);
+  }, [disabled, duration, jumpFrame, onSeek]);
 
   const handleJumpSubmit = useCallback(
     (e: React.FormEvent) => {
@@ -243,6 +248,7 @@ export const PlayerControls = memo(function PlayerControls({
   return (
     <div
       className="px-4 py-2 flex flex-wrap items-center gap-x-2 gap-y-1"
+      aria-disabled={disabled || undefined}
       style={{
         borderTop: "1px solid rgba(255,255,255,0.04)",
         // Add iOS safe-area inset so Safari's bottom URL bar doesn't occlude
@@ -256,7 +262,7 @@ export const PlayerControls = memo(function PlayerControls({
         type="button"
         aria-label={isPlaying ? "Pause" : "Play"}
         onClick={onTogglePlay}
-        disabled={!timelineReady}
+        disabled={controlsDisabled}
         className="flex-shrink-0 w-8 h-8 flex items-center justify-center rounded-lg disabled:opacity-30 disabled:pointer-events-none transition-colors"
         style={{ background: "rgba(255,255,255,0.06)" }}
       >
@@ -293,12 +299,15 @@ export const PlayerControls = memo(function PlayerControls({
           (sliderRef as React.MutableRefObject<HTMLDivElement | null>).current = el;
         }}
         role="slider"
-        tabIndex={0}
+        tabIndex={disabled ? -1 : 0}
         aria-label="Seek"
+        aria-disabled={disabled || undefined}
         aria-valuemin={0}
         aria-valuemax={Math.round(duration)}
         aria-valuenow={0}
-        className="min-w-[96px] flex-1 h-6 flex items-center cursor-pointer group"
+        className={`min-w-[96px] flex-1 h-6 flex items-center group ${
+          disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer"
+        }`}
         // `touch-action: none` tells the browser we're handling every
         // pointer gesture on this element ourselves. Without it, iOS
         // Safari consumes horizontal swipes for its own swipe-back-to-
@@ -334,6 +343,7 @@ export const PlayerControls = memo(function PlayerControls({
         <button
           type="button"
           onClick={() => setShowSpeedMenu((v) => !v)}
+          disabled={disabled}
           className="w-10 px-2 py-1 rounded-md text-[10px] font-mono tabular-nums transition-colors"
           style={{ color: "#71717A", background: "rgba(255,255,255,0.04)" }}
         >
@@ -374,6 +384,7 @@ export const PlayerControls = memo(function PlayerControls({
       <button
         type="button"
         onClick={() => setLoopEnabled(!loopEnabled)}
+        disabled={disabled}
         className={`h-7 w-14 rounded-md border px-2 text-[10px] font-medium transition-colors ${
           loopEnabled
             ? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
@@ -389,6 +400,7 @@ export const PlayerControls = memo(function PlayerControls({
       <button
         type="button"
         onClick={() => setTimeDisplayMode((mode) => (mode === "time" ? "frame" : "time"))}
+        disabled={disabled}
         className="h-7 w-14 rounded-md border border-neutral-700 px-2 text-[10px] font-mono text-neutral-300 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
         title="Toggle time/frame display"
         aria-label="Toggle time and frame display"
@@ -403,6 +415,7 @@ export const PlayerControls = memo(function PlayerControls({
         <input
           value={jumpFrame}
           onChange={(e) => setJumpFrame(e.target.value)}
+          disabled={disabled}
           inputMode="numeric"
           pattern="[0-9]*"
           aria-label="Jump to frame"

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

@@ -8,9 +8,12 @@ import {
   getTimelinePlayheadLeft,
   getTimelineScrollLeftForZoomAnchor,
   getTimelineScrollLeftForZoomTransition,
+  shouldShowTimelineShortcutHint,
   shouldHandleTimelineDeleteKey,
   shouldAutoScrollTimeline,
 } from "./Timeline";
+import { TIMELINE_CLIP_CONTROL_Z_INDEX } from "./TimelineClip";
+import { COMPOSITION_THUMBNAIL_LABEL_Z_INDEX } from "./CompositionThumbnail";
 import { formatTime } from "../lib/time";
 
 describe("generateTicks", () => {
@@ -163,6 +166,12 @@ describe("shouldAutoScrollTimeline", () => {
   });
 });
 
+describe("timeline clip controls", () => {
+  it("renders layer controls above composition thumbnail chrome", () => {
+    expect(TIMELINE_CLIP_CONTROL_Z_INDEX).toBeGreaterThan(COMPOSITION_THUMBNAIL_LABEL_Z_INDEX);
+  });
+});
+
 describe("getTimelineScrollLeftForZoomTransition", () => {
   it("resets horizontal scroll when switching from manual zoom back to fit", () => {
     expect(getTimelineScrollLeftForZoomTransition("manual", "fit", 480)).toBe(0);
@@ -237,6 +246,17 @@ describe("getTimelineCanvasHeight", () => {
   });
 });
 
+describe("shouldShowTimelineShortcutHint", () => {
+  it("shows the hint when the timeline does not vertically overflow", () => {
+    expect(shouldShowTimelineShortcutHint(220, 220)).toBe(true);
+    expect(shouldShowTimelineShortcutHint(220.5, 220)).toBe(true);
+  });
+
+  it("hides the hint when timeline tracks need vertical scrolling", () => {
+    expect(shouldShowTimelineShortcutHint(221.5, 220)).toBe(false);
+  });
+});
+
 describe("shouldHandleTimelineDeleteKey", () => {
   it("handles Delete and Backspace when focus is not in an editor", () => {
     expect(shouldHandleTimelineDeleteKey({ key: "Delete" })).toBe(true);