fix(core): apply chain edits to the running graph

A structural edit — an effect added, removed, bypassed, or a filter's pole
count switched — was dropped. `buildFxChain`'s update reports false when the
change is not merely new values, and the attribute observer ignored that, so
the edit only took hold when the persisting write reloaded the composition.
That reload restarted every playing track, which is what was heard as the
audio chopping.

The graph is now swapped in place: the old effects are detached, the new ones
built and connected between the same source and gain, and any lanes
re-scheduled onto the new nodes. The source node is never touched, so playback
does not restart.

A track with no chain is watched too, rather than wired through and forgotten,
so adding its first effect is heard the same way. That means the function
always returns a disposer instead of null for the empty case.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: vanceingalls

packages/core/src/runtime/audioFx.test.ts

@@ -70,8 +70,7 @@ describe("attachElementFxChain", () => {
   it("connects source straight to destination when there is no chain", () => {
     const src = new Node();
     const dst = new Node();
-    const handle = attachElementFxChain(ctx(), el(), src as never, dst as never);
-    expect(handle).toBeNull();
+    attachElementFxChain(ctx(), el(), src as never, dst as never);
     expect(src.connections).toContain(dst);
   });
 
@@ -102,7 +101,7 @@ describe("attachElementFxChain", () => {
       src as never,
       dst as never,
     );
-    expect(handle).toBeNull();
+    expect(handle).not.toBeNull();
     expect(src.connections).toContain(dst);
   });
 
@@ -115,10 +114,90 @@ describe("attachElementFxChain", () => {
       src as never,
       dst as never,
     );
-    expect(handle).toBeNull();
+    expect(handle).not.toBeNull();
     expect(src.connections).toContain(dst);
   });
 
