From df57ad4bace78f97bef51d9b1dc32ec1f6ded431 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 13 Aug 2026 03:16:35 -0700 Subject: [PATCH] fix(studio): the shared-row follow-ups (#3215) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(core): dedupe the wet/dry mix math between delayFeedback and chorusLfo Both effect builders set wet.gain to the mix and dry.gain to its complement in identical two-line blocks; fallow kept re-flagging it as a 10-line clone on every unrelated change. Extracted setWetDryMix. * fix(core): remove the build-audio-fx-runtime.ts stray resurrected by a main merge An earlier merge with main brought this deleted file back (git's merge/delete handling on an unchanged-on-one-side file); package.json already points at build-inline-artifact.ts, so it sat unreachable and duplicating that file's config, both of which fallow flagged. * fix(studio): pull TimelineLanes under the 600-line cap TimelineLanes.tsx hit 620 lines. Extracted the three per-clip pointer gestures (resize-start, pointer-down move-arm, click/razor-split) into createClipGestureHandlers — one factory call per rendered clip instead of ~120 lines of inline handler bodies in the render loop. 529 lines now. * fix(studio): split the extracted pointerdown handler under the CRAP threshold Moving the ~120-line gesture logic into timelineClipGestureHandlers.ts concentrated it into two functions fallow flagged (onPointerDown at CRAP 63.6, onResizeStart at 31.6). Split the decision logic (which gesture a pointerdown implies) into a pure resolvePointerDownAction, then split its own intent-blocking check into isIntentBlocked. onResizeStart's guard moved into canStartResize. Every function now scores under 30. * fix(studio): drop the unused DomEditSelection import in PropertyPanelFlat CI caught it on PR #3026 (wa-12-panel-params); a later refactor in the stack removed the last use of the type here without removing the import. * fix(studio): close the typecheck and fallow gaps wa-18b-reschedule opened useAutomationLanes.ts's write() assumed gesture-scoped coalescing and a preview-only commit that useDomEditAttributeCommits.ts never grew — backported that option support from its own later commit so the two sides of the API agree. The paste path and its tests were missing the box selection's v0/v1 bounds a sibling commit added to AutomationSelection. The FX panel's carve controls still edited the six mechanism numbers (maxCutDb, bands, intelligibilityBias) after carveProfile() collapsed authoring to one Strength knob, so those fields no longer existed on HfCarveSettings; UI now edits strength, and analyseCarveBands is called with carveProfile(strength). Also closes fallow's complexity, dead-code and duplication findings on this PR's diff: extracted automationLaneDragMath.ts (pure group/point-move math) and useAutomationRangeDrag.ts (the marquee-select gesture) out of useAutomationLaneGestures.ts, pulled a couple of render-loop ternaries and a resolver into named functions, dropped an export nothing outside its file used, and shared a step-simplifier between audioCarve's two envelope builders. The edge-stretch vs. box-select priority test in TimelineAutomationLane.test was still pinning the pre-box-select rule (edge wins over a point sitting on it) that a sibling commit deliberately reversed — a point inside the box is now selected content, so grabbing it drags the group instead. Updated the test to the shipped rule instead of the old one. Co-Authored-By: Claude Opus 5 (1M context) * fix(core): cap the via conic's weight so an edge-clamped via point can't NaN A via point pulled out past the segment (viaX: 5, viaY: -3) clamps to (0.999, 0.001) — exactly on the steady region's edge, where edge - viaX is 0. viaConic divided by that zero to get an infinite weight, and shapeVia turned Infinity into NaN a few steps later (Infinity - Infinity in the quadratic coefficient). NaN reaching setValueCurveAtTime silences the automated parameter for the rest of the render. Capped the weight at 1e6 instead of leaving it unbounded — past that point the arc already reads as touching the via point, so nothing visible is lost. Also hardened shapeVia's existing denominator guard (`<= 0`) to `!(> 0)`, since NaN fails the original comparison and fell through it. Review by Miga (PR #3208). * fix(studio-server): fingerprint the proactive waveform cache key too The route already keys the waveform cache on the asset's size and mtime as well as its path, so a rebuilt-in-place file gets fresh peaks instead of stale ones. generateWaveformCache — the proactive path that runs on upload — still called buildWaveformCacheKey with the path alone, so it wrote to a different key than the route reads from (making the pre-generated cache never found) and kept the exact collision bug this fingerprint exists to fix on its own path. Review by Miga (PR #3211). * style(docs): run oxfmt on the /hyperframes-audio skill docs Table column widths had drifted out of alignment with oxfmt's own rules, failing format:check and blocking the Preflight gate every downstream branch inherits. Whitespace only, no content change. * fix(core): stop \b from missing underscore-separated names, guard clipsOverlap's negative duration \b treats `_` as a word character, so \bbed\b never matched bed_01, music_bed_loop, or theme_song, and \bvo\b/\bvox\b/\btts\b had the same gap — an underscore-separated bed classified as "unknown" and could end up offered as its own carve source. Replaced the short hints with a boundary that actually excludes letters and digits on both sides. clipsOverlap computed end = start + duration without guarding sign, so a negative duration put end before start — an interval that does not describe anything, and one specific case showed it silently dropping a real overlap (a shorter, earlier broken end rejected a clip that genuinely contained the point). Duration clamps to zero instead: a clip cannot un-play time, and a zero-length clip at its start is the sane reading of "duration nobody wrote down as positive." Review by Miga (PR #3212). * fix(studio): widen PropertyPanel's resetModules render timeout again The 20s margin (already once widened for the same reason) is timing out in CI's full-monorepo Test run — the resetModules()+fresh-import render this test needs is uncached and competes with every other package's test suite for the same worker pool, and the same test passes in well under 2s standalone. Went to 45s rather than re-tuning to whatever number happens to clear the current CI load, since that number moves every time CI gains a package. * fix(studio): stop the single-candidate auto-apply carve firing twice Two auto-apply effects both fire when sourceOptions.length === 1: the multi-candidate effect only guards length === 0, so a single candidate passes it too, and the single-candidate effect passes its own guard right after — both compute the same sources list and both call setCarve, so the common case (one narrator, one bed) triggered two decodes, two FFT runs, and two concurrent attribute writes for one decision. The multi-candidate effect now defers to its sibling for exactly one candidate, which already has its own detailed handling for that case. Review by Miga (PR #3213). * feat(core): carve against every voice over a bed, always (#3212) * feat(core): carve against every voice over a bed, always dynamically A bed usually runs under a whole sequence — a narrator, an interview answer, a second presenter — and carving against one of them left the others fighting it. `source` becomes `sources`, and `mixCarveSources` sums every voice onto the BED's clock before anything is measured. That is what keeps one analysis sufficient: the chain is fixed, so there is no per-voice filter to switch between, and bands drawn from all the speech there is with envelopes that rise wherever any of it happens answer the actual question — where and when is speech masking this bed. Summed rather than averaged: two people talking at once mask more than either alone. Audio before the bed starts is dropped rather than folded in at zero, since it plays over nothing and shifting it would put a cut where there is no voice. `dynamic` is gone. A fixed depth thins the bed through every pause, and once both have been heard there is no reason to want it, so every carve follows the speech. Two helpers the panel and the headless script now share instead of each carrying a copy — two definitions of "what does this name suggest" drift, and then the two disagree about which track is the voice: - `classifyAudioName` reads a track's kind from its id and filename together. `unknown` is deliberately common: treating an unrecognised name as "not a voice" would hide the one track somebody needs to pick. - `clipsOverlap` keeps out a voice that never plays while the bed does. An unwritten duration counts as unbounded, not zero — refusing a clip whose length the composition leaves to the media would drop the commonest case there is. Files written before this still load: a single `source` reads as a one-voice list, a stored `dynamic` is ignored, and an absent attribute means the defaults whole. Co-Authored-By: Claude Opus 5 (1M context) * fix(core): stop \b from missing underscore-separated names, guard clipsOverlap's negative duration \b treats `_` as a word character, so \bbed\b never matched bed_01, music_bed_loop, or theme_song, and \bvo\b/\bvox\b/\btts\b had the same gap — an underscore-separated bed classified as "unknown" and could end up offered as its own carve source. Replaced the short hints with a boundary that actually excludes letters and digits on both sides. clipsOverlap computed end = start + duration without guarding sign, so a negative duration put end before start — an interval that does not describe anything, and one specific case showed it silently dropping a real overlap (a shorter, earlier broken end rejected a clip that genuinely contained the point). Duration clamps to zero instead: a clip cannot un-play time, and a zero-length clip at its start is the sane reading of "duration nobody wrote down as positive." Review by Miga (PR #3212). --------- Co-authored-by: Claude Opus 5 (1M context) * fix(studio): port the carve UI off the removed source/dynamic fields #3212 (accidentally squash-merged into this branch instead of main) changed HfCarveSettings from a single `source` + `dynamic` toggle to a `sources` list with dynamic mode removed outright — the multi-voice UI consumer that goes with that shape lands in the very next PR, so this branch was left with a type that no longer matched its own code. Minimal port, not the multi-voice redesign that PR does properly: the "Listen to" picker and analyse() treat sources[0] as the one voice this UI still understands, and every dynamic-mode branch (the automated envelope lanes, the toggle, the checkbox) is gone along with the field — a carve is now always the static value the analysis computes, matching what the type change made permanent. Test suite trimmed the same way: the automation-lane and toggle tests covered behavior that no longer exists. --------- Co-authored-by: Claude Opus 5 (1M context) --- .../editor/propertyPanelAudioFxGroup.test.tsx | 165 +++++++++++- .../editor/propertyPanelAudioFxGroup.tsx | 107 ++++++-- .../src/hooks/useElementLifecycleOps.ts | 3 + .../studio/src/hooks/useTimelineEditing.ts | 3 + .../components/AutomationValueInput.tsx | 4 +- .../src/player/components/Timeline.test.ts | 47 ++++ .../components/TimelineAutomationLane.tsx | 9 +- .../TimelineAutomationLaneSlot.test.tsx | 25 +- .../player/components/TimelineLanes.test.tsx | 29 +- .../src/player/components/TimelineLanes.tsx | 64 +++-- .../components/TimelinePropertyLanes.tsx | 10 +- .../player/components/TimelineTrackHeader.tsx | 7 +- .../player/components/TimelineTrackRow.tsx | 9 +- .../src/utils/studioFileHistory.test.ts | 49 ++++ .../studio/src/utils/studioFileHistory.ts | 18 +- plans/audio-automation-lanes/SPEC.md | 255 ++++++++++++++++++ plans/automation-lanes-shared-rows.md | 6 +- plans/automation-time-selection-design.md | 174 ++++++++++++ 18 files changed, 913 insertions(+), 71 deletions(-) create mode 100644 plans/audio-automation-lanes/SPEC.md create mode 100644 plans/automation-time-selection-design.md diff --git a/packages/studio/src/components/editor/propertyPanelAudioFxGroup.test.tsx b/packages/studio/src/components/editor/propertyPanelAudioFxGroup.test.tsx index 73b8d9f11..7950411fc 100644 --- a/packages/studio/src/components/editor/propertyPanelAudioFxGroup.test.tsx +++ b/packages/studio/src/components/editor/propertyPanelAudioFxGroup.test.tsx @@ -1114,15 +1114,21 @@ describe("AudioFxGroup carve source list", () => { }); it("keeps the picker when the stored voice is not among the candidates", () => { - // The stored track was renamed, or classifies as music now. Reading the one - // remaining candidate out would quietly claim the carve listens to it. + // The stored track is still there but no longer classifies as a voice. + // Reading the one remaining candidate out would quietly claim the carve + // listens to it. (A stored track that is GONE is a different case — see the + // deleted-voice tests, which re-analyse rather than sit on a measurement of + // something that is not there.) const bed = document.createElement("audio"); bed.id = "bed"; bed.setAttribute( "data-fx-carve", - JSON.stringify({ enabled: true, sources: ["gone"], strength: 0.25 }), + JSON.stringify({ enabled: true, sources: ["backing-music"], strength: 0.25 }), ); document.body.append(bed); + const stored = document.createElement("audio"); + stored.id = "backing-music"; + document.body.append(stored); const voice = document.createElement("audio"); voice.id = "narration"; document.body.append(voice); @@ -1136,7 +1142,7 @@ describe("AudioFxGroup carve source list", () => { dataAttributes: { "fx-carve": JSON.stringify({ enabled: true, - sources: ["gone"], + sources: ["backing-music"], strength: 0.25, }), }, @@ -1310,3 +1316,154 @@ describe("AudioFxGroup carve across tracks", () => { ]); }); }); + +/** + * The filters and envelopes a carve produces are a MEASUREMENT of specific + * tracks. Delete one and they describe something nobody can hear any more — the + * bed keeps ducking for a voice that is gone. + */ +describe("AudioFxGroup carve against a deleted voice", () => { + const CARVED_CHAIN = JSON.stringify({ + version: 1, + nodes: [ + { type: "peaking", id: "c1", enabled: true, fromCarve: true, params: { frequency: 1000 } }, + { type: "lowpass", id: "k1", enabled: true, params: { frequency: 8000 } }, + ], + }); + const CARVED_AUTOMATION = JSON.stringify({ + version: 1, + lanes: [ + { target: "fx.c1.gain", points: [{ t: 0, v: -6 }] }, + { target: "fx.k1.frequency", points: [{ t: 0, v: 8000 }] }, + ], + }); + + /** + * A bed carving against `sources`, with only `present` still in the composition. + * + * The timeline is what says a track is gone — not the preview DOM, which keeps + * a deleted element around — so the store is seeded and the document is left + * holding every track, which is exactly the mismatch the studio produces. + */ + function mountCarved(sources: string[], present: string[]) { + const carve = JSON.stringify({ enabled: true, sources, strength: 0.25 }); + const bed = document.createElement("audio"); + bed.id = "bed"; + document.body.append(bed); + for (const id of new Set([...sources, ...present])) { + const el = document.createElement("audio"); + el.id = id; + document.body.append(el); + } + usePlayerStore.setState({ + elements: [ + { id: "bed", tag: "audio", start: 0, duration: 10, track: 0 }, + ...present.map((id) => ({ id, tag: "audio", start: 0, duration: 10, track: 1 })), + ] as never, + }); + const onSetAttributeQuiet = vi.fn(); + const host = document.createElement("div"); + document.body.append(host); + act(() => { + createRoot(host).render( + , + ); + }); + return { host, onSetAttributeQuiet }; + } + + it("re-analyses against the voices that are left", () => { + // Two voices were measured together into one set of bands. With one gone that + // set answers a question nobody asked; the survivor has to be measured again. + const { onSetAttributeQuiet } = mountCarved(["narration", "guest"], ["narration"]); + const write = writeTo(onSetAttributeQuiet.mock.calls, "data-fx-carve"); + expect(JSON.parse(String(write![1]))).toMatchObject({ + enabled: true, + sources: ["narration"], + }); + }); + + it("leaves a carve alone while every voice it names is still there", () => { + const { onSetAttributeQuiet } = mountCarved(["narration", "guest"], ["narration", "guest"]); + expect(onSetAttributeQuiet.mock.calls.some((c) => c[0] === "data-fx-carve")).toBe(false); + }); + + it("does not fall back to carving against an effect when no voice is left", async () => { + // Found in the studio, not here: deleting the narration emptied the source + // list, and the panel filled it again with the only audio in the composition + // — a 200 ms explosion. The picker's fallback (offer everything rather than + // hide the track somebody needs) is for the AUTHOR to choose from. The panel + // choosing off it is the panel deciding, and that is never the answer. + const carve = JSON.stringify({ enabled: true, sources: [], strength: 0.25 }); + const bed = document.createElement("audio"); + bed.id = "bed"; + bed.setAttribute("data-fx-carve", carve); + document.body.append(bed); + const sfx = document.createElement("audio"); + sfx.id = "sfx-explosion"; + document.body.append(sfx); + const onSetAttributeQuiet = vi.fn(); + const host = document.createElement("div"); + document.body.append(host); + act(() => { + createRoot(host).render( + , + ); + }); + await act(async () => {}); + // Nothing written: the carve waits rather than picking the explosion. + expect(onSetAttributeQuiet.mock.calls.some((c) => c[0] === "data-fx-carve")).toBe(false); + // Still offered, so the author can say "actually, listen to that one". + expect( + Array.from(host.querySelectorAll("[data-carve-source]")).map((e) => + e.getAttribute("data-carve-source"), + ), + ).toEqual(["sfx-explosion"]); + }); + + it("drops what it generated when the last voice goes and none is left to pick", async () => { + // Staying on with nothing to listen to is honest — a voice may come back, and + // "off" is a different thing the author chose. What cannot stay is the output: + // those filters and that envelope are making room for nobody. + const { onSetAttributeQuiet } = mountCarved(["narration"], []); + // The three writes are sequenced, not fired together: each is a + // read-modify-write against the same file, so the carve write lands only + // after the two that strip its output. + await act(async () => {}); + const carve = writeTo(onSetAttributeQuiet.mock.calls, "data-fx-carve"); + expect(JSON.parse(String(carve![1]))).toMatchObject({ enabled: true, sources: [] }); + + const chain = writeTo(onSetAttributeQuiet.mock.calls, "data-fx-chain"); + // The hand-added low-pass survives; only what the carve minted goes. + expect(JSON.parse(String(chain![1])).nodes.map((n: { id: string }) => n.id)).toEqual(["k1"]); + + const automation = writeTo(onSetAttributeQuiet.mock.calls, "data-automation"); + expect( + JSON.parse(String(automation![1])).lanes.map((l: { target: string }) => l.target), + ).toEqual(["fx.k1.frequency"]); + }); +}); diff --git a/packages/studio/src/components/editor/propertyPanelAudioFxGroup.tsx b/packages/studio/src/components/editor/propertyPanelAudioFxGroup.tsx index 664f701ea..224d653aa 100644 --- a/packages/studio/src/components/editor/propertyPanelAudioFxGroup.tsx +++ b/packages/studio/src/components/editor/propertyPanelAudioFxGroup.tsx @@ -48,6 +48,7 @@ import { } from "./propertyPanelAutomation"; import type { DomEditSelection } from "./domEditingTypes"; import { useLivePlayheadTime } from "../../hooks/useLivePlayheadTime"; +import { usePlayerStore } from "../../player"; /** * Rate the carve source is decoded at. Analysis is self-consistent because it @@ -199,10 +200,12 @@ export function AudioFxGroup({ * commit, which does not exist yet. */ const setCarve = async (next: HfCarveSettings | null): Promise => { - // Envelopes the carve wrote outlive it otherwise, and an automated gain - // ignores the panel's own depth — so switching dynamic off would leave the - // filters still following the voice with nothing saying they do. - if (!next?.enabled) { + // What the carve generated is only justified by the voices it was measured + // from: switched off, or left naming none — every source deleted, say — + // there is nothing those filters are making room for. Left behind they keep + // dipping the bed with nothing in the panel to explain them. + const generatedOutputStands = Boolean(next?.enabled) && (next?.sources.length ?? 0) > 0; + if (!generatedOutputStands) { const carriedOver = withoutCarveLanes(automation, chain); if (carriedOver.lanes.length !== automation.lanes.length) { await onSetAttributeQuiet( @@ -211,7 +214,7 @@ export function AudioFxGroup({ ); } } - if (!next?.enabled) { + if (!generatedOutputStands) { const kept = chain.nodes.filter((n) => !n.fromCarve); if (kept.length !== chain.nodes.length) { await onSetAttributeQuiet( @@ -300,9 +303,12 @@ export function AudioFxGroup({ * first, and if filtering would leave nothing at all every track comes back. A * picker that hides the track somebody needs is worse than a long one. */ - const sourceOptions: AudioTrackOption[] = (() => { + const { sourceOptions, autoSourceIds } = ((): { + sourceOptions: AudioTrackOption[]; + autoSourceIds: string[]; + } => { const doc = element.element?.ownerDocument; - if (!doc) return []; + if (!doc) return { sourceOptions: [], autoSourceIds: [] }; const others = Array.from(doc.querySelectorAll("audio[id]")).filter( (a) => a.id !== element.id, ); @@ -324,11 +330,75 @@ export function AudioFxGroup({ })); const plausible = described.filter((t) => t.kind === "voice" || t.kind === "unknown"); const offered = plausible.length > 0 ? plausible : described; - return offered - .sort((a, b) => (a.kind === "voice" ? 0 : 1) - (b.kind === "voice" ? 0 : 1)) - .map(({ id, label }) => ({ id, label })); + const byVoiceFirst = (list: typeof described) => + [...list].sort((a, b) => (a.kind === "voice" ? 0 : 1) - (b.kind === "voice" ? 0 : 1)); + return { + sourceOptions: byVoiceFirst(offered).map(({ id, label }) => ({ id, label })), + // What the panel may pick WITHOUT being asked — never the fallback. The + // fallback exists so the picker can still show a track whose name reads as + // music or as an effect, because a name is a hint and the author may know + // better. Choosing off that list is a different act: it is the panel + // deciding, and "the only audio left is a 200 ms explosion" is not a voice + // to make room for. A bed surrounded by nothing plausible waits instead. + autoSourceIds: byVoiceFirst(plausible).map((t) => t.id), + }; })(); + /** + * The voices this carve names that are still in the composition. + * + * Existence, not the candidate list: a voice can stop being offered without + * being gone (it stopped overlapping the bed), and dropping it then would + * quietly rewrite a relationship the author set. Deleted is the case that has + * to be noticed, because what the carve produced was measured from that track. + * + * Asked of the timeline rather than of `element.element.ownerDocument`, which + * is the preview's DOM and outlives a delete: measured in the studio, a bed + * selected right after its voice was deleted still found that voice through + * the document, so the carve sat on a measurement of a track the timeline had + * already dropped. The store is what the delete actually edited. + */ + const timelineElements = usePlayerStore((s) => s.elements); + const survivingSources = ((): string[] => { + if (!carve) return []; + const present = new Set(timelineElements.map((el) => el.domId ?? el.id)); + // Absence only means deletion once the timeline is known to describe THIS + // composition, and the bed being in it is the proof. Without that check a + // store that is empty — not loaded yet, or a panel mounted outside the + // player — reads as "every voice was deleted" and throws away a carve that + // is perfectly fine. Unchanged sources are what the prune treats as nothing + // to do. + if (!element.id || !present.has(element.id)) return carve.sources; + return carve.sources.filter((id) => present.has(id)); + })(); + + /** + * A deleted voice re-analyses the bed. + * + * The filters and envelopes are a measurement of specific tracks, so losing one + * makes them a measurement of something that is no longer there — the bed keeps + * ducking for a voice nobody can hear. `analyse` already skips a source it + * cannot find, but nothing asked it to run again. + * + * Pruning is the whole trigger: `setCarve` re-analyses when the source list + * changes, so the surviving voices are re-measured together. Losing the LAST + * one leaves an empty list, which the effects below repoint at whatever + * candidates remain — and if there are none, `setCarve` drops what the carve + * generated, since there is nothing left it could be making room for. + * + * Keyed on the survivors rather than on the candidates: a voice that had + * stopped overlapping was never in the candidate list, so its deletion would + * not change that identity and this would never fire. + */ + useEffect(() => { + if (carvedAgainstBy || !carve?.enabled) return; + if (survivingSources.length === carve.sources.length) return; + void setCarve({ ...carve, sources: survivingSources }); + // Keyed on the identity of the decision, not on setCarve — which is rebuilt + // every render and would re-fire this. + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [carve, carvedAgainstBy, survivingSources.join(" ")]); + /** * A bed with voices above it carves itself. * @@ -346,14 +416,14 @@ export function AudioFxGroup({ * off stores `enabled: false`, which is also a configured carve. That is the whole * reason the flag exists rather than "off" being an absent attribute. */ - const candidateIds = sourceOptions.map((o) => o.id).join("\u0000"); + const candidateIds = autoSourceIds.join("\u0000"); useEffect(() => { // Exactly one candidate is the sibling effect's case below, not this one's: // both guards passing for a single candidate fired two setCarve calls with // the same result — two decodes, two FFT runs, two concurrent attribute // writes. - if (carvedAgainstBy || sourceOptions.length <= 1) return; - const all = sourceOptions.map((o) => o.id); + if (carvedAgainstBy || autoSourceIds.length <= 1) return; + const all = autoSourceIds; // Nothing configured: the default carve, pointed at everything it could hear. if (carve === null) { void setCarve({ ...DEFAULT_CARVE, sources: all }); @@ -387,24 +457,23 @@ export function AudioFxGroup({ * reason the flag exists rather than "off" being an absent attribute. */ useEffect(() => { - if (carvedAgainstBy || sourceOptions.length !== 1) return; - const only = sourceOptions[0]; + if (carvedAgainstBy || autoSourceIds.length !== 1) return; + const only = autoSourceIds[0]; if (!only) return; // Nothing configured: the default carve, pointed at the one candidate. if (carve === null) { - void setCarve({ ...DEFAULT_CARVE, sources: [only.id] }); + void setCarve({ ...DEFAULT_CARVE, sources: [only] }); return; } // Configured but with no voice yet — a carve switched on before there was // anything to listen to, or one whose source was cleared. The panel reads the // sole candidate out as the source, so it has to be the stored one too; // otherwise the card claims a relationship the attribute does not record. - if (carve.enabled && carve.sources.length === 0) - void setCarve({ ...carve, sources: [only.id] }); + if (carve.enabled && carve.sources.length === 0) void setCarve({ ...carve, sources: [only] }); // Deliberately keyed on the identity of the decision, not on setCarve — which // is rebuilt every render and would re-fire this. // eslint-disable-next-line react-hooks/exhaustive-deps - }, [carve, carvedAgainstBy, sourceOptions.length, sourceOptions[0]?.id]); + }, [carve, carvedAgainstBy, autoSourceIds.length, autoSourceIds[0]]); const [analysing, setAnalysing] = useState(false); diff --git a/packages/studio/src/hooks/useElementLifecycleOps.ts b/packages/studio/src/hooks/useElementLifecycleOps.ts index 3df6bf402..07b98324b 100644 --- a/packages/studio/src/hooks/useElementLifecycleOps.ts +++ b/packages/studio/src/hooks/useElementLifecycleOps.ts @@ -142,6 +142,9 @@ export function useElementLifecycleOps({ kind: "timeline", files: { [targetPath]: patchedContent }, readFile: async () => originalContent, + // remove-element already wrote the removal, so disk holds THAT — not + // the content read at the top. Undo still goes back to the original. + diskContent: { [targetPath]: patchedContent }, writeFile: writeProjectFile, recordEdit: editHistory.recordEdit, }); diff --git a/packages/studio/src/hooks/useTimelineEditing.ts b/packages/studio/src/hooks/useTimelineEditing.ts index 10f0da7de..e8f5ddc9b 100644 --- a/packages/studio/src/hooks/useTimelineEditing.ts +++ b/packages/studio/src/hooks/useTimelineEditing.ts @@ -449,6 +449,9 @@ export function useTimelineEditing({ kind: "timeline", files: { [targetPath]: patchedContent }, readFile: async () => originalContent, + // remove-element already wrote the removal, so disk holds THAT — not the + // content read at the top. Undo still goes back to the original. + diskContent: { [targetPath]: removedContent }, writeFile: writeProjectFile, recordEdit, }); diff --git a/packages/studio/src/player/components/AutomationValueInput.tsx b/packages/studio/src/player/components/AutomationValueInput.tsx index d37559c6a..9dbf5bd74 100644 --- a/packages/studio/src/player/components/AutomationValueInput.tsx +++ b/packages/studio/src/player/components/AutomationValueInput.tsx @@ -28,7 +28,9 @@ export function AutomationValueInput({ }: AutomationValueInputProps) { return ( { // One shared volume row, and BOTH clips hold it open. expectTrackExpansion(row, ["narration-1", "narration-2"], TRACK_H + AUTOMATION_LANE_H); + // Every clip bar on the row is capped to one track height. Only the clip + // owning the property lanes used to be, so its siblings stretched the whole + // expanded row and painted their waveforms over the envelopes below. + expect( + ["narration-1", "narration-2"].map( + (id) => host.querySelector(`[data-el-id="${id}"]`)?.style.height, + ), + ).toEqual([`${TRACK_H - 2 * CLIP_Y}px`, `${TRACK_H - 2 * CLIP_Y}px`]); + act(() => caret()?.click()); expectTrackExpansion(row, [], TRACK_H); act(() => root.unmount()); }); + // The lanes are the row's, and selecting a clip must not rebuild them. They + // used to hang off the active clip's property lanes, so clicking a sibling + // moved the whole subtree into a different element and remounted every lane — + // which threw away each one's hover state and any gesture in flight. Pressing + // a lane to select its clip therefore made the handles vanish under the + // pointer, which is the one gesture the read-only lane exists to support. + it("keeps the automation lanes mounted when the selection moves along the row", () => { + const host = createSizedTimelineHost(720); + const automation = JSON.stringify({ + version: 1, + lanes: [{ target: "volume", points: [{ t: 0, v: 1 }] }], + }); + usePlayerStore.setState({ + duration: 8, + timelineReady: true, + selectedElementId: "narration-2", + elements: [ + { id: "narration-1", tag: "audio", start: 0, duration: 4, track: 0, automation }, + { id: "narration-2", tag: "audio", start: 4, duration: 4, track: 0, automation }, + ], + }); + const root = createRoot(host); + act(() => root.render(React.createElement(Timeline))); + act(() => host.querySelector('button[aria-label$=" keyframes"]')?.click()); + + const before = [...host.querySelectorAll(".hf-automation-lane")]; + expect(before).toHaveLength(2); + + act(() => usePlayerStore.setState({ selectedElementId: "narration-1" })); + + // Identity, not deep equality: a remount produces structurally identical + // nodes, so only `toBe` can tell the two apart. + const after = [...host.querySelectorAll(".hf-automation-lane")]; + expect(after).toHaveLength(before.length); + after.forEach((node, index) => expect(node).toBe(before[index])); + act(() => root.unmount()); + }); + it("marks every clip in selectedElementIds as selected", () => { const host = createSizedTimelineHost(720); diff --git a/packages/studio/src/player/components/TimelineAutomationLane.tsx b/packages/studio/src/player/components/TimelineAutomationLane.tsx index 0340756dc..3e4f5dbf0 100644 --- a/packages/studio/src/player/components/TimelineAutomationLane.tsx +++ b/packages/studio/src/player/components/TimelineAutomationLane.tsx @@ -328,7 +328,12 @@ export function TimelineAutomationLane({ return (
@@ -347,7 +352,7 @@ export function TimelineAutomationLane({ envelope it described and scrolled horizontally away from its own row. */} { @@ -119,7 +118,12 @@ function mountRow(elements: readonly TimelineElement[], selectedKey?: string) { />, ); }); - return [...host.querySelectorAll(".hf-automation-lane")] + return host; +} + +/** Every drawn envelope as `row @ left`, which is the whole claim under test. */ +function mountRow(elements: readonly TimelineElement[], selectedKey?: string) { + return [...renderRow(elements, selectedKey).querySelectorAll(".hf-automation-lane")] .map((lane) => `${lane.style.top} @ ${lane.querySelector("svg")?.style.left}`) .sort(); } @@ -148,6 +152,21 @@ describe("TimelineAutomationLaneSlot shared rows", () => { ]); }); + it("lets each clip's envelope be reached, not just the one drawn last", () => { + // Every clip mounts a band spanning the WHOLE row (the row separator needs + // the full width), so three bands sit on top of each other here. If a band + // took the pointer, the last one rendered would swallow hover and drag over + // its siblings' envelopes — handles appeared only on the final clip, and + // only on rows that a single clip happened to own. + const host = renderRow([narration1, narration2]); + const bands = [...host.querySelectorAll(".hf-automation-lane")]; + expect(bands.length).toBeGreaterThan(1); + for (const band of bands) { + expect(band.className).toContain("pointer-events-none"); + expect(band.querySelector("svg")?.getAttribute("class")).toContain("pointer-events-auto"); + } + }); + it("keeps the same rows whichever clip is selected", () => { // The bug this replaces: the row listed only the selected clip's lanes, so // clicking a sibling swapped which envelopes existed. diff --git a/packages/studio/src/player/components/TimelineLanes.test.tsx b/packages/studio/src/player/components/TimelineLanes.test.tsx index be2179f0e..0fb47204e 100644 --- a/packages/studio/src/player/components/TimelineLanes.test.tsx +++ b/packages/studio/src/player/components/TimelineLanes.test.tsx @@ -232,10 +232,23 @@ describe("TimelineLanes track numbering", () => { describe("TimelineLanes disclosure target", () => { const ANIMATIONS = new Map([["clip-a", [positionTween("clip-a")]]]); - function ariaControlsTarget(host: HTMLElement): HTMLElement | null { + /** + * `aria-controls` is an ID LIST, and the caret needs one: it reveals the + * active clip's keyframe lanes AND the track's automation lanes, which cannot + * be one element — one belongs to a clip, the other to the row. + */ + function ariaControlsIds(host: HTMLElement): string[] { const caret = host.querySelector("button[aria-controls]"); - const id = caret?.getAttribute("aria-controls"); - return id ? host.querySelector(`#${id}`) : null; + return (caret?.getAttribute("aria-controls") ?? "").split(/\s+/).filter(Boolean); + } + + function ariaControlsTargets(host: HTMLElement): (HTMLElement | null)[] { + return ariaControlsIds(host).map((id) => host.querySelector(`#${id}`)); + } + + /** The first region named, which is the keyframe lanes. */ + function ariaControlsTarget(host: HTMLElement): HTMLElement | null { + return ariaControlsTargets(host)[0] ?? null; } // aria-controls used to name a div in the sticky label column: it computed to @@ -246,6 +259,9 @@ describe("TimelineLanes disclosure target", () => { expect(target).not.toBeNull(); expect(target?.querySelectorAll("[data-timeline-property-lane]").length).toBeGreaterThan(0); + // Every region it names has to exist, or the caret points at nothing. + expect(ariaControlsTargets(view.host).length).toBeGreaterThan(1); + expect(ariaControlsTargets(view.host).every(Boolean)).toBe(true); act(() => view.root.unmount()); }); @@ -255,6 +271,9 @@ describe("TimelineLanes disclosure target", () => { expect(target).not.toBeNull(); expect(target?.querySelectorAll("[data-timeline-property-lane]")).toHaveLength(0); + // Including the automation region, which is mounted empty while collapsed + // for exactly this reason. + expect(ariaControlsTargets(view.host).every(Boolean)).toBe(true); act(() => view.root.unmount()); }); @@ -266,8 +285,8 @@ describe("TimelineLanes disclosure target", () => { const second = renderLanes({ animations: ANIMATIONS, expandedClipIds: ["clip-a"] }); const idsFor = (host: HTMLElement) => - Array.from(host.querySelectorAll("button[aria-controls]")).map((caret) => - caret.getAttribute("aria-controls"), + Array.from(host.querySelectorAll("button[aria-controls]")).flatMap((caret) => + (caret.getAttribute("aria-controls") ?? "").split(/\s+/).filter(Boolean), ); const firstIds = idsFor(first.host); const secondIds = idsFor(second.host); diff --git a/packages/studio/src/player/components/TimelineLanes.tsx b/packages/studio/src/player/components/TimelineLanes.tsx index b037a9f71..d0993d81f 100644 --- a/packages/studio/src/player/components/TimelineLanes.tsx +++ b/packages/studio/src/player/components/TimelineLanes.tsx @@ -209,6 +209,12 @@ export function TimelineLanes({ ); const keyframeClipKey = keyframeClip?.key ?? keyframeClip?.id; const rowExpanded = isTrackRowExpanded(els, expandedClipIds); + // How tall a clip BAR is drawn. An expanded row is mostly lanes, and a + // clip left to fill it painted its waveform straight over them — so the + // bar is capped for every clip on the row, not just the one whose + // property lanes are showing. Undefined means "fill the row", which is + // right only while it is collapsed and the row is nothing but bar. + const clipBarHeight = rowExpanded ? TRACK_H - 2 * CLIP_Y : undefined; // The clips whose envelopes this row draws, at their dragged positions. // Once per row, not once per clip in the map below. const automationElements = els.map(getPreviewElement); @@ -217,6 +223,10 @@ export function TimelineLanes({ // on the canvas. Keyed by display row, not by `trackNum`, which is a // fractional sort key and would mint ids like `...-0.16666666666666666`. const lanesId = `${lanesIdPrefix}-track-${row}`; + // The caret reveals two canvas regions now: the active clip's keyframe + // lanes and the track's automation lanes. They cannot be one element — + // one belongs to a clip, the other to the row — so the caret names both. + const automationLanesId = `${lanesId}-automation`; // The header's remove buttons write through the same binding the lanes // themselves edit through, so a deletion persists exactly like dragging // a point does — and the binding reports read-only for an unselected @@ -245,6 +255,7 @@ export function TimelineLanes({ logicalRow={logicalRow} propertyRows={trackLogicalRows.slice(1)} lanesId={lanesId} + headerLanesId={`${lanesId} ${automationLanesId}`} top={rowGeometry.getRowTop(row)} height={rowHeight} virtualized={rowsVirtualized} @@ -263,7 +274,7 @@ export function TimelineLanes({ els[0]?.id ?? `Track${trackDisplaySuffix(displayNumber)}` } - lanesId={lanesId} + lanesId={`${lanesId} ${automationLanesId}`} contentOrigin={contentOrigin} keyframeClip={keyframeClip} trackElements={els} @@ -411,7 +422,7 @@ export function TimelineLanes({ el={previewElement} pps={pps} clipY={CLIP_Y} - clipHeight={showsLanes ? TRACK_H - 2 * CLIP_Y : undefined} + clipHeight={clipBarHeight} isSelected={isSelected} isHovered={hoveredClip === clipKey} isDragging={false} @@ -503,25 +514,6 @@ export function TimelineLanes({ Promise.resolve(false) } suppressClickRef={suppressClickRef} - footer={ - showsLanes ? ( - // Every clip on the row, not this one: the lanes are - // the TRACK's, one row per automated property. - { - const key = getTimelineElementIdentity(element); - return selectedElementId === key || selectedElementIds.has(key); - }} - lanes={automationLanes} - pps={pps} - laneCount={laneCounts.get(elementKey) ?? 0} - accentColor={clipStyle.accent} - currentTime={currentTime} - beatTimes={beatAnalysis?.beatTimes} - /> - ) : null - } /> ); @@ -556,6 +548,36 @@ export function TimelineLanes({ ); }) } + {/* The automation lanes belong to the ROW, so they are mounted + here rather than under the active clip's property lanes. + Hanging off that clip meant selecting a sibling moved the + whole subtree into a different clip's element and remounted + every lane — which threw away each lane's hover state (and + any gesture mid-flight), so pressing a lane to select its + clip made the handles you were reaching for disappear. + + Mounted in BOTH disclosure states, empty while collapsed, so + the caret's aria-controls resolves either way — same reason + the keyframe lanes are. Absolute positions inside resolve + against this same relative row, so the geometry is unchanged + by the move. */} +
+ {rowExpanded ? ( + { + const key = getTimelineElementIdentity(element); + return selectedElementId === key || selectedElementIds.has(key); + }} + lanes={automationLanes} + pps={pps} + laneCount={keyframeClipKey ? (laneCounts.get(keyframeClipKey) ?? 0) : 0} + accentColor={getTrackStyle(keyframeClip?.tag ?? "").accent} + currentTime={currentTime} + beatTimes={beatAnalysis?.beatTimes} + /> + ) : null} +
); diff --git a/packages/studio/src/player/components/TimelinePropertyLanes.tsx b/packages/studio/src/player/components/TimelinePropertyLanes.tsx index 7366d3213..31dd97962 100644 --- a/packages/studio/src/player/components/TimelinePropertyLanes.tsx +++ b/packages/studio/src/player/components/TimelinePropertyLanes.tsx @@ -1,4 +1,4 @@ -import { useMemo, type MouseEvent as ReactMouseEvent, type ReactNode, type RefObject } from "react"; +import { useMemo, type MouseEvent as ReactMouseEvent, type RefObject } from "react"; import { classifyPropertyGroup, type GsapAnimation, @@ -35,12 +35,6 @@ export interface TimelinePropertyLanesProps { onContextMenuKeyframe?: (e: ReactMouseEvent, target: TimelineKeyframeTarget) => void; onMoveKeyframe?: (target: TimelineKeyframeTarget, toClipPercentage: number) => Promise; suppressClickRef?: RefObject; - /** - * Rendered after the keyframe lanes, inside this wrapper. An audio clip's - * automation lane lives here so it shares the same disclosure — and so the - * header caret's `aria-controls` covers it too. - */ - footer?: ReactNode; } /** @@ -202,7 +196,6 @@ export function TimelinePropertyLanes({ onContextMenuKeyframe, onMoveKeyframe, suppressClickRef, - footer, }: TimelinePropertyLanesProps) { // Memoized: TimelineDiamondLane is React.memo'd, and rebuilding the lanes (and // a fresh keyframesData literal per lane) on every render would re-render every @@ -270,7 +263,6 @@ export function TimelinePropertyLanes({ /> ))} - {footer} ); } diff --git a/packages/studio/src/player/components/TimelineTrackHeader.tsx b/packages/studio/src/player/components/TimelineTrackHeader.tsx index 7244d717a..3d043fbd1 100644 --- a/packages/studio/src/player/components/TimelineTrackHeader.tsx +++ b/packages/studio/src/player/components/TimelineTrackHeader.tsx @@ -30,8 +30,11 @@ interface TimelineTrackHeaderProps { * from the label rather than inventing one (see trackDisplayNumber). */ trackDisplayNumber: number | null; trackLabel: string; - /** Id of the canvas-side lanes element the disclosure caret expands. Minted by - * TimelineLanes, which is the one place that sees both subtrees. */ + /** Ids of the canvas-side lane regions the disclosure caret expands, space + * separated as `aria-controls` takes them: the active clip's keyframe lanes + * and the track's automation lanes are separate elements, one owned by a + * clip and one by the row. Minted by TimelineLanes, the one place that sees + * every subtree. */ lanesId: string; contentOrigin: number; /** The track's active keyframe clip (selected, else primary) — the one whose diff --git a/packages/studio/src/player/components/TimelineTrackRow.tsx b/packages/studio/src/player/components/TimelineTrackRow.tsx index d360edb20..6eb22131c 100644 --- a/packages/studio/src/player/components/TimelineTrackRow.tsx +++ b/packages/studio/src/player/components/TimelineTrackRow.tsx @@ -7,7 +7,13 @@ interface TimelineTrackRowProps { rowKey: number; logicalRow: TimelineLogicalRow; propertyRows: readonly TimelineLogicalRow[]; + /** Names the canvas-side content cell — the active clip's own property lanes, + * minted with this single id in TimelinePropertyLanes. */ lanesId: string; + /** Names the header cell. Space-separated because the caret it lives under + * expands two disjoint subtrees (the clip's keyframe lanes AND the track's + * automation lanes) — see TimelineTrackHeader for why they cannot share one id. */ + headerLanesId: string; top: number; height: number; virtualized: boolean; @@ -24,6 +30,7 @@ export function TimelineTrackRow({ logicalRow, propertyRows, lanesId, + headerLanesId, top, height, virtualized, @@ -78,7 +85,7 @@ export function TimelineTrackRow({
{group}
diff --git a/packages/studio/src/utils/studioFileHistory.test.ts b/packages/studio/src/utils/studioFileHistory.test.ts index f909bd3db..8965e3881 100644 --- a/packages/studio/src/utils/studioFileHistory.test.ts +++ b/packages/studio/src/utils/studioFileHistory.test.ts @@ -29,6 +29,55 @@ describe("saveProjectFilesWithHistory", () => { }); }); + /** + * Deleting a clip POSTs `remove-element`, which rewrites the file server-side, + * and only then saves the duration shrink. Expecting the content read before + * the mutation made the server refuse that write as a conflict: the save queue + * paused on the 409 and the clip stayed on the timeline until a reload. + */ + it("expects what is on disk, not the undo baseline, when they differ", async () => { + const expectations: Record = {}; + const recordEdit = vi.fn(); + + await saveProjectFilesWithHistory({ + projectId: "project-1", + label: "Delete timeline clip", + kind: "timeline", + files: { "index.html": "removed+shrunk" }, + readFile: async () => "original", + diskContent: { "index.html": "removed" }, + writeFile: async (path, _content, expectedContent) => { + expectations[path] = expectedContent; + }, + recordEdit, + }); + + expect(expectations["index.html"]).toBe("removed"); + // Undo still goes all the way back, which is the whole reason the two are + // allowed to differ. + expect(recordEdit).toHaveBeenCalledWith( + expect.objectContaining({ + files: { "index.html": { before: "original", after: "removed+shrunk" } }, + }), + ); + }); + + it("still expects the undo baseline when nothing says otherwise", async () => { + const expectations: Record = {}; + await saveProjectFilesWithHistory({ + projectId: "project-1", + label: "Move layer", + kind: "manual", + files: { "index.html": "after" }, + readFile: async () => "before", + writeFile: async (path, _content, expectedContent) => { + expectations[path] = expectedContent; + }, + recordEdit: vi.fn(), + }); + expect(expectations["index.html"]).toBe("before"); + }); + it("skips writes and history for unchanged content", async () => { const writeFile = vi.fn(); const recordEdit = vi.fn(); diff --git a/packages/studio/src/utils/studioFileHistory.ts b/packages/studio/src/utils/studioFileHistory.ts index 19d4f6729..c055cb870 100644 --- a/packages/studio/src/utils/studioFileHistory.ts +++ b/packages/studio/src/utils/studioFileHistory.ts @@ -34,6 +34,21 @@ interface SaveProjectFilesWithHistoryInput { readFile: (path: string) => Promise; writeFile: ProjectFileWriter; recordEdit: (entry: RecordEditInput) => Promise; + /** + * What a path holds ON DISK right now, when that is not the same as the + * history's "before". + * + * The two are normally one value, so the write's optimistic-concurrency + * expectation was taken straight from the undo baseline. They come apart when + * a server-side mutation has already written part of the edit: deleting a clip + * POSTs `remove-element`, which rewrites the file, and only then saves the + * duration shrink — expecting the pre-delete content it read at the start. The + * server had moved the file on, so the write was refused as a conflict, the + * save queue paused, and the clip stayed on the timeline until a reload. + * + * Undo still restores `before`; this only says what to expect on disk. + */ + diskContent?: Record; } export async function readProjectFileContent(pid: string, path: string): Promise { @@ -57,6 +72,7 @@ export async function saveProjectFilesWithHistory({ readFile, writeFile, recordEdit, + diskContent, }: SaveProjectFilesWithHistoryInput): Promise { return serializeStudioFileMutations(writeFile, Object.keys(files), async () => { const snapshots: Record = {}; @@ -73,7 +89,7 @@ export async function saveProjectFilesWithHistory({ const writtenPaths: string[] = []; try { for (const path of changedPaths) { - await writeFile(path, snapshots[path].after, snapshots[path].before); + await writeFile(path, snapshots[path].after, diskContent?.[path] ?? snapshots[path].before); writtenPaths.push(path); } diff --git a/plans/audio-automation-lanes/SPEC.md b/plans/audio-automation-lanes/SPEC.md new file mode 100644 index 000000000..628d727ce --- /dev/null +++ b/plans/audio-automation-lanes/SPEC.md @@ -0,0 +1,255 @@ +# Audio automation lanes + +Breakpoint envelopes on audio tracks, edited in the timeline the way Ableton +Live edits arrangement automation: expand a lane under the track, pick a +parameter, click to add points, drag to shape. Applies to track volume and to +FX-chain parameters. + +Status: SPEC — not implemented. Builds on the `wa-*` Web Audio FX stack. + +--- + +## 1. Why this shape + +Two facts make this cheaper here than in most editors: + +1. **Web Audio has native envelope playback.** `AudioParam` scheduling + (`linearRampToValueAtTime`, `setValueCurveAtTime`) is sample-accurate and + runs on the audio thread. No per-frame JS evaluates the envelope; the studio + only *schedules* it. +2. **Preview and render share one graph.** The render runs the same builders in + an `OfflineAudioContext`, so an envelope scheduled the same way in both + places is identical by construction. No parity harness needed. + +And one fact makes the UI cheap: the FX registry already declares `min` / +`max` / `step` / `unit` / `scale` for every parameter. A lane's y-axis, +clamping, and log/linear mapping are read from the registry — the lane +component knows nothing about any specific effect (same principle as the +panel). + +## 2. What exists today (grounding) + +- **Static volume**: `data-volume` on the element; baseline gain. +- **GSAP volume tweens**: `tl.to("#bgm", { volume: 0 })` — probed at 60 Hz into + `volumeKeyframes`, applied in preview via `interpolateVolumeGain` + (`runtime/media.ts`) and baked into PCM at render via + `applyVolumeEnvelopeToWav` (sample-accurate) with an ffmpeg-expression + fallback (`MAX_VOLUME_SEGMENTS = 32`). +- **FX chains**: `data-fx-chain` serialised on the element; transport splices + the graph between decoded source and gain (`attachElementFxChain`); render + runs the same graph offline. Worklet params are set via `port.postMessage`, + **not** AudioParams. +- **Transport scheduling**: sources are (re)scheduled on play, seek, and rate + change (`scheduleWebAudioForActiveClips`), started with an `elapsed` offset + into the buffer. Envelope scheduling piggybacks on exactly these moments. +- **Timeline lanes**: `TimelineLanes.tsx` renders track rows; + `TimelinePropertyLanes.tsx` is the keyframe-lane precedent; + `AudioWaveform.tsx` already draws the waveform the envelope will sit over. +- **Edit plumbing**: `onSetAttributeLive` (coalesced, no preview refresh) for + drags; `onSetAttribute` persists on gesture end. Proven by the wa-8 fix. + +## 3. UX spec (Ableton mapping) + +| Ableton | Here | +| --- | --- | +| Automation triangle on track header | Expand toggle on audio track rows in the timeline gutter | +| One parameter per lane, selector at lane left | Same. Selector lists `Volume` + every automatable param of every chain node (`Compressor · Threshold`) | +| Breakpoint envelope over the clip | SVG envelope drawn over the existing waveform, clip-local | +| Double-click segment → add point | Same | +| Drag point (value tooltip) | Same; tooltip shows value + unit from the registry | +| Drag segment vertically → bend curvature | Same (Phase 2; format supports it from v1) | +| Delete key / right-click → remove point | Same | +| Dimmed line when no automation | Flat line at the current static value; first edit creates the lane | + +Lane height ~48 px expanded. Multiple lanes per track may be open at once +(one per parameter), matching Ableton's "+" lanes — Phase 2; V1 shows one lane +per track with the selector. + +**Editing writes:** point drags go through `onSetAttributeLive`; release +persists via `onSetAttribute`. The running graph follows the attribute (wa-8 +observer), so edits are audible without a reload. Undo = attribute history, +coalesced per gesture — free. + +## 4. Data model + +Serialised on the element, versioned, same pattern as `data-fx-chain`: + +```html +