From f20f1170c94ce7d62e458e173e17193cba4315eb Mon Sep 17 00:00:00 2001
From: ChuxiJ <junmin@acestudio.ai>
Date: Fri, 27 Mar 2026 16:16:29 +0800
Subject: [PATCH 1/2] feat: route piano roll playback through canonical
 instruments

---
 src/components/dialogs/InstrumentPicker.tsx  |   2 +-
 src/components/midi/VirtualKeyboard.tsx      |  12 +-
 src/components/pianoroll/PianoRoll.tsx       |  39 +++++-
 src/components/pianoroll/PianoRollCanvas.tsx |  18 ++-
 src/engine/SynthEngine.ts                    | 133 +++++++++++--------
 src/hooks/useTransport.ts                    |  25 ++--
 src/utils/__tests__/trackInstrument.test.ts  |  64 +++++++++
 src/utils/trackInstrument.ts                 |  22 +++
 tests/unit/PianoRoll.test.tsx                |  23 ++++
 tests/unit/VirtualKeyboard.test.tsx          |   8 +-
 10 files changed, 267 insertions(+), 79 deletions(-)
 create mode 100644 src/utils/__tests__/trackInstrument.test.ts

diff --git a/src/components/dialogs/InstrumentPicker.tsx b/src/components/dialogs/InstrumentPicker.tsx
index 49969936..5b18e088 100644
--- a/src/components/dialogs/InstrumentPicker.tsx
+++ b/src/components/dialogs/InstrumentPicker.tsx
@@ -278,7 +278,7 @@ export function InstrumentPicker() {
             <button
               onClick={() => {
                 const track = addTrackAtSelectedSlot('keyboard', 'pianoRoll');
-                updateTrack(track.id, { displayName: 'Quick Sampler', synthPreset: 'sampler' });
+                updateTrack(track.id, { displayName: 'Quick Sampler' });
                 setTrackSampler(track.id, { rootNote: 60 });
                 close();
                 setOpenPianoRoll(track.id);
diff --git a/src/components/midi/VirtualKeyboard.tsx b/src/components/midi/VirtualKeyboard.tsx
index 1b18f286..277f7eef 100644
--- a/src/components/midi/VirtualKeyboard.tsx
+++ b/src/components/midi/VirtualKeyboard.tsx
@@ -6,6 +6,7 @@ import { useProjectStore } from '../../store/projectStore';
 import { useTransportStore } from '../../store/transportStore';
 import { useUIStore } from '../../store/uiStore';
 import type { Track } from '../../types/project';
+import { getTrackInstrumentSelectValue, resolveTrackInstrument } from '../../utils/trackInstrument';
 
 const WHITE_KEY_BINDINGS = [
   { code: 'KeyA', semitone: 0, label: 'A' },
@@ -158,7 +159,16 @@ export function VirtualKeyboard() {
       let clipStartTime = 0;
 
       if (targetTrack) {
-        synthEngine.ensureTrackSynth(targetTrack.id, targetTrack.synthPreset ?? 'piano');
+        const trackInstrument = resolveTrackInstrument(targetTrack);
+        const instrumentSelectValue = getTrackInstrumentSelectValue(targetTrack);
+        synthEngine.ensureTrackSynth(
+          targetTrack.id,
+          trackInstrument ?? (
+            instrumentSelectValue === 'fm' || instrumentSelectValue === 'sampler'
+              ? 'piano'
+              : instrumentSelectValue
+          ),
+        );
         synthEngine.noteOn(targetTrack.id, pitch, nextVelocity);
         captureService.noteOn(targetTrack.id, pitch, velocityNormalized, startTime);
 
diff --git a/src/components/pianoroll/PianoRoll.tsx b/src/components/pianoroll/PianoRoll.tsx
index 7b180dab..0d8c9186 100644
--- a/src/components/pianoroll/PianoRoll.tsx
+++ b/src/components/pianoroll/PianoRoll.tsx
@@ -4,6 +4,12 @@ import { useProjectStore } from '../../store/projectStore';
 import { useUIStore } from '../../store/uiStore';
 import type { PianoRollGrid, SamplerConfig } from '../../types/project';
 import { CHORD_SHAPES, DEFAULT_CHORD_SHAPE_ABBR, getChordShapeByAbbr } from '../../utils/chords';
+import {
+  createDefaultSubtractiveInstrument,
+  getTrackInstrumentSelectValue,
+  resolveTrackInstrument,
+  type TrackInstrumentSelectValue,
+} from '../../utils/trackInstrument';
 import { QuickSamplerEditor } from './QuickSamplerEditor';
 import { GeneratePatternDialog } from './GeneratePatternDialog';
 import { PianoRollCanvas } from './PianoRollCanvas';
@@ -30,7 +36,7 @@ export function PianoRoll() {
   const [samplerDropActive, setSamplerDropActive] = useState(false);
 
   const project = useProjectStore((s) => s.project);
-  const updateTrack = useProjectStore((s) => s.updateTrack);
+  const setTrackInstrument = useProjectStore((s) => s.setTrackInstrument);
   const setTrackSampler = useProjectStore((s) => s.setTrackSampler);
   const clearTrackSampler = useProjectStore((s) => s.clearTrackSampler);
   const updateSamplerConfig = useProjectStore((s) => s.updateSamplerConfig);
@@ -106,6 +112,15 @@ export function PianoRoll() {
     return track.clips.find((candidate) => candidate.midiData) ?? null;
   }, [openClipId, track]);
 
+  const trackInstrument = useMemo(
+    () => (track ? resolveTrackInstrument(track) : null),
+    [track],
+  );
+  const instrumentSelectValue = useMemo<TrackInstrumentSelectValue>(
+    () => (track ? getTrackInstrumentSelectValue(track) : 'piano'),
+    [track],
+  );
+
   const ghostNotes = useMemo(() => {
     if (!showGhostNotes || !project || !track) return [];
     const notes: Array<{ pitch: number; startBeat: number; durationBeats: number; color: string }> = [];
@@ -312,8 +327,23 @@ export function PianoRoll() {
 
         <select
           aria-label="Track synth preset"
-          value={track.synthPreset ?? 'piano'}
-          onChange={(e) => updateTrack(track.id, { synthPreset: e.target.value as typeof track.synthPreset })}
+          value={instrumentSelectValue}
+          onChange={(e) => {
+            const nextValue = e.target.value as TrackInstrumentSelectValue;
+            if (nextValue === 'fm') return;
+
+            if (nextValue === 'sampler') {
+              setTrackSampler(track.id, {
+                audioKey: track.sampler?.audioKey,
+                sampleName: track.sampler?.sampleName,
+                rootNote: track.sampler?.rootNote ?? samplerConfig?.rootNote ?? 60,
+                sampleDuration: track.sampler?.sampleDuration ?? samplerConfig?.trimEnd ?? 1,
+              });
+              return;
+            }
+
+            setTrackInstrument(track.id, createDefaultSubtractiveInstrument(nextValue));
+          }}
           className="bg-[#111] border border-[#333] rounded px-2 py-1 text-[11px] text-zinc-300"
         >
           <option value="piano">Piano</option>
@@ -323,6 +353,7 @@ export function PianoRoll() {
           <option value="bass">Bass</option>
           <option value="organ">Organ</option>
           <option value="sampler">Quick Sampler</option>
+          {trackInstrument?.kind === 'fm' && <option value="fm">FM</option>}
         </select>
 
         {clip && <TransformMenu clipId={clip.id} selectedNoteIds={selectedNoteIds} />}
@@ -411,7 +442,7 @@ export function PianoRoll() {
         </div>
       </div>
 
-      {track.synthPreset === 'sampler' && (
+      {trackInstrument?.kind === 'sampler' && (
         <div
           aria-label="Quick Sampler target"
           className={samplerDropActive ? 'ring-1 ring-cyan-400/70 shrink-0' : 'shrink-0'}
diff --git a/src/components/pianoroll/PianoRollCanvas.tsx b/src/components/pianoroll/PianoRollCanvas.tsx
index 7ed1e373..f3067188 100644
--- a/src/components/pianoroll/PianoRollCanvas.tsx
+++ b/src/components/pianoroll/PianoRollCanvas.tsx
@@ -6,6 +6,10 @@ import { useUIStore } from '../../store/uiStore';
 import { ContextMenuWrapper, ContextMenuItem } from '../ui/ContextMenu';
 import { useTransportStore } from '../../store/transportStore';
 import type { Clip, MidiNote, PianoRollGrid, Track } from '../../types/project';
+import {
+  getTrackInstrumentSelectValue,
+  resolveTrackInstrument,
+} from '../../utils/trackInstrument';
 import { drawPianoRollKeyboard } from './PianoRollKeyboard';
 import { drawVelocityLane } from './VelocityLane';
 import { DEFAULT_CHORD_SHAPE_ABBR, getChordShapeByAbbr } from '../../utils/chords';
@@ -108,14 +112,20 @@ export function PianoRollCanvas({
   const bpm = useProjectStore((s) => s.project?.bpm ?? 120);
   const currentTime = useTransportStore((s) => s.currentTime);
   const previewEnabled = true;
-  const synthPreset = track.synthPreset ?? 'piano';
+  const trackInstrument = resolveTrackInstrument(track);
+  const instrumentSelectValue = getTrackInstrumentSelectValue(track);
+  const synthSource = trackInstrument ?? (
+    instrumentSelectValue === 'fm' || instrumentSelectValue === 'sampler'
+      ? 'piano'
+      : instrumentSelectValue
+  );
   const previewNoteAtPitch = useCallback((pitch: number, velocity = 100, duration = 0.3) => {
-    if (synthPreset === 'sampler') {
+    if (trackInstrument?.kind === 'sampler') {
       void samplerEngine.previewTrackNote(track, pitch, velocity, duration);
       return;
     }
-    void synthEngine.previewNote(pitch, velocity, duration, synthPreset);
-  }, [synthPreset, track]);
+    void synthEngine.previewNote(pitch, velocity, duration, synthSource);
+  }, [synthSource, track, trackInstrument]);
 
   const keyHeight = PIANO_ROLL_KEY_HEIGHT * prZoomY;
   const pixelsPerBeat = 40 * prZoomX;
diff --git a/src/engine/SynthEngine.ts b/src/engine/SynthEngine.ts
index 4183d32c..35b78786 100644
--- a/src/engine/SynthEngine.ts
+++ b/src/engine/SynthEngine.ts
@@ -1,54 +1,69 @@
 import * as Tone from 'tone';
-import type { SynthPreset } from '../types/project';
+import type {
+  LegacySynthVoicePreset,
+  SubtractiveTrackInstrument,
+  SynthPreset,
+  TrackInstrument,
+} from '../types/project';
+import {
+  createDefaultSubtractiveInstrument,
+  getLegacySynthPresetFromInstrument,
+} from '../utils/trackInstrument';
+
+type SynthSource = TrackInstrument | SynthPreset;
+const DEFAULT_TRACK_GAIN = 0.55;
 
 interface SynthInstance {
   synth: Tone.PolySynth;
-  preset: SynthPreset;
+  signature: string;
   gain: Tone.Gain;
 }
 
-export function createSynthForPreset(preset: SynthPreset): Tone.PolySynth {
-  const synth = new Tone.PolySynth(Tone.Synth);
+function toLegacySubtractivePreset(preset: SynthPreset): LegacySynthVoicePreset {
+  return preset === 'sampler' ? 'piano' : preset;
+}
 
-  switch (preset) {
-    case 'piano':
-      synth.set({
-        oscillator: { type: 'triangle8' },
-        envelope: { attack: 0.005, decay: 0.3, sustain: 0.2, release: 1.2 },
-      });
-      break;
-    case 'strings':
-      synth.set({
-        oscillator: { type: 'sawtooth' },
-        envelope: { attack: 0.4, decay: 0.2, sustain: 0.8, release: 1.5 },
-      });
-      break;
-    case 'pad':
-      synth.set({
-        oscillator: { type: 'sine' },
-        envelope: { attack: 0.8, decay: 0.5, sustain: 0.9, release: 2.0 },
-      });
-      break;
-    case 'lead':
-      synth.set({
-        oscillator: { type: 'square' },
-        envelope: { attack: 0.01, decay: 0.1, sustain: 0.6, release: 0.3 },
-      });
-      break;
-    case 'bass':
-      synth.set({
-        oscillator: { type: 'sawtooth' },
-        envelope: { attack: 0.01, decay: 0.2, sustain: 0.4, release: 0.5 },
-      });
-      break;
-    case 'organ':
-      synth.set({
-        oscillator: { type: 'sine' },
-        envelope: { attack: 0.01, decay: 0.01, sustain: 1, release: 0.1 },
-      });
-      break;
+function resolveSubtractiveInstrument(source: SynthSource): SubtractiveTrackInstrument {
+  if (typeof source === 'string') {
+    return createDefaultSubtractiveInstrument(toLegacySubtractivePreset(source));
   }
 
+  if (source.kind === 'subtractive') return source;
+
+  return createDefaultSubtractiveInstrument(
+    toLegacySubtractivePreset(getLegacySynthPresetFromInstrument(source)),
+  );
+}
+
+function getSynthSignature(source: SynthSource): string {
+  return typeof source === 'string'
+    ? `preset:${source}`
+    : `instrument:${JSON.stringify(source)}`;
+}
+
+function getTrackGainLevel(instrument: SubtractiveTrackInstrument, baseGain = DEFAULT_TRACK_GAIN): number {
+  const outputGainScale = Math.pow(10, instrument.settings.outputGain / 20);
+  return Math.max(0, Math.min(2, baseGain * outputGainScale));
+}
+
+export function createSynthForPreset(preset: SynthPreset): Tone.PolySynth {
+  return createSynthForSource(preset);
+}
+
+export function createSynthForSource(source: SynthSource): Tone.PolySynth {
+  const instrument = resolveSubtractiveInstrument(source);
+  const synth = new Tone.PolySynth(Tone.Synth);
+  synth.set({
+    oscillator: { type: instrument.settings.oscillator.waveform },
+    envelope: {
+      attack: instrument.settings.ampEnvelope.attack,
+      decay: instrument.settings.ampEnvelope.decay,
+      sustain: instrument.settings.ampEnvelope.sustain,
+      release: instrument.settings.ampEnvelope.release,
+    },
+    portamento: instrument.settings.glideTime,
+  });
+
   return synth;
 }
 
@@ -56,6 +71,7 @@ class SynthEngine {
   private synths = new Map<string, SynthInstance>();
   private previewSynth: Tone.PolySynth | null = null;
   private previewGain: Tone.Gain | null = null;
+  private previewSignature: string | null = null;
 
   async ensureStarted() {
     if (Tone.getContext().state !== 'running') {
@@ -63,9 +79,10 @@ class SynthEngine {
     }
   }
 
-  ensureTrackSynth(trackId: string, preset: SynthPreset, connectTo?: Tone.InputNode): Tone.PolySynth {
+  ensureTrackSynth(trackId: string, source: SynthSource, connectTo?: Tone.InputNode): Tone.PolySynth {
+    const signature = getSynthSignature(source);
     const existing = this.synths.get(trackId);
-    if (existing && existing.preset === preset) return existing.synth;
+    if (existing && existing.signature === signature) return existing.synth;
 
     if (existing) {
       existing.synth.releaseAll();
@@ -73,15 +90,16 @@ class SynthEngine {
       existing.gain.dispose();
     }
 
-    const synth = createSynthForPreset(preset);
-    const gain = new Tone.Gain(0.55);
+    const instrument = resolveSubtractiveInstrument(source);
+    const synth = createSynthForSource(source);
+    const gain = new Tone.Gain(getTrackGainLevel(instrument));
     synth.connect(gain);
     if (connectTo) {
       gain.connect(connectTo);
     } else {
       gain.toDestination();
     }
-    this.synths.set(trackId, { synth, preset, gain });
+    this.synths.set(trackId, { synth, signature, gain });
     return synth;
   }
 
@@ -89,20 +107,26 @@ class SynthEngine {
     return this.synths.get(trackId)?.synth ?? null;
   }
 
-  async previewNote(pitch: number, velocity = 100, duration = 0.3, preset: SynthPreset = 'piano') {
+  async previewNote(pitch: number, velocity = 100, duration = 0.3, source: SynthSource = 'piano') {
     await this.ensureStarted();
-    if (!this.previewSynth || !this.previewGain) {
-      this.previewSynth = createSynthForPreset(preset);
-      this.previewGain = new Tone.Gain(0.3).toDestination();
+    const signature = getSynthSignature(source);
+
+    if (!this.previewSynth || !this.previewGain || this.previewSignature !== signature) {
+      this.previewSynth?.dispose();
+      this.previewGain?.dispose();
+      const instrument = resolveSubtractiveInstrument(source);
+      this.previewSynth = createSynthForSource(source);
+      this.previewGain = new Tone.Gain(getTrackGainLevel(instrument, 0.3)).toDestination();
       this.previewSynth.connect(this.previewGain);
+      this.previewSignature = signature;
     }
     const freq = Tone.Frequency(pitch, 'midi').toFrequency();
     this.previewSynth.triggerAttackRelease(freq, duration, undefined, velocity / 127);
   }
 
-  async playNote(trackId: string, pitch: number, velocity: number, duration: number, preset: SynthPreset) {
+  async playNote(trackId: string, pitch: number, velocity: number, duration: number, source: SynthSource) {
     await this.ensureStarted();
-    const synth = this.ensureTrackSynth(trackId, preset);
+    const synth = this.ensureTrackSynth(trackId, source);
     const freq = Tone.Frequency(pitch, 'midi').toFrequency();
     synth.triggerAttackRelease(freq, duration, undefined, velocity / 127);
   }
@@ -113,10 +137,10 @@ class SynthEngine {
     toPitch: number,
     velocity: number,
     duration: number,
-    preset: SynthPreset,
+    source: SynthSource,
   ) {
     await this.ensureStarted();
-    const synth = this.ensureTrackSynth(trackId, preset) as unknown as {
+    const synth = this.ensureTrackSynth(trackId, source) as unknown as {
       set: (options: Record<string, unknown>) => void;
       triggerAttack: (note: number, time?: string | number, velocity?: number) => void;
       triggerRelease: (note: number, time?: string | number) => void;
@@ -171,6 +195,7 @@ class SynthEngine {
     this.previewGain?.dispose();
     this.previewSynth = null;
     this.previewGain = null;
+    this.previewSignature = null;
   }
 }
 
diff --git a/src/hooks/useTransport.ts b/src/hooks/useTransport.ts
index 9eeecc20..e62912f6 100644
--- a/src/hooks/useTransport.ts
+++ b/src/hooks/useTransport.ts
@@ -6,7 +6,7 @@ import { useUIStore } from '../store/uiStore';
 import { getAudioEngine } from './useAudioEngine';
 import { loadAudioBlobByKey } from '../services/audioFileManager';
 import { synthEngine } from '../engine/SynthEngine';
-import { createSamplerConfig, samplerEngine } from '../engine/SamplerEngine';
+import { samplerEngine } from '../engine/SamplerEngine';
 import { drumEngine } from '../engine/DrumEngine';
 import { automationEngine } from '../engine/AutomationEngine';
 import {
@@ -25,6 +25,10 @@ import {
   getClipAudibleStartTime,
   getClipAudibleTimelineDuration,
 } from '../utils/clipAudio';
+import {
+  getTrackSamplerConfigFromInstrument,
+  resolveTrackInstrument,
+} from '../utils/trackInstrument';
 import { toastInfo } from './useToast';
 import type { TimelineScrubClip } from '../engine/AudioEngine';
 import { useVST3Store } from '../store/vst3Store';
@@ -360,16 +364,9 @@ export function useTransport() {
           (inst) => inst.trackId === track.id && inst.enabled && inst.online,
         );
 
-        const preset = track.synthPreset ?? 'piano';
-        const samplerConfig = track.samplerConfig
-          ?? (preset === 'sampler' && track.sampler?.audioKey
-            ? createSamplerConfig(track.sampler.audioKey, {
-                rootNote: track.sampler.rootNote ?? 60,
-                trimEnd: track.sampler.sampleDuration,
-                loopEnd: track.sampler.sampleDuration,
-              })
-            : null);
-        const useSampler = !vst3Instrument && !!samplerConfig;
+        const instrument = resolveTrackInstrument(track);
+        const samplerConfig = getTrackSamplerConfigFromInstrument(track);
+        const useSampler = !vst3Instrument && instrument?.kind === 'sampler' && !!samplerConfig;
 
         synthEngine.removeTrackSynth(track.id);
         samplerEngine.removeTrackSampler(track.id);
@@ -384,8 +381,8 @@ export function useTransport() {
               trackNode.inputGain as unknown as Tone.InputNode,
             );
           }
-        } else if (preset !== 'sampler') {
-          synthEngine.ensureTrackSynth(track.id, preset);
+        } else if (instrument?.kind !== 'sampler') {
+          synthEngine.ensureTrackSynth(track.id, instrument ?? (track.synthPreset ?? 'piano'));
         }
 
         const midiClips = mainView === 'session'
@@ -471,7 +468,7 @@ export function useTransport() {
                       note.pitch,
                       Math.max(1, Math.round(velocity * 127)),
                       scheduledDuration,
-                      preset,
+                      instrument ?? (track.synthPreset ?? 'piano'),
                     );
                     return;
                   }
diff --git a/src/utils/__tests__/trackInstrument.test.ts b/src/utils/__tests__/trackInstrument.test.ts
new file mode 100644
index 00000000..fdf93fde
--- /dev/null
+++ b/src/utils/__tests__/trackInstrument.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createDefaultFmInstrument,
+  createDefaultSamplerInstrument,
+  getTrackInstrumentSelectValue,
+  getTrackSamplerConfigFromInstrument,
+  resolveTrackInstrument,
+} from '../trackInstrument';
+
+describe('trackInstrument helpers', () => {
+  it('resolves a subtractive instrument from legacy synth preset state', () => {
+    const instrument = resolveTrackInstrument({
+      trackName: 'keyboard',
+      trackType: 'pianoRoll',
+      instrument: undefined,
+      synthPreset: 'pad',
+      sampler: undefined,
+      samplerConfig: undefined,
+    });
+
+    expect(instrument).toMatchObject({
+      kind: 'subtractive',
+      preset: 'pad',
+    });
+  });
+
+  it('derives sampler config from a canonical sampler instrument', () => {
+    const samplerConfig = getTrackSamplerConfigFromInstrument({
+      trackName: 'keyboard',
+      trackType: 'pianoRoll',
+      instrument: createDefaultSamplerInstrument({
+        audioKey: 'audio:test:sampler',
+        sampleName: 'Glass Vox',
+        rootNote: 48,
+        sampleDuration: 1.5,
+        trimEnd: 1.25,
+        loopEnd: 1.1,
+      }),
+      synthPreset: undefined,
+      sampler: undefined,
+      samplerConfig: undefined,
+    });
+
+    expect(samplerConfig).toMatchObject({
+      audioKey: 'audio:test:sampler',
+      rootNote: 48,
+      trimEnd: 1.25,
+      loopEnd: 1.1,
+    });
+  });
+
+  it('returns an fm selector value for canonical fm instruments', () => {
+    const selectValue = getTrackInstrumentSelectValue({
+      trackName: 'synth',
+      trackType: 'pianoRoll',
+      instrument: createDefaultFmInstrument({ fallbackPreset: 'lead' }),
+      synthPreset: undefined,
+      sampler: undefined,
+      samplerConfig: undefined,
+    });
+
+    expect(selectValue).toBe('fm');
+  });
+});
diff --git a/src/utils/trackInstrument.ts b/src/utils/trackInstrument.ts
index e5e9081b..5f83d350 100644
--- a/src/utils/trackInstrument.ts
+++ b/src/utils/trackInstrument.ts
@@ -19,6 +19,7 @@ type TrackInstrumentSyncInput = Pick<
 >;
 
 type TrackInstrumentSyncState = Pick<Track, 'instrument' | 'synthPreset' | 'sampler' | 'samplerConfig'>;
+export type TrackInstrumentSelectValue = LegacySynthVoicePreset | 'sampler' | 'fm';
 
 const DEFAULT_AMP_ENVELOPE: InstrumentEnvelope = {
   attack: 0.01,
@@ -299,6 +300,27 @@ export function getLegacySynthPresetFromInstrument(instrument: TrackInstrument):
   }
 }
 
+export function resolveTrackInstrument(input: TrackInstrumentSyncInput): TrackInstrument | undefined {
+  return syncTrackInstrumentState(input).instrument;
+}
+
+export function getTrackInstrumentSelectValue(input: TrackInstrumentSyncInput): TrackInstrumentSelectValue {
+  const instrument = resolveTrackInstrument(input);
+
+  if (instrument?.kind === 'subtractive') return instrument.preset;
+  if (instrument?.kind === 'sampler') return 'sampler';
+  if (instrument?.kind === 'fm') return 'fm';
+
+  const fallbackPreset = input.synthPreset ?? getDefaultTrackInstrumentPreset(input.trackName);
+  return fallbackPreset === 'sampler' ? 'sampler' : fallbackPreset;
+}
+
+export function getTrackSamplerConfigFromInstrument(input: TrackInstrumentSyncInput): SamplerConfig | null {
+  const instrument = resolveTrackInstrument(input);
+  if (instrument?.kind !== 'sampler') return null;
+  return buildLegacySamplerState(instrument).samplerConfig ?? null;
+}
+
 function normalizeExistingInstrument(
   input: TrackInstrumentSyncInput,
   instrument: TrackInstrument,
diff --git a/tests/unit/PianoRoll.test.tsx b/tests/unit/PianoRoll.test.tsx
index 4d5a0764..7b26d0fd 100644
--- a/tests/unit/PianoRoll.test.tsx
+++ b/tests/unit/PianoRoll.test.tsx
@@ -158,4 +158,27 @@ describe('PianoRoll', () => {
     expect(screen.getByLabelText('Piano roll navigation status')).toHaveTextContent('1 note selected');
     expect(screen.getByLabelText('Piano roll canvas stub')).toHaveAttribute('data-selected-note-ids', 'note-c4');
   });
+
+  it('writes canonical instrument state when the piano-roll instrument selector changes', () => {
+    render(<PianoRoll />);
+
+    const instrumentSelect = screen.getByLabelText('Track synth preset');
+    fireEvent.change(instrumentSelect, { target: { value: 'sampler' } });
+
+    let track = useProjectStore.getState().project?.tracks[0];
+    expect(track?.instrument).toMatchObject({
+      kind: 'sampler',
+      preset: 'sampler',
+    });
+    expect(screen.getByText('sampler')).toBeInTheDocument();
+
+    fireEvent.change(instrumentSelect, { target: { value: 'pad' } });
+
+    track = useProjectStore.getState().project?.tracks[0];
+    expect(track?.instrument).toMatchObject({
+      kind: 'subtractive',
+      preset: 'pad',
+    });
+    expect(screen.queryByText('sampler')).not.toBeInTheDocument();
+  });
 });
diff --git a/tests/unit/VirtualKeyboard.test.tsx b/tests/unit/VirtualKeyboard.test.tsx
index 73644804..e435a034 100644
--- a/tests/unit/VirtualKeyboard.test.tsx
+++ b/tests/unit/VirtualKeyboard.test.tsx
@@ -57,7 +57,13 @@ describe('VirtualKeyboard', () => {
     render(<VirtualKeyboard />);
 
     fireEvent.keyDown(window, { code: 'KeyA' });
-    expect(synthEngineSpies.ensureTrackSynth).toHaveBeenCalledWith(track.id, 'organ');
+    expect(synthEngineSpies.ensureTrackSynth).toHaveBeenCalledWith(
+      track.id,
+      expect.objectContaining({
+        kind: 'subtractive',
+        preset: 'organ',
+      }),
+    );
     expect(synthEngineSpies.noteOn).toHaveBeenCalledWith(track.id, 60, 96);
     expect(useUIStore.getState().virtualKeyboardPressedPitches).toEqual([60]);
 

From 51c3e3f262512758791cac78f6ef37724811be03 Mon Sep 17 00:00:00 2001
From: ChuxiJ <junmin@acestudio.ai>
Date: Fri, 27 Mar 2026 18:22:09 +0800
Subject: [PATCH 2/2] feat: add piano roll synth editor shell

---
 src/components/pianoroll/PianoRoll.tsx        |  18 +-
 .../pianoroll/SynthInstrumentEditor.tsx       | 885 ++++++++++++++++++
 tests/unit/PianoRoll.test.tsx                 |  21 +-
 tests/unit/SynthInstrumentEditor.test.tsx     |  64 ++
 4 files changed, 984 insertions(+), 4 deletions(-)
 create mode 100644 src/components/pianoroll/SynthInstrumentEditor.tsx
 create mode 100644 tests/unit/SynthInstrumentEditor.test.tsx

diff --git a/src/components/pianoroll/PianoRoll.tsx b/src/components/pianoroll/PianoRoll.tsx
index 0d8c9186..99c00ffa 100644
--- a/src/components/pianoroll/PianoRoll.tsx
+++ b/src/components/pianoroll/PianoRoll.tsx
@@ -5,12 +5,14 @@ import { useUIStore } from '../../store/uiStore';
 import type { PianoRollGrid, SamplerConfig } from '../../types/project';
 import { CHORD_SHAPES, DEFAULT_CHORD_SHAPE_ABBR, getChordShapeByAbbr } from '../../utils/chords';
 import {
+  createDefaultFmInstrument,
   createDefaultSubtractiveInstrument,
   getTrackInstrumentSelectValue,
   resolveTrackInstrument,
   type TrackInstrumentSelectValue,
 } from '../../utils/trackInstrument';
 import { QuickSamplerEditor } from './QuickSamplerEditor';
+import { SynthInstrumentEditor } from './SynthInstrumentEditor';
 import { GeneratePatternDialog } from './GeneratePatternDialog';
 import { PianoRollCanvas } from './PianoRollCanvas';
 import { PianoRollEmptyState } from './PianoRollEmptyState';
@@ -330,8 +332,6 @@ export function PianoRoll() {
           value={instrumentSelectValue}
           onChange={(e) => {
             const nextValue = e.target.value as TrackInstrumentSelectValue;
-            if (nextValue === 'fm') return;
-
             if (nextValue === 'sampler') {
               setTrackSampler(track.id, {
                 audioKey: track.sampler?.audioKey,
@@ -342,6 +342,11 @@ export function PianoRoll() {
               return;
             }
 
+            if (nextValue === 'fm') {
+              setTrackInstrument(track.id, createDefaultFmInstrument());
+              return;
+            }
+
             setTrackInstrument(track.id, createDefaultSubtractiveInstrument(nextValue));
           }}
           className="bg-[#111] border border-[#333] rounded px-2 py-1 text-[11px] text-zinc-300"
@@ -352,8 +357,8 @@ export function PianoRoll() {
           <option value="lead">Lead</option>
           <option value="bass">Bass</option>
           <option value="organ">Organ</option>
+          <option value="fm">FM</option>
           <option value="sampler">Quick Sampler</option>
-          {trackInstrument?.kind === 'fm' && <option value="fm">FM</option>}
         </select>
 
         {clip && <TransformMenu clipId={clip.id} selectedNoteIds={selectedNoteIds} />}
@@ -460,6 +465,13 @@ export function PianoRoll() {
         </div>
       )}
 
+      {trackInstrument && trackInstrument.kind !== 'sampler' && (
+        <SynthInstrumentEditor
+          instrument={trackInstrument}
+          onInstrumentChange={(nextInstrument) => setTrackInstrument(track.id, nextInstrument)}
+        />
+      )}
+
       {clip ? (
         <PianoRollCanvas
           clip={clip}
diff --git a/src/components/pianoroll/SynthInstrumentEditor.tsx b/src/components/pianoroll/SynthInstrumentEditor.tsx
new file mode 100644
index 00000000..74269220
--- /dev/null
+++ b/src/components/pianoroll/SynthInstrumentEditor.tsx
@@ -0,0 +1,885 @@
+import type { ComponentProps, ReactNode } from 'react';
+import type {
+  FmTrackInstrument,
+  InstrumentWaveform,
+  LegacySynthVoicePreset,
+  SubtractiveTrackInstrument,
+} from '../../types/project';
+import { Knob } from '../ui/Knob';
+
+const WAVEFORM_OPTIONS: InstrumentWaveform[] = ['sine', 'triangle', 'square', 'sawtooth'];
+const FILTER_TYPE_OPTIONS: Array<SubtractiveTrackInstrument['settings']['filter']['type']> = ['lowpass', 'highpass', 'bandpass'];
+const LFO_TARGET_OPTIONS: Array<SubtractiveTrackInstrument['settings']['lfo']['target']> = ['off', 'pitch', 'filterCutoff', 'amp', 'pan'];
+const LEGACY_PRESET_OPTIONS: LegacySynthVoicePreset[] = ['piano', 'strings', 'pad', 'lead', 'bass', 'organ'];
+const UNISON_VOICE_OPTIONS = [1, 2, 4, 6, 8];
+
+interface SynthInstrumentEditorProps {
+  instrument: SubtractiveTrackInstrument | FmTrackInstrument;
+  onInstrumentChange: (instrument: SubtractiveTrackInstrument | FmTrackInstrument) => void;
+}
+
+interface SectionProps {
+  title: string;
+  eyebrow?: string;
+  accentClassName?: string;
+  action?: ReactNode;
+  children: ReactNode;
+}
+
+function Section({ title, eyebrow, accentClassName, action, children }: SectionProps) {
+  return (
+    <div className={`rounded-xl border px-3 py-3 ${accentClassName ?? 'border-white/8 bg-white/[0.03]'}`}>
+      <div className="flex items-start justify-between gap-3">
+        <div>
+          {eyebrow && (
+            <div className="text-[11px] font-semibold uppercase tracking-[0.18em] text-zinc-400">
+              {eyebrow}
+            </div>
+          )}
+          <div className="text-sm text-zinc-100">{title}</div>
+        </div>
+        {action}
+      </div>
+      {children}
+    </div>
+  );
+}
+
+function FieldLabel({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <label className="text-[10px] text-zinc-400">
+      <span className="block mb-1 uppercase tracking-[0.14em]">{label}</span>
+      {children}
+    </label>
+  );
+}
+
+function SelectField({
+  ariaLabel,
+  label,
+  value,
+  onChange,
+  children,
+}: {
+  ariaLabel: string;
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+  children: ReactNode;
+}) {
+  return (
+    <FieldLabel label={label}>
+      <select
+        aria-label={ariaLabel}
+        value={value}
+        onChange={(event) => onChange(event.target.value)}
+        className="w-full rounded border border-[#2d3449] bg-[#101827] px-2 py-1 text-[11px] text-zinc-200"
+      >
+        {children}
+      </select>
+    </FieldLabel>
+  );
+}
+
+function ToggleButton({
+  ariaLabel,
+  active,
+  activeLabel,
+  inactiveLabel,
+  onClick,
+}: {
+  ariaLabel: string;
+  active: boolean;
+  activeLabel: string;
+  inactiveLabel: string;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      aria-label={ariaLabel}
+      aria-pressed={active ? 'true' : 'false'}
+      className={`rounded px-2 py-1 text-[10px] font-semibold transition-colors ${
+        active
+          ? 'bg-cyan-500/20 text-cyan-100'
+          : 'bg-white/5 text-zinc-400 hover:bg-white/10'
+      }`}
+      onClick={onClick}
+    >
+      {active ? activeLabel : inactiveLabel}
+    </button>
+  );
+}
+
+function EditorKnob(props: ComponentProps<typeof Knob>) {
+  return <Knob size={38} {...props} />;
+}
+
+function renderWaveformOptions() {
+  return WAVEFORM_OPTIONS.map((waveform) => (
+    <option key={waveform} value={waveform}>
+      {waveform}
+    </option>
+  ));
+}
+
+function renderPresetOptions() {
+  return LEGACY_PRESET_OPTIONS.map((preset) => (
+    <option key={preset} value={preset}>
+      {preset}
+    </option>
+  ));
+}
+
+function renderSubtractiveEditor(
+  instrument: SubtractiveTrackInstrument,
+  onInstrumentChange: (instrument: SubtractiveTrackInstrument) => void,
+) {
+  const { oscillator, ampEnvelope, filter, lfo, unison, glideTime, outputGain } = instrument.settings;
+
+  const updateSettings = (settings: SubtractiveTrackInstrument['settings']) => {
+    onInstrumentChange({
+      ...instrument,
+      settings,
+    });
+  };
+
+  return (
+    <>
+      <Section
+        title={instrument.name}
+        eyebrow="Synth Rack"
+        accentClassName="border-cyan-400/25 bg-cyan-300/[0.06]"
+        action={(
+          <span className="rounded-full border border-cyan-400/25 bg-cyan-500/10 px-2 py-1 text-[10px] uppercase tracking-[0.18em] text-cyan-100">
+            {instrument.preset}
+          </span>
+        )}
+      >
+        <div className="mt-3 grid grid-cols-2 gap-2">
+          <SelectField
+            ariaLabel="Instrument waveform"
+            label="Oscillator"
+            value={oscillator.waveform}
+            onChange={(waveform) => updateSettings({
+              ...instrument.settings,
+              oscillator: {
+                ...oscillator,
+                waveform: waveform as InstrumentWaveform,
+              },
+            })}
+          >
+            {renderWaveformOptions()}
+          </SelectField>
+          <div className="rounded border border-white/8 bg-black/15 px-2 py-2 text-[10px] text-zinc-400">
+            <div className="uppercase tracking-[0.14em] text-zinc-500">Voice</div>
+            <div className="mt-1 text-zinc-200">Canonical subtractive synth state</div>
+            <div className="mt-1 text-zinc-500">Edits write directly into `track.instrument`.</div>
+          </div>
+        </div>
+
+        <div className="mt-3 grid grid-cols-4 gap-3">
+          <EditorKnob
+            value={oscillator.octave}
+            min={-2}
+            max={2}
+            defaultValue={0}
+            step={1}
+            label="Osc Octave"
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              oscillator: {
+                ...oscillator,
+                octave: value,
+              },
+            })}
+          />
+          <EditorKnob
+            value={oscillator.detuneCents}
+            min={-50}
+            max={50}
+            defaultValue={0}
+            step={1}
+            label="Osc Detune"
+            unit="c"
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              oscillator: {
+                ...oscillator,
+                detuneCents: value,
+              },
+            })}
+          />
+          <EditorKnob
+            value={oscillator.level}
+            min={0}
+            max={1}
+            defaultValue={0.9}
+            step={0.01}
+            label="Osc Level"
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              oscillator: {
+                ...oscillator,
+                level: value,
+              },
+            })}
+          />
+          <EditorKnob
+            value={outputGain}
+            min={-18}
+            max={12}
+            defaultValue={0}
+            step={0.5}
+            label="Output Gain"
+            unit="dB"
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              outputGain: value,
+            })}
+          />
+        </div>
+
+        <div className="mt-4">
+          <div className="text-[11px] font-semibold uppercase tracking-[0.16em] text-zinc-400">Amp Envelope</div>
+          <div className="mt-2 grid grid-cols-4 gap-3">
+            <EditorKnob
+              value={ampEnvelope.attack}
+              min={0}
+              max={2}
+              defaultValue={0.01}
+              step={0.01}
+              label="Amp Attack"
+              unit="s"
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                ampEnvelope: {
+                  ...ampEnvelope,
+                  attack: value,
+                },
+              })}
+            />
+            <EditorKnob
+              value={ampEnvelope.decay}
+              min={0}
+              max={2}
+              defaultValue={0.2}
+              step={0.01}
+              label="Amp Decay"
+              unit="s"
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                ampEnvelope: {
+                  ...ampEnvelope,
+                  decay: value,
+                },
+              })}
+            />
+            <EditorKnob
+              value={ampEnvelope.sustain}
+              min={0}
+              max={1}
+              defaultValue={0.7}
+              step={0.01}
+              label="Amp Sustain"
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                ampEnvelope: {
+                  ...ampEnvelope,
+                  sustain: value,
+                },
+              })}
+            />
+            <EditorKnob
+              value={ampEnvelope.release}
+              min={0}
+              max={5}
+              defaultValue={0.5}
+              step={0.01}
+              label="Amp Release"
+              unit="s"
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                ampEnvelope: {
+                  ...ampEnvelope,
+                  release: value,
+                },
+              })}
+            />
+          </div>
+        </div>
+      </Section>
+
+      <Section
+        title="Filter, Modulation, and Width"
+        eyebrow="Motion"
+        action={(
+          <div className="flex items-center gap-2">
+            <ToggleButton
+              ariaLabel="Toggle synth filter"
+              active={filter.enabled}
+              activeLabel="Filter On"
+              inactiveLabel="Filter Off"
+              onClick={() => updateSettings({
+                ...instrument.settings,
+                filter: {
+                  ...filter,
+                  enabled: !filter.enabled,
+                },
+              })}
+            />
+            <ToggleButton
+              ariaLabel="Toggle synth lfo"
+              active={lfo.enabled}
+              activeLabel="LFO On"
+              inactiveLabel="LFO Off"
+              onClick={() => updateSettings({
+                ...instrument.settings,
+                lfo: {
+                  ...lfo,
+                  enabled: !lfo.enabled,
+                },
+              })}
+            />
+          </div>
+        )}
+      >
+        <div className="mt-3 grid grid-cols-2 gap-2">
+          <SelectField
+            ariaLabel="Instrument filter type"
+            label="Filter Type"
+            value={filter.type}
+            onChange={(type) => updateSettings({
+              ...instrument.settings,
+              filter: {
+                ...filter,
+                type: type as SubtractiveTrackInstrument['settings']['filter']['type'],
+              },
+            })}
+          >
+            {FILTER_TYPE_OPTIONS.map((type) => (
+              <option key={type} value={type}>
+                {type}
+              </option>
+            ))}
+          </SelectField>
+          <SelectField
+            ariaLabel="Instrument LFO target"
+            label="LFO Target"
+            value={lfo.target}
+            onChange={(target) => updateSettings({
+              ...instrument.settings,
+              lfo: {
+                ...lfo,
+                target: target as SubtractiveTrackInstrument['settings']['lfo']['target'],
+              },
+            })}
+          >
+            {LFO_TARGET_OPTIONS.map((target) => (
+              <option key={target} value={target}>
+                {target}
+              </option>
+            ))}
+          </SelectField>
+          <SelectField
+            ariaLabel="Instrument LFO waveform"
+            label="LFO Waveform"
+            value={lfo.waveform}
+            onChange={(waveform) => updateSettings({
+              ...instrument.settings,
+              lfo: {
+                ...lfo,
+                waveform: waveform as InstrumentWaveform,
+              },
+            })}
+          >
+            {renderWaveformOptions()}
+          </SelectField>
+          <FieldLabel label="Retrigger">
+            <button
+              type="button"
+              aria-label="Toggle synth LFO retrigger"
+              aria-pressed={lfo.retrigger ? 'true' : 'false'}
+              className={`w-full rounded border px-2 py-1 text-[11px] transition-colors ${
+                lfo.retrigger
+                  ? 'border-cyan-400/35 bg-cyan-500/10 text-cyan-100'
+                  : 'border-white/10 bg-black/15 text-zinc-400 hover:bg-white/5'
+              }`}
+              onClick={() => updateSettings({
+                ...instrument.settings,
+                lfo: {
+                  ...lfo,
+                  retrigger: !lfo.retrigger,
+                },
+              })}
+            >
+              {lfo.retrigger ? 'Restart per note' : 'Free running'}
+            </button>
+          </FieldLabel>
+        </div>
+
+        <div className={`mt-3 grid grid-cols-4 gap-3 ${filter.enabled ? '' : 'opacity-45'}`}>
+          <EditorKnob
+            value={filter.cutoffHz}
+            min={80}
+            max={16000}
+            defaultValue={7200}
+            step={10}
+            label="Filter Cutoff"
+            unit="Hz"
+            disabled={!filter.enabled}
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              filter: {
+                ...filter,
+                cutoffHz: value,
+              },
+            })}
+          />
+          <EditorKnob
+            value={filter.resonance}
+            min={0}
+            max={20}
+            defaultValue={0.2}
+            step={0.1}
+            label="Filter Resonance"
+            disabled={!filter.enabled}
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              filter: {
+                ...filter,
+                resonance: value,
+              },
+            })}
+          />
+          <EditorKnob
+            value={filter.drive}
+            min={0}
+            max={1}
+            defaultValue={0}
+            step={0.01}
+            label="Filter Drive"
+            disabled={!filter.enabled}
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              filter: {
+                ...filter,
+                drive: value,
+              },
+            })}
+          />
+          <EditorKnob
+            value={filter.keyTracking}
+            min={0}
+            max={1}
+            defaultValue={0.1}
+            step={0.01}
+            label="Filter Key Track"
+            disabled={!filter.enabled}
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              filter: {
+                ...filter,
+                keyTracking: value,
+              },
+            })}
+          />
+        </div>
+
+        <div className="mt-4 grid grid-cols-4 gap-3">
+          <EditorKnob
+            value={lfo.rateHz}
+            min={0.1}
+            max={20}
+            defaultValue={5}
+            step={0.1}
+            label="LFO Rate"
+            unit="Hz"
+            disabled={!lfo.enabled}
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              lfo: {
+                ...lfo,
+                rateHz: value,
+              },
+            })}
+          />
+          <EditorKnob
+            value={lfo.depth}
+            min={0}
+            max={1}
+            defaultValue={0}
+            step={0.01}
+            label="LFO Depth"
+            disabled={!lfo.enabled}
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              lfo: {
+                ...lfo,
+                depth: value,
+              },
+            })}
+          />
+          <EditorKnob
+            value={glideTime}
+            min={0}
+            max={1}
+            defaultValue={0}
+            step={0.01}
+            label="Glide Time"
+            unit="s"
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              glideTime: value,
+            })}
+          />
+          <EditorKnob
+            value={unison.detuneCents}
+            min={0}
+            max={40}
+            defaultValue={0}
+            step={0.5}
+            label="Unison Detune"
+            unit="c"
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              unison: {
+                ...unison,
+                detuneCents: value,
+              },
+            })}
+          />
+        </div>
+
+        <div className="mt-4 grid grid-cols-2 gap-2">
+          <SelectField
+            ariaLabel="Instrument unison voices"
+            label="Unison Voices"
+            value={String(unison.voices)}
+            onChange={(voices) => updateSettings({
+              ...instrument.settings,
+              unison: {
+                ...unison,
+                voices: Number(voices),
+              },
+            })}
+          >
+            {UNISON_VOICE_OPTIONS.map((voices) => (
+              <option key={voices} value={voices}>
+                {voices}
+              </option>
+            ))}
+          </SelectField>
+          <div className="grid grid-cols-2 gap-3">
+            <EditorKnob
+              value={unison.stereoSpread}
+              min={0}
+              max={1}
+              defaultValue={0}
+              step={0.01}
+              label="Unison Spread"
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                unison: {
+                  ...unison,
+                  stereoSpread: value,
+                },
+              })}
+            />
+            <EditorKnob
+              value={unison.blend}
+              min={0}
+              max={1}
+              defaultValue={1}
+              step={0.01}
+              label="Unison Blend"
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                unison: {
+                  ...unison,
+                  blend: value,
+                },
+              })}
+            />
+          </div>
+        </div>
+      </Section>
+    </>
+  );
+}
+
+function renderFmEditor(
+  instrument: FmTrackInstrument,
+  onInstrumentChange: (instrument: FmTrackInstrument) => void,
+) {
+  const { carrier, modulator, modulationIndex, feedback, ampEnvelope, outputGain } = instrument.settings;
+  const { fallbackPreset } = instrument;
+
+  const updateSettings = (settings: FmTrackInstrument['settings']) => {
+    onInstrumentChange({
+      ...instrument,
+      settings,
+    });
+  };
+
+  return (
+    <>
+      <Section
+        title={instrument.name}
+        eyebrow="FM Rack"
+        accentClassName="border-fuchsia-400/25 bg-fuchsia-300/[0.06]"
+        action={(
+          <span className="rounded-full border border-fuchsia-400/25 bg-fuchsia-500/10 px-2 py-1 text-[10px] uppercase tracking-[0.18em] text-fuchsia-100">
+            FM
+          </span>
+        )}
+      >
+        <div className="mt-3 grid grid-cols-2 gap-2">
+          <SelectField
+            ariaLabel="Instrument FM fallback preset"
+            label="Fallback Voice"
+            value={fallbackPreset}
+            onChange={(preset) => onInstrumentChange({
+              ...instrument,
+              fallbackPreset: preset as LegacySynthVoicePreset,
+            })}
+          >
+            {renderPresetOptions()}
+          </SelectField>
+          <div className="rounded border border-white/8 bg-black/15 px-2 py-2 text-[10px] text-zinc-400">
+            <div className="uppercase tracking-[0.14em] text-zinc-500">Playback</div>
+            <div className="mt-1 text-zinc-200">FM parameter shell on canonical state</div>
+            <div className="mt-1 text-zinc-500">Current engine falls back to the selected legacy voice.</div>
+          </div>
+        </div>
+
+        <div className="mt-4 grid grid-cols-2 gap-3">
+          <div className="rounded border border-white/8 bg-black/15 px-3 py-3">
+            <div className="text-[11px] font-semibold uppercase tracking-[0.16em] text-zinc-400">Carrier</div>
+            <div className="mt-2">
+              <SelectField
+                ariaLabel="FM carrier waveform"
+                label="Waveform"
+                value={carrier.waveform}
+                onChange={(waveform) => updateSettings({
+                  ...instrument.settings,
+                  carrier: {
+                    ...carrier,
+                    waveform: waveform as InstrumentWaveform,
+                  },
+                })}
+              >
+                {renderWaveformOptions()}
+              </SelectField>
+            </div>
+            <div className="mt-3 grid grid-cols-2 gap-3">
+              <EditorKnob
+                value={carrier.ratio}
+                min={0.25}
+                max={8}
+                defaultValue={1}
+                step={0.25}
+                label="Carrier Ratio"
+                onChange={(value) => updateSettings({
+                  ...instrument.settings,
+                  carrier: {
+                    ...carrier,
+                    ratio: value,
+                  },
+                })}
+              />
+              <EditorKnob
+                value={carrier.level}
+                min={0}
+                max={1}
+                defaultValue={1}
+                step={0.01}
+                label="Carrier Level"
+                onChange={(value) => updateSettings({
+                  ...instrument.settings,
+                  carrier: {
+                    ...carrier,
+                    level: value,
+                  },
+                })}
+              />
+            </div>
+          </div>
+
+          <div className="rounded border border-white/8 bg-black/15 px-3 py-3">
+            <div className="text-[11px] font-semibold uppercase tracking-[0.16em] text-zinc-400">Modulator</div>
+            <div className="mt-2">
+              <SelectField
+                ariaLabel="FM modulator waveform"
+                label="Waveform"
+                value={modulator.waveform}
+                onChange={(waveform) => updateSettings({
+                  ...instrument.settings,
+                  modulator: {
+                    ...modulator,
+                    waveform: waveform as InstrumentWaveform,
+                  },
+                })}
+              >
+                {renderWaveformOptions()}
+              </SelectField>
+            </div>
+            <div className="mt-3 grid grid-cols-2 gap-3">
+              <EditorKnob
+                value={modulator.ratio}
+                min={0.25}
+                max={8}
+                defaultValue={2}
+                step={0.25}
+                label="Modulator Ratio"
+                onChange={(value) => updateSettings({
+                  ...instrument.settings,
+                  modulator: {
+                    ...modulator,
+                    ratio: value,
+                  },
+                })}
+              />
+              <EditorKnob
+                value={modulator.level}
+                min={0}
+                max={1}
+                defaultValue={0.75}
+                step={0.01}
+                label="Modulator Level"
+                onChange={(value) => updateSettings({
+                  ...instrument.settings,
+                  modulator: {
+                    ...modulator,
+                    level: value,
+                  },
+                })}
+              />
+            </div>
+          </div>
+        </div>
+      </Section>
+
+      <Section title="Modulation Index and Envelope" eyebrow="Dynamics">
+        <div className="mt-3 grid grid-cols-3 gap-3">
+          <EditorKnob
+            value={modulationIndex}
+            min={0}
+            max={12}
+            defaultValue={2}
+            step={0.1}
+            label="Modulation Index"
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              modulationIndex: value,
+            })}
+          />
+          <EditorKnob
+            value={feedback}
+            min={0}
+            max={1}
+            defaultValue={0}
+            step={0.01}
+            label="FM Feedback"
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              feedback: value,
+            })}
+          />
+          <EditorKnob
+            value={outputGain}
+            min={-18}
+            max={12}
+            defaultValue={0}
+            step={0.5}
+            label="Output Gain"
+            unit="dB"
+            onChange={(value) => updateSettings({
+              ...instrument.settings,
+              outputGain: value,
+            })}
+          />
+        </div>
+
+        <div className="mt-4">
+          <div className="text-[11px] font-semibold uppercase tracking-[0.16em] text-zinc-400">Amp Envelope</div>
+          <div className="mt-2 grid grid-cols-4 gap-3">
+            <EditorKnob
+              value={ampEnvelope.attack}
+              min={0}
+              max={2}
+              defaultValue={0.01}
+              step={0.01}
+              label="Amp Attack"
+              unit="s"
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                ampEnvelope: {
+                  ...ampEnvelope,
+                  attack: value,
+                },
+              })}
+            />
+            <EditorKnob
+              value={ampEnvelope.decay}
+              min={0}
+              max={2}
+              defaultValue={0.2}
+              step={0.01}
+              label="Amp Decay"
+              unit="s"
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                ampEnvelope: {
+                  ...ampEnvelope,
+                  decay: value,
+                },
+              })}
+            />
+            <EditorKnob
+              value={ampEnvelope.sustain}
+              min={0}
+              max={1}
+              defaultValue={0.7}
+              step={0.01}
+              label="Amp Sustain"
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                ampEnvelope: {
+                  ...ampEnvelope,
+                  sustain: value,
+                },
+              })}
+            />
+            <EditorKnob
+              value={ampEnvelope.release}
+              min={0}
+              max={5}
+              defaultValue={0.5}
+              step={0.01}
+              label="Amp Release"
+              unit="s"
+              onChange={(value) => updateSettings({
+                ...instrument.settings,
+                ampEnvelope: {
+                  ...ampEnvelope,
+                  release: value,
+                },
+              })}
+            />
+          </div>
+        </div>
+      </Section>
+    </>
+  );
+}
+
+export function SynthInstrumentEditor({ instrument, onInstrumentChange }: SynthInstrumentEditorProps) {
+  return (
+    <div className="grid grid-cols-[minmax(240px,1.25fr)_minmax(220px,1fr)] gap-3 border-b border-[#1f2536] bg-[#0b1220] px-3 py-3 shrink-0">
+      {instrument.kind === 'fm'
+        ? renderFmEditor(instrument, onInstrumentChange)
+        : renderSubtractiveEditor(instrument, onInstrumentChange)}
+    </div>
+  );
+}
diff --git a/tests/unit/PianoRoll.test.tsx b/tests/unit/PianoRoll.test.tsx
index 7b26d0fd..4396bcdd 100644
--- a/tests/unit/PianoRoll.test.tsx
+++ b/tests/unit/PianoRoll.test.tsx
@@ -38,6 +38,12 @@ vi.mock('../../src/components/pianoroll/QuickSamplerEditor', () => ({
   QuickSamplerEditor: () => <div>sampler</div>,
 }));
 
