@hyperframes/studio 0.8.56 → 0.8.57

package/src/player/hooks/timelinePlayerTestHarness.ts

@@ -0,0 +1,120 @@
+// Shared test harness: mounts the real useTimelinePlayer and fakes an iframe
+// whose window exposes a playback adapter.
+import React, { act, useEffect } from "react";
+import { createRoot } from "react-dom/client";
+import { vi } from "vitest";
+import { useTimelinePlayer, type UseTimelinePlayerOptions } from "./useTimelinePlayer";
+import { usePlayerStore } from "../store/playerStore";
+
+export type TimelinePlayerApi = ReturnType<typeof useTimelinePlayer>;
+
+export function resetPlayerStore() {
+  usePlayerStore.getState().reset();
+  usePlayerStore.setState({ requestedSeekTime: null });
+}
+
+function TimelinePlayerHarness({
+  onValue,
+  options,
+}: {
+  onValue: (value: TimelinePlayerApi) => void;
+  options?: UseTimelinePlayerOptions;
+}) {
+  const value = useTimelinePlayer(options);
+  useEffect(() => {
+    onValue(value);
+  }, [onValue, value]);
+  return null;
+}
+
+/** `api` is the first render's snapshot; `getApi()` returns the latest render's value. */
+export function renderTimelinePlayerHarness(options?: UseTimelinePlayerOptions) {
+  let latest: TimelinePlayerApi | null = null;
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+
+  act(() => {
+    root.render(
+      React.createElement(TimelinePlayerHarness, { onValue: (value) => (latest = value), options }),
+    );
+  });
+
+  if (!latest) throw new Error("useTimelinePlayer did not mount");
+  const rerender = (next?: UseTimelinePlayerOptions) =>
+    act(() => {
+      root.render(
+        React.createElement(TimelinePlayerHarness, {
+          onValue: (value) => (latest = value),
+          options: next,
+        }),
+      );
+    });
+  return {
+    api: latest as TimelinePlayerApi,
+    getApi: () => latest as TimelinePlayerApi,
+    root,
+    rerender,
+  };
+}
+
+export function makeFakeIframe(iframeWindow: Record<string, unknown>): HTMLIFrameElement {
+  const iframe = document.createElement("iframe");
+  Object.defineProperty(iframe, "contentWindow", { value: iframeWindow, configurable: true });
+  Object.defineProperty(iframe, "contentDocument", {
+    value: document.implementation.createHTMLDocument("preview"),
+    configurable: true,
+  });
+  return iframe;
+}
+
+export function attachIframeWindow(api: TimelinePlayerApi, iframeWindow: Record<string, unknown>) {
+  const iframe = makeFakeIframe(iframeWindow);
+  act(() => {
+    api.iframeRef.current = iframe;
+    api.onIframeLoad();
+  });
+}
+
+export function makeAdapterWindow(
+  options: {
+    postMessage?: (message: unknown, targetOrigin: string) => void;
+    timelines?: Record<string, unknown>;
+    duration?: number;
+  } = {},
+) {
+  let currentTime = 0;
+  let playing = false;
+  const adapter = {
+    play: vi.fn(() => {
+      playing = true;
+    }),
+    pause: vi.fn(() => {
+      playing = false;
+    }),
+    seek: (time: number) => {
+      currentTime = time;
+    },
+    getTime: () => currentTime,
+    getDuration: () => options.duration ?? 30,
+    isPlaying: () => playing,
+  };
+  const win = {
+    __player: adapter,
+    __timelines: options.timelines,
+    postMessage: options.postMessage ?? (() => {}),
+    scrollTo: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+  };
+  return { adapter, win };
+}
+
+export function attachIframeAdapter(
+  api: TimelinePlayerApi,
+  options: Parameters<typeof makeAdapterWindow>[0] = {},
+) {
+  const { adapter, win } = makeAdapterWindow(options);
+  attachIframeWindow(api, win);
+  return adapter;
+}

package/src/player/hooks/usePreviewFirstFrameTelemetry.ts

