Skip to content

Commit 6a92d21

Browse files
vanceingallsclaude
andauthored
feat(studio,core): reach presets and the rack from the timeline (#3292)
C1: the FX button in the track/group header, and its popover — the "reach FX from the timeline" entry point, last on purpose because it targets a group or a single clip, never "a track" (N clips = N chains is the ill-defined thing the design doc refuses to build). The button (TimelineFxButton.tsx): renders on group rows and on track rows holding exactly one audio clip, reading "FX" (or "FX n" once the target's data-fx-chain has n enabled nodes). A multi-clip ungrouped audio track gets a pointer instead ("Group these clips to add effects to all of them" + a Group action) rather than silently hiding the entry point — reuses B6's exact auto-grouping write (useAudioGroupCarveAssignment, exposed as onGroupClips) with a minted group id (mintGroupId, exported from useFxCarveGrouping.ts). The popover (TimelineFxPopover.tsx, components/editor/): a thin positioner around FxPresetMenu exactly as the property panel renders it — same audition contract (useFxAudition), same preset-apply computation (extracted into useApplyAudioFxPreset.ts's applyPresetToChain, now shared with propertyPanelFxSection.tsx's own applyPreset rather than duplicated). Escape closes without deselecting whatever is behind it; an outside pointerdown dismisses. Footer's "+ effect"/"Open rack ›" both select the target and hand off to the property panel (a simplification from the step doc's two distinct behaviors — remotely toggling the rack's own internal "adding" state isn't plumbed anywhere, and building that plumbing would be new UI-state wiring beyond what "reuse existing selection dispatch" asks for). Writes, one path per target kind, neither a new persistence mechanism: - Group: B7/B5's existing onSetAudioGroupAttributeLive/Quiet (data-fx-chain, same as data-volume/data-hidden already do). - Clip: a NEW onSetElementAttributeLive/Quiet pair (timelineElementFxAttribute.ts), addressed by the TimelineElement itself rather than the current selection. This is the one real architectural gap the step doc's assumption didn't survive: the property panel's onSetAttributeQuiet closes over domEditSelection, so writing a clip that isn't already selected has no synchronous path through it. Extracted the shared live-patch-then-persist core (persistElementAttribute, timelineEditingHelpers.ts) out of both this new path and the existing setAudioGroupAttribute, which the fallow duplication gate flagged as a 66-line clone on first pass — now a single ~50-line core parameterized by patchLive/readLive, with each caller a ~15-line wrapper resolving its own patch target (buildPatchTarget({domId}) for a group, buildPatchTarget(element) for an arbitrary clip) and live-DOM lookup. Data plumbing: HfAudioGroup.fxChain (already on the B1 model) mirrored onto TimelineElement.audioGroupFxChain (timelineDOM.ts's groupInfoFor cache) and TimelineTrackGroupInfo.fxChain (useTimelineTrackDerivations.ts), alongside the existing volume/hidden mirrors. Deferred: the property panel's own rack doesn't (yet) expose a way to remotely force its add-menu open, so "+ effect" and "Open rack ›" converge on the same navigation rather than the step doc's two distinct ones. A grouped multi-clip track (some clips already carry data-audio-group) gets neither the chain button nor the pointer — its members' own per-clip FX buttons still work individually, and the group's own FX button on TimelineGroupHeader covers the group level. Gates: bun run build clean; packages/studio full suite 4286/4304 (18 pre-existing todo, up from 4276/4294 — 10 new tests, 0 regressions); new TimelineFxPopover.test.tsx (6) + TimelineFxButton.test.tsx (4) cover exactly-one-write-per-apply, hover-audition-reverts-on-leave, Escape-without-deselecting, outside/inside pointerdown dismissal, and the group-pointer's Group action; oxfmt/oxlint clean on all 22 touched files; fallow clean (0 new dead-code/unused-export/duplication findings — the pointer test caught during the first commit attempt). Co-authored-by: Claude Sonnet 5 <[email protected]>
1 parent 9ec75a4 commit 6a92d21

23 files changed

Lines changed: 1148 additions & 215 deletions