+vi.mock('../../src/components/pianoroll/SynthInstrumentEditor', () => ({
+  SynthInstrumentEditor: ({ instrument }: { instrument: { kind: string } }) => (
+    <div data-testid="synth-editor">{instrument.kind}</div>
+  ),
+}));
+
 vi.mock('../../src/components/pianoroll/GeneratePatternDialog', () => ({
   GeneratePatternDialog: () => null,
 }));
@@ -163,6 +169,8 @@ describe('PianoRoll', () => {
     render(<PianoRoll />);
 
     const instrumentSelect = screen.getByLabelText('Track synth preset');
+    expect(screen.getByTestId('synth-editor')).toHaveTextContent('subtractive');
+
     fireEvent.change(instrumentSelect, { target: { value: 'sampler' } });
 
     let track = useProjectStore.getState().project?.tracks[0];
@@ -171,6 +179,17 @@ describe('PianoRoll', () => {
       preset: 'sampler',
     });
     expect(screen.getByText('sampler')).toBeInTheDocument();
+    expect(screen.queryByTestId('synth-editor')).not.toBeInTheDocument();
+
+    fireEvent.change(instrumentSelect, { target: { value: 'fm' } });
+
+    track = useProjectStore.getState().project?.tracks[0];
+    expect(track?.instrument).toMatchObject({
+      kind: 'fm',
+      preset: 'fm',
+    });
+    expect(screen.getByTestId('synth-editor')).toHaveTextContent('fm');
+    expect(screen.queryByText('sampler')).not.toBeInTheDocument();
 
     fireEvent.change(instrumentSelect, { target: { value: 'pad' } });
 
@@ -179,6 +198,6 @@ describe('PianoRoll', () => {
       kind: 'subtractive',
       preset: 'pad',
     });
-    expect(screen.queryByText('sampler')).not.toBeInTheDocument();
+    expect(screen.getByTestId('synth-editor')).toHaveTextContent('subtractive');
   });
 });
