@hyperframes/studio 0.8.58 → 0.8.60

package/src/player/components/useTimelineProviderState.tsx

@@ -10,6 +10,7 @@ import { useTimelineClipDrag } from "./useTimelineClipDrag";
 import type { ClipContextMenuState, TimelineContextValue } from "./TimelineProvider";
 import {
   buildTimelineMeta,
+  resolveMultiDragPreview,
   resolveRenderClipContent,
   resolveResizingElementIds,
   shouldIgnoreTimelinePointerDown,
@@ -30,7 +31,7 @@ import {
 } from "./useTimelineTrackLayout";
 import { useTimelineKeyframeHandlers } from "./useTimelineKeyframeHandlers";
 import { useTimelineGapHighlights } from "./useTimelineGapHighlights";
-import { TimelineRazorGuide, useTimelineRazorInteraction } from "./TimelineRazorInteraction";
+import { TimelineRazorGuideOverlay, useTimelineRazorInteraction } from "./TimelineRazorInteraction";
 import { useTimelinePerformanceTelemetry } from "./useTimelinePerformanceTelemetry";
 import {
   getEffectiveTimelineDuration,
@@ -44,6 +45,8 @@ import { useTimelineClipRenderWindow } from "./useTimelineClipRenderWindow";
 import { useTimelineActiveClips } from "./useTimelineActiveClips";
 import { useTimelineLaneMoveRefresh } from "./useTimelineLaneMoveRefresh";
 import { useTimelineLogicalFocus } from "./useTimelineLogicalFocus";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import { resolveSnapGuide } from "./timelineSnapping";
 export function useTimelineProviderState({
   onSeek,
   onDrillDown,
@@ -90,10 +93,10 @@ export function useTimelineProviderState({
     onSplitElement: onSplitElementOverride,
   });
   const theme = useMemo(() => ({ ...defaultTimelineTheme, ...themeOverrides }), [themeOverrides]);
+  const editContext = useTimelineEditContextOptional();
   const refreshAfterLaneMove = useTimelineLaneMoveRefresh();
   useMusicBeatAnalysis();
-  const rawElements = usePlayerStore((s) => s.elements);
-  const timelineElements = rawElements;
+  const timelineElements = usePlayerStore((s) => s.elements);
   const adjustedBeatAnalysis = useAdjustedBeatAnalysis();
   const duration = usePlayerStore((s) => s.duration);
   const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
@@ -108,7 +111,6 @@ export function useTimelineProviderState({
   );
   // The label column provides pre-t=0 space; otherwise keep TRACKS_LEFT_PAD after the gutter.
   const contentOrigin = labelMode ? LABEL_COL_W + GUTTER : GUTTER + TRACKS_LEFT_PAD;
-  const contentGutter = labelMode ? GUTTER : 0;
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatDragging = usePlayerStore((s) => s.beatDragging);
@@ -130,8 +132,8 @@ export function useTimelineProviderState({
   }, []);
   const lastScrollLeftRef = useRef(0);
   const effectiveDuration = useMemo(
-    () => getEffectiveTimelineDuration(duration, rawElements),
-    [duration, rawElements],
+    () => getEffectiveTimelineDuration(duration, timelineElements),
+    [duration, timelineElements],
   );
   const keyframeCache = usePlayerStore((s) => s.keyframeCache);
   useAutoExpandKeyframedClips(gsapAnimations);
@@ -406,7 +408,6 @@ export function useTimelineProviderState({
     handlePointerCancel,
   } = overlaysProps;
   const { rangeSelection, setRangeSelection } = overlays;
-
   const laneGapStrips = useTimelineGapHighlights({
     gapHighlight,
     tracks,
@@ -416,25 +417,24 @@ export function useTimelineProviderState({
     dragActive: draggedClip?.started === true || resizingClip != null,
     displayDuration,
   });
-
   const { major, minor, majorTickInterval } = useTimelineTicks(
     displayDuration,
     pps,
     timeDisplayMode,
     timelineFocus.rowVirtualizationActive ? renderTimeRange : undefined,
   );
-
   const getPreviewElement = useCallback(
     (element: TimelineElement): TimelineElement => getTimelinePreviewElement(element, resizingClip),
     [resizingClip],
   );
-
+  const draggedElement = draggedClip?.element ?? null;
+  const multiDragPreview = resolveMultiDragPreview(draggedClip, selectedElementIds);
   const canvasProps = {
     major,
     minor,
     pps,
     contentOrigin,
-    contentGutter,
+    contentGutter: labelMode ? GUTTER : 0,
     trackContentWidth: displayContentWidth,
     totalH: displayLayout.totalH,
     effectiveDuration,
@@ -501,6 +501,13 @@ export function useTimelineProviderState({
     onResizeElement,
     onMoveElement,
     beatDragging,
+    draggedElement,
+    snapGuide: resolveSnapGuide(draggedClip, resizingClip),
+    multiDragPreview,
+    onToggleTrackHidden: editContext.onToggleTrackHidden,
+    onTogglePropertyGroupKeyframe: editContext.onTogglePropertyGroupKeyframe,
+    onRazorSplit: editContext.onRazorSplit,
+    onRazorSplitAll: editContext.onRazorSplitAll,
   };
   const timelineRenderClipContent = resolveRenderClipContent(
     timelineFocus.rowVirtualizationActive,
@@ -559,7 +566,7 @@ export function useTimelineProviderState({
     labelColumnWidth: LABEL_COL_W,
     razorGuide:
       activeTool === "razor" && razorGuideX !== null ? (
-        <TimelineRazorGuide x={razorGuideX} />
+        <TimelineRazorGuideOverlay x={razorGuideX} />
       ) : null,
   });
   const contextValue: TimelineContextValue = {

package/src/player/lib/timelineElementHelpers.ts

@@ -12,6 +12,7 @@ import type { ClipManifestClip } from "./playbackTypes";
 import { isFinitePositive } from "./playbackAdapter";
 import { getSourceScopedSelectorIndex } from "../../utils/sourceScopedSelectorIndex";
 import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
+import { readElementFades } from "@hyperframes/core/audio-fade";
 
 // ---------------------------------------------------------------------------
 // Layer-reveal lift transparency
@@ -173,8 +174,27 @@ function applyPlaybackMetadataFromElement(entry: TimelineElement, el: Element):
   }
 }
 
+/** Sets or clears an optional field, so a re-parse after the attribute is removed drops it. */
+function setOptional<K extends keyof TimelineElement>(
+  entry: TimelineElement,
+  key: K,
+  value: TimelineElement[K] | undefined,
+): void {
+  if (value === undefined) delete entry[key];
+  else entry[key] = value;
+}
+
+/** `data-has-audio` and the clip-edge fades: what the mixer hears and how it enters and leaves. */
+function applyAudioMetadataFromElement(entry: TimelineElement, el: Element): void {
+  setOptional(entry, "hasAudio", el.getAttribute("data-has-audio") === "true" ? true : undefined);
+  const fades = readElementFades(el);
+  setOptional(entry, "fadeIn", fades.fadeIn > 0 ? fades.fadeIn : undefined);
+  setOptional(entry, "fadeOut", fades.fadeOut > 0 ? fades.fadeOut : undefined);
+}
+
 export function applyMediaMetadataFromElement(entry: TimelineElement, el: Element): void {
   applyPlaybackMetadataFromElement(entry, el);
+  applyAudioMetadataFromElement(entry, el);
 
   const mediaEl = resolveMediaElement(el);
   if (!mediaEl) return;

package/src/player/store/timelineElement.ts

@@ -54,6 +54,11 @@ export interface TimelineElement {
   playbackRate?: number;
   sourceDuration?: number;
   volume?: number;
+  /** `data-has-audio="true"` on a video: its sound is mixed, so it takes audio affordances (fades). */
+  hasAudio?: boolean;
+  /** Clip-edge fades from `data-fade-in` / `data-fade-out`, seconds; absent means none. */
+  fadeIn?: number;
+  fadeOut?: number;
   /** Verbatim `data-fx-chain` / `data-automation`; see automationLaneData. */
   fxChain?: string;
   automation?: string;

package/src/styles/hex-baseline.json

@@ -1,5 +1,5 @@
 {
-  "total": 385,
+  "total": 302,
   "files": {
     "packages/studio/src/captions/components/CaptionOverlay.tsx": 5,
     "packages/studio/src/captions/components/CaptionTimeline.tsx": 11,
@@ -49,35 +49,16 @@
     "packages/studio/src/components/sidebar/AudioRow.tsx": 2,
     "packages/studio/src/components/ui/HyperframesMark.tsx": 4,
     "packages/studio/src/hooks/useInlineTextEdit.ts": 1,
-    "packages/studio/src/player/components/AudioWaveform.tsx": 6,
+    "packages/studio/src/player/components/AudioWaveform.tsx": 1,
     "packages/studio/src/player/components/BeatStrip.tsx": 6,
     "packages/studio/src/player/components/CompositionThumbnail.tsx": 2,
-    "packages/studio/src/player/components/ImageThumbnail.tsx": 6,
-    "packages/studio/src/player/components/LayerDisclosureRow.tsx": 3,
     "packages/studio/src/player/components/Player.tsx": 2,
     "packages/studio/src/player/components/PlayerControls.tsx": 1,
-    "packages/studio/src/player/components/PlayheadIndicator.tsx": 3,
     "packages/studio/src/player/components/ShortcutsPanel.tsx": 7,
     "packages/studio/src/player/components/SpeedMenu.tsx": 2,
-    "packages/studio/src/player/components/TimelineAutomationLane.tsx": 4,
-    "packages/studio/src/player/components/TimelineCanvas.tsx": 13,
-    "packages/studio/src/player/components/TimelineClipDiamonds.tsx": 2,
-    "packages/studio/src/player/components/TimelineDiamondConnectors.tsx": 2,
-    "packages/studio/src/player/components/TimelineEmptyState.tsx": 1,
-    "packages/studio/src/player/components/TimelineFxButton.tsx": 8,
-    "packages/studio/src/player/components/TimelineGroupHeader.tsx": 6,
-    "packages/studio/src/player/components/TimelineGroupLaneLabels.tsx": 1,
-    "packages/studio/src/player/components/TimelineGroupRow.tsx": 1,
-    "packages/studio/src/player/components/TimelineRazorInteraction.tsx": 1,
-    "packages/studio/src/player/components/TimelineRuler.tsx": 1,
-    "packages/studio/src/player/components/TimelineShortcutHint.tsx": 2,
-    "packages/studio/src/player/components/TimelineTrackHeader.tsx": 2,
-    "packages/studio/src/player/components/TimelineTrackPlainHeader.tsx": 2,
-    "packages/studio/src/player/components/VideoThumbnail.tsx": 6,
-    "packages/studio/src/player/components/timelineTheme.ts": 5,
     "packages/studio/src/player/components/trackHeaderLabelRows.tsx": 6,
-    "packages/studio/src/styles/studio.css": 63,
     "packages/studio/src/telemetry/client.ts": 1,
-    "packages/studio/src/webmcp/webmcpTestUtils.ts": 1
+    "packages/studio/src/webmcp/webmcpTestUtils.ts": 1,
+    "packages/studio/src/styles/studio.css": 48
   }
 }

package/src/styles/studio.css

@@ -202,7 +202,10 @@ body {
 .timeline-clip {
   background-color: var(--clip-bg);
   border: 1px solid var(--clip-border);
-  border-radius: 8px;
+  border-radius: var(--timeline-clip-radius);
+  box-shadow:
+    inset 0 1px 0 var(--timeline-clip-highlight),
+    var(--timeline-clip-shadow);
 }
 
 .timeline-clip::before {
@@ -227,16 +230,19 @@ body {
    accented visual clips — so the audio zone at the bottom is visually separate
    at a glance (the timeline's kinds: visual on top, audio below). */
 .timeline-clip.is-audio {
-  background-color: rgba(167, 139, 250, 0.16);
-  border-color: rgba(167, 139, 250, 0.4);
+  background-color: var(--timeline-clip-audio-bg);
+  border-color: var(--timeline-clip-audio-border);
+  border-radius: var(--timeline-clip-audio-radius);
 }
 
 .timeline-clip.is-audio.is-hovered {
-  background-color: rgba(167, 139, 250, 0.24);
+  background-color: var(--timeline-clip-audio-bg-hover);
 }
 
 .timeline-clip.is-audio.is-dragging {
-  background-color: rgba(60, 52, 84, 0.96);
+  box-shadow:
+    inset 0 0 0 999px var(--timeline-clip-audio-bg-dragging),
+    0 8px 24px var(--timeline-clip-shadow-dragging);
 }
 
 .timeline-clip.is-hovered {
@@ -248,53 +254,56 @@ body {
 }
 
 .timeline-clip.is-selected {
-  box-shadow: 0 0 0 1.5px rgba(255, 255, 255, 0.85);
-}
-
-.timeline-clip[data-active].is-selected {
-  box-shadow: 0 0 0 1.5px rgba(255, 255, 255, 0.85);
+  outline: 1.5px solid var(--timeline-clip-selection);
+  outline-offset: -1.5px;
 }
 
-.timeline-clip.is-dragging {
-  /* Solid background so the picked-up clip reads clearly while dragging — audio
-     clips (waveform drawn on a separate layer) would otherwise look transparent. */
-  background-color: var(--clip-bg-dragging);
-  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+.timeline-clip.is-selected::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: 4;
+  border-radius: inherit;
+  box-shadow: inset 0 0 0 1px var(--timeline-clip-selection-highlight);
+  pointer-events: none;
 }
 
-/* Keep the white selection outline while dragging (a plain box-shadow alone gets
-   overridden by .is-dragging's drop shadow, so re-state both together). */
-.timeline-clip.is-selected.is-dragging {
-  box-shadow:
-    0 0 0 1.5px rgba(255, 255, 255, 0.85),
-    0 8px 24px rgba(0, 0, 0, 0.4);
+.timeline-clip[data-active].is-selected {
+  outline: 1.5px solid var(--timeline-clip-selection);
+  outline-offset: -1.5px;
 }
 
-.timeline-clip[data-active].is-selected.is-dragging {
+.timeline-clip.is-dragging {
+  /* Veil is a shadow, not background-color, so drop does not fade the hover fill. */
   box-shadow:
-    0 0 0 1.5px rgba(255, 255, 255, 0.85),
-    0 8px 24px rgba(0, 0, 0, 0.4);
+    inset 0 0 0 999px var(--clip-bg-dragging),
+    0 8px 24px var(--timeline-clip-shadow-dragging);
 }
 
 .timeline-clip__label {
   position: absolute;
-  top: 6px;
-  left: 12px;
-  right: 10px;
+  top: 5px;
+  left: 6px;
   z-index: 6;
+  width: fit-content;
+  max-width: calc(100% - 22px);
   overflow: hidden;
-  color: rgba(255, 255, 255, 0.5);
+  padding: 1px 5px;
+  border-radius: 4px;
+  background: var(--timeline-clip-chip-bg);
+  color: var(--timeline-clip-chip-text);
   font-size: 10px;
   font-weight: 500;
-  line-height: 1;
+  line-height: 16px;
   pointer-events: none;
-  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.85);
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
-.timeline-clip[data-active] .timeline-clip__label {
-  color: rgba(232, 255, 247, 0.95);
+.timeline-clip.is-audio .timeline-clip__label {
+  top: 11px;
+  left: 9px;
+  background: var(--timeline-clip-chip-audio-bg);
 }
 
 .timeline-clip__timecode {
@@ -302,7 +311,7 @@ body {
   bottom: 6px;
   left: 12px;
   overflow: hidden;
-  color: rgba(255, 255, 255, 0.34);
+  color: var(--timeline-tick-text);
   font-family: var(--font-mono);
   font-size: 9px;
   font-variant-numeric: tabular-nums;
@@ -313,20 +322,7 @@ body {
 
 @media (prefers-reduced-motion: no-preference) {
   .timeline-clip {
-    transition:
-      background-color 200ms cubic-bezier(0.22, 1, 0.36, 1),
-      border-color 200ms cubic-bezier(0.22, 1, 0.36, 1),
-      box-shadow 200ms cubic-bezier(0.22, 1, 0.36, 1),
-      color 200ms cubic-bezier(0.22, 1, 0.36, 1),
-      opacity 200ms cubic-bezier(0.22, 1, 0.36, 1);
-  }
-
-  .timeline-clip::before {
-    transition: opacity 200ms cubic-bezier(0.22, 1, 0.36, 1);
-  }
-
-  .timeline-clip__label {
-    transition: color 200ms cubic-bezier(0.22, 1, 0.36, 1);
+    transition: background-color 120ms ease-out;
   }
 
   .timeline-clip__handle-bar {

package/src/styles/theme.css

@@ -62,6 +62,42 @@
   --timeline-tick-major: rgba(255, 255, 255, 0.1);
   --timeline-tick-minor: rgba(255, 255, 255, 0.06);
   --timeline-clip-bg: rgba(255, 255, 255, 0.12);
+  --timeline-clip-label-active: rgba(232, 255, 247, 0.95);
+  --timeline-clip-label-shadow: 0 1px 2px rgba(0, 0, 0, 0.85);
+  --timeline-clip-audio-bg: rgba(167, 139, 250, 0.16);
+  --timeline-clip-audio-border: rgba(167, 139, 250, 0.4);
+  --timeline-clip-audio-bg-hover: rgba(167, 139, 250, 0.24);
+  --timeline-clip-audio-bg-dragging: rgba(60, 52, 84, 0.96);
+  --timeline-clip-selection: rgba(255, 255, 255, 0.85);
+  --timeline-clip-selection-highlight: rgb(255 255 255 / 0.55);
+  --timeline-clip-radius: 8px;
+  --timeline-clip-audio-radius: 21px;
+  --timeline-clip-highlight: rgb(255 255 255 / 0.08);
+  --timeline-clip-shadow: 0 2px 6px rgb(0 0 0 / 0.3);
+  --timeline-clip-chip-bg: rgba(15, 22, 18, 0.73);
+  --timeline-clip-chip-audio-bg: rgba(25, 16, 38, 0.7);
+  --timeline-clip-chip-text: #ffffff;
+  --timeline-shortcut-bg: rgba(17, 23, 35, 0.84);
+  --timeline-thumbnail-shimmer: linear-gradient(
+    90deg,
+    rgba(255, 255, 255, 0.02) 0%,
+    rgba(255, 255, 255, 0.05) 50%,
+    rgba(255, 255, 255, 0.02) 100%
+  );
+  --timeline-thumbnail-label-gradient: linear-gradient(
+    to top,
+    rgba(0, 0, 0, 0.85) 0%,
+    rgba(0, 0, 0, 0.4) 60%,
+    transparent 100%
+  );
+  --timeline-thumbnail-label-shadow: 0 1px 2px rgba(0, 0, 0, 0.9);
+  --timeline-waveform-bar-rgb: 75, 163, 210;
+  --timeline-waveform-error: repeating-linear-gradient(
+    90deg,
+    rgba(75, 163, 210, 0.35) 0 2px,
+    transparent 2px 5px
+  );
+  --timeline-waveform-label-shadow: 0 1px 3px rgba(0, 0, 0, 0.9);
   --timeline-clip-bg-active: rgba(60, 230, 172, 0.2);
   --timeline-clip-bg-hover: rgba(255, 255, 255, 0.16);
   --timeline-clip-bg-dragging: rgba(38, 42, 52, 0.96);
@@ -69,11 +105,49 @@
   --timeline-clip-border-hover: rgba(60, 230, 172, 0.75);
   --timeline-clip-border-active: rgba(60, 230, 172, 0.55);
   --timeline-handle: rgba(255, 255, 255, 0.55);
+  /* Audio clip fades: the shaded wedge over the faded gain, and the corner dots. */
+  --timeline-fade-shade: rgba(0, 0, 0, 0.38);
+  --timeline-fade-dot-active: rgba(255, 255, 255, 1);
+  --timeline-fade-dot-ring: rgba(0, 0, 0, 0.55);
   --timeline-resize-seam: rgba(255, 255, 255, 0.12);
   --timeline-resize-active: rgba(255, 255, 255, 0.24);
   --timeline-track-clip-fill: rgba(255, 255, 255, 0.055);
   --timeline-track-clip-active: rgba(60, 230, 172, 0.16);
   --timeline-track-label: rgba(255, 255, 255, 0.5);
+  --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-accent: #3ce6ac;
+  --timeline-accent-soft: rgba(60, 230, 172, 0.18);
+  --timeline-accent-faint: rgba(60, 230, 172, 0.055);
+  --timeline-accent-fill: rgba(60, 230, 172, 0.1);
+  --timeline-accent-glow: rgba(60, 230, 172, 0.5);
+  --timeline-accent-border: rgba(60, 230, 172, 0.7);
+  --timeline-accent-rail: rgba(60, 230, 172, 0.35);
+  --timeline-accent-hover: rgba(60, 230, 172, 0.25);
+  --timeline-accent-button-bg: rgba(60, 230, 172, 0.15);
+  --timeline-danger: rgba(239, 68, 68, 0.7);
+  --timeline-info-bg: rgba(59, 130, 246, 0.12);
+  --timeline-info-border: rgba(59, 130, 246, 0.4);
+  --timeline-dialog-bg: #1b1b1f;
+  --timeline-diamond-bg: #171717;
+  --timeline-diamond-border: rgba(255, 255, 255, 0.14);
+  --timeline-text-solid: #ffffff;
+  --timeline-text-faint: rgba(255, 255, 255, 0.35);
+  --timeline-text-dim: rgba(255, 255, 255, 0.4);
+  --timeline-text-soft: rgba(255, 255, 255, 0.75);
+  --timeline-text-bright: rgba(255, 255, 255, 0.7);
+  --timeline-snap-guide: rgba(255, 255, 255, 0.6);
+  --timeline-overlay-bg: rgba(0, 0, 0, 0.8);
+  --timeline-overlay-bg-strong: rgba(0, 0, 0, 0.85);
+  --timeline-input-bg: rgba(0, 0, 0, 0.3);
+  --timeline-automation-rail: rgba(255, 255, 255, 0.08);
+  --timeline-automation-point-muted: rgba(0, 0, 0, 0.5);
+  --timeline-diamond-muted: #a3a3a3;
+  --timeline-beat: rgb(34, 197, 94);
+  --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);
 
   /* -------------------------------------------------------------- geometry */
 
@@ -142,7 +216,14 @@
   --duration-press: 120ms;
   --duration-hover: 150ms;
   --duration-expand: 160ms;
-  --duration-open: 180ms;
+  /* Menus, popovers, and dropdowns. Open is ease-out; close is shorter and ease-in. */
+  --duration-open: 120ms;
+  --duration-close: 90ms;
+  /* Tooltips use the same enter shape on a shorter open. */
+  --duration-tooltip: 100ms;
+  /* Visible on the first frame. Never enter from scale 0 or opacity 0. */
+  --popup-enter-opacity: 0.8;
+  --popup-enter-scale: 0.97;
 
   /* ------------------------------------------------------------------ icon */
 
@@ -260,6 +341,33 @@
   --color-white: #fff;
 }
 
+/* One paper block. A host sets data-theme="paper" on the document element. */
+:root[data-theme="paper"] {
+  --timeline-shell-bg: #f4f6f3;
+  --timeline-row-bg: #edf0ed;
+  --timeline-clip-bg: #c9d1cb;
+  --timeline-clip-shadow: 0 2px 6px rgb(0 0 0 / 0.12);
+  --timeline-clip-highlight: rgb(255 255 255 / 0.08);
+  --timeline-clip-selection: #0f766e;
+  --timeline-clip-selection-highlight: rgb(255 255 255 / 0.55);
+  --timeline-clip-chip-bg: rgba(15, 22, 18, 0.73);
+  --timeline-clip-chip-audio-bg: rgba(25, 16, 38, 0.7);
+  --timeline-clip-chip-text: #ffffff;
+  --timeline-clip-audio-bg: rgb(150, 128, 180);
+  --timeline-clip-audio-bg-hover: rgb(135, 109, 170);
+  --timeline-clip-audio-bg-dragging: rgb(232, 224, 242);
+  --timeline-clip-audio-border: rgba(113, 80, 155, 0.45);
+  --timeline-clip-audio-muted-bg: rgb(156, 161, 157);
+  --timeline-audio-link: #626d66;
+  --timeline-waveform-bar-rgb: 20, 12, 32;
+  --timeline-waveform-muted-rgb: 24, 28, 26;
+  --timeline-waveform-error: repeating-linear-gradient(
+    90deg,
+    rgba(20, 12, 32, 0.35) 0 2px,
+    transparent 2px 5px
+  );
+}
+
 /* Motion durations as utilities, since Tailwind has no `--duration-*`
  * namespace. Each one zeroes itself under `prefers-reduced-motion`, so a
  * caller cannot forget the reduced-motion case. */

package/src/styles/theme.test.ts

@@ -109,6 +109,15 @@ describe("studio theme", () => {
     expect(vars.get("--text-lg")).toBe("1.125rem");
   });
 
+  it("opens menus from a visible shape and closes them faster", () => {
+    expect(declaredValue("--duration-open")).toBe("120ms");
+    expect(declaredValue("--duration-close")).toBe("90ms");
+    expect(declaredValue("--duration-tooltip")).toBe("100ms");
+    expect(declaredValue("--popup-enter-opacity")).toBe("0.8");
+    expect(declaredValue("--popup-enter-scale")).toBe("0.97");
+    expect(declaredValue("--duration-hover")).toBe("150ms");
+  });
+
   it("compiles a motion-duration utility with a reduced-motion variant", async () => {
     const css = await build("studio.css", ["duration-press", "duration-open"]);
 

package/src/utils/audioMeterMath.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import {
+  levelToFraction,
+  markFraction,
+  SILENT_CHANNEL,
+  stepChannel,
+  stepPair,
+} from "./audioMeterMath";
+
+describe("levelToFraction", () => {
+  it("puts each dB mark on its equally spaced stop", () => {
+    [1, 0.8, 0.6, 0.4, 0.2].forEach((f, i) =>
+      expect(markFraction([0, -3, -6, -12, -24][i]!)).toBeCloseTo(f, 6),
+    );
+  });
+  it("clamps silence and overs", () => {
+    expect(levelToFraction(0)).toBe(0);
+    expect(levelToFraction(4)).toBe(1);
+  });
+  it("is monotonic between marks", () => {
+    expect(levelToFraction(0.5)).toBeGreaterThan(markFraction(-12));
+    expect(levelToFraction(0.5)).toBeLessThan(markFraction(-3));
+  });
+});
+
+describe("stepChannel", () => {
+  it("attacks instantly, holds the peak, then falls", () => {
+    let ch = stepChannel(SILENT_CHANNEL, 1, 0, 16);
+    expect(ch.level).toBe(1);
+    ch = stepChannel(ch, 0, 500, 16);
+    expect(ch.peak).toBe(1);
+    expect(ch.level).toBeLessThan(1);
+    ch = stepChannel(ch, 0, 2000, 500);
+    expect(ch.peak).toBeLessThan(1);
+  });
+});
+
+describe("stepPair", () => {
+  it("returns the same pair while silent at rest, and moves on sound", () => {
+    const rest = stepPair(undefined, undefined, 0, 16);
+    expect(stepPair(rest, { l: 0, r: 0 }, 16, 16)).toBe(rest);
+    expect(stepPair(rest, { l: 1, r: 0 }, 32, 16)).not.toBe(rest);
+  });
+});

package/src/utils/audioMeterMath.ts

@@ -0,0 +1,79 @@
+import { useMemo } from "react";
+import { audioDbToGain, audioGainToDb } from "@hyperframes/core/audio-gain";
+import { usePlayerStore, type TimelineElement } from "../player";
+import { isAudioTimelineElement } from "./timelineInspector";
+
+/** dB stops of the meter scale, top to bottom; equal spacing between stops. */
+export const METER_DB_MARKS = [0, -3, -6, -12, -24] as const;
+const FLOOR_DB = -60;
+const STOPS = [...METER_DB_MARKS, FLOOR_DB];
+
+const FALL_PER_SECOND = 0.9;
+const HOLD_MS = 1200;
+
+/** Linear peak (0..1) to a 0..1 bar fraction along the piecewise-linear dB scale. */
+export function levelToFraction(linear: number): number {
+  const db = linear > 0 ? audioGainToDb(linear) : FLOOR_DB;
+  if (db >= 0) return 1;
+  if (db <= FLOOR_DB) return 0;
+  const j = STOPS.findIndex((stop) => db >= stop);
+  const hi = STOPS[j - 1] as number;
+  const lo = STOPS[j] as number;
+  return (STOPS.length - 1 - j + (db - lo) / (hi - lo)) / (STOPS.length - 1);
+}
+
+/** Fraction of the bar height at which a dB mark sits, 0 at the bottom. */
+export function markFraction(db: number): number {
+  return levelToFraction(audioDbToGain(db));
+}
+
+export interface MeterChannel {
+  level: number;
+  peak: number;
+  peakAt: number;
+}
+
+export const SILENT_CHANNEL: MeterChannel = { level: 0, peak: 0, peakAt: 0 };
+
+/** Instant attack, steady fall; the peak holds for HOLD_MS, then falls with the bar. */
+export function stepChannel(
+  prev: MeterChannel,
+  linear: number,
+  now: number,
+  dtMs: number,
+): MeterChannel {
+  const fall = (dtMs / 1000) * FALL_PER_SECOND;
+  const target = levelToFraction(linear);
+  const level = Math.max(target, prev.level - fall);
+  if (target >= prev.peak) return { level, peak: target, peakAt: now };
+  if (now - prev.peakAt < HOLD_MS) return { level, peak: prev.peak, peakAt: prev.peakAt };
+  return { level, peak: Math.max(target, prev.peak - fall), peakAt: prev.peakAt };
+}
+
+export type MeterPair = [MeterChannel, MeterChannel];
+
+const atRest = (ch: MeterChannel): boolean => ch.level === 0 && ch.peak === 0;
+
+/** Steps both channels; returns `prev` itself while silent and at rest, so callers can skip the paint. */
+export function stepPair(
+  prev: MeterPair | undefined,
+  raw: { l: number; r: number } | undefined,
+  now: number,
+  dtMs: number,
+): MeterPair {
+  const [l, r] = prev ?? [SILENT_CHANNEL, SILENT_CHANNEL];
+  const silent = !raw?.l && !raw?.r;
+  if (prev && silent && atRest(l) && atRest(r)) return prev;
+  return [stepChannel(l, raw?.l ?? 0, now, dtMs), stepChannel(r, raw?.r ?? 0, now, dtMs)];
+}
+
+/** The meters appear only for a project with at least one audio clip or group. */
+function hasProjectAudio(elements: readonly TimelineElement[]): boolean {
+  return elements.some((el) => isAudioTimelineElement(el) || el.audioGroup !== undefined);
+}
+
+/** Scans once per `elements` change, not on every store update (the playhead ticks each frame). */
+export function useProjectHasAudio(): boolean {
+  const elements = usePlayerStore((s) => s.elements);
+  return useMemo(() => hasProjectAudio(elements), [elements]);
+}

package/src/utils/audioMeterVisibility.ts

@@ -0,0 +1,14 @@
+import { create } from "zustand";
+import { readStudioUiPreferences, writeStudioUiPreferences } from "./studioUiPreferences";
+
+/** Whether the audio meter strip is shown; persisted, off unless the user showed it. */
+export const useAudioMetersVisible = create<{
+  visible: boolean;
+  setVisible: (visible: boolean) => void;
+}>((set) => ({
+  visible: readStudioUiPreferences().audioMetersVisible ?? false,
+  setVisible: (visible) => {
+    writeStudioUiPreferences({ audioMetersVisible: visible });
+    set({ visible });
+  },
+}));