@hyperframes/studio 0.8.6 → 0.8.8

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);
+  });
+});

package/src/player/components/TimelineGroupBusStrip.tsx

@@ -0,0 +1,103 @@
+/**
+ * B7: the group's own volume slider + a living level bar + "Holds …" — the
+ * bus, not the mechanism. No dB numbers, no peak-hold readout, no routing
+ * row (groups doc §5, casual-user section) — a slider, a bar that moves with
+ * the sound, and the words "Too loud" when it clips.
+ */
+import { useEffect, useRef, useState } from "react";
+import { useGroupLevel } from "../../hooks/useGroupLevel";
+import { STRIP_H, TRACK_H } from "./timelineLayout";
+import type { TimelineTheme } from "./timelineTheme";
+
+/** How long "Too loud" stays lit after the last clipped block. */
+const CLIP_HOLD_MS = 2000;
+
+function clampVolume(value: number): number {
+  return Math.min(2, Math.max(0, value));
+}
+
+interface TimelineGroupBusStripProps {
+  groupId: string;
+  volume: number;
+  memberLabels: readonly string[];
+  onVolumeChange: (value: number) => void;
+  onVolumeCommit: (value: number) => void;
+  theme: TimelineTheme;
+}
+
+export function TimelineGroupBusStrip({
+  groupId,
+  volume,
+  memberLabels,
+  onVolumeChange,
+  onVolumeCommit,
+  theme,
+}: TimelineGroupBusStripProps) {
+  const [dragValue, setDragValue] = useState<number | null>(null);
+  const reading = useGroupLevel(groupId);
+  const [clipped, setClipped] = useState(false);
+  const clipTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (!reading?.clipped) return;
+    setClipped(true);
+    if (clipTimerRef.current) clearTimeout(clipTimerRef.current);
+    clipTimerRef.current = setTimeout(() => setClipped(false), CLIP_HOLD_MS);
+  }, [reading?.clipped]);
+
+  useEffect(
+    () => () => {
+      if (clipTimerRef.current) clearTimeout(clipTimerRef.current);
+    },
+    [],
+  );
+
+  const shownVolume = dragValue ?? volume;
+  const level = Math.min(1, reading?.level ?? 0);
+  const holdsText =
+    memberLabels.length > 0 ? `Holds ${memberLabels.join(", ")}` : "Holds nothing yet";
+
+  return (
+    <div
+      className="absolute left-0 right-0 flex items-center gap-2 px-2 text-[10px] text-white/70"
+      style={{ top: TRACK_H, height: STRIP_H }}
+    >
+      <input
+        type="range"
+        aria-label="Group volume"
+        min={0}
+        max={2}
+        step={0.01}
+        value={shownVolume}
+        className="h-1 w-20 shrink-0 accent-[#3CE6AC]"
+        onChange={(event) => {
+          const next = clampVolume(Number(event.currentTarget.value));
+          setDragValue(next);
+          onVolumeChange(next);
+        }}
+        onPointerUp={(event) => {
+          const next = clampVolume(Number(event.currentTarget.value));
+          setDragValue(null);
+          onVolumeCommit(next);
+        }}
+      />
+      <div
+        className="relative h-1.5 w-16 shrink-0 overflow-hidden rounded-full"
+        style={{ background: theme.gutterBorder }}
+        aria-hidden="true"
+      >
+        <div
+          className="absolute inset-y-0 left-0 rounded-full"
+          style={{
+            width: `${level * 100}%`,
+            background: clipped ? "#ff5c5c" : "#3CE6AC",
+          }}
+        />
+      </div>
+      {clipped && <span className="shrink-0 font-medium text-[#ff5c5c]">Too loud</span>}
+      <span className="min-w-0 flex-1 truncate" title={holdsText}>
+        {holdsText}
+      </span>
+    </div>
+  );
+}

package/src/player/components/TimelineGroupHeader.tsx

