fix(studio): stop the grouping dialog opening off the bottom of the window

Reported as "the grouping button did nothing — I clicked it and nothing
happened". The dialog WAS opening. It positioned itself raw at
`top: anchorRect.bottom + 4` with no flip and no clamp, and the timeline lives
at the bottom of the studio window, so it opened past the viewport edge. It was
the only floating surface in this feature with no viewport handling at all — the
FX popover next to it has had a clamp since it was written.

The clamp moves to `components/editor/floatingPanelPosition.ts` and both
surfaces use it, so the next one cannot drift the same way.

Second silent path on the same click, fixed too: the timeline offers the
grouping pointer when `clipCount > 1`, but the write bails out returning [] when
fewer than two clips RESOLVE against the expanded-rows list. That bail is
correct for the carve picker (nothing to group) and invisible for a button
someone just pressed, so a request for 2+ clips that resolves to fewer now says
so instead of doing nothing quietly.

`useAudioGroupCarveAssignment` moves to its own module in the process — it is not
track-visibility work, and that file was at the 600-line studio ceiling.

Two tests, with a realistic bottom-of-window anchor. The existing group-pointer
test passed throughout: happy-dom reports an all-zero rect for an unlaid-out
button, which lands the dialog at top:4 — on screen, and nothing like the app.

Author: vanceingalls

packages/studio/src/components/editor/TimelineFxPopover.tsx

@@ -8,45 +8,20 @@
  * clip) — nothing here serializes a chain of its own.
  */
 
-import { useEffect, useRef, type CSSProperties, type KeyboardEvent } from "react";
+import { useEffect, useRef, type KeyboardEvent } from "react";
 import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
 import type { HfAudioNameKind } from "@hyperframes/core/audio-carve";
 import { FxPresetMenu } from "./propertyPanelFxPresetMenu.js";
 import { applyPresetToChain } from "./useApplyAudioFxPreset.js";
 import { useFxAudition } from "./useFxAudition.js";
+import { floatingPanelStyle } from "./floatingPanelPosition.js";
 
 const POPOVER_WIDTH = 260;
-const VIEWPORT_MARGIN = 8;
+/** Below this much room underneath, the popover flips above the anchor. */
+const POPOVER_PREFERRED_HEIGHT = 260;
 /** Below this the popover is useless anyway; it scrolls instead of vanishing. */
 const MIN_POPOVER_HEIGHT = 160;
 