@@ -0,0 +1,51 @@
+import { useCallback, useRef } from "react";
+import { parseTimelineFromDOM } from "../lib/timelineDOM";
+import { readTimelineDurationFromDocument } from "../lib/timelineElementHelpers";
+import type { PreviewIframeSlot } from "./useTimelineSyncCallbacks";
+import { trackPreviewFirstFrame } from "../../telemetry/events";
+import { getBrowserSystemMeta } from "../../telemetry/system";
+
+export function readPreviewComplexity(doc: Document | null | undefined): {
+  clip_count: number;
+  media_clip_count: number;
+} {
+  if (!doc) return { clip_count: 0, media_clip_count: 0 };
+  const elements = parseTimelineFromDOM(doc, readTimelineDurationFromDocument(doc));
+  return {
+    clip_count: elements.length,
+    media_clip_count: elements.filter(({ tag }) => tag === "video" || tag === "audio").length,
+  };
+}
+
+export function usePreviewFirstFrameTelemetry(previewSlots: PreviewIframeSlot[]) {
+  const previewSlotsRef = useRef(previewSlots);
+  previewSlotsRef.current = previewSlots;
+  const reportedPaintsRef = useRef(new Set<string>());
+
+  return useCallback(
+    (
+      slot: PreviewIframeSlot,
+      {
+        iframe,
+        startedAt,
+        loadId,
+      }: { iframe: HTMLIFrameElement; startedAt: number; loadId: number },
+    ) => {
+      const currentSlot = previewSlotsRef.current.find(
+        (candidate) => candidate.gen === slot.gen && candidate.role === slot.role,
+      );
+      if (!currentSlot) return;
+      const reportKey = `${slot.role}:${slot.gen}:${loadId}`;
+      if (reportedPaintsRef.current.has(reportKey)) return;
+      reportedPaintsRef.current.add(reportKey);
+      const complexity = readPreviewComplexity(iframe.contentDocument);
+      trackPreviewFirstFrame({
+        duration_ms: Math.max(0, Math.round(performance.now() - startedAt)),
+        composition_seconds: readTimelineDurationFromDocument(iframe.contentDocument),
+        ...complexity,
+        studio_version: getBrowserSystemMeta().studio_version,
+      });
+    },
+    [],
+  );
+}

package/src/player/hooks/useShadowPreviewReload.ts

