@hyperframes/studio 0.8.58 → 0.8.60

package/src/player/components/TimelineParts.tsx

@@ -0,0 +1,74 @@
+import { TimelineCanvas as TimelineCanvasImpl } from "./TimelineCanvas";
+import {
+  TimelineClipMenuOverlay as TimelineClipMenuImpl,
+  TimelineEditPopoverOverlay as TimelineEditPopoverImpl,
+  TimelineGapMenuOverlay as TimelineGapMenuImpl,
+  TimelineKeyframeMenuOverlay as TimelineKeyframeMenuImpl,
+  TimelineShortcutHintOverlay as TimelineShortcutHintImpl,
+} from "./TimelineOverlays";
+import { TimelineLanes as TimelineLanesImpl } from "./TimelineLanes";
+import { PlayheadIndicator } from "./PlayheadIndicator";
+import { useTimelineContext } from "./TimelineProvider";
+import { TimelineEmptyState } from "./TimelineEmptyState";
+import { TimelineRulerPart } from "./TimelineRulerPart";
+
+/** The provider-backed canvas shell. */
+export function TimelineFrame() {
+  return <TimelineCanvasImpl />;
+}
+
+/** The provider-backed ruler. */
+export const TimelineRuler = TimelineRulerPart;
+
+/**
+ * The provider-backed lane renderer. TimelineFrame remains the composed Studio
+ * canvas; this part is exported for hosts that own the canvas arrangement.
+ */
+export function TimelineLanes() {
+  const { state, actions } = useTimelineContext();
+  const props = state.canvas;
+  return (
+    <TimelineLanesImpl
+      {...props}
+      renderClipContent={actions.renderClipContent}
+      renderClipOverlay={actions.renderClipOverlay}
+    />
+  );
+}
+
+/** The provider-backed playhead indicator. */
+export function TimelinePlayhead() {
+  const { state } = useTimelineContext();
+  const props = state.canvas;
+  return <PlayheadIndicator scrubbing={props.isScrubbing} />;
+}
+
+/** The provider-backed razor guide. */
+export function TimelineRazorGuide() {
+  const { meta } = useTimelineContext();
+  return meta.razorGuide;
+}
+
+/** The composed overlay surface used by the Studio variant. */
+export { TimelineOverlays } from "./TimelineOverlays";
+
+export function TimelineEmptyStatePart() {
+  const { meta } = useTimelineContext();
+  return <TimelineEmptyState {...meta.emptyState} />;
+}
+
+export function TimelineShortcutHint() {
+  return <TimelineShortcutHintImpl />;
+}
+export function TimelineEditPopover() {
+  return <TimelineEditPopoverImpl />;
+}
+export function TimelineClipMenu() {
+  return <TimelineClipMenuImpl />;
+}
+export function TimelineKeyframeMenu() {
+  return <TimelineKeyframeMenuImpl />;
+}
+export function TimelineGapMenu() {
+  return <TimelineGapMenuImpl />;
+}

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

