@hyperframes/studio 0.8.10 → 0.8.12

package/src/player/components/TimelineAutomationLaneSlot.tsx

@@ -12,7 +12,7 @@ import { resolveAutomationRange, type HfAutomationLane } from "@hyperframes/core
 import { TimelineAutomationLane } from "./TimelineAutomationLane";
 import { AUTOMATION_LANE_H } from "./automationLaneHeight";
 import { getTimelineLaneTop } from "./timelineLayout";
-import { groupAutomationLanes } from "./automationLaneData";
+import { groupAutomationLanes, isCarveLane } from "./automationLaneData";
 import { isAudioTimelineElement } from "../../utils/timelineInspector";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
 import type { TimelineElement } from "../store/playerStore";
@@ -100,7 +100,21 @@ function ClipAutomationLanes({
             onCommit={bound.onCommit}
             onSelect={bound.onSelect}
             snapTimes={snapTimes}
-            readOnly={bound.readOnly}
+            // The carve owns its own envelopes and rewrites them on every
+            // re-run, so a drag would be silently discarded — shown, but not
+            // editable. Per LANE, not per binding: a carved bed can carry the
+            // author's own volume curve beside the carve's bands.
+            readOnly={bound.readOnly || isCarveLane(lane.target, bound.chain)}
+            // Two distinct reasons, so two notes. The carve one names the way
+            // out — change strength, or switch the carve off and own the chain
+            // — because "not editable" without that reads as broken.
+            readOnlyNote={
+              isCarveLane(lane.target, bound.chain)
+                ? "Owned by the voiceover carve — re-derived on every analysis. Change strength in the FX rack, or turn the carve off to edit these by hand."
+                : bound.readOnly
+                  ? "Read-only here."
+                  : undefined
+            }
             rangeSelection={
               bound.selection?.target === lane.target
                 ? {
@@ -128,6 +142,10 @@ export interface TimelineAutomationLaneSlotProps {
   pps: number;
   /** Keyframe lanes already stacked above, which automation sits under. */
   laneCount: number;
+  /** Exact y for the first lane, overriding `laneCount`. A group's lanes sit
+   *  directly under its header row rather than under a stack of keyframe
+   *  lanes, so it cannot be said in `laneCount`. */
+  topOffset?: number;
   accentColor: string;
   /** Composition-time playhead; the slot converts it to clip-local. */
   currentTime: number;
@@ -151,6 +169,7 @@ export function TimelineAutomationLaneSlot({
   lanes,
   pps,
   laneCount,
+  topOffset,
   accentColor,
   currentTime,
   beatTimes,
@@ -165,7 +184,7 @@ export function TimelineAutomationLaneSlot({
       else rowsByClip.set(key, [{ lane: entry.lane, rowIndex }]);
     }
   });
-  const top = getTimelineLaneTop(laneCount);
+  const top = topOffset ?? getTimelineLaneTop(laneCount);
   return (
     <>
       {clips.map((element) => (

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

@@ -1,5 +1,5 @@
 // @vitest-environment happy-dom
-import { act } from "react";
+import React, { act } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createRoot } from "react-dom/client";
 import { serializeAudioFxChain } from "@hyperframes/core/audio-fx";
@@ -68,14 +68,191 @@ describe("TimelineFxButton", () => {
     expect(document.querySelector('[role="dialog"]')).toBeTruthy();
   });
 
-  it("group-pointer variant offers Group instead of a popover", () => {
+  // A muted target auditions anyway — the mute is lifted on the running graph
+  // for the hover and put back on the way out. The read has to happen on the
+  // way IN: the live unmute flows back into this component's props, so a
+  // restore that re-read `isMuted` would find it false and never re-mute.
+  it("borrows a muted target's mute for the audition and returns it", () => {
+    const onSetMutedLive = vi.fn();
+    const host = mount(
+      <TimelineFxButton
+        variant="chain"
+        fxChainRaw={undefined}
+        isMuted
+        onSetMutedLive={onSetMutedLive}
+        onChainChange={vi.fn()}
+        onChainPreview={vi.fn()}
+        onOpenRack={vi.fn()}
+      />,
+    );
+    act(() => byTextButton(host, "FX")?.click());
+    const preset = document.querySelector<HTMLButtonElement>(".hf-fx-preset-item");
+    act(() => preset?.dispatchEvent(new MouseEvent("mouseover", { bubbles: true })));
+    expect(onSetMutedLive).toHaveBeenLastCalledWith(false);
+    const shelf = document.querySelector(".hf-fx-preset-menu");
+    act(() => shelf?.dispatchEvent(new MouseEvent("mouseout", { bubbles: true })));
+    expect(onSetMutedLive).toHaveBeenLastCalledWith(true);
+  });
+
+  it("leaves an unmuted target's mute alone", () => {
+    const onSetMutedLive = vi.fn();
+    const host = mount(
+      <TimelineFxButton
+        variant="chain"
+        fxChainRaw={undefined}
+        onSetMutedLive={onSetMutedLive}
+        onChainChange={vi.fn()}
+        onChainPreview={vi.fn()}
+        onOpenRack={vi.fn()}
+      />,
+    );
+    act(() => byTextButton(host, "FX")?.click());
+    const preset = document.querySelector<HTMLButtonElement>(".hf-fx-preset-item");
+    act(() => preset?.dispatchEvent(new MouseEvent("mouseover", { bubbles: true })));
+    expect(onSetMutedLive).not.toHaveBeenCalled();
+  });
+
+  // Hovering writes the preset through the preview channel, and the chain prop
+  // is read back from that same live attribute. Applying while a DIFFERENT
+  // preset is being auditioned used to save both — heard as the effect running
+  // twice — so the apply has to land on the stored chain.
+  it("applies onto the stored chain, not the one being auditioned", () => {
+    const onChainChange = vi.fn();
+    // The write-back the real timeline does: a preview patches the live
+    // attribute, and the row re-reads it into `fxChainRaw`. Without this the
+    // prop never moves and the bug cannot show.
+    function Harness() {
+      const [raw, setRaw] = React.useState<string | undefined>(undefined);
+      return (
+        <TimelineFxButton
+          variant="chain"
+          fxChainRaw={raw}
+          onChainChange={onChainChange}
+          onChainPreview={(next) => setRaw(serializeAudioFxChain(next))}
+          onOpenRack={vi.fn()}
+        />
+      );
+    }
+    const host = mount(<Harness />);
+    act(() => byTextButton(host, "FX")?.click());
+    const items = Array.from(document.querySelectorAll<HTMLButtonElement>(".hf-fx-preset-item"));
+    const [hovered, clicked] = [items[0], items[1]];
+    act(() => hovered?.dispatchEvent(new MouseEvent("mouseover", { bubbles: true })));
+    act(() => clicked?.click());
+    const saved = onChainChange.mock.calls.at(-1)?.[0];
+    const presets = new Set(saved?.nodes.map((n: { fromPreset?: string }) => n.fromPreset));
+    expect(presets.size).toBe(1);
+  });
+
+  // The design doc calls the sentence this dialog carries "the highest-leverage
+  // copy in this plan": it is the concept of a submix bus delivered without the
+  // word, to an author who has never met one. The old pointer auto-named the
+  // group on one click and never mentioned the shared volume.
+  it("group-pointer variant names the group and explains what one is", () => {
     const onGroupClips = vi.fn();
-    const host = mount(<TimelineFxButton variant="group-pointer" onGroupClips={onGroupClips} />);
+    const host = mount(
+      <TimelineFxButton variant="group-pointer" clipCount={2} 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();
+    const dialog = document.querySelector('[role="dialog"]');
+    expect(dialog?.textContent).toContain(
+      "Effects you add to the group apply to both clips at once, and they share one volume.",
+    );
+    const group = Array.from(document.body.querySelectorAll("button")).find(
+      (b) => b.textContent === "Group",
+    );
+    act(() => group?.click());
+    expect(onGroupClips).toHaveBeenCalledWith("Voiceover");
+  });
+
+  // Three or more must not read "both".
+  it("counts the clips in the explanation", () => {
+    mount(<TimelineFxButton variant="group-pointer" clipCount={3} onGroupClips={vi.fn()} />);
+    act(() => byTextButton(document.body as HTMLElement, "FX")?.click());
+    expect(document.querySelector('[role="dialog"]')?.textContent).toContain("all 3 clips at once");
+  });
+
+  // §1.4 keeps groups audio-only in v1, and §5 is explicit that a deliberate
+  // limit must be stated: "silent ones just send authors hunting for something
+  // that was never built."
+  it("states the video limit instead of offering a name field", () => {
+    const onGroupClips = vi.fn();
+    const host = mount(
+      <TimelineFxButton
+        variant="group-pointer"
+        clipCount={2}
+        refusal="Video audio can't be grouped yet — only audio clips can join a group."
+        onGroupClips={onGroupClips}
+      />,
+    );
+    act(() => byTextButton(host, "FX")?.click());
+    const dialog = document.querySelector('[role="dialog"]');
+    expect(dialog?.textContent).toContain("Video audio can't be grouped yet");
+    expect(document.querySelector('input[aria-label="Group name"]')).toBeNull();
+    expect(
+      Array.from(document.body.querySelectorAll("button")).some((b) => b.textContent === "Group"),
+    ).toBe(false);
+  });
+
+  // #3421: the dialog positioned itself at `anchorRect.bottom + 4` with no flip
+  // and no clamp, and this button lives in a track header at the bottom of the
+  // studio window — so it opened past the viewport edge and was reported as
+  // "the grouping button did nothing". Numbers derive from GROUP_DIALOG_SIZE
+  // (256x160) against happy-dom's 1024x768 window and a 12px margin.
+  it("flips the group dialog above the anchor when there is no room below", () => {
+    const host = mount(
+      <TimelineFxButton variant="group-pointer" clipCount={2} onGroupClips={vi.fn()} />,
+    );
+    const fx = byTextButton(host, "FX");
+    fx!.getBoundingClientRect = () =>
+      ({ left: 300, top: 760, right: 320, bottom: 776, width: 20, height: 16 }) as DOMRect;
+    act(() => fx?.click());
+    const dialog = document.querySelector('[role="dialog"]') as HTMLElement;
+    expect(dialog).toBeTruthy();
+    const top = Number.parseFloat(dialog.style.top);
+    // Fully inside the viewport on both edges, which the unclamped form was not.
+    expect(top).toBeGreaterThanOrEqual(12);
+    expect(top + 160).toBeLessThanOrEqual(768 - 12);
+  });
+
+  it("keeps the group dialog inside the right edge of the window", () => {
+    const host = mount(
+      <TimelineFxButton variant="group-pointer" clipCount={2} onGroupClips={vi.fn()} />,
+    );
+    const fx = byTextButton(host, "FX");
+    fx!.getBoundingClientRect = () =>
+      ({ left: 1010, top: 100, right: 1024, bottom: 116, width: 14, height: 16 }) as DOMRect;
+    act(() => fx?.click());
+    const dialog = document.querySelector('[role="dialog"]') as HTMLElement;
+    const left = Number.parseFloat(dialog.style.left);
+    expect(left).toBeGreaterThanOrEqual(12);
+    expect(left + 256).toBeLessThanOrEqual(1024 - 12);
+  });
+
+  it("carries the typed name into the group it creates", () => {
+    const onGroupClips = vi.fn();
+    const host = mount(
+      <TimelineFxButton variant="group-pointer" clipCount={2} onGroupClips={onGroupClips} />,
+    );
+    act(() => byTextButton(host, "FX")?.click());
+    const input = document.querySelector<HTMLInputElement>('input[aria-label="Group name"]');
+    expect(input).not.toBeNull();
+    // React tracks the input's value on the node, so assigning `.value`
+    // directly is swallowed — the native setter is what makes onChange fire.
+    const setValue = Object.getOwnPropertyDescriptor(
+      window.HTMLInputElement.prototype,
+      "value",
+    )?.set;
+    act(() => {
+      if (input && setValue) {
+        setValue.call(input, "SFX");
+        input.dispatchEvent(new Event("input", { bubbles: true }));
+      }
+    });
+    const group = Array.from(document.body.querySelectorAll("button")).find(
+      (b) => b.textContent === "Group",
+    );
     act(() => group?.click());
-    expect(onGroupClips).toHaveBeenCalledTimes(1);
+    expect(onGroupClips).toHaveBeenCalledWith("SFX");
   });
 });

package/src/player/components/TimelineFxButton.tsx

@@ -9,7 +9,7 @@
  * it gets the grouping pointer instead of the popover).
  */
 
-import { useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import {
   enabledAudioFxNodes,
@@ -18,6 +18,129 @@ import {
 } from "@hyperframes/core/audio-fx";
 import type { HfAudioNameKind } from "@hyperframes/core/audio-carve";
 import { TimelineFxPopover } from "../../components/editor/TimelineFxPopover.js";
+import { resolveFloatingPanelPosition } from "../../components/editor/floatingPanel.js";
+import {
+  useAuditionTransport,
+  type AuditionSpan,
+} from "../../components/editor/useAuditionTransport.js";
+
+/**
+ * Naming a group is the moment the whole feature is explained.
+ *
+ * The design doc calls the sentence below "the highest-leverage copy in this
+ * plan and it should be written before the routing is" — it is the concept of a
+ * submix bus delivered without the word, to an author who has never met one.
+ * The old pointer skipped both the name and the sentence: it made an
+ * auto-named group on one click and said only "Group these clips to add effects
+ * to all of them", which leaves out the shared volume entirely.
+ */
+// Estimated, like FORMAT_PANEL_SIZE in RenderQueue: `w-64` is exact, and only
+// the flip decision uses the height — the clamp keeps the dialog on screen
+// either way.
+const GROUP_DIALOG_SIZE = { width: 256, height: 160 };
+
+/** Where the grouping dialog goes: flipped above the anchor when there is no
+ *  room below, and clamped so neither edge leaves the viewport. This button
+ *  lives in a track header at the BOTTOM of the studio window, so an unclamped
+ *  `anchorRect.bottom + 4` opened it past the viewport edge and read as "the
+ *  grouping button did nothing". */
+function groupDialogPosition(anchorRect: DOMRect): { left: number; top: number } {
+  const { left, top } = resolveFloatingPanelPosition(
+    anchorRect,
+    { width: window.innerWidth, height: window.innerHeight },
+    GROUP_DIALOG_SIZE,
+    { offset: 4 },
+  );
+  return { left, top };
+}
+
+function GroupNameDialog({
+  anchorRect,
+  clipCount,
+  defaultLabel,
+  refusal,
+  onCancel,
+  onConfirm,
+}: {
+  anchorRect: DOMRect;
+  clipCount: number;
+  defaultLabel?: string;
+  refusal?: string;
+  onCancel: () => void;
+  onConfirm: (label: string) => void;
+}) {
+  const [label, setLabel] = useState(defaultLabel ?? "Voiceover");
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  // Focused on open so the name can be typed over without a second click —
+  // the field is the only thing here that wants input.
+  useEffect(() => inputRef.current?.select(), []);
+  if (refusal) {
+    return (
+      <div
+        role="dialog"
+        aria-label="This track cannot be grouped"
+        className="z-[200] w-64 rounded-md border border-white/10 bg-[#1b1b1f] p-3 text-[11px] leading-snug text-white/75 shadow-xl"
+        style={{ position: "fixed", ...groupDialogPosition(anchorRect) }}
+        onPointerDown={(event) => event.stopPropagation()}
+        onKeyDown={(event) => {
+          if (event.key !== "Escape") return;
+          event.stopPropagation();
+          onCancel();
+        }}
+      >
+        <p>{refusal}</p>
+      </div>
+    );
+  }
+  const confirm = () => onConfirm(label.trim() || defaultLabel || "Voiceover");
+  return (
+    <div
+      role="dialog"
+      aria-label="Name this group"
+      className="z-[200] w-64 rounded-md border border-white/10 bg-[#1b1b1f] p-3 text-[11px] text-white/75 shadow-xl"
+      style={{ position: "fixed", ...groupDialogPosition(anchorRect) }}
+      onPointerDown={(event) => event.stopPropagation()}
+      onKeyDown={(event) => {
+        if (event.key === "Escape") {
+          event.stopPropagation();
+          onCancel();
+        }
+        if (event.key === "Enter") confirm();
+      }}
+    >
+      <p className="mb-1.5 font-medium text-white">Name this group</p>
+      <input
+        ref={inputRef}
+        type="text"
+        aria-label="Group name"
+        value={label}
+        onChange={(event) => setLabel(event.currentTarget.value)}
+        className="w-full rounded border border-white/20 bg-black/30 px-1.5 py-1 text-[11px] text-white outline-none focus:border-[#3CE6AC]"
+      />
+      {/* The sentence. No jargon, and it names both things a bus does. */}
+      <p className="mt-2 leading-snug">
+        Effects you add to the group apply to {clipCount === 2 ? "both" : `all ${clipCount}`} clips
+        at once, and they share one volume.
+      </p>
+      <div className="mt-2.5 flex justify-end gap-1.5">
+        <button
+          type="button"
+          className="rounded border border-white/20 px-2 py-1 text-[10px] text-white/75 hover:bg-white/10"
+          onClick={onCancel}
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          className="rounded border border-[#3CE6AC] bg-[#3CE6AC]/15 px-2 py-1 text-[10px] font-semibold text-[#3CE6AC] hover:bg-[#3CE6AC]/25"
+          onClick={confirm}
+        >
+          Group
+        </button>
+      </div>
+    </div>
+  );
+}
 
 function parseFxChainOrEmpty(raw: string | undefined): HfAudioFxChain {
   if (!raw) return { version: 1, nodes: [] };
@@ -35,12 +158,31 @@ interface TimelineFxButtonChainProps {
   fxChainRaw: string | undefined;
   onChainChange: (next: HfAudioFxChain) => void;
   onChainPreview?: (next: HfAudioFxChain) => void;
-  onAuditionTransport?: (on: boolean) => void;
+  /** The clips this chain is heard through, so an audition starts where they
+   *  actually sound rather than from a playhead parked before the first. */
+  auditionSpans?: readonly AuditionSpan[];
+  /** Whether this target is muted right now. */
+  isMuted?: boolean;
+  /** Set this target's mute on the running graph WITHOUT touching the document,
+   *  so an audition can lift a mute and put it back. Hovering a preset on a
+   *  muted bus is a question about the preset, not about the mute. */
+  onSetMutedLive?: (muted: boolean) => void;
 }
 
 interface TimelineFxButtonGroupPointerProps {
   variant: "group-pointer";
-  onGroupClips: () => void;
+  /** Create the group under this name. */
+  onGroupClips: (label: string) => void;
+  /** How many clips are about to be grouped, for the copy that explains it. */
+  clipCount: number;
+  /** Seeded into the name field — "Voiceover" per the design's own mockup. */
+  defaultLabel?: string;
+  /** Why this track cannot be grouped at all. Present, the dialog states the
+   *  limit instead of offering a name field — groups are audio-only in v1
+   *  (§1.4), and the doc is explicit that a deliberate limit has to be said:
+   *  "silent ones just send authors hunting for something that was never
+   *  built." */
+  refusal?: string;
 }
 
 type TimelineFxButtonProps = TimelineFxButtonChainProps | TimelineFxButtonGroupPointerProps;
@@ -49,6 +191,12 @@ export function TimelineFxButton(props: TimelineFxButtonProps) {
   const [open, setOpen] = useState(false);
   const buttonRef = useRef<HTMLButtonElement | null>(null);
   const [anchorRect, setAnchorRect] = useState<DOMRect | null>(null);
+  // Owned here rather than threaded from each caller: both timeline call sites
+  // want the same thing, and neither passed one, so hovering a preset in this
+  // popover was silent unless the transport already happened to be running.
+  const transport = useAuditionTransport();
+  /** Whether THIS audition lifted a mute, so only it puts one back. */
+  const borrowedMute = useRef(false);
 
   const openAt = () => {
     setAnchorRect(buttonRef.current?.getBoundingClientRect() ?? null);
@@ -76,25 +224,17 @@ export function TimelineFxButton(props: TimelineFxButtonProps) {
         {open &&
           anchorRect &&
           createPortal(
-            <div
-              role="dialog"
-              aria-label="Group these clips to add effects"
-              className="z-[200] 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>,
+            <GroupNameDialog
+              refusal={props.refusal}
+              anchorRect={anchorRect}
+              clipCount={props.clipCount}
+              defaultLabel={props.defaultLabel}
+              onCancel={() => setOpen(false)}
+              onConfirm={(label) => {
+                setOpen(false);
+                props.onGroupClips(label);
+              }}
+            />,
             document.body,
           )}
       </div>
@@ -133,7 +273,15 @@ export function TimelineFxButton(props: TimelineFxButtonProps) {
             onClose={() => setOpen(false)}
             onChainChange={props.onChainChange}
             onChainPreview={props.onChainPreview}
-            onAuditionTransport={props.onAuditionTransport}
+            onAuditionTransport={(on) => {
+              // Read on the way IN and remembered: the live unmute flows back
+              // into the row's props, so by the time the audition ends the
+              // target no longer looks muted and the mute would never return.
+              if (on) borrowedMute.current = props.isMuted === true;
+              if (borrowedMute.current) props.onSetMutedLive?.(!on);
+              if (!on) borrowedMute.current = false;
+              transport(on, props.auditionSpans);
+            }}
             onOpenRack={props.onOpenRack}
           />,
           document.body,

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

@@ -23,11 +23,6 @@ function renderHeader(
         laneCount={0}
         isLaneOpen={false}
         onToggleLanes={vi.fn()}
-        hidden={false}
-        onToggleHidden={vi.fn()}
-        isSoloed={false}
-        isHalfLitSolo={false}
-        onToggleSolo={vi.fn()}
         onFxChainChange={vi.fn()}
         onOpenFxRack={vi.fn()}
         columnWidth={220}