I make Pianory, a browser piano learning and practice app. AI helped draft this article; I checked the code and focused test results described below against the repository.

A compressed MusicXML (.mxl) file is a ZIP archive. Choosing the first .xml entry can silently load the wrong document if the archive has metadata or a decoy file before the score. The archive's declared root file is the stronger signal.

Pianory first lists the archive entries. If META-INF/container.xml exists, the extractor reads its rootfile tags, takes a full-path ending in .musicxml or .xml that actually exists in the archive, and uses the first matching declaration. Only when that does not yield a usable path does it fall back to the first MusicXML-named entry outside META-INF. If there is no candidate or the selected entry cannot be read, it throws an invalid-archive error. The extracted text then passes through the supported-score check.

The regression fixture makes the mistake concrete: it puts aaa-decoy.xml in the archive before scores/elise.musicxml, while container.xml declares scores/elise.musicxml. The test asserts that both the extractor and the file reader return the declared piano score, not the decoy. A separate fixture checks the fallback when no usable manifest path is present, and another checks rejection of an archive without a score.

I ran pnpm exec vitest run src/lib/music/musicxml-file.spec.ts: 16 focused tests passed. Those tests cover the archive shapes in the fixtures. They do not establish compatibility with every MXL producer. The broader design lesson is to let a format's manifest choose the entry, then test with an earlier file that looks plausible but is wrong.

Source: src/lib/music/musicxml-file.ts and src/lib/music/musicxml-file.spec.ts in the Pianory repository.