@hyperframes/studio 0.8.50 → 0.8.53-desktop.0

package/src/player/components/useTimelineClipDrag.resize.test.tsx

@@ -31,10 +31,14 @@ afterEach(() => {
 function renderResizeHarness(
   elements: TimelineElement[],
   selected: string[],
-  options: { wireGroupResize?: boolean } = {},
+  options: {
+    wireGroupResize?: boolean;
+    snap?: boolean;
+    onSeek?: (time: number, seekOptions?: { keepPlaying?: boolean }) => void;
+  } = {},
 ) {
   usePlayerStore.getState().setElements(elements);
-  usePlayerStore.setState({ timelineSnapEnabled: false });
+  usePlayerStore.setState({ timelineSnapEnabled: options.snap === true });
   usePlayerStore.getState().setSelectedElementIds(new Set(selected));
 
   const scroll = document.createElement("div");
@@ -61,6 +65,7 @@ function renderResizeHarness(
       onMoveElement,
       onBlockedEditAttempt,
       onResizeElements: options.wireGroupResize === false ? undefined : onResizeElements,
+      onSeek: options.onSeek,
       setShowPopover: vi.fn(),
       setRangeSelectionRef: { current: vi.fn() },
       sessionEpoch,
@@ -92,6 +97,9 @@ function renderResizeHarness(
     getResizeProjection() {
       return resizingClip?.groupPreview ?? [];
     },
+    getResizingClip() {
+      return resizingClip;
+    },
     getBlockedClip() {
       return blockedClipRef?.current ?? null;
     },
@@ -441,3 +449,129 @@ describe("useTimelineClipDrag — multi-select group resize (restored)", () => {
     h.unmount();
   });
 });
+
+describe("useTimelineClipDrag — trim guide and preview frame", () => {
+  /** Playhead at 1.25s that follows preview seeks; clip a's end edge grabbed and dragged once. */
+  function trimEndWithSeekingPlayhead(state: { isPlaying?: boolean } = {}) {
+    usePlayerStore.setState({ currentTime: 1.25, ...state });
+    const onSeek = vi.fn((t: number) => usePlayerStore.setState({ currentTime: t }));
+    const a = el("a", { start: 1, duration: 2 });
+    const h = renderResizeHarness([a], [], { onSeek });
+    h.startResize(a, "end");
+    h.movePointer(50);
+    return { onSeek, h };
+  }
+
+  /** Clip a (0-2s) with neighbour b starting at 5s, snapping on, a's end edge grabbed. */
+  function trimAEndBesideB() {
+    const a = el("a", { start: 0, duration: 2 });
+    const b = el("b", { start: 5, duration: 2 });
+    const h = renderResizeHarness([a, b], [], { snap: true });
+    h.startResize(a, "end");
+    return h;
+  }
+
+  it("publishes the snap target while a trimmed edge is on a neighbour edge", () => {
+    const h = trimAEndBesideB();
+    h.movePointer(296); // a's end lands at 4.96s, 4px from b's start
+    expect(h.getResizingClip()).toMatchObject({ snapTime: 5, snapType: "clip-edge" });
+    h.unmount();
+  });
+
+  it("keeps the guide when the trimmed edge sits exactly on the neighbour edge", () => {
+    const h = trimAEndBesideB();
+    h.movePointer(300);
+    expect(h.getResizingClip()).toMatchObject({ snapTime: 5, previewDuration: 5 });
+    h.unmount();
+  });
+
+  it("publishes no snap target when the trimmed edge is free", () => {
+    const h = trimAEndBesideB();
+    h.movePointer(150);
+    expect(h.getResizingClip()).toMatchObject({ snapTime: null, snapType: null });
+    h.unmount();
+  });
+
+  it("never snaps a trimmed edge to the playhead — the edge drives its own seek", () => {
+    usePlayerStore.setState({ currentTime: 5 }); // no clip edge or beat nearby, only the playhead
+    const a = el("a", { start: 0, duration: 2 });
+    const h = renderResizeHarness([a], [], { snap: true });
+    h.startResize(a, "end");
+    h.movePointer(296); // a's end lands at 4.96s, 4px from the playhead
+    expect(h.getResizingClip()).toMatchObject({
+      snapTime: null,
+      snapType: null,
+      previewDuration: 4.96,
+    });
+    h.unmount();
+  });
+
+  it("shows the frame at the dragged edge, then puts the playhead back on release", async () => {
+    usePlayerStore.setState({ currentTime: 1.25 });
+    const onSeek = vi.fn();
+    const a = el("a", { start: 1, duration: 2 });
+    const h = renderResizeHarness([a], [], { onSeek });
+    h.startResize(a, "end");
+    h.movePointer(50);
+    expect(onSeek).toHaveBeenLastCalledWith(3.5 - 1 / 30, { keepPlaying: true });
+    await h.dropPointer();
+    expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true });
+    h.unmount();
+  });
+
+  it("previews the new in-point when the start edge is trimmed", () => {
+    const onSeek = vi.fn();
+    const a = el("a", { start: 1, duration: 2 });
+    const h = renderResizeHarness([a], [], { onSeek });
+    h.startResize(a, "start");
+    h.movePointer(50);
+    expect(onSeek).toHaveBeenLastCalledWith(1.5, { keepPlaying: true });
+    h.unmount();
+  });
+
+  it("publishes the guide when the start edge snaps to a neighbour's end", () => {
+    // playbackStart leaves source to reveal when the in-point moves left.
+    const a = el("a", { start: 3, duration: 2, playbackStart: 5 });
+    const b = el("b", { start: 0, duration: 2 });
+    const h = renderResizeHarness([a, b], [], { snap: true });
+    h.startResize(a, "start");
+    h.movePointer(-96); // a's start lands at 2.04s, 4px from b's end
+    expect(h.getResizingClip()).toMatchObject({ snapTime: 2, previewStart: 2 });
+    h.unmount();
+  });
+
+  it("restores the playhead it had before the first preview seek, not a seeked time", async () => {
+    const { onSeek, h } = trimEndWithSeekingPlayhead();
+    h.movePointer(80);
+    h.movePointer(120);
+    await h.dropPointer();
+    expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true });
+    h.unmount();
+  });
+
+  it("leaves the playhead where playback is when a trim is released while playing", async () => {
+    const { onSeek, h } = trimEndWithSeekingPlayhead({ isPlaying: true });
+    h.movePointer(120);
+    const callsBeforeRelease = onSeek.mock.calls.length;
+    await h.dropPointer();
+    expect(onSeek).toHaveBeenCalledTimes(callsBeforeRelease);
+    expect(onSeek).not.toHaveBeenCalledWith(1.25, expect.anything());
+    usePlayerStore.setState({ isPlaying: false });
+    h.unmount();
+  });
+
+  it("draws no guide and seeks to the rendered edge when a group member clamps the trim", () => {
+    const onSeek = vi.fn();
+    const a = el("a", { start: 0, duration: 4 });
+    const b = el("b", { start: 0, duration: 1 });
+    const c = el("c", { start: 2, duration: 1 });
+    const h = renderResizeHarness([a, b, c], ["a", "b"], { snap: true, onSeek });
+    h.startResize(a, "end");
+    h.movePointer(-198); // a's raw end 2.02s snaps to c at 2s; b clamps the shared delta
+    const clip = h.getResizingClip()!;
+    expect(clip.previewStart + clip.previewDuration).toBeCloseTo(3.1, 3);
+    expect(clip).toMatchObject({ snapTime: null, snapType: null });
+    expect(onSeek).toHaveBeenLastCalledWith(expect.closeTo(3.1 - 1 / 30, 3), { keepPlaying: true });
+    h.unmount();
+  });
+});

