@hyperframes/studio 0.8.6 → 0.8.7

package/src/player/components/ShortcutsPanel.tsx

@@ -1,4 +1,4 @@
-import { useState, useCallback, useId, memo } from "react";
+import { useState, useCallback, useEffect, useId, useRef, memo } from "react";
 import { formatTime, frameToSeconds } from "../lib/time";
 import { Tooltip } from "../../components/ui";
 import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
@@ -19,7 +19,7 @@ const SHORTCUT_SECTIONS = [
     ],
   },
   {
-    title: "Keyframes",
+    title: "Keyframes (when an element is selected)",
     hints: [
       { key: "K", label: "Add keyframe at playhead" },
       { key: "Del", label: "Delete selected keyframe" },
@@ -37,9 +37,10 @@ const SHORTCUT_SECTIONS = [
       { key: "⌘V", label: "Paste element" },
       { key: "⌘X", label: "Cut element" },
       { key: "S", label: "Split clip at playhead" },
+      { key: "⇧Click", label: "Razor tool: split all tracks" },
       { key: "⌘G", label: "Group elements" },
       { key: "⌘⇧G", label: "Ungroup" },
-      { key: "Del", label: "Delete selected element" },
+      { key: "Del", label: "Delete selected element (no keyframe selected)" },
     ],
   },
   {
@@ -112,6 +113,20 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
   const shortcutsPanelId = useId();
   const closeShortcuts = useCallback(() => setShowShortcuts(false), []);
   const shortcutsPanelRef = useContextMenuDismiss(closeShortcuts);
+  const panelBodyRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  // Move focus into the panel on open so keyboard users can scroll and read
+  // it; hand focus back to the trigger on close.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!showShortcuts) return;
+    const trigger = triggerRef.current;
+    panelBodyRef.current?.focus();
+    return () => {
+      trigger?.focus();
+    };
+  }, [showShortcuts]);
 
   const commitJumpFrame = useCallback(() => {
     if (disabled) return;
@@ -141,6 +156,7 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
     <div ref={shortcutsPanelRef} className="relative flex-shrink-0">
       <Tooltip label="Shortcuts and tools">
         <button
+          ref={triggerRef}
           type="button"
           onClick={() => setShowShortcuts((v) => !v)}
           className={`flex h-7 w-7 items-center justify-center rounded-md transition-colors ${
@@ -169,11 +185,14 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
       {showShortcuts && (
         <div
           id={shortcutsPanelId}
+          ref={panelBodyRef}
+          tabIndex={-1}
           role="dialog"
+          aria-label="Keyboard shortcuts and tools"
           // Deliberately NOT aria-modal. This is a non-modal disclosure: focus is
           // not trapped and the rest of the editor stays operable, so claiming
           // modality would make assistive tech treat the whole app as inert.
-          className="absolute bottom-full right-0 mb-2 z-50 rounded-lg shadow-xl min-w-[220px] overflow-y-auto"
+          className="absolute bottom-full right-0 mb-2 z-50 rounded-lg shadow-xl min-w-[220px] overflow-y-auto outline-none"
           style={{
             background: "#161618",
             border: "1px solid rgba(255,255,255,0.08)",

package/src/player/components/SpeedMenu.tsx

@@ -1,6 +1,7 @@
-import { useState, useRef, useEffect, memo } from "react";
+import { useState, useCallback, memo } from "react";
 import { trackStudioEvent } from "../../utils/studioTelemetry";
 import { Tooltip } from "../../components/ui";
+import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
 
 const SPEED_OPTIONS = [0.25, 0.5, 1, 1.5, 2] as const;
 
@@ -16,23 +17,10 @@ export const SpeedMenu = memo(function SpeedMenu({
   disabled,
 }: SpeedMenuProps) {
   const [showSpeedMenu, setShowSpeedMenu] = useState(false);
-  const speedMenuContainerRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (!showSpeedMenu) return;
-    const handleMouseDown = (e: MouseEvent) => {
-      if (
-        speedMenuContainerRef.current &&
-        !speedMenuContainerRef.current.contains(e.target as Node)
-      ) {
-        setShowSpeedMenu(false);
-      }
-    };
-    document.addEventListener("mousedown", handleMouseDown);
-    return () => {
-      document.removeEventListener("mousedown", handleMouseDown);
-    };
-  }, [showSpeedMenu]);
+  const closeMenu = useCallback(() => setShowSpeedMenu(false), []);
+  // Ref on the container (trigger + menu) so trigger clicks toggle instead of
+  // close-then-reopen; Escape also dismisses.
+  const speedMenuContainerRef = useContextMenuDismiss(closeMenu);
 
   return (
     <div ref={speedMenuContainerRef} className="relative flex-shrink-0">
@@ -41,6 +29,9 @@ export const SpeedMenu = memo(function SpeedMenu({
           type="button"
           onClick={() => setShowSpeedMenu((v) => !v)}
           disabled={disabled}
+          aria-haspopup="menu"
+          aria-expanded={showSpeedMenu}
+          aria-label="Playback speed"
           className="h-7 w-8 rounded-md font-mono text-[10px] tabular-nums text-neutral-500 transition-colors hover:text-neutral-200 disabled:opacity-30"
         >
           {playbackRate === 1 ? "1x" : `${playbackRate}x`}
@@ -48,33 +39,34 @@ export const SpeedMenu = memo(function SpeedMenu({
       </Tooltip>
       {showSpeedMenu && (
         <div
+          role="menu"
+          aria-label="Playback speed options"
           className="absolute bottom-full right-0 mb-1.5 rounded-lg shadow-xl z-50 min-w-[56px] overflow-hidden"
           style={{ background: "#161618", border: "1px solid rgba(255,255,255,0.08)" }}
         >
-          {SPEED_OPTIONS.map((rate) => (
-            <button
-              key={rate}
-              onClick={() => {
-                trackStudioEvent("playback", { action: "speed_change", rate });
-                setPlaybackRate(rate);
-                setShowSpeedMenu(false);
-              }}
-              className="block w-full px-3 py-1.5 text-[11px] text-left font-mono tabular-nums transition-colors"
-              style={{
-                color: rate === playbackRate ? "#FAFAFA" : "#71717A",
-                background: rate === playbackRate ? "rgba(255,255,255,0.06)" : "transparent",
-              }}
-              onMouseEnter={(e) => {
-                if (rate !== playbackRate)
-                  e.currentTarget.style.background = "rgba(255,255,255,0.04)";
-              }}
-              onMouseLeave={(e) => {
-                if (rate !== playbackRate) e.currentTarget.style.background = "transparent";
-              }}
-            >
-              {rate}x
-            </button>
-          ))}
+          {SPEED_OPTIONS.map((rate) => {
+            const isCurrent = rate === playbackRate;
+            return (
+              <button
+                key={rate}
+                type="button"
+                role="menuitemradio"
+                aria-checked={isCurrent}
+                onClick={() => {
+                  trackStudioEvent("playback", { action: "speed_change", rate });
+                  setPlaybackRate(rate);
+                  setShowSpeedMenu(false);
+                }}
+                className={`block w-full px-3 py-1.5 text-[11px] text-left font-mono tabular-nums transition-colors outline-none focus-visible:bg-white/[0.04] ${
+                  isCurrent
+                    ? "text-neutral-50 bg-white/[0.06]"
+                    : "text-neutral-500 hover:bg-white/[0.04]"
+                }`}
+              >
+                {rate}x
+              </button>
+            );
+          })}
         </div>
       )}
     </div>

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

@@ -556,11 +556,11 @@ describe("Timeline provider boundary", () => {
     // Keyframed clip-1 is expanded by default (AE/Figma default); its disclosure
     // lives in the left column. clip-2 has no keyframes so it never shows one.
     const collapseButton = host.querySelector<HTMLButtonElement>(
-      'button[aria-label="Collapse clip-1 keyframes"]',
+      'button[aria-label="Hide clip-1 lanes"]',
     );
     expect(collapseButton).not.toBeNull();
-    expect(host.querySelector('button[aria-label="Expand clip-2 keyframes"]')).toBeNull();
-    expect(host.querySelector('button[aria-label="Collapse clip-2 keyframes"]')).toBeNull();
+    expect(host.querySelector('button[aria-label="Show clip-2 lanes"]')).toBeNull();
+    expect(host.querySelector('button[aria-label="Hide clip-2 lanes"]')).toBeNull();
 
     const clip = host.querySelector<HTMLElement>('[data-el-id="clip-1"]');
     const row = clip?.parentElement?.parentElement;
@@ -571,7 +571,7 @@ describe("Timeline provider boundary", () => {
     expectTrackExpansion(row, [], TRACK_H);
 
     const expandButton = host.querySelector<HTMLButtonElement>(
-      'button[aria-label="Expand clip-1 keyframes"]',
+      'button[aria-label="Show clip-1 lanes"]',
     );
     expect(expandButton).not.toBeNull();
     act(() => expandButton?.click());
@@ -603,8 +603,8 @@ describe("Timeline provider boundary", () => {
     const row = host.querySelector<HTMLElement>('[data-el-id="narration-1"]')?.parentElement
       ?.parentElement;
     // A row of several clips is named for the track, so the caret is too.
-    const caret = () => host.querySelector<HTMLButtonElement>('button[aria-label$=" keyframes"]');
-    expect(caret()?.getAttribute("aria-label")).toBe("Expand Track 1 keyframes");
+    const caret = () => host.querySelector<HTMLButtonElement>('button[aria-label$=" lanes"]');
+    expect(caret()?.getAttribute("aria-label")).toBe("Show Track 1 lanes");
 
     act(() => caret()?.click());
     // One shared volume row, and BOTH clips hold it open.
@@ -647,7 +647,7 @@ describe("Timeline provider boundary", () => {
     });
     const root = createRoot(host);
     act(() => root.render(React.createElement(Timeline)));
-    act(() => host.querySelector<HTMLButtonElement>('button[aria-label$=" keyframes"]')?.click());
+    act(() => host.querySelector<HTMLButtonElement>('button[aria-label$=" lanes"]')?.click());
 
     const before = [...host.querySelectorAll(".hf-automation-lane")];
     expect(before).toHaveLength(2);

package/src/player/components/Timeline.tsx

@@ -1,6 +1,5 @@
 import { useRef, useMemo, useCallback, useState, memo } from "react";
-import { useMusicBeatAnalysis } from "../../hooks/useMusicBeatAnalysis";
-import { remapBeatAnalysisToComposition } from "../../utils/beatEditActions";
+import { useAdjustedBeatAnalysis, useMusicBeatAnalysis } from "../../hooks/useMusicBeatAnalysis";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { useExpandedTimelineElements } from "../hooks/useExpandedTimelineElements";
 import { defaultTimelineTheme } from "./timelineTheme";
@@ -39,7 +38,6 @@ import {
 import { useTimelineSelectionLifecycle } from "./useTimelineSelectionLifecycle";
 import { useTimelineShiftModifier } from "./useTimelineShiftModifier";
 import { useTimelineTicks } from "./useTimelineTicks";
-import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
 import { useTimelineClipRenderWindow } from "./useTimelineClipRenderWindow";
 import { useTimelineActiveClips } from "./useTimelineActiveClips";
@@ -109,13 +107,7 @@ export const Timeline = memo(function Timeline({
   useMusicBeatAnalysis();
   const rawElements = usePlayerStore((s) => s.elements);
   const expandedElements = useExpandedTimelineElements();
-  const beatAnalysis = usePlayerStore((s) => s.beatAnalysis);
-  const musicElement = usePlayerStore((s) => getTimelineElementIndexes(s.elements).musicElement);
-  const beatEdits = usePlayerStore((s) => s.beatEdits);
-  const adjustedBeatAnalysis = useMemo(
-    () => remapBeatAnalysisToComposition(beatAnalysis, musicElement, beatEdits),
-    [beatAnalysis, musicElement, beatEdits],
-  );
+  const adjustedBeatAnalysis = useAdjustedBeatAnalysis();
   const duration = usePlayerStore((s) => s.duration);
   const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
   const timelineReady = usePlayerStore((s) => s.timelineReady);
@@ -158,6 +150,8 @@ export const Timeline = memo(function Timeline({
     laneCounts,
     rowGeometry,
     rowGeometryRef,
+    groups,
+    trackGroupOf,
   } = useTimelineTrackLayout(
     expandedElements,
     gsapAnimations,
@@ -289,6 +283,8 @@ export const Timeline = memo(function Timeline({
     laneCounts,
     selectedElementId,
     selectedElementIds,
+    groups,
+    trackGroupOf,
     gsapAnimations,
     elements: expandedElements,
     pixelsPerSecond: pps,
@@ -509,6 +505,7 @@ export const Timeline = memo(function Timeline({
           trackOrder={trackOrder}
           tracks={tracks}
           trackStyles={trackStyles}
+          groups={groups}
           laneCounts={laneCounts}
           selectedElementId={selectedElementId}
           selectedElementIds={selectedElementIds}

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

@@ -0,0 +1,81 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createRoot } from "react-dom/client";
+import { serializeAudioFxChain } from "@hyperframes/core/audio-fx";
+import { TimelineFxButton } from "./TimelineFxButton.js";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function byTextButton(host: HTMLElement, text: string): HTMLButtonElement | undefined {
+  return Array.from(host.querySelectorAll("button")).find((b) => b.textContent?.includes(text));
+}
+
+function mount(node: React.ReactElement) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  act(() => createRoot(host).render(node));
+  return host;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("TimelineFxButton", () => {
+  it("reads FX with no count when the chain is empty", () => {
+    const host = mount(
+      <TimelineFxButton
+        variant="chain"
+        fxChainRaw={undefined}
+        onChainChange={vi.fn()}
+        onOpenRack={vi.fn()}
+      />,
+    );
+    expect(byTextButton(host, "FX")?.textContent).toBe("FX");
+  });
+
+  it("counts only enabled nodes", () => {
+    const chain = {
+      version: 1 as const,
+      nodes: [
+        { type: "peaking", params: {}, enabled: true },
+        { type: "gain", params: {}, enabled: false },
+      ],
+    };
+    const host = mount(
+      <TimelineFxButton
+        variant="chain"
+        fxChainRaw={serializeAudioFxChain(chain)}
+        onChainChange={vi.fn()}
+        onOpenRack={vi.fn()}
+      />,
+    );
+    expect(byTextButton(host, "FX 1")).toBeDefined();
+  });
+
+  it("opens the popover on click, anchored off the button", () => {
+    const host = mount(
+      <TimelineFxButton
+        variant="chain"
+        fxChainRaw={undefined}
+        onChainChange={vi.fn()}
+        onOpenRack={vi.fn()}
+      />,
+    );
+    expect(host.querySelector('[role="dialog"]')).toBeNull();
+    act(() => byTextButton(host, "FX")?.click());
+    expect(document.querySelector('[role="dialog"]')).toBeTruthy();
+  });
+
+  it("group-pointer variant offers Group instead of a popover", () => {
+    const onGroupClips = vi.fn();
+    const host = mount(<TimelineFxButton variant="group-pointer" onGroupClips={onGroupClips} />);
+    act(() => byTextButton(host, "FX")?.click());
+    const groupButton = document.body.querySelectorAll("button");
+    const group = Array.from(groupButton).find((b) => b.textContent === "Group");
+    expect(group).toBeDefined();
+    act(() => group?.click());
+    expect(onGroupClips).toHaveBeenCalledTimes(1);
+  });
+});

package/src/player/components/TimelineFxButton.tsx

@@ -0,0 +1,143 @@
+/**
+ * The FX entry point from the timeline (C1) — a track or group header button
+ * that opens the same preset shelf the property panel's rack uses, without
+ * requiring a trip through the panel first.
+ *
+ * Rendered on group rows and on track rows holding exactly one audio clip
+ * (see `plans/audio-mixer-groups.md` §1.6 and the execution runbook's C1 step
+ * — a track with several ungrouped clips has no single chain to point at, so
+ * it gets the grouping pointer instead of the popover).
+ */
+
+import { useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import {
+  enabledAudioFxNodes,
+  parseAudioFxChain,
+  type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import type { HfAudioNameKind } from "@hyperframes/core/audio-carve";
+import { TimelineFxPopover } from "../../components/editor/TimelineFxPopover.js";
+
+function parseFxChainOrEmpty(raw: string | undefined): HfAudioFxChain {
+  if (!raw) return { version: 1, nodes: [] };
+  try {
+    return parseAudioFxChain(raw);
+  } catch {
+    return { version: 1, nodes: [] };
+  }
+}
+
+interface TimelineFxButtonChainProps {
+  variant?: "chain";
+  trackKind?: HfAudioNameKind;
+  onOpenRack: () => void;
+  fxChainRaw: string | undefined;
+  onChainChange: (next: HfAudioFxChain) => void;
+  onChainPreview?: (next: HfAudioFxChain) => void;
+  onAuditionTransport?: (on: boolean) => void;
+}
+
+interface TimelineFxButtonGroupPointerProps {
+  variant: "group-pointer";
+  onGroupClips: () => void;
+}
+
+type TimelineFxButtonProps = TimelineFxButtonChainProps | TimelineFxButtonGroupPointerProps;
+
+export function TimelineFxButton(props: TimelineFxButtonProps) {
+  const [open, setOpen] = useState(false);
+  const buttonRef = useRef<HTMLButtonElement | null>(null);
+  const [anchorRect, setAnchorRect] = useState<DOMRect | null>(null);
+
+  const openAt = () => {
+    setAnchorRect(buttonRef.current?.getBoundingClientRect() ?? null);
+    setOpen(true);
+  };
+
+  if (props.variant === "group-pointer") {
+    return (
+      <div className="relative shrink-0">
+        <button
+          type="button"
+          tabIndex={-1}
+          ref={buttonRef}
+          aria-label="Effects — group these clips first"
+          title="Group these clips to add effects to all of them"
+          className="flex h-6 items-center justify-center rounded border-0 bg-transparent px-1 text-[10px] font-semibold text-white/35 hover:text-white/75"
+          onPointerDown={(event) => event.stopPropagation()}
+          onClick={(event) => {
+            event.stopPropagation();
+            openAt();
+          }}
+        >
+          FX
+        </button>
+        {open &&
+          anchorRect &&
+          createPortal(
+            <div
+              role="dialog"
+              aria-label="Group these clips to add effects"
+              className="z-50 w-56 rounded-md border border-white/10 bg-[#1b1b1f] p-2.5 text-[11px] text-white/75 shadow-xl"
+              style={{ position: "fixed", left: anchorRect.left, top: anchorRect.bottom + 4 }}
+              onPointerDown={(event) => event.stopPropagation()}
+            >
+              <p>Group these clips to add effects to all of them.</p>
+              <button
+                type="button"
+                className="mt-2 w-full rounded border border-white/20 py-1 text-[10px] font-semibold text-white hover:bg-white/10"
+                onClick={() => {
+                  setOpen(false);
+                  props.onGroupClips();
+                }}
+              >
+                Group
+              </button>
+            </div>,
+            document.body,
+          )}
+      </div>
+    );
+  }
+
+  const chain = parseFxChainOrEmpty(props.fxChainRaw);
+  const nodeCount = enabledAudioFxNodes(chain).length;
+
+  return (
+    <div className="relative shrink-0">
+      <button
+        type="button"
+        tabIndex={-1}
+        ref={buttonRef}
+        aria-label={nodeCount > 0 ? `Effects — ${nodeCount} applied` : "Effects"}
+        title="Effects"
+        className={`flex h-6 items-center justify-center gap-0.5 rounded border-0 bg-transparent px-1 text-[10px] font-semibold transition-colors ${
+          open || nodeCount > 0 ? "text-[#3CE6AC]" : "text-white/35 hover:text-white/75"
+        }`}
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={(event) => {
+          event.stopPropagation();
+          openAt();
+        }}
+      >
+        FX{nodeCount > 0 ? ` ${nodeCount}` : ""}
+      </button>
+      {open &&
+        anchorRect &&
+        createPortal(
+          <TimelineFxPopover
+            anchorRect={anchorRect}
+            chain={chain}
+            trackKind={props.trackKind}
+            onClose={() => setOpen(false)}
+            onChainChange={props.onChainChange}
+            onChainPreview={props.onChainPreview}
+            onAuditionTransport={props.onAuditionTransport}
+            onOpenRack={props.onOpenRack}
+          />,
+          document.body,
+        )}
+    </div>
+  );
+}

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

@@ -0,0 +1,146 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { TimelineGroupBusStrip } from "./TimelineGroupBusStrip";
+import { defaultTimelineTheme } from "./timelineTheme";
+import { groupLevels } from "../store/groupLevels";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  groupLevels.notify(new Map());
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  vi.useRealTimers();
+});
+
+function renderStrip(overrides: Partial<React.ComponentProps<typeof TimelineGroupBusStrip>> = {}) {
+  const onVolumeChange = vi.fn();
+  const onVolumeCommit = vi.fn();
+  act(() => {
+    root.render(
+      <TimelineGroupBusStrip
+        groupId="vo"
+        volume={1}
+        memberLabels={["vo-1", "vo-2"]}
+        onVolumeChange={onVolumeChange}
+        onVolumeCommit={onVolumeCommit}
+        theme={defaultTimelineTheme}
+        {...overrides}
+      />,
+    );
+  });
+  return { onVolumeChange, onVolumeCommit };
+}
+
+function slider(): HTMLInputElement {
+  return container.querySelector('input[type="range"]') as HTMLInputElement;
+}
+
+const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+  window.HTMLInputElement.prototype,
+  "value",
+)?.set;
+
+/** React tracks the DOM's own value setter to detect real changes — a plain
+ *  `input.value = ...` assignment is invisible to it, so onChange never
+ *  fires. Go through the native setter, same as this codebase's other
+ *  range/text input tests (e.g. propertyPanelFlatStyleSections.test.tsx). */
+function setSliderValue(input: HTMLInputElement, value: string) {
+  nativeInputValueSetter?.call(input, value);
+  input.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+describe("TimelineGroupBusStrip", () => {
+  it('renders "Holds …" from the member labels, comma-joined', () => {
+    renderStrip({ memberLabels: ["vo-1", "vo-2"] });
+    expect(container.textContent).toContain("Holds vo-1, vo-2");
+  });
+
+  it("falls back to a neutral line when a group has no members yet", () => {
+    renderStrip({ memberLabels: [] });
+    expect(container.textContent).toContain("Holds nothing yet");
+  });
+
+  it("live-writes on every drag tick, but only commits once on release", () => {
+    const { onVolumeChange, onVolumeCommit } = renderStrip({ volume: 1 });
+    const input = slider();
+
+    act(() => setSliderValue(input, "1.2"));
+    act(() => setSliderValue(input, "1.5"));
+    expect(onVolumeChange).toHaveBeenCalledTimes(2);
+    expect(onVolumeChange).toHaveBeenLastCalledWith(1.5);
+    expect(onVolumeCommit).not.toHaveBeenCalled();
+
+    act(() => {
+      input.value = "1.5";
+      input.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+    });
+    expect(onVolumeCommit).toHaveBeenCalledTimes(1);
+    expect(onVolumeCommit).toHaveBeenCalledWith(1.5);
+  });
+
+  it("clamps the volume slider to the 0..2 range", () => {
+    const { onVolumeChange } = renderStrip();
+    const input = slider();
+    expect(input.min).toBe("0");
+    expect(input.max).toBe("2");
+
+    act(() => setSliderValue(input, "2"));
+    expect(onVolumeChange).toHaveBeenLastCalledWith(2);
+  });
+
+  it("the level bar tracks a live reading and shows nothing extra when it isn't clipping", () => {
+    vi.useFakeTimers();
+    renderStrip();
+    act(() => {
+      groupLevels.notify(new Map([["vo", { level: 0.4, clipped: false }]]));
+      vi.advanceTimersByTime(40); // past useGroupLevel's 33ms throttle
+    });
+    expect(container.textContent).not.toContain("Too loud");
+  });
+
+  it('shows "Too loud" while clipped and holds it for ~2s after clipping stops', () => {
+    vi.useFakeTimers();
+    renderStrip();
+
+    act(() => {
+      groupLevels.notify(new Map([["vo", { level: 0.9, clipped: true }]]));
+      vi.advanceTimersByTime(40);
+    });
+    expect(container.textContent).toContain("Too loud");
+
+    // Clipping stops — the warning must still hold for a couple seconds.
+    act(() => {
+      groupLevels.notify(new Map([["vo", { level: 0.2, clipped: false }]]));
+      vi.advanceTimersByTime(40);
+    });
+    expect(container.textContent).toContain("Too loud");
+
+    act(() => {
+      vi.advanceTimersByTime(2001);
+    });
+    expect(container.textContent).not.toContain("Too loud");
+  });
+
+  it("never renders a dB number anywhere in the strip (design constraint: no dB, no peak-hold readout)", () => {
+    vi.useFakeTimers();
+    renderStrip({ volume: 1.5 });
+    act(() => {
+      groupLevels.notify(new Map([["vo", { level: 0.9, clipped: true }]]));
+      vi.advanceTimersByTime(40);
+    });
+    expect(container.textContent ?? "").not.toMatch(/dB/i);
+  });
+});