diff --git a/tests/unit/SynthInstrumentEditor.test.tsx b/tests/unit/SynthInstrumentEditor.test.tsx
new file mode 100644
index 00000000..0e12605e
--- /dev/null
+++ b/tests/unit/SynthInstrumentEditor.test.tsx
@@ -0,0 +1,64 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { SynthInstrumentEditor } from '../../src/components/pianoroll/SynthInstrumentEditor';
+import { createDefaultFmInstrument, createDefaultSubtractiveInstrument } from '../../src/utils/trackInstrument';
+
+describe('SynthInstrumentEditor', () => {
+  it('updates subtractive oscillator waveform and filter cutoff through canonical instrument state', () => {
+    const onInstrumentChange = vi.fn();
+
+    render(
+      <SynthInstrumentEditor
+        instrument={createDefaultSubtractiveInstrument('pad')}
+        onInstrumentChange={onInstrumentChange}
+      />,
+    );
+
+    fireEvent.change(screen.getByLabelText('Instrument waveform'), { target: { value: 'square' } });
+    expect(onInstrumentChange).toHaveBeenLastCalledWith(expect.objectContaining({
+      kind: 'subtractive',
+      settings: expect.objectContaining({
+        oscillator: expect.objectContaining({ waveform: 'square' }),
+      }),
+    }));
+
+    fireEvent.contextMenu(screen.getByLabelText('Filter Cutoff knob'));
+    fireEvent.change(screen.getByLabelText('Filter Cutoff exact value'), { target: { value: '3200' } });
+    fireEvent.keyDown(screen.getByLabelText('Filter Cutoff exact value'), { key: 'Enter' });
+
+    expect(onInstrumentChange).toHaveBeenLastCalledWith(expect.objectContaining({
+      kind: 'subtractive',
+      settings: expect.objectContaining({
+        filter: expect.objectContaining({ cutoffHz: 3200 }),
+      }),
+    }));
+  });
+
+  it('updates FM fallback preset and modulation index through canonical instrument state', () => {
+    const onInstrumentChange = vi.fn();
+
+    render(
+      <SynthInstrumentEditor
+        instrument={createDefaultFmInstrument()}
+        onInstrumentChange={onInstrumentChange}
+      />,
+    );
+
+    fireEvent.change(screen.getByLabelText('Instrument FM fallback preset'), { target: { value: 'bass' } });
+    expect(onInstrumentChange).toHaveBeenLastCalledWith(expect.objectContaining({
+      kind: 'fm',
+      fallbackPreset: 'bass',
+    }));
+
+    fireEvent.contextMenu(screen.getByLabelText('Modulation Index knob'));
+    fireEvent.change(screen.getByLabelText('Modulation Index exact value'), { target: { value: '7.5' } });
+    fireEvent.keyDown(screen.getByLabelText('Modulation Index exact value'), { key: 'Enter' });
+
+    expect(onInstrumentChange).toHaveBeenLastCalledWith(expect.objectContaining({
+      kind: 'fm',
+      settings: expect.objectContaining({
+        modulationIndex: 7.5,
+      }),
+    }));
+  });
+});