@hyperframes/studio 0.8.105 → 0.8.107

package/src/hooks/usePreviewPersistence.history.test.tsx

@@ -0,0 +1,47 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../player/store/playerStore";
+import type { TimelineElement } from "../player/store/timelineElement";
+import { mountReactHarness } from "./domSelectionTestHarness";
+import { usePreviewPersistence } from "./usePreviewPersistence";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+});
+
+describe("undo that reloads the preview", () => {
+  it("keeps the timeline's clips until the reloaded preview reports its own", async () => {
+    const clips = [{ id: "a" }, { id: "b" }] as unknown as TimelineElement[];
+    usePlayerStore.getState().setElements(clips);
+    usePlayerStore.getState().setTimelineReady(true);
+    const reloadPreview = vi.fn();
+    let sync: ReturnType<typeof usePreviewPersistence>["syncHistoryPreviewAfterApply"] | null =
+      null;
+    function Harness() {
+      sync = usePreviewPersistence({
+        showToast: () => {},
+        readOptionalProjectFile: async () => "",
+        writeProjectFile: async () => {},
+        recordEdit: async () => {},
+        previewIframeRef: { current: null },
+        activeCompPathRef: { current: "index.html" },
+        reloadPreview,
+      }).syncHistoryPreviewAfterApply;
+      return null;
+    }
+    mountReactHarness(<Harness />);
+
+    // A nested composition's undo is not the active file's, so it reloads the preview.
+    const files = { "compositions/sub.html": { previous: "<p>1</p>", restored: "<p>2</p>" } };
+    await act(async () => sync!({ paths: Object.keys(files), files }));
+
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    const player = usePlayerStore.getState();
+    expect([player.elements, player.timelineReady]).toEqual([clips, true]);
+  });
+});

package/src/hooks/usePreviewPersistence.ts

@@ -159,6 +159,11 @@ export function usePreviewPersistence({
     if (result.status !== "clean") throw result.error;
   }, [drainPendingDomEditSaves]);
 