‎packages/studio/src/App.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -546,6 +546,8 @@ export function StudioApp() {
546546
handleTimelineGroupResize={timelineEditing.handleTimelineGroupResize}
547547
handleToggleTrackHidden={timelineEditing.handleToggleTrackHidden}
548548
setAudioGroupAttribute={timelineEditing.setAudioGroupAttribute}
549+
handleGroupClips={timelineEditing.handleAutoGroupCarveSources}
550+
setElementFxAttribute={timelineEditing.setElementFxAttribute}
549551
handleBlockedTimelineEdit={timelineEditing.handleBlockedTimelineEdit}
550552
handleTimelineElementSplit={timelineEditing.handleTimelineElementSplit}
551553
handleRazorSplit={timelineEditing.handleRazorSplit}

‎packages/studio/src/components/EditorShell.tsx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,8 @@ export function EditorShell({
8686
handleTimelineGroupResize,
8787
handleToggleTrackHidden,
8888
setAudioGroupAttribute,
89+
handleGroupClips,
90+
setElementFxAttribute,
8991
handleBlockedTimelineEdit,
9092
handleTimelineElementSplit,
9193
handleRazorSplit,
@@ -137,6 +139,8 @@ export function EditorShell({
137139
handleTimelineGroupResize,
138140
handleToggleTrackHidden,
139141
setAudioGroupAttribute,
142+
handleGroupClips,
143+
setElementFxAttribute,
140144
handleBlockedTimelineEdit,
141145
handleTimelineElementSplit,
142146
handleRazorSplit,
Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
// @vitest-environment happy-dom
2+
import { act } from "react";
3+
import { afterEach, describe, expect, it, vi } from "vitest";
4+
import { createRoot } from "react-dom/client";
5+
import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
6+
import { TimelineFxPopover } from "./TimelineFxPopover.js";
7+
8+
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
9+
10+
const EMPTY_CHAIN: HfAudioFxChain = { version: 1, nodes: [] };
11+
const RECT = { left: 0, top: 0, right: 0, bottom: 0 } as DOMRect;
12+
13+
function byTextButton(host: HTMLElement, text: string): HTMLButtonElement | undefined {
14+
return Array.from(host.querySelectorAll("button")).find((b) => b.textContent?.includes(text));
15+
}
16+
17+
function mount(overrides: Partial<Parameters<typeof TimelineFxPopover>[0]> = {}) {
18+
const onClose = vi.fn();
19+
const onChainChange = vi.fn();
20+
const onChainPreview = vi.fn();
21+
const onOpenRack = vi.fn();
22+
const host = document.createElement("div");
23+
document.body.append(host);
24+
act(() => {
25+
createRoot(host).render(
26+
<TimelineFxPopover
27+
anchorRect={RECT}
28+
chain={EMPTY_CHAIN}
29+
onClose={onClose}
30+
onChainChange={onChainChange}
31+
onChainPreview={onChainPreview}
32+
onOpenRack={onOpenRack}
33+
{...overrides}
34+
/>,
35+
);
36+
});
37+
return { host, onClose, onChainChange, onChainPreview, onOpenRack };
38+
}
39+
40+
afterEach(() => {
41+
document.body.innerHTML = "";
42+
});
43+
44+
describe("TimelineFxPopover", () => {
45+
it("applies a preset with exactly one onChainChange write, and closes", () => {
46+
const { host, onChainChange, onClose } = mount();
47+
const button = byTextButton(host, "Chipmunk");
48+
expect(button).toBeDefined();
49+
act(() => button?.click());
50+
expect(onChainChange).toHaveBeenCalledTimes(1);
51+
const written = onChainChange.mock.calls[0]?.[0] as HfAudioFxChain;
52+
expect(written.nodes.length).toBeGreaterThan(0);
53+
expect(onClose).toHaveBeenCalled();
54+
});
55+
56+
it("auditions on hover (focus is the keyboard's hover) and reverts on leave", () => {
57+
const { host, onChainPreview } = mount();
58+
const button = byTextButton(host, "Chipmunk");
59+
expect(button).toBeDefined();
60+
act(() => (button as HTMLButtonElement).focus());
61+
expect(onChainPreview).toHaveBeenCalled();
62+
const previewed = onChainPreview.mock.calls.at(-1)?.[0] as HfAudioFxChain;
63+
expect(previewed.nodes.length).toBeGreaterThan(0);
64+
onChainPreview.mockClear();
65+
act(() => {
66+
button?.dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
67+
});
68+
expect(onChainPreview).toHaveBeenCalledWith(EMPTY_CHAIN);
69+
});
70+
71+
it("Escape closes without letting the keystroke propagate past the popover", () => {
72+
const { host, onClose } = mount();
73+
const outer = vi.fn();
74+
document.body.addEventListener("keydown", outer);
75+
const dialog = host.querySelector('[role="dialog"]');
76+
expect(dialog).toBeTruthy();
77+
act(() => {
78+
dialog?.dispatchEvent(
79+
new KeyboardEvent("keydown", { key: "Escape", bubbles: true, cancelable: true }),
80+
);
81+
});
82+
expect(onClose).toHaveBeenCalled();
83+
expect(outer).not.toHaveBeenCalled();
84+
document.body.removeEventListener("keydown", outer);
85+
});
86+
87+
it("dismisses on an outside pointerdown", () => {
88+
const { onClose } = mount();
89+
act(() => {
90+
document.body.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true }));
91+
});
92+
expect(onClose).toHaveBeenCalled();
93+
});
94+
95+
it("does not dismiss on a pointerdown inside the popover", () => {
96+
const { host, onClose } = mount();
97+
const dialog = host.querySelector('[role="dialog"]');
98+
expect(dialog).toBeTruthy();
99+
act(() => {
100+
dialog?.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true }));
101+
});
102+
expect(onClose).not.toHaveBeenCalled();
103+
});
104+
105+
it("the footer opens the rack and closes the popover", () => {
106+
const { host, onOpenRack, onClose } = mount();
107+
const openRack = byTextButton(host, "Open rack");
108+
expect(openRack).toBeDefined();
109+
act(() => openRack?.click());
110+
expect(onOpenRack).toHaveBeenCalledTimes(1);
111+
expect(onClose).toHaveBeenCalled();
112+
});
113+
});
Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
/**
2+
* The FX popover the timeline's per-track/per-group FX button opens (C1).
3+
*
4+
* A THIN positioner around existing pieces, not a second rack: the body is
5+
* `FxPresetMenu` exactly as the property panel's FX section renders it, and
6+
* applying or auditioning a preset goes through the caller's own write path
7+
* (a group's own attribute for a group target, the selected element's for a
8+
* clip) — nothing here serializes a chain of its own.
9+
*/
10+
11+
import { useEffect, useRef, type CSSProperties, type KeyboardEvent } from "react";
12+
import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
13+
import type { HfAudioNameKind } from "@hyperframes/core/audio-carve";
14+
import { FxPresetMenu } from "./propertyPanelFxPresetMenu.js";
15+
import { applyPresetToChain } from "./useApplyAudioFxPreset.js";
16+
import { useFxAudition } from "./useFxAudition.js";
17+
18+
const POPOVER_WIDTH = 260;
19+
const VIEWPORT_MARGIN = 8;
20+
21+
function clampedStyle(anchorRect: DOMRect): CSSProperties {
22+
const left = Math.min(
23+
Math.max(anchorRect.left, VIEWPORT_MARGIN),
24+
Math.max(VIEWPORT_MARGIN, window.innerWidth - POPOVER_WIDTH - VIEWPORT_MARGIN),
25+
);
26+
const spaceBelow = window.innerHeight - anchorRect.bottom;
27+
const openUpward = spaceBelow < 260 && anchorRect.top > spaceBelow;
28+
return {
29+
position: "fixed",
30+
left,
31+
width: POPOVER_WIDTH,
32+
...(openUpward
33+
? { bottom: window.innerHeight - anchorRect.top + 4 }
34+
: { top: anchorRect.bottom + 4 }),
35+
};
36+
}
37+
38+
export interface TimelineFxPopoverProps {
39+
anchorRect: DOMRect;
40+
chain: HfAudioFxChain;
41+
trackKind?: HfAudioNameKind;
42+
onClose: () => void;
43+
/** Persist the applied preset onto the target (group attribute, or the
44+
* selected clip's attribute — the caller resolves which). */
45+
onChainChange: (next: HfAudioFxChain) => void;
46+
/** Preview a hypothetical chain on the running graph without persisting. */
47+
onChainPreview?: (next: HfAudioFxChain) => void;
48+
onAuditionTransport?: (on: boolean) => void;
49+
/** Select the target the way clicking it in the timeline does, and ensure
50+
* the property panel's Audio FX group is expanded. */
51+
onOpenRack: () => void;
52+
}
53+
54+
export function TimelineFxPopover({
55+
anchorRect,
56+
chain,
57+
trackKind,
58+
onClose,
59+
onChainChange,
60+
onChainPreview,
61+
onAuditionTransport,
62+
onOpenRack,
63+
}: TimelineFxPopoverProps) {
64+
const rootRef = useRef<HTMLDivElement | null>(null);
65+
const { audition, clearAudition } = useFxAudition(chain, onChainPreview, onAuditionTransport);
66+
67+
// Outside click dismisses like any other popover; the button itself is
68+
// excluded by pointerdown timing (the button's own click hasn't happened yet).
69+
useEffect(() => {
70+
const onPointerDown = (event: PointerEvent) => {
71+
if (rootRef.current && !rootRef.current.contains(event.target as Node)) onClose();
72+
};
73+
document.addEventListener("pointerdown", onPointerDown, true);
74+
return () => document.removeEventListener("pointerdown", onPointerDown, true);
75+
}, [onClose]);
76+
77+
const applyPreset = (id: string) => {
78+
const next = applyPresetToChain(chain, id, trackKind);
79+
if (!next) return;
80+
clearAudition();
81+
onChainChange(next);
82+
onClose();
83+
};
84+
85+
// Escape closes without deselecting whatever is behind this — a keystroke
86+
// aimed at the popover is not aimed at the clip under it.
87+
const onKeyDown = (event: KeyboardEvent) => {
88+
if (event.key !== "Escape") return;
89+
event.stopPropagation();
90+
audition(null);
91+
onClose();
92+
};
93+
94+
return (
95+
<div
96+
ref={rootRef}
97+
role="dialog"
98+
aria-label="Effects"
99+
className="z-50 rounded-md border border-white/10 bg-[#1b1b1f] p-2 shadow-xl"
100+
style={clampedStyle(anchorRect)}
101+
onKeyDown={onKeyDown}
102+
onPointerDown={(event) => event.stopPropagation()}
103+
>
104+
<FxPresetMenu
105+
trackKind={trackKind}
106+
onPick={applyPreset}
107+
onAudition={
108+
onChainPreview
109+
? (id) =>
110+
audition(id ? (base) => applyPresetToChain(base, id, trackKind) ?? base : null)
111+
: undefined
112+
}
113+
/>
114+
<div className="mt-2 flex items-center justify-between border-t border-white/10 pt-2 text-[10px] text-white/55">
115+
<button
116+
type="button"
117+
className="hover:text-white"
118+
onClick={() => {
119+
onClose();
120+
onOpenRack();
121+
}}
122+
>
123+
+ effect
124+
</button>
125+
<button
126+
type="button"
127+
className="hover:text-white"
128+
onClick={() => {
129+
onClose();
130+
onOpenRack();
131+
}}
132+
>
133+
Open rack ›
134+
</button>
135+
</div>
136+
</div>
137+
);
138+
}

