@hyperframes/studio 0.8.55 → 0.8.57

package/src/components/editor/usePreviewCompositionRect.test.tsx

@@ -1,9 +1,9 @@
 // @vitest-environment happy-dom
 
-import { act, useRef } from "react";
+import { act, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it } from "vitest";
-import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
+import { resetOverlayFrameLoopForTests } from "./overlayFrameLoop";
 import {
   usePreviewCompositionRect,
   type PreviewCompositionRect,
@@ -12,7 +12,7 @@ import {
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 afterEach(() => {
-  usePreviewIframeStore.getState().setIframe(null);
+  resetOverlayFrameLoopForTests();
   document.body.innerHTML = "";
 });
 
@@ -24,9 +24,12 @@ function boxed<T extends HTMLElement>(el: T, box: [number, number, number, numbe
 
 function mountProbe() {
   let rect: PreviewCompositionRect | undefined;
+  let setIframe: (iframe: HTMLIFrameElement | null) => void = () => {};
   function Probe() {
     const ref = useRef<HTMLDivElement>(null);
-    rect = usePreviewCompositionRect(ref);
+    const [iframe, updateIframe] = useState<HTMLIFrameElement | null>(null);
+    setIframe = updateIframe;
+    rect = usePreviewCompositionRect(ref, iframe);
     return (
       <div
         ref={(el) => {
@@ -38,8 +41,9 @@ function mountProbe() {
   }
   const host = document.createElement("div");
   document.body.append(host);
-  act(() => createRoot(host).render(<Probe />));
-  return () => rect;
+  const root = createRoot(host);
+  act(() => root.render(<Probe />));
+  return { read: () => rect, setIframe, unmount: () => act(() => root.unmount()) };
 }
 
 function compositionFrame(box: [number, number, number, number], width: number, height: number) {
@@ -57,13 +61,13 @@ const settle = () => new Promise((r) => setTimeout(r, 400));
 
 describe("usePreviewCompositionRect", () => {
   it("reports the live preview iframe's box relative to the overlay, scaled to the composition", async () => {
-    const read = mountProbe();
+    const probe = mountProbe();
     const iframe = compositionFrame([110, 70, 960, 540], 1920, 1080);
     await act(async () => {
-      usePreviewIframeStore.getState().setIframe(iframe);
+      probe.setIframe(iframe);
       await settle();
     });
-    expect(read()).toEqual({
+    expect(probe.read()).toEqual({
       left: 100,
       top: 50,
       width: 960,
@@ -71,19 +75,20 @@ describe("usePreviewCompositionRect", () => {
       scaleX: 0.5,
       scaleY: 0.5,
     });
+    probe.unmount();
   });
 
   it("follows the iframe when a reload replaces it", async () => {
-    const read = mountProbe();
+    const probe = mountProbe();
     await act(async () => {
-      usePreviewIframeStore.getState().setIframe(compositionFrame([110, 70, 960, 540], 1920, 1080));
+      probe.setIframe(compositionFrame([110, 70, 960, 540], 1920, 1080));
       await settle();
     });
     await act(async () => {
-      usePreviewIframeStore.getState().setIframe(compositionFrame([60, 40, 500, 500], 1000, 1000));
+      probe.setIframe(compositionFrame([60, 40, 500, 500], 1000, 1000));
       await settle();
     });
-    expect(read()).toEqual({
+    expect(probe.read()).toEqual({
       left: 50,
       top: 20,
       width: 500,
@@ -91,5 +96,6 @@ describe("usePreviewCompositionRect", () => {
       scaleX: 0.5,
       scaleY: 0.5,
     });
+    probe.unmount();
   });
 });

package/src/components/editor/usePreviewCompositionRect.ts

@@ -1,21 +1,21 @@
-import { useMemo, type RefObject } from "react";
-import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
+import { useEffect, useRef, type RefObject } from "react";
+import { requestOverlayFrames } from "./overlayFrameLoop";
 import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
 
 export type { DomEditCompositionRect as PreviewCompositionRect } from "./useDomEditCompositionRect";
 
 /**
  * Where the composition sits inside `overlayRef`, in overlay pixels, plus the scale from
- * composition units to pixels. Follows the live preview iframe across reloads.
+ * composition units to pixels.
  */
-export function usePreviewCompositionRect(overlayRef: RefObject<HTMLDivElement | null>) {
-  const iframeRef = useMemo<RefObject<HTMLIFrameElement | null>>(
-    () => ({
-      get current() {
-        return usePreviewIframeStore.getState().iframe;
-      },
-    }),
-    [],
-  );
+export function usePreviewCompositionRect(
+  overlayRef: RefObject<HTMLDivElement | null>,
+  iframe: HTMLIFrameElement | null,
+) {
+  const iframeRef = useRef<HTMLIFrameElement | null>(iframe);
+  iframeRef.current = iframe;
+  useEffect(() => {
+    requestOverlayFrames();
+  }, [iframe]);
   return useDomEditCompositionRect({ iframeRef, overlayRef });
 }

package/src/components/editor/useVolumeAutomation.test.tsx

@@ -191,3 +191,71 @@ describe("useVolumeAutomation", () => {
     expect(writtenAutomation(onSetAttributeQuiet).lanes[0].points[0].v).toBe(1);
   });
 });
+
+describe("useVolumeAutomation speed lane", () => {
+  const rateLane = JSON.stringify({
+    version: 1,
+    lanes: [
+      {
+        target: "rate",
+        points: [
+          { t: 0, v: 1 },
+          { t: 4, v: 4 },
+        ],
+      },
+    ],
+  });
+
+  it("seeds a rate lane at the clip's constant rate so automating does not change the speed", () => {
+    const { binding, onSetAttributeQuiet } = bind({ "playback-rate": "2" });
+    binding.rate.onAutomate();
+    expect(writtenAutomation(onSetAttributeQuiet).lanes).toEqual([
+      { target: "rate", points: [{ t: 0, v: 2 }] },
+    ]);
+  });
+
+  it("reports the lane's geometric value at the playhead", () => {
+    // 1x to 4x over 4s: halfway is 2x, not the linear 2.5x
+    const { binding } = bind({ automation: rateLane, start: "0", duration: "4" }, 2);
+    expect(binding.rate.automated).toBe(true);
+    expect(binding.rate.automatedValue).toBeCloseTo(2, 5);
+  });
+
+  it("writes a keyframe on the rate lane and leaves the volume lane alone", () => {
+    const both = JSON.stringify({
+      version: 1,
+      lanes: [
+        { target: "volume", points: [{ t: 0, v: 0.5 }] },
+        { target: "rate", points: [{ t: 0, v: 1 }] },
+      ],
+    });
+    const { binding, onSetAttributeQuiet } = bind(
+      { automation: both, start: "0", duration: "4" },
+      2,
+    );
+    binding.rate.onCommitAt(3);
+    const lanes = writtenAutomation(onSetAttributeQuiet).lanes;
+    expect(lanes.find((l: { target: string }) => l.target === "volume").points).toEqual([
+      { t: 0, v: 0.5 },
+    ]);
+    expect(lanes.find((l: { target: string }) => l.target === "rate").points).toContainEqual({
+      t: 2,
+      v: 3,
+    });
+  });
+
+  it("stretches a preset over the clip's duration", () => {
+    const { binding, onSetAttributeQuiet } = bind({ start: "0", duration: "8" });
+    binding.rate.onApplyPreset("flash-out");
+    const lane = writtenAutomation(onSetAttributeQuiet).lanes[0];
+    expect(lane.target).toBe("rate");
+    expect(lane.points.at(-1).t).toBe(8);
+  });
+
+  it("offers no preset while the clip has no known duration, and writes nothing", () => {
+    const { binding, onSetAttributeQuiet } = bind({ start: "0" });
+    expect(binding.rate.canApplyPreset).toBe(false);
+    binding.rate.onApplyPreset("flash-out");
+    expect(onSetAttributeQuiet).not.toHaveBeenCalled();
+  });
+});

package/src/components/editor/useVolumeAutomation.ts

@@ -1,13 +1,15 @@
 /**
- * The volume lane's state and edits for the media section.
+ * The media section's lane state and edits: volume and speed.
  *
- * Volume lives in a different panel section from the FX chain, but is automated
- * the same way, so it reads and writes through the same helper the FX group uses
+ * Both live in a different panel section from the FX chain but are automated
+ * the same way, so they read and write through the same helper the FX group uses
  * rather than a second interpretation of the attribute.
  */
 
 import {
   HF_AUDIO_AUTOMATION_DATA_KEY,
+  RATE_TARGET,
+  resolveAutomationRange,
   sampleAutomationLane,
   VOLUME_TARGET,
 } from "@hyperframes/core/audio-automation";
@@ -16,30 +18,50 @@ import {
   automationAttrValue,
   HF_AUDIO_AUTOMATION_ATTR,
   readPanelAutomation,
+  withLane,
   withoutLane,
   withPointAt,
   withSeededLane,
 } from "./propertyPanelAutomation";
 import { deriveElementTiming } from "./propertyPanelFlatTimingDerivation";
+import { SPEED_PRESETS, speedPresetLane, type SpeedPresetId } from "@hyperframes/core/speed-ramp";
 import { clampNumber } from "../../utils/studioHelpers";
 
+export interface LaneBinding {
+  automated: boolean;
+  onAutomate: () => void;
+  onRemoveAutomation: () => void;
+  /** Write `v` as a keyframe at the playhead instead of the disabled fallback. */
+  onCommitAt: (v: number) => void;
+  /** The envelope's own value at the playhead, so the slider tracks it live. */
+  automatedValue: number | undefined;
+}
+
+export type RateBinding = LaneBinding & {
+  /** False while the clip has no known duration to stretch a preset over. */
+  canApplyPreset: boolean;
+  onApplyPreset: (id: SpeedPresetId) => void;
+};
+
 export interface VolumeAutomationBinding {
   volumeAutomated: boolean;
   onAutomateVolume: () => void;
   onRemoveVolumeAutomation: () => void;
-  /** Write `v` as a keyframe at the playhead instead of the disabled fallback. */
   onCommitVolumeAt: (v: number) => void;
-  /** The envelope's own value at the playhead, so the slider tracks it live. */
   automatedVolumeValue: number | undefined;
+  /** Speed: the `rate` lane, plus the CapCut-style presets that seed it. */
+  rate: RateBinding;
 }
 
+export const SPEED_PRESET_OPTIONS = SPEED_PRESETS.map(({ id, label }) => ({ value: id, label }));
+
 export function useVolumeAutomation(
   element: DomEditSelection,
   currentTime: number,
   onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>,
 ): VolumeAutomationBinding {
-  // The chain is not needed to resolve a volume lane — volume is always a valid
-  // target — so this deliberately does not parse it.
+  // The chain is not needed to resolve a volume or rate lane: both are always valid
+  // targets, so this deliberately does not parse it.
   const automation = readPanelAutomation(
     element.dataAttributes?.[HF_AUDIO_AUTOMATION_DATA_KEY],
     undefined,
@@ -55,21 +77,40 @@ export function useVolumeAutomation(
     // playing track, while the same click on an effect parameter did not.
     void onSetAttributeQuiet(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(next) || null);
   };
+  const laneBinding = (target: string, seed: number): LaneBinding => {
+    const lane = automation.lanes.find((l) => l.target === target);
+    return {
+      automated: lane !== undefined,
+      automatedValue: lane
+        ? sampleAutomationLane(lane, clipTimeSec, resolveAutomationRange(target, undefined)?.scale)
+        : undefined,
+      // Seeded at the level the control already shows, so automating does not change it.
+      onAutomate: () => write(withSeededLane(automation, target, seed)),
+      onRemoveAutomation: () => write(withoutLane(automation, target)),
+      onCommitAt: (v: number) => write(withPointAt(automation, target, clipTimeSec, v)),
+    };
+  };
   // `??` alone would let an empty `data-volume` through as Number("") === 0, so
   // automating the track would seed its lane at silence. The engine reads the same
   // empty value as unity.
   const raw = element.dataAttributes?.["volume"];
   const parsed = raw ? Number(raw) : 1;
   const current = Number.isFinite(parsed) ? parsed : 1;
-  const volumeLane = automation.lanes.find((lane) => lane.target === VOLUME_TARGET);
+  const volume = laneBinding(VOLUME_TARGET, current);
+  const rateAttr = Number.parseFloat(element.dataAttributes?.["playback-rate"] ?? "");
+  const rate = laneBinding(RATE_TARGET, Number.isFinite(rateAttr) && rateAttr > 0 ? rateAttr : 1);
   return {
-    volumeAutomated: volumeLane !== undefined,
-    automatedVolumeValue: volumeLane ? sampleAutomationLane(volumeLane, clipTimeSec) : undefined,
-    // Seeded at the level the slider already shows, so automating the track does
-    // not change how loud it is.
-    onAutomateVolume: () =>
-      write(withSeededLane(automation, VOLUME_TARGET, Number.isFinite(current) ? current : 1)),
-    onRemoveVolumeAutomation: () => write(withoutLane(automation, VOLUME_TARGET)),
-    onCommitVolumeAt: (v: number) => write(withPointAt(automation, VOLUME_TARGET, clipTimeSec, v)),
+    volumeAutomated: volume.automated,
+    automatedVolumeValue: volume.automatedValue,
+    onAutomateVolume: volume.onAutomate,
+    onRemoveVolumeAutomation: volume.onRemoveAutomation,
+    onCommitVolumeAt: volume.onCommitAt,
+    rate: {
+      ...rate,
+      canApplyPreset: elDuration > 0,
+      onApplyPreset: (id) => {
+        if (elDuration > 0) write(withLane(automation, speedPresetLane(id, elDuration)));
+      },
+    },
   };
 }

package/src/components/nle/NLEContext.tsx

@@ -2,6 +2,7 @@ import { buildProjectApiPath } from "../../utils/projectRouting";
 import { useContext, useState, useCallback, useRef, useEffect, type ReactNode } from "react";
 import { useTimelinePlayer, usePlayerStore } from "../../player";
 import type { TimelineElement } from "../../player";
+import type { PreviewIframeSlot } from "../../player/hooks/useTimelineSyncCallbacks";
 import type { CompositionLevel } from "./CompositionBreadcrumb";
 import { useCompositionStack } from "./useCompositionStack";
 import { setCompositionSourceMap } from "../editor/domEditingDom";
@@ -21,6 +22,14 @@ export interface NLEContextValue {
   seek: (time: number, options?: { keepPlaying?: boolean }) => boolean;
   refreshPlayer: () => void;
   onIframeLoad: () => void;
+  // The hidden reload iframe NLEPreview renders next to the live one during a full reload.
+  previewSlots: PreviewIframeSlot[];
+  onShadowIframeLoad: (gen: number) => void;
+  onShadowReadyChange: (gen: number, ready: boolean) => void;
+  onShadowError: (gen: number, message: string) => void;
+  setShadowIframeNode: (node: HTMLIFrameElement | null) => void;
+  resetPreviewSlots: () => void;
+  containerRef: React.MutableRefObject<HTMLDivElement | null>;
   // composition stack (from useCompositionStack)
   compositionStack: CompositionLevel[];
   updateCompositionStack: React.Dispatch<React.SetStateAction<CompositionLevel[]>>;
@@ -55,6 +64,8 @@ export interface NLEProviderProps {
   onCompositionChange?: (compositionPath: string | null) => void;
   onCompIdToSrcChange?: (map: Map<string, string>) => void;
   onCompositionLoadingChange?: (loading: boolean) => void;
+  /** A preview reload was abandoned; the previous preview is still showing. */
+  onPreviewReloadFailed?: (message: string) => void;
   children: ReactNode;
 }
 
@@ -66,15 +77,27 @@ export function NLEProvider({
   onCompositionChange,
   onCompIdToSrcChange,
   onCompositionLoadingChange,
+  onPreviewReloadFailed,
   children,
 }: NLEProviderProps) {
+  const shadowPromotedRef = useRef<() => void>(() => {});
+  const containerRef = useRef<HTMLDivElement>(null);
   const {
     iframeRef,
     togglePlay,
     seek,
     onIframeLoad: baseOnIframeLoad,
     refreshPlayer,
-  } = useTimelinePlayer();
+    previewSlots,
+    onShadowIframeLoad,
+    onShadowReadyChange,
+    onShadowError,
+    setShadowIframeNode,
+    resetPreviewSlots,
+  } = useTimelinePlayer({
+    onShadowPromoted: () => shadowPromotedRef.current(),
+    onPreviewReloadFailed,
+  });
 
   // Reset timeline state when the project changes. Done in an effect, not during
   // render: reset() updates the player store, and updating another store/component
@@ -107,14 +130,20 @@ export function NLEProvider({
     refreshPlayer();
   }, [refreshKey, refreshPlayer]);
 
-  const onIframeLoad = useCallback(() => {
-    baseOnIframeLoad();
+  // Steps that follow every load of the live iframe, including a reload promoted in place.
+  const afterLiveIframeLoad = useCallback(() => {
     // Pre-load + register MotionPathPlugin once so adding a motion path in the
     // studio doesn't take the async plugin-load flash path on the first soft
     // reload (the comp may not ship the plugin until it actually uses one).
     ensureMotionPathPluginLoaded(iframeRef.current);
     onIframeRef?.(iframeRef.current);
-  }, [baseOnIframeLoad, iframeRef, onIframeRef]);
+  }, [iframeRef, onIframeRef]);
+  shadowPromotedRef.current = afterLiveIframeLoad;
+
+  const onIframeLoad = useCallback(() => {
+    baseOnIframeLoad();
+    afterLiveIframeLoad();
+  }, [baseOnIframeLoad, afterLiveIframeLoad]);
 
   const {
     compositionStack,
@@ -269,10 +298,17 @@ export function NLEProvider({
   const value: NLEContextValue = {
     projectId,
     iframeRef,
+    containerRef,
     togglePlay,
     seek,
     refreshPlayer,
     onIframeLoad,
+    previewSlots,
+    onShadowIframeLoad,
+    onShadowReadyChange,
+    onShadowError,
+    setShadowIframeNode,
+    resetPreviewSlots,
     compositionStack,
     updateCompositionStack,
     handleNavigateComposition,

package/src/components/nle/NLEPreview.test.ts

@@ -3,10 +3,14 @@
 import React, { act, createRef } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useTimelinePlayer } from "../../player/hooks/useTimelinePlayer";
 import { NLEPreview, getPreviewPlayerKey, resolvePreviewStageSize } from "./NLEPreview";
+import { readPreviewComplexity } from "../../player/hooks/usePreviewFirstFrameTelemetry";
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
+const playerMounts: string[] = [];
+
 vi.mock("../../player", async () => {
   const React = await import("react");
 
@@ -14,6 +18,7 @@ vi.mock("../../player", async () => {
     Player: React.forwardRef(function MockPlayer(
       props: {
         onLoad?: () => void;
+        suppressLoadingOverlay?: boolean;
         style?: React.CSSProperties;
       },
       ref: React.ForwardedRef<HTMLIFrameElement>,
@@ -21,6 +26,7 @@ vi.mock("../../player", async () => {
       React.useEffect(() => {
         props.onLoad?.();
       }, [props]);
+      React.useState(() => playerMounts.push(props.suppressLoadingOverlay ? "shadow" : "live"));
 
       return React.createElement("div", {
         ref: ref as React.ForwardedRef<HTMLDivElement>,
@@ -70,7 +76,11 @@ function setRect(node: Element, rect: { width: number; height: number }) {
   });
 }
 
-function renderPreview() {
+function renderPreview(
+  previewSlots: Array<{ gen: number; role: "live" | "shadow"; url?: string }> = [
+    { gen: 0, role: "live" },
+  ],
+) {
   resizeCallbacks = [];
   const host = document.createElement("div");
   document.body.append(host);
@@ -83,6 +93,12 @@ function renderPreview() {
         projectId: "timeline-edit-playground",
         iframeRef,
         onIframeLoad: () => {},
+        previewSlots,
+        onShadowIframeLoad: () => {},
+        onShadowReadyChange: () => {},
+        onShadowError: () => {},
+        setShadowIframeNode: () => {},
+        resetPreviewSlots: () => {},
       }),
     );
   });
@@ -163,6 +179,13 @@ describe("resolvePreviewStageSize", () => {
 });
 
 describe("NLEPreview", () => {
+  it("counts timeline clips and media clips from the painted document", () => {
+    const doc = new DOMParser().parseFromString(
+      '<div data-composition-id="main" data-duration="10"><video data-start="0" data-duration="2"></video><audio data-start="2" data-duration="3"></audio><div data-start="5" data-duration="1"></div></div>',
+      "text/html",
+    );
+    expect(readPreviewComplexity(doc)).toEqual({ clip_count: 3, media_clip_count: 2 });
+  });
   beforeEach(() => {
     globalThis.ResizeObserver = MockResizeObserver as typeof ResizeObserver;
   });
@@ -227,4 +250,46 @@ describe("NLEPreview", () => {
     expect(view.stage.style.transform).toContain("translate3d(30px, -24px, 0)");
     view.cleanup();
   });
+
+  it("clips a shadow reload so its own loading overlay cannot paint over the live frame", () => {
+    const view = renderPreview([
+      { gen: 0, role: "live" },
+      { gen: 1, role: "shadow", url: "/api/projects/p/preview?_t=1" },
+    ]);
+    const players = [...view.stage.querySelectorAll<HTMLElement>('[data-testid="mock-player"]')];
+    expect(players).toHaveLength(2);
+    expect(players[0].style.clipPath).toBe("");
+    expect(players[1].style.clipPath).toBe("inset(100%)");
+    expect(players[1].style.visibility).toBe("hidden");
+    view.cleanup();
+  });
+
+  it("mounts the live player once when the composition switches", () => {
+    playerMounts.length = 0;
+    const Harness = ({ projectId }: { projectId: string }) => {
+      const api = useTimelinePlayer();
+      return React.createElement(NLEPreview, {
+        projectId,
+        iframeRef: api.iframeRef,
+        onIframeLoad: api.onIframeLoad,
+        previewSlots: api.previewSlots,
+        onShadowIframeLoad: api.onShadowIframeLoad,
+        onShadowReadyChange: api.onShadowReadyChange,
+        onShadowError: api.onShadowError,
+        setShadowIframeNode: api.setShadowIframeNode,
+        resetPreviewSlots: api.resetPreviewSlots,
+      });
+    };
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => root.render(React.createElement(Harness, { projectId: "a" })));
+    expect(playerMounts).toEqual(["live"]);
+
+    act(() => root.render(React.createElement(Harness, { projectId: "b" })));
+    expect(playerMounts).toEqual(["live", "live"]);
+
+    act(() => root.unmount());
+    host.remove();
+  });
 });