@hyperframes/studio 0.8.11 → 0.8.12

package/src/hooks/useAudioSoloBridge.ts

@@ -1,61 +0,0 @@
-import { useEffect, useMemo } from "react";
-import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
-import { usePlayerStore } from "../player/store/playerStore";
-import { getTimelineElementDisplayLabel } from "../player/lib/timelineElementHelpers";
-
-interface IframeWindow extends Window {
-  __hf?: { setAudioSolo?: (ids: readonly string[]) => void };
-}
-
-/**
- * Pushes the studio's "Hear only this" set into the preview runtime whenever
- * it changes. A dedicated push, not a DOM write: solo is session-only and
- * must never touch an attribute (design doc §2.2 / the export-safety
- * guarantee), so it can't ride `syncTimedElementVisibility`'s attribute-diff
- * the way group mute does — see `window.__hf.setAudioSolo`.
- */
-export function useAudioSoloBridge(previewIframeRef: { current: HTMLIFrameElement | null }): void {
-  const soloed = usePlayerStore((s) => s.soloed);
-  useEffect(() => {
-    const win = previewIframeRef.current?.contentWindow as IframeWindow | null;
-    win?.__hf?.setAudioSolo?.([...soloed]);
-  }, [soloed, previewIframeRef]);
-}
-
-/** One soloed id's display label — reads the live preview DOM directly (same
- *  approach as `patchLiveGroupAttribute`), since solo ids are never anywhere
- *  but the document's own element ids. A group carries its label on
- *  `data-label`; anything else falls back to the same label rule the
- *  timeline itself uses. */
-function resolveSoloLabel(doc: Document | null | undefined, id: string): string {
-  const el = doc?.getElementById(id);
-  if (!el) return id;
-  if (el.tagName.toLowerCase() === HF_AUDIO_GROUP_TAG) {
-    return getTimelineElementDisplayLabel({ id, label: el.getAttribute("data-label") });
-  }
-  return getTimelineElementDisplayLabel({
-    id,
-    label: el.getAttribute("data-timeline-label") ?? el.getAttribute("data-label"),
-    tag: el.tagName,
-  });
-}
-
-/**
- * The transport bar's "Hear only this" banner text — `null` while nothing is
- * soloed. One name when exactly one thing is soloed, `"N tracks"` otherwise
- * (design doc §2.2's banner rule); "your export is not affected" is fixed
- * copy the caller owns, this only resolves the variable half.
- */
-export function useSoloBannerText(previewIframeRef: {
-  current: HTMLIFrameElement | null;
-}): string | null {
-  const soloed = usePlayerStore((s) => s.soloed);
-  return useMemo(() => {
-    if (soloed.size === 0) return null;
-    if (soloed.size === 1) {
-      const doc = previewIframeRef.current?.contentDocument;
-      return resolveSoloLabel(doc, [...soloed][0]);
-    }
-    return `${soloed.size} tracks`;
-  }, [soloed, previewIframeRef]);
-}

package/src/hooks/useGroupLevel.ts

@@ -1,36 +0,0 @@
-/**
- * A group's live meter reading (0..1 RMS-ish level, whether it just clipped),
- * or null when the group is idle/unknown — never zero for "not playing yet".
- *
- * Mirrors useLivePlayheadTime's shape: the runtime posts readings at its own
- * cadence (only while playing — see `postGroupLevels` in init.ts), this just
- * throttles the re-render, it does not add its own polling loop.
- */
-import { useEffect, useRef, useState } from "react";
-import { groupLevels, type GroupLevelReading } from "../player/store/groupLevels";
-
-const THROTTLE_MS = 33;
-
-export function useGroupLevel(groupId: string): GroupLevelReading | null {
-  const latestRef = useRef<GroupLevelReading | null>(groupLevels.get().get(groupId) ?? null);
-  const [, forceRender] = useState(0);
-
-  useEffect(() => {
-    let timerId: ReturnType<typeof setTimeout> | 0 = 0;
-    const unsubscribe = groupLevels.subscribe((levels) => {
-      latestRef.current = levels.get(groupId) ?? null;
-      if (!timerId) {
-        timerId = setTimeout(() => {
-          timerId = 0;
-          forceRender((v) => v + 1);
-        }, THROTTLE_MS);
-      }
-    });
-    return () => {
-      unsubscribe();
-      if (timerId) clearTimeout(timerId);
-    };
-  }, [groupId]);
-
-  return latestRef.current;
-}

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

@@ -1,146 +0,0 @@
-// @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