@@ -0,0 +1,183 @@
+// Loads a full-reload edit in a hidden shadow iframe and promotes it once painted,
+// so the live iframe never shows a blank frame.
+
+import { useCallback, useRef, useState } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
+import { logReload } from "../../utils/reloadDebug";
+import {
+  useTimelineSyncCallbacks,
+  planShadowReload,
+  planShadowPromotion,
+  planShadowDiscard,
+  type PreviewIframeSlot,
+  type UseTimelineSyncCallbacksParams,
+} from "./useTimelineSyncCallbacks";
+import type { PlaybackAdapter } from "../lib/playbackTypes";
+
+// The single wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade
+// leaves about 6.5s for the document load and runtime boot. Nothing shorter may fail the swap.
+export const SHADOW_READY_TIMEOUT_MS = 15_000;
+
+type UseShadowPreviewReloadParams = Omit<
+  UseTimelineSyncCallbacksParams,
+  "probeIntervalRef" | "onAdapterReady" | "getAdapter" | "isCurrent" | "onLoadGiveUp"
+> & {
+  getAdapter: (overrideIframe?: HTMLIFrameElement | null) => PlaybackAdapter | null;
+  /** Runs right after a shadow becomes the live iframe (iframeRef already points at it). */
+  onPromoted?: () => void;
+  /** A shadow that never became ready was dropped; the live preview is unchanged. */
+  onReloadFailed?: (message: string) => void;
+};
+
+export function useShadowPreviewReload({
+  iframeRef,
+  getAdapter,
+  pendingSeekRef,
+  isRefreshingRef,
+  syncTimelineElements,
+  setDuration,
+  setCurrentTime,
+  requestTimelineReady,
+  setIsPlaying,
+  attachIframeShortcutListeners,
+  applyPreviewAudioState,
+  onPromoted,
+  onReloadFailed,
+}: UseShadowPreviewReloadParams) {
+  const shadowIframeRef = useRef<HTMLIFrameElement | null>(null);
+  const shadowProbeIntervalRef = useRef<ReturnType<typeof setInterval> | undefined>(undefined);
+  // Invalidation counter, separate from the live slot's key: bumping it never remounts the live Player.
+  const shadowGenRef = useRef(0);
+  const pendingCommitRef = useRef<{ gen: number; commit: () => void } | null>(null);
+  const visuallyReadyGenRef = useRef<number | null>(null);
+  const onPromotedRef = useRef(onPromoted);
+  onPromotedRef.current = onPromoted;
+  const onReloadFailedRef = useRef(onReloadFailed);
+  onReloadFailedRef.current = onReloadFailed;
+  const readyTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const cancelPendingLoadRef = useRef<() => void>(() => {});
+  const [previewSlots, setPreviewSlots] = useState<PreviewIframeSlot[]>([{ gen: 0, role: "live" }]);
+
+  const stopPendingShadow = useCallback(() => {
+    clearTimeout(readyTimerRef.current);
+    cancelPendingLoadRef.current();
+    pendingCommitRef.current = null;
+    visuallyReadyGenRef.current = null;
+  }, []);
+
+  const failShadow = useCallback(
+    (gen: number, cause: string) => {
+      if (gen !== shadowGenRef.current) return;
+      shadowGenRef.current += 1;
+      stopPendingShadow();
+      shadowIframeRef.current = null;
+      isRefreshingRef.current = false;
+      pendingSeekRef.current = null;
+      setPreviewSlots(planShadowDiscard);
+      const message = `The preview did not reload (${cause}). The previous preview is still showing.`;
+      logReload("shadow-failed", { cause });
+      console.error(`[studio] ${message}`);
+      onReloadFailedRef.current?.(message);
+    },
+    [stopPendingShadow, isRefreshingRef, pendingSeekRef],
+  );
+
+  const promoteWhenReady = useCallback(
+    (gen: number) => {
+      const shadow = shadowIframeRef.current;
+      const pending = pendingCommitRef.current;
+      const ready = pending?.gen === gen && visuallyReadyGenRef.current === gen;
+      if (!shadow || !pending || !ready || gen !== shadowGenRef.current) return;
+      stopPendingShadow();
+      // The store takes the new document's timeline only now that it is the one on screen.
+      pending.commit();
+      iframeRef.current = shadow;
+      shadowIframeRef.current = null;
+      attachIframeShortcutListeners();
+      applyPreviewAudioState();
+      setPreviewSlots((prev) => planShadowPromotion(prev, gen));
+      onPromotedRef.current?.();
+    },
+    [stopPendingShadow, iframeRef, attachIframeShortcutListeners, applyPreviewAudioState],
+  );
+
+  const getShadowAdapter = useCallback(() => getAdapter(shadowIframeRef.current), [getAdapter]);
+  const isCurrentShadow = useCallback((gen?: number) => gen === shadowGenRef.current, []);
+  const markAdapterReady = useCallback(
+    (_iframe: HTMLIFrameElement | null, gen: number | undefined, commit: () => void) => {
+      if (gen == null || gen !== shadowGenRef.current) return;
+      pendingCommitRef.current = { gen, commit };
+      promoteWhenReady(gen);
+    },
+    [promoteWhenReady],
+  );
+
+  const { onIframeLoad: onShadowIframeLoad, cancelPendingLoad } = useTimelineSyncCallbacks({
+    iframeRef: shadowIframeRef,
+    probeIntervalRef: shadowProbeIntervalRef,
+    pendingSeekRef,
+    isRefreshingRef,
+    getAdapter: getShadowAdapter,
+    syncTimelineElements,
+    setDuration,
+    setCurrentTime,
+    requestTimelineReady,
+    setIsPlaying,
+    // A hidden shadow gets neither: shortcuts and audio state apply once it is promoted.
+    attachIframeShortcutListeners: () => {},
+    applyPreviewAudioState: () => {},
+    onAdapterReady: markAdapterReady,
+    isCurrent: isCurrentShadow,
+  });
+  cancelPendingLoadRef.current = cancelPendingLoad;
+
+  // The Player reports whether loaders (shader transition, assets) are cleared right now.
+  const onShadowReadyChange = useCallback(
+    (gen: number, ready: boolean) => {
+      if (gen !== shadowGenRef.current) return;
+      visuallyReadyGenRef.current = ready ? gen : null;
+      if (ready) promoteWhenReady(gen);
+    },
+    [promoteWhenReady],
+  );
+
+  const setShadowIframeNode = useCallback((node: HTMLIFrameElement | null) => {
+    shadowIframeRef.current = node;
+  }, []);
+
+  const beginShadowReload = useCallback(
+    (url: string) => {
+      shadowGenRef.current += 1;
+      const gen = shadowGenRef.current;
+      stopPendingShadow();
+      readyTimerRef.current = setTimeout(
+        () => failShadow(gen, "it took too long to load"),
+        SHADOW_READY_TIMEOUT_MS,
+      );
+      setPreviewSlots((prev) => planShadowReload(prev, gen, url));
+    },
+    [stopPendingShadow, failShadow],
+  );
+
+  // Composition switch (not an edit reload): drop any in-flight shadow.
+  const resetPreviewSlots = useCallback(() => {
+    shadowGenRef.current += 1;
+    stopPendingShadow();
+    shadowIframeRef.current = null;
+    isRefreshingRef.current = false;
+    pendingSeekRef.current = null;
+    setPreviewSlots(planShadowDiscard);
+  }, [stopPendingShadow, isRefreshingRef, pendingSeekRef]);
+
+  useMountEffect(() => stopPendingShadow);
+
+  return {
+    previewSlots,
+    onShadowIframeLoad,
+    onShadowReadyChange,
+    onShadowError: failShadow,
+    setShadowIframeNode,
+    beginShadowReload,
+    resetPreviewSlots,
+  };
+}

