From e79ee2d76c1b9ccbd1b721956bd4ec171243126d Mon Sep 17 00:00:00 2001
From: ChuxiJ <junmin@acestudio.ai>
Date: Fri, 27 Mar 2026 20:42:53 +0800
Subject: [PATCH] feat: expose filter envelope controls in synth editor

---
 .../pianoroll/SynthInstrumentEditor.tsx       | 100 +++++++++++++++++-
 tests/unit/SynthInstrumentEditor.test.tsx     |  24 ++++-
 2 files changed, 121 insertions(+), 3 deletions(-)

diff --git a/src/components/pianoroll/SynthInstrumentEditor.tsx b/src/components/pianoroll/SynthInstrumentEditor.tsx
index 57e9edec..021e2467 100644
--- a/src/components/pianoroll/SynthInstrumentEditor.tsx
+++ b/src/components/pianoroll/SynthInstrumentEditor.tsx
@@ -135,7 +135,7 @@ function renderSubtractiveEditor(
   instrument: SubtractiveTrackInstrument,
   onInstrumentChange: (instrument: SubtractiveTrackInstrument) => void,
 ) {
-  const { oscillator, ampEnvelope, filter, lfo, unison, glideTime, outputGain } = instrument.settings;
+  const { oscillator, ampEnvelope, filter, filterEnvelope, lfo, unison, glideTime, outputGain } = instrument.settings;
 
   const updateSettings = (settings: SubtractiveTrackInstrument['settings']) => {
     onInstrumentChange({
@@ -311,7 +311,7 @@ function renderSubtractiveEditor(
       </Section>
 
       <Section
-        title="Filter, Modulation, and Width"
+        title="Filter, Envelopes, and Motion"
         eyebrow="Motion"
         action={(
           <div className="flex items-center gap-2">
@@ -486,6 +486,101 @@ function renderSubtractiveEditor(
           />
         </div>
 
+        <div className="mt-4">
+          <div className="flex items-center justify-between gap-3">
+            <div className="text-[11px] font-semibold uppercase tracking-[0.16em] text-zinc-400">Filter Envelope</div>
+            <div className="text-[10px] uppercase tracking-[0.14em] text-zinc-500">Per-note cutoff contour</div>
+          </div>
+          <div className={`mt-2 grid grid-cols-3 gap-3 ${filter.enabled ? '' : 'opacity-45'}`}>
+            <EditorKnob
+              value={filterEnvelope.amount}
+              min={0}
+              max={1}
+              defaultValue={0}
+              step={0.01}
+              label="Filter Env Amt"
+              disabled={!filter.enabled}
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                filterEnvelope: {
+                  ...filterEnvelope,
+                  amount: value,
+                },
+              })}
+            />
+            <EditorKnob
+              value={filterEnvelope.attack}
+              min={0}
+              max={2}
+              defaultValue={0.01}
+              step={0.01}
+              label="Filt Env Attack"
+              unit="s"
+              disabled={!filter.enabled}
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                filterEnvelope: {
+                  ...filterEnvelope,
+                  attack: value,
+                },
+              })}
+            />
+            <EditorKnob
+              value={filterEnvelope.decay}
+              min={0}
+              max={2}
+              defaultValue={0.2}
+              step={0.01}
+              label="Filt Env Decay"
+              unit="s"
+              disabled={!filter.enabled}
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                filterEnvelope: {
+                  ...filterEnvelope,
+                  decay: value,
+                },
+              })}
+            />
+          </div>
+          <div className={`mt-3 grid grid-cols-2 gap-3 ${filter.enabled ? '' : 'opacity-45'}`}>
+            <EditorKnob
+              value={filterEnvelope.sustain}
+              min={0}
+              max={1}
+              defaultValue={0.5}
+              step={0.01}
+              label="Filt Env Sustain"
+              disabled={!filter.enabled}
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                filterEnvelope: {
+                  ...filterEnvelope,
+                  sustain: value,
+                },
+              })}
+            />
+            <EditorKnob
+              value={filterEnvelope.release}
+              min={0}
+              max={5}
+              defaultValue={0.5}
+              step={0.01}
+              label="Filt Env Release"
+              unit="s"
+              disabled={!filter.enabled}
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                filterEnvelope: {
+                  ...filterEnvelope,
+                  release: value,
+                },
+              })}
+            />
+          </div>
+        </div>
+
+        <div className="mt-4 text-[11px] font-semibold uppercase tracking-[0.16em] text-zinc-400">LFO and Glide</div>
         <div className="mt-4 grid grid-cols-4 gap-3">
           <EditorKnob
             value={lfo.rateHz}
@@ -551,6 +646,7 @@ function renderSubtractiveEditor(
           />
         </div>
 
+        <div className="mt-4 text-[11px] font-semibold uppercase tracking-[0.16em] text-zinc-400">Unison</div>
         <div className="mt-4 grid grid-cols-2 gap-2">
           <SelectField
             ariaLabel="Instrument unison voices"
diff --git a/tests/unit/SynthInstrumentEditor.test.tsx b/tests/unit/SynthInstrumentEditor.test.tsx
index 0e12605e..d572b922 100644
--- a/tests/unit/SynthInstrumentEditor.test.tsx
+++ b/tests/unit/SynthInstrumentEditor.test.tsx
@@ -4,7 +4,7 @@ import { SynthInstrumentEditor } from '../../src/components/pianoroll/SynthInstr
 import { createDefaultFmInstrument, createDefaultSubtractiveInstrument } from '../../src/utils/trackInstrument';
 
 describe('SynthInstrumentEditor', () => {
-  it('updates subtractive oscillator waveform and filter cutoff through canonical instrument state', () => {
+  it('updates subtractive oscillator waveform, filter cutoff, and filter envelope through canonical instrument state', () => {
     const onInstrumentChange = vi.fn();
 
     render(
@@ -32,6 +32,28 @@ describe('SynthInstrumentEditor', () => {
         filter: expect.objectContaining({ cutoffHz: 3200 }),
       }),
     }));
+
+    fireEvent.contextMenu(screen.getByLabelText('Filter Env Amt knob'));
+    fireEvent.change(screen.getByLabelText('Filter Env Amt exact value'), { target: { value: '0.42' } });
+    fireEvent.keyDown(screen.getByLabelText('Filter Env Amt exact value'), { key: 'Enter' });
+
+    expect(onInstrumentChange).toHaveBeenLastCalledWith(expect.objectContaining({
+      kind: 'subtractive',
+      settings: expect.objectContaining({
+        filterEnvelope: expect.objectContaining({ amount: 0.42 }),
+      }),
+    }));
+
+    fireEvent.contextMenu(screen.getByLabelText('Filt Env Release knob'));
+    fireEvent.change(screen.getByLabelText('Filt Env Release exact value'), { target: { value: '1.8' } });
+    fireEvent.keyDown(screen.getByLabelText('Filt Env Release exact value'), { key: 'Enter' });
+
+    expect(onInstrumentChange).toHaveBeenLastCalledWith(expect.objectContaining({
+      kind: 'subtractive',
+      settings: expect.objectContaining({
+        filterEnvelope: expect.objectContaining({ release: 1.8 }),
+      }),
+    }));
   });
 
   it('updates FM fallback preset and modulation index through canonical instrument state', () => {