@hyperframes/studio 0.8.105 → 0.8.106

package/src/hooks/useDomEditSession.test.tsx

@@ -9,6 +9,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import type { TimelineElement } from "../player";
 import type { UseDomEditSessionParams } from "./useDomEditSession";
+import { makeSelection } from "./domSelectionTestHarness";
 
 const styleOp = (property: string, value: string): PatchOperation => ({
   type: "inline-style",
@@ -132,26 +133,30 @@ vi.mock("./useDomEditCommits", () => ({
     };
   },
 }));
+const iframesHandedOn: Array<{ hook: string; iframe: unknown }> = [];
 vi.mock("./useDomSelection", () => ({
-  useDomSelection: () => ({
-    domEditSelection: domEditSelectionRef.current,
-    domEditGroupSelections: [],
-    domEditHoverSelection: null,
-    activeGroupElement: null,
-    domEditSelectionRef,
-    domEditGroupSelectionsRef,
-    setActiveGroupElement: vi.fn(),
-    applyDomSelection: vi.fn(),
-    clearDomSelection: vi.fn(),
-    buildDomSelectionFromTarget: vi.fn(),
-    resolveDomSelectionFromPreviewPoint: vi.fn(),
-    resolveAllDomSelectionsFromPreviewPoint: vi.fn(),
-    updateDomEditHoverSelection: vi.fn(),
-    buildDomSelectionForTimelineElement: vi.fn(),
-    handleTimelineElementSelect: vi.fn(),
-    refreshDomEditSelectionFromPreview: vi.fn(),
-    applyMarqueeSelection: vi.fn(),
-  }),
+  useDomSelection: ({ previewIframe }: { previewIframe: unknown }) => {
+    iframesHandedOn.push({ hook: "selection", iframe: previewIframe });
+    return {
+      domEditSelection: domEditSelectionRef.current,
+      domEditGroupSelections: [],
+      domEditHoverSelection: null,
+      activeGroupElement: null,
+      domEditSelectionRef,
+      domEditGroupSelectionsRef,
+      setActiveGroupElement: vi.fn(),
+      applyDomSelection: vi.fn(),
+      clearDomSelection: vi.fn(),
+      buildDomSelectionFromTarget: vi.fn(),
+      resolveDomSelectionFromPreviewPoint: vi.fn(),
+      resolveAllDomSelectionsFromPreviewPoint: vi.fn(),
+      updateDomEditHoverSelection: vi.fn(),
+      buildDomSelectionForTimelineElement: vi.fn(),
+      handleTimelineElementSelect: vi.fn(),
+      refreshDomEditSelectionFromPreview: vi.fn(),
+      applyMarqueeSelection: vi.fn(),
+    };
+  },
 }));
 vi.mock("./useAskAgentModal", () => ({
   useAskAgentModal: () => ({
@@ -208,33 +213,36 @@ vi.mock("./useGroupCommits", () => ({
   }),
 }));
 vi.mock("./useDomEditWiring", () => ({
-  useDomEditWiring: () => ({
-    onClickToSource: vi.fn(),
-    selectedGsapAnimations: [],
-    gsapMultipleTimelines: false,
-    gsapUnsupportedTimelinePattern: false,
-    trackGsapInteractionFailure: vi.fn(),
-    makeFetchFallback: vi.fn(),
-    handleGsapUpdateProperty: vi.fn(),
-    handleGsapUpdateMeta: vi.fn(),
-    handleGsapDeleteAnimation: vi.fn(),
-    handleGsapDeleteAllForElement: vi.fn(),
-    handleGsapAddAnimation: vi.fn(),
-    handleGsapAddProperty: vi.fn(),
-    handleGsapRemoveProperty: vi.fn(),
-    handleGsapUpdateFromProperty: vi.fn(),
-    handleGsapAddFromProperty: vi.fn(),
-    handleGsapRemoveFromProperty: vi.fn(),
-    handleGsapAddKeyframe: vi.fn(),
-    handleGsapAddKeyframeBatch: vi.fn(),
-    handleGsapRemoveKeyframe: vi.fn(),
-    handleGsapMoveKeyframeToPlayhead: vi.fn(),
-    handleGsapMoveKeyframe: vi.fn(),
-    handleGsapResizeKeyframedTween: vi.fn(),
-    handleGsapConvertToKeyframes: vi.fn(),
-    handleGsapRemoveAllKeyframes: vi.fn(),
-    handleResetSelectedElementKeyframes: vi.fn(),
-  }),
+  useDomEditWiring: ({ previewIframe }: { previewIframe: unknown }) => {
+    iframesHandedOn.push({ hook: "wiring", iframe: previewIframe });
+    return {
+      onClickToSource: vi.fn(),
+      selectedGsapAnimations: [],
+      gsapMultipleTimelines: false,
+      gsapUnsupportedTimelinePattern: false,
+      trackGsapInteractionFailure: vi.fn(),
+      makeFetchFallback: vi.fn(),
+      handleGsapUpdateProperty: vi.fn(),
+      handleGsapUpdateMeta: vi.fn(),
+      handleGsapDeleteAnimation: vi.fn(),
+      handleGsapDeleteAllForElement: vi.fn(),
+      handleGsapAddAnimation: vi.fn(),
+      handleGsapAddProperty: vi.fn(),
+      handleGsapRemoveProperty: vi.fn(),
+      handleGsapUpdateFromProperty: vi.fn(),
+      handleGsapAddFromProperty: vi.fn(),
+      handleGsapRemoveFromProperty: vi.fn(),
+      handleGsapAddKeyframe: vi.fn(),
+      handleGsapAddKeyframeBatch: vi.fn(),
+      handleGsapRemoveKeyframe: vi.fn(),
+      handleGsapMoveKeyframeToPlayhead: vi.fn(),
+      handleGsapMoveKeyframe: vi.fn(),
+      handleGsapResizeKeyframedTween: vi.fn(),
+      handleGsapConvertToKeyframes: vi.fn(),
+      handleGsapRemoveAllKeyframes: vi.fn(),
+      handleResetSelectedElementKeyframes: vi.fn(),
+    };
+  },
 }));
 vi.mock("./usePreviewInteraction", () => ({
   usePreviewInteraction: () => ({
@@ -310,32 +318,9 @@ describe("onReorderShadow source filter", () => {
 describe("bulk segment ease commits", () => {
   it("uses one ordered batch for many ids and sane paths for one or no ids", async () => {
     const { useDomEditSession } = await import("./useDomEditSession");
-    const selection: DomEditSelection = {
-      id: "hero",
-      element: document.createElement("div"),
-      label: "Hero",
-      tagName: "DIV",
-      sourceFile: "index.html",
-      compositionPath: "index.html",
-      isCompositionHost: false,
-      isInsideLockedComposition: false,
-      boundingBox: { x: 0, y: 0, width: 100, height: 100 },
-      textContent: null,
-      dataAttributes: {},
-      inlineStyles: {},
-      computedStyles: {},
-      textFields: [],
-      capabilities: {
-        canSelect: true,
-        canEditStyles: true,
-        canCrop: true,
-        canMove: true,
-        canResize: true,
-        canApplyManualOffset: true,
-        canApplyManualSize: true,
-        canApplyManualRotation: true,
-      },
-    };
+    const hero = document.createElement("div");
+    hero.id = "hero";
+    const selection = makeSelection("Hero", hero);
     domEditSelectionRef.current = selection;
     gsapCommitMutation.mockClear();
     gsapCommitMutation.batch.mockClear();
@@ -601,3 +586,22 @@ describe("handleDomEditElementDelete routing", () => {
     expect(handleDomEditElementsDeleteMock).not.toHaveBeenCalled();
   });
 });
+
+describe("a shadow reload promoted without a host re-render", () => {
+  it("hands the promoted iframe to the session's selection and preview sync", async () => {
+    const { useDomEditSession } = await import("./useDomEditSession");
+    const { announcePreviewPromoted } = await import("../player/sceneSwap");
+    const [host, promoted] = [0, 1].map(() => document.createElement("iframe"));
+    function Probe() {
+      useDomEditSession(createSessionParams({ previewIframe: host! }));
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(<Probe />));
+    act(() => announcePreviewPromoted({ retired: host!, live: promoted! }));
+    const last = (hook: string) => iframesHandedOn.findLast((seen) => seen.hook === hook)?.iframe;
+    expect(last("selection")).toBe(promoted);
+    expect(last("wiring")).toBe(promoted);
+    act(() => root.unmount());
+  });
+});

package/src/hooks/useDomEditSession.ts

@@ -24,6 +24,7 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { membersForDelete, timelineElementsForDelete } from "./domEditDeleteMembers";
 import type { RecordEditInput } from "./domEditDeleteMembers";
 import type { DomEditTimelineParams } from "./useDomSelectionTypes";
+import { useLivePreviewIframe } from "./useLivePreviewIframe";
 // Re-exported: the delete rule lives in its own module; callers and its test import it from here.
 export { membersForDelete };
 
@@ -86,14 +87,13 @@ export function useDomEditSession({
   importedFontAssetsRef,
   projectDir,
   projectIdRef,
-  previewIframe,
+  previewIframe: hostPreviewIframe,
   refreshKey,
   previewDocumentVersion,
   rightPanelTab,
   applyStudioManualEditsToPreviewRef,
   syncPreviewHotkeys,
   reloadPreview,
-  setRefreshKey: _setRefreshKey,
   openSourceForSelection,
   sdkSession,
   publishSdkSession,
@@ -103,7 +103,7 @@ export function useDomEditSession({
 }: UseDomEditSessionParams) {
   const isMasterView = !activeCompPath || activeCompPath === "index.html";
   const previewCaptionEditMode = captionEditMode && !readOnlyPreview;
-  void _setRefreshKey;
+  const previewIframe = useLivePreviewIframe(hostPreviewIframe);
   const {
     domEditSelection,
     domEditGroupSelections,
@@ -173,29 +173,11 @@ export function useDomEditSession({
 
   const { version: gsapCacheVersion, bump: bumpGsapCache } = useGsapCacheVersion();
 
-  // ── GSAP script commits ──
-
   const {
     commitMutation: gsapCommitMutation,
-    updateGsapProperty,
-    updateGsapMeta,
-    deleteGsapAnimation,
-    deleteAllForSelector,
-    addGsapAnimation,
-    addGsapProperty,
-    removeGsapProperty,
-    updateGsapFromProperty,
-    addGsapFromProperty,
-    removeGsapFromProperty,
-    addKeyframe,
-    addKeyframeBatch,
-    removeKeyframe,
-    moveKeyframe,
-    resizeKeyframedTween,
-    convertToKeyframes,
-    removeAllKeyframes,
     setArcPath,
     updateArcSegment,
+    ...gsapScriptEdits
   } = useGsapScriptCommits({
     projectIdRef,
     activeCompPath,
@@ -211,8 +193,6 @@ export function useDomEditSession({
     forceReloadSdkSession,
   });
 
-  // ── DOM commit handlers ──
-
   const {
     resolveImportedFontAsset,
     handleDomStyleCommit,
@@ -430,23 +410,7 @@ export function useDomEditSession({
     applyDomSelection,
     buildDomSelectionFromTarget,
     openSourceForSelection,
-    updateGsapProperty,
-    updateGsapMeta,
-    deleteGsapAnimation,
-    deleteAllForSelector,
-    addGsapAnimation,
-    addGsapProperty,
-    removeGsapProperty,
-    updateGsapFromProperty,
-    addGsapFromProperty,
-    removeGsapFromProperty,
-    addKeyframe,
-    addKeyframeBatch,
-    removeKeyframe,
-    moveKeyframe,
-    resizeKeyframedTween,
-    convertToKeyframes,
-    removeAllKeyframes,
+    ...gsapScriptEdits,
     handleDomManualEditsReset,
   });
   const {
@@ -492,8 +456,8 @@ export function useDomEditSession({
     handleDomBoxSizeCommit,
     handleDomRotationCommit: handleDomCssRotationCommit,
     commitPositionPatchToHtml,
-    addGsapAnimation,
-    convertToKeyframes,
+    addGsapAnimation: gsapScriptEdits.addGsapAnimation,
+    convertToKeyframes: gsapScriptEdits.convertToKeyframes,
     setArcPath,
     updateArcSegment,
   });

package/src/hooks/useGsapTweenCache.ts

@@ -336,8 +336,7 @@ export function usePopulateKeyframeCacheForFile(
     // fallow-ignore-next-line complexity
     const tryRuntimeScan = () => {
       if (runtimeScanDoneRef.current === `kf-cache:${projectId}:${sf}:${version}`) return true;
-      const iframe =
-        iframeRef?.current ?? document.querySelector<HTMLIFrameElement>("iframe[src*='/preview/']");
+      const iframe = iframeRef?.current;
       if (!iframe) return false;
       // Clip dims per element so the scan converts tween-relative keyframes to
       // clip-relative (matching the static path) instead of timeline-relative.

package/src/hooks/useInlineTextEdit.ts

@@ -1,6 +1,12 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { sanitizeRichTextChildren } from "@hyperframes/core/rich-text-sanitize";
 import { usePreviewReadOnly } from "../components/editor/previewReadOnlyContext";
+import { trackStudioPendingEdit } from "../utils/studioPendingEdits";
+import {
+  beginStudioManualEditGesture,
+  endStudioManualEditGesture,
+  noteStudioManualEditSave,
+} from "../components/editor/manualEditsDom";
 
 /**
  * Editing an element's text where it sits, in the composition itself.
@@ -43,6 +49,8 @@ export interface InlineTextEditSession {
   outline: string;
   /** The element's own outline offset, restored with the outline. */
   outlineOffset: string;
+  /** Holds the preview on screen while the edit is open. */
+  gesture?: string;
 }
 
 /** The live markup to persist and the session snapshot to restore on failure. */
@@ -86,7 +94,7 @@ export function useInlineTextEdit({
   onPause,
 }: {
   /** Where the edited text goes. The caller owns persistence. */
-  onCommit: (commit: InlineTextEditCommit) => void;
+  onCommit: (commit: InlineTextEditCommit) => unknown;
   /** Stop playback, so the element is not animating under the caret. */
   onPause?: () => void;
 }): InlineTextEditControls {
@@ -106,6 +114,7 @@ export function useInlineTextEdit({
       framesRef.current = null;
     }
     openRef.current = null;
+    endStudioManualEditGesture(open.element, open.gesture);
     setSession(null);
     // An element removed from the document mid-session is not an error, it is
     // just nothing left to clean up.
@@ -132,6 +141,7 @@ export function useInlineTextEdit({
         original: element.innerHTML,
         outline: element.style.outline,
         outlineOffset: element.style.outlineOffset,
+        gesture: beginStudioManualEditGesture(element),
       };
       // Drawn on the element itself, not in Studio's overlay above it. This is
       // the only mark that says the caret is in the TEXT rather than the
@@ -168,10 +178,14 @@ export function useInlineTextEdit({
     // saved rather than something the server will quietly cut down.
     sanitizeRichTextChildren(open.element);
     const html = open.element.innerHTML;
+    // Counted and pending before the edit closes, so a reload waits for the save, not the mark.
+    let save: (saving: unknown) => void = () => {};
+    trackStudioPendingEdit(new Promise((resolve) => (save = resolve)));
+    noteStudioManualEditSave(open.element);
     teardown();
     // After teardown, so the commit path's own resync does not fight an
     // element that is still editable.
-    onCommit({ element: open.element, html, previousHtml: open.original });
+    save(onCommit({ element: open.element, html, previousHtml: open.original }));
   }, [onCommit, teardown]);
 
   const cancel = useCallback(() => {

package/src/hooks/useLivePreviewIframe.ts

@@ -0,0 +1,18 @@
+import { useEffect, useRef, useState } from "react";
+import { onPreviewPromoted } from "../player/sceneSwap";
+
+/** The one source for which preview is on screen: the host's iframe, then each reload promoted in its place. */
+export function useLivePreviewIframe(host: HTMLIFrameElement | null): HTMLIFrameElement | null {
+  const [promoted, setPromoted] = useState<{ host: HTMLIFrameElement; live: HTMLIFrameElement }>();
+  const live = host && promoted?.host === host ? promoted.live : host;
+  const liveRef = useRef(live);
+  liveRef.current = live;
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!host) return;
+    return onPreviewPromoted(host.ownerDocument, ({ retired, live: next }) => {
+      if (retired === liveRef.current) setPromoted({ host, live: next });
+    });
+  }, [host]);
+  return live;
+}

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

@@ -207,16 +207,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],

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/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";

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