package/src/player/hooks/useTimelinePlayer.seek.test.ts

@@ -1,105 +1,25 @@
 // @vitest-environment happy-dom
 
-import React, { act, useEffect } from "react";
-import { createRoot } from "react-dom/client";
+import { act } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { useTimelinePlayer } from "./useTimelinePlayer";
+import type { useTimelinePlayer } from "./useTimelinePlayer";
+import {
+  attachIframeAdapter,
+  attachIframeWindow,
+  renderTimelinePlayerHarness,
+  resetPlayerStore,
+} from "./timelinePlayerTestHarness";
 import { liveTime, usePlayerStore } from "../store/playerStore";
 import { setTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFixture";
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
-function resetPlayerStore() {
-  usePlayerStore.getState().reset();
-  usePlayerStore.setState({ requestedSeekTime: null });
-}
-
-function TimelinePlayerHarness({
-  onValue,
-}: {
-  onValue: (value: ReturnType<typeof useTimelinePlayer>) => void;
-}) {
-  const value = useTimelinePlayer();
-  useEffect(() => {
-    onValue(value);
-  }, [onValue, value]);
-  return null;
-}
-
-function renderTimelinePlayerHarness() {
-  let api: ReturnType<typeof useTimelinePlayer> | null = null;
-  const host = document.createElement("div");
-  document.body.append(host);
-  const root = createRoot(host);
-
-  act(() => {
-    root.render(React.createElement(TimelinePlayerHarness, { onValue: (value) => (api = value) }));
-  });
-
-  if (!api) throw new Error("useTimelinePlayer did not mount");
-  return { api, root };
-}
-
 afterEach(() => {
   setTimelinePerformanceFixtureLease(false);
   document.body.innerHTML = "";
   resetPlayerStore();
 });
 
-function attachIframeWindow(
-  api: ReturnType<typeof useTimelinePlayer>,
-  iframeWindow: Record<string, unknown>,
-): void {
-  const iframe = document.createElement("iframe");
-  Object.defineProperty(iframe, "contentWindow", {
-    value: iframeWindow,
-    configurable: true,
-  });
-  Object.defineProperty(iframe, "contentDocument", {
-    value: document.implementation.createHTMLDocument("preview"),
-    configurable: true,
-  });
-  act(() => {
-    api.iframeRef.current = iframe;
-    api.onIframeLoad();
-  });
-}
-
-function attachIframeAdapter(
-  api: ReturnType<typeof useTimelinePlayer>,
-  options: {
-    postMessage?: (message: unknown, targetOrigin: string) => void;
-    timelines?: Record<string, unknown>;
-    duration?: number;
-  } = {},
-) {
-  let currentTime = 0;
-  let playing = false;
-  const adapter = {
-    play: vi.fn(() => {
-      playing = true;
-    }),
-    pause: vi.fn(() => {
-      playing = false;
-    }),
-    seek: (time: number) => {
-      currentTime = time;
-    },
-    getTime: () => currentTime,
-    getDuration: () => options.duration ?? 30,
-    isPlaying: () => playing,
-  };
-  attachIframeWindow(api, {
-    __player: adapter,
-    __timelines: options.timelines,
-    postMessage: options.postMessage ?? (() => {}),
-    scrollTo: () => {},
-    addEventListener: () => {},
-    removeEventListener: () => {},
-  });
-  return adapter;
-}
-
 function renderAttachedTimelinePlayer() {
   const { api, root } = renderTimelinePlayerHarness();
   const adapter = attachIframeAdapter(api);