fix(studio,core,engine): close the defects a max-effort review found in the fixes

A review of the five fix commits found eleven real defects, including a
regression one of them introduced. Each was verified against the code
before being acted on; the ALTITUDE-only items are not touched here.

REGRESSION, from "group rows survive a collapse". Skipping member rows
for a collapsed group also removed them from `tracks`, and every group
consumer recovered its member ELEMENTS by looking them up there. Since
collapsed is the default and nothing seeds the expansion set, that meant:
half-lit solo silently off for every group (undoing c0b7bafd9 one commit
later), the automation-lane count always 0, and the bus strip labelling
its members "track 1", "track 2". Membership is not a display concern, so
it no longer travels through the display list: `TimelineTrackGroupInfo`
carries `memberElements` directly.

Group bus. `reanchor` wrote `fader.gain.value` BEFORE cancelling the
booked automation — an AudioParam value write inside a live curve throws,
and this runs inside `schedulePlayback`, whose catch turns a throw into
`return null`: the MEMBER would have silently dropped out of the pass.
Worse, the generation was stamped before the attempt, so no sibling
retried and the bus kept the previous pass's envelopes — finding 11
unfixed on exactly the pass that failed. Now: clear first, stamp only on
success, and isolate the call. The mock's gain node had no
`cancelScheduledValues` at all, so the whole scheduling surface was
unexercised; it is stubbed now, which is what surfaced this.

`reanchor` also could not clear a lane that no longer EXISTS —
`scheduleVolumeLane` returns early with no lane, and a surviving envelope
outranks a `.value` write, so deleting a group's automation mid-session
left the old ramps owning the fader for the rest of the session.

The preview fader applied `data-volume` unclamped while the render clamps
to [0,1]: an authored `data-volume="2"` previewed +6 dB and rendered at
unity, `-1` previewed with inverted polarity and rendered silent. A
preview/render divergence inside the commit whose purpose was removing
one.

Pitch shift. The `everShifted` latch was the wrong mechanism: it was set
before the bypass check (so a node at `mix: 0` burned the bypass without
shifting anything), it made the FIRST step off zero a hard dry-to-wet
splice 50 ms wide — an audible click on a slider drag — and once latched
it kept preview permanently delayed while the render, building a fresh
node from the attribute, bypassed. Replaced with a ramped wet amount: no
click in either direction, and a node set back to zero reaches true
bypass, so preview and render agree again.

Silent no-ops. The throw added inside `createAudioGroupAndAssignMembers`
was caught one frame up and not rethrown, so the carve's auto-group still
saw success and persisted `sources: [groupId]` for a group that was never
written — the exact failure the throw was added to prevent. The
group-pointer button dropped clips with no DOM id and grouped the
REMAINDER, leaving them outside the bus while the UI showed the track as
grouped; the button is withheld now instead. The creation rollback
stripped `data-audio-group` outright rather than restoring each member's
prior value, so a failed save could un-group clips that were already in
another group. `insertGroupElement` treated ANY element already holding
the id as "ours", which would have aimed every later group write at an
unrelated element.

`setAudioMuteHidden` rescheduled Web Audio mid-play without `stopAll()`.
Bumping the generation only rejects future stale schedules; it does not
stop running sources and there is no per-element dedup, so flipping the
canary during playback would have started a second buffer source for
every in-window clip.

`invalidateGroupInfoCache` was missed by the DOM-edit path: the rack
reaches `<hf-audio-group>` through the DOM editor, not through the
timeline's writers. Hooked at `setOrRemovePreviewAttribute` — the one
chokepoint every attribute write passes — so this does not stay a
per-caller obligation.

Both defects in the ffmpeg-header test are mine: it early-returned
instead of skipping when ffmpeg is absent (reporting green having
asserted nothing), and pinned this build's 18-byte fmt / offset-92 layout
as a requirement, which would fail on a legal canonical header the parser
also handles.

Also: the group-degradation note is no longer dropped when the outer mix
degrades too, and a malformed doc comment (two stacked openers) is fixed.

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

packages/core/src/audio/audioFxWorklets.test.ts

@@ -168,23 +168,77 @@ describe("the worklet processors themselves", () => {
       expect(maxErr).toBeLessThan(1e-6);
     });
 