-function clampedStyle(anchorRect: DOMRect): CSSProperties {
-  const left = Math.min(
-    Math.max(anchorRect.left, VIEWPORT_MARGIN),
-    Math.max(VIEWPORT_MARGIN, window.innerWidth - POPOVER_WIDTH - VIEWPORT_MARGIN),
-  );
-  const spaceBelow = window.innerHeight - anchorRect.bottom;
-  // Named, because the height cap below needs the same quantity the flip does.
-  // (`spaceAbove === anchorRect.top` for a viewport-relative rect, so the flip
-  // condition itself is unchanged — this is a rename, not a behaviour fix.)
-  const spaceAbove = anchorRect.top;
-  const openUpward = spaceBelow < 260 && spaceAbove > spaceBelow;
-  // Flipping direction alone is not enough: the preset list is taller than either
-  // gap on a short window, so the popover ran off the top or the bottom and its
-  // footer ("+ effect" / "Open rack") went with it. Cap to whatever the chosen
-  // side actually has and let the list scroll inside that.
-  const available = (openUpward ? spaceAbove : spaceBelow) - VIEWPORT_MARGIN - 4;
-  return {
-    position: "fixed",
-    left,
-    width: POPOVER_WIDTH,
-    maxHeight: Math.max(MIN_POPOVER_HEIGHT, available),
-    ...(openUpward
-      ? { bottom: window.innerHeight - anchorRect.top + 4 }
-      : { top: anchorRect.bottom + 4 }),
-  };
-}
-
 export interface TimelineFxPopoverProps {
   anchorRect: DOMRect;
   chain: HfAudioFxChain;
@@ -109,7 +84,11 @@ export function TimelineFxPopover({
       role="dialog"
       aria-label="Effects"
       className="z-[200] flex flex-col overflow-hidden rounded-md border border-white/10 bg-[#1b1b1f] p-2 shadow-xl"
-      style={clampedStyle(anchorRect)}
+      style={floatingPanelStyle(anchorRect, {
+        width: POPOVER_WIDTH,
+        preferredHeight: POPOVER_PREFERRED_HEIGHT,
+        minHeight: MIN_POPOVER_HEIGHT,
+      })}
       onKeyDown={onKeyDown}
       onPointerDown={(event) => event.stopPropagation()}
     >

packages/studio/src/components/editor/floatingPanelPosition.ts

@@ -0,0 +1,58 @@
+/**
+ * Viewport-aware placement for a timeline surface portaled to `document.body`.
+ *
+ * Shared because the timeline's floating surfaces sit at the BOTTOM of the
+ * studio window, so the naive `top: anchorRect.bottom + 4` puts them off the
+ * bottom edge — a click that appears to do nothing. The FX popover grew this
+ * handling; the group-creation dialog was still positioning itself raw. One
+ * implementation, so the next surface cannot drift again.
+ */
+
+import type { CSSProperties } from "react";
+
+/** Keep this much clear of every viewport edge. */
+const VIEWPORT_MARGIN = 8;
+/** The gap between the anchor and the surface it opens. */
+const ANCHOR_GAP = 4;
+
+export interface FloatingPanelPlacement {
+  /** Fixed width of the surface, in px — needed to clamp the right edge. */
+  width: number;
+  /**
+   * How tall the surface wants to be. Below this much room underneath, it
+   * flips above the anchor (when there is genuinely more room there).
+   */
+  preferredHeight: number;
+  /** Never cap shorter than this; the surface scrolls instead of vanishing. */
+  minHeight: number;
+}
+
+/**
+ * Placement for `anchorRect`, as inline style. Flips above the anchor when
+ * below is too tight, clamps horizontally into the viewport, and caps the
+ * height to whichever side it chose so the surface cannot run off-screen.
+ */
+export function floatingPanelStyle(
+  anchorRect: DOMRect,
+  { width, preferredHeight, minHeight }: FloatingPanelPlacement,
+): CSSProperties {
+  const left = Math.min(
+    Math.max(anchorRect.left, VIEWPORT_MARGIN),
+    Math.max(VIEWPORT_MARGIN, window.innerWidth - width - VIEWPORT_MARGIN),
+  );
+  const spaceBelow = window.innerHeight - anchorRect.bottom;
+  // The space actually available above. Equal to `anchorRect.top` for a
+  // viewport-relative rect; named because the height cap needs it too.
+  const spaceAbove = anchorRect.top;
+  const openUpward = spaceBelow < preferredHeight && spaceAbove > spaceBelow;
+  const available = (openUpward ? spaceAbove : spaceBelow) - VIEWPORT_MARGIN - ANCHOR_GAP;
+  return {
+    position: "fixed",
+    left,
+    width,
+    maxHeight: Math.max(minHeight, available),
+    ...(openUpward
+      ? { bottom: window.innerHeight - anchorRect.top + ANCHOR_GAP }
+      : { top: anchorRect.bottom + ANCHOR_GAP }),
+  };
+}

packages/studio/src/hooks/timelineTrackVisibility.ts

@@ -532,67 +532,3 @@ export function useTimelineElementVisibilityEditing({
     ],
   );
 }
-
-/**
- * The write behind B6's auto-group: pick two or more voice clips in the carve
- * picker and they land in a group instead of naming each other by id. Same
- * expanded-rows resolution as element-visibility, for the same reason — a
- * nested sub-composition child has no entry in the raw store list.
- */
-export function useAudioGroupCarveAssignment({
-  projectIdRef,
-  activeCompPath,
-  showToast,
-  writeProjectFile,
-  recordEdit,
-  domEditSaveTimestampRef,
-  previewIframeRef,
-  pendingTimelineEditPathRef,
-  isRecordingRef,
-}: UseTimelineElementVisibilityEditingInput): (
-  clipIds: readonly string[],
-  groupId: string,
-) => Promise<void> {
-  const expandedElements = useExpandedTimelineElements();
-  return useCallback(
-    async (clipIds: readonly string[], groupId: string) => {
-      if (isRecordingRef?.current) {
-        showToast("Cannot edit timeline while recording", "error");
-        return;
-      }
-      const pid = projectIdRef.current;
-      if (!pid) return;
-      const keys = new Set(clipIds);
-      const elements = expandedElements.filter((item) => keys.has(item.key ?? item.id));
-      try {
-        await createAudioGroupAndAssignMembers({
-          projectId: pid,
-          activeCompPath,
-          elements,
-          groupId,
-          previewIframe: previewIframeRef.current,
-          writeProjectFile,
-          recordEdit,
-          domEditSaveTimestampRef,
-          pendingTimelineEditPathRef,
-        });
-      } catch (error) {
-        console.error("[Timeline] Failed to group voice clips", error);
-        const message = error instanceof Error ? error.message : "Failed to group voice clips";
-        showToast(message);
-      }
-    },
-    [
-      activeCompPath,
-      expandedElements,
-      previewIframeRef,
-      writeProjectFile,
-      recordEdit,
-      domEditSaveTimestampRef,
-      pendingTimelineEditPathRef,
-      isRecordingRef,
-      showToast,
-      projectIdRef,
-    ],
-  );
-}

packages/studio/src/hooks/useAudioGroupCarveAssignment.ts

@@ -0,0 +1,88 @@
+import { useCallback } from "react";
+import { useExpandedTimelineElements } from "../player/hooks/useExpandedTimelineElements";
+import {
+  createAudioGroupAndAssignMembers,
+  type UseTimelineElementVisibilityEditingInput,
+} from "./timelineTrackVisibility";
+
+/**
+ * The write behind B6's auto-group and behind C1's grouping pointer in a track
+ * header: pick two or more voice clips (or press the pointer on an ungrouped
+ * audio track) and they land in a group instead of naming each other by id.
+ *
+ * Its own module because this is not track-visibility work, and that file is at
+ * the studio 600-line ceiling. Same
+ * expanded-rows resolution as element-visibility, for the same reason — a
+ * nested sub-composition child has no entry in the raw store list.
+ */
+export function useAudioGroupCarveAssignment({
+  projectIdRef,
+  activeCompPath,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  previewIframeRef,
+  pendingTimelineEditPathRef,
+  isRecordingRef,
+}: UseTimelineElementVisibilityEditingInput): (
+  clipIds: readonly string[],
+  groupId: string,
+) => Promise<void> {
+  const expandedElements = useExpandedTimelineElements();
+  return useCallback(
+    async (clipIds: readonly string[], groupId: string) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      const keys = new Set(clipIds);
+      const elements = expandedElements.filter((item) => keys.has(item.key ?? item.id));
+      // `createAudioGroupAndAssignMembers` returns [] for fewer than two
+      // members, which is right for the carve picker (nothing to group) but
+      // silent for a button the author just pressed: the timeline offers the
+      // grouping pointer on `clipCount > 1`, so a request that resolves to
+      // fewer than two clips is an id-space mismatch, not a no-op. Say so
+      // rather than letting the click look like it did nothing.
+      if (clipIds.length > 1 && elements.length < 2) {
+        console.error("[Timeline] Grouping resolved too few clips", {
+          requested: clipIds,
+          resolved: elements.map((item) => item.key ?? item.id),
+        });
+        showToast("Could not group these clips — try expanding the track first", "error");
+        return;
+      }
+      try {
+        await createAudioGroupAndAssignMembers({
+          projectId: pid,
+          activeCompPath,
+          elements,
+          groupId,
+          previewIframe: previewIframeRef.current,
+          writeProjectFile,
+          recordEdit,
+          domEditSaveTimestampRef,
+          pendingTimelineEditPathRef,
+        });
+      } catch (error) {
+        console.error("[Timeline] Failed to group voice clips", error);
+        const message = error instanceof Error ? error.message : "Failed to group voice clips";
+        showToast(message);
+      }
+    },
+    [
+      activeCompPath,
+      expandedElements,
+      previewIframeRef,
+      writeProjectFile,
+      recordEdit,
+      domEditSaveTimestampRef,
+      pendingTimelineEditPathRef,
+      isRecordingRef,
+      showToast,
+      projectIdRef,
+    ],
+  );
+}

packages/studio/src/hooks/useTimelineEditing.ts

@@ -25,10 +25,10 @@ import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
 import { useTimelineDeleteOps } from "./useTimelineDeleteOps";
 import { useSetElementAttribute } from "./timelineElementFxAttribute";
 import {
-  useAudioGroupCarveAssignment,
   useTimelineElementVisibilityEditing,
   useTimelineTrackVisibilityEditing,
 } from "./timelineTrackVisibility";
+import { useAudioGroupCarveAssignment } from "./useAudioGroupCarveAssignment";
 import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
 import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
 import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";

packages/studio/src/player/components/TimelineFxButton.test.tsx

@@ -68,6 +68,36 @@ describe("TimelineFxButton", () => {
     expect(document.querySelector('[role="dialog"]')).toBeTruthy();
   });
 
+  // The reported symptom: clicking FX on an ungrouped audio track "did
+  // nothing". The dialog WAS opening — it was positioned at
+  // `anchorRect.bottom + 4` with no flip, and the timeline lives at the bottom
+  // of the studio window, so it opened past the viewport edge. The old test
+  // passed because happy-dom reports an all-zero rect for an unlaid-out button,
+  // which lands the dialog at top:4 — on screen, and nothing like the real app.
+  it("flips the group dialog above the anchor when it sits at the bottom of the window", () => {
+    const host = mount(<TimelineFxButton variant="group-pointer" onGroupClips={vi.fn()} />);
+    const fx = byTextButton(host, "FX");
+    // A track header near the bottom edge of the (1024x768) window.
+    fx!.getBoundingClientRect = () => ({ left: 300, top: 760, right: 320, bottom: 776 }) as DOMRect;
+    act(() => fx?.click());
+    const dialog = document.querySelector('[role="dialog"]') as HTMLElement;
+    expect(dialog).toBeTruthy();
+    // Anchored from the bottom, not pushed off the edge with `top`.
+    expect(dialog.style.bottom).toBe("12px");
+    expect(dialog.style.top).toBe("");
+  });
+
+  it("keeps the group dialog inside the right edge of the window", () => {
+    const host = mount(<TimelineFxButton variant="group-pointer" onGroupClips={vi.fn()} />);
+    const fx = byTextButton(host, "FX");
+    // Anchor hard against the right edge: 224px wide + 8px margin must fit.
+    fx!.getBoundingClientRect = () =>
+      ({ left: 1010, top: 100, right: 1024, bottom: 116 }) as DOMRect;
+    act(() => fx?.click());
+    const dialog = document.querySelector('[role="dialog"]') as HTMLElement;
+    expect(dialog.style.left).toBe("792px");
+  });
+
   it("group-pointer variant offers Group instead of a popover", () => {
     const onGroupClips = vi.fn();
     const host = mount(<TimelineFxButton variant="group-pointer" onGroupClips={onGroupClips} />);

packages/studio/src/player/components/TimelineFxButton.tsx

@@ -18,6 +18,11 @@ import {
 } from "@hyperframes/core/audio-fx";
 import type { HfAudioNameKind } from "@hyperframes/core/audio-carve";
 import { TimelineFxPopover } from "../../components/editor/TimelineFxPopover.js";
+import { floatingPanelStyle } from "../../components/editor/floatingPanelPosition.js";
+
+/** `w-56`, and roughly the height of its one paragraph plus the button. */
+const GROUP_DIALOG_WIDTH = 224;
+const GROUP_DIALOG_HEIGHT = 120;
 
 function parseFxChainOrEmpty(raw: string | undefined): HfAudioFxChain {
   if (!raw) return { version: 1, nodes: [] };
@@ -80,7 +85,14 @@ export function TimelineFxButton(props: TimelineFxButtonProps) {
               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 }}
+              // Was positioning raw at `anchorRect.bottom + 4`. The timeline
+              // sits at the BOTTOM of the window, so this dialog opened past
+              // the viewport edge and the click read as doing nothing at all.
+              style={floatingPanelStyle(anchorRect, {
+                width: GROUP_DIALOG_WIDTH,
+                preferredHeight: GROUP_DIALOG_HEIGHT,
+                minHeight: GROUP_DIALOG_HEIGHT,
+              })}
               onPointerDown={(event) => event.stopPropagation()}
             >
               <p>Group these clips to add effects to all of them.</p>