Phrase mode: player-style transport, separate display toggles, preview cursor + stepping

- Transport restructured like a music player: Start/Pause, step
  back/forward buttons (while previewing), Preview, Retry, Next.
- Virtual instrument and Hint moved out of the transport row into a
  separate display-toggles row using switch-style toggles (same visual
  language as tuner/metronome switches) — pure show/hide, no run state.
- Preview now tracks a cursor: the current preview event is marked in
  the notation (caret + color via existing currentIdx pipeline).
- Preview stepping: pause-free stepping forward/backward one event at
  a time; each step replays from the cursor position so notes can be
  located on the fretboard. Arrow keys ←/→ work while previewing.
- With Hint active, the fretboard/piano marks the preview cursor note
  (displayIdx follows the preview cursor).
- previewIdx resets on structural changes and when the preview ends.

src/App.css

@@ -1172,3 +1172,37 @@ button {
   margin: 0;
   text-align: center;
 }
+
+/* ---- Transport step group (preview stepping) ---------------------------- */
+.transport-step-group {
+  display: flex;
+  gap: 6px;
+}
+
+.step-button {
+  padding: 0.4rem 0.55rem;
+}
+
+/* ---- Display toggles (virtual instrument / hint show-hide) -------------- */
+/* Separate row of pure show/hide switches, styled like the tuner and
+   metronome switches — visually distinct from transport actions. */
+.display-toggles {
+  display: flex;
+  justify-content: center;
+  gap: var(--spacing-lg);
+  margin-top: 10px;
+}
+
+.display-toggle {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.display-toggle-label {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 12px;
+  color: var(--color-text-muted);
+}

src/App.tsx

@@ -165,6 +165,12 @@ function App() {
           case 'n':
             phraseRef.current?.next();
             break;
+          case 'arrowleft':
+            phraseRef.current?.previewStep(-1);
+            break;
+          case 'arrowright':
+            phraseRef.current?.previewStep(1);
+            break;
           case 's':
             phraseRef.current?.skip();
             break;
@@ -430,6 +436,7 @@ function App() {
                 <>
                   <div className="help-item"><span>Start / Pause / Resume</span><span className="shortcut-key">Space</span></div>
                   <div className="help-item"><span>Preview phrase (Play / Stop)</span><span className="shortcut-key">P</span></div>
+                  <div className="help-item"><span>While previewing: step note forward / back</span><span className="shortcut-key">→ / ←</span></div>
                   <div className="help-item"><span>Retry phrase</span><span className="shortcut-key">R</span></div>
                   <div className="help-item"><span>New melody / next bars</span><span className="shortcut-key">N</span></div>
                   <div className="help-item"><span>Skip note (at your pace)</span><span className="shortcut-key">S</span></div>

src/components/PhraseTrainer.tsx

@@ -35,11 +35,12 @@ import { TUNINGS, getFretboardPositions } from '../music/Tunings';
 import { INSTRUMENT_DEFINITIONS, resolveClefTranspose } from '../music/InstrumentConfigs';
 const AUTO_CONTINUE_DELAY_MS = 1500;
 
-import { Play, Pause, RotateCcw, SkipForward, Volume2, Square, ChevronDown, Music2, Upload, HelpCircle, Guitar } from 'lucide-react';
+import { Play, Pause, RotateCcw, SkipForward, SkipBack, Volume2, Square, ChevronDown, Music2, Upload, HelpCircle, Guitar } from 'lucide-react';
 
 export interface PhraseHandle {
     pauseToggle: () => void;
     previewToggle: () => void;
+    previewStep: (dir: 1 | -1) => void;
     retry: () => void;
     skip: () => void;
     next: () => void;
@@ -328,6 +329,7 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
         useImperativeHandle(ref, () => ({
             pauseToggle: () => trainer?.pauseToggle(),
             previewToggle: () => trainer?.previewToggle(),
+            previewStep: (dir) => trainer?.previewStep(dir),
             retry: () => trainer?.retry(),
             skip: () => trainer?.skip(),
             pause: () => trainer?.pause(),
@@ -337,8 +339,11 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
         // ---- Hints --------------------------------------------------------------
         const activeScore = trainer.activeScore;
         const events = scoreEvents(activeScore);
-        const currentMidi = trainer.currentIdx >= 0 && events[trainer.currentIdx]?.pitch
+        // While previewing, the hint instruments follow the preview cursor so
-            ? events[trainer.currentIdx]!.pitch!.midi
+        // the user can find notes on the fretboard while listening.
+        const displayIdx = trainer.phase === 'preview' ? trainer.previewIdx : trainer.currentIdx;
+        const currentMidi = displayIdx >= 0 && events[displayIdx]?.pitch
+            ? events[displayIdx]!.pitch!.midi
             : null;
 
         const hintPositions = useMemo(() => {
@@ -714,7 +719,7 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
                     {scoreOk ? (
                         <PhraseSheetMusic
                             score={trainer.activeScore}
-                            currentIdx={trainer.currentIdx}
+                            currentIdx={trainer.phase === 'preview' ? trainer.previewIdx : trainer.currentIdx}
                             statuses={trainer.statuses}
                             clef={activeClef}
                             transpose={activeTranspose}
@@ -758,8 +763,28 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
                     </button>
                     {!settings.zenMode && (
                         <>
+                            {trainer.phase === 'preview' && (
+                                <div className="transport-step-group" role="group" aria-label="Preview stepping">
+                                    <button
+                                        className="hint-button step-button"
+                                        onClick={() => trainer.previewStep(-1)}
+                                        title="One event back (while previewing)"
+                                        aria-label="Step back"
+                                    >
+                                        <SkipBack size={16} />
+                                    </button>
+                                    <button
+                                        className="hint-button step-button"
+                                        onClick={() => trainer.previewStep(1)}
+                                        title="One event forward (while previewing)"
+                                        aria-label="Step forward"
+                                    >
+                                        <SkipForward size={16} />
+                                    </button>
+                                </div>
+                            )}
                             <button
-                                className="hint-button"
+                                className={`hint-button ${trainer.phase === 'preview' ? 'active' : ''}`}
                                 onClick={trainer.previewToggle}
                                 title="Preview the phrase (P)"
                             >
@@ -799,28 +824,45 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
                             )}
                         </>
                     )}
-                    {!settings.zenMode && currentInstrumentDef.showTuning && (
-                        <button
-                            className={`hint-button ${settings.showFretboard ? 'active' : ''}`}
-                            onClick={() => setSettings(s => ({ ...s, showFretboard: !s.showFretboard }))}
-                            title={`Toggle Virtual ${currentInstrumentDef.displayName} (Keyboard Shortcut: V)`}
-                        >
-                            <Guitar size={18} />
-                            {currentInstrumentDef.id === 'piano' ? 'Piano' : 'Guitar'}
-                        </button>
-                    )}
-                    {!settings.zenMode && (
-                        <button
-                            className={`hint-button ${settings.showHint ? 'active' : ''}`}
-                            onClick={() => setSettings(s => ({ ...s, showHint: !s.showHint }))}
-                            title="Keyboard Shortcut: H"
-                        >
-                            <HelpCircle size={18} />
-                            {settings.showHint ? "Hide Hint" : "Show Hint"}
-                        </button>
-                    )}
                 </div>
 
+                {/* Display toggles — separate row, switch style (like the
+                    tuner/metronome switches): pure show/hide, no run state. */}
+                {!settings.zenMode && (
+                    <div className="display-toggles">
+                        {currentInstrumentDef.showTuning && (
+                            <div className="display-toggle">
+                                <span className="display-toggle-label">
+                                    <Guitar size={15} />
+                                    {currentInstrumentDef.id === 'piano' ? 'Piano' : 'Guitar'}
+                                </span>
+                                <button
+                                    className={`switch-button ${settings.showFretboard ? 'active' : ''}`}
+                                    onClick={() => setSettings(s => ({ ...s, showFretboard: !s.showFretboard }))}
+                                    title={`Toggle Virtual ${currentInstrumentDef.displayName} (Keyboard Shortcut: V)`}
+                                    aria-label={`Show virtual ${currentInstrumentDef.displayName}`}
+                                >
+                                    <div className="switch-thumb" />
+                                </button>
+                            </div>
+                        )}
+                        <div className="display-toggle">
+                            <span className="display-toggle-label">
+                                <HelpCircle size={15} />
+                                Hint
+                            </span>
+                            <button
+                                className={`switch-button ${settings.showHint ? 'active' : ''}`}
+                                onClick={() => setSettings(s => ({ ...s, showHint: !s.showHint }))}
+                                title="Keyboard Shortcut: H"
+                                aria-label="Show hint"
+                            >
+                                <div className="switch-thumb" />
+                            </button>
+                        </div>
+                    </div>
+                )}
+
 
                 {/* Hint instruments */}
                 {(settings.showHint || settings.showFretboard) && currentInstrumentDef.showTuning && (

src/hooks/usePhraseTrainer.ts

@@ -56,6 +56,8 @@ const REARM_AFTER_SUSTAINED_MS = 2500;
 
 export interface PhraseTrainerApi {
     readonly phase: PhrasePhase;
+    /** Event index the preview cursor points at (-1 when not previewing). */
+    readonly previewIdx: number;
     /** Active slice the user is currently working through (may be a resume tail). */
     readonly activeScore: Score;
     readonly statuses: NoteStatus[];
@@ -76,6 +78,9 @@ export interface PhraseTrainerApi {
     retry: () => void;
     skip: () => void;
     previewToggle: () => void;
+    /** While previewing: step one event forward/backward (player-style).
+      * Plays the note at the new position and moves the preview indicator. */
+    previewStep: (dir: 1 | -1) => void;
     virtualTap: (midi: number) => void;
     /** External pause (settings dialog, visibility change handled internally). */
     pause: () => void;
@@ -95,6 +100,7 @@ export function usePhraseTrainer(
     const [countInLeft, setCountInLeft] = useState(0);
     const [error, setError] = useState<string | null>(null);
     const [repeatedNoteBlocked, setRepeatedNoteBlocked] = useState(false);
+    const [previewIdx, setPreviewIdx] = useState(-1);
     const [accumulated, setAccumulated] = useState<PhraseSummary>({ total: 0, matched: 0, missed: 0, skipped: 0 });
 
     // ---- Active slice (resume tails replace it) ---------------------------
@@ -102,6 +108,7 @@ export function usePhraseTrainer(
 
     const matcherRef = useRef<PhraseMatcher | null>(null);
     const repeatBlockedRef = useRef(false);
+    const previewIdxRef = useRef(-1);
     const phaseRef = useRef<PhrasePhase>('ready');
     const paceRef = useRef(config.pace);
     const configRef = useRef(config);
@@ -157,6 +164,8 @@ export function usePhraseTrainer(
         setAccumulated({ total: 0, matched: 0, missed: 0, skipped: 0 });
         audioEngine.cancelGroup(PREVIEW_GROUP);
         audioEngine.cancelGroup(CLICK_GROUP);
+        previewIdxRef.current = -1;
+        setPreviewIdx(-1);
         setPhaseBoth('ready');
         setCurrentIdx(-1);
         setCountInLeft(0);
@@ -485,25 +494,26 @@ export function usePhraseTrainer(
         advanceStep(m);
     }, [advanceStep]);
 
-    const previewToggle = useCallback(() => {
+    const stopPreview = useCallback(() => {
-        if (phaseRef.current === 'preview') {
+        audioEngine.cancelGroup(PREVIEW_GROUP);
-            audioEngine.cancelGroup(PREVIEW_GROUP);
+        if (previewTimerRef.current) { clearTimeout(previewTimerRef.current); previewTimerRef.current = null; }
-            if (previewTimerRef.current) { clearTimeout(previewTimerRef.current); previewTimerRef.current = null; }
+        previewIdxRef.current = -1;
-            setPhaseBoth('ready');
+        setPreviewIdx(-1);
-            return;
+        setPhaseBoth('ready');
-        }
+    }, [setPhaseBoth]);
-        pause();
+
-        runTokenRef.current++;
+    const playPreviewFrom = useCallback((fromIdx: number, token: number) => {
-        const token = runTokenRef.current;
         void audioEngine.ensureRunning().then(() => {
             if (runTokenRef.current !== token) return;
             const bpm = sanitizeBpm(configRef.current.bpm);
             const spb = 60 / bpm;
             const t0 = audioEngine.now() + 0.15;
             const vol = configRef.current.previewVolume ?? 0.4;
+            const startTick = fromIdx > 0 ? events[fromIdx].startTick : 0;
             for (const e of events) {
                 if (!e.pitch) continue;
-                audioEngine.scheduleNote(e.pitch.midi, t0 + (e.startTick / PPQ) * spb, (e.durationTicks / PPQ) * spb, vol, PREVIEW_GROUP);
+                if (e.startTick < startTick) continue;
+                audioEngine.scheduleNote(e.pitch.midi, t0 + ((e.startTick - startTick) / PPQ) * spb, (e.durationTicks / PPQ) * spb, vol, PREVIEW_GROUP);
             }
             // Tempo pace: click along with the preview so the rhythm is
             // audible while listening (quarter beats over the full span).
@@ -511,20 +521,47 @@ export function usePhraseTrainer(
             // its clicks (no ghost metronomes after an aborted preview).
             if (paceRef.current === 'tempo' && configRef.current.clickSound) {
                 const totalTicks = events.reduce((a, e) => Math.max(a, e.startTick + e.durationTicks), 0);
-                const beats = Math.floor(totalTicks / PPQ);
+                const beats = Math.floor((totalTicks - startTick) / PPQ);
                 for (let i = 0; i < beats; i++) {
-                    audioEngine.playClickAt(t0 + i * spb, CLICK_VOLUME, i % 4 === 0, PREVIEW_GROUP);
+                    audioEngine.playClickAt(t0 + i * spb, CLICK_VOLUME, (fromIdx + i) % 4 === 0, PREVIEW_GROUP);
                 }
             }
             setPhaseBoth('preview');
-            const totalSec = (events.reduce((a, e) => Math.max(a, e.startTick + e.durationTicks), 0) / PPQ) * spb;
+            const totalSec = ((events.reduce((a, e) => Math.max(a, e.startTick + e.durationTicks), 0) - startTick) / PPQ) * spb;
+            if (previewTimerRef.current) clearTimeout(previewTimerRef.current);
             previewTimerRef.current = setTimeout(() => {
                 if (runTokenRef.current === token) {
                     setPhaseBoth('ready');
+                    setPreviewIdx(-1);
                 }
             }, 150 + totalSec * 1000 + 200);
         });
-    }, [events, pause, setPhaseBoth]);
+    }, [events, setPhaseBoth]);
+
+    const previewToggle = useCallback(() => {
+        if (phaseRef.current === 'preview') {
+            stopPreview();
+            return;
+        }
+        pause();
+        runTokenRef.current++;
+        const token = runTokenRef.current;
+        setPreviewIdx(0);
+        previewIdxRef.current = 0;
+        playPreviewFrom(0, token);
+    }, [pause, playPreviewFrom, stopPreview]);
+
+    /** Player-style stepping while previewing: move the cursor, play that
+      * single note so the user can find it on the instrument. */
+    const previewStep = useCallback((dir: 1 | -1) => {
+        if (phaseRef.current !== 'preview') return;
+        const nextIdx = Math.max(0, Math.min(events.length - 1, previewIdxRef.current + dir));
+        if (nextIdx === previewIdxRef.current) return;
+        previewIdxRef.current = nextIdx;
+        setPreviewIdx(nextIdx);
+        const token = ++runTokenRef.current;
+        playPreviewFrom(nextIdx, token);
+    }, [events.length, playPreviewFrom]);
 
     const virtualTap = useCallback((midi: number) => {
         const p = phaseRef.current;
@@ -602,6 +639,7 @@ export function usePhraseTrainer(
         statuses,
         currentIdx,
         countInLeft,
+        previewIdx,
         scoreStart: scoreStartRef.current,
         spb: spbRef.current,
         error,
@@ -611,6 +649,7 @@ export function usePhraseTrainer(
         retry,
         skip,
         previewToggle,
+        previewStep,
         virtualTap,
         pause,
         stop,