-    // A track whose semitones are automated THROUGH zero must not jump between
-    // the delayed and the undelayed path — that discontinuity is a click, which
-    // is worse than the delay the bypass would save.
-    it("keeps processing at zero once it has shifted, rather than clicking to dry", async () => {
+    /** Largest sample-to-sample step — a splice between the dry and the
+     *  ~50 ms-delayed wet path shows up here as a discontinuity. */
+    function maxStep(s: Float32Array, from: number, to: number): number {
+      let worst = 0;
+      for (let i = from + 1; i < to; i++) {
+        worst = Math.max(worst, Math.abs((s[i] ?? 0) - (s[i - 1] ?? 0)));
+      }
+      return worst;
+    }
+
+    // Dragging the semitones slider off zero mid-playback swaps the output from
+    // x[t] to x[t-50ms]. Switched hard that is an audible click; the wet amount
+    // is ramped instead. A 440 Hz sine steps ~0.057 per sample at its steepest,
+    // so anything near the signal's own peak is a splice, not the waveform.
+    it("does not click when the shift moves off zero mid-signal", async () => {
+      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
+      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
+      const p = new HfPitchshift({ processorOptions: { semitones: 0, mix: 1 } });
+      run(p, sine(440, 0.3)); // settled dry, ring warm
+      p.p = { ...p.p, semitones: 7 };
+      const output = run(p, sine(440, 0.3));
+      expect(maxStep(output, 0, output.length)).toBeLessThan(0.2);
+    });
+
+    it("does not click on the way back to zero either", async () => {
       const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
       if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
       const p = new HfPitchshift({ processorOptions: { semitones: 7, mix: 1 } });
-      const input = sine(440, 0.4);
-      run(p, input);
+      run(p, sine(440, 0.3));
       p.p = { ...p.p, semitones: 0 };
-      const output = run(p, sine(440, 0.4));
-      // Still the wet path (grain-delayed), so it does NOT equal the input.
+      const output = run(p, sine(440, 0.3));
+      expect(maxStep(output, 0, output.length)).toBeLessThan(0.2);
+    });
+
+    // ...and having ramped back down it must reach TRUE bypass, not sit on a
+    // permanently latched wet path. The render builds a fresh node from the
+    // saved attribute and bypasses at semitones 0; a preview that stayed wet
+    // would carry a 50 ms delay the export does not have.
+    it("returns to true bypass after being shifted and set back to zero", async () => {
+      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
+      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
+      const p = new HfPitchshift({ processorOptions: { semitones: 7, mix: 1 } });
+      run(p, sine(440, 0.3));
+      p.p = { ...p.p, semitones: 0 };
+      run(p, sine(440, 0.3)); // ramp down settles here
+
+      const input = sine(440, 0.3);
+      const output = run(p, input);
       let maxErr = 0;
-      for (let i = 0; i < 4000; i++) {
+      for (let i = 0; i < input.length; i++) {
         maxErr = Math.max(maxErr, Math.abs((output[i] ?? 0) - (input[i] ?? 0)));
       }
-      expect(maxErr).toBeGreaterThan(1e-3);
+      expect(maxErr).toBeLessThan(1e-6);
+    });
+
+    // A node parked at mix 0 has shifted nothing, so it must not have spent
+    // anything that stops the zero-shift bypass engaging later.
+    it("is transparent at zero after sitting mixed fully out", async () => {
+      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
+      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
+      const p = new HfPitchshift({ processorOptions: { semitones: 7, mix: 0 } });
+      run(p, sine(440, 0.3));
+
+      p.p = { ...p.p, semitones: 0, mix: 1 };
+      const input = sine(440, 0.3);
+      const output = run(p, input);
+      let maxErr = 0;
+      for (let i = 0; i < input.length; i++) {
+        maxErr = Math.max(maxErr, Math.abs((output[i] ?? 0) - (input[i] ?? 0)));
+      }
+      expect(maxErr).toBeLessThan(1e-6);
     });
 
     // The ring starts empty, so the taps read zeros for the first grain. That

packages/core/src/audio/audioFxWorklets.ts

@@ -257,11 +257,17 @@ class HfPitchshift extends AudioWorkletProcessor {
     // behind the write head, so until this fills they would read the ring's
     // zeros — the head of every clip came out attenuated or silent.
     this.filled = 0;
-    // Latched the first time a non-zero shift is asked for. The no-op bypass
-    // below must not engage for a track whose semitones are AUTOMATED through
-    // zero: switching between a delayed and an undelayed path mid-signal is a
-    // click, which is worse than the delay it would save.
-    this.everShifted = false;
+    // How much of the wet (pitch-shifted) path is currently in the output, and
+    // where it is heading. Crossing between dry and wet is a ~50 ms jump in the
+    // signal, so it is RAMPED rather than switched: a hard swap either way is a
+    // click. Ramping in both directions is also what lets a node return to true
+    // bypass at semitones 0 — a one-way latch left preview stuck with the delay
+    // that the render, building a fresh node from the attribute, does not have.
+    this.wet = 0;
+    this.wetTarget = 0;
+    // ~15 ms one-pole, short enough to feel immediate on a slider drag and long
+    // enough that the splice is inaudible.
+    this.wetCoef = Math.exp(-1 / (sampleRate * 0.015));
     this.port.onmessage = (e) => {
       if (e.data && e.data.__hfDispose) { this.dead = true; return; }
       this.p = { ...this.p, ...e.data };
@@ -274,7 +280,6 @@ class HfPitchshift extends AudioWorkletProcessor {
     const p = this.p;
     const semitones = Math.max(-12, Math.min(12, p.semitones ?? 0));
     const mix = Math.max(0, Math.min(1, p.mix ?? 1));
-    if (semitones !== 0) this.everShifted = true;
     const grain = this.grain;
     const ringLen = grain * 2;
     const n = i[0] ? i[0].length : 0;
@@ -282,12 +287,16 @@ class HfPitchshift extends AudioWorkletProcessor {
       if (!this.buf[ch]) this.buf[ch] = new Float32Array(ringLen);
     }
 
-    // A node asking for no shift at all, or mixed fully out, is transparent.
-    // The grain delay is ~grain/2 whatever the ratio, so at semitones=0 this
-    // used to degrade into a pure 50 ms delay of the signal — while the copy
-    // for that exact setting reads "Unchanged pitch". The ring keeps filling
-    // so a later shift does not start cold.
-    if (mix === 0 || (semitones === 0 && !this.everShifted)) {
+    // Nothing to shift, or mixed fully out. The grain delay is ~grain/2
+    // whatever the ratio, so at semitones=0 this degenerated into a pure 50 ms
+    // delay of the signal — while the copy for that exact setting reads
+    // "Unchanged pitch".
+    this.wetTarget = semitones === 0 ? 0 : mix;
+
+    // Fully dry AND settled: take the cheap transparent path. The ring keeps
+    // filling, so a later shift does not start cold.
+    if (this.wetTarget === 0 && this.wet < 1e-4) {
+      this.wet = 0;
       let w = this.write;
       for (let s = 0; s < n; s++) {
         for (let ch = 0; ch < i.length; ch++) {
@@ -304,7 +313,8 @@ class HfPitchshift extends AudioWorkletProcessor {
 
     const ratio = Math.pow(2, semitones / 12);
     const inc = (1 - ratio) / grain;
-    let write = this.write, phase = this.phase, filled = this.filled;
+    let write = this.write, phase = this.phase, filled = this.filled, wetNow = this.wet;
+    const target = this.wetTarget, coef = this.wetCoef;
     for (let s = 0; s < n; s++) {
       phase += inc;
       phase -= Math.floor(phase);
@@ -313,7 +323,8 @@ class HfPitchshift extends AudioWorkletProcessor {
       // Ramp the wet path in as the ring fills rather than reading zeros:
       // 100 ms of unshifted audio at the head of a clip beats 50 ms of silence.
       const warm = filled >= grain ? 1 : filled / grain;
-      const wetMix = mix * warm;
+      wetNow = target + coef * (wetNow - target);
+      const wetMix = wetNow * warm;
       for (let ch = 0; ch < i.length; ch++) {
         const ring = this.buf[ch];
         const inp = i[ch], out = o[ch];
@@ -329,6 +340,7 @@ class HfPitchshift extends AudioWorkletProcessor {
     this.write = write;
     this.phase = phase;
     this.filled = filled;
+    this.wet = wetNow;
     return true;
   }
 }