From 263b6f6b6966fa91923f07505246d47855a53aea Mon Sep 17 00:00:00 2001
From: OpenClaw <openclaw@nyx>
Date: Mon, 14 Sep 2026 18:44:14 +0000
Subject: [PATCH] Arpeggio sequences + auto-start on first note
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Sequence mode: bars (2/4/6/8) with one chord per bar, chosen by
  functional rules (I->IV/V/vi...), diatonic cycle, or random (no immediate
  repeats); deterministic via melody seed. Chord symbols per bar in the
  score model (chordSymbols) rendered above the staff via setSection.
- Rhythm: quarters or eighths (cycling up/down through the pattern).
- Single-chord mode unchanged (whole path, overflow bars if needed).
- Auto-start: 'Start on first note (no count-in)' — step pace begins the
  run as soon as the mic detects the first note; no start press needed.
- 'New' button re-rolls the progression (new seed).
- Tests 174/174.
---
 src/components/PhraseSheetMusic.tsx |   8 ++
 src/components/PhraseTrainer.tsx    |  42 ++++++-
 src/hooks/usePhraseTrainer.ts       |  16 ++-
 src/music/arpeggioGenerator.test.ts |  47 ++++++++
 src/music/arpeggioGenerator.ts      | 165 ++++++++++++++++++++++++----
 src/score/model.ts                  |   3 +
 src/types/SettingsTypes.ts          |  11 ++
 7 files changed, 265 insertions(+), 27 deletions(-)