package/src/player/components/useTimelineClipDrag.ts

@@ -17,6 +17,7 @@ import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import {
   computeDragPreview,
   computeResizePreview,
+  trimPreviewTime,
   previewGroupResize,
   type ResizePreviewResult,
 } from "./timelineClipDragPreview";
@@ -64,6 +65,8 @@ interface UseTimelineClipDragInput {
   ) => Promise<void> | void;
   onResizeElements?: NonNullable<TimelineEditCallbacks["onResizeElements"]>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedClipState["intent"]) => void;
+  /** Seeks the preview; a trim shows the frame at its dragged edge. */
+  onSeek?: (time: number, options?: { keepPlaying?: boolean }) => void;
   setShowPopover: (show: boolean) => void;
   /** Stable ref to the range selection setter — wired after mount to break circular dependency. */
   setRangeSelectionRef: React.RefObject<((sel: null) => void) | null>;
@@ -92,6 +95,7 @@ export function useTimelineClipDrag({
   onResizeElement,
   onResizeElements,
   onBlockedEditAttempt,
+  onSeek,
   setShowPopover,
   setRangeSelectionRef,
   readZIndex,
@@ -149,11 +153,15 @@ export function useTimelineClipDrag({
   const dragAudioTracksRef = useRef<ReadonlySet<number> | null>(null);
 
   const buildSnapTargets = useCallback(
-    (excludeElementKey: string | null, includeBeats: boolean): TimelineSnapTarget[] => {
+    (
+      excludeElementKey: string | null,
+      includeBeats: boolean,
+      includePlayhead = true,
+    ): TimelineSnapTarget[] => {
       // Magnet off ⇒ no targets and no scan; do NOT cache so a mid-gesture toggle
       // back on starts scanning immediately (preserves the existing skip).
       if (!snapContextRef.current.enabled) return [];
-      const cacheKey = `${excludeElementKey ?? ""}|${includeBeats ? 1 : 0}`;
+      const cacheKey = `${excludeElementKey ?? ""}|${includeBeats ? 1 : 0}|${includePlayhead ? 1 : 0}`;
       const cached = snapTargetsCacheRef.current.get(cacheKey);
       if (cached) return cached;
       const targets = collectTimelineSnapTargets({
@@ -161,6 +169,7 @@ export function useTimelineClipDrag({
         playheadTime: usePlayerStore.getState().currentTime,
         beatTimes: includeBeats ? snapContextRef.current.beatTimes : [],
         excludeElementKey,
+        includePlayhead,
       });
       snapTargetsCacheRef.current.set(cacheKey, targets);
       return targets;
@@ -244,6 +253,10 @@ export function useTimelineClipDrag({
   onResizeElementRef.current = onResizeElement;
   const onResizeElementsRef = useRef(onResizeElements);
   onResizeElementsRef.current = onResizeElements;
+  const onSeekRef = useRef(onSeek);
+  onSeekRef.current = onSeek;
+  // Playhead time before the first trim preview seek; restored when the gesture ends.
+  const trimSeekOriginRef = useRef<number | null>(null);
   const readZIndexRef = useRef(readZIndex);
   readZIndexRef.current = readZIndex;
   const onStackingPatchesRef = useRef(onStackingPatches);
@@ -292,10 +305,17 @@ export function useTimelineClipDrag({
         pps: ppsRef.current,
         buildSnapTargets,
       });
-      const setResizeState = (v: ResizePreviewResult) =>
+      trimSeekOriginRef.current ??= usePlayerStore.getState().currentTime;
+      const setResizeState = (v: ResizePreviewResult) => {
+        // A trim never changes the play state: keepPlaying lets seek() decide,
+        // and it only resumes playback if it was already playing.
+        onSeekRef.current?.(trimPreviewTime(resize.edge, v.previewStart, v.previewDuration), {
+          keepPlaying: true,
+        });
         publishResizingClip(
           resizingClipRef.current ? { ...resizingClipRef.current, started: true, ...v } : null,
         );
+      };
 
       // Group resize: a capability-clean multi-selection resizes rigidly by one
       // shared, member-clamped delta (legacy main 36413da7f). The grabbed clip
@@ -338,6 +358,13 @@ export function useTimelineClipDrag({
       cancelAnimationFrame(clipDragScrollRaf.current);
       clipDragScrollRaf.current = 0;
     }
+    if (trimSeekOriginRef.current != null) {
+      // Paused: put the playhead back. Playing: leave it, a backward jump would rewind live playback.
+      if (!usePlayerStore.getState().isPlaying) {
+        onSeekRef.current?.(trimSeekOriginRef.current, { keepPlaying: true });
+      }
+      trimSeekOriginRef.current = null;
+    }
     // Gesture teardown: drop frozen caches so the next gesture reads fresh state.
     snapTargetsCacheRef.current.clear();
     dragAudioTracksRef.current = null;

package/src/player/lib/describeClips.ts

@@ -1,34 +1,9 @@
 /** Plain-field clip facts from the player store; feeds the Ask-agent prompt and `studio_look`. */
 import type { TimelineElement } from "../store/playerStore";
 import { elementAutomationLanes } from "../components/automationLaneData";
-import { roundTo3 } from "../../utils/rounding";
-
-export interface ClipLane {
-  /** `volume`, or `fx.<nodeId>.<param>`. */
-  target: string;
-  /** `t` is seconds from the start of the clip, not the composition. */
-  points: { t: number; v: number }[];
-}
-
-export interface ClipFact {
-  id: string;
-  label: string | null;
-  kind: string;
-  start: number;
-  duration: number;
-  end: number;
-  /** The `data-track-index` as written in the source file. */
-  trackIndex: number;
-  src: string | null;
-  sourceFile: string | null;
-  /** `null` when `data-volume` is not authored (the clip plays at 1). */
-  volume: number | null;
-  lanes: ClipLane[];
-  /** `null` at normal speed: not authored, or 1 (the manifest defaults it to 1). */
-  playbackRate: number | null;
-  audioGroup: string | null;
-  role: string | null;
-}
+import { byStart, formatClipLine, type ClipFact } from "@hyperframes/core/clip-facts";
+export { byStart } from "@hyperframes/core/clip-facts";
+export type { ClipFact } from "@hyperframes/core/clip-facts";
 
 /** The store holds preview URLs; the agent edits project files, so drop the origin and preview prefix. */
 function projectRelativeSrc(src: string): string {
@@ -57,36 +32,10 @@ export function describeClip(element: TimelineElement): ClipFact {
   };
 }
 
-export const byStart = (a: ClipFact, b: ClipFact) =>
-  a.start - b.start || a.trackIndex - b.trackIndex;
-
 export function describeClips(elements: readonly TimelineElement[]): ClipFact[] {
   return elements.map(describeClip).sort(byStart);
 }
 
-const num = (n: number) => String(roundTo3(n));
-
-function formatClipLine(clip: ClipFact): string {
-  const parts = [
-    `${clip.kind} "${clip.id}"`,
-    clip.src && `src=${clip.src}`,
-    `start=${num(clip.start)}`,
-    `duration=${num(clip.duration)}`,
-    `end=${num(clip.end)}`,
-    `track=${clip.trackIndex}`,
-    clip.volume !== null && `volume=${num(clip.volume)}`,
-    clip.playbackRate !== null && `rate=${num(clip.playbackRate)}`,
-    clip.audioGroup && `group=${clip.audioGroup}`,
-    clip.role && `role=${clip.role}`,
-    clip.sourceFile && `file=${clip.sourceFile}`,
-    ...clip.lanes.map(
-      (lane) =>
-        `${lane.target}-lane=[${lane.points.map((p) => `${num(p.t)}:${num(p.v)}`).join(", ")}]`,
-    ),
-  ];
-  return `- ${parts.filter(Boolean).join(" ")}`;
-}
-
 const PROMPT_CLIP_CAP = 200;
 
 /** The Ask-agent prompt's Timeline block; empty when the timeline has no clips. */

package/src/player/lib/playbackShortcuts.ts

@@ -17,6 +17,8 @@ const PLAYBACK_SHORTCUT_IGNORED_SELECTOR = [
   "[role='checkbox']",
   "[role='combobox']",
   "[role='menuitem']",
+  // Base UI's menu radio item is a `<div>`, so `button` above no longer catches it.
+  "[role='menuitemradio']",
   "[role='radio']",
   "[role='slider']",
   "[role='spinbutton']",

package/src/player/lib/timelinePerformanceDiagnostics.test.ts

@@ -14,7 +14,7 @@ describe("timeline performance diagnostics", () => {
 
   it("reads mounted resources without mutating the timeline", () => {
     document.body.innerHTML = `
-      <div aria-label="Timeline" data-timeline-scheduler-queued="3"
+      <div aria-label="Timeline track view" data-timeline-scheduler-queued="3"
            data-timeline-scheduler-active="2" data-timeline-cache-bytes="4096">
         <div data-timeline-row><div data-clip="true"></div><div data-clip="true"></div></div>
         <div data-timeline-row><div data-clip="true"></div></div>
@@ -41,7 +41,8 @@ describe("timeline performance diagnostics", () => {
   });
 
   it("returns the zero baseline after unmount or reset removes the DOM", () => {
-    document.body.innerHTML = '<div aria-label="Timeline"><div data-clip="true"></div></div>';
+    document.body.innerHTML =
+      '<div aria-label="Timeline track view"><div data-clip="true"></div></div>';
     expect(readTimelinePerformanceDiagnostics().mountedClipRoots).toBe(1);
 
     document.body.replaceChildren();

package/src/player/lib/timelinePerformanceDiagnostics.ts

@@ -69,7 +69,7 @@ function sumDataAttribute(root: ParentNode, selector: string, dataKey: string):
 export function readTimelinePerformanceDiagnostics(
   root: ParentNode = document,
 ): Readonly<TimelinePerformanceDiagnostics> {
-  const timelineRoots = root.querySelectorAll<HTMLElement>('[aria-label="Timeline"]');
+  const timelineRoots = root.querySelectorAll<HTMLElement>('[aria-label="Timeline track view"]');
   let mountedTimelineDescendants = 0;
   for (const timelineRoot of timelineRoots) {
     mountedTimelineDescendants += timelineRoot.querySelectorAll("*").length;

package/src/player/store/previewIframeStore.notify.test.tsx

@@ -0,0 +1,75 @@
+// @vitest-environment jsdom
+import { act, StrictMode, useCallback, useEffect, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it } from "vitest";
+import { useOwnPreviewIframe, usePreviewIframeStore } from "./previewIframeStore";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+// Mirrors NLEContext.tsx: a ref callback pushes the element on attach
+// (~L126, onIframeLoad) and a separate mount/dep effect re-pushes the SAME
+// ref value (~L304-306, deps include an unrelated counter like refreshKey).
+function Child({ tick }: { tick: number }) {
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const setIframe = usePreviewIframeStore((s) => s.setIframe);
+
+  const handleRef = useCallback(
+    (el: HTMLIFrameElement | null) => {
+      iframeRef.current = el;
+      setIframe(el);
+    },
+    [setIframe],
+  );
+
+  useEffect(() => {
+    setIframe(iframeRef.current);
+  }, [tick, setIframe]);
+
+  return <iframe ref={handleRef} />;
+}
+
+function Owner({ tick }: { tick: number }) {
+  useOwnPreviewIframe();
+  return <Child tick={tick} />;
+}
+
+it("does not notify raw subscribers for a repeated setIframe(sameValue)", () => {
+  let notifyCount = 0;
+  const unsubscribe = usePreviewIframeStore.subscribe(() => {
+    notifyCount += 1;
+  });
+
+  const container = document.createElement("div");
+  const root = createRoot(container);
+  act(() => {
+    root.render(
+      <StrictMode>
+        <Owner tick={0} />
+      </StrictMode>,
+    );
+  });
+  // A dep bump on the mount effect with the iframe DOM node unchanged -
+  // the shape NLEContext hits every time refreshKey moves without a new
+  // <iframe>.
+  act(() => {
+    root.render(
+      <StrictMode>
+        <Owner tick={1} />
+      </StrictMode>,
+    );
+  });
+
+  const iframe = usePreviewIframeStore.getState().iframe;
+  expect(iframe).not.toBeNull();
+
+  // 3 real Object.is-distinct transitions happen here: the ref-callback's
+  // null -> element attach, then StrictMode's mount-effect replay drives
+  // useOwnPreviewIframe's unmount cleanup (element -> null) and the
+  // re-run mount effect (null -> element) once each. Measured on the
+  // unfixed store: 7 (four of those are the SAME value re-pushed by the
+  // ref callback's own redundant effect run and the tick-bump update).
+  expect(notifyCount).toBe(3);
+
+  act(() => root.unmount());
+  unsubscribe();
+});

package/src/player/store/previewIframeStore.test.tsx

@@ -0,0 +1,29 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it } from "vitest";
+import { useOwnPreviewIframe, usePreviewIframeStore } from "./previewIframeStore";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+it("clears the store on owner unmount so a remount starts from null", () => {
+  const seen: Array<HTMLIFrameElement | null> = [];
+  const Owner = () => {
+    seen.push(useOwnPreviewIframe());
+    return null;
+  };
+  const iframe = document.createElement("iframe");
+  const first = createRoot(document.createElement("div"));
+  act(() => first.render(<Owner />));
+  act(() => usePreviewIframeStore.getState().setIframe(iframe));
+  expect(seen.at(-1)).toBe(iframe);
+
+  act(() => first.unmount());
+  expect(usePreviewIframeStore.getState().iframe).toBeNull();
+
+  seen.length = 0;
+  const second = createRoot(document.createElement("div"));
+  act(() => second.render(<Owner />));
+  expect(seen).toEqual([null]);
+  act(() => second.unmount());
+});

package/src/player/store/previewIframeStore.ts

@@ -0,0 +1,25 @@
+import { create } from "zustand";
+import { useMountEffect } from "../../hooks/useMountEffect";
+
+interface PreviewIframeState {
+  iframe: HTMLIFrameElement | null;
+  setIframe: (iframe: HTMLIFrameElement | null) => void;
+}
+
+/** The one owner of "the live preview iframe element"; a promoted reload replaces it. */
+export const usePreviewIframeStore = create<PreviewIframeState>((set) => ({
+  iframe: null,
+  // Return the same state reference on a no-op set so zustand skips the
+  // notify (Object.is check in setState) instead of merging a new object
+  // every time a caller re-pushes the current value.
+  setIframe: (iframe) => set((state) => (Object.is(state.iframe, iframe) ? state : { iframe })),
+}));
+
+/** Subscribe an effect to the live iframe by listing the result in its dependencies. */
+export const useLivePreviewIframe = () => usePreviewIframeStore((s) => s.iframe);
+
+/** The owner's hook: reads the live iframe and clears it on unmount so a remount starts from null. */
+export function useOwnPreviewIframe() {
+  useMountEffect(() => () => usePreviewIframeStore.getState().setIframe(null));
+  return useLivePreviewIframe();
+}

package/src/renderQueueExports.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment happy-dom
+// Imports the render queue the way a host app does: by package name, through the declared exports.
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import {
+  RenderQueue,
+  getPersistedRenderSettings,
+  persistRenderSettings,
+  useRenderQueue,
+  type FfmpegStatus,
+  type RenderJob,
+} from "@hyperframes/studio";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe("render queue package exports", () => {
+  it("exposes the hook and settings helpers", () => {
+    expect(typeof useRenderQueue).toBe("function");
+    persistRenderSettings("webm", "high", 30);
+    expect(getPersistedRenderSettings()).toMatchObject({
+      format: "webm",
+      quality: "high",
+      fps: 30,
+    });
+  });
+
+  it("mounts RenderQueue with a host-supplied job", async () => {
+    const job: RenderJob = {
+      id: "j1",
+      status: "complete",
+      progress: 100,
+      filename: "host-render.mp4",
+      createdAt: 0,
+    };
+    const ffmpeg: FfmpegStatus = { ok: true };
+    const el = document.createElement("div");
+    document.body.append(el);
+    const root = createRoot(el);
+    await act(async () => {
+      root.render(
+        <RenderQueue
+          jobs={[job]}
+          projectId="p"
+          onDelete={vi.fn()}
+          onClearCompleted={vi.fn()}
+          onStartRender={vi.fn()}
+          isRendering={false}
+          ffmpeg={ffmpeg}
+          ffmpegChecking={false}
+          onRecheckFfmpeg={vi.fn()}
+        />,
+      );
+    });
+    expect(el.textContent).toContain("host-render.mp4");
+    await act(async () => root.unmount());
+  });
+});

package/src/styles/classCandidates.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import { extractClassCandidates } from "./classCandidates";
+
+function bases(source: string): string[] {
+  return extractClassCandidates(source)
+    .map((candidate) => candidate.base)
+    .sort();
+}
+
+describe("extractClassCandidates", () => {
+  it("reads a plain className attribute", () => {
+    expect(bases(`<div className="text-center border-dashed" />`)).toEqual([
+      "border-dashed",
+      "text-center",
+    ]);
+  });
+
+  it("reads every string a class-building call is given", () => {
+    const source = `<div className={cn("flex", open && "bg-surface", { "text-accent": on })} />`;
+
+    expect(bases(source)).toEqual(["bg-surface", "flex", "text-accent"]);
+  });
+
+  it("reads a class map that never touches a className literal", () => {
+    // The shape Studio's primitives use: the utility only reaches markup
+    // through a lookup, so an attribute-only reader would miss it entirely.
+    const source = `const sizeStyles: Record<ButtonSize, string> = {
+      sm: "h-7 px-2.5 rounded-button",
+    };`;
+
+    expect(bases(source)).toEqual(["h-7", "px-2.5", "rounded-button"]);
+  });
+
+  it("reads a class map whose name says nothing about classes", () => {
+    // The defect this replaced: candidate-ness was decided by the binding's
+    // name, so the same classes were gated in `sizeStyles` and invisible in
+    // `buttonSizes`. What makes them classes is where they are used.
+    const source = `const fooSizes = { md: "h-ctl rounded-hologram" };
+      const Foo = ({ size }) => <span className={cn(fooSizes[size])} />;`;
+
+    expect(bases(source)).toEqual(["h-ctl", "rounded-hologram"]);
+  });
+
+  it("follows an identifier that contains a dollar sign", () => {
+    const source = `const $cls = "flex-none";\nconst a = <div className={$cls} />;`;
+
+    expect(bases(source)).toEqual(["flex-none"]);
+  });
+
+  it("does not read a lookup key's default value as a class", () => {
+    // `variant` is the key, not the class list, so the default it falls back
+    // to is a map entry name and never reaches markup.
+    const source = `const map = { ghost: "bg-transparent" };
+      const Foo = ({ variant = "ghost" }) => <span className={map[variant]} />;`;
+
+    expect(bases(source)).toEqual(["bg-transparent"]);
+  });
+
+  it("leaves a lookup table alone when nothing uses it as a class", () => {
+    const source = `const labels = { md: "Medium size" };
+      const Foo = () => <span title={labels.md} />;`;
+
+    expect(bases(source)).toEqual([]);
+  });
+
+  it("drops the template chunk that touches an interpolation", () => {
+    expect(bases("<div className={`w-${i} flex`} />")).toEqual(["flex"]);
+  });
+
+  it("keeps a chunk that whitespace separates from the interpolation", () => {
+    expect(bases("<div className={`${base} flex `} />")).toEqual(["flex"]);
+  });
+
+  it("strips variant prefixes, including bracketed ones", () => {
+    const source = `<div className="hover:bg-surface/50 md:group-data-[open]:text-accent" />`;
+
+    expect(bases(source)).toEqual(["bg-surface/50", "text-accent"]);
+  });
+
+  it("flags bracketed arbitrary values so the sweep can count them", () => {
+    const found = extractClassCandidates(`<div className="text-[11px] text-center" />`);
+
+    expect(found.filter((candidate) => candidate.arbitrary).map((c) => c.raw)).toEqual([
+      "text-[11px]",
+    ]);
+  });
+
+  it("ignores strings that are not class lists", () => {
+    const source = `const styles = getComputedStyle(el);
+      const label = "Export video";
+      log("failed to open the project file");`;
+
+    expect(bases(source)).toEqual([]);
+  });
+
+  it("does not read past the end of a class region", () => {
+    const source = `<div className="flex" title="Export video" />`;
+
+    expect(bases(source)).toEqual(["flex"]);
+  });
+
+  it("survives an unterminated region without hanging", () => {
+    expect(bases(`<div className={cn("flex",`)).toEqual(["flex"]);
+  });
+});