feat: added fine tune region position feature

src/components/track/Region.css

@@ -97,11 +97,23 @@
   background-color: #5a9b6a;
 }
 
-/* Region pencil trigger inside content */
+/* Left-side button cluster inside region-content */
-.region-pencil-btn {
+.region-left-buttons {
   position: absolute;
   top: 4px;
   left: 4px;
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 2px;
+  z-index: 2;
+}
+
+/* Shared style for all region content buttons */
+.region-pencil-btn,
+.region-waveform-btn,
+.region-spectrogram-btn,
+.region-hybrid-btn {
   background: rgba(0, 0, 0, 0.25);
   color: #fff;
   border: 1px solid rgba(255, 255, 255, 0.2);
@@ -109,77 +121,61 @@
   padding: 2px;
   margin: 0;
   cursor: pointer;
-  z-index: 2;
   display: inline-flex;
   align-items: center;
   justify-content: center;
 }
 
-.region-pencil-btn:hover {
+.region-pencil-btn:hover,
+.region-spectrogram-btn:hover,
+.region-hybrid-btn:hover {
   background: rgba(0, 0, 0, 0.35);
 }
 
 .region-waveform-btn {
-  position: absolute;
-  top: 4px;
-  left: 4px;
-  background: rgba(0, 0, 0, 0.25);
-  color: #fff;
-  border: 1px solid rgba(255, 255, 255, 0.2);
-  border-radius: 3px;
-  padding: 2px;
-  margin: 0;
-  cursor: pointer;
-  z-index: 2;
   display: none;
-  align-items: center;
-  justify-content: center;
 }
 
 .region-waveform-btn:hover {
   background: rgba(0, 0, 0, 0.35);
 }
 
-.region-spectrogram-btn {
+/* Fine-move widget: sits inline in the left button cluster */
-  position: absolute;
+.region-fine-move-widget {
-  top: 4px;
+  display: flex;
-  left: 4px;
+  flex-direction: row;
+  align-items: center;
+  gap: 2px;
+}
+
+.region-fine-move-btn {
   background: rgba(0, 0, 0, 0.25);
   color: #fff;
   border: 1px solid rgba(255, 255, 255, 0.2);
   border-radius: 3px;
   padding: 2px;
   margin: 0;
-  cursor: pointer;
+  cursor: ew-resize;
-  z-index: 2;
   display: inline-flex;
   align-items: center;
   justify-content: center;
+  flex-shrink: 0;
 }
 
-.region-spectrogram-btn:hover {
+.region-fine-move-btn:hover {
   background: rgba(0, 0, 0, 0.35);
 }
 
-.region-hybrid-btn {
+.region-fine-move-label {
-  position: absolute;
-  top: 4px;
-  left: 24px;
   background: rgba(0, 0, 0, 0.25);
   color: #fff;
   border: 1px solid rgba(255, 255, 255, 0.2);
   border-radius: 3px;
-  padding: 2px;
+  padding: 2px 4px;
-  margin: 0;
+  font-size: 10px;
-  cursor: pointer;
+  white-space: nowrap;
-  z-index: 2;
+  line-height: 1;
-  display: inline-flex;
+  user-select: none;
-  align-items: center;
-  justify-content: center;
-}
-
-.region-hybrid-btn:hover {
-  background: rgba(0, 0, 0, 0.35);
 }
 
 /* Instrument dropdown specific styles */

src/components/track/RegionItem.tsx

@@ -1,7 +1,7 @@
 import React, { useState, useRef, useEffect } from 'react';
 import './Region.css';
 import { FaPencilAlt, FaPlus } from 'react-icons/fa';
-import { MdGraphicEq } from 'react-icons/md';
+import { MdGraphicEq, MdSwapHoriz } from 'react-icons/md';
 import type { ResizeAction } from '../interfaces';
 import { REGION_CONSTANTS, DEBUG_MODE } from '../../constants';
 import { KGMidiRegion } from '../../core/region/KGMidiRegion';
@@ -35,6 +35,8 @@ interface RegionItemProps {
   // Enter hybrid mode (show + when piano roll is open with the opposite region type selected)
   showHybridButton?: boolean;
   onOpenHybrid?: (regionId: string) => void;
+  // Fine-move end callback — passes raw (unscaled) mouse pixel delta
+  onFineMoveEnd?: (regionId: string, rawPixelDelta: number) => void;
   // MIDI region data for rendering notes
   midiRegion?: KGMidiRegion;
   // Audio region data for rendering waveform
@@ -60,6 +62,7 @@ const RegionItem: React.FC<RegionItemProps> = ({
   onOpenSpectrogram,
   showHybridButton,
   onOpenHybrid,
+  onFineMoveEnd,
   midiRegion,
   audioRegion,
   audioBuffer
@@ -77,6 +80,14 @@ const RegionItem: React.FC<RegionItemProps> = ({
   const isDraggingRef = useRef<boolean>(false);
   const isPendingDragRef = useRef<boolean>(false);
 
+  // Fine-move state
+  const [isFineDragging, setIsFineDragging] = useState(false);
+  const [fineDeltaDisplay, setFineDeltaDisplay] = useState('+0.00');
+  const [fineTranslateX, setFineTranslateX] = useState(0);
+  const isFineDraggingRef = useRef(false);
+  const fineMouseStartXRef = useRef(0);
+  const fineRawDeltaRef = useRef(0);
+
   // Canvas ref for note visualization
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
   const regionContentRef = useRef<HTMLDivElement | null>(null);
@@ -534,11 +545,48 @@ const RegionItem: React.FC<RegionItemProps> = ({
     document.removeEventListener('mouseup', handleGlobalMouseUp);
   };
 
+  // Fine-move handlers
+  const handleFineMoveGlobalMouseMove = (e: MouseEvent) => {
+    if (!isFineDraggingRef.current) return;
+    const rawDelta = e.clientX - fineMouseStartXRef.current;
+    fineRawDeltaRef.current = rawDelta;
+    const scaledDelta = rawDelta * REGION_CONSTANTS.FINE_MOVE_SPEED_RATIO;
+    setFineTranslateX(scaledDelta);
+    setFineDeltaDisplay(scaledDelta >= 0 ? `+${scaledDelta.toFixed(2)}` : `${scaledDelta.toFixed(2)}`);
+  };
+
+  const handleFineMoveGlobalMouseUp = () => {
+    if (!isFineDraggingRef.current) return;
+    isFineDraggingRef.current = false;
+    setIsFineDragging(false);
+    setFineTranslateX(0);
+    document.removeEventListener('mousemove', handleFineMoveGlobalMouseMove);
+    document.removeEventListener('mouseup', handleFineMoveGlobalMouseUp);
+    if (fineRawDeltaRef.current !== 0 && onFineMoveEnd) {
+      onFineMoveEnd(id, fineRawDeltaRef.current);
+    }
+  };
+
+  const handleFineMoveMouseDown = (e: React.MouseEvent<HTMLButtonElement>) => {
+    e.preventDefault();
+    e.stopPropagation();
+    if (isFineDraggingRef.current) return;
+    fineMouseStartXRef.current = e.clientX;
+    fineRawDeltaRef.current = 0;
+    isFineDraggingRef.current = true;
+    setIsFineDragging(true);
+    setFineDeltaDisplay('+0.00');
+    document.addEventListener('mousemove', handleFineMoveGlobalMouseMove);
+    document.addEventListener('mouseup', handleFineMoveGlobalMouseUp);
+  };
+
   // Clean up event listeners on unmount
   useEffect(() => {
     return () => {
       document.removeEventListener('mousemove', handleGlobalMouseMove);
       document.removeEventListener('mouseup', handleGlobalMouseUp);
+      document.removeEventListener('mousemove', handleFineMoveGlobalMouseMove);
+      document.removeEventListener('mouseup', handleFineMoveGlobalMouseUp);
     };
   }, []);
 
@@ -555,7 +603,7 @@ const RegionItem: React.FC<RegionItemProps> = ({
     <div
       key={id}
       className={`track-region ${isDragging ? 'dragging' : ''} ${isSelected ? 'selected' : ''} ${audioRegion ? 'audio-region' : ''}`}
-      style={{ ...style, cursor }}
+      style={{ ...style, cursor, ...(isFineDragging ? { transform: `translateX(${fineTranslateX}px)`, zIndex: 100 } : {}) }}
       onMouseMove={handleMouseMove}
       onMouseLeave={handleMouseLeave}
       onMouseDown={handleMouseDown}
@@ -568,6 +616,7 @@ const RegionItem: React.FC<RegionItemProps> = ({
         {name}
       </div>
       <div className={`region-content${audioRegion ? ' audio-region-content' : ''}`} ref={regionContentRef}>
+        <div className="region-left-buttons">
           {!audioRegion && (
             <button
               className="region-pencil-btn"
@@ -654,6 +703,21 @@ const RegionItem: React.FC<RegionItemProps> = ({
               <FaPlus size={10} />
             </button>
           )}
+          <div className="region-fine-move-widget">
+            <button
+              className="region-fine-move-btn"
+              title="Fine move"
+              onMouseDown={handleFineMoveMouseDown}
+              onClick={(e) => { e.preventDefault(); e.stopPropagation(); }}
+              aria-label="Fine move region"
+            >
+              <MdSwapHoriz size={10} />
+            </button>
+            {isFineDragging && (
+              <span className="region-fine-move-label">{fineDeltaDisplay}</span>
+            )}
+          </div>
+        </div>
         <canvas ref={canvasRef} />
       </div>
     </div>

src/components/track/TrackGridItem.tsx

@@ -24,6 +24,7 @@ interface TrackGridItemProps {
   onRegionResizeEnd?: (regionId: string, finalBarNumber: number, finalLength: number) => void;
   onRegionDrag?: (regionId: string, newBarNumber: number, newTrackIndex: number) => void;
   onRegionDragEnd?: (regionId: string, finalBarNumber: number, finalTrackIndex: number) => void;
+  onRegionFineMoveEnd?: (regionId: string, deltaInBars: number) => void;
   onRegionClick?: (regionId: string) => void;
   onOpenPianoRoll?: (regionId: string) => void;
   onOpenSpectrogram?: (regionId: string) => void;
@@ -49,6 +50,7 @@ const TrackGridItem: React.FC<TrackGridItemProps> = ({
   onRegionResizeEnd,
   onRegionDrag,
   onRegionDragEnd,
+  onRegionFineMoveEnd,
   onRegionClick,
   onOpenPianoRoll,
   onOpenSpectrogram,
@@ -505,6 +507,14 @@ const TrackGridItem: React.FC<TrackGridItemProps> = ({
     }
   };
 
+  // Handle fine-move end — convert raw pixel delta to delta in bars and pass up
+  const handleRegionFineMoveEnd = (regionId: string, rawPixelDelta: number) => {
+    const barWidth = containerWidth / maxBars;
+    if (barWidth <= 0) return;
+    const deltaInBars = (rawPixelDelta * REGION_CONSTANTS.FINE_MOVE_SPEED_RATIO) / barWidth;
+    onRegionFineMoveEnd?.(regionId, deltaInBars);
+  };
+
   // Handle region click
   const handleRegionClick = (regionId: string) => {
     if (DEBUG_MODE.TRACK_GRID_ITEM) {
@@ -570,6 +580,7 @@ const TrackGridItem: React.FC<TrackGridItemProps> = ({
             onDragStart={handleRegionDragStart}
             onDrag={handleRegionDrag}
             onDragEnd={handleRegionDragEnd}
+            onFineMoveEnd={handleRegionFineMoveEnd}
             // Keep onClick for selection-only logic if needed by parent
             onClick={handleRegionClick}
             // New explicit pencil action — disabled for audio regions

src/components/track/TrackGridPanel.tsx

@@ -473,6 +473,44 @@ const TrackGridPanel: React.FC<TrackGridPanelProps> = ({
     }
   };
 
+  // Handle fine-move end — execute MoveRegionCommand with float-precision beat position
+  const handleRegionFineMoveEnd = (regionId: string, deltaInBars: number) => {
+    const region = regions.find(r => r.id === regionId);
+    if (!region) return;
+    const track = tracks.find(t => t.getId().toString() === region.trackId);
+    if (!track) return;
+    const coreRegion = track.getRegions().find(r => r.getId() === regionId);
+    if (!coreRegion) return;
+
+    const beatsPerBar = timeSignature.numerator;
+    const newStartFromBeat = Math.max(0, coreRegion.getStartFromBeat() + deltaInBars * beatsPerBar);
+    if (newStartFromBeat === coreRegion.getStartFromBeat()) return;
+
+    try {
+      // Use constructor directly (NOT fromBarCoordinates) to preserve float precision
+      const command = new MoveRegionCommand(
+        regionId,
+        newStartFromBeat,
+        track.getId().toString(),
+        region.trackIndex
+      );
+      KGCore.instance().executeCommand(command);
+
+      if (DEBUG_MODE.TRACK_GRID_PANEL) {
+        console.log(`Fine-moved region ${regionId}: startFromBeat=${newStartFromBeat}`);
+      }
+
+      const newBarNumber = newStartFromBeat / beatsPerBar + 1;
+      onRegionUpdated?.(
+        regionId,
+        { barNumber: newBarNumber, trackId: region.trackId, trackIndex: region.trackIndex },
+        { startBeat: newStartFromBeat, length: coreRegion.getLength() }
+      );
+    } catch (error) {
+      console.error('Error executing fine-move:', error);
+    }
+  };
+
   // Handle region click
   const handleRegionClick = (regionId: string) => {
     if (DEBUG_MODE.TRACK_GRID_PANEL) {
@@ -664,6 +702,7 @@ const TrackGridPanel: React.FC<TrackGridPanelProps> = ({
           onRegionResizeEnd={handleRegionResizeEnd}
           onRegionDrag={handleRegionDrag}
           onRegionDragEnd={handleRegionDragEnd}
+          onRegionFineMoveEnd={handleRegionFineMoveEnd}
           onRegionClick={handleRegionClick}
           onOpenPianoRoll={onOpenPianoRoll}
           onOpenSpectrogram={onOpenSpectrogram}

src/constants/uiConstants.ts

@@ -28,6 +28,8 @@ export const REGION_CONSTANTS = {
   EDGE_THRESHOLD: 10,
   // Minimum region length in bars
   MIN_REGION_LENGTH: 1.0,
+  // Fine-move speed ratio: mouse pixels to region movement pixels
+  FINE_MOVE_SPEED_RATIO: 0.25,
 };
 
 // Piano roll related constants