+  const settlePendingEdits = useCallback(async (): Promise<void> => {
+    await flushStudioPendingEdits();
+    await domEditSaveQueueRef.current?.waitForIdle();
+  }, []);
+
   const resetDomEditSaveQueueBreaker = useCallback(() => {
     domEditSaveQueueRef.current?.reset();
     setDomEditSaveQueuePaused(null);
@@ -207,16 +212,13 @@ export function usePreviewPersistence({
         reloadPreview,
       );
       if (strategy === "full") {
-        const player = usePlayerStore.getState();
-        player.setElements([]);
-        player.setSelectedElementId(null);
-        player.setTimelineReady(false);
+        usePlayerStore.getState().setSelectedElementId(null);
         return;
       }
       // A soft restore patched the reverted attributes onto the live preview, but the
       // player store keeps its own copy and that copy is what the automation lanes
       // draw — so without this an undone envelope edit stayed invisible until a
-      // reload. The full path above clears the store and waits for discovery instead.
+      // reload. The full path above waits for the reloaded preview to report instead.
       syncStoredAutomationFromPreview(previewIframeRef.current?.contentDocument ?? null);
     },
     [previewIframeRef, activeCompPathRef, reloadPreview],
@@ -256,6 +258,7 @@ export function usePreviewPersistence({
     queueDomEditSave,
     drainPendingDomEditSaves,
     waitForPendingDomEditSaves,
+    settlePendingEdits,
     domEditSaveQueuePaused,
     resetDomEditSaveQueueBreaker,
     applyCurrentStudioManualEditsToPreview,

package/src/hooks/useRenderClipContent.ts

@@ -9,7 +9,7 @@ import {
 import type { TimelineElement } from "../player";
 import type { TimelineClipRenderContext } from "../player/components/TimelineTypes";
 import { audioPillFlags } from "../player/components/audioClipLink";
-import { AudioWaveform } from "../player/components/AudioWaveform";
+import { AudioWaveform, rendersWaveform } from "../player/components/AudioWaveform";
 import { ImageThumbnail } from "../player/components/ImageThumbnail";
 import { encodePreviewPath, resolveMediaPreviewUrl } from "../player/components/thumbnailUtils";
 import { usePlayerStore } from "../player/store/playerStore";
@@ -135,7 +135,7 @@ export function useRenderClipContent({
       // Thumbnail generation disabled (perf) -> plain clip bars. Audio still shows
       // its waveform (cheap, not a frame thumbnail). Toggle: timeline toolbar.
       if (effectiveMode === "hidden") {
-        return el.tag === "audio"
+        return rendersWaveform(el)
           ? renderAudioClip(el, pid, sessionEpoch, style.label, context, elements)
           : null;
       }
@@ -173,7 +173,7 @@ export function useRenderClipContent({
       // Audio clips — waveform visualization. Resolve these before the generic
       // activePreviewUrl thumbnail branch; audio rows need waveform data, not a
       // captured frame from the currently drilled composition preview.
-      if (el.tag === "audio") {
+      if (rendersWaveform(el)) {
         return renderAudioClip(el, pid, sessionEpoch, style.label, context, elements);
       }
 

package/src/hooks/useTrackPendingTimelineEdit.ts

@@ -1,5 +1,5 @@
 import { useCallback, useRef } from "react";
-import { trackStudioPendingEdit } from "../utils/studioPendingEdits";
+import { trackedStudioEdit } from "../utils/studioPendingEdits";
 
 type AsyncFn = (...args: never[]) => Promise<unknown>;
 
@@ -11,11 +11,7 @@ export function useTrackPendingTimelineEdit() {
     const key = fn as unknown as AsyncFn;
     const cached = wrappedRef.current.get(key);
     if (cached) return cached as unknown as (...args: Args) => Promise<R>;
-    const wrapped = (...args: Args): Promise<R> => {
-      const result = fn(...args);
-      trackStudioPendingEdit(result);
-      return result;
-    };
+    const wrapped = trackedStudioEdit(fn);
     wrappedRef.current.set(key, wrapped as unknown as AsyncFn);
     return wrapped;
   }, []);

package/src/index.ts

@@ -181,6 +181,8 @@ export type { UseClipboardOptions } from "./hooks/useClipboard";
 // DOM editing for a host outside EditorShell; the Commit hooks save without useDomEditSession.
 export { useDomEditSession } from "./hooks/useDomEditSession";
 export type { UseDomEditSessionParams } from "./hooks/useDomEditSession";
+export { useLivePreviewIframe } from "./hooks/useLivePreviewIframe";
+export type { PreviewPromotion } from "./player/sceneSwap";
 export { usePreviewPersistence } from "./hooks/usePreviewPersistence";
 export type { UsePreviewPersistenceParams } from "./hooks/usePreviewPersistence";
 export { DomEditProvider, useDomEditSelectionContext } from "./contexts/DomEditContext";
@@ -238,3 +240,10 @@ export type { MarqueeGestures, MarqueeGesturesDeps } from "./components/editor/m
 export { MarqueeOverlay } from "./components/editor/MarqueeOverlay";
 export type { MarqueeOverlayProps } from "./components/editor/MarqueeOverlay";
 export type { Rect as MarqueeRect } from "./utils/marqueeGeometry";
+
+export { buildStudioTools } from "./webmcp/useStudioAgentTools";
+export type { StudioAgentToolsDeps } from "./webmcp/useStudioAgentTools";
+export { collectStudioLookScene } from "./webmcp/tools/lookTools";
+export type { StudioLookSnapshot } from "./webmcp/tools/lookTools";
+export type { ModelContextTool } from "./webmcp/types";
+export type { ToolResult } from "./webmcp/toolResult";

package/src/livePreviewIframeExport.test.tsx

@@ -0,0 +1,33 @@
+// @vitest-environment happy-dom
+// Reads the preview on screen the way a host app does: by package name.
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, expectTypeOf, it } from "vitest";
+import { useLivePreviewIframe, type PreviewPromotion } from "@hyperframes/studio";
+import {
+  makePreview,
+  mountPlayerWithPreview,
+  paintShadow,
+} from "./player/hooks/timelinePlayerTestHarness";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+it("gives a host the preview on screen after a real shadow reload is promoted", async () => {
+  expectTypeOf<PreviewPromotion>().toHaveProperty("live");
+  const host = makePreview("<h1>Title</h1>");
+  const player = mountPlayerWithPreview(host);
+  let live: HTMLIFrameElement | null = null;
+  function Probe() {
+    live = useLivePreviewIframe(host);
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  act(() => root.render(<Probe />));
+  act(() => player.getApi().refreshPlayer());
+  const shadow = makePreview("<h1>Title</h1>", "?_t=1");
+  await paintShadow(player.getApi, shadow);
+  expect(player.getApi().iframeRef.current).toBe(shadow);
+  expect(live).toBe(shadow);
+  act(() => root.unmount());
+  act(() => player.root.unmount());
+});

package/src/main.tsx

@@ -2,6 +2,7 @@ import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { IconContext } from "@phosphor-icons/react";
 import { StudioApp } from "./App";
+import { ShowThemeToggle } from "./components/ThemeToggle";
 import { StudioErrorBoundary } from "./components/StudioErrorBoundary";
 import { readIconTokens } from "./styles/iconTokens";
 import { trackStudioEvent } from "./utils/studioTelemetry";
@@ -128,7 +129,9 @@ createRoot(document.getElementById("root")!).render(
         Icons that pass their own size or weight still win. */}
     <IconContext.Provider value={readIconTokens()}>
       <StudioErrorBoundary>
-        <StudioApp />
+        <ShowThemeToggle.Provider value>
+          <StudioApp />
+        </ShowThemeToggle.Provider>
       </StudioErrorBoundary>
     </IconContext.Provider>
   </StrictMode>,

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

@@ -20,24 +20,30 @@ afterEach(() => {
   document.body.innerHTML = "";
 });
 
+/** A 6 x 20 canvas whose 2D context records every fill as [style, x, y, width, height]. */
+function recordingCanvas() {
+  const fills: Array<[string, number, number, number, number]> = [];
+  const context = {
+    scale: vi.fn(),
+    clearRect: vi.fn(),
+    fillStyle: "",
+    fillRect: (x: number, y: number, width: number, height: number) =>
+      fills.push([String(context.fillStyle), x, y, width, height]),
+  } as unknown as CanvasRenderingContext2D;
+  const canvas = document.createElement("canvas");
+  Object.defineProperties(canvas, {
+    clientWidth: { value: 6 },
+    clientHeight: { value: 20 },
+  });
+  vi.spyOn(canvas, "getContext").mockReturnValue(context);
+  return { canvas, fills };
+}
+
 describe("AudioWaveform", () => {
   it("paints a baseline and peak bar for every mapped waveform bin", () => {
-    const fillRect = vi.fn();
-    const context = {
-      scale: vi.fn(),
-      clearRect: vi.fn(),
-      fillRect,
-      fillStyle: "",
-    } as unknown as CanvasRenderingContext2D;
-    const canvas = document.createElement("canvas");
-    Object.defineProperties(canvas, {
-      clientWidth: { value: 6 },
-      clientHeight: { value: 20 },
-    });
-    vi.spyOn(canvas, "getContext").mockReturnValue(context);
+    const { canvas, fills } = recordingCanvas();
     drawWaveformCanvas(canvas, [0.25, 1], false, 0, 1);
-    expect(fillRect).toHaveBeenCalledTimes(4);
-    expect(fillRect.mock.calls.map(([x, y, width, height]) => [x, y, width, height])).toEqual([
+    expect(fills.map(([, x, y, width, height]) => [x, y, width, height])).toEqual([
       [0, 18, 3, 2],
       [0, 15, 3, 5],
       [3, 18, 3, 2],
@@ -45,6 +51,21 @@ describe("AudioWaveform", () => {
     ]);
   });
 
+  it("shrinks each bar to the fade's gain and keeps the cut-away part as a ghost", () => {
+    const { canvas, fills } = recordingCanvas();
+    // A 1 s fade-in on a 2 s clip: the first bar's centre (0.5 s) plays at half gain.
+    drawWaveformCanvas(canvas, [1, 1], false, 0, 1, { fadeIn: 1, fadeOut: 0, duration: 2 });
+    const bars = fills.filter(([, , y, , height]) => !(y === 18 && height === 2));
+    // The heard half, then the ghost only above it, so the two never stack.
+    expect(bars.map(([, x, y, width, height]) => [x, y, width, height])).toEqual([
+      [0, 10, 3, 10],
+      [0, 0, 3, 10],
+      [3, 0, 3, 20],
+    ]);
+    const alpha = (style: string) => Number(style.split(",").at(-1)?.replace(")", ""));
+    expect(alpha(bars[1][0])).toBeCloseTo(alpha(bars[0][0]) * 0.27, 2);
+  });
+
   it("leases waveform decoding with the clip's project, session, and viewport priority", () => {
     const host = document.createElement("div");
     document.body.append(host);

package/src/player/components/AudioWaveform.tsx

@@ -1,8 +1,10 @@
-import { memo, useCallback, useEffect, useMemo, useRef } from "react";
+import { memo, useCallback, useContext, useEffect, useMemo, useRef } from "react";
+import { fadeGain } from "@hyperframes/core/audio-fade";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { useThumbnailLease } from "../../hooks/useThumbnailLease";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { decimatePeaks, loudnessToOpacity } from "./audioWaveformPeaks";
+import { ClipFadesContext, type ClipFadeShape } from "./TimelineClipFades";
 
 export interface AudioWaveformProps {
   audioUrl: string;
@@ -22,7 +24,10 @@ export interface AudioWaveformProps {
 
 const BAR_STEP = 3;
 
-type BarGeometry = { x: number; width: number; height: number };
+export const rendersWaveform = (el: { tag: string }) => el.tag === "audio";
+const FADE_GHOST_OPACITY = 0.27;
+
+type BarGeometry = { x: number; width: number; height: number; gain: number };
 
 function paintWaveformBars(
   context: CanvasRenderingContext2D,
@@ -33,11 +38,18 @@ function paintWaveformBars(
   amplitudes: readonly number[],
 ) {
   bars.forEach((bar, index) => {
-    const amplitude = amplitudes[index] ?? 0;
+    const opacity = loudnessToOpacity(amplitudes[index] ?? 0);
     context.fillStyle = `rgb(${waveformBaselineRgb})`;
     context.fillRect(bar.x, height - 2, bar.width, 2);
-    context.fillStyle = `rgba(${waveformBarRgb},${loudnessToOpacity(amplitude).toFixed(2)})`;
-    context.fillRect(bar.x, height - bar.height, bar.width, bar.height);
+    const paint = (alpha: number, top: number, barHeight: number) => {
+      context.fillStyle = `rgba(${waveformBarRgb},${alpha.toFixed(2)})`;
+      context.fillRect(bar.x, top, bar.width, barHeight);
+    };
+    const faded = bar.height * bar.gain;
+    if (faded > 0) paint(opacity, height - faded, faded);
+    if (faded < bar.height) {
+      paint(opacity * FADE_GHOST_OPACITY, height - bar.height, bar.height - faded);
+    }
   });
 }
 
@@ -47,6 +59,7 @@ export function drawWaveformCanvas(
   muted: boolean,
   trimStartFraction: number,
   trimEndFraction: number,
+  fades: ClipFadeShape | null = null,
 ) {
   const width = Math.max(1, canvas.clientWidth);
   const height = Math.max(1, canvas.clientHeight);
@@ -67,6 +80,9 @@ export function drawWaveformCanvas(
     x: (index * width) / amplitudes.length,
     width: Math.max(1, width / amplitudes.length),
     height: Math.max(3, amplitude * height),
+    gain: fades
+      ? fadeGain(((index + 0.5) / amplitudes.length) * fades.duration, fades.duration, fades)
+      : 1,
   }));
   const channelToken = muted ? "--timeline-waveform-muted-rgb" : "--timeline-waveform-bar-rgb";
   const waveformBarRgb = getComputedStyle(canvas).getPropertyValue(channelToken);
@@ -179,11 +195,12 @@ export const AudioWaveform = memo(function AudioWaveform({
   const peaks =
     snapshot.status === "ready" && snapshot.value.kind === "waveform" ? snapshot.value.peaks : null;
 
+  const fades = useContext(ClipFadesContext);
   const draw = useCallback(() => {
     const canvas = canvasRef.current;
     if (!canvas || !peaks) return;
-    drawWaveformCanvas(canvas, peaks, muted, trimStartFraction ?? 0, trimEndFraction ?? 1);
-  }, [muted, peaks, trimEndFraction, trimStartFraction]);
+    drawWaveformCanvas(canvas, peaks, muted, trimStartFraction ?? 0, trimEndFraction ?? 1, fades);
+  }, [fades, muted, peaks, trimEndFraction, trimStartFraction]);
 
   const setCanvasRef = useCallback(
     (canvas: HTMLCanvasElement | null) => {

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

@@ -16,7 +16,6 @@ import {
   getTimelineScrollLeftForZoomAnchor,
   getTimelineScrollLeftForZoomTransition,
   shouldShowTimelineShortcutHint,
-  shouldHandleTimelineDeleteKey,
   shouldAutoScrollTimeline,
   getTimelineVisibleTimeRange,
   getTimelineScrollTopForGeometryChange,
@@ -1248,26 +1247,6 @@ describe("shouldShowTimelineShortcutHint", () => {
   });
 });
 
-describe("shouldHandleTimelineDeleteKey", () => {
-  it("handles Delete and Backspace when focus is not in an editor", () => {
-    expect(shouldHandleTimelineDeleteKey({ key: "Delete" })).toBe(true);
-    expect(shouldHandleTimelineDeleteKey({ key: "Backspace" })).toBe(true);
-  });
-
-  it("ignores modifier shortcuts", () => {
-    expect(shouldHandleTimelineDeleteKey({ key: "Delete", metaKey: true })).toBe(false);
-    expect(shouldHandleTimelineDeleteKey({ key: "Backspace", ctrlKey: true })).toBe(false);
-  });
-
-  it("ignores input and editable targets", () => {
-    const input = { tagName: "INPUT", isContentEditable: false };
-    const editable = { tagName: "DIV", isContentEditable: true };
-
-    expect(shouldHandleTimelineDeleteKey({ key: "Delete", target: input })).toBe(false);
-    expect(shouldHandleTimelineDeleteKey({ key: "Delete", target: editable })).toBe(false);
-  });
-});
-
 describe("getDefaultDroppedTrack", () => {
   it("defaults to track 0 when there are no rows yet", () => {
     expect(getDefaultDroppedTrack([])).toBe(0);

package/src/player/components/Timeline.tsx

@@ -26,7 +26,6 @@ export {
   getTimelineCanvasHeight,
   shouldShowTimelineShortcutHint,
   resolveTimelineAssetDrop,
-  shouldHandleTimelineDeleteKey,
   getDefaultDroppedTrack,
 } from "./timelineLayout";
 export { formatTimelineTickLabel, generateTicks } from "./timelineRulerGeometry";

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

@@ -5,6 +5,7 @@ import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
 import { TimelineClip } from "./TimelineClip";
+import { ClipFadesContext } from "./TimelineClipFades";
 import type { TimelineEditCapabilities } from "./timelineEditing";
 import { defaultTimelineTheme, type TimelineTheme } from "./timelineTheme";
 
@@ -67,6 +68,43 @@ function renderClip({
 }
 
 describe("TimelineClip", () => {
+  it("hands its content the clip's fades, and none to a clip the mixer does not hear", () => {
+    const seen: unknown[] = [];
+    function Probe() {
+      seen.push(React.useContext(ClipFadesContext));
+      return null;
+    }
+    const render = (element: TimelineElement) => {
+      const host = document.createElement("div");
+      document.body.append(host);
+      const root = createRoot(host);
+      act(() => {
+        root.render(
+          <TimelineClip
+            el={element}
+            pps={100}
+            clipY={0}
+            isSelected={false}
+            isHovered={false}
+            hasCustomContent
+            capabilities={capabilities}
+            isComposition={false}
+            onHoverStart={vi.fn()}
+            onHoverEnd={vi.fn()}
+            onClick={vi.fn()}
+            onDoubleClick={vi.fn()}
+          >
+            <Probe />
+          </TimelineClip>,
+        );
+      });
+      act(() => root.unmount());
+    };
+    render({ id: "music", tag: "audio", start: 0, duration: 4, track: 0, fadeIn: 1, fadeOut: 0.5 });
+    render({ id: "title", tag: "div", start: 0, duration: 4, track: 0, fadeIn: 1 });
+    expect(seen).toEqual([{ fadeIn: 1, fadeOut: 0.5, duration: 4 }, null]);
+  });
+
   it("renders the clip label above custom content without showing default timecode", () => {
     const { host, root } = renderClip({
       element: { id: "hero", label: "Hero", tag: "div", start: 1, duration: 1, track: 0 },

package/src/player/components/TimelineClip.tsx

@@ -9,7 +9,8 @@ import {
 import type { TimelineEditCapabilities } from "./timelineEditing";
 import { isAudioTimelineElement } from "../../utils/timelineInspector";
 import { timelineClipFocusId } from "./timelineNavigationIdentity";
-import { TimelineClipFades } from "./TimelineClipFades";
+import { ClipFadesContext, TimelineClipFades, useClipFadeDraft } from "./TimelineClipFades";
+import { rendersWaveform } from "./AudioWaveform";
 
 interface TimelineClipProps {
   el: TimelineElement;
@@ -82,6 +83,8 @@ export const TimelineClip = memo(function TimelineClip({
     "--clip-handle": theme.handleColor,
   } as CSSProperties;
   const isAudioClip = isAudioTimelineElement(el);
+  const hasFades = (isAudioClip || Boolean(el.hasAudio)) && !isGestureActor;
+  const fade = useClipFadeDraft(el);
   const clipClassName = [
     "timeline-clip",
     "absolute",
@@ -206,16 +209,21 @@ export const TimelineClip = memo(function TimelineClip({
           {startLabel}-{endLabel}s
         </span>
       )}
-      {children}
-      {/* Fade handles + ramps for anything the mixer hears — audio clips and
-          videos marked data-has-audio. They write data-fade-in/out on the clip
-          and are the timeline half of the inspector's Fade rows. */}
-      {(isAudioClip || el.hasAudio) && !isGestureActor && (
+      <ClipFadesContext.Provider value={hasFades ? fade.shape : null}>
+        {children}
+      </ClipFadesContext.Provider>
+      {/* Fade handles for anything the mixer hears: audio clips and videos marked
+          data-has-audio. They write data-fade-in/out, the timeline half of the
+          inspector's Fade rows. */}
+      {hasFades && (
         <TimelineClipFades
           el={el}
           pps={pps}
           widthPx={widthPx}
           showHandles={(isHovered || isSelected) && !isDragging}
+          focusable={isSelected}
+          hasWaveform={rendersWaveform(el)}
+          fade={fade}
         />
       )}
     </button>