fix(importer): pair and apply MusicXML spans per part, staff and number

[Danielku15]

Note

AI-authored disclosure (alphatab-ai-authored-v1)

Portions of this content were authored by an AI agent. The agent has read
AGENTS.md and the human submitter accepts responsibility for
compliance with the rules in that document.

Issues

Fixes #2867

Proposed changes

#2867: a let ring written as <words>LetRing</words> + <dashes> was drawn but not heard. There were two causes:

• The flag went to the wrong place. The importer set only the derived Beat.isLetRing, but playback and the palm-mute rendering read Note.isLetRing/Note.isPalmMute. The beat flag is not serialized either, so the line was also missing in the web worker.
• The span state itself was unreliable. It was one global flag, applied in document order:
  • <dashes type="stop"/> without repeated words never ended the span;
  • spans leaked into other staves and parts;
  • number and <offset> were ignored.

Wedges, octave shifts, slash notation and endings had the same global, document-order handling. So the fix gives all MusicXML spans one shared foundation instead of special-casing let ring.

Design

• MusicXmlSpans pairs starts and stops per part:
  • by element and MusicXML number-level;
  • never across different staves (exporters reuse numbers per staff);
  • stops before starts within one direction;
  • stops that appear in the document before their start (other voice after <backup>) are parked until the start appears.
• MusicXmlSpanApplier applies the paired time ranges to beats, pedal markers and simile bars.
  • Beats next to the position the start or stop is written at count as written. MuseScore writes stops after the last covered note; Finale nudges them with a small <offset> into the neighbouring note.
  • Beats in other voices count if their middle lies within the span.
  • Grace notes at a boundary are ordered as in the document.
• MusicXmlNoteLinks pairs ties, slurs, slides, glissandos and trill/vibrato lines within a staff.
• Endings are tracked per part in the importer.

Behaviour changes

• Let ring / palm mute:
  • applied to the notes, so they are heard, drawn for palm mute, and kept after JSON serialization;
  • ringing ends when the same string is struck again;
  • also read from <bracket> and MuseScore's spellings ("let ring", "P.M.", "palm mute"), and from a label in a separate preceding direction (music21);
  • <tied type="let-ring"/> is supported, including TuxGuitar's placement outside <notations>.
• Lines with other labels ("cresc.", "dim.", "ritard.") keep their label as beat text instead of dropping it.
• Wedges: stay on their staff and on the voice they are written at. No spill onto other staves or parts, and no duplicated hairpins.
• Octave shifts:
  • stay on their staff (an 8va on the right hand no longer shifts the left hand);
  • an unsupported 22ma no longer ends a running 8va;
  • Finale/Sibelius stops follow their convention (detected via <software>, as in test suite 33da/33db).
• Pedals: a release in a later bar is no longer dropped, and change, resume and discontinue are supported. A change is drawn as "✱ Ped." side by side.
• Trills:
  • a trill line covers all notes of its voice;
  • trill-step half/unison is supported;
  • trills on tablature use the played fret.
• Measure styles: slash notation no longer leaks into other parts, and measure repeats cover the whole range up to their stop.
• Endings: combined across parts, so a later part without <ending> no longer erases them.
• Note links:
  • unended ties are tied to the next note with the same pitch;
  • glissandos and slides no longer share number slots;
  • a slur written along a hammer-on is not drawn twice.
• Offsets are converted from divisions for tempo, metronome and pedal positions. Tempo honours <offset sound="yes">.
• Hammer-ons / pull-offs: MusicXML notes are now registered by string once their <string> is read. Before, the string lookup of MusicXML beats was always empty, so hammer-ons and pull-offs were never imported. Only the start of a hammer-on/pull-off marks the origin.
• Model (Bar.finish): a pedal pressed again after a lift, in a bar after a held bar, was turned into a hold.

Reference renders

The changed renders were checked one by one:

Change	Files
Pedal changes now drawn	31a, 33a, 34b, Dichterliebe01
Line labels ("cresc.", "dim.", "ritard.") kept	31d, 34b, 34c, DebuMandSample, Dichterliebe01
Correct octave shifts	33da
Continuous trill lines	33a, 33f, 34a, 34c
Unended ties	33i
Spill onto other staves and duplicated hairpins removed	DebuMandSample, MahlFaGe4Sample
Offset units (tempo mark, pedal marks)	31b, BeetAnGeSample
Hammer-ons / pull-offs now imported	chord-diagram, BrookeWestSample

Not covered

The model has nothing to hold these:

• two-note tremolo
• the trill accidental-mark
• tuplet bracket bounds
• other-notation, principal-voice, string-mute
• links across staves

Pedals are not played back (MIDI does not read the pedal markers). This is unchanged.

Checklist

• I consent that this change becomes part of alphaTab under its current or any future open source license
• This PR is linked to an accepted issue (see above)
• Changes are implemented
• New tests were added
• I have read AGENTS.md if an AI helped draft any part of this PR

New tests:

• MusicXmlImporter.test.ts: hammer-pull and describe('spans'), covering lines, wedges, octave shifts, pedals, wavy lines, measure styles, endings, note links and tempo offsets
• Bar.test.ts: the pedal retake

TS, C# and Kotlin test suites pass.

AI authorship disclosure

• No AI agent authored any part of this PR (description, code, tests, or commit messages)
• An AI agent contributed to this PR. The AI-authored disclosure block
  (alphatab-ai-authored-v1) is present at the top of this body, and I have
  personally reviewed every change and can explain each one

Further details

• This is a breaking change
• This change will require update of the documentation/website