Skip to content

Write HTML. Render video. Built for agents.

22.9 KB
Raw Blame
import { buildProjectApiPath } from "../../utils/projectRouting";
import { forwardRef, useEffect, useRef, useState } from "react";
import { isLottieAnimationLoaded } from "@hyperframes/core/runtime/lottie-readiness";
import { useMountEffect } from "../../hooks/useMountEffect";
import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
import { HyperframesLoader } from "../../components/ui";
import { usePlayerStore } from "../store/playerStore";
import { announcePreviewDocumentLoaded } from "../sceneSwap";
import type { IframeWindow } from "../lib/playbackTypes";
// Importing "@hyperframes/player" registers a class extending HTMLElement at
// module load, which throws under SSR, hence the dynamic import behind a
// `typeof window` guard. Kicking it here rather than in the mount effect puts
// the chunk request in flight before the shell's first layout. Clearing the memo
// on rejection stops one failure poisoning every later mount; the browser's
// module map still caches a failed fetch, so recovery is a page reload.
let playerModule: Promise<unknown> | null = null;

export function loadPlayerModule(): Promise<unknown> {
  playerModule ??= import("@hyperframes/player").catch((err: unknown) => {
    playerModule = null;
    throw err;
  });
  return playerModule;
}

if (typeof window !== "undefined") void loadPlayerModule().catch(() => {});

interface PlayerProps {
  projectId?: string;
  directUrl?: string;
  onLoad: () => void;
  /** Fires once the loaded document is painted and every loader (shader, assets) has cleared. */
  onReadyToShowChange?: (ready: boolean) => void;
  onPreviewError?: (message: string) => void;
  onCompositionLoadingChange?: (loading: boolean) => void;
  onPainted?: (details: { iframe: HTMLIFrameElement; startedAt: number; loadId: number }) => void;
  portrait?: boolean;
  style?: React.CSSProperties;
  suppressLoadingOverlay?: boolean;
  noLoadTimeout?: boolean;
}

interface HyperframesPlayerElement extends HTMLElement {
  iframeElement: HTMLIFrameElement;
  ready?: boolean;
  painted?: boolean;
}

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;
}

function getShaderTransitionLoading(event: Event): boolean | null {
  if (!(event instanceof CustomEvent)) return null;
  const detail: unknown = event.detail;
  if (!isRecord(detail)) return null;
  const state = detail.state;
  if (!isRecord(state)) return null;
  return state.loading === true && state.ready !== true;
}

const COMPOSITION_LOADING_OVERLAY_DELAY_MS = 400;
const PREVIEW_BOOT_DEADLINE_MS = 5000;
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;

  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.
//
// Returns whichever value was returned last on cross-origin / transient DOM
// 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.
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 (
        isPreviewMediaElement(el) &&
        !el.error &&
        el.networkState !== MEDIA_NETWORK_NO_SOURCE &&
        el.readyState < MEDIA_HAVE_FUTURE_DATA
      ) {
        return true;
      }
    }

    const lotties = win.__hfLottie;
    if (lotties?.length) {
      for (const anim of lotties) {
        if (!isLottieAnimationLoaded(anim)) return true;
      }
    }

    return false;
  } catch {
    return lastResult;
  }
}

const runtimeBootedIn = (iframe: HTMLIFrameElement) =>
  (iframe.contentWindow as IframeWindow | null)?.__playerReady === true;

/**
 * Renders a composition preview using the <hyperframes-player> web component.
 *
 * The web component handles iframe scaling, dimension detection, and
 * ResizeObserver internally. This wrapper bridges its inner iframe to the
 * forwarded ref so useTimelinePlayer can access it for clip manifest parsing,
 * timeline probing, and DOM inspection.
 */
export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
  (
    {
      projectId,
      directUrl,
      onLoad,
      onReadyToShowChange,
      onPreviewError,
      onCompositionLoadingChange,
      onPainted,
      portrait,
      style,
      suppressLoadingOverlay,
      noLoadTimeout,
    },
    ref,
  ) => {
    const containerRef = useRef<HTMLDivElement>(null);
    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 loadStartedAtRef = useRef(0);
    const loadIdRef = useRef(0);
    const retryCountRef = useRef(0);
    // Read at call time: this element outlives its first props (a shadow preview is
    // promoted in place), so mount-time closures would go stale.
    const onLoadRef = useRef(onLoad);
    onLoadRef.current = onLoad;
    const onReadyToShowChangeRef = useRef(onReadyToShowChange);
    onReadyToShowChangeRef.current = onReadyToShowChange;
    const onPreviewErrorRef = useRef(onPreviewError);
    onPreviewErrorRef.current = onPreviewError;
    const [loaded, setLoaded] = useState(false);
    const [assetsLoading, setAssetsLoading] = useState(false);
    const [assetOverlayVisible, setAssetOverlayVisible] = useState(false);
    const [assetOverlayFading, setAssetOverlayFading] = useState(false);
    const [assetWaitLong, setAssetWaitLong] = useState(false);
    const [shaderTransitionLoading, setShaderTransitionLoading] = useState(false);
    const [compositionLoading, setCompositionLoading] = useState(true);
    const [painted, setPainted] = useState(false);
    const [compositionOverlayDeferred, setCompositionOverlayDeferred] = useState(true);
    const [previewError, setPreviewError] = useState<string | null>(null);

    // eslint-disable-next-line no-restricted-syntax
    useEffect(() => {
      if (!compositionLoading) {
        setCompositionOverlayDeferred(true);
        return;
      }
      const timer = setTimeout(
        () => setCompositionOverlayDeferred(false),
        COMPOSITION_LOADING_OVERLAY_DELAY_MS,
      );
      return () => clearTimeout(timer);
    }, [compositionLoading]);

    useMountEffect(() => {
      const container = containerRef.current;
      if (!container) return;

      const previewSource =
        directUrl || (projectId ? buildProjectApiPath(projectId, "/preview") : null);
      if (!previewSource) return;

      let canceled = false;
      let cleanup: (() => void) | undefined;

      void loadPlayerModule().then(() => {
        if (canceled) return;

        // Create the web component imperatively to avoid JSX custom-element typing.
        const player = document.createElement("hyperframes-player") as HyperframesPlayerElement;
        const srcUrl = new URL(previewSource, window.location.origin);
        applyPreviewVariablesToUrl(srcUrl);
        const src = srcUrl.pathname + srcUrl.search;
        const retryPreview = () => {
          retryCountRef.current += 1;
          const retryUrl = new URL(src, window.location.origin);
          retryUrl.searchParams.set("_hfStudioRetry", String(retryCountRef.current));
          setPreviewError(null);
          setCompositionLoading(true);
          loadStartedAtRef.current = performance.now();
          loadIdRef.current += 1;
          player.removeAttribute("no-load-timeout");
          player.setAttribute("src", retryUrl.pathname + retryUrl.search);
        };
        retryPreviewRef.current = retryPreview;
        const iframe = player.iframeElement;
        const preventToggle = (e: Event) => e.stopImmediatePropagation();
        const handleShaderTransitionState = (event: Event) => {
          const loading = getShaderTransitionLoading(event);
          if (loading !== null) setShaderTransitionLoading(loading);
        };
        let loadedDocument: Document | null = null;
        const handleReady = () => {
          setPreviewError(null);
          setCompositionLoading(false);
          if (iframe.contentDocument && runtimeBootedIn(iframe)) handleLoad();
        };
        const handlePainted = () => {
          setPainted(true);
          onPainted?.({ iframe, startedAt: loadStartedAtRef.current, loadId: loadIdRef.current });
        };
        const handleError = (event: Event) => {
          const message = readPreviewErrorMessage(event);
          onPreviewErrorRef.current?.(message);
          setPreviewError(message);
          setCompositionLoading(false);
        };
        const handleLoad = () => {
          const doc = iframe.contentDocument;
          if (doc && doc === loadedDocument) return;
          loadedDocument = doc;
          loadCountRef.current++;
          setLoaded(true);
          setPreviewError(null);
          setShaderTransitionLoading(false);
          setCompositionLoading(!player.ready);
          setPainted(Boolean(player.painted));
          // Reveal animation on reload (hot-reload, composition switch)
          if (loadCountRef.current > 1) {
            container.classList.remove("preview-revealing");
            void container.offsetWidth;
            container.classList.add("preview-revealing");
            const onEnd = () => container.classList.remove("preview-revealing");
            container.addEventListener("animationend", onEnd, { once: true });
          }
          onLoadRef.current();
          announcePreviewDocumentLoaded(iframe);

          // Show a loading overlay until every `<video>`/`<audio>` and Lottie
          // asset is ready. Without this users can click play before audio has
          // buffered — the runtime is resilient (queued play() resolves once
          // data arrives), but the overlay communicates why the first frame
          // or first audio beat may lag.
          //
          // Skip the overlay on subsequent loads (content refreshes via
          // refreshPlayer). The browser has already cached the assets from
          // the first load, so they resolve near-instantly and the overlay
          // just creates a disruptive flash.
          //
          // Poll with a 10 s safety cap (100 ticks × 100 ms). If the cap
          // trips we hide the overlay so the UI doesn't appear stuck forever,
          // but we log a debug warning so the case is diagnosable — a long
          // cold video or a broken asset can legitimately exceed 10 s on a
          // slow network.
          if (assetPollRef.current) clearInterval(assetPollRef.current);
          const isContentRefresh = loadCountRef.current > 1;
          let lastUnloaded = isContentRefresh ? false : hasUnloadedAssets(iframe, false);
          if (lastUnloaded) {
            setAssetsLoading(true);
            let attempts = 0;
            assetPollRef.current = setInterval(() => {
              attempts += 1;
              lastUnloaded = hasUnloadedAssets(iframe, lastUnloaded);
              if (!lastUnloaded || attempts > 100) {
                if (lastUnloaded && attempts > 100) {
                  console.debug(
                    "[studio] asset readiness poll hit the 10s cap, continuing with unloaded assets",
                  );
                }
                if (assetPollRef.current) clearInterval(assetPollRef.current);
                assetPollRef.current = null;
                setAssetsLoading(false);
              }
            }, 100);
          } else {
            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("painted", handlePainted);
        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("low-power-idle", "");
        player.toggleAttribute("no-load-timeout", noLoadTimeout === true);
        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";
        loadStartedAtRef.current = performance.now();
        loadIdRef.current += 1;
        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);
          player.removeEventListener("click", preventToggle, { capture: true });
          player.removeEventListener("shadertransitionstate", handleShaderTransitionState);
          player.removeEventListener("ready", handleReady);
          player.removeEventListener("painted", handlePainted);
          player.removeEventListener("error", handleError);
          if (assetPollRef.current) clearInterval(assetPollRef.current);
          assetPollRef.current = null;
          // `remove()` rather than `container.removeChild(player)`: by the time
          // this cleanup runs the element may already be detached — React can
          // re-render the container, a crossfade refresh can swap it, or a
          // translation/extension can reparent it. `removeChild` then throws
          // NotFoundError, which the error boundary turns into a full-screen
          // "Something went wrong". `remove()` is a no-op when already detached.
          player.remove();
          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
          // nulling it would break seeking in the new Player.
          // Callback refs are skipped — we can't read back the current value to
          // guard against clobbering a newer assignment. The mutable-ref branch
          // (the only path used today) is guarded by identity check.
          if (typeof ref === "function") {
            // no-op: can't safely guard callback refs
          } else if (ref) {
            const mutableRef = ref as React.MutableRefObject<HTMLIFrameElement | null>;
            if (mutableRef.current === iframe) {
              mutableRef.current = null;
            }
          }
        };
      });

      return () => {
        canceled = true;
        cleanup?.();
      };
    });

    // Surface a "Continue anyway" escape hatch once the asset wait drags on.
    // eslint-disable-next-line no-restricted-syntax
    useEffect(() => {
      if (!assetsLoading) {
        setAssetWaitLong(false);
        return;
      }
      const timer = setTimeout(() => setAssetWaitLong(true), 3000);
      return () => clearTimeout(timer);
    }, [assetsLoading]);

    useEffect(() => {
      if (assetFadeRef.current) {
        clearTimeout(assetFadeRef.current);
        assetFadeRef.current = null;
      }

      if (assetsLoading) {
        setAssetOverlayVisible(true);
        setAssetOverlayFading(false);
        return;
      }

      setAssetOverlayFading(true);
      assetFadeRef.current = setTimeout(() => {
        setAssetOverlayVisible(false);
        setAssetOverlayFading(false);
        assetFadeRef.current = null;
      }, 240);

      return () => {
        if (assetFadeRef.current) {
          clearTimeout(assetFadeRef.current);
          assetFadeRef.current = null;
        }
      };
    }, [assetsLoading]);

    const handleContinueAnyway = () => {
      if (assetPollRef.current) {
        clearInterval(assetPollRef.current);
        assetPollRef.current = null;
      }
      setAssetsLoading(false);
    };

    const firstFrameShown =
      loaded && painted && !compositionLoading && !shaderTransitionLoading && !previewError;
    const readyToShow = firstFrameShown && !assetsLoading;
    // Work waiting on the boot starts at the first frame, while media still buffers.
    useEffect(() => {
      if (firstFrameShown) usePlayerStore.getState().markPreviewBooted();
    }, [firstFrameShown]);
    // `painted` means the player's own loader has finished fading; two frames of grace on top.
    useEffect(() => {
      if (!readyToShow) {
        onReadyToShowChangeRef.current?.(false);
        return;
      }
      let second = 0;
      const first = requestAnimationFrame(() => {
        second = requestAnimationFrame(() => onReadyToShowChangeRef.current?.(true));
      });
      return () => {
        cancelAnimationFrame(first);
        cancelAnimationFrame(second);
      };
    }, [readyToShow]);

    useEffect(() => {
      if (previewError) usePlayerStore.getState().markPreviewBooted();
    }, [previewError]);

    useEffect(() => {
      const timer = setTimeout(
        () => usePlayerStore.getState().markPreviewBooted(),
        PREVIEW_BOOT_DEADLINE_MS,
      );
      return () => clearTimeout(timer);
    }, [projectId]);

    const showCompositionOverlay =
      !suppressLoadingOverlay &&
      !compositionOverlayDeferred &&
      shouldShowCompositionLoadingOverlay(compositionLoading);
    const showAssetOverlay =
      assetOverlayVisible && !shaderTransitionLoading && !showCompositionOverlay && !previewError;

    useEffect(() => {
      onCompositionLoadingChange?.(showCompositionOverlay || showAssetOverlay);
    }, [onCompositionLoadingChange, showCompositionOverlay, showAssetOverlay]);

    return (
      <div
        className="relative w-full h-full max-w-full max-h-full overflow-hidden 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"
            data-hyperframes-ignore=""
            draggable={false}
            style={{
              opacity: assetOverlayFading ? 0 : 1,
              pointerEvents: assetOverlayFading ? "none" : "auto",
              transition: "opacity 180ms ease-in",
            }}
            onDragStart={(event) => event.preventDefault()}
            onMouseDown={(event) => event.preventDefault()}
          >
            <div className="flex flex-col items-center gap-3">
              <HyperframesLoader
                title="Preparing preview assets"
                detail="Waiting for media and motion assets before playback starts."
                size={56}
              />
              {assetWaitLong && (
                <button
                  type="button"
                  onClick={handleContinueAnyway}
                  className="px-3 py-1.5 text-[11px] rounded-md border border-neutral-700 text-neutral-300 hover:border-neutral-500 hover:bg-neutral-800 transition-colors"
                >
                  Continue anyway
                </button>
              )}
            </div>
          </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>
    );
  },
);

Player.displayName = "Player";