Vocal phrase refactor

[elicwhite]

Stacked on #84. Merge #84 first.

What changed

Type structure — single source of truth for vocal data

Removed top-level notes[] and lyrics[] from NormalizedVocalPart. All vocal content is now accessed through phrase grouping:

• NormalizedVocalPart.notePhrases[].notes[] — vocal notes (was: NormalizedVocalPart.notes + redundant copy under each phrase)
• NormalizedVocalPart.notePhrases[].lyrics[] — lyrics belonging to each phrase
• NormalizedVocalPart.staticLyricPhrases[] — note 106 display-only phrases (HARM2/3)

Previously the same notes/lyrics existed in two places (top-level array + per-phrase). Consumers had to know which to use, and a malformed file could cause them to disagree. The new structure has one location per piece of data.

New fields on NormalizedVocalPart

• rangeShifts[] — vocal range shift markers (MIDI note 0). Per-part because PART VOCALS and HARM1 often have distinct sets that must be preserved separately for round-trip.
• lyricShifts[] — vocal lyric shift markers (MIDI note 1). Same per-part rationale.
• textEvents[] — raw text events on the vocal track (stance markers, Band_PlayFacialAnim, etc.). YARG considers a VocalsPart non-empty iff it has phrases OR text events; without storing these, vocal tracks with only stance markers (no notes/lyrics/phrases) round-trip to empty and the track disappears.

New field on NormalizedVocalPhrase

• player?: 1 | 2 — versus player tag (PART VOCALS only). Note 105 → player 1, note 106 → player 2. Required for versus-mode rendering. Previously, note 106 phrases were stored separately in staticLyricPhrases on PART VOCALS, which lost the distinction between "this is a player 2 scoring phrase" and "this is a HARM2/3 static lyric phrase".

PART VOCALS phrase merging

PART VOCALS now merges note 105 + note 106 phrase boundaries into a single notePhrases list (with player tags), matching YARG's MoonSongLoader.Vocals.cs behavior. Both notes create scoring phrases in YARG; they only differ in versus-player attribution. Previously we treated 105 and 106 as separate phrase lists, which caused notes near 106 boundaries to appear "orphaned" (~10K charts in the corpus had this artifact).

Harmonies keep 105/106 separate

HARM1/2/3 keep distinct 105 (scoring) and 106 (static lyric) phrase lists for lossless round-trip. The writer needs to emit each on its original MIDI note number, and CopyDown relies on HARM1's vocalPhrases (note 105 only) to know which phrases to clone to HARM2/3.

HARM3 CopyDownPhrases

HARM3 now clones staticLyricPhrases from HARM2 (in addition to scoring phrases from HARM1), matching YARG CopyDownPhrases exactly. Previously HARM3 had no static lyric phrases unless authored directly on the HARM3 track.

Lyric text preservation

NormalizedLyricEvent.text now stores the original unstripped text including markup symbols (#, ^, +, =, $, _, §, etc.). Consumers should use the flags bitmask for semantic interpretation rather than parsing the text directly. Previously we stripped flag symbols and replaced = with -, which made round-trip writing incorrect (writers couldn't reconstruct the original text).

Pitch preservation for nonPitched notes

NormalizedVocalNote.pitch keeps the original MIDI pitch for nonPitched notes (lyric flags #/^/*). Previously we set pitch to -1 for both percussion and nonPitched, losing the distinction. Consumers check the associated lyric's nonPitched flag for semantic meaning.

Pre-collect lyrics per phrase

The phrase-grouping algorithm now advances the lyric index to the phrase end regardless of whether the phrase has notes. Previously, pitch-slide-only phrases (no notes) would leave their lyrics stranded between phrases, causing divergence on round-trip.

Pitch-slide skip refinement

Pitch-slide notes are only skipped when their associated lyric survives the emptiness filter. Prevents losing slides whose lyrics would otherwise be dropped.

extractMidiVocalTextEvents

New helper extracts bracketed control-event text events on vocal tracks (stance markers, Band_PlayFacialAnim, etc.) into VocalTrackData.textEvents. Filters out lyrics (handled separately) and events scan-chart consumes internally (ENHANCED_OPENS, [mix N drumsM], [range_shift ...]).

Generic chart-parser helpers (used by both .chart and .mid paths)

These aren't strictly vocal-related but are bundled because the vocal work needed them and they're load-bearing elsewhere:

• resolveChartTrackName(sectionName) — matches YARG ChartReader logic for resolving a .chart section name like ExpertDoubleDrums into an {instrument, difficulty} pair. Handles non-standard names (e.g. "ExpertDoubleDrums" in Megadeth - Bite the Hand) which YARG accepts via prefix+suffix matching.
• parseChartSectionEventText(text) — matches YARG's TextEvents.NormalizeTextEvent → TryParseSectionEvent pipeline for section event detection. Handles typo cases like sections Pre-Chorus that YARG's StartsWith("section") accepts.

Why

The previous vocal data structure (PR #85 / vocal-normalization) correctly produced phrase-grouped output but left several issues unresolved:

1. Ambiguity: notes/lyrics existed in two places (top-level + per-phrase). Future code changes risked them drifting apart.
2. Round-trip incorrectness: lyric symbols were stripped, pitches were lost, range/lyric shifts and text events weren't exposed, so the writer couldn't reconstruct the original chart.
3. Versus mode unsupported: player attribution was lost when 105/106 phrases were merged on PART VOCALS, blocking versus-mode rendering.
4. HARM2/3 round-trip: needed the distinction between 105 (scoring, copied from HARM1) and 106 (static lyric, kept on the harmony track) for the writer to re-emit them on the correct MIDI note.

This refactor doesn't change YARG-comparable output — both before and after produce 0 vocal phrase diffs across 78,452 charts. The value is enabling round-trip writing, exposing data consumers need (player tags, shifts, text events), and removing the dual-storage ambiguity.

Validation

• 268 unit tests pass
• 0 hash regressions vs upstream master baseline (15,524 charts)
• 0 vocal phrase diffs vs YARG dumps across the full corpus (78,452 charts) — phrase boundaries, note ticks/pitches, lyric counts/text/flags all match YARG exactly