@@ -0,0 +1,176 @@
+import { SpeakerHigh, SpeakerSlash } from "@phosphor-icons/react";
+import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
+import { TRACK_H } from "./timelineLayout";
+import type { TimelineTheme } from "./timelineTheme";
+import { TimelineFxButton } from "./TimelineFxButton";
+
+interface TimelineGroupHeaderProps {
+  label: string;
+  memberCount: number;
+  /** Caret: shows/hides the member rows beneath this group (structural). */
+  isExpanded: boolean;
+  onToggleExpanded: () => void;
+  /** `∿`: shows/hides the group's own automation-lane rows. */
+  laneCount: number;
+  isLaneOpen: boolean;
+  onToggleLanes: () => void;
+  /** The group element's own `data-hidden` — mutes every member at once. */
+  hidden: boolean;
+  onToggleHidden: () => void;
+  /** This group id is itself in the soloed set (fully lit). */
+  isSoloed: boolean;
+  /** Not soloed itself, but at least one member is (half-lit). */
+  isHalfLitSolo: boolean;
+  /** `add: true` (⌘/Ctrl-click) toggles membership; a plain click is exclusive. */
+  onToggleSolo: (options?: { add?: boolean }) => void;
+  /** C1: the group's serialized `data-fx-chain`, when set. */
+  fxChain?: string;
+  onFxChainChange: (next: HfAudioFxChain) => void;
+  onFxChainPreview?: (next: HfAudioFxChain) => void;
+  onFxAuditionTransport?: (on: boolean) => void;
+  onOpenFxRack: () => void;
+  columnWidth: number;
+  theme: TimelineTheme;
+}
+
+/**
+ * A group's own row header: caret (member disclosure) + `▤` + label + count +
+ * mute + solo + FX + `∿ n` (lane disclosure).
+ */
+export function TimelineGroupHeader({
+  label,
+  memberCount,
+  isExpanded,
+  onToggleExpanded,
+  laneCount,
+  isLaneOpen,
+  onToggleLanes,
+  hidden,
+  onToggleHidden,
+  isSoloed,
+  isHalfLitSolo,
+  onToggleSolo,
+  fxChain,
+  onFxChainChange,
+  onFxChainPreview,
+  onFxAuditionTransport,
+  onOpenFxRack,
+  columnWidth,
+  theme,
+}: TimelineGroupHeaderProps) {
+  return (
+    <div
+      role="rowheader"
+      aria-colindex={1}
+      className="sticky left-0 z-[12] flex shrink-0 items-center gap-1.5 overflow-hidden px-1.5 text-[11px]"
+      style={{
+        width: columnWidth,
+        height: TRACK_H,
+        color: "#ffffff",
+        background: theme.gutterBackground,
+        borderRight: `1px solid ${theme.gutterBorder}`,
+      }}
+    >
+      <button
+        type="button"
+        tabIndex={-1}
+        aria-expanded={isExpanded}
+        aria-label={`${isExpanded ? "Hide" : "Show"} ${label} tracks`}
+        title={`${isExpanded ? "Hide" : "Show"} tracks`}
+        className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[11px] focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
+          isExpanded ? "text-white" : "text-white/55 hover:text-white"
+        }`}
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={(event) => {
+          event.stopPropagation();
+          onToggleExpanded();
+        }}
+      >
+        <span aria-hidden="true" style={{ transform: isExpanded ? "rotate(90deg)" : undefined }}>
+          ▸
+        </span>
+      </button>
+      <span aria-hidden="true" className="shrink-0 text-[12px] leading-none text-white/50">
+        ▤
+      </span>
+      <span className="min-w-0 flex-1 truncate font-medium" title={label}>
+        {label}
+      </span>
+      <span
+        className="shrink-0 rounded-full bg-white/10 px-1 text-[9px] leading-[14px] tabular-nums text-white/55"
+        aria-hidden="true"
+        title={`${memberCount} tracks`}
+      >
+        {memberCount}
+      </span>
+      <button
+        type="button"
+        tabIndex={-1}
+        aria-label={hidden ? "Unmute group" : `Mute group ${label}`}
+        title={hidden ? "Unmute group" : `Mute group ${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 focus-visible:outline-1 focus-visible:outline-offset-[-1px] focus-visible:outline-[#3CE6AC] ${
+          hidden ? "text-[#3CE6AC] hover:text-white" : "text-white/55 hover:text-white"
+        }`}
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={(event) => {
+          event.stopPropagation();
+          onToggleHidden();
+        }}
+      >
+        {hidden ? (
+          <SpeakerSlash size={14} weight="bold" aria-hidden="true" />
+        ) : (
+          <SpeakerHigh size={14} weight="bold" aria-hidden="true" />
+        )}
+      </button>
+      <button
+        type="button"
+        tabIndex={-1}
+        aria-pressed={isSoloed}
+        aria-label="Hear only this"
+        title="Hear only this"
+        className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[13px] font-semibold transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-[-1px] focus-visible:outline-[#3CE6AC] ${
+          isSoloed
+            ? "text-[#F5C542] hover:text-white"
+            : isHalfLitSolo
+              ? "text-[#F5C542]/50 hover:text-white"
+              : "text-white/35 hover:text-white/75"
+        }`}
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={(event) => {
+          event.stopPropagation();
+          onToggleSolo({ add: event.metaKey || event.ctrlKey });
+        }}
+      >
+        <span aria-hidden="true">⌗</span>
+      </button>
+      <TimelineFxButton
+        fxChainRaw={fxChain}
+        onChainChange={onFxChainChange}
+        onChainPreview={onFxChainPreview}
+        onAuditionTransport={onFxAuditionTransport}
+        onOpenRack={onOpenFxRack}
+      />
+      <button
+        type="button"
+        tabIndex={-1}
+        aria-expanded={isLaneOpen}
+        aria-label={`${isLaneOpen ? "Hide" : "Show"} ${label} lanes`}
+        title={`${isLaneOpen ? "Hide" : "Show"} lanes`}
+        className={`flex h-6 items-center justify-center gap-0.5 rounded border-0 bg-transparent px-1 text-[11px] leading-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
+          isLaneOpen ? "text-[#3CE6AC]" : "text-white/55 hover:text-white"
+        }`}
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={(event) => {
+          event.stopPropagation();
+          onToggleLanes();
+        }}
+      >
+        <span aria-hidden="true">∿</span>
+        {laneCount > 0 && (
+          <span className="text-[9px] tabular-nums text-white/55">{laneCount}</span>
+        )}
+      </button>
+    </div>
+  );
+}