+  /**
+   * A structural edit — an effect added, removed or bypassed — used to be
+   * ignored here, so it only took effect when the persisting write reloaded the
+   * composition. That reload restarted every playing track, which is what was
+   * heard as the audio chopping. The graph is now swapped in place instead, with
+   * the source node left alone.
+   */
+  describe("editing the chain while it plays", () => {
+    const audioEl = (chain?: unknown): HTMLElement => {
+      const node = document.createElement("audio");
+      if (chain) node.setAttribute("data-fx-chain", JSON.stringify(chain));
+      document.body.append(node);
+      return node;
+    };
+    /** Let the MutationObserver's microtask run. */
+    const settle = () => new Promise((r) => setTimeout(r, 0));
+
+    it("routes through an effect added to a track that had none", async () => {
+      const src = new Node();
+      const dst = new Node();
+      const node = audioEl();
+      attachElementFxChain(ctx(), node, src as never, dst as never);
+      expect(src.connections).toContain(dst);
+
+      node.setAttribute("data-fx-chain", JSON.stringify(CHAIN));
+      await settle();
+      // Now feeding the chain, not the gain directly.
+      expect(src.connections.at(-1)).not.toBe(dst);
+    });
+
+    it("returns to dry when the last effect is removed", async () => {
+      const src = new Node();
+      const dst = new Node();
+      const node = audioEl(CHAIN);
+      attachElementFxChain(ctx(), node, src as never, dst as never);
+      const firstTarget = src.connections[0] as Node;
+      expect(firstTarget).not.toBe(dst);
+
+      node.removeAttribute("data-fx-chain");
+      await settle();
+      expect(src.connections.at(-1)).toBe(dst);
+      // The graph that was in the path is torn down, not left running.
+      expect(firstTarget.disconnected).toBe(true);
+    });
+
+    it("swaps the graph without replacing the source node", async () => {
+      const src = new Node();
+      const dst = new Node();
+      const node = audioEl(CHAIN);
+      attachElementFxChain(ctx(), node, src as never, dst as never);
+      const before = src.connections[0] as Node;
+
+      node.setAttribute(
+        "data-fx-chain",
+        JSON.stringify({
+          version: 1,
+          nodes: [
+            { type: "peaking", params: { frequency: 1000, gain: -6, q: 1 } },
+            { type: "lowpass", params: { frequency: 800, q: 0.7, poles: "2" } },
+          ],
+        }),
+      );
+      await settle();
+      const after = src.connections.at(-1) as Node;
+      // A different graph, reached from the same source: the audio never restarts.
+      expect(after).not.toBe(before);
+      expect(before.disconnected).toBe(true);
+    });
+
+    it("keeps playing dry when an edit leaves the chain unreadable", async () => {
+      const src = new Node();
+      const dst = new Node();
+      const node = audioEl(CHAIN);
+      attachElementFxChain(ctx(), node, src as never, dst as never);
+      node.setAttribute("data-fx-chain", "{not json");
+      await settle();
+      expect(src.connections.at(-1)).toBe(dst);
+    });
+  });
+
   it("tears the chain down on dispose", () => {
     const src = new Node();
     const dst = new Node();

packages/core/src/runtime/audioFx.ts

@@ -68,18 +68,6 @@ function readChain(el: { getAttribute?(name: string): string | null }): {
   }
 }
 
-/**
- * An element's automation lanes, bound to whatever chain it carries.
- *
- * FX lanes need the chain to resolve their target's range, so they are dropped
- * for an element with no chain; a volume lane is always readable.
- */
-export function readElementAutomation(el: {
-  getAttribute?(name: string): string | null;
-}): HfAutomation {
-  return readAutomation(el, readChain(el).chain);
-}
-
 /**
  * Splice an element's FX chain between a decoded source and its gain stage.
  *
@@ -88,8 +76,8 @@ export function readElementAutomation(el: {
  * point where effects belong — capturing the element would process a stream
  * nothing is listening to.
  *
- * Returns null when the element carries no chain, leaving the original
- * source-to-gain connection in place.
+ * A track with no chain is wired straight through, but still watched: adding its
+ * first effect is then heard without rescheduling the source.
  *
  * With `timing`, the element's automation lanes are scheduled onto the built
  * effects as AudioParam ramps, and rescheduled when the attribute is edited.
@@ -102,10 +90,6 @@ export function attachElementFxChain(
   timing?: AutomationTiming,
 ): { dispose(): void } | null {
   const { chain } = readChain(el);
-  if (chain.nodes.length === 0) {
-    source.connect(destination);
-    return null;
-  }
 
   // An AudioWorkletNode cannot be constructed before its processor is
   // registered — it throws, and the whole chain is lost. So when the chain
@@ -137,21 +121,56 @@ export function attachElementFxChain(
     };
   }
 
-  let handle: FxChainHandle;
-  try {
-    handle = buildFxChain(ctx, chain);
-  } catch {
-    // A chain we cannot realise plays dry rather than silencing the track.
-    source.connect(destination);
-    return null;
-  }
+  // Null means the source runs straight into its gain: an empty chain, or one
+  // that could not be realised. Mutable because a structural edit swaps the
+  // whole graph rather than re-parameterising it.
+  let handle: FxChainHandle | null = null;
+  let automated: FxParamTarget[] = [];
+
+  /** Take the current graph out of the path, leaving the source connected dry. */
+  const detach = (): void => {
+    try {
+      if (handle) {
+        source.disconnect(handle.input);
+        handle.output.disconnect(destination);
+        handle.dispose();
+      } else {
+        source.disconnect(destination);
+      }
+    } catch {
+      // Already disconnected; nothing to unwind.
+    }
+    handle = null;
+  };
+
+  /**
+   * Put `next` in the signal path.
+   *
+   * A chain that cannot be realised — an unregistered worklet, an unknown
+   * effect — plays dry rather than silencing the track.
+   */
+  const attach = (next: HfAudioFxChain): void => {
+    if (next.nodes.length === 0) {
+      source.connect(destination);
+      return;
+    }
+    try {
+      const built = buildFxChain(ctx, next);
+      source.connect(built.input);
+      built.output.connect(destination);
+      handle = built;
+    } catch {
+      source.connect(destination);
+    }
+  };
 
-  source.connect(handle.input);
-  handle.output.connect(destination);
+  const scheduleFor = (next: HfAudioFxChain, at: AutomationTiming | null): void => {
+    automated =
+      at && handle ? scheduleChainAutomation(readAutomation(el, next), next, handle.nodes, at) : [];
+  };
 
-  let automated: FxParamTarget[] = timing
-    ? scheduleChainAutomation(readAutomation(el, chain), chain, handle.nodes, timing)
-    : [];
+  attach(chain);
+  scheduleFor(chain, timing ?? null);
 
   /**
    * Re-aim the envelope at the live playhead. An edit lands mid-playback, so
@@ -171,14 +190,31 @@ export function attachElementFxChain(
     const at = timingNow();
     if (!at) return;
     cancelParamLane(automated, at.scheduledAt);
-    automated = scheduleChainAutomation(readAutomation(el, next), next, handle.nodes, at);
+    scheduleFor(next, at);
+  };
+
+  /**
+   * Rebuild the graph for a shape change — an effect added, removed, bypassed,
+   * or a filter's pole count switched — while the source keeps playing.
+   *
+   * The source node is untouched, so the audio does not restart; only the
+   * effects between it and its gain are replaced. Doing this here is what keeps
+   * a structural edit from needing a composition reload, which is what made the
+   * audio audibly chop.
+   */
+  const rebuild = (next: HfAudioFxChain): void => {
+    const at = timingNow();
+    cancelParamLane(automated, at?.scheduledAt ?? 0);
+    detach();
+    attach(next);
+    scheduleFor(next, at);
   };
 
-  // Follow the attribute while the source plays, so dragging a knob is heard
-  // without rescheduling the track. Values-only changes re-parameterise the
-  // running graph and land on the next 128-sample quantum; a shape change
-  // (effect added, bypassed, pole count) cannot be patched in place and waits
-  // for the next schedule rather than cutting the audio mid-play.
+  // Follow the attribute while the source plays, so editing a chain is heard
+  // without rescheduling the track. A values-only change re-parameterises the
+  // running graph and lands on the next 128-sample quantum; anything structural
+  // swaps the effects between the source and its gain, leaving the source — and
+  // so the playing audio — alone.
   let observer: MutationObserver | null = null;
   const target = el as unknown as Node;
   if (
@@ -187,11 +223,10 @@ export function attachElementFxChain(
   ) {
     observer = new MutationObserver(() => {
       const next = readChain(el);
-      if (next.chain.nodes.length === 0) return;
-      handle.update(next.chain);
-      // Values pushed by `update` would fight a running envelope, so the lanes
-      // are re-scheduled on top of them from the current playhead.
-      rescheduleAutomation(next.chain);
+      // `update` reports false when the change is structural rather than a new
+      // set of values, which is the signal to swap the graph.
+      if (!handle || !handle.update(next.chain)) rebuild(next.chain);
+      else rescheduleAutomation(next.chain);
     });
     observer.observe(target, {
       attributes: true,
@@ -205,7 +240,7 @@ export function attachElementFxChain(
       if (automated.length > 0) {
         cancelParamLane(automated, typeof ctx.currentTime === "number" ? ctx.currentTime : 0);
       }
-      handle.dispose();
+      handle?.dispose();
     },
   };
 }