@@ -0,0 +1,58 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { Timeline } from "./Timeline";
+import { usePlayerStore } from "../store/playerStore";
+import { useTimelineContext } from "./TimelineProvider";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+});
+
+function TimelinePartsVariant() {
+  const { meta } = useTimelineContext();
+  return React.createElement(
+    "div",
+    meta.containerProps,
+    React.createElement(
+      "div",
+      meta.viewportProps,
+      React.createElement(Timeline.Frame),
+      React.createElement(Timeline.RazorGuide),
+    ),
+    React.createElement(Timeline.Overlays),
+  );
+}
+
+describe("Timeline provider boundary", () => {
+  it("keeps the composed Timeline markup equal to its provider parts", () => {
+    usePlayerStore.setState({
+      duration: 4,
+      timelineReady: true,
+      elements: [{ id: "parity-clip", tag: "div", start: 0, duration: 2, track: 0 }],
+    });
+    const composedHost = document.createElement("div");
+    const partsHost = document.createElement("div");
+    document.body.append(composedHost, partsHost);
+    const composedRoot = createRoot(composedHost);
+    const partsRoot = createRoot(partsHost);
+    act(() => {
+      composedRoot.render(React.createElement(Timeline));
+      partsRoot.render(
+        React.createElement(Timeline.Provider, null, React.createElement(TimelinePartsVariant)),
+      );
+    });
+    const normalizeMarkup = (markup: string) =>
+      markup.replaceAll(/timeline-lanes_[^"]+/g, "timeline-lanes");
+    expect(normalizeMarkup(partsHost.innerHTML)).toBe(normalizeMarkup(composedHost.innerHTML));
+    act(() => {
+      composedRoot.unmount();
+      partsRoot.unmount();
+    });
+  });
+});

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

@@ -386,7 +386,7 @@ describe("TimelinePropertyLanes", () => {
     const positionFill = laneDiamonds(host, "position")[0]?.querySelector("path:last-child");
     const visualFill = laneDiamonds(host, "visual")[0]?.querySelector("path:last-child");
     expect(positionFill?.getAttribute("fill")).toBe("#4ba3d2");
-    expect(visualFill?.getAttribute("fill")).toBe("#a3a3a3");
+    expect(visualFill?.getAttribute("fill")).toBe("var(--timeline-diamond-muted)");
     act(() => root.unmount());
   });
 

package/src/player/components/TimelineProvider.tsx

@@ -17,6 +17,8 @@ import type { Rect } from "../../utils/marqueeGeometry";
 import type { ResizingClipState } from "./useTimelineClipDrag";
 import type { TimelineLaneBaseProps } from "./timelineLaneProps";
 import type { TimelineLaneGapStrips } from "./useTimelineGapHighlights";
+import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
+import type { TimelineSnapTarget } from "./timelineSnapping";
 import type { TimelineElement } from "../store/playerStore";
 import type { KeyframeCacheEntry } from "../store/keyframeSlice";
 import type { AnimationKeyframeTarget } from "../../hooks/gsapTweenSynth";
@@ -24,6 +26,10 @@ import type { TimelineTheme } from "./timelineTheme";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import type { KeyframeDiamondContextMenuState } from "./KeyframeDiamondContextMenu";
 import { useTimelineProviderState } from "./useTimelineProviderState";
+import {
+  TimelineEditProvider,
+  useTimelineEditContextValue,
+} from "../../contexts/TimelineEditContext";
 
 export type TimelineCanvasState = Omit<
   TimelineLaneBaseProps,
@@ -51,6 +57,13 @@ export type TimelineCanvasState = Omit<
   beatDragging: boolean;
   onResizeElement: TimelineEditCallbacks["onResizeElement"];
   onMoveElement: TimelineEditCallbacks["onMoveElement"];
+  draggedElement: TimelineElement | null;
+  snapGuide: TimelineSnapTarget | null;
+  multiDragPreview: MultiDragPreviewInput | null;
+  onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
+  onTogglePropertyGroupKeyframe: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];
+  onRazorSplit: TimelineEditCallbacks["onRazorSplit"];
+  onRazorSplitAll: TimelineEditCallbacks["onRazorSplitAll"];
 };
 
 export interface ClipContextMenuState {
@@ -166,6 +179,18 @@ export interface TimelineContextValue {
 const TimelineContext = createContext<TimelineContextValue | null>(null);
 
 export function TimelineProvider({ children, ...props }: TimelineProps & { children: ReactNode }) {
+  const editContext = useTimelineEditContextValue();
+  if (!editContext) {
+    return (
+      <TimelineEditProvider value={props}>
+        <TimelineProviderState {...props}>{children}</TimelineProviderState>
+      </TimelineEditProvider>
+    );
+  }
+  return <TimelineProviderState {...props}>{children}</TimelineProviderState>;
+}
+
+function TimelineProviderState({ children, ...props }: TimelineProps & { children: ReactNode }) {
   const value = useTimelineProviderState(props);
   return <TimelineContext.Provider value={value}>{children}</TimelineContext.Provider>;
 }

package/src/player/components/TimelineRazorInteraction.tsx

@@ -50,11 +50,11 @@ export function useTimelineRazorInteraction({
   return { razorGuideX, updateRazorGuide, clearRazorGuide, splitAllAtPointer };
 }
 
-export function TimelineRazorGuide({ x }: { x: number }) {
+export function TimelineRazorGuideOverlay({ x }: { x: number }) {
   return (
     <div
       className="absolute top-0 bottom-0 pointer-events-none z-10"
-      style={{ left: x, width: 1, background: "rgba(239,68,68,0.7)" }}
+      style={{ left: x, width: 1, background: "var(--timeline-danger)" }}
     />
   );
 }

package/src/player/components/TimelineRuler.tsx

@@ -69,7 +69,8 @@ export const TimelineRuler = memo(function TimelineRuler({
                 y1={0}
                 x2={x}
                 y2={totalH}
-                stroke={`rgba(34, 197, 94, ${opacity.toFixed(3)})`}
+                stroke="var(--timeline-beat)"
+                strokeOpacity={opacity}
                 strokeWidth="1"
               />
             );
@@ -99,7 +100,7 @@ export const TimelineRuler = memo(function TimelineRuler({
           style={{
             height: RULER_H,
             width: trackContentWidth,
-            // Ruler background = panel surface (#0A0A0B) — no bottom border,
+            // Ruler background = the panel surface token — no bottom border,
             // no tick lines (CapCut-style clean ruler, labels only).
             background: theme.shellBackground,
           }}

package/src/player/components/TimelineRulerPart.tsx

@@ -0,0 +1,22 @@
+import { TimelineRuler as TimelineRulerImpl } from "./TimelineRuler";
+import { useTimelineContext } from "./TimelineProvider";
+
+export function TimelineRulerPart() {
+  const { state } = useTimelineContext();
+  const props = state.canvas;
+  return (
+    <TimelineRulerImpl
+      major={props.major}
+      minor={props.minor}
+      pps={props.pps}
+      trackContentWidth={props.trackContentWidth}
+      totalH={props.totalH}
+      effectiveDuration={props.effectiveDuration}
+      majorTickInterval={props.majorTickInterval}
+      theme={props.theme}
+      beatAnalysis={props.beatAnalysis}
+      contentOrigin={props.contentOrigin}
+      renderTimeRange={props.rowsVirtualized ? props.renderTimeRange : undefined}
+    />
+  );
+}

package/src/player/components/TimelineShortcutHint.tsx

@@ -9,11 +9,11 @@ export function TimelineShortcutHint({ theme }: TimelineShortcutHintProps) {
     <div className="absolute bottom-2 right-3 pointer-events-none z-20">
       <div
         className="flex items-center gap-1.5 px-2 py-1 rounded-md border"
-        style={{ background: "rgba(17,23,35,0.84)", borderColor: theme.gutterBorder }}
+        style={{ background: "var(--timeline-shortcut-bg)", borderColor: theme.gutterBorder }}
       >
         <kbd
           className="text-[9px] font-mono px-1 py-0.5 rounded-sm"
-          style={{ color: theme.textSecondary, background: "rgba(255,255,255,0.06)" }}
+          style={{ color: theme.textSecondary, background: "var(--timeline-tick-minor)" }}
         >
           Shift
         </kbd>

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

@@ -793,7 +793,7 @@ describe("TimelineTrackHeader", () => {
         isGroupMember: true,
       });
       expect(header()?.style.paddingLeft).toBe("14px");
-      expect(header()?.style.borderLeft).toContain("2px");
+      expect(header()?.style.borderLeft).toContain("var(--timeline-accent-rail)");
       act(() => view.root.unmount());
     });
 

package/src/player/components/TimelineTrackHeader.tsx

@@ -26,12 +26,10 @@ import { useMemo } from "react";
 
 /** Accent rail + inset marking a row as a group MEMBER, matching the level-2
  *  nesting its `aria-level` already reports. */
-const GROUP_MEMBER_RAIL = "#3CE6AC59";
+const GROUP_MEMBER_RAIL = "var(--timeline-accent-rail)";
 const GROUP_MEMBER_INDENT = 14;
-/** A hair lighter than `gutterBackground`, so a member row reads as sitting
- *  INSIDE its group rather than beside it. Overlaid rather than hard-coded so
- *  it tracks whatever the theme's gutter is. */
-const GROUP_MEMBER_TINT = "rgba(255,255,255,0.035)";
+/** A neutral wash keeps group membership visible without changing the row's hue. */
+const GROUP_MEMBER_TINT = "var(--timeline-group-member-tint)";
 
 /** The gutter fill for a row, tinted when it belongs to a group. */
 export function gutterFill(base: string, isGroupMember: boolean): string {
@@ -288,7 +286,7 @@ export function TimelineTrackHeader({
           <div
             className={
               showTrackLabel
-                ? "flex flex-col justify-center gap-0.5 px-1.5 text-white/55"
+                ? "flex flex-col justify-center gap-0.5 px-1.5 text-[var(--timeline-handle)]"
                 : "flex flex-col items-center justify-center gap-0.5"
             }
             style={{ height: TRACK_H }}

package/src/player/components/TimelineTrackPlainHeader.tsx

@@ -39,8 +39,10 @@ export function VisibilityButton({
       type="button"
       aria-label={label}
       title={label}
-      className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 transition-colors focus-visible:outline-solid focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-[#3CE6AC] ${
-        hidden ? "text-[#3CE6AC] hover:text-white" : "text-white/35 hover:text-white/75"
+      className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 transition-colors focus-visible:outline-solid focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-[var(--timeline-accent)] ${
+        hidden
+          ? "text-[var(--timeline-accent)] hover:text-[var(--timeline-text-solid)]"
+          : "text-[var(--timeline-text-faint)] hover:text-[var(--timeline-text-soft)]"
       }`}
       onPointerDown={(event) => event.stopPropagation()}
       onClick={(event) => {
@@ -89,7 +91,12 @@ export function PlainTrackHeader({
           and the name gives way instead. */}
       <div className="flex min-w-0 items-center gap-1">
         {isAudioTrack && (
-          <Music size={12} weight="fill" aria-hidden="true" className="text-white/35" />
+          <Music
+            size={12}
+            weight="fill"
+            aria-hidden="true"
+            className="text-[var(--timeline-text-faint)]"
+          />
         )}
         {/* No `flex-1`: the name takes only the width it needs, so the clip
             count sits against it rather than being pushed out to meet the

package/src/player/components/VideoThumbnail.tsx

@@ -112,8 +112,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
         <div
           className="absolute inset-0 animate-pulse motion-reduce:animate-none"
           style={{
-            background:
-              "linear-gradient(90deg, rgba(255,255,255,0.02) 0%, rgba(255,255,255,0.05) 50%, rgba(255,255,255,0.02) 100%)",
+            background: "var(--timeline-thumbnail-shimmer)",
           }}
         />
       )}
@@ -128,13 +127,12 @@ export const VideoThumbnail = memo(function VideoThumbnail({
         <div
           className="absolute inset-x-0 bottom-0 z-10 px-1.5 pb-0.5 pt-3"
           style={{
-            background:
-              "linear-gradient(to top, rgba(0,0,0,0.85) 0%, rgba(0,0,0,0.4) 60%, transparent 100%)",
+            background: "var(--timeline-thumbnail-label-gradient)",
           }}
         >
           <span
             className="block truncate text-[9px] font-semibold leading-tight"
-            style={{ color: labelColor, textShadow: "0 1px 2px rgba(0,0,0,0.9)" }}
+            style={{ color: labelColor, textShadow: "var(--timeline-thumbnail-label-shadow)" }}
           >
             {label}
           </span>

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

@@ -2,17 +2,17 @@ import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 
 const studioCss = readFileSync(new URL("../../styles/studio.css", import.meta.url), "utf8");
+const themeCss = readFileSync(new URL("../../styles/theme.css", import.meta.url), "utf8");
+const timelineOverlaySources = [
+  "TimelineShortcutHint.tsx",
+  "LayerDisclosureRow.tsx",
+  "ImageThumbnail.tsx",
+  "AudioWaveform.tsx",
+  "VideoThumbnail.tsx",
+].map((fileName) => readFileSync(new URL(`./${fileName}`, import.meta.url), "utf8"));
 const timelineClipSource = readFileSync(new URL("./TimelineClip.tsx", import.meta.url), "utf8");
 const playheadSource = readFileSync(new URL("./PlayheadIndicator.tsx", import.meta.url), "utf8");
 
-const allowedTimelineTransitionProperties = [
-  "background-color",
-  "border-color",
-  "box-shadow",
-  "color",
-  "opacity",
-];
-
 function expectRule(css: string, selector: string): string {
   const selectorStart = css.indexOf(`${selector} {`);
   expect(selectorStart).toBeGreaterThanOrEqual(0);
@@ -31,28 +31,26 @@ function expectDeclaration(ruleBody: string, property: string): string {
   return declarationMatch?.[1].trim() ?? "";
 }
 
-function transitionProperties(transitionDeclaration: string): string[] {
-  const items: string[] = [];
-  let depth = 0;
-  let item = "";
-
-  for (const char of transitionDeclaration) {
-    if (char === "(") depth += 1;
-    if (char === ")") depth -= 1;
-    if (char === "," && depth === 0) {
-      items.push(item.trim());
-      item = "";
-      continue;
-    }
-    item += char;
-  }
-
-  if (item.trim().length > 0) items.push(item.trim());
-
-  return items.map((transition) => transition.split(/\s+/)[0]);
+function themeTokenValue(token: string): string {
+  const match = new RegExp(`${token}:\\s*([^;]+);`).exec(themeCss);
+  expect(match?.[1]).toBeDefined();
+  return match?.[1].trim() ?? "";
 }
 
 describe("timeline motion styles", () => {
+  it.each([
+    ["--timeline-track-label", "rgba(255, 255, 255, 0.5)"],
+    ["--timeline-tick-text", "rgba(255, 255, 255, 0.34)"],
+    ["--timeline-border-strong", "rgba(255, 255, 255, 0.2)"],
+    ["--timeline-group-member-tint", "rgba(255, 255, 255, 0.035)"],
+    ["--timeline-overlay-text", "rgba(255, 255, 255, 0.8)"],
+    ["--timeline-clip-shadow-dragging", "rgba(0, 0, 0, 0.4)"],
+    ["--timeline-playhead-glow", "rgba(60, 230, 172, 0.14)"],
+    ["--timeline-playhead-shadow", "rgba(0, 0, 0, 0.55)"],
+  ])("keeps the migrated default for %s", (token, expected) => {
+    expect(themeTokenValue(token)).toBe(expected);
+  });
+
   it("keeps clip motion reduced-motion gated and layout safe", () => {
     const mediaStart = studioCss.indexOf("@media (prefers-reduced-motion: no-preference)");
     expect(mediaStart).toBeGreaterThanOrEqual(0);
@@ -63,19 +61,73 @@ describe("timeline motion styles", () => {
 
     const motionMediaCss = studioCss.slice(mediaStart);
     const timelineClipMotionRule = expectRule(motionMediaCss, ".timeline-clip");
-    const clipTransition = expectDeclaration(timelineClipMotionRule, "transition");
 
-    expect(transitionProperties(clipTransition)).toEqual(allowedTimelineTransitionProperties);
-    expect(clipTransition).not.toMatch(/\b(?:all|left|width|top|bottom|transform)\b/);
+    expect(expectDeclaration(timelineClipMotionRule, "transition")).toBe(
+      "background-color 120ms ease-out",
+    );
   });
 
   it("layers the active mint bloom through opacity instead of a gradient background swap", () => {
     const baseTimelineClipRule = expectRule(studioCss, ".timeline-clip");
+    const timelineClipLabelRule = expectRule(studioCss, ".timeline-clip__label");
+    const timelineClipTimecodeRule = expectRule(studioCss, ".timeline-clip__timecode");
+    const audioClipRule = expectRule(studioCss, ".timeline-clip.is-audio");
+    const audioClipHoverRule = expectRule(studioCss, ".timeline-clip.is-audio.is-hovered");
+    const audioClipDraggingRule = expectRule(studioCss, ".timeline-clip.is-audio.is-dragging");
     const activeTimelineClipRule = expectRule(studioCss, ".timeline-clip[data-active]");
+    const selectedTimelineClipRule = expectRule(studioCss, ".timeline-clip.is-selected");
+    const activeSelectedTimelineClipRule = expectRule(
+      studioCss,
+      ".timeline-clip[data-active].is-selected",
+    );
     const bloomOverlayRule = expectRule(studioCss, ".timeline-clip::before");
     const activeBloomOverlayRule = expectRule(studioCss, ".timeline-clip[data-active]::before");
 
     expect(baseTimelineClipRule).toContain("background-color: var(--clip-bg)");
+    expect(baseTimelineClipRule).toContain("border: 1px solid var(--clip-border)");
+    expect(baseTimelineClipRule).toContain("box-shadow:");
+    expect(baseTimelineClipRule).toContain("inset 0 1px 0 var(--timeline-clip-highlight)");
+    expect(baseTimelineClipRule).toContain("var(--timeline-clip-shadow)");
+    expect(timelineClipLabelRule).toContain("background: var(--timeline-clip-chip-bg)");
+    expect(timelineClipLabelRule).toContain("color: var(--timeline-clip-chip-text)");
+    expect(timelineClipLabelRule).toContain("text-overflow: ellipsis");
+    expect(timelineClipLabelRule).toContain("max-width: calc(100% - 22px)");
+    expect(timelineClipTimecodeRule).toContain("color: var(--timeline-tick-text)");
+    expect(themeCss).toContain("--timeline-clip-bg: rgba(255, 255, 255, 0.12)");
+    expect(themeCss).toContain("--timeline-clip-border: rgba(255, 255, 255, 0.22)");
+    expect(themeCss).toContain("--timeline-track-label: rgba(255, 255, 255, 0.5)");
+    expect(themeCss).toContain("--timeline-tick-text: rgba(255, 255, 255, 0.34)");
+    expect(themeCss).toContain("--timeline-clip-label-active: rgba(232, 255, 247, 0.95)");
+    expect(themeCss).toContain("--timeline-clip-label-shadow: 0 1px 2px rgba(0, 0, 0, 0.85)");
+    expect(themeCss).toContain("--timeline-clip-selection: rgba(255, 255, 255, 0.85)");
+    expect(themeCss).toContain("--timeline-clip-selection-highlight: rgb(255 255 255 / 0.55)");
+    expect(themeCss).toContain("--timeline-clip-radius: 8px");
+    expect(themeCss).toContain("--timeline-clip-audio-radius: 21px");
+    expect(themeCss).toContain("--timeline-clip-highlight: rgb(255 255 255 / 0.08)");
+    expect(themeCss).toContain("--timeline-clip-shadow: 0 2px 6px rgb(0 0 0 / 0.3)");
+    expect(themeCss).toContain("--timeline-clip-chip-bg: rgba(15, 22, 18, 0.73)");
+    expect(themeCss).toContain("--timeline-clip-chip-audio-bg: rgba(25, 16, 38, 0.7)");
+    expect(themeCss).toContain("--timeline-clip-chip-text: #ffffff");
+    expect(themeCss).toContain("--timeline-row-bg: #edf0ed");
+    expect(themeCss).toContain("--timeline-clip-shadow: 0 2px 6px rgb(0 0 0 / 0.12)");
+    expect(themeCss).toContain("--timeline-clip-selection: #0f766e");
+    expect(themeCss).toContain("--timeline-clip-audio-bg: rgba(167, 139, 250, 0.16)");
+    expect(themeCss).toContain("--timeline-clip-audio-border: rgba(167, 139, 250, 0.4)");
+    expect(themeCss).toContain("--timeline-clip-audio-bg-hover: rgba(167, 139, 250, 0.24)");
+    expect(themeCss).toContain("--timeline-clip-audio-bg-dragging: rgba(60, 52, 84, 0.96)");
+    expect(audioClipRule).toContain("background-color: var(--timeline-clip-audio-bg)");
+    expect(audioClipRule).toContain("border-color: var(--timeline-clip-audio-border)");
+    expect(audioClipHoverRule).toContain("background-color: var(--timeline-clip-audio-bg-hover)");
+    expect(audioClipDraggingRule).toContain("var(--timeline-clip-audio-bg-dragging)");
+    expect(themeCss).toContain("--timeline-clip-selection: rgba(255, 255, 255, 0.85)");
+    expect(selectedTimelineClipRule).toContain(
+      "outline: 1.5px solid var(--timeline-clip-selection)",
+    );
+    expect(selectedTimelineClipRule).toContain("outline-offset: -1.5px");
+    expect(activeSelectedTimelineClipRule).toContain(
+      "outline: 1.5px solid var(--timeline-clip-selection)",
+    );
+    expect(activeSelectedTimelineClipRule).toContain("outline-offset: -1.5px");
     expect(activeTimelineClipRule).not.toContain("background: linear-gradient");
     expect(activeTimelineClipRule).toContain("border-color: var(--clip-border-active)");
     expect(activeTimelineClipRule).not.toContain("box-shadow");
@@ -85,6 +137,20 @@ describe("timeline motion styles", () => {
     expect(activeBloomOverlayRule).toContain("opacity: 1");
   });
 
+  it("routes timeline overlay colours through theme tokens", () => {
+    const overlaySource = timelineOverlaySources.join("\n");
+
+    expect(overlaySource).toContain("var(--timeline-shortcut-bg)");
+    expect(overlaySource).toContain("var(--timeline-thumbnail-shimmer)");
+    expect(overlaySource).toContain("var(--timeline-thumbnail-label-gradient)");
+    expect(overlaySource).toContain("var(--timeline-thumbnail-label-shadow)");
+    expect(overlaySource).toContain('"--timeline-waveform-bar-rgb"');
+    expect(overlaySource).toContain("var(--timeline-waveform-error)");
+    expect(overlaySource).toContain("var(--timeline-waveform-label-shadow)");
+    expect(overlaySource).toContain("var(--timeline-text-solid)");
+    expect(overlaySource).toContain("var(--timeline-accent)");
+  });
+
   it("targets trim handle bars without changing drag geometry", () => {
     const handleClassMatches = timelineClipSource.match(/className="timeline-clip__handle-bar"/g);
 

package/src/player/components/timelineProviderStateBuilders.ts

@@ -5,6 +5,26 @@ import type {
 } from "./TimelineProvider";
 import type { ResizingClipState } from "./useTimelineClipDrag";
 import type { TimelineLaneBaseProps } from "./timelineLaneProps";
+import type { DraggedClipState } from "./timelineClipDragTypes";
+import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
+import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
+
+export function resolveMultiDragPreview(
+  draggedClip: DraggedClipState | null,
+  selectedKeys: ReadonlySet<string>,
+): MultiDragPreviewInput | null {
+  // The dragged clip is a free ghost; selected companions follow the same
+  // clamped delta so the formation stays rigid at the lane boundary.
+  if (!draggedClip?.started) return null;
+  const draggedKey = getTimelineElementIdentity(draggedClip.element);
+  return {
+    dragStarted: true,
+    draggedKey,
+    draggedOriginStart: draggedClip.element.start,
+    draggedPreviewStart: draggedClip.previewStart,
+    selectedKeys,
+  };
+}
 
 export function resolveResizingElementIds(
   resizingClip: ResizingClipState | null,

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

@@ -1,11 +1,25 @@
 import { describe, expect, it } from "vitest";
 import {
+  clipWidthLadder,
+  defaultTimelineTheme,
   getClipHandleOpacity,
   getRenderedTimelineElement,
   getTimelineTrackStyle,
 } from "./timelineTheme";
 import { getTrackStyle } from "./timelineIcons";
 
+describe("clipWidthLadder", () => {
+  it("labels from 60px, keeps the picture below that, and uses one frame below 24px", () => {
+    expect(clipWidthLadder(200)).toBe("labeled");
+    expect(clipWidthLadder(60)).toBe("labeled");
+    expect(clipWidthLadder(59)).toBe("picture");
+    expect(clipWidthLadder(24)).toBe("picture");
+    expect(clipWidthLadder(23)).toBe("frame");
+    expect(defaultTimelineTheme.clipRadius).toBe("var(--timeline-clip-radius)");
+    expect(defaultTimelineTheme.audioClipRadius).toBe("var(--timeline-clip-audio-radius)");
+  });
+});
+
 describe("getTimelineTrackStyle", () => {
   it("uses one neutral clip style for every timeline tag", () => {
     const expectedStyle = {

package/src/player/components/timelineTheme.ts

@@ -27,14 +27,11 @@ export interface TimelineTheme {
   clipBorder: string;
   clipBorderHover: string;
   clipBorderActive: string;
-  clipShadow: string;
-  clipShadowHover: string;
-  clipShadowActive: string;
-  clipShadowDragging: string;
   handleColor: string;
   panelResizeSeam: string;
   panelResizeActive: string;
   clipRadius: string;
+  audioClipRadius: string;
 }
 
 const TRACK_STYLE: TimelineTrackStyle = {
@@ -67,18 +64,22 @@ export const defaultTimelineTheme: TimelineTheme = {
   clipBorder: "var(--timeline-clip-border)",
   clipBorderHover: "var(--timeline-clip-border-hover)",
   clipBorderActive: "var(--timeline-clip-border-active)",
-  // Shadows stay literal: a light host still wants a dark contact shadow, so
-  // these are not part of the surface/hairline/text/clip-colour theming ask.
-  clipShadow: "none",
-  clipShadowHover: "0 2px 8px rgba(0,0,0,0.2)",
-  clipShadowActive: "0 2px 8px rgba(0,0,0,0.2), 0 0 0 1px rgba(255,255,255,0.04)",
-  clipShadowDragging: "0 8px 24px rgba(0,0,0,0.4), 0 0 0 1px rgba(255,255,255,0.06)",
   handleColor: "var(--timeline-handle)",
   panelResizeSeam: "var(--timeline-resize-seam)",
   panelResizeActive: "var(--timeline-resize-active)",
-  clipRadius: "var(--radius-lg)",
+  clipRadius: "var(--timeline-clip-radius)",
+  audioClipRadius: "var(--timeline-clip-audio-radius)",
 };
 
+export type ClipWidthLadder = "labeled" | "picture" | "frame";
+
+/** Label chip from 60px. Under 24px the clip is one cropped frame. */
+export function clipWidthLadder(widthPx: number): ClipWidthLadder {
+  if (widthPx < 24) return "frame";
+  if (widthPx < 60) return "picture";
+  return "labeled";
+}
+
 export function getTimelineTrackStyle(_tag: string): TimelineTrackStyle {
   return TRACK_STYLE;
 }