Skip to content

feat: expose first-fret text and location in mx::api - #430

Merged
webern merged 1 commit into
webern:mainfrom
rpatters1:claude/first-fret-display-attributes-14fb08
Aug 26, 2026
Merged

feat: expose first-fret text and location in mx::api#430
webern merged 1 commit into
webern:mainfrom
rpatters1:claude/first-fret-display-attributes-14fb08

Conversation

@rpatters1

Copy link
Copy Markdown
Contributor

Human Summary

Round-trip the <first-fret> text and location attributes through mx::api.

Summary

MusicXML's <first-fret> carries two display attributes beside its value: text, the label to
print (Finale writes 4fr. for a frame starting at the fourth fret), and location, whether that
label appears to the left or the right of the grid. mx::core has modeled both since it was
generated, but mx::api exposed only firstFret and isFirstFretSpecified, so the writer emitted
a bare <first-fret>4</first-fret> and a reading application had to invent the label and its side.

FrameData gains firstFretText, an optional string, and firstFretLocation, a new
FirstFretLocation enum whose unspecified default writes no attribute. The two are independent:
MusicXML permits either alone, and a frame that wants only the fret number keeps working untouched.

The value and its is...Specified flag are left as they are rather than folded into a sub-struct,
per the AGENTS.md rule that the legacy sentinel fields are migrated deliberately and separately.

Non-breaking: two new fields on FrameData, both absent by default.

Testing

  • New harmonyFrameFirstFretRoundTrip covers both attributes through XML and back;
    harmonyFrameFirstFretBareRoundTrip verifies a frame with neither still emits
    <first-fret>3</first-fret> and reads back as unspecified
  • make api-test (6367 assertions in 582 test cases)
  • make api-roundtrip (405 of 405 pinned)
  • synthetic/first-fret.3.0.xml unlocked and added to the round-trip baseline; confirmed it
    fails on the parent commit with attribute count mismatch at .../frame/first-fret and passes with
    this change

References

## Human Summary

Round-trip the `<first-fret>` text and location attributes through
`mx::api`.

## Summary

MusicXML's `<first-fret>` carries two display attributes beside its
value: `text`, the label to print (Finale writes `4fr.` for a frame
starting at the fourth fret), and `location`, whether that label appears
to the left or the right of the grid. `mx::core` has modeled both since
it was generated, but `mx::api` exposed only `firstFret` and
`isFirstFretSpecified`, so the writer emitted a bare
`<first-fret>4</first-fret>` and a reading application had to invent the
label and its side.

`FrameData` gains `firstFretText`, an optional string, and
`firstFretLocation`, a new `FirstFretLocation` enum whose `unspecified`
default writes no attribute. The two are independent: MusicXML permits
either alone, and a frame that wants only the fret number keeps working
untouched.

The value and its `is...Specified` flag are left as they are rather than
folded into a sub-struct, per the AGENTS.md rule that the legacy
sentinel fields are migrated deliberately and separately (webern#249).

Non-breaking: two new fields on `FrameData`, both absent by default.

## Testing

- [x] New `harmonyFrameFirstFretRoundTrip` test covers both attributes
through XML and back; `harmonyFrameFirstFretBareRoundTrip` verifies a
frame with neither still emits `<first-fret>3</first-fret>` and reads
back as `unspecified`
- [x] `make api-test` (6367 assertions in 582 test cases)
- [x] `make api-roundtrip` (405 of 405 pinned)
- [x] `synthetic/first-fret.3.0.xml` unlocked and added to the
round-trip baseline; confirmed it fails on the parent commit with
`attribute count mismatch at .../frame/first-fret` and passes with this
change

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UbK99eFKnXpH5ki6ysZMdA

@webern webern left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good.

@webern
webern merged commit 0897aa8 into webern:main Aug 26, 2026
8 checks passed
@rpatters1
rpatters1 deleted the claude/first-fret-display-attributes-14fb08 branch August 26, 2026 20:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants