@hyperframes/studio 0.8.107 → 0.8.109

package/src/hooks/useTimelineEditing.ts

@@ -27,6 +27,12 @@ import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
 import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
 import { useSetElementAttribute } from "./timelineElementFxAttribute";
 import { useTimelineDeleteOps } from "./useTimelineDeleteOps";
+import { useTimelineEditGuard } from "./useTimelineEditGuard";
+import {
+  linkEditTargets,
+  useTimelineLinkEditing,
+  withLinkPartners,
+} from "./useTimelineLinkEditing";
 import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
 import { useAudioGroupCarveAssignment } from "./timelineAudioGroupCreate";
 import {
@@ -35,26 +41,12 @@ import {
 } from "./timelineTrackVisibility";
 import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
 import { useBlockedTimelineEditToast } from "./useBlockedTimelineEditToast";
-import {
-  useTimelineEditGate,
-  useTimelineEditRefusal,
-  type TimelineEditOutcome,
-} from "./timelineEditPermission";
+import { useTimelineEditGate, type TimelineEditOutcome } from "./timelineEditPermission";
 import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
 import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
 import type { TimelineMoveUpdates, UseTimelineEditingOptions } from "./useTimelineEditingTypes";
 import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
 
-type GuardedTimelineHandler = (...args: never[]) => Promise<unknown>;
-type GuardedTimelineResolver = (...args: never[]) => readonly TimelineElement[];
-type GuardedTimelineRefusal = (reason: string, ...args: never[]) => unknown;
-
-interface GuardedTimelineEntry {
-  resolveTargets: GuardedTimelineResolver;
-  onRefused?: GuardedTimelineRefusal;
-  wrapped: GuardedTimelineHandler;
-}
-
 export function useTimelineEditing({
   projectId,
   activeCompPath,
@@ -80,40 +72,7 @@ export function useTimelineEditing({
   const editQueueRef = useRef(Promise.resolve());
   const track = useTrackPendingTimelineEdit();
   const checkEditable = useTimelineEditGate(canEdit, showToast);
-  const refuseEdit = useTimelineEditRefusal(canEdit, showToast);
-  const refuseEditRef = useRef(refuseEdit);
-  refuseEditRef.current = refuseEdit;
-  const guardedRef = useRef(new WeakMap<GuardedTimelineHandler, GuardedTimelineEntry>());
-  // Refuses (no call, no write, no history entry) when any target is
-  // blocked; otherwise runs fn as before. Cached by fn identity — like
-  // track() — so a fresh closure here doesn't defeat track's own cache.
-  const guard = useCallback(
-    <H extends (...args: never[]) => Promise<unknown>>(
-      resolveTargets: (...args: Parameters<H>) => readonly TimelineElement[],
-      fn: H,
-      onRefused?: (reason: string, ...args: Parameters<H>) => Awaited<ReturnType<H>>,
-    ): H => {
-      const key = fn as unknown as GuardedTimelineHandler;
-      const cached = guardedRef.current.get(key);
-      if (cached) {
-        cached.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
-        cached.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
-        return cached.wrapped as H;
-      }
-      const entry = {} as GuardedTimelineEntry;
-      entry.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
-      entry.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
-      entry.wrapped = ((...args: Parameters<H>) => {
-        const reason = refuseEditRef.current(entry.resolveTargets(...(args as never[])));
-        if (reason !== null)
-          return Promise.resolve(entry.onRefused?.(reason, ...(args as never[])));
-        return fn(...args);
-      }) as H as unknown as GuardedTimelineHandler;
-      guardedRef.current.set(key, entry);
-      return entry.wrapped as H;
-    },
-    [],
-  );
+  const guard = useTimelineEditGuard(canEdit, showToast);
 
   const enqueueEdit = useCallback(
     (
@@ -252,7 +211,7 @@ export function useTimelineEditing({
         return reorderDone
           .then(() => {
             // SDK setTiming writes start only; a lane change needs the fallback's track patch.
-            if (sdkSession && element.hfId && !needsExtension && !trackChanged) {
+            if (sdkSession && element.hfId && !element.link && !needsExtension && !trackChanged) {
               return sdkTimingPersist(
                 element.hfId,
                 targetPath,
@@ -359,7 +318,7 @@ export function useTimelineEditing({
           finishResizeGsapSync(),
         );
       const persistDone =
-        sdkSession && element.hfId && !hasPbsAdjustment && !needsExtension
+        sdkSession && element.hfId && !element.link && !hasPbsAdjustment && !needsExtension
           ? sdkTimingPersist(
               element.hfId,
               targetPath,
@@ -461,7 +420,7 @@ export function useTimelineEditing({
     isRecordingRef,
   });
 
-  const { handleTimelineElementsDelete, handleTimelineElementDelete } = useTimelineDeleteOps({
+  const { handleTimelineElementsDelete } = useTimelineDeleteOps({
     projectIdRef,
     activeCompPath,
     timelineElements,
@@ -491,9 +450,22 @@ export function useTimelineEditing({
       checkEditable,
     });
 
-  const handleBlockedTimelineEdit = useBlockedTimelineEditToast(showToast);
+  const linkEditing = useTimelineLinkEditing({
+    projectIdRef,
+    activeCompPath,
+    editQueueRef,
+    pendingTimelineEditPathRef,
+    isRecordingRef,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    reloadPreview,
+    forceReloadSdkSession,
+    handleTimelineElementsDelete,
+  });
 
-  const { handleRazorSplit, handleRazorSplitAll } = useRazorSplit({
+  const handleBlockedTimelineEdit = useBlockedTimelineEditToast(showToast);
+  const { handleRazorSplit, handleRazorSplitAll, handleFreezeFrame } = useRazorSplit({
     projectId,
     activeCompPath,
     showToast,
@@ -527,7 +499,9 @@ export function useTimelineEditing({
   // Every write-handler is tracked here, the one place all hand edits
   // converge, so undo never races a write; canEdit gates the same point.
   // Coverage boundary: see the PR body, not every kind resolves an element.
-  const trackedRazorSplit = track(guard((element) => [element], handleRazorSplit));
+  const trackedRazorSplit = track(
+    guard((element) => withLinkPartners([element]), handleRazorSplit),
+  );
   return {
     handleTimelineElementMove: track(guard((element) => [element], handleTimelineElementMove)),
     handleTimelineElementResize: track(guard((element) => [element], handleTimelineElementResize)),
@@ -569,12 +543,19 @@ export function useTimelineEditing({
         ),
       ),
     },
-    handleTimelineElementDelete: track(guard((element) => [element], handleTimelineElementDelete)),
+    handleTimelineElementDelete: track(
+      guard((element) => withLinkPartners([element]), linkEditing.handleLinkedElementDelete),
+    ),
     handleTimelineElementsDelete: track(
-      guard((elements) => elements, handleTimelineElementsDelete),
+      guard(withLinkPartners, linkEditing.handleLinkedElementsDelete),
+    ),
+    handleTimelineElementDeleteOnly: track(
+      guard((element) => [element], linkEditing.handleDeleteElementOnly),
     ),
+    handleLinkEdit: track(guard(linkEditTargets, linkEditing.handleLinkEdit)),
     handleTimelineElementSplit: trackedRazorSplit,
     handleRazorSplit: trackedRazorSplit,
+    handleFreezeFrame: track(guard((element) => [element], handleFreezeFrame)),
     // Same selection the handler itself splits (useRazorSplit.ts).
     handleRazorSplitAll: track(
       guard(

package/src/hooks/useTimelineLinkEditing.test.tsx

@@ -0,0 +1,112 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../player";
+import { useTimelineLinkEditing, withLinkPartners } from "./useTimelineLinkEditing";
+import { useLinkedClipPreferences } from "../utils/linkedClipPreferences";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const clip = (id: string, tag: string, link?: string): TimelineElement => ({
+  id,
+  domId: id,
+  tag,
+  start: 0,
+  duration: 4,
+  track: 0,
+  ...(link ? { link } : {}),
+});
+const video = clip("talk", "video", "lk-1");
+const audio = clip("talk-audio", "audio", "lk-1");
+const title = clip("title", "div");
+
+const SOURCE =
+  '<div><video id="talk" muted data-link="lk-1"></video><audio id="talk-audio" data-link="lk-1"></audio></div>';
+
+async function renderLinkEditing(handleTimelineElementsDelete = vi.fn()) {
+  usePlayerStore.getState().setElements([video, audio, title]);
+  const writeProjectFile = vi.fn().mockResolvedValue(undefined);
+  const recordEdit = vi.fn().mockResolvedValue(undefined);
+  let api: ReturnType<typeof useTimelineLinkEditing> | undefined;
+  function Harness() {
+    api = useTimelineLinkEditing({
+      projectIdRef: { current: "p1" },
+      activeCompPath: "index.html",
+      editQueueRef: { current: Promise.resolve() },
+      pendingTimelineEditPathRef: { current: new Set() },
+      showToast: vi.fn(),
+      writeProjectFile,
+      recordEdit,
+      reloadPreview: vi.fn(),
+      handleTimelineElementsDelete,
+    });
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  await act(async () => root.render(React.createElement(Harness)));
+  if (!api) throw new Error("hook did not render");
+  return { api, writeProjectFile, recordEdit, unmount: () => act(() => root.unmount()) };
+}
+
+describe("withLinkPartners", () => {
+  it("adds partners after the selection, once", () => {
+    usePlayerStore.getState().setElements([video, audio, title]);
+    expect(withLinkPartners([video, title]).map((el) => el.id)).toEqual([
+      "talk",
+      "title",
+      "talk-audio",
+    ]);
+    expect(withLinkPartners([video, audio])).toHaveLength(2);
+  });
+});
+
+describe("useTimelineLinkEditing", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("deletes a linked clip with its partner", async () => {
+    const del = vi.fn().mockResolvedValue(undefined);
+    const { api, unmount } = await renderLinkEditing(del);
+    await act(async () => api.handleLinkedElementDelete(video));
+    expect(del.mock.calls[0]?.[0].map((el: TimelineElement) => el.id)).toEqual([
+      "talk",
+      "talk-audio",
+    ]);
+    unmount();
+  });
+
+  it("with Linked Selection off, delete removes the clip alone and unlinks the survivor", async () => {
+    const del = vi.fn().mockResolvedValue(undefined);
+    const { api, unmount } = await renderLinkEditing(del);
+    useLinkedClipPreferences.getState().setLinkedSelection(false);
+    try {
+      expect(withLinkPartners([video])).toEqual([video]);
+      await act(async () => api.handleLinkedElementDelete(video));
+      expect(del).toHaveBeenCalledWith([video], [audio]);
+    } finally {
+      useLinkedClipPreferences.getState().setLinkedSelection(true);
+    }
+    unmount();
+  });
+
+  it("delete-only removes one member and unlinks the survivor", async () => {
+    const del = vi.fn().mockResolvedValue(undefined);
+    const { api, unmount } = await renderLinkEditing(del);
+    await act(async () => api.handleDeleteElementOnly(video));
+    expect(del).toHaveBeenCalledWith([video], [audio]);
+    unmount();
+  });
+
+  it("unlink writes one undo step removing data-link from both", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ content: SOURCE }), { status: 200 }),
+    );
+    const { api, writeProjectFile, recordEdit, unmount } = await renderLinkEditing();
+    await act(async () => api.handleLinkEdit({ kind: "unlink", elements: [video, audio] }));
+    expect(writeProjectFile).toHaveBeenCalledTimes(1);
+    expect(writeProjectFile.mock.calls[0]?.[1]).not.toContain("data-link");
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    expect(recordEdit.mock.calls[0]?.[0].label).toBe("Unlink clips");
+    unmount();
+  });
+});

package/src/hooks/useTimelineLinkEditing.ts

@@ -0,0 +1,153 @@
+import { useCallback, type MutableRefObject } from "react";
+import { usePlayerStore, type TimelineElement } from "../player";
+import type { TimelineLinkEdit } from "../player/components/timelineCallbacks";
+import { expandToLinkedMembers } from "../player/components/audioClipLink";
+import { isLinkedSelectionOn } from "../utils/linkedClipPreferences";
+import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
+import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
+import { readFileContent } from "./timelineEditingHelpers";
+import { clipsToUnlink, planLinkEdit } from "./timelineLinkEditPlan";
+
+interface UseTimelineLinkEditingOptions {
+  projectIdRef: MutableRefObject<string | null>;
+  activeCompPath: string | null;
+  editQueueRef: MutableRefObject<Promise<void>>;
+  pendingTimelineEditPathRef: MutableRefObject<Set<string>>;
+  isRecordingRef?: MutableRefObject<boolean>;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  reloadPreview: () => void;
+  forceReloadSdkSession?: () => void;
+  handleTimelineElementsDelete: (
+    selection: TimelineElement[],
+    alsoUnlink?: readonly TimelineElement[],
+  ) => Promise<void>;
+}
+
+const keyOf = (el: TimelineElement) => el.key ?? el.id;
+
+/** Every clip a link edit writes, for the edit-permission gate. */
+export function linkEditTargets(edit: TimelineLinkEdit): TimelineElement[] {
+  switch (edit.kind) {
+    case "unlink":
+    case "link":
+      return [...edit.elements];
+    case "detach":
+    case "move-into-sync":
+    case "slip-into-sync":
+      return [edit.element];
+    case "merge":
+      return [edit.video, edit.audio];
+  }
+}
+
+export function withLinkPartners(selection: readonly TimelineElement[]): TimelineElement[] {
+  const elements = usePlayerStore.getState().elements;
+  const keys = expandToLinkedMembers(selection.map(keyOf), elements, isLinkedSelectionOn());
+  const known = new Set(selection.map(keyOf));
+  return [...selection, ...elements.filter((el) => keys.has(keyOf(el)) && !known.has(keyOf(el)))];
+}
+
+export function useTimelineLinkEditing({
+  projectIdRef,
+  activeCompPath,
+  editQueueRef,
+  pendingTimelineEditPathRef,
+  isRecordingRef,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  reloadPreview,
+  forceReloadSdkSession,
+  handleTimelineElementsDelete,
+}: UseTimelineLinkEditingOptions) {
+  const handleLinkEdit = useCallback(
+    async (edit: TimelineLinkEdit) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      const plan = planLinkEdit(edit, usePlayerStore.getState().elements);
+      if (!pid || !plan) return;
+      const path = plan.anchor.sourceFile || activeCompPath || "index.html";
+      pendingTimelineEditPathRef.current.add(path);
+      const queued = editQueueRef.current.then(() =>
+        saveProjectFilesWithHistory({
+          projectId: pid,
+          label: plan.label,
+          files: {
+            [path]: (current) => {
+              const next = plan.transform(current);
+              if (next === null || next === current) {
+                throw new Error(`Couldn't ${plan.label.toLowerCase()}`);
+              }
+              return next;
+            },
+          },
+          readFile: (filePath) => readFileContent(pid, filePath),
+          writeFile: writeProjectFile,
+          recordEdit,
+        }),
+      );
+      editQueueRef.current = queued.then(
+        () => undefined,
+        () => undefined,
+      );
+      try {
+        await queued;
+        forceReloadSdkSession?.();
+        reloadPreview();
+      } catch (error) {
+        showToast(getStudioSaveErrorMessage(error), "error");
+      }
+    },
+    [
+      activeCompPath,
+      editQueueRef,
+      forceReloadSdkSession,
+      isRecordingRef,
+      pendingTimelineEditPathRef,
+      projectIdRef,
+      recordEdit,
+      reloadPreview,
+      showToast,
+      writeProjectFile,
+    ],
+  );
+
+  const handleLinkedElementsDelete = useCallback(
+    (selection: TimelineElement[]) => {
+      if (isLinkedSelectionOn()) return handleTimelineElementsDelete(withLinkPartners(selection));
+      const removed = new Set(selection.map(keyOf));
+      const orphans = clipsToUnlink(selection, usePlayerStore.getState().elements).filter(
+        (el) => !removed.has(keyOf(el)),
+      );
+      return handleTimelineElementsDelete(selection, orphans);
+    },
+    [handleTimelineElementsDelete],
+  );
+
+  const handleLinkedElementDelete = useCallback(
+    (element: TimelineElement) => handleLinkedElementsDelete([element]),
+    [handleLinkedElementsDelete],
+  );
+
+  const handleDeleteElementOnly = useCallback(
+    (element: TimelineElement) => {
+      const orphans = clipsToUnlink([element], usePlayerStore.getState().elements).filter(
+        (el) => keyOf(el) !== keyOf(element),
+      );
+      return handleTimelineElementsDelete([element], orphans);
+    },
+    [handleTimelineElementsDelete],
+  );
+
+  return {
+    handleLinkEdit,
+    handleLinkedElementsDelete,
+    handleLinkedElementDelete,
+    handleDeleteElementOnly,
+  };
+}

package/src/index.ts

@@ -31,6 +31,7 @@ export {
   liveTime,
   formatTime,
 } from "./player";
+export { usePreviewIframeStore } from "./player/store/previewIframeStore";
 export type {
   PlayerHandle,
   PlayerHandleElement,
@@ -175,6 +176,7 @@ export { TimelineHistoryButtons } from "./components/TimelineHistoryButtons";
 export type { TimelineHistoryButtonsProps } from "./components/TimelineHistoryButtons";
 export { AudioMeterStrip } from "./components/nle/AudioMeterStrip";
 export type { AudioMeterStripProps } from "./components/nle/AudioMeterStrip";
+export { useAudioMetersVisible } from "./utils/audioMeterVisibility";
 export { useClipboard } from "./hooks/useClipboard";
 export type { UseClipboardOptions } from "./hooks/useClipboard";
 

package/src/player/components/AudibleVideoClipContent.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from "react";
+
+/** Share of the clip height the sound strip takes under a video's thumbnails. */
+const AUDIBLE_VIDEO_WAVE_SHARE = 0.38;
+
+/** A video that carries sound: thumbnails on top, its waveform strip along the bottom. */
+export function AudibleVideoClipContent({
+  thumbnail,
+  waveform,
+}: {
+  thumbnail: ReactNode;
+  waveform: ReactNode;
+}) {
+  const waveHeight = `${AUDIBLE_VIDEO_WAVE_SHARE * 100}%`;
+  return (
+    <div className="relative h-full w-full" data-testid="audible-video-clip">
+      <div className="absolute inset-x-0 top-0" style={{ bottom: waveHeight }}>
+        {thumbnail}
+      </div>
+      <div
+        className="absolute inset-x-0 bottom-0 bg-black/30"
+        data-testid="audible-video-wave"
+        style={{ height: waveHeight }}
+      >
+        {waveform}
+      </div>
+    </div>
+  );
+}

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

@@ -96,7 +96,7 @@ describe("AudioWaveform", () => {
     act(() => root.unmount());
   });
 
-  it("greys the clip in place when muted and draws the parent tick when linked", () => {
+  it("greys the clip in place when muted", () => {
     const host = document.createElement("div");
     host.className = "timeline-clip is-audio";
     document.body.append(host);
@@ -112,15 +112,42 @@ describe("AudioWaveform", () => {
           sessionEpoch={1}
           priority="visible"
           muted
-          linked
         />,
       );
     });
 
     expect(host.getAttribute("data-audio-muted")).toBe("true");
-    expect(host.querySelector(".timeline-audio-link")).not.toBeNull();
 
     act(() => root.unmount());
     expect(host.hasAttribute("data-audio-muted")).toBe(false);
   });
+
+  it("fills a short sound strip when the label band is dropped", () => {
+    const heights = [16, 0].map((labelInset) => {
+      const host = document.createElement("div");
+      document.body.append(host);
+      const root = createRoot(host);
+      act(() => {
+        root.render(
+          <AudioWaveform
+            audioUrl="/media/talk.mp4"
+            label=""
+            labelColor="#fff"
+            projectId="project-a"
+            sessionEpoch={1}
+            priority="visible"
+            {...(labelInset === 16 ? {} : { labelInset })}
+          />,
+        );
+      });
+      const canvas = host.querySelector("canvas");
+      const box = { top: canvas?.style.top, height: canvas?.style.height };
+      act(() => root.unmount());
+      return box;
+    });
+    expect(heights).toEqual([
+      { top: "16px", height: "calc(100% - 16px)" },
+      { top: "0px", height: "calc(100% - 0px)" },
+    ]);
+  });
 });

package/src/player/components/AudioWaveform.tsx

@@ -18,8 +18,7 @@ export interface AudioWaveformProps {
   priority: ThumbnailPriority;
   /** `data-hidden` or a muted audio group. Greys the pill; the clip stays. */
   muted?: boolean;
-  /** Same media file as a video clip. Draws the 1px parent tick. */
-  linked?: boolean;
+  labelInset?: number;
 }
 
 const BAR_STEP = 3;
@@ -167,7 +166,7 @@ export const AudioWaveform = memo(function AudioWaveform({
   sessionEpoch,
   priority,
   muted = false,
-  linked = false,
+  labelInset = 16,
 }: AudioWaveformProps) {
   const rootRef = useRef<HTMLDivElement | null>(null);
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
@@ -236,17 +235,17 @@ export const AudioWaveform = memo(function AudioWaveform({
 
   return (
     <div ref={rootRef} className="absolute inset-0">
-      {linked ? <span className="timeline-audio-link" aria-hidden="true" /> : null}
       <div className="absolute inset-0 overflow-hidden" style={{ zIndex: 10 }}>
         <canvas
           ref={setCanvasRef}
           className="absolute inset-x-0 bottom-0 w-full"
-          style={{ top: 16, height: "calc(100% - 16px)" }}
+          style={{ top: labelInset, height: `calc(100% - ${labelInset}px)` }}
         />
         {snapshot.status === "loading" && (
           <div
-            className="absolute inset-x-0 bottom-0 top-4 animate-pulse"
+            className="absolute inset-x-0 bottom-0 animate-pulse"
             style={{
+              top: labelInset,
               background: "var(--timeline-thumbnail-shimmer)",
             }}
           />
@@ -256,7 +255,7 @@ export const AudioWaveform = memo(function AudioWaveform({
         {snapshot.status === "error" && (
           <div
             className="absolute inset-x-0 flex items-center justify-center gap-1.5"
-            style={{ top: 16, bottom: 0 }}
+            style={{ top: labelInset, bottom: 0 }}
           >
             <div
               className="absolute inset-x-0"

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

@@ -0,0 +1,82 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { usePreviewIframeStore } from "../store/previewIframeStore";
+import { ClipBadges } from "./ClipBadges";
+
+Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
+  configurable: true,
+  value: true,
+});
+
+let root: Root | null = null;
+
+afterEach(() => {
+  act(() => root?.unmount());
+  root = null;
+  usePreviewIframeStore.getState().setIframe(null);
+  document.body.innerHTML = "";
+});
+
+const talk: TimelineElement = {
+  id: "talk",
+  domId: "talk",
+  tag: "video",
+  start: 0,
+  duration: 6,
+  track: 0,
+  hasAudio: true,
+};
+
+function render(el: TimelineElement) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() => root?.render(<ClipBadges el={el} />));
+}
+
+const labels = () =>
+  Array.from(document.querySelectorAll("[data-badge]")).map(
+    (badge) => `${badge.getAttribute("data-badge")}:${badge.textContent}`,
+  );
+
+function mountPreview(html: string): Document {
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const doc = iframe.contentDocument;
+  if (!doc) throw new Error("no iframe document");
+  doc.body.innerHTML = html;
+  usePreviewIframeStore.getState().setIframe(iframe);
+  return doc;
+}
+
+describe("ClipBadges", () => {
+  it("renders nothing for an untouched clip", () => {
+    render(talk);
+    expect(document.querySelector("[data-testid='clip-badges']")).toBeNull();
+  });
+
+  it("falls back to the store's volume without a preview", () => {
+    render({ ...talk, volume: 1.8 });
+    expect(labels()).toEqual(["volume:180%"]);
+  });
+
+  it("reads the live node and follows an agent's attribute edit", async () => {
+    const doc = mountPreview(
+      `<video id="talk" data-has-audio="true" data-link="talk-pair" style="clip-path: inset(10px)"></video>`,
+    );
+    render(talk);
+    expect(labels()).toEqual(["link:🔗", "crop:Crop"]);
+    const node = doc.getElementById("talk");
+    await act(async () => {
+      node?.setAttribute("data-color-grading", '{"preset":"warm-daylight","intensity":1}');
+      node?.setAttribute("data-volume", "0.6");
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    expect(labels()).toEqual(["link:🔗", "look:Warm daylight", "crop:Crop", "more:+1"]);
+    expect(document.querySelector("[data-badge='more']")?.getAttribute("title")).toBe("60%");
+  });
+});