‎packages/studio/src/components/editor/propertyPanelFxSection.tsx‎

Lines changed: 4 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import {
1414
type HfAudioFxParamValues,
1515
} from "@hyperframes/core/audio-fx";
1616
import { applyAudioFxPreset, getAudioFxPreset } from "@hyperframes/core/audio-fx-presets";
17+
import { applyPresetToChain } from "./useApplyAudioFxPreset.js";
1718
import {
1819
addAudioEq,
1920
audioEqIds,
@@ -31,7 +32,6 @@ import {
3132
trackNodeAdded,
3233
trackNodeMoved,
3334
trackNodeRemoved,
34-
trackPresetApplied,
3535
trackPresetAuditioned,
3636
trackPresetAutomated,
3737
trackPresetRemoved,
@@ -138,31 +138,16 @@ export function FxSection({
138138

139139
const applyPreset = useCallback(
140140
(id: string) => {
141-
const preset = getAudioFxPreset(id);
142-
if (!preset) return;
143-
// Appends. Stacking a character preset onto an already-cleaned voice is a
144-
// real thing to want, and replacing silently would throw work away — so
145-
// the destructive option is a separate gesture, not the default one.
146-
const next = applyAudioFxPreset(chain, preset);
147-
// Re-applying replaces this preset's own nodes in place rather than
148-
// appending a second copy, and the two are different decisions — worth
149-
// telling apart in the numbers.
150-
const reapply = chain.nodes.some((n) => n.fromPreset === preset.id);
151-
trackPresetApplied(
152-
preset.id,
153-
preset.family,
154-
preset.nodes.length,
155-
reapply ? "reapply" : "append",
156-
{ trackKind },
157-
);
141+
const next = applyPresetToChain(chain, id, trackKind);
142+
if (!next) return;
158143
// The audition WAS this, so there is nothing to put back — and putting the
159144
// old chain back over the write that just landed is a race the author
160145
// hears as the preset arriving and then leaving again.
161146
clearAudition();
162147
mutate(next.nodes);
163148
// Land on the first node the preset wrote, so the author can hear what
164149
// arrived and immediately see what it is made of.
165-
setOpenNode(next.nodes.findIndex((n) => n.fromPreset === preset.id));
150+
setOpenNode(next.nodes.findIndex((n) => n.fromPreset === id));
166151
setPicking(false);
167152
},
168153
[chain, mutate, clearAudition, trackKind],
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/**
2+
* Append (or, on reapply, replace in place) a preset's nodes onto a chain,
3+
* with the telemetry that decision needs — the write path the property
4+
* panel's FX section and the timeline FX popover (C1) both use, so a preset
5+
* applied from either surface counts the same way.
6+
*/
7+
8+
import { applyAudioFxPreset, getAudioFxPreset } from "@hyperframes/core/audio-fx-presets";
9+
import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
10+
import type { HfAudioNameKind } from "@hyperframes/core/audio-carve";
11+
import { trackPresetApplied } from "./audioFxTelemetry.js";
12+
13+
export function applyPresetToChain(
14+
chain: HfAudioFxChain,
15+
presetId: string,
16+
trackKind: HfAudioNameKind | undefined,
17+
): HfAudioFxChain | null {
18+
const preset = getAudioFxPreset(presetId);
19+
if (!preset) return null;
20+
// Appends. Stacking a character preset onto an already-cleaned voice is a
21+
// real thing to want, and replacing silently would throw work away — so
22+
// the destructive option is a separate gesture, not the default one.
23+
const next = applyAudioFxPreset(chain, preset);
24+
// Re-applying replaces this preset's own nodes in place rather than
25+
// appending a second copy, and the two are different decisions — worth
26+
// telling apart in the numbers.
27+
const reapply = chain.nodes.some((n) => n.fromPreset === preset.id);
28+
trackPresetApplied(
29+
preset.id,
30+
preset.family,
31+
preset.nodes.length,
32+
reapply ? "reapply" : "append",
33+
{ trackKind },
34+
);
35+
return next;
36+
}

‎packages/studio/src/components/editor/useFxCarveGrouping.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ import { resolveAudioGroups } from "@hyperframes/core/audio-groups";
1515
* document — group ids and plain element ids share one namespace, so both
1616
* have to be checked.
1717
*/
18-
function mintGroupId(doc: Document): string {
18+
export function mintGroupId(doc: Document): string {
1919
const taken = new Set([
2020
...resolveAudioGroups(doc).map((g) => g.id),
2121
...Array.from(doc.querySelectorAll("[id]")).map((el) => el.id),

0 commit comments

Comments
 (0)