@hyperframes/studio 0.8.62 → 0.8.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.62",
+  "version": "0.8.63",
   "description": "",
   "repository": {
     "type": "git",
@@ -51,11 +51,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.62",
-    "@hyperframes/parsers": "0.8.62",
-    "@hyperframes/sdk": "0.8.62",
-    "@hyperframes/player": "0.8.62",
-    "@hyperframes/studio-server": "0.8.62"
+    "@hyperframes/core": "0.8.63",
+    "@hyperframes/player": "0.8.63",
+    "@hyperframes/parsers": "0.8.63",
+    "@hyperframes/sdk": "0.8.63",
+    "@hyperframes/studio-server": "0.8.63"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -71,7 +71,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.62"
+    "@hyperframes/producer": "0.8.63"
   },
   "peerDependencies": {
     "react": "19",

package/src/clipContentExports.test.tsx

@@ -0,0 +1,54 @@
+// @vitest-environment happy-dom
+// Imports the clip-content thumbnail primitives the way a host app does: by package name.
+// Desktop's timeline lane draws audio waveforms and image thumbnails without a deep import.
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { installReactActEnvironment, mountReactHarness } from "./hooks/domSelectionTestHarness";
+
+const { leaseSpy } = vi.hoisted(() => ({
+  leaseSpy: vi.fn((_request: unknown) => ({ status: "loading" as const })),
+}));
+
+vi.mock("./hooks/useThumbnailLease", () => ({
+  useThumbnailLease: leaseSpy,
+}));
+
+import { AudioWaveform, ImageThumbnail, useRenderClipContent } from "@hyperframes/studio";
+
+installReactActEnvironment();
+
+afterEach(() => {
+  leaseSpy.mockClear();
+  document.body.innerHTML = "";
+});
+
+describe("clip content package exports", () => {
+  it("mounts AudioWaveform and leases waveform decoding", async () => {
+    const root = mountReactHarness(
+      <AudioWaveform
+        audioUrl="/media/voice.wav"
+        label=""
+        labelColor="#fff"
+        projectId="project-a"
+        sessionEpoch={9}
+        priority="interaction"
+      />,
+    );
+
+    expect(leaseSpy).toHaveBeenCalledWith(expect.objectContaining({ kind: "waveform" }));
+    await act(async () => root.unmount());
+  });
+
+  it("mounts ImageThumbnail and leases the still frame", async () => {
+    const root = mountReactHarness(
+      <ImageThumbnail imageSrc="/media/frame.png" label="" labelColor="#fff" />,
+    );
+
+    expect(leaseSpy).toHaveBeenCalledWith(expect.objectContaining({ kind: "image" }));
+    await act(async () => root.unmount());
+  });
+
+  it("exposes useRenderClipContent as a hook a host can call", () => {
+    expect(typeof useRenderClipContent).toBe("function");
+  });
+});

package/src/components/nle/TimelinePane.tsx

@@ -1,77 +1,10 @@
-import { useCallback, type ReactNode } from "react";
+import type { ReactNode } from "react";
 import { Timeline } from "../../player";
 import type { TimelineElement, TimelineTimeRange } from "../../player";
 import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
 import { AudioMeterStrip } from "./AudioMeterStrip";
 import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
-import { trackStudioExpandedClipEdit } from "../../telemetry/events";
 import { useNLEContext } from "./NLEContext";
-import type { TimelineMoveOperation } from "../../hooks/timelineMoveAdapter";
-
-type TimelineMoveEdit = {
-  element: TimelineElement;
-  updates: Pick<TimelineElement, "start" | "track">;
-};
-
-export function forwardRebasedTimelineMoveElements(
-  edits: TimelineMoveEdit[],
-  coalesceKey: string | undefined,
-  operation: TimelineMoveOperation | undefined,
-  onMoveElements: (
-    edits: TimelineMoveEdit[],
-    coalesceKey?: string,
-    operation?: TimelineMoveOperation,
-    coalesceMs?: number,
-  ) => Promise<void> | void,
-  coalesceMs?: number,
-) {
-  return onMoveElements(
-    edits.map(({ element, updates }) => {
-      const basis = element.expandedParentStart;
-      if (basis === undefined) return { element, updates };
-      return {
-        element: { ...element, id: element.domId ?? element.id, start: element.start - basis },
-        updates: { ...updates, start: Math.max(0, updates.start - basis) },
-      };
-    }),
-    coalesceKey,
-    operation,
-    coalesceMs,
-  );
-}
-
-type TimelineResizeChange = {
-  element: TimelineElement;
-  start: number;
-  duration: number;
-  playbackStart?: number;
-};
-
-export function forwardRebasedTimelineResizeElements(
-  changes: TimelineResizeChange[],
-  options: { coalesceKey?: string } | undefined,
-  onResizeElements: (
-    changes: TimelineResizeChange[],
-    options?: { coalesceKey?: string },
-  ) => Promise<void> | void,
-) {
-  return onResizeElements(
-    changes.map((change) => {
-      const basis = change.element.expandedParentStart;
-      if (basis === undefined) return change;
-      return {
-        ...change,
-        element: {
-          ...change.element,
-          id: change.element.domId ?? change.element.id,
-          start: change.element.start - basis,
-        },
-        start: Math.max(0, change.start - basis),
-      };
-    }),
-    options,
-  );
-}
 
 export interface TimelinePaneProps {
   /** Slot rendered above the timeline tracks (toolbar with split, delete, zoom) */
@@ -114,7 +47,6 @@ export interface TimelinePaneProps {
   canPasteClip?: () => boolean;
 }
 
-// fallow-ignore-next-line complexity
 export function TimelinePane({
   timelineToolbar,
   timelineFooter,
@@ -142,119 +74,10 @@ export function TimelinePane({
     timelineSessionEpoch,
   } = useNLEContext();
 
-  // Move/resize/split come from the timeline edit context, not props — the
-  // wrappers below intercept expanded clips and must call the *real* handlers.
-  // (Delete is a direct prop; it stays that way.)
+  // Move/resize/split come from the timeline edit context, not props.
   const { onMoveElement, onMoveElements, onResizeElement, onResizeElements, onSplitElement } =
     useTimelineEditContext();
 
-  // An expanded sub-comp child reaches the normal edit handlers in its own
-  // local coordinates: addressed by its real DOM id, with timeline time rebased
-  // onto the sub-comp it lives in. The handlers then save + reloadPreview exactly
-  // as they do for top-level clips — no separate live-DOM path.
-  const toLocalElement = useCallback(
-    (element: TimelineElement, basis: number): TimelineElement => ({
-      ...element,
-      id: element.domId ?? element.id,
-      start: element.start - basis,
-    }),
-    [],
-  );
-
-  const handleMoveElement = useCallback(
-    (element: TimelineElement, updates: Pick<TimelineElement, "start" | "track">) => {
-      const basis = element.expandedParentStart;
-      if (basis === undefined) return onMoveElement?.(element, updates);
-      trackStudioExpandedClipEdit({ action: "move" });
-      onMoveElement?.(toLocalElement(element, basis), {
-        ...updates,
-        start: Math.max(0, updates.start - basis),
-      });
-    },
-    [onMoveElement, toLocalElement],
-  );
-
-  // Batched move (ripple / insert): rebase each expanded sub-comp child to its
-  // local coords, exactly as handleMoveElement does for a single clip.
-  const handleMoveElements = useCallback(
-    (
-      edits: Array<{ element: TimelineElement; updates: Pick<TimelineElement, "start" | "track"> }>,
-      coalesceKey?: string,
-      operation?: TimelineMoveOperation,
-      coalesceMs?: number,
-    ) => {
-      // Match the sibling handlers: report the telemetry when the batch touches at
-      // least one expanded sub-comp child (the clips being rebased to local coords).
-      if (edits.some(({ element }) => element.expandedParentStart !== undefined)) {
-        trackStudioExpandedClipEdit({ action: "move" });
-      }
-      if (!onMoveElements) return;
-      return forwardRebasedTimelineMoveElements(
-        edits,
-        coalesceKey,
-        operation,
-        onMoveElements,
-        coalesceMs,
-      );
-    },
-    [onMoveElements],
-  );
-
-  const handleResizeElement = useCallback(
-    (
-      element: TimelineElement,
-      updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
-    ) => {
-      const basis = element.expandedParentStart;
-      if (basis === undefined) return onResizeElement?.(element, updates);
-      trackStudioExpandedClipEdit({ action: "resize" });
-      onResizeElement?.(toLocalElement(element, basis), {
-        ...updates,
-        start: Math.max(0, updates.start - basis),
-      });
-    },
-    [onResizeElement, toLocalElement],
-  );
-
-  const handleResizeElements = useCallback(
-    (
-      changes: Array<{
-        element: TimelineElement;
-        start: number;
-        duration: number;
-        playbackStart?: number;
-      }>,
-      options?: { coalesceKey?: string },
-    ) => {
-      if (!onResizeElements) return;
-      if (changes.some(({ element }) => element.expandedParentStart !== undefined)) {
-        trackStudioExpandedClipEdit({ action: "resize" });
-      }
-      return forwardRebasedTimelineResizeElements(changes, options, onResizeElements);
-    },
-    [onResizeElements],
-  );
-
-  const handleDeleteElement = useCallback(
-    (element: TimelineElement) => {
-      const basis = element.expandedParentStart;
-      if (basis === undefined) return onDeleteElement?.(element);
-      trackStudioExpandedClipEdit({ action: "delete" });
-      return onDeleteElement?.(toLocalElement(element, basis));
-    },
-    [onDeleteElement, toLocalElement],
-  );
-
-  const handleSplitElement = useCallback(
-    (element: TimelineElement, splitTime: number) => {
-      const basis = element.expandedParentStart;
-      if (basis === undefined) return onSplitElement?.(element, splitTime);
-      trackStudioExpandedClipEdit({ action: "split" });
-      return onSplitElement?.(toLocalElement(element, basis), Math.max(0, splitTime - basis));
-    },
-    [onSplitElement, toLocalElement],
-  );
-
   return (
     <div
       className="relative flex h-full flex-col"
@@ -280,16 +103,16 @@ export function TimelinePane({
               onDrillDown={handleDrillDown}
               renderClipContent={renderClipContent}
               onFileDrop={onFileDrop}
-              onDeleteElement={handleDeleteElement}
+              onDeleteElement={onDeleteElement}
               onAssetDrop={onAssetDrop}
               onBlockDrop={onBlockDrop}
               onCompositionDrop={onCompositionDrop}
-              onMoveElement={handleMoveElement}
-              onMoveElements={handleMoveElements}
-              onResizeElement={handleResizeElement}
-              onResizeElements={handleResizeElements}
+              onMoveElement={onMoveElement}
+              onMoveElements={onMoveElements}
+              onResizeElement={onResizeElement}
+              onResizeElements={onResizeElements}
               onBlockedEditAttempt={onBlockedEditAttempt}
-              onSplitElement={handleSplitElement}
+              onSplitElement={onSplitElement}
               onSelectElement={onSelectTimelineElement}
               onRangeSelect={onRangeSelect}
               onCopyClip={onCopyClip}

package/src/components/nle/useCanvasZOrderTimelineMirror.test.tsx

@@ -321,55 +321,6 @@ describe("useCanvasZOrderTimelineMirror", () => {
     expect(history.moveCoalesceKeys).toEqual([]);
   });
 
-  it("maps the crossed neighbor to its timeline key and rebases expanded sub-comp children", async () => {
-    // t is an expanded sub-comp child (expandedParentStart 5, absolute start 5):
-    // the mirror must forward its persist in LOCAL time (start 0), the same
-    // rebase a timeline lane drag applies (forwardRebasedTimelineMoveElements).
-    setStoreElements([
-      {
-        ...storeEl("a", 0, 25, 5),
-        sourceFile: "sub.html",
-        key: "sub.html#a",
-        expandedParentStart: 5,
-      },
-      {
-        ...storeEl("b", 1, 5, 10),
-        sourceFile: "sub.html",
-        key: "sub.html#b",
-        expandedParentStart: 5,
-      },
-      {
-        ...storeEl("t", 2, 5, 10),
-        sourceFile: "sub.html",
-        key: "sub.html#t",
-        expandedParentStart: 5,
-      },
-    ]);
-    const edits: Array<{ element: TimelineElement; updates: { start: number; track: number } }> =
-      [];
-    const onMoveElements: TimelineEditCallbacks["onMoveElements"] = (batch) => {
-      edits.push(...batch);
-    };
-    const { mirror } = mountMirrorOnlyHarness(onMoveElements);
-
-    const mirrored = await act(async () =>
-      mirror({
-        selectionKey: "sub.html#t",
-        action: "bring-forward",
-        // The crossed sibling maps to sub.html#b via its DOM id + sourceFile —
-        // the same derivation reorder entries use (deriveTimelineStoreKey).
-        crossed: domTarget("b"),
-        sourceFile: "sub.html",
-        coalesceKey: "z-reorder:bring-forward:t",
-      }),
-    );
-    expect(mirrored).toBe(true);
-    expect(edits).toHaveLength(1);
-    // Rebased to sub-comp local coords: absolute 5 − parent start 5 = 0.
-    expect(edits[0].element.start).toBe(0);
-    expect(edits[0].updates).toMatchObject({ start: 0, track: 0 });
-  });
-
   it("maps a cross-file duplicate selector to the source-scoped crossed occurrence", async () => {
     setStoreElements([
       {

package/src/components/nle/useCanvasZOrderTimelineMirror.ts

@@ -13,7 +13,6 @@ import { commitZMirrorLaneMove } from "../../player/components/timelineClipDragC
 import { deriveTimelineStoreKey } from "../../player/lib/timelineElementHelpers";
 import { buildStableSelector, getSelectorIndex } from "../editor/domEditingDom";
 import { useStudioShellContextOptional } from "../../contexts/StudioContext";
-import { forwardRebasedTimelineMoveElements } from "./TimelinePane";
 
 export interface MirrorZOrderInput {
   /** Timeline store key of the element the menu acted on (entry.key), if any. */
@@ -44,10 +43,9 @@ export interface MirrorZOrderInput {
  * renders and the resolver expects. No alternate row expansion is built here.
  *
  * The mirror persists through the SAME machinery as a timeline lane drag
- * (commitZMirrorLaneMove → persistMoveEdits → onMoveElements, with expanded
- * children rebased to local coords via forwardRebasedTimelineMoveElements) —
- * optimistic store update + rollback included, so the timeline reflects the
- * lane change without a reload. The deps below deliberately OMIT
+ * (commitZMirrorLaneMove → persistMoveEdits → onMoveElements) — optimistic
+ * store update + rollback included, so the timeline reflects the lane change
+ * without a reload. The deps below deliberately OMIT
  * `readZIndex`/`onStackingPatches`: the lane→z stacking sync
  * (syncStackingForEdit) must not fire and recompute the z values the user just
  * set — commitZMirrorLaneMove never calls it, and without these deps it would
@@ -160,16 +158,7 @@ function useMirrorLaneMoveCommit(): (
           elements: els,
           trackOrder: displayTrackOrder(els),
           updateElement: (key, updates) => usePlayerStore.getState().updateElement(key, updates),
-          onMoveElements: onMoveElements
-            ? (edits, coalesceKey2, operation, coalesceMs) =>
-                forwardRebasedTimelineMoveElements(
-                  edits,
-                  coalesceKey2,
-                  operation,
-                  onMoveElements,
-                  coalesceMs,
-                )
-            : undefined,
+          onMoveElements,
           // NO readZIndex / onStackingPatches: see the hook doc — the lane→z
           // stacking sync must not re-trigger and fight the just-set z values.
         },

package/src/components/ui/VideoFrameThumbnail.test.tsx

@@ -0,0 +1,170 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { VideoFrameThumbnail } from "./VideoFrameThumbnail";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+// The component builds its thumbnail from document.createElement("video"/"canvas"),
+// so both are faked here. The video fake records load() calls and keeps listener
+// sets, letting a test re-fire an event handler after cleanup removed it — the
+// exact shape of the error→cleanup→error loop this suite guards against.
+interface FakeVideo {
+  crossOrigin: string;
+  muted: boolean;
+  preload: string;
+  duration: number;
+  videoWidth: number;
+  videoHeight: number;
+  currentTime: number;
+  loadCalls: number;
+  _src: string;
+  src: string;
+  addEventListener(type: string, fn: () => void): void;
+  removeEventListener(type: string, fn: () => void): void;
+  getAttribute(name: string): string | null;
+  load(): void;
+  dispatch(type: string): void;
+}
+
+function makeVideo(): FakeVideo {
+  const listeners = new Map<string, Set<() => void>>();
+  const video: FakeVideo = {
+    crossOrigin: "",
+    muted: false,
+    preload: "",
+    duration: 10,
+    videoWidth: 640,
+    videoHeight: 360,
+    currentTime: 0,
+    loadCalls: 0,
+    _src: "",
+    src: "",
+    addEventListener(type, fn) {
+      if (!listeners.has(type)) listeners.set(type, new Set());
+      listeners.get(type)!.add(fn);
+    },
+    removeEventListener(type, fn) {
+      listeners.get(type)?.delete(fn);
+    },
+    getAttribute(name) {
+      return name === "src" ? video.src : null;
+    },
+    load() {
+      video.loadCalls++;
+    },
+    dispatch(type) {
+      for (const fn of [...(listeners.get(type) ?? [])]) fn();
+    },
+  };
+  Object.defineProperty(video, "src", {
+    get: () => video._src,
+    set: (v: string) => {
+      video._src = v;
+    },
+  });
+  return video;
+}
+
+const canvas = {
+  width: 0,
+  height: 0,
+  getContext: () => ({ drawImage: () => {} }),
+  toDataURL: () => "data:image/jpeg;base64,AAAA",
+};
+
+describe("VideoFrameThumbnail", () => {
+  let videos: FakeVideo[];
+  let root: Root;
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    videos = [];
+    const original = document.createElement.bind(document);
+    vi.spyOn(document, "createElement").mockImplementation(((tag: string) => {
+      if (tag === "video") {
+        const v = makeVideo();
+        videos.push(v);
+        return v as unknown as HTMLVideoElement;
+      }
+      if (tag === "canvas") return canvas as unknown as HTMLCanvasElement;
+      return original(tag);
+    }) as typeof document.createElement);
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.restoreAllMocks();
+  });
+
+  const render = (props: { src: string; fallbackLabel?: string }) => {
+    act(() => root.render(<VideoFrameThumbnail {...props} />));
+    return videos[videos.length - 1];
+  };
+
+  it("renders the fallback label when the video errors", () => {
+    render({ src: "missing.mp4", fallbackLabel: "VIDEO" });
+    const video = videos[0];
+    expect(video.src).toBe("missing.mp4");
+    expect(video.loadCalls).toBe(1);
+
+    act(() => video.dispatch("error"));
+
+    expect(container.textContent).toContain("VIDEO");
+    // cleanup ran once: detached the error listener and reset the media element
+    expect(video.src).toBe("");
+    expect(video.loadCalls).toBe(2);
+  });
+
+  it("does not loop when the cleared src fires a synthetic error", () => {
+    render({ src: "missing.mp4", fallbackLabel: "VIDEO" });
+    const video = videos[0];
+    act(() => video.dispatch("error"));
+    expect(video.loadCalls).toBe(2);
+
+    // The empty src makes the browser fire `error` again; the detached handler
+    // must stay detached — repeated dispatches must not touch load() anymore.
+    act(() => {
+      video.dispatch("error");
+      video.dispatch("error");
+      video.dispatch("error");
+    });
+
+    expect(video.loadCalls).toBe(2);
+    expect(container.textContent).toContain("VIDEO");
+  });
+
+  it("keeps the extracted frame and stays inert after a post-seek synthetic error", () => {
+    render({ src: "clip.mp4" });
+    const video = videos[0];
+
+    act(() => video.dispatch("loadedmetadata"));
+    expect(video.currentTime).toBe(1); // 10% of a 10s clip
+
+    act(() => video.dispatch("seeked"));
+    const img = container.querySelector("img");
+    expect(img?.getAttribute("src")).toBe("data:image/jpeg;base64,AAAA");
+    expect(video.src).toBe("");
+    expect(video.loadCalls).toBe(2);
+
+    act(() => {
+      video.dispatch("error");
+      video.dispatch("error");
+    });
+
+    expect(container.querySelector("img")?.getAttribute("src")).toBe("data:image/jpeg;base64,AAAA");
+    expect(video.loadCalls).toBe(2);
+  });
+
+  it("retries with a fresh video element when src changes", () => {
+    render({ src: "a.mp4" });
+    act(() => root.render(<VideoFrameThumbnail src="b.mp4" />));
+    expect(videos.length).toBe(2);
+    expect(videos[1].src).toBe("b.mp4");
+  });
+});

package/src/components/ui/VideoFrameThumbnail.tsx

@@ -26,10 +26,19 @@ export function VideoFrameThumbnail({
     const canvas = document.createElement("canvas");
     const ctx = canvas.getContext("2d");
 
+    // Clearing src fires one more `error` on the video, so the error handler
+    // must be detached first — otherwise error → cleanup → error spins forever.
     const cleanup = () => {
+      video.removeEventListener("error", onError);
       video.src = "";
       video.load();
     };
+    const onError = () => {
+      // Ignore the synthetic error cleanup itself just triggered.
+      if (!video.getAttribute("src")) return;
+      setFailed(true);
+      cleanup();
+    };
 
     video.addEventListener("loadedmetadata", () => {
       video.currentTime = Math.min(2, video.duration * 0.1 || 2);
@@ -44,11 +53,7 @@ export function VideoFrameThumbnail({
       cleanup();
     });
 
-    video.addEventListener("error", () => {
-      // Resolve the loading state — a permanent shimmer reads as "still loading".
-      setFailed(true);
-      cleanup();
-    });
+    video.addEventListener("error", onError);
     video.src = src;
     video.load();
 

package/src/hooks/useRenderClipContent.ts

@@ -97,7 +97,7 @@ function renderAudioClip(
   });
 }
 
-interface UseRenderClipContentOptions {
+export interface UseRenderClipContentOptions {
   projectIdRef: { current: string | null };
   compIdToSrc: Map<string, string>;
   activePreviewUrl: string | null;

package/src/index.ts

@@ -77,6 +77,16 @@ export {
 export { TimelineProvider, useTimelineContext } from "./player/components/TimelineProvider";
 export type { TimelineTheme } from "./player/components/timelineTheme";
 
+// Clip content thumbnails: used by a host rendering its own timeline lane.
+export { AudioWaveform } from "./player/components/AudioWaveform";
+export type { AudioWaveformProps } from "./player/components/AudioWaveform";
+export { ImageThumbnail } from "./player/components/ImageThumbnail";
+export type { ImageThumbnailProps } from "./player/components/ImageThumbnail";
+export { useRenderClipContent } from "./hooks/useRenderClipContent";
+export type { UseRenderClipContentOptions } from "./hooks/useRenderClipContent";
+export type { ThumbnailPriority } from "./player/lib/thumbnailScheduler";
+export type { TimelineClipRenderContext } from "./player/components/TimelineTypes";
+
 // Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
 export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";
 export type { PreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";

package/src/player/components/AudioWaveform.tsx

@@ -4,7 +4,7 @@ import { useThumbnailLease } from "../../hooks/useThumbnailLease";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { decimatePeaks, loudnessToOpacity } from "./audioWaveformPeaks";
 
-interface AudioWaveformProps {
+export interface AudioWaveformProps {
   audioUrl: string;
   waveformUrl?: string;
   label: string;

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

@@ -137,6 +137,13 @@ describe("CompositionThumbnail", () => {
     const tiles = [...host.querySelectorAll("img")];
     expect(tiles.length).toBeGreaterThan(0);
     expect(tiles.every((tile) => !tile.classList.contains("hidden"))).toBe(true);
+    // Pictures read untinted by default, like video filmstrips; the theme tokens own any dimming.
+    expect(
+      tiles.every((tile) => tile.style.opacity === "var(--timeline-composition-thumbnail-opacity)"),
+    ).toBe(true);
+    expect(tiles[0]?.parentElement?.parentElement?.style.mixBlendMode).toBe(
+      "var(--timeline-composition-thumbnail-blend)",
+    );
   });
 
   it("aborts its scheduled off-DOM image probe when unmounted", async () => {