fix(studio): the shared-row follow-ups (#3215)

* 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com>
2026-09-05 00:56:23 +00:00 · 2026-08-13 03:16:35 -07:00
parent 9b18fa7a26
commit df57ad4bac
18 changed files with 913 additions and 71 deletions
@@ -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(
+        <AudioFxGroup
+          element={
+            {
+              dataAttributes: {
+                "fx-carve": carve,
+                "fx-chain": CARVED_CHAIN,
+                automation: CARVED_AUTOMATION,
+              },
+              id: "bed",
+              element: bed,
+            } as unknown as DomEditSelection
+          }
+          onSetAttributeQuiet={onSetAttributeQuiet}
+          onSetAttributeLive={vi.fn()}
+        />,
+      );
+    });
+    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(
+        <AudioFxGroup
+          element={
+            {
+              dataAttributes: { "fx-carve": carve },
+              id: "bed",
+              element: bed,
+            } as unknown as DomEditSelection
+          }
+          onSetAttributeQuiet={onSetAttributeQuiet}
+          onSetAttributeLive={vi.fn()}
+        />,
+      );
+    });
+    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"]);
+  });
+});
@@ -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<void> => {
-    // 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<HTMLAudioElement>("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);

@@ -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,
        });
@@ -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,
          });
@@ -28,7 +28,9 @@ export function AutomationValueInput({
 }: AutomationValueInputProps) {
  return (
    <input
-      className="hf-automation-value absolute rounded-[3px] border border-panel-border-input bg-panel-bg-2 px-1 font-mono text-[9px] text-panel-text-1"
+      // pointer-events-auto: the lane band around it takes none, so that clips
+      // sharing the row do not cover each other's envelopes (see the lane).
+      className="hf-automation-value pointer-events-auto absolute rounded-[3px] border border-panel-border-input bg-panel-bg-2 px-1 font-mono text-[9px] text-panel-text-1"
      style={{ left: leftPx, top: 1, width: 44, zIndex: 4 }}
      // The lane is a pointer surface, and the timeline above it owns single-key
      // shortcuts. Without stopping both, a press lands on the lane instead of
@@ -610,11 +610,58 @@ describe("Timeline provider boundary", () => {
    // 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<HTMLElement>(`[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<HTMLButtonElement>('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);

@@ -328,7 +328,12 @@ export function TimelineAutomationLane({

  return (
    <div
-      className="hf-automation-lane absolute"
+      // Spans the whole row so the separator below can, but takes no pointer
+      // events itself: clips sharing a row each mount one of these over the
+      // full width, so a band that accepted the pointer would let whichever
+      // clip rendered last swallow every sibling's envelope — hover, drag and
+      // all. Only the drawn parts opt back in.
+      className="hf-automation-lane pointer-events-none absolute"
      style={{ top: topPx, left: 0, right: 0, height: h }}
      data-automation-lane={target}
    >
@@ -347,7 +352,7 @@ export function TimelineAutomationLane({
          envelope it described and scrolled horizontally away from its own row. */}
      <svg
        ref={svgRef}
-        className="hf-automation-svg absolute"
+        className="hf-automation-svg pointer-events-auto absolute"
        style={{
          left: leftPx - PAD_X,
          top: 0,
@@ -102,8 +102,7 @@ const readingBind = (element: TimelineElement, isSelected: boolean): AutomationL
  onRangeClear: vi.fn(),
 });

-/** Every drawn envelope as `row @ left`, which is the whole claim under test. */
-function mountRow(elements: readonly TimelineElement[], selectedKey?: string) {
+function renderRow(elements: readonly TimelineElement[], selectedKey?: string): HTMLElement {
  const host = document.createElement("div");
  document.body.append(host);
  act(() => {
@@ -119,7 +118,12 @@ function mountRow(elements: readonly TimelineElement[], selectedKey?: string) {
      />,
    );
  });
-  return [...host.querySelectorAll<HTMLElement>(".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<HTMLElement>(".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<HTMLElement>(".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.
@@ -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<HTMLElement>(`#${id}`) : null;
+    return (caret?.getAttribute("aria-controls") ?? "").split(/\s+/).filter(Boolean);
+  }
+
+  function ariaControlsTargets(host: HTMLElement): (HTMLElement | null)[] {
+    return ariaControlsIds(host).map((id) => host.querySelector<HTMLElement>(`#${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);
@@ -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.
-                            <TimelineAutomationLaneSlot
-                              elements={automationElements}
-                              isSelected={(element) => {
-                                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. */}
+                <div id={automationLanesId}>
+                  {rowExpanded ? (
+                    <TimelineAutomationLaneSlot
+                      elements={automationElements}
+                      isSelected={(element) => {
+                        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}
+                </div>
              </div>
            </TimelineTrackRow>
          );
@@ -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<boolean>;
  suppressClickRef?: RefObject<boolean>;
-  /**
-   * 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({
          />
        </div>
      ))}
-      {footer}
    </div>
  );
 }
@@ -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
@@ -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({
            <div
              role="rowheader"
              aria-colindex={1}
-              aria-owns={timelineLogicalRowCellId(lanesId, row.id, "header")}
+              aria-owns={timelineLogicalRowCellId(headerLanesId, row.id, "header")}
            >
              {group}
            </div>
@@ -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<string, string | undefined> = {};
+    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<string, string | undefined> = {};
+    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();
@@ -34,6 +34,21 @@ interface SaveProjectFilesWithHistoryInput {
  readFile: (path: string) => Promise<string>;
  writeFile: ProjectFileWriter;
  recordEdit: (entry: RecordEditInput) => Promise<void>;
+  /**
+   * 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<string, string>;
 }

 export async function readProjectFileContent(pid: string, path: string): Promise<string> {
@@ -57,6 +72,7 @@ export async function saveProjectFilesWithHistory({
  readFile,
  writeFile,
  recordEdit,
+  diskContent,
 }: SaveProjectFilesWithHistoryInput): Promise<string[]> {
  return serializeStudioFileMutations(writeFile, Object.keys(files), async () => {
    const snapshots: Record<string, { before: string; after: string }> = {};
@@ -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);
      }

@@ -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
+<audio id="music" src="..." data-volume="0.55"
+  data-fx-chain='{"version":1,"nodes":[{"id":"n1","type":"peaking",...}]}'
+  data-automation='{
+    "version": 1,
+    "lanes": [
+      { "target": "volume",
+        "points": [ {"t":0,"v":0.55}, {"t":2.5,"v":0.2,"curve":-0.4}, {"t":6,"v":0.55} ] },
+      { "target": "fx.n1.frequency",
+        "points": [ {"t":0,"v":200}, {"t":4,"v":8000} ] }
+    ]
+  }'>
+```
+
+- **`t`** — seconds, **clip-local** (relative to the element's `data-start`).
+  The attribute lives on the element, so automation travels with the clip when
+  it moves. (Ableton note: arrangement automation stays put when clips move;
+  clip envelopes travel. We are the clip-envelope model. Stated, not hidden.)
+- **`v`** — value in the parameter's own unit as declared in the registry
+  (dB for a compressor threshold, Hz for a cutoff). Volume is **linear 0..1**,
+  consistent with `data-volume` and the existing linear-domain envelope
+  machinery — no dB conversion enters the volume path.
+- **`curve`** — optional, `-1..1`, curvature of the segment *leaving* this
+  point. `0`/absent = linear. Power-curve bend, Ableton-style.
+- **`target`** — `"volume"` or `"fx.<nodeId>.<paramKey>"`.
+
+**Chain node ids.** `HfAudioFxNode` gains an optional `id` (short random,
+minted by the panel when a node is added). Automation addresses nodes by id,
+so reordering the chain never re-targets a lane. Chains without ids stay
+valid — they just can't be automation targets until the panel touches them.
+
+**Normalization** (`normalizeAutomation`, mirrors `normalizeAudioFxParams`):
+- points sorted by `t`; duplicate `t` keeps the later point
+- `v` clamped to the target's registry range; non-finite → point dropped
+- lanes targeting a node id that no longer exists in the chain are **dropped**
+  (the author deleted the device; its automation dies with it — panel also
+  removes them eagerly on node delete)
+- 1-point lane = constant; empty lanes array = attribute removed
+
+**Precedence for volume** (documented + linted):
+`data-automation` volume lane → GSAP volume tween → `data-volume`.
+New lint rule `audio_volume_double_automation` (warning) when an element has
+both a volume lane and a GSAP tween on `volume`.
+
+## 5. Interpolation semantics
+
+- Between points: linear in the parameter's **working domain**. Params with
+  registry `scale: "log"` (frequency, some times) interpolate in log domain —
+  a 200 Hz → 8 kHz sweep is perceptually linear, matching what a DAW does.
+- `curve` bends the segment: `f(x) = x^(2^(k·s))` shaping applied in the
+  working domain (s = curve, k ≈ 2). Exact constant chosen to visually match
+  Ableton's feel; pinned by unit tests once chosen.
+- Before the first point: hold first value. After the last: hold last value.
+- One shared implementation `sampleAutomationLane(lane, t)` in core — used by
+  the lane renderer (drawing), the scheduler (curve sampling), and the render
+  path. One interpolator, three consumers, or preview and picture drift.
+
+## 6. Preview architecture
+
+Scheduling hooks into `schedulePlayback` (transport), which already runs on
+play / seek / rate change with the clip's `elapsed` offset:
+
+- **Volume lane** → scheduled on the source's existing `gainNode.gain`
+  (post-FX, i.e. fader semantics — matches Ableton, matches the render order
+  where FX runs before the volume bake).
+- **FX param lanes** → scheduled on AudioParams exposed by the graph builders
+  (§8) of the chain instance spliced for this source.
+
+Mechanics per lane, at schedule time:
+1. Convert clip-local envelope → context-time segments starting at
+   `scheduledAt`, offset by `elapsed`, scaled by playback rate.
+2. Linear segments → `setValueAtTime` + `linearRampToValueAtTime` (log-domain
+   params ramp via sampled curve, below).
+3. Curved or log-domain segments → `setValueCurveAtTime` with the segment
+   sampled at 100 pts/s (min 8 per segment).
+4. On stop/dispose → `cancelScheduledValues` before the nodes disconnect.
+
+**Live edit while playing:** the wa-8 attribute observer already re-parameterises
+the running chain. Extend it: on an automation change, `cancelScheduledValues`
+from `currentTime` and re-schedule the remainder. Point drags are audible
+mid-playback without rescheduling the source.
+
+## 7. Render architecture
+
+- **Volume lane**: sampled into the `volumeKeyframes` shape (dense linear
+  points for curved segments, ~20/segment) and fed to the existing
+  `applyVolumeEnvelopeToWav` PCM bake. Zero new render machinery; existing
+  order (FX → volume bake) already matches fader-post-FX semantics.
+- **FX param lanes**: the injectable audio-fx runtime entry
+  (`audio-fx-runtime-entry.ts`) grows an `automation` argument; it schedules
+  lanes on the offline graph exactly as §6 does on the live one. The engine
+  passes the element's `data-automation` through `applyAudioFxChain`.
+- Parity is structural (same interpolator, same scheduler code path), but one
+  fixture test renders a swept filter offline and asserts the sweep landed
+  (spectral check at two timestamps) so a regression is loud.
+
+## 8. Registry & graph-builder changes
+
+- `HfAudioFxNumberParam` gains `automatable?: boolean`.
+- `FxNodeHandle` gains `params?: Record<string, AudioParam>` — each builder
+  exposes the AudioParams backing its automatable params.
+- **Invariant test**: for every registry param with `automatable: true`, the
+  built node exposes a matching AudioParam. The flag can never lie.
+
+**Automatable in V1** (param maps to a real AudioParam):
+
+| Effect | Params |
+| --- | --- |
+| Peaking / shelves | frequency, gain, Q |
+| High/low-pass (2-pole) | frequency, Q |
+| Delay | time (delayTime), feedback, mix |
+| Chorus | rate, depth, mix |
+| Phaser | rate, wet/dry gains |
+| Reverb | wet, dry |
+| *Volume* | (transport gainNode) |
+
+**Not automatable in V1**, greyed out in the selector, with reasons:
+- **Worklet effects** (compressor, limiter, gate, bitcrush): params travel by
+  `postMessage`, not AudioParams. V2 path: declare
+  `parameterDescriptors` in the processors and read `parameters` in
+  `process()` — mechanical but touches every processor; separate PR.
+- **Saturation** type/threshold: a WaveShaper curve is not an AudioParam.
+- **Reverb size/damping**: changing them regenerates the IR; not continuously
+  automatable by construction. Output gain via post-node possible later.
+- **1-pole filter frequency**: IIRFilterNode coefficients are immutable.
+
+## 9. Studio UI components
+
+- `TimelineAutomationLane.tsx` — SVG envelope over `AudioWaveform`, driven by
+  registry metadata (range/scale/unit). Hit-testing, point drag with tooltip,
+  double-click add, right-click/Delete remove.
+- Track header expand toggle + param selector (grouped: Volume, then per
+  chain node by label).
+- `TimelineElement` (playerStore) gains a parsed `automation?` summary the
+  same way it carries `volumeKeyframes`, populated at manifest translation.
+- Orphan handling: deleting a chain node in the panel deletes its lanes in the
+  same attribute write (atomic — both live in element attributes).
+
+## 10. Edge cases
+
+- Clip trimmed shorter than envelope: points beyond `data-duration` are kept
+  in data, drawn dimmed, inert at playback (hold-last stops at clip end).
+- Clip start moved: clip-local times mean the envelope moves with it. This is
+  the chosen semantic, not an accident.
+- `data-playback-rate` ≠ 1: envelope times are clip-timeline seconds; the
+  scheduler divides by rate when mapping to context time (same as the buffer).
+- Unreadable `data-automation`: preview plays without it (dry-not-silent
+  philosophy); render **fails loudly** (same split as chains — plausible-but-
+  wrong renders are the worst outcome).
+- Element with automation but no chain: volume lane still valid.
+
+## 11. PR breakdown (all < 1000 LOC)
+
+| PR | Scope | Est. LOC |
+| --- | --- | --- |
+| A `wa-10-automation-model` | core: types, parse/normalize/serialize, `sampleAutomationLane`, curvature math, chain node ids, lint rule | ~450 |
+| B `wa-11-param-exposure` | core: `automatable` flags, `FxNodeHandle.params`, invariant test | ~350 |
+| C `wa-12-preview-scheduling` | core: transport + attach-path scheduling, cancel/re-schedule on live edit | ~400 |
+| D `wa-13-render-scheduling` | core/engine: offline scheduling in runtime entry, volume→bake bridge, sweep fixture test | ~350 |
+| E `wa-14-lane-ui` | studio: lane component, expand toggle, selector, point editing, orphan cleanup | ~800 |
+| F `wa-15-curvature` (Phase 2) | studio: segment-bend drag; worklet `parameterDescriptors` migration | ~300+ |
+
+A→B→C→D are dependency-ordered; E needs A+B (draws and writes) and benefits
+from C (audible while editing). F is optional polish.
+
+## 12. Open questions (need a call before building)
+
+1. **Volume lane display unit** — data stays linear either way; show the axis
+   as % (matches `data-volume`) or dB (matches DAW muscle memory)?
+   *Default if unanswered: %.*
+2. **Curvature in V1?** Format supports it from day one regardless. Building
+   the bend-drag in V1 adds ~2 days to E. *Default: defer to F, straight lines
+   first.*
+3. **Worklet-param automation deferral acceptable?** Compressor threshold
+   automation is the notable absence. *Default: defer; it's a self-contained
+   follow-up.*
+4. **Clip-envelope semantics confirmed?** Automation travels with the clip.
+   If you expected Ableton *arrangement* behaviour (stays put), say so now —
+   it changes the data model (composition-global times, stored off-element).
@@ -1,6 +1,6 @@
 # Shared automation lane rows on a track

-Decision taken 2026-08-07. Not yet implemented.
+Decision taken 2026-08-07. Implemented in `1e21d763b`.

 ## The bug

@@ -43,7 +43,7 @@ its own row.
  selection moves.
 - **Gestures stay per clip.** Each clip keeps its own SVG, its own
  `useAutomationLaneGestures`, and its own selection box; a shared row is a shared
-  *lane track*, not a shared envelope. Two clips' envelopes in one row must not be
+  _lane track_, not a shared envelope. Two clips' envelopes in one row must not be
  draggable as one thing.
 - **Row height** is `AUTOMATION_LANE_H` per grouped lane, not per clip-lane, so
  `getTimelineLaneTop` and the header's row positions follow the grouped count.
@@ -53,6 +53,6 @@ its own row.

 ## Worth deciding while implementing

-A clip on the row that does *not* automate a grouped property has empty space in
+A clip on the row that does _not_ automate a grouped property has empty space in
 that row. Leave it empty (the envelope is simply absent there) rather than drawing a
 flat line at the stored value — a flat line would claim an envelope exists.
@@ -0,0 +1,174 @@
+# Automation lane time selection — design
+
+2026-08-05 · builds on stack #3027 (wa-1 … wa-14) · status: approved, awaiting implementation plan
+
+## Context
+
+Audio automation lanes (breakpoint envelopes over `data-automation`) ship point-level
+editing: add, drag, curve, snap, type a value, delete one point. Everything range-shaped —
+"fade the music here", "duck this under the voiceover", "reuse that swell" — still means
+placing points one at a time. Ableton's envelope editor solves this with a time selection;
+this design ports the useful subset for video authors. Explicitly not a DAW: no musical
+LFO features, no automation recording, no unlinked/looped envelopes.
+
+## Goals
+
+- Select a time range on one lane by dragging its background.
+- Delete the points in a range without disturbing the envelope outside it.
+- Insert simple shapes (ramp up, ramp down, swell, dip) into a range in one action.
+- Copy a range and paste it elsewhere — other time, other lane, other parameter.
+- Retime a range by dragging its edges.
+- Thin dense point runs (Simplify).
+
+## Non-goals
+
+- Multi-lane or multi-clip selection. One selection, one lane.
+- Vertical scaling and skew of a selection.
+- Draw mode, automation recording, ADSR/waveform shapes (saw, square).
+- Persisting the selection. It is view state, never serialized.
+
+## Model
+
+New store slice `automationSelectionSlice.ts` (own file — `playerStore.ts` sits at the
+600-line ceiling; `keyframeSlice.ts` is the precedent):
+
+```ts
+interface AutomationSelection {
+  elementKey: string; // which clip
+  target: string;     // which lane ("volume" | "fx.<nodeId>.<param>")
+  t0: number;         // clip-local seconds
+  t1: number;         // > t0
+}
+// automationSelection: AutomationSelection | null
+// setAutomationSelection(sel), clearAutomationSelection()
+```
+
+Why a slice and not lane-local state: Delete/Cmd+C/V handlers and the shape context menu
+live outside the lane component and need to read the active selection —
+`useKeyframeKeyboard` already solved this exact problem by going through the store.
+
+Lifecycle: cleared on Escape, on a sub-threshold click in any lane, and automatically when
+the element or target it names stops resolving (clip deleted, effect removed). The lane
+receives it through `bind()` in `useAutomationLanes` like every other prop.
+
+## Gesture
+
+A plain drag on the lane background range-selects. This surface is free: today a
+pointerdown that misses every point and has no Alt falls through and does nothing.
+
+- Pointerdown (no point hit, no Alt): arm at `t`, capture the pointer.
+- Move past ~3 px horizontally: live-update the selection (`t0`/`t1` ordered, clamped to
+  `[0, duration]`). Endpoints snap to the same beat-grid + neighbour-point targets a point
+  drag uses; Alt bypasses, matching the point-drag convention.
+- Pointerup under the threshold: clear the selection (it was a click, not a drag).
+
+Renders as a translucent accent rect behind the envelope path with faint vertical edges.
+Existing gestures unchanged: point hits win over range-drag; Alt on the line still curves.
+Implemented as a third gesture kind in `useAutomationLaneGestures` beside point-drag and
+curve-drag.
+
+## Range ops
+
+Pure module `automationLaneSelection.ts` (studio, not core — the render never needs any of
+this; core keeps only the envelope model it already has):
+
+```ts
+pointsIn(lane, t0, t1): HfAutomationPoint[]
+replaceRange(lane, range, t0, t1, inner: HfAutomationPoint[]): HfAutomationLane
+```
+
+`replaceRange` is the only mutator, and carries THE invariant: **the envelope outside the
+selection never moves.** It samples the lane at `t0` and `t1` first (`sampleAutomationLane`,
+log-aware) and pins anchor points at both edges, drops the old interior, inserts `inner`,
+sorts, and runs the existing normalize path (dedupe, `MAX_AUTOMATION_POINTS` 512 cap).
+Every feature below composes it, and every write flows through the lane's existing
+`commitPoints` preview/persist split — undo, drafts, and the quiet-commit path are
+inherited, not rebuilt.
+
+## Features
+
+### Delete range (wa-15)
+
+`replaceRange(..., [])` on Delete/Backspace via a new `useAutomationSelectionKeyboard`
+hook (sibling of `useKeyframeKeyboard`), inert while the value input or any text field has
+focus. Escape clears the selection.
+
+### Shapes (wa-16)
+
+Right-click the selection rect → context menu: **Ramp up · Ramp down · Swell · Dip**, plus
+**Simplify**. Pure generators in `automationShapes.ts`, one shape scaled to the selection,
+values computed in unit space so log knobs behave:
+
+| Shape     | Points | Semantics                                                            |
+| --------- | ------ | -------------------------------------------------------------------- |
+| Ramp up   | 2      | `range.min` at `t0` → envelope's own value at `t1` (fade in)          |
+| Ramp down | 2      | envelope's own value at `t0` → `range.min` at `t1` (fade out)         |
+| Swell     | 3      | edge values, peak at `range.max` at the midpoint, `curve`-smoothed    |
+| Dip       | 3      | edge values, midpoint at 25 % of the edge value in unit space (duck), smoothed |
+
+Point counts are tiny; the 512 cap is never approached.
+
+### Copy/paste (wa-17)
+
+Module-level clipboard `{ sourceRange: AutomationRange, span: number, points }`, times
+rebased to `t0`. Not the OS clipboard — points aren't text, and `useClipboard` is already
+the DOM-element channel.
+
+- **Cmd+C**: copy `pointsIn` the active selection.
+- **Cmd+V**: paste at the active selection's start when one exists, else at the playhead's
+  clip-local position, onto the selected clip's active lane. Inserted via `replaceRange`
+  over the pasted span.
+- Cross-parameter values map through unit space: `toUnit(sourceRange, v)` →
+  `fromUnit(targetRange, u)` — a volume duck pasted onto a log-scaled `wet` lands sanely.
+- Registered in `useAppHotkeys` and active only while an automation selection exists (copy)
+  or clipboard content exists with an audio clip selected (paste), so clip-level
+  copy/paste is never shadowed.
+
+### Stretch (wa-18)
+
+8 px grab zones just inside the selection's left/right edges (points win hits over
+handles). Dragging an edge retimes interior points proportionally:
+`t' = t0' + (t − t0) · span'/span`, then `replaceRange` over the union of old and new
+spans. One more gesture kind in the hook. Vertical scaling deliberately cut.
+
+### Simplify (wa-16, shares the menu)
+
+Ramer–Douglas–Peucker in unit space over the selection, ε ≈ 2 % of lane height. Exists for
+carve output and dense hand edits.
+
+## Testing
+
+- `replaceRange`: assert `sampleAutomationLane` outside the range is identical before and
+  after every op — the invariant, tested directly. Anchor pinning, cap, dedupe.
+- Generators: point counts, unit-space values on a log lane, edge continuity.
+- RDP: dense sine in → few points out, max deviation < ε.
+- Clipboard mapping: volume → wet round-trip on a log range.
+- Gestures: existing harness (synthetic pointers, stubbed box, assert `onPreview`/
+  `onCommit` payloads). New: drag selects; sub-threshold click clears; Escape clears;
+  Delete empties the range and pins anchors; edge drag retimes; menu insert writes a swell.
+- Keyboard hook inert while a text input has focus.
+- Nothing below the attribute changes → no engine/render tests.
+
+## PR breakdown
+
+Stacked on wa-14 (stack #3027), each under the 1000-LOC convention:
+
+| PR    | Content                                                                  | ~LOC |
+| ----- | ------------------------------------------------------------------------ | ---- |
+| wa-15 | slice, drag gesture, rect render, `replaceRange`/`pointsIn`, Delete/Esc  | 400  |
+| wa-16 | shape generators, selection context menu (ramp/swell/dip), Simplify      | 380  |
+| wa-17 | clipboard, Cmd+C/V in `useAppHotkeys`, unit-space mapping                | 300  |
+| wa-18 | edge-handle stretch gesture                                              | 250  |
+
+wa-16/17/18 are independent once wa-15 lands. File-size note: `useAutomationLaneGestures`
+grows in wa-15 and wa-18 (310 lines today — headroom exists); the menu is a new file.
+
+## Decisions log
+
+- One cycle per shape, scaled to the selection (per-beat cycles rejected: not a music tool).
+- Shape set is the utility four (ramp up/down, swell, dip); saw/square/ADSR rejected.
+- Paste anchor: selection start when active, else playhead.
+- Selection state in a store slice (approach A); component-local and DomEditContext rejected.
+- Internal clipboard, not OS clipboard.
+- All range math pure, in studio; core untouched.
+- Vertical scale and skew cut from stretch.