@@ -1,103 +0,0 @@
-/**
- * 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/TimelineSoloButton.tsx

@@ -1,32 +0,0 @@
-/**
- * "Hear only this" — the `⌗` toggle beside a track's mute control. Session
- * state only (see `audioSoloSlice`): a plain click is exclusive, ⌘/Ctrl-click
- * toggles membership without disturbing the rest of the set.
- */
-export function TimelineSoloButton({
-  isSoloed,
-  onToggle,
-}: {
-  isSoloed: boolean;
-  onToggle: (options?: { add?: boolean }) => void;
-}) {
-  return (
-    <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" : "text-white/35 hover:text-white/75"
-      }`}
-      onPointerDown={(event) => event.stopPropagation()}
-      onClick={(event) => {
-        event.stopPropagation();
-        onToggle({ add: event.metaKey || event.ctrlKey });
-      }}
-    >
-      <span aria-hidden="true">⌗</span>
-    </button>
-  );
-}

package/src/player/store/audioSoloSlice.test.ts

@@ -1,113 +0,0 @@
-// @vitest-environment happy-dom
-
-import { describe, expect, it, vi } from "vitest";
-import { usePlayerStore } from "./playerStore";
-import { isAudibleUnderSolo, isGroupHalfLitUnderSolo } from "./audioSoloSlice";
-import * as studioFileHistory from "../../utils/studioFileHistory";
-
-describe("audioSoloSlice", () => {
-  it("is exclusive by default, and clicking the only soloed element again clears it", () => {
-    usePlayerStore.getState().toggleSolo("a");
-    expect(usePlayerStore.getState().soloed).toEqual(new Set(["a"]));
-    usePlayerStore.getState().toggleSolo("b");
-    expect(usePlayerStore.getState().soloed).toEqual(new Set(["b"]));
-    usePlayerStore.getState().toggleSolo("b");
-    expect(usePlayerStore.getState().soloed).toEqual(new Set());
-  });
-
-  it("⌘/Ctrl-click adds and removes membership without disturbing the rest", () => {
-    usePlayerStore.getState().toggleSolo("a");
-    usePlayerStore.getState().toggleSolo("b", { add: true });
-    expect(usePlayerStore.getState().soloed).toEqual(new Set(["a", "b"]));
-    usePlayerStore.getState().toggleSolo("a", { add: true });
-    expect(usePlayerStore.getState().soloed).toEqual(new Set(["b"]));
-  });
-
-  it("clearSolo empties the set", () => {
-    usePlayerStore.getState().toggleSolo("a");
-    usePlayerStore.getState().clearSolo();
-    expect(usePlayerStore.getState().soloed).toEqual(new Set());
-  });
-});
-
-describe("export-safety: solo never touches an attribute or the save path", () => {
-  it("toggling, ⌘-adding, and clearing solo never calls setAttribute/removeAttribute on any element", () => {
-    usePlayerStore.getState().clearSolo();
-    const setAttributeSpy = vi.spyOn(Element.prototype, "setAttribute");
-    const removeAttributeSpy = vi.spyOn(Element.prototype, "removeAttribute");
-
-    usePlayerStore.getState().toggleSolo("a");
-    usePlayerStore.getState().toggleSolo("b", { add: true });
-    usePlayerStore.getState().toggleSolo("a", { add: true });
-    usePlayerStore.getState().clearSolo();
-
-    expect(setAttributeSpy).not.toHaveBeenCalled();
-    expect(removeAttributeSpy).not.toHaveBeenCalled();
-    setAttributeSpy.mockRestore();
-    removeAttributeSpy.mockRestore();
-  });
-
-  it("toggling, ⌘-adding, and clearing solo never invokes the project save path (setElementsHidden's own write function)", () => {
-    usePlayerStore.getState().clearSolo();
-    const saveSpy = vi.spyOn(studioFileHistory, "saveProjectFilesWithHistory");
-
-    usePlayerStore.getState().toggleSolo("a");
-    usePlayerStore.getState().toggleSolo("b", { add: true });
-    usePlayerStore.getState().clearSolo();
-
-    expect(saveSpy).not.toHaveBeenCalled();
-    saveSpy.mockRestore();
-  });
-});
-
-describe("isAudibleUnderSolo — the three-bullet rule", () => {
-  it("everything is audible when no solo is active", () => {
-    expect(isAudibleUnderSolo(new Set(), "clip-a")).toBe(true);
-    expect(isAudibleUnderSolo(new Set(), "clip-a", "group-1")).toBe(true);
-  });
-
-  it("a soloed element is audible", () => {
-    expect(isAudibleUnderSolo(new Set(["clip-a"]), "clip-a")).toBe(true);
-  });
-
-  it("a sibling of a soloed element is silent", () => {
-    expect(isAudibleUnderSolo(new Set(["clip-a"]), "clip-b")).toBe(false);
-  });
-
-  it("a member of a soloed group is audible (group solo = members solo)", () => {
-    expect(isAudibleUnderSolo(new Set(["group-1"]), "clip-a", "group-1")).toBe(true);
-  });
-
-  it("a member of an UNsoloed group, while a sibling group is soloed, is silent", () => {
-    expect(isAudibleUnderSolo(new Set(["group-2"]), "clip-a", "group-1")).toBe(false);
-  });
-
-  it("soloing one member of a group does not un-attenuate its siblings in the same group", () => {
-    // clip-a is soloed directly; clip-b shares its group but is not itself
-    // soloed and the group itself is not soloed — clip-b stays silent.
-    expect(isAudibleUnderSolo(new Set(["clip-a"]), "clip-b", "group-1")).toBe(false);
-  });
-
-  it("the group itself, monitored as a bus, is audible only when it or a member is soloed", () => {
-    expect(isAudibleUnderSolo(new Set(["clip-a"]), "group-1", null)).toBe(false);
-    expect(isAudibleUnderSolo(new Set(["group-1"]), "group-1", null)).toBe(true);
-  });
-});
-
-describe("isGroupHalfLitUnderSolo", () => {
-  it("is false when no solo is active", () => {
-    expect(isGroupHalfLitUnderSolo(new Set(), "group-1", ["a", "b"])).toBe(false);
-  });
-
-  it("is false when the group itself is soloed (fully lit, not half)", () => {
-    expect(isGroupHalfLitUnderSolo(new Set(["group-1"]), "group-1", ["a", "b"])).toBe(false);
-  });
-
-  it("is true when a member is soloed but the group is not", () => {
-    expect(isGroupHalfLitUnderSolo(new Set(["a"]), "group-1", ["a", "b"])).toBe(true);
-  });
-
-  it("is false when an unrelated element is soloed", () => {
-    expect(isGroupHalfLitUnderSolo(new Set(["other"]), "group-1", ["a", "b"])).toBe(false);
-  });
-});

package/src/player/store/audioSoloSlice.ts

@@ -1,43 +0,0 @@
-/**
- * "Hear only this" — session-only monitoring override, never persisted.
- *
- * Holds clip ids and group ids (never track numbers, per the design doc: solo
- * is a per-element/per-group concept, not a row-position one). Exclusive by
- * default (a plain toggle replaces the set); ⌘/Ctrl-click adds/removes one
- * member without disturbing the rest. Never written to any attribute or
- * document — the export-safety guarantee this slice exists to hold.
- */
-import type { StoreApi } from "zustand";
-import { isAudibleUnderSolo, isGroupHalfLitUnderSolo } from "@hyperframes/core/audio-groups";
-
-export { isAudibleUnderSolo, isGroupHalfLitUnderSolo };
-
-export interface AudioSoloSlice {
-  soloed: ReadonlySet<string>;
-  toggleSolo: (id: string, options?: { add?: boolean }) => void;
-  clearSolo: () => void;
-}
-
-export function createAudioSoloSlice(
-  set: StoreApi<AudioSoloSlice>["setState"],
-  get: StoreApi<AudioSoloSlice>["getState"],
-): AudioSoloSlice {
-  return {
-    soloed: new Set(),
-    toggleSolo: (id, options) => {
-      const current = get().soloed;
-      if (options?.add) {
-        const next = new Set(current);
-        if (next.has(id)) next.delete(id);
-        else next.add(id);
-        set({ soloed: next });
-        return;
-      }
-      // Exclusive click: soloing the only-soloed element again clears it;
-      // otherwise it replaces the set.
-      const isOnlyMember = current.size === 1 && current.has(id);
-      set({ soloed: isOnlyMember ? new Set() : new Set([id]) });
-    },
-    clearSolo: () => set({ soloed: new Set() }),
-  };
-}

package/src/player/store/groupLevels.ts

@@ -1,33 +0,0 @@
-// ponytail: mirrors liveTime.ts's plain pub-sub — same throttle-at-the-edge shape.
-/** A group's live meter reading, or absent when idle/unknown (never zero). */
-export type GroupLevelReading = { level: number; clipped: boolean };
-
-type Listener = (levels: ReadonlyMap<string, GroupLevelReading>) => void;
-const listeners = new Set<Listener>();
-let latest: ReadonlyMap<string, GroupLevelReading> = new Map();
-
-export const groupLevels = {
-  notify: (levels: ReadonlyMap<string, GroupLevelReading>) => {
-    latest = levels;
-    listeners.forEach((listener) => listener(levels));
-  },
-  subscribe: (listener: Listener) => {
-    listeners.add(listener);
-    return () => listeners.delete(listener);
-  },
-  get: () => latest,
-};
-
-/** Turns the runtime's `group-levels` postMessage payload into the map `groupLevels.notify` wants. */
-export function parseGroupLevelsMessage(
-  data: unknown,
-): ReadonlyMap<string, GroupLevelReading> | null {
-  const levels = (data as { levels?: unknown } | null)?.levels;
-  if (!Array.isArray(levels)) return null;
-  return new Map(
-    (levels as Array<{ groupId: string; level: number; clipped: boolean }>).map((entry) => [
-      entry.groupId,
-      { level: entry.level, clipped: entry.clipped },
-    ]),
-  );
-}