diff --git a/src/components/PhraseSheetMusic.tsx b/src/components/PhraseSheetMusic.tsx
index d74ec50..c85ab60 100644
--- a/src/components/PhraseSheetMusic.tsx
+++ b/src/components/PhraseSheetMusic.tsx
@@ -272,6 +272,14 @@ export const PhraseSheetMusic: React.FC<PhraseSheetMusicProps> = ({
                     if (r === 0) treble.addTimeSignature(`${score.meter.numerator}/${score.meter.denominator}`);
                     treble.setMeasure(measure.number);
                 }
+                // Chord symbol above the staff (bar-indexed), drawn via the
+                // stave's annotation area so it shifts with the clef offset.
+                const chordSym = score.chordSymbols?.[m];
+                if (chordSym) {
+                    try {
+                        treble.setSection(chordSym, 0);
+                    } catch { /* courtesy label — never fatal */ }
+                }
                 let bass: Stave | null = null;
                 if (isGrand) {
                     bass = new Stave(x, y + 130, barWidth);
diff --git a/src/components/PhraseTrainer.tsx b/src/components/PhraseTrainer.tsx
index 9f8ff30..49c16ab 100644
--- a/src/components/PhraseTrainer.tsx
+++ b/src/components/PhraseTrainer.tsx
@@ -210,6 +210,10 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
                     pattern: phrase.arpeggioPattern,
                     coverage: phrase.arpeggioCoverage,
                     meter: { numerator: phrase.meterNumerator, denominator: 4 },
+                    bars: phrase.arpeggioBars,
+                    progression: phrase.arpeggioProgression,
+                    rhythm: phrase.arpeggioRhythm,
+                    seed: melodySeed,
                 }, pool);
             }
             if (phrase.material === 'library') {
@@ -225,6 +229,7 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
         }, [phrase.material, phrase.keyTonic, phrase.keyMode, phrase.bars, phrase.meterNumerator,
             phrase.rhythmLevel, phrase.scaleDirection, phrase.scaleCoverage, phrase.libraryId,
             phrase.arpeggioDegree, phrase.arpeggioPattern, phrase.arpeggioCoverage,
+            phrase.arpeggioBars, phrase.arpeggioProgression, phrase.arpeggioRhythm, melodySeed,
             melodySeed, pool, importedScore]);
 
         const fullScore: Result<Score> | null = useMemo(() => {
@@ -252,6 +257,7 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
                 clickSound: phrase.clickSound,
                 inputMode: phrase.inputMode,
                 previewVolume: settings.autoPlayVolume ?? 0.4,
+                autoStartOnNote: phrase.autoStartOnNote,
             },
             listening,
             micError,
@@ -310,7 +316,7 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
         }, [scoreOk, fixedMaterial, pool, fullScore]);
 
         const nextAction = useCallback(() => {
-            if (phrase.material === 'melody') {
+            if (phrase.material === 'melody' || (phrase.material === 'arpeggio' && phrase.arpeggioBars > 1)) {
                 setMelodySeed(s => (s + 1) % 999983);
             } else if (fixedMaterial && scoreOk) {
                 const total = fullScore!.value.measures.length;
@@ -499,7 +505,7 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
                                 <RotateCcw size={18} />
                                 Retry
                             </button>
-                            {(phrase.material === 'melody' || fixedMaterial) && (
+                            {(phrase.material === 'melody' || phrase.material === 'arpeggio' || fixedMaterial) && (
                                 <button className="hint-button" onClick={nextAction} title="New melody / next bars (N)">
                                     <SkipForward size={18} />
                                     {phrase.material === 'melody' ? 'New' : 'Next'}
@@ -520,7 +526,7 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
                                 <RotateCcw size={18} />
                                 Retry
                             </button>
-                            {(phrase.material === 'melody' || fixedMaterial) && (
+                            {(phrase.material === 'melody' || phrase.material === 'arpeggio' || fixedMaterial) && (
                                 <button className="hint-button" onClick={nextAction} title="New / Next (N)">
                                     <SkipForward size={18} />
                                     {phrase.material === 'melody' ? 'New' : 'Next'}
@@ -622,7 +628,7 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
                             {phrase.material === 'arpeggio' && (
                                 <>
                                     <label>Chord
-                                        <select value={phrase.arpeggioDegree} onChange={e => setPhrase({ arpeggioDegree: e.target.value })}>
+                                        <select value={phrase.arpeggioDegree} onChange={e => setPhrase({ arpeggioDegree: e.target.value, arpeggioBars: 1 })}>
                                             {(Object.keys(ARPEGGIO_DEGREE_LABELS) as ArpeggioDegree[]).map(d => (
                                                 <option key={d} value={d}>{ARPEGGIO_DEGREE_LABELS[d]}</option>
                                             ))}
@@ -642,6 +648,26 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
                                             <option value="two-octave">Two octaves</option>
                                         </select>
                                     </label>
+                                    <label>Length
+                                        <select value={phrase.arpeggioBars} onChange={e => setPhrase({ arpeggioBars: Math.max(1, Math.min(8, Number(e.target.value))) })}>
+                                            {[1, 2, 4, 6, 8].map(b => <option key={b} value={b}>{b === 1 ? 'Single chord' : `${b} bars`}</option>)}
+                                        </select>
+                                    </label>
+                                    {phrase.arpeggioBars > 1 && (
+                                        <label>Chords
+                                            <select value={phrase.arpeggioProgression} onChange={e => setPhrase({ arpeggioProgression: e.target.value as PhraseSettings['arpeggioProgression'] })}>
+                                                <option value="functional">Functional (I-IV-V...)</option>
+                                                <option value="diatonic-cycle">Diatonic cycle</option>
+                                                <option value="random">Random</option>
+                                            </select>
+                                        </label>
+                                    )}
+                                    <label>Rhythm
+                                        <select value={phrase.arpeggioRhythm} onChange={e => setPhrase({ arpeggioRhythm: e.target.value as PhraseSettings['arpeggioRhythm'] })}>
+                                            <option value="quarters">Quarter notes</option>
+                                            <option value="eighths">Eighth notes</option>
+                                        </select>
+                                    </label>
                                     <label>Meter
                                         <select value={phrase.meterNumerator} onChange={e => setPhrase({ meterNumerator: Number(e.target.value) === 3 ? 3 : 4 })}>
                                             <option value={4}>4/4</option>
@@ -761,6 +787,14 @@ export const PhraseTrainer = forwardRef<PhraseHandle, PhraseTrainerProps>(
                                 />
                                 Auto-continue
                             </label>
+                            <label className="phrase-check">
+                                <input
+                                    type="checkbox"
+                                    checked={phrase.autoStartOnNote}
+                                    onChange={e => setPhrase({ autoStartOnNote: e.target.checked })}
+                                />
+                                Start on first note (no count-in)
+                            </label>
                         </div>
                         {phrase.pace === 'tempo' && (
                             <p className="phrase-note">The run clicks a full count-in bar, then one click per beat. The metronome pendulum mirrors these beats — set the tempo on the metronome tool.</p>
diff --git a/src/hooks/usePhraseTrainer.ts b/src/hooks/usePhraseTrainer.ts
index c25ea2c..518a9f7 100644
--- a/src/hooks/usePhraseTrainer.ts
+++ b/src/hooks/usePhraseTrainer.ts
@@ -34,6 +34,9 @@ export interface PhraseTrainerConfig {
     readonly clickSound: boolean;
     readonly inputMode: 'mic' | 'virtual';
     readonly previewVolume?: number;
+    /** Auto-start: begin without count-in as soon as the mic detects the
+     *  first note (step pace only — tempo needs the scheduled clock). */
+    readonly autoStartOnNote?: boolean;
 }
 
 export interface PhraseSummary {
@@ -282,7 +285,18 @@ export function usePhraseTrainer(
         const unsubscribe = subscribeRawFrames(frame => {
             if (configRef.current.inputMode !== 'mic') return;
             const p = phaseRef.current;
-            if (p !== 'countIn' && p !== 'playing') return;
+            // Auto-start: first detected note begins the run immediately
+            // (no count-in) — only in step pace, only from 'ready', mic only.
+            if (
+                p === 'ready' &&
+                configRef.current.autoStartOnNote &&
+                paceRef.current === 'step'
+            ) {
+                startRef.current?.();
+                // Fall through: this frame feeds the fresh run below.
+            }
+            const p2 = phaseRef.current;
+            if (p2 !== 'countIn' && p2 !== 'playing') return;
             // Pitched speaker output (preview, virtual instruments) must not
             // be scored; while audible the matcher sees no frames at all.
             if (audioEngine.isAudible()) return;
diff --git a/src/music/arpeggioGenerator.test.ts b/src/music/arpeggioGenerator.test.ts
index 1e62427..4f3705c 100644
--- a/src/music/arpeggioGenerator.test.ts
+++ b/src/music/arpeggioGenerator.test.ts
@@ -89,3 +89,50 @@ describe('generateArpeggio', () => {
         expect(a).toEqual(b);
     });
 });
+
+describe('generateArpeggio — sequence mode', () => {
+    it('generates one chord per bar with functional progression', () => {
+        const r = generateArpeggio({ ...base, degree: 'I', pattern: 'up', coverage: 'one-octave', bars: 4, progression: 'functional', seed: 7 }, pool);
+        expect(r.ok).toBe(true);
+        if (!r.ok) return;
+        expect(r.value.measures.length).toBe(4);
+        expect(r.value.chordSymbols?.length).toBe(4);
+        expect(r.value.chordSymbols?.[0]).toBe('C'); // starts on I
+        // bar boundaries: each bar starts on a chord root? (not enforced) — but ticks align
+        const ev = scoreEvents(r.value);
+        expect(validateScore(r.value)).toEqual([]);
+        // 4 beats per bar × 4 bars = 16 notes in quarters mode
+        expect(ev.length).toBe(16);
+        // deterministic
+        const r2 = generateArpeggio({ ...base, degree: 'I', pattern: 'up', coverage: 'one-octave', bars: 4, progression: 'functional', seed: 7 }, pool);
+        expect(r2.ok && JSON.stringify(scoreEvents(r2.value)) === JSON.stringify(ev)).toBe(true);
+    });
+
+    it('diatonic cycle walks I ii iii IV V vi vii', () => {
+        const r = generateArpeggio({ ...base, degree: 'I', pattern: 'up', coverage: 'one-octave', bars: 7, progression: 'diatonic-cycle', seed: 1 }, pool);
+        expect(r.ok).toBe(true);
+        if (!r.ok) return;
+        const syms = r.value.chordSymbols!;
+        expect(syms).toEqual(['C', 'Dm', 'Em', 'F', 'G', 'Am', 'Bdim']);
+    });
+
+    it('eighths rhythm doubles notes per bar', () => {
+        const r = generateArpeggio({ ...base, degree: 'I', pattern: 'up', coverage: 'one-octave', bars: 2, progression: 'functional', rhythm: 'eighths', seed: 3 }, pool);
+        expect(r.ok).toBe(true);
+        if (!r.ok) return;
+        const ev = scoreEvents(r.value);
+        expect(ev.length).toBe(16); // 2 bars × 4 beats × 2
+        expect(ev[0].durationTicks).toBe(240);
+        expect(validateScore(r.value)).toEqual([]);
+    });
+
+    it('random avoids repeating the same chord back-to-back', () => {
+        const r = generateArpeggio({ ...base, degree: 'I', pattern: 'up', coverage: 'one-octave', bars: 6, progression: 'random', seed: 11 }, pool);
+        expect(r.ok).toBe(true);
+        if (!r.ok) return;
+        const syms = r.value.chordSymbols!;
+        for (let i = 1; i < syms.length; i++) {
+            expect(syms[i]).not.toBe(syms[i - 1]);
+        }
+    });
+});
diff --git a/src/music/arpeggioGenerator.ts b/src/music/arpeggioGenerator.ts
index 82899de..acd6873 100644
--- a/src/music/arpeggioGenerator.ts
+++ b/src/music/arpeggioGenerator.ts
@@ -11,10 +11,15 @@
 import { PPQ, validateScore, type Result, type Score, type ScoreEvent } from '../score/model';
 import { keyFor, type KeyContext, type ModeId } from './scales';
 import { STEP_LETTERS, LETTER_PC, type StepLetter } from '../score/model';
+import { makeRng } from './melodyGenerator';
 
 export type ArpeggioDegree = 'I' | 'ii' | 'iii' | 'IV' | 'V' | 'vi' | 'vii0';
 export type ArpeggioPattern = 'up' | 'down' | 'updown' | '1235';
 export type ArpeggioCoverage = 'one-octave' | 'two-octave';
+/** How the chord per bar is chosen in sequence mode. */
+export type ArpeggioProgression = 'random' | 'functional' | 'diatonic-cycle';
+/** Rhythm density for arpeggio sequences. */
+export type ArpeggioRhythm = 'quarters' | 'eighths';
 
 export interface ArpeggioConfig {
     readonly keyTonic: string;
@@ -23,6 +28,12 @@ export interface ArpeggioConfig {
     readonly pattern: ArpeggioPattern;
     readonly coverage: ArpeggioCoverage;
     readonly meter: { readonly numerator: 3 | 4; readonly denominator: 4 };
+    /** Sequence mode: bars > 1 with chord progression selection. */
+    readonly bars?: number;
+    readonly progression?: ArpeggioProgression;
+    readonly rhythm?: ArpeggioRhythm;
+    /** Seed for progression selection (deterministic). */
+    readonly seed?: number;
 }
 
 /** Degree index (0-based) into the scale for each arpeggio degree label. */
@@ -38,6 +49,20 @@ export const ARPEGGIO_DEGREE_LABELS: Record<ArpeggioDegree, string> = {
 const degreePc = (d: { step: StepLetter; alter: number }): number =>
     (LETTER_PC[STEP_LETTERS.indexOf(d.step)] + d.alter + 144) % 12;
 
+/** Chord symbol name for a diatonic degree, e.g. "C", "Am", "Bdim". */
+function chordNameFor(key: KeyContext, degreeIndex: number): string {
+    const d = key.degrees[degreeIndex];
+    const third = key.degrees[(degreeIndex + 2) % 7];
+    const fifth = key.degrees[(degreeIndex + 4) % 7];
+    const root = d.step + (d.alter < 0 ? 'b'.repeat(-d.alter) : '#'.repeat(d.alter));
+    const thirdInterval = (degreePc(third) - degreePc(d) + 12) % 12;
+    const fifthInterval = (degreePc(fifth) - degreePc(d) + 12) % 12;
+    let suffix = '';
+    if (thirdInterval === 3 && fifthInterval === 7) suffix = 'm';
+    else if (thirdInterval === 3 && fifthInterval === 6) suffix = 'dim';
+    return root + suffix;
+}
+
 /**
  * Chord-tone midi notes of the diatonic triad on `degreeIndex` (0-based),
  * intersected with the playable pool, ascending.
@@ -132,47 +157,143 @@ export function generateArpeggio(
     const pool = Array.from(new Set(eligiblePitches.filter(m => Number.isInteger(m)))).sort((a, b) => a - b);
     if (pool.length === 0) return { ok: false, error: 'No playable notes in the selected range — widen the note set.' };
 
-    const degreeIndex = DEGREE_INDEX[config.degree];
-    const path = buildPath(key, degreeIndex, pool, config.coverage, config.pattern);
-    if (!path || path.length === 0) {
-        return {
-            ok: false,
-            error: 'The complete arpeggio does not fit the playable range — widen the range (strings/fret window) or pick another degree.',
-        };
+    const bars = config.bars ?? 1;
+    const pattern = config.pattern;
+    const coverage = config.coverage;
+
+    // ---- Chord sequence ----------------------------------------------------
+    // Single-bar mode: the chosen degree for all bars (bars is 1).
+    // Sequence mode: one chord per bar, chosen by progression rule.
+    const degreeIndices: number[] = [];
+    if (bars === 1) {
+        degreeIndices.push(DEGREE_INDEX[config.degree]);
+    } else {
+        const rng = makeRng(config.seed ?? 1);
+        const pick = <T,>(arr: T[]): T => arr[Math.floor(rng() * arr.length)];
+        for (let b = 0; b < bars; b++) {
+            if (b === 0) {
+                // Start on the user-chosen degree (or tonic default)
+                degreeIndices.push(DEGREE_INDEX[config.degree]);
+                continue;
+            }
+            const prev = degreeIndices[b - 1];
+            if (config.progression === 'diatonic-cycle') {
+                degreeIndices.push((prev + 1) % 7);
+            } else if (config.progression === 'functional') {
+                // Simple tonal function rules (major-oriented; mirrored for
+                // minor by degree relationships below):
+                //   I   -> {IV, V, vi}
+                //   ii  -> {V}
+                //   iii -> {IV, vi}
+                //   IV  -> {I, V}
+                //   V   -> {I, vi}
+                //   vi  -> {ii, IV}
+                //   vii -> {I}
+                const NEXT: Record<number, number[]> = {
+                    0: [3, 4, 5],
+                    1: [4],
+                    2: [3, 5],
+                    3: [0, 4],
+                    4: [0, 5],
+                    5: [1, 3],
+                    6: [0],
+                };
+                degreeIndices.push(pick(NEXT[prev] ?? [0]));
+            } else {
+                // random: any diatonic degree, avoid immediate repetition
+                const candidates = [0, 1, 2, 3, 4, 5, 6].filter(d => d !== prev);
+                degreeIndices.push(pick(candidates));
+            }
+        }
     }
 
-    // ---- Quarter-note rhythm, final note extended to fill its bar ---------
+    // ---- Path per bar: one arpeggio cycle per chord -------------------------
     const full = config.meter.numerator * PPQ;
-    if (path.length * PPQ > 8 * full) {
-        return { ok: false, error: 'This arpeggio is longer than 8 bars — reduce the coverage.' };
+    const perBarSegments: { path: number[]; degreeIndex: number }[] = [];
+    for (const di of degreeIndices) {
+        const path = buildPath(key, di, pool, coverage, pattern);
+        if (!path || path.length === 0) {
+            return {
+                ok: false,
+                error: 'The arpeggio does not fit the playable range — widen the range (strings/fret window) or pick another degree.',
+            };
+        }
+        perBarSegments.push({ path, degreeIndex: di });
     }
-    const barCount = Math.max(1, Math.ceil((path.length * PPQ) / full));
-    const totalTicks = barCount * full;
-    const lastDuration = PPQ + (totalTicks - path.length * PPQ);
 
+    // ---- Events: fit each segment into one bar ------------------------------
+    const rhythm = config.rhythm ?? 'quarters';
     const events: ScoreEvent[] = [];
+    const chordSymbols: (string | null)[] = [];
     let cursor = 0;
-    for (let i = 0; i < path.length; i++) {
-        const dur = i === path.length - 1 ? lastDuration : PPQ;
-        const spelled = spellInKey(key, path[i]);
-        if (!spelled) return { ok: false, error: 'Internal error spelling arpeggio pitch.' };
-        events.push({ id: `a${i}`, startTick: cursor, durationTicks: dur, pitch: { midi: path[i], ...spelled } });
-        cursor += dur;
+    for (let b = 0; b < bars; b++) {
+        const { path, degreeIndex } = perBarSegments[b];
+        chordSymbols.push(chordNameFor(key, degreeIndex));
+        if (bars === 1) {
+            // Single-bar mode (v1 behavior): whole path, final note extended
+            // to fill the bar — or, when the path overflows one bar, spread
+            // over the needed bars with the overflow in the last note.
+            const barCount = Math.max(1, Math.ceil((path.length * PPQ) / full));
+            const totalTicks = barCount * full;
+            const lastDuration = PPQ + (totalTicks - path.length * PPQ);
+            path.forEach((midi, n) => {
+                const spelled = spellInKey(key, midi);
+                if (!spelled) return;
+                const dur = n === path.length - 1 ? lastDuration : PPQ;
+                events.push({ id: `a${b}-${n}`, startTick: cursor, durationTicks: dur, pitch: { midi, ...spelled } });
+                cursor += dur;
+            });
+            continue;
+        }
+        // Sequence mode: fit the bar exactly. 'quarters': one note per beat,
+        // cycling up/down through the path. 'eighths': two notes per beat.
+        const slots = rhythm === 'quarters' ? 1 : 2;
+        const notesPerBar = config.meter.numerator * slots;
+        const line: number[] = [];
+        let dir = 1;
+        let lastIdx = 0;
+        while (line.length < notesPerBar) {
+            line.push(path[lastIdx]);
+            if (lastIdx + dir < 0 || lastIdx + dir >= path.length) dir = -dir;
+            else lastIdx += dir;
+        }
+        const noteDur = full / notesPerBar;
+        line.forEach((midi, n) => {
+            const spelled = spellInKey(key, midi);
+            if (!spelled) return;
+            events.push({
+                id: `a${b}-${n}`,
+                startTick: cursor,
+                durationTicks: noteDur,
+                pitch: { midi, ...spelled },
+            });
+            cursor += noteDur;
+        });
     }
 
     const chordName = `${key.tonic} ${ARPEGGIO_DEGREE_LABELS[config.degree]}`;
     const patternLabel = { up: 'up', down: 'down', updown: 'up & down', '1235': '1-2-3-5' }[config.pattern];
+    // Single-bar paths can overflow into extra bars (updown/two-octave);
+    // sequence mode always has exactly `bars` measures.
+    const totalMeasures = bars === 1 ? Math.max(1, Math.ceil((cursor) / full)) : bars;
+    const title = bars === 1
+        ? `Arpeggio — ${chordName} (${patternLabel}, ${coverage})`
+        : `Arpeggio — ${key.tonic}: ${bars} bars (${config.progression ?? 'functional'})`;
     const score: Score = {
         version: 1,
-        id: `arpeggio-${config.keyTonic}-${config.keyMode}-${config.degree}-${config.pattern}-${config.coverage}-${config.meter.numerator}4`,
-        title: `Arpeggio — ${chordName} (${patternLabel}, ${config.coverage})`,
+        id: `arpeggio-${config.keyTonic}-${config.keyMode}-${config.degree}-${config.pattern}-${config.coverage}-${bars}b-${config.progression ?? 'single'}-${config.seed ?? 0}`,
+        title,
         meter: config.meter,
         key: { tonic: config.keyTonic, mode: config.keyMode, signature: key.signature },
-        measures: Array.from({ length: barCount }, (_, i) => ({
+        measures: Array.from({ length: totalMeasures }, (_, i) => ({
             number: i + 1,
             startTick: i * full,
             durationTicks: full,
         })),
+        chordSymbols: bars === 1
+            // repeat the single chord symbol across the overflow bars
+            ? Array.from({ length: totalMeasures }, () => chordSymbols[0])
+            : chordSymbols,
         voices: [{ id: 'melody', events }],
     };
     const problems = validateScore(score);
diff --git a/src/score/model.ts b/src/score/model.ts
index f9f30aa..32e4641 100644
--- a/src/score/model.ts
+++ b/src/score/model.ts
@@ -91,6 +91,9 @@ export interface Score {
     readonly measures: ScoreMeasure[];
     /** Exactly one voice in v1. */
     readonly voices: ReadonlyArray<{ readonly id: 'melody'; readonly events: ScoreEvent[] }>;
+    /** Optional chord symbol per bar index (0-based), e.g. "C", "Am", "G7".
+     *  Rendered above the staff; absent = no symbol for that bar. */
+    readonly chordSymbols?: ReadonlyArray<string | null>;
     readonly source?: ScoreSource;
 }
 
diff --git a/src/types/SettingsTypes.ts b/src/types/SettingsTypes.ts
index a606698..084b42a 100644
--- a/src/types/SettingsTypes.ts
+++ b/src/types/SettingsTypes.ts
@@ -57,6 +57,10 @@ export interface PhraseSettings {
     arpeggioDegree: string; // ArpeggioDegree
     arpeggioPattern: 'up' | 'down' | 'updown' | '1235';
     arpeggioCoverage: 'one-octave' | 'two-octave';
+    /** Sequence mode: bars per exercise (1 = single chord). */
+    arpeggioBars: number;
+    arpeggioProgression: 'random' | 'functional' | 'diatonic-cycle';
+    arpeggioRhythm: 'quarters' | 'eighths';
     /** Phrase-local fret window (guitar/bass) — overrides the note set. */
     fretWindowEnabled: boolean;
     fretMin: number;
@@ -71,6 +75,9 @@ export interface PhraseSettings {
      *  new melody) after a short pause — keeps practice flowing. */
     autoContinue: boolean;
     inputMode: 'mic' | 'virtual';
+    /** Begin the run as soon as the first note is played (no count-in,
+     *  step pace only). */
+    autoStartOnNote: boolean;
 }
 
 export const DEFAULT_PHRASE_SETTINGS: PhraseSettings = {
@@ -86,6 +93,9 @@ export const DEFAULT_PHRASE_SETTINGS: PhraseSettings = {
     arpeggioDegree: 'I',
     arpeggioPattern: 'up',
     arpeggioCoverage: 'one-octave',
+    arpeggioBars: 1,
+    arpeggioProgression: 'functional',
+    arpeggioRhythm: 'quarters',
     fretWindowEnabled: false,
     fretMin: 0,
     fretMax: 4,
@@ -96,6 +106,7 @@ export const DEFAULT_PHRASE_SETTINGS: PhraseSettings = {
     clickSound: false,
     autoContinue: true,
     inputMode: 'mic',
+    autoStartOnNote: false,
 };
 
 export function getPhraseSettings(s: AppSettings): PhraseSettings {