diff --git a/EXAMPLES.md b/EXAMPLES.md
new file mode 100644
index 000000000..0af215ed7
--- /dev/null
+++ b/EXAMPLES.md
@@ -0,0 +1,294 @@
+- accent-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/accent-element/ SKIP: already tested
+- accidental-mark-element-notation: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/accidental-mark-element-notation/
+- accidental-mark-element-ornament: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/accidental-mark-element-ornament/
+- accidental-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/accidental-element/ SKIP: already tested
+- accordion-high-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/accordion-high-element/ SKIP: esoteric
+- accordion-low-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/accordion-low-element/ SKIP: esoteric
+- accordion-middle-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/accordion-middle-element/ SKIP: esoteric
+- accordion-registration-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/accordion-registration-element/ SKIP: esoteric
+- alter-element-microtones: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/alter-element-microtones/ SKIP: esoteric
+- alter-element-semitones: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/alter-element-semitones/ SKIP: already tested
+- arpeggiate-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/arpeggiate-element/ SKIP: already tested
+- arrow-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/arrow-element/
+- arrowhead-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/arrowhead-element/
+- articulations-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/articulations-element/ SKIP: already tested
+- artificial-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/artificial-element/
+- assess-and-player-elements: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/assess-and-player-elements/ SKIP: esoteric
+- attributes-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/attributes-element/ SKIP: already tested
+- backup-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/backup-element/ SKIP: already tested
+- barline-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/barline-element/
+- barre-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/barre-element/ SKIP: already tested
+- bass-alter-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/bass-alter-element/ SKIP: already tested
+- bass-separator-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/bass-separator-element/
+- bass-step-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/bass-step-element/ SKIP: already tested
+- beam-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/beam-element/ SKIP: already tested
+- beat-repeat-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/beat-repeat-element/
+- beat-type-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/beat-type-element/ SKIP: already tested
+- beat-unit-dot-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/beat-unit-dot-element/ SKIP: already tested
+- beat-unit-tied-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/beat-unit-tied-element/
+- beat-unit-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/beat-unit-element/ SKIP: already tested
+- beater-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/beater-element/ SKIP: esoteric
+- beats-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/beats-element/ SKIP: already tested
+- bend-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/bend-element/ SKIP: already tested
+- bookmark-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/bookmark-element/ SKIP: esoteric
+- bracket-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/bracket-element/
+- brass-bend-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/brass-bend-element/
+- breath-mark-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/breath-mark-element/
+- caesura-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/caesura-element/
+- cancel-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/cancel-element/ SKIP: already tested
+- capo-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/capo-element/ SKIP: esoteric
+- chord-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/chord-element/ SKIP: already tested
+- chord-element-multiple-stop: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/chord-element-multiple-stop/ SKIP: already tested
+- circular-arrow-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/circular-arrow-element/
+- coda-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/coda-element/
+- concert-score-and-for-part-elements: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/concert-score-and-for-part-elements/ SKIP: esoteric
+- credit-image-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/credit-image-element/ SKIP: esoteric
+- credit-symbol-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/credit-symbol-element/ SKIP: esoteric
+- credit-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/credit-element/ SKIP: esoteric
+- cue-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/cue-element/
+- damp-all-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/damp-all-element/ SKIP: esoteric
+- damp-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/damp-element/ SKIP: esoteric
+- dashes-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/dashes-element/
+- defaults-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/defaults-element/ SKIP: esoteric
+- degree-alter-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/degree-alter-element/ SKIP: already tested
+- degree-type-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/degree-type-element/ SKIP: already tested
+- degree-value-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/degree-value-element/ SKIP: already tested
+- delayed-inverted-turn-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/delayed-inverted-turn-element/
+- delayed-turn-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/delayed-turn-element/
+- detached-legato-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/detached-legato-element/
+- divisions-and-duration-elements: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/divisions-and-duration-elements/ SKIP: already tested
+- doit-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/doit-element/
+- dot-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/dot-element/ SKIP: already tested
+- double-tongue-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/double-tongue-element/
+- double-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/double-element/ SKIP: esoteric
+- down-bow-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/down-bow-element/
+- effect-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/effect-element/ SKIP: esoteric
+- elision-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/elision-element/
+- end-line-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/end-line-element/ SKIP: esoteric
+- end-paragraph-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/end-paragraph-element/ SKIP: esoteric
+- ending-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/ending-element/
+- ensemble-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/ensemble-element/ SKIP: esoteric
+- except-voice-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/except-voice-element/ SKIP: esoteric
+- extend-element-figure: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/extend-element-figure/
+- extend-element-lyric: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/extend-element-lyric/
+- eyeglasses-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/eyeglasses-element/ SKIP: esoteric
+- f-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/f-element/
+- falloff-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/falloff-element/
+- fermata-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/fermata-element/ SKIP: already tested
+- ff-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/ff-element/
+- fff-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/fff-element/
+- ffff-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/ffff-element/
+- fffff-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/fffff-element/ SKIP: esoteric
+- ffffff-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/ffffff-element/ SKIP: esoteric
+- figure-number-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/figure-number-element/
+- fingering-element-frame: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/fingering-element-frame/ SKIP: already tested
+- fingering-element-notation: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/fingering-element-notation/
+- fingernails-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/fingernails-element/ SKIP: esoteric
+- flip-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/flip-element/
+- footnote-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/footnote-element/ SKIP: esoteric
+- forward-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/forward-element/ SKIP: already tested
+- fp-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/fp-element/
+- fret-element-frame: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/fret-element-frame/ SKIP: already tested
+- fz-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/fz-element/
+- glass-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/glass-element/ SKIP: esoteric
+- glissando-element-multiple: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/glissando-element-multiple/
+- glissando-element-single: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/glissando-element-single/
+- glyph-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/glyph-element/ SKIP: esoteric
+- golpe-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/golpe-element/ SKIP: esoteric
+- grace-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/grace-element/ SKIP: already tested
+- grace-element-appoggiatura: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/grace-element-appoggiatura/ SKIP: already tested
+- group-abbreviation-display-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/group-abbreviation-display-element/ SKIP: esoteric
+- group-abbreviation-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/group-abbreviation-element/ SKIP: esoteric
+- group-barline-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/group-barline-element/ SKIP: already tested
+- group-name-display-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/group-name-display-element/ SKIP: esoteric
+- group-time-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/group-time-element/ SKIP: already tested
+- grouping-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/grouping-element/ SKIP: esoteric
+- half-muted-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/half-muted-element/
+- handbell-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/handbell-element/ SKIP: esoteric
+- harmon-mute-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/harmon-mute-element/
+- harp-pedals-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/harp-pedals-element/ SKIP: esoteric
+- haydn-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/haydn-element/
+- heel-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/heel-element/ SKIP: esoteric
+- heel-toe-substitution: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/heel-toe-substitution/ SKIP: esoteric
+- hole-type-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/hole-type-element/ SKIP: esoteric
+- hole-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/hole-element/ SKIP: esoteric
+- humming-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/humming-element/ SKIP: esoteric
+- identification-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/identification-element/ SKIP: esoteric
+- image-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/image-element/ SKIP: esoteric
+- instrument-change-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/instrument-change-element/ SKIP: esoteric
+- instrument-link-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/instrument-link-element/ SKIP: esoteric
+- interchangeable-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/interchangeable-element/
+- inversion-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/inversion-element/ SKIP: already tested
+- inverted-mordent-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/inverted-mordent-element/
+- inverted-turn-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/inverted-turn-element/
+- inverted-vertical-turn-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/inverted-vertical-turn-element/
+- ipa-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/ipa-element/ SKIP: esoteric
+- key-octave-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/key-octave-element/ SKIP: esoteric
+- key-element-non-traditional: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/key-element-non-traditional/ SKIP: esoteric
+- key-element-traditional: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/key-element-traditional/ SKIP: already tested
+- kind-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/kind-element/ SKIP: already tested
+- laughing-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/laughing-element/ SKIP: esoteric
+- level-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/level-element/ SKIP: esoteric
+- line-detail-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/line-detail-element/ SKIP: esoteric
+- line-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/line-element/
+- link-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/link-element/ SKIP: esoteric
+- lyric-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/lyric-element/
+- measure-distance-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/measure-distance-element/ SKIP: esoteric
+- measure-numbering-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/measure-numbering-element/ SKIP: already tested
+- measure-repeat-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/measure-repeat-element/
+- membrane-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/membrane-element/ SKIP: esoteric
+- metal-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/metal-element/ SKIP: esoteric
+- metronome-arrows-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/metronome-arrows-element/ SKIP: esoteric
+- metronome-note-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/metronome-note-element/
+- metronome-tied-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/metronome-tied-element/ SKIP: esoteric
+- metronome-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/metronome-element/ SKIP: already tested
+- mf-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/mf-element/
+- midi-device-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/midi-device-element/ SKIP: esoteric
+- midi-instrument-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/midi-instrument-element/ SKIP: esoteric
+- midi-name-and-midi-bank-elements: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/midi-name-and-midi-bank-elements/ SKIP: esoteric
+- midi-unpitched-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/midi-unpitched-element/ SKIP: esoteric
+- mordent-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/mordent-element/
+- movement-number-and-movement-title-elements: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/movement-number-and-movement-title-elements/ SKIP: esoteric
+- mp-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/mp-element/
+- multiple-rest-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/multiple-rest-element/
+- n-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/n-element/ SKIP: esoteric
+- natural-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/natural-element/ SKIP: already tested
+- non-arpeggiate-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/non-arpeggiate-element/
+- normal-dot-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/normal-dot-element/ SKIP: esoteric
+- notehead-text-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/notehead-text-element/
+- numeral-alter-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/numeral-alter-element/ SKIP: already tested
+- numeral-key-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/numeral-key-element/ SKIP: esoteric
+- numeral-root-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/numeral-root-element/ SKIP: already tested
+- octave-change-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/octave-change-element/ SKIP: esoteric
+- octave-shift-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/octave-shift-element/
+- octave-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/octave-element/ SKIP: already tested
+- open-string-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/open-string-element/ SKIP: already tested
+- open-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/open-element/
+- p-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/p-element/
+- pan-and-elevation-elements: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/pan-and-elevation-elements/ SKIP: esoteric
+- part-abbreviation-display-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/part-abbreviation-display-element/ SKIP: esoteric
+- part-link-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/part-link-element/ SKIP: esoteric
+- part-name-display-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/part-name-display-element/ SKIP: esoteric
+- part-symbol-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/part-symbol-element/ SKIP: already tested
+- pedal-element-lines: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/pedal-element-lines/ SKIP: already tested
+- pedal-element-symbols: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/pedal-element-symbols/ SKIP: already tested
+- per-minute-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/per-minute-element/ SKIP: already tested
+- pf-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/pf-element/
+- pitch-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/pitch-element/ SKIP: already tested
+- pitched-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/pitched-element/ SKIP: esoteric
+- plop-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/plop-element/ SKIP: esoteric
+- pluck-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/pluck-element/ SKIP: esoteric
+- pp-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/pp-element/
+- ppp-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/ppp-element/
+- pppp-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/pppp-element/
+- ppppp-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/ppppp-element/ SKIP: esoteric
+- pppppp-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/pppppp-element/ SKIP: esoteric
+- pre-bend-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/pre-bend-element/ SKIP: already tested
+- prefix-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/prefix-element/
+- principal-voice-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/principal-voice-element/ SKIP: esoteric
+- rehearsal-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/rehearsal-element/
+- release-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/release-element/ SKIP: already tested
+- repeat-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/repeat-element/
+- rest-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/rest-element/ SKIP: already tested
+- rf-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/rf-element/
+- rfz-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/rfz-element/
+- root-alter-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/root-alter-element/ SKIP: already tested
+- root-step-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/root-step-element/ SKIP: already tested
+- schleifer-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/schleifer-element/
+- scoop-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/scoop-element/ SKIP: esoteric
+- scordatura-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/scordatura-element/ SKIP: esoteric
+- score-timewise-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/score-timewise-element/ SKIP: esoteric
+- segno-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/segno-element/
+- semi-pitched-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/semi-pitched-element/ SKIP: esoteric
+- senza-misura-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/senza-misura-element/
+- sf-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/sf-element/
+- sffz-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/sffz-element/
+- sfp-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/sfp-element/
+- sfpp-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/sfpp-element/
+- sfz-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/sfz-element/
+- sfzp-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/sfzp-element/
+- shake-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/shake-element/
+- slash-type-and-slash-dot-elements: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/slash-type-and-slash-dot-elements/ SKIP: esoteric
+- slash-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/slash-element/ SKIP: esoteric
+- slide-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/slide-element/
+- slur-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/slur-element/ SKIP: already tested
+- smear-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/smear-element/ SKIP: esoteric
+- snap-pizzicato-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/snap-pizzicato-element/
+- soft-accent-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/soft-accent-element/
+- spiccato-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/spiccato-element/
+- staccatissimo-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/staccatissimo-element/ SKIP: already tested
+- staccato-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/staccato-element/ SKIP: already tested
+- staff-distance-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/staff-distance-element/ SKIP: esoteric
+- staff-divide-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/staff-divide-element/ SKIP: esoteric
+- staff-lines-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/staff-lines-element/ SKIP: already tested
+- staff-size-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/staff-size-element/ SKIP: esoteric
+- staff-tuning-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/staff-tuning-element/ SKIP: already tested
+- staff-type-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/staff-type-element/ SKIP: already tested
+- staff-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/staff-element/ SKIP: already tested
+- staves-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/staves-element/ SKIP: already tested
+- step-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/step-element/ SKIP: already tested
+- stick-location-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/stick-location-element/ SKIP: esoteric
+- stick-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/stick-element/ SKIP: esoteric
+- stopped-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/stopped-element/
+- straight-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/straight-element/ SKIP: esoteric
+- stress-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/stress-element/
+- string-mute-element-off: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/string-mute-element-off/
+- string-mute-element-on: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/string-mute-element-on/
+- strong-accent-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/strong-accent-element/ SKIP: already tested
+- suffix-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/suffix-element/ SKIP: esoteric
+- supports-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/supports-element/ SKIP: esoteric
+- swing-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/swing-element/ SKIP: esoteric
+- syllabic-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/syllabic-element/
+- symbol-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/symbol-element/ SKIP: esoteric
+- sync-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/sync-element/ SKIP: esoteric
+- system-distance-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/system-distance-element/ SKIP: esoteric
+- system-dividers-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/system-dividers-element/ SKIP: esoteric
+- tap-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tap-element/ SKIP: already tested
+- technical-element-tablature: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/technical-element-tablature/ SKIP: already tested
+- tenuto-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tenuto-element/ SKIP: already tested
+- thumb-position-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/thumb-position-element/
+- tied-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tied-element/ SKIP: already tested
+- time-modification-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/time-modification-element/
+- timpani-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/timpani-element/ SKIP: esoteric
+- toe-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/toe-element/ SKIP: esoteric
+- transpose-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/transpose-element/ SKIP: esoteric
+- tremolo-element-double: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tremolo-element-double/
+- tremolo-element-single: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tremolo-element-single/
+- trill-mark-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/trill-mark-element/
+- triple-tongue-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/triple-tongue-element/ SKIP: esoteric
+- tuplet-dot-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tuplet-dot-element/ SKIP: esoteric
+- tuplet-element-nested: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tuplet-element-nested/ SKIP: already tested
+- tuplet-element-regular: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tuplet-element-regular/ SKIP: already tested
+- turn-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/turn-element/
+- unpitched-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/unpitched-element/ SKIP: esoteric
+- unstress-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/unstress-element/ SKIP: esoteric
+- up-bow-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/up-bow-element/
+- vertical-turn-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/vertical-turn-element/
+- virtual-instrument-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/virtual-instrument-element/ SKIP: esoteric
+- voice-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/voice-element/ SKIP: already tested
+- wait-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/wait-element/ SKIP: esoteric
+- wavy-line-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/wavy-line-element/ SKIP: esoteric
+- wedge-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/wedge-element/
+- with-bar-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/with-bar-element/ SKIP: already tested
+- wood-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/wood-element/ SKIP: esoteric
+- work-element: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/work-element/ SKIP: esoteric
+- alto-clef: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/alto-clef/
+- baritone-c-clef: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/baritone-c-clef/
+- baritone-f-clef: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/baritone-f-clef/
+- bass-clef: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/bass-clef/ SKIP: already tested
+- bass-clef-down-octave: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/bass-clef-down-octave/ SKIP: already tested
+- mezzo-soprano-clef: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/mezzo-soprano-clef/
+- percussion-clef: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/percussion-clef/
+- soprano-clef: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/soprano-clef/
+- system-attribute-also-top: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/system-attribute-also-top/ SKIP: esoteric
+- system-attribute-only-top: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/system-attribute-only-top/ SKIP: esoteric
+- tab-clef: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tab-clef/ SKIP: already tested
+- tenor-clef: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tenor-clef/
+- treble-clef: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/treble-clef/ SKIP: already tested
+- tutorial-apres-un-reve: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tutorial-apres-un-reve/
+- tutorial-chopin-prelude: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tutorial-chopin-prelude/
+- tutorial-chord-symbols: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tutorial-chord-symbols/ SKIP: already tested
+- tutorial-hello-world: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tutorial-hello-world/ SKIP: already tested
+- tutorial-percussion: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tutorial-percussion/
+- tutorial-tablature: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/tutorial-tablature/ SKIP: already tested
+- vocal-tenor-clef: https://w3c-cg.github.io/musicxml/musicxml-reference/examples/vocal-tenor-clef/
diff --git a/cli/render.ts b/cli/render.ts
index 8ee0f5efb..6c0f2af9d 100644
--- a/cli/render.ts
+++ b/cli/render.ts
@@ -29,11 +29,11 @@ export async function render(opts: {
 		await page.goto('http://localhost:3101/');
 		await page.evaluate(
 			async ({ musicXML, config }) => {
-				const canvas = document.getElementById('vexml');
-				if (!(canvas instanceof HTMLCanvasElement)) {
-					throw new Error('canvas not found');
+				const container = document.getElementById('screenshot');
+				if (!(container instanceof HTMLDivElement)) {
+					throw new Error('container not found');
 				}
-				await window.render(musicXML, canvas, config);
+				await window.render(musicXML, container, config);
 			},
 			{ musicXML, config },
 		);
diff --git a/site/src/App.tsx b/site/src/App.tsx
index 1967f97fd..293b2fe60 100644
--- a/site/src/App.tsx
+++ b/site/src/App.tsx
@@ -1,6 +1,33 @@
 import { useEffect, useRef, useState } from 'react';
-import type { Config } from '../../src';
-import { render } from '../../src';
+import type {
+	Config,
+	Note,
+	PointerTarget,
+	PointerTargetEvent,
+} from '../../src';
+import { render, type Score } from '../../src';
+
+// One-line summary of the hovered target for the tooltip.
+function describe(target: PointerTarget): string {
+	if (target.type === 'note') {
+		const beats = target.getBeats();
+		const parts = [
+			target.getPitch() ?? 'rest',
+			`${beats} beat${beats === 1 ? '' : 's'}`,
+		];
+		if (target.isGrace()) {
+			parts.push('grace');
+		}
+		if (target.isChordMember()) {
+			parts.push('chord');
+		}
+		return parts.join(' · ');
+	}
+	if (target.type === 'tab-position') {
+		return `string ${target.getString()} · fret ${target.getFret()} · ${target.getNote().getPitch() ?? 'rest'}`;
+	}
+	return '';
+}
 
 // Vite reads the test fixtures straight from ../tests at build time (fs.allow: ['..'] in
 // vite.config permits it) and hands us the file list — no symlink or hand-written manifest.
@@ -68,7 +95,8 @@ function Or() {
 }
 
 export default function App() {
-	const canvasRef = useRef<HTMLCanvasElement>(null);
+	const containerRef = useRef<HTMLDivElement>(null);
+	const scoreRef = useRef<Score | null>(null);
 	const [text, setText] = useState('');
 	const [input, setInput] = useState<string | Blob | null>(null);
 	const [fixture, setFixture] = useState('');
@@ -83,6 +111,17 @@ export default function App() {
 	);
 	const [cleared, setCleared] = useState(false);
 	const [restored, setRestored] = useState(false);
+	const [showInfo, setShowInfo] = useState(true);
+	const [tooltip, setTooltip] = useState<{
+		x: number;
+		y: number;
+		text: string;
+	} | null>(null);
+	// Read live inside the pointer handler so toggling the checkbox doesn't re-subscribe.
+	const showInfoRef = useRef(showInfo);
+	showInfoRef.current = showInfo;
+	// The note whose halo is currently lit, so the next move can turn it back off.
+	const haloRef = useRef<Note | null>(null);
 	const debounceRef = useRef<ReturnType<typeof setTimeout> | undefined>(
 		undefined,
 	);
@@ -139,10 +178,14 @@ export default function App() {
 	}, [config, renderMs]);
 
 	useEffect(() => {
-		const canvas = canvasRef.current;
-		if (!canvas || input == null) {
+		const container = containerRef.current;
+		if (!container || input == null) {
 			return;
 		}
+		// Replace the previous render before starting a new one: render() appends a fresh
+		// managed canvas, so the old Score must be disposed or canvases would stack.
+		scoreRef.current?.dispose();
+		scoreRef.current = null;
 		setError(null);
 		const start = performance.now();
 		// Engrave once at the configured reference width; CSS then scales the canvas to fit
@@ -152,19 +195,75 @@ export default function App() {
 			renderConfig.layout?.type === 'standard'
 				? renderConfig.layout.width
 				: undefined;
-		render(input, canvas, {
+		let cancelled = false;
+		// Turn off the lit halo and hide the tooltip; called on move-to-empty and on leave.
+		const clearHalo = () => {
+			haloRef.current?.halo.off();
+			haloRef.current?.color.off();
+			haloRef.current = null;
+			container.style.cursor = '';
+			setTooltip(null);
+		};
+		let detach: (() => void) | undefined;
+		render(input, container, {
 			...renderConfig,
 			layout: { type: 'standard', width: layoutWidth },
 		})
-			.then(() => {
-				canvas.style.width = '100%';
-				canvas.style.height = 'auto';
+			.then((score) => {
+				// The effect can re-run before this resolves; drop the late score so it
+				// doesn't leak a canvas into a container a newer render already owns.
+				if (cancelled) {
+					score.dispose();
+					return;
+				}
+				scoreRef.current = score;
 				setRenderMs(performance.now() - start);
+
+				const onPointer = (e: PointerTargetEvent) => {
+					const note =
+						e.target?.type === 'note'
+							? e.target
+							: e.target?.type === 'tab-position'
+								? e.target.getNote()
+								: null;
+					if (note !== haloRef.current) {
+						haloRef.current?.halo.off();
+						haloRef.current?.color.off();
+						note?.halo.on();
+						note?.color.on('#2962ff');
+						haloRef.current = note;
+						container.style.cursor = note ? 'pointer' : '';
+					}
+					if (note && e.target && showInfoRef.current) {
+						const r = e.target.getBoundingClientRect();
+						setTooltip({
+							x: r.left + r.width / 2,
+							y: r.top,
+							text: describe(e.target),
+						});
+					} else {
+						setTooltip(null);
+					}
+				};
+				score.addEventListener('pointermove', onPointer);
+				score.addEventListener('pointerdown', onPointer);
+				container.addEventListener('pointerleave', clearHalo);
+				detach = () => {
+					container.removeEventListener('pointerleave', clearHalo);
+					clearHalo();
+				};
 			})
 			.catch((e: unknown) => {
 				setRenderMs(null);
 				setError(e instanceof Error ? e.message : String(e));
 			});
+		return () => {
+			cancelled = true;
+			// score.dispose() drops its own listeners; this only unbinds the DOM-level leave handler.
+			detach?.();
+			scoreRef.current?.dispose();
+			scoreRef.current = null;
+		};
 	}, [input, renderConfig]);
 
 	// Restore the last-edited MusicXML, or open with a random example.
@@ -426,6 +525,23 @@ export default function App() {
 								/>
 								Dark mode
 							</label>
+							<label
+								htmlFor="showInfo"
+								className="flex items-center gap-2 text-xs font-medium text-zinc-500"
+							>
+								<input
+									id="showInfo"
+									type="checkbox"
+									checked={showInfo}
+									onChange={(e) => {
+										setShowInfo(e.target.checked);
+										if (!e.target.checked) {
+											setTooltip(null);
+										}
+									}}
+								/>
+								Show note info on hover
+							</label>
 							<div className="flex flex-col gap-1.5">
 								<label
 									htmlFor="notationFont"
@@ -694,16 +810,17 @@ export default function App() {
 							)
 						)}
 						{input != null && (
-							// The canvas is engraved at that width and CSS-scaled to fit, shrinking on narrow viewports, never past 100%.
+							// vexml appends its managed canvas here; React manages only this div's
+							// attributes, never its children. The canvas is engraved at the reference
+							// width and CSS-scaled to fit (down when narrow, never past 100%); the
+							// `.vexml-canvas` child-selector targets only the score canvas (not vexml's
+							// overlay layers) so the dark-mode invert and scaling react without
+							// re-rendering. ponytail: invert the black glyphs to light rather than
+							// re-engraving in a light color.
 							<div
-								className={`relative mx-auto w-full max-w-237.5 py-8 px-4 shadow-md ring-1 sm:py-16 ${dark ? 'bg-zinc-900 ring-zinc-700' : 'bg-white ring-zinc-200'}`}
-							>
-								{/* ponytail: invert the black glyphs to light for dark mode instead of re-engraving in a light color. */}
-								<canvas
-									ref={canvasRef}
-									className={`block ${dark ? 'invert' : ''}`}
-								/>
-							</div>
+								ref={containerRef}
+								className={`relative mx-auto w-full max-w-237.5 py-8 px-4 shadow-md ring-1 sm:py-16 [&_.vexml-canvas]:block [&_.vexml-canvas]:!h-auto [&_.vexml-canvas]:!w-full ${dark ? 'bg-zinc-900 ring-zinc-700 [&_.vexml-canvas]:invert' : 'bg-white ring-zinc-200'}`}
+							/>
 						)}
 						{debouncing && (
 							<div className="pointer-events-none absolute inset-0 bg-black/40">
@@ -721,6 +838,15 @@ export default function App() {
 					</div>
 				</section>
 			</main>
+
+			{tooltip && (
+				<div
+					className="pointer-events-none fixed z-30 -translate-x-1/2 -translate-y-full rounded bg-zinc-900/90 px-2 py-1 font-mono text-xs text-white shadow-lg"
+					style={{ left: tooltip.x, top: tooltip.y - 8 }}
+				>
+					{tooltip.text}
+				</div>
+			)}
 		</div>
 	);
 }
diff --git a/src/decorations.test.ts b/src/decorations.test.ts
new file mode 100644
index 000000000..7b3c7d344
--- /dev/null
+++ b/src/decorations.test.ts
@@ -0,0 +1,162 @@
+import { expect, test } from 'bun:test';
+import { Decorations } from './decorations';
+import { Rect } from './geometry';
+import type { Layer, LayerHost, LayerKind } from './stage';
+import type { Decoratable, NoteGlyph } from './targets';
+
+// A recording 2D context: logs the operations Decorations performs so a test can assert what was
+// painted (and in what order) without a real canvas. Cast to CanvasRenderingContext2D — only the
+// members Decorations touches are implemented.
+
+class RecordingContext {
+	fillStyle: string | CanvasGradient | CanvasPattern = '#000000';
+	font = '';
+	textAlign = 'left';
+	textBaseline = 'alphabetic';
+	readonly canvas = { width: 800, height: 600 } as HTMLCanvasElement;
+	// In call order: 'clear', 'fill:<shape>:<style>', or 'text:<text>:<style>:<font>'.
+	readonly ops: string[] = [];
+	private shape = '';
+	save(): void {}
+	restore(): void {}
+	setTransform(): void {}
+	clearRect(): void {
+		this.ops.push('clear');
+	}
+	beginPath(): void {}
+	ellipse(): void {
+		this.shape = 'ellipse';
+	}
+	arc(): void {
+		this.shape = 'arc';
+	}
+	fill(): void {
+		this.ops.push(`fill:${this.shape}:${String(this.fillStyle)}`);
+	}
+	fillText(text: string): void {
+		this.ops.push(`text:${text}:${String(this.fillStyle)}:${this.font}`);
+	}
+}
+
+class FakeLayer implements Layer {
+	disposed = false;
+	constructor(readonly ctx: CanvasRenderingContext2D) {}
+	dispose(): void {
+		this.disposed = true;
+	}
+}
+
+class FakeLayerHost implements LayerHost {
+	readonly recorder = new RecordingContext();
+	createLayerCalls = 0;
+	layer: FakeLayer | null = null;
+	createLayer(_kind: LayerKind): Layer {
+		this.createLayerCalls++;
+		this.layer = new FakeLayer(
+			this.recorder as unknown as CanvasRenderingContext2D,
+		);
+		return this.layer;
+	}
+}
+
+const HALO = 'fill:arc:rgba(41, 98, 255, 0.35)';
+const GLYPH: NoteGlyph = { text: 'q', font: '30px Bravura', x: 12, y: 20 };
+
+const decoratable = (
+	rect: Rect,
+	glyph: NoteGlyph | null = null,
+): Decoratable => ({
+	rect,
+	glyph,
+	getBoundingClientRect: () => ({}) as DOMRect,
+});
+
+// The marks (fills/texts) recorded since the last clear — i.e., the result of the latest repaint.
+function marksSinceLastClear(ops: string[]): string[] {
+	return ops.slice(ops.lastIndexOf('clear') + 1).filter((o) => o !== 'clear');
+}
+
+test('the overlay layer is created lazily, on the first decoration', () => {
+	const host = new FakeLayerHost();
+	const decorations = new Decorations(host);
+	expect(host.createLayerCalls).toBe(0);
+	decorations.setColor(decoratable(new Rect(0, 0, 12, 10), GLYPH), '#2962ff');
+	expect(host.createLayerCalls).toBe(1);
+});
+
+test('setColor stamps the notehead glyph in the color and reports isColored', () => {
+	const host = new FakeLayerHost();
+	const decorations = new Decorations(host);
+	const target = decoratable(new Rect(10, 10, 12, 10), GLYPH);
+	decorations.setColor(target, '#2962ff');
+	expect(decorations.isColored(target)).toBe(true);
+	// The exact glyph (text + font) vexflow drew, replayed in the chosen color.
+	expect(marksSinceLastClear(host.recorder.ops)).toEqual([
+		'text:q:#2962ff:30px Bravura',
+	]);
+});
+
+test('a glyph-less target (a rest) falls back to a filled ellipse', () => {
+	const host = new FakeLayerHost();
+	const decorations = new Decorations(host);
+	decorations.setColor(decoratable(new Rect(0, 0, 12, 10), null), '#2962ff');
+	expect(marksSinceLastClear(host.recorder.ops)).toEqual([
+		'fill:ellipse:#2962ff',
+	]);
+});
+
+test('setColor(null) clears the decoration, drawing nothing', () => {
+	const host = new FakeLayerHost();
+	const decorations = new Decorations(host);
+	const target = decoratable(new Rect(0, 0, 12, 10), GLYPH);
+	decorations.setColor(target, '#ff0000');
+	decorations.setColor(target, null);
+	expect(decorations.isColored(target)).toBe(false);
+	expect(host.recorder.ops.at(-1)).toBe('clear');
+	expect(marksSinceLastClear(host.recorder.ops)).toEqual([]);
+});
+
+test('halo draws under color', () => {
+	const host = new FakeLayerHost();
+	const decorations = new Decorations(host);
+	const target = decoratable(new Rect(0, 0, 12, 10), GLYPH);
+	decorations.setColor(target, '#2962ff');
+	decorations.setHalo(target, true);
+	expect(marksSinceLastClear(host.recorder.ops)).toEqual([
+		HALO,
+		'text:q:#2962ff:30px Bravura',
+	]);
+});
+
+test('setHalo(false) removes the halo', () => {
+	const host = new FakeLayerHost();
+	const decorations = new Decorations(host);
+	const target = decoratable(new Rect(0, 0, 12, 10), GLYPH);
+	decorations.setHalo(target, true);
+	expect(decorations.isHaloed(target)).toBe(true);
+	decorations.setHalo(target, false);
+	expect(decorations.isHaloed(target)).toBe(false);
+	expect(marksSinceLastClear(host.recorder.ops)).toEqual([]);
+});
+
+test('every repaint clears first, then redraws the whole active set', () => {
+	const host = new FakeLayerHost();
+	const decorations = new Decorations(host);
+	decorations.setColor(decoratable(new Rect(0, 0, 12, 10), GLYPH), '#111111');
+	decorations.setColor(decoratable(new Rect(20, 0, 12, 10), GLYPH), '#222222');
+	expect(marksSinceLastClear(host.recorder.ops)).toEqual([
+		'text:q:#111111:30px Bravura',
+		'text:q:#222222:30px Bravura',
+	]);
+});
+
+test('dispose disposes the layer and clears state', () => {
+	const host = new FakeLayerHost();
+	const decorations = new Decorations(host);
+	const target = decoratable(new Rect(0, 0, 12, 10), GLYPH);
+	decorations.setColor(target, '#2962ff');
+	const layer = host.layer;
+	decorations.dispose();
+	expect(layer?.disposed).toBe(true);
+	expect(decorations.isColored(target)).toBe(false);
+});
diff --git a/src/decorations.ts b/src/decorations.ts
new file mode 100644
index 000000000..aa1420f1c
--- /dev/null
+++ b/src/decorations.ts
@@ -0,0 +1,140 @@
+import type { Rect } from './geometry';
+import type { Layer, LayerHost } from './stage';
+import type { Decoratable, Decorator } from './targets';
+
+// A soft round highlight drawn behind a note to denote activity. Fixed (the halo toggle takes no
+// argument); the color toggle is what carries a caller-chosen color. HALO_MARGIN is how far the
+// circle extends past the notehead's half-extent, so the note sits evenly inside it.
+const HALO_COLOR = 'rgba(41, 98, 255, 0.35)';
+const HALO_MARGIN = 8;
+
+/*
+ * The decoration store and painter — the production `Decorator`. A target's color/halo toggles
+ * delegate here. Decorations are retained as an active set (which targets are colored/haloed) and
+ * drawn on a single `content` overlay layer that sits in score space over the engraving.
+ *
+ * Every change repaints the whole layer from the active set rather than erasing one rect. That's
+ * the answer to "how does off() work without disturbing neighbors": clearing one decoration's box
+ * could wipe part of an overlapping one, so instead the lot is cleared and redrawn — halos first
+ * (under), colors on top. The layer is created lazily on the first decoration, so an undecorated
+ * score never allocates an overlay.
+ */
+export class Decorations implements Decorator {
+	private readonly colors = new Map<Decoratable, string>();
+	private readonly halos = new Set<Decoratable>();
+	private layer: Layer | null = null;
+
+	constructor(private readonly host: LayerHost) {}
+
+	setColor(target: Decoratable, color: string | null): void {
+		if (color === null) {
+			this.colors.delete(target);
+		} else {
+			this.colors.set(target, color);
+		}
+		this.repaint();
+	}
+
+	setHalo(target: Decoratable, on: boolean): void {
+		if (on) {
+			this.halos.add(target);
+		} else {
+			this.halos.delete(target);
+		}
+		this.repaint();
+	}
+
+	isColored(target: Decoratable): boolean {
+		return this.colors.has(target);
+	}
+
+	isHaloed(target: Decoratable): boolean {
+		return this.halos.has(target);
+	}
+
+	dispose(): void {
+		this.layer?.dispose();
+		this.layer = null;
+		this.colors.clear();
+		this.halos.clear();
+	}
+
+	// Repaint from the retained active set: clear, then halos (under) then colors (over).
+	private repaint(): void {
+		if (this.colors.size === 0 && this.halos.size === 0) {
+			// Nothing active: clear an existing layer, but don't allocate one just to clear it.
+			if (this.layer) {
+				this.clear(this.layer.ctx);
+			}
+			return;
+		}
+		const ctx = this.ensureLayer().ctx;
+		this.clear(ctx);
+		for (const target of this.halos) {
+			this.drawHalo(ctx, target.rect);
+		}
+		for (const [target, color] of this.colors) {
+			this.drawColor(ctx, target, color);
+		}
+	}
+
+	private ensureLayer(): Layer {
+		if (!this.layer) {
+			this.layer = this.host.createLayer('content');
+		}
+		return this.layer;
+	}
+
+	// Clear the whole bitmap regardless of the dpr transform the layer applied.
+	private clear(ctx: CanvasRenderingContext2D): void {
+		ctx.save();
+		ctx.setTransform(1, 0, 0, 1, 0, 0);
+		ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+		ctx.restore();
+	}
+
+	// Recolor the note: replay vexflow's own notehead render (same glyph text, font, and baseline)
+	// in the chosen color, so the actual notehead is recolored and hollow heads stay hollow. A
+	// glyph-less target (a rest, or a non-note) falls back to a filled ellipse over its box.
+	private drawColor(
+		ctx: CanvasRenderingContext2D,
+		target: Decoratable,
+		color: string,
+	): void {
+		ctx.save();
+		ctx.fillStyle = color;
+		const glyph = target.glyph;
+		if (glyph) {
+			ctx.font = glyph.font;
+			ctx.textAlign = 'left';
+			ctx.textBaseline = 'alphabetic';
+			ctx.fillText(glyph.text, glyph.x, glyph.y);
+		} else {
+			const r = target.rect;
+			ctx.beginPath();
+			ctx.ellipse(
+				r.x + r.w / 2,
+				r.y + r.h / 2,
+				r.w / 2,
+				r.h / 2,
+				0,
+				0,
+				2 * Math.PI,
+			);
+			ctx.fill();
+		}
+		ctx.restore();
+	}
+
+	private drawHalo(ctx: CanvasRenderingContext2D, rect: Rect): void {
+		// A circle centered on the notehead box, a fixed margin larger than its half-extent, so it
+		// encircles the note evenly regardless of the notehead's width.
+		const radius = Math.max(rect.w, rect.h) / 2 + HALO_MARGIN;
+		ctx.save();
+		ctx.fillStyle = HALO_COLOR;
+		ctx.beginPath();
+		ctx.arc(rect.x + rect.w / 2, rect.y + rect.h / 2, radius, 0, 2 * Math.PI);
+		ctx.fill();
+		ctx.restore();
+	}
+}
diff --git a/src/draw.ts b/src/draw.ts
index 5a1474b31..dcde1c913 100644
--- a/src/draw.ts
+++ b/src/draw.ts
@@ -49,6 +49,7 @@ import {
 	WORDS_Y_OFFSET,
 } from './constants';
 import { Rect } from './geometry';
+import type { RawGeometry, RawMeasure, RawNote } from './hit';
 import type { MeasureNumbering, ScoreLayout } from './layout';
 import {
 	endBeatOf,
@@ -177,6 +178,10 @@ type PendingStave = {
 	// StaveNotes whose lead carries a tie — they get a tie-apex collision obstacle once their
 	// stem direction is final (stem-down ties bow up over the noteheads). See tieApexRect.
 	tiedNotes: Set<StaveNote>;
+	// Each real (non-grace) note paired with its mdom chord, so the hit index can map every
+	// notehead/fret back to its note after formatting. One of these is populated per stave kind.
+	noteChords: Array<{ note: StaveNote; chord: Chord }>;
+	tabChords: Array<{ note: TabNote; chord: Chord }>;
 };
 
 /*
@@ -199,9 +204,17 @@ function buildNotes(
 	const endBeat = Math.max(endBeatOf(voices), meterFloor);
 	const staveNotes: StaveNote[] = [];
 	const tiedNotes = new Set<StaveNote>();
+	const noteChords: Array<{ note: StaveNote; chord: Chord }> = [];
 	const vexVoices = voices.map((voice) => {
+		const chords = voice.chords;
+		// lead note -> its chord, so the record callback (which only gets the lead) can pair
+		// each StaveNote with the chord whose noteheads it draws (for the hit index).
+		const chordByLead = new Map<Note, Chord>();
+		for (const chord of chords) {
+			chordByLead.set(chord.lead, chord);
+		}
 		const tickables = vexflowVoiceTickables(
-			voice.chords,
+			chords,
 			clef,
 			endBeat,
 			(lead, note) => {
@@ -210,6 +223,10 @@ function buildNotes(
 				if (lead.ties.length > 0) {
 					tiedNotes.add(note);
 				}
+				const chord = chordByLead.get(lead);
+				if (chord && !lead.isGrace) {
+					noteChords.push({ note, chord });
+				}
 			},
 		);
 		return softVoice(tickables, softmaxFactor);
@@ -231,6 +248,8 @@ function buildNotes(
 		tuplets,
 		staveNotes,
 		tiedNotes,
+		noteChords,
+		tabChords: [],
 	};
 }
 
@@ -595,14 +614,24 @@ function buildTabNotes(
 	softmaxFactor: number,
 	byTabLead: Map<Note, TabNote>,
 ): PendingStave {
-	const vexVoices = voices.map((voice) =>
-		softVoice(
-			vexflowTabTickables(voice.chords, (lead, tabNote) =>
-				byTabLead.set(lead, tabNote),
-			),
+	const tabChords: Array<{ note: TabNote; chord: Chord }> = [];
+	const vexVoices = voices.map((voice) => {
+		const chords = voice.chords;
+		const chordByLead = new Map<Note, Chord>();
+		for (const chord of chords) {
+			chordByLead.set(chord.lead, chord);
+		}
+		return softVoice(
+			vexflowTabTickables(chords, (lead, tabNote) => {
+				byTabLead.set(lead, tabNote);
+				const chord = chordByLead.get(lead);
+				if (chord && !lead.isGrace) {
+					tabChords.push({ note: tabNote, chord });
+				}
+			}),
 			softmaxFactor,
-		),
-	);
+		);
+	});
 	// Build (but discard) the tab tuplets: their construction rescales the notes'
 	// ticks (Tuplet.attach), which the part's shared formatter needs so a triplet's
 	// tab frets stay aligned under their notation notes. The bracket/number is drawn
@@ -618,6 +647,8 @@ function buildTabNotes(
 		tuplets: [],
 		staveNotes: [],
 		tiedNotes: new Set(),
+		noteChords: [],
+		tabChords,
 	};
 }
 
@@ -775,17 +806,25 @@ function showsMeasureNumber(
 	}
 }
 
+// Half-heights (CSS px) for the hit-index boxes. A notehead's x-span is measured exactly (from
+// getNoteHeadBeginX/EndX) so decorations land on the glyph; its height and the fret box are
+// approximated to ~one notehead — enough to pick a target and to draw a centered color/halo.
+const NOTEHEAD_HALF_H = 5;
+const FRET_HALF_W = 6;
+const FRET_HALF_H = 7;
+
 /*
  * Draw the whole score onto the element: one SVG stave per part-staff per measure,
  * placed at the boxes computed by computeLayout, with clefs/keys/time signatures,
- * notes, and the brace/barline connectors that group parts into systems.
+ * notes, and the brace/barline connectors that group parts into systems. Returns the
+ * hit-index geometry (notehead/fret/measure boxes) in final score space.
  */
 export function drawScore(
 	canvas: HTMLCanvasElement,
 	parts: Part[],
 	layout: ScoreLayout,
 	config: Config,
-): void {
+): RawGeometry {
 	const {
 		measureCount,
 		boxes,
@@ -835,6 +874,8 @@ export function drawScore(
 		pageTop: number;
 		pageBottom: number;
 		observedOverflow: Map<number, number>;
+		rawNotes: RawNote[];
+		rawMeasures: RawMeasure[];
 	} => {
 		// One note map for the whole score: ties and slurs can span a barline, so their
 		// two endpoints may live in different measures. Notes are drawn measure by
@@ -857,6 +898,10 @@ export function drawScore(
 		// top stave into that gap — is covered by topOverflow, measured on a prior pass.
 		let pageBottom = 0;
 		let pageTop = Infinity;
+		// Hit-index geometry collected this pass, in scratch space; the caller shifts it into
+		// final score space once cropTop is known. Only the final pass's arrays are kept.
+		const rawNotes: RawNote[] = [];
+		const rawMeasures: RawMeasure[] = [];
 		let systemTopY = layout.top + topSlack;
 		let systemContentBottom = systemTopY;
 		let currentSystem = -1;
@@ -1235,6 +1280,96 @@ export function drawScore(
 			pageBottom = Math.max(pageBottom, noteExtent.bottom);
 			systemContentBottom = Math.max(systemContentBottom, noteExtent.bottom);
 			pageTop = Math.min(pageTop, noteExtent.top);
+
+			// Collect hit-index boxes now that this measure's notes are formatted (positions
+			// final). Each notehead/fret maps back to its mdom note; measure boxes back each
+			// measure's staff column. Still scratch space — shifted to score space by the caller.
+			for (const p of systemPending) {
+				if (p.isTab) {
+					const tabStave = p.stave as TabStave;
+					for (const { note, chord } of p.tabChords) {
+						const x = note.getAbsoluteX();
+						for (const mnote of chord.notes) {
+							const string = mnote.string;
+							const fret = mnote.fret;
+							if (string === null || fret === null) {
+								continue;
+							}
+							const y = tabStave.getYForLine(string - 1);
+							rawNotes.push({
+								mnote,
+								rect: new Rect(
+									x - FRET_HALF_W,
+									y - FRET_HALF_H,
+									2 * FRET_HALF_W,
+									2 * FRET_HALF_H,
+								),
+								chord: chord.notes,
+								measureIndex: m,
+								tab: { string, fret },
+								glyph: null,
+							});
+						}
+					}
+				} else {
+					for (const { note, chord } of p.noteChords) {
+						// The notehead glyph's true x-span (getAbsoluteX is the tick anchor, left of
+						// the notehead — centering on it puts decorations off the note). y per
+						// notehead comes from getYs; noteHeads is indexed in the same (chord.notes)
+						// order, so heads[i] is this note's glyph.
+						const headX = note.getNoteHeadBeginX();
+						const headWidth = note.getNoteHeadEndX() - headX;
+						const ys = note.getYs();
+						const heads = note.noteHeads;
+						chord.notes.forEach((mnote, i) => {
+							const y = ys[i];
+							if (y === undefined) {
+								return;
+							}
+							// Capture the exact stamp vexflow drew (text + font + baseline) so a
+							// decoration can replay it in color — see Decorations. Scratch space; the
+							// caller shifts y by cropTop into score space alongside the rect. Read x
+							// from the bounding box (this.x + xShift), not getX(): a NoteHead borrows
+							// its StaveNote's tick context, so the inherited Tickable.getX() throws.
+							// The baseline y is the notehead's staff y (ys[i]); noteheads carry no yShift.
+							const head = heads[i];
+							const glyph = head
+								? {
+										text: head.getText(),
+										font: head.getFont(),
+										x: head.getBoundingBox().getX(),
+										y,
+									}
+								: null;
+							rawNotes.push({
+								mnote,
+								rect: new Rect(
+									headX,
+									y - NOTEHEAD_HALF_H,
+									headWidth,
+									2 * NOTEHEAD_HALF_H,
+								),
+								chord: chord.notes,
+								measureIndex: m,
+								tab: null,
+								glyph,
+							});
+						});
+					}
+				}
+			}
+			if (systemTop && systemBottom) {
+				rawMeasures.push({
+					rect: new Rect(
+						measureX,
+						systemY,
+						measureWidth,
+						Math.max(0, systemContentBottom - systemY),
+					),
+					index: m,
+				});
+			}
+
 			if (noteExtent.top < Infinity) {
 				systemHighestTop.set(
 					systemIndex,
@@ -1405,18 +1540,22 @@ export function drawScore(
 				observedOverflow.set(idx, Math.max(0, topY - highest));
 			}
 		}
-		return { pageTop, pageBottom, observedOverflow };
+		return { pageTop, pageBottom, observedOverflow, rawNotes, rawMeasures };
 	};
 
 	// Multi-system scores can clash where a system's notes rise above its top stave into
 	// the previous system's depth. Pass one measures that per-system overflow; if any is
 	// found, pass two redraws (onto the freshly cleared scratch) with the overflow reserved
 	// above each system. Single-system scores never stack, so one pass suffices.
-	let { pageTop, pageBottom, observedOverflow } = runPass(new Map());
-	if (systemCount > 1 && [...observedOverflow.values()].some((v) => v > 0)) {
+	let pass = runPass(new Map());
+	if (
+		systemCount > 1 &&
+		[...pass.observedOverflow.values()].some((v) => v > 0)
+	) {
 		renderer.resize(width, scratchHeight);
-		({ pageTop, pageBottom } = runPass(observedOverflow));
+		pass = runPass(pass.observedOverflow);
 	}
+	const { pageTop, pageBottom } = pass;
 
 	// Crop to the lowest thing actually drawn so deep ledger lines in the bottom
 	// system aren't clipped and there's no trailing whitespace. Sizing the real
@@ -1450,4 +1589,20 @@ export function drawScore(
 			scratch.width,
 			canvas.height,
 		);
+
+	// The geometry was collected in scratch space; the blit shifts content up by cropTop, so
+	// translate every box into final score space (the canvas's own coordinates). dpr stays out —
+	// these are CSS px, like getAbsoluteX/getYs.
+	const toScore = (r: Rect) => r.translate(0, -cropTop);
+	const toScoreGlyph = (g: RawNote['glyph']) =>
+		g ? { ...g, y: g.y - cropTop } : null;
+	return {
+		bounds: new Rect(0, 0, width, cssHeight),
+		notes: pass.rawNotes.map((n) => ({
+			...n,
+			rect: toScore(n.rect),
+			glyph: toScoreGlyph(n.glyph),
+		})),
+		measures: pass.rawMeasures.map((mm) => ({ ...mm, rect: toScore(mm.rect) })),
+	};
 }
diff --git a/src/events.test.ts b/src/events.test.ts
new file mode 100644
index 000000000..6f57a5c6e
--- /dev/null
+++ b/src/events.test.ts
@@ -0,0 +1,66 @@
+import { expect, test } from 'bun:test';
+import { EventBus } from './events';
+
+// A tiny event map for exercising the generic bus in isolation.
+interface TestMap {
+	ping: { n: number };
+	pong: string;
+}
+
+test('emit delivers to every listener for the type, not others', () => {
+	const bus = new EventBus<TestMap>();
+	const pings: number[] = [];
+	const pongs: string[] = [];
+	bus.addEventListener('ping', (e) => pings.push(e.n));
+	bus.addEventListener('ping', (e) => pings.push(e.n * 10));
+	bus.addEventListener('pong', (e) => pongs.push(e));
+
+	bus.emit('ping', { n: 2 });
+	expect(pings).toEqual([2, 20]);
+	expect(pongs).toEqual([]);
+});
+
+test('count reflects registrations and dedups the same listener', () => {
+	const bus = new EventBus<TestMap>();
+	const listener = (_e: { n: number }) => {};
+	expect(bus.count('ping')).toBe(0);
+	bus.addEventListener('ping', listener);
+	bus.addEventListener('ping', listener); // same ref -> still one
+	expect(bus.count('ping')).toBe(1);
+	bus.addEventListener('ping', (_e) => {});
+	expect(bus.count('ping')).toBe(2);
+});
+
+test('removeEventListener stops delivery and decrements count', () => {
+	const bus = new EventBus<TestMap>();
+	const seen: number[] = [];
+	const listener = (e: { n: number }) => seen.push(e.n);
+	bus.addEventListener('ping', listener);
+	bus.emit('ping', { n: 1 });
+	bus.removeEventListener('ping', listener);
+	bus.emit('ping', { n: 2 });
+	expect(seen).toEqual([1]);
+	expect(bus.count('ping')).toBe(0);
+});
+
+test('emit with no listeners is a no-op', () => {
+	const bus = new EventBus<TestMap>();
+	expect(() => bus.emit('pong', 'x')).not.toThrow();
+});
+
+test('a listener unsubscribing mid-dispatch does not perturb the current fan-out', () => {
+	const bus = new EventBus<TestMap>();
+	const seen: string[] = [];
+	const a = (_e: { n: number }) => {
+		seen.push('a');
+		bus.removeEventListener('ping', b); // remove a not-yet-called listener mid-dispatch
+	};
+	const b = (_e: { n: number }) => seen.push('b');
+	bus.addEventListener('ping', a);
+	bus.addEventListener('ping', b);
+	bus.emit('ping', { n: 0 });
+	// b was still called this round (iteration is over a snapshot), but is gone next round.
+	expect(seen).toEqual(['a', 'b']);
+	bus.emit('ping', { n: 0 });
+	expect(seen).toEqual(['a', 'b', 'a']);
+});
diff --git a/src/events.ts b/src/events.ts
new file mode 100644
index 000000000..14d2b3ea1
--- /dev/null
+++ b/src/events.ts
@@ -0,0 +1,91 @@
+import type { PointerTarget } from './targets';
+
+/*
+ * The event seam. `EventListenable<M>` is the abstraction over add/removeEventListener that the
+ * public Score implements (M maps an event name to its payload type); `EventBus<M>` is the
+ * reusable production implementer the Score delegates to. Callers are coupled to the interface,
+ * never the bus. Tests drive the bus directly.
+ */
+export interface EventListenable<M> {
+	addEventListener<K extends keyof M>(
+		type: K,
+		listener: (event: M[K]) => void,
+	): void;
+	removeEventListener<K extends keyof M>(
+		type: K,
+		listener: (event: M[K]) => void,
+	): void;
+}
+
+type Listener<M, K extends keyof M> = (event: M[K]) => void;
+
+/* A typed multi-listener dispatcher. A per-type Set keeps registration idempotent (adding the
+ * same listener twice is one entry) and `count` lets an owner bind/unbind an underlying source
+ * lazily — see Score, which only attaches a DOM listener while someone is subscribed. */
+export class EventBus<M> implements EventListenable<M> {
+	private readonly listeners: { [K in keyof M]?: Set<Listener<M, K>> } = {};
+
+	addEventListener<K extends keyof M>(type: K, listener: Listener<M, K>): void {
+		let set = this.listeners[type];
+		if (!set) {
+			set = new Set();
+			this.listeners[type] = set;
+		}
+		set.add(listener);
+	}
+
+	removeEventListener<K extends keyof M>(
+		type: K,
+		listener: Listener<M, K>,
+	): void {
+		this.listeners[type]?.delete(listener);
+	}
+
+	/* Dispatch to every listener for `type`. Iterates a copy so a listener that unsubscribes
+	 * (or subscribes) mid-dispatch doesn't perturb the in-progress fan-out. */
+	emit<K extends keyof M>(type: K, event: M[K]): void {
+		const set = this.listeners[type];
+		if (!set) {
+			return;
+		}
+		for (const listener of [...set]) {
+			listener(event);
+		}
+	}
+
+	count<K extends keyof M>(type: K): number {
+		return this.listeners[type]?.size ?? 0;
+	}
+}
+
+/* A pointer interaction over the score: the target under the pointer (null on empty space), the
+ * pointer position in score space, and the raw DOM event for everything else (buttons, modifier
+ * keys, preventDefault). */
+export interface PointerTargetEvent {
+	readonly target: PointerTarget | null;
+	readonly point: { x: number; y: number };
+	readonly native: PointerEvent;
+}
+
+/* The container scrolled: its new scroll offset plus the raw event. */
+export interface ScoreScrollEvent {
+	readonly left: number;
+	readonly top: number;
+	readonly native: Event;
+}
+
+/* The rendered area changed size (the caller's container resized): its new content-box size. */
+export interface ScoreResizeEvent {
+	readonly width: number;
+	readonly height: number;
+}
+
+/* The events a Score dispatches, keyed by name. Pointer events hit-test; scroll/resize don't. */
+export interface ScoreEventMap {
+	pointermove: PointerTargetEvent;
+	pointerdown: PointerTargetEvent;
+	pointerup: PointerTargetEvent;
+	click: PointerTargetEvent;
+	scroll: ScoreScrollEvent;
+	resize: ScoreResizeEvent;
+}
diff --git a/src/hit.test.ts b/src/hit.test.ts
new file mode 100644
index 000000000..e8569083e
--- /dev/null
+++ b/src/hit.test.ts
@@ -0,0 +1,137 @@
+import { expect, test } from 'bun:test';
+import { MDOMParser } from '@stringsync/mdom';
+import { Rect } from './geometry';
+import { buildTargets, type RawGeometry, type RawNote } from './hit';
+import type {
+	Bounded,
+	Decorator,
+	Note,
+	TabPosition,
+	Viewport,
+} from './targets';
+
+class FakeViewport implements Viewport {
+	clientRectOf(rect: Rect): DOMRect {
+		return { x: rect.x, y: rect.y, width: rect.w, height: rect.h } as DOMRect;
+	}
+	toScoreSpace(clientX: number, clientY: number): { x: number; y: number } {
+		return { x: clientX, y: clientY };
+	}
+}
+
+class FakeDecorator implements Decorator {
+	setColor(): void {}
+	setHalo(): void {}
+	isColored(_target: Bounded): boolean {
+		return false;
+	}
+	isHaloed(_target: Bounded): boolean {
+		return false;
+	}
+}
+
+const XML = `<?xml version="1.0"?>
+<score-partwise version="4.0">
+  <part-list><score-part id="P1"><part-name>M</part-name></score-part></part-list>
+  <part id="P1">
+    <measure number="1">
+      <attributes><divisions>1</divisions></attributes>
+      <note><pitch><step>C</step><octave>4</octave></pitch><duration>1</duration><type>quarter</type></note>
+      <note><chord/><pitch><step>E</step><octave>4</octave></pitch><duration>1</duration><type>quarter</type></note>
+      <note><pitch><step>B</step><alter>-1</alter><octave>3</octave></pitch><duration>1</duration><type>quarter</type></note>
+    </measure>
+  </part>
+</score-partwise>`;
+
+function must<T>(value: T | undefined, what: string): T {
+	if (value === undefined) {
+		throw new Error(`missing ${what}`);
+	}
+	return value;
+}
+
+function build() {
+	const mdoc = new MDOMParser().parseFromString(XML);
+	const chords = must(
+		mdoc.score.parts[0]?.measures[0]?.voices[0],
+		'voice',
+	).chords;
+	const mC = must(chords[0]?.notes[0], 'C');
+	const mE = must(chords[0]?.notes[1], 'E');
+	const mBb = must(chords[1]?.notes[0], 'Bb');
+
+	// C and E stack as a chord; Bb is a lone tab note (fret 3 on string 2).
+	const notes: RawNote[] = [
+		{
+			mnote: mC,
+			rect: new Rect(50, 40, 8, 8),
+			chord: [mC, mE],
+			measureIndex: 0,
+			tab: null,
+			glyph: null,
+		},
+		{
+			mnote: mE,
+			rect: new Rect(50, 50, 8, 8),
+			chord: [mC, mE],
+			measureIndex: 0,
+			tab: null,
+			glyph: null,
+		},
+		{
+			mnote: mBb,
+			rect: new Rect(90, 40, 6, 6),
+			chord: [mBb],
+			measureIndex: 0,
+			tab: { string: 2, fret: 3 },
+			glyph: null,
+		},
+	];
+	const geometry: RawGeometry = {
+		bounds: new Rect(0, 0, 200, 100),
+		notes,
+		measures: [{ rect: new Rect(0, 0, 200, 100), index: 0 }],
+	};
+	return buildTargets(geometry, new FakeViewport(), new FakeDecorator());
+}
+
+test('a notehead beats the measure background under it', () => {
+	const hit = build().hitTest({ x: 54, y: 44 });
+	expect(hit?.type).toBe('note');
+	expect((hit as Note).getPitch()).toBe('C/4');
+});
+
+test('empty staff space hits the measure', () => {
+	const hit = build().hitTest({ x: 150, y: 80 });
+	expect(hit?.type).toBe('measure');
+});
+
+test('a chord stack resolves to the notehead under the point', () => {
+	const tester = build();
+	expect((tester.hitTest({ x: 54, y: 44 }) as Note).getPitch()).toBe('C/4');
+	expect((tester.hitTest({ x: 54, y: 54 }) as Note).getPitch()).toBe('E/4');
+});
+
+test('a tab fret hits a TabPosition, not the note; both cross-link', () => {
+	const hit = build().hitTest({ x: 92, y: 42 });
+	expect(hit?.type).toBe('tab-position');
+	const tab = hit as TabPosition;
+	expect(tab.getString()).toBe(2);
+	expect(tab.getFret()).toBe(3);
+	const note = tab.getNote();
+	expect(note.getPitch()).toBe('Bb/3');
+	expect(note.getTabPosition()).toBe(tab);
+});
+
+test('a notation notehead has no tab position', () => {
+	const note = build().hitTest({ x: 54, y: 44 }) as Note;
+	expect(note.getTabPosition()).toBeNull();
+});
+
+test('chordmates are wired from the raw chord grouping', () => {
+	const tester = build();
+	const c = tester.hitTest({ x: 54, y: 44 }) as Note;
+	const e = tester.hitTest({ x: 54, y: 54 }) as Note;
+	expect(c.getChordSiblings({ includeSelf: false })).toEqual([e]);
+	expect(c.isChordMember()).toBe(true);
+});
diff --git a/src/hit.ts b/src/hit.ts
new file mode 100644
index 000000000..594a8aca6
--- /dev/null
+++ b/src/hit.ts
@@ -0,0 +1,150 @@
+import type { Note as MNote } from '@stringsync/mdom';
+import { Rect } from './geometry';
+import { QuadTree } from './quadtree';
+import {
+	type Decorator,
+	Measure,
+	Note,
+	type NoteGlyph,
+	type PointerTarget,
+	TabPosition,
+	type Viewport,
+} from './targets';
+
+/*
+ * The hit index: a spatial map from a point in score space to the target under it. Built once
+ * per render from the geometry the draw pass emits, then queried on every pointer event. The
+ * QuadTree (the renderer's collision broad-phase) doubles as the index — targets are Bounded,
+ * so they're valid items.
+ */
+
+/* A notehead or fret the draw pass laid out, in score space. `tab` is set when this is a tab
+ * fret rendering (the note's string/fret); null for a notation notehead. `chord` lists every
+ * mdom note sharing this note's onset so chordmates resolve. mnote stays internal. */
+export interface RawNote {
+	mnote: MNote;
+	rect: Rect;
+	chord: MNote[];
+	measureIndex: number;
+	tab: { string: number; fret: number } | null;
+	/* The engraved notehead glyph (for recoloring); null for a tab fret or a rest. */
+	glyph: NoteGlyph | null;
+}
+
+export interface RawMeasure {
+	rect: Rect;
+	index: number;
+}
+
+/* Everything the draw pass emits for the index, in score space (crop already applied). */
+export interface RawGeometry {
+	bounds: Rect;
+	notes: RawNote[];
+	measures: RawMeasure[];
+}
+
+export interface HitTester {
+	hitTest(point: { x: number; y: number }): PointerTarget | null;
+}
+
+export class QuadTreeHitTester implements HitTester {
+	constructor(private readonly tree: QuadTree<PointerTarget>) {}
+
+	/*
+	 * The target under `point`: a foreground glyph (note / fret) beats the measure background it
+	 * sits on, and among same-tier overlaps the tighter (smaller-area) box wins — so a notehead
+	 * is picked over the measure, and the nearer notehead of a chord over its neighbor.
+	 */
+	hitTest(point: { x: number; y: number }): PointerTarget | null {
+		const probe = new Rect(point.x, point.y, 1, 1);
+		let best: PointerTarget | null = null;
+		let bestArea = Number.POSITIVE_INFINITY;
+		let bestForeground = false;
+		for (const target of this.tree.query(probe)) {
+			const foreground = target.type !== 'measure';
+			const area = target.rect.w * target.rect.h;
+			const better =
+				best === null ||
+				(foreground && !bestForeground) ||
+				(foreground === bestForeground && area < bestArea);
+			if (better) {
+				best = target;
+				bestArea = area;
+				bestForeground = foreground;
+			}
+		}
+		return best;
+	}
+}
+
+/*
+ * Turn the draw pass's raw geometry into linked target wrappers and index them. Pure given its
+ * inputs (no DOM, no rendering), so it's unit-tested directly. A tab note becomes both a Note
+ * (its pitch/beats) and a TabPosition (its fret); only the visible glyph is inserted into the
+ * tree — the TabPosition for a tab note, the Note for a notation notehead — so a point hits one
+ * target, while the other stays reachable via getNote()/getTabPosition().
+ *
+ * The two maps double as the NoteLookup/TabLookup the wrappers resolve their cross-links through;
+ * they're fully populated before any query runs, so the deferred resolution always lands.
+ */
+export function buildTargets(
+	geometry: RawGeometry,
+	viewport: Viewport,
+	decorator: Decorator,
+): HitTester {
+	const measures = new Map<number, Measure>();
+	for (const m of geometry.measures) {
+		measures.set(m.index, new Measure(m.rect, viewport));
+	}
+
+	const noteByMnote = new Map<MNote, Note>();
+	const tabByMnote = new Map<MNote, TabPosition>();
+
+	for (const rn of geometry.notes) {
+		const measure = measures.get(rn.measureIndex);
+		if (!measure) {
+			continue;
+		}
+		noteByMnote.set(
+			rn.mnote,
+			new Note({
+				mnote: rn.mnote,
+				rect: rn.rect,
+				viewport,
+				decorator,
+				measure,
+				chord: rn.chord,
+				notes: noteByMnote,
+				tabs: tabByMnote,
+				glyph: rn.glyph,
+			}),
+		);
+	}
+
+	for (const rn of geometry.notes) {
+		const note = noteByMnote.get(rn.mnote);
+		if (!rn.tab || !note) {
+			continue;
+		}
+		tabByMnote.set(
+			rn.mnote,
+			new TabPosition(rn.rect, viewport, {
+				string: rn.tab.string,
+				fret: rn.tab.fret,
+				note,
+			}),
+		);
+	}
+
+	const tree = new QuadTree<PointerTarget>(geometry.bounds);
+	for (const rn of geometry.notes) {
+		const target = tabByMnote.get(rn.mnote) ?? noteByMnote.get(rn.mnote);
+		if (target) {
+			tree.insert(target);
+		}
+	}
+	for (const measure of measures.values()) {
+		tree.insert(measure);
+	}
+	return new QuadTreeHitTester(tree);
+}
diff --git a/src/index.ts b/src/index.ts
index d4e2c5337..df7ca44d9 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -6,6 +6,25 @@ export {
 	type ChordSpec,
 } from './chord-diagram';
 export type { Config } from './config';
+export type {
+	EventListenable,
+	PointerTargetEvent,
+	ScoreEventMap,
+	ScoreResizeEvent,
+	ScoreScrollEvent,
+} from './events';
 export type { FontConfig, FontOverride } from './fonts';
+export { Rect } from './geometry';
 export type { Layout, MeasureNumbering } from './layout';
 export * from './render';
+export { Score } from './score';
+export type { Layer, LayerKind } from './stage';
+export {
+	type Bounded,
+	Measure,
+	Note,
+	type NoteGlyph,
+	type PointerTarget,
+	TabPosition,
+	type Toggle,
+} from './targets';
diff --git a/src/render.ts b/src/render.ts
index 62d948dbb..391e69696 100644
--- a/src/render.ts
+++ b/src/render.ts
@@ -1,25 +1,42 @@
-import { MDOMParser, type MDocument } from '@stringsync/mdom';
+import { MDOMParser } from '@stringsync/mdom';
 import { VexFlow } from 'vexflow';
 import { type Config, DEFAULT_CONFIG } from './config';
+import { Decorations } from './decorations';
 import { drawScore } from './draw';
 import { loadFonts } from './fonts';
+import { Rect } from './geometry';
+import { buildTargets, type RawGeometry } from './hit';
 import { computeLayout } from './layout';
+import { Score } from './score';
+import { Stage } from './stage';
+
+const EMPTY_GEOMETRY: RawGeometry = {
+	bounds: new Rect(0, 0, 0, 0),
+	notes: [],
+	measures: [],
+};
 
 /*
- * Render a MusicXML score onto a canvas: parse the input (a MusicXML string or a
- * compressed .mxl Blob), lay it out, and draw it. Merges the caller's partial config
- * over the defaults and sets VexFlow's global glyph fonts before drawing.
+ * Render a MusicXML score into a container: parse the input (a MusicXML string or a compressed
+ * .mxl Blob), build the stage inside the div, lay the score out, and draw it onto the stage's
+ * managed canvas. The caller never sees the canvas — only the returned Score, which owns the DOM
+ * and is the handle for events/decorations/layers (and dispose). Merges the caller's partial
+ * config over the defaults and sets VexFlow's global glyph fonts before drawing.
  */
 export async function render(
 	input: string | Blob,
-	canvas: HTMLCanvasElement,
+	container: HTMLDivElement,
 	config?: Partial<Config>,
-) {
+): Promise<Score> {
 	const resolved: Config = { ...DEFAULT_CONFIG, ...config };
 	if (resolved.minLastSystemFill < 0 || resolved.minLastSystemFill > 1) {
 		throw new RangeError('render: minLastSystemFill must be between 0 and 1');
 	}
-	const { notation, text } = loadFonts(canvas, resolved.fonts);
+
+	const stage = new Stage(container);
+	// Fonts and CSS vars go on the container; the managed canvas inherits them, so drawScore's
+	// getComputedStyle(canvas) read of --vexml-font-text still resolves.
+	const { notation, text } = loadFonts(container, resolved.fonts);
 	// VexFlow engraves glyphs from its own bundled font modules via global state, not the
 	// --vexml-font-notation CSS var. setFonts sets a CSS font-family stack the browser falls
 	// through per glyph: music glyphs (noteheads, clefs, the stacked "TAB" clef) come from the
@@ -30,39 +47,28 @@ export async function render(
 	// the whole CSS font string invalid and every glyph falls back to serif. Reset each call
 	// so one render's font choice can't leak into the next.
 	VexFlow.setFonts(`'${notation}'`, `'${text}'`, 'sans-serif');
-	if (typeof input === 'string') {
-		return renderMusicXML(input, canvas, resolved);
-	}
-	if (input instanceof Blob) {
-		return renderMXL(input, canvas, resolved);
-	}
-	throw new TypeError('render: input is not a string or Blob');
-}
-
-function renderMusicXML(
-	musicXML: string,
-	canvas: HTMLCanvasElement,
-	config: Config,
-) {
-	const parser = new MDOMParser();
-	const mdoc = parser.parseFromString(musicXML);
-	return renderMDoc(mdoc, canvas, config);
-}
 
-async function renderMXL(mxl: Blob, canvas: HTMLCanvasElement, config: Config) {
 	const parser = new MDOMParser();
-	const mdoc = await parser.parseFromBlob(mxl);
-	return renderMDoc(mdoc, canvas, config);
-}
+	const mdoc =
+		typeof input === 'string'
+			? parser.parseFromString(input)
+			: input instanceof Blob
+				? await parser.parseFromBlob(input)
+				: null;
+	if (mdoc === null) {
+		throw new TypeError('render: input is not a string or Blob');
+	}
 
-function renderMDoc(
-	mdoc: MDocument,
-	canvas: HTMLCanvasElement,
-	config: Config,
-) {
 	const parts = mdoc.score.parts;
-	if (parts.length === 0) {
-		return;
-	}
-	drawScore(canvas, parts, computeLayout(parts, config), config);
+	const geometry =
+		parts.length > 0
+			? drawScore(stage.base, parts, computeLayout(parts, resolved), resolved)
+			: EMPTY_GEOMETRY;
+
+	// The stage is the Viewport (score<->client transform) the targets map through, and the
+	// decorations are the Decorator their color/halo toggles delegate to (drawing on a content
+	// layer the stage hands them). Both feed buildTargets, which links the targets and indexes them.
+	const decorations = new Decorations(stage);
+	const index = buildTargets(geometry, stage, decorations);
+	return new Score(stage, index, decorations);
 }
diff --git a/src/score.test.ts b/src/score.test.ts
new file mode 100644
index 000000000..321355688
--- /dev/null
+++ b/src/score.test.ts
@@ -0,0 +1,211 @@
+import { expect, test } from 'bun:test';
+import { Decorations } from './decorations';
+import { Rect } from './geometry';
+import type { HitTester } from './hit';
+import { Score } from './score';
+import type { Host, Layer, LayerKind } from './stage';
+import { Measure, type PointerTarget, type Viewport } from './targets';
+
+// Separate fake classes fulfilling the injected seams (preferred over mocks).
+
+// A no-op 2D context: the real Decorations draws on the layer it gets from the host, so the fake
+// layer's context must absorb those calls. (What's painted is asserted in decorations.test.ts.)
+function noopContext(): CanvasRenderingContext2D {
+	return {
+		canvas: { width: 0, height: 0 },
+		fillStyle: '',
+		save() {},
+		restore() {},
+		setTransform() {},
+		clearRect() {},
+		beginPath() {},
+		ellipse() {},
+		arc() {},
+		fill() {},
+	} as unknown as CanvasRenderingContext2D;
+}
+
+class FakeLayer implements Layer {
+	disposed = false;
+	readonly ctx = noopContext();
+	constructor(readonly kind: LayerKind) {}
+	dispose(): void {
+		this.disposed = true;
+	}
+}
+
+class FakeHost implements Host {
+	readonly events = new EventTarget();
+	scroll = { left: 0, top: 0 };
+	resizeListener: ((size: { width: number; height: number }) => void) | null =
+		null;
+	resizeUnobserved = false;
+	disposed = false;
+	relayoutLayersCalls = 0;
+	readonly created: FakeLayer[] = [];
+	// Identity transform: client coords are score coords, so tests assert on the input directly.
+	toScoreSpace(clientX: number, clientY: number): { x: number; y: number } {
+		return { x: clientX, y: clientY };
+	}
+	observeResize(
+		onResize: (size: { width: number; height: number }) => void,
+	): () => void {
+		this.resizeListener = onResize;
+		return () => {
+			this.resizeUnobserved = true;
+			this.resizeListener = null;
+		};
+	}
+	createLayer(kind: LayerKind): Layer {
+		const layer = new FakeLayer(kind);
+		this.created.push(layer);
+		return layer;
+	}
+	relayoutLayers(): void {
+		this.relayoutLayersCalls++;
+	}
+	dispose(): void {
+		this.disposed = true;
+	}
+}
+
+class FakeHitTester implements HitTester {
+	readonly probes: Array<{ x: number; y: number }> = [];
+	constructor(private readonly result: PointerTarget | null) {}
+	hitTest(point: { x: number; y: number }): PointerTarget | null {
+		this.probes.push(point);
+		return this.result;
+	}
+}
+
+// A bare EventTarget has no DOM tree, so a synthetic Event with the coords the handler reads is
+// enough to drive a pointer event through.
+class FakePointerEvent extends Event {
+	constructor(
+		type: string,
+		readonly clientX: number,
+		readonly clientY: number,
+	) {
+		super(type);
+	}
+}
+
+const viewport: Viewport = {
+	clientRectOf: (r) => ({ x: r.x, y: r.y, width: r.w, height: r.h }) as DOMRect,
+	toScoreSpace: (x, y) => ({ x, y }),
+};
+
+function fixture(target: PointerTarget | null) {
+	const host = new FakeHost();
+	const index = new FakeHitTester(target);
+	const decorations = new Decorations(host);
+	const score = new Score(host, index, decorations);
+	return { host, index, decorations, score };
+}
+
+test('a pointer event hit-tests the point and emits target, score-space point, and native', () => {
+	const target = new Measure(new Rect(0, 0, 10, 10), viewport);
+	const { host, index, score } = fixture(target);
+	const seen: Array<{ type: string; x: number; y: number; native: Event }> = [];
+	score.addEventListener('pointermove', (e) =>
+		seen.push({
+			type: e.target?.type ?? 'none',
+			x: e.point.x,
+			y: e.point.y,
+			native: e.native,
+		}),
+	);
+
+	const native = new FakePointerEvent('pointermove', 30, 40);
+	host.events.dispatchEvent(native);
+
+	expect(index.probes).toEqual([{ x: 30, y: 40 }]);
+	expect(seen).toHaveLength(1);
+	expect(seen[0]).toMatchObject({ type: 'measure', x: 30, y: 40, native });
+});
+
+test('listeners are bound lazily: no subscriber means no hit-testing', () => {
+	const { host, index } = fixture(null);
+	host.events.dispatchEvent(new FakePointerEvent('pointermove', 1, 2));
+	expect(index.probes).toHaveLength(0);
+});
+
+test('the source is detached when the last listener leaves', () => {
+	const { host, index, score } = fixture(null);
+	const listener = () => {};
+	score.addEventListener('pointermove', listener);
+	host.events.dispatchEvent(new FakePointerEvent('pointermove', 1, 1));
+	score.removeEventListener('pointermove', listener);
+	host.events.dispatchEvent(new FakePointerEvent('pointermove', 2, 2));
+	// Only the dispatch made while subscribed reached the hit tester.
+	expect(index.probes).toEqual([{ x: 1, y: 1 }]);
+});
+
+test('the source stays bound until every listener for the type is removed', () => {
+	const { host, index, score } = fixture(null);
+	const a = () => {};
+	const b = () => {};
+	score.addEventListener('pointermove', a);
+	score.addEventListener('pointermove', b);
+	score.removeEventListener('pointermove', a);
+	host.events.dispatchEvent(new FakePointerEvent('pointermove', 5, 5));
+	expect(index.probes).toEqual([{ x: 5, y: 5 }]); // still bound for b
+	score.removeEventListener('pointermove', b);
+	host.events.dispatchEvent(new FakePointerEvent('pointermove', 6, 6));
+	expect(index.probes).toEqual([{ x: 5, y: 5 }]); // now detached
+});
+
+test('scroll events carry the offset and the score.scroll getter reflects the host', () => {
+	const { host, score } = fixture(null);
+	host.scroll = { left: 12, top: 34 };
+	const seen: Array<{ left: number; top: number }> = [];
+	score.addEventListener('scroll', (e) =>
+		seen.push({ left: e.left, top: e.top }),
+	);
+	host.events.dispatchEvent(new Event('scroll'));
+	expect(seen).toEqual([{ left: 12, top: 34 }]);
+	expect(score.scroll).toEqual({ left: 12, top: 34 });
+});
+
+test('resize is observed from construction and re-fits viewport layers before emitting', () => {
+	const { host, score } = fixture(null);
+	// Observed eagerly (it also drives viewport-layer sizing), not lazily on first subscriber.
+	expect(host.resizeListener).not.toBeNull();
+
+	const seen: Array<{ width: number; height: number }> = [];
+	let layersResizedAtEmit = -1;
+	score.addEventListener('resize', (e) => {
+		layersResizedAtEmit = host.relayoutLayersCalls;
+		seen.push({ width: e.width, height: e.height });
+	});
+	host.resizeListener?.({ width: 100, height: 50 });
+
+	expect(seen).toEqual([{ width: 100, height: 50 }]);
+	// Layers were re-fit (and cleared) before the caller's handler ran, so its redraw lands clean.
+	expect(layersResizedAtEmit).toBe(1);
+});
+
+test('addLayer delegates to the host; removeLayer disposes the layer', () => {
+	const { host, score } = fixture(null);
+	const layer = score.addLayer('content');
+	expect(host.created).toHaveLength(1);
+	expect(host.created[0]).toBe(layer as FakeLayer);
+	score.removeLayer(layer);
+	expect(host.created[0]?.disposed).toBe(true);
+});
+
+test('dispose detaches every listener and tears down decorations and host', () => {
+	const target = new Measure(new Rect(0, 0, 10, 10), viewport);
+	const { host, index, decorations, score } = fixture(target);
+	score.addEventListener('pointermove', () => {});
+	score.addEventListener('resize', () => {});
+	decorations.setColor(target, '#ff0000');
+
+	score.dispose();
+
+	expect(host.disposed).toBe(true);
+	expect(host.resizeUnobserved).toBe(true);
+	expect(decorations.isColored(target)).toBe(false); // decorations.dispose() ran
+	host.events.dispatchEvent(new FakePointerEvent('pointermove', 9, 9));
+	expect(index.probes).toHaveLength(0); // pointer handler detached
+});
diff --git a/src/score.ts b/src/score.ts
new file mode 100644
index 000000000..9d953a42a
--- /dev/null
+++ b/src/score.ts
@@ -0,0 +1,133 @@
+import type { Decorations } from './decorations';
+import { EventBus, type EventListenable, type ScoreEventMap } from './events';
+import type { HitTester } from './hit';
+import type { Host, Layer, LayerKind } from './stage';
+
+/*
+ * A rendered score: the handle render() returns. Owns the DOM vexml built (the Stage/Host) and
+ * lets callers subscribe to pointer/scroll/resize events through the EventListenable interface,
+ * and stack their own drawing layers over the score. Pointer events are hit-tested against the
+ * index to the target under the pointer. dispose() tears the whole thing down so a caller can
+ * re-render or unmount cleanly.
+ *
+ * Pointer/scroll DOM listeners are bound lazily: the underlying source is attached only while at
+ * least one caller is subscribed, so an unobserved score does no per-pointer hit-testing. Resize
+ * is observed from construction instead — it also resizes viewport layers, which must happen even
+ * with no resize subscriber.
+ */
+export class Score implements EventListenable<ScoreEventMap> {
+	private readonly bus = new EventBus<ScoreEventMap>();
+	// The live DOM listeners (pointer/scroll), keyed by event name so unbind can remove the exact
+	// reference. Resize isn't here — it's a ResizeObserver, set up once below.
+	private readonly bound = new Map<string, EventListener>();
+	private readonly unobserveResize: () => void;
+
+	constructor(
+		private readonly host: Host,
+		private readonly index: HitTester,
+		private readonly decorations: Decorations,
+	) {
+		// On resize: re-sync the layers (viewport layers are refit and cleared; content layers just
+		// re-track the base canvas) before telling the caller, so a viewport-layer redraw in the
+		// resize handler lands on a correctly sized, cleared surface.
+		this.unobserveResize = host.observeResize((size) => {
+			host.relayoutLayers();
+			this.bus.emit('resize', size);
+		});
+	}
+
+	/* The container's current scroll offset (score space and client space differ only by it and
+	 * any zoom — getBoundingClientRect already folds scroll into hit-testing). */
+	get scroll(): { left: number; top: number } {
+		return this.host.scroll;
+	}
+
+	/* Add a caller-owned drawing layer over the score; returns it for drawing (via ctx) and removal
+	 * (via dispose, or removeLayer). A content layer spans the engraved score; a viewport layer
+	 * spans the visible box and is re-fit on resize. */
+	addLayer(kind: LayerKind): Layer {
+		return this.host.createLayer(kind);
+	}
+
+	removeLayer(layer: Layer): void {
+		layer.dispose();
+	}
+
+	addEventListener<K extends keyof ScoreEventMap>(
+		type: K,
+		listener: (event: ScoreEventMap[K]) => void,
+	): void {
+		const first = this.bus.count(type) === 0;
+		this.bus.addEventListener(type, listener);
+		if (first) {
+			this.bind(type);
+		}
+	}
+
+	removeEventListener<K extends keyof ScoreEventMap>(
+		type: K,
+		listener: (event: ScoreEventMap[K]) => void,
+	): void {
+		this.bus.removeEventListener(type, listener);
+		if (this.bus.count(type) === 0) {
+			this.unbind(type);
+		}
+	}
+
+	dispose(): void {
+		for (const [type, handler] of this.bound) {
+			this.host.events.removeEventListener(type, handler);
+		}
+		this.bound.clear();
+		this.unobserveResize();
+		this.decorations.dispose();
+		this.host.dispose();
+	}
+
+	// Attach the underlying source for a Score event on its first subscriber. Pointer events
+	// hit-test the point under them; scroll carries the new offset; resize is already observed
+	// from construction (for the layers), so there's nothing to bind here.
+	private bind(type: keyof ScoreEventMap): void {
+		switch (type) {
+			case 'resize':
+				return;
+			case 'scroll': {
+				const handler: EventListener = (native) => {
+					this.bus.emit('scroll', { ...this.host.scroll, native });
+				};
+				this.bound.set(type, handler);
+				this.host.events.addEventListener(type, handler);
+				return;
+			}
+			default: {
+				const handler: EventListener = (native) => {
+					const pointer = native as PointerEvent;
+					const point = this.host.toScoreSpace(
+						pointer.clientX,
+						pointer.clientY,
+					);
+					this.bus.emit(type, {
+						target: this.index.hitTest(point),
+						point,
+						native: pointer,
+					});
+				};
+				this.bound.set(type, handler);
+				this.host.events.addEventListener(type, handler);
+			}
+		}
+	}
+
+	// Detach the underlying source when the last subscriber for a Score event leaves. Resize stays
+	// observed (it serves the layers), so it's a no-op here.
+	private unbind(type: keyof ScoreEventMap): void {
+		if (type === 'resize') {
+			return;
+		}
+		const handler = this.bound.get(type);
+		if (handler) {
+			this.host.events.removeEventListener(type, handler);
+			this.bound.delete(type);
+		}
+	}
+}
diff --git a/src/stage.ts b/src/stage.ts
new file mode 100644
index 000000000..58a5e0252
--- /dev/null
+++ b/src/stage.ts
@@ -0,0 +1,253 @@
+import type { Rect } from './geometry';
+import type { Viewport } from './targets';
+
+/* Where a custom drawing layer sits. A `content` layer covers the whole engraved score (score
+ * space, scrolls with the content) — what decorations draw on. A `viewport` layer covers only the
+ * visible box (client space) and is resized as the container resizes. */
+export type LayerKind = 'content' | 'viewport';
+
+/* A caller-owned drawing surface stacked over the score. Only the 2D context is exposed — never
+ * the canvas, its size, or a clear — so the layer's lifecycle stays vexml's. The caller draws via
+ * ctx (CSS pixels; the dpr scale is applied for them) and removes the layer with dispose(). */
+export interface Layer {
+	readonly ctx: CanvasRenderingContext2D;
+	dispose(): void;
+}
+
+/* The minimal seam for making a drawing layer — what Decorations needs from the stage (it draws
+ * on its own content layer but needs nothing else). Stage satisfies it; a unit test injects a
+ * fake whose layer carries a recording context. */
+export interface LayerHost {
+	createLayer(kind: LayerKind): Layer;
+}
+
+/*
+ * What a Score needs from its host: the score<-client transform (toScoreSpace), a raw event
+ * source to bind pointer/scroll listeners on, the current scroll offset, a resize subscription,
+ * custom-layer creation/resizing, and teardown. Stage is the production implementer; a Score unit
+ * test injects a fake. Kept separate from Viewport (the targets' coordinate seam) so each consumer
+ * depends only on what it uses, even though Stage satisfies both.
+ */
+export interface Host extends LayerHost {
+	toScoreSpace(clientX: number, clientY: number): { x: number; y: number };
+	readonly events: EventTarget;
+	readonly scroll: { left: number; top: number };
+	observeResize(
+		onResize: (size: { width: number; height: number }) => void,
+	): () => void;
+	/* Re-sync every layer to the container's current geometry (called on resize). Viewport layers
+	 * are refit to the visible box (clearing them); content layers keep their score-resolution bitmap
+	 * (no clear) but re-track the base canvas's rendered box, so they stay aligned however the
+	 * caller's CSS has scaled the score. */
+	relayoutLayers(): void;
+	dispose(): void;
+}
+
+/*
+ * A managed overlay canvas — the production Layer. Absolutely positioned over the base canvas, dpr
+ * scaled so the caller's ctx draws in CSS pixels, and sized by its kind. Resizing resets the
+ * bitmap (which clears it) and re-applies the dpr transform. Back-references its Stage only to
+ * deregister on dispose (both live here and are disposed together).
+ */
+class ManagedLayer implements Layer {
+	readonly ctx: CanvasRenderingContext2D;
+
+	constructor(
+		readonly kind: LayerKind,
+		private readonly canvas: HTMLCanvasElement,
+		private readonly stage: Stage,
+	) {
+		const ctx = canvas.getContext('2d');
+		if (!ctx) {
+			throw new Error('vexml: 2D context unavailable for layer');
+		}
+		this.ctx = ctx;
+	}
+
+	resize(cssWidth: number, cssHeight: number): void {
+		const dpr = window.devicePixelRatio || 1;
+		this.canvas.width = Math.max(0, Math.round(cssWidth * dpr));
+		this.canvas.height = Math.max(0, Math.round(cssHeight * dpr));
+		this.canvas.style.width = `${cssWidth}px`;
+		this.canvas.style.height = `${cssHeight}px`;
+		// Setting width/height cleared the bitmap and reset the transform; re-apply dpr so the
+		// caller keeps drawing in CSS pixels. setTransform (not scale) stays idempotent on re-resize.
+		this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+	}
+
+	// Position and stretch the element's on-screen box, independent of the bitmap resolution resize()
+	// set. For a content layer this lets a fixed score-resolution bitmap be displayed at the base
+	// canvas's (possibly CSS-scaled) rendered size, so the overlay tracks it without a clearing resize.
+	place(left: number, top: number, width: number, height: number): void {
+		this.canvas.style.left = `${left}px`;
+		this.canvas.style.top = `${top}px`;
+		this.canvas.style.width = `${width}px`;
+		this.canvas.style.height = `${height}px`;
+	}
+
+	dispose(): void {
+		this.canvas.remove();
+		this.stage.forget(this);
+	}
+}
+
+/*
+ * The host: the DOM vexml builds inside the caller's container, and the coordinate authority
+ * between score space (where target rects live) and client/page space (where pointer events and
+ * DOM popups live). The caller hands render() a <div>; the Stage owns the canvas it draws the
+ * score onto and never exposes it to callers — they see only the Score.
+ *
+ * The base canvas is a plain in-flow child, so the container sizes to it exactly as a
+ * hand-placed <canvas> did — output stays pixel-identical. Custom layers stack over it as absolute
+ * overlays. The transform falls out of the base canvas's own getBoundingClientRect: score space is
+ * its CSS-pixel space with the origin at its top-left. Reading the live rect each call means page
+ * scroll and any CSS scaling of the canvas are handled for free.
+ */
+export class Stage implements Viewport, Host {
+	readonly base: HTMLCanvasElement;
+	private readonly prevPosition: string;
+	private readonly layers = new Set<ManagedLayer>();
+
+	constructor(private readonly container: HTMLDivElement) {
+		// A positioned container is the containing block the overlay layers anchor to. Only set it
+		// when the caller left position static, and remember it so dispose restores.
+		this.prevPosition = container.style.position;
+		if (!container.style.position) {
+			container.style.position = 'relative';
+		}
+		this.base = document.createElement('canvas');
+		// `vexml-canvas` is the stable hook callers style to size/scale the rendered score. They style
+		// this class (or the container), never the bare element — that keeps the overlay canvases
+		// (`vexml-layer`) out of their selectors. vexml leaves `display` to the caller so the engraved
+		// output stays byte-identical to a hand-placed canvas.
+		this.base.className = 'vexml-canvas';
+		container.appendChild(this.base);
+	}
+
+	clientRectOf(rect: Rect): DOMRect {
+		const { left, top, sx, sy } = this.frame();
+		return new DOMRect(
+			left + rect.x * sx,
+			top + rect.y * sy,
+			rect.w * sx,
+			rect.h * sy,
+		);
+	}
+
+	toScoreSpace(clientX: number, clientY: number): { x: number; y: number } {
+		const { left, top, sx, sy } = this.frame();
+		return { x: (clientX - left) / sx, y: (clientY - top) / sy };
+	}
+
+	// Bind on the container, not the canvas: canvas pointer/scroll events bubble up to it, and
+	// it's where the overlay layers live too, so one source covers the whole stage.
+	get events(): EventTarget {
+		return this.container;
+	}
+
+	get scroll(): { left: number; top: number } {
+		return { left: this.container.scrollLeft, top: this.container.scrollTop };
+	}
+
+	observeResize(
+		onResize: (size: { width: number; height: number }) => void,
+	): () => void {
+		// Report the visible (client) box — the size a viewport layer is given and the most useful
+		// "rendered area" for a caller — rather than the ResizeObserver's content-box entry.
+		const observer = new ResizeObserver(() => {
+			onResize({
+				width: this.container.clientWidth,
+				height: this.container.clientHeight,
+			});
+		});
+		observer.observe(this.container);
+		return () => observer.disconnect();
+	}
+
+	createLayer(kind: LayerKind): Layer {
+		const canvas = document.createElement('canvas');
+		// Overlay absolutely positioned within the (positioned) container. Purely visual: pointer
+		// events pass through to the container, where the Score hit-tests them — layers never capture
+		// input. `vexml-layer` marks it as vexml-owned so caller `vexml-canvas` styles skip it.
+		canvas.className = 'vexml-layer';
+		canvas.style.position = 'absolute';
+		canvas.style.pointerEvents = 'none';
+		const layer = new ManagedLayer(kind, canvas, this);
+		this.container.appendChild(canvas);
+		this.layers.add(layer);
+		this.sizeBitmap(layer);
+		this.placeLayer(layer);
+		return layer;
+	}
+
+	relayoutLayers(): void {
+		for (const layer of this.layers) {
+			// Viewport layers are tied to the visible box, so refit the bitmap (which clears them —
+			// callers redraw in their resize handler). Content layers keep their fixed score-resolution
+			// bitmap; only their on-screen box is re-placed, so the drawing scales without clearing.
+			if (layer.kind === 'viewport') {
+				this.sizeBitmap(layer);
+			}
+			this.placeLayer(layer);
+		}
+	}
+
+	// Deregister a layer disposing itself (called from ManagedLayer.dispose).
+	forget(layer: ManagedLayer): void {
+		this.layers.delete(layer);
+	}
+
+	dispose(): void {
+		for (const layer of [...this.layers]) {
+			layer.dispose();
+		}
+		this.base.remove();
+		this.container.style.position = this.prevPosition;
+	}
+
+	// Size a layer's drawing bitmap. A content layer's bitmap is fixed to the engraved score (the
+	// base canvas's intrinsic CSS box), so the caller always draws in score px — its element is then
+	// stretched over the base's rendered box by placeLayer. A viewport bitmap matches the visible box.
+	private sizeBitmap(layer: ManagedLayer): void {
+		if (layer.kind === 'content') {
+			layer.resize(
+				parseFloat(this.base.style.width) || 0,
+				parseFloat(this.base.style.height) || 0,
+			);
+		} else {
+			layer.resize(this.container.clientWidth, this.container.clientHeight);
+		}
+	}
+
+	// Position and stretch a layer's on-screen box over the base canvas. A content layer covers the
+	// base's *rendered* box (base.offset*, which reflect whatever CSS scaling the caller applied), so
+	// a score-resolution bitmap lines up 1:1 with the engraving at any size. A viewport layer is
+	// anchored at the base's offset but spans the container's visible box.
+	private placeLayer(layer: ManagedLayer): void {
+		const left = this.base.offsetLeft;
+		const top = this.base.offsetTop;
+		if (layer.kind === 'content') {
+			layer.place(left, top, this.base.offsetWidth, this.base.offsetHeight);
+		} else {
+			layer.place(
+				left,
+				top,
+				this.container.clientWidth,
+				this.container.clientHeight,
+			);
+		}
+	}
+
+	/*
+	 * The live score-space -> client-space mapping: the canvas's page offset plus the scale
+	 * between its rendered size and its score-space (CSS-px) size. Scale is 1 unless the caller
+	 * stretched the canvas with CSS; the `|| 1` guards an unsized (empty-score) canvas so it
+	 * maps 1:1 instead of dividing by zero.
+	 */
+	private frame(): { left: number; top: number; sx: number; sy: number } {
+		const r = this.base.getBoundingClientRect();
+		const w = parseFloat(this.base.style.width) || r.width || 1;
+		const h = parseFloat(this.base.style.height) || r.height || 1;
+		return { left: r.left, top: r.top, sx: r.width / w, sy: r.height / h };
+	}
+}
diff --git a/src/targets.test.ts b/src/targets.test.ts
new file mode 100644
index 000000000..b3438ce0e
--- /dev/null
+++ b/src/targets.test.ts
@@ -0,0 +1,188 @@
+import { expect, test } from 'bun:test';
+import { MDOMParser, type Note as MNote } from '@stringsync/mdom';
+import { Rect } from './geometry';
+import {
+	type Decoratable,
+	type Decorator,
+	Measure,
+	Note,
+	TabPosition,
+	type Viewport,
+} from './targets';
+
+// Separate fake classes that fulfill the injected interfaces (preferred over mocks).
+
+class FakeViewport implements Viewport {
+	clientRectOf(rect: Rect): DOMRect {
+		// bun's runtime has no DOMRect; a structural literal is enough for unit reads.
+		return {
+			x: rect.x,
+			y: rect.y,
+			width: rect.w,
+			height: rect.h,
+			top: rect.y,
+			left: rect.x,
+			right: rect.right,
+			bottom: rect.bottom,
+			toJSON: () => ({}),
+		} as DOMRect;
+	}
+	toScoreSpace(clientX: number, clientY: number): { x: number; y: number } {
+		return { x: clientX, y: clientY };
+	}
+}
+
+class FakeDecorator implements Decorator {
+	readonly colors = new Map<Decoratable, string>();
+	readonly halos = new Set<Decoratable>();
+	setColor(target: Decoratable, color: string | null): void {
+		if (color === null) {
+			this.colors.delete(target);
+		} else {
+			this.colors.set(target, color);
+		}
+	}
+	setHalo(target: Decoratable, on: boolean): void {
+		if (on) {
+			this.halos.add(target);
+		} else {
+			this.halos.delete(target);
+		}
+	}
+	isColored(target: Decoratable): boolean {
+		return this.colors.has(target);
+	}
+	isHaloed(target: Decoratable): boolean {
+		return this.halos.has(target);
+	}
+}
+
+const XML = `<?xml version="1.0"?>
+<score-partwise version="4.0">
+  <part-list><score-part id="P1"><part-name>Music</part-name></score-part></part-list>
+  <part id="P1">
+    <measure number="1">
+      <attributes><divisions>1</divisions></attributes>
+      <note><pitch><step>C</step><octave>4</octave></pitch><duration>1</duration><type>quarter</type></note>
+      <note><chord/><pitch><step>E</step><octave>4</octave></pitch><duration>1</duration><type>quarter</type></note>
+      <note><rest/><duration>1</duration><type>quarter</type></note>
+      <note><pitch><step>B</step><alter>-1</alter><octave>3</octave></pitch><duration>1</duration><type>quarter</type></note>
+    </measure>
+  </part>
+</score-partwise>`;
+
+function must<T>(value: T | undefined, what: string): T {
+	if (value === undefined) {
+		throw new Error(`fixture: missing ${what}`);
+	}
+	return value;
+}
+
+function fixture() {
+	const mdoc = new MDOMParser().parseFromString(XML);
+	const voice = must(mdoc.score.parts[0]?.measures[0]?.voices[0], 'voice');
+	const chords = voice.chords;
+	const mC = must(chords[0]?.notes[0], 'C');
+	const mE = must(chords[0]?.notes[1], 'E');
+	const mRest = must(chords[1]?.notes[0], 'rest');
+	const mBb = must(chords[2]?.notes[0], 'Bb');
+
+	const viewport = new FakeViewport();
+	const decorator = new FakeDecorator();
+	const measure = new Measure(new Rect(0, 0, 100, 50), viewport);
+
+	// The shared registries the wrappers resolve their cross-links through (a Map fulfills the
+	// NoteLookup / TabLookup interfaces). Populated as each note is built.
+	const notesByMnote = new Map<MNote, Note>();
+	const tabsByMnote = new Map<MNote, TabPosition>();
+	const base = (mnote: MNote, rect: Rect, chord: MNote[]): Note => {
+		const note = new Note({
+			mnote,
+			rect,
+			viewport,
+			decorator,
+			measure,
+			chord,
+			notes: notesByMnote,
+			tabs: tabsByMnote,
+			glyph: null,
+		});
+		notesByMnote.set(mnote, note);
+		return note;
+	};
+
+	// Chord [C4, E4], then a rest, then Bb3 (each its own solo chord).
+	const noteC = base(mC, new Rect(10, 10, 8, 8), [mC, mE]);
+	const noteE = base(mE, new Rect(10, 18, 8, 8), [mC, mE]);
+	const noteRest = base(mRest, new Rect(20, 10, 8, 8), [mRest]);
+	const noteBb = base(mBb, new Rect(30, 10, 8, 8), [mBb]);
+
+	return { viewport, decorator, measure, noteC, noteE, noteRest, noteBb };
+}
+
+test('getPitch formats vexflow keys and returns null for rests', () => {
+	const { noteC, noteE, noteRest, noteBb } = fixture();
+	expect(noteC.getPitch()).toBe('C/4');
+	expect(noteE.getPitch()).toBe('E/4');
+	expect(noteRest.getPitch()).toBeNull();
+	expect(noteBb.getPitch()).toBe('Bb/3');
+});
+
+test('getBeats and isGrace read the underlying note', () => {
+	const { noteC } = fixture();
+	expect(noteC.getBeats()).toBe(1);
+	expect(noteC.isGrace()).toBe(false);
+});
+
+test('chord membership and siblings', () => {
+	const { noteC, noteE, noteBb } = fixture();
+	expect(noteC.isChordMember()).toBe(true);
+	expect(noteBb.isChordMember()).toBe(false);
+	expect(noteC.getChordSiblings({ includeSelf: false })).toEqual([noteE]);
+	expect(noteC.getChordSiblings({ includeSelf: true })).toEqual([noteC, noteE]);
+});
+
+test('getMeasure and getTabPosition return the linked objects', () => {
+	const { noteC, measure } = fixture();
+	expect(noteC.getMeasure()).toBe(measure);
+	expect(noteC.getTabPosition()).toBeNull();
+});
+
+test('color toggle delegates to the decorator and reflects active state', () => {
+	const { noteC, decorator } = fixture();
+	expect(noteC.color.active).toBe(false);
+	noteC.color.on('#2962ff');
+	expect(decorator.colors.get(noteC)).toBe('#2962ff');
+	expect(noteC.color.active).toBe(true);
+	noteC.color.off();
+	expect(decorator.colors.has(noteC)).toBe(false);
+	expect(noteC.color.active).toBe(false);
+});
+
+test('halo toggle delegates to the decorator', () => {
+	const { noteC, decorator } = fixture();
+	noteC.halo.on();
+	expect(decorator.halos.has(noteC)).toBe(true);
+	expect(noteC.halo.active).toBe(true);
+	noteC.halo.off();
+	expect(noteC.halo.active).toBe(false);
+});
+
+test('getBoundingClientRect maps the score-space rect through the viewport', () => {
+	const { noteC } = fixture();
+	const r = noteC.getBoundingClientRect();
+	expect([r.x, r.y, r.width, r.height]).toEqual([10, 10, 8, 8]);
+});
+
+test('TabPosition exposes string/fret and links back to its note', () => {
+	const { noteC, viewport } = fixture();
+	const tab = new TabPosition(new Rect(0, 0, 6, 6), viewport, {
+		string: 3,
+		fret: 5,
+		note: noteC,
+	});
+	expect(tab.getString()).toBe(3);
+	expect(tab.getFret()).toBe(5);
+	expect(tab.getNote()).toBe(noteC);
+	expect(tab.type).toBe('tab-position');
+});
diff --git a/src/targets.ts b/src/targets.ts
new file mode 100644
index 000000000..0cbbf710c
--- /dev/null
+++ b/src/targets.ts
@@ -0,0 +1,245 @@
+import type { Note as MNote } from '@stringsync/mdom';
+import type { Rect } from './geometry';
+
+/*
+ * The interaction model: vexml-owned objects a caller gets from hit-testing a rendered score.
+ * They wrap the underlying @stringsync/mdom nodes but never expose them — a caller is coupled
+ * to these types only. Every target is laid out (Bounded) and built once during rendering, so
+ * identities are stable for the lifetime of a Score (reference equality works).
+ */
+
+/* Something with a known box. `rect` is in score space; getBoundingClientRect() maps it to the
+ * page through the live scroll/zoom transform (mirrors DOM Element.getBoundingClientRect). */
+export interface Bounded {
+	readonly rect: Rect;
+	getBoundingClientRect(): DOMRect;
+}
+
+/* A note's engraved glyph, captured so a decoration can re-stamp it in color on an overlay: the
+ * SMuFL text, the exact CSS font vexflow drew it with, and its baseline position in score space.
+ * Replaying vexflow's own fillText reproduces the notehead precisely — hollow notes stay hollow. */
+export interface NoteGlyph {
+	readonly text: string;
+	readonly font: string;
+	readonly x: number;
+	readonly y: number;
+}
+
+/* What a decoration paints: a target's box (for the halo) and its glyph (to recolor the notehead),
+ * the glyph being null when there is none (a measure, a rest). The decoration seam operates on
+ * this rather than bare Bounded so it can stamp the actual notehead glyph. */
+export interface Decoratable extends Bounded {
+	readonly glyph: NoteGlyph | null;
+}
+
+/* A reversible on/off effect carrying an optional value (color string, etc.). `off()` is the
+ * whole undo — these are view state, not document edits, so there is no history. */
+export interface Toggle<T = void> {
+	on(value: T): void;
+	off(): void;
+	readonly active: boolean;
+}
+
+/*
+ * The coordinate authority: converts between score space (where rects live) and client/page
+ * space (where pointer events and DOM popups live). The stage implements it for real; tests
+ * inject a fake. The target wrappers are its first consumers, so the interface lives here.
+ */
+export interface Viewport {
+	clientRectOf(rect: Rect): DOMRect;
+	toScoreSpace(clientX: number, clientY: number): { x: number; y: number };
+}
+
+export type DecorationKind = 'color' | 'halo';
+
+/*
+ * The decoration seam. A target's color/halo toggles delegate here rather than drawing
+ * themselves, so the drawing surface stays out of the model. Production: Decorations (owns the
+ * overlay layer, repaints from the active set). Tests: a FakeDecorator that records state.
+ */
+export interface Decorator {
+	setColor(target: Decoratable, color: string | null): void;
+	setHalo(target: Decoratable, on: boolean): void;
+	isColored(target: Decoratable): boolean;
+	isHaloed(target: Decoratable): boolean;
+}
+
+/*
+ * Resolves an mdom note to the wrapper built for it. The targets reference one another (a note
+ * to its chordmates, a note to its tab fret), which would be circular at construction; instead
+ * each holds a lookup and resolves on demand, once the builder has registered every wrapper. A
+ * Map<MNote, …> is the production implementer; tests pass their own.
+ */
+export interface NoteLookup {
+	get(mnote: MNote): Note | undefined;
+}
+export interface TabLookup {
+	get(mnote: MNote): TabPosition | undefined;
+}
+
+/* The color decoration as an on/off toggle, delegating to the Decorator. */
+class ColorToggle implements Toggle<string> {
+	constructor(
+		private readonly target: Decoratable,
+		private readonly decorator: Decorator,
+	) {}
+	on(color: string): void {
+		this.decorator.setColor(this.target, color);
+	}
+	off(): void {
+		this.decorator.setColor(this.target, null);
+	}
+	get active(): boolean {
+		return this.decorator.isColored(this.target);
+	}
+}
+
+/* The halo decoration as an on/off toggle, delegating to the Decorator. */
+class HaloToggle implements Toggle {
+	constructor(
+		private readonly target: Decoratable,
+		private readonly decorator: Decorator,
+	) {}
+	on(): void {
+		this.decorator.setHalo(this.target, true);
+	}
+	off(): void {
+		this.decorator.setHalo(this.target, false);
+	}
+	get active(): boolean {
+		return this.decorator.isHaloed(this.target);
+	}
+}
+
+/* Shared base for every target: holds the score-space rect and maps it to the page on demand.
+ * Decoratable with no glyph by default; Note overrides glyph with its notehead stamp. */
+abstract class BoundedTarget implements Decoratable {
+	constructor(
+		readonly rect: Rect,
+		protected readonly viewport: Viewport,
+	) {}
+	get glyph(): NoteGlyph | null {
+		return null;
+	}
+	getBoundingClientRect(): DOMRect {
+		return this.viewport.clientRectOf(this.rect);
+	}
+}
+
+/* MusicXML <pitch> -> vexflow key string, e.g. {step:'B', alter:-1, octave:3} -> "Bb/3". */
+function pitchToKey(p: {
+	step: string;
+	octave: number;
+	alter: number;
+}): string {
+	const n = Math.round(p.alter);
+	const accidental = n > 0 ? '#'.repeat(n) : n < 0 ? 'b'.repeat(-n) : '';
+	return `${p.step}${accidental}/${p.octave}`;
+}
+
+/* The dependencies a Note needs. Cross-links resolve through the lookups (see NoteLookup), so
+ * construction stays single-phase despite the mutual references. mnote is private — never exposed. */
+export interface NoteDeps {
+	mnote: MNote;
+	rect: Rect;
+	viewport: Viewport;
+	decorator: Decorator;
+	measure: Measure;
+	/* Every mdom note in this note's chord, including itself (a solo note is a 1-member chord). */
+	chord: MNote[];
+	/* Resolves chord members to their Notes, and this note's mnote to its tab fret rendering. */
+	notes: NoteLookup;
+	tabs: TabLookup;
+	/* The engraved notehead glyph, for recoloring; null for a rest (no notehead). */
+	glyph: NoteGlyph | null;
+}
+
+/* A single musical note (one notehead). The unit of selection, playback, and editing. */
+export class Note extends BoundedTarget {
+	readonly type = 'note';
+	readonly color: Toggle<string>;
+	readonly halo: Toggle;
+
+	constructor(private readonly deps: NoteDeps) {
+		super(deps.rect, deps.viewport);
+		this.color = new ColorToggle(this, deps.decorator);
+		this.halo = new HaloToggle(this, deps.decorator);
+	}
+
+	/* The engraved notehead glyph (for recoloring), or null for a rest. */
+	override get glyph(): NoteGlyph | null {
+		return this.deps.glyph;
+	}
+
+	/* The sounding pitch as a vexflow key ("E/4"), or null for a rest. */
+	getPitch(): string | null {
+		const pitch = this.deps.mnote.pitch;
+		return pitch ? pitchToKey(pitch) : null;
+	}
+
+	/* Duration in quarter-note beats; 0 for a grace note (which steals time — see isGrace). */
+	getBeats(): number {
+		return this.deps.mnote.beats ?? 0;
+	}
+
+	isGrace(): boolean {
+		return this.deps.mnote.isGrace;
+	}
+
+	/* True when this note is part of a chord of two or more notes (the lead counts too). */
+	isChordMember(): boolean {
+		return this.deps.chord.length > 1;
+	}
+
+	getChordSiblings(opts: { includeSelf: boolean }): Note[] {
+		const all: Note[] = [];
+		for (const mnote of this.deps.chord) {
+			const note = this.deps.notes.get(mnote);
+			if (note) {
+				all.push(note);
+			}
+		}
+		return opts.includeSelf ? all : all.filter((n) => n !== this);
+	}
+
+	getMeasure(): Measure {
+		return this.deps.measure;
+	}
+
+	getTabPosition(): TabPosition | null {
+		return this.deps.tabs.get(this.deps.mnote) ?? null;
+	}
+}
+
+/* A measure's box — the background target, hit when a pointer lands on staff space (not a note). */
+export class Measure extends BoundedTarget {
+	readonly type = 'measure';
+}
+
+/* A fret number on a tab string. The same note can render as both a Note (notehead) and a
+ * TabPosition (fret); they cross-reference via Note.getTabPosition() / TabPosition.getNote(). */
+export class TabPosition extends BoundedTarget {
+	readonly type = 'tab-position';
+
+	constructor(
+		rect: Rect,
+		viewport: Viewport,
+		private readonly opts: { string: number; fret: number; note: Note },
+	) {
+		super(rect, viewport);
+	}
+
+	getString(): number {
+		return this.opts.string;
+	}
+
+	getFret(): number {
+		return this.opts.fret;
+	}
+
+	getNote(): Note {
+		return this.opts.note;
+	}
+}
+
+export type PointerTarget = Note | Measure | TabPosition;
diff --git a/tests/integration/__screenshots__/decoration_color.png b/tests/integration/__screenshots__/decoration_color.png
new file mode 100644
index 000000000..8d65eb08d
Binary files /dev/null and b/tests/integration/__screenshots__/decoration_color.png differ
diff --git a/tests/integration/__screenshots__/decoration_halo.png b/tests/integration/__screenshots__/decoration_halo.png
new file mode 100644
index 000000000..248ebc0a4
Binary files /dev/null and b/tests/integration/__screenshots__/decoration_halo.png differ
diff --git a/tests/integration/decorations.test.ts b/tests/integration/decorations.test.ts
new file mode 100644
index 000000000..77b47a6c9
--- /dev/null
+++ b/tests/integration/decorations.test.ts
@@ -0,0 +1,72 @@
+import { expect, test } from 'bun:test';
+import type { Note } from '../../src';
+import { TEST_URL, testBrowser } from '../testing/setup';
+
+// Decorations end to end, the way a caller actually reaches them: render, hover to hit-test the
+// notes, toggle a decoration, and screenshot the composite (base engraving + the decoration
+// overlay). The drawing logic itself is unit-tested in src/decorations.test.ts; this proves it
+// lands on the score, aligned. Uses the run's shared browser/server (see setup.ts).
+
+async function decorate(mode: 'color' | 'halo'): Promise<Buffer> {
+	const browser = await testBrowser();
+	const page = await browser.newPage({ viewport: { width: 900, height: 400 } });
+	try {
+		await page.goto(TEST_URL);
+		const count = await page.evaluate(async (mode) => {
+			const container = document.getElementById('screenshot');
+			if (!(container instanceof HTMLDivElement)) {
+				throw new Error('container not found');
+			}
+			const xml = await (await fetch('/data/note.musicxml')).text();
+			const score = await window.render(xml, container, {});
+			const canvas = container.querySelector('canvas');
+			if (!canvas) {
+				throw new Error('canvas not found');
+			}
+
+			// Hover the whole canvas to collect every note under the pointer (deduped by identity).
+			const notes = new Set<Note>();
+			score.addEventListener('pointermove', (e) => {
+				if (e.target?.type === 'note') {
+					notes.add(e.target);
+				}
+			});
+			const rect = canvas.getBoundingClientRect();
+			for (let dy = 2; dy < rect.height; dy += 4) {
+				for (let dx = 2; dx < rect.width; dx += 4) {
+					canvas.dispatchEvent(
+						new PointerEvent('pointermove', {
+							clientX: rect.left + dx,
+							clientY: rect.top + dy,
+							bubbles: true,
+						}),
+					);
+				}
+			}
+
+			for (const note of notes) {
+				if (mode === 'color') {
+					note.color.on('#2962ff');
+				} else {
+					note.halo.on();
+				}
+			}
+			return notes.size;
+		}, mode);
+
+		if (count === 0) {
+			throw new Error('no notes found to decorate');
+		}
+		return await page.locator('#screenshot').screenshot();
+	} finally {
+		await page.close();
+	}
+}
+
+test('a colored note', async () => {
+	expect(await decorate('color')).toMatchScreenshot('decoration_color.png');
+}, 30_000);
+
+test('a haloed note', async () => {
+	expect(await decorate('halo')).toMatchScreenshot('decoration_halo.png');
+}, 30_000);
diff --git a/tests/integration/events.test.ts b/tests/integration/events.test.ts
new file mode 100644
index 000000000..7eecbb321
--- /dev/null
+++ b/tests/integration/events.test.ts
@@ -0,0 +1,62 @@
+import { expect, test } from 'bun:test';
+import { TEST_URL, testBrowser } from '../testing/setup';
+
+// The unit tests cover the wiring with fakes; this proves the real chain end to end — a DOM
+// pointer event on the managed canvas bubbles to the Score, gets mapped to score space through
+// the live Stage transform, and hit-tests against the index built from real geometry. Uses the
+// run's shared browser/server (see setup.ts).
+test('a real pointer event maps to score space and hit-tests a target', async () => {
+	const browser = await testBrowser();
+	const page = await browser.newPage({ viewport: { width: 900, height: 700 } });
+	try {
+		await page.goto(TEST_URL);
+		const result = await page.evaluate(async () => {
+			const container = document.getElementById('screenshot');
+			if (!(container instanceof HTMLDivElement)) {
+				throw new Error('container not found');
+			}
+			const xml = await (
+				await fetch('/data/structure_single_stave.musicxml')
+			).text();
+			const score = await window.render(xml, container, {});
+			const canvas = container.querySelector('canvas');
+			if (!canvas) {
+				throw new Error('canvas not found');
+			}
+
+			const types = new Set<string>();
+			const points: Array<{ x: number; y: number }> = [];
+			score.addEventListener('pointerdown', (e) => {
+				if (e.target) {
+					types.add(e.target.type);
+				}
+				points.push({ x: e.point.x, y: e.point.y });
+			});
+
+			// Scan down the vertical center line so the stave is crossed wherever the crop
+			// places it — robust to the exact engraved height.
+			const rect = canvas.getBoundingClientRect();
+			const cx = rect.left + rect.width / 2;
+			for (let dy = 4; dy < rect.height; dy += 4) {
+				canvas.dispatchEvent(
+					new PointerEvent('pointerdown', {
+						clientX: cx,
+						clientY: rect.top + dy,
+						bubbles: true,
+					}),
+				);
+			}
+			return { types: [...types], points, width: rect.width };
+		});
+
+		// The event reached the listener with its point mapped into score space (the unscaled
+		// harness canvas means client x == score x, offset by the canvas origin).
+		expect(result.points.length).toBeGreaterThan(0);
+		expect(result.points[0]?.x).toBeCloseTo(result.width / 2, 0);
+		expect(result.points[0]?.y).toBeCloseTo(4, 0);
+		// The measure box, built from real geometry, was hittable.
+		expect(result.types).toContain('measure');
+	} finally {
+		await page.close();
+	}
+}, 30_000);
diff --git a/tests/integration/layers.test.ts b/tests/integration/layers.test.ts
new file mode 100644
index 000000000..9c13d44d6
--- /dev/null
+++ b/tests/integration/layers.test.ts
@@ -0,0 +1,76 @@
+import { expect, test } from 'bun:test';
+import { TEST_URL, testBrowser } from '../testing/setup';
+
+// Custom layers, end to end in a real browser: a content layer spans the engraved score (score
+// space), a viewport layer spans the visible box (client space) and is re-fit when the container
+// resizes. Reads layer.ctx.canvas to check sizing — a test-only peek; the public Layer hides the
+// canvas. Uses the run's shared browser/server (see setup.ts).
+test('content layers span the score, viewport layers span the visible box and re-fit on resize', async () => {
+	const browser = await testBrowser();
+	const page = await browser.newPage({ viewport: { width: 900, height: 700 } });
+	try {
+		await page.goto(TEST_URL);
+		const result = await page.evaluate(async () => {
+			const container = document.getElementById('screenshot');
+			if (!(container instanceof HTMLDivElement)) {
+				throw new Error('container not found');
+			}
+			const xml = await (
+				await fetch('/data/structure_single_stave.musicxml')
+			).text();
+			const score = await window.render(xml, container, {});
+			const base = container.querySelector('canvas');
+			if (!base) {
+				throw new Error('base canvas not found');
+			}
+
+			const content = score.addLayer('content');
+			const viewport = score.addLayer('viewport');
+			const before = {
+				contentW: parseFloat(content.ctx.canvas.style.width),
+				baseW: parseFloat(base.style.width),
+				viewportW: parseFloat(viewport.ctx.canvas.style.width),
+				clientW: container.clientWidth,
+			};
+
+			// Shrink the container and wait for the resize to propagate to the viewport layer.
+			let resizes = 0;
+			const settled = new Promise<void>((resolve) => {
+				score.addEventListener('resize', () => {
+					resizes++;
+					if (
+						parseFloat(viewport.ctx.canvas.style.width) ===
+							container.clientWidth &&
+						container.clientWidth < before.clientW
+					) {
+						resolve();
+					}
+				});
+			});
+			container.style.width = '300px';
+			await Promise.race([
+				settled,
+				new Promise<void>((r) => setTimeout(r, 3000)),
+			]);
+
+			return {
+				before,
+				after: {
+					viewportW: parseFloat(viewport.ctx.canvas.style.width),
+					clientW: container.clientWidth,
+					resizes,
+				},
+			};
+		});
+
+		// Content layer matches the base canvas (score space); viewport matches the visible box.
+		expect(result.before.contentW).toBeCloseTo(result.before.baseW, 0);
+		expect(result.before.viewportW).toBeCloseTo(result.before.clientW, 0);
+		// Shrinking the container fired a resize that re-fit the viewport layer to the new box.
+		expect(result.after.clientW).toBeLessThan(result.before.clientW);
+		expect(result.after.resizes).toBeGreaterThan(0);
+		expect(result.after.viewportW).toBeCloseTo(result.after.clientW, 0);
+	} finally {
+		await page.close();
+	}
+}, 30_000);
diff --git a/tests/testing/harness.ts b/tests/testing/harness.ts
index 21df8ffed..12c63cbd7 100644
--- a/tests/testing/harness.ts
+++ b/tests/testing/harness.ts
@@ -1,28 +1,11 @@
-import { afterAll, beforeAll } from 'bun:test';
-import { type Browser, chromium } from 'playwright';
 import type { Config } from '../../src';
 import { DEFAULT_WIDTH } from '../../src/constants';
-import { serve } from './serve';
-
-const PORT = 3100;
-
-let browser: Browser;
-let server: ReturnType<typeof serve>;
-
-// Importing this module registers the hooks against the importing test file.
-beforeAll(async () => {
-	server = serve(PORT);
-	browser = await chromium.launch();
-});
-
-afterAll(async () => {
-	await browser?.close();
-	server?.stop(true);
-});
+import { TEST_URL, testBrowser } from './setup';
 
 // A fixture is laid out to its reference width (8.5in unless the test overrides it);
 // the result scales to any container at runtime, so a static viewport exercises the
-// layout deterministically.
+// layout deterministically. The browser and page server are shared across the whole run
+// (see setup.ts) — launching a second Chromium per file is flaky in Docker.
 
 /** Render a corpus file in the browser and return its screenshot PNG. */
 export async function render(
@@ -32,22 +15,23 @@ export async function render(
 	const width =
 		(config.layout?.type === 'standard' ? config.layout.width : undefined) ??
 		DEFAULT_WIDTH;
+	const browser = await testBrowser();
 	const page = await browser.newPage({
 		viewport: { width: width + 64, height: 600 },
 	});
 	try {
-		await page.goto(`http://localhost:${PORT}/`);
+		await page.goto(TEST_URL);
 		await page.evaluate(
 			async ({ file, config }) => {
 				const res = await fetch(`/data/${file}`);
 				const input = file.endsWith('.mxl')
 					? await res.blob()
 					: await res.text();
-				const canvas = document.getElementById('vexml');
-				if (!(canvas instanceof HTMLCanvasElement)) {
-					throw new Error('canvas not found');
+				const container = document.getElementById('screenshot');
+				if (!(container instanceof HTMLDivElement)) {
+					throw new Error('container not found');
 				}
-				await window.render(input, canvas, config);
+				await window.render(input, container, config);
 			},
 			{ file, config },
 		);
diff --git a/tests/testing/index.html b/tests/testing/index.html
index 3d785f318..a0a9f1390 100644
--- a/tests/testing/index.html
+++ b/tests/testing/index.html
@@ -13,7 +13,7 @@
         </style>
     </head>
     <body>
-        <div id="screenshot"><canvas id="vexml" /></div>
+        <div id="screenshot"></div>
         <script type="module" src="./entry.ts"></script>
     </body>
 </html>
diff --git a/tests/testing/setup.ts b/tests/testing/setup.ts
index cb226d9b7..9bb38854c 100644
--- a/tests/testing/setup.ts
+++ b/tests/testing/setup.ts
@@ -1,4 +1,4 @@
-import { afterAll, expect } from 'bun:test';
+import { afterAll, beforeAll, expect } from 'bun:test';
 import {
 	existsSync,
 	mkdirSync,
@@ -11,7 +11,9 @@ import * as path from 'node:path';
 import { createCanvas, createImageData } from 'canvas';
 import chalk from 'chalk';
 import pixelmatch from 'pixelmatch';
+import { type Browser, chromium } from 'playwright';
 import { PNG } from 'pngjs';
+import { serve } from './serve';
 
 // Guard: tests must go through `vex test`, which renders in the pinned Docker
 // image. Bare `bun test` on the host compares against the committed Docker
@@ -26,6 +28,38 @@ if (process.env.I_AM_RUNNING_TESTS_USING_VEX_TEST !== '1') {
 	process.exit(1);
 }
 
+// One browser and one page server for the whole `bun test` run. Launching a second Chromium in
+// the same run is flaky in Docker — its teardown hangs past the hook timeout — so every browser
+// test (the screenshot harness and the events smoke test) reuses these. Preloaded, so the
+// lifecycle scopes to the run, not one file. Eager (beforeAll) to keep the launch out of the
+// first test's own timeout; lazy getters so a unit-only run still pays for them only if used.
+const TEST_PORT = 3100;
+export const TEST_URL = `http://localhost:${TEST_PORT}/`;
+let sharedServer: ReturnType<typeof serve> | null = null;
+let sharedBrowser: Promise<Browser> | null = null;
+
+export function testServer(): ReturnType<typeof serve> {
+	sharedServer ??= serve(TEST_PORT);
+	return sharedServer;
+}
+
+export function testBrowser(): Promise<Browser> {
+	testServer();
+	sharedBrowser ??= chromium.launch();
+	return sharedBrowser;
+}
+
+beforeAll(async () => {
+	await testBrowser();
+});
+
+afterAll(async () => {
+	if (sharedBrowser) {
+		await (await sharedBrowser).close();
+	}
+	sharedServer?.stop(true);
+});
+
 // [old][diff][new] stacked vertically, each captioned, returned as a PNG buffer.
 function composite(